# QI Tech — Documentação completa

Documentação da QI Tech em texto corrido, para colar em um LLM.
Fonte: https://docs.qitech.com.br
1509 página(s).

Índice:
- Atualização uso de TAC (/documentation/1bb151c7-735f-4449-bd9a-4780be271da8)
- Troca com Troco SIAPE/EXÉRCITO (/documentation/6fabde14-8ce4-42ac-9f93-28246356e45d)
- Abertura de Conta em Duas Etapas (/documentation/account_request)
- Manual de Aditamento (/documentation/aditamento/manual_aditamento)
- Realizar agendamento de pagamento de boleto (/documentation/agendamentos/agendamento_boleto)
- Agendar transferência Pix (/documentation/agendamentos/agendamento_pix)
- Realizar transferência (/documentation/agendamentos/agendamento_ted)
- Cancelar agendamento (/documentation/agendamentos/cancelar_agendamento)
- Consulta de transações agendadas (/documentation/agendamentos/consulta_agendamentos)
- arranjos_e_adquirentes (/documentation/arranjos_e_adquirentes/)
- Criar uma renegociação (/documentation/arranjos_e_adquirentes/consulta_de_agenda)
- trava_de_domicilio_bancario (/documentation/arranjos_e_adquirentes/trava_de_domicilio_bancario)
- emissao_de_divida (/documentation/auxilio_brasil/emissao_de_divida)
- webhook_auxilio_brasil (/documentation/auxilio_brasil/webhook_auxilio_brasil)
- Confirmar Abertura de Conta de Pessoa Física (/documentation/baas/account/2fa_v2/abrir_conta_pf)
- Abertura de Conta de Pessoa Jurídica (/documentation/baas/account/2fa_v2/abrir_conta_pj)
- Confirmar Abertura de Conta de Pessoa Física (/documentation/baas/account/abrir_conta_pf)
- Confirmar Abertura de Conta de Pessoa Jurídica (/documentation/baas/account/abrir_conta_pj)
- Solicitar reserva de conta (/documentation/baas/account/account_draft_checking)
- Solicitar reserva de conta (/documentation/baas/account/d4bf7f96-69b0-424b-a9d6-0a1bc79629cd)
- Introdução (/documentation/baas/account/introducao)
- Solicitar Abertura de Conta de Pessoa Física (/documentation/baas/account/reservar_conta_pf)
- Abertura de Conta de Pessoa Jurídica (/documentation/baas/account/reservar_conta_pj)
- Webhooks de abertura de conta (/documentation/baas/account/webhooks)
- Catálogo de Erros - Banking-as-a-Service (/documentation/baas/catalogo_de_erros_baas)
- Cancelar agendamento em lote de pagamento (/documentation/baas/cobranca/2fa_v2/agendamento/cancelar_agendamento_em_lote_de_pagamento)
- Confirmar Agendamento de Boleto Bancário (/documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_de_boleto_bancario)
- Confirmação de Pagamento de Fatura de Recolhimento (/documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_de_fatura_de_recolhimento)
- Confirmar agendamento em lote de boleto bancário (/documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_em_lote_de_boleto_bancario)
- Confirmar agendamento em lote de fatura de recolhimento (/documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_em_lote_de_fatura_de_recolhimento)
- Consultar lote de agendamento de pagamento (/documentation/baas/cobranca/2fa_v2/agendamento/consultar_lote_de_agendamento_de_pagamento)
- Listar lotes de agendamento de pagamento (/documentation/baas/cobranca/2fa_v2/agendamento/listar_lotes_de_agendamento_de_pagamento)
- Reenviar Token Autenticação de Dois Fatores de Agendamento de Boleto Bancário (/documentation/baas/cobranca/2fa_v2/agendamento/reenviar_token_de_agendamento_boleto_bancario)
- Reenviar Token Autenticação de Dois Fatores de Agendamento de Fatura de Recolhimento (/documentation/baas/cobranca/2fa_v2/agendamento/reenviar_token_de_agendamento_de_fatura_de_recolhimento)
- Reenviar token de autenticação de dois fatores de agendamento em lote de boleto bancário (/documentation/baas/cobranca/2fa_v2/agendamento/reenviar_token_de_agendamento_em_lote_de_boleto_bancario)
- Reenviar token de autenticação de dois fatores de agendamento em lote de fatura de recolhimento (/documentation/baas/cobranca/2fa_v2/agendamento/reenviar_token_de_agendamento_em_lote_de_fatura_de_recolhimento)
- Solicitar Agendamento de Pagamento de Boleto Bancário com Autenticação de Dois Fatores (2FA) (/documentation/baas/cobranca/2fa_v2/agendamento/solicitar_agendamento_de_boleto_bancario)
- Solicitar Agendamento de Pagamento de Facutara de Recolhimento com Autenticação de Dois Fatores (2FA) (/documentation/baas/cobranca/2fa_v2/agendamento/solicitar_agendamento_de_pagamento_de_fatura_de_recolhimento)
- Solicitar agendamento em lote de boleto bancário com autenticação de dois fatores (2FA) (/documentation/baas/cobranca/2fa_v2/agendamento/solicitar_agendamento_em_lote_de_boleto_bancario)
- Solicitar agendamento em lote de fatura de recolhimento com autenticação de dois fatores (2FA) (/documentation/baas/cobranca/2fa_v2/agendamento/solicitar_agendamento_em_lote_de_fatura_de_recolhimento)
- Confirmação de lote de pagamento de boleto bancário (/documentation/baas/cobranca/2fa_v2/confirmacao_de_lote_de_boleto_bancario)
- Confirmação de lote de pagamento de fatura de recolhimento (convênio/tributo) (/documentation/baas/cobranca/2fa_v2/confirmacao_de_lote_de_fatura_de_recolhimento)
- Confirmação de Pagamento de Boleto Bancário (/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_boleto_bancario)
- Confirmação de Pagamento de Fatura de Recolhimento (/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_fatura_de_recolhimento)
- Introdução a Autenticação de Dois Fatores (/documentation/baas/cobranca/2fa_v2/introducao_ao_pagamento_2fa)
- Solicitação de pagamento de Boleto Bancário com Autenticação de Dois Fatores (/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_boleto_bancario)
- Solicitação de Pagamento de Fatura de Recolhimento com Autenticação de Dois Fatores (/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_fatura_de_recolhimento)
- Reenviar Token Autenticação de Dois Fatores de Pagamentos de Boleto Bancário (/documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_boleto_bancario)
- Reenviar Token de Autenticação de Dois Fatores para Pagamentos de Fatura de Recolhimento (/documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_fatura_de_recolhimento)
- Reenviar token de confirmação de lote de pagamento de boleto bancário (/documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_lote_de_boleto_bancario)
- Reenviar token de confirmação de lote de pagamento de fatura de recolhimento (convênio/tributo) (/documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_lote_de_fatura_de_recolhimento)
- Solicitar pagamento em lote de boleto bancário com autenticação de dois fatores (/documentation/baas/cobranca/2fa_v2/solicitar_pagamento_lote_de_boleto_bancario_com_confirmacao_de_lote)
- Solicitar pagamento em lote de boleto bancário com autenticação de dois fatores (/documentation/baas/cobranca/2fa_v2/solicitar_pagamento_lote_de_boleto_bancario_sem_confirmacao_de_lote)
- Solicitar pagamento em lote de fatura de recolhimento (convênio/tributo) com autenticação de dois fatores (/documentation/baas/cobranca/2fa_v2/solicitar_pagamento_lote_de_fatura_de_recolhimento_com_confirmacao_de_lote)
- Solicitar pagamento em lote de fatura de recolhimento (convênio/tributo) com autenticação de dois fatores (/documentation/baas/cobranca/2fa_v2/solicitar_pagamento_lote_de_fatura_de_recolhimento_sem_confirmacao_de_lote)
- Validação de token de lote de pagamento de boleto bancário (/documentation/baas/cobranca/2fa_v2/validacao_de_token_de_lote_de_boleto_bancario)
- Validação de token de lote de pagamento de fatura de recolhimento (convênio/tributo) (/documentation/baas/cobranca/2fa_v2/validacao_de_token_de_lote_de_fatura_de_recolhimento)
- Agendar Pagamento de Boleto Bancário (/documentation/baas/cobranca/agendamento/agendar_pagamento_de_boleto_bancario)
- Agendar Pagamento de Fatura de Recolhimento (convênio/tributo) (/documentation/baas/cobranca/agendamento/agendar_pagamento_de_fatura_de_recolhimento)
- Cancelar Agendamento (/documentation/baas/cobranca/agendamento/cancelar_agendamento)
- Consultar Agendamento (/documentation/baas/cobranca/agendamento/consultar_agendamento)
- Listar Agendamentos (/documentation/baas/cobranca/agendamento/listar_agendamentos)
- Solicitar agendamento em lote de boleto bancário (/documentation/baas/cobranca/agendamento/solicitar_agendamento_em_lote_de_boleto_bancario)
- Solicitar agendamento em lote de fatura de recolhimento (/documentation/baas/cobranca/agendamento/solicitar_agendamento_em_lote_de_fatura_de_recolhimento)
- Confirmação de lote de pagamento de boleto bancário (/documentation/baas/cobranca/confirmacao_de_lote_de_boleto_bancario)
- Confirmação de lote de pagamento de fatura de recolhimento (convênio/tributo) (/documentation/baas/cobranca/confirmacao_de_lote_de_fatura_de_recolhimento)
- Consulta de Boleto Bancário (/documentation/baas/cobranca/consultar_boleto_bancario)
- Consulta de Fatura de Recolhimento (/documentation/baas/cobranca/consultar_fatura_de_recolhimento)
- Consultar lote de pagamento (/documentation/baas/cobranca/consultar_lote_de_pagamento)
- Listar lotes de pagamento (/documentation/baas/cobranca/listar_lotes_de_pagamento)
- Listar Pagamentos (/documentation/baas/cobranca/listar_pagamentos)
- Realizar Pagamento de Boleto Bancário (/documentation/baas/cobranca/pagar_boleto_bancario)
- Realizar Pagamento de Fatura de Recolhimento (convênio/tributo) (/documentation/baas/cobranca/pagar_fatura_de_recolhimento)
- Simulação de cenários (/documentation/baas/cobranca/simulacao_de_cenarios)
- Solicitar Pagamento em Lote de Boleto Bancário (/documentation/baas/cobranca/solicitar_pagamento_lote_de_boleto_bancario_com_confirmacao_de_lote)
- Solicitar Pagamento em Lote de Boleto Bancário (/documentation/baas/cobranca/solicitar_pagamento_lote_de_boleto_bancario_sem_confirmacao_de_lote)
- Solicitar Pagamento em Lote de Fatura de Recolhimento (convênio/tributo) (/documentation/baas/cobranca/solicitar_pagamento_lote_de_fatura_de_recolhimento_com_confirmacao_de_lote)
- Solicitar Pagamento em Lote de Fatura de Recolhimento (convênio/tributo) (/documentation/baas/cobranca/solicitar_pagamento_lote_de_fatura_de_recolhimento_sem_confirmacao_de_lote)
- Webhooks (/documentation/baas/cobranca/webhooks)
- Consultar dispositivo (/documentation/baas/dispositivo/consultar_dispositivo)
- Aprovar criação de dispositivo (/documentation/baas/dispositivo/create/aprovar_cadastro_dispositivo)
- Solicitar Criação de Dispositivo (/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo)
- Solicitar reenvio de token (/documentation/baas/dispositivo/create/solicitacao_reenvio_token)
- Desativar dispositivo (/documentation/baas/dispositivo/delete/desativar_dispositivo)
- Introdução (/documentation/baas/dispositivo/introducao)
- Confirmar Abertura de Conta de Pessoa Física (/documentation/baas/escrow/abrir_conta_pf)
- Confirmar Abertura de Conta de Pessoa Jurídica (/documentation/baas/escrow/abrir_conta_pj)
- Abertura de Conta de Pessoa Física (/documentation/baas/escrow/reservar_conta_pf)
- Abertura de Conta de Pessoa Jurídica (/documentation/baas/escrow/reservar_conta_pj)
- Webhooks de abertura de conta (/documentation/baas/escrow/webhooks)
- baas_consulta_de_instituicoes_financeiras (/documentation/baas/lista_de_instituicoes_financeiras/baas_consulta_de_instituicoes_financeiras)
- baas_configuracao_de_notificacao (/documentation/baas/notificacoes/baas_configuracao_de_notificacao)
- baas_configuracao_template (/documentation/baas/notificacoes/baas_configuracao_template)
- baas_introducao (/documentation/baas/notificacoes/baas_introducao)
- baas_reenvio_de_notificacoes (/documentation/baas/notificacoes/baas_reenvio_de_notificacoes)
- baas_template (/documentation/baas/notificacoes/baas_template)
- baas_tipos_de_evento (/documentation/baas/notificacoes/baas_tipos_de_evento)
- Upload de arquivo remessa (CNAB) (/documentation/baas/pagamento_em_lote/envio_de_remessa)
- Introdução a Transação em Lote CNAB240 (/documentation/baas/pagamento_em_lote/introducao)
- Consultar Dados de um Lote de Pagamentos por conta (/documentation/baas/pix_automatico/conciliacao/consultar_lote_por_conta)
- Consultar Lotes de Pagamentos por Requester (/documentation/baas/pix_automatico/conciliacao/consultar_lote_requester)
- Listagem de Pagamentos de uma Conta (/documentation/baas/pix_automatico/conciliacao/listar_payment_orders)
- Webhook de Criação de Lote de Conciliação de Ordens de Pagamento (/documentation/baas/pix_automatico/conciliacao/webhooks)
- FAQ - Pix Automático (/documentation/baas/pix_automatico/faq)
- Introdução ao Pix Automático (/documentation/baas/pix_automatico/introducao)
- Aceitar recorrência de pagamento (/documentation/baas/pix_automatico/movimentacoes/aceitar_recorrencia)
- Cancelar a recorrência (/documentation/baas/pix_automatico/movimentacoes/cancelar_recorrencia)
- Consultar Recorrência (/documentation/baas/pix_automatico/movimentacoes/consultar_recorrencia)
- Criar recorrência de pagamento (/documentation/baas/pix_automatico/movimentacoes/criar_recorrencia)
- Listagem de Recorrências (/documentation/baas/pix_automatico/movimentacoes/listar_recorrencias)
- Simulação de cenários (/documentation/baas/pix_automatico/movimentacoes/simulacao)
- Webhooks (/documentation/baas/pix_automatico/movimentacoes/webhooks)
- Atualizar Valor da Ordem de Pagamento (/documentation/baas/pix_automatico/pagamentos/atualizar_payment_order)
- Cancelar uma Ordem de Pagamento (/documentation/baas/pix_automatico/pagamentos/cancelar_payment_order)
- Consultar Payment Order (/documentation/baas/pix_automatico/pagamentos/consultar_payment_order)
- Listar Payment Orders por Conta (/documentation/baas/pix_automatico/pagamentos/listar_account_payment_orders)
- Decodificar QR Code para Pix Automático (/documentation/baas/pix_automatico/qr_code/decodificar_qr_code)
- Cancelar recorrência de pagamento (/documentation/baas/pix_automatico/recebedor/cancelar_recorrencia)
- Consultar dados de uma recorrência por outgoing_recurrence_key (/documentation/baas/pix_automatico/recebedor/consultar_recorrencia)
- Consulta de Dados de Recorrência Automática Pix pelo QRCode (/documentation/baas/pix_automatico/recebedor/consultar_recorrencia_receiver)
- Conciliação e Liquidação de Pagamentos (/documentation/baas/pix_automatico/recebedor/introducao)
- Criar uma Recorrência (Jornada 4) (/documentation/baas/pix_automatico/recebedor/journey_four)
- Criar uma Recorrência (Jornada 1) (/documentation/baas/pix_automatico/recebedor/journey_one)
- Criar uma Recorrência (Jornada 3) (/documentation/baas/pix_automatico/recebedor/journey_three)
- Criar uma Recorrência (Jornada 2) (/documentation/baas/pix_automatico/recebedor/journey_two)
- Listagem de Recorrências de um Requester (/documentation/baas/pix_automatico/recebedor/listar_recorrencias_de_um_requester)
- Listagem de Recorrências de uma Conta (/documentation/baas/pix_automatico/recebedor/listar_recorrencias_de_uma_conta)
- Simulação de cenários (/documentation/baas/pix_automatico/recebedor/simulacao)
- Webhooks Pix Automático (/documentation/baas/pix_automatico/recebedor/webhooks)
- Aprovar Transação com Autenticação de Dois Fatores (/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa)
- Introdução a Autenticação de Dois Fatores (/documentation/baas/pix/2fa_v2/introducao_a_transacao_pix_2fa)
- Solicitar a devolução de um Pix recebido (/documentation/baas/pix/2fa_v2/solicitacao_de_devolucao_pix)
- Solicitar reenvio de token para uma transação (/documentation/baas/pix/2fa_v2/solicitacao_de_reenvio_de_token)
- Solicitar Transação com Autenticação de Dois Fatores (/documentation/baas/pix/2fa_v2/solicitacao_de_transacao_pix_2fa)
- Aprovar Agendamento de Transação Pix com Autenticação de Dois Fatores (/documentation/baas/pix/agendamento/aprovacao_de_agendamento_2fa)
- Aprovar Agendamento em Lote de Transação Pix com Autenticação de Dois Fatores (/documentation/baas/pix/agendamento/batch/aprovacao_de_agendamento_em_lote_2fa)
- Cancelar Agendamento de Transação Pix em Lote (/documentation/baas/pix/agendamento/batch/cancelamento_de_agendamento_em_lote)
- Listar Agendamentos de um Lote de Agendamento (/documentation/baas/pix/agendamento/batch/consulta_de_agendamentos_de_um_lote)
- Listar Lotes de Agendamento de uma conta (/documentation/baas/pix/agendamento/batch/consulta_de_agendamentos_em_lote_de_uma_conta)
- Solicitar Agendamento de Transação Pix em Lote (/documentation/baas/pix/agendamento/batch/solicitacao_de_agendamento_em_lote)
- Solicitar Agendamento de Transação Pix em Lote (/documentation/baas/pix/agendamento/batch/solicitacao_de_agendamento_em_lote_2fa)
- Solicitar reenvio de token para um agendamento em lote (/documentation/baas/pix/agendamento/batch/solicitacao_de_reenvio_de_token_para_agendamento_em_lote_2fa)
- Cancelar Agendamento de Transação Pix (/documentation/baas/pix/agendamento/cancelamento_de_agendamento)
- Consultar Agendamento de Transação Pix (/documentation/baas/pix/agendamento/consulta_de_agendamento)
- Consultar Agendamentos de Transação Pix de uma conta (/documentation/baas/pix/agendamento/consulta_de_agendamentos_de_uma_conta)
- Tabela de Erros para Pix Schedule (/documentation/baas/pix/agendamento/erros_de_agendamento)
- Introdução (/documentation/baas/pix/agendamento/introducao)
- Introdução a Autenticação de Dois Fatores (/documentation/baas/pix/agendamento/introducao_a_agendamento_2fa)
- Solicitar Agendamento de Transação Pix (/documentation/baas/pix/agendamento/solicitacao_de_agendamento)
- Solicitar Agendamento de Transação Pix com Autenticação de Dois Fatores (/documentation/baas/pix/agendamento/solicitacao_de_agendamento_2fa)
- Solicitar reenvio de token para um agendamento (/documentation/baas/pix/agendamento/solicitacao_de_reenvio_de_token_para_agendamento_2fa)
- Webhook de conclusão de Agendamento Pix (/documentation/baas/pix/agendamento/webhook_de_conclusao_de_agendamento)
- Aprovar Transação em Lote com Autenticação de Dois Fatores (/documentation/baas/pix/batch/aprovar_transacao_em_lote_pix_2fa)
- Introdução a Transação em Lote Pix (/documentation/baas/pix/batch/introducao_a_transacao_em_lote_pix)
- Listar Transações de um lote de uma conta (/documentation/baas/pix/batch/listar_transacoes_de_um_lote_de_transacoes_pix)
- Listar Transações em Lote de uma conta (/documentation/baas/pix/batch/listar_transacoes_em_lote_pix_de_uma_conta)
- Solicitar reenvio de token para uma Transação Pix em Lote (/documentation/baas/pix/batch/solicitacao_de_reenvio_de_token_para_lote)
- Realizar Transação Pix em Lote (/documentation/baas/pix/batch/solicitacao_de_transacao_em_lote_pix)
- Realizar Transação Pix em Lote com Autenticação de Dois Fatores (/documentation/baas/pix/batch/solicitacao_de_transacao_em_lote_pix_2fa)
- Consulta de Dados de Chave Pix no Banco Central (/documentation/baas/pix/consultar_chave_pix)
- Consultar Transferências (/documentation/baas/pix/consultar_transferencias)
- Tabela de Erros para Pix Transfer (/documentation/baas/pix/erros_de_pix)
- Listar Transferências de uma Conta (/documentation/baas/pix/listar_transferencias)
- Cancelar uma solicitação de limite Pix temporário (/documentation/baas/pix/pix_temporario/cancelamento_de_pix_temporario)
- Consultar solicitações de limite Pix temporário (/documentation/baas/pix/pix_temporario/consulta_de_pix_temporario)
- Consultar o uso do limite Pix temporário (/documentation/baas/pix/pix_temporario/consulta_de_uso_de_pix_temporario)
- Erros de Pix temporário (/documentation/baas/pix/pix_temporario/erros_de_pix_temporario)
- Introdução (/documentation/baas/pix/pix_temporario/introducao)
- Realizar transferência de Pix temporário (/documentation/baas/pix/pix_temporario/realizar_transferencia_pix_temporario)
- Solicitar um limite Pix temporário (/documentation/baas/pix/pix_temporario/solicitacao_de_pix_temporario)
- Realizar Transação Pix (/documentation/baas/pix/realizar_transferencia)
- Solicitar a devolução de um Pix recebido (/documentation/baas/pix/solicitar_devolucao)
- Webhooks (/documentation/baas/pix/webhooks)
- baas_configurando_webhooks (/documentation/baas/primeiros_passos/baas_configurando_webhooks)
- Configurar IP de Integração (/documentation/baas/primeiros_passos/baas_configurar_ip_de_integracao)
- baas_inicio (/documentation/baas/primeiros_passos/baas_inicio)
- baas_troca_de_chaves (/documentation/baas/primeiros_passos/baas_troca_de_chaves)
- baas_endpoints_de_teste (/documentation/baas/primeiros_passos/teste_de_autenticacao/baas_endpoints_de_teste)
- baas_possiveis_erros (/documentation/baas/primeiros_passos/teste_de_autenticacao/baas_possiveis_erros)
- baas_teste_de_autenticacao_completo (/documentation/baas/primeiros_passos/teste_de_autenticacao/baas_teste_de_autenticacao_completo)
- baas_teste_de_autenticacao_v2 (/documentation/baas/primeiros_passos/teste_de_autenticacao/baas_teste_de_autenticacao_v2)
- baas_webhook_v2 (/documentation/baas/primeiros_passos/teste_de_autenticacao/baas_webhook_v2)
- Aprovar TED com Autenticação de Dois Fatores (/documentation/baas/ted/2fa/aprovar_transacao_ted_2fa)
- Realizar TED com Autenticação de Dois Fatores (/documentation/baas/ted/2fa/realizar_transferencia_2fa)
- Solicitar Reenvio de Token para uma Transação Ted (/documentation/baas/ted/2fa/solicitacao_de_reenvio_de_token)
- Aprovar Transação em Lote com Autenticação de Dois Fatores (/documentation/baas/ted/batch_2fa/aprovar_transacao_em_lote_ted_2fa)
- Solicitar Reenvio de Token para uma Transação Ted em Lote (/documentation/baas/ted/batch_2fa/solicitacao_de_reenvio_de_token_para_lote_ted)
- Realizar Transação Ted em Lote com Autenticação de Dois Fatores (/documentation/baas/ted/batch_2fa/solicitacao_de_transacao_em_lote_ted_2fa)
- Introdução a Transação em Lote Ted (/documentation/baas/ted/batch/introducao_a_transacao_em_lote_ted)
- Listar Transações Ted de um lote de uma conta (/documentation/baas/ted/batch/listar_transacoes_de_um_lote_de_transacoes_ted)
- Listar Transações em Lote de uma conta (/documentation/baas/ted/batch/listar_transacoes_em_lote_ted_de_uma_conta)
- Realizar Transação Ted em Lote (/documentation/baas/ted/batch/solicitacao_de_transacao_em_lote_ted)
- Consultar TED (/documentation/baas/ted/consultar_ted)
- Tabela de Erros para Ted (/documentation/baas/ted/erros_ted)
- Listar TEDs (/documentation/baas/ted/listar_teds)
- Realizar TED (/documentation/baas/ted/realizar_transferencia)
- Aprovar Agendamento de Transação Ted com Autenticação de Dois Fatores (/documentation/baas/ted/schedule_2fa/aprovacao_de_agendamento_2fa)
- Introdução a Autenticação de Dois Fatores (/documentation/baas/ted/schedule_2fa/introducao_a_agendamento_2fa)
- Solicitar Agendamento de Transação Ted com Autenticação de Dois Fatores (/documentation/baas/ted/schedule_2fa/solicitacao_de_agendamento_2fa)
- Solicitar reenvio de token para um agendamento (/documentation/baas/ted/schedule_2fa/solicitacao_de_reenvio_de_token_para_agendamento_2fa)
- Aprovar Agendamento de Transação Ted em Lote com Autenticação de Dois Fatores (/documentation/baas/ted/schedule_batch_2fa/aprovacao_de_agendamento_em_lote_2fa)
- Solicitar Agendamento de Transação Ted em Lote (/documentation/baas/ted/schedule_batch_2fa/solicitacao_de_agendamento_em_lote_2fa)
- Solicitar Reenvio de Token para um Agendamento de Transação Ted em Lote (/documentation/baas/ted/schedule_batch_2fa/solicitacao_de_reenvio_de_token_para_agendamento_em_lote_2fa)
- Cancelar Agendamento de Transação Ted em Lote (/documentation/baas/ted/schedule_batch/cancelamento_de_agendamento_em_lote)
- Listar Agendamentos de um Lote de Agendamento (/documentation/baas/ted/schedule_batch/listar_agendamentos_de_um_lote)
- Listar Lotes de Agendamento de uma conta (/documentation/baas/ted/schedule_batch/listar_agendamentos_em_lote_de_uma_conta)
- Solicitar Agendamento de Transação Ted em Lote (/documentation/baas/ted/schedule_batch/solicitacao_de_agendamento_em_lote)
- Cancelar Agendamento de Transação Ted (/documentation/baas/ted/schedule/cancelamento_de_agendamento)
- Consultar Agendamento de Transação Ted (/documentation/baas/ted/schedule/consulta_de_agendamento)
- Introdução (/documentation/baas/ted/schedule/introducao)
- Listar Agendamentos de Transação Ted de uma conta (/documentation/baas/ted/schedule/listar_agendamentos_de_uma_conta)
- Solicitar Agendamento de Transação Ted (/documentation/baas/ted/schedule/solicitacao_de_agendamento)
- Webhook de conclusão de Agendamento Ted (/documentation/baas/ted/schedule/webhook_de_conclusao_de_agendamento)
- Webhook após finalização de envio de TED (/documentation/baas/ted/webhooks)
- baas_consulta_documents (/documentation/baas/upload_de_documentos/baas_consulta_documents)
- baas_upload_de_documentos (/documentation/baas/upload_de_documentos/)
- Aprovar o pagamento de um Boleto (/documentation/boletos/2fa/realizar_pagamento_de_um_boleto)
- Solicitar token para pagamento de um Boleto (/documentation/boletos/2fa/solicitar_token_para_pagamento)
- Criar carteira (/documentation/boletos/carteira/criar_carteira)
- Editar carteira (/documentation/boletos/carteira/editar_carteira)
- Listar carteiras da conta (/documentation/boletos/carteira/listar_carteiras)
- Consultar arquivo temporário (/documentation/boletos/cnab/consulta_por_chave)
- Arquivos remessa (CNAB) - Introdução (/documentation/boletos/cnab/introducao)
- Listar arquivos remessa temporários (/documentation/boletos/cnab/listar_arquivos_temporarios)
- Listar ocorrências temporárias (/documentation/boletos/cnab/listar_ocorrencias_temporarias)
- Upload de arquivo remessa (CNAB) (/documentation/boletos/cnab/upload_de_arquivo_remessa)
- Consulta de boleto por chave (/documentation/boletos/consulta/consulta_por_chave)
- Listar boletos (/documentation/boletos/consulta/listar_boletos)
- Consulta de carteiras de cobrança (/documentation/boletos/consultar_v1/consulta_de_carteira)
- Consultar arquivo retorno (/documentation/boletos/consultar_v1/consultar_arquivo_retorno)
- Consultar boleto (/documentation/boletos/consultar_v1/consultar_boleto)
- Emitir PDF (/documentation/boletos/consultar_v1/emitir_pdf)
- Francesinha (/documentation/boletos/consultar_v1/francesinha)
- Listar boletos (/documentation/boletos/consultar_v1/listar_boletos)
- Relatório de posição diária em Excel (/documentation/boletos/consultar_v1/posicao_diaria_excel)
- Relatório de posição diária em JSON (/documentation/boletos/consultar_v1/posicao_diaria_json)
- Rotina de conciliação de arquivo retorno (/documentation/boletos/consultar_v1/rotina_de_conciliacao_de_arquivo_retorno)
- Solicitar 2ª via de boleto (/documentation/boletos/consultar_v1/segunda_via_de_boleto)
- Emissão de boleto único (instantânea) (/documentation/boletos/emissao/emissao_boleto_unico_instantanea)
- Emissão de boleto único (padrão) (/documentation/boletos/emissao/emissao_boleto_unico_padrao)
- Emissão de boletos em lote (/documentation/boletos/emissao/emissao_em_lote)
- Cancelamento de abatimento (/documentation/boletos/instrucoes/abatimento/cancelar_abatimento)
- Criar abatimento (/documentation/boletos/instrucoes/abatimento/criar_abatimento)
- Baixa (/documentation/boletos/instrucoes/baixa)
- Desconto (/documentation/boletos/instrucoes/desconto)
- Edição (/documentation/boletos/instrucoes/edicao)
- Prorrogação (/documentation/boletos/instrucoes/extensao)
- Juros (/documentation/boletos/instrucoes/juros)
- Consultar lote de instruções (/documentation/boletos/instrucoes/lote/consultar_lote_de_instrucoes)
- Criar lote de instruções (/documentation/boletos/instrucoes/lote/criar_lote_de_instrucoes)
- Listar lotes de instruções (/documentation/boletos/instrucoes/lote/listar_lotes_de_instrucoes)
- Multa (/documentation/boletos/instrucoes/multa)
- Pagamento Parcial (/documentation/boletos/instrucoes/pagamento_parcial)
- Consulta de instrumento de protesto (/documentation/boletos/instrucoes/protesto/consulta_instrumento_de_protesto)
- Consulta de protesto por chave (/documentation/boletos/instrucoes/protesto/consulta_por_chave)
- Desistência (sustação) de protesto (/documentation/boletos/instrucoes/protesto/desistencia_de_protesto)
- Desistência (sustação) de protesto e baixa do boleto (/documentation/boletos/instrucoes/protesto/desistencia_de_protesto_e_baixa_do_boleto)
- Introdução (/documentation/boletos/instrucoes/protesto/introducao)
- Listar protestos (/documentation/boletos/instrucoes/protesto/listar_protestos)
- Pedido de protesto (/documentation/boletos/instrucoes/protesto/pedido_de_protesto)
- Sustação de protesto (/documentation/boletos/instrucoes/protesto/sustacao_de_protesto)
- Atualização de Rateio de Crédito (/documentation/boletos/instrucoes/rateio_de_credito)
- Valor (/documentation/boletos/instrucoes/valor)
- Introdução (/documentation/boletos/introducao)
- Listar grupos de liquidação (/documentation/boletos/liquidacao/listar_grupos_de_liquidacao)
- Listar liquidações (/documentation/boletos/liquidacao/listar_liquidacoes)
- Simulação de cenários (/documentation/boletos/liquidacao/simulacao_de_cenarios_de_liquidacao)
- Aprovar pagamento de boleto (/documentation/boletos/pagamento/aprovar_pagamento)
- Consultar linha digitável de boleto (/documentation/boletos/pagamento/consulta_linha_digitavel)
- Realizar pagamento de boleto (/documentation/boletos/pagamento/realizar_pagamento)
- Redirecionamento da Conta de Liquidação de um Boleto (/documentation/boletos/redirecionamento_de_conta_de_liquidacao)
- Listar arquivos retorno (/documentation/boletos/retorno/listar_arquivos_retorno)
- Emissão de um bolePix (/documentation/boletos/v1/emissao/emissao_de_um_bolepix)
- Emissão de boleto via CNAB (/documentation/boletos/v1/emissao/emissao_via_cnab)
- Emissão de boleto via JSON (/documentation/boletos/v1/emissao/emissao_via_json)
- Enviar instrução de boleto (/documentation/boletos/v1/enviar_instrucao_de_boleto)
- Introdução (/documentation/boletos/v1/introducao)
- Webhooks de boletos (/documentation/boletos/webhooks/boleto)
- Webhooks de carteiras de boletos (/documentation/boletos/webhooks/carteira)
- Webhooks de liquidação (/documentation/boletos/webhooks/liquidacao)
- Webhooks de arquivos retorno (/documentation/boletos/webhooks/retorno)
- Autenticação (/documentation/caas/account_event/authentication)
- Objeto Device Validation (/documentation/caas/account_event/device_validation)
- Status HTTP (/documentation/caas/account_event/http_status)
- Introdução (/documentation/caas/account_event/introduction)
- Pre PIX Transaction (/documentation/caas/account_event/pre_pix_transaction)
- Recuperar um Evento de Conta (/documentation/caas/account_event/query_registration)
- Padrões (/documentation/caas/account_event/standards)
- Dinâmica dos Status (/documentation/caas/account_event/status_dynamics)
- Criação de Conta (/documentation/caas/account_monitoring/account_registration)
- authentication (/documentation/caas/account_monitoring/authentication)
- Status HTTP (/documentation/caas/account_monitoring/http_status)
- Introdução (/documentation/caas/account_monitoring/introduction)
- Criação de Pessoas (/documentation/caas/account_monitoring/person_registration)
- Padrões (/documentation/caas/account_monitoring/standards)
- Webhook (/documentation/caas/account_monitoring/webhook)
- Criação de Sessão (/documentation/caas/auth_session_manager/auth_session)
- Autenticação (/documentation/caas/auth_session_manager/authentication)
- Status HTTP (/documentation/caas/auth_session_manager/http_status)
- Introdução (/documentation/caas/auth_session_manager/introduction)
- Gestão de Sessão (/documentation/caas/auth_session_manager/retrieve_session)
- authentication (/documentation/caas/banking/authentication)
- Boleto (/documentation/caas/banking/bankslips)
- Pagamento de Contas (/documentation/caas/banking/bill_payments)
- Depósitos (/documentation/caas/banking/deposits/introduction)
- Status HTTP (/documentation/caas/banking/http_status)
- Introdução (/documentation/caas/banking/introduction)
- Objetos Compartilhados (/documentation/caas/banking/objects)
- PIX Dict Operation (/documentation/caas/banking/pix_dict_operations)
- PIX Infraction Report (/documentation/caas/banking/pix_infraction_reports)
- PIX Transaction (/documentation/caas/banking/pix_transactions)
- Padrões (/documentation/caas/banking/standards)
- Webhook (/documentation/caas/banking/webhook)
- Transferências (/documentation/caas/banking/wire_transfers)
- Saques (/documentation/caas/banking/withdrawals)
- Status HTTP (/documentation/caas/car_rental/http_status)
- Imagens (/documentation/caas/car_rental/image)
- Introdução (/documentation/caas/car_rental/introduction)
- Troca de Mensagens (/documentation/caas/car_rental/messages)
- Objetos Compartilhados (/documentation/caas/car_rental/objects)
- Envio de Resultado Quiz (/documentation/caas/car_rental/quiz)
- RentalAgreement-v1 (/documentation/caas/car_rental/rental_agreement)
- RentalAgreement-v2 (/documentation/caas/car_rental/rental_agreement_v2)
- Reservation-v1 (/documentation/caas/car_rental/reservation)
- Reservation-v2 (/documentation/caas/car_rental/reservation_v2)
- Padrões (/documentation/caas/car_rental/standards)
- Webhook (/documentation/caas/car_rental/webhook)
- Alertas de Portadores (/documentation/caas/card_issuance/alerts)
- authentication (/documentation/caas/card_issuance/authentication)
- Status HTTP (/documentation/caas/card_issuance/http_status)
- Introdução (/documentation/caas/card_issuance/introduction)
- Padrões (/documentation/caas/card_issuance/standards)
- Transaction (/documentation/caas/card_issuance/transaction)
- authentication (/documentation/caas/card_order/authentication)
- Status HTTP (/documentation/caas/card_order/http_status)
- Introdução (/documentation/caas/card_order/introduction)
- Objetos (/documentation/caas/card_order/objects)
- Order (/documentation/caas/card_order/order)
- Padrões (/documentation/caas/card_order/standards)
- Webhook (/documentation/caas/card_order/webhook)
- authentication (/documentation/caas/credit_analysis/authentication)
- Fluxo de Desafio (/documentation/caas/credit_analysis/challenge_flow)
- Recuperar uma Análise de Crédito (/documentation/caas/credit_analysis/get_credit_analysis)
- Status HTTP (/documentation/caas/credit_analysis/http_status)
- Imagens (/documentation/caas/credit_analysis/image)
- Introdução (/documentation/caas/credit_analysis/introduction)
- Análise de Crédito - Pessoa Jurídica (/documentation/caas/credit_analysis/legal_person)
- Análise de Crédito - Pessoa Física (/documentation/caas/credit_analysis/natural_person)
- Objetos Compartilhados (/documentation/caas/credit_analysis/objects)
- Dados Sistema de Informações de Créditos (SCR - BACEN) (/documentation/caas/credit_analysis/scr)
- Padrões (/documentation/caas/credit_analysis/standards)
- Dinâmica dos Status (/documentation/caas/credit_analysis/status_dynamics)
- Atualizar o status de uma Análise de Crédito (/documentation/caas/credit_analysis/update_credit_analysis)
- Webhook (/documentation/caas/credit_analysis/webhook)
- Objeto Account (/documentation/caas/device_manager/account)
- Autenticação (/documentation/caas/device_manager/authentication)
- Objeto Device (/documentation/caas/device_manager/device_registration)
- Status HTTP (/documentation/caas/device_manager/http_status)
- Introdução (/documentation/caas/device_manager/introduction)
- Objeto Person (/documentation/caas/device_manager/person)
- Recuperar ou Desativar uma Account, Person ou Device (/documentation/caas/device_manager/query_registration)
- Padrões (/documentation/caas/device_manager/standards)
- Dinâmica dos Status (/documentation/caas/device_manager/status_dynamics)
- Compatibilidade da Biblioteca (/documentation/caas/device_scan/android/compatibility)
- O objeto DeviceScan (/documentation/caas/device_scan/android/device_scan_object)
- Implementação (/documentation/caas/device_scan/android/example)
- Coleta de informações (/documentation/caas/device_scan/android/information_gathering)
- Introdução (/documentation/caas/device_scan/android/introduction)
- Integração nativa (/documentation/caas/device_scan/android/native_java)
- Permissões (/documentation/caas/device_scan/android/permissions)
- Autenticação (/documentation/caas/device_scan/api/authentication)
- Compatibilidade da Biblioteca (/documentation/caas/device_scan/flutter/compatibility)
- O objeto QitechDeviceScan (/documentation/caas/device_scan/flutter/device_scan_object)
- Implementação (/documentation/caas/device_scan/flutter/example)
- Instalação (/documentation/caas/device_scan/flutter/installation)
- Introdução (/documentation/caas/device_scan/flutter/introduction)
- Permissões (/documentation/caas/device_scan/flutter/permissions)
- O objeto QITechIosDeviceScan (/documentation/caas/device_scan/ios/device_scan_object)
- Implementação (/documentation/caas/device_scan/ios/example)
- Coleta de informações (/documentation/caas/device_scan/ios/information_gathering)
- Introdução (/documentation/caas/device_scan/ios/introduction)
- Integração nativa (/documentation/caas/device_scan/ios/native_swift)
- Permissões (/documentation/caas/device_scan/ios/permissions)
- Compatibilidade (/documentation/caas/device_scan/react_native/compatibility)
- A função startDeviceScan (/documentation/caas/device_scan/react_native/device_scan_object)
- Implementação (/documentation/caas/device_scan/react_native/example)
- Instalação (/documentation/caas/device_scan/react_native/installation)
- Introdução (/documentation/caas/device_scan/react_native/introduction)
- Permissões (/documentation/caas/device_scan/react_native/permissions)
- Desktop Device Scan (/documentation/caas/device_scan/web/desktop)
- O objeto DeviceScan (/documentation/caas/device_scan/web/device_scan_object)
- Implementação (/documentation/caas/device_scan/web/example)
- Importando a biblioteca (/documentation/caas/device_scan/web/import)
- Coletando os Retornos (/documentation/caas/device_scan/web/information_gathering)
- Introdução (/documentation/caas/device_scan/web/introduction)
- Enviando um documento (/documentation/caas/document_analysis/document_submission)
- Status HTTP (/documentation/caas/document_analysis/http_status)
- Introdução (/documentation/caas/document_analysis/introduction)
- Webhook (/documentation/caas/document_analysis/webhook)
- builder (/documentation/caas/face_recognition/android/builder)
- Coletando os Resultados (/documentation/caas/face_recognition/android/collecting_response)
- Validação 1:1 - Face Match (/documentation/caas/face_recognition/android/face_match)
- Introdução (/documentation/caas/face_recognition/android/introduction)
- Integração nativa (/documentation/caas/face_recognition/android/native_java)
- using_sdk (/documentation/caas/face_recognition/android/using_sdk)
- Autenticação (/documentation/caas/face_recognition/api/authentication)
- Registro de rosto (1:1) (/documentation/caas/face_recognition/api/face_registration)
- Status HTTP (/documentation/caas/face_recognition/api/http_status)
- Imagem (/documentation/caas/face_recognition/api/image)
- Introdução (/documentation/caas/face_recognition/api/introduction)
- Registration (/documentation/caas/face_recognition/api/registration)
- Padrões (/documentation/caas/face_recognition/api/standards)
- Validation (/documentation/caas/face_recognition/api/validation)
- Coletando os Retornos (/documentation/caas/face_recognition/flutter/collecting_response)
- Compatibilidade (/documentation/caas/face_recognition/flutter/compatibility)
- Implementação (/documentation/caas/face_recognition/flutter/example)
- O objeto FaceReconOptions (/documentation/caas/face_recognition/flutter/face_recon_options)
- Instalação (/documentation/caas/face_recognition/flutter/installation)
- Introdução (/documentation/caas/face_recognition/flutter/introduction)
- Coletando os Retornos do SDK (/documentation/caas/face_recognition/ios/collecting_response)
- QITechIosFaceRecognitionConfiguration (/documentation/caas/face_recognition/ios/configuration)
- Introdução (/documentation/caas/face_recognition/ios/introduction)
- Importando o SDK (/documentation/caas/face_recognition/ios/native_swift)
- necessary_permissions (/documentation/caas/face_recognition/ios/necessary_permissions)
- using_sdk (/documentation/caas/face_recognition/ios/using_sdk)
- Coletando os Retornos (/documentation/caas/face_recognition/react_native/collecting_response)
- Compatibilidade (/documentation/caas/face_recognition/react_native/compatibility)
- Implementação (/documentation/caas/face_recognition/react_native/example)
- O objeto FaceReconOptions (/documentation/caas/face_recognition/react_native/face_recon_options)
- Instalação (/documentation/caas/face_recognition/react_native/installation)
- Introdução (/documentation/caas/face_recognition/react_native/introduction)
- Coletando os Retornos do SDK (/documentation/caas/face_recognition/web/collecting_response)
- Implementação (/documentation/caas/face_recognition/web/example)
- O construtor QITechWebFaceRecon.WebFaceRecon() (/documentation/caas/face_recognition/web/example_zaigwebfacerecon)
- Importando a biblioteca (/documentation/caas/face_recognition/web/import)
- Introdução (/documentation/caas/face_recognition/web/introduction)
- Registro de Rosto e Validação 1:1 (/documentation/caas/face_recognition/web/registration_and_validation)
- authentication (/documentation/caas/limits/authentication)
- Status HTTP (/documentation/caas/limits/http_status)
- Introdução (/documentation/caas/limits/introduction)
- Cadastro de Novo Limite (/documentation/caas/limits/limit_registration)
- Criando uma lista de beneficiários (/documentation/caas/limits/recipient_list)
- Padrões (/documentation/caas/limits/standards)
- Dinâmica dos Status (/documentation/caas/limits/status_dynamics)
- Webhook (/documentation/caas/limits/webhook)
- builder (/documentation/caas/ocr/android/builder)
- Coletando os Retornos (/documentation/caas/ocr/android/collecting_response)
- DocumentRecognitionStep (/documentation/caas/ocr/android/document_step)
- DocumentDetectorStep (/documentation/caas/ocr/android/implementation_demo)
- Introdução (/documentation/caas/ocr/android/introduction)
- Integração nativa (/documentation/caas/ocr/android/native_java)
- using_sdk (/documentation/caas/ocr/android/using_sdk)
- authentication (/documentation/caas/ocr/api/authentication)
- Status HTTP (/documentation/caas/ocr/api/http_status)
- Introdução (/documentation/caas/ocr/api/introduction)
- quality (/documentation/caas/ocr/api/quality)
- Enviando um Documento (/documentation/caas/ocr/api/send_image)
- Coletando os Retornos (/documentation/caas/ocr/flutter/collecting_response)
- Compatibilidade (/documentation/caas/ocr/flutter/compatibility)
- Implementação (/documentation/caas/ocr/flutter/example)
- Instalação (/documentation/caas/ocr/flutter/installation)
- Introdução (/documentation/caas/ocr/flutter/introduction)
- O objeto OcrOptions (/documentation/caas/ocr/flutter/ocr_options)
- Coletando os Retornos (/documentation/caas/ocr/ios/collecting_response)
- QITechIosOcrConfiguration (/documentation/caas/ocr/ios/configuration)
- Introdução (/documentation/caas/ocr/ios/introduction)
- Importando o SDK (/documentation/caas/ocr/ios/native_swift)
- necessary_permissions (/documentation/caas/ocr/ios/necessary_permissions)
- Importando o SDK (/documentation/caas/ocr/ios/using_sdk)
- Coletando os Retornos (/documentation/caas/ocr/react_native/collecting_response)
- Compatibilidade (/documentation/caas/ocr/react_native/compatibility)
- Implementação (/documentation/caas/ocr/react_native/example)
- Instalação (/documentation/caas/ocr/react_native/installation)
- Introdução (/documentation/caas/ocr/react_native/introduction)
- O objeto OcrOptions (/documentation/caas/ocr/react_native/ocr_options)
- Coletando os Retornos (/documentation/caas/ocr/web/collecting_results)
- O construtor QiTechWebOCR.WebOCR() (/documentation/caas/ocr/web/constructor_info)
- Implementação (/documentation/caas/ocr/web/example)
- Importando a biblioteca (/documentation/caas/ocr/web/import)
- A função initialize() (/documentation/caas/ocr/web/initialize_info)
- Introdução (/documentation/caas/ocr/web/introduction)
- Autenticação (/documentation/caas/onboarding/authentication)
- Status HTTP (/documentation/caas/onboarding/http_status)
- Integrações (/documentation/caas/onboarding/integrations)
- Introdução (/documentation/caas/onboarding/introduction)
- Objeto Legal Person (/documentation/caas/onboarding/legal_person)
- Objeto Natural Person (/documentation/caas/onboarding/natural_person)
- Objetos Compartilhados (/documentation/caas/onboarding/objects)
- Recuperar um Cadastro (/documentation/caas/onboarding/query_registration)
- Integrando os dados do SDK (face, documentos e device) (/documentation/caas/onboarding/sdk_integration)
- Padrões (/documentation/caas/onboarding/standards)
- Dinâmica dos status (/documentation/caas/onboarding/status_dynamics)
- Atualizar um cadastro (/documentation/caas/onboarding/update_registration)
- Webhook (/documentation/caas/onboarding/webhook)
- Requisição de Autorização (Opcional) (/documentation/cards/autorizacao/)
- Transações na QI Conta (/documentation/cards/autorizacao/balance_transaction)
- Simulação de autorização (/documentation/cards/autorizacao/simular_autorizacao)
- Gerar cartão físico (/documentation/cards/create/gerar_cartao_fisico)
- Criar cartão virtual (/documentation/cards/create/gerar_cartao_virtual)
- Introdução (/documentation/cards/introducao)
- Buscar autorização pela Chave da Autorização (/documentation/cards/search/buscar_autorizacao)
- Buscar Authorizações (/documentation/cards/search/buscar_autorizacoes)
- Buscar cartão por chave (/documentation/cards/search/buscar_cartao_by_key)
- Buscar dados PCI (/documentation/cards/search/buscar_dados_pci)
- Buscar entrega por chave de cartão (/documentation/cards/search/buscar_entrega_by_key)
- Buscar Senha PCI (/documentation/cards/search/buscar_senha)
- Listar cartões (/documentation/cards/search/listar_cartoes)
- Ativar cartão físico (/documentation/cards/status/ativar_cartao)
- Atualizar status (/documentation/cards/status/update_status_cartao)
- Configuração do contactless (/documentation/cards/update/contactless_cartao)
- Alterar senha cartão físico (/documentation/cards/update/password_cartao)
- Atualizar endereço de entrega (/documentation/cards/update/update_delivery_address)
- Configuração do contactless (/documentation/cartao_pos_pago/cartao/atualizar/atualizar_contactless)
- Atualizar endereço de entrega (/documentation/cartao_pos_pago/cartao/atualizar/atualizar_endereco_entrega)
- Alterar senha cartão físico (/documentation/cartao_pos_pago/cartao/atualizar/atualizar_senha)
- Simulação de cenários (/documentation/cartao_pos_pago/cartao/atualizar/simulacao_de_cenarios)
- Buscar cartão por chave (/documentation/cartao_pos_pago/cartao/busca/buscar_cartao_por_chave)
- Buscar entrega por chave de cartão (/documentation/cartao_pos_pago/cartao/busca/buscar_dados_entrega_por_chave)
- Buscar dados PCI (/documentation/cartao_pos_pago/cartao/busca/buscar_dados_pci)
- Buscar Senha PCI (/documentation/cartao_pos_pago/cartao/busca/buscar_senha)
- Ativar cartão físico (/documentation/cartao_pos_pago/cartao/status/ativar_cartao)
- Atualizar status (/documentation/cartao_pos_pago/cartao/status/atualizar_status_cartao)
- Alteração de Limite de Carteira (/documentation/cartao_pos_pago/faturas/carteira/alteracao_de_limite)
- Buscar Entrada de Carteira por Chave (/documentation/cartao_pos_pago/faturas/carteira/consulta_entrada_por_chave)
- Consulta de Carteira por Chave (/documentation/cartao_pos_pago/faturas/carteira/consulta_por_chave)
- Criação de Carteira (Wallet) (/documentation/cartao_pos_pago/faturas/carteira/criacao_de_carteira)
- Listar de Carteiras (Wallets) (/documentation/cartao_pos_pago/faturas/carteira/listar_carteiras)
- Listar Entradas de Carteira (/documentation/cartao_pos_pago/faturas/carteira/listar_entradas_da_carteira)
- Buscar Boleto da Carteira (/documentation/cartao_pos_pago/faturas/fatura/boleto_de_pagamento_da_fatura)
- Buscar Fatura por Chave (/documentation/cartao_pos_pago/faturas/fatura/consulta_por_chave)
- Listar Faturas (/documentation/cartao_pos_pago/faturas/fatura/listar_faturas)
- Simulação de cenários - Fechamento e Vencimento de Faturas (/documentation/cartao_pos_pago/faturas/fatura/simulacao_de_cenarios)
- Alteração de Limite de Instrumento de Pagamento (/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/alteracao_de_limite)
- Cancelamento de Instrumento de Pagamento (/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/cancelamento_de_instrumento_de_pagamento)
- Buscar Entrada de Instrumento de Pagamento por Chave (/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/consulta_entrada_por_chave)
- Criação de Instrumento de Pagamento (/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/criacao_de_instrumento_de_pagamento)
- Listar Entradas de Instrumentos de Pagamento (/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/listar_entradas_do_instrumento_de_pagamento)
- Listar Instrumentos de Pagamento (/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/listar_instrumentos_de_pagamento)
- Simulação de cenários (/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/simulacao_de_cenarios)
- Webhooks de Carteira (/documentation/cartao_pos_pago/faturas/webhooks/carteira)
- Webhooks de Entradas de Carteira (/documentation/cartao_pos_pago/faturas/webhooks/entrada_da_carteira)
- Webhooks de Entradas de Instrumento de Pagamento (/documentation/cartao_pos_pago/faturas/webhooks/entrada_do_instrumento_de_pagamento)
- Webhooks de Fatura (/documentation/cartao_pos_pago/faturas/webhooks/fatura)
- Webhooks de Pagamento de Fatura (/documentation/cartao_pos_pago/faturas/webhooks/pagamento_da_fatura)
- Introdução (/documentation/cartao_pos_pago/introducao)
- Manual BaaS - Conta Digital (/documentation/casos_de_uso/manual_baas)
- Manual BaaS - Serviço (/documentation/casos_de_uso/manual_baas_servico)
- Ambientes (/documentation/certifiqi/ambientes)
- Arquivos Zip (/documentation/certifiqi/arquivo_zip)
- Assinatura Automática (/documentation/certifiqi/assinatura_automatica)
- Criação de Perfil de Acesso (/documentation/certifiqi/cadastro)
- Cancelar um Evento de Assinatura (/documentation/certifiqi/cancelar_batch_group_de_assinatura)
- Consultar Evento de Assinatura (/documentation/certifiqi/consultar_evento)
- Consultar URLs dos documentos (/documentation/certifiqi/consultar_url)
- Criar Evento de Assinatura (/documentation/certifiqi/criar_batch_group)
- Criar Evento de Assinatura para Notificar o Fromtis (/documentation/certifiqi/criar_batch_group_fromtis)
- Enviar para Assinatura (/documentation/certifiqi/enviar_para_assinatura)
- Estrutura (/documentation/certifiqi/estrutura)
- Forma de Autenticação (/documentation/certifiqi/forma_de_autenticacao)
- Início (/documentation/certifiqi/inicio)
- Permissão do usuário (/documentation/certifiqi/permissoes)
- Upload de Documentos em CNAB (/documentation/certifiqi/upload_documentos_cnab_assincrono)
- Upload de Documentos em PDF (/documentation/certifiqi/upload_documentos_pdf)
- Webhook (/documentation/certifiqi/webhook)
- Criação de Cessões (/documentation/cessoes/criacao_de_cessao_0eaeffec-ee95-4cb1-a266-bcb52f23237d)
- Abertura de conta escrow PF (/documentation/contas/abertura_de_conta_escrow/abertura_de_conta_escrow_pf)
- Abertura de conta escrow PJ (/documentation/contas/abertura_de_conta_escrow/abertura_de_conta_escrow_pj)
- Introdução (/documentation/contas/abertura_de_conta_escrow/introducao)
- Abertura de conta PF (/documentation/contas/abertura_de_conta/abertura_de_conta_pf)
- Abertura de conta PJ (/documentation/contas/abertura_de_conta/abertura_de_conta_pj)
- Rascunho de Conta Livre Movimentação - Pessoa Jurídica (/documentation/contas/abertura_de_conta/draft_checking_legal_person)
- fluxo_de_abertura_de_conta (/documentation/contas/abertura_de_conta/fluxo_de_abertura_de_conta)
- Introdução (/documentation/contas/abertura_de_conta/introducao)
- Webhooks de abertura de conta (/documentation/contas/abertura_de_conta/webhooks_contas)
- Emitir Carta Bancária (/documentation/contas/carta_bancaria)
- Emitir Carta de Circularização (/documentation/contas/carta_circularizacao)
- Consulta de tarifas (/documentation/contas/consulta_de_tarifas)
- Consultar conta (/documentation/contas/consultar_conta)
- Listar contas (/documentation/contas/consultar_contas)
- Consultar detalhes de pedido de conta (/documentation/contas/consultar_detalhes_pedido_conta)
- Encerramento de conta (/documentation/contas/encerramento_de_conta)
- Extrato de tarifas (/documentation/contas/extrato_de_tarifas)
- Gestão de tarifas (/documentation/contas/gestao_de_tarifas)
- Informe de rendimentos (/documentation/contas/informe_rendimentos)
- Consultar Bloqueios em Conta (/documentation/contas/ordens_de_bloqueio)
- Simulação de cenários (/documentation/contas/simulacao)
- Criar conta destino para escrow (/documentation/d88ff174-100d-4b55-80b7-86e11f508400)
- Cadastrar conta no DDA (/documentation/dda/cadastro_dda)
- Remover conta do DDA (/documentation/dda/cancelamento_dda)
- Consultar conta cadastrada no DDA (/documentation/dda/consultar_dados_conta)
- Erros retornados na api (/documentation/dda/erros)
- Introdução (/documentation/dda/introducao)
- Listar contas cadastradas no DDA (/documentation/dda/lista_contas_cadastradas)
- Lista de boletos registrados no DDA (bank slip notification) com filtros (/documentation/dda/lista_notificacoes_de_boletos)
- Recuperação de termo de aceite e cancelamento de cadastro no DDA (/documentation/dda/recuperacao_termo)
- Simulação de cenários de registro e alteração de boletos (/documentation/dda/simulacoes)
- Formato dos Webhooks (/documentation/dda/webhooks)
- acg1 (/documentation/documentacoes ocultas/agc1/acg1)
- introducao (/documentation/documentacoes ocultas/agc1/introducao)
- Permissão (Geral): (/documentation/documentacoes ocultas/perfis_de_acesso)
- cancelamento_de_solicitacao.md (/documentation/documentacoes ocultas/scr/cancelamento_de_solicitacao.md)
- consultar_solicitacao (/documentation/documentacoes ocultas/scr/consultar_solicitacao)
- consultar_solicitacoes (/documentation/documentacoes ocultas/scr/consultar_solicitacoes)
- introducao (/documentation/documentacoes ocultas/scr/introducao)
- refazer_consulta (/documentation/documentacoes ocultas/scr/refazer_consulta)
- solicitacao_de_consulta (/documentation/documentacoes ocultas/scr/solicitacao_de_consulta)
- webhook (/documentation/documentacoes ocultas/scr/webhook)
- Atualizar cessionário do contrato de crédito (/documentation/emissao_de_divida/atualizar_cessionario_047911bb-d3fb-48fe-88fd-aebdeb7e11ad)
- Atualizar informações das partes relacionadas ao contrato de crédito (/documentation/emissao_de_divida/atualizar_dados_da_parte_relacionada)
- Autorizar desembolso (/documentation/emissao_de_divida/autorizar_desembolso)
- Cancelar dívida antes de desembolsar (/documentation/emissao_de_divida/cancelamento/cancelar_divida_antes_de_desembolsar)
- Cancelar permanentemente (/documentation/emissao_de_divida/cancelamento/cancelar_permanentemente)
- Emissão de pix qr code de devolução (/documentation/emissao_de_divida/cancelamento/desistencia/cancelamento_de_divida_em_ate_sete_dias_apos_o_desembolso)
- Consulta de pix qr code de devolução (/documentation/emissao_de_divida/cancelamento/desistencia/consulta_de_pix_qr_code_de_devolucao)
- Introdução (/documentation/emissao_de_divida/cancelamento/desistencia/introducao)
- Introdução (/documentation/emissao_de_divida/cancelamento/introducao)
- Catálogo de Erros - Lending-as-a-Service (/documentation/emissao_de_divida/catalogo_de_erros_laas)
- Configurar data de desembolso (/documentation/emissao_de_divida/configurar_data_de_desembolso)
- Consulta de dívida (/documentation/emissao_de_divida/consulta_de_divida)
- Consulta de dívida por Contract Number (/documentation/emissao_de_divida/consulta_por_contract_number)
- Consulta de dívida por Credit Operation Key (/documentation/emissao_de_divida/consulta_por_credit_operation_key)
- Consulta de dívida por Requester Identifier Key (/documentation/emissao_de_divida/consulta_por_requester_identifier_key)
- Desembolso da operação (/documentation/emissao_de_divida/desembolso_da_operacao)
- Emissão de dívida PF (/documentation/emissao_de_divida/emissao/emissao_de_divida_pf)
- Emissão de dívida PJ (/documentation/emissao_de_divida/emissao/emissao_de_divida_pj)
- Exemplos de payload de desembolso (/documentation/emissao_de_divida/emissao/exemplo_payloads_desembolso)
- Assinaturas alternativas (/documentation/emissao_de_divida/formalizacao/assinatura_de_contrato)
- Assinatura de contrato com OPT-IN (/documentation/emissao_de_divida/formalizacao/assinatura_opt_in)
- Envio do PDF assinado (/documentation/emissao_de_divida/formalizacao/assinatura_pdf)
- Assinatura de contrato com selfie (/documentation/emissao_de_divida/formalizacao/assinatura_selfie)
- Assinatura de contrato (/documentation/emissao_de_divida/formalizacao/introducao_formalizacao)
- Gerar Boleto ou PIX para uma Parcela (/documentation/emissao_de_divida/gerar_boleto_ou_pix_para_uma_parcela)
- Introdução (/documentation/emissao_de_divida/introducao)
- Monitoramento do correspondente bancário (/documentation/emissao_de_divida/mcb)
- Metadata (/documentation/emissao_de_divida/metadata)
- Não me perturbe (/documentation/emissao_de_divida/nao_me_perturbe)
- Introdução (/documentation/emissao_de_divida/reapresentacao_de_conta_bancaria)
- Reenviar documentos das partes relacionadas ao contrato de crédito (/documentation/emissao_de_divida/reenviar_documentos_das_partes_relacionadas)
- Ações pós-desembolso (/documentation/emissao_de_divida/reprocessar_acao_pos_desembolso)
- Recalcular contrato de crédito (/documentation/emissao_de_divida/reprocessar_contrato)
- Alterar Dados de Desembolso (/documentation/emissao_de_divida/reprocessar_multiplas_datas/trocar_conta)
- Alterar Data de Desembolso (/documentation/emissao_de_divida/reprocessar_multiplas_datas/trocar_data)
- Seguro (/documentation/emissao_de_divida/seguro)
- Simulação de dívida antigo (/documentation/emissao_de_divida/simulacao_de_divida_antigo)
- Simulação de dívida novo (/documentation/emissao_de_divida/simulacao_de_divida_novo)
- Simulando erros em Sandbox (/documentation/emissao_de_divida/simulando_erros)
- Possíveis status de uma dívida (/documentation/emissao_de_divida/status_de_uma_divida)
- Catálogo de Erros (/documentation/erros/catalogo_de_erros)
- Aditamento (/documentation/escrituracao/aditamento/conceito)
- Baixar Documento (/documentation/escrituracao/aditamento/endpoints/baixar-documento)
- Cancelar Aditamento (/documentation/escrituracao/aditamento/endpoints/cancelar-aditamento)
- Consultar Aditamento (/documentation/escrituracao/aditamento/endpoints/consultar-aditamento)
- Consultar Signatários (/documentation/escrituracao/aditamento/endpoints/consultar-signatarios)
- Criar Aditamento (/documentation/escrituracao/aditamento/endpoints/criar-aditamento)
- Simular Aditamento (/documentation/escrituracao/aditamento/endpoints/simular-aditamento)
- Validar Aditamento (/documentation/escrituracao/aditamento/endpoints/validar-aditamento)
- Exemplos (/documentation/escrituracao/aditamento/exemplos)
- Regras de Negócio — Aditamento (/documentation/escrituracao/aditamento/regras-de-negocio)
- Tipos de Alteração (/documentation/escrituracao/aditamento/tipos-de-alteracao)
- Amortização Extraordinária (/documentation/escrituracao/amortizacao-extraordinaria/conceito)
- Consultar Amortização Extraordinária (/documentation/escrituracao/amortizacao-extraordinaria/endpoints/consultar-amortizacao)
- Criar Amortização Extraordinária (/documentation/escrituracao/amortizacao-extraordinaria/endpoints/criar-amortizacao)
- Simular Valor Presente da Amortização Extraordinária (/documentation/escrituracao/amortizacao-extraordinaria/endpoints/simular-valor-presente)
- Exemplos — Amortização Extraordinária (/documentation/escrituracao/amortizacao-extraordinaria/exemplos)
- Amortização com Recompra (/documentation/escrituracao/amortizacao-extraordinaria/recompra-de-operacao)
- Regras de Negócio — Amortização Extraordinária (/documentation/escrituracao/amortizacao-extraordinaria/regras-de-negocio)
- Catálogo de Erros (/documentation/escrituracao/catalogo-erros/catalogo-erros)
- Configuração de Webhooks (/documentation/escrituracao/configuracao-webhooks)
- Cadastro de Lastro (Ativo Subjacente) (/documentation/escrituracao/emissao-cr/cadastro-lastro)
- Cadastro de Operação de CR (/documentation/escrituracao/emissao-cr/cadastro-operacao)
- Envio de Documento (/documentation/escrituracao/emissao-cr/envio-documento)
- Enviar Documento Externo da Operação (/documentation/escrituracao/emissao-cr/envio-documento-externo)
- Cadastro de Lastro (Ativo Subjacente) (/documentation/escrituracao/emissao-cra/cadastro-lastro)
- Cadastro de Operação de CRA (/documentation/escrituracao/emissao-cra/cadastro-operacao)
- Envio de Documento (/documentation/escrituracao/emissao-cra/envio-documento)
- Enviar Documento Externo da Operação (/documentation/escrituracao/emissao-cra/envio-documento-externo)
- Cadastro de Lastro (Ativo Subjacente) (/documentation/escrituracao/emissao-cri/cadastro-lastro)
- Cadastro de Operação de CRI (/documentation/escrituracao/emissao-cri/cadastro-operacao)
- Envio de Documento (/documentation/escrituracao/emissao-cri/envio-documento)
- Enviar Documento Externo da Operação (/documentation/escrituracao/emissao-cri/envio-documento-externo)
- Atualização da conta de desembolso da operação. (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-conta-desembolso)
- Atualização de dados financeiros na Operação (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-dados-financeiros)
- Atualização de dados dos investidores na Operação (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-investidores)
- Atualização do método de assinatura na Operação (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-metodo-assinatura)
- Envio de Garantia na Operação (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/cadastro-garantia)
- Remoção de Garantia na Operação (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/remover-garantia)
- Envio de documentos (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/upload-documento)
- Cadastro e Remoção de Metadata na Operação (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-metadata-identificacao)
- Envio e Remoção de Documentos de Representantes de Partes Relacionadas (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-documento)
- Envio e Remoção de Grupos de Assinantes de Representantes de Partes Relacionadas (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-grupo-assinantes)
- Cadastro e Remoção de Partes Relacionadas de um documento específico (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-parte-relacionada-em-documento)
- Cadastro e Remoção de Partes Relacionadas (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/cadastrar-parte-relacionada)
- Cadastro de Operação de Nota Comercial (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/criar-operacao)
- Desembolso para terceiro na operação (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/desembolso-terceiro)
- Campos Extras (Extra Fields) (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/extra-fields)
- Envio do log de aceite do cliente (/documentation/escrituracao/emissao-de-notas/cadastro-operacao/log-aceite)
- Cancelar Operação (/documentation/escrituracao/emissao-de-notas/cancelar-operacao)
- Consulta do Link dos contratos assinados via QI SIGN da Operação (/documentation/escrituracao/emissao-de-notas/consulta-link-assinado-qisign)
- Consulta dos Links para assinatura via QI SIGN da Operação (/documentation/escrituracao/emissao-de-notas/consulta-link-assinatura-qisign)
- Consulta dos Documentos da Operação (/documentation/escrituracao/emissao-de-notas/consulta/consulta-documentos-operacao)
- Consulta de Operação por Chave (/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-chave)
- Consulta de Operações por Filtros (/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-filtros)
- Consulta do Próximo Número de Emissão por Emissor (/documentation/escrituracao/emissao-de-notas/consulta/consulta-proximo-numero-emissao)
- Enviar Atas de Aprovação Assinadas (/documentation/escrituracao/emissao-de-notas/envio-ata-aprovacao)
- Enviar Documentos Assinados da Operação (/documentation/escrituracao/emissao-de-notas/envio-contratos-assinados)
- Enviar Operação para Análise (/documentation/escrituracao/emissao-de-notas/envio-para-analise)
- Enviar Operação para Assinatura (/documentation/escrituracao/emissao-de-notas/envio-para-assinatura)
- Alterar Template do Termo de Adesão (/documentation/escrituracao/emissao-de-notas/geracao-minutas/alterar-template-ta)
- Alterar Template do Termo Constitutivo (/documentation/escrituracao/emissao-de-notas/geracao-minutas/alterar-template-tc)
- Consulta de templates disponíveis (/documentation/escrituracao/emissao-de-notas/geracao-minutas/consulta-minutas-disponiveis)
- Pré-visualizar Termo de Adesão (/documentation/escrituracao/emissao-de-notas/geracao-minutas/gerar-minuta-adesao)
- Pré-visualizar Termo Constitutivo (/documentation/escrituracao/emissao-de-notas/geracao-minutas/gerar-minuta-contrato)
- Introdução à Emissão de Notas Comerciais (/documentation/escrituracao/emissao-de-notas/inicio)
- Simulação de condições financeiras (/documentation/escrituracao/emissao-de-notas/simulacao)
- Cadastro de Operação de Debênture (/documentation/escrituracao/emissao-debentures/cadastro-operacao)
- Envio de Documento (/documentation/escrituracao/emissao-debentures/envio-documento)
- Enviar Documento Externo da Operação (/documentation/escrituracao/emissao-debentures/envio-documento-externo)
- Envio de Garantia na Operação (/documentation/escrituracao/emissao-debentures/envio-garantia)
- Alteração de Cadastro do Emissor (/documentation/escrituracao/homologacao-emissor/alteracao-cadastro/)
- Consulta da Auto-assinatura (/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-auto-assinatura)
- Consulta dos Links de Assinatura do Termo de Adesão (/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-links-assinatura)
- Auto-assinatura do Emissor (/documentation/escrituracao/homologacao-emissor/auto-assinatura/inicio)
- Solicitação da Auto-assinatura (/documentation/escrituracao/homologacao-emissor/auto-assinatura/solicitacao-auto-assinatura)
- Cadastro de Grupos de Assinantes do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor)
- Remoção de Grupos de Assinantes do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor-remocao)
- Cadastro Básico do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/cadastro-basico)
- Cadastro de Conta Bancária do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor)
- Definição de Conta Bancária Principal do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor-principal)
- Remoção de Conta Bancária do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor-remocao)
- Envio de Documentos do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor)
- Remoção de Documentos do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor-remocao)
- Envio de Documentos do Representante do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor)
- Remoção de Documentos do Representante do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor-remocao)
- Cadastro de Informações de Contato do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor)
- Definição de Contato Principal do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor-principal)
- Remoção de Informações de Contato do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor-remocao)
- Cadastro de Representantes do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor)
- Remoção de Representante do Emissor (/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor-remocao)
- Consulta de Emissor (/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-chave)
- Consulta de Emissores por filtros (/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-filtro)
- Envio para Análise do Emissor (/documentation/escrituracao/homologacao-emissor/envio-analise/)
- Introdução (/documentation/escrituracao/homologacao-emissor/inicio)
- Solicitação de Acesso aos Dados do Emissor (/documentation/escrituracao/homologacao-emissor/solicitacao-acesso)
- Alteraçao de Cadastro do Investidor (/documentation/escrituracao/homologacao-investidor/alteracao-cadastro/)
- Cadastro de Grupos de Assinantes do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor)
- Remoção de Grupos de Assinantes do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor-remocao)
- Cadastro Básico do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/cadastro-basico)
- Cadastro de Conta Bancária do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor)
- Remoção de Conta Bancária do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor-remocao)
- Envio de Documentos do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor)
- Remoção de Documentos do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor-remocao)
- Envio de Documentos do Representante do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor)
- Remoção de Documentos do Representante do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor-remocao)
- Cadastro de Informações de Contato do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor)
- Remoção de Informações de Contato do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor-remocao)
- Cadastro de Representantes do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor)
- Remoção de Representante do Investidor (/documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor-remocao)
- Consulta de Investidor (/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-chave)
- Consulta de Investidores por filtros (/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-filtro)
- Envio para Análise do Investidor (/documentation/escrituracao/homologacao-investidor/envio-analise/)
- Introdução (/documentation/escrituracao/homologacao-investidor/inicio)
- **Solicitação de Acesso aos Dados do Investidor** (/documentation/escrituracao/homologacao-investidor/solicitacao-acesso)
- Consulta de Comprovante de Transação (/documentation/escrituracao/integralizacao-cotas/consulta-comprovante-transacao)
- Consulta de Conta de Liquidação (/documentation/escrituracao/integralizacao-cotas/consulta-conta-liquidacao)
- Consulta de Integralização por Chave (/documentation/escrituracao/integralizacao-cotas/consulta-processo-integralizacao)
- Consulta de Transações da Integralização (/documentation/escrituracao/integralizacao-cotas/consulta-transacoes-integralizacao)
- Introdução à Integralização de Cotas (/documentation/escrituracao/integralizacao-cotas/inicio)
- Cadastro de Subscrição (/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cadastro-subscricao)
- Cancelar subscrição (/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cancelar-subscricao)
- Confirmação ou Rejeição do Pagamento de Subscrição (/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/confirmacao-pagamento)
- Consulta de Subscrição (/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/consulta-subscricao-cotas)
- Registro de Pagamento de Subscrição (/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/registro-de-pagamento)
- Recebimento de Webhooks (/documentation/escrituracao/introducao/autenticacao_webhooks)
- Escrituração de Notas Comerciais (/documentation/escrituracao/introducao/)
- Endpoints de teste (/documentation/escrituracao/introducao/teste-autenticacao/endpoints_de_teste)
- Teste de autenticação (/documentation/escrituracao/introducao/teste-autenticacao/teste_de_autenticacao)
- Troca de Chaves (/documentation/escrituracao/introducao/troca_de_chaves)
- Consulta de Ativo (/documentation/escrituracao/operacoes-ativas/consulta-security)
- Consulta de Posição do Investidor (/documentation/escrituracao/operacoes-ativas/posicao-investidor)
- Roteiro de Integração — API de Escrituração de Notas Comerciais (NC) com Auto-Assinatura (/documentation/escrituracao/roteiro-integracao/integration-guide-nc-auto-signature)
- Roteiro de Integração de escrituração de notas comerciais (/documentation/escrituracao/roteiro-integracao/roteiro-integracao-padrao)
- Roteiro de Integração de escrituração de notas comerciais (/documentation/escrituracao/roteiro-integracao/roteiro-integracao-padrao-external)
- Roteiro de Integração de escrituração de notas comerciais + Boletos + Sistema de baixas (/documentation/escrituracao/roteiro-integracao/roteiro-integracao-securities-baas-dtvm)
- Webhooks de Escrituração (/documentation/escrituracao/webhooks-escrituracao)
- Aprovação de Reserva (/documentation/garantia_veicular/aprovacao_reserva)
- Cancelamento (/documentation/garantia_veicular/cancelamento)
- Consultas (/documentation/garantia_veicular/consultas)
- Mapa de Status e Etapas (/documentation/garantia_veicular/mapa_de_status)
- Simulação e Emissão (/documentation/garantia_veicular/simulacao_e_emissao)
- Mocks (Sandbox) (/documentation/garantia_veicular/testes_homologacao)
- Webhooks — Garantia Veicular (/documentation/garantia_veicular/webhooks)
- Alteração de contato de pessoa (/documentation/gestao_de_usuarios/alteracao_de_contato_de_pessoa)
- Alteração de contato de vínculo (/documentation/gestao_de_usuarios/alteracao_de_contato_de_vinculo)
- Editar dados de uma pessoa (/documentation/gestao_de_usuarios/alteracao_de_dados_pessoais)
- Editar endereço de uma pessoa (/documentation/gestao_de_usuarios/alteracao_de_endereco)
- Consultar partes relacionadas a uma conta PJ (/documentation/gestao_de_usuarios/consulta_partes_relacionadas)
- Criação de pessoa (/documentation/gestao_de_usuarios/criacao_de_pessoa)
- Exclusão de vínculo (/documentation/gestao_de_usuarios/exclusao_de_vinculo)
- Inclusão de vínculo (/documentation/gestao_de_usuarios/inclusao_de_vinculo)
- Introdução (/documentation/gestao_de_usuarios/tfa_introducao)
- Consulta de Dados do Benefício (/documentation/guides/INSS/inquiries/dados-do-beneficio)
- Consulta da Lista de Benefícios (/documentation/guides/INSS/inquiries/lista-de-beneficios)
- Consulta Offline de Saldo (/documentation/guides/INSS/inquiries/offline-balance-request)
- Lista de Participantes do CTC (/documentation/guides/INSS/inquiries/participantes-ctc)
- Consulta de Portabilidade de Origem (/documentation/guides/INSS/inquiries/portabilidade-de-origem)
- Última Resposta da Averbação (/documentation/guides/INSS/inquiries/ultima-resposta)
- Crédito Consignado INSS (/documentation/guides/INSS/intro)
- Mocks (Sandbox) (/documentation/guides/INSS/mocks-sandbox)
- Emissão da Operação (/documentation/guides/INSS/new-credit-and-refinancing/emissao)
- Novo e Refin Puro (/documentation/guides/INSS/new-credit-and-refinancing/end-to-end)
- Envio de Documentos e Formalização (/documentation/guides/INSS/new-credit-and-refinancing/formalizacao)
- Falha no Desembolso e Reapresentação (/documentation/guides/INSS/new-credit-and-refinancing/pos-desembolso)
- Recálculo (/documentation/guides/INSS/new-credit-and-refinancing/recalculate)
- Simulação da Dívida (/documentation/guides/INSS/new-credit-and-refinancing/simulacao)
- Anuência (pending confirmation) (/documentation/guides/INSS/pending_confirmation)
- Alterando o Cessionário (/documentation/guides/INSS/portability+refinancing/alterando-cessionario)
- Consultas e Enumeradores (/documentation/guides/INSS/portability+refinancing/consultas-e-enumeradores)
- Correção de Dados da Proposta (/documentation/guides/INSS/portability+refinancing/correcao-de-dados)
- Diminuir o Valor das Parcelas (/documentation/guides/INSS/portability+refinancing/diminuir-parcela)
- Portabilidade + Refin (/documentation/guides/INSS/portability+refinancing/end-to-end)
- Envio de Documentos e Formalização (/documentation/guides/INSS/portability+refinancing/formalizacao)
- Máquinas de Status (/documentation/guides/INSS/portability+refinancing/maquinas-de-status)
- Digitação da Proposta (/documentation/guides/INSS/portability+refinancing/proposta)
- Recálculo da Portabilidade (/documentation/guides/INSS/portability+refinancing/recalculate-portability)
- Recálculo e Reformalização do Refinanciamento (/documentation/guides/INSS/portability+refinancing/reformalization)
- Simulação da Proposta (/documentation/guides/INSS/portability+refinancing/simulacao)
- Enumeradores (/documentation/guides/INSS/reference/enumeradores)
- Averbação e Desaverbação (/documentation/guides/INSS/reservations/averbacao-e-desaverbacao)
- Fura-fila (priority request) (/documentation/guides/INSS/reservations/priority-request)
- Fila prioritária (/documentation/guides/INSS/reservations/priority-reservation)
- Assinatura em grupo (INSS) (/documentation/guides/INSS/signatures/batch-group-signature)
- Assinatura em lote (INSS) (/documentation/guides/INSS/signatures/batch-signature)
- Consignado Público - Consulta de Margem (/documentation/guides/publico/consulta-de-margem)
- Consignado Público - Emissão (/documentation/guides/publico/credito-novo/emissao)
- Consignado Público - Formalização (/documentation/guides/publico/credito-novo/formalizacao)
- Consignado Público - Simulação (/documentation/guides/publico/credito-novo/simulacao)
- Consignado Público - Entes Consignantes (/documentation/guides/publico/entes)
- Consignado Público - Enumeradores (/documentation/guides/publico/enumeradores)
- Consignado Público - Portabilidade (/documentation/guides/publico/portabilidade)
- Consignado Público - Refinanciamento (/documentation/guides/publico/refinanciamento)
- Consignado Público - Reserva de Margem (/documentation/guides/publico/reserva)
- Consignado Público - Visão Geral (/documentation/guides/publico/visao_geral)
- Consignado Público - Webhooks (/documentation/guides/publico/webhooks)
- Inserção de Documentos (/documentation/iaas/aditamento_recebiveis/envio_documento)
- Introdução (/documentation/iaas/aditamento_recebiveis/inicio)
- Criação de pedido de aditamento (/documentation/iaas/aditamento_recebiveis/pedido_aditamento_contrato)
- Boletador de Títulos Públicos (/documentation/iaas/boletador/boletador_titulos_publicos)
- Listagem de Títulos Públicos (/documentation/iaas/boletador/listagem_titulos_publicos)
- Introdução (/documentation/iaas/boletos/inicio)
- Instruções de Boleto (/documentation/iaas/boletos/instrucoes_boleto)
- Recuperação de Arquivos CNAB (/documentation/iaas/boletos/recuperar_arquivo_retorno)
- Recuperação de Boleto e Segunda via (/documentation/iaas/boletos/recuperar_boleto)
- Recuperação de Boletos (/documentation/iaas/boletos/recuperar_boletos)
- Recuperação de Carteiras de Cobrança (/documentation/iaas/boletos/recuperar_carteiras_cobranca)
- Recuperação de Configurações de Boleto (/documentation/iaas/boletos/recuperar_configuracoes_boleto)
- Webhooks (/documentation/iaas/boletos/webhook)
- Carteira - Aprovação (/documentation/iaas/composicao_carteira/aprovar_carteira)
- Carteira - Baixar a Carteira (/documentation/iaas/composicao_carteira/baixar_carteira)
- Introdução (/documentation/iaas/composicao_carteira/inicio)
- Carteira - Recuperação da Carteira (/documentation/iaas/composicao_carteira/recuperar_carteira)
- Consulta de Aplicações Financeiras por Classe de Fundo (/documentation/iaas/cotas_de_fundo/consulta_paginada_aplicacoes_financeiras)
- Consulta de Resgates por Classe de Fundo (/documentation/iaas/cotas_de_fundo/consulta_paginada_resgates)
- Consulta de Séries de Emissão (/documentation/iaas/cotas_de_fundo/consulta_paginada_series_de_emissao)
- Consulta de Posições em Cotas de Fundo (/documentation/iaas/cotas_de_fundo/consulta_posicoes_cotas_de_fundo)
- Introdução (/documentation/iaas/cotas_de_fundo/inicio)
- Criar Aplicação Financeira (/documentation/iaas/cotas_de_fundo/operacao_aplicacoes_financeiras)
- Criar Pedido de Resgate (/documentation/iaas/cotas_de_fundo/operacao_resgates)
- Consulta de despesas consolidadas (/documentation/iaas/despesas/despesa_consolidada/consulta_despesas)
- Atualização do Contrato (/documentation/iaas/despesas/submissao_despesa/contrato/atualizacao)
- Cancelamento do Contrato (/documentation/iaas/despesas/submissao_despesa/contrato/cancelamento)
- Criação do Contrato (/documentation/iaas/despesas/submissao_despesa/contrato/criacao)
- Listagem de Contratos (/documentation/iaas/despesas/submissao_despesa/contrato/listagem)
- Consulta de Contrato (/documentation/iaas/despesas/submissao_despesa/contrato/recuperacao)
- Submissão do Contrato (/documentation/iaas/despesas/submissao_despesa/contrato/submissao)
- Atualização da Despesa (/documentation/iaas/despesas/submissao_despesa/despesa/atualizacao)
- Cancelamento da Despesa (/documentation/iaas/despesas/submissao_despesa/despesa/cancelamento)
- Criação da Despesa (/documentation/iaas/despesas/submissao_despesa/despesa/criacao)
- Listagem de Despesas (/documentation/iaas/despesas/submissao_despesa/despesa/listagem)
- Consulta de Despesa (/documentation/iaas/despesas/submissao_despesa/despesa/recuperacao)
- Submissão da Despesa (/documentation/iaas/despesas/submissao_despesa/despesa/submissao)
- Listagem de Documentos (/documentation/iaas/despesas/submissao_despesa/documentos/listagem)
- Upload de Documentos (/documentation/iaas/despesas/submissao_despesa/documentos/upload)
- Fluxo de submissão de despesas (/documentation/iaas/despesas/submissao_despesa/fluxo_despesas)
- Anotações da Análise (/documentation/iaas/despesas/submissao_despesa/fornecedor/anotacoes)
- Atualização de Dados da Análise (/documentation/iaas/despesas/submissao_despesa/fornecedor/atualizacao)
- Cancelamento da Análise (/documentation/iaas/despesas/submissao_despesa/fornecedor/cancelamento)
- Cadastro de Fornecedor (/documentation/iaas/despesas/submissao_despesa/fornecedor/criacao)
- Documentos da Análise (/documentation/iaas/despesas/submissao_despesa/fornecedor/documentos)
- Consulta de Fornecedores e Análises (/documentation/iaas/despesas/submissao_despesa/fornecedor/listagem)
- Submissão para Análise (/documentation/iaas/despesas/submissao_despesa/fornecedor/submissao)
- Submissão de Despesas (/documentation/iaas/despesas/submissao_despesa/inicio)
- Emissões - Integralização (/documentation/iaas/emissoes/cadastrar_boleta)
- Cadastro de Ativos - Emissões (/documentation/iaas/emissoes/cadastro_ativo)
- Confirmação de Emissão (/documentation/iaas/emissoes/confirmacao_emissao)
- Introdução (/documentation/iaas/emissoes/inicio)
- Apontamentos de Compliance (/documentation/iaas/homologacao_cedente/cadastro/apontamentos)
- Atualização de Cadastro (/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro)
- Definição de Assinantes (/documentation/iaas/homologacao_cedente/cadastro/definicao_de_assinantes)
- Envio para Análise (/documentation/iaas/homologacao_cedente/cadastro/disparo_da_analise)
- Envio de Cadastro (/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro)
- Envio de Documentos (/documentation/iaas/homologacao_cedente/cadastro/envio_de_documentos)
- Cadastro de Filiais (/documentation/iaas/homologacao_cedente/cadastro/filiais)
- Contas do cedente (/documentation/iaas/homologacao_cedente/cadastro/manutencao_de_contas)
- Webhooks (/documentation/iaas/homologacao_cedente/cadastro/webhooks_analise)
- Consulta de Análise (/documentation/iaas/homologacao_cedente/consulta/consulta_de_analise)
- Consulta de Assinantes (/documentation/iaas/homologacao_cedente/consulta/consulta_de_assinantes)
- Consulta de Cedente (/documentation/iaas/homologacao_cedente/consulta/consulta_de_cedente)
- Ativação do Produto (/documentation/iaas/homologacao_cedente/contrato_de_cessao/ativacao_da_esteira)
- Consultar Documentos (/documentation/iaas/homologacao_cedente/contrato_de_cessao/consulta_de_documentos)
- Manipulação de contrato (/documentation/iaas/homologacao_cedente/contrato_de_cessao/manutencao_do_contrato)
- Contrato de Cessão (/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato)
- Recuperação do Contrato (/documentation/iaas/homologacao_cedente/contrato_de_cessao/recuperacao_de_contrato)
- Webhooks do Contrato (/documentation/iaas/homologacao_cedente/contrato_de_cessao/webhooks_contrato)
- Webhooks do Produto (/documentation/iaas/homologacao_cedente/contrato_de_cessao/webhooks_produto)
- Introdução (/documentation/iaas/homologacao_cedente/inicio)
- Integração via SFTP (/documentation/iaas/integracao_sftp/inicio)
- Recebimento de Webhooks (/documentation/iaas/introducao/autenticacao_webhooks)
- Introdução (/documentation/iaas/introducao/inicio)
- Integração pelo portal (/documentation/iaas/introducao/integracao_via_portal)
- Pacote de Endpoints (/documentation/iaas/introducao/pacote_endpoints)
- Endpoints de teste (/documentation/iaas/introducao/teste_de_autenticacao/endpoints_de_teste)
- Teste de autenticação (/documentation/iaas/introducao/teste_de_autenticacao/)
- Troca de Chaves (/documentation/iaas/introducao/troca_de_chaves)
- Início (/documentation/iaas/investidor/cadastro_investidor/inicio)
- atualizacao_cadastral (/documentation/iaas/investidor/cadastro/atualizacao_cadastral)
- atualizar_status_grupo_assinantes (/documentation/iaas/investidor/cadastro/atualizar_status_grupo_assinantes)
- busca_informacoes_de_uma_analise_cadastral_do_investidor (/documentation/iaas/investidor/cadastro/busca_informacoes_de_uma_analise_cadastral_do_investidor)
- busca_informacoes_do_investidor (/documentation/iaas/investidor/cadastro/busca_informacoes_do_investidor)
- buscar_documentos_para_assinatura (/documentation/iaas/investidor/cadastro/buscar_documentos_para_assinatura)
- Buscar Dados de investidores paginado (/documentation/iaas/investidor/cadastro/buscar_investidores_paginado)
- ciclo_de_vida_da_analise (/documentation/iaas/investidor/cadastro/ciclo_de_vida_da_analise)
- consultar_analise_em_andamento (/documentation/iaas/investidor/cadastro/consultar_analise_em_andamento)
- atualizar_status_conta_bancaria (/documentation/iaas/investidor/cadastro/contas_bancarias/atualizar_status_conta_bancaria)
- definir_conta_principal (/documentation/iaas/investidor/cadastro/contas_bancarias/definir_conta_principal)
- enviar_contas_bancarias (/documentation/iaas/investidor/cadastro/contas_bancarias/enviar_contas_bancarias)
- Criar investidor (/documentation/iaas/investidor/cadastro/criar_investidor)
- definir_grupo_assinantes_padrao (/documentation/iaas/investidor/cadastro/definir_grupo_assinantes_padrao)
- enviar_cadastro_para_analise (/documentation/iaas/investidor/cadastro/enviar_cadastro_para_analise)
- enviar_dados_cadastrais (/documentation/iaas/investidor/cadastro/enviar_dados_cadastrais)
- enviar_endereco (/documentation/iaas/investidor/cadastro/enviar_endereco)
- enviar_grupos_assinantes (/documentation/iaas/investidor/cadastro/enviar_grupos_assinantes)
- enviar_investor_document (/documentation/iaas/investidor/cadastro/enviar_investor_document)
- enviar_patrimonio (/documentation/iaas/investidor/cadastro/enviar_patrimonio)
- consultar_feedback (/documentation/iaas/investidor/cadastro/feedback/consultar_feedback)
- enviar_mensagem_feedback (/documentation/iaas/investidor/cadastro/feedback/enviar_mensagem_feedback)
- listar_feedbacks (/documentation/iaas/investidor/cadastro/feedback/listar_feedbacks)
- Introdução (/documentation/iaas/investidor/cadastro/introducao)
- atualizar_parte_relacionada (/documentation/iaas/investidor/cadastro/related_party/atualizar_parte_relacionada)
- atualizar_status_parte_relacionada (/documentation/iaas/investidor/cadastro/related_party/atualizar_status_parte_relacionada)
- criar_parte_relacionada (/documentation/iaas/investidor/cadastro/related_party/criar_parte_relacionada)
- enviar_documento_parte_relacionada (/documentation/iaas/investidor/cadastro/related_party/enviar_documento_parte_relacionada)
- consultar_formulario_suitability (/documentation/iaas/investidor/cadastro/suitability/consultar_formulario_suitability)
- enviar_suitability (/documentation/iaas/investidor/cadastro/suitability/enviar_suitability)
- atualizacao_cadastral (/documentation/iaas/investidor/carteira_administrada/atualizacao_cadastral)
- atualizar_status_grupo_assinantes (/documentation/iaas/investidor/carteira_administrada/atualizar_status_grupo_assinantes)
- busca_informacoes_de_uma_analise_cadastral_do_investidor (/documentation/iaas/investidor/carteira_administrada/busca_informacoes_de_uma_analise_cadastral_do_investidor)
- busca_informacoes_do_investidor (/documentation/iaas/investidor/carteira_administrada/busca_informacoes_do_investidor)
- buscar_documentos_para_assinatura (/documentation/iaas/investidor/carteira_administrada/buscar_documentos_para_assinatura)
- ciclo_de_vida_da_analise (/documentation/iaas/investidor/carteira_administrada/ciclo_de_vida_da_analise)
- consultar_analise_em_andamento (/documentation/iaas/investidor/carteira_administrada/consultar_analise_em_andamento)
- atualizar_status_conta_bancaria (/documentation/iaas/investidor/carteira_administrada/contas_bancarias/atualizar_status_conta_bancaria)
- definir_conta_principal (/documentation/iaas/investidor/carteira_administrada/contas_bancarias/definir_conta_principal)
- enviar_contas_bancarias (/documentation/iaas/investidor/carteira_administrada/contas_bancarias/enviar_contas_bancarias)
- Criar investidor (/documentation/iaas/investidor/carteira_administrada/criar_investidor)
- definir_grupo_assinantes_padrao (/documentation/iaas/investidor/carteira_administrada/definir_grupo_assinantes_padrao)
- enviar_cadastro_para_analise (/documentation/iaas/investidor/carteira_administrada/enviar_cadastro_para_analise)
- enviar_dados_cadastrais (/documentation/iaas/investidor/carteira_administrada/enviar_dados_cadastrais)
- enviar_endereco (/documentation/iaas/investidor/carteira_administrada/enviar_endereco)
- enviar_grupos_assinantes (/documentation/iaas/investidor/carteira_administrada/enviar_grupos_assinantes)
- enviar_investor_document (/documentation/iaas/investidor/carteira_administrada/enviar_investor_document)
- enviar_patrimonio (/documentation/iaas/investidor/carteira_administrada/enviar_patrimonio)
- consultar_feedback (/documentation/iaas/investidor/carteira_administrada/feedback/consultar_feedback)
- enviar_mensagem_feedback (/documentation/iaas/investidor/carteira_administrada/feedback/enviar_mensagem_feedback)
- listar_feedbacks (/documentation/iaas/investidor/carteira_administrada/feedback/listar_feedbacks)
- Introdução (/documentation/iaas/investidor/carteira_administrada/introducao)
- enviar_documento_investor_owner (/documentation/iaas/investidor/carteira_administrada/investor_owner/enviar_documento_investor_owner)
- atualizar_parte_relacionada (/documentation/iaas/investidor/carteira_administrada/related_party/atualizar_parte_relacionada)
- atualizar_status_parte_relacionada (/documentation/iaas/investidor/carteira_administrada/related_party/atualizar_status_parte_relacionada)
- criar_parte_relacionada (/documentation/iaas/investidor/carteira_administrada/related_party/criar_parte_relacionada)
- enviar_documento_parte_relacionada (/documentation/iaas/investidor/carteira_administrada/related_party/enviar_documento_parte_relacionada)
- consultar_formulario_suitability (/documentation/iaas/investidor/carteira_administrada/suitability/consultar_formulario_suitability)
- enviar_suitability (/documentation/iaas/investidor/carteira_administrada/suitability/enviar_suitability)
- Assinar Documento (/documentation/iaas/investidor/compartilhado/assinar_documento)
- Atualização Cadastral (/documentation/iaas/investidor/compartilhado/atualizacao_cadastral)
- Atualizar Status do Grupo de Assinantes (/documentation/iaas/investidor/compartilhado/atualizar_status_grupo_assinantes)
- Consulta Informações de uma Análise Cadastral do Investidor (/documentation/iaas/investidor/compartilhado/busca_informacoes_de_uma_analise_cadastral_do_investidor)
- Consulta Informações do Investidor (/documentation/iaas/investidor/compartilhado/busca_informacoes_do_investidor)
- Buscar Lotes de Documentos para Assinatura (/documentation/iaas/investidor/compartilhado/buscar_documentos_para_assinatura)
- Ciclo de vida da análise cadastral (/documentation/iaas/investidor/compartilhado/ciclo_de_vida_da_analise)
- Consultar Análise em Andamento (/documentation/iaas/investidor/compartilhado/consultar_analise_em_andamento)
- Adicionar Conta Bancária (/documentation/iaas/investidor/compartilhado/contas_bancarias/adicionar_contas_bancarias)
- Atualizar Conta Bancária (/documentation/iaas/investidor/compartilhado/contas_bancarias/atualizar_conta_bancaria)
- Atualizar Status da Conta Bancária (/documentation/iaas/investidor/compartilhado/contas_bancarias/atualizar_status_conta_bancaria)
- Consultar Contas Bancárias (/documentation/iaas/investidor/compartilhado/contas_bancarias/buscar_contas_bancarias)
- Definir Conta Bancária Principal (/documentation/iaas/investidor/compartilhado/contas_bancarias/definir_conta_principal)
- Enviar Conta Bancária do Investidor (/documentation/iaas/investidor/compartilhado/contas_bancarias/enviar_contas_bancarias)
- Criar investidor (/documentation/iaas/investidor/compartilhado/criar_investidor)
- Definir Grupo de Assinantes Padrão (/documentation/iaas/investidor/compartilhado/definir_grupo_assinantes_padrao)
- Enviar Cadastro do Investidor para Análise (/documentation/iaas/investidor/compartilhado/enviar_cadastro_para_analise)
- Enviar Dados Cadastrais do Investidor (/documentation/iaas/investidor/compartilhado/enviar_dados_cadastrais)
- Enviar Documento Assinado (/documentation/iaas/investidor/compartilhado/enviar_documento_assinado)
- Enviar Endereço do Investidor (/documentation/iaas/investidor/compartilhado/enviar_endereco)
- Enviar Grupo de Assinantes (/documentation/iaas/investidor/compartilhado/enviar_grupos_assinantes)
- Enviar Documento do Investidor (/documentation/iaas/investidor/compartilhado/enviar_investor_document)
- Enviar Patrimônio do Investidor (/documentation/iaas/investidor/compartilhado/enviar_patrimonio)
- Consultar Feedback (/documentation/iaas/investidor/compartilhado/feedback/consultar_feedback)
- Enviar Mensagem em Feedback (/documentation/iaas/investidor/compartilhado/feedback/enviar_mensagem_feedback)
- Listar Feedbacks (/documentation/iaas/investidor/compartilhado/feedback/listar_feedbacks)
- Criar Investor Owner (/documentation/iaas/investidor/compartilhado/investor_owner/criar_investor_owner)
- Enviar Documento de Investor Owner (/documentation/iaas/investidor/compartilhado/investor_owner/enviar_documento_investor_owner)
- Atualizar Parte Relacionada (/documentation/iaas/investidor/compartilhado/related_party/atualizar_parte_relacionada)
- Atualizar Status da Parte Relacionada (/documentation/iaas/investidor/compartilhado/related_party/atualizar_status_parte_relacionada)
- Criar Parte Relacionada (/documentation/iaas/investidor/compartilhado/related_party/criar_parte_relacionada)
- Enviar Documento da Parte Relacionada (/documentation/iaas/investidor/compartilhado/related_party/enviar_documento_parte_relacionada)
- Consultar Formulário Suitability (/documentation/iaas/investidor/compartilhado/suitability/consultar_formulario_suitability)
- Enviar Resposta Suitability (/documentation/iaas/investidor/compartilhado/suitability/enviar_suitability)
- assinar_documento (/documentation/iaas/investidor/distribuicao_externa/assinar_documento)
- atualizacao_cadastral (/documentation/iaas/investidor/distribuicao_externa/atualizacao_cadastral)
- atualizar_status_grupo_assinantes (/documentation/iaas/investidor/distribuicao_externa/atualizar_status_grupo_assinantes)
- busca_informacoes_de_uma_analise_cadastral_do_investidor (/documentation/iaas/investidor/distribuicao_externa/busca_informacoes_de_uma_analise_cadastral_do_investidor)
- busca_informacoes_do_investidor (/documentation/iaas/investidor/distribuicao_externa/busca_informacoes_do_investidor)
- buscar_documentos_para_assinatura (/documentation/iaas/investidor/distribuicao_externa/buscar_documentos_para_assinatura)
- ciclo_de_vida_da_analise (/documentation/iaas/investidor/distribuicao_externa/ciclo_de_vida_da_analise)
- consultar_analise_em_andamento (/documentation/iaas/investidor/distribuicao_externa/consultar_analise_em_andamento)
- atualizar_status_conta_bancaria (/documentation/iaas/investidor/distribuicao_externa/contas_bancarias/atualizar_status_conta_bancaria)
- definir_conta_principal (/documentation/iaas/investidor/distribuicao_externa/contas_bancarias/definir_conta_principal)
- enviar_contas_bancarias (/documentation/iaas/investidor/distribuicao_externa/contas_bancarias/enviar_contas_bancarias)
- Criar investidor (/documentation/iaas/investidor/distribuicao_externa/criar_investidor)
- definir_grupo_assinantes_padrao (/documentation/iaas/investidor/distribuicao_externa/definir_grupo_assinantes_padrao)
- enviar_cadastro_para_analise (/documentation/iaas/investidor/distribuicao_externa/enviar_cadastro_para_analise)
- Enviar Dados Cadastrais do Investidor (/documentation/iaas/investidor/distribuicao_externa/enviar_dados_cadastrais)
- enviar_documento_assinado (/documentation/iaas/investidor/distribuicao_externa/enviar_documento_assinado)
- enviar_endereco (/documentation/iaas/investidor/distribuicao_externa/enviar_endereco)
- enviar_grupos_assinantes (/documentation/iaas/investidor/distribuicao_externa/enviar_grupos_assinantes)
- Enviar Documento do Investidor (/documentation/iaas/investidor/distribuicao_externa/enviar_investor_document)
- enviar_patrimonio (/documentation/iaas/investidor/distribuicao_externa/enviar_patrimonio)
- Enviar Suitability (/documentation/iaas/investidor/distribuicao_externa/enviar_suitability)
- consultar_feedback (/documentation/iaas/investidor/distribuicao_externa/feedback/consultar_feedback)
- enviar_mensagem_feedback (/documentation/iaas/investidor/distribuicao_externa/feedback/enviar_mensagem_feedback)
- listar_feedbacks (/documentation/iaas/investidor/distribuicao_externa/feedback/listar_feedbacks)
- Introdução (/documentation/iaas/investidor/distribuicao_externa/introducao)
- criar_investor_owner (/documentation/iaas/investidor/distribuicao_externa/investor_owner/criar_investor_owner)
- enviar_documento_investor_owner (/documentation/iaas/investidor/distribuicao_externa/investor_owner/enviar_documento_investor_owner)
- atualizar_parte_relacionada (/documentation/iaas/investidor/distribuicao_externa/related_party/atualizar_parte_relacionada)
- atualizar_status_parte_relacionada (/documentation/iaas/investidor/distribuicao_externa/related_party/atualizar_status_parte_relacionada)
- criar_parte_relacionada (/documentation/iaas/investidor/distribuicao_externa/related_party/criar_parte_relacionada)
- enviar_documento_parte_relacionada (/documentation/iaas/investidor/distribuicao_externa/related_party/enviar_documento_parte_relacionada)
- Recuperando Informações da Posição do Investidor (/documentation/iaas/investidor/informacoes_posicao_investidor)
- Introdução (/documentation/iaas/investidor/inicio)
- Layout CNAB 444 — Baixa (/documentation/iaas/liquidacao_ativos/arquivo/cnab444_baixa)
- Baixa por Arquivo (/documentation/iaas/liquidacao_ativos/arquivo/inicio)
- Inserção de Liquidações (/documentation/iaas/liquidacao_ativos/ativos/)
- Remoção de Liquidações (/documentation/iaas/liquidacao_ativos/ativos/remocao_liquidacoes)
- Webhooks de Liquidação (/documentation/iaas/liquidacao_ativos/ativos/webhook)
- Fluxo de liquidação de ativos (/documentation/iaas/liquidacao_ativos/fluxo_liquidacao)
- Liquidação de Ativos (/documentation/iaas/liquidacao_ativos/inicio)
- Criação do Lote de Pagamento (/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao)
- Encerrar Inserção no Lote de Pagamento (/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento)
- Listagem de Lotes de Pagamento (/documentation/iaas/liquidacao_ativos/lote_pagamento/listagem)
- Webhooks do Lote de Pagamento (/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook)
- Layout CNAB 444 — Cessão (/documentation/iaas/negociacao_recebiveis/arquivo/cnab444)
- Layout CSV — Contratos Parcelados (/documentation/iaas/negociacao_recebiveis/arquivo/csv_contrato_parcelado)
- Cessão por Arquivo (/documentation/iaas/negociacao_recebiveis/arquivo/inicio)
- Criação de Ativo — CCB (/documentation/iaas/negociacao_recebiveis/asset/criacao_co)
- Criação de Ativo — Contrato Parcelado (/documentation/iaas/negociacao_recebiveis/asset/criacao_contract)
- Criação de Ativo — CTE (/documentation/iaas/negociacao_recebiveis/asset/criacao_cte)
- Criação de Ativo — Contrato Descontado (/documentation/iaas/negociacao_recebiveis/asset/criacao_discounted_contract)
- Criação de Ativo — Duplicata (/documentation/iaas/negociacao_recebiveis/asset/criacao_duplicata)
- Inserção de Ativo para Recompra (/documentation/iaas/negociacao_recebiveis/asset/criacao_repurchased_asset)
- Inserção de Documentos do Ativo (/documentation/iaas/negociacao_recebiveis/asset/documents)
- Consulta de Ativos do Lote (/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos)
- Remoção de Ativos do Lote (/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos)
- Webhooks do Ativo (/documentation/iaas/negociacao_recebiveis/asset/webhooks)
- Aprovação do Gestor (/documentation/iaas/negociacao_recebiveis/assignment/aprovacao)
- Criação do Lote de Cessão (/documentation/iaas/negociacao_recebiveis/assignment/criacao)
- Documentos da Cessão (/documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao)
- Encerrar Inserção de Ativos (/documentation/iaas/negociacao_recebiveis/assignment/fechamento)
- Listagem de Lotes de Cessão (/documentation/iaas/negociacao_recebiveis/assignment/listagem)
- Recuperação do Lote de Cessão (/documentation/iaas/negociacao_recebiveis/assignment/recuperacao)
- Como criar uma cessão? (/documentation/iaas/negociacao_recebiveis/assignment/video_cessao)
- Webhooks do Lote de Cessão (/documentation/iaas/negociacao_recebiveis/assignment/webhooks)
- Fluxo de Cessão (/documentation/iaas/negociacao_recebiveis/fluxo_cessao)
- Cessão de Direitos Creditórios (/documentation/iaas/negociacao_recebiveis/inicio)
- Listagem de Configurações de Cessão (/documentation/iaas/negociacao_recebiveis/listagem)
- Manual de Cessão de Direitos Creditórios (/documentation/iaas/negociacao_recebiveis/manual_api)
- Listagem de Solicitações de Amortização (/documentation/iaas/passivo/amortizacao/listagem)
- Consulta paginada de Aplicação Financeira (/documentation/iaas/passivo/aplicacao_financeira/busca_paginada_aplicacoes_financeiras)
- Consulta paginada de Fechamento das Aplicações Financeiras (/documentation/iaas/passivo/aplicacao_financeira/busca_paginada_fechamento_das_aplicacoes_financeiras)
- Consultar Aplicação Financeira por chave (/documentation/iaas/passivo/aplicacao_financeira/buscar_aplicacao_financeira_por_chave)
- Criar Aplicação Financeira (/documentation/iaas/passivo/aplicacao_financeira/criar_aplicacao_financeira)
- Aprovação manual de bloqueio de cotas (/documentation/iaas/passivo/bloqueio_de_cotas/aprovar_bloqueio_pendente_aprovacao)
- Consultar bloqueio de cotas (/documentation/iaas/passivo/bloqueio_de_cotas/consulta_de_bloqueio_de_cotas)
- Consultar bloqueio de cotas de um investidor (/documentation/iaas/passivo/bloqueio_de_cotas/consulta_de_bloqueio_de_cotas_de_um_investidor)
- Enviar Documento da Garantia (/documentation/iaas/passivo/bloqueio_de_cotas/enviar_documento_da_garantia)
- Enviar Documento do Ativo (/documentation/iaas/passivo/bloqueio_de_cotas/enviar_documento_do_ativo)
- Execução de garantia (/documentation/iaas/passivo/bloqueio_de_cotas/execucao_de_garantia)
- Reduzir bloqueio de cotas (/documentation/iaas/passivo/bloqueio_de_cotas/reduzir_bloqueio_de_cotas)
- Solicitar bloqueio de cotas (/documentation/iaas/passivo/bloqueio_de_cotas/solicitar_bloqueio_de_cotas)
- Webhook de bloqueio de cotas (/documentation/iaas/passivo/bloqueio_de_cotas/webhooks_de_bloqueio_de_cota)
- Consulta paginada de investidores por classe de fundo (/documentation/iaas/passivo/consultas/consulta_investidores_classe_fundo)
- Consulta paginada de posições de cotistas por classe de fundo (/documentation/iaas/passivo/consultas/consulta_posicoes_cotistas_classe_fundo)
- Consulta paginada do Mapa de Evolução de Cotas (/documentation/iaas/passivo/consultas/consultar_mapa_de_evolucao_de_cotas)
- Consulta paginada de Séries de Emissão (/documentation/iaas/passivo/consultas/consultar_todas_series_de_emissao)
- Consulta paginada de Fundos (/documentation/iaas/passivo/consultas/consultar_todos_fundos)
- Enviar Boletim de Subscrição Assinado (/documentation/iaas/passivo/controle_de_oferta/enviar_boletim_de_subscricao_assinado)
- Recuperando Informações sobre Boletim de Subscrição (/documentation/iaas/passivo/controle_de_oferta/informacoes_boletins_de_subscricao)
- Recuperando Informações sobre as Ofertas (/documentation/iaas/passivo/controle_de_oferta/informacoes_das_ofertas)
- Solicitar Boletim de Subscrição (/documentation/iaas/passivo/controle_de_oferta/solicitar_boletim_de_subscricao)
- Recuperando Cotas Públicas (/documentation/iaas/passivo/fundos/cotas_publicas)
- Introdução (/documentation/iaas/passivo/inicio)
- Consulta paginada de negociações em mercado secundário (/documentation/iaas/passivo/mercado_secundario/consulta_negociacoes_mercado_secundario)
- Consultar Pedido de Resgate por chave (/documentation/iaas/passivo/pedido_de_resgate/buscar_pedido_de_resgate_por_chave)
- Consulta paginada de pedidos de resgate por classe de fundo (/documentation/iaas/passivo/pedido_de_resgate/consulta_pedidos_resgate_classe_fundo)
- Consulta paginada de pedidos de resgate por investidor (/documentation/iaas/passivo/pedido_de_resgate/consulta_pedidos_resgate_investidor)
- Criar Pedido de Resgate (/documentation/iaas/passivo/pedido_de_resgate/criar_pedido_de_resgate)
- Enviar Termo de Adesão Assinado (/documentation/iaas/passivo/termo_de_adesao/enviar_termo_de_adesao_assinado)
- Solicitar Termo de Adesão (/documentation/iaas/passivo/termo_de_adesao/solicitar_termo_de_adesao)
- Razão Contábil (/documentation/iaas/relatorios_dtvm/accounting_ledger)
- Composição de Carteira de Ativos (/documentation/iaas/relatorios_dtvm/assets_wallet_composition)
- Composição de Ativos da Cessão (/documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition)
- Lastros da Cessão (/documentation/iaas/relatorios_dtvm/assignment_documents)
- Relatório de Balanço (/documentation/iaas/relatorios_dtvm/balance_report)
- Demonstrativo de Caixa (/documentation/iaas/relatorios_dtvm/cash_account_demonstrative)
- Movimentações de Caixa (/documentation/iaas/relatorios_dtvm/cash_account_demonstrative_movements)
- Aquisição Consolidada de Direitos Creditórios (/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_acquisition_assets)
- Conciliação Consolidada de Direitos Creditórios (/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_conciliation_assets)
- Relatórios DTVM (/documentation/iaas/relatorios_dtvm/)
- Cotas MEC (/documentation/iaas/relatorios_dtvm/quota_mec)
- Testando a Captura de Lastro (/documentation/iaas/relatorios_dtvm/testar_captura_lastro)
- Composição da Carteira (/documentation/iaas/relatorios_dtvm/wallet_composition)
- Webhook de Entrega (/documentation/iaas/relatorios_dtvm/webhook_de_entrega)
- XML ANBIMA (tipos 5 e 401) (/documentation/iaas/relatorios_dtvm/xml_anbima)
- Criação de um ativo a ser recomprado/vendido (/documentation/iaas/venda_ativos/asset/criacao_recompra)
- Aprovação do Gestor (/documentation/iaas/venda_ativos/assignment/aprovacao_recompra)
- Criação de um lote de recompra (/documentation/iaas/venda_ativos/assignment/criacao_recompra)
- Encerrar Inserção de Ativos (/documentation/iaas/venda_ativos/assignment/fechamento_recompra)
- Recompra e Venda de Ativos (/documentation/iaas/venda_ativos/inicio)
- Recuperando Informações da Conta (/documentation/iaas/visibildade_de_caixa/get_accounts)
- Recuperando Transações de uma Conta (/documentation/iaas/visibildade_de_caixa/get_transaction_reversals)
- Recuperando Transações de uma Conta (/documentation/iaas/visibildade_de_caixa/get_transactions)
- Introdução (/documentation/iaas/visibildade_de_caixa/inicio)
- Transferência entre contas do fundo (/documentation/iaas/visibildade_de_caixa/post_internal_transfer)
- Criando Pedido de Estorno (/documentation/iaas/visibildade_de_caixa/post_transaction_reversal)
- Webhooks (/documentation/iaas/visibildade_de_caixa/webhook_transaction_reversal)
- Introdução a Documentação (/documentation/introducao_api_reference)
- Bem Vindo à Seção de Manuais das API's da QI Tech (/documentation/introducao_manuais)
- Bem Vindo à Seção de Manuais das API's da QI Tech (/documentation/introducao_operational_guides)
- Consulta de instituições financeiras (/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras)
- Manual Consignado da Aeronáutica (/documentation/manual_aeronautica/manual_consignado)
- Homologation Roadmap - BNPL (/documentation/manual_bnpl_ecommerce/manual_bnpl)
- Homologation Roadmap - BNPL (/documentation/manual_bnpl_ecommerce/)
- Consulta - Emissão BNPL (/documentation/manual_bnpl_full/emissao/consulta)
- Emissão BNPL (/documentation/manual_bnpl_full/emissao/)
- Simulação - Emissão BNPL (/documentation/manual_bnpl_full/emissao/simulacao)
- Webhooks - Emissão BNPL (/documentation/manual_bnpl_full/emissao/webhooks)
- Estorno BNPL (/documentation/manual_bnpl_full/estorno/)
- Estorno via Amortização — equal_amount e full_settle (/documentation/manual_bnpl_full/estorno/estorno_amortizacao)
- Webhooks - Estorno BNPL (/documentation/manual_bnpl_full/estorno/webhooks)
- Consulta de Valor Presente - Refinanciamento BNPL (/documentation/manual_bnpl_full/refinanciamento/consulta_valor_presente)
- Criação - Refinanciamento BNPL (/documentation/manual_bnpl_full/refinanciamento/criacao)
- Introdução - Refinanciamento BNPL (/documentation/manual_bnpl_full/refinanciamento/introducao)
- Simulação - Refinanciamento BNPL (/documentation/manual_bnpl_full/refinanciamento/simulacao)
- Cenários - Renegociação em Lote BNPL (/documentation/manual_bnpl_full/renegociacao/cenarios)
- Consulta - Renegociação em Lote BNPL (/documentation/manual_bnpl_full/renegociacao/consulta)
- Renegociação com IOF Spread e Desconto Somente Juros - BNPL (/documentation/manual_bnpl_full/renegociacao/iof-spread-e-desconto-juros)
- Proposta de Renegociação em Lote - BNPL (/documentation/manual_bnpl_full/renegociacao/proposta)
- Simulação - Renegociação em Lote BNPL (/documentation/manual_bnpl_full/renegociacao/simulacao)
- Webhooks - Renegociação em Lote BNPL (/documentation/manual_bnpl_full/renegociacao/webhooks)
- Scripts de Integração - BNPL Full (/documentation/manual_bnpl_full/scripts_integracao)
- Manual Cartão Consignado - Changelog (/documentation/manual_cartao_beneficio/changelog)
- Manual Cartão Consignado - Acompanhamento (/documentation/manual_cartao_beneficio/manual_cartao_beneficio_acompanhamento)
- Documentos e Assinatura (/documentation/manual_cartao_beneficio/manual_cartao_beneficio_documentos)
- Manual Cartão Consignado - Criação (/documentation/manual_cartao_beneficio/manual_cartao_beneficio_emissao)
- Gestão de Endereço (/documentation/manual_cartao_beneficio/manual_cartao_beneficio_endereco)
- Manual Cartão Consignado - Webhook (/documentation/manual_cartao_beneficio/manual_cartao_beneficio_webhook)
- Manual Cartão Consignado - Visão Geral (/documentation/manual_cartao_beneficio/visao_geral)
- Manual CertifiQI (/documentation/manual_certifiqi/dc37cf4f-adad-45c5-9251-9c957fb9ce8e)
- Cessão (/documentation/manual_cessao/)
- Conciliação (/documentation/manual_conciliacao/)
- Manual Consignado Privado - Averbação de Novos Empréstimos: Consulta de Reservas (/documentation/manual_consignado_privado/averbacao_novos_emprestimos/consultas)
- Manual Consignado Privado - Averbação de Novos Empréstimos: Enumeradores (/documentation/manual_consignado_privado/averbacao_novos_emprestimos/enumeradores)
- Manual Consignado Privado - Averbação de Novos Empréstimos: Erros de Averbação (/documentation/manual_consignado_privado/averbacao_novos_emprestimos/erros)
- Manual Consignado Privado - Averbação de Novos Empréstimos: Autorização e Averbação (/documentation/manual_consignado_privado/averbacao_novos_emprestimos/tecnico)
- Manual Consignado Privado - Averbação de Novos Empréstimos: Regras de Negócio (/documentation/manual_consignado_privado/averbacao_novos_emprestimos/visao_geral)
- Manual Consignado Privado - Formalização Externa (/documentation/manual_consignado_privado/manual_assinatura_externa)
- Manual Consignado Privado - Acompanhamento da Operação de crédito (/documentation/manual_consignado_privado/manual_assinatura_leilao)
- Manual Consignado Privado - Averbação e Desembolso (/documentation/manual_consignado_privado/manual_averbacao_desembolso)
- Manual Consignado Privado - Configuração dos Filtros de Recebimento de Propostas de Leilão (/documentation/manual_consignado_privado/manual_configuracao_filtros)
- Manual Consignado Privado - Consulta de Escriturações (/documentation/manual_consignado_privado/manual_consultas_conciliacao)
- Manual Consignado Privado - Consultas do Trabalhador (/documentation/manual_consignado_privado/manual_consultas_trabalhador)
- Manual Consignado Privado - Contratos Legados (/documentation/manual_consignado_privado/manual_contratos_legados)
- Manual Consignado Privado - Crédito Novo (/documentation/manual_consignado_privado/manual_credito_novo)
- Manual Consignado Privado - Fluxo Ativo de Emissão (/documentation/manual_consignado_privado/manual_detalhamento_fluxo_ativo)
- Manual Consignado Privado - Fluxo de Emissão Via Leilão (/documentation/manual_consignado_privado/manual_detalhamento_fluxo_leilao)
- Manual Consignado Privado - Leilão Interno (/documentation/manual_consignado_privado/manual_leilao_interno)
- Manual Consignado Privado - Refinanciamento (/documentation/manual_consignado_privado/manual_refinanciamento)
- Seguro (/documentation/manual_consignado_privado/manual_seguro)
- Manual Consignado Privado - Tombamento do Legado (/documentation/manual_consignado_privado/manual_tombamento_legado)
- Manual Consignado Privado - Portabilidade: Consultas Prévias (/documentation/manual_consignado_privado/portabilidade/consultas)
- Manual Consignado Privado - Portabilidade: Consultas e Operações Pós-Proposta (/documentation/manual_consignado_privado/portabilidade/consultas_pos_proposta)
- Manual Consignado Privado - Portabilidade: Enumeradores (/documentation/manual_consignado_privado/portabilidade/enumeradores)
- Manual Consignado Privado - Portabilidade: Formalização (/documentation/manual_consignado_privado/portabilidade/formalizacao)
- Manual Consignado Privado - Portabilidade: Acompanhamento da Operação (/documentation/manual_consignado_privado/portabilidade/maquina_de_status)
- Manual Consignado Privado - Portabilidade: Mocks e Sandbox (/documentation/manual_consignado_privado/portabilidade/mocks_sandbox)
- Manual Consignado Privado - Portabilidade: Digitação da Proposta (/documentation/manual_consignado_privado/portabilidade/proposta)
- Manual Consignado Privado - Portabilidade: Simulação (/documentation/manual_consignado_privado/portabilidade/simulacao)
- Manual Consignado Privado - Portabilidade + Refinanciamento (/documentation/manual_consignado_privado/portabilidade/visao_geral)
- Manual Consignado Privado - Movimentação de Vínculos: Consulta de Reservas (/documentation/manual_consignado_privado/vinculos_empregaticios/consultas)
- Manual Consignado Privado - Movimentação de Vínculos: Enumeradores (/documentation/manual_consignado_privado/vinculos_empregaticios/enumeradores)
- Manual Consignado Privado - Movimentação de Vínculos: Webhooks de Movimentação (/documentation/manual_consignado_privado/vinculos_empregaticios/movimentacao_de_vinculos)
- Manual Consignado Privado - Movimentação de Vínculos: Averbação por Revínculo (/documentation/manual_consignado_privado/vinculos_empregaticios/revinculo)
- Manual Consignado Privado - Movimentação de Vínculos: Regras de Negócio (/documentation/manual_consignado_privado/vinculos_empregaticios/visao_geral)
- Manual de Consulta de Autorização FGTS (/documentation/manual_consulta_de_autorizacao_FGTS/)
- Consulta - Emissão Crédito Clean (/documentation/manual_credito_clean/emissao/consulta)
- Consulta de Cessão (/documentation/manual_credito_clean/emissao/consulta_cessao)
- Emissão Crédito Clean (/documentation/manual_credito_clean/emissao/)
- Emissão com Assinatura Posterior (/documentation/manual_credito_clean/emissao/emissao_dois_passos)
- Emissão com Assinatura Imediata (/signed_debt) (/documentation/manual_credito_clean/emissao/emissao_signed_debt)
- Simulação - Emissão Crédito Clean (/documentation/manual_credito_clean/emissao/simulacao)
- Webhooks - Emissão Crédito Clean (/documentation/manual_credito_clean/emissao/webhooks)
- Estorno Crédito Clean (/documentation/manual_credito_clean/estorno/)
- Webhooks - Estorno Crédito Clean (/documentation/manual_credito_clean/estorno/webhooks)
- Notificações - Crédito Clean (/documentation/manual_credito_clean/notificacoes)
- Consulta de Valor Presente - Refinanciamento Crédito Clean (/documentation/manual_credito_clean/refinanciamento/consulta_valor_presente)
- Criação - Refinanciamento Crédito Clean (/documentation/manual_credito_clean/refinanciamento/criacao)
- Introdução - Refinanciamento Crédito Clean (/documentation/manual_credito_clean/refinanciamento/introducao)
- Simulação - Refinanciamento Crédito Clean (/documentation/manual_credito_clean/refinanciamento/simulacao)
- Cenários - Renegociação em Lote Crédito Clean (/documentation/manual_credito_clean/renegociacao/cenarios)
- Consulta - Renegociação em Lote Crédito Clean (/documentation/manual_credito_clean/renegociacao/consulta)
- Proposta de Renegociação em Lote - Crédito Clean (/documentation/manual_credito_clean/renegociacao/proposta)
- Simulação - Renegociação em Lote Crédito Clean (/documentation/manual_credito_clean/renegociacao/simulacao)
- Webhooks - Renegociação em Lote Crédito Clean (/documentation/manual_credito_clean/renegociacao/webhooks)
- Scripts de Integração - Crédito Clean (/documentation/manual_credito_clean/scripts_integracao)
- Emissão de Dívida PJ com Assinatura Imediata (/documentation/manual_emissao_pj_signed_debt/emissao_signed_debt_pj)
- Assinatura em Lote (/documentation/manual_exercito/assinatura-em-lote)
- Cancelamento, Desaverbação e Reversal (/documentation/manual_exercito/cancelamento)
- Consulta de Margem Consignável (/documentation/manual_exercito/consulta-margem)
- Conta Interna para Desembolso (/documentation/manual_exercito/conta-interna-desembolso)
- Modelos de Formalização (/documentation/manual_exercito/formalizacao)
- Consignado do Exército — Introdução (/documentation/manual_exercito/introducao)
- Mapa de Status (/documentation/manual_exercito/mapa-de-status)
- Margem Livre (Crédito Novo) (/documentation/manual_exercito/margem-livre)
- Mocks (Sandbox) (/documentation/manual_exercito/mocks-sandbox)
- Portabilidade + Refinanciamento (/documentation/manual_exercito/portabilidade-refin)
- Recálculo e Retentativa de Averbação (/documentation/manual_exercito/recalculo)
- Webhooks (/documentation/manual_exercito/webhooks)
- Manual Saque Aniversário - FGTS (/documentation/manual_FGTS/)
- Manual de Garantia Veicular (/documentation/manual_garantia_veicular/)
- Manual Leilão de propostas Meu INSS (/documentation/manual_leilao_meu_inss/)
- Portabilidade Out - Evidências de rentenção (/documentation/manual_portabilidade/evidencias_de_retencao)
- Portabilidade Out (/documentation/manual_portabilidade/portabilidade_out)
- QI Cartões - Pré-pago (/documentation/manual_pre_pago/casos_uso)
- Manual Previdência Privada - Averbação e Desembolso (/documentation/manual_previdencia_privada/manual_previdencia_privada_averbacao_desembolso)
- Manual Previdência Privada - Consulta (/documentation/manual_previdencia_privada/manual_previdencia_privada_consulta)
- Manual Previdência Privada - Crédito Novo (/documentation/manual_previdencia_privada/manual_previdencia_privada_credito_novo)
- QI FATURA (/documentation/manual_qi_fatura/pix_parcelado)
- Manual QI Sign (/documentation/manual_qi_sign/)
- Aprovar transferência (/documentation/movimentacao_de_contas/aprovar_transferencia)
- Comprovante de transferência (/documentation/movimentacao_de_contas/comprovante_de_transferencia)
- Consulta de Transações (/documentation/movimentacao_de_contas/consulta_de_transacoes)
- Consulta de transações pendentes (/documentation/movimentacao_de_contas/consulta_de_transacoes_pendentes)
- Consulta de extrato (/documentation/movimentacao_de_contas/consulta_de_transferencias_realizadas)
- Realizar transferência (/documentation/movimentacao_de_contas/realizar_transferencia)
- Simulação de cenários (/documentation/movimentacao_de_contas/transacao)
- Webhooks (/documentation/movimentacao_de_contas/webhook_movimentacoes)
- Configuração de notificação (/documentation/notificacoes/configuracao_de_notificacao)
- Configuração de template (/documentation/notificacoes/configuracao_template)
- Gerenciamento de Notificações Personalizadas (/documentation/notificacoes/introducao)
- Reenvio de Notificações (/documentation/notificacoes/reenvio_de_notificacoes)
- Templates (/documentation/notificacoes/template)
- Eventos (/documentation/notificacoes/tipos_de_evento)
- Objeto Address (/documentation/objetos_compartilhados/address)
- Objeto Borrower (/documentation/objetos_compartilhados/borrower)
- Objeto Disbursement Account (/documentation/objetos_compartilhados/disbursement_account)
- Objeto Financial Institution (/documentation/objetos_compartilhados/financial_institution)
- Manual Operacional de Boletos (/documentation/operational_guide/boletos)
- Criação de uma chave pix para um Alias (/documentation/pix_indireto/chaves_pix/criacao_de_chaves)
- Deleção de chave Pix de um Alias (/documentation/pix_indireto/chaves_pix/deletar_chaves)
- Introdução a gestao de chaves PIX para um Alias (/documentation/pix_indireto/chaves_pix/introducao_chaves_pix)
- Listagem de chaves Pix de um Alias (/documentation/pix_indireto/chaves_pix/listar_chaves)
- Cancelar Solicitação de Devolução (/documentation/pix_indireto/devolucao/cancelar_devolucao)
- Consultar Solicitação de Devolução (/documentation/pix_indireto/devolucao/consultar_devolucao)
- Abrir Solicitação de Devolução (/documentation/pix_indireto/devolucao/criar_devolucao)
- Fechar Solicitação de Devolução (/documentation/pix_indireto/devolucao/fechar_devolucao)
- Listar Solicitações de Devolução (/documentation/pix_indireto/devolucao/listar_solicitacoes)
- Introdução ao fluxo de Devolução (/documentation/pix_indireto/devolucao/maquina_estados)
- Simulação de Cenários (/documentation/pix_indireto/devolucao/simulacao_de_cenarios)
- Receber Solicitação de Devolução (/documentation/pix_indireto/devolucao/webhooks_devolucao)
- Consulta de uma entidade Alias (/documentation/pix_indireto/gerenciamento_de_alias/consultar_alias)
- Consulta de Alias por Request Control Key (/documentation/pix_indireto/gerenciamento_de_alias/consultar_request_control_key)
- Criação de uma entidade Alias (/documentation/pix_indireto/gerenciamento_de_alias/criacao_de_alias)
- Deleção de uma entidade Alias (/documentation/pix_indireto/gerenciamento_de_alias/deletar_alias)
- Introdução à entidade de Alias (/documentation/pix_indireto/gerenciamento_de_alias/introducao_alias)
- Listagem de Alias (/documentation/pix_indireto/gerenciamento_de_alias/listagem_de_alias)
- Introdução (/documentation/pix_indireto/introducao)
- Chaves PIX mockadas em ambiente de sandbox (/documentation/pix_indireto/movimentacoes/chaves_pix_mockadas)
- Consulta de Dados de Chave Pix no Banco Central (/documentation/pix_indireto/movimentacoes/consultar_chave_pix)
- Consultar Transação Pix (/documentation/pix_indireto/movimentacoes/consultar_pix)
- Efetuar devolução de um Pix (/documentation/pix_indireto/movimentacoes/devolucao_pix)
- Introdução à movimentações no âmbito do PIX (/documentation/pix_indireto/movimentacoes/introducao_movimentacoes)
- Simulação de cenários (/documentation/pix_indireto/movimentacoes/simulacao)
- Efetuar Transferencia Assíncrona para Pix Manual (/documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_manual)
- Efetuar Transferencia Assíncrona via Chave Pix (/documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_normal)
- Efetuar Transferencia Assíncrona para Pix Qr Code (/documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_qr_code)
- Transação Pix por Chave Pix (/documentation/pix_indireto/movimentacoes/transacao/transacao_pix_chave_sync)
- Transação Pix Manual (/documentation/pix_indireto/movimentacoes/transacao/transacao_pix_manual_sync)
- Transação Pix por QR Code (/documentation/pix_indireto/movimentacoes/transacao/transacao_pix_qr_code_sync)
- Webhook para Devoluções de Pix (/documentation/pix_indireto/movimentacoes/webhook/webhook_devolucao_outgoing_pix)
- Webhook para Pix de Entrada (/documentation/pix_indireto/movimentacoes/webhook/webhook_incoming_pix)
- Webhook para Transações Pendentes (/documentation/pix_indireto/movimentacoes/webhook/webhook_transacao)
- Cancelar um Pedido de Portabilidade (/documentation/pix_indireto/portabilidade/cancelar_pedido_de_portabilidade)
- Completa um Pedido de Portabilidade (/documentation/pix_indireto/portabilidade/completar_pedido_de_portabilidade)
- Confirmar um Pedido de Portabilidade (/documentation/pix_indireto/portabilidade/confirmar_pedido_de_portabilidade)
- Consultar Pedidos de Portabilidade (/documentation/pix_indireto/portabilidade/consultar_pedido_de_portabilidade)
- Criação de um Pedido de Portabilidade (/documentation/pix_indireto/portabilidade/criar_pedido_de_portabilidade)
- Introdução a Pedidos de Portabilidade (/documentation/pix_indireto/portabilidade/introducao_portabilidade)
- Consultar Pedidos de Portabilidade de um Alias (/documentation/pix_indireto/portabilidade/listar_pedidos_de_portabilidade_de_um_alias)
- Webhook Atualização de Portabilidade (/documentation/pix_indireto/portabilidade/webhook/webhook_atualizacao_do_pedido_de_portabilidade)
- Webhook Registro Externo de Portabilidade (/documentation/pix_indireto/portabilidade/webhook/webhook_receber_registro_externo_de_portabilidade)
- Consultar um QR Code Pix (/documentation/pix_indireto/qr_code/consultar_qr_code)
- Criar QR Code Pix dinâmico com vencimento (/documentation/pix_indireto/qr_code/Criar QR Code/criar_qr_code_dinamico_com_vencimento)
- Criar QR Code Pix dinâmico pagamento imediato (/documentation/pix_indireto/qr_code/Criar QR Code/criar_qr_code_dinamico_imediato)
- Criar QR Code Pix Estático (/documentation/pix_indireto/qr_code/Criar QR Code/criar_qr_code_estatico)
- Listar QR Codes de um alias (/documentation/pix_indireto/qr_code/decodificar_qr_code)
- Alterar um QR Code Pix (/documentation/pix_indireto/qr_code/desativar_qr_code)
- Introdução QR Code pix (/documentation/pix_indireto/qr_code/introducao_qr_code)
- Listar QR Codes de um alias (/documentation/pix_indireto/qr_code/listar_alias_qr_codes)
- Webhook para Pix de Entrada de pagamento de QR Code (/documentation/pix_indireto/qr_code/webhook_incoming_pix)
- Cancelar Relato de Infração (/documentation/pix_indireto/relato_de_infracao/cancelar_relato_infracao)
- Consultar Relato de Infração (/documentation/pix_indireto/relato_de_infracao/consultar_relato_infracao)
- Abrir Relato de Infração (/documentation/pix_indireto/relato_de_infracao/criar_relato_infracao)
- Fechar Relato de Infração (/documentation/pix_indireto/relato_de_infracao/fechar_relato_infracao)
- Listar Relatos de Infração (/documentation/pix_indireto/relato_de_infracao/listar_relatos)
- Introdução ao fluxo de Relato de Infração (/documentation/pix_indireto/relato_de_infracao/maquina_estados)
- Simulação de Cenários (/documentation/pix_indireto/relato_de_infracao/simulacao_de_cenarios)
- Receber Relato de Infração (/documentation/pix_indireto/relato_de_infracao/webhooks_relato_infracao)
- Pix (/documentation/pix_v2)
- Aprovar transferência (/documentation/pix/2fa/aprovar_solicitacao_de_transferencia)
- Solicitar devolução de um Pix (/documentation/pix/2fa/solicitar_chargeback_pix)
- Solicitar Token de Aprovação da Transferência (/documentation/pix/2fa/solicitar_token_de_aprovacao)
- Solicitar Transferência Pix (/documentation/pix/2fa/solicitar_transferencia)
- Aprovar solicitação de transferência (/documentation/pix/aprovar_solicitacao_de_transferencia)
- Consulta de Dados de Chave Pix no Banco Central (/documentation/pix/baas_v2/consultar_chave_pix)
- Baixar QR Code Pix dinâmico (/documentation/pix/baixar_qr_code_dinamico)
- Busca por solicitação de limite Pix (/documentation/pix/busca_por_solicitacao_de_limite_pix)
- Busca por uso de limite Pix (/documentation/pix/busca_por_uso_de_limite_pix)
- Chaves PIX mockadas em ambiente de sandbox (/documentation/pix/chaves_pix_mockadas)
- Comprovante de transação (/documentation/pix/comprovante_de_transferencia)
- Comprovante de transferência agendada (/documentation/pix/comprovante_de_transferencia_agendada)
- Consultar chaves Pix (/documentation/pix/consultar_chave)
- Consultar chaves Pix (/documentation/pix/consultar_chave_v2)
- Criar Chave Pix (/documentation/pix/criar_chave)
- Criar QR Code Pix dinâmico (/documentation/pix/criar_qr_code_dinamico)
- Criar QR Code Estático (/documentation/pix/criar_qr_code_estatico)
- Decodificar QR Code Pix (/documentation/pix/decodificar_qr_code)
- Excluir chave Pix (/documentation/pix/excluir_chave)
- Introdução (/documentation/pix/introducao)
- Listar chaves Pix de uma conta (/documentation/pix/listar_chaves_pix)
- MED 2.0 — Consultar Recuperações de Valores (/documentation/pix/med/consultar_recuperacao_de_valores)
- Mecanismo Especial de Devolução do PIX (MED) (/documentation/pix/med/introducao)
- Recebimento de Pedidos de Devolução (/documentation/pix/med/recebimento_pedidos_de_devolucao)
- MED 2.0 — Recebimento de Recuperação de Valores (/documentation/pix/med/recebimento_recuperacao_de_valores)
- Recebimento de Relatos de Infração (/documentation/pix/med/recebimento_relatos_de_infracao)
- MED 2.0 — Responder Recuperação de Valores (/documentation/pix/med/responder_recuperacao_de_valores)
- Responder Relatos de Infração (/documentation/pix/med/resposta_relatos_de_infracao)
- Pesquisar por QR Code Pix dinâmico próprio (/documentation/pix/pesquisar_por_qr_code_dinamico)
- Pesquisar por transferência Pix de saída (/documentation/pix/pesquisar_por_transferencia_pix_de_saida)
- Conclusão da portabilidade (/documentation/pix/portabilidade/conclusao_de_portabilidade)
- Consulta de portabilidade por conta (/documentation/pix/portabilidade/consulta_de_portabilidade_por_conta)
- Criando um pedido de portabilidade (/documentation/pix/portabilidade/criando_um_pedido_de_portabilidade)
- Deletando um pedido de portabilidade (/documentation/pix/portabilidade/deletando_um_pedido_de_portabilidade)
- Portabilidade (/documentation/pix/portabilidade/recebendo_pedido_de_portabilidade)
- Reenviando a validação de dois fatores (/documentation/pix/portabilidade/reenviando_a_2fa)
- Portabilidade (/documentation/pix/portabilidade/respondendo_pedido_de_portabilidade)
- Simular alteração de status de portabilidade (/documentation/pix/portabilidade/simular_alteracao_de_status_de_portabilidade)
- Simular webhook de conclusão do pedido de portabilidade (/documentation/pix/portabilidade/simular_webhook_de_conclusao)
- Simular webhook de recebimento de um pedido de portabilidade (/documentation/pix/portabilidade/simular_webhook_recebimento)
- Validação de dois fatores (/documentation/pix/portabilidade/validacao_de_dois_fatores)
- Simulação de cenários (/documentation/pix/simulacao)
- Solicitar alteração de limite Pix (/documentation/pix/solicitar_alteracao_de_limite_pix)
- Solicitar devolução de um Pix (/documentation/pix/solicitar_chargeback_pix)
- solicitar_transferencia (/documentation/pix/solicitar_transferencia)
- Webhook por QR Code Pix dinâmico expirado (/documentation/pix/webhook_por_qr_code_expirado)
- Configurando Webhooks (/documentation/primeiros_passos/configurando_webhooks)
- Configurar IP de Integração (/documentation/primeiros_passos/configurar_ip_de_integracao)
- Introdução (/documentation/primeiros_passos/inicio)
- Endpoints de teste (/documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste)
- Possíveis erros (/documentation/primeiros_passos/teste_de_autenticacao/possiveis_erros)
- Exemplo completo de teste de autenticação (/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_completo)
- Teste de autenticação (/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2)
- Validação de Webhooks (/documentation/primeiros_passos/teste_de_autenticacao/webhook_v2)
- Troca de chaves (/documentation/primeiros_passos/troca_de_chaves)
- Consulta de valor presente de uma operação (/documentation/refinanciamento/consulta_de_valor_presente_de_uma_operacao)
- introducao (/documentation/refinanciamento/introducao)
- Simulando um refinanciamento (/documentation/refinanciamento/simulando_refinanciamento)
- Criar um refinanciamento (/documentation/refinanciamento/solicitando_refinanciamento)
- Atualizar regra de movimentação automática (/documentation/regras_de_movimentacao/atualizar_regra_movimentacao)
- Criar regra de movimentação automática (/documentation/regras_de_movimentacao/criar_regra_de_movimentacao)
- Regras de movimentação (/documentation/regras_de_movimentacao/)
- Cancelar uma renegociação (/documentation/renegociacao/cancelar_uma_renegociacao)
- Consultar uma renegociação (/documentation/renegociacao/consultar_uma_renegociacao)
- Criar uma renegociação (/documentation/renegociacao/criacao_de_uma_renegociacao)
- Renegociação internal e external (/documentation/renegociacao/criacao_renegociacao_internal)
- Listar renegociações (/documentation/renegociacao/listar_renegociacoes)
- Pagamento de renegociação (/documentation/renegociacao/pagamento_renegociacao)
- Renegociação em lote (/documentation/renegociacao/renegociacao_em_lote)
- Simulação com valor por parcela (/documentation/renegociacao/simulacao_com_valor_por_parcela)
- Simulação de uma renegociação (/documentation/renegociacao/simulacao_de_uma_renegociacao)
- Update de um pagamento manual (/documentation/renegociacao/update_de_um_pagamento_manual)
- Roteiro de Homologação - Circuito de Compras (/documentation/roteiros_de_homologacao/circuito_dd46f8d3-f078-41ba-a311-55be848f1c69)
- Roteiro de Homologação - BaaS Conta Digital (/documentation/roteiros_de_homologacao/conta_digital)
- Roteiro de Homologação - BaaS Conta Digital com Dupla Autenticação (/documentation/roteiros_de_homologacao/conta_digital_2fa)
- Roteiro de Homologação - BaaS Conta Digital com Dupla Autenticação (/documentation/roteiros_de_homologacao/conta_digital_2fa_baas)
- Roteiro de Homologação - BaaS Conta Digital (/documentation/roteiros_de_homologacao/conta_digital_baas)
- Roteiro de Homologação - BaaS Conta Digital Escrow (/documentation/roteiros_de_homologacao/conta_digital_escrow)
- Roteiro de Homologação - BaaS Conta Digital Escrow (/documentation/roteiros_de_homologacao/conta_digital_escrow_caas)
- Roteiro de Homologação - BaaS Cobrança (/documentation/roteiros_de_homologacao/roteiro_cobranca)
- Roteiro de Homologação - BaaS Conta Digital com Dupla Autenticação (/documentation/roteiros_de_homologacao/roteiro_conta_digital)
- Roteiro de Homologação - BaaS Conta Digital (/documentation/roteiros_de_homologacao/roteiro_conta_digital_d795dc71-05b2-4476-bfbc-07ef247abd90)
- Roteiro de Homologação - Conta Integrada (/documentation/roteiros_de_homologacao/roteiro_conta_integrada)
- Roteiro para construção do Backoffice (/documentation/roteiros_de_homologacao/roteiro_criacao_backoffice_cliente)
- Roteiro de Homologação - BaaS Conta Payments (/documentation/roteiros_de_homologacao/roteiro_payments)
- Roteiro de Homologação - Pix Conta Integrada (/documentation/roteiros_de_homologacao/roteiro_pix_conta_integrada)
- Roteiro de Homologação - Pix indireto (/documentation/roteiros_de_homologacao/roteiro_pix_indireto)
- Roteiro de Homologação - Emissão de dívida PF com desembolso pagando QR Code (/documentation/roteiros_laas/roteiro_00f2a5d3-39c2-4f3d-9234-7d1525daaaf2)
- Roteiro de Homologação - Emissão de dívida PF - Adiantamento de Precatório (/documentation/roteiros_laas/roteiro_5d068423-6094-49e4-b15b-7740038295a8)
- Homologation Roadmap - Credit Pay (/documentation/roteiros_laas/roteiro_cecdd0e2-081a-4590-b571-188c376a7c64)
- APP Integration (/documentation/roteiros_laas/roteiro_e7030e18-a9c7-452b-8236-1cf8edfb4de9)
- Webhooks INSS (/documentation/roteiros_laas/webhooks_inss)
- Consultar saldo disponível (/documentation/saque_aniversario_fgts/consultar_saldo_disponivel)
- Criar operação de crédito (/documentation/saque_aniversario_fgts/criacao_da_operacao)
- Introdução ao Saque Aniversário FGTS (/documentation/saque_aniversario_fgts/introducao)
- roteiro_de_homologacao (/documentation/saque_aniversario_fgts/roteiro_de_homologacao)
- Simulação do valor desejado (/documentation/saque_aniversario_fgts/simulacao_do_valor_desejado)
- Simulação do valor máximo (/documentation/saque_aniversario_fgts/simulacao_do_valor_maximo)
- Webhooks de Consulta de Saldo (/documentation/saque_aniversario_fgts/webhooks_de_consulta_de_saldo)
- Cancelar apólice (/documentation/seguros/apolices/cancelar_apolice)
- Consultar apólice (/documentation/seguros/apolices/consultar_apolice)
- Início (/documentation/seguros/apolices/inicio)
- Listar apólices de um pedido (/documentation/seguros/apolices/listar_apolices)
- Webhooks da Apólice (/documentation/seguros/apolices/webhooks)
- Consultar produto (/documentation/seguros/catalogo/consultar_produto)
- Início (/documentation/seguros/catalogo/inicio)
- Listar produtos (/documentation/seguros/catalogo/listar_produtos)
- Criar cotação (/documentation/seguros/cotacao/criar_cotacao)
- Início (/documentation/seguros/cotacao/inicio)
- Simular faixa de preço (/documentation/seguros/cotacao/simular_precos)
- Consultar extrato (/documentation/seguros/financeiro/consultar_extrato)
- Consultar saldo (/documentation/seguros/financeiro/consultar_saldo)
- Início (/documentation/seguros/financeiro/inicio)
- Listar repasses (/documentation/seguros/financeiro/listar_transferencias)
- Autenticação (/documentation/seguros/introducao/autenticacao)
- Introdução (/documentation/seguros/introducao/inicio)
- Cancelar pedido (/documentation/seguros/pedidos/cancelar_pedido)
- Consultar pedido (/documentation/seguros/pedidos/consultar_pedido)
- Criar pedido (/documentation/seguros/pedidos/criar_pedido)
- Início (/documentation/seguros/pedidos/inicio)
- Listar pedidos (/documentation/seguros/pedidos/listar_pedidos)
- Webhooks do Pedido (/documentation/seguros/pedidos/webhooks)
- Configurando Webhooks (/documentation/seguros/primeiros_passos/seguros_configurando_webhooks)
- Configurar IP de Integração (/documentation/seguros/primeiros_passos/seguros_configurar_ip_de_integracao)
- Troca de chaves (/documentation/seguros/primeiros_passos/seguros_troca_de_chaves)
- Possíveis erros (/documentation/seguros/primeiros_passos/teste_de_autenticacao/seguros_possiveis_erros)
- Exemplo completo de teste de autenticação (/documentation/seguros/primeiros_passos/teste_de_autenticacao/seguros_teste_de_autenticacao_completo)
- Teste de autenticação (/documentation/seguros/primeiros_passos/teste_de_autenticacao/seguros_teste_de_autenticacao_v2)
- Validação de Webhooks (/documentation/seguros/primeiros_passos/teste_de_autenticacao/seguros_webhook_v2)
- Assinatura em Lote (/documentation/siape/assinatura-em-lote)
- Cancelamento, Desaverbação e Reversal (SIAPE) (/documentation/siape/cancelamento)
- Consulta de Margem Consignável (SIAPE) (/documentation/siape/consulta-margem)
- Conta Interna para Desembolso (/documentation/siape/conta-interna-desembolso)
- Modelos de Formalização (SIAPE) (/documentation/siape/formalizacao)
- SIAPE-SIGEPE — Introdução (/documentation/siape/introducao)
- Mapa de Status (/documentation/siape/mapa-de-status)
- Margem Livre (Crédito Novo) (/documentation/siape/margem-livre)
- Mocks (Sandbox) (/documentation/siape/mocks-sandbox)
- Portabilidade + Refinanciamento (/documentation/siape/portabilidade-refin)
- Webhooks (/documentation/siape/webhooks)
- Manual SRCC - Consulta de Condição da Operação (/documentation/srcc/consulta_condicao_operacao)
- Manual SRCC - Introdução (/documentation/srcc/introducao)
- Aprovar Transferência (/documentation/ted/2fa/aprovar_transferencia)
- Solicitar Transferência (/documentation/ted/2fa/solicitar_transferencia)
- TED (/documentation/ted/ted_v2)
- consulta_de_agenda_com_opt_in (/documentation/trava_de_domicilio_bancario/consulta_de_agenda_com_opt_in)
- consulta_de_agenda_sem_opt_in (/documentation/trava_de_domicilio_bancario/consulta_de_agenda_sem_opt_in)
- emissao_de_divida_com_trava_de_agenda (/documentation/trava_de_domicilio_bancario/emissao_de_divida_com_trava_de_agenda)
- introducao (/documentation/trava_de_domicilio_bancario/introducao)
- Abrir lote de tombamento de boletos (/documentation/troca_de_titularidade/abrir_lote)
- Aprovar lote de tombamento de boletos (/documentation/troca_de_titularidade/aprovar_lote)
- Cancelar lote de tombamento de boletos (/documentation/troca_de_titularidade/cancelar_lote)
- Criar lote de tombamento de boletos (/documentation/troca_de_titularidade/criar_lote_batch)
- Incluir boletos em um lote de tombamento (/documentation/troca_de_titularidade/incluir_boletos)
- Introdução (/documentation/troca_de_titularidade/introducao)
- Listar boletos de um lote de tombamento (/documentation/troca_de_titularidade/listar_boletos_lote)
- Listar lotes de tombamento de boletos - destino (/documentation/troca_de_titularidade/listar_lotes_destino)
- Listar lotes de tombamento de boletos - origem (/documentation/troca_de_titularidade/listar_lotes_origem)
- Webhooks de Tombamento de Boletos (/documentation/troca_de_titularidade/notificacoes_webhooks)
- Remover boletos em um lote de tombamento (/documentation/troca_de_titularidade/remover_boletos)
- Enviar lote de tombamento de boletos (/documentation/troca_de_titularidade/validar_lote_e_enviar)
- Consulta de documentos (/documentation/upload_de_documentos/consulta_documents)
- Upload de documentos (/documentation/upload_de_documentos/)
- acg1 (/documentation/webhooks/acg1)
- agenda_de_recebiveis (/documentation/webhooks/agenda_de_recebiveis)
- Webhooks de boletos (/documentation/webhooks/boletos)
- Webhooks de dívida (/documentation/webhooks/dividas)
- Webhooks de gestão de risco (/documentation/webhooks/gestao_de_risco)
- Webhooks de indevidos (/documentation/webhooks/indevidos)
- notificacoes_baas_e_laas (/documentation/webhooks/notificacoes_baas_e_laas)
- Webhooks de pagamento de parcelas (/documentation/webhooks/pagamento_de_parcela)
- Webhooks de parcelas (/documentation/webhooks/parcelas)

---

# Atualização uso de TAC

URL: /documentation/1bb151c7-735f-4449-bd9a-4780be271da8

## Consulta de elegibilidade de CPF

Em posse dos dados de **CPF**, é possível a consulta da elegibilidade do CPF.

### Request

ENDPOINT /debts/borrower/[document_number]/tac_eligibility
MÉTODO GET

### Path Params

| Campo          | Descrição                              | Caracteres |
|---------------|----------------------------------------|------------|
| `document_number`  | Número de CPF do devedor | 11         |

### Response

STATUS 200

Response Body

```json
{
    "eligible": true
}
```

### Descrição
| Campo                        | Tipo   | 
|------------------------------|--------|
| `elegible`            | boleean | 

:::caution Atenção
Para um CPF com o retorno **"eligible": false**, tanto a simulação, quanto a emissão da dívida não serão possíveis com o envio de TAC na lista **rebates**.
:::

 

## Erro de elegibilidade durante a simulação e emissão de dívida
Ao enviar um valor de TAC tanto na simulação quanto na emissão de uma operação, para um CPF não elegível à cobrança de TAC, será retornado um erro síncrono.

STATUS 400

Response Body

```json
{
	"title": "Bad Request",
	"description": "Operation not eligible for tac fee charge. Please do not use this fee type for this borrower.",
	"translation": "Operação não elegível para cobrança de taxa do tipo tac. Por favor, não use esse tipo de fee para esse tomador de crédito.",
	"code": "COP000355"
}
```

## Cancelamento de operações inelegíveis

Em caso de operações simultâneas enviadas com TAC para o mesmo tomador, a primeira a desembolsar forçará o cancelamento das restantes. Dessa forma, será enviado um webhook de cancelamento com o payload abaixo.

Response Body

```json
{
    "webhook_type": "debt",
    "key": "27a099df-4688-43cb-87fa-515b1cf343a5",
    "event_datetime": "2022-09-27 07:03:49",
    "data": {
        "cancel_reason": "Taxa da operação do tipo tac não permitida.",
        "cancel_reason_enumerator": "tac_not_allowed"
    },
    "status": "canceled"
}

```

---

# Troca com Troco SIAPE/EXÉRCITO

URL: /documentation/6fabde14-8ce4-42ac-9f93-28246356e45d

## Consulta da lista de contratos

:::caution Atenção
Essa funcionalidade é **exclusiva** para integrações com a API de exército.
:::

Em posse dos dados de **CPF**, **Matrícula do militar** e a **Token**, o parceiro integrador pode realizar a consulta da lista de contratos do militar disponíveis para compra através do seguinte endpoint:

### Request

ENDPOINT /military_payroll/portability_contracts_report
MÉTODO POST

Request Body

```json
{
    "document_number": "45507529710",
    "registration_code": "146254221",
    "token": "abc1234"
}
```

:::info
 O CPF deve ser informado em formato de texto, com no máximo 11 caracteres, sem ".", sem "-" e alinhado com zeros à esquerda.
:::

#### Request Body Params

| Campo                        | Tipo   | Descrição                                 |
|------------------------------|--------|-------------------------------------------|
| `document_number`            | string | CPF do militar.                           |
| `registration_code`          | string | Matrícula do militar.                     |
| `token`                      | string | Senha do militar.                        |

### Response

ENDPOINT /military_payroll/portability_contracts_report
MÉTODO POST
STATUS 201

Response Body

```json
{
	"portability_contracts_report_key": "3e41a8afb-e1b2-4215-8093-c4b5feab529c" ,
	"status": "pending_search"
}
```

Os dados da consulta de margem serão retornados via webhook.

#### Response Body Params

| Campo                              | Tipo   | Descrição                                                                                                              |
|------------------------------------|--------|------------------------------------------------------------------------------------------------------------------------|
| `portability_contracts_report_key` | string | Chave de identificação da consulta da lista de contratos.                                                              |
| `status`                           | enum   | [Enumeradores de status de consulta da lista de contratos.](#enumeradores-de-status-da-consulta-da-lista-de-contratos) |

#### Enumeradores de Status da Consulta da Lista de Contratos

| Enumerador         | Descrição                                                                   |
|--------------------|-----------------------------------------------------------------------------|
| `pending_search`   | Consulta da lista de contratos pendente de resposta do sistema do exército.  |
| `failed`           | Falha na consulta da lista de contratos.                                       |
 | `succeeded`        | Sucesso na consulta da lista de contratos.        |  

### Consulta com sucesso

O webhook de sucesso será retornado da seguinte forma: 

WEBHOOK_TYPE military_payroll.portability_contracts_report
STATUS succeeded

Body

```json
{
	"webhook_type": "military_payroll.portability_contracts_report.status_change",
	"key": "3e41a8afb-e1b2-4215-8093-c4b5feab529c",
	"event_datetime": "2023-05-28T08:43:29Z",
	"status": "succeeded",
	"data": {
		"document_number": "45507529710",
		"contracts" : [
			{
				"econsig_id": "2361529",
				"installment_amount": 10.0,
				"number_of_installments": 5,
				"number_of_paid_installments": 1,
				"consignatory": "BANCO XPTO", 
				"contract_date": "2022-01-03T15:01:57Z",
				"contract_status": 	"accepted"			
			}
		]
		
	}
}
```

### Consulta com falha

O webhook de falha será retornado da seguinte forma: 

WEBHOOK_TYPE military_payroll.portability_contracts_report
STATUS failed

Body

```json
{
	"webhook_type": "military_payroll.portability_contracts_report.status_change",
	"key": "3e41a8afb-e1b2-4215-8093-c4b5feab529c",
	"event_datetime": "2023-05-28T08:43:29Z",
	"status": "failed",
	"data": { 
		"enumerator": "military_not_found" 
	}
}
```

Cada `enumerator` tem uma descrição mais detalhada e, para facilitar a consulta, a tabela abaixo relaciona ambas as coisas para cada caso.

#### Enumeradores failure_reason

| Enumerador                | Descrição                                                     | Código Zetra |
|---------------------------|---------------------------------------------------------------|--------------|
| contracts_not_found       | Nenhum contrato encontrado para os dados informados           | 294          |
| invalid_registration_code | Matrícula informada não é válida                              | 210          |
| military_blocked          | Consulta não pode ser concluída pois o militar está bloqueado | 352          |
| military_not_found        | Nenhum servidor encontrado para os dados informados           | 293          |

## Simulação da Operação de Crédito Pessoal

Primeiramente é preciso calcular o valor da operação de Crédtio Pessoal necessária para quitar a operação de crédito original.

O valor do saldo devedor da dívida original deve ser informado no campo _**disbursed_amount**_.

:::caution Aviso
A operação deve ser simulada com apenas 1 parcela, desembolso em **D0** e a parcela deve ter seu vencimento para **D+5 dias úteis**, contas a partir da data de desembolso (pagamento) da operação.
:::

### Request

ENDPOINT /debt_simulation
MÉTODO POST

```json title='Request Body'
{
	"borrower": {
		"person_type": "natural"
	},
	"financial": {
		"disbursed_amount": 80492.95,
		"monthly_interest_rate": 0.03,
		"credit_operation_type": "ccb",
		"disbursement_date": "2023-03-17",
		"issue_date": "2023-03-17",
		"fine_configuration": {
			"contract_fine_rate": 0,
			"interest_base": "workdays",
			"monthly_rate": 0
		},
		"interest_grace_period": 0,
		"interest_type": "pre_price_days",
		"number_of_installments": 1,
		"principal_grace_period": 0,
		"first_due_date_delay": 5
	}
}
```

---

## Simulação da Operação de Crédito Consignado do SIAPE/ EXÉRCITO 

A simulação da Operação de Crédito Consignado do SIAPE, deverá simular a quitação do contrato original e o calculo do valor do troco liberado para o cliente em função da margem disponível e taxa do contrato.

Nesta simulação os campos informados terão seus valores atribuidos da seguinte forma:

_**installment_face_value**_ = Valor da margem consignável

_**disbursement_date**_ = **D+5 dias úteis** do momento da simulação

_**due_balance**_ = **total_amount** da 1ª parcela retornada na simulação da Operação de Crédito Pessoal

_**original_deadline**_ = Prazo total em dias da Operação de Crédito Pessoal (5 dias)

:::info IOF
O valor de IOF da Operação de Crédito Consignado do SIAPE, uma vez que ela refinancie a Operação de Crédito Pessoal, corresponderá apenas ao valor do troco liberado ao cliente (dinheiro novo). 
:::

### Request

ENDPOINT /debt_simulation
MÉTODO POST

```json title='Request Body'
{
    "borrower": {
        "person_type": "natural"
    },
    "financial": {
        "first_due_date": "2023-06-10",
        "installment_face_value": 100.0,
        "disbursement_date": "2023-03-22",
        "number_of_installments": 96,
        "monthly_interest_rate": 0.0205,
        "interest_type": "pre_price_days",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0
    },
    "collaterals": [{
        "collateral_type": "federal_payroll/military_payroll"
    }],
    "refinanced_credit_operations": [
        {
            "due_balance": 1250.20,
            "original_deadline": 120
        }
    ]
}
```

O campo _**data.final_disbursement_amount**_ retornado na simulação será o valor do troco pago ao cliente.

---

### Consulta do valor de parcela da operação de Crédito Pessoal

#### Request

ENDPOINT /debt?key=[DEBT-KEY]&eval_present_value=True&calculate_delay=True&calculate_spread=False
MÉTODO GET

:::info Informação
A DEBT-KEY é a chave retornada na resposta da criação da operação (resposta do /debt)
:::

---

## Criação da conta de titularidade do devedor

Antes da digitação das propostas é necessário abrir uma conta para o devedor na QI Tech.

A conta será utilizada para receber o desembolso da Operação de Crédito Pessoal, realizar os pagamentos do saldo devedor da dívida original em outro banco (via Boleto, TED ou Pix).

### Request

ENDPOINT /account
MÉTODO POST

```json title='Request Body'
{
	"is_operation_account": true,
	"account_owner": {
		"address": {
			"city": "São Paulo",
			"complement": "s/c",
			"neighborhood": "Pinheiros",
			"number": "215",
			"postal_code": "12345012",
			"state": "SP",
			"street": "Gilberto Sabino"
		},
		"birth_date": "1961-01-30",
		"document_identification": "261a8fbc-d998-4dd7-8515-ddebb212ae27",
		"is_pep": false,
		"mother_name": "Nome da Mãe do Devedor",
		"nationality": "brasileiro",
		"email": "email@email.com",
		"individual_document_number": "12345678911",
		"name": "Nome do Devedor",
		"phone": {
			"area_code": "11",
			"country_code": "055",
			"number": "900000000"
		},
		"person_type": "natural"
	}
}
```

| Parâmetro                                                    | Descrição                                          |
|--------------------------------------------------------------|----------------------------------------------------|
| **account_owner**                                            | Dados do devedor                                   |
| **is_operation_account**                                     | Indicativo de que a conta é uma conta de operação. |

### Response

ENDPOINT /account
MÉTODO POST

```json title='Response Body'
{
	"data": {
		"account_info": {
			"account_branch": "0001",
			"account_digit": "3",
			"account_number": "1234567",
			"financial_institution_code": "329"
		},
		"account_owner": {
			"document_number": "12345678911",
			"name": "Nome do Devedor"
		}
	},
	"event_datetime": "2023-03-21 12:30:24",
	"key": "8ff1e73f-e87b-4641-99a6-3267030c6034",
	"status": "account_pending_operation",
	"webhook_type": "account"
}
```

:::info
Os dados de conta retornados no /account deverão ser utilizados como conta de desembolso da Operação de Crédito Pessoal
:::

### Erro 5xx ou Timeout 

O fluxo não deve prosseguir enquanto a conta não estiver abertua com sucesso. 
Para os casos de falha, deve ser checado se a conta de fato não foi aberta para o cliente, antes de uma possível retentativa de abertura.

É possível checar se a conta foi aberta para o cliente, listando as conta abertas para um determinado CPF.

#### Request

ENDPOINT /account
MÉTODO POST
PARAMETER owner_document_number, requester_key

| Parâmetro                 | Descrição                          |
|---------------------------|------------------------------------|
| **owner_document_number** | CPF do devedor                     |
| **requester_key**         | É uma chave interna da integração. |

#### Response
STATUS 200

```json title='Response Body'
{
	"data": [{
		...
		"account_branch": "0001",
		...
		"account_digit": "2",
		...
		"account_key": "f600a6a9-0845-454f-b25c-a6d108ea582e",
		"account_name": "Default",
		"account_number": "1467576",
		"account_status": {
			"created_at": "2019-10-11T18:58:31",
			"enumerator": "opened",
			"translation_path": "account.AccountStatus.opened"
		},
		...
		"owner_document_number": "09080702000105",
		"owner_name": "Nome do Devedor",
		...
	}],
	"pagination": {
		"current_page": 1,
		"next_page": null,
		"rows_per_page": 100,
		"total_pages": 1,
		"total_rows": 1
	}
}
```

:::info Informação
No payload de resposta acima, estão listados apenas os campos relevantes para leitura.
:::

---

## Emissão das Operações

A criação das operações de Crédito Pessoal e Crédito Consignado do SIAPE, **deverão ser realizadas no mesmo momento**, tendo cada uma as seguintes configurações

- **Operação de Crédito Pessoal**: Deve ser emitida com desembolso em D0 e com apenas uma parcela com vencimento para **D+5 dias úteis** do desembolso.
- **Operação de Crédito Consignado do SIAPE**: Deve ser emitida com desembolso em **D+0**, mas com opções de desembolso para até **D+15 dias corridos** e com o número de parcelas pretendidas.

:::danger Atenção
Para emissão da Operação de Crédito Pessoal o objeto "_**financial**_", deve ser enviado com exatamente as mesmas informações enviadas na sua simulação.

Para emissão da Operação de Crédito Consignado do SIAPE, o obejeto "_**financial**_" terá as seguintes diferenças:
- O campo _**disbursement_date**_ deve ser substituído pelos campos _**disbursement_start_date**_ e _**disbursement_end_date**_, onde a diferença entre um e outro deve ser de **15 dias corridos**.
- O campo _**refinanced_credit_operations[0].operation_key**_ deve conter a **DEBT-KEY**, retornada no retorno da criação da Operação de Crédito Pessoal. 
:::

:::info Informação
A Operação de Crédito Pessoal, só pode desembolsar em **dias úteis** e nos seguintes horários, à depender do meio de pagamento do saldo devedor da dívida original:
- **TED**: desembolso entre **6:30 e 17:15**
- **Boleto**: desembolso entre **7:00 e 22:00**
- **Pix**: qualquer horário (mas é recomendado o desembolso em horário comercial, pois caso uma operação seja desembolsada de madrugada, por exemplo, a entrada do Pix pode ser rejeitada por suspeitas de fraude)
:::

### Emissão da Operação de Crédito Pessoal

Para emitir a Operação de Crédito Pessoal, é necessário enviar a informação dos Boletos/TEDs/Pix que precisam ser pagos após o desembolso da operação. 

:::caution Atenção
O parceiro deve gerar uma chave interna de identificação da operação e enviá-la na requisição de emissão de dívida no campo "_**requester_identifier_key**_"
:::

#### Exemplos Resquests

ENDPOINT /debt
MÉTODO POST

**Boleto**

```json title='Request Body'
{
	"borrower": {
		"name": "Nome do Devedor",
		"email": "email@email.com",
		"phone": {
			"number": "900000000",
			"area_code": "11",
			"country_code": "055"
		},
		"address": {
			"city": "São Paulo",
			"state": "SP",
			"number": "215",
			"street": "Gilberto Sabino",
			"complement": "s/c",
			"postal_code": "12345012",
			"neighborhood": "Pinheiros"
		},
		"role_type": "issuer",
		"birth_date": "1969-05-01",
		"mother_name": "Nome da Mãe do Devedor",
		"person_type": "natural",
		"individual_document_number": "12345678911",
		"gender": "male",
		"nationality": "brasileiro",
		"is_pep": false,
		"marital_status": "married"
	},
	"financial": {
		"disbursed_amount": 80492.95,
		"annual_interest_rate": 0.20983,
		"credit_operation_type": "ccb",
		"disbursement_date": "2023-03-17",
		"issue_date": "2023-03-17",
		"fine_configuration": {
			"contract_fine_rate": 0,
			"interest_base": "workdays",
			"monthly_rate": 0
		},
		"interest_grace_period": 0,
		"interest_type": "pre_price_days",
		"number_of_installments": 1,
		"principal_grace_period": 0,
		"first_due_date_delay": 5
	},
	"simplified": true,
	"additional_data": {
		"debt_payment": [{
			"bank_slip": [{
                "digitable_line": "10495419967200010004900031456924592920008049295",
                "amount": "80492,95",
                "beneficiary": "CAIXA ECONÔMICA FEDERAL",
                "due_date": "2023-03-17"
            }],
			"funds_transfer": [],
			"pix": [],
			"financial_institution_code_number": "623"
		}],
		"issuer_account": {
			"account_digit": "0",
			"account_branch": "1234",
			"account_number": "123456",
			"financial_institution_code_number": "104"
		},
		"total_af_amount": 86186.52
	},
	"requester_identifier_key": "7ac52492-61c0-4dd6-a414-b0bf940fb7ca",
	"disbursement_bank_account": {
		"bank_code": "329",
		"account_digit": "3",
		"branch_number": "0001",
		"account_number": "1234567"
	},
	"after_disbursement_actions": [{
		"action_data": {
			"digitable_line": "10495419967200010004900031456924592920008049295"
		},
		"action_type": "bankslip_payment"
	}],
	"modality": {
        "code": "0203"
    }
}
```

**TED**

```json title='Request Body'
{
	"borrower": {
		"name": "Nome do Devedor",
		"email": "email@email.com",
		"phone": {
			"number": "900000000",
			"area_code": "11",
			"country_code": "055"
		},
		"address": {
			"city": "São Paulo",
			"state": "SP",
			"number": "215",
			"street": "Gilberto Sabino",
			"complement": "s/c",
			"postal_code": "12345012",
			"neighborhood": "Pinheiros"
		},
		"role_type": "issuer",
		"birth_date": "1969-05-01",
		"mother_name": "Nome da Mãe do Devedor",
		"person_type": "natural",
		"individual_document_number": "12345678911",
		"gender": "male",
		"nationality": "brasileiro",
		"is_pep": false,
		"marital_status": "married"
	},
	"financial": {
		"disbursed_amount": 80492.95,
		"annual_interest_rate": 0.20983,
		"credit_operation_type": "ccb",
		"disbursement_date": "2023-03-17",
		"issue_date": "2023-03-17",
		"fine_configuration": {
			"contract_fine_rate": 0,
			"interest_base": "workdays",
			"monthly_rate": 0
		},
		"interest_grace_period": 0,
		"interest_type": "pre_price_days",
		"number_of_installments": 1,
		"principal_grace_period": 0,
		"first_due_date_delay": 5
	},
	"simplified": true,
	"additional_data": {
		"debt_payment": [{
			"bank_slip": [],
			"funds_transfer": [{
				"amount": "4736,07",
				"account_digit": "0",
				"account_branch": "0897",
				"account_number": "20001",
				"financial_institution_code_number": "341"
			}],
			"pix": [],
			"financial_institution_code_number": "341"
		}],
		"issuer_account": {
			"account_digit": "0",
			"account_branch": "0491",
			"account_number": "100021100",
			"financial_institution_code_number": "104"
		},
		"total_af_amount": 86186.52
	},
	"requester_identifier_key": "7ac52492-61c0-4dd6-a414-b0bf940fb7ca",
	"disbursement_bank_account": {
		"bank_code": "329",
		"account_digit": "3",
		"branch_number": "0001",
		"account_number": "1234567"
	},
	"after_disbursement_actions": [{
		"action_data": {
			"destination": {
				"name": "Nome Credor Original",
				"account_digit": "0",
				"account_branch": "0897",
				"account_number": "20001",
				"document_number": "87163234000138",
				"financial_institution_code_number": "341"
			},
			"transaction_amount": 4736.07
		},
		"action_type": "funds_transfer"
	}],
	"modality": {
        "code": "0203"
    }
}
```

**Chave Pix**

```json title='Request Body'
{
	"borrower": {
		"name": "Nome do Devedor",
		"email": "email@email.com",
		"phone": {
			"number": "900000000",
			"area_code": "11",
			"country_code": "055"
		},
		"address": {
			"city": "São Paulo",
			"state": "SP",
			"number": "215",
			"street": "Gilberto Sabino",
			"complement": "s/c",
			"postal_code": "12345012",
			"neighborhood": "Pinheiros"
		},
		"role_type": "issuer",
		"birth_date": "1969-05-01",
		"mother_name": "Nome da Mãe do Devedor",
		"person_type": "natural",
		"individual_document_number": "12345678911",
		"gender": "male",
		"nationality": "brasileiro",
		"is_pep": false,
		"marital_status": "married"
	},
	"financial": {
		"disbursed_amount": 80492.95,
		"annual_interest_rate": 0.20983,
		"credit_operation_type": "ccb",
		"disbursement_date": "2023-03-17",
		"issue_date": "2023-03-17",
		"fine_configuration": {
			"contract_fine_rate": 0,
			"interest_base": "workdays",
			"monthly_rate": 0
		},
		"interest_grace_period": 0,
		"interest_type": "pre_price_days",
		"number_of_installments": 1,
		"principal_grace_period": 0,
		"first_due_date_delay": 5
	},
	"simplified": true,
	"additional_data": {
		"debt_payment": [{
			"bank_slip": [],
			"funds_transfer": [],
			"pix": [{
				"amount": "4736,07",
				"account_digit": "0",
				"account_branch": "0897",
				"account_number": "20001",
				"financial_institution_code_number": "341",
				"ispb": "60701190"
			}],
			"financial_institution_code_number": "341"
		}],
		"issuer_account": {
			"account_digit": "0",
			"account_branch": "0491",
			"account_number": "100021100",
			"financial_institution_code_number": "104"
		},
		"total_af_amount": 86186.52
	},
	"requester_identifier_key": "7ac52492-61c0-4dd6-a414-b0bf940fb7ca",
	"disbursement_bank_account": {
		"bank_code": "329",
		"account_digit": "3",
		"branch_number": "0001",
		"account_number": "1234567"
	},
	"after_disbursement_actions": [{
		"action_data": {
			"pix_transfer_type": "key",
			"pix_key": "cahvepix@credororiginal.com.br",
			"transaction_amount": 4736.07
		},
		"action_type": "pix"
	}],
	"modality": {
        "code": "0203"
    }
}
```

**Pix Manual**

```json title='Request Body'
{
	"borrower": {
		"name": "Nome do Devedor",
		"email": "email@email.com",
		"phone": {
			"number": "900000000",
			"area_code": "11",
			"country_code": "055"
		},
		"address": {
			"city": "São Paulo",
			"state": "SP",
			"number": "215",
			"street": "Gilberto Sabino",
			"complement": "s/c",
			"postal_code": "12345012",
			"neighborhood": "Pinheiros"
		},
		"role_type": "issuer",
		"birth_date": "1969-05-01",
		"mother_name": "Nome da Mãe do Devedor",
		"person_type": "natural",
		"individual_document_number": "12345678911",
		"gender": "male",
		"nationality": "brasileiro",
		"is_pep": false,
		"marital_status": "married"
	},
	"financial": {
		"disbursed_amount": 80492.95,
		"annual_interest_rate": 0.20983,
		"credit_operation_type": "ccb",
		"disbursement_date": "2023-03-17",
		"issue_date": "2023-03-17",
		"fine_configuration": {
			"contract_fine_rate": 0,
			"interest_base": "workdays",
			"monthly_rate": 0
		},
		"interest_grace_period": 0,
		"interest_type": "pre_price_days",
		"number_of_installments": 1,
		"principal_grace_period": 0,
		"first_due_date_delay": 5
	},
	"simplified": true,
	"additional_data": {
		"debt_payment": [{
			"bank_slip": [],
			"funds_transfer": [],
			"pix": [{
				"amount": "4736,07",
				"account_digit": "0",
				"account_branch": "0897",
				"account_number": "20001",
				"financial_institution_code_number": "341",
				"ispb": "60701190"
			}],
			"financial_institution_code_number": "341"
		}],
		"issuer_account": {
			"account_digit": "0",
			"account_branch": "0491",
			"account_number": "100021100",
			"financial_institution_code_number": "104"
		},
		"total_af_amount": 86186.52
	},
	"requester_identifier_key": "7ac52492-61c0-4dd6-a414-b0bf940fb7ca",
	"disbursement_bank_account": {
		"bank_code": "329",
		"account_digit": "3",
		"branch_number": "0001",
		"account_number": "1234567"
	},
	"after_disbursement_actions": [{
		"action_data": {
			"pix_transfer_type": "manual",
			"target_account": {
			    "name": "Nome Credor Original",
				"account_digit": "0",
				"account_branch": "0897",
				"account_number": "20001",
				"document_number": "87163234000138",
				"financial_institution_code_number": "341"
			},
			"transaction_amount": 4736.07
		},
		"action_type": "pix"
	}],
	"modality": {
        "code": "0203"
    }
}
```
  

**QrCode Pix**

```json title='Request Body'
{
    "borrower": {
		"name": "Nome do Devedor",
		"email": "email@email.com",
		"phone": {
			"number": "900000000",
			"area_code": "11",
			"country_code": "055"
		},
		"address": {
			"city": "São Paulo",
			"state": "SP",
			"number": "215",
			"street": "Gilberto Sabino",
			"complement": "s/c",
			"postal_code": "12345012",
			"neighborhood": "Pinheiros"
		},
		"role_type": "issuer",
		"birth_date": "1969-05-01",
		"mother_name": "Nome da Mãe do Devedor",
		"person_type": "natural",
		"individual_document_number": "12345678911",
		"gender": "male",
		"nationality": "brasileiro",
		"is_pep": false,
		"marital_status": "married"
	},
	"financial": {
		"disbursed_amount": 80492.95,
		"annual_interest_rate": 0.20983,
		"credit_operation_type": "ccb",
		"disbursement_date": "2023-03-17",
		"issue_date": "2023-03-17",
		"fine_configuration": {
			"contract_fine_rate": 0,
			"interest_base": "workdays",
			"monthly_rate": 0
		},
		"interest_grace_period": 0,
		"interest_type": "pre_price_days",
		"number_of_installments": 1,
		"principal_grace_period": 0,
		"first_due_date_delay": 5
	},
	"simplified": true,
	"additional_data": {
		"debt_payment": [{
			"bank_slip": [],
			"funds_transfer": [],
			"pix": [{
				"amount": "4736,07",
				"account_digit": "0",
				"account_branch": "0897",
				"account_number": "20001",
				"financial_institution_code_number": "341",
				"ispb": "60701190"
			}],
			"financial_institution_code_number": "341"
		}],
		"issuer_account": {
			"account_digit": "0",
			"account_branch": "0491",
			"account_number": "100021100",
			"financial_institution_code_number": "104"
		},
		"total_af_amount": 86186.52
	},
	"requester_identifier_key": "7ac52492-61c0-4dd6-a414-b0bf940fb7ca",
	"disbursement_bank_account": {
		"bank_code": "329",
		"account_digit": "3",
		"branch_number": "0001",
		"account_number": "1234567"
	},
	"after_disbursement_actions": [{
		"action_data": {
			"pix_transfer_type": "qr_code",
			"qr_code": "00020126870014br.gov.bcb.pix2565qrcode.qitech.app/bacen/cobv/4ec760c4-b950-4afd-af10-92c1bb7804015204000053039865802BR5925SECURITIZADORA DE CREDITO6009SAO PAULO61080540700362070503***63042FA4"
		},
		"action_type": "pix"
	}],
	"modality": {
        "code": "0203"
    }
}
```
    

#### Enumeradores Marital Status
| Enumerador   | Descrição     |
|--------------|---------------|
| **single**   | Solteiro(a)   |
| **married**  | Casado(a)     |
| **widower**  | Viúvo(a)      |
| **divorced** | Divorciado(a) |

#### Erro 5xx ou Timeout

Caso seja retornado algum 5xx ou Timeout na requisição, afim de certificar que a operação de fato não foi criada na QI, é recomendado que o parceiro realize uma consulta da operação que teve retorno 5xx ou timeout.

ENDPOINT /debt?requester_identifier_key=34427233-925d-416d-93eb-c7f5084e8359
MÉTODO GET

Caso o retorno do GET seja um 200, o parceiro não deve retentar a criação da operação e seguir o fluxo da operação.
Caso seja retornado um 404 - Not Found, o parceiro deve retentar a criação da operação.

STATUS 200

```json title='Response Body'
{
	"data": {
		"additional_iof": 307.166388,
		"annual_cet": "60,4731%",
		"assignment_amount": 80833.26,
		"base_iof": 33.141637696905995,
		"borrower": {
			"document_number": "12345678911",
			"name": "Nome do Devedor"
		},
		"cet": "4,0200%",
		"collaterals": [],
		"contract": {
			"external_contract_key": "351eada5-a626-404c-a3a3-f91c123270ce",
			"number": "0000000001/NDD",
			"signature_information": [{
				"signature_url": "https://sign.qitech.com.br/s/hNrwjda",
				"signer_document_number": "12345678911",
				"signer_email": "email@email.com",
				"signer_external_key": "56d105f3-a7f6-4442-95e9-71f44d2ae5fc",
				"signer_name": "Nome do Devedor",
				"signer_role": "issuer"
			}],
			"urls": [
				"https://storage.googleapis.com/live-doc-api/documents/45e5b9c0-0f56-40a8-aace-d206f72c164d/QISCD-NOME_DO_DEVEDOR-CCB-0001212121-20230317194512.pdf"
			]
		},
		"contract_fee_amount": 0,
		"contract_fees": [],
		"external_contract_fee_amount": 0,
		"external_contract_fees": [],
		"installments": [{
			"accrual_reference_date": null,
			"additional_costs": [],
			"advanced_paid_amount": 0,
			"bank_slip_key": null,
			"business_due_date": "2023-03-22",
			"calendar_days": 5,
			"digitable_line": null,
			"due_date": "2023-03-22",
			"due_interest": 0,
			"due_principal": 80833.26,
			"fine_amount": null,
			"has_interest": true,
			"installment_history": [],
			"installment_key": "75460851-2e82-4e3d-a805-b3e55b6b31d4",
			"installment_number": 1,
			"installment_payment": [],
			"installment_status": "created",
			"installment_type": "principal",
			"original_due_principal": 80833.26,
			"original_pre_fixed_amount": 183.5073246195304,
			"original_principal_amortization_amount": 80833.26267538047,
			"original_total_amount": 81016.77,
			"paid_amount": 0,
			"paid_at": null,
			"post_fixed_amount": 0,
			"pre_fixed_amount": 183.5073246195304,
			"principal_amortization_amount": 80833.26267538047,
			"qr_code_key": null,
			"qr_code_url": null,
			"renegotiation_proposal_key": null,
			"tax_amount": 33.141637696905995,
			"total_accrual_amount": null,
			"total_amount": 81016.77,
			"total_paid_amount": 0,
			"workdays": 3
		}],
		"iof_charge_method": "financed",
		"issue_amount": 80833.26,
		"net_external_contract_fee_amount": 0,
		"number_of_installments": 1,
		"prefixed_interest_rate": {
			"annual_rate": 0.20983,
			"created_at": "2023-03-17T19:45:11",
			"daily_rate": 0.00075616,
			"interest_base": "workdays",
			"monthly_rate": 0.01599997
		},
		"requester_identifier_key": "34427233-925d-416d-93eb-c7f5084e8359",
		"total_iof": 340.31,
		"total_pre_fixed_amount": 183.5073246195304
	},
	"event_datetime": "2023-03-17 19:45:19",
	"key": "052fe83c-37f6-4339-a831-127b50566745",
	"status": "waiting_signature",
	"webhook_type": "debt"
}
```

:::info Informação
O campo "key" da resposta de criação da operação é a **DEBT-KEY**, que é a chave única da operação dentro da QI.
:::

#### Assinatura

**Mesmo procedimento de assinatura ativo para a operação de SIAPE ML**

#### Autorizar desembolso

Após assinatura da operação, é necessário autorizar a operação para desembolso.

:::danger Atenção
A autorização de desembolso da Operação de Crédito Pessoal, deve ser enviada após o recebimento do webhook de confirmação da digitação da proposta no SIAPE. 
:::

ENDPOINT /debt/ [DEBT-KEY] /allow_disbursement
MÉTODO POST

```json title='Request Body'
{
	"allow_disbursement": true
}
```

#### Desembolso

Após ser assinada e autorizada para desembolso, a operação seguirá automaticamente para esteira de desembolso.

Após o desembolso ser processado o parceiro receberá o seguinte webhook:

#### Sucesso no desembolso

WEBHOOK_TYPE debt
STATUS Disbursed

```json title='Webhook Body'
{
	"key": "052fe83c-37f6-4339-a831-127b50566745",
	"data": {
		"installments": [{
			"due_date": "2023-03-22",
			"total_amount": 81016.77,
			"installment_key": "75460851-2e82-4e3d-a805-b3e55b6b31d4",
			"pre_fixed_amount": 183.5073246195304,
			"principal_amortization_amount": 80833.26267538047
		}],
		"ted_receipt_list": []
	},
	"status": "disbursed",
	"webhook_type": "debt",
	"event_datetime": "2023-03-17 13:20:40"
}
```

#### Ações pós-desembolso

Após o desembolso da Operação de Crédito Pessoal na conta do devedor criada na QI, serão executados os pagamentos de boleto/TED/Pix referente à quitação do saldo devedor da dívida original do devedor (ações pós-desembolso)

#### Sucesso

WEBHOOK_TYPE after_disbursement_action_update
STATUS Success

**Boleto**

```json title='Webhook Body'
{
	"key": "3bce3113-3644-4491-b87a-fe6551edff70",
	"data": {
		"status": "done",
		"action_key": "d25097e2-09f1-47fc-8b7f-d1988b1a7669",
		"error_data": null,
		"action_data": {
			"digitable_line": "10495419967200010004900031456924592920008049295"
		},
		"action_type": "bankslip_payment",
		"execution_data": {
			"bank_slip": {
				"payer": {
					"name": "Nome do Devedor",
					"document_number": "12345678911",
					"document_number_formatted": "123.456.789-11"
				},
				"beneficiary": {
					"name": "CAIXA ECONÔMICA FEDERAL",
					"document_number": "00360305000104",
					"document_number_formatted": "00.360.305/0001-04"
				},
				"payment_key": "500a496e-4cca-4b12-9dc8-254932ebbcac",
				"payment_date": "2023-03-08",
				"digitable_line": "10495419967200010004900031456924592920008049295",
				"expiration_date": "2023-03-10",
				"payment_date_formatted": "08/03/2023",
				"expiration_date_formatted": "10/03/2023",
				"financial_institution_name": "CAIXA ECONÔMICA FEDERAL",
				"financial_institution_compe_number": "104"
			},
			"origin_key": "dfac205a-bdef-4820-8608-2dc81d9e10d4",
			"transacted_at": "2023-03-08 16:07:58",
			"source_account": {
				"owner_name": "Nome do Devedor",
				"account_digit": "3",
				"account_branch": "0001",
				"account_number": "1234567",
				"owner_document_number": "12345678911",
				"financial_institution_name": "QI SCD S.A.",
				"owner_document_number_formatted": "123.456.789-11",
				"financial_institution_compe_number": 329
			},
			"source_subtype": "bank_slip_payment",
			"transaction_key": "86a4320d-a69d-4c14-8300-9a6f22d35fcb",
			"transacted_at_br": "2023-03-08 13:07:58",
			"pdf_encoded_string": "\<BASE 64 DO PDF DO COMPROVANTE\>",
			"transaction_amount": 3864.95,
			"transacted_at_formatted": "08/03/2023, 16:07:58",
			"transacted_at_br_formatted": "08/03/2023, 13:07:58",
			"transaction_amount_formatted": "R$ 3.864,95",
			"source_subtype_translation_ptbr": "Pagamento de Boleto"
		}
	},
	"webhook_type": "after_disbursement_action_update",
	"event_datetime": "2023-03-08 16:08:02"
}
```

**TED**

```json title='Webhook Body'
{
	"key": "1f13c154-4164-412d-b3f3-00b7af7b18ee",
	"data": {
		"status": "done",
		"action_key": "a7a2c87d-b882-4680-ae58-9a5292d26788",
		"error_data": null,
		"action_data": {
			"destination": {
				"name": "Nome Credor Original",
				"account_digit": "0",
				"account_branch": "0897",
				"account_number": "20001",
				"document_number": "87163234000138",
				"financial_institution_code_number": "341"
			},
			"transaction_amount": 520
		},
		"action_type": "funds_transfer",
		"execution_data": {
			"origin_key": "f786dc97-faaa-40d8-9818-c8dc184bf131",
			"transacted_at": "2023-03-23 16:48:27",
			"source_account": {
				"owner_name": "Nome do Devedor",
				"account_digit": "3",
				"account_branch": "0001",
				"account_number": "1234567",
				"owner_document_number": "12345678911",
				"financial_institution_name": "QI SCD S.A.",
				"owner_document_number_formatted": "123.456.789-11",
				"financial_institution_compe_number": 329
			},
			"source_subtype": "withdrawal",
			"target_account": {	
				"owner_name": "Nome Credor Original",
				"account_type": "checking_account",
				"account_digit": "0",
				"account_branch": "0897",
				"account_number": "20001",
				"account_type_str": "Conta Corrente",
				"owner_document_number": "87163234000138",
				"financial_institution_name": "ITAÚ UNIBANCO S.A.",
				"owner_document_number_formatted": "87.163.234/0001-38",
				"financial_institution_compe_number": "341"
			},
			"transaction_key": "b8993075-9ede-4073-be2d-6130b052f888",
			"transacted_at_br": "2023-03-23 13:48:27",
			"pdf_encoded_string": "\<BASE 64 DO PDF DO COMPROVANTE\>",
			"transaction_amount": 520.0,
			"transacted_at_formatted": "23/03/2023, 16:48:27",
			"transacted_at_br_formatted": "23/03/2023, 13:48:27",
			"transaction_amount_formatted": "R$ 520,00",
			"source_subtype_translation_ptbr": "Transferência"
		}
	},
	"webhook_type": "after_disbursement_action_update",
	"event_datetime": "2023-03-23 16:48:31"
}
```

  

#### Erro na ação pós-desembolso

Em caso de erro no pagamento da ação pós-desembolso, o parceiro será notificado através do seguinte webhook:

WEBHOOK_TYPE after_disbursement_action_update
STATUS Error

**Boleto**

```json title='Webhook Body'
{
	"key": "e358e7e3-17b8-4aab-9da1-92f6b78dea00",
	"data": {
		"status": "error",
		"action_key": "e2495e5a-df32-4826-b6f0-419014d3c35a",
		"error_data": {
			"error_code": "QIT000007",
			"description": "Account blocked balance cannot be negative."
		},
		"action_data": {
            "digitable_line": "10495419967200010004900031456924592920008049295"
		},
		"action_type": "bankslip_payment",
		"execution_data": null
	},
	"webhook_type": "after_disbursement_action_update",
	"event_datetime": "2023-03-22 12:06:38"
}
```

**TED**

```json title='Webhook Body'
{
	"key": "e358e7e3-17b8-4aab-9da1-92f6b78dea00",
	"data": {
		"status": "error",
		"action_key": "e2495e5a-df32-4826-b6f0-419014d3c35a",
		"error_data": {
			"error_code": "QIT000007",
			"description": "Account blocked balance cannot be negative."
		},
		"action_data": {
			"destination": {
			    "name": "Nome Credor Original",
				"account_digit": "0",
				"account_branch": "0897",
				"account_number": "20001",
				"document_number": "87163234000138",
				"financial_institution_code_number": "341"
			},
			"transaction_amount": 1000
		},
		"action_type": "funds_transfer",
		"execution_data": null
	},
	"webhook_type": "after_disbursement_action_update",
	"event_datetime": "2023-03-22 12:06:38"
}
```

#### Estorno da TED da ação pós-desembolso

Caso a TED realizada na ação pós-desembolso seja devolvida pela instituição financeira destinatária, o parceiro será notificado através do seguinte webhook:

WEBHOOK_TYPE after_disbursement_action_update
STATUS Refused

```json title='Webhook Body'
{
	"key": "f4b5c36a-2aa1-4865-9678-e5a6fa585845",
	"data": {
		"status": "refused",
		"action_key": "cf3b8809-36dc-4574-8763-3600e413cf5c",
		"error_data": {
			"code": "agencia_conta_invalida",
			"description": "Agência ou Conta Destinatária do Crédito Inválida"
		},
		"action_data": {
			"destination": {
				"name": "SILVANA RAMOS DOS SANTOS",
				"account_digit": "1",
				"account_branch": "0150",
				"account_number": "301771620",
				"document_number": "30874011884",
				"financial_institution_code_number": "237"
			},
			"transaction_amount": 3200
		},
		"action_type": "funds_transfer",
		"action_amount": 3200.0
	},
	"webhook_type": "after_disbursement_action_update",
	"event_datetime": "2023-03-23 14:46:39"
}
```

#### Retentar ação pós-desembolso com falha

Caso ocorra um erro/estorno no pagamento da ação pós-desembolso, ela pode ser retentada através do seguinte endpoint [/baas/action/**[ACTION-KEY]**](/documentation/emissao_de_divida/reprocessar_acao_pos_desembolso)

### Emissão da Operação de Crédito Consignado do SIAPE

A Operação de Crédito Consignado do SIAPE deve quitar a Operação de Crédito Pessoal e liberar (caso exista) o troco para o cliente

#### Request

ENDPOINT /debt
MÉTODO POST

**Digitação Margem Livre**

```json title='Request Body'
{
    "borrower": {
		"name": "Nome do Devedor",
		"email": "email@email.com",
		"phone": {
			"number": "900000000",
			"area_code": "11",
			"country_code": "055"
		},
		"address": {
			"city": "São Paulo",
			"state": "SP",
			"number": "215",
			"street": "Gilberto Sabino",
			"complement": "s/c",
			"postal_code": "12345012",
			"neighborhood": "Pinheiros"
		},
		"role_type": "issuer",
		"birth_date": "1969-05-01",
		"mother_name": "Nome da Mãe do Devedor",
		"person_type": "natural",
		"individual_document_number": "12345678911",
		"gender": "male",
		"nationality": "brasileiro",
		"is_pep": false,
		"marital_status": "married"
	},
    "financial": {
        "first_due_date": "2023-05-07",
        "installment_face_value": 100.0,
        "disbursement_date": "2023-03-22",
        "limit_days_to_disburse": 3,
        "number_of_installments": 96,
        "monthly_interest_rate": 0.0205,
        "interest_type": "pre_price_days",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0
    },
    "simplified": true,
    "collaterals": [{
        "percentage": 1,
        "collateral_data": {
            "reservation_type": "new_credit",
            "authority_code": "17000",
            "pensioner_registration_code": "",
            "registration_code": "12345678",
			"authority": {
				"description": "teste",
				"authority_document_number": "1234"
			}
        },
        "collateral_type": "federal_payroll"
    }],
    "requester_identifier_key": "13176f51-3cc8-46a3-96e9-df59d7e3960c",
    "disbursement_bank_account": {
		"bank_code": "329",
		"account_digit": "3",
		"branch_number": "0001",
		"account_number": "1234567"
	},
    "purchaser_document_number": "32402502000135",
	"modality": {
        "code": "0202"
    },
    "refinanced_credit_operations": [
        {
            "operation_key": "052fe83c-37f6-4339-a831-127b50566745"
        }
    ]
}
```
**Digitação Portabilidade**

```json title='Request Body'
{
    "borrower": {
		"name": "Nome do Devedor",
		"email": "email@email.com",
		"phone": {
			"number": "900000000",
			"area_code": "11",
			"country_code": "055"
		},
		"address": {
			"city": "São Paulo",
			"state": "SP",
			"number": "215",
			"street": "Gilberto Sabino",
			"complement": "s/c",
			"postal_code": "12345012",
			"neighborhood": "Pinheiros"
		},
		"role_type": "issuer",
		"birth_date": "1969-05-01",
		"mother_name": "Nome da Mãe do Devedor",
		"person_type": "natural",
		"individual_document_number": "12345678911",
		"gender": "male",
		"nationality": "brasileiro",
		"is_pep": false,
		"marital_status": "married"
	},
    "financial": {
        "first_due_date": "2023-05-07",
        "installment_face_value": 100.0,
        "disbursement_date": "2023-03-22",
        "limit_days_to_disburse": 3,
        "number_of_installments": 96,
        "monthly_interest_rate": 0.0205,
        "interest_type": "pre_price_days",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0
    },
    "simplified": true,
    "collaterals": [{
        "percentage": 1,
        "collateral_data": {
	 "reservation_method": "creation",
            "authority": {
		"description": "",
                "authority_document_number": ""
		},
            "reservation_type": "portability",
            "authority_code": "17000",
            "pensioner_registration_code": "",
            "registration_code": "12345678",
            "portability_data": {
                "start_date": "",
                "control_number": "",
                "origin_contract": {
                    "contract_number": "",
                    "financial_institution_document_number": ""
                }
            }
        },
        "collateral_type": "federal_payroll"
    }],
    "requester_identifier_key": "13176f51-3cc8-46a3-96e9-df59d7e3960c",
    "disbursement_bank_account": {
		"bank_code": "329",
		"account_digit": "3",
		"branch_number": "0001",
		"account_number": "1234567"
	},
    "purchaser_document_number": "32402502000135",
	"modality": {
        "code": "0202"
    },
    "refinanced_credit_operations": [
        {
            "operation_key": "052fe83c-37f6-4339-a831-127b50566745"
        }
    ]
}
```

#### Response

STATUS 200

```json title='Response Body'
{
    "data": {
        "borrower": {
            "document_number": "12345678911",
            "name": "Nome do Devedor",
            "related_party_key": "c5584ee3-e077-41dc-a28e-c2ba97390bf1"
        },
        "collaterals": [{
            "absolute_amount": null,
            "collateral_constituted": false,
            "collateral_data": {
                "authority_code": "17000",
                "pensioner_registration_code": null,
                "registration_code": "12345678"
            },
            "collateral_key": "5e40c191-06ae-4da2-9d4b-3c0bf6eeb1a3",
            "collateral_type": "federal_payroll",
            "created_at": "2023-03-17T20:56:09.200482",
            "external_key": "8cda40d8-1593-4a1e-938f-5e1488e734d8",
            "percentage": 1,
            "updated_at": "2023-03-17T20:56:09.200474"
        }],
        "contract": {
            "number": "0000000002/NDD",
            "signature_information": [{
                "signature_url": null,
                "signer_document_number": "12345678911",
                "signer_email": "email@email.com",
                "signer_external_key": null,
                "signer_name": "Nome do Devedor",
                "signer_role": "issuer"
            }],
            "urls": [
                "https://storage.googleapis.com/live-doc-api/documents/45e5b9c0-0f56-40a8-aace-d206f72c164d/QISCD-NOME_DO_DEVEDOR-CCB-0000000002-20230317183044.pdf"
            ]
        },
        "disbursement_options": [{
                "additional_iof": 24.220242,
                "annual_cet": "26.1457%",
                "assignment_amount": 3205.12,
                "base_iof": 176.6603785598479778,
                "cet": "1,9544%",
                "contract_fee_amount": 17.68,
                "contract_fees": [{
                    "amount": 17.68,
                    "amount_type": "absolute",
                    "fee_amount": 17.68,
                    "fee_type": "spread_cip_cost"
                }],
                "disbursement_date": "2023-03-22",
                "external_contract_fee_amount": 0,
                "external_contract_fees": [],
                "first_due_date": "2023-05-07",
                "installments": [{
                        "additional_costs": [],
                        "business_due_date": "2022-05-08",
                        "calendar_days": 34,
                        "due_date": "2023-05-07",
                        "due_interest": 0,
                        "due_principal": 3187.44,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "installment_status": null,
                        "installment_type": null,
                        "post_fixed_amount": 0,
                        "pre_fixed_amount": 64.20069301315790,
                        "principal_amortization_amount": 35.79930698684210,
                        "tax_amount": 0.10014353287723266,
                        "total_amount": 100,
                        "workdays": 23
                    }, 
                    ... 
                    x 96
                ],
                "issue_amount": 3187.44,
                "net_external_contract_fee_amount": 0,
                "total_iof": 100.44,
                "total_pre_fixed_amount": 3225.1656904289435
            },
            ...
            x 15
        ],
        "iof_charge_method": "financed",
        "requester_identifier_key": "13176f51-3cc8-46a3-96e9-df59d7e3960c"
    },
    "event_datetime": "2023-03-17 13:54:58",
    "key": "32f99efe-7654-4e74-a509-c7413341a831",
    "status": "waiting_signature",
    "webhook_type": "debt"
}
```

#### Webhook de Anuência Pendente

WEBHOOK_TYPE credit_operation.collateral
STATUS Pending Consent

Body

```json
{
	"key": "\<DEBT-KEY\>",
	"data": {
        "collateral_data": {
			"reservation_status": "pending_consent"
		},
		"collateral_type": "federal_payroll",
		"collateral_constituted": false
	},
	"event_time": "2022-10-31 15:23:46",
	"webhook_type": "credit_operation.collateral"
}
```

#### Averbação

Após a criação da Operação de Crédito Consignado do SIAPE, a QI iniciará o processo de averbação da operação.

O processo de tentativa de averbação inicia no momento da criação da operação, e será retentado até a última data de opção de desembolso da operação.

Assim que a digitação for concluída  a QI informará o parceiro sobre a pendência de anuência da averbação:

WEBHOOK_TYPE credit_operation.collateral
STATUS Pending Consent

Body

```json
{
	"key": "\<DEBT-KEY\>",
	"data": {
        "collateral_data": {
			"reservation_status": "pending_consent"
		},
		"collateral_type": "federal_payroll",
		"collateral_constituted": false
	},
	"event_time": "2022-10-31 15:23:46",
	"webhook_type": "credit_operation.collateral"
}
```

A após a conclusão da anuência e confirmação da averbação da margem, a QI notificará o parceiro através do seguinte webhook:

WEBHOOK_TYPE credit_operation.collateral
STATUS Success

```json title='Webhook Body'
{
    "key": "32f99efe-7654-4e74-a509-c7413341a831",
    "data": {
        "collateral_type": "federal_payroll",
        "collateral_constituted": true
    },
    "event_time": "2022-03-22 15:23:46",
    "webhook_type": "credit_operation.collateral"
}
```

---

### Emissão da Operação de Crédito Consignado do Exército

A Operação de Crédito Consignado do Exército deve quitar a Operação de Crédito Pessoal e liberar (caso exista) o troco para o cliente

#### Request

ENDPOINT /debt
MÉTODO POST

**Digitação Portabilidade (Deprecada a partir de 30/11/2023)**

```json title='Request Body'
{
    "borrower": {
		"name": "Nome do Devedor",
		"email": "email@email.com",
		"phone": {
			"number": "900000000",
			"area_code": "11",
			"country_code": "055"
		},
		"address": {
			"city": "São Paulo",
			"state": "SP",
			"number": "215",
			"street": "Gilberto Sabino",
			"complement": "s/c",
			"postal_code": "12345012",
			"neighborhood": "Pinheiros"
		},
		"role_type": "issuer",
		"birth_date": "1969-05-01",
		"mother_name": "Nome da Mãe do Devedor",
		"person_type": "natural",
		"individual_document_number": "12345678911",
		"gender": "male",
		"nationality": "brasileiro",
		"is_pep": false,
		"marital_status": "married"
	},
    "financial": {
        "first_due_date": "2023-05-07",
        "installment_face_value": 100.0,
        "disbursement_date": "2023-03-22",
        "limit_days_to_disburse": 3,
        "number_of_installments": 72,
        "monthly_interest_rate": 0.017,
        "interest_type": "pre_price_days",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0
    },
    "simplified": true,
    "collaterals": [{
        "percentage": 1,
        "collateral_data": {
            "reservation_type": "portability",
            "portability_data":{
                "token":"hw342y1h24",
                "origin_econsig_id":"2016587"
            },
            "registration_code": "12345678",
			"reservation_method": "creation"
        },
        "collateral_type": "military_payroll" 
    }],
    "requester_identifier_key": "7e000c2d-d381-470e-b233-416097504866",
    "disbursement_bank_account": {
		"bank_code": "341",
		"account_digit": "3",
		"branch_number": "1234",
		"account_number": "1234567"
	},
    "purchaser_document_number": "32402502000135",
	"modality": {
        "code": "0202"
    },
    "refinanced_credit_operations": [
        {
            "operation_key": "d2fd3f63-3d11-42a8-ab5c-9a84b5c58b6c"
        }
    ]
}
```

**Digitação Portabilidade(s) (Vigente a partir de 21/11/2023)**

```json title='Request Body'
{
    "borrower": {
		"name": "Nome do Devedor",
		"email": "email@email.com",
		"phone": {
			"number": "900000000",
			"area_code": "11",
			"country_code": "055"
		},
		"address": {
			"city": "São Paulo",
			"state": "SP",
			"number": "215",
			"street": "Gilberto Sabino",
			"complement": "s/c",
			"postal_code": "12345012",
			"neighborhood": "Pinheiros"
		},
		"role_type": "issuer",
		"birth_date": "1969-05-01",
		"mother_name": "Nome da Mãe do Devedor",
		"person_type": "natural",
		"individual_document_number": "12345678911",
		"gender": "male",
		"nationality": "brasileiro",
		"is_pep": false,
		"marital_status": "married"
	},
    "financial": {
        "first_due_date": "2023-05-07",
        "installment_face_value": 100.0,
        "disbursement_date": "2023-03-22",
        "limit_days_to_disburse": 3,
        "number_of_installments": 72,
        "monthly_interest_rate": 0.017,
        "interest_type": "pre_price_days",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0
    },
    "simplified": true,
    "collaterals": [{
        "percentage": 1,
        "collateral_data": {
            "reservation_type": "portability",
            "portability_data":{
                "token":"hw342y1h24",
                "origin_econsig_ids": [
					"2016587",
					"2016588",
					"2016589",
				]
            },
            "registration_code": "12345678",
			"reservation_method": "creation"
        },
        "collateral_type": "military_payroll" 
    }],
    "requester_identifier_key": "7e000c2d-d381-470e-b233-416097504866",
    "disbursement_bank_account": {
		"bank_code": "341",
		"account_digit": "3",
		"branch_number": "1234",
		"account_number": "1234567"
	},
    "purchaser_document_number": "32402502000135",
	"modality": {
        "code": "0202"
    },
    "refinanced_credit_operations": [
        {
            "operation_key": "d2fd3f63-3d11-42a8-ab5c-9a84b5c58b6c"
        }
    ]
}
```

**Digitação Margem Livre**

```json title='Request Body'
{
    "borrower": {
		"name": "Nome do Devedor",
		"email": "email@email.com",
		"phone": {
			"number": "900000000",
			"area_code": "11",
			"country_code": "055"
		},
		"address": {
			"city": "São Paulo",
			"state": "SP",
			"number": "215",
			"street": "Gilberto Sabino",
			"complement": "s/c",
			"postal_code": "12345012",
			"neighborhood": "Pinheiros"
		},
		"role_type": "issuer",
		"birth_date": "1969-05-01",
		"mother_name": "Nome da Mãe do Devedor",
		"person_type": "natural",
		"individual_document_number": "12345678911",
		"gender": "male",
		"nationality": "brasileiro",
		"is_pep": false,
		"marital_status": "married"
	},
    "financial": {
        "first_due_date": "2023-05-07",
        "installment_face_value": 100.0,
        "disbursement_date": "2023-03-22",
        "limit_days_to_disburse": 3,
        "number_of_installments": 72,
        "monthly_interest_rate": 0.017,
        "interest_type": "pre_price_days",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0
    },
    "simplified": true,
    "collaterals": [{
        "percentage": 1,
        "collateral_data": {
            "reservation_type": "new_credit",
            "registration_code": "123456789",
			"reservation_method": "creation"
        },
        "collateral_type": "military_payroll"
    }],
    "requester_identifier_key": "7e000c2d-d381-470e-b233-416097504866",
    "disbursement_bank_account": {
		"bank_code": "341",
		"account_digit": "3",
		"branch_number": "1234",
		"account_number": "1234567"
	},
    "purchaser_document_number": "32402502000135",
	"modality": {
        "code": "0202"
    },
    "refinanced_credit_operations": [
        {
            "operation_key": "d2fd3f63-3d11-42a8-ab5c-9a84b5c58b6c"
        }
    ]
}
```

**Digitação Refinanciamento**

```json title='Request Body'
{
    "borrower": {
		"name": "Nome do Devedor",
		"email": "email@email.com",
		"phone": {
			"number": "900000000",
			"area_code": "11",
			"country_code": "055"
		},
		"address": {
			"city": "São Paulo",
			"state": "SP",
			"number": "215",
			"street": "Gilberto Sabino",
			"complement": "s/c",
			"postal_code": "12345012",
			"neighborhood": "Pinheiros"
		},
		"role_type": "issuer",
		"birth_date": "1969-05-01",
		"mother_name": "Nome da Mãe do Devedor",
		"person_type": "natural",
		"individual_document_number": "12345678911",
		"gender": "male",
		"nationality": "brasileiro",
		"is_pep": false,
		"marital_status": "married"
	},
    "financial": {
        "first_due_date": "2023-05-07",
        "installment_face_value": 100.0,
        "disbursement_date": "2023-03-22",
        "limit_days_to_disburse": 3,
        "number_of_installments": 72,
        "monthly_interest_rate": 0.017,
        "interest_type": "pre_price_days",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0
    },
    "simplified": true,
    "collaterals": [{
        "percentage": 1,
        "collateral_data": {
            "reservation_type": "refinancing",
            "registration_code": "123456789",
			"reservation_method": "issuing"
        },
        "collateral_type": "military_payroll"
    }],
    "requester_identifier_key": "7e000c2d-d381-470e-b233-416097504866",
    "disbursement_bank_account": {
		"bank_code": "341",
		"account_digit": "3",
		"branch_number": "1234",
		"account_number": "1234567"
	},
    "purchaser_document_number": "32402502000135",
	"modality": {
        "code": "0202"
    },
    "refinanced_credit_operations": [
        {
            "operation_key": "d2fd3f63-3d11-42a8-ab5c-9a84b5c58b6c"
        }
    ]
}
```

### Detalhamento de campos no objeto collateral_data
| Campo             	| Descrição             						| Valores  												|
|-----------------------|-----------------------------------------------|-------------------------------------------------------|
| reservation_type		| Tipo da reserva								| [Enumeradores](#reservation_type_enumerator)			|
| registration_code		| Matrícula do militar							| 123456789               								|
| reservation_method	| Determina quando deve-se iniciar a tentativa de averbação do consignado, seja no momento da criação da operação de crédito ou no momento da emissão da mesma.	| [Enumeradores](#reservation_method_enumerator)		|
| portability_data  	| Dados de portabilidade						| [Objeto de Portabilidade](#portability_data_object)	|

### Tabela de tipos de reserva {#reservation_type_enumerator}
| Enumerador  | Descrição 		|
|-------------|-----------------|
| new_credit  | Crédito Novo 	|
| portability | Portabilidade 	|
| refinancing | Refinanciamento |

### Tabela de metodos de criação de reserva {#reservation_method_enumerator}

:::caution Atenção
Campo muito importante, pois ele determina diretamente quando o pedido de intensão de reserva na Zetra será feito.
:::

| Enumerator 	| Descrição                                     																		|
|---------------|-----------------------------------------------------------------------------------------------------------------------|
| creation		| A tentativa de averbação começará quando a operação de crédito for criada.											|
| issuing		| A tentativa de averbação começará quando a operação de crédito for emitida, ou seja, após a formalização da mesma.	|

### Detalhamento de campos no objeto portability_data {#portability_data_object}
| Campo             	| Descrição             									| Valores  						|
|-----------------------|-----------------------------------------------------------|-------------------------------|
| token             	| Senha fornecida pelo militar								| 1234abcd  					|
| origin_econsig_id		| Código identificador de contrato da Zetra					| 1234567						|
| origin_econsig_ids	| Lista de códigos identificadores de contratos da Zetra	| [1234567, 1234568, 1234569]	|

#### Response

STATUS 200

```json title='Response Body'
{
    "data": {
        "borrower": {
            "document_number": "12345678911",
            "name": "Nome do Devedor",
            "related_party_key": "1fe936e7-0917-4c3d-9206-87958254fa1d"
        },
        "collaterals": [{
            "absolute_amount": null,
            "collateral_constituted": false,
            "collateral_data": {
                "reservation_type": "new_credit",
                "registration_code": "123456789"
            },
            "collateral_key": "c6006572-d66a-45f6-862d-4ecb5b9b5d2d",
            "collateral_type": "military_payroll",
            "created_at": "2023-03-17T20:56:09.200482",
            "external_key": "1c736cd8-a4c7-43d4-8abd-c00ed0cd6450",
            "percentage": 1,
            "updated_at": "2023-03-17T20:56:09.200474"
        }],
        "contract": {
            "number": "0000000003/NDD",
            "signature_information": [{
                "signature_url": null,
                "signer_document_number": "12345678911",
                "signer_email": "email@email.com",
                "signer_external_key": null,
                "signer_name": "Nome do Devedor",
                "signer_role": "issuer"
            }],
            "urls": [
                "https://storage.googleapis.com/live-doc-api/documents/ae66d0cd-1054-4ff5-b1d6-e03aaaa2ff1b/QISCD-NOME_DO_DEVEDOR-CCB-0000000002-20230317183044.pdf"
            ]
        },
        "disbursement_options": [{
                "additional_iof": 24.220242,
                "annual_cet": "26.1457%",
                "assignment_amount": 3205.12,
                "base_iof": 176.6603785598479778,
                "cet": "1,9544%",
                "contract_fee_amount": 17.68,
                "contract_fees": [{
                    "amount": 17.68,
                    "amount_type": "absolute",
                    "fee_amount": 17.68,
                    "fee_type": "spread_cip_cost"
                }],
                "disbursement_date": "2023-03-22",
                "external_contract_fee_amount": 0,
                "external_contract_fees": [],
                "first_due_date": "2023-05-07",
                "installments": [{
                        "additional_costs": [],
                        "business_due_date": "2022-05-08",
                        "calendar_days": 34,
                        "due_date": "2023-05-07",
                        "due_interest": 0,
                        "due_principal": 3187.44,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "installment_status": null,
                        "installment_type": null,
                        "post_fixed_amount": 0,
                        "pre_fixed_amount": 64.20069301315790,
                        "principal_amortization_amount": 35.79930698684210,
                        "tax_amount": 0.10014353287723266,
                        "total_amount": 100,
                        "workdays": 23
                    }, 
                    ... 
                    x 96
                ],
                "issue_amount": 3187.44,
                "net_external_contract_fee_amount": 0,
                "total_iof": 100.44,
                "total_pre_fixed_amount": 3225.1656904289435
            },
            ...
            x 15
        ],
        "iof_charge_method": "financed",
        "requester_identifier_key": "f7fa079e-e02f-469f-a9ba-7a550f8f665f"
    },
    "event_datetime": "2023-03-17 13:54:58",
    "key": "23c89acf-b11b-4988-b738-a0f5ba238c33",
    "status": "waiting_signature",
    "webhook_type": "debt"
}
```

#### Averbação

Após a criação da Operação de Crédito Consignado do EXÉRCITO, a QI iniciará o processo de averbação da operação.

O processo de tentativa de averbação inicia no momento da criação da operação, e será retentado até a última data de opção de desembolso da operação.

A após a conclusão da averbação da margem consignável do exército, a QI notificará o parceiro através do seguinte webhook:

WEBHOOK_TYPE credit_operation.collateral
STATUS Success

```json title='Webhook Body'
{
    "key": "23c89acf-b11b-4988-b738-a0f5ba238c33",
    "data": {
        "collateral_type": "military_payroll",
        "collateral_constituted": true
    },
    "event_time": "2022-10-31 15:23:46",
    "webhook_type": "credit_operation.collateral"
}
```
Caso o token informado não seja válido, enviaremos o seguinte webhook. Esse webhook também será enviado caso o token informado já tenha sido utilizado e seja necessário um novo.

WEBHOOK_TYPE credit_operation.collateral
STATUS Pending Valid Token

```json title='Webhook Body'
{
    "key": "23c89acf-b11b-4988-b738-a0f5ba238c33",
    "data": {
		"collateral_type": "military_payroll",
		"collateral_data": {
			"reservation_status": "pending_valid_token",
			"cancel_reason": "invalid_token",
		},
		"collateral_constituted": false,
    },
    "event_time": "2022-10-31 15:23:46",
    "webhook_type": "credit_operation.collateral"
}
```

#### Resposta que ocasionam cancelamento automático

Dependendo da resposta da Zetra, a operação será cancelada automaticamente.
Quando isso ocorrer enviaremos um webhook no formato abaixo, o motivo do cancelamento é informado no campo "cancel_reason"

WEBHOOK_TYPE credit_operation.collateral
STATUS Canceled

```json title='Webhook Body'
{
	"data": {
		"cancel_reason": "Contrato de origem não encontrato.",
		"cancel_reason_enumerator": "military_payroll_portability_not_found"
	},
	"event_datetime": "2023-10-10 15:45:21",
	"key": "\<UUID \>",
	"status": "canceled",
	"webhook_type": "debt"

}
```
#### Tabela de enumeradores
| Enumerador                    				| Descrição                             | Código da Zetra  |
|-----------------------------------------------|---------------------------------------|------------------|
| military_payroll_military_not_found			| Militar não encontrado. 				| 293              |
| military_payroll_portability_not_found		| Contrato de origem não encontrato.	| 294              |
| military_payroll_consignable_margin_exceeded	| Margem disponível excedida.			| 359              |

#### Expiração da Portabilidade

Após 10 dias, a Zetra cancela os pedidos de portabilidades que estão aguardando confirmação.

Desta forma, para reiniciar o fluxo de portabilidade, faz-se necessário um novo token válido. Caso exista um novo token válido, a proposta retorna para o passo de intenção de portabilidade (status da reserva: pending_reservation). No entanto, caso não exista um token válido, geralmente porque o token enviado já foi utilizado na intenção de portabilidade anterior, a proposta é atualizada para o status de pending_valid_token, aguardando o envio de um novo token. Com o envio de um novo token válido, a proposta segue normalmente o fluxo de intenção de portabilidade e confirmação.

Para informar a situação será enviado o seguinte webhook:

WEBHOOK_TYPE credit_operation.collateral
STATUS Pending Reservation/Pending Valid Token

```json title='Webhook Body'
{
    "key": "23c89acf-b11b-4988-b738-a0f5ba238c33",
    "data": {
		"collateral_type": "military_payroll",
		"collateral_data": {
			"reservation_status": "pending_reservation" ou "pending_valid_token",
			"cancel_reason": "expired_portability",
		},
    },
    "event_time": "2022-10-31 15:23:46",
    "webhook_type": "credit_operation.collateral"
}
```
## Cancelamento
Para realizar o cancelamento definitivo de uma operação, com a desaverbação da margem consignável, deve ser utilizado o seguinte endpoint:

:::caution Atenção
Vale ressaltar que o processo de desaverbação é assíncrono, ou seja, o cancelamento da operação de crédito, NÃO signifca necessáriamente que a desaverbação foi concluída. Para consultar o status da desaverbação vide [Recuperar resposta da última request](#recuperar_ultima_request)".
:::

:::caution Atenção
O cancelamento definitivo também pode ocorrer de forma automática, isso acontece quando uma operação está no status "canceled" por mais de 7 dias.
:::
### Request

ENDPOINT /debt/[DEBT-KEY]/cancel_permanently
MÉTODO POST

### Cancelamento da operação com sucesso:

Após a conclusão do cancelamento da operação, o parceiro receberá o seguinte webhook:

WEBHOOK_TYPE debt
STATUS Canceled Permanently

Body

```json
{
	"key": "\<DEBT-KEY\>",
	"data": {},
	"status": "canceled_permanently",
	"webhook_type": "debt",
	"event_datetime": "2022-11-01 03:46:31"
}
```

## Envio de novo Token de Portabilidade

O token de portabilidade é de uso único, portanto, é necessário que um novo token seja enviado quando o anterior for utilizado ou no caso de token inválido.

A forma de envio é uma chamada simples:

### Request

ENDPOINT /debt/[DEBT-KEY]/collateral
MÉTODO PATCH

Request Body

```json
    {
        "portability_data": {
            "token": "12345678"
        }
    }
```

### Casos de sucesso
#### Response 204

Response Body

```json
    {}
```

### Caso de erro
:::info
Somente o token deverá ser enviado nessa requisição, caso contrário o processo retornará um erro
:::
#### Response

Response Body

```json
    {
        "title": "Bad Request",
        "description": "Additional properties are not allowed (<campo extra> was unexpected)",
        "translation": "Schema Inválido",
        "code": "QIT000001"
    }
```

## Alteração do tipo de averbação da operação

Alterar, exclusivamente, o tipo de averbação de uma operação de portabilidade para crédito novo.
Após a alteração, a reserva seguirá, automaticamente, o fluxo e regras de averbação de uma reserva do tipo crédito novo.
### Request

ENDPOINT /debt/[DEBT-KEY]/collateral
MÉTODO PATCH

Request Body

```json
    {
        "reservation_type": "new_credit"
    }
```

### Casos de sucesso
#### Response 204

Response Body

```json
    {}
```

### Caso de erro

#### Response

Response Body

```json
    {
        "title": "Bad Request",
        "description": "Additional properties are not allowed (<campo extra> was unexpected)",
        "translation": "Schema Inválido",
        "code": "QIT000001"
    }
```

## Recuperar resposta da última request {#recuperar_ultima_request}

O last response é uma forma de mapear, de forma simples e objetiva, a resposta da comunicação entre a QI e a Zetra, possibilitando saber quando essa requisição foi feita e qual o retorno obtido (através de um enumerador).

Cada enumerador tem uma descrição detalhada. Podemos conferir abaixo, com mais detalhes, como serão apresentados os dados do last response.

### Casos de sucesso

#### Request
ENDPOINT /debt/[DEBT-KEY]/collateral
MÉTODO GET

#### Response

Response Body

```json
  {
    "collateral_constituted": true,
    "collateral_type": "military_payroll",
    "updated_at": "2023-05-24 19:13:02",
    "collateral_data": {
      "status": "reserved",
      "last_response": {
        "success": [
          {
            "enumerator": "succesfully_reserved"
          }
        ]
      },
      "last_response_event_datetime": "2023-05-22T19:13:02Z"
    }
  }
```

Response Body Portability

```json
{
    "collateral_constituted": true,
    "collateral_type": "military_payroll",
    "collateral_data": {
        "status": "reserved",
        "last_response": {
            "success": [
                {
                    "enumerator": "successfully_reserved"
                }
            ]
        },
        "last_response_event_datetime": "2023-08-09T19:25:09Z",
        "portability_data": {
            "origin_econsig_id": "2016587",
            "token": "123456"
        }       
    }
}
```

#### Tabela de enumeradores
| Enumerador                        | Descrição                        | Detalhes                                                           | Status da reserva    |
|-----------------------------------|----------------------------------|--------------------------------------------------------------------| ---------------------|
| successfully_accepted             | Reservation request accepted     | O pedido de averbação foi aceito e está aguardando confirmação     | pending_confirmation |
| successfully_reserved             | Reservation made successfully    | A reserva foi averbada com sucesso                                 | reserved             |
| successfully_deleted              | Reservation successfully deleted | A reserva foi desaverbada com sucesso                              | deleted              |

### Casos de erro

#### Request
ENDPOINT /debt/[DEBT-KEY]/collateral
MÉTODO GET

#### Response

Response Body

```json
  {
    "collateral_constituted": false,
    "collateral_type": "military_payroll",
    "updated_at": "2023-05-24 19:13:02",
    "collateral_data": {
      "status": "pending_reservation",
      "last_response": {
        "errors": [
          {
            "enumerator": "invalid_portability_token"
          }
        ]
      },
      "last_response_event_datetime": "2023-05-22T19:13:02Z"
    }
  }
```

#### Tabela de enumeradores
| Enumerador                  | Descrição                                 | Ação QI | Código correspondente da Zetra  |
|-----------------------------|-------------------------------------------|---------|---------------------------------|
| waiting_confirmation        | Waiting Confirmation on Portability       | retry   |                                 |
| communication_error         | Communication Error with Zetra            | retry   | 241                             |
| consignable_margin_excceded | Exceeded consignable margin               | retry   | 359                             |

## Informe de Saldo Devedor

O informe de saldo devedor acontece no 5º dia útil após o dia da solicitação, e todos os informados são enviados pelo webhook com as seguintes informações:

WEBHOOK_TYPE military_payroll.due_balance.status_change
STATUS processed

Response Body

```json
{
	"webhook_type": "military_payroll.due_balance.status_change",
	"status": "processed",
	"event_datetime": "2024-03-12T19:23:12Z",
	"data": [
		{
			"contract_number": "0000086715/TA",
			"payment_amount": 284.28,
			"balance_limit_date": "2024-03-12"
		},
		{
			"contract_number": "0000086715/BE",
			"payment_amount": 134.00,
			"balance_limit_date": "2024-03-12"
		}
	]
}
```

---

# Abertura de Conta em Duas Etapas

URL: /documentation/account_request

## Solicitar Reserva de Conta de Livre Movimentação

### Request

ENDPOINT /account_request/checking
MÉTODO POST

Request Body - Titular PJ

```json
{
    "account_owner": {
        "company_document_number": "64669455000187",
        "email": "marcos.alves@yopmail.com",
        "foundation_date": "2017-09-16",
        "name": "NOME DA EMPRESA"
    }
}
```

Request Body - Titular PF

```json
{
    "account_owner": {
        "document_number": "64669455000187",
        "email": "marcos.alves@yopmail.com",
        "birthdate": "2017-09-16",
        "name": "NOME DA EMPRESA"
    }
}
```

## Solicitar Reserva de Conta Escrow

ENDPOINT /account_request/escrow
MÉTODO POST

Request Body - Titular PJ

```json
{
    "account_owner": {
        "company_document_number": "64669455000187",
        "email": "marcos.alves@yopmail.com",
        "foundation_date": "2017-09-16",
        "name": "NOME DA EMPRESA"
    }
}
```

Request Body - Titular PF

```json
{
    "account_owner": {
        "document_number": "64669455000187",
        "email": "marcos.alves@yopmail.com",
        "birthdate": "2017-09-16",
        "name": "NOME DA EMPRESA"
    }
}
```

### Body Params Titular PJ

| Campo            | Tipo       | Descrição                                      | Caracteres                                                                        |
|------------------|------------|------------------------------------------------|-----------------------------------------------------------------------------------|
| **account_owner**  | object     | Informações simplificadas da pessoa jurídica titular da conta | [Objeto account_owner PJ](#objeto-account_owner-solicitar-reserva-pj) <br/><br/> [Objeto account_owner PF](#objeto-account_owner-solicitar-reserva-pf) |

### Objeto account_owner Solicitar Reserva PJ

| Campo                         | Tipo   | Descrição                                 | Caracteres |
|-------------------------------|--------|-------------------------------------------|------------|
| **company_document_number** * | string | CNPJ do titualar da conta.                | 14         |
| **email** *                   | string | E-mail da empresa titular da contato.     | 200        |
| **foundation_date**           | string | Data de abertura da empresa.              | 10         |
| **name** *                    | string | Razão Social da empresa titular da conta. | 50         |

### Objeto account_owner Solicitar Reserva PF

| Campo                  | Tipo   | Descrição                                 | Caracteres |
|------------------------|--------|-------------------------------------------|------------|
| **document_number** *  | string | CPF do titualar da conta.                 | 14         |
| **email** *            | string | E-mail da empresa titular da contato.     | 200        |
| **birthdate**          | string | Data de nascimento.                       | 10         |
| **name** *             | string | Razão Social da empresa titular da conta. | 50         |

### Response

STATUS 201

Response Body

```json
{
    "account_info": {
        "account_branch": "0001",
        "account_digit": "3",
        "account_number": "1638634"
    },
    "account_request_key": "e48eb139-448e-43b9-9aee-df5f4b51158c",
    "account_request_status": "pending_kyc_analysis"
}
```

### Webhook aprovação KYC

Webhook Body

```json
{
    "data": {
        "account_info": {
            "account_digit": "3",
            "account_branch": "0001",
            "account_number": "1638634"
        },
        "account_request_key": "dc575950-dcce-48e1-99a6-5fb0ada63d86"
    },
    "event_datetime": "2022-09-02 22:39:39",
    "key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
    "status": "pending_additional_data",
    "webhook_type": "account_request.status_change"
}
```

### Enumeradores account_request_status
| Enum                        | Description                     |
|-----------------------------|---------------------------------|
| **pending_kyc_analysis**    | Pendente aprovação KYC          |
| **pending_additional_data** | Pendente informações adicionais |
| **rejected**                | Abertura rejeitada              |

## Abertura de Conta Livre Movimentação

### Request

ENDPOINT /account_request/ACCOUNT_REQUEST_KEY/checking
MÉTODO PATCH

Request Body - Titular PJ

```json
{
    "account_owner": {
        "address": {
            "city": "Caraguatatuba",
            "complement": "complemento",
            "neighborhood": "Jaraguazinho",
            "number": "924",
            "postal_code": "11675200",
            "state": "SP",
            "street": "Praça Jorge Vitório de Souza"
        },
        "cnae_code": "4721-1/02",
        "company_document_number": "64669455000187",
        "company_statute": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
        "company_type": "ltda",
        "email": "marcos.alves@yopmail.com",
        "foundation_date": "2017-09-16",
        "name": "NOME DA EMPRESA",
        "person_type": "legal",
        "phone": {
            "area_code": "19",
            "country_code": "055",
            "number": "988888888"
        },
        "trading_name": "Pães e Doces",
        "company_representatives": [
            {
                "name": "Marcos Felipe Henrique Alves",
                "address": {
                    "city": "Recife",
                    "complement": null,
                    "neighborhood": "Fundão",
                    "number": "137",
                    "postal_code": "52221110",
                    "state": "PE",
                    "street": "Rua Camapuã"
                },
                "email": "marcos.alves@yopmail.com",
                "birth_date": "1972-02-02",
                "individual_document_number": "08531309069",
                "document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
                "document_identification_number": "339122924",
                "is_pep": false,
                "final_beneficiary": true,
                "marital_status": "single",
                "mother_name": "Sueli Isadora Alves",
                "nationality": "Brasileira",
                "person_type": "natural",
                "phone": {
                    "area_code": "88",
                    "country_code": "055",
                    "number": "995924634"
                }
            }
        ]
    },
    "signed_contract": {
        "document_key": "4d7f4e29-4b58-4905-9a69-b1f9215263f5",
        "signatures": [
            {
                "authenticity": {
                    "timestamp": "1970-01-01T00:00:01.080100Z",
                    "facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
                    "lang": "-35.8916627",
                    "lat": "-7.2226067",
                    "ip_address": "177.51.1.186",
                    "session_id": "jdifj329842"
                },
                "signer": {
                    "name": "IVANILDO DE SENA LIMA",
                    "email": "ivanlima2604@gmail.com",
                    "phone": {
                        "country_code": "055",
                        "area_code": "11",
                        "number": "999999999"
                    },
                    "document_number": "61766976204"
                },
                "authentication_type": "opt-in"
            }
        ]
    },
    "additional_documents": ["b12c8807-8f3f-4083-9cb1-7cce641f3786"],
    "guarantee_document_key": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d"
}
```

Request Body - Titular PF

```json
{
    "account_owner": {
        "address": {
            "street": "Av. Brigadeiro Faria Lima",
            "state": "SP",
            "city": "São Paulo",
            "neighborhood": "Jardim Paulistano",
            "number": "2391",
            "postal_code": "01452905",
            "complement": "1o. Andar"
        },
        "birth_date": "1990-05-06",
        "document_identification": "3c24579b-9810-4fa6-9b08-fe67d237160a",
        "email": "ivanlima2604@gmail.com",
        "individual_document_number": "34651104630",
        "is_pep": false,
        "mother_name": "Dona Maria Mariane",
        "name": "Nome do Titular da Conta",
        "nationality": "nationality",
        "person_type": "natural",
        "phone": {
            "country_code": "055",
            "area_code": "11",
            "number": "999999999"
        },
        "proof_of_residence": "780456bd-1eec-4e5f-82c0-d8c3921497ea"
    },
    "signed_contract": {
        "document_key": "4d7f4e29-4b58-4905-9a69-b1f9215263f5",
        "signatures": [
            {
                "authenticity": {
                    "timestamp": "1970-01-01T00:00:01.080100Z",
                    "facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
                    "lang": "-35.8916627",
                    "lat": "-7.2226067",
                    "ip_address": "177.51.1.186",
                    "session_id": "jdifj329842"
                },
                "signer": {
                    "name": "Nome do Titular da Conta",
                    "email": "ivanlima2604@gmail.com",
                    "phone": {
                        "country_code": "055",
                        "area_code": "11",
                        "number": "999999999"
                    },
                    "document_number": "61766976204"
                },
                "authentication_type": "opt-in"
            }
        ]
    },
    "additional_documents": ["b12c8807-8f3f-4083-9cb1-7cce641f3786"],
    "guarantee_document_key": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d"
}
```

### Response

STATUS 201

Response Body

```json
{
    "account_key": "e48eb139-448e-43b9-9aee-df5f4b51158c"
}
```

:::info ACCOUNT_KEY
A `account_key` será a chave única de identificação da conta. Toda interação com a conta se dará através dela.
:::

## Abertura de Conta Escrow

### Request

ENDPOINT /account_request/ACCOUNT_REQUEST_KEY/escrow
MÉTODO PATCH

Request Body - Titular PJ

```json
{
    "account_owner": {
        "address": {
            "city": "Caraguatatuba",
            "complement": "complemento",
            "neighborhood": "Jaraguazinho",
            "number": "924",
            "postal_code": "11675200",
            "state": "SP",
            "street": "Praça Jorge Vitório de Souza"
        },
        "cnae_code": "4721-1/02",
        "company_document_number": "64669455000187",
        "company_statute": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
        "company_type": "ltda",
        "email": "marcos.alves@yopmail.com",
        "foundation_date": "2017-09-16",
        "name": "NOME DA EMPRESA",
        "person_type": "legal",
        "phone": {
            "area_code": "19",
            "country_code": "055",
            "number": "988888888"
        },
        "trading_name": "Pães e Doces",
        "company_representatives": [
            {
                "name": "Marcos Felipe Henrique Alves",
                "address": {
                    "city": "Recife",
                    "complement": null,
                    "neighborhood": "Fundão",
                    "number": "137",
                    "postal_code": "52221110",
                    "state": "PE",
                    "street": "Rua Camapuã"
                },
                "email": "marcos.alves@yopmail.com",
                "birth_date": "1972-02-02",
                "individual_document_number": "08531309069",
                "document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
                "document_identification_number": "339122924",
                "is_pep": false,
                "final_beneficiary": true,
                "marital_status": "single",
                "mother_name": "Sueli Isadora Alves",
                "nationality": "Brasileira",
                "person_type": "natural",
                "phone": {
                    "area_code": "88",
                    "country_code": "055",
                    "number": "995924634"
                }
            }
        ]
    },
    "signed_contract": {
        "document_key": "4d7f4e29-4b58-4905-9a69-b1f9215263f5",
        "signatures": [
            {
                "authenticity": {
                    "timestamp": "1970-01-01T00:00:01.080100Z",
                    "facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
                    "lang": "-35.8916627",
                    "lat": "-7.2226067",
                    "ip_address": "177.51.1.186",
                    "session_id": "jdifj329842"
                },
                "signer": {
                    "name": "IVANILDO DE SENA LIMA",
                    "email": "ivanlima2604@gmail.com",
                    "phone": {
                        "country_code": "055",
                        "area_code": "11",
                        "number": "999999999"
                    },
                    "document_number": "61766976204"
                },
                "authentication_type": "opt-in"
            }
        ]
    },
    "destinations": [
        {
            "account_branch": "0001",
            "account_number": "1234567",
            "account_digit": "1",
            "document_number": "04252012000123",
            "name": "Conta do FIDC",
            "ispb_number": "32402502",
            "financial_institution_code_number": "329"
        }
    ],
    "additional_documents": ["b12c8807-8f3f-4083-9cb1-7cce641f3786"],
    "guarantee_document_key": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d"
}
```

Request Body - Titular PF

```json
{
    "account_owner": {
        "address": {
            "street": "Av. Brigadeiro Faria Lima",
            "state": "SP",
            "city": "São Paulo",
            "neighborhood": "Jardim Paulistano",
            "number": "2391",
            "postal_code": "01452905",
            "complement": "1o. Andar"
        },
        "birth_date": "1990-05-06",
        "document_identification": "3c24579b-9810-4fa6-9b08-fe67d237160a",
        "email": "ivanlima2604@gmail.com",
        "individual_document_number": "34651104630",
        "is_pep": false,
        "mother_name": "Dona Maria Mariane",
        "name": "Nome do Titular da Conta",
        "nationality": "nationality",
        "person_type": "natural",
        "phone": {
            "country_code": "055",
            "area_code": "11",
            "number": "999999999"
        },
        "proof_of_residence": "780456bd-1eec-4e5f-82c0-d8c3921497ea"
    },
    "signed_contract": {
        "document_key": "4d7f4e29-4b58-4905-9a69-b1f9215263f5",
        "signatures": [
            {
                "authenticity": {
                    "timestamp": "1970-01-01T00:00:01.080100Z",
                    "facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
                    "lang": "-35.8916627",
                    "lat": "-7.2226067",
                    "ip_address": "177.51.1.186",
                    "session_id": "jdifj329842"
                },
                "signer": {
                    "name": "Nome do Titular da Conta",
                    "email": "ivanlima2604@gmail.com",
                    "phone": {
                        "country_code": "055",
                        "area_code": "11",
                        "number": "999999999"
                    },
                    "document_number": "34651104630"
                },
                "authentication_type": "opt-in"
            }
        ]
    },
    "destinations": [
        {
            "account_branch": "0001",
            "account_number": "1234567",
            "account_digit": "1",
            "document_number": "04252012000123",
            "name": "Conta do FIDC",
            "ispb_number": "32402502",
            "financial_institution_code_number": "329"
        }
    ],
    "additional_documents": ["b12c8807-8f3f-4083-9cb1-7cce641f3786"],
    "guarantee_document_key": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d"
}
```

### Response

STATUS 201

Response Body

```json
{
    "account_key": "e48eb139-448e-43b9-9aee-df5f4b51158c"
}
```

:::info ACCOUNT_KEY
A `account_key` será a chave única de identificação da conta. Toda interação com a conta se dará através dela.
:::

### Body Params Abertura de Conta
| Campo                      | Tipo   | Descrição                                                                   | Caracteres                                                                                                                                                     |
|----------------------------|--------|-----------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **account_owner** *        | object | Informações completas do titular da conta                                   | **[Objeto account_owner PJ](#objeto-account_owner-abertura-de-conta-pj)** <br/><br/> **[Objeto account_owner PF](#objeto-account_owner-abertura-de-conta-pf)** |
| **signed_contract** *      | object | Objeto contendo os dados de contrato e dos assinantes do contrato da conta. | **[Objeto signed_contract](#objeto-signed_contract)**                                                                                                          |
| **destinations** **        | list   | Lista de contas destino autorizadas a receber transaferências.              | **[Objeto destinations](#objeto-destinations)**                                                                                                                |
| **additional_documents**   | list   | Lista de id's de documentos extras/opcionais .                              | Array de UUID's                                                                                                                                                |
| **guarantee_document_key** | uuidv4 | DOCUMENT_KEY do PDF do documento de caução/garantia do contrato de conta escrow (enviado previamente). (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36                                                                                                                                                             |

`(**) Obrigatório para conta Escrow`

### Objeto account_owner Abertura de Conta PJ
| Campo                         | Tipo       | Descrição                                                                                                       | Caracteres                                                            |
|-------------------------------|------------|-----------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
| **address** *                 | object     | Objeto endereço do titular da conta                                                                             | **[Objeto address](#objeto-address)**                                 |
| **cnae_code** *               | string     | Classificação Nacional de Atividades Econômicas                                                                 | 9                                                                     |
| **company_document_number** * | string     | CNPJ                                                                                                            | 14                                                                    |
| **company_statute** *         | uuidv4     | DOCUMENT_KEY do PDF do estatuto da empresa (enviado previamente).                                               | 36                                                                    |
| **company_type** *            | enumerator | Tipo da empresa                                                                                                 | **[Enumeradores company_type](#enumeradores-company_type)**           |
| **email** *                   | string     | Email institucional da empresa.                                                                                 | 200                                                                   |
| **foundation_date** *         | string     | Data de abertura da empresa (formato "AAAA-MM-DD").                                                             | 10                                                                    |
| **name** *                    | string     | Razão social do titular da conta.                                                                               | 50                                                                    |
| **person_type** *             | enumerator | Identificador de que o objeto enviado é uma pessoa jurídica. Deve conter SEMPRE o valor "legal" para Objeto PJ. | **[Enumeradores person_type](#enumeradores-person_type)**             |
| **phone** *                   | object     | Telefone do titular da conta.                                                                                   | **[Objeto phone](#objeto-phone)**                                     |
| **trading_name** *            | string     | Nome fantasia.                                                                                                  | 200                                                                   |
| **company_representatives** * | list       | Lista dos representantes legais da empresa                                                                      | **[Objeto company_representatives](#objeto-company_representatives)** |

### Objeto account_owner Abertura de Conta PF
| Campo                            | Tipo    | Descrição                                                                                                         | Caracteres                                                |
|----------------------------------|---------|-------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------| 
| **address**                      | string  | Objeto endereço do titular da conta                                                                               | **[Objeto address](#objeto-address)**                     | 
| **birth_date** *                 | string  | Data de nascimento da pessoa (formato "AAAA-MM-DD")                                                               | -                                                         |
| **document_identification** *    | uuidv4  | DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente)            | 36                                                        |
| **email** *                      | string  | Email do titular da conta.                                                                                        | 200                                                       |
| **individual_document_number** * | string  | CPF da pessoa (apenas números).                                                                                   | 11                                                        |
| **is_pep** *                     | boolean | Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep).                     | -                                                         |
| **mother_name** *                | string  | Nome da mãe do titular da conta.                                                                                  | -                                                         |
| **name** *                       | string  | Nome do titular da conta.                                                                                         | -                                                         |
| **nationality** *                | string  | Nacionalidade do cliente.                                                                                         | -                                                         |
| **person_type** *                | string  | Identificador de que o objeto enviado é uma pessoa jurídica. Deve conter SEMPRE o valor "natural" para Objeto PF. | **[Enumeradores person_type](#enumeradores-person_type)** |
| **phone**                        | string  | Objeto com dados do telefone do titular da conta                                                                  | 36                                                        |
| **proof_of_residence**           | uuidv4  | DOCUMENT_KEY do PDF do comprovante de endereço do endereço enviado (enviado previamente).                         |                                                           |

### Objeto address
| Campo              | Descrição | Exemplo                                                                                   | Caracteres |
|--------------------|-----------|-------------------------------------------------------------------------------------------|------------|
| **street** *       | string    | Rua do endereço                                                                           | 500        |
| **state** *        | enum      | Estado do endereço (com dois caracteres maiúsculos)                                       | 2          |
| **city** *         | string    | Cidade do endereço                                                                        | 255        |
| **neighborhood** * | string    | Bairro do endereço                                                                        | 500        |
| **number** *       | string    | Número da rua                                                                             | 10         |
| **postal_code** *  | string    | CEP do endereço (http://www.buscacep.correios.com.br/sistemas/buscacep/) (apenas números) | 8          |
| **complement**     | string    | Complemento do endereço (texto livre)                                                     | 500        |

### Objeto phone
| Campo              | Descrição | Exemplo                                               | Caracteres   |
|--------------------|-----------|-------------------------------------------------------|--------------|
| **country_code** * | string    | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3            |
| **area_code** *    | string    | Código DDD do telefone (https://ddd.guiamais.com.br/) | 3            |
| **number** *       | string    | Número de telefone (apenas números)                   | 10           |

### Objeto company_representatives
| Campo                              | Tipo    | Descrição                                                                                              | Caracteres                                                                              |
|------------------------------------|---------|--------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
| **name** *                         | string  | Nome do representante da empresa                                                                       | 100                                                                                     |
| **address** *                      | object  | Objeto endereço do representante da empresa                                                            | **[Objeto address](#objeto-address)**                                                   |
| **email** *                        | string  | Email do representante da empresa                                                                      | 254                                                                                     |
| **birth_date** *                   | string  | Data de nascimento representante da empresa (formato "AAAA-MM-DD")                                     | 10                                                                                      |
| **individual_document_number** *   | string  | CPF do representante da empresa (apenas números).                                                      | 11                                                                                      |
| **document_identification** *      | uuidv4  | DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) | 36                                                                                      |
| **document_identification_number** | string  | Número do documento de identificação com foto da pessoa (RG ou CNH)                                    | 16                                                                                      |
| **document_identification_type**   | enum    | Tipo do documento de identificação com foto da pessoa (RG ou CNH)                                      | [Enumeradores document_identification_type](#enumeradores-document_identification_type) |
| **is_pep** *                       | boolean | Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep).          | -                                                                                       |
| **final_beneficiary**              | boolean | Declaração se o representante é beneficiário final da empresa.                                         | -                                                                                       |
| **marital_status**                 | enum    | Estado civil do representante da empresa                                                               | **[Enumeradores marital status](#enumeradores-marital_status)**                         |
| **mother_name** *                  | string  | Nome da mãe do representante da empresa                                                                | 100                                                                                     |
| **nationality**                    | string  | Nacionalidade do representante da empresa                                                              | 50                                                                                      |
| **person_type** *                  | enum    | Identificador de que o objeto enviado é uma pessoa física                                              | **[Enumeradores person_type](#enumeradores-person_type)**                               |
| **phone** *                        | object  | Objeto com dados do telefone do representante da empresa                                               | **[Objeto phone](#objeto-phone)**                                                       |

### Objeto signed_contract conta livre
| Campo              | Tipo   | Descrição                                                                                                                                                                                                           | Caracteres                              |
|--------------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------|
| **document_key** * | uuidv4 | Chave única de identificação do documento do **Termo de Abertura de Conta** ou **Contrato de Conta Escrow**. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36                                      |
| **signatures** *   | list   | Dados de assinatura do documento enviado. Cada item da lista, corresponde a um assinante do documento.                                                                                                              | [Objeto signatures](#objeto-signatures) |

### Objeto signatures
| Campo              | Tipo       | Descrição                                                                          | Caracteres                                  |
|--------------------|------------|------------------------------------------------------------------------------------|---------------------------------------------|
| **authenticity** * | object     | Conjunto de dados que evidenciam a assinatura eletrônica realizada pelo assinante. | [Objeto authenticity](#objeto-authenticity) |
| **signer** * | object     | Objeto contendo os dados de um dos assinantes do documento.                        | [Objeto signer](#objeto-signer)             |
| **authentication_type** * | enumerator | Tipo de assinatura. Sempre será "**opt-in**"                                       | "**opt-in**"                                |

### Objeto authenticity
| Campo                      | Tipo   | Descrição                                                                                                                                                                  | Caracteres |
|----------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| **timestamp** *            | string | Data e hora do momento da assinatura do documento.                                                                                                                         | 27         |
| **facial_recognition_key** | uuidv4 | Chave única de identificação da foto da selfie do titular da conta. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36         |
| **lang**                   | string | Coordenada de longitude da geolocalização do assinante capturada no momento da assinatura.                                                                                 | -          |
| **lat**                    | string | Coordenada de latitude da geolocalização do assinante capturada no momento da assinatura.                                                                                  | -          |
| **ip_address**             | string | Endereço IP do dispositivo do assinante.                                                                                                                                   | -          |
| **session_id**             | string | ID da seção do assinante no momento da assinatura.                                                                                                                         | -          |

### Objeto signer
| Campo                 | Tipo   | Descrição                                 | Caracteres                        |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** *            | string | Nome do assinante.                        | -                                 |
| **email** *           | string | Email do assinante.                       | -                                 |
| **phone** *           | object | Objeto com dados do telefone do assinante | **[Objeto phone](#objeto-phone)** |
| **document_number** * | string | CPF do assinante.                         | 11                                |

### Objeto destinations
| Campo                                   | Tipo   | Descrição                                                       | Caracteres |
|-----------------------------------------|--------|-----------------------------------------------------------------|------------|
| **account_branch** *                    | string | Número da Agência da conta destino.                             | 4          |
| **account_number** *                    | string | Número da conta destino.                                        | -          |
| **account_digit** *                     | string | Dígito verificador do número da conta destino.                  | 1          |
| **document_number** *                   | string | CPF/CNPJ do titular da conta destino.                           | -          |
| **name** *                              | string | Nome/Razão Social do titular da conta destino.                  | -          |
| **ispb_number** *                       | string | ISPB (base do CNPJ) da instituição financeira da conta destino. | 8          |
| **financial_institution_code_number** * | string | Código da instituição financeira da conta destino.              | 3          |

### Enumeradores person_type
| Enum        | Description       |
|-------------|-------------------|
| **natural** | Pessoa física     |
| **legal**   | Pessoa jurídica   |

### Enumeradores document_identification_type
| Enum    | Description                            |
|---------|----------------------------------------|
| **rg**  | RG - Registro Geral                    |
| **cnh** | CNH - Carteira Nacional de Habilitação |

### Enumeradores company_type
| Enum                    | 	Description                                                              |
|-------------------------|---------------------------------------------------------------------------|
| **ltda**                | Limitada                                                                  |
| **sa**	                 | Sociedade Anônima                                                         |
| **micro_enterprise**	   | Micro Empresa                                                             |
| **freelancer**          | Freelancer                                                                |
| **sa_opened**           | Sociedade Anônima de Capital Aberto                                       |
| **sa_closed**	          | Sociedade Anônima de Capital Fechado                                      |
| **se_ltda**             | Sociedade Empresária Limitada                                             |
| **se_cn**               | Sociedade Empresária em Nome Coletivo                                     |
| **se_cs**               | Sociedade Empresária em Comandita Simples                                 |
| **se_ca**	              | Sociedade Empresária em Comandita por Ações                               |
| **scp**                 | Sociedade em Conta de Participação                                        |
| **ei**	                 | Empresário Individual                                                     |
| **ese**	                | Estabelecimento, no Brasil, de Sociedade Estrangeira                      |
| **eeab**	               | Estabelecimento, no Brasil, de Empresa Binacional Argentino-Brasileira    |
| **ssp**                 | Sociedade Simples Pura                                                    |
| **ss_ltda**	            | Sociedade Simples Limitada                                                |
| **ss_cn**               | Sociedade Simples em Nome Coletivo                                        |
| **ss_cs**               | Sociedade Simples em Comandita Simples                                    |
| **eireli_ne**           | Empresa Individual de Responsabilidade Limitada (de Natureza Empresária)  |
| **eireli_ns**           | Empresa Individual de Responsabilidade Limitada (de Natureza Simples)     |
| **eireli**              | Empresa de Responsabilidade Individual                                    |
| **mei**                 | Micro Empreendedor Individual                                             |
| **me**	                 | Micro Empresa                                                             |
| **cop**	                | Cooperativa                                                               |
| **private_association** | Sociedade Privada                                                         |
| **association**	        | Associação                                                               |
| **others**              | Outros                                                         |

### Enumeradores marital_status
| Enum         | 	Description  |
|--------------|---------------|
| **single**   | Solteiro(a)   |
| **married**  | Casado(a)    |
| **widower**  | Viúvo(a)     |
| **divorced** | Divorciado(a) |
| **separated** | Separado(a) |

---

# Manual de Aditamento

URL: /documentation/aditamento/manual_aditamento

Este manual descreve o passo a passo envolvido no processo de aditamento. Trata-se do postergamento do prazo da dívida, em que ocorre a mudança na data de vencimento das parcelas e se mantém o número de contrato. 

Nesse processo de aditamento, a `final_debt_key` retornada no webhook de desembolso é a nova chave da operação e, após esse processo, novos boletos das parcelas aditadas serão gerados. 

O aditamento só é válido para operações pré-fixadas.

## 1 - Criação da operação de aditamento

O campo `desired_installments` é uma lista de objetos com o atributo `due_date`.

O campo de `calculate_delay` só está disponível no Response Body se for enviado na requisição de POST.

Nesse momento, como ainda não houve desembolso da operação originada do aditamento, os campos relacionados ao boleto, como `bank_slip_key`, `digitable_line`, `qr_code_key` e `qr_code_url`, serão nulos.

**1.1.** Simulação:

        **Request**

ENDPOINT /amendment_simulation
MÉTODO POST

Request Body

```json
{
	"amendment_debt_key": "\<Chave unitária da operação/debt a ser aditada\>",
	"amendment_date": "\<Nova data de referência para a operação originada a partir aditamento\>",
	"financial": {
		"calculate_delay": "\<Booleano para cálculo de juros de atraso em cima da operação a ser adiatada\>",
        "monthly_rate": "\<Valor em decimal do juros do aditamento ao mês\>", 
		"desired_installments" : [
			{
				"due_date": "\<Nova data de vencimento da parcela\>",
			}
		]
	},
	"additional_data": "\<JSON de campos adicionais livre\>",
}

```

        **Response**

Response Body

```json
{
	"amendment_debt_key": "\<Chave unitária da operação/debt a ser aditada enviada no POST\>",
	"amendment_date": "\<Nova data de referência para a operação, originada a partir da data enviada no POST\>",
	"financial":{
		"calculate_delay": "\<Booleano para cálculo de juros de atraso em cima da operação a ser adiatada\>",
        "monthly_rate": "\<Valor em decimal do juros do aditamento ao mês\>",
		"desired_installments" : [
			{
				"due_date": "\<Nova data de vencimento da parcela\>",
				"total_amount": "\<Valor da parcela\>",
			}
		]
	},
	"additional_data": "\<JSON de campos adicionais livre enviada no POST\>",
	"final_debt": {
		"annual_cet": "\<Custo Efetivo Total anual\>",
		"cet": "\<Custo Efetivo Total mensal\>",
		"installments":{
            "bank_slip_key": "\<Chave unitária do boleto relacionado a parcela\>",
            "business_due_date": "\<Data de vencimento da parcela, considerndo dias úteis\>",
            "calendar_days": "\<Dias corridos em relação a data de referência anterior\>",
            "digitable_line": "\<Linha digitável do boleto\>",
            "due_date": "\<Data de vencimento da parcela\>",
            "due_interest": "\<Valor de Juros da parcela\>",
            "due_principal":"\<Valor Principal da parcela\>",
            "installment_key": "\<Chave unitária característica da parcela\>",
            "installment_number": "\<Número da parcela dentro do total de parcelas\>",
            "post_fixed_amount": "\<Valor de Juros pós-fixado da parcela\>",
            "pre_fixed_amount": "\<Valor de Juros pré-fixado da parcela\>",
            "principal_amortization_amount": "\<Valor de amortização de principal da parcela\>",
            "qr_code_key": "\<Chave unitária do QR Code associado ao boleto\>",
            "qr_code_url": "\<URL do QR Code associado ao boleto\>",
            "total_amount": "\<Valor Total da parcela\>",
            "workdays": "\<Dias úteis em relação a data de referência anterior\>",
        },
		"prefixed_interest_rate": {
			"annual_rate": "\<Taxa anual de juros pré-fixado\>",
        	"daily_rate": "\<Taxa diária de juros pré-fixado\>",
        	"interest_base": "\<Base de cálculo de juros\>",
        	"monthly_rate": "\<Taxa mensal de juros pré-fixado\>",
    	},
		"issue_amount": "\<Valor de emissão da operação de aditamento\>",
		"number_of_installments": "\<Número de parcelas\>",
		"total_iof": "\<IOF da operação\>"
	}
}

```

**1.2.** Criação:

        **Request**

ENDPOINT /amendment
MÉTODO POST

Request Body

```json
{
	"amendment_debt_key": "\<Chave unitária da operação/debt a ser aditada\>",
	"amendment_date": "\<Nova data de referência para a operação originada a partir aditamento\>",
	"financial": {
		"calculate_delay": "\<Booleano para cálculo de juros de atraso em cima da operação a ser adiatada\>",
        "monthly_rate": "\<Valor em decimal do juros do aditamento ao mês\>",
		"desired_installments" : [
			{
				"due_date": "\<Nova data de vencimento da parcela\>",
			}
		]
	},
	"additional_data": "\<JSON de campos adicionais livre\>",
}

```

        **Response**

Response Body

```json
{
	"amendment_key": "\<Chave unitária característica do aditamento\>",
	"amendment_debt_key": "\<Chave unitária da operação/debt a ser aditada enviada no POST\>",
	"amendment_date": "\<Nova data de referência para a operação, originada a partir da data enviada no POST\>",
	"financial":{
		"calculate_delay": "\<Booleano para cálculo de juros de atraso em cima da operação a ser adiatada\>",
        "monthly_rate": "\<Valor em decimal do juros do aditamento ao mês\>",
		"desired_installments" : [
			{
				"due_date": "\<Nova data de vencimento da parcela\>",
				"total_amount": "\<Valor da parcela\>",
			}
		]
	},
	"additional_data": "\<JSON de campos adicionais livre enviada no POST\>",
	"amendment_status": "waiting_signature",
	"document_key": "\<Chave unitária do documento/contrato da operação de aditamento\>",
	"document_url": "\<URL do documento/contrato da operação de aditamento\>",
	"final_debt": {
		"annual_cet": "\<Custo Efetivo Total anual\>",
		"cet": "\<Custo Efetivo Total mensal\>",
		"installments":{
            "bank_slip_key": "\<Chave unitária do boleto relacionado a parcela\>",
            "business_due_date": "\<Data de vencimento da parcela, considerndo dias úteis\>",
            "calendar_days": "\<Dias corridos em relação a data de referência anterior\>",
            "digitable_line": "\<Linha digitável do boleto\>",
            "due_date": "\<Data de vencimento da parcela\>",
            "due_interest": "\<Valor de Juros da parcela\>",
            "due_principal":"\<Valor Principal da parcela\>",
            "installment_key": "\<Chave unitária característica da parcela\>",
            "installment_number": "\<Número da parcela dentro do total de parcelas\>",
            "post_fixed_amount": "\<Valor de Juros pós-fixado da parcela\>",
            "pre_fixed_amount": "\<Valor de Juros pré-fixado da parcela\>",
            "principal_amortization_amount": "\<Valor de amortização de principal da parcela\>",
            "qr_code_key": "\<Chave unitária do QR Code associado ao boleto\>",
            "qr_code_url": "\<URL do QR Code associado ao boleto\>",
            "total_amount": "\<Valor Total da parcela\>",
            "workdays": "\<Dias úteis em relação a data de referÊncia anterior\>",
        },
		"prefixed_interest_rate": {
			"annual_rate": "\<Taxa anual de juros pré-fixado\>",
        	"daily_rate": "\<Taxa diária de juros pré-fixado\>",
        	"interest_base": "\<Base de cálculo de juros\>",
        	"monthly_rate": "\<Taxa mensal de juros pré-fixado\>",
    	},
		"issue_amount": "\<Valor de emissão da operação de aditamento\>",
		"number_of_installments": "\<Número de parcelas\>",
		"total_iof": "\<IOF da operação\>"
	}
}

```

Em relação a simulação, o Response Body da criação se diferencia pela presença da `amendment_key`, da `amendment_status`, da `document_key` e da `document_url`.

Na criação do operação de aditamento, sempre se retorna o `amendment_status` como "waiting_signature". 

## 2 - GET da operação de aditamento
        **Request**

ENDPOINT /amendment/[AMENDMENT_KEY]
MÉTODO GET

O `amendment_key` que deve ser enviado para realização do GET é o valor do campo, de mesmo nome, retornado na criação da operação de aditamento e que representa a chave unitária característica do aditamento.

        **Response**

Response Body

```json
{
	"amendment_key": "\<Chave unitária característica do aditamento\>",
	"amendment_debt_key": "\<Chave unitária da operação/debt a ser aditada enviada no POST\>",
	"amendment_date": "\<Nova data de referência para a operação, originada a partir da data enviada no POST\>",
	"financial":{
		"calculate_delay": "\<Booleano para cálculo de juros de atraso em cima da operação a ser adiatada\>",
        "monthly_rate": "\<Valor em decimal do juros do aditamento ao mês\>",
		"desired_installments" : [
			{
				"due_date": "\<Nova data de vencimento da parcela\>",
				"total_amount": "\<Valor da parcela\>",
			}
		]
	},
	"additional_data": "\<JSON de campos adicionais livre enviada no POST\>",
	"amendment_status":  "\<Status do aditamento\>",
	"document_key": "\<Chave unitária do documento/contrato da operação de aditamento\>",
	"document_url": "\<URL do documento/contrato da operação de aditamento\>",
	"final_debt": {
		"annual_cet": "\<Custo Efetivo Total anual\>",
		"cet": "\<Custo Efetivo Total mensal\>",
		"installments":{
            "bank_slip_key": "\<Chave unitária do boleto relacionado a parcela\>",
            "business_due_date": "\<Data de vencimento da parcela, considerndo dias úteis\>",
            "calendar_days": "\<Dias corridos em relação a data de referência anterior\>",
            "digitable_line": "\<Linha digitável do boleto\>",
            "due_date": "\<Data de vencimento da parcela\>",
            "due_interest": "\<Valor de Juros da parcela\>",
            "due_principal":"\<Valor Principal da parcela\>",
            "installment_key": "\<Chave unitária característica da parcela\>",
            "installment_number": "\<Número da parcela dentro do total de parcelas\>",
            "post_fixed_amount": "\<Valor de Juros pós-fixado da parcela\>",
            "pre_fixed_amount": "\<Valor de Juros pré-fixado da parcela\>",
            "principal_amortization_amount": "\<Valor de amortização de principal da parcela\>",
            "qr_code_key": "\<Chave unitária do QR Code associado ao boleto\>",
            "qr_code_url": "\<URL do QR Code associado ao boleto\>",
            "total_amount": "\<Valor Total da parcela\>",
            "workdays": "\<Dias úteis em relação a data de referência anterior\>",
        },
		"prefixed_interest_rate": {
			"annual_rate": "\<Taxa anual de juros pré-fixado\>",
        	"daily_rate": "\<Taxa diária de juros pré-fixado\>",
        	"interest_base": "\<Base de cálculo de juros\>",
        	"monthly_rate": "\<Taxa mensal de juros pré-fixado\>",
    	},
		"issue_amount": "\<Valor de emissão da operação de aditamento\>",
		"number_of_installments": "\<Número de parcelas\>",
		"total_iof": "\<IOF da operação\>"
	}
}

```

        **Response Canceled**

Response Body

```json
{
	"amendment_key": "\<Chave unitária característica do aditamento\>",
	"amendment_debt_key": "\<Chave unitária da operação/debt a ser aditada enviada no POST\>",
	"amendment_date": "\<Nova data de referência para a operação, originada a partir da data enviada no POST\>",
	"financial":{
		"calculate_delay": "\<Booleano para cálculo de juros de atraso em cima da operação a ser adiatada\>",
        "monthly_rate": "\<Valor em decimal do juros do aditamento ao mês\>",
		"desired_installments" : [
			{
				"due_date": "\<Nova data de vencimento da parcela\>",
				"total_amount": "\<Valor da parcela\>",
			}
		]
	},
	"additional_data": "\<JSON de campos adicionais livre enviada no POST\>",
	"amendment_status":  "canceled",
	"cancel_reason": {
		"enumerator": "non_signed_amendment",
		"description": "It wasn't possible to effect the amendment of the operation, because the amended operation hasn't been signed until the sent reference date (2023-09-19).",
		"translation": "Não foi possível efetivar o aditamento da operação, pois a operação de aditamento não foi assinada até a data de referência enviada (2023-09-19)."
	},
	"document_key": "\<Chave unitária do documento/contrato da operação de aditamento\>",
	"document_url": "\<URL do documento/contrato da operação de aditamento\>",
	"final_debt": {
		"annual_cet": "\<Custo Efetivo Total anual\>",
		"cet": "\<Custo Efetivo Total mensal\>",
		"installments":{
            "bank_slip_key": "\<Chave unitária do boleto relacionado a parcela\>",
            "business_due_date": "\<Data de vencimento da parcela, considerndo dias úteis\>",
            "calendar_days": "\<Dias corridos em relação a data de referência anterior\>",
            "digitable_line": "\<Linha digitável do boleto\>",
            "due_date": "\<Data de vencimento da parcela\>",
            "due_interest": "\<Valor de Juros da parcela\>",
            "due_principal":"\<Valor Principal da parcela\>",
            "installment_key": "\<Chave unitária característica da parcela\>",
            "installment_number": "\<Número da parcela dentro do total de parcelas\>",
            "post_fixed_amount": "\<Valor de Juros pós-fixado da parcela\>",
            "pre_fixed_amount": "\<Valor de Juros pré-fixado da parcela\>",
            "principal_amortization_amount": "\<Valor de amortização de principal da parcela\>",
            "qr_code_key": "\<Chave unitária do QR Code associado ao boleto\>",
            "qr_code_url": "\<URL do QR Code associado ao boleto\>",
            "total_amount": "\<Valor Total da parcela\>",
            "workdays": "\<Dias úteis em relação a data de referência anterior\>",
        },
		"prefixed_interest_rate": {
			"annual_rate": "\<Taxa anual de juros pré-fixado\>",
        	"daily_rate": "\<Taxa diária de juros pré-fixado\>",
        	"interest_base": "\<Base de cálculo de juros\>",
        	"monthly_rate": "\<Taxa mensal de juros pré-fixado\>",
    	},
		"issue_amount": "\<Valor de emissão da operação de aditamento\>",
		"number_of_installments": "\<Número de parcelas\>",
		"total_iof": "\<IOF da operação\>"
	}
}

```

## 3 - Cancelamento da operação de aditamento
        **Request**

ENDPOINT /amendment/[AMENDMENT_KEY]
MÉTODO DELETE

O `amendment_key` que deve ser enviado para realização do DELETE é o valor do campo, de mesmo nome, retornado na criação da operação de aditamento e que representa a chave unitária característica do aditamento.

No DELETE do aditamento, não há payload de resposta e o status da operação de aditamento é alterado para "canceled".

## 4 - Webhooks

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

Abaixo estão descritos os webhooks que serão enviados nas situações de assinatura, de desembolso e de cancelamento da operação de aditamento. 

**4.1.** Assinatura:

Body

```json
{
    "webhook_type": "amendment",
	"amendment_key": "\<Chave unitária característica do aditamento\>",
    "event_datetime": "\<String de data referente ao momento de assinatura no formato da ISO8601\>",
    "data": {
            "amendment_status": "signed",
            "document_key": "\<Chave unitária do documento/contrato da operação de aditamento\>",
            "signed_document_url": "\<URL do documento/contrato da operação de aditamento assinado\>"
            }
}

```

**4.2.** Desembolso:

Body

```json
{
	"webhook_type": "amendment",
	"amendment_key": "\<Chave unitária característica do aditamento\>",
	"event_datetime": "\<String de data referente ao momento de desembolso no formato da ISO8601\>",
	"data": {
		"amendment_status": "disbursed",
		"final_debt_key": "\<Chave unitária da operação/debt originada do aditamento\>",
		"installments": [
			{
            "bank_slip_key": "\<Chave unitária do boleto relacionado a parcela\>",
            "business_due_date": "\<Data de vencimento da parcela, considerndo dias úteis\>",
            "calendar_days": "\<Dias corridos em relação a data de referência anterior\>",
            "digitable_line": "\<Linha digitável do boleto\>",
            "due_date": "\<Data de vencimento da parcela\>",
            "due_interest": "\<Valor de Juros da parcela\>",
            "due_principal":"\<Valor Principal da parcela\>",
            "installment_key": "\<Chave unitária característica da parcela\>",
            "installment_number": "\<Número da parcela dentro do total de parcelas\>",
            "post_fixed_amount": "\<Valor de Juros pós-fixado da parcela\>",
            "pre_fixed_amount": "\<Valor de Juros pré-fixado da parcela\>",
            "principal_amortization_amount": "\<Valor de amortização de principal da parcela\>",
            "qr_code_key": "\<Chave unitária do QR Code associado ao boleto\>",
            "qr_code_url": "\<URL do QR Code associado ao boleto\>",
            "total_amount": "\<Valor Total da parcela\>",
            "workdays": "\<Dias úteis em relação a data de referência anterior\>"
        }
	]
	}
}

```

**4.3.** Cancelamento:

Body

```json
{
    "webhook_type": "amendment",
	"amendment_key": "\<Chave unitária característica do aditamento\>",
    "event_datetime": "\<String de data referente ao momento de desembolso no formato da ISO8601\>",
    "data": {
		"amendment_status": "canceled",
		"cancel_reason": {
			"enumerator": "\<Enumerador do motivo de cancelamento\>",
			"description": "\<Descrição do motivo de cancelamento em inglês\>",
			"translation": "\<Tradução da descrição do motivo de cancelamento\>"
		}
	}
}

```

A cancel_reason segue os seguintes enumeradores: **[Enumerador Cancel Reason](#enumerador-cancel-reason)**.

## 5 - Informações Gerais

A referência anterior nos campos `calendar_days` ou `workdays` é a data de desembolso na primeira parcela e a data de vencimento da parcela anterior nos demais casos.

O campo installments é uma lista preenchida de objetos. Nesse caso, para cada parcela do aditamento, deve haver um objeto com as respectivas informações.

| Campo | Tipo | Exemplo | Observações |
|---| ---| ---| ---|
| `additional_data` | json | { } | Não é obrigatório seu envio |
| `amendment_key` | string | 5fd3ecc8-1ea5-4d23-835c-37338da96181 | |
| `amendment_date` | string | "2023-06-05" | |
| `amendment_debt_key` | string | 31327efa-a96e-4a17-b703-e9fc39e17902 | |
| `amendment_status` | enumerador | **[Enumerador Amendment Status](#enumerador-amendment-status)** | |
| `annual_cet`	| float | 0.0012 | |
| `annual_rate`	| float | 0.0012 | |
| `bank_slip_key` | string | aea9ab16-d211-4c17-8f46-8a2669154a37 | |
| `business_due_date` | string | "2023-10-05" | |
| `calculate_delay` | bool | True | Não é obrigatório seu envio e é default como Falso |
| `calendar_days` | int | 27 | |
| `cet`	| float | 0.0012 | |
| `daily_rate` | float | 0.0012 | |
| `digitable_line` | string | 32990001031000699925351000000201192690000055231 | |
| `document_key` | string | 7f49d9ff-0878-4d48-8cc3-cb0c3c6769d2 | |
| `document_url` | string | "https://storage.googleapis.com/sandbox-doc-api/documents/7f49d9ff-0878-4d48-8cc3-cb0c3c6769d2/image_166618030043.jpg" | |
| `due_date`	| string | "2023-06-05" | |
| `due_interest`	| float | 0.0 | |
| `due_principal`	| float | 1000.10 | |
| `event_datetime` | string |	"2023-05-05T22:20:10Z" | |
| `final_debt_key` | string | 8779a554-1ec9-40ec-8ff2-cbd52fc776ef | Essa é a nova debt key  |
| `installment_number` | int | 3 | |
| `installment_key` | string | 1b65d775-b5ab-49d5-a833-46980387afb1	| |
| `interest_base` | enumerador | **[Enumerador Interest Base](#enumerador-interest-base)** | |
| `issue_amount` | float | 1000.00 | |
| `monthly_rate` | float | 0.0012 | |
| `number_of_installments` | int | 3 | |
| `post_fixed_amount` | int | 0 | Sempre zero, já que o aditamento só é válido para operações pré-fixadas |
| `pre_fixed_amount` | float | 2.00 | |
| `principal_amortization_amount` | float | 20.00 | |
| `qr_code_key` | string | 003590d0-29f8-4d18-93bb-a7c36f0f1785	| |
| `qr_code_url` | string | "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/cf7d2d2e-003a-4296-9daf-350864d282245204000053039865802BR5925QI SOCIEDADE DE CREDITO D6009Sao Paulo61080145200062070503***63047335"| |
| `signed_document_url` | string | "https://storage.googleapis.com/sandbox-doc-api/documents/7f49d9ff-0878-4d48-8cc3-cb0c3c6769d2/image_166618030043.jpg" | |
| `total_amount` | float | 100.00 |  |
| `total_iof` | float | 11.03 |  |
| `workdays` | int | 10 |  |

### Enumerador _Interest Base_
| Enumerador            | Descrição                                                                 |
|-----------------------|---------------------------------------------------------------------------|
| **workdays**          | Base de cálculo de juros em dias úteis considerando um ano de 252 dias    |
| **calendar_days**     | Base de cálculo de juros em dias corridos considerando um ano de 360 dias |
| **calendar_days_365** | Base de cálculo de juros em dias corridos considerando um ano de 365 dias |

### Enumerador _Amendment Status_
| Enumerador            | Descrição                                                                 |
|-----------------------|---------------------------------------------------------------------------|
| **waiting_signature** | Aguardando assinatura													    |
| **signed**     		| Assinada																    |
| **disbursed** 		| Desembolsada															    |
| **canceled** 			| Cancelada																    |
| **disbursing_error**	| Erro no momento do desembolso											    |

:::caution Atenção!
O status 'disbursing_error' representa um status intermediário, o contrato de aditamento será cancelado ou desembolsado.
:::

### Enumerador _Cancel Reason_
| Enumerador            	| Descrição                                                                    |
|---------------------------|------------------------------------------------------------------------------|
| **delete_amendment** 		| Requisição no endpoint de DELETE											   |
| **non_signed_amendment**  | Operação de aditamento não foi assinada até a data de referência enviada (amendment_date)															    |
| **different_balance_due** | Saldo devedor diferente entre a criação da operação de aditamento e o desembolso															         |
| **different_installments_number** | Número de parcelas em aberto diferente entre a criação da operação de aditamento e o desembolso																	|

---

# Realizar agendamento de pagamento de boleto

URL: /documentation/agendamentos/agendamento_boleto

Segue o mesmo príncipio do pagamento em outros fluxos, tendo como principal diferença que deve ser enviado o schedule_date e nesse caso você receberá a schedule_key.

## Request

ENDPOINT /bank_slip/payment
MÉTODO POST

Request Body

```json
{
    "digitable_line": "32990001031000000001708001075103794890000015000",
    "source_account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
    "payment_date": "2023-09-25",
    "transaction_amount": 150.00
}

```

### Body params

| Campo                    | Tipo   | Descrição                                                         | Caracteres |
|--------------------------|--------|-------------------------------------------------------------------|------------|
| `digitable_line` *       | string | Linha digitável do boleto.                                        | -          |
| `resource_account_key` * | string | Chave da conta que será utilizada.                                | -          |
| `payment_date` *         | date   | Data para a realização do pagamento. Se não enviada a data será hoje. | -          |
| `transaction_amount`           | float  | Valor a ser pago.                                                 | -          |

:::info Informação

Para visualizar os convênios de pagamentos aceitos, [clique aqui](https://storage.googleapis.com/live-doc-api/public_samples/convenios_qi_tech.xlsx) .

:::

## Response

STATUS 200

Response Body: Pagamento através de uma conta livre

```json
{
    "data": {
        "digitable_line": "09990001029100010009895007444201283400000001000",
        "resource_account_key": "21af482f-b8ac-48dd-8f9a-ea23429d28be"
    },
    "event_datetime": "2020-08-06 19:22:06",
    "key": "e7719f95-a31d-4171-ae83-2d8b3d419dc2",
    "status": "waiting_approval",
    "webhook_type": "bank_slip_payment"
    "schedule_key": "e7719f95-a31d-4171-ae83-2d8b3d419dc2"
}

```

STATUS 200

Response Body: Pagamento através de uma conta escrow

```json
{
    "data": {
        "digitable_line": "09990001029100010009895007444201283400000001000",
        "resource_account_key": "21af482f-b8ac-48dd-8f9a-ea23429d28be"
    },
    "event_datetime": "2020-08-06 19:22:06",
    "key": "e7719f95-a31d-4171-ae83-2d8b3d419dc2",
    "status": "waiting_approval",
    "webhook_type": "bank_slip_payment",
    "schedule_key": "e7719f95-a31d-4171-ae83-2d8b3d419dc2"
}

```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

---

# Agendar transferência Pix

URL: /documentation/agendamentos/agendamento_pix

Segue o mesmo princípio da transferência pix, tendo como principal diferença que deve ser enviado o schedule_date e nesse caso você receberá a schedule_key.

## Request

ENDPOINT /baas/pix_transfer
MÉTODO POST

**Manual**
Request Body: Transferência Manual

```json
    {
        "pix_transfer_type": "manual",
        "source_account": {
            "account_branch": "0001",
            "account_digit": "2",
            "account_number": "2359934",
            "owner_document_number": "09080702000105"
        },
        "schedule_date": "2023-08-24",
        "target_account": {
              "bank_code": "104",
              "account_branch": "0001",
              "account_digit": "4",
              "account_number": "6717606",
              "owner_document_number": "60744463000190",
              "owner_name": "Qi Tech",
              "account_type": "checking",
              "ispb": "32402502"
         },
        "transaction_amount": 15
    }

```

## Response

STATUS 200
Response Body: Transferência manual

```json

{
  "data": {
      "operation_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "status": "pending",
      "event_datetime": "2021-08-04 20:05:54",
      "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "pix_transaction": {
        "pix_message": "",
        "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
        "transaction_amount": 1891268.97,
        "source_account": {
          "account_branch": "0001",
          "account_digit": "3",
          "account_number": "24339",
          "owner_document_number": "32402502000135",
          "owner_name": "Qi Tech",
          "account_type": "checking"
        },
        "target_account": {
          "target_account": "78340-6",
          "financial_institution_code": "329",
          "owner_document_number": "32402502000135",
          "owner_name": "QI Tech",
          "target_account_type": "checking_account",
          "owner_person_type": "legal",
          "trading_name": "QITech"
        },
        "fee_amount": 0,
        "schedule_date": "2020-08-04"
      }
    }
}

```
**Chave**
Request Body: Transferência Chave

```json
        {
            "pix_transfer_type": "key",
            "source_account": {
                "account_branch": "0001",
                "account_digit": "2",
                "account_number": "2359934",
                "owner_document_number": "09080702000105"
            },
            "schedule_date": "2023-08-24",
            "end_to_end_id":	"E32402502202308231745g1goFJ577mp",
            "pix_key":"52720072800",
            "target_account": {
                  "bank_code": "104",
                  "account_branch": "0001",
                  "account_digit": "4",
                  "account_number": "6717606",
                  "owner_document_number": "60744463000190",
                  "owner_name": "Qi Tech",
                  "ispb": "32402502"
             },
            "transaction_amount": 15
        }

```

## Response

STATUS 200
Response Body: Transferência chave

```json
{
  "data": {
    "end_to_end_id": "E32402502202308231825nkKhXiA9DEA",
    "fee_amount": 1,
    "pix_message": "",
    "pix_transfer_key": "c32ad14a-6bfe-43f4-b5a1-4f335dcdd543",
    "source_account": {
      "account_brach": "0001",
      "account_digit": "2",
      "account_number": "2359934",
      "account_type": "checking",
      "owner_document_number": "09080702000105",
      "owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
    },
    "target_account": {
      "document_number": "***.951.18*-**",
      "financial_institution": "CAIXA ECONOMICA FEDERAL"
    },
    "transaction_amount": 15,
    "transfer_purpose": "transfer"
  },
  "event_datetime": "2023-08-23 15:25:36",
  "operation_key": "b37224f2-9a8c-4816-b446-acb213bfe5f0",
  "schedule_key": "c32ad14a-6bfe-43f4-b5a1-4f335dcdd543",
  "status": "pending_approval"
}

```

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `pix_transfer_type` * | string | O Pix possui diferentes tipos de iniciação, o "manual" onde o usuário deve enviar os campos da conta de destino e conta de origem e o "key" onde o usuário deve enviar os campos da chave Pix do recebedor (conta de destino) e os dados da conta de origem. | 10 |
| `source_account` * | Object | Conta de origem. | **[Objeto source_account](#objeto-source_account)** | 
| `target_account` | Object | Conta destino - Só deve ser enviada em transações do tipo "manual". | **[Objeto target_account](#objeto-target_account)** | 10 |
| `transaction_amount` * | string | Valor da transferencia. | 10 | 
| `schedule_date` | date | Data de agendamento da transação (caso não seja enviado a transferência é realizada no momento da aprovação).  | 10 |
| `receiver_conciliation_id` | string | Identicação de conciliação do recebedor. | 10 |
| `is_chargeback` | string | Flag de identificação de uma devolução de transação Pix (booleano True ou False). | 10 |
| `requester_document_identification` * | string | CPF do usuário quem está solicitando a transferência. | 10 |
| `pix_transfer_key` | string | Chave de idempotência de uma transação Pix - só deve ser enviado se o tipo de transferência for "key". | 10 |
| `chargeback_amount` | string | Valor da devolução - Este campo deve ser enviado apenas em caso de chargeback e exclui a obrigatoriedade do campo "transaction_amount". |  10 |
| `chargeback_other_reason` | string | Motivo de devolução ( Este campo deve ser enviado apenas em caso de chargeback). | 10 |
| `chargeback_message` | string | Campo para usuário inserir mensagem durante a devolução ( Este campo deve ser enviado apenas em caso de chargeback). | 10 |
 
### Objeto source_account

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `account_branch` * | string | Número Agência. | 0 |
| `branch_digit` |string | Dígito da Agência.| 0 |
| `account_digit` * | string | Dígito da conta.| 0 |
| `account_number` * | string | Número da conta.| 0 | 
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta.| 0 |

### Objeto target_account

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `account_branch` * | string | Agência. | 10 |
| `account_digit` * | string | Dígito da conta | 10 |
| `account_number` * | string | Número da conta. | 10 |
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta. | 10 |
| `owner_name` * | string | Nome do titular da conta. | 10 |
| `account_type` * |string |  CPF ou CNPJ (apenas números) do titular da conta.| 10 |
| `trading_name` | string |  Nome fantasia para pessoa jurídica.| 10 |
| `ispb` | string |  Código de oito dígitos que identifica os bancos no sistema de transferência de reserva do Banco Central.| 10 |

## Response

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

---

# Realizar transferência

URL: /documentation/agendamentos/agendamento_ted

Segue o mesmo príncipio da transferência comum, tendo como principal diferença que deve ser enviado o schedule_date e nesse caso você receberá a schedule_key.

## Request

ENDPOINT /wire_transfer
MÉTODO POST

Request Body

```json
{
    "source_account": {
        "account_branch": "0001",
        "account_number": "9477323",
        "account_digit": "0",
        "owner_document_number": "38299588000107"
    },
    "target_account": {
        "financial_institution_code": "341",
        "account_branch": "0001",
        "account_number": "92796",
        "account_digit": "1",
        "owner_document_number": "23599885000192",
        "owner_name": "plugify"
    },
    "schedule_date": "2023-10-10",
    "transaction_amount": 8.86
}

```

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `source_account` * | object | Conta de origem. | **[Objeto source_account](#objeto-source_account)** | 
| `target_account` * |  object | Conta de destino. | **[Objeto target_account](#objeto-target_account)** | 
| `transaction_amount` * | double | Valor da transferência. | 10 |
| `schedule_date` * | date |  Data de agendamento da transação, se não especificado a transação será realizada no momento do envio ou assim que aprovada. | 10 |

### Objeto source_account

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `account_branch` * |  string | Agência. | 10 |
| `account_digit` * |  string | Dígito da conta | 10 |
| `account_number` * | string | Número da conta. | 10 |
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta. | 10 |
| `target_account_type` * |  string | Tipo da conta destino |  **[Enumeradores](#enumeradores-ted_account_type)** |

### Objeto target_account

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `account_branch` * | string | Agência. | 10 |
| `account_digit` * | string | Dígito da conta | 10 |
| `account_number` * | string | Número da conta. | 10 |
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta. | 10 |
| `owner_name` * | string | Nome do titular da conta. | 10 |

### Enumeradores target_account_type

| Enumerador | Tradução |
|---|---|
|  checking_account  | conta corrente |
|  deposit_account  |  conta depósito  |
|  guaranteed_account  |  conta de garantia  |
|  investment_account  |  conta de investimento |
|  payment_account  | conta de pagamento |
|  saving_account  | conta poupança  |

## Response
### Transferência a partir de uma conta de livre movimentação

STATUS 200

Response Body

```json
{
  "data": {
    "outgoing_ted_key": null,
    "schedule_date": "2023-10-10",
    "schedule_key": "3be3e5ef-5e43-4d04-b987-be80ae983529",
    "source_account": {
      "account_branch": "0001",
      "account_digit": "0",
      "account_number": "9477323",
      "owner_document_number": "38299588000107"
    },
    "target_account": {
      "account_branch": "0001",
      "account_digit": "1",
      "account_number": "92796",
      "financial_institution_code": "341",
      "owner_document_number": "23599885000192",
      "owner_name": "plugify"
    },
    "transaction_amount": 8.86
  },
  "event_datetime": "2023-08-23 19:40:54",
  "key": "2b198f4d-1b1d-4116-8cd6-ec3da64e6b96",
  "status": "success",
  "webhook_type": "wire_transfer"
}

```

### Transferência a partir de uma conta de escrow

STATUS 200

Response Body

```json
{
  "data": {
    "source_account": {
      "account_branch": "0001",
      "account_digit": "3",
      "account_number": "24339",
      "owner_document_number": "32402502000135"
    },
    "target_account": {
      "account_branch": "0001",
      "account_digit": "6",
      "account_number": "78340",
      "financial_institution_code": "329",
      "owner_document_number": "32402502000135",
      "owner_name": "QI Tech"
    },
    "transaction_key": "7986dcc7-4331-478f-af47-adfbdf7f4a36",
    "transaction_amount": 1891268.97
  },
  "event_datetime": "2019-11-28 19:22:04",
  "key": "fa80723e-4f9a-42b1-9410-d5fa3c183fa8",
  "status": "success",
  "webhook_type": "wire_transfer"
}

```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

---

# Cancelar agendamento

URL: /documentation/agendamentos/cancelar_agendamento

## Request

ENDPOINT /account/transaction/schedule/SCHEDULED_TRANSACTION_KEY/cancel
MÉTODO PATCH

Request Body

```json
{
            "reason": "reason (opcional)"
}

```

### Path Params

| Campo         | Tipo   | Descrição                          |
|---------------|--------|------------------------------------|
| `SCHEDULED_TRANSACTION_KEY` | string | Chave que identifica o agendamento |

Response Body

```json
{}
```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

:::danger Observações Gerais:
Apenas são passíveis de cancelamento os agendamentos aprovados quando a aprovação for aplicável!
:::

---

# Consulta de transações agendadas

URL: /documentation/agendamentos/consulta_agendamentos

## Request

ENDPOINT /account/ACCOUNT_KEY/scheduled_transactions
MÉTODO GET

### QUERY PARAMS

| Campo                | Descrição                                  |
|----------------------|--------------------------------------------|
| `status`             | status de um boleto                        |
| `date`               | Data do agendamento.         |
| `page_number`        | Página atual que está sendo consultada     |
| `page_size`          | Quantidade de resultados por página        |

### Path Params

| Campo                | Descrição                                  |
|----------------------|--------------------------------------------|
| `ACCOUNT_KEY`        | account_key da conta de origem das transações|

## Response

STATUS 200

Response Body

```json
{
  "data": [{
    "outgoing_pix_key": "chave da schedule",
    "outgoing_ted_key": "chave da schedule",
    "schedule_date": "iso date string",
    "source_account_key": "chave da conta de origem da transação",
    "target_account_bank_code": "banco destino (opcional)",
    "target_account_bank_ispb": "ispb destino (opcional)",
    "target_account_branch": "agencia destino",
    "target_account_number": "conta de destino",
    "target_account_digit": "digito conta destino",
    "target_account_type": "tipo de conta destino (opcional)",
    "beneficiary_name": "nomoe do beneficiario",
    "beneficiary_document_number": "documento do beneficiario (cpf/cnpj)",
    "scheduled_amount": "valor agendadp",
    "beneficiary_person_type": "tipo de beneficiario",
    "target_account_key": "chave da conta destino (opcional)",
    "source_subtype": "tipo de transação (enum)",
    "created_at": "data em que o agendamento foi feito",
    "status": "status do agendamento",
    "pix_key": "chave pix destino (opcional)",
    "cancellation_requester": "identificação do requisitor do cancelamento",
    "cancellation_reason": "origem do cancelamento (enum)",
    "updated_at": "data de atualização"
  }],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "rows_per_page": 10
  }
}
```

:::danger Observações Gerais:
Apenas serão listados os agendamentos aprovados quando a aprovação for aplicável!
:::

---

# arranjos_e_adquirentes

URL: /documentation/arranjos_e_adquirentes/

## Arranjos e Adquirentes

### Adquirentes

As adquirentes são empresas como a Stone, a Cielo e a Rede, e seu papel é liquidar as transações financeiras por meio de cartão de crédito e débito. Para isso, elas se comunicam com as bandeiras de cartão e os bancos emissores (como Nubank, Itaú, Santander etc.) para processar as transações.

Lista de adquirentes:

| Nome | CNPJ |
|---|---|
|BRB – BANCO DE BRASÍLIA S.A|208000100|
|CIELO S.A.|1027058000191|
|BANCO COOPERATIVO SICREDI S.A.|1181521000155|
|REDECARD S.A.|1425787000104|
|CREDICARD|1425787003383|
|VERDECARD ADMINISTRADORA DE CARTÕES S.A.|1722480000167|
|WORLDPAY DO BRASIL PROCESSAMENTO DE PAGAMENTOS LTDA|991143000102|
|BANCO COOPERATIVO DO BRASIL S.A.|2038232000164|
|CABAL BRASIL LTDA|3766873000106|
|CRED-SYSTEM|4670195000138|
|FD DO BRASIL SOLUÇÕES DE PAGAMENTO LTDA|4962772000165|
|PAGSEGURO INTERNET S.A.|8561701000101|
|ELO SERVIÇOS S.A|9227084000175|
|GETNET ADQUIRENCIA E SERVIÇOS PARA MEIOS DE PAGAMENTO S.A.|10440482000154|
|MERCADO.COM REPRESENTAÇÕES LTDA|10573521000515|
|ELAVON DO BRASIL SA|12592831000189|
|SAQUE E PAGUE REDE DE AUTOATENDIMENTO|12901364000121|
|HUB PAGAMENTOS S.A.|13884775000119|
|ADYEN DO BRASIL LTDA|14796606000190|
|STONE PAGAMENTOS S.A.|16501555000157|
|BANCO TRIÂNGULO S.A|17351180000159|
|CLOUDWALK MEIOS DE PAGAMENTOS E SERVICOS LTDA|18189547000142|
|BANCO BONSUCESSO S.A. ADQUIRENTE|20520298000178|
|BANCO BONSUCESSO S.A. ADQUIRENTE|20520298000178|
|STRIPE BRASIL SOLUÇÕES DE PAGAMENTO LTDA|22121209000146|
|BMG GRANITO SOLUÇÕES EM PAGAMENTO S.A|22177858000169|
|BOLT CARD CREDENCIADORA DE CARTAO DE CREDITO LTDA|28080769000186|
|BEN BENEFÍCIOS E SERVIÇOS S.A.|30798783000161|
|LISTO INSTITUIÇÃO DE PAGAMENTO LTDA|32971064000126|
|ACQIO ADQUIRÊNCIA S.A|33171211000146|
|BANCO SAFRA S.A.|58160789000128|
|BANCO SMARTBANK S.A.|58497702000102|
|SOROCRED MEIOS DE PAGAMENTO|60114865000100|
|BANCO CREFISA S.A|61033106000186|
|BANCO RENDIMENTO S.A|68900810000138|
|BANRISUL CARTÕES S.A|92934215000106|
|Global Payments - Servicos de Pagamentos S.a.|17887874000105|
|POVIG TECNOLOGIA EM PAGAMENTOS ELETRONICOS LTDA.|35524559000103|

### Arranjos de Pagamentos

Os arranjos de pagamentos são, basicamente, um conjunto de regras, regulamentos e processos que permitem a realização de serviços financeiros, como saques, transferências, emissão de cartão de crédito, débito e outras soluções de pagamento.

Lista de arranjos:

| Código | Descrição |
|---|---|
|ACC|Amex Cartão de Crédito|
|BCC|Banescard Cartão de Crédito|
|BCD|Banescard Cartão de Débito|
|BVV|Banescard Cartão de Débito|
|BVV|Ben Visa Vale|
|CAC|Cielo Amex Crédito|
|CBC|Cabal Crédito|
|CBD|Cabal Débito|
|CBP|Cabal Pré-pago|
|CDC|Cielo Diners Cartão de Crédito|
|CEC|Cielo Elo Cartão de Crédito|
|CED|Cielo Elo Cartão de Débito|
|CHC|Cielo Hipercard Crédito|
|CMC|Cielo Mastercard Crédito|
|CMD|Cielo Mastercard Débito|
|CZC|Credz Crédito|
|DCC|Diners Cartão de Crédito|
|ECC|Elo Cartão de Crédito|
|ECD|Elo Cartão de Débito|
|GCC|Goodcard Crédito|
|GDC|Global Payments Diners Crédito|
|GMC|Global Payments Mastercard Crédito|
|GMD|Global Payments Mastercard Débito|
|GVC|Global Payments Visa Crédito|
|GVD|Global Payments Visa Débito|
|HCC|Hipercard Cartão de Crédito|
|JCC|JCB Cartão de Crédito|
|MAC|Mais Cartão de Crédito|
|MCA|Mastercard Cartão ATM|
|MCC|Mastercard Cartão de Crédito|
|MCD|Mastercard Cartão de Débito|
|MCP|Mastercard Cartão Pré-pago|
|OCD|Ourocard Cartão de Débito|
|SCC|Sorocred Cartão de Crédito|
|SCD|Sorocred Cartão de Débito|
|VCA|Visa Cartão ATM|
|VCC|Visa Cartão de Crédito|
|VCD|Visa Cartão de Débito|
|VCP|Visa Cartão Pré-pago|
|VDC|Verdecard Cartão de Crédito|
|VIC|Visa Internacional Compra Crédito|
|VID|Visa Internacional Compra Débito|
|HCD|Hiper Débito|
|SIC|Sicredi|
|BRS|Banrisul|
|CUP|Cup Crédito|
|FRC|Fortbrasil|
|MXC|Maxifrota|
|SFC|Senff|
|TKC|TicketLog|
|BNC|Banese Card|
|BRC|Brasil Card|
|SPC|Sem Parar|
|CSC|Credi-Shop|
|DAC|Dacasa|
|AGC|Agiplan|
|AUC|Aura|
|RCC|Redesplan|
|AVC|Avista|
|CCD|Calcard|
|DBC|Discover|
|99T|Todas|

---

# Criar uma renegociação

URL: /documentation/arranjos_e_adquirentes/consulta_de_agenda

## Request

ENDPOINT /debt
MÉTODO POST

Request Body

```json
{
  "notification_type": "webhook",
  "owner_person_type": "legal",
  "owner_person_name": "John Sample Inc",
  "owner_document_number": "86498542000151",
  "reference_code": "5830c2f9-fd17-4c9c-b30c-68ddd1a92751",
  "signature": {
    "signers": [
      {
        "name": "John Sample",
        "email": "john.sample@yopmail.com",
        "person_type": "natural",
        "document_number": "42889916090"
      }
    ]
  },
  "agenda": {
    "acquirers": [
      "cdc"
    ],
    "card_schemes": [
      "cdc"
    ],
    "end_date": "2021-06-23",
    "start_date": "2021-06-23"
  }
}

```

:::caution Atenção!

O payload ultilizado na emissão de um refinanciamento é o mesmo ultilizado na emissã de uma divida simples, com a adição da lista de operações que serão quitadas em **"refinanced_credit_operations"**.
:::

### Body Params

| Campo                           | Tipo   | Descrição                                                                                                                                                                                                        | Máx. Caract. | 
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **notification_type** *                  | enum | tipo de notificação                                                                                                                                    | -            | 
| **owner_person_type** * | enum |Tipo de pessoa (natural ou juridica) objeto da consulta de agenda.                                                                       | -            |
| **owner_person_name** *                 | string | Nome do objeto da consulta de agenda. | -            |
| **owner_document_number** * | string | Numero de documento do objeto da consulta de agenda.                                                                                                                                                    | -            |
| **reference_code** * | object | Identificador único do opt-in.                                                                                                                                                    | -            |
| **signature** * | object | Informações do opt-in.              refinanciadas.                                                                                                                                                           | -            |
| **agenda** * | object | Parâmetros para a consulta de agenda.                                                                                                                                                          | -            |

## Definições

### Objeto agenda
| Campo                           | Tipo   | Descrição                                                                                                                                                                                                        | Máx. Caract. | 
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **acquirers** *                  | array | Lista de números de documentos da Credenciadoras.                                                                                                                                     | -            | 
| **card_schemes** * | array | Lista de arranjos de pagamento.                                                                      | -            |
| **end_date** *                 | string | Data de termino da consulta. | -            |
| **start_date** * | string | Data de início da consulta.                                                                                                                                                           | -            |

# Enumeradores

### Enumerador _Person Type_
| Enumerador             | Descrição             |
|------------------------|-----------------------|
| **legal**   | Pessoa juridica        |
| **natural**    | Pesso física    |

### Enumerador _Account Type_
| Enumerador             | Descrição             |
|------------------------|-----------------------|
| **webhook**   | Conta corrente        |

## Response

STATUS 200

Response Body

```json
{}
```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

---

# trava_de_domicilio_bancario

URL: /documentation/arranjos_e_adquirentes/trava_de_domicilio_bancario

Caso o cliente deseje realizar uma operação de crédito com garantia em recebíveis, a QI Tech juntamente com a CERC, está preparada para criar essa operação de maneira muito semelhante ao fluxo de emissão de dívida comum.

# Criar uma renegociação

## Request

ENDPOINT /baas/debt_receivables
MÉTODO POST

Request Body

```json
{
	"borrower": {
		"name": "Alan Mathison Turing",
		"email": "alan.turing@email.com",
		"phone": {
			"number": "912345678",
			"area_code": "11",
			"country_code": "055"
		},
		"is_pep": false,
		"address": {
			"city": "São Paulo",
			"state": "SP",
			"number": "1000",
			"street": "Avenida Feliz",
			"complement": "AP 801",
			"postal_code": "49026100",
			"neighborhood": "Centro"
		},
		"role_type": "issuer",
		"birth_date": "1990-11-20",
		"mother_name": "Nome da Mãe do Alan",
		"nationality": "brasileiro",
		"person_type": "natural",
		"individual_document_number": "96969879003",
        "document_identification": "494598fd-c226-4332-a500-591ae3884673"
	},
	"financial": {
        "amount": 123456,
        "interest_type": "pre_price_days",
        "credit_operation_type": "ccb",
        "annual_interest_rate": 2.32,
        "disbursement_date": "2023-03-01",
        "interest_grace_period": 0,
        "principal_grace_period": 0,
        "number_of_installments": 2,
        "fine_configuration": {
          "contract_fine_rate": 0.02,
          "interest_base": "calendar_days",
          "monthly_rate": 0.01
        }
    },
	"disbursement_bank_account": {
		"name": "Alan Mathison Turing",
        "document_number": "96969879003",
		"bank_code": "341",
        "branch_number": "8615",
        "account_number": "22110",
        "account_digit": "2",
		"account_type": "checking_account"
	},
	"purchaser_document_number": "32402502000135",
      "contract": {
    "payment_account": {
      "account_number": "48391",
      "account_branch": "0001",
      "account_digit": "6",
      "owner_document_number": "86498542000151"
    },
    "collaterals": [
      {
        "card_scheme": [
          "abc"
        ],
        "initial_date": "2021-06-28",
        "final_date": "2021-07-06",
        "division_rule": 2,
        "encumbered_amount": 30
      }
    ],
    "collateral_management": {
      "collateral_management_type": "absolute",
      "amount": 2000,
      "maximum_value": 2000,
      "maximum_daily_value": 200,
      "minimum_date": "2021-06-28",
      "contract_payment_type": "partial_payment"
    }
  }
}
```

## Response

STATUS 200

Response Body

```json
{
  "data": {
    "additional_iof": 38000,
    "annual_cet": "253,2642%",
    "assignment_amount": 10000000,
    "base_iof": 69331,
    "borrower": {
      "document_number": "89940878025962",
      "name": "Parmalat"
    },
    "cet": "11,0900%",
    "collaterals": [],
    "contract": {
      "external_contract_key": "2f0b8b6e-0b60-47f0-b27f-e291c028549b",
      "number": "1907258737/P",
      "signature_information": [
        {
          "signature_url": "https://sign.qitech.com.br/s/hNrwjda",
          "signer_document_number": "94632180173",
          "signer_email": "pedro.alves@yopmail.com",
          "signer_external_key": "07a1c438-43a4-49a9-85a9-29667507453b",
          "signer_name": "Pedro Felipe Henrique Alves",
          "signer_role": "issuer"
        },
        {
          "signature_url": "https://sign.qitech.com.br/s/EaTajda",
          "signer_document_number": "34651104630",
          "signer_email": "patricia.tereza@yopmail.com",
          "signer_external_key": "61a1ea50-769a-410a-8ef8-09f0ce4611f6",
          "signer_name": "Patrícia Tereza Bernardes",
          "signer_role": "guarantor"
        }
      ],
      "urls": [
        "https://storage.googleapis.com/sandbox-doc-api/documents/abedfeab-dcf8-4e13-897b-da02c222cef4/SALGADINHO_SALETE_LTDA-PARMALAT-CCB-1907258737-20220512165254.pdf"
      ]
    },
    "contract_fee_amount": 50000,
    "contract_fees": [
      {
        "fee_amount": 50000,
        "fee_type": "tac"
      }
    ],
    "external_contract_fee_amount": 0,
    "external_contract_fees": [],
    "installments": [
      {
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": null,
        "business_due_date": "2019-08-26",
        "calendar_days": 32,
        "digitable_line": null,
        "due_date": "2019-08-26",
        "due_interest": null,
        "due_principal": 10000000,
        "fine_amount": null,
        "has_interest": true,
        "installment_key": "81e4a732-d300-4e39-b6d5-2d9ac8df429b",
        "installment_number": 1,
        "installment_payment": [],
        "installment_status": "created",
        "installment_type": "principal",
        "original_due_principal": 10000000,
        "original_pre_fixed_amount": 1125598.54,
        "original_principal_amortization_amount": 1000000,
        "original_total_amount": null,
        "paid_amount": 0,
        "paid_at": null,
        "payments": [],
        "post_fixed_amount": null,
        "pre_fixed_amount": 1125598.54,
        "principal_amortization_amount": 1000000,
        "tax_amount": 1312,
        "total_amount": null,
        "total_paid_amount": 0,
        "workdays": 22
      },
      {
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": null,
        "business_due_date": "2019-09-25",
        "calendar_days": 30,
        "digitable_line": null,
        "due_date": "2019-09-25",
        "due_interest": null,
        "due_principal": 9000000,
        "fine_amount": null,
        "has_interest": true,
        "installment_key": "bac4fe3e-9559-4380-9f4b-bdda3492738e",
        "installment_number": 2,
        "installment_payment": [],
        "installment_status": "created",
        "installment_type": "principal",
        "original_due_principal": 9000000,
        "original_pre_fixed_amount": 946509.06,
        "original_principal_amortization_amount": 1000000,
        "original_total_amount": null,
        "paid_amount": 0,
        "paid_at": null,
        "payments": [],
        "post_fixed_amount": null,
        "pre_fixed_amount": 946509.06,
        "principal_amortization_amount": 1000000,
        "tax_amount": 2542,
        "total_amount": null,
        "total_paid_amount": 0,
        "workdays": 22
      },
      {
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": null,
        "business_due_date": "2019-10-25",
        "calendar_days": 30,
        "digitable_line": null,
        "due_date": "2019-10-25",
        "due_interest": null,
        "due_principal": 8000000,
        "fine_amount": null,
        "has_interest": true,
        "installment_key": "aaaec4d7-94a0-418d-8a8e-ac7af6787aec",
        "installment_number": 3,
        "installment_payment": [],
        "installment_status": "created",
        "installment_type": "principal",
        "original_due_principal": 8000000,
        "original_pre_fixed_amount": 841341.39,
        "original_principal_amortization_amount": 1000000,
        "original_total_amount": null,
        "paid_amount": 0,
        "paid_at": null,
        "payments": [],
        "post_fixed_amount": null,
        "pre_fixed_amount": 841341.39,
        "principal_amortization_amount": 1000000,
        "tax_amount": 3772,
        "total_amount": null,
        "total_paid_amount": 0,
        "workdays": 22
      },
      {
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": null,
        "business_due_date": "2019-11-25",
        "calendar_days": 31,
        "digitable_line": null,
        "due_date": "2019-11-25",
        "due_interest": null,
        "due_principal": 7000000,
        "fine_amount": null,
        "has_interest": true,
        "installment_key": "bead5a38-c56e-4cfc-98f9-af6d71ec7d65",
        "installment_number": 4,
        "installment_payment": [],
        "installment_status": "created",
        "installment_type": "principal",
        "original_due_principal": 7000000,
        "original_pre_fixed_amount": 762003.23,
        "original_principal_amortization_amount": 1000000,
        "original_total_amount": null,
        "paid_amount": 0,
        "paid_at": null,
        "payments": [],
        "post_fixed_amount": null,
        "pre_fixed_amount": 762003.23,
        "principal_amortization_amount": 1000000,
        "tax_amount": 5043,
        "total_amount": null,
        "total_paid_amount": 0,
        "workdays": 20
      },
      {
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": null,
        "business_due_date": "2019-12-26",
        "calendar_days": 31,
        "digitable_line": null,
        "due_date": "2019-12-26",
        "due_interest": null,
        "due_principal": 6000000,
        "fine_amount": null,
        "has_interest": true,
        "installment_key": "350a89e3-58a7-4879-b7ff-5fa0391da39c",
        "installment_number": 5,
        "installment_payment": [],
        "installment_status": "created",
        "installment_type": "principal",
        "original_due_principal": 6000000,
        "original_pre_fixed_amount": 653145.63,
        "original_principal_amortization_amount": 1000000,
        "original_total_amount": null,
        "paid_amount": 0,
        "paid_at": null,
        "payments": [],
        "post_fixed_amount": null,
        "pre_fixed_amount": 653145.63,
        "principal_amortization_amount": 1000000,
        "tax_amount": 6314,
        "total_amount": null,
        "total_paid_amount": 0,
        "workdays": 22
      },
      {
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": null,
        "business_due_date": "2020-01-27",
        "calendar_days": 32,
        "digitable_line": null,
        "due_date": "2020-01-27",
        "due_interest": null,
        "due_principal": 5000000,
        "fine_amount": null,
        "has_interest": true,
        "installment_key": "bf935dc2-3151-4f66-91c6-35e446b57f2e",
        "installment_number": 6,
        "installment_payment": [],
        "installment_status": "created",
        "installment_type": "principal",
        "original_due_principal": 5000000,
        "original_pre_fixed_amount": 562799.27,
        "original_principal_amortization_amount": 1000000,
        "original_total_amount": null,
        "paid_amount": 0,
        "paid_at": null,
        "payments": [],
        "post_fixed_amount": null,
        "pre_fixed_amount": 562799.27,
        "principal_amortization_amount": 1000000,
        "tax_amount": 7626,
        "total_amount": null,
        "total_paid_amount": 0,
        "workdays": 20
      },
      {
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": null,
        "business_due_date": "2020-02-26",
        "calendar_days": 30,
        "digitable_line": null,
        "due_date": "2020-02-26",
        "due_interest": null,
        "due_principal": 4000000,
        "fine_amount": null,
        "has_interest": true,
        "installment_key": "76aad8ce-3ee1-464c-90db-d72a2729560e",
        "installment_number": 7,
        "installment_payment": [],
        "installment_status": "created",
        "installment_type": "principal",
        "original_due_principal": 4000000,
        "original_pre_fixed_amount": 420670.69,
        "original_principal_amortization_amount": 1000000,
        "original_total_amount": null,
        "paid_amount": 0,
        "paid_at": null,
        "payments": [],
        "post_fixed_amount": null,
        "pre_fixed_amount": 420670.69,
        "principal_amortization_amount": 1000000,
        "tax_amount": 8856,
        "total_amount": null,
        "total_paid_amount": 0,
        "workdays": 20
      },
      {
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": null,
        "business_due_date": "2020-03-25",
        "calendar_days": 28,
        "digitable_line": null,
        "due_date": "2020-03-25",
        "due_interest": null,
        "due_principal": 3000000,
        "fine_amount": null,
        "has_interest": true,
        "installment_key": "fc190222-5baf-4023-9e93-95b25774a37e",
        "installment_number": 8,
        "installment_payment": [],
        "installment_status": "created",
        "installment_type": "principal",
        "original_due_principal": 3000000,
        "original_pre_fixed_amount": 293473.82,
        "original_principal_amortization_amount": 1000000,
        "original_total_amount": null,
        "paid_amount": 0,
        "paid_at": null,
        "payments": [],
        "post_fixed_amount": null,
        "pre_fixed_amount": 293473.82,
        "principal_amortization_amount": 1000000,
        "tax_amount": 10004,
        "total_amount": null,
        "total_paid_amount": 0,
        "workdays": 20
      },
      {
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": null,
        "business_due_date": "2020-04-27",
        "calendar_days": 33,
        "digitable_line": null,
        "due_date": "2020-04-27",
        "due_interest": null,
        "due_principal": 2000000,
        "fine_amount": null,
        "has_interest": true,
        "installment_key": "7c2972a8-def7-4b76-b215-0ade0a5bca13",
        "installment_number": 9,
        "installment_payment": [],
        "installment_status": "created",
        "installment_type": "principal",
        "original_due_principal": 2000000,
        "original_pre_fixed_amount": 232548.93,
        "original_principal_amortization_amount": 1000000,
        "original_total_amount": null,
        "paid_amount": 0,
        "paid_at": null,
        "payments": [],
        "post_fixed_amount": null,
        "pre_fixed_amount": 232548.93,
        "principal_amortization_amount": 1000000,
        "tax_amount": 11357,
        "total_amount": null,
        "total_paid_amount": 0,
        "workdays": 21
      },
      {
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": null,
        "business_due_date": "2020-05-25",
        "calendar_days": 28,
        "digitable_line": null,
        "due_date": "2020-05-25",
        "due_interest": null,
        "due_principal": 1000000,
        "fine_amount": null,
        "has_interest": true,
        "installment_key": "d848c880-f489-4bc1-a9e4-101f8d664317",
        "installment_number": 10,
        "installment_payment": [],
        "installment_status": "created",
        "installment_type": "principal",
        "original_due_principal": 1000000,
        "original_pre_fixed_amount": 97824.6,
        "original_principal_amortization_amount": 1000000,
        "original_total_amount": null,
        "paid_amount": 0,
        "paid_at": null,
        "payments": [],
        "post_fixed_amount": null,
        "pre_fixed_amount": 97824.6,
        "principal_amortization_amount": 1000000,
        "tax_amount": 12505,
        "total_amount": null,
        "total_paid_amount": 0,
        "workdays": 19
      }
    ],
    "iof_charge_method": "financed",
    "issue_amount": 10000000,
    "net_external_contract_fee_amount": 0,
    "number_of_installments": 10,
    "post_fixed_interest_base": "workdays",
    "post_fixed_interest_rate": 1,
    "prefixed_interest_rate": {
      "annual_rate": 2.32,
      "created_at": null,
      "daily_rate": 0.0033388,
      "interest_base": "calendar_days",
      "monthly_rate": 0.10516767
    },
    "requester_identifier_key": "b7ddbcfb-3de0-49d8-8014-07972d8b27f2",
    "total_iof": 107331,
    "total_pre_fixed_amount": 5935915.16
  },
  "event_datetime": "2022-05-12 16:53:10",
  "key": "b7ddbcfb-3de0-49d8-8014-07972d8b27f2",
  "status": "waiting_signature",
  "webhook_type": "debt"
}

```

:::caution Atenção!

O payload ultilizado na emissão de um refinanciamento é o mesmo ultilizado na emissã de uma divida simples, com a adição da lista de operações que serão quitadas em **"refinanced_credit_operations"**.
:::

### Body Params

| Campo                           | Tipo   | Descrição                                                                                                                                                                                                        | Máx. Caract. | 
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **borrower** *                  | object | **[Objeto Borrower](#objeto-borrower)** - Devedor da operação de crédito.                                                                                                                                         | -            | 
| **disbursement_bank_account** * | object | **[Objeto Disbursement Bank Account](#objeto-disbursement_bank_accounts)** - Dados da conta bancária para desembolso da operação.                                                                                 | -            |
| **financial** *                 | object | **[Objeto Financial](#objeto-financial)** - Dados da conta bancária para desembolso da operaçãoIdentificador de que o objeto enviado é uma pessoa física. Deve conter SEMPRE o  valor "natural" para borrower PF. | -            |
| **purchaser_document_number** * | string | CNPJ do cessionário (comprador) da operação de crédito.                                                                                                                                                           | -            |
| **refinanced_credit_operations** * | array of objects | Lista de **[Objetos Refinanced Credit Operations](#objeto-refinanced_credit_operations)** contendo as operações refinanciadas.                                                                                                                                                           | -            |

## Definições

### Objeto Request Body
| Campo                           | Tipo   | Descrição                                                                                                                                                                                                        | Máx. Caract. | 
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **borrower** *                  | object | **[Objeto Borrower](#objeto-borrower)** - Devedor da operação de crédito                                                                                                                                         | -            | 
| **disbursement_bank_account** * | object | **[Objeto Disbursement Bank Account](#objeto-disbursement_bank_accounts)** - Dados da conta bancária para desembolso da operação                                                                                 | -            |
| **financial** *                 | object | **[Objeto Financial](#objeto-financial)** - Dados da conta bancária para desembolso da operaçãoIdentificador de que o objeto enviado é uma pessoa física. Deve conter SEMPRE o  valor "natural" para borrower PF | -            |
| **purchaser_document_number** * | string | CNPJ do cessionário (comprador) da operação de crédito                                                                                                                                                           | -            |
| **contract** * | object | **[Objeto Financial](#objeto-contract)**  com dados da garantia.                                                                                                                                                           | -            |

### Objeto Borrower
| Campo                            | Tipo    | Descrição                                                                             | Máx. Caract. | 
|----------------------------------|---------|---------------------------------------------------------------------------------------|--------------|
| **name** *                       | string  | Nome do devedor                                                                       | 100          |
| **email**                        | string  | Email do devedor                                                                      | 254          |
| **phone**                        | object  | **[Objeto Phone](#objeto-phone)** - Telefone de contato do devedor                    | -            | 
| **is_pep** *                     | boolean | Indicador de PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep)      | -            |
| **address** *                    | object  | **[Objeto Address](#objeto-address)** - Endereço do devedor                           | -            | 
| **role_type** *                  | enum    | default: _issuer_                                                                     | -            |
| **birth_date** *                 | date    | Data de nascimento do devedor (formato "AAAA-MM-DD")                                  | -            |
| **mother_name** *                | string  | Nome da mãe do devedor                                                                | 100          |
| **nationality**                  | string  | Nacionalidade do devedor                                                              | 50           |
| **person_type** *                | string  | Indicador de pessoa física - default: _natural_                                       | -            |
| **individual_document_number** * | string  | CPF do devedor (apenas números)                                                       | 11           |
| **document_identification**     * | string  | **DOCUMENT_KEY** do PDF do documento de identificação do devedor com foto (RG ou CNH) | -            |
| **document_identification_back** |string | DOCUMENT_KEY do PDF da parte de trás do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente). | 11 |
| **wedding_certificate** | string | DOCUMENT_KEY do PDF do certificado de casamento da pessoa (enviado previamente). No caso de marital_status ser "single", o valor deste campo deve ser NULL. | 11 |
| **proof_of_residence** * |string | DOCUMENT_KEY do PDF do comprovante de endereço do endereço enviado (enviado previamente). | 11 |

### Objeto Address
| Campo              | Tipo   | Descrição                                                                | Máx. Caract. | 
|--------------------|--------|--------------------------------------------------------------------------|--------------| 
| **city** *         | string | Cidade do endereço                                                       | 100          |
| **state** *        | string | Estado do endereço (com dois caracteres maiúsculos)                      | 2            |
| **number** *       | string | Número do endereço                                                       | 10           |
| **street** *       | string | Rua do endereço                                                          | 100          |
| **complement** *   | string | Complemento do endereço (texto livre)                                    | 100          |
| **postal_code** *  | string | CEP do endereço (http://www.buscacep.correios.com.br/sistemas/buscacep/) | 8            |
| **neighborhood** * | string | Bairro do endereço                                                       | 100          |

### Objeto Phone
| Campo              | Descrição | Exemplo                                               | Máx. Caract. | 
|--------------------|-----------|-------------------------------------------------------|--------------| 
| **number** *       | string    | Número de telefone                                    | 10           |
| **area_code** *    | string    | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2            |
| **country_code** * | string    | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3            |

### Objeto Disbursement Bank Account

Uma emissão de dívida deve conter as informações bancárias para desembolso, por padrão, uma conta de titularidade do devedor.

| Campo                 | Tipo   | Descrição                                                                                          | Máx. Caract. | 
|-----------------------|--------|----------------------------------------------------------------------------------------------------|--------------|
| name                  | string | Nome do titular da conta                                                                           | 50           |
| document_number       | string | CPF do titular da conta                                                                            | 11           |
| bank_code *           | string | Código COMPE da instituição financeira (https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf) | 3            |
| branch_number *       | string | Número da agência (não informar o dígito verificador da agência!)                                  | 4            |
| account_number *      | string | Número da conta (sem o dígito verificador da conta!)                                               | 10           |
| account_digit *       | string | Dígito verificador da conta (informar zero no lugar de letras)                                     | 1            |
| account_type          | enum   | [Enumerador Account Type](#enumerador-account-type) Tipo da conta                                  | 1            |

### Objeto Financial

O objeto financial descreve as informações financeiras da operação de crédito.

| Campo                      | Tipo   | Descrição                                                                                                     | Máx. Caract. |
|----------------------------|--------|---------------------------------------------------------------------------------------------------------------|--------------|
| **amout**                  | float  | Valor de emissão/nominal da operação de crédito                                                               | -            |
| **interest_type**          | object | **[Enumerador Interest Type](#enumerador-interest-type)** - Método de amortização e forma de cálculo de juros | -            |
| **credit_operation_type**  | object | **[Enumerador Credit Operation Type](#enumerador-credit-operation-type)** - Tipo do contrato de crédito       | -            |
| **annual_interest_rate**   | float  | Taxa de juros pré-fixada expressa em decimal ao ano                                                           | -            |
| **disbursement_date**      | date   | Data do desembolso da operação                                                                                | -            |
| **interest_grace_period**  | int    | Carência de juros (em meses)                                                                                  | -            |
| **principal_grace_period** | int    | Período carência de principal                                                                                 | -            |
| **number_of_installments** | int    | Número de parcelas da operação de crédito                                                                     | -            |
| **fine_configuration**     | object | **[Objeto Fine Configuration](#objeto-fine-configuration)** - Configuração de juros e multa por atraso        | -            |

### Objeto Fine Configuration

No Objeto Fine Configuration são informados os valor de multa e juros por atraso da operação de crédito. 

| Campo                  | Tipo  | Descrição                                                                            | Máx. Caract. |
|------------------------|-------|--------------------------------------------------------------------------------------|--------------|
| **contract_fine_rate** | float | Percentual de multa por atraso                                                       | -            |
| **interest_base**      | enum  | **[Enumerador Interest Base](#enumerador-interest-base)** - Base de cálculo de juros | -            |
| **monthly_rate**       | float | Percentual de juros de atraso ao mês                                                 | -            |

### Objeto Contract

O objeto financial descreve as informações financeiras da operação de crédito.

| Campo                      | Tipo   | Descrição                                                                                                     | Máx. Caract. |
|----------------------------|--------|---------------------------------------------------------------------------------------------------------------|--------------|
| **payment_account**                  | object  | Conta de pagamentos para os recebíveis.                                                               | -            |
| **collaterals**          | array | Listas de garantias. | -            |
| **collateral_management**  | object | **[Objeto Collateral Management](#objeto-collateral-management)** - Configurações de garantia.       | -            |

### Objeto Collateral Management

O objeto financial descreve as informações financeiras da operação de crédito.

| Campo                      | Tipo   | Descrição                                                                                                     | Máx. Caract. |
|----------------------------|--------|---------------------------------------------------------------------------------------------------------------|--------------|
| **collateral_management_type**                  | enum  |  **[Enumerador Collateral Management Type](#enumerador-collateral-management-type)** - Tipo de gestão a ser utilizada para amortizar a divida.                                                               | -            |
| **amount**          | float | Valor a ser utilizado. | -            |
| **maximum_value**  | float | Valor máximo que será utilizado para pagamento da operação.      | -            |
| **maximum_daily_value**  | float | Valor máximo que será utilizado por dia.       | -            |
| **minimum_date**  | string | Data mínima para começar à utilizar os recebiveis.      | -            |
| **contract_payment_type**  | enum | **[Enumerador Credit Operation Type](#enumerador-credit-operation-type)** - Tipo de pagamento para o contrato       | -            |

# Enumeradores

### Enumerador _Person Type_
| Enumerador             | Descrição             |
|------------------------|-----------------------|
| **legal**   | Pessoa juridica        |
| **natural**    | Pesso física    |

### Enumerador _Account Type_
| Enumerador             | Descrição             |
|------------------------|-----------------------|
| **checking_account**   | Conta corrente        |
| **deposit_account**    | Conta de depósito     |
| **guaranteed_account** | Conta de garantia     |
| **investment_account** | Conta de investimento |
| **payment_account**    | Conta de pagamento    |
| **saving_account**     | Conta poupança        |
| **salary_account**     | Conta salário         |

### Enumerador _Interest Type_
| Enumerador           | Descrição                                                                                                                                                                |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **pre_price_days**   | Método de amortização Price (parcelas iguais) com cálculo do juros pré-fixado ao dia                                                                                     |
| **pre_price**        | Método de amortização Price (parcelas iguais) com cálculo do juros pré-fixado em períodos fixos (30 dias)                                                                |
| **pre_sac**          | Método de amortização SAC (amortização constante) com cálculo do juros pré-fixado ao dia                                                                                 |
| **post_sac**         | Método de amortização SAC (amortização constante) com cálculo do juros baseado em uma taxa pré-fixada + indexador pós-fixado (cdi, ipca ou igpm) ao dia                  |
| **post_price**       | Método de amortização Price (parcelas iguais) com cálculo do juros baseado em uma taxa pré-fixada + indexador pós-fixado (cdi, ipca ou igpm) em períodos fixos (30 dias) |
| **post_price_days**  | Método de amortização Price (parcelas iguais) com cálculo do juros baseado em uma taxa pré-fixada + indexador pós-fixado (cdi, ipca ou igpm) ao dia                      |

### Enumerador _Credit Operation Type_
| Enumerador    | Descrição                      |
|---------------|--------------------------------|
| **ccb**       | Cédula de Crédito Bancário     |
| **cce**       | Cédula de Crédito à Exportação |
| **cci**       | Cédula de Crédito Imobiliário  |
| **nce**       | Nota de Crédito à Exportação   |

### Enumerador _Interest Base_
| Enumerador            | Descrição                                                                 |
|-----------------------|---------------------------------------------------------------------------|
| **workdays**          | Base de cálculo de juros em dias úteis considerando um ano de 252 dias    |
| **calendar_days**     | Base de cálculo de juros em dias corridos considerando um ano de 360 dias |
| **calendar_days_365** | Base de cálculo de juros em dias corridos considerando um ano de 365 dias |

### Enumerador _Fee Type_
Cada tipo de fee deve ser previamente habilitado e configurado pela QI Tech

| Enumerador            | Descrição                                                                  |
|-----------------------|----------------------------------------------------------------------------|
| **tac**               | Tarifa de abertura de cadastro                                             |
| **spread**            | Ágio cobrado no valor de aquisição da operação de crédito                  |
| **warranty_analysis** | Tarifa de análise de garantias                                             |
| **ted_fee**           | Tarifa de TED                                                              |
| **spread_ted_fee**    | Ágio da tarifa de TED cobrado no valor de aquisição da operação de crédito |

### Enumerador _Collateral Management Type_
| Enumerador             | Descrição             |
|------------------------|-----------------------|
| **absolute**   | Valor absoluto       |
| **percentage**    | Valor percentual    |

### Enumerador _Person Type_
| Enumerador             | Descrição             |
|------------------------|-----------------------|
| **partial_payment**   | Pagamento parcial        |
| **total_payment**    | Pagamento total    |
| **monthly_payment**    | Pagamento mensal    |

## Response

STATUS 200

Response Body

```json
{
  "data": {
    "additional_iof": 469.1328,
    "annual_cet": "283,3821%",
    "assignment_amount": 124690.56,
    "base_iof": 473.6829374063069,
    "borrower": {
      "document_number": "96969879003",
      "name": "Alan Mathison Turing"
    },
    "cet": "11,8500%",
    "collaterals": [],
    "contract": {
      "number": "0000067563/AMT",
      "signature_information": [
        {
          "signature_url": null,
          "signer_document_number": "15627918004",
          "signer_email": "alan.turing@email.com",
          "signer_external_key": null,
          "signer_name": "Alan Mathison Turing",
          "signer_role": "issuer"
        }
      ],
      "urls": [
        "https://storage.googleapis.com/sandbox-doc-api/documents/5af36fcd-8e4c-4421-ad45-7bcba899c0d3/SYNGENTASANDBOX-ALAN_MATHISON_TURING-CCB-0000067563-20230302234816.pdf"
      ]
    },
    "contract_fee_amount": 1234.56,
    "contract_fees": [
      {
        "fee_amount": 1234.56,
        "fee_type": "tac"
      }
    ],
    "external_contract_fee_amount": 1234.56,
    "external_contract_fees": [
      {
        "fee_amount": 1234.56,
        "fee_type": "spread",
        "net_fee_amount": 1120.36,
        "tax_amount": 114.2
      }
    ],
    "installments": [
      {
        "accrual_reference_date": null,
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": null,
        "business_due_date": "2023-04-03",
        "calendar_days": 31,
        "digitable_line": null,
        "due_date": "2023-04-02",
        "due_interest": 0,
        "due_principal": 123456,
        "fine_amount": null,
        "has_interest": true,
        "installment_history": [],
        "installment_key": "da264e95-2bbd-47de-876b-bfea7d25e266",
        "installment_number": 1,
        "installment_payment": [],
        "installment_status": "created",
        "installment_type": "principal",
        "original_due_principal": 123456,
        "original_pre_fixed_amount": 13245.468714162304,
        "original_principal_amortization_amount": 58473.151285837695,
        "original_total_amount": 71718.62,
        "paid_amount": 0,
        "paid_at": null,
        "post_fixed_amount": 0,
        "pre_fixed_amount": 13245.468714162304,
        "principal_amortization_amount": 58473.151285837695,
        "qr_code_key": null,
        "qr_code_url": null,
        "renegotiation_proposal_key": null,
        "tax_amount": 148.63875056859942,
        "total_accrual_amount": null,
        "total_amount": 71718.62,
        "total_paid_amount": 0,
        "workdays": 21
      },
      {
        "accrual_reference_date": null,
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": null,
        "business_due_date": "2023-05-02",
        "calendar_days": 30,
        "digitable_line": null,
        "due_date": "2023-05-02",
        "due_interest": 0,
        "due_principal": 64982.848714162305,
        "fine_amount": null,
        "has_interest": true,
        "installment_history": [],
        "installment_key": "cac7064b-2310-45e1-a91f-5e8f39f0f0ea",
        "installment_number": 2,
        "installment_payment": [],
        "installment_status": "created",
        "installment_type": "principal",
        "original_due_principal": 64982.848714162305,
        "original_pre_fixed_amount": 6735.77577015044,
        "original_principal_amortization_amount": 64982.84422984956,
        "original_total_amount": 71718.62,
        "paid_amount": 0,
        "paid_at": null,
        "post_fixed_amount": 0,
        "pre_fixed_amount": 6735.77577015044,
        "principal_amortization_amount": 64982.84422984956,
        "qr_code_key": null,
        "qr_code_url": null,
        "renegotiation_proposal_key": null,
        "tax_amount": 325.0441868377075,
        "total_accrual_amount": null,
        "total_amount": 71718.62,
        "total_paid_amount": 0,
        "workdays": 19
      }
    ],
    "iof_charge_method": "financed",
    "issue_amount": 123456,
    "net_external_contract_fee_amount": 1120.36,
    "number_of_installments": 2,
    "prefixed_interest_rate": {
      "annual_rate": 2.32,
      "created_at": "2023-03-02T23:48:15",
      "daily_rate": 0.00329298,
      "interest_base": "calendar_days_365",
      "monthly_rate": 0.10516767
    },
    "requester_identifier_key": "1c2ca4dc-2a20-4dd4-bd5f-af143fadadf4",
    "total_iof": 942.82,
    "total_pre_fixed_amount": 19981.244484312745
  },
  "event_datetime": "2023-03-02 23:48:20",
  "key": "1c2ca4dc-2a20-4dd4-bd5f-af143fadadf4",
  "status": "waiting_signature",
  "webhook_type": "debt"
}
```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

---

# emissao_de_divida

URL: /documentation/auxilio_brasil/emissao_de_divida

## Emissão de dívida

## Request

- ENDPOINT /debt
- MÉTODO POST
- BODY (antes de ser assinado):

YOUR REQUEST HISTORY

**body.json**

```json
{
    "borrower": {
        "person_type": "natural",
        "name": "Qi Tech Ltda.",
        "mother_name": "Maria Mariane",
        "birth_date": "1990-05-06",
        "profession": "Deputada",
        "nationality": "nationality",
        "marital_status": "married",
        "wedding_certificate": "56ab7849-4d90-490b-b539-96ac3c5a619b",
        "spouse": {
            "person_type": "natural",
            "name": "Qi Tech Ltda.",
            "mother_name": "Maria Mariane",
            "birth_date": "1990-05-06",
            "profession": "Deputada",
            "nationality": "nationality",
            "marital_status": "married",
            "wedding_certificate": "56ab7849-4d90-490b-b539-96ac3c5a619b",
            "is_pep": False,
            "individual_document_number": "34651104630",
            "document_identification": "3c24579b-9810-4fa6-9b08-fe67d237160a",
            "document_identification_back": "2f43456a-3664-4805-82b8-96a2ec72c04c",
            "document_identification_type": "cnh",
            "document_identification_number": "232479719",
            "email": "api@qitech.com.br",
            "phone": {
                "country_code": "055",
                "area_code": "11",
                "number": "999999999"
            },
            "proof_of_residence": "780456bd-1eec-4e5f-82c0-d8c3921497ea",
            "address": {
                "street": "Av. Brigadeiro Faria Lima",
                "state": "SP",
                "city": "São Paulo",
                "neighborhood": "Jardim Paulistano",
                "number": "2391",
                "postal_code": "01452905",
                "complement": "1o. Andar"
            }
        },
        "is_pep": False,
        "individual_document_number": "34651104630",
        "document_identification": "3c24579b-9810-4fa6-9b08-fe67d237160a",
        "document_identification_back": "2f43456a-3664-4805-82b8-96a2ec72c04c",
        "document_identification_type": "cnh",
        "document_identification_number": "232479719",
        "email": "api@qitech.com.br",
        "phone": {
            "country_code": "055",
            "area_code": "11",
            "number": "999999999"
        },
        "proof_of_residence": "780456bd-1eec-4e5f-82c0-d8c3921497ea",
        "address": {
            "street": "Av. Brigadeiro Faria Lima",
            "state": "SP",
            "city": "São Paulo",
            "neighborhood": "Jardim Paulistano",
            "number": "2391",
            "postal_code": "01452905",
            "complement": "1o. Andar"
        }
    },
    "financial": {
        "interest_type": "pre_price_days",
        "disbursement_start_date": "2019-07-25",
        "disbursement_end_date": "2019-07-29",
        "fine_configuration": {
            "contract_fine_rate": 0.02,
            "interest_base": "workdays",
            "monthly_rate": 0.01
        },
        "annual_interest_rate": 0.02,
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "number_of_installments": 10,
        "principal_grace_period": 0
    }
}

```

### Body Params

| Campo | Descrição |
|---|---|
| `borrower` *(obrigatório)* | Dados do mutuário. |
| `guarantors` | Garantidores da operação (que pode ser uma lista de Objeto PF e/ou Objeto PJ e não é um campo obrigatório). |
| `collaterals` *(obrigatório)* | Informações das parcelas de pagamento. |
| `financial` *(obrigatório)* | O objeto financeiro descreve as informações financeiras da emissão. Aqui são definidas a taxa de juros, carência e valor da dívida entre outros. |
| `disbursement_bank_accounts`  | Lista de informações bancárias para o desembolso (Objeto Conta Bancária). |

### BORROWER OBJECT

| Campo | Descrição |
|---|---|
| `person_type` *(obrigatório)* | Identificador de que o objeto enviado é uma pessoa física ou jurídica. |
| `name` *(obrigatório)* | Nome da pessoa. Limitado a 100 caracteres. |
| `mother_name` | mother_name |
| `birth_date` | Data de nascimento da pessoa (formato "AAAA-MM-DD") |
| `profession` | Profissão da pessoa |
| `nationality` | Nacionalidade do cliente. Limitado a 50 caracteres. |
| `marital_status` | Estado civil do cliente. |
| `property_system` | Regime de separação de bens (obrigatório apenas para pessoas com marital_status "married"). |
| `wedding_certificate` | DOCUMENT_KEY do PDF do certificado de casamento da pessoa (enviado previamente). No caso de marital_status ser "single", o valor deste campo deve ser NULL.|
| `spouse` | Objeto PF do esposo/esposa da pessoa (obrigatório apenas quando "compulsory_separation_of_goods" for "total_communion_of_goods", "partial_communion_of_goods", "final_participation_of_acquisitions" ou "compulsory_separation_of_goods"). No caso de marital_status ser "single", o valor deste campo deve ser NULL. |
| `is_pep` *(obrigatório)* | Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep) valor booleano |
| `individual_document_number` | CPF da pessoa (apenas números) |
| `document_identification` *(obrigatório)* | DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) |
| `document_identification_back` | DOCUMENT_KEY do PDF da parte de trás do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) |
| `document_identification_type` | Tipo do documento de identificação. Valores aceitos: `rg`, `rne`, `cnh`, `ctps`, `class_document`, `passport`, `other`, `cin`. Quando `cin`, o campo `document_identification_number` deve ser igual ao CPF. |
| `document_identification_number` *(obrigatório)* | Número do documento de identificação da pessoa enviado em document_identification. Quando `document_identification_type` for `cin`, deve ser igual ao CPF. |
| `email` | Email da pessoa |
| `phone` | Telefone da pessoa |
| `address` | Endereço da pessoa |
| `proof_of_residence` *(obrigatório)* | DOCUMENT_KEY do PDF do comprovante de endereço do endereço enviado (enviado previamente) |

### GUARANTORS OBJECT

| Campo | Descrição |
|---|---|
| `person_type` *(obrigatório)* | Identificador de que o objeto enviado é uma pessoa física ou jurídica. |
| `name` *(obrigatório)* | Nome da pessoa. Limitado a 100 caracteres. |
| `mother_name` *(obrigatório)* | Nome da mãe do cliente em caso de PF. Limitado a 100 caracteres. |
| `birth_date` *(obrigatório)* | Data de nascimento da pessoa (formato "AAAA-MM-DD") |
| `profession` *(obrigatório)* | Profissão do cliente. Limitado a 64 caracteres. |
| `nationality` *(obrigatório)* | Nacionalidade do cliente. Limitado a 50 caracteres. |
| `marital_status` *(obrigatório)* | Estado civil do cliente. |
| `property_system` | Regime de separação de bens (obrigatório apenas para pessoas com marital_status "married"). |
| `wedding_certificate` *(obrigatório)* | DOCUMENT_KEY do PDF do certificado de casamento da pessoa (enviado previamente). No caso de marital_status ser "single", o valor deste campo deve ser NULL. |
| `spouse` *(obrigatório)* | Objeto PF do esposo/esposa da pessoa (obrigatório apenas quando "compulsory_separation_of_goods" for "total_communion_of_goods", "partial_communion_of_goods", "final_participation_of_acquisitions" ou "compulsory_separation_of_goods"). No caso de marital_status ser "single", o valor deste campo deve ser NULL. |
| `is_pep` *(obrigatório)* | Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep). |
| `individual_document_number` *(obrigatório)* | CPF da pessoa (apenas números). Limitado a 11 caracteres. |
| `document_identification` *(obrigatório)* | DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) |
| `document_identification_back` | DOCUMENT_KEY do PDF da parte de trás do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) |
| `document_identification_type` | Qual o tipo do documento de identificação enviado. |
| `document_identification_number` *(obrigatório)* | Número do documento de identificação da pessoa enviado em "document_identification". Limitado a 16 caracteres. |
| `email` | Email da pessoa |
| `phone` | Telefone da pessoa |
| `proof_of_residence` *(obrigatório)* | DOCUMENT_KEY do PDF do comprovante de endereço do endereço enviado (enviado previamente) |
| `address` | Endereço da pessoa |

### SPOUSE OBJECT

| Campo | Descrição |
|---|---|
| `person_type` *(obrigatório)* | Identificador de que o objeto enviado é uma pessoa física. Deve conter SEMPRE o valor "natural" para Objeto PF |
| `name` *(obrigatório)* | Nome da pessoa |
| `mother_name` *(obrigatório)* | mother_name |
| `birth_date` *(obrigatório)* | Data de nascimento da pessoa (formato "AAAA-MM-DD") |
| `profession` *(obrigatório)* | Profissão da pessoa |
| `nationality` *(obrigatório)* | Nacionalidade da pessoa |
| `marital_status` *(obrigatório)* | Estado civil da pessoa: "single", "married", "widower" ou "divorced" |
| `property_system` | Regime de separação de bens (obrigatório apenas para pessoas com marital_status "married"): "total_communion_of_goods", "partial_communion_of_goods", "total_separation_of_goods", "final_participation_of_acquisitions" ou "compulsory_separation_of_goods" |
| `wedding_certificate` *(obrigatório)* | DOCUMENT_KEY do PDF do certificado de casamento da pessoa (enviado previamente). No caso de marital_status ser "single", o valor deste campo deve ser null |
| `spouse` *(obrigatório)* | Objeto PF do esposo/esposa da pessoa (obrigatório apenas quando "compulsory_separation_of_goods" for "total_communion_of_goods", "partial_communion_of_goods", "final_participation_of_acquisitions" ou "compulsory_separation_of_goods"). No caso de marital_status ser "single", o valor deste campo deve ser null |
| `is_pep` *(obrigatório)* | Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep) valor booleano |
| `individual_document_number` *(obrigatório)* | CPF da pessoa (apenas números) |
| `document_identification` *(obrigatório)* | DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) |
| `document_identification_back` | DOCUMENT_KEY do PDF da parte de trás do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) |
| `document_identification_type` | Tipo do documento de identificação. Valores aceitos: `rg`, `rne`, `cnh`, `ctps`, `class_document`, `passport`, `other`, `cin`. Quando `cin`, o campo `document_identification_number` deve ser igual ao CPF. |
| `document_identification_number` *(obrigatório)* | Número do documento de identificação da pessoa enviado em document_identification. Quando `document_identification_type` for `cin`, deve ser igual ao CPF. |
| `email` | Email da pessoa |
| `phone` | Telefone da pessoa |
| `proof_of_residence` *(obrigatório)* | DOCUMENT_KEY do PDF do comprovante de endereço do endereço enviado (enviado previamente) |
| `address` | Endereço da pessoa |

### PHONE OBJECT

| Campo | Descrição |
|---|---|
| `country_code` *(obrigatório)* | Código DDI do telefone (https://ddi.guiamais.com.br/)(deve ter obrigatoriamente 3 dígitos). |
| `area_code` *(obrigatório)* | Código DDD do telefone (https://ddd.guiamais.com.br/).) |
| `number` *(obrigatório)* | Número de telefone (apenas números). |
| `document_number` *(obrigatório)* | Numero de documento do signatário. |

### ADDRESS OBJECT

| Campo | Descrição |
|---|---|
| `street` *(obrigatório)* | Rua do endereço. |
| `state` *(obrigatório)* | Estado do endereço (com dois caracteres maiúsculos). |
| `city` *(obrigatório)* | Cidade do endereço. |
| `neighborhood` *(obrigatório)* | Bairro do endereço. |
| `number` *(obrigatório)* | Número da rua. |
| `postal_code` *(obrigatório)* | CEP do endereço (http://www.buscacep.correios.com.br/sistemas/buscacep/) (apenas números). |
| `complement` *(obrigatório)* | Complemento do endereço (texto livre). |

### OCR OBJECT

| Campo | Descrição |
|---|---|
| `ocr` | Objeto para entrega das chaves geradas pelo SDK de OCR |

### COLLATERALS OBJECT

| Campo | Descrição |
|---|---|
| `collateral_data` | Lista de garantias da operação. |
| `percentage` |  |
| `collateral_type` *(obrigatório)* | Tipo de collateral. No caso do Auxílio Brasil, precisa ser "social_benefit" |

### COLLATERAL DATA OBJECT

| Campo | Descrição |
|---|---|
| `reservation_period` | Período do beneficio bloqueado como garantia. |
| `reservation_amount` | Valor do beneficio bloqueado como garantia. |
| `family_code` | Código da Família do beneficio. |
| `state` | UF da família do beneficio. |
| `financial_education_term` | Respostas do Termo de Educação Financeira exigido pelo Ministério da Cidadania |

### FINANCIAL EDUCATION TERM OBJECT

| Campo | Descrição |
|---|---|
| `questions` |  |

### QUESTIONS OBJECT

| Campo | Descrição |
|---|---|
| `answer` |  |

### FINANCIAL OBJECT

| Campo | Descrição |
|---|---|
| `desired_installments` | Lista de parcelas. |
| `interest_type` *(obrigatório)* | Tipo de juros da operação. |
| `disbursement_start_date` | Data início do período de desembolso (formato "AAAA-MM-DD"). |
| `disbursement_end_date` | Data final do período de desembolso (formato "AAAA-MM-DD"). |
| `annual_interest_rate` *(obrigatório)* | Valor porcentual da parcela prefixada de juros (atenção: 1 = 100%) |
| `credit_operation_type` *(obrigatório)* | Tipo de operação de crédito. |
| `interest_grace_period` | Carência de juros (em meses) |
| `number_of_installments` | Número de parcelas (mensais) |
| `principal_grace_period` | Carência do principal (em meses) |

### DESIRED INSTALLMENTS OBJECT

| Campo | Descrição |
|---|---|
| `due_date` | Data da parcela. |
| `total_amount` | Valor total da parcela |

### REBATES OBJECT

| Campo | Descrição |
|---|---|
| `amount` | Valor do rebate. |
| `fee_type` | Tipo de fee |
| `amount_type` | Tipo do valor inserido (valor absoluto, valor em porcentagem) |
| `rebate_bank_account` | Objeto conta bancária de rebate. |

### FINE CONFIGURATION OBJECT

| Campo | Descrição |
|---|---|
| `contract_fine_rate` *(obrigatório)* | Valor porcentual fixo da multa |
| `interest_base` | Contagem do tempo para multa ("calendar_days" para dias corridos, "workdays" para dias úteis) |
| `monthly_rate` | Valor porcentual mensal da multa |

### DISBURSEMENT BANK ACCOUNT OBJECT

| Campo | Descrição |
|---|---|
| `name`  | Nome do dono da conta para desembolso - Obrigatório apenas se o método de transferência for ted ou pix. e caso haja mais de uma conta para desembolso (Limite de 80 caracteres). |
| `bank_code` | Código COMPE da instituição financeira (https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf) com 3 dígitos - Obrigatório apenas se o método de transferência for ted ou pix e se "ispb_number" não for enviado. |
| `branch_number` | Número da agência - Obrigatório apenas se o método de transferência for ted ou pix. |
| `account_number` | Número da conta - Obrigatório apenas se o método de transferência for ted ou pix - Obrigatório apenas se o método de transferência for ted ou pix. |
| `document_number`| CPF ou CNPJ do dono da conta para desembolso - Obrigatório apenas se o método de transferência for ted ou pix. e caso haja mais de uma conta para desembolso. |
| `percentage_receivable` | Valor em porcentagem que a conta receberá no desembolso. Este campo é utilizado para definir a quantidade a ser dividida caso haja mais de uma conta para desembolso (no caso de ser somente uma conta, o valor integral será transferido). Caso a porcentagem não seja enviada (de uma, ou de todas as contas), a porcentagem restante será dividida igualmente entre as contas sem porcentagem definida. Caso todas as porcentagens sejam enviadas, a soma delas não pode passar de 100 - Obrigatório apenas se o método de transferência for ted ou pix. |
| `ispb_number` | Identificador da instituição no Sistema de Pagamentos Brasileiro - Obrigatório apenas se o método de transferência for ted ou pix e se o "bank_code" não for enviado. |
| `qr_code_key` | Chave fornecida no momento da criação de um QR Code PIX - Pode ser enviado como o único parâmetro deste objeto, assim o desembolso acontece como pagamento desse QR code PIX. |
| `digitable_line` | Representação numérica de um código de barras de um boleto - Pode ser enviado como o único parâmetro deste objeto, assim o desembolso acontece como pagamento desse boleto. |
| `transfer_method` | Por padrão as operações são desembolsadas via PIX, então quando existr a necessidade de que uma operação seja desembolsada via TED este campo pode ser enviado. |

---

# webhook_auxilio_brasil

URL: /documentation/auxilio_brasil/webhook_auxilio_brasil

## Webhook auxílio brasil

**Criação de uma operação**

Na criação de uma operação do Auxílio Brasil dentro do nosso sistema, são possíveis os seguintes status:

- **success**: Informa o sucesso na consulta do benefício.
- **failure**: Informa que ocorreu um erro na consulta do benefício.

**Exemplos**

Webhook de sucesso na consulta

**body.json**

```json
{
    "callback": {
        "key": "bfbe918d-fe58-55a0-bdaf-5a3733b7a12d",
        "data": {
            "name": "LUIZ ANTONIO DA SILVA",
            "state": "RJ",
            "balance": "111",
            "family_code": 8553463416,
            "reference_date": "2022-08-03",
            "benefit_net_amount": 294,
            "benefit_total_amount": 294,
            "disbursement_bank_account": {
                "bank_code": "103",
                "account_digit": "5",
                "account_branch": "3880",
                "account_number": "000925559475"
            },
            "number_of_active_reservations": 0
        },
        "status": "success",
        "webhook_type": "social_benefit_balance",
        "event_datetime": "2022-08-29T20:47:48"
    }
}

```

Webhook de erro na consulta

**body.json**

```json
{
    "callback": {
        "key": "5d85a8eb-94c1-4fcc-8f66-15b6301f6kfe",
        "data": {
            "enumerator": "not_found_family_member",
            "description": "there is not an active authorization for person"
        },
        "status": "failure",
        "webhook_type": "social_benefit_balance",
        "event_datetime": "2022-10-17T21:54:16"
    }
}

```

| Enumerators | Descrição |
|---|---|
| `dataprev_error`  | erro inesperado no Dataprev |
| `not_found_family_member` | não há uma autorização ativa para pessoa |
| `benefit_deleted`  | benefício foi excluído |

**Cancelamento de uma operação**

Existem alguns processos que cancelam uma operação de crédito, majoritariamente:

1. PIX/TED falhou ou foi estornado;
2. Passamos da data de desembolso;
3. Tentativa de averbação foi rejeitada;

Toda operação que está cancelada em nosso sistema pode voltar ao seu estado anterior através do método de mudança da data de desembolso.
Alguns casos não são possíveis de voltarem ao estado inicial porque nunca será desembolsada, como é o caso 3, cuja tentativa de averbação foi rejeitada.

Para o primeiro caso:

**body.json**

```json
{
    "key": "\<CHAVE DA OPERAÇÃO DE CRÉDITO\>",
    "data": {
        "pix_refusal": {
            "reason": "Número da conta de destino é inexistente ou inválido.",
            "reason_enumerator": "invalid_account"
        },
        "cancel_reason": "pix_refusal"
    },
    "status": "canceled",
    "webhook_type": "debt",
    "event_datetime": "2022-11-01 13:39:44"
}

```

A reason_enumerator pode ser conforme a lista abaixo:

| Enumerators | Descrição |
|---|---|
| `invalid_document_number`  | Documento inválido |
| `invalid_account` | Conta inválida |
| `unsupported_transaction`  | Transação não suportada |
| `blocked_account`  | Conta bloqueada |
| `closed_account`  | Conta fechada |
| `rejected_payment`  | Pagamento rejeitado |
| `amount_too_great`  | Valor monetário muito alto |
| `spi_timeout`  | Timeout do prestador de serviço |
| `receiver_error`  | Erro do receptor |
| `incorrect_account_type`  | Tipo de conta incorreta |
| `duplicity_of_payment_order`  | Ordem de pagamento duplicado |
| `refund_after_unexpected_value`  | Reembolso depois de valor inesperado |
| `refund_after_psp_error`  | Reembolso depois de erros no PSP |
| `refund_after_technical_issues`  | Reembolso depois de problemas técnicos |
| `refund_after_cancellation`  | Reembolso depois de cancelamento |
| `refund_after_fraud`  | Reembolso depois de fraude |
| `refund_after_payee_request`  | Reembolso após solicitação do beneficiário |
| `refund_after_fraud_report`  | Reembolso depois de relatório de fraude |
| `payee_not_in_allowed_list`  | Beneficiário não se encontra na lista permitida |
| `payee_in_blocked_list`  | Beneficiário se encontra na lista bloqueada |
| `unjustified_payment_order`  | Ordem de pagamento não justificado |

O segundo caso, ocorre quando algum processo interno dispara o cancelamento da Operação:

**body.json**

```json
{
    "key": "\<CHAVE DA OPERAÇÃO DE CRÉDITO\>",
    "data": {
        "cancel_reason": "Operacao cancelada manualmente",
        "cancel_reason_enumerator": "manual"
    },
    "status": "canceled",
    "webhook_type": "debt",
    "event_datetime": "2022-11-01 03:46:31"
}

```

Aqui podemos ter os seguintes "cancel_reason_enumerators":

- Cancel Reason Enumerators em rejeição de PAB:

| Enumerators | Descrição |
|---|---|
| `social_benefit_ineligible_benefit`  | Beneficio inelegível |
| `social_benefit_invalid_beneficiary_data` | Dados do beneficiário inválidos |
| `social_benefit_invalid_balance`  | Margem indisponível |
| `social_benefit_contract_limit_exceeded`  | O cliente não pode ter mais contratos |
| `social_benefit_installments_limit_exceeded`  | O cliente não pode ter esse numero de parcelas em um contrato |
| `social_benefit_invalid_disbursement_account`  | Conta divergente com o DataPrev |

- Cancel Reason Enumerators mudança de dia

| Enumerators | Descrição |
|---|---|
| `not_collateral_constituted_social_benefit`  | Mudou de dia e a operação não teve a garantia averbada |
| `waiting_signature` | Mudou de dia e a operação não foi assinada |
| `not_assigned`  | Mudou de dia e a CCB está configurada para desembolsar após a cessão, mas nao foi cedida |
| `disburse_is_not_allowed`  | Mudou de dia e a CCB está configurada com o fluxo de "Liberar o desembolso" mas não foi liberado |
| `manual`  | Mudou de dia e a operação não foi desembolsada. |

Os cancel reason começados com "social_benefit" são permanentes, então a reserva foi de fato rejeitada. Mas em relação aos outros, ainda podem retornar ao estado inicial então deve ser devidamente analisado.

---

# Confirmar Abertura de Conta de Pessoa Física

URL: /documentation/baas/account/2fa_v2/abrir_conta_pf

Como segunda etapa da abertura de conta pessoa física, [após a reserva de conta](/documentation/baas/account/abrir_conta_pf), devem ser enviados os dados cadastrais completos do titular e evidências do aceite nos termos de abertura da conta.

## Request
ENDPOINT /account_request/checking
MÉTODO POST

## Path Params
| Campo         | Tipo   | Descrição                              | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_request_key` | uuidv4 | Chave única de identificação solicitação de reserva da conta. | 36         |

Request Body

```json
{
    "account_owner": {
        "address": {
            "street": "Av. Brigadeiro Faria Lima",
            "state": "SP",
            "city": "São Paulo",
            "neighborhood": "Jardim Paulistano",
            "number": "2391",
            "postal_code": "01452905",
            "complement": "Complemento"
        },
        "birth_date": "1990-05-06",
        "document_identification": "3884579b-9810-4fa6-9b08-fe67d237160a",
        "email": "teste@gmail.com",
        "individual_document_number": "99999999999",
        "is_pep": false,
        "mother_name": "Dona Maria Mariane",
        "name": "Nome do Titular da Conta",
        "nationality": "nationality",
        "person_type": "natural",
        "phone": {
            "country_code": "055",
            "area_code": "11",
            "number": "999999999"
        },
        "proof_of_residence": "4d7f4e-1eec-4e5f-82c0-d8c3921497ea"
    },
    "signed_contract": {
        "document_key": "48a8f4g9-4b58-4905-9a69-b1f9215263f5",
        "signatures": [
            {
                "authenticity": {
                    "timestamp": "1970-01-01T00:00:01.080100Z",
                    "facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
                    "lang": "-35.8916627",
                    "lat": "-7.2226067",
                    "ip_address": "177.51.1.186",
                    "session_id": "jdifj329842"
                },
                "signer": {
                    "name": "Nome do Titular da Conta",
                    "email": "teste@gmail.com",
                    "phone": {
                        "country_code": "055",
                        "area_code": "11",
                        "number": "999999999"
                    },
                    "document_number": "999999999"
                },
                "authentication_type": "opt-in"
            }
        ]
    },
    "additional_documents": ["b12c8807-8f3f-4083-9cb1-7cce641f3786"]
}
```

### Request Body Params

| Campo | Tipo | Descrição                                                                                  | Caracteres |
|---|---|--------------------------------------------------------------------------------------------|---|
| `account_owner` * | object  | Objeto contendo as informações do Titular da Conta                                         | **[Objeto account_owner](#objeto-account_owner)** |
| `signed_contract` * | object  | Objeto contendo as evidências do aceito do Titular quanto aos termos de abertura da conta. | **[Objeto signed_contract](#objeto-signed_contract)** |

### Objeto account_owner

| Campo | Tipo | Descrição | Caracteres                            |
|---| ---| ---|---------------------------------------| 
| `address` * | string | Endereço do cliente. | **[Objeto address](#objeto-address)** |  |
| `birth_date` * | string |  Data de nascimento da pessoa (formato "AAAA-MM-DD") |                                       |
| `document_identification` * | string |  DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) |                                       |
| `document_identification_type` * | string |  Tipo do documento enviado previamente (RG ou CNH) |                                       |
| `email` * | string |  Email do cliente. |                                       |
| `individual_document_number` | string | CPF da pessoa (apenas números). Limitado a 11 caracteres. |                                       |
| `is_pep` * | string |  Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep).|                                       |
| `mother_name` * | string |  Nome da mãe do cliente em caso de PF. | 100                                   |
| `name` * | string |  Razão social em caso de operações PJ ou Nome da pessoa em caso de operações PF. | 100                                   |
| `nationality` * | string |  Nacionalidade do cliente. | 50                                    |
| `person_type` * | string | Identificador de que o objeto enviado é uma pessoa física ou jurídica.|                                       |
| `phone` * | string | Objeto com dados do telefone | **[Objeto phone](#objeto-phone)**     |
| `proof_of_residence` | string |  DOCUMENT_KEY do PDF do comprovante de endereço do endereço enviado (enviado previamente).|                                       |

### Objeto address 

Este objeto, presente tanto no objeto PF quanto no objeto PJ, é um simples objeto para representar um endereço.

| Campo | Descrição | Exemplo |  Máx. Caracteres | 
|---|---|---|---| 
| `street` *| string | Rua do endereço  | 100 |
| `state` *| string | Estado do endereço (com dois caracteres maiúsculos) | 2 |
| `city` *| string | Cidade do endereço | 100 |
| `neighborhood` *| string |Bairro do endereço | 100 |
| `number` *| string | Número da rua | 10 |
| `postal_code` *| string |CEP do endereço (http://www.buscacep.correios.com.br/sistemas/buscacep/) (apenas números) |  8 |
| `complement` *| string |Complemento do endereço (texto livre) | 100 |

### Objeto signed_contract 
| Campo | Tipo   | Descrição        | Caracteres    |
|-------|--------|------------------|---------------|
| **document_key** * | uuidv4 | Chave única de identificação do documento do **Termo de Abertura de Conta** ou **Contrato de Conta Escrow**. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36            |
| **signatures** *   | list   | Dados de assinatura do documento enviado. Cada item da lista, corresponde a um assinante do documento.      | [Objeto signatures](#objeto-signatures) |

### Objeto signatures
| Campo | Tipo       | Descrição         | Caracteres        |
|-------|------------|-------------------|-------------------|
| **authenticity** * | object     | Conjunto de dados que evidenciam a assinatura eletrônica realizada pelo assinante. | [Objeto authenticity](#objeto-authenticity) |
| **signer** * | object     | Objeto contendo os dados de um dos assinantes do documento.           | [Objeto signer](#objeto-signer)|
| **authentication_type** * | enumerator | Tipo de assinatura. Sempre será "**opt-in**"| "**opt-in**"                   |

### Objeto authenticity
| Campo | Tipo   | Descrição               | Caracteres |
|-------|--------|-------------------------|------------|
| **timestamp** *            | string | Data e hora do momento da assinatura do documento.                | 27         |
| **facial_recognition_key** | uuidv4 | Chave única de identificação da foto da selfie do titular da conta. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36         |
| **lang**                   | string | Coordenada de longitude da geolocalização do assinante capturada no momento da assinatura.                  | -          |
| **lat**                    | string | Coordenada de latitude da geolocalização do assinante capturada no momento da assinatura.                   | -          |
| **ip_address**             | string | Endereço IP do dispositivo do assinante.     | -          |
| **session_id**             | string | ID da seção do assinante no momento da assinatura.                | -          |

### Objeto signer
| Campo                 | Tipo   | Descrição                                 | Caracteres                        |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** *            | string | Nome do assinante.                        | -                                 |
| **email** *           | string | Email do assinante.                       | -                                 |
| **phone** *           | object | Objeto com dados do telefone do assinante | **[Objeto phone](#objeto-phone)** |
| **document_number** * | string | CPF do assinante.                         | 11                                |

### Objeto phone 

| Campo | Descrição | Exemplo |  Máx. Caracteres | 
| --- | --- | --- | --- | 
|`country_code` *| string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 | 
| `area_code` *| string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |Número de telefone (apenas números) |  10 |

## Response

STATUS 201

Response Body

```json
{
    "account_info": {
        "account_branch": "0001",
        "account_digit": "0",
        "account_number": "1693580"
    },
    "account_request_key": "f230f1b5-07af-4737-b0e3-8a472304f5e7",
    "account_request_status": "pending_kyc_analysis"
}
```

:::warning Atenção
 O campo `account_request_key` deve ser armazenado e será utilizado para a confirmação da abertura da conta.
:::

### Response Body Params

| Campo | Tipo | Descrição | Caracteres|
|---|---| ---|---|
| `account_info` * | object  | Objeto contendo as informações do Titular da Conta |**[Objeto account_info](#objeto-account_info)**  | - |
| `account_request_key` * | string  | Chave de identificação da requisição de criação | - | - |
| `account_request_status` * | string  | Status de KYC | - | - |

### Objeto account_info
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| --- |
| `account_branch` * | string  | Número da Agência | 4 |
| `account_digit` * | string  | Email | 11 |
| `account_number` * | string  | Nome Completo do Titular da Conta | 50 |

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`  | Descrição (eng)<br/>`description` | Descrição(ptbr) <br></br>`translation`|
|---| --- | --- | --- | --- | 
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|

---

# Abertura de Conta de Pessoa Jurídica

URL: /documentation/baas/account/2fa_v2/abrir_conta_pj

A abertura de conta ocorre em duas etapas obrigatórias. Primeiro, uma requisição POST envia dados preliminares para reservar a conta. Em seguida, um webhook do tipo `account_request.status_change` com o status `pending_additional_data` é disparado. Na segunda etapa, uma requisição PATCH finaliza a abertura, oficializando a conta com as informações complementares. 

## Request
ENDPOINT /account_request/checking
MÉTODO POST

## Path Params
| Campo         | Tipo   | Descrição                              | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_request_key` | uuidv4 | Chave única de identificação solicitação de reserva da conta. | 36         |

## Abertura da Conta de Livre Movimentação

Request Body

```json
{
    "account_owner": {
        "phone": {
            "country_code": "55",
            "area_code": "11",
            "number": "999999999"
        },
        "email": "email@teste.com.br",
        "person_type": "legal",
        "name": "Empresa de Teste",
        "address": {
            "street": "Rua Abrahão Calux",
            "state": "SP",
            "city": "São Paulo",
            "neighborhood": "Vila Teste",
            "number": "116",
            "postal_code": "04286100",
            "complement": "Complemento"
        },
        "trading_name": "Nome fantasia",
        "company_document_number": "99999999000130",
        "cnae_code": "4721102",
        "foundation_date": "1980-07-11",
        "company_statute": "99999999-01c9-4cf5-a0fa-1d2a96f4b34d",
        "company_representatives": [
            {
                "name": "Nome do Socio",
                "individual_document_number": "99999999999",
                "document_identification_number": "999999999",
                "birth_date": "1989-09-01",
                "mother_name": "Maria da Silva",
                "email": "teste@gmail.com",
                "is_pep": false,
                "final_beneficiary": true,
                "person_type": "natural",
                "nationality": "brasileiro(a)",
                "marital_status": "single",
                "document_identification": "88888-0ddf-4932-874f-9231794963da",
                "phone": {
                    "country_code": "055",
                    "area_code": "19",
                    "number": "999999999"
                },
                "address": {
                    "street": "Rua dos Limões",
                    "neighborhood": "Vila Moinho Velho",
                    "city": "São Paulo",
                    "state": "SP",
                    "postal_code": "04286100",
                    "number": "116",
                    "complement": "complemento"
                }
            }
        ],
        "company_type": "ltda"
    },
    "signed_contract": {
        "document_key": "57cda530-d469-4427-a9d4-2523a510dee1",
        "signatures": [
            {
                "authenticity": {
                    "timestamp": "2024-05-10T14:15:03.114895Z",
                    "ip_address": "192168161",
                    "lang": "-35.8916627",
                    "lat": "-7.2226067",
                    "session_id": "54b8e3cf-15de-41e5-9305-0ecf059d6e2a",
                    "facial_recognition_key": "c367a540-2e7e-4373-a167-61bc43c30dc1"
                },
                "signer": {
                    "name": "Nome do assinante",
                    "email": "teste@gmail.com.br",
                    "phone": {
                        "country_code": "55",
                        "area_code": "11",
                        "number": "999999999"
                    },
                    "document_number": "99999999"
                },
                "authentication_type": "opt-in"
            }
        ]
    },
    "additional_documents": [
        "61f2a65e-0ddf-4932-874f-9231794963da"
    ]
}
```

### Request Body Params

| Campo                 | Tipo   | Descrição                                                                    | Caracteres                                            |
|-----------------------|--------|------------------------------------------------------------------------------|-------------------------------------------------------|
| **account_owner** *   | object | Objeto Dono da conta                                                         | **[Objeto account_owner](#objeto-account_owner)**     |
| **allowed_user** *    | object | Usuário vinculado a conta.                                                   | **[Objeto allowed_user](#objeto-allowed_user)**       |
| **account_manager**   | object | Dados do parceiro integrador que realizará a movimentação da conta via API.  | **[Objeto account_manager](#objeto-account_manager)** |
| `signed_contract` *| object | Objeto contento as informações da assinatura do contrato. | **[Objeto signed_contract](#objeto-signed_contract)** |

### Objeto account_owner

| Campo                         | Tipo   | Descrição                                                                                                                         | Caracteres                                                            |
|-------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
| **address** *                 | object | Objeto endereço do titular da conta                                                                                               | **[Objeto address](#objeto-address)**                                 |
| **cnae_code** *               | string | Classificação Nacional de Atividades Econômicas                                                                                   | 9                                                                     |
| **company_document_number** * | string | CNPJ                                                                                                                              | 14                                                                    |
| **company_statute** *         | string | DOCUMENT_KEY do PDF do estatuto da empresa (enviado previamente).                                                                 | 36                                                                    |
| **company_type**              | enum   | Tipo da empresa                                                                                                                   | **[Enumeradores company_type](#enumeradores-company_type)**           |
| **company_representatives** * | list   | Lista dos representantes legais da empresa                                                                                        | **[Objeto company_representatives](#objeto-company_representatives)** |
| **email** *                   | string | Email institucional da empresa.                                                                                                   | 254                                                                   |
| **foundation_date** *         | string | Data de abertura da empresa (formato "AAAA-MM-DD").                                                                               | 10                                                                    |
| **name** *                    | string | Razão social.                                                                                                                     | 100                                                                   |
| **person_type** *             | enum   | Identificador de que o objeto enviado é uma pessoa jurídica. Deve conter SEMPRE o valor "legal" para Objeto PJ.                   | **[Enumeradores person_type](#enumeradores-person_type)**             |
| **phone** *                   | object | Telefone do titular da conta.                                                                                                     | **[Objeto phone](#objeto-phone)**                                     | - |
| **trading_name** *            | string | Nome fantasia.                                                                                                                    | 200                                                                   |

### Objeto company_representatives

| Campo                              | Tipo    | Descrição                                                                                              | Caracteres                                                                              |
|------------------------------------|---------|--------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
| **name** *                         | string  | Nome do representante da empresa                                                                       | 100                                                                                     |
| **address** *                      | object  | Objeto endereço do representante da empresa                                                            | **[Objeto address](#objeto-address)**                                                   |
| **email** *                        | string  | Email do representante da empresa                                                                      | 254                                                                                     |
| **birth_date** *                   | string  | Data de nascimento representante da empresa (formato "AAAA-MM-DD")                                     | 10                                                                                      |
| **individual_document_number** *   | string  | CPF do representante da empresa (apenas números).                                                      | 11                                                                                      |
| **document_identification**        | string  | DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) | 36                                                                                      |
| **document_identification_number** | string  | Número do documento de identificação com foto da pessoa (RG ou CNH)                                    | 16                                                                                      |
| **document_identification_type**   | enum    | Tipo do documento de identificação com foto da pessoa (RG ou CNH)                                      | [Enumeradores document_identification_type](#enumeradores-document_identification_type) |
| **is_pep** *                       | boolean | Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep).          | -                                                                                       |
| **final_beneficiary**              | boolean | Declaração se o representante é beneficiário final da empresa.                                         | -                                                                                       |
| **marital_status**                 | enum    | Estado civil do representante da empresa                                                               | **[Enumeradores marital status](#enumeradores-marital_status)**                         |
| **mother_name** *                  | string  | Nome da mãe do representante da empresa                                                                | 100                                                                                     |
| **nationality**                    | string  | Nacionalidade do representante da empresa                                                              | 50                                                                                      |
| **person_type** *                  | enum    | Identificador de que o objeto enviado é uma pessoa física                                              | **[Enumeradores person_type](#enumeradores-person_type)**                               |
| **phone** * | object  | Objeto com dados do telefone do representante da empresa  | **[Objeto phone](#objeto-phone)** |

### Objeto address

Este objeto, presente tanto no objeto PF quanto no objeto PJ, é um simples objeto para representar um endereço.

| Campo              | Descrição | Exemplo                                                                                   | Caracteres |
|--------------------|-----------|-------------------------------------------------------------------------------------------|------------|
| **street** *       | string    | Rua do endereço                                                                           | 500        |
| **state** *        | enum      | Estado do endereço (com dois caracteres maiúsculos)                                       | 2          |
| **city** *         | string    | Cidade do endereço                                                                        | 255        |
| **neighborhood** * | string    | Bairro do endereço                                                                        | 500        |
| **number** *       | string    | Número da rua                                                                             | 10         |
| **postal_code** *  | string    | CEP do endereço (http://www.buscacep.correios.com.br/sistemas/buscacep/) (apenas números) | 8          |
| **complement**     | string    | Complemento do endereço (texto livre)                                                     | 500        |

### Objeto signed_contract 
| Campo | Tipo   | Descrição        | Caracteres    |
|-------|--------|------------------|---------------|
| **document_key** * | uuidv4 | Chave única de identificação do documento do **Termo de Abertura de Conta** ou **Contrato de Conta Escrow**. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36            |
| **signatures** *   | list   | Dados de assinatura do documento enviado. Cada item da lista, corresponde a um assinante do documento.      | [Objeto signatures](#objeto-signatures) |

### Objeto signatures
| Campo | Tipo       | Descrição         | Caracteres        |
|-------|------------|-------------------|-------------------|
| **authenticity** * | object     | Conjunto de dados que evidenciam a assinatura eletrônica realizada pelo assinante. | [Objeto authenticity](#objeto-authenticity) |
| **signer** * | object     | Objeto contendo os dados de um dos assinantes do documento.           | [Objeto signer](#objeto-signer)|
| **authentication_type** * | enumerator | Tipo de assinatura. Sempre será "**opt-in**"| "**opt-in**"                   |

### Objeto authenticity
| Campo | Tipo   | Descrição               | Caracteres |
|-------|--------|-------------------------|------------|
| **timestamp** *            | string | Data e hora do momento da assinatura do documento.                | 27         |
| **facial_recognition_key** | uuidv4 | Chave única de identificação da foto da selfie do titular da conta. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36         |
| **lang**                   | string | Coordenada de longitude da geolocalização do assinante capturada no momento da assinatura.                  | -          |
| **lat**                    | string | Coordenada de latitude da geolocalização do assinante capturada no momento da assinatura.                   | -          |
| **ip_address**             | string | Endereço IP do dispositivo do assinante.     | -          |
| **session_id**             | string | ID da seção do assinante no momento da assinatura.                | -          |

### Objeto signer
| Campo                 | Tipo   | Descrição                                 | Caracteres                        |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** *            | string | Nome do assinante.                        | -                                 |
| **email** *           | string | Email do assinante.                       | -                                 |
| **phone** *           | object | Objeto com dados do telefone do assinante | **[Objeto phone](#objeto-phone)** |
| **document_number** * | string | CPF do assinante.                         | 11                                |

### Objeto phone 

| Campo | Descrição | Exemplo |  Máx. Caracteres | 
| --- | --- | --- | --- | 
|`country_code` *| string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 | 
| `area_code` *| string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |Número de telefone (apenas números) |  10 |

### Enumeradores person_type
| Enum        | Description       |
|-------------|-------------------|
| **natural** | Pessoa física     |
| **legal**   | Pessoa jurídica   |

### Enumeradores document_identification_type
| Enum    | Description                            |
|---------|----------------------------------------|
| **rg**  | RG - Registro Geral                    |
| **cnh** | CNH - Carteira Nacional de Habilitação |

### Enumeradores company_type
| Enum                       | 	Description                                                             |
|----------------------------|--------------------------------------------------------------------------|
| **ltda**                   | Limitada                                                                |
| **sa**	                    | Sociedade Anônima                                                        |
| **micro_enterprise**	      | Micro Empresa                                                            |
| **freelancer**             | Freelancer                                                              |
| **sa_opened**              | Sociedade Anônima de Capital Aberto                                     |
| **sa_closed**	             | Sociedade Anônima de Capital Fechado                                     |
| **se_ltda**                | Sociedade Empresária Limitada                                           |
| **se_cn**                  | Sociedade Empresária em Nome Coletivo                                   |
| **se_cs**                  | Sociedade Empresária em Comandita Simples                               |
| **se_ca**	                 | Sociedade Empresária em Comandita por Ações                              |
| **scp**                    | Sociedade em Conta de Participação                                      |
| **ei**	                    | Empresário Individual                                                    |
| **ese**	                   | Estabelecimento, no Brasil, de Sociedade Estrangeira                     |
| **eeab**	                  | Estabelecimento, no Brasil, de Empresa Binacional Argentino-Brasileira   |
| **ssp**                    | Sociedade Simples Pura                                                  |
| **ss_ltda**	               | Sociedade Simples Limitada                                               |
| **ss_cn**                  | Sociedade Simples em Nome Coletivo                                      |
| **ss_cs**                  | Sociedade Simples em Comandita Simples                                  |
| **eireli_ne**              | Empresa Individual de Responsabilidade Limitada (de Natureza Empresária) |
| **eireli_ns**              | Empresa Individual de Responsabilidade Limitada (de Natureza Simples)   |
| **eireli**                 | Empresa de Responsabilidade Individual                                  |
| **mei**                    | Micro Empreendedor Individual                                            |
| **me**	                    | Micro Empresa                                                            |
| **cop**	                   | Cooperativa                                                              |
| **private_association**	   | Sociedade Privada                                                        |

### Enumeradores marital_status
| Enum         | 	Description  |
|--------------|---------------|
| **single**   | Solteiro(a)   |
| **married**  | Casado(a)    |
| **widower**  | Viúvo(a)     |
| **divorced** | Divorciado(a) |
| **separated** | Separado(a) |

## Response

STATUS 201

Response Body

```json
{
    "account_info": {
        "account_branch": "0001",
        "account_digit": "0",
        "account_number": "1693580"
    },
    "account_request_key": "f230f1b5-07af-4737-b0e3-8a472304f5e7",
    "account_request_status": "pending_kyc_analysis"
}
```

:::warning Atenção
 O campo `account_request_key` deve ser armazenado e será utilizado para a confirmação da abertura da conta.
:::

### Response Body Params

| Campo | Tipo | Descrição | Caracteres|
|---|---| ---|---|
| `account_info` * | object  | Objeto contendo as informações do Titular da Conta |**[Objeto account_info](#objeto-account_info)**  | - |
| `account_request_key` * | string  | Chave de identificação da requisição de criação | - | - |
| `account_request_status` * | string  | Status de KYC | - | - |

### Objeto account_info
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| --- |
| `account_branch` * | string  | Número da Agência | 4 |
| `account_digit` * | string  | Email | 11 |
| `account_number` * | string  | Nome Completo do Titular da Conta | 50 |

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`  | Descrição (eng)<br/>`description` | Descrição(ptbr) <br></br>`translation`|
|---| --- | --- | --- | --- | 
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|

---

# Confirmar Abertura de Conta de Pessoa Física

URL: /documentation/baas/account/abrir_conta_pf

Como segunda etapa da abertura de conta pessoa física, [após a reserva de conta](/documentation/baas/account/abrir_conta_pf), devem ser enviados os dados cadastrais completos do titular e evidências do aceite nos termos de abertura da conta.

## Request
ENDPOINT /account_request/ ACCOUNT_REQUEST_KEY /checking
MÉTODO PATCH

## Path Params
| Campo         | Tipo   | Descrição                              | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_request_key` | uuidv4 | Chave única de identificação solicitação de reserva da conta. | 36         |

Request Body

```json
{
    "account_owner": {
        "address": {
            "street": "Av. Brigadeiro Faria Lima",
            "state": "SP",
            "city": "São Paulo",
            "neighborhood": "Jardim Paulistano",
            "number": "2391",
            "postal_code": "01452905",
            "complement": "Complemento"
        },
        "birth_date": "1990-05-06",
        "document_identification": "3884579b-9810-4fa6-9b08-fe67d237160a",
        "email": "teste@gmail.com",
        "individual_document_number": "99999999999",
        "is_pep": false,
        "mother_name": "Dona Maria Mariane",
        "name": "Nome do Titular da Conta",
        "nationality": "nationality",
        "person_type": "natural",
        "phone": {
            "country_code": "055",
            "area_code": "11",
            "number": "999999999"
        },
        "proof_of_residence": "4d7f4e-1eec-4e5f-82c0-d8c3921497ea",
        "monthly_income": 1000
    },
    "signed_contract": {
        "document_key": "48a8f4g9-4b58-4905-9a69-b1f9215263f5",
        "signatures": [
            {
                "authenticity": {
                    "timestamp": "1970-01-01T00:00:01.080100Z",
                    "facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
                    "lang": "-35.8916627",
                    "lat": "-7.2226067",
                    "ip_address": "177.51.1.186",
                    "session_id": "jdifj329842"
                },
                "signer": {
                    "name": "Nome do Titular da Conta",
                    "email": "teste@gmail.com",
                    "phone": {
                        "country_code": "055",
                        "area_code": "11",
                        "number": "999999999"
                    },
                    "document_number": "999999999"
                },
                "authentication_type": "opt-in"
            }
        ]
    },
    "additional_documents": ["b12c8807-8f3f-4083-9cb1-7cce641f3786"]
}
```

### Request Body Params

| Campo | Tipo | Descrição                                                                                  | Caracteres |
|---|---|--------------------------------------------------------------------------------------------|---|
| `account_owner` * | object  | Objeto contendo as informações do Titular da Conta                                         | **[Objeto account_owner](#objeto-account_owner)** |
| `signed_contract` * | object  | Objeto contendo as evidências do aceito do Titular quanto aos termos de abertura da conta. | **[Objeto signed_contract](#objeto-signed_contract)** |

### Objeto account_owner

| Campo | Tipo | Descrição | Caracteres                            |
|---| ---| ---|---------------------------------------| 
| `address` * | string | Endereço do cliente. | **[Objeto address](#objeto-address)** |  |
| `birth_date` | string |  Data de nascimento da pessoa (formato "AAAA-MM-DD") |                                       |
| `document_identification` * | string |  DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) |                                       |                                   |
| `email` * | string |  Email do cliente. |                                       |
| `individual_document_number`* | string | CPF da pessoa (apenas números). Limitado a 11 caracteres. |                                       |
| `is_pep` * | string |  Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep).|                                       |
| `mother_name` | string |  Nome da mãe do cliente em caso de PF. | 100                                   |
| `name` * | string |  Razão social em caso de operações PJ ou Nome da pessoa em caso de operações PF. | 100                                   |
| `nationality` * | string |  Nacionalidade do cliente. | 50                                    |
| `person_type` * | string | Identificador de que o objeto enviado é uma pessoa física ou jurídica.|                                       |
| `phone` * | string | Objeto com dados do telefone | **[Objeto phone](#objeto-phone)**     |
| `proof_of_residence` | string |  DOCUMENT_KEY do PDF do comprovante de endereço do endereço enviado (enviado previamente).|                                       |
|`monthly_income`* | number | Renda mensal do titular da conta | | 

### Objeto address 

Este objeto, presente tanto no objeto PF quanto no objeto PJ, é um simples objeto para representar um endereço.

| Campo | Descrição | Exemplo |  Máx. Caracteres | 
|---|---|---|---| 
| `street` *| string | Rua do endereço  | 100 |
| `state` *| enum | Estado do endereço (com dois caracteres maiúsculos) | 2 |
| `city` *| string | Cidade do endereço | 100 |
| `neighborhood` *| string |Bairro do endereço | 100 |
| `number` *| string | Número da rua | 10 |
| `postal_code` *| string |CEP do endereço (http://www.buscacep.correios.com.br/sistemas/buscacep/) (apenas números) |  8 |
| `complement` *| string |Complemento do endereço (texto livre) | 100 |

### Objeto signed_contract 
| Campo | Tipo   | Descrição        | Caracteres                                |
|-------|--------|------------------|-------------------------------------------|
| `document_key` * | uuidv4 | Chave única de identificação do documento do **Termo de Abertura de Conta** ou **Contrato de Conta Escrow**. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36                                        |
| `signatures` *   | list   | Dados de assinatura do documento enviado. Cada item da lista, corresponde a um assinante do documento.      | **[Objeto signatures](#objeto-signatures)** |

### Objeto signatures
| Campo | Tipo       | Descrição         | Caracteres                                      |
|-------|------------|-------------------|-------------------------------------------------|
| `authenticity` * | object     | Conjunto de dados que evidenciam a assinatura eletrônica realizada pelo assinante. | **[Objeto authenticity](#objeto-authenticity)** |
| `signer` * | object     | Objeto contendo os dados de um dos assinantes do documento.           | **[Objeto signer](#objeto-signer)**             |
| `authentication_type` * | enumerator | Tipo de assinatura. Sempre será "**opt-in**"| "**opt-in**"                                    |

### Objeto authenticity
| Campo | Tipo   | Descrição               | Caracteres |
|-------|--------|-------------------------|------------|
| `timestamp` *            | string | Data e hora do momento da assinatura do documento.                | 27         |
| `facial_recognition_key`* | uuidv4 | Chave única de identificação da foto da selfie do titular da conta. | 36         |
| `lang`                  | string | Coordenada de longitude da geolocalização do assinante capturada no momento da assinatura.                  | -          |
| `lat`                    | string | Coordenada de latitude da geolocalização do assinante capturada no momento da assinatura.                   | -          |
| `ip_address`             | string | Endereço IP do dispositivo do assinante.     | -          |
| `session_id`  *           | string | ID da seção do assinante no momento da assinatura.                | -          |

### Objeto signer
| Campo                 | Tipo   | Descrição                                 | Caracteres                        |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| `name` *            | string | Nome do assinante.                        | -                                 |
| `email` *           | string | Email do assinante.                       | -                                 |
| `phone` *           | object | Objeto com dados do telefone do assinante | **[Objeto phone](#objeto-phone)** |
| `document_number` * | string | CPF do assinante.                         | 11                                |

### Objeto phone 

| Campo | Descrição | Exemplo |  Máx. Caracteres | 
| --- | --- | --- | --- | 
|`country_code` *| string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 | 
| `area_code` *| string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |Número de telefone (apenas números) |  10 |

## Response

STATUS 201

Response Body

```json
 { "account_key": "78ea0fa6-8ea6-46ff-b66b-d2bc36fc8869" }
```

:::warning Atenção
 O campo `account_request_key` deve ser armazenado e será utilizado para a confirmação da abertura da conta.
:::

### Response Body Params

| Campo | Tipo | Descrição | Caracteres                                      |
|---|---| ---|-------------------------------------------------|
| `account_key` * | string  | Chave de única de identificação da conta| -                                               | - |

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`  | Descrição (eng)<br/>`description` | Descrição(ptbr) <br></br>`translation`|
|---| --- | --- | --- | --- | 
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|

---

# Confirmar Abertura de Conta de Pessoa Jurídica

URL: /documentation/baas/account/abrir_conta_pj

A abertura de conta ocorre em duas etapas obrigatórias. Primeiro, uma requisição POST envia dados preliminares para reservar a conta. Em seguida, um webhook do tipo `account_request.status_change` com o status `pending_additional_data` é disparado. Na segunda etapa, uma requisição PATCH finaliza a abertura, oficializando a conta com as informações complementares. 

## Request
ENDPOINT /account_request/ ACCOUNT_REQUEST_KEY /checking
MÉTODO PATCH

## Path Params
| Campo         | Tipo   | Descrição                              | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_request_key` | uuidv4 | Chave única de identificação solicitação de reserva da conta. | 36         |

## Abertura da Conta de Livre Movimentação

Request Body

```json
{
    "account_owner": {
        "phone": {
            "country_code": "55",
            "area_code": "11",
            "number": "999999999"
        },
        "email": "email@teste.com.br",
        "person_type": "legal",
        "name": "Empresa de Teste",
        "address": {
            "street": "Rua Abrahão Calux",
            "state": "SP",
            "city": "São Paulo",
            "neighborhood": "Vila Teste",
            "number": "116",
            "postal_code": "04286100",
            "complement": "Complemento"
        },
        "trading_name": "Nome fantasia",
        "company_document_number": "99999999000130",
        "cnae_code": "4721102",
        "foundation_date": "1980-07-11",
        "company_statute": "99999999-01c9-4cf5-a0fa-1d2a96f4b34d",
        "monthly_revenue": 100000,
        "company_representatives": [
            {
                "name": "Nome do Socio",
                "individual_document_number": "99999999999",
                "document_identification_number": "999999999",
                "birth_date": "1989-09-01",
                "mother_name": "Maria da Silva",
                "email": "teste@gmail.com",
                "is_pep": false,
                "final_beneficiary": true,
                "person_type": "natural",
                "nationality": "brasileiro(a)",
                "marital_status": "single",
                "document_identification": "88888-0ddf-4932-874f-9231794963da",
                "phone": {
                    "country_code": "055",
                    "area_code": "19",
                    "number": "999999999"
                },
                "address": {
                    "street": "Rua dos Limões",
                    "neighborhood": "Vila Moinho Velho",
                    "city": "São Paulo",
                    "state": "SP",
                    "postal_code": "04286100",
                    "number": "116",
                    "complement": "complemento"
                },
                "representative_relationship": "ceo"
            }
        ],
        "company_type": "ltda"
    },
    "signed_contract": {
        "document_key": "57cda530-d469-4427-a9d4-2523a510dee1",
        "signatures": [
            {
                "authenticity": {
                    "timestamp": "2024-05-10T14:15:03.114895Z",
                    "ip_address": "192168161",
                    "lang": "-35.8916627",
                    "lat": "-7.2226067",
                    "session_id": "54b8e3cf-15de-41e5-9305-0ecf059d6e2a",
                    "facial_recognition_key": "c367a540-2e7e-4373-a167-61bc43c30dc1"
                },
                "signer": {
                    "name": "Nome do assinante",
                    "email": "teste@gmail.com.br",
                    "phone": {
                        "country_code": "55",
                        "area_code": "11",
                        "number": "999999999"
                    },
                    "document_number": "99999999"
                },
                "authentication_type": "opt-in"
            }
        ]
    },
    "additional_documents": [
        "61f2a65e-0ddf-4932-874f-9231794963da"
    ]
}
```

### Request Body Params

| Campo                 | Tipo   | Descrição                                                                            | Caracteres                                            |
|-----------------------|--------|--------------------------------------------------------------------------------------|-------------------------------------------------------|
| `account_owner` *   | object | Objeto titular da conta                                                              | **[Objeto account_owner](#objeto-account_owner)**     |
| `signed_contract` *| object | Objeto contento as informações do aceita eletrônico dos termos de abertura da conta. | **[Objeto signed_contract](#objeto-signed_contract)** |
| `additional_documents` *| list   | Lista com as `document_key` (uuidv4) dos documentos adicionais do titular da conta.  | 36 |

### Objeto account_owner

| Campo                         | Tipo   | Descrição                                                                                                                         | Caracteres                                                            |
|-------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
| `address` *                 | object | Objeto endereço do titular da conta                                                                                               | **[Objeto address](#objeto-address)**                                 |
| `cnae_code`               | string | Classificação Nacional de Atividades Econômicas                                                                                   | 9                                                                     |
| `company_document_number` * | string | CNPJ                                                                                                                              | 14                                                                    |
| `company_statute` *         | string | DOCUMENT_KEY do PDF do estatuto da empresa (enviado previamente).                                                                 | 36                                                                    |
| `company_type`*              | enum   | Tipo da empresa                                                                                                                   | **[Enumeradores company_type](#enumeradores-company_type)**           |
| `company_representatives` * | list   | Lista dos representantes legais da empresa                                                                                        | **[Objeto company_representatives](#objeto-company_representatives)** |
| `email` *                   | string | Email institucional da empresa.                                                                                                   | 254                                                                   |
| `foundation_date`         | string | Data de abertura da empresa (formato "AAAA-MM-DD").                                                                               | 10                                                                    |
| `name` *                    | string | Razão social.                                                                                                                     | 100                                                                   |
| `person_type` *             | enum   | Identificador de que o objeto enviado é uma pessoa jurídica. Deve conter SEMPRE o valor "legal" para Objeto PJ.                   | **[Enumeradores person_type](#enumeradores-person_type)**             |
| `phone` *                   | object | Telefone do titular da conta.                                                                                                     | **[Objeto phone](#objeto-phone)**                                     | - |
| `trading_name` *            | string | Nome fantasia.                                                                                                                    | 200                                                                   |
| `monthly_revenue`* | number | Faturamento mensal da empresa | |

### Objeto company_representatives

| Campo                              | Tipo    | Descrição                                                                                              | Caracteres                                                                                  |
|------------------------------------|---------|--------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| `name` *                         | string  | Nome do representante da empresa                                                                       | 100                                                                                         |
| `address` *                      | object  | Objeto endereço do representante da empresa                                                            | **[Objeto address](#objeto-address)**                                                       |
| `email` *                        | string  | Email do representante da empresa                                                                      | 254                                                                                         |
| `birth_date`                   | string  | Data de nascimento representante da empresa (formato "AAAA-MM-DD")                                     | 10                                                                                          |
| `individual_document_number` *   | string  | CPF do representante da empresa (apenas números).                                                      | 11                                                                                          |
| `document_identification`*        | string  | DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) | 36                                                                                          |
| `document_identification_number`* | string  | Número do documento de identificação com foto da pessoa (RG ou CNH)                                    | 16                                                                                          |
| `document_identification_type`   | enum    | Tipo do documento de identificação com foto da pessoa (RG ou CNH)                                      | **[Enumeradores document_identification_type](#enumeradores-document_identification_type)** |
| `is_pep` *                       | boolean | Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep).          | -                                                                                           |
| `final_beneficiary`              | boolean | Declaração se o representante é beneficiário final da empresa.                                         | -                                                                                           |
| `marital_status`                 | enum    | Estado civil do representante da empresa                                                               | **[Enumeradores marital status](#enumeradores-marital_status)**                             |
| `mother_name`                  | string  | Nome da mãe do representante da empresa                                                                | 100                                                                                         |
| `nationality`                    | string  | Nacionalidade do representante da empresa                                                              | 50                                                                                          |
| `person_type` *                  | enum    | Identificador de que o objeto enviado é uma pessoa física                                              | **[Enumeradores person_type](#enumeradores-person_type)**                                   |
| `phone` * | object  | Objeto com dados do telefone do representante da empresa  | **[Objeto phone](#objeto-phone)**                                                           |
| `representative_relationship` * | enum | Identificador do vínculo existente entre a empresa e o seu representante | **[Enumeradores representative_relationship](#enumeradores-representative_relationship)

### Objeto address

Este objeto, presente tanto no objeto PF quanto no objeto PJ, é um simples objeto para representar um endereço.

| Campo              | Descrição | Exemplo                                                                                   | Caracteres |
|--------------------|-----------|-------------------------------------------------------------------------------------------|------------|
| `street` *       | string    | Rua do endereço                                                                           | 500        |
| `state` *        | enum      | Estado do endereço (com dois caracteres maiúsculos)                                       | 2          |
| `city` *         | string    | Cidade do endereço                                                                        | 255        |
| `neighborhood` * | string    | Bairro do endereço                                                                        | 500        |
| `number` *       | string    | Número da rua                                                                             | 10         |
| `postal_code` *  | string    | CEP do endereço (http://www.buscacep.correios.com.br/sistemas/buscacep/) (apenas números) | 8          |
| `complement`*     | string    | Complemento do endereço (texto livre)                                                     | 500        |

### Objeto signed_contract 
| Campo | Tipo   | Descrição        | Caracteres    |
|-------|--------|------------------|---------------|
| `document_key` * | uuidv4 | Chave única de identificação do documento do **Termo de Abertura de Conta** ou **Contrato de Conta Escrow**. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36            |
| `signatures` *   | list   | Dados de assinatura do documento enviado. Cada item da lista, corresponde a um assinante do documento.      | [Objeto signatures](#objeto-signatures) |

### Objeto signatures
| Campo | Tipo       | Descrição         | Caracteres        |
|-------|------------|-------------------|-------------------|
| `authenticity` * | object     | Conjunto de dados que evidenciam a assinatura eletrônica realizada pelo assinante. | [Objeto authenticity](#objeto-authenticity) |
| `signer` * | object     | Objeto contendo os dados de um dos assinantes do documento.           | [Objeto signer](#objeto-signer)|
| `authentication_type` * | enumerator | Tipo de assinatura. Sempre será "**opt-in**"| "**opt-in**"                   |

### Objeto authenticity
| Campo | Tipo   | Descrição               | Caracteres |
|-------|--------|-------------------------|------------|
| `timestamp` *            | string | Data e hora do momento da assinatura do documento.                | 27         |
| `facial_recognition_key`* | uuidv4 | Chave única de identificação da foto da selfie do titular da conta.  | 36         |
| `lang`                   | string | Coordenada de longitude da geolocalização do assinante capturada no momento da assinatura.                  | -          |
| `lat`                    | string | Coordenada de latitude da geolocalização do assinante capturada no momento da assinatura.                   | -          |
| `ip_address`             | string | Endereço IP do dispositivo do assinante.     | -          |
| `session_id`*             | string | ID da seção do assinante no momento da assinatura.                | -          |

### Objeto signer
| Campo                 | Tipo   | Descrição                                 | Caracteres                        |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| `name` *            | string | Nome do assinante.                        | -                                 |
| `email` *           | string | Email do assinante.                       | -                                 |
| `phone` *           | object | Objeto com dados do telefone do assinante | **[Objeto phone](#objeto-phone)** |
| `document_number` * | string | CPF do assinante.                         | 11                                |

### Objeto phone 

| Campo | Descrição | Exemplo |  Máx. Caracteres | 
| --- | --- | --- | --- | 
|`country_code` *| string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 | 
| `area_code` *| string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |Número de telefone (apenas números) |  10 |

### Enumeradores person_type
| Enum        | Description       |
|-------------|-------------------|
| `natural` | Pessoa física     |
| `legal`   | Pessoa jurídica   |

### Enumeradores representative_relationship
| Enum        | Description       |
|-------------|-------------------|
| `ceo` | Administrador  |
| `partner` | Sócio/Acionista |
| `attorney` | Procurador|

### Enumeradores document_identification_type
| Enum    | Description                            |
|---------|----------------------------------------|
| `rg`  | RG - Registro Geral                    |
| `cnh` | CNH - Carteira Nacional de Habilitação |

### Enumeradores company_type
| Enum                     | 	Description                                                             |
|--------------------------|--------------------------------------------------------------------------|
| `ltda`                  | Limitada                                                                |
| `sa`	                  | Sociedade Anônima                                                        |
| `micro_enterprise`	    | Micro Empresa                                                            |
| `freelancer`            | Freelancer                                                              |
| `sa_opened`             | Sociedade Anônima de Capital Aberto                                     |
| `sa_closed`	           | Sociedade Anônima de Capital Fechado                                     |
| `se_ltda`               | Sociedade Empresária Limitada                                           |
| `se_cn`                 | Sociedade Empresária em Nome Coletivo                                   |
| `se_cs`                 | Sociedade Empresária em Comandita Simples                               |
| `se_ca`	               | Sociedade Empresária em Comandita por Ações                              |
| `scp`                   | Sociedade em Conta de Participação                                      |
| `ei`	                   | Empresário Individual                                                    |
| `ese`	                 | Estabelecimento, no Brasil, de Sociedade Estrangeira                     |
| `eeab`	                | Estabelecimento, no Brasil, de Empresa Binacional Argentino-Brasileira   |
| `ssp`                  | Sociedade Simples Pura                                                  |
| `ss_ltda`	             | Sociedade Simples Limitada                                               |
| `ss_cn`                | Sociedade Simples em Nome Coletivo                                      |
| `ss_cs`                | Sociedade Simples em Comandita Simples                                  |
| `eireli_ne`            | Empresa Individual de Responsabilidade Limitada (de Natureza Empresária) |
| `eireli_ns`            | Empresa Individual de Responsabilidade Limitada (de Natureza Simples)   |
| `eireli`               | Empresa de Responsabilidade Individual                                  |
| `mei`                  | Micro Empreendedor Individual                                            |
| `me`	                  | Micro Empresa                                                            |
| `cop`	                 | Cooperativa                                                              |
| `private_association`	 | Sociedade Privada                                                        |
| `others`	   | Outros  |

### Enumeradores marital_status
| Enum         | 	Description  |
|--------------|---------------|
| `single`   | Solteiro(a)   |
| `married`  | Casado(a)    |
| `widower`  | Viúvo(a)     |
| `divorced` | Divorciado(a) |
| `separated` | Separado(a) |

## Response

STATUS 201

Response Body

```json
 { "account_key": "78ea0fa6-8ea6-46ff-b66b-d2bc36fc8869" }
```

:::warning Atenção
 O campo `account_request_key` deve ser armazenado e será utilizado para a confirmação da abertura da conta.
:::

### Response Body Params

| Campo | Tipo | Descrição | Caracteres                                      |
|---|---| ---|-------------------------------------------------|
| `account_key` * | string  | Chave de única de identificação da conta| -                                               | - |

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`  | Descrição (eng)<br/>`description` | Descrição(ptbr) <br></br>`translation`|
|---| --- | --- | --- | --- | 
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|

---

# Solicitar reserva de conta

URL: /documentation/baas/account/account_draft_checking

## Request
ENDPOINT /account_request/draft_checking
MÉTODO POST

## Abertura da Conta 

Request Body

```json
{
   "account_owner":{
      "address":{
         "street":"Av. Brigadeiro Faria Lima",
         "state":"SP",
         "city":"São Paulo",
         "neighborhood":"Jardim Paulistano",
         "number":"2391",
         "postal_code":"01452905",
         "complement":"Complemento"
      },
      "birth_date":"1990-05-06",
      "email":"teste@gmail.com",
      "individual_document_number":"99999999999",
      "is_pep":false,
      "mother_name":"Dona Maria Mariane",
      "name":"Nome do Titular da Conta",
      "nationality":"nationality",
      "person_type":"natural",
      "phone":{
         "country_code":"055",
         "area_code":"11",
         "number":"999999999"
      },
      "monthly_income":1000
   }
}
```

### Abertura da Conta

### Request Body Params

| Campo            | Tipo   | Descrição                                                                  |
|------------------|--------|----------------------------------------------------------------------------|
| `account_owner`* | object | Detalhes do titular da conta, incluindo endereço e informações pessoais.   |

### Objeto account_owner

| Campo                         | Tipo    | Descrição                                                      |
|-------------------------------|---------|----------------------------------------------------------------|
| `address`*                    | object  | Endereço do titular da conta.                                  |
| `birth_date`*                 | string  | Data de nascimento do titular (formato "AAAA-MM-DD").          |
| `email`*                      | string  | Email do titular da conta.                                     |
| `individual_document_number`* | string  | CPF do titular (apenas números).                               |
| `is_pep`*                     | boolean | Declaração se a pessoa é PEP.                                  |
| `mother_name`*                | string  | Nome da mãe do titular.                                        |
| `name`*                       | string  | Nome completo do titular.                                      |
| `nationality`                 | string  | Nacionalidade do titular.                                      |
| `person_type`*                | enum    | Tipo de pessoa, deve ser sempre "natural" para pessoa física.  |
| `phone`*                      | object  | Telefone do titular.                                           |
| `monthly_income`              | number  | Renda mensal do titular.                                       |

### Objeto address

| Campo           | Tipo   | Descrição              | Caracteres |
|-----------------|--------|------------------------|------------|
| `street`*       | string | Rua do endereço        | -        |
| `state`*        | enum   | Estado do endereço     | 2          |
| `city`*         | string | Cidade do endereço     | -        |
| `neighborhood`* | string | Bairro do endereço     | -        |
| `number`*       | string | Número da rua          | -         |
| `postal_code`*  | string | CEP do endereço        | -          |
| `complement`    | string | Complemento do endereço| -        |

### Objeto phone

| Campo            | Tipo   | Descrição                |
|------------------|--------|--------------------------|
| `country_code`*  | string | Código DDI do telefone   |
| `area_code`*     | string | Código DDD do telefone   |
| `number`*        | string | Número de telefone       |

### Enumeradores person_type

| Enum    | Descrição    |
|---------|--------------|
| `natural` | Pessoa física |
|`legal`| Pessoa Jurídica |

## Response

STATUS 201

Response Body

```json
{
    "account_number": "1638634",
    "reserved_account_status":"reserved",
    "account_type":  "checking",
    "account_digit": "3",
    "account_key": "b1690f7b-1e82-4f76-a8d3-c326a2b89b67",
    "account_branch": "0001",
    "account_name": "Nome do Proprietário",
    "created_at": "2023-10-07T15:52:24"
}
```

:::warning Atenção
 O campo `account_request_key` deve ser armazenado e será utilizado para a confirmação da abertura da conta.
:::

### Response Body Params

| Campo | Tipo | Descrição | Caracteres                                      |
|---|---| ---|-------------------------------------------------|
| `account_key` * | string  | Chave de única de identificação da conta| -                                               | - |

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`  | Descrição (eng)<br/>`description` | Descrição(ptbr) <br></br>`translation`|
|---| --- | --- | --- | --- | 
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|

---

# Solicitar reserva de conta

URL: /documentation/baas/account/d4bf7f96-69b0-424b-a9d6-0a1bc79629cd

## Request
ENDPOINT /account_request/draft_checking
MÉTODO POST

## Abertura da Conta 

Request Body

```json
{
   "account_owner":{
      "address":{
         "street":"Av. Brigadeiro Faria Lima",
         "state":"SP",
         "city":"São Paulo",
         "neighborhood":"Jardim Paulistano",
         "number":"2391",
         "postal_code":"01452905",
         "complement":"Complemento"
      },
      "birth_date":"1990-05-06",
      "email":"teste@gmail.com",
      "individual_document_number":"99999999999",
      "is_pep":false,
      "mother_name":"Dona Maria Mariane",
      "name":"Nome do Titular da Conta",
      "nationality":"nationality",
      "person_type":"natural",
      "phone":{
         "country_code":"055",
         "area_code":"11",
         "number":"999999999"
      },
      "monthly_income":1000
   }
}
```

### Abertura da Conta

### Request Body Params

| Campo            | Tipo   | Descrição                                                                  |
|------------------|--------|----------------------------------------------------------------------------|
| `account_owner`* | object | Detalhes do titular da conta, incluindo endereço e informações pessoais.   |

### Objeto account_owner

| Campo                         | Tipo    | Descrição                                                      |
|-------------------------------|---------|----------------------------------------------------------------|
| `address`*                    | object  | Endereço do titular da conta.                                  |
| `birth_date`*                 | string  | Data de nascimento do titular (formato "AAAA-MM-DD").          |
| `email`*                      | string  | Email do titular da conta.                                     |
| `individual_document_number`* | string  | CPF do titular (apenas números).                               |
| `is_pep`*                     | boolean | Declaração se a pessoa é PEP.                                  |
| `mother_name`*                | string  | Nome da mãe do titular.                                        |
| `name`*                       | string  | Nome completo do titular.                                      |
| `nationality`                 | string  | Nacionalidade do titular.                                      |
| `person_type`*                | enum    | Tipo de pessoa, deve ser sempre "natural" para pessoa física.  |
| `phone`*                      | object  | Telefone do titular.                                           |
| `monthly_income`              | number  | Renda mensal do titular.                                       |

### Objeto address

| Campo           | Tipo   | Descrição              | Caracteres |
|-----------------|--------|------------------------|------------|
| `street`*       | string | Rua do endereço        | -        |
| `state`*        | enum   | Estado do endereço     | 2          |
| `city`*         | string | Cidade do endereço     | -        |
| `neighborhood`* | string | Bairro do endereço     | -        |
| `number`*       | string | Número da rua          | -         |
| `postal_code`*  | string | CEP do endereço        | -          |
| `complement`    | string | Complemento do endereço| -        |

### Objeto phone

| Campo            | Tipo   | Descrição                |
|------------------|--------|--------------------------|
| `country_code`*  | string | Código DDI do telefone   |
| `area_code`*     | string | Código DDD do telefone   |
| `number`*        | string | Número de telefone       |

### Enumeradores person_type

| Enum    | Descrição    |
|---------|--------------|
| `natural` | Pessoa física |
|`legal`| Pessoa Jurídica |

## Response

STATUS 201

Response Body

```json
{
    "account_number": "1638634",
    "reserved_account_status":"reserved",
    "account_type":  "checking",
    "account_digit": "3",
    "account_key": "b1690f7b-1e82-4f76-a8d3-c326a2b89b67",
    "account_branch": "0001",
    "account_name": "Nome do Proprietário",
    "created_at": "2023-10-07T15:52:24"
}
```

:::warning Atenção
 O campo `account_request_key` deve ser armazenado e será utilizado para a confirmação da abertura da conta.
:::

### Response Body Params

| Campo | Tipo | Descrição | Caracteres                                      |
|---|---| ---|-------------------------------------------------|
| `account_key` * | string  | Chave de única de identificação da conta| -                                               | - |

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`  | Descrição (eng)<br/>`description` | Descrição(ptbr) <br></br>`translation`|
|---| --- | --- | --- | --- | 
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|

---

# Introdução

URL: /documentation/baas/account/introducao

Uma das funcionalidades que podemos oferecer em nossa integração é a possibilidade de gerenciar contas e transferências para contas da QI Tech ou de outras instituições financeiras via API, mas não é só isso, provemos a possibilidade de fazer a ABERTURA de uma conta via API.Seja para você mesmo, ou para terceiros.

Assim como as demais APIs a liberação do serviço deve ser feita junto ao nosso time e as chamadas são autenticadas.

A abertura de conta ocorre em duas etapas obrigatórias. Na primeira etapa, uma requisição POST é enviada com os dados preliminares para realizar a reserva da conta. Após essa solicitação, é executada automaticamente uma consulta ao Banco Central, especificamente ao repositório vinculado ao projeto BC Protege+. Esse sistema permite que pessoas físicas e jurídicas registrem voluntariamente restrições indicando em quais instituições financeiras não desejam que novas contas sejam abertas em seus nomes, como medida de prevenção a fraudes.

Nesse fluxo, o status inicial da reserva é `pending_bacen_validation`.
Se a consulta for aprovada, um webhook do tipo `account_request.status_change` é disparado, atualizando o status para `pending_kyc_analysis`.

Após a aprovação na análise de KYC, um novo webhook `account_request.status_change` é enviado, alterando o status para `pending_additional_data` — etapa que indica a conclusão da análise e a necessidade de envio das informações complementares.

Na segunda etapa, deve ser realizada uma requisição PATCH contendo os dados adicionais necessários para finalizar o processo e oficializar a abertura da conta.

---

# Solicitar Abertura de Conta de Pessoa Física

URL: /documentation/baas/account/reservar_conta_pf

A abertura de conta ocorre em duas etapas obrigatórias. Primeiro, uma requisição POST envia dados preliminares para reservar a conta. Em seguida, um webhook do tipo `account_request.status_change` com o status `pending_additional_data` é disparado. Na segunda etapa, uma requisição PATCH finaliza a abertura, oficializando a conta com as informações complementares. 

## Solicitar Reserva de Conta

## Request
ENDPOINT /account_request/checking
MÉTODO POST

Request Body

```json
{
    "request_control_key": "5ef0f67a-7672-4d00-8a02-faf847157c4b",
    "account_owner": {
        "document_number": "99999999999",
        "email": "email@teste.com",
        "birthdate": "2017-09-16",
        "name": "Titular da Conta",
        "documents": {
            "rg": {
                "ocr_front_key": "2ef0f67a-7672-4d00-8a02-faf847157b4a",
                "ocr_back_key": "1bd0e0a1-c1fa-4f9c-a230-f7a4163864be"
            },
            "cnh": {
                "ocr_key": "7a73be1a-0b66-4c0a-932a-1d1d02efdc4c"
            }
        },
        "face": "d38dd3c0-6f24-43b9-a37a-425d6700620f"
    }
}
```

:::info Mock de CPF/CNPJ
Para simular situações de aprovação, reprovação e analise manual pode ser utilizado o primeiro digito do CPF/CNPJ do owner da conta:

0 à 7 -> Análise Manual

8 -> Reprovado automaticamente no KYC

9 -> Aprovação Automática
:::

### Request Body Params

| Campo | Tipo   | Descrição                                         | Caracteres                                        |
|---|--------|---------------------------------------------------|---------------------------------------------------|
| `account_owner` * | object | Objeto contendo as informações do Titular da Conta | **[Objeto account_owner](#objeto-account_owner)** |
| `request_control_key` * | UUID   | Identificador único por requisição do parceiro  | 36                                                |

### Objeto account_owner
| Campo | Tipo | Descrição | Caracteres |
|--- | --- | --- | --- |
| `document_number` * | string  | CPF do Titular da Conta | 11 |
| `email` * | string  | Email | 11 |
| `birthdate` | string  | Data de nascimento do Titular da Conta(formato YYYY-MM-DD) | 10 |
| `name` * | string  | Nome Completo do Titular da Conta | 50 |
| `documents`* | object  | Documento(s) do titular da conta | **[Objeto documents](#objeto-documents)** |
| `face`*      | uuidv4  | Chave do reconhecimento facial feito junto ao antifraude (`face_recognition_key`) | 36 |

### Objeto documents

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `rg`                           | object      | Chaves OCR (OCR keys) do upload da frente e verso do RG do titular | **[Objeto rg](#objeto-rg)**   |
| `cnh`                          | object      | Chave OCR do upload da CNH do titular                              | **[Objeto cnh](#objeto-cnh)** |
| `cnh_digital`                     | object      | Chave OCR do upload da CNH digital do titular                       | **[Objeto cnh_digital](#objeto-cnh_digital)** |
| `national_registry_of_foreigners` | object   | Chaves OCR (OCR keys) do upload da frente e verso do RNE do titular| **[Objeto national_registry_of_foreigners](#objeto-national_registry_of_foreigners)** |
| `national_migration_registry` | object   | Chaves OCR (OCR keys) do upload da frente e verso do CRNM do titular| **[Objeto national_migration_registry](#objeto-national_migration_registry)** |
| `passport`                     | object      | Chave OCR do upload do passaporte do titular                       | **[Objeto passport](#objeto-passport)** |
| `cin_digital`                     | object      | Chave OCR do upload da Cédula de Identidade Nacional digital do titular                       | **[Objeto cin_digital](#objeto-cin_digital)** |

:::info Informação
As chaves OCR (`ocr_key` ou `ocr_front_key` e `ocr_back_key`) do upload das imagens dos documentos são fornecidos como resposta do upload das imagens no antifraude. A `face_recognition_key` é retornada na resposta do reconhecimento facial.
:::

### Objeto rg

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | Chave OCR do upload da imagem da frente do RG                      | 36                            |
| `ocr_back_key` *               | uuidv4      | Chave OCR do upload da imagem do verso do RG                       | 36                            |

OU

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | Chave OCR do upload da imagem do RG                                | 36                       |

### Objeto cnh

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | Chave OCR do upload da imagem da frente da CNH                     | 36                            |
| `ocr_back_key` *               | uuidv4      | Chave OCR do upload da imagem do verso da CNH                      | 36                            |

OU

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | Chave OCR do upload da imagem da CNH                               | 36                            |

### Objeto cnh_digital

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | Chave OCR do upload da imagem da CNH digital                               | 36                            |

### Objeto national_registry_of_foreigners

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | Chave OCR do upload da imagem da frente do RNE                     | 36                            |
| `ocr_back_key` *               | uuidv4      | Chave OCR do upload da imagem do verso do RNE                      | 36                            |

OU

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | Chave OCR do upload da imagem do RNE                               | 36                            |

### Objeto national_migration_registry

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | Chave OCR do upload da imagem da frente do CRNM                     | 36                            |
| `ocr_back_key` *               | uuidv4      | Chave OCR do upload da imagem do verso do CRNM                      | 36                            |

OU

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | Chave OCR do upload da imagem do CRNM                               | 36                            |

### Objeto passport

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | Chave OCR do upload da imagem do passaporte                               | 36                            |

### Objeto cin_digital

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | Chave OCR do upload da imagem da Cédula de Identidade Nacional digital                               | 36                            |

## Response

STATUS 201

Response Body

```json
{
    "account_info": {
        "account_branch": "0001",
        "account_digit": "0",
        "account_number": "1693580"
    },
    "account_request_key": "f230f1b5-07af-4737-b0e3-8a472304f5e7",
    "account_request_status": "pending_bacen_validation"
}
```

:::info Fluxo Bacen Protege+
A proposta começa com status `pending_bacen_validation`. O sistema realiza uma validação prévia junto ao Bacen Protege+ antes de prosseguir com a análise de KYC. Após aprovação do Bacen, o status será atualizado para `pending_kyc_analysis` automaticamente.
:::

:::warning Atenção
 O campo `account_request_key` deve ser armazenado e será utilizado para a confirmação da abertura da conta.
:::

### Response Body Params

| Campo | Tipo | Descrição | Caracteres|
|---|---| ---|---|
| `account_info` * | object  | Objeto contendo as informações do Titular da Conta |**[Objeto account_info](#objeto-account_info)**  | - |
| `account_request_key` * | string  | Chave de identificação da requisição de criação | - | - |
| `account_request_status` * | string  | Status de KYC | - | - |

### Objeto account_info
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| --- |
| `account_branch` * | string  | Número da Agência | 4 |
| `account_digit` * | string  | Dígito da Conta | 11 |
| `account_number` * | string  | Numero da Conta | 50 |

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`  | Descrição (eng)<br/>`description` | Descrição(ptbr) <br></br>`translation`|
|---| --- | --- | --- | --- | 
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|

---

# Abertura de Conta de Pessoa Jurídica

URL: /documentation/baas/account/reservar_conta_pj

A abertura de conta ocorre em duas etapas obrigatórias. Primeiro, uma requisição POST envia dados preliminares para reservar a conta. Em seguida, um webhook do tipo `account_request.status_change` com o status `pending_additional_data` é disparado. Na segunda etapa, uma requisição PATCH finaliza a abertura, oficializando a conta com as informações complementares. 

## Solicitar Reserva de Conta

## Request
ENDPOINT /account_request/checking
MÉTODO POST

Request Body

```json
{
  
    "account_owner": {
        "company_document_number": "99999999000199",
        "email": "teste@email.com",
        "foundation_date": "2017-09-16",
        "name": "NOME DA EMPRESA"
    },
    "legal_representatives": [
        {
            "birthdate": "1963-07-23",
            "name": "Don Corleone",
            "document_number": "03912394323",
            "email": "teste@gmail.com",
            "documents": {
                "national_registry_of_foreigners": {
                    "ocr_front_key": "0aa8a4ca-5873-49bd-851c-1f2c71a1cc28",
                    "ocr_back_key": "29f6e346-7fae-4dcb-9ea1-2a3e4ef593ea"
                }
            },
            "face": "68da08f1-6cf4-4dce-a297-7b2f09311784"
        },
        {
            "birthdate": "1996-03-10",
            "name": "John Doe",
            "document_number": "39113492093",
            "email": "teste@gmail.com",
            "documents": {
                "cnh": {
                    "ocr_key": "beee557e-9240-4c5b-88f1-42812b195168"
                }
            }
        }
    ]
}
```
:::info Mock de CPF/CNPJ
Para simular situações de aprovação, reprovação e analise manual pode ser utilizado o primeiro digito do CPF/CNPJ do owner da conta:

0 à 6 -> Análise Manual

7 -> Rejeitado pelo bacen protege+

8 -> Reprovado automaticamente no KYC

9 -> Aprovação Automática
:::

### Request Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---|---|
| `account_owner` * | object  | Objeto contendo as informações do Titular da Conta | **[Objeto account_owner](#objeto-account_owner)** |
| `legal_representatives`* | object array | Lista de representantes da conta e seus dados | **[Objeto legal_representative](#objeto-legal_representative)** |

### Objeto account_owner
| Campo | Tipo | Descrição | Caracteres |
|--- | --- | --- | --- |
| `company_document_number` * | string  | CNPJ do Titular da Conta | 50 |
| `email` * | string  | Email | 11 |
| `foundation_date` | string  | Data de fundação da empresa(formato YYYY-MM-DD) | 10 |
| `name` * | string  | Nome Completo do Titular da Conta | 50 |

### Objeto legal_representative

| Campo | Tipo | Descrição | Caracteres |
|--- | --- | --- | --- |
| `document_number` * | string  | CPF do Titular da Conta | 11 |
| `birthdate` | string  | 	Data de nascimento. (formato YYYY-MM-DD) | 10 |
| `name` * | string  | Nome do Titular da Conta | 50 |
| `documents` * | object  | Documento(s) do titular da conta | **[Objeto documents](#objeto-documents)** |
| `face`*      | uuidv4  | Chave do reconhecimento facial feito junto ao antifraude (`face_recognition_key`) | 36 |

### Objeto documents

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `rg`                           | object      | Chaves OCR (OCR keys) do upload da frente e verso do RG do titular | **[Objeto rg](#objeto-rg)**   |
| `cnh`                          | object      | Chave OCR do upload da CNH do titular                              | **[Objeto cnh](#objeto-cnh)** |
| `cnh_digital`                     | object      | Chave OCR do upload da CNH digital do titular                       | **[Objeto cnh_digital](#objeto-cnh_digital)** |
| `national_registry_of_foreigners` | object   | Chaves OCR (OCR keys) do upload da frente e verso do RNE do titular| **[Objeto national_registry_of_foreigners](#objeto-national_registry_of_foreigners)** |
| `national_migration_registry` | object   | Chaves OCR (OCR keys) do upload da frente e verso do CRNM do titular| **[Objeto national_migration_registry](#objeto-national_migration_registry)** |
| `passport`                     | object      | Chave OCR do upload do passaporte do titular                       | **[Objeto passport](#objeto-passport)** |
| `cin_digital`                     | object      | Chave OCR do upload da Cédula de Identidade Nacional digital do titular                       | **[Objeto cin_digital](#objeto-cin_digital)** |

:::info Informação
As chaves OCR (`ocr_key` ou `ocr_front_key` e `ocr_back_key`) do upload das imagens dos documentos são fornecidos como resposta do upload das imagens no antifraude. A `face_recognition_key` é retornada na resposta do reconhecimento facial.
:::

### Objeto rg

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | Chave OCR do upload da imagem da frente do RG                      | 36                            |
| `ocr_back_key` *               | uuidv4      | Chave OCR do upload da imagem do verso do RG                       | 36                            |

OU

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | Chave OCR do upload da imagem do RG                                | 36                            |

### Objeto cnh

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | Chave OCR do upload da imagem da frente da CNH                     | 36                            |
| `ocr_back_key` *               | uuidv4      | Chave OCR do upload da imagem do verso da CNH                      | 36                            |

OU

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | Chave OCR do upload da imagem da CNH                               | 36                            |

### Objeto cnh_digital

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | Chave OCR do upload da imagem da CNH digital                               | 36                            |

### Objeto national_registry_of_foreigners

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | Chave OCR do upload da imagem da frente do RNE                     | 36                            |
| `ocr_back_key` *               | uuidv4      | Chave OCR do upload da imagem do verso do RNE                      | 36                            |

OU

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | Chave OCR do upload da imagem do RNE                               | 36                            |

### Objeto national_migration_registry

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | Chave OCR do upload da imagem da frente do CRNM                     | 36                            |
| `ocr_back_key` *               | uuidv4      | Chave OCR do upload da imagem do verso do CRNM                      | 36                            |

OU

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | Chave OCR do upload da imagem do CRNM                               | 36                            |

### Objeto passport

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | Chave OCR do upload da imagem do passaporte                               | 36                            |

### Objeto cin_digital

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | Chave OCR do upload da imagem da Cédula de Identidade Nacional digital                               | 36                            |

## Response

STATUS 201

Response Body

```json
{
    "account_info": {
        "account_branch": "0001",
        "account_digit": "0",
        "account_number": "1693580"
    },
    "account_request_key": "f230f1b5-07af-4737-b0e3-8a472304f5e7",
    "account_request_status": "pending_bacen_validation"
}
```

:::info Fluxo Bacen Protege+
A proposta começa com status `pending_bacen_validation`. O sistema realiza uma validação prévia junto ao Bacen Protege+ antes de prosseguir com a análise de KYC. Após aprovação do Bacen, o status será atualizado para `pending_kyc_analysis` automaticamente.
:::

:::warning Atenção
 O campo `account_request_key` deve ser armazenado e será utilizado para a confirmação da abertura da conta.
:::

### Response Body Params

| Campo | Tipo | Descrição | Caracteres|
|---|---| ---|---|
| `account_info` * | object  | Objeto contendo as informações do Titular da Conta |**[Objeto account_info](#objeto-account_info)**  | - |
| `account_request_key` * | string  | Chave de identificação da requisição de criação | - | - |
| `account_request_status` * | string  | Status de KYC | - | - |

### Objeto account_info
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| --- |
| `account_branch` * | string  | Número da Agência | 4 |
| `account_digit` * | string  | Email | 11 |
| `account_number` * | string  | Nome Completo do Titular da Conta | 50 |

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`  | Descrição (eng)<br/>`description` | Descrição(ptbr) <br></br>`translation`|
|---| --- | --- | --- | --- | 
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|

---

# Webhooks de abertura de conta

URL: /documentation/baas/account/webhooks

Após a solicitação de reserva de conta, o status inicial é `pending_bacen_validation`. Se aprovada, o status da reserva é atualizado para `pending_kyc_analysis`. Em seguida, ao ser aprovado em KYC, o status se torna `pending_additional_data`.

Para os status `pending_kyc_analysis`, `pending_additional_data` e `rejected`, o webhook do tipo `account_request.status_change` é enviado, sendo esse evento essencial para controle das próximas ações necessárias à confirmação da abertura de conta.

O número de conta será reservado no momento da solicitação de reserva de abertura, porém neste momento **a conta ainda não estará aberta**. Somente após a conclusão da análise de KYC da QI Tech e posterior confirmação da solicitação pelo parceiro, a conta estará aberta.

### Enumeradores account_request_status
| Enum                        | Description                         |
|-----------------------------|-------------------------------------|
| **pending_kyc_analysis**    | Pendente de aprovação KYC           |
| **pending_additional_data** | Pendente de informações adicionais  |
| **rejected**                | Abertura rejeitada                  |

Quando o status for `rejected`, o webhook inclui o campo `rejection_reason` no corpo raiz da mensagem. O valor desse campo é livre e pode variar conforme a razão identificada, seja proveniente da análise de KYC ou do Bacen Protege+.

### Webhook de pendência de análise de KYC

WEBHOOK_TYPE account_request.status_change
STATUS pending_kyc_analysis

Webhook Body

```json
{
    "data": {
        "account_info": {
            "account_digit": "3",
            "account_branch": "0001",
            "account_number": "1638634"
        },
        "account_request_key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
        "status": "pending_kyc_analysis"
    },
    "event_datetime": "2022-09-02 22:39:39",
    "key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
    "status": "pending_kyc_analysis",
    "webhook_type": "account_request.status_change"
}
```

### Webhook de pendência de confirmação de conta

WEBHOOK_TYPE account_request.status_change
STATUS pending_additional_data

Webhook Body

```json
{
    "key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
    "data": {
        "account_info": {
            "account_digit": "3",
            "account_branch": "0001",
            "account_number": "1638634"
        },
        "account_request_key": "dc575950-dcce-48e1-99a6-5fb0ada63d86"
    },
    "event_datetime": "2022-09-02 22:39:39",
    "status": "pending_additional_data",
    "webhook_type": "account_request.status_change"
}
```

### Webhook de abertura rejeitada (KYC)

WEBHOOK_TYPE account_request.status_change
STATUS rejected

Webhook Body

```json
{
    "data": {
        "account_info": {
            "account_digit": "3",
            "account_branch": "0001",
            "account_number": "1638634"
        },
        "account_request_key": "dc575950-dcce-48e1-99a6-5fb0ada63d86"
    },
    "event_datetime": "2022-09-02T22:39:39",
    "key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
    "status": "rejected",
    "webhook_type": "account_request.status_change",
    "rejection_reason": "UNSC"
}
```

### Webhook de abertura rejeitada (Bacen Protege+)

WEBHOOK_TYPE account_request.status_change
STATUS rejected

Webhook Body

```json
{
    "data": {
        "account_info": {
            "account_digit": "3",
            "account_branch": "0001",
            "account_number": "1638634"
        },
        "account_request_key": "dc575950-dcce-48e1-99a6-5fb0ada63d86"
    },
    "event_datetime": "2022-09-02T22:39:39",
    "key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
    "status": "rejected",
    "webhook_type": "account_request.status_change",
    "rejection_reason": "Rejeitado devido ao Bacen Protege+"
}
```

---

# Catálogo de Erros - Banking-as-a-Service

URL: /documentation/baas/catalogo_de_erros_baas

Abaixo estão listados todos os erros que podem ser retornados pelas APIs do Banking-as-a-Service.
Cada código de erro possui um identificador único que pode ser usado como referência.

:::info
O serviço pix-keys-api utiliza apenas erros compartilhados (QIT) listados na seção de Erros Comuns abaixo.
:::

## Erros Comuns

Erros compartilhados entre todas as APIs da plataforma.

| Código | HTTP | Mensagem |
|-|-|-|
| <a id="QIT000001"></a>`QIT000001` | 400 | **Schema Validator Error**<br/>Payload Inválido<br/><small>{description}</small> |
| <a id="QIT000002"></a>`QIT000002` | 403 | **Permission Validator Error**<br/>Request must be internal |
| <a id="QIT000003"></a>`QIT000003` | 403 | **Permission Validator Error**<br/>O agente não tem funções suficientes.<br/><small>The agent does not have enough roles.</small> |
| <a id="QIT000004"></a>`QIT000004` | 403 | **Permission Validator Error**<br/>Agente selecionado e person_key são diferentes<br/><small>Selected agent and person_key are different</small> |
| <a id="QIT000005"></a>`QIT000005` | 403 | **Permission Validator Error**<br/>O agente selecionado não é dono do item.<br/><small>Selected agent do not own this item.</small> |
| <a id="QIT000006"></a>`QIT000006` | 403 | **Permission Validator Error**<br/>Agente selecionado não é dono deste item e não tem funções suficientes.<br/><small>Selected agent do not own this item and has not enough roles.</small> |
| <a id="QIT000007"></a>`QIT000007` | - | **External API Error (Rest Connector)**<br/>{translation}<br/><small>{description}</small> |
| <a id="QIT000010"></a>`QIT000010` | 400 | **Search Params Error**<br/>Valor inválido para parâmetros página ou tamanho de página<br/><small>Invalid integer value for page or size querystring parameters</small> |
| <a id="QIT000400"></a>`QIT000400` | 400 | **Bad Request**<br/>O servidor não pode ou não processará a requisição devido a um erro do cliente (por exemplo, corpo da requisição inválido, tamanho muito grande, formatação da mensagem inválida ou rota inválida)<br/><small>The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, size too large, invalid request message framing, or deceptive request routing)</small> |
| <a id="QIT000404"></a>`QIT000404` | 404 | **Not Found**<br/>O resource solicitado não pôde ser encontrado, mas pode estar disponível no futuro. Requests subsequentes do cliente são permitidos<br/><small>The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible</small> |
| <a id="QIT000500"></a>`QIT000500` | 500 | **Internal Error**<br/>Um erro interno aconteceu e está sendo investigado.<br/><small>An internal error has occurred and its being investigated.</small> |
| <a id="QIT000753"></a>`QIT000753` | 500 | **Internal Error**<br/>Um erro interno aconteceu e está sendo investigado.<br/><small>An internal error has occurred and its being investigated.</small> |

## Erros Específicos

### ACC — Contas

224 erros

| Código | HTTP | Mensagem |
|-|-|-|
| <a id="ACC000001"></a>`ACC000001` | 400 | **Bad Request**<br/>Use POST /account |
| <a id="ACC000002"></a>`ACC000002` | 409 | **Reserved Account Error**<br/>Conta reservada já foi criada<br/><small>Reserved account already created</small> |
| <a id="ACC000003"></a>`ACC000003` | 409 | **Reserved Account Error**<br/>Conta reservada já foi liberada<br/><small>Reserved account already released</small> |
| <a id="ACC000004"></a>`ACC000004` | 400 | **Bad Request**<br/>Use PATCH /account/{account_key} |
| <a id="ACC000005"></a>`ACC000005` | 403 | **Unauthorized Agent**<br/>Este agente não pode realizar esta ação<br/><small>This agent can not perform this action</small> |
| <a id="ACC000006"></a>`ACC000006` | 404 | **Not Found**<br/>Conta não encontrada para a seguinte chave {account_key}<br/><small>Account not found for the given key {account_key}</small> |
| <a id="ACC000007"></a>`ACC000007` | 400 | **Bad Request**<br/>SELECTED_AGENT ou person_key devem ser fornecidos<br/><small>A SELECTED_AGENT or person_key must be provided</small> |
| <a id="ACC000008"></a>`ACC000008` | 404 | **Not Found**<br/>Conta não encontrada para os parâmetros fornecidos.<br/><small>Account not found for the given parameters.</small> |
| <a id="ACC000009"></a>`ACC000009` | 423 | **Invalid Account**<br/>Contas bloqueadas ou fechadas não podem realizar esta ação.<br/><small>Blocked or closed accounts can not perform this action</small> |
| <a id="ACC000010"></a>`ACC000010` | 404 | **Owner Person Not Found**<br/>Dono não encontrada para a person_key {person_key}.<br/><small>Owner person_key {person_key} not found.</small> |
| <a id="ACC000011"></a>`ACC000011` | 423 | **Invalid Account**<br/>Contas fechadas não podem realizar esta ação.<br/><small>Closed accounts can not perform this action.</small> |
| <a id="ACC000012"></a>`ACC000012` | 400 | **Bad Request**<br/>Chave da conta (account_key) é obrigatória<br/><small>Account Key is obligatory</small> |
| <a id="ACC000013"></a>`ACC000013` | 400 | **Bad Request**<br/>Use /account/{account_key}/beneficiary |
| <a id="ACC000014"></a>`ACC000014` | 400 | **Bad Request**<br/>Use /account/{account_key}/beneficiary?document_number={document_number} ou /account/{account_key}/beneficiary/{beneficiary_key}<br/><small>Use /account/{account_key}/beneficiary?document_number={document_number} or /account/{account_key}/beneficiary/{beneficiary_key}</small> |
| <a id="ACC000015"></a>`ACC000015` | 400 | **Bad Request**<br/>Parâmetro is_activated é obrigatório<br/><small>is_activated is needed in payload</small> |
| <a id="ACC000016"></a>`ACC000016` | 404 | **Not Found**<br/>Contas do beneficiário não encontradas para os parâmetros fornecidos<br/><small>Beneficiary accounts not found for the given parameters.</small> |
| <a id="ACC000017"></a>`ACC000017` | 404 | **Not Found**<br/>Conta destino não encontrada para os parâmetros fornecidos<br/><small>Target account not found for the given key</small> |
| <a id="ACC000018"></a>`ACC000018` | 402 | **Block Balance Error**<br/>Não é possível blockear uma quantidade maior do que o saldo na conta<br/><small>Impossible to block an amount greater than account balance</small> |
| <a id="ACC000019"></a>`ACC000019` | 402 | **Block Balance Error**<br/>Saldo da conta a ser bloqueada não pode ser negativo.<br/><small>Account blocked balance cannot be negative.</small> |
| <a id="ACC000020"></a>`ACC000020` | 402 | **Block Balance Error**<br/>Saldo da conta a ser bloqueada não pode ser 0 ou nulo.<br/><small>Account blocked balance cannot be 0 or null.</small> |
| <a id="ACC000021"></a>`ACC000021` | 422 | **Account Status Error**<br/>Status da conta não pode realizar esta ação (source_status: {source_account_enumerator}, target_status: {target_account_enumerator})<br/><small>Account status can not perform this action (source_status: {source_account_enumerator}, target_status: {target_account_enumerator})</small> |
| <a id="ACC000022"></a>`ACC000022` | 422 | **Unprocessable Entity**<br/>Transação já realizada<br/><small>Transaction already performed</small> |
| <a id="ACC000023"></a>`ACC000023` | 422 | **Unprocessable Entity**<br/>Transação não pode ser realizada antes da data de transação (transaction_date)<br/><small>Transaction cannot be performed before the transaction_date</small> |
| <a id="ACC000024"></a>`ACC000024` | 404 | **Not Found**<br/>Transação não encontrada<br/><small>Transaction not found</small> |
| <a id="ACC000025"></a>`ACC000025` | 422 | **Invalid Account**<br/>Conta inválida.<br/><small>Invalid account.</small> |
| <a id="ACC000026"></a>`ACC000026` | 422 | **Account Error**<br/>Transações devem ser realizadas utilizando uma conta do sistema.<br/><small>Transaction must be performed using a system account.</small> |
| <a id="ACC000027"></a>`ACC000027` | 402 | **Account Balance Error**<br/>Saldo da conta não pode ser negativo após a transação.<br/><small>Account balance must not be negative after the transaction.</small> |
| <a id="ACC000028"></a>`ACC000028` | 402 | **Account Balance Error**<br/>Transação não pode ser feita pois saldo em conta bloqueado.<br/><small>Transaction cannot be made due to already blocked balance.</small> |
| <a id="ACC000029"></a>`ACC000029` | 400 | **Bad Request**<br/>Request não possui body.<br/><small>No body provided</small> |
| <a id="ACC000030"></a>`ACC000030` | 400 | **Bad Request**<br/>Use POST /reserved_account |
| <a id="ACC000031"></a>`ACC000031` | 400 | **Bad Request**<br/>Use GET /reserved_account/{reserved_account_key} |
| <a id="ACC000032"></a>`ACC000032` | 404 | **Not Found**<br/>Conta reservada não encontrada<br/><small>Reserved account not found.</small> |
| <a id="ACC000033"></a>`ACC000033` | 404 | **Not Found**<br/>Transação não encontrada para a chave fornecida<br/><small>There is no transaction for the given key</small> |
| <a id="ACC000034"></a>`ACC000034` | 422 | **Account Error**<br/>Transações não devem ser realizadas utilizando uma conta do sistema.<br/><small>Transaction cannot be performed using a system account.</small> |
| <a id="ACC000035"></a>`ACC000035` | 400 | **Bad Request**<br/>É necessário o parâmetro STATUS na request<br/><small>Status parameter is required</small> |
| <a id="ACC000036"></a>`ACC000036` | 400 | **Bad Request**<br/>Parâmetros incorretos<br/><small>Wrong parameters used on the request</small> |
| <a id="ACC000037"></a>`ACC000037` | 400 | **Bad Request**<br/>Parâmetro incorreto: {param}<br/><small>Wrong parameter used on the request: {param}</small> |
| <a id="ACC000038"></a>`ACC000038` | 400 | **Transaction Request Error**<br/>Necessária a chave da Solicitação de transação<br/><small>Missing transaction request key</small> |
| <a id="ACC000039"></a>`ACC000039` | 400 | **Transaction Request Error**<br/>Solicitação de transação não encontrada<br/><small>Transaction request not found</small> |
| <a id="ACC000040"></a>`ACC000040` | 400 | **Transaction Request Error**<br/>Solicitação de transação {transaction_request_key} já foi aprovada<br/><small>Transaction request {transaction_request_key} already approved</small> |
| <a id="ACC000041"></a>`ACC000041` | 400 | **Transaction Request Error**<br/>Solicitação de transação {transaction_request_key} já foi recusada<br/><small>Transaction {transaction_request_key} request already rejected</small> |
| <a id="ACC000042"></a>`ACC000042` | 400 | **Transaction Request Error**<br/>O usuário já aprovou a solicitação {transaction_request_key}<br/><small>User has already approved the {transaction_request_key} request</small> |
| <a id="ACC000043"></a>`ACC000043` | 400 | **Transaction Request Error**<br/>O usuário já rejeitou a solicitação {transaction_request_key}<br/><small>User has already rejected the {transaction_request_key} request</small> |
| <a id="ACC000044"></a>`ACC000044` | 423 | **Transaction Request Error**<br/>Conta destino fechada não pode receber transferências<br/><small>Closed target can not receive transfer</small> |
| <a id="ACC000045"></a>`ACC000045` | 400 | **Bad Request**<br/>Request não possui os parâmetros obrigatórios de tamanho e número de página.<br/><small>Missing page or size mandatory parameters on request.</small> |
| <a id="ACC000046"></a>`ACC000046` | 404 | **Not Found**<br/>Nenhum resultado encontrado para a schedule_key fornecida<br/><small>No match for given schedule_key</small> |
| <a id="ACC000047"></a>`ACC000047` | 400 | **Bad Request**<br/>Data de agendamento não pode ser para o mesmo dia após as 17:00, nem ser finais de semana, feriados ou datas passadas.<br/><small>Scheduling time cannot occur for the same day after 17:00, nor be on a weekend, holiday or on a past date.</small> |
| <a id="ACC000048"></a>`ACC000048` | 402 | **Balance Error**<br/>Saldo insuficiente para esta transação<br/><small>Not enough balance to perform transaction</small> |
| <a id="ACC000049"></a>`ACC000049` | 400 | **Credential Error**<br/>Esta conta não possui credenciais de requester<br/><small>This account doesn't have requester credentials</small> |
| <a id="ACC000050"></a>`ACC000050` | 400 | **Bad Request**<br/>COnta de destino inválida, conta de destino não cadastrada para essa conta escrow<br/><small>Invalid destination, destination account not permitted for this escrow account</small> |
| <a id="ACC000051"></a>`ACC000051` | 400 | **Destination Error**<br/>Destino não é uma conta interna<br/><small>Destination isn't a internal account</small> |
| <a id="ACC000052"></a>`ACC000052` | 400 | **Bad Request**<br/>Tipo de transação inválido<br/><small>Invalid Transaction Type.</small> |
| <a id="ACC000053"></a>`ACC000053` | 400 | **Bad Request**<br/>Tipo de operação inválida para este tipo de conta<br/><small>Invalid operation for this account type</small> |
| <a id="ACC000054"></a>`ACC000054` | 400 | **Bad Request**<br/>{rule_enum} não encontrada dentro das regras registradas.<br/><small>{rule_enum} was not found among registered rules.</small> |
| <a id="ACC000055"></a>`ACC000055` | 400 | **Bad Request**<br/>Incompatibilidade entre a configuração de transferência automática e o modelo da respectiva regra: {message}<br/><small>Mismatch between automatic transfer configuration and respective rule template: {message}</small> |
| <a id="ACC000056"></a>`ACC000056` | 422 | **Unprocessable Entity**<br/>A conta está vazia.<br/><small>Account is empty.</small> |
| <a id="ACC000057"></a>`ACC000057` | 400 | **Bad Request**<br/>Data de movimentação não pode ser uma data passada<br/><small>Movement date cannot be a past date</small> |
| <a id="ACC000058"></a>`ACC000058` | 400 | **Bad Request**<br/>Data de movimentação precisa ser um dia util<br/><small>Movement date has to be a workday</small> |
| <a id="ACC000059"></a>`ACC000059` | 400 | **Bad Request**<br/>Data de movimentação precisa ser hoje para o tipo: {movement_type}<br/><small>Movement date has to be today for movement type: {movement_type}</small> |
| <a id="ACC000060"></a>`ACC000060` | 400 | **Bad Request**<br/>Data de movimentação não pode ser hoje para o tipo: {movement_type}<br/><small>Movement date cannot be today for movement type: {movement_type}</small> |
| <a id="ACC000061"></a>`ACC000061` | 423 | **Locked**<br/>Pagamento de boleto está disponível entre {opening_time} e {closing_time}<br/><small>Bank slip payment is available from {opening_time} to {closing_time}</small> |
| <a id="ACC000062"></a>`ACC000062` | 423 | **Locked**<br/>TED está disponível entre {opening_time} e {closing_time}<br/><small>TED is available from {opening_time} to {closing_time}</small> |
| <a id="ACC000063"></a>`ACC000063` | 404 | **Not Found**<br/>Schema de movimentação não pode ser encontrado para o tipo: {movement_type}<br/><small>Movement schema not found for {movement_type} movement type</small> |
| <a id="ACC000064"></a>`ACC000064` | 400 | **Bad Request**<br/>{product_type} {role_type} não encontrado para a person_key {person_key}<br/><small>No {product_type} {role_type} found for owner_person_key {person_key}</small> |
| <a id="ACC000065"></a>`ACC000065` | 400 | **Bad Request**<br/>Feedback do aprovador precisa ser booleano<br/><small>Approver feedback must be a boolean</small> |
| <a id="ACC000066"></a>`ACC000066` | 404 | **Not Found**<br/>Pedidos de movimentação não encontrados para as chaves informadas<br/><small>Movement requests not found for given keys</small> |
| <a id="ACC000067"></a>`ACC000067` | 409 | **Conflict**<br/>Um pedido de movimentação com status {movement_status} ja existe para a linha digitavel<br/><small>A movement request with status {movement_status} already exists for the informed digitable line</small> |
| <a id="ACC000068"></a>`ACC000068` | 403 | **Unauthorized**<br/>Apenas usuários master podem mudar a habilitação da conta para o webhook<br/><small>Only master users can change account webhook enablement</small> |
| <a id="ACC000069"></a>`ACC000069` | 400 | **Bad Request**<br/>Use POST /account/{account_key}/webhook_enabled |
| <a id="ACC000070"></a>`ACC000070` | 400 | **Bad Request**<br/>Use POST /monthly_account_fee |
| <a id="ACC000071"></a>`ACC000071` | 400 | **Bad Request**<br/>Use PATCH /monthly_account_fee/{account_key} |
| <a id="ACC000072"></a>`ACC000072` | 404 | **Not Found**<br/>Recibo de transação não encontrado para key {transaction_key}<br/><small>Transaction Receipt Not Found for key {transaction_key}</small> |
| <a id="ACC000073"></a>`ACC000073` | 400 | **Bad Request**<br/>Saldo remanescente mínimo não pode ser menor que 0<br/><small>Remaining balance must not be less than 0</small> |
| <a id="ACC000074"></a>`ACC000074` | 423 | **Locked**<br/>Pagamento de boleto igual ou acima de R${amount} está disponível entre {opening_time} e {closing_time}<br/><small>Bank slip payment greater than or equal to R${amount} is available from {opening_time} to {closing_time}</small> |
| <a id="ACC000075"></a>`ACC000075` | 403 | **Unauthorized**<br/>Usuário não tem permissão para requisitar essa transação<br/><small>User does not have permission to request this transaction</small> |
| <a id="ACC000076"></a>`ACC000076` | 400 | **Bad Request**<br/>Cron inválida para cadastro de transferência automática<br/><small>Invalid cron for automatic transfer</small> |
| <a id="ACC000077"></a>`ACC000077` | 400 | **Bad Request**<br/>Número da conta e da agência devem ser inteiros.<br/><small>Account number and branch must be integers.</small> |
| <a id="ACC000078"></a>`ACC000078` | 404 | **Not Found**<br/>Conta destino interna não encontrada<br/><small>Destination account internal not found</small> |
| <a id="ACC000079"></a>`ACC000079` | 403 | **Unauthorized**<br/>Usuário não tem permissão para aprovar ou rejeitar um pedido de transação<br/><small>User does not have permission to approve or reject this movement request</small> |
| <a id="ACC000080"></a>`ACC000080` | 403 | **Bad Request**<br/>Taxa de configuração não pode ser negativa<br/><small>Setup Fee can not be negative</small> |
| <a id="ACC000081"></a>`ACC000081` | 404 | **Not Found**<br/>Transação não encontrada<br/><small>Transaction Schedule not found</small> |
| <a id="ACC000082"></a>`ACC000082` | 423 | **Invalid Account**<br/>Contas fechadas não podem realizar esta ação. {account_key}<br/><small>Closed accounts can not perform this action {account_key}.</small> |
| <a id="ACC000083"></a>`ACC000083` | 400 | **Source Account not found**<br/>A conta de origem identificada no CNAB não foi encontrada. Conta de origem {account_number}<br/><small>The source account from CNAB was not found. Source Account number: {account_number}</small> |
| <a id="ACC000084"></a>`ACC000084` | 400 | **Payment date in the past**<br/>Foi encontrada uma transação que está com a data de pagamento no passado. {payment_date}<br/><small>It was found a transaction with payment date in the past. Payment date from transaction: {payment_date}</small> |
| <a id="ACC000085"></a>`ACC000085` | 400 | **Bad Request - CNAB ERROR**<br/>Arquivo vazio ou corrompido.<br/><small>Empty or corrupted file.</small> |
| <a id="ACC000085"></a>`ACC000085` | 400 | **Bad Request - CNAB ERROR**<br/>Versão de CNAB não suportada.<br/><small>CNAB version not supported yet.</small> |
| <a id="ACC000086"></a>`ACC000086` | 400 | **Bad Request - CNAB ERROR**<br/>Não foi possível identificar o tipo de arquivo CNAB enviado.<br/><small>Could not find the CNAB type.</small> |
| <a id="ACC000088"></a>`ACC000088` | 400 | **Bad Request - CNAB ERROR**<br/>Registro com tamanho incorreto.<br/><small>Registry line size incorrect.</small> |
| <a id="ACC000089"></a>`ACC000089` | 400 | **Bad Request - CNAB ERROR**<br/>Não foi possível determinar o código do banco operador detalhess: {details_br} cnab_filename: {cnab_filename} cnab_line: {cnab_line} cnab_inline_start_position: {cnab_inline_start_position} cnab_inline_end_position: {cnab_inline_end_position} cnab_inline_field: {cnab_inline_field} cnab_inline_field_type: {cnab_inline_field_type} cnab_inline_field_value: {cnab_inline_field_value}<br/><small>Could not determine Bank Code.</small> |
| <a id="ACC000090"></a>`ACC000090` | 400 | **Bad Request - CNAB ERROR**<br/>Não foi possível determinar a versão do CNAB.<br/><small>Could not determine CNAB version.</small> |
| <a id="ACC000091"></a>`ACC000091` | 400 | **Bad Request - CNAB ERROR**<br/>Não foi possível determinar o tipo do CNAB (Remessa / Retorno).<br/><small>Could not determine CNAB type (Remittance / Discharge).</small> |
| <a id="ACC000092"></a>`ACC000092` | 400 | **Bad Request - CNAB ERROR**<br/>Não foi possível ler o campo.<br/><small>Could not set the field.</small> |
| <a id="ACC000093"></a>`ACC000093` | 400 | **Bad Request - CNAB ERROR**<br/>Número máximo de dígitos excedido para o campo.<br/><small>Max field size exceeded.</small> |
| <a id="ACC000094"></a>`ACC000094` | 400 | **Bad Request - CNAB ERROR**<br/>Value type incorrect.<br/><small>Tipo de valor incorreto.</small> |
| <a id="ACC000095"></a>`ACC000095` | 400 | **Bad Request - CNAB ERROR**<br/>Número de casas decimais incorreto.<br/><small>Wrong number of decimal places.</small> |
| <a id="ACC000096"></a>`ACC000096` | 400 | **Bad Request - CNAB ERROR**<br/>Registro Header colocado na posição incorreta.<br/><small>Wrong header record position in file.</small> |
| <a id="ACC000097"></a>`ACC000097` | 400 | **Bad Request - CNAB ERROR**<br/>Sequência de registros incorreta no arquivo.<br/><small>Wrong cnab record sequence.</small> |
| <a id="ACC000098"></a>`ACC000098` | 400 | **Bad Request - CNAB ERROR**<br/>Tipo de registro não suportado.<br/><small>Record type not supported.</small> |
| <a id="ACC000099"></a>`ACC000099` | 400 | **Bad Request - CNAB ERROR**<br/>Não foi possível determinar o nome do banco.<br/><small>Could not determine bank name.</small> |
| <a id="ACC000100"></a>`ACC000100` | 400 | **Bad Request**<br/>Não foi possível ler o CNAB devido presença de caracteres especiais na linha {line} e posição {position} do arquivo.<br/><small>Unable to read CNAB file. Check file data for special characters at line {line} and position {position}</small> |
| <a id="ACC000101"></a>`ACC000101` | 422 | **Unprocessable Entity**<br/>O campo Identificação da Empresa Beneficiária {beneficiary_code} nas linhas de registro (posições 021 a 037) é diferente da identificação da empresa beneficiária {company_code} no cabeçalho (posições 027 a 046).<br/><small>The field Identification of the Beneficiary Institution {beneficiary_code} on the registration lines (positions 021 to 037) is different from the beneficiary company identification {company_code} in the header (positions 027 to 046).</small> |
| <a id="ACC000102"></a>`ACC000102` | 400 | **Invalid FileName**<br/>Nome de arquivo inválido ({cnab_filename}). Favor não utilizar caracteres especiais como '!,@,(,),$' .<br/><small>Invalid filename ({cnab_filename}). Please do not use specials characters like '!,@,(,),$' .</small> |
| <a id="ACC000103"></a>`ACC000103` | 404 | **Not Found**<br/>Não foi possível encontrar a instituicao financeira com o codigo bancario {code_number}<br/><small>Could not find financial institution with bank code: {code_number}</small> |
| <a id="ACC000104"></a>`ACC000104` | 400 | **Bad Request**<br/>Porcentagem total da divisão é maior que 100%<br/><small>Total Percentage Split is greater than 100%</small> |
| <a id="ACC000105"></a>`ACC000105` | 400 | **Bad Request**<br/>Erros nas transações em lote<br/><small>Errors in batch transactions</small> |
| <a id="ACC000106"></a>`ACC000106` | 403 | **Forbidden**<br/>Conta {account_key} está fechada e não pode realizar transação<br/><small>Account {account_key} is closed and cannot perform movement request</small> |
| <a id="ACC000107"></a>`ACC000107` | 400 | **Bad Request**<br/>Não foi informado a conta do webhook a ser alterado<br/><small>The account webhook to be changed was not informed</small> |
| <a id="ACC000108"></a>`ACC000108` | 404 | **Not Found**<br/>Nenhum resultado encontrado para a schedule_category informada<br/><small>No match for given schedule_category</small> |
| <a id="ACC000109"></a>`ACC000109` | 400 | **Bad Request**<br/>A data de agendamento escolhida não pode estar fora do intervalo de 60 dias futuros a partir de hoje.<br/><small>The chosen scheduled movement date cannot happen outside a limit of 60 days from now.</small> |
| <a id="ACC000110"></a>`ACC000110` | 400 | **Bad Request**<br/>Solicitar uma devolução agendada de PIX não é uma operação permitida.<br/><small>Requesting a scheduled chargeback is not an allowed operation.</small> |
| <a id="ACC000111"></a>`ACC000111` | 400 | **Bad Request**<br/>Campo {field} necessário para o pix<br/><small>Pix field {field} required</small> |
| <a id="ACC000112"></a>`ACC000112` | 404 | **Not Found**<br/>A automatic_transfer não foi encontrada com os parâmetros fornecidos<br/><small>An automatic_transfer not found for the given parameters</small> |
| <a id="ACC000113"></a>`ACC000113` | 400 | **Bad Request**<br/>Não é possível realizar uma operação com um valor de transação nulo.<br/><small>Unable to perform a transaction with a null transaction amount</small> |
| <a id="ACC000114"></a>`ACC000114` | 400 | **Bad Request**<br/>Não é possível realizar uma operação com um valor que tenha mais de duas casas decimais.<br/><small>Unable to perform a transaction with a transaction amount with more than 2 decimal places</small> |
| <a id="ACC000115"></a>`ACC000115` | 400 | **Bad Request**<br/>Impossível deletar a ultima permissão de uma pessoa.<br/><small>Unable to deactivate the last credential from a person.</small> |
| <a id="ACC000116"></a>`ACC000116` | 404 | **Not Found**<br/>Tipo de conta ted não encontrado para tipo: {type}.<br/><small>Ted account type not found for type: {type}.</small> |
| <a id="ACC000117"></a>`ACC000117` | 409 | **Conflict**<br/>Já existe um destino de conta com os mesmos dados.<br/><small>There's already an account destination with the same data.</small> |
| <a id="ACC000118"></a>`ACC000118` | 404 | **Not Found**<br/>Status da conta de destino não foi encontrado.<br/><small>Account destination status not found.</small> |
| <a id="ACC000119"></a>`ACC000119` | 400 | **Bad Request**<br/>O número do documento de destino da conta deve ser o mesmo do proprietário da conta.<br/><small>Account destination document number must be the same of the account owner.</small> |
| <a id="ACC000120"></a>`ACC000120` | 400 | **Bad Request**<br/>valor pré fixado é superior ao valor disponível.<br/><small>prefixed amount is greater than available amount.</small> |
| <a id="ACC000121"></a>`ACC000121` | 400 | **Bad Request**<br/>Formato da data está invalido. Este deve ser YYYY-mm-dd<br/><small>Date format is invalid.It must be YYYY-mm-dd</small> |
| <a id="ACC000122"></a>`ACC000122` | 400 | **Bad Request**<br/>Campo nome não pode ter mais de 50 caracteres<br/><small>Name field cannot be longer than 50 characters</small> |
| <a id="ACC000123"></a>`ACC000123` | 400 | **Bad Request**<br/>Saldo remanescente nao pode ser maior que 0.<br/><small>Account balance cannot be greater than 0.</small> |
| <a id="ACC000124"></a>`ACC000124` | 400 | **Bad Request**<br/>Não é possível realizar essa ação. Há transações futuras que não foram pagas.<br/><small>Can't perform this action. There'are few unpaid fees</small> |
| <a id="ACC000125"></a>`ACC000125` | 400 | **Bad Request**<br/>Não é possível realizar essa ação. Há taxas de boleto que não foram pagas.<br/><small>Can't perform this action. There'are few unpaid bankslip fees</small> |
| <a id="ACC000126"></a>`ACC000126` | 400 | **Bad Request**<br/>Ainda há boletos aceitos, registrados ou com aviso de pagamento<br/><small>There are accepted, registered or payment notice bank slips yet</small> |
| <a id="ACC000127"></a>`ACC000127` | 500 | **Bad Request**<br/>Falha ao criar termo de cancelamento de conta<br/><small>Failed to create account cancelling term</small> |
| <a id="ACC000128"></a>`ACC000128` | 400 | **Bad Request**<br/>Pix indisponível no momento. Por favor utilizar a TED.<br/><small>Pix unavailable in this moment. Please use TED.</small> |
| <a id="ACC000129"></a>`ACC000129` | 400 | **Bad Request**<br/>{type} não é um tipo válido de extrato.<br/><small>{type} is not a valid balance type.</small> |
| <a id="ACC000130"></a>`ACC000130` | 400 | **Bad Request**<br/>Contas de sistema não são habilitadas para executar essa transação.<br/><small>System Account is not allowed to do that transaction</small> |
| <a id="ACC000131"></a>`ACC000131` | 400 | **Bad Request**<br/>Transações de saída não podem possuir uma conta destino<br/><small>Outgoing transfer must not have a target account</small> |
| <a id="ACC000132"></a>`ACC000132` | 400 | **Bad Request**<br/>Transações de entrada não podem possuir uma conta origem<br/><small>Incoming transfer must not have a source account</small> |
| <a id="ACC000133"></a>`ACC000133` | 401 | **Unauthorized**<br/>Token inválido<br/><small>Invalid token</small> |
| <a id="ACC000134"></a>`ACC000134` | 401 | **Unauthorized**<br/>Token Expirado<br/><small>Expired token</small> |
| <a id="ACC000135"></a>`ACC000135` | 400 | **Bad Request**<br/>Contato nao existe<br/><small>Contact does not exist</small> |
| <a id="ACC000136"></a>`ACC000136` | 400 | **Bad Request**<br/>Agência ou número da conta de destino não podem ser 0.<br/><small>Target account branch or number must not be 0.</small> |
| <a id="ACC000137"></a>`ACC000137` | 400 | **Bad Request**<br/>Não há nenhum pedido de movimentação correspondente à payload enviada<br/><small>There is no pending movement correspondent to sent payload</small> |
| <a id="ACC000138"></a>`ACC000138` | 400 | **Bad Request**<br/>Movement request tem movement type nulo<br/><small>Movement request has null movement type</small> |
| <a id="ACC000139"></a>`ACC000139` | 400 | **Bad Request**<br/>Movement request possui movement status inválido: {old_movement_status}<br/><small>Movement request has invalid movement status: {old_movement_status}</small> |
| <a id="ACC000140"></a>`ACC000140` | 400 | **Bad Request**<br/>Não foi possível encontrar movement approval para o agente {selected_agent}<br/><small>Could not find movement approval for agent {selected_agent}</small> |
| <a id="ACC000141"></a>`ACC000141` | 400 | **Bad Request**<br/>Movement request já recebeu um feedback<br/><small>Movement request has already received feedback</small> |
| <a id="ACC000142"></a>`ACC000142` | 400 | **Bad Request**<br/>Sua conta não possui aprovador. Por favor, contate nosso suporte.<br/><small>Your account has no approver. Please, contact our support.</small> |
| <a id="ACC000143"></a>`ACC000143` | 404 | **Not Found**<br/>Investmento não foi encontrado.<br/><small>Investment not found</small> |
| <a id="ACC000144"></a>`ACC000144` | 400 | **Bad Request**<br/>Contas não possuem relacionamento de investimento adequado<br/><small>Accounts do not have proper investment relationship</small> |
| <a id="ACC000145"></a>`ACC000145` | 400 | **Not Found**<br/>Valor de procentagem de rendimento inválido.<br/><small>Invalid yield percentage amount</small> |
| <a id="ACC000146"></a>`ACC000146` | 422 | **Unprocessable Entity**<br/>Já existe uma configuração de investimento para esta conta<br/><small>Account investment configuration already exists for this account</small> |
| <a id="ACC000147"></a>`ACC000147` | 422 | **Unprocessable Entity**<br/>A conta não tem uma configuração de investimento associada.<br/><small>Account has not a existing investment configuration linked</small> |
| <a id="ACC000148"></a>`ACC000148` | 422 | **Unprocessable Entity**<br/>Não pode criar uma configuração de investimento em uma conta fechada<br/><small>Cannot setup a investment configuration to a closed account</small> |
| <a id="ACC000149"></a>`ACC000149` | 422 | **Unprocessable Entity**<br/>Houve um problema ao efetuar este saque. Por favor contate nosso suporte<br/><small>There was a problem performing this withdraw. Please contact our support</small> |
| <a id="ACC000150"></a>`ACC000150` | 400 | **Bad Request**<br/>Envio de mensagens internacionais não permitido<br/><small>International messaging not allowed</small> |
| <a id="ACC000151"></a>`ACC000151` | 400 | **Bad Request**<br/>Operação não identificada<br/><small>Operation not identified</small> |
| <a id="ACC000152"></a>`ACC000152` | 400 | **Bad Request**<br/>Forma de contato por {contact_type} não permitida<br/><small>Contact type {contact_type} not allowed</small> |
| <a id="ACC000153"></a>`ACC000153` | 400 | **Bad Request**<br/>Número de celular incorreto ou incompleto<br/><small>Incorrect or incomplete mobile number</small> |
| <a id="ACC000154"></a>`ACC000154` | 404 | **Not Found**<br/>Professional Data não encontrada<br/><small>Professional Data not found</small> |
| <a id="ACC000155"></a>`ACC000155` | 400 | **Bad Request**<br/>Transação {source_subtype} não pode ser realizada com as contas informadas<br/><small>Transaction {source_subtype} cannot be performed with given accounts</small> |
| <a id="ACC000156"></a>`ACC000156` | 400 | **Bad Request**<br/>Valor de transação não deve ser zero<br/><small>Transaction amount cannot be zero</small> |
| <a id="ACC000157"></a>`ACC000157` | 404 | **Not Found**<br/>Configuração de Investimento não encontrada<br/><small>Investment Configuration not found</small> |
| <a id="ACC000158"></a>`ACC000158` | 400 | **Bad Request**<br/>Somatório de investimentos insuficiente para realizar a transação<br/><small>Investment available amount not enough to perform withdraw</small> |
| <a id="ACC000159"></a>`ACC000159` | 400 | **Bad Request**<br/>Tipo de Movimentação de investimento inválida<br/><small>Invalid Investment Movement type</small> |
| <a id="ACC000160"></a>`ACC000160` | 400 | **Bad Request**<br/>Número de conta {account_number} já em uso<br/><small>Account number {account_number} already in use</small> |
| <a id="ACC000161"></a>`ACC000161` | 400 | **Bad Request**<br/>Depósito de investimento requerido maior que permitido<br/><small>Required investment deposit amount greater than allowed</small> |
| <a id="ACC000162"></a>`ACC000162` | 400 | **Conflict**<br/>Update de investment_available_balance não atendeu às espectativas. Esperado: {expected}. Calculado: {calculated}<br/><small>Update of investment_available_balance did not meet expectations. Expected: {expected}. Calculated: {calculated}</small> |
| <a id="ACC000163"></a>`ACC000163` | 400 | **Conflict**<br/>Valor {value} não permitido para atributo {attribute} no objeto {object_name}<br/><small>Value {value} not allowed for attribute {attribute} in object {object_name}</small> |
| <a id="ACC000164"></a>`ACC000164` | 400 | **Bad Request**<br/>Intervalo de datas (date_from and date_to) deve ser fornecido para geração de extrato<br/><small>Date interval (date_from and date_to) must be provided to generate statement</small> |
| <a id="ACC000165"></a>`ACC000165` | 400 | **Bad Request**<br/>Intervalo de datas maior que o permitido de {maximum_days}<br/><small>Date interval greater than allowed of {maximum_days}</small> |
| <a id="ACC000166"></a>`ACC000166` | 400 | **Bad Request**<br/>Person_key deve ser fornecida<br/><small>Person_key must be provided</small> |
| <a id="ACC000167"></a>`ACC000167` | 400 | **Conflict**<br/>Discrepância detectada em available yield transfer<br/><small>Discrepancy detected on available yield transfer</small> |
| <a id="ACC000168"></a>`ACC000168` | 400 | **Bad Request**<br/>O agent document number enviado não esta vinculado a empresa titular da conta para aprovar esta solicitação.<br/><small>The agent document number is not linked to the company that owns the account to approve this request.</small> |
| <a id="ACC000169"></a>`ACC000169` | 400 | **Bad Request**<br/>Transações externas não podem ser revertidas<br/><small>External transactions cannot be reversed</small> |
| <a id="ACC000170"></a>`ACC000170` | 400 | **Bad Request**<br/>Reversão de transação já realizada<br/><small>Reversal transaction already made</small> |
| <a id="ACC000171"></a>`ACC000171` | 400 | **Bad Request**<br/>Subtipo não pode ter transação revertida<br/><small>Subtype is not allowed to have transaction reversed</small> |
| <a id="ACC000172"></a>`ACC000172` | 400 | **Bad Request**<br/>Balanço de conta deve ter no máximo 2 casas decimais<br/><small>Account balance must have a maximum of 2 decimal places</small> |
| <a id="ACC000173"></a>`ACC000173` | 400 | **Bad Request**<br/>Balanço de conta da transação deve ser igual ao balanço de conta<br/><small>Transaction account balance must be equal to account balance</small> |
| <a id="ACC000174"></a>`ACC000174` | 400 | **Bad Request**<br/>Contas de sistema devem ser requeridas e propeietárias da QITECH<br/><small>System accounts must be owned and requested by QITECH</small> |
| <a id="ACC000175"></a>`ACC000175` | 400 | **Bad Request**<br/>Status da conta {account_status} não permitido<br/><small>Account status {account_status} not allowed</small> |
| <a id="ACC000176"></a>`ACC000176` | 400 | **Transaction limit exceeded**<br/>As transações nesse intervalo de data excedem o limite, tente novamente com um intervalo de data menor!<br/><small>The transactions within this date range exceeds the limit, please try again with a smaller date range!</small> |
| <a id="ACC000177"></a>`ACC000177` | 400 | **Bad Request**<br/>Intervalo de datas deve ser fornecido!<br/><small>The date range must be provided!</small> |
| <a id="ACC000178"></a>`ACC000178` | 400 | **Bad Request**<br/>Person_key e account_key deve ser fornecida<br/><small>Person_key and account_key must be provided</small> |
| <a id="ACC000179"></a>`ACC000179` | 429 | **Conflict**<br/>A request_control_jey {request_control_key} já existe<br/><small>The request_control_key {request_control_key} already exists</small> |
| <a id="ACC000180"></a>`ACC000180` | 400 | **Bad Request**<br/>O owner_trading_name só pode ser utilizado por uma pessoa jurídica<br/><small>The owner_trading_name can only be sent by a legal person type</small> |
| <a id="ACC000181"></a>`ACC000181` | 404 | **Not found**<br/>Alias {alias_key} não encontrado<br/><small>Alias {alias_key} not found</small> |
| <a id="ACC000182"></a>`ACC000182` | 404 | **Alias Key Not found**<br/>A alias_key {alias_key} não foi encontrada<br/><small>The alias_key {alias_key} was not Found</small> |
| <a id="ACC000183"></a>`ACC000183` | 400 | **Wrong Pagination Query Parameter Set**<br/>Se o page_number foi informado, o page_size deve ser informado tambem<br/><small>If page_number was informed, the page_size should also be informed</small> |
| <a id="ACC000184"></a>`ACC000184` | 400 | **Wrong Datetime**<br/>A datetime contida na string {datetime_string} não está em formato datetime-Zulu<br/><small>The datetime contined in the string {datetime_string} is not in datetime-Zulu format</small> |
| <a id="ACC000185"></a>`ACC000185` | 403 | **Invalid Owner Person Key**<br/>A account_key informada {account_key} não tem permissão de acessar esse recurso, pois a SELECTED-AGENT key não é a mesma da account informada<br/><small>The informed account_key {account_key} is not allowed to access this resource, because the SELECTED-AGENT key is not the same from the informed account</small> |
| <a id="ACC000186"></a>`ACC000186` | 404 | **Request Control Key Not found**<br/>A request_control_key informada {request_control_key} não possui entrada original associada<br/><small>The informed request_control_key {request_control_key} has no original registered entry associated</small> |
| <a id="ACC000187"></a>`ACC000187` | 403 | **Forbidden Selected-Agent**<br/>O SELECTED-AGENT informado {selected_agent_key} não tem permissão de acessar esse recurso<br/><small>The informed SELECTED-AGENT {selected_agent_key} is not allowed to access this resource</small> |
| <a id="ACC000188"></a>`ACC000188` | 400 | **Invalid Indirect Participant Key**<br/>a Indirect Participant Key é invalida<br/><small>The informed Indirect Participant Key is invalid</small> |
| <a id="ACC000189"></a>`ACC000189` | 400 | **Missing Query Parameters**<br/>Os paramentros necessarios para a query não estão presentes<br/><small>The necessery parameters for the query are not present</small> |
| <a id="ACC000190"></a>`ACC000190` | 404 | **Account Key not Found**<br/>A Account Key relacionada com os parametros apresentados não foi encontrada<br/><small>The Account key related with the presented parameters was not found</small> |
| <a id="ACC000191"></a>`ACC000191` | 422 | **Repeated Request Informations**<br/>A mesma combinação de account_number, account_branch e ispb ja foi previamente registrado em outra requisição de criação de Alias<br/><small>The same combination of account_number, account_branch and ispb was already previusly done in another Alias creation requisition</small> |
| <a id="ACC000192"></a>`ACC000192` | 400 | **Bad Request**<br/>Conta com configuração de rebate de floating ativo!<br/><small>Account with floating rebate configuration!</small> |
| <a id="ACC000193"></a>`ACC000193` | 400 | **Bad Request**<br/>Problema durante a verificação de configuração de rebate de floating!<br/><small>There was a problem performing verification in floating rebate configuration</small> |
| <a id="ACC000194"></a>`ACC000194` | 400 | **Bad Request**<br/>Número de documento {document_number} não é válido<br/><small>Document number {document_number} is not valid</small> |
| <a id="ACC000195"></a>`ACC000195` | 400 | **Bad Request**<br/>Número de documento {document_number} não corresponde ao tipo de pessoa {person_type}<br/><small>Document number {document_number} sent does not match the person_type {person_type}</small> |
| <a id="ACC000196"></a>`ACC000196` | 400 | **Bad Request**<br/>A conta está vinculada ao DDA.<br/><small>The account is bonded in DDA.</small> |
| <a id="ACC000197"></a>`ACC000197` | 400 | **Bad Request**<br/>Selected user agent deve ser fornecido.<br/><small>Selected user agent must be provided.</small> |
| <a id="ACC000198"></a>`ACC000198` | 400 | **Bad Request**<br/>Não é possível mudar o contato utilizando o contact type {contact_type}<br/><small>Unable to change {contact_info} using contact type {contact_type}</small> |
| <a id="ACC000199"></a>`ACC000199` | 400 | **Bad Request**<br/>Dados de configuração de cobrança não pode ser nula<br/><small>Billing configuration data can not be None</small> |
| <a id="ACC000200"></a>`ACC000200` | 400 | **Invalid reference year**<br/>Ano de referência inválido.<br/><small>Invalid reference year.</small> |
| <a id="ACC000201"></a>`ACC000201` | 403 | **Invalid Destination**<br/>Conta alvo não é um destino válido<br/><small>Target account is not a valid Destination</small> |
| <a id="ACC000202"></a>`ACC000202` | 400 | **Invalid permission**<br/>Requisitante enviado não possui permissão na conta<br/><small>Given requester has no permission to the account</small> |
| <a id="ACC000203"></a>`ACC000203` | 400 | **Invalid permission**<br/>Aprovador enviado não possui permissão na conta<br/><small>Given approver has no permission to the account</small> |
| <a id="ACC000204"></a>`ACC000204` | 400 | **Mandatory parameters missing**<br/>Parâmetros de query requester_person_key e approver_person_key são obrigatórios<br/><small>Query parameters requester_person_key and approver_person_key must be sent</small> |
| <a id="ACC000205"></a>`ACC000205` | 400 | **Conflicting parameters**<br/>Envie apenas um document_number ou uma person_key<br/><small>Send only a document_number or a person_key</small> |
| <a id="ACC000206"></a>`ACC000206` | 400 | **Bad Request**<br/>Conta de pessoa física não possui usuários autorizados.<br/><small>Natural person account does not have allowed users.</small> |
| <a id="ACC000207"></a>`ACC000207` | 400 | **Bad Request**<br/>Valor da transação deve ser maior que 0.<br/><small>Transaction amount must be greater than 0.</small> |
| <a id="ACC000208"></a>`ACC000208` | 404 | **Account not found**<br/>Conta não encontrada.<br/><small>Account not found.</small> |
| <a id="ACC000209"></a>`ACC000209` | 405 | **Method not allowed**<br/>Você não tem permissão para este método.<br/><small>you are not allowed to call this method.</small> |
| <a id="ACC000210"></a>`ACC000210` | 403 | **Forbidden**<br/>Método não peermitido para contas escrow.<br/><small>Escrow account are not allowed to call this method.</small> |
| <a id="ACC000211"></a>`ACC000211` | 409 | **Conflict**<br/>Entrada duplicada para request control key {request_control_key}.<br/><small>Duplicated request control key {request_control_key}.</small> |
| <a id="ACC000212"></a>`ACC000212` | 400 | **Bad Request**<br/>Documento do agente deve ser fornecido.<br/><small>Agent document number must be provided.</small> |
| <a id="ACC000213"></a>`ACC000213` | 400 | **Bad Request**<br/>UUID no formato inválido.<br/><small>Invalid uuid format.</small> |
| <a id="ACC000214"></a>`ACC000214` | 400 | **Bad Request**<br/>Tamanho da página inválido.<br/><small>Invalid page size.</small> |
| <a id="ACC000215"></a>`ACC000215` | 400 | **Bad Request**<br/>Formato inválido para campo. Deve ser uma string compostas por apenas digitos<br/><small>Invalid format for field. It must be a string comprised of only digits</small> |
| <a id="ACC000216"></a>`ACC000216` | 400 | **Bad Request**<br/>Agendamentos de pix em aberto detectados para esta conta<br/><small>Open Pix Schedules for this account detected</small> |
| <a id="ACC000217"></a>`ACC000217` | 400 | **Bad Request**<br/>Não é possível realizar transação de ponta a ponta com mesma origem e destino<br/><small>Can't perform peer to peer with the same target and source account</small> |
| <a id="ACC000218"></a>`ACC000218` | 400 | **Automatic Transfer External Transaction Error**<br/>Um erro ocorreu durante tentativa de realizar transferência automática<br/><small>An error occurred while performing automatic transfer transaction</small> |
| <a id="ACC000219"></a>`ACC000219` | 403 | **Requester not allowed to perform this action**<br/>Requester não autorizado a criar conta destino<br/><small>Requester not allowed to create destination</small> |
| <a id="ACC000220"></a>`ACC000220` | 400 | **Max attempts for automatic transfer reached**<br/>Número máximo de tentativas falhas de transferências atingida<br/><small>Maximum number of failed attempts for automatic transfer reached</small> |
| <a id="ACC000221"></a>`ACC000221` | 404 | **Not Found**<br/>Filial da instituição financeira não encontrada<br/><small>Financial institution branch not found</small> |
| <a id="ACC000222"></a>`ACC000222` | 400 | **Bad Request**<br/>Transferência automática para a mesma conta que de origem.<br/><small>Automatic transfer to the same account as source</small> |
| <a id="ACC000223"></a>`ACC000223` | 409 | **Conflict**<br/>Conta com número {account_number} já existe<br/><small>Account with number {account_number} already exists</small> |
| <a id="ACC000224"></a>`ACC000224` | 400 | **Bad Request**<br/>Contas de origem e destino devem ser diferentes<br/><small>Source and target accounts must be different</small> |

### ACR — Abertura de Conta

47 erros

| Código | HTTP | Mensagem |
|-|-|-|
| <a id="ACR000001"></a>`ACR000001` | 404 | **Account Request Not Found**<br/>Solicitação de conta não encontrada para os parâmetros dados.<br/><small>Account Request not found for the given parameters</small> |
| <a id="ACR000002"></a>`ACR000002` | 404 | **Account Request Not Found**<br/>Solicitação de conta não encontrada para a seguinte chave {account_request_key}.<br/><small>Account Request not found for the given key {account_request_key}.</small> |
| <a id="ACR000003"></a>`ACR000003` | 404 | **Proposal Not Found**<br/>Proposta não encontrada.<br/><small>Proposal not found.</small> |
| <a id="ACR000004"></a>`ACR000004` | 400 | **Bad Request**<br/>Esta conta não tem credenciais válidas para esta proposta.<br/><small>This account don't have valid credentials to this proposal.</small> |
| <a id="ACR000005"></a>`ACR000005` | 400 | **Bad Request**<br/>Use PUT account_request/{account_request_key} |
| <a id="ACR000006"></a>`ACR000006` | 400 | **Account Request Error**<br/>Pedido de conta não está pendente de aprovação master<br/><small>Account Request is not pending master approval</small> |
| <a id="ACR000007"></a>`ACR000007` | 400 | **Bad Request**<br/>Use PATCH /account/{account_key} |
| <a id="ACR000008"></a>`ACR000008` | 403 | **Unauthorized Agent**<br/>Este agente não pode realizar esta ação<br/><small>This agent can not perform this action</small> |
| <a id="ACR000009"></a>`ACR000009` | 400 | **Bad Request**<br/>Requester key necessária!<br/><small>Requester key needed!</small> |
| <a id="ACR000010"></a>`ACR000010` | 400 | **Bad Request**<br/>Related Party Owner necessário!<br/><small>Related Party Owner needed!</small> |
| <a id="ACR000011"></a>`ACR000011` | 400 | **Proposal Error**<br/>Proposta não está pendente de aprovação do administrador!<br/><small>Proposal Isn't Pending Administrator Approval!</small> |
| <a id="ACR000012"></a>`ACR000012` | 400 | **Proposal Update Error**<br/>Erro no update<br/><small>Update Error</small> |
| <a id="ACR000013"></a>`ACR000013` | 400 | **Bad Request**<br/>Ação inválida!<br/><small>Invalid Action!</small> |
| <a id="ACR000014"></a>`ACR000014` | 400 | **Bad Request**<br/>Necessário uma razão para a rejeição!<br/><small>Rejection Reason Needed!</small> |
| <a id="ACR000015"></a>`ACR000015` | 400 | **Fee Error**<br/>O valor de Fee não pode ser negativo!<br/><small>Fee value can not be negative!</small> |
| <a id="ACR000016"></a>`ACR000016` | 400 | **Fee Error**<br/>O valor de taxa fixa de TED não pode ser negativo!<br/><small>Ted fixed amount fee value can not be negative!</small> |
| <a id="ACR000017"></a>`ACR000017` | 400 | **Fee Error**<br/>O valor de taxa percentual de TED não pode ser negativo!<br/><small>Ted percentage fee value can not be negative!</small> |
| <a id="ACR000018"></a>`ACR000018` | 400 | **Proposal Error**<br/>A proposta não está com assinatura do documento pendente!<br/><small>Proposal Isn't Pending Document Signature!</small> |
| <a id="ACR000019"></a>`ACR000019` | 400 | **Proposal Error**<br/>A proposta não está com contrato de usuário pendente!<br/><small>Proposal Isn't Pending User Agreement!</small> |
| <a id="ACR000020"></a>`ACR000020` | 400 | **Proposal Error**<br/>Status de proposta inválido!<br/><small>Invalid Proposal Status!</small> |
| <a id="ACR000021"></a>`ACR000021` | 400 | **Bad Request**<br/>A regra de transferência automática não segue o modelo de regra: {message}<br/><small>Automatic transfer rule does not follow rule template: {message}</small> |
| <a id="ACR000022"></a>`ACR000022` | 422 | **Unprocessable Entity**<br/>Solicitante da proposta possui configuração incompleta no sistema de faturamento<br/><small>Proposal requester has incomplete configuration in billing system</small> |
| <a id="ACR000023"></a>`ACR000023` | 400 | **Bad Request**<br/>Documento inválido {document_number} para {name}.<br/><small>Invalid Document Number {document_number} for {name}.</small> |
| <a id="ACR000024"></a>`ACR000024` | 400 | **Bad Request**<br/>Use POST account_request/{account_request_key}/generate_document |
| <a id="ACR000025"></a>`ACR000025` | 400 | **Bad Request**<br/>O status da proposta deve estar pendente para ser atualizado.<br/><small>Proposal status must be pending to get updated.</small> |
| <a id="ACR000026"></a>`ACR000026` | 400 | **Bad Request**<br/>Não foi possível criar um destino devido a um código de instituição inexistent: {codes_list}<br/><small>Could not create destination due inexistent financial code numbers: {codes_list}</small> |
| <a id="ACR000027"></a>`ACR000027` | 404 | **Not Found**<br/>Email do solicitante não foi encontrado.<br/><small>Requester email not found.</small> |
| <a id="ACR000028"></a>`ACR000028` | 400 | **Bad Request**<br/>Motivo da transferência é obrigatório para cadastrar tarifas para operações de boleto.<br/><small>An operation reason is required to register fees for bankslip products</small> |
| <a id="ACR000029"></a>`ACR000029` | 400 | **Bad Request**<br/>Um valor para o pacote de operações PIX que não serão cobradas tarifas é obrigatório.<br/><small>A package value of PIX operations to not be charged fees is required</small> |
| <a id="ACR000030"></a>`ACR000030` | 400 | **Bad Request**<br/>Não é possível processar uma configuração de tarifa repetida no payload<br/><small>Unable to process a repeated fee_configuration in the payload</small> |
| <a id="ACR000031"></a>`ACR000031` | 400 | **Bad Request**<br/>Tipo de conta não é escrow.<br/><small>Account type is not escrow.</small> |
| <a id="ACR000032"></a>`ACR000032` | 400 | **Bad Request**<br/>Proposal {proposal_key} Tipo de conta não é checking.<br/><small>Proposal {proposal_key} Account type is not checking.</small> |
| <a id="ACR000033"></a>`ACR000033` | 400 | **Bad Request**<br/>O nome {name} contém caractéres inválidos. Aceitos apenas caractéres alfanuméricos e os simbolos: . / & - ’<br/><small>Name {name} has invalid characters.</small> |
| <a id="ACR000034"></a>`ACR000034` | 400 | **Bad Request**<br/>Não é permitido alterar as configurações de cobrança de tarifas desta conta.<br/><small>It is not allowed to change account default billing configuration data.</small> |
| <a id="ACR000035"></a>`ACR000035` | 400 | **Bad Request**<br/>O valor da tarifa mensal de manutenção de conta não pode ser negativo!<br/><small>Account maintenance monthly fee value cannot be negative!</small> |
| <a id="ACR000036"></a>`ACR000036` | 400 | **Bad Request**<br/>É necessária ao menos uma configuração de tarifa mensal de conta nos dados de 'billing_configuration_data' no payload<br/><small>At least '1' fee configuration is required for account_maintenance billing configuration data in the payload</small> |
| <a id="ACR000037"></a>`ACR000037` | 400 | **Bad Request**<br/>'billing_account_key' não pode ser nula<br/><small>'billing_account_key' cannot be null</small> |
| <a id="ACR000038"></a>`ACR000038` | 400 | **Bad Request**<br/>Proposta com status de operação pendente de emissão não pode ser assinada<br/><small>Proposal with status pending operation issue cannot be signed</small> |
| <a id="ACR000039"></a>`ACR000039` | 400 | **Bad Request**<br/>Email É obrigatorio para configurações de tarifas pagas via boleto<br/><small>Email is required for billing configurations paid via bank-slip</small> |
| <a id="ACR000040"></a>`ACR000040` | 403 | **Forbidden**<br/>Este usuário não tem permissão para requisitar conta<br/><small>This user does not have permission to request account</small> |
| <a id="ACR000041"></a>`ACR000041` | 404 | **Account request not found**<br/>Requisição de abertura de conta não encontrada para {account_request_key}<br/><small>Account request not found for {account_request_key}</small> |
| <a id="ACR000042"></a>`ACR000042` | 400 | **Account request in wrong status**<br/>Requisição de abertura de conta com status inválido para conclusão<br/><small>Account request in wrong status for conclusion</small> |
| <a id="ACR000043"></a>`ACR000043` | 400 | **Account request is pending kyc analysis**<br/>Requisição de abertura de conta pendente de análise KYC<br/><small>Account request is pending kyc analysis</small> |
| <a id="ACR000044"></a>`ACR000044` | 400 | **Conflictingly ispb and code number**<br/>ISPB e financial_institution_code conflitantes<br/><small>Conflictingly ISPB and financial_institution_code</small> |
| <a id="ACR000045"></a>`ACR000045` | 404 | **ISPB not found**<br/>ISPB não encontrado<br/><small>ISB not found</small> |
| <a id="ACR000046"></a>`ACR000046` | 404 | **Account Not Found**<br/>Conta não encontrada.<br/><small>Account not found.</small> |
| <a id="ACR000047"></a>`ACR000047` | 403 | **Forbidden**<br/>Agente não é solicitante da conta.<br/><small>Person is not requester of this account.</small> |

### BLP — Boletos

191 erros

| Código | HTTP | Mensagem |
|-|-|-|
| <a id="BLP000001"></a>`BLP000001` | 400 | **Bad Request**<br/>Instituição registradora inválida {registration_institution_enumerator}<br/><small>Invalid Registration Institution {registration_institution_enumerator}</small> |
| <a id="BLP000002"></a>`BLP000002` | 404 | **Not Found**<br/>Não é possível gerar arquivo vazio<br/><small>Cannot generate empty file</small> |
| <a id="BLP000003"></a>`BLP000003` | 400 | **Bad Request**<br/>Use POST /cnab/{action_type} |
| <a id="BLP000004"></a>`BLP000004` | 404 | **Not Found**<br/>Boleto não encontrado.<br/><small>Bank Slip not found.</small> |
| <a id="BLP000005"></a>`BLP000005` | 400 | **Bad Request**<br/>Use GET /bank_slip/{bank_slip_key} ou /bank_slip/person/{person_key}<br/><small>Use GET /bank_slip/{bank_slip_key} or /bank_slip/person/{person_key}</small> |
| <a id="BLP000006"></a>`BLP000006` | 400 | **Bad Request**<br/>A request precisa de um dos seguintes parâmetros:  requester_profile_code, beneficiary_key<br/><small>Request needs one of the following parameters: requester_profile_code, beneficiary_key</small> |
| <a id="BLP000007"></a>`BLP000007` | 400 | **Bad Request**<br/>Parâmetro obrigatório ausente: content_type<br/><small>Missing mandatory parameter: content_type</small> |
| <a id="BLP000008"></a>`BLP000008` | 400 | **Bad Request**<br/>content_type inválido, tente um dos seguintes: {valid_content_types}<br/><small>Invalid content_type, try one of: {valid_content_types}</small> |
| <a id="BLP000009"></a>`BLP000009` | 400 | **Bad Request**<br/>Despesa já paga<br/><small>Expense already paid</small> |
| <a id="BLP000010"></a>`BLP000010` | 400 | **Bad Request**<br/>Defina a despesa para liquidar<br/><small>Please set the expense to settle</small> |
| <a id="BLP000011"></a>`BLP000011` | 400 | **Bad Request**<br/>Parâmetro obrigatório ausente: beneficiary_key<br/><small>Missing mandatory parameter: beneficiary_key</small> |
| <a id="BLP000012"></a>`BLP000012` | 400 | **Bad Request**<br/>Parâmetro obrigatório ausente: digitable_line<br/><small>Missing mandatory parameter: digitable_line</small> |
| <a id="BLP000013"></a>`BLP000013` | 400 | **Bad Request**<br/>Defina subject_account_key para liquidar<br/><small>Please set the subject_account_key to settle</small> |
| <a id="BLP000014"></a>`BLP000014` | 400 | **Bad Request**<br/>Já existe um boleto com o status {status_br}.<br/><small>Impossible to schedule or execute payment: entry already exists in database with {existing_payment_status} status.</small> |
| <a id="BLP000015"></a>`BLP000015` | 400 | **Bad Request**<br/>Impossível agendar pagamento após data de vencimento.<br/><small>Impossible to schedule payment after expiration date.</small> |
| <a id="BLP000016"></a>`BLP000016` | 400 | **Bad Request**<br/>Impossível executar o pagamento para o período desejado.<br/><small>Impossible to execute payment after valid time frame.</small> |
| <a id="BLP000017"></a>`BLP000017` | 400 | **Bad Request**<br/>Impossível executar ou agendar pagamentos com um valor total superior a 249.999,99<br/><small>Impossible to execute or schedule payments with a total amount greater than 249,999.99</small> |
| <a id="BLP000018"></a>`BLP000018` | 400 | **Bad Request**<br/>Cálculo de pagamento inválido! Modelo de cálculo: {calculation_model}; Data do cálculo: {calculation_date}<br/><small>Invalid payment calculation! Calculation model: {calculation_model}; Calculation date: {calculation_date}</small> |
| <a id="BLP000019"></a>`BLP000019` | 404 | **Not Found**<br/>Pagamento não encontrada para a chave {payment_key}.<br/><small>Payment entry not found for key {payment_key}.</small> |
| <a id="BLP000020"></a>`BLP000020` | 400 | **Bad Request**<br/>Impossível executar o pagamento para a chave de pagamento {payment_key}. Seu status é diferente de 'agendado'.<br/><small>Impossible to execute payment for payment_key {payment_key}. Payment status is not 'scheduled'.</small> |
| <a id="BLP000021"></a>`BLP000021` | 400 | **Bad Request**<br/>Pagamento inválido: a data agendada do pagamento {payment_key} não é hoje.<br/><small>Invalid payment: scheduled payment date is not today for key {payment_key}.</small> |
| <a id="BLP000022"></a>`BLP000022` | 400 | **Bad Request**<br/>A data do pagamento deve ser a partir de hoje.<br/><small>Payment date has to be from today onwards.</small> |
| <a id="BLP000023"></a>`BLP000023` | 400 | **Bad Request**<br/>A data do pagamento deve ser um dia útil.<br/><small>Payment date has to be a workday.</small> |
| <a id="BLP000024"></a>`BLP000024` | 423 | **Locked**<br/>Operação encerrada. Sistema disponível de {opening_time} a {closing_time}<br/><small>Operation window closed. System available from {opening_time} to {closing_time}</small> |
| <a id="BLP000025"></a>`BLP000025` | 400 | **Bad Request**<br/>Parâmetro obrigatório ausente: {param}<br/><small>Missing mandatory parameter: {param}</small> |
| <a id="BLP000026"></a>`BLP000026` | 400 | **Bad Request**<br/>Só é possível procurar pagamentos agendados com o seguinte status: {valid_payment_status_set}.<br/><small>It's only possible to search for scheduled payments with the following status: {valid_payment_status_set}.</small> |
| <a id="BLP000027"></a>`BLP000027` | 400 | **Bad Request**<br/>Só é possível alterar o pagamento agendado para o seguinte status: {valid_payment_status_set}.<br/><small>It's only possible to change scheduled payment to the following status: {valid_payment_status_set}.</small> |
| <a id="BLP000028"></a>`BLP000028` | 400 | **Bad Request**<br/>O pagamento não está agendado. Status atual do pagamento: {current_payment_status}.<br/><small>Payment is not scheduled. Current payment status: {current_payment_status}.</small> |
| <a id="BLP000029"></a>`BLP000029` | 400 | **Bad Request**<br/>Use GET /bank_slip/{bank_slip_key}/2-way |
| <a id="BLP000030"></a>`BLP000030` | 404 | **Not Found**<br/>Conta do beneficiário do boleto não encontrada.<br/><small>Bank Slip beneficiary account not found.</small> |
| <a id="BLP000031"></a>`BLP000031` | 404 | **Not Found**<br/>Beneficiário do boleto não encontrado.<br/><small>Bank Slip beneficiary not found.</small> |
| <a id="BLP000032"></a>`BLP000032` | 400 | **Bad Request**<br/>Este acordo já foi pago<br/><small>This settlement is already paid</small> |
| <a id="BLP000033"></a>`BLP000033` | 400 | **Bad Request**<br/>Use POST /cnab/{action_type} |
| <a id="BLP000034"></a>`BLP000034` | 400 | **Bad Request**<br/>Tipo CNAB inválido<br/><small>Invalid CNAB Type</small> |
| <a id="BLP000035"></a>`BLP000035` | 400 | **Bad Request**<br/>Use GET /cnab_file/{person_key}/{cnab_type} |
| <a id="BLP000036"></a>`BLP000036` | 404 | **Not Found**<br/>Não há um arquivo CNAB para a cnab_key especificada.<br/><small>There is no CNAB File with the specified cnab_key.</small> |
| <a id="BLP000037"></a>`BLP000037` | 400 | **Bad Request**<br/>Código da carteira necessário<br/><small>Requester Profile Code Needed</small> |
| <a id="BLP000038"></a>`BLP000038` | 404 | **Not Found**<br/>Carteira não encontrada para o código da carteira fornecido<br/><small>Requester Profile not found for the given requester profile code</small> |
| <a id="BLP000039"></a>`BLP000039` | 404 | **Not Found**<br/>Ocorrências para envio não encontradas<br/><small>Occurrences for submission not found</small> |
| <a id="BLP000040"></a>`BLP000040` | 404 | **Not Found**<br/>Ocorrências para envio não encontradas para a chave fornecida<br/><small>No Occurrence found for the given key.</small> |
| <a id="BLP000041"></a>`BLP000041` | 400 | **Bad Request**<br/>Use GET /cnab_temporary/{remittance_key} |
| <a id="BLP000042"></a>`BLP000042` | 400 | **Bad Request**<br/>Tipo de ação não permitido, use editar ou enviar<br/><small>Action Type not allowed, use edit or submit</small> |
| <a id="BLP000043"></a>`BLP000043` | 400 | **Bad Request**<br/>Use PATCH /cnab_temporary/{remittance_key}/{action_type} |
| <a id="BLP000044"></a>`BLP000044` | 423 | **Locked**<br/>A geração de retorno não pode ser realizada nos feriados<br/><small>Discharge generation can not be performed on holidays</small> |
| <a id="BLP000045"></a>`BLP000045` | 423 | **Locked**<br/>Geração de retorno não está pronta para continuar<br/><small>Discharge generation not ready to continue</small> |
| <a id="BLP000046"></a>`BLP000046` | 400 | **Bad Request**<br/>Use PUT /expense_configuration/{beneficiary_account_key} |
| <a id="BLP000047"></a>`BLP000047` | 400 | **Bad Request**<br/>Nenhuma company_key encontrada<br/><small>No company_key found</small> |
| <a id="BLP000048"></a>`BLP000048` | 400 | **Bad Request**<br/>O campo selected-agent do cabeçalho é necessário.<br/><small>Header selected-agent is needed.</small> |
| <a id="BLP000049"></a>`BLP000049` | 400 | **Bad Request**<br/>O campo selected-agent do cabeçalho é necessário.<br/><small>Header selected-agent is needed.</small> |
| <a id="BLP000050"></a>`BLP000050` | 400 | **Bad Request**<br/>Registro encontrado sem o nosso número<br/><small>Found record without our_number</small> |
| <a id="BLP000051"></a>`BLP000051` | 400 | **Bad Request**<br/>O remetente não pode ser uma instituição de registro no caso de arquivos REM.<br/><small>Remitter can't be a registration institution in case of REM files.</small> |
| <a id="BLP000052"></a>`BLP000052` | 404 | **Not Found**<br/>Boleto para pagamento em cartório não encontrado<br/><small>Bank Slip for notary office payment not found</small> |
| <a id="BLP000053"></a>`BLP000053` | 400 | **Bad Request**<br/>Tipo de arquivo {file_type} não implementado.<br/><small>File type {file_type} not implemented.</small> |
| <a id="BLP000055"></a>`BLP000055` | 404 | **Not Found**<br/>Nenhum boleto para protesto encontrado<br/><small>Bank SLip for protest not found</small> |
| <a id="BLP000056"></a>`BLP000056` | 400 | **Bad Request**<br/>Use POST /requester_configuration |
| <a id="BLP000057"></a>`BLP000057` | 404 | **Not Found**<br/>Carteira não encontrada.<br/><small>Requester Profile not found.</small> |
| <a id="BLP000058"></a>`BLP000058` | 400 | **Bad Request**<br/>Parâmetro obrigatório ausente: person_key<br/><small>Missing mandatory parameter: person_key</small> |
| <a id="BLP000059"></a>`BLP000059` | 400 | **Bad Request**<br/>Use POST /requester_profile/{requester_profile_key} |
| <a id="BLP000060"></a>`BLP000060` | 404 | **Not Found**<br/>Conta não encontrada para a chave {person_key}.<br/><small>Account not found for person key {person_key}.</small> |
| <a id="BLP000061"></a>`BLP000061` | 400 | **Bad Request**<br/>Intervalo já usado<br/><small>Range already used</small> |
| <a id="BLP000062"></a>`BLP000062` | 400 | **Bad Request**<br/>Use POST /requester_profile_range |
| <a id="BLP000064"></a>`BLP000064` | 400 | **Bad Request**<br/>Falta REGISTRATION_INSTITUTION_CONFIG<br/><small>Missing Registration Institution config</small> |
| <a id="BLP000065"></a>`BLP000065` | 422 | **Pub Sub Ocurrence Error**<br/>Ordem de ocorrência de arquivo CNAB inválida.<br/><small>Invalid CNAB file occurrence order.</small> |
| <a id="BLP000066"></a>`BLP000066` | 400 | **Bad Request**<br/>Tipo de ocorrência {occurrence_type} não suportado<br/><small>Occurrence type {occurrence_type} not supported</small> |
| <a id="BLP000067"></a>`BLP000067` | 400 | **Bad Request**<br/>Erros encontrados no arquivo CNAB de retorno: {occurrence_sequence}<br/><small>Errors found on return CNAB File: {occurrence_sequence}</small> |
| <a id="BLP000068"></a>`BLP000068` | 400 | **Bad Request**<br/>Arquivo: {filename}. Erro: {error}<br/><small>File: {filename}. Error: {error}</small> |
| <a id="BLP000069"></a>`BLP000069` | 400 | **Bad Request - CNAB ERROR**<br/>Arquivo vazio ou corrompido.<br/><small>Empty or corrupted file.</small> |
| <a id="BLP000070"></a>`BLP000070` | 400 | **Bad Request - CNAB ERROR**<br/>Não foi possível identificar o tipo de arquivo CNAB enviado.<br/><small>Could not find the CNAB type.</small> |
| <a id="BLP000071"></a>`BLP000071` | 400 | **Bad Request - CNAB ERROR**<br/>Versão de CNAB não suportada.<br/><small>CNAB version not supported yet.</small> |
| <a id="BLP000072"></a>`BLP000072` | 400 | **Bad Request - CNAB ERROR**<br/>Linha de registro com tamanho incorreto.<br/><small>Registry line size incorrect.</small> |
| <a id="BLP000073"></a>`BLP000073` | 400 | **Bad Request - CNAB ERROR**<br/>Não foi possível determinar o código do banco operador<br/><small>Could not determine Bank Code.</small> |
| <a id="BLP000074"></a>`BLP000074` | 400 | **Bad Request - CNAB ERROR**<br/>Não foi possível determinar a versão do CNAB.<br/><small>Could not determine CNAB version.</small> |
| <a id="BLP000075"></a>`BLP000075` | 400 | **Bad Request - CNAB ERROR**<br/>Não foi possível determinar o tipo do CNAB (Remessa / Retorno).<br/><small>Could not determine CNAB type (Remittance / Discharge).</small> |
| <a id="BLP000076"></a>`BLP000076` | 400 | **Bad Request - CNAB ERROR**<br/>Tipo de arquivo incorreto, deve ser Remessa(1) ou Retorno(2).<br/><small>Invalid CNAB type, must be Remittance(1) or Discharge(2).</small> |
| <a id="BLP000077"></a>`BLP000077` | 400 | **Bad Request - CNAB ERROR**<br/>Tradutor de CNAB não implementado para o tipo enviado.<br/><small>CNAB translator not implemented yet for the type sent.</small> |
| <a id="BLP000078"></a>`BLP000078` | 400 | **Bad Request - CNAB ERROR**<br/>Não foi possível ler o campo.<br/><small>Could not set the field.</small> |
| <a id="BLP000079"></a>`BLP000079` | 400 | **Bad Request - CNAB ERROR**<br/>Número máximo de dígitos excedido para o campo.<br/><small>Max field size exceeded.</small> |
| <a id="BLP000080"></a>`BLP000080` | 400 | **Bad Request - CNAB ERROR**<br/>Tipo de valor incorreto.<br/><small>Value type incorrect.</small> |
| <a id="BLP000081"></a>`BLP000081` | 400 | **Bad Request - CNAB ERROR**<br/>Número de casas decimais incorreto.<br/><small>Wrong number of decimal places.</small> |
| <a id="BLP000082"></a>`BLP000082` | 400 | **Bad Request - CNAB ERROR**<br/>Linha de Registro Header colocado na posição incorreta.<br/><small>Wrong header record position in file.</small> |
| <a id="BLP000083"></a>`BLP000083` | 400 | **Bad Request - CNAB ERROR**<br/>Sequência de registros incorreta no arquivo.<br/><small>Wrong cnab record sequence.</small> |
| <a id="BLP000084"></a>`BLP000084` | 400 | **Bad Request - CNAB ERROR**<br/>Linha de Registro trailer colocado na posição incorreta.<br/><small>Wrong trailer record position in file.</small> |
| <a id="BLP000085"></a>`BLP000085` | 400 | **Bad Request - CNAB ERROR**<br/>Tipo de registro não suportado.<br/><small>Record type not supported.</small> |
| <a id="BLP000086"></a>`BLP000086` | 400 | **Bad Request - CNAB ERROR**<br/>Espécie de Título não suportada.<br/><small>Asset type not supported.</small> |
| <a id="BLP000087"></a>`BLP000087` | 400 | **Bad Request - CNAB ERROR**<br/>Tipo de ocorrência não suportada.<br/><small>Occurrence not supported.</small> |
| <a id="BLP000088"></a>`BLP000088` | 400 | **Bad Request - CNAB ERROR**<br/>Número sequencial de remessa inválido ou em uso.<br/><small>Remittance sequence number invalid or in use.</small> |
| <a id="BLP000089"></a>`BLP000089` | 400 | **Bad Request - CNAB ERROR**<br/>Nome do arquivo de remessa inválido.<br/><small>Invalid Remittance filename.</small> |
| <a id="BLP000090"></a>`BLP000090` | 400 | **Bad Request - CNAB ERROR**<br/>Número sequencial de registro inválido ou não sequencial.<br/><small>Invalid record sequence or not sequential.</small> |
| <a id="BLP000091"></a>`BLP000091` | 400 | **Bad Request - CNAB ERROR**<br/>Número máximo de retornos gerados alcançado.<br/><small>Max Number of Discharges reached.</small> |
| <a id="BLP000094"></a>`BLP000094` | 400 | **Bad Request - CNAB ERROR**<br/>Nome do arquivo de remessa duplicado.<br/><small>Duplicated Remittance filename.</small> |
| <a id="BLP000097"></a>`BLP000097` | 400 | **Bad Request - CNAB ERROR**<br/>Não foi possível determinar o nome do banco.<br/><small>Could not determine bank name.</small> |
| <a id="BLP000098"></a>`BLP000098` | 400 | **Bad Request - CNAB ERROR**<br/>Carteira não encontrada: {requester_profiles}. Verifique o campo Identificação da Empresa Beneficiária (posições 21 a 37)<br/><small>Requester profile not found: {requester_profiles}. Check CNAB field beneficiary identification (positions 21 to 37)</small> |
| <a id="BLP000099"></a>`BLP000099` | 400 | **Bad Request - CNAB ERROR**<br/>Número máximo de remessas alcançado.<br/><small>Max Number of Remittances reached.</small> |
| <a id="BLP000100"></a>`BLP000100` | 400 | **Bad Request - CNAB ERROR**<br/>Tipo de ocorrência não suportado.<br/><small>Not supported occurrence type.</small> |
| <a id="BLP000102"></a>`BLP000102` | 400 | **Bad Request**<br/>A Request precisa de pelo menos um dos seguintes parâmetros: barcode, digitable_line<br/><small>Request needs at least one of the following parameters: barcode, digitable_line</small> |
| <a id="BLP000103"></a>`BLP000103` | 400 | **Bad Request**<br/>Lista de chaves não pode ser vazia<br/><small>Keys must not be empty</small> |
| <a id="BLP000104"></a>`BLP000104` | 400 | **Bad Request**<br/>Registro na CIP inválido, por favor tente novamente daqui alguns minutos<br/><small>CIP registration not valid please try again in a few minutes</small> |
| <a id="BLP000105"></a>`BLP000105` | 400 | **Bad Request**<br/>SELECTED_AGENT deve ser fornecido<br/><small>A SELECTED_AGENT must be provided</small> |
| <a id="BLP000106"></a>`BLP000106` | 400 | **Bad Request**<br/>Use PATCH /expense_configuration/{requester_profile_key} |
| <a id="BLP000107"></a>`BLP000107` | 400 | **Bad Request**<br/>Mensagem para o boleto inválida, ocorrência {occurrence_sequence}<br/><small>Invalid bank teller instruction, occurrence {occurrence_sequence}</small> |
| <a id="BLP000108"></a>`BLP000108` | 400 | **Bad Request**<br/>Use GET expense?subject_account_key={account_key} |
| <a id="BLP000109"></a>`BLP000109` | 404 | **Not Found**<br/>Cnab não encontrado para a chave {cnab_key}.<br/><small>Cnab not found for the given key {cnab_key}</small> |
| <a id="BLP000110"></a>`BLP000110` | 422 | **Unprocessable Entity**<br/>Nosso número {our_number} duplicado, ordem da ocorrência {occurrence_sequence}<br/><small>Duplicate our number {our_number}, occurrence sequence {occurrence_sequence}</small> |
| <a id="BLP000111"></a>`BLP000111` | 422 | **Unprocessable Entity**<br/>Nosso número {our_number} inválido para código de carteira {requester_profile_code}, ordem da ocorrência {occurrence_sequence}<br/><small>Invalid our number {our_number} for requester profile code {requester_profile_code}, occurrence sequence {occurrence_sequence}</small> |
| <a id="BLP000112"></a>`BLP000112` | 422 | **Unprocessable Entity**<br/>Remessa Rejeitada<br/><small>Rejected Remittance</small> |
| <a id="BLP000113"></a>`BLP000113` | 422 | **Unprocessable Entity**<br/>Código do banco não enviado, ordem da ocorrência {occurrence_sequence}<br/><small>Bank Code not sent, occurrence sequence {occurrence_sequence}</small> |
| <a id="BLP000114"></a>`BLP000114` | 422 | **Unprocessable Entity**<br/>Agência não enviada, ordem da ocorrência {occurrence_sequence}<br/><small>Payment branch not sent, occurrence sequence {occurrence_sequence}</small> |
| <a id="BLP000115"></a>`BLP000115` | 422 | **Unprocessable Entity**<br/>Data de Pagamento não enviada, ordem da ocorrência {occurrence_sequence}<br/><small>Payment Credit Date not sent, occurrence sequence {occurrence_sequence}</small> |
| <a id="BLP000116"></a>`BLP000116` | 422 | **Unprocessable Entity**<br/>Linha digitável inválida: {digitable_line}<br/><small>Invalid digitable line: {digitable_line}</small> |
| <a id="BLP000117"></a>`BLP000117` | 400 | **Bad Request**<br/>A carteira selecionada possui {bank_slips_count} boletos em aberto. Não é possível desativar esta carteira.<br/><small>This requester profile has {bank_slips_count} open bank slips. You cannot deactivate this profile.</small> |
| <a id="BLP000118"></a>`BLP000118` | 422 | **Unprocessable Entity**<br/>Carteira bloqueada ou fechada não pode registrar novos boletos , ordem da ocorrência {occurrence_sequence}<br/><small>Blocked or closed requester profile can not register new bank slips, occurrence sequence {occurrence_sequence}</small> |
| <a id="BLP000119"></a>`BLP000119` | 400 | **Bad Request**<br/>Carteiras fechadas não podem gerar novas ocorrências<br/><small>Closed requester profile can not register new occurrences</small> |
| <a id="BLP000120"></a>`BLP000120` | 400 | **Bad Request**<br/>Não foi possível ler o CNAB devido presença de caracteres especiais na linha {line} e posição {position} do arquivo.<br/><small>Unable to read CNAB file. Check file data for special characters at line {line} and position {position}</small> |
| <a id="BLP000121"></a>`BLP000121` | 404 | **Not Found**<br/>Boletos não encontrados para gerar tarifa de permanência<br/><small>Not Found bank Slip to generate permanency expense</small> |
| <a id="BLP000122"></a>`BLP000122` | 404 | **Not Found**<br/>Boletos não encontrados para gerar baixa por decurso de prazo<br/><small>Not Found bank Slip to generate write off term</small> |
| <a id="BLP000123"></a>`BLP000123` | 400 | **Bad Request**<br/>Arquivo CNAB com mais de uma carteira (posições 021 a 037).<br/><small>CNAB file with more than one requester profile (positions 021 a 037).</small> |
| <a id="BLP000124"></a>`BLP000124` | 400 | **Bad Request**<br/>Parâmetro obrigatório ausente: requester_profile_key<br/><small>Missing mandatory parameter: requester_profile_key</small> |
| <a id="BLP000125"></a>`BLP000125` | 404 | **Not Found**<br/>Nenhum boleto com notificações a serem enviadas foi encontrado<br/><small>No bankslips with notifications to be sent found</small> |
| <a id="BLP000126"></a>`BLP000126` | 400 | **Bad Request**<br/>Tipo de arquivo inválido. O upload do logo deve ser uma imagem .png<br/><small>Invalid file type. Logo upload should be a .png image type</small> |
| <a id="BLP000127"></a>`BLP000127` | 400 | **Bad Request**<br/>Largura inválida. A largura máxima do logo deve ser 300px.<br/><small>Invalid image width. Logo image width should be 300px max.</small> |
| <a id="BLP000128"></a>`BLP000128` | 400 | **Bad Request**<br/>Altura inválida. A altura máxima do logo deve ser 100px.<br/><small>Invalid image height. Logo image height should be 100px max.</small> |
| <a id="BLP000129"></a>`BLP000129` | 400 | **Bad Request**<br/>Orientação inválida. A orientação do logo deve ser paisagem e não retrato/quadrado<br/><small>Invalid image orientation. Logo image orientation should be landscape and not portrait/square</small> |
| <a id="BLP000130"></a>`BLP000130` | 400 | **Bad Request**<br/>Falta o arquivo.<br/><small>Missing file.</small> |
| <a id="BLP000131"></a>`BLP000131` | 400 | **Bad Request**<br/>Request sem ocorrências.<br/><small>Request without occurrences.</small> |
| <a id="BLP000132"></a>`BLP000132` | 403 | **Unauthorized**<br/>Occurrence type não permitida.<br/><small>Occurrence type is not allowed.</small> |
| <a id="BLP000134"></a>`BLP000134` | 422 | **Unprocessable Entity**<br/>Nosso número duplicado, {our_number}<br/><small>Our duplicate number, {our_number}</small> |
| <a id="BLP000135"></a>`BLP000135` | 422 | **Unprocessable Entity**<br/>O campo Identificação da Empresa Beneficiária {beneficiary_code} nas linhas de registro (posições 021 a 037) é diferente da identificação da empresa beneficiária {company_code} no cabeçalho (posições 027 a 046).<br/><small>The field Identification of the Beneficiary Institution {beneficiary_code} on the registration lines (positions 021 to 037) is different from the beneficiary company identification {company_code} in the header (positions 027 to 046).</small> |
| <a id="BLP000136"></a>`BLP000136` | 400 | **Invalid FileName**<br/>Nome de arquivo inválido ({cnab_filename}). Favor não utilizar caracteres especiais como '!,@,(,),$' .<br/><small>Invalid filename ({cnab_filename}). Please do not use specials characters like '!,@,(,),$' .</small> |
| <a id="BLP000137"></a>`BLP000137` | 400 | **Bad Request**<br/>Tamanho inválido do código de barras. Código de barras deve possuir 44 dígitos.<br/><small>Invalid barcode length ({barcode_length}). Barcode must be 44 digits.</small> |
| <a id="BLP000138"></a>`BLP000138` | 404 | **Not Found**<br/>Nenhum boleto para baixa automática encontrado<br/><small>Bank Slip for automatic write-off not found</small> |
| <a id="BLP000139"></a>`BLP000139` | 404 | **Not Found**<br/>Não foi possível encontrar a configuração de notificação para os parâmetros enviados.<br/><small>Notification configuration not found for the given parameters.</small> |
| <a id="BLP000140"></a>`BLP000140` | 400 | **Bad Request**<br/>O nome do arquivo CNAB é muito longo para ser salvo no nosso Banco de Dados.<br/><small>The given CNAB filename is too long to be saved in our database.</small> |
| <a id="BLP000141"></a>`BLP000141` | 400 | **Bad Request**<br/>A linha digitável fornecida deve conter somente números.<br/><small>The given digitable_line must have only numbers.</small> |
| <a id="BLP000142"></a>`BLP000142` | 400 | **Bad Request**<br/>Esta linha digitável está fora do comprimento mínimo ou máximo.<br/><small>This digitable line is out of minimum or maximum length.</small> |
| <a id="BLP000143"></a>`BLP000143` | 404 | **Not Found**<br/>Conta não encontrada para a chave {account_key}.<br/><small>Account not found for key {account_key}.</small> |
| <a id="BLP000144"></a>`BLP000144` | 400 | **Bad Request**<br/>Essa linha digitável não é aceita.<br/><small>This digitable line is not accepted.</small> |
| <a id="BLP000145"></a>`BLP000145` | 400 | **Bad Request**<br/>Não é possível gerar PDF a partir de um boleto bancário rejeitado.<br/><small>Cannot generate PDF from a rejected bank slip.</small> |
| <a id="BLP000146"></a>`BLP000146` | 400 | **Bad Request**<br/>Pagamento rejeitado.<br/><small>Payment rejected.</small> |
| <a id="BLP000147"></a>`BLP000147` | 400 | **Bad Request**<br/>Para habilitar o QR Code uma chave pix padrão válida deve ser enviada.<br/><small>To enable QR Code a valid defaul pix key must be send.</small> |
| <a id="BLP000148"></a>`BLP000148` | 400 | **Bad Request**<br/>Conta beneficiária deve ser a mesma da chave pix.<br/><small>Beneficiary account and pix key must match.</small> |
| <a id="BLP000149"></a>`BLP000149` | 400 | **Bad Request**<br/>Carteira {requester_profile_key} deve estar ativa.<br/><small>Requester Profile {requester_profile_key} must be active.</small> |
| <a id="BLP000150"></a>`BLP000150` | 400 | **Bad Request**<br/>Formato de data incorreto, Dever ser do tipo YYYY-MM-DD.<br/><small>Wrong Date format. Format must be YYYY-MM-DD.</small> |
| <a id="BLP000151"></a>`BLP000151` | 400 | **Bad Request**<br/>Custas de cartório deven ser em porcentagem.<br/><small>Protest expense must be percentage.</small> |
| <a id="BLP000152"></a>`BLP000152` | 400 | **Bad Request**<br/>Código de carteira {requester_profile_code}<br/><small>Requester Profile Code {requester_profile_code} already in use</small> |
| <a id="BLP000153"></a>`BLP000153` | 400 | **Bad Request**<br/>{filter_param} deve ter tamanho mínimo de {min_length}<br/><small>{filter_param} must have min length of {min_length}</small> |
| <a id="BLP000154"></a>`BLP000154` | 422 | **Unprocessable Entity**<br/>Erro ao realizar pagamento de arrecadação: {message}<br/><small>Error paying tax collection: {message}</small> |
| <a id="BLP000155"></a>`BLP000155` | 402 | **Bad Request**<br/>Fundos insuficientes para pagamento de boleto<br/><small>Not enough funds for bank-slip payment</small> |
| <a id="BLP000156"></a>`BLP000156` | 400 | **Bad Request**<br/>Use GET /cnab_file/return/{cnab_type}/{requester_profile_code} |
| <a id="BLP000157"></a>`BLP000157` | 400 | **Bad Request**<br/>Parâmetro obrigatório ausente: cnab_type<br/><small>Missing mandatory parameter: cnab_type</small> |
| <a id="BLP000158"></a>`BLP000158` | 400 | **Bad Request**<br/>Chave de emissor de remessa deve ser fornecida. Por favor envie um SELECTED-AGENT ou faça uma requisição interna<br/><small>Remitter key must be provided. Please send SELECTED-AGENT or make an internal request</small> |
| <a id="BLP000159"></a>`BLP000159` | 412 | **Bad Request**<br/>Erro ao gerar {file_type}, usuário com o documento {document_number} não possui endereço cadastrado!<br/><small>Error generating {file_type}, user with document {document_number} does not have a registered address!</small> |
| <a id="BLP000160"></a>`BLP000160` | 422 | **Unprocessable Entity**<br/>Data de vencimento não pode ser depois de 2049-10-13<br/><small>Expiration date cannot be after 2049-10-13</small> |
| <a id="BLP000161"></a>`BLP000161` | 400 | **Bad Request**<br/>Juros diário deve estar no formato 9999999.99<br/><small>Interest Daily Value must match format 9999999.99</small> |
| <a id="BLP000162"></a>`BLP000162` | 400 | **Bad Request**<br/>Valor multa deve estar no formato 9999999.99<br/><small>Fine Percentage Value must match format 9999999.99</small> |
| <a id="BLP000163"></a>`BLP000163` | 400 | **Bad Request**<br/>Valor de Desconto diário deve estar no formato 9999999.99<br/><small>Discount Value must match format 9999999.99</small> |
| <a id="BLP000164"></a>`BLP000164` | 404 | **Not Found**<br/>Pagamento não encontrada para o código de barras {barcode}.<br/><small>Payment entry not found for barcode {barcode}.</small> |
| <a id="BLP000165"></a>`BLP000165` | 400 | **Bad Request**<br/>O pagamento não está pago. Status atual do pagamento: {current_payment_status}.<br/><small>Payment is not paid. Current payment status: {current_payment_status}.</small> |
| <a id="BLP000166"></a>`BLP000166` | 400 | **Bad Request**<br/>Falha ao cancelar pagamento no PCR. Código de barras: {barcode}.<br/><small>Failed to cancel payment in PCR. Barcode: {barcode}.</small> |
| <a id="BLP000167"></a>`BLP000167` | 400 | **Bad Request**<br/>A configuração max_payment_days da carteira deve ser um número inteiro igual ou menor a 360 e diferente de 0<br/><small>Requester max_payment_days must be an integer no greater than 360 and must not be 0.</small> |
| <a id="BLP000168"></a>`BLP000168` | 400 | **Bad Request**<br/>O boleto não está com aviso de pagamento. Status atual do boleto: {bank_slip_status}.<br/><small>Bank slip is not does not have a payment notice. Current bank slip status: {bank_slip_status}.</small> |
| <a id="BLP000169"></a>`BLP000169` | 400 | **Bad Request**<br/>O boleto não possui uma ocorrência de aviso de pagamento confirmada.<br/><small>Bank slip does not have a confirmed payment notice occurrence.</small> |
| <a id="BLP000170"></a>`BLP000170` | 400 | **Bad Request**<br/>Se sobreescrever configurações de interesse estiver ativado, as suas configurações devem ser preenchidas.<br/><small>If override_automatic_bankruptcy_protest_settings is true, bankruptcy protest settings must be filled.</small> |
| <a id="BLP000171"></a>`BLP000171` | 400 | **Bad Request**<br/>Se sobreescrever configurações de multa estiver ativado, as suas configurações devem ser preenchidas.<br/><small>If override_fine_settings is true, bankruptcy protest settings must be filled.</small> |
| <a id="BLP000172"></a>`BLP000172` | 400 | **Bad Request**<br/>Se sobreescrever configurações de baixa automática estiver ativado, as suas configurações devem ser preenchidas.<br/><small>If override_automatic_write_off_settings is true, bankruptcy protest settings must be filled.</small> |
| <a id="BLP000173"></a>`BLP000173` | 400 | **Bad Request**<br/>Se sobreescrever configurações de protesto por falência estiver ativado, as suas configurações devem ser preenchidas.<br/><small>If override_automatic_bankruptcy_protest_settings is true, bankruptcy protest settings must be filled.</small> |
| <a id="BLP000174"></a>`BLP000174` | 400 | **Bad Request**<br/>Se sobreescrever configurações de protesto estiver ativado, as suas configurações devem ser preenchidas.<br/><small>If override_automatic_protest_settings is true, protest settings must be filled.</small> |
| <a id="BLP000175"></a>`BLP000175` | 400 | **Bad Request**<br/>Se sobreescrever configurações de política de impressão estiver ativado, as suas configurações devem ser preenchidas.<br/><small>If override_printing_policy_settings is true, printing policy settings must be filled.</small> |
| <a id="BLP000176"></a>`BLP000176` | 400 | **Bad Request**<br/>Falha ao consultar pagamento no PCR. Código de barras: {barcode}.<br/><small>Failed to consult payment in PCR. Barcode: {barcode}.</small> |
| <a id="BLP000177"></a>`BLP000177` | 400 | **Bad Request**<br/>Propósito não permitido.<br/><small>Purpose not allowed.</small> |
| <a id="BLP000178"></a>`BLP000178` | 400 | **Bad Request**<br/>Não é possível agendar pagamentos para arrecadação<br/><small>It's not possible to schedule payments for tax collection</small> |
| <a id="BLP000179"></a>`BLP000179` | 400 | **Bad Request**<br/>Data de pagamento não pode ser anterior a data de hoje.<br/><small>Payment date can't be before today.</small> |
| <a id="BLP000180"></a>`BLP000180` | 400 | **Bad Request**<br/>Propósito inválido .<br/><small>Invalid purpose.</small> |
| <a id="BLP000181"></a>`BLP000181` | 400 | **Bad Request**<br/>Documento inválido.<br/><small>Invalid guarantor document.</small> |
| <a id="BLP000182"></a>`BLP000182` | 400 | **Bad Request**<br/>Data de validade inválida.<br/><small>Invalid expiration date.</small> |
| <a id="BLP000183"></a>`BLP000183` | 400 | **Bad Request**<br/>Caracter inválido na linha {line}.<br/><small>Invalid character in line {line}.</small> |
| <a id="BLP000184"></a>`BLP000184` | 501 | **Not Implemented**<br/>Recurso disponível apenas em sandbox<br/><small>Resource only available in sandbox</small> |
| <a id="BLP000185"></a>`BLP000185` | 400 | **Invalid Qr Code Type**<br/>O payload de QR Code fornecido não contêm um tipo de Qr Code Válido<br/><small>The Qr Code payload given did not provide a proper Qr Code type</small> |
| <a id="BLP000186"></a>`BLP000186` | 400 | **Invalid Qr Code Format**<br/>O formato do Qr Code é inválido<br/><small>The Qr Code format is invalid</small> |
| <a id="BLP000187"></a>`BLP000187` | 404 | **Not Found**<br/>Pagamento não encontrada para a linha digitável {digitable_line}.<br/><small>Payment entry not found for digitable line {digitable_line}.</small> |
| <a id="BLP000188"></a>`BLP000188` | 400 | **Bad Request**<br/>Não foi possível consultar o boleto neste momento. Por favor, tente novamente em alguns minutos.<br/><small>It was not possible to consult the bank slip at this time. Please try again in a few minutes.</small> |
| <a id="BLP000189"></a>`BLP000189` | 400 | **Bad Request**<br/>Houve um problema ao processar o pagamento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para obter assistência.<br/><small>There was a problem processing the payment. Please verify your information and, if necessary, contact us for assistance.</small> |
| <a id="BLP000190"></a>`BLP000190` | 400 | **Bad Request**<br/>Ciclo de liquidação não encontrado<br/><small>Settlement cycle not found</small> |
| <a id="BLP000191"></a>`BLP000191` | 400 | **Bad Request**<br/>Temporariamente indisponível<br/><small>Temporary unavalilable</small> |
| <a id="BLP000192"></a>`BLP000192` | 400 | **Bad Request**<br/>Genaração de cnab para a carteira em progresso<br/><small>Cnab profile output in progress for requester_profile_code</small> |
| <a id="BLP000193"></a>`BLP000193` | 422 | **Unprocessable Entity**<br/>Carteira {requester_profile_code} está bloqueada por outra ação, por favor tente novamente mais tarde.<br/><small>Requester profile {requester_profile_code} is locked by other action, please try again later.</small> |
| <a id="BLP000194"></a>`BLP000194` | 400 | **Bad Request**<br/>O campo requester_key é obrigatório no corpo da requisição.<br/><small>Field requester_key is required in the request body.</small> |
| <a id="BLP000195"></a>`BLP000195` | 400 | **Bad Request**<br/>O tipo de liquidação do boleto deve ser informado.<br/><small>Bank slip settlement type must be informed.</small> |
| <a id="BLP000196"></a>`BLP000196` | 400 | **Bad Request**<br/>Nome do sacador avalista inválido.<br/><small>Invalid guarantor name.</small> |
| <a id="BLP000197"></a>`BLP000197` | 400 | **Bad Request**<br/>Conta beneficiária não está aberta<br/><small>Beneficiary account is not opened</small> |
| <a id="BLP000198"></a>`BLP000198` | 400 | **Bad Request**<br/>Múltiplas entradas de pagamento encontradas para o código de barras {barcode}.<br/><small>Multiple payment entries found for barcode {barcode}.</small> |
| <a id="BLP000199"></a>`BLP000199` | 400 | **Bad Request**<br/>O valor total do pagamento do boleto é diferente do valor retornado.<br/><small>Bank slip payment total amount is different from the returned amount.</small> |

### GDF — Autenticação e Autorização

28 erros

| Código | HTTP | Mensagem |
|-|-|-|
| <a id="GDF000001"></a>`GDF000001` | 403 | **Permission Validation Error**<br/>Somente usuários master são permitidos<br/><small>Only master user's are allowed</small> |
| <a id="GDF000002"></a>`GDF000002` | 403 | **Permission Validation Error**<br/>Um SELECTED-AGENT deve ser fornecido<br/><small>A SELECTED-AGENT must be provided</small> |
| <a id="GDF000003"></a>`GDF000003` | 400 | **Bad Request**<br/>Nenhuma chave de API do cliente recebida<br/><small>No API Client Key received</small> |
| <a id="GDF000004"></a>`GDF000004` | 400 | **Bad Request**<br/>Corpo da request vazio<br/><small>Empty body received</small> |
| <a id="GDF000005"></a>`GDF000005` | 400 | **Bad Request**<br/>Cliente da API já criado para esta person_key<br/><small>API Client already created for this person_key</small> |
| <a id="GDF000006"></a>`GDF000006` | 400 | **Bad Request**<br/>allowed_endpoint duplicado<br/><small>Duplicated allowed_endpoint provided</small> |
| <a id="GDF000007"></a>`GDF000007` | 404 | **Not Found**<br/>Nenhuma ClientIntegration encontrada para client_integration_key: {client_integration_key}.<br/><small>No ClientIntegration found for client_integration_key: {client_integration_key} .</small> |
| <a id="GDF000008"></a>`GDF000008` | 400 | **Bad Request**<br/>Uma client_integration_key deve ser fornecida<br/><small>A client_integration_key must be provided</small> |
| <a id="GDF000009"></a>`GDF000009` | 400 | **Bad Request**<br/>Uma ação deve ser fornecida<br/><small>A action must be provided</small> |
| <a id="GDF000010"></a>`GDF000010` | 400 | **Bad Request**<br/>Ação não existe ({action_name}).<br/><small>Action doesnt exist ({action_name}).</small> |
| <a id="GDF000011"></a>`GDF000011` | 404 | **Not Found**<br/>Nenhuma ClientIntegration encontrada para client_integration_key / allowed_endpoint_key: {client_integration_key} / {allowed_endpoint_key}.<br/><small>No ClientIntegration found for client_integration_key / allowed_endpoint_key: {client_integration_key} / {allowed_endpoint_key}.</small> |
| <a id="GDF000012"></a>`GDF000012` | 404 | **Not Found**<br/>Nenhuma AllowedEndpoint encontrada para client_integration_key / allowed_endpoint_key: {client_integration_key} / {allowed_endpoint_key}.<br/><small>No AllowedEndpoint found for client_integration_key / allowed_endpoint_key: {client_integration_key} / {allowed_endpoint_key}.</small> |
| <a id="GDF000013"></a>`GDF000013` | 400 | **Bad Request**<br/>Uma chave allowed_endpoint_key deve ser fornecida<br/><small>A allowed_endpoint_key must be provided</small> |
| <a id="GDF000014"></a>`GDF000014` | 401 | **QI Unauthenticated**<br/>Por favor forneça credenciais válidas como parte da request. (Documentação: https://docs.qitech.com.br) Detalhes: {details_br}<br/><small>Please provide valid credentials as part of the request. (Documentation: https://docs.qitech.com.br) Details: {details}</small> |
| <a id="GDF000015"></a>`GDF000015` | 400 | **Bad Request**<br/>Por favor forneça uma chave pública válida<br/><small>Please provide a valid client_public_key</small> |
| <a id="GDF000016"></a>`GDF000016` | 400 | **Bad Request**<br/>Erro ao decodificar o JSON do corpo da requisição. Por favor verifique se o corpo é válido. Detalhes: {json_ex}<br/><small>Error while decoding request's JSON body. Please verify if body is valid. Details: {json_ex}</small> |
| <a id="GDF000017"></a>`GDF000017` | 400 | **Bad Request**<br/>Valor inválido ({info}).<br/><small>Invalid Value ({info}).</small> |
| <a id="GDF000018"></a>`GDF000018` | 404 | **Not Found**<br/>Nenhuma ClientIntegration encontrada para api_client_key: {api_client_key}.<br/><small>No ClientIntegration found for api_client_key: {api_client_key}.</small> |
| <a id="GDF000019"></a>`GDF000019` | 400 | **Bad Request**<br/>Mapeamento ainda inexistente para request_type: '{request_type}'.<br/><small>Informed request_type: '{request_type}' has not been mapped yet.</small> |
| <a id="GDF000020"></a>`GDF000020` | 500 | **Internal Error**<br/>Account Key não pode ser nulo quando solicitar uma inclusão de chave.<br/><small>Account Key can't be null when including pix key.</small> |
| <a id="GDF000021"></a>`GDF000021` | 500 | **Internal Error**<br/>Falha na requisição para autorização de SCR.<br/><small>Failed to request SCR authorization.</small> |
| <a id="GDF000022"></a>`GDF000022` | 400 | **Bad Request**<br/>Mapeamento ainda inexistente para request_type: '{request_type}'.<br/><small>Informed request_type: '{request_type}' has not been mapped yet.</small> |
| <a id="GDF000023"></a>`GDF000023` | 401 | **Unauthorized**<br/>SSL validation error<br/><small>Error na verificação SSL</small> |
| <a id="GDF000024"></a>`GDF000024` | 400 | **Bad Request**<br/>Error at client webhook endpoint<br/><small>Error no endpoint de webhook do cliente</small> |
| <a id="GDF000025"></a>`GDF000025` | 403 | **Permission Validation Error**<br/>Somente os ambientes de desenvolvimento e de sandbox são permitidos para realizar requisições na Mock API.<br/><small>Only sandbox and dev environment are allowed to request Mock API</small> |
| <a id="GDF000026"></a>`GDF000026` | 400 | **Bad Request**<br/>Versão do método de assinatura não permitida<br/><small>Signature method version not allowed</small> |
| <a id="GDF000027"></a>`GDF000027` | 404 | **Not Found**<br/>Nenhuma ClientIntegration encontrada para a person_key: {person_key}.<br/><small>No ClientIntegration found for person_key: {person_key}.</small> |
| <a id="GDF000028"></a>`GDF000028` | 404 | **Not Found**<br/>A requisição precisa de um body, mesmo que um vazio como: '{}'.<br/><small>The request needs a body, even an empty one like: '{}'.</small> |

### OBD — Cadastro de Cliente

88 erros

| Código | HTTP | Mensagem |
|-|-|-|
| <a id="OBD000001"></a>`OBD000001` | 400 | **Bad Request**<br/>Use DELETE /bank_account/{bank_account_key} com um agente válido<br/><small>Use DELETE /bank_account/{bank_account_key} with a valid agent</small> |
| <a id="OBD000002"></a>`OBD000002` | 404 | **Not Found**<br/>Conta não encontrada<br/><small>Bank account not found</small> |
| <a id="OBD000003"></a>`OBD000003` | 400 | **Bad Request**<br/>Use POST /bank_account/ com um agente válido<br/><small>Use POST /bank_account/ with a valid agent</small> |
| <a id="OBD000004"></a>`OBD000004` | 404 | **Not Found**<br/>Não existe pessoa com número de documento {document_number}<br/><small>There is no person with document number {document_number}</small> |
| <a id="OBD000005"></a>`OBD000005` | 400 | **Bad Request**<br/>Use GET /cnae/{cnae_code} |
| <a id="OBD000006"></a>`OBD000006` | 400 | **Bad Request**<br/>O código Cnae deve ter 7 dígitos e não conter caracteres especiais<br/><small>Cnae code must be without special characters and must have 7 digits</small> |
| <a id="OBD000007"></a>`OBD000007` | 404 | **Not Found**<br/>Cnae não encontrado.<br/><small>Cnae was not found.</small> |
| <a id="OBD000008"></a>`OBD000008` | 404 | **Not Found**<br/>Proprietário (owner_person) não encontrado.<br/><small>Owner Person not found.</small> |
| <a id="OBD000009"></a>`OBD000009` | 404 | **Not Found**<br/>Draft person não encontrada para {name}<br/><small>Draft person not found for {name}</small> |
| <a id="OBD000010"></a>`OBD000010` | 400 | **Bad Request**<br/>O fundo já existe, use PUT /fund/{fund_key}.<br/><small>Fund already exists, please use PUT /fund/{fund_key}.</small> |
| <a id="OBD000011"></a>`OBD000011` | 400 | **Bad Request**<br/>custodian_person não encontrado.<br/><small>Custodian Person not found.</small> |
| <a id="OBD000012"></a>`OBD000012` | 400 | **Bad Request**<br/>custodian_person não é válido.<br/><small>Custodian Person sent is not a custodian.</small> |
| <a id="OBD000013"></a>`OBD000013` | 400 | **Bad Request**<br/>Administrador não encontrado<br/><small>Administrator Person not found.</small> |
| <a id="OBD000014"></a>`OBD000014` | 400 | **Bad Request**<br/>administrador_person não é um administrador.<br/><small>Administrator Person sent is not a administrator.</small> |
| <a id="OBD000015"></a>`OBD000015` | 400 | **Bad Request**<br/>Fundo não encontrado.<br/><small>Fund not found.</small> |
| <a id="OBD000016"></a>`OBD000016` | 400 | **Bad Request**<br/>O número do documento do fundo enviado deve corresponder a um fundo existente. Enviado: {fund_document_number}.<br/><small>Fund document_number sent must match an existing fund. Sent: {fund_document_number}.</small> |
| <a id="OBD000017"></a>`OBD000017` | 400 | **Bad Request**<br/>O número do documento do fundo enviado deve corresponder ao fundo existente. Enviado: {fund_document_number}. Experado: {document_number}.<br/><small>Fund document_number sent must match existing fund. Sent: {fund_document_number}. Expected: {document_number}.</small> |
| <a id="OBD000018"></a>`OBD000018` | 400 | **Bad Request**<br/>A pessoa já tem qualificação {qualification_enum}.<br/><small>Person already has {qualification_enum} qualification.</small> |
| <a id="OBD000019"></a>`OBD000019` | 404 | **Not Found**<br/>Pessoa não encontrada.<br/><small>Person not found</small> |
| <a id="OBD000020"></a>`OBD000020` | 404 | **Not Found**<br/>Empresa ou agente não encontrado<br/><small>Company or Agent not found</small> |
| <a id="OBD000021"></a>`OBD000021` | 400 | **Bad Request**<br/>Use GET /person/(person_document) ou /person?document_number?(document_number)<br/><small>Use GET /person/(person_document) or /person?document_number?(document_number)</small> |
| <a id="OBD000022"></a>`OBD000022` | 400 | **Bad Request**<br/>E-mail ou documento duplicado<br/><small>Duplicated document/email</small> |
| <a id="OBD000023"></a>`OBD000023` | 500 | **Internal Error**<br/>Erro ao criar usuário: {document_number}. Falha ao enviar email de boas-vindas<br/><small>Error creating user:{document_number}. Fail to send welcome email</small> |
| <a id="OBD000024"></a>`OBD000024` | 404 | **Not Found**<br/>Agente não encontrado<br/><small>POST Agent Not Found</small> |
| <a id="OBD000025"></a>`OBD000025` | 400 | **Bad Request**<br/>Documento deve ser CPF ou CNPJ<br/><small>First document must be CPF or CNPJ</small> |
| <a id="OBD000026"></a>`OBD000026` | 400 | **Bad Request**<br/>Use POST /person |
| <a id="OBD000027"></a>`OBD000027` | 400 | **Bad Request**<br/>Conflito com chave e tipo de pessoa<br/><small>Conflict with person key and person type</small> |
| <a id="OBD000028"></a>`OBD000028` | 400 | **Bad Request**<br/>Use PATCH /person/{person_key} |
| <a id="OBD000029"></a>`OBD000029` | 400 | **Bad Request**<br/>Use GET /person_qualification/{qualification} |
| <a id="OBD000030"></a>`OBD000030` | 400 | **Bad Request**<br/>Use PUT /person_qualification |
| <a id="OBD000031"></a>`OBD000031` | 400 | **Bad Request**<br/>A pessoa não tem qualificação {qualification_enum}.<br/><small>Person does not have {qualification_enum} qualification.</small> |
| <a id="OBD000032"></a>`OBD000032` | 400 | **Bad Request**<br/>Use DELETE /person_qualification |
| <a id="OBD000033"></a>`OBD000033` | 400 | **Bad Request**<br/>Pessoa física não encontrada<br/><small>Natural person not found</small> |
| <a id="OBD000034"></a>`OBD000034` | 400 | **Bad Request**<br/>Pessoa jurídica não encontrada<br/><small>Legal person not found</small> |
| <a id="OBD000035"></a>`OBD000035` | 400 | **Bad Request**<br/>Dados profissionais já existem<br/><small>Professional data already exists</small> |
| <a id="OBD000036"></a>`OBD000036` | 400 | **Bad Request**<br/>Dados profissionais não encontrados<br/><small>Professional data not found</small> |
| <a id="OBD000037"></a>`OBD000037` | 400 | **Bad Request**<br/>Use POST /professional_data |
| <a id="OBD000038"></a>`OBD000038` | 400 | **Bad Request**<br/>Você não pode se remover<br/><small>You cannot remove yourself</small> |
| <a id="OBD000039"></a>`OBD000039` | 400 | **Bad Request**<br/>Atributo person_key ausente no corpo da request<br/><small>Missing attribute person_key in request body</small> |
| <a id="OBD000040"></a>`OBD000040` | 400 | **Bad Request**<br/>Você deve fornecer um nome.<br/><small>You must provide a name.</small> |
| <a id="OBD000041"></a>`OBD000041` | 400 | **Bad Request**<br/>Você deve fornecer um nome e um número de documento para fazer a verificação do PEP.<br/><small>You must provide a name and a document number to do the PEP check.</small> |
| <a id="OBD000042"></a>`OBD000042` | 500 | **Internal Error**<br/>KeyCloak não retornou o cabeçalho do local<br/><small>KeyCloak did not returned location header</small> |
| <a id="OBD000043"></a>`OBD000043` | 400 | **Bad Request**<br/>Qualificação não existe<br/><small>Qualification does not exist</small> |
| <a id="OBD000044"></a>`OBD000044` | 400 | **Bad Request**<br/>Pessoa fisica ou juridica nao encontradas.<br/><small>Could not find either legal nor natural person</small> |
| <a id="OBD000045"></a>`OBD000045` | 400 | **Bad Request**<br/>Atributo owner_person_key ausente<br/><small>Missing attribute owner_person_key</small> |
| <a id="OBD000046"></a>`OBD000046` | 400 | **Bad Request**<br/>Professional data não está ativo<br/><small>Professional data is not active</small> |
| <a id="OBD000047"></a>`OBD000047` | 403 | **Unauthorized**<br/>Usuário não tem permissão para adicionar ou modificar usuários<br/><small>User does not have permission to add or modify users to this person</small> |
| <a id="OBD000048"></a>`OBD000048` | 400 | **Bad Request**<br/>A chave de usuário deve ser enviada.<br/><small>Client Key must be provided.</small> |
| <a id="OBD000049"></a>`OBD000049` | 404 | **Bad Request**<br/>Client não encontrado<br/><small>Client not found.</small> |
| <a id="OBD000050"></a>`OBD000050` | 400 | **Bad Request**<br/>Parâmetro client_key não permitido no método POST<br/><small>Parameter client_key not allowed no POST method</small> |
| <a id="OBD000051"></a>`OBD000051` | 400 | **Bad Request**<br/>Person não está ativa<br/><small>Person is not active</small> |
| <a id="OBD000052"></a>`OBD000052` | 400 | **Bad Request**<br/>document_type: {document_type} não permitido para person {person_type}<br/><small>document_type: {document_type} not allowed for {person_type} person</small> |
| <a id="OBD000053"></a>`OBD000053` | 400 | **Bad Request**<br/>document_type: {document_type} incorreto utilizado no documento: {document_field_name}<br/><small>Wrong document_type: {document_type} used in document: {document_field_name}</small> |
| <a id="OBD000054"></a>`OBD000054` | 400 | **Bad Request**<br/>Cliente já registrado para o document_number: {document_number}. use o método PATCH para atualizar um cliente<br/><small>Client already registered for document_number: {document_number}. Use PATCH method to update a client</small> |
| <a id="OBD000055"></a>`OBD000055` | 404 | **Bad Request**<br/>Não foi possíel encontrar nenhum resultado com os parâmetros eviados.<br/><small>Can not find any result for search parameters</small> |
| <a id="OBD000056"></a>`OBD000056` | 403 | **Unauthorized**<br/>Usuário não tem permissão para adicionar ou modificar clientes<br/><small>User does not have permission to add or modify clients to this person</small> |
| <a id="OBD000057"></a>`OBD000057` | 403 | **Bad Request**<br/>O cliente {document_number} está bloqueado, favor contactar o suporte.<br/><small>Client {document_number} is blocked, please contact support.</small> |
| <a id="OBD000058"></a>`OBD000058` | 403 | **Bad Request**<br/>Ação não implementada.<br/><small>Action not implemented.</small> |
| <a id="OBD000059"></a>`OBD000059` | 400 | **Bad Request**<br/>document_key duplicada no company representative com document_number: {document_number}<br/><small>Duplicated document_key on company representative with document_number: {document_number}</small> |
| <a id="OBD000060"></a>`OBD000060` | 400 | **Bad Request**<br/>company_representative duplicado recebido<br/><small>Duplicated company_representative received</small> |
| <a id="OBD000061"></a>`OBD000061` | 400 | **Bad Request**<br/>document_key duplicada nos attached_documents do client<br/><small>Duplicated document_key on client's attached_documents</small> |
| <a id="OBD000062"></a>`OBD000062` | 400 | **Bad Request**<br/>filtro order_by permitido para os seguintes valores: {order_by_list}<br/><small>order_by filter must be one of: {order_by_list}</small> |
| <a id="OBD000063"></a>`OBD000063` | 401 | **Unauthorized**<br/>reset de senha não autorizado fora do app<br/><small>password reset not authorized out of app</small> |
| <a id="OBD000064"></a>`OBD000064` | 400 | **Bad Request**<br/>professional data já está ativo<br/><small>professional data is already active</small> |
| <a id="OBD000065"></a>`OBD000065` | 400 | **Bad Request**<br/>Você deve fornecer um email.<br/><small>You must provide an email.</small> |
| <a id="OBD000066"></a>`OBD000066` | 412 | **Precondition Failed**<br/>OwnerPerson deve pertencer ao Domain da QI SCD<br/><small>OwnerPerson must be in the QI SCD Domain.</small> |
| <a id="OBD000067"></a>`OBD000067` | 400 | **Bad Request**<br/>Domínio já existe para OwnerPerson.<br/><small>Domain already exists for owner person.</small> |
| <a id="OBD000068"></a>`OBD000068` | 404 | **Not Found**<br/>Domínio não encontrado.<br/><small>Domain not found</small> |
| <a id="OBD000069"></a>`OBD000069` | 400 | **Bad Request**<br/>Apenas pessoas jurídicas podem ter domínios.<br/><small>Only legal person may own domains.</small> |
| <a id="OBD000070"></a>`OBD000070` | 400 | **Bad Request**<br/>Tipo errado para {variable}. Deve ser {type}<br/><small>Wrong type for {variable}. Must be {type}</small> |
| <a id="OBD000071"></a>`OBD000071` | 400 | **Bad Request**<br/>Você deve fornecer um email ou um número de telefone.<br/><small>You must provide an email or a phone number.</small> |
| <a id="OBD000072"></a>`OBD000072` | 400 | **Bad Request**<br/>Use owner_person_key ou domain_key na busca.<br/><small>Use either owner_person_key or domain_key in search.</small> |
| <a id="OBD000073"></a>`OBD000073` | 403 | **Unauthorized**<br/>Usuário não tem permissão para adicionar ou modificar pessoas a este domínio.<br/><small>User does not have permission to add or modify persons to this domain</small> |
| <a id="OBD000075"></a>`OBD000075` | 400 | **Bad Request**<br/>Pessoas físicas e jurídicas deves pertencer ao mesmo domínio.<br/><small>Natural and legal person must be in the same domain.</small> |
| <a id="OBD000076"></a>`OBD000076` | 400 | **Bad Request**<br/>Uma professional_data_key deve ser fornecida.<br/><small>A professional_data_key must be provided.</small> |
| <a id="OBD000077"></a>`OBD000077` | 400 | **Bad Request**<br/>Permissão inválida para pessoa juurídica, enviado {role}<br/><small>Invalid legal person role sent {role}.</small> |
| <a id="OBD000078"></a>`OBD000078` | 400 | **Bad Request**<br/>Sempre deve existir ao menos um administrador de conta<br/><small>There must always be an account administrator left</small> |
| <a id="OBD000079"></a>`OBD000079` | 400 | **Bad Request**<br/>Endpoint utilizado apenas para atualizações de pessoas fisicas<br/><small>Endpoint used for natural person updates only</small> |
| <a id="OBD000080"></a>`OBD000080` | 400 | **Bad Request**<br/>Número de telefone inválido<br/><small>Invalid phone number</small> |
| <a id="OBD000081"></a>`OBD000081` | 400 | **Bad Request**<br/>E-mail inválido<br/><small>Invalid e-mail</small> |
| <a id="OBD000082"></a>`OBD000082` | 400 | **Bad Request**<br/>Pessoa física não possui usuários autorizados.<br/><small>Natural person does not have allowed users.</small> |
| <a id="OBD000083"></a>`OBD000083` | 404 | **Not found**<br/>Dados proficionais não encontrados.<br/><small>Professional data not found.</small> |
| <a id="OBD000084"></a>`OBD000084` | 400 | **Bad Request**<br/>O usuário open finance já foi validado.<br/><small>The openfinance user is already validated.</small> |
| <a id="OBD000085"></a>`OBD000085` | 400 | **Bad Request**<br/>Método permitido apenas para usuários de domain.<br/><small>Method only allowed for domain users.</small> |
| <a id="OBD000086"></a>`OBD000086` | 400 | **Bad Request**<br/>Dados recusados.<br/><small>Reproved person data.</small> |
| <a id="OBD000087"></a>`OBD000087` | 400 | **Requester Configuration Already Exists**<br/>Requester Configuration já existe para essa requester_key.<br/><small>Requester Configuration already exists for this requester_key.</small> |
| <a id="OBD000088"></a>`OBD000088` | 400 | **Invalid Requester Configuration Info**<br/>O formato de configuração enviado não é válido.<br/><small>The configuration format sent is not valid.</small> |
| <a id="OBD000089"></a>`OBD000089` | 404 | **Requester Configuration not found**<br/>Não há Requester Configuration para a requester_key enviada<br/><small>There is no Requester Configuration attributed to requester_key given</small> |

### PMB — Notificações

34 erros

| Código | HTTP | Mensagem |
|-|-|-|
| <a id="PMB000001"></a>`PMB000001` | 403 | **Permission Validator Error**<br/>Somente usuários master estão autorizados<br/><small>Only master user's are allowed</small> |
| <a id="PMB000002"></a>`PMB000002` | 403 | **Permission Validator Error**<br/>Um SELECTED-AGENT deve ser fornecido<br/><small>A SELECTED-AGENT must be provided</small> |
| <a id="PMB000003"></a>`PMB000003` | 404 | **Not Found**<br/>Nenhum callback encontrado para callback_key: {callback_key}.<br/><small>No callback found for callback_key: {callback_key} .</small> |
| <a id="PMB000004"></a>`PMB000004` | 400 | **Bad Request**<br/>O event_type solicitado ({callback_event_name}) não existe.<br/><small>The requested event_type ({callback_event_name}) does not exists.</small> |
| <a id="PMB000005"></a>`PMB000005` | 400 | **Bad Request**<br/>Não foi possível executar a ação de nova tentativa com o callback_status atual ({callback_status_enumerator})<br/><small>Unable to perform retry action with current callback_status ({callback_status_enumerator})</small> |
| <a id="PMB000006"></a>`PMB000006` | 400 | **Bad Request**<br/>Já existe uma NotificationConfiguration para event_type: {event_type}.<br/><small>A NotificationConfiguration already exists for event_type: {event_type} .</small> |
| <a id="PMB000007"></a>`PMB000007` | 400 | **Bad Request**<br/>Nenhuma NotificationConfiguration encontrada para event_type: {event_type}.<br/><small>No NotificationConfiguration found for event_type: {event_type} .</small> |
| <a id="PMB000008"></a>`PMB000008` | 404 | **Not Found**<br/>Evento não encontrado (event_key = {event_key})<br/><small>Event not found (event_key = {event_key})</small> |
| <a id="PMB000009"></a>`PMB000009` | 400 | **Bad Request**<br/>Evento já existe (event_key = {event_key})<br/><small>Event already exists (event_key: {event_key})</small> |
| <a id="PMB000010"></a>`PMB000010` | 400 | **Bad Request**<br/>Já existe uma NotificationConfiguration para person_key: {person_key} / event_type: {event_type} .<br/><small>A NotificationConfiguration already exists for person_key: {person_key} / event_type: {event_type} .</small> |
| <a id="PMB000011"></a>`PMB000011` | 400 | **Bad Request**<br/>Origem '{enumerador}' já existe.<br/><small>Origin '{enumerator}' already exists.</small> |
| <a id="PMB000012"></a>`PMB000012` | 400 | **Bad Request**<br/>EventType '{enumerator}' já existe.<br/><small>EventType '{enumerator}' already exists.</small> |
| <a id="PMB000013"></a>`PMB000013` | 400 | **Bad Request**<br/>Uma person_key deve ser fornecida<br/><small>A person_key must be provided</small> |
| <a id="PMB000014"></a>`PMB000014` | 400 | **Bad Request**<br/>Já existe uma CallbackConfiguration para person_key: {person_key}.<br/><small>A CallbackConfiguration already exists for person_key: {person_key} .</small> |
| <a id="PMB000015"></a>`PMB000015` | 404 | **Not Found**<br/>Nenhuma cCallbackConfiguration encontrada para person_key: {person_key}.<br/><small>No CallbackConfiguration found for person_key: {person_key} .</small> |
| <a id="PMB000016"></a>`PMB000016` | 404 | **Not Found**<br/>A URL do CallbackConfiguration precisa estar em https.<br/><small>The CallbackConfiguration URL must be in https.</small> |
| <a id="PMB000017"></a>`PMB000017` | 404 | **Not Found**<br/>Os Headers do CallbackConfiguration precisa ser um dicionário, ou um objeto JSON.<br/><small>The CallbackConfiguration Headers must be a dict or a json object</small> |
| <a id="PMB000018"></a>`PMB000018` | 404 | **Not Found**<br/>SMS Try não encontrado pela chave externa<br/><small>SMS Try not found by external key</small> |
| <a id="PMB000019"></a>`PMB000019` | 400 | **Bad Request**<br/>A origem solicitada ({origin}) não existe.<br/><small>The requested origin ({origin}) does not exists.</small> |
| <a id="PMB000020"></a>`PMB000020` | 400 | **Bad Request**<br/>A {invalid_uuid} enviada não é válida<br/><small>The {invalid_uuid} sent is not valid</small> |
| <a id="PMB000021"></a>`PMB000021` | 400 | **Bad Request**<br/>O tipo de template {enumerator} enviado não é válida<br/><small>The template type {enumerator} is not valid</small> |
| <a id="PMB000022"></a>`PMB000022` | 400 | **Bad Request**<br/>O tipo de evento {enumerator} enviado não é válida<br/><small>The event type {enumerator} is not valid</small> |
| <a id="PMB000023"></a>`PMB000023` | 400 | **Bad Request**<br/>Já existe um template configuration para essa pessoa e event type<br/><small>Already exists an template configuration to this person and event type</small> |
| <a id="PMB000024"></a>`PMB000024` | 404 | **Not found**<br/>Configuração de template não encontrada<br/><small>Template configuration not found</small> |
| <a id="PMB000025"></a>`PMB000025` | 404 | **Not found**<br/>Template não encontrado<br/><small>Template not found</small> |
| <a id="PMB000026"></a>`PMB000026` | 400 | **Invalid notification for event type**<br/>Método de notificação inválido para tipo de evento<br/><small>Invalid notification method for event type</small> |
| <a id="PMB000027"></a>`PMB000027` | 409 | **Conflict**<br/>Configuração de notificação já existe para essa pessoa e tipo de evento<br/><small>Notification configuration already exists for this person and event type</small> |
| <a id="PMB000028"></a>`PMB000028` | 404 | **Not found**<br/>Configuração de notificação já não encontrada<br/><small>Notification configuration not found</small> |
| <a id="PMB000029"></a>`PMB000029` | 403 | **Forbidden**<br/>Callback não pertence a este usuário<br/><small>User does not own this callback</small> |
| <a id="PMB000030"></a>`PMB000030` | 429 | **Too Many Requests**<br/>O limiar de SMS por segundo foi atingido.<br/><small>SMS per second threshold has been reached.</small> |
| <a id="PMB000031"></a>`PMB000031` | 400 | **Bad Request**<br/>Uma client_integration_key deve ser fornecida<br/><small>A client_integration_key must be provided</small> |
| <a id="PMB000032"></a>`PMB000032` | 400 | **Bad Request**<br/>O intervalo de tempo selecionado deve ter no máximo 14 dias<br/><small>Selected timeframe should have a maximum of 14 days</small> |
| <a id="PMB000033"></a>`PMB000033` | 400 | **Bad Request**<br/>'template_id' deve ser um inteiro<br/><small>'template_id' must be an integer</small> |
| <a id="PMB000034"></a>`PMB000034` | 400 | **Bad Request**<br/>Este recurso está temporariamente indisponível<br/><small>This resource is temporary unavailable</small> |

### PXT — Pix

185 erros

| Código | HTTP | Mensagem |
|-|-|-|
| <a id="PXT000002"></a>`PXT000002` | - | **Person is not Account Owner**<br/>A pessoa {person_key} não é dona da conta<br/><small>Person {person_key} is not account owner</small> |
| <a id="PXT000003"></a>`PXT000003` | - | **Account is Closed**<br/>Conta {account_key} está fechada<br/><small>Account {account_key} is closed</small> |
| <a id="PXT000004"></a>`PXT000004` | - | **Account not found**<br/>Conta não encontrada para: {account_datum}<br/><small>Account not found for: {account_datum}</small> |
| <a id="PXT000005"></a>`PXT000005` | - | **Account not found**<br/>Conta não encontrada para chave pix: {pix_key}<br/><small>Account not found for pix key: {pix_key}</small> |
| <a id="PXT000006"></a>`PXT000006` | - | **Account not found**<br/>Chave de identificação da conta não foi fornecida<br/><small>Account was not provided for this query</small> |
| <a id="PXT000008"></a>`PXT000008` | - | **Invalid Permission**<br/>Pessoa {person_key} não tem permissões de administrador para a conta {account_key}<br/><small>Person {person_key} does not have administration roles for account {account_key}</small> |
| <a id="PXT000009"></a>`PXT000009` | - | **Person Not Found**<br/>Pessoa com número de documento {person_document_number} não encontrada<br/><small>Person with document number {person_document_number} not found</small> |
| <a id="PXT000010"></a>`PXT000010` | - | **Account is Blocked**<br/>Conta {account_key} está bloqueada<br/><small>Account {account_key} is blocked</small> |
| <a id="PXT000011"></a>`PXT000011` | - | **Account Type Mismatch**<br/>O tipo de conta fornecido não condiz com o registrado<br/><small>Given account type does not match one registered</small> |
| <a id="PXT000012"></a>`PXT000012` | - | **Invalid Document Number**<br/>CPF/CNPJ {document_number} fornecido não é valido<br/><small>Given {document_number} document number is invalid</small> |
| <a id="PXT0000126"></a>`PXT0000126` | - | **Error on qr code decode**<br/>Houve um erro ao decodificar o qr code<br/><small>There was an error on decode qr code</small> |
| <a id="PXT0000127"></a>`PXT0000127` | - | **Invalid Reversal Reason**<br/>Razão de reversão {reversal_reason} não é válida<br/><small>Reversal reason {reversal_reason} is not valid</small> |
| <a id="PXT000013"></a>`PXT000013` | - | **Account Validation Failure**<br/>Validação da conta para o end_to_end_id recebido não é válida<br/><small>Account validation for received end_to_end_id is not valid</small> |
| <a id="PXT000014"></a>`PXT000014` | - | **Target Account mismatch**<br/>Dados da conta de destino recebida não corresponde à conta validada<br/><small>Received target account data doesn</small> |
| <a id="PXT000015"></a>`PXT000015` | - | **Reversal date expired**<br/>A data de criação da transação original é mais antiga que 90 dias<br/><small>Reversal original transaction is older than 90 days</small> |
| <a id="PXT000016"></a>`PXT000016` | - | **Reversal Account Flow Mismatch**<br/>O fluxo de contas de destino e de origem não correspondem ao da transação original<br/><small>Reversal account flow does not match original pix transfer</small> |
| <a id="PXT000017"></a>`PXT000017` | - | **Reversal Too Great**<br/>A soma das transações de devolução ultrapassam o valor da transação pix original<br/><small>Reversal transfers sum amount surpasses that of original pix transfer</small> |
| <a id="PXT000018"></a>`PXT000018` | - | **Reversal Original Transfer not Found**<br/>Transferência original da devolução não foi encontrada<br/><small>Reversal original pix transfer not found</small> |
| <a id="PXT000019"></a>`PXT000019` | - | **Chargeback Validation Failure**<br/>Os valores da atual devolução não correspondem com aqueles das validação<br/><small>Previously done validation values do match with incoming chargeback</small> |
| <a id="PXT000020"></a>`PXT000020` | - | **Incoming PIX Validation Not Found**<br/>Não se encontrou validação anterior para o id ponta-a-ponta provido<br/><small>No previously done validation was found for given end to end id</small> |
| <a id="PXT000021"></a>`PXT000021` | - | **Incoming Validation Already Done**<br/>A validação para o id ponta a ponta {end_to_end_id} já foi feita<br/><small>There</small> |
| <a id="PXT000022"></a>`PXT000022` | - | **Wrong ISPB**<br/>ISPB é diferente de 32402502<br/><small>ISPB is different from 32402502</small> |
| <a id="PXT000023"></a>`PXT000023` | - | **Outgoing PIX Transfer Not Found**<br/>Transferência PIX de saída com chave {pix_transfer_key} não foi encontrada<br/><small>Pix transfer key {pix_transfer_key} was not found</small> |
| <a id="PXT000024"></a>`PXT000024` | - | **PIX Transfer Not Pending Confirmation**<br/>Transferência PIX {pix_transfer_key} não está aguardando confirmação<br/><small>Pix transfer {pix_transfer_key} is not pending confirmation</small> |
| <a id="PXT000025"></a>`PXT000025` | - | **Invalid pix transfer key**<br/>Transferência PIX {pix_transfer_key} não está aguardando confirmação ou não existe<br/><small>Pix transfer {pix_transfer_key} is not pending confirmation or does not exist</small> |
| <a id="PXT000026"></a>`PXT000026` | - | **Search Params Error**<br/>Valor inválido para parâmetros de página ou tamanho de página<br/><small>Invalid integer value for page or size querystring parameters</small> |
| <a id="PXT000027"></a>`PXT000027` | - | **Invalid Permission**<br/>Pessoa selecionada não tem credencial de administrador<br/><small>Selected Person does not have administration roles</small> |
| <a id="PXT000028"></a>`PXT000028` | - | **Account Key can not be null when search for config fees**<br/>A chave de conta não pode ser nula quando buscar por configurações de tarifa<br/><small>Account key can not be null when search for config fees</small> |
| <a id="PXT000029"></a>`PXT000029` | - | **Invalid Value for Enumerator Type**<br/>Valor inválido {value} para o tipo de enumerador {enumerator}<br/><small>Invalid value {value} used for enumerator type {enumerator}</small> |
| <a id="PXT000030"></a>`PXT000030` | - | **To update or delete a fee configuration must be provided a valid fee ID**<br/>Para atualizar ou remover uma configuração de tarifa deve ser fornecido um ID válido. ID fornecido: {identification}<br/><small>To update or delete a fee configuration must be provided a valid fee ID. ID provided: {identification}</small> |
| <a id="PXT000031"></a>`PXT000031` | - | **Fee configuration already exists**<br/>Configuração de tarifa já existe para conta {person_owner_type} com: finalidade= {purpose} e {transfer_type}. Por favor utilize o update<br/><small>Fee configuration already exists for {person_owner_type} account with: purpose= {purpose} and {transfer_type}. Please use update</small> |
| <a id="PXT000032"></a>`PXT000032` | - | **Unable To Delete Default Configuration**<br/>Não é permitido deletar uma configuração default. Por favor utilize o update<br/><small>Unable To Delete Default Configuration. Please use update</small> |
| <a id="PXT000033"></a>`PXT000033` | - | **Target Account Must Not Be Source Account**<br/>A conta de destino não pode ser a conta de origem<br/><small>Target Account Must Not Be Source Account</small> |
| <a id="PXT000034"></a>`PXT000034` | - | **Account Key Must Not Be Null**<br/>É necessário definir uma chave de conta para definir uma configuração de tarifa para a mesma<br/><small>You Need To Define An Account Key To Create A Fee Configuration</small> |
| <a id="PXT000035"></a>`PXT000035` | - | **Limit configuration already exists**<br/>Configuração de limite já existe para conta {account_key} para o período(s) {existing_limit_periods}. Por favor utilize o update<br/><small>Limit configuration already exists for {account_key} account for period(s) {existing_limit_periods}. Please use update</small> |
| <a id="PXT000036"></a>`PXT000036` | - | **No limit configuration found. Please set default configurations**<br/>Não foi possível encontrar configurações de limite, favor utilizar configurações padrões para {person_type}<br/><small>No limit configuration found. Please set default configurations for {person_type} person</small> |
| <a id="PXT000037"></a>`PXT000037` | - | **Person Not Found**<br/>Pessoa com chave {person_key} não encontrada<br/><small>Person with key {person_key} not found</small> |
| <a id="PXT000038"></a>`PXT000038` | - | **Not enough balance**<br/>Saldo insuficiente para pagar por tarifa de pix de entrada<br/><small>Not enough balance to pay for incoming pix fee</small> |
| <a id="PXT000039"></a>`PXT000039` | - | **Invalid Batch Limit Configuration**<br/>Recebido {} configuração(ões) erradas para contas: {}. Configurações devem ser None ou float positivo<br/><small>Received {} wrong configuration(s) for accounts: {}. Configurations must be None or positive float</small> |
| <a id="PXT000040"></a>`PXT000040` | - | **Bad Request**<br/>Limite deve ser nulo, positivo inteiro ou decimal. Sent {limit}<br/><small>Amount limit must be null, positive float or int. Sent {limit}</small> |
| <a id="PXT000041"></a>`PXT000041` | - | **Not Found**<br/>Qr Code não encontrado<br/><small>Qr Code not found</small> |
| <a id="PXT000042"></a>`PXT000042` | - | **Bad Request**<br/>Não existe código ISPB para esse Bank Code<br/><small>There is no ISPB number for this Bank Code</small> |
| <a id="PXT000043"></a>`PXT000043` | - | **Bad Request**<br/>Valor decimal inválido, enviado {number}<br/><small>Invalid decimal amount, sent {number}</small> |
| <a id="PXT000044"></a>`PXT000044` | - | **Not Found**<br/>Chave PIX {pix_key} não está ativada<br/><small>Pix Key {pix_key} is not activated</small> |
| <a id="PXT000045"></a>`PXT000045` | - | **Not Found**<br/>Pagamento via QR Code é inválido para Cliente Recebedor {receiver_conciliation_id}<br/><small>QR Code Payment is invalid for Receiver Conciliation ID {receiver_conciliation_id}</small> |
| <a id="PXT000046"></a>`PXT000046` | - | **Bad Request**<br/>Valor inválido para o query parameter<br/><small>Invalid value for</small> |
| <a id="PXT000047"></a>`PXT000047` | - | **Bad Request**<br/>{field_name} não pode ser maior que {max_length} caracteres<br/><small>{field_name} could not be larger than {max_length} characters</small> |
| <a id="PXT000048"></a>`PXT000048` | - | **Bad Request**<br/>Emoji não é permitido na mensagem pix<br/><small>Emoji not allowed in pix message</small> |
| <a id="PXT000049"></a>`PXT000049` | - | **Bad Request**<br/>Ao pagar um QR Code o end_to_end_id não pode ser nulo<br/><small>When paying QR Code end_to_end_id could not be none</small> |
| <a id="PXT000050"></a>`PXT000050` | - | **Bad Request**<br/>Não foi possível ler o tipo de QR Code. Favor tente ler o qr_code outra vez<br/><small>Could not read QR Code type, please try to read qr_code again</small> |
| <a id="PXT000051"></a>`PXT000051` | - | **Invalid Requester Configuration Info**<br/>O formato enviado da configuração {configuration} não é válido<br/><small>The configuration {configuration} format sent is not valid</small> |
| <a id="PXT000052"></a>`PXT000052` | - | **Bad Request**<br/>Apenas o Master QI Tech pode alterar as configurações de limites padrões<br/><small>Only Master QI Tech can change default limits configurations</small> |
| <a id="PXT000053"></a>`PXT000053` | - | **Bad Request**<br/>Qr Code já Pago<br/><small>QrCode already paid</small> |
| <a id="PXT000054"></a>`PXT000054` | - | **Bad Request**<br/>Chave pix inválida, enviado {pix_key}<br/><small>Invalid Pix Key, sent {pix_key}</small> |
| <a id="PXT000055"></a>`PXT000055` | - | **Pix error**<br/>Tipo inválido de limite enviado<br/><small>Invalid Limit Type Sent</small> |
| <a id="PXT000056"></a>`PXT000056` | - | **Bad Request**<br/>Apenas o Master QI Tech pode alterar eventos de limites<br/><small>Only Master QI Tech can handle limit events</small> |
| <a id="PXT000057"></a>`PXT000057` | - | **Bad Request**<br/>requisição inválida ou requisição não encontrado, requisição enviada {request_key}<br/><small>Invalid request_key or no request found, request_key sent {request_key}</small> |
| <a id="PXT000058"></a>`PXT000058` | - | **Bad Request**<br/>Quando uma requisição de limite é rejeitada, o motivo não pode ser nulo<br/><small>When limit request is rejected, rejected reason could not be null</small> |
| <a id="PXT000059"></a>`PXT000059` | - | **Bad Request**<br/>O documento infomado não é o mesmo da conta de destino<br/><small>Target document number is not account owner document number</small> |
| <a id="PXT000060"></a>`PXT000060` | - | **Bad Request**<br/>Conta inexistente no banco de destino<br/><small>Nonexistent account in destination bank</small> |
| <a id="PXT000061"></a>`PXT000061` | - | **Conflict**<br/>End to end id inválido. Uma transação pix com o identificador único {end_to_end} já foi registrada!<br/><small>End to end id invalid. A pix transfer with the end to end id {end_to_end} has already been registered!</small> |
| <a id="PXT000062"></a>`PXT000062` | - | **Conflict**<br/>Campos faltantes detectados em resposta do JD connector: {response}<br/><small>Missing fields detected on jd connector response: {response}</small> |
| <a id="PXT000063"></a>`PXT000063` | - | **Conflict**<br/>Resposta inesperada: {response}<br/><small>Unexpected response: {response}</small> |
| <a id="PXT000064"></a>`PXT000064` | - | **Bad Request**<br/>Para transação pix do tipo manual, uma conta destino deve ser fornecida<br/><small>For Manual Pix Transfer Type a target account must be provided</small> |
| <a id="PXT000065"></a>`PXT000065` | - | **Bad Request**<br/>Pix transfer já rejeitada. Motivo da rejeição: {error_description_translated}<br/><small>Pix transfer sent was already rejected. Rejection_reason: {error_description}</small> |
| <a id="PXT000067"></a>`PXT000067` | - | **Pix Key is Unregistered**<br/>A chave pix {pix_key} não está sendo utilizada<br/><small>Pix key {pix_key} is not currently used</small> |
| <a id="PXT000068"></a>`PXT000068` | - | **Pix Key is Unregistered**<br/>Consulta de chave pix excedeu o tempo limite. Por favor tente novamente<br/><small>Pix key inquiry timeout. Please try again</small> |
| <a id="PXT000069"></a>`PXT000069` | - | **Error in Qr Code Payload Request**<br/>Um erro ocorreu durante a requisição do payload do qr code para a instituição de registro<br/><small>An error occurred while requesting the qr code payload to the registry institution</small> |
| <a id="PXT000070"></a>`PXT000070` | - | **Invalid Qr Code Format**<br/>O formato do Qr Code é inválido, por favor insira um Qr Code válido<br/><small>The Qr Code format is invalid, please enter a valid Qr Code</small> |
| <a id="PXT000071"></a>`PXT000071` | - | **Invalid Qr Code Type**<br/>O payload de QR Code fornecido não contêm um tipo de Qr Code Válido<br/><small>The Qr Code payload given did not provide a propper Qr Code type</small> |
| <a id="PXT000072"></a>`PXT000072` | - | **Pending Transfer**<br/>Não foi possível concluir a transação ({end_to_end_id}) e ela está pendente de confirmação<br/><small>The transaction ({end_to_end_id}) could not be completed and is pending confirmation</small> |
| <a id="PXT000073"></a>`PXT000073` | - | **Outgoing PIX Transfer Not Found**<br/>Transferência PIX de saída com identificador único {end_to_end_id} não foi encontrada<br/><small>Pix transfer end to end id {end_to_end_id} was not found</small> |
| <a id="PXT000074"></a>`PXT000074` | - | **Invalid Transaction Status**<br/>Não foi possível atualizar o status da transação. O status {status} é invalido<br/><small>Unable to update transaction status. The status {status} is invalid</small> |
| <a id="PXT000075"></a>`PXT000075` | - | **Pix Transfer Key or End To End Not Provided**<br/>Não foram fornecidos uma pix transfer key ou end to end id<br/><small>No pix transfer key or end to end id provided</small> |
| <a id="PXT000076"></a>`PXT000076` | - | **Incoming PIX Transfer Not Found**<br/>Transferência PIX de entrada com chave {pix_transfer_key} não foi encontrada<br/><small>Pix transfer key {pix_transfer_key} was not found</small> |
| <a id="PXT000077"></a>`PXT000077` | - | **Pix Transfer Receipt not allowed**<br/>Recibo de transação pix não pode ser gerado para transações rejeitadas<br/><small>Pix Transfer Receipt cannot be generated for rejected transfers</small> |
| <a id="PXT000078"></a>`PXT000078` | - | **Pix Transfer Receipt not available**<br/>Comprovante não disponível pois transação Pix está em processamento. Por favor, aguarde alguns minutos e tente novamente<br/><small>Receipt not available due to pix transfer currently being processed. Wait a few minutes and try again</small> |
| <a id="PXT000079"></a>`PXT000079` | - | **Bad Request**<br/>Saldo de conta de cobrança insuficiente para a taxa<br/><small>Insufficient billing account balance for fee</small> |
| <a id="PXT000080"></a>`PXT000080` | - | **Bad Request**<br/>Não foi possível concluir a transação e a transferência foi rejeitada<br/><small>Could not complete the transaction and the transaction was rejected</small> |
| <a id="PXT000081"></a>`PXT000081` | - | **Bad Request**<br/>Chave PIX não enviada<br/><small>Pix key not sent</small> |
| <a id="PXT000082"></a>`PXT000082` | - | **Bad Request**<br/>A chave PIX enviada {pix_key} não coincide com a chave PIX decodificada<br/><small>The sent PIX key {pix_key} does not match the decoded PIX key</small> |
| <a id="PXT000083"></a>`PXT000083` | - | **Bad Request**<br/>Pix rejeitado.<br/><small>Pix rejected.</small> |
| <a id="PXT000084"></a>`PXT000084` | - | **Original Pix Transfer Was Not Found**<br/>A transação PIX original não foi encontrada<br/><small>Original Pix Transfer Was Not Found</small> |
| <a id="PXT000085"></a>`PXT000085` | - | **Invalid Permission**<br/>Usuário não tem permissões suficientes<br/><small>User do not has sufficient permissions</small> |
| <a id="PXT000086"></a>`PXT000086` | - | **Update Default Failed**<br/>Para alterar a configuracao de requester padrao, envie default como requester_key na url<br/><small>To update default requester configuration send default as requester_key in url</small> |
| <a id="PXT000087"></a>`PXT000087` | - | **Amount limit not approved try a lower value**<br/>Limite total não aprovado para pessoa {person_type}, por favor tente um menor<br/><small>Amount limit for {person_type} person not approved, please try a lower value</small> |
| <a id="PXT000088"></a>`PXT000088` | - | **Bad Request**<br/>Informações da conta inválidas na tradução do DTO<br/><small>Invalid account information when translating to account DTO</small> |
| <a id="PXT000089"></a>`PXT000089` | - | **Incoming Pix not pending**<br/>Transferência de Entrada PIX {pix_transfer_key} não está pendente<br/><small>Incoming Pix with pix transfer key {pix_transfer_key} is not pending</small> |
| <a id="PXT000090"></a>`PXT000090` | - | **Service Unavailable**<br/>Transferência Pix não esta disponível no momento. Favor aguardar ou utilizar TED<br/><small>Pix transfer is not available right now. Please wait or use TED service</small> |
| <a id="PXT000091"></a>`PXT000091` | - | **Bad Request**<br/>Contas de sistema não possuem limite. Chave de conta {account_key} é conta de sistema<br/><small>System account has no limits. Account key {account_key} is system account</small> |
| <a id="PXT000092"></a>`PXT000092` | - | **Invalid Account Type**<br/>Transações Pix não estão implementadas para conta que não sejam escrow ou livres<br/><small>Pix is not yet implemented for non-checking or non-escrow account types</small> |
| <a id="PXT000093"></a>`PXT000093` | - | **Bad Request**<br/>Tarifas fixas e percentuais são multualmente exclusivas<br/><small>Fee must be either fixed_amount or percentage</small> |
| <a id="PXT000094"></a>`PXT000094` | - | **Bad Request**<br/>Falha ao obter transações por origin key<br/><small>Failed to fetch transactions by origin key</small> |
| <a id="PXT000095"></a>`PXT000095` | - | **Unforeseen Error Scenario on Reprocess**<br/>Cenário: pix_transfer_key: {pix_transfer_key}, pix_status: {pix_status}, bacen_status: {bacen_status}, internal_tx: {internal_tx}, reverse_tx: {reverse_tx}, external_tx: {external_tx}<br/><small>Scenario: pix_transfer_key: {pix_transfer_key}, pix_status: {pix_status}, bacen_status: {bacen_status}, internal_tx: {internal_tx}, reverse_tx: {reverse_tx}, external_tx: {external_tx}</small> |
| <a id="PXT000096"></a>`PXT000096` | - | **Expectation Failed**<br/>Erro inesperado ao tentar refazer transação externa de saída Pix {pix_transfer_key}<br/><small>Unexpected error trying to reprocess external transaction for outgoing Pix {pix_transfer_key}</small> |
| <a id="PXT000097"></a>`PXT000097` | - | **Expectation Failed**<br/>Erro inesperado ao tentar refazer transação reversa de saída Pix {pix_transfer_key}<br/><small>Unexpected error trying to reprocess reverse transaction for outgoing Pix {pix_transfer_key}</small> |
| <a id="PXT000098"></a>`PXT000098` | - | **Expectation Failed**<br/>Subtipo inesperado encontrado: {subtype}<br/><small>Unexpected subtype encountered: {subtype}</small> |
| <a id="PXT000099"></a>`PXT000099` | - | **Error retrieving account data**<br/>Erro ao recolher informações da conta {account_key}<br/><small>Error while retrieving data for account_key {account_key}</small> |
| <a id="PXT000100"></a>`PXT000100` | - | **Rejected by external analysis**<br/>A transação foi rejeitada pela análise externa<br/><small>The transaction was rejected by external analysis</small> |
| <a id="PXT000101"></a>`PXT000101` | - | **Bad Request**<br/>Não é permitido inserir valores de mínimo e máximo para tarifas de valor fixo<br/><small>It is not allowed to set a maximum or a minumum value to a fixed amount fee</small> |
| <a id="PXT000102"></a>`PXT000102` | - | **Invalid caas_client_key**<br/>A caas_client_key enviada não é válida<br/><small>There caas_client_key is not valid</small> |
| <a id="PXT000103"></a>`PXT000103` | - | {key} não foi aceito por não ser uma palavra uuid v4 válida<br/><small>{key} was not accepted for not being a valid uuid v4 string</small> |
| <a id="PXT000104"></a>`PXT000104` | - | **Invalid Transaction Amount**<br/>O valor de transação {transaction_amount} não é válido. Deve ser um valor positivo com no máximo duas casas decimais<br/><small>Transaction amount of {transaction_amount} is not valid. It must be a positive value with at maximum 2 decimal places</small> |
| <a id="PXT000105"></a>`PXT000105` | - | **Invalid end_to_end_id**<br/>O end_to_end_id enviado {end_to_end_id} não é válido<br/><small>The end_to_end_id sent {end_to_end_id} is not valid</small> |
| <a id="PXT000106"></a>`PXT000106` | - | **Failed to load pix limit used**<br/>Falha ao carregar limite pix utilizado. Caso o problema persista, por favor contate nosso suporte<br/><small>Failed to load pix limit used. Please try again. If the problem persists contact our support</small> |
| <a id="PXT000107"></a>`PXT000107` | - | **Failed to load pix limit configuration**<br/>Falha ao carregar configuração de limite pix. Caso o problema persista, por favor contate nosso suporte<br/><small>Failed to load pix limit configuration. Please try again. If the problem persists contact our support</small> |
| <a id="PXT000108"></a>`PXT000108` | - | **Bad Request**<br/>Conta de cobrança encerrada ou bloqueada<br/><small>Billing account closed or blocked</small> |
| <a id="PXT000109"></a>`PXT000109` | - | **Bad Request**<br/>request_control_key {request_control_key} já utilizada<br/><small>request_control_key {request_control_key} already in use</small> |
| <a id="PXT000110"></a>`PXT000110` | - | **Failed external analysis**<br/>A transação foi rejeitada falhou em ser validada pela análise externa<br/><small>The transaction failed to be validated by external analysis</small> |
| <a id="PXT000111"></a>`PXT000111` | - | **Bad Request**<br/>Tipo de transação pix inválida<br/><small>invalid pix transfer type sent</small> |
| <a id="PXT000112"></a>`PXT000112` | - | **Bad Request**<br/>Número de conciliação do recebedor não atende ao esperado<br/><small>Receiver Conciliation id sent does not match expected</small> |
| <a id="PXT000113"></a>`PXT000113` | - | **Bad Request**<br/>Foi identificado por request_control_key ou end_to_end_id que está requisição está sendo processada<br/><small>It has been identified by request_control_key or end_to_end_id that this request is already being processed</small> |
| <a id="PXT000114"></a>`PXT000114` | - | **Bad Request**<br/>Requester Configuration já existe para o {requester_key}<br/><small>Requester Configuration already exists for {requester_key}</small> |
| <a id="PXT000115"></a>`PXT000115` | - | **Bad Request**<br/>Saldo de conta insuficiente para a transação e a taxa<br/><small>Insufficient account balance for transfer and fee amount</small> |
| <a id="PXT000117"></a>`PXT000117` | - | **Pix Transfer Pending**<br/>Um erro ocorreu ao enviar a pix_transfer {pix_transfer.pix_transfer_key} ao SPI<br/><small>An error occurred while sending pix_transfer {pix_transfer.pix_transfer_key} to SPI</small> |
| <a id="PXT000118"></a>`PXT000118` | - | **Requester is not Pix Participant**<br/>O requisitante enviou uma alias key no entanto não é um participante do pix indireto<br/><small>The requester sent an alias key but is not a indirect pix participant</small> |
| <a id="PXT000119"></a>`PXT000119` | - | **Requester is not account Owner**<br/>O requisitante não é dono da conta enviada<br/><small>The requester is not the owner for the account sent</small> |
| <a id="PXT000120"></a>`PXT000120` | - | **Alias sent not found**<br/>Alias key vinculada à conta não encontrada<br/><small>Alias key attached to this account not found</small> |
| <a id="PXT000121"></a>`PXT000121` | - | **Pix Transfer Direction Invalid**<br/>Pix transfer direction deve ser outgoing ou incoming<br/><small>Pix transfer direction must be either outgoing or incoming</small> |
| <a id="PXT000122"></a>`PXT000122` | - | **Pix Transfer key or Request Control Key needed**<br/>Uma pix_transfer_key ou uma request_control_key deve ser fornecida<br/><small>A pix_transfer_key or a request_control_key must be provided</small> |
| <a id="PXT000123"></a>`PXT000123` | - | **Invalid Timestamp Format sent**<br/>Parametro enviado não está no formato correto {timestamp_format}<br/><small>Given parameter is not in the correct format {timestamp_format}</small> |
| <a id="PXT000124"></a>`PXT000124` | - | **Outgoing Pix Transfer not found**<br/>Parâmetros enviados não retornaram resultados<br/><small>Given parameters returned no results found</small> |
| <a id="PXT000125"></a>`PXT000125` | - | **Incoming Pix Transfer not found**<br/>Parâmetros enviados não retornaram resultados<br/><small>Given parameters returned no results found</small> |
| <a id="PXT000128"></a>`PXT000128` | - | **Bad Request**<br/>Chave Pix {pix_key} enviada não condiz com consulta. Verifique se end_to_end_id enviado está correto<br/><small>Pix key {pix_key} sent does match inquiry pix key. Verify if end_to_end_id sent is correct</small> |
| <a id="PXT000129"></a>`PXT000129` | - | **SPI Error message**<br/>Mensagem rejeitada pela SPI-ICOM<br/><small>Message rejected by SPI-ICOM</small> |
| <a id="PXT000130"></a>`PXT000130` | - | **SPI Timeout Control**<br/>Controle de timeout no SPI<br/><small>SPI Timeout Control</small> |
| <a id="PXT000131"></a>`PXT000131` | - | **Receiver Internal Error**<br/>Transação interrompida devido a erro no PSP do Recebedor<br/><small>Cancelled transaction due to receiver</small> |
| <a id="PXT000132"></a>`PXT000132` | - | **Invalid Target Account Number**<br/>Número da conta de destino é inexistente ou inválido<br/><small>Target account number is invalid</small> |
| <a id="PXT000133"></a>`PXT000133` | - | **Blocked Target Account**<br/>A conta de destino encontra-se bloqueada<br/><small>Target account is blocked</small> |
| <a id="PXT000134"></a>`PXT000134` | - | **Closed Target Account**<br/>A conta de destino encontra-se encerrada<br/><small>Target account is closed</small> |
| <a id="PXT000135"></a>`PXT000135` | - | **Unsupported Transaction**<br/>A conta de destino não suporta este tipo de transação<br/><small>Unsupported transaction for given target account</small> |
| <a id="PXT000136"></a>`PXT000136` | - | **Invalid Participant**<br/>Participante direto do SPI não é liquidante do PSP do Pagador / Recebedor<br/><small>SPI participant is not PSP settler agent of payer nor receiver</small> |
| <a id="PXT000137"></a>`PXT000137` | - | **Zero Value Payment Order**<br/>Ordem de pagamento com valor zero<br/><small>Zero value payment order</small> |
| <a id="PXT000138"></a>`PXT000138` | - | **Insufficient Funds**<br/>Saldo insuficiente na conta PI do pagador<br/><small>Insufficient funds in PI account from payer</small> |
| <a id="PXT000139"></a>`PXT000139` | - | **Return Value Too Great**<br/>Valor de devolução acima do valor de pagamento correspondente<br/><small>Return value greater than corresponding payment order</small> |
| <a id="PXT000140"></a>`PXT000140` | - | **Invalid Transactions Number**<br/>Quantidade de transações inválida<br/><small>Invalid transactions number</small> |
| <a id="PXT000141"></a>`PXT000141` | - | **Unrelated Beneficiary Document Number**<br/>CPF/CNPJ do usuário recebedor não é compatível com o titular da conta de destino<br/><small>Beneficiary document number is not that of target account owner</small> |
| <a id="PXT000142"></a>`PXT000142` | - | **Invalid Beneficiary Document Number**<br/>CPF/CNPJ da conta de destino está incorreto<br/><small>Invalid beneficiary document number</small> |
| <a id="PXT000143"></a>`PXT000143` | - | **Incorrect Message Element**<br/>Elemento da mensagem incorreto<br/><small>Incorrect message element</small> |
| <a id="PXT000144"></a>`PXT000144` | - | **Rejected Payment Order**<br/>Ordem de pagamento foi rejeitada pelo banco recebedor<br/><small>Beneficiary</small> |
| <a id="PXT000145"></a>`PXT000145` | - | **Unauthorized Payer**<br/>Participante que assinou a mensagem não é autorizado a realizar a operação na conta PI<br/><small>Signing participant is unauthorized to make a payment order for paying account</small> |
| <a id="PXT000146"></a>`PXT000146` | - | **Invalid Datetime**<br/>Data e Hora do envio da mensagem inválida<br/><small>Invalid datetime for message delivery</small> |
| <a id="PXT000147"></a>`PXT000147` | - | **Generic Error**<br/>Erro no processamento do pagamento (erro genérico)<br/><small>Error while processing payment (generic error)</small> |
| <a id="PXT000148"></a>`PXT000148` | - | **Bad Format Operation Identifier**<br/>Identificador da operação mal formatado<br/><small>Badly formatted operation</small> |
| <a id="PXT000149"></a>`PXT000149` | - | **Invalid Payer ISPB**<br/>Número ISPB do PSP do Pagador é inválido ou inexistente<br/><small>Invalid or non-existent payer</small> |
| <a id="PXT000150"></a>`PXT000150` | - | **Invalid Beneficiary ISPB**<br/>Número ISPB do banco recebedor é inválido ou inexistente<br/><small>Invalid or non-existent beneficiary</small> |
| <a id="PXT000151"></a>`PXT000151` | - | **Incorrect Type**<br/>Tipo incorreto para a conta transacional especificada<br/><small>Incorrect type for target account</small> |
| <a id="PXT000152"></a>`PXT000152` | - | **SPI Repeated E2E ID**<br/>O end_to_end_id já foi utilizado<br/><small>The end_to_end_id was already used</small> |
| <a id="PXT000153"></a>`PXT000153` | - | **Invalid Target Account Type**<br/>O tipo de conta destino não pode receber transações PIX<br/><small>The target account type can not receive PIX transactions</small> |
| <a id="PXT000154"></a>`PXT000154` | - | **Invalid ISPB**<br/>Número ISPB é inválido ou inexistente<br/><small>Invalid or non-existent ISPB number</small> |
| <a id="PXT000155"></a>`PXT000155` | - | **Amount too Great**<br/>Valor de pagamento/devolução acima do permitido para a conta de destino creditada<br/><small>Amount too great for credited account</small> |
| <a id="PXT000156"></a>`PXT000156` | - | **QR Code Rejected**<br/>QR Code rejeitado pelo PSP do usuário recebedor<br/><small>QR Code rejected by beneficiary</small> |
| <a id="PXT000157"></a>`PXT000157` | - | **Bacen Service Unavailable**<br/>Não pode enviar a mensagem para a ICOM depois de 3 tentativas<br/><small>Could not sent the message to ICOM after 3 retries</small> |
| <a id="PXT000158"></a>`PXT000158` | - | **Invalid Amount**<br/>O valor do pagamento diverge do valor esperado de {expected_amount}<br/><small>Paid amount diverges from expected amount of {expected_amount}</small> |
| <a id="PXT000159"></a>`PXT000159` | - | **QR code inactive**<br/>QR code não está ativo no instante do pagamento<br/><small>QR code is not active at the time of payment</small> |
| <a id="PXT000160"></a>`PXT000160` | - | **QR code inactive**<br/>QR code não está ativo no instante do pagamento<br/><small>QR code is not active at the time of payment</small> |
| <a id="PXT000161"></a>`PXT000161` | - |  |
| <a id="PXT000162"></a>`PXT000162` | - |  |
| <a id="PXT000163"></a>`PXT000163` | - |  |
| <a id="PXT000164"></a>`PXT000164` | - | **Unmapped Rejection Error Code**<br/>Código de recusa desconhecido do PSP recebedor<br/><small>Settlement failed, unknown error reason code from receiver PSP</small> |
| <a id="PXT000165"></a>`PXT000165` | - | **Request Control Key needed**<br/>Uma request_control_key deve ser fornecida<br/><small>A request_control_key must be provided</small> |
| <a id="PXT000166"></a>`PXT000166` | - | **Invalid Target**<br/>A conta não possui permissão para realizar transferências para a conta enviada<br/><small>Account does not have permission to transfer to the given target account</small> |
| <a id="PXT000167"></a>`PXT000167` | - | **Requester not allowed to access this endpoint**<br/>Requester não possui permissão de realizar transações pix através deste endpoint<br/><small>Requester has no permission to perform pix transfers on this endpoint</small> |
| <a id="PXT000168"></a>`PXT000168` | - | **No approver permission**<br/>Número de documento enviado não pertence a um aprovador da conta<br/><small>Given document number does not belong to an approver for this account</small> |
| <a id="PXT000169"></a>`PXT000169` | - | **tfa_info is required**<br/>Cliente deve enviar objeto tfa_info<br/><small>Client must send object tfa_info</small> |
| <a id="PXT000170"></a>`PXT000170` | - | **Error occurred while sending token**<br/>Um erro inexperado ocorreu ao tentar enviar token<br/><small>An unexpected error occurred while sending token</small> |
| <a id="PXT000171"></a>`PXT000171` | - | **Number of token validation attempts exceeded**<br/>Número máximo de tentativas de validação de token atingida<br/><small>The maximum number of failed token validation attempts has been reached</small> |
| <a id="PXT000172"></a>`PXT000172` | - | **Token Expired**<br/>Token expirado. Reenvie token ou recrie a transferência<br/><small>Token has expired. Resend token or recreate transfer</small> |
| <a id="PXT000173"></a>`PXT000173` | - | **Incorrect Token**<br/>Token enviado não condiz com, o esperado<br/><small>Token sent does not match expected</small> |
| <a id="PXT000174"></a>`PXT000174` | - | **Error Sending Token**<br/>Um erro ocorreu ao enviar token e está sendo investigado<br/><small>An error occurred while sending token and its being investigated</small> |
| <a id="PXT000175"></a>`PXT000175` | - | **Invalid Status**<br/>Pix transfer não está pendente de aprovação por autenticação de dois fatores<br/><small>Pix transfer not in pending_2fa_approval status</small> |
| <a id="PXT000176"></a>`PXT000176` | - | **Error Sending Token**<br/>Um erro ocorreu ao reenviar token e está sendo investigado<br/><small>An error occurred while resending token and its being investigated</small> |
| <a id="PXT000177"></a>`PXT000177` | - | **Pix Transfer Batch key needed**<br/>Uma pix_transfer_batch_key deve ser fornecida<br/><small>A pix_transfer_batch_key must be provided</small> |
| <a id="PXT000178"></a>`PXT000178` | - | **Pix Transfer Batch not found**<br/>Uma pix_transfer_batch não encontrada<br/><small>A pix_transfer_batch not found</small> |
| <a id="PXT000179"></a>`PXT000179` | - | **Empty pix-transfer list received**<br/>Uma lista de transferências pix deve ser fornecida<br/><small>A list of pix transfers must be provided</small> |
| <a id="PXT000180"></a>`PXT000180` | - | **Invalid Status**<br/>Pix transfer em lote não está pendente de aprovação por autenticação de dois fatores<br/><small>Pix transfer Batch not in pending_2fa_approval status</small> |
| <a id="PXT000181"></a>`PXT000181` | - | **Target PSP Timeout**<br/>Timeout do participante recebedor da ordem de pagamento<br/><small>Beneficiary</small> |
| <a id="PXT000182"></a>`PXT000182` | - | **Bad Request**<br/>A Pix transfer enviada está ligada a um lote. Ela não pode ser individualmente aprovada. Por favor aprove o lote<br/><small>The given Pix transfer is tied to a batch. It cannot be individually approved. Please approve batch</small> |
| <a id="PXT000183"></a>`PXT000183` | - | **Invalid Person Type**<br/>Pessoa Física não pode pagar tarifa de PIX<br/><small>Natural Person Cannot Pay for a PIX Fee</small> |
| <a id="PXT000184"></a>`PXT000184` | - | **Outgoing PIX Transfer must hold to be reprocessed**<br/>Transferência PIX de saída com chave {pix_transfer_key} deve aguardar para ser reprocessada<br/><small>Pix transfer key {pix_transfer_key} must wait to be reprocessed</small> |
| <a id="PXT000185"></a>`PXT000185` | - | **Invalid Limit Request Status**<br/>Status de requisição de limite pix inválida para realizar operação<br/><small>Invalid limit request status to perform request</small> |
| <a id="PXT000186"></a>`PXT000186` | - | **Invalid pix transfer Status**<br/>Status de pix inválido para realizar operação<br/><small>Invalid pix transfer status to perform request</small> |
| <a id="PXT000187"></a>`PXT000187` | - | **Reprocessing Blocked. Reversal Transaction Detected**<br/>Pix transfer não pode ser reprocessda devido a presença de reversal<br/><small>Pix transfer cannot be reprocessed due to reversal being detected</small> |
| <a id="PXT000188"></a>`PXT000188` | - | **Session ID needed**<br/>Uma session_id deve ser fornecida<br/><small>A session_id must be provided</small> |
| <a id="PXT000189"></a>`PXT000189` | - | **Token Required**<br/>Um token é necessário para validação via SMS ou email.<br/><small>A token is required for SMS or email validation.</small> |

---

# Cancelar agendamento em lote de pagamento

URL: /documentation/baas/cobranca/2fa_v2/agendamento/cancelar_agendamento_em_lote_de_pagamento

Este endpoint permite cancelar um lote de agendamento de pagamentos enquanto o lote estiver em status cancelável.

:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::

:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::

## Request

### Request Endpoint

ENDPOINT /account/ ACCOUNT_KEY /batch_payment_schedule/ BATCH_PAYMENT_SCHEDULE_KEY /cancel
MÉTODO PATCH

### Request Path Params

| Campo                 | Tipo  | Descrição                                        | Caracteres |
|-----------------------|-------|--------------------------------------------------|------------|
| `account_key` *       | uuid4 | Chave única de identificação da conta.           | 36         |
| `batch_payment_key` * | uuid4 | Chave única de identificação do lote de agendamento. | 36         |

## Response

### Success Response

STATUS 200

Response Body: Lote de agendamento cancelado

```json
{
  "batch_payment_schedule_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
  "total_amount": 1357.3,
  "batch_payment_schedule_status": "canceled",
  "payment_type": "bank_slip"
}
```

### Response Body Params

| Campo                           | Tipo   | Descrição |
|--------------------------------|--------|-----------|
| `batch_payment_schedule_key` * | uuid4  | Chave única de identificação do lote de agendamento. |
| `request_control_key` *        | uuid4  | Chave única de identificação da requisição do cliente (lote). |
| `account_key` *                | uuid4  | Chave da conta debitada. |
| `total_amount` *               | number | Soma dos valores dos itens do lote. |
| `batch_payment_schedule_status` * | [enum](#enumeradores-batch_payment_schedule_status) | Status do lote após a solicitação de cancelamento. |
| `payment_type` *               | [enum](#enumeradores-payment_type) | Tipo do pagamento. |

### Enumeradores batch_payment_schedule_status

| Enumerador             | Descrição                 |
|------------------------|---------------------------|
| `pending_2fa_approval` | Pendente de aprovação 2FA |
| `scheduled`            | Agendado                  |
| `rejected`             | Rejeitado                 |
| `canceled`             | Cancelado                 |
| `error`                | Erro ao agendar           |

### Enumeradores payment_type

| Enumerador        | Descrição              |
|-------------------|------------------------|
| `bank_slip`       | Boleto bancário        |
| `collection_slip` | Fatura de recolhimento |

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título      | Descrição (eng)                              | Descrição (pt-br)                                      |
|-------------|-----------|-------------|----------------------------------------------|--------------------------------------------------------|
| 403         | BIP000010 | Forbidden   | User is not allowed to do this action        | Usuário não tem autorização para fazer essa ação       |
| 404         | BIP000011 | Not Found   | The source account key was not found.        | A chave da conta de origem não foi encontrada.         |
| 404         | BIP000083 | Not Found   | Batch payment not found by batch payment key.| Lote de pagamentos não encontrado pela chave do lote.  |
| 400         | BIP000085 | Bad Request | Batch payment status is not pending approval.| Status do lote de pagamentos não é de aprovação pendente. |

---

# Confirmar Agendamento de Boleto Bancário

URL: /documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_de_boleto_bancario

Este endpoint permite realizar a confirmação do agendamento de pagamento de um boleto bancário.

:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/ PAYMENT_SCHEDULE_KEY /bank_slip/validate_token
MÉTODO PATCH

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |
| `payment_schedule_key` * | uuid4   | Chave única de identificação do agendamento. | 36         |

Request Body: Confirmação de agendamento de boleto bancário

```json
{
  "token": "329adf"
}
```

### Body Params

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `token` * | string | Código de autenticação enviado ao aprovador de movimentações da conta |

## Response

### Success Response

STATUS 200

Response Body: Agendamento confirmado

```json
{
   "payment_schedule_key":"c4325104-d60b-44f3-aae4-49155564a2ea",
   "request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189",
   "payer_name":"COOPERATIVA INDUSTRIAL MURILO",
   "payer_document_number":"00037025000160",
   "source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
   "paid_amount":1050.1,
   "payment_date":"2024-04-03",
   "payment_type":"bank_slip",
   "bank_slip": {
        "bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
        "barcode":"00193967000009910000000003615574000000002417",
        "digitable_line":"00190000090361557400500000024174396700000991000",
        "payer_name":"COOPERATIVA TESTE",
        "payer_document_number":"00037025000160",
        "beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
        "beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
        "beneficiary_document_number":"52069937000117",
        "beneficiary_bank_ispb":"00000000",
        "guarantor_name":null,
        "guarantor_document_number":null,
        "expiration_date":"2024-03-29",
        "max_payment_data": "2026-03-29",
        "partial_payment_indicator":"allowed",
        "registered_payment_amount":9029.0,
        "nominal_amount":9910.0,
        "total_amount":10129.1,
        "rebate_amount":0.0,
        "discount_amount":0.0,
        "fine_amount":0.0,
        "interest_amount":219.1
    },
   "collection_slip":null,
   "payment_schedule_status":"scheduled"
}
```

### Response Body Params

| Campo               | Tipo    | Descrição                                           |
|---------------------|---------|-----------------------------------------------------|
| `payment_key` *               | uuid4 | Chave única de identificação do pagamento.          |
| `request_control_key` *       | uuid4 | Chave única de identificação da request do cliente. |
| `payer_name` *                | string | Nome do pagador efetivo.                            |
| `payer_document_number` *     | string | Número do documento do pagador efetivo (CPF/CNPJ).  |
| `source_account_key` *        | uuid4 | Chave da conta debitada.                            |
| `paid_amount` *               | number | Valor pago efetivamente.                            |
| `payment_date` *              | string | Data do pagamento.                                  |
| `payment_type` *              | [enum](#enumeradores-payment_type) | Tipo do pagamento.                                  |
| `bank_slip`                   | [object](#objeto-bank_slip) | Boleto bancário.                                    |
| `collection_slip`             | object | Fatura de recolhimento.                             |
| `payment_schedule_status` *            | [enum](#enumeradores-payment_schedule_status) | Status do agendamento.                              |

### Enumeradores payment_type
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

:::danger Aviso
O enumerador `collection_slip` não se aplica para o fluxo de boletos bancários, assim como o objeto collection_slip que sempre será nulo.
:::

### Enumeradores payment_schedule_status
| Enumerador          | Descrição                                                        |
|---------------------|------------------------------------------------------------------|
| `pending_2fa_approval` | Agendamento pendente de autenticação de dois fatores (2FA)       |
| `scheduled`          | Pagamento agendado com sucesso                                   |
| `executed`          | O agendamento foi executado com sucesso e o pagamento referente ao agendamento gerado |
| `rejected`          | O agendamento foi rejeitado e nenhum pagamento foi gerado             |
| `canceled`         | Agendamento cancelado                                            |
| `error`             | Erro ao realizar o agendamento                                   |

### Objeto bank_slip
| Campo                             | Tipo    | Descrição                         |
|-----------------------------------|---------|-----------------------------------|
| `barcode` *                       | string | Código de barras. |
| `digitable_line` *                | string | Linha digitável. |
| `payer_name` *                    | string | Nome do pagador.|
| `payer_document_number` *         | string | Número do documento do pagador (CPF/CNPJ). |
| `beneficiary_name` *              | string | Nome do beneficiário. |
| `beneficiary_trading_name`        | string | Nome fantasia do beneficiário. |
| `beneficiary_document_number` *   | string | Número do documento do beneficiário  (CPF/CNPJ). |
| `beneficiary_bank_ispb` *         | string | Código ispb do banco do beneficiário. |
| `guarantor_name`                  | string | Nome do sacador avalista. |
| `guarantor_document_number`       | string | Número do documento do sacador avalista (CPF/CNPJ). |
| `expiration_date` *               | string | Data de vencimento. |
| `max_payment_date` * | string  | Data máxima de pagamento. |
| `partial_payment_indicator` *     | [enum](#enumeradores-partial_payment_indicator)   | Indicador de pagamento parcial. |
| `registered_payment_amount`       | string | Valor total de pagamento registrado. |
| `nominal_amount` *                | number | Valor original. |
| `total_amount` *                  | number | Valor total. |
| `rebate_amount` *                 | number | Valor do batimento. |
| `discount_amount` *               | number | Valor do desconto. |
| `fine_amount` *                   | number | Valor da multa. |
| `interest_amount` *               | number | Valor do juros. |

### Enumeradores partial_payment_indicator
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `allowed`     | string    | Permitido     |
| `not_allowed` | string    | Não permitido |

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 403         | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404         | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400         | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400         | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 400         | BIP000022 | Bad Request | Bank slip payment service is closed. | Serviço de pagamento de boleto está fechado. |
| 400         | BIP000023 | Bad Request | The source account has insufficient balance. Payment cannot be made. | A conta de origem possui saldo insuficiente. Pagamento não pode ser realizado. |
| 400         | BIP000025 | Bad Request | It was not possible to pay the bank slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar o boleto neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. |
| 400         | BIP000028 | Bad Request | The source account has blocked balance. Payment cannot be made. | A conta de origem possui saldo em conta bloqueado. Pagamento não pode ser realizado. |
| 404         | BIP000056 | Not Found | Payment not found. | Pagamento não encontrado. |
| 400         | BIP000057 | Bad Request | Payment status is not pending approval. | Status de pagamento não é de aprovação pendente. |
| 400         | BIP000058 | Bad Request | Error while validating verification token | Erro ao validar token de verificação |
| 400         | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Número de tentativas de validação de token de verificação excedido. |
| 400         | BIP000060 | Bad Request | Verification token expired. | Token de verificação expirado. |
| 400         | BIP000061 | Bad Request | Verification token validation failed. | Falha na validação do token de verificação. |
| 400         | BIP000062 | Bad Request | Payment type is not bank slip. | Tipo de pagamento não é boleto. |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |

---

# Confirmação de Pagamento de Fatura de Recolhimento

URL: /documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_de_fatura_de_recolhimento

Este endpoint permite realizar a confirmação do pagamento de faturas de recolhimento.

:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::

## Request

### Request Endpoint

ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/ PAYMENT_SCHEDULE_KEY /collection_slip/validate_token
MÉTODO PATCH

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |
| `payment_schedule_key` * | uuid4   | Chave única de identificação do agendamento. | 36         |

Request Body: Confirmação de agendamento de fatura de recolhimento

```json
{
  "token": "329adf"
}
```

### Body Params

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `token` * | string | Código de autenticação enviado ao aprovador de movimentações da conta |

## Response

### Success Response

STATUS 200

Response Body: Agendamento confirmado

```json
{
  "payment_schedule_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
  "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
  "payer_name": "COOPERATIVA INDUSTRIAL MURILO",
  "payer_document_number": "62069937000118",
  "source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "paid_amount": 1389.21,
  "payment_date": "2024-04-30",
  "payment_type": "collection_slip",
  "bank_slip": null,
  "collection_slip": {
    "barcode": null,
    "digitable_line": "836200000138892100450006762142420244046000010192",
    "collection_name": "CIA ULTRAGAZ SA-COD",
    "collection_document_number": "00394460005887",
    "expiration_date": "2024-04-15",
    "total_amount": 1389.21
  },
  "payment_status": "scheduled"
}
```

### Response Body Params

| Campo               | Tipo    | Descrição                                           |
|---------------------|---------|-----------------------------------------------------|
| `payment_key` *               | uuid4 | Chave única de identificação do pagamento.          |
| `request_control_key` *       | uuid4 | Chave única de identificação da request do cliente. |
| `payer_name` *                | string | Nome do pagador efetivo.                            |
| `payer_document_number` *     | string | Número do documento do pagador efetivo (CPF/CNPJ).  |
| `source_account_key` *        | uuid4 | Chave da conta debitada.                            |
| `paid_amount` *               | number | Valor pago efetivamente.                            |
| `payment_date` *              | string | Data do pagamento.                                  |
| `payment_type` *              | [enum](#enumeradores-payment_type) | Tipo do pagamento.                                  |
| `bank_slip`                   | object | Boleto bancário.                                    |
| `collection_slip`             | [object](#objeto-collection_slip) | Fatura de recolhimento.                             |
| `payment_schedule_status` *            | [enum](#enumeradores-payment_schedule_status) | Status do agendamento.                              |

### Enumeradores payment_type
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

:::danger Aviso
O enumerador `bank_slip` não se aplica para o fluxo de faturas de recolhimento, assim como o objeto bank_slip que sempre será nulo.
:::

### Enumeradores payment_schedule_status
| Enumerador          | Descrição                                                        |
|---------------------|------------------------------------------------------------------|
| `pending_2fa_approval` | Agendamento pendente de autenticação de dois fatores (2FA)       |
| `scheduled`          | Pagamento agendado com sucesso                                   |
| `executed`          | O agendamento foi executado com sucesso e o pagamento referente ao agendamento gerado |
| `rejected`          | O agendamento foi rejeitado e nenhum pagamento foi gerado             |
| `canceled`         | Agendamento cancelado                                            |
| `error`             | Erro ao realizar o agendamento                                   |

### Objeto collection_slip
| Campo                             | Tipo    | Descrição                         |
|-----------------------------------|---------|-----------------------------------|
| `barcode`          | string | Código de barras. |
| `digitable_line`   | string | Linha digitável. |
| `collection_name` *         | string | Nome do convênio.|
| `collection_document_number`   | string | Número de documento do convênio (CPF/CNPJ).|
| `expiration_date` *  | string  | Data de vencimento. |
| `total_amount` *  | number | Valor total. |

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 403         | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404         | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400         | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400         | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |s
| 400         | BIP000023 | Bad Request | The source account has insufficient balance. Payment cannot be made. | A conta de origem possui saldo insuficiente. Pagamento não pode ser realizado. |
| 400         | BIP000028 | Bad Request | The source account has blocked balance. Payment cannot be made. | A conta de origem possui saldo em conta bloqueado. Pagamento não pode ser realizado. |
| 400         | BIP000036 | Bad Request | Covenant slip overdue. | Fatura de recolhimento vencida. |
| 400         | BIP000038 | Bad Request | Outside of covenant payment hours. | Fora do horário de pagamento do convênio. |
| 400         | BIP000044 | Bad Request | It was not possible to pay the collection slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar a fatura de recolhimento neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. |
| 400         | BIP000045 | Bad Request | Collection slip payment service is closed. | Serviço de pagamento de fatura de recolhimento está fechado. |
| 404         | BIP000056 | Not Found | Payment not found. | Pagamento não encontrado. |
| 400         | BIP000057 | Bad Request | Payment status is not pending approval. | Status de pagamento não é de aprovação pendente. |
| 400         | BIP000058 | Bad Request | Error while validating verification token | Erro ao validar token de verificação |
| 400         | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Número de tentativas de validação de token de verificação excedido. |
| 400         | BIP000060 | Bad Request | Verification token expired. | Token de verificação expirado. |
| 400         | BIP000061 | Bad Request | Verification token validation failed. | Falha na validação do token de verificação. |
| 400         | BIP000063 | Bad Request | Payment type is not collection slip. | Tipo de pagamento não é fatura de recolhimento. |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |

---

# Confirmar agendamento em lote de boleto bancário

URL: /documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_em_lote_de_boleto_bancario

Este endpoint permite validar o token de autenticação de dois fatores (2FA) de um lote de agendamento de boletos bancários em `batch_payment_schedule_status` **`pending_2fa_approval`**.

:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::

## Request

### Request Endpoint

ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payment/schedule_bank_slip/ BATCH_PAYMENT_SCHEDULE_KEY /validate_token
MÉTODO PATCH

### Request Path Params

| Campo                 | Tipo  | Descrição                                                                                | Caracteres |
| --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- |
| `account_key` *       | uuid4 | Chave única de identificação da conta.                                                   | 36         |
| `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do lote de agendamento. | 36         |

Request Body: Validação de token do lote de agendamento

```json
{
  "token": "329adf"
}
```

### Body Params

| Campo   | Tipo   | Descrição                                                                                                        | Caracteres |
| ------- | ------ | ---------------------------------------------------------------------------------------------------------------- | ---------- |
| `token` | string | Código de autenticação enviado ao aprovador de movimentações da conta | 6          |

## Response

### Success Response

STATUS 200

Response Body: Lote de agendamento confirmado

```json
{
  "batch_payment_schedule_key": "c4325104-d60b-44f3-aae4-49155564a2ea",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
  "total_amount": 1357.3,
  "batch_payment_schedule_status": "scheduled",
  "payment_type": "bank_slip"
}
```

### Response Body Params

| Campo                   | Tipo   | Descrição |
| ----------------------- | ------ | --------- |
| `batch_payment_schedule_key` *   | uuid4  | Chave única de identificação do agendamento em lote. |
| `request_control_key` * | uuid4  | Chave única de identificação da requisição do cliente (lote). |
| `account_key` *         | uuid4  | Chave da conta debitada. |
| `total_amount` *        | number | Soma dos valores dos itens do lote. |
| `batch_payment_schedule_status` *        | [enum](#enumeradores-batch_payment_schedule_status) | Status do lote de agendamento após a validação do token. |
| `payment_type` *        | string | Tipo do pagamento; para este fluxo, espera-se `bank_slip`. |

### Enumeradores batch_payment_schedule_status

| Enumerador    | Descrição     |
|---------------|---------------|
| `pending_2fa_approval` | Pendente de aprovação 2FA |
| `scheduled`   | Agendado |
| `rejected`    | Rejeitado |
| `error`       | Erro ao agendar |

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título      | Descrição (eng)                               | Descrição (pt-br)                                                |
| ----------- | --------- | ----------- | --------------------------------------------- | ---------------------------------------------------------------- |
| 403         | BIP000010 | Forbidden   | User is not allowed to do this action         | Usuário não tem autorização para fazer essa ação                 |
| 404         | BIP000011 | Not Found   | The source account key was not found.         | A chave da conta de origem não foi encontrada.                   |
| 400         | BIP000058 | Bad Request | Error while validating verification token     | Erro ao validar token de verificação                             |
| 400         | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Número de tentativas de validação de token de verificação excedido. |
| 400         | BIP000060 | Bad Request | Verification token expired.                   | Token de verificação expirado.                                   |
| 400         | BIP000061 | Bad Request | Verification token validation failed.       | Falha na validação do token de verificação.                      |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded.    | Janela de tempo de verificação de pagamento excedida.            |
| 404         | BIP000083 | Not Found   | Batch payment not found by batch payment key. | Lote de pagamentos não encontrado pela chave do lote.            |
| 400         | BIP000085 | Bad Request | Batch payment status is not pending approval. | Status do lote de pagamentos não é de aprovação pendente.        |
| 400         | BIP000086 | Bad Request | A token is required for SMS or email validation. | Um token é necessário para validação via SMS ou email.         |

---

# Confirmar agendamento em lote de fatura de recolhimento

URL: /documentation/baas/cobranca/2fa_v2/agendamento/confirmar_agendamento_em_lote_de_fatura_de_recolhimento

Este endpoint permite validar o token de autenticação de dois fatores (2FA) de um lote de agendamento de faturas de recolhimento em `batch_payment_schedule_status` **`pending_2fa_approval`**.

:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::

## Request

### Request Endpoint

ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payment/schedule_collection_slip/ BATCH_PAYMENT_SCHEDULE_KEY /validate_token
MÉTODO PATCH

### Request Path Params

| Campo                 | Tipo  | Descrição                                                                                | Caracteres |
| --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- |
| `account_key` *       | uuid4 | Chave única de identificação da conta.                                                   | 36         |
| `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do lote de agendamento. | 36         |

Request Body: Validação de token do lote de agendamento

```json
{
  "token": "329adf"
}
```

### Body Params

| Campo   | Tipo   | Descrição                                                                                                        | Caracteres |
| ------- | ------ | ---------------------------------------------------------------------------------------------------------------- | ---------- |
| `token` | string | Código de autenticação enviado ao aprovador de movimentações da conta | 6          |

## Response

### Success Response

STATUS 200

Response Body: Lote de agendamento confirmado

```json
{
  "batch_payment_schedule_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
  "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
  "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "total_amount": 1939.31,
  "batch_payment_schedule_status": "scheduled",
  "payment_type": "collection_slip"
}
```

### Response Body Params

| Campo                   | Tipo   | Descrição |
| ----------------------- | ------ | --------- |
| `batch_payment_schedule_key` *   | uuid4  | Chave única de identificação do agendamento em lote. |
| `request_control_key` * | uuid4  | Chave única de identificação da requisição do cliente (lote). |
| `account_key` *         | uuid4  | Chave da conta debitada. |
| `total_amount` *        | number | Soma dos valores dos itens do lote. |
| `batch_payment_schedule_status` *        | [enum](#enumeradores-batch_payment_schedule_status) | Status do lote de agendamento após a validação do token. |
| `payment_type` *        | string | Tipo do pagamento; para este fluxo, espera-se `collection_slip`. |

### Enumeradores batch_payment_schedule_status

| Enumerador    | Descrição     |
|---------------|---------------|
| `pending_2fa_approval` | Pendente de aprovação 2FA |
| `scheduled`   | Agendado |
| `rejected`    | Rejeitado |
| `error`       | Erro ao agendar |

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título      | Descrição (eng)                               | Descrição (pt-br)                                                |
| ----------- | --------- | ----------- | --------------------------------------------- | ---------------------------------------------------------------- |
| 403         | BIP000010 | Forbidden   | User is not allowed to do this action         | Usuário não tem autorização para fazer essa ação                 |
| 404         | BIP000011 | Not Found   | The source account key was not found.         | A chave da conta de origem não foi encontrada.                   |
| 400         | BIP000058 | Bad Request | Error while validating verification token     | Erro ao validar token de verificação                             |
| 400         | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Número de tentativas de validação de token de verificação excedido. |
| 400         | BIP000060 | Bad Request | Verification token expired.                   | Token de verificação expirado.                                   |
| 400         | BIP000061 | Bad Request | Verification token validation failed.       | Falha na validação do token de verificação.                      |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded.    | Janela de tempo de verificação de pagamento excedida.            |
| 404         | BIP000083 | Not Found   | Batch payment not found by batch payment key. | Lote de pagamentos não encontrado pela chave do lote.            |
| 400         | BIP000085 | Bad Request | Batch payment status is not pending approval. | Status do lote de pagamentos não é de aprovação pendente.        |
| 400         | BIP000086 | Bad Request | A token is required for SMS or email validation. | Um token é necessário para validação via SMS ou email.         |

---

# Consultar lote de agendamento de pagamento

URL: /documentation/baas/cobranca/2fa_v2/agendamento/consultar_lote_de_agendamento_de_pagamento

Este endpoint retorna o resumo do lote de agendamento e a lista paginada dos agendamentos que o compõem (boletos bancários ou faturas de recolhimento).

Para localizar `batch_payment_schedule_key`, utilize [Listar lotes de agendamento de pagamento](./listar_lotes_de_agendamento_de_pagamento.md).

:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::

:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::

## Request

### Request Endpoint

ENDPOINT /bill_payment/account/ ACCOUNT_KEY /schedule/ BATCH_PAYMENT_SCHEDULE_KEY
MÉTODO GET

### Request Path Params

| Campo                        | Tipo  | Descrição                                          | Caracteres |
|-----------------------------|-------|----------------------------------------------------|------------|
| `account_key` *             | uuid4 | Chave única de identificação da conta.             | 36         |
| `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do lote de agendamento. | 36         |

### Request Query String Params

| Campo       | Tipo   | Descrição                                                                     |
|-------------|--------|-------------------------------------------------------------------------------|
| `page`      | string | Número da página dos itens em `payment_schedules.data`. 1 por padrão.       |
| `page_size` | string | Tamanho da página dos itens em `payment_schedules.data`. 30 por padrão e valor máximo. |

## Response

### Success Response

STATUS 200

Response Body: Detalhes do lote de agendamento

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "total_scheduled": 10,
  "total_pending": 0,
  "total_error": 0,
  "total_amount": 1357.3,
  "batch_payment_schedule_status": "scheduled",
  "payment_schedules": {
    "pagination": {
      "current_page": 1,
      "rows_per_page": 30
    },
    "data": [
      {
        "payment_schedule_key": "c4325104-d60b-44f3-aae4-49155564a2ea",
        "request_control_key": "b713b2f6-2f48-4d18-b0c9-7186e4edf189",
        "payer_name": "COOPERATIVA INDUSTRIAL MURILO",
        "payer_document_number": "00037025000160",
        "source_account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
        "paid_amount": 1050.1,
        "payment_date": "2024-04-03",
        "payment_type": "bank_slip",
        "bank_slip": {
          "bank_slip_key": "95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
          "barcode": "00193967000009910000000003615574000000002417",
          "digitable_line": "00190000090361557400500000024174396700000991000",
          "payer_name": "COOPERATIVA TESTE",
          "payer_document_number": "00037025000160",
          "beneficiary_name": "TESTE EQUIPAMENTOS E SERVICOS LTDA",
          "beneficiary_trading_name": "TESTE EQUIPAMENTOS E SERVICOS LTDA",
          "beneficiary_document_number": "52069937000117",
          "beneficiary_bank_ispb": "00000000",
          "guarantor_name": null,
          "guarantor_document_number": null,
          "expiration_date": "2024-03-29",
          "max_payment_date": "2026-03-29",
          "partial_payment_indicator": "allowed",
          "registered_payment_amount": 9029.0,
          "nominal_amount": 9910.0,
          "total_amount": 10129.1,
          "rebate_amount": 0.0,
          "discount_amount": 0.0,
          "fine_amount": 0.0,
          "interest_amount": 219.1
        },
        "collection_slip": null,
        "payment_schedule_status": "scheduled",
        "error_reason": null
      }
    ]
  }
}
```

### Response Body Params

| Campo                           | Tipo                                     | Descrição                                                     |
|--------------------------------|------------------------------------------|---------------------------------------------------------------|
| `request_control_key` *        | uuid4                                    | Chave única de identificação da requisição do cliente (lote). |
| `total_scheduled` *            | int                                      | Quantidade de itens do lote agendados com sucesso.            |
| `total_pending` *              | int                                      | Quantidade de itens ainda pendentes no lote.                  |
| `total_error` *                | int                                      | Quantidade de itens com erro no lote.                         |
| `total_amount` *               | number                                   | Valor total do lote.                                          |
| `batch_payment_schedule_status` * | [enum](#enumeradores-batch_payment_schedule_status) | Status do lote de agendamento.                                |
| `payment_schedules` *          | [object](#objeto-payment_schedules)      | Lista paginada dos agendamentos do lote.                      |

### Objeto payment_schedules

| Campo          | Tipo                         | Descrição                                                |
|----------------|------------------------------|----------------------------------------------------------|
| `pagination` * | [object](#objeto-pagination) | Paginação da lista de agendamentos do lote.             |
| `data` *       | array                        | Itens do lote (agendamentos individuais).               |

Cada elemento de `payment_schedules.data` contém:

| Campo                     | Tipo                                 | Descrição                                                                      |
|--------------------------|--------------------------------------|--------------------------------------------------------------------------------|
| `payment_schedule_key` * | uuid4                                | Chave única de identificação do agendamento.                                   |
| `request_control_key` *  | uuid4                                | Chave única de identificação da requisição do cliente para o item do lote.     |
| `payer_name` *           | string                               | Nome do pagador efetivo.                                                       |
| `payer_document_number` *| string                               | Número de documento do pagador efetivo (CPF/CNPJ).                             |
| `source_account_key` *   | uuid4                                | Chave da conta debitada.                                                       |
| `paid_amount` *          | number                               | Valor agendado para pagamento.                                                 |
| `payment_date` *         | string                               | Data do agendamento.                                                           |
| `payment_type` *         | [enum](#enumeradores-payment_type)   | Tipo do pagamento.                                                             |
| `bank_slip`              | [object](#objeto-bank_slip)          | Boleto bancário. Pode ser `null` quando `payment_type` for `collection_slip`. |
| `collection_slip`        | [object](#objeto-collection_slip)    | Fatura de recolhimento. Pode ser `null` quando `payment_type` for `bank_slip`.|
| `payment_schedule_status` * | [enum](#enumeradores-payment_schedule_status) | Status do agendamento.                                                         |
| `error_reason`           | string                               | Motivo do erro, quando aplicável; caso contrário `null`.                       |

### Objeto pagination

| Campo             | Tipo | Descrição                           |
|------------------|------|-------------------------------------|
| `current_page` * | int  | Página atual retornada.             |
| `rows_per_page` *| int  | Quantidade de registros por página. |

### Enumeradores payment_type

| Enumerador        | Descrição              |
|-------------------|------------------------|
| `bank_slip`       | Boleto bancário        |
| `collection_slip` | Fatura de recolhimento |

### Enumeradores payment_schedule_status

| Enumerador             | Descrição                                                        |
|------------------------|------------------------------------------------------------------|
| `pending_2fa_approval` | Agendamento pendente de autenticação de dois fatores (2FA)       |
| `scheduled`            | Pagamento agendado com sucesso                                   |
| `executed`             | O agendamento foi executado com sucesso e o pagamento foi gerado |
| `rejected`             | O agendamento foi rejeitado e nenhum pagamento foi gerado        |
| `canceled`             | Agendamento cancelado                                            |
| `error`                | Erro ao realizar o agendamento                                   |

### Enumeradores batch_payment_schedule_status

| Enumerador             | Descrição                 |
|------------------------|---------------------------|
| `pending_2fa_approval` | Pendente de aprovação 2FA |
| `scheduled`            | Agendado                  |
| `rejected`             | Rejeitado                 |
| `canceled`             | Cancelado                 |
| `error`                | Erro ao agendar           |

### Objeto bank_slip

| Campo                           | Tipo                                            | Descrição                                           |
|--------------------------------|-------------------------------------------------|-----------------------------------------------------|
| `bank_slip_key` *              | uuid4                                           | Chave única de identificação do boleto bancário.    |
| `barcode` *                    | string                                          | Código de barras.                                   |
| `digitable_line` *             | string                                          | Linha digitável.                                    |
| `payer_name` *                 | string                                          | Nome do pagador.                                    |
| `payer_document_number` *      | string                                          | Número de documento do pagador (CPF/CNPJ).          |
| `beneficiary_name` *           | string                                          | Nome do beneficiário.                               |
| `beneficiary_trading_name`     | string                                          | Nome fantasia do beneficiário.                      |
| `beneficiary_document_number` *| string                                          | Número de documento do beneficiário (CPF/CNPJ).     |
| `beneficiary_bank_ispb` *      | string                                          | Código ispb do banco do beneficiário.               |
| `guarantor_name`               | string                                          | Nome do sacador avalista.                           |
| `guarantor_document_number`    | string                                          | Número de documento do sacador avalista (CPF/CNPJ). |
| `expiration_date` *            | string                                          | Data de vencimento.                                 |
| `max_payment_date` *           | string                                          | Data máxima de pagamento.                           |
| `partial_payment_indicator` *  | [enum](#enumeradores-partial_payment_indicator) | Indicador de pagamento parcial.                     |
| `registered_payment_amount`    | number                                          | Valor total de pagamento registrado.                |
| `nominal_amount` *             | number                                          | Valor original.                                     |
| `total_amount` *               | number                                          | Valor total.                                        |
| `rebate_amount` *              | number                                          | Valor do abatimento.                                |
| `discount_amount` *            | number                                          | Valor do desconto.                                  |
| `fine_amount` *                | number                                          | Valor da multa.                                     |
| `interest_amount` *            | number                                          | Valor dos juros.                                    |

### Enumeradores partial_payment_indicator

| Enumerador    | Descrição     |
|---------------|---------------|
| `allowed`     | Permitido     |
| `not_allowed` | Não permitido |

### Objeto collection_slip

| Campo                          | Tipo   | Descrição                                   |
|--------------------------------|--------|---------------------------------------------|
| `barcode` *                    | string | Código de barras.                           |
| `digitable_line` *             | string | Linha digitável.                            |
| `collection_name` *            | string | Nome do convênio.                           |
| `collection_document_number` * | string | Número de documento do convênio (CPF/CNPJ). |
| `expiration_date` *            | string | Data de vencimento.                         |
| `total_amount` *               | number | Valor total.                                |

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título      | Descrição (eng)                                                 | Descrição (pt-br)                                              |
|-------------|-----------|-------------|-----------------------------------------------------------------|----------------------------------------------------------------|
| 400         | BIP000027 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
| 404         | BIP000083 | Not Found   | Batch payment not found by batch payment key.                   | Lote de pagamentos não encontrado pela chave do lote.          |

---

# Listar lotes de agendamento de pagamento

URL: /documentation/baas/cobranca/2fa_v2/agendamento/listar_lotes_de_agendamento_de_pagamento

Este endpoint retorna os lotes de agendamento de pagamentos de boletos bancários e faturas de recolhimento associados à conta, com suporte a filtros e paginação.

:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::

:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::

## Request

### Request Endpoint

ENDPOINT /bill_payment/account/ ACCOUNT_KEY /schedules
MÉTODO GET

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |

### Request Query String Params

| Campo                          | Tipo        | Descrição                         |
|--------------------------------|-------------|-----------------------------------|
| `request_control_key`          | uuid4       | Chave única de identificação da requisição do cliente (lote). |
| `batch_payment_schedule_key`   | uuid4       | Chave única de identificação do lote de agendamento. |
| `payment_type`                 | [enum](#enumeradores-payment_type) | Tipo do pagamento do lote. |
| `batch_payment_schedule_status`| [enum](#enumeradores-batch_payment_schedule_status) | Status do lote de agendamento. |
| `date_from`                    | string      | Data inicial. Formato `YYYY-MM-DD`. |
| `date_to`                      | string      | Data final. Formato `YYYY-MM-DD`. |
| `page`                         | string      | Número da página requisitada. 1 por padrão. |
| `page_size`                    | string      | Tamanho da página requisitada na consulta. 30 por padrão e valor máximo. |

### Enumeradores payment_type

| Enumerador        | Tipo   | Descrição              |
|-------------------|--------|------------------------|
| `bank_slip`       | string | Boleto bancário        |
| `collection_slip` | string | Fatura de recolhimento |

### Enumeradores batch_payment_schedule_status

| Enumerador             | Descrição                          |
|------------------------|------------------------------------|
| `pending_2fa_approval` | Pendente de aprovação 2FA          |
| `scheduled`            | Agendado                           |
| `rejected`             | Rejeitado                          |
| `canceled`             | Cancelado                          |
| `error`                | Erro ao agendar                    |

## Response

### Success Response

STATUS 200

Response Body: Listagem de lotes de agendamento

```json
{
  "pagination": {
    "current_page": 1,
    "rows_per_page": 30
  },
  "data": [
    {
      "batch_payment_schedule_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "batch_payment_schedule_status": "scheduled",
      "payment_type": "bank_slip",
      "total_scheduled": 10,
      "total_pending": 0,
      "total_error": 0,
      "total_amount": 1357.3
    }
  ]
}
```

### Response Body Params

| Campo               | Tipo    | Descrição                         |
|---------------------|---------|-----------------------------------|
| `pagination` *      | [object](#objeto-pagination) | Informações de paginação da consulta. |
| `data` *            | array   | Lista de lotes encontrados. |

Cada elemento de `data` contém:

| Campo                           | Tipo    | Descrição                         |
|---------------------------------|---------|-----------------------------------|
| `batch_payment_schedule_key` *  | uuid4   | Chave única de identificação do lote de agendamento. |
| `request_control_key` *         | uuid4   | Chave única de identificação da requisição do cliente (lote). |
| `batch_payment_schedule_status` * | [enum](#enumeradores-batch_payment_schedule_status-1) | Status atual do lote de agendamento. |
| `payment_type` *                | [enum](#enumeradores-payment_type-1) | Tipo do pagamento do lote. |
| `total_scheduled` *             | int     | Quantidade de itens do lote agendados com sucesso. |
| `total_pending` *               | int     | Quantidade de itens ainda pendentes no lote. |
| `total_error` *                 | int     | Quantidade de itens com erro no lote. |
| `total_amount` *                | number  | Valor total do lote. |

### Objeto pagination

| Campo               | Tipo    | Descrição                         |
|---------------------|---------|-----------------------------------|
| `current_page` *    | int     | Página atual retornada. |
| `rows_per_page` *   | int     | Quantidade de registros por página. |

### Enumeradores payment_type

| Enumerador        | Descrição              |
|-------------------|------------------------|
| `bank_slip`       | Boleto bancário        |
| `collection_slip` | Fatura de recolhimento |

### Enumeradores batch_payment_schedule_status

| Enumerador             | Descrição                 |
|------------------------|---------------------------|
| `pending_2fa_approval` | Pendente de aprovação 2FA |
| `scheduled`            | Agendado                  |
| `rejected`             | Rejeitado                 |
| `canceled`             | Cancelado                 |
| `error`                | Erro ao agendar           |

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400         | BIP000026 | Bad Request | Invalid payment date format. The correct format is YYYY-MM-DD. | Formato de data de pagamento inválido. O formato correto é YYYY-MM-DD. |
| 400         | BIP000027 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
| 400         | BIP000047 | Bad Request | Invalid payment type. | Tipo de pagamento inválido. |

---

# Reenviar Token Autenticação de Dois Fatores de Agendamento de Boleto Bancário

URL: /documentation/baas/cobranca/2fa_v2/agendamento/reenviar_token_de_agendamento_boleto_bancario

Este endpoint permite realizar o reenvio do token de autenticação de agendamento de Boletos Bancários.

:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/ PAYMENT_SCHEDULE_KEY /bank_slip/resend_token
MÉTODO PATCH

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |
| `payment_schedule_key` * | uuid4   | Chave única de identificação do agendamento. | 36         |

### Body Params

| Campo          | Tipo   | Descrição                                                                                 | Caracteres |
|----------------|--------|-------------------------------------------------------------------------------------------|------------|
| `contact_type` | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** |

:::info Informação
Caso não seja enviado um `contact_type`, o token será enviado da forma solicitada originalmente.
:::

| Enumerador | Descrição                                         |
|------------|---------------------------------------------------|
| **sms**    | Envio por Mensagem de Texto para telefone celular |
| **email**  | Envio por correio eletrônico                      |

## Response

### Success Response

STATUS 200

Response Body: Token reenviado com sucesso

```json
{
   "payment_schedule_key":"c4325104-d60b-44f3-aae4-49155564a2ea",
   "request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189",
   "payer_name":"COOPERATIVA INDUSTRIAL MURILO",
   "payer_document_number":"00037025000160",
   "source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
   "paid_amount":1050.1,
   "payment_date":"2024-04-03",
   "payment_type":"bank_slip",
   "bank_slip": {
        "bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
        "barcode":"00193967000009910000000003615574000000002417",
        "digitable_line":"00190000090361557400500000024174396700000991000",
        "payer_name":"COOPERATIVA TESTE",
        "payer_document_number":"00037025000160",
        "beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
        "beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
        "beneficiary_document_number":"52069937000117",
        "beneficiary_bank_ispb":"00000000",
        "guarantor_name":null,
        "guarantor_document_number":null,
        "expiration_date":"2024-03-29",
        "max_payment_data": "2026-03-29",
        "partial_payment_indicator":"allowed",
        "registered_payment_amount":9029.0,
        "nominal_amount":9910.0,
        "total_amount":10129.1,
        "rebate_amount":0.0,
        "discount_amount":0.0,
        "fine_amount":0.0,
        "interest_amount":219.1
    },
   "collection_slip":null,
   "payment_schedule_status":"pending_2fa_approval"
}
```

### Response Body Params

| Campo               | Tipo    | Descrição                                           |
|---------------------|---------|-----------------------------------------------------|
| `payment_key` *               | uuid4 | Chave única de identificação do pagamento.          |
| `request_control_key` *       | uuid4 | Chave única de identificação da request do cliente. |
| `payer_name` *                | string | Nome do pagador efetivo.                            |
| `payer_document_number` *     | string | Número documento do pagador efetivo (CPF/CNPJ).     |
| `source_account_key` *        | uuid4 | Chave da conta debitada.                            |
| `transaction_key` *           | uuid4 | Chave da transação do pagamento.                    |
| `transaction_revert_key`      | uuid4 | Chave da transação de reversão do pagamento.        |
| `paid_amount` *               | number | Valor pago efetivamente.                            |
| `payment_date` *              | string | Data do pagamento.                                  |
| `payment_type` *              | [enum](#enumeradores-payment_type) | Tipo do pagamento.                                  |
| `bank_slip`                   | [object](#objeto-bank_slip) | Boleto bancário.                                    |
| `collection_slip`             | object | Fatura de recolhimento.                             |
| `payment_schedule_status` *            | [enum](#enumeradores-payment_schedule_status) | Status do agendamento.                              |

### Enumeradores payment_type
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

:::danger Aviso
O enumerador `collection_slip` não se aplica para o fluxo de boletos bancários, assim como o objeto collection_slip que sempre será nulo.
:::

### Enumeradores payment_schedule_status
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `pending_2fa_approval`    | string  | pendente de aprovação de dois fatores |

### Objeto bank_slip
| Campo                             | Tipo    | Descrição                         |
|-----------------------------------|---------|-----------------------------------|
| `barcode` *                       | string | Código de barras. |
| `digitable_line` *                | string | Linha digitável. |
| `payer_name` *                    | string | Nome do pagador.|
| `payer_document_number` *         | string | Número de documento do pagador (CPF/CNPJ). |
| `beneficiary_name` *              | string | Nome do beneficiário. |
| `beneficiary_trading_name`        | string | Nome fantasia do beneficiário. |
| `beneficiary_document_number` *   | string | Número de documento do beneficiário (CPF/CNPJ). |
| `beneficiary_bank_ispb` *         | string | Código ispb do banco do beneficiário. |
| `guarantor_name`                  | string | Nome do sacador avalista. |
| `guarantor_document_number`       | string | Número de documento do sacador avalista (CPF/CNPJ). |
| `expiration_date` *               | string | Data de vencimento. |
| `max_payment_date` * | string  | Data máxima de pagamento. |
| `partial_payment_indicator` *     | [enum](#enumeradores-partial_payment_indicator)   | Indicador de pagamento parcial. |
| `registered_payment_amount`       | string | Valor total de pagamento registrado. |
| `nominal_amount` *                | number | Valor original. |
| `total_amount` *                  | number | Valor total. |
| `rebate_amount` *                 | number | Valor do abatimento. |
| `discount_amount` *               | number | Valor do desconto. |
| `fine_amount` *                   | number | Valor da multa. |
| `interest_amount` *               | number | Valor do juros. |

### Enumeradores partial_payment_indicator
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `allowed`     | string    | Permitido     |
| `not_allowed` | string    | Não permitido |

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 403         | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404         | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400         | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400         | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 404         | BIP000056 | Not Found | Payment not found. | Pagamento não encontrado. |
| 400         | BIP000057 | Bad Request | Payment status is not pending approval. | Status de pagamento não é de aprovação pendente. |
| 400         | BIP000062 | Bad Request | Payment type is not bank slip. | Tipo de pagamento não é boleto. |
| 400         | BIP000064 | Bad Request | Error resending verification token | Erro ao reenviar token de verificação |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |

---

# Reenviar Token Autenticação de Dois Fatores de Agendamento de Fatura de Recolhimento

URL: /documentation/baas/cobranca/2fa_v2/agendamento/reenviar_token_de_agendamento_de_fatura_de_recolhimento

Este endpoint permite realizar o reenvio do token de autenticação de agendamento de Faturas de Recolhimento.

:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/ PAYMENT_SCHEDULE_KEY /collection_slip/resend_token
MÉTODO PATCH

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |
| `payment_schedule_key` * | uuid4   | Chave única de identificação do agendamento. | 36         |

## Response

### Success Response

STATUS 200

Response Body: Token reenviado com sucesso

```json
{
  "payment_schedule_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
  "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
  "payer_name": "COOPERATIVA INDUSTRIAL MURILO",
  "payer_document_number": "62069937000118",
  "source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "paid_amount": 1389.21,
  "payment_date": "2024-04-30",
  "payment_type": "collection_slip",
  "bank_slip": null,
  "collection_slip": {
    "barcode": null,
    "digitable_line": "836200000138892100450006762142420244046000010192",
    "collection_name": "CIA ULTRAGAZ SA-COD",
    "collection_document_number": "00394460005887",
    "expiration_date": "2024-04-15",
    "total_amount": 1389.21
  },
  "payment_schedule_status": "pending_2fa_approval"
}
```

### Response Body Params

| Campo               | Tipo    | Descrição                         |
|---------------------|---------|-----------------------------------|
| `payment_key` *               | uuid4 | Chave única de identificação do pagamento. |
| `request_control_key` *       | uuid4 | Chave única de identificação da request do cliente. |
| `payer_name` *                | string | Nome do pagador efetivo.|
| `payer_document_number` *     | string | Número de documento do pagador efetivo (CPF/CNPJ). |
| `source_account_key` *        | uuid4 | Chave da conta debitada. |
| `transaction_key` *           | uuid4 | Chave da transação do pagamento. |
| `transaction_revert_key`      | uuid4 | Chave da transação de reversão do pagamento. |
| `paid_amount` *               | number | Valor pago efetivamente. |
| `payment_date` *              | string | Data do pagamento. |
| `payment_type` *              | [enum](#enumeradores-payment_type) | Tipo do pagamento. |
| `bank_slip`                   | object | Boleto bancário. |
| `collection_slip`             | [object](#objeto-collection_slip) | Fatura de recolhimento. |
| `payment_schedule_status` *            | [enum](#enumeradores-payment_schedule_status) | Status do pagamento. |

### Enumeradores payment_type
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

:::danger Aviso
O enumerador `bank_slip` não se aplica para o fluxo de faturas de recolhimento, assim como o objeto bank_slip que sempre será nulo.
:::

### Enumeradores payment_schedule_status
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `pending_2fa_approval`    | string  | pendente de aprovação de dois fatores |

### Objeto collection_slip
| Campo                             | Tipo    | Descrição                         |
|-----------------------------------|---------|-----------------------------------|
| `barcode`          | string | Código de barras. |
| `digitable_line`   | string | Linha digitável. |
| `collection_name` *         | string | Nome do convênio.|
| `collection_document_number`   | string | Número de documento do convênio (CPF/CNPJ).|
| `expiration_date` *  | string  | Data de vencimento. |
| `total_amount` *  | number | Valor total. |

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 403         | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404         | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400         | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400         | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 404         | BIP000056 | Not Found | Payment not found. | Pagamento não encontrado. |
| 400         | BIP000057 | Bad Request | Payment status is not pending approval. | Status de pagamento não é de aprovação pendente. |
| 400         | BIP000063 | Bad Request | Payment type is not collection slip. | Tipo de pagamento não é fatura de recolhimento. |
| 400         | BIP000064 | Bad Request | Error resending verification token | Erro ao reenviar token de verificação |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |

---

# Reenviar token de autenticação de dois fatores de agendamento em lote de boleto bancário

URL: /documentation/baas/cobranca/2fa_v2/agendamento/reenviar_token_de_agendamento_em_lote_de_boleto_bancario

Este endpoint permite **reenviar** o token de autenticação de dois fatores (2FA) para um lote de agendamento de boletos bancários que esteja em `batch_payment_schedule_status` **`pending_2fa_approval`**.

:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::

## Request

### Request Endpoint

ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payment/schedule_bank_slip/ BATCH_PAYMENT_SCHEDULE_KEY /resend_token
MÉTODO PATCH

### Request Path Params

| Campo                 | Tipo  | Descrição                                                                                | Caracteres |
| --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- |
| `account_key` *       | uuid4 | Chave única de identificação da conta.                                                   | 36         |
| `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do lote de agendamento. | 36         |

### Request Body

Request Body (opcional)

```json
{
  "contact_type": "sms"
}
```

### Body Params

| Campo          | Tipo       | Descrição                               | Caracteres                                              |
| -------------- | ---------- | --------------------------------------- | ------------------------------------------------------- |
| `contact_type` | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** |

:::info Informação
Caso não seja enviado um `contact_type`, o token será enviado da forma solicitada originalmente no agendamento do lote (`tfa_info.contact_type`).
:::

### Enumerador contact_type

| Enumerador | Descrição                                         |
| ---------- | ------------------------------------------------- |
| **sms**    | Envio por mensagem de texto para telefone celular |
| **email**  | Envio por correio eletrônico                      |

## Response

### Success Response

STATUS 200

Response Body: Token reenviado com sucesso

```json
{
  "batch_payment_schedule_key": "c4325104-d60b-44f3-aae4-49155564a2ea",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
  "total_amount": 1357.3,
  "batch_payment_schedule_status": "pending_2fa_approval",
  "payment_type": "bank_slip"
}
```

### Response Body Params

| Campo                   | Tipo   | Descrição |
| ----------------------- | ------ | --------- |
| `batch_payment_schedule_key` *   | uuid4  | Chave única de identificação do agendamento em lote. |
| `request_control_key` * | uuid4  | Chave única de identificação da requisição do cliente (lote). |
| `account_key` *         | uuid4  | Chave da conta debitada. |
| `total_amount` *        | number | Soma dos valores dos itens do lote. |
| `batch_payment_schedule_status` *        | string | Após o reenvio, o lote permanece aguardando validação do token (`pending_2fa_approval`). |
| `payment_type` *        | string | Tipo do pagamento; para este fluxo, espera-se `bank_slip`. |

Em seguida, utilize [Confirmar agendamento em lote de boleto bancário](./confirmar_agendamento_em_lote_de_boleto_bancario.md) para concluir o 2FA.

### Error Response

STATUS 4XX

Response Body

```json
{
  "title": "Título",
  "description": "Description in english",
  "translation": "Descrição em português",
  "code": "Código"
}
```

| Código HTTP | Código QI | Título      | Descrição (eng)                                                                                    | Descrição (pt-br)                                                                                         |
| ----------- | --------- | ----------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| 403         | BIP000010 | Forbidden   | User is not allowed to do this action                                                              | Usuário não tem autorização para fazer essa ação                                                          |
| 404         | BIP000011 | Not Found   | The source account key was not found.                                                              | A chave da conta de origem não foi encontrada.                                                            |
| 400         | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000059 | Bad Request | Number of verification token validation attempts exceeded.                                         | Número de tentativas de validação de token de verificação excedido.                                       |
| 400         | BIP000064 | Bad Request | Error resending verification token                                                                 | Erro ao reenviar token de verificação                                                                     |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded.                                                         | Janela de tempo de verificação de pagamento excedida.                                                     |
| 404         | BIP000083 | Not Found   | Batch payment not found by batch payment key.                                                      | Lote de pagamentos não encontrado pela chave do lote.                                                     |
| 400         | BIP000085 | Bad Request | Batch payment status is not pending approval.                                                      | Status do lote de pagamentos não é de aprovação pendente.                                                 |

---

# Reenviar token de autenticação de dois fatores de agendamento em lote de fatura de recolhimento

URL: /documentation/baas/cobranca/2fa_v2/agendamento/reenviar_token_de_agendamento_em_lote_de_fatura_de_recolhimento

Este endpoint permite **reenviar** o token de autenticação de dois fatores (2FA) para um lote de agendamento de faturas de recolhimento que esteja em `batch_payment_schedule_status` **`pending_2fa_approval`**.

:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::

## Request

### Request Endpoint

ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payment/schedule_collection_slip/ BATCH_PAYMENT_SCHEDULE_KEY /resend_token
MÉTODO PATCH

### Request Path Params

| Campo                 | Tipo  | Descrição                                                                                | Caracteres |
| --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- |
| `account_key` *       | uuid4 | Chave única de identificação da conta.                                                   | 36         |
| `batch_payment_schedule_key` * | uuid4 | Chave única de identificação do lote de agendamento. | 36         |

### Request Body

Request Body (opcional)

```json
{
  "contact_type": "sms"
}
```

### Body Params

| Campo          | Tipo       | Descrição                               | Caracteres                                              |
| -------------- | ---------- | --------------------------------------- | ------------------------------------------------------- |
| `contact_type` | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** |

:::info Informação
Caso não seja enviado um `contact_type`, o token será enviado da forma solicitada originalmente no agendamento do lote (`tfa_info.contact_type`).
:::

### Enumerador contact_type

| Enumerador | Descrição                                         |
| ---------- | ------------------------------------------------- |
| **sms**    | Envio por mensagem de texto para telefone celular |
| **email**  | Envio por correio eletrônico                      |

## Response

### Success Response

STATUS 200

Response Body: Token reenviado com sucesso

```json
{
  "batch_payment_schedule_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
  "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
  "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "total_amount": 1939.31,
  "batch_payment_schedule_status": "pending_2fa_approval",
  "payment_type": "collection_slip"
}
```

### Response Body Params

| Campo                   | Tipo   | Descrição |
| ----------------------- | ------ | --------- |
| `batch_payment_schedule_key` *   | uuid4  | Chave única de identificação do agendamento em lote. |
| `request_control_key` * | uuid4  | Chave única de identificação da requisição do cliente (lote). |
| `account_key` *         | uuid4  | Chave da conta debitada. |
| `total_amount` *        | number | Soma dos valores dos itens do lote. |
| `batch_payment_schedule_status` *        | string | Após o reenvio, o lote permanece aguardando validação do token (`pending_2fa_approval`). |
| `payment_type` *        | string | Tipo do pagamento; para este fluxo, espera-se `collection_slip`. |

Em seguida, utilize [Confirmar agendamento em lote de fatura de recolhimento](./confirmar_agendamento_em_lote_de_fatura_de_recolhimento.md) para concluir o 2FA.

### Error Response

STATUS 4XX

Response Body

```json
{
  "title": "Título",
  "description": "Description in english",
  "translation": "Descrição em português",
  "code": "Código"
}
```

| Código HTTP | Código QI | Título      | Descrição (eng)                                                                                    | Descrição (pt-br)                                                                                         |
| ----------- | --------- | ----------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| 403         | BIP000010 | Forbidden   | User is not allowed to do this action                                                              | Usuário não tem autorização para fazer essa ação                                                          |
| 404         | BIP000011 | Not Found   | The source account key was not found.                                                              | A chave da conta de origem não foi encontrada.                                                            |
| 400         | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000059 | Bad Request | Number of verification token validation attempts exceeded.                                         | Número de tentativas de validação de token de verificação excedido.                                       |
| 400         | BIP000064 | Bad Request | Error resending verification token                                                                 | Erro ao reenviar token de verificação                                                                     |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded.                                                         | Janela de tempo de verificação de pagamento excedida.                                                     |
| 404         | BIP000083 | Not Found   | Batch payment not found by batch payment key.                                                      | Lote de pagamentos não encontrado pela chave do lote.                                                     |
| 400         | BIP000085 | Bad Request | Batch payment status is not pending approval.                                                      | Status do lote de pagamentos não é de aprovação pendente.                                                 |

---

# Solicitar Agendamento de Pagamento de Boleto Bancário com Autenticação de Dois Fatores (2FA)

URL: /documentation/baas/cobranca/2fa_v2/agendamento/solicitar_agendamento_de_boleto_bancario

Este endpoint permite realizar a solicitação de agendamento de pagamento de boletos bancários. 
A solicitação deve ser realizado após a consulta, utilizando as informações retornadas 
para garantir o funcionamento correto do fluxo, evitando falhas durante o processo.

:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). 
Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de 
pagamento autorizadas a funcionar pelo Banco Central.
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/bank_slip
MÉTODO POST

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |

Request Body: Solicitação de agendamento com linha digitável

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "digitable_line": "00190000090361557400500000024174396700000991000",
  "payment_amount": 1156.8,
  "payment_date": "2024-03-30",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```
Request Body: Solicitação de agendamento com código de barras

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "barcode": "00190000090361557400500000024174396700000991000",
  "payment_amount": 1156.8,
  "payment_date": "2024-03-30",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```

### Body Params

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | Chave única de identificação da request do cliente. |    
| `barcode`               | string    | Código de barras. |
| `digitable_line`        | string    | Linha digitável. |
| `payment_amount` *      | number    | Valor a ser pago. |
| `payment_date` *        | string | Data do agendamento.                                |
| `tfa_info` *            | [object](#objeto-tfa_info)    | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato. | 

:::danger Aviso
O `payment_amount` deve sempre igual ao `total_amount` retornado na consulta do boleto bancário caso o pagamento parcial não seja permitido para o boleto bancário. Para títulos em que o pagamento parcial é permitido, o cliente pode escolher o `payment_amount`, desde que a soma do mesmo com o `registered_payment_amount` do boleto bancário não seja superior que o `total_amount`.
:::

### Objeto tfa_info
| Campo                       | Tipo    | Descrição                         |
|-----------------------------|---------|-----------------------------------|
| `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta. | 
| `contact_type`*             | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** |

| Enumerador | Descrição                                         |
|------------|---------------------------------------------------|
| **sms**    | Envio por Mensagem de Texto para telefone celular |
| **email**  | Envio por correio eletrônico                      |

## Response

### Success Response

STATUS 201

Response Body: Agendamento pendente de aprovação de dois fatores

```json
{
   "payment_schedule_key":"c4325104-d60b-44f3-aae4-49155564a2ea",
   "request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189",
   "payer_name":"COOPERATIVA INDUSTRIAL MURILO",
   "payer_document_number":"00037025000160",
   "source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
   "paid_amount":1050.1,
   "payment_date":"2024-04-03",
   "payment_type":"bank_slip",
   "bank_slip": {
        "barcode":"00193967000009910000000003615574000000002417",
        "digitable_line":"00190000090361557400500000024174396700000991000",
        "payer_name":"COOPERATIVA TESTE",
        "payer_document_number":"00037025000160",
        "beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
        "beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
        "beneficiary_document_number":"52069937000117",
        "beneficiary_bank_ispb":"00000000",
        "guarantor_name":null,
        "guarantor_document_number":null,
        "expiration_date":"2024-03-29",
        "max_payment_data": "2026-03-29",
        "partial_payment_indicator":"allowed",
        "registered_payment_amount":9029.0,
        "nominal_amount":9910.0,
        "total_amount":10129.1,
        "rebate_amount":0.0,
        "discount_amount":0.0,
        "fine_amount":0.0,
        "interest_amount":219.1
    },
   "collection_slip":null,
   "payment_schedule_status":"pending_2fa_approval"
}
```

### Response Body Params

| Campo               | Tipo    | Descrição                                           |
|---------------------|---------|-----------------------------------------------------|
| `payment_key` *               | uuid4 | Chave única de identificação do pagamento.          |
| `request_control_key` *       | uuid4 | Chave única de identificação da request do cliente. |
| `payer_name` *                | string | Nome do pagador efetivo.                            |
| `payer_document_number` *     | string | Número do documento do pagador efetivo  (CPF/CNPJ). |
| `source_account_key` *        | uuid4 | Chave da conta debitada.                            |
| `transaction_key` *           | uuid4 | Chave da transação do pagamento.                    |
| `transaction_revert_key`      | uuid4 | Chave da transação de reversão do pagamento.        |
| `paid_amount` *               | number | Valor pago efetivamente.                            |
| `payment_date` *              | string | Data do agendamento.                                |
| `payment_type` *              | [enum](#enumeradores-payment_type) | Tipo do pagamento.                                  |
| `bank_slip`                   | [object](#objeto-bank_slip) | Boleto bancário.                                    |
| `collection_slip`             | object | Fatura de recolhimento.                             |
| `payment_schedule_status` *            | [enum](#enumeradores-payment_schedule_status) | Status do agendamento.                              |

### Enumeradores payment_type
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

:::danger Aviso
O enumerador `collection_slip` não se aplica para o fluxo de boletos bancários, assim como o objeto collection_slip que sempre será nulo.
:::

### Enumeradores payment_schedule_status
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `pending_2fa_approval`    | string  | pendente de aprovação de dois fatores |

### Objeto bank_slip
| Campo                             | Tipo    | Descrição                         |
|-----------------------------------|---------|-----------------------------------|
| `barcode` *                       | string | Código de barras. |
| `digitable_line` *                | string | Linha digitável. |
| `payer_name` *                    | string | Nome do pagador.|
| `payer_document_number` *         | string | Número do documento do pagador (CPF/CNPJ). |
| `beneficiary_name` *              | string | Nome do beneficiário. |
| `beneficiary_trading_name`        | string | Nome fantasia do beneficiário. |
| `beneficiary_document_number` *   | string | Número do documento do beneficiário (CPF/CNPJ). |
| `beneficiary_bank_ispb` *         | string | Código ispb do banco do beneficiário. |
| `guarantor_name`                  | string | Nome do sacador avalista. |
| `guarantor_document_number`       | string | Número do documento do sacador avalista (CPF/CNPJ). |
| `expiration_date` *               | string | Data de vencimento. |
| `max_payment_date` * | string  | Data máxima de pagamento. |
| `partial_payment_indicator` *     | [enum](#enumeradores-partial_payment_indicator)   | Indicador de pagamento parcial. |
| `registered_payment_amount`       | string | Valor total de pagamento registrado. |
| `nominal_amount` *                | number | Valor original. |
| `total_amount` *                  | number | Valor total. |
| `rebate_amount` *                 | number | Valor do abatimento. |
| `discount_amount` *               | number | Valor do desconto. |
| `fine_amount` *                   | number | Valor da multa. |
| `interest_amount` *               | number | Valor do juros. |

### Enumeradores partial_payment_indicator
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `allowed`     | string    | Permitido     |
| `not_allowed` | string    | Não permitido |

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400         | BIP000001 | Bad Request | The barcode or digitable line must have 44 or 47 characters. | O código de barras ou linha digitável deve ter 44 ou 47 caracteres. |
| 400         | BIP000002 | Bad Request | The bill sent does not correspond to a bank slip. | A conta enviado não corresponde a um boleto bancário. |
| 400         | BIP000003 | Bad Request | The digitable line sent is invalid. | A linha digitável enviada é inválida. |
| 404         | BIP000004 | Not Found | The bank slip was not found. | O boleto não foi encontrado. |
| 400         | BIP000005 | Bad Request | It was not possible to consult the bank slip at this time. Please try again in a few minutes. | Não foi possível consultar o boleto neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000006 | Bad Request | Bank slip already written off | Boleto já baixado |
| 400         | BIP000007 | Bad Request | Bank slip blocked for payment | Boleto bloqueado para pagamento |
| 400         | BIP000008 | Bad Request | Bank slip already paid | Boleto já pago |
| 400         | BIP000009 | Bad Request | Invalid bank slip. Please consult issuing bank | Boleto inválido. Favor consultar banco emissor |
| 403         | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404         | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400         | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400         | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 400         | BIP000015 | Bad Request | Payment date is greater than the maximum payment date. | A data de pagamento é maior que a data máxima de pagamento. |
| 400         | BIP000016 | Bad Request | Payment date is smaller than the calculation date. | A data de pagamento é menor que a data de cálculo. |
| 400         | BIP000017 | Bad Request | Invalid payment amount. | Valor de pagamento inválido. |
| 400         | BIP000018 | Bad Request | Partial payment is not allowed. | Pagamento parcial não é permitido. |
| 400         | BIP000019 | Bad Request | The payment amount is greater than the available amount. | O valor do pagamento é maior que o valor disponível. |
| 400         | BIP000020 | Bad Request | All partial payments for this bank slip have already been made. | Todos os pagamentos parciais deste boleto já foram realizados. |
| 400         | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 403         | BIP000052 | Forbidden | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta |
| 400         | BIP000053 | Bad Request | Error getting approver data | Erro ao obter dados do aprovador |
| 400         | BIP000054 | Bad Request | TFA info required | Informações de TFA necessárias |
| 400         | BIP000055 | Bad Request | Error sending verification token | Erro ao enviar token de verificação |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |

## Ambiente de Sandbox

Em nosso ambiente de sandbox, disponibilizamos linhas digitáveis mockadas para a simulação de pagamentos bem-sucedidos e testes de cenários de erro.

| Linha digitável |
|-----------------|
| 00190000090361557400500000024174396700000991000 |
| 00190000090282802601919212747174596760001294161 |
| 23793390014000000455277000249001596900000103995 |
| 75691434020137513680900001040013196770002417240 |
| 21390001171200000570700168167484796770000148206 |
| 34191090083273252027893634770007296690012513600 |
| 42297048060005815702500130494123896770000239491 |
| 07090010287045349010776686070590896770001160123 |
| 74891123702849020818918378871083196690000050000 |
| 23792374119000209350986000372408496610000122810 |

---

# Solicitar Agendamento de Pagamento de Facutara de Recolhimento com Autenticação de Dois Fatores (2FA)

URL: /documentation/baas/cobranca/2fa_v2/agendamento/solicitar_agendamento_de_pagamento_de_fatura_de_recolhimento

Este endpoint permite realizar a solicitação de agendamento de pagamento de faturas de recolhimento com autenticação de dois fatores. 
A solicitação deve ser realizado após a consulta, utilizando as informações retornadas para garantir o funcionamento correto do fluxo,
evitando falhas durante o processo.

:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/collection_slip
MÉTODO POST

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |

Request Body: Solicitação de com linha digitável

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "digitable_line": "00190000090361557400500000024174396700000991000",
  "payment_amount": 1156.8,
  "payment_date": "2024-03-30",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```
Request Body: Solicitação de agendamento com código de barras

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "barcode": "00190000090361557400500000024174396700000991000",
  "payment_amount": 1156.8,
  "payment_date": "2024-03-30",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```

### Body Params

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | Chave única de identificação da request do cliente. |    
| `barcode`               | string    | Código de barras. |
| `digitable_line`        | string    | Linha digitável. |
| `payment_amount` *      | number    | Valor a ser pago. |
| `tfa_info` *            | [object](#objeto-tfa_info)    | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato. | 

:::danger Aviso
O `payment_amount` deve sempre igual ao `total_amount` retornado na consulta do boleto bancário.
:::

### Objeto tfa_info
| Campo                       | Tipo    | Descrição                         |
|-----------------------------|---------|-----------------------------------|
| `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta (CPF/CNPJ). | 
| `contact_type`*             | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** |

| Enumerador | Descrição                                         |
|------------|---------------------------------------------------|
| **sms**    | Envio por Mensagem de Texto para telefone celular |
| **email**  | Envio por correio eletrônico                      |

## Response

### Success Response

STATUS 201

Response Body: Agendamento pendente de aprovação de dois fatores

```json
{
  "payment_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
  "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
  "payer_name": "COOPERATIVA INDUSTRIAL MURILO",
  "payer_document_number": "62069937000118",
  "source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "paid_amount": 1389.21,
  "payment_date": "2024-04-30",
  "payment_type": "collection_slip",
  "bank_slip": null,
  "collection_slip": {
    "barcode": null,
    "digitable_line": "836200000138892100450006762142420244046000010192",
    "collection_name": "CIA ULTRAGAZ SA-COD",
    "collection_document_number": "00394460005887",
    "expiration_date": "2024-04-15",
    "total_amount": 1389.21
  },
  "payment_schedule_status": "pending_2fa_approval"
}
```

### Response Body Params

| Campo               | Tipo    | Descrição                                           |
|---------------------|---------|-----------------------------------------------------|
| `payment_key` *               | uuid4 | Chave única de identificação do pagamento.          |
| `request_control_key` *       | uuid4 | Chave única de identificação da request do cliente. |
| `payer_name` *                | string | Nome do pagador efetivo.                            |
| `payer_document_number` *     | string | Documento do pagador efetivo (CPF/CNPJ).            |
| `source_account_key` *        | uuid4 | Chave da conta debitada.                            |
| `transaction_key` *           | uuid4 | Chave da transação do pagamento.                    |
| `transaction_revert_key`      | uuid4 | Chave da transação de reversão do pagamento.        |
| `paid_amount` *               | number | Valor pago efetivamente.                            |
| `payment_date` *              | string | Data do agendamento.                                |
| `payment_type` *              | [enum](#enumeradores-payment_type) | Tipo do pagamento.                                  |
| `bank_slip`                   | object | Boleto bancário.                                    |
| `collection_slip`             | [object](#objeto-collection_slip) | Fatura de recolhimento.                             |
| `payment_schedule_status` *            | [enum](#enumeradores-payment_schedule_status) | Status do agendamento.                              |

### Enumeradores payment_type
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

:::danger Aviso
O enumerador `bank_slip` não se aplica para o fluxo de faturas de recolhimento, assim como o objeto bank_slip que sempre será nulo.
:::

### Enumeradores payment_schedule_status
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `pending_2fa_approval`    | string  | pendente de aprovação de dois fatores |

### Objeto collection_slip
| Campo                             | Tipo    | Descrição                         |
|-----------------------------------|---------|-----------------------------------|
| `barcode`          | string | Código de barras. |
| `digitable_line`   | string | Linha digitável. |
| `collection_name` *         | string | Nome do convênio.|
| `collection_document_number`   | string | Número de documento do convênio (CPF/CNPJ).|
| `expiration_date` *  | string  | Data de vencimento. |
| `total_amount` *  | number | Valor total. |

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400         | BIP000032 | Bad Request | The bill sent does not correspond to a collection slip. | A conta enviada não corresponde a uma fatura de recolhimento. |
| 400         | BIP000033 | Bad Request | The barcode or digitable line of the collection slip must have 44 or 48 characters. | O código de barras ou linha digitável da fatura de recolhimento deve ter 44 ou 48 caracteres. |
| 403         | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404         | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400         | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400         | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 400         | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 400         | BIP000028 | Bad Request | The source account has blocked balance. Payment cannot be made. | A conta de origem possui saldo em conta bloqueado. Pagamento não pode ser realizado. |
| 400         | BIP000034 | Bad Request | Collection slip already paid. | Fatura de recolhimento já paga. |
| 400         | BIP000035 | Bad Request | Covenant slip invalid barcode. | Código de barras da fatura de recolhimento inválido. |
| 400         | BIP000036 | Bad Request | Covenant slip overdue. | Fatura de recolhimento vencida. |
| 400         | BIP000037 | Bad Request | Error in collection slip consultation. | Erro na consulta da fatura de recolhimento. |
| 400         | BIP000038 | Bad Request | Outside of covenant payment hours. | Fora do horário de pagamento do convênio. |
| 400         | BIP000039 | Bad Request | Collection slip not accepted. | Fatura de recolhimento não aceita. |
| 400         | BIP000040 | Bad Request | Minimum advance not reached. | Mínimo de dias de adiantamento não atingido. |
| 400         | BIP000041 | Bad Request | Max payment amount exceeded. | Valor máximo de pagamento excedido. |
| 400         | BIP000044 | Bad Request | It was not possible to pay the collection slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar a fatura de recolhimento neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. |
| 403         | BIP000052 | Forbidden | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta |
| 400         | BIP000053 | Bad Request | Error getting approver data | Erro ao obter dados do aprovador |
| 400         | BIP000054 | Bad Request | TFA info required | Informações de TFA necessárias |
| 400         | BIP000055 | Bad Request | Error sending verification token | Erro ao enviar token de verificação |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |

## Ambiente de Sandbox

Em nosso ambiente de sandbox, disponibilizamos linhas digitáveis mockadas para a simulação de pagamentos bem-sucedidos e testes de cenários de erro.

| Linha digitável |
|---|
| 828300000007411100972013905080001546763201900028 |
| 838000000009235700481007241345219112001474229880 |
| 848000000006308600802021201071261517689002201070 |
| 858200000015000000643025703477209504800448091020 |
| 858500000037350000643217212883260006147448091022 |

---

# Solicitar agendamento em lote de boleto bancário com autenticação de dois fatores (2FA)

URL: /documentation/baas/cobranca/2fa_v2/agendamento/solicitar_agendamento_em_lote_de_boleto_bancario

Este endpoint permite solicitar o **agendamento em lote** de boletos bancários em uma única requisição, com autenticação de dois fatores quando aplicável.

:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::

## Request

### Request Endpoint

ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments_schedule/batch_bank_slip
MÉTODO POST

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |

Request Body: Agendamento em lote de boletos bancários

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "bank_slip_payment_schedules": [
    {
      "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
      "digitable_line": "00190000090361557400500000024174396700000991000",
      "payment_amount": 1156.8,
      "payment_date": "2026-04-10"
    },
    {
      "request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e",
      "barcode": "00190000090361557400500000024174396700000991000",
      "payment_amount": 200.5,
      "payment_date": "2026-04-15"
    }
  ],
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```

### Body Params

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | Chave única de identificação da requisição do cliente (lote). |
| `bank_slip_payment_schedules` * | array     | Lista de agendamentos de boleto bancário. Limite de **1000** itens por requisição. |
| `tfa_info` *            | [object](#objeto-tfa_info)    | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato. |

Cada elemento de `bank_slip_payment_schedules` deve conter:

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | Chave única de identificação da requisição do cliente para aquele item do lote. |
| `barcode`               | string    | Código de barras. |
| `digitable_line`        | string    | Linha digitável. |
| `payment_amount` *      | number    | Valor a ser pago. |
| `payment_date` *        | string    | Data do agendamento do item. |

:::danger Aviso
Para cada item, o `payment_amount` deve seguir as regras do título retornadas na consulta do boleto bancário. Se o pagamento parcial não for permitido, o valor deve corresponder ao total atualizado do título.
:::

### Objeto tfa_info

| Campo                       | Tipo    | Descrição                         |
|-----------------------------|---------|-----------------------------------|
| `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta (CPF/CNPJ). |
| `contact_type`*             | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** |

| Enumerador | Descrição                                         |
|------------|---------------------------------------------------|
| **sms**    | Envio por mensagem de texto para telefone celular |
| **email**  | Envio por correio eletrônico                      |

## Response

### Success Response

STATUS 202

Response Body: Lote de agendamento pendente de aprovação de dois fatores

```json
{
  "batch_payment_schedule_key": "c4325104-d60b-44f3-aae4-49155564a2ea",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
  "total_amount": 1357.3,
  "batch_payment_schedule_status": "pending_2fa_approval",
  "payment_type": "bank_slip"
}
```

### Response Body Params

| Campo               | Tipo    | Descrição                         |
|---------------------|---------|-----------------------------------|
| `batch_payment_schedule_key` *       | uuid4 | Chave única de identificação do agendamento em lote. |
| `request_control_key` *     | uuid4 | Chave única de identificação da requisição do cliente (lote). |
| `account_key` *             | uuid4 | Chave da conta debitada. |
| `total_amount` *            | number | Soma dos valores (`payment_amount`) dos itens do lote. |
| `batch_payment_schedule_status` *         | [enum](#enumeradores-batch_payment_schedule_status) | Status do lote de agendamento após a solicitação. |
| `payment_type` *            | [enum](#enumeradores-payment_type) | Tipo do pagamento. |

### Enumeradores batch_payment_schedule_status

| Enumerador    | Descrição     |
|---------------|---------------|
| `pending_2fa_approval` | Pendente de aprovação 2FA |
| `scheduled`   | Agendado |
| `rejected`    | Rejeitado |
| `error`       | Erro ao agendar |

### Enumeradores payment_type

| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

:::danger Aviso
O enumerador `collection_slip` não se aplica ao fluxo de agendamento em lote de boletos bancários deste endpoint; para este caso, espera-se `payment_type` com valor `bank_slip`.
:::

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 403         | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404         | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400         | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 400         | BIP000052 | Bad Request | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta |
| 400         | BIP000053 | Bad Request | Error getting approver data | Erro ao obter dados do aprovador |
| 400         | BIP000054 | Bad Request | TFA info required | Informações de TFA necessárias |
| 400         | BIP000055 | Bad Request | Error sending verification token | Erro ao enviar token de verificação |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |

---

# Solicitar agendamento em lote de fatura de recolhimento com autenticação de dois fatores (2FA)

URL: /documentation/baas/cobranca/2fa_v2/agendamento/solicitar_agendamento_em_lote_de_fatura_de_recolhimento

Este endpoint permite solicitar o **agendamento em lote** de faturas de recolhimento (convênio/tributo) em uma única requisição, com autenticação de dois fatores quando aplicável.

:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::

## Request

### Request Endpoint

ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments_schedule/batch_collection_slip
MÉTODO POST

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |

Request Body: Agendamento em lote de faturas de recolhimento

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "collection_slip_payment_schedules": [
    {
      "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
      "digitable_line": "836200000138892100450006762142420244046000010192",
      "payment_amount": 1389.21,
      "payment_date": "2026-04-10"
    },
    {
      "request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e",
      "barcode": "836200000138892100450006762142420244046000010192",
      "payment_amount": 550.10,
      "payment_date": "2026-04-15"
    }
  ],
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```

### Body Params

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | Chave única de identificação da requisição do cliente (lote). |
| `collection_slip_payment_schedules` * | array     | Lista de agendamentos de fatura de recolhimento. Limite de **1000** itens por requisição. |
| `tfa_info` *            | [object](#objeto-tfa_info)    | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato. |

Cada elemento de `collection_slip_payment_schedules` deve conter:

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | Chave única de identificação da requisição do cliente para aquele item do lote. |
| `barcode`               | string    | Código de barras. |
| `digitable_line`        | string    | Linha digitável. |
| `payment_amount` *      | number    | Valor a ser pago. |
| `payment_date` *        | string    | Data do agendamento do item. |

### Objeto tfa_info

| Campo                       | Tipo    | Descrição                         |
|-----------------------------|---------|-----------------------------------|
| `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta (CPF/CNPJ). |
| `contact_type`*             | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** |

| Enumerador | Descrição                                         |
|------------|---------------------------------------------------|
| **sms**    | Envio por mensagem de texto para telefone celular |
| **email**  | Envio por correio eletrônico                      |

## Response

### Success Response

STATUS 202

Response Body: Lote de agendamento pendente de aprovação de dois fatores

```json
{
  "batch_payment_schedule_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
  "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
  "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "total_amount": 1939.31,
  "batch_payment_schedule_status": "pending_2fa_approval",
  "payment_type": "collection_slip"
}
```

### Response Body Params

| Campo               | Tipo    | Descrição                         |
|---------------------|---------|-----------------------------------|
| `batch_payment_schedule_key` *       | uuid4 | Chave única de identificação do agendamento em lote. |
| `request_control_key` *     | uuid4 | Chave única de identificação da requisição do cliente (lote). |
| `account_key` *             | uuid4 | Chave da conta debitada. |
| `total_amount` *            | number | Soma dos valores (`payment_amount`) dos itens do lote. |
| `batch_payment_schedule_status` *         | [enum](#enumeradores-batch_payment_schedule_status) | Status do lote de agendamento após a solicitação. |
| `payment_type` *            | [enum](#enumeradores-payment_type) | Tipo do pagamento. |

### Enumeradores batch_payment_schedule_status

| Enumerador    | Descrição     |
|---------------|---------------|
| `pending_2fa_approval` | Pendente de aprovação 2FA |
| `scheduled`   | Agendado |
| `rejected`    | Rejeitado |
| `error`       | Erro ao agendar |

### Enumeradores payment_type

| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

:::danger Aviso
O enumerador `bank_slip` não se aplica ao fluxo de agendamento em lote de faturas de recolhimento deste endpoint; para este caso, espera-se `payment_type` com valor `collection_slip`.
:::

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400         | BIP000032 | Bad Request | The bill sent does not correspond to a collection slip. | A conta enviada não corresponde a uma fatura de recolhimento. |
| 400         | BIP000033 | Bad Request | The barcode or digitable line of the collection slip must have 44 or 48 characters. | O código de barras ou linha digitável da fatura de recolhimento deve ter 44 ou 48 caracteres. |
| 403         | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404         | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400         | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 403         | BIP000052 | Forbidden | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta |
| 400         | BIP000053 | Bad Request | Error getting approver data | Erro ao obter dados do aprovador |
| 400         | BIP000054 | Bad Request | TFA info required | Informações de TFA necessárias |
| 400         | BIP000055 | Bad Request | Error sending verification token | Erro ao enviar token de verificação |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |

---

# Confirmação de lote de pagamento de boleto bancário

URL: /documentation/baas/cobranca/2fa_v2/confirmacao_de_lote_de_boleto_bancario

Este documento descreve a **mesma rota** de [Confirmação de lote de pagamento de boleto bancário](../confirmacao_de_lote_de_boleto_bancario.md) quando a operação exige **autenticação de dois fatores (2FA)** na etapa de confirmação: o corpo da requisição deve incluir **`tfa_info`** junto com `batch_status: approved` ou `batch_status: rejected`. Em seguida, o lote pode ficar em `pending_2fa_approval` (aprovação) ou `pending_2fa_rejection` (rejeição) até a **validação do token**.

:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::

## Request

### Request Endpoint

ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_bank_slip/**PAYMENT_BATCH_KEY**/confirmation
MÉTODO PATCH

### Request Path Params

| Campo                 | Tipo  | Descrição                                                                                | Caracteres |
| --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- |
| `account_key` *       | uuid4 | Chave única de identificação da conta.                                                   | 36         |
| `payment_batch_key` * | uuid4 | Chave única de identificação do lote (`batch_payment_key` retornado na criação do lote). | 36         |

### Request Body

**Request Body: Rejeição do lote (com `tfa_info`)**

```json
{
  "batch_status": "rejected",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```

**Request Body: Aprovação do lote (com `tfa_info`)**

```json
{
  "batch_status": "approved",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```

### Body Params

| Campo            | Tipo   | Descrição                                                                                                                                                                                                                                                                                                                                              |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `batch_status` * | string | Decisão sobre o lote. Valores: `approved` (seguir com o processamento) ou `rejected` (cancelar o lote). Ver [enumerador batch_confirmation_status](#enumerador-batch_confirmation_status).                                                                                                                                                     |
| `tfa_info`       | object | Obrigatório neste fluxo com `batch_status: approved` ou `batch_status: rejected`; informe aprovador e canal de envio do token em [objeto tfa_info](#objeto-tfa_info). |

### Enumerador batch_confirmation_status

| Valor      | Descrição                                                     |
| ---------- | ------------------------------------------------------------- |
| `approved` | Aprovar o lote e continuar o fluxo de processamento.          |
| `rejected` | Rejeitar o lote; não há processamento assíncrono dos boletos. |

### Objeto tfa_info

| Campo                        | Tipo   | Descrição                                                                                                                                          |
| ---------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `approver_document_number` * | string | Documento (CPF) da pessoa aprovadora que receberá o token. Obrigatório quando `tfa_info` é enviado.                                                |
| `contact_type` *             | string | Canal para envio do token (por exemplo `sms` ou `email`), conforme regras da operação e cadastro. Obrigatório quando `tfa_info` é enviado. |

## Response

O status HTTP e o campo `batch_status` na resposta dependem da decisão enviada e de o fluxo exigir validação do token após esta chamada.

### Resposta: lote rejeitado — pendência de validação do token (2FA)

STATUS 202

Quando `batch_status` no corpo da requisição é `rejected` e a requisição inclui `tfa_info`, a API responde com **202**. O lote fica aguardando validação do token; o corpo retorna `batch_status` como `pending_2fa_rejection`. Após a validação do token, a decisão de rejeição é aplicada.

**Response Body: Lote aguardando validação do token (decisão de rejeição)**

```json
{
  "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
  "total_amount": 1357.3,
  "batch_status": "pending_2fa_approval",
  "payment_type": "bank_slip"
}
```

### Resposta: lote aprovado — pendência de validação do token (2FA)

STATUS 202

Quando `batch_status` no corpo é `approved` e a requisição inclui `tfa_info`, a API responde com **202**. O lote fica aguardando validação do token; o corpo retorna `batch_status` como `pending_2fa_approval`. Os passos seguintes (envio do código, validação e reenvio) estão em [Validação de token de lote de pagamento de boleto bancário](./validacao_de_token_de_lote_de_boleto_bancario.md) e [Reenviar token de confirmação de lote de pagamento de boleto bancário](./solicitacao_de_reenvio_de_token_de_lote_de_boleto_bancario.md).

**Response Body: Lote aguardando validação do token**

```json
{
  "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
  "total_amount": 1357.3,
  "batch_status": "pending_2fa_rejection",
  "payment_type": "bank_slip"
}
```

### Response Body Params

| Campo                   | Tipo   | Descrição                                                                                                                                                                                                                                                                     |
| ----------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batch_payment_key` *   | uuid4  | Chave única de identificação do pagamento em lote.                                                                                                                                                                                                                            |
| `request_control_key` * | uuid4  | Chave única de identificação da requisição do cliente (lote).                                                                                                                                                                                                                 |
| `account_key` *         | uuid4  | Chave da conta debitada.                                                                                                                                                                                                                                                      |
| `total_amount` *        | number | Soma dos valores dos itens do lote.                                                                                                                                                                                                                                           |
| `batch_status` *        | string | Nesta chamada, o lote permanece em `pending_2fa_approval` (aprovação) ou `pending_2fa_rejection` (rejeição) até a validação do token. Após a validação, o status final reflete a decisão enviada na confirmação (`approved` ou `rejected`). |
| `payment_type` *        | string | Tipo do pagamento; para este fluxo, espera-se `bank_slip`.                                                                                                                                                                                                                    |

### Error Response

STATUS 4XX

**Response Body**

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título      | Descrição (eng)                               | Descrição (pt-br)                                     |
| ----------- | --------- | ----------- | --------------------------------------------- | ----------------------------------------------------- |
| 400         | BIP000013 | Bad Request | The source account is closed.                 | A conta de origem está fechada.                       |
| 400         | BIP000050 | Bad Request | Requester configuration does not exist        | Configuração do requester não existe.                 |
| 400         | BIP000054 | Bad Request | TFA info required.                            | Informações de TFA necessárias.                       |
| 404         | BIP000083 | Not Found   | Batch payment not found by batch payment key. | Lote de pagamentos não encontrado pela chave do lote. |
| 400         | BIP000084 | Bad Request | Batch payment status is not pending.          | O status do lote de pagamentos não está pendente.     |

---

# Confirmação de lote de pagamento de fatura de recolhimento (convênio/tributo)

URL: /documentation/baas/cobranca/2fa_v2/confirmacao_de_lote_de_fatura_de_recolhimento

Este documento descreve a **mesma rota** de [Confirmação de lote de pagamento de fatura de recolhimento (convênio/tributo)](../confirmacao_de_lote_de_fatura_de_recolhimento.md) quando a operação exige **autenticação de dois fatores (2FA)** na etapa de confirmação: o corpo da requisição deve incluir **`tfa_info`** junto com `batch_status: approved` ou `batch_status: rejected`. Em seguida, o lote pode ficar em `pending_2fa_approval` (aprovação) ou `pending_2fa_rejection` (rejeição) até a **validação do token**.

:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um boleto bancário apresenta.
:::

## Request

### Request Endpoint

ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_collection_slip/**PAYMENT_BATCH_KEY**/confirmation
MÉTODO PATCH

### Request Path Params

| Campo                 | Tipo  | Descrição                                                                                | Caracteres |
| --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- |
| `account_key` *       | uuid4 | Chave única de identificação da conta.                                                   | 36         |
| `payment_batch_key` * | uuid4 | Chave única de identificação do lote (`batch_payment_key` retornado na criação do lote). | 36         |

### Request Body

**Request Body: Rejeição do lote (com `tfa_info`)**

```json
{
  "batch_status": "rejected",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```

**Request Body: Aprovação do lote (com `tfa_info`)**

```json
{
  "batch_status": "approved",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```

### Body Params

| Campo            | Tipo   | Descrição                                                                                                                                                                                                                                                                                                                                              |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `batch_status` * | string | Decisão sobre o lote. Valores: `approved` (seguir com o processamento) ou `rejected` (cancelar o lote). Ver [enumerador batch_confirmation_status](#enumerador-batch_confirmation_status).                                                                                                                                                     |
| `tfa_info`       | object | Obrigatório neste fluxo com `batch_status: approved` ou `batch_status: rejected`; informe aprovador e canal de envio do token em [objeto tfa_info](#objeto-tfa_info). |

### Enumerador batch_confirmation_status

Valores aceitos no corpo da requisição para `batch_status`:

| Valor      | Descrição                                                                     |
| ---------- | ----------------------------------------------------------------------------- |
| `approved` | Aprovar o lote e continuar o fluxo de processamento.                          |
| `rejected` | Rejeitar o lote; não há processamento assíncrono das faturas de recolhimento. |

### Objeto tfa_info

| Campo                        | Tipo   | Descrição                                                                                                                                          |
| ---------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `approver_document_number` * | string | Documento (CPF) da pessoa aprovadora que receberá o token. Obrigatório quando `tfa_info` é enviado.                                                |
| `contact_type` *             | string | Canal para envio do token (por exemplo `sms` ou `email`), conforme regras da operação e cadastro. Obrigatório quando `tfa_info` é enviado. |

## Response

O status HTTP e o campo `batch_status` na resposta dependem da decisão enviada e de o fluxo exigir validação do token após esta chamada.

### Resposta: lote rejeitado — pendência de validação do token (2FA)

STATUS 202

Quando `batch_status` no corpo da requisição é `rejected` e a requisição inclui `tfa_info`, a API responde com **202**. O lote fica aguardando validação do token; o corpo retorna `batch_status` como `pending_2fa_rejection`. Após a validação do token, a decisão de rejeição é aplicada.

**Response Body: Lote aguardando validação do token (decisão de rejeição)**

```json
{
  "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "total_amount": 2778.42,
  "batch_status": "pending_2fa_rejection",
  "payment_type": "collection_slip"
}
```

### Resposta: lote aprovado — pendência de validação do token (2FA)

STATUS 202

Quando `batch_status` no corpo é `approved` e a requisição inclui `tfa_info`, a API responde com **202**. O lote fica aguardando validação do token; o corpo retorna `batch_status` como `pending_2fa_approval`. Os passos seguintes estão em [Validação de token de lote de pagamento de fatura de recolhimento (convênio/tributo)](./validacao_de_token_de_lote_de_fatura_de_recolhimento.md) e [Reenviar token de confirmação de lote de pagamento de fatura de recolhimento (convênio/tributo)](./solicitacao_de_reenvio_de_token_de_lote_de_fatura_de_recolhimento.md).

**Response Body: Lote aguardando validação do token**

```json
{
  "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "total_amount": 2778.42,
  "batch_status": "pending_2fa_rejection",
  "payment_type": "collection_slip"
}
```

### Response Body Params

| Campo                   | Tipo   | Descrição                                                                                                                                                                                                                                                                                    |
| ----------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batch_payment_key` *   | uuid4  | Chave única de identificação do pagamento em lote.                                                                                                                                                                                                                                           |
| `request_control_key` * | uuid4  | Chave única de identificação da requisição do cliente (lote).                                                                                                                                                                                                                                |
| `account_key` *         | uuid4  | Chave da conta debitada.                                                                                                                                                                                                                                                                     |
| `total_amount` *        | number | Soma dos valores dos itens do lote.                                                                                                                                                                                                                                                          |
| `batch_status` *        | string | Nesta chamada, o lote permanece em `pending_2fa_approval` (aprovação) ou `pending_2fa_rejection` (rejeição) até a validação do token. Após a validação, o status final reflete a decisão enviada na confirmação (`approved` ou `rejected`). |
| `payment_type` *        | string | Tipo do pagamento; para este fluxo, espera-se `collection_slip`.                                                                                                                                                                                                                             |

### Error Response

STATUS 4XX

**Response Body**

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título      | Descrição (eng)                               | Descrição (pt-br)                                     |
| ----------- | --------- | ----------- | --------------------------------------------- | ----------------------------------------------------- |
| 400         | BIP000013 | Bad Request | The source account is closed.                 | A conta de origem está fechada.                       |
| 400         | BIP000050 | Bad Request | Requester configuration does not exist        | Configuração do requester não existe.                 |
| 400         | BIP000054 | Bad Request | TFA info required.                            | Informações de TFA necessárias.                       |
| 404         | BIP000083 | Not Found   | Batch payment not found by batch payment key. | Lote de pagamentos não encontrado pela chave do lote. |
| 400         | BIP000084 | Bad Request | Batch payment status is not pending.          | O status do lote de pagamentos não está pendente.     |

---

# Confirmação de Pagamento de Boleto Bancário

URL: /documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_boleto_bancario

Este endpoint permite realizar a confirmação do pagamento de boleto bancário.

:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::

## Request

### Request Endpoint

ENDPOINT /account/ ACCOUNT_KEY /payment/ PAYMENT_KEY /bank_slip/validate_token
MÉTODO PATCH

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |
| `payment_key` *     | uuid4   | Chave única de identificação do pagamento.  | 36     |

### Autenticação via Email e SMS

Request Body: Confirmação de pagamento de boleto bancário

```json
{
  "token": "329adf"
}
```

### Autenticação via Dispositivo

Para aprovar e finalizar a autenticação via dispositivo, a requisição deve ser enviada com um payload vazio. A validação ocorre internamente, sem necessidade de informações adicionais no corpo da requisição. É importante destacar que este endpoint só deve ser utilizado após a [solicitação de transação](./solicitacao_de_pagamento_de_boleto_bancario.md) ter sido iniciada.

Request Body: Confirmação de pagamento de boleto bancário

```json
{

}
```

### Body Params

| Campo     | Tipo   | Descrição                                                             | Caracteres |
|-----------|--------|-----------------------------------------------------------------------|------------|
| `token`   | string | Código de autenticação enviado ao aprovador de movimentações da conta **obrigatório para TFA via SMS ou e-mail**| 6          |

## Response

### Success Response

STATUS 200

Response Body: Pagamento executado

```json
{
   "payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea",
   "request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189",
   "payer_name":"COOPERATIVA INDUSTRIAL MURILO",
   "payer_document_number":"00037025000160",
   "source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
   "transaction_key":"4e80070a-a0bb-4be2-8178-55fbd73a3704",
   "transaction_revert_key":null,
   "paid_amount":1050.1,
   "payment_date":"2024-04-03",
   "payment_type":"bank_slip",
   "bank_slip": {
        "bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
        "barcode":"00193967000009910000000003615574000000002417",
        "digitable_line":"00190000090361557400500000024174396700000991000",
        "payer_name":"COOPERATIVA TESTE",
        "payer_document_number":"00037025000160",
        "beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
        "beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
        "beneficiary_document_number":"52069937000117",
        "beneficiary_bank_ispb":"00000000",
        "guarantor_name":null,
        "guarantor_document_number":null,
        "expiration_date":"2024-03-29",
        "max_payment_data": "2026-03-29",
        "partial_payment_indicator":"allowed",
        "registered_payment_amount":9029.0,
        "nominal_amount":9910.0,
        "total_amount":10129.1,
        "rebate_amount":0.0,
        "discount_amount":0.0,
        "fine_amount":0.0,
        "interest_amount":219.1
    },
   "collection_slip":null,
   "payment_status":"executed"
}
```

STATUS 202

Response Body: Pagamento pendente de execução

```json
{
   "payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea",
   "request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189",
   "payer_name":"COOPERATIVA INDUSTRIAL MURILO",
   "payer_document_number":"00037025000160",
   "source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
   "transaction_key":"4e80070a-a0bb-4be2-8178-55fbd73a3704",
   "transaction_revert_key":null,
   "paid_amount":1050.1,
   "payment_date":"2024-04-03",
   "payment_type":"bank_slip",
   "bank_slip": {
        "bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
        "barcode":"00193967000009910000000003615574000000002417",
        "digitable_line":"00190000090361557400500000024174396700000991000",
        "payer_name":"COOPERATIVA TESTE",
        "payer_document_number":"00037025000160",
        "beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
        "beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
        "beneficiary_document_number":"52069937000117",
        "beneficiary_bank_ispb":"00000000",
        "guarantor_name":null,
        "guarantor_document_number":null,
        "expiration_date":"2024-03-29",
        "max_payment_data": "2026-03-29",
        "partial_payment_indicator":"allowed",
        "registered_payment_amount":9029.0,
        "nominal_amount":9910.0,
        "total_amount":10129.1,
        "rebate_amount":0.0,
        "discount_amount":0.0,
        "fine_amount":0.0,
        "interest_amount":219.1
    },
   "collection_slip":null,
   "payment_status": "pending_execution"
}
```

:::info Informação
Caso seja retornado **HTTP Status 202** com o campo `payment_status` com valor **pending_execution**, o pagamento não deve ser retentado.

Este pagamento será processado assincronamente. É necessário verificar o status da transferência por meio
da consulta de pagamento, ou aguardar envio do webhook de pagamento pendente descrito na [página de webhooks](/documentation/baas/cobranca/webhooks).
:::

### Response Body Params

| Campo               | Tipo    | Descrição                         |
|---------------------|---------|-----------------------------------|
| `payment_key` *               | uuid4 | Chave única de identificação do pagamento. |
| `request_control_key` *       | uuid4 | Chave única de identificação da request do cliente. |
| `payer_name` *                | string | Nome do pagador efetivo.|
| `payer_document_number` *     | string | Número do documento do pagador efetivo (CPF/CNPJ). |
| `source_account_key` *        | uuid4 | Chave da conta debitada. |
| `transaction_key` *           | uuid4 | Chave da transação do pagamento. |
| `transaction_revert_key`      | uuid4 | Chave da transação de reversão do pagamento. |
| `paid_amount` *               | number | Valor pago efetivamente. |
| `payment_date` *              | string | Data do pagamento. |
| `payment_type` *              | [enum](#enumeradores-payment_type) | Tipo do pagamento. |
| `bank_slip`                   | [object](#objeto-bank_slip) | Boleto bancário. |
| `collection_slip`             | object | Fatura de recolhimento. |
| `payment_status` *            | [enum](#enumeradores-payment_status) | Status do pagamento. |

### Enumeradores payment_type
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

:::danger Aviso
O enumerador `collection_slip` não se aplica para o fluxo de boletos bancários, assim como o objeto collection_slip que sempre será nulo.
:::

### Enumeradores payment_status
| Enumerador    | Descrição     |
|---------------|---------------|
| `pending_execution`     | Pendente de execução |
| `executed`    | Executado |
| `reverted`    | Revertido |
| `rejected`    | Rejeitado |
| `error`       | Erro      |

:::danger Aviso
Para pagamentos aonde a QI não receber uma resposta da CIP em até dois minutos, o pagamento será retornado com o status `pending_execution`. Após a QI receber a resposta da CIP, será enviado para o cliente o webhook de pagamento pendente descrito na [página de webhooks](/documentation/baas/cobranca/webhooks).
:::

### Objeto bank_slip
| Campo                             | Tipo    | Descrição                         |
|-----------------------------------|---------|-----------------------------------|
| `barcode` *                       | string | Código de barras. |
| `digitable_line` *                | string | Linha digitável. |
| `payer_name` *                    | string | Nome do pagador.|
| `payer_document_number` *         | string | Número do documento do pagador (CPF/CNPJ). |
| `beneficiary_name` *              | string | Nome do beneficiário. |
| `beneficiary_trading_name`        | string | Nome fantasia do beneficiário. |
| `beneficiary_document_number` *   | string | Número do documento do beneficiário  (CPF/CNPJ). |
| `beneficiary_bank_ispb` *         | string | Código ispb do banco do beneficiário. |
| `guarantor_name`                  | string | Nome do sacador avalista. |
| `guarantor_document_number`       | string | Número do documento do sacador avalista (CPF/CNPJ). |
| `expiration_date` *               | string | Data de vencimento. |
| `max_payment_date` * | string  | Data máxima de pagamento. |
| `partial_payment_indicator` *     | [enum](#enumeradores-partial_payment_indicator)   | Indicador de pagamento parcial. |
| `registered_payment_amount`       | string | Valor total de pagamento registrado. |
| `nominal_amount` *                | number | Valor original. |
| `total_amount` *                  | number | Valor total. |
| `rebate_amount` *                 | number | Valor do batimento. |
| `discount_amount` *               | number | Valor do desconto. |
| `fine_amount` *                   | number | Valor da multa. |
| `interest_amount` *               | number | Valor do juros. |

### Enumeradores partial_payment_indicator
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `allowed`     | string    | Permitido     |
| `not_allowed` | string    | Não permitido |

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 403         | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404         | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400         | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400         | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 400         | BIP000022 | Bad Request | Bank slip payment service is closed. | Serviço de pagamento de boleto está fechado. |
| 400         | BIP000023 | Bad Request | The source account has insufficient balance. Payment cannot be made. | A conta de origem possui saldo insuficiente. Pagamento não pode ser realizado. |
| 400         | BIP000025 | Bad Request | It was not possible to pay the bank slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar o boleto neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. |
| 400         | BIP000028 | Bad Request | The source account has blocked balance. Payment cannot be made. | A conta de origem possui saldo em conta bloqueado. Pagamento não pode ser realizado. |
| 400         | BIP000029 | Bad Request | Bank slip payment write off rejected. | Baixa de pagamento de boleto rejeitada. |
| 404         | BIP000056 | Not Found | Payment not found. | Pagamento não encontrado. |
| 400         | BIP000057 | Bad Request | Payment status is not pending approval. | Status de pagamento não é de aprovação pendente. |
| 400         | BIP000058 | Bad Request | Error while validating verification token | Erro ao validar token de verificação |
| 400         | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Número de tentativas de validação de token de verificação excedido. |
| 400         | BIP000060 | Bad Request | Verification token expired. | Token de verificação expirado. |
| 400         | BIP000061 | Bad Request | Verification token validation failed. | Falha na validação do token de verificação. |
| 400         | BIP000062 | Bad Request | Payment type is not bank slip. | Tipo de pagamento não é boleto. |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |
| 400                      | BIP000086            | Bad Request                                | A token is required for SMS or email validation.                    | Um token é necessário para validação via SMS ou email.             |

---

# Confirmação de Pagamento de Fatura de Recolhimento

URL: /documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_fatura_de_recolhimento

Este endpoint permite realizar a confirmação do pagamento de faturas de recolhimento.

:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::

## Request

### Request Endpoint

ENDPOINT /account/ ACCOUNT_KEY /payment/ PAYMENT_KEY /collection_slip/validate_token
MÉTODO PATCH

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |
| `payment_key` *     | uuid4   | Chave única de identificação do pagamento.  | 36     |

### Autenticação via Email e SMS

Request Body: Confirmação de pagamento de fatura de recolhimento

```json
{
  "token": "329adf"
}
```

### Autenticação via Dispositivo

Para aprovar e finalizar a autenticação via dispositivo, a requisição deve ser enviada com um payload vazio. A validação ocorre internamente, sem necessidade de informações adicionais no corpo da requisição. É importante destacar que este endpoint só deve ser utilizado após a [solicitação de transação](./solicitacao_de_pagamento_de_fatura_de_recolhimento.md) ter sido iniciada.

Request Body: Confirmação de pagamento de fatura de recolhimento

```json
{

}
```

### Body Params

| Campo     | Tipo   | Descrição                                                             | Caracteres |
|-----------|--------|-----------------------------------------------------------------------|------------|
| `token`   | string | Código de autenticação enviado ao aprovador de movimentações da conta **obrigatório para TFA via SMS ou e-mail**| 6          |

## Response

### Success Response

STATUS 200

Response Body: Pagamento executado

```json
{
  "payment_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
  "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
  "payer_name": "COOPERATIVA INDUSTRIAL MURILO",
  "payer_document_number": "62069937000118",
  "source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "transaction_key": "fc9ccfd0-2f21-4207-9772-69238be74152",
  "transaction_revert_key": null,
  "paid_amount": 1389.21,
  "payment_date": "2024-04-30",
  "payment_type": "collection_slip",
  "bank_slip": null,
  "collection_slip": {
    "barcode": null,
    "digitable_line": "836200000138892100450006762142420244046000010192",
    "collection_name": "CIA ULTRAGAZ SA-COD",
    "collection_document_number": "00394460005887",
    "expiration_date": "2024-04-15",
    "total_amount": 1389.21
  },
  "payment_status": "executed"
}
```

### Response Body Params

| Campo               | Tipo    | Descrição                         |
|---------------------|---------|-----------------------------------|
| `payment_key` *               | uuid4 | Chave única de identificação do pagamento. |
| `request_control_key` *       | uuid4 | Chave única de identificação da request do cliente. |
| `payer_name` *                | string | Nome do pagador efetivo.|
| `payer_document_number` *     | string | Número do documento do pagador efetivo (CPF/CNPJ). |
| `source_account_key` *        | uuid4 | Chave da conta debitada. |
| `transaction_key` *           | uuid4 | Chave da transação do pagamento. |
| `transaction_revert_key`      | uuid4 | Chave da transação de reversão do pagamento. |
| `paid_amount` *               | number | Valor pago efetivamente. |
| `payment_date` *              | string | Data do pagamento. |
| `payment_type` *              | [enum](#enumeradores-payment_type) | Tipo do pagamento. |
| `bank_slip`                   | object | Boleto bancário. |
| `collection_slip`             | [object](#objeto-collection_slip) | Fatura de recolhimento. |
| `payment_status` *            | [enum](#enumeradores-payment_status) | Status do pagamento. |

### Enumeradores payment_type
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

:::danger Aviso
O enumerador `bank_slip` não se aplica para o fluxo de faturas de recolhimento, assim como o objeto bank_slip que sempre será nulo.
:::

### Enumeradores payment_status
| Enumerador    | Descrição     |
|---------------|---------------|
| `executed`    | Executado |
| `reverted`    | Revertido |
| `rejected`    | Rejeitado |
| `error`       | Erro      |

### Objeto collection_slip
| Campo                             | Tipo    | Descrição                         |
|-----------------------------------|---------|-----------------------------------|
| `barcode`          | string | Código de barras. |
| `digitable_line`   | string | Linha digitável. |
| `collection_name` *         | string | Nome do convênio.|
| `collection_document_number`   | string | Número de documento do convênio (CPF/CNPJ).|
| `expiration_date` *  | string  | Data de vencimento. |
| `total_amount` *  | number | Valor total. |

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 403         | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404         | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400         | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400         | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |s
| 400         | BIP000023 | Bad Request | The source account has insufficient balance. Payment cannot be made. | A conta de origem possui saldo insuficiente. Pagamento não pode ser realizado. |
| 400         | BIP000028 | Bad Request | The source account has blocked balance. Payment cannot be made. | A conta de origem possui saldo em conta bloqueado. Pagamento não pode ser realizado. |
| 400         | BIP000034 | Bad Request | Collection slip already paid. | Fatura de recolhimento já paga. |
| 400         | BIP000036 | Bad Request | Covenant slip overdue. | Fatura de recolhimento vencida. |
| 400         | BIP000038 | Bad Request | Outside of covenant payment hours. | Fora do horário de pagamento do convênio. |
| 400         | BIP000044 | Bad Request | It was not possible to pay the collection slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar a fatura de recolhimento neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. |
| 400         | BIP000045 | Bad Request | Collection slip payment service is closed. | Serviço de pagamento de fatura de recolhimento está fechado. |
| 404         | BIP000056 | Not Found | Payment not found. | Pagamento não encontrado. |
| 400         | BIP000057 | Bad Request | Payment status is not pending approval. | Status de pagamento não é de aprovação pendente. |
| 400         | BIP000058 | Bad Request | Error while validating verification token | Erro ao validar token de verificação |
| 400         | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Número de tentativas de validação de token de verificação excedido. |
| 400         | BIP000060 | Bad Request | Verification token expired. | Token de verificação expirado. |
| 400         | BIP000061 | Bad Request | Verification token validation failed. | Falha na validação do token de verificação. |
| 400         | BIP000063 | Bad Request | Payment type is not collection slip. | Tipo de pagamento não é fatura de recolhimento. |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |
| 400                      | BIP000086            | Bad Request                                | A token is required for SMS or email validation.                    | Um token é necessário para validação via SMS ou email.             |

---

# Introdução a Autenticação de Dois Fatores

URL: /documentation/baas/cobranca/2fa_v2/introducao_ao_pagamento_2fa

Neste tipo de pagamento, é necessário a confirmação do pagamento via token enviado à pessoa com poderes de aprovação de
movimentação na conta pagadora.

A solicitação de pagamento por parceiros integradores configurados para a utilização de autenticação de dois
fatores é realizada de forma similar ao descrito
em [pagamento de boleto bancário](/documentation/baas/cobranca/pagar_boleto_bancario) e [pagamento de fatura de recolhimento](/documentation/baas/cobranca/pagar_fatura_de_recolhimento). 
A diferença ocorre na adição do objeto `tfa_info` na requisição, contendo informações sobre o aprovador da transferência e a forma de contato, e o status da
solicitação no retorna da requisição. O status da solicitação sempre será retornado como **pending_2fa_approval**.

## Fluxo para uma pagamento com autorização

O pagamento bem sucedido seguirá o seguinte fluxo de processos:

- Realização da [solicitação de pagamento de boleto bancário](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_boleto_bancario) ou [solicitação de pagamento de fatura de recolhimento](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_fatura_de_recolhimento) e recebimento da resposta de forma síncrona com status de **pending_2fa_approval** e a `payment_key`.
- O aprovador indicado receberá um `token` de 6 dígitos compostos por algarismos.
- O requisitante realiza a [confirmação do pagamento de boleto bancário](/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_boleto_bancario) ou [confirmação do pagamento de fatura de recolhimento](/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_fatura_de_recolhimento) com a `payment_key` e o `token`.
- O pagamento será concluída de forma síncrona.

## Observações

- Cada pagamento possui um limite máximo de tentativas de validação do `token` de 5 vezes. Quando este limite é alcançado o pagamento será colocado em status de rejeitado (**rejected**) automaticamente.
- Cada `token` possui duração máxima de 5 minutos.
- Um pagamento pode ter seu `token` renovado e reenviado para o aprovador da conta. Este processo reinicia o tempo de 5 minutos e não reinicia o contador de tentativas inválidas. O `token` anterior torna-se inválido.
- Uma vez aprovado o pagamento, este será concluído de forma síncrona.
- O evento de notificação para o envio de `token` ao aprovador é **baas.token_validation.bill_payment.payment.single**. É possível [personalizar](/documentation/notificacoes/template) a mensagem enviada.
- As formas de envio (`contact_type`) de token implementadas são por **sms** e **email**.

---

# Solicitação de pagamento de Boleto Bancário com Autenticação de Dois Fatores

URL: /documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_boleto_bancario

Este endpoint permite realizar a solicitação de pagamento de boletos bancários. A solicitação deve ser realizado após a consulta, utilizando as informações retornadas para garantir o funcionamento correto do fluxo, evitando falhas durante o processo.

:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::

## Request

### Request Endpoint

ENDPOINT /account/ ACCOUNT_KEY /payment/bank_slip
MÉTODO POST

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |

## Autenticação via Email e SMS

Request Body: Solicitação de boleto bancário com linha digitável com TFA por SMS ou Email

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "digitable_line": "00190000090361557400500000024174396700000991000",
  "payment_amount": 1156.8,
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```
Request Body: Solicitação de boleto bancário com código de barras com TFA por SMS ou Email

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "barcode": "00190000090361557400500000024174396700000991000",
  "payment_amount": 1156.8,
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```

## Autenticação via Dispositivo

Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`.

Request Body: Solicitação de boleto bancário com linha digitável com TFA por Dispositivo

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "digitable_line": "00190000090361557400500000024174396700000991000",
  "payment_amount": 1156.8,
  "tfa_info": {
    "approver_document_number": "98765432100",
    "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
    "contact_type": "device"
  }
}
```
Request Body: Solicitação de boleto bancário com código de barras com TFA por Dispositivo

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "barcode": "00190000090361557400500000024174396700000991000",
  "payment_amount": 1156.8,
  "tfa_info": {
    "approver_document_number": "98765432100",
    "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
    "contact_type": "device"
  }
}
```
### Body Params

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | Chave única de identificação da request do cliente. |    
| `barcode`               | string    | Código de barras. |
| `digitable_line`        | string    | Linha digitável. |
| `payment_amount` *      | number    | Valor a ser pago. |
| `tfa_info` *            | [object](#objeto-tfa_info)    | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato. | 

:::danger Aviso
O `payment_amount` deve sempre igual ao `total_amount` retornado na consulta do boleto bancário caso o pagamento parcial não seja permitido para o boleto bancário. Para títulos em que o pagamento parcial é permitido, o cliente pode escolher o `payment_amount`, desde que a soma do mesmo com o `registered_payment_amount` do boleto bancário não seja superior que o `total_amount`.
:::

### Objeto tfa_info
| Campo                             | Tipo    | Descrição                         |
|-----------------------------------|---------|-----------------------------------|
| `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta (CPF/CNPJ). | 
| `session_id`| string | Chave única de identificação da sessão do dispositivo no formato UUID v4 (obrigatório para TFA via dispositivo). |   36         |
| `contact_type`*             | enumerator | Método de validação do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** |

| Enumerador | Descrição                                         |
|------------|---------------------------------------------------|
| **sms**    | Envio por Mensagem de Texto para telefone celular |
| **email**  | Envio por correio eletrônico                      |
| **device** | Validação por token do dispositivo                |

## Response

### Success Response

STATUS 201

Response Body: Pagamento pendente de aprovação de dois fatores

```json
{
   "payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea",
   "request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189",
   "payer_name":"COOPERATIVA INDUSTRIAL MURILO",
   "payer_document_number":"00037025000160",
   "source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
   "transaction_key":"4e80070a-a0bb-4be2-8178-55fbd73a3704",
   "transaction_revert_key":null,
   "paid_amount":1050.1,
   "payment_date":"2024-04-03",
   "payment_type":"bank_slip",
   "bank_slip": {
        "bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
        "barcode":"00193967000009910000000003615574000000002417",
        "digitable_line":"00190000090361557400500000024174396700000991000",
        "payer_name":"COOPERATIVA TESTE",
        "payer_document_number":"00037025000160",
        "beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
        "beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
        "beneficiary_document_number":"52069937000117",
        "beneficiary_bank_ispb":"00000000",
        "guarantor_name":null,
        "guarantor_document_number":null,
        "expiration_date":"2024-03-29",
        "max_payment_data": "2026-03-29",
        "partial_payment_indicator":"allowed",
        "registered_payment_amount":9029.0,
        "nominal_amount":9910.0,
        "total_amount":10129.1,
        "rebate_amount":0.0,
        "discount_amount":0.0,
        "fine_amount":0.0,
        "interest_amount":219.1
    },
   "collection_slip":null,
   "payment_status":"pending_2fa_approval"
}
```

### Response Body Params

| Campo               | Tipo    | Descrição                         |
|---------------------|---------|-----------------------------------|
| `payment_key` *               | uuid4 | Chave única de identificação do pagamento. |
| `request_control_key` *       | uuid4 | Chave única de identificação da request do cliente. |
| `payer_name` *                | string | Nome do pagador efetivo.|
| `payer_document_number` *     | string | Número do documento do pagador efetivo  (CPF/CNPJ). |
| `source_account_key` *        | uuid4 | Chave da conta debitada. |
| `transaction_key` *           | uuid4 | Chave da transação do pagamento. |
| `transaction_revert_key`      | uuid4 | Chave da transação de reversão do pagamento. |
| `paid_amount` *               | number | Valor pago efetivamente. |
| `payment_date` *              | string | Data do pagamento. |
| `payment_type` *              | [enum](#enumeradores-payment_type) | Tipo do pagamento. |
| `bank_slip`                   | [object](#objeto-bank_slip) | Boleto bancário. |
| `collection_slip`             | object | Fatura de recolhimento. |
| `payment_status` *            | [enum](#enumeradores-payment_status) | Status do pagamento. |

### Enumeradores payment_type
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

:::danger Aviso
O enumerador `collection_slip` não se aplica para o fluxo de boletos bancários, assim como o objeto collection_slip que sempre será nulo.
:::

### Enumeradores payment_status
| Enumerador    | Descrição     |
|---------------|---------------|
| `pending_2fa_approval`    | pendente de aprovação de dois fatores |

### Objeto bank_slip
| Campo                             | Tipo    | Descrição                         |
|-----------------------------------|---------|-----------------------------------|
| `barcode` *                       | string | Código de barras. |
| `digitable_line` *                | string | Linha digitável. |
| `payer_name` *                    | string | Nome do pagador.|
| `payer_document_number` *         | string | Número do documento do pagador (CPF/CNPJ). |
| `beneficiary_name` *              | string | Nome do beneficiário. |
| `beneficiary_trading_name`        | string | Nome fantasia do beneficiário. |
| `beneficiary_document_number` *   | string | Número do documento do beneficiário (CPF/CNPJ). |
| `beneficiary_bank_ispb` *         | string | Código ispb do banco do beneficiário. |
| `guarantor_name`                  | string | Nome do sacador avalista. |
| `guarantor_document_number`       | string | Número do documento do sacador avalista (CPF/CNPJ). |
| `expiration_date` *               | string | Data de vencimento. |
| `max_payment_date` * | string  | Data máxima de pagamento. |
| `partial_payment_indicator` *     | [enum](#enumeradores-partial_payment_indicator)   | Indicador de pagamento parcial. |
| `registered_payment_amount`       | string | Valor total de pagamento registrado. |
| `nominal_amount` *                | number | Valor original. |
| `total_amount` *                  | number | Valor total. |
| `rebate_amount` *                 | number | Valor do abatimento. |
| `discount_amount` *               | number | Valor do desconto. |
| `fine_amount` *                   | number | Valor da multa. |
| `interest_amount` *               | number | Valor do juros. |

### Enumeradores partial_payment_indicator
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `allowed`     | string    | Permitido     |
| `not_allowed` | string    | Não permitido |

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400         | BIP000001 | Bad Request | The barcode or digitable line must have 44 or 47 characters. | O código de barras ou linha digitável deve ter 44 ou 47 caracteres. |
| 400         | BIP000002 | Bad Request | The bill sent does not correspond to a bank slip. | A conta enviado não corresponde a um boleto bancário. |
| 400         | BIP000003 | Bad Request | The digitable line sent is invalid. | A linha digitável enviada é inválida. |
| 404         | BIP000004 | Not Found | The bank slip was not found. | O boleto não foi encontrado. |
| 400         | BIP000005 | Bad Request | It was not possible to consult the bank slip at this time. Please try again in a few minutes. | Não foi possível consultar o boleto neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000006 | Bad Request | Bank slip already written off | Boleto já baixado |
| 400         | BIP000007 | Bad Request | Bank slip blocked for payment | Boleto bloqueado para pagamento |
| 400         | BIP000008 | Bad Request | Bank slip already paid | Boleto já pago |
| 400         | BIP000009 | Bad Request | Invalid bank slip. Please consult issuing bank | Boleto inválido. Favor consultar banco emissor |
| 403         | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404         | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400         | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400         | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 400         | BIP000015 | Bad Request | Payment date is greater than the maximum payment date. | A data de pagamento é maior que a data máxima de pagamento. |
| 400         | BIP000016 | Bad Request | Payment date is smaller than the calculation date. | A data de pagamento é menor que a data de cálculo. |
| 400         | BIP000017 | Bad Request | Invalid payment amount. | Valor de pagamento inválido. |
| 400         | BIP000018 | Bad Request | Partial payment is not allowed. | Pagamento parcial não é permitido. |
| 400         | BIP000019 | Bad Request | The payment amount is greater than the available amount. | O valor do pagamento é maior que o valor disponível. |
| 400         | BIP000020 | Bad Request | All partial payments for this bank slip have already been made. | Todos os pagamentos parciais deste boleto já foram realizados. |
| 400         | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 403         | BIP000052 | Forbidden | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta |
| 400         | BIP000053 | Bad Request | Error getting approver data | Erro ao obter dados do aprovador |
| 400         | BIP000054 | Bad Request | TFA info required | Informações de TFA necessárias |
| 400         | BIP000055 | Bad Request | Error sending verification token | Erro ao enviar token de verificação |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |
| 400                      | BIP000079            | Bad Request | A session_id must be provided token                      | Uma session_id deve ser fornecida                |

## Ambiente de Sandbox

Em nosso ambiente de sandbox, disponibilizamos linhas digitáveis mockadas para a simulação de pagamentos bem-sucedidos e testes de cenários de erro.

| Linha digitável |
|-----------------|
| 00190000090361557400500000024174396700000991000 |
| 00190000090282802601919212747174596760001294161 |
| 23793390014000000455277000249001596900000103995 |
| 75691434020137513680900001040013196770002417240 |
| 21390001171200000570700168167484796770000148206 |
| 34191090083273252027893634770007296690012513600 |
| 42297048060005815702500130494123896770000239491 |
| 07090010287045349010776686070590896770001160123 |
| 74891123702849020818918378871083196690000050000 |
| 23792374119000209350986000372408496610000122810 |

---

# Solicitação de Pagamento de Fatura de Recolhimento com Autenticação de Dois Fatores

URL: /documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_fatura_de_recolhimento

Este endpoint permite realizar a solicitação de pagamento de faturas de recolhimento com autenticação de dois fatores. A solicitação deve ser realizado após a consulta, utilizando as informações retornadas para garantir o funcionamento correto do fluxo, evitando falhas durante o processo.

:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::

## Request

### Request Endpoint

ENDPOINT /account/ ACCOUNT_KEY /payment/collection_slip
MÉTODO POST

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |

## Autenticação via Email e SMS

Request Body: Solicitação de fatura de recolhimento com linha digitável com TFA por SMS ou Email

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "digitable_line": "00190000090361557400500000024174396700000991000",
  "payment_amount": 1156.8,
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```
Request Body: Solicitação de fatura de recolhimento com código de barras com TFA por SMS ou Email

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "barcode": "00190000090361557400500000024174396700000991000",
  "payment_amount": 1156.8,
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```

## Autenticação via Dispositivo

Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`.

Request Body: Solicitação de fatura de recolhimento com linha digitável com TFA por Dispositivo

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "digitable_line": "00190000090361557400500000024174396700000991000",
  "payment_amount": 1156.8,
  "tfa_info": {
    "approver_document_number": "98765432100",
    "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
    "contact_type": "device"
  }
}
```
Request Body: Solicitação de fatura de recolhimento com código de barras com TFA por Dispositivo

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "barcode": "00190000090361557400500000024174396700000991000",
  "payment_amount": 1156.8,
  "tfa_info": {
    "approver_document_number": "98765432100",
    "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
    "contact_type": "device"
  }
}
```

### Body Params

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | Chave única de identificação da request do cliente. |    
| `barcode`               | string    | Código de barras. |
| `digitable_line`        | string    | Linha digitável. |
| `payment_amount` *      | number    | Valor a ser pago. |
| `tfa_info` *            | [object](#objeto-tfa_info)    | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato. | 

:::danger Aviso
O `payment_amount` deve sempre igual ao `total_amount` retornado na consulta do boleto bancário.
:::

### Objeto tfa_info
| Campo                             | Tipo    | Descrição                         |
|-----------------------------------|---------|-----------------------------------|
| `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta (CPF/CNPJ). | 
| `session_id`| string | Chave única de identificação da sessão do dispositivo no formato UUID v4 (obrigatório para TFA via dispositivo). |   36         |
| `contact_type`*             | enumerator | Método de validação do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** |

| Enumerador | Descrição                                         |
|------------|---------------------------------------------------|
| **sms**    | Envio por Mensagem de Texto para telefone celular |
| **email**  | Envio por correio eletrônico                      |
| **device** | Validação por token do dispositivo                |

## Response

### Success Response

STATUS 201

Response Body: Pagamento pendente de aprovação de dois fatores

```json
{
  "payment_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
  "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
  "payer_name": "COOPERATIVA INDUSTRIAL MURILO",
  "payer_document_number": "62069937000118",
  "source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "transaction_key": "fc9ccfd0-2f21-4207-9772-69238be74152",
  "transaction_revert_key": null,
  "paid_amount": 1389.21,
  "payment_date": "2024-04-30",
  "payment_type": "collection_slip",
  "bank_slip": null,
  "collection_slip": {
    "barcode": null,
    "digitable_line": "836200000138892100450006762142420244046000010192",
    "collection_name": "CIA ULTRAGAZ SA-COD",
    "collection_document_number": "00394460005887",
    "expiration_date": "2024-04-15",
    "total_amount": 1389.21
  },
  "payment_status": "pending_2fa_approval"
}
```

### Response Body Params

| Campo               | Tipo    | Descrição                         |
|---------------------|---------|-----------------------------------|
| `payment_key` *               | uuid4 | Chave única de identificação do pagamento. |
| `request_control_key` *       | uuid4 | Chave única de identificação da request do cliente. |
| `payer_name` *                | string | Nome do pagador efetivo.|
| `payer_document_number` *     | string | Documento do pagador efetivo (CPF/CNPJ). |
| `source_account_key` *        | uuid4 | Chave da conta debitada. |
| `transaction_key` *           | uuid4 | Chave da transação do pagamento. |
| `transaction_revert_key`      | uuid4 | Chave da transação de reversão do pagamento. |
| `paid_amount` *               | number | Valor pago efetivamente. |
| `payment_date` *              | string | Data do pagamento. |
| `payment_type` *              | [enum](#enumeradores-payment_type) | Tipo do pagamento. |
| `bank_slip`                   | object | Boleto bancário. |
| `collection_slip`             | [object](#objeto-collection_slip) | Fatura de recolhimento. |
| `payment_status` *            | [enum](#enumeradores-payment_status) | Status do pagamento. |

### Enumeradores payment_type
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

:::danger Aviso
O enumerador `bank_slip` não se aplica para o fluxo de faturas de recolhimento, assim como o objeto bank_slip que sempre será nulo.
:::

### Enumeradores payment_status
| Enumerador    | Descrição     |
|---------------|---------------|
| `pending_2fa_approval`    | pendente de aprovação de dois fatores |

### Objeto collection_slip
| Campo                             | Tipo    | Descrição                         |
|-----------------------------------|---------|-----------------------------------|
| `barcode`          | string | Código de barras. |
| `digitable_line`   | string | Linha digitável. |
| `collection_name` *         | string | Nome do convênio.|
| `collection_document_number`   | string | Número de documento do convênio (CPF/CNPJ).|
| `expiration_date` *  | string  | Data de vencimento. |
| `total_amount` *  | number | Valor total. |

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400         | BIP000032 | Bad Request | The bill sent does not correspond to a collection slip. | A conta enviada não corresponde a uma fatura de recolhimento. |
| 400         | BIP000033 | Bad Request | The barcode or digitable line of the collection slip must have 44 or 48 characters. | O código de barras ou linha digitável da fatura de recolhimento deve ter 44 ou 48 caracteres. |
| 403         | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404         | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400         | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400         | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 400         | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 400         | BIP000028 | Bad Request | The source account has blocked balance. Payment cannot be made. | A conta de origem possui saldo em conta bloqueado. Pagamento não pode ser realizado. |
| 400         | BIP000034 | Bad Request | Collection slip already paid. | Fatura de recolhimento já paga. |
| 400         | BIP000035 | Bad Request | Covenant slip invalid barcode. | Código de barras da fatura de recolhimento inválido. |
| 400         | BIP000036 | Bad Request | Covenant slip overdue. | Fatura de recolhimento vencida. |
| 400         | BIP000037 | Bad Request | Error in collection slip consultation. | Erro na consulta da fatura de recolhimento. |
| 400         | BIP000038 | Bad Request | Outside of covenant payment hours. | Fora do horário de pagamento do convênio. |
| 400         | BIP000039 | Bad Request | Collection slip not accepted. | Fatura de recolhimento não aceita. |
| 400         | BIP000040 | Bad Request | Minimum advance not reached. | Mínimo de dias de adiantamento não atingido. |
| 400         | BIP000041 | Bad Request | Max payment amount exceeded. | Valor máximo de pagamento excedido. |
| 400         | BIP000044 | Bad Request | It was not possible to pay the collection slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar a fatura de recolhimento neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. |
| 403         | BIP000052 | Forbidden | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta |
| 400         | BIP000053 | Bad Request | Error getting approver data | Erro ao obter dados do aprovador |
| 400         | BIP000054 | Bad Request | TFA info required | Informações de TFA necessárias |
| 400         | BIP000055 | Bad Request | Error sending verification token | Erro ao enviar token de verificação |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |
| 400                      | BIP000079            | Bad Request | A session_id must be provided token                      | Uma session_id deve ser fornecida                |

## Ambiente de Sandbox

Em nosso ambiente de sandbox, disponibilizamos linhas digitáveis mockadas para a simulação de pagamentos bem-sucedidos e testes de cenários de erro.

| Linha digitável |
|---|
| 828300000007411100972013905080001546763201900028 |
| 838000000009235700481007241345219112001474229880 |
| 848000000006308600802021201071261517689002201070 |
| 858200000015000000643025703477209504800448091020 |
| 858500000037350000643217212883260006147448091022 |

---

# Reenviar Token Autenticação de Dois Fatores de Pagamentos de Boleto Bancário

URL: /documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_boleto_bancario

Este endpoint permite realizar o reenvio do token de autenticação de pagamentos de Boleto Bancário.

:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária
de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco
Central.
:::

## Request

### Request Endpoint

ENDPOINT /account/ ACCOUNT_KEY /payment/ PAYMENT_KEY /bank_slip/resend_token
MÉTODO PATCH

### Request Path Params

| Campo           | Tipo  | Descrição                                  | Caracteres |
|-----------------|-------|--------------------------------------------|------------|
| `account_key` * | uuid4 | Chave única de identificação da conta.     | 36         |
| `payment_key` * | uuid4 | Chave única de identificação do pagamento. | 36         |

### Body Params

| Campo          | Tipo       | Descrição                               | Caracteres                                              |
|----------------|------------|-----------------------------------------|---------------------------------------------------------|
| `contact_type` | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** |

:::info Informação
Caso não seja enviado um `contact_type`, o token será enviado da forma solicitada originalmente.
:::

| Enumerador | Descrição                                         |
|------------|---------------------------------------------------|
| **sms**    | Envio por Mensagem de Texto para telefone celular |
| **email**  | Envio por correio eletrônico                      |

## Response

### Success Response

STATUS 200

Response Body: Token reenviado com sucesso

```json
{
  "payment_key": "c4325104-d60b-44f3-aae4-49155564a2ea",
  "request_control_key": "b713b2f6-2f48-4d18-b0c9-7186e4edf189",
  "payer_name": "COOPERATIVA INDUSTRIAL MURILO",
  "payer_document_number": "00037025000160",
  "source_account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
  "transaction_key": "4e80070a-a0bb-4be2-8178-55fbd73a3704",
  "transaction_revert_key": null,
  "paid_amount": 1050.1,
  "payment_date": "2024-04-03",
  "payment_type": "bank_slip",
  "bank_slip": {
    "bank_slip_key": "95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
    "barcode": "00193967000009910000000003615574000000002417",
    "digitable_line": "00190000090361557400500000024174396700000991000",
    "payer_name": "COOPERATIVA TESTE",
    "payer_document_number": "00037025000160",
    "beneficiary_name": "TESTE EQUIPAMENTOS E SERVICOS LTDA",
    "beneficiary_trading_name": "TESTE EQUIPAMENTOS E SERVICOS LTDA",
    "beneficiary_document_number": "52069937000117",
    "beneficiary_bank_ispb": "00000000",
    "guarantor_name": null,
    "guarantor_document_number": null,
    "expiration_date": "2024-03-29",
    "max_payment_data": "2026-03-29",
    "partial_payment_indicator": "allowed",
    "registered_payment_amount": 9029.0,
    "nominal_amount": 9910.0,
    "total_amount": 10129.1,
    "rebate_amount": 0.0,
    "discount_amount": 0.0,
    "fine_amount": 0.0,
    "interest_amount": 219.1
  },
  "collection_slip": null,
  "payment_status": "pending_2fa_approval"
}
```

### Response Body Params

| Campo                     | Tipo                                 | Descrição                                           |
|---------------------------|--------------------------------------|-----------------------------------------------------|
| `payment_key` *           | uuid4                                | Chave única de identificação do pagamento.          |
| `request_control_key` *   | uuid4                                | Chave única de identificação da request do cliente. |
| `payer_name` *            | string                               | Nome do pagador efetivo.                            |
| `payer_document_number` * | string                               | Número documento do pagador efetivo (CPF/CNPJ).     |
| `source_account_key` *    | uuid4                                | Chave da conta debitada.                            |
| `transaction_key` *       | uuid4                                | Chave da transação do pagamento.                    |
| `transaction_revert_key`  | uuid4                                | Chave da transação de reversão do pagamento.        |
| `paid_amount` *           | number                               | Valor pago efetivamente.                            |
| `payment_date` *          | string                               | Data do pagamento.                                  |
| `payment_type` *          | [enum](#enumeradores-payment_type)   | Tipo do pagamento.                                  |
| `bank_slip`               | [object](#objeto-bank_slip)          | Boleto bancário.                                    |
| `collection_slip`         | object                               | Fatura de recolhimento.                             |
| `payment_status` *        | [enum](#enumeradores-payment_status) | Status do pagamento.                                |

### Enumeradores payment_type

| Enumerador        | Tipo   | Descrição              |
|-------------------|--------|------------------------|
| `bank_slip`       | string | Boleto bancário        |
| `collection_slip` | string | Fatura de recolhimento |

:::danger Aviso
O enumerador `collection_slip` não se aplica para o fluxo de boletos bancários, assim como o objeto collection_slip que
sempre será nulo.
:::

### Enumeradores payment_status

| Enumerador             | Descrição                             |
|------------------------|---------------------------------------|
| `pending_2fa_approval` | pendente de aprovação de dois fatores |

### Objeto bank_slip

| Campo                           | Tipo                                            | Descrição                                           |
|---------------------------------|-------------------------------------------------|-----------------------------------------------------|
| `barcode` *                     | string                                          | Código de barras.                                   |
| `digitable_line` *              | string                                          | Linha digitável.                                    |
| `payer_name` *                  | string                                          | Nome do pagador.                                    |
| `payer_document_number` *       | string                                          | Número de documento do pagador (CPF/CNPJ).          |
| `beneficiary_name` *            | string                                          | Nome do beneficiário.                               |
| `beneficiary_trading_name`      | string                                          | Nome fantasia do beneficiário.                      |
| `beneficiary_document_number` * | string                                          | Número de documento do beneficiário (CPF/CNPJ).     |
| `beneficiary_bank_ispb` *       | string                                          | Código ispb do banco do beneficiário.               |
| `guarantor_name`                | string                                          | Nome do sacador avalista.                           |
| `guarantor_document_number`     | string                                          | Número de documento do sacador avalista (CPF/CNPJ). |
| `expiration_date` *             | string                                          | Data de vencimento.                                 |
| `max_payment_date` *            | string                                          | Data máxima de pagamento.                           |
| `partial_payment_indicator` *   | [enum](#enumeradores-partial_payment_indicator) | Indicador de pagamento parcial.                     |
| `registered_payment_amount`     | string                                          | Valor total de pagamento registrado.                |
| `nominal_amount` *              | number                                          | Valor original.                                     |
| `total_amount` *                | number                                          | Valor total.                                        |
| `rebate_amount` *               | number                                          | Valor do abatimento.                                |
| `discount_amount` *             | number                                          | Valor do desconto.                                  |
| `fine_amount` *                 | number                                          | Valor da multa.                                     |
| `interest_amount` *             | number                                          | Valor do juros.                                     |

### Enumeradores partial_payment_indicator

| Enumerador    | Tipo   | Descrição     |
|---------------|--------|---------------|
| `allowed`     | string | Permitido     |
| `not_allowed` | string | Não permitido |

### Error Response

STATUS 4XX

Response Body

```json
{
  "title": "Título",
  "description": "Description in english",
  "translation": "Descrição em português",
  "code": "Código"
}
```

| Código HTTP | Código QI | Título      | Descrição (eng)                                                                                    | Descrição (pt-br)                                                                                         |
|-------------|-----------|-------------|----------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------|
| 403         | BIP000010 | Forbidden   | User is not allowed to do this action                                                              | Usuário não tem autorização para fazer essa ação                                                          |
| 404         | BIP000011 | Not Found   | The source account key was not found.                                                              | A chave da conta de origem não foi encontrada.                                                            |
| 400         | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000013 | Bad Request | The source account is closed.                                                                      | A conta de origem está fechada.                                                                           |
| 400         | BIP000014 | Bad Request | The source account is blocked.                                                                     | A conta de origem está bloqueada.                                                                         |
| 404         | BIP000056 | Not Found   | Payment not found.                                                                                 | Pagamento não encontrado.                                                                                 |
| 400         | BIP000057 | Bad Request | Payment status is not pending approval.                                                            | Status de pagamento não é de aprovação pendente.                                                          |
| 400         | BIP000062 | Bad Request | Payment type is not bank slip.                                                                     | Tipo de pagamento não é boleto.                                                                           |
| 400         | BIP000064 | Bad Request | Error resending verification token                                                                 | Erro ao reenviar token de verificação                                                                     |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded.                                                         | Janela de tempo de verificação de pagamento excedida.                                                     |

---

# Reenviar Token de Autenticação de Dois Fatores para Pagamentos de Fatura de Recolhimento

URL: /documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_fatura_de_recolhimento

Este endpoint permite realizar o reenvio do token de autenticação de pagamentos de faturas de recolhimento.

:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::

## Request

### Request Endpoint

ENDPOINT /account/ ACCOUNT_KEY /payment/ PAYMENT_KEY /collection_slip/resend_token
MÉTODO PATCH

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |
| `payment_key` *     | uuid4   | Chave única de identificação do pagamento.  | 36     |

### Body Params

| Campo          | Tipo   | Descrição                                                                                 | Caracteres |
|----------------|--------|-------------------------------------------------------------------------------------------|------------|
| `contact_type` | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** |

:::info Informação
Caso não seja enviado um `contact_type`, o token será enviado da forma solicitada originalmente.
:::

| Enumerador | Descrição                                         |
|------------|---------------------------------------------------|
| **sms**    | Envio por Mensagem de Texto para telefone celular |
| **email**  | Envio por correio eletrônico                      |

## Response

### Success Response

STATUS 200

Response Body: Token reenviado com sucesso

```json
{
  "payment_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
  "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
  "payer_name": "COOPERATIVA INDUSTRIAL MURILO",
  "payer_document_number": "62069937000118",
  "source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "transaction_key": "fc9ccfd0-2f21-4207-9772-69238be74152",
  "transaction_revert_key": null,
  "paid_amount": 1389.21,
  "payment_date": "2024-04-30",
  "payment_type": "collection_slip",
  "bank_slip": null,
  "collection_slip": {
    "barcode": null,
    "digitable_line": "836200000138892100450006762142420244046000010192",
    "collection_name": "CIA ULTRAGAZ SA-COD",
    "collection_document_number": "00394460005887",
    "expiration_date": "2024-04-15",
    "total_amount": 1389.21
  },
  "payment_status": "pending_2fa_approval"
}
```

### Response Body Params

| Campo               | Tipo    | Descrição                         |
|---------------------|---------|-----------------------------------|
| `payment_key` *               | uuid4 | Chave única de identificação do pagamento. |
| `request_control_key` *       | uuid4 | Chave única de identificação da request do cliente. |
| `payer_name` *                | string | Nome do pagador efetivo.|
| `payer_document_number` *     | string | Número de documento do pagador efetivo (CPF/CNPJ). |
| `source_account_key` *        | uuid4 | Chave da conta debitada. |
| `transaction_key` *           | uuid4 | Chave da transação do pagamento. |
| `transaction_revert_key`      | uuid4 | Chave da transação de reversão do pagamento. |
| `paid_amount` *               | number | Valor pago efetivamente. |
| `payment_date` *              | string | Data do pagamento. |
| `payment_type` *              | [enum](#enumeradores-payment_type) | Tipo do pagamento. |
| `bank_slip`                   | object | Boleto bancário. |
| `collection_slip`             | [object](#objeto-collection_slip) | Fatura de recolhimento. |
| `payment_status` *            | [enum](#enumeradores-payment_status) | Status do pagamento. |

### Enumeradores payment_type
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

:::danger Aviso
O enumerador `bank_slip` não se aplica para o fluxo de faturas de recolhimento, assim como o objeto bank_slip que sempre será nulo.
:::

### Enumeradores payment_status
| Enumerador    | Descrição     |
|---------------|---------------|
| `pending_2fa_approval`    | pendente de aprovação de dois fatores |

### Objeto collection_slip
| Campo                             | Tipo    | Descrição                         |
|-----------------------------------|---------|-----------------------------------|
| `barcode`          | string | Código de barras. |
| `digitable_line`   | string | Linha digitável. |
| `collection_name` *         | string | Nome do convênio.|
| `collection_document_number`   | string | Número de documento do convênio (CPF/CNPJ).|
| `expiration_date` *  | string  | Data de vencimento. |
| `total_amount` *  | number | Valor total. |

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 403         | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404         | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400         | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400         | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 404         | BIP000056 | Not Found | Payment not found. | Pagamento não encontrado. |
| 400         | BIP000057 | Bad Request | Payment status is not pending approval. | Status de pagamento não é de aprovação pendente. |
| 400         | BIP000063 | Bad Request | Payment type is not collection slip. | Tipo de pagamento não é fatura de recolhimento. |
| 400         | BIP000064 | Bad Request | Error resending verification token | Erro ao reenviar token de verificação |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |

---

# Reenviar token de confirmação de lote de pagamento de boleto bancário

URL: /documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_lote_de_boleto_bancario

Este endpoint permite **reenviar** o token de autenticação de dois fatores (2FA) para um lote de boletos bancários que esteja aguardando validação do token. Um novo token é gerado e enviado ao aprovador. Se o **limite de tentativas de validação** do token tiver sido excedido, o reenvio pode não ser permitido.

:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::

## Request

### Request Endpoint

ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_bank_slip/**PAYMENT_BATCH_KEY**/resend_token
MÉTODO PATCH

### Request Path Params

| Campo                 | Tipo  | Descrição                                                                                | Caracteres |
| --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- |
| `account_key` *       | uuid4 | Chave única de identificação da conta.                                                   | 36         |
| `payment_batch_key` * | uuid4 | Chave única de identificação do lote (`batch_payment_key` retornado na criação do lote). | 36         |

### Request Body

Request Body (opcional)

```json
{
  "contact_type": "sms"
}
```

### Body Params

| Campo          | Tipo       | Descrição                               | Caracteres                                              |
| -------------- | ---------- | --------------------------------------- | ------------------------------------------------------- |
| `contact_type` | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** |

:::info Informação
Caso não seja enviado um `contact_type`, o token será enviado da forma solicitada originalmente (`tfa_info.contact_type`).
:::

### Enumerador contact_type

| Enumerador | Descrição                                         |
| ---------- | ------------------------------------------------- |
| **sms**    | Envio por mensagem de texto para telefone celular |
| **email**  | Envio por correio eletrônico                      |

## Response

### Success Response

STATUS 200

Response Body: Token reenviado com sucesso

```json
{
  "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
  "total_amount": 1357.3,
  "batch_status": "pending_2fa_approval",
  "payment_type": "bank_slip"
}
```

### Response Body Params

| Campo                   | Tipo   | Descrição                                                                                                                                                                                                                                                                                    |
| ----------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batch_payment_key` *   | uuid4  | Chave única de identificação do pagamento em lote.                                                                                                                                                                                                                                           |
| `request_control_key` * | uuid4  | Chave única de identificação da requisição do cliente (lote).                                                                                                                                                                                                                                |
| `account_key` *         | uuid4  | Chave da conta debitada.                                                                                                                                                                                                                                                                     |
| `total_amount` *        | number | Soma dos valores dos itens do lote.                                                                                                                                                                                                                                                          |
| `batch_status` *        | string | Após o reenvio, o lote permanece aguardando validação do token. O ciclo de `batch_status` está alinhado ao descrito na documentação de **solicitação de pagamento em lote** fornecida à operação (enumeradores `batch_payment_status`). |
| `payment_type` *        | string | Tipo do pagamento; para este fluxo, espera-se `bank_slip`.                                                                                                                                                                                                                                   |

Em seguida, utilize [Validação de token de lote de pagamento de boleto bancário](./validacao_de_token_de_lote_de_boleto_bancario.md) para concluir o 2FA.

### Error Response

STATUS 4XX

Response Body

```json
{
  "title": "Título",
  "description": "Description in english",
  "translation": "Descrição em português",
  "code": "Código"
}
```

| Código HTTP | Código QI | Título      | Descrição (eng)                                                                                    | Descrição (pt-br)                                                                                         |
| ----------- | --------- | ----------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| 403         | BIP000010 | Forbidden   | User is not allowed to do this action                                                              | Usuário não tem autorização para fazer essa ação                                                          |
| 404         | BIP000011 | Not Found   | The source account key was not found.                                                              | A chave da conta de origem não foi encontrada.                                                            |
| 400         | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000013 | Bad Request | The source account is closed.                                                                      | A conta de origem está fechada.                                                                           |
| 400         | BIP000014 | Bad Request | The source account is blocked.                                                                     | A conta de origem está bloqueada.                                                                         |
| 400         | BIP000059 | Bad Request | Number of verification token validation attempts exceeded.                                         | Número de tentativas de validação de token de verificação excedido.                                       |
| 400         | BIP000064 | Bad Request | Error resending verification token                                                                 | Erro ao reenviar token de verificação                                                                     |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded.                                                         | Janela de tempo de verificação de pagamento excedida.                                                     |
| 404         | BIP000083 | Not Found   | Batch payment not found by batch payment key.                                                      | Lote de pagamentos não encontrado pela chave do lote.                                                     |
| 400         | BIP000085 | Bad Request | Batch payment status is not pending approval.                                                      | Status do lote de pagamentos não é de aprovação pendente.                                                 |
| 400         | BIP000086 | Bad Request | A token is required for SMS or email validation.                    | Um token é necessário para validação via SMS ou email.             |

---

# Reenviar token de confirmação de lote de pagamento de fatura de recolhimento (convênio/tributo)

URL: /documentation/baas/cobranca/2fa_v2/solicitacao_de_reenvio_de_token_de_lote_de_fatura_de_recolhimento

Este endpoint permite **reenviar** o token de autenticação de dois fatores (2FA) para um lote de faturas de recolhimento que esteja aguardando validação do token. Um novo token é gerado e enviado ao aprovador. Se o **limite de tentativas de validação** do token tiver sido excedido, o reenvio pode não ser permitido.

:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::

## Request

### Request Endpoint

ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_collection_slip/**PAYMENT_BATCH_KEY**/resend_token
MÉTODO PATCH

### Request Path Params

| Campo                 | Tipo  | Descrição                                                                                | Caracteres |
| --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- |
| `account_key` *       | uuid4 | Chave única de identificação da conta.                                                   | 36         |
| `payment_batch_key` * | uuid4 | Chave única de identificação do lote (`batch_payment_key` retornado na criação do lote). | 36         |

### Request Body

Request Body (opcional)

```json
{
  "contact_type": "sms"
}
```

### Body Params

| Campo          | Tipo       | Descrição                               | Caracteres                                              |
| -------------- | ---------- | --------------------------------------- | ------------------------------------------------------- |
| `contact_type` | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** |

:::info Informação
Caso não seja enviado um `contact_type`, o token será enviado da forma solicitada originalmente (`tfa_info.contact_type`).
:::

### Enumerador contact_type

| Enumerador | Descrição                                         |
| ---------- | ------------------------------------------------- |
| **sms**    | Envio por mensagem de texto para telefone celular |
| **email**  | Envio por correio eletrônico                      |

## Response

### Success Response

STATUS 200

Response Body: Token reenviado com sucesso

```json
{
  "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "total_amount": 2778.42,
  "batch_status": "pending_2fa_approval",
  "payment_type": "collection_slip"
}
```

### Response Body Params

| Campo                   | Tipo   | Descrição                                                                                                                                                                                                                                                                                                      |
| ----------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batch_payment_key` *   | uuid4  | Chave única de identificação do pagamento em lote.                                                                                                                                                                                                                                                             |
| `request_control_key` * | uuid4  | Chave única de identificação da requisição do cliente (lote).                                                                                                                                                                                                                                                  |
| `account_key` *         | uuid4  | Chave da conta debitada.                                                                                                                                                                                                                                                                                       |
| `total_amount` *        | number | Soma dos valores dos itens do lote.                                                                                                                                                                                                                                                                            |
| `batch_status` *        | string | Após o reenvio, o lote permanece aguardando validação do token. O ciclo de `batch_status` está alinhado ao descrito na documentação de **solicitação de pagamento em lote** fornecida à operação (enumeradores `batch_payment_status`). |
| `payment_type` *        | string | Tipo do pagamento; para este fluxo, espera-se `collection_slip`.                                                                                                                                                                                                                                               |

Em seguida, utilize [Validação de token de lote de pagamento de fatura de recolhimento (convênio/tributo)](./validacao_de_token_de_lote_de_fatura_de_recolhimento.md) para concluir o 2FA.

### Error Response

STATUS 4XX

Response Body

```json
{
  "title": "Título",
  "description": "Description in english",
  "translation": "Descrição em português",
  "code": "Código"
}
```

| Código HTTP | Código QI | Título      | Descrição (eng)                                                                                    | Descrição (pt-br)                                                                                         |
| ----------- | --------- | ----------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| 403         | BIP000010 | Forbidden   | User is not allowed to do this action                                                              | Usuário não tem autorização para fazer essa ação                                                          |
| 404         | BIP000011 | Not Found   | The source account key was not found.                                                              | A chave da conta de origem não foi encontrada.                                                            |
| 400         | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000013 | Bad Request | The source account is closed.                                                                      | A conta de origem está fechada.                                                                           |
| 400         | BIP000014 | Bad Request | The source account is blocked.                                                                     | A conta de origem está bloqueada.                                                                         |                                                |
| 400         | BIP000059 | Bad Request | Number of verification token validation attempts exceeded.                                         | Número de tentativas de validação de token de verificação excedido.                                       |
| 400         | BIP000064 | Bad Request | Error resending verification token                                                                 | Erro ao reenviar token de verificação                                                                     |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded.                                                         | Janela de tempo de verificação de pagamento excedida.                                                     |
| 404         | BIP000083 | Not Found   | Batch payment not found by batch payment key.                                                      | Lote de pagamentos não encontrado pela chave do lote.                                                     |
| 400         | BIP000085 | Bad Request | Batch payment status is not pending approval.                                                      | Status do lote de pagamentos não é de aprovação pendente.
| 400         | BIP000086 | Bad Request | A token is required for SMS or email validation.                    | Um token é necessário para validação via SMS ou email.             |

---

# Solicitar pagamento em lote de boleto bancário com autenticação de dois fatores

URL: /documentation/baas/cobranca/2fa_v2/solicitar_pagamento_lote_de_boleto_bancario_com_confirmacao_de_lote

Este endpoint permite solicitar o pagamento de múltiplos boletos bancários em uma única requisição, com **`tfa_info`** quando a operação exigir autenticação de dois fatores **nesta solicitação**.

:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::

:::info Fluxo após a solicitação
Após a solicitação, o lote pode permanecer aguardando a [confirmação do lote com autenticação de dois fatores](./confirmacao_de_lote_de_boleto_bancario.md), conforme as regras da operação. Nesta etapa de confirmação, siga o fluxo com `tfa_info` descrito nessa documentação.
:::

## Request

### Request Endpoint

ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments/batch_bank_slip
MÉTODO POST

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |

Request Body: Pagamento em lote de boletos bancários (sem TFA nesta etapa)

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "bank_slip_payments": [
    {
      "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
      "digitable_line": "00190000090361557400500000024174396700000991000",
      "payment_amount": 1156.8
    },
    {
      "request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e",
      "barcode": "00190000090361557400500000024174396700000991000",
      "payment_amount": 200.5
    }
  ]
}
```

### Body Params

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | Chave única de identificação da requisição do cliente (lote). |
| `bank_slip_payments` * | array     | Lista de pagamentos de boleto bancário. Limite de **1000** itens por requisição. |

Cada elemento de `bank_slip_payments` deve conter:

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | Chave única de identificação da requisição do cliente para aquele item do lote. |
| `barcode`               | string    | Código de barras. |
| `digitable_line`        | string    | Linha digitável. |
| `payment_amount` *      | number    | Valor a ser pago. |

:::danger Aviso
Para cada item, o `payment_amount` enviado deve ser compatível com o que a consulta interna do boleto determinar: se o pagamento parcial **não** for permitido para aquele título, o valor deve corresponder ao total atualizado; se for permitido, o `payment_amount` pode seguir as regras do título (incluindo, quando aplicável, valores acima do nominal), como no fluxo de pagamento unitário de boleto bancário.
:::

### Objeto tfa_info

| Campo                        | Tipo   | Descrição                                                                                                                                          |
| ---------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `approver_document_number` * | string | Documento (CPF/CNPJ) da pessoa aprovadora que receberá o token ou aprovará via dispositivo. Obrigatório quando `tfa_info` é enviado.                |
| `session_id`                 | string | Chave única de identificação da sessão do dispositivo no formato UUID v4 (**obrigatório** para TFA via dispositivo).                               |
| `contact_type` *             | string | Canal para envio ou validação do token: **[Enumerador contact_type](#enumerador-contact_type)**. Obrigatório quando `tfa_info` é enviado. |

#### Enumerador contact_type

| Enumerador | Descrição                                         |
|------------|---------------------------------------------------|
| **sms**    | Envio por mensagem de texto para telefone celular |
| **email**  | Envio por correio eletrônico                      |
| **device** | Validação por token do dispositivo                |

## Response

### Success Response

STATUS 202

Response Body: Lote aceito para processamento

```json
{
  "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
  "total_amount": 1357.3,
  "batch_status": "pending",
  "payment_type": "bank_slip"
}
```

Response Body: exemplo ilustrativo (`batch_status` aprovado)

```json
{
  "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
  "total_amount": 1357.3,
  "batch_status": "approved",
  "payment_type": "bank_slip"
}
```

:::info Processamento do lote
O campo `batch_status` na resposta indica o **estado imediato** do lote após esta solicitação (por exemplo, pendente de confirmação, pendente de aprovação 2FA ou já encaminhado ao processamento), conforme o fluxo aplicável. Quando houver etapa de [confirmação do lote](./confirmacao_de_lote_de_boleto_bancario.md), siga essa documentação para aprovar ou rejeitar o lote com autenticação de dois fatores. Os valores possíveis de `batch_status` estão em [batch_payment_status](#enumeradores-batch_payment_status).
:::

### Response Body Params

| Campo               | Tipo    | Descrição                         |
|---------------------|---------|-----------------------------------|
| `batch_payment_key` *       | uuid4 | Chave única de identificação do pagamento em lote. |
| `request_control_key` *     | uuid4 | Chave única de identificação da requisição do cliente (lote). |
| `account_key` *             | uuid4 | Chave da conta debitada. |
| `total_amount` *            | number | Soma dos valores (`payment_amount`) dos itens do lote. |
| `batch_status` *         | [enum](#enumeradores-batch_payment_status) | Status do lote logo após a solicitação; depende do fluxo (confirmação, 2FA e processamento imediato). |
| `payment_type` *            | [enum](#enumeradores-payment_type) | Tipo do pagamento. |

### Enumeradores batch_payment_status

| Enumerador    | Descrição     |
|---------------|---------------|
| `pending`     | Pendente de processamento |
| `pending_2fa_approval` | Pendente de aprovação 2FA |
| `rejected`    | Rejeitado |
| `approved`    | Aprovado |
| `processed`   | Processado |

### Enumeradores payment_type

| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

:::danger Aviso
O enumerador `collection_slip` não se aplica ao fluxo de lote de boletos bancários deste endpoint; para este caso, espera-se `payment_type` com valor `bank_slip`.
:::

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 403         | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404         | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400         | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 400         | BIP000050 | Bad Request | Requester configuration does not exist. | Configuração do requester não existe. |
| 400         | BIP000052 | Bad Request | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta |
| 400         | BIP000053 | Bad Request | Error getting approver data | Erro ao obter dados do aprovador |
| 400         | BIP000054 | Bad Request | TFA info required | Informações de TFA necessárias |
| 400         | BIP000055 | Bad Request | Error sending verification token | Erro ao enviar token de verificação |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |
| 400         | BIP000079 | Bad Request | A session_id must be provided token | Uma session_id deve ser fornecida |
| 400         | BIP000080 | Bad Request | Beneficiary bank code of this bank slip is not allowed. | Banco beneficiário desse boleto não é permitido. |
| 400         | BIP000081 | Bad Request | A list of bank slip payments must be provided. | Uma lista de boletos bancários deve ser fornecida. |

---

# Solicitar pagamento em lote de boleto bancário com autenticação de dois fatores

URL: /documentation/baas/cobranca/2fa_v2/solicitar_pagamento_lote_de_boleto_bancario_sem_confirmacao_de_lote

Este endpoint permite solicitar o pagamento de múltiplos boletos bancários em uma única requisição, com **`tfa_info`** quando a operação exigir autenticação de dois fatores **nesta solicitação**.

:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::

## Request

### Request Endpoint

ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments/batch_bank_slip
MÉTODO POST

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |

## Autenticação via email e SMS

Request Body: lote com linha digitável e TFA por SMS ou email

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  },
  "bank_slip_payments": [
    {
      "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
      "digitable_line": "00190000090361557400500000024174396700000991000",
      "payment_amount": 1156.8
    }
  ]
}
```

Request Body: lote com código de barras e TFA por SMS ou email

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  },
  "bank_slip_payments": [
    {
      "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
      "barcode": "00190000090361557400500000024174396700000991000",
      "payment_amount": 1156.8
    }
  ]
}
```

## Autenticação via dispositivo

Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`.

Request Body: lote com linha digitável e TFA por dispositivo

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
    "contact_type": "device"
  },
  "bank_slip_payments": [
    {
      "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
      "digitable_line": "00190000090361557400500000024174396700000991000",
      "payment_amount": 1156.8
    }
  ]
}
```

Request Body: lote com código de barras e TFA por dispositivo

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
    "contact_type": "device"
  },
  "bank_slip_payments": [
    {
      "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
      "barcode": "00190000090361557400500000024174396700000991000",
      "payment_amount": 1156.8
    }
  ]
}
```

### Body Params

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | Chave única de identificação da requisição do cliente (lote). |
| `tfa_info`       | object | Quando o 2FA for exigido **nesta etapa** (solicitação do lote), envie aprovador e canal de envio do token no [objeto `tfa_info`](#objeto-tfa_info). Caso o fluxo não exija 2FA na solicitação, omita o campo. |
| `bank_slip_payments` * | array     | Lista de pagamentos de boleto bancário. Limite de **1000** itens por requisição. |

Cada elemento de `bank_slip_payments` deve conter:

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | Chave única de identificação da requisição do cliente para aquele item do lote. |
| `barcode`               | string    | Código de barras. |
| `digitable_line`        | string    | Linha digitável. |
| `payment_amount` *      | number    | Valor a ser pago. |

:::danger Aviso
Para cada item, o `payment_amount` enviado deve ser compatível com o que a consulta interna do boleto determinar: se o pagamento parcial **não** for permitido para aquele título, o valor deve corresponder ao total atualizado; se for permitido, o `payment_amount` pode seguir as regras do título (incluindo, quando aplicável, valores acima do nominal), como no fluxo de pagamento unitário de boleto bancário.
:::

### Objeto tfa_info

| Campo                        | Tipo   | Descrição                                                                                                                                          |
| ---------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `approver_document_number` * | string | Documento (CPF/CNPJ) da pessoa aprovadora que receberá o token ou aprovará via dispositivo. Obrigatório quando `tfa_info` é enviado.                |
| `session_id`                 | string | Chave única de identificação da sessão do dispositivo no formato UUID v4 (**obrigatório** para TFA via dispositivo).                               |
| `contact_type` *             | string | Canal para envio ou validação do token: **[Enumerador contact_type](#enumerador-contact_type)**. Obrigatório quando `tfa_info` é enviado. |

#### Enumerador contact_type

| Enumerador | Descrição                                         |
|------------|---------------------------------------------------|
| **sms**    | Envio por mensagem de texto para telefone celular |
| **email**  | Envio por correio eletrônico                      |
| **device** | Validação por token do dispositivo                |

## Response

### Success Response

STATUS 201

Response Body: Lote pendente de aprovação de dois fatores

```json
{
  "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
  "total_amount": 1357.3,
  "batch_status": "pending_2fa_approval",
  "payment_type": "bank_slip"
}
```

:::info Processamento do lote
O campo `batch_status` na resposta indica o **estado imediato** do lote após esta solicitação (por exemplo, pendente de aprovação 2FA ou já encaminhado ao processamento), conforme o fluxo aplicável. O 2FA pode integrar esta solicitação (`tfa_info`) ou outras etapas do fluxo, conforme a operação. Os valores possíveis de `batch_status` estão em [batch_payment_status](#enumeradores-batch_payment_status).
:::

### Response Body Params

| Campo               | Tipo    | Descrição                         |
|---------------------|---------|-----------------------------------|
| `batch_payment_key` *       | uuid4 | Chave única de identificação do pagamento em lote. |
| `request_control_key` *     | uuid4 | Chave única de identificação da requisição do cliente (lote). |
| `account_key` *             | uuid4 | Chave da conta debitada. |
| `total_amount` *            | number | Soma dos valores (`payment_amount`) dos itens do lote. |
| `batch_status` *         | [enum](#enumeradores-batch_payment_status) | Status do lote logo após a solicitação; depende do fluxo (2FA e processamento imediato). |
| `payment_type` *            | [enum](#enumeradores-payment_type) | Tipo do pagamento. |

### Enumeradores batch_payment_status

| Enumerador    | Descrição     |
|---------------|---------------|
| `pending`     | Pendente de processamento |
| `pending_2fa_approval` | Lote pendente de 2FA para aprovação |
| `pending_2fa_rejection` | Lote pendente de 2FA para rejeição |
| `rejected`    | Rejeitado |
| `approved`    | Aprovado |
| `processed`   | Processado |

### Enumeradores payment_type

| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

:::danger Aviso
O enumerador `collection_slip` não se aplica ao fluxo de lote de boletos bancários deste endpoint; para este caso, espera-se `payment_type` com valor `bank_slip`.
:::

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 403         | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404         | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400         | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 400         | BIP000050 | Bad Request | Requester configuration does not exist. | Configuração do requester não existe. |
| 400         | BIP000052 | Bad Request | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta |
| 400         | BIP000053 | Bad Request | Error getting approver data | Erro ao obter dados do aprovador |
| 400         | BIP000054 | Bad Request | TFA info required | Informações de TFA necessárias |
| 400         | BIP000055 | Bad Request | Error sending verification token | Erro ao enviar token de verificação |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |
| 400         | BIP000079 | Bad Request | A session_id must be provided token | Uma session_id deve ser fornecida |
| 400         | BIP000080 | Bad Request | Beneficiary bank code of this bank slip is not allowed. | Banco beneficiário desse boleto não é permitido. |
| 400         | BIP000081 | Bad Request | A list of bank slip payments must be provided. | Uma lista de boletos bancários deve ser fornecida. |

---

# Solicitar pagamento em lote de fatura de recolhimento (convênio/tributo) com autenticação de dois fatores

URL: /documentation/baas/cobranca/2fa_v2/solicitar_pagamento_lote_de_fatura_de_recolhimento_com_confirmacao_de_lote

Este endpoint permite solicitar o pagamento de múltiplas faturas de recolhimento em uma única requisição, com **`tfa_info`** quando a operação exigir autenticação de dois fatores **nesta solicitação**.

:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um boleto bancário apresenta.
:::

:::info Fluxo após a solicitação
Após a solicitação, o lote pode permanecer aguardando a [confirmação do lote com autenticação de dois fatores](./confirmacao_de_lote_de_fatura_de_recolhimento.md), conforme as regras da operação. Quando o 2FA for exigido nesta solicitação, o corpo deve incluir **`tfa_info`** conforme as seções abaixo e o [objeto `tfa_info`](#objeto-tfa_info). Na etapa de confirmação do lote deste fluxo, siga a documentação com `tfa_info`.
:::

## Request

### Request Endpoint

ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments/batch_collection_slip
MÉTODO POST

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |

Request Body: Pagamento em lote de faturas de recolhimento (sem TFA nesta etapa)

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "collection_slip_payments": [
    {
      "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
      "digitable_line": "836200000138892100450006762142420244046000010192",
      "payment_amount": 1389.21
    },
    {
      "request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e",
      "barcode": "83620000001388921004500067621424202440460000101",
      "payment_amount": 1389.21
    }
  ]
}
```

## Autenticação via email e SMS

Request Body: lote com linha digitável e TFA por SMS ou email

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  },
  "collection_slip_payments": [
    {
      "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
      "digitable_line": "836200000138892100450006762142420244046000010192",
      "payment_amount": 1389.21
    }
  ]
}
```

Request Body: lote com código de barras e TFA por SMS ou email

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  },
  "collection_slip_payments": [
    {
      "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
      "barcode": "83620000001388921004500067621424202440460000101",
      "payment_amount": 1389.21
    }
  ]
}
```

## Autenticação via dispositivo

Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`.

Request Body: lote com linha digitável e TFA por dispositivo

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
    "contact_type": "device"
  },
  "collection_slip_payments": [
    {
      "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
      "digitable_line": "836200000138892100450006762142420244046000010192",
      "payment_amount": 1389.21
    }
  ]
}
```

Request Body: lote com código de barras e TFA por dispositivo

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
    "contact_type": "device"
  },
  "collection_slip_payments": [
    {
      "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
      "barcode": "83620000001388921004500067621424202440460000101",
      "payment_amount": 1389.21
    }
  ]
}
```

### Body Params

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | Chave única de identificação da requisição do cliente (lote). |
| `tfa_info`       | object | Quando o 2FA for exigido **nesta etapa** (solicitação do lote), envie aprovador e canal de envio do token no [objeto `tfa_info`](#objeto-tfa_info). Caso o fluxo não exija 2FA na solicitação, omita o campo. |
| `collection_slip_payments` * | array     | Lista de pagamentos de fatura de recolhimento. Limite de **1000** itens por requisição. |

Cada elemento de `collection_slip_payments` deve conter:

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | Chave única de identificação da requisição do cliente para aquele item do lote. |
| `barcode`               | string    | Código de barras. |
| `digitable_line`        | string    | Linha digitável. |
| `payment_amount` *      | number    | Valor a ser pago. |

:::danger Aviso
Para cada item, o `payment_amount` enviado deve ser compatível com o que a consulta interna da fatura de recolhimento determinar (por exemplo, alinhado ao `total_amount` e às regras do convênio/tributo), nas mesmas condições do fluxo de pagamento unitário de fatura de recolhimento.
:::

### Objeto tfa_info

| Campo                        | Tipo   | Descrição                                                                                                                                          |
| ---------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `approver_document_number` * | string | Documento (CPF/CNPJ) da pessoa aprovadora que receberá o token ou aprovará via dispositivo. Obrigatório quando `tfa_info` é enviado.                |
| `session_id`                 | string | Chave única de identificação da sessão do dispositivo no formato UUID v4 (**obrigatório** para TFA via dispositivo).                               |
| `contact_type` *             | string | Canal para envio ou validação do token: **[Enumerador contact_type](#enumerador-contact_type)**. Obrigatório quando `tfa_info` é enviado. |

#### Enumerador contact_type

| Enumerador | Descrição                                         |
|------------|---------------------------------------------------|
| **sms**    | Envio por mensagem de texto para telefone celular |
| **email**  | Envio por correio eletrônico                      |
| **device** | Validação por token do dispositivo                |

## Response

### Success Response

STATUS 202

Response Body: Lote aceito para processamento

```json
{
  "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "total_amount": 2778.42,
  "batch_status": "pending",
  "payment_type": "collection_slip"
}
```

Response Body: exemplo ilustrativo (`batch_status` aprovado)

```json
{
  "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "total_amount": 2778.42,
  "batch_status": "approved",
  "payment_type": "collection_slip"
}
```

:::info Processamento do lote
O campo `batch_status` na resposta indica o **estado imediato** do lote após esta solicitação (por exemplo, pendente de confirmação, pendente de aprovação 2FA ou já encaminhado ao processamento), conforme o fluxo aplicável. Quando houver etapa de [confirmação do lote](./confirmacao_de_lote_de_fatura_de_recolhimento.md), siga essa documentação para aprovar ou rejeitar o lote com autenticação de dois fatores. Os valores possíveis de `batch_status` estão em [batch_payment_status](#enumeradores-batch_payment_status).
:::

### Response Body Params

| Campo               | Tipo    | Descrição                         |
|---------------------|---------|-----------------------------------|
| `batch_payment_key` *       | uuid4 | Chave única de identificação do pagamento em lote. |
| `request_control_key` *     | uuid4 | Chave única de identificação da requisição do cliente (lote). |
| `account_key` *             | uuid4 | Chave da conta debitada. |
| `total_amount` *            | number | Soma dos valores (`payment_amount`) dos itens do lote. |
| `batch_status` *         | [enum](#enumeradores-batch_payment_status) | Status do lote logo após a solicitação; depende do fluxo (confirmação, 2FA e processamento imediato). |
| `payment_type` *            | [enum](#enumeradores-payment_type) | Tipo do pagamento. |

### Enumeradores batch_payment_status

| Enumerador    | Descrição     |
|---------------|---------------|
| `pending`     | Pendente de processamento |
| `pending_2fa_approval` | Pendente de aprovação 2FA |
| `rejected`    | Rejeitado |
| `approved`    | Aprovado |
| `processed`   | Processado |

### Enumeradores payment_type

| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

:::danger Aviso
O enumerador `bank_slip` não se aplica ao fluxo de lote de faturas de recolhimento deste endpoint; para este caso, espera-se `payment_type` com valor `collection_slip`.
:::

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400         | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 400         | BIP000050 | Bad Request | Requester configuration does not exist. | Configuração do requester não existe. |
| 400         | BIP000052 | Bad Request | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta |
| 400         | BIP000053 | Bad Request | Error getting approver data | Erro ao obter dados do aprovador |
| 400         | BIP000054 | Bad Request | TFA info required | Informações de TFA necessárias |
| 400         | BIP000055 | Bad Request | Error sending verification token | Erro ao enviar token de verificação |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |
| 400         | BIP000079 | Bad Request | A session_id must be provided token | Uma session_id deve ser fornecida |
| 400         | BIP000082 | Bad Request | A list of collection slip payments must be provided. | Uma lista de faturas de recolhimento deve ser fornecida. |

---

# Solicitar pagamento em lote de fatura de recolhimento (convênio/tributo) com autenticação de dois fatores

URL: /documentation/baas/cobranca/2fa_v2/solicitar_pagamento_lote_de_fatura_de_recolhimento_sem_confirmacao_de_lote

Este endpoint permite solicitar o pagamento de múltiplas faturas de recolhimento em uma única requisição, com **`tfa_info`** quando a operação exigir autenticação de dois fatores **nesta solicitação**.

:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um boleto bancário apresenta.
:::

:::info Fluxo após a solicitação
A **autenticação de dois fatores (2FA)** é exigida **nesta solicitação**; o corpo deve incluir **`tfa_info`** conforme as seções abaixo e o [objeto `tfa_info`](#objeto-tfa_info).
:::

## Request

### Request Endpoint

ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments/batch_collection_slip
MÉTODO POST

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |

## Autenticação via email e SMS

Request Body: lote com linha digitável e TFA por SMS ou email

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  },
  "collection_slip_payments": [
    {
      "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
      "digitable_line": "836200000138892100450006762142420244046000010192",
      "payment_amount": 1389.21
    }
  ]
}
```

Request Body: lote com código de barras e TFA por SMS ou email

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  },
  "collection_slip_payments": [
    {
      "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
      "barcode": "83620000001388921004500067621424202440460000101",
      "payment_amount": 1389.21
    }
  ]
}
```

## Autenticação via dispositivo

Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`.

Request Body: lote com linha digitável e TFA por dispositivo

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
    "contact_type": "device"
  },
  "collection_slip_payments": [
    {
      "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
      "digitable_line": "836200000138892100450006762142420244046000010192",
      "payment_amount": 1389.21
    }
  ]
}
```

Request Body: lote com código de barras e TFA por dispositivo

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
    "contact_type": "device"
  },
  "collection_slip_payments": [
    {
      "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
      "barcode": "83620000001388921004500067621424202440460000101",
      "payment_amount": 1389.21
    }
  ]
}
```

### Body Params

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | Chave única de identificação da requisição do cliente (lote). |
| `tfa_info`       | object | Quando o 2FA for exigido **nesta etapa** (solicitação do lote), envie aprovador e canal de envio do token no [objeto `tfa_info`](#objeto-tfa_info). Caso o fluxo não exija 2FA na solicitação, omita o campo. |
| `collection_slip_payments` * | array     | Lista de pagamentos de fatura de recolhimento. Limite de **1000** itens por requisição. |

Cada elemento de `collection_slip_payments` deve conter:

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | Chave única de identificação da requisição do cliente para aquele item do lote. |
| `barcode`               | string    | Código de barras. |
| `digitable_line`        | string    | Linha digitável. |
| `payment_amount` *      | number    | Valor a ser pago. |

:::danger Aviso
Para cada item, o `payment_amount` enviado deve ser compatível com o que a consulta interna da fatura de recolhimento determinar (por exemplo, alinhado ao `total_amount` e às regras do convênio/tributo), nas mesmas condições do fluxo de pagamento unitário de fatura de recolhimento.
:::

### Objeto tfa_info

Os campos seguem o mesmo formato da [solicitação de pagamento de fatura de recolhimento](./solicitacao_de_pagamento_de_fatura_de_recolhimento.md#objeto-tfa_info).

| Campo                        | Tipo   | Descrição                                                                                                                                          |
| ---------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `approver_document_number` * | string | Documento (CPF/CNPJ) da pessoa aprovadora que receberá o token ou aprovará via dispositivo. Obrigatório quando `tfa_info` é enviado.                |
| `session_id`                 | string | Chave única de identificação da sessão do dispositivo no formato UUID v4 (**obrigatório** para TFA via dispositivo).                               |
| `contact_type` *             | string | Canal para envio ou validação do token: **[Enumerador contact_type](#enumerador-contact_type)**. Obrigatório quando `tfa_info` é enviado. |

#### Enumerador contact_type

| Enumerador | Descrição                                         |
|------------|---------------------------------------------------|
| **sms**    | Envio por mensagem de texto para telefone celular |
| **email**  | Envio por correio eletrônico                      |
| **device** | Validação por token do dispositivo                |

## Response

### Success Response

STATUS 202

Response Body: Lote aceito para processamento

```json
{
  "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "total_amount": 2778.42,
  "batch_status": "pending",
  "payment_type": "collection_slip"
}
```

Response Body: exemplo ilustrativo com `batch_status` aprovado

```json
{
  "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "total_amount": 2778.42,
  "batch_status": "approved",
  "payment_type": "collection_slip"
}
```

:::info Processamento do lote
O campo `batch_status` na resposta indica o **estado imediato** do lote após esta solicitação (por exemplo, pendente de aprovação 2FA ou já encaminhado ao processamento), conforme o fluxo aplicável. O 2FA pode integrar esta solicitação (`tfa_info`) ou outras etapas do fluxo, conforme a operação. Os valores possíveis de `batch_status` estão em [batch_payment_status](#enumeradores-batch_payment_status).
:::

### Response Body Params

| Campo               | Tipo    | Descrição                         |
|---------------------|---------|-----------------------------------|
| `batch_payment_key` *       | uuid4 | Chave única de identificação do pagamento em lote. |
| `request_control_key` *     | uuid4 | Chave única de identificação da requisição do cliente (lote). |
| `account_key` *             | uuid4 | Chave da conta debitada. |
| `total_amount` *            | number | Soma dos valores (`payment_amount`) dos itens do lote. |
| `batch_status` *         | [enum](#enumeradores-batch_payment_status) | Status do lote logo após a solicitação; depende do fluxo (2FA e processamento imediato). |
| `payment_type` *            | [enum](#enumeradores-payment_type) | Tipo do pagamento. |

### Enumeradores batch_payment_status

| Enumerador    | Descrição     |
|---------------|---------------|
| `pending`     | Pendente de processamento |
| `pending_2fa_approval` | Pendente de aprovação 2FA |
| `rejected`    | Rejeitado |
| `approved`    | Aprovado |
| `processed`   | Processado |

### Enumeradores payment_type

| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

:::danger Aviso
O enumerador `bank_slip` não se aplica ao fluxo de lote de faturas de recolhimento deste endpoint; para este caso, espera-se `payment_type` com valor `collection_slip`.
:::

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400         | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 400         | BIP000050 | Bad Request | Requester configuration does not exist. | Configuração do requester não existe. |
| 400         | BIP000052 | Bad Request | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta |
| 400         | BIP000053 | Bad Request | Error getting approver data | Erro ao obter dados do aprovador |
| 400         | BIP000054 | Bad Request | TFA info required | Informações de TFA necessárias |
| 400         | BIP000055 | Bad Request | Error sending verification token | Erro ao enviar token de verificação |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |
| 400         | BIP000079 | Bad Request | A session_id must be provided token | Uma session_id deve ser fornecida |
| 400         | BIP000082 | Bad Request | A list of collection slip payments must be provided. | Uma lista de faturas de recolhimento deve ser fornecida. |

---

# Validação de token de lote de pagamento de boleto bancário

URL: /documentation/baas/cobranca/2fa_v2/validacao_de_token_de_lote_de_boleto_bancario

Este endpoint conclui a etapa de **autenticação de dois fatores (2FA)** para um lote de boletos bancários que, após a [confirmação do lote com `tfa_info`](./confirmacao_de_lote_de_boleto_bancario.md), encontra-se em `batch_status` **`pending_2fa_approval`** (aprovação) ou **`pending_2fa_rejection`** (rejeição). Com o token validado, o lote segue para **processamento assíncrono** dos pagamentos e o status final reflete a decisão registrada na confirmação (`approved` ou `rejected`). Para solicitar novo envio do token enquanto o lote estiver em **pending_2fa_approval** (aprovação) ou **pending_2fa_rejection** (rejeição), use [Reenviar token de confirmação de lote de pagamento de boleto bancário](./solicitacao_de_reenvio_de_token_de_lote_de_boleto_bancario.md).

:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::

## Request

### Request Endpoint

ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_bank_slip/**PAYMENT_BATCH_KEY**/validate_token
MÉTODO PATCH

### Request Path Params

| Campo                 | Tipo  | Descrição                                                                                | Caracteres |
| --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- |
| `account_key` *       | uuid4 | Chave única de identificação da conta.                                                   | 36         |
| `payment_batch_key` * | uuid4 | Chave única de identificação do lote (`batch_payment_key` retornado na criação do lote). | 36         |

### Autenticação via Email e SMS

Request Body: Validação de token do lote

```json
{
  "token": "329adf"
}
```

### Autenticação via Dispositivo

Para finalizar a autenticação via dispositivo, a requisição deve ser enviada com um payload vazio. A validação ocorre internamente, sem necessidade de informações adicionais no corpo da requisição. Este endpoint só deve ser utilizado após o lote ter entrado em **`pending_2fa_approval`** (aprovação) ou **`pending_2fa_rejection`** (rejeição) na [confirmação do lote com `tfa_info`](./confirmacao_de_lote_de_boleto_bancario.md).

Request Body: Validação de token do lote

```json
{

}
```

### Body Params

| Campo   | Tipo   | Descrição                                                                                                        | Caracteres |
| ------- | ------ | ---------------------------------------------------------------------------------------------------------------- | ---------- |
| `token` | string | Código de autenticação enviado ao aprovador de movimentações da conta **obrigatório para TFA via SMS ou e-mail** | 6          |

## Response

### Success Response

Após a validação bem-sucedida, a API responde com **202** e o lote passa a ser processado de forma assíncrona. O status final segue a decisão registrada na confirmação (`approved` ou `rejected`).

STATUS 202

Response Body: Lote após validação do token (exemplo com decisão `approved`)

```json
{
  "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
  "total_amount": 1357.3,
  "batch_status": "approved",
  "payment_type": "bank_slip"
}
```

### Response Body Params

| Campo                   | Tipo   | Descrição                                                                                                                                                                                                                                                                    |
| ----------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batch_payment_key` *   | uuid4  | Chave única de identificação do pagamento em lote.                                                                                                                                                                                                                           |
| `request_control_key` * | uuid4  | Chave única de identificação da requisição do cliente (lote).                                                                                                                                                                                                                |
| `account_key` *         | uuid4  | Chave da conta debitada.                                                                                                                                                                                                                                                     |
| `total_amount` *        | number | Soma dos valores dos itens do lote.                                                                                                                                                                                                                                          |
| `batch_status` *        | string | Após validação do token, o status final reflete a decisão registrada na confirmação (`approved` ou `rejected`). O ciclo de `batch_status` está alinhado ao descrito na documentação de **solicitação de pagamento em lote** fornecida à operação (enumeradores `batch_payment_status`). |
| `payment_type` *        | string | Tipo do pagamento; para este fluxo, espera-se `bank_slip`.                                                                                                                                                                                                                     |

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título      | Descrição (eng)                               | Descrição (pt-br)                                                |
| ----------- | --------- | ----------- | --------------------------------------------- | ---------------------------------------------------------------- |
| 403         | BIP000010 | Forbidden   | User is not allowed to do this action         | Usuário não tem autorização para fazer essa ação                 |
| 404         | BIP000011 | Not Found   | The source account key was not found.         | A chave da conta de origem não foi encontrada.                   |
| 400         | BIP000013 | Bad Request | The source account is closed.                 | A conta de origem está fechada.                                 |
| 400         | BIP000050 | Bad Request | Requester configuration does not exist        | Configuração do requester não existe.                            |
| 400         | BIP000058 | Bad Request | Error while validating verification token     | Erro ao validar token de verificação                             |
| 400         | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Número de tentativas de validação de token de verificação excedido. |
| 400         | BIP000060 | Bad Request | Verification token expired.                   | Token de verificação expirado.                                   |
| 400         | BIP000061 | Bad Request | Verification token validation failed.       | Falha na validação do token de verificação.                      |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded.    | Janela de tempo de verificação de pagamento excedida.            |
| 404         | BIP000083 | Not Found   | Batch payment not found by batch payment key. | Lote de pagamentos não encontrado pela chave do lote.            |
| 400         | BIP000085 | Bad Request | Batch payment status is not pending approval. | Status do lote de pagamentos não é de aprovação pendente.        |
| 400         | BIP000086 | Bad Request | A token is required for SMS or email validation.                    | Um token é necessário para validação via SMS ou email.             |

---

# Validação de token de lote de pagamento de fatura de recolhimento (convênio/tributo)

URL: /documentation/baas/cobranca/2fa_v2/validacao_de_token_de_lote_de_fatura_de_recolhimento

Este endpoint conclui a etapa de **autenticação de dois fatores (2FA)** para um lote de faturas de recolhimento que, após a [confirmação do lote com `tfa_info`](./confirmacao_de_lote_de_fatura_de_recolhimento.md), encontra-se em `batch_status` **`pending_2fa_approval`** (aprovação) ou **`pending_2fa_rejection`** (rejeição). Com o token validado, o lote segue para **processamento assíncrono** dos pagamentos e o status final reflete a decisão registrada na confirmação (`approved` ou `rejected`). Para solicitar novo envio do token enquanto o lote estiver em **pending_2fa_approval** (aprovação) ou **pending_2fa_rejection** (rejeição), use [Reenviar token de confirmação de lote de pagamento de fatura de recolhimento (convênio/tributo)](./solicitacao_de_reenvio_de_token_de_lote_de_fatura_de_recolhimento.md).

:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::

## Request

### Request Endpoint

ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_collection_slip/**PAYMENT_BATCH_KEY**/validate_token
MÉTODO PATCH

### Request Path Params

| Campo                 | Tipo  | Descrição                                                                                | Caracteres |
| --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- |
| `account_key` *       | uuid4 | Chave única de identificação da conta.                                                   | 36         |
| `payment_batch_key` * | uuid4 | Chave única de identificação do lote (`batch_payment_key` retornado na criação do lote). | 36         |

### Autenticação via Email e SMS

Request Body: Validação de token do lote

```json
{
  "token": "329adf"
}
```

### Autenticação via Dispositivo

Para finalizar a autenticação via dispositivo, a requisição deve ser enviada com um payload vazio. A validação ocorre internamente, sem necessidade de informações adicionais no corpo da requisição. Este endpoint só deve ser utilizado após o lote ter entrado em **`pending_2fa_approval`** (aprovação) ou **`pending_2fa_rejection`** (rejeição) na [confirmação do lote com `tfa_info`](./confirmacao_de_lote_de_fatura_de_recolhimento.md).

Request Body: Validação de token do lote

```json
{

}
```

### Body Params

| Campo   | Tipo   | Descrição                                                                                                        | Caracteres |
| ------- | ------ | ---------------------------------------------------------------------------------------------------------------- | ---------- |
| `token` | string | Código de autenticação enviado ao aprovador de movimentações da conta **obrigatório para TFA via SMS ou e-mail** | 6          |

## Response

### Success Response

Após a validação bem-sucedida, a API responde com **202** e o lote passa a ser processado de forma assíncrona. O status final segue a decisão registrada na confirmação (`approved` ou `rejected`).

STATUS 202

Response Body: Lote após validação do token (exemplo com decisão `approved`)

```json
{
  "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "total_amount": 2778.42,
  "batch_status": "approved",
  "payment_type": "collection_slip"
}
```

### Response Body Params

| Campo                   | Tipo   | Descrição                                                                                                                                                                                                                                                                                         |
| ----------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batch_payment_key` *   | uuid4  | Chave única de identificação do pagamento em lote.                                                                                                                                                                                                                                                |
| `request_control_key` * | uuid4  | Chave única de identificação da requisição do cliente (lote).                                                                                                                                                                                                                                       |
| `account_key` *         | uuid4  | Chave da conta debitada.                                                                                                                                                                                                                                                                          |
| `total_amount` *        | number | Soma dos valores dos itens do lote.                                                                                                                                                                                                                                                               |
| `batch_status` *        | string | Após validação do token, o status final reflete a decisão registrada na confirmação (`approved` ou `rejected`). O ciclo de `batch_status` está alinhado ao descrito na documentação de **solicitação de pagamento em lote** fornecida à operação (enumeradores `batch_payment_status`). |
| `payment_type` *        | string | Tipo do pagamento; para este fluxo, espera-se `collection_slip`.                                                                                                                                                                                                                                   |

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título      | Descrição (eng)                               | Descrição (pt-br)                                                |
| ----------- | --------- | ----------- | --------------------------------------------- | ---------------------------------------------------------------- |
| 403         | BIP000010 | Forbidden   | User is not allowed to do this action         | Usuário não tem autorização para fazer essa ação                 |
| 404         | BIP000011 | Not Found   | The source account key was not found.         | A chave da conta de origem não foi encontrada.                   |
| 400         | BIP000013 | Bad Request | The source account is closed.                 | A conta de origem está fechada.                                 |
| 400         | BIP000050 | Bad Request | Requester configuration does not exist        | Configuração do requester não existe.                            |
| 400         | BIP000058 | Bad Request | Error while validating verification token     | Erro ao validar token de verificação                             |
| 400         | BIP000059 | Bad Request | Number of verification token validation attempts exceeded. | Número de tentativas de validação de token de verificação excedido. |
| 400         | BIP000060 | Bad Request | Verification token expired.                   | Token de verificação expirado.                                   |
| 400         | BIP000061 | Bad Request | Verification token validation failed.       | Falha na validação do token de verificação.                      |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded.    | Janela de tempo de verificação de pagamento excedida.            |
| 404         | BIP000083 | Not Found   | Batch payment not found by batch payment key. | Lote de pagamentos não encontrado pela chave do lote.            |
| 400         | BIP000085 | Bad Request | Batch payment status is not pending approval.         | Status do lote de pagamentos não é de aprovação pendente.              |
| 400         | BIP000086 | Bad Request | A token is required for SMS or email validation.                    | Um token é necessário para validação via SMS ou email.             |

---

# Agendar Pagamento de Boleto Bancário

URL: /documentation/baas/cobranca/agendamento/agendar_pagamento_de_boleto_bancario

Este endpoint permite realizar o agendamento do pagamento de boletos bancários. 
O agendamento deve ser realizado após a consulta do boleto bancário, utilizando as informações retornadas para garantir o funcionamento correto do fluxo, evitando falhas durante o processo de pagamento.

:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/bank_slip
MÉTODO POST

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |

Request Body: Pagamento de boleto bancário com linha digitável

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "digitable_line": "00190000090361557400500000024174396700000991000",
  "payment_amount": 1156.8,
  "payment_date": "2024-03-30"
}
```
Request Body: Pagamento de boleto bancário com código de barras

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "barcode": "00190000090361557400500000024174396700000991000",
  "payment_amount": 1156.8,
  "payment_date": "2024-03-30"
}
```

### Body Params

| Campo                   | Tipo   | Descrição                                           |
|-------------------------|--------|-----------------------------------------------------|
| `request_control_key` * | uuid4  | Chave única de identificação da request do cliente. |    
| `barcode`               | string | Código de barras.                                   |
| `digitable_line`        | string | Linha digitável.                                    |
| `payment_amount` *      | number | Valor a ser pago.                                   |
| `payment_date` *        | string | Data do agendamento.                                |

:::danger Aviso
O `payment_amount` deve ser sempre igual ao `total_amount` retornado na consulta do boleto bancário caso o pagamento parcial 
não seja permitido para o boleto bancário. Para títulos em que o pagamento parcial é permitido,
o cliente pode escolher o `payment_amount`, desde que a soma do mesmo com o `registered_payment_amount` 
do boleto bancário não seja superior ao `total_amount`.
:::

## Response

### Success Response

STATUS 201

Response Body: Agendamento confirmado

```json
{
   "payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea",
   "request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189",
   "payer_name":"COOPERATIVA INDUSTRIAL MURILO",
   "payer_document_number":"00037025000160",
   "source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
   "paid_amount":1050.1,
   "payment_date":"2024-04-03",
   "payment_type":"bank_slip",
   "bank_slip": {
        "bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
        "barcode":"00193967000009910000000003615574000000002417",
        "digitable_line":"00190000090361557400500000024174396700000991000",
        "payer_name":"COOPERATIVA TESTE",
        "payer_document_number":"00037025000160",
        "beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
        "beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
        "beneficiary_document_number":"52069937000117",
        "beneficiary_bank_ispb":"00000000",
        "guarantor_name":null,
        "guarantor_document_number":null,
        "expiration_date":"2024-03-29",
        "max_payment_data": "2026-03-29",
        "partial_payment_indicator":"allowed",
        "registered_payment_amount":9029.0,
        "nominal_amount":9910.0,
        "total_amount":10129.1,
        "rebate_amount":0.0,
        "discount_amount":0.0,
        "fine_amount":0.0,
        "interest_amount":219.1
    },
   "collection_slip":null,
   "payment_schedule_status":"scheduled"
}
```

### Response Body Params

| Campo               | Tipo    | Descrição                         |
|---------------------|---------|-----------------------------------|
| `payment_key` *               | uuid4 | Chave única de identificação do pagamento. |
| `request_control_key` *       | uuid4 | Chave única de identificação da request do cliente. |
| `payer_name` *                | string | Nome do pagador efetivo.|
| `payer_document_number` *     | string | Número de documento do pagador efetivo (CPF/CNPJ). |
| `source_account_key` *        | uuid4 | Chave da conta debitada. |
| `paid_amount` *               | number | Valor pago efetivamente. |
| `payment_date` *              | string | Data do pagamento. |
| `payment_type` *              | [enum](#enumeradores-payment_type) | Tipo do pagamento. |
| `bank_slip`                   | [object](#objeto-bank_slip) | Boleto bancário. |
| `collection_slip`             | object | Fatura de recolhimento. |
| `payment_schedule_status` *            | [enum](#enumeradores-payment_schedule_status) | Status do pagamento. |

### Enumeradores payment_type
| Enumerador    | Descrição     |
|---------------|---------------|
| `bank_slip`     | Boleto bancário    |
| `collection_slip` | Fatura de recolhimento |

:::danger Aviso
O enumerador `collection_slip` não se aplica para o fluxo de boletos bancários, assim como o objeto collection_slip que sempre será nulo.
:::

### Enumeradores payment_schedule_status
| Enumerador          | Descrição                                                        |
|---------------------|------------------------------------------------------------------|
| `pending_2fa_approval` | Agendamento pendente de autenticação de dois fatores (2FA)       |
| `scheduled`          | Pagamento agendado com sucesso                                   |
| `executed`          | O agendamento foi executado com sucesso e o pagamento referente ao agendamento gerado |
| `rejected`          | O agendamento foi rejeitado e nenhum pagamento foi gerado       |
| `canceled`         | Agendamento cancelado                                            |
| `error`             | Erro ao realizar o agendamento                                   |

:::danger Aviso
Para pagamentos onde a QI não receber uma resposta da CIP em até dois minutos, o pagamento será retornado com o status `pending_execution`. Após a QI receber a resposta da CIP, será enviado para o cliente o webhook de pagamento pendente descrito na [página de webhooks](/documentation/baas/cobranca/webhooks).
:::

### Objeto bank_slip
| Campo                             | Tipo    | Descrição                         |
|-----------------------------------|---------|-----------------------------------|
| `barcode` *                       | string | Código de barras. |
| `digitable_line` *                | string | Linha digitável. |
| `payer_name` *                    | string | Nome do pagador.|
| `payer_document_number` *         | string | Número de documento do pagador (CPF/CNPJ). |
| `beneficiary_name` *              | string | Nome do beneficiário. |
| `beneficiary_trading_name`        | string | Nome fantasia do beneficiário. |
| `beneficiary_document_number` *   | string | Número de documento do beneficiário (CPF/CNPJ). |
| `beneficiary_bank_ispb` *         | string | Código ispb do banco do beneficiário. |
| `guarantor_name`                  | string | Nome do sacador avalista. |
| `guarantor_document_number`       | string | Número de documento do sacador avalista (CPF/CNPJ). |
| `expiration_date` *               | string | Data de vencimento. |
| `max_payment_date` * | string  | Data máxima de pagamento. |
| `partial_payment_indicator` *     | [enum](#enumeradores-partial_payment_indicator)   | Indicador de pagamento parcial. |
| `registered_payment_amount`       | string | Valor total de pagamento registrado. |
| `nominal_amount` *                | number | Valor original. |
| `total_amount` *                  | number | Valor total. |
| `rebate_amount` *                 | number | Valor do abatimento. |
| `discount_amount` *               | number | Valor do desconto. |
| `fine_amount` *                   | number | Valor da multa. |
| `interest_amount` *               | number | Valor do juros. |

### Enumeradores partial_payment_indicator
| Enumerador    | Descrição     |
|---------------|---------------|
| `allowed`     | Permitido     |
| `not_allowed` | Não permitido |

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400         | BIP000001 | Bad Request | The barcode or digitable line must have 44 or 47 characters. | O código de barras ou linha digitável deve ter 44 ou 47 caracteres. |
| 400         | BIP000002 | Bad Request | The bill sent does not correspond to a bank slip. | A conta enviado não corresponde a um boleto bancário. |
| 400         | BIP000003 | Bad Request | The digitable line sent is invalid. | A linha digitável enviada é inválida. |
| 404         | BIP000004 | Not Found | The bank slip was not found. | O boleto não foi encontrado. |
| 400         | BIP000005 | Bad Request | It was not possible to consult the bank slip at this time. Please try again in a few minutes. | Não foi possível consultar o boleto neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000006 | Bad Request | Bank slip already written off | Boleto já baixado |
| 400         | BIP000007 | Bad Request | Bank slip blocked for payment | Boleto bloqueado para pagamento |
| 400         | BIP000008 | Bad Request | Bank slip already paid | Boleto já pago |
| 400         | BIP000009 | Bad Request | Invalid bank slip. Please consult issuing bank | Boleto inválido. Favor consultar banco emissor |
| 403         | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404         | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400         | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400         | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 400         | BIP000015 | Bad Request | Payment date is greater than the maximum payment date. | A data de pagamento é maior que a data máxima de pagamento. |
| 400         | BIP000016 | Bad Request | Payment date is smaller than the calculation date. | A data de pagamento é menor que a data de cálculo. |
| 400         | BIP000017 | Bad Request | Invalid payment amount. | Valor de pagamento inválido. |
| 400         | BIP000018 | Bad Request | Partial payment is not allowed. | Pagamento parcial não é permitido. |
| 400         | BIP000019 | Bad Request | The payment amount is greater than the available amount. | O valor do pagamento é maior que o valor disponível. |
| 400         | BIP000020 | Bad Request | All partial payments for this bank slip have already been made. | Todos os pagamentos parciais deste boleto já foram realizados. |
| 400         | BIP000022 | Bad Request | Bank slip payment service is closed. | Serviço de pagamento de boleto está fechado. |
| 400         | BIP000023 | Bad Request | The source account has insufficient balance. Payment cannot be made. | A conta de origem possui saldo insuficiente. Pagamento não pode ser realizado. |
| 400         | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 400         | BIP000025 | Bad Request | It was not possible to pay the bank slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar o boleto neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. |
| 400         | BIP000028 | Bad Request | The source account has blocked balance. Payment cannot be made. | A conta de origem possui saldo em conta bloqueado. Pagamento não pode ser realizado. |

## Ambiente de Sandbox

Para realizar os testes em ambiente de sandbox, devem ser usadas as linhas digitáveis listadas na [Seção de pagamento de boleto bancário](/documentation/baas/cobranca/pagar_boleto_bancario).

---

# Agendar Pagamento de Fatura de Recolhimento (convênio/tributo)

URL: /documentation/baas/cobranca/agendamento/agendar_pagamento_de_fatura_de_recolhimento

Este endpoint permite realizar o agendamento de pagamento de faturas de recolhimento. 
O agendamento deve ser realizado após a consulta da Fatura de Recolhimento, utilizando as informações retornadas para garantir o funcionamento correto do fluxo, evitando falhas durante o processo de pagamento.

:::info Fatura de Recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/collection_slip
MÉTODO POST

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |

Request Body: Agendamento de fatura de recolhimento com linha digitável

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "digitable_line": "00190000090361557400500000024174396700000991000",
  "payment_amount": 1156.8,
  "payment_date": "2024-03-30"
}
```
Request Body: Agendamento de fatura de recolhimento com código de barras

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "barcode": "00190000090361557400500000024174396700000991000",
  "payment_amount": 1156.8,
  "payment_date": "2024-03-30"
}
```

### Body Params

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | Chave única de identificação da request do cliente. |    
| `barcode`               | string    | Código de barras. |
| `digitable_line`        | string    | Linha digitável. |
| `payment_amount` *      | number    | Valor a ser pago. |
| `payment_date` *        | string | Data do agendamento.                                |

:::danger Aviso
O `payment_amount` deve sempre igual ao `total_amount` retornado na consulta do boleto bancário.
:::

## Response

### Success Response

STATUS 201

Response Body: Agendamento confirmado

```json
{
  "payment_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
  "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
  "payer_name": "COOPERATIVA INDUSTRIAL MURILO",
  "payer_document_number": "62069937000118",
  "source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "paid_amount": 1389.21,
  "payment_date": "2024-04-30",
  "payment_type": "collection_slip",
  "bank_slip": null,
  "collection_slip": {
    "barcode": null,
    "digitable_line": "836200000138892100450006762142420244046000010192",
    "collection_name": "CIA ULTRAGAZ SA-COD",
    "collection_document_number": "00394460005887",
    "expiration_date": "2024-04-15",
    "total_amount": 1389.21
  },
  "payment_schedule_status": "scheduled"
}
```

### Response Body Params

| Campo               | Tipo    | Descrição                                           |
|---------------------|---------|-----------------------------------------------------|
| `payment_key` *               | uuid4 | Chave única de identificação do pagamento.          |
| `request_control_key` *       | uuid4 | Chave única de identificação da request do cliente. |
| `payer_name` *                | string | Nome do pagador efetivo.                            |
| `payer_document_number` *     | string | Número de documento do pagador efetivo (CPF/CNPJ).  |
| `source_account_key` *        | uuid4 | Chave da conta debitada.                            |
| `transaction_key` *           | uuid4 | Chave da transação do pagamento.                    |
| `transaction_revert_key`      | uuid4 | Chave da transação de reversão do pagamento.        |
| `paid_amount` *               | number | Valor pago efetivamente.                            |
| `payment_date` *              | string | Data do pagamento.                                  |
| `payment_type` *              | [enum](#enumeradores-payment_type) | Tipo do pagamento.                                  |
| `bank_slip`                   | object | Boleto bancário.                                    |
| `collection_slip`             | [object](#objeto-collection_slip) | Fatura de recolhimento.                             |
| `payment_schedule_status` *            | [enum](#enumeradores-payment_schedule_status) | Status do agendamento.                              |

### Enumeradores payment_type
| Enumerador    | Descrição     |
|---------------|---------------|
| `bank_slip`     | Boleto bancário    |
| `collection_slip` | Fatura de recolhimento |

:::danger Aviso
O enumerador `bank_slip` não se aplica para o fluxo de faturas de recolhimento, assim como o objeto bank_slip que sempre será nulo.
:::

### Enumeradores payment_schedule_status
| Enumerador          | Descrição                                                        |
|---------------------|------------------------------------------------------------------|
| `pending_2fa_approval` | Agendamento pendente de autenticação de dois fatores (2FA)       |
| `scheduled`          | Pagamento agendado com sucesso                                   |
| `executed`          | O agendamento foi executado com sucesso e o pagamento referente ao agendamento gerado |
| `rejected`          | O agendamento foi rejeitado e nenhum pagamento foi gerado             |
| `canceled`         | Agendamento cancelado                                            |
| `error`             | Erro ao realizar o agendamento                                   |

### Objeto collection_slip
| Campo                             | Tipo    | Descrição                         |
|-----------------------------------|---------|-----------------------------------|
| `barcode`          | string | Código de barras. |
| `digitable_line`   | string | Linha digitável. |
| `collection_name` *         | string | Nome do convênio.|
| `collection_document_number`   | string | Número de documento do convênio (CPF/CNPJ).|
| `expiration_date` *  | string  | Data de vencimento. |
| `total_amount` *  | number | Valor total. |

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400         | BIP000032 | Bad Request | The bill sent does not correspond to a collection slip. | A conta enviada não corresponde a uma fatura de recolhimento. |
| 400         | BIP000033 | Bad Request | The barcode or digitable line of the collection slip must have 44 or 48 characters. | O código de barras ou linha digitável da fatura de recolhimento deve ter 44 ou 48 caracteres. |
| 403         | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404         | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400         | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400         | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 400         | BIP000023 | Bad Request | The source account has insufficient balance. Payment cannot be made. | A conta de origem possui saldo insuficiente. Pagamento não pode ser realizado. |
| 400         | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 400         | BIP000028 | Bad Request | The source account has blocked balance. Payment cannot be made. | A conta de origem possui saldo em conta bloqueado. Pagamento não pode ser realizado. |
| 400         | BIP000034 | Bad Request | Collection slip already paid. | Fatura de recolhimento já paga. |
| 400         | BIP000035 | Bad Request | Covenant slip invalid barcode. | Código de barras da fatura de recolhimento inválido. |
| 400         | BIP000036 | Bad Request | Covenant slip overdue. | Fatura de recolhimento vencida. |
| 400         | BIP000037 | Bad Request | Error in collection slip consultation. | Erro na consulta da fatura de recolhimento. |
| 400         | BIP000038 | Bad Request | Outside of covenant payment hours. | Fora do horário de pagamento do convênio. |
| 400         | BIP000039 | Bad Request | Collection slip not accepted. | Fatura de recolhimento não aceita. |
| 400         | BIP000040 | Bad Request | Minimum advance not reached. | Mínimo de dias de adiantamento não atingido. |
| 400         | BIP000041 | Bad Request | Max payment amount exceeded. | Valor máximo de pagamento excedido. |
| 400         | BIP000044 | Bad Request | It was not possible to pay the collection slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar a fatura de recolhimento neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. |

## Ambiente de Sandbox

Em nosso ambiente de sandbox, disponibilizamos linhas digitáveis mockadas para a simulação de pagamentos bem-sucedidos e testes de cenários de erro.

### Cenários de sucesso

| Linha digitável |
|---|
| 828300000007411100972013905080001546763201900028 |
| 838000000009235700481007241345219112001474229880 |
| 848000000006308600802021201071261517689002201070 |
| 858200000015000000643025703477209504800448091020 |

### Cenários de erro

| Linha digitável | Código de erro |
|---|---|
| 858500000037350000643217212883260006147448091022 | BIP000035 |

---

# Cancelar Agendamento

URL: /documentation/baas/cobranca/agendamento/cancelar_agendamento

Este endpoint é utilizado para realizar o cancelamento de um agendamento de pagamento de um Boleto Bancário ou Fatura de Recolhimento.

:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::

:::info Fatura de Recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/ PAYMENT_SCHEDULE_KEY /cancel
MÉTODO PATCH

### Request Path Params

| Campo                    | Tipo    | Descrição                                    | Caracteres |
|--------------------------|---------|----------------------------------------------|------------|
| `account_key` *          | uuid4   | Chave única de identificação da conta.       | 36         |
| `payment_schedule_key` * | uuid4   | Chave única de identificação do agendamento. | 36         |

## Response

### Success Response

STATUS 200

Response Body: agendamento de pagamento de boleto bancário cancelado

```json
{
   "payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea",
   "request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189",
   "payer_name":"COOPERATIVA INDUSTRIAL MURILO",
   "payer_document_number":"00037025000160",
   "source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
   "paid_amount":1050.1,
   "payment_date":"2024-04-03",
   "payment_type":"bank_slip",
   "bank_slip": {
        "bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
        "barcode":"00193967000009910000000003615574000000002417",
        "digitable_line":"00190000090361557400500000024174396700000991000",
        "payer_name":"COOPERATIVA TESTE",
        "payer_document_number":"00037025000160",
        "beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
        "beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
        "beneficiary_document_number":"52069937000117",
        "beneficiary_bank_ispb":"00000000",
        "guarantor_name":null,
        "guarantor_document_number":null,
        "expiration_date":"2024-03-29",
        "max_payment_data": "2026-03-29",
        "partial_payment_indicator":"allowed",
        "registered_payment_amount":9029.0,
        "nominal_amount":9910.0,
        "total_amount":10129.1,
        "rebate_amount":0.0,
        "discount_amount":0.0,
        "fine_amount":0.0,
        "interest_amount":219.1
    },
   "collection_slip":null,
   "payment_schedule_status":"canceled"
}
```

Response Body: agendamento de pagamento de fatura de recolhimento cancelada

```json
{
  "payment_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
  "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
  "payer_name": "COOPERATIVA INDUSTRIAL MURILO",
  "payer_document_number": "62069937000118",
  "source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "paid_amount": 1389.21,
  "payment_date": "2024-04-30",
  "payment_type": "collection_slip",
  "bank_slip": null,
  "collection_slip": {
    "barcode": null,
    "digitable_line": "836200000138892100450006762142420244046000010192",
    "collection_name": "CIA ULTRAGAZ SA-COD",
    "collection_document_number": "00394460005887",
    "expiration_date": "2024-04-15",
    "total_amount": 1389.21
  },
  "payment_schedule_status": "canceled"
}
```

### Response Body Params

| Campo               | Tipo    | Descrição                                           |
|---------------------|---------|-----------------------------------------------------|
| `payment_key` *               | uuid4 | Chave única de identificação do pagamento.          |
| `request_control_key` *       | uuid4 | Chave única de identificação da request do cliente. |
| `payer_name` *                | string | Nome do pagador efetivo.                            |
| `payer_document_number` *     | string | Número do documento do pagador efetivo  (CPF/CNPJ). |
| `source_account_key` *        | uuid4 | Chave da conta debitada.                            |
| `paid_amount` *               | number | Valor pago efetivamente.                            |
| `payment_date` *              | string | Data do agendamento.                                |
| `payment_type` *              | [enum](#enumeradores-payment_type) | Tipo do pagamento.                                  |
| `bank_slip`                   | [object](#objeto-bank_slip) | Boleto bancário.                                    |
| `collection_slip`             | object | Fatura de recolhimento.                             |
| `payment_schedule_status` *            | [enum](#enumeradores-payment_schedule_status) | Status do agendamento.                              |

### Enumeradores payment_type
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

### Enumeradores payment_schedule_status
| Enumerador | Descrição             |
|------------|-----------------------|
| `canceled` | Agendamento cancelado |

### Objeto bank_slip
| Campo                             | Tipo    | Descrição                         |
|-----------------------------------|---------|-----------------------------------|
| `barcode` *                       | string | Código de barras. |
| `digitable_line` *                | string | Linha digitável. |
| `payer_name` *                    | string | Nome do pagador.|
| `payer_document_number` *         | string | Número do documento do pagador (CPF/CNPJ). |
| `beneficiary_name` *              | string | Nome do beneficiário. |
| `beneficiary_trading_name`        | string | Nome fantasia do beneficiário. |
| `beneficiary_document_number` *   | string | Número do documento do beneficiário (CPF/CNPJ). |
| `beneficiary_bank_ispb` *         | string | Código ispb do banco do beneficiário. |
| `guarantor_name`                  | string | Nome do sacador avalista. |
| `guarantor_document_number`       | string | Número do documento do sacador avalista (CPF/CNPJ). |
| `expiration_date` *               | string | Data de vencimento. |
| `max_payment_date` * | string  | Data máxima de pagamento. |
| `partial_payment_indicator` *     | [enum](#enumeradores-partial_payment_indicator)   | Indicador de pagamento parcial. |
| `registered_payment_amount`       | string | Valor total de pagamento registrado. |
| `nominal_amount` *                | number | Valor original. |
| `total_amount` *                  | number | Valor total. |
| `rebate_amount` *                 | number | Valor do abatimento. |
| `discount_amount` *               | number | Valor do desconto. |
| `fine_amount` *                   | number | Valor da multa. |
| `interest_amount` *               | number | Valor do juros. |

### Enumeradores partial_payment_indicator
| Enumerador    | Descrição     |
|---------------|---------------|
| `allowed`     | Permitido     |
| `not_allowed` | Não permitido |

### Objeto collection_slip
| Campo                             | Tipo    | Descrição                         |
|-----------------------------------|---------|-----------------------------------|
| `barcode`          | string | Código de barras. |
| `digitable_line`   | string | Linha digitável. |
| `collection_name` *         | string | Nome do convênio.|
| `collection_document_number`   | string | Número de documento do convênio (CPF/CNPJ).|
| `expiration_date` *  | string  | Data de vencimento. |
| `total_amount` *  | number | Valor total. |

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400         | BIP000001 | Bad Request | The barcode or digitable line must have 44 or 47 characters. | O código de barras ou linha digitável deve ter 44 ou 47 caracteres. |
| 400         | BIP000002 | Bad Request | The bill sent does not correspond to a bank slip. | A conta enviado não corresponde a um boleto bancário. |
| 400         | BIP000003 | Bad Request | The digitable line sent is invalid. | A linha digitável enviada é inválida. |
| 404         | BIP000004 | Not Found | The bank slip was not found. | O boleto não foi encontrado. |
| 400         | BIP000005 | Bad Request | It was not possible to consult the bank slip at this time. Please try again in a few minutes. | Não foi possível consultar o boleto neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000006 | Bad Request | Bank slip already written off | Boleto já baixado |
| 400         | BIP000007 | Bad Request | Bank slip blocked for payment | Boleto bloqueado para pagamento |
| 400         | BIP000008 | Bad Request | Bank slip already paid | Boleto já pago |
| 400         | BIP000009 | Bad Request | Invalid bank slip. Please consult issuing bank | Boleto inválido. Favor consultar banco emissor |

---

# Consultar Agendamento

URL: /documentation/baas/cobranca/agendamento/consultar_agendamento

Este endpoint é utilizado para consultar as informações de um agendamento de pagamento de um Boleto Bancário ou Fatura de Recolhimento.

:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::

:::info Fatura de Recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /payment_schedule/ PAYMENT_SCHEDULE_KEY
MÉTODO GET

### Request Path Params

| Campo                    | Tipo    | Descrição                                    | Caracteres |
|--------------------------|---------|----------------------------------------------|------------|
| `account_key` *          | uuid4   | Chave única de identificação da conta.       | 36         |
| `payment_schedule_key` * | uuid4   | Chave única de identificação do agendamento. | 36         |

## Response

### Success Response

STATUS 200

Response Body: Agendamento de pagamento de boleto bancário

```json
{
   "payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea",
   "request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189",
   "payer_name":"COOPERATIVA INDUSTRIAL MURILO",
   "payer_document_number":"00037025000160",
   "source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
   "paid_amount":1050.1,
   "payment_date":"2024-04-03",
   "payment_type":"bank_slip",
   "bank_slip": {
        "bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
        "barcode":"00193967000009910000000003615574000000002417",
        "digitable_line":"00190000090361557400500000024174396700000991000",
        "payer_name":"COOPERATIVA TESTE",
        "payer_document_number":"00037025000160",
        "beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
        "beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
        "beneficiary_document_number":"52069937000117",
        "beneficiary_bank_ispb":"00000000",
        "guarantor_name":null,
        "guarantor_document_number":null,
        "expiration_date":"2024-03-29",
        "max_payment_data": "2026-03-29",
        "partial_payment_indicator":"allowed",
        "registered_payment_amount":9029.0,
        "nominal_amount":9910.0,
        "total_amount":10129.1,
        "rebate_amount":0.0,
        "discount_amount":0.0,
        "fine_amount":0.0,
        "interest_amount":219.1
    },
   "collection_slip":null,
   "payment_schedule_status":"scheduled"
}
```

Response Body: Agendamento de pagamento de fatura de recolhimento

```json
{
  "payment_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
  "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
  "payer_name": "COOPERATIVA INDUSTRIAL MURILO",
  "payer_document_number": "62069937000118",
  "source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "paid_amount": 1389.21,
  "payment_date": "2024-04-30",
  "payment_type": "collection_slip",
  "bank_slip": null,
  "collection_slip": {
    "barcode": null,
    "digitable_line": "836200000138892100450006762142420244046000010192",
    "collection_name": "CIA ULTRAGAZ SA-COD",
    "collection_document_number": "00394460005887",
    "expiration_date": "2024-04-15",
    "total_amount": 1389.21
  },
  "payment_schedule_status": "scheduled"
}
```

### Response Body Params

| Campo               | Tipo    | Descrição                                           |
|---------------------|---------|-----------------------------------------------------|
| `payment_key` *               | uuid4 | Chave única de identificação do pagamento.          |
| `request_control_key` *       | uuid4 | Chave única de identificação da request do cliente. |
| `payer_name` *                | string | Nome do pagador efetivo.                            |
| `payer_document_number` *     | string | Número do documento do pagador efetivo  (CPF/CNPJ). |
| `source_account_key` *        | uuid4 | Chave da conta debitada.                            |
| `transaction_key` *           | uuid4 | Chave da transação do pagamento.                    |
| `transaction_revert_key`      | uuid4 | Chave da transação de reversão do pagamento.        |
| `paid_amount` *               | number | Valor pago efetivamente.                            |
| `payment_date` *              | string | Data do agendamento.                                |
| `payment_type` *              | [enum](#enumeradores-payment_type) | Tipo do pagamento.                                  |
| `bank_slip`                   | [object](#objeto-bank_slip) | Boleto bancário.                                    |
| `collection_slip`             | object | Fatura de recolhimento.                             |
| `payment_schedule_status` *            | [enum](#enumeradores-payment_schedule_status) | Status do agendamento.                              |

### Enumeradores payment_type
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

### Enumeradores payment_schedule_status
| Enumerador          | Descrição                                                        |
|---------------------|------------------------------------------------------------------|
| `pending_2fa_approval` | Agendamento pendente de autenticação de dois fatores (2FA)       |
| `scheduled`          | Pagamento agendado com sucesso                                   |
| `executed`          | O agendamento foi executado com sucesso e o pagamento referente ao agendamento gerado |
| `rejected`          | O agendamento foi rejeitado e nenhum pagamento foi gerado             |
| `canceled`         | Agendamento cancelado                                            |
| `error`             | Erro ao realizar o agendamento                                   |

### Objeto bank_slip
| Campo                             | Tipo    | Descrição                         |
|-----------------------------------|---------|-----------------------------------|
| `barcode` *                       | string | Código de barras. |
| `digitable_line` *                | string | Linha digitável. |
| `payer_name` *                    | string | Nome do pagador.|
| `payer_document_number` *         | string | Número do documento do pagador (CPF/CNPJ). |
| `beneficiary_name` *              | string | Nome do beneficiário. |
| `beneficiary_trading_name`        | string | Nome fantasia do beneficiário. |
| `beneficiary_document_number` *   | string | Número do documento do beneficiário (CPF/CNPJ). |
| `beneficiary_bank_ispb` *         | string | Código ispb do banco do beneficiário. |
| `guarantor_name`                  | string | Nome do sacador avalista. |
| `guarantor_document_number`       | string | Número do documento do sacador avalista (CPF/CNPJ). |
| `expiration_date` *               | string | Data de vencimento. |
| `max_payment_date` * | string  | Data máxima de pagamento. |
| `partial_payment_indicator` *     | [enum](#enumeradores-partial_payment_indicator)   | Indicador de pagamento parcial. |
| `registered_payment_amount`       | string | Valor total de pagamento registrado. |
| `nominal_amount` *                | number | Valor original. |
| `total_amount` *                  | number | Valor total. |
| `rebate_amount` *                 | number | Valor do abatimento. |
| `discount_amount` *               | number | Valor do desconto. |
| `fine_amount` *                   | number | Valor da multa. |
| `interest_amount` *               | number | Valor do juros. |

### Enumeradores partial_payment_indicator
| Enumerador    | Descrição     |
|---------------|---------------|
| `allowed`     | Permitido     |
| `not_allowed` | Não permitido |

### Objeto collection_slip
| Campo                             | Tipo    | Descrição                         |
|-----------------------------------|---------|-----------------------------------|
| `barcode`          | string | Código de barras. |
| `digitable_line`   | string | Linha digitável. |
| `collection_name` *         | string | Nome do convênio.|
| `collection_document_number`   | string | Número de documento do convênio (CPF/CNPJ).|
| `expiration_date` *  | string  | Data de vencimento. |
| `total_amount` *  | number | Valor total. |

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400         | BIP000001 | Bad Request | The barcode or digitable line must have 44 or 47 characters. | O código de barras ou linha digitável deve ter 44 ou 47 caracteres. |
| 400         | BIP000002 | Bad Request | The bill sent does not correspond to a bank slip. | A conta enviado não corresponde a um boleto bancário. |
| 400         | BIP000003 | Bad Request | The digitable line sent is invalid. | A linha digitável enviada é inválida. |
| 404         | BIP000004 | Not Found | The bank slip was not found. | O boleto não foi encontrado. |
| 400         | BIP000005 | Bad Request | It was not possible to consult the bank slip at this time. Please try again in a few minutes. | Não foi possível consultar o boleto neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000006 | Bad Request | Bank slip already written off | Boleto já baixado |
| 400         | BIP000007 | Bad Request | Bank slip blocked for payment | Boleto bloqueado para pagamento |
| 400         | BIP000008 | Bad Request | Bank slip already paid | Boleto já pago |
| 400         | BIP000009 | Bad Request | Invalid bank slip. Please consult issuing bank | Boleto inválido. Favor consultar banco emissor |

---

# Listar Agendamentos

URL: /documentation/baas/cobranca/agendamento/listar_agendamentos

Este endpoint tem a finalidade de fornecer detalhes de todos os agendamentos realizados pelo parceiro integrador,
incluindo boletos bancários e Faturas de recolhimento.

:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::

:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /payment_schedules
MÉTODO GET

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |

### Request Query String Params

| Campo                  | Tipo        | Descrição                                                                |
|------------------------|-------------|--------------------------------------------------------------------------|
| `request_control_key`  | uuid4     | Chave única de identificação da request do cliente.                      |
| `payment_schedule_key` | uuid4     | Chave única de identificação do agendamento.                             |
| `payment_key` | uuid4     | Chave única de identificação do pagamento gerado para o agendamento.                             |
| `payment_type`         | [enum](#enumeradores-payment_type)      | Tipo do pagamento.                                                       |
| `payment_schedule_status`         | [enum](#enumeradores-payment_schedule_status)      | Status do agendamento.                                                       |
| `date_from`            | string    | Data inicial. Formato "YYYY-MM-DD".                                      |
| `date_to`              | string    | Data final. Formato "YYYY-MM-DD".                                        |
| `page`                 | string    | Número da página requisitada. 1 por padrão.                              |
| `page_size`            | string    | Tamanho da página requisitada na consulta. 30 por padrão e valor máximo. |

### Enumeradores payment_type
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

### Enumeradores payment_schedule_status
| Enumerador          | Descrição                                                        |
|---------------------|------------------------------------------------------------------|
| `pending_2fa_approval` | Agendamento pendente de autenticação de dois fatores (2FA)       |
| `scheduled`          | Pagamento agendado com sucesso                                   |
| `executed`          | O agendamento foi executado com sucesso e o pagamento referente ao agendamento gerado |
| `rejected`          | O agendamento foi rejeitado e nenhum pagamento foi gerado             |
| `canceled`         | Agendamento cancelado                                            |
| `error`             | Erro ao realizar o agendamento

## Response

### Success Response

STATUS 200

Response Body: Consulta de pagamentos

```json
{
  "data": [
    {
       "payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea",
       "request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189",
       "payer_name":"COOPERATIVA INDUSTRIAL MURILO",
       "payer_document_number":"00037025000160",
       "source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
       "paid_amount":1050.1,
       "payment_date":"2024-04-03",
       "payment_type":"bank_slip",
       "bank_slip": {
            "bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
            "barcode":"00193967000009910000000003615574000000002417",
            "digitable_line":"00190000090361557400500000024174396700000991000",
            "payer_name":"COOPERATIVA TESTE",
            "payer_document_number":"00037025000160",
            "beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
            "beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
            "beneficiary_document_number":"52069937000117",
            "beneficiary_bank_ispb":"00000000",
            "guarantor_name":null,
            "guarantor_document_number":null,
            "expiration_date":"2024-03-29",
            "max_payment_data": "2026-03-29",
            "partial_payment_indicator":"allowed",
            "registered_payment_amount":9029.0,
            "nominal_amount":9910.0,
            "total_amount":10129.1,
            "rebate_amount":0.0,
            "discount_amount":0.0,
            "fine_amount":0.0,
            "interest_amount":219.1
        },
       "collection_slip":null,
       "payment_schedule_status":"scheduled"
    },
    {
      "payment_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
      "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
      "payer_name": "COOPERATIVA INDUSTRIAL MURILO",
      "payer_document_number": "62069937000118",
      "source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
      "paid_amount": 1389.21,
      "payment_date": "2024-04-30",
      "payment_type": "collection_slip",
      "bank_slip": null,
      "collection_slip": {
        "barcode": null,
        "digitable_line": "836200000138892100450006762142420244046000010192",
        "collection_name": "CIA ULTRAGAZ SA-COD",
        "collection_document_number": "00394460005887",
        "expiration_date": "2024-04-15",
        "total_amount": 1389.21
      },
      "payment_schedule_status": "scheduled"
    }
  ],
  "pagination": {
    "current_page": 1,
    "rows_per_page": 30
  }
}
```

### Response Body Params

| Campo               | Tipo    | Descrição                                           |
|---------------------|---------|-----------------------------------------------------|
| `payment_key` *               | uuid4 | Chave única de identificação do pagamento.          |
| `request_control_key` *       | uuid4 | Chave única de identificação da request do cliente. |
| `payer_name` *                | string | Nome do pagador efetivo.                            |
| `payer_document_number` *     | string | Número de documento do pagador efetivo (CPF/CNPJ).  |
| `source_account_key` *        | uuid4 | Chave da conta debitada.                            |
| `paid_amount` *               | number | Valor pago efetivamente.                            |
| `payment_date` *              | string | Data do pagamento.                                  |
| `payment_type` *              | [enum](#enumeradores-payment_type-1) | Tipo do pagamento.                                  |
| `bank_slip`                   | [object](#objeto-bank_slip) | Boleto bancário.                                    |
| `collection_slip`             | [object](#objeto-collection_slip) | Fatura de recolhimento.                             |
| `payment_schedule_status` *            | [enum](#enumeradores-payment_schedule_status) | Status do agendamento.                              |

### Enumeradores payment_type
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

### Enumeradores payment_schedule_status
| Enumerador          | Descrição                                                        |
|---------------------|------------------------------------------------------------------|
| `pending_2fa_approval` | Agendamento pendente de autenticação de dois fatores (2FA)       |
| `scheduled`          | Pagamento agendado com sucesso                                   |
| `executed`          | O agendamento foi executado com sucesso e o pagamento referente ao agendamento gerado |
| `rejected`          | O agendamento foi rejeitado e nenhum pagamento foi gerado             |
| `canceled`         | Agendamento cancelado                                            |
| `error`             | Erro ao realizar o agendamento                                   |

### Objeto bank_slip
| Campo                             | Tipo    | Descrição                         |
|-----------------------------------|---------|-----------------------------------|
| `barcode` *                       | string | Código de barras. |
| `digitable_line` *                | string | Linha digitável. |
| `payer_name` *                    | string | Nome do pagador.|
| `payer_document_number` *         | string | Número de documento do pagador (CPF/CNPJ). |
| `beneficiary_name` *              | string | Nome do beneficiário. |
| `beneficiary_trading_name`        | string | Nome fantasia do beneficiário. |
| `beneficiary_document_number` *   | string | Número de documento do beneficiário (CPF/CNPJ). |
| `beneficiary_bank_ispb` *         | string | Código ispb do banco do beneficiário. |
| `guarantor_name`                  | string | Nome do sacador avalista. |
| `guarantor_document_number`       | string | Número de documento do sacador avalista (CPF/CNPJ). |
| `expiration_date` *               | string | Data de vencimento. |
| `max_payment_date` * | string  | Data máxima de pagamento. |
| `partial_payment_indicator` *     | [enum](#enumeradores-partial_payment_indicator)   | Indicador de pagamento parcial. |
| `registered_payment_amount`       | string | Valor total de pagamento registrado. |
| `nominal_amount` *                | number | Valor original. |
| `total_amount` *                  | number | Valor total. |
| `rebate_amount` *                 | number | Valor do abatimento. |
| `discount_amount` *               | number | Valor do desconto. |
| `fine_amount` *                   | number | Valor da multa. |
| `interest_amount` *               | number | Valor do juros. |

### Enumeradores partial_payment_indicator
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `allowed`     | string    | Permitido     |
| `not_allowed` | string    | Não permitido |

### Objeto collection_slip
| Campo                             | Tipo    | Descrição                         |
|-----------------------------------|---------|-----------------------------------|
| `barcode` *                       | string | Código de barras. |
| `digitable_line` *                | string | Linha digitável. |
| `collection_name` *               | string | Nome do pagador.|
| `collection_document_number` *    | string | Número de documento do convênio (CPF/CNPJ). |
| `expiration_date` *               | string | Data de vencimento. |
| `total_amount` *                  | number | Valor total. |

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400         | BIP000026 | Bad Request | Invalid payment date format. The correct format is YYYY-MM-DD. | Formato de data de pagamento inválido. O formato correto é YYYY-MM-DD. |
| 400         | BIP000027 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
| 400         | BIP000047 | Bad Request | Invalid payment type. | Tipo de pagamento inválido. |

---

# Solicitar agendamento em lote de boleto bancário

URL: /documentation/baas/cobranca/agendamento/solicitar_agendamento_em_lote_de_boleto_bancario

Este endpoint permite solicitar o **agendamento em lote** de boletos bancários em uma única requisição.

:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::

## Request

### Request Endpoint

ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments_schedule/batch_bank_slip
MÉTODO POST

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |

Request Body: Agendamento em lote de boletos bancários

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "bank_slip_payment_schedules": [
    {
      "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
      "digitable_line": "00190000090361557400500000024174396700000991000",
      "payment_amount": 1156.8,
      "payment_date": "2026-04-10"
    },
    {
      "request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e",
      "barcode": "00190000090361557400500000024174396700000991000",
      "payment_amount": 200.5,
      "payment_date": "2026-04-15"
    }
  ]
}
```

### Body Params

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | Chave única de identificação da requisição do cliente (lote). |
| `bank_slip_payment_schedules` * | array     | Lista de agendamentos de boleto bancário. Limite de **1000** itens por requisição. |

Cada elemento de `bank_slip_payment_schedules` deve conter:

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | Chave única de identificação da requisição do cliente para aquele item do lote. |
| `barcode`               | string    | Código de barras. |
| `digitable_line`        | string    | Linha digitável. |
| `payment_amount` *      | number    | Valor a ser pago. |
| `payment_date` *        | string    | Data do agendamento do item. |

:::danger Aviso
Para cada item, o `payment_amount` deve seguir as regras do título retornadas na consulta do boleto bancário. Se o pagamento parcial não for permitido, o valor deve corresponder ao total atualizado do título.
:::

## Response

### Success Response

STATUS 202

Response Body: Lote de agendamento criado

```json
{
  "batch_payment_schedule_key": "c4325104-d60b-44f3-aae4-49155564a2ea",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
  "total_amount": 1357.3,
  "batch_payment_schedule_status": "scheduled",
  "payment_type": "bank_slip"
}
```

### Response Body Params

| Campo               | Tipo    | Descrição                         |
|---------------------|---------|-----------------------------------|
| `batch_payment_schedule_key` *       | uuid4 | Chave única de identificação do agendamento em lote. |
| `request_control_key` *     | uuid4 | Chave única de identificação da requisição do cliente (lote). |
| `account_key` *             | uuid4 | Chave da conta debitada. |
| `total_amount` *            | number | Soma dos valores (`payment_amount`) dos itens do lote. |
| `batch_payment_schedule_status` *         | [enum](#enumeradores-batch_payment_schedule_status) | Status do lote de agendamento após a solicitação. |
| `payment_type` *            | [enum](#enumeradores-payment_type) | Tipo do pagamento. |

### Enumeradores batch_payment_schedule_status

| Enumerador    | Descrição     |
|---------------|---------------|
| `pending_2fa_approval` | Pendente de aprovação 2FA |
| `scheduled`   | Agendado |
| `rejected`    | Rejeitado |
| `error`       | Erro ao agendar |

### Enumeradores payment_type

| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

:::danger Aviso
O enumerador `collection_slip` não se aplica ao fluxo de agendamento em lote de boletos bancários deste endpoint; para este caso, espera-se `payment_type` com valor `bank_slip`.
:::

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 403         | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404         | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400         | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |

---

# Solicitar agendamento em lote de fatura de recolhimento

URL: /documentation/baas/cobranca/agendamento/solicitar_agendamento_em_lote_de_fatura_de_recolhimento

Este endpoint permite solicitar o **agendamento em lote** de faturas de recolhimento (convênio/tributo) em uma única requisição.

:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::

## Request

### Request Endpoint

ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments_schedule/batch_collection_slip
MÉTODO POST

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |

Request Body: Agendamento em lote de faturas de recolhimento

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "collection_slip_payment_schedules": [
    {
      "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
      "digitable_line": "836200000138892100450006762142420244046000010192",
      "payment_amount": 1389.21,
      "payment_date": "2026-04-10"
    },
    {
      "request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e",
      "barcode": "836200000138892100450006762142420244046000010192",
      "payment_amount": 550.10,
      "payment_date": "2026-04-15"
    }
  ]
}
```

### Body Params

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | Chave única de identificação da requisição do cliente (lote). |
| `collection_slip_payment_schedules` * | array     | Lista de agendamentos de fatura de recolhimento. Limite de **1000** itens por requisição. |

Cada elemento de `collection_slip_payment_schedules` deve conter:

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | Chave única de identificação da requisição do cliente para aquele item do lote. |
| `barcode`               | string    | Código de barras. |
| `digitable_line`        | string    | Linha digitável. |
| `payment_amount` *      | number    | Valor a ser pago. |
| `payment_date` *        | string    | Data do agendamento do item. |

## Response

### Success Response

STATUS 202

Response Body: Lote de agendamento criado

```json
{
  "batch_payment_schedule_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
  "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
  "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "total_amount": 1939.31,
  "batch_payment_schedule_status": "scheduled",
  "payment_type": "collection_slip"
}
```

### Response Body Params

| Campo               | Tipo    | Descrição                         |
|---------------------|---------|-----------------------------------|
| `batch_payment_schedule_key` *       | uuid4 | Chave única de identificação do agendamento em lote. |
| `request_control_key` *     | uuid4 | Chave única de identificação da requisição do cliente (lote). |
| `account_key` *             | uuid4 | Chave da conta debitada. |
| `total_amount` *            | number | Soma dos valores (`payment_amount`) dos itens do lote. |
| `batch_payment_schedule_status` *         | [enum](#enumeradores-batch_payment_schedule_status) | Status do lote de agendamento após a solicitação. |
| `payment_type` *            | [enum](#enumeradores-payment_type) | Tipo do pagamento. |

### Enumeradores batch_payment_schedule_status

| Enumerador    | Descrição     |
|---------------|---------------|
| `pending_2fa_approval` | Pendente de aprovação 2FA |
| `scheduled`   | Agendado |
| `rejected`    | Rejeitado |
| `error`       | Erro ao agendar |

### Enumeradores payment_type

| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

:::danger Aviso
O enumerador `bank_slip` não se aplica ao fluxo de agendamento em lote de faturas de recolhimento deste endpoint; para este caso, espera-se `payment_type` com valor `collection_slip`.
:::

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400         | BIP000032 | Bad Request | The bill sent does not correspond to a collection slip. | A conta enviada não corresponde a uma fatura de recolhimento. |
| 400         | BIP000033 | Bad Request | The barcode or digitable line of the collection slip must have 44 or 48 characters. | O código de barras ou linha digitável da fatura de recolhimento deve ter 44 ou 48 caracteres. |
| 403         | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404         | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400         | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 400         | BIP000065 | Bad Request | Payment verification time window exceeded. | Janela de tempo de verificação de pagamento excedida. |

---

# Confirmação de lote de pagamento de boleto bancário

URL: /documentation/baas/cobranca/confirmacao_de_lote_de_boleto_bancario

Este endpoint permite **confirmar ou rejeitar** um lote de pagamento de boletos bancários previamente criado com [Solicitar pagamento em lote de boleto bancário](./solicitar_pagamento_lote_de_boleto_bancario_com_confirmacao_de_lote.md). A confirmação é a etapa que define se o processamento do lote segue (aprovação) ou é encerrado sem débito dos títulos (rejeição).

:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::

## Request

### Request Endpoint

ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_bank_slip/**PAYMENT_BATCH_KEY**/confirmation
MÉTODO PATCH

### Request Path Params

| Campo                 | Tipo  | Descrição                                                                                | Caracteres |
| --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- |
| `account_key` *       | uuid4 | Chave única de identificação da conta.                                                   | 36         |
| `payment_batch_key` * | uuid4 | Chave única de identificação do lote (`batch_payment_key` retornado na criação do lote). | 36         |

### Request Body

**Request Body: Rejeição do lote**

```json
{
  "batch_status": "rejected"
}
```

**Request Body: Aprovação do lote**

```json
{
  "batch_status": "approved"
}
```

### Body Params

| Campo            | Tipo   | Descrição                                                                                                                                                     |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batch_status` * | string | Decisão sobre o lote. Valores: `approved` (seguir com o processamento) ou `rejected` (cancelar o lote). Ver [enumerador batch_confirmation_status](#enumerador-batch_confirmation_status). |

### Enumerador batch_confirmation_status

Valores aceitos no corpo da requisição para `batch_status`:

| Valor      | Descrição                                                     |
| ---------- | ------------------------------------------------------------- |
| `approved` | Aprovar o lote e continuar o fluxo de processamento.          |
| `rejected` | Rejeitar o lote; não há processamento assíncrono dos boletos. |

## Response

### Resposta: lote rejeitado

STATUS 200

Quando `batch_status` no corpo da requisição é `rejected`, a API responde com **200**. O lote fica encerrado como rejeitado; não há fila assíncrona de pagamento dos boletos.

**Response Body: Lote rejeitado**

```json
{
  "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
  "total_amount": 1357.3,
  "batch_status": "rejected",
  "payment_type": "bank_slip"
}
```

### Resposta: lote aprovado — processamento assíncrono

STATUS 202

Quando `batch_status` no corpo é `approved`, a API responde com **202** e o lote segue para **processamento assíncrono** dos boletos. O corpo retorna `batch_status` como `approved`.

**Response Body: Lote aprovado para processamento assíncrono**

```json
{
  "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
  "total_amount": 1357.3,
  "batch_status": "approved",
  "payment_type": "bank_slip"
}
```

### Response Body Params

| Campo                   | Tipo   | Descrição                                                                                                                                                                                                                                                                     |
| ----------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batch_payment_key` *   | uuid4  | Chave única de identificação do pagamento em lote.                                                                                                                                                                                                                            |
| `request_control_key` * | uuid4  | Chave única de identificação da requisição do cliente (lote).                                                                                                                                                                                                                 |
| `account_key` *         | uuid4  | Chave da conta debitada.                                                                                                                                                                                                                                                      |
| `total_amount` *        | number | Soma dos valores dos itens do lote.                                                                                                                                                                                                                                           |
| `batch_status` *        | string | Status do lote após esta chamada (`rejected` ou `approved` para o fluxo descrito nesta página). Alinhado ao ciclo de vida em [Solicitar pagamento em lote de boleto bancário — batch_payment_status](./solicitar_pagamento_lote_de_boleto_bancario_com_confirmacao_de_lote.md#enumeradores-batch_payment_status). |
| `payment_type` *        | string | Tipo do pagamento; para este fluxo, espera-se `bank_slip`.                                                                                                                                                                                                                    |

### Error Response

STATUS 4XX

**Response Body**

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título      | Descrição (eng)                               | Descrição (pt-br)                                     |
| ----------- | --------- | ----------- | --------------------------------------------- | ----------------------------------------------------- |
| 400         | BIP000013 | Bad Request | The source account is closed.                 | A conta de origem está fechada.                       |
| 400         | BIP000050 | Bad Request | Requester configuration does not exist        | Configuração do requester não existe.                 |
| 404         | BIP000083 | Not Found   | Batch payment not found by batch payment key. | Lote de pagamentos não encontrado pela chave do lote. |
| 400         | BIP000084 | Bad Request | Batch payment status is not pending.          | O status do lote de pagamentos não está pendente.     |

---

# Confirmação de lote de pagamento de fatura de recolhimento (convênio/tributo)

URL: /documentation/baas/cobranca/confirmacao_de_lote_de_fatura_de_recolhimento

Este endpoint permite **confirmar ou rejeitar** um lote de pagamento de faturas de recolhimento previamente criado com [Solicitar pagamento em lote de fatura de recolhimento (convênio/tributo)](./solicitar_pagamento_lote_de_fatura_de_recolhimento_com_confirmacao_de_lote.md). A confirmação é a etapa que define se o processamento do lote segue (aprovação) ou é encerrado sem débito dos títulos (rejeição).

:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um boleto bancário apresenta.
:::

## Request

### Request Endpoint

ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/payment/batch_collection_slip/**PAYMENT_BATCH_KEY**/confirmation
MÉTODO PATCH

### Request Path Params

| Campo                 | Tipo  | Descrição                                                                                | Caracteres |
| --------------------- | ----- | ---------------------------------------------------------------------------------------- | ---------- |
| `account_key` *       | uuid4 | Chave única de identificação da conta.                                                   | 36         |
| `payment_batch_key` * | uuid4 | Chave única de identificação do lote (`batch_payment_key` retornado na criação do lote). | 36         |

### Request Body

**Request Body: Rejeição do lote**

```json
{
  "batch_status": "rejected"
}
```

**Request Body: Aprovação do lote**

```json
{
  "batch_status": "approved"
}
```

### Body Params

| Campo            | Tipo   | Descrição                                                                                                                                                     |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batch_status` * | string | Decisão sobre o lote. Valores: `approved` (seguir com o processamento) ou `rejected` (cancelar o lote). Ver [enumerador batch_confirmation_status](#enumerador-batch_confirmation_status). |

### Enumerador batch_confirmation_status

Valores aceitos no corpo da requisição para `batch_status`:

| Valor      | Descrição                                                                     |
| ---------- | ----------------------------------------------------------------------------- |
| `approved` | Aprovar o lote e continuar o fluxo de processamento.                          |
| `rejected` | Rejeitar o lote; não há processamento assíncrono das faturas de recolhimento. |

## Response

### Resposta: lote rejeitado

STATUS 200

Quando `batch_status` no corpo da requisição é `rejected`, a API responde com **200**. O lote fica encerrado como rejeitado; não há fila assíncrona de pagamento das faturas de recolhimento.

**Response Body: Lote rejeitado**

```json
{
  "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "total_amount": 2778.42,
  "batch_status": "rejected",
  "payment_type": "collection_slip"
}
```

### Resposta: lote aprovado — processamento assíncrono

STATUS 202

Quando `batch_status` no corpo é `approved`, a API responde com **202** e o lote segue para **processamento assíncrono** das faturas de recolhimento. O corpo retorna `batch_status` como `approved`.

**Response Body: Lote aprovado para processamento assíncrono**

```json
{
  "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "total_amount": 2778.42,
  "batch_status": "approved",
  "payment_type": "collection_slip"
}
```

### Response Body Params

| Campo                   | Tipo   | Descrição                                                                                                                                                                                                                                                                                    |
| ----------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `batch_payment_key` *   | uuid4  | Chave única de identificação do pagamento em lote.                                                                                                                                                                                                                                           |
| `request_control_key` * | uuid4  | Chave única de identificação da requisição do cliente (lote).                                                                                                                                                                                                                                |
| `account_key` *         | uuid4  | Chave da conta debitada.                                                                                                                                                                                                                                                                     |
| `total_amount` *        | number | Soma dos valores dos itens do lote.                                                                                                                                                                                                                                                          |
| `batch_status` *        | string | Status do lote após esta chamada (`rejected` ou `approved` para o fluxo descrito nesta página). Alinhado ao ciclo de vida em [Solicitar pagamento em lote de fatura de recolhimento — batch_payment_status](./solicitar_pagamento_lote_de_fatura_de_recolhimento_com_confirmacao_de_lote.md#enumeradores-batch_payment_status). |
| `payment_type` *        | string | Tipo do pagamento; para este fluxo, espera-se `collection_slip`.                                                                                                                                                                                                                             |

### Error Response

STATUS 4XX

**Response Body**

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título      | Descrição (eng)                               | Descrição (pt-br)                                     |
| ----------- | --------- | ----------- | --------------------------------------------- | ----------------------------------------------------- |
| 400         | BIP000013 | Bad Request | The source account is closed.                 | A conta de origem está fechada.                       |
| 400         | BIP000050 | Bad Request | Requester configuration does not exist        | Configuração do requester não existe.                 |
| 404         | BIP000083 | Not Found   | Batch payment not found by batch payment key. | Lote de pagamentos não encontrado pela chave do lote. |
| 400         | BIP000084 | Bad Request | Batch payment status is not pending.          | O status do lote de pagamentos não está pendente.     |

---

# Consulta de Boleto Bancário

URL: /documentation/baas/cobranca/consultar_boleto_bancario

Este endpoint é utilizado para consultar as informações de um boleto bancário.

:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::

## Request

### Request Endpoint

ENDPOINT /bill_payment/bank_slip/ DIGITABLE_LINE or BARCODE
MÉTODO GET

### Request Path Params

| Campo               | Tipo    | Descrição                         | Caracteres |
|---------------------|---------|-----------------------------------|------------|
| `digitable_line`  | string  | Linha digitável a ser consultada. | 47         |
| `barcode`         | string  | Código de barras a ser consultado.| 44         |

### Request Query String Params

| Campo               | Tipo        | Descrição                         | Caracteres |
|---------------------|-------------|-----------------------------------|------------|
| `payment_date`      | string      | Data do pagamento e que será levada em consideração nos cálculos dos valores do boleto. | YYYY-MM-DD |

## Response

### Success Response

STATUS 200

Response Body: Boleto bancário disponível para pagamento

```json
{
   "barcode":"00193967000009910000000003615574000000002417",
   "digitable_line":"00190000090361557400500000024174396700000991000",
   "payer_name":"COOPERATIVA AGRO.INDUSTRIAL TEST",
   "payer_document_number":"21063663000125",
   "beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA.",
   "beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
   "beneficiary_document_number":"30639204000138",
   "beneficiary_bank_ispb":"00000000",
   "guarantor_name":null,
   "guarantor_document_number":null,
   "expiration_date":"2024-03-29",
   "max_payment_data": "2026-03-29",
   "partial_payment_indicator":"not_allowed",
   "registered_payment_amount":null,
   "nominal_amount":9910.0,
   "total_amount":10129.1,
   "rebate_amount":0.0,
   "discount_amount":0.0,
   "fine_amount":0.0,
   "interest_amount":219.1
}
```

### Response Body Params

| Campo               | Tipo    | Descrição                         |
|---------------------|---------|-----------------------------------|
| `barcode` *         | string | Código de barras. |
| `digitable_line` *  | string | Linha digitável. |
| `payer_name` *         | string | Nome do pagador.|
| `payer_document_number` *  | string | Número de documento do pagador (CPF/CNPJ). |
| `beneficiary_name` *         | string | Nome do beneficiário. |
| `beneficiary_trading_name`  | string | Nome fantasia do beneficiário. |
| `beneficiary_document_number` *         | string | Número de documento do beneficiário (CPF/CNPJ). |
| `beneficiary_bank_ispb` *         | string | Código ispb do banco do beneficiário. |
| `guarantor_name`   | string | Nome do sacador avalista. |
| `guarantor_document_number`        | string | Número de documento do sacador avalista (CPF/CNPJ). |
| `expiration_date` *  | string  | Data de vencimento. |
| `max_payment_date` * | string  | Data máxima de pagamento. |
| `partial_payment_indicator` *  | [enum](#enumeradores-partial_payment_indicator) | Indicador de pagamento parcial |
| `registered_payment_amount`   | string | Valor total de pagamento registrado. |
| `nominal_amount` *  | number | Valor original. |
| `total_amount` *  | number | Valor total. |
| `rebate_amount` *  | number | Valor do abatimento. |
| `discount_amount` *  | number | Valor do desconto. |
| `fine_amount` *  | number | Valor da multa. |
| `interest_amount` *  | number | Valor do juros. |

### Enumeradores partial_payment_indicator
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `allowed`     | string    | Permitido     |
| `not_allowed` | string    | Não permitido |

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400         | BIP000001 | Bad Request | The barcode or digitable line must have 44 or 47 characters. | O código de barras ou linha digitável deve ter 44 ou 47 caracteres. |
| 400         | BIP000002 | Bad Request | The bill sent does not correspond to a bank slip. | A conta enviado não corresponde a um boleto bancário. |
| 400         | BIP000003 | Bad Request | The digitable line sent is invalid. | A linha digitável enviada é inválida. |
| 404         | BIP000004 | Not Found | The bank slip was not found. | O boleto não foi encontrado. |
| 400         | BIP000005 | Bad Request | It was not possible to consult the bank slip at this time. Please try again in a few minutes. | Não foi possível consultar o boleto neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000006 | Bad Request | Bank slip already written off | Boleto já baixado |
| 400         | BIP000007 | Bad Request | Bank slip blocked for payment | Boleto bloqueado para pagamento |
| 400         | BIP000008 | Bad Request | Bank slip already paid | Boleto já pago |
| 400         | BIP000009 | Bad Request | Invalid bank slip. Please consult issuing bank | Boleto inválido. Favor consultar banco emissor |

## Ambiente de Sandbox

Em nosso ambiente de sandbox, disponibilizamos linhas digitáveis mockadas para a simulação de pagamentos bem-sucedidos e testes de cenários de erro.

### Cenários de sucesso

| Linha digitável |
|---|
| 00190000090361557400500000024174396700000991000 |
| 00190000090282802601919212747174596760001294161 |
| 23793390014000000455277000249001596900000103995 |
| 75691434020137513680900001040013196770002417240 |
| 21390001171200000570700168167484796770000148206 |
| 07790001161200000039300602819070498470000182970 |
| 23792372059034189564835003432701998420000008306 |
| 03399199530490000005254172701010698420000467696 |
| 03399135012340000000830681701014198420038743888 |
| 75691324620100735471370255730478698420064900819 |
| 75691413310108906500520369970015899610000033705 |
| 13695621010000389701400000037598810770000217000 |

### Cenários de erro

| Linha digitável | Código de erro |
|---|---|
| 34191090083273252027893634770007296690012513600 | BIP000007 |
| 07090010287045349010776686070590896770001160123 | BIP000007 |
| 42297048060005815702500130494123896770000239491 | BIP000006 |
| 74891123702849020818918378871083196690000050000 | BIP000009 |
| 23792374119000209350986000372408496610000122810 | BIP000008 |

---

# Consulta de Fatura de Recolhimento

URL: /documentation/baas/cobranca/consultar_fatura_de_recolhimento

Este endpoint é utilizado para consultar as informações de uma fatura de recolhimento.

:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta. Você pode conferir a lista de convênios aceitos pela QI Tech, bem como seus respectivos horários limite de pagamento, através deste [link](https://storage.googleapis.com/live-doc-api/public_samples/active_covenants.xlsx).
:::

## Request

### Request Endpoint

ENDPOINT /bill_payment/collection_slip/ DIGITABLE_LINE or BARCODE
MÉTODO GET

### Request Path Params

| Campo               | Tipo    | Descrição                         | Caracteres |
|---------------------|---------|-----------------------------------|------------|
| `digitable_line`  | string  | Linha digitável a ser consultada. | 48         |
| `barcode`         | string  | Código de barras a ser consultado.| 44         |

## Response

### Success Response

STATUS 200

Response Body: Fatura de recolhimento disponível para pagamento

```json
{
  "barcode": null,
  "digitable_line": "836200000138892100450006762142420244046000010192",
  "collection_name": "CIA ULTRAGAZ SA-COD",
  "expiration_date": "2024-04-15",
  "total_amount": 1389.21
}
```

### Response Body Params

| Campo               | Tipo    | Descrição                         |
|---------------------|---------|-----------------------------------|
| `barcode`          | string | Código de barras. |
| `digitable_line`   | string | Linha digitável. |
| `collection_name` *         | string | Nome do convênio.|
| `expiration_date` *  | string  | Data de vencimento. |
| `total_amount` *  | number | Valor total. |

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400         | BIP000032 | Bad Request | The bill sent does not correspond to a collection slip. | A conta enviada não corresponde a uma fatura de recolhimento. |
| 400         | BIP000033 | Bad Request | The barcode or digitable line of the collection slip must have 44 or 48 characters. | O código de barras ou linha digitável da fatura de recolhimento deve ter 44 ou 48 caracteres. |
| 400         | BIP000034 | Bad Request | Collection slip already paid. | Fatura de recolhimento já paga. |
| 400         | BIP000035 | Bad Request | Covenant slip invalid barcode. | Código de barras da fatura de recolhimento inválido. |
| 400         | BIP000036 | Bad Request | Covenant slip overdue. | Fatura de recolhimento vencida. |
| 400         | BIP000037 | Bad Request | Error in collection slip consultation. | Erro na consulta da fatura de recolhimento. |
| 400         | BIP000038 | Bad Request | Outside of covenant payment hours. | Fora do horário de pagamento do convênio. |
| 400         | BIP000039 | Bad Request | Collection slip not accepted. | Fatura de recolhimento não aceita. |
| 400         | BIP000040 | Bad Request | Minimum advance not reached. | Mínimo de dias de adiantamento não atingido. |
| 400         | BIP000041 | Bad Request | Max payment amount exceeded. | Valor máximo de pagamento excedido. |

## Ambiente de Sandbox

Em nosso ambiente de sandbox, disponibilizamos linhas digitáveis mockadas para a simulação de pagamentos bem-sucedidos e testes de cenários de erro.

### Cenários de sucesso

| Linha digitável |
|---|
| 828300000007411100972013905080001546763201900028 |
| 838000000009235700481007241345219112001474229880 |
| 848000000006308600802021201071261517689002201070 |
| 858200000015000000643025703477209504800448091020 |

### Cenários de erro

| Linha digitável | Código de erro |
|---|---|
| 858500000037350000643217212883260006147448091022 | BIP000035 |

---

# Consultar lote de pagamento

URL: /documentation/baas/cobranca/consultar_lote_de_pagamento

Este endpoint retorna o resumo do lote e a lista paginada dos pagamentos que o compõem (boletos bancários ou faturas de recolhimento).

Para localizar `batch_payment_key`, utilize [Listar lotes de pagamento](./listar_lotes_de_pagamento.md).

:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::

:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::

## Request

### Request Endpoint

ENDPOINT /bill_payment/account/**ACCOUNT_KEY**/batch/**BATCH_PAYMENT_KEY**
MÉTODO GET

### Request Path Params

| Campo                 | Tipo  | Descrição                                          | Caracteres |
| --------------------- | ----- | -------------------------------------------------- | ---------- |
| `account_key` *       | uuid4 | Chave única de identificação da conta.             | 36         |
| `batch_payment_key` * | uuid4 | Chave única de identificação do pagamento em lote. | 36         |

### Request Query String Params

| Campo       | Tipo   | Descrição                                                                     |
| ----------- | ------ | ----------------------------------------------------------------------------- |
| `page`      | string | Número da página dos itens em `payments.data`. 1 por padrão.                  |
| `page_size` | string | Tamanho da página dos itens em `payments.data`. 30 por padrão e valor máximo. |

## Response

### Success Response

STATUS

 200

**Response Body: Detalhes do lote de pagamento**

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "total_paid": 10,
  "total_pending": 0,
  "total_error": 0,
  "total_amount": 1357.3,
  "payments": {
    "pagination": {
      "current_page": 1,
      "rows_per_page": 30
    },
    "data": [
      {
        "payment_key": "c4325104-d60b-44f3-aae4-49155564a2ea",
        "payer_name": "COOPERATIVA INDUSTRIAL MURILO",
        "payer_document_number": "00037025000160",
        "source_account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
        "transaction_key": "4e80070a-a0bb-4be2-8178-55fbd73a3704",
        "transaction_revert_key": null,
        "paid_amount": 1050.1,
        "payment_date": "2024-04-03",
        "payment_type": "bank_slip",
        "bank_slip": {
          "bank_slip_key": "95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
          "barcode": "00193967000009910000000003615574000000002417",
          "digitable_line": "00190000090361557400500000024174396700000991000",
          "payer_name": "COOPERATIVA TESTE",
          "payer_document_number": "00037025000160",
          "beneficiary_name": "TESTE EQUIPAMENTOS E SERVICOS LTDA",
          "beneficiary_trading_name": "TESTE EQUIPAMENTOS E SERVICOS LTDA",
          "beneficiary_document_number": "52069937000117",
          "beneficiary_bank_ispb": "00000000",
          "guarantor_name": null,
          "guarantor_document_number": null,
          "expiration_date": "2024-03-29",
          "max_payment_date": "2026-03-29",
          "partial_payment_indicator": "allowed",
          "registered_payment_amount": 9029.0,
          "nominal_amount": 9910.0,
          "total_amount": 10129.1,
          "rebate_amount": 0.0,
          "discount_amount": 0.0,
          "fine_amount": 0.0,
          "interest_amount": 219.1
        },
        "collection_slip": null,
        "payment_status": "executed",
        "error_reason": null
      }
    ]
  }
}
```

### Response Body Params

| Campo                   | Tipo                       | Descrição                                                     |
| ----------------------- | -------------------------- | ------------------------------------------------------------- |
| `request_control_key` * | uuid4                      | Chave única de identificação da requisição do cliente (lote). |
| `total_paid` *          | int                        | Quantidade de itens do lote pagos com sucesso.                |
| `total_pending` *       | int                        | Quantidade de itens ainda pendentes no lote.                  |
| `total_error` *         | int                        | Quantidade de itens com erro no lote.                         |
| `total_amount` *        | number                     | Valor total do lote.                                          |
| `payments` *            | [object](#objeto-payments) | Lista paginada dos pagamentos do lote.                        |

### Objeto payments

| Campo          | Tipo                         | Descrição                                                                                                                                     |
| -------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `pagination` * | [object](#objeto-pagination) | Paginação da lista de pagamentos do lote.                                                                                                     |
| `data` *       | array                        | Itens do lote (estrutura equivalente a cada elemento de `data` em [Listar pagamentos](./listar_pagamentos.md), com campos adicionais abaixo). |

Cada elemento de `payments.data` contém:

| Campo                     | Tipo                                 | Descrição                                                                      |
| ------------------------- | ------------------------------------ | ------------------------------------------------------------------------------ |
| `payment_key` *           | uuid4                                | Chave única de identificação do pagamento.                                     |
| `payer_name` *            | string                               | Nome do pagador efetivo.                                                       |
| `payer_document_number` * | string                               | Número de documento do pagador efetivo (CPF/CNPJ).                             |
| `source_account_key` *    | uuid4                                | Chave da conta debitada.                                                       |
| `transaction_key` *       | uuid4                                | Chave da transação do pagamento.                                               |
| `transaction_revert_key`  | uuid4                                | Chave da transação de reversão do pagamento.                                   |
| `paid_amount` *           | number                               | Valor pago efetivamente.                                                       |
| `payment_date` *          | string                               | Data do pagamento.                                                             |
| `payment_type` *          | [enum](#enumeradores-payment_type)   | Tipo do pagamento.                                                             |
| `bank_slip`               | [object](#objeto-bank_slip)          | Boleto bancário. Pode ser `null` quando `payment_type` for `collection_slip`.  |
| `collection_slip`         | [object](#objeto-collection_slip)    | Fatura de recolhimento. Pode ser `null` quando `payment_type` for `bank_slip`. |
| `payment_status` *        | [enum](#enumeradores-payment_status) | Status do pagamento.                                                           |
| `error_reason`            | string                               | Motivo do erro, quando aplicável; caso contrário `null`.                       |

### Objeto pagination

| Campo             | Tipo | Descrição                           |
| ----------------- | ---- | ----------------------------------- |
| `current_page` *  | int  | Página atual retornada.             |
| `rows_per_page` * | int  | Quantidade de registros por página. |

### Enumeradores payment_type

| Enumerador        | Descrição              |
| ----------------- | ---------------------- |
| `bank_slip`       | Boleto bancário        |
| `collection_slip` | Fatura de recolhimento |

### Enumeradores payment_status

| Enumerador          | Descrição            |
| ------------------- | -------------------- |
| `pending_execution` | Pendente de execução |
| `executed`          | Executado            |
| `reverted`          | Revertido            |
| `rejected`          | Rejeitado            |
| `error`             | Erro                 |

### Objeto bank_slip

| Campo                           | Tipo                                            | Descrição                                           |
| ------------------------------- | ----------------------------------------------- | --------------------------------------------------- |
| `bank_slip_key` *               | uuid4                                           | Chave única de identificação do boleto bancário.    |
| `barcode` *                     | string                                          | Código de barras.                                   |
| `digitable_line` *              | string                                          | Linha digitável.                                    |
| `payer_name` *                  | string                                          | Nome do pagador.                                    |
| `payer_document_number` *       | string                                          | Número de documento do pagador (CPF/CNPJ).          |
| `beneficiary_name` *            | string                                          | Nome do beneficiário.                               |
| `beneficiary_trading_name`      | string                                          | Nome fantasia do beneficiário.                      |
| `beneficiary_document_number` * | string                                          | Número de documento do beneficiário (CPF/CNPJ).     |
| `beneficiary_bank_ispb` *       | string                                          | Código ispb do banco do beneficiário.               |
| `guarantor_name`                | string                                          | Nome do sacador avalista.                           |
| `guarantor_document_number`     | string                                          | Número de documento do sacador avalista (CPF/CNPJ). |
| `expiration_date` *             | string                                          | Data de vencimento.                                 |
| `max_payment_date` *            | string                                          | Data máxima de pagamento.                           |
| `partial_payment_indicator` *   | [enum](#enumeradores-partial_payment_indicator) | Indicador de pagamento parcial.                     |
| `registered_payment_amount`     | number                                          | Valor total de pagamento registrado.                |
| `nominal_amount` *              | number                                          | Valor original.                                     |
| `total_amount` *                | number                                          | Valor total.                                        |
| `rebate_amount` *               | number                                          | Valor do abatimento.                                |
| `discount_amount` *             | number                                          | Valor do desconto.                                  |
| `fine_amount` *                 | number                                          | Valor da multa.                                     |
| `interest_amount` *             | number                                          | Valor dos juros.                                    |

### Enumeradores partial_payment_indicator

| Enumerador    | Descrição     |
| ------------- | ------------- |
| `allowed`     | Permitido     |
| `not_allowed` | Não permitido |

### Objeto collection_slip

| Campo                          | Tipo   | Descrição                                   |
| ------------------------------ | ------ | ------------------------------------------- |
| `barcode` *                    | string | Código de barras.                           |
| `digitable_line` *             | string | Linha digitável.                            |
| `collection_name` *            | string | Nome do pagador.                            |
| `collection_document_number` * | string | Número de documento do convênio (CPF/CNPJ). |
| `expiration_date` *            | string | Data de vencimento.                         |
| `total_amount` *               | number | Valor total.                                |

### Error Response

STATUS

 4XX

**Response Body**

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título      | Descrição (eng)                                                 | Descrição (pt-br)                                              |
| ----------- | --------- | ----------- | --------------------------------------------------------------- | -------------------------------------------------------------- |
| 400         | BIP000027 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |

---

# Listar lotes de pagamento

URL: /documentation/baas/cobranca/listar_lotes_de_pagamento

Este endpoint retorna os lotes de pagamento de boletos bancários e faturas de recolhimento associados à conta, com suporte a filtros e paginação.

:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::

:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::

## Request

### Request Endpoint

ENDPOINT /bill_payment/account/ ACCOUNT_KEY /batches
MÉTODO GET

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |

### Request Query String Params

| Campo               | Tipo        | Descrição                         |
|---------------------|-------------|-----------------------------------|
| `request_control_key` | uuid4     | Chave única de identificação da requisição do cliente (lote). |
| `batch_payment_key`   | uuid4     | Chave única de identificação do pagamento em lote. |
| `payment_type`        | [enum](#enumeradores-payment_type)      | Tipo do pagamento do lote. |
| `batch_payment_status` | [enum](#enumeradores-batch_payment_status) | Status do lote. |
| `date_from`           | string    | Data inicial. Formato "YYYY-MM-DD". |
| `date_to`             | string    | Data final. Formato "YYYY-MM-DD". |
| `page`                | string    | Número da página requisitada. 1 por padrão. |
| `page_size`           | string    | Tamanho da página requisitada na consulta. 30 por padrão e valor máximo. |

### Enumeradores payment_type

| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

### Enumeradores batch_payment_status

| Enumerador    | Descrição     |
|---------------|---------------|
| `pending`     | Pendente de processamento |
| `pending_2fa_approval` | Pendente de aprovação 2FA |
| `rejected`    | Rejeitado |
| `approved`    | Aprovado |
| `processed`   | Processado |

## Response

### Success Response

STATUS 200

Response Body: Listagem de lotes de pagamento

```json
{
  "pagination": {
    "current_page": 1,
    "rows_per_page": 30
  },
  "data": [
    {
      "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "batch_status": "processed",
      "payment_type": "bank_slip",
      "total_paid": 10,
      "total_pending": 0,
      "total_error": 0,
      "total_amount": 1357.3
    }
  ]
}
```

### Response Body Params

| Campo               | Tipo    | Descrição                         |
|---------------------|---------|-----------------------------------|
| `pagination` *      | [object](#objeto-pagination) | Informações de paginação da consulta. |
| `data` *            | array   | Lista de lotes encontrados. |

Cada elemento de `data` contém:

| Campo               | Tipo    | Descrição                         |
|---------------------|---------|-----------------------------------|
| `batch_payment_key` * | uuid4 | Chave única de identificação do pagamento em lote. |
| `request_control_key` * | uuid4 | Chave única de identificação da requisição do cliente (lote). |
| `batch_status` *    | [enum](#enumeradores-batch_payment_status-1) | Status atual do lote. |
| `payment_type` *    | [enum](#enumeradores-payment_type-1) | Tipo do pagamento do lote. |
| `total_paid` *      | int     | Quantidade de itens do lote pagos com sucesso. |
| `total_pending` *   | int     | Quantidade de itens ainda pendentes no lote. |
| `total_error` *     | int     | Quantidade de itens com erro no lote. |
| `total_amount` *    | number  | Valor total do lote. |

### Objeto pagination

| Campo               | Tipo    | Descrição                         |
|---------------------|---------|-----------------------------------|
| `current_page` *    | int     | Página atual retornada. |
| `rows_per_page` *   | int     | Quantidade de registros por página. |

### Enumeradores payment_type

| Enumerador    | Descrição     |
|---------------|---------------|
| `bank_slip`     | Boleto bancário    |
| `collection_slip` | Fatura de recolhimento |

### Enumeradores batch_payment_status

| Enumerador    | Descrição     |
|---------------|---------------|
| `pending`     | Pendente de processamento |
| `pending_2fa_approval` | Pendente de aprovação 2FA |
| `rejected`    | Rejeitado |
| `approved`    | Aprovado |
| `processed`   | Processado |

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400         | BIP000026 | Bad Request | Invalid payment date format. The correct format is YYYY-MM-DD. | Formato de data de pagamento inválido. O formato correto é YYYY-MM-DD. |
| 400         | BIP000027 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
| 400         | BIP000047 | Bad Request | Invalid payment type. | Tipo de pagamento inválido. |

---

# Listar Pagamentos

URL: /documentation/baas/cobranca/listar_pagamentos

Este endpoint tem a finalidade de fornecer detalhes de todas as cobranças pagas pelo cliente, incluindo boletos bancários e Faturas de recolhimento.

:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::

:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::

## Request

### Request Endpoint

ENDPOINT /account/ ACCOUNT_KEY /payments
MÉTODO GET

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |

### Request Query String Params

| Campo               | Tipo        | Descrição                         |
|---------------------|-------------|-----------------------------------|
| `request_control_key` | uuid4     | Chave única de identificação da request do cliente. |
| `payment_key`         | uuid4     | Chave única de identificação do pagamento. |
| `payment_schedule_key`         | uuid4     | Chave única de identificação do agendamento de pagamento. |
| `payment_type`        | [enum](#enumeradores-payment_type)      | Tipo do pagamento. |
| `payment_status`        | [enum](#enumeradores-payment_status)      | Status do pagamento. |
| `date_from`           | string    | Data inicial. Formato "YYYY-MM-DD". |
| `date_to`             | string    | Data final. Formato "YYYY-MM-DD". |
| `page`                | string    | Número da página requisitada. 1 por padrão. |
| `page_size`           | string    | Tamanho da página requisitada na consulta. 30 por padrão e valor máximo. |

### Enumeradores payment_type
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

### Enumeradores payment_status
| Enumerador    | Descrição     |
|---------------|---------------|
| `pending_execution`     | Pendente de execução |
| `executed`    | Executado |
| `reverted`    | Revertido |
| `rejected`    | Rejeitado |
| `error`       | Erro      |

## Response

### Success Response

STATUS 200

Response Body: Consulta de pagamentos

```json
{
  "data": [
    {
        "payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea",
        "request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189",
        "payer_name":"COOPERATIVA INDUSTRIAL MURILO",
        "payer_document_number":"00037025000160",
        "source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
        "transaction_key":"4e80070a-a0bb-4be2-8178-55fbd73a3704",
        "transaction_revert_key":null,
        "paid_amount":1050.1,
        "payment_date":"2024-04-03",
        "payment_type":"bank_slip",
        "bank_slip": {
                "bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
                "barcode":"00193967000009910000000003615574000000002417",
                "digitable_line":"00190000090361557400500000024174396700000991000",
                "payer_name":"COOPERATIVA TESTE",
                "payer_document_number":"00037025000160",
                "beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
                "beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
                "beneficiary_document_number":"52069937000117",
                "beneficiary_bank_ispb":"00000000",
                "guarantor_name":null,
                "guarantor_document_number":null,
                "expiration_date":"2024-03-29",
                "max_payment_data": "2026-03-29",
                "partial_payment_indicator":"allowed",
                "registered_payment_amount":9029.0,
                "nominal_amount":9910.0,
                "total_amount":10129.1,
                "rebate_amount":0.0,
                "discount_amount":0.0,
                "fine_amount":0.0,
                "interest_amount":219.1
            },
        "collection_slip":null,
        "payment_status":"executed"
    }
  ],
  "pagination": {
    "current_page": 1,
    "rows_per_page": 30
  }
}
```

### Response Body Params

| Campo               | Tipo    | Descrição                         |
|---------------------|---------|-----------------------------------|
| `payment_key` *               | uuid4 | Chave única de identificação do pagamento. |
| `request_control_key` *       | uuid4 | Chave única de identificação da request do cliente. |
| `payer_name` *                | string | Nome do pagador efetivo.|
| `payer_document_number` *     | string | Número de documento do pagador efetivo (CPF/CNPJ). |
| `source_account_key` *        | uuid4 | Chave da conta debitada. |
| `transaction_key` *           | uuid4 | Chave da transação do pagamento. |
| `transaction_revert_key`      | uuid4 | Chave da transação de reversão do pagamento. |
| `paid_amount` *               | number | Valor pago efetivamente. |
| `payment_date` *              | string | Data do pagamento. |
| `payment_type` *              | [enum](#enumeradores-payment_type-1) | Tipo do pagamento. |
| `bank_slip`                   | [object](#objeto-bank_slip) | Boleto bancário. |
| `collection_slip`             | [object](#objeto-collection_slip) | Fatura de recolhimento. |
| `payment_status` *            | [enum](#enumeradores-payment_status) | Status do pagamento. |

### Enumeradores payment_type
| Enumerador    | Descrição     |
|---------------|---------------|
| `bank_slip`     | Boleto bancário    |
| `collection_slip` | Fatura de recolhimento |

### Enumeradores payment_status
| Enumerador    | Descrição     |
|---------------|---------------|
| `pending_execution`     | Pendente de execução |
| `executed`    | Executado |
| `reverted`    | Revertido |
| `rejected`    | Rejeitado |
| `error`       | Erro      |

### Objeto bank_slip
| Campo                             | Tipo    | Descrição                         |
|-----------------------------------|---------|-----------------------------------|
| `barcode` *                       | string | Código de barras. |
| `digitable_line` *                | string | Linha digitável. |
| `payer_name` *                    | string | Nome do pagador.|
| `payer_document_number` *         | string | Número de documento do pagador (CPF/CNPJ). |
| `beneficiary_name` *              | string | Nome do beneficiário. |
| `beneficiary_trading_name`        | string | Nome fantasia do beneficiário. |
| `beneficiary_document_number` *   | string | Número de documento do beneficiário (CPF/CNPJ). |
| `beneficiary_bank_ispb` *         | string | Código ispb do banco do beneficiário. |
| `guarantor_name`                  | string | Nome do sacador avalista. |
| `guarantor_document_number`       | string | Número de documento do sacador avalista (CPF/CNPJ). |
| `expiration_date` *               | string | Data de vencimento. |
| `max_payment_date` * | string  | Data máxima de pagamento. |
| `partial_payment_indicator` *     | [enum](#enumeradores-partial_payment_indicator)   | Indicador de pagamento parcial. |
| `registered_payment_amount`       | string | Valor total de pagamento registrado. |
| `nominal_amount` *                | number | Valor original. |
| `total_amount` *                  | number | Valor total. |
| `rebate_amount` *                 | number | Valor do abatimento. |
| `discount_amount` *               | number | Valor do desconto. |
| `fine_amount` *                   | number | Valor da multa. |
| `interest_amount` *               | number | Valor do juros. |

### Enumeradores partial_payment_indicator
| Enumerador    | Descrição     |
|---------------|---------------|
| `allowed`     | Permitido     |
| `not_allowed` | Não permitido |

### Objeto collection_slip
| Campo                             | Tipo    | Descrição                         |
|-----------------------------------|---------|-----------------------------------|
| `barcode` *                       | string | Código de barras. |
| `digitable_line` *                | string | Linha digitável. |
| `collection_name` *               | string | Nome do pagador.|
| `collection_document_number` *    | string | Número de documento do convênio (CPF/CNPJ). |
| `expiration_date` *               | string | Data de vencimento. |
| `total_amount` *                  | number | Valor total. |

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400         | BIP000026 | Bad Request | Invalid payment date format. The correct format is YYYY-MM-DD. | Formato de data de pagamento inválido. O formato correto é YYYY-MM-DD. |
| 400         | BIP000027 | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
| 400         | BIP000047 | Bad Request | Invalid payment type. | Tipo de pagamento inválido. |

---

# Realizar Pagamento de Boleto Bancário

URL: /documentation/baas/cobranca/pagar_boleto_bancario

Este endpoint permite realizar o pagamento de boletos bancários. O pagamento deve ser realizado após a consulta, utilizando as informações retornadas para garantir o funcionamento correto do fluxo, evitando falhas durante o processo de pagamento.

:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::

## Request

### Request Endpoint

ENDPOINT /account/ ACCOUNT_KEY /payment/bank_slip
MÉTODO POST

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |

Request Body: Pagamento de boleto bancário com linha digitável

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "digitable_line": "00190000090361557400500000024174396700000991000",
  "payment_amount": 1156.8
}
```
Request Body: Pagamento de boleto bancário com código de barras

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "barcode": "00190000090361557400500000024174396700000991000",
  "payment_amount": 1156.8
}
```

### Body Params

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | Chave única de identificação da request do cliente. |    
| `barcode`               | string    | Código de barras. |
| `digitable_line`        | string    | Linha digitável. |
| `payment_amount` *      | number    | Valor a ser pago. |

:::danger Aviso
O `payment_amount` deve ser sempre igual ao `total_amount` retornado na consulta do boleto bancário caso o pagamento parcial não seja permitido para o boleto bancário. Para títulos em que o pagamento parcial é permitido, o cliente pode escolher arbitrariamente o `payment_amount`, podendo, inclusive, exceder o valor de face do boleto (`total_amount`).
:::

## Response

### Success Response

STATUS 201

Response Body: Pagamento executado

```json
{
   "payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea",
   "request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189",
   "payer_name":"COOPERATIVA INDUSTRIAL MURILO",
   "payer_document_number":"00037025000160",
   "source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
   "transaction_key":"4e80070a-a0bb-4be2-8178-55fbd73a3704",
   "transaction_revert_key":null,
   "paid_amount":1050.1,
   "payment_date":"2024-04-03",
   "payment_type":"bank_slip",
   "bank_slip": {
        "bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
        "barcode":"00193967000009910000000003615574000000002417",
        "digitable_line":"00190000090361557400500000024174396700000991000",
        "payer_name":"COOPERATIVA TESTE",
        "payer_document_number":"00037025000160",
        "beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
        "beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
        "beneficiary_document_number":"52069937000117",
        "beneficiary_bank_ispb":"00000000",
        "guarantor_name":null,
        "guarantor_document_number":null,
        "expiration_date":"2024-03-29",
        "max_payment_data": "2026-03-29",
        "partial_payment_indicator":"allowed",
        "registered_payment_amount":9029.0,
        "nominal_amount":9910.0,
        "total_amount":10129.1,
        "rebate_amount":0.0,
        "discount_amount":0.0,
        "fine_amount":0.0,
        "interest_amount":219.1
    },
   "collection_slip":null,
   "payment_status":"executed"
}
```

STATUS 202

Response Body: Pagamento pendente de execução

```json
{
   "payment_key":"c4325104-d60b-44f3-aae4-49155564a2ea",
   "request_control_key":"b713b2f6-2f48-4d18-b0c9-7186e4edf189",
   "payer_name":"COOPERATIVA INDUSTRIAL MURILO",
   "payer_document_number":"00037025000160",
   "source_account_key":"6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
   "transaction_key":"4e80070a-a0bb-4be2-8178-55fbd73a3704",
   "transaction_revert_key":null,
   "paid_amount":1050.1,
   "payment_date":"2024-04-03",
   "payment_type":"bank_slip",
   "bank_slip": {
        "bank_slip_key":"95080ffd-3ac5-48d7-b3fe-659e4aaba81a",
        "barcode":"00193967000009910000000003615574000000002417",
        "digitable_line":"00190000090361557400500000024174396700000991000",
        "payer_name":"COOPERATIVA TESTE",
        "payer_document_number":"00037025000160",
        "beneficiary_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
        "beneficiary_trading_name":"TESTE EQUIPAMENTOS E SERVICOS LTDA",
        "beneficiary_document_number":"52069937000117",
        "beneficiary_bank_ispb":"00000000",
        "guarantor_name":null,
        "guarantor_document_number":null,
        "expiration_date":"2024-03-29",
        "max_payment_data": "2026-03-29",
        "partial_payment_indicator":"allowed",
        "registered_payment_amount":9029.0,
        "nominal_amount":9910.0,
        "total_amount":10129.1,
        "rebate_amount":0.0,
        "discount_amount":0.0,
        "fine_amount":0.0,
        "interest_amount":219.1
    },
   "collection_slip":null,
   "payment_status": "pending_execution"
}
```

:::info Informação
Caso seja retornado **HTTP Status 202** com o campo `payment_status` com valor **pending_execution**, o pagamento não deve ser retentado.

Esta esse pagamento será processado assincronamente. É necessário verificar o status da transferência por meio
da consulta de pagamento, ou aguardar envio do webhook de pagamento pendente descrito na [página de webhooks](/documentation/baas/cobranca/webhooks).
:::

### Response Body Params

| Campo               | Tipo    | Descrição                         |
|---------------------|---------|-----------------------------------|
| `payment_key` *               | uuid4 | Chave única de identificação do pagamento. |
| `request_control_key` *       | uuid4 | Chave única de identificação da request do cliente. |
| `payer_name` *                | string | Nome do pagador efetivo.|
| `payer_document_number` *     | string | Número de documento do pagador efetivo (CPF/CNPJ). |
| `source_account_key` *        | uuid4 | Chave da conta debitada. |
| `transaction_key` *           | uuid4 | Chave da transação do pagamento. |
| `transaction_revert_key`      | uuid4 | Chave da transação de reversão do pagamento. |
| `paid_amount` *               | number | Valor pago efetivamente. |
| `payment_date` *              | string | Data do pagamento. |
| `payment_type` *              | [enum](#enumeradores-payment_type) | Tipo do pagamento. |
| `bank_slip`                   | [object](#objeto-bank_slip) | Boleto bancário. |
| `collection_slip`             | object | Fatura de recolhimento. |
| `payment_status` *            | [enum](#enumeradores-payment_status) | Status do pagamento. |

### Enumeradores payment_type
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

:::danger Aviso
O enumerador `collection_slip` não se aplica para o fluxo de boletos bancários, assim como o objeto collection_slip que sempre será nulo.
:::

### Enumeradores payment_status
| Enumerador    | Descrição     |
|---------------|---------------|
| `pending_execution`     | Pendente de execução |
| `executed`    | Executado |
| `reverted`    | Revertido |
| `rejected`    | Rejeitado |
| `error`       | Erro      |

:::danger Aviso
Para pagamentos onde a QI não receber uma resposta da CIP em até dois minutos, o pagamento será retornado com o status `pending_execution`. Após a QI receber a resposta da CIP, será enviado para o cliente o webhook de pagamento pendente descrito na [página de webhooks](/documentation/baas/cobranca/webhooks).
:::

### Objeto bank_slip
| Campo                             | Tipo    | Descrição                         |
|-----------------------------------|---------|-----------------------------------|
| `barcode` *                       | string | Código de barras. |
| `digitable_line` *                | string | Linha digitável. |
| `payer_name` *                    | string | Nome do pagador.|
| `payer_document_number` *         | string | Número de documento do pagador (CPF/CNPJ). |
| `beneficiary_name` *              | string | Nome do beneficiário. |
| `beneficiary_trading_name`        | string | Nome fantasia do beneficiário. |
| `beneficiary_document_number` *   | string | Número de documento do beneficiário (CPF/CNPJ). |
| `beneficiary_bank_ispb` *         | string | Código ispb do banco do beneficiário. |
| `guarantor_name`                  | string | Nome do sacador avalista. |
| `guarantor_document_number`       | string | Número de documento do sacador avalista (CPF/CNPJ). |
| `expiration_date` *               | string | Data de vencimento. |
| `max_payment_date` * | string  | Data máxima de pagamento. |
| `partial_payment_indicator` *     | [enum](#enumeradores-partial_payment_indicator)   | Indicador de pagamento parcial. |
| `registered_payment_amount`       | string | Valor total de pagamento registrado. |
| `nominal_amount` *                | number | Valor original. |
| `total_amount` *                  | number | Valor total. |
| `rebate_amount` *                 | number | Valor do abatimento. |
| `discount_amount` *               | number | Valor do desconto. |
| `fine_amount` *                   | number | Valor da multa. |
| `interest_amount` *               | number | Valor do juros. |

### Enumeradores partial_payment_indicator
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `allowed`     | string    | Permitido     |
| `not_allowed` | string    | Não permitido |

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400         | BIP000001 | Bad Request | The barcode or digitable line must have 44 or 47 characters. | O código de barras ou linha digitável deve ter 44 ou 47 caracteres. |
| 400         | BIP000002 | Bad Request | The bill sent does not correspond to a bank slip. | A conta enviado não corresponde a um boleto bancário. |
| 400         | BIP000003 | Bad Request | The digitable line sent is invalid. | A linha digitável enviada é inválida. |
| 404         | BIP000004 | Not Found | The bank slip was not found. | O boleto não foi encontrado. |
| 400         | BIP000005 | Bad Request | It was not possible to consult the bank slip at this time. Please try again in a few minutes. | Não foi possível consultar o boleto neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000006 | Bad Request | Bank slip already written off | Boleto já baixado |
| 400         | BIP000007 | Bad Request | Bank slip blocked for payment | Boleto bloqueado para pagamento |
| 400         | BIP000008 | Bad Request | Bank slip already paid | Boleto já pago |
| 400         | BIP000009 | Bad Request | Invalid bank slip. Please consult issuing bank | Boleto inválido. Favor consultar banco emissor |
| 403         | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404         | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400         | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400         | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 400         | BIP000015 | Bad Request | Payment date is greater than the maximum payment date. | A data de pagamento é maior que a data máxima de pagamento. |
| 400         | BIP000016 | Bad Request | Payment date is smaller than the calculation date. | A data de pagamento é menor que a data de cálculo. |
| 400         | BIP000017 | Bad Request | Invalid payment amount. | Valor de pagamento inválido. |
| 400         | BIP000018 | Bad Request | Partial payment is not allowed. | Pagamento parcial não é permitido. |
| 400         | BIP000019 | Bad Request | The payment amount is greater than the available amount. | O valor do pagamento é maior que o valor disponível. |
| 400         | BIP000020 | Bad Request | All partial payments for this bank slip have already been made. | Todos os pagamentos parciais deste boleto já foram realizados. |
| 400         | BIP000022 | Bad Request | Bank slip payment service is closed. | Serviço de pagamento de boleto está fechado. |
| 400         | BIP000023 | Bad Request | The source account has insufficient balance. Payment cannot be made. | A conta de origem possui saldo insuficiente. Pagamento não pode ser realizado. |
| 400         | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 400         | BIP000025 | Bad Request | It was not possible to pay the bank slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar o boleto neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. |
| 400         | BIP000028 | Bad Request | The source account has blocked balance. Payment cannot be made. | A conta de origem possui saldo em conta bloqueado. Pagamento não pode ser realizado. |

## Ambiente de Sandbox

Em nosso ambiente de sandbox, disponibilizamos linhas digitáveis mockadas para a simulação de pagamentos bem-sucedidos e testes de cenários de erro.

### Cenários de sucesso

| Linha digitável |
|---|
| 00190000090361557400500000024174396700000991000 |
| 00190000090282802601919212747174596760001294161 |
| 23793390014000000455277000249001596900000103995 |
| 75691434020137513680900001040013196770002417240 |
| 21390001171200000570700168167484796770000148206 |
| 07790001161200000039300602819070498470000182970 |
| 23792372059034189564835003432701998420000008306 |
| 03399199530490000005254172701010698420000467696 |
| 03399135012340000000830681701014198420038743888 |
| 75691324620100735471370255730478698420064900819 |

### Cenários de `pending_execution`

A simulação desse cenário está melhor descrita na [página de simulações](/documentation/baas/cobranca/simulacao).

| Linha digitável |
|---|
| 75691333790100505390300569460017397220000306867 |

### Cenários de erro

| Linha digitável | Código de erro |
|---|---|
| 34191090083273252027893634770007296690012513600 | BIP000007 |
| 07090010287045349010776686070590896770001160123 | BIP000007 |
| 42297048060005815702500130494123896770000239491 | BIP000006 |
| 74891123702849020818918378871083196690000050000 | BIP000009 |
| 23792374119000209350986000372408496610000122810 | BIP000008 |

---

# Realizar Pagamento de Fatura de Recolhimento (convênio/tributo)

URL: /documentation/baas/cobranca/pagar_fatura_de_recolhimento

Este endpoint permite realizar o pagamento de faturas de recolhimento. O pagamento deve ser realizado após a consulta, utilizando as informações retornadas na mesma, para garantir o funcionamento correto do fluxo evitando falhas durante o processo de pagamento.

:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgão públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um Boleto bancário apresenta.
:::

## Request

### Request Endpoint

ENDPOINT /account/ ACCOUNT_KEY /payment/collection_slip
MÉTODO POST

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |

Request Body: Pagamento de fatura de recolhimento com linha digitável

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "digitable_line": "00190000090361557400500000024174396700000991000",
  "payment_amount": 1156.8
}
```
Request Body: Pagamento de fatura de recolhimento com código de barras

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "barcode": "00190000090361557400500000024174396700000991000",
  "payment_amount": 1156.8
}
```

### Body Params

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | Chave única de identificação da request do cliente. |    
| `barcode`               | string    | Código de barras. |
| `digitable_line`        | string    | Linha digitável. |
| `payment_amount` *      | number    | Valor a ser pago. |

:::danger Aviso
O `payment_amount` deve sempre igual ao `total_amount` retornado na consulta do boleto bancário.
:::

## Response

### Success Response

STATUS 201

Response Body: Pagamento executado

```json
{
  "payment_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
  "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
  "payer_name": "COOPERATIVA INDUSTRIAL MURILO",
  "payer_document_number": "62069937000118",
  "source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "transaction_key": "fc9ccfd0-2f21-4207-9772-69238be74152",
  "transaction_revert_key": null,
  "paid_amount": 1389.21,
  "payment_date": "2024-04-30",
  "payment_type": "collection_slip",
  "bank_slip": null,
  "collection_slip": {
    "barcode": null,
    "digitable_line": "836200000138892100450006762142420244046000010192",
    "collection_name": "CIA ULTRAGAZ SA-COD",
    "collection_document_number": "00394460005887",
    "expiration_date": "2024-04-15",
    "total_amount": 1389.21
  },
  "payment_status": "executed"
}
```

STATUS 202

:::info Webhook
Quando o pagamento retornar status `202`, o processamento ainda está em andamento. **Não realize uma nova tentativa de pagamento** enquanto não receber a atualização do status final via webhook.
:::

Response Body: Pagamento pendente

```json
{
  "payment_key": "33860ad0-bcb0-47b7-bbe7-c7e3ec2fc61a",
  "request_control_key": "ae4508df-f2cb-4e28-9f04-a19b7f2758c9",
  "payer_name": "COOPERATIVA INDUSTRIAL MURILO",
  "payer_document_number": "62069937000118",
  "source_account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "transaction_key": "fc9ccfd0-2f21-4207-9772-69238be74152",
  "transaction_revert_key": null,
  "paid_amount": 1389.21,
  "payment_date": "2024-04-30",
  "payment_type": "collection_slip",
  "bank_slip": null,
  "collection_slip": {
    "barcode": null,
    "digitable_line": "836200000138892100450006762142420244046000010192",
    "collection_name": "CIA ULTRAGAZ SA-COD",
    "collection_document_number": "00394460005887",
    "expiration_date": "2024-04-15",
    "total_amount": 1389.21
  },
  "payment_status": "pending"
}
```

### Response Body Params

| Campo               | Tipo    | Descrição                         |
|---------------------|---------|-----------------------------------|
| `payment_key` *               | uuid4 | Chave única de identificação do pagamento. |
| `request_control_key` *       | uuid4 | Chave única de identificação da request do cliente. |
| `payer_name` *                | string | Nome do pagador efetivo.|
| `payer_document_number` *     | string | Número de documento do pagador efetivo (CPF/CNPJ). |
| `source_account_key` *        | uuid4 | Chave da conta debitada. |
| `transaction_key` *           | uuid4 | Chave da transação do pagamento. |
| `transaction_revert_key`      | uuid4 | Chave da transação de reversão do pagamento. |
| `paid_amount` *               | number | Valor pago efetivamente. |
| `payment_date` *              | string | Data do pagamento. |
| `payment_type` *              | [enum](#enumeradores-payment_type) | Tipo do pagamento. |
| `bank_slip`                   | object | Boleto bancário. |
| `collection_slip`             | [object](#objeto-collection_slip) | Fatura de recolhimento. |
| `payment_status` *            | [enum](#enumeradores-payment_status) | Status do pagamento. |

### Enumeradores payment_type
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

:::danger Aviso
O enumerador `bank_slip` não se aplica para o fluxo de faturas de recolhimento, assim como o objeto bank_slip que sempre será nulo.
:::

### Enumeradores payment_status
| Enumerador    | Descrição     |
|---------------|---------------|
| `pending`     | Pendente  |
| `executed`    | Executado |
| `reverted`    | Revertido |
| `rejected`    | Rejeitado |
| `error`       | Erro      |

### Objeto collection_slip
| Campo                             | Tipo    | Descrição                         |
|-----------------------------------|---------|-----------------------------------|
| `barcode`          | string | Código de barras. |
| `digitable_line`   | string | Linha digitável. |
| `collection_name` *         | string | Nome do convênio.|
| `collection_document_number`   | string | Número de documento do convênio (CPF/CNPJ).|
| `expiration_date` *  | string  | Data de vencimento. |
| `total_amount` *  | number | Valor total. |

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400         | BIP000032 | Bad Request | The bill sent does not correspond to a collection slip. | A conta enviada não corresponde a uma fatura de recolhimento. |
| 400         | BIP000033 | Bad Request | The barcode or digitable line of the collection slip must have 44 or 48 characters. | O código de barras ou linha digitável da fatura de recolhimento deve ter 44 ou 48 caracteres. |
| 403         | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404         | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400         | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400         | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 400         | BIP000023 | Bad Request | The source account has insufficient balance. Payment cannot be made. | A conta de origem possui saldo insuficiente. Pagamento não pode ser realizado. |
| 400         | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 400         | BIP000028 | Bad Request | The source account has blocked balance. Payment cannot be made. | A conta de origem possui saldo em conta bloqueado. Pagamento não pode ser realizado. |
| 400         | BIP000034 | Bad Request | Collection slip already paid. | Fatura de recolhimento já paga. |
| 400         | BIP000035 | Bad Request | Covenant slip invalid barcode. | Código de barras da fatura de recolhimento inválido. |
| 400         | BIP000036 | Bad Request | Covenant slip overdue. | Fatura de recolhimento vencida. |
| 400         | BIP000037 | Bad Request | Error in collection slip consultation. | Erro na consulta da fatura de recolhimento. |
| 400         | BIP000038 | Bad Request | Outside of covenant payment hours. | Fora do horário de pagamento do convênio. |
| 400         | BIP000039 | Bad Request | Collection slip not accepted. | Fatura de recolhimento não aceita. |
| 400         | BIP000040 | Bad Request | Minimum advance not reached. | Mínimo de dias de adiantamento não atingido. |
| 400         | BIP000041 | Bad Request | Max payment amount exceeded. | Valor máximo de pagamento excedido. |
| 400         | BIP000044 | Bad Request | It was not possible to pay the collection slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar a fatura de recolhimento neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. |
| 400         | BIP000045 | Bad Request | Collection slip payment service is closed. | Serviço de pagamento de fatura de recolhimento está fechado. |

## Ambiente de Sandbox

Em nosso ambiente de sandbox, disponibilizamos linhas digitáveis mockadas para a simulação de pagamentos bem-sucedidos e testes de cenários de erro.

### Cenários de sucesso

| Linha digitável |
|---|
| 828300000007411100972013905080001546763201900028 |
| 838000000009235700481007241345219112001474229880 |
| 848000000006308600802021201071261517689002201070 |
| 858200000015000000643025703477209504800448091020 |

### Cenários de erro

| Linha digitável | Código de erro |
|---|---|
| 858500000037350000643217212883260006147448091022 | BIP000035 |

---

# Simulação de cenários

URL: /documentation/baas/cobranca/simulacao_de_cenarios

## 1 - Simulação de pagamento em estado pendente de execução

Para pagamentos aonde a QI não receber uma resposta da CIP em até dois minutos, o pagamento será retornado com o status `pending_execution`. Após a QI receber a resposta da CIP, será enviado para o cliente o webhook de pagamento pendente descrito na [página de webhooks](/documentation/baas/cobranca/webhooks). Para simular este cenário, realize um pagamento com linha digitável `"digitable_line": "75691333790100505390300569460017397220000306867"`.

Para que o status do pagamento seja atualizado, realize a requisição abaixo com `payment_status` de **approved** para
aprovar o pagamento, ou **rejected** para reprová-lo.

## Request

### Request Endpoint

ENDPOINT /mock/account/ ACCOUNT_KEY /payment/ PAYMENT_KEY /bank_slip/confirmation
MÉTODO PATCH

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |
| `payment_key` *     | uuid4   | Chave única de identificação do pagamento.  | 36     |

Request Body: Simulação de confirmação de pagamento

```json
{
  "payment_status": "approved",
}
```

### Body Parameters

| Campo                       | Tipo   | Descrição                                                             |
|-----------------------------|--------|-----------------------------------------------------------------------|
| `payment_status` *           | [enum](#enumeradores-payment_status) | Status do pagamento |

### Enumeradores payment_status

| Enumerador   |Descrição |
|--------------|-----------|
| `approved`    | Aprovar e concluir o pagamento |
| `rejected`    | Rejeitar e reverter o pagamento |

## Response

### Success Response

STATUS 204

Response Body: Simulação concluída

```json
{}
```

---

# Solicitar Pagamento em Lote de Boleto Bancário

URL: /documentation/baas/cobranca/solicitar_pagamento_lote_de_boleto_bancario_com_confirmacao_de_lote

Este endpoint permite solicitar o pagamento de múltiplos boletos bancários em uma única requisição.

:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::

:::info Fluxo após a solicitação
Após a solicitação, o lote pode permanecer aguardando a [confirmação do lote](./confirmacao_de_lote_de_boleto_bancario.md), conforme as regras da operação.
:::

## Request

### Request Endpoint

ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments/batch_bank_slip
MÉTODO POST

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |

Request Body: Pagamento em lote de boletos bancários

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "bank_slip_payments": [
    {
      "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
      "digitable_line": "00190000090361557400500000024174396700000991000",
      "payment_amount": 1156.8
    },
    {
      "request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e",
      "barcode": "00190000090361557400500000024174396700000991000",
      "payment_amount": 200.5
    }
  ]
}
```

### Body Params

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | Chave única de identificação da requisição do cliente (lote). |
| `bank_slip_payments` * | array     | Lista de pagamentos de boleto bancário. Limite de **1000** itens por requisição. |

Cada elemento de `bank_slip_payments` deve conter:

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | Chave única de identificação da requisição do cliente para aquele item do lote. |
| `barcode`               | string    | Código de barras. |
| `digitable_line`        | string    | Linha digitável. |
| `payment_amount` *      | number    | Valor a ser pago. |

:::danger Aviso
Para cada item, o `payment_amount` enviado deve ser compatível com o que a consulta interna do boleto determinar: se o pagamento parcial **não** for permitido para aquele título, o valor deve corresponder ao total atualizado; se for permitido, o `payment_amount` pode seguir as regras do título (incluindo, quando aplicável, valores acima do nominal), como no fluxo de pagamento unitário de boleto bancário.
:::

## Response

### Success Response

STATUS 202

Response Body: Lote aceito para processamento

```json
{
  "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
  "total_amount": 1357.3,
  "batch_status": "pending",
  "payment_type": "bank_slip"
}
```

Response Body: exemplo ilustrativo (`batch_status` aprovado)

```json
{
  "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
  "total_amount": 1357.3,
  "batch_status": "approved",
  "payment_type": "bank_slip"
}
```

:::info Processamento do lote
O campo `batch_status` na resposta indica o **estado imediato** do lote após esta solicitação (por exemplo, pendente de confirmação ou já encaminhado ao processamento), conforme o fluxo aplicável. Quando houver etapa de [confirmação do lote](./confirmacao_de_lote_de_boleto_bancario.md), utilize essa chamada para aprovar ou rejeitar o lote antes do débito dos títulos. Os valores possíveis de `batch_status` estão em [batch_payment_status](#enumeradores-batch_payment_status).
:::

### Response Body Params

| Campo               | Tipo    | Descrição                         |
|---------------------|---------|-----------------------------------|
| `batch_payment_key` *       | uuid4 | Chave única de identificação do pagamento em lote. |
| `request_control_key` *     | uuid4 | Chave única de identificação da requisição do cliente (lote). |
| `account_key` *             | uuid4 | Chave da conta debitada. |
| `total_amount` *            | number | Soma dos valores (`payment_amount`) dos itens do lote. |
| `batch_status` *         | [enum](#enumeradores-batch_payment_status) | Status do lote logo após a solicitação; depende do fluxo (confirmação e processamento imediato). |
| `payment_type` *            | [enum](#enumeradores-payment_type) | Tipo do pagamento. |

### Enumeradores batch_payment_status

| Enumerador    | Descrição     |
|---------------|---------------|
| `pending`     | Pendente de processamento |
| `pending_2fa_approval` | Pendente de aprovação 2FA |
| `rejected`    | Rejeitado |
| `approved`    | Aprovado |
| `processed`   | Processado |

### Enumeradores payment_type

| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

:::danger Aviso
O enumerador `collection_slip` não se aplica ao fluxo de lote de boletos bancários deste endpoint; para este caso, espera-se `payment_type` com valor `bank_slip`.
:::

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 403         | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404         | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400         | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 400         | BIP000050 | Bad Request | Requester configuration does not exist. | Configuração do requester não existe. |
| 400         | BIP000080 | Bad Request | Beneficiary bank code of this bank slip is not allowed. | Banco beneficiário desse boleto não é permitido. |
| 400         | BIP000081 | Bad Request | A list of bank slip payments must be provided. | Uma lista de boletos bancários deve ser fornecida. |

---

# Solicitar Pagamento em Lote de Boleto Bancário

URL: /documentation/baas/cobranca/solicitar_pagamento_lote_de_boleto_bancario_sem_confirmacao_de_lote

Este endpoint permite solicitar o pagamento de múltiplos boletos bancários em uma única requisição.

:::info Boleto bancário
É o boleto bancário convencional (linhas digitáveis não iniciadas com dígito 8). Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.
:::

:::info Fluxo após a solicitação
Após a solicitação, o lote é encaminhado conforme o processamento definido para a operação. O campo `batch_status` reflete o estado imediato (por exemplo, pendente de processamento ou já em fila de débito). Os valores possíveis estão em [batch_payment_status](#enumeradores-batch_payment_status).
:::

## Request

### Request Endpoint

ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments/batch_bank_slip
MÉTODO POST

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |

Request Body: Pagamento em lote de boletos bancários

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "bank_slip_payments": [
    {
      "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
      "digitable_line": "00190000090361557400500000024174396700000991000",
      "payment_amount": 1156.8
    },
    {
      "request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e",
      "barcode": "00190000090361557400500000024174396700000991000",
      "payment_amount": 200.5
    }
  ]
}
```

### Body Params

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | Chave única de identificação da requisição do cliente (lote). |
| `bank_slip_payments` * | array     | Lista de pagamentos de boleto bancário. Limite de **1000** itens por requisição. |

Cada elemento de `bank_slip_payments` deve conter:

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | Chave única de identificação da requisição do cliente para aquele item do lote. |
| `barcode`               | string    | Código de barras. |
| `digitable_line`        | string    | Linha digitável. |
| `payment_amount` *      | number    | Valor a ser pago. |

:::danger Aviso
Para cada item, o `payment_amount` enviado deve ser compatível com o que a consulta interna do boleto determinar: se o pagamento parcial **não** for permitido para aquele título, o valor deve corresponder ao total atualizado; se for permitido, o `payment_amount` pode seguir as regras do título (incluindo, quando aplicável, valores acima do nominal), como no fluxo de pagamento unitário de boleto bancário.
:::

## Response

### Success Response

STATUS 202

Response Body: Lote aceito para processamento

```json
{
  "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
  "total_amount": 1357.3,
  "batch_status": "pending",
  "payment_type": "bank_slip"
}
```

Response Body: exemplo ilustrativo com `batch_status` aprovado

```json
{
  "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "6dc89d57-fac7-4643-b151-cd2ca0a7f68f",
  "total_amount": 1357.3,
  "batch_status": "approved",
  "payment_type": "bank_slip"
}
```

:::info Processamento do lote
O campo `batch_status` na resposta indica o **estado imediato** do lote após esta solicitação (por exemplo, pendente de processamento ou já encaminhado ao processamento dos títulos), conforme o fluxo aplicável. Os valores possíveis de `batch_status` estão em [batch_payment_status](#enumeradores-batch_payment_status).
:::

### Response Body Params

| Campo               | Tipo    | Descrição                         |
|---------------------|---------|-----------------------------------|
| `batch_payment_key` *       | uuid4 | Chave única de identificação do pagamento em lote. |
| `request_control_key` *     | uuid4 | Chave única de identificação da requisição do cliente (lote). |
| `account_key` *             | uuid4 | Chave da conta debitada. |
| `total_amount` *            | number | Soma dos valores (`payment_amount`) dos itens do lote. |
| `batch_status` *         | [enum](#enumeradores-batch_payment_status) | Status do lote logo após a solicitação; depende do processamento imediato e das regras da operação. |
| `payment_type` *            | [enum](#enumeradores-payment_type) | Tipo do pagamento. |

### Enumeradores batch_payment_status

| Enumerador    | Descrição     |
|---------------|---------------|
| `pending`     | Pendente de processamento |
| `pending_2fa_approval` | Pendente de aprovação 2FA |
| `rejected`    | Rejeitado |
| `approved`    | Aprovado |
| `processed`   | Processado |

### Enumeradores payment_type

| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

:::danger Aviso
O enumerador `collection_slip` não se aplica ao fluxo de lote de boletos bancários deste endpoint; para este caso, espera-se `payment_type` com valor `bank_slip`.
:::

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 403         | BIP000010 | Forbidden | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404         | BIP000011 | Not Found | The source account key was not found. | A chave da conta de origem não foi encontrada. |
| 400         | BIP000012 | Bad Request | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400         | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 400         | BIP000050 | Bad Request | Requester configuration does not exist. | Configuração do requester não existe. |
| 400         | BIP000080 | Bad Request | Beneficiary bank code of this bank slip is not allowed. | Banco beneficiário desse boleto não é permitido. |
| 400         | BIP000081 | Bad Request | A list of bank slip payments must be provided. | Uma lista de boletos bancários deve ser fornecida. |

---

# Solicitar Pagamento em Lote de Fatura de Recolhimento (convênio/tributo)

URL: /documentation/baas/cobranca/solicitar_pagamento_lote_de_fatura_de_recolhimento_com_confirmacao_de_lote

Este endpoint permite solicitar o pagamento de múltiplas faturas de recolhimento em uma única requisição.

:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um boleto bancário apresenta.
:::

:::info Fluxo após a solicitação
Após a solicitação, o lote pode permanecer aguardando a [confirmação do lote](./confirmacao_de_lote_de_fatura_de_recolhimento.md), conforme as regras da operação.
:::

## Request

### Request Endpoint

ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments/batch_collection_slip
MÉTODO POST

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |

Request Body: Pagamento em lote de faturas de recolhimento

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "collection_slip_payments": [
    {
      "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
      "digitable_line": "836200000138892100450006762142420244046000010192",
      "payment_amount": 1389.21
    },
    {
      "request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e",
      "barcode": "83620000001388921004500067621424202440460000101",
      "payment_amount": 1389.21
    }
  ]
}
```

### Body Params

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | Chave única de identificação da requisição do cliente (lote). |
| `collection_slip_payments` * | array     | Lista de pagamentos de fatura de recolhimento. Limite de **1000** itens por requisição. |

Cada elemento de `collection_slip_payments` deve conter:

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | Chave única de identificação da requisição do cliente para aquele item do lote. |
| `barcode`               | string    | Código de barras. |
| `digitable_line`        | string    | Linha digitável. |
| `payment_amount` *      | number    | Valor a ser pago. |

:::danger Aviso
Para cada item, o `payment_amount` enviado deve ser compatível com o que a consulta interna da fatura de recolhimento determinar (por exemplo, alinhado ao `total_amount` e às regras do convênio/tributo), nas mesmas condições do fluxo de pagamento unitário de fatura de recolhimento.
:::

## Response

### Success Response

STATUS 202

Response Body: Lote aceito para processamento

```json
{
  "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "total_amount": 2778.42,
  "batch_status": "pending",
  "payment_type": "collection_slip"
}
```

Response Body: exemplo ilustrativo (`batch_status` aprovado)

```json
{
  "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "total_amount": 2778.42,
  "batch_status": "approved",
  "payment_type": "collection_slip"
}
```

:::info Processamento do lote
O campo `batch_status` na resposta indica o **estado imediato** do lote após esta solicitação (por exemplo, pendente de confirmação ou já encaminhado ao processamento), conforme o fluxo aplicável. Quando houver etapa de [confirmação do lote](./confirmacao_de_lote_de_fatura_de_recolhimento.md), utilize essa chamada para aprovar ou rejeitar o lote antes do débito dos títulos. Os valores possíveis de `batch_status` estão em [batch_payment_status](#enumeradores-batch_payment_status).
:::

### Response Body Params

| Campo               | Tipo    | Descrição                         |
|---------------------|---------|-----------------------------------|
| `batch_payment_key` *       | uuid4 | Chave única de identificação do pagamento em lote. |
| `request_control_key` *     | uuid4 | Chave única de identificação da requisição do cliente (lote). |
| `account_key` *             | uuid4 | Chave da conta debitada. |
| `total_amount` *            | number | Soma dos valores (`payment_amount`) dos itens do lote. |
| `batch_status` *         | [enum](#enumeradores-batch_payment_status) | Status do lote logo após a solicitação; depende do fluxo (confirmação e processamento imediato). |
| `payment_type` *            | [enum](#enumeradores-payment_type) | Tipo do pagamento. |

### Enumeradores batch_payment_status

| Enumerador    | Descrição     |
|---------------|---------------|
| `pending`     | Pendente de processamento |
| `pending_2fa_approval` | Pendente de aprovação 2FA |
| `rejected`    | Rejeitado |
| `approved`    | Aprovado |
| `processed`   | Processado |

### Enumeradores payment_type

| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

:::danger Aviso
O enumerador `bank_slip` não se aplica ao fluxo de lote de faturas de recolhimento deste endpoint; para este caso, espera-se `payment_type` com valor `collection_slip`.
:::

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400         | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 400         | BIP000050 | Bad Request | Requester configuration does not exist. | Configuração do requester não existe. |
| 400         | BIP000082 | Bad Request | A list of collection slip payments must be provided. | Uma lista de faturas de recolhimento deve ser fornecida. |

---

# Solicitar Pagamento em Lote de Fatura de Recolhimento (convênio/tributo)

URL: /documentation/baas/cobranca/solicitar_pagamento_lote_de_fatura_de_recolhimento_sem_confirmacao_de_lote

Este endpoint permite solicitar o pagamento de múltiplas faturas de recolhimento em uma única requisição.

:::info Fatura de recolhimento
Esse tipo de cobrança é emitido por concessionárias de serviços (conta de água, luz, telefone e gás) e órgãos públicos (tributos). Eles não são registrados na Câmara Interbancária de Pagamento (CIP/Núclea), por isso, não retornam as mesmas informações que um boleto bancário apresenta.
:::

:::info Fluxo após a solicitação
Após a solicitação, o lote é encaminhado conforme o processamento definido para a operação. O campo `batch_status` reflete o estado imediato (por exemplo, pendente de processamento ou já em fila de débito). Os valores possíveis estão em [batch_payment_status](#enumeradores-batch_payment_status).
:::

## Request

### Request Endpoint

ENDPOINT /bill_payment/account/ ACCOUNT_KEY /payments/batch_collection_slip
MÉTODO POST

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |

Request Body: Pagamento em lote de faturas de recolhimento

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "collection_slip_payments": [
    {
      "request_control_key": "c7915a43-212f-5813-9adc-d3ed5d3d3bfd",
      "digitable_line": "836200000138892100450006762142420244046000010192",
      "payment_amount": 1389.21
    },
    {
      "request_control_key": "d8a26b54-323a-4924-0aed-e4fe6e4e4c0e",
      "barcode": "83620000001388921004500067621424202440460000101",
      "payment_amount": 1389.21
    }
  ]
}
```

### Body Params

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | Chave única de identificação da requisição do cliente (lote). |
| `collection_slip_payments` * | array     | Lista de pagamentos de fatura de recolhimento. Limite de **1000** itens por requisição. |

Cada elemento de `collection_slip_payments` deve conter:

| Campo               | Tipo          | Descrição                         |
|---------------------|---------------|-----------------------------------|
| `request_control_key` * | uuid4     | Chave única de identificação da requisição do cliente para aquele item do lote. |
| `barcode`               | string    | Código de barras. |
| `digitable_line`        | string    | Linha digitável. |
| `payment_amount` *      | number    | Valor a ser pago. |

:::danger Aviso
Para cada item, o `payment_amount` enviado deve ser compatível com o que a consulta interna da fatura de recolhimento determinar (por exemplo, alinhado ao `total_amount` e às regras do convênio/tributo), nas mesmas condições do fluxo de pagamento unitário de fatura de recolhimento.
:::

## Response

### Success Response

STATUS 202

Response Body: Lote aceito para processamento

```json
{
  "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "total_amount": 2778.42,
  "batch_status": "pending",
  "payment_type": "collection_slip"
}
```

Response Body: exemplo ilustrativo com `batch_status` aprovado

```json
{
  "batch_payment_key": "a3214093-e51c-55e2-b5d3-60244475b3fb",
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "account_key": "daae79e6-ee8b-449f-aa1e-96959d5d5a72",
  "total_amount": 2778.42,
  "batch_status": "approved",
  "payment_type": "collection_slip"
}
```

:::info Processamento do lote
O campo `batch_status` na resposta indica o **estado imediato** do lote após esta solicitação (por exemplo, pendente de processamento ou já encaminhado ao processamento dos títulos), conforme o fluxo aplicável. Os valores possíveis de `batch_status` estão em [batch_payment_status](#enumeradores-batch_payment_status).
:::

### Response Body Params

| Campo               | Tipo    | Descrição                         |
|---------------------|---------|-----------------------------------|
| `batch_payment_key` *       | uuid4 | Chave única de identificação do pagamento em lote. |
| `request_control_key` *     | uuid4 | Chave única de identificação da requisição do cliente (lote). |
| `account_key` *             | uuid4 | Chave da conta debitada. |
| `total_amount` *            | number | Soma dos valores (`payment_amount`) dos itens do lote. |
| `batch_status` *         | [enum](#enumeradores-batch_payment_status) | Status do lote logo após a solicitação; depende do processamento imediato e das regras da operação. |
| `payment_type` *            | [enum](#enumeradores-payment_type) | Tipo do pagamento. |

### Enumeradores batch_payment_status

| Enumerador    | Descrição     |
|---------------|---------------|
| `pending`     | Pendente de processamento |
| `pending_2fa_approval` | Pendente de aprovação 2FA |
| `rejected`    | Rejeitado |
| `approved`    | Aprovado |
| `processed`   | Processado |

### Enumeradores payment_type

| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

:::danger Aviso
O enumerador `bank_slip` não se aplica ao fluxo de lote de faturas de recolhimento deste endpoint; para este caso, espera-se `payment_type` com valor `collection_slip`.
:::

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400         | BIP000024 | Bad Request | Request control key already exists. | Chave de controle da requisição já existe. |
| 400         | BIP000050 | Bad Request | Requester configuration does not exist. | Configuração do requester não existe. |
| 400         | BIP000082 | Bad Request | A list of collection slip payments must be provided. | Uma lista de faturas de recolhimento deve ser fornecida. |

---

# Webhooks

URL: /documentation/baas/cobranca/webhooks

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

## Webhook de pagamentos

### Webhook Request Body

Request Body: Pagamento executado

```json
{
  "webhook_type": "baas.bill_payment.payment",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "source_account_key": "ca2c934e-5970-4c15-bdef-87e1b5c204e3",
    "payment_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "payment_schedule_key": null,
    "transaction_key": "5f67e4fc-d3bd-4831-a9b1-20859dcee7a9",
    "barcode":"00193967000009910000000003615574000000002417",
    "digitable_line":"00190000090361557400500000024174396700000991000",
    "payment_status": "executed",
    "payment_type":"bank_slip",
    "error_code": null,
    "error_message": null
  }
}
```

Request Body: Pagamento pendente de execução

```json
{
  "webhook_type": "baas.bill_payment.payment",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "source_account_key": "ca2c934e-5970-4c15-bdef-87e1b5c204e3",
    "payment_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "payment_schedule_key": null,
    "transaction_key": "5f67e4fc-d3bd-4831-a9b1-20859dcee7a9",
    "barcode":"00193967000009910000000003615574000000002417",
    "digitable_line":"00190000090361557400500000024174396700000991000",
    "payment_status": "pending_execution",
    "payment_type":"bank_slip",
    "error_code": null,
    "error_message": null
  }
}
```

Request Body: Pagamento rejeitado

```json
{
  "webhook_type": "baas.bill_payment.payment",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "source_account_key": "ca2c934e-5970-4c15-bdef-87e1b5c204e3",
    "payment_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "payment_schedule_key": null,
    "transaction_key": null,
    "barcode":"00193967000009910000000003615574000000002417",
    "digitable_line":"00190000090361557400500000024174396700000991000",
    "payment_status": "rejected",
    "payment_type":"bank_slip",
    "error_code": "BIP000023",
    "error_message": "The source account has insufficient balance. Payment cannot be made."
  }
}
```

Request Body: Pagamento revertido

```json
{
  "webhook_type": "baas.bill_payment.payment",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "source_account_key": "ca2c934e-5970-4c15-bdef-87e1b5c204e3",
    "payment_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "payment_schedule_key": null,
    "transaction_key": "5f67e4fc-d3bd-4831-a9b1-20859dcee7a9",
    "barcode":"81620000000000336592028110120200020214942099",
    "digitable_line":"816200000007000336592027811012020004202149420996",
    "payment_status": "reverted",
    "payment_type":"collection_slip",
    "error_code": "BIP000029",
    "error_message": "Bank slip payment write off rejected."
  }
}
```

### Webhook Body Params

| Campo                 | Tipo   | Descrição                                                 |
|-----------------------|--------|-----------------------------------------------------------|
| `webhook_type`        | string | Um enumerador que define o tipo de evento sendo reportado |
| `webhook_datetime`    | string | Data e hora do envio do webhook                           |
| `request_control_key` | uuid4  | Chave única de identificação da request do cliente.     |
| `source_account_key` *        | uuid4 | Chave da conta debitada.                            |
| `payment_key`        | uuid4  | Chave única de identificação do pagamento. |
| `payment_schedule_key` | uuid4     | Chave única de identificação do agendamento (somente para pagamentos gerados a partir de um agendamento).                             |
| `barcode`            | string | Código de barras. |
| `digitable_line`     | string | Linha digitável. |
| `payment_type`       | [enum](#enumeradores-payment_type) | Tipo do pagamento. |
| `payment_status`     | [enum](#enumeradores-payment_status) | Status do pagamento. |
| `error_code`       | string | Código de erro. |
| `error_message`     | string | Mensagem de erro. |

### Enumeradores payment_type
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

### Enumeradores payment_status
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `executed`    | string  | Executado |
| `rejected`    | string  | rejeitado |
| `reverted`    | string  | Revertido |

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400         | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400         | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 400         | BIP000023 | Bad Request | The source account has insufficient balance. Payment cannot be made. | A conta de origem possui saldo insuficiente. Pagamento não pode ser realizado. |
| 400         | BIP000025 | Bad Request | It was not possible to pay the bank slip at this time. Please verify your information and, if necessary, contact us for assistance. | Não foi possível pagar o boleto neste momento. Por favor, verifique suas informações e, se necessário, entre em contato conosco para assistência. |
| 400         | BIP000029 | Bad Request | Bank slip payment write off rejected. | Baixa de pagamento de boleto rejeitada. |
| 400         | BIP000034 | Bad Request | Collection slip already paid. | Fatura de recolhimento já paga. |
| 400         | BIP000036 | Bad Request | Covenant slip overdue. | Fatura de recolhimento vencida. |
| 400         | BIP000038 | Bad Request | Outside of covenant payment hours. | Fora do horário de pagamento do convênio. |
| 400         | BIP000044 | Bad Request | It was not possible to pay the collection slip at this time. Please verify your 

## Webhook de agendamento de pagamento

:::info Fluxo de Webhooks para Agendamentos de Pagamentos
O processo de agendamento e execução de pagamentos envolve a utilização de diferentes webhooks, cada um desempenhando um papel específico na notificação e no acompanhamento do status do pagamento.

Quando o agendamento é executado na data solicitada, ele pode seguir para o status `executed` e será disparado um webhook de `payment_schedule` com o status `executed`, a execução do agendamento resulta na criação de um `payment` com o status `pending` e será enviado o webhook do mesmo. Alternativamente, o agendamento pode seguir para o status `rejected`, sem que o `payment` seja criado, em situações como o fechamento da conta ou alteração do valor do boleto, por exemplo. Nesse caso somente o webhook de `payment_schedule` com o status `rejected` é enviado, acompanhado dos devidos códigos de erro.

- Inicialmente, o status do pagamento será `pending`, pois o processo de pagamento está em andamento. Quando o pagamento é concluído, um novo webhook de `payment` é enviado, agora com o status `executed`.
- Se o pagamento não puder ser concluído, por exemplo, devido à falta de saldo na conta, um webhook de `payment` com o status `rejected` será enviado, acompanhado dos devidos códigos de erro.
- Em casos de insuficiência de saldo na conta, o sistema realizará até 3 tentativas de pagamento, com um intervalo de 30 minutos entre cada uma. Nessa situação, poderão ser gerados múltiplos registros de pagamento para um mesmo agendamento executado. Por exemplo, se o saldo suficiente estiver disponível apenas na terceira tentativa, serão disparados os webhooks dos dois primeiros pagamentos com os status `payment` e `rejected`, seguidos pelos webhooks do terceiro pagamento com os status `payment` e `executed`.
:::

### Webhook Request Body

Request Body: Agendamento de pagamento executado

```json
{
  "webhook_type": "baas.bill_payment.payment_schedule",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "source_account_key": "ca2c934e-5970-4c15-bdef-87e1b5c204e3",
    "payment_schedule_key": "a72947e5-e676-4710-8f66-7d345f1c4064",
    "payment_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "barcode":"00193967000009910000000003615574000000002417",
    "digitable_line":"00190000090361557400500000024174396700000991000",
    "payment_type":"bank_slip",
    "payment_schedule_status": "executed",
    "error_code": null,
    "error_message": null
  }
}
```

Request Body: Agendamento de pagamento rejeitado

```json
{
  "webhook_type": "baas.bill_payment.payment_schedule",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "source_account_key": "ca2c934e-5970-4c15-bdef-87e1b5c204e3",
    "payment_schedule_key": "a72947e5-e676-4710-8f66-7d345f1c4064",
    "payment_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "barcode":"00193967000009910000000003615574000000002417",
    "digitable_line":"00190000090361557400500000024174396700000991000",
    "payment_type":"bank_slip",
    "payment_schedule_status": "rejected",
    "error_code": "BIP000007",
    "error_message": "Bank slip blocked for payment"
  }
}
```

### Webhook Body Params

| Campo                 | Tipo   | Descrição                                                 |
|-----------------------|--------|-----------------------------------------------------------|
| `webhook_type`        | string | Um enumerador que define o tipo de evento sendo reportado |
| `webhook_datetime`    | string | Data e hora do envio do webhook                           |
| `request_control_key` | uuid4  | Chave única de identificação da request do cliente.     |
| `source_account_key` *        | uuid4 | Chave da conta debitada.                            |
| `payment_key`        | uuid4  | Chave única de identificação do pagamento. |
| `payment_schedule_key`        | uuid4  | Chave única de identificação do agendamento pagamento. |
| `barcode`            | string | Código de barras. |
| `digitable_line`     | string | Linha digitável. |
| `payment_type`       | [enum](#enumeradores-payment_type) | Tipo do agendamento de pagamento. |
| `payment_schedule_status`     | [enum](#enumeradores-payment_schedule_status) | Status do agendamento de pagamento. |
| `error_code`       | string | Código de erro. |
| `error_message`     | string | Mensagem de erro. |

### Enumeradores payment_type
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `bank_slip`     | string    | Boleto bancário    |
| `collection_slip` | string  | Fatura de recolhimento |

### Enumeradores payment_schedule_status
| Enumerador    | Tipo      | Descrição     |
|---------------|-----------|---------------|
| `executed`    | string  | Executado |
| `rejected`    | string  | Rejeitado |

| Código HTTP | Código QI | Título | Descrição (eng) | Descrição (pt-br) |
|-------------|-----------|--------|------------------|------------------|
| 400         | BIP000013 | Bad Request | The source account is closed. | A conta de origem está fechada. |
| 400         | BIP000014 | Bad Request | The source account is blocked. | A conta de origem está bloqueada. |
| 400         | BIP000006 | Bad Request | Bank slip already written off | Boleto já baixado |
| 400         | BIP000007 | Bad Request | Bank slip blocked for payment | Boleto bloqueado para pagamento |
| 400         | BIP000008 | Bad Request | Bank slip already paid | Boleto já pago |
| 400         | BIP000009 | Bad Request | Invalid bank slip. Please consult issuing bank | Boleto inválido. Favor consultar banco emissor |
| 400         | BIP000034 | Bad Request | Collection slip already paid. | Fatura de recolhimento já paga. |

---

# Consultar dispositivo

URL: /documentation/baas/dispositivo/consultar_dispositivo

## Request

ENDPOINT /account/ ACCOUNT_KEY /device/ DEVICE_KEY
MÉTODO GET

### Path Params

| Campo         | Tipo   | Descrição                              | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36         |
| `device_key` | uuidv4 | Chave única de identificação do dispositivo. | 36         |

## Response

STATUS 200

Response Body: Dispositivo encontrado

```json
{
  "device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "session_id": "05894BAD-C94E-4A61-B2A8-57EDAE868A0F",
  "analysis_status": "automatically_approved",
  "status": "registered",
  "device_registration_data": {
    "device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "session_id": "05894BAD-C94E-4A61-B2A8-57EDAE868A0F",
    "document_number": "438.858.048-16",
    "registration_date": "2025-06-30T14:52:13-03:00",
    "face_recognition_key": "367195fc-de24-46b0-9ddb-79231dc7eeff"
  },
  "analysis_status_events": [
    {
      "new_analisys_status": "automatically_approved",
      "reason": null,
      "reason_description": null,
      "event_date": "2025-06-30T14:52:13Z"
    }
  ],
  "status_events": [
    {
      "new_status": "registered",
      "event_date": "2025-06-30T14:52:13Z"
    }
  ],
  "registration_date": "2025-06-30T14:52:14Z",
  "created_at": "2025-06-30T14:52:13Z"
}
```

### Response Body Params

| Campo                   | Tipo   | Descrição                                                                           | Caracteres |
|-------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `device_key` *          | uuidv4 | Chave única de identificação do dispositivo no formato uuid v4                     | 36         |
| `session_id` *          | uuidv4 | Identificador da sessão obtido via device_scan                                      | 36         |
| `analysis_status` *      | string | Status da análise do motor de fraude                                                | **[Enumeradores analysis_status](#enumeradores-analysis_status)** |
| `status` *               | string | Status do dispositivo                                                               | **[Enumeradores status](#enumeradores-status)** |
| `device_registration_data` * | object | Dados de registro do dispositivo                                            | **[Objeto device_registration_data](#objeto-device_registration_data)** |
| `analysis_status_events` * | array | Histórico de eventos de mudança de status de análise                               | -          |
| `status_events` *       | array  | Histórico de eventos de mudança de status do dispositivo                           | -          |
| `registration_date` *    | string | Data de registro do dispositivo no formato ISO (UTC - "YYYY-MM-DDTHH:MM:SSZ")       | 20         |
| `created_at` *           | string | Data de criação do dispositivo no formato ISO (UTC - "YYYY-MM-DDTHH:MM:SSZ")       | 20         |

### Objeto device_registration_data

| Campo                   | Tipo   | Descrição                                                                           | Caracteres |
|-------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `device_key` *          | uuidv4 | Chave única de identificação do dispositivo no formato uuid v4                     | 36         |
| `session_id` *          | uuidv4 | Identificador da sessão obtido via device_scan                                      | 36         |
| `document_number`       | string | Número do documento (CPF/CNPJ) do usuário                                          | 14         |
| `registration_date` *   | string | Data de registro no formato ISO com fuso horário                                   | 25         |
| `face_recognition_key`  | uuidv4 | Chave de reconhecimento facial (quando aplicável)                                  | 36         |

### Objeto analysis_status_event

| Campo                   | Tipo   | Descrição                                                                           | Caracteres |
|-------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `new_analisys_status` * | string | Novo status de análise                                                              | **[Enumeradores analysis_status](#enumeradores-analysis_status)** |
| `reason`                | string | Razão da mudança de status (quando aplicável)                                       | -          |
| `reason_description`    | string | Descrição da razão da mudança de status (quando aplicável)                          | -          |
| `event_date` *          | string | Data do evento no formato ISO (UTC - "YYYY-MM-DDTHH:MM:SSZ")                        | 20         |

### Objeto status_event

| Campo                   | Tipo   | Descrição                                                                           | Caracteres |
|-------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `new_status` *          | string | Novo status do dispositivo                                                          | **[Enumeradores status](#enumeradores-status)** |
| `event_date` *          | string | Data do evento no formato ISO (UTC - "YYYY-MM-DDTHH:MM:SSZ")                        | 20         |

### Enumeradores analysis_status

| Enumerador              | Descrição                               |
|-------------------------|-----------------------------------------|
| automatically_approved  | Aprovado automaticamente pelo motor de fraude |
| automatically_reproved | Reprovado automaticamente pelo motor de fraude |
| pending                 | Pendente de análise                     |

### Enumeradores status

| Enumerador         | Descrição                               |
|--------------------|-----------------------------------------|
| registered         | Dispositivo registrado                  |
| disabled           | Dispositivo desativado                 |
| pending            | Dispositivo pendente de aprovação       |

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (ptbr)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Erro de Schema                                                                                                         |
| 404                      | OBD000002            | Not Found                             | Bank account not found                                                   | Conta não encontrada                                                       |
| 404                      | OBD000100            | Device not found                                 | No device is associated with the provided device_key.                                                                                     | Nenhum dispositivo está associado à device_key fornecida.                                             |

---

# Aprovar criação de dispositivo

URL: /documentation/baas/dispositivo/create/aprovar_cadastro_dispositivo

## Request

ENDPOINT /account/ ACCOUNT_KEY /device/ DEVICE_KEY /validate
MÉTODO PUT

### Path Params

| Campo         | Tipo   | Descrição                              | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36         |
| `device_key` | uuidv4 | Chave única de identificação do dispositivo. | 36         |

Request Body

```json
{
  "token": "329adf"
}
```

### Body Params

| Campo     | Tipo   | Descrição                                                             | Caracteres |
|-----------|--------|-----------------------------------------------------------------------|------------|
| `token` * | string | Código de autenticação enviado ao aprovador de movimentações da conta | 6          | 

## Response

STATUS 201

Response Body: Dispositivo Criado

```json
{
  "device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "device_status": "created",
  "created_at": "2024-12-22T20:30:23.459Z"
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (ptbr)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Erro de Schema                                                                                                         |
| 404                      | OBD000002            | Not Found                             | Bank account not found                                                   | Conta não encontrada                                                       |
| 400                      | OBD000088            | Bad Request                               | Account blocked or closed can not perform this action                                                                                        | A conta bloqueada ou fechada não pode executar esta ação                                                                                    |
| 400                      | OBD000089            | Bad Request                               | Hub account can not perform this action                                                                                 | A conta hub não pode executar esta ação                                                                                    |
| 400                      | OBD000099            | Number of token validation attempts exceeded                                 | The maximum number of failed token validation attempts has been reached                                                                                     | Número máximo de tentativas de validação de token atingida                                                    |
| 404                      | OBD000100            | Device not found                                 | No device is associated with the provided device_key.                                                                                     | Nenhum dispositivo está associado à device_key fornecida.                                             |
| 400                      | OBD0000100            | Incorrect Token                                | Token sent does not match expected                             | Token enviado não condiz com, o esperado                                                                |

---

# Solicitar Criação de Dispositivo

URL: /documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo

## Request

ENDPOINT /account/ ACCOUNT_KEY /device
MÉTODO POST

### Path Params

| Campo         | Tipo   | Descrição                              | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36         |

**SMS**

Request Body: Autenticação via SMS

```json
{
    "device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "session_id": "fae3cb6c-9012-4b1c-9d61-7e8b2a6a5ed2",
    "tfa_info": {
        "approver_document_number": "98765432100",
        "contact_type": "sms",
    },
}
```

### Body Params

| Campo                   | Tipo       | Descrição                                                                                                                                                                                                                                        | Caracteres                              |
|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------|
| `device_key` * | uuidv4     | Chave única de identificação do dispositivo no formato uuid v4, adquirida atráves da **device_scan** (criada nesse momento pelo cliente integrador).                                                                                                                                                               | 36                                      | 
| `session_id` * | uuidv4     | Chave única de identificação da sessão no formato uuid v4, adquirida atráves da **device_scan** (criada nesse momento pelo cliente integrador).                                                                                                                                                               | 36                                      | 
| `tfa_info`*             | Object     | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato ou `image_key`.                                                                                                                                                                  | **[Objeto tfa_info](#objeto-tfa_info)** |

### Objeto tfa_info

| Campo                       | Tipo   | Descrição                                                                           | Caracteres |
|-----------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta.                                  | 11         | 
| `contact_type`*             | string | Indica o método de contato com a pessoa responsável pela aprovação da conta. Os valores possíveis são **sms**, **email**, ou **liveness** (quando a autenticação for realizada utilizando image_key).|            |

## Response

STATUS 202

Response Body: Transação Solicitada

```json
{
  "device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "device_status": "pending_2fa_approval",
  "created_at": "2024-12-22T20:30:23.459Z"
}
```

**Email**
Request Body: Autenticação via Email

```json
{
    "device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "session_id": "fae3cb6c-9012-4b1c-9d61-7e8b2a6a5ed2",
    "tfa_info": {
        "approver_document_number": "98765432100",
        "contact_type": "email",
    },
}
```

### Body Params

| Campo                   | Tipo       | Descrição                                                                                         | Caracteres                                          |
|-------------------------|------------|---------------------------------------------------------------------------------------------------|-----------------------------------------------------|
| `device_key` * | uuidv4     | Chave única de identificação do dispositivo no formato uuid v4, adquirida atráves da **device_scan** (criada nesse momento pelo cliente integrador).                                                                                                                                                               | 36                                      | 
| `session_id` * | uuidv4     | Chave única de identificação da sessão no formato uuid v4, adquirida atráves da **device_scan** (criada nesse momento pelo cliente integrador).                                                                                                                                                               | 36                                      | 
| `tfa_info`*             | Object     | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato ou `image_key`.                                                                                                                                                                  | **[Objeto tfa_info](#objeto-tfa_info)** |

### Objeto tfa_info

| Campo                       | Tipo   | Descrição                                                                           | Caracteres |
|-----------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta.                                  | 11         | 
| `contact_type`*             | string | Indica o método de contato com a pessoa responsável pela aprovação da conta. Os valores possíveis são **sms**, **email**, ou **liveness** (quando a autenticação for realizada utilizando image_key).|            |

## Response

STATUS 202

Response Body: Transação Solicitada

```json
{
  "device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "device_status": "pending_2fa_approval",
  "created_at": "2024-12-22T20:30:23.459Z"
}
```

**Image Key**

Request Body: Autenticação via Image Key

```json
{
    "device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "session_id": "fae3cb6c-9012-4b1c-9d61-7e8b2a6a5ed2",
    "tfa_info": {
        "approver_document_number": "98765432100",
        "contact_type": "liveness",
        "image_key": "367195fc-de24-46b0-9ddb-79231dc7eeff",
    },
}
```

### Body Params

| Campo                      | Tipo       | Descrição                                                                                                                                                                                                                                         | Caracteres                                |
|----------------------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|
| `device_key` * | uuidv4     | Chave única de identificação do dispositivo no formato uuid v4, adquirida atráves da **device_scan** (criada nesse momento pelo cliente integrador).                                                                                                                                                               | 36                                      | 
| `session_id` * | uuidv4     | Chave única de identificação da sessão no formato uuid v4, adquirida atráves da **device_scan** (criada nesse momento pelo cliente integrador).                                                                                                                                                               | 36                                      | 
| `tfa_info`*             | Object     | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato ou `image_key`.                                                                                                                                                                  | **[Objeto tfa_info](#objeto-tfa_info)** |

### Objeto tfa_info

| Campo                       | Tipo   | Descrição                                                                           | Caracteres |
|-----------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta.                                  | 11         | 
| `contact_type`*             | string | Indica o método de contato com a pessoa responsável pela aprovação da conta. Os valores possíveis são **sms**, **email**, ou **liveness** (quando a autenticação for realizada utilizando image_key).|            |
| `image_key` * | uuidv4     | Chave única de identificação da imagem utilizada para reconhecimento facial, no formato UUID v4, obtida por meio do processo de **liveness**.                                                                                                                                                               | 36                                      | 

## Response

STATUS 202

Response Body: Dispositivo Criado

```json
{
  "device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "device_status": "created",
  "created_at": "2024-12-22T20:30:23.459Z"
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (ptbr)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Erro de Schema                                                                                                         |
| 404                      | OBD000002            | Not Found                             | Bank account not found                                                   | Conta não encontrada                                                       |
| 400                      | OBD000088            | Bad Request                               | Account blocked or closed can not perform this action                                                                                        | A conta bloqueada ou fechada não pode executar esta ação                                                                                    |
| 400                      | OBD000089            | Bad Request                               | Hub account can not perform this action                                                                                 | A conta hub não pode executar esta ação                                                                                    |
| 403                      | OBD000090            | No approver permission | Given document number does not belong to an approver for this account string                                               | Número de documento enviado não pertence a um aprovador da conta                                              |
| 400                      | OBD000091            | tfa_info is required                                        | Client must send object tfa_info                                                                                       | Cliente deve enviar objeto tfa_info.                                                                                 |
| 400                      | OBD000092            | Invalid device info                         | Session ID and Device Key must be a valid UUID4 | A Session ID e o Device Key devem ser um UUID4 válidos |
| 404                      | OBD000093            | Requester Configuration not found                                  | There is no Requester Configuration attributed to requester_key | Não há Requester Configuration para a requester_key enviada                                                                           |
| 403                      | OBD000094            | Requester not allowed to create a device                                  | Requester has no permission to create a device                                               | Requester não possui permissão para criar um dispositivo                                                                           |
| 400                      | OBD000097            | Error occurred while sending token                                 | An unexpected error occurred while sending token                                                                                     | Um erro inexperado ocorreu ao tentar enviar token                                                                                    |

---

# Solicitar reenvio de token

URL: /documentation/baas/dispositivo/create/solicitacao_reenvio_token

Um novo token será gerado e enviado ao aprovador responsável pela criação do dispositivo (apenas nos casos de contato por email ou SMS). Caso o limite de tentativas de validação do token seja excedido, o reenvio não será permitido.

## Request

ENDPOINT /account/ ACCOUNT_KEY /device/ DEVICE_KEY /resend_token
MÉTODO PATCH

### Path Params

| Campo         | Tipo   | Descrição                              | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36         |
| `device_key` | uuidv4 | Chave única de identificação do dispositivo. | 36         |

### Body Params
| Campo         | Tipo   | Descrição                              | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `contact_type`*             | string | Indica o método de contato com a pessoa responsável pela aprovação da conta. Os valores possíveis são **sms**, **email**| **[Enumerador contact_type](#enumerador-contact_type)**  |

:::info Informação
Caso não seja enviado um `contact_type`, o token será enviado da forma solicitada originalmente.
:::

| Enumerador | Descrição                                         |
|------------|---------------------------------------------------|
| **sms**    | Envio por Mensagem de Texto para telefone celular |
| **email**  | Envio por correio eletrônico                      |

## Response

STATUS 202

Response Body: Reenvio Solicitado

```json
{
  "device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "device_status": "pending_2fa_approval",
  "created_at": "2024-12-22T20:30:23.459Z"
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (ptbr)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Erro de Schema                                                                                                         |
| 404                      | OBD000002            | Not Found                             | Bank account not found                                                   | Conta não encontrada                                                       |
| 400                      | OBD000088            | Bad Request                               | Account blocked or closed can not perform this action                                                                                        | A conta bloqueada ou fechada não pode executar esta ação                                                                                    |
| 400                      | OBD000089            | Bad Request                               | Hub account can not perform this action                                                                                 | A conta hub não pode executar esta ação                                                                                    |
| 400                      | OBD000097            | Error occurred while sending token                                 | An unexpected error occurred while sending token                                                                                     | Um erro inexperado ocorreu ao tentar enviar token                                                                                    |
| 400                      | OBD000099            | Number of token validation attempts exceeded                                 | The maximum number of failed token validation attempts has been reached                                                                                     | Número máximo de tentativas de validação de token atingida                                                    |
| 404                      | OBD000100            | Device not found                                 | No device is associated with the provided device_key.                                                                                     | Nenhum dispositivo está associado à device_key fornecida.                                             |

---

# Desativar dispositivo

URL: /documentation/baas/dispositivo/delete/desativar_dispositivo

## Request

ENDPOINT /account/ ACCOUNT_KEY /device/ DEVICE_KEY /disable
MÉTODO DELETE

### Path Params

| Campo         | Tipo   | Descrição                              | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36         |
| `device_key` | uuidv4 | Chave única de identificação do dispositivo. | 36         |

## Response

STATUS 200

Response Body: Dispositivo desativado

```json
{
  "device_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "device_status": "disabled",
  "created_at": "2024-12-22T20:30:23.459Z"
}
```

### Response Body Params

| Campo                   | Tipo   | Descrição                                                                           | Caracteres |
|-------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `device_key` *          | uuidv4 | Chave única de identificação do dispositivo no formato uuid v4                     | 36         |
| `device_status` *       | string | Status do dispositivo                                                               | **[Enumeradores device_status](#enumeradores-device_status)** |
| `created_at` *          | string | Data de criação do dispositivo no formato ISO (UTC - "YYYY-MM-DDTHH:MM:SSZ")        | 20         |

### Enumeradores device_status

| Enumerador         | Descrição                               |
|--------------------|-----------------------------------------|
| active             | Dispositivo ativo e disponível para uso |
| disabled           | Dispositivo desativado                 |
| pending            | Dispositivo pendente de aprovação       |

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (ptbr)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Erro de Schema                                                                                                         |
| 404                      | OBD000002            | Not Found                             | Bank account not found                                                   | Conta não encontrada                                                       |
| 400                      | OBD000088            | Bad Request                               | Account blocked or closed can not perform this action                                                                                        | A conta bloqueada ou fechada não pode executar esta ação                                                                                    |
| 400                      | OBD000089            | Bad Request                               | Hub account can not perform this action                                                                                 | A conta hub não pode executar esta ação                                                                                    |
| 404                      | OBD000100            | Device not found                                 | No device is associated with the provided device_key.                                                                                     | Nenhum dispositivo está associado à device_key fornecida.                                             |

---

# Introdução

URL: /documentation/baas/dispositivo/introducao

A API de Onboarding oferece a funcionalidade de Gestão de Dispositivos, permitindo que parceiros cadastrem dispositivos específicos a usuários vinculados a uma conta. Com essa funcionalidade, é possível reforçar a segurança das operações, garantindo que apenas dispositivos autorizados possam realizar transações, as quais serão validadas por meio do **token do dispositivo**.

### Cadastro de Dispositivo

O cadastro de um novo dispositivo para validação de transações é realizado por meio de um fluxo dividido em três etapas:

---

**I. Solicitação de Cadastro (POST)**  
Nesta etapa, é enviada uma requisição `POST` contendo:  
- Dados do dispositivo obtidos via `device_scan`  
- Informações necessárias para a autenticação de dois fatores(2FA)

Ao concluir a solicitação, um token 2FA é gerado e encaminhado ao usuário (por e-mail ou SMS). Esse token assegura que o cadastro está sendo realizado pela pessoa efetivamente autorizada a vincular o dispositivo.

:::info Observação
Caso a autenticação seja feita por reconhecimento facial, a **image_key** adquirida através da [liveness](/documentation/caas/face_recognition/api/introduction) deverá ser enviada no campo de 2FA.
Nesse caso, não será necessário passar pelos próximos passos de validação. 
:::

---

**II. Validação do Token 2FA (PUT/PATCH)**  
Após receber o token 2FA, o usuário deve validá-lo utilizando uma requisição `PUT`. Caso o código precise ser reenviado (por perda, não recebimento ou expiração), utiliza-se uma requisição `PATCH` para solicitar um novo token.  
Uma vez que o token seja validado com sucesso, o dispositivo será efetivamente registrado no sistema.

---

**III. Autenticação com o Token do Dispositivo em Transações Futuras**  
Com o dispositivo devidamente cadastrado, ele poderá ser utilizado na validação de transações futuras. As transações serão autenticadas utilizando o token do dispositivo, tornando o processo mais seguro e confiável.

---

### Consultar um Dispositivo

É possível consultar as informações de um dispositivo específico através de uma requisição `GET`, fornecendo a `account_key` e a `device_key`. Esta operação retorna os detalhes do dispositivo, incluindo seu status atual, data de criação e última atualização.

---

### Desativar um Dispositivo

Quando necessário, um dispositivo pode ser desativado através de uma requisição `DELETE`. Uma vez desativado, o dispositivo não poderá mais ser utilizado para validação de transações, garantindo maior controle sobre a segurança das operações.

---

# Confirmar Abertura de Conta de Pessoa Física

URL: /documentation/baas/escrow/abrir_conta_pf

A abertura de conta ocorre em duas etapas obrigatórias. Primeiro, uma requisição POST envia dados preliminares para reservar a conta. Em seguida, um webhook do tipo `account_request.status_change` com o status `pending_additional_data` é disparado. Na segunda etapa, uma requisição PATCH finaliza a abertura, oficializando a conta com as informações complementares. 

## Request
ENDPOINT /account_request/ ACCOUNT_REQUEST_KEY /escrow
MÉTODO PATCH

## Path Params
| Campo         | Tipo   | Descrição                              | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_request_key` | uuidv4 | Chave única de identificação solicitação de reserva da conta. | 36         |

## Abertura de conta Escrow

Request Body

```json
{
    "account_owner": {
        "address": {
            "street": "Av. Brigadeiro Faria Lima",
            "state": "SP",
            "city": "São Paulo",
            "neighborhood": "Jardim Paulistano",
            "number": "2391",
            "postal_code": "01452905",
            "complement": "Complemento"
        },
        "birth_date": "1990-05-06",
        "document_identification": "3884579b-9810-4fa6-9b08-fe67d237160a",
        "email": "teste@gmail.com",
        "individual_document_number": "99999999999",
        "is_pep": false,
        "mother_name": "Dona Maria Mariane",
        "name": "Nome do Titular da Conta",
        "nationality": "nationality",
        "person_type": "natural",
        "phone": {
            "country_code": "055",
            "area_code": "11",
            "number": "999999999"
        },
        "proof_of_residence": "4d7f4e-1eec-4e5f-82c0-d8c3921497ea",
        "monthly_income": 1000
    },
    "signed_contract": {
        "document_key": "48a8f4g9-4b58-4905-9a69-b1f9215263f5",
        "signatures": [
            {
                "authenticity": {
                    "timestamp": "1970-01-01T00:00:01.080100Z",
                    "facial_recognition_key":"79003de0-2590-455d-9b73-426b8ca284eb",
                    "lang": "-35.8916627",
                    "lat": "-7.2226067",
                    "ip_address": "177.51.1.186",
                    "session_id": "jdifj329842"
                },
                "signer": {
                    "name": "Nome do Titular da Conta",
                    "email": "teste@gmail.com",
                    "phone": {
                        "country_code": "055",
                        "area_code": "11",
                        "number": "999999999"
                    },
                    "document_number": "999999999"
                },
                "authentication_type": "opt-in"
            }
        ]
    },
    "destinations": [
        {
            "account_branch": "0001",
            "account_number": "1234567",
            "account_digit": "1",
            "document_number": "04252012000123",
            "name": "Conta do FIDC",
            "ispb_number": "32402502",
            "financial_institution_code_number": "329"
        }
    ],
    "additional_documents": ["b12c8807-8f3f-4083-9cb1-7cce641f3786"]
}
```

### Request Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---|---|
| `account_owner` * | object  | Objeto contendo as informações do Titular da Conta | **[Objeto account_owner](#objeto-account_owner)** |
| `signed_contract` * | object  | Objeto contendo as informações do Titular da Conta | **[Objeto signed_contract](#objeto-signed_contract)** |
| `destinations ` * | list  | Lista de contas destino autorizadas a receber transaferências. | **[Objeto destinations](#objeto-destinations)** |
| `additional_documents`  | list  | Lista de id's de documentos extras/opcionais . | Array de UUID's |

### Objeto account_owner

| Campo | Tipo | Descrição | Caracteres |
|---| ---| ---| ---| 
| `address` * | object | Endereço da pessoa titular da conta. | **[Objeto adress](#objeto-address)** |  |
| `birth_date` | string |  Data de nascimento da pessoa titular da conta(formato "AAAA-MM-DD"). | - |
| `document_identification` * | uuidv4 |  DOCUMENT_KEY do PDF do documento de identificação da pessoa titular da conta com foto (RG ou CNH) (enviado previamente) | 36 |
| `email` * | string |  Email da pessoa titular da conta. | 200 |
| `individual_document_number` | string | CPF da pessoa titular da conta (apenas números). Limitado a 11 caracteres. | 11 |
| `is_pep` * | string |  Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep).| - |
| `mother_name` | string |  Nome da mãe do cliente em caso de PF. | - |
| `name` * | string | Nome do titular da conta. | - |
| `nationality` * | string |  Nacionalidade do cliente. | - |
| `person_type` * | enumerator | Identificador de que o objeto enviado é uma pessoa física ou jurídica.| **[Enumeradores person_type](#enumeradores-person_type)**|
| `phone` * | string | Objeto com dados do telefone | **[Objeto phone](#objeto-phone)**|
| `proof_of_residence` | string |  DOCUMENT_KEY do PDF do comprovante de endereço do endereço enviado (enviado previamente).| - |
| `monthly_income`* | number | Renda mensal do titular da conta | | 

### Objeto address 

Este objeto, presente tanto no objeto PF quanto no objeto PJ, é um simples objeto para representar um endereço.

| Campo | Tipo | Descrição |  Caracteres | 
|---|---|---|---| 
| `street` *| string | Rua do endereço  | 500 |
| `state` *| string | Estado do endereço (com dois caracteres maiúsculos) | 2 |
| `city` *| string | Cidade do endereço | 255 |
| `neighborhood` *| string |Bairro do endereço | 500 |
| `number` *| string | Número da rua | 10 |
| `postal_code` *| string |CEP do endereço (http://www.buscacep.correios.com.br/sistemas/buscacep/) (apenas números) |  8 |
| `complement` *| string |Complemento do endereço (texto livre) | 500 |

### Objeto destinations

| Campo | Tipo | Descrição | Caracteres |
|---| ---| ---| ---| 
| `account_branch` * | string | Número da Agência da conta destino. | 4 | 
| `account_number` * | string |  Número da conta destino. | - |
| `account_digit` * | string |  Dígito verificador do número da conta destino. | 1 |
| `document_number` * | string |  CPF/CNPJ do titular da conta destino. | - |
| `name ` | string | Nome/Razão Social do titular da conta destino. | - |
| `ispb_number` * | string |  ISPB (base do CNPJ) da instituição financeira da conta destino.| 8 |
| `financial_institution_code_number ` * | string |  Código da instituição financeira da conta destino. | 3 |

### Objeto signed_contract 
| Campo | Tipo   | Descrição        | Caracteres    |
|-------|--------|------------------|---------------|
| **document_key** * | uuidv4 | Chave única de identificação do documento do **Termo de Abertura de Conta** ou **Contrato de Conta Escrow**. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36            |
| **signatures** *   | list   | Dados de assinatura do documento enviado. Cada item da lista, corresponde a um assinante do documento.      | [Objeto signatures](#objeto-signatures) |

### Objeto signatures
| Campo | Tipo       | Descrição         | Caracteres        |
|-------|------------|-------------------|-------------------|
| **authenticity** * | object     | Conjunto de dados que evidenciam a assinatura eletrônica realizada pelo assinante. | [Objeto authenticity](#objeto-authenticity) |
| **signer** * | object     | Objeto contendo os dados de um dos assinantes do documento.           | [Objeto signer](#objeto-signer)|
| **authentication_type** * | enumerator | Tipo de assinatura. Sempre será "**opt-in**"| "**opt-in**"                   |

### Enumeradores person_type
| Enum | Descrição         | 
|-------|-------------------|
| **natural** * | Pessoa Física     |
| **legal** * | Pessoa Jurídica     |    

### Objeto authenticity
| Campo | Tipo   | Descrição               | Caracteres |
|-------|--------|-------------------------|------------|
| **timestamp** *            | string | Data e hora do momento da assinatura do documento.                | 27         |
| **facial_recognition_key** *| uuidv4 | Chave única de identificação da foto da selfie do titular da conta.  | 36         |
| **lang**                   | string | Coordenada de longitude da geolocalização do assinante capturada no momento da assinatura.                  | -          |
| **lat**                    | string | Coordenada de latitude da geolocalização do assinante capturada no momento da assinatura.                   | -          |
| **ip_address**             | string | Endereço IP do dispositivo do assinante.     | -          |
| **session_id**     *        | string | ID da seção do assinante no momento da assinatura.                | -          |

### Objeto signer
| Campo                 | Tipo   | Descrição                                 | Caracteres                        |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** *            | string | Nome do assinante.                        | -                                 |
| **email** *           | string | Email do assinante.                       | -                                 |
| **phone** *           | object | Objeto com dados do telefone do assinante | **[Objeto phone](#objeto-phone)** |
| **document_number** * | string | CPF do assinante.                         | 11                                |

### Objeto phone 

| Campo | Descrição | Exemplo |  Máx. Caracteres | 
| --- | --- | --- | --- | 
|`country_code` *| string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 | 
| `area_code` *| string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 3 |
| `number` *| string |Número de telefone (apenas números) |  10 |

## Response

STATUS 201

Response Body

```json
{
    
    "account_key": "e48eb139-448e-43b9-9aee-df5f4b51158c"
}
```

:::warning Atenção
 O campo `account_key`  será a chave única de identificação da conta. Toda interação com a conta se dará através dela.
:::

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`  | Descrição (eng)<br/>`description` | Descrição(ptbr) <br></br>`translation`|
|---| --- | --- | --- | --- | 
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|

---

# Confirmar Abertura de Conta de Pessoa Jurídica

URL: /documentation/baas/escrow/abrir_conta_pj

A abertura de conta ocorre em duas etapas obrigatórias. Primeiro, uma requisição POST envia dados preliminares para reservar a conta. Em seguida, um webhook do tipo `account_request.status_change` com o status `pending_additional_data` é disparado. Na segunda etapa, uma requisição PATCH finaliza a abertura, oficializando a conta com as informações complementares. 

## Request
ENDPOINT /account_request/ ACCOUNT_REQUEST_KEY /escrow
MÉTODO PATCH

## Path Params
| Campo         | Tipo   | Descrição                              | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_request_key` | uuidv4 | Chave única de identificação solicitação de reserva da conta. | 36         |

## Abertura de conta Escrow

Request Body

```json
{
    "account_owner": {
        "address": {
            "city": "Caraguatatuba",
            "complement": "complemento",
            "neighborhood": "Jaraguazinho",
            "number": "924",
            "postal_code": "11675200",
            "state": "SP",
            "street": "Praça Jorge Vitório de Souza"
        },
        "cnae_code": "4721-1/02",
        "company_document_number": "64669455000187",
        "company_statute": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
        "company_type": "ltda",
        "email": "marcos.alves@yopmail.com",
        "foundation_date": "2017-09-16",
        "name": "NOME DA EMPRESA",
        "person_type": "legal",
        "phone": {
            "area_code": "19",
            "country_code": "055",
            "number": "988888888"
        },
        "trading_name": "Pães e Doces",
        "monthly_revenue": 100000,
        "company_representatives": [
            {
                "name": "Marcos Felipe Henrique Alves",
                "address": {
                    "city": "Recife",
                    "complement": null,
                    "neighborhood": "Fundão",
                    "number": "137",
                    "postal_code": "52221110",
                    "state": "PE",
                    "street": "Rua Camapuã"
                },
                "email": "marcos.alves@yopmail.com",
                "birth_date": "1972-02-02",
                "individual_document_number": "08531309069",
                "document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
                "document_identification_number": "339122924",
                "is_pep": false,
                "final_beneficiary": true,
                "marital_status": "single",
                "mother_name": "Sueli Isadora Alves",
                "nationality": "Brasileira",
                "person_type": "natural",
                "phone": {
                    "area_code": "88",
                    "country_code": "055",
                    "number": "995924634"
                }
            }
        ]
    },
    "signed_contract": {
        "document_key": "4d7f4e29-4b58-4905-9a69-b1f9215263f5",
        "signatures": [
            {
                "authenticity": {
                    "timestamp": "1970-01-01T00:00:01.080100Z",
                    "facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
                    "lang": "-35.8916627",
                    "lat": "-7.2226067",
                    "ip_address": "177.51.1.186",
                    "session_id": "jdifj329842"
                },
                "signer": {
                    "name": "IVANILDO DE SENA LIMA",
                    "email": "ivanlima2604@gmail.com",
                    "phone": {
                        "country_code": "055",
                        "area_code": "11",
                        "number": "999999999"
                    },
                    "document_number": "61766976204"
                },
                "authentication_type": "opt-in"
            }
        ]
    },
    "destinations": [
        {
            "account_branch": "0001",
            "account_number": "1234567",
            "account_digit": "1",
            "document_number": "04252012000123",
            "name": "Conta do FIDC",
            "ispb_number": "32402502",
            "financial_institution_code_number": "329"
        }
    ],
    "additional_documents": ["b12c8807-8f3f-4083-9cb1-7cce641f3786"]
}
```

### Request Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---|---|
| `account_owner` * | object  | Objeto contendo as informações do Titular da Conta | **[Objeto account_owner](#objeto-account_owner)** |
 `signed_contract` * | object  | Objeto contendo as informações do Titular da Conta | **[Objeto signed_contract](#objeto-signed_contract)** |
| `destinations ` * | list  | Lista de contas destino autorizadas a receber transaferências. | **[Objeto destinations](#objeto-destinations)** |
| `additional_documents` | list | Lista de id's de documentos extras/opcionais . | Array de UUID's |

### Objeto account_owner

| Campo | Tipo | Descrição | Caracteres |
|---| ---| ---| ---| 
| `address` * | object | Endereço do titular da conta. | **[Objeto adress](#objeto-address)** |  |
| `cnae_code` | string | Classificação Nacional de Atividades Econômicas | 9 |
| `company_document_number ` * | string |  CNPJ | 14 |
| `company_statute ` | uuidv4 | DOCUMENT_KEY do PDF do estatuto da empresa (enviado previamente). | 36 |
| `company_type` * | enumerator	 |  Tipo da empresa|   **[Enumeradores company_type](#enumeradores-company_type)**    |
| `email` * | string |  Email do titular da conta. | 200 |
| `foundation_date` | string |  Data de abertura da empresa (formato "AAAA-MM-DD"). | 10 |
| `name` * | string | Razão social do titular da conta. | 50 |
| `person_type` * | enumerator | Identificador de que o objeto enviado é uma pessoa física ou jurídica.| **[Enumeradores person_type](#enumeradores-person_type)**|
| `phone` * | object | Objeto com dados do telefone | **[Objeto phone](#objeto-phone)**|
| `trading_name ` * | string | Nome fantasia. | 200 |
| `company_representatives` | list | Lista dos representantes legais da empresa | **[Objeto company_representatives](#objeto-company_representatives)** |
| `monthly_revenue`* | number | Faturamento mensal da empresa | |

### Objeto signed_contract 
| Campo | Tipo   | Descrição        | Caracteres    |
|-------|--------|------------------|---------------|
| ` document_key` * | uuidv4 | Chave única de identificação do documento do **Termo de Abertura de Conta** ou **Contrato de Conta Escrow**. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36            |
|` signatures` *   | list   | Dados de assinatura do documento enviado. Cada item da lista, corresponde a um assinante do documento.      | [Objeto signatures](#objeto-signatures) |

### Objeto destinations

| Campo | Tipo | Descrição | Caracteres |
|---| ---| ---| ---| 
| `account_branch` * | string | Número da Agência da conta destino. | 4 | 
| `account_number` * | string |  Número da conta destino. | - |
| `account_digit` * | string |  Dígito verificador do número da conta destino. | 1 |
| `document_number` * | string |  CPF/CNPJ do titular da conta destino. | - |
| `name ` | string | Nome/Razão Social do titular da conta destino. | - |
| `ispb_number` * | string |  ISPB (base do CNPJ) da instituição financeira da conta destino.| 8 |
| `financial_institution_code_number ` * | string |  Código da instituição financeira da conta destino. | 3 |

### Objeto company_representatives

| Campo                              | Tipo    | Descrição                                                                                              | Caracteres                                                                              |
|------------------------------------|---------|--------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
| **name** *                         | string  | Nome do representante da empresa                                                                       | 100                                                                                     |
| **address** *                      | object  | Objeto endereço do representante da empresa                                                            | **[Objeto address](#objeto-address)**                                                   |
| **email** *                        | string  | Email do representante da empresa                                                                      | 254                                                                                     |
| **birth_date**                   | string  | Data de nascimento representante da empresa (formato "AAAA-MM-DD")                                     | 10                                                                                      |
| **individual_document_number** *   | string  | CPF do representante da empresa (apenas números).                                                      | 11                                                                                      |
| **document_identification**        | string  | DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) | 36                                                                                      |
| **document_identification_number** | string  | Número do documento de identificação com foto da pessoa (RG ou CNH)                                    | 16                                                                                      |
| **document_identification_type**   | enum    | Tipo do documento de identificação com foto da pessoa (RG ou CNH)                                      | [Enumeradores document_identification_type](#enumeradores-document_identification_type) |
| **is_pep** *                       | boolean | Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep).          | -                                                                                       |
| **final_beneficiary**              | boolean | Declaração se o representante é beneficiário final da empresa.                                         | -                                                                                       |
| **marital_status**                 | enum    | Estado civil do representante da empresa                                                               | **[Enumeradores marital status](#enumeradores-marital_status)**                         |
| **mother_name**                  | string  | Nome da mãe do representante da empresa                                                                | 100                                                                                     |
| **nationality**                    | string  | Nacionalidade do representante da empresa                                                              | 50                                                                                      |
| **person_type** *                  | enum    | Identificador de que o objeto enviado é uma pessoa física                                              | **[Enumeradores person_type](#enumeradores-person_type)**                               |
| **phone** * | object  | Objeto com dados do telefone do representante da empresa  | **[Objeto phone](#objeto-phone)** |

### Objeto address

Este objeto, presente tanto no objeto PF quanto no objeto PJ, é um simples objeto para representar um endereço.

| Campo              | Descrição | Exemplo                                                                                   | Caracteres |
|--------------------|-----------|-------------------------------------------------------------------------------------------|------------|
| **street** *       | string    | Rua do endereço                                                                           | 500        |
| **state** *        | enum      | Estado do endereço (com dois caracteres maiúsculos)                                       | 2          |
| **city** *         | string    | Cidade do endereço                                                                        | 255        |
| **neighborhood** * | string    | Bairro do endereço                                                                        | 500        |
| **number** *       | string    | Número da rua                                                                             | 10         |
| **postal_code** *  | string    | CEP do endereço (http://www.buscacep.correios.com.br/sistemas/buscacep/) (apenas números) | 8          |
| **complement**     | string    | Complemento do endereço (texto livre)                                                     | 500        |

### Objeto signed_contract 
| Campo | Tipo   | Descrição        | Caracteres    |
|-------|--------|------------------|---------------|
| **document_key** * | uuidv4 | Chave única de identificação do documento do **Termo de Abertura de Conta** ou **Contrato de Conta Escrow**. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36            |
| **signatures** *   | list   | Dados de assinatura do documento enviado. Cada item da lista, corresponde a um assinante do documento.      | [Objeto signatures](#objeto-signatures) |

### Objeto signatures
| Campo | Tipo       | Descrição         | Caracteres        |
|-------|------------|-------------------|-------------------|
| **authenticity** * | object     | Conjunto de dados que evidenciam a assinatura eletrônica realizada pelo assinante. | [Objeto authenticity](#objeto-authenticity) |
| **signer** * | object     | Objeto contendo os dados de um dos assinantes do documento.           | [Objeto signer](#objeto-signer)|
| **authentication_type** * | enumerator | Tipo de assinatura. Sempre será "**opt-in**"| "**opt-in**"                   |

### Objeto authenticity
| Campo | Tipo   | Descrição               | Caracteres |
|-------|--------|-------------------------|------------|
| **timestamp** *            | string | Data e hora do momento da assinatura do documento.                | 27         |
| **facial_recognition_key** *| uuidv4 | Chave única de identificação da foto da selfie do titular da conta.| 36         |
| **lang**                   | string | Coordenada de longitude da geolocalização do assinante capturada no momento da assinatura.                  | -          |
| **lat**                    | string | Coordenada de latitude da geolocalização do assinante capturada no momento da assinatura.                   | -          |
| **ip_address**             | string | Endereço IP do dispositivo do assinante.     | -          |
| **session_id**  *           | string | ID da seção do assinante no momento da assinatura.                | -          |

### Objeto signer
| Campo                 | Tipo   | Descrição                                 | Caracteres                        |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** *            | string | Nome do assinante.                        | -                                 |
| **email** *           | string | Email do assinante.                       | -                                 |
| **phone** *           | object | Objeto com dados do telefone do assinante | **[Objeto phone](#objeto-phone)** |
| **document_number** * | string | CPF do assinante.                         | 11                                |

### Objeto phone 

| Campo | Descrição | Exemplo |  Máx. Caracteres | 
| --- | --- | --- | --- | 
|`country_code` *| string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 | 
| `area_code` *| string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |Número de telefone (apenas números) |  10 |

### Enumeradores person_type
| Enum        | Description       |
|-------------|-------------------|
| **natural** | Pessoa física     |
| **legal**   | Pessoa jurídica   |

### Enumeradores document_identification_type
| Enum    | Description                            |
|---------|----------------------------------------|
| **rg**  | RG - Registro Geral                    |
| **cnh** | CNH - Carteira Nacional de Habilitação |

### Enumeradores company_type
| Enum                       | 	Description                                                             |
|----------------------------|--------------------------------------------------------------------------|
| **ltda**                   | Limitada                                                                |
| **sa**	                    | Sociedade Anônima                                                        |
| **micro_enterprise**	      | Micro Empresa                                                            |
| **freelancer**             | Freelancer                                                              |
| **sa_opened**              | Sociedade Anônima de Capital Aberto                                     |
| **sa_closed**	             | Sociedade Anônima de Capital Fechado                                     |
| **se_ltda**                | Sociedade Empresária Limitada                                           |
| **se_cn**                  | Sociedade Empresária em Nome Coletivo                                   |
| **se_cs**                  | Sociedade Empresária em Comandita Simples                               |
| **se_ca**	                 | Sociedade Empresária em Comandita por Ações                              |
| **scp**                    | Sociedade em Conta de Participação                                      |
| **ei**	                    | Empresário Individual                                                    |
| **ese**	                   | Estabelecimento, no Brasil, de Sociedade Estrangeira                     |
| **eeab**	                  | Estabelecimento, no Brasil, de Empresa Binacional Argentino-Brasileira   |
| **ssp**                    | Sociedade Simples Pura                                                  |
| **ss_ltda**	               | Sociedade Simples Limitada                                               |
| **ss_cn**                  | Sociedade Simples em Nome Coletivo                                      |
| **ss_cs**                  | Sociedade Simples em Comandita Simples                                  |
| **eireli_ne**              | Empresa Individual de Responsabilidade Limitada (de Natureza Empresária) |
| **eireli_ns**              | Empresa Individual de Responsabilidade Limitada (de Natureza Simples)   |
| **eireli**                 | Empresa de Responsabilidade Individual                                  |
| **mei**                    | Micro Empreendedor Individual                                            |
| **me**	                    | Micro Empresa                                                            |
| **cop**	                   | Cooperativa                                                              |
| **private_association**	   | Sociedade Privada        
| **association**	   | Associação                                                   |
| **others**	   | Outros  |

### Enumeradores marital_status
| Enum         | 	Description  |
|--------------|---------------|
| **single**   | Solteiro(a)   |
| **married**  | Casado(a)    |
| **widower**  | Viúvo(a)     |
| **divorced** | Divorciado(a) |
| **separated** | Separado(a) |

## Response

STATUS 201

Response Body

```json
{
    "account_key": "e48eb139-448e-43b9-9aee-df5f4b51158c"
}
```

:::warning Atenção
 A `account_key`  será a chave única de identificação da conta. Toda interação com a conta se dará através dela.

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`  | Descrição (eng)<br/>`description` | Descrição(ptbr) <br></br>`translation`|
|---| --- | --- | --- | --- | 
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|

---

# Abertura de Conta de Pessoa Física

URL: /documentation/baas/escrow/reservar_conta_pf

A abertura de conta ocorre em duas etapas obrigatórias. Primeiro, uma requisição POST envia dados preliminares para reservar a conta. Em seguida, um webhook do tipo `account_request.status_change` com o status `pending_additional_data` é disparado. Na segunda etapa, uma requisição PATCH finaliza a abertura, oficializando a conta com as informações complementares. 

## Solicitar Reserva de Conta

## Request 
ENDPOINT /account_request/escrow
MÉTODO POST

Request Body

```json
{
    "account_owner": {
        "document_number": "64669455000187",
        "email": "marcos.alves@yopmail.com",
        "birthdate": "2017-09-16",
        "name": "NOME",
        "documents": {
            "rg": {
                "ocr_front_key": "9d6fefc0-77c9-4acc-8526-53523ff155b9",
                "ocr_back_key": "30157d15-3b93-46ad-9c94-cd8bd533f9ed"
            },
            "cnh": {
                "ocr_key": "f30cea56-dd66-415b-9a28-746f7330b708"
            }
        },
        "face": "dbdaf3c9-cdf6-4737-8551-92910b213b7e"
    }
}
```

:::info Mock de CPF/CNPJ
Para simular situações de aprovação, reprovação e analise manual pode ser utilizado o primeiro digito do CPF/CNPJ do owner da conta:

0 à 6 -> Análise Manual

7 -> Rejeitado pelo bacen protege+

8 -> Reprovado automaticamente no KYC

9 -> Aprovação Automática
:::

### Request Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---|---|
| `account_owner` * | object  | Objeto contendo as informações do Titular da Conta | **[Objeto account_owner](#objeto-account_owner)** |

### Objeto account_owner
| Campo | Tipo | Descrição | Caracteres |
|--- | --- | --- | --- |
| `document_number` * | string  | CPF do Titular da Conta | 11 |
| `email` * | string  | E-mail do Titular da Conta | 200 |
| `birthdate` | string  | 	Data de nascimento. (formato YYYY-MM-DD) | 10 |
| `name` * | string  | Nome do Titular da Conta | 50 |
| `documents` *| object  | Documento(s) do titular da conta | **[Objeto documents](#objeto-documents)** |
| `face` *     | uuidv4  | Chave do reconhecimento facial feito junto ao antifraude (`face_recognition_key`) | 36 |

### Objeto documents

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `rg`                           | object      | Chaves OCR (OCR keys) do upload da frente e verso do RG do titular | **[Objeto rg](#objeto-rg)**   |
| `cnh`                          | object      | Chave OCR do upload da CNH do titular                              | **[Objeto cnh](#objeto-cnh)** |
| `cnh_digital`                     | object      | Chave OCR do upload da CNH digital do titular                       | **[Objeto cnh_digital](#objeto-cnh_digital)** |
| `national_registry_of_foreigners` | object   | Chaves OCR (OCR keys) do upload da frente e verso do RNE do titular| **[Objeto national_registry_of_foreigners](#objeto-national_registry_of_foreigners)** |
| `national_migration_registry` | object   | Chaves OCR (OCR keys) do upload da frente e verso do CRNM do titular| **[Objeto national_migration_registry](#objeto-national_migration_registry)** |
| `passport`                     | object      | Chave OCR do upload do passaporte do titular                       | **[Objeto passport](#objeto-passport)** |
| `cin_digital`                     | object      | Chave OCR do upload da Cédula de Identidade Nacional digital do titular                       | **[Objeto cin_digital](#objeto-cin_digital)** |

:::info Informação
As chaves OCR (`ocr_key` ou `ocr_front_key` e `ocr_back_key`) do upload das imagens dos documentos são fornecidos como resposta do upload das imagens no antifraude. A `face_recognition_key` é retornada na resposta do reconhecimento facial.
:::

### Objeto rg

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | Chave OCR do upload da imagem da frente do RG                      | 36                            |
| `ocr_back_key` *               | uuidv4      | Chave OCR do upload da imagem do verso do RG                       | 36                            |

OU

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | Chave OCR do upload da imagem do RG                                | 36                       |

### Objeto cnh

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | Chave OCR do upload da imagem da frente da CNH                     | 36                            |
| `ocr_back_key` *               | uuidv4      | Chave OCR do upload da imagem do verso da CNH                      | 36                            |

OU

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | Chave OCR do upload da imagem da CNH                               | 36                            |

### Objeto cnh_digital

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | Chave OCR do upload da imagem da CNH digital                               | 36                            |

### Objeto national_registry_of_foreigners

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | Chave OCR do upload da imagem da frente do RNE                     | 36                            |
| `ocr_back_key` *               | uuidv4      | Chave OCR do upload da imagem do verso do RNE                      | 36                            |

OU

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | Chave OCR do upload da imagem do RNE                               | 36                            |

### Objeto national_migration_registry

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | Chave OCR do upload da imagem da frente do CRNM                     | 36                            |
| `ocr_back_key` *               | uuidv4      | Chave OCR do upload da imagem do verso do CRNM                      | 36                            |

OU

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | Chave OCR do upload da imagem do CRNM                               | 36                            |

### Objeto passport

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | Chave OCR do upload da imagem do passaporte                               | 36                            |

### Objeto cin_digital

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | Chave OCR do upload da imagem da Cédula de Identidade Nacional digital                               | 36                            |

## Response

STATUS 201

Response Body

```json
{
    "account_info": {
        "account_branch": "0001",
        "account_digit": "0",
        "account_number": "1693580"
    },
    "account_request_key": "f230f1b5-07af-4737-b0e3-8a472304f5e7",
    "account_request_status": "pending_bacen_validation"
}
```

:::info Fluxo Bacen Protege+
A proposta começa com status `pending_bacen_validation`. O sistema realiza uma validação prévia junto ao Bacen Protege+ antes de prosseguir com a análise de KYC. Após aprovação do Bacen, o status será atualizado para `pending_kyc_analysis` automaticamente.
:::

:::warning Atenção
 O campo `account_request_key` deve ser armazenado e será utilizado para a confirmação da abertura da conta.
:::

### Response Body Params

| Campo | Tipo | Descrição | Caracteres|
|---|---| ---|---|
| `account_info` * | object  | Objeto contendo as informações do Titular da Conta |**[Objeto account_info](#objeto-account_info)**  | - |
| `account_request_key` * | string  | Chave de identificação da requisição de criação | - | - |
| `account_request_status` * | string  | Status de KYC | - | - |

### Objeto account_info
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| --- |
| `account_branch` * | string  | Número da Agência | 4 |
| `account_digit` * | string  | Dígito da Conta | 11 |
| `account_number` * | string  | Número da Conta | 50 |

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`  | Descrição (eng)<br/>`description` | Descrição(ptbr) <br></br>`translation`|
|---| --- | --- | --- | --- | 
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|

---

# Abertura de Conta de Pessoa Jurídica

URL: /documentation/baas/escrow/reservar_conta_pj

A abertura de conta ocorre em duas etapas obrigatórias. Primeiro, uma requisição POST envia dados preliminares para reservar a conta. Em seguida, um webhook do tipo `account_request.status_change` com o status `pending_additional_data` é disparado. Na segunda etapa, uma requisição PATCH finaliza a abertura, oficializando a conta com as informações complementares. 

## Solicitar Reserva de Conta

## Request
ENDPOINT /account_request/escrow
MÉTODO POST

Request Body

```json
{
    "account_owner": {
        "company_document_number": "99999999999",
        "email": "email@teste.com",
        "foundation_date": "2017-09-16",
        "name": "Nome da Empresa"
    },
    "legal_representatives": [
        {
            "birthdate": "1963-07-23",
            "name": "Don Corleone",
            "document_number": "03912394323",
            "documents": {
                "national_registry_of_foreigners": {
                    "ocr_front_key": "0aa8a4ca-5873-49bd-851c-1f2c71a1cc28",
                    "ocr_back_key": "29f6e346-7fae-4dcb-9ea1-2a3e4ef593ea"
                }
            },
            "face": "68da08f1-6cf4-4dce-a297-7b2f09311784"
        },
        {
            "birthdate": "1996-03-10",
            "name": "John Doe",
            "document_number": "39113492093",
            "documents": {
                "cnh": {
                    "ocr_key": "beee557e-9240-4c5b-88f1-42812b195168"
                }
            }
        }
    ]
}
```

:::info Mock de CPF/CNPJ
Para simular situações de aprovação, reprovação e analise manual pode ser utilizado o primeiro digito do CPF/CNPJ do owner da conta:

0 à 6 -> Análise Manual

7 -> Rejeitado pelo bacen protege+

8 -> Reprovado automaticamente no KYC

9 -> Aprovação Automática
:::

### Request Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---|---|
| `account_owner` * | object  | Objeto contendo as informações do Titular da Conta | **[Objeto account_owner](#objeto-account_owner)** |
| `legal_representatives` | object array | Lista de representantes da conta e seus dados | **[Objeto legal_representative](#objeto-legal_representative)** |

### Objeto account_owner
| Campo | Tipo | Descrição | Caracteres |
|--- | --- | --- | --- |
| `"company_document_number"` * | string  | CNPJ do Titular da Conta | 14 |
| `email` * | string  | Email da empresa titular do contrato | 200 |
| `foundation_date` | string  | Data de abertura da empresa (formato YYYY-MM-DD) | 10 |
| `name` * | string  | Razão Social | 50 |

### Objeto legal_representative

| Campo | Tipo | Descrição | Caracteres |
|--- | --- | --- | --- |
| `document_number` * | string  | CPF do Titular da Conta | 11 |
| `birthdate` | string  | 	Data de nascimento. (formato YYYY-MM-DD) | 10 |
| `name` * | string  | Nome do Titular da Conta | 50 |
| `documents` * | object  | Documento(s) do titular da conta | **[Objeto documents](#objeto-documents)** |
| `face`      | uuidv4  | Chave do reconhecimento facial feito junto ao antifraude (`face_recognition_key`) | 36 |

### Objeto documents

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `rg`                           | object      | Chaves OCR (OCR keys) do upload da frente e verso do RG do titular | **[Objeto rg](#objeto-rg)**   |
| `cnh`                          | object      | Chave OCR do upload da CNH do titular                              | **[Objeto cnh](#objeto-cnh)** |
| `cnh_digital`                     | object      | Chave OCR do upload da CNH digital do titular                       | **[Objeto cnh_digital](#objeto-cnh_digital)** |
| `national_registry_of_foreigners` | object   | Chaves OCR (OCR keys) do upload da frente e verso do RNE do titular| **[Objeto national_registry_of_foreigners](#objeto-national_registry_of_foreigners)** |
| `national_migration_registry` | object   | Chaves OCR (OCR keys) do upload da frente e verso do CRNM do titular| **[Objeto national_migration_registry](#objeto-national_migration_registry)** |
| `passport`                     | object      | Chave OCR do upload do passaporte do titular                       | **[Objeto passport](#objeto-passport)** |
| `cin_digital`                     | object      | Chave OCR do upload da Cédula de Identidade Nacional digital do titular                       | **[Objeto cin_digital](#objeto-cin_digital)** |

:::info Informação
As chaves OCR (`ocr_key` ou `ocr_front_key` e `ocr_back_key`) do upload das imagens dos documentos são fornecidos como resposta do upload das imagens no antifraude. A `face_recognition_key` é retornada na resposta do reconhecimento facial.
:::

### Objeto rg

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | Chave OCR do upload da imagem da frente do RG                      | 36                            |
| `ocr_back_key` *               | uuidv4      | Chave OCR do upload da imagem do verso do RG                       | 36                            |

OU

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | Chave OCR do upload da imagem do RG                                | 36                       |

### Objeto cnh

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | Chave OCR do upload da imagem da frente da CNH                     | 36                            |
| `ocr_back_key` *               | uuidv4      | Chave OCR do upload da imagem do verso da CNH                      | 36                            |

OU

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | Chave OCR do upload da imagem da CNH                               | 36                            |

### Objeto cnh_digital

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | Chave OCR do upload da imagem da CNH digital                               | 36                            |

### Objeto national_registry_of_foreigners

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | Chave OCR do upload da imagem da frente do RNE                     | 36                            |
| `ocr_back_key` *               | uuidv4      | Chave OCR do upload da imagem do verso do RNE                      | 36                            |

OU

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | Chave OCR do upload da imagem do RNE                               | 36                            |

### Objeto national_migration_registry

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_front_key` *              | uuidv4      | Chave OCR do upload da imagem da frente do CRNM                     | 36                            |
| `ocr_back_key` *               | uuidv4      | Chave OCR do upload da imagem do verso do CRNM                      | 36                            |

OU

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | Chave OCR do upload da imagem do CRNM                               | 36                            |

### Objeto passport

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | Chave OCR do upload da imagem do passaporte                               | 36                            |

### Objeto cin_digital

| Campo                          | Tipo        | Descrição                                                          | Caracteres                    |
|--------------------------------|-------------|--------------------------------------------------------------------|-------------------------------|
| `ocr_key` *                    | uuidv4      | Chave OCR do upload da imagem da Cédula de Identidade Nacional digital                               | 36                            |

## Response

STATUS 201

Response Body

```json
{
    "account_info": {
        "account_branch": "0001",
        "account_digit": "0",
        "account_number": "1693580"
    },
    "account_request_key": "f230f1b5-07af-4737-b0e3-8a472304f5e7",
    "account_request_status": "pending_bacen_validation"
}
```

:::info Fluxo Bacen Protege+
A proposta começa com status `pending_bacen_validation`. O sistema realiza uma validação prévia junto ao Bacen Protege+ antes de prosseguir com a análise de KYC. Após aprovação do Bacen, o status será atualizado para `pending_kyc_analysis` automaticamente.
:::

:::warning Atenção
 O campo `account_request_key` deve ser armazenado e será utilizado para a confirmação da abertura da conta.
:::

### Response Body Params

| Campo | Tipo | Descrição | Caracteres|
|---|---| ---|---|
| `account_info` * | object  | Objeto contendo as informações do Titular da Conta |**[Objeto account_info](#objeto-account_info)**  | - |
| `account_request_key` * | string  | Chave de identificação da requisição de criação | - | - |
| `account_request_status` * | string  | Status de KYC | - | - |

### Objeto account_info
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| --- |
| `account_branch` * | string  | Número da Agência | 4 |
| `account_digit` * | string  | Dígito da Conta | 11 |
| `account_number` * | string  | Número da Conta | 50 |

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`  | Descrição (eng)<br/>`description` | Descrição(ptbr) <br></br>`translation`|
|---| --- | --- | --- | --- | 
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|

---

# Webhooks de abertura de conta

URL: /documentation/baas/escrow/webhooks

Após a chamada de solicitação de reserva de conta de conta é enviado um webhook do tipo account_request.status_change com o status pending_additional_data, esse evento é o gatilho para que seja enviada a requisição para confirmação da abertura de conta.

A resposta da solicitação de abertura de conta poderá retornar o status “pending_kyc_analysis” a depender da configuração de integração do parceiro.

Neste caso, a resposta sobre a aprovação ou reprovação da abertura da conta será retornada de forma assíncrona via webhook.

O número de conta será reservado no momento da solicitação de abertura, porém neste momento **a conta ainda não estará aberta**. Somente após a conclusão da análise de KYC da QI Tech a conta estará aberta.

## Webhook Pending KYC Analysis

Após a aprovação do Bacen Protege+, o status da solicitação de abertura de conta é atualizado para `pending_kyc_analysis` e um webhook é enviado para notificar o parceiro.

WEBHOOK_TYPE account_request.status_change
STATUS pending_kyc_analysis

Webhook Body

```json
{
    "data": {
        "account_info": {
            "account_digit": "3",
            "account_branch": "0001",
            "account_number": "1638634"
        },
        "account_request_key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
        "status": "pending_kyc_analysis"
    },
    "event_datetime": "2022-09-02 22:39:39",
    "key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
    "status": "pending_kyc_analysis",
    "webhook_type": "account_request.status_change"
}
```

## Webhook aprovação KYC

Webhook Body

```json
{
    "data": {
        "account_info": {
            "account_digit": "3",
            "account_branch": "0001",
            "account_number": "1638634"
        },
        "account_request_key": "dc575950-dcce-48e1-99a6-5fb0ada63d86"
    },
    "event_datetime": "2022-09-02 22:39:39",
    "key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
    "status": "pending_additional_data",
    "webhook_type": "account_request.status_change"
}
```

### Enumeradores account_request_status
| Enum                        | Description                     |
|-----------------------------|---------------------------------|
| **pending_kyc_analysis**    | Pendente aprovação KYC          |
| **pending_additional_data** | Pendente informações adicionais |
| **rejected**                | Abertura rejeitada              |

## Contas de Pessoa Jurídica

# Account Rejected

WEBHOOK_TYPE account
STATUS account_rejected

Webhook Body

```json
{
	"data": {
		"account_info": {
			"account_digit": "2",
			"account_branch": "0001",
			"account_number": "2359934",
			"financial_institution_code": "329"
		},
		"allowed_user": {
			"name": "Juliana Tereza Bernardes",
			"document_number": "97564480084"
		},
		"account_owner": {
			"name": "VOVO LUCIA CONVENIENCIA LTDA",
			"document_number": "09080702000105"
		}
	},
	"event_datetime": "2022-09-02 22:39:39",
	"key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
	"status": "account_rejected",
	"webhook_type": "account"
}
```

## Contas de Pessoa Física

# Account Rejected

WEBHOOK_TYPE account
STATUS account_rejected

Webhook Body

```json
{
    "key":"84864614-2860-4b78-bd44-77b961354014",
  	"data":{
        "account_info":{
            "account_key":"1435dbavf-2860-4b78-bd44-77b961354014",
            "account_digit":"5",
            "account_branch":"0001",
            "account_number":"3998360",
            "financial_institution_code":"329"
        },
        "account_owner":{
            "name":"Pedro Pinho",
            "document_number":"97634408077"
        }
      },
    "status":"account_rejected",
    "webhook_type":"account",
    "event_datetime":"2024-01-09 14:35:46"
}
```

---

# baas_consulta_de_instituicoes_financeiras

URL: /documentation/baas/lista_de_instituicoes_financeiras/baas_consulta_de_instituicoes_financeiras



---

# baas_configuracao_de_notificacao

URL: /documentation/baas/notificacoes/baas_configuracao_de_notificacao



---

# baas_configuracao_template

URL: /documentation/baas/notificacoes/baas_configuracao_template



---

# baas_introducao

URL: /documentation/baas/notificacoes/baas_introducao



---

# baas_reenvio_de_notificacoes

URL: /documentation/baas/notificacoes/baas_reenvio_de_notificacoes



---

# baas_template

URL: /documentation/baas/notificacoes/baas_template



---

# baas_tipos_de_evento

URL: /documentation/baas/notificacoes/baas_tipos_de_evento



---

# Upload de arquivo remessa (CNAB)

URL: /documentation/baas/pagamento_em_lote/envio_de_remessa

:::caution Atenção!
A chamada deve ser autenticada seguindo o padrão descrito na seção de [**Upload de documentos**](/documentation/upload_de_documentos).
:::

## Request

ENDPOINT /payments/account/ ACCOUNT_KEY /remittance
MÉTODO POST

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |

## Request Body Params

Deverão ser enviados os seguintes dados, como form-data , no body da request:

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `file` *                | file   | Arquivo CNAB no padrão estipulado pela QI Tech               | -          |

## Response

STATUS 202

Response Body
```json
{
  "cnab_remittance_key": "f14e9bac-94ed-4eb1-87b4-7fd7b7a2d280",
  "cnab_remittance_status": "accepted"
}
```

### Response Body Params

| Campo                          | Tipo    | Descrição                                                       | Caracteres                 |
|--------------------------------|---------|-----------------------------------------------------------------|----------------------------|
| `cnab_remittance_key` *    | uuidv4  | Chave única de identificação do arquivo CNAB no formato uuid v4 | 36                         |
| `cnab_remittance_status` * | string  | Status do arquivo CNAB | **[Enumeradores cnab_remittance_status](#enumeradores-cnab_file_status)** |

### Enumeradores cnab_remittance_status

| Enumerador | Descrição                                                                 |
|------------|---------------------------------------------------------------------------|
| uploaded   | Upload feito com sucesso, mas arquivo ainda não começou a ser processado  |
| processing | Arquivo sendo lido                                                        |
| accepted   | Arquivo lido e aceito                                                     |
| rejected   | Arquivo lido e rejeitado (todas as ocorrências do arquivo são rejeitadas) |

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (ptbr)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 409                      | PAP000002            | Conflict                                  | CNAB file alredy received                                                                                | Arquivo CNAB já recebido                                                                         |
| 400                      | PAP000003            | Bad Request                                  | Invalid file name '`<file_name>`' . Please do not use specials characters like '!', '@', '(', ')', '$'.                                                                                      | Nome de arquivo invalido '`<file_name>`'. Favor não utilizar caracteres especiais como '!', '@', '(', ')', '$'."                                                                                   |
| 403                      | PAP000004            | Forbidden         |    Usuario não tem autorização para fazer essa ação                                                                 | User is not allowed to do this action
| 404                      | PAP000005            | Not Found | The source account key was not found         |               A chave da conta de origem não foi encontrada                                                              |

---

# Introdução a Transação em Lote CNAB240

URL: /documentation/baas/pagamento_em_lote/introducao

A QI Tech, através da API Payments, permite a realização de pagamentos utilizando o formato CNAB240, suportando diferentes tipos de transações, como boletos, PIX e TED, em uma única chamada. Esse sistema possibilita a execução de pagamentos em lote, garantindo maior eficiência para processos financeiros de alto volume.

Os pagamentos são processados de forma assíncrona, com validações rigorosas durante a submissão do arquivo CNAB240. Caso a solicitação inicial resulte em um HTTP status 4xx, nenhum pagamento será processado.

Após a submissão, o arquivo pode ser aprovado ou rejeitado. Caso seja rejeitado, a API retornará uma lista detalhada de erros relacionados à formatação do arquivo, permitindo que o integrador realize as correções necessárias antes de uma nova tentativa de envio. O arquivo será rejeitado caso seja encontrado qualquer erro sintático. No entanto, ele é lido integralmente, ou até que sejam encontrados um limite de 100 erros, para que todos os erros possam ser retornados e corrigidos de maneira mais prática e eficiente.

Enquanto o arquivo é lido, as ocorrências são adicionadas a uma fila, mas só serão processadas caso ele seja aceito. Ou seja, se o arquivo for rejeitado (status rejected), todas as suas ocorrências também serão descartadas. Por outro lado, no momento em que o arquivo é totalmente lido e aceito (status accepted), inicia-se o processamento dessas ocorrências, assegurando a continuidade das transações com base nos dados fornecidos.

---

# Consultar Dados de um Lote de Pagamentos por conta

URL: /documentation/baas/pix_automatico/conciliacao/consultar_lote_por_conta

## Request

ENDPOINT /account/ ACCOUNT_KEY /payment_order_conciliation_batch/ PAYMENT_ORDER_CONCILIATION_BATCH_KEY
MÉTODO GET

### Path Params

| Campo                    | Tipo   | Descrição                                         | Caracteres |
|--------------------------|--------|---------------------------------------------------|------------|
| **`ACCOUNT_KEY`** *          | uuidv4 | Chave única de identificação da conta.            | 36         |
| **`PAYMENT_ORDER_CONCILIATION_BATCH_KEY`***| uuidv4 | Chave única de identificação do lote.      | 36         |

## Response

STATUS 200

Response Body

```json
{
  "payment_order_conciliation_batch_status": "open",
  "payment_order_conciliation_batch_type": "fixed_amount",
  "total_amount": 1000.00,
  "conciliated_amount": 500.00,
  "total_payment_orders": 10,
  "conciliated_payment_orders": 5,
  "reference_date": "2025-06-13",
  "created_at": "2025-06-10T20:30:23.459Z"
}
```

### Response Body Params

| Campo                                    | Tipo       | Descrição                                                      | Caracteres |
|------------------------------------------|------------|----------------------------------------------------------------|------------|
| `payment_order_conciliation_batch_status`| enumerator | Status do lote de conciliação de ordens de pagamento.          | [Enumeradores payment_order_conciliation_batch_status](#enumeradores-payment_order_conciliation_batch_status) |
| `payment_order_conciliation_batch_type`  | enumerator | Tipo do lote de conciliação de ordens de pagamento.           | [Enumeradores payment_order_conciliation_batch_type](#enumeradores-payment_order_conciliation_batch_type) |
| `total_amount`                           | number     | Valor total do lote de conciliação em reais (R$).              | -          |
| `conciliated_amount`                     | number     | Valor já conciliado do lote em reais (R$).                     | -          |
| `total_payment_orders`                   | integer    | Número total de ordens de pagamento no lote.                   | -          |
| `conciliated_payment_orders`             | integer    | Número de ordens de pagamento já conciliadas no lote.          | -          |
| `reference_date`                         | string     | Data de referência do lote (formato ISO 8601, e.g., "2025-06-13"). | 10         |
| `created_at`                             | string     | Data e hora de criação do lote (formato ISO 8601).             | -          |

### Enumeradores payment_order_conciliation_batch_status

| Enumerador   | Descrição                                   |
|--------------|---------------------------------------------|
| `open`       | Lote de conciliação aberto                 |
| `closed`     | Lote de conciliação fechado                |
| `processing` | Lote de conciliação em processamento       |
| `completed`  | Lote de conciliação concluído              |
| `cancelled`  | Lote de conciliação cancelado              |

### Enumeradores payment_order_conciliation_batch_type

| Enumerador        | Descrição                                   |
|-------------------|---------------------------------------------|
| `fixed_amount`    | Lote de conciliação de valor fixo          |
| `variable_amount` | Lote de conciliação de valor variável      |

STATUS 4XX

Response Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em português",
  "code": "codigo"
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                | Descrição (eng)<br/>`description`                                          | Descrição (ptbr)<br/>`translation`                                 |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400         | QIT000002            | Bad Request                       | Invalid request schema.                                                    | Erro no esquema da requisição.                                     |
| 404         | APX000003            | Conciliation Batch Not Found      | Conciliation batch \{conciliation_batch_key\} not found.                   | Lote de conciliação \{conciliation_batch_key\} não encontrado.      |

---

# Consultar Lotes de Pagamentos por Requester

URL: /documentation/baas/pix_automatico/conciliacao/consultar_lote_requester

## Request

ENDPOINT /payment_order_conciliation_batches
MÉTODO GET

### Query Params

| Campo                                    | Tipo       | Descrição                                                      | Obrigatório |
|------------------------------------------|------------|----------------------------------------------------------------|-------------|
| `payment_order_conciliation_batch_status`| enumerator | Filtro por status do lote de conciliação.                     | Não         |
| `payment_order_conciliation_batch_type`  | enumerator | Filtro por tipo do lote de conciliação.                       | Não         |
| `page`                                   | integer    | Número da página para paginação (padrão: 1).                  | Não         |
| `page_size`                              | integer    | Tamanho da página para paginação (padrão: 25).                | Não         |
| `from_date`                              | string     | Data inicial para filtro (formato ISO 8601, e.g., "2025-06-01"). | Não         |
| `to_date`                                | string     | Data final para filtro (formato ISO 8601, e.g., "2025-06-30").   | Não         |

## Response

STATUS 200

Response Body

```json
{
    "payment_order_conciliation_batches": [
        {
            "payment_order_conciliation_batch_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
            "payment_order_conciliation_batch_status": "closed",
            "payment_order_conciliation_batch_type": "fixed_amount",
            "account_key": "9b9ae7b0-7292-4b0d-9131-0167525ab067",
            "total_amount": 1200,
            "conciliated_amount": 1200,
            "total_payment_orders": 12,
            "conciliated_payment_orders": 12,
            "reference_date": "2025-06-13",
            "created_at": "2025-06-10T20:30:23.459Z"
        },
        {
            "payment_order_conciliation_batch_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
            "payment_order_conciliation_batch_status": "closed",
            "payment_order_conciliation_batch_type": "variable_amount",
            "account_key": "9b9ae7b0-7292-4b0d-9131-0167525ab067",
            "total_amount": 700,
            "conciliated_amount": 600,
            "total_payment_orders": 7,
            "conciliated_payment_orders": 6,
            "reference_date": "2025-06-13",
            "created_at": "2025-06-10T20:30:23.459Z"
        },
        {
            "payment_order_conciliation_batch_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
            "payment_order_conciliation_batch_status": "open",
            "payment_order_conciliation_batch_type": "variable_amount",
            "account_key": "9b9ae7b0-7292-4b0d-9131-0167525ab067",
            "total_amount": 900,
            "conciliated_amount": 700,
            "total_payment_orders": 9,
            "conciliated_payment_orders": 7,
            "reference_date": "2025-06-17",
            "created_at": "2025-06-10T20:30:23.459Z"
        },
        {
            "payment_order_conciliation_batch_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
            "payment_order_conciliation_batch_status": "closed",
            "payment_order_conciliation_batch_type": "fixed_amount",
            "account_key": "c24a0ac4-792c-494e-b887-6185e07a33a3",
            "total_amount": 800,
            "conciliated_amount": 800,
            "total_payment_orders": 8,
            "conciliated_payment_orders": 8,
            "reference_date": "2025-06-13",
            "created_at": "2025-06-10T20:30:23.459Z"
        },
        {
            "payment_order_conciliation_batch_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
            "payment_order_conciliation_batch_status": "open",
            "payment_order_conciliation_batch_type": "variable_amount",
            "account_key": "c24a0ac4-792c-494e-b887-6185e07a33a3",
            "total_amount": 1000,
            "conciliated_amount": 500,
            "total_payment_orders": 10,
            "conciliated_payment_orders": 5,
            "reference_date": "2025-06-17",
            "created_at": "2025-06-10T20:30:23.459Z"
        }
    ],
    "pagination": {
        "page": 1,
        "page_size": 25,
        "number_of_pages": 1
    }
}
```

### Response Body Params

| Campo                                | Tipo  | Descrição                                                    | Caracteres |
|--------------------------------------|-------|--------------------------------------------------------------|------------|
| `payment_order_conciliation_batches` | array | Lista de lotes de conciliação de ordens de pagamento.       | [Array payment_order_conciliation_batches](#array-payment_order_conciliation_batches) |
| `pagination`                         | object| Informações de paginação da consulta.                       | [Objeto pagination](#objeto-pagination) |

### Array payment_order_conciliation_batches

| Campo                                    | Tipo       | Descrição                                                      | Caracteres |
|------------------------------------------|------------|----------------------------------------------------------------|------------|
| `payment_order_conciliation_batch_key`   | uuidv4     | Identificador único do lote de conciliação.                   | 36         |
| `payment_order_conciliation_batch_status`| enumerator | Status do lote de conciliação de ordens de pagamento.          | [Enumeradores payment_order_conciliation_batch_status](#enumeradores-payment_order_conciliation_batch_status) |
| `payment_order_conciliation_batch_type`  | enumerator | Tipo do lote de conciliação de ordens de pagamento.           | [Enumeradores payment_order_conciliation_batch_type](#enumeradores-payment_order_conciliation_batch_type) |
| `account_key`                            | uuidv4     | Chave única de identificação da conta.                        | 36         |
| `total_amount`                           | number     | Valor total do lote de conciliação em reais (R$).              | -          |
| `conciliated_amount`                     | number     | Valor já conciliado do lote em reais (R$).                     | -          |
| `total_payment_orders`                   | integer    | Número total de ordens de pagamento no lote.                   | -          |
| `conciliated_payment_orders`             | integer    | Número de ordens de pagamento já conciliadas no lote.          | -          |
| `reference_date`                         | string     | Data de referência do lote (formato ISO 8601, e.g., "2025-06-13"). | 10         |
| `created_at`                             | string     | Data e hora de criação do lote (formato ISO 8601).             | -          |

### Objeto pagination

| Campo              | Tipo    | Descrição                                      | Caracteres |
|--------------------|---------|------------------------------------------------|------------|
| `page`             | integer | Página atual da consulta.                     | -          |
| `page_size`        | integer | Tamanho da página (número de itens por página). | -          |
| `number_of_pages`  | integer | Número total de páginas disponíveis.          | -          |

### Enumeradores payment_order_conciliation_batch_status

| Enumerador   | Descrição                                   |
|--------------|---------------------------------------------|
| `open`       | Lote de conciliação aberto                 |
| `closed`     | Lote de conciliação fechado                |
| `processing` | Lote de conciliação em processamento       |
| `completed`  | Lote de conciliação concluído              |
| `cancelled`  | Lote de conciliação cancelado              |

### Enumeradores payment_order_conciliation_batch_type

| Enumerador        | Descrição                                   |
|-------------------|---------------------------------------------|
| `fixed_amount`    | Lote de conciliação de valor fixo          |
| `variable_amount` | Lote de conciliação de valor variável      |

STATUS 4XX

Response Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em português",
  "code": "codigo"
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                | Descrição (eng)<br/>`description`                                          | Descrição (ptbr)<br/>`translation`                                 |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400         | QIT000002            | Bad Request                       | Invalid request schema.                                                    | Erro no esquema da requisição.                                     |
| 404         | APX000003            | Conciliation Batch Not Found      | Conciliation batch not found.                                              | Lote de conciliação não encontrado.                                |

---

# Listagem de Pagamentos de uma Conta

URL: /documentation/baas/pix_automatico/conciliacao/listar_payment_orders

## Request

ENDPOINT /account/ ACCOUNT_KEY /payment_order_conciliation_batch/ PAYMENT_ORDER_CONCILIATION_BATCH_KEY /payment_orders
MÉTODO GET

### Query Params

| Campo                  | Tipo       | Descrição                                                                      | Caracteres |
|------------------------|------------|--------------------------------------------------------------------------------|------------|
| `payment_order_status` | enumerador | Filtra pagamentos pelo status (e.g., `processed`, `pending`, `failed`).        | 30         |
| `page`                 | integer    | Número da página a ser retornada (paginação).                                  | -          |
| `page_size`            | integer    | Número de itens por página (paginação).                                        | -          |

## Response

STATUS 200

Response Body

```json
{
  "payment_orders": [
    {
      "payment_order_key": "a1b2c3d4-e5f6-7890-ghij-1234567890kl",
      "payment_order_status": "processed",
      "amount": 150.75,
      "currency": "BRL",
      "transaction_date": "2023-10-05",
      "recipient_data": {
        "name": "Maria Silva",
        "document_number": "12345678900",
        "bank_account": {
          "account_number": "987654",
          "account_digit": "2",
          "account_branch": "1234",
          "ispb": "12345678"
        }
      },
      "pix_key": "maria@example.com",
      "pix_message": "Pagamento ref. Fatura 123",
      "conciliation_id": "uuid-conciliation"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 25,
    "number_of_pages": 3
  }
}
```

## Response Body Params

| Campo           | Tipo   | Descrição                                               | Caracteres |
|-----------------|--------|---------------------------------------------------------|------------|
| `payment_orders`| array  | Lista de objetos de pedidos de pagamento.               | [Array payment_orders](#array-payment_orders) |
| `pagination`    | object | Objeto de paginação contendo informações dos resultados. | [Objeto pagination](#objeto-pagination)         |

---

### Array payment_orders

| Campo                 | Tipo       | Descrição                                                               | Caracteres |
|-----------------------|------------|-------------------------------------------------------------------------|------------|
| `payment_order_key`   | uuidv4     | Identificador único do pedido de pagamento.                             | 36         |
| `payment_order_status`| string     | Status do pedido de pagamento (`processed`, `pending`, `failed`, etc.). | 30         |
| `amount`              | number     | Valor do pedido de pagamento em reais (R$).                             | -          |
| `currency`            | string     | Moeda do pagamento.                                                     | 3          |
| `transaction_date`    | string     | Data da transação (formato ISO 8601, e.g., `2023-10-05`).               | 10         |
| `recipient_data`      | object     | Dados do destinatário do pagamento.                                     | [Objeto recipient_data](#objeto-recipient_data) |
| `pix_key`             | string     | Chave Pix do destinatário.                                              | 77         |
| `pix_message`         | string     | Mensagem enviada junto à transação Pix.                                 | 140        |
| `conciliation_id`     | string     | Identificador de conciliação do pagamento.                              | 36         |

---

### Objeto recipient_data

| Campo             | Tipo   | Descrição               | Caracteres |
|-------------------|--------|-------------------------|------------|
| `name`            | string | Nome do destinatário.   | 50         |
| `document_number` | string | CPF ou CNPJ do destinatário. | 14      |
| `bank_account`    | object | Dados da conta bancária do destinatário. | [Objeto bank_account](#objeto-bank_account) |

---

### Objeto bank_account

| Campo           | Tipo   | Descrição                    | Caracteres |
|-----------------|--------|------------------------------|------------|
| `account_number`| string | Número da conta.             | -          |
| `account_digit` | string | Dígito da conta.             | -          |
| `account_branch`| string | Agência.                     | -          |
| `ispb`          | string | ISPB da instituição financeira.| -         |

### Objeto pagination

| Campo            | Tipo    | Descrição                           | Caracteres |
|------------------|---------|-------------------------------------|------------|
| `page`           | integer | Número da página retornada.         | -          |
| `page_size`      | integer | Quantidade de itens por página.     | -          |
| `number_of_pages`| integer | Total de páginas disponíveis.       | 
-          |

### Enumeradores payment_order_status

| Enumerador            | Descrição                                          |
|-----------------------|----------------------------------------------------|
| `pending_conciliation`| Aguardando conciliação.                            |
| `pending`             | Pendente e ainda não processada.                   |
| `accepted`            | Aceita e aguardando pagamento.                     |
| `paid`                | Paga com sucesso.                                  |
| `rejected`            | Rejeitada e não será processada.                   |
| `cancelled`           | Cancelada antes do pagamento.                      |

STATUS 4XX

Response Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em português",
  "code": "codigo"
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                | Descrição (eng)<br/>`description`                                          | Descrição (ptbr)<br/>`translation`                                 |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400         | QIT000002            | Bad Request                       | Invalid request schema.                                                    | Erro no esquema da requisição.                                     |
| 404         | APX000002            | Payment Order Not Found           | Payment order \{payment_order_key\} not found.                             | Pedido de pagamento \{payment_order_key\} não encontrado.           |

---

# Webhook de Criação de Lote de Conciliação de Ordens de Pagamento

URL: /documentation/baas/pix_automatico/conciliacao/webhooks

As notificações via webhook são essenciais para processamento de eventos sobre conciliação de pagamentos no Pix Automático. Este webhook informa sobre a criação de lotes de conciliação de ordens de pagamento.

## Webhook de Criação de Lote de Conciliação

Este webhook é emitido quando um novo lote de conciliação de ordens de pagamento é criado.

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeados de forma restrita.
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

### Webhook Request Body

Request Body: Jornada 1

```json
{
    "webhook_type": "baas.automatic_pix.payment_order_conciliation_batch.creation",
    "webhook_datetime": "2021-10-22T20:30:23.459Z",
    "data": {
        "payment_order_conciliation_batches": [
            {
                "payment_order_conciliation_batch_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
                "payment_order_conciliation_batch_status": "open",
                "payment_order_conciliation_batch_type": "fixed_amount",
                "account_key": "uuid",
                "total_amount": 0,
                "conciliated_amount": 0,
                "total_payment_orders": 0,
                "conciliated_payment_orders": 0,
                "reference_date": "2025-06-13",
                "created_at": "2025-06-10T20:30:23.459Z"
            },
            {
                "payment_order_conciliation_batch_key": "99fc62fd-b0a0-4604-9bea-475e91a9dc82",
                "payment_order_conciliation_batch_status": "open",
                "payment_order_conciliation_batch_type": "variable_amount",
                "account_key": "uuid",
                "total_amount": 0,
                "conciliated_amount": 0,
                "total_payment_orders": 0,
                "conciliated_payment_orders": 0,
                "reference_date": "2025-06-13",
                "created_at": "2025-06-10T20:30:23.459Z"
            }
        ]
    }
}
```

### Webhook Body Params

| Campo             | Tipo    | Descrição                                                                                     | Caracteres |
|-------------------|---------|-----------------------------------------------------------------------------------------------|------------|
| `webhook_type` *  | string  | Tipo do evento do webhook (`baas.automatic_pix.payment_order_conciliation_batch.creation`).   | 100        |
| `webhook_datetime` * | string | Data e hora que o webhook foi gerado (formato ISO 8601).                                     | -          |
| `data` *          | Object  | Objeto contendo detalhes dos lotes de conciliação.                                            | [Objeto data](#objeto-data)                          |

---

### Objeto data

| Campo                                 | Tipo  | Descrição                                                                         | Caracteres |
|---------------------------------------|-------|-----------------------------------------------------------------------------------|------------|
| `payment_order_conciliation_batches` * | array | Lista de lotes de conciliação criados.                                            | [Array payment_order_conciliation_batches](#array-payment_order_conciliation_batches) |

### Array payment_order_conciliation_batches

| Campo                                  | Tipo    | Descrição                                                                | Caracteres |
|----------------------------------------|---------|--------------------------------------------------------------------------|------------|
| `payment_order_conciliation_batch_key` | string  | Chave única do lote de conciliação.                                      | 36         |
| `payment_order_conciliation_batch_status` | string | Status do lote de conciliação (`open`).                                  | -          |
| `payment_order_conciliation_batch_type` | string | Tipo do lote de conciliação (`fixed_amount`, `variable_amount`).         | -          |
| `account_key`                          | uuidv4  | Chave de identificação da conta associada ao lote.                       | 36         |
| `total_amount`                         | number  | Valor total do lote de conciliação.                                      | -          |
| `conciliated_amount`                   | number  | Valor total conciliado no lote.                                          | -          |
| `total_payment_orders`                 | number  | Número total de ordens de pagamento no lote.                             | -          |
| `conciliated_payment_orders`           | number  | Número de ordens de pagamento conciliadas no lote.                       | -          |
| `reference_date`                       | string  | Data de referência do lote (formato YYYY-MM-DD).                         | 10         |
| `created_at`                           | string  | Data de criação do lote (formato ISO 8601).                              | -          |

---

# FAQ - Pix Automático

URL: /documentation/baas/pix_automatico/faq

{`
.faq-container {
  margin: 30px 0;
}

.faq-section {
  margin-bottom: 40px;
}

.faq-section-title {
  font-size: 20px;
  font-weight: 700;
  color: #0f172a;
  margin-bottom: 24px;
  padding-bottom: 12px;
  border-bottom: 2px solid #e5e7eb;
}

.faq-grid {
  display: grid;
  grid-template-columns: 1fr;
  gap: 20px;
}

.faq-card {
  background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%);
  border: 2px solid #1e40af;
  border-radius: 12px;
  padding: 24px;
  transition: all 0.3s ease;
  position: relative;
  overflow: hidden;
  width: 100%;
}

.faq-card::before {
  content: '';
  position: absolute;
  top: 0;
  left: 0;
  width: 4px;
  height: 100%;
  background: linear-gradient(to bottom, rgb(40, 85, 232), #0f172a);
  transition: width 0.3s ease;
}

.faq-card:hover {
  transform: translateY(-4px);
  box-shadow: 0 10px 25px rgba(0, 0, 0, 0.1);
  border-color: #1e3a8a;
}

.faq-card:hover::before {
  width: 6px;
}

.faq-question {
  font-size: 18px;
  font-weight: 700;
  color: #0f172a;
  margin-bottom: 16px;
  display: flex;
  align-items: flex-start;
  gap: 12px;
  line-height: 1.4;
}

.faq-question::before {
  content: '';
  font-size: 20px;
  flex-shrink: 0;
  margin-top: 2px;
}

.faq-answer {
  font-size: 14px;
  line-height: 1.7;
  color: #475569;
  margin: 0;
}

.faq-answer ul {
  margin: 12px 0;
  padding-left: 20px;
}

.faq-answer li {
  margin-bottom: 8px;
  line-height: 1.6;
}

.faq-answer strong {
  color: #0f172a;
  font-weight: 700;
}

@media (max-width: 768px) {
  .faq-grid {
    grid-template-columns: 1fr;
  }
}
`}

Perguntas sobre Recorrências
  
Uma recorrência precisa ter vigência ou quantidade de pagamentos pré-definidos?
A vigência da recorrência é um parâmetro definido na relação entre o recebedor e o pagador. A autorização pode ser concedida por período indefinido , ou alternativamente ter pré-definidos o número de cobranças ou a data final de vigência .

A data escolhida para o débito poderá ser qualquer uma dentro do ciclo?
Sim, desde que respeitada a antecedência mínima de 2 dias entre a data do agendamento e a data prevista para a liquidação, que deverá ser anterior à data de início do próximo ciclo .

Perguntas sobre Jornadas de Autorização
  
Qual a diferença principal entre as jornadas com QR Code?
A diferença principal está na experiência do usuário e no momento da autorização da recorrência. A Jornada 2 autoriza apenas a recorrência futura, sem processar pagamento na hora. A Jornada 3 permite o primeiro pagamento imediato junto com a autorização da recorrência - o pagamento efetuado é o que ativa a recorrência. A Jornada 4 funciona de forma diferente: o usuário lê um QR Code como se fosse um PIX normal, e após realizar o pagamento ou agendamento, o sistema oferece a opção de pix automático para ele. A Jornada 4 é a única que suporta recorrências de valor variável e oferece mais flexibilidade na experiência do usuário.

Se, por meio da jornada 3, ocorrer sucesso na liquidação e insucesso na autorização, será necessário o cancelamento do pagamento, já que o fluxo prevê o sucesso de ambos?
Fica a critério do usuário recebedor . Ele poderá devolver o Pix liquidado e viabilizar uma nova jornada 3 ou poderá oferecer outra jornada de autorização do Pix Automático com a finalidade exclusiva de viabilizar a autorização para pagamentos subsequentes.

Perguntas Frequentes sobre Lotes de Conciliação
  
O que são lotes de conciliação?
Os lotes de conciliação são agrupamentos de pagamentos que são criados automaticamente pelo sistema para facilitar a conciliação e controle dos pagamentos do Pix Automático. Eles servem como uma forma de organizar e rastrear os pagamentos por data de liquidação e tipo de recorrência.

Como os pagamentos são agrupados em lotes?
Os pagamentos são agrupados automaticamente em lotes baseados em critérios como:
Data de liquidação prevista para o pagamento
Tipo de recorrência: fixed_amount ou variable_amount
Conta específica
Requester específico

Quando um lote é criado?
Os lotes são criados automaticamente pelo sistema quando há ordens de pagamento que precisam ser processadas para determinada data de pagamento. O sistema agrupa essas ordens que possuem liquidação no mesmo dia em lotes , para facilitar o processamento, visualização e conciliação.

Quando um lote é fechado?
Um lote é fechado sempre três dias antes da data de referência de pagamento daquele lote, pois as ordens de pagamento precisam ser enviadas com até no máximo dois dias de antecedência referente à data de pagamento daquele ciclo. Ou seja, quando chega a data do seu fechamento.
O sistema calcula automaticamente essa data baseado na data de liquidação do pagamento menos 3 dias, garantindo que as instruções de pagamento sejam enviadas dentro do prazo regulamentar estabelecido pelo Banco Central.

Posso consultar pagamentos de lotes fechados?
Sim, você pode consultar pagamentos de lotes fechados através dos endpoints de consulta de lotes e listagem de pagamentos de um lote específico.

Perguntas sobre Ordens de Pagamento e Tentativas
  
Qual a diferença entre ordem de pagamento e tentativa de pagamento?
Ordem de Pagamento: É a instrução criada pelo sistema para realizar um pagamento específico em uma data determinada.
Tentativa de Pagamento: É cada execução individual dessa ordem de pagamento, podendo haver múltiplas tentativas se a primeira falhar.

Quantas tentativas de pagamento são realizadas?
O sistema realiza até 4 tentativas de pagamento por ordem de pagamento. Se todas as tentativas falharem, a ordem de pagamento é marcada como rejeitada.

O que acontece quando todas as tentativas falham?
Quando todas as 4 tentativas de pagamento falham, a ordem de pagamento tem seu status alterado para "rejected" e não serão realizadas mais tentativas para o pagamento desse ciclo.

Como funcionam as retentativas?
As retentativas são executadas automaticamente pelo sistema de acordo com os dias de retentativas configurados pelo recebedor na hora da criação da recorrência. Cada tentativa que falha gera um webhook de notificação para que você possa acompanhar o status desse pagamento.

Perguntas sobre Cancelamentos
  
Posso cancelar uma ordem de pagamento específica?
Sim, você pode cancelar uma ordem de pagamento específica através do endpoint de cancelamento de ordem de pagamento, desde que ela ainda não tenha sido liquidada.

Qual a diferença entre cancelar uma recorrência e cancelar uma ordem de pagamento?
Cancelar Recorrência: Cancela toda a recorrência e todas as ordens de pagamento futuras associadas a ela.
Cancelar Ordem de Pagamento: Cancela apenas a ordem de pagamento específica daquele ciclo, sem afetar a recorrência ou outras ordens.

Perguntas sobre Simulação
  
Para que servem os cenários de simulação?
Os cenários de simulação servem para testar o fluxo completo do Pix Automático no ambiente sandbox, simulando as respostas e interações do PSP Pagador (Provedor de Serviços de Pagamento).

Como usar adequadamente os cenários de simulação?
Os cenários devem ser executados em sequência para simular o fluxo completo:
Criar uma recorrência
Processar ordens de pagamento
Atualizar datas de execução (sandbox)
Processar tentativas de pagamento
Simular PIX de entrada
Simular tentativas rejeitadas (se necessário)

Perguntas sobre Webhooks
  
Quais webhooks são enviados pelo Pix Automático?
O sistema envia webhooks para diversos eventos, incluindo:
Mudanças de status de recorrências
Mudanças de status de ordens de pagamento
Mudanças de status de tentativas de pagamento
Criação e fechamento de lotes de conciliação

Perguntas sobre Benefícios e Comparações
  
Quais são os principais benefícios para os recebedores aderirem ao Pix Automático relativamente aos demais meios de pagamento existentes?
O Pix Automático oferece uma nova opção aos usuários recebedores para o recebimento e gestão das cobranças periódicas recorrentes, utilizando a infraestrutura do Pix. Dentre as vantagens, destacam-se: aumento da base de clientes , menor custo operacional por não precisar firmar convênios com mais de uma instituição, diversificação da forma de pagamento , oferecendo o Pix como alternativa aos clientes que usam cartão ou boleto, além da redução da inadimplência e mais agilidade no gerenciamento de seus recebimentos.

Qual a principal diferença entre o débito automático em conta (tradicional) e o Pix Automático?
Com foco na experiência tanto dos usuários recebedores, quanto dos pagadores, o Pix Automático apresenta novas funcionalidades para gerenciamento de autorizações e agendamentos recorrentes . Além disso, qualquer participante do Pix pode oferecer o produto a seus clientes, ampliando o acesso de cidadãos e empresas que hoje não são atendidos pelo serviço de débito automático, ofertado de forma mais restrita apenas entre instituições bancárias.

---

# Introdução ao Pix Automático

URL: /documentation/baas/pix_automatico/introducao

O **Pix Automático** é uma solução inovadora que automatiza pagamentos recorrentes de forma simplificada, eficiente e segura. Ideal para negócios que trabalham com assinaturas, mensalidades ou cobranças recorrentes de contas, o Pix Automático evolui dos métodos tradicionais ao eliminar a necessidade de interação manual, reduzir inadimplências e facilitar a gestão financeira, atendendo tanto empresas quanto consumidores.

{`
.hero-section {
  background: linear-gradient(135deg, #eff6ff 0%, #ffffff 100%);
  border: 1px solid #e5e7eb;
  border-radius: 16px;
  padding: 24px;
  margin: 24px 0 32px 0;
}

.hero-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
  gap: 16px;
  margin-top: 20px;
}

.hero-item {
  background: #ffffff;
  border: 1px solid #e5e7eb;
  border-radius: 10px;
  padding: 16px;
}

.hero-item strong {
  display: block;
  color: #1e40af;
  font-size: 14px;
  margin-bottom: 6px;
}

.hero-item p {
  margin: 0;
  font-size: 13px;
  color: #475569;
  line-height: 1.5;
}

.flow-section {
  margin: 32px 0;
}

.flow-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
  gap: 16px;
  margin-top: 20px;
}

.flow-step-card {
  border-radius: 12px;
  padding: 18px;
  color: #ffffff;
  min-height: 100px;
  display: flex;
  flex-direction: column;
  gap: 8px;
}

.flow-step-card h4 {
  margin: 0;
  font-size: 15px;
  font-weight: 700;
}

.flow-step-card p {
  margin: 0;
  font-size: 13px;
  opacity: 0.95;
  line-height: 1.5;
}
`}

Como funciona na prática?
  
Para quem?
Ideal para empresas que oferecem assinaturas, serviços recorrentes, mensalidades escolares, planos de saúde e similares.
    
O que preciso fazer?
O recebedor cria uma recorrência e o pagador autoriza uma única vez. Depois, os pagamentos acontecem automaticamente em cada ciclo.
    
Vantagens principais
Reduz atrasos, elimina necessidade de lembrar datas de pagamento e simplifica a gestão financeira para ambas as partes.

### Fluxo em 4 etapas simples

1. Criar Recorrência
O recebedor define as características da cobrança recorrente (valor, periodicidade, data de início).
    
2. Autorizar
O pagador autoriza uma única vez no aplicativo do banco, escolhendo uma das 4 jornadas disponíveis.
    
3. Agendar
A cada ciclo, o recebedor envia a instrução de pagamento e o banco do pagador agenda automaticamente.
    
4. Liquidar
Na data agendada, o débito e crédito são processados automaticamente na conta de cada parte.

---

## Funcionalidades da API do Pix Automático

A QI Tech, por meio de sua **API Automatic Pix**, capacita a integração de pagamentos automáticos usando o Pix, com base em autorizações prévias do pagador ao recebedor. O sistema abrange as seguintes responsabilidades:

{`
.features-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
  gap: 20px;
  margin: 30px 0;
}

.feature-card {
  background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%);
  border: 2px solid #e5e7eb;
  border-radius: 12px;
  padding: 24px;
  transition: all 0.3s ease;
  position: relative;
  overflow: hidden;
}

.feature-card::before {
  content: '';
  position: absolute;
  top: 0;
  left: 0;
  width: 4px;
  height: 100%;
  background: linear-gradient(to bottom, #3b82f6, #1e40af);
  transition: width 0.3s ease;
}

.feature-card:hover {
  transform: translateY(-4px);
  box-shadow: 0 10px 25px rgba(0, 0, 0, 0.1);
  border-color: #3b82f6;
}

.feature-card:hover::before {
  width: 6px;
}

.feature-title {
  font-size: 16px;
  font-weight: 700;
  color: #1e40af;
  margin-bottom: 12px;
  display: flex;
  align-items: center;
  gap: 10px;
}

.feature-icon {
  font-size: 20px;
}

.feature-description {
  font-size: 14px;
  line-height: 1.6;
  color: #475569;
  margin: 0;
}

.recurrence-types {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
  gap: 24px;
  margin: 30px 0;
}

.recurrence-card {
  background: #ffffff;
  border-radius: 16px;
  padding: 28px;
  border: 2px solid;
  position: relative;
  transition: all 0.3s ease;
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08);
}

.recurrence-card:hover {
  transform: translateY(-5px);
  box-shadow: 0 12px 30px rgba(0, 0, 0, 0.12);
}

.recurrence-card.fixed {
  border-color:rgb(11, 63, 250);
  background: linear-gradient(135deg, #ffffff 0%,rgb(235, 240, 255) 100%);
}

.recurrence-card.variable {
  border-color:rgb(11, 63, 250);
  background: linear-gradient(135deg, #ffffff 0%,rgb(235, 240, 255) 100%);
}

.recurrence-header {
  display: flex;
  align-items: center;
  gap: 12px;
  margin-bottom: 16px;
}

.recurrence-badge {
  padding: 6px 14px;
  border-radius: 20px;
  font-size: 12px;
  font-weight: 700;
  text-transform: uppercase;
  letter-spacing: 0.5px;
}

.recurrence-card.fixed .recurrence-badge {
  background:rgb(16, 64, 185);
  color: #ffffff;
}

.recurrence-card.variable .recurrence-badge {
  background:rgb(16, 64, 185);
  color: #ffffff;
}

.recurrence-title {
  font-size: 20px;
  font-weight: 700;
  color: #0f172a;
  margin: 0;
}

.recurrence-description {
  font-size: 15px;
  line-height: 1.7;
  color: #475569;
  margin-bottom: 16px;
}

.recurrence-detail {
  background: rgba(255, 255, 255, 0.7);
  border-left: 3px solid;
  padding: 12px 16px;
  border-radius: 8px;
  font-size: 13px;
  line-height: 1.6;
  color: #64748b;
}

.recurrence-card.fixed .recurrence-detail {
  border-left-color:rgb(203, 15, 68);
}

.recurrence-card.variable .recurrence-detail {
  border-left-color:rgb(203, 15, 68);
}

.periodicity-container {
  background: linear-gradient(135deg, #eff6ff 0%, #ffffff 100%);
  border: 2px solid #e5e7eb;
  border-radius: 16px;
  padding: 28px;
  margin: 30px 0;
}

.periodicity-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
  gap: 16px;
  margin-top: 20px;
}

.periodicity-item {
  background: #ffffff;
  padding: 16px;
  border-radius: 10px;
  text-align: center;
  border: 2px solid #e5e7eb;
  transition: all 0.3s ease;
}

.periodicity-item:hover {
  border-color: #3b82f6;
  transform: translateY(-3px);
  box-shadow: 0 6px 20px rgba(59, 130, 246, 0.15);
}

.periodicity-label {
  font-size: 14px;
  font-weight: 600;
  color: #1e40af;
  margin: 0;
}

.journeys-container {
  margin: 30px 0;
}

.journey-card {
  background: #ffffff;
  border: 2px solid #e5e7eb;
  border-radius: 12px;
  padding: 24px;
  margin-bottom: 16px;
  transition: all 0.3s ease;
  border-left: 5px solid;
}

.journey-card:hover {
  transform: translateX(5px);
  box-shadow: 0 8px 20px rgba(0, 0, 0, 0.1);
}

.journey-card.journey-1 {
  border-left-color: #3b82f6;
}

.journey-card.journey-2 {
  border-left-color: #10b981;
}

.journey-card.journey-3 {
  border-left-color: #f59e0b;
}

.journey-card.journey-4 {
  border-left-color: #ec4899;
}

.journey-header {
  display: flex;
  align-items: center;
  gap: 12px;
  margin-bottom: 12px;
}

.journey-number {
  background: linear-gradient(135deg, #1e40af, #3b82f6);
  color: #ffffff;
  width: 36px;
  height: 36px;
  border-radius: 50%;
  display: flex;
  align-items: center;
  justify-content: center;
  font-weight: 700;
  font-size: 16px;
  flex-shrink: 0;
}

.journey-card.journey-1 .journey-number {
  background: linear-gradient(135deg, #1e40af, #3b82f6);
}

.journey-card.journey-2 .journey-number {
  background: linear-gradient(135deg, #059669, #10b981);
}

.journey-card.journey-3 .journey-number {
  background: linear-gradient(135deg, #d97706, #f59e0b);
}

.journey-card.journey-4 .journey-number {
  background: linear-gradient(135deg, #db2777, #ec4899);
}

.journey-title {
  font-size: 18px;
  font-weight: 700;
  color: #0f172a;
  margin: 0;
}

.journey-description {
  font-size: 14px;
  line-height: 1.7;
  color: #475569;
  margin: 0;
  padding-left: 48px;
}

.cancellation-info {
  background: linear-gradient(135deg, #f8fafc 0%, #ffffff 100%);
  border: 2px solid #e5e7eb;
  border-radius: 16px;
  padding: 28px;
  margin: 30px 0;
}

.cancellation-list {
  list-style: none;
  padding: 0;
  margin: 20px 0 0 0;
}

.cancellation-item {
  background: #ffffff;
  padding: 16px 20px;
  border-radius: 10px;
  margin-bottom: 12px;
  border-left: 4px solid #3b82f6;
  display: flex;
  gap: 12px;
}

.cancellation-item:last-child {
  margin-bottom: 0;
}

.cancellation-label {
  font-weight: 700;
  color: #1e40af;
  min-width: 180px;
}

.cancellation-text {
  color: #475569;
  flex: 1;
  margin: 0;
}

.advantages-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
  gap: 20px;
  margin: 30px 0;
}

.advantage-card {
  background: linear-gradient(135deg, #ffffff 0%, #f0fdf4 100%);
  border: 2px solid #d1fae5;
  border-radius: 12px;
  padding: 20px;
  transition: all 0.3s ease;
}

.advantage-card:hover {
  transform: translateY(-4px);
  border-color: #10b981;
  box-shadow: 0 10px 25px rgba(16, 185, 129, 0.15);
}

.advantage-text {
  font-size: 14px;
  line-height: 1.7;
  color: #475569;
  margin: 0;
  display: flex;
  align-items: flex-start;
  gap: 10px;
}

.advantage-icon {
  color: #10b981;
  font-size: 18px;
  flex-shrink: 0;
  margin-top: 2px;
}

@media (max-width: 768px) {
  .features-grid,
  .recurrence-types,
  .advantages-grid {
    grid-template-columns: 1fr;
  }

  .periodicity-grid {
    grid-template-columns: repeat(2, 1fr);
  }

  .journey-description {
    padding-left: 0;
    margin-top: 12px;
  }
}
`}

Criação e Gestão
Facilita a criação, gestão e cancelamento de recorrências de forma simplificada e eficiente.

Orquestração de Autorizações
Garante que os pagamentos recorrentes do Pix Automático sejam autorizados corretamente pelo pagador.

Agendamento e Liquidação
Automatiza completamente os ciclos de pagamento, desde o agendamento até a liquidação.

Logs e Auditorias
Mantém registro completo de todas as operações para conformidade com as regras do Bacen.

---

## Tipos de Recorrência

Valor Fixo
Recorrência de Valor Fixo
      Na modalidade de valor fixo, o pagador autoriza a recorrência de pagamentos periódicos de valores fixos, previamente estabelecidos na criação da recorrência.
Ideal para: Assinaturas mensais, mensalidades escolares, planos de serviços com valores fixos.

Valor Variável
Recorrência de Valor Variável
      Na modalidade de valor variável, o pagador e o recebedor concordam com uma faixa de valores permitidos para cada cobrança recorrente. O recebedor define o valor mínimo e o pagador define o valor máximo.
Importante: O recebedor deve conciliar a ordem de pagamento com o valor a ser cobrado no período de 10 a 3 dias antes da data da cobrança.
Ideal para: Modelos baseados em consumo, contas de serviços variáveis, pagamentos ajustáveis ao longo do tempo.

---

## Periodicidade das Recorrências

Atualmente, é possível realizar a criação de recorrências com as seguintes periodicidades:

Periodicidades Disponíveis
Semanal
Mensal
Trimestral
Semestral
Anual

---

## Jornadas de Autorização do Pix Automático

O Pix Automático suporta várias jornadas de autorização para atender a diferentes cenários de negócio:

1
Jornada 1: Push Notification
      Notificação via app para confirmação da recorrência, sem necessidade de QR Code. O pagador recebe uma notificação e autoriza diretamente no aplicativo.

2
Jornada 2: QR Code - Recorrência
      Autorização com QR Code contendo apenas dados da recorrência. O pagador escaneia o QR Code e autoriza apenas a recorrência futura.

3
Jornada 3: QR Code + Primeiro Pagamento
      QR Code permitindo o primeiro pagamento imediato e a configuração de recorrência simultaneamente. Ideal para casos onde deseja-se receber o primeiro pagamento e criar a recorrência na mesma transação.

4
Jornada 4: QR Code Completo
      QR Code incluindo dados para pagamento/agendamento imediato e oferta de pix automático para aquela cobrança, após pagamento ou agendamento. Permite pagamento (ou agendamento) e oferta do pix automático em uma única operação.

:::info Documentação das Jornadas
Para detalhes completos sobre como implementar cada jornada, consulte:
- [Jornada 1 - Push Notification](./recebedor/journey_one.md)
- [Jornada 2 - QR Code (apenas recorrência)](./recebedor/journey_two.md)
- [Jornada 3 - QR Code (com primeiro pagamento)](./recebedor/journey_three.md)
- [Jornada 4 - QR Code (com primeiro pagamento e valores variáveis)](./recebedor/journey_four.md)
:::

---

## Cancelamento de Recorrência

Regras de Cancelamento
  
Solicitação de Cancelamento
Pode ser feita tanto pelo usuário pagador quanto pelo recebedor de forma unilateral, sem necessidade de aprovação mútua.
Impacto do Cancelamento
A autorização e a recorrência são canceladas simultaneamente, bloqueando novas instruções de pagamento automaticamente.
Processo de Cancelamento
O usuário pagador atualiza e comunica o status de cancelamento ao usuário recebedor, que deve ser informado imediatamente.
Efeitos Imediatos
Cancela automaticamente todos os agendamentos associados, exceto aqueles previstos para liquidação no próprio dia do cancelamento.
Iniciativa do Recebedor
O recebedor pode cancelar a recorrência por decisão própria ou sob solicitação do pagador através da API.

---

## Vantagens e Potencial

O Pix Automático oferece diversas vantagens, como a centralização de autorizações e pagamentos, incentivo à digitalização financeira, e eficiência em soluções de débito automático, suprindo lacunas dos métodos tradicionais de pagamento.

✓
Redução do risco de atrasos e da necessidade de lembrar datas de vencimento, com eliminação de etapas manuais

✓
Centralização do controle de autorizações e pagamentos em uma única plataforma

✓
Incentivo à digitalização dos processos financeiros e modernização do relacionamento com clientes

✓
Simplificação das operações para estabelecimentos e clientes finais

✓
Eficiência em soluções de débito automático com tecnologia Pix

✓
Preenchimento de lacunas existentes nos instrumentos tradicionais de pagamento

---

## Simulação de Cenários

Durante o desenvolvimento e testes da integração com o Pix Automático, é essencial validar todos os fluxos antes de utilizar o ambiente de produção. A **Simulação de Cenários** fornece um ambiente sandbox completo que permite testar todo o ciclo de vida de uma recorrência, desde a criação até a liquidação dos pagamentos.

### O que é a Simulação de Cenários?

A Simulação de Cenários é uma ferramenta que permite **testar o fluxo completo do Pix Automático** no ambiente sandbox, simulando as respostas da SPI (Sistema de Pagamentos Instantâneos) sem realizar transações reais. Ela abrange:

- **Criação e aprovação de recorrências** utilizando as 4 jornadas disponíveis
- **Processamento de ordens de pagamento** e criação de lotes de conciliação
- **Simulação de tentativas de pagamento** com diferentes resultados (sucesso ou rejeição)
- **Teste de fluxos de cancelamento** e gestão de recorrências

### Quando usar?

A simulação é recomendada para:

- **Validação de integração**: Testar se sua aplicação está corretamente integrada com a API
- **Desenvolvimento**: Desenvolver e debugar sua implementação sem custos
- **Testes de fluxos**: Validar diferentes cenários (pagamentos bem-sucedidos, rejeições, cancelamentos)
- **Treinamento**: Familiarizar sua equipe com os fluxos do Pix Automático antes de ir para produção

### Como usar?

O processo de simulação segue uma sequência de passos que replica o fluxo real:

1. **Criar uma recorrência** usando uma das jornadas de autorização
2. **Aprovar a recorrência** via mock, simulando a confirmação do pagador
3. **Processar ordens de pagamento** que criam automaticamente os lotes de conciliação
4. **Consultar e conciliar** as ordens (obrigatório para valores variáveis)
5. **Atualizar data de execução** para acelerar os testes no sandbox
6. **Processar tentativas** de pagamento
7. **Simular o resultado**: Pix de entrada (sucesso) ou rejeição

:::tip Documentação Completa
Para um guia passo a passo detalhado sobre como usar a simulação de cenários, incluindo todos os endpoints disponíveis e exemplos de requisições, consulte:

**[📋 Guia de Simulação de Cenários](./recebedor/simulacao.md)**
:::

### Benefícios da Simulação

✓
Testes sem custos ou riscos, em ambiente controlado e isolado

✓
Validação completa de todos os fluxos antes da produção

✓
Aceleração de datas e processos para testes mais rápidos

✓
Simulação de diferentes cenários (sucessos, falhas, cancelamentos)

---

# Aceitar recorrência de pagamento

URL: /documentation/baas/pix_automatico/movimentacoes/aceitar_recorrencia

## Request

ENDPOINT /account/ ACCOUNT_KEY /incoming_recurrence/ INCOMING_RECURRENCE_KEY /approve
MÉTODO PATCH

### Request Path Params

| Campo       | Tipo   | Descrição                      | Caracteres |
|-------------|--------|--------------------------------|------------|
| `account_key` * | uuid4  | Chave única de identificação da conta. | 36 |
| `incoming_recurrence_key` * | uuid4  | Chave única de identificação da autorização                                    | 36 |

### Request Body

Request Body: Aprovar recorrência de valor fixo

```json
{
  "incoming_recurrence_status": "active"
}
```

Request Body: Aprovar recorrência de valor variável com limite máximo

```json
{
  "incoming_recurrence_status": "active",
  "maximum_transaction_amount": 500.00
}
```

### Body Params

| Campo                   | Tipo       | Descrição                                                                                                                                                                                                                                        | Caracteres |
|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `incoming_recurrence_status` *           | string     | Identificador de status da recorrência Pix. Deve ser "active" para ativar a recorrência                                                                                                                                                                                                | 20        |
| `maximum_transaction_amount`           | number     | Valor máximo que o usuário aceita pagar por transação (opcional, apenas para recorrências de valor variável)                                                                                                                                                                                                | 10        |

:::info Valor Máximo para Recorrências Variáveis
O campo `maximum_transaction_amount` é **opcional** e deve ser usado apenas para **recorrências de valor variável**. Ele permite que o pagador defina o valor máximo que aceita pagar por transação dentro da recorrência autorizada.
:::
## Response

STATUS 200

Response Body: Recorrência ativada

```json
{
  "incoming_recurrence_key": "cfa32109-a6dd-4304-94db-03a7b6d92a47",
  "incoming_recurrence_status": "active",
  "created_at": "2025-05-22T20:30:23.459Z",
  "updated_at": "2025-05-22T20:39:23.459Z"
}
```

STATUS 4XX

Response Body

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo"
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`           | Descrição (eng)<br/>`Description`                                   | Descrição (ptbr)<br/>`translation`                                |
|-------------|----------------------|------------------------------|---------------------------------------------------------------------|-------------------------------------------------------------------|
| 400         | QIT000001            | Bad Request	            | Schema Error                                      | Erro de Schema                       |
 403         | APX000025            | User is not allowed to do this transaction        | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 403         | APX000017            | Requester not allowed to access this endpoint        | Requester has no permission to perform pix transfers on this endpoint | Requester não possui permissão de realizar transações pix através deste endpoint |
| 404         | APX000020            | Account not Found             | Account was not found | Conta \{account_key\} não foi encontrada. |
| 404         | APX000001            | Recurrence not Found        | Recurrence was not found | Recorrência \{incoming_recurrence_key\} não foi encontrada |

---

# Cancelar a recorrência

URL: /documentation/baas/pix_automatico/movimentacoes/cancelar_recorrencia

## Request

ENDPOINT /account/ ACCOUNT_KEY /incoming_recurrence/ INCOMING_RECURRENCE_KEY /cancel
MÉTODO PATCH

### Request Path Params

| Campo       | Tipo   | Descrição                      | Caracteres |
|-------------|--------|--------------------------------|------------|
| `account_key` * | uuid4  | Chave única de identificação da conta. | 36 |
| `incoming_recurrence_key` * | uuid4  | Chave única de identificação da autorização                                    | 36 |

### Request Body

Request Body: Cancelar uma recorrência

```json
{
  "incoming_recurrence_status": "cancelled",
}
```

### Body Params

| Campo                   | Tipo       | Descrição                                                                                                                                                                                                                                        | Caracteres |
|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `incoming_recurrence_status` *           | string     | Identificador de status da recorrência Pix.                                                                                                                                                                                                | cancelled        |
## Response

STATUS 200

Response Body: Recorrência cancelada

```json
{
  "incoming_recurrence_key": "cfa32109-a6dd-4304-94db-03a7b6d92a47",
  "incoming_recurrence_status": "cancelled",
  "created_at": "2025-05-22T20:30:23.459Z",
  "updated_at": "2025-05-22T20:39:23.459Z"
}
```

STATUS 4XX

Response Body

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo"
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`           | Descrição (eng)<br/>`Description`                                   | Descrição (ptbr)<br/>`translation`                                |
|-------------|----------------------|------------------------------|---------------------------------------------------------------------|-------------------------------------------------------------------|
| 400         | QIT000001            | Bad Request	            | Schema Error                                      | Erro de Schema                       |
 403         | APX000025            | User is not allowed to do this transaction        | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 403         | APX000017            | Requester not allowed to access this endpoint        | Requester has no permission to perform pix transfers on this endpoint | Requester não possui permissão de realizar transações pix através deste endpoint |
| 404         | APX000020            | Account not Found             | Account was not found | Conta \{account_key\} não foi encontrada. |
| 404         | APX000001            | Recurrence not Found        | Recurrence was not found | Recorrência \{incoming_recurrence_key\} não foi encontrada |

---

# Consultar Recorrência

URL: /documentation/baas/pix_automatico/movimentacoes/consultar_recorrencia

## Consultar recorrência Pix por incoming_recurrency_key

### Request

ENDPOINT /account/ ACCOUNT_KEY /incoming_recurrence/ INCOMING_RECURRENCE_KEY
MÉTODO GET

### Path Params

| Campo                      | Tipo       | Descrição                                             | Caracteres                                                                  |
|----------------------------|------------|-------------------------------------------------------|-----------------------------------------------------------------------------|
| `account_key` *            | uuid4     | Chave única de identificação da conta QI.             | 36                                                                          |
| `incoming_recurrency_key` *       | uuid4     | Chave única de identificação da recorrência de Pix automático.    | 36                                                                          |

### Response

STATUS 200

Response Body: Consulta da recorrência

```json
{
  "incoming_recurrence_key": "c2f3eefa-1b8e-4d5f-9b9d-123456789abc",
  "incoming_recurrence_status": "pending_confirmation",
  "request_control_key": "e04197f6-433e-48d2-8a8e-9258a70aba0b",
  "transaction_amount": "150.00",
  "periodicity": "monthly",
  "journey_type": "journey_one",
  "pix_transfer_type": "key",
  "end_to_end_id": "E1234567890123456789012",
  "start_date": "2025-06-01",
  "end_date": "2026-06-01",
  "next_execution_date": "2025-07-01",
  "receiver_conciliation_id": "rec-conc-789",
  "target_pix_key": "receiver@bank.com.br",
  "payer_document_number": "12345678900",
  "pix_message": "Pagamento mensal de serviço",
  "created_at": "2025-05-22T10:00:00Z",
  "updated_at": "2025-05-22T12:00:00Z",
}

```

| Campo                          | Tipo    | Descrição                                                                                                                                                                                                                                                                                     | Max. Caracteres                                                   |
|--------------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `incoming_recurrence_key`  | uuid4    | Chave única de identificação da autorização                                                                                                                                                              | 36         | 
| `incoming_recurrence_status`               | string  |Identificador de status da recorrência                                                                                                                                         | [Enumerador incoming_recurrence_status](#enumerador-incoming_recurrence_status)                                                           |
| `request_control_key`  | uuid4     | Chave única de identificação da request utilizada pelo cliente                                                                                                                                                              | 36         | 
| `transaction_amount`   | number     | Valor da transferência para ocorrência de valor fixo.                                                                                                                                                                                                                         | 10         |
| `minimum_transaction_amount`   | number     | Valor mínimo da transferência para ocorrência de valor variável.                                                                                                                                                                                                                         | 10         |
| `maximum_transaction_amount`   | number     | Valor máximo da transferência para ocorrência de valor valor variável.                                                                                                                                                                                                                         | 10         |
| `periodicity`    | enumerator | Tipo da periodicidade associada ao pagamento                                                                                                                                           | [Enumeradores periodicity](#enumeradores-periodicity)     |
| `journey_type`    | enumerator | Tipo da jornada de solicitação                                                                                                                                                    | [Enumeradores journey_type](#enumeradores-journey_type)     |
| `pix_transfer_type`    | enumerator | Tipo do pix a ser realizado                                                                                                                                                   | [Enumeradores pix_transfer_type](#enumeradores-pix_transfer_type)     |
| `end_to_end_id`        | string     | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na consulta de chave Pix. | 32 |
| `start_date`    | string | Data de ínicio da recorrência                                                                                                                                                         | -      |
| `end_date`   | string | Data de término da recorrência, para os casos de tempo indeterminado, enviar como null                                                                                                                        
| `next_execution_date`    | string | Data de execução da próxima transação da recorrência                                                                                                                                                      | -      |
| `receiver_conciliation_id` | string     | Identicação de conciliação do recebedor. | 35                                        |
| `target_pix_key`       | string     | Chave pix da conta da transação.                                                                                                                                                                                                    | 100        |
| `payer_document_number`       | string     | Número de documento do pagador da transação transação.                                                                                                                                                                                                    | 14        |
| `pix_message`           | string     | Mensagem a ser enviada junto à transferência Pix.                                                                                                                                                                                                | 140        |
| `created_at`              | string  | Horário da criação da solicitação de recorrência                                                                                                                                       | -          
| `updated_at`              | string  | Horário de atualização da solicitação de recorrência                                                                                                                                       | -                                  

### Enumerador incoming_recurrence_status

| Enumerador           | Descrição           |
|----------------------|---------------------|
| `pending_confirmation` | Recorrência pendente de confirmação      |
| `active`   | Recorrência ativa       |
| `cancelled`   | Recorrência cancelada      |
| `suspended`  | Recorrência suspensa |
| `expired`  | Recorrência expirada |

### Enumeradores periodicity
| Enumerador       | Descrição          |
|------------------|--------------------|
| `weekly` | Recorrência semanal |
| `monthly` | Recorrência mensal  |
| `quarterly` | Recorrência trimestral     |
| `semiannual` | Recorrência semestral     |
| `annual` | Recorrência anual      |

### Enumeradores journey_type
| Enumerador       | Descrição          |
|------------------|--------------------|
| `journey_one` | Solicitação de autorização mediante uma notificação no aplicativo |
| `jouney_two` | Solicitação de autorização mediante a leitura de um QR Code  |
| `journey_three` | Autorização de recorrência por meio de um pix imediato mediante leitura de um QR Code     |
| `journey_four` | Pagamento ou agendamento de um pix com uma solicitação de autorização da recorrência em sequência      |

### Enumeradores pix_transfer_type

| Enumerador          | Descrição                                |
|---------------------|------------------------------------------|
| `manual`          | Pix utilizando os dados da conta destino |
| `key`             | Pix utilizando uma chave pix             |
| `static_qr_code`  | Pix utilizando um QR code estático       |
| `dynamic_qr_code` | Pix utilizando um QR code dinâmico       |

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                          | Descrição (eng)<br/>`Description`                   | Descrição (ptbr)<br/>`translation`                                            |
|-------------|----------------------|---------------------------------------------|-----------------------------------------------------|-------------------------------------------------------------------------------|
 403         | APX000025            | User is not allowed to do this transaction        | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 403         | APX000017            | Requester not allowed to access this endpoint        | Requester has no permission to perform pix transfers on this endpoint | Requester não possui permissão de realizar transações pix através deste endpoint |
| 404         | APX000020            | Account not Found             | Account was not found | Conta \{account_key\} não foi encontrada. |
| 404         | APX000001            | Recurrence not Found        | Recurrence was not found | Recorrência \{incoming_recurrence_key\} não foi encontrada |

---

# Criar recorrência de pagamento

URL: /documentation/baas/pix_automatico/movimentacoes/criar_recorrencia

## Request

ENDPOINT /account/ ACCOUNT_KEY /incoming_recurrence
MÉTODO POST

### Request Path Params

| Campo       | Tipo   | Descrição                      | Caracteres |
|-------------|--------|--------------------------------|------------|
| `account_key` * | uuid4  | Chave única de identificação da conta. | 36 |

### Request Body

Request Body: Criar recorrência de valor fixo

```json
{
  "request_control_key": "01585acf-b0c3-4389-baf3-a58abbe92d58",
  "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
  "periodicity": "monthly",
  "journey_type": "journey_one",
  "start_date": "2025-04-01",
  "end_date": "2027-04-01",
  "target_pix_key": "pix_key@test.bcb.com",
  "pix_message": "Informação do pagamento",
  "is_retry_allowed": true,
  "transaction_amount": 150.04
}
```

Request Body: Criar recorrência de valor variável

```json
{
  "request_control_key": "12385acf-b0c3-4389-baf3-a58abbe92d58",
  "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
  "periodicity": "monthly",
  "journey_type": "journey_one",
  "start_date": "2025-07-01",
  "end_date": null,
  "target_pix_key": "pix_key@test.bcb.com",
  "pix_message": "Pagamento da conta de energia elétrica",
  "is_retry_allowed": true,
  "minimum_transaction_amount": 50.00,
  "maximum_transaction_amount": 300.00
}
```

### Body Params

| Campo                   | Tipo       | Descrição                                                                                                                                                                                                                                        | Caracteres |
|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuid     | Chave única de identificação da request utilizada pelo cliente no formato uuid4.                                                                                                                                                               | 36         | 
| `periodicity` *   | enumerator | Tipo da periodicidade associada ao pagamento                                                                                                                                           | [Enumeradores periodicity](#enumeradores-periodicity)     |
| `journey_type` *   | enumerator | Tipo da jornada de solicitação                                                                                                                                                    | [Enumeradores journey_type](#enumeradores-journey_type)     |
| `start_date` *   | string | Data de ínicio da recorrência                                                                                                                                                         | -      |
| `end_to_end_id` *       | string     | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na consulta de chave Pix. | 32 |
| `target_pix_key`       | string     | Chave pix da conta a ser enviada a transação.                                                                                                                                                                                                    | 100        |
| `target_account`       | Object     | Conta destino - Só deve ser enviada em transferências para transferência manuais. | [Objeto target_account](#objeto-target_account) | 10 |
| `transaction_amount`   | number     | Valor da transferência para ocorrência de valor fixo.                                                                                                                                                                                                                         | 10         |
| `minimum_transaction_amount`   | number     | Valor mínimo da transferência para ocorrência de valor variável.                                                                                                                                                                                                                         | 10         |
| `maximum_transaction_amount`   | number     | Valor máximo da transferência para ocorrência de valor valor variável.                                                                                                                                                                                                                         | 10         |
| `end_date`   | string | Data de término da recorrência, para os casos de tempo indeterminado, enviar como null                                                                                                                                                        | -      |
| `pix_message`           | string     | Mensagem a ser enviada junto à transferência Pix.                                                                                                                                                                                                | 140        |
| `is_retry_allowed`           | boolean     | Permissão para retentativa de transação Pix.                                                                                                                                                                                                | -        |

### Enumeradores periodicity
| Enumerador       | Descrição          |
|------------------|--------------------|
| `weekly` | Recorrência semanal |
| `monthly` | Recorrência mensal  |
| `quarterly` | Recorrência trimestral     |
| `semiannual` | Recorrência semestral     |
| `annual` | Recorrência anual      |

### Enumeradores journey_type
| Enumerador       | Descrição          |
|------------------|--------------------|
| `journey_one` | Solicitação de autorização mediante uma notificação no aplicativo |
| `journey_two` | Solicitação de autorização mediante a leitura de um QR Code  |
| `journey_three` | Autorização de recorrência por meio de um pix imediato mediante leitura de um QR Code     |
| `journey_four` | Pagamento ou agendamento de um pix com uma solicitação de autorização da recorrência em sequência      |

### Objeto target_account

| Campo                     | Tipo       | Descrição                                           | Caracteres                                              |
|---------------------------|------------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch`         | string     | Agência da conta.                                   | 6                                                       |
| `account_digit`          | string     | Dígito da conta.                                    | 1                                                       |
| `account_number`         | string     | Número da conta.                                    | 20                                                      |
| `owner_document_number`  | string     | CPF ou CNPJ (apenas números) do titular da conta.   | 14                                                      |
| `owner_name`             | string     | Nome do titular da conta.                           | 150                                                     |
| `account_type`          | enumerator | Tipo da conta.                                      | [Enumerador account_type](#enumerador-account_type) |
| `ispb`                   | string     | Base no CNPJ da instituição financeira (8 dígitos). | 8                                                       |

:::info
Diferentes enumeradores podem significar o mesmo tipo de conta devido a informação retornada por diferentes
instituições.
:::
### Enumerador account_type

| Enumerador           | Descrição           |
|----------------------|---------------------|
| `checking_account` | Conta Corrente      |
| `salary_account`   | Conta Salário       |
| `saving_account`   | Conta Poupança      |
| `payment_account`  | Conta de Pagamentos |

## Response

STATUS 200

Response Body: Recorrência criada

```json
{
  "incoming_recurrence_key": "cfa32109-a6dd-4304-94db-03a7b6d92a47",
  "incoming_recurrence_status": "pending_confirmation",
  "created_at": "2025-05-22T20:30:23.459Z",
}
```

| Campo                          | Tipo    | Descrição                                                                                                                                                                                                                                                                                     | Max. Caracteres                                                   |
|--------------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `incoming_recurrence_key`  | uuid     | Chave única de identificação da autorização                                                                                                                                                              | 36         | 
| `incoming_recurrence_status`               | string  |Identificador de status da recorrência                                                                                                                                         | [Enumerador incoming_recurrence_status](#enumerador-incoming_recurrence_status)                                                           |
| `created_at`              | string  | Horário da criação da solicitação de recorrência                                                                                                                                       | -                                                                

### Enumerador incoming_recurrence_status

| Enumerador           | Descrição           |
|----------------------|---------------------|
| **pending_confirmation** | Recorrência pendente de confirmação      |
| **active**   | Recorrência ativa       |
| **cancelled**   | Recorrência cancelada      |
| **suspended**  | Recorrência suspensa |
| **expired**  | Recorrência expirada |

STATUS 4XX

Response Body

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo"
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`           | Descrição (eng)<br/>`Description`                                   | Descrição (ptbr)<br/>`translation`                                |
|-------------|----------------------|------------------------------|---------------------------------------------------------------------|-------------------------------------------------------------------|
| 400         | QIT000001            | Bad Request	            | Schema Error                                      | Erro de Schema                       |
| 403         | APX000025            | User is not allowed to do this transaction        | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 403         | APX000017            | Requester not allowed to access this endpoint        | Requester has no permission to perform pix transfers on this endpoint | Requester não possui permissão de realizar transações pix através deste endpoint |
| 404         | APX000020            | Account not Found             | Account was not found | Conta \{account_key\} não foi encontrada. |
| 406         | APX000026            | Invalid end_to_end_id            | The end_to_end_id sent \{end_to_end_id\} is not valid.                                      | O end_to_end_id enviado  \{end_to_end_id\} não é válido                       |
| 406         | APX000005            | Invalid Transaction Amount            | Transaction amount of \{transaction_amount\} is not valid. It must be a positive value with at maximum 2 decimal places                                     | O valor de transação \{transaction_amount\} não é válido. Deve ser um valor positivo com no máximo duas casas decimais                      |
| 409         | APX000013            | Request Control Key Reuse Error            | The request_control_key \{request_control_key\} already in use                                      | A request_control_key \{request_control_key\} já utilizada                       |

---

# Listagem de Recorrências

URL: /documentation/baas/pix_automatico/movimentacoes/listar_recorrencias

## Listagem de recorrências Pix para uma conta

### Request

ENDPOINT /account/ ACCOUNT_KEY /incoming_recurrences
MÉTODO GET

### Path Params

| Campo                      | Tipo       | Descrição                                             | Caracteres                                                                  |
|----------------------------|------------|-------------------------------------------------------|-----------------------------------------------------------------------------|
| `account_key` *            | uuid4     | Chave única de identificação da conta QI.             | 36                                                                          |

### Query Params

| Campo                    | Tipo       | Descrição                                                                                                  | Caracteres                                                                  |
|--------------------------|------------|------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| `request_control_key`    | uuid4     | Chave única de identificação da request utilizada pelo cliente.                                            | 36                                                                          |
| `status`          | string     | Identificador de status da recorrência Pix                                                                | [Enumerador status](#enumerador-status)                                                                          |
| `date_from`              | string     | Data inicial para o filtro de listagem.   | Formato "YYYY-MM-DD" |
| `date_to`                | string     | Data final para o filtro de listagem. | Formato "YYYY-MM-DD" | 
| `page`                   | integer    | Número da página requisitada. |  Padrão 1  |
| `page_size`              | integer    | Tamanho da página requisitada na consulta.                                     | Valor padrão e máximo de 30                                 

### Enumerador status

| Enumerador           | Descrição           |
|----------------------|---------------------|
| `pending_confirmation` | Recorrência pendente de confirmação      |
| `active`   | Recorrência ativa       |
| `cancelled`   | Recorrência cancelada      |
| `suspended`  | Recorrência suspensa |
| `expired`  | Recorrência expirada |

### Response

STATUS 200

Response Body: Listagem das recorrências

```json

{
    "data": [
        {
            "incoming_recurrence_key": "c2f3eefa-1b8e-4d5f-9b9d-123456789abc",
            "incoming_recurrence_status": "pending_confirmation",
            "request_control_key": "e04197f6-433e-48d2-8a8e-9258a70aba0b",
            "transaction_amount": "150.00",
            "periodicity": "monthly",
            "journey_type": "journey_one",
            "pix_transfer_type": "key",
            "end_to_end_id": "E1234567890123456789012",
            "start_date": "2025-06-01",
            "end_date": "2026-06-01",
            "next_execution_date": "2025-07-01",
            "receiver_conciliation_id": "rec-conc-789",
            "target_pix_key": "receiver@bank.com.br",
            "payer_document_number": "12345678900",
            "pix_message": "Pagamento mensal de serviço",
            "created_at": "2025-05-22T10:00:00Z",
            "updated_at": "2025-05-22T12:00:00Z"
        }
    ],
    "pagination": {
        "current_page": 1,
        "rows_per_page": 30
    }
}

```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                          | Descrição (eng)<br/>`Description`                   | Descrição (ptbr)<br/>`translation`                                            |
|-------------|----------------------|---------------------------------------------|-----------------------------------------------------|-------------------------------------------------------------------------------|
 403         | APX000025            | User is not allowed to do this transaction        | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 403         | APX000017            | Requester not allowed to access this endpoint        | Requester has no permission to perform pix transfers on this endpoint | Requester não possui permissão de realizar transações pix através deste endpoint |
| 404         | APX000020            | Account not Found             | Account was not found | Conta \{account_key\} não foi encontrada. |

---

# Simulação de cenários

URL: /documentation/baas/pix_automatico/movimentacoes/simulacao

Passo a passo para simular a criação de recorrências e pagamentos automáticos no âmbito do PIX Automático. Essas simulações incluem a criação de recorrências e a criação de pagamentos programados.

## 1 - Simulação de criação de recorrência

### Request

ENDPOINT /mock/incoming_recurrence
MÉTODO POST

Request Body: Recorrência de valor fixo

```json
{
  "request_control_key": "01585acf-b0c3-4389-baf3-a58abbe92d58",
  "recurrence_type": "fixed_amount",
  "transaction_amount": 100.50,
  "periodicity": "monthly",
  "journey_type": "journey_one",
  "start_date": "2025-07-01",
  "is_retry_allowed": true,
  "payer_account_information": {
    "owner_name": "John Doe",
    "document_number": "06975239000136",
    "ispb": "32402502",
    "account_digit": "7",
    "account_branch": "3",
    "account_number": "9552432"
}
```

Request Body: Recorrência de valor variável

```json
{
  "request_control_key": "01585acf-b0c3-4389-baf3-a58abbe92d58",
  "recurrence_type": "variable_amount",
  "minimum_transaction_amount": 50.00,
  "periodicity": "monthly",
  "journey_type": "journey_one",
  "start_date": "2025-07-01",
  "is_retry_allowed": true,
  "payer_account_information": {
    "owner_name": "John Doe",
    "document_number": "06975239000136",
    "ispb": "32402502",
    "account_digit": "7",
    "account_branch": "3",
    "account_number": "9552432"}
```

### Objeto Request Body

| Campo                           | Tipo           | Descrição                                                    | Máx. Caract. |
|--------------------------------|----------------|--------------------------------------------------------------|--------------|
| **request_control_key***       | string         | Chave única de identificação da request no formato uuid4    | 36           |
| **recurrence_type***           | string         | Tipo de recorrência (fixed_amount ou variable_amount)       | 20           |
| **transaction_amount**         | number, null   | Valor da transação para recorrência de valor fixo (fixed_amount) | 10           |
| **minimum_transaction_amount** | number, null   | Valor mínimo da transação para recorrência de valor variável (variable_amount) | 10           |
| **periodicity***               | string         | Periodicidade da recorrência                                 | 20           |
| **journey_type***              | string         | Tipo da jornada de autorização                               | 50           |
| **start_date***                | string         | Data de início da recorrência (formato YYYY-MM-DD)          | 10           |
| **end_date**                   | string, null   | Data de término da recorrência (formato YYYY-MM-DD)         | 10           |
| **is_retry_allowed***          | boolean        | Permissão para retentativa de transação                     | -            |
| **payer_account_information*** | object         | Dados da conta do pagador                                    | -            |
| **pix_message**                | string, null   | Mensagem PIX associada à transação                          | 140          |

:::caution Observação
Pelo menos um dos campos `transaction_amount` ou `minimum_transaction_amount` deve ser fornecido com um valor não nulo. Ambos os campos não podem ser nulos simultaneamente.
:::

### Objeto payer_account_information

| Campo                      | Tipo   | Descrição                                           | Máx. Caract. |
|----------------------------|--------|-----------------------------------------------------|--------------|
| **owner_name***            | string | Nome do titular da conta                            | 150          |
| **document_number***       | string | CPF ou CNPJ do titular da conta (apenas números)   | 14           |
| **ispb***                  | string | Código ISPB da instituição financeira              | 8            |
| **account_digit***         | string | Dígito da conta                                     | 1            |
| **account_branch***        | string | Agência da conta                                    | 6            |
| **account_number***        | string | Número da conta                                     | 20           |

:::info Tipos de Recorrência
- **Recorrência de valor fixo (fixed_amount)**: Utilize o campo `transaction_amount` e não envie `minimum_transaction_amount`
- **Recorrência de valor variável (variable_amount)**: Utilize o campo `minimum_transaction_amount` e não envie `transaction_amount`
:::

## Response

STATUS 200

Response Body

```json
{
    "incoming_recurrence_key": "e13c5986-f4d1-4d07-a56b-eda90862630a",
    "incoming_recurrence_spi_id": "RR32402502202507170197A5B7CB9",
    "incoming_recurrence_status": "pending_confirmation",
    "created_at": "2025-07-17T14:44:38Z",
    "account_key": "ba685cfd-3aee-4992-b6bf-58f8038faa6b"
}
```

### Response Body

| Campo                         | Tipo       | Descrição                                                    | Caracteres |
|-------------------------------|------------|--------------------------------------------------------------|------------|
| `incoming_recurrence_key`     | uuid       | Chave única de identificação da recorrência de entrada      | 36         |
| `incoming_recurrence_spi_id`  | string     | Identificador SPI da recorrência de entrada                 | 29         |
| `incoming_recurrence_status`  | enumerator | Status atual da recorrência de entrada                      | [Enumeradores incoming_recurrence_status](#enumeradores-incoming_recurrence_status) |
| `created_at`                  | string     | Data e hora de criação da recorrência (formato ISO 8601)    | -          |
| `account_key`                 | uuid       | Chave única de identificação da conta                       | 36         |

### Enumeradores incoming_recurrence_status

| Enumerador              | Descrição                           |
|-------------------------|-------------------------------------|
| `pending_confirmation`  | Recorrência pendente de confirmação |
| `active`                | Recorrência ativa                   |
| `cancelled`             | Recorrência cancelada               |
| `suspended`             | Recorrência suspensa                |
| `expired`               | Recorrência expirada                |

## 2 - Simulação de criação de pagamento

### Request

ENDPOINT /mock/incoming_recurrence/ INCOMING_RECURRENCE_SPI_ID /outgoing_payment
MÉTODO POST

Request Body

```json
{
  "transaction_amount": 100.50,
  "target_account_data": {
    "owner_name": "John Doe",
    "owner_document_number": "06975239000136",
    "ispb": "32402502",
    "account_digit": "7",
    "account_branch": "3",
    "account_type": "checking_account",
    "account_number": "9552432"
  },
  "receiver_conciliation_id": "3d7d6a2bf72f44z7bb2079a2b94dff56452",
  "outgoing_payment_spi_id": "7d2d1b6cd72f44z7bb2079a2b94dff52673",
  "end_to_end_id": "E60701190202110191604DY5LHIZ9O66",
  "next_execution_datetime": "2023-06-01"
}
```

### Objeto Request Body

| Campo                         | Tipo   | Descrição                                                    | Máx. Caract. |
|-------------------------------|--------|--------------------------------------------------------------|--------------|
| **transaction_amount***       | number | Valor da transação                                           | 10           |
| **target_account_data**       | object | Dados da conta de destino                                    | -            |
| **receiver_conciliation_id*** | string | Identificação de conciliação do recebedor                    | 35           |
| **outgoing_payment_spi_id***  | string | Identificador SPI do pagamento                               | 20           |
| **end_to_end_id***            | string | Chave de idempotência da transação PIX no SPI               | 32           |
| **next_execution_datetime**   | string | Data e hora da próxima execução (formato YYYY-MM-DD)        | 10           |

### Objeto target_account_data

| Campo                      | Tipo   | Descrição                                           | Máx. Caract. |
|----------------------------|--------|-----------------------------------------------------|--------------|
| **owner_name***            | string | Nome do titular da conta                            | 150          |
| **owner_document_number*** | string | CPF ou CNPJ do titular da conta (apenas números)   | 14           |
| **ispb_number***                  | string | Código ISPB da instituição financeira              | 8            |
| **account_digit***         | string | Dígito da conta                                     | 1            |
| **account_branch***        | string | Agência da conta                                    | 6            |
| **account_type***          | string | Tipo da conta                                       | 20           |
| **account_number***        | string | Número da conta                                     | 20           |

### Enumerador account_type

| Enumerador           | Descrição           |
|----------------------|---------------------|
| **checking_account** | Conta Corrente      |
| **salary_account**   | Conta Salário       |
| **saving_account**   | Conta Poupança      |
| **payment_account**  | Conta de Pagamentos |

### Enumeradores periodicity

| Enumerador    | Descrição            |
|---------------|----------------------|
| **weekly**    | Recorrência semanal  |
| **monthly**   | Recorrência mensal   |
| **quarterly** | Recorrência trimestral |
| **semiannual**| Recorrência semestral |
| **annual**    | Recorrência anual    |

### Enumeradores journey_type

| Enumerador                     | Descrição                                                                    |
|--------------------------------|------------------------------------------------------------------------------|
| **journey_one**                | Solicitação de autorização mediante uma notificação no aplicativo           |
| **journey_two**                | Solicitação de autorização mediante a leitura de um QR Code                 |
| **journey_three**              | Autorização de recorrência por meio de um pix imediato mediante leitura de um QR Code |
| **journey_four**               | Pagamento ou agendamento de um pix com uma solicitação de autorização da recorrência em sequência |

---

# Webhooks

URL: /documentation/baas/pix_automatico/movimentacoes/webhooks

Uma vez que as transferências ocorrem de forma assíncrona, é de suma importância o mapeamento e o tratamento corretos
dos webhooks enviados.

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeados de forma restrita.
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

## Webhook para criação da recorrência de Pix Automático  

Webhook destinado com as informações de criação de recorrência do cliente

### Webhook Request Body

Request Body: Criação de recorrência

```json
{
    "webhook_type": "baas.automatic_pix.incoming_recurrence",
    "webhook_datetime": "2025-10-22T20:30:23.459Z",
    "data": {
        "account_key": "13385acf-b0c3-4389-baf3-a58abbe92d58",
        "incoming_recurrence_key": "12385acf-b0c3-4389-baf3-a58abbe92d58",
        "incoming_recurrence_status": "pending_confirmation",
        "transaction_amount": "150.00",
        "periodicity": "monthly",
        "journey_type": "journey_one",
        "pix_transfer_type": "key",
        "end_to_end_id": "E1234567890123456789012",
        "start_date": "2025-06-01",
        "end_date": "2026-06-01",
        "receiver_conciliation_id": "rec-conc-789",
        "target_pix_key": "receiver@bank.com.br",
        "payer_document_number": "12345678900",
        "pix_message": "Pagamento mensal de serviço",
        "created_at": "2025-05-22T10:00:00Z",
        "updated_at": "2025-05-22T12:00:00Z"
    }
}
```

### Webhook Body Param
| Campo                        | Tipo      | Descrição                                                                                                | Max. Caracteres |
|------------------------------|-----------|----------------------------------------------------------------------------------------------------------|-----------------|
| `webhook_type`               | string    | Um enumerador que define o tipo de evento sendo reportado                                                | 23              |
| `webhook_datetime`           | string    | Data e hora do envio do webhook                                                                          | 20              |
| `account_key`                | uuid4     | Chave única de identificação da conta.                                                                   | 36              |
| `incoming_recurrence_key`    | uuid4     | Chave única de identificação da autorização                                                              | 36              |
| `incoming_recurrence_status` | string    | Identificador de status da recorrência Pix.                                                              | [Enumeradores incoming_recurrence_status](#enumeradores-incoming_recurrence_status) |
| `transaction_amount`         | number    | Valor da transferência para ocorrência de valor fixo.                                                    | 10              |
| `minimum_transaction_amount` | number    | Valor mínimo da transferência para ocorrência de valor variável.                                         | 10              |
| `maximum_transaction_amount` | number    | Valor máximo da transferência para ocorrência de valor variável.                                         | 10              |
| `periodicity`                | enum      | Tipo da periodicidade associada ao pagamento                                                             | [Enumeradores periodicity](#enumeradores-periodicity) |
| `journey_type`               | enum      | Tipo da jornada de solicitação                                                                            | [Enumeradores journey_type](#enumeradores-journey_type) |
| `pix_transfer_type`          | enum      | Tipo do Pix a ser realizado                                                                              | [Enumeradores pix_transfer_type](#enumeradores-pix_transfer_type) |
| `end_to_end_id`              | string    | Chave de idempotência de uma transação Pix dentro do SPI.                                                | 32              |
| `start_date`                 | string    | Data de início da recorrência                                                                            | -               |
| `end_date`                   | string    | Data de término da recorrência, para os casos de tempo indeterminado, enviar como null                   | -               |
| `receiver_conciliation_id`   | string    | Identificação de conciliação do recebedor.                                                               | 35              |
| `target_pix_key`             | string    | Chave Pix da conta da transação.                                                                         | 100             |
| `payer_document_number`      | string    | Número de documento do pagador da transação                                                              | 14              |
| `pix_message`                | string    | Mensagem a ser enviada junto à transferência Pix.                                                        | 140             |
| `created_at`                 | string    | Horário da criação da solicitação de recorrência                                                         | -               |
| `updated_at`                 | string    | Horário de atualização da solicitação de recorrência                                                     | -               |

### Enumerador incoming_recurrence_status

| Enumerador           | Descrição           |
|----------------------|---------------------|
| `pending_confirmation` | Recorrência pendente de confirmação      |
| `active`   | Recorrência ativa       |
| `cancelled`   | Recorrência cancelada      |
| `suspended`  | Recorrência suspensa |
| `expired`  | Recorrência expirada |

### Enumeradores periodicity
| Enumerador       | Descrição          |
|------------------|--------------------|
| `weekly` | Recorrência semanal |
| `monthly` | Recorrência mensal  |
| `quarterly` | Recorrência trimestral     |
| `semiannual` | Recorrência semestral     |
| `annual` | Recorrência anual      |

### Enumeradores journey_type
| Enumerador       | Descrição          |
|------------------|--------------------|
| `journey_one` | Solicitação de autorização mediante uma notificação no aplicativo |
| `journey_two` | Solicitação de autorização mediante a leitura de um QR Code  |
| `journey_three` | Autorização de recorrência por meio de um pix imediato mediante leitura de um QR Code     |
| `journey_four` | Pagamento ou agendamento de um pix com uma solicitação de autorização da recorrência em sequência      |

### Enumeradores pix_transfer_type

| Enumerador          | Descrição                                |
|---------------------|------------------------------------------|
| `manual`          | Pix utilizando os dados da conta destino |
| `key`             | Pix utilizando uma chave pix             |
| `static_qr_code`  | Pix utilizando um QR code estático       |
| `dynamic_qr_code` | Pix utilizando um QR code dinâmico       |

[//]: # (Break here for new page -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------)

---

# Atualizar Valor da Ordem de Pagamento

URL: /documentation/baas/pix_automatico/pagamentos/atualizar_payment_order

## Request

ENDPOINT /account/ ACCOUNT_KEY /outgoing_recurrence/ OUTGOING_RECURRENCE_KEY /payment_order/ PAYMENT_ORDER_KEY
MÉTODO PATCH

### Path Params

| Campo                    | Tipo   | Descrição                                          | Caracteres |
|--------------------------|--------|----------------------------------------------------|------------|
| `ACCOUNT_KEY`            | uuidv4 | Chave única de identificação da conta.             | 36         |
| `OUTGOING_RECURRENCE_KEY`| uuidv4 | Chave única da recorrência a ser atualizada.       | 36         |
| `PAYMENT_ORDER_KEY`      | uuidv4 | Chave única da ordem de pagamento a ser atualizada.| 36         |

### Request Body

Atualizar Payment Order

```json
{
    "transaction_amount": 100
}
```

### Request Body Params

| Campo                | Tipo   | Descrição                          | Caracteres |
|----------------------|--------|------------------------------------|------------|
| `transaction_amount` | floating | Valor da transação a ser atualizado.| -          |

## Response

STATUS 200

Response Body

```json
{}
```

STATUS 4XX

Response Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em português",
  "code": "codigo"
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                | Descrição (eng)<br/>`description`                                          | Descrição (ptbr)<br/>`translation`                                 |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400         | QIT000002            | Bad Request                       | Invalid request schema.                                                    | Erro no esquema da requisição.                                     |
| 404         | APX000404            | Payment Order Not Found      | Payment Order \{payment_order_key\} not found.                   | Lote de conciliação \{payment_order_key\} não encontrado.      |

---

# Cancelar uma Ordem de Pagamento

URL: /documentation/baas/pix_automatico/pagamentos/cancelar_payment_order

Este endpoint permite cancelar uma ordem de pagamento específica associada a uma recorrência automática Pix.

:::warning
Só é possível cancelar uma payment order que está em status de pending_conciliation ou pending, até as 22h do dia anterior ao reference_date.
:::

## Request

ENDPOINT /automatic_pix/account/ ACCOUNT_KEY /outgoing_recurrence/ OUTGOING_RECURRENCE_KEY /payment_order/ PAYMENT_ORDER_KEY /cancel
MÉTODO PATCH

### Path Params

| Campo                    | Tipo   | Descrição                                          | Caracteres |
|--------------------------|--------|----------------------------------------------------|------------|
| `ACCOUNT_KEY`            | uuidv4 | Chave única de identificação da conta.             | 36         |
| `OUTGOING_RECURRENCE_KEY`| uuidv4 | Chave única da recorrência.                        | 36         |
| `PAYMENT_ORDER_KEY`      | uuidv4 | Chave única da ordem de pagamento a ser cancelada. | 36         |

### Request Body

Cancelar Payment Order

```json
{}
```

## Response

STATUS 200

Response Body

```json
{
    "payment_order_key": "10fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "payment_order_conciliation_batch_key": "11fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "payment_order_status": "cancelled"
}
```

### Response Body Params

| Campo                                  | Tipo   | Descrição                                          | Caracteres |
|----------------------------------------|--------|----------------------------------------------------|------------|
| `payment_order_key`                    | string | Chave única da ordem de pagamento.                 | 36         |
| `payment_order_conciliation_batch_key` | string | Chave do lote de conciliação da ordem de pagamento.| 36         |
| `payment_order_status`                 | string | Status atual da ordem de pagamento.                | -          |

### Enumeradores payment_order_status

| Enumerador            | Descrição                                          |
|-----------------------|----------------------------------------------------|
| `pending_conciliation`| Aguardando conciliação.                            |
| `pending`             | Pendente e ainda não processada.                   |
| `accepted`            | Aceita e aguardando pagamento.                     |
| `paid`                | Paga com sucesso.                                  |
| `rejected`            | Rejeitada e não será processada.                   |
| `cancelled`           | Cancelada antes do pagamento.                      |

STATUS 4XX

Response Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em português",
  "code": "codigo"
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                | Descrição (eng)<br/>`description`                                          | Descrição (ptbr)<br/>`translation`                                 |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400         | QIT000002            | Bad Request                       | Invalid request schema.                                                    | Erro no esquema da requisição.                                     |
| 404         | APX000404            | Payment Order Not Found      | Payment Order \{payment_order_key\} not found.                   | Lote de conciliação \{payment_order_key\} não encontrado.      |

---

# Consultar Payment Order

URL: /documentation/baas/pix_automatico/pagamentos/consultar_payment_order

## Request

Este endpoint permite consultar os detalhes de uma payment order específica associada a uma recorrência automática Pix.

ENDPOINT /account/ ACCOUNT_KEY /outgoing_recurrence/ OUTGOING_RECURRENCE_KEY /payment_order/ PAYMENT_ORDER_KEY
MÉTODO GET

### Path Params

| Campo                    | Tipo   | Descrição                                         | Caracteres |
|--------------------------|--------|---------------------------------------------------|------------|
| `account_key`            | uuidv4 | Chave única de identificação da conta.            | 36         |
| `outgoing_recurrence_key`| uuidv4 | Chave única da recorrência a ser consultada.      | 36         |
| `payment_order_key`      | uuidv4 | Chave única da ordem de pagamento a ser consultada.| 36         |

## Response Body

STATUS 200

Response Body

```json
{
    "outgoing_recurrence_spi_id": "RR2222222220240429njua7shf40k",
    "payment_order_status": "paid",
    "reference_date": "2025-06-30",
    "payment_order_conciliation_batch_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "receiver_conciliation_id": "cac0b5f7-4ee2-40f1-b2ad-16902506503d",
    "transaction_amount": 125.53,
    "transaction_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc56",
    "incoming_pix_transfer_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc56",
    "debtor_account_data": {
        "account_number": "897465",
        "account_digit": "1",
        "account_branch": "0123",
        "ispb": "323243"
    },
    "created_at": "2021-10-22T20:30:23.459Z",
    "paid_at": "2023-10-22T20:30:23.459Z",
    "payment_order_attempts": [
        {
            "payment_order_attempt_key": "uuid",
            "end_to_end_id": "id",
            "payment_order_attempt_status": "sent",
            "payment_order_attempt_error": {
                "code": "code",
                "description": "description do error",
                "translation": "translation"
            },
            "created_at": "2021-10-22T20:30:23.459Z"
        }
    ]
}
```

### Response Body Params

| Campo                              | Tipo     | Descrição                                                                 | Caracteres |
|------------------------------------|----------|---------------------------------------------------------------------------|------------|
| `outgoing_recurrence_spi_id`       | string   | ID da SPI da recorrência automática.                                      | 36         |
| `payment_order_status`             | string   | Status atual da ordem de pagamento.                                       |[Enumeradores payment_order_status](#payment_order_status)        |
| `reference_date`                   | string   | Data de referência da cobrança.                                           | 10         |
| `payment_order_conciliation_batch_key`| uuidv4 | Chave do lote de conciliação da ordem de pagamento.                       | 36         |
| `receiver_conciliation_id`         | uuidv4   | ID de conciliação do recebedor.                                           | 36         |
| `transaction_amount`               | number   | Valor da transação.                                                       | -          |
| `transaction_key`                  | uuidv4   | Chave única da transação.                                                 | 36         |
| `incoming_pix_transfer_key`        | uuidv4   | Chave de transferência Pix recebida.                                      | 36         |
| `debtor_account_data`              | object   | Dados da conta devedor.                                                   | [Objeto debtor_account_data](#objeto-debtor_account_data) |
| `created_at`                       | string   | Data/hora de criação da ordem.                                            | -          |
| `paid_at`                          | string   | Data/hora do pagamento efetuado.                                          | -          |
| `payment_order_attempts`           | array    | Tentativas de pagamento da ordem.                                         | [Array payment_order_attempts](#array-payment_order_attempts) |

### Objeto debtor_account_data

| Campo            | Tipo   | Descrição                  | Caracteres |
|------------------|--------|----------------------------|------------|
| `account_number` | string | Número da conta            | -          |
| `account_digit`  | string | Dígito da conta            | -          |
| `account_branch` | string | Agência                    | -          |
| `ispb`           | string | ISPB da instituição financeira | -       |

### Array payment_order_attempts

| Campo                        | Tipo     | Descrição                                                      | Caracteres |
|------------------------------|----------|----------------------------------------------------------------|------------|
| `payment_order_attempt_key`  | string   | Chave única da tentativa de pagamento.                         | 36         |
| `end_to_end_id`              | string   | Identificador end-to-end da tentativa.                         | 36         |
| `payment_order_attempt_status`| string  | Status da tentativa de pagamento.                              | -          |
| `payment_order_attempt_error`| object   | Erro associado à tentativa de pagamento.                       | [Objeto payment_order_attempt_error](#objeto-payment_order_attempt_error) |
| `created_at`                 | string   | Data/hora de criação da tentativa.                             | -          |

### Objeto payment_order_attempt_error

| Campo       | Tipo   | Descrição               | Caracteres |
|-------------|--------|-------------------------|------------|
| `code`      | string | Código do erro.         | -          |
| `description`| string | Descrição do erro.     | -          |
| `translation`| string | Tradução da descrição. | -          |

### Enumeradores payment_order_status

| Enumerador            | Descrição                                          |
|-----------------------|----------------------------------------------------|
| `pending_conciliation`| Aguardando conciliação.                            |
| `pending`             | Pendente e ainda não processada.                   |
| `accepted`            | Aceita e aguardando pagamento.                     |
| `paid`                | Paga com sucesso.                                  |
| `rejected`            | Rejeitada e não será processada.                   |
| `cancelled`           | Cancelada antes do pagamento.                      |

STATUS 4XX

Response Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em português",
  "code": "codigo"
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                | Descrição (eng)<br/>`description`                                          | Descrição (ptbr)<br/>`translation`                                 |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400         | QIT000002            | Bad Request                       | Invalid request schema.                                                    | Erro no esquema da requisição.                                     |
| 404         | APX000002            | Payment Order Not Found           | Payment order \{payment_order_key\} not found.                             | Ordem de pagamento \{payment_order_key\} não encontrada.            |

---

# Listar Payment Orders por Conta

URL: /documentation/baas/pix_automatico/pagamentos/listar_account_payment_orders

Este endpoint permite listar as ordens de pagamento associadas a uma conta específica.

ENDPOINT /account/ ACCOUNT_KEY /payment_orders
MÉTODO GET

### Path Params

| Campo        | Tipo   | Descrição                                             | Caracteres |
|--------------|--------|-------------------------------------------------------|------------|
| `account_key`| uuidv4 | Chave única de identificação da conta.                | 36         |

### Query Params

| Campo                | Tipo   | Descrição                                        | Caracteres |
|----------------------|--------|--------------------------------------------------|------------|
| `payment_order_status`| string | Filtra as ordens por status (e.g., `paid`).     | -          |
| `start_date`         | string | Data de início para filtrar ordens (formato YYYY-MM-DD). | 10         |
| `end_date`           | string | Data de fim para filtrar ordens (formato YYYY-MM-DD).   | 10         |

## Response Body

STATUS 200

Response Body

```json
{
    "payment_orders": [
        {
            "payment_order_key": "a1b2c3d4-e5f6-4789-a123-456789abcdef",
            "payment_order_spi_id": "1a2b3c4d5e6f7890abcdef1234567890",
            "outgoing_recurrence_key": "b2c3d4e5-f6a7-4890-b234-567890abcdef",
            "outgoing_recurrence_spi_id": "RR3240250220251025A1B2C3D4E5F",
            "payment_order_conciliation_batch_key": "c3d4e5f6-a7b8-4901-c345-678901abcdef",
            "payment_order_status": "pending_conciliation",
            "reference_date": "2025-11-15",
            "receiver_conciliation_id": "2b3c4d5e6f7890abcdef1234567890ab",
            "transaction_amount": null,
            "account_key": "d4e5f6a7-b8c9-4012-d456-789012abcdef",
            "transaction_key": null,
            "incoming_pix_transfer_key": null,
            "debtor_account_data": {
                "ispb": "31872495",
                "account_digit": "7",
                "account_branch": "0001",
                "account_number": "123456"
            },
            "created_at": "2025-10-15T03:00:12Z",
            "paid_at": null,
            "payment_order_attempts": []
        },
        {
            "payment_order_key": "e5f6a7b8-c9d0-4123-e567-890123abcdef",
            "payment_order_spi_id": "3c4d5e6f7890abcdef1234567890abcd",
            "outgoing_recurrence_key": "f6a7b8c9-d0e1-4234-f678-901234abcdef",
            "outgoing_recurrence_spi_id": "RR3240250220251025B2C3D4E5F6A",
            "payment_order_conciliation_batch_key": "c3d4e5f6-a7b8-4901-c345-678901abcdef",
            "payment_order_status": "pending",
            "reference_date": "2025-11-15",
            "receiver_conciliation_id": "4d5e6f7890abcdef1234567890abcdef",
            "transaction_amount": 220.00,
            "account_key": "d4e5f6a7-b8c9-4012-d456-789012abcdef",
            "transaction_key": null,
            "incoming_pix_transfer_key": null,
            "debtor_account_data": {
                "ispb": "31872495",
                "account_digit": "7",
                "account_branch": "0001",
                "account_number": "123456"
            },
            "created_at": "2025-10-15T03:00:10Z",
            "paid_at": null,
            "payment_order_attempts": []
        }
    ],
    "pagination": {
        "page": 1,
        "page_size": 25,
        "number_of_pages": 9
    }
}
```

### Response Body Params

| Campo                                  | Tipo     | Descrição                                                           | Caracteres |
|----------------------------------------|----------|---------------------------------------------------------------------|------------|
| `payment_order_key`                    | uuidv4   | Chave única da ordem de pagamento.                                  | 36         |
| `payment_order_spi_id`                 | string   | ID da SPI da ordem de pagamento.                                    | 32         |
| `outgoing_recurrence_key`              | uuidv4   | Chave única da recorrência de saída.                               | 36         |
| `outgoing_recurrence_spi_id`           | string   | ID da SPI da recorrência automática.                               | 27         |
| `payment_order_conciliation_batch_key` | uuidv4   | Chave do lote de conciliação da ordem de pagamento.                | 36         |
| `payment_order_status`                 | string   | Status atual da ordem de pagamento.                                | -          |
| `reference_date`                       | string   | Data de referência da cobrança.                                    | 10         |
| `receiver_conciliation_id`             | string   | ID de conciliação do recebedor.                                    | 32         |
| `transaction_amount`                   | number   | Valor da transação (pode ser null).                                | -          |
| `account_key`                          | uuidv4   | Chave única da conta.                                               | 36         |
| `transaction_key`                      | uuidv4   | Chave única da transação (pode ser null).                          | 36         |
| `incoming_pix_transfer_key`            | uuidv4   | Chave de transferência Pix recebida (pode ser null).               | 36         |
| `debtor_account_data`                  | object   | Dados da conta do devedor.                                          | [Objeto debtor_account_data](#objeto-debtor_account_data) |
| `created_at`                           | string   | Data/hora de criação da ordem (formato ISO 8601).                  | -          |
| `paid_at`                              | string   | Data/hora do pagamento efetuado (formato ISO 8601, pode ser null). | -          |
| `payment_order_attempts`               | array    | Tentativas de pagamento da ordem.                                   | [Array payment_order_attempts](#array-payment_order_attempts) |

### Objeto debtor_account_data

| Campo            | Tipo   | Descrição                  | Caracteres |
|------------------|--------|----------------------------|------------|
| `account_number` | string | Número da conta            | -          |
| `account_digit`  | string | Dígito da conta            | -          |
| `account_branch` | string | Agência                    | -          |
| `ispb`           | string | ISPB da instituição financeira | -       |

### Array payment_order_attempts

| Campo                        | Tipo     | Descrição                                                      | Caracteres |
|------------------------------|----------|----------------------------------------------------------------|------------|
| `payment_order_attempt_key`  | string   | Chave única da tentativa de pagamento.                         | 36         |
| `end_to_end_id`              | string   | Identificador end-to-end da tentativa.                         | 32         |
| `due_date`                   | string   | Data de vencimento da tentativa (formato YYYY-MM-DD, pode ser null). | 10         |
| `payment_order_attempt_status`| string  | Status da tentativa de pagamento.                              | -          |
| `payment_order_attempt_error`| object   | Erro associado à tentativa de pagamento (pode ser null).       | [Objeto payment_order_attempt_error](#objeto-payment_order_attempt_error) |
| `sent_at`                    | string   | Data/hora de envio da tentativa (formato ISO 8601, pode ser null). | -          |
| `created_at`                 | string   | Data/hora de criação da tentativa (formato ISO 8601).          | -          |

### Objeto payment_order_attempt_error

| Campo       | Tipo   | Descrição               | Caracteres |
|-------------|--------|-------------------------|------------|
| `code`      | string | Código do erro.         | -          |
| `description`| string | Descrição do erro.      | -          |
| `translation`| string | Tradução da descrição. | -          |

### Enumeradores payment_order_status

| Enumerador              | Descrição                                          |
|-------------------------|----------------------------------------------------|
| `pending_conciliation`  | A ordem de pagamento está pendente de conciliação |
| `pending`               | A ordem de pagamento está pendente                |
| `accepted`              | A ordem de pagamento foi aceita                   |
| `paid`                  | A ordem de pagamento foi paga                     |
| `rejected`              | A ordem de pagamento foi rejeitada                |
| `cancelled`             | A ordem de pagamento foi cancelada                |

STATUS 4XX

Response Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em português",
  "code": "codigo"
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                | Descrição (eng)<br/>`description`                                          | Descrição (ptbr)<br/>`translation`                                 |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400         | QIT000002            | Bad Request                       | Invalid request schema.                                                    | Erro no esquema da requisição.                                     |
| 404         | APX000002            | Payment Order Not Found           | Payment order \{payment_order_key\} not found.                             | Ordem de pagamento \{payment_order_key\} não encontrada.            |

---

# Decodificar QR Code para Pix Automático

URL: /documentation/baas/pix_automatico/qr_code/decodificar_qr_code

## Request

ENDPOINT /account/ ACCOUNT_KEY /qrcode/decode
MÉTODO POST

### Request Path Params

| Campo       | Tipo   | Descrição                      | Caracteres |
|-------------|--------|--------------------------------|------------|
| `account_key` * | uuid4  | Chave única de identificação da conta. | 36 |

### Request Body

Request Body: Decodificar QR Code

```json
{
    "qr_code_payload": "00020101021226840014br.gov.bcb.pix2562invoice.starkbank.com/v2/cobv/8b434df48c30482a81f7c936ae35cc87080400005303986540555.595802BR5925Stark Bank S.A.6015Sao Caetano do Sul62070503***80740014br.gov.bcb.pix2552pix.example.com/rec/2353c790eefb11eaadc10242ac120002630411FC"
}
```

### Body Params

| Campo                   | Tipo       | Descrição                                                                                                                                                                                                                                        | Caracteres |
|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `qr_code_payload` *           | string     | URL do PIX Copia e Cola                                                                                                                                                                                                | -        |

## Response

STATUS 200

Response Body: QR decodificado

```json
{
    "end_to_end_id": "E32402502202303101532yCipbxgUnUj",
    "qr_code_payload": "00020101021226840014br.gov.bcb.pix2562invoice.starkbank.com/v2/cobv/8b434df48c30482a81f7c936ae35cc87080400005303986540555.595802BR5925Stark Bank S.A.6015Sao Caetano do Sul62070503***80740014br.gov.bcb.pix2552pix.example.com/rec/2353c790eefb11eaadc10242ac120002630411FC",
    "qr_code_key": "8c2c19bd-f260-4714-955c-956f3eaa30ca",
    "qr_code_type": "dynamic_composed",
    "qr_code_data": {
        "incoming_recurrence": {
            "incoming_recurrence_key": "67abc123-4567-89ab-cdef-1234567890ab",
            "journey_type": "j2_recurrence_only_qrcode",
            "incoming_recurrence_type": "variable_amount",
            "incoming_recurrence_status": "pending_confirmation",
            "start_date": "2024-08-01",
            "end_date": null,
            "periodicity": "weekly",
            "target_pix_key": "teste.recorrencia@email.com.br",
            "minimum_transaction_amount": "100.00",
            "maximum_transaction_amount": "500.00",
            "transaction_amount": null,
            "is_retry_allowed": true,
            "created_at": "2024-07-23T14:30:45.123Z",
            "payer_document_number": "12345678901",
            "payer_name": "João da Silva",
            "payer_account_key": "a5d7e60f-1c9b-4b8a-9de7-6f3b919cc45d",
            "request_control_key": "c7d7e60f-1c9b-4b8a-9de7-6f3b919cc45f",
            "receiver_conciliation_id": "RRAUTOTESTE001",
            "pix_message": "Autorização de débito mensal"
        },
        "payment_data": {
            "request_control_key": "c7d7e60f-1c9b-4b8a-9de7-6f3b919cc45f",
            "transaction_amount": "150.75",
            "target_pix_key": "teste.recorrencia@email.com.br",
            "target_account": null,
            "receiver_conciliation_id": "fgnb4NTt7pOUBGfrcporERwVVqr0f8PWRfK",
            "pix_message": "Assinatura mensal do serviço"
        }
    }
}
```

| Campo                          | Tipo    | Descrição                                                                                                                                                                                                                                                                                     | Max. Caracteres                                                   |
|--------------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `end_to_end_id`        | string     | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na consulta de chave Pix. | 32 |
| `qr_code_payload`          | string     | URL do PIX Copia Cola  |  |
| `qr_code_key`  | uuid4    | Chave única de identificação do qr code                                                                                                                                                              | 36         |         
 `qr_code_data`       | Object     | Dados dos qr code | [Objeto qr_code_data](#objeto-qr_code_data) | 10 |

### Objeto qr_code_data

| Campo                     | Tipo       | Descrição                                           | Caracteres                                              |
|---------------------------|------------|-----------------------------------------------------|---------------------------------------------------------|
| `incoming_recurrence`         | objeto     | Objeto de identificação da recorrência |   [Objeto incoming_recurrence](#objeto-incoming_recurrence)                                                     |
| `payment_data`          | objeto     | Objeto com informações de pagamento para journey_types: *j3_payment_and_recurrence_qrcode*, *j4_recurrence_offer_post_payment* | [Objeto payment_data](#objeto-payment_data)  

### Objeto incoming_recurrence

| Campo                     | Tipo       | Descrição                                           | Caracteres                                              |
|---------------------------|------------|-----------------------------------------------------|---------------------------------------------------------|
| `incoming_recurrence_key`  | uuid4    | Chave única de identificação da autorização                                                                                                                                                              | 36         | 
| `incoming_recurrence_status`               | string  |Identificador de status da recorrência                                                                                                                                         | [Enumerador incoming_recurrence_status](#enumerador-incoming_recurrence_status)                                                           |
| `request_control_key`  | uuid4     | Chave única de identificação da request utilizada pelo cliente                                                                                                                                                              | 36         | 
| `transaction_amount`   | number     | Valor da transferência para ocorrência de valor fixo.                                                                                                                                                                                                                         | 10         |
| `minimum_transaction_amount`   | number     | Valor mínimo da transferência para ocorrência de valor variável.                                                                                                                                                                                                                         | 10         |
| `maximum_transaction_amount`   | number     | Valor máximo da transferência para ocorrência de valor valor variável.                                                                                                                                                                                                                         | 10         |
| `periodicity`    | enumerator | Tipo da periodicidade associada ao pagamento                                                                                                                                           | [Enumeradores periodicity](#enumeradores-periodicity)     |
| `journey_type`    | enumerator | Tipo da jornada de solicitação                                                                                                                                                    | [Enumeradores journey_type](#enumeradores-journey_type)     |
| `end_to_end_id`        | string     | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na consulta de chave Pix. | 32 |
| `start_date`    | string | Data de ínicio da recorrência                                                                                                                                                         | -      |
| `end_date`   | string | Data de término da recorrência, para os casos de tempo indeterminado, enviar como null                                                                                                                        
| `next_execution_date`    | string | Data de execução da próxima transação da recorrência                                                                                                                                                      | -      |
| `receiver_conciliation_id` | string     | Identicação de conciliação do recebedor. | 35                                        |
| `target_pix_key`       | string     | Chave pix da conta da transação.                                                                                                                                                                                                    | 100        |
| `is_retry_allowed`           | boolean     | Permissão para retentativa de transação Pix.                                                                                                                                                                                                | -        |
| `payer_document_number`       | string     | Número de documento do pagador da transação transação.                                                                                                                                                                                                    | 14        |
| `payer_name`       | string     | Nome do pagador da transação transação.                                                                                                                                                                                                    | -        |
| `payer_account_key`       | string     | Identificador da conta do pagador da transação transação.                                                                                                                                                                                                    | -        |
| `pix_message`           | string     | Mensagem a ser enviada junto à transferência Pix.                                                                                                                                                                                                | 140        |
| `created_at`              | string  | Horário da criação da solicitação de recorrência                                                                                                                                       | -          

### Objeto payment_data

| Campo                     | Tipo       | Descrição                                           | Caracteres                                              |
|---------------------------|------------|-----------------------------------------------------|---------------------------------------------------------|
| `request_control_key`  | uuid4     | Chave única de identificação da request utilizada pelo cliente                                                                                                                                                              | 36         |
| `transaction_amount`   | number     | Valor da transferência para ocorrência de valor fixo.                                                                                                                                                                                                                         | 10         |
| `target_pix_key`       | string     | Chave pix da conta da transação.                                                                                                                                                                                                    | 100        |
| `target_account`       | Object     | Conta destino em transferências manuais. | [Objeto target_account](#objeto-target_account) | 10 |
| `receiver_conciliation_id` | string     | Identicação de conciliação do recebedor. | 35                                        |
| `pix_message`           | string     | Mensagem a ser enviada junto à transferência Pix.                                                                                                                                                                                                | 140        |

### Objeto target_account

| Campo                     | Tipo       | Descrição                                           | Caracteres                                              |
|---------------------------|------------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch`         | string     | Agência da conta.                                   | 6                                                       |
| `account_digit`          | string     | Dígito da conta.                                    | 1                                                       |
| `account_number`         | string     | Número da conta.                                    | 20                                                      |
| `owner_document_number`  | string     | CPF ou CNPJ (apenas números) do titular da conta.   | 14                                                      |
| `owner_name`             | string     | Nome do titular da conta.                           | 150                                                     |
| `account_type`          | enumerator | Tipo da conta.                                      | [Enumerador account_type](#enumerador-account_type) |
| `ispb`                   | string     | Base no CNPJ da instituição financeira (8 dígitos). | 8                                                       |

:::info
Diferentes enumeradores podem significar o mesmo tipo de conta devido a informação retornada por diferentes
instituições.
:::
### Enumerador account_type

| Enumerador           | Descrição           |
|----------------------|---------------------|
| `checking_account`| Conta Corrente      |
| `salary_account`   | Conta Salário       |
| `saving_account`   | Conta Poupança      |
| `payment_account`  | Conta de Pagamentos |

### Enumerador incoming_recurrence_status

| Enumerador           | Descrição           |
|----------------------|---------------------|
| **pending_confirmation** | Recorrência pendente de confirmação      |
| **active**   | Recorrência ativa       |
| **cancelled**   | Recorrência cancelada      |
| **suspended**  | Recorrência suspensa |
| **expired**  | Recorrência expirada |

### Enumeradores periodicity
| Enumerador       | Descrição          |
|------------------|--------------------|
| `weekly` | Recorrência semanal |
| `monthly` | Recorrência mensal  |
| `quarterly` | Recorrência trimestral     |
| `semiannual` | Recorrência semestral     |
| `annual` | Recorrência anual      |

### Enumeradores journey_type
| Enumerador       | Descrição          |
|------------------|--------------------|
| `j1_in_app_only_recurrence` | Solicitação de autorização mediante uma notificação no aplicativo |
| `j2_recurrence_only_qrcode` | Solicitação de autorização mediante a leitura de um QR Code  |
| `j3_payment_and_recurrence_qrcode` | Autorização de recorrência por meio de um pix imediato mediante leitura de um QR Code     |
| `j4_recurrence_offer_post_payment` | Pagamento ou agendamento de um pix com uma solicitação de autorização da recorrência em sequência      |

### Enumeradores pix_transfer_type

| Enumerador          | Descrição                                |
|---------------------|------------------------------------------|
| `manual`          | Pix utilizando os dados da conta destino |
| `key`             | Pix utilizando uma chave pix             |
| `static_qr_code`  | Pix utilizando um QR code estático       |
| `dynamic_qr_code` | Pix utilizando um QR code dinâmico       |

STATUS 4XX

Response Body

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo"
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`           | Descrição (eng)<br/>`Description`                                   | Descrição (ptbr)<br/>`translation`                                |
|-------------|----------------------|------------------------------|---------------------------------------------------------------------|-------------------------------------------------------------------|
| 400         | QIT000001            | Bad Request	            | Schema Error                                      | Erro de Schema                       |
 403         | APX000025            | User is not allowed to do this transaction        | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 403         | APX000017            | Requester not allowed to access this endpoint        | Requester has no permission to perform pix transfers on this endpoint | Requester não possui permissão de realizar transações pix através deste endpoint |
| 404         | APX000020            | Account not Found             | Account was not found | Conta \{account_key\} não foi encontrada. |

---

# Cancelar recorrência de pagamento

URL: /documentation/baas/pix_automatico/recebedor/cancelar_recorrencia

## Request

ENDPOINT /account/ ACCOUNT_KEY /outgoing_recurrence/ OUTGOING_RECURRENCE_KEY /cancel
MÉTODO PATCH

### Request Path Params

| Campo       | Tipo   | Descrição                      | Caracteres |
|-------------|--------|--------------------------------|------------|
| `account_key` * | uuid4  | Chave única de identificação da conta. | 36 |
| `outgoing_recurrence_key` * | uuid4  | Chave única de identificação da autorização                                    | 36 |

### Request Body

Request Body: Cancelar uma recorrência

```json
{
  "outgoing_recurrence_status": "cancelled",
}
```

### Body Params

| Campo                   | Tipo       | Descrição                                                                                                                                                                                                                                        | Caracteres |
|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `outgoing_recurrence_status` *           | string     | Identificador de status da recorrência Pix.                                                                                                                                                                                                | cancelled        |
## Response

STATUS 200

Response Body: Recorrência cancelada

```json
{
  "outgoing_recurrence_key": "cfa32109-a6dd-4304-94db-03a7b6d92a47",
  "outgoing_recurrence_status": "cancelled",
  "created_at": "2025-05-22T20:30:23.459Z",
  "updated_at": "2025-05-22T20:39:23.459Z"
}
```

STATUS 4XX

Response Body

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo"
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`           | Descrição (eng)<br/>`Description`                                   | Descrição (ptbr)<br/>`translation`                                |
|-------------|----------------------|------------------------------|---------------------------------------------------------------------|-------------------------------------------------------------------|
| 400         | QIT000001            | Bad Request	            | Schema Error                                      | Erro de Schema                       |
 403         | APX000025            | User is not allowed to do this transaction        | User is not allowed to do this transaction | Usuário não tem autorização para fazer essa transação |
| 403         | APX000017            | Requester not allowed to access this endpoint        | Requester has no permission to perform pix transfers on this endpoint | Requester não possui permissão de realizar transações pix através deste endpoint |
| 404         | APX000020            | Account not Found             | Account was not found | Conta \{account_key\} não foi encontrada. |
| 404         | APX000001            | Recurrence not Found        | Recurrence was not found | Recorrência \{outgoing_recurrence_key\} não foi encontrada |

---

# Consultar dados de uma recorrência por outgoing_recurrence_key

URL: /documentation/baas/pix_automatico/recebedor/consultar_recorrencia

## Request

ENDPOINT /account/ ACCOUNT_KEY /outgoing_recurrence/ OUTGOING_RECURRENCE_KEY
MÉTODO GET

### Path Params

| Campo                    | Tipo   | Descrição                                         | Caracteres |
|--------------------------|--------|---------------------------------------------------|------------|
| `account_key` *          | uuidv4 | Chave única de identificação da conta.            | 36         |
| `outgoing_recurrence_key`*| uuidv4 | Chave única da recorrência a ser consultada.      | 36         |

## Response

STATUS 200

Response Body

```json
{
   "request_control_key":"98fc62fd-b0a0-4604-9bea-475e91a9dc82",
   "outgoing_recurrence_key":"8cb70dea-9fb0-4a68-9572-99a72849c8d6",
   "outgoing_recurrence_status":"approved",
   "periodicity":"monthly",
   "journey_type":"journey_four",
   "start_date":"2025-06-10",
   "end_date":"2027-06-10",
   "outgoing_recurrence_data":{
      "minimum_recurrence_amount":123.45,
      "recurrence_amount":null,
      "retry_configuration":{
         "retry_allowed":true,
         "retry_rule":{
            "first_retry":{
               "day":"1",
               "time":"14:00"
            },
            "second_retry":{
               "day":"3",
               "time":"12:00"
            },
            "third_retry":{
               "day":"4",
               "time":"15:32"
            }
         }
      },
      "debtor_data":{
         "name":"Sebastião",
         "email":"sebastiao@test.com",
         "document_number":"05431134850",
         "address":{
            "city":"São Paulo",
            "postal_code":"123456-789",
            "uf":"SP",
            "street":"Av Paulista 123"
         },
         "account_data":{
            "account_number":"123456",
            "account_digit":"7",
            "account_branch":"0001",
            "ispb":"31872495"
         }
      },
      "qr_code_data":{
         "qr_code_key":"0f45cc3d-9bd1-4d68-a865-4cf477b5da45",
         "qr_code_url":"urlqrcode.url",
         "qr_code_image":"image_base64"
      },
      "initial_payment_data":{
         "amount":22.34,
         "pix_key":"3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
         "qr_code_type":"dynamic_term_composed",
         "additional_data":[
            {
               "key_name":"Juros e Multa",
               "value":"Juros 2 ao mes e multa de 1%"
            }
         ],
         "fine_amount":3,
         "interest_amount":2,
         "expiration_date":"2023-03-25",
         "max_payment_days":128,
         "rebate_amount":1,
         "discounts":[],
         "receiver_conciliation_id":"3d7d6a2bf72f44z7bb2079a94dff5645",
         "transaction_data":{
            "transaction_key":"4d7d6a2b-f72f-44z7-bb20-79a94dff5645",
            "pix_transfer_key":"5d7d6a2b-f72f-44z7-bb20-79a94dff5645",
            "end_to_end_id":"E32402502202303141907qlBAF1evdJ2"
         }
      },
      "pix_message":"Conta de Luz Residencial nº123",
      "settlement_date_type":"calendar_days"
      },
      "payment_orders":[
         {
            "payment_order_key":"10fc62fd-b0a0-4604-9bea-475e91a9dc82",
            "payment_order_status":"paid",
            "reference_date":"2025-06-30",
            "receiver_conciliation_id":"cac0b5f74ee240f1b2ad16902506503d",
            "transaction_amount":125.53,
            "transaction_key":"21fc62fd-b0a0-4604-9bea-475e91a9dc56",
            "incoming_pix_transfer_key":"21fc62fd-b0a0-4604-9bea-475e91a9dc56",
            "created_at":"2021-10-22T20:30:23.459Z",
            "paid_at":"2023-10-22T20:30:23.459Z"
         }
      ],
      "outgoing_recurrence_events":[
         {
            "outgoing_recurrence_event_key":"20fc62fd-b0a0-4604-9bea-475e91a9dc82",
            "outgoing_recurrence_status":"created",
            "created_at":"2021-10-22T20:30:23.459Z"
         }
      ]
}
```

### Response Body Params

| Campo                        | Tipo       | Descrição                                                                                   | Caracteres |
|------------------------------|------------|---------------------------------------------------------------------------------------------|------------|
| `request_control_key`        | uuidv4     | Chave única para controle da requisição.                                                    | 36         |
| `outgoing_recurrence_key`    | uuidv4     | Identificador da recorrência automática.                                                    | 36         |
| `outgoing_recurrence_status` | string     | Status atual da recorrência (`approved`, `pending`, `rejected`, etc.).                      | 30         |
| `periodicity`                | enumerator | Periodicidade da recorrência.                                                               | [Enumeradores periodicity](#enumeradores-periodicity)      |
| `journey_type`               | enumerator | Jornada da recorrência automática.                                                          | [Enumeradores journey_type](#enumeradores-journey_type)    |
| `start_date`                 | string     | Data de início da recorrência (formato ISO 8601, e.g., `2025-06-10`).                      | 10         |
| `end_date`                   | string     | Data de término da recorrência (formato ISO 8601) ou null, se indeterminado.                | 10 ou null |
| `outgoing_recurrence_data`   | object     | Objeto agrupando parâmetros da assinatura e dados complementares.                           | [Objeto outgoing_recurrence_data](#objeto-outgoing_recurrence_data) |
| `payment_orders`             | array      | Objeto agrupando parâmetros da assinatura e dados complementares.                           | [Objeto payment_orders](#objeto-payment_orders) |
| `outgoing_recurrence_events` | array      | Objeto agrupando parâmetros dos eventos da recorrência                                      | [Objeto outgoing_recurrence_events](#objeto-outgoing_recurrence_events) |

### Objeto outgoing_recurrence_data

| Campo                       | Tipo     | Descrição                                                          | Caracteres |
|-----------------------------|----------|--------------------------------------------------------------------|------------|
| `minimum_recurrence_amount` | number   | Valor mínimo esperado nas recorrências de valor variável           | -          |
| `recurrence_amount`         | number   | Valor da recorrência (para valor fixo; null se variável)           | -          |
| `retry_configuration`       | object   | Configuração de tentativas para recorrências não concluídas         | [Objeto retry_configuration](#objeto-retry_configuration)   |
| `debtor_data`               | object   | Dados do devedor (assinante)                                       | [Objeto debtor_data](#objeto-debtor_data)                  |
| `qr_code_data`              | object   | Dados de QR Code gerado para o pagamento (se houver)                | [Objeto qr_code_data](#objeto-qr_code_data)                |
| `initial_payment_data`      | object   | Dados da cobrança inicial                                          | [Objeto initial_payment_data](#objeto-initial_payment_data) |
| `pix_message`               | string   | Mensagem enviada junto à transação Pix                             | 140        |
| `settlement_date_type`      | enumerator| Tipo do ajuste da data de liquidação                               | [Enumeradores settlement_date_type](#enumeradores-settlement_date_type) |

---

### Objeto retry_configuration

| Campo           | Tipo    | Descrição                                   | Caracteres |
|-----------------|---------|---------------------------------------------|------------|
| `retry_allowed` | boolean | Indica se retentativas estão habilitadas    | -          |
| `retry_rule`    | object  | Regras detalhadas das retentativas          | [Objeto retry_rule](#objeto-retry_rule) |

---

### Objeto retry_rule

| Campo         | Tipo   | Descrição                         | Caracteres |
|---------------|--------|-----------------------------------|------------|
| `first_retry` | object | Configuração para 1ª retentativa  | [Objeto retry_detail](#objeto-retry_detail) |
| `second_retry`| object | Configuração para 2ª retentativa  | [Objeto retry_detail](#objeto-retry_detail) |
| `third_retry` | object | Configuração para 3ª retentativa  | [Objeto retry_detail](#objeto-retry_detail) |

---

### Objeto retry_detail

| Campo | Tipo   | Descrição               | Caracteres |
|-------|--------|-------------------------|------------|
| `day` | string | Dia da retentativa.     | -          |
| `time`| string | Horário da retentativa. | -          |

---

### Objeto debtor_data

| Campo             | Tipo   | Descrição              | Caracteres |
|-------------------|--------|------------------------|------------|
| `name`            | string | Nome do assinante.     | 50         |
| `email`           | string | E-mail do assinante.   | 100        |
| `document_number` | string | CPF ou CNPJ.           | 14         |
| `address`         | object | Endereço do assinante. | [Objeto address](#objeto-address) |
| `account_data`    | object | Dados bancários.       | [Objeto account_data](#objeto-account_data) |

---

### Objeto address

| Campo         | Tipo   | Descrição         | Caracteres |
|---------------|--------|-------------------|------------|
| `city`        | string | Cidade.           | -          |
| `postal_code` | string | CEP.              | -          |
| `uf`          | string | Estado (sigla).   | -          |
| `street`      | string | Logradouro.       | -          |

---

### Objeto account_data

| Campo           | Tipo   | Descrição                    | Caracteres |
|-----------------|--------|------------------------------|------------|
| `account_number`| string | Número da conta              | -          |
| `account_digit` | string | Dígito da conta              | -          |
| `account_branch`| string | Agência                      | -          |
| `ispb`          | string | ISPB da instituição financeira| -         |

---

### Objeto qr_code_data

| Campo            | Tipo   | Descrição                                   | Caracteres |
|------------------|--------|---------------------------------------------|------------|
| `qr_code_key`    | string | Identificador do QR Code gerado             | -          |
| `qr_code_url`    | string | URL para visualização do QR Code            | -          |
| `qr_code_image`  | string | Imagem do QR Code (em Base64)               | -          |

---

### Objeto initial_payment_data

| Campo                     | Tipo     | Descrição                                                                | Caracteres |
|---------------------------|----------|--------------------------------------------------------------------------|------------|
| `amount`                  | number   | Valor principal da cobrança inicial em reais (R$)                        | -          |
| `pix_key`                 | string   | Chave Pix de destino para o pagamento inicial                            | 77         |
| `qr_code_type`            | enum     | Tipo de QR Code para cobrança inicial.                                   | [Enumeradores qr_code_type](#enumeradores-qr_code_type) |
| `additional_data`         | array    | Lista de informações adicionais relacionadas à cobrança                   | [Array de objects additional_data](#array-additional_data) |
| `fine_amount`             | number   | Valor da multa, caso ocorra atraso no pagamento                          | -          |
| `interest_amount`         | number   | Valor dos juros, caso ocorra atraso no pagamento                         | -          |
| `expiration_date`         | string   | Data de expiração da cobrança inicial (formato ISO 8601)                 | 10         |
| `max_payment_days`        | integer  | Número máximo de dias de aceite após expiração                           | -          |
| `rebate_amount`           | number   | Valor do desconto para pagamento antecipado                              | -          |
| `discounts`               | array    | Lista de descontos adicionais                                            | -          |
| `receiver_conciliation_id`| string   | Identificador de conciliação do pagamento pelo recebedor                 | 35         |
| `transaction_data`        | object   | Detalhes da transação relacionada à cobrança inicial                     | [Objeto transaction_data](#objeto-transaction_data) |

---

### Array additional_data

| Campo        | Tipo    | Descrição                                                       | Caracteres |
|--------------|---------|-----------------------------------------------------------------|------------|
| `key_name`   | string  | Nome da informação adicional (ex: "Juros e Multa")              | 140        |
| `value`      | string  | Valor ou descrição da informação adicional                      | 140        |

---

### Objeto transaction_data

| Campo               | Tipo   | Descrição                              | Caracteres |
|---------------------|--------|----------------------------------------|------------|
| `transaction_key`   | string | Chave única da transação               | 36         |
| `pix_transfer_key`  | string | Identificador da transferência Pix     | 36         |
| `end_to_end_id`     | string | Identificador end-to-end do Pix        | 32         |

---

### Objeto payment_orders

| Campo                       | Tipo    | Descrição                                               | Caracteres |
|-----------------------------|---------|---------------------------------------------------------|------------|
| `payment_order_key`         | string  | Chave única identificadora da ordem de pagamento        | 32         |
| `payment_order_status`      | string  | Status da ordem de pagamento                            | -          |
| `reference_date`            | string  | Data de referência da cobrança                          | -          |
| `receiver_conciliation_id`  | uuidv4  | ID de conciliação do recebedor                          | 35         |
| `transaction_amount`        | number  | Valor monetário da transação                            | -          |
| `transaction_key`           | uuidv4  | Chave única da transação                                | 36         |
| `incoming_pix_transfer_key` | uuidv4  | Chave de transferência Pix recebida                     | 36         |
| `created_at`                | string  | Data/hora de criação da ordem (formato ISO 8601)        | -          |
| `paid_at`                   | string  | Data/hora do pagamento efetuado (formato ISO 8601)      | -          |

### Objeto outgoing_recurrence_events

| Campo                       | Tipo    | Descrição                                               | Caracteres |
|-----------------------------|---------|---------------------------------------------------------|------------|
| `outgoing_recurrence_event_key`         | string  | Chave única identificadora do evento de recorrência        | 36         |
| `outgoing_recurrence_status`      | string  | Status da recorrência                            | -          |
| `created_at`                | string  | Data/hora de criação da ordem (formato ISO 8601)        | -          |

### Enumeradores periodicity

| Enumerador   | Descrição             |
|--------------|----------------------|
| `weekly`     | Recorrência semanal   |
| `monthly`    | Recorrência mensal    |
| `quarterly`  | Recorrência trimestral|
| `semiannual` | Recorrência semestral |
| `annual`     | Recorrência anual     |

---

### Enumeradores journey_type

| Enumerador      | Descrição                                     |
|-----------------|-----------------------------------------------|
| `journey_one`   | Notificação direta no aplicativo bancário     |
| `journey_two`   | Experiência QR Code para cobrança recorrente  |
| `journey_three` | Pagamento instantâneo + recorrência QR Code   |
| `journey_four`  | Opt-in recorrente a partir de operação Pix    |

---

### Enumeradores settlement_date_type

| Enumerador      | Descrição             |
|-----------------|----------------------|
| `workdays`      | Dias úteis           |
| `calendar_days` | Dias corridos         |

---

### Enumeradores qr_code_type

| Enumerador                 | Descrição                                             |
|----------------------------|-------------------------------------------------------|
| `dynamic_instant_composed` | QR Code dinâmico para pagamento instantâneo           |
| `dynamic_term_composed`    | QR Code dinâmico para pagamento com vencimento futuro |

STATUS 4XX

Response Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em português",
  "code": "codigo"
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                | Descrição (eng)<br/>`description`                                          | Descrição (ptbr)<br/>`translation`                                 |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400         | QIT000002            | Bad Request                       | Invalid request schema.                                                    | Erro no esquema da requisição.                                     |
| 404         | APX000002            | Recurrence Not Found              | Recurrence \{recurrence_key\} not found.                                   | Recorrência \{recurrence_key\} não encontrada.                      |

---

# Consulta de Dados de Recorrência Automática Pix pelo QRCode

URL: /documentation/baas/pix_automatico/recebedor/consultar_recorrencia_receiver

## Request

ENDPOINT /account/ ACCOUNT_KEY /outgoing_recurrence/qr_code_initial_payment/ RECEIVER_CONCILIATION_ID
MÉTODO GET

### Path Params

| Campo                    | Tipo   | Descrição                                         | Caracteres |
|--------------------------|--------|---------------------------------------------------|------------|
| `account_key` *          | uuidv4 | Chave única de identificação da conta.            | 36         |
| `receiver_conciliation_id`*| string | Id de conciliação do qr_code associado à recorrência    | 32         |

## Response

STATUS 200

Response Body

```json
{
  "request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
  "outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "outgoing_recurrence_status": "approved",
  "periodicity": "monthly",
  "journey_type": "journey_four",
  "start_date": "2025-06-10",
  "end_date": "2027-06-10",
  "outgoing_recurrence_data": {
    "minimum_recurrence_amount": 123.45,
    "recurrence_amount": null,
    "retry_configuration": {
      "retry_allowed": true,
      "retry_rule": {
        "first_retry": {
          "day": "1"
        },
        "second_retry": {
          "day": "3"
        },
        "third_retry": {
          "day": "4"
        }
      }
    },
    "debtor_data": {
      "name": "Sebastião",
      "email": "sebastiao@test.com",
      "document_number": "05431134850",
      "address": {
        "city": "São Paulo",
        "postal_code": "123456-789",
        "uf": "SP",
        "street": "Av Paulista 123"
      },
      "account_data": {
        "account_number": "123456",
        "account_digit": "7",
        "account_branch": "0001",
        "ispb": "31872495"
      }
    },
    "qr_code_data": {
      "qr_code_key": "0f45cc3d-9bd1-4d68-a865-4cf477b5da45",
      "qr_code_url": "urlqrcode.url",
      "qr_code_image": "image_base64"
    },
    "initial_payment_data": {
      "amount": 22.34,
      "pix_key": "3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
      "qr_code_type": "dynamic_term_composed",
      "additional_data": [
        {
          "key_name": "Juros e Multa",
          "value": "Juros 2 ao mes e multa de 1%"
        }
      ],
      "fine_amount": 3,
      "interest_amount": 2,
      "expiration_date": "2023-03-25",
      "max_payment_days": 128,
      "rebate_amount": 1,
      "discounts": [],
      "receiver_conciliation_id":"3d7d6a2bf72f44z7bb2079a94dff5645",
      "transaction_data":{
        "transaction_key":"4d7d6a2b-f72f-44z7-bb20-79a94dff5645",
        "pix_transfer_key":"5d7d6a2b-f72f-44z7-bb20-79a94dff5645",
        "end_to_end_id":"E32402502202303141907qlBAF1evdJ2"
      }
    },
    "pix_message": "Conta de Luz Residencial nº123",
    "settlement_date_type": "calendar_days"
  }
}
```

### Response Body Params

| Campo                        | Tipo       | Descrição                                                                                   | Caracteres |
|------------------------------|------------|---------------------------------------------------------------------------------------------|------------|
| `request_control_key`        | uuidv4     | Chave única para controle da requisição.                                                    | 36         |
| `outgoing_recurrence_key`    | uuidv4     | Identificador da recorrência automática.                                                    | 36         |
| `outgoing_recurrence_status` | string     | Status atual da recorrência (`approved`, `pending`, `rejected`, etc.).                      | 30         |
| `periodicity`                | enumerator | Periodicidade da recorrência.                                                               | [Enumeradores periodicity](#enumeradores-periodicity)      |
| `journey_type`               | enumerator | Jornada da recorrência automática.                                                          | [Enumeradores journey_type](#enumeradores-journey_type)    |
| `start_date`                 | string     | Data de início da recorrência (formato ISO 8601, e.g., `2025-06-10`).                      | 10         |
| `end_date`                   | string     | Data de término da recorrência (formato ISO 8601) ou null, se indeterminado.                | 10 ou null |
| `outgoing_recurrence_data`   | object     | Objeto agrupando parâmetros da assinatura e dados complementares.                           | [Objeto outgoing_recurrence_data](#objeto-outgoing_recurrence_data) |

---

### Objeto outgoing_recurrence_data

| Campo                       | Tipo     | Descrição                                                          | Caracteres |
|-----------------------------|----------|--------------------------------------------------------------------|------------|
| `minimum_recurrence_amount` | number   | Valor mínimo esperado nas recorrências de valor variável           | -          |
| `recurrence_amount`         | number   | Valor da recorrência (para valor fixo; null se variável)           | -          |
| `retry_configuration`       | object   | Configuração de tentativas para recorrências não concluídas         | [Objeto retry_configuration](#objeto-retry_configuration)   |
| `debtor_data`               | object   | Dados do devedor (assinante)                                       | [Objeto debtor_data](#objeto-debtor_data)                  |
| `qr_code_data`              | object   | Dados de QR Code gerado para o pagamento (se houver)                | [Objeto qr_code_data](#objeto-qr_code_data)                |
| `initial_payment_data`      | object   | Dados da cobrança inicial                                          | [Objeto initial_payment_data](#objeto-initial_payment_data) |
| `pix_message`               | string   | Mensagem enviada junto à transação Pix                             | 140        |
| `settlement_date_type`      | enumerator| Tipo do ajuste da data de liquidação                               | [Enumeradores settlement_date_type](#enumeradores-settlement_date_type) |

---

### Objeto retry_configuration

| Campo           | Tipo    | Descrição                                   | Caracteres |
|-----------------|---------|---------------------------------------------|------------|
| `retry_allowed` | boolean | Indica se retentativas estão habilitadas    | -          |
| `retry_rule`    | object  | Regras detalhadas das retentativas          | [Objeto retry_rule](#objeto-retry_rule) |

---

### Objeto retry_rule

| Campo         | Tipo   | Descrição                         | Caracteres |
|---------------|--------|-----------------------------------|------------|
| `first_retry` | object | Configuração para 1ª retentativa  | [Objeto retry_detail](#objeto-retry_detail) |
| `second_retry`| object | Configuração para 2ª retentativa  | [Objeto retry_detail](#objeto-retry_detail) |
| `third_retry` | object | Configuração para 3ª retentativa  | [Objeto retry_detail](#objeto-retry_detail) |

---

### Objeto retry_detail

| Campo | Tipo   | Descrição               | Caracteres |
|-------|--------|-------------------------|------------|
| `day` | string | Dia da retentativa.     | -          |
| `time`| string | Horário da retentativa. | -          |

---

### Objeto debtor_data

| Campo             | Tipo   | Descrição              | Caracteres |
|-------------------|--------|------------------------|------------|
| `name`            | string | Nome do assinante.     | 50         |
| `email`           | string | E-mail do assinante.   | 100        |
| `document_number` | string | CPF ou CNPJ.           | 14         |
| `address`         | object | Endereço do assinante. | [Objeto address](#objeto-address) |
| `account_data`    | object | Dados bancários.       | [Objeto account_data](#objeto-account_data) |

---

### Objeto address

| Campo         | Tipo   | Descrição         | Caracteres |
|---------------|--------|-------------------|------------|
| `city`        | string | Cidade.           | -          |
| `postal_code` | string | CEP.              | -          |
| `uf`          | string | Estado (sigla).   | -          |
| `street`      | string | Logradouro.       | -          |

---

### Objeto account_data

| Campo           | Tipo   | Descrição                    | Caracteres |
|-----------------|--------|------------------------------|------------|
| `account_number`| string | Número da conta              | -          |
| `account_digit` | string | Dígito da conta              | -          |
| `account_branch`| string | Agência                      | -          |
| `ispb`          | string | ISPB da instituição financeira| -         |

---

### Objeto qr_code_data

| Campo            | Tipo   | Descrição                                   | Caracteres |
|------------------|--------|---------------------------------------------|------------|
| `qr_code_key`    | string | Identificador do QR Code gerado             | -          |
| `qr_code_url`    | string | URL para visualização do QR Code            | -          |
| `qr_code_image`  | string | Imagem do QR Code (em Base64)               | -          |

---

### Objeto initial_payment_data

| Campo                     | Tipo     | Descrição                                                                | Caracteres |
|---------------------------|----------|--------------------------------------------------------------------------|------------|
| `amount`                  | number   | Valor principal da cobrança inicial em reais (R$)                        | -          |
| `pix_key`                 | string   | Chave Pix de destino para o pagamento inicial                            | 77         |
| `qr_code_type`            | enum     | Tipo de QR Code para cobrança inicial.                                   | [Enumeradores qr_code_type](#enumeradores-qr_code_type) |
| `additional_data`         | array    | Lista de informações adicionais relacionadas à cobrança                   | [Array de objects additional_data](#array-additional_data) |
| `fine_amount`             | number   | Valor da multa, caso ocorra atraso no pagamento                          | -          |
| `interest_amount`         | number   | Valor dos juros, caso ocorra atraso no pagamento                         | -          |
| `expiration_date`         | string   | Data de expiração da cobrança inicial (formato ISO 8601)                 | 10         |
| `max_payment_days`        | integer  | Número máximo de dias de aceite após expiração                           | -          |
| `rebate_amount`           | number   | Valor do desconto para pagamento antecipado                              | -          |
| `discounts`               | array    | Lista de descontos adicionais                                            | -          |
| `receiver_conciliation_id`| string   | Identificador de conciliação do pagamento pelo recebedor                 | 35         |
| `transaction_data`        | object   | Detalhes da transação relacionada à cobrança inicial                     | [Objeto transaction_data](#objeto-transaction_data) |

---

### Array additional_data

| Campo        | Tipo    | Descrição                                                       | Caracteres |
|--------------|---------|-----------------------------------------------------------------|------------|
| `key_name`   | string  | Nome da informação adicional (ex: "Juros e Multa")              | 140        |
| `value`      | string  | Valor ou descrição da informação adicional                      | 140        |

---

### Objeto transaction_data

| Campo               | Tipo   | Descrição                              | Caracteres |
|---------------------|--------|----------------------------------------|------------|
| `transaction_key`   | string | Chave única da transação               | 36         |
| `pix_transfer_key`  | string | Identificador da transferência Pix     | 36         |
| `end_to_end_id`     | string | Identificador end-to-end do Pix        | 32         |

---

### Enumeradores periodicity

| Enumerador   | Descrição             |
|--------------|----------------------|
| `weekly`     | Recorrência semanal   |
| `monthly`    | Recorrência mensal    |
| `quarterly`  | Recorrência trimestral|
| `semiannual` | Recorrência semestral |
| `annual`     | Recorrência anual     |

---

### Enumeradores journey_type

| Enumerador      | Descrição                                     |
|-----------------|-----------------------------------------------|
| `journey_one`   | Notificação direta no aplicativo bancário     |
| `journey_two`   | Experiência QR Code para cobrança recorrente  |
| `journey_three` | Pagamento instantâneo + recorrência QR Code   |
| `journey_four`  | Opt-in recorrente a partir de operação Pix    |

---

### Enumeradores settlement_date_type

| Enumerador      | Descrição             |
|-----------------|----------------------|
| `workdays`      | Dias úteis           |
| `calendar_days` | Dias corridos         |

---

### Enumeradores qr_code_type

| Enumerador                 | Descrição                                             |
|----------------------------|-------------------------------------------------------|
| `dynamic_instant_composed` | QR Code dinâmico para pagamento instantâneo           |
| `dynamic_term_composed`    | QR Code dinâmico para pagamento com vencimento futuro |

STATUS 4XX

Response Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em português",
  "code": "codigo"
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                | Descrição (eng)<br/>`description`                                          | Descrição (ptbr)<br/>`translation`                                 |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400         | QIT000002            | Bad Request                       | Invalid request schema.                                                    | Erro no esquema da requisição.                                     |
| 404         | APX000002            | Recurrence Not Found              | Recurrence \{recurrence_key\} not found.                                   | Recorrência \{recurrence_key\} não encontrada.                      |

---

# Conciliação e Liquidação de Pagamentos

URL: /documentation/baas/pix_automatico/recebedor/introducao

## Visão Geral do Negócio

O sistema de pagamentos via Pix Automático oferece uma solução eficiente para automatizar débitos recorrentes, proporcionando maior comodidade tanto para o pagador quanto para o recebedor. Ao garantir a automação e a notificação dos envolvidos, minimiza-se o risco de inadimplência e otimiza-se o fluxo de caixa das empresas.

## Processamento de Pagamentos via Pix Automático

Na data agendada para o pagamento de um débito via Pix Automático, o banco do pagador deve emitir a ordem de pagamento entre meia-noite e 8h. Após a confirmação do pagamento, o usuário pagador receberá uma notificação. Caso o débito seja cancelado pelo pagador ou recebedor antes dessa etapa, a transação não será processada.

## Recorrências de Valor Variável

Para recorrências com valor variável, o usuário recebedor definirá o valor mínimo, enquanto o pagador determinará o valor máximo permitido. O valor específico a ser cobrado deve ser enviado pelo recebedor entre 10 a 2 dias antes da data de pagamento. 

:::warning
Se não for enviado, a cobrança não será realizada. Essa etapa não se aplica a recorrências de valor fixo.
:::

### Contexto de Negócio

As recorrências de valor variável são particularmente úteis em setores onde os valores cobráveis podem oscilar, como no fornecimento de utilidades ou em assinaturas baseadas em uso, permitindo flexibilidade nos pagamentos.

## Lotes de Conciliação de Pagamentos

Um conjunto de recorrências com pagamentos a receber será chamado de grupo de liquidação (`conciliation_batch`).

- A criação dos lotes de conciliação ocorre 10 dias antes da data de pagamento.
- Os lotes são fechados 2 dias antes da data de pagamento.
- Após a criação de um lote, um webhook será enviado com a `conciliation_batch_key`. As recorrências associadas podem ser obtidas através do endpoint específico.

### Impacto no Negócio

Os lotes de conciliação facilitam a gestão de recebíveis em escala, proporcionando transparência e controle sobre os fluxos financeiros programados, essencial para o planejamento estratégico e financeiro de qualquer organização.

## Retentativas de Recebimento

O usuário recebedor pode definir retentativas de recebimento durante a criação da recorrência, respeitando as seguintes condições:

- As retentativas podem ocorrer até 7 dias após a data de vencimento original.
- No máximo três tentativas podem ser efetuadas, conforme definido na criação.
- O valor deve ser o mesmo do pagamento original.

### Considerações de Negócio

As retentativas de recebimento são uma funcionalidade crucial para a maximização de recebíveis, garantindo oportunidades adicionais para liquidar pagamentos que, por qualquer motivo, falharam na data original. Isso reduz perdas por inadimplência e melhora a experiência do cliente ao proporcionar flexibilidade adicional.

---

# Criar uma Recorrência (Jornada 4)

URL: /documentation/baas/pix_automatico/recebedor/journey_four

> Jornada 4 — QR Code + Pagament ou agendamento + Oferta do pix automático

{`
.hero-section { background: linear-gradient(135deg, #eff6ff 0%, #ffffff 100%); border: 1px solid #e5e7eb; border-radius: 16px; padding: 24px; margin: 24px 0 32px 0; }
.hero-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); gap: 16px; margin-top: 20px; }
.hero-item { background: #ffffff; border: 1px solid #e5e7eb; border-radius: 10px; padding: 16px; }
.hero-item > strong { display: block; color: #1e40af; font-size: 14px; margin-bottom: 6px; font-weight: 700; }
.hero-item p { margin: 0; font-size: 13px; color: #475569; line-height: 1.5; }

.endpoint-card { background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%); border: 2px solid #e5e7eb; border-radius: 12px; padding: 24px; position: relative; overflow: hidden; }
.endpoint-card::before { content: ''; position: absolute; top: 0; left: 0; width: 4px; height: 100%; background: linear-gradient(to bottom, #3b82f6, #1e40af); }
.endpoint-list { display: grid; gap: 12px; font-size: 13px; color: #334155; }
.endpoint__item { display: grid; grid-template-columns: 120px 1fr; align-items: center; gap: 12px; background: #ffffff; border: 1px solid #e5e7eb; border-radius: 8px; padding: 10px 14px; }
.badge { font-size: 11px; font-weight: 800; padding: 4px 10px; border-radius: 6px; color: #fff; text-transform: uppercase; letter-spacing: .4px; background: #1e40af; }

.details-container { background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%); border: 1px solid #e5e7eb; border-radius: 10px; padding: 8px 12px; margin: 20px 0; }
.details-container summary { font-weight: 700; color: #1e40af; cursor: pointer; font-size: 14px; padding: 10px 0 10px 28px; display: flex; align-items: center; position: relative; }
.details-container summary::-webkit-details-marker { display: none; }
.details-container summary::before { content: ''; position: absolute; left: 10px; width: 0; height: 0; border-left: 7px solid #1e40af; border-top: 6px solid transparent; border-bottom: 6px solid transparent; transition: transform .2s ease; }
.details-container[open] summary::before { transform: rotate(90deg); }
.code-block { margin-top: 12px; border-radius: 8px; overflow: hidden; }

.table-container { overflow: auto; border: 0; border-radius: 0; margin: 20px 0; background: transparent; }
.table-container table { width: 100%; border-collapse: collapse; font-size: 13px; }
.table-container th, .table-container td { border-top: 1px solid #e5e7eb; padding: 12px 16px; text-align: left; }
.table-container thead th { background: linear-gradient(135deg, #f8fafc 0%, #ffffff 100%); font-weight: 700; color: #0f172a; font-size: 13px; }
`}

Visão geral
O que é O cliente realiza o pagamento ou agendamento de um QR Code e, depois, recebe a oferta para ativar a recorrência Pix Automático.
Quando usar Indicado para faturas, boletos ou contas com proposta de adesão à recorrência, mas só após o pagamento ou agendamento inicial.
Como funciona Pagador lê o QR Code → paga ou agenda o pagamento → ao concluir, recebe convite para ativar o Pix Automático para aquela cobrança (opcional).
Benefícios Flexível: a decisão sobre a recorrência ocorre após o pagamento/agendamento, permitindo adesão voluntária e espontânea pelo pagador.
Pontos de atenção A oferta de recorrência é feita somente após o pagamento/agendamento — pode ser recusada pelo cliente. Se não disponível para aquele caso, prossiga apenas com o pagamento, sem oferecer recorrência.

## Request

{`
.endpoint-card { background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%); border: 2px solid #e5e7eb; border-radius: 12px; padding: 24px; position: relative; overflow: hidden; }
.endpoint-card::before { content: ''; position: absolute; top: 0; left: 0; width: 4px; height: 100%; background: linear-gradient(to bottom, #3b82f6, #1e40af); }
.endpoint-list { display: grid; gap: 12px; font-size: 13px; color: #334155; }
.endpoint__item { display: grid; grid-template-columns: 120px 1fr; align-items: center; gap: 12px; background: #ffffff; border: 1px solid #e5e7eb; border-radius: 8px; padding: 10px 14px; }
.badge { font-size: 11px; font-weight: 800; padding: 4px 10px; border-radius: 6px; color: #fff; text-transform: uppercase; letter-spacing: .4px; background: #1e40af; }
.details-container { background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%); border: 1px solid #e5e7eb; border-radius: 10px; padding: 8px 12px; margin: 20px 0; }
.details-container summary { font-weight: 700; color: #1e40af; cursor: pointer; font-size: 14px; padding: 10px 0 10px 28px; display: flex; align-items: center; position: relative; }
.details-container summary::-webkit-details-marker { display: none; }
.details-container summary::before { content: ''; position: absolute; left: 10px; width: 0; height: 0; border-left: 7px solid #1e40af; border-top: 6px solid transparent; border-bottom: 6px solid transparent; transition: transform .2s ease; }
.details-container[open] summary::before { transform: rotate(90deg); }
.code-block { margin-top: 12px; border-radius: 8px; overflow: hidden; }
`}

ENDPOINT /account/ account_key /outgoing_recurrence/journey_four
MÉTODO POST

### Request Path Params

| Campo         | Tipo  | Descrição                                      | Caracteres |
|---------------|-------|------------------------------------------------|------------|
| `account_key`*| uuid4 | Chave única de identificação da conta.          | 36         |

### Request Body

**Request Body: Criar Recorrência (Jornada 4)**

```json
{
    "request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "periodicity": "monthly",
    "minimum_recurrence_amount": 125,
    "start_date": "2025-06-10",
    "end_date": "2027-06-10",
    "pix_message": "Conta de Luz Residencial nº123",
    "recurrence_type": "variable_amount",
    "debtor_data": {
        "name": "Sebastião",
        "email": "sebastiao@test.com",
        "document_number": "05431134850",
        "contract_id": "12345",
        "address": {
            "street": "Av. Brigadeiro Faria Lima",
            "state": "SP",
            "city": "São Paulo",
            "neighborhood": "Jardim Paulistano",
            "number": "2391",
            "postal_code": "01452905",
            "complement": "Complemento"
        }
    },
    "initial_payment_data": {
        "amount": 22.34,
        "pix_key": "3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
        "qr_code_type": "dynamic_term_composed",
        "additional_data": [
            {
                "key_name": "Juros e Multa",
                "value": "Juros 2 ao mes e multa de 1%"
            }	
        ],
        "fine_amount": 3,
        "interest_amount": 2,
        "expiration_date": "2023-03-25",
        "max_payment_days": 128,
        "rebate_amount": 1,
        "discounts": [],
        "receiver_conciliation_id": "3d7d6a2bf72f44z7bb2079a94dff5645"		
    },
    "retry_configuration": {
        "retry_allowed": true,
        "retry_rule": {
            "first_retry": {
                "day": "1"
            },
            "second_retry": {
                "day": "3"
            },
            "third_retry": {
                "day": "4"
            }
        }
    },
    "settlement_date_type": "workdays"
}
```

### Body Params

| Campo                            | Tipo        | Descrição                                                                                                         | Caracteres |
|-----------------------------------|-------------|-------------------------------------------------------------------------------------------------------------------|------------|
| `request_control_key` *           | uuid        | Chave única de identificação da requisição utilizada pelo cliente no formato uuid4.                               | 36         |
| `periodicity` *                   | enumerator  | Tipo da periodicidade associada à recorrência da assinatura.                                                      | [Enumeradores periodicity](#enumeradores-periodicity) |
| `minimum_recurrence_amount`       | float      | Valor mínimo da transação para recorrências de valor variável                                       | -          |
| `start_date` *                    | string      | Data de início da recorrência (formato ISO 8601, e.g., "2025-07-01").                                             | -          |
| `end_date`                        | string      | Data de término da recorrência; para tempo indeterminado, enviar como null.                                       | -          |
| `pix_message` *                   | string      | Mensagem a ser enviada junto à transação Pix.                                                                     | 140        |
| `debtor_data` *                   | Object      | Dados do devedor (assinante).                                                                                     | [Objeto debtor_data](#objeto-debtor_data) |
| `retry_configuration` *           | Object      | Configuração de retentativas para transações não concluídas.                                                      | [Objeto retry_configuration](#objeto-retry_configuration) |
| `settlement_date_type` *          | enumerator  | Tipo de ajuste da data de liquidação                                                                              | [Enumeradores settlement_date_type](#enumeradores-settlement_date_type) |
| `recurrence_type` *               | enumerator  | Tipo de recorrência                                                                                               | [Enumeradores recurrence_type](#enumeradores-recurrence_type) |
| `initial_payment_data` *            | Object      | Objeto com informações da cobrança inicial a ser realizada na criação da assinatura.                              | [Objeto initial_payment_data](#objeto-initial_payment_data) |

:::caution Atenção
O campo `minimum_recurrence_amount` é opcional e deve ser informado apenas para recorrência de valor variável. Caso a recorrência seja de valor fixo, deve-se enviar o campo `recurrence_amount`, com o valor da recorrência. Assim como o enumerador `recurrence_type`, que deverá corresponder ao tipo da recorrência (Valor fixo ou variável).
:::

### Enumeradores periodicity

| Enumerador   | Descrição             |
|--------------|-----------------------|
| `weekly`     | Recorrência semanal   |
| `monthly`    | Recorrência mensal    |
| `quarterly`  | Recorrência trimestral|
| `semiannual` | Recorrência semestral |
| `annual`     | Recorrência anual     |

### Enumeradores settlement_date_type

| Enumerador   | Descrição             |
|--------------|-----------------------|
| `workdays`     | Dias úteis   |
| `calendar_days`     | Dias corridos   |

### Enumeradores recurrence_type

| Enumerador   | Descrição             |
|--------------|-----------------------|
| `fixed_amount`     | Recorrência de Valor Fixo   |
| `variable_amount`     | Recorrência de Valor Variável   |

### Objeto debtor_data

| Campo               | Tipo   | Descrição             | Caracteres |
|---------------------|--------|-----------------------|------------|
| `name` *            | string | Nome do assinante.    | 50         |
| `email` *           | string | E-mail do assinante.  | 100        |
| `document_number` * | string | CPF ou CNPJ do assinante. | 14      |
| `contract_id`       | string | Identificador do contrato do assinante. | 100      |
| `address` *         | Object | Endereço do assinante.| [Objeto address](#objeto-address) |

### Objeto address

| Campo         | Tipo   | Descrição         | Caracteres |
|---------------|--------|-------------------|------------|
| `street`      | string | Rua.              | -          |
| `state`       | string | Estado.           | -          |
| `city`        | string | Cidade.           | -          |
| `neighborhood`| string | Bairro.           | -          |
| `number`      | string | Número.           | -          |
| `postal_code` | string | CEP.              | -          |
| `complement`  | string | Complemento.      | -          |

### Objeto retry_configuration

| Campo         | Tipo    | Descrição               | Caracteres |
|---------------|---------|-------------------------|------------|
| `retry_allowed`| boolean | Indica se retentativas são permitidas. | -     |
| `retry_rule`  | Object  | Regras de retentativa.  | [Objeto retry_rule](#objeto-retry_rule) |

### Objeto retry_rule

| Campo         | Tipo   | Descrição               | Caracteres |
|---------------|--------|-------------------------|------------|
| `first_retry` | Object | Configuração da primeira retentativa. | [Objeto retry_detail](#objeto-retry_detail) |
| `second_retry`| Object | Configuração da segunda retentativa.  | [Objeto retry_detail](#objeto-retry_detail) |
| `third_retry` | Object | Configuração da terceira retentativa. | [Objeto retry_detail](#objeto-retry_detail) |

### Objeto retry_detail

| Campo | Tipo   | Descrição               | Caracteres |
|-------|--------|-------------------------|------------|
| `day` | string | Dia da retentativa.     | -          |

### Objeto initial_payment_data

| Campo                      | Tipo       | Descrição                                                                                | Caracteres |
|----------------------------|------------|------------------------------------------------------------------------------------------|------------|
| `amount` *                 | number     | Valor principal da cobrança inicial em reais (R$).                                       | -          |
| `pix_key` *                | string     | Chave Pix de destino para o pagamento.                                                   | 77         |
| `qr_code_type`*             | enumerator | Tipo de QR Code para a cobrança inicial.                                                | [Enumeradores qr_code_type](#enumeradores-qr_code_type) |
| `additional_data`*          | array      | Lista de objetos com informações adicionais relacionadas à cobrança (ex: juros, multa). | [Objetos additional_data](#obj-additional_data) |
| `fine_amount`              | number     | Valor da multa, caso ocorra atraso no pagamento.                                         | -          |
| `interest_amount`          | number     | Valor dos juros, caso ocorra atraso no pagamento.                                        | -          |
| `expiration_date` *        | string     | Data de expiração da cobrança inicial (formato ISO 8601, e.g., "2023-03-25").            | -          |
| `max_payment_days`         | integer    | Número máximo de dias, a partir da data de expiração, em que o pagamento pode ser aceito.| -          |
| `rebate_amount`            | number     | Valor do desconto para pagamento antecipado.                                             | -          |
| `discounts`                | array      | Lista de descontos adicionais aplicáveis (se houver).                                    | -          |
| `receiver_conciliation_id` | string     | Identificador único para conciliação do pagamento pelo recebedor.                        | 32         |

### Enumeradores qr_code_type

| Valor                      | Descrição                                                                       |
|----------------------------|---------------------------------------------------------------------------------|
| `dynamic_instant_composed` | Gera um QR Code dinâmico para pagamento instantâneo, com vencimento imediato.   |
| `dynamic_term_composed`    | Gera um QR Code dinâmico com prazo definido para pagamento (vencimento futuro). |

### Objeto additional_data

| Campo        | Tipo    | Descrição                                                       | Caracteres |
|--------------|---------|-----------------------------------------------------------------|------------|
| `key_name`   | string  | Nome do campo adicional de informação (exemplo: "Juros e Multa").| -        |
| `value`      | string  | Valor ou descrição da informação adicional.                      | -        |

## Response

STATUS 200

:::caution Atenção
Quando o usuário pagor recebe a notificação, ele pode optar por agendar o Pix ou realizar a transferência naquele momento. Caso o pagador realize instantaneamente o pagamento, será enviado o webhook do tipo `baas.automatic_pix.outgoing_recurrence.status_change` com as informações preenchidas, em caso de agendamento os valores serão `null`.
:::

**Response Body**

```json
{
    "request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "outgoing_recurrence_status": "pending_confirmation",
    "qr_code_data": {
	    "qr_code_url": "url",
	    "qr_code_key": "6f270b64-1b7a-4269-91f8-3f9cf30ba0bb",
	    "qr_code_image": "imageb64" 
    },
     "initial_payment_data": {
			"receiver_conciliation_id": "6f270b64-1b7a-4269-91f8-3f9cf30ba0bb"			  
		},
    "created_at": "2021-10-22T20:30:23.459Z"
}
```

### Response Body

| Campo                 | Tipo       | Descrição                                                                 | Caracteres |
|-----------------------|------------|---------------------------------------------------------------------------|------------|
| `request_control_key` | uuid       | Chave de controle da requisição enviada pelo cliente.                     | 36         |
| `recurrence_key`      | uuid       | Chave única de identificação da recorrência de assinatura.                | 36         |
| `recurrence_status`   | enumerator | Status atual da recorrência.                                              | [Enumeradores recurrence_status](#enumeradores-recurrence_status) |
| `qr_code_data`        | enumerator | Dados do QRCode                                                           | [Objeto qr_code_data](#enumeradores-qr_code_data) |
| `initial_payment_data`| enumerator | Informações do pagamento iniciado                                          | [Objeto qr_code_data](#enumeradores-qr_code_data) |
| `created_at`          | string     | Data e hora de criação da recorrência (formato ISO 8601).                 | -          |

### Objeto qr_code_data

| Campo | Tipo   | Descrição               | Caracteres |
|-------|--------|-------------------------|------------|
| `qr_code_url` | string | URL do copia e cola do qr_code     | -          |
| `qr_code_key`| uuuid | Chave Única de identificação do qr_code. | 36          |
| `qr_code_image`| string | Base64 da imagem do qr_code | -         |

### Objeto initial_payment_data

| Campo | Tipo   | Descrição               | Caracteres |
|-------|--------|-------------------------|------------|
| `receiver_conciliation_id` | string     | Identificador único para conciliação do pagamento pelo recebedor.                        | 32         |

### Enumeradores recurrence_status

| Enumerador           | Descrição                         |
|----------------------|-----------------------------------|
| `pending_confirmation` | Recorrência pendente de confirmação |
| `active`              | Recorrência ativa                 |
| `cancelled`           | Recorrência cancelada             |
| `suspended`           | Recorrência suspensa              |
| `expired`             | Recorrência expirada              |

STATUS 4XX

**Response Error**

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em português",
  "code": "codigo"
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                | Descrição (eng)<br/>`description`                                          | Descrição (ptbr)<br/>`translation`                                 |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400         | QIT000002            | Bad Request                       | Invalid request schema.                                                    | Erro no esquema da requisição.                                     |
| 403         | APX000030            | Unauthorized Transaction          | User is not authorized to create this recurrence.                          | Usuário não autorizado a criar esta recorrência.                   |
| 403         | APX000018            | Endpoint Access Denied            | Requester lacks permission to access this endpoint.                        | Requester não possui permissão para acessar este endpoint.          |
| 404         | APX000021            | Subscription Not Found            | Subscription \{subscription_key\} not found.                               | Assinatura \{subscription_key\} não encontrada.                     |
| 404         | APX000002            | Recurrence Not Found              | Recurrence \{recurrence_key\} not found.                                   | Recorrência \{recurrence_key\} não encontrada.                      |
| 406         | APX000027            | Invalid Transaction Amount        | Transaction amount \{minimum_transaction_amount\} is invalid.              | Valor da transação \{minimum_transaction_amount\} é inválido.        |
| 409         | APX000014            | Request Control Key Conflict      | The request_control_key \{request_control_key\} is already in use.         | A request_control_key \{request_control_key\} já está em uso.        |

---

# Criar uma Recorrência (Jornada 1)

URL: /documentation/baas/pix_automatico/recebedor/journey_one

> Jornada 1 — Sem QR Code (notificação no app)

{`
.hero-section { background: linear-gradient(135deg, #eff6ff 0%, #ffffff 100%); border: 1px solid #e5e7eb; border-radius: 16px; padding: 24px; margin: 24px 0 32px 0; }
.hero-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); gap: 16px; margin-top: 20px; }
.hero-item { background: #ffffff; border: 1px solid #e5e7eb; border-radius: 10px; padding: 16px; }
.hero-item > strong { display: block; color: #1e40af; font-size: 14px; margin-bottom: 6px; font-weight: 700; }
.hero-item p { margin: 0; font-size: 13px; color: #475569; line-height: 1.5; }

.endpoint-card { background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%); border: 2px solid #e5e7eb; border-radius: 12px; padding: 24px; position: relative; overflow: hidden; }
.endpoint-card::before { content: ''; position: absolute; top: 0; left: 0; width: 4px; height: 100%; background: linear-gradient(to bottom, #3b82f6, #1e40af); }
.endpoint-list { display: grid; gap: 12px; font-size: 13px; color: #334155; }
.endpoint__item { display: grid; grid-template-columns: 120px 1fr; align-items: center; gap: 12px; background: #ffffff; border: 1px solid #e5e7eb; border-radius: 8px; padding: 10px 14px; }
.badge { font-size: 11px; font-weight: 800; padding: 4px 10px; border-radius: 6px; color: #fff; text-transform: uppercase; letter-spacing: .4px; background: #1e40af; }

.details-container { background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%); border: 1px solid #e5e7eb; border-radius: 10px; padding: 8px 12px; margin: 20px 0; }
.details-container summary { font-weight: 700; color: #1e40af; cursor: pointer; font-size: 14px; padding: 10px 0 10px 28px; display: flex; align-items: center; position: relative; }
.details-container summary::-webkit-details-marker { display: none; }
.details-container summary::before { content: ''; position: absolute; left: 10px; width: 0; height: 0; border-left: 7px solid #1e40af; border-top: 6px solid transparent; border-bottom: 6px solid transparent; transition: transform .2s ease; }
.details-container[open] summary::before { transform: rotate(90deg); }
.code-block { margin-top: 12px; border-radius: 8px; overflow: hidden; }

.table-container { overflow: auto; border: 0; border-radius: 0; margin: 20px 0; background: transparent; }
.table-container table { width: 100%; border-collapse: collapse; font-size: 13px; }
.table-container th, .table-container td { border-top: 1px solid #e5e7eb; padding: 12px 16px; text-align: left; }
.table-container thead th { background: linear-gradient(135deg, #f8fafc 0%, #ffffff 100%); font-weight: 700; color: #0f172a; font-size: 13px; }
`}

Visão geral
O que é Autorização solicitada ao pagador diretamente no app do banco, sem leitura de QR Code.
Quando usar Contato ativo (telefone, chat, presencial) ou relacionamento já existente com o cliente.
Como funciona Recebedor cria a recorrência com dados da conta do pagador → o pagador recebe uma notificação no app → aprova a recorrência → futuras cobranças podem ser agendadas.
Benefícios Experiência simples e direta; não exige exibição de QR Code.

## Request

ENDPOINT /account/ account_key /outgoing_recurrence/journey_one
MÉTODO POST

### Request Path Params

| Campo         | Tipo  | Descrição                                      | Caracteres |
|---------------|-------|------------------------------------------------|------------|
| `account_key`*| uuid4 | Chave única de identificação da conta.          | 36         |

### Request Body

**Request Body: Criar Recorrência (Jornada 1)**

```json
{
    "request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "periodicity": "monthly",
    "minimum_recurrence_amount": 125,
    "start_date": "2025-06-10",
    "end_date": "2027-06-10",
    "pix_message": "Conta de Luz Residencial nº123",
    "recurrence_type": "variable_amount",
    "debtor_data": {
        "name": "Sebastião",
        "email": "sebastiao@test.com",
        "document_number": "05431134850",
        "contract_id": "Contrato de pagamento recorrente",
        "address": {
            "street": "Av. Brigadeiro Faria Lima",
            "state": "SP",
            "city": "São Paulo",
            "neighborhood": "Jardim Paulistano",
            "number": "2391",
            "postal_code": "01452905",
            "complement": "Complemento"
        },
        "account_data": {
            "account_number": "123456",
            "account_digit": "7",
            "account_branch": "0001",
            "ispb": "31872495"
        }
    },
    "retry_configuration": {
        "retry_allowed": true,
        "retry_rule": {
            "first_retry": {
                "day": "1",
            },
            "second_retry": {
                "day": "3",
            },
            "third_retry": {
                "day": "4",
            }
        }
    },
    "settlement_date_type": "workdays"
}
```

### Body Params

| Campo                          | Tipo       | Descrição                                                                                                  | Caracteres |
|--------------------------------|------------|------------------------------------------------------------------------------------------------------------|------------|
| `request_control_key` *        | uuid       | Chave única de identificação da requisição utilizada pelo cliente no formato uuid4.                        | 36         |
| `periodicity` *                | enumerator | Tipo da periodicidade associada à recorrência da assinatura.                                               | [Enumeradores periodicity](#enumeradores-periodicity) |
| `minimum_recurrence_amount`   | number     | Valor mínimo da transação para recorrências de valor variável (em centavos).                               | -          |
| `start_date` *                 | string     | Data de início da recorrência (formato ISO 8601, e.g., "2025-07-01").                                      | -          |
| `end_date`                     | string     | Data de término da recorrência; para tempo indeterminado, enviar como null.                                | -          |
| `pix_message` *                | string     | Mensagem a ser enviada junto à transação Pix.                                                              | 140        |
| `debtor_data` *                | Object     | Dados do devedor (assinante).                                                                              | [Objeto debtor_data](#objeto-debtor_data) |
| `retry_configuration` *        | Object     | Configuração de retentativas para transações não concluídas.                                               | [Objeto retry_configuration](#objeto-retry_configuration) |
| `settlement_date_type` *       | enumerator | Tipo de ajuste da data de liquidação                                                                       | [Enumeradores settlement_date_type](#enumeradores-settlement_date_type) |
| `recurrence_type` *       | enumerator | Tipo de recorrência                                                                                             | [Enumeradores recurrence_type](#enumeradores-recurrence_type) |

:::caution Atenção
O campo `minimum_recurrence_amount` é opcional e deve ser informado apenas para recorrência de valor variável. Caso a recorrência seja de valor fixo, deve-se enviar o campo `recurrence_amount`, com o valor da recorrência. Assim como o enumerador `recurrence_type`, que deverá corresponder ao tipo da recorrência (Valor fixo ou variável).
:::

### Enumeradores periodicity

| Enumerador   | Descrição             |
|--------------|-----------------------|
| `weekly`     | Recorrência semanal   |
| `monthly`    | Recorrência mensal    |
| `quarterly`  | Recorrência trimestral|
| `semiannual` | Recorrência semestral |
| `annual`     | Recorrência anual     |

### Enumeradores settlement_date_type

| Enumerador   | Descrição             |
|--------------|-----------------------|
| `workdays`     | Dias úteis   |
| `calendar_days`     | Dias corridos   |

### Enumeradores recurrence_type

| Enumerador   | Descrição             |
|--------------|-----------------------|
| `fixed_amount`     | Recorrência de Valor Fixo   |
| `variable_amount`     | Recorrência de Valor Variável   |

### Objeto debtor_data

| Campo               | Tipo   | Descrição             | Caracteres |
|---------------------|--------|-----------------------|------------|
| `name` *            | string | Nome do assinante.    | 50         |
| `email` *           | string | E-mail do assinante.  | 100        |
| `document_number` * | string | CPF ou CNPJ do assinante. | 14      |
| `contract_id`       | string | Identificador do contrato do assinante. | 100      |
| `address` *         | Object | Endereço do assinante.| [Objeto address](#objeto-address) |
| `account_data` *    | Object | Dados bancários do assinante. | [Objeto account_data](#objeto-account_data) |

### Objeto address

| Campo         | Tipo   | Descrição         | Caracteres |
|---------------|--------|-------------------|------------|
| `street`      | string | Rua.              | -          |
| `state`       | string | Estado.           | -          |
| `city`        | string | Cidade.           | -          |
| `neighborhood`| string | Bairro.           | -          |
| `number`      | string | Número.           | -          |
| `postal_code` | string | CEP.              | -          |
| `complement`  | string | Complemento.      | -          |

### Objeto account_data

| Campo           | Tipo   | Descrição                    | Caracteres |
|-----------------|--------|------------------------------|------------|
| `account_number`| string | Número da conta.             | -          |
| `account_digit` | string | Dígito da conta.             | -          |
| `account_branch`| string | Agência da conta.            | -          |
| `ispb`          | string | ISPB da instituição financeira. | -       |

### Objeto retry_configuration

| Campo         | Tipo    | Descrição               | Caracteres |
|---------------|---------|-------------------------|------------|
| `retry_allowed`| boolean | Indica se retentativas são permitidas. | -     |
| `retry_rule`  | Object  | Regras de retentativa.  | [Objeto retry_rule](#objeto-retry_rule) |

### Objeto retry_rule

| Campo         | Tipo   | Descrição               | Caracteres |
|---------------|--------|-------------------------|------------|
| `first_retry` | Object | Configuração da primeira retentativa. | [Objeto retry_detail](#objeto-retry_detail) |
| `second_retry`| Object | Configuração da segunda retentativa.  | [Objeto retry_detail](#objeto-retry_detail) |
| `third_retry` | Object | Configuração da terceira retentativa. | [Objeto retry_detail](#objeto-retry_detail) |

### Objeto retry_detail

| Campo | Tipo   | Descrição               | Caracteres |
|-------|--------|-------------------------|------------|
| `day` | string | Dia da retentativa.     | -          |

## Response

STATUS 200

**Response Body**

```json
{
    "request_control_key": "a7b9e3c1-f2d4-4a8b-9c7e-123456789abc",
    "recurrence_key": "b2c3d4e5-f6g7-4h8i-9j0k-l1m2n3o4p5q6",
    "recurrence_status": "pending_confirmation",
    "created_at": "2025-06-16T23:52:00.000Z"
}
```

### Response Body

| Campo                 | Tipo       | Descrição                                                                 | Caracteres |
|-----------------------|------------|---------------------------------------------------------------------------|------------|
| `request_control_key` | uuid       | Chave de controle da requisição enviada pelo cliente.                     | 36         |
| `recurrence_key`      | uuid       | Chave única de identificação da recorrência de assinatura.                | 36         |
| `recurrence_status`   | enumerator | Status atual da recorrência.                                              | [Enumeradores recurrence_status](#enumeradores-recurrence_status) |
| `created_at`          | string     | Data e hora de criação da recorrência (formato ISO 8601).                 | -          |

### Enumeradores recurrence_status

| Enumerador           | Descrição                         |
|----------------------|-----------------------------------|
| `pending_confirmation` | Recorrência pendente de confirmação |
| `active`              | Recorrência ativa                 |
| `cancelled`           | Recorrência cancelada             |
| `suspended`           | Recorrência suspensa              |
| `expired`             | Recorrência expirada              |

STATUS 4XX

Response Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em português",
  "code": "codigo"
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                | Descrição (eng)<br/>`description`                                          | Descrição (ptbr)<br/>`translation`                                 |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400         | QIT000002            | Bad Request                       | Invalid request schema.                                                    | Erro no esquema da requisição.                                     |
| 403         | APX000030            | Unauthorized Transaction          | User is not authorized to create this recurrence.                          | Usuário não autorizado a criar esta recorrência.                   |
| 403         | APX000018            | Endpoint Access Denied            | Requester lacks permission to access this endpoint.                        | Requester não possui permissão para acessar este endpoint.          |
| 404         | APX000021            | Subscription Not Found            | Subscription \{subscription_key\} not found.                               | Assinatura \{subscription_key\} não encontrada.                     |
| 404         | APX000002            | Recurrence Not Found              | Recurrence \{recurrence_key\} not found.                                   | Recorrência \{recurrence_key\} não encontrada.                      |
| 406         | APX000027            | Invalid Transaction Amount        | Transaction amount \{minimum_transaction_amount\} is invalid.              | Valor da transação \{minimum_transaction_amount\} é inválido.        |
| 409         | APX000014            | Request Control Key Conflict      | The request_control_key \{request_control_key\} is already in use.         | A request_control_key \{request_control_key\} já está em uso.        |

---

# Criar uma Recorrência (Jornada 3)

URL: /documentation/baas/pix_automatico/recebedor/journey_three

> Jornada 3 — QR Code + Primeiro Pagamento (ativação imediata da recorrência)

{`
.hero-section {
  background: linear-gradient(135deg, #eff6ff 0%, #ffffff 100%);
  border: 1px solid #e5e7eb;
  border-radius: 16px;
  padding: 24px;
  margin: 24px 0 32px 0;
}

.hero-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
  gap: 16px;
  margin-top: 20px;
}

.hero-item {
  background: #ffffff;
  border: 1px solid #e5e7eb;
  border-radius: 10px;
  padding: 16px;
  transition: all 0.3s ease;
}

.hero-item:hover {
  transform: translateY(-2px);
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.08);
  border-color: #3b82f6;
}

/* FIX: título em bloco, destaques inline dentro do parágrafo */
.j3-card > strong,
.hero-item > strong {
  display: block;
  color: #1e40af;
  font-size: 14px;
  margin-bottom: 6px;
  font-weight: 700;
}
.j3-card p strong,
.hero-item p strong {
  display: inline;
  color: #1e40af;
  font-weight: 700;
}

.hero-item p {
  margin: 0;
  font-size: 13px;
  color: #475569;
  line-height: 1.5;
}

.flow-section {
  margin: 32px 0;
}

.flow-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
  gap: 16px;
  margin-top: 20px;
}

.flow-step-card {
  border-radius: 12px;
  padding: 18px;
  color: #ffffff;
  min-height: 100px;
  display: flex;
  flex-direction: column;
  gap: 8px;
}

.flow-step-card h4 {
  margin: 0;
  font-size: 15px;
  font-weight: 700;
}

.flow-step-card p {
  margin: 0;
  font-size: 13px;
  opacity: 0.95;
  line-height: 1.5;
}

.endpoint-section {
  margin: 32px 0;
}

.endpoint-card {
  background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%);
  border: 2px solid #e5e7eb;
  border-radius: 12px;
  padding: 24px;
  transition: all 0.3s ease;
  position: relative;
  overflow: hidden;
}

.endpoint-card::before {
  content: '';
  position: absolute;
  top: 0;
  left: 0;
  width: 4px;
  height: 100%;
  background: linear-gradient(to bottom, #3b82f6, #1e40af);
  transition: width 0.3s ease;
}

.endpoint-card:hover {
  transform: translateY(-4px);
  box-shadow: 0 10px 25px rgba(0, 0, 0, 0.1);
  border-color: #3b82f6;
}

.endpoint-card:hover::before {
  width: 6px;
}

.endpoint-list {
  display: grid;
  gap: 12px;
  font-size: 13px;
  color: #334155;
}

.endpoint-item {
  display: grid;
  grid-template-columns: 120px 1fr;
  align-items: center;
  gap: 12px;
  background: #ffffff;
  border: 1px solid #e5e7eb;
  border-radius: 8px;
  padding: 10px 14px;
}

.badge {
  font-size: 11px;
  font-weight: 800;
  padding: 4px 10px;
  border-radius: 6px;
  color: #fff;
  text-transform: uppercase;
  letter-spacing: 0.4px;
  background: #1e40af;
}

.info-note {
  background: linear-gradient(135deg, #eff6ff 0%, #ffffff 100%);
  border-left: 4px solid #3b82f6;
  padding: 14px 18px;
  border-radius: 8px;
  font-size: 13px;
  color: #1e40af;
  margin: 20px 0;
  line-height: 1.6;
}

.warn-note {
  background: linear-gradient(135deg, #fef3c7 0%, #ffffff 100%);
  border-left: 4px solid #f59e0b;
  padding: 14px 18px;
  border-radius: 8px;
  font-size: 13px;
  color: #0f172a;
  margin: 20px 0;
  line-height: 1.6;
}

.table-container {
  overflow: auto;
  border: 0;
  border-radius: 0;
  margin: 20px 0;
  background: transparent;
}

.table-container table {
  width: 100%;
  border-collapse: collapse;
  font-size: 13px;
}

.table-container th,
.table-container td {
  border-top: 1px solid #e5e7eb;
  padding: 12px 16px;
  text-align: left;
}

.table-container thead th {
  background: linear-gradient(135deg, #f8fafc 0%, #ffffff 100%);
  font-weight: 700;
  color: #0f172a;
  font-size: 13px;
}

.table-container tbody tr:hover {
  background: #f8fafc;
}

.details-container {
  background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%);
  border: 1px solid #e5e7eb;
  border-radius: 10px;
  padding: 8px 12px;
  margin: 20px 0;
}

.details-container summary {
  font-weight: 700;
  color: #1e40af;
  cursor: pointer;
  font-size: 14px;
  padding: 10px 0 10px 28px;
  display: flex;
  align-items: center;
  position: relative;
}
.details-container summary::-webkit-details-marker { display: none; }
.details-container summary::before {
  content: '';
  position: absolute;
  left: 10px;
  width: 0; height: 0;
  border-left: 7px solid #1e40af;
  border-top: 6px solid transparent;
  border-bottom: 6px solid transparent;
  transition: transform .2s ease;
}
.details-container[open] summary::before { transform: rotate(90deg); }

.code-block {
  margin-top: 12px;
  border-radius: 8px;
  overflow: hidden;
}

.tips-section {
  margin: 32px 0;
}

.tip-card {
  background: linear-gradient(135deg, #ffffff 0%, #f0fdf4 100%);
  border: 2px solid #d1fae5;
  border-radius: 12px;
  padding: 18px 20px;
  margin-bottom: 16px;
  transition: all 0.3s ease;
}

.tip-card:hover {
  transform: translateY(-2px);
  border-color: #10b981;
  box-shadow: 0 6px 20px rgba(16, 185, 129, 0.15);
}

.tip-text {
  font-size: 14px;
  line-height: 1.7;
  color: #475569;
  margin: 0;
  display: flex;
  align-items: flex-start;
  gap: 10px;
}

.tip-icon {
  color: #10b981;
  font-size: 18px;
  flex-shrink: 0;
  margin-top: 2px;
  font-weight: 700;
}

.section-title {
  font-size: 20px;
  font-weight: 700;
  color: #0f172a;
  margin: 32px 0 20px 0;
  padding-bottom: 12px;
  border-bottom: 2px solid #e5e7eb;
}

@media (max-width: 768px) {
  .hero-grid,
  .flow-grid {
    grid-template-columns: 1fr;
  }
  .endpoint-item {
    grid-template-columns: 100px 1fr;
    font-size: 12px;
  }
  .endpoint-item code {
    font-size: 11px;
  }
}
`}

Visão geral
O que é
Um único QR Code que permite pagar agora e ativar a recorrência no mesmo fluxo.
Quando usar
Casos com cobrança inicial obrigatória (ex.: adesão, matrícula, primeira mensalidade).
Como funciona
O pagador lê o QR → realiza o primeiro pagamento → autoriza a recorrência imediatamente.
Benefícios
Receita imediata + recorrência configurada, reduzindo fricção e inadimplência.

### Fluxo da Jornada 3

1. Ler o QR Code
O usuário escaneia o QR dinâmico gerado para a cobrança inicial.
2. Pagar Agora
O pagamento imediato é processado, registrando a cobrança inicial.
3. Autorizar Recorrência
Na mesma experiência, o usuário confirma a autorização da recorrência.
4. Recorrência Ativa
Próximos ciclos são automatizados; você só precisa conciliar valores quando necessário.

---

## Request

ENDPOINT
/account/ account_key /outgoing_recurrence/journey_three
MÉTODO
POST

### Path Params

Campo Tipo Descrição Caracteres
account_key &#42; uuid4 Chave única de identificação da conta. 36

### Request Body

**Request Body: Criar Recorrência (Jornada 3)**

```json
{
  "request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
  "periodicity": "monthly",
  "minimum_recurrence_amount": 125,
  "start_date": "2025-06-10",
  "end_date": "2027-06-10",
  "pix_message": "Conta de Luz Residencial nº123",
  "recurrence_type": "variable_amount",
  "debtor_data": {
    "name": "Sebastião",
    "email": "sebastiao@test.com",
    "document_number": "05431134850",
    "contract_id": "12345",
    "address": {
      "street": "Av. Brigadeiro Faria Lima",
      "state": "SP",
      "city": "São Paulo",
      "neighborhood": "Jardim Paulistano",
      "number": "2391",
      "postal_code": "01452905",
      "complement": "Complemento"
    }
  },
  "initial_payment_data": {
    "amount": 22.34,
    "pix_key": "3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
    "qr_code_type": "dynamic_term_composed",
    "additional_data": [
      {
        "key_name": "Juros e Multa",
        "value": "Juros 2 ao mes e multa de 1%"
      }
    ],
    "fine_amount": 3,
    "interest_amount": 2,
    "expiration_date": "2023-03-25",
    "max_payment_days": 128,
    "rebate_amount": 1,
    "discounts": [],
    "receiver_conciliation_id": "3d7d6a2bf72f44z7bb2079a94dff5645"
  },
  "retry_configuration": {
    "retry_allowed": true,
    "retry_rule": {
      "first_retry": {
        "day": "1"
      },
      "second_retry": {
        "day": "3"
      },
      "third_retry": {
        "day": "4"
      }
    }
  },
  "settlement_date_type": "workdays"
}
```

### Body Params

Campo Tipo Descrição Caracteres
request_control_key &#42; uuid Chave única da requisição (uuid4). 36
periodicity &#42; enumerator Periodicidade da recorrência. Enumeradores periodicity
minimum_recurrence_amount float Valor mínimo por transação (recorrências variáveis). -
start_date &#42; string Data de início (ISO 8601). -
end_date string Data de término ou null para indeterminado. -
pix_message &#42; string Mensagem exibida na transação Pix. 140
debtor_data &#42; Object Dados do assinante. Objeto debtor_data
retry_configuration &#42; Object Regras de retentativa. Objeto retry_configuration
settlement_date_type &#42; enumerator Ajuste da data de liquidação. Enumeradores settlement_date_type
recurrence_type &#42; enumerator Tipo da recorrência. Enumeradores recurrence_type
initial_payment_data &#42; Object Dados da cobrança inicial. Objeto initial_payment_data

Atenção: para recorrência de valor variável, informe minimum_recurrence_amount . Para valor fixo, envie recurrence_amount e ajuste o enumerador recurrence_type de acordo.

#### Enumeradores periodicity

Enumerador Descrição
weekly Recorrência semanal
monthly Recorrência mensal
quarterly Recorrência trimestral
semiannual Recorrência semestral
annual Recorrência anual

#### Enumeradores settlement_date_type

Enumerador Descrição
workdays Dias úteis
calendar_days Dias corridos

#### Enumeradores recurrence_type

Enumerador Descrição
fixed_amount Recorrência de Valor Fixo
variable_amount Recorrência de Valor Variável

#### Objeto debtor_data

Campo Tipo Descrição Caracteres
name &#42; string Nome do assinante. 50
email &#42; string E-mail do assinante. 100
document_number &#42; string CPF/CNPJ do assinante. 14
contract_id string Identificador do contrato. 100
address &#42; Object Endereço do assinante. Objeto address

#### Objeto address

Campo Tipo Descrição
street string Rua
state string Estado
city string Cidade
neighborhood string Bairro
number string Número
postal_code string CEP
complement string Complemento

#### Objeto retry_configuration

Campo Tipo Descrição
retry_allowed boolean Habilita retentativas
retry_rule Object Regras de retentativa

#### Objeto retry_rule

Campo Tipo Descrição
first_retry Object Primeira retentativa
second_retry Object Segunda retentativa
third_retry Object Terceira retentativa

#### Objeto retry_detail

Campo Tipo Descrição
day string Dia da retentativa

#### Objeto initial_payment_data

Campo Tipo Descrição Caracteres
amount &#42; number Valor da cobrança inicial (R$). -
pix_key &#42; string Chave Pix de destino. 77
qr_code_type &#42; enumerator Tipo de QR Code da cobrança inicial. Enumeradores qr_code_type
additional_data &#42; array Lista de dados adicionais (ex.: juros/multa). Objetos additional_data
fine_amount number Multa por atraso. -
interest_amount number Juros por atraso. -
expiration_date &#42; string Data de expiração (ISO 8601). -
max_payment_days integer Dias máximos após expiração para aceitar o pagamento. -
rebate_amount number Desconto por antecipação. -
discounts array Descontos adicionais. -
receiver_conciliation_id string Identificador para conciliação pelo recebedor. 32

#### Enumeradores qr_code_type

Valor Descrição
dynamic_instant_composed QR dinâmico para pagamento imediato
dynamic_term_composed QR dinâmico com prazo (vencimento futuro)

#### Objetos additional_data

Campo Tipo Descrição
key_name string Rótulo da informação (ex.: Juros e Multa)
value string Valor/descrição

---

## Response

STATUS
200

**Response Body (exemplo)**

```json
{
  "request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
  "outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "outgoing_recurrence_status": "pending_confirmation",
  "qr_code_data": {
    "qr_code_url": "url",
    "qr_code_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc85",
    "qr_code_image": "imageb64"
  },
  "initial_payment_data": {
    "receiver_conciliation_id": "6f270b64-1b7a-4269-91f8-3f9cf30ba0bb"
  },
  "created_at": "2021-10-22T20:30:23.459Z"
}
```

### Campos do Response

Campo Tipo Descrição Caracteres
request_control_key uuid Chave de controle enviada pelo cliente 36
recurrence_key uuid Identificação da recorrência de assinatura 36
recurrence_status enumerator Status da recorrência Enumeradores recurrence_status
qr_code_data Object Dados do QR gerado para o primeiro pagamento Objeto qr_code_data
initial_payment_data Object Informações do pagamento inicial Objeto initial_payment_data
created_at string Data/hora de criação (ISO 8601) -

#### Objeto qr_code_data

Campo Tipo Descrição Caracteres
qr_code_url string URL do copia e cola -
qr_code_key uuid Identificador do QR 36
qr_code_image string Imagem (Base64) -

#### Objeto initial_payment_data

Campo Tipo Descrição Caracteres
receiver_conciliation_id string ID de conciliação do pagamento 32

#### Enumeradores recurrence_status

Enumerador Descrição
pending_confirmation Pendente de confirmação
active Ativa
cancelled Cancelada
suspended Suspensa
expired Expirada

---

## Dicas e Boas Práticas

✓
Conciliação em recorrência variável: para variable_amount , concilie o valor de 10 a 3 dias antes da data de cobrança.
✓
Mensagens Pix: utilize pix_message com até 140 caracteres para explicar claramente a cobrança inicial.
⚠
Segurança: valide documentos/contas e trate erros de rede e de integrações externas com retentativas idempotentes.

---

# Criar uma Recorrência (Jornada 2)

URL: /documentation/baas/pix_automatico/recebedor/journey_two

> Jornada 2 — QR Code com dados apenas da recorrência

{`
.hero-section { background: linear-gradient(135deg, #eff6ff 0%, #ffffff 100%); border: 1px solid #e5e7eb; border-radius: 16px; padding: 24px; margin: 24px 0 32px 0; }
.hero-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); gap: 16px; margin-top: 20px; }
.hero-item { background: #ffffff; border: 1px solid #e5e7eb; border-radius: 10px; padding: 16px; }
.hero-item > strong { display: block; color: #1e40af; font-size: 14px; margin-bottom: 6px; font-weight: 700; }
.hero-item p { margin: 0; font-size: 13px; color: #475569; line-height: 1.5; }

.endpoint-card { background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%); border: 2px solid #e5e7eb; border-radius: 12px; padding: 24px; position: relative; overflow: hidden; }
.endpoint-card::before { content: ''; position: absolute; top: 0; left: 0; width: 4px; height: 100%; background: linear-gradient(to bottom, #3b82f6, #1e40af); }
.endpoint-list { display: grid; gap: 12px; font-size: 13px; color: #334155; }
.endpoint__item { display: grid; grid-template-columns: 120px 1fr; align-items: center; gap: 12px; background: #ffffff; border: 1px solid #e5e7eb; border-radius: 8px; padding: 10px 14px; }
.badge { font-size: 11px; font-weight: 800; padding: 4px 10px; border-radius: 6px; color: #fff; text-transform: uppercase; letter-spacing: .4px; background: #1e40af; }

.details-container { background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%); border: 1px solid #e5e7eb; border-radius: 10px; padding: 8px 12px; margin: 20px 0; }
.details-container summary { font-weight: 700; color: #1e40af; cursor: pointer; font-size: 14px; padding: 10px 0 10px 28px; display: flex; align-items: center; position: relative; }
.details-container summary::-webkit-details-marker { display: none; }
.details-container summary::before { content: ''; position: absolute; left: 10px; width: 0; height: 0; border-left: 7px solid #1e40af; border-top: 6px solid transparent; border-bottom: 6px solid transparent; transition: transform .2s ease; }
.details-container[open] summary::before { transform: rotate(90deg); }
.code-block { margin-top: 12px; border-radius: 8px; overflow: hidden; }

.table-container { overflow: auto; border: 0; border-radius: 0; margin: 20px 0; background: transparent; }
.table-container table { width: 100%; border-collapse: collapse; font-size: 13px; }
.table-container th, .table-container td { border-top: 1px solid #e5e7eb; padding: 12px 16px; text-align: left; }
.table-container thead th { background: linear-gradient(135deg, #f8fafc 0%, #ffffff 100%); font-weight: 700; color: #0f172a; font-size: 13px; }
`}

Visão geral
O que é QR Code que apresenta apenas os dados da recorrência para o pagador autorizar, sem cobrança imediata.
Quando usar Onboarding sem cobrança inicial; uso em pontos de venda, balcões, telas ou materiais impressos.
Como funciona Pagador lê o QR → visualiza os dados da recorrência no app → autoriza → futuras cobranças poderão ser agendadas.
Benefícios Habilitação ágil via QR; permite captação em massa de clientes com baixo atrito e o QR pode ser reutilizado para novas recorrências.

:::info Importante — prazo de autorização
O QR Code em si não possui `expiration_date`: não há cobrança inicial associada a ele, e ele pode ser reutilizado para autorizar novas recorrências.

Porém, a recorrência criada tem uma `start_date`. Se o pagador **não autorizar até a `start_date`**, o `recurrence_status` muda automaticamente para `expired` — e uma nova recorrência precisa ser criada, já que não é possível reaproveitar uma recorrência expirada.
:::

## Request

{`
.endpoint-card { background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%); border: 2px solid #e5e7eb; border-radius: 12px; padding: 24px; position: relative; overflow: hidden; }
.endpoint-card::before { content: ''; position: absolute; top: 0; left: 0; width: 4px; height: 100%; background: linear-gradient(to bottom, #3b82f6, #1e40af); }
.endpoint-list { display: grid; gap: 12px; font-size: 13px; color: #334155; }
.endpoint__item { display: grid; grid-template-columns: 120px 1fr; align-items: center; gap: 12px; background: #ffffff; border: 1px solid #e5e7eb; border-radius: 8px; padding: 10px 14px; }
.badge { font-size: 11px; font-weight: 800; padding: 4px 10px; border-radius: 6px; color: #fff; text-transform: uppercase; letter-spacing: .4px; background: #1e40af; }
.details-container { background: linear-gradient(135deg, #ffffff 0%, #f8fafc 100%); border: 1px solid #e5e7eb; border-radius: 10px; padding: 8px 12px; margin: 20px 0; }
.details-container summary { font-weight: 700; color: #1e40af; cursor: pointer; font-size: 14px; padding: 10px 0 10px 28px; display: flex; align-items: center; position: relative; }
.details-container summary::-webkit-details-marker { display: none; }
.details-container summary::before { content: ''; position: absolute; left: 10px; width: 0; height: 0; border-left: 7px solid #1e40af; border-top: 6px solid transparent; border-bottom: 6px solid transparent; transition: transform .2s ease; }
.details-container[open] summary::before { transform: rotate(90deg); }
.code-block { margin-top: 12px; border-radius: 8px; overflow: hidden; }
`}

ENDPOINT /account/ account_key /outgoing_recurrence/journey_two
MÉTODO POST

### Request Path Params

| Campo         | Tipo  | Descrição                                      | Caracteres |
|---------------|-------|------------------------------------------------|------------|
| `account_key`*| uuid4 | Chave única de identificação da conta.          | 36         |

### Request Body

**Request Body: Criar Recorrência (Jornada 2)**

```json
{
    "request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "periodicity": "monthly",
    "minimum_recurrence_amount": 125,
    "start_date": "2025-06-10",
    "end_date": "2027-06-10",
    "pix_message": "Conta de Luz Residencial nº123",
    "recurrence_type": "variable_amount",
    "debtor_data": {
        "name": "Sebastião",
        "email": "sebastiao@test.com",
        "document_number": "05431134850",
        "contract_id": "124587624",
        "address": {
            "street": "Av. Brigadeiro Faria Lima",
            "state": "SP",
            "city": "São Paulo",
            "neighborhood": "Jardim Paulistano",
            "number": "2391",
            "postal_code": "01452905",
            "complement": "Complemento"
        }
    },
    "retry_configuration": {
        "retry_allowed": true,
        "retry_rule": {
            "first_retry": {
                "day": "1"
            },
            "second_retry": {
                "day": "3"
            },
            "third_retry": {
                "day": "4"
            }
        }
    },
    "settlement_date_type": "workdays"
}
```

### Body Params

| Campo                          | Tipo       | Descrição                                                                                                  | Caracteres |
|--------------------------------|------------|------------------------------------------------------------------------------------------------------------|------------|
| `request_control_key` *        | uuid       | Chave única de identificação da requisição utilizada pelo cliente no formato uuid4.                        | 36         |
| `periodicity` *                | enumerator | Tipo da periodicidade associada à recorrência da assinatura.                                               | [Enumeradores periodicity](#enumeradores-periodicity) |
| `minimum_recurrence_amount`   | number     | Valor mínimo da transação para recorrências de valor variável (em centavos).                               | -          |
| `start_date` *                 | string     | Data de início da recorrência (formato ISO 8601, e.g., "2025-07-01").                                      | -          |
| `end_date`                     | string     | Data de término da recorrência; para tempo indeterminado, enviar como null.                                | -          |
| `pix_message` *                | string     | Mensagem a ser enviada junto à transação Pix.                                                              | 140        |
| `debtor_data` *                | Object     | Dados do devedor (assinante).                                                                              | [Objeto debtor_data](#objeto-debtor_data) |
| `retry_configuration` *        | Object     | Configuração de retentativas para transações não concluídas.                                               | [Objeto retry_configuration](#objeto-retry_configuration) |
| `settlement_date_type` *       | enumerator | Tipo de ajuste da data de liquidação                                                                       | [Enumeradores settlement_date_type](#enumeradores-settlement_date_type) |
| `recurrence_type` *       | enumerator | Tipo de recorrência                                                                                             | [Enumeradores recurrence_type](#enumeradores-recurrence_type) |

:::caution Atenção
O campo `minimum_recurrence_amount` é opcional e deve ser informado apenas para recorrência de valor variável. Caso a recorrência seja de valor fixo, deve-se enviar o campo `recurrence_amount`, com o valor da recorrência. Assim como o enumerador `recurrence_type`, que deverá corresponder ao tipo da recorrência (Valor fixo ou variável).
:::

### Enumeradores periodicity

| Enumerador   | Descrição             |
|--------------|-----------------------|
| `weekly`     | Recorrência semanal   |
| `monthly`    | Recorrência mensal    |
| `quarterly`  | Recorrência trimestral|
| `semiannual` | Recorrência semestral |
| `annual`     | Recorrência anual     |

### Enumeradores settlement_date_type

| Enumerador   | Descrição             |
|--------------|-----------------------|
| `workdays`     | Dias úteis   |
| `calendar_days`     | Dias corridos   |

### Enumeradores recurrence_type

| Enumerador   | Descrição             |
|--------------|-----------------------|
| `fixed_amount`     | Recorrência de Valor Fixo   |
| `variable_amount`     | Recorrência de Valor Variável   |

### Objeto debtor_data

| Campo               | Tipo   | Descrição             | Caracteres |
|---------------------|--------|-----------------------|------------|
| `name` *            | string | Nome do assinante.    | 50         |
| `email` *           | string | E-mail do assinante.  | 100        |
| `document_number` * | string | CPF ou CNPJ do assinante. | 14      |
| `contract_id`       | string | Identificador do contrato do assinante. | 100      |
| `address` *         | Object | Endereço do assinante.| [Objeto address](#objeto-address) |

### Objeto address

| Campo         | Tipo   | Descrição         | Caracteres |
|---------------|--------|-------------------|------------|
| `street`      | string | Rua.              | -          |
| `state`       | string | Estado.           | -          |
| `city`        | string | Cidade.           | -          |
| `neighborhood`| string | Bairro.           | -          |
| `number`      | string | Número.           | -          |
| `postal_code` | string | CEP.              | -          |
| `complement`  | string | Complemento.      | -          |

### Objeto retry_configuration

| Campo         | Tipo    | Descrição               | Caracteres |
|---------------|---------|-------------------------|------------|
| `retry_allowed`| boolean | Indica se retentativas são permitidas. | -     |
| `retry_rule`  | Object  | Regras de retentativa.  | [Objeto retry_rule](#objeto-retry_rule) |

### Objeto retry_rule

| Campo         | Tipo   | Descrição               | Caracteres |
|---------------|--------|-------------------------|------------|
| `first_retry` | Object | Configuração da primeira retentativa. | [Objeto retry_detail](#objeto-retry_detail) |
| `second_retry`| Object | Configuração da segunda retentativa.  | [Objeto retry_detail](#objeto-retry_detail) |
| `third_retry` | Object | Configuração da terceira retentativa. | [Objeto retry_detail](#objeto-retry_detail) |

### Objeto retry_detail

| Campo | Tipo   | Descrição               | Caracteres |
|-------|--------|-------------------------|------------|
| `day` | string | Dia da retentativa.     | -          |

## Response

STATUS 200

**Response Body**

```json
{
    "request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "outgoing_recurrence_status": "pending_confirmation",
    "qr_code_data": {
	    "qr_code_url": "url",
	    "qr_code_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc85",
	    "qr_code_image": "imageb64"  
    },
    "created_at": "2021-10-22T20:30:23.459Z"
}
```

### Response Body

| Campo                 | Tipo       | Descrição                                                                 | Caracteres |
|-----------------------|------------|---------------------------------------------------------------------------|------------|
| `request_control_key` | uuid       | Chave de controle da requisição enviada pelo cliente.                     | 36         |
| `recurrence_key`      | uuid       | Chave única de identificação da recorrência de assinatura.                | 36         |
| `recurrence_status`   | enumerator | Status atual da recorrência.                                              | [Enumeradores recurrence_status](#enumeradores-recurrence_status) |
| `qr_code_data`   | enumerator | Status atual da recorrência.                                              | [Objeto qr_code_data](#enumeradores-qr_code_data) |
| `created_at`          | string     | Data e hora de criação da recorrência (formato ISO 8601).                 | -          |

### Objeto qr_code_data

| Campo | Tipo   | Descrição               | Caracteres |
|-------|--------|-------------------------|------------|
| `qr_code_url` | string | URL do copia e cola do qr_code     | -          |
| `qr_code_key`| uuuid | Chave Única de identificação do qr_code. | 36          |
| `qr_code_image`| string | Base64 da imagem do qr_code | -         |

### Enumeradores recurrence_status

| Enumerador           | Descrição                         |
|----------------------|-----------------------------------|
| `pending_confirmation` | Recorrência pendente de confirmação |
| `active`              | Recorrência ativa                 |
| `cancelled`           | Recorrência cancelada             |
| `suspended`           | Recorrência suspensa              |
| `expired`             | Recorrência expirada — ocorre quando o pagador não autoriza até a `start_date` |

STATUS 4XX

**Response Error**

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em português",
  "code": "codigo"
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                | Descrição (eng)<br/>`description`                                          | Descrição (ptbr)<br/>`translation`                                 |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400         | QIT000002            | Bad Request                       | Invalid request schema.                                                    | Erro no esquema da requisição.                                     |
| 403         | APX000030            | Unauthorized Transaction          | User is not authorized to create this recurrence.                          | Usuário não autorizado a criar esta recorrência.                   |
| 403         | APX000018            | Endpoint Access Denied            | Requester lacks permission to access this endpoint.                        | Requester não possui permissão para acessar este endpoint.          |
| 404         | APX000021            | Subscription Not Found            | Subscription \{subscription_key\} not found.                               | Assinatura \{subscription_key\} não encontrada.                     |
| 404         | APX000002            | Recurrence Not Found              | Recurrence \{recurrence_key\} not found.                                   | Recorrência \{recurrence_key\} não encontrada.                      |
| 406         | APX000027            | Invalid Transaction Amount        | Transaction amount \{minimum_transaction_amount\} is invalid.              | Valor da transação \{minimum_transaction_amount\} é inválido.        |
| 409         | APX000014            | Request Control Key Conflict      | The request_control_key \{request_control_key\} is already in use.         | A request_control_key \{request_control_key\} já está em uso.        |

---

# Listagem de Recorrências de um Requester

URL: /documentation/baas/pix_automatico/recebedor/listar_recorrencias_de_um_requester

## Request

ENDPOINT /outgoing_recurrences
MÉTODO GET

### Query Params

| Campo                       | Tipo        | Descrição                                                              | Caracteres |
|-----------------------------|-------------|------------------------------------------------------------------------|------------|
| `outgoing_recurrence_status`| enumerador      | Filtra recorrências pelo status (`approved`, `pending`, `rejected`, `pending_confirmation`) | 30         |
| `page`                      | integer     | Número da página a ser retornada (paginação).                          | -          |
| `page_size`                 | integer     | Número de itens por página (paginação).                                | -          |

---

## Response

STATUS 200

Response Body

```json
{
  "outgoing_recurrences": [
    {
      "request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
      "outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "outgoing_recurrence_status": "approved",
      "periodicity": "monthly",
      "journey_type": "journey_four",
      "start_date": "2025-06-10",
      "end_date": "2027-06-10",
      "account_key": "uuuid",
      "outgoing_recurrence_data": {
        "minimum_recurrence_amount": 123.45,
        "recurrence_amount": null,
        "retry_configuration": {
          "retry_allowed": true,
          "retry_rule": {
            "first_retry": {
              "day": "1",
              "time": "14:00"
            },
            "second_retry": {
              "day": "3",
              "time": "12:00"
            },
            "third_retry": {
              "day": "4",
              "time": "15:32"
            }
          }
        },
        "debtor_data": {
          "name": "Sebastião",
          "email": "sebastiao@test.com",
          "document_number": "05431134850",
          "address": {
            "city": "São Paulo",
            "postal_code": "123456-789",
            "uf": "SP",
            "street": "Av Paulista 123"
          },
          "account_data": {
            "account_number": "123456",
            "account_digit": "7",
            "account_branch": "0001",
            "ispb": "31872495"
          }
        },
        "qr_code_data": {
          "qr_code_key": "0f45cc3d-9bd1-4d68-a865-4cf477b5da45",
          "qr_code_url": "urlqrcode.url",
          "qr_code_image": "image_base64"
        },
        "initial_payment_data": {
          "amount": 22.34,
          "pix_key": "3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
          "qr_code_type": "dynamic_term_composed",
          "additional_data": [
            {
              "key_name": "Juros e Multa",
              "value": "Juros 2 ao mes e multa de 1%"
            }
          ],
          "fine_amount": 3,
          "interest_amount": 2,
          "expiration_date": "2023-03-25",
          "max_payment_days": 128,
          "rebate_amount": 1,
          "discounts": [],
          "receiver_conciliation_id":"3d7d6a2bf72f44z7bb2079a94dff5645",
          "transaction_data":{
            "transaction_key":"4d7d6a2b-f72f-44z7-bb20-79a94dff5645",
            "pix_transfer_key":"5d7d6a2b-f72f-44z7-bb20-79a94dff5645",
            "end_to_end_id":"E32402502202303141907qlBAF1evdJ2"
         }
        },
        "pix_message": "Conta de Luz Residencial nº123",
        "settlement_date_type": "calendar_days"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 25,
    "number_of_pages": 4
  }
}
```

### Response Body Params

| Campo                  | Tipo   | Descrição                                                                               | Caracteres |
|------------------------|--------|-----------------------------------------------------------------------------------------|------------|
| `outgoing_recurrences` | array  | Lista de objetos de recorrências automáticas.                                           | [Array outgoing_recurrences](#array-outgoing_recurrences) |
| `pagination`           | object | Objeto de paginação contendo informações sobre as páginas dos resultados.               | [Objeto pagination](#objeto-pagination)                   |

---

### Array outgoing_recurrences

| Campo                        | Tipo       | Descrição                                                                               | Caracteres |
|------------------------------|------------|-----------------------------------------------------------------------------------------|------------|
| `request_control_key`        | uuidv4     | Chave única para controle da requisição.                                                | 36         |
| `outgoing_recurrence_key`    | uuidv4     | Identificador da recorrência automática.                                                | 36         |
| `account_key`                | uuidv4     | Chave única de identificação da conta                                                   | 36         |
| `outgoing_recurrence_status` | string     | Status atual da recorrência (`approved`, `pending`, `rejected`, etc.).                  | 30         |
| `periodicity`                | enumerator | Periodicidade da recorrência.                                                           | [Enumeradores periodicity](#enumeradores-periodicity)      |
| `journey_type`               | enumerator | Jornada da recorrência automática.                                                      | [Enumeradores journey_type](#enumeradores-journey_type)    |
| `start_date`                 | string     | Data de início da recorrência (formato ISO 8601, e.g., `2025-06-10`).                  | 10         |
| `end_date`                   | string     | Data de término da recorrência (formato ISO 8601) ou null, se indeterminado.            | 10 ou null |
| `outgoing_recurrence_data`   | object     | Objeto agrupando parâmetros da assinatura e dados complementares.                       | [Objeto outgoing_recurrence_data](#objeto-outgoing_recurrence_data) |

---

### Objeto outgoing_recurrence_data

| Campo                       | Tipo     | Descrição                                                      | Caracteres |
|-----------------------------|----------|----------------------------------------------------------------|------------|
| `minimum_recurrence_amount` | number   | Valor mínimo esperado nas recorrências de valor variável        | -          |
| `recurrence_amount`         | number   | Valor da recorrência (para valor fixo; null se variável)        | -          |
| `retry_configuration`       | object   | Configuração de tentativas para recorrências não concluídas      | [Objeto retry_configuration](#objeto-retry_configuration) |
| `debtor_data`               | object   | Dados do devedor (assinante)                                    | [Objeto debtor_data](#objeto-debtor_data)                |
| `qr_code_data`              | object   | Dados de QR Code gerado para o pagamento (se houver)            | [Objeto qr_code_data](#objeto-qr_code_data)              |
| `initial_payment_data`      | object   | Dados da cobrança inicial                                       | [Objeto initial_payment_data](#objeto-initial_payment_data) |
| `pix_message`               | string   | Mensagem enviada junto à transação Pix                          | 140        |
| `settlement_date_type`      | enumerator| Tipo do ajuste da data de liquidação                            | [Enumeradores settlement_date_type](#enumeradores-settlement_date_type) |

---

### Objeto retry_configuration

| Campo           | Tipo    | Descrição                                   | Caracteres |
|-----------------|---------|---------------------------------------------|------------|
| `retry_allowed` | boolean | Indica se retentativas estão habilitadas    | -          |
| `retry_rule`    | object  | Regras detalhadas das retentativas          | [Objeto retry_rule](#objeto-retry_rule) |

---

### Objeto retry_rule

| Campo         | Tipo   | Descrição                         | Caracteres |
|---------------|--------|-----------------------------------|------------|
| `first_retry` | object | Configuração para 1ª retentativa  | [Objeto retry_detail](#objeto-retry_detail) |
| `second_retry`| object | Configuração para 2ª retentativa  | [Objeto retry_detail](#objeto-retry_detail) |
| `third_retry` | object | Configuração para 3ª retentativa  | [Objeto retry_detail](#objeto-retry_detail) |

---

### Objeto retry_detail

| Campo | Tipo   | Descrição               | Caracteres |
|-------|--------|-------------------------|------------|
| `day` | string | Dia da retentativa.     | -          |
| `time`| string | Horário da retentativa. | -          |

---

### Objeto debtor_data

| Campo             | Tipo   | Descrição              | Caracteres |
|-------------------|--------|------------------------|------------|
| `name`            | string | Nome do assinante.     | 50         |
| `email`           | string | E-mail do assinante.   | 100        |
| `document_number` | string | CPF ou CNPJ.           | 14         |
| `address`         | object | Endereço do assinante. | [Objeto address](#objeto-address) |
| `account_data`    | object | Dados bancários.       | [Objeto account_data](#objeto-account_data) |

---

### Objeto address

| Campo         | Tipo   | Descrição         | Caracteres |
|---------------|--------|-------------------|------------|
| `city`        | string | Cidade.           | -          |
| `postal_code` | string | CEP.              | -          |
| `uf`          | string | Estado (sigla).   | -          |
| `street`      | string | Logradouro.       | -          |

---

### Objeto account_data

| Campo           | Tipo   | Descrição                    | Caracteres |
|-----------------|--------|------------------------------|------------|
| `account_number`| string | Número da conta              | -          |
| `account_digit` | string | Dígito da conta              | -          |
| `account_branch`| string | Agência                      | -          |
| `ispb`          | string | ISPB da instituição financeira| -         |

---

### Objeto qr_code_data

| Campo            | Tipo   | Descrição                                   | Caracteres |
|------------------|--------|---------------------------------------------|------------|
| `qr_code_key`    | string | Identificador do QR Code gerado             | -          |
| `qr_code_url`    | string | URL para visualização do QR Code            | -          |
| `qr_code_image`  | string | Imagem do QR Code (em Base64)               | -          |

---

### Objeto initial_payment_data

| Campo                     | Tipo     | Descrição                                                                | Caracteres |
|---------------------------|----------|--------------------------------------------------------------------------|------------|
| `amount`                  | number   | Valor principal da cobrança inicial em reais (R$)                        | -          |
| `pix_key`                 | string   | Chave Pix de destino para o pagamento inicial                            | 77         |
| `qr_code_type`            | enum     | Tipo de QR Code para cobrança inicial.                                   | [Enumeradores qr_code_type](#enumeradores-qr_code_type) |
| `additional_data`         | array    | Lista de informações adicionais relacionadas à cobrança                   | [Array de objects additional_data](#array-additional_data) |
| `fine_amount`             | number   | Valor da multa, caso ocorra atraso no pagamento                          | -          |
| `interest_amount`         | number   | Valor dos juros, caso ocorra atraso no pagamento                         | -          |
| `expiration_date`         | string   | Data de expiração da cobrança inicial (formato ISO 8601)                 | 10         |
| `max_payment_days`        | integer  | Número máximo de dias de aceite após expiração                           | -          |
| `rebate_amount`           | number   | Valor do desconto para pagamento antecipado                              | -          |
| `discounts`               | array    | Lista de descontos adicionais                                            | -          |
| `receiver_conciliation_id`| string   | Identificador de conciliação do pagamento pelo recebedor                 | 35         |
| `transaction_data`        | object   | Detalhes da transação relacionada à cobrança inicial                     | [Objeto transaction_data](#objeto-transaction_data) |

---

### Array additional_data

| Campo        | Tipo    | Descrição                                                 | Caracteres |
|--------------|---------|-----------------------------------------------------------|------------|
| `key_name`   | string  | Nome da informação adicional (ex: "Juros e Multa")        | 140        |
| `value`      | string  | Valor ou descrição da informação adicional                | 140        |

---

### Objeto transaction_data

| Campo               | Tipo   | Descrição                              | Caracteres |
|---------------------|--------|----------------------------------------|------------|
| `transaction_key`   | string | Chave única da transação               | 36         |
| `pix_transfer_key`  | string | Identificador da transferência Pix     | 36         |
| `end_to_end_id`     | string | Identificador end-to-end do Pix        | 32         |

---

### Objeto pagination

| Campo            | Tipo    | Descrição                           | Caracteres |
|------------------|---------|-------------------------------------|------------|
| `page`           | integer | Número da página retornada.         | -          |
| `page_size`      | integer | Quantidade de itens por página.     | -          |
| `number_of_pages`| integer | Total de páginas disponíveis.       | -          |

---

### Enumeradores periodicity

| Enumerador   | Descrição              |
|--------------|-----------------------|
| `weekly`     | Recorrência semanal   |
| `monthly`    | Recorrência mensal    |
| `quarterly`  | Recorrência trimestral|
| `semiannual` | Recorrência semestral |
| `annual`     | Recorrência anual     |

---

### Enumeradores journey_type

| Enumerador      | Descrição                                    |
|-----------------|----------------------------------------------|
| `journey_one`   | Notificação direta no aplicativo bancário     |
| `journey_two`   | Experiência QR Code para cobrança recorrente  |
| `journey_three` | Pagamento instantâneo + recorrência QR Code   |
| `journey_four`  | Opt-in recorrente a partir de operação Pix    |

---

### Enumeradores settlement_date_type

| Enumerador      | Descrição         |
|-----------------|------------------|
| `workdays`      | Dias úteis        |
| `calendar_days` | Dias corridos     |

---

### Enumeradores qr_code_type

| Enumerador                 | Descrição                                             |
|----------------------------|-------------------------------------------------------|
| `dynamic_instant_composed` | QR Code dinâmico para pagamento instantâneo           |
| `dynamic_term_composed`    | QR Code dinâmico para pagamento com vencimento futuro |

STATUS 4XX

Response Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em português",
  "code": "codigo"
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                | Descrição (eng)<br/>`description`                                          | Descrição (ptbr)<br/>`translation`                                 |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400         | QIT000002            | Bad Request                       | Invalid request schema.                                                    | Erro no esquema da requisição.                                     |
| 404         | APX000002            | Recurrence Not Found              | Recurrence \{recurrence_key\} not found.                                   | Recorrência \{recurrence_key\} não encontrada.                      |

---

# Listagem de Recorrências de uma Conta

URL: /documentation/baas/pix_automatico/recebedor/listar_recorrencias_de_uma_conta

## Request

ENDPOINT /account/ ACCOUNT_KEY /outgoing_recurrences
MÉTODO GET

### Query Params

| Campo                       | Tipo        | Descrição                                                              | Caracteres |
|-----------------------------|-------------|------------------------------------------------------------------------|------------|
| `outgoing_recurrence_status`| enumerador      | Filtra recorrências pelo status (`approved`, `pending`, `rejected`, `pending_confirmation`) | 30         |
| `page`                      | integer     | Número da página a ser retornada (paginação).                          | -          |
| `page_size`                 | integer     | Número de itens por página (paginação).                                | -          |

---

## Response

STATUS 200

Response Body

```json
{
  "outgoing_recurrences": [
    {
      "request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
      "outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "outgoing_recurrence_status": "approved",
      "periodicity": "monthly",
      "journey_type": "journey_four",
      "start_date": "2025-06-10",
      "end_date": "2027-06-10",
      "outgoing_recurrence_data": {
        "minimum_recurrence_amount": 123.45,
        "recurrence_amount": null,
        "retry_configuration": {
          "retry_allowed": true,
          "retry_rule": {
            "first_retry": {
              "day": "1",
              "time": "14:00"
            },
            "second_retry": {
              "day": "3",
              "time": "12:00"
            },
            "third_retry": {
              "day": "4",
              "time": "15:32"
            }
          }
        },
        "debtor_data": {
          "name": "Sebastião",
          "email": "sebastiao@test.com",
          "document_number": "05431134850",
          "address": {
            "city": "São Paulo",
            "postal_code": "123456-789",
            "uf": "SP",
            "street": "Av Paulista 123"
          },
          "account_data": {
            "account_number": "123456",
            "account_digit": "7",
            "account_branch": "0001",
            "ispb": "31872495"
          }
        },
        "qr_code_data": {
          "qr_code_key": "0f45cc3d-9bd1-4d68-a865-4cf477b5da45",
          "qr_code_url": "urlqrcode.url",
          "qr_code_image": "image_base64"
        },
        "initial_payment_data": {
          "amount": 22.34,
          "pix_key": "3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
          "qr_code_type": "dynamic_term_composed",
          "additional_data": [
            {
              "key_name": "Juros e Multa",
              "value": "Juros 2 ao mes e multa de 1%"
            }
          ],
          "fine_amount": 3,
          "interest_amount": 2,
          "expiration_date": "2023-03-25",
          "max_payment_days": 128,
          "rebate_amount": 1,
          "discounts": [],
          "receiver_conciliation_id":"3d7d6a2bf72f44z7bb2079a94dff5645",
          "transaction_data":{
            "transaction_key":"4d7d6a2b-f72f-44z7-bb20-79a94dff5645",
            "pix_transfer_key":"5d7d6a2b-f72f-44z7-bb20-79a94dff5645",
            "end_to_end_id":"E32402502202303141907qlBAF1evdJ2"
          }
        },
        "pix_message": "Conta de Luz Residencial nº123",
        "settlement_date_type": "calendar_days"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 25,
    "number_of_pages": 4
  }
}
```

### Response Body Params

| Campo                  | Tipo   | Descrição                                                                               | Caracteres |
|------------------------|--------|-----------------------------------------------------------------------------------------|------------|
| `outgoing_recurrences` | array  | Lista de objetos de recorrências automáticas.                                           | [Array outgoing_recurrences](#array-outgoing_recurrences) |
| `pagination`           | object | Objeto de paginação contendo informações sobre as páginas dos resultados.               | [Objeto pagination](#objeto-pagination)                   |

---

### Array outgoing_recurrences

| Campo                        | Tipo       | Descrição                                                                               | Caracteres |
|------------------------------|------------|-----------------------------------------------------------------------------------------|------------|
| `request_control_key`        | uuidv4     | Chave única para controle da requisição.                                                | 36         |
| `outgoing_recurrence_key`    | uuidv4     | Identificador da recorrência automática.                                                | 36         |
| `outgoing_recurrence_status` | string     | Status atual da recorrência (`approved`, `pending`, `rejected`, etc.).                  | 30         |
| `periodicity`                | enumerator | Periodicidade da recorrência.                                                           | [Enumeradores periodicity](#enumeradores-periodicity)      |
| `journey_type`               | enumerator | Jornada da recorrência automática.                                                      | [Enumeradores journey_type](#enumeradores-journey_type)    |
| `start_date`                 | string     | Data de início da recorrência (formato ISO 8601, e.g., `2025-06-10`).                  | 10         |
| `end_date`                   | string     | Data de término da recorrência (formato ISO 8601) ou null, se indeterminado.            | 10 ou null |
| `outgoing_recurrence_data`   | object     | Objeto agrupando parâmetros da assinatura e dados complementares.                       | [Objeto outgoing_recurrence_data](#objeto-outgoing_recurrence_data) |

---

### Objeto outgoing_recurrence_data

| Campo                       | Tipo     | Descrição                                                      | Caracteres |
|-----------------------------|----------|----------------------------------------------------------------|------------|
| `minimum_recurrence_amount` | number   | Valor mínimo esperado nas recorrências de valor variável        | -          |
| `recurrence_amount`         | number   | Valor da recorrência (para valor fixo; null se variável)        | -          |
| `retry_configuration`       | object   | Configuração de tentativas para recorrências não concluídas      | [Objeto retry_configuration](#objeto-retry_configuration) |
| `debtor_data`               | object   | Dados do devedor (assinante)                                    | [Objeto debtor_data](#objeto-debtor_data)                |
| `qr_code_data`              | object   | Dados de QR Code gerado para o pagamento (se houver)            | [Objeto qr_code_data](#objeto-qr_code_data)              |
| `initial_payment_data`      | object   | Dados da cobrança inicial                                       | [Objeto initial_payment_data](#objeto-initial_payment_data) |
| `pix_message`               | string   | Mensagem enviada junto à transação Pix                          | 140        |
| `settlement_date_type`      | enumerator| Tipo do ajuste da data de liquidação                            | [Enumeradores settlement_date_type](#enumeradores-settlement_date_type) |

---

### Objeto retry_configuration

| Campo           | Tipo    | Descrição                                   | Caracteres |
|-----------------|---------|---------------------------------------------|------------|
| `retry_allowed` | boolean | Indica se retentativas estão habilitadas    | -          |
| `retry_rule`    | object  | Regras detalhadas das retentativas          | [Objeto retry_rule](#objeto-retry_rule) |

---

### Objeto retry_rule

| Campo         | Tipo   | Descrição                         | Caracteres |
|---------------|--------|-----------------------------------|------------|
| `first_retry` | object | Configuração para 1ª retentativa  | [Objeto retry_detail](#objeto-retry_detail) |
| `second_retry`| object | Configuração para 2ª retentativa  | [Objeto retry_detail](#objeto-retry_detail) |
| `third_retry` | object | Configuração para 3ª retentativa  | [Objeto retry_detail](#objeto-retry_detail) |

---

### Objeto retry_detail

| Campo | Tipo   | Descrição               | Caracteres |
|-------|--------|-------------------------|------------|
| `day` | string | Dia da retentativa.     | -          |
| `time`| string | Horário da retentativa. | -          |

---

### Objeto debtor_data

| Campo             | Tipo   | Descrição              | Caracteres |
|-------------------|--------|------------------------|------------|
| `name`            | string | Nome do assinante.     | 50         |
| `email`           | string | E-mail do assinante.   | 100        |
| `document_number` | string | CPF ou CNPJ.           | 14         |
| `address`         | object | Endereço do assinante. | [Objeto address](#objeto-address) |
| `account_data`    | object | Dados bancários.       | [Objeto account_data](#objeto-account_data) |

---

### Objeto address

| Campo         | Tipo   | Descrição         | Caracteres |
|---------------|--------|-------------------|------------|
| `city`        | string | Cidade.           | -          |
| `postal_code` | string | CEP.              | -          |
| `uf`          | string | Estado (sigla).   | -          |
| `street`      | string | Logradouro.       | -          |

---

### Objeto account_data

| Campo           | Tipo   | Descrição                    | Caracteres |
|-----------------|--------|------------------------------|------------|
| `account_number`| string | Número da conta              | -          |
| `account_digit` | string | Dígito da conta              | -          |
| `account_branch`| string | Agência                      | -          |
| `ispb`          | string | ISPB da instituição financeira| -         |

---

### Objeto qr_code_data

| Campo            | Tipo   | Descrição                                   | Caracteres |
|------------------|--------|---------------------------------------------|------------|
| `qr_code_key`    | string | Identificador do QR Code gerado             | -          |
| `qr_code_url`    | string | URL para visualização do QR Code            | -          |
| `qr_code_image`  | string | Imagem do QR Code (em Base64)               | -          |

---

### Objeto initial_payment_data

| Campo                     | Tipo     | Descrição                                                                | Caracteres |
|---------------------------|----------|--------------------------------------------------------------------------|------------|
| `amount`                  | number   | Valor principal da cobrança inicial em reais (R$)                        | -          |
| `pix_key`                 | string   | Chave Pix de destino para o pagamento inicial                            | 77         |
| `qr_code_type`            | enum     | Tipo de QR Code para cobrança inicial.                                   | [Enumeradores qr_code_type](#enumeradores-qr_code_type) |
| `additional_data`         | array    | Lista de informações adicionais relacionadas à cobrança                   | [Array de objects additional_data](#array-additional_data) |
| `fine_amount`             | number   | Valor da multa, caso ocorra atraso no pagamento                          | -          |
| `interest_amount`         | number   | Valor dos juros, caso ocorra atraso no pagamento                         | -          |
| `expiration_date`         | string   | Data de expiração da cobrança inicial (formato ISO 8601)                 | 10         |
| `max_payment_days`        | integer  | Número máximo de dias de aceite após expiração                           | -          |
| `rebate_amount`           | number   | Valor do desconto para pagamento antecipado                              | -          |
| `discounts`               | array    | Lista de descontos adicionais                                            | -          |
| `receiver_conciliation_id`| string   | Identificador de conciliação do pagamento pelo recebedor                 | 35        |
| `transaction_data`        | object   | Detalhes da transação relacionada à cobrança inicial                     | [Objeto transaction_data](#objeto-transaction_data) |

---

### Array additional_data

| Campo        | Tipo    | Descrição                                                 | Caracteres |
|--------------|---------|-----------------------------------------------------------|------------|
| `key_name`   | string  | Nome da informação adicional (ex: "Juros e Multa")        | 140        |
| `value`      | string  | Valor ou descrição da informação adicional                | 140        |

---

### Objeto transaction_data

| Campo               | Tipo   | Descrição                              | Caracteres |
|---------------------|--------|----------------------------------------|------------|
| `transaction_key`   | string | Chave única da transação               | 36         |
| `pix_transfer_key`  | string | Identificador da transferência Pix     | 36         |
| `end_to_end_id`     | string | Identificador end-to-end do Pix        | 32         |

---

### Objeto pagination

| Campo            | Tipo    | Descrição                           | Caracteres |
|------------------|---------|-------------------------------------|------------|
| `page`           | integer | Número da página retornada.         | -          |
| `page_size`      | integer | Quantidade de itens por página.     | -          |
| `number_of_pages`| integer | Total de páginas disponíveis.       | -          |

---

### Enumeradores periodicity

| Enumerador   | Descrição              |
|--------------|-----------------------|
| `weekly`     | Recorrência semanal   |
| `monthly`    | Recorrência mensal    |
| `quarterly`  | Recorrência trimestral|
| `semiannual` | Recorrência semestral |
| `annual`     | Recorrência anual     |

---

### Enumeradores journey_type

| Enumerador      | Descrição                                    |
|-----------------|----------------------------------------------|
| `journey_one`   | Notificação direta no aplicativo bancário     |
| `journey_two`   | Experiência QR Code para cobrança recorrente  |
| `journey_three` | Pagamento instantâneo + recorrência QR Code   |
| `journey_four`  | Opt-in recorrente a partir de operação Pix    |

---

### Enumeradores settlement_date_type

| Enumerador      | Descrição         |
|-----------------|------------------|
| `workdays`      | Dias úteis        |
| `calendar_days` | Dias corridos     |

---

### Enumeradores qr_code_type

| Enumerador                 | Descrição                                             |
|----------------------------|-------------------------------------------------------|
| `dynamic_instant_composed` | QR Code dinâmico para pagamento instantâneo           |
| `dynamic_term_composed`    | QR Code dinâmico para pagamento com vencimento futuro |

STATUS 4XX

Response Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em português",
  "code": "codigo"
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                | Descrição (eng)<br/>`description`                                          | Descrição (ptbr)<br/>`translation`                                 |
|-------------|----------------------|-----------------------------------|----------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400         | QIT000002            | Bad Request                       | Invalid request schema.                                                    | Erro no esquema da requisição.                                     |
| 404         | APX000002            | Recurrence Not Found              | Recurrence \{recurrence_key\} not found.                                   | Recorrência \{recurrence_key\} não encontrada.                      |

---

# Simulação de cenários

URL: /documentation/baas/pix_automatico/recebedor/simulacao

Guia completo para simular o fluxo recebedor da automatic-pix-api no ambiente sandbox. Este guia inclui tanto os endpoints de mock quanto os endpoints reais necessários para o fluxo completo de testes.

:::caution Pré-requisitos Importantes
Antes de executar qualquer simulação de mock, você **deve** criar uma recorrência utilizando uma das jornadas de autorização disponíveis. Os mocks simulam apenas as respostas da SPI, mas a recorrência precisa existir no sistema.

**Consulte as jornadas de criação:**
- [Jornada 1 - Push Notification](./journey_one.md)
- [Jornada 2 - QR Code (apenas recorrência)](./journey_two.md)
- [Jornada 3 - QR Code (com primeiro pagamento)](./journey_three.md)
- [Jornada 4 - QR Code (com primeiro pagamento e valores variáveis)](./journey_four.md)
:::

{`
.pix-flow-container {
  width: 100%;
  max-width: 800px;
  margin: 40px auto;
  background-color: #f8fafc;
  border-radius: 16px;
  box-shadow: 0 10px 30px rgba(0, 0, 0, 0.1);
  padding: 30px;
  position: relative;
  border: 1px solid #e5e7eb;
}

.pix-flow-header {
  text-align: center;
  margin-bottom: 30px;
  border-bottom: 2px solid #e5e7eb;
  padding-bottom: 20px;
  position: relative;
}

.pix-flow-header h3 {
  font-size: 24px;
  font-weight: 700;
  color: #1e40af;
  text-transform: uppercase;
  letter-spacing: 1px;
  margin-bottom: 8px;
}

.pix-flow-header p {
  font-size: 14px;
  color: #64748b;
}

.status-indicator {
  position: absolute;
  top: 10px;
  right: 10px;
  display: flex;
  align-items: center;
  gap: 6px;
  font-size: 12px;
  color: #64748b;
}

.status-light {
  width: 10px;
  height: 10px;
  border-radius: 50%;
  background-color: #10b981;
  animation: pulse-status 2s infinite;
}

@keyframes pulse-status {
  0%, 100% { opacity: 1; box-shadow: 0 0 0 0 rgba(16, 185, 129, 0.7); }
  50% { opacity: 0.8; box-shadow: 0 0 0 8px rgba(16, 185, 129, 0); }
}

.pix-flowchart {
  display: flex;
  flex-direction: column;
  gap: 20px;
  max-height: 800px;
  overflow-y: auto;
  padding-right: 10px;
}

.pix-flowchart::-webkit-scrollbar {
  width: 8px;
}

.pix-flowchart::-webkit-scrollbar-track {
  background: #f1f5f9;
  border-radius: 10px;
}

.pix-flowchart::-webkit-scrollbar-thumb {
  background-color: #cbd5e1;
  border-radius: 10px;
}

.pix-flowchart::-webkit-scrollbar-thumb:hover {
  background-color: #94a3b8;
}

.pix-step {
  background-color: #ffffff;
  border-radius: 12px;
  padding: 18px;
  position: relative;
  border-left: 5px solid;
  transition: all 0.3s ease;
  cursor: pointer;
  opacity: 0;
  transform: translateX(-20px);
  animation: fadeInStep 0.5s forwards;
  display: flex;
  flex-direction: column;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08);
  text-decoration: none;
  color: inherit;
}

.pix-step:hover {
  transform: translateY(-5px);
  box-shadow: 0 10px 25px rgba(0, 0, 0, 0.15);
  border-left-width: 6px;
}

.pix-step:visited {
  color: inherit;
}

.pix-step.step-create { border-left-color: #3b82f6; }
.pix-step.step-approve { border-left-color: #1e293b; }
.pix-step.step-process { border-left-color: #1e40af; }
.pix-step.step-conciliate { border-left-color: #0f172a; }
.pix-step.step-update { border-left-color: #ec4899; }
.pix-step.step-attempts { border-left-color: #3b82f6; }

.pix-step-header {
  display: flex;
  justify-content: space-between;
  align-items: center;
  margin-bottom: 12px;
}

.pix-step-number {
  width: 32px;
  height: 32px;
  border-radius: 50%;
  background-color: #f1f5f9;
  display: flex;
  justify-content: center;
  align-items: center;
  font-size: 14px;
  font-weight: 700;
  flex-shrink: 0;
  transition: all 0.3s ease;
}

.pix-step:hover .pix-step-number {
  transform: scale(1.15);
  box-shadow: 0 6px 15px rgba(0, 0, 0, 0.2);
}

.pix-step.step-create .pix-step-number { background-color: #3b82f6; color: #ffffff; }
.pix-step.step-approve .pix-step-number { background-color: #1e293b; color: #ffffff; }
.pix-step.step-process .pix-step-number { background-color: #1e40af; color: #ffffff; }
.pix-step.step-conciliate .pix-step-number { background-color: #0f172a; color: #ffffff; }
.pix-step.step-update .pix-step-number { background-color: #ec4899; color: #ffffff; }
.pix-step.step-attempts .pix-step-number { background-color: #3b82f6; color: #ffffff; }

.pix-step-title {
  font-size: 16px;
  font-weight: 700;
  color: #0f172a;
  flex-grow: 1;
  margin-left: 12px;
}

.pix-step-type {
  font-size: 11px;
  background-color: #f1f5f9;
  padding: 4px 10px;
  border-radius: 6px;
  font-weight: 600;
  text-transform: uppercase;
  letter-spacing: 0.5px;
}

.pix-step-type.mock { background-color: #dbeafe; color: #1e40af; }
.pix-step-type.real { background-color: #dcfce7; color: #16a34a; }
.pix-step-type.optional { background-color: #fef3c7; color: #d97706; }

.pix-step-content {
  display: flex;
  flex-direction: column;
  gap: 12px;
  max-height: 0;
  overflow: hidden;
  transition: max-height 0.4s ease;
  margin-top: 8px;
}

.pix-step.active .pix-step-content {
  max-height: 500px;
}

.pix-step-description {
  font-size: 14px;
  line-height: 1.6;
  color: #475569;
}

.pix-step-info {
  background-color: #eff6ff;
  border-left: 3px solid #3b82f6;
  padding: 10px 14px;
  font-size: 13px;
  color: #1e40af;
  border-radius: 6px;
}

.pix-step-warning {
  background-color: #fef3c7;
  border-left: 3px solid #f59e0b;
  padding: 10px 14px;
  font-size: 13px;
  color: #92400e;
  border-radius: 6px;
}

.pix-connector {
  height: 24px;
  width: 3px;
  background: linear-gradient(to bottom, #cbd5e1, #94a3b8);
  margin: -12px auto;
  position: relative;
  z-index: 1;
  border-radius: 2px;
}

.pix-connector::before {
  content: '';
  position: absolute;
  bottom: 0;
  left: 50%;
  transform: translateX(-50%);
  width: 0;
  height: 0;
  border-left: 6px solid transparent;
  border-right: 6px solid transparent;
  border-top: 8px solid #94a3b8;
}

.pix-branch-container {
  margin-top: 30px;
  padding-top: 0px;
}

.pix-branch-title {
  text-align: center;
  font-size: 18px;
  font-weight: 700;
  color: #0f172a;
  margin-bottom: 24px;
}
.pix-branch-container {
  position: relative;
}

.pix-branch-connectors {
  position: absolute;
  top: -25px;
  left: 0;
  right: 0;
  height: 40px;
  display: flex;
  justify-content: space-between;
  align-items: flex-start;
  pointer-events: none;
  z-index: 0;
}

.pix-branch-arrow {
  width: 3px;
  height: 105px;
  position: relative;
  opacity: 0.9;
}

.pix-branch-arrow::after {
  content: '';
  position: absolute;
  bottom: 0;
  left: 50%;
  transform: translateX(-50%);
  width: 0;
  height: 0;
  border-left: 6px solid transparent;
  border-right: 6px solid transparent;
  border-top: 10px solid;
}

.pix-branch-options {
  display: grid;
  grid-template-columns: 1fr 1fr;
  gap: 20px;
}

.pix-branch-option {
  background-color: #ffffff;
  border-radius: 12px;
  padding: 20px;
  text-align: center;
  transition: all 0.3s ease;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.08);
  cursor: pointer;
  text-decoration: none;
  color: inherit;
}

.pix-branch-option:hover {
  transform: translateY(-3px);
  box-shadow: 0 8px 20px rgba(0, 0, 0, 0.12);
}

.branch-title-payment {
  font-weight: 800;
  font-size: 16px;
  margin-bottom: 14px;
  color: #1e40af;
}

.branch-title-rejection {
  font-weight: 800;
  font-size: 16px;
  margin-bottom: 14px;
  color: #ec4899;
}

.pix-branch-button {
  padding: 14px 20px 5px 20px; 
  border-radius: 10px;
  font-weight: 700;
  font-size: 14px;
  color: #ffffff;
  border: none;
  cursor: pointer;
  width: 100%;
  margin-top: 8px;
  transition: all 0.3s ease;
  text-decoration: none;
  display: inline-block;
  align-items: center;
  justify-content: center;
}

.pix-branch-button:hover {
  transform: scale(1.02);
}

.branch-button-payment {
  background: linear-gradient(135deg, #1e3a8a 0%, #3b82f6 50%, #60a5fa 100%);
  box-shadow: 0 4px 12px rgba(30, 64, 175, 0.3);
}

.branch-button-rejection {
  background: linear-gradient(135deg, #9f1239 0%, #ec4899 50%, #f472b6 100%);
  box-shadow: 0 4px 12px rgba(236, 72, 153, 0.3);
}

@keyframes fadeInStep {
  to {
    opacity: 1;
    transform: translateX(0);
  }
}

@media (max-width: 768px) {
  .pix-flow-container {
    padding: 20px;
  }

  .pix-flow-header h3 {
    font-size: 20px;
  }

  .pix-step {
    padding: 14px;
  }

  .pix-step-title {
    font-size: 14px;
  }

  .pix-step-number {
    width: 28px;
    height: 28px;
    font-size: 12px;
  }

  .pix-branch-options {
    grid-template-columns: 1fr;
  }

  .status-indicator {
    top: 5px;
    right: 5px;
    font-size: 10px;
  }
}
`}

Fluxo Completo de Simulação
Teste de ponta a ponta do Pix Automático - Sandbox Environment
SANDBOX

1
Criar Recorrência
REAL
Passo obrigatório antes de qualquer simulação. Escolha uma das quatro jornadas disponíveis (Jornada 1: Push Notification, Jornadas 2-4: QR Code com diferentes configurações). Após criar, guarde o outgoing_recurrence_spi_id retornado.
Jornadas disponíveis: Jornada 1 (Push), Jornada 2 (QR Code - recorrência), Jornada 3 (QR Code + primeiro pagamento), Jornada 4 (QR Code + pagamento + valores variáveis)

2
Aprovar Recorrência
MOCK
Simula as atualizações de status de recorrência que a SPI enviará para a automatic-pix-api. Utilize o endpoint /mock/outgoing_recurrence/OUTGOING_RECURRENCE_SPI_ID para atualizar o status para pending_confirmation e depois para approved .
Atenção: Nas jornadas 2, 3 e 4, é necessário enviar também os dados da conta ( account_data ) na aprovação. Nas jornadas 3 e 4, inclua também informações do primeiro pagamento.

3
Processar Ordens de Pagamento
MOCK
Simula o processamento das ordens de pagamento através do endpoint /mock/process_payment_orders . Este passo cria automaticamente os lotes de conciliação e envia o webhook de criação de lote para sua URL configurada.
O que acontece: Ordens são criadas automaticamente, lotes de conciliação são criados ou atualizados com base na reference_date e tipo de recorrência, e o webhook de criação é disparado.

4
Consultar e Conciliar Ordens
REAL
Passo real (não é mock): Consultar o lote de conciliação criado e obter o receiver_conciliation_id e payment_order_key . Para recorrências do tipo variable_amount , você deve atualizar a ordem de pagamento com o valor específico.
Importante: Este passo é obrigatório para recorrências variable_amount . Sem a atualização do valor, a ordem não será processada. Para fixed_amount , este passo não é necessário.

5
Atualizar Data de Execução
MOCK
Atualiza o next_retry_execution_datetime de uma ordem de pagamento para a data atual, permitindo que o processamento das tentativas ocorra imediatamente. Utilize o endpoint /mock/payment_order/PAYMENT_ORDER_KEY/update_next_retry_execution_datetime .
Disponível apenas no sandbox. Este passo é necessário para avançar o fluxo e permitir o processamento imediato das tentativas de pagamento.

6
Processar Tentativas de Pagamento
MOCK
Simula o processamento das tentativas de pagamento através do endpoint /mock/process_payment_order_attempts . Cria as tentativas necessárias para o fluxo de PIX automático, preparando o sistema para receber a simulação de PIX de entrada ou rejeição.
Disponível apenas no sandbox. Após este passo, você pode simular o recebimento do PIX (Passo 7) ou a rejeição (Passo 8).

Simulações de Resultado
  
Pagamento
        7. Simular Pix de Entrada
        Simula o recebimento bem-sucedido do pagamento via PIX
    
Rejeições
        7. Simular Rejeição
        Simula a rejeição de uma tentativa de pagamento

{`
if (typeof document !== 'undefined') {
  document.addEventListener('DOMContentLoaded', function() {
    const steps = document.querySelectorAll('.pix-step');
    
    steps.forEach((step, index) => {
      step.style.animationDelay = \`\${index * 0.15}s\`;
      
      step.addEventListener('click', function(e) {
        e.preventDefault();
        const targetId = this.getAttribute('href');
        
        // Toggle active state
        const wasActive = this.classList.contains('active');
        
        // Close all steps
        steps.forEach(s => s.classList.remove('active'));
        
        // If wasn't active, open it
        if (!wasActive) {
          this.classList.add('active');
          
          // Scroll to section
          if (targetId) {
            const targetElement = document.querySelector(targetId);
            if (targetElement) {
              setTimeout(() => {
                targetElement.scrollIntoView({ behavior: 'smooth', block: 'start' });
              }, 300);
            }
          }
        } else {
          // If was active and clicked again, navigate to section
          if (targetId) {
            const targetElement = document.querySelector(targetId);
            if (targetElement) {
              targetElement.scrollIntoView({ behavior: 'smooth', block: 'start' });
            }
          }
        }
      });
    });
    
    // Auto-open first step after animation
    setTimeout(() => {
      if (steps.length > 0) {
        steps[0].classList.add('active');
      }
    }, steps.length * 150 + 200);
  });
}
`}

---
## Pré-requisito: Criar Recorrência

:::danger Obrigatório
**Este passo é obrigatório** antes de qualquer simulação de mock. Escolha uma das jornadas de criação de recorrência conforme sua necessidade.
:::

### Escolha sua Jornada

| Jornada | Descrição | Link |
|---------|-----------|------|
| **Jornada 1** | Push Notification - Autorização via notificação | [Criar Recorrência: Jornada 1](./journey_one.md) |
| **Jornada 2** | QR Code - Apenas autorização da recorrência | [Criar Recorrência: Jornada 2](./journey_two.md) |
| **Jornada 3** | QR Code - Recorrência + primeiro pagamento | [Criar Recorrência: Jornada 3](./journey_three.md) |
| **Jornada 4** | QR Code - Recorrência + primeiro pagamento + valores variáveis | [Criar Recorrência: Jornada 4](./journey_four.md) |

:::info Informação Importante
Após criar a recorrência, guarde o `outgoing_recurrence_spi_id` retornado. Ele será necessário para as simulações de mock.
:::

---

## Passo 1: Simulação de Atualização de Recorrência (Simulação)

:::caution Pré-requisito
**Antes deste passo**, você deve ter:
1. Criado uma recorrência usando uma das [jornadas de criação](#passo-0-criar-recorrência-pré-requisito)
2. Obtido o `outgoing_recurrence_spi_id` da recorrência criada
:::

Este endpoint simula as atualizações de status de recorrência que a SPI enviará para a automatic-pix-api durante diferentes jornadas do fluxo recebedor.

### Request

ENDPOINT /mock/outgoing_recurrence/ OUTGOING_RECURRENCE_SPI_ID
MÉTODO PATCH

Request Body: Jornada 1 - Recebimento da solicitação pelo PSP Pagador

```json
{
  "outgoing_recurrence_status": "pending_confirmation"
}
```

Request Body: Jornada 1 - Recebimento da confirmação da solicitação pelo PSP Pagador

```json
{
  "outgoing_recurrence_status": "approved"
}
```

Request Body: Jornadas 2, 3 e 4 - Recebimento da solicitação pelo PSP Pagador

```json
{
  "outgoing_recurrence_status": "pending_confirmation"
}
```

Request Body: Jornada 2 - Recebimento da confirmação da solicitação pelo PSP Pagador

```json
{
  "outgoing_recurrence_status": "approved",
  "account_data": {
    "account_number": "123456",
    "account_digit": "7",
    "account_branch": "0001",
    "ispb": "31872495"
  }
}
```

Request Body: Jornadas 3 e 4 - Recebimento da confirmação da solicitação pelo PSP Pagador

```json
{
  "outgoing_recurrence_status": "approved",
  "account_data": {
    "account_number": "123456",
    "account_digit": "7",
    "account_branch": "0001",
    "ispb": "31872495"
  },
  "receiver_conciliation_id": "064b6563329047c59db6902725b8d31e",
  "target_account_key": "23a4a1c8-9d82-4ebe-a90d-44fe8d839ec0",
  "transaction_amount": 250
}
```

### Path Parameters

| Campo                          | Tipo   | Descrição                                      | Máx. Caract. |
|--------------------------------|--------|------------------------------------------------|--------------|
| **outgoing_recurrence_spi_id*** | string | Identificador SPI da recorrência de saída      | 50           |

### Objeto Request Body

| Campo                         | Tipo   | Descrição                                       | Máx. Caract. |
|-------------------------------|--------|-------------------------------------------------|--------------|
| **outgoing_recurrence_status*** | string | Status da recorrência de saída                  | 50           |
| **account_data**              | object | Dados da conta (apenas jornadas 2, 3 e 4)      | -            |

### Objeto account_data

| Campo               | Tipo   | Descrição                                | Máx. Caract. |
|---------------------|--------|------------------------------------------|--------------|
| **account_number*** | string | Número da conta                          | 20           |
| **account_digit***  | string | Dígito da conta                          | 1            |
| **account_branch*** | string | Agência da conta                         | 6            |
| **ispb***           | string | Código ISPB da instituição financeira   | 8            |

### Enumerador outgoing_recurrence_status

| Enumerador              | Descrição                           |
|-------------------------|-------------------------------------|
| **pending_confirmation** | Pendente de confirmação             |
| **approved**            | Aprovado                            |

:::info Fluxos de Jornada
- **Jornada 1**: Apenas atualização de status, sem dados da conta
- **Jornada 2**: Primeiro apenas status, depois status + dados da conta (apenas aprovação da recorrência)
- **Jornadas 3 e 4**: Primeiro apenas status, depois status + dados da conta + dados do primeiro pagamento
:::

:::tip Próximo Passo
Após aprovar a recorrência, prossiga para o [Passo 3: Processar Ordens de Pagamento](#passo-3-processar-ordens-de-pagamento-mock)
:::

---

## Passo 2: Simulação de Cancelamento de Recorrência (Simulação - Opcional)

:::caution Pré-requisito
**Antes deste passo**, você deve ter:
1. Criado uma recorrência
2. Aprovado a recorrência ([Passo 1](#passo-1-simulação-de-atualização-de-recorrência-mock))
:::

Este endpoint simula o cancelamento de uma recorrência de saída acionado pela SPI.

### Request

ENDPOINT /mock/outgoing_recurrence/ OUTGOING_RECURRENCE_SPI_ID /cancel
MÉTODO PATCH

:::info Sem Payload
Este endpoint não possui request body (payload). Apenas o path parameter é necessário.
:::

### Path Parameters

| Campo                          | Tipo   | Descrição                                      | Máx. Caract. |
|--------------------------------|--------|------------------------------------------------|--------------|
| **outgoing_recurrence_spi_id*** | string | Identificador SPI da recorrência de saída      | 50           |

---

## Passo 3: Processar Ordens de Pagamento (Simulação)

:::caution Pré-requisitos
**Antes deste passo**, você deve ter:
1. Criado uma recorrência
2. Aprovado a recorrência ([Passo 1](#passo-1-simulação-de-atualização-de-recorrência-mock))
:::

Este endpoint simula o processamento das ordens de pagamento que, consequentemente, irá criar os lotes de conciliação e enviar o Webhook de criação desses lotes.

### Request

ENDPOINT /mock/process_payment_orders
MÉTODO PATCH

:::info Sem Payload
Este endpoint não possui request body (payload). A simulação é executada automaticamente.
:::

:::info O que acontece neste passo?
1. **Ordens de pagamento são criadas** automaticamente pelo sistema
2. **Lote de conciliação é criado ou atualizado** (`payment_order_conciliation_batch`)
   - Se já existir um lote aberto para a `reference_date` e para o tipo de recorrência ('fixed_amount' ou 'variable_amount'), a ordem é incluída nele
   - Caso contrário, um novo lote é criado
3. **Webhook de criação de lote é enviado** para sua URL configurada
:::

:::tip Próximo Passo
Após processar as ordens, você precisa **consultar e conciliar** as ordens de pagamento antes de continuar. Veja o [Passo 4](#passo-4-consultar-e-conciliar-ordens-de-pagamento).
:::

---

## Passo 4: Consultar e Conciliar Ordens de Pagamento

:::danger Passo Obrigatório (NÃO é Mock)
**Este é um passo real**, não é uma simulação! Você precisa consultar o lote de conciliação criado no passo anterior e obter o `receiver_conciliation_id` e a `payment_order_key` que serão usados posteriormente.
:::

:::caution Pré-requisitos
**Antes deste passo**, você deve ter:
1. Processado as ordens de pagamento ([Passo 3](#passo-3-processar-ordens-de-pagamento-mock))
2. Recebido o webhook de criação do lote de conciliação
:::

### 4.1 - Consultar Lote de Pagamentos

Para consultar os lotes criados, utilize o endpoint de consulta de lotes:

**Consulte a documentação completa:**
- [Consultar lote de pagamentos por conta](../conciliacao/consultar_lote_por_conta.md)
- [Consultar lote de pagamentos por requester](../conciliacao/consultar_lote_requester.md)

:::info Informações Importantes
Na resposta do GET, você encontrará:
- `payment_order_conciliation_batch_key`: Chave do lote
- `payment_orders`: Lista de ordens de pagamento dentro do lote
- `receiver_conciliation_id`: **Guarde este valor!** Será usado no Passo 7 para simular o PIX de entrada
- `payment_order_spi_id`: Identificador SPI da ordem de pagamento
- `payment_order_key`: Chave única da ordem de pagamento
:::

### 4.2 - Atualizar Ordem de Pagamento (Obrigatório para Valor Variável)

:::warning Importante
**Este passo é obrigatório** para recorrências do tipo `variable_amount`. Para recorrências de valor fixo (`fixed_amount`), este passo não é necessário.
:::

Para recorrências de valor variável, você **deve** atualizar a ordem de pagamento informando o valor específico que será cobrado neste ciclo:

**Consulte a documentação completa:**
- [Atualizar ordem de pagamento](../pagamentos/atualizar_payment_order.md)

ENDPOINT
/account/ ACCOUNT_KEY /outgoing_recurrence/ OUTGOING_RECURRENCE_KEY /payment_order/ PAYMENT_ORDER_KEY
MÉTODO
      PATCH

Request Body - Exemplo para Valor Variável

```json
{
  "transaction_amount": 150.75,
}
```

### Quando é Obrigatório?

| Tipo de Recorrência | Atualização Obrigatória? | Motivo |
|---------------------|---------------------------|---------|
| **`fixed_amount`** |  Não | Valor já definido na criação da recorrência |
| **`variable_amount`** |  **Sim** | Valor deve ser informado a cada execução |

:::info Informação
- **Recorrências fixas**: O valor já está definido na criação, não precisa ser atualizado
- **Recorrências variáveis**: O valor deve ser informado antes de cada processamento de pagamento
- **Sem atualização**: Recorrências variáveis sem atualização não serão processadas
:::

:::tip Próximo Passo
Após consultar o lote e atualizar a ordem de pagamento (se necessário), prossiga para o [Passo 5](#passo-5-atualizar-data-de-execução-mock---sandbox).
:::

---

## Passo 5: Atualizar Data de Execução (Simulação)

:::caution Pré-requisitos
**Antes deste passo**, você deve ter:
1. Processado as ordens de pagamento ([Passo 3](#passo-3-processar-ordens-de-pagamento-mock))
2. Consultado o lote de conciliação ([Passo 4](#passo-4-consultar-e-conciliar-ordens-de-pagamento))
3. Obtido o `payment_order_key` da ordem de pagamento
:::

Este endpoint permite atualizar o `next_retry_execution_datetime` de uma Ordem de Pagamento específica para a data atual, possibilitando que o processamento das Order Attempts ocorra imediatamente.

:::info Sandbox Apenas
Este endpoint está disponível **apenas no ambiente sandbox**.
:::

### Request

ENDPOINT /mock/payment_order/ payment_order_key /update_next_retry_execution_datetime
MÉTODO PATCH

### Path Params

| Campo                | Tipo   | Descrição                                      | Máx. Caract. |
|----------------------|--------|------------------------------------------------|--------------|
| **payment_order_key*** | uuid4  | Chave única de identificação da ordem de pagamento | 36           |

Request Body

```json
{
  "next_retry_execution_datetime": "2025-08-22"
}
```

### Request Body Params

| Campo                            | Tipo   | Descrição                                      | Máx. Caract. |
|----------------------------------|--------|------------------------------------------------|--------------|
| **next_retry_execution_datetime*** | string | Nova data de execução da order (formato YYYY-MM-DD) | 10           |

:::info Finalidade
Este endpoint atualiza a data de próxima execução da tentativa para a data atual, permitindo que o sistema processe imediatamente as tentativas de pagamento, que são necessárias para simular o recebimento de PIX de entrada.
:::

:::tip Próximo Passo
Após atualizar a data de execução, prossiga para o [Passo 6](#passo-6-processar-tentativas-de-pagamento-mock---sandbox).
:::

---

## Passo 6: Processar Tentativas de Pagamento (Simulação)

:::caution Pré-requisitos
**Antes deste passo**, você deve ter:
1. Atualizado a data de execução ([Passo 5](#passo-5-atualizar-data-de-execução-mock---sandbox))
:::

Este endpoint simula o processamento das tentativas de pagamento, criando as tentativas necessárias para o fluxo de PIX automático.

:::info Sandbox Apenas
Este endpoint está disponível **apenas no ambiente sandbox**.
:::

### Request

ENDPOINT /mock/process_payment_order_attempts
MÉTODO PATCH

:::info Sem Payload
Este endpoint não possui request body (payload). A simulação é executada automaticamente.
:::

:::info Finalidade
Este endpoint processa as tentativas de pagamento baseadas nas ordens de pagamento com datas de execução atualizadas, criando as tentativas necessárias para simular o recebimento de PIX de entrada.
:::

:::tip Próximo Passo - Escolha seu Caminho

**Fluxo de Sucesso**: Prossiga para o [Passo 7: Simular PIX de Entrada](#passo-7-simular-pix-de-entrada-mock)

**Fluxo de Rejeição**: Prossiga para o [Passo 8: Simular Tentativa Rejeitada](#passo-8-simular-tentativa-de-pagamento-rejeitada-mock)
:::

---

## Passo 7: Simular Pix de Entrada

:::caution Pré-requisitos
**Antes deste passo**, você deve ter:
1. Atualizado a data de execução ([Passo 5](#passo-5-atualizar-data-de-execução-mock---sandbox))
2. Processado as tentativas de pagamento ([Passo 6](#passo-6-processar-tentativas-de-pagamento-mock---sandbox))
3. Obtido o `receiver_conciliation_id` do lote ([Passo 4](#passo-4-consultar-e-conciliar-ordens-de-pagamento))
4. Obtido o `outgoing_recurrence_spi_id` e `payment_order_spi_id`
:::

Este endpoint simula o recebimento de um Pix que será associado a uma Ordem de Pagamento de uma recorrência.

### Request

ENDPOINT /mock/automatic_pix/incoming_pix
MÉTODO POST

Request Body

```json
{
  "target_account_key": "23a4a2c8-9d82-4ebe-a90d-44fe8d839ec0",
  "amount": 1000.00,
  "receiver_conciliation_id": "7535f0467d9a4af69c4d99408c2fec9d"
}
```

### Objeto Request Body

| Campo                         | Tipo   | Descrição                                                    | Máx. Caract. |
|-------------------------------|--------|--------------------------------------------------------------|--------------|
| **target_account_key***       | string | Chave única da conta de destino                              | 36           |
| **amount***                   | number | Valor da transação PIX                                       | -            |
| **receiver_conciliation_id*** | string | Identificação de conciliação do recebedor (obtido no Passo 4) | 35           |

:::info Informação
Este endpoint simula o fluxo completo de Incoming Pix, incluindo:
1. Processamento da transferência Pix
2. Associação à ordem de pagamento da automatic-pix usando o `receiver_conciliation_id`
:::

:::success Fluxo Concluído!
Parabéns! Você completou o fluxo de pagamento bem-sucedido. O sistema processou:
- Criação da recorrência
- Aprovação da recorrência
- Criação de ordens de pagamento e lotes
- Processamento de tentativas
- Recebimento do PIX
:::

---

## Passo 8: Simular Tentativa de Pagamento Rejeitada (Simulação)

:::caution Pré-requisitos
**Antes deste passo**, você deve ter:
1. Processado as ordens de pagamento ([Passo 3](#passo-3-processar-ordens-de-pagamento-mock))
2. Atualizado a data de execução ([Passo 5](#passo-5-atualizar-data-de-execução-mock---sandbox))
3. Processado as tentativas de pagamento ([Passo 6](#passo-6-processar-tentativas-de-pagamento-mock---sandbox))
4. Obtido o `outgoing_recurrence_spi_id` e `payment_order_spi_id`
:::

Este endpoint simula a rejeição de uma tentativa de pagamento PIX dentro de uma recorrência de saída, replicando o comportamento quando a SPI rejeita uma transação. O sistema criará automaticamente as tentativas de pagamento e simulará o PIX rejeitado, resultando no envio do webhook de mudança de status da tentativa.

### Request

ENDPOINT /mock/automatic_pix/outgoing_recurrence/ OUTGOING_RECURRENCE_SPI_ID /payment_order/ PAYMENT_ORDER_SPI_ID
MÉTODO PATCH

Request Body: Tentativa rejeitada

```json
{
  "payment_order_status": "rejected",
  "rejection_information": {
    "bacen_reason_code": "AC06"
  }
}
```

### Path Parameters

| Campo                          | Tipo   | Descrição                                      | Máx. Caract. |
|--------------------------------|--------|------------------------------------------------|--------------|
| **outgoing_recurrence_spi_id*** | string | Identificador SPI da recorrência de saída      | 50           |
| **payment_order_spi_id***      | string | Identificador SPI da ordem de pagamento        | 50           |

### Objeto Request Body

| Campo                         | Tipo   | Descrição                                       | Máx. Caract. |
|-------------------------------|--------|-------------------------------------------------|--------------|
| **payment_order_status***     | string | Status da ordem de pagamento (sempre "rejected") | 50           |
| **rejection_information***    | object | Informações sobre a rejeição                   | -            |

### Objeto rejection_information

| Campo                 | Tipo   | Descrição                                | Máx. Caract. |
|-----------------------|--------|------------------------------------------|--------------|
| **bacen_reason_code*** | string | Código de erro do Bacen para rejeição   | 4            |

### Códigos de Erro Bacen Comuns

| Código | Descrição (Inglês) | Descrição (Português) |
|--------|-------------------|----------------------|
| **AB10** | ErrorInstructedAgent | Erro interno no PSP pagador |
| **AC05** | ClosedDebtorAccountNumber | Conta do pagador encerrada |
| **AC06** | BlockedAccount | Conta do pagador bloqueada |
| **AG12** | NotAllowedBookTransfer | Transferência não permitida entre contas da mesma instituição |
| **AM02** | NotAllowedAmount | Valor excede limite máximo do pagador |
| **AM09** | WrongAmount | Valor não corresponde ao estabelecido na recorrência |
| **DENC** | DebtorIdentifierNotCorrespond | CPF/CNPJ do pagador não confere com a recorrência |
| **DS27** | UserNotYetActivated | Participante não cadastrado no SPI |
| **DTED** | InvalidExpiryDate | Data de vencimento inválida para a periodicidade |
| **DTNT** | - | Tentativas pós vencimento fora do prazo permitido |
| **FBRD** | FailureToComplyBusinessRuleDeadline | Solicitação fora do prazo para regras de negócio |
| **IRNT** | - | Recorrência não permite novas tentativas pós vencimento |
| **MIDI** | MandateIdIncorrect | ID da recorrência inexistente ou incorreto |
| **MSUC** | UnconfirmedMandateStatus | Status da recorrência não confirmado pelo pagador |
| **NIEC** | - | Ordem de pagamento anterior ainda pendente |
| **NIPA** | - | Pagamento já foi efetivado |
| **NITX** | - | Instrução não corresponde à cobrança recorrente anterior |
| **QUNT** | - | Limite de tentativas pós vencimento excedido |
| **RC09** | InvalidDebtorClearingSystemMemberIdentifier | ISPB do pagador inválido ou inexistente |
| **UDEI** | UltimateDebtorIdentifierIncorrect | CPF/CNPJ do devedor incorreto |

:::info Funcionamento do Sistema
1. **Simulação de rejeição**: O sistema simula o PIX rejeitado com o código de erro especificado
2. **Webhook enviado**: Para cada tentativa rejeitada, é enviado o webhook `baas.automatic_pix.payment_order_attempt.status_change`
3. **Múltiplas tentativas**: O sistema permite até 4 tentativas de pagamento. Na 4ª tentativa rejeitada, a ordem de pagamento tem seu status alterado para "rejected"
:::

:::info Webhook Resultante
Cada tentativa rejeitada irá gerar um webhook com o seguinte formato:
```json
{
  "event_type": "baas.automatic_pix.payment_order_attempt.status_change",
  "origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "data": {
    "request_control_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "payment_order_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "payment_order_attempt_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "payment_order_status": "pending",
    "payment_order_attempt_status": "rejected",
    "transaction_amount": 125.53,
    "reason": "Conta de destino inexistente",
    "outgoing_recurrence_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82"
  }
}
```
:::

### Fluxo de Múltiplas Tentativas

1. **1ª Tentativa**: Payment order permanece com status "pending", attempt status "rejected"
2. **2ª Tentativa**: Payment order permanece com status "pending", nova attempt criada
3. **3ª Tentativa**: Payment order permanece com status "pending", nova attempt criada  
4. **4ª Tentativa**: Payment order muda para status "rejected" (limite máximo atingido)

---

## Resumo dos Fluxos

### Fluxo Completo de Sucesso

| Passo | Descrição | Fluxo | Documentação |
|-------|-----------|------|--------------|
| 0 | Criar Recorrência | **Real** | [Jornadas de criação](#passo-0-criar-recorrência-pré-requisito) |
| 1 | Aprovar Recorrência | Simulação | [Ver detalhes](#passo-1-simulação-de-atualização-de-recorrência-mock) |
| 3 | Processar Ordens de Pagamento | Simulação | [Ver detalhes](#passo-3-processar-ordens-de-pagamento-mock) |
| 4 | Consultar e Conciliar Ordens | **Real** | [Consultar lotes](../conciliacao/consultar_lote_por_conta.md) |
| 5 | Atualizar Data de Execução | Simulação | [Ver detalhes](#passo-5-atualizar-data-de-execução-mock---sandbox) |
| 6 | Processar Tentativas | Simulação | [Ver detalhes](#passo-6-processar-tentativas-de-pagamento-mock---sandbox) |
| 7 | Simular PIX de Entrada | Simulação | [Ver detalhes](#passo-7-simular-pix-de-entrada-mock) |

### Fluxo Completo de Rejeição

| Passo | Descrição | Fluxo | Documentação |
|-------|-----------|------|--------------|
| 0 | Criar Recorrência | **Real** | [Jornadas de criação](#passo-0-criar-recorrência-pré-requisito) |
| 1 | Aprovar Recorrência | Simulação | [Ver detalhes](#passo-1-simulação-de-atualização-de-recorrência-mock) |
| 3 | Processar Ordens de Pagamento | Simulação | [Ver detalhes](#passo-3-processar-ordens-de-pagamento-mock) |
| 4 | Consultar e Conciliar Ordens | **Real** | [Consultar lotes](../conciliacao/consultar_lote_por_conta.md) |
| 5 | Atualizar Data de Execução | Simulação | [Ver detalhes](#passo-5-atualizar-data-de-execução-mock---sandbox) |
| 6 | Processar Tentativas | Simulação | [Ver detalhes](#passo-6-processar-tentativas-de-pagamento-mock---sandbox) |
| 8 | Simular Rejeição | Simulação | [Ver detalhes](#passo-8-simular-tentativa-de-pagamento-rejeitada-mock) |

---

## Links Úteis

### Gerenciamento de Recorrências
- [Consultar uma recorrência](./consultar_recorrencia.md)
- [Consultar uma recorrência pelo QR Code](./consultar_recorrencia_receiver.md)
- [Listar recorrências de uma conta](./listar_recorrencias_de_uma_conta.md)
- [Cancelar recorrência](./cancelar_recorrencia.md)

### Gerenciamento de Pagamentos
- [Listar ordens de pagamento](../pagamentos/listar_account_payment_orders.md)
- [Consultar ordem de pagamento](../pagamentos/consultar_payment_order.md)
- [Atualizar ordem de pagamento](../pagamentos/atualizar_payment_order.md)
- [Cancelar ordem de pagamento](../pagamentos/cancelar_payment_order.md)

### Lotes de Conciliação
- [Consultar lote por conta](../conciliacao/consultar_lote_por_conta.md)
- [Consultar lote por requester](../conciliacao/consultar_lote_requester.md)
- [Listar pagamentos de um lote](../conciliacao/listar_payment_orders.md)
- [Webhooks de conciliação](../conciliacao/webhooks.md)

### Webhooks
- [Webhooks do Usuário Recebedor](./webhooks.md)
- [Webhooks de Lotes de Conciliação](../conciliacao/webhooks.md)

---

# Webhooks Pix Automático

URL: /documentation/baas/pix_automatico/recebedor/webhooks

As notificações via webhook são fundamentais para o correto processamento de eventos assíncronos relacionados ao Pix Automático, incluindo especialmente as autorizações e execuções de pagamentos recorrentes em diferentes jornadas.

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeados de forma restrita.
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

## Webhook de Status de Recorrência

Este webhook é destinado ao reporte de alterações de status de autorizações e ciclos de recorrência do Pix Automático, diferenciando os tipos de jornadas envolvidas.

### Webhook Request Body

### Jornada 1 – journey_one

Request Body: Jornada 1

```json
{
  "event_type": "baas.automatic_pix.outgoing_recurrence.status_change",
  "origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "data": {
    "request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "outgoing_recurrence_status": "approved",
    "journey_type": "journey_one",
    "outgoing_recurrence_data": {
      "minimum_recurrence_amount": 123.45,
      "recurrence_amount": null
    },
    "payment_conciliation_batch_key": "uuid"
  }
}
```

### Jornada 2 – journey_two

Request Body: Jornada 2

```json
{
    "event_type": "baas.automatic_pix.outgoing_recurrence.status_change",
    "origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "data": {
        "request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
        "outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
        "outgoing_recurrence_status": "approved",
        "journey_type": "journey_two",
        "outgoing_recurrence_data": {
            "minimum_recurrence_amount": 123.45,
            "recurrence_amount": null
        },
        "payment_conciliation_batch_key": "uuid" or null
    }
}
```

### Jornada 3 – journey_three

Request Body: Jornada 3

```json
{
    "event_type": "baas.automatic_pix.outgoing_recurrence.status_change",
    "origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "data": {
        "request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
        "outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
        "outgoing_recurrence_status": "approved",
        "journey_type": "journey_three",
        "outgoing_recurrence_data": {
            "minimum_recurrence_amount": 123.45,
            "recurrence_amount": null,
            "qr_code_initial_payment_data": {
                "receiver_conciliation_id": "id",
                "transaction_data": {
                    "transaction_key": "uuid",
                    "pix_transfer_key": "uuid",
                    "end_to_end_id": "end_to_end"
                }
            },
            "payment_conciliation_batch_key": "uuid" or null
        }
    }
}
```

### Jornada 4 – journey_four

Request Body: Jornada 4

```json
{
    "event_type": "baas.automatic_pix.outgoing_recurrence.status_change",
    "origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "data": {
        "request_control_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
        "outgoing_recurrence_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
        "outgoing_recurrence_status": "approved",
        "journey_type": "journey_four",
        "outgoing_recurrence_data": {
            "minimum_recurrence_amount": 123.45,
            "recurrence_amount": null
        },
        "qr_code_initial_payment_data": {
            "receiver_conciliation_id": "id",
            "transaction_data": {
                "transaction_key": "uuid" or null,
                "pix_transfer_key": "uuid" or null,
                "end_to_end_id": "end_to_end" or null
            }
        },
        "payment_conciliation_batch_key": "uuid" or null
    }
}
```

:::caution Atenção
Quando o usuário pagor recebe a notificação, ele pode optar por agendar o Pix ou realizar a transferência naquele momento. Caso o pagador realize instantaneamente o pagamento, será enviado o webhook do tipo `baas.automatic_pix.outgoing_recurrence.status_change` com as informações preenchidas, em caso de agendamento os valores serão `null`.
:::

### Webhook Body Params

| Campo                                | Tipo       | Descrição                                                                                                               | Caracteres |
|-------------------------------------- |------------|-------------------------------------------------------------------------------------------------------------------------|------------|
| `event_type` *                       | string     | Tipo do evento reportado (exemplo: `baas.automatic_pix.outgoing_recurrence.status_change`).                             | 100        |
| `origin_key` *                       | string     | Identificador único de origem do evento (UUID).                                                                         | 36         |
| `data` *                             | Object     | Objeto principal contendo os detalhes da recorrência automática.                                                        | [Objeto data](#objeto-data)                                    |

---

### Objeto data

| Campo                                | Tipo       | Descrição                                                                                           | Caracteres |
|-------------------------------------- |------------|-----------------------------------------------------------------------------------------------------|------------|
| `request_control_key` *               | string     | Chave de controle única da requisição (UUID4).                                                      | 36         |
| `outgoing_recurrence_key` *           | string     | Identificador único da recorrência automática (UUID).                                               | 36         |
| `outgoing_recurrence_status` *        | string     | Status da recorrência em questão (ex: `approved`, `pending`, `rejected`, etc.)                      | 30         |
| `journey_type` *                      | enumerator | Jornada correspondente à autorização do Pix Automático (`journey_one`, `journey_two`, etc.).         | [Enumeradores journey_type](#enumeradores-journey_type) |
| `outgoing_recurrence_data` *           | Object     | Objeto contendo informações específicas da recorrência e da jornada.                                | [Objeto outgoing_recurrence_data](#objeto-outgoing_recurrence_data) |
| `payment_conciliation_batch_key`       | string     | Identificador de agrupamento para conciliação de pagamentos. Pode ser null.                         | 36 ou null |
| `qr_code_initial_payment_data`         | Object     | (Jornada 3 e 4) Detalhamento de dados do pagamento via QR Code inicial, se houver.                  | [Objeto qr_code_initial_payment_data](#objeto-qr_code_initial_payment_data) |

---

### Objeto outgoing_recurrence_data

| Campo                           | Tipo    | Descrição                                                                                      | Caracteres |
|----------------------------------|---------|----------------------------------------------------------------------------------------------- |------------|
| `minimum_recurrence_amount`      | number  | Valor mínimo da recorrência autorizada.                                                        | -          |
| `recurrence_amount`              | number  | Valor total da recorrência (pode ser null se não aplicável).                                   | -          |
| `qr_code_initial_payment_data`   | Object  | (Jornada 3) Dados detalhados do pagamento inicial caso QR Code seja utilizado.                 | [Objeto qr_code_initial_payment_data](#objeto-qr_code_initial_payment_data) |
| `payment_conciliation_batch_key` | string  | Identificador de lote/conciliação do pagamento.                                                | 36         |

---

### Objeto qr_code_initial_payment_data

| Campo                     | Tipo    | Descrição                                               | Caracteres |
|---------------------------|---------|---------------------------------------------------------|------------|
| `receiver_conciliation_id`| string  | Identificador único da conciliação do recebedor.        | -          |
| `transaction_data`        | Object  | Detalhes da transação associada ao QR code inicial.     | [Objeto transaction_data](#objeto-transaction_data) |

---

### Objeto transaction_data

| Campo               | Tipo   | Descrição                                   | Caracteres |
|---------------------|--------|---------------------------------------------|------------|
| `transaction_key`   | string | Chave única da transação.                   | 36         |
| `pix_transfer_key`  | string | Identificador da transferência Pix associada.| 36         |
| `end_to_end_id`     | string | Identificador end-to-end do Pix.            | 32         |

---

### Enumeradores journey_type

| Enumerador      | Descrição                                    |
|-----------------|----------------------------------------------|
| `journey_one`   | Notificação direta no aplicativo bancário    |
| `journey_two`   | Experiência QR Code para cobrança recorrente |
| `journey_three` | Pagamento instantâneo + recorrência QR Code  |
| `journey_four`  | Opt-in recorrente a partir de operação Pix   |

## Webhook de Status de Ordem de Pagamento

Este webhook é destinado ao reporte de alterações de status de ordens de pagamento do Pix Automático, informando sobre cancelamentos, pagamentos realizados e rejeições.

### Webhook Request Body

### Status: Cancelado (cancelled)

Request Body: Payment Order Cancelada

```json
{
  "event_type": "baas.automatic_pix.payment_order.status_change",
  "origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "data": {
    "payment_order_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "payment_order_spi_id": "RR2222222220240429njua7shf40k",
    "outgoing_recurrence_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "payment_order_status": "cancelled",
    "receiver_conciliation_id": "cac0b5f7-4ee2-40f1-b2ad-16902506503d",
    "transaction_amount": 125.53,
    "payment_order_conciliation_batch_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "transaction_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc56",
    "incoming_pix_transfer_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc56"
  }
}
```

### Status: Pago (paid)

Request Body: Payment Order Paga

```json
{
  "event_type": "baas.automatic_pix.payment_order.status_change",
  "origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "data": {
    "payment_order_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "payment_order_spi_id": "RR2222222220240429njua7shf40k",
    "outgoing_recurrence_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "payment_order_status": "paid",
    "receiver_conciliation_id": "cac0b5f7-4ee2-40f1-b2ad-16902506503d",
    "transaction_amount": 125.53,
    "payment_order_conciliation_batch_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "transaction_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc56",
    "incoming_pix_transfer_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc56",
    "paid_at": "2021-10-22T20:30:23.459Z"
  }
}
```

### Status: Rejeitado (rejected)

Request Body: Payment Order Rejeitada

```json
{
  "event_type": "baas.automatic_pix.payment_order.status_change",
  "origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "data": {
    "payment_order_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "payment_order_spi_id": "RR2222222220240429njua7shf40k",
    "outgoing_recurrence_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "payment_order_status": "rejected",
    "receiver_conciliation_id": "cac0b5f7-4ee2-40f1-b2ad-16902506503d",
    "transaction_amount": 125.53,
    "payment_order_conciliation_batch_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc82"
  }
}
```

:::info Informação
As ordens de pagamento rejeitadas são enviadas após o esgotamento do número máximo de tentativas (caso a recorrência permita retentativas). Neste caso, os campos `transaction_key` e `incoming_pix_transfer_key` não são incluídos no payload.
:::

### Webhook Body Params - Payment Order

| Campo                                | Tipo       | Descrição                                                                                                               | Caracteres |
|-------------------------------------- |------------|-------------------------------------------------------------------------------------------------------------------------|------------|
| `event_type` *                       | string     | Tipo do evento reportado (`baas.automatic_pix.payment_order.status_change`).                                            | 100        |
| `origin_key` *                       | string     | Identificador único de origem do evento (UUID da payment order).                                                        | 36         |
| `data` *                             | Object     | Objeto principal contendo os detalhes da ordem de pagamento.                                                            | [Objeto data](#objeto-data-payment-order)                                    |

---

### Objeto data (Payment Order)

| Campo                                | Tipo       | Descrição                                                                                           | Caracteres |
|-------------------------------------- |------------|-----------------------------------------------------------------------------------------------------|------------|
| `payment_order_key` *                 | string     | Chave única da ordem de pagamento (UUID).                                                           | 36         |
| `payment_order_spi_id` *              | string     | Identificador SPI da ordem de pagamento.                                                            | 29         |
| `outgoing_recurrence_key` *           | string     | Identificador único da recorrência automática associada (UUID).                                     | 36         |
| `payment_order_status` *              | string     | Status da ordem de pagamento (`cancelled`, `paid`, `rejected`).                                     | 30         |
| `receiver_conciliation_id` *          | string     | Identificador de conciliação do recebedor (UUID).                                                   | 36         |
| `transaction_amount` *                | number     | Valor da transação da ordem de pagamento.                                                           | -          |
| `payment_order_conciliation_batch_key` * | string  | Identificador do lote de conciliação associado (UUID).                                              | 36         |
| `transaction_key`                     | string     | Chave única da transação (presente apenas em status `cancelled` e `paid`).                          | 36         |
| `incoming_pix_transfer_key`           | string     | Identificador da transferência PIX de entrada (presente apenas em status `cancelled` e `paid`).     | 36         |
| `paid_at`                             | string     | Data e hora do pagamento (presente apenas em status `paid`, formato ISO 8601).                      | -          |

---

### Enumeradores payment_order_status

| Enumerador      | Descrição                                                    |
|-----------------|--------------------------------------------------------------|
| `cancelled`     | Ordem de pagamento cancelada pelo pagador ou recebedor       |
| `paid`          | Ordem de pagamento executada com sucesso                     |
| `rejected`      | Ordem de pagamento rejeitada após esgotamento de tentativas  |

## Webhook de Status de Tentativa de Ordem de Pagamento

Este webhook é destinado ao reporte de alterações de status das tentativas de execução de ordens de pagamento do Pix Automático, informando especialmente sobre tentativas rejeitadas e os motivos de rejeição.

### Webhook Request Body

### Status: Rejeitado (rejected)

Request Body: Tentativa de Payment Order Rejeitada

```json
{
  "event_type": "baas.automatic_pix.payment_order_attempt.status_change",
  "origin_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "data": {
    "request_control_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "payment_order_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "payment_order_attempt_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc82",
    "payment_order_status": "pending",
    "payment_order_attempt_status": "rejected",
    "transaction_amount": 125.53,
    "reason": "Conta de destino inexistente",
    "outgoing_recurrence_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82"
  }
}
```

:::info Informação
Este webhook é enviado sempre que uma tentativa de execução de uma ordem de pagamento é rejeitada pelo SPI. A ordem de pagamento pode ter novas tentativas dependendo da configuração da recorrência e do motivo da rejeição. O campo `reason` contém a descrição do motivo da rejeição baseado no código de erro do Bacen.
:::

### Webhook Body Params - Payment Order Attempt

| Campo                                | Tipo       | Descrição                                                                                                               | Caracteres |
|-------------------------------------- |------------|-------------------------------------------------------------------------------------------------------------------------|------------|
| `event_type` *                       | string     | Tipo do evento reportado (`baas.automatic_pix.payment_order_attempt.status_change`).                                   | 100        |
| `origin_key` *                       | string     | Identificador único de origem do evento (UUID da payment order).                                                        | 36         |
| `data` *                             | Object     | Objeto principal contendo os detalhes da tentativa de ordem de pagamento.                                               | [Objeto data](#objeto-data-payment-order-attempt)                                    |

---

### Objeto data (Payment Order Attempt)

| Campo                                | Tipo       | Descrição                                                                                           | Caracteres |
|-------------------------------------- |------------|-----------------------------------------------------------------------------------------------------|------------|
| `request_control_key` *               | string     | Chave de controle única da requisição (UUID da payment order).                                      | 36         |
| `payment_order_key` *                 | string     | Chave única da ordem de pagamento associada (UUID).                                                 | 36         |
| `payment_order_attempt_key` *         | string     | Chave única da tentativa de pagamento (UUID).                                                       | 36         |
| `payment_order_status` *              | string     | Status atual da ordem de pagamento (`pending`, `accepted`, `cancelled`, etc.).                      | 30         |
| `payment_order_attempt_status` *      | string     | Status da tentativa de pagamento (`rejected`).                                                      | 30         |
| `transaction_amount` *                | number     | Valor da transação da tentativa de pagamento.                                                       | -          |
| `reason` *                            | string     | Motivo da rejeição da tentativa (descrição do erro baseado no código Bacen).                       | 200        |
| `outgoing_recurrence_key` *           | string     | Identificador único da recorrência automática associada (UUID).                                     | 36         |

---

### Enumeradores payment_order_attempt_status

| Enumerador      | Descrição                                                         |
|-----------------|-------------------------------------------------------------------|
| `rejected`      | Tentativa de pagamento rejeitada pelo SPI por erro específico    |

## Webhook para tentativa de ordem de pagamento não liquidada

Webhook destinado a notificar quando uma tentativa de ordem de pagamento foi aceita mas não foi liquidada no prazo esperado.

### Webhook Request Body

Request Body: Tentativa de ordem de pagamento não liquidada

```json
{
    "webhook_type": "baas.automatic_pix.payment_order_attempt.not_liquidated",
    "webhook_datetime": "2025-10-22T21:15:00.000Z",
    "data": {
        "payment_order_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
        "payment_order_spi_id": "RR2222222220240429njua7shf40k",
        "outgoing_recurrence_key": "98fc62fd-b0a0-4604-9bea-475e91a9dc82",
        "payment_order_status": "pending",
        "receiver_conciliation_id": "cac0b5f7-4ee2-40f1-b2ad-16902506503d",
        "transaction_amount": "125.53",
        "payment_order_conciliation_batch_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc82",
        "payment_order_attempt_key": "21fc62fd-b0a0-4604-9bea-475e91a9dc83",
        "payment_order_attempt_status": "not_liquidated",
        "due_date": "2025-10-22",
        "end_to_end_id": "E1234567890123456789012"
    }
}
```

### Webhook Body Param

| Campo                                | Tipo      | Descrição                                                                                                | Max. Caracteres |
|--------------------------------------|-----------|----------------------------------------------------------------------------------------------------------|-----------------|
| `webhook_type`                       | string    | Um enumerador que define o tipo de evento sendo reportado                                                | 100             |
| `webhook_datetime`                   | string    | Data e hora do envio do webhook                                                                          | 20              |
| `payment_order_key`                  | uuid4     | Chave única de identificação da ordem de pagamento.                                                      | 36              |
| `payment_order_spi_id`               | string    | Identificador da ordem de pagamento no SPI.                                                               | 50              |
| `outgoing_recurrence_key`            | uuid4     | Chave única de identificação da recorrência de saída associada.                                          | 36              |
| `payment_order_status`               | string    | Status atual da ordem de pagamento.                                                                      | [Enumeradores payment_order_status](#enumeradores-payment_order_status) |
| `receiver_conciliation_id`           | string    | Identificação de conciliação do recebedor.                                                               | 36              |
| `transaction_amount`                 | number    | Valor da transação da ordem de pagamento.                                                                 | -               |
| `payment_order_conciliation_batch_key` | uuid4   | Chave única de identificação do lote de conciliação associado.                                           | 36              |
| `payment_order_attempt_key`          | uuid4     | Chave única de identificação da tentativa de ordem de pagamento.                                         | 36              |
| `payment_order_attempt_status`       | string    | Status da tentativa de ordem de pagamento.                                                               | [Enumeradores payment_order_attempt_status](#enumeradores-payment_order_attempt_status) |
| `due_date`                           | string    | Data de vencimento da tentativa de ordem de pagamento (formato YYYY-MM-DD).                              | 10              |
| `end_to_end_id`                      | string    | Chave de idempotência de uma transação Pix dentro do SPI.                                                | 32              |

### Enumeradores payment_order_status

| Enumerador            | Descrição                                          |
|-----------------------|----------------------------------------------------|
| `pending_conciliation`| Aguardando conciliação.                            |
| `pending`             | Pendente e aguardando pagamento.                   |
| `paid`                | Paga com sucesso.                                  |
| `rejected`            | Rejeitada e não será processada.                   |
| `cancelled`           | Cancelada antes do pagamento.                      |

### Enumeradores payment_order_attempt_status

| Enumerador      | Descrição                                                         |
|-----------------|-------------------------------------------------------------------|
| `sent`          | Tentativa de pagamento enviada                                    |
| `accepted`      | Tentativa de pagamento aceita                                     |
| `rejected`      | Tentativa de pagamento rejeitada pelo SPI por erro específico    |
| `not_liquidated`| Tentativa de pagamento aceita mas não liquidada no prazo esperado |

---

# Aprovar Transação com Autenticação de Dois Fatores

URL: /documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer/ PIX_TRANSFER_KEY /validate_token
MÉTODO PUT

### Path Params

| Campo              | Tipo   | Descrição                                      | Caracteres |
|--------------------|--------|------------------------------------------------|------------|
| `account_key`      | uuidv4 | Chave única de identificação da conta.         | 36         |
| `pix_transfer_key` | uuidv4 | Chave única de identificação da transação pix. | 36         |

## Autenticação via Email e SMS

Request Body

```json
{
  "token": "329adf"
}
```

## Autenticação via Dispositivo

Para aprovar e finalizar a autenticação via dispositivo, a requisição deve ser enviada com um payload vazio. A validação ocorre internamente, sem necessidade de informações adicionais no corpo da requisição. É importante destacar que este endpoint só deve ser utilizado após a [solicitação de transação](./solicitacao_de_transacao_pix_2fa.md) ter sido iniciada.

Request Body

```json
{

}
```

## Body Params

| Campo     | Tipo   | Descrição                                                             | Caracteres |
|-----------|--------|-----------------------------------------------------------------------|------------|
| `token`   | string | Código de autenticação enviado ao aprovador de movimentações da conta **obrigatório para TFA via SMS ou e-mail**| 6          | 

## Response

STATUS 201

Response Body: Transferência Enviada

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "end_to_end_id": "E32402502202405081755SxyT2DDcVwc",
  "pix_transfer_status": "sent",
  "created_at": "2021-10-22T20:30:23.459Z",
  "transaction_key": "46804f32-101e-4702-8fbc-c2dbc4c2caec"
}
```

STATUS 202

Response Body: Transferência Pendente

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "end_to_end_id": "E32402502202405081755SxyT2DDcVwc",
  "pix_transfer_status": "pending",
  "created_at": "2021-10-22T20:30:23.459Z"
}
```

STATUS 4xx

Response Body: Transferência Rejeitada

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {
    "pix_transfer_data": {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "end_to_end_id": "E32402502202405081755SxyT2DDcVwc",
      "pix_transfer_status": "rejected",
      "created_at": "2021-10-22T20:30:23.459Z"
    }
  }
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (ptbr)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Erro de Schema                                                                                                         |
| 404                      | PXT000023            | Outgoing PIX Transfer Not Found                    | Pix transfer key \{pix_transfer_key\} was not found                                                                     | Transferência PIX de saída com chave \{pix_transfer_key\} não foi encontrada                                           |
| 400                      | PXT000175            | Invalid Status                                     | Pix transfer not in pending_2fa_approval status                                                                         | Pix transfer não está pendente de aprovação por two factor authentication                                              |
| 400                      | PXT000182            | Bad Request                                        | The given Pix transfer is tied to a batch. It cannot be individually approved. Please approve batch                     | A Pix transfer enviada está ligada a um lote. Ela não pode ser individualmente aprovada. Por favor aprove o lote       |
| 400                      | PXT000174            | Error Sending Token                                | An error occurred while sending token and its being investigated                                                        | Um erro ocorreu ao enviar token e está sendo investigado                                                               |
| 400                      | PXT000173            | Incorrect Token                                    | Token sent does not match expected                                                                                      | Token enviado não condiz com, o esperado                                                                               |
| 400                      | PXT000172            | Token Expired                                      | Token has expired. Resend token or recreate transfer                                                                    | Token expirado. Reenvie token ou recrie a transferência                                                                | 
| 400                      | PXT000171            | Number of token validation attempts exceeded       | The maximum number of failed token validation attempts has been reached                                                 | Número máximo de tentativas de validação de token atingida                                                             |
| 406                      | PXT000103            | request_control_key must be a valid uuid v4 string | request_control_key was not accepted for not being a valid uuid v4 string                                               | request_control_key não foi aceito por não ser uma palavra uuid v4 válida                                              |
| 400                      | PXT000048            | Bad Request                                        | Emoji not allowed in pix message.                                                                                       | Emoji não é permitido na mensagem pix.                                                                                 |
| 400                      | PXT000104            | Invalid Transaction Amount                         | Transaction amount of \{transaction_amount\} is not valid. It must be a positive value with at maximum 2 decimal places | O valor de transação \{transaction_amount\} não é válido. Deve ser um valor positivo com no máximo duas casas decimais |
| 404                      | PXT000004            | Account not found                                  | Account not found for: \{account_datum\}                                                                                | Conta não encontrada para: \{account_datum\}                                                                           |
| 400                      | PXT000003            | Account is Closed                                  | Account \{account_key\} is closed.                                                                                      | Conta \{account_key\} está fechada.                                                                                    |
| 422                      | PXT000092            | Invalid Account Type                               | Pix is not yet implemented for non-checking or non-escrow account types                                                 | Transações Pix não estão implementadas para conta que não sejam escrow ou livres                                       |
| 403                      | PIT000001            | User is not allowed to do this transaction         |                                                                                                                         | Usuário não tem autorização para fazer essa transação                                                                  |
| 400                      | PXT000010            | Account is Blocked                                 | Account \{account_key\} is blocked.                                                                                     | Conta \{account_key\} está bloqueada.                                                                                  |
| 400                      | PXT000003            | Account is Closed                                  | Account \{account_key\} is closed.                                                                                      | Conta \{account_key\} está fechada.                                                                                    |
| 400                      | PIT000003            | Bad Request                                        | Insufficient account balance for transfer and fee amount.                                                               | Saldo de conta insuficiente para a transferência e a taxa.                                                             |
| 400                      | PXT000118            | Requester is not Pix Participant                   | The requester sent an alias key but is not a indirect pix participant                                                   | O requisitante enviou uma alias key no entanto não é um participante do pix indireto                                   |
| 404                      | PXT000120            | Alias sent not found                               | Alias key attached to this account not found                                                                            | Alias key vinculada à conta não encontrada                                                                             |
| 406                      | PXT000105            | Invalid end_to_end_id                              | The end_to_end_id sent \{end_to_end_id\} is not valid.                                                                  | O end_to_end_id enviado \{end_to_end_id\} não é válido.                                                                |
| 400                      | PXT000108            | Bad Request                                        | Billing account closed or blocked                                                                                       | Conta de cobrança encerrada ou bloqueada                                                                               |
| 400                      | PXT000079            | Bad Request                                        | Insufficient billing account balance for fee.                                                                           | Saldo de conta de cobrança insuficiente para a taxa.                                                                   |
| 400                      | PIT000004            | Bad Request                                        | Transaction amount is over limit.                                                                                       | O total da transferência é superior ao limite.                                                                         |
| 404                      | PIX000056            | Not Found                                          | Pix key inquiry not found                                                                                               | Consulta de chave pix não encontrada                                                                                   |
| 404                      | PXT000041            | Not Found                                          | Qr Code not found                                                                                                       | Qr Code não encontrado                                                                                                 |
| 400                      | PXT000053            | Bad Request                                        | QrCode already paid                                                                                                     | Qr Code já Pago                                                                                                        |
| 400                      | PXT000118            | Requester is not Pix Participant                   | The requester sent an alias key but is not a indirect pix participant                                                   | O requisitante enviou uma alias key no entanto não é um participante do pix indireto                                   |
| 404                      | PXT000120            | Alias sent not found                               | Alias key attached to this account not found                                                                            | Alias key vinculada à conta não encontrada                                                                             |
| 400                      | PXT000115            | Bad Request                                        | Insufficient account balance for transfer and fee amount.                                                               | Saldo de conta insuficiente para a transferência e a taxa                                                              |
| 400                      | PXT000128            | Bad Request                                        | Pix key \{pix_key\} sent does match inquiry pix key. Verify if end_to_end_id sent is correct                            | Chave Pix \{pix_key\} enviada não condiz com consulta. Verifique se end_to_end_id enviado está correto                 |
| 400                      | PXT000109            | Bad Request                                        | request_control_key \{request_control_key\} already in use                                                              | request_control_key \{request_control_key\} já utilizada                                                               |
| 400                      | PXT000061            | Bad Request                                        | End to end id invalid. A pix transfer with the end to end id \{end_to_end\} has already been registered!                | End to end id inválido. Uma transação pix com o identificador único \{end_to_end\} já foi registrada!                  |
| 400                      | PXT000129            | SPI Error message                                  | Message rejected by SPI-ICOM                                                                                            | Mensagem rejeitada pela SPI-ICOM                                                                                       |
| 408                      | PXT000130            | SPI Timeout Control                                | SPI Timeout Control                                                                                                     | Controle de timeout no SPI                                                                                             |
| 400                      | PXT000131            | Receiver Internal Error                            | Cancelled transaction due to receiver's internal error                                                                  | Transação interrompida devido a erro no PSP do Recebedor                                                               |
| 400                      | PXT000132            | Invalid Target Account Number                      | Target account number is invalid                                                                                        | Número da conta de destino é inexistente ou inválido                                                                   |
| 400                      | PXT000133            | Blocked Target Account                             | Target account is blocked.                                                                                              | A conta de destino encontra-se bloqueada.                                                                              |
| 400                      | PXT000134            | Closed Target Account                              | Target account is closed.                                                                                               | A conta de destino encontra-se encerrada.                                                                              |
| 400                      | PXT000135            | Unsupported Transaction                            | Unsupported transaction for given target account.                                                                       | A conta de destino não suporta este tipo de transação.                                                                 |
| 400                      | PXT000136            | Invalid Participant                                | SPI participant is not PSP settler agent of payer nor receiver.                                                         | Participante direto do SPI não é liquidante do PSP do Pagador / Recebedor.                                             |
| 400                      | PXT000137            | Zero Value Payment Order                           | Zero value payment order.                                                                                               | Ordem de pagamento com valor zero.                                                                                     |
| 400                      | PXT000138            | Insufficient Funds                                 | Insufficient funds in PI account from payer.                                                                            | Saldo insuficiente na conta PI do pagador.                                                                             |
| 400                      | PXT000139            | Return Value Too Great                             | Return value greater than corresponding payment order.                                                                  | Valor de devolução acima do valor de pagamento correspondente.                                                         |
| 400                      | PXT000140            | Invalid Transactions Number                        | Invalid transactions number.                                                                                            | Quantidade de transações inválida.                                                                                     |
| 400                      | PXT000141            | Unrelated Beneficiary Document Number              | Beneficiary document number is not that of target account owner.                                                        | CPF/CNPJ do usuário recebedor não é compatível com o titular da conta de destino.                                      |
| 400                      | PXT000142            | Invalid Beneficiary Document Number                | Invalid beneficiary document number                                                                                     | CPF/CNPJ da conta de destino está incorreto.                                                                           |
| 400                      | PXT000143            | Incorrect Message Element                          | Incorrect message element.                                                                                              | Elemento da mensagem incorreto.                                                                                        |
| 403                      | PXT000144            | Rejected Payment Order                             | Beneficiary's PSP has rejected payment order.                                                                           | Ordem de pagamento foi rejeitada pelo banco recebedor.                                                                 |
| 403                      | PXT000145            | Unauthorized Payer                                 | Signing participant is unauthorized to make a payment order for paying account.                                         | Participante que assinou a mensagem não é autorizado a realizar a operação na conta PI debitada.                       |
| 400                      | PXT000146            | Invalid Datetime                                   | Invalid datetime for message delivery.                                                                                  | Data e Hora do envio da mensagem inválida.                                                                             |
| 400                      | PXT000147            | Generic Error                                      | Error while processing payment (generic error).                                                                         | Erro no processamento do pagamento (erro genérico).                                                                    |
| 400                      | PXT000148            | Bad Format Operation Identifier                    | Badly formatted operation's identifier.                                                                                 | Identificador da operação mal formatado.                                                                               |
| 400                      | PXT000149            | Invalid Payer ISPB                                 | Invalid or non-existent payer's PSP ISPB number.                                                                        | Número ISPB do PSP do Pagador é inválido ou inexistente.                                                               |
| 400                      | PXT000150            | Invalid Beneficiary ISPB                           | Invalid or non-existent beneficiary's PSP ISPB number.                                                                  | Número ISPB do banco recebedor é inválido ou inexistente.                                                              |
| 400                      | PXT000151            | Incorrect Type                                     | Incorrect type for target account.                                                                                      | Tipo incorreto para a conta transacional especificada.                                                                 |
| 400                      | PXT000152            | Repeated End-to-End ID Error                       | The end_to_end_id was already used                                                                                      | O end_to_end_id já foi utilizado                                                                                       |
| 400                      | PXT000153            | Invalid Target Account Type                        | The target account type cannot receive PIX transactions                                                                 | O tipo de conta destino não pode receber transações PIX                                                                |
| 400                      | PXT000154            | Invalid ISPB                                       | Invalid or non-existent ISPB number.                                                                                    | Número ISPB é inválido ou inexistente.                                                                                 |
| 400                      | PXT000155            | Amount too Great                                   | Amount too great for credited account.                                                                                  | Valor de pagamento/devolução acima do permitido para a conta de destino creditada.                                     |
| 400                      | PXT000156            | QR Code Rejected                                   | QR Code rejected by beneficiary's PSP.                                                                                  | QR Code rejeitado pelo PSP do usuário recebedor.                                                                       |
| 503                      | PXT000157            | Bacen Service Unavailable Error                    | Could not send the message to ICOM after 3 retries                                                                      | Não pode enviar a mensagem para a ICOM depois de 3 tentativas                                                          |
| 400                      | PXT000158            | Invalid Amount                                     | Paid amount diverges from expected amount of \{expected_amount\}                                                        | O valor do pagamento diverge do valor esperado de \{expected_amount\}                                                  |
| 400                      | PXT000159            | QR code inactive                                   | QR code is not active at the time of payment                                                                            | QR code não está ativo no instante do pagamento                                                                        |
| 400                      | PXT000189            | Token Required                                | A token is required for SMS or email validation.                    | Um token é necessário para validação via SMS ou email.             |

---

# Introdução a Autenticação de Dois Fatores

URL: /documentation/baas/pix/2fa_v2/introducao_a_transacao_pix_2fa

Neste tipo de transação, é necessário a confirmação do pagamento via token enviado à pessoa com poderes de aprovação de
movimentação na conta credora.

A solicitação de transação Pix por parceiros integradores configurados para a utilização de autenticação de dois
fatores é realizada de forma similar ao descrito
em [realizar transação Pix](/documentation/baas/pix/realizar_transferencia). A diferença ocorre na adição do
objeto `tfa_info`, contento informações sobre o aprovador da transferência e a forma de contato, e o status de uma
solicitação bem sucedida que será sempre **pending_2fa_approval**.

O mesmo vale para transações em lote Pix descrito em [realizar transação pix em lote](/documentation/baas/pix/batch/solicitacao_de_transacao_em_lote_pix).

## Fluxo para uma transação Pix com autorização

A transação Pix bem sucedida seguirá o seguinte fluxo de processos:
Realização da [solicitação de transação Pix](/documentation/baas/pix/2fa_v2/solicitacao_de_transacao_pix_2fa) e recebimento de resposta de forma síncrona com status de **pending_2fa_approval** e valor da `pix_transfer_key`.
O aprovador indicado receberá um `token` de 6 dígitos compostos por algarismos.
O requisitante realiza a [confirmação de transação pix](/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa) com a `pix_transfer_key` e o `token`.
A transferência será concluída de forma síncrona ou assíncrona a depender da configuração do parceiro integrador.
## Observações
Cada transação possui um limite máximo de tentativas de validação do `token` de 5. Quando este limite é alcançado a transação será colocada em status de rejeitada (**rejected**) automaticamente.
Cada `token` possui duração máxima de 5 minutos.
Uma transação pode ter seu `token` renovado e reenviado para o aprovador da transferência. Este processo reinica o tempo de 5 minutos e não reinicia o contador de tentativas inválidas. O `token` anterior torna-se inválido.
Uma vez aprovada a transação, esta será concluída em regime síncrono ou assíncrono a depender da configuração do parceiro integrador.
O evento de notificação para o envio de `token` ao aprovador é **baas.token_validation.pix_transfer.single**. É possível [personalizar](/documentation/notificacoes/template) a mensagem enviada.
As formas de envio (`contact_type`) de token implementadas são por **sms** e **email**.

---

# Solicitar a devolução de um Pix recebido

URL: /documentation/baas/pix/2fa_v2/solicitacao_de_devolucao_pix

A devolução de um Pix pode ser efetuada em até 90 dias a partir de seu recebimento.

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer/ PIX_TRANSFER_KEY /reversal
MÉTODO POST

### Path Params

| Campo                | Tipo   | Descrição                                                        | Caracteres |
|----------------------|--------|------------------------------------------------------------------|------------|
| `account_key` *      | uuidv4 | Chave única de identificação da conta.                           | 36         |
| `pix_transfer_key` * | uuidv4 | Chave única de identificação da transferência Pix no sistema QI. | 36         |

Request Body

```json
{
  "request_control_key": "303393bf-8f2e-4ff0-b326-ee7ad612e8ca",
  "reversal_amount": 147,
  "reversal_reason": "client_request",
  "reversal_message": "Mensagem Pix da Devolução",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```

### Request Params

| Campo                   | Tipo   | Descrição                                                                       | Caracteres                                                    |
|-------------------------|--------|---------------------------------------------------------------------------------|---------------------------------------------------------------|
| `request_control_key` * | uuidv4 | Chave de unicidade da requisição.                                               | 36                                                            |
| `reversal_amount` *     | number | Valor da devolução.                                                             | 11                                                            |
| `reversal_reason` *     | string | Motivo da devolução.                                                            | **[Enumerador reversal_reason](#enumerador-reversal_reason)** |
| `reversal_message`      | string | Mensagem da devolução.                                                          | 140                                                           |
| `tfa_info`*             | Object | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato. | **[Objeto tfa_info](#objeto-tfa_info)**                       |

### Enumerador reversal_reason

| Enumerador         | Descrição                                     |
|--------------------|-----------------------------------------------|
| **client_request** | Caso tenha sido requerido pelo dono da conta. |
| **reconciliation** | Para reconciliação devido a erro operacional. |

### Objeto tfa_info

| Campo                       | Tipo   | Descrição                                                                           | Caracteres |
|-----------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta.                                  | 11         | 
| `contact_type`*             | string | Forma de contato com a pessoa aprovadora da conta, podendo ser **sms** ou **email** |            |

## Response

STATUS 202

Response Body: Reversão Requisitada

```json
{
  "reversal_status": "pending_2fa_approval",
  "end_to_end_id": "E32402502202405081755SxyT2DDcVwc",
  "pix_transfer_key": "cdcf0d25-08a1-46e3-902a-6d7ca75e6c48",
  "request_control_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
  "created_at": "2021-10-22T20:30:23.459Z"
}
```

### Response Body

| Campo                 | Tipo       | Descrição                                                       | Caracteres                                                |
|-----------------------|------------|-----------------------------------------------------------------|-----------------------------------------------------------|
| `reversal_status`     | enumerator | Enumerador de status da transação de devolução.                 | [Enumerador reversal_status](#enumerador-reversal_status) |
| `transfer_amount`     | number     | Valor da transferência de devolução.                            | 11                                                        |
| `pix_transfer_key`    | uuidv4     | Chave da transação pix executada na devolução.                  | 36                                                        |
| `request_control_key` | uuidv4     | Chave única de identificação da request utilizada pelo cliente. | 36                                                        |
| `created_at`          | string     | Data e hora da devolução.                                       | 10                                                        |

### Enumerador reversal_status

| Enumerador               | Descrição                                                |
|--------------------------|----------------------------------------------------------|
| **sent**                 | Transferência Pix realizada com sucesso.                 |
| **pending**              | Transferência Pix pendente.                              |
| **pending_2fa_approval** | Transferência Pix pendente de aprovação por dois fatores |
| **rejected**             | Transferência Pix rejeitada.                             |

STATUS 4xx

Response Body: Reversão Rejeitada

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {
    "pix_transfer_data": {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "end_to_end_id": "E32402502202405081755SxyT2DDcVwc",
      "pix_transfer_status": "rejected",
      "created_at": "2021-10-22T20:30:23.459Z"
    }
  }
}
```

:::info Informação
Além dos erros anteriormente listados para [transferência Pix](/documentation/baas/pix/realizar_transferencia), a
devolução de um Pix também pode retornar os erros listados abaixo.
:::

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                   | Descrição (eng)<br/>`description`                                      | Descrição (ptbr)<br/>`translation`                                                        |
|--------------------------|----------------------|--------------------------------------|------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                          | Schema Error                                                           | Erro de Schema                                                                            |
| 404                      | PXT000018            | Reversal Original Transfer not Found | Reversal original pix transfer not found.                              | Transferência original da devolução não foi encontrada.                                   |
| 400                      | PXT000017            | Reversal Too Great                   | Reversal transfers sum amount surpasses that of original pix transfer. | A soma das transferências de devolução ultrapassam o valor da transferência pix original. |
| 400                      | PXT000015            | Reversal date expired                | Reversal original transaction is older than 90 days                    | A data de criação da transação original é mais antiga que 90 dias                         |
| 400                      | PXT0000127           | Invalid Reversal Reason              | Reversal reason \{reversal_reason\} is not valid                       | Razão de reversão \{reversal_reason\} não é válida                                        |

---

# Solicitar reenvio de token para uma transação

URL: /documentation/baas/pix/2fa_v2/solicitacao_de_reenvio_de_token

Um novo token será gerado e enviado para o aprovador da transação pix. Caso o número limite de tentativas de validação
do token tenha sido excedida, não será permitido o reenvio.

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer/ PIX_TRANSFER_KEY /resend_token
MÉTODO PATCH

### Path Params

| Campo                | Tipo   | Descrição                                                        | Caracteres |
|----------------------|--------|------------------------------------------------------------------|------------|
| `account_key` *      | uuidv4 | Chave única de identificação da conta.                           | 36         |
| `pix_transfer_key` * | uuidv4 | Chave única de identificação da transferência Pix no sistema QI. | 36         |

### Body Params

| Campo          | Tipo   | Descrição                                                                                 | Caracteres |
|----------------|--------|-------------------------------------------------------------------------------------------|------------|
| `contact_type` | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** |

:::info Informação
Caso não seja enviado um `contact_type`, o token será enviado da forma solicitada originalmente.
:::

| Enumerador | Descrição                                         |
|------------|---------------------------------------------------|
| **sms**    | Envio por Mensagem de Texto para telefone celular |
| **email**  | Envio por correio eletrônico                      |

## Response

STATUS 202

Response Body: Transação Solicitada

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "end_to_end_id": "E32402502202405081755SxyT2DDcVwc",
  "pix_transfer_status": "pending_2fa_approval",
  "created_at": "2021-10-22T20:30:23.459Z"
}
```

STATUS 4xx

Response Body: Transferência Rejeitada

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {
    "pix_transfer_data": {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "pix_transfer_status": "rejected",
      "created_at": "2021-10-22T20:30:23.459Z"
    }
  }
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                           | Descrição (eng)<br/>`description`                                       | Descrição (ptbr)<br/>`translation`                                           |
|--------------------------|----------------------|----------------------------------------------|-------------------------------------------------------------------------|------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                  | Schema Error                                                            | Erro de Schema                                                               |
| 404                      | PXT000004            | Account not found                            | Account not found for: \{account_datum\}                                | Conta não encontrada para: \{account_datum\}                                 |
| 404                      | PXT000023            | Outgoing PIX Transfer Not Found              | Pix transfer key \{pix_transfer_key\} was not found                     | Transferência PIX de saída com chave \{pix_transfer_key\} não foi encontrada |
| 400                      | PXT000171            | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida                   |
| 400                      | PXT000175            | Invalid Status                               | Pix transfer not in pending_2fa_approval status                         | Pix transfer não está pendente de aprovação por two factor authentication    |
| 400                      | PXT000176            | Error Sending Token                          | An error occurred while resending token and its being investigated      | Um erro ocorreu ao reenviar token e está sendo investigado                   |

---

# Solicitar Transação com Autenticação de Dois Fatores

URL: /documentation/baas/pix/2fa_v2/solicitacao_de_transacao_pix_2fa

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer
MÉTODO POST

### Path Params

| Campo         | Tipo   | Descrição                              | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36         |

**Chave**
## Autenticação via Email e SMS
Request Body: Transferência via Chave Pix com TFA por SMS ou Email

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_type": "key",
  "target_pix_key": "target_pix_key@email.com",
  "transaction_amount": 500.65,
  "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
  "pix_message": "Ola Mundo",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```

## Autenticação via Dispositivo

Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`.
Request Body: Transferência via Chave Pix com TFA por Dispositivo

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_type": "key",
  "target_pix_key": "target_pix_key@email.com",
  "transaction_amount": 500.65,
  "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
  "pix_message": "Ola Mundo",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
    "contact_type": "device"
  }
}
```

### Body Params

| Campo                   | Tipo       | Descrição                                                                                                                                                                                                                                        | Caracteres                              |
|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------|
| `request_control_key` * | uuidv4     | Chave única de identificação da request utilizada pelo cliente no formato uuid v4.                                                                                                                                                               | 36                                      | 
| `pix_transfer_type` *   | enumerator | Tipo do pix a ser realizado. Para o caso de transferência por chave deve ser **key**.                                                                                                                                                            | **key**                                 |
| `target_pix_key` *      | string     | Chave pix da conta a ser enviada a transação.                                                                                                                                                                                                    | 100                                     |
| `transaction_amount` *  | number     | Valor da transferência.                                                                                                                                                                                                                          | 10                                      |
| `end_to_end_id` *       | string     | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na consulta de chave Pix. Só deve ser enviado se o `pix_transfer_type` for **key**, **static_qr_code** ou **static_qr_code** | 32                                      |
| `pix_message`           | string     | Mensagem a ser enviada junto à transferência Pix.                                                                                                                                                                                                | 140                                     |
| `tfa_info`*             | Object     | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato.                                                                                                                                                                  | **[Objeto tfa_info](#objeto-tfa_info)** |

**Manual**
## Autenticação via Email e SMS
Request Body: Transferência Manual com TFA por SMS ou Email

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_type": "manual",
  "target_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "32402502000135",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502"
  },
  "transaction_amount": 500.65,
  "pix_message": "Ola Mundo",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```

## Autenticação via Dispositivo

Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`.

Request Body: Transferência Manual com TFA por Dispositivo

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_type": "manual",
  "target_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "32402502000135",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502"
  },
  "transaction_amount": 500.65,
  "pix_message": "Ola Mundo",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
    "contact_type": "device"
  }
}
```

### Body Params

| Campo                   | Tipo       | Descrição                                                                                         | Caracteres                                          |
|-------------------------|------------|---------------------------------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | uuidv4     | Chave única de identificação da request utilizada pelo cliente no formato uuid v4.                | 36                                                  | 
| `pix_transfer_type` *   | enumerator | Tipo de transferência Pix.                                                                        | **manual**                                          |
| `target_account` *      | Object     | Conta destino - Só deve ser enviada em transferências com `pix_transfer_type` do tipo **manual**. | **[Objeto target_account](#objeto-target_account)** | 10 |
| `transaction_amount` *  | number     | Valor da transferência.                                                                           | 10                                                  |
| `pix_message`           | string     | Mensagem a ser enviada junto à transferência Pix.                                                 | 140                                                 |
| `tfa_info`*             | Object     | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato.                   | **[Objeto tfa_info](#objeto-tfa_info)**             |

### Objeto target_account

| Campo                     | Tipo       | Descrição                                           | Caracteres                                              |
|---------------------------|------------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string     | Agência da conta.                                   | 4                                                       |
| `account_digit` *         | string     | Dígito da conta.                                    | 1                                                       |
| `account_number` *        | string     | Número da conta.                                    | 20                                                      |
| `owner_document_number` * | string     | CPF ou CNPJ (apenas números) do titular da conta.   | 14                                                      |
| `owner_name` *            | string     | Nome do titular da conta.                           | 150                                                     |
| `account_type`*           | enumerator | Tipo da conta.                                      | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string     | Base no CNPJ da instituição financeira (8 dígitos). | 8                                                       |

### Enumerador account_type

| Enumerador           | Descrição           |
|----------------------|---------------------|
| **checking_account** | Conta Corrente      |
| **salary_account**   | Conta Salário       |
| **saving_account**   | Conta Poupança      |
| **payment_account**  | Conta de Pagamentos |

**Qr Code**
## Autenticação via Email e SMS
Request Body: Transferência via QR Code com TFA por SMS ou Email

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_type": "static_qr_code",
  "transaction_amount": 500.65,
  "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
  "receiver_conciliation_id": "REC00000000000000000000009459463343",
  "target_pix_key": "target_pix_key@email.com",
  "pix_message": "Ola Mundo",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```

## Autenticação via Dispositivo

Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`.

Request Body: Transferência via QR Code com TFA por Dispositivo

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_type": "static_qr_code",
  "transaction_amount": 500.65,
  "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
  "receiver_conciliation_id": "REC00000000000000000000009459463343",
  "target_pix_key": "target_pix_key@email.com",
  "pix_message": "Ola Mundo",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
    "contact_type": "device"
  }
}
```

### Body Params

| Campo                      | Tipo       | Descrição                                                                                                                                                                                                                                         | Caracteres                                |
|----------------------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|
| `request_control_key`*     | uuidv4     | Chave única de identificação da request utilizada pelo cliente no formato uuid v4.                                                                                                                                                                | 36                                        | 
| `pix_transfer_type`*       | enumerator | Tipo de transferência Pix.                                                                                                                                                                                                                        | **static_qr_code** ou **dynamic_qr_code** |
| `target_pix_key`*          | string     | Chave pix da conta a ser enviada a transação.                                                                                                                                                                                                     | 100                                       |
| `receiver_conciliation_id` | string     | Identicação de conciliação do recebedor.                                                                                                                                                                                                          | 35                                        |
| `transaction_amount`*      | number     | Valor da transferência.                                                                                                                                                                                                                           | 10                                        |
| `end_to_end_id`*           | string     | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na consulta de chave Pix. Só deve ser enviado se o `pix_transfer_type` for **key**, **static_qr_code** ou **static_qr_code**. | 32                                        |
| `pix_message`              | string     | Mensagem a ser enviada junto à transferência Pix.                                                                                                                                                                                                 | 140                                       |
| `tfa_info`*                | Object     | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato.                                                                                                                                                                   | **[Objeto tfa_info](#objeto-tfa_info)**   |

:::info Aviso
O `end_to_end_id` é retornado ao [decodificar o QR Code Pix](/documentation/pix/decodificar_qr_code), utilizando a URI
do Pix Copia e Cola.
:::

### Objeto tfa_info

| Campo                       | Tipo   | Descrição                                                                           | Caracteres |
|-----------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta.                                  | 11         | 
| `session_id`| string | Chave única de identificação da sessão do dispositivo no formato UUID v4 (obrigatório para TFA via dispositivo). |   36         |
| `contact_type`*             | string | Forma de contato com a pessoa aprovadora da conta, podendo ser **sms**, **email** ou **device** |            |

:::danger Aviso
O `end_to_end_id` da consulta deve ter sido feito em nome da conta que solicitará a movimentação!
:::

:::danger Aviso
Um `end_to_end_id` só pode ser utilizado para uma única transferência, não importando, se a transferência tenha sido bem
sucedida ou não.
:::

## Response

STATUS 202

Response Body: Transação Solicitada

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "end_to_end_id": "E32402502202405081755SxyT2DDcVwc",
  "pix_transfer_status": "pending_2fa_approval",
  "created_at": "2021-10-22T20:30:23.459Z"
}
```

STATUS 4xx

Response Body: Transferência Rejeitada

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {
    "pix_transfer_data": {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "end_to_end_id": "E32402502202405081755SxyT2DDcVwc",
      "pix_transfer_status": "rejected",
      "created_at": "2021-10-22T20:30:23.459Z"
    }
  }
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (ptbr)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Erro de Schema                                                                                                         |
| 400                      | PXT000168            | No approver permission                             | Given document number does not belong to an approver for this account                                                   | Número de documento enviado não pertence a um aprovador da conta                                                       |
| 400                      | PXT000169            | tfa_info is required                               | Client must send object tfa_info                                                                                        | Cliente deve enviar objeto tfa_info                                                                                    |
| 400                      | PXT000170            | Error occurred while sending token                 | An unexpected error occurred while sending token                                                                        | Um erro inexperado ocorreu ao tentar enviar token                                                                      |
| 406                      | PXT000103            | request_control_key must be a valid uuid v4 string | request_control_key was not accepted for not being a valid uuid v4 string                                               | request_control_key não foi aceito por não ser uma palavra uuid v4 válida                                              |
| 400                      | PXT000048            | Bad Request                                        | Emoji not allowed in pix message.                                                                                       | Emoji não é permitido na mensagem pix.                                                                                 |
| 400                      | PXT000104            | Invalid Transaction Amount                         | Transaction amount of \{transaction_amount\} is not valid. It must be a positive value with at maximum 2 decimal places | O valor de transação \{transaction_amount\} não é válido. Deve ser um valor positivo com no máximo duas casas decimais |
| 404                      | PXT000004            | Account not found                                  | Account not found for: \{account_datum\}                                                                                | Conta não encontrada para: \{account_datum\}                                                                           |
| 400                      | PXT000003            | Account is Closed                                  | Account \{account_key\} is closed.                                                                                      | Conta \{account_key\} está fechada.                                                                                    |
| 422                      | PXT000092            | Invalid Account Type                               | Pix is not yet implemented for non-checking or non-escrow account types                                                 | Transações Pix não estão implementadas para conta que não sejam escrow ou livres                                       |
| 403                      | PIT000001            | User is not allowed to do this transaction         |                                                                                                                         | Usuário não tem autorização para fazer essa transação                                                                  |
| 400                      | PXT000010            | Account is Blocked                                 | Account \{account_key\} is blocked.                                                                                     | Conta \{account_key\} está bloqueada.                                                                                  |
| 400                      | PXT000003            | Account is Closed                                  | Account \{account_key\} is closed.                                                                                      | Conta \{account_key\} está fechada.                                                                                    |
| 400                      | PIT000003            | Bad Request                                        | Insufficient account balance for transfer and fee amount.                                                               | Saldo de conta insuficiente para a transferência e a taxa.                                                             |
| 400                      | PXT000118            | Requester is not Pix Participant                   | The requester sent an alias key but is not a indirect pix participant                                                   | O requisitante enviou uma alias key no entanto não é um participante do pix indireto                                   |
| 404                      | PXT000120            | Alias sent not found                               | Alias key attached to this account not found                                                                            | Alias key vinculada à conta não encontrada                                                                             |
| 406                      | PXT000105            | Invalid end_to_end_id                              | The end_to_end_id sent \{end_to_end_id\} is not valid.                                                                  | O end_to_end_id enviado \{end_to_end_id\} não é válido.                                                                |
| 400                      | PXT000108            | Bad Request                                        | Billing account closed or blocked                                                                                       | Conta de cobrança encerrada ou bloqueada                                                                               |
| 400                      | PXT000079            | Bad Request                                        | Insufficient billing account balance for fee.                                                                           | Saldo de conta de cobrança insuficiente para a taxa.                                                                   |
| 400                      | PIT000004            | Bad Request                                        | Transaction amount is over limit.                                                                                       | O total da transferência é superior ao limite.                                                                         |
| 404                      | PIX000056            | Not Found                                          | Pix key inquiry not found                                                                                               | Consulta de chave pix não encontrada                                                                                   |
| 404                      | PXT000041            | Not Found                                          | Qr Code not found                                                                                                       | Qr Code não encontrado                                                                                                 |
| 400                      | PXT000053            | Bad Request                                        | QrCode already paid                                                                                                     | Qr Code já Pago                                                                                                        |
| 400                      | PXT000118            | Requester is not Pix Participant                   | The requester sent an alias key but is not a indirect pix participant                                                   | O requisitante enviou uma alias key no entanto não é um participante do pix indireto                                   |
| 404                      | PXT000120            | Alias sent not found                               | Alias key attached to this account not found                                                                            | Alias key vinculada à conta não encontrada                                                                             |
| 400                      | PXT000115            | Bad Request                                        | Insufficient account balance for transfer and fee amount.                                                               | Saldo de conta insuficiente para a transferência e a taxa                                                              |
| 400                      | PXT000128            | Bad Request                                        | Pix key \{pix_key\} sent does match inquiry pix key. Verify if end_to_end_id sent is correct                            | Chave Pix \{pix_key\} enviada não condiz com consulta. Verifique se end_to_end_id enviado está correto                 |
| 400                      | PXT000109            | Bad Request                                        | request_control_key \{request_control_key\} already in use                                                              | request_control_key \{request_control_key\} já utilizada                                                               |
| 400                      | PXT000061            | Bad Request                                        | End to end id invalid. A pix transfer with the end to end id \{end_to_end\} has already been registered!                | End to end id inválido. Uma transação pix com o identificador único \{end_to_end\} já foi registrada!                  |
| 400                      | PXT000129            | SPI Error message                                  | Message rejected by SPI-ICOM                                                                                            | Mensagem rejeitada pela SPI-ICOM                                                                                       |
| 408                      | PXT000130            | SPI Timeout Control                                | SPI Timeout Control                                                                                                     | Controle de timeout no SPI                                                                                             |
| 400                      | PXT000131            | Receiver Internal Error                            | Cancelled transaction due to receiver's internal error                                                                  | Transação interrompida devido a erro no PSP do Recebedor                                                               |
| 400                      | PXT000132            | Invalid Target Account Number                      | Target account number is invalid                                                                                        | Número da conta de destino é inexistente ou inválido                                                                   |
| 400                      | PXT000133            | Blocked Target Account                             | Target account is blocked.                                                                                              | A conta de destino encontra-se bloqueada.                                                                              |
| 400                      | PXT000134            | Closed Target Account                              | Target account is closed.                                                                                               | A conta de destino encontra-se encerrada.                                                                              |
| 400                      | PXT000135            | Unsupported Transaction                            | Unsupported transaction for given target account.                                                                       | A conta de destino não suporta este tipo de transação.                                                                 |
| 400                      | PXT000136            | Invalid Participant                                | SPI participant is not PSP settler agent of payer nor receiver.                                                         | Participante direto do SPI não é liquidante do PSP do Pagador / Recebedor.                                             |
| 400                      | PXT000137            | Zero Value Payment Order                           | Zero value payment order.                                                                                               | Ordem de pagamento com valor zero.                                                                                     |
| 400                      | PXT000138            | Insufficient Funds                                 | Insufficient funds in PI account from payer.                                                                            | Saldo insuficiente na conta PI do pagador.                                                                             |
| 400                      | PXT000139            | Return Value Too Great                             | Return value greater than corresponding payment order.                                                                  | Valor de devolução acima do valor de pagamento correspondente.                                                         |
| 400                      | PXT000140            | Invalid Transactions Number                        | Invalid transactions number.                                                                                            | Quantidade de transações inválida.                                                                                     |
| 400                      | PXT000141            | Unrelated Beneficiary Document Number              | Beneficiary document number is not that of target account owner.                                                        | CPF/CNPJ do usuário recebedor não é compatível com o titular da conta de destino.                                      |
| 400                      | PXT000142            | Invalid Beneficiary Document Number                | Invalid beneficiary document number                                                                                     | CPF/CNPJ da conta de destino está incorreto.                                                                           |
| 400                      | PXT000143            | Incorrect Message Element                          | Incorrect message element.                                                                                              | Elemento da mensagem incorreto.                                                                                        |
| 403                      | PXT000144            | Rejected Payment Order                             | Beneficiary's PSP has rejected payment order.                                                                           | Ordem de pagamento foi rejeitada pelo banco recebedor.                                                                 |
| 403                      | PXT000145            | Unauthorized Payer                                 | Signing participant is unauthorized to make a payment order for paying account.                                         | Participante que assinou a mensagem não é autorizado a realizar a operação na conta PI debitada.                       |
| 400                      | PXT000146            | Invalid Datetime                                   | Invalid datetime for message delivery.                                                                                  | Data e Hora do envio da mensagem inválida.                                                                             |
| 400                      | PXT000147            | Generic Error                                      | Error while processing payment (generic error).                                                                         | Erro no processamento do pagamento (erro genérico).                                                                    |
| 400                      | PXT000148            | Bad Format Operation Identifier                    | Badly formatted operation's identifier.                                                                                 | Identificador da operação mal formatado.                                                                               |
| 400                      | PXT000149            | Invalid Payer ISPB                                 | Invalid or non-existent payer's PSP ISPB number.                                                                        | Número ISPB do PSP do Pagador é inválido ou inexistente.                                                               |
| 400                      | PXT000150            | Invalid Beneficiary ISPB                           | Invalid or non-existent beneficiary's PSP ISPB number.                                                                  | Número ISPB do banco recebedor é inválido ou inexistente.                                                              |
| 400                      | PXT000151            | Incorrect Type                                     | Incorrect type for target account.                                                                                      | Tipo incorreto para a conta transacional especificada.                                                                 |
| 400                      | PXT000152            | Repeated End-to-End ID Error                       | The end_to_end_id was already used                                                                                      | O end_to_end_id já foi utilizado                                                                                       |
| 400                      | PXT000153            | Invalid Target Account Type                        | The target account type cannot receive PIX transactions                                                                 | O tipo de conta destino não pode receber transações PIX                                                                |
| 400                      | PXT000154            | Invalid ISPB                                       | Invalid or non-existent ISPB number.                                                                                    | Número ISPB é inválido ou inexistente.                                                                                 |
| 400                      | PXT000155            | Amount too Great                                   | Amount too great for credited account.                                                                                  | Valor de pagamento/devolução acima do permitido para a conta de destino creditada.                                     |
| 400                      | PXT000156            | QR Code Rejected                                   | QR Code rejected by beneficiary's PSP.                                                                                  | QR Code rejeitado pelo PSP do usuário recebedor.                                                                       |
| 503                      | PXT000157            | Bacen Service Unavailable Error                    | Could not send the message to ICOM after 3 retries                                                                      | Não pode enviar a mensagem para a ICOM depois de 3 tentativas                                                          |
| 400                      | PXT000158            | Invalid Amount                                     | Paid amount diverges from expected amount of \{expected_amount\}                                                        | O valor do pagamento diverge do valor esperado de \{expected_amount\}                                                  |
| 400                      | PXT000159            | QR code inactive                                   | QR code is not active at the time of payment                                                                            | QR code não está ativo no instante do pagamento                                                                        |
| 400                      | PXT000188            | Session ID needed | A session_id must be provided token                      | Uma session_id deve ser fornecida                |

---

# Aprovar Agendamento de Transação Pix com Autenticação de Dois Fatores

URL: /documentation/baas/pix/agendamento/aprovacao_de_agendamento_2fa

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_schedule/ SCHEDULE_KEY /validate_token
MÉTODO PUT

### Path Params

| Campo          | Tipo   | Descrição                                    | Caracteres |
|----------------|--------|----------------------------------------------|------------|
| `account_key`  | uuidv4 | Chave única de identificação da conta.       | 36         |
| `schedule_key` | uuidv4 | Chave única de identificação do agendamento. | 36         |

## Autenticação via Email e SMS

Request Body

```json
{
  "token": "329adf"
}
```

## Autenticação via Dispositivo

Para aprovar e finalizar a autenticação via dispositivo, a requisição deve ser enviada com um payload vazio. A validação ocorre internamente, sem necessidade de informações adicionais no corpo da requisição. É importante destacar que este endpoint só deve ser utilizado após a [solicitação de agendamento](./solicitacao_de_agendamento_2fa.md) ter sido iniciada.

Request Body

```json
{

}
```

### Body Params

| Campo   | Tipo   | Descrição                                                                                                                              | Caracteres |
|---------|--------|----------------------------------------------------------------------------------------------------------------------------------------|------------|
| `token` | string | Código de autenticação enviado ao aprovador de movimentações da conta **obrigatório para TFA via SMS ou e-mail**                       | 6          |

## Response

STATUS 201

Response Body: Agendamento Aprovado

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "schedule_key": "f64b3fa7-d09d-4927-ad4f-b966df9fb153",
  "schedule_status": "scheduled",
  "schedule_date": "2024-12-31",
  "created_at": "2023-03-13T19:00:28.440Z"
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                           | Descrição (eng)<br/>`description`                                       | Descrição (ptbr)<br/>`translation`                                         |
|--------------------------|----------------------|----------------------------------------------|-------------------------------------------------------------------------|----------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                  | schema error description                                                | Schema Inválido                                                            |
| 404                      | PSC000001            | Account not Found                            | Account was not found                                                   | Conta não encontrada                                                       |
| 403                      | PSC000012            | User is not allowed to do this transaction   | User is not allowed to do this transaction                              | Usuário não tem autorização para fazer essa transação                      |
| 404                      | PSC000025            | PixSchedule not Found                        | PixSchedule was not found                                               | PixSchedule não encontrada                                                 |
| 400                      | PSC000048            | Error occurred while sending token           | An unexpected error occurred while sending token                        | Um erro inesperado ocorreu ao tentar enviar token                          |
| 400                      | PSC000049            | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida                 |
| 400                      | PSC000052            | Incorrect Token                              | Token sent does not match expected                                      | Token enviado não condiz com o esperado                                    |
| 400                      | PSC000053            | Error Sending Token                          | An error occurred while resending token and its being investigated      | Um erro ocorreu ao reenviar token e está sendo investigado                 |
| 400                      | PSC000054            | Invalid Schedule Date                        | Schedule must be approved before the scheduled date                     | Agendamento deve ser aprovado em data anterior à programada para transação |
| 400                      | PSC000055            | Bad Request                                  | Schedule cannot be approved in current status                           | Agendamento pix não pode ser aprovado no status atual                      |
| 400                      | PSC000058            | Token Required                               | A token is required for SMS or email validation.                                                         | Um token é necessário para validação via SMS ou email.                                                     |

---

# Aprovar Agendamento em Lote de Transação Pix com Autenticação de Dois Fatores

URL: /documentation/baas/pix/agendamento/batch/aprovacao_de_agendamento_em_lote_2fa

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_schedule_batch/ SCHEDULE_BATCH_KEY /validate_token
MÉTODO PUT

### Path Params

| Campo                | Tipo   | Descrição                                            | Caracteres |
|----------------------|--------|------------------------------------------------------|------------|
| `account_key`        | uuidv4 | Chave única de identificação da conta.               | 36         |
| `schedule_batch_key` | uuidv4 | Chave única de identificação do agendamento em lote. | 36         |

## Autenticação via Email e SMS

Request Body

```json
{
  "token": "329adf"
}
```

## Autenticação via Dispositivo

Para aprovar e finalizar a autenticação via dispositivo, a requisição deve ser enviada com um payload vazio. A validação ocorre internamente, sem necessidade de informações adicionais no corpo da requisição. É importante destacar que este endpoint só deve ser utilizado após a [solicitação de agendamento em lote](./solicitacao_de_agendamento_em_lote_2fa.md) ter sido iniciada.

Request Body

```json
{

}
```

### Body Params

| Campo   | Tipo   | Descrição                                                                                                                              | Caracteres |
|---------|--------|----------------------------------------------------------------------------------------------------------------------------------------|------------|
| `token` | string | Código de autenticação enviado ao aprovador de movimentações da conta **obrigatório para TFA via SMS ou e-mail**                       | 6          |

## Response

STATUS 201

Response Body: Agendamento Aprovado

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "schedule_batch_key": "f64b3fa7-d09d-4927-ad4f-b966df9fb153",
  "schedule_batch_status": "approved",
  "created_at": "2023-03-13T19:00:28.440Z"
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                           | Descrição (eng)<br/>`description`                                       | Descrição (ptbr)<br/>`translation`                                                 |
|--------------------------|----------------------|----------------------------------------------|-------------------------------------------------------------------------|------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                  | schema error description                                                | Schema Inválido                                                                    |
| 404                      | PSC000001            | Account not Found                            | Account was not found                                                   | Conta não encontrada                                                               |
| 403                      | PSC000012            | User is not allowed to do this transaction   | User is not allowed to do this transaction                              | Usuário não tem autorização para fazer essa transação                              |
| 404                      | PSC000042            | Schedule Batch not Found                     | ScheduleBatch was not found                                             | ScheduleBatch não encontrada                                                       |
| 400                      | PSC000048            | Error occurred while sending token           | An unexpected error occurred while sending token                        | Um erro inesperado ocorreu ao tentar enviar token                                  |
| 400                      | PSC000049            | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida                         |
| 400                      | PSC000052            | Incorrect Token                              | Token sent does not match expected                                      | Token enviado não condiz com o esperado                                            |
| 400                      | PSC000053            | Error Sending Token                          | An error occurred while resending token and its being investigated      | Um erro ocorreu ao reenviar token e está sendo investigado                         |
| 400                      | PSC000054            | Invalid Schedule Date                        | Schedule must be approved before the scheduled date                     | Agendamento deve ser aprovado em data anterior à programada para transação         |
| 400                      | PSC000055            | Bad Request                                  | Schedule cannot be approved in current status                           | Agendamento pix não pode ser aprovado no status atual                              |
| 400                      | PSC000056            | Bad Request                                  | Schedule Batch cannot be approved in current status                     | Lote de agendamento pix não pode ser aprovado no status atual                      |
| 400                      | PSC000057            | Invalid Schedule Date                        | Batch Schedule must be approved before the earliest scheduled date      | Lote de agendamento deve ser aprovado em data anterior à programada para transação |
| 400                      | PSC000058            | Token Required                               | A token is required for SMS or email validation.                                                         | Um token é necessário para validação via SMS ou email.                                                     |

---

# Cancelar Agendamento de Transação Pix em Lote

URL: /documentation/baas/pix/agendamento/batch/cancelamento_de_agendamento_em_lote

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_schedule_batch/ SCHEDULE_BATCH_KEY /cancel
MÉTODO PATCH

### Path Params

| Campo                | Tipo   | Descrição                                           | Caracteres |
|----------------------|--------|-----------------------------------------------------|------------|
| `account_key`        | uuidv4 | Chave única de identificação da conta.              | 36         |
| `schedule_batch_key` | uuidv4 | Chave única de identificação do lote de agendamento | 36         |

### Response

STATUS 200

Response Body: Agendamento Cancelado

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "schedule_batch_key": "f64b3fa7-d09d-4927-ad4f-b966df9fb153",
  "schedule_batch_status": "cancelled",
  "created_at": "2023-03-13T19:00:28.440Z"
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                  | Descrição (eng)<br/>`description`                                                                                                    | Descrição (ptbr)<br/>`translation`                                                                                                          |
|--------------------------|----------------------|-----------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                         | schema error description                                                                                                             | Schema Inválido                                                                                                                             |
| 404                      | PSC000001            | Account not Found                                   | Account was not found                                                                                                                | Conta não encontrada                                                                                                                        |
| 403                      | PSC000012            | User is not allowed to do this transaction          | User is not allowed to do this transaction                                                                                           | Usuário não tem autorização para fazer essa transação                                                                                       |
| 404                      | PSC000025            | PixSchedule not Found                               | PixSchedule was not found                                                                                                            | PixSchedule não encontrada                                                                                                                  |
| 400                      | PSC000027            | Bad Request                                         | Action cannot be taken place as there is currently a pending transfer in progress                                                    | A ação não pôde ser completada como há uma transferência pendente                                                                           |
| 404                      | PSC000042            | Schedule Batch not Found                            | ScheduleBatch was not found                                                                                                          | ScheduleBatch não encontrada                                                                                                                |
| 400                      | PSC000043            | Schedule Batch could not be canceled                | ScheduleBatch could not be canceled due to current date being equal or after earliest schedule date. Cancel pix_schedules one by one | ScheduleBatch não pode ser cancelada devido a data atual ser superior ou igual à menor schedule_date. Cancele pix_schedules individualmente |
| 400                      | PSC000044            | Bad Request                                         | Schedule Batch cannot be cancelled in current status                                                                                 | Agendamento pix não pode ser cancelado no status atual                                                                                      |

---

# Listar Agendamentos de um Lote de Agendamento

URL: /documentation/baas/pix/agendamento/batch/consulta_de_agendamentos_de_um_lote

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_schedule_batch/ SCHEDULE_BATCH_KEY /pix_schedules
MÉTODO GET

### Path Params

| Campo                | Tipo   | Descrição                                             | Caracteres |
|----------------------|--------|-------------------------------------------------------|------------|
| `account_key`        | uuidv4 | Chave única de identificação da conta.                | 36         |
| `schedule_batch_key` | uuidv4 | Chave única de identificação do lote de agendamentos. | 36         |

### Query Params

| Campo                 | Tipo    | Descrição                                                               | Caracteres         |
|-----------------------|---------|-------------------------------------------------------------------------|--------------------|
| `request_control_key` | uuidv4  | Chave única de identificação da request utilizada pelo cliente.         | 36                 |
| `schedule_status`     | string  | Status do agendamento. Pode ser enviado em forma de lista.              |  **[Enumerador schedule_status](#enumerador-schedule_status)** |
| `page`                | integer | Número da página requisitada. 1 por padrão                              |                    |
| `page_size`           | integer | Tamanho da página requisitada na consulta. 30 por padrão e valor máximo | Valor máximo de 30 |

### Enumerador schedule_status

| Enumerador                 | Descrição                                                                                      |
|----------------------------|------------------------------------------------------------------------------------------------|
| **scheduled**              | Transação agendada                                                                             |
| **sent**                   | Agendamento concluído e enviado com sucesso. Estado final                                      |
| **rejected**               | Agendamento rejeitado durante criação ou execução. Estado final                                |
| **cancelled**              | Agendamento cancelado por solicitação de cliente. Estado final                                 |
| **pending_2fa_approval**   | Pendente de aprovação por autenticação de dois fatores                                         |
| **pending_creation**       | Agendamento em processo de criação (Estado transitório para agendamento em lote)               |
| **waiting_batch_approval** | Agendamento criado e vinculado a um lote aguardando aprovação por autenticação de dois fatores |

### Response

STATUS 200

Response Body

```json
{
  "data": [
    {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "schedule_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "schedule_status": "scheduled",
      "schedule_date": "2024-12-31",
      "created_at": "2023-03-13T19:00:28.440Z"
    },
    {
      "request_control_key": "bf6b0a4b-c7a5-446b-9dad-1ae10b25342a",
      "schedule_key": "2479a5cd-079e-4d72-bf4e-16a695bda45e",
      "schedule_status": "cancelled",
      "schedule_date": "2024-12-31",
      "created_at": "2023-03-13T19:00:28.440Z"
    },
    {
      "request_control_key": "9d36c03e-2db7-4c90-87ed-6c9ddb3c03c7",
      "schedule_key": "5d6b14b9-053f-408c-bcd7-61ecf9224f2c",
      "schedule_status": "rejected",
      "schedule_date": "2024-12-31",
      "created_at": "2023-03-13T19:00:28.440Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "rows_per_page": 30
  }
}

```

---

# Listar Lotes de Agendamento de uma conta

URL: /documentation/baas/pix/agendamento/batch/consulta_de_agendamentos_em_lote_de_uma_conta

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_schedule_batches
MÉTODO GET

### Path Params

| Campo         | Tipo   | Descrição                              | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36         |

### Query Params

| Campo                   | Tipo    | Descrição                                                               | Caracteres         |
|-------------------------|---------|-------------------------------------------------------------------------|--------------------|
| `request_control_key`   | uuidv4  | Chave única de identificação da request utilizada pelo cliente.         | 36                 |
| `schedule_batch_status` | string  | Status do lote de agendamento. Pode ser enviado em forma de lista.      | 20                 |
| `page`                  | integer | Número da página requisitada. 1 por padrão                              |                    |
| `page_size`             | integer | Tamanho da página requisitada na consulta. 30 por padrão e valor máximo | Valor máximo de 30 |

### Response

STATUS 200

Response Body

```json
{
  "data": [
    {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "schedule_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "schedule_batch_status": "approved",
      "created_at": "2021-10-22T20:30:23.459Z"
    },
    {
      "request_control_key": "bf6b0a4b-c7a5-446b-9dad-1ae10b25342a",
      "schedule_batch_key": "2479a5cd-079e-4d72-bf4e-16a695bda45e",
      "schedule_batch_status": "cancelled",
      "created_at": "2021-10-22T20:30:23.459Z"
    },
    {
      "request_control_key": "9d36c03e-2db7-4c90-87ed-6c9ddb3c03c7",
      "schedule_batch_key": "5d6b14b9-053f-408c-bcd7-61ecf9224f2c",
      "schedule_batch_status": "rejected",
      "created_at": "2021-10-22T20:30:23.459Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "rows_per_page": 30
  }
}

```

# Consultar Lote de Agendamento de uma conta

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_schedule_batch/ SCHEDULE_BATCH_KEY
MÉTODO GET

### Path Params

| Campo                | Tipo   | Descrição                                             | Caracteres |
|----------------------|--------|-------------------------------------------------------|------------|
| `account_key`        | uuidv4 | Chave única de identificação da conta.                | 36         |
| `schedule_batch_key` | uuidv4 | Chave única de identificação do lote de agendamentos. | 36         |

### Response

STATUS 200

Response Body

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "schedule_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "schedule_batch_status": "approved",
  "created_at": "2021-10-22T20:30:23.459Z"
}
```

---

# Solicitar Agendamento de Transação Pix em Lote

URL: /documentation/baas/pix/agendamento/batch/solicitacao_de_agendamento_em_lote

A QI Tech oferece a possibilidade de realizar várias transações agendadas pix com uma única chamada. Nesse sistema os
agendamentos são realizados de forma assíncrona. Caso na chamada inicial seja retornado um **http status 4xx**, nenhum
dos agendamentos será realizado. Após a solicitação, o parceiro integrador receberá um webhook para cada **pix_schedule
**
rejeitado no ato da criação.

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_schedule_batch
MÉTODO POST

```json
{
  "request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
  "pix_schedules": [
    {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "pix_transfer_type": "key",
      "target_pix_key": "target_pix_key@email.com",
      "transaction_amount": 500.65,
      "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
      "pix_message": "Ola Mundo",
      "schedule_date": "2024-12-01"
    },
    {
      "request_control_key": "c6804f35-101e-4702-8fbc-c2dbc4c2caea",
      "pix_transfer_type": "manual",
      "target_account": {
        "account_branch": "0001",
        "account_digit": "3",
        "account_number": "12345678",
        "owner_document_number": "32402502000135",
        "owner_name": "Qi Tech",
        "account_type": "checking_account",
        "ispb": "32402502"
      },
      "transaction_amount": 500.65,
      "pix_message": "Ola Mundo",
      "schedule_date": "2024-12-01"
    },
    {
      "request_control_key": "a6804f42-101e-4702-8fbc-c2dbc4c2caed",
      "pix_transfer_type": "static_qr_code",
      "transaction_amount": 500.65,
      "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
      "receiver_conciliation_id": "REC00000000000000000000009459463343",
      "target_pix_key": "target_pix_key@email.com",
      "pix_message": "Ola Mundo"
    }
  ]
}
```

## Path Params

| Campo         | Tipo   | Descrição                              | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36         |

### Body Params

| Campo                   | Tipo   | Descrição                                                                          | Caracteres                                               |
|-------------------------|--------|------------------------------------------------------------------------------------|----------------------------------------------------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36                                                       | 
| `pix_schedules` *       | array  | Lista de objetos pix_schedule vinculados ao lote.                                  | lista de **[Objeto pix_schedule](#objeto-pix_schedule)** |

### Objeto pix_schedule

| Campo                      | Tipo       | Descrição                                                                                                                                                                                                                                         | Caracteres                                                        |
|----------------------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `request_control_key`*     | uuidv4     | Chave única de identificação da request utilizada pelo cliente no formato uuid v4.                                                                                                                                                                | 36                                                                | 
| `pix_transfer_type`*       | enumerator | Tipo de transferência Pix.                                                                                                                                                                                                                        | **[Enumerador pix_transfer_type](#enumerador-pix_transfer_type)** |
| `target_pix_key`           | string     | Chave pix da conta a ser enviada a transação.                                                                                                                                                                                                     | 100                                                               |
| `receiver_conciliation_id` | string     | Identicação de conciliação do recebedor.                                                                                                                                                                                                          | 35                                                                |
| `target_account` *         | Object     | Conta destino - Só deve ser enviada em transferências com `pix_transfer_type` do tipo **manual**.                                                                                                                                                 | **[Objeto target_account](#objeto-target_account)**               | 10 |
| `transaction_amount`*      | number     | Valor da transferência.                                                                                                                                                                                                                           | 10                                                                |
| `end_to_end_id`            | string     | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na consulta de chave Pix. Só deve ser enviado se o `pix_transfer_type` for **key**, **static_qr_code** ou **static_qr_code**. | 32                                                                |
| `pix_message`              | string     | Mensagem a ser enviada junto à transferência Pix.                                                                                                                                                                                                 | 140                                                               |

### Objeto target_account

| Campo                     | Tipo       | Descrição                                           | Caracteres                                              |
|---------------------------|------------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string     | Agência da conta.                                   | 6                                                       |
| `account_digit` *         | string     | Dígito da conta.                                    | 1                                                       |
| `account_number` *        | string     | Número da conta.                                    | 20                                                      |
| `owner_document_number` * | string     | CPF ou CNPJ (apenas números) do titular da conta.   | 14                                                      |
| `owner_name` *            | string     | Nome do titular da conta.                           | 150                                                     |
| `account_type`*           | enumerator | Tipo da conta.                                      | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string     | Base no CNPJ da instituição financeira (8 dígitos). | 8                                                       |

### Enumerador account_type

| Enumerador           | Descrição           |
|----------------------|---------------------|
| **checking_account** | Conta Corrente      |
| **salary_account**   | Conta Salário       |
| **saving_account**   | Conta Poupança      |
| **payment_account**  | Conta de Pagamentos |

### Enumerador pix_transfer_type

| Enumerador          | Descrição                                                                                                                                                                                                                 |
|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **manual**          | Pix utilizando os dados da conta destino. Obrigatório enviar `target_account`                                                                                                                                             |
| **key**             | Pix utilizando uma chave pix. Obrigatório enviar `target_pix_key`. Recomendado enviar `end_to_end_id` da [consulta de chave](/documentation/pix_indireto/movimentacoes/consultar_chave_pix) pix caso tenha sido realizada |
| **static_qr_code**  | Pix utilizando um QR code estático. Obrigatório enviar o `end_to_end_id` retornado na [decodificação do QR code](/documentation/pix/decodificar_qr_code)                                                                  |
| **dynamic_qr_code** | Pix utilizando um QR code dinâmico. Obrigatório enviar o `end_to_end_id` retornado na [decodificação do QR code](/documentation/pix/decodificar_qr_code)                                                                  |

## Response

STATUS 201

Response Body: Agendamento em lote Aprovado

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "schedule_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "schedule_batch_status": "approved",
  "created_at": "2021-10-22T20:30:23.459Z"
}
```

### Enumerador schedule_batch_status

| Enumerador               | Descrição                                                                  |
|--------------------------|----------------------------------------------------------------------------|
| **created**              | Agendamento em lote criado                                                 |
| **approved**             | Agendamento em lote aprovado                                               |
| **rejected**             | Agendamento em lote rejeitado                                              |
| **pending_2fa_approval** | Agendamento em lote pendente de aprovação por autenticação de dois fatores |

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                  | Descrição (eng)<br/>`description`                                                                                         | Descrição (ptbr)<br/>`translation`                                                                                                |
|--------------------------|----------------------|-----------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                         | schema error description                                                                                                  | Schema Inválido                                                                                                                   |
| 404                      | PSC000001            | Account not Found                                   | Account was not found                                                                                                     | Conta não encontrada                                                                                                              |
| 406                      | PSC000002            | Invalid Uuid                                        | key was not accepted for not being a valid uuid v4 string                                                                 | key não foi aceito por não ser uma palavra uuid v4 válida                                                                         |
| 400                      | PSC000003            | Bad Request                                         | pix_message can not be longer than 140 characters                                                                         | pix_message não pode ser maior que 140 caracteres                                                                                 |
| 400                      | PSC000004            | Bad Request                                         | Emoji not allowed in pix message                                                                                          | Emoji não é permitido na mensagem pix                                                                                             |
| 406                      | PSC000005            | Invalid Transaction Amount                          | Transaction amount of transaction_amount is not valid. It must be a positive value with at maximum 2 decimal places       | O valor de transação transaction_amount não é válido. Deve ser um valor positivo com no máximo duas casas decimais                |
| 406                      | PSC000006            | Invalid end_to_end_id                               | The end_to_end_id sent end_to_end_id is not valid                                                                         | O end_to_end_id enviado end_to_end_id não é válido                                                                                |
| 400                      | PSC000007            | Invalid date format                                 | Dates must be sent using format YYYY-MM-DD                                                                                | Datas devem ser enviadas no formato YYYY-MM-DD                                                                                    |
| 400                      | PSC000008            | Invalid Schedule Date                               | Schedule date must be after current date for UTC-3                                                                        | Data de agendamento deve ser após a data atual em UTC-3                                                                           |
| 400                      | PSC000009            | Account is Closed                                   | Account is closed                                                                                                         | Conta está fechada                                                                                                                |
| 400                      | PSC000010            | Account is Blocked                                  | Account is blocked                                                                                                        | Conta está bloqueada                                                                                                              |
| 422                      | PSC000011            | Invalid Account Type                                | Pix is not yet implemented for non-checking or non-escrow account types                                                   | Transações Pix não estão implementadas para conta que não sejam escrow ou livres                                                  |
| 403                      | PSC000012            | User is not allowed to do this transaction          | User is not allowed to do this transaction                                                                                | Usuário não tem autorização para fazer essa transação                                                                             |
| 400                      | PSC000013            | Bad Request                                         | For Manual Pix Transfer Type a target account must be provided                                                            | Para transação pix do tipo manual, uma conta destino deve ser fornecida                                                           |
| 404                      | PSC000014            | Inquiry Not Found                                   | Pix key inquiry was not found                                                                                             | Pesquisa de chave pix não encontrada                                                                                              |
| 400                      | PSC000015            | Bad Request                                         | Pix key sent does match inquiry pix key. Verify if end_to_end_id sent is correct                                          | Chave Pix enviada não condiz com consulta. Verifique se end_to_end_id enviado está correto                                        |
| 404                      | PSC000016            | Account not found                                   | Nonexistent account in destination financial institution                                                                  | Conta inexistente na instituição financeira de destino                                                                            |
| 400                      | PSC000017            | Target Account and Source Account must be different | Target Account must not be the same as Source Account                                                                     | A conta de destino não pode ser a mesma da conta de origem                                                                        |
| 409                      | PSC000018            | Bad Request                                         | request_control_key request_control_key already in use                                                                    | request_control_key request_control_key já utilizada                                                                              |
| 400                      | PSC000019            | Invalid Target                                      | Account does not have permission to transfer to the given target account                                                  | A conta não possui permissão para realizar transferências para a conta enviada                                                    |
| 404                      | PSC000020            | Decode Inquiry Not Found                            | QR Code decode inquiry not found                                                                                          | Pesquisa e decodificação de QR code não encontrada                                                                                |
| 400                      | PSC000021            | Bad Request                                         | Receiver Conciliation Id sent does match decode inquiry receiver_conciliation_id. Verify if end_to_end_id sent is correct | Identificador de transação enviado não condiz com consulta. Verifique se end_to_end_id enviado está correto                       |
| 400                      | PSC000022            | Bad Request                                         | Dynamic Instant QR codes cannot be scheduled for payment                                                                  | Pagamentos de vencimento instantâneo não podem ter pagamento agendado                                                             |
| 400                      | PSC000023            | Bad Request                                         | Schedule Date sent is after max payment date for target qr code                                                           | Data de agendamento enviada é após a data máxima de pagamento para o qr code enviado                                              |
| 400                      | PSC000024            | Bad Request                                         | Pix transfer type sent does match decode inquiry qr code type. Verify if end_to_end_id sent is correct                    | Tipo de transação pix enviado enviado não condiz com tipo de qr code da consulta. Verifique se end_to_end_id enviado está correto |
| 400                      | PSC000040            | Empty pix-schedule list received                    | A list of pix schedules must be provided                                                                                  | Uma lista de agendamentos pix deve ser fornecida                                                                                  |
| 409                      | PSC000041            | Bad Request                                         | One or more request_control_key already in use                                                                            | Uma ou mais request_control_key já está sendo utilizada                                                                           |
| 403                      | PSC000045            | Requester not allowed to access this endpoint       | Requester has no permission to perform pix transfers on this endpoint                                                     | Requester não possui permissão de realizar transações pix através deste endpoint                                                  |

---

# Solicitar Agendamento de Transação Pix em Lote

URL: /documentation/baas/pix/agendamento/batch/solicitacao_de_agendamento_em_lote_2fa

A QI Tech oferece a possibilidade de realizar várias transações agendadas pix com uma única chamada. Nesse sistema os
agendamentos são realizados de forma assíncrona. Caso na chamada inicial seja retornado um **http status 4xx**, nenhum
dos agendamentos será realizado. Após a solicitação, o parceiro integrador receberá um webhook para cada **pix_schedule
** rejeitado no ato da criação.

Neste tipo de agendamento, é necessário a confirmação da programação de pagamento via token enviado à pessoa com poderes
de aprovação de movimentação na conta credora.

A solicitação de agendamento Pix em lote por parceiros integradores configurados para a utilização de autenticação de
dois
fatores é realizada de forma similar ao descrito
em [solicitar agendamento de_transação_pix_em_lote](/documentation/baas/pix/agendamento/solicitacao_de_agendamento_em_lote).
A diferença
ocorre na adição do objeto `tfa_info`, contento informações sobre o aprovador da transferência e a forma de contato, e o
status de uma solicitação bem sucedida que será sempre **pending_2fa_approval**.

O evento de notificação para o envio de `token` ao aprovador é **baas.token_validation.pix_transfer.schedule.batch**. É
possível [personalizar](/documentation/notificacoes/template) a mensagem enviada.

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_schedule_batch
MÉTODO POST

## Autenticação via Email e SMS

Request Body: Agendamento em Lote com TFA por SMS ou Email

```json
{
  "request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  },
  "pix_schedules": [
    {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "pix_transfer_type": "key",
      "target_pix_key": "target_pix_key@email.com",
      "transaction_amount": 500.65,
      "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
      "pix_message": "Ola Mundo",
      "schedule_date": "2024-12-01"
    },
    {
      "request_control_key": "c6804f35-101e-4702-8fbc-c2dbc4c2caea",
      "pix_transfer_type": "manual",
      "target_account": {
        "account_branch": "0001",
        "account_digit": "3",
        "account_number": "12345678",
        "owner_document_number": "32402502000135",
        "owner_name": "Qi Tech",
        "account_type": "checking_account",
        "ispb": "32402502"
      },
      "transaction_amount": 500.65,
      "pix_message": "Ola Mundo",
      "schedule_date": "2024-12-01"
    },
    {
      "request_control_key": "a6804f42-101e-4702-8fbc-c2dbc4c2caed",
      "pix_transfer_type": "static_qr_code",
      "transaction_amount": 500.65,
      "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
      "receiver_conciliation_id": "REC00000000000000000000009459463343",
      "target_pix_key": "target_pix_key@email.com",
      "pix_message": "Ola Mundo"
    }
  ]
}
```

## Autenticação via Dispositivo

Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`.

Request Body: Agendamento em Lote com TFA por Dispositivo

```json
{
  "request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
    "contact_type": "device"
  },
  "pix_schedules": [
    {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "pix_transfer_type": "key",
      "target_pix_key": "target_pix_key@email.com",
      "transaction_amount": 500.65,
      "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
      "pix_message": "Ola Mundo",
      "schedule_date": "2024-12-01"
    },
    {
      "request_control_key": "c6804f35-101e-4702-8fbc-c2dbc4c2caea",
      "pix_transfer_type": "manual",
      "target_account": {
        "account_branch": "0001",
        "account_digit": "3",
        "account_number": "12345678",
        "owner_document_number": "32402502000135",
        "owner_name": "Qi Tech",
        "account_type": "checking_account",
        "ispb": "32402502"
      },
      "transaction_amount": 500.65,
      "pix_message": "Ola Mundo",
      "schedule_date": "2024-12-01"
    },
    {
      "request_control_key": "a6804f42-101e-4702-8fbc-c2dbc4c2caed",
      "pix_transfer_type": "static_qr_code",
      "transaction_amount": 500.65,
      "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
      "receiver_conciliation_id": "REC00000000000000000000009459463343",
      "target_pix_key": "target_pix_key@email.com",
      "pix_message": "Ola Mundo"
    }
  ]
}
```

## Path Params

| Campo         | Tipo   | Descrição                              | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36         |

### Body Params

| Campo                   | Tipo   | Descrição                                                                          | Caracteres                                               |
|-------------------------|--------|------------------------------------------------------------------------------------|----------------------------------------------------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36                                                       | 
| `pix_schedules` *       | array  | Lista de objetos pix_schedule vinculados ao lote.                                  | lista de **[Objeto pix_schedule](#objeto-pix_schedule)** |
| `tfa_info`*             | Object | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato.    | **[Objeto tfa_info](#objeto-tfa_info)**                  |

### Objeto tfa_info

| Campo                       | Tipo   | Descrição                                                                                                                        | Caracteres |
|-----------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------|------------|
| `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta.                                                                               | 11         |
| `session_id`                | string | Chave única de identificação da sessão do dispositivo no formato UUID v4 (obrigatório para TFA via dispositivo).                 | 36         |
| `contact_type`*             | string | Forma de contato com a pessoa aprovadora da conta, podendo ser **sms**, **email** ou **device**                                  |            |

### Objeto pix_schedule

| Campo                      | Tipo       | Descrição                                                                                                                                                                                                                                         | Caracteres                                                        |
|----------------------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `request_control_key`*     | uuidv4     | Chave única de identificação da request utilizada pelo cliente no formato uuid v4.                                                                                                                                                                | 36                                                                | 
| `pix_transfer_type`*       | enumerator | Tipo de transferência Pix.                                                                                                                                                                                                                        | **[Enumerador pix_transfer_type](#enumerador-pix_transfer_type)** |
| `target_pix_key`           | string     | Chave pix da conta a ser enviada a transação.                                                                                                                                                                                                     | 100                                                               |
| `receiver_conciliation_id` | string     | Identicação de conciliação do recebedor.                                                                                                                                                                                                          | 35                                                                |
| `target_account` *         | Object     | Conta destino - Só deve ser enviada em transferências com `pix_transfer_type` do tipo **manual**.                                                                                                                                                 | **[Objeto target_account](#objeto-target_account)**               | 10 |
| `transaction_amount`*      | number     | Valor da transferência.                                                                                                                                                                                                                           | 10                                                                |
| `end_to_end_id`            | string     | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na consulta de chave Pix. Só deve ser enviado se o `pix_transfer_type` for **key**, **static_qr_code** ou **static_qr_code**. | 32                                                                |
| `pix_message`              | string     | Mensagem a ser enviada junto à transferência Pix.                                                                                                                                                                                                 | 140                                                               |

### Objeto target_account

| Campo                     | Tipo       | Descrição                                           | Caracteres                                              |
|---------------------------|------------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string     | Agência da conta.                                   | 6                                                       |
| `account_digit` *         | string     | Dígito da conta.                                    | 1                                                       |
| `account_number` *        | string     | Número da conta.                                    | 20                                                      |
| `owner_document_number` * | string     | CPF ou CNPJ (apenas números) do titular da conta.   | 14                                                      |
| `owner_name` *            | string     | Nome do titular da conta.                           | 150                                                     |
| `account_type`*           | enumerator | Tipo da conta.                                      | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string     | Base no CNPJ da instituição financeira (8 dígitos). | 8                                                       |

### Enumerador account_type

| Enumerador           | Descrição           |
|----------------------|---------------------|
| **checking_account** | Conta Corrente      |
| **salary_account**   | Conta Salário       |
| **saving_account**   | Conta Poupança      |
| **payment_account**  | Conta de Pagamentos |

### Enumerador pix_transfer_type

| Enumerador          | Descrição                                                                                                                                                                                                                 |
|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **manual**          | Pix utilizando os dados da conta destino. Obrigatório enviar `target_account`                                                                                                                                             |
| **key**             | Pix utilizando uma chave pix. Obrigatório enviar `target_pix_key`. Recomendado enviar `end_to_end_id` da [consulta de chave](/documentation/pix_indireto/movimentacoes/consultar_chave_pix) pix caso tenha sido realizada |
| **static_qr_code**  | Pix utilizando um QR code estático. Obrigatório enviar o `end_to_end_id` retornado na [decodificação do QR code](/documentation/pix/decodificar_qr_code)                                                                  |
| **dynamic_qr_code** | Pix utilizando um QR code dinâmico. Obrigatório enviar o `end_to_end_id` retornado na [decodificação do QR code](/documentation/pix/decodificar_qr_code)                                                                  |

## Response

STATUS 202

Response Body: Agendamento em lote Aprovado

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "schedule_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "schedule_batch_status": "pending_2fa_approval",
  "created_at": "2021-10-22T20:30:23.459Z"
} 
```

### Enumerador schedule_batch_status

| Enumerador               | Descrição                                                                  |
|--------------------------|----------------------------------------------------------------------------|
| **created**              | Agendamento em lote criado                                                 |
| **approved**             | Agendamento em lote aprovado                                               |
| **rejected**             | Agendamento em lote rejeitado                                              |
| **pending_2fa_approval** | Agendamento em lote pendente de aprovação por autenticação de dois fatores |

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                  | Descrição (eng)<br/>`description`                                                                                         | Descrição (ptbr)<br/>`translation`                                                                                                |
|--------------------------|----------------------|-----------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                         | schema error description                                                                                                  | Schema Inválido                                                                                                                   |
| 404                      | PSC000001            | Account not Found                                   | Account was not found                                                                                                     | Conta não encontrada                                                                                                              |
| 406                      | PSC000002            | Invalid Uuid                                        | key was not accepted for not being a valid uuid v4 string                                                                 | key não foi aceito por não ser uma palavra uuid v4 válida                                                                         |
| 400                      | PSC000003            | Bad Request                                         | pix_message can not be longer than 140 characters                                                                         | pix_message não pode ser maior que 140 caracteres                                                                                 |
| 400                      | PSC000004            | Bad Request                                         | Emoji not allowed in pix message                                                                                          | Emoji não é permitido na mensagem pix                                                                                             |
| 406                      | PSC000005            | Invalid Transaction Amount                          | Transaction amount of transaction_amount is not valid. It must be a positive value with at maximum 2 decimal places       | O valor de transação transaction_amount não é válido. Deve ser um valor positivo com no máximo duas casas decimais                |
| 406                      | PSC000006            | Invalid end_to_end_id                               | The end_to_end_id sent end_to_end_id is not valid                                                                         | O end_to_end_id enviado end_to_end_id não é válido                                                                                |
| 400                      | PSC000007            | Invalid date format                                 | Dates must be sent using format YYYY-MM-DD                                                                                | Datas devem ser enviadas no formato YYYY-MM-DD                                                                                    |
| 400                      | PSC000008            | Invalid Schedule Date                               | Schedule date must be after current date for UTC-3                                                                        | Data de agendamento deve ser após a data atual em UTC-3                                                                           |
| 400                      | PSC000009            | Account is Closed                                   | Account is closed                                                                                                         | Conta está fechada                                                                                                                |
| 400                      | PSC000010            | Account is Blocked                                  | Account is blocked                                                                                                        | Conta está bloqueada                                                                                                              |
| 422                      | PSC000011            | Invalid Account Type                                | Pix is not yet implemented for non-checking or non-escrow account types                                                   | Transações Pix não estão implementadas para conta que não sejam escrow ou livres                                                  |
| 403                      | PSC000012            | User is not allowed to do this transaction          | User is not allowed to do this transaction                                                                                | Usuário não tem autorização para fazer essa transação                                                                             |
| 400                      | PSC000013            | Bad Request                                         | For Manual Pix Transfer Type a target account must be provided                                                            | Para transação pix do tipo manual, uma conta destino deve ser fornecida                                                           |
| 404                      | PSC000014            | Inquiry Not Found                                   | Pix key inquiry was not found                                                                                             | Pesquisa de chave pix não encontrada                                                                                              |
| 400                      | PSC000015            | Bad Request                                         | Pix key sent does match inquiry pix key. Verify if end_to_end_id sent is correct                                          | Chave Pix enviada não condiz com consulta. Verifique se end_to_end_id enviado está correto                                        |
| 404                      | PSC000016            | Account not found                                   | Nonexistent account in destination financial institution                                                                  | Conta inexistente na instituição financeira de destino                                                                            |
| 400                      | PSC000017            | Target Account and Source Account must be different | Target Account must not be the same as Source Account                                                                     | A conta de destino não pode ser a mesma da conta de origem                                                                        |
| 409                      | PSC000018            | Bad Request                                         | request_control_key request_control_key already in use                                                                    | request_control_key request_control_key já utilizada                                                                              |
| 400                      | PSC000019            | Invalid Target                                      | Account does not have permission to transfer to the given target account                                                  | A conta não possui permissão para realizar transferências para a conta enviada                                                    |
| 404                      | PSC000020            | Decode Inquiry Not Found                            | QR Code decode inquiry not found                                                                                          | Pesquisa e decodificação de QR code não encontrada                                                                                |
| 400                      | PSC000021            | Bad Request                                         | Receiver Conciliation Id sent does match decode inquiry receiver_conciliation_id. Verify if end_to_end_id sent is correct | Identificador de transação enviado não condiz com consulta. Verifique se end_to_end_id enviado está correto                       |
| 400                      | PSC000022            | Bad Request                                         | Dynamic Instant QR codes cannot be scheduled for payment                                                                  | Pagamentos de vencimento instantâneo não podem ter pagamento agendado                                                             |
| 400                      | PSC000023            | Bad Request                                         | Schedule Date sent is after max payment date for target qr code                                                           | Data de agendamento enviada é após a data máxima de pagamento para o qr code enviado                                              |
| 400                      | PSC000024            | Bad Request                                         | Pix transfer type sent does match decode inquiry qr code type. Verify if end_to_end_id sent is correct                    | Tipo de transação pix enviado enviado não condiz com tipo de qr code da consulta. Verifique se end_to_end_id enviado está correto |
| 400                      | PSC000040            | Empty pix-schedule list received                    | A list of pix schedules must be provided                                                                                  | Uma lista de agendamentos pix deve ser fornecida                                                                                  |
| 409                      | PSC000041            | Bad Request                                         | One or more request_control_key already in use                                                                            | Uma ou mais request_control_key já está sendo utilizada                                                                           |
| 403                      | PSC000045            | Requester not allowed to access this endpoint       | Requester has no permission to perform pix transfers on this endpoint                                                     | Requester não possui permissão de realizar transações pix através deste endpoint                                                  |

---

# Solicitar reenvio de token para um agendamento em lote

URL: /documentation/baas/pix/agendamento/batch/solicitacao_de_reenvio_de_token_para_agendamento_em_lote_2fa

Um novo token será gerado e enviado para o aprovador do agendamento pix. Caso o número limite de tentativas de validação
do token tenha sido excedida, não será permitido o reenvio.

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_schedule_batch/ SCHEDULE_BATCH_KEY /resend_token
MÉTODO PATCH

### Path Params

| Campo                | Tipo   | Descrição                                            | Caracteres |
|----------------------|--------|------------------------------------------------------|------------|
| `account_key`        | uuidv4 | Chave única de identificação da conta.               | 36         |
| `schedule_batch_key` | uuidv4 | Chave única de identificação do agendamento em lote. | 36         |

### Body Params

| Campo          | Tipo       | Descrição                               | Caracteres                                              |
|----------------|------------|-----------------------------------------|---------------------------------------------------------|
| `contact_type` | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** |

:::info Informação
Caso não seja enviado um `contact_type`, o token será enviado da forma solicitada originalmente.
:::

| Enumerador | Descrição                                         |
|------------|---------------------------------------------------|
| **sms**    | Envio por Mensagem de Texto para telefone celular |
| **email**  | Envio por correio eletrônico                      |

## Response

STATUS 202

Response Body: Agendamento em lote Solicitado

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "schedule_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "schedule_batch_status": "pending_2fa_approval",
  "created_at": "2021-10-22T20:30:23.459Z"
} 
```

STATUS 4xx

Response Body: Transferência Rejeitada

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                           | Descrição (eng)<br/>`description`                                       | Descrição (ptbr)<br/>`translation`                                                 |
|--------------------------|----------------------|----------------------------------------------|-------------------------------------------------------------------------|------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                  | schema error description                                                | Schema Inválido                                                                    |
| 404                      | PSC000001            | Account not Found                            | Account was not found                                                   | Conta não encontrada                                                               |
| 403                      | PSC000012            | User is not allowed to do this transaction   | User is not allowed to do this transaction                              | Usuário não tem autorização para fazer essa transação                              |
| 404                      | PSC000042            | Schedule Batch not Found                     | ScheduleBatch was not found                                             | ScheduleBatch não encontrada                                                       |
| 400                      | PSC000049            | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida                         |
| 400                      | PSC000052            | Incorrect Token                              | Token sent does not match expected                                      | Token enviado não condiz com o esperado                                            |
| 400                      | PSC000053            | Error Sending Token                          | An error occurred while resending token and its being investigated      | Um erro ocorreu ao reenviar token e está sendo investigado                         |
| 400                      | PSC000054            | Invalid Schedule Date                        | Schedule must be approved before the scheduled date                     | Agendamento deve ser aprovado em data anterior à programada para transação         |
| 400                      | PSC000055            | Bad Request                                  | Schedule cannot be approved in current status                           | Agendamento pix não pode ser aprovado no status atual                              |
| 400                      | PSC000056            | Bad Request                                  | Schedule Batch cannot be approved in current status                     | Lote de agendamento pix não pode ser aprovado no status atual                      |
| 400                      | PSC000057            | Invalid Schedule Date                        | Batch Schedule must be approved before the earliest scheduled date      | Lote de agendamento deve ser aprovado em data anterior à programada para transação |

---

# Cancelar Agendamento de Transação Pix

URL: /documentation/baas/pix/agendamento/cancelamento_de_agendamento

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_schedule/ SCHEDULE_KEY /cancel
MÉTODO PATCH

### Path Params

| Campo          | Tipo   | Descrição                                   | Caracteres |
|----------------|--------|---------------------------------------------|------------|
| `account_key`  | uuidv4 | Chave única de identificação da conta.      | 36         |
| `schedule_key` | uuidv4 | Chave única de identificação do agendamento | 36         |

### Response

STATUS 200

Response Body: Agendamento Cancelado

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "schedule_key": "f64b3fa7-d09d-4927-ad4f-b966df9fb153",
  "schedule_status": "cancelled",
  "schedule_date": "2024-12-31",
  "created_at": "2023-03-13T19:00:28.440Z"
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                         | Descrição (eng)<br/>`description`                                                 | Descrição (ptbr)<br/>`translation`                                                          |
|--------------------------|----------------------|--------------------------------------------|-----------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                | schema error description                                                          | Schema Inválido                                                                             |
| 404                      | PSC000001            | Account not Found                          | Account was not found                                                             | Conta não encontrada                                                                        |
| 403                      | PSC000012            | User is not allowed to do this transaction | User is not allowed to do this transaction                                        | Usuário não tem autorização para fazer essa transação                                       |
| 404                      | PSC000025            | PixSchedule not Found                      | PixSchedule was not found                                                         | PixSchedule não encontrada                                                                  |
| 400                      | PSC000027            | Bad Request                                | Action cannot be taken place as there is currently a pending transfer in progress | A ação não pôde ser completada como há uma transferência pendente                           |
| 400                      | PSC000028            | Bad Request                                | Pix Schedule cannot be cancelled in current status                                | Agendamento pix não pode ser cancelado no status atual                                      |
| 400                      | PSC000029            | Bad Request                                | The given Pix Schedule is tied to a batch. It cannot be individually cancelled    | O agendamento pix enviado está ligado a um lote. Ela não pode ser individualmente cancelada |

---

# Consultar Agendamento de Transação Pix

URL: /documentation/baas/pix/agendamento/consulta_de_agendamento

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_schedule/ SCHEDULE_KEY
MÉTODO GET

### Path Params

| Campo          | Tipo   | Descrição                                   | Caracteres |
|----------------|--------|---------------------------------------------|------------|
| `account_key`  | uuidv4 | Chave única de identificação da conta.      | 36         |
| `schedule_key` | uuidv4 | Chave única de identificação do agendamento | 36         |

### Response

STATUS 200

Response Body

```json
{
    "created_at": "2024-07-10T16:17:28Z",
    "pix_message": null,
    "rejection_info": null,
    "rejection_reason": null,
    "request_control_key": "b8eb663e-10fe-4729-9db5-8f8c93de5001",
    "schedule_date": "2024-07-10",
    "schedule_key": "0c9091ab-079b-4a43-8b3d-d4ba36a23883",
    "schedule_status": "sent",
    "schedule_transfers": [
        {
            "created_at": "2024-07-10T16:19:33Z",
            "end_to_end_id": "E3240250220240710161922sSHNf8BjI",
            "pix_transfer_key": "427b70cd-73b0-45d1-bb4a-97f50f605022",
            "pix_transfer_status": "sent"
        }
    ],
    "target_account": {
        "account_branch": "0001",
        "account_digit": "8",
        "account_number": "1234567",
        "account_type": "checking_account",
        "ispb": "99999004",
        "owner_document_number": "***91111***",
        "owner_name": "Conta manual geral",
        "owner_person_type": "natural",
        "pix_key": null,
        "receiver_conciliation_id": null
    },
    "transaction_amount": 2.0,
    "updated_at": "2024-07-10T16:19:38Z"
}

```

---

# Consultar Agendamentos de Transação Pix de uma conta

URL: /documentation/baas/pix/agendamento/consulta_de_agendamentos_de_uma_conta

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_schedules
MÉTODO GET

### Path Params

| Campo          | Tipo   | Descrição                                   | Caracteres |
|----------------|--------|---------------------------------------------|------------|
| `account_key`  | uuidv4 | Chave única de identificação da conta.      | 36         |

### Query Params

| Campo                 | Tipo    | Descrição                                                               | Caracteres         |
|-----------------------|---------|-------------------------------------------------------------------------|--------------------|
| `request_control_key` | uuidv4  | Chave única de identificação da request utilizada pelo cliente.         | 36                 |
| `schedule_status`     | string  | Status do agendamento. Pode ser enviado em forma de lista.              |  **[Enumerador schedule_status](#enumerador-schedule_status)** |
| `page`                | integer | Número da página requisitada. 1 por padrão                              |                    |
| `page_size`           | integer | Tamanho da página requisitada na consulta. 30 por padrão e valor máximo | Valor máximo de 30 |

### Enumerador schedule_status

| Enumerador                 | Descrição                                                                                      |
|----------------------------|------------------------------------------------------------------------------------------------|
| **scheduled**              | Transação agendada                                                                             |
| **sent**                   | Agendamento concluído e enviado com sucesso. Estado final                                      |
| **rejected**               | Agendamento rejeitado durante criação ou execução. Estado final                                |
| **cancelled**              | Agendamento cancelado por solicitação de cliente. Estado final                                 |
| **pending_2fa_approval**   | Pendente de aprovação por autenticação de dois fatores                                         |
| **pending_creation**       | Agendamento em processo de criação (Estado transitório para agendamento em lote)               |
| **waiting_batch_approval** | Agendamento criado e vinculado a um lote aguardando aprovação por autenticação de dois fatores |

### Response

STATUS 200

Response Body

```json
{
  "data": [
    {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "schedule_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "schedule_status": "scheduled",
      "schedule_date": "2024-12-31",
      "created_at": "2023-03-13T19:00:28.440Z"
    },
    {
      "request_control_key": "bf6b0a4b-c7a5-446b-9dad-1ae10b25342a",
      "schedule_key": "2479a5cd-079e-4d72-bf4e-16a695bda45e",
      "schedule_status": "cancelled",
      "schedule_date": "2024-12-31",
      "created_at": "2023-03-13T19:00:28.440Z"
    },
    {
      "request_control_key": "9d36c03e-2db7-4c90-87ed-6c9ddb3c03c7",
      "schedule_key": "5d6b14b9-053f-408c-bcd7-61ecf9224f2c",
      "schedule_status": "rejected",
      "schedule_date": "2024-12-31",
      "created_at": "2023-03-13T19:00:28.440Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "rows_per_page": 30
  }
}

```

---

# Tabela de Erros para Pix Schedule

URL: /documentation/baas/pix/agendamento/erros_de_agendamento

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                  | Descrição (eng)<br/>`description`                                                                                                    | Descrição (ptbr)<br/>`translation`                                                                                                          |
|--------------------------|----------------------|-----------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                         | schema error description                                                                                                             | Schema Inválido                                                                                                                             |
| 404                      | PSC000001            | Account not Found                                   | Account was not found                                                                                                                | Conta não encontrada                                                                                                                        |
| 406                      | PSC000002            | Invalid Uuid                                        | key was not accepted for not being a valid uuid v4 string                                                                            | key não foi aceito por não ser uma palavra uuid v4 válida                                                                                   |
| 400                      | PSC000003            | Bad Request                                         | pix_message can not be longer than 140 characters                                                                                    | pix_message não pode ser maior que 140 caracteres                                                                                           |
| 400                      | PSC000004            | Bad Request                                         | Emoji not allowed in pix message                                                                                                     | Emoji não é permitido na mensagem pix                                                                                                       |
| 406                      | PSC000005            | Invalid Transaction Amount                          | Transaction amount of transaction_amount is not valid. It must be a positive value with at maximum 2 decimal places                  | O valor de transação transaction_amount não é válido. Deve ser um valor positivo com no máximo duas casas decimais                          |
| 406                      | PSC000006            | Invalid end_to_end_id                               | The end_to_end_id sent end_to_end_id is not valid                                                                                    | O end_to_end_id enviado end_to_end_id não é válido                                                                                          |
| 400                      | PSC000007            | Invalid date format                                 | Dates must be sent using format YYYY-MM-DD                                                                                           | Datas devem ser enviadas no formato YYYY-MM-DD                                                                                              |
| 400                      | PSC000008            | Invalid Schedule Date                               | Schedule date must be after current date for UTC-3                                                                                   | Data de agendamento deve ser após a data atual em UTC-3                                                                                     |
| 400                      | PSC000009            | Account is Closed                                   | Account is closed                                                                                                                    | Conta está fechada                                                                                                                          |
| 400                      | PSC000010            | Account is Blocked                                  | Account is blocked                                                                                                                   | Conta está bloqueada                                                                                                                        |
| 422                      | PSC000011            | Invalid Account Type                                | Pix is not yet implemented for non-checking or non-escrow account types                                                              | Transações Pix não estão implementadas para conta que não sejam escrow ou livres                                                            |
| 403                      | PSC000012            | User is not allowed to do this transaction          | User is not allowed to do this transaction                                                                                           | Usuário não tem autorização para fazer essa transação                                                                                       |
| 400                      | PSC000013            | Bad Request                                         | For Manual Pix Transfer Type a target account must be provided                                                                       | Para transação pix do tipo manual, uma conta destino deve ser fornecida                                                                     |
| 404                      | PSC000014            | Inquiry Not Found                                   | Pix key inquiry was not found                                                                                                        | Pesquisa de chave pix não encontrada                                                                                                        |
| 400                      | PSC000015            | Bad Request                                         | Pix key sent does match inquiry pix key. Verify if end_to_end_id sent is correct                                                     | Chave Pix enviada não condiz com consulta. Verifique se end_to_end_id enviado está correto                                                  |
| 404                      | PSC000016            | Account not found                                   | Nonexistent account in destination financial institution                                                                             | Conta inexistente na instituição financeira de destino                                                                                      |
| 400                      | PSC000017            | Target Account and Source Account must be different | Target Account must not be the same as Source Account                                                                                | A conta de destino não pode ser a mesma da conta de origem                                                                                  |
| 409                      | PSC000018            | Bad Request                                         | request_control_key request_control_key already in use                                                                               | request_control_key request_control_key já utilizada                                                                                        |
| 400                      | PSC000019            | Invalid Target                                      | Account does not have permission to transfer to the given target account                                                             | A conta não possui permissão para realizar transferências para a conta enviada                                                              |
| 404                      | PSC000020            | Decode Inquiry Not Found                            | QR Code decode inquiry not found                                                                                                     | Pesquisa e decodificação de QR code não encontrada                                                                                          |
| 400                      | PSC000021            | Bad Request                                         | Receiver Conciliation Id sent does match decode inquiry receiver_conciliation_id. Verify if end_to_end_id sent is correct            | Identificador de transação enviado não condiz com consulta. Verifique se end_to_end_id enviado está correto                                 |
| 400                      | PSC000022            | Bad Request                                         | Dynamic Instant QR codes cannot be scheduled for payment                                                                             | Pagamentos de vencimento instantâneo não podem ter pagamento agendado                                                                       |
| 400                      | PSC000023            | Bad Request                                         | Schedule Date sent is after max payment date for target qr code                                                                      | Data de agendamento enviada é após a data máxima de pagamento para o qr code enviado                                                        |
| 400                      | PSC000024            | Bad Request                                         | Pix transfer type sent does match decode inquiry qr code type. Verify if end_to_end_id sent is correct                               | Tipo de transação pix enviado enviado não condiz com tipo de qr code da consulta. Verifique se end_to_end_id enviado está correto           |
| 404                      | PSC000025            | PixSchedule not Found                               | PixSchedule was not found                                                                                                            | PixSchedule não encontrada                                                                                                                  |
| 400                      | PSC000026            | Search Params Error                                 | Invalid integer value for page or size querystring parameters                                                                        | Valor inválido para parâmetros de página ou tamanho de página                                                                               |
| 400                      | PSC000027            | Bad Request                                         | Action cannot be taken place as there is currently a pending transfer in progress                                                    | A ação não pôde ser completada como há uma transferência pendente                                                                           |
| 400                      | PSC000028            | Bad Request                                         | Pix Schedule cannot be cancelled in current status                                                                                   | Agendamento pix não pode ser cancelado no status atual                                                                                      |
| 400                      | PSC000029            | Bad Request                                         | The given Pix Schedule is tied to a batch. It cannot be individually cancelled                                                       | O agendamento pix enviado está ligado a um lote. Ela não pode ser individualmente cancelada                                                 |
| 400                      | PSC000030            | Bad Request                                         | The maximum amount of pix transfer attempts has been reached                                                                         | A máxima quantidade de retentativas de transação pix foi atingida                                                                           |
| 400                      | PSC000031            | Bad Request                                         | An error occurred while attempting to run pix transfer                                                                               | Um erro ocorreu ao tentar realizar a transação pix                                                                                          |
| 404                      | PSC000032            | Pix Key Not Found                                   | Pix key was not found                                                                                                                | Chave pix não encontrada                                                                                                                    |
| 404                      | PSC000033            | Account Missmatch                                   | Target Account changed from schedule creation                                                                                        | A conta alvo foi alterada desde a criação do agendamento                                                                                    |
| 400                      | PSC000034            | Pix Schedule Conciliation Error                     | The referenced PixSchedule could not be updated                                                                                      | O PixSchedule referenciado não pode ser atualizado                                                                                          |
| 400                      | PSC000035            | Pix Schedule Transfer Conciliation Error            | The referenced PixScheduleTransfer could not be updated                                                                              | O PixScheduleTransfer referenciado não pode ser atualizado                                                                                  |
| 404                      | PSC000036            | Person Not Found                                    | Person not found                                                                                                                     | Pessoa não encontrada                                                                                                                       |
| 400                      | PSC000040            | Empty pix-schedule list received                    | A list of pix schedules must be provided                                                                                             | Uma lista de agendamentos pix deve ser fornecida                                                                                            |
| 409                      | PSC000041            | Bad Request                                         | One or more request_control_key already in use                                                                                       | Uma ou mais request_control_key já está sendo utilizada                                                                                     |
| 404                      | PSC000042            | Schedule Batch not Found                            | ScheduleBatch was not found                                                                                                          | ScheduleBatch não encontrada                                                                                                                |
| 400                      | PSC000043            | Schedule Batch could not be canceled                | ScheduleBatch could not be canceled due to current date being equal or after earliest schedule date. Cancel pix_schedules one by one | ScheduleBatch não pode ser cancelada devido a data atual ser superior ou igual à menor schedule_date. Cancele pix_schedules individualmente |
| 400                      | PSC000044            | Bad Request                                         | Schedule Batch cannot be cancelled in current status                                                                                 | Agendamento pix não pode ser cancelado no status atual                                                                                      |
| 403                      | PSC000045            | Requester not allowed to access this endpoint       | Requester has no permission to perform pix transfers on this endpoint                                                                | Requester não possui permissão de realizar transações pix através deste endpoint                                                            |
| 400                      | PSC000046            | tfa_info is required                                | Client must send object tfa_info                                                                                                     | Cliente deve enviar objeto tfa_info                                                                                                         |
| 403                      | PSC000047            | No approver permission                              | Given document number does not belong to an approver for this account                                                                | Número de documento enviado não pertence a um aprovador da conta                                                                            |
| 400                      | PSC000048            | Error occurred while sending token                  | An unexpected error occurred while sending token                                                                                     | Um erro inesperado ocorreu ao tentar enviar token                                                                                           |
| 400                      | PSC000049            | Number of token validation attempts exceeded        | The maximum number of failed token validation attempts has been reached                                                              | Número máximo de tentativas de validação de token atingida                                                                                  |
| 400                      | PSC000050            | Token Expired                                       | Token has expired. Resend token or recreate schedule                                                                                 | Token expirado. Reenvie token ou recrie a agendamento                                                                                       |
| 400                      | PSC000051            | Error Sending Token                                 | An error occurred while sending token and its being investigated                                                                     | Um erro ocorreu ao enviar token e está sendo investigado                                                                                    |
| 400                      | PSC000052            | Incorrect Token                                     | Token sent does not match expected                                                                                                   | Token enviado não condiz com o esperado                                                                                                     |
| 400                      | PSC000053            | Error Sending Token                                 | An error occurred while resending token and its being investigated                                                                   | Um erro ocorreu ao reenviar token e está sendo investigado                                                                                  |
| 400                      | PSC000054            | Invalid Schedule Date                               | Schedule must be approved before the scheduled date                                                                                  | Agendamento deve ser aprovado em data anterior à programada para transação                                                                  |
| 400                      | PSC000055            | Bad Request                                         | Schedule cannot be approved in current status                                                                                        | Agendamento pix não pode ser aprovado no status atual                                                                                       |
| 400                      | PSC000056            | Bad Request                                         | Schedule Batch cannot be approved in current status                                                                                  | Lote de agendamento pix não pode ser aprovado no status atual                                                                               |
| 400                      | PSC000057            | Invalid Schedule Date                               | Batch Schedule must be approved before the earliest scheduled date                                                                   | Lote de agendamento deve ser aprovado em data anterior à programada para transação                                                          |

---

# Introdução

URL: /documentation/baas/pix/agendamento/introducao

Por meio dos endpoints apresentados nesta sessão, o parceiro integrador pode solicitar o agendamento de transações do
tipo pix. Com esta funcionalidade será possível criar, listar e cancelar agendamentos de uma determinada conta.

## Observações

- A data de agendamento leva em consideração o horário de Brasília (BRT ou UTC/GMT -03:00)
- As transações serão tentadas a partir de 8h BRT
- Transações que tenham falhado por falta de saldo serão retentadas em 1 hora com um limite de 3 tentativas
- Para transaçôes do tipo **key**, **static_qr_code** e **dynamic_qr_code**, antes de a transação ser completada, será
  realizada uma nova verificação da chave Pix para garantir que a conta destino não foi alterada. Caso seja detectada
  alguma discrepância, o agendamento será rejeitado (**rejected**)
- Um webhook será enviado ao parceiro integrador informando o sucesso ou rejeição de um agendamento
- Não é possível agendar um **dynamic_qr_code** instantâneo
- Transferencias por agendamento consomem limite de transação pix

## Pix Schedule Status

| Enumerador                 | Descrição                                                                                      |
|----------------------------|------------------------------------------------------------------------------------------------|
| **scheduled**              | Transação agendada                                                                             |
| **sent**                   | Agendamento concluído e enviado com sucesso. Estado final                                      |
| **rejected**               | Agendamento rejeitado durante criação ou execução. Estado final                                |
| **cancelled**              | Agendamento cancelado por solicitação de cliente. Estado final                                 |
| **pending_2fa_approval**   | Pendente de aprovação por autenticação de dois fatores                                         |
| **pending_creation**       | Agendamento em processo de criação (Estado transitório para agendamento em lote)               |
| **waiting_batch_approval** | Agendamento criado e vinculado a um lote aguardando aprovação por autenticação de dois fatores |

## Schedule Transfers

No dia do agendamento, após a realização da verificação de consistência da conta alvo, será tentada a transação pix.
Neste momento é gerada uma **pix_transfer** e esta será adicionada à lista de `schedule_transfers`. Serão tentadas um
máximo 3 transações pix.

### Schedule Transfer Object

| Campo                 | Tipo   | Descrição                                                                                   | Caracteres                                                          |
|-----------------------|--------|---------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
| `pix_transfer_key`    | uuidv4 | Chave única de identificação da transferência Pix no sistema QI.                            | 36                                                                  |
| `end_to_end_id` *     | string | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo) | 32                                                                  |
| `pix_transfer_status` | string | Status da transação.                                                                        | [Enumeradores pix_transfer_status](#enumerador-pix-transfer-status) |         |
| `created_at`          | string | Data e hora de criação da transação.                                                        | 20                                                                  |

### Enumerador Pix Transfer Status

| Enumerador   | Descrição                                           |
|--------------|-----------------------------------------------------|
| **sent**     | Transação enviada com sucesso. Estado final         |
| **rejected** | Transação rejeitada durante execução. Estado final  |
| **pending**  | Transação pendente de conclusão. Estado Transitório |

---

# Introdução a Autenticação de Dois Fatores

URL: /documentation/baas/pix/agendamento/introducao_a_agendamento_2fa

Neste tipo de agendamento, é necessário a confirmação da programação de pagamento via token enviado à pessoa com poderes
de aprovação de movimentação na conta credora.

A solicitação de agendamento Pix por parceiros integradores configurados para a utilização de autenticação de dois
fatores é realizada de forma similar ao descrito
em [solicitar agendamento de_transação_pix](/documentation/baas/pix/agendamento/solicitacao_de_agendamento). A diferença
ocorre na adição do objeto `tfa_info`, contento informações sobre o aprovador da transferência e a forma de contato, e o
status de uma solicitação bem sucedida que será sempre **pending_2fa_approval**.

O mesmo vale para transações em lote Pix descrito
em [realizar transação pix em lote](/documentation/baas/pix/batch/solicitacao_de_transacao_em_lote_pix).

## Fluxo para um agendamento Pix com autorização

O agendamento Pix bem sucedido seguirá o seguinte fluxo de processos:
Realização da [solicitação de transação Pix](/documentation/baas/pix/agendamento/solicitacao_de_agendamento_2fa) e recebimento de resposta de forma síncrona com status de **pending_2fa_approval** e valor da `schedule_key`.
O aprovador indicado receberá um `token` de 6 dígitos compostos por algarismos.
O requisitante realiza a [confirmação de transação pix](/documentation/baas/pix/agendamento/aprovacao_de_agendamento_2fa) com a `schedule_key` e o `token`.
O agendamento será então atualizado para o status de **scheduled**.
## Observações
Cada agendamento possui um limite máximo de tentativas de validação do `token` de 5. Quando este limite é alcançado o agendamento será colocado em status de rejeitado (**rejected**) automaticamente.
Cada `token` possui duração máxima de 5 minutos.
Um agendamento pode ter seu `token` renovado e reenviado para o aprovador da transferência. Este processo reinica o tempo de 5 minutos e não reinicia o contador de tentativas inválidas. O `token` anterior torna-se inválido.
O evento de notificação para o envio de `token` ao aprovador é **baas.token_validation.pix_transfer.schedule.single**. É possível [personalizar](/documentation/notificacoes/template) a mensagem enviada.
As formas de envio (`contact_type`) de token implementadas são por **sms** e **email**.

---

# Solicitar Agendamento de Transação Pix

URL: /documentation/baas/pix/agendamento/solicitacao_de_agendamento

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_schedule
MÉTODO POST

### Path Params

| Campo         | Tipo   | Descrição                              | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36         |

**Chave**

Request Body: Agendamento por Chave Pix

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_type": "key",
  "target_pix_key": "target_pix_key@email.com",
  "transaction_amount": 500.65,
  "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
  "pix_message": "Ola Mundo",
  "schedule_date": "2024-12-01"
}
```

### Body Params

| Campo                   | Tipo       | Descrição                                                                                                                                                                                                                                        | Caracteres |
|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4     | Chave única de identificação da request utilizada pelo cliente no formato uuid v4.                                                                                                                                                               | 36         | 
| `pix_transfer_type` *   | enumerator | Tipo do pix a ser realizado. Para o caso de transferência por chave deve ser **key**.                                                                                                                                                            | **key**    |
| `target_pix_key` *      | string     | Chave pix da conta a ser enviada a transação.                                                                                                                                                                                                    | 100        |
| `transaction_amount` *  | number     | Valor da transferência.                                                                                                                                                                                                                          | 10         |
| `end_to_end_id` *       | string     | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na consulta de chave Pix. Só deve ser enviado se o `pix_transfer_type` for **key**, **static_qr_code** ou **static_qr_code** | 32         |
| `pix_message`           | string     | Mensagem a ser enviada junto à transferência Pix.                                                                                                                                                                                                | 140        |
| `schedule_date`*        | string     | Data a ser realizada a transação.                                                                                                                                                                                                                | 10         |

**Manual**
Request Body: Transferência Manual

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_type": "manual",
  "target_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "32402502000135",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502"
  },
  "transaction_amount": 500.65,
  "pix_message": "Ola Mundo",
  "schedule_date": "2024-12-01"
}
```

### Body Params

| Campo                   | Tipo       | Descrição                                                                                         | Caracteres                                          |
|-------------------------|------------|---------------------------------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | uuidv4     | Chave única de identificação da request utilizada pelo cliente no formato uuid v4.                | 36                                                  | 
| `pix_transfer_type` *   | enumerator | Tipo de transferência Pix.                                                                        | **manual**                                          |
| `target_account` *      | Object     | Conta destino - Só deve ser enviada em transferências com `pix_transfer_type` do tipo **manual**. | **[Objeto target_account](#objeto-target_account)** | 10 |
| `transaction_amount` *  | number     | Valor da transferência.                                                                           | 10                                                  |
| `pix_message`           | string     | Mensagem a ser enviada junto à transferência Pix.                                                 | 140                                                 |
| `schedule_date`*        | string     | Data a ser realizada a transação.                                                                 | 10                                                  |

### Objeto target_account

| Campo                     | Tipo       | Descrição                                           | Caracteres                                              |
|---------------------------|------------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string     | Agência da conta.                                   | 4                                                       |
| `account_digit` *         | string     | Dígito da conta.                                    | 1                                                       |
| `account_number` *        | string     | Número da conta.                                    | 20                                                      |
| `owner_document_number` * | string     | CPF ou CNPJ (apenas números) do titular da conta.   | 14                                                      |
| `owner_name` *            | string     | Nome do titular da conta.                           | 150                                                     |
| `account_type`*           | enumerator | Tipo da conta.                                      | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string     | Base no CNPJ da instituição financeira (8 dígitos). | 8                                                       |

### Enumerador account_type

| Enumerador           | Descrição           |
|----------------------|---------------------|
| **checking_account** | Conta Corrente      |
| **salary_account**   | Conta Salário       |
| **saving_account**   | Conta Poupança      |
| **payment_account**  | Conta de Pagamentos |

**Qr Code**

Request Body: Transferência por Qr Code

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_type": "static_qr_code",
  "transaction_amount": 500.65,
  "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
  "receiver_conciliation_id": "REC00000000000000000000009459463343",
  "target_pix_key": "target_pix_key@email.com",
  "pix_message": "Ola Mundo",
  "schedule_date": "2024-12-01"
}
```

### Body Params

| Campo                      | Tipo       | Descrição                                                                                                                                                                                                                                         | Caracteres                                |
|----------------------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|
| `request_control_key`*     | uuidv4     | Chave única de identificação da request utilizada pelo cliente no formato uuid v4.                                                                                                                                                                | 36                                        | 
| `pix_transfer_type`*       | enumerator | Tipo de transferência Pix.                                                                                                                                                                                                                        | **static_qr_code** ou **dynamic_qr_code** |
| `target_pix_key`*          | string     | Chave pix da conta a ser enviada a transação.                                                                                                                                                                                                     | 100                                       |
| `receiver_conciliation_id` | string     | Identicação de conciliação do recebedor.                                                                                                                                                                                                          | 35                                        |
| `transaction_amount`*      | number     | Valor da transferência.                                                                                                                                                                                                                           | 10                                        |
| `end_to_end_id`*           | string     | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na consulta de chave Pix. Só deve ser enviado se o `pix_transfer_type` for **key**, **static_qr_code** ou **static_qr_code**. | 32                                        |
| `pix_message`              | string     | Mensagem a ser enviada junto à transferência Pix.                                                                                                                                                                                                 | 140                                       |

:::info Aviso
O `end_to_end_id` é retornado ao [decodificar o QR Code Pix](/documentation/pix/decodificar_qr_code), utilizando a URI
do Pix Copia e Cola.
:::

:::danger Aviso
O `end_to_end_id` da consulta deve ter sido feito em nome da conta que solicitará a movimentação!
:::

:::danger Aviso
Um `end_to_end_id` só pode ser utilizado para uma única transferência, não importando, se a transferência tenha sido bem
sucedida ou não.
:::

## Response

STATUS 201

Response Body: Agendamento Criado

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "schedule_key": "f64b3fa7-d09d-4927-ad4f-b966df9fb153",
  "schedule_status": "scheduled",
  "schedule_date": "2024-12-31",
  "created_at": "2023-03-13T19:00:28.440Z"
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                  | Descrição (eng)<br/>`description`                                                                                                    | Descrição (ptbr)<br/>`translation`                                                                                                          |
|--------------------------|----------------------|-----------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                         | schema error description                                                                                                             | Schema Inválido                                                                                                                             |
| 404                      | PSC000001            | Account not Found                                   | Account was not found                                                                                                                | Conta não encontrada                                                                                                                        |
| 406                      | PSC000002            | Invalid Uuid                                        | key was not accepted for not being a valid uuid v4 string                                                                            | key não foi aceito por não ser uma palavra uuid v4 válida                                                                                   |
| 400                      | PSC000003            | Bad Request                                         | pix_message can not be longer than 140 characters                                                                                    | pix_message não pode ser maior que 140 caracteres                                                                                           |
| 400                      | PSC000004            | Bad Request                                         | Emoji not allowed in pix message                                                                                                     | Emoji não é permitido na mensagem pix                                                                                                       |
| 406                      | PSC000005            | Invalid Transaction Amount                          | Transaction amount of transaction_amount is not valid. It must be a positive value with at maximum 2 decimal places                  | O valor de transação transaction_amount não é válido. Deve ser um valor positivo com no máximo duas casas decimais                          |
| 406                      | PSC000006            | Invalid end_to_end_id                               | The end_to_end_id sent end_to_end_id is not valid                                                                                    | O end_to_end_id enviado end_to_end_id não é válido                                                                                          |
| 400                      | PSC000007            | Invalid date format                                 | Dates must be sent using format YYYY-MM-DD                                                                                           | Datas devem ser enviadas no formato YYYY-MM-DD                                                                                              |
| 400                      | PSC000008            | Invalid Schedule Date                               | Schedule date must be after current date for UTC-3                                                                                   | Data de agendamento deve ser após a data atual em UTC-3                                                                                     |
| 400                      | PSC000009            | Account is Closed                                   | Account is closed                                                                                                                    | Conta está fechada                                                                                                                          |
| 400                      | PSC000010            | Account is Blocked                                  | Account is blocked                                                                                                                   | Conta está bloqueada                                                                                                                        |
| 422                      | PSC000011            | Invalid Account Type                                | Pix is not yet implemented for non-checking or non-escrow account types                                                              | Transações Pix não estão implementadas para conta que não sejam escrow ou livres                                                            |
| 403                      | PSC000012            | User is not allowed to do this transaction          | User is not allowed to do this transaction                                                                                           | Usuário não tem autorização para fazer essa transação                                                                                       |
| 400                      | PSC000013            | Bad Request                                         | For Manual Pix Transfer Type a target account must be provided                                                                       | Para transação pix do tipo manual, uma conta destino deve ser fornecida                                                                     |
| 404                      | PSC000014            | Inquiry Not Found                                   | Pix key inquiry was not found                                                                                                        | Pesquisa de chave pix não encontrada                                                                                                        |
| 400                      | PSC000015            | Bad Request                                         | Pix key sent does match inquiry pix key. Verify if end_to_end_id sent is correct                                                     | Chave Pix enviada não condiz com consulta. Verifique se end_to_end_id enviado está correto                                                  |
| 404                      | PSC000016            | Account not found                                   | Nonexistent account in destination financial institution                                                                             | Conta inexistente na instituição financeira de destino                                                                                      |
| 400                      | PSC000017            | Target Account and Source Account must be different | Target Account must not be the same as Source Account                                                                                | A conta de destino não pode ser a mesma da conta de origem                                                                                  |
| 409                      | PSC000018            | Bad Request                                         | request_control_key request_control_key already in use                                                                               | request_control_key request_control_key já utilizada                                                                                        |
| 400                      | PSC000019            | Invalid Target                                      | Account does not have permission to transfer to the given target account                                                             | A conta não possui permissão para realizar transferências para a conta enviada                                                              |
| 404                      | PSC000020            | Decode Inquiry Not Found                            | QR Code decode inquiry not found                                                                                                     | Pesquisa e decodificação de QR code não encontrada                                                                                          |
| 400                      | PSC000021            | Bad Request                                         | Receiver Conciliation Id sent does match decode inquiry receiver_conciliation_id. Verify if end_to_end_id sent is correct            | Identificador de transação enviado não condiz com consulta. Verifique se end_to_end_id enviado está correto                                 |
| 400                      | PSC000022            | Bad Request                                         | Dynamic Instant QR codes cannot be scheduled for payment                                                                             | Pagamentos de vencimento instantâneo não podem ter pagamento agendado                                                                       |
| 400                      | PSC000023            | Bad Request                                         | Schedule Date sent is after max payment date for target qr code                                                                      | Data de agendamento enviada é após a data máxima de pagamento para o qr code enviado                                                        |
| 400                      | PSC000024            | Bad Request                                         | Pix transfer type sent does match decode inquiry qr code type. Verify if end_to_end_id sent is correct                               | Tipo de transação pix enviado enviado não condiz com tipo de qr code da consulta. Verifique se end_to_end_id enviado está correto           |

---

# Solicitar Agendamento de Transação Pix com Autenticação de Dois Fatores

URL: /documentation/baas/pix/agendamento/solicitacao_de_agendamento_2fa

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_schedule
MÉTODO POST

### Path Params

| Campo         | Tipo   | Descrição                              | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36         |

**Chave**
## Autenticação via Email e SMS
Request Body: Agendamento por Chave Pix com TFA por SMS ou Email

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_type": "key",
  "target_pix_key": "target_pix_key@email.com",
  "transaction_amount": 500.65,
  "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
  "pix_message": "Ola Mundo",
  "schedule_date": "2024-12-01",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```

## Autenticação via Dispositivo

Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`.

Request Body: Agendamento por Chave Pix com TFA por Dispositivo

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_type": "key",
  "target_pix_key": "target_pix_key@email.com",
  "transaction_amount": 500.65,
  "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
  "pix_message": "Ola Mundo",
  "schedule_date": "2024-12-01",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
    "contact_type": "device"
  }
}
```

### Body Params

| Campo                   | Tipo       | Descrição                                                                                                                                                                                                                                        | Caracteres                              |
|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------|
| `request_control_key` * | uuidv4     | Chave única de identificação da request utilizada pelo cliente no formato uuid v4.                                                                                                                                                               | 36                                      | 
| `pix_transfer_type` *   | enumerator | Tipo do pix a ser realizado. Para o caso de transferência por chave deve ser **key**.                                                                                                                                                            | **key**                                 |
| `target_pix_key` *      | string     | Chave pix da conta a ser enviada a transação.                                                                                                                                                                                                    | 100                                     |
| `transaction_amount` *  | number     | Valor da transferência.                                                                                                                                                                                                                          | 10                                      |
| `end_to_end_id` *       | string     | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na consulta de chave Pix. Só deve ser enviado se o `pix_transfer_type` for **key**, **static_qr_code** ou **static_qr_code** | 32                                      |
| `pix_message`           | string     | Mensagem a ser enviada junto à transferência Pix.                                                                                                                                                                                                | 140                                     |
| `schedule_date`*        | string     | Data a ser realizada a transação.                                                                                                                                                                                                                | 10                                      |
| `tfa_info`*             | Object     | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato.                                                                                                                                                                  | **[Objeto tfa_info](#objeto-tfa_info)** |

**Manual**
## Autenticação via Email e SMS
Request Body: Transferência Manual com TFA por SMS ou Email

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_type": "manual",
  "target_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "32402502000135",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502"
  },
  "transaction_amount": 500.65,
  "pix_message": "Ola Mundo",
  "schedule_date": "2024-12-01",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```

## Autenticação via Dispositivo

Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`.

Request Body: Transferência Manual com TFA por Dispositivo

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_type": "manual",
  "target_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "32402502000135",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502"
  },
  "transaction_amount": 500.65,
  "pix_message": "Ola Mundo",
  "schedule_date": "2024-12-01",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
    "contact_type": "device"
  }
}
```

### Body Params

| Campo                   | Tipo       | Descrição                                                                                         | Caracteres                                          |
|-------------------------|------------|---------------------------------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | uuidv4     | Chave única de identificação da request utilizada pelo cliente no formato uuid v4.                | 36                                                  | 
| `pix_transfer_type` *   | enumerator | Tipo de transferência Pix.                                                                        | **manual**                                          |
| `target_account` *      | Object     | Conta destino - Só deve ser enviada em transferências com `pix_transfer_type` do tipo **manual**. | **[Objeto target_account](#objeto-target_account)** | 10 |
| `transaction_amount` *  | number     | Valor da transferência.                                                                           | 10                                                  |
| `pix_message`           | string     | Mensagem a ser enviada junto à transferência Pix.                                                 | 140                                                 |
| `schedule_date`*        | string     | Data a ser realizada a transação.                                                                 | 10                                                  |
| `tfa_info`*             | Object     | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato.                   | **[Objeto tfa_info](#objeto-tfa_info)**             |

### Objeto target_account

| Campo                     | Tipo       | Descrição                                           | Caracteres                                              |
|---------------------------|------------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string     | Agência da conta.                                   | 4                                                       |
| `account_digit` *         | string     | Dígito da conta.                                    | 1                                                       |
| `account_number` *        | string     | Número da conta.                                    | 20                                                      |
| `owner_document_number` * | string     | CPF ou CNPJ (apenas números) do titular da conta.   | 14                                                      |
| `owner_name` *            | string     | Nome do titular da conta.                           | 150                                                     |
| `account_type`*           | enumerator | Tipo da conta.                                      | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string     | Base no CNPJ da instituição financeira (8 dígitos). | 8                                                       |

### Enumerador account_type

| Enumerador           | Descrição           |
|----------------------|---------------------|
| **checking_account** | Conta Corrente      |
| **salary_account**   | Conta Salário       |
| **saving_account**   | Conta Poupança      |
| **payment_account**  | Conta de Pagamentos |

**Qr Code**
## Autenticação via Email e SMS
Request Body: Transferência por Qr Code com TFA por SMS ou Email

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_type": "static_qr_code",
  "transaction_amount": 500.65,
  "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
  "receiver_conciliation_id": "REC00000000000000000000009459463343",
  "target_pix_key": "target_pix_key@email.com",
  "pix_message": "Ola Mundo",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```

## Autenticação via Dispositivo

Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`.

Request Body: Transferência por Qr Code com TFA por Dispositivo

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_type": "static_qr_code",
  "transaction_amount": 500.65,
  "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
  "receiver_conciliation_id": "REC00000000000000000000009459463343",
  "target_pix_key": "target_pix_key@email.com",
  "pix_message": "Ola Mundo",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
    "contact_type": "device"
  }
}
```

### Body Params

| Campo                      | Tipo       | Descrição                                                                                                                                                                                                                                         | Caracteres                                |
|----------------------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|
| `request_control_key`*     | uuidv4     | Chave única de identificação da request utilizada pelo cliente no formato uuid v4.                                                                                                                                                                | 36                                        | 
| `pix_transfer_type`*       | enumerator | Tipo de transferência Pix.                                                                                                                                                                                                                        | **static_qr_code** ou **dynamic_qr_code** |
| `target_pix_key`*          | string     | Chave pix da conta a ser enviada a transação.                                                                                                                                                                                                     | 100                                       |
| `receiver_conciliation_id` | string     | Identicação de conciliação do recebedor.                                                                                                                                                                                                          | 35                                        |
| `transaction_amount`*      | number     | Valor da transferência.                                                                                                                                                                                                                           | 10                                        |
| `end_to_end_id`*           | string     | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na consulta de chave Pix. Só deve ser enviado se o `pix_transfer_type` for **key**, **static_qr_code** ou **static_qr_code**. | 32                                        |
| `pix_message`              | string     | Mensagem a ser enviada junto à transferência Pix.                                                                                                                                                                                                 | 140                                       |
| `tfa_info`*                | Object     | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato.                                                                                                                                                                   | **[Objeto tfa_info](#objeto-tfa_info)**   |

:::info Aviso
O `end_to_end_id` é retornado ao [decodificar o QR Code Pix](/documentation/pix/decodificar_qr_code), utilizando a URI
do Pix Copia e Cola.
:::

### Objeto tfa_info

| Campo                       | Tipo   | Descrição                                                                                                                        | Caracteres |
|-----------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------|------------|
| `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta.                                                                               | 11         |
| `session_id`                | string | Chave única de identificação da sessão do dispositivo no formato UUID v4 (obrigatório para TFA via dispositivo).                 | 36         |
| `contact_type`*             | string | Forma de contato com a pessoa aprovadora da conta, podendo ser **sms**, **email** ou **device**                                  |            |

:::danger Aviso
O `end_to_end_id` da consulta deve ter sido feito em nome da conta que solicitará a movimentação!
:::

:::danger Aviso
Um `end_to_end_id` só pode ser utilizado para uma única transferência, não importando, se a transferência tenha sido bem
sucedida ou não.
:::

## Response

STATUS 201

Response Body: Agendamento Criado

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "schedule_key": "f64b3fa7-d09d-4927-ad4f-b966df9fb153",
  "schedule_status": "pending_2fa_approval",
  "schedule_date": "2024-12-31",
  "created_at": "2023-03-13T19:00:28.440Z"
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                  | Descrição (eng)<br/>`description`                                                                                         | Descrição (ptbr)<br/>`translation`                                                                                                |
|--------------------------|----------------------|-----------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                         | schema error description                                                                                                  | Schema Inválido                                                                                                                   |
| 404                      | PSC000001            | Account not Found                                   | Account was not found                                                                                                     | Conta não encontrada                                                                                                              |
| 406                      | PSC000002            | Invalid Uuid                                        | key was not accepted for not being a valid uuid v4 string                                                                 | key não foi aceito por não ser uma palavra uuid v4 válida                                                                         |
| 400                      | PSC000003            | Bad Request                                         | pix_message can not be longer than 140 characters                                                                         | pix_message não pode ser maior que 140 caracteres                                                                                 |
| 400                      | PSC000004            | Bad Request                                         | Emoji not allowed in pix message                                                                                          | Emoji não é permitido na mensagem pix                                                                                             |
| 406                      | PSC000005            | Invalid Transaction Amount                          | Transaction amount of transaction_amount is not valid. It must be a positive value with at maximum 2 decimal places       | O valor de transação transaction_amount não é válido. Deve ser um valor positivo com no máximo duas casas decimais                |
| 406                      | PSC000006            | Invalid end_to_end_id                               | The end_to_end_id sent end_to_end_id is not valid                                                                         | O end_to_end_id enviado end_to_end_id não é válido                                                                                |
| 400                      | PSC000007            | Invalid date format                                 | Dates must be sent using format YYYY-MM-DD                                                                                | Datas devem ser enviadas no formato YYYY-MM-DD                                                                                    |
| 400                      | PSC000008            | Invalid Schedule Date                               | Schedule date must be after current date for UTC-3                                                                        | Data de agendamento deve ser após a data atual em UTC-3                                                                           |
| 400                      | PSC000009            | Account is Closed                                   | Account is closed                                                                                                         | Conta está fechada                                                                                                                |
| 400                      | PSC000010            | Account is Blocked                                  | Account is blocked                                                                                                        | Conta está bloqueada                                                                                                              |
| 422                      | PSC000011            | Invalid Account Type                                | Pix is not yet implemented for non-checking or non-escrow account types                                                   | Transações Pix não estão implementadas para conta que não sejam escrow ou livres                                                  |
| 403                      | PSC000012            | User is not allowed to do this transaction          | User is not allowed to do this transaction                                                                                | Usuário não tem autorização para fazer essa transação                                                                             |
| 400                      | PSC000013            | Bad Request                                         | For Manual Pix Transfer Type a target account must be provided                                                            | Para transação pix do tipo manual, uma conta destino deve ser fornecida                                                           |
| 404                      | PSC000014            | Inquiry Not Found                                   | Pix key inquiry was not found                                                                                             | Pesquisa de chave pix não encontrada                                                                                              |
| 400                      | PSC000015            | Bad Request                                         | Pix key sent does match inquiry pix key. Verify if end_to_end_id sent is correct                                          | Chave Pix enviada não condiz com consulta. Verifique se end_to_end_id enviado está correto                                        |
| 404                      | PSC000016            | Account not found                                   | Nonexistent account in destination financial institution                                                                  | Conta inexistente na instituição financeira de destino                                                                            |
| 400                      | PSC000017            | Target Account and Source Account must be different | Target Account must not be the same as Source Account                                                                     | A conta de destino não pode ser a mesma da conta de origem                                                                        |
| 409                      | PSC000018            | Bad Request                                         | request_control_key request_control_key already in use                                                                    | request_control_key request_control_key já utilizada                                                                              |
| 400                      | PSC000019            | Invalid Target                                      | Account does not have permission to transfer to the given target account                                                  | A conta não possui permissão para realizar transferências para a conta enviada                                                    |
| 404                      | PSC000020            | Decode Inquiry Not Found                            | QR Code decode inquiry not found                                                                                          | Pesquisa e decodificação de QR code não encontrada                                                                                |
| 400                      | PSC000021            | Bad Request                                         | Receiver Conciliation Id sent does match decode inquiry receiver_conciliation_id. Verify if end_to_end_id sent is correct | Identificador de transação enviado não condiz com consulta. Verifique se end_to_end_id enviado está correto                       |
| 400                      | PSC000022            | Bad Request                                         | Dynamic Instant QR codes cannot be scheduled for payment                                                                  | Pagamentos de vencimento instantâneo não podem ter pagamento agendado                                                             |
| 400                      | PSC000023            | Bad Request                                         | Schedule Date sent is after max payment date for target qr code                                                           | Data de agendamento enviada é após a data máxima de pagamento para o qr code enviado                                              |
| 400                      | PSC000024            | Bad Request                                         | Pix transfer type sent does match decode inquiry qr code type. Verify if end_to_end_id sent is correct                    | Tipo de transação pix enviado enviado não condiz com tipo de qr code da consulta. Verifique se end_to_end_id enviado está correto |
| 400                      | PSC000046            | tfa_info is required                                | Client must send object tfa_info                                                                                          | Cliente deve enviar objeto tfa_info                                                                                               |
| 403                      | PSC000047            | No approver permission                              | Given document number does not belong to an approver for this account                                                     | Número de documento enviado não pertence a um aprovador da conta                                                                  |
| 400                      | PSC000048            | Error occurred while sending token                  | An unexpected error occurred while sending token                                                                          | Um erro inesperado ocorreu ao tentar enviar token                                                                                 |

---

# Solicitar reenvio de token para um agendamento

URL: /documentation/baas/pix/agendamento/solicitacao_de_reenvio_de_token_para_agendamento_2fa

Um novo token será gerado e enviado para o aprovador do agendamento pix. Caso o número limite de tentativas de validação
do token tenha sido excedida, não será permitido o reenvio.

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_schedule/ SCHEDULE_KEY /resend_token
MÉTODO PATCH

### Path Params

| Campo          | Tipo   | Descrição                                    | Caracteres |
|----------------|--------|----------------------------------------------|------------|
| `account_key`  | uuidv4 | Chave única de identificação da conta.       | 36         |
| `schedule_key` | uuidv4 | Chave única de identificação do agendamento. | 36         |

### Body Params

| Campo          | Tipo       | Descrição                               | Caracteres                                              |
|----------------|------------|-----------------------------------------|---------------------------------------------------------|
| `contact_type` | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** |

:::info Informação
Caso não seja enviado um `contact_type`, o token será enviado da forma solicitada originalmente.
:::

| Enumerador | Descrição                                         |
|------------|---------------------------------------------------|
| **sms**    | Envio por Mensagem de Texto para telefone celular |
| **email**  | Envio por correio eletrônico                      |

## Response

STATUS 202

Response Body: Transação Solicitada

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "schedule_key": "f64b3fa7-d09d-4927-ad4f-b966df9fb153",
  "schedule_status": "pending_2fa_approval",
  "schedule_date": "2024-12-31",
  "created_at": "2023-03-13T19:00:28.440Z"
}
```

STATUS 4xx

Response Body: Transferência Rejeitada

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                           | Descrição (eng)<br/>`description`                                       | Descrição (ptbr)<br/>`translation`                                         |
|--------------------------|----------------------|----------------------------------------------|-------------------------------------------------------------------------|----------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                  | schema error description                                                | Schema Inválido                                                            |
| 404                      | PSC000001            | Account not Found                            | Account was not found                                                   | Conta não encontrada                                                       |
| 403                      | PSC000012            | User is not allowed to do this transaction   | User is not allowed to do this transaction                              | Usuário não tem autorização para fazer essa transação                      |
| 404                      | PSC000025            | PixSchedule not Found                        | PixSchedule was not found                                               | PixSchedule não encontrada                                                 |
| 400                      | PSC000049            | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida                 |
| 400                      | PSC000052            | Incorrect Token                              | Token sent does not match expected                                      | Token enviado não condiz com o esperado                                    |
| 400                      | PSC000053            | Error Sending Token                          | An error occurred while resending token and its being investigated      | Um erro ocorreu ao reenviar token e está sendo investigado                 |
| 400                      | PSC000054            | Invalid Schedule Date                        | Schedule must be approved before the scheduled date                     | Agendamento deve ser aprovado em data anterior à programada para transação |
| 400                      | PSC000055            | Bad Request                                  | Schedule cannot be approved in current status                           | Agendamento pix não pode ser aprovado no status atual                      |

---

# Webhook de conclusão de Agendamento Pix

URL: /documentation/baas/pix/agendamento/webhook_de_conclusao_de_agendamento

Após a conclusão de um agendamento Pix, um webhook será enviado ao parceiro integrador com o resultado.

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeados de forma restrita. Campos adicionais podem ser incluídos aos payloads dos
webhooks retornados em nossas APIs.
:::

### Webhook Request Body

Request Body: Agendamento Concluído e Enviado

```json
{
  "webhook_type": "baas.pix_schedule.completed",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "created_at": "2024-07-10T16:17:28Z",
    "pix_message": null,
    "rejection_info": null,
    "rejection_reason": null,
    "request_control_key": "b8eb663e-10fe-4729-9db5-8f8c93de5001",
    "schedule_date": "2024-07-10",
    "schedule_key": "0c9091ab-079b-4a43-8b3d-d4ba36a23883",
    "schedule_status": "sent",
    "schedule_transfers": [
      {
        "created_at": "2024-07-10T16:19:33Z",
        "end_to_end_id": "E3240250220240710161922sSHNf8BjI",
        "pix_transfer_key": "427b70cd-73b0-45d1-bb4a-97f50f605022",
        "pix_transfer_status": "sent"
      }
    ],
    "target_account": {
      "account_branch": "0001",
      "account_digit": "8",
      "account_number": "1234567",
      "account_type": "checking_account",
      "ispb": "99999004",
      "owner_document_number": "***91111***",
      "owner_name": "Conta manual geral",
      "owner_person_type": "natural",
      "pix_key": null,
      "receiver_conciliation_id": null
    },
    "transaction_amount": 2.0,
    "updated_at": "2024-07-10T16:19:38Z"
  }
}
```

Request Body: Agendamento Concluído e Rejeitado

```json
{
  "created_at": "2024-07-11T16:03:54Z",
  "pix_message": null,
  "rejection_info": {
    "error_code": "PSC000030",
    "error_description": "The maximum amount of pix transfer attempts has been reached",
    "error_translation": "A maxima quantidade de retentativas de transacao pix foi atingida",
    "rejection_reason": "max_tries_exceeded"
  },
  "rejection_reason": null,
  "request_control_key": "b8eb663e-10fe-4729-9db5-8f8c93de0008",
  "schedule_date": "2024-07-11",
  "schedule_key": "8b262d82-3fc6-40f0-bfe5-bf18556ededb",
  "schedule_status": "rejected",
  "schedule_transfers": [
    {
      "created_at": "2024-07-11T16:04:21Z",
      "end_to_end_id": "E32402502202407111604ffoPVrGebI0",
      "pix_transfer_key": "c2c4e064-e684-450b-add5-07fb1efe8991",
      "pix_transfer_status": "rejected"
    },
    {
      "created_at": "2024-07-11T16:08:33Z",
      "end_to_end_id": "E32402502202407111608TQ3C4vRPRPk",
      "pix_transfer_key": "c30254db-86b2-4d8a-be01-29fa0d93ae92",
      "pix_transfer_status": "rejected"
    },
    {
      "created_at": "2024-07-11T16:09:20Z",
      "end_to_end_id": "E32402502202407111609zSUQQOvmMV6",
      "pix_transfer_key": "1a329248-fc39-4b49-9b95-8f1c1bb10c8b",
      "pix_transfer_status": "rejected"
    }
  ],
  "target_account": {
    "account_branch": "0001",
    "account_digit": "8",
    "account_number": "1234567",
    "account_type": "checking_account",
    "ispb": "99999004",
    "owner_document_number": "***91111***",
    "owner_name": "Conta manual geral",
    "owner_person_type": "natural",
    "pix_key": null,
    "receiver_conciliation_id": null
  },
  "transaction_amount": 2.0,
  "updated_at": "2024-07-11T16:09:21Z"
}
```

### Webhook Body Param

| Campo                 | Tipo   | Descrição                                                                          | Max. Caracteres                                                    |
|-----------------------|--------|------------------------------------------------------------------------------------|--------------------------------------------------------------------|
| `webhook_type`        | string | Um enumerador que define o tipo de evento sendo reportado                          | 23                                                                 |
| `webhook_datetime`    | string | Data e hora do envio do webhook                                                    | 20                                                                 |
| `transaction_amount`  | number | Valor da transferencia                                                             | 10                                                                 |
| `target_account`      | object | Conta destino do agendamento                                                       | **[Objeto target_account](#objeto-target_account)**                |
| `schedule_transfers`  | array  | Lista de tentativas de transferências realizadas pelo agendamento                  | lista de **[Objeto schedule_transfer](#schedule-transfer-object)** |
| `schedule_status`     | string | Status do agendamento                                                              | **[Enumerador schedule_status](#pix-schedule-status)**             |
| `schedule_key`        | string | Chave única de identificação do agendamento                                        | 36                                                                 |
| `schedule_date`       | string | Data a ser realizada a transação.                                                  | 10                                                                 |
| `request_control_key` | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36                                                                 |                                                                  |
| `rejection_info`      | object | Objeto com informaçôes sobre o evento de rejeição                                  |                                                                    |
| `rejection_reason`    | string | Motivo da rejeição                                                                 | **[Enumeradores rejection_reason](#enumeradores-rejection_reason)** |
| `pix_message`         | string | Mensagem a ser enviada junto à transferência Pix                                   | 140                                                                |
| `updated_at`          | string | Data e hora da última atualização do agendamento.                                  | 20                                                                 |
| `created_at`          | string | Data e hora de criação do agendamento.                                             | 20                                                                 |

## Pix Schedule Status

| Enumerador                 | Descrição                                                                                      |
|----------------------------|------------------------------------------------------------------------------------------------|
| **scheduled**              | Transação agendada                                                                             |
| **sent**                   | Agendamento concluído e enviado com sucesso. Estado final                                      |
| **rejected**               | Agendamento rejeitado durante criação ou execução. Estado final                                |
| **cancelled**              | Agendamento cancelado por solicitação de cliente. Estado final                                 |
| **pending_2fa_approval**   | Pendente de aprovação por autenticação de dois fatores                                         |
| **pending_creation**       | Agendamento em processo de criação (Estado transitório para agendamento em lote)               |
| **waiting_batch_approval** | Agendamento criado e vinculado a um lote aguardando aprovação por autenticação de dois fatores |

### Schedule Transfer Object

| Campo                 | Tipo   | Descrição                                                                                   | Caracteres                                                          |
|-----------------------|--------|---------------------------------------------------------------------------------------------|---------------------------------------------------------------------|
| `pix_transfer_key`    | uuidv4 | Chave única de identificação da transferência Pix no sistema QI.                            | 36                                                                  |
| `end_to_end_id` *     | string | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo) | 32                                                                  |
| `pix_transfer_status` | string | Status da transação.                                                                        | [Enumeradores pix_transfer_status](#enumerador-pix-transfer-status) |         |
| `created_at`          | string | Data e hora de criação da transação.                                                        | 20                                                                  |

### Enumerador Pix Transfer Status

| Enumerador   | Descrição                                           |
|--------------|-----------------------------------------------------|
| **sent**     | Transação enviada com sucesso. Estado final         |
| **rejected** | Transação rejeitada durante execução. Estado final  |
| **pending**  | Transação pendente de conclusão. Estado Transitório |

### Objeto target_account

| Campo                   | Tipo       | Descrição                                                                                               | Caracteres                                                        |
|-------------------------|------------|---------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `account_branch`        | string     | Agência da conta                                                                                        | 6                                                                 |
| `account_digit`         | string     | Dígito da conta                                                                                         | 1                                                                 |
| `account_number`        | string     | Número da conta                                                                                         | 20                                                                |
| `owner_document_number` | string     | CPF ou CNPJ (apenas números) do titular da conta                                                        | 14                                                                |
| `owner_name`            | string     | Nome do titular da conta                                                                                | 150                                                               |
| `owner_person_type`     | enumerator | Identificador de que o dono da conta enviada é uma pessoa física ou jurídica                            | **[Enumerador owner_person_type](#enumerador-owner_person_type)** |                                                    |
| `owner_name`            | string     | Nome do titular da conta                                                                                | 150                                                               |
| `account_type`          | enumerator | Tipo da conta                                                                                           | **[Enumerador account_type](#enumerador-account_type)**           |
| `ispb`                  | string     | Código de oito dígitos que identifica os bancos no sistema de transferência de reserva do Banco Central | 8                                                                 |
| `pix_key`               | string     | Chave pix alvo do agendamento                                                                           | 100                                                               |

### Enumerador owner_person_type

| Enum        | Description     |
|-------------|-----------------|
| **natural** | Pessoa física   |
| **legal**   | Pessoa jurídica |

### Enumerador account_type

| Enumerador           | Descrição           |
|----------------------|---------------------|
| **checking_account** | Conta Corrente      |
| **salary_account**   | Conta Salário       |
| **saving_account**   | Conta Poupança      |
| **payment_account**  | Conta de Pagamentos |

### Enumeradores rejection_reason

| Enumerador                                          | Descrição                                                                 |
|-----------------------------------------------------|---------------------------------------------------------------------------|
| `target_creation_error`                             | Erro na criação do agendamento                                         |
| `limit_date_for_approval_surpassed`                 | Data limite para aprovação ultrapassada                                  |
| `limit_date_for_batch_approval_surpassed`           | Data limite para aprovação de lote ultrapassada                          |
| `max_tries_exceeded`                                | Número máximo de tentativas excedido                                     |
| `rejection_by_transfer`                             | Rejeição pela transferência                                              |
| `target_change`                                     | Mudança na conta destino                                                  |
| `invalid_pix_key`                                   | Chave Pix inválida                                                        |
| `max_token_validation_attempts_exceeded`            | Número máximo de tentativas de validação de token excedido               |
| `error_sending_token`                               | Erro ao enviar token                                                     |
| `max_token_validation_attempts_exceeded_for_batch`  | Número máximo de tentativas de validação de token para lote excedido     |

---

# Aprovar Transação em Lote com Autenticação de Dois Fatores

URL: /documentation/baas/pix/batch/aprovar_transacao_em_lote_pix_2fa

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer_batch/ PIX_TRANSFER_BATCH_KEY /validate_token
MÉTODO PUT

### Path Params

| Campo                    | Tipo   | Descrição                                              | Caracteres |
|--------------------------|--------|--------------------------------------------------------|------------|
| `account_key`            | uuidv4 | Chave única de identificação da conta.                 | 36         |
| `pix_transfer_batch_key` | uuidv4 | Chave única de identificação da transação em lote pix. | 36         |

## Autenticação via Email e SMS

Request Body

```json
{
  "token": "329adf"
}
```

## Autenticação via Dispositivo

Para aprovar e finalizar a autenticação via dispositivo, a requisição deve ser enviada com um payload vazio. A validação ocorre internamente, sem necessidade de informações adicionais no corpo da requisição. É importante destacar que este endpoint só deve ser utilizado após a [solicitação de transação em lote](./solicitacao_de_transacao_em_lote_pix_2fa.md) ter sido iniciada.

Request Body

```json
{

}
```

### Body Params

| Campo   | Tipo   | Descrição                                                                                                                              | Caracteres |
|---------|--------|----------------------------------------------------------------------------------------------------------------------------------------|------------|
| `token` | string | Código de autenticação enviado ao aprovador de movimentações da conta **obrigatório para TFA via SMS ou e-mail**                       | 6          |

## Response

STATUS 201

Response Body: Transferência Enviada

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "pix_transfer_batch_status": "approved"
}
```

STATUS 4xx

Response Body: Transferência Rejeitada

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {
    "pix_transfer_batch_data": {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "pix_transfer_batch_status": "rejected"
    }
  }
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                           | Descrição (eng)<br/>`description`                                                                        | Descrição (ptbr)<br/>`translation`                                                   |
|--------------------------|----------------------|----------------------------------------------|----------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------|
| 404                      | PXT000178            | Pix Transfer Batch not found                 | A pix_transfer_batch not found                                                                           | Uma pix_transfer_batch não encontrada                                                |
| 400                      | PXT000180            | Invalid Status                               | Pix transfer Batch not in pending_2fa_approval status                                                    | Pix transfer em lote não está pendente de aprovação por autenticação de dois fatores |
| 400                      | PXT000171            | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached                                  | Número máximo de tentativas de validação de token atingida                           |
| 400                      | PXT000172            | Token Expired                                | Token has expired. Resend token or recreate transferToken has expired. Resend token or recreate transfer | Token expirado. Reenvie token ou recrie a transferência                              |
| 400                      | PXT000173            | Incorrect Token                              | Token sent does not match expected                                                                       | Token enviado não condiz com, o esperado                                             |
| 400                      | PXT000189            | Token Required                               | A token is required for SMS or email validation.                                                         | Um token é necessário para validação via SMS ou email.                               |

---

# Introdução a Transação em Lote Pix

URL: /documentation/baas/pix/batch/introducao_a_transacao_em_lote_pix

A QI Tech oferece a possibilidade de realizar várias transações pix com uma única chamada. Nesse sistema as transações
são realizadas de forma assíncrona. Caso na chamada inicial seja retornado um **http status 4xx**, nenhuma das
transações será realizada. Após a solicitação, o parceiro integrador receberá um webhook para cada transação informando
o status final da tentativa, podendo ser **rejected** ou **sent**.

## Autenticação de Dois Fatores

Assim como em transações pix, parceiros integradores com configuração de autenticação de dois fatores devem enviar o
objeto `tfa_info` com as informações de contato e envio de token.

---

# Listar Transações de um lote de uma conta

URL: /documentation/baas/pix/batch/listar_transacoes_de_um_lote_de_transacoes_pix

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer_batch/ PIX_TRANSFER_BATCH_KEY /pix_transfers
MÉTODO GET

### Path Params

| Campo                    | Tipo   | Descrição                                          | Caracteres |
|--------------------------|--------|----------------------------------------------------|------------|
| `account_key`            | uuidv4 | Chave única de identificação da conta.             | 36         |
| `pix_transfer_batch_key` | uuidv4 | Chave única de identificação da transação em lote. | 36         |

### Query Params

| Campo                       | Tipo    | Descrição                                                               | Caracteres                                                        |
|-----------------------------|---------|-------------------------------------------------------------------------|-------------------------------------------------------------------|
| `request_control_key`       | uuidv4  | Chave única de identificação da request utilizada pelo cliente.         | 36                                                                |
| `pix_transfer_batch_status` | string  | Status da transação Pix.                                                | [Enumerador pix_transfer_status](#enumerador-pix_transfer_status) |
| `page`                      | integer | Número da página requisitada. 1 por padrão                              |                                                                   |
| `page_size`                 | integer | Tamanho da página requisitada na consulta. 30 por padrão e valor máximo | Valor máximo de 30                                                |

### Enumerador pix_transfer_status

| Enumerador               | Descrição                                                |
|--------------------------|----------------------------------------------------------|
| **sent**                 | Transferência Pix realizada com sucesso.                 |
| **pending**              | Transferência Pix pendente.                              |
| **pending_2fa_approval** | Transferência Pix pendente de aprovação por dois fatores |
| **rejected**             | Transferência Pix rejeitada.                             |

### Response

STATUS 200

Response Body

```json
{
  "data": [
    {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "end_to_end_id": "E32402502202405081755SxyT2DDcVwc",
      "pix_transfer_status": "sent",
      "created_at": "2021-10-22T20:30:23.459Z"
    },
    {
      "request_control_key": "697c07c3-5398-48d2-a418-853323f85f97",
      "pix_transfer_key": "e95eabdb-4520-4c3d-a76f-99cb5b64724b",
      "end_to_end_id": "E32402502202405081755SxyT14Dtvwa",
      "pix_transfer_status": "sent",
      "created_at": "2021-10-22T20:30:23.459Z"
    },
    {
      "request_control_key": "ca35c526-b5a0-40d7-8c56-8566c77a34f4",
      "pix_transfer_key": "58d2fa9e-42ec-4779-b2fc-14ec98cbdca8",
      "end_to_end_id": "E32402502202405081755SsbT7DDcVwb",
      "pix_transfer_status": "rejected",
      "created_at": "2021-10-22T20:30:23.459Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "rows_per_page": 30
  }
}

```

---

# Listar Transações em Lote de uma conta

URL: /documentation/baas/pix/batch/listar_transacoes_em_lote_pix_de_uma_conta

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer_batches
MÉTODO GET

### Path Params

| Campo         | Tipo   | Descrição                              | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36         |

### Query Params

| Campo                 | Tipo    | Descrição                                                               | Caracteres         |
|-----------------------|---------|-------------------------------------------------------------------------|--------------------|
| `request_control_key` | uuidv4  | Chave única de identificação da request utilizada pelo cliente.         | 36                 |
| `date_from`           | string  | Data inicial. Formato "YYYY-MM-DD"                                      |                    |
| `date_to`             | string  | Data final. Formato "YYYY-MM-DD"                                        |                    |
| `page`                | integer | Número da página requisitada. 1 por padrão                              |                    |
| `page_size`           | integer | Tamanho da página requisitada na consulta. 30 por padrão e valor máximo | Valor máximo de 30 |

### Response

STATUS 200

Response Body

```json
{
  "data": [
    {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "pix_transfer_batch_status": "approved"
    },
    {
      "request_control_key": "939d1503-aa5a-49a6-ae3b-ff84122a6dd3",
      "pix_transfer_batch_key": "03cf9181-0eb9-480e-8bb4-66a5a9a6410e",
      "pix_transfer_batch_status": "rejected"
    },
    {
      "request_control_key": "43a14f3a-b2af-4a0e-8a74-70af2fca74a9",
      "pix_transfer_batch_key": "94ab9fad-9c65-4117-b9c3-a47b1269508f",
      "pix_transfer_batch_status": "approved"
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "rows_per_page": 30
  }
}

```

# Consultar Transação em Lote

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer_batch/ PIX_TRANSFER_BATCH_KEY
MÉTODO GET

### Path Params

| Campo                    | Tipo   | Descrição                                          | Caracteres |
|--------------------------|--------|----------------------------------------------------|------------|
| `account_key`            | uuidv4 | Chave única de identificação da conta.             | 36         |
| `pix_transfer_batch_key` | uuidv4 | Chave única de identificação da transação em lote. | 36         |

### Response

STATUS 200

Response Body

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "pix_transfer_batch_status": "approved"
}
```

---

# Solicitar reenvio de token para uma Transação Pix em Lote

URL: /documentation/baas/pix/batch/solicitacao_de_reenvio_de_token_para_lote

Um novo token será gerado e enviado para o aprovador de movimentação da conta. Caso o número limite de tentativas de
validação do token tenha sido excedida, não será permitido o reenvio.

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer_batch/ PIX_TRANSFER_BATCH_KEY /resend_token
MÉTODO PATCH

### Path Params

| Campo                      | Tipo   | Descrição                                          | Caracteres |
|----------------------------|--------|----------------------------------------------------|------------|
| `account_key` *            | uuidv4 | Chave única de identificação da conta.             | 36         |
| `pix_transfer_batch_key` * | uuidv4 | Chave única de identificação da transação em lote. | 36         |

Request Body

```json
{
  "contact_type": "sms"
}
```

### Body Params

| Campo          | Tipo   | Descrição                                                                                 | Caracteres |
|----------------|--------|-------------------------------------------------------------------------------------------|------------|
| `contact_type` | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** |

:::info Informação
Caso não seja enviado um `contact_type`, o token será enviado da forma solicitada originalmente.
:::

| Enumerador | Descrição                                         |
|------------|---------------------------------------------------|
| **sms**    | Envio por Mensagem de Texto para telefone celular |
| **email**  | Envio por correio eletrônico                      |

## Response

STATUS 202

Response Body: Transação Solicitada

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "pix_transfer_status": "pending_2fa_approval"
}
```

STATUS 4xx

Response Body: Transferência Rejeitada

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {
    "pix_transfer_data": {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "pix_transfer_status": "rejected"
    }
  }
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                           | Descrição (eng)<br/>`description`                                                                        | Descrição (ptbr)<br/>`translation`                                                         |
|--------------------------|----------------------|----------------------------------------------|----------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                  | Schema Error                                                                                             | Erro de Schema                                                                             |
| 404                      | PXT000004            | Account not found                            | Account not found for: \{account_datum\}                                                                 | Conta não encontrada para: \{account_datum\}                                               |
| 400                      | PXT000176            | Error Sending Token                          | An error occurred while resending token and its being investigated                                       | Um erro ocorreu ao reenviar token e está sendo investigado                                 |
| 404                      | PXT000178            | Pix Transfer Batch not found                 | A pix_transfer_batch not found                                                                           | Uma pix_transfer_batch não encontrada                                                      |
| 400                      | PXT000180            | Invalid Status                               | Pix transfer Batch not in pending_2fa_approval status                                                    | Pix transfer em lote não está pendente de aprovação por duṕla autenticação |
| 400                      | PXT000171            | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached                                  | Número máximo de tentativas de validação de token atingida                                 |
| 400                      | PXT000172            | Token Expired                                | Token has expired. Resend token or recreate transferToken has expired. Resend token or recreate transfer | Token expirado. Reenvie token ou recrie a transferência                                    |
| 400                      | PXT000173            | Incorrect Token                              | Token sent does not match expected                                                                       | Token enviado não condiz com, o esperado                                                   |

---

# Realizar Transação Pix em Lote

URL: /documentation/baas/pix/batch/solicitacao_de_transacao_em_lote_pix

A QI Tech oferece a possibilidade de realizar várias transações pix com uma única chamada. Nesse sistema as transações
são realizadas de forma assíncrona. Caso na chamada inicial seja retornado um **http status 4xx**, nenhuma das
transações será realizada. Após a solicitação, o parceiro integrador receberá um webhook para cada transação informando
o status final da tentativa, podendo ser **rejected** ou **sent**.

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer_batch
MÉTODO POST

```json
{
  "request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
  "pix_transfers": [
    {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "pix_transfer_type": "key",
      "target_pix_key": "target_pix_key@email.com",
      "transaction_amount": 500.65,
      "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
      "pix_message": "Ola Mundo"
    },
    {
      "request_control_key": "5fb20e2e-78e3-4ca7-bb36-515640ec2e78",
      "pix_transfer_type": "manual",
      "target_account": {
        "account_branch": "0001",
        "account_digit": "3",
        "account_number": "12345678",
        "owner_document_number": "32402502000135",
        "owner_name": "Qi Tech",
        "account_type": "checking_account",
        "ispb": "32402502"
      },
      "transaction_amount": 500.65,
      "pix_message": "Ola Mundo"
    },
    {
      "request_control_key": "10ad6e08-1a4c-403c-8122-178b0acf1dfa",
      "pix_transfer_type": "static_qr_code",
      "transaction_amount": 500.65,
      "end_to_end_id": "E73856642202309201429bZKfklNlbrb",
      "receiver_conciliation_id": "REC00000000000000000000009459463343",
      "target_pix_key": "target_pix_key@email.com",
      "pix_message": "Ola Mundo"
    }
  ]
}
```

## Path Params

| Campo         | Tipo   | Descrição                              | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36         |

### Body Params

| Campo                   | Tipo   | Descrição                                                                          | Caracteres                                               |
|-------------------------|--------|------------------------------------------------------------------------------------|----------------------------------------------------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36                                                       | 
| `pix_transfers` *       | array  | Lista de objetos pix_transfer vinculados ao lote.                                  | lista de **[Objeto pix_transfer](#objeto-pix_transfer)** |

### Objeto pix_transfer

| Campo                      | Tipo       | Descrição                                                                                                                                                                                                                                        | Caracteres                                                        |
|----------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `request_control_key` *    | uuidv4     | Chave única de identificação da request utilizada pelo cliente no formato uuid v4.                                                                                                                                                               | 36                                                                | 
| `pix_transfer_type` *      | enumerator | Tipo do pix a ser realizado.                                                                                                                                                                                                                     | **[Enumerador pix_transfer_type](#enumerador-pix_transfer_type)** |
| `target_pix_key`           | string     | Chave pix da conta a ser enviada a transação.                                                                                                                                                                                                    | 100                                                               |
| `target_account`           | Object     | Conta destino - Só deve ser enviada em transferências com `pix_transfer_type` do tipo **manual**.                                                                                                                                                | **[Objeto target_account](#objeto-target_account)**               |
| `receiver_conciliation_id` | string     | Identicação de conciliação do recebedor.                                                                                                                                                                                                         | 35                                                                |
| `transaction_amount` *     | number     | Valor da transferência.                                                                                                                                                                                                                          | 10                                                                |
| `end_to_end_id`            | string     | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na consulta de chave Pix. Só deve ser enviado se o `pix_transfer_type` for **key**, **static_qr_code** ou **static_qr_code** | 32                                                                |
| `pix_message`              | string     | Mensagem a ser enviada junto à transferência Pix.                                                                                                                                                                                                | 140                                                               |

### Objeto target_account

| Campo                     | Tipo       | Descrição                                           | Caracteres                                              |
|---------------------------|------------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string     | Agência da conta.                                   | 4                                                       |
| `account_digit` *         | string     | Dígito da conta.                                    | 1                                                       |
| `account_number` *        | string     | Número da conta.                                    | 20                                                      |
| `owner_document_number` * | string     | CPF ou CNPJ (apenas números) do titular da conta.   | 14                                                      |
| `owner_name` *            | string     | Nome do titular da conta.                           | 150                                                     |
| `account_type`*           | enumerator | Tipo da conta.                                      | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string     | Base no CNPJ da instituição financeira (8 dígitos). | 8                                                       |

### Enumerador account_type

| Enumerador           | Descrição           |
|----------------------|---------------------|
| **checking_account** | Conta Corrente      |
| **salary_account**   | Conta Salário       |
| **saving_account**   | Conta Poupança      |
| **payment_account**  | Conta de Pagamentos |

### Enumerador pix_transfer_type

| Enumerador          | Descrição                                                                                                                                                                                                                 |
|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **manual**          | Pix utilizando os dados da conta destino. Obrigatório enviar `target_account`                                                                                                                                             |
| **key**             | Pix utilizando uma chave pix. Obrigatório enviar `target_pix_key`. Recomendado enviar `end_to_end_id` da [consulta de chave](/documentation/pix_indireto/movimentacoes/consultar_chave_pix) pix caso tenha sido realizada |
| **static_qr_code**  | Pix utilizando um QR code estático. Obrigatório enviar o `end_to_end_id` retornado na [decodificação do QR code](/documentation/pix/decodificar_qr_code)                                                                  |
| **dynamic_qr_code** | Pix utilizando um QR code dinâmico. Obrigatório enviar o `end_to_end_id` retornado na [decodificação do QR code](/documentation/pix/decodificar_qr_code)                                                                  |

## Response

STATUS 201

Response Body: Transferência em lote Aprovada

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "pix_transfer_batch_status": "approved"
}
```

### Enumerador pix_transfer_batch_status

| Enumerador               | Descrição                                                            |
|--------------------------|----------------------------------------------------------------------|
| **approved**             | Transferência em lote aprovada e transações em processo de execução. |
| **rejected**             | Transferência em lote rejeitada                                      |
| **pending_2fa_approval** | Transferência em lote pendente de aprovação manual                   |

STATUS 4xx

Response Body: Transferência Rejeitada

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {
    "pix_transfer_batch_data": {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "pix_transfer_batch_status": "rejected"
    }
  }
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

:::info Informação
Os erros anteriormente listados para [transferência Pix](/documentation/baas/pix/realizar_transferencia) são
passiveis de serem retornados por este endpoint.
:::

---

# Realizar Transação Pix em Lote com Autenticação de Dois Fatores

URL: /documentation/baas/pix/batch/solicitacao_de_transacao_em_lote_pix_2fa

A QI Tech oferece a possibilidade de realizar várias transações pix com uma única chamada. Nesse sistema as transações
são realizadas de forma assíncrona. Caso na chamada inicial seja retornado um **http status 4xx**, nenhuma das
transações será realizada. Após a solicitação, o parceiro integrador receberá um webhook para cada transação informando
o status final da tentativa, podendo ser **rejected** ou **sent**.

Neste tipo de transação, é necessário a confirmação do pagamento via token enviado à pessoa com poderes de aprovação de
movimentação na conta credora.

A solicitação de transação Pix por parceiros integradores configurados para a utilização de autenticação de dois fatores
é realizada de forma similar ao descrito
em [realizar transação pix em lote](/documentation/baas/pix/batch/solicitacao_de_transacao_em_lote_pix). A diferença
ocorre na adição do objeto `tfa_info`, contento informações sobre o aprovador da transferência e a forma de contato, e o
status de uma solicitação bem sucedida que será sempre **pending_2fa_approval**.

O evento de notificação para o envio de `token` ao aprovador é **baas.token_validation.pix_transfer.batch**. É
possível [personalizar](/documentation/notificacoes/template) a mensagem enviada.

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer_batch
MÉTODO POST

## Autenticação via Email e SMS

Request Body: Transferência em Lote com TFA por SMS ou Email

```json
{
  "request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  },
  "pix_transfers": [
    {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "pix_transfer_type": "key",
      "target_pix_key": "target_pix_key@email.com",
      "transaction_amount": 500.65,
      "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
      "pix_message": "Ola Mundo"
    },
    {
      "request_control_key": "5fb20e2e-78e3-4ca7-bb36-515640ec2e78",
      "pix_transfer_type": "manual",
      "target_account": {
        "account_branch": "0001",
        "account_digit": "3",
        "account_number": "12345678",
        "owner_document_number": "32402502000135",
        "owner_name": "Qi Tech",
        "account_type": "checking_account",
        "ispb": "32402502"
      },
      "transaction_amount": 500.65,
      "pix_message": "Ola Mundo"
    },
    {
      "request_control_key": "10ad6e08-1a4c-403c-8122-178b0acf1dfa",
      "pix_transfer_type": "static_qr_code",
      "transaction_amount": 500.65,
      "end_to_end_id": "E73856642202309201429bZKfklNlbrb",
      "receiver_conciliation_id": "REC00000000000000000000009459463343",
      "target_pix_key": "target_pix_key@email.com",
      "pix_message": "Ola Mundo"
    }
  ]
}
```

## Autenticação via Dispositivo

Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`.

Request Body: Transferência em Lote com TFA por Dispositivo

```json
{
  "request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
    "contact_type": "device"
  },
  "pix_transfers": [
    {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "pix_transfer_type": "key",
      "target_pix_key": "target_pix_key@email.com",
      "transaction_amount": 500.65,
      "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
      "pix_message": "Ola Mundo"
    },
    {
      "request_control_key": "5fb20e2e-78e3-4ca7-bb36-515640ec2e78",
      "pix_transfer_type": "manual",
      "target_account": {
        "account_branch": "0001",
        "account_digit": "3",
        "account_number": "12345678",
        "owner_document_number": "32402502000135",
        "owner_name": "Qi Tech",
        "account_type": "checking_account",
        "ispb": "32402502"
      },
      "transaction_amount": 500.65,
      "pix_message": "Ola Mundo"
    },
    {
      "request_control_key": "10ad6e08-1a4c-403c-8122-178b0acf1dfa",
      "pix_transfer_type": "static_qr_code",
      "transaction_amount": 500.65,
      "end_to_end_id": "E73856642202309201429bZKfklNlbrb",
      "receiver_conciliation_id": "REC00000000000000000000009459463343",
      "target_pix_key": "target_pix_key@email.com",
      "pix_message": "Ola Mundo"
    }
  ]
}
```

## Path Params

| Campo         | Tipo   | Descrição                              | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36         |

### Body Params

| Campo                   | Tipo   | Descrição                                                                          | Caracteres                                               |
|-------------------------|--------|------------------------------------------------------------------------------------|----------------------------------------------------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36                                                       | 
| `pix_transfers` *       | array  | Lista de objetos pix_transfer vinculados ao lote.                                  | lista de **[Objeto pix_transfer](#objeto-pix_transfer)** |
| `tfa_info`*             | Object | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato.    | **[Objeto tfa_info](#objeto-tfa_info)**                  |

### Objeto tfa_info

| Campo                       | Tipo   | Descrição                                                                                                                        | Caracteres |
|-----------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------|------------|
| `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta.                                                                               | 11         |
| `session_id`                | string | Chave única de identificação da sessão do dispositivo no formato UUID v4 (obrigatório para TFA via dispositivo).                 | 36         |
| `contact_type`*             | string | Forma de contato com a pessoa aprovadora da conta, podendo ser **sms**, **email** ou **device**                                  |            |

### Objeto pix_transfer

| Campo                      | Tipo       | Descrição                                                                                                                                                                                                                                        | Caracteres                                                        |
|----------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `request_control_key` *    | uuidv4     | Chave única de identificação da request utilizada pelo cliente no formato uuid v4.                                                                                                                                                               | 36                                                                | 
| `pix_transfer_type` *      | enumerator | Tipo do pix a ser realizado.                                                                                                                                                                                                                     | **[Enumerador pix_transfer_type](#enumerador-pix_transfer_type)** |
| `target_pix_key`           | string     | Chave pix da conta a ser enviada a transação.                                                                                                                                                                                                    | 100                                                               |
| `target_account`           | Object     | Conta destino - Só deve ser enviada em transferências com `pix_transfer_type` do tipo **manual**.                                                                                                                                                | **[Objeto target_account](#objeto-target_account)**               | 10 |
| `receiver_conciliation_id` | string     | Identicação de conciliação do recebedor.                                                                                                                                                                                                         | 35                                                                |
| `transaction_amount` *     | number     | Valor da transferência.                                                                                                                                                                                                                          | 10                                                                |
| `end_to_end_id`            | string     | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na consulta de chave Pix. Só deve ser enviado se o `pix_transfer_type` for **key**, **static_qr_code** ou **static_qr_code** | 32                                                                |
| `pix_message`              | string     | Mensagem a ser enviada junto à transferência Pix.                                                                                                                                                                                                | 140                                                               |

### Objeto target_account

| Campo                     | Tipo       | Descrição                                           | Caracteres                                              |
|---------------------------|------------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string     | Agência da conta.                                   | 4                                                       |
| `account_digit` *         | string     | Dígito da conta.                                    | 1                                                       |
| `account_number` *        | string     | Número da conta.                                    | 20                                                      |
| `owner_document_number` * | string     | CPF ou CNPJ (apenas números) do titular da conta.   | 14                                                      |
| `owner_name` *            | string     | Nome do titular da conta.                           | 150                                                     |
| `account_type`*           | enumerator | Tipo da conta.                                      | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string     | Base no CNPJ da instituição financeira (8 dígitos). | 8                                                       |

### Enumerador account_type

| Enumerador           | Descrição           |
|----------------------|---------------------|
| **checking_account** | Conta Corrente      |
| **salary_account**   | Conta Salário       |
| **saving_account**   | Conta Poupança      |
| **payment_account**  | Conta de Pagamentos |

### Enumerador pix_transfer_type

| Enumerador          | Descrição                                                                                                                                                                                                                 |
|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **manual**          | Pix utilizando os dados da conta destino. Obrigatório enviar `target_account`                                                                                                                                             |
| **key**             | Pix utilizando uma chave pix. Obrigatório enviar `target_pix_key`. Recomendado enviar `end_to_end_id` da [consulta de chave](/documentation/pix_indireto/movimentacoes/consultar_chave_pix) pix caso tenha sido realizada |
| **static_qr_code**  | Pix utilizando um QR code estático. Obrigatório enviar o `end_to_end_id` retornado na [decodificação do QR code](/documentation/pix/decodificar_qr_code)                                                                  |
| **dynamic_qr_code** | Pix utilizando um QR code dinâmico. Obrigatório enviar o `end_to_end_id` retornado na [decodificação do QR code](/documentation/pix/decodificar_qr_code)                                                                  |

## Response

STATUS 201

Response Body: Transferência em Lote Solicitada

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "pix_transfer_batch_status": "pending_2fa_approval"
}
```

### Enumerador pix_transfer_batch_status

| Enumerador               | Descrição                                                                  |
|--------------------------|----------------------------------------------------------------------------|
| **approved**             | Transferência em lote aprovada e transações em processo de execução.       |
| **rejected**             | Transferência em lote rejeitada                                            |
| **pending_2fa_approval** | Agendamento em lote pendente de aprovação por autenticação de dois fatores |

STATUS 4xx

Response Body: Transferência Rejeitada

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {
    "pix_transfer_batch_data": {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "pix_transfer_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "pix_transfer_batch_status": "rejected"
    }
  }
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

:::info Informação
Os erros anteriormente listados para [transferência Pix](/documentation/baas/pix/realizar_transferencia) são
passiveis de serem retornados por este endpoint além dos erros listados abaixo.
:::

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                 | Descrição (eng)<br/>`description`                                     | Descrição (ptbr)<br/>`translation`                               |
|--------------------------|----------------------|------------------------------------|-----------------------------------------------------------------------|------------------------------------------------------------------|
| 400                      | PXT000168            | No approver permission             | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta |
| 400                      | PXT000169            | tfa_info is required               | Client must send object tfa_info                                      | Cliente deve enviar objeto tfa_info                              |
| 400                      | PXT000170            | Error occurred while sending token | An unexpected error occurred while sending token                      | Um erro inexperado ocorreu ao tentar enviar token                |

---

# Consulta de Dados de Chave Pix no Banco Central

URL: /documentation/baas/pix/consultar_chave_pix

## Request

ENDPOINT /pix_key/ PIX_KEY
MÉTODO GET

### Request Path Params

| Campo       | Tipo   | Descrição                      | Caracteres |
|-------------|--------|--------------------------------|------------|
| `pix_key` * | string | Chave Pix que será consultada. | 77         |

:::info Tipos de Chave Pix
A “pix_key” pode ser um CPF, CNPJ, E-mail, Celular ou uma Chave Aleatória (UUID), seguindo as seguintes formatações:

**CPF**: Número inteiro com 11 dígitos.

**CNPJ**: Número inteiro com 14 dígitos.

**E-mail**: Texto contendo ao menos um “@”.

**Celular**: Texto contendo os seguintes valores: “+55” + “DDD do celular“ + “Número Inteiro do Celular com no mínimo 8
e no máximo 9 dígitos”. Ex: “+5511987654321“.

**Chave Aleatória**: UUID4.
:::

### Request Query Params

| Campo             | Tipo   | Descrição                                                                                                                                                                                            | Caracteres |
|-------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `account_key` *   | uuidv4 | Chave única de identificação da conta.                                                                                                                                                               | 36         |
| `document_number` | string | CPF/CNPJ do titular da Chave Pix. Ao passar este parâmetro o campo `is_pix_key_owner` será retornado com um valor booleano identificando se o CPF/CNPJ informado é igual ao do titular da Chave Pix. | 14 ou 11   |

:::info Utilização de tokens de consulta
Para que o token de consulta de chave pix seja cobrado da pessoa titular da conta, é obrigatório que o `account_key`
seja enviado.
Caso não seja enviado o account_key, o token será cobrado do número de documento do parceiro integrador.
:::

## Response

STATUS 200

Response Body: Chave Ativa

```json
{
  "bank_code": "237",
  "end_to_end_id": "E3240250220230404185631R0kjZnC6G",
  "financial_institution": "BCO BRADESCO S.A.",
  "is_pix_key_owner": false,
  "ispb": "60746948",
  "owner_masked_document_number": "***.141.857-**",
  "owner_name": "Teste teste",
  "owner_person_type": "legal",
  "owner_trading_name": "Teste LTDA.",
  "pix_key": "teste@gmail.com"
}
```

| Campo                          | Tipo    | Descrição                                                                                                                                                                                                                                                                                     | Max. Caracteres                                                   |
|--------------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `bank_code`                    | string  | Código do banco registrador da Chave Pix. Pode ser retornado como nulo, para instituições que não possuem código de banco                                                                                                                                                                     | 3                                                                 |
| `end_to_end_id`                | string  | Indentificador único da consulta da chave Pix no Bacen. Deve ser enviado na transferência Pix para que o token consumido na consulta seja recuperado.                                                                                                                                         | 32                                                                |
| `financial_institution`        | string  | Nome da instituição financeira registradora da Chave Pix.                                                                                                                                                                                                                                     | 200                                                               |
| `is_pix_key_owner`             | boolean | Será retornado um valor boleano, caso o parâmetro `document_number` seja passado na request. Este campo informa se o CPF/CNPJ informado no parâmetro `document_number` é o mesmo do titular da Chave Pix. Será retornado um valor nulo caso o parâmetro `document_number` não seja informado. | -                                                                 |
| `ispb`                         | string  | ISPB do Participate detentor da Chave Pix.                                                                                                                                                                                                                                                    | 8                                                                 |
| `owner_masked_document_number` | string  | Número de CPF mascarado ou CNPJ do titular da Chave Pix.                                                                                                                                                                                                                                      | 14                                                                |
| `owner_name`                   | string  | Nome do titular da Chave Pix.                                                                                                                                                                                                                                                                 | 120                                                               |
| `owner_person_type`            | enum    | Natureza jurídica do titular da Chave Pix.                                                                                                                                                                                                                                                    | [Enumeradores Owner Person Type](#enumeradores-owner_person_type) |
| `owner_trading_name`           | string  | Nome fantasia do titular da Chave Pix (somente para `owner_person_type=legal`).                                                                                                                                                                                                               | 100                                                               |
| `pix_key`                      | string  | Chave Pix.                                                                                                                                                                                                                                                                                    | -                                                                 |

### Enumeradores account_type

| Enumerador         | Descrição          |
|--------------------|--------------------|
| `payment`          | Conta de pagamento |
| `checking`         | Conta de corrente  |
| `savings`          | Conta poupança     |
| `saving`           | Conta poupança     |
| `salary`           | Conta salário      |
| `saving_account`   | Conta poupança     |
| `payment_account`  | Conta de pagamento |
| `checking_account` | Conta de corrente  |
| `salary_account`   | Conta salário      |
| `escrow`           | Conta Vinculada    |

:::info
Diferentes enumeradores podem significar o mesmo tipo de conta devido a informação retornada por diferentes
instituições.
:::

### Enumeradroes owner_person_type

| Enumerador | Descrição |
|------------|-----------|
| `natural`  | string    |
| `legal`    | string    |

STATUS 4XX

Response Body

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo"
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`           | Descrição (eng)<br/>`Description`                                   | Descrição (ptbr)<br/>`translation`                                |
|-------------|----------------------|------------------------------|---------------------------------------------------------------------|-------------------------------------------------------------------|
| 404         | PIX000017            | Pix Key Not Found            | Pix key \{pix_key\} not found.                                      | A chave pix \{pix_key\} não foi encontrada.                       |
| 403         | PIX000080            | Not enough permission        | The selected agent doesn't have permission to access this resource. | O agente selecionado não tem permissão para acessar este recurso. |
| 429         | PIX000081            | Rate Limit Exceeded          | Rate Limit Exceeded                                                 | Limite de requisições excedido                                    |
| 404         | PIX000083            | Pix Key not found            | Pix Key \{pix_key\} not found for Alias \{alias_key\}               | Chave Pix \{pix_key\} não encontrada para o Alias \{alias_key\}   |
| 400         | PIX000084            | Only one query param allowed | Only one query param allowed                                        | Somente um parâmetro de consulta é permitido                      |

---

# Consultar Transferências

URL: /documentation/baas/pix/consultar_transferencias

## Consultar Transação Pix por pix_transfer_key

### Request

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer/ PIX_TRANSFER_KEY / PIX_TRANSFER_DIRECTION
MÉTODO GET

### Path Params

| Campo                      | Tipo       | Descrição                                             | Caracteres                                                                  |
|----------------------------|------------|-------------------------------------------------------|-----------------------------------------------------------------------------|
| `pix_transfer_direction` * | enumerator | Indicador do sentido da transação (entrada ou saída). | [Enumeradores pix_transfer_direction](#enumeradores-pix_transfer_direction) |
| `account_key` *            | uuidv4     | Chave única de identificação da conta QI.             | 36                                                                          |
| `pix_transfer_key` *       | uuidv4     | Chave única de identificação da transferência Pix.    | 36                                                                          |

### Enumeradores pix_transfer_direction

| Enumerador   | Descrição                    |
|--------------|------------------------------|
| **incoming** | Transferência Pix de entrada |
| **outgoing** | Transferência Pix de saída   |

### Response

STATUS 200

Response Body: Transferência Enviada (outgoing)

```json
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "pix_message": "Bom dia",
  "pix_transfer_type": "manual",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "updated_at": "2021-10-22T20:30:23.459Z",
  "created_at": "2021-10-22T20:30:23.459Z",
  "target_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "***02502000***",
    "owner_person_type": "legal",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502",
    "financial_institution_name": "QI SCD",
    "pix_key": null
  },
  "receiver_conciliation_id": null,
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "end_to_end_id": "E3240250220211022203051750897529",
  "pix_transfer_status": "sent",
  "transfer_amount": 126.97,
  "fee_amount": 0.0,
  "rejection_reason": null,
  "reversals": [
    {
      "end_to_end_id": "D35713491202309182058jlqdBkkHSWU",
      "transfer_amount": 0.01,
      "reversal_reason": "client_request",
      "pix_transfer_status": "received",
      "pix_transfer_key": "423866cd-0f3f-4cdd-904b-0d2e33273afd",
      "request_control_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0a",
      "created_at": "2021-10-23T20:30.459Z"
    }
  ]
}

```

Response Body: Transferência Rejeitada (outgoing)

```json
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "pix_message": "Bom dia",
  "pix_transfer_type": "manual",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "updated_at": "2021-10-22T20:30:23.459Z",
  "created_at": "2021-10-22T20:30:23.459Z",
  "target_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "***02502000***",
    "owner_person_type": "legal",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502",
    "pix_key": null
  },
  "receiver_conciliation_id": null,
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "end_to_end_id": "E3240250220211022203051750897529",
  "pix_transfer_status": "rejected",
  "transfer_amount": 126.97,
  "fee_amount": 0.0,
  "error_code": "PXT000132",
  "error_description": "Target account number is invalid.",
  "error_translation": "Número da conta de destino é inexistente ou inválido.",
  "reversals": []
}

```

Response Body: Devolução Enviada (outgoing)

```json
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "pix_message": "Bom dia",
  "pix_transfer_type": "reversal",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "updated_at": "2021-10-22T20:30:23.459Z",
  "created_at": "2021-10-22T20:30:23.459Z",
  "target_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "***02502000***",
    "owner_person_type": "legal",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502",
    "pix_key": null
  },
  "receiver_conciliation_id": null,
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "end_to_end_id": "E3240250220211022203051750897529",
  "pix_transfer_status": "sent",
  "transfer_amount": 126.97,
  "fee_amount": 0.0,
  "rejection_reason": null,
  "reversals": [],
  "original_incoming_pix_transfer": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3"
}

```

Response Body: Transferência Recebida (incoming)

```json
{
  "request_control_key": null,
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "end_to_end_id": "E18236120202308111235s14fddf2801",
  "pix_transfer_status": "received",
  "receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
  "transfer_amount": 126.97,
  "fee_amount": 0.0,
  "source_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "***02502000***",
    "owner_person_type": "legal",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502"
  },
  "pix_transfer_type": "dynamic_qr_code",
  "error_code": null,
  "error_description": null,
  "error_translation": null,
  "error_short_description": null,
  "reversals": []
}
```

Response Body: Devolução Recebida (incoming)

```json
{
  "request_control_key": null,
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "end_to_end_id": "E18236120202308111235s14fddf2801",
  "pix_transfer_status": "received",
  "receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
  "transfer_amount": 126.97,
  "fee_amount": 0.0,
  "source_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "***02502000***",
    "owner_person_type": "legal",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502"
  },
  "pix_transfer_type": "reversal",
  "error_code": null,
  "error_description": null,
  "error_translation": null,
  "error_short_description": null,
  "reversals": [],
  "original_outgoing_pix_transfer": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3"
}
```

Response Body: Transferência Em Análise Manual (incoming)

```json
{
  "request_control_key": null,
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "end_to_end_id": "E18236120202308111235s14fddf2801",
  "pix_transfer_status": "in_manual_analysis",
  "receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
  "transfer_amount": 126.97,
  "fee_amount": 0.0,
  "source_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "***02502000***",
    "owner_person_type": "legal",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502"
  },
  "pix_transfer_type": "dynamic_qr_code",
  "error_code": null,
  "error_description": null,
  "error_translation": null,
  "error_short_description": null,
  "reversals": []
}
```

Response Body: Transferência Rejeitada Pela Análise (incoming)

```json
{
  "request_control_key": null,
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "end_to_end_id": "E18236120202308111235s14fddf2801",
  "pix_transfer_status": "rejected_by_analysis",
  "receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
  "transfer_amount": 126.97,
  "fee_amount": 0.0,
  "source_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "***02502000***",
    "owner_person_type": "legal",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502"
  },
  "pix_transfer_type": "dynamic_qr_code",
  "error_code": "PXT000194",
  "error_description": "Incoming pix transfer rejected by manual analysis",
  "error_translation": "Transferência de Pix de entrada rejeitada pela análise manual",
  "error_short_description": null,
  "reversals": []
}
```

Response Body: Transferência Rejeitada (incoming)

```json
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "end_to_end_id": "E18236120202308111235s14fddf2801",
  "pix_transfer_status": "rejected",
  "receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
  "transfer_amount": 126.97,
  "fee_amount": 0.0,
  "source_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "***02502000***",
    "owner_person_type": "legal",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502"
  },
  "pix_transfer_type": "dynamic_qr_code",
  "reversals": []
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                          | Descrição (eng)<br/>`Description`                   | Descrição (ptbr)<br/>`translation`                                            |
|-------------|----------------------|---------------------------------------------|-----------------------------------------------------|-------------------------------------------------------------------------------|
| 400         | PXT000075            | Pix Transfer Key or End To End Not Provided | No pix transfer key or end to end id provided.      | Não foram fornecidos uma pix transfer key ou end to end id.                   |
| 404         | PXT000023            | Outgoing PIX Transfer Not Found             | Pix transfer key \{pix_transfer_key\} was not found | Transferência PIX de saída com chave \{pix_transfer_key\} não foi encontrada. |
| 403         | PIT000001            | User is not allowed to do this transaction  | User is not allowed to do this transaction          | Usuário não tem autorização para fazer essa transação                         |

---

# Tabela de Erros para Pix Transfer

URL: /documentation/baas/pix/erros_de_pix

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| HTTP Status Code | Error Code | Title                                                                   | Description                                                                                                                                                                                          | Translation                                                                                                                                                                                                                                 |
|------------------|------------|-------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 500              | QIT000500  | Internal Error                                                          | An internal error has occurred and its being investigated                                                                                                                                            | Um erro interno aconteceu e está sendo investigado                                                                                                                                                                                          |
| 404              | QIT000404  | Bad Request                                                             | The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible                                                                      | O recurso solicitado não pôde ser encontrado, mas pode estar disponível no futuro. Requests subsequentes do cliente são permitidos                                                                                                          |
| 400              | QIT000400  | Bad Request                                                             | The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, size too large, invalid request message framing, or deceptive request routing)    | O servidor não pode ou não processará a requisição devido a um erro do cliente (por exemplo, sintaxe de requisição malformada, tamanho muito grande, enquadramento de mensagem de requisição inválida ou roteamento de requisição enganoso) |
| 753              | QIT000753  | Syntax Error                                                            | Malformed JSON. Could not decode the request body. The JSON was incorrect, empty or not encoded as UTF-8                                                                                             | JSON malformado. Não foi possível decodificar o corpo da requisição. O JSON estava incorreto, vazio ou não foi codificado como UTF-8                                                                                                        |
| 400              | QIT000001  | Bad Request                                                             | (custom)                                                                                                                                                                                             | Payload Inválido                                                                                                                                                                                                                            |
| 403              | QIT000002  | Permission Validator Error                                              | Request must be internal                                                                                                                                                                             | Request deve ser interna                                                                                                                                                                                                                    |
| 403              | QIT000003  | Permission Validator Error                                              | Request must be from a master user                                                                                                                                                                   | Request deve ser de usuário master                                                                                                                                                                                                          |
| 403              | PIT000001  | User is not allowed to do this transaction                              | User is not allowed to do this transaction                                                                                                                                                           | Usuário não tem autorização para fazer essa transação                                                                                                                                                                                       |
| 400              | PIT000003  | Bad Request                                                             | Insufficient account balance for transfer and fee amount                                                                                                                                             | Saldo de conta insuficiente para a transação e a taxa                                                                                                                                                                                       |
| 400              | PIT000004  | Bad Request                                                             | Transaction amount is over limit                                                                                                                                                                     | O total da transação é superior ao limite                                                                                                                                                                                                   |
| 404              | PIX000056  | Not Found                                                               | Pix key inquiry not found                                                                                                                                                                            | Consulta de chave pix não encontrada                                                                                                                                                                                                        |
| 400              | PXT000002  | Person is not Account Owner                                             | Person \{person_key\} is not account owner                                                                                                                                                           | A pessoa \{person_key\} não é dona da conta                                                                                                                                                                                                 |
| 400              | PXT000003  | Account is Closed                                                       | Account \{account_key\} is closed                                                                                                                                                                    | Conta \{account_key\} está fechada                                                                                                                                                                                                          |
| 404              | PXT000004  | Account not found                                                       | Account not found for: \{account_datum\}                                                                                                                                                             | Conta não encontrada para: \{account_datum\}                                                                                                                                                                                                |
| 404              | PXT000005  | Account not found                                                       | Account not found for pix key: \{pix_key\}                                                                                                                                                           | Conta não encontrada para chave pix: \{pix_key\}                                                                                                                                                                                            |
| 400              | PXT000006  | Account not found                                                       | Account was not provided for this query                                                                                                                                                              | Chave de identificação da conta não foi fornecida                                                                                                                                                                                           |
| 403              | PXT000008  | Invalid Permission                                                      | Person \{person_key\} does not have administration roles for account \{account_key\}                                                                                                                 | Pessoa \{person_key\} não tem permissões de administrador para a conta \{account_key\}                                                                                                                                                      |
| 404              | PXT000009  | Person Not Found                                                        | Person with document number \{person_document_number\} not found                                                                                                                                     | Pessoa com número de documento \{person_document_number\} não encontrada                                                                                                                                                                    |
| 400              | PXT000010  | Account is Blocked                                                      | Account \{account_key\} is blocked                                                                                                                                                                   | Conta \{account_key\} está bloqueada                                                                                                                                                                                                        |
| 400              | PXT000011  | Account Type Mismatch                                                   | Given account type does not match one registered                                                                                                                                                     | O tipo de conta fornecido não condiz com o registrado                                                                                                                                                                                       |
| 400              | PXT000012  | Invalid Document Number                                                 | Given \{document_number\} document number is invalid                                                                                                                                                 | CPF/CNPJ \{document_number\} fornecido não é válido                                                                                                                                                                                         |
| 400              | PXT000013  | Account Validation Failure                                              | Account validation for received end_to_end_id is not valid                                                                                                                                           | Validação da conta para o end_to_end_id recebido não é válida                                                                                                                                                                               |
| 400              | PXT000014  | Target Account mismatch                                                 | Received target account data doesn't match validated account                                                                                                                                         | Dados da conta de destino recebida não corresponde à conta validada                                                                                                                                                                         |
| 400              | PXT000015  | Reversal date expired                                                   | Reversal original transaction is older than 90 days                                                                                                                                                  | A data de criação da transação original é mais antiga que 90 dias                                                                                                                                                                           |
| 400              | PXT000016  | Reversal Account Flow Mismatch                                          | Reversal account flow does not match original pix transfer's                                                                                                                                         | O fluxo de contas de destino e de origem não correspondem ao da transação original                                                                                                                                                          |
| 400              | PXT000017  | Reversal Too Great                                                      | Reversal transfers sum amount surpasses that of original pix transfer                                                                                                                                | A soma das transações de devolução ultrapassam o valor da transação pix original                                                                                                                                                            |
| 404              | PXT000018  | Reversal Original Transfer not Found                                    | Reversal original pix transfer not found                                                                                                                                                             | Transferência original da devolução não foi encontrada                                                                                                                                                                                      |
| 400              | PXT000019  | Chargeback Validation Failure                                           | Previously done validation values do match with incoming chargeback                                                                                                                                  | Os valores da atual devolução não correspondem com aqueles das validação                                                                                                                                                                    |
| 404              | PXT000020  | Incoming PIX Validation Not Found                                       | No previously done validation was found for given end to end id                                                                                                                                      | Não se encontrou validação anterior para o id ponta-a-ponta provido                                                                                                                                                                         |
| 400              | PXT000021  | Incoming Validation Already Done                                        | There's an existing validation for end to end id \{end_to_end_id\}                                                                                                                                   | A validação para o id ponta a ponta \{end_to_end_id\} já foi feita                                                                                                                                                                          |
| 400              | PXT000022  | Wrong ISPB                                                              | ISPB is different from 32402502                                                                                                                                                                      | ISPB é diferente de 32402502                                                                                                                                                                                                                |
| 404              | PXT000023  | Outgoing PIX Transfer Not Found                                         | Pix transfer key \{pix_transfer_key\} was not found                                                                                                                                                  | Transferência PIX de saída com chave \{pix_transfer_key\} não foi encontrada                                                                                                                                                                |
| 400              | PXT000024  | PIX Transfer Not Pending Confirmation                                   | Pix transfer \{pix_transfer_key\} is not pending confirmation                                                                                                                                        | Transferência PIX \{pix_transfer_key\} não está aguardando confirmação                                                                                                                                                                      |
| 400              | PXT000025  | Invalid pix transfer key                                                | Pix transfer \{pix_transfer_key\} is not pending confirmation or does not exist                                                                                                                      | Transferência PIX \{pix_transfer_key\} não está aguardando confirmação ou não existe                                                                                                                                                        |
| 400              | PXT000025  | Outgoing PIX Transfer Beyond of Transaction Limit                       | Pix transfer value R$ \{transfer_amount\} beyond of transaction limit R$ \{transaction_limit\}                                                                                                       | Transferência PIX valor R$ \{transfer_amount\} além do limite R$ \{transaction_limit\}                                                                                                                                                      |
| 400              | PXT000026  | Search Params Error                                                     | Invalid integer value for page or size querystring parameters                                                                                                                                        | Valor inválido para parâmetros de página ou tamanho de página                                                                                                                                                                               |
| 403              | PXT000027  | Invalid Permission                                                      | Selected Person does not have administration roles                                                                                                                                                   | Pessoa selecionada não tem credencial de administrador                                                                                                                                                                                      |
| 400              | PXT000028  | Account Key can not be null when search for config fees                 | Account key can not be null when search for config fees                                                                                                                                              | A chave de conta não pode ser nula quando buscar por configurações de tarifa                                                                                                                                                                |
| 400              | PXT000029  | Invalid Value for Enumerator Type                                       | Invalid value \{value\} used for enumerator type \{enumerator\}                                                                                                                                      | Valor inválido \{value\} para o tipo de enumerador \{enumerator\}                                                                                                                                                                           |
| 400              | PXT000030  | To update or delete a fee configuration must be provided a valid fee ID | To update or delete a fee configuration must be provided a valid fee ID. ID provided: \{identification\}                                                                                             | Para atualizar ou remover uma configuração de tarifa deve ser fornecido um ID válido. ID fornecido: \{identification\}                                                                                                                      |
| 400              | PXT000031  | Fee configuration already exists                                        | Fee configuration already exists for \{person_owner_type\} account with: purpose= \{purpose\} and \{transfer_type\}. Please use update                                                               | Configuração de tarifa já existe para conta \{person_owner_type\} com: finalidade= \{purpose\} e \{transfer_type\}. Por favor utilize o update                                                                                              |
| 400              | PXT000032  | Unable To Delete Default Configuration                                  | Unable To Delete Default Configuration. Please use update                                                                                                                                            | Não é permitido deletar uma configuração default. Por favor utilize o update                                                                                                                                                                |
| 400              | PXT000033  | Target Account Must Not Be Source Account                               | Target Account Must Not Be Source Account                                                                                                                                                            | A conta de destino não pode ser a conta de origem                                                                                                                                                                                           |
| 400              | PXT000034  | Account Key Must Not Be Null                                            | You Need To Define An Account Key To Create A Fee Configuration                                                                                                                                      | É necessário definir uma chave de conta para definir uma configuração de tarifa para a mesma                                                                                                                                                |
| 400              | PXT000035  | Limit configuration already exists                                      | Limit configuration already exists for \{account_key\} account for period(s) \{existing_limit_periods\}. Please use update                                                                           | Configuração de limite já existe para conta \{account_key\} para o período(s) \{existing_limit_periods\}. Por favor utilize o update                                                                                                        |
| 400              | PXT000036  | No limit configuration found. Please set default configurations         | No limit configuration found. Please set default configurations for \{person_type\} person                                                                                                           | Não foi possível encontrar configurações de limite, favor utilizar configurações padrões para \{person_type\}                                                                                                                               |
| 404              | PXT000037  | Person Not Found                                                        | Person with key \{person_key\} not found                                                                                                                                                             | Pessoa com chave \{person_key\} não encontrada                                                                                                                                                                                              |
| 400              | PXT000038  | Not enough balance                                                      | Not enough balance to pay for incoming pix fee                                                                                                                                                       | Saldo insuficiente para pagar por tarifa de pix de entrada                                                                                                                                                                                  |
| 400              | PXT000039  | Invalid Batch Limit Configuration                                       | Received \{counter_config\} wrong configuration(s) for accounts: \{account_keys\}. Configurations must be None or positive float                                                                     | Recebido \{counter_config\} configuração(ões) erradas para contas: \{account_keys\}. Configurações devem ser None ou float positivo                                                                                                         |
| 400              | PXT000040  | Bad Request                                                             | Amount limit must be null, positive float or int. Sent \{limit\}                                                                                                                                     | Limite deve ser nulo, positivo inteiro ou decimal. Sent \{limit\}                                                                                                                                                                           |
| 404              | PXT000041  | Not Found                                                               | Qr Code not found                                                                                                                                                                                    | Qr Code não encontrado                                                                                                                                                                                                                      |
| 400              | PXT000042  | Bad Request                                                             | There is no ISPB number for this Bank Code                                                                                                                                                           | Não existe código ISPB para esse Bank Code                                                                                                                                                                                                  |
| 400              | PXT000043  | Bad Request                                                             | Invalid decimal amount, sent \{number\}                                                                                                                                                              | Valor decimal inválido, enviado \{number\}                                                                                                                                                                                                  |
| 404              | PXT000044  | Not Found                                                               | Pix Key \{pix_key\} is not activated                                                                                                                                                                 | Chave PIX \{pix_key\} não está ativada                                                                                                                                                                                                      |
| 404              | PXT000045  | Not Found                                                               | QR Code Payment is invalid for Receiver Conciliation ID \{receiver_conciliation_id\}                                                                                                                 | Pagamento via QR Code é inválido para Cliente Recebedor \{receiver_conciliation_id\}                                                                                                                                                        |
| 403              | PXT000046  | Invalid Permission                                                      | Only Master can change resource configuration                                                                                                                                                        | Apenas o Administrador pode alterar as configurações do recurso                                                                                                                                                                             |
| 400              | PXT000047  | Bad Request                                                             | \{field_name\} could not be larger than \{max_length\} characters                                                                                                                                    | \{field_name\} não pode ser maior que \{max_length\} caracteres                                                                                                                                                                             |
| 400              | PXT000048  | Bad Request                                                             | Emoji not allowed in pix message                                                                                                                                                                     | Emoji não é permitido na mensagem pix                                                                                                                                                                                                       |
| 400              | PXT000049  | Bad Request                                                             | When paying QR Code end_to_end_id could not be none                                                                                                                                                  | Ao pagar um QR Code o end_to_end_id não pode ser nulo                                                                                                                                                                                       |
| 400              | PXT000050  | Bad Request                                                             | Could not read QR Code type, please try to read qr_code again                                                                                                                                        | Não foi possível ler o tipo de QR Code. Favor tente ler o qr_code outra vez                                                                                                                                                                 |
| 400              | PXT000051  | Invalid Requester Configuration Info                                    | The configuration \{configuration\} format sent is not valid                                                                                                                                         | O formato enviado da configuração \{configuration\} não é válido                                                                                                                                                                            |
| 400              | PXT000052  | Bad Request                                                             | Only Master QI Tech can change default limits configurations                                                                                                                                         | Apenas o Master QI Tech pode alterar as configurações de limites padrões                                                                                                                                                                    |
| 400              | PXT000053  | Bad Request                                                             | QrCode already paid                                                                                                                                                                                  | Qr Code já Pago                                                                                                                                                                                                                             |
| 400              | PXT000054  | Bad Request                                                             | Invalid Pix Key, sent \{pix_key\}                                                                                                                                                                    | Chave pix inválida, enviado \{pix_key\}                                                                                                                                                                                                     |
| 400              | PXT000055  | Pix error                                                               | Invalid Limit Type Sent                                                                                                                                                                              | Tipo inválido de limite enviado                                                                                                                                                                                                             |
| 400              | PXT000056  | Bad Request                                                             | Only Master QI Tech can handle limit events                                                                                                                                                          | Apenas o Master QI Tech pode alterar eventos de limites                                                                                                                                                                                     |
| 400              | PXT000057  | Bad Request                                                             | Invalid request_key or no request found, request_key sent \{request_key\}                                                                                                                            | Requisição inválida ou requisição não encontrada, requisição enviada \{request_key\}                                                                                                                                                        |
| 400              | PXT000058  | Bad Request                                                             | When limit request is rejected, rejected reason could not be null                                                                                                                                    | Quando uma requisição de limite é rejeitada, o motivo não pode ser nulo                                                                                                                                                                     |
| 400              | PXT000059  | Bad Request                                                             | Target document number is not account owner document number                                                                                                                                          | O documento informado não é o mesmo da conta de destino                                                                                                                                                                                     |
| 400              | PXT000060  | Bad Request                                                             | Nonexistent account in destination bank                                                                                                                                                              | Conta inexistente no banco de destino                                                                                                                                                                                                       |
| 409              | PXT000061  | Conflict                                                                | End to end id invalid. A pix transfer with the end to end id \{end_to_end\} has already been registered!                                                                                             | End to end id inválido. Uma transação pix com o identificador único \{end_to_end\} já foi registrada!                                                                                                                                       |
| 409              | PXT000062  | Conflict                                                                | Missing fields detected on jd connector response: \{response\}                                                                                                                                       | Campos faltantes detectados em resposta do JD connector: \{response\}                                                                                                                                                                       |
| 409              | PXT000063  | Conflict                                                                | Unexpected response: \{response\}                                                                                                                                                                    | Resposta inesperada: \{response\}                                                                                                                                                                                                           |
| 400              | PXT000064  | Bad Request                                                             | For Manual Pix Transfer Type a target account must be provided                                                                                                                                       | Para transação pix do tipo manual, uma conta destino deve ser fornecida                                                                                                                                                                     |
| 400              | PXT000065  | Bad Request                                                             | Pix transfer sent was already rejected. Rejection_reason: \{error_description\}                                                                                                                      | Pix transfer já rejeitada. Motivo da rejeição: \{error_description_translated\}                                                                                                                                                             |
| 404              | PXT000067  | Pix Key is Unregistered                                                 | Pix key \{pix_key\} is not currently used                                                                                                                                                            | A chave pix \{pix_key\} não está sendo utilizada                                                                                                                                                                                            |
| 422              | PXT000068  | Pix Key is Unregistered                                                 | Pix key inquiry timeout. Please try again                                                                                                                                                            | Consulta de chave pix excedeu o tempo limite. Por favor tente novamente                                                                                                                                                                     |
| 400              | PXT000069  | Error in Qr Code Payload Request                                        | An error occurred while requesting the qr code payload to the registry institution                                                                                                                   | Um erro ocorreu durante a requisição do payload do qr code para a instituição de registro                                                                                                                                                   |
| 400              | PXT000070  | Invalid Qr Code Format                                                  | The Qr Code format is invalid, please enter a valid Qr Code                                                                                                                                          | O formato do Qr Code é inválido, por favor insira um Qr Code válido                                                                                                                                                                         |
| 400              | PXT000071  | Invalid Qr Code Type                                                    | The Qr Code payload given did not provide a proper Qr Code type                                                                                                                                      | O payload de QR Code fornecido não contêm um tipo de Qr Code Válido                                                                                                                                                                         |
| 422              | PXT000072  | Pending Transfer                                                        | The transaction (\{end_to_end_id\}) could not be completed and is pending confirmation                                                                                                               | Não foi possível concluir a transação (\{end_to_end_id\}) e ela está pendente de confirmação                                                                                                                                                |
| 404              | PXT000073  | Outgoing PIX Transfer Not Found                                         | Pix transfer end to end id \{end_to_end_id\} was not found                                                                                                                                           | Transferência PIX de saída com identificador único \{end_to_end_id\} não foi encontrada                                                                                                                                                     |
| 400              | PXT000074  | Invalid Transaction Status                                              | Unable to update transaction status. The status \{status\} is invalid                                                                                                                                | Não foi possível atualizar o status da transação. O status \{status\} é invalido                                                                                                                                                            |
| 400              | PXT000075  | Pix Transfer Key or End To End Not Provided                             | No pix transfer key or end to end id provided                                                                                                                                                        | Não foram fornecidos uma pix transfer key ou end to end id                                                                                                                                                                                  |
| 404              | PXT000076  | Incoming PIX Transfer Not Found                                         | Pix transfer key \{pix_transfer_key\} was not found                                                                                                                                                  | Transferência PIX de entrada com chave \{pix_transfer_key\} não foi encontrada                                                                                                                                                              |
| 400              | PXT000077  | Pix Transfer Receipt not allowed                                        | Pix Transfer Receipt cannot be generated for rejected transfers                                                                                                                                      | Recibo de transação pix não pode ser gerado para transações rejeitadas                                                                                                                                                                      |
| 400              | PXT000078  | Pix Transfer Receipt not available                                      | Receipt not available due to pix transfer currently being processed. Wait a few minutes and try again                                                                                                | Comprovante não disponível pois transação Pix está em processamento. Por favor, aguarde alguns minutos e tente novamente                                                                                                                    |
| 400              | PXT000079  | Bad Request                                                             | Insufficient billing account balance for fee                                                                                                                                                         | Saldo de conta de cobrança insuficiente para a taxa                                                                                                                                                                                         |
| 400              | PXT000080  | Bad Request                                                             | Could not complete the transaction and the transaction was rejected                                                                                                                                  | Não foi possível concluir a transação e a transferência foi rejeitada                                                                                                                                                                       |
| 400              | PXT000081  | Bad Request                                                             | Pix key not sent                                                                                                                                                                                     | Chave PIX não enviada                                                                                                                                                                                                                       |
| 400              | PXT000082  | Bad Request                                                             | The sent PIX key \{pix_key\} does not match the decoded PIX key                                                                                                                                      | A chave PIX enviada \{pix_key\} não coincide com a chave PIX decodificada                                                                                                                                                                   |
| 400              | PXT000083  | Bad Request                                                             | Pix rejected.                                                                                                                                                                                        | Pix rejeitado.                                                                                                                                                                                                                              |
| 404              | PXT000084  | Original Pix Transfer Was Not Found                                     | Original Pix Transfer Was Not Found                                                                                                                                                                  | A transação PIX original não foi encontrada                                                                                                                                                                                                 |
| 403              | PXT000085  | Invalid Permission                                                      | User do not has sufficient permissions                                                                                                                                                               | Usuário não tem permissões suficientes                                                                                                                                                                                                      |
| 400              | PXT000086  | Update Default Failed                                                   | To update default requester configuration send default as requester_key in url                                                                                                                       | Para alterar a configuracao de requester padrao, envie default como requester_key na url                                                                                                                                                    |
| 400              | PXT000087  | Amount limit not approved try a lower value                             | Amount limit for \{person_type\} person not approved, please try a lower value                                                                                                                       | Limite total não aprovado para pessoa \{person_type\}, por favor tente um menor                                                                                                                                                             |
| 400              | PXT000088  | Bad Request                                                             | Invalid account information when translating to account DTO                                                                                                                                          | Informações da conta inválidas na tradução do DTO                                                                                                                                                                                           |
| 409              | PXT000089  | Incoming Pix not pending                                                | Incoming Pix with pix transfer key \{pix_transfer_key\} is not pending                                                                                                                               | Transferência de Entrada PIX \{pix_transfer_key\} não está pendente                                                                                                                                                                         |
| 503              | PXT000090  | Service Unavailable                                                     | Pix transfer is not available right now. Please wait or use TED service                                                                                                                              | Transferência Pix não esta disponível no momento. Favor aguardar ou utilizar TED                                                                                                                                                            |
| 400              | PXT000091  | Bad Request                                                             | System account has no limits. Account key \{account_key\} is system account                                                                                                                          | Contas de sistema não possuem limite. Chave de conta \{account_key\} é conta de sistema                                                                                                                                                     |
| 422              | PXT000092  | Invalid Account Type                                                    | Pix is not yet implemented for non-checking or non-escrow account types                                                                                                                              | Transações Pix não estão implementadas para conta que não sejam escrow ou livres                                                                                                                                                            |
| 400              | PXT000093  | Bad Request                                                             | Fee must be either fixed_amount or percentage                                                                                                                                                        | Tarifas fixas e percentuais são mutuamente exclusivas                                                                                                                                                                                       |
| 400              | PXT000094  | Bad Request                                                             | Failed to fetch transactions by origin key                                                                                                                                                           | Falha ao obter transações por origin key                                                                                                                                                                                                    |
| 400              | PXT000095  | Unforeseen Error Scenario on Reprocess                                  | Scenario: pix_transfer_key: \{pix_transfer_key\}, pix_status: \{pix_status\}, bacen_status: \{bacen_status\}, internal_tx: \{internal_tx\}, reverse_tx: \{reverse_tx\}, external_tx: \{external_tx\} | Cenário: pix_transfer_key: \{pix_transfer_key\}, pix_status: \{pix_status\}, bacen_status: \{bacen_status\}, internal_tx: \{internal_tx\}, reverse_tx: \{reverse_tx\}, external_tx: \{external_tx\}                                         |
| 417              | PXT000096  | Expectation Failed                                                      | Unexpected error trying to reprocess external transaction for outgoing Pix \{pix_transfer_key\}                                                                                                      | Erro inesperado ao tentar refazer transação externa de saída Pix \{pix_transfer_key\}                                                                                                                                                       |
| 417              | PXT000097  | Expectation Failed                                                      | Unexpected error trying to reprocess reverse transaction for outgoing Pix \{pix_transfer_key\}                                                                                                       | Erro inesperado ao tentar refazer transação reversa de saída Pix \{pix_transfer_key\}                                                                                                                                                       |
| 400              | PXT000098  | Expectation Failed                                                      | Unexpected subtype encountered: \{subtype\}                                                                                                                                                          | Subtipo inesperado encontrado: \{subtype\}                                                                                                                                                                                                  |
| 400              | PXT000099  | Error retrieving account data                                           | Error while retrieving data for account_key \{account_key\}                                                                                                                                          | Erro ao recolher informações da conta \{account_key\}                                                                                                                                                                                       |
| 400              | PXT000100  | Rejected by external analysis                                           | The transaction was rejected by external analysis                                                                                                                                                    | A transação foi rejeitada pela análise externa                                                                                                                                                                                              |
| 400              | PXT000101  | Bad Request                                                             | It is not allowed to set a maximum or a minumum value to a fixed amount fee                                                                                                                          | Não é permitido inserir valores de mínimo e máximo para tarifas de valor fixo                                                                                                                                                               |
| 404              | PXT000101  | Requester Configuration not found                                       | There is no Requester Configuration attributed to requester_key given                                                                                                                                | Não há Requester Configuration para a requester_key enviada                                                                                                                                                                                 |
| 400              | PXT000102  | Invalid caas_client_key                                                 | There caas_client_key is not valid                                                                                                                                                                   | A caas_client_key enviada não é válida                                                                                                                                                                                                      |
| 406              | PXT000103  | \{key\} must be a valid uuid v4 string                                  | \{key\} was not accepted for not being a valid uuid v4 string                                                                                                                                        | \{key\} não foi aceito por não ser uma string uuid v4 válida                                                                                                                                                                                |
| 400              | PXT000104  | Invalid key format                                                      | The key \{key\} is invalid                                                                                                                                                                           | A chave \{key\} é inválida                                                                                                                                                                                                                  |
| 400              | PXT000105  | Invalid Key Type                                                        | Invalid Key Type: \{key_type\}                                                                                                                                                                       | Tipo de chave inválido: \{key_type\}                                                                                                                                                                                                        |
| 400              | PXT000106  | Bad Request                                                             | The key sent does not match the given key type                                                                                                                                                       | A chave enviada não corresponde ao tipo de chave fornecido                                                                                                                                                                                  |
| 400              | PXT000107  | Invalid UUID                                                            | The UUID \{uuid\} is invalid                                                                                                                                                                         | O UUID \{uuid\} é inválido                                                                                                                                                                                                                  |
| 404              | PXT000108  | Invoice not found                                                       | The invoice with \{invoice_id\} was not found                                                                                                                                                        | A fatura com o id \{invoice_id\} não foi encontrada                                                                                                                                                                                         |
| 404              | PXT000109  | Payment Method not found                                                | The payment method with \{payment_method_id\} was not found                                                                                                                                          | O método de pagamento com o id \{payment_method_id\} não foi encontrado                                                                                                                                                                     |
| 404              | PXT000110  | Payment not found                                                       | The payment with \{payment_id\} was not found                                                                                                                                                        | O pagamento com o id \{payment_id\} não foi encontrado                                                                                                                                                                                      |
| 400              | PXT000111  | Bad Request                                                             | Invalid pix transfer type sent                                                                                                                                                                       | Tipo de transação pix inválida                                                                                                                                                                                                              |
| 400              | PXT000112  | Bad Request                                                             | Receiver Conciliation id sent does not match expected                                                                                                                                                | Número de conciliação do recebedor não atende ao esperado                                                                                                                                                                                   |
| 400              | PXT000113  | Bad Request                                                             | It has been identified by request_control_key or end_to_end_id that this request is already being processed                                                                                          | Foi identificado por request_control_key ou end_to_end_id que está requisição está sendo processada                                                                                                                                         |
| 400              | PXT000114  | Bad Request                                                             | Requester Configuration already exists for \{requester_key\}                                                                                                                                         | Requester Configuration já existe para o \{requester_key\}                                                                                                                                                                                  |
| 400              | PXT000115  | Bad Request                                                             | Insufficient account balance for transfer and fee amount                                                                                                                                             | Saldo de conta insuficiente para a transação e a taxa                                                                                                                                                                                       |
| 400              | PXT000117  | Pix Transfer Pending                                                    | An error occurred while sending pix_transfer \{pix_transfer_key\} to SPI                                                                                                                             | Um erro ocorreu ao enviar a pix_transfer \{pix_transfer_key\} ao SPI                                                                                                                                                                        |
| 400              | PXT000118  | Requester is not Pix Participant                                        | The requester sent an alias key but is not a indirect pix participant                                                                                                                                | O requisitante enviou uma alias key no entanto não é um participante do pix indireto                                                                                                                                                        |
| 400              | PXT000119  | Requester is not account Owner                                          | The requester is not the owner for the account sent                                                                                                                                                  | O requisitante não é dono da conta enviada                                                                                                                                                                                                  |
| 404              | PXT000120  | Alias sent not found                                                    | Alias key attached to this account not found                                                                                                                                                         | Alias key vinculada à conta não encontrada                                                                                                                                                                                                  |
| 400              | PXT000121  | Pix Transfer Direction Invalid                                          | Pix transfer direction must be either outgoing or incoming                                                                                                                                           | Pix transfer direction deve ser outgoing ou incoming                                                                                                                                                                                        |
| 400              | PXT000122  | Pix Transfer key or Request Control Key needed                          | A pix_transfer_key or a request_control_key must be provided                                                                                                                                         | Uma pix_transfer_key ou uma request_control_key deve ser fornecida                                                                                                                                                                          |
| 400              | PXT000123  | Invalid Timestamp Format sent                                           | Given parameter is not in the correct format \{timestamp_format\}                                                                                                                                    | Parametro enviado não está no formato correto \{timestamp_format\}                                                                                                                                                                          |
| 404              | PXT000124  | Outgoing Pix Transfer not found                                         | Given parameters returned no results found                                                                                                                                                           | Parâmetros enviados não retornaram resultados                                                                                                                                                                                               |
| 404              | PXT000125  | Incoming Pix Transfer not found                                         | Given parameters returned no results found                                                                                                                                                           | Parâmetros enviados não retornaram resultados                                                                                                                                                                                               |
| 400              | PXT000126  | Error on qr code decode                                                 | There was an error on decode qr code                                                                                                                                                                 | Houve um erro ao decodificar o qr code                                                                                                                                                                                                      |
| 400              | PXT000127  | Invalid Reversal Reason                                                 | Reversal reason \{reversal_reason\} is not valid                                                                                                                                                     | Razão de reversão \{reversal_reason\} não é válida                                                                                                                                                                                          |
| 400              | PXT000128  | Bad Request                                                             | Pix key \{pix_key\} sent does match inquiry pix key. Verify if end_to_end_id sent is correct                                                                                                         | Chave Pix \{pix_key\} enviada não condiz com consulta. Verifique se end_to_end_id enviado está correto                                                                                                                                      |
| 400              | PXT000129  | SPI Error message                                                       | Message rejected by SPI-ICOM                                                                                                                                                                         | Mensagem rejeitada pela SPI-ICOM                                                                                                                                                                                                            |
| 408              | PXT000130  | SPI Timeout Control                                                     | SPI Timeout Control                                                                                                                                                                                  | Controle de timeout no SPI                                                                                                                                                                                                                  |
| 400              | PXT000131  | Receiver Internal Error                                                 | Cancelled transaction due to receiver's internal error                                                                                                                                               | Transação interrompida devido a erro no PSP do Recebedor                                                                                                                                                                                    |
| 400              | PXT000132  | Invalid Target Account Number                                           | Target account number is invalid                                                                                                                                                                     | Número da conta de destino é inexistente ou inválido                                                                                                                                                                                        |
| 400              | PXT000133  | Blocked Target Account                                                  | Target account is blocked                                                                                                                                                                            | A conta de destino encontra-se bloqueada                                                                                                                                                                                                    |
| 400              | PXT000134  | Closed Target Account                                                   | Target account is closed                                                                                                                                                                             | A conta de destino encontra-se encerrada                                                                                                                                                                                                    |
| 400              | PXT000135  | Unsupported Transaction                                                 | Unsupported transaction for given target account                                                                                                                                                     | A conta de destino não suporta este tipo de transação                                                                                                                                                                                       |
| 400              | PXT000136  | Invalid Participant                                                     | SPI participant is not PSP settler agent of payer nor receiver                                                                                                                                       | Participante direto do SPI não é liquidante do PSP do Pagador / Recebedor                                                                                                                                                                   |
| 400              | PXT000137  | Zero Value Payment Order                                                | Zero value payment order                                                                                                                                                                             | Ordem de pagamento com valor zero                                                                                                                                                                                                           |
| 400              | PXT000138  | Insufficient Funds                                                      | Insufficient funds in PI account from payer                                                                                                                                                          | Saldo insuficiente na conta PI do pagador                                                                                                                                                                                                   |
| 400              | PXT000139  | Return Value Too Great                                                  | Return value greater than corresponding payment order                                                                                                                                                | Valor de devolução acima do valor de pagamento correspondente                                                                                                                                                                               |
| 400              | PXT000140  | Invalid Transactions Number                                             | Invalid transactions number                                                                                                                                                                          | Quantidade de transações inválida                                                                                                                                                                                                           |
| 400              | PXT000141  | Unrelated Beneficiary Document Number                                   | Beneficiary document number is not that of target account owner                                                                                                                                      | CPF/CNPJ do usuário recebedor não é compatível com o titular da conta de destino                                                                                                                                                            |
| 400              | PXT000142  | Invalid Beneficiary Document Number                                     | Invalid beneficiary document number                                                                                                                                                                  | CPF/CNPJ da conta de destino está incorreto                                                                                                                                                                                                 |
| 400              | PXT000143  | Incorrect Message Element                                               | Incorrect message element                                                                                                                                                                            | Elemento da mensagem incorreto                                                                                                                                                                                                              |
| 400              | PXT000144  | Rejected Payment Order                                                  | Beneficiary's PSP has rejected payment order                                                                                                                                                         | Ordem de pagamento foi rejeitada pelo banco recebedor                                                                                                                                                                                       |
| 403              | PXT000145  | Unauthorized Payer                                                      | Signing participant is unauthorized to make a payment order for paying account                                                                                                                       | Participante que assinou a mensagem não é autorizado a realizar a operação na conta PI debitada                                                                                                                                             |
| 400              | PXT000146  | Invalid Datetime                                                        | Invalid datetime for message delivery                                                                                                                                                                | Data e Hora do envio da mensagem inválida                                                                                                                                                                                                   |
| 400              | PXT000147  | Generic Error                                                           | Error while processing payment (generic error)                                                                                                                                                       | Erro no processamento do pagamento (erro genérico)                                                                                                                                                                                          |
| 400              | PXT000148  | Bad Format Operation Identifier                                         | Badly formatted operation's identifier                                                                                                                                                               | Identificador da operação mal formatado                                                                                                                                                                                                     |
| 400              | PXT000149  | Invalid Payer ISPB                                                      | Invalid or non-existent payer's PSP ISPB number                                                                                                                                                      | Número ISPB do PSP do Pagador é inválido ou inexistente                                                                                                                                                                                     |
| 400              | PXT000150  | Invalid Beneficiary ISPB                                                | Invalid or non-existent beneficiary's PSP ISPB number                                                                                                                                                | Número ISPB do banco recebedor é inválido ou inexistente                                                                                                                                                                                    |
| 400              | PXT000151  | Incorrect Type                                                          | Incorrect type for target account                                                                                                                                                                    | Tipo incorreto para a conta transacional especificada                                                                                                                                                                                       |
| 400              | PXT000152  | SPI Repeated E2E ID                                                     | The end_to_end_id was already used                                                                                                                                                                   | O end_to_end_id já foi utilizado                                                                                                                                                                                                            |
| 400              | PXT000153  | Invalid Target Account Type                                             | The target account type can not receive PIX transactions                                                                                                                                             | O tipo de conta destino não pode receber transações PIX                                                                                                                                                                                     |
| 400              | PXT000154  | Invalid ISPB                                                            | Invalid or non-existent ISPB number                                                                                                                                                                  | Número ISPB é inválido ou inexistente                                                                                                                                                                                                       |
| 400              | PXT000155  | Amount too Great                                                        | Amount too great for credited account                                                                                                                                                                | Valor de pagamento/devolução acima do permitido para a conta de destino creditada                                                                                                                                                           |
| 400              | PXT000156  | QR Code Rejected                                                        | QR Code rejected by beneficiary's PSP                                                                                                                                                                | QR Code rejeitado pelo PSP do usuário recebedor                                                                                                                                                                                             |
| 503              | PXT000157  | Bacen Service Unavailable                                               | Could not send the message to ICOM after 3 retries                                                                                                                                                   | Não pode enviar a mensagem para a ICOM depois de 3 tentativas                                                                                                                                                                               |
| 400              | PXT000158  | Invalid Amount                                                          | Paid amount diverges from expected amount of \{expected_amount\}                                                                                                                                     | O valor do pagamento diverge do valor esperado de \{expected_amount\}                                                                                                                                                                       |
| 400              | PXT000159  | QR code inactive                                                        | QR code is not active at the time of payment                                                                                                                                                         | QR code não está ativo no instante do pagamento                                                                                                                                                                                             |
| 400              | PXT000160  | QR Code Inactive                                                        | QR code is not active at the time of payment                                                                                                                                                         | QR code não está ativo no instante do pagamento                                                                                                                                                                                             |
| 400              | PXT000161  | Pix Key Is Not Active                                                   | Pix key is not active                                                                                                                                                                                | Chave Pix não está ativa                                                                                                                                                                                                                    |
| 400              | PXT000162  | QR Code Not Found                                                       | QR code or Pix key is not valid                                                                                                                                                                      | QR code ou Chave Pix não é válida                                                                                                                                                                                                           |
| 400              | PXT000163  | QR Code Or Pix Key Is Not Valid                                         | QR code or Pix key is not valid                                                                                                                                                                      | QR code ou Chave Pix não é válida                                                                                                                                                                                                           |
| 400              | PXT000164  | Unmapped Rejection Error Code                                           | Settlement failed, unknown error reason code from receiver PSP                                                                                                                                       | Código de recusa desconhecido do PSP recebedor                                                                                                                                                                                              |
| 400              | PXT000166  | Invalid Target                                                          | Account does not have permission to transfer to the given target account                                                                                                                             | A conta não possui permissão para realizar transferências para a conta enviada                                                                                                                                                              |
| 403              | PXT000167  | Requester not allowed to access this endpoint                           | Requester has no permission to perform pix transfers on this endpoint                                                                                                                                | Requester não possui permissão de realizar transações pix através deste endpoint                                                                                                                                                            |
| 403              | PXT000168  | No approver permission                                                  | Given document number does not belong to an approver for this account                                                                                                                                | Número de documento enviado não pertence a um aprovador da conta                                                                                                                                                                            |
| 400              | PXT000169  | tfa_info is required                                                    | Client must send object tfa_info                                                                                                                                                                     | Cliente deve enviar objeto tfa_info                                                                                                                                                                                                         |
| 400              | PXT000170  | Error occurred while sending token                                      | An unexpected error occurred while sending token                                                                                                                                                     | Um erro inesperado ocorreu ao tentar enviar token                                                                                                                                                                                           |
| 400              | PXT000171  | Number of token validation attempts exceeded                            | The maximum number of failed token validation attempts has been reached                                                                                                                              | Número máximo de tentativas de validação de token atingido                                                                                                                                                                                  |
| 400              | PXT000172  | Token Expired                                                           | Token has expired. Resend token or recreate transfer                                                                                                                                                 | Token expirado. Reenvie token ou recrie a transferência                                                                                                                                                                                     |
| 400              | PXT000173  | Incorrect Token                                                         | Token sent does not match expected                                                                                                                                                                   | Token enviado não condiz com o esperado                                                                                                                                                                                                     |
| 400              | PXT000174  | Error Sending Token                                                     | An error occurred while sending token and its being investigated                                                                                                                                     | Um erro ocorreu ao enviar token e está sendo investigado                                                                                                                                                                                    |
| 400              | PXT000175  | Invalid Status                                                          | Pix transfer not in pending_2fa_approval status                                                                                                                                                      | Pix transfer não está pendente de aprovação por autenticação de dois fatores                                                                                                                                                                |
| 400              | PXT000176  | Error Sending Token                                                     | An error occurred while resending token and its being investigated                                                                                                                                   | Um erro ocorreu ao reenviar token e está sendo investigado                                                                                                                                                                                  |
| 400              | PXT000177  | Pix Transfer Batch key needed                                           | A pix_transfer_batch_key must be provided                                                                                                                                                            | Uma pix_transfer_batch_key deve ser fornecida                                                                                                                                                                                               |
| 404              | PXT000178  | Pix Transfer Batch not found                                            | A pix_transfer_batch not found                                                                                                                                                                       | Uma pix_transfer_batch não encontrada                                                                                                                                                                                                       |
| 400              | PXT000179  | Empty pix-transfer list received                                        | A list of pix transfers must be provided                                                                                                                                                             | Uma lista de transferências pix deve ser fornecida                                                                                                                                                                                          |
| 400              | PXT000180  | Invalid Status                                                          | Pix transfer Batch not in pending_2fa_approval status                                                                                                                                                | Pix transfer em lote não está pendente de aprovação por autenticação de dois fatores                                                                                                                                                        |
| 400              | PXT000181  | Target PSP Timeout                                                      | Beneficiary's PSP payment order timeout                                                                                                                                                              | Timeout do participante recebedor da ordem de pagamento                                                                                                                                                                                     |
| 400              | PXT000182  | Bad Request                                                             | The given Pix transfer is tied to a batch. It cannot be individually approved. Please approve batch                                                                                                  | A Pix transfer enviada está ligada a um lote. Ela não pode ser individualmente aprovada. Por favor aprove o lote                                                                                                                            |
| 400              | PXT000183  | Invalid Person Type                                                     | Natural Person Cannot Pay for a PIX Fee                                                                                                                                                              | Pessoa Física não pode pagar tarifa de PIX                                                                                                                                                                                                  |
| 404              | PXT000184  | Outgoing PIX Transfer must hold to be reprocessed                       | Pix transfer key \{pix_transfer_key\} must wait to be reprocessed                                                                                                                                    | Transferência PIX de saída com chave \{pix_transfer_key\} deve aguardar para ser reprocessada                                                                                                                                               |

---

# Listar Transferências de uma Conta

URL: /documentation/baas/pix/listar_transferencias

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_transfers
MÉTODO GET

### Path Params

| Campo           | Tipo   | Descrição                                | Caracteres |
|-----------------|--------|------------------------------------------|------------|
| `account_key` * | uuidv4 | Chave única de identificação da conta QI | 36         |

### Query Params

| Campo                    | Tipo       | Descrição                                                                                                  | Caracteres                                                                  |
|--------------------------|------------|------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| `pix_transfer_direction` | enumerator | Indicador do sentido da transação (entrada ou saída). Caso não seja enviado, **outgoing** será considerado | [Enumeradores pix_transfer_direction](#enumeradores-pix_transfer_direction) |
| `request_control_key`    | uuidv4     | Chave única de identificação da request utilizada pelo cliente.                                            | 36                                                                          |
| `end_to_end_id`          | string     | Chave de idempotência de uma transação Pix                                                                 | 32                                                                          |
| `transaction_key`        | uuidv4     | Chave de identificação da movimentação na conta                                                            | 36                                                                          |
| `order_by`  | string  | "asc" para ordem ascendente ou "desc" para descendente. "asc" por padrão |
| `date_from`              | string     | Data inicial. Formato "YYYY-MM-DD"                                                                         |                                                                             |
| `date_to`                | string     | Data final. Formato "YYYY-MM-DD"                                                                           |                                                                             |
| `page`                   | integer    | Número da página requisitada. 1 por padrão                                                                 |                                                                             |
| `page_size`              | integer    | Tamanho da página requisitada na consulta. 30 por padrão e valor máximo                                    | Valor máximo de 30                                                          |

### Enumeradores pix_transfer_direction

| Enumerador   | Descrição                    |
|--------------|------------------------------|
| **incoming** | Transferência Pix de entrada |
| **outgoing** | Transferência Pix de saída   |

## Response

STATUS 201

Response Body

```json
{
  "data": [
    {
      "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
      "pix_message": "Bom dia",
      "pix_transfer_type": "manual",
      "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
      "updated_at": "2021-10-22T20:30:23.459Z",
      "created_at": "2021-10-22T20:30:23.459Z",
      "target_account": {
        "account_branch": "0001",
        "account_digit": "3",
        "account_number": "12345678",
        "owner_document_number": "***02502000***",
        "owner_person_type": "legal",
        "owner_name": "Qi Tech",
        "account_type": "checking_account",
        "ispb": "32402502",
        "financial_institution_name": "QI SCD",
        "pix_key": null
      },
      "receiver_conciliation_id": null,
      "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "transaction_key": "848d3ff7-4e98-4911-8773-f1d1b48c3068",
      "end_to_end_id": "E3240250220211022203051750897529",
      "pix_transfer_status": "sent",
      "transfer_amount": 126.97,
      "fee_amount": 0.0,
      "rejection_reason": null,
      "reversals": [
        {
          "end_to_end_id": "D35713491202309182058jlqdBkkHSWU",
          "transfer_amount": 0.01,
          "reversal_reason": "client_request",
          "pix_transfer_status": "received",
          "pix_transfer_key": "423866cd-0f3f-4cdd-904b-0d2e33273afd",
          "request_control_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0a",
          "created_at": "2021-10-23T20:30.459Z"
        }
      ]
    }
  ],
  "pagination": {
    "current_page": 1,
    "rows_per_page": 30
  }
}

```

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                          | Descrição (eng)<br/>`Description`                   | Descrição (ptbr)<br/>`translation`                                            |
|-------------|----------------------|---------------------------------------------|-----------------------------------------------------|-------------------------------------------------------------------------------|
| 400         | PXT000075            | Pix Transfer Key or End To End Not Provided | No pix transfer key or end to end id provided.      | Não foram fornecidos uma pix transfer key ou end to end id.                   |
| 404         | PXT000023            | Outgoing PIX Transfer Not Found             | Pix transfer key \{pix_transfer_key\} was not found | Transferência PIX de saída com chave \{pix_transfer_key\} não foi encontrada. |
| 403         | PIT000001            | User is not allowed to do this transaction  | User is not allowed to do this transaction          | Usuário não tem autorização para fazer essa transação                         |

---

# Cancelar uma solicitação de limite Pix temporário

URL: /documentation/baas/pix/pix_temporario/cancelamento_de_pix_temporario

Cancela uma solicitação de limite Pix temporário que ainda não foi utilizada, esteja ela aprovada ou em análise
manual. Cancelar uma solicitação aprovada libera o volume declarado do teto de aprovação automática da integração; cancelar uma
em análise apenas retira o pedido da fila, já que ela ainda não ocupava o teto.

## Request

ENDPOINT /baas/pix/exceptional_pix_request/ PIX_REQUEST_KEY /cancel
MÉTODO POST

:::caution
Disponível somente entre **06:00** e **17:00** (horário de Brasília). Fora dessa janela a resposta é `PXT000200`.
:::

A requisição não possui corpo.

## Path Params

| Campo         | Tipo   | Descrição                                                        | Caracteres |
|---------------|--------|------------------------------------------------------------------|------------|
| `pix_request_key` | uuidv4 | Chave única de identificação da solicitação a ser cancelada.       | 36         |

## Condições

O cancelamento só é aceito quando **todas** as condições abaixo são verdadeiras. Qualquer uma delas falsa resulta em
`PXT000201`.

- A solicitação pertence ao solicitante que está chamando.
- A solicitação está em `pending_approval` **ou** `approved` — uma solicitação em `rejected`, `cancelled` ou
  `expired` não pode ser cancelada.
- **Para cancelar a solicitação `approved`, a conta não pode ter transacionado nenhum volume por Pix temporário no
  dia.** Depois da primeira transferência, mesmo parcial, a conta precisa permanecer com uma solicitação aprovada até
  as 20:00 — inclusive uma solicitação nova que substituiu a anterior. Uma transferência que terminou recusada não
  conta como volume transacionado. Para saber de antemão se o cancelamento será aceito, use
  [Consultar o uso do limite Pix temporário](/documentation/baas/pix/pix_temporario/consulta_de_uso_de_pix_temporario).
  **Uma solicitação `pending_approval` pode ser cancelada a qualquer momento**, com
  ou sem volume transacionado: ela não autoriza nada, e a aprovada continua cobrindo a conta.

:::info
Para reduzir ou substituir um limite já utilizado, crie uma nova solicitação para a mesma conta, com
`total_amount` maior ou igual ao volume já transacionado no dia. Uma redução vale na hora; um aumento só passa a
valer quando a QI Tech aprovar, e até lá a solicitação anterior continua valendo.
Veja [Solicitar um limite Pix temporário](/documentation/baas/pix/pix_temporario/solicitacao_de_pix_temporario).
:::

## Response

Response Body: 200 OK

```json
{
  "pix_request_key": "9c3b7d21-8f4a-4c2b-9e1d-7a6b5c4d3e2f",
  "account_key": "0f2a1e4c-1111-2222-3333-444455556666",
  "total_amount": 1200000.00,
  "request_reason": "folha de pagamento do cliente Alfa Ltda",
  "status": "cancelled",
  "message": "Request cancelled and no longer available for use."
}
```

### Response Body Params

| Campo          | Tipo       | Descrição                                                                                                    |
|----------------|------------|--------------------------------------------------------------------------------------------------------------|
| `pix_request_key`  | uuidv4     | Chave única de identificação da solicitação cancelada.                                                        |
| `account_key`  | uuidv4     | Conta à qual a solicitação se aplicava.                                                                      |
| `total_amount` | number     | Volume total que havia sido declarado.                                                                       |
| `request_reason` | string     | Motivo informado na solicitação.                                                                             |
| `status`       | enumerator | Status da solicitação, **cancelled** após esta operação.                                                      |
| `message`      | string     | Texto descritivo do status, em inglês.                                                                       |

## Erros

Os erros específicos de Pix temporário estão em
[Erros de Pix temporário](/documentation/baas/pix/pix_temporario/erros_de_pix_temporario). Nesta operação podem
ocorrer `PXT000200` e `PXT000201`.

---

# Consultar solicitações de limite Pix temporário

URL: /documentation/baas/pix/pix_temporario/consulta_de_pix_temporario

Lista as solicitações de limite Pix temporário do próprio solicitante. É por aqui que se acompanha o desfecho de uma
solicitação que ficou em análise manual, além dos webhooks.

## Request

ENDPOINT /baas/pix/exceptional_pix_request
MÉTODO GET

Para consultar uma solicitação específica, informe a chave dela na URL:
/baas/pix/exceptional_pix_request/ PIX_REQUEST_KEY . A resposta tem o mesmo formato, com a
lista contendo apenas a solicitação consultada.

Não há restrição de horário nesta operação.

## Path Params

| Campo         | Tipo   | Descrição                                                                                             | Caracteres |
|---------------|--------|--------------------------------------------------------------------------------------------------------|------------|
| `pix_request_key` | uuidv4 | Chave única de identificação da solicitação de limite. Opcional — sem ela, todas as solicitações são listadas. | 36         |

## Query Params

| Campo         | Tipo    | Descrição                                                                              | Caracteres |
|---------------|---------|----------------------------------------------------------------------------------------|------------|
| `account_key` | uuidv4  | Filtra pela conta à qual a solicitação se aplica.                                       | 36         |
| `status`      | string  | Filtra por status. Aceita vários valores separados por vírgula.                          | —          |
| `page`        | integer | Página a ser retornada.                                                                 | —          |
| `page_size`   | integer | Quantidade de registros por página. Máximo e padrão: 30.                                | —          |

:::info
A consulta é sempre restrita às solicitações do próprio solicitante — não é possível consultar a solicitação de outro
parceiro, ainda que a `pix_request_key` seja conhecida.
:::

## Response

Response Body: 200 OK

```json
{
  "data": [
    {
      "pix_request_key": "9c3b7d21-8f4a-4c2b-9e1d-7a6b5c4d3e2f",
      "account_key": "0f2a1e4c-1111-2222-3333-444455556666",
      "total_amount": 1200000.00,
      "request_reason": "folha de pagamento do cliente Alfa Ltda",
      "status": "approved",
      "message": "Request approved and available for use today until 20:00."
    }
  ],
  "page": 1,
  "page_size": 30,
  "has_next_page": false,
  "requires_manual_approval": false
}
```

### Response Body Params

| Campo                      | Tipo    | Descrição                                                                                                    |
|----------------------------|---------|----------------------------------------------------------------------------------------------------------------|
| `data`                     | array   | Lista de solicitações de limite Pix temporário.                                                              |
| `page`                     | integer | Página retornada.                                                                                             |
| `page_size`                | integer | Quantidade de registros por página.                                                                           |
| `has_next_page`            | boolean | Indica se existe uma próxima página.                                                                          |
| `requires_manual_approval` | boolean | Indica se o solicitante está sob análise manual obrigatória para novas solicitações. Ver [Subutilização](/documentation/baas/pix/pix_temporario/introducao#subutilizacao). |

**Campos de cada item de `data`:**

| Campo             | Tipo       | Descrição                                                                                                    |
|-------------------|------------|--------------------------------------------------------------------------------------------------------------|
| `pix_request_key`     | uuidv4     | Chave única de identificação da solicitação de limite Pix temporário.                                        |
| `account_key`     | uuidv4     | Conta à qual a solicitação se aplica.                                                                        |
| `total_amount`    | number     | Volume total declarado para o dia.                                                                           |
| `request_reason`  | string     | Motivo informado na solicitação.                                                                             |
| `status`          | enumerator | Status da solicitação. Ver [Temporary Pix Request Status](/documentation/baas/pix/pix_temporario/introducao#temporary-pix-request-status). |
| `message`         | string     | Texto descritivo do status, em inglês.                                                                       |
| `rejected_reason` | string     | Motivo da recusa, quando informado. Opcional — pode não vir mesmo em uma solicitação recusada.                 |

## Erros

Esta operação não possui erros específicos — uma `pix_request_key` que não pertença ao solicitante simplesmente não
retorna registros. Os erros das demais operações estão em
[Erros de Pix temporário](/documentation/baas/pix/pix_temporario/erros_de_pix_temporario).

---

# Consultar o uso do limite Pix temporário

URL: /documentation/baas/pix/pix_temporario/consulta_de_uso_de_pix_temporario

Retorna o volume que a conta já transacionou no dia Pix corrente pela trilha temporária — o quanto do limite já foi
consumido. É o valor que decide se um cancelamento será aceito e quanto ainda resta do limite aprovado.

## Request

ENDPOINT /baas/pix/limits/ ACCOUNT_KEY /exceptional_usage
MÉTODO GET

Não há restrição de horário nesta operação.

## Path Params

| Campo         | Tipo   | Descrição                                                                     | Caracteres |
|---------------|--------|-------------------------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta, de titularidade do solicitante.         | 36         |

## Response

Response Body: 200 OK

```json
{
  "exceptional_pix_amount_used": 300000.00
}
```

### Response Body Params

| Campo                         | Tipo   | Descrição                                                                                  |
|-------------------------------|--------|--------------------------------------------------------------------------------------------|
| `exceptional_pix_amount_used` | number | Volume já transacionado pela conta no dia Pix corrente pela trilha temporária.                  |

:::info Para que serve
- **Saber se o cancelamento vai passar.** A solicitação `approved` só pode ser cancelada enquanto este valor é `0`.
  Veja [Cancelar uma solicitação de limite](/documentation/baas/pix/pix_temporario/cancelamento_de_pix_temporario).
- **Saber quanto resta.** O volume restante é o `total_amount` da solicitação aprovada menos este valor.
- **Saber o piso da próxima solicitação.** Um novo `total_amount` não pode ser inferior a este valor, sob pena de
  `PXT000202`.
:::

:::caution
O contador é **por conta e por dia Pix** (das 06:00 às 06:00 do dia seguinte), não por solicitação. Volume
transacionado sob uma solicitação que depois foi substituída continua contando no dia. Uma transferência que
terminou recusada não conta.
:::

---

# Erros de Pix temporário

URL: /documentation/baas/pix/pix_temporario/erros_de_pix_temporario

Os erros abaixo são específicos das operações de Pix temporário. As transferências de Pix temporário também podem
retornar qualquer erro da transferência Pix comum — veja
[Realizar transferência Pix](/documentation/baas/pix/realizar_transferencia).

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`  | Descrição (eng)<br/>`description`                                                                                     | Descrição (ptbr)<br/>`translation`                                                                                          |
|--------------------------|----------------------|---------------------|-----------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|
| 403                      | PXT000206            | Forbidden           | This requester is not allowed to use temporary Pix.                                                                 | Este solicitante não está habilitado a utilizar Pix temporário.                                                             |
| 422                      | PXT000200            | Unprocessable Entity | Temporary Pix requests can only be created or cancelled between \{window_start\} and \{window_end\}.                | Solicitações de Pix temporário só podem ser criadas ou canceladas entre \{window_start\} e \{window_end\}.                  |
| 422                      | PXT000201            | Unprocessable Entity | The temporary Pix request status does not allow this operation.                                                     | O status da solicitação de Pix temporário não permite esta operação.                                                        |
| 422                      | PXT000202            | Unprocessable Entity | The requested total amount is below the \{used_amount\} already used today.                                            | O valor total solicitado é inferior ao valor de \{used_amount\} já utilizado hoje.                                           |
| 422                      | PXT000203            | Unprocessable Entity | This transfer would exceed the temporary Pix total of \{total_amount\}, of which \{used_amount\} was already used today. | Esta transferência excederia o total de Pix temporário de \{total_amount\}, do qual \{used_amount\} já foi utilizado hoje.  |
| 422                      | PXT000204            | Unprocessable Entity | Temporary Pix transfers can only be executed until \{execution_cutoff\}.                                             | Transferências de Pix temporário só podem ser executadas até as \{execution_cutoff\}.                                      |

## Onde cada erro ocorre

| Operação                                                                                                            | Erros possíveis                             |
|---------------------------------------------------------------------------------------------------------------------|---------------------------------------------|
| [Solicitar um limite Pix temporário](/documentation/baas/pix/pix_temporario/solicitacao_de_pix_temporario)               | `PXT000206`, `PXT000200`, `PXT000202`       |
| [Consultar solicitações de limite](/documentation/baas/pix/pix_temporario/consulta_de_pix_temporario)                  | nenhum erro específico                       |
| [Cancelar uma solicitação de limite](/documentation/baas/pix/pix_temporario/cancelamento_de_pix_temporario)               | `PXT000200`, `PXT000201`                    |
| [Realizar transferência de Pix temporário](/documentation/baas/pix/pix_temporario/realizar_transferencia_pix_temporario) | `PXT000201`, `PXT000203`, `PXT000204` |

## Observações sobre PXT000201

`PXT000201` cobre todas as situações em que o status da solicitação não permite a operação, e o campo `description`
detalha qual delas ocorreu:

- não existe solicitação com essa `pix_request_key`, ou ela não pertence ao solicitante;
- o cancelamento foi tentado em uma solicitação que não está `approved`;
- o cancelamento foi tentado em uma solicitação já utilizada;
- a transferência foi tentada em uma conta sem limite Pix temporário aprovado ativo — inclusive quando a solicitação ainda
  está em `pending_approval`.

---

# Introdução

URL: /documentation/baas/pix/pix_temporario/introducao

O limite Pix temporário permite que o parceiro integrador declare, para uma conta de sua titularidade, um volume
**adicional** de Pix a ser transacionado no dia — útil para dias de pagamento em lote planejados, em que o volume a ser
enviado excede o limite Pix corrente da conta.

O volume temporário corre em um contador **independente** do limite Pix padrão da conta. Transferências feitas pelo
endpoint de transferência de Pix temporário não consomem o limite padrão, e o limite padrão permanece integralmente disponível para as
transferências Pix normais.

Cada integração tem um **teto diário de aprovação automática**, combinado previamente com a QI Tech. Solicitações
que, somadas ao que a integração já tem aprovado no dia para outras contas, cabem nesse teto são aprovadas na hora;
acima dele, a aprovação é manual.

:::info
A funcionalidade é habilitada sob demanda. Enquanto o limite Pix temporário não estiver habilitado para a sua
integração, os endpoints desta seção respondem `PXT000206`.
:::

## Fluxo

1. O parceiro solicita um limite Pix temporário para uma conta, informando o volume total que pretende transacionar
   no dia ([Solicitar um limite Pix temporário](/documentation/baas/pix/pix_temporario/solicitacao_de_pix_temporario)).
2. Dentro do teto de aprovação automática da integração, a solicitação é **aprovada na hora** e o limite já pode ser
   usado.
3. Acima do teto, a solicitação **segue para análise manual da QI Tech**, que pode aprová-la ou
   recusá-la. Enquanto pendente, ela não libera transferências; o resultado chega por webhook.
4. Estando a solicitação aprovada, o parceiro executa quantas transferências quiser pelo endpoint de transferência de
   Pix temporário, até somar o volume declarado
   ([Realizar transferência de Pix temporário](/documentation/baas/pix/pix_temporario/realizar_transferencia_pix_temporario)).
5. Enquanto nada tiver sido transferido, o parceiro pode cancelar a solicitação
   ([Cancelar uma solicitação de limite](/documentation/baas/pix/pix_temporario/cancelamento_de_pix_temporario)).
6. Ao final do dia Pix, toda solicitação ainda em aberto é expirada automaticamente.

## Janelas de horário

Os horários abaixo consideram o horário de Brasília (BRT ou UTC/GMT -03:00).

| Operação                                     | Janela          |
|----------------------------------------------|-----------------|
| Solicitar um limite Pix temporário          | 06:00 às 17:00  |
| Cancelar uma solicitação de limite           | 06:00 às 17:00  |
| Realizar transferência de Pix temporário    | 06:00 às 20:00  |

:::caution
A janela de solicitação encerra às **17:00**, três horas antes da janela de execução. Uma solicitação não pode ser
criada nem cancelada depois das 17:00, mesmo que ainda haja volume disponível para transferir até as 20:00. Fora da
janela de solicitação e cancelamento a resposta é `PXT000200`; depois das 20:00 a transferência responde `PXT000204`.
:::

## Observações

- **A solicitação mais recente substitui a anterior, não soma.** Ao criar uma nova solicitação para a mesma conta,
  os volumes **não** se somam: vale o `total_amount` da mais recente que estiver aprovada. Se você já transferiu
  R$ 300.000,00 e passa a valer uma solicitação de R$ 500.000,00, o volume restante é R$ 200.000,00, e não
  R$ 500.000,00.
- **Uma solicitação aprovada continua utilizável enquanto um aumento aguarda análise manual.** Se o novo
  `total_amount` for um aumento que ultrapassa o teto de aprovação automática da integração, a solicitação nova
  nasce `pending_approval` e a aprovada **permanece aprovada** — você continua transferindo dentro dela. Quando a QI Tech aprova a nova, a anterior passa a
  `cancelled` e o novo total vale; se a QI Tech recusa, a anterior segue valendo. Uma conta tem no máximo uma
  solicitação aprovada e no máximo uma em análise ao mesmo tempo.
- **Reduzir o total é imediato.** Um novo `total_amount` menor ou igual ao aprovado é aprovado na hora e substitui o
  anterior, sem análise manual.
- **O `total_amount` de uma nova solicitação não pode ser inferior ao volume já transacionado no dia** por Pix
  temporário naquela conta, justamente porque a nova solicitação substitui a anterior. Caso seja, a resposta é
  `PXT000202`.
- **Reduzir uma solicitação já aprovada é aprovado na hora.** Se a solicitação em aberto está `approved` e você cria
  uma nova para a mesma conta com `total_amount` **menor ou igual** ao aprovado, a nova também nasce `approved`,
  ainda que o valor esteja acima do seu teto de aprovação automática — reduzir não amplia sua exposição. Aumentar
  o valor volta a passar pela regra normal e pode cair em análise manual, inclusive se o novo valor já tiver sido
  aprovado antes no mesmo dia.
- **O cancelamento só é possível enquanto a conta não tiver transacionado nada por Pix temporário no dia.** Depois
  da primeira transferência a conta fica coberta por uma solicitação ativa até as 20:00, para que nunca haja volume
  transacionado sem solicitação que o autorize — a resposta é `PXT000201`.
- **Reuso de `request_control_key` é rejeitado, não reprocessado.** Ao repetir uma `request_control_key` já utilizada na
  transferência de Pix temporário, a requisição é recusada; a transferência original **não** é retornada nem
  reexecutada. Envie uma chave nova para cada transferência.
- **Declarar muito mais do que você transaciona tem custo.** Veja
  [Subutilização](#subutilizacao) — solicitações amplamente subutilizadas passam o solicitante a análise manual
  permanente.
- Transferências de Pix temporário **não** consomem o limite Pix padrão da conta e não aparecem no uso reportado pela
  consulta de limites.
- O corpo da transferência de Pix temporário aceita **somente** o tipo `manual`, com os dados da conta de destino.
  Transferências por chave Pix ou QR Code não são suportadas neste endpoint.

## Temporary Pix Request Status

| Enumerador           | Descrição                                                                                        |
|----------------------|--------------------------------------------------------------------------------------------------|
| **approved**         | Solicitação aprovada e disponível para uso no dia                                                |
| **pending_approval** | Solicitação em análise manual da QI Tech, que pode aprová-la ou recusá-la. Ainda **não** é utilizável      |
| **rejected**         | Solicitação recusada na análise manual. Estado final                                             |
| **cancelled**        | Solicitação cancelada pelo parceiro ou substituída por uma solicitação mais recente da mesma conta. Estado final |
| **expired**          | Solicitação expirada no encerramento do dia Pix. Estado final                                    |

## Subutilização

No encerramento do dia Pix, cada solicitação ainda aprovada é avaliada pelo volume **não utilizado**. Se o volume não
utilizado for maior ou igual a **10% do `total_amount`**, a QI Tech:

1. envia o webhook `baas.pix.exceptional.underutilized`; e
2. passa o solicitante a **análise manual obrigatória** para todas as solicitações futuras de limite Pix temporário.

:::caution Isto muda o tratamento das suas solicitações futuras
A análise manual obrigatória é permanente e não é revertida automaticamente. A partir dela, toda solicitação de limite Pix
temporário do solicitante — inclusive as que estariam dentro do teto de aprovação automática — responde `202` com
`pending_approval` e depende de aprovação manual da QI Tech antes de ser utilizável. Declare um `total_amount`
próximo do volume que você efetivamente pretende transacionar.
:::

## Webhooks

Os três eventos abaixo são enviados ao solicitante. O corpo é o mesmo objeto retornado pela consulta de solicitações de
limite, com os campos adicionais indicados.

| Evento                                 | Quando é enviado                                                                    |
|----------------------------------------|-------------------------------------------------------------------------------------|
| `baas.pix.exceptional.approved`        | Uma solicitação em análise manual foi aprovada e já pode ser utilizada              |
| `baas.pix.exceptional.rejected`        | Uma solicitação em análise manual foi recusada. Traz `rejected_reason` se informado |
| `baas.pix.exceptional.underutilized`   | Uma solicitação aprovada foi amplamente subutilizada no encerramento do dia Pix      |

:::info
A aprovação automática — a solicitação que já nasce `approved` dentro do teto — **não** gera webhook: o
`201` da própria criação já informa o resultado.
:::

Webhook Body: baas.pix.exceptional.approved

```json
{
  "pix_request_key": "9c3b7d21-8f4a-4c2b-9e1d-7a6b5c4d3e2f",
  "account_key": "0f2a1e4c-1111-2222-3333-444455556666",
  "total_amount": 1200000.00,
  "status": "approved",
  "message": "Request approved and available for use today until 20:00."
}
```

Webhook Body: baas.pix.exceptional.rejected

```json
{
  "pix_request_key": "9c3b7d21-8f4a-4c2b-9e1d-7a6b5c4d3e2f",
  "account_key": "0f2a1e4c-1111-2222-3333-444455556666",
  "total_amount": 1200000.00,
  "status": "rejected",
  "message": "Request rejected after manual analysis.",
  "rejected_reason": "Volume incompatível com o histórico da conta"
}
```

Webhook Body: baas.pix.exceptional.underutilized

```json
{
  "pix_request_key": "9c3b7d21-8f4a-4c2b-9e1d-7a6b5c4d3e2f",
  "account_key": "0f2a1e4c-1111-2222-3333-444455556666",
  "total_amount": 1200000.00,
  "status": "expired",
  "message": "Request expired and no longer available for use.",
  "used_amount": 150000.00,
  "unused_amount": 1050000.00,
  "max_unused_amount": 240000.00,
  "requires_manual_approval": true
}
```

### Webhook Body Params

| Campo                      | Tipo       | Descrição                                                                                          |
|----------------------------|------------|----------------------------------------------------------------------------------------------------|
| `pix_request_key`              | uuidv4     | Chave única de identificação da solicitação de limite Pix temporário.                                     |
| `account_key`              | uuidv4     | Conta à qual a solicitação se aplica.                                                               |
| `total_amount`             | number     | Volume total declarado para o dia.                                                                  |
| `status`                   | enumerator | Status da solicitação. Ver [Temporary Pix Request Status](#temporary-pix-request-status).        |
| `message`                  | string     | Texto descritivo do status, em inglês.                                                              |
| `rejected_reason`          | string     | Motivo da recusa, quando informado. Opcional — pode não vir mesmo em uma recusa.                       |
| `used_amount`              | number     | Volume efetivamente transacionado. Presente apenas no evento de subutilização.                       |
| `unused_amount`            | number     | Volume declarado e não transacionado. Presente apenas no evento de subutilização.                    |
| `max_unused_amount`        | number     | Volume não utilizado a partir do qual a subutilização é caracterizada. Apenas na subutilização.       |
| `requires_manual_approval` | boolean    | Indica que as solicitações futuras do solicitante passam a exigir análise manual. Apenas na subutilização. |

---

# Realizar transferência de Pix temporário

URL: /documentation/baas/pix/pix_temporario/realizar_transferencia_pix_temporario

Executa uma transferência Pix consumindo o volume de um limite Pix temporário aprovado da conta, sem tocar no limite
Pix padrão. O endpoint resolve sozinho o limite temporário ativo da conta — não é necessário informar a `pix_request_key`.

## Request

ENDPOINT /account/ ACCOUNT_KEY /exceptional_pix_transfer
MÉTODO POST

:::caution
Disponível das **06:00** às **20:00** (horário de Brasília). Fora dessa janela a resposta é `PXT000204`, ainda que haja
volume disponível.
:::

## Path Params

| Campo         | Tipo   | Descrição                                                                                  | Caracteres |
|---------------|--------|--------------------------------------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta de origem, que deve possuir um limite Pix temporário aprovado. | 36         |

Request Body

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_type": "manual",
  "transaction_amount": 300000.00,
  "target_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "32402502000135",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502"
  },
  "pix_message": "Pagamento de folha"
}
```

### Body Params

| Campo                   | Tipo       | Descrição                                                                                            | Caracteres |
|-------------------------|------------|------------------------------------------------------------------------------------------------------|------------|
| `pix_transfer_type` *   | enumerator | Tipo do Pix a ser realizado. Neste endpoint aceita **somente** o valor **manual**.                     | "manual"   |
| `transaction_amount` *  | number     | Valor da transferência. Somado ao volume já transacionado, não pode exceder o `total_amount` aprovado.  | —          |
| `target_account` *      | object     | Dados da conta de destino. Ver [Target Account](#target-account).                                      | —          |
| `request_control_key`   | uuidv4     | Chave de idempotência da requisição, definida pelo parceiro. Ver [Idempotência](#idempotencia).          | 36         |
| `pix_message`           | string     | Mensagem a ser enviada junto à transferência Pix.                                                      | 140        |

:::info
Transferência por chave Pix, QR Code estático ou QR Code dinâmico **não** é suportada neste endpoint. Para esses tipos,
use [Realizar transferência Pix](/documentation/baas/pix/realizar_transferencia), que consome o limite Pix padrão.
:::

### Target Account

| Campo                     | Tipo       | Descrição                                                        | Caracteres |
|---------------------------|------------|------------------------------------------------------------------|------------|
| `account_branch` *        | string     | Agência da conta de destino.                                      | 4          |
| `account_digit` *         | string     | Dígito da conta de destino.                                       | 1          |
| `account_number` *        | string     | Número da conta de destino.                                       | 20         |
| `owner_document_number` * | string     | CPF ou CNPJ do titular da conta de destino, somente números.       | 11 ou 14   |
| `owner_name` *            | string     | Nome do titular da conta de destino.                              | 100        |
| `account_type` *          | enumerator | Tipo da conta de destino.                                         | —          |
| `ispb` *                  | string     | ISPB da instituição da conta de destino.                          | 8          |

### Idempotência

A `request_control_key` é a chave de idempotência da requisição.

:::caution Reuso é rejeitado, não reprocessado
Ao reenviar uma `request_control_key` já utilizada, a requisição é **recusada** — a transferência original **não** é
retornada nem reexecutada, e nenhum volume de Pix temporário é consumido. Use uma chave nova em cada transferência.
:::

## Response

O código de resposta depende do modo de execução configurado para o solicitante, exatamente como na transferência Pix
comum:

| Código HTTP | `pix_transfer_status`   | Significado                                                      |
|-------------|-------------------------|------------------------------------------------------------------|
| 201         | `sent`                  | Transferência enviada de forma síncrona                           |
| 202         | `pending`               | Transferência aceita e sendo processada de forma assíncrona        |
| 202         | `pending_2fa_approval`  | Transferência aguardando aprovação por autenticação de dois fatores |

Response Body: 201 Created

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_key": "4f1c8b7a-2d3e-4f5a-9b8c-7d6e5f4a3b2c",
  "transaction_key": "8a7b6c5d-4e3f-2a1b-9c8d-7e6f5a4b3c2d",
  "end_to_end_id": "E32402502202608141530abcdefghijk",
  "pix_transfer_status": "sent",
  "created_at": "2026-08-14 15:30:00"
}
```

### Response Body Params

| Campo                 | Tipo       | Descrição                                                                          |
|-----------------------|------------|------------------------------------------------------------------------------------|
| `request_control_key` | uuidv4     | Chave de idempotência informada na requisição.                                      |
| `pix_transfer_key`    | uuidv4     | Chave única de identificação da transferência Pix no sistema QI.                     |
| `transaction_key`     | uuidv4     | Chave única de identificação da transação.                                          |
| `end_to_end_id`       | string     | Chave de idempotência da transação Pix dentro do SPI.                                |
| `pix_transfer_status` | enumerator | Status da transferência.                                                            |
| `created_at`          | string     | Data e hora de criação da transferência.                                            |

:::info
O volume do limite Pix temporário é reservado no momento desta chamada, antes da execução, e é **liberado** caso a
transferência seja rejeitada. Nos modos assíncrono e 2FA a reserva atravessa o processamento — o volume permanece
reservado enquanto a transferência estiver pendente.
:::

## Erros

Os erros específicos de Pix temporário estão em
[Erros de Pix temporário](/documentation/baas/pix/pix_temporario/erros_de_pix_temporario). Nesta operação podem
ocorrer `PXT000201`, `PXT000203` e `PXT000204`.

Além deles, valem todos os erros da transferência Pix comum — veja
[Realizar transferência Pix](/documentation/baas/pix/realizar_transferencia).

---

# Solicitar um limite Pix temporário

URL: /documentation/baas/pix/pix_temporario/solicitacao_de_pix_temporario

Solicita, para uma conta de titularidade do solicitante, o limite Pix temporário do dia: o volume total de Pix que se
pretende transacionar pela trilha temporária.

## Request

ENDPOINT /baas/pix/exceptional_pix_request
MÉTODO POST

:::caution
Disponível somente entre **06:00** e **17:00** (horário de Brasília). Fora dessa janela a resposta é `PXT000200`.
:::

Request Body

```json
{
  "account_key": "0f2a1e4c-1111-2222-3333-444455556666",
  "total_amount": 1200000.00,
  "request_reason": "folha de pagamento do cliente Alfa Ltda"
}
```

### Body Params

| Campo            | Tipo   | Descrição                                                                                                                              | Caracteres |
|------------------|--------|----------------------------------------------------------------------------------------------------------------------------------------|------------|
| `account_key` *  | uuidv4 | Chave única de identificação da conta, de titularidade do solicitante, à qual o limite se aplica.                              | 36         |
| `total_amount` * | number | Volume total do limite Pix temporário para hoje a partir desta conta. Não pode ser inferior ao volume já transacionado no dia.  | —          |
| `request_reason` * | string | Motivo pelo qual o volume temporário é necessário. Usado pela QI Tech na análise manual, quando houver. | 3 a 255 |

## Response

Duas respostas de sucesso são possíveis, e a diferença entre elas é o que determina se o limite já pode ser
usado:

| Código HTTP | `status`           | Significado                                                                                        |
|-------------|--------------------|----------------------------------------------------------------------------------------------------|
| 201         | `approved`         | Dentro do teto de aprovação automática da integração. **O limite já pode ser utilizado** para transferências hoje.       |
| 202         | `pending_approval` | Acima do teto de aprovação automática. **Segue para análise manual da QI Tech**, que pode aprovar ou recusar; não utilizável enquanto pendente. |

:::caution 202 não é aprovação
Com `202` e `pending_approval`, a solicitação foi registrada mas **não** libera transferências. Tentar uma
transferência nesse estado responde `PXT000201`. O resultado da análise chega pelos webhooks
`baas.pix.exceptional.approved` ou `baas.pix.exceptional.rejected`, e também pode ser acompanhado por
[Consultar solicitações de limite](/documentation/baas/pix/pix_temporario/consulta_de_pix_temporario).
:::

:::info
Ao criar uma solicitação para uma conta que já possui outra em aberto, os volumes **não** se somam. Se a anterior
estava `approved` e o novo `total_amount` é menor ou igual ao dela, a nova é aprovada na hora e a anterior passa a
`cancelled`. Se o novo `total_amount` é maior, a nova nasce `pending_approval` e **a anterior continua aprovada e
utilizável** até a QI Tech resolver — aprovando a nova, a anterior passa a `cancelled`; recusando, a anterior segue
valendo. Veja
[Observações](/documentation/baas/pix/pix_temporario/introducao#observacoes).
:::

Response Body: 201 Created

```json
{
  "pix_request_key": "9c3b7d21-8f4a-4c2b-9e1d-7a6b5c4d3e2f",
  "account_key": "0f2a1e4c-1111-2222-3333-444455556666",
  "total_amount": 1200000.00,
  "request_reason": "folha de pagamento do cliente Alfa Ltda",
  "status": "approved",
  "message": "Request approved and available for use today until 20:00."
}
```

Response Body: 202 Accepted

```json
{
  "pix_request_key": "9c3b7d21-8f4a-4c2b-9e1d-7a6b5c4d3e2f",
  "account_key": "0f2a1e4c-1111-2222-3333-444455556666",
  "total_amount": 1200000.00,
  "request_reason": "folha de pagamento do cliente Alfa Ltda",
  "status": "pending_approval",
  "message": "Request received and forwarded to manual analysis. The result will be sent by webhook."
}
```

### Response Body Params

| Campo          | Tipo       | Descrição                                                                                                    |
|----------------|------------|--------------------------------------------------------------------------------------------------------------|
| `pix_request_key`  | uuidv4     | Chave única de identificação da solicitação de limite Pix temporário.                                               |
| `account_key`  | uuidv4     | Conta à qual a solicitação se aplica.                                                                        |
| `total_amount` | number     | Volume total declarado para o dia.                                                                           |
| `request_reason` | string     | Motivo informado na solicitação.                                                                             |
| `status`       | enumerator | Status da solicitação. Ver [Temporary Pix Request Status](/documentation/baas/pix/pix_temporario/introducao#temporary-pix-request-status). |
| `message`      | string     | Texto descritivo do status, em inglês.                                                                       |

## Erros

Os erros específicos de Pix temporário estão em
[Erros de Pix temporário](/documentation/baas/pix/pix_temporario/erros_de_pix_temporario). Nesta operação podem
ocorrer `PXT000206`, `PXT000200` e `PXT000202`.

---

# Realizar Transação Pix

URL: /documentation/baas/pix/realizar_transferencia

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer
MÉTODO POST

## Path Params

| Campo         | Tipo   | Descrição                              | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36         |

## Transferência por Chave Pix

Request Body: Transferência por Chave Pix

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_type": "key",
  "target_pix_key": "target_pix_key@email.com",
  "transaction_amount": 500.65,
  "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
  "pix_message": "Ola Mundo"
}
```

### Body Params

| Campo                   | Tipo       | Descrição                                                                                                                                                                                                                                        | Caracteres |
|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4     | Chave única de identificação da request utilizada pelo cliente no formato uuid v4.                                                                                                                                                               | 36         | 
| `pix_transfer_type` *   | enumerator | Tipo do pix a ser realizado. Para o caso de transferência por chave deve ser **key**.                                                                                                                                                            | "key"      |
| `target_pix_key` *      | string     | Chave pix da conta a ser enviada a transação.                                                                                                                                                                                                    | 100        |
| `transaction_amount` *  | number     | Valor da transferência.                                                                                                                                                                                                                          | 10         |
| `end_to_end_id` *       | string     | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na consulta de chave Pix. Só deve ser enviado se o `pix_transfer_type` for **key**, **static_qr_code** ou **static_qr_code** | 32         |
| `pix_message`           | string     | Mensagem a ser enviada junto à transferência Pix.                                                                                                                                                                                                | 140        |

## Transferência Manual - Utilizando os Dados da Conta

Request Body: Transferência Manual

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_type": "manual",
  "target_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "32402502000135",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502"
  },
  "transaction_amount": 500.65,
  "pix_message": "Ola Mundo"
}
```

### Body Params

| Campo                   | Tipo       | Descrição                                                                                         | Caracteres                                          |
|-------------------------|------------|---------------------------------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | uuidv4     | Chave única de identificação da request utilizada pelo cliente no formato uuid v4.                | 36                                                  | 
| `pix_transfer_type` *   | enumerator | Tipo de transferência Pix.                                                                        | **manual**                                          |
| `target_account` *      | Object     | Conta destino - Só deve ser enviada em transferências com `pix_transfer_type` do tipo **manual**. | **[Objeto target_account](#objeto-target_account)** | 10 |
| `transaction_amount` *  | number     | Valor da transferência.                                                                           | 10                                                  |
| `pix_message`           | string     | Mensagem a ser enviada junto à transferência Pix.                                                 | 140                                                 |

### Objeto target_account

| Campo                     | Tipo       | Descrição                                           | Caracteres                                              |
|---------------------------|------------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string     | Agência da conta.                                   | 4                                                       |
| `account_digit` *         | string     | Dígito da conta.                                    | 1                                                       |
| `account_number` *        | string     | Número da conta.                                    | 20                                                      |
| `owner_document_number` * | string     | CPF ou CNPJ (apenas números) do titular da conta.   | 14                                                      |
| `owner_name` *            | string     | Nome do titular da conta.                           | 150                                                     |
| `account_type`*           | enumerator | Tipo da conta.                                      | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string     | Base no CNPJ da instituição financeira (8 dígitos). | 8                                                       |

### Enumerador account_type

| Enumerador           | Descrição           |
|----------------------|---------------------|
| **checking_account** | Conta Corrente      |
| **salary_account**   | Conta Salário       |
| **saving_account**   | Conta Poupança      |
| **payment_account**  | Conta de Pagamentos |

## Transferência por QR Code Pix

Os dados utilizados para realizção de uma transação de pagamento de um QR Code Pix devem ser obtidos através
da [decodificação do QR Code Pix](/documentation/pix/decodificar_qr_code), utilizando a URI do Pix Copia e Cola.

I - O campo “end_to_end_id” deve ser o mesmo valor retornado da decodificação do QR Code Dinâmico.
II - Informar no campo “transaction_amount“ o mesmo valor retornado no campo “qr_code_data.amount” da decodificação do
QR Code Dinâmico;
III - Alterar o campo “pix_transfer_type” para o enumerador correspondente (**static_qr_code** ou **dynamic_qr_code** ), para solicitação do pagamento.
IV - O campo “receiver_conciliation_id” deve ser o mesmo valor retornado da decodificação do QR Code Dinâmico.

Request Body: Transferência por Qr Code

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_type": "static_qr_code",
  "transaction_amount": 500.65,
  "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
  "receiver_conciliation_id": "REC00000000000000000000009459463343",
  "target_pix_key": "target_pix_key@email.com",
  "pix_message": "Ola Mundo"
}
```

### Body Params

| Campo                      | Tipo       | Descrição                                                                                                                                                                                                                                                                               | Caracteres                                |
|----------------------------|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|
| `request_control_key` *    | uuidv4     | Chave única de identificação da request utilizada pelo cliente no formato uuid v4.                                                                                                                                                                                                      | 36                                        | 
| `pix_transfer_type` *      | enumerator | Tipo de transferência Pix.                                                                                                                                                                                                                                                              | **static_qr_code** ou **dynamic_qr_code** |
| `target_pix_key` *         | string     | Chave pix da conta a ser enviada a transação.                                                                                                                                                                                                                                           | 100                                       |
| `receiver_conciliation_id` | string     | Identicação de conciliação do recebedor.                                                                                                                                                                                                                                                | 35                                        |
| `transaction_amount` *     | number     | Valor da transferência.                                                                                                                                                                                                                                                                 | 10                                        |
| `end_to_end_id` *          | string     | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na [consulta de chave Pix](/documentation/pix/consultar_chave). Só deve ser enviado se o `pix_transfer_type` for **key**, **static_qr_code** ou **static_qr_code**. | 32                                        |
| `pix_message`              | string     | Mensagem a ser enviada junto à transferência Pix.                                                                                                                                                                                                                                       | 140                                       |

:::danger Aviso
O `end_to_end_id` da consulta deve ter sido feito em nome da conta que solicitará a movimentação!
:::

:::danger Aviso
Um `end_to_end_id` só pode ser utilizado para uma única transferência, não importando, se a transferência tenha sido bem
sucedida ou não.
:::

## Response

STATUS 201

Response Body: Transferência Enviada

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "transaction_key": "848d3ff7-4e98-4911-8773-f1d1b48c3068",
  "pix_transfer_status": "sent",
  "created_at": "2021-10-22T20:30:23.459Z"
}
```

STATUS 202

Response Body: Transferência Pendente

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "transaction_key": "848d3ff7-4e98-4911-8773-f1d1b48c3068",
  "pix_transfer_status": "pending",
  "created_at": "2021-10-22T20:30:23.459Z",
  "transaction_key": "8ea90347-330d-4b3a-8ebb-2ac217ad6eb3"
}
```

:::info Informação
Caso seja retornado **HTTP Status 202** com o campo `pix_transfer_status` com valor **pending**, a solicitação de Pix
não deve ser retentada.

Esta transferência será reprocessada. É necessário verificar o status da transferência por meio
da [Consulta de Transferência Pix](#consultar-transação-pix).
:::

STATUS 4xx

Response Body: Transferência Rejeitada

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {
    "pix_transfer_data": {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "pix_transfer_status": "rejected",
      "created_at": "2021-10-22T20:30:23.459Z"
    }
  }
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (ptbr)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Erro de Schema                                                                                                         |
| 403                      | PIT000001            | User is not allowed to do this transaction         |                                                                                                                         | Usuário não tem autorização para fazer essa transação                                                                  |
| 400                      | PIT000003            | Bad Request                                        | Insufficient account balance for transfer and fee amount.                                                               | Saldo de conta insuficiente para a transferência e a taxa.                                                             |
| 400                      | PIT000004            | Bad Request                                        | Transaction amount is over limit.                                                                                       | O total da transferência é superior ao limite.                                                                         |
| 400                      | PXT000003            | Account is Closed                                  | Account \{account_key\} is closed.                                                                                      | Conta \{account_key\} está fechada.                                                                                    |
| 404                      | PXT000004            | Account not found                                  | Account not found for: \{account_datum\}                                                                                | Conta não encontrada para: \{account_datum\}                                                                           |
| 400                      | PXT000010            | Account is Blocked                                 | Account \{account_key\} is blocked.                                                                                     | Conta \{account_key\} está bloqueada.                                                                                  |
| 404                      | PXT000018            | Reversal Original Transfer not Found               | Reversal original pix transfer not found                                                                                | Transferência original da devolução não foi encontrada                                                                 |
| 400                      | PXT000033            | Target Account Must Not Be Source Account          | Target Account Must Not Be Source Account                                                                               | A conta de destino não pode ser a conta de origem                                                                      |
| 404                      | PXT000041            | Not Found                                          | Qr Code not found                                                                                                       | Qr Code não encontrado                                                                                                 |
| 400                      | PXT000048            | Bad Request                                        | Emoji not allowed in pix message.                                                                                       | Emoji não é permitido na mensagem pix.                                                                                 |
| 400                      | PXT000053            | Bad Request                                        | QrCode already paid                                                                                                     | Qr Code já Pago                                                                                                        |
| 400                      | PXT000060            | Bad Request                                        | Nonexistent account in destination bank                                                                                 | Conta inexistente no banco de destino                                                                                  |
| 400                      | PXT000061            | Bad Request                                        | End to end id invalid. A pix transfer with the end to end id \{end_to_end\} has already been registered!                | End to end id inválido. Uma transação pix com o identificador único \{end_to_end\} já foi registrada!                  |
| 400                      | PXT000079            | Bad Request                                        | Insufficient billing account balance for fee.                                                                           | Saldo de conta de cobrança insuficiente para a taxa.                                                                   |
| 400                      | PXT000083            | Bad Request                                        | Pix rejected                                                                                                            | Pix rejeitado                                                                                                          |
| 406                      | PXT000103            | request_control_key must be a valid uuid v4 string | request_control_key was not accepted for not being a valid uuid v4 string                                               | request_control_key não foi aceito por não ser uma palavra uuid v4 válida                                              |
| 400                      | PXT000104            | Invalid Transaction Amount                         | Transaction amount of \{transaction_amount\} is not valid. It must be a positive value with at maximum 2 decimal places | O valor de transação \{transaction_amount\} não é válido. Deve ser um valor positivo com no máximo duas casas decimais |
| 406                      | PXT000105            | Invalid end_to_end_id                              | The end_to_end_id sent \{end_to_end_id\} is not valid.                                                                  | O end_to_end_id enviado \{end_to_end_id\} não é válido.                                                                |
| 400                      | PXT000108            | Bad Request                                        | Billing account closed or blocked                                                                                       | Conta de cobrança encerrada ou bloqueada                                                                               |
| 400                      | PXT000109            | Bad Request                                        | request_control_key \{request_control_key\} already in use                                                              | request_control_key \{request_control_key\} já utilizada                                                               |
| 400                      | PXT000115            | Bad Request                                        | Insufficient account balance for transfer and fee amount.                                                               | Saldo de conta insuficiente para a transferência e a taxa                                                              |
| 400                      | PXT000118            | Requester is not Pix Participant                   | The requester sent an alias key but is not a indirect pix participant                                                   | O requisitante enviou uma alias key no entanto não é um participante do pix indireto                                   |
| 400                      | PXT000128            | Bad Request                                        | Pix key \{pix_key\} sent does match inquiry pix key. Verify if end_to_end_id sent is correct                            | Chave Pix \{pix_key\} enviada não condiz com consulta. Verifique se end_to_end_id enviado está correto                 |
| 400                      | PXT000129            | SPI Error message                                  | Message rejected by SPI-ICOM                                                                                            | Mensagem rejeitada pela SPI-ICOM                                                                                       |
| 408                      | PXT000130            | SPI Timeout Control                                | SPI Timeout Control                                                                                                     | Controle de timeout no SPI                                                                                             |
| 400                      | PXT000131            | Receiver Internal Error                            | Cancelled transaction due to receiver's internal error                                                                  | Transação interrompida devido a erro no PSP do Recebedor                                                               |
| 400                      | PXT000132            | Invalid Target Account Number                      | Target account number is invalid                                                                                        | Número da conta de destino é inexistente ou inválido                                                                   |
| 400                      | PXT000133            | Blocked Target Account                             | Target account is blocked.                                                                                              | A conta de destino encontra-se bloqueada.                                                                              |
| 400                      | PXT000134            | Closed Target Account                              | Target account is closed.                                                                                               | A conta de destino encontra-se encerrada.                                                                              |
| 400                      | PXT000135            | Unsupported Transaction                            | Unsupported transaction for given target account.                                                                       | A conta de destino não suporta este tipo de transação.                                                                 |
| 400                      | PXT000136            | Invalid Participant                                | SPI participant is not PSP settler agent of payer nor receiver.                                                         | Participante direto do SPI não é liquidante do PSP do Pagador / Recebedor.                                             |
| 400                      | PXT000137            | Zero Value Payment Order                           | Zero value payment order.                                                                                               | Ordem de pagamento com valor zero.                                                                                     |
| 400                      | PXT000138            | Insufficient Funds                                 | Insufficient funds in PI account from payer.                                                                            | Saldo insuficiente na conta PI do pagador.                                                                             |
| 400                      | PXT000139            | Return Value Too Great                             | Return value greater than corresponding payment order.                                                                  | Valor de devolução acima do valor de pagamento correspondente.                                                         |
| 400                      | PXT000140            | Invalid Transactions Number                        | Invalid transactions number.                                                                                            | Quantidade de transações inválida.                                                                                     |
| 400                      | PXT000141            | Unrelated Beneficiary Document Number              | Beneficiary document number is not that of target account owner.                                                        | CPF/CNPJ do usuário recebedor não é compatível com o titular da conta de destino.                                      |
| 400                      | PXT000142            | Invalid Beneficiary Document Number                | Invalid beneficiary document number                                                                                     | CPF/CNPJ da conta de destino está incorreto.                                                                           |
| 400                      | PXT000143            | Incorrect Message Element                          | Incorrect message element.                                                                                              | Elemento da mensagem incorreto.                                                                                        |
| 403                      | PXT000144            | Rejected Payment Order                             | Beneficiary's PSP has rejected payment order.                                                                           | Ordem de pagamento foi rejeitada pelo banco recebedor.                                                                 |
| 403                      | PXT000145            | Unauthorized Payer                                 | Signing participant is unauthorized to make a payment order for paying account.                                         | Participante que assinou a mensagem não é autorizado a realizar a operação na conta PI debitada.                       |
| 400                      | PXT000146            | Invalid Datetime                                   | Invalid datetime for message delivery.                                                                                  | Data e Hora do envio da mensagem inválida.                                                                             |
| 400                      | PXT000147            | Generic Error                                      | Error while processing payment (generic error).                                                                         | Erro no processamento do pagamento (erro genérico).                                                                    |
| 400                      | PXT000148            | Bad Format Operation Identifier                    | Badly formatted operation's identifier.                                                                                 | Identificador da operação mal formatado.                                                                               |
| 400                      | PXT000149            | Invalid Payer ISPB                                 | Invalid or non-existent payer's PSP ISPB number.                                                                        | Número ISPB do PSP do Pagador é inválido ou inexistente.                                                               |
| 400                      | PXT000150            | Invalid Beneficiary ISPB                           | Invalid or non-existent beneficiary's PSP ISPB number.                                                                  | Número ISPB do banco recebedor é inválido ou inexistente.                                                              |
| 400                      | PXT000151            | Incorrect Type                                     | Incorrect type for target account.                                                                                      | Tipo incorreto para a conta transacional especificada.                                                                 |
| 400                      | PXT000152            | Repeated End-to-End ID Error                       | The end_to_end_id was already used                                                                                      | O end_to_end_id já foi utilizado                                                                                       |
| 400                      | PXT000153            | Invalid Target Account Type                        | The target account type cannot receive PIX transactions                                                                 | O tipo de conta destino não pode receber transações PIX                                                                |
| 400                      | PXT000154            | Invalid ISPB                                       | Invalid or non-existent ISPB number.                                                                                    | Número ISPB é inválido ou inexistente.                                                                                 |
| 400                      | PXT000155            | Amount too Great                                   | Amount too great for credited account.                                                                                  | Valor de pagamento/devolução acima do permitido para a conta de destino creditada.                                     |
| 400                      | PXT000156            | QR Code Rejected                                   | QR Code rejected by beneficiary's PSP.                                                                                  | QR Code rejeitado pelo PSP do usuário recebedor.                                                                       |
| 503                      | PXT000157            | Bacen Service Unavailable Error                    | Could not send the message to ICOM after 3 retries                                                                      | Não pode enviar a mensagem para a ICOM depois de 3 tentativas                                                          |
| 400                      | PXT000158            | Invalid Amount                                     | Paid amount diverges from expected amount of \{expected_amount\}                                                        | O valor do pagamento diverge do valor esperado de \{expected_amount\}                                                  |
| 403                      | PXT000167            | Requester not allowed to access this endpoint      | Requester has no permission to perform pix transfers on this endpoint                                                   | Requester não possui permissão de realizar transações pix através deste endpoint                                       |

---

# Solicitar a devolução de um Pix recebido

URL: /documentation/baas/pix/solicitar_devolucao

A devolução de um Pix pode ser efetuada em até 90 dias a partir de seu recebimento.

## Request

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer/ PIX_TRANSFER_KEY /reversal
MÉTODO POST

### Path Params

| Campo                | Tipo   | Descrição                                                        | Caracteres |
|----------------------|--------|------------------------------------------------------------------|------------|
| `account_key` *      | uuidv4 | Chave única de identificação da conta.                           | 36         |
| `pix_transfer_key` * | uuidv4 | Chave única de identificação da transferência Pix no sistema QI. | 36         |

Request Body

```json
{
  "request_control_key": "303393bf-8f2e-4ff0-b326-ee7ad612e8ca",
  "reversal_amount": 147,
  "reversal_reason": "client_request",
  "reversal_message": "Mensagem Pix da Devolução"
}
```

### Request Body

| Campo                   | Tipo   | Descrição                         | Caracteres                                                    |
|-------------------------|--------|-----------------------------------|---------------------------------------------------------------|
| `request_control_key` * | uuidv4 | Chave de unicidade da requisição. | 36                                                            |
| `reversal_amount` *     | number | Valor da devolução.               | 11                                                            |
| `reversal_reason` *     | string | Motivo da devolução.              | **[Enumerador reversal_reason](#enumerador-reversal_reason)** |
| `reversal_message`      | string | Mensagem da devolução.            | 140                                                           |

### Enumerador reversal_reason

| Enumerador         | Descrição                                     |
|--------------------|-----------------------------------------------|
| **client_request** | Caso tenha sido requerido pelo dono da conta. |
| **reconciliation** | Para reconciliação devido a erro operacional. |

## Response

STATUS 201

Response Body: Reversão Enviada

```json
{
  "reversal_status": "sent",
  "transaction_amount": 147,
  "pix_transfer_key": "cdcf0d25-08a1-46e3-902a-6d7ca75e6c48",
  "end_to_end_id": "E32402502202405081755SxyT2DDcVwc",
  "request_control_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
  "created_at": "2021-10-22T20:30:23.459Z"
}
```

STATUS 202

Response Body: Reversão Pendente

```json
{
  "reversal_status": "pending",
  "transaction_amount": 147,
  "pix_transfer_key": "cdcf0d25-08a1-46e3-902a-6d7ca75e6c48",
  "end_to_end_id": "E32402502202407112211Id9JbxoaiTf",
  "request_control_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
  "created_at": "2021-10-22T20:30:23.459Z"
}
```

:::info Informação
Caso seja retornado **HTTP Status 202** com o campo `pix_transfer_status` com valor **pending**, a solicitação de Pix
não deve ser retentada.

Esta transferência será reprocessada. É necessário verificar o status da transferência por meio
da [Consulta de Transferência Pix](#consultar-transação-pix).
:::

### Response Body

| Campo                 | Tipo       | Descrição                                                                                   | Caracteres                                                |
|-----------------------|------------|---------------------------------------------------------------------------------------------|-----------------------------------------------------------|
| `reversal_status`     | enumerator | Enumerador de status da transação de devolução.                                             | [Enumerador reversal_status](#enumerador-reversal_status) |
| `transfer_amount`     | number     | Valor da transferência de devolução.                                                        | 11                                                        |
| `pix_transfer_key`    | uuidv4     | Chave da transação pix executada na devolução.                                              | 36                                                        |
| `end_to_end_id`       | string     | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo) | 32                                                        |
| `request_control_key` | uuidv4     | Chave única de identificação da request utilizada pelo cliente.                             | 36                                                        |
| `created_at`          | string     | Data e hora da devolução.                                                                   | 10                                                        |

### Enumerador reversal_status

| Enumerador   | Descrição                                |
|--------------|------------------------------------------|
| **sent**     | Transferência Pix realizada com sucesso. |
| **pending**  | Transferência Pix pendente.              |
| **rejected** | Transferência Pix rejeitada.             |

STATUS 4xx

Response Body: Reversão Rejeitada

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {
    "pix_transfer_data": {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "end_to_end_id": "E32402502202407112211Id9JbxoaiTf",
      "pix_transfer_status": "rejected",
      "created_at": "2021-10-22T20:30:23.459Z"
    }
  }
}
```

:::info Informação
Além dos erros anteriormente listados para [transferência Pix](/documentation/baas/pix/realizar_transferencia), a
devolução de um Pix também pode retornar os erros
listados abaixo.
:::

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                   | Descrição (eng)<br/>`description`                                      | Descrição (ptbr)<br/>`translation`                                                        |
|--------------------------|----------------------|--------------------------------------|------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                          | Schema Error                                                           | Erro de Schema                                                                            |
| 404                      | PXT000018            | Reversal Original Transfer not Found | Reversal original pix transfer not found.                              | Transferência original da devolução não foi encontrada.                                   |
| 400                      | PXT000017            | Reversal Too Great                   | Reversal transfers sum amount surpasses that of original pix transfer. | A soma das transferências de devolução ultrapassam o valor da transferência pix original. |
| 400                      | PXT000015            | Reversal date expired                | Reversal original transaction is older than 90 days                    | A data de criação da transação original é mais antiga que 90 dias                         |
| 400                      | PXT0000127           | Invalid Reversal Reason              | Reversal reason \{reversal_reason\} is not valid                       | Razão de reversão \{reversal_reason\} não é válida                                        |

---

# Webhooks

URL: /documentation/baas/pix/webhooks

Uma vez que as transferências ocorrem de forma assíncrona, é de suma importância o mapeamento e o tratamento corretos
dos webhooks enviados.

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeados de forma restrita.
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

## Webhook para Transações Pendentes

Webhook destinado para atualizar o status das transferências que ficaram pendentes (status 202)
na [requisição](/documentation/baas/pix/realizar_transferencia) de envio do Pix.

### Webhook Request Body

Request Body: Transação Enviada

```json
{
  "webhook_type": "baas.pix_transfer.outgoing_pix",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "pix_transfer_status": "sent",
    "created_at": "2021-10-22T20:30:23.459Z"
  }
}
```

Request Body: Transação Rejeitada

```json
{
  "webhook_type": "baas.pix_transfer.outgoing_pix",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "pix_transfer_status": "rejected",
    "created_at": "2021-10-22T20:30:23.459Z",
    "error_code": "PXT000132",
    "error_description": "Target account number is invalid.",
    "error_translation": "Número da conta de destino é inexistente ou inválido.",
    "error_short_description": null
  }
}
```

### Webhook Body Param

| Campo                 | Tipo   | Descrição                                                 | Max. Caracteres |
|-----------------------|--------|-----------------------------------------------------------|-----------------|
| `webhook_type`        | string | Um enumerador que define o tipo de evento sendo reportado | 23              |
| `webhook_datetime`    | string | Data e hora do envio do webhook                           | 20              |
| `request_control_key` | string | UUID4 para fins de consulta sobre a requisição feita.     | 36              |
| `pix_transfer_key`    | string | Chave de identificação da transferência Pix no sistema QI | 36              |
| `pix_transfer_status` | string | Status da transação.                                      | 200             |
| `created_at`          | string | Data e hora de criação da transação.                      | 20              |
| `error_code`          | string | Código do erro ocorrido na transação                      | 20              |
| `error_description`   | string | Descrição do erro em inglês                               | 200             |
| `error_translation`   | string | Descrição do erro traduzida para português                | 200             |
| `error_short_description` | string | Descrição curta do erro                               | 100             |

[//]: # (Break here for new page -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------)

## Webhook para Pix de Entrada

Webhook que servirá para avisar sobre transações Pix que chegaram para uma conta.

### Webhook Request Body

Request Body: Pix Recebido

```json
{
  "webhook_type": "baas.pix_transfer.incoming_pix",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "end_to_end_id": "E18236120202308111235s14fddf2801",
    "pix_transfer_status": "received",
    "account_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
    "receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
    "transfer_amount": 126.97,
    "fee_amount": 0.0,
    "source_account": {
      "account_branch": "0001",
      "account_digit": "3",
      "account_number": "12345678",
      "owner_document_number": "***02502000***",
      "owner_person_type": "legal",
      "owner_name": "Qi Tech",
      "account_type": "checking_account",
      "ispb": "32402502"
    },
    "pix_transfer_type": "dynamic_qr_code",
    "pix_message": "pix message received",
    "error_code": null,
    "error_description": null,
    "error_translation": null,
    "error_short_description": null,
    "created_at": "2021-10-22T20:30:23.459Z",
    "reversals": []
  }
}
```

Request Body: Pix Em Análise Manual

```json
{
  "webhook_type": "baas.pix_transfer.incoming_pix",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "end_to_end_id": "E18236120202308111235s14fddf2801",
    "pix_transfer_status": "in_manual_analysis",
    "account_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
    "receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
    "transfer_amount": 126.97,
    "fee_amount": 0.0,
    "source_account": {
      "account_branch": "0001",
      "account_digit": "3",
      "account_number": "12345678",
      "owner_document_number": "***02502000***",
      "owner_person_type": "legal",
      "owner_name": "Qi Tech",
      "account_type": "checking_account",
      "ispb": "32402502"
    },
    "pix_transfer_type": "dynamic_qr_code",
    "pix_message": "pix message",
    "error_code": null,
    "error_description": null,
    "error_translation": null,
    "error_short_description": null,
    "created_at": "2021-10-22T20:30:23.459Z",
    "reversals": []
  }
}
```

Request Body: Pix Rejeitado Pela Análise

```json
{
  "webhook_type": "baas.pix_transfer.incoming_pix",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "end_to_end_id": "E18236120202308111235s14fddf2801",
    "pix_transfer_status": "rejected_by_analysis",
    "account_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
    "receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
    "transfer_amount": 126.97,
    "fee_amount": 0.0,
    "source_account": {
      "account_branch": "0001",
      "account_digit": "3",
      "account_number": "12345678",
      "owner_document_number": "***02502000***",
      "owner_person_type": "legal",
      "owner_name": "Qi Tech",
      "account_type": "checking_account",
      "ispb": "32402502"
    },
    "pix_transfer_type": "dynamic_qr_code",
    "pix_message": "pix message",
    "error_code": "PXT000194",
    "error_description": "Incoming pix transfer rejected by manual analysis",
    "error_translation": "Transferência de Pix de entrada rejeitada pela análise manual",
    "error_short_description": null,
    "created_at": "2021-10-22T20:30:23.459Z",
    "reversals": []
  }
}
```

:::info Bloqueio Cautelar
Ao receber um Pix, o mesmo pode ficar bloqueado cautelarmente. Nesse cenário, nenhum recurso é creditado na conta destino e um webhook com o status `in_manual_analysis` é enviado para o cliente. O Pix passará pelo processo de análise manual em até no máximo 72 horas. Após realizada a análise, a entrada será aceita ou recusada e o Pix de entrada irá para o status `received` (nesse momento o recurso será creditado na conta do cliente) ou `rejected_by_analysis`, respectivamente.
:::

### Webhook Body Param

| Campo                      | Tipo       | Descrição                                                                                             | Max. Caracteres                                                   |
|----------------------------|------------|-------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `webhook_type`             | string     | Um enumerador que define o tipo de evento sendo reportado                                             | 23                                                                |
| `webhook_datetime`         | string     | Data e hora do envio do webhook                                                                       | 20                                                                |
| `pix_transfer_type`        | enumerator | Tipo do pix realizado                                                                                 | **[Enumerador pix_transfer_type](#enumerador-pix_transfer_type)** |
| `target_pix_key`           | string     | Chave pix da conta a ser enviada a transação                                                          | 100                                                               |
| `source_account`           | Object     | Conta destino - Só deve ser enviada em transações do tipo "manual"                                    | **[Objeto source_account](#objeto-source_account)**               |
| `transfer_amount`          | number     | Valor da transferencia                                                                                | 10                                                                |
| `receiver_conciliation_id` | string     | Identicação de conciliação do recebedor                                                               | 35                                                                |
| `end_to_end_id`            | string     | Chave de idempotência de uma transação Pix - só deve ser enviado se o tipo de transferência for "key" | 32                                                                |
| `pix_message`              | string     | Mensagem a ser enviada junto à transferência Pix                                                      | 140                                                               |
| `fee_amount`               | number     | Valor da transferencia                                                                                | 10                                                                |
| `pix_transfer_status`      | string     | Status da transação pix                                                                               | 10                                                                |
| `account_key`              | string     | Chave única de identificação da conta QI                                                              | 36                                                                |
| `pix_transfer_key`         | string     | Chave única de identificação da transferência Pix                                                     | 36                                                                |
| `error_code`               | string     | Código do erro ocorrido na transação                                                                  | 20                                                                |
| `error_description`        | string     | Descrição do erro em inglês                                                                           | 200                                                               |
| `error_translation`        | string     | Descrição do erro traduzida para português                                                            | 200                                                               |
| `error_short_description`  | string     | Descrição curta do erro                                                                               | 100                                                               |

### Enumerador pix_transfer_type

| Enumerador          | Descrição                                |
|---------------------|------------------------------------------|
| **manual**          | Pix utilizando os dados da conta destino |
| **key**             | Pix utilizando uma chave pix             |
| **static_qr_code**  | Pix utilizando um QR code estático       |
| **dynamic_qr_code** | Pix utilizando um QR code dinâmico       |
| **reversal**        | Devolução Pix                            |

### Objeto source_account

| Campo                     | Tipo       | Descrição                                                                                               | Caracteres                                              |
|---------------------------|------------|---------------------------------------------------------------------------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string     | Agência da conta                                                                                        | 6                                                       |
| `account_digit` *         | string     | Dígito da conta                                                                                         | 1                                                       |
| `account_number` *        | string     | Número da conta                                                                                         | 20                                                      |
| `owner_document_number` * | string     | CPF ou CNPJ (apenas números) do titular da conta                                                        | 14                                                      |
| `owner_name`              | string     | Nome do titular da conta                                                                                | 150                                                     |
| `account_type`*           | enumerator | Tipo da conta                                                                                           | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string     | Código de oito dígitos que identifica os bancos no sistema de transferência de reserva do Banco Central | 8                                                       |

### Enumerador account_type

| Enumerador           | Descrição           |
|----------------------|---------------------|
| **checking_account** | Conta Corrente      |
| **salary_account**   | Conta Salário       |
| **saving_account**   | Conta Poupança      |
| **payment_account**  | Conta de Pagamentos |

[//]: # (Break here for new page -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------)

## Webhook para Devoluções de Pix

Webhook que servirá para avisar sobre devoluções Pix que chegaram para uma conta.

### Webhook Request Body

Request Body: Pix Recebido

```json
{
  "webhook_type": "baas.pix_transfer.incoming_pix",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "end_to_end_id": "D18236120202308111235s14fddf2801",
    "pix_transfer_status": "received",
    "account_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
    "receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
    "transfer_amount": 126.97,
    "fee_amount": 0.0,
    "source_account": {
      "account_branch": "0001",
      "account_digit": "3",
      "account_number": "12345678",
      "owner_document_number": "***02502000***",
      "owner_person_type": "legal",
      "owner_name": "Qi Tech",
      "account_type": "checking_account",
      "ispb": "32402502"
    },
    "pix_transfer_type": "reversal",
    "pix_message": "pix message received",
    "error_code": null,
    "error_description": null,
    "error_translation": null,
    "error_short_description": null,
    "created_at": "2021-10-22T20:30:23.459Z",
    "reversals": [],
    "original_outgoing_pix_transfer": "b56862c4-2b20-4057-8063-b8809866e494",
    "original_end_to_end_id": "E18236120202308111235s14fddf2801"
  }
}
```

### Webhook Body Param

| Campo                            | Tipo       | Descrição                                                                                             | Max. Caracteres                                                   |
|----------------------------------|------------|-------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `webhook_type`                   | string     | Um enumerador que define o tipo de evento sendo reportado                                             | 23                                                                |
| `webhook_datetime`               | string     | Data e hora do envio do webhook                                                                       | 20                                                                |
| `pix_transfer_type`              | enumerator | Tipo do pix realizado                                                                                 | **[Enumerador pix_transfer_type](#enumerador-pix_transfer_type)** |
| `target_pix_key`                 | string     | Chave pix da conta a ser enviada a transação                                                          | 100                                                               |
| `source_account`                 | Object     | Conta destino - Só deve ser enviada em transações do tipo "manual"                                    | **[Objeto source_account](#objeto-source_account)**               |
| `transfer_amount`                | number     | Valor da transferencia                                                                                | 10                                                                |
| `receiver_conciliation_id`       | string     | Identicação de conciliação do recebedor                                                               | 35                                                                |
| `end_to_end_id`                  | string     | Chave de idempotência de uma transação Pix - só deve ser enviado se o tipo de transferência for "key" | 32                                                                |
| `pix_message`                    | string     | Mensagem a ser enviada junto à transferência Pix                                                      | 140                                                               |
| `fee_amount`                     | number     | Valor da transferencia                                                                                | 10                                                                |
| `pix_transfer_status`            | string     | Status da transação pix                                                                               | 10                                                                |
| `account_key`                    | string     | Chave única de identificação da conta QI                                                              | 36                                                                |
| `pix_transfer_key`               | string     | Chave única de identificação da transferência Pix                                                     | 36                                                                |
| `original_outgoing_pix_transfer` | string     | Chave única de identificação da transferência Pix de saída Original                                   | 36                                                                |
| `original_end_to_end_id`         | string     | End to end da transferência Pix de saída Original                                                     | 36                                                                |
| `error_code`               | string     | Código do erro ocorrido na transação                                                                  | 20                                                                |
| `error_description`        | string     | Descrição do erro em inglês                                                                           | 200                                                               |
| `error_translation`        | string     | Descrição do erro traduzida para português                                                            | 200                                                               |
| `error_short_description`  | string     | Descrição curta do erro                                                                               | 100                                                               |

### Enumerador pix_transfer_type

| Enumerador          | Descrição                                |
|---------------------|------------------------------------------|
| **manual**          | Pix utilizando os dados da conta destino |
| **key**             | Pix utilizando uma chave pix             |
| **static_qr_code**  | Pix utilizando um QR code estático       |
| **dynamic_qr_code** | Pix utilizando um QR code dinâmico       |
| **reversal**        | Devolução Pix                            |

### Objeto source_account

| Campo                   | Tipo       | Descrição                                                                                               | Caracteres                                              |
|-------------------------|------------|---------------------------------------------------------------------------------------------------------|---------------------------------------------------------|
| `account_branch`        | string     | Agência da conta                                                                                        | 6                                                       |
| `account_digit`         | string     | Dígito da conta                                                                                         | 1                                                       |
| `account_number`        | string     | Número da conta                                                                                         | 20                                                      |
| `owner_document_number` | string     | CPF ou CNPJ (apenas números) do titular da conta                                                        | 14                                                      |
| `owner_name`            | string     | Nome do titular da conta                                                                                | 150                                                     |
| `account_type`          | enumerator | Tipo da conta                                                                                           | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb`                  | string     | Código de oito dígitos que identifica os bancos no sistema de transferência de reserva do Banco Central | 8                                                       |

### Enumerador account_type

| Enumerador           | Descrição           |
|----------------------|---------------------|
| **checking_account** | Conta Corrente      |
| **salary_account**   | Conta Salário       |
| **saving_account**   | Conta Poupança      |
| **payment_account**  | Conta de Pagamentos |

---

# baas_configurando_webhooks

URL: /documentation/baas/primeiros_passos/baas_configurando_webhooks



---

# Configurar IP de Integração

URL: /documentation/baas/primeiros_passos/baas_configurar_ip_de_integracao



---

# baas_inicio

URL: /documentation/baas/primeiros_passos/baas_inicio



---

# baas_troca_de_chaves

URL: /documentation/baas/primeiros_passos/baas_troca_de_chaves



---

# baas_endpoints_de_teste

URL: /documentation/baas/primeiros_passos/teste_de_autenticacao/baas_endpoints_de_teste



---

# baas_possiveis_erros

URL: /documentation/baas/primeiros_passos/teste_de_autenticacao/baas_possiveis_erros



---

# baas_teste_de_autenticacao_completo

URL: /documentation/baas/primeiros_passos/teste_de_autenticacao/baas_teste_de_autenticacao_completo



---

# baas_teste_de_autenticacao_v2

URL: /documentation/baas/primeiros_passos/teste_de_autenticacao/baas_teste_de_autenticacao_v2



---

# baas_webhook_v2

URL: /documentation/baas/primeiros_passos/teste_de_autenticacao/baas_webhook_v2



---

# Aprovar TED com Autenticação de Dois Fatores

URL: /documentation/baas/ted/2fa/aprovar_transacao_ted_2fa

## Request

ENDPOINT /account/ ACCOUNT_KEY /ted/ TED_KEY /validate_token
MÉTODO PUT

### Path Params

| Campo         | Tipo   | Descrição                                         | Caracteres |
|---------------|--------|---------------------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta.            | 36         |
| `ted_key`     | uuidv4 | Chave única de identificação da transferência TED | 36         |

## Autenticação via Email e SMS

Request Body

```json
{
  "token": "329123"
}
```

## Autenticação via Dispositivo

Para aprovar e finalizar a autenticação via dispositivo, a requisição deve ser enviada com um payload vazio. A validação ocorre internamente, sem necessidade de informações adicionais no corpo da requisição. É importante destacar que este endpoint só deve ser utilizado após a [solicitação de transação](./realizar_transferencia_2fa.md) ter sido iniciada.

Request Body

```json
{

}
```

## Body Params

| Campo     | Tipo   | Descrição                                                             | Caracteres |
|-----------|--------|-----------------------------------------------------------------------|------------|
| `token`   | string | Código de autenticação enviado ao aprovador de movimentações da conta **obrigatório para TFA via SMS ou e-mail**| 6          | 

## Response

STATUS 201

Response Body: Transferência Enviada

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "transaction_key": "46804f32-101e-4702-8fbc-c2dbc4c2caec",
  "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "transaction_amount": 202.01,
  "fee_amount": 10,
  "ted_status": "sent",
  "created_at": "2021-10-22T20:30:23.459Z"
}
```

STATUS 202

Response Body: Transferência Pendente

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "transaction_amount": 202.01,
  "fee_amount": 10,
  "ted_status": "pending",
  "created_at": "2021-10-22T20:30:23.459Z"
}
```

STATUS 4xx

Response Body: Transferência Rejeitada

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {
    "ted_data": {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "transaction_amount": 202.01,
      "fee_amount": 10,
      "ted_status": "rejected",
      "created_at": "2021-10-22T20:30:23.459Z"
    }
  }
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

:::info Informação
Os erros anteriormente listados para [realizar TED](/documentation/baas/ted/realizar_transferencia) são
passiveis de serem retornados por este endpoint além dos erros listados abaixo.
:::

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                           | Descrição (eng)<br/>`description`                                       | Descrição (ptbr)<br/>`translation`                                  |
|--------------------------|----------------------|----------------------------------------------|-------------------------------------------------------------------------|---------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                  | Schema Error                                                            | Erro de Schema                                                      |
| 404                      | TED000020            | Not Found                                    | Ted was not found for the given parameters.                             | Ted não encontrada para os parâmetros fornecidos.                   |
| 404                      | TED000086            | Invalid Status                               | Ted not in pending_2fa_approval status                                  | Ted não está pendente de aprovação por autenticação de dois fatores |
| 400                      | TED000082            | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida          |
| 400                      | TED000084            | Incorrect Token                              | Token sent does not match expected                                      | Token enviado não condiz com, o esperado                            |
| 400                      | TED000083            | Token Expired                                | Token has expired. Resend token or recreate transfer                    | Token expirado. Reenvie token ou recrie a transferência             |
| 400                      | TED000110            | Token Required                                | A token is required for SMS or email validation.                    | Um token é necessário para validação via SMS ou email.             |

---

# Realizar TED com Autenticação de Dois Fatores

URL: /documentation/baas/ted/2fa/realizar_transferencia_2fa

Neste tipo de transação, é necessário a confirmação do pagamento via token enviado à pessoa com poderes de aprovação de
movimentação na conta credora.

A solicitação de transação TED por parceiros integradores configurados para a utilização de autenticação de dois
fatores é realizada de forma similar ao descrito
em [realizar TED](/documentation/baas/ted/realizar_transferencia). A diferença ocorre na adição do
objeto `tfa_info`, contento informações sobre o aprovador da transferência e a forma de contato, e o status de uma
solicitação bem sucedida que será sempre **pending_2fa_approval**.

## Request

ENDPOINT /account/ ACCOUNT_KEY /ted
MÉTODO POST

## Autenticação via Email e SMS

Request Body

```json
{
  "request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
  "target_account": {
    "account_branch": "0001",
    "account_number": "92796",
    "account_digit": "1",
    "owner_document_number": "23599885000192",
    "owner_name": "Titular da Conta",
    "ispb": "12345678",
    "account_type": "checking_account"
  },
  "transaction_amount": 8.86,
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```

## Autenticação via Dispositivo

Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`.

Request Body

```json
{
  "request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
  "target_account": {
    "account_branch": "0001",
    "account_number": "92796",
    "account_digit": "1",
    "owner_document_number": "23599885000192",
    "owner_name": "Titular da Conta",
    "ispb": "12345678",
    "account_type": "checking_account"
  },
  "transaction_amount": 8.86,
  "tfa_info": {
    "approver_document_number": "98765432100",
    "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
    "contact_type": "device"
  }
}
```

## Body Params

| Campo                   | Tipo   | Descrição                                                                          | Caracteres                                          |
|-------------------------|--------|------------------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | string | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36                                                  |
| `target_account` *      | object | Conta de destino                                                                   | **[Objeto target_account](#objeto-target_account)** | 
| `transaction_amount` *  | float  | Valor da transferência                                                             | 10                                                  |
| `tfa_info`*             | object | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato.    | **[Objeto tfa_info](#objeto-tfa_info)**             |

## Objeto target_account

| Campo                     | Tipo   | Descrição                                           | Caracteres                                                |
|---------------------------|--------|-----------------------------------------------------|-----------------------------------------------------------|
| `account_branch` *        | string | Agência.                                            | 4                                                         |
| `account_digit` *         | string | Dígito da conta                                     | 1                                                         |
| `account_number` *        | string | Número da conta.                                    | 20                                                        |
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta.   | 14                                                        |
| `owner_name` *            | string | Nome do titular da conta.                           | 50                                                        |
| `account_type`*           | string | Tipo da conta.                                      | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string | Base no CNPJ da instituição financeira (8 dígitos). | 8                                                         |

## Objeto tfa_info

| Campo                       | Tipo   | Descrição                                                                           | Caracteres |
|-----------------------------|--------|-------------------------------------------------------------------------------------|------------|
| `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta.                                  | 11         | 
| `session_id`| string | Chave única de identificação da sessão do dispositivo no formato UUID v4 (obrigatório para TFA via dispositivo). |   36         |
| `contact_type`*             | string | Forma de contato com a pessoa aprovadora da conta, podendo ser **sms**, **email** ou **device** |            |

## Enumerador account_type

| Enumerador             | Tradução              |
|------------------------|-----------------------|
| **checking_account**   | conta corrente        |
| **deposit_account**    | conta depósito        |
| **guaranteed_account** | conta de garantia     |
| **investment_account** | conta de investimento |
| **payment_account**    | conta de pagamento    |
| **saving_account**     | conta poupança        |

## Response

STATUS 202

Response Body

```json
{
  "request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
  "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "created_at": "2021-10-22T20:30:23.459Z",
  "ted_status": "pending_2fa_approval",
  "transaction_amount": 126.97,
  "fee_amount": 0.0
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

:::info Informação
Os erros anteriormente listados para [realizar TED](/documentation/baas/ted/realizar_transferencia) são
passiveis de serem retornados por este endpoint além dos erros listados abaixo.
:::

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                 | Descrição (eng)<br/>`description`                                     | Descrição (ptbr)<br/>`translation`                               |
|--------------------------|----------------------|------------------------------------|-----------------------------------------------------------------------|------------------------------------------------------------------|
| 400                      | TED000079            | No approver permission             | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta |
| 400                      | TED000080            | tfa_info is required               | Client must send object tfa_info                                      | Cliente deve enviar objeto tfa_info                              |
| 400                      | TED000081            | Error occurred while sending token | An unexpected error occurred while sending token                      | Um erro inexperado ocorreu ao tentar enviar token                |
| 400                      | TED0000109           | Session ID needed | A session_id must be provided token | Uma session_id deve ser fornecida |

---

# Solicitar Reenvio de Token para uma Transação Ted

URL: /documentation/baas/ted/2fa/solicitacao_de_reenvio_de_token

Um novo token será gerado e enviado para o aprovador da transação Ted. Caso o número limite de tentativas de validação
do token tenha sido excedida, não será permitido o reenvio.

## Request

ENDPOINT /account/ ACCOUNT_KEY /ted/ TED_KEY /resend_token
MÉTODO PATCH

### Path Params

| Campo           | Tipo   | Descrição                                         | Caracteres |
|-----------------|--------|---------------------------------------------------|------------|
| `account_key` * | uuidv4 | Chave única de identificação da conta.            | 36         |
| `ted_key` *     | uuidv4 | Chave única de identificação da transferência TED | 36         |

## Body Params

| Campo          | Tipo   | Descrição                                                                                 | Caracteres |
|----------------|--------|-------------------------------------------------------------------------------------------|------------|
| `contact_type` | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** |

:::info Informação
Caso não seja enviado um `contact_type`, o token será enviado da forma solicitada originalmente.
:::

### Enumerador contact_type

| Enumerador | Descrição                                         |
|------------|---------------------------------------------------|
| **sms**    | Envio por Mensagem de Texto para telefone celular |
| **email**  | Envio por correio eletrônico                      |

## Response

STATUS 202

Response Body: Transação Solicitada

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "transaction_amount": 202.01,
  "fee_amount": 10,
  "ted_status": "pending_2fa_approval",
  "created_at": "2021-10-22T20:30:23.459Z"
}
```

STATUS 4xx

Response Body: Transferência Rejeitada

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {
    "ted_data": {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "transaction_amount": 202.01,
      "fee_amount": 10,
      "ted_status": "rejected",
      "created_at": "2021-10-22T20:30:23.459Z"
    }
  }
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                           | Descrição (eng)<br/>`description`                                       | Descrição (ptbr)<br/>`translation`                                        |
|--------------------------|----------------------|----------------------------------------------|-------------------------------------------------------------------------|---------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                  | Schema Error                                                            | Erro de Schema                                                            |
| 404                      | TED000009            | Account not found                            | Account not found for the given key: \{account_key\}                    | Conta não encontrada para a chave fornecida: \{account_ke\}               |
| 404                      | TED000020            | Not Found                                    | Ted was not found for the given parameters.                             | Ted não encontrada para os parâmetros fornecidos.                         |
| 404                      | TED000086            | Invalid Status                               | Ted not in pending_2fa_approval status                                  | Ted não está pendente de aprovação por autenticação de dois fatores |
| 400                      | TED000082            | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida                |
| 400                      | TED000087            | Error Sending Token                          | An error occurred while resending token and its being investigated      | Um erro ocorreu ao reenviar token e está sendo investigado                |

---

# Aprovar Transação em Lote com Autenticação de Dois Fatores

URL: /documentation/baas/ted/batch_2fa/aprovar_transacao_em_lote_ted_2fa

## Request

ENDPOINT /account/ ACCOUNT_KEY /ted_batch/ TED_BATCH_KEY /validate_token
MÉTODO PUT

### Path Params

| Campo           | Tipo   | Descrição                                              | Caracteres |
|-----------------|--------|--------------------------------------------------------|------------|
| `account_key`   | uuidv4 | Chave única de identificação da conta.                 | 36         |
| `ted_batch_key` | uuidv4 | Chave única de identificação da transação em lote ted. | 36         |

## Autenticação via Email e SMS

Request Body

```json
{
  "token": "329123"
}
```

## Autenticação via Dispositivo

Para aprovar e finalizar a autenticação via dispositivo, a requisição deve ser enviada com um payload vazio. A validação ocorre internamente, sem necessidade de informações adicionais no corpo da requisição. É importante destacar que este endpoint só deve ser utilizado após a [solicitação de transação em lote](./solicitacao_de_transacao_em_lote_ted_2fa.md) ter sido iniciada.

Request Body

```json
{

}
```

## Body Params

| Campo   | Tipo   | Descrição                                                                                                                              | Caracteres |
|---------|--------|----------------------------------------------------------------------------------------------------------------------------------------|------------|
| `token` | string | Código de autenticação enviado ao aprovador de movimentações da conta **obrigatório para TFA via SMS ou e-mail**                       | 6          |

## Response

STATUS 201

Response Body: Lote Aprovado

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "ted_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "ted_batch_status": "approved"
}
```

STATUS 4xx

Response Body: Lote Rejeitado

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {
    "ted_batch_data": {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "ted_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "ted_batch_status": "rejected"
    }
  }
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                           | Descrição (eng)<br/>`description`                                                                        | Descrição (ptbr)<br/>`translation`                                          |
|--------------------------|----------------------|----------------------------------------------|----------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| 400                      | TED000082            | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached                                  | Número máximo de tentativas de validação de token atingida                  |
| 400                      | TED000083            | Token Expired                                | Token has expired. Resend token or recreate transferToken has expired. Resend token or recreate transfer | Token expirado. Reenvie token ou recrie a transferência                     |
| 400                      | TED000084            | Incorrect Token                              | Token sent does not match expected                                                                       | Token enviado não condiz com, o esperado                                    |
| 404                      | TED000101            | TedBatch not Found                           | Ted Batch was not found                                                                                  | TedBatch não encontrada                                                     |
| 400                      | TED000102            | Invalid Status                               | Ted Batch not in pending_2fa_approval status                                                             | Lote de Ted não está pendente de aprovação por autenticação de dois fatores |
| 400                      | TED000110            | Token Required                               | A token is required for SMS or email validation.                                                         | Um token é necessário para validação via SMS ou email.                                                     |

---

# Solicitar Reenvio de Token para uma Transação Ted em Lote

URL: /documentation/baas/ted/batch_2fa/solicitacao_de_reenvio_de_token_para_lote_ted

Um novo token será gerado e enviado para o aprovador de movimentação da conta. Caso o número limite de tentativas de
validação do token tenha sido excedida, não será permitido o reenvio.

## Request

ENDPOINT /account/ ACCOUNT_KEY /ted_batch/ TED_BATCH_KEY /resend_token
MÉTODO PATCH

### Path Params

| Campo             | Tipo   | Descrição                                          | Caracteres |
|-------------------|--------|----------------------------------------------------|------------|
| `account_key` *   | uuidv4 | Chave única de identificação da conta.             | 36         |
| `ted_batch_key` * | uuidv4 | Chave única de identificação da transação em lote. | 36         |

Request Body

```json
{
  "contact_type": "sms"
}
```

## Body Params

| Campo          | Tipo       | Descrição                               | Caracteres                                              |
|----------------|------------|-----------------------------------------|---------------------------------------------------------|
| `contact_type` | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** |

:::info Informação
Caso não seja enviado um `contact_type`, o token será enviado da forma solicitada originalmente.
:::

### Enumerador contact_type

| Enumerador | Descrição                                         |
|------------|---------------------------------------------------|
| **sms**    | Envio por Mensagem de Texto para telefone celular |
| **email**  | Envio por correio eletrônico                      |

## Response

STATUS 202

Response Body: Transação Solicitada

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "ted_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "ted_status": "pending_2fa_approval"
}
```

STATUS 4xx

Response Body: Transferência Rejeitada

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {
    "ted_data": {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "ted_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "ted_status": "rejected"
    }
  }
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                           | Descrição (eng)<br/>`description`                                       | Descrição (ptbr)<br/>`translation`                                          |
|--------------------------|----------------------|----------------------------------------------|-------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                  | Schema Error                                                            | Erro de Schema                                                              |
| 404                      | TED000009            | Account not found                            | Account not found for the given key: \{account_key\}                    | Conta não encontrada para a chave fornecida: \{account_ke\}                 |
| 404                      | TED000020            | Not Found                                    | Ted was not found for the given parameters.                             | Ted não encontrada para os parâmetros fornecidos.                           |
| 400                      | TED000082            | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached | Número máximo de tentativas de validação de token atingida                  |
| 400                      | TED000083            | Token Expired                                | Token has expired. Resend token or recreate transfer                    | Token expirado. Reenvie token ou recrie a transferência                     |
| 400                      | TED000084            | Incorrect Token                              | Token sent does not match expected                                      | Token enviado não condiz com, o esperado                                    |
| 404                      | TED000086            | Invalid Status                               | Ted not in pending_2fa_approval status                                  | Ted não está pendente de aprovação por autenticação de dois fatores         |
| 400                      | TED000087            | Error Sending Token                          | An error occurred while resending token and its being investigated      | Um erro ocorreu ao reenviar token e está sendo investigado                  |
| 404                      | TED000101            | TedBatch not Found                           | Ted Batch was not found                                                 | TedBatch não encontrada                                                     |
| 400                      | TED000102            | Invalid Status                               | Ted Batch not in pending_2fa_approval status                            | Lote de Ted não está pendente de aprovação por autenticação de dois fatores |

---

# Realizar Transação Ted em Lote com Autenticação de Dois Fatores

URL: /documentation/baas/ted/batch_2fa/solicitacao_de_transacao_em_lote_ted_2fa

A QI Tech oferece a possibilidade de realizar várias transações ted com uma única chamada. Nesse sistema as transações
são realizadas de forma assíncrona. Caso na chamada inicial seja retornado um **http status 4xx**, nenhuma das
transações será realizada. Após a solicitação, o parceiro integrador receberá um webhook para cada transação informando
o status final da tentativa, podendo ser **rejected** ou **sent**.

Neste tipo de transação, é necessário a confirmação do pagamento via token enviado à pessoa com poderes de aprovação de
movimentação na conta credora.

A solicitação de transação Ted por parceiros integradores configurados para a utilização de autenticação de dois fatores
é realizada de forma similar ao descrito
em [realizar transação ted em lote](/documentation/baas/ted/batch/solicitacao_de_transacao_em_lote_ted). A diferença
ocorre na adição do objeto `tfa_info`, contento informações sobre o aprovador da transferência e a forma de contato, e o
status de uma solicitação bem sucedida que será sempre **pending_2fa_approval**.

O evento de notificação para o envio de `token` ao aprovador é **baas.token_validation.ted.batch**. É
possível [personalizar](/documentation/notificacoes/template) a mensagem enviada.

## Request

ENDPOINT /account/ ACCOUNT_KEY /ted_batch
MÉTODO POST

## Autenticação via Email e SMS

Request Body: Transferência em Lote com TFA por SMS ou Email

```json
{
  "request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  },
  "teds": [
    {
      "request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
      "target_account": {
        "account_branch": "0001",
        "account_number": "92796",
        "account_digit": "1",
        "owner_document_number": "23599885000192",
        "owner_name": "Titular da Conta",
        "ispb": "12345678",
        "account_type": "checking_account"
      },
      "transaction_amount": 8.86
    },
    {
      "request_control_key": "ff9f2a48-918c-4911-9371-a496e37dccfc",
      "target_account": {
        "account_branch": "0001",
        "account_number": "92797",
        "account_digit": "2",
        "owner_document_number": "23599885000192",
        "owner_name": "Titular da Conta",
        "ispb": "12345678",
        "account_type": "checking_account"
      },
      "transaction_amount": 10.00
    }
  ]
}
```

## Autenticação via Dispositivo

Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`.

Request Body: Transferência em Lote com TFA por Dispositivo

```json
{
  "request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
    "contact_type": "device"
  },
  "teds": [
    {
      "request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
      "target_account": {
        "account_branch": "0001",
        "account_number": "92796",
        "account_digit": "1",
        "owner_document_number": "23599885000192",
        "owner_name": "Titular da Conta",
        "ispb": "12345678",
        "account_type": "checking_account"
      },
      "transaction_amount": 8.86
    },
    {
      "request_control_key": "ff9f2a48-918c-4911-9371-a496e37dccfc",
      "target_account": {
        "account_branch": "0001",
        "account_number": "92797",
        "account_digit": "2",
        "owner_document_number": "23599885000192",
        "owner_name": "Titular da Conta",
        "ispb": "12345678",
        "account_type": "checking_account"
      },
      "transaction_amount": 10.00
    }
  ]
}
```

## Path Params

| Campo         | Tipo   | Descrição                              | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36         |

## Body Params

| Campo                   | Tipo   | Descrição                                                                          | Caracteres                              |
|-------------------------|--------|------------------------------------------------------------------------------------|-----------------------------------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36                                      | 
| `teds` *                | array  | Lista de objetos ted vinculados ao lote.                                           | lista de **[Objeto ted](#objeto-ted)**  |
| `tfa_info`*             | Object | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato.    | **[Objeto tfa_info](#objeto-tfa_info)** |

## Objeto tfa_info

| Campo                       | Tipo   | Descrição                                                                                                                        | Caracteres |
|-----------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------|------------|
| `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta.                                                                               | 11         |
| `session_id`                | string | Chave única de identificação da sessão do dispositivo no formato UUID v4 (obrigatório para TFA via dispositivo).                 | 36         |
| `contact_type`*             | string | Forma de contato com a pessoa aprovadora da conta, podendo ser **sms**, **email** ou **device**                                  |            |

## Objeto ted

| Campo                   | Tipo   | Descrição                                                                          | Caracteres                                          |
|-------------------------|--------|------------------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | string | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36                                                  |
| `target_account` *      | object | Conta de destino                                                                   | **[Objeto target_account](#objeto-target_account)** | 
| `transaction_amount` *  | float  | Valor da transferência                                                             | 10                                                  |

## Objeto target_account

| Campo                     | Tipo   | Descrição                                           | Caracteres                                              |
|---------------------------|--------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string | Agência.                                            | 4                                                       |
| `account_digit` *         | string | Dígito da conta                                     | 1                                                       |
| `account_number` *        | string | Número da conta.                                    | 20                                                      |
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta.   | 14                                                      |
| `owner_name` *            | string | Nome do titular da conta.                           | 50                                                      |
| `account_type`*           | string | Tipo da conta.                                      | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string | Base no CNPJ da instituição financeira (8 dígitos). | 8                                                       |

## Enumerador account_type

| Enumerador             | Tradução              |
|------------------------|-----------------------|
| **checking_account**   | conta corrente        |
| **deposit_account**    | conta depósito        |
| **guaranteed_account** | conta de garantia     |
| **investment_account** | conta de investimento |
| **payment_account**    | conta de pagamento    |
| **saving_account**     | conta poupança        |

## Response

STATUS 202

Response Body: Transferência em Lote Solicitada

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "ted_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "ted_batch_status": "pending_2fa_approval"
}
```

### Enumerador ted_batch_status

| Enumerador               | Descrição                                                                  |
|--------------------------|----------------------------------------------------------------------------|
| **approved**             | Transferência em lote aprovada e transações em processo de execução.       |
| **rejected**             | Transferência em lote rejeitada                                            |
| **pending_2fa_approval** | Agendamento em lote pendente de aprovação por autenticação de dois fatores |
| **cancelled**            | Transferência em lote cancelada                                            |

STATUS 4xx

Response Body: Transferência Rejeitada

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {
    "ted_batch_data": {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "ted_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "ted_batch_status": "rejected"
    }
  }
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

:::info Informação
Os erros anteriormente listados para [transferência Ted](/documentation/baas/ted/solicitacao_de_transacao_em_lote_ted)
são
passiveis de serem retornados por este endpoint além dos erros listados abaixo.
:::

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                 | Descrição (eng)<br/>`description`                                     | Descrição (ptbr)<br/>`translation`                               |
|--------------------------|----------------------|------------------------------------|-----------------------------------------------------------------------|------------------------------------------------------------------|
| 400                      | TED000079            | No approver permission             | Given document number does not belong to an approver for this account | Número de documento enviado não pertence a um aprovador da conta |
| 400                      | TED000080            | tfa_info is required               | Client must send object tfa_info                                      | Cliente deve enviar objeto tfa_info                              |
| 400                      | TED000081            | Error occurred while sending token | An unexpected error occurred while sending token                      | Um erro inexperado ocorreu ao tentar enviar token                |

---

# Introdução a Transação em Lote Ted

URL: /documentation/baas/ted/batch/introducao_a_transacao_em_lote_ted

A QI Tech oferece a possibilidade de realizar várias transações ted com uma única chamada. Nesse sistema, as transações
são realizadas de forma assíncrona. Caso na chamada inicial seja retornado um **http status 4xx**, nenhuma das
transações será realizada. Após a solicitação, o parceiro integrador receberá um webhook para cada transação informando
o status final da tentativa, podendo ser **rejected** ou **sent**.

## Autenticação de Dois Fatores

Assim como em transações ted, parceiros integradores com configuração de autenticação de dois fatores devem enviar o
objeto `tfa_info` com as informações de contato e envio de token.

---

# Listar Transações Ted de um lote de uma conta

URL: /documentation/baas/ted/batch/listar_transacoes_de_um_lote_de_transacoes_ted

## Request

ENDPOINT /account/ ACCOUNT_KEY /ted_batch/ TED_BATCH_KEY /teds
MÉTODO GET

### Path Params

| Campo           | Tipo   | Descrição                                          | Caracteres |
|-----------------|--------|----------------------------------------------------|------------|
| `account_key`   | uuidv4 | Chave única de identificação da conta.             | 36         |
| `ted_batch_key` | uuidv4 | Chave única de identificação da transação em lote. | 36         |

### Query Params

| Campo                 | Tipo    | Descrição                                                               | Caracteres                                          |
|-----------------------|---------|-------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` | uuidv4  | Chave única de identificação da request utilizada pelo cliente.         | 36                                                  |
| `ted_status`          | string  | Status da transação TED. Pode ser enviado como lista.                   | **[Enumerador ted_status](#enumerador-ted_status)** |
| `date_from`           | string  | Data inicial. Formato "YYYY-MM-DD"                                      | 10                                                  |
| `date_to`             | string  | Data final. Formato "YYYY-MM-DD"                                        | 10                                                  |
| `page`                | integer | Número da página requisitada. 1 por padrão                              |                                                     |
| `page_size`           | integer | Tamanho da página requisitada na consulta. 30 por padrão e valor máximo | Valor máximo de 30                                  |

## Enumerador ted_status

| Enumerador   | Descrição                                |
|--------------|------------------------------------------|
| **sent**     | Transferência TED realizada com sucesso. |
| **pending**  | Transferência TED pendente.              |
| **rejected** | Transferência TED rejeitada.             |
| **returned** | Transferência TED devolvida.             |

### Response

STATUS 200

Response Body

```json
{
  "data": [
    {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "ted_status": "sent"
    },
    {
      "request_control_key": "697c07c3-5398-48d2-a418-853323f85f97",
      "ted_key": "e95eabdb-4520-4c3d-a76f-99cb5b64724b",
      "ted_status": "sent"
    },
    {
      "request_control_key": "ca35c526-b5a0-40d7-8c56-8566c77a34f4",
      "ted_key": "58d2fa9e-42ec-4779-b2fc-14ec98cbdca8",
      "ted_status": "rejected"
    }
  ],
  "pagination": {
    "current_page": 1,
    "rows_per_page": 30
  }
}

```

---

# Listar Transações em Lote de uma conta

URL: /documentation/baas/ted/batch/listar_transacoes_em_lote_ted_de_uma_conta

## Request

ENDPOINT /account/ ACCOUNT_KEY /ted_batches
MÉTODO GET

### Path Params

| Campo         | Tipo   | Descrição                              | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36         |

### Query Params

| Campo                 | Tipo    | Descrição                                                               | Caracteres                                                      |
|-----------------------|---------|-------------------------------------------------------------------------|-----------------------------------------------------------------|
| `request_control_key` | uuidv4  | Chave única de identificação da request utilizada pelo cliente.         | 36                                                              |
| `ted_batch_status`    | uuidv4  | Status do lote de transações Ted. Pode ser enviado como lista.          | **[Enumerador ted_batch_status](#enumerador-ted_batch_status)** |
| `date_from`           | string  | Data inicial. Formato "YYYY-MM-DD"                                      | 10                                                              |
| `date_to`             | string  | Data final. Formato "YYYY-MM-DD"                                        | 10                                                              |
| `page`                | integer | Número da página requisitada. 1 por padrão                              |                                                                 |
| `page_size`           | integer | Tamanho da página requisitada na consulta. 30 por padrão e valor máximo | Valor máximo de 30                                              |

### Enumerador ted_batch_status

| Enumerador               | Descrição                                                                  |
|--------------------------|----------------------------------------------------------------------------|
| **approved**             | Transferência em lote aprovada e transações em processo de execução.       |
| **rejected**             | Transferência em lote rejeitada                                            |
| **pending_2fa_approval** | Agendamento em lote pendente de aprovação por autenticação de dois fatores |
| **cancelled**            | Transferência em lote cancelada                                            |

### Response

STATUS 200

Response Body

```json
{
  "data": [
    {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "ted_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "ted_batch_status": "approved"
    },
    {
      "request_control_key": "939d1503-aa5a-49a6-ae3b-ff84122a6dd3",
      "ted_batch_key": "03cf9181-0eb9-480e-8bb4-66a5a9a6410e",
      "ted_batch_status": "rejected"
    },
    {
      "request_control_key": "43a14f3a-b2af-4a0e-8a74-70af2fca74a9",
      "ted_batch_key": "94ab9fad-9c65-4117-b9c3-a47b1269508f",
      "ted_batch_status": "approved"
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "rows_per_page": 30
  }
}

```

---

# Realizar Transação Ted em Lote

URL: /documentation/baas/ted/batch/solicitacao_de_transacao_em_lote_ted

A QI Tech oferece a possibilidade de realizar várias transações ted com uma única chamada. Nesse sistema, as transações
são realizadas de forma assíncrona. Caso na chamada inicial seja retornado um **http status 4xx**, nenhuma das
transações será realizada. Após a solicitação, o parceiro integrador receberá um webhook para cada transação informando
o status final da tentativa, podendo ser **rejected** ou **sent**.

## Request

ENDPOINT /account/ ACCOUNT_KEY /ted_batch
MÉTODO POST

```json
{
  "request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
  "teds": [
    {
      "request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
      "target_account": {
        "account_branch": "0001",
        "account_number": "92796",
        "account_digit": "1",
        "owner_document_number": "23599885000192",
        "owner_name": "Titular da Conta",
        "ispb": "12345678",
        "account_type": "checking_account"
      },
      "transaction_amount": 8.86
    }
  ]
}
```

## Path Params

| Campo         | Tipo   | Descrição                              | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36         |

## Body Params

| Campo                   | Tipo   | Descrição                                                                          | Caracteres                             |
|-------------------------|--------|------------------------------------------------------------------------------------|----------------------------------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36                                     | 
| `teds` *                | array  | Lista de objetos ted vinculados ao lote.                                           | lista de **[Objeto ted](#objeto-ted)** |

## Objeto ted

| Campo                   | Tipo   | Descrição                                                                          | Caracteres                                          |
|-------------------------|--------|------------------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | string | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36                                                  |
| `target_account` *      | object | Conta de destino                                                                   | **[Objeto target_account](#objeto-target_account)** | 
| `transaction_amount` *  | float  | Valor da transferência                                                             | 10                                                  |

## Objeto target_account

| Campo                     | Tipo   | Descrição                                           | Caracteres                                              |
|---------------------------|--------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string | Agência.                                            | 4                                                       |
| `account_digit` *         | string | Dígito da conta                                     | 1                                                       |
| `account_number` *        | string | Número da conta.                                    | 20                                                      |
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta.   | 14                                                      |
| `owner_name` *            | string | Nome do titular da conta.                           | 50                                                      |
| `account_type`*           | string | Tipo da conta.                                      | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string | Base no CNPJ da instituição financeira (8 dígitos). | 8                                                       |

## Enumerador account_type

| Enumerador             | Tradução              |
|------------------------|-----------------------|
| **checking_account**   | conta corrente        |
| **deposit_account**    | conta depósito        |
| **guaranteed_account** | conta de garantia     |
| **investment_account** | conta de investimento |
| **payment_account**    | conta de pagamento    |
| **saving_account**     | conta poupança        |

## Response

STATUS 201

Response Body: Transferência em lote Aprovada

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "ted_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "ted_batch_status": "approved"
}
```

### Enumerador ted_batch_status

| Enumerador               | Descrição                                                                  |
|--------------------------|----------------------------------------------------------------------------|
| **approved**             | Transferência em lote aprovada e transações em processo de execução.       |
| **rejected**             | Transferência em lote rejeitada                                            |
| **pending_2fa_approval** | Agendamento em lote pendente de aprovação por autenticação de dois fatores |
| **cancelled**            | Transferência em lote cancelada                                            |

STATUS 4xx

Response Body: Lote Rejeitado

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {
    "ted_batch_data": {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "ted_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "ted_batch_status": "rejected"
    }
  }
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

:::info Informação
Os erros anteriormente listados para [transferência Ted](/documentation/baas/ted/realizar_transferencia) são
passiveis de serem retornados por este endpoint.
:::

---

# Consultar TED

URL: /documentation/baas/ted/consultar_ted

## Request

ENDPOINT /account/ ACCOUNT_KEY /ted/ TED_KEY / TED_DIRECTION
MÉTODO GET

## Request Path Params

| Campo             | Tipo   | Descrição                                                   | Caracteres                                                  |
|-------------------|--------|-------------------------------------------------------------|-------------------------------------------------------------|
| `ted_direction` * | string | Filtro para indicar se uma transação é de entrada ou saída. | **[Enumerador ted_direction](#enumeradores-ted_direction)** |
| `account_key` *   | uuidv4 | Chave única de identificação da conta QI                    | 36                                                          |
| `ted_key` *       | uuidv4 | Chave única de identificação da transferência TED           | 36                                                          |

## Enumeradores ted_direction

| Enumerador | Tradução |
|------------|----------|
| incoming   | entrada  |
| outgoing   | saída    |

:::caution Atenção
Será apenas permitida a visualização de uma transferência caso o requisitante tenha permissões na conta de saída da
transação para o caso da ted_direction de outgoing ou tenha permissões na conta de entrada da
transação para o caso da ted_direction de incoming. Caso o contrário um erro de não encontrado será retornado.
:::

## Response

STATUS 200

Response Body: Transferência Rejeitada (outgoing)

```json
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "created_at": "2021-10-22T20:30:23.459Z",
  "ted_status": "rejected",
  "transaction_amount": 126.97,
  "fee_amount": 0.0,
  "target_account": {
    "account_branch": "0001",
    "account_digit": "6",
    "account_number": "78340",
    "ispb": "12345678",
    "owner_document_number": "32402502000135",
    "owner_name": "QI Tech"
  },
  "refusal_reason": {
    "refusal_code": 1,
    "enumerator": "conta_destinatario_encerrada",
    "description": "Conta Destinatária do Crédito Encerrada"
  }
}
```

Response Body: Transferência Enviada (outgoing)

```json
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "created_at": "2021-10-22T20:30:23.459Z",
  "ted_status": "sent",
  "transaction_amount": 126.97,
  "fee_amount": 0.0,
  "target_account": {
    "account_branch": "0001",
    "account_digit": "6",
    "account_number": "78340",
    "ispb": "12345678",
    "owner_document_number": "32402502000135",
    "owner_name": "QI Tech"
  },
  "refusal_reason": {}
}
```

Response Body: Transferência Recebida (incoming)

```json
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "created_at": "2021-10-22T20:30:23.459Z",
  "ted_status": "received",
  "transaction_amount": 126.97,
  "fee_amount": 0.0,
  "source_account": {
    "account_branch": "0001",
    "account_digit": "6",
    "account_number": "78340",
    "ispb": "12345678",
    "owner_document_number": "32402502000135",
    "owner_name": "QI Tech"
  },
  "refusal_reason": {}
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`     | Descrição (eng)<br/>`description` | Descrição (ptbr)<br/>`translation`                                     |
|--------------------------|----------------------|------------------------|-----------------------------------|------------------------------------------------------------------------|
| 404                      | TED000020            | Not Found | Ted was not found for the given parameters. | Ted não encontrada para os parâmetros fornecidos.   |

---

# Tabela de Erros para Ted

URL: /documentation/baas/ted/erros_ted

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                  | Descrição (eng)<br/>`description`                                                                                                                                                                                        | Descrição (ptbr)<br/>`translation`                                                                                                                                                                                    |
|--------------------------|----------------------|-----------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                         | schema error description                                                                                                                                                                                                 | Schema Inválido                                                                                                                                                                                                       |
| 500                      | QIT000500            | Internal Error                                      | An internal error has occurred and its being investigated.                                                                                                                                                               | Um erro interno aconteceu e está sendo investigado                                                                                                                                                                    |
| 400                      | TED000001            | Bad Request                                         | Account already have a fee created                                                                                                                                                                                       | A conta já tem uma taxa criada                                                                                                                                                                                        |
| 400                      | TED000002            | Bad Request                                         | Fee not already created                                                                                                                                                                                                  | Taxa ainda não criada                                                                                                                                                                                                 |
| 403                      | TED000003            | Unauthorized                                        | This agent can not add a financial institution.                                                                                                                                                                          | Este agente não pode adicionar uma instituição financeira.                                                                                                                                                            |
| 400                      | TED000004            | Bad Request                                         | The cockpit_key must be unique (error raised on commit: \{msg\})                                                                                                                                                         | A cockpit_key deve ser exclusiva (erro gerado no commit: \{msg\})                                                                                                                                                     |
| 400                      | TED000005            | Bad Request                                         | Event for the provided transaction_code not implemented                                                                                                                                                                  | Evento para a transaction_code fornecida não implementado                                                                                                                                                             |
| 404                      | TED000006            | Target account Not Found                            | Target account was not found for given parameters                                                                                                                                                                        | Conta destino não encontrada para os parâmetros informados                                                                                                                                                            |
| 400                      | TED000007            | Bad Request                                         | A related_account_key must be provided                                                                                                                                                                                   | Uma chave related_account_key deve ser fornecida                                                                                                                                                                      |
| 404                      | TED000008            | Not Found                                           | No related_account found                                                                                                                                                                                                 | Nenhuma conta relacionada encontrada                                                                                                                                                                                  |
| 404                      | TED000009            | Not Found                                           | Account not found for the given key: \{account_key\}                                                                                                                                                                     | Conta não encontrada para a chave fornecida: \{account_key\}                                                                                                                                                          |
| 400                      | TED000010            | Bad Request                                         | Account already registered                                                                                                                                                                                               | Conta já registrada                                                                                                                                                                                                   |
| 400                      | TED000011            | Bad Request                                         | Wrong day/time for TED                                                                                                                                                                                                   | Dia/hora incorretos para a TED                                                                                                                                                                                        |
| 400                      | TED000012            | Bad Request                                         | The target's length of the account + account_digit cannot be larger than 21                                                                                                                                              | O número de digitos na conta de destino + digito não pode ser maior que 21                                                                                                                                            |
| 400                      | TED000013            | Bad Request                                         | Unable to find source_account_key's account                                                                                                                                                                              | Não foi possível encontrar a conta com source_account_key fornecido                                                                                                                                                   |
| 403                      | TED000014            | Invalid target account                              | Invalid target account                                                                                                                                                                                                   | Conta destino inválida                                                                                                                                                                                                |
| 400                      | TED000015            | Bad Request                                         | Account blocked or closed can not perform this action                                                                                                                                                                    | A conta bloqueada ou fechada não pode executar esta ação                                                                                                                                                              |
| 400                      | TED000016            | Bad Request                                         | Hub account can not perform this action                                                                                                                                                                                  | A conta hub não pode executar esta ação                                                                                                                                                                               |
| 403                      | TED000017            | Unauthorized                                        | Provided account does not have approval credential for the given person                                                                                                                                                  | A conta fornecida não possui credencial de aprovação para a pessoa especificada                                                                                                                                       |
| 403                      | TED000018            | Unauthorized                                        | Provided account not owned by SELECTED_AGENT                                                                                                                                                                             | Conta fornecida não pertencente ao SELECTED_AGENT                                                                                                                                                                     |
| 400                      | TED000019            | Bad Request                                         | Scheduling not implemented yet                                                                                                                                                                                           | Agendamento ainda não implementado                                                                                                                                                                                    |
| 404                      | TED000020            | Not Found                                           | Ted was not found for the given parameters.                                                                                                                                                                              | Ted não encontrada para os parâmetros fornecidos.                                                                                                                                                                     |
| 400                      | TED000021            | Bad Request                                         | A ted_type must be provided                                                                                                                                                                                              | Um tipo de ted deve ser fornecido                                                                                                                                                                                     |
| 400                      | TED000022            | Bad Request                                         | Ted not found for the given IF Control Number                                                                                                                                                                            | Ted não encontrada para o número de controle da IF fornecida                                                                                                                                                          |
| 422                      | TED000023            | Bad Request                                         | Unable to process message due to the current status (\{current_status\}). Messages of the type \{bacen_message_code\} are allowed to happen on teds with status \{allowed_status\}. [ted_type = \{type\}, key = \{key\}] | Não foi possível processar a mensagem devido ao status atual (\{current_status\}). Mensagens do tipo \{bacen_message_code\} podem ocorrer em teds com status \{allowed_status\}. [Ted_type = \{type\}, key = \{key\}] |
| 403                      | TED000024            | Unauthorized                                        | This agent can not add rules.                                                                                                                                                                                            | Este agente não pode adicionar regras.                                                                                                                                                                                |
| 403                      | TED000025            | Unauthorized                                        | This agent can not add rules types.                                                                                                                                                                                      | Este agente não pode adicionar tipos de regras.                                                                                                                                                                       |
| 400                      | TED000026            | Bad Request                                         | \{ted_rule_type_enum\} was not found among registered rules.                                                                                                                                                             | \{ted_rule_type_enum\} não encontrada dentro das regras registradas.                                                                                                                                                  |
| 400                      | TED000027            | Bad Request                                         | Mismatch between rule data and rule schema: \{message\}                                                                                                                                                                  | Incompatibilidade entre os dados da regra e o esquema de regra: \{message\}                                                                                                                                           |
| 400                      | TED000028            | Bad Request                                         | Both source_account_key and source_document_number are not null. At least one of them should be null.                                                                                                                    | Tanto a source_account_key quanto o source_document_number estão preenchidos. Pelo menos um dos dois deve ser nulo.                                                                                                   |
| 422                      | TED000029            | Unprocessable Entity                                | \{object_name\} has invalid type \{object_type\}                                                                                                                                                                         | \{object_name\} possui tipo inválido \{object_type\}                                                                                                                                                                  |
| 400                      | TED000030            | Empty ted list received                             | A list of teds must be provided                                                                                                                                                                                          | Uma lista de transferências ted deve ser fornecida                                                                                                                                                                    |
| 400                      | TED000031            | Bad Request                                         | ISPB number \{ispb\} does not exist or is inactive                                                                                                                                                                       | ISPB \{ispb\} não existe ou está inativo                                                                                                                                                                              |
| 404                      | TED000032            | Not Found                                           | Account limit request with key \{account_limit_request_key\} was not found.                                                                                                                                              | Pedido de limite com chave \{account_limit_request_key\} não encontrado.                                                                                                                                              |
| 400                      | TED000033            | Bad Request                                         | An account limit request with status \{status\} does not allow this operation.                                                                                                                                           | Pedido de limite com chave \{status\} não permite essa operação                                                                                                                                                       |
| 400                      | TED000034            | Bad Request                                         | Account limit request \{account_limit_request_key\} is not approved then cannot be executed.                                                                                                                             | Pedido de limite \{account_limit_request_key\} não foi aprovado portanto não pode ser executado                                                                                                                       |
| 406                      | TED000035            | Not Acceptable                                      | It is not possible to request changes in limits for different accounts.                                                                                                                                                  | Não é possível realziar pedidos de mudanças de limites para contas diferentes.                                                                                                                                        |
| 400                      | TED000036            | Bad Request                                         | Transfer rejected by the system                                                                                                                                                                                          | A transferência foi recusada pelo sistema                                                                                                                                                                             |
| 400                      | TED000037            | Bad Request                                         | The account \{account_key\} already has a pending request for limit type \{account_limit_type\}.                                                                                                                         | A conta \{account_key\} ja possui um pedido do tipo \{account_limit_type\} pendente.                                                                                                                                  |
| 409                      | TED000038            | Conflict                                            | Ted \{outgoing_ted_key\} is not pending analysis therefore cannot be updated.                                                                                                                                            | Ted \{outgoing_ted_key\} não está pendente de análise portanto não pode ser atualizada.                                                                                                                               |
| 400                      | TED000039            | Bad Request                                         | Your centralized billing account is closed, please contact support.                                                                                                                                                      | Sua conta de tarifas centralizadas está fechada, favor entrar em contato com o suporte.                                                                                                                               |
| 400                      | TED000040            | Bad Request                                         | Your centralized billing account has insufficient funds, please contact support.                                                                                                                                         | Sua conta de tarifas centralizadas não possui saldo sufciente, favor entrar em contato com o suporte.                                                                                                                 |
| 400                      | TED000041            | Bad Request                                         | Pending fraud analysis return                                                                                                                                                                                            | Retorno pendente da análise de fraude                                                                                                                                                                                 |
| 400                      | TED000042            | Ted Direction Invalid                               | Ted Direction must be either outgoing or incoming                                                                                                                                                                        | Ted Direction deve ser outgoing ou incoming                                                                                                                                                                           |
| 400                      | TED000043            | Ted Key needed                                      | A ted_key must be provided                                                                                                                                                                                               | Uma ted_key deve ser fornecida                                                                                                                                                                                        |
| 400                      | TED000044            | Invalid Timestamp Format sent                       | Given parameter is not in the correct format \{timestamp_format\}                                                                                                                                                        | Parametro enviado não está no formato correto \{timestamp_format\}                                                                                                                                                    |
| 400                      | TED000045            | Search Params Error                                 | Invalid integer value for page or size querystring parameters                                                                                                                                                            | Valor inválido para parâmetros de página ou tamanho de página                                                                                                                                                         |
| 400                      | TED000046            | Invalid uuid v4 string sent                         | \{key\} was not accepted for not being a valid uuid v4 string                                                                                                                                                            | \{key\} não foi aceito por não ser uma palavra uuid v4 válida                                                                                                                                                         |
| 404                      | TED000047            | Not found                                           | Incoming Ted with key \{incoming_ted_key\} was not found.                                                                                                                                                                | Ted de entrada com chave \{incoming_ted_key\} não foi encontrado.                                                                                                                                                     |
| 400                      | TED000048            | Bad Request                                         | The status of the incoming ted is not approved.                                                                                                                                                                          | O status do ted de entrada não é aprovado.                                                                                                                                                                            |
| 400                      | TED000049            | Bad Request                                         | Invalid message type: \{message_type\}                                                                                                                                                                                   | Tipo de mensagem inválido: \{message_type\}                                                                                                                                                                           |
| 400                      | TED000050            | Bad Request                                         | Refusal reason \{refusal_reason_enumerator\} not found                                                                                                                                                                   | Motivo de recusa \{refusal_reason_enumerator\} não encontrado                                                                                                                                                         |
| 400                      | TED000051            | Barcode payment Not implemented for this endpoint   | Barcode payment Not implemented for this endpoint                                                                                                                                                                        | Pagamento de código de barras não implementado para este endpoint                                                                                                                                                     |
| 400                      | TED000052            | Invalid Source Subtype                              | Source Subtype \{source_subtype\} is invalid                                                                                                                                                                             | Source Subtype \{source_subtype\} é inválido                                                                                                                                                                          |
| 400                      | TED000053            | Invalid Target Account Type                         | Target Account Type \{account_type\} is invalid                                                                                                                                                                          | Tipo de conta destino \{account_type\} é inválido                                                                                                                                                                     |
| 400                      | TED000054            | Invalid Transaction Amount                          | Transaction Amount \{transaction_amount\} is invalid                                                                                                                                                                     | Valor de transação \{transaction_amount\} é inválido                                                                                                                                                                  |
| 400                      | TED000055            | Invalid Observation                                 | Observation sent is invalid                                                                                                                                                                                              | Observação enviada é inválida                                                                                                                                                                                         |
| 400                      | TED000057            | Invalid Document Number                             | Given \{document_number\} document number is invalid                                                                                                                                                                     | CPF/CNPJ \{document_number\} fornecido não é valido                                                                                                                                                                   |
| 400                      | TED000058            | Bad Request                                         | Insufficient account balance for transfer and fee amount                                                                                                                                                                 | Saldo de conta insuficiente para a transação e a taxa                                                                                                                                                                 |
| 400                      | TED000059            | Bad Request                                         | Unmapped transaction error received                                                                                                                                                                                      | Erro transacional não mapeado recebido                                                                                                                                                                                |
| 400                      | TED000060            | Bad Request                                         | Billing Account is closed                                                                                                                                                                                                | Conta centralizadora de pagamentos de tarifa fechada                                                                                                                                                                  |
| 400                      | TED000061            | Bad Request                                         | Billing Account without necessary funds                                                                                                                                                                                  | Conta centralizadora de pagamentos sem saldo necessário                                                                                                                                                               |
| 400                      | TED000062            | Bad Request                                         | Error while performing outgoing ted refusal transfer                                                                                                                                                                     | Erro ao realizar transferência ted de rejeição                                                                                                                                                                        |
| 400                      | TED000063            | Internal Error                                      | Error while sending outgoing ted str. Ted_key: \{outgoing_ted_key\}                                                                                                                                                      | Erro ao enviar str de ted de saída. Ted_key: \{outgoing_ted_key\}                                                                                                                                                     |
| 409                      | TED000064            | Bad Request                                         | request_control_key \{request_control_key\} already in use                                                                                                                                                               | request_control_key \{request_control_key\} já utilizada                                                                                                                                                              |
| 400                      | TED000065            | Bad Request                                         | It has been identified by request_control_key that this request is already being processed                                                                                                                               | Foi identificado por request_control_key que está requisição está sendo processada                                                                                                                                    |
| 400                      | TED000067            | Error loading fees                                  | Failed to load fees for account \{account_key\}                                                                                                                                                                          | Falha ao carregar tarifas para conta \{account_key\}                                                                                                                                                                  |
| 400                      | TED000068            | Bad Request                                         | Transfer rejected by th system                                                                                                                                                                                           | A transferência foi recusada pelo sistema                                                                                                                                                                             |
| 404                      | TED000069            | Account Not Found                                   | Account was not found for given parameters                                                                                                                                                                               | Conta não encontrada para os parâmetros informados                                                                                                                                                                    |
| 400                      | TED000070            | Bad Request                                         | Insufficient account balance fee amount in billing account                                                                                                                                                               | Saldo de conta centralizadora insuficiente para taxa                                                                                                                                                                  |
| 400                      | TED000071            | Bad Request                                         | Transaction cannot be made due to already blocked balance                                                                                                                                                                | Transação não pode ser feita pois saldo em conta bloqueado                                                                                                                                                            |
| 400                      | TED000072            | Invalid target ispb                                 | Target ispb must be external                                                                                                                                                                                             | ISPB de destino deve ser externo                                                                                                                                                                                      |
| 404                      | TED000073            | Person Not Found                                    | Person with key \{person_key\} not found                                                                                                                                                                                 | Pessoa com chave \{person_key\} não encontrada                                                                                                                                                                        |
| 400                      | TED000074            | Invalid caas_client_key                             | There caas_client_key is not valid                                                                                                                                                                                       | A caas_client_key enviada não é válida                                                                                                                                                                                |
| 400                      | TED000075            | Invalid Requester Configuration Info                | The configuration \{configuration\} format sent is not valid                                                                                                                                                             | O formato enviado da configuração \{configuration\} não é válido                                                                                                                                                      |
| 404                      | TED000076            | Requester Configuration not found                   | There is no Requester Configuration attributed to requester_key given                                                                                                                                                    | Não há Requester Configuration para a requester_key enviada                                                                                                                                                           |
| 400                      | TED000077            | Bad Request                                         | Requester Configuration already exists for \{requester_key\}                                                                                                                                                             | Requester Configuration já existe para o \{requester_key\}                                                                                                                                                            |
| 403                      | TED000078            | Requester not allowed to access this endpoint       | Requester has no permission to perform ted transfers on this endpoint                                                                                                                                                    | Requester não possui permissão de realizar transações ted através deste endpoint                                                                                                                                      |
| 403                      | TED000079            | No approver permission                              | Given document number does not belong to an approver for this account                                                                                                                                                    | Número de documento enviado não pertence a um aprovador da conta                                                                                                                                                      |
| 400                      | TED000080            | tfa_info is required                                | Client must send object tfa_info                                                                                                                                                                                         | Cliente deve enviar objeto tfa_info                                                                                                                                                                                   |
| 400                      | TED000081            | Error occurred while sending token                  | An unexpected error occurred while sending token                                                                                                                                                                         | Um erro inexperado ocorreu ao tentar enviar token                                                                                                                                                                     |
| 400                      | TED000082            | Number of token validation attempts exceeded        | The maximum number of failed token validation attempts has been reached                                                                                                                                                  | Número máximo de tentativas de validação de token atingida                                                                                                                                                            |
| 400                      | TED000083            | Token Expired                                       | Token has expired. Resend token or recreate transfer                                                                                                                                                                     | Token expirado. Reenvie token ou recrie a transferência                                                                                                                                                               |
| 400                      | TED000084            | Incorrect Token                                     | Token sent does not match expected                                                                                                                                                                                       | Token enviado não condiz com, o esperado                                                                                                                                                                              |
| 400                      | TED000085            | Error Validating Token                              | An error occurred while validating token and it is being investigated                                                                                                                                                    | Um erro ocorreu ao validar token e está sendo investigado                                                                                                                                                             |
| 400                      | TED000086            | Invalid Status                                      | Ted not in pending_2fa_approval status                                                                                                                                                                                   | Ted não está pendente de aprovação por autenticação de dois fatores                                                                                                                                                   |
| 400                      | TED000087            | Error Sending Token                                 | An error occurred while resending token and its being investigated                                                                                                                                                       | Um erro ocorreu ao reenviar token e está sendo investigado                                                                                                                                                            |
| 403                      | TED000088            | Bad Request                                         | Could not complete the transaction and the transaction was rejected. Try again                                                                                                                                           | Não foi possível concluir a transação e a transferência foi rejeitada. Tente novamente                                                                                                                                |
| 400                      | TED000089            | Invalid Schedule Date                               | Schedule date must be after current date for UTC-3                                                                                                                                                                       | Data de agendamento deve ser após a data atual em UTC-3                                                                                                                                                               |
| 400                      | TED000090            | Invalid Schedule Date                               | Schedule date must be a workday                                                                                                                                                                                          | Data de agendamento deve ser um dia útil                                                                                                                                                                              |
| 400                      | TED000091            | Target Account and Source Account must be different | Target Account must not be the same as Source Account                                                                                                                                                                    | A conta de destino não pode ser a mesma da conta de origem                                                                                                                                                            |
| 400                      | TED000092            | Invalid reason code                                 | Invalid reason code                                                                                                                                                                                                      | Motivo inválido                                                                                                                                                                                                       |
| 404                      | TED000093            | TedSchedule not Found                               | TedSchedule was not found                                                                                                                                                                                                | TedSchedule não encontrada                                                                                                                                                                                            |
| 400                      | TED000094            | Bad Request                                         | Ted Schedule cannot be cancelled in current status                                                                                                                                                                       | Agendamento Ted não pode ser cancelado no status atual                                                                                                                                                                |
| 400                      | TED000095            | Bad Request                                         | The given Ted Schedule is tied to a batch. It cannot be individually cancelled                                                                                                                                           | O agendamento Ted enviado está ligado a um lote. Ela não pode ser individualmente cancelada                                                                                                                           |
| 400                      | TED000096            | Bad Request                                         | Action cannot be taken place as there is currently a pending transfer in progress                                                                                                                                        | A ação não pôde ser completada como há uma transferência pendente                                                                                                                                                     |
| 400                      | TED000098            | Bad Request                                         | The outgoing ted was returned                                                                                                                                                                                            | A transferência ted de saída foi devolvida                                                                                                                                                                            |
| 400                      | TED000099            | Invalid Status                                      | Ted Schedule not in pending_2fa_approval status                                                                                                                                                                          | Agendamento Ted não está pendente de aprovação por autenticação de dois fatores                                                                                                                                       |
| 400                      | TED000100            | Invalid Schedule Date                               | Schedule must be approved before the scheduled date                                                                                                                                                                      | Agendamento deve ser aprovado em data anterior à programada para transação                                                                                                                                            |
| 404                      | TED000101            | TedBatch not Found                                  | TedBatch was not found                                                                                                                                                                                                   | TedBatch não encontrada                                                                                                                                                                                               |
| 400                      | TED000102            | Invalid Status                                      | Ted Batch not in pending_2fa_approval status                                                                                                                                                                             | Lote de Ted não está pendente de aprovação por autenticação de dois fatores                                                                                                                                           |
| 404                      | TED000103            | ScheduleBatch not Found                             | Ted Schedule Batch was not found                                                                                                                                                                                         | Agendamento de Ted em lote não encontrado                                                                                                                                                                             |
| 400                      | TED000104            | Invalid Status                                      | Schedule Batch cannot be cancelled in current status                                                                                                                                                                     | Lote de agendamento não pode ser cancelado no status atual                                                                                                                                                            |
| 400                      | TED000105            | Schedule Batch could not be cancelled               | ScheduleBatch could not be cancelled due to current date being equal or after earliest schedule date. Cancel schedules one by one                                                                                        | ScheduleBatch não pode ser cancelada devido a data atual ser superior ou igual à menor schedule_date. Cancele agendamentos individualmente                                                                            |
| 400                      | TED000106            | Invalid Status                                      | ScheduleBatch not in pending_2fa_approval status                                                                                                                                                                         | Lote Agendamentos de Ted não está pendente de aprovação por autenticação de dois fatores                                                                                                                              |
| 400                      | TED000107            | Schedule Batch could not be approved                | ScheduleBatch could not be approved due to current date being equal or after earliest schedule date. Rejecting batch                                                                                                     | ScheduleBatch não pode ser aprovada devido a data atual ser superior ou igual à menor schedule_date. Rejeitando lote                                                                                                  |
| 400                      | TED000108            | Number of transfer attempts exceeded                | The maximum number of failed transfer attempts has been reached                                                                                                                                                          | Número máximo de tentativas de transferência foi atingida                                                                                                                                                             |

---

# Listar TEDs

URL: /documentation/baas/ted/listar_teds

## Request

ENDPOINT /account/ ACCOUNT_KEY /teds
MÉTODO GET

## Path Params

| Campo           | Tipo   | Descrição                                | Caracteres |
|-----------------|--------|------------------------------------------|------------|
| `account_key` * | uuidv4 | Chave única de identificação da conta QI | 36         |

## Query Params

| Campo                 | Tipo       | Descrição                                                                                                  | Caracteres                                                                  |
|-----------------------|------------|------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| `ted_direction`       | enumerator | Indicador do sentido da transação (entrada ou saída). Caso não seja enviado, **outgoing** será considerado | [Enumeradores ted_transfer_direction](#enumeradores-ted_transfer_direction) |
| `request_control_key` | uuidv4     | Chave única de identificação da request utilizada pelo cliente.                                            | 36                                                                          |
| `date_from`           | string     | Data inicial. Formato "YYYY-MM-DD"                                                                         |                                                                             |
| `date_to`             | string     | Data final. Formato "YYYY-MM-DD"                                                                           |                                                                             |
| `page`                | integer    | Número da página requisitada. 1 por padrão                                                                 |                                                                             |
| `page_size`           | integer    | Tamanho da página requisitada na consulta. 30 por padrão e valor máximo                                    | Valor máximo de 30                                                          |

## Enumeradores ted_transfer_direction

| Enumerador   | Descrição                    |
|--------------|------------------------------|
| **incoming** | Transferência TED de entrada |
| **outgoing** | Transferência TED de saída   |

## Response

STATUS 200

Response Body

```json
{
  "data": [
    {
      "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
      "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
      "created_at": "2021-10-22T20:30:23.459Z",
      "ted_status": "sent",
      "transaction_amount": 126.97,
      "fee_amount": 0.0,
      "target_account": {
        "account_branch": "0001",
        "account_digit": "6",
        "account_number": "78340",
        "ispb": "12345678",
        "owner_document_number": "32402502000135",
        "owner_name": "QI Tech"
      },
      "refusal_reason": {}
    }
  ],
  "pagination": {
    "current_page": 1,
    "rows_per_page": 30
  }
}

```

---

# Realizar TED

URL: /documentation/baas/ted/realizar_transferencia

O recebimento de uma transação TED não é instantânea no sistema financeiro nacional. Ao realizar uma transação TED no
sistema QI uma resposta imediata será retornada informando erro, rejeição ou aceite da transferencia. Mesmo que uma
transferência tenha sido colocada em `sent`, a Instituição Financeira recebedora pode recusar a entrada de
recurso e
realizar a devolução do valor. Neste caso um novo webhook com status de `rejected` será enviado e o motivo da rejeição
retornado no campo `refusal_reason`.

Débitos na conta fonte da transação serão realizados imediatamente. Isso não significa que o valor foi creditado na
conta destino devido aos princípios de transações TED descritos acima. Caso ocorra a rejeição da transação enviada, o
valor da transação será creditado novamente à conta fonte.

## Request

ENDPOINT /account/ ACCOUNT_KEY /ted
MÉTODO POST

Request Body

```json
{
  "request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
  "target_account": {
    "account_branch": "0001",
    "account_number": "92796",
    "account_digit": "1",
    "owner_document_number": "23599885000192",
    "owner_name": "Titular da Conta",
    "ispb": "12345678",
    "account_type": "checking_account"
  },
  "transaction_amount": 8.86
}
```

## Body Params

| Campo                   | Tipo   | Descrição                                                                          | Caracteres                                          |
|-------------------------|--------|------------------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | string | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36                                                  |
| `target_account` *      | object | Conta de destino                                                                   | **[Objeto target_account](#objeto-target_account)** | 
| `transaction_amount` *  | float  | Valor da transferência                                                             | 10                                                  |

## Objeto target_account

| Campo                     | Tipo   | Descrição                                           | Caracteres                                                |
|---------------------------|--------|-----------------------------------------------------|-----------------------------------------------------------|
| `account_branch` *        | string | Agência.                                            | 4                                                         |
| `account_digit` *         | string | Dígito da conta                                     | 1                                                         |
| `account_number` *        | string | Número da conta.                                    | 20                                                        |
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta.   | 14                                                        |
| `owner_name` *            | string | Nome do titular da conta.                           | 50                                                        |
| `account_type`*           | string | Tipo da conta.                                      | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string | Base no CNPJ da instituição financeira (8 dígitos). | 8                                                         |

## Enumerador account_type

| Enumerador             | Tradução              |
|------------------------|-----------------------|
| **checking_account**   | conta corrente        |
| **deposit_account**    | conta depósito        |
| **guaranteed_account** | conta de garantia     |
| **investment_account** | conta de investimento |
| **payment_account**    | conta de pagamento    |
| **saving_account**     | conta poupança        |

## Response

STATUS 201

Response Body

```json
{
  "request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
  "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "created_at": "2021-10-22T20:30:23.459Z",
  "ted_status": "sent",
  "transaction_amount": 126.97,
  "fee_amount": 0.0,
  "transaction_key": "46804f32-101e-4702-8fbc-c2dbc4c2caec"
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`          | Descrição (eng)<br/>`description`                                                                                       | Descrição (ptbr)<br/>`translation`                                                                                     |
|--------------------------|----------------------|-----------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                 | Schema Error                                                                                                            | Erro de Schema                                                                                                         |
| 400                      | TED000066            | InvalidUuid                 | request_control_key was not accepted for not being a valid uuid v4 string                                               | request_control_key não foi aceito por não ser uma palavra uuid v4 válida                                              |
| 400                      | TED000011            | InvalidUuid                 | Wrong day/time for TED                                                                                                  | Dia/hora incorretos para a TED                                                                                         |
| 400                      | TED000055            | Invalid Observation         | Observation sent is invalid                                                                                             | Observação enviada é inválida                                                                                          |
| 400                      | TED000054            | Invalid Transaction Amount  | Transaction amount of \{transaction_amount\} is not valid. It must be a positive value with at maximum 2 decimal places | O valor de transação \{transaction_amount\} não é válido. Deve ser um valor positivo com no máximo duas casas decimais |
| 400                      | TED000012            | Bad Request                 | The target's length of the account + account_digit cannot be larger than 21                                             | O número de digitos na conta de destino + digito não pode ser maior que 21                                             |
| 400                      | TED000053            | Invalid Target Account Type | Target Account Type \{account_type\} is invalid                                                                         | Tipo de conta destino \{account_type\} é inválido                                                                      |
| 400                      | TED000031            | Bad Request                 | ISPB number \{ispb\} does not exist or is inactive                                                                      | ISPB \{ispb\} não existe ou está inativo                                                                               |
| 400                      | TED000065            | Bad Request                 | It has been identified by request_control_key that this request is already being processed                              | Foi identificado por request_control_key que está requisição está sendo processada                                     |
| 403                      | TED000071            | Invalid target account      | Invalid target account                                                                                                  | Conta destino inválida                                                                                                 |
| 400                      | TED000058            | Bad Request                 | Insufficient account balance for transfer and fee amount                                                                | Saldo de conta insuficiente para a transação e a taxa                                                                  |
| 400                      | TED000070            | Bad Request                 | Insufficient account balance fee amount in billing account                                                              | Saldo de conta centralizadora insuficiente para taxa                                                                   |
| 400                      | TED000071            | Bad Request                 | Transaction cannot be made due to already blocked balance                                                               | Transação não pode ser feita pois saldo em conta bloqueado                                                             |
| 400                      | TED000068            | Bad Request                 | Transfer rejected by the system                                                                                         | transferêancia foi recusada pelo sistema                                                                               |
| 404                      | TED000013            | Bad Request                 | Unable to find source_account_key's account                                                                             | Não foi possível encontrar a conta com source_account_key fornecido                                                    |
| 400                      | TED000015            | Bad Request                 | Account blocked or closed can not perform this action                                                                   | A conta bloqueada ou fechada não pode executar esta ação                                                               |
| 400                      | TED000016            | Bad Request                 | Hub account can not perform this action                                                                                 | A conta hub não pode executar esta ação                                                                                |
| 403                      | TED000017            | Unauthorized                | Provided account does not have approval credential for the given person                                                 | A conta fornecida não possui credencial de aprovação para a pessoa especificada                                        |
| 403                      | TED000018            | Unauthorized                | Provided account not owned by SELECTED_AGENT                                                                            | Conta fornecida não pertencente ao SELECTED_AGENT                                                                      |
| 400                      | TED000060            | Bad Request                 | Billing Account is closed                                                                                               | Conta centralizadora de pagamentos de tarifa fechada                                                                   |
| 400                      | TED000061            | Bad Request                 | Billing Account without necessary funds                                                                                 | Conta centralizadora de pagamentos sem saldo necessário                                                                |
| 409                      | TED000064            | Bad Request                 | request_control_key \{request_control_key\} already in use                                                              | request_control_key \{request_control_key\} já utilizada                                                               |

---

# Aprovar Agendamento de Transação Ted com Autenticação de Dois Fatores

URL: /documentation/baas/ted/schedule_2fa/aprovacao_de_agendamento_2fa

## Request

ENDPOINT /account/ ACCOUNT_KEY /ted_schedule/ SCHEDULE_KEY /validate_token
MÉTODO PUT

### Path Params

| Campo          | Tipo   | Descrição                                    | Caracteres |
|----------------|--------|----------------------------------------------|------------|
| `account_key`  | uuidv4 | Chave única de identificação da conta.       | 36         |
| `schedule_key` | uuidv4 | Chave única de identificação do agendamento. | 36         |

## Autenticação via Email e SMS

Request Body

```json
{
  "token": "329123"
}
```

## Autenticação via Dispositivo

Para aprovar e finalizar a autenticação via dispositivo, a requisição deve ser enviada com um payload vazio. A validação ocorre internamente, sem necessidade de informações adicionais no corpo da requisição. É importante destacar que este endpoint só deve ser utilizado após a [solicitação de agendamento](./solicitacao_de_agendamento_2fa.md) ter sido iniciada.

Request Body

```json
{

}
```

## Body Params

| Campo   | Tipo   | Descrição                                                                                                                              | Caracteres |
|---------|--------|----------------------------------------------------------------------------------------------------------------------------------------|------------|
| `token` | string | Código de autenticação enviado ao aprovador de movimentações da conta **obrigatório para TFA via SMS ou e-mail**                       | 6          |

## Response

STATUS 201

Response Body: Agendamento Aprovado

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "schedule_key": "f64b3fa7-d09d-4927-ad4f-b966df9fb153",
  "schedule_status": "scheduled",
  "schedule_date": "2024-12-31"
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                           | Descrição (eng)<br/>`description`                                                 | Descrição (ptbr)<br/>`translation`                                              |
|--------------------------|----------------------|----------------------------------------------|-----------------------------------------------------------------------------------|---------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                  | schema error description                                                          | Schema Inválido                                                                 |
| 404                      | TED000009            | Not Found                                    | Account not found for the given key: \{account_key\}                              | Conta não encontrada para a chave fornecida: \{account_key\}                    |
| 403                      | TED000018            | Unauthorized                                 | Provided account not owned by SELECTED_AGENT                                      | Conta fornecida não pertencente ao SELECTED_AGENT                               |
| 400                      | TED000082            | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached           | Número máximo de tentativas de validação de token atingida                      |
| 400                      | TED000083            | Token Expired                                | Token has expired. Resend token or recreate transfer                              | Token expirado. Reenvie token ou recrie a transferência                         |
| 400                      | TED000084            | Incorrect Token                              | Token sent does not match expected                                                | Token enviado não condiz com, o esperado                                        |
| 400                      | TED000085            | Error Validating Token                       | An error occurred while validating token and it is being investigated             | Um erro ocorreu ao validar token e está sendo investigado                       |
| 400                      | TED000086            | Invalid Status                               | Ted not in pending_2fa_approval status                                            | Ted não está pendente de aprovação por autenticação de dois fatores             |
| 404                      | TED000093            | TedSchedule not Found                        | TedSchedule was not found                                                         | TedSchedule não encontrada                                                      |
| 400                      | TED000096            | Bad Request                                  | Action cannot be taken place as there is currently a pending transfer in progress | A ação não pôde ser completada como há uma transferência pendente               |
| 400                      | TED000099            | Invalid Status                               | Ted Schedule not in pending_2fa_approval status                                   | Agendamento Ted não está pendente de aprovação por autenticação de dois fatores |
| 400                      | TED000100            | Invalid Schedule Date                        | Schedule must be approved before the scheduled date                               | Agendamento deve ser aprovado em data anterior à programada para transação      |

| 400                      | TED000110            | Token Required                               | A token is required for SMS or email validation.                                                         | Um token é necessário para validação via SMS ou email.                                                     |

---

# Introdução a Autenticação de Dois Fatores

URL: /documentation/baas/ted/schedule_2fa/introducao_a_agendamento_2fa

Neste tipo de agendamento, é necessário a confirmação da programação de pagamento via token enviado à pessoa com poderes
de aprovação de movimentação na conta credora.

A solicitação de agendamento Ted por parceiros integradores configurados para a utilização de autenticação de dois
fatores é realizada de forma similar ao descrito
em [solicitar agendamento de_transação_ted](/documentation/baas/ted/schedule/solicitacao_de_agendamento). A diferença
ocorre na adição do objeto `tfa_info`, contento informações sobre o aprovador da transferência e a forma de contato, e o
status de uma solicitação bem sucedida que será sempre **pending_2fa_approval**.

O mesmo vale para agendamentos em lote Ted descrito em [solicitar agendamento de_transação_ted em lote](/documentation/baas/ted/schedule_batch/solicitacao_de_agendamento_em_lote).

## Fluxo para um agendamento Ted com autorização

O agendamento Ted bem sucedido seguirá o seguinte fluxo de processos:
Realização da [solicitação de transação Ted](/documentation/baas/ted/schedule/solicitacao_de_agendamento_2fa) e recebimento de resposta de forma síncrona com status de **pending_2fa_approval** e valor da `schedule_key`.
O aprovador indicado receberá um `token` de 6 dígitos compostos por algarismos.
O requisitante realiza a [confirmação de transação ted](/documentation/baas/ted/schedule/aprovacao_de_agendamento_2fa) com a `schedule_key` e o `token`.
O agendamento será então atualizado para o status de **scheduled**.
## Observações
Cada agendamento possui um limite máximo de tentativas de validação do `token` de 5. Quando este limite é alcançado o agendamento será colocado em status de rejeitado (**rejected**) automaticamente.
Cada `token` possui duração máxima de 5 minutos.
Um agendamento pode ter seu `token` renovado e reenviado para o aprovador da transferência. Este processo reinica o tempo de 5 minutos e não reinicia o contador de tentativas inválidas. O `token` anterior torna-se inválido.
O evento de notificação para o envio de `token` ao aprovador é **baas.token_validation.ted.schedule.single**. É possível [personalizar](/documentation/notificacoes/template) a mensagem enviada.
As formas de envio (`contact_type`) de token implementadas são por **sms** e **email**.

---

# Solicitar Agendamento de Transação Ted com Autenticação de Dois Fatores

URL: /documentation/baas/ted/schedule_2fa/solicitacao_de_agendamento_2fa

## Request

ENDPOINT /account/ ACCOUNT_KEY /ted_schedule
MÉTODO POST

## Autenticação via Email e SMS

Request Body: Agendamento com TFA por SMS ou Email

```json
{
  "request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
  "target_account": {
    "account_branch": "0001",
    "account_number": "92796",
    "account_digit": "1",
    "owner_document_number": "23599885000192",
    "owner_name": "Titular da Conta",
    "ispb": "12345678",
    "account_type": "checking_account"
  },
  "transaction_amount": 8.86,
  "schedule_date": "2024-12-01",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```

## Autenticação via Dispositivo

Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`.

Request Body: Agendamento com TFA por Dispositivo

```json
{
  "request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
  "target_account": {
    "account_branch": "0001",
    "account_number": "92796",
    "account_digit": "1",
    "owner_document_number": "23599885000192",
    "owner_name": "Titular da Conta",
    "ispb": "12345678",
    "account_type": "checking_account"
  },
  "transaction_amount": 8.86,
  "schedule_date": "2024-12-01",
  "tfa_info": {
    "approver_document_number": "98765432100",
    "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
    "contact_type": "device"
  }
}
```

## Body Params

| Campo                   | Tipo   | Descrição                                                                          | Caracteres                                          |
|-------------------------|--------|------------------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | string | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36                                                  |
| `target_account` *      | object | Conta de destino                                                                   | **[Objeto target_account](#objeto-target_account)** | 
| `transaction_amount` *  | float  | Valor da transferência                                                             | 10                                                  |
| `schedule_date`*        | string | Data a ser realizada a transação.                                                  | 10                                                  |
| `tfa_info`*             | Object | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato.    | **[Objeto tfa_info](#objeto-tfa_info)**             |

## Objeto tfa_info

| Campo                       | Tipo   | Descrição                                                                                                                        | Caracteres |
|-----------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------|------------|
| `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta.                                                                               | 11         |
| `session_id`                | string | Chave única de identificação da sessão do dispositivo no formato UUID v4 (obrigatório para TFA via dispositivo).                 | 36         |
| `contact_type`*             | string | Forma de contato com a pessoa aprovadora da conta, podendo ser **sms**, **email** ou **device**                                  |            |

## Objeto target_account

| Campo                     | Tipo   | Descrição                                           | Caracteres                                              |
|---------------------------|--------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string | Agência.                                            | 4                                                       |
| `account_digit` *         | string | Dígito da conta                                     | 1                                                       |
| `account_number` *        | string | Número da conta.                                    | 20                                                      |
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta.   | 14                                                      |
| `owner_name` *            | string | Nome do titular da conta.                           | 50                                                      |
| `account_type`*           | string | Tipo da conta.                                      | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string | Base no CNPJ da instituição financeira (8 dígitos). | 8                                                       |

## Enumerador account_type

| Enumerador             | Tradução              |
|------------------------|-----------------------|
| **checking_account**   | conta corrente        |
| **deposit_account**    | conta depósito        |
| **guaranteed_account** | conta de garantia     |
| **investment_account** | conta de investimento |
| **payment_account**    | conta de pagamento    |
| **saving_account**     | conta poupança        |

## Response

STATUS 202

Response Body: Agendamento Criado

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "schedule_key": "f64b3fa7-d09d-4927-ad4f-b966df9fb153",
  "schedule_status": "pending_2fa_approval",
  "schedule_date": "2024-12-31"
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                  | Descrição (eng)<br/>`description`                                                          | Descrição (ptbr)<br/>`translation`                                                 |
|--------------------------|----------------------|-----------------------------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                         | schema error description                                                                   | Schema Inválido                                                                    |
| 404                      | TED000006            | Target account Not Found                            | Target account was not found for given parameters                                          | Conta destino não encontrada para os parâmetros informados                         |
| 404                      | TED000009            | Not Found                                           | Account not found for the given key: \{account_key\}                                       | Conta não encontrada para a chave fornecida: \{account_key\}                       |
| 403                      | TED000014            | Invalid target account                              | Invalid target account                                                                     | Conta destino inválida                                                             |
| 400                      | TED000015            | Bad Request                                         | Account blocked or closed can not perform this action                                      | A conta bloqueada ou fechada não pode executar esta ação                           |
| 400                      | TED000016            | Bad Request                                         | Hub account can not perform this action                                                    | A conta hub não pode executar esta ação                                            |
| 403                      | TED000018            | Unauthorized                                        | Provided account not owned by SELECTED_AGENT                                               | Conta fornecida não pertencente ao SELECTED_AGENT                                  |
| 400                      | TED000031            | Bad Request                                         | ISPB number \{ispb\} does not exist or is inactive                                         | ISPB \{ispb\} não existe ou está inativo                                           |
| 400                      | TED000044            | Invalid Timestamp Format sent                       | Given parameter is not in the correct format \{timestamp_format\}                          | Parametro enviado não está no formato correto \{timestamp_format\}                 |
| 400                      | TED000046            | Invalid uuid v4 string sent                         | \{key\} was not accepted for not being a valid uuid v4 string                              | \{key\} não foi aceito por não ser uma palavra uuid v4 válida                      |
| 400                      | TED000054            | Invalid Transaction Amount                          | Transaction Amount \{transaction_amount\} is invalid                                       | Valor de transação \{transaction_amount\} é inválido                               |
| 400                      | TED000057            | Invalid Document Number                             | Given \{document_number\} document number is invalid                                       | CPF/CNPJ \{document_number\} fornecido não é valido                                |
| 409                      | TED000064            | Bad Request                                         | request_control_key \{request_control_key\} already in use                                 | request_control_key \{request_control_key\} já utilizada                           |
| 400                      | TED000065            | Bad Request                                         | It has been identified by request_control_key that this request is already being processed | Foi identificado por request_control_key que está requisição está sendo processada |
| 403                      | TED000079            | No approver permission                              | Given document number does not belong to an approver for this account                      | Número de documento enviado não pertence a um aprovador da conta                   |
| 400                      | TED000080            | tfa_info is required                                | Client must send object tfa_info                                                           | Cliente deve enviar objeto tfa_info                                                |
| 400                      | TED000081            | Error occurred while sending token                  | An unexpected error occurred while sending token                                           | Um erro inexperado ocorreu ao tentar enviar token                                  |
| 400                      | TED000089            | Invalid Schedule Date                               | Schedule date must be after current date for UTC-3                                         | Data de agendamento deve ser após a data atual em UTC-3                            |
| 400                      | TED000090            | Invalid Schedule Date                               | Schedule date must be a workday                                                            | Data de agendamento deve ser um dia útil                                           |
| 400                      | TED000091            | Target Account and Source Account must be different | Target Account must not be the same as Source Account                                      | A conta de destino não pode ser a mesma da conta de origem                         |

---

# Solicitar reenvio de token para um agendamento

URL: /documentation/baas/ted/schedule_2fa/solicitacao_de_reenvio_de_token_para_agendamento_2fa

Um novo token será gerado e enviado para o aprovador do agendamento ted. Caso o número limite de tentativas de validação
do token tenha sido excedida, não será permitido o reenvio.

## Request

ENDPOINT /account/ ACCOUNT_KEY /ted_schedule/ SCHEDULE_KEY /resend_token
MÉTODO PATCH

### Path Params

| Campo          | Tipo   | Descrição                                    | Caracteres |
|----------------|--------|----------------------------------------------|------------|
| `account_key`  | uuidv4 | Chave única de identificação da conta.       | 36         |
| `schedule_key` | uuidv4 | Chave única de identificação do agendamento. | 36         |

## Body Params

| Campo          | Tipo       | Descrição                               | Caracteres                                              |
|----------------|------------|-----------------------------------------|---------------------------------------------------------|
| `contact_type` | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** |

:::info Informação
Caso não seja enviado um `contact_type`, o token será enviado da forma solicitada originalmente.
:::

### Enumerador contact_type

| Enumerador | Descrição                                         |
|------------|---------------------------------------------------|
| **sms**    | Envio por Mensagem de Texto para telefone celular |
| **email**  | Envio por correio eletrônico                      |

## Response

STATUS 202

Response Body: Transação Solicitada

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "schedule_key": "f64b3fa7-d09d-4927-ad4f-b966df9fb153",
  "schedule_status": "pending_2fa_approval",
  "schedule_date": "2024-12-31"
}
```

STATUS 4xx

Response Body: Transferência Rejeitada

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                           | Descrição (eng)<br/>`description`                                                 | Descrição (ptbr)<br/>`translation`                                              |
|--------------------------|----------------------|----------------------------------------------|-----------------------------------------------------------------------------------|---------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                  | schema error description                                                          | Schema Inválido                                                                 |
| 404                      | TED000009            | Not Found                                    | Account not found for the given key: \{account_key\}                              | Conta não encontrada para a chave fornecida: \{account_key\}                    |
| 403                      | TED000018            | Unauthorized                                 | Provided account not owned by SELECTED_AGENT                                      | Conta fornecida não pertencente ao SELECTED_AGENT                               |
| 400                      | TED000082            | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached           | Número máximo de tentativas de validação de token atingida                      |
| 400                      | TED000086            | Invalid Status                               | Ted not in pending_2fa_approval status                                            | Ted não está pendente de aprovação por autenticação de dois fatores             |
| 400                      | TED000087            | Error Sending Token                          | An error occurred while resending token and its being investigated                | Um erro ocorreu ao reenviar token e está sendo investigado                      |
| 404                      | TED000093            | TedSchedule not Found                        | TedSchedule was not found                                                         | TedSchedule não encontrada                                                      |
| 400                      | TED000096            | Bad Request                                  | Action cannot be taken place as there is currently a pending transfer in progress | A ação não pôde ser completada como há uma transferência pendente               |
| 400                      | TED000099            | Invalid Status                               | Ted Schedule not in pending_2fa_approval status                                   | Agendamento Ted não está pendente de aprovação por autenticação de dois fatores |
| 400                      | TED000100            | Invalid Schedule Date                        | Schedule must be approved before the scheduled date                               | Agendamento deve ser aprovado em data anterior à programada para transação      |

---

# Aprovar Agendamento de Transação Ted em Lote com Autenticação de Dois Fatores

URL: /documentation/baas/ted/schedule_batch_2fa/aprovacao_de_agendamento_em_lote_2fa

## Request

ENDPOINT /account/ ACCOUNT_KEY /ted_schedule_batch/ SCHEDULE_BATCH_KEY /validate_token
MÉTODO PUT

### Path Params

| Campo                | Tipo   | Descrição                                            | Caracteres |
|----------------------|--------|------------------------------------------------------|------------|
| `account_key`        | uuidv4 | Chave única de identificação da conta.               | 36         |
| `schedule_batch_key` | uuidv4 | Chave única de identificação do agendamento em lote. | 36         |

## Autenticação via Email e SMS

Request Body

```json
{
  "token": "329123"
}
```

## Autenticação via Dispositivo

Para aprovar e finalizar a autenticação via dispositivo, a requisição deve ser enviada com um payload vazio. A validação ocorre internamente, sem necessidade de informações adicionais no corpo da requisição. É importante destacar que este endpoint só deve ser utilizado após a [solicitação de agendamento em lote](./solicitacao_de_agendamento_em_lote_2fa.md) ter sido iniciada.

Request Body

```json
{

}
```

## Body Params

| Campo   | Tipo   | Descrição                                                                                                                              | Caracteres |
|---------|--------|----------------------------------------------------------------------------------------------------------------------------------------|------------|
| `token` | string | Código de autenticação enviado ao aprovador de movimentações da conta **obrigatório para TFA via SMS ou e-mail**                       | 6          |

## Response

STATUS 201

Response Body: Agendamento en Lote Aprovado

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "schedule_batch_key": "f64b3fa7-d09d-4927-ad4f-b966df9fb153",
  "schedule_batch_status": "approved",
  "created_at": "2023-03-13T19:00:28.440Z"
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                           | Descrição (eng)<br/>`description`                                                                                    | Descrição (ptbr)<br/>`translation`                                                                                   |
|--------------------------|----------------------|----------------------------------------------|----------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                  | schema error description                                                                                             | Schema Inválido                                                                                                      |
| 404                      | TED000009            | Not Found                                    | Account not found for the given key: \{account_key\}                                                                 | Conta não encontrada para a chave fornecida: \{account_key\}                                                         |
| 403                      | TED000018            | Unauthorized                                 | Provided account not owned by SELECTED_AGENT                                                                         | Conta fornecida não pertencente ao SELECTED_AGENT                                                                    |
| 400                      | TED000082            | Number of token validation attempts exceeded | The maximum number of failed token validation attempts has been reached                                              | Número máximo de tentativas de validação de token atingida                                                           |
| 400                      | TED000083            | Token Expired                                | Token has expired. Resend token or recreate transfer                                                                 | Token expirado. Reenvie token ou recrie a transferência                                                              |
| 400                      | TED000084            | Incorrect Token                              | Token sent does not match expected                                                                                   | Token enviado não condiz com, o esperado                                                                             |
| 400                      | TED000085            | Error Validating Token                       | An error occurred while validating token and it is being investigated                                                | Um erro ocorreu ao validar token e está sendo investigado                                                            |
| 400                      | TED000102            | Invalid Status                               | Ted Batch not in pending_2fa_approval status                                                                         | Lote de Ted não está pendente de aprovação por autenticação de dois fatores                                          |
| 404                      | TED000103            | ScheduleBatch not Found                      | Ted Schedule Batch was not found                                                                                     | Agendamento de Ted em lote não encontrado                                                                            |
| 400                      | TED000106            | Invalid Status                               | ScheduleBatch not in pending_2fa_approval status                                                                     | Lote Agendamentos de Ted não está pendente de aprovação por autenticação de dois fatores                             |
| 400                      | TED000107            | Schedule Batch could not be approved         | ScheduleBatch could not be approved due to current date being equal or after earliest schedule date. Rejecting batch | ScheduleBatch não pode ser aprovada devido a data atual ser superior ou igual à menor schedule_date. Rejeitando lote |
| 400                      | TED000110            | Token Required                               | A token is required for SMS or email validation.                                                         | Um token é necessário para validação via SMS ou email.                                                     |

---

# Solicitar Agendamento de Transação Ted em Lote

URL: /documentation/baas/ted/schedule_batch_2fa/solicitacao_de_agendamento_em_lote_2fa

A QI Tech oferece a possibilidade de realizar várias transações agendadas ted com uma única chamada. Caso na chamada
inicial seja retornado um http status 4xx, nenhum dos agendamentos será realizado.

Neste tipo de agendamento, é necessário a confirmação da programação de pagamento via token enviado à pessoa com poderes
de aprovação de movimentação na conta credora.

A solicitação de agendamento Ted em lote por parceiros integradores configurados para a utilização de autenticação de
dois fatores é realizada de forma similar ao descrito
em [solicitar agendamento de_transação_ted_em_lote](/documentation/baas/ted/schedule/solicitacao_de_agendamento_em_lote).
A diferença ocorre na adição do objeto `tfa_info`, contento informações sobre o aprovador da transferência e a forma de
contato, e o status de uma solicitação bem sucedida que será sempre **pending_2fa_approval**.

O evento de notificação para o envio de `token` ao aprovador é **baas.token_validation.ted.schedule.batch**. É
possível [personalizar](/documentation/notificacoes/template) a mensagem enviada.

## Request

ENDPOINT /account/ ACCOUNT_KEY /ted_schedule_batch
MÉTODO POST

## Autenticação via Email e SMS

Request Body: Agendamento em Lote com TFA por SMS ou Email

```json
{
  "request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
  "ted_schedules": [
    {
      "request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
      "target_account": {
        "account_branch": "0001",
        "account_number": "92796",
        "account_digit": "1",
        "owner_document_number": "23599885000192",
        "owner_name": "Titular da Conta",
        "ispb": "12345678",
        "account_type": "checking_account"
      },
      "transaction_amount": 8.86,
      "schedule_date": "2024-12-01"
    }
  ],
  "tfa_info": {
    "approver_document_number": "98765432100",
    "contact_type": "email"
  }
}
```

## Autenticação via Dispositivo

Além das formas já existentes de autenticação via **sms** e **email**, é possível autenticar a transação utilizando um dispositivo [previamente cadastrado](/documentation/baas/dispositivo/create/solicitacao_cadastro_dispositivo). Nesse caso, o `session_id` deve ser obtido na **Device Scan** e enviado no `tfa_info`.

Request Body: Agendamento em Lote com TFA por Dispositivo

```json
{
  "request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
  "ted_schedules": [
    {
      "request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
      "target_account": {
        "account_branch": "0001",
        "account_number": "92796",
        "account_digit": "1",
        "owner_document_number": "23599885000192",
        "owner_name": "Titular da Conta",
        "ispb": "12345678",
        "account_type": "checking_account"
      },
      "transaction_amount": 8.86,
      "schedule_date": "2024-12-01"
    }
  ],
  "tfa_info": {
    "approver_document_number": "98765432100",
    "session_id": "b2f18d3a-67c2-4a7f-98e5-1d3f5c6b8a72",
    "contact_type": "device"
  }
}
```

## Path Params

| Campo         | Tipo   | Descrição                              | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36         |

## Body Params

| Campo                   | Tipo   | Descrição                                                                          | Caracteres                                               |
|-------------------------|--------|------------------------------------------------------------------------------------|----------------------------------------------------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36                                                       | 
| `ted_schedules` *       | array  | Lista de objetos ted_schedule vinculados ao lote.                                  | lista de **[Objeto ted_schedule](#objeto-ted_schedule)** |
| `tfa_info`*             | Object | Objeto contendo o documento da pessoa aprovadora da conta e a forma de contato.    | **[Objeto tfa_info](#objeto-tfa_info)**                  |

## Objeto tfa_info

| Campo                       | Tipo   | Descrição                                                                                                                        | Caracteres |
|-----------------------------|--------|----------------------------------------------------------------------------------------------------------------------------------|------------|
| `approver_document_number`* | string | Número de documento da pessoa aprovadora da conta.                                                                               | 11         |
| `session_id`                | string | Chave única de identificação da sessão do dispositivo no formato UUID v4 (obrigatório para TFA via dispositivo).                 | 36         |
| `contact_type`*             | string | Forma de contato com a pessoa aprovadora da conta, podendo ser **sms**, **email** ou **device**                                  |            |

## Objeto ted_schedule

| Campo                   | Tipo   | Descrição                                                                          | Caracteres                                          |
|-------------------------|--------|------------------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | string | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36                                                  |
| `target_account` *      | object | Conta de destino                                                                   | **[Objeto target_account](#objeto-target_account)** | 
| `transaction_amount` *  | float  | Valor da transferência                                                             | 10                                                  |
| `schedule_date`*        | string | Data a ser realizada a transação.                                                  | 10                                                  |

## Objeto target_account

| Campo                     | Tipo   | Descrição                                           | Caracteres                                              |
|---------------------------|--------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string | Agência.                                            | 4                                                       |
| `account_digit` *         | string | Dígito da conta                                     | 1                                                       |
| `account_number` *        | string | Número da conta.                                    | 20                                                      |
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta.   | 14                                                      |
| `owner_name` *            | string | Nome do titular da conta.                           | 50                                                      |
| `account_type`*           | string | Tipo da conta.                                      | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string | Base no CNPJ da instituição financeira (8 dígitos). | 8                                                       |

## Enumerador account_type

| Enumerador             | Tradução              |
|------------------------|-----------------------|
| **checking_account**   | conta corrente        |
| **deposit_account**    | conta depósito        |
| **guaranteed_account** | conta de garantia     |
| **investment_account** | conta de investimento |
| **payment_account**    | conta de pagamento    |
| **saving_account**     | conta poupança        |

## Response

STATUS 202

Response Body: Agendamento em lote Requisitado

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "schedule_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "schedule_batch_status": "pending_2fa_approval",
  "created_at": "2021-10-22T20:30:23.459Z"
}
```

### Enumerador schedule_batch_status

| Enumerador               | Descrição                                                                  |
|--------------------------|----------------------------------------------------------------------------|
| **created**              | Agendamento em lote criado                                                 |
| **approved**             | Agendamento em lote aprovado                                               |
| **rejected**             | Agendamento em lote rejeitado                                              |
| **pending_2fa_approval** | Agendamento em lote pendente de aprovação por autenticação de dois fatores |

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                  | Descrição (eng)<br/>`description`                                                          | Descrição (ptbr)<br/>`translation`                                                 |
|--------------------------|----------------------|-----------------------------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                         | schema error description                                                                   | Schema Inválido                                                                    |
| 404                      | TED000006            | Target account Not Found                            | Target account was not found for given parameters                                          | Conta destino não encontrada para os parâmetros informados                         |
| 404                      | TED000009            | Not Found                                           | Account not found for the given key: \{account_key\}                                       | Conta não encontrada para a chave fornecida: \{account_key\}                       |
| 403                      | TED000014            | Invalid target account                              | Invalid target account                                                                     | Conta destino inválida                                                             |
| 400                      | TED000015            | Bad Request                                         | Account blocked or closed can not perform this action                                      | A conta bloqueada ou fechada não pode executar esta ação                           |
| 400                      | TED000016            | Bad Request                                         | Hub account can not perform this action                                                    | A conta hub não pode executar esta ação                                            |
| 403                      | TED000018            | Unauthorized                                        | Provided account not owned by SELECTED_AGENT                                               | Conta fornecida não pertencente ao SELECTED_AGENT                                  |
| 400                      | TED000031            | Bad Request                                         | ISPB number \{ispb\} does not exist or is inactive                                         | ISPB \{ispb\} não existe ou está inativo                                           |
| 400                      | TED000044            | Invalid Timestamp Format sent                       | Given parameter is not in the correct format \{timestamp_format\}                          | Parametro enviado não está no formato correto \{timestamp_format\}                 |
| 400                      | TED000045            | Search Params Error                                 | Invalid integer value for page or size querystring parameters                              | Valor inválido para parâmetros de página ou tamanho de página                      |
| 400                      | TED000046            | Invalid uuid v4 string sent                         | \{key\} was not accepted for not being a valid uuid v4 string                              | \{key\} não foi aceito por não ser uma palavra uuid v4 válida                      |
| 400                      | TED000054            | Invalid Transaction Amount                          | Transaction Amount \{transaction_amount\} is invalid                                       | Valor de transação \{transaction_amount\} é inválido                               |
| 400                      | TED000057            | Invalid Document Number                             | Given \{document_number\} document number is invalid                                       | CPF/CNPJ \{document_number\} fornecido não é valido                                |
| 409                      | TED000064            | Bad Request                                         | request_control_key \{request_control_key\} already in use                                 | request_control_key \{request_control_key\} já utilizada                           |
| 400                      | TED000065            | Bad Request                                         | It has been identified by request_control_key that this request is already being processed | Foi identificado por request_control_key que está requisição está sendo processada |
| 403                      | TED000079            | No approver permission                              | Given document number does not belong to an approver for this account                      | Número de documento enviado não pertence a um aprovador da conta                   |
| 400                      | TED000080            | tfa_info is required                                | Client must send object tfa_info                                                           | Cliente deve enviar objeto tfa_info                                                |
| 400                      | TED000081            | Error occurred while sending token                  | An unexpected error occurred while sending token                                           | Um erro inexperado ocorreu ao tentar enviar token                                  |
| 400                      | TED000089            | Invalid Schedule Date                               | Schedule date must be after current date for UTC-3                                         | Data de agendamento deve ser após a data atual em UTC-3                            |
| 400                      | TED000090            | Invalid Schedule Date                               | Schedule date must be a workday                                                            | Data de agendamento deve ser um dia útil                                           |
| 400                      | TED000091            | Target Account and Source Account must be different | Target Account must not be the same as Source Account                                      | A conta de destino não pode ser a mesma da conta de origem                         |

---

# Solicitar Reenvio de Token para um Agendamento de Transação Ted em Lote

URL: /documentation/baas/ted/schedule_batch_2fa/solicitacao_de_reenvio_de_token_para_agendamento_em_lote_2fa

Um novo token será gerado e enviado para o aprovador do agendamento ted. Caso o número limite de tentativas de validação
do token tenha sido excedida, não será permitido o reenvio.

## Request

ENDPOINT /account/ ACCOUNT_KEY /ted_schedule_batch/ SCHEDULE_BATCH_KEY /resend_token
MÉTODO PATCH

### Path Params

| Campo                | Tipo   | Descrição                                            | Caracteres |
|----------------------|--------|------------------------------------------------------|------------|
| `account_key`        | uuidv4 | Chave única de identificação da conta.               | 36         |
| `schedule_batch_key` | uuidv4 | Chave única de identificação do agendamento em lote. | 36         |

## Body Params

| Campo          | Tipo       | Descrição                               | Caracteres                                              |
|----------------|------------|-----------------------------------------|---------------------------------------------------------|
| `contact_type` | enumerator | Forma de envio do token de autenticação | **[Enumerador contact_type](#enumerador-contact_type)** |

:::info Informação
Caso não seja enviado um `contact_type`, o token será enviado da forma solicitada originalmente.
:::

### Enumerador contact_type

| Enumerador | Descrição                                         |
|------------|---------------------------------------------------|
| **sms**    | Envio por Mensagem de Texto para telefone celular |
| **email**  | Envio por correio eletrônico                      |

## Response

STATUS 202

Response Body: Agendamento em lote Solicitado

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "schedule_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "schedule_batch_status": "pending_2fa_approval",
  "created_at": "2021-10-22T20:30:23.459Z"
} 
```

STATUS 4xx

Response Body: Transferência Rejeitada

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                   | Descrição (eng)<br/>`description`                                                                                    | Descrição (ptbr)<br/>`translation`                                                                                   |
|--------------------------|----------------------|--------------------------------------|----------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                          | schema error description                                                                                             | Schema Inválido                                                                                                      |
| 404                      | TED000009            | Not Found                            | Account not found for the given key: \{account_key\}                                                                 | Conta não encontrada para a chave fornecida: \{account_key\}                                                         |
| 403                      | TED000018            | Unauthorized                         | Provided account not owned by SELECTED_AGENT                                                                         | Conta fornecida não pertencente ao SELECTED_AGENT                                                                    |
| 400                      | TED000087            | Error Sending Token                  | An error occurred while resending token and its being investigated                                                   | Um erro ocorreu ao reenviar token e está sendo investigado                                                           |
| 404                      | TED000103            | ScheduleBatch not Found              | Ted Schedule Batch was not found                                                                                     | Agendamento de Ted em lote não encontrado                                                                            |
| 400                      | TED000106            | Invalid Status                       | ScheduleBatch not in pending_2fa_approval status                                                                     | Lote Agendamentos de Ted não está pendente de aprovação por autenticação de dois fatores                             |
| 400                      | TED000107            | Schedule Batch could not be approved | ScheduleBatch could not be approved due to current date being equal or after earliest schedule date. Rejecting batch | ScheduleBatch não pode ser aprovada devido a data atual ser superior ou igual à menor schedule_date. Rejeitando lote |

---

# Cancelar Agendamento de Transação Ted em Lote

URL: /documentation/baas/ted/schedule_batch/cancelamento_de_agendamento_em_lote

## Request

ENDPOINT /account/ ACCOUNT_KEY /ted_schedule_batch/ SCHEDULE_BATCH_KEY /cancel
MÉTODO PATCH

### Path Params

| Campo                | Tipo   | Descrição                                           | Caracteres |
|----------------------|--------|-----------------------------------------------------|------------|
| `account_key`        | uuidv4 | Chave única de identificação da conta.              | 36         |
| `schedule_batch_key` | uuidv4 | Chave única de identificação do lote de agendamento | 36         |

### Response

STATUS 200

Response Body: Agendamento Cancelado

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "schedule_batch_key": "f64b3fa7-d09d-4927-ad4f-b966df9fb153",
  "schedule_batch_status": "cancelled",
  "created_at": "2023-03-13T19:00:28.440Z"
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                    | Descrição (eng)<br/>`description`                                                                                                 | Descrição (ptbr)<br/>`translation`                                                                                                         |
|--------------------------|----------------------|---------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                           | schema error description                                                                                                          | Schema Inválido                                                                                                                            |
| 404                      | TED000009            | Not Found                             | Account not found for the given key: \{account_key\}                                                                              | Conta não encontrada para a chave fornecida: \{account_key\}                                                                               |
| 403                      | TED000018            | Unauthorized                          | Provided account not owned by SELECTED_AGENT                                                                                      | Conta fornecida não pertencente ao SELECTED_AGENT                                                                                          |
| 400                      | TED000096            | Bad Request                           | Action cannot be taken place as there is currently a pending transfer in progress                                                 | A ação não pôde ser completada como há uma transferência pendente                                                                          |
| 404                      | TED000101            | TedBatch not Found                    | TedBatch was not found                                                                                                            | TedBatch não encontrada                                                                                                                    |
| 404                      | TED000103            | ScheduleBatch not Found               | Ted Schedule Batch was not found                                                                                                  | Agendamento de Ted em lote não encontrado                                                                                                  |
| 400                      | TED000104            | Invalid Status                        | Schedule Batch cannot be cancelled in current status                                                                              | Lote de agendamento não pode ser cancelado no status atual                                                                                 |
| 400                      | TED000105            | Schedule Batch could not be cancelled | ScheduleBatch could not be cancelled due to current date being equal or after earliest schedule date. Cancel schedules one by one | ScheduleBatch não pode ser cancelada devido a data atual ser superior ou igual à menor schedule_date. Cancele agendamentos individualmente |

---

# Listar Agendamentos de um Lote de Agendamento

URL: /documentation/baas/ted/schedule_batch/listar_agendamentos_de_um_lote

## Request

ENDPOINT /account/ ACCOUNT_KEY /ted_schedule_batch/ SCHEDULE_BATCH_KEY /ted_schedules
MÉTODO GET

### Path Params

| Campo                | Tipo   | Descrição                                             | Caracteres |
|----------------------|--------|-------------------------------------------------------|------------|
| `account_key`        | uuidv4 | Chave única de identificação da conta.                | 36         |
| `schedule_batch_key` | uuidv4 | Chave única de identificação do lote de agendamentos. | 36         |

### Query Params

| Campo                 | Tipo    | Descrição                                                               | Caracteres                                                    |
|-----------------------|---------|-------------------------------------------------------------------------|---------------------------------------------------------------|
| `request_control_key` | uuidv4  | Chave única de identificação da request utilizada pelo cliente.         | 36                                                            |
| `schedule_status`     | string  | Status do agendamento. Pode ser enviado em forma de lista.              | **[Enumerador schedule_status](#enumerador-schedule_status)** |
| `start_date`          | string  | Data de início da consulta                                              | 10                                                            |
| `end_date`            | string  | Data de término da consulta                                             | 10                                                            |
| `page`                | integer | Número da página requisitada. 1 por padrão                              |                                                               |
| `page_size`           | integer | Tamanho da página requisitada na consulta. 30 por padrão e valor máximo | Valor máximo de 30                                            |

### Enumerador schedule_status

| Enumerador                 | Descrição                                                                                      |
|----------------------------|------------------------------------------------------------------------------------------------|
| **scheduled**              | Transação agendada                                                                             |
| **sent**                   | Agendamento concluído e enviado com sucesso. Estado final                                      |
| **rejected**               | Agendamento rejeitado durante criação ou execução. Estado final                                |
| **cancelled**              | Agendamento cancelado por solicitação de cliente. Estado final                                 |
| **pending_2fa_approval**   | Pendente de aprovação por autenticação de dois fatores                                         |
| **pending_creation**       | Agendamento em processo de criação (Estado transitório para agendamento em lote)               |
| **waiting_batch_approval** | Agendamento criado e vinculado a um lote aguardando aprovação por autenticação de dois fatores |

### Response

STATUS 200

Response Body

```json
{
  "data": [
    {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "schedule_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "schedule_status": "scheduled",
      "schedule_date": "2024-12-31",
      "created_at": "2023-03-13T19:00:28.440Z"
    },
    {
      "request_control_key": "bf6b0a4b-c7a5-446b-9dad-1ae10b25342a",
      "schedule_key": "2479a5cd-079e-4d72-bf4e-16a695bda45e",
      "schedule_status": "cancelled",
      "schedule_date": "2024-12-31",
      "created_at": "2023-03-13T19:00:28.440Z"
    },
    {
      "request_control_key": "9d36c03e-2db7-4c90-87ed-6c9ddb3c03c7",
      "schedule_key": "5d6b14b9-053f-408c-bcd7-61ecf9224f2c",
      "schedule_status": "rejected",
      "schedule_date": "2024-12-31",
      "created_at": "2023-03-13T19:00:28.440Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "rows_per_page": 30
  }
}

```

---

# Listar Lotes de Agendamento de uma conta

URL: /documentation/baas/ted/schedule_batch/listar_agendamentos_em_lote_de_uma_conta

## Request

ENDPOINT /account/ ACCOUNT_KEY /ted_schedule_batches
MÉTODO GET

### Path Params

| Campo         | Tipo   | Descrição                              | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36         |

### Query Params

| Campo                   | Tipo    | Descrição                                                               | Caracteres                                                                |
|-------------------------|---------|-------------------------------------------------------------------------|---------------------------------------------------------------------------|
| `request_control_key`   | uuidv4  | Chave única de identificação da request utilizada pelo cliente.         | 36                                                                        |
| `schedule_batch_status` | string  | Status do lote de agendamento. Pode ser enviado em forma de lista.      | **[Enumerador schedule_batch_status](#enumerador-schedule_batch_status)** |
| `page`                  | integer | Número da página requisitada. 1 por padrão                              |                                                                           |
| `page_size`             | integer | Tamanho da página requisitada na consulta. 30 por padrão e valor máximo | Valor máximo de 30                                                        |

### Enumerador schedule_batch_status

| Enumerador               | Descrição                                                                  |
|--------------------------|----------------------------------------------------------------------------|
| **created**              | Agendamento em lote criado                                                 |
| **approved**             | Agendamento em lote aprovado                                               |
| **rejected**             | Agendamento em lote rejeitado                                              |
| **pending_2fa_approval** | Agendamento em lote pendente de aprovação por autenticação de dois fatores |

### Response

STATUS 200

Response Body

```json
{
  "data": [
    {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "schedule_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "schedule_batch_status": "approved",
      "created_at": "2021-10-22T20:30:23.459Z"
    },
    {
      "request_control_key": "bf6b0a4b-c7a5-446b-9dad-1ae10b25342a",
      "schedule_batch_key": "2479a5cd-079e-4d72-bf4e-16a695bda45e",
      "schedule_batch_status": "cancelled",
      "created_at": "2021-10-22T20:30:23.459Z"
    },
    {
      "request_control_key": "9d36c03e-2db7-4c90-87ed-6c9ddb3c03c7",
      "schedule_batch_key": "5d6b14b9-053f-408c-bcd7-61ecf9224f2c",
      "schedule_batch_status": "rejected",
      "created_at": "2021-10-22T20:30:23.459Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "rows_per_page": 30
  }
}

```

---

# Solicitar Agendamento de Transação Ted em Lote

URL: /documentation/baas/ted/schedule_batch/solicitacao_de_agendamento_em_lote

A QI Tech oferece a possibilidade de realizar várias transações agendadas ted com uma única chamada. Caso na chamada
inicial seja retornado um **http status 4xx**, nenhum dos agendamentos será realizado.

## Request

ENDPOINT /account/ ACCOUNT_KEY /ted_schedule_batch
MÉTODO POST

```json
{
  "request_control_key": "6e4fc980-f8a1-4462-b6e2-d8a49f0ac055",
  "ted_schedules": [
    {
      "request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
      "target_account": {
        "account_branch": "0001",
        "account_number": "92796",
        "account_digit": "1",
        "owner_document_number": "23599885000192",
        "owner_name": "Titular da Conta",
        "ispb": "12345678",
        "account_type": "checking_account"
      },
      "transaction_amount": 8.86,
      "schedule_date": "2024-12-01"
    }
  ]
}
```

## Path Params

| Campo         | Tipo   | Descrição                              | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36         |

## Body Params

| Campo                   | Tipo   | Descrição                                                                          | Caracteres                                               |
|-------------------------|--------|------------------------------------------------------------------------------------|----------------------------------------------------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36                                                       | 
| `ted_schedules` *       | array  | Lista de objetos ted_schedule vinculados ao lote.                                  | lista de **[Objeto ted_schedule](#objeto-ted_schedule)** |

## Objeto ted_schedule

| Campo                   | Tipo   | Descrição                                                                          | Caracteres                                          |
|-------------------------|--------|------------------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | string | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36                                                  |
| `target_account` *      | object | Conta de destino                                                                   | **[Objeto target_account](#objeto-target_account)** | 
| `transaction_amount` *  | float  | Valor da transferência                                                             | 10                                                  |
| `schedule_date`*        | string | Data a ser realizada a transação.                                                  | 10                                                  |

## Objeto target_account

| Campo                     | Tipo   | Descrição                                           | Caracteres                                              |
|---------------------------|--------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string | Agência.                                            | 4                                                       |
| `account_digit` *         | string | Dígito da conta                                     | 1                                                       |
| `account_number` *        | string | Número da conta.                                    | 20                                                      |
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta.   | 14                                                      |
| `owner_name` *            | string | Nome do titular da conta.                           | 50                                                      |
| `account_type`*           | string | Tipo da conta.                                      | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string | Base no CNPJ da instituição financeira (8 dígitos). | 8                                                       |

## Enumerador account_type

| Enumerador             | Tradução              |
|------------------------|-----------------------|
| **checking_account**   | conta corrente        |
| **deposit_account**    | conta depósito        |
| **guaranteed_account** | conta de garantia     |
| **investment_account** | conta de investimento |
| **payment_account**    | conta de pagamento    |
| **saving_account**     | conta poupança        |

## Response

STATUS 201

Response Body: Agendamento em lote Aprovado

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "schedule_batch_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "schedule_batch_status": "approved",
  "created_at": "2021-10-22T20:30:23.459Z"
}
```

### Enumerador schedule_batch_status

| Enumerador               | Descrição                                                                  |
|--------------------------|----------------------------------------------------------------------------|
| **created**              | Agendamento em lote criado                                                 |
| **approved**             | Agendamento em lote aprovado                                               |
| **rejected**             | Agendamento em lote rejeitado                                              |
| **pending_2fa_approval** | Agendamento em lote pendente de aprovação por autenticação de dois fatores |

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                  | Descrição (eng)<br/>`description`                                                          | Descrição (ptbr)<br/>`translation`                                                 |
|--------------------------|----------------------|-----------------------------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                         | schema error description                                                                   | Schema Inválido                                                                    |
| 404                      | TED000006            | Target account Not Found                            | Target account was not found for given parameters                                          | Conta destino não encontrada para os parâmetros informados                         |
| 404                      | TED000009            | Not Found                                           | Account not found for the given key: \{account_key\}                                       | Conta não encontrada para a chave fornecida: \{account_key\}                       |
| 403                      | TED000014            | Invalid target account                              | Invalid target account                                                                     | Conta destino inválida                                                             |
| 400                      | TED000015            | Bad Request                                         | Account blocked or closed can not perform this action                                      | A conta bloqueada ou fechada não pode executar esta ação                           |
| 400                      | TED000016            | Bad Request                                         | Hub account can not perform this action                                                    | A conta hub não pode executar esta ação                                            |
| 403                      | TED000018            | Unauthorized                                        | Provided account not owned by SELECTED_AGENT                                               | Conta fornecida não pertencente ao SELECTED_AGENT                                  |
| 400                      | TED000031            | Bad Request                                         | ISPB number \{ispb\} does not exist or is inactive                                         | ISPB \{ispb\} não existe ou está inativo                                           |
| 400                      | TED000044            | Invalid Timestamp Format sent                       | Given parameter is not in the correct format \{timestamp_format\}                          | Parametro enviado não está no formato correto \{timestamp_format\}                 |
| 400                      | TED000045            | Search Params Error                                 | Invalid integer value for page or size querystring parameters                              | Valor inválido para parâmetros de página ou tamanho de página                      |
| 400                      | TED000046            | Invalid uuid v4 string sent                         | \{key\} was not accepted for not being a valid uuid v4 string                              | \{key\} não foi aceito por não ser uma palavra uuid v4 válida                      |
| 400                      | TED000054            | Invalid Transaction Amount                          | Transaction Amount \{transaction_amount\} is invalid                                       | Valor de transação \{transaction_amount\} é inválido                               |
| 400                      | TED000057            | Invalid Document Number                             | Given \{document_number\} document number is invalid                                       | CPF/CNPJ \{document_number\} fornecido não é valido                                |
| 409                      | TED000064            | Bad Request                                         | request_control_key \{request_control_key\} already in use                                 | request_control_key \{request_control_key\} já utilizada                           |
| 400                      | TED000065            | Bad Request                                         | It has been identified by request_control_key that this request is already being processed | Foi identificado por request_control_key que está requisição está sendo processada |
| 400                      | TED000089            | Invalid Schedule Date                               | Schedule date must be after current date for UTC-3                                         | Data de agendamento deve ser após a data atual em UTC-3                            |
| 400                      | TED000090            | Invalid Schedule Date                               | Schedule date must be a workday                                                            | Data de agendamento deve ser um dia útil                                           |
| 400                      | TED000091            | Target Account and Source Account must be different | Target Account must not be the same as Source Account                                      | A conta de destino não pode ser a mesma da conta de origem                         |

---

# Cancelar Agendamento de Transação Ted

URL: /documentation/baas/ted/schedule/cancelamento_de_agendamento

## Request

ENDPOINT /account/ ACCOUNT_KEY /ted_schedule/ SCHEDULE_KEY /cancel
MÉTODO PATCH

### Path Params

| Campo          | Tipo   | Descrição                                   | Caracteres |
|----------------|--------|---------------------------------------------|------------|
| `account_key`  | uuidv4 | Chave única de identificação da conta.      | 36         |
| `schedule_key` | uuidv4 | Chave única de identificação do agendamento | 36         |

### Response

STATUS 200

Response Body: Agendamento Cancelado

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "schedule_key": "f64b3fa7-d09d-4927-ad4f-b966df9fb153",
  "schedule_status": "cancelled",
  "schedule_date": "2024-12-31"
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                   | Descrição (eng)<br/>`description`                                                 | Descrição (ptbr)<br/>`translation`                                                          |
|--------------------------|----------------------|--------------------------------------|-----------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                          | schema error description                                                          | Schema Inválido                                                                             |
| 404                      | TED000009            | Not Found                            | Account not found for the given key: \{account_key\}                              | Conta não encontrada para a chave fornecida: \{account_key\}                                |
| 403                      | TED000018            | Unauthorized                         | Provided account not owned by SELECTED_AGENT                                      | Conta fornecida não pertencente ao SELECTED_AGENT                                           |
| 400                      | TED000044            | Invalid Timestamp Format sent        | Given parameter is not in the correct format \{timestamp_format\}                 | Parametro enviado não está no formato correto \{timestamp_format\}                          |
| 400                      | TED000045            | Search Params Error                  | Invalid integer value for page or size querystring parameters                     | Valor inválido para parâmetros de página ou tamanho de página                               |
| 400                      | TED000046            | Invalid uuid v4 string sent          | \{key\} was not accepted for not being a valid uuid v4 string                     | \{key\} não foi aceito por não ser uma palavra uuid v4 válida                               |
| 404                      | TED000093            | TedSchedule not Found                | TedSchedule was not found                                                         | TedSchedule não encontrada                                                                  |
| 400                      | TED000094            | Bad Request                          | Ted Schedule cannot be cancelled in current status                                | Agendamento Ted não pode ser cancelado no status atual                                      |
| 400                      | TED000095            | Bad Request                          | The given Ted Schedule is tied to a batch. It cannot be individually cancelled    | O agendamento Ted enviado está ligado a um lote. Ela não pode ser individualmente cancelada |
| 400                      | TED000096            | Bad Request                          | Action cannot be taken place as there is currently a pending transfer in progress | A ação não pôde ser completada como há uma transferência pendente                           |
| 400                      | TED000108            | Number of transfer attempts exceeded | The maximum number of failed transfer attempts has been reached                   | Número máximo de tentativas de transferência foi atingida                                   |

---

# Consultar Agendamento de Transação Ted

URL: /documentation/baas/ted/schedule/consulta_de_agendamento

## Request

ENDPOINT /account/ ACCOUNT_KEY /ted_schedule/ SCHEDULE_KEY
MÉTODO GET

### Path Params

| Campo          | Tipo   | Descrição                                   | Caracteres |
|----------------|--------|---------------------------------------------|------------|
| `account_key`  | uuidv4 | Chave única de identificação da conta.      | 36         |
| `schedule_key` | uuidv4 | Chave única de identificação do agendamento | 36         |

### Response

STATUS 200

Response Body

```json
{
  "request_control_key": "b8eb663e-10fe-4729-9db5-8f8c93de5001",
  "schedule_key": "0c9091ab-079b-4a43-8b3d-d4ba36a23883",
  "schedule_batch_key": null,
  "schedule_status": "sent",
  "target_account": {
    "account_branch": "0001",
    "account_digit": "8",
    "account_number": "1234567",
    "owner_document_number": "***91111***",
    "owner_person_type": "natural",
    "owner_name": "Conta manual geral",
    "account_type": "checking_account",
    "ispb": "99999004"
  },
  "transaction_amount": 2.0,
  "rejection_info": null,
  "schedule_date": "2024-07-10",
  "updated_at": "2024-07-10T16:19:38Z",
  "created_at": "2024-06-10T11:17:28Z",
  "schedule_transfers": [
    {
      "request_control_key": "12723821-41d5-496b-b66c-fb7188f50fc1",
      "ted_key": "91028dfa-43a2-4665-adf2-0bd4571f6f0d",
      "created_at": "2024-07-10T16:19:38Z",
      "ted_status": "sent",
      "fee_amount": 2.00
    }
  ]
}
```

---

# Introdução

URL: /documentation/baas/ted/schedule/introducao

Por meio dos endpoints apresentados nesta sessão, o parceiro integrador pode solicitar o agendamento de transações do
tipo ted. Com esta funcionalidade será possível criar, listar e cancelar agendamentos de uma determinada conta.

## Observações

- A data de agendamento leva em consideração o horário de Brasília (BRT ou UTC/GMT -03:00)
- As transações serão tentadas a partir de 8h BRT
- As transações não podem ser agendadas para feriados ou fim de semana
- Transações que tenham falhado por falta de saldo serão retentadas em 1 hora com um limite de 3 tentativas
- Um webhook será enviado ao parceiro integrador informando o sucesso ou rejeição de um agendamento

## Ted Schedule Status

| Enumerador                 | Descrição                                                                                      |
|----------------------------|------------------------------------------------------------------------------------------------|
| **scheduled**              | Transação agendada                                                                             |
| **sent**                   | Agendamento concluído e enviado com sucesso. Estado final                                      |
| **rejected**               | Agendamento rejeitado durante criação ou execução. Estado final                                |
| **cancelled**              | Agendamento cancelado por solicitação de cliente. Estado final                                 |
| **pending_2fa_approval**   | Pendente de aprovação por autenticação de dois fatores                                         |
| **waiting_batch_approval** | Agendamento criado e vinculado a um lote aguardando aprovação por autenticação de dois fatores |

## Schedule Transfers

No dia do agendamento será tentada a transação ted. Neste momento é gerada uma **ted** e esta será adicionada à lista de
`schedule_transfers`. Serão tentadas um
máximo 3 transações ted.

---

# Listar Agendamentos de Transação Ted de uma conta

URL: /documentation/baas/ted/schedule/listar_agendamentos_de_uma_conta

## Request

ENDPOINT /account/ ACCOUNT_KEY /ted_schedules
MÉTODO GET

### Path Params

| Campo         | Tipo   | Descrição                              | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36         |

### Query Params

| Campo                 | Tipo    | Descrição                                                               | Caracteres                                                    |
|-----------------------|---------|-------------------------------------------------------------------------|---------------------------------------------------------------|
| `request_control_key` | uuidv4  | Chave única de identificação da request utilizada pelo cliente.         | 36                                                            |
| `schedule_status`     | string  | Status do agendamento. Pode ser enviado em forma de lista.              | **[Enumerador schedule_status](#enumerador-schedule_status)** |
| `page`                | integer | Número da página requisitada. 1 por padrão                              |                                                               |
| `page_size`           | integer | Tamanho da página requisitada na consulta. 30 por padrão e valor máximo | Valor máximo de 30                                            |

### Enumerador schedule_status

| Enumerador                 | Descrição                                                                                      |
|----------------------------|------------------------------------------------------------------------------------------------|
| **scheduled**              | Transação agendada                                                                             |
| **sent**                   | Agendamento concluído e enviado com sucesso. Estado final                                      |
| **rejected**               | Agendamento rejeitado durante criação ou execução. Estado final                                |
| **cancelled**              | Agendamento cancelado por solicitação de cliente. Estado final                                 |
| **pending_2fa_approval**   | Pendente de aprovação por autenticação de dois fatores                                         |
| **pending_creation**       | Agendamento em processo de criação (Estado transitório para agendamento em lote)               |
| **waiting_batch_approval** | Agendamento criado e vinculado a um lote aguardando aprovação por autenticação de dois fatores |

### Response

STATUS 200

Response Body

```json
{
  "data": [
    {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "schedule_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "schedule_status": "scheduled",
      "schedule_date": "2024-12-31",
      "created_at": "2023-03-13T19:00:28.440Z"
    },
    {
      "request_control_key": "bf6b0a4b-c7a5-446b-9dad-1ae10b25342a",
      "schedule_key": "2479a5cd-079e-4d72-bf4e-16a695bda45e",
      "schedule_status": "cancelled",
      "schedule_date": "2024-12-31",
      "created_at": "2023-03-13T19:00:28.440Z"
    },
    {
      "request_control_key": "9d36c03e-2db7-4c90-87ed-6c9ddb3c03c7",
      "schedule_key": "5d6b14b9-053f-408c-bcd7-61ecf9224f2c",
      "schedule_status": "rejected",
      "schedule_date": "2024-12-31",
      "created_at": "2023-03-13T19:00:28.440Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "rows_per_page": 30
  }
}

```

---

# Solicitar Agendamento de Transação Ted

URL: /documentation/baas/ted/schedule/solicitacao_de_agendamento

## Request

ENDPOINT /account/ ACCOUNT_KEY /ted_schedule
MÉTODO POST

Request Body

```json
{
  "request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
  "target_account": {
    "account_branch": "0001",
    "account_number": "92796",
    "account_digit": "1",
    "owner_document_number": "23599885000192",
    "owner_name": "Titular da Conta",
    "ispb": "12345678",
    "account_type": "checking_account"
  },
  "transaction_amount": 8.86,
  "schedule_date": "2024-12-01"
}
```

### Path Params

| Campo         | Tipo   | Descrição                              | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36         |

## Body Params

| Campo                   | Tipo   | Descrição                                                                          | Caracteres                                          |
|-------------------------|--------|------------------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | string | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36                                                  |
| `target_account` *      | object | Conta de destino                                                                   | **[Objeto target_account](#objeto-target_account)** | 
| `transaction_amount` *  | float  | Valor da transferência                                                             | 10                                                  |
| `schedule_date`*        | string | Data a ser realizada a transação.                                                  | 10                                                  |

## Objeto target_account

| Campo                     | Tipo   | Descrição                                           | Caracteres                                              |
|---------------------------|--------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string | Agência.                                            | 4                                                       |
| `account_digit` *         | string | Dígito da conta                                     | 1                                                       |
| `account_number` *        | string | Número da conta.                                    | 20                                                      |
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta.   | 14                                                      |
| `owner_name` *            | string | Nome do titular da conta.                           | 50                                                      |
| `account_type`*           | string | Tipo da conta.                                      | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string | Base no CNPJ da instituição financeira (8 dígitos). | 8                                                       |

## Enumerador account_type

| Enumerador             | Tradução              |
|------------------------|-----------------------|
| **checking_account**   | conta corrente        |
| **deposit_account**    | conta depósito        |
| **guaranteed_account** | conta de garantia     |
| **investment_account** | conta de investimento |
| **payment_account**    | conta de pagamento    |
| **saving_account**     | conta poupança        |

## Response

STATUS 201

Response Body: Agendamento Criado

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "schedule_key": "f64b3fa7-d09d-4927-ad4f-b966df9fb153",
  "schedule_status": "scheduled",
  "schedule_date": "2024-12-31"
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                  | Descrição (eng)<br/>`description`                                                          | Descrição (ptbr)<br/>`translation`                                                 |
|--------------------------|----------------------|-----------------------------------------------------|--------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                         | schema error description                                                                   | Schema Inválido                                                                    |
| 404                      | TED000006            | Target account Not Found                            | Target account was not found for given parameters                                          | Conta destino não encontrada para os parâmetros informados                         |
| 404                      | TED000009            | Not Found                                           | Account not found for the given key: \{account_key\}                                       | Conta não encontrada para a chave fornecida: \{account_key\}                       |
| 403                      | TED000014            | Invalid target account                              | Invalid target account                                                                     | Conta destino inválida                                                             |
| 400                      | TED000015            | Bad Request                                         | Account blocked or closed can not perform this action                                      | A conta bloqueada ou fechada não pode executar esta ação                           |
| 400                      | TED000016            | Bad Request                                         | Hub account can not perform this action                                                    | A conta hub não pode executar esta ação                                            |
| 403                      | TED000018            | Unauthorized                                        | Provided account not owned by SELECTED_AGENT                                               | Conta fornecida não pertencente ao SELECTED_AGENT                                  |
| 400                      | TED000031            | Bad Request                                         | ISPB number \{ispb\} does not exist or is inactive                                         | ISPB \{ispb\} não existe ou está inativo                                           |
| 400                      | TED000044            | Invalid Timestamp Format sent                       | Given parameter is not in the correct format \{timestamp_format\}                          | Parametro enviado não está no formato correto \{timestamp_format\}                 |
| 400                      | TED000046            | Invalid uuid v4 string sent                         | \{key\} was not accepted for not being a valid uuid v4 string                              | \{key\} não foi aceito por não ser uma palavra uuid v4 válida                      |
| 400                      | TED000054            | Invalid Transaction Amount                          | Transaction Amount \{transaction_amount\} is invalid                                       | Valor de transação \{transaction_amount\} é inválido                               |
| 400                      | TED000057            | Invalid Document Number                             | Given \{document_number\} document number is invalid                                       | CPF/CNPJ \{document_number\} fornecido não é valido                                |
| 409                      | TED000064            | Bad Request                                         | request_control_key \{request_control_key\} already in use                                 | request_control_key \{request_control_key\} já utilizada                           |
| 400                      | TED000065            | Bad Request                                         | It has been identified by request_control_key that this request is already being processed | Foi identificado por request_control_key que está requisição está sendo processada |
| 400                      | TED000089            | Invalid Schedule Date                               | Schedule date must be after current date for UTC-3                                         | Data de agendamento deve ser após a data atual em UTC-3                            |
| 400                      | TED000090            | Invalid Schedule Date                               | Schedule date must be a workday                                                            | Data de agendamento deve ser um dia útil                                           |
| 400                      | TED000091            | Target Account and Source Account must be different | Target Account must not be the same as Source Account                                      | A conta de destino não pode ser a mesma da conta de origem                         |

---

# Webhook de conclusão de Agendamento Ted

URL: /documentation/baas/ted/schedule/webhook_de_conclusao_de_agendamento

Após a conclusão de um agendamento Ted, um webhook será enviado ao parceiro integrador com o resultado.

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeados de forma restrita. Campos adicionais podem ser incluídos aos payloads dos
webhooks retornados em nossas APIs.
:::

### Webhook Request Body

Request Body: Agendamento Concluído e Enviado

```json
{
  "webhook_type": "baas.ted.ted_schedule.completed",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "request_control_key": "b8eb663e-10fe-4729-9db5-8f8c93de5001",
    "schedule_key": "0c9091ab-079b-4a43-8b3d-d4ba36a23883",
    "schedule_batch_key": null,
    "schedule_status": "sent",
    "target_account": {
      "account_branch": "0001",
      "account_digit": "8",
      "account_number": "1234567",
      "owner_document_number": "***91111***",
      "owner_person_type": "natural",
      "owner_name": "Conta manual geral",
      "account_type": "checking_account",
      "ispb": "99999004"
    },
    "transaction_amount": 2.0,
    "rejection_info": null,
    "schedule_date": "2024-07-10",
    "updated_at": "2024-07-10T16:19:38Z",
    "created_at": "2024-06-10T11:17:28Z",
    "schedule_transfers": [
      {
        "request_control_key": "12723821-41d5-496b-b66c-fb7188f50fc1",
        "ted_key": "91028dfa-43a2-4665-adf2-0bd4571f6f0d",
        "created_at": "2024-07-10T16:19:38Z",
        "ted_status": "sent",
        "fee_amount": 2.00
      }
    ]
  }
}
```

Request Body: Agendamento Concluído e Rejeitado

```json
{
  "webhook_type": "baas.ted.ted_schedule.completed",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "request_control_key": "b8eb663e-10fe-4729-9db5-8f8c93de5001",
    "schedule_key": "0c9091ab-079b-4a43-8b3d-d4ba36a23883",
    "schedule_batch_key": null,
    "schedule_status": "sent",
    "target_account": {
      "account_branch": "0001",
      "account_digit": "8",
      "account_number": "1234567",
      "owner_document_number": "***91111***",
      "owner_person_type": "natural",
      "owner_name": "Conta manual geral",
      "account_type": "checking_account",
      "ispb": "99999004"
    },
    "transaction_amount": 2.0,
    "rejection_info": {
      "error_code": "TED000103",
      "error_description": "The maximum number of failed transfer attempts has been reached",
      "error_translation": "Número máximo de tentativas de transferência foi atingida",
      "rejection_reason": "max_tries_exceeded"
    },
    "schedule_date": "2024-07-10",
    "updated_at": "2024-07-10T16:19:38Z",
    "created_at": "2024-06-10T11:17:28Z",
    "schedule_transfers": [
      {
        "ted_key": "907e38c5-5700-492f-a181-8f651317458b",
        "created_at": "2024-07-10T16:19:38Z",
        "ted_status": "rejected",
        "fee_amount": 2.00
      },
      {
        "ted_key": "356f8855-8f8d-4aaa-8e8c-1287e363d143",
        "created_at": "2024-07-10T17:19:38Z",
        "ted_status": "rejected",
        "fee_amount": 2.00
      },
      {
        "ted_key": "c51cc7ee-d966-4bbb-8405-4850b90b43f8",
        "created_at": "2024-07-10T18:19:38Z",
        "ted_status": "rejected",
        "fee_amount": 2.00
      }
    ]
  }
}
```

### Webhook Body Param

| Campo                 | Tipo   | Descrição                                                                          | Max. Caracteres                                                    |
|-----------------------|--------|------------------------------------------------------------------------------------|--------------------------------------------------------------------|
| `webhook_type`        | string | Um enumerador que define o tipo de evento sendo reportado                          | 23                                                                 |
| `webhook_datetime`    | string | Data e hora do envio do webhook                                                    | 20                                                                 |
| `request_control_key` | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36                                                                 |                                                                  |
| `schedule_key`        | string | Chave única de identificação do agendamento                                        | 36                                                                 |
| `schedule_batch_key`  | string | Chave única de identificação do lote de agendamento                                | 36                                                                 |
| `schedule_status`     | string | Status do agendamento                                                              | **[Enumerador schedule_status](#ted-schedule-status)**             |
| `target_account`      | object | Conta destino do agendamento                                                       | **[Objeto target_account](#objeto-target_account)**                |
| `transaction_amount`  | number | Valor da transferencia                                                             | 10                                                                 |
| `schedule_transfers`  | array  | Lista de tentativas de transferências realizadas pelo agendamento                  | lista de **[Objeto schedule_transfer](#objeto-schedule-transfer)** |
| `schedule_date`       | string | Data a ser realizada a transação.                                                  | 10                                                                 |
| `rejection_info`      | object | Objeto com informaçôes sobre o evento de rejeição                                  |                                                                    |
| `updated_at`          | string | Data e hora da última atualização do agendamento.                                  | 20                                                                 |
| `created_at`          | string | Data e hora de criação do agendamento.                                             | 20                                                                 |

## Ted Schedule Status

| Enumerador                 | Descrição                                                                                      |
|----------------------------|------------------------------------------------------------------------------------------------|
| **scheduled**              | Transação agendada                                                                             |
| **sent**                   | Agendamento concluído e enviado com sucesso. Estado final                                      |
| **rejected**               | Agendamento rejeitado durante criação ou execução. Estado final                                |
| **cancelled**              | Agendamento cancelado por solicitação de cliente. Estado final                                 |
| **pending_2fa_approval**   | Pendente de aprovação por autenticação de dois fatores                                         |
| **waiting_batch_approval** | Agendamento criado e vinculado a um lote aguardando aprovação por autenticação de dois fatores |

### Objeto Schedule Transfer

| Campo        | Tipo   | Descrição                                                        | Caracteres                                        |
|--------------|--------|------------------------------------------------------------------|---------------------------------------------------|
| `ted_key`    | uuidv4 | Chave única de identificação da transferência Ted no sistema QI. | 36                                                |
| `ted_status` | string | Status da transação.                                             | [Enumeradores ted_status](#enumerador-ted-status) |
| `fee_amount` | number | Valor da transferencia                                           | 10                                                |
| `created_at` | string | Data e hora de criação da transação                              | 20                                                |

### Enumerador Ted Status

| Enumerador   | Descrição                                           |
|--------------|-----------------------------------------------------|
| **sent**     | Transação enviada com sucesso. Estado final         |
| **rejected** | Transação rejeitada durante execução. Estado final  |
| **pending**  | Transação pendente de conclusão. Estado Transitório |

### Objeto target_account

| Campo                   | Tipo       | Descrição                                                                                               | Caracteres                                                        |
|-------------------------|------------|---------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `account_branch`        | string     | Agência da conta                                                                                        | 6                                                                 |
| `account_digit`         | string     | Dígito da conta                                                                                         | 1                                                                 |
| `account_number`        | string     | Número da conta                                                                                         | 20                                                                |
| `owner_document_number` | string     | CPF ou CNPJ (apenas números) do titular da conta                                                        | 14                                                                |
| `owner_name`            | string     | Nome do titular da conta                                                                                | 150                                                               |
| `owner_person_type`     | enumerator | Identificador de que o dono da conta enviada é uma pessoa física ou jurídica                            | **[Enumerador owner_person_type](#enumerador-owner_person_type)** |                                                    |
| `owner_name`            | string     | Nome do titular da conta                                                                                | 150                                                               |
| `account_type`          | enumerator | Tipo da conta                                                                                           | **[Enumerador account_type](#enumerador-account_type)**           |
| `ispb`                  | string     | Código de oito dígitos que identifica os bancos no sistema de transferência de reserva do Banco Central | 8                                                                 |

### Enumerador owner_person_type

| Enum        | Description     |
|-------------|-----------------|
| **natural** | Pessoa física   |
| **legal**   | Pessoa jurídica |

## Enumerador account_type

| Enumerador             | Tradução              |
|------------------------|-----------------------|
| **checking_account**   | conta corrente        |
| **deposit_account**    | conta depósito        |
| **guaranteed_account** | conta de garantia     |
| **investment_account** | conta de investimento |
| **payment_account**    | conta de pagamento    |
| **saving_account**     | conta poupança        |

---

# Webhook após finalização de envio de TED

URL: /documentation/baas/ted/webhooks

Webhook informará caso uma transação TED tenha sido devolvida.

## Webhook Request Body

**Webhook Body: TED Rejeitada**

```json
{
  "webhook_type": "baas.ted.outgoing_ted",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
    "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
    "created_at": "2021-10-22T20:30:23.459Z",
    "ted_status": "sent",
    "transaction_amount": 126.97,
    "fee_amount": 0.0,
    "target_account": {
      "account_branch": "0001",
      "account_digit": "6",
      "account_number": "78340",
      "ispb": "12345678",
      "owner_document_number": "32402502000135",
      "owner_name": "QI Tech"
    },
    "refusal_reason": {
      "refusal_code": 1,
      "enumerator": "conta_destinatario_encerrada",
      "description": "Conta Destinatária do Crédito Encerrada"
    }
  }
}
```

**Webhook Body: TED Confirmada**

```json
{
  "webhook_type": "baas.ted.outgoing_ted",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
    "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
    "created_at": "2021-10-22T20:30:23.459Z",
    "ted_status": "confirmed",
    "transaction_amount": 126.97,
    "fee_amount": 0.0,
    "target_account": {
      "account_branch": "0001",
      "account_digit": "6",
      "account_number": "78340",
      "ispb": "12345678",
      "owner_document_number": "32402502000135",
      "owner_name": "QI Tech"
    },
    "refusal_reason": null
  }
}
```

## Webhook Body Param

| Campo                 | Tipo   | Descrição                                                                         | Max. Caracteres                                     |
|-----------------------|--------|-----------------------------------------------------------------------------------|-----------------------------------------------------|
| `webhook_type`        | string | Um enumerador que define o tipo de evento sendo reportado                         | 23                                                  |
| `webhook_datetime`    | string | Data e hora do envio do webhook                                                   | 20                                                  |
| `request_control_key` | string | Chave única de identificação da request utilizada pelo cliente no formato uuid v4 | 36                                                  | 
| `ted_key`             | string | Chave única de identificação da transferência TED                                 | 36                                                  |
| `created_at`          | string | Data e hora de criação da transação                                               | 24                                                  |
| `ted_status`          | string | Status da transação TED                                                           | **[Enumerador ted_status](#enumerador-ted_status)** |
| `transaction_amount`  | number | Valor da transferência                                                            | 10                                                  |
| `fee_amount`          | number | Valor da taxa cobrada pela transferencia                                         | 35                                                  |
| `target_account`      | Object | Conta destino - Só deve ser enviada em transações do tipo "manual"                | **[Objeto target_account](#objeto-target_account)** |
| `refusal_reason`      | Object | Motivo da recusa de acordo com o padrão do Banco Central                          | **[Objeto refusal_reason](#objeto-refusal_reason)** |

## Enumerador ted_status

| Enumerador    | Descrição                                |
|---------------|------------------------------------------|
| **sent**      | Transferência TED enviada com sucesso.   |
| **confirmed** | Transferência TED realizada com sucesso. |
| **pending**   | Transferência TED pendente.              |
| **rejected**  | Transferência TED rejeitada.             |
| **returned**  | Transferência TED devolvida.             |

## Objeto target_account

| Campo                     | Tipo   | Descrição                                           | Caracteres                                              |
|---------------------------|--------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string | Agência.                                            | 4                                                       |
| `account_digit` *         | string | Dígito da conta                                     | 1                                                       |
| `account_number` *        | string | Número da conta.                                    | 20                                                      |
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta.   | 14                                                      |
| `owner_name` *            | string | Nome do titular da conta.                           | 50                                                      |
| `account_type`*           | string | Tipo da conta.                                      | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string | Base no CNPJ da instituição financeira (8 dígitos). | 8                                                       |

## Objeto refusal_reason

| Campo           | Tipo   | Descrição                  | Caracteres |
|-----------------|--------|----------------------------|------------|
| `bacen_code` *  | string | Código de recusa Bacen     | 3          |
| `enumerator` *  | string | Enumerador da recusa Bacen | 100        |
| `description` * | string | Descrição da recusa Bacen  | 100        |

## Enumerador account_type

| Enumerador         | Tradução              |
|--------------------|-----------------------|
| checking_account   | conta corrente        |
| deposit_account    | conta depósito        |
| guaranteed_account | conta de garantia     |
| investment_account | conta de investimento |
| payment_account    | conta de pagamento    |
| saving_account     | conta poupança        |

## Webhook após o recebimento de TED

Webhook informará sobre o status final da transação TED.

## Webhook Request Body

**Request Body: TED Recebida**

```json
{
  "webhook_type": "baas.ted.incoming_ted",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
    "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
    "created_at": "2021-10-22T20:30:23.459Z",
    "ted_status": "received",
    "transaction_amount": 126.97,
    "fee_amount": 0.0,
    "source_account": {
      "account_branch": "0001",
      "account_digit": "6",
      "account_number": "78340",
      "ispb": "12345678",
      "owner_document_number": "32402502000135",
      "owner_name": "QI Tech"
    },
    "refusal_reason": {}
  }
}
```

## Webhook Body Param

| Campo                 | Tipo   | Descrição                                                                         | Max. Caracteres                                     |
|-----------------------|--------|-----------------------------------------------------------------------------------|-----------------------------------------------------|
| `webhook_type`        | string | Um enumerador que define o tipo de evento sendo reportado                         | 23                                                  |
| `webhook_datetime`    | string | Data e hora do envio do webhook                                                   | 20                                                  |
| `ted_key`             | string | Chave única de identificação da transferência TED                                 | 36                                                  |
| `created_at`          | string | Data e hora de criação da transação                                               | 100                                                 |
| `ted_status`          | string | Status da transação TED                                                           | **[Enumerador ted_status](#enumerador-ted_status)** |
| `transaction_amount`  | number | Valor da transferência                                                            | 10                                                  |
| `fee_amount`          | number | Valor da taxa cobrada pela transferencia                                         | 35                                                  |
| `target_account`      | Object | Conta destino - Só deve ser enviada em transações do tipo "manual"                | **[Objeto target_account](#objeto-target_account)** |
| `refusal_reason`      | Object | Motivo da recusa de acordo com o padrão do Banco Central                          | **[Objeto refusal_reason](#objeto-refusal_reason)** |

## Enumerador ted_status

| Enumerador   | Descrição                                |
|--------------|------------------------------------------|
| **received** | Transferência TED recebida com sucesso.  |
| **pending**  | Transferência TED pendente.              |
| **rejected** | Transferência TED rejeitada.             |

## Objeto target_account

| Campo                     | Tipo   | Descrição                                           | Caracteres                                              |
|---------------------------|--------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string | Agência.                                            | 10                                                      |
| `account_digit` *         | string | Dígito da conta                                     | 10                                                      |
| `account_number` *        | string | Número da conta.                                    | 10                                                      |
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta.   | 14                                                      |
| `owner_name` *            | string | Nome do titular da conta.                           | 50                                                      |
| `account_type`*           | string | Tipo da conta.                                      | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string | Base no CNPJ da instituição financeira (8 dígitos). | 8                                                       |

## Objeto refusal_reason

| Campo           | Tipo   | Descrição                  | Caracteres |
|-----------------|--------|----------------------------|------------|
| `bacen_code` *  | string | Código de recusa Bacen     | 3          |
| `enumerator` *  | string | Enumerador da recusa Bacen | 100        |
| `description` * | string | Descrição da recusa Bacen  | 100        |

## Enumerador account_type

| Enumerador         | Tradução              |
|--------------------|-----------------------|
| checking_account   | conta corrente        |
| deposit_account    | conta depósito        |
| guaranteed_account | conta de garantia     |
| investment_account | conta de investimento |
| payment_account    | conta de pagamento    |
| saving_account     | conta poupança        |

---

# baas_consulta_documents

URL: /documentation/baas/upload_de_documentos/baas_consulta_documents



---

# baas_upload_de_documentos

URL: /documentation/baas/upload_de_documentos/



---

# Aprovar o pagamento de um Boleto

URL: /documentation/boletos/2fa/realizar_pagamento_de_um_boleto

Para realizar o pagamento de um Boleto é necessário realizar duas chamadas: 

1. Solicitação de token de validação de transferência: /baas/token_request

2. Aprovação da transferência: /baas/movement_validation

:::info
O Token enviado deve ser informado no momento da aprovação do pagamento do boleto, e o “***movement_payload***” deve ser o mesmo informado no momento da solicitação do Token.
:::

## Request

MÉTODO POST
ENDPOINT /baas/movement_validation

Request Body

```json
{
    "token": "358192",
    "movement_payload": {
        "resource_account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
        "digitable_line": "32990001031000699926165000000201993810000003500"
    }
}

```

## Body Params
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `token` * | string | Token de autenticação | 6 |
| `agent_document_number` * | string | CPF do usuário que irá receber o token. (Apenas números) | 11 | 
| `movement_payload` | Object | Payload contendo as informações da transferência | **[Objeto movement_payload](#objeto-movement_payload)** | 

### Objeto movement_payload

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `resource_account_key` * | uuuidv4 | Chave única de identificação da conta que irá realizar o pagamento | 36 |
| `digitable_line` * | float |  Linha digitável do boleto | 47 |

## Response

STATUS 200

Response Body

```json
{
    "movement_info": {
        "origin": {
            "account": "42863",
            "branch": "0001",
            "digit": "0",
            "document": "73685224000239",
            "name": "Empresa de Teste",
            "financialInstitution": "QI Sociedade de Crédito Direto S.A."
        },
          "faceValue": "2185.0",
          "amount": "2185.0",
          "dueDate": "2024-04-18T03:00:00.000Z",
          "type": "bank_slip_payment",
          "digitableLine": "32990001031000699926165000000201993810000003500",
          "barCode": "00191969000002185000000001120035240112154117",
          "destination": {
            "document": "05626796000106",
            "guarantorName": null,
            "name": "Beneficiário do Boleto",
            "guarantorDocument": null,
            "bank": "QI Sociedade de Crédito Direto S.A."
          }
        },
        "account_key": "0000000-0000-0000-0000-000000000000",
        "transaction_key": "0000000-0000-0000-0000-000000000000",
        "movement_status": "approved",
        "schedule_key": null,
        "movement_amount": 2185,
        "origin_key": null,
        "transacted_at_br": "2024-04-18 09:50:38-03:00",
        "requester_user_key": "0000000-0000-0000-0000-000000000000",
        "requester_key": "0000000-0000-0000-0000-000000000000",
        "movement_request_key": "0000000-0000-0000-0000-000000000000",
        "movement_date": "2024-04-18",
        "approval_feedback": true,
        "movement_type": "bank_slip_payment",
        "movement_data": {
          "transaction_key":  "0000000-0000-0000-0000-000000000000",
          "resource_account_key": "0000000-0000-0000-0000-000000000000",
          "digitable_line": "32990001031000699926165000000201993810000003500"
        },
        "transacted_at": "2024-04-18 12:50:38"
    }
```

---

# Solicitar token para pagamento de um Boleto

URL: /documentation/boletos/2fa/solicitar_token_para_pagamento

Para realizar o pagamento de um Boleto é necessário realizar duas chamadas: 

1. Solicitação de token de validação de transferência: /baas/token_request

2. Aprovação da transferência: /baas/movement_validation

## Request

- MÉTODO POST
- ENDPOINT /baas/token_request

Request Body

```json
{
    "contact_type": "email",
    "agent_document_number": "97564480084",
    "movement_payload": {
        "resource_account_key": "6d3089b1-cb90-4ceb-b1ea-5bd600cdf3c8",
        "digitable_line": "32990001031000699926165000000201993810000003500"
    }
}
```

## Body Params
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `contact_type` * | string | Forma de envio do token de autenticação,  podendo ser via E-mail (“email”) ou SMS (“sms”)| 10 |
| `agent_document_number` * | string | CPF do usuário que irá receber o token. (Apenas números) | 11 | 
| `movement_payload` | Object | Payload contendo as informações da transferência | **[Objeto movement_payload](#objeto-movement_payload)** | 

### Objeto movement_payload

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `resource_account_key` * | uuuidv4 | Chave única de identificação da conta que irá realizar o pagamento | 36 |
| `digitable_line` * | float |  Linha digitável do boleto | 47 |

## Response

STATUS 200

Response Body
```json
{}
```

---

# Criar carteira

URL: /documentation/boletos/carteira/criar_carteira

:::danger Importante
Para registrar bolePix, é necessário que exista uma chave Pix aleatória ativa na conta em que os boletos serão registrados.
:::

As carteiras de boleto possuem um código de identificação único (`requester_profile_code`) e configurações padrão específicas de pagamento, baixa, protesto etc. do boleto. Uma mesma conta pode ter várias carteiras de boleto, o que permite ao usuário criar várias carteiras com configurações padrão diferente. Tal dinâmica facilita a geração de boletos, com diferentes configurações, de maneira mais ágil e automática.

:::info Informação
Para todas as contas, é criada uma carteira de boletos com as configurações padrão do cliente. Esse padrão de configurações pode ser alterado entrando em contato com nosso suporte (suporte.baas@qitech.com.br). Após a criação da conta, é possível alterar também as tarifas da conta utilizando o [**endpoint de configuração de tarifas**](/documentation/contas/consulta_de_tarifas).
:::

:::caution Atenção!
A criação de carteiras de boletos é um fluxo assíncrono. Após a aprovação/rejeição da criação da carteira pela CIP/Nuclea, o solicitante será notificado via [**webhook**](/documentation/boletos/v2/webhooks/carteira) sobre o resultado de tal solicitação.
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile
MÉTODO POST

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |

Request Body

```json
{
  "request_control_key": "0868a24b-4a69-4138-ac4d-ecaeddf0005f",
  "configuration_data": {
    "max_payment_days": 1,
    "protest_settings": {
      "days_to_protest": 0
    },
    "bankruptcy_protest_settings": {
      "days_to_bankruptcy_protest": 0
    },
    "write_off_settings": {
      "days_to_write_off": 0
    },
    "fine_settings": {
      "fine_type": "absolute",
      "fine_amount": 10,
      "days_to_fine": 0
    },
    "interest_settings": {
      "interest_type": "workdays_daily_amount",
      "interest_amount": 10,
      "days_to_interest": 0
    },
    "qr_code_settings": {
      "pix_key": "5df7a433-bd61-4f98-9515-df9aedc2980c",
      "qr_code_on_discharge_enabled": false
    },
    "cnab_settings": {
      "default_bank": "qi_scd",
      "preferred_layout": "400"
    }
  }
}
```

### Request Body Params

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` *    | uuidv4  | Chave única de identificação da request utilizada pelo cliente no formato uuid v4  | 36         |
| `configuration_data` *     | object  | Configurações padrão da carteira  | **[Objeto configuration_data](#objeto-configuration_data)** |

### Objeto configuration_data

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `max_payment_days` *      | integer | Máximo de dias corridos que o boleto ficará disponível para pagamento, após o vencimento (pode ser no máximo 365) | -          |
| `write_off_settings`       | object  | Configuração padrão de baixa      | **[Objeto write_off_settings](#objeto-write_off_settings)** |
| `protest_settings`         | object  | Configuração padrão de protesto       | **[Objeto protest_settings](#objeto-protest_settings)** |
| `bankruptcy_protest_settings` | object  | Configuração padrão de protesto falimentar | **[Objeto bankruptcy_protest_settings](#objeto-bankruptcy_protest_settings)** |
| `fine_settings`            | object  | Configuração padrão de multa                 | **[Objeto fine_setings](#objeto-fine_settings)** |
| `interest_settings`        | object  | Configuração padrão de juros        | **[Objeto interest_settings](#objeto-interest_settings)** |
| `qr_code_settings`         | object  | Configuração padrão de QR Code PIX (para bolePix) | **[Objeto qr_code_settings](#objeto-qr_code_settings)** |
| `cnab_settings`            | object  | Configuração padrão de arquivos CNAB | **[Objeto cnab_settings](#objeto-cnab_settings)** |

### Objeto write_off_settings

| Campo                     | Tipo    | Descrição                                                                   | Caracteres |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_write_off` *     | integer | Dias, após o vencimento, para que o boleto seja baixado automaticamente     | -          |

### Objeto protest_settings
| Campo                     | Tipo    | Descrição                                                                   | Caracteres |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_protest` *       | integer | Dias, após o vencimento, para que o boleto seja protestado automaticamente  | -          |

### Objeto bankruptcy_protest_settings

| Campo                          | Tipo    | Descrição                                                                   | Caracteres  |
|--------------------------------|---------|-----------------------------------------------------------------------------|-------------|
| `days_to_bankruptcy_protest` * | integer | Dias, após o vencimento, para que seja iniciado um processo de protesto falimentar automaticamente  | -           |

### Objeto fine_settings

Opção 1: multa em valor absoluto (`fine_type=absolute`)

| Campo                     | Tipo    | Descrição                                               | Caracteres                |
|---------------------------|---------|---------------------------------------------------------|-------------------------------------------------------------------------|
| `fine_type` *             | string  | Tipo da multa                                                       | **[Enumeradores fine_type](#enumeradores-fine_type)**                                              |
| `fine_amount` *           | float   | Valor absoluto da multa                                             | -                                                                        |
| `days_to_fine` *          | integer | Dias, após o vencimento, para que a multa seja cobrada              | -                                                                        |

Opção 2: multa em valor percentual (`fine_type=percentage`)

| Campo                     | Tipo    | Descrição                                                 | Caracteres                             |
|---------------------------|---------|-----------------------------------------------------------|---------------------------------------|
| `fine_type` *             | string  | Tipo da multa                                             | **[Enumeradores fine_type](#enumeradores-fine_type)** |
| `fine_percentage` *       | integer | Valor percentual da multa, de 1 a 100                     | -                                      |
| `days_to_fine` *          | integer | Dias, após o vencimento, para que a multa seja cobrada    | -                                      |

### Enumeradores fine_type

| Enumerador         | Descrição             |
|--------------------|-----------------------|
| absolute           | valor absoluto        |
| percentage         | valor percentual      |

### Objeto interest_settings

Opção 1: juros utilizando valores absolutos (`interest_type=calendar_days_daily_amount` ou `interest_type=workdays_daily_amount`)

| Campo                     | Tipo    | Descrição                                                                     | Caracteres                                                                                      |
|---------------------------|---------|-------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| `interest_type` *         | string  | Tipo de juros       | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_amount` *       | float   | Valor a ser cobrado por unidade de tempo determinada (dias úteis ou corridos) | -                                                                                               |
| `days_to_interest` *      | integer | Dias, após o vencimento, para que comece a cobrar os juros                    | -                                                                                               |

Opção 2: juros utilizando valores percentuais (`interest_type=calendar_days_monthly_percentage`)

| Campo                    | Tipo    | Descrição                                                                             | Caracteres                                                                                          |
|--------------------------|---------|---------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
| `interest_type` *        | string  | Tipo de juros       | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_percentage` *  | integer | Porcentagem a ser cobrada por unidade de tempo determinada (dias úteis ou corridos)                                                                      | -                                                                           |
| `days_to_interest` *     | integer | Dias, após o vencimento, para que comece a cobrar os juros                             | -                                                                                                   |

### Enumeradores interest_type

| Enumerador                       | Descrição                                                            |
|----------------------------------|----------------------------------------------------------------------|
| calendar_days_daily_amount       | Valor diário sobre dias corridos                                     |
| workdays_daily_amount            | Valor diário sobre dias úteis                                        |
| calendar_days_monthly_percentage | Porcentagem de juros cobrados mensalmente, com base em dias corridos |

### Objeto qr_code_settings

| Campo                            | Tipo    | Descrição                                                                   | Caracteres  |
|----------------------------------|---------|-----------------------------------------------------------------------------|-------------|
| `pix_key` *                      | uuidv4  | Chave Pix do tipo aleatória                                                 | 36          |
| `qr_code_on_discharge_enabled` * | boolean | Determina se as informações do QR Code constarão no arquivo retorno (CNAB)  | -           |

:::info Informação
O PIX copia e cola será retornado no arquivo CNAB na posição 029 a 105.
:::

:::caution Atenção!
Caso o objeto `qr_code_settings` seja enviado na request, essa carteira terá como configuração padrão a geração de bolePix. BolePix são boletos cujo pagamento é vinculado a um QR Code Pix. Sendo assim, o pagador pode realizar o pagamento dos boletos tanto utilizando as linhas digitáveis dos mesmos, quanto através da leitura dos QR Codes Pix vinculados. Caso o pagamento seja feito via QR Code, a liquidação financeira se dá instantaneamente. Já em relação às notificações, são enviados dois webhooks: um no ato da transferência PIX (aviso de pagamento, boleto vai para o status `payment_notice`); e outro alguns segundos ou minutos depois, após a confirmação da baixa na CIP/Nuclea (pago, boleto vai para o status `paid`).
:::

### Objeto cnab_settings

| Campo                            | Tipo    | Descrição                                                                   | Caracteres  |
|----------------------------------|---------|-----------------------------------------------------------------------------|-------------|
| `default_bank`                   | string  | Layout do banco padrão para processamento de arquivos CNAB                            | **[Enumeradores default_bank](#enumeradores-default_bank)** |
| `preferred_layout`               | string  | Layout preferido para arquivos CNAB                                         | **[Enumeradores preferred_layout](#enumeradores-preferred_layout)** |

### Enumeradores default_bank

| Enumerador         | Descrição             |
|--------------------|-----------------------|
| santander          | Banco Santander       |
| itau               | Banco Itaú            |
| bradesco           | Banco Bradesco        |
| qi_scd             | QI SCD                |

### Enumeradores preferred_layout

| Enumerador         | Descrição             |
|--------------------|-----------------------|
| 400                | Layout CNAB 400       |
| 240                | Layout CNAB 240       |

## Response

STATUS 202

Response Body

```json
{
  "requester_profile_key": "fd86d9b1-2a5e-4e03-9a59-a043c7632c97",
  "requester_profile_code": "329-04-2338-2625918",
  "request_control_key": "0868a24b-4a69-4138-ac4d-ecaeddf0005f",
  "account_key": "0494902f-b21c-4ae6-b37e-854cfe883402",
  "requester_profile_status": "pending",
  "configuration_data": {
    "max_payment_days": 1,
    "protest_settings": {
      "days_to_protest": 0
    },
    "bankruptcy_protest_settings": {
      "days_to_bankruptcy_protest": 0
    },
    "write_off_settings": {
      "days_to_write_off": 0
    },
    "fine_settings": {
      "fine_type": "absolute",
      "fine_amount": 10,
      "days_to_fine": 0
    },
    "interest_settings": {
      "interest_type": "workdays_daily_amount",
      "interest_amount": 10,
      "days_to_interest": 0
    },
    "qr_code_settings": {
      "pix_key": "5df7a433-bd61-4f98-9515-df9aedc2980c",
      "qr_code_on_discharge_enabled": false
    },
    "cnab_settings": {
      "default_bank": "qi_scd",
      "preferred_layout": "400"
    }
  }
}

```

### Response Body Params

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `requester_profile_key` *  | uuidv4  | Chave única de identificação da carteira no formato uuid v4  | 36      |
| `requester_profile_code` * | string  | Código único de identificação da carteira                    | 19      |
| `request_control_key` *    | uuidv4  | Chave única de identificação da request utilizada pelo cliente no formato uuid v4 | 36 |
| `account_key` *            | uuidv4  | Chave única de identificação da conta no formato uuid v4 | 36 |
| `requester_profile_status` * | string | Status da carteira | **[Enumeradores requester_profile_status](#enumeradores-requester_profile_status)** |
| `configuration_data` * | object | Configurações padrão da carteira | **[Objeto configuration_data](#objeto-configuration_data)** |

### Enumeradores profile_status

| Enumerador                       | Descrição                                                            |
|----------------------------------|----------------------------------------------------------------------|
| pending                          | Carteira aceita e pendente de confirmação                            |

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 404                      | BKS000001            | Not Found | Person not found with key: {`person_key`}`                                               | Pessoa não encontrada com a chave: {`person_key`}`                                               |
| 404                      | BKS000004            | Not Found | Pix key not found: `{pix_key}`                                               | Chave pix não encontrada: `{pix_key}`                                               |
| 403                      | BKS000005            | Forbidden                         | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404                      | BKS000006            | Not Found                                  | The source account key was not found.                                                                                | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                  | It was not possible to consult the source account at this time. Please try again in a few minutes.                                                                                      | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                                                                                    |
| 400                      | BKS000008            | Bad Request | The source account is closed.         |               A conta de origem está fechada.                                                                 |
| 400                      | BKS000009            | Bad Request | The source account is blocked.         |               A conta de origem está bloqueada.                                                                 |
| 403                      | BKS000010            | Forbidden                                 | The pix key owner does not match the account owner.                                                                                     | O proprietário da chave pix não corresponde ao proprietário da conta.                                                             |
| 409                      | BKS000014            | Conflict           | Request control key already sent or duplicated sent: `{request_control_key}`                                                              | Chave de controle da requisição já utilizada ou enviada duplicada: `{request_control_key}`                                                                        |
| 400                      | BKS000047            | Bad Request             | It was not possible to consult the sent pix key at this time. Please try again in a few minutes.          | Não foi possível consultar a chave pix enviada no momento. Por favor, tente novamente em alguns minutos.                                                           |

---

# Editar carteira

URL: /documentation/boletos/carteira/editar_carteira

A edição de carteira sobrepõe as configurações padrão (`configuration_data`) da carteira de boletos e todos os seus objetos filhos.

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY
MÉTODO PUT

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36         |

Request Body

```json
{
  "max_payment_days": 1,
  "protest_settings": {
    "days_to_protest": 0
  },
  "bankruptcy_protest_settings": {
    "days_to_bankruptcy_protest": 0
  },
  "write_off_settings": {
    "days_to_write_off": 0
  },
  "fine_settings": {
    "fine_type": "absolute",
    "fine_amount": 10,
    "days_to_fine": 0
  },
  "interest_settings": {
    "interest_type": "workdays_daily_amount",
    "interest_amount": 10,
    "days_to_interest": 0
  },
  "qr_code_settings": {
    "pix_key": "248ebea3-9bdd-44b3-a8b9-7f2bd34cd7bf",
    "qr_code_on_discharge_enabled": false
  },
  "cnab_settings": {
    "default_bank": "qi_scd",
    "preferred_layout": "400"
  }
}
```

### Request Body Params

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `max_payment_days` *      | integer | Máximo de dias corridos que o boleto ficará disponível para pagamento, após o vencimento (pode ser no máximo 365) | -          |
| `write_off_settings`       | object  | Configuração padrão de baixa      | **[Objeto write_off_settings](#objeto-write_off_settings)** |
| `protest_settings`         | object  | Configuração padrão de protesto       | **[Objeto protest_settings](#objeto-protest_settings)** |
| `bankruptcy_protest_settings` | object  | Configuração padrão de protesto falimentar | **[Objeto bankruptcy_protest_settings](#objeto-bankruptcy_protest_settings)** |
| `fine_settings`            | object  | Configuração padrão de multa                 | **[Objeto fine_setings](#objeto-fine_settings)** |
| `interest_settings`        | object  | Configuração padrão de juros        | **[Objeto interest_settings](#objeto-interest_settings)** |
| `qr_code_settings`         | object  | Configuração padrão de QR Code PIX (para bolePix) | **[Objeto qr_code_settings](#objeto-qr_code_settings)** |
| `cnab_settings`            | object  | Configuração padrão de arquivos CNAB | **[Objeto cnab_settings](#objeto-cnab_settings)** |

### Objeto write_off_settings

| Campo                     | Tipo    | Descrição                                                                   | Caracteres |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_write_off` *     | integer | Dias, após o vencimento, para que o boleto seja baixado automaticamente     | -          |

### Objeto protest_settings
| Campo                     | Tipo    | Descrição                                                                   | Caracteres |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_protest` *       | integer | Dias, após o vencimento, para que o boleto seja protestado automaticamente  | -          |

### Objeto bankruptcy_protest_settings

| Campo                          | Tipo    | Descrição                                                                   | Caracteres  |
|--------------------------------|---------|-----------------------------------------------------------------------------|-------------|
| `days_to_bankruptcy_protest` * | integer | Dias, após o vencimento, para que seja iniciado um processo de protesto falimentar automaticamente  | -           |

### Objeto fine_settings

Opção 1: multa em valor absoluto (`fine_type=absolute`)

| Campo                     | Tipo    | Descrição                                               | Caracteres                |
|---------------------------|---------|---------------------------------------------------------|-------------------------------------------------------------------------|
| `fine_type` *             | string  | Tipo da multa                                                       | **[Enumeradores fine_type](#enumeradores-fine_type)**                                              |
| `fine_amount` *           | float   | Valor absoluto da multa                                             | -                                                                        |
| `days_to_fine` *          | integer | Dias, após o vencimento, para que a multa seja cobrada              | -                                                                        |

Opção 2: multa em valor percentual (`fine_type=percentage`)

| Campo                     | Tipo    | Descrição                                                 | Caracteres                             |
|---------------------------|---------|-----------------------------------------------------------|---------------------------------------|
| `fine_type` *             | string  | Tipo da multa                                             | **[Enumeradores fine_type](#enumeradores-fine_type)** |
| `fine_percentage` *       | integer | Valor percentual da multa, de 1 a 100                     | -                                      |
| `days_to_fine` *          | integer | Dias, após o vencimento, para que a multa seja cobrada    | -                                      |

### Enumeradores fine_type

| Enumerador         | Descrição             |
|--------------------|-----------------------|
| absolute           | valor absoluto        |
| percentage         | valor percentual      |

### Objeto interest_settings

Opção 1: juros utilizando valores absolutos (`interest_type=calendar_days_daily_amount` ou `interest_type=workdays_daily_amount`)

| Campo                     | Tipo    | Descrição                                                                     | Caracteres                                                                                      |
|---------------------------|---------|-------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| `interest_type` *         | string  | Tipo de juros       | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_amount` *       | float   | Valor a ser cobrado por unidade de tempo determinada (dias úteis ou corridos) | -                                                                                               |
| `days_to_interest` *      | integer | Dias, após o vencimento, para que comece a cobrar os juros                    | -                                                                                               |

Opção 2: juros utilizando valores percentuais (`interest_type=calendar_days_monthly_percentage`)

| Campo                    | Tipo    | Descrição                                                                             | Caracteres                                                                                          |
|--------------------------|---------|---------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
| `interest_type` *        | string  | Tipo de juros       | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_percentage` *  | integer | Porcentagem a ser cobrada por unidade de tempo determinada (dias úteis ou corridos)                                                                      | -                                                                           |
| `days_to_interest` *     | integer | Dias, após o vencimento, para que comece a cobrar os juros                             | -                                                                                                   |

### Enumeradores interest_type

| Enumerador                       | Descrição                                                            |
|----------------------------------|----------------------------------------------------------------------|
| calendar_days_daily_amount       | Valor diário sobre dias corridos                                     |
| workdays_daily_amount            | Valor diário sobre dias úteis                                        |
| calendar_days_monthly_percentage | Porcentagem de juros cobrados mensalmente, com base em dias corridos |

### Objeto qr_code_settings

| Campo                            | Tipo    | Descrição                                                                   | Caracteres  |
|----------------------------------|---------|-----------------------------------------------------------------------------|-------------|
| `pix_key` *                      | uuidv4  | Chave Pix do tipo aleatória                                                 | 36          |
| `qr_code_on_discharge_enabled` * | boolean | Determina se as informações do QR Code constarão no arquivo retorno (CNAB)  | -           |

:::info Informação
O PIX copia e cola será retornado no arquivo CNAB na posição 029 a 105.
:::

:::caution Atenção!
Caso o objeto `qr_code_settings` seja enviado na request, essa carteira terá como configuração padrão a geração de bolePix. BolePix são boletos cujo pagamento é vinculado a um QR Code Pix. Sendo assim, o pagador pode realizar o pagamento dos boletos tanto utilizando as linhas digitáveis dos mesmos, quanto através da leitura dos QR Codes Pix vinculados. Caso o pagamento seja feito via QR Code, a liquidação financeira se dá instantaneamente. Já em relação às notificações, são enviados dois webhooks: um no ato da transferência PIX (aviso de pagamento, boleto vai para o status `payment_notice`); e outro alguns segundos ou minutos depois, após a confirmação da baixa na CIP/Nuclea (pago, boleto vai para o status `paid`).
:::

### Objeto cnab_settings

| Campo                            | Tipo    | Descrição                                                                   | Caracteres  |
|----------------------------------|---------|-----------------------------------------------------------------------------|-------------|
| `default_bank`                   | string  | Layout do banco padrão para processamento de arquivos CNAB                            | **[Enumeradores default_bank](#enumeradores-default_bank)** |
| `preferred_layout`               | string  | Layout preferido para arquivos CNAB                                         | **[Enumeradores preferred_layout](#enumeradores-preferred_layout)** |

### Enumeradores default_bank

| Enumerador         | Descrição             |
|--------------------|-----------------------|
| santander          | Banco Santander       |
| itau               | Banco Itaú            |
| bradesco           | Banco Bradesco        |
| qi_scd             | QI SCD                |

### Enumeradores preferred_layout

| Enumerador         | Descrição             |
|--------------------|-----------------------|
| 400                | Layout CNAB 400       |
| 240                | Layout CNAB 240       |

## Response

STATUS 200

Response Body

```json
{
  "requester_profile_key": "c92e8666-e310-4a72-b15e-753525684ae2",
  "requester_profile_code": "329-48-2628-2625918",
  "request_control_key": "727a5f00-1f86-4a7a-9aa5-c45cf8a2394c",
  "account_key": "e0089187-ab08-42c0-82f2-259d40726117",
  "requester_profile_status": "pending",
  "configuration_data": {
    "max_payment_days": 1,
    "protest_settings": {
      "days_to_protest": 0
    },
    "bankruptcy_protest_settings": {
      "days_to_bankruptcy_protest": 0
    },
    "write_off_settings": {
      "days_to_write_off": 0
    },
    "fine_settings": {
      "fine_type": "absolute",
      "fine_amount": 10,
      "days_to_fine": 0
    },
    "interest_settings": {
      "interest_type": "workdays_daily_amount",
      "interest_amount": 10,
      "days_to_interest": 0
    },
    "qr_code_settings": {
      "pix_key": "248ebea3-9bdd-44b3-a8b9-7f2bd34cd7bf",
      "qr_code_on_discharge_enabled": false
    },
    "cnab_settings": {
      "default_bank": "qi_scd",
      "preferred_layout": "400"
    }
  }
}
```

### Response Body Params

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `requester_profile_key` *  | uuidv4  | Chave única de identificação da carteira no formato uuid v4  | 36      |
| `requester_profile_code` * | string  | Código único de identificação da carteira                    | 19      |
| `request_control_key` *    | uuidv4  | Chave única de identificação da request utilizada pelo cliente no formato uuid v4 | 36 |
| `account_key` *            | uuidv4  | Chave única de identificação da conta no formato uuid v4 | 36 |
| `requester_profile_status` * | string | Status da carteira | **[Enumeradores requester_profile_status](#enumeradores-requester_profile_status)** |
| `configuration_data` * | object | Configurações padrão da carteira | **[Objeto configuration_data](#objeto-configuration_data)** |

### Enumeradores profile_status

| Enumerador                       | Descrição                                                            |
|----------------------------------|----------------------------------------------------------------------|
| pending                          | Carteira aceita e pendente de confirmação                            |
| opened                           | Carteira aberta                                                      |

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 404                      | BKS000001            | Not Found | Person not found with key: {`person_key`}`                                               | Pessoa não encontrada com a chave: {`person_key`}`                                               |
| 404                      | BKS000004            | Not Found | Pix key not found: `{pix_key}`                                               | Chave pix não encontrada: `{pix_key}`                                               |
| 403                      | BKS000005            | Forbidden                         | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404                      | BKS000006            | Not Found                                  | The source account key was not found.                                                                                | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                  | It was not possible to consult the source account at this time. Please try again in a few minutes.                                                                                      | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                                                                                    |
| 400                      | BKS000008            | Bad Request | The source account is closed.         |               A conta de origem está fechada.                                                                 |
| 400                      | BKS000009            | Bad Request | The source account is blocked.         |               A conta de origem está bloqueada.                                                                 |
| 403                      | BKS000010            | Forbidden                                 | The pix key owner does not match the account owner.                                                                                     | O proprietário da chave pix não corresponde ao proprietário da conta.                                                             |
| 409                      | BKS000014            | Conflict           | Request control key already sent or duplicated sent: `{request_control_key}`                                                              | Chave de controle da requisição já utilizada ou enviada duplicada: `{request_control_key}`                                                                        |
| 400                      | BKS000047            | Bad Request             | It was not possible to consult the sent pix key at this time. Please try again in a few minutes.          | Não foi possível consultar a chave pix enviada no momento. Por favor, tente novamente em alguns minutos.                                                           |

---

# Listar carteiras da conta

URL: /documentation/boletos/carteira/listar_carteiras

A listagem de carteiras retornará todas as carteiras de boletos da conta que se enquadrarem nos query parameters enviados na request.

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profiles
MÉTODO GET

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |

### Query parameters

| Campo                    | Tipo   | Descrição                                                                 | Caracteres |
|--------------------------|--------|---------------------------------------------------------------------------|------------|
| `request_control_key`    | uuidv4 | Chave única de identificação da request, no formato uuid v4               | 36         |
| `requester_profile_key`  | uuidv4 | Chave única de identificação da carteira de boletos, no formato uuid v4   | 36         |
| `requester_profile_code` | string | Código único de identificação da carteira                                 | 19         |
| `page`                   | integer| Número da página                                                          | -          |
| `page_size`              | integer| Tamanho da página                                                         | -          |

## Response

STATUS 200

Response Body

```json
{
  "data": [
    {
      "requester_profile_key": "fd86d9b1-2a5e-4e03-9a59-a043c7632c97",
      "requester_profile_code": "329-04-2338-2625918",
      "request_control_key": "0868a24b-4a69-4138-ac4d-ecaeddf0005f",
      "account_key": "0494902f-b21c-4ae6-b37e-854cfe883402",
      "requester_profile_status": "pending",
      "configuration_data": {
        "max_payment_days": 1,
        "protest_settings": {
          "days_to_protest": 0
        },
        "bankruptcy_protest_settings": {
          "days_to_bankruptcy_protest": 0
        },
        "write_off_settings": {
          "days_to_write_off": 0
        },
        "fine_settings": {
          "fine_type": "absolute",
          "fine_amount": 10,
          "days_to_fine": 0
        },
        "interest_settings": {
          "interest_type": "workdays_daily_amount",
          "interest_amount": 10,
          "days_to_interest": 0
        },
        "qr_code_settings": {
          "pix_key": "5df7a433-bd61-4f98-9515-df9aedc2980c",
          "qr_code_on_discharge_enabled": false
        },
        "cnab_settings": {
          "default_bank": "qi_scd",
          "preferred_layout": "400"
        }
      }
    }
  ],
  "pagination": {
    "current_page": 1,
    "rows_per_page": 100
  }
}
```

### Response Body Parameters

| Campo          | Tipo         | Descrição                         | Caracteres                                                |
|----------------|--------------|-----------------------------------|-----------------------------------------------------------|
| `data` *       | object array | Carteiras de boletos              | **[Objeto requester_profile](#objeto-requester_profile)** |
| `pagination` * | object       | Informações de paginação          | **[Objeto pagination](#objeto-pagination)**               |

### Objeto requester_profile

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `requester_profile_key` *  | uuidv4  | Chave única de identificação da carteira no formato uuid v4  | 36      |
| `requester_profile_code` * | string  | Código único de identificação da carteira                    | 19      |
| `request_control_key` *    | uuidv4  | Chave única de identificação da request utilizada pelo cliente no formato uuid v4 | 36 |
| `account_key` *            | uuidv4  | Chave única de identificação da conta no formato uuid v4 | 36 |
| `requester_profile_status` * | string | Status da carteira | **[Enumeradores requester_profile_status](#enumeradores-requester_profile_status)** |
| `configuration_data` * | object | Configurações padrão da carteira | **[Objeto configuration_data](#objeto-configuration_data)** |

### Enumeradores requester_profile_status

| Enumerador                       | Descrição                                                            |
|----------------------------------|----------------------------------------------------------------------|
| pending                          | Carteira aceita e pendente de confirmação                            |
| opened                           | Carteira aberta                                                      |

### Objeto pagination

| Campo                      | Tipo    | Descrição                                                    | Caracteres |
|----------------------------|---------|--------------------------------------------------------------|------------|
| `current_page` *           | integer | Página atual                                                 | -          |
| `rows_per_page` *          | integer | Itens por página                                             | -          |

### Objeto configuration_data

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `max_payment_days` *      | integer | Máximo de dias corridos que o boleto ficará disponível para pagamento, após o vencimento (pode ser no máximo 365) | -          |
| `write_off_settings`       | object  | Configuração padrão de baixa      | **[Objeto write_off_settings](#objeto-write_off_settings)** |
| `protest_settings`         | object  | Configuração padrão de protesto       | **[Objeto protest_settings](#objeto-protest_settings)** |
| `bankruptcy_protest_settings` | object  | Configuração padrão de protesto falimentar | **[Objeto bankruptcy_protest_settings](#objeto-bankruptcy_protest_settings)** |
| `fine_settings`            | object  | Configuração padrão de multa                 | **[Objeto fine_setings](#objeto-fine_settings)** |
| `interest_settings`        | object  | Configuração padrão de juros        | **[Objeto interest_settings](#objeto-interest_settings)** |
| `qr_code_settings`         | object  | Configuração padrão de QR Code PIX (para bolePix) | **[Objeto qr_code_settings](#objeto-qr_code_settings)** |
| `cnab_settings`            | object  | Configuração padrão de arquivos CNAB | **[Objeto cnab_settings](#objeto-cnab_settings)** |

### Objeto write_off_settings

| Campo                     | Tipo    | Descrição                                                                   | Caracteres |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_write_off` *     | integer | Dias, após o vencimento, para que o boleto seja baixado automaticamente     | -          |

### Objeto protest_settings
| Campo                     | Tipo    | Descrição                                                                   | Caracteres |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_protest` *       | integer | Dias, após o vencimento, para que o boleto seja protestado automaticamente  | -          |

### Objeto bankruptcy_protest_settings

| Campo                          | Tipo    | Descrição                                                                   | Caracteres  |
|--------------------------------|---------|-----------------------------------------------------------------------------|-------------|
| `days_to_bankruptcy_protest` * | integer | Dias, após o vencimento, para que seja iniciado um processo de protesto falimentar automaticamente  | -           |

### Objeto fine_settings

Opção 1: multa em valor absoluto (`fine_type=absolute`)

| Campo                     | Tipo    | Descrição                                               | Caracteres                |
|---------------------------|---------|---------------------------------------------------------|-------------------------------------------------------------------------|
| `fine_type` *             | string  | Tipo da multa                                                       | **[Enumeradores fine_type](#enumeradores-fine_type)**                                              |
| `fine_amount` *           | float   | Valor absoluto da multa                                             | -                                                                        |
| `days_to_fine` *          | integer | Dias, após o vencimento, para que a multa seja cobrada              | -                                                                        |

Opção 2: multa em valor percentual (`fine_type=percentage`)

| Campo                     | Tipo    | Descrição                                                 | Caracteres                             |
|---------------------------|---------|-----------------------------------------------------------|---------------------------------------|
| `fine_type` *             | string  | Tipo da multa                                             | **[Enumeradores fine_type](#enumeradores-fine_type)** |
| `fine_percentage` *       | integer | Valor percentual da multa, de 1 a 100                     | -                                      |
| `days_to_fine` *          | integer | Dias, após o vencimento, para que a multa seja cobrada    | -                                      |

### Enumeradores fine_type

| Enumerador         | Descrição             |
|--------------------|-----------------------|
| absolute           | valor absoluto        |
| percentage         | valor percentual      |

### Objeto interest_settings

Opção 1: juros utilizando valores absolutos (`interest_type=calendar_days_daily_amount` ou `interest_type=workdays_daily_amount`)

| Campo                     | Tipo    | Descrição                                                                     | Caracteres                                                                                      |
|---------------------------|---------|-------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| `interest_type` *         | string  | Tipo de juros       | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_amount` *       | float   | Valor a ser cobrado por unidade de tempo determinada (dias úteis ou corridos) | -                                                                                               |
| `days_to_interest` *      | integer | Dias, após o vencimento, para que comece a cobrar os juros                    | -                                                                                               |

Opção 2: juros utilizando valores percentuais (`interest_type=calendar_days_monthly_percentage`)

| Campo                    | Tipo    | Descrição                                                                             | Caracteres                                                                                          |
|--------------------------|---------|---------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
| `interest_type` *        | string  | Tipo de juros       | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_percentage` *  | integer | Porcentagem a ser cobrada por unidade de tempo determinada (dias úteis ou corridos)                                                                      | -                                                                           |
| `days_to_interest` *     | integer | Dias, após o vencimento, para que comece a cobrar os juros                             | -                                                                                                   |

### Enumeradores interest_type

| Enumerador                       | Descrição                                                            |
|----------------------------------|----------------------------------------------------------------------|
| calendar_days_daily_amount       | Valor diário sobre dias corridos                                     |
| workdays_daily_amount            | Valor diário sobre dias úteis                                        |
| calendar_days_monthly_percentage | Porcentagem de juros cobrados mensalmente, com base em dias corridos |

### Objeto qr_code_settings

| Campo                            | Tipo    | Descrição                                                                   | Caracteres  |
|----------------------------------|---------|-----------------------------------------------------------------------------|-------------|
| `pix_key` *                      | uuidv4  | Chave Pix do tipo aleatória                                                 | 36          |
| `qr_code_on_discharge_enabled` * | boolean | Determina se as informações do QR Code constarão no arquivo retorno (CNAB)  | -           |

### Objeto cnab_settings

| Campo                            | Tipo    | Descrição                                                                   | Caracteres  |
|----------------------------------|---------|-----------------------------------------------------------------------------|-------------|
| `default_bank`                   | string  | Layout do banco padrão para processamento de arquivos CNAB                            | **[Enumeradores default_bank](#enumeradores-default_bank)** |
| `preferred_layout`               | string  | Layout preferido para arquivos CNAB                                         | **[Enumeradores preferred_layout](#enumeradores-preferred_layout)** |

### Enumeradores default_bank

| Enumerador         | Descrição             |
|--------------------|-----------------------|
| santander          | Banco Santander       |
| itau               | Banco Itaú            |
| bradesco           | Banco Bradesco        |
| qi_scd             | QI SCD                |

### Enumeradores preferred_layout

| Enumerador         | Descrição             |
|--------------------|-----------------------|
| 400                | Layout CNAB 400       |
| 240                | Layout CNAB 240       |

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (ptbr)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 404                      | BKS000006            | Not Found                                  | The source account key was not found.                                                                                | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                  | It was not possible to consult the source account at this time. Please try again in a few minutes.                                                                                      | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                                                                                    |
| 400                      | BKS000008            | Bad Request | The source account is closed.         |               A conta de origem está fechada.                                                                 |
| 400                      | BKS000009            | Bad Request | The source account is blocked.         |               A conta de origem está bloqueada.                                                                 |
| 400                      | BKS000012            | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
| 404                      | BKS000013            | Not Found | Requester profile not found         |               Carteira não encontrada                                                                 |
| 400                      | BKS000025            | Bad Request | Invalid bank slip status.      | Status de boleto inválido.                          |

---

# Consultar arquivo temporário

URL: /documentation/boletos/cnab/consulta_por_chave

A consulta de um arquivo CNAB temporário, utilizando sua chave, retorna informações detalhadas sobre o mesmo, como, por exemplo, a quantidade de ocorrências que já foram processadas e possíveis erros encontrados no arquivo.

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /temporary_cnab_file/ TEMPORARY_CNAB_FILE_KEY
MÉTODO GET

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36         |
| `temporary_cnab_file_key` | uuidv4 | Chave única de identificação do arquivo CNAB temporário, no formato uuid v4 | 36         |

## Response

STATUS 200

Response Body: Arquivo aceito (sem erros)

```json
{
  "temporary_cnab_file_key": "fa4f094d-8475-4828-9105-99756914e14f",
  "temporary_cnab_file_name": "240827463_t.REM",
  "temporary_cnab_file_status": "read",
  "occurrence_quantity": 6,
  "total_processed_occurrences": 6,
  "created_at": "2024-08-28T15:09:30Z"
}
```

Response Body: Arquivo rejeitado (com erros)

```json
{
  "temporary_cnab_file_key": "c16baa13-0969-46a7-a85f-6f975d266d9f",
  "temporary_cnab_file_name": "240905623.REM",
  "temporary_cnab_file_status": "rejected",
  "occurrence_quantity": 0,
  "total_processed_occurrences": 0,
  "created_at": "2024-09-10T15:59:25Z",
  "error_data": [
    {
      "code": "BKS000063",
      "title": "Bad Request",
      "description": "Invalid file code.",
      "translation": "Codigo de arquivo invalido.",
      "extra_fields": {
        "details": "Invalid file code. Expected: '1'. Got: '0'.",
        "file_line": 1,
        "details_pt_br": "Código de arquivo inválido. Esperado: '1'. Recebido: '0'.",
        "cnab_file_name": "240905623.REM",
        "cnab_inline_end_position": 2,
        "cnab_inline_start_position": 2
      }
    },
    {
      "code": "BKS000069",
      "title": "Bad Request",
      "description": "Invalid beneficiary account: beneficiary account is not the one that the requester profiles belongs to.",
      "translation": "Conta do beneficiario invalida: a conta do beneficiario nao e aquela a qual a carteira de boletos pertence.",
      "extra_fields": {
        "details": "Invalid beneficiary account header on header. Expected: '1927400'. Got: '3;53179'.",
        "file_line": 1,
        "details_pt_br": "Conta do beneficiário inválida no header. Esperado: '1927400'. Recebido: '3;53179'.",
        "cnab_file_name": "240905623.REM",
        "cnab_inline_end_position": 46,
        "cnab_inline_start_position": 40
      }
    },
    {
      "code": "BKS000064",
      "title": "Bad Request",
      "description": "Invalid bank code (014).",
      "translation": "Codigo do banco invalido (014).",
      "extra_fields": {
        "details": "Invalid bank code. Expected: '329'. Got: '014'",
        "bank_code": "014",
        "details_pt_br": "Código do banco inválido. Esperado: '329'. Recebido: '014'",
        "cnab_file_name": "240905623.REM"
      }
    },
    {
      "code": "BKS000056",
      "title": "Bad Request",
      "description": "Invalid record sequence.",
      "translation": "Sequencia invalida de registros.",
      "extra_fields": {
        "cnab_line": 1,
        "cnab_file_name": "240905623.REM"
      }
    },
    {
      "code": "BKS000056",
      "title": "Bad Request",
      "description": "Invalid record sequence.",
      "translation": "Sequencia invalida de registros.",
      "extra_fields": {
        "cnab_line": 2,
        "cnab_file_name": "240905623.REM"
      }
    },
    {
      "code": "BKS000086",
      "title": "Bad Request",
      "description": "File missing trailler record.",
      "translation": "Arquivo sem registro trailler.",
      "extra_fields": {
        "file_line": 3,
        "cnab_file_name": "240905623.REM"
      }
    }
  ]
}
```

### Response Body Params

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `temporary_cnab_file_key` *| uuidv4  | Chave única de identificação do arquivo CNAB temporário no formato uuid v4         | 36                                                |
| `temporary_cnab_file_name` *| uuidv4  | Nome do arquivo                                                                   | 100                                               |
| `temporary_cnab_file_status` *| string | Status do arquivo CNAB temporário | **[Enumeradores temporary_cnab_file_status](#enumeradores-temporary_cnab_file_status)** |
| `occurrence_quantity` *        | integer  | Quantidade de ocorrências no arquivo                                          | -                                                 |
| `total_processed_occurrences` *| integer  | Quantidade de ocorrências já processadas                                      | -                                                 |
| `error_data`                   | object array | Objetos, em JSON, dos erros encontrados no arquivo, no mesmo padrão retornado pelas APIs | **[Objeto error_data](#objeto-error_data)**                                                |
| `created_at` *                 | string   | Timestamp do horário de criação do arquivo na base de dados, no formato ISO Zulu | 20                                         |

### Enumeradores temporary_cnab_file_status

| Enumerador                   | Descrição                                                                    |
|------------------------------|------------------------------------------------------------------------------|
| uploaded                     | upload feito com sucesso, mas arquivo ainda não começou a ser processado     |
| processing                   | arquivo sendo lido                                                           |
| read                         | arquivo lido e aceito                                                        |
| rejected                     | arquivo lido e rejeitado por erro sintático                                  |

### Objeto error_data

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `code` *         | string  | Código do erro         | 9                                                |
| `title` *        | string  | Título do erro                                                                   | 100                                               |
| `description` *  | string  | Descrição do erro, em inglês | 100 |
| `translation` *  | integer | Tradução da descrição do erro                                          | 100                                               |
| `extra_fields`                 | object   | Informações adicionais sobre o erro | -                                         |

:::danger Importante
Os campos retornados no objeto `extra_fields` servem para fornecer informações adicionais sobre o erro e podem variar. Portanto, não devem ser mapeados de maneira restrita.
:::

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (ptbr)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 404                      | BKS000006            | Not Found                                  | The source account key was not found.                                                                                | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                  | It was not possible to consult the source account at this time. Please try again in a few minutes.                                                                                      | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                                                                                    |
| 400                      | BKS000008            | Bad Request | The source account is closed.         |               A conta de origem está fechada.                                                                 |
| 400                      | BKS000009            | Bad Request | The source account is blocked.         |               A conta de origem está bloqueada.                                                                 |
| 404                      | BKS000013            | Not Found | Requester profile not found         |               Carteira não encontrada                                                                 |
| 404                      | BKS000054            | Not Found | Remittance not found with key: `{temporary_cnab_file_key}`        |               Remessa não encontrada com a chave: `{temporary_cnab_file_key}`                                                                 |

---

# Arquivos remessa (CNAB) - Introdução

URL: /documentation/boletos/cnab/introducao

:::info
O arquivo transmitido nesta chamada deve seguir o padrão de Layout de Arquivo de Cobrança com 400 posições da QI Tech.
Segue link para download do manual: [Layout de Cobrança - QI Tech versão 2.1.](https://storage.googleapis.com/live-doc-api/public_samples/Layout%20de%20Cobran%C3%A7a%20-%20QI%20Tech%20v2.1.pdf)
:::

Os arquivos remessa (CNAB) oferecem a possibilidade de enviar várias instruções de registros de boleto, juntamente com outros tipos de instrução (extensão, abatimento, baixa etc.), para diferentes boletos, em um único arquivo. Ao enviar instruções como as mencionadas (extensão, abatimento etc.), para boletos já existentes, o boleto é identificado pelo código da carteira (`requester_profile_code`) e pelo nosso número (`our_number`).

Ao fazer o upload de um arquivo CNAB, caso a requisição tenha sucesso (código de resposta `202`), será criado um arquivo CNAB temporário (`TemporaryCNABFile`). É possível consultar o status de processamento do arquivo --- bem como possíveis erros, tanto no próprio arquivo quanto em suas ocorrências ---, utilizando os endpoints de [**consulta de arquivo CNAB temporário**](/documentation/boletos/cnab/consulta_por_chave) e [**suas ocorrências**](/documentation/boletos/cnab/listar_ocorrencias_temporarias).

O arquivo será rejeitado caso seja encontrado qualquer erro sintático. No entanto, ele é lido integralmente, ou até que sejam encontrados um limite de 100 erros, para que todos os erros possam ser retornados e corrigidos de maneira mais prática e eficiente.

Enquanto o arquivo é lido, são criadas ocorrências temporárias , que só serão processadas caso ele seja aceito. Ou seja, se o arquivo for rejeitado (status `rejected`), todas as suas ocorrências também serão . Ademais, se o arquivo for rejeitado, não são mais criadas ocorrências temporárias para o mesmo. Portanto, é comum que as entradas de arquivos rejeitados possuam menos ocorrências do que a quantidade de ocorrências enviada no arquivo.

Por outro lado, no momento em que o arquivo é totalmente lido e aceito (status `read`), inicia-se a criação das ocorrências definitivas, que serão as instruções que valerão de fato. Se uma ocorrência temporária apresenta o status `rejected` (rejeitada), significa que foi encontrado algum erro semântico na mesma --- ou seja, algum erro no seu conteúdo. Nesse caso, haverá um objeto `error_data` junto a mesma, que fornece detalhes acerca do motivo de rejeição. Em contrapartida, se apresentar o status `processed`, significa que a ocorrência definitiva já foi criada e enviada para a CIP/Nuclea. Maiores detalhes a respeito de cada uma dessas entidades são fornecidos nas páginas subsequentes, de consulta de arquivos e ocorrências temporárias.

:::tip Rateio de Crédito via CNAB
Para informar [**rateio de crédito**](/documentation/boletos/instrucoes/rateio_de_credito) (split de pagamento) em arquivos CNAB:

- **QI SCD (CNAB400 - layout QI Tech v2.1):** registro de detalhe com `identificacao_registro = 3`. Detalhes completos no **[Layout de Cobrança - QI Tech v2.1](https://storage.googleapis.com/live-doc-api/public_samples/Layout%20de%20Cobran%C3%A7a%20-%20QI%20Tech%20v2.1.pdf)**.
- **Bradesco (CNAB400 e CNAB240):** registro de detalhe tipo `3`.
- **Itaú (CNAB400 e CNAB240):** registro de detalhe tipo `4`.
- **Santander:** não suporta rateio de crédito via CNAB. Use o endpoint REST [**Atualização de Rateio de Crédito**](/documentation/boletos/instrucoes/rateio_de_credito) ou inclua `split_payment_data` na emissão via API.

**Como mapear N rateados:** Cada registro de rateio comporta até **3 contas adicionais** (número da conta + dígito + percentual). Para mais de 3 rateados, adicione **múltiplos registros de rateio em sequência** após o registro principal do boleto — eles são acumulados na mesma ocorrência. Exemplo: 7 contas = 3 registros (3 + 3 + 1).

**Restrições (todos os bancos):**
- Apenas o cálculo por **percentual** é suportado (`código de cálculo = 2`).
- A soma dos percentuais (beneficiário + rateios) deve ser exatamente **100**.
- Limite total de rateados respeita o mesmo da API REST (até 10 contas adicionais).
- O campo `beneficiary_max_amount` (rateio com valor máximo do beneficiário e excedente para a primeira regra) é **exclusivo da API REST**. Não é suportado via CNAB. Para esse cenário, use o endpoint REST de [**emissão**](/documentation/boletos/emissao/emissao_boleto_unico_padrao) ou de [**atualização de rateio de crédito**](/documentation/boletos/instrucoes/rateio_de_credito).
:::

---

# Listar arquivos remessa temporários

URL: /documentation/boletos/cnab/listar_arquivos_temporarios

A listagem de arquivos CNAB temporários retornará todos os arquivos CNAB temporários da carteira que se enquadrarem nos query parameters enviados na request.

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /temporary_cnab_file
MÉTODO GET

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36         |

### Query parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres              |
|-------------------------|--------|--------------------------------------------------------------|-------------------------|
| `temporary_cnab_file_status` | string | Status do arquivo CNAB temporário | **[Enumeradores temporary_cnab_file_status](#enumeradores-temporary_cnab_file_status)** |
| `page`                  | integer| Número da página                                             | -                       |
| `page_size`             | integer| Tamanho da página                                            | -                       |

### Enumeradores temporary_cnab_file_status

| Enumerador                   | Descrição                                                                    |
|------------------------------|------------------------------------------------------------------------------|
| uploaded                     | upload feito com sucesso, mas arquivo ainda não começou a ser processado     |
| processing                   | arquivo sendo lido                                                           |
| read                         | arquivo lido e aceito                                                        |
| rejected                     | arquivo lido e rejeitado por erro sintático                                  |

## Response

STATUS 200

Response Body

```json
{
  "data": [
    {
      "temporary_cnab_file_key": "a6db5f8b-1ed7-4d13-9cbf-f3c4275e3ca3",
      "temporary_cnab_file_name": "240903573.REM",
      "temporary_cnab_file_status": "processing",
      "occurrence_quantity": null,
      "created_at": "2024-09-07T15:44:01Z"
    },
    {
      "temporary_cnab_file_key": "2351c4ae-9a01-4675-86e4-099a30dafa42",
      "temporary_cnab_file_name": "240904603.REM",
      "temporary_cnab_file_status": "rejected",
      "occurrence_quantity": 0,
      "created_at": "2024-09-06T12:35:50Z"
    },
    {
      "temporary_cnab_file_key": "fa4f094d-8475-4828-9105-99756914e14f",
      "temporary_cnab_file_name": "240827463_t.REM",
      "temporary_cnab_file_status": "read",
      "occurrence_quantity": 10424,
      "created_at": "2024-08-28T15:09:30Z"
    },
    {
      "temporary_cnab_file_key": "e99cea6d-0d1c-4ec3-a2c6-bc603aede7c6",
      "temporary_cnab_file_name": "240827443_t.REM",
      "temporary_cnab_file_status": "read",
      "occurrence_quantity": 542,
      "created_at": "2024-08-27T20:07:11Z"
    },
    {
      "temporary_cnab_file_key": "2351c4ae-9a01-4675-86e4-099a30dafa42",
      "temporary_cnab_file_name": "240812604.REM",
      "temporary_cnab_file_status": "rejected",
      "occurrence_quantity": 0,
      "created_at": "2024-08-12T12:52:13Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "rows_per_page": 100
  }
}
```

### Response Body Params

| Campo            | Tipo         | Descrição                             | Caracteres                                  |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `data` *         | object array | Arquivos CNAB temporários             | **[Objeto temporary_cnab_file](#objeto-temporary_cnab_file)**   |
| `pagination` *   | object       | Informações de paginação              | **[Objeto pagination](#objeto-pagination)** |

### Objeto temporary_cnab_file

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `temporary_cnab_file_key` *| uuidv4  | Chave única de identificação do arquivo CNAB temporário no formato uuid v4         | 36                                                |
| `temporary_cnab_file_name` *| uuidv4  | Nome do arquivo                                                                   | 100                                               |
| `temporary_cnab_file_status` *| string | Status do arquivo CNAB temporário | **[Enumeradores temporary_cnab_file_status](#enumeradores-temporary_cnab_file_status)** |
| `occurrence_quantity` *        | integer  | Quantidade de ocorrências no arquivo                                          | -                                                 |
| `created_at` *                 | string   | Timestamp do horário de criação do arquivo na base de dados, no formato ISO Zulu | 20                                         |

### Objeto pagination

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `current_page` *           | integer | Página atual                                                 | -      |
| `rows_per_page` *          | integer | Itens por página                                             | -      |

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 403                      | BKS000005            | Forbidden                         | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404                      | BKS000006            | Not Found                                  | The source account key was not found.                                                                                | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                  | It was not possible to consult the source account at this time. Please try again in a few minutes.                                                                                      | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                                                                                    |
| 400                      | BKS000008            | Bad Request | The source account is closed.         |               A conta de origem está fechada.                                                                 |
| 400                      | BKS000009            | Bad Request | The source account is blocked.         |               A conta de origem está bloqueada.                                                                 |
| 400                      | BKS000012            | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
| 404                      | BKS000013            | Not Found | Requester profile not found         |               Carteira não encontrada                                                                 |

---

# Listar ocorrências temporárias

URL: /documentation/boletos/cnab/listar_ocorrencias_temporarias

A listagem de ocorrências temporárias retornará todas as ocorrências temporárias de um dado arquivo CNAB.

:::info
Quando no momento em que um arquivo CNAB é rejeitado por erro sintático, não são mais criadas ocorrências temporárias referentes ao mesmo, visto que todas seriam rejeitadas porque o arquivo foi rejeitado. Portanto, quando o arquivo é rejeitado, é possível que o número de ocorrências temporárias relacionadas ao arquivo seja menor que o número de ocorrências enviadas no mesmo.
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /temporary_cnab_file / TEMPORARY_CNAB_FILE_KEY /occurrences
MÉTODO GET

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36         |

### Query parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres              |
|-------------------------|--------|--------------------------------------------------------------|-------------------------|
| `occurrence_status`     | string | Status da ocorrência temporária                              | **[Enumeradores occurrence_status](#enumeradores-temporary_cnab_file_status)** |
| `occurrence_type`       | string | Tipo da ocorrência temporária                                | **[Enumeradores occurrence_type](#enumeradores-temporary_cnab_file_type)** |
| `page`                  | integer| Número da página                                             | -                       |
| `page_size`             | integer| Tamanho da página                                            | -                       |

### Enumeradores occurrence_status

| Enumerador                   | Descrição                                                                    |
|------------------------------|------------------------------------------------------------------------------|
| pending                      | ocorrência ainda não foi processada                                          |
| processed                    | ocorrência processada com sucesso                                            |
| rejected                     | ocorrência processada e rejeitada por erro semântico                         |

### Enumeradores occurrence_type

| Enumerador                           | Descrição                                                                    |
|--------------------------------------|------------------------------------------------------------------------------|
| registration                         | registro de boleto                                                           |
| write_off                            | baixa de boleto                                                              |
| rebate                               | abatimento de valor do boleto                                                |
| cancel_rebate                        | cancelamento de abatimento                                                   |
| extension                            | prorrogação da data de pagamento                                             |
| protest_request                      | pedido de protesto                                                           |
| bankruptcy_protest_request           | pedido de protesto falimentar                                                |
| protest_cancel_and_write_off_request | cancelamento de pedido de protesto e baixa do boleto                         |
| protest_cancel_request               | cancelamento de pedido de protesto                                           |
| bank_slip_edit                       | edição de demais dados do boleto                                             |

## Response

STATUS 200

Response Body

```json
{
    "data": [
        {
            "occurrence_key": "191f2220-1465-47d7-8c81-67d8f59f5af2",
            "occurrence_status": "rejected",
            "occurrence_type": "registration",
            "occurrence_our_number": 12455,
            "error_data": {
                "code": "BKS000069",
                "title": "Bad Request",
                "description": "Invalid beneficiary account: beneficiary account is not the one that the requester profiles belongs to.",
                "translation": "Conta do beneficiario invalida: a conta do beneficiario nao e aquela a qual a carteira de boletos pertence.",
                "extra_fields": {
                    "account_digit": "4",
                    "account_branch": "0001",
                    "account_number": "1927400"
                }
            }
        },
        {
            "occurrence_key": "adc0ce54-9e69-45ec-9220-fbfe0e3ba103",
            "occurrence_status": "rejected",
            "occurrence_type": "registration",
            "occurrence_our_number": 12453,
            "error_data": {
                "code": "BKS000069",
                "title": "Bad Request",
                "description": "Invalid beneficiary account: beneficiary account is not the one that the requester profiles belongs to.",
                "translation": "Conta do beneficiario invalida: a conta do beneficiario nao e aquela a qual a carteira de boletos pertence.",
                "extra_fields": {
                    "account_digit": "4",
                    "account_branch": "0001",
                    "account_number": "1927400"
                }
            }
        },
        {
            "occurrence_key": "0521c4db-b243-4599-af2f-c288a299948a",
            "occurrence_status": "rejected",
            "occurrence_type": "registration",
            "occurrence_our_number": 12452,
            "error_data": {
                "code": "BKS000069",
                "title": "Bad Request",
                "description": "Invalid beneficiary account: beneficiary account is not the one that the requester profiles belongs to.",
                "translation": "Conta do beneficiario invalida: a conta do beneficiario nao e aquela a qual a carteira de boletos pertence.",
                "extra_fields": {
                    "account_digit": "4",
                    "account_branch": "0001",
                    "account_number": "1927400"
                }
            }
        },
        {
            "occurrence_key": "f0875275-dea0-4e93-a665-a24e921d0a95",
            "occurrence_status": "rejected",
            "occurrence_type": "registration",
            "occurrence_our_number": 12451,
            "error_data": {
                "code": "BKS000069",
                "title": "Bad Request",
                "description": "Invalid beneficiary account: beneficiary account is not the one that the requester profiles belongs to.",
                "translation": "Conta do beneficiario invalida: a conta do beneficiario nao e aquela a qual a carteira de boletos pertence.",
                "extra_fields": {
                    "account_digit": "4",
                    "account_branch": "0001",
                    "account_number": "1927400"
                }
            }
        },
        {
            "occurrence_key": "98ac54d9-0b3c-45a6-86e1-4b79d25f6364",
            "occurrence_status": "rejected",
            "occurrence_type": "registration",
            "occurrence_our_number": 12450,
            "error_data": {
                "code": "BKS000069",
                "title": "Bad Request",
                "description": "Invalid beneficiary account: beneficiary account is not the one that the requester profiles belongs to.",
                "translation": "Conta do beneficiario invalida: a conta do beneficiario nao e aquela a qual a carteira de boletos pertence.",
                "extra_fields": {
                    "account_digit": "4",
                    "account_branch": "0001",
                    "account_number": "1927400"
                }
            }
        },
        {
            "occurrence_key": "dd2c8d76-d663-4dbb-9c8b-84a627156147",
            "occurrence_status": "rejected",
            "occurrence_type": "registration",
            "occurrence_our_number": 12449,
            "error_data": {
                "code": "BKS000069",
                "title": "Bad Request",
                "description": "Invalid beneficiary account: beneficiary account is not the one that the requester profiles belongs to.",
                "translation": "Conta do beneficiario invalida: a conta do beneficiario nao e aquela a qual a carteira de boletos pertence.",
                "extra_fields": {
                    "account_digit": "4",
                    "account_branch": "0001",
                    "account_number": "1927400"
                }
            }
        }
    ],
    "pagination": {
        "current_page": 1,
        "rows_per_page": 100
    }
}
```

### Response Body Params

| Campo            | Tipo         | Descrição                             | Caracteres                                  |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `data` *         | object array | Ocorrências temporárias               | **[Objeto temporary_occurrence](#objeto-temporary_occurrence)**   |
| `pagination` *   | object       | Informações de paginação              | **[Objeto pagination](#objeto-pagination)** |

### Objeto temporary_cnab_file

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `occurrence_key` *| uuidv4  | Chave única de identificação da ocorrência temporária no formato uuid v4         | 36                                                |
| `occurrence_status` * | string  | Status da ocorrência temporária                                                                   | **[Enumeradores temporary_occurrence_status](#enumeradores-temporary_occurrence_status)** |
| `occurrence_type` *   | string  | Tipo da ocorrência temporária | **[Enumeradores occurrence_type](#enumeradores-occurrence_type)** |
| `occurrence_our_number` *       | integer  | Quantidade de ocorrências no arquivo                                          | -                                                 |
| `error_data`                   | object | Objetos, em JSON, dos erros encontrados no arquivo, no mesmo padrão retornado pelas APIs | **[Objeto error_data](#objeto-error_data)**                                                |

### Objeto pagination

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `current_page` *           | integer | Página atual                                                 | -      |
| `rows_per_page` *          | integer | Itens por página                                             | -      |

### Objeto error_data

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `code` *         | string  | Código do erro         | 9                                                |
| `title` *        | string  | Título do erro                                                                   | 100                                               |
| `description` *  | string  | Descrição do erro, em inglês | 100 |
| `translation` *  | integer | Tradução da descrição do erro                                          | 100                                               |
| `extra_fields`                 | object   | Informações adicionais sobre o erro | -                                         |

:::danger Importante
Os campos retornados no objeto `extra_fields` servem para fornecer informações adicionais sobre o erro e podem variar. Portanto, não devem ser mapeados de maneira restrita.
:::

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 403                      | BKS000005            | Forbidden                         | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404                      | BKS000006            | Not Found                                  | The source account key was not found.                                                                                | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                  | It was not possible to consult the source account at this time. Please try again in a few minutes.                                                                                      | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                                                                                    |
| 400                      | BKS000008            | Bad Request | The source account is closed.         |               A conta de origem está fechada.                                                                 |
| 400                      | BKS000009            | Bad Request | The source account is blocked.         |               A conta de origem está bloqueada.                                                                 |
| 400                      | BKS000012            | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
| 404                      | BKS000013            | Not Found | Requester profile not found         |               Carteira não encontrada                                                                 |
| 404                      | BKS000054            | Not Found | Remittance not found with key: `{temporary_cnab_file_key}`        |               Remessa não encontrada com a chave: `{temporary_cnab_file_key}`                                                                 |

---

# Upload de arquivo remessa (CNAB)

URL: /documentation/boletos/cnab/upload_de_arquivo_remessa

:::caution Atenção!
A chamada deve ser autenticada seguindo o padrão descrito na seção de [**Upload de documentos**](/documentation/upload_de_documentos).
:::

Os arquivos remessa (CNAB) oferecem a possibilidade de enviar várias instruções de registros de boleto, juntamente com outros tipos de instrução (extensão, abatimento, baixa etc.), para diferentes boletos, em um único arquivo. Ao enviar instruções como as mencionadas (extensão, abatimento etc.), para boletos já existentes, o boleto é identificado pelo código da carteira (`requester_profile_code`) e pelo nosso número (`our_number`).

:::info
Ao fazer o upload de um arquivo CNAB, caso a requisição tenha sucesso (código de resposta `202`), será criado um arquivo CNAB temporário (`TemporaryCNABFile`). É possível consultar o status de processamento do arquivo --- bem como possíveis erros, tanto no próprio arquivo quanto em suas ocorrências ---, utilizando os endpoints de [**consulta de arquivo CNAB temporário**](/documentation/boletos/cnab/consulta_por_chave) e [**suas ocorrências**](/documentation/boletos/cnab/listar_ocorrencias_temporarias).
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /cnab_file
MÉTODO POST

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36         |

## Request Body Params

Deverão ser enviados os seguintes dados, como form-data , no body da request:

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `file` *                | file   | Arquivo CNAB no padrão estipulado pela QI Tech               | -          |

## Response

STATUS 202

Response Body

```json
{
  "temporary_cnab_file_key": "f14e9bac-94ed-4eb1-87b4-7fd7b7a2d280",
  "temporary_cnab_file_status": "accepted"
}
```

### Response Body Params

| Campo                          | Tipo    | Descrição                                                       | Caracteres                 |
|--------------------------------|---------|-----------------------------------------------------------------|----------------------------|
| `temporary_cnab_file_key` *    | uuidv4  | Chave única de identificação do arquivo CNAB no formato uuid v4 | 36                         |
| `temporary_cnab_file_status` * | string  | Status do arquivo CNAB | **[Enumeradores temporary_cnab_file_status](#enumeradores-cnab_file_status)** |

### Enumeradores temporary_cnab_file_status

| Enumerador | Descrição                                                                 |
|------------|---------------------------------------------------------------------------|
| uploaded   | Upload feito com sucesso, mas arquivo ainda não começou a ser processado  |
| processing | Arquivo sendo lido                                                        |
| read       | Arquivo lido e aceito                                                     |
| rejected   | Arquivo lido e rejeitado (todas as ocorrências do arquivo são rejeitadas) |

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (ptbr)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 404                      | BKS000006            | Not Found                                  | The source account key was not found.                                                                                | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                  | It was not possible to consult the source account at this time. Please try again in a few minutes.                                                                                      | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                                                                                    |
| 400                      | BKS000008            | Bad Request | The source account is closed.         |               A conta de origem está fechada.                                                                 |
| 400                      | BKS000009            | Bad Request | The source account is blocked.         |               A conta de origem está bloqueada.                                                                 |
| 404                      | BKS000013            | Not Found | Requester profile not found         |               Carteira não encontrada                                                                 |
| 400                      | BKS000022            | Bad Request                                        | Requester profile is not opened.                                                              | Carteira não está aberta.                          |
| 409                      | BKS000053            | Conflict                                           | CNAB file already received: '`<file_name>`'                                                   | Arquivo CNAB já recebido: '`<file_name>`'                          |

---

# Consulta de boleto por chave

URL: /documentation/boletos/consulta/consulta_por_chave

A consulta de um boleto, utilizando sua chave, retorna informações detalhadas sobre o mesmo, como, por exemplo, todas as instruções referentes àquele boleto.

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY
MÉTODO GET

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36         |
| `bank_slip_key`         | uuidv4 | Chave única de identificação do boleto, no formato uuid v4   | 36         |

## Response

STATUS 200

Response Body

```json
{
  "bank_slip_key": "4c2fa514-a44d-40f2-8d57-c0caf1b9165a",
  "request_control_key": "0dcb3182-4d7e-4526-8f92-c15cdbc51bad",
  "our_number": 26652176735,
  "document_number": "DOC4561237",
  "amount": "5000.00",
  "rebate_amount": "0.00",
  "expiration": "2024-07-12",
  "barcode": "32994978900005000000001546128483498231955340",
  "digitable_line": "32990001524612848349582319553408497890000500000",
  "bank_teller_instructions": "Confirm payment",
  "protest_data": {
    "days_to_protest": 7
  },
  "bankruptcy_protest_data": {
    "days_to_bankruptcy_protest": 14
  },
  "max_payment_days": 45,
  "fine_data": {
    "fine_type": "absolute",
    "fine_amount": 100.0,
    "days_to_fine": 10
  },
  "interest_data": {
    "interest_type": "workdays_daily_amount",
    "interest_amount": 10.0,
    "days_to_interest": 2
  },
  "discounts_data": [
    {
      "discount_type": "absolute",
      "discount_amount": 50.0,
      "discount_number": 1,
      "discount_limit_date": "2024-07-12"
    }
  ],
  "payer_data": {
    "name": "Global Tech",
    "address": {
      "city": "Innovation City",
      "state": "SP",
      "number": "202",
      "street": "101 High St.",
      "complement": "Building A",
      "postal_code": "57099999",
      "neighborhood": "Tech Park"
    },
    "person_type": "legal",
    "document_number": "12345678000195"
  },
  "guarantor_data": {
    "name": "Jane Doe",
    "address": {
      "city": "Peaceful Town",
      "state": "RJ",
      "number": "303",
      "street": "202 Elm St.",
      "complement": "House 1",
      "postal_code": "57099999",
      "neighborhood": "Quiet Neighborhood"
    },
    "person_type": "natural",
    "document_number": "23456789012"
  },
  "qr_code_data": {
    "qr_code_key": "58bd3558-f214-4e83-9c88-1ac4c93db214",
    "pix_key": "f9b05a58-9dcf-49cb-bc7f-99c5b3f1fdcb",
    "receiver_conciliation_id": "a3861b53f5414b0ba6c9f800d7374474",
    "url": "00020126890014br.gov.bcb.pix2567qrcode-h.dev.qitech.app/bacen/cobv/a3861b53f5414b0ba6c9f800d73744745204000053039865802BR5922BeatrizCoutodeCarvalho6012SAOJOSEDORIO61081501410062070503***6304ED95",
    "image": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAALCAD0APQBAREA/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/9oACAEBAAA/APf6KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK+QPhl8Mv+Fjf2p/xN/wCz/sHlf8u3m79+/wD21xjZ79a7/wD4Zl/6m7/ym/8A22j/AIZl/wCpu/8AKb/9to/Zl/5mn/t0/wDa1H7TX/Mrf9vf/tGj9mX/AJmn/t0/9rVwHwy+Jv8Awrn+1P8AiUf2h9v8r/l58rZs3/7DZzv9ule//DL4Zf8ACuf7U/4m/wDaH2/yv+Xbytmzf/ttnO/26V5//wAMy/8AU3f+U3/7bR+01/zK3/b3/wC0a9A+JvxN/wCFc/2X/wASj+0Pt/m/8vPlbNmz/YbOd/t0o+JvxN/4Vz/Zf/Eo/tD7f5v/AC8+Vs2bP9hs53+3SvAPhl8Mv+Fjf2p/xN/7P+weV/y7ebv37/8AbXGNnv1r3/4m/E3/AIVz/Zf/ABKP7Q+3+b/y8+Vs2bP9hs53+3Sj4m/DL/hY39l/8Tf+z/sHm/8ALt5u/fs/21xjZ79a8A+Jvwy/4Vz/AGX/AMTf+0Pt/m/8u3lbNmz/AG2znf7dK+v6+QPib8Tf+Fjf2X/xKP7P+web/wAvPm79+z/YXGNnv1rv/wBpr/mVv+3v/wBo16B8Tfhl/wALG/sv/ib/ANn/AGDzf+Xbzd+/Z/trjGz3615//wAm5/8AUw/27/26eR5H/fzdu872xt7544D4ZfE3/hXP9qf8Sj+0Pt/lf8vPlbNm/wD2Gznf7dK+v6+QPhl8Mv8AhY39qf8AE3/s/wCweV/y7ebv37/9tcY2e/Wu/wD+GZf+pu/8pv8A9to/4Zl/6m7/AMpv/wBto/Zl/wCZp/7dP/a1fQFFFFfP/wCzL/zNP/bp/wC1q8Ar3/8AZl/5mn/t0/8Aa1H7Mv8AzNP/AG6f+1q4D4ZfDL/hY39qf8Tf+z/sHlf8u3m79+//AG1xjZ79a9/+GXxN/wCFjf2p/wASj+z/ALB5X/Lz5u/fv/2FxjZ79a8A+GXwy/4WN/an/E3/ALP+weV/y7ebv37/APbXGNnv1r6/rz/4ZfE3/hY39qf8Sj+z/sHlf8vPm79+/wD2FxjZ79a8A+Jvwy/4Vz/Zf/E3/tD7f5v/AC7eVs2bP9ts53+3Svf/AIZfE3/hY39qf8Sj+z/sHlf8vPm79+//AGFxjZ79a9Arz/4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3SvP/2mv+ZW/wC3v/2jXAfE34m/8LG/sv8A4lH9n/YPN/5efN379n+wuMbPfrX1/XyB8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpX1/Xn/xN+GX/Cxv7L/4m/8AZ/2Dzf8Al283fv2f7a4xs9+tHxN+Jv8Awrn+y/8AiUf2h9v83/l58rZs2f7DZzv9uleAfDL4m/8ACuf7U/4lH9ofb/K/5efK2bN/+w2c7/bpXf8A/Jxn/Uvf2F/29+f5/wD3727fJ987u2OfQPhl8Tf+Fjf2p/xKP7P+weV/y8+bv37/APYXGNnv1rz/APZl/wCZp/7dP/a1eAV7/wDsy/8AM0/9un/taj9mX/maf+3T/wBrV9AUUUV8/wD7Mv8AzNP/AG6f+1qP+GZf+pu/8pv/ANtr0D4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3SvP/2Zf+Zp/wC3T/2tXAfDL4Zf8LG/tT/ib/2f9g8r/l283fv3/wC2uMbPfrXf/sy/8zT/ANun/taj/hmX/qbv/Kb/APbaP2Zf+Zp/7dP/AGtR/wAm5/8AUw/27/26eR5H/fzdu872xt754P8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPB/w01/1KP/AJUv/tVH/Juf/Uw/27/26eR5H/fzdu872xt7544D4ZfDL/hY39qf8Tf+z/sHlf8ALt5u/fv/ANtcY2e/Wu//AOGZf+pu/wDKb/8Aba8Ar6/+GXxN/wCFjf2p/wASj+z/ALB5X/Lz5u/fv/2FxjZ79a8A+Jvwy/4Vz/Zf/E3/ALQ+3+b/AMu3lbNmz/bbOd/t0r3/AOGXxN/4WN/an/Eo/s/7B5X/AC8+bv37/wDYXGNnv1rz/wD4Zl/6m7/ym/8A22vQPhl8Tf8AhY39qf8AEo/s/wCweV/y8+bv37/9hcY2e/WvP/8AhmX/AKm7/wApv/22j9mX/maf+3T/ANrV9AV8/wD7Mv8AzNP/AG6f+1qP+GZf+pu/8pv/ANtr0D4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3SvP/2Zf+Zp/wC3T/2tX0BRRRXz/wD8My/9Td/5Tf8A7bR/wzL/ANTd/wCU3/7bR/wzL/1N3/lN/wDttegfDL4Zf8K5/tT/AIm/9ofb/K/5dvK2bN/+22c7/bpXgHwy+Jv/AArn+1P+JR/aH2/yv+Xnytmzf/sNnO/26V7/APDL4Zf8K5/tT/ib/wBofb/K/wCXbytmzf8A7bZzv9ulHwy+GX/Cuf7U/wCJv/aH2/yv+Xbytmzf/ttnO/26UfDL4Zf8K5/tT/ib/wBofb/K/wCXbytmzf8A7bZzv9ulef8A/Juf/Uw/27/26eR5H/fzdu872xt7549A+GXwy/4Vz/an/E3/ALQ+3+V/y7eVs2b/APbbOd/t0o+GXwy/4Vz/AGp/xN/7Q+3+V/y7eVs2b/8AbbOd/t0rz/8AZl/5mn/t0/8Aa1H7Mv8AzNP/AG6f+1q9A+GXwy/4Vz/an/E3/tD7f5X/AC7eVs2b/wDbbOd/t0rwD4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Sj4ZfE3/hXP9qf8Sj+0Pt/lf8vPlbNm/wD2Gznf7dK7/wD5Nz/6mH+3f+3TyPI/7+bt3ne2NvfPHoHwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpR8Mvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9ulef/wDJuf8A1MP9u/8Abp5Hkf8Afzdu872xt754P2Zf+Zp/7dP/AGtXoHwy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulHwy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpXn/wDwzL/1N3/lN/8AttH/AAzL/wBTd/5Tf/ttH/DMv/U3f+U3/wC216B8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXoFFFFfIHwy+Jv8Awrn+1P8AiUf2h9v8r/l58rZs3/7DZzv9ulHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9ulef19f/DL4Zf8K5/tT/ib/wBofb/K/wCXbytmzf8A7bZzv9ulef8A7TX/ADK3/b3/AO0a+gK+QPib8Mv+Fc/2X/xN/wC0Pt/m/wDLt5WzZs/22znf7dK8/r6/+GXxN/4WN/an/Eo/s/7B5X/Lz5u/fv8A9hcY2e/Wj4m/E3/hXP8AZf8AxKP7Q+3+b/y8+Vs2bP8AYbOd/t0rwD4ZfDL/AIWN/an/ABN/7P8AsHlf8u3m79+//bXGNnv1r3/4ZfE3/hY39qf8Sj+z/sHlf8vPm79+/wD2FxjZ79a8A+GXwy/4WN/an/E3/s/7B5X/AC7ebv37/wDbXGNnv1o+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0r3/4ZfDL/hXP9qf8Tf8AtD7f5X/Lt5WzZv8A9ts53+3SvP8A/k4z/qXv7C/7e/P8/wD797dvk++d3bHJ/wAMy/8AU3f+U3/7bX0BXz/+01/zK3/b3/7Ro/5Nz/6mH+3f+3TyPI/7+bt3ne2NvfPHoHwy+Jv/AAsb+1P+JR/Z/wBg8r/l583fv3/7C4xs9+teAfDL4Zf8LG/tT/ib/wBn/YPK/wCXbzd+/f8A7a4xs9+td/8A8m5/9TD/AG7/ANunkeR/383bvO9sbe+eD/hmX/qbv/Kb/wDba8Ar6/8Ahl8Mv+Fc/wBqf8Tf+0Pt/lf8u3lbNm//AG2znf7dKPhl8Tf+Fjf2p/xKP7P+weV/y8+bv37/APYXGNnv1r0CiiivP/hl8Mv+Fc/2p/xN/wC0Pt/lf8u3lbNm/wD22znf7dK8/wD+Gmv+pR/8qX/2qj/hmX/qbv8Aym//AG2j/hmX/qbv/Kb/APba9A+JvxN/4Vz/AGX/AMSj+0Pt/m/8vPlbNmz/AGGznf7dK8//AOGZf+pu/wDKb/8Aba9A+Jvwy/4WN/Zf/E3/ALP+web/AMu3m79+z/bXGNnv1o+Jvwy/4WN/Zf8AxN/7P+web/y7ebv37P8AbXGNnv1rz/8A4aa/6lH/AMqX/wBqr6Ar4Ar3/wD5OM/6l7+wv+3vz/P/AO/e3b5Pvnd2xyfsy/8AM0/9un/tauA+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0rv8A/hmX/qbv/Kb/APbaP+Gmv+pR/wDKl/8Aaq4D4m/E3/hY39l/8Sj+z/sHm/8ALz5u/fs/2FxjZ79a7/8A5Nz/AOph/t3/ALdPI8j/AL+bt3ne2NvfPHoHwy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpXn/wDybn/1MP8Abv8A26eR5H/fzdu872xt7544D4m/E3/hY39l/wDEo/s/7B5v/Lz5u/fs/wBhcY2e/Wvr+vn/APZl/wCZp/7dP/a1H7Mv/M0/9un/ALWo/wCTc/8AqYf7d/7dPI8j/v5u3ed7Y2988H7TX/Mrf9vf/tGvoCiiiivn/wDaa/5lb/t7/wDaNH/DTX/Uo/8AlS/+1V6B8Tfib/wrn+y/+JR/aH2/zf8Al58rZs2f7DZzv9ulef8A/DMv/U3f+U3/AO21wHxN+Jv/AAsb+y/+JR/Z/wBg83/l583fv2f7C4xs9+tef17/APsy/wDM0/8Abp/7WrgPhl8Mv+Fjf2p/xN/7P+weV/y7ebv37/8AbXGNnv1rv/2Zf+Zp/wC3T/2tR+01/wAyt/29/wDtGj/k4z/qXv7C/wC3vz/P/wC/e3b5Pvnd2xz9AV8//wDDMv8A1N3/AJTf/ttcB8Tfhl/wrn+y/wDib/2h9v8AN/5dvK2bNn+22c7/AG6V3/8AycZ/1L39hf8Ab35/n/8Afvbt8n3zu7Y5P2Zf+Zp/7dP/AGtR/wAm5/8AUw/27/26eR5H/fzdu872xt7549A+GXxN/wCFjf2p/wASj+z/ALB5X/Lz5u/fv/2FxjZ79a8A+GXwy/4WN/an/E3/ALP+weV/y7ebv37/APbXGNnv1r3/AOGXwy/4Vz/an/E3/tD7f5X/AC7eVs2b/wDbbOd/t0o+JvxN/wCFc/2X/wASj+0Pt/m/8vPlbNmz/YbOd/t0rz//AIaa/wCpR/8AKl/9qo/4Zl/6m7/ym/8A22vQPhl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dKPhl8Tf+Fjf2p/xKP7P+weV/wAvPm79+/8A2FxjZ79a8A+Jvwy/4Vz/AGX/AMTf+0Pt/m/8u3lbNmz/AG2znf7dK9/+GXxN/wCFjf2p/wASj+z/ALB5X/Lz5u/fv/2FxjZ79a9Aooor5/8A+Gmv+pR/8qX/ANqr6Ar5A+GXxN/4Vz/an/Eo/tD7f5X/AC8+Vs2b/wDYbOd/t0rv/wDk3P8A6mH+3f8At08jyP8Av5u3ed7Y2988H/Juf/Uw/wBu/wDbp5Hkf9/N27zvbG3vng/4aa/6lH/ypf8A2quA+JvxN/4WN/Zf/Eo/s/7B5v8Ay8+bv37P9hcY2e/Wvf8A4ZfDL/hXP9qf8Tf+0Pt/lf8ALt5WzZv/ANts53+3SvP/ANmX/maf+3T/ANrUf8My/wDU3f8AlN/+216B8Mvib/wsb+1P+JR/Z/2Dyv8Al583fv3/AOwuMbPfrXn/APycZ/1L39hf9vfn+f8A9+9u3yffO7tjk/4aa/6lH/ypf/aq9A+GXwy/4Vz/AGp/xN/7Q+3+V/y7eVs2b/8AbbOd/t0rwD4m/E3/AIWN/Zf/ABKP7P8AsHm/8vPm79+z/YXGNnv1r3/4ZfDL/hXP9qf8Tf8AtD7f5X/Lt5WzZv8A9ts53+3SvP8A/hpr/qUf/Kl/9qrgPhl8Tf8AhXP9qf8AEo/tD7f5X/Lz5WzZv/2Gznf7dK7/AP4Zl/6m7/ym/wD22j9mX/maf+3T/wBrUf8AJxn/AFL39hf9vfn+f/3727fJ987u2OT/AIaa/wCpR/8AKl/9qr0D4m/DL/hY39l/8Tf+z/sHm/8ALt5u/fs/21xjZ79a8/8A+GZf+pu/8pv/ANtr0D4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3SvAPib8Mv+Fc/2X/xN/wC0Pt/m/wDLt5WzZs/22znf7dK7/wDZl/5mn/t0/wDa1fQFFFFef/DL4m/8LG/tT/iUf2f9g8r/AJefN379/wDsLjGz3614B8Tfhl/wrn+y/wDib/2h9v8AN/5dvK2bNn+22c7/AG6UfDL4m/8ACuf7U/4lH9ofb/K/5efK2bN/+w2c7/bpXf8A/DMv/U3f+U3/AO20f8nGf9S9/YX/AG9+f5//AH727fJ987u2OeA+GXwy/wCFjf2p/wATf+z/ALB5X/Lt5u/fv/21xjZ79a7/AP4aa/6lH/ypf/aq4D4m/DL/AIVz/Zf/ABN/7Q+3+b/y7eVs2bP9ts53+3Su/wD2Zf8Amaf+3T/2tXAfDL4Zf8LG/tT/AIm/9n/YPK/5dvN379/+2uMbPfrR8Tfib/wsb+y/+JR/Z/2Dzf8Al583fv2f7C4xs9+tHwy+GX/Cxv7U/wCJv/Z/2Dyv+Xbzd+/f/trjGz3615/X1/8ADL4Zf8K5/tT/AIm/9ofb/K/5dvK2bN/+22c7/bpXgHwy+Jv/AArn+1P+JR/aH2/yv+Xnytmzf/sNnO/26UfE34m/8LG/sv8A4lH9n/YPN/5efN379n+wuMbPfrXf/tNf8yt/29/+0aP+TjP+pe/sL/t78/z/APv3t2+T753dscn7Mv8AzNP/AG6f+1q4D4ZfDL/hY39qf8Tf+z/sHlf8u3m79+//AG1xjZ79a+v68/8Ahl8Tf+Fjf2p/xKP7P+weV/y8+bv37/8AYXGNnv1rz/8A5Nz/AOph/t3/ALdPI8j/AL+bt3ne2NvfPHoHxN+Jv/Cuf7L/AOJR/aH2/wA3/l58rZs2f7DZzv8AbpXgHwy+GX/Cxv7U/wCJv/Z/2Dyv+Xbzd+/f/trjGz360fDL4Zf8LG/tT/ib/wBn/YPK/wCXbzd+/f8A7a4xs9+tfX9FFFFfIHxN+GX/AArn+y/+Jv8A2h9v83/l28rZs2f7bZzv9uld/wD8m5/9TD/bv/bp5Hkf9/N27zvbG3vnjgPhl8Tf+Fc/2p/xKP7Q+3+V/wAvPlbNm/8A2Gznf7dKPib8Mv8AhXP9l/8AE3/tD7f5v/Lt5WzZs/22znf7dK7/AP5OM/6l7+wv+3vz/P8A+/e3b5Pvnd2xz6B8Mvib/wALG/tT/iUf2f8AYPK/5efN379/+wuMbPfrXyBX1/8AE34m/wDCuf7L/wCJR/aH2/zf+XnytmzZ/sNnO/26UfDL4m/8LG/tT/iUf2f9g8r/AJefN379/wDsLjGz3615/wDsy/8AM0/9un/taj/k3P8A6mH+3f8At08jyP8Av5u3ed7Y2988eAV9f/DL4m/8LG/tT/iUf2f9g8r/AJefN379/wDsLjGz3614B8Tfib/wsb+y/wDiUf2f9g83/l583fv2f7C4xs9+td/+01/zK3/b3/7Rr6Ar5/8A+TjP+pe/sL/t78/z/wDv3t2+T753dsc+gfDL4Zf8K5/tT/ib/wBofb/K/wCXbytmzf8A7bZzv9ulef8A/DMv/U3f+U3/AO21wHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrXf8A/Jxn/Uvf2F/29+f5/wD3727fJ987u2OfQPib8Tf+Fc/2X/xKP7Q+3+b/AMvPlbNmz/YbOd/t0rz/AP5Nz/6mH+3f+3TyPI/7+bt3ne2NvfPB/wAm5/8AUw/27/26eR5H/fzdu872xt754+gK+QPhl8Mv+Fjf2p/xN/7P+weV/wAu3m79+/8A21xjZ79a+v6KKKK8/wDib8Tf+Fc/2X/xKP7Q+3+b/wAvPlbNmz/YbOd/t0rz/wDaa/5lb/t7/wDaNH7Mv/M0/wDbp/7Wo/5Nz/6mH+3f+3TyPI/7+bt3ne2NvfPB/wAMy/8AU3f+U3/7bXoHwy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpR8Mvib/wALG/tT/iUf2f8AYPK/5efN379/+wuMbPfrXn//AA01/wBSj/5Uv/tVH/DMv/U3f+U3/wC21wHxN+Jv/Cxv7L/4lH9n/YPN/wCXnzd+/Z/sLjGz360fDL4m/wDCuf7U/wCJR/aH2/yv+Xnytmzf/sNnO/26UfE34Zf8K5/sv/ib/wBofb/N/wCXbytmzZ/ttnO/26V3/wDycZ/1L39hf9vfn+f/AN+9u3yffO7tjk/5OM/6l7+wv+3vz/P/AO/e3b5Pvnd2xz6B8Mvhl/wrn+1P+Jv/AGh9v8r/AJdvK2bN/wDttnO/26V4B8Tfib/wsb+y/wDiUf2f9g83/l583fv2f7C4xs9+tHxN+Jv/AAsb+y/+JR/Z/wBg83/l583fv2f7C4xs9+tHxN+GX/Cuf7L/AOJv/aH2/wA3/l28rZs2f7bZzv8AbpXv/wAMvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9ulHxN+GX/Cxv7L/4m/8AZ/2Dzf8Al283fv2f7a4xs9+tHxN+GX/Cxv7L/wCJv/Z/2Dzf+Xbzd+/Z/trjGz3614B8Mvhl/wALG/tT/ib/ANn/AGDyv+Xbzd+/f/trjGz3613/APybn/1MP9u/9unkeR/383bvO9sbe+ePoCvn/wD4Zl/6m7/ym/8A22j9pr/mVv8At7/9o0fsy/8AM0/9un/tavoCiiivn/8A4Zl/6m7/AMpv/wBtr6Ar5/8A2Zf+Zp/7dP8A2tR/wzL/ANTd/wCU3/7bR/ycZ/1L39hf9vfn+f8A9+9u3yffO7tjk/Zl/wCZp/7dP/a1H/Juf/Uw/wBu/wDbp5Hkf9/N27zvbG3vng/5Nz/6mH+3f+3TyPI/7+bt3ne2NvfPHoHxN+GX/Cxv7L/4m/8AZ/2Dzf8Al283fv2f7a4xs9+teAfE34Zf8K5/sv8A4m/9ofb/ADf+XbytmzZ/ttnO/wBulHxN+Jv/AAsb+y/+JR/Z/wBg83/l583fv2f7C4xs9+td/wD8NNf9Sj/5Uv8A7VXoHwy+GX/Cuf7U/wCJv/aH2/yv+Xbytmzf/ttnO/26V5//AMNNf9Sj/wCVL/7VR/ybn/1MP9u/9unkeR/383bvO9sbe+ePoCvn/wD5OM/6l7+wv+3vz/P/AO/e3b5Pvnd2xzwHwy+GX/Cxv7U/4m/9n/YPK/5dvN379/8AtrjGz3617/8ADL4Zf8K5/tT/AIm/9ofb/K/5dvK2bN/+22c7/bpXn/8AwzL/ANTd/wCU3/7bXgFe/wD/AA01/wBSj/5Uv/tVegfDL4Zf8K5/tT/ib/2h9v8AK/5dvK2bN/8AttnO/wBulef/APDMv/U3f+U3/wC216B8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpR8Mvhl/wrn+1P+Jv/aH2/wAr/l28rZs3/wC22c7/AG6V6BRRRRXyB8Tfib/wsb+y/wDiUf2f9g83/l583fv2f7C4xs9+tHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrR8Mvhl/wsb+1P+Jv/Z/2Dyv+Xbzd+/f/ALa4xs9+td//AMMy/wDU3f8AlN/+21wHwy+GX/Cxv7U/4m/9n/YPK/5dvN379/8AtrjGz3617/8ADL4Zf8K5/tT/AIm/9ofb/K/5dvK2bN/+22c7/bpXgHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrR8Tfib/wsb+y/wDiUf2f9g83/l583fv2f7C4xs9+td//AMNNf9Sj/wCVL/7VR/ybn/1MP9u/9unkeR/383bvO9sbe+eD/hpr/qUf/Kl/9qo/4aa/6lH/AMqX/wBqrgPhl8Mv+Fjf2p/xN/7P+weV/wAu3m79+/8A21xjZ79a7/8A4Zl/6m7/AMpv/wBtrgPhl8Tf+Fc/2p/xKP7Q+3+V/wAvPlbNm/8A2Gznf7dK8/r6/wDhl8Tf+Fjf2p/xKP7P+weV/wAvPm79+/8A2FxjZ79aPhl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK8//wCGmv8AqUf/ACpf/aqP+GZf+pu/8pv/ANtrgPib8Mv+Fc/2X/xN/wC0Pt/m/wDLt5WzZs/22znf7dKPib8Mv+Fc/wBl/wDE3/tD7f5v/Lt5WzZs/wBts53+3Sj4ZfDL/hY39qf8Tf8As/7B5X/Lt5u/fv8A9tcY2e/Wu/8A+GZf+pu/8pv/ANto/Zl/5mn/ALdP/a1cB8Tfhl/wrn+y/wDib/2h9v8AN/5dvK2bNn+22c7/AG6V7/8ADL4m/wDCxv7U/wCJR/Z/2Dyv+Xnzd+/f/sLjGz3616BRRRXyB8Tfhl/wrn+y/wDib/2h9v8AN/5dvK2bNn+22c7/AG6V7/8ADL4Zf8K5/tT/AIm/9ofb/K/5dvK2bN/+22c7/bpXn/7Mv/M0/wDbp/7Wr0D4ZfDL/hXP9qf8Tf8AtD7f5X/Lt5WzZv8A9ts53+3SvAPhl8Mv+Fjf2p/xN/7P+weV/wAu3m79+/8A21xjZ79a7/8Aaa/5lb/t7/8AaNH/AA01/wBSj/5Uv/tVcB8Mvib/AMK5/tT/AIlH9ofb/K/5efK2bN/+w2c7/bpXv/xN+Jv/AArn+y/+JR/aH2/zf+XnytmzZ/sNnO/26V4B8Tfib/wsb+y/+JR/Z/2Dzf8Al583fv2f7C4xs9+td/8AtNf8yt/29/8AtGuA+Jvwy/4Vz/Zf/E3/ALQ+3+b/AMu3lbNmz/bbOd/t0rv/ANmX/maf+3T/ANrV6B8Mvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9uleAfDL4m/8ACuf7U/4lH9ofb/K/5efK2bN/+w2c7/bpXf8A7Mv/ADNP/bp/7Wr0D4m/DL/hY39l/wDE3/s/7B5v/Lt5u/fs/wBtcY2e/WvAPib8Mv8AhXP9l/8AE3/tD7f5v/Lt5WzZs/22znf7dK9/+Jvwy/4WN/Zf/E3/ALP+web/AMu3m79+z/bXGNnv1rwD4ZfDL/hY39qf8Tf+z/sHlf8ALt5u/fv/ANtcY2e/Wvf/AIZfE3/hY39qf8Sj+z/sHlf8vPm79+//AGFxjZ79a9Ar5/8A2Zf+Zp/7dP8A2tXoHwy+GX/Cuf7U/wCJv/aH2/yv+Xbytmzf/ttnO/26V5/+zL/zNP8A26f+1q+gK8/+GXxN/wCFjf2p/wASj+z/ALB5X/Lz5u/fv/2FxjZ79a9Aooor5/8A+Gmv+pR/8qX/ANqo/wCTc/8AqYf7d/7dPI8j/v5u3ed7Y2988cB8Mvhl/wALG/tT/ib/ANn/AGDyv+Xbzd+/f/trjGz3613/APwzL/1N3/lN/wDttcB8Tfhl/wAK5/sv/ib/ANofb/N/5dvK2bNn+22c7/bpR8Tfhl/wrn+y/wDib/2h9v8AN/5dvK2bNn+22c7/AG6UfDL4m/8ACuf7U/4lH9ofb/K/5efK2bN/+w2c7/bpXf8A7Mv/ADNP/bp/7Wo/Zl/5mn/t0/8Aa1H/AAzL/wBTd/5Tf/ttH/DMv/U3f+U3/wC20f8ADTX/AFKP/lS/+1V4BXv/APwzL/1N3/lN/wDttegfDL4Zf8K5/tT/AIm/9ofb/K/5dvK2bN/+22c7/bpXgHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrR8Tfhl/wrn+y/wDib/2h9v8AN/5dvK2bNn+22c7/AG6V9f15/wDDL4Zf8K5/tT/ib/2h9v8AK/5dvK2bN/8AttnO/wBulHxN+GX/AAsb+y/+Jv8A2f8AYPN/5dvN379n+2uMbPfrR8Tfhl/wsb+y/wDib/2f9g83/l283fv2f7a4xs9+teAfDL4Zf8LG/tT/AIm/9n/YPK/5dvN379/+2uMbPfrXf/8ADMv/AFN3/lN/+21wHwy+GX/Cxv7U/wCJv/Z/2Dyv+Xbzd+/f/trjGz3615/X1/8ADL4Zf8K5/tT/AIm/9ofb/K/5dvK2bN/+22c7/bpXn/7Mv/M0/wDbp/7Wr6Aooor5/wD+Gmv+pR/8qX/2quA+GXwy/wCFjf2p/wATf+z/ALB5X/Lt5u/fv/21xjZ79aPhl8Mv+Fjf2p/xN/7P+weV/wAu3m79+/8A21xjZ79a7/8A5Nz/AOph/t3/ALdPI8j/AL+bt3ne2NvfPB/w01/1KP8A5Uv/ALVXoHxN+Jv/AArn+y/+JR/aH2/zf+XnytmzZ/sNnO/26V5//wANNf8AUo/+VL/7VR/w01/1KP8A5Uv/ALVR/wAm5/8AUw/27/26eR5H/fzdu872xt7549A+Jvwy/wCFjf2X/wATf+z/ALB5v/Lt5u/fs/21xjZ79a8//wCGmv8AqUf/ACpf/aqP+TjP+pe/sL/t78/z/wDv3t2+T753dscn/Jxn/Uvf2F/29+f5/wD3727fJ987u2OeA+GXxN/4Vz/an/Eo/tD7f5X/AC8+Vs2b/wDYbOd/t0rv/wBpr/mVv+3v/wBo1wHxN+Jv/Cxv7L/4lH9n/YPN/wCXnzd+/Z/sLjGz360fDL4m/wDCuf7U/wCJR/aH2/yv+Xnytmzf/sNnO/26V7/8Tfib/wAK5/sv/iUf2h9v83/l58rZs2f7DZzv9ulHwy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpXyBXv/APycZ/1L39hf9vfn+f8A9+9u3yffO7tjngPib8Tf+Fjf2X/xKP7P+web/wAvPm79+z/YXGNnv1o+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0r3/4ZfDL/hXP9qf8Tf8AtD7f5X/Lt5WzZv8A9ts53+3SvP8A/hmX/qbv/Kb/APbaP2mv+ZW/7e//AGjX0BRRRRXz/wDsy/8AM0/9un/tavQPib8Mv+Fjf2X/AMTf+z/sHm/8u3m79+z/AG1xjZ79a8//AGmv+ZW/7e//AGjXAfE34Zf8K5/sv/ib/wBofb/N/wCXbytmzZ/ttnO/26V9f18//tNf8yt/29/+0a+gK8/+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0rwD4m/DL/hXP9l/8Tf8AtD7f5v8Ay7eVs2bP9ts53+3Sj4ZfDL/hY39qf8Tf+z/sHlf8u3m79+//AG1xjZ79a8/r3/8A5OM/6l7+wv8At78/z/8Av3t2+T753dscn/DMv/U3f+U3/wC20f8AJuf/AFMP9u/9unkeR/383bvO9sbe+eOA+GXwy/4WN/an/E3/ALP+weV/y7ebv37/APbXGNnv1o+GXxN/4Vz/AGp/xKP7Q+3+V/y8+Vs2b/8AYbOd/t0o+JvxN/4WN/Zf/Eo/s/7B5v8Ay8+bv37P9hcY2e/Wvf8A4ZfE3/hY39qf8Sj+z/sHlf8ALz5u/fv/ANhcY2e/WvkCvr/4m/E3/hXP9l/8Sj+0Pt/m/wDLz5WzZs/2Gznf7dK8/wD2mv8AmVv+3v8A9o1wHwy+GX/Cxv7U/wCJv/Z/2Dyv+Xbzd+/f/trjGz3617/8Tfhl/wALG/sv/ib/ANn/AGDzf+Xbzd+/Z/trjGz360fE34Zf8LG/sv8A4m/9n/YPN/5dvN379n+2uMbPfrXn/wDw01/1KP8A5Uv/ALVR/wAm5/8AUw/27/26eR5H/fzdu872xt754P2Zf+Zp/wC3T/2tX0BRRRXwBXoHxN+GX/Cuf7L/AOJv/aH2/wA3/l28rZs2f7bZzv8AbpR8Mvib/wAK5/tT/iUf2h9v8r/l58rZs3/7DZzv9ule/wDwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpXn/AO01/wAyt/29/wDtGuA+JvxN/wCFjf2X/wASj+z/ALB5v/Lz5u/fs/2FxjZ79aPib8Tf+Fjf2X/xKP7P+web/wAvPm79+z/YXGNnv1o+JvxN/wCFjf2X/wASj+z/ALB5v/Lz5u/fs/2FxjZ79aPhl8Mv+Fjf2p/xN/7P+weV/wAu3m79+/8A21xjZ79a9/8Aib8Mv+Fjf2X/AMTf+z/sHm/8u3m79+z/AG1xjZ79a9Arz/4m/E3/AIVz/Zf/ABKP7Q+3+b/y8+Vs2bP9hs53+3SvkCvf/wBpr/mVv+3v/wBo16B8Tfhl/wALG/sv/ib/ANn/AGDzf+Xbzd+/Z/trjGz3615/+zL/AMzT/wBun/tauA+GXxN/4Vz/AGp/xKP7Q+3+V/y8+Vs2b/8AYbOd/t0o+GXxN/4Vz/an/Eo/tD7f5X/Lz5WzZv8A9hs53+3Svr+vn/8AZl/5mn/t0/8Aa1egfDL4m/8ACxv7U/4lH9n/AGDyv+Xnzd+/f/sLjGz3615//wANNf8AUo/+VL/7VR/wzL/1N3/lN/8AttegfDL4m/8ACxv7U/4lH9n/AGDyv+Xnzd+/f/sLjGz3615//wAnGf8AUvf2F/29+f5//fvbt8n3zu7Y59A+Jvwy/wCFjf2X/wATf+z/ALB5v/Lt5u/fs/21xjZ79aPhl8Mv+Fc/2p/xN/7Q+3+V/wAu3lbNm/8A22znf7dK9Aooorz/AOJvwy/4WN/Zf/E3/s/7B5v/AC7ebv37P9tcY2e/Wj4ZfE3/AIWN/an/ABKP7P8AsHlf8vPm79+//YXGNnv1r0CvkD4m/DL/AIVz/Zf/ABN/7Q+3+b/y7eVs2bP9ts53+3SvP6+v/hl8Tf8AhY39qf8AEo/s/wCweV/y8+bv37/9hcY2e/WvAPib8Mv+Fc/2X/xN/wC0Pt/m/wDLt5WzZs/22znf7dK7/wDaa/5lb/t7/wDaNH7TX/Mrf9vf/tGj/k4z/qXv7C/7e/P8/wD797dvk++d3bHJ+01/zK3/AG9/+0a4D4m/E3/hY39l/wDEo/s/7B5v/Lz5u/fs/wBhcY2e/Wu//wCTc/8AqYf7d/7dPI8j/v5u3ed7Y2988cB8Tfib/wALG/sv/iUf2f8AYPN/5efN379n+wuMbPfrXv8A8Tfib/wrn+y/+JR/aH2/zf8Al58rZs2f7DZzv9uleAfDL4Zf8LG/tT/ib/2f9g8r/l283fv3/wC2uMbPfrR8Mvhl/wALG/tT/ib/ANn/AGDyv+Xbzd+/f/trjGz360fE34m/8LG/sv8A4lH9n/YPN/5efN379n+wuMbPfrXf/sy/8zT/ANun/tauA+Jvwy/4Vz/Zf/E3/tD7f5v/AC7eVs2bP9ts53+3Svf/AIm/E3/hXP8AZf8AxKP7Q+3+b/y8+Vs2bP8AYbOd/t0rz/8AZl/5mn/t0/8Aa1H/ACbn/wBTD/bv/bp5Hkf9/N27zvbG3vnj6Ar5A+JvxN/4WN/Zf/Eo/s/7B5v/AC8+bv37P9hcY2e/WvP69/8A2Zf+Zp/7dP8A2tX0BRRRXwBXoHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrXn9e/wD/AAzL/wBTd/5Tf/ttH/DTX/Uo/wDlS/8AtVH7TX/Mrf8Ab3/7RrgPhl8Mv+Fjf2p/xN/7P+weV/y7ebv37/8AbXGNnv1rv/8Ak4z/AKl7+wv+3vz/AD/+/e3b5Pvnd2xz6B8Tfib/AMK5/sv/AIlH9ofb/N/5efK2bNn+w2c7/bpXn/8Aybn/ANTD/bv/AG6eR5H/AH83bvO9sbe+ePQPib8Mv+Fjf2X/AMTf+z/sHm/8u3m79+z/AG1xjZ79aPib8Tf+Fc/2X/xKP7Q+3+b/AMvPlbNmz/YbOd/t0o+Jvwy/4WN/Zf8AxN/7P+web/y7ebv37P8AbXGNnv1rz/8A5OM/6l7+wv8At78/z/8Av3t2+T753dscn/Juf/Uw/wBu/wDbp5Hkf9/N27zvbG3vnj6Ar5//AGZf+Zp/7dP/AGtXoHwy+Jv/AAsb+1P+JR/Z/wBg8r/l583fv3/7C4xs9+tef/8ADMv/AFN3/lN/+21wHxN+GX/Cuf7L/wCJv/aH2/zf+XbytmzZ/ttnO/26V7/8Tfib/wAK5/sv/iUf2h9v83/l58rZs2f7DZzv9ulef/8ADTX/AFKP/lS/+1VwHwy+Jv8Awrn+1P8AiUf2h9v8r/l58rZs3/7DZzv9uld//wAnGf8AUvf2F/29+f5//fvbt8n3zu7Y59A+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0rz//AJOM/wCpe/sL/t78/wA//v3t2+T753dsc/QFFFFFef8Awy+Jv/Cxv7U/4lH9n/YPK/5efN379/8AsLjGz3615/8AtNf8yt/29/8AtGuA+GXxN/4Vz/an/Eo/tD7f5X/Lz5WzZv8A9hs53+3Su/8A+Tc/+ph/t3/t08jyP+/m7d53tjb3zwf8m5/9TD/bv/bp5Hkf9/N27zvbG3vng/4Zl/6m7/ym/wD22j9mX/maf+3T/wBrUf8AJxn/AFL39hf9vfn+f/3727fJ987u2OfoCvn/AP5OM/6l7+wv+3vz/P8A+/e3b5Pvnd2xyf8ADMv/AFN3/lN/+20ftNf8yt/29/8AtGvQPhl8Tf8AhY39qf8AEo/s/wCweV/y8+bv37/9hcY2e/WvP/8Ahpr/AKlH/wAqX/2quA+Jvwy/4Vz/AGX/AMTf+0Pt/m/8u3lbNmz/AG2znf7dKPib8Tf+Fjf2X/xKP7P+web/AMvPm79+z/YXGNnv1r3/AOJvwy/4WN/Zf/E3/s/7B5v/AC7ebv37P9tcY2e/WvP/APhmX/qbv/Kb/wDbaP8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPB/w01/1KP/AJUv/tVegfDL4Zf8K5/tT/ib/wBofb/K/wCXbytmzf8A7bZzv9ulHwy+GX/Cuf7U/wCJv/aH2/yv+Xbytmzf/ttnO/26V4B8Mvib/wAK5/tT/iUf2h9v8r/l58rZs3/7DZzv9ule/wDxN+GX/Cxv7L/4m/8AZ/2Dzf8Al283fv2f7a4xs9+tfIFfX/xN+GX/AAsb+y/+Jv8A2f8AYPN/5dvN379n+2uMbPfrR8Mvib/wsb+1P+JR/Z/2Dyv+Xnzd+/f/ALC4xs9+tegUUUV8gfE34Zf8K5/sv/ib/wBofb/N/wCXbytmzZ/ttnO/26V3/wDycZ/1L39hf9vfn+f/AN+9u3yffO7tjk/4Zl/6m7/ym/8A22j/AIZl/wCpu/8AKb/9trgPib8Mv+Fc/wBl/wDE3/tD7f5v/Lt5WzZs/wBts53+3Sj4ZfDL/hY39qf8Tf8As/7B5X/Lt5u/fv8A9tcY2e/Wu/8A+GZf+pu/8pv/ANtr0D4ZfE3/AIWN/an/ABKP7P8AsHlf8vPm79+//YXGNnv1r5Ar3/8A5OM/6l7+wv8At78/z/8Av3t2+T753dsc+gfDL4Zf8K5/tT/ib/2h9v8AK/5dvK2bN/8AttnO/wBulef/APDTX/Uo/wDlS/8AtVegfDL4Zf8ACuf7U/4m/wDaH2/yv+Xbytmzf/ttnO/26UfDL4Zf8K5/tT/ib/2h9v8AK/5dvK2bN/8AttnO/wBulHwy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulHwy+Jv/Cxv7U/4lH9n/YPK/5efN379/8AsLjGz3614B8Tfib/AMLG/sv/AIlH9n/YPN/5efN379n+wuMbPfrXf/8ADMv/AFN3/lN/+216B8Tfhl/wsb+y/wDib/2f9g83/l283fv2f7a4xs9+tef/ALTX/Mrf9vf/ALRo/wCTjP8AqXv7C/7e/P8AP/797dvk++d3bHJ/w01/1KP/AJUv/tVH/DMv/U3f+U3/AO20f8nGf9S9/YX/AG9+f5//AH727fJ987u2OT/hmX/qbv8Aym//AG2vAK+v/hl8Tf8AhY39qf8AEo/s/wCweV/y8+bv37/9hcY2e/WvQKKKKK8/+Jvwy/4WN/Zf/E3/ALP+web/AMu3m79+z/bXGNnv1r0Cvn//AIZl/wCpu/8AKb/9to/Zl/5mn/t0/wDa1fQFfIHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9ule/8Awy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpR8Mvib/wALG/tT/iUf2f8AYPK/5efN379/+wuMbPfrXgHxN+Jv/Cxv7L/4lH9n/YPN/wCXnzd+/Z/sLjGz3613/wC01/zK3/b3/wC0a4D4ZfE3/hXP9qf8Sj+0Pt/lf8vPlbNm/wD2Gznf7dKPhl8Mv+Fjf2p/xN/7P+weV/y7ebv37/8AbXGNnv1rv/8AhmX/AKm7/wApv/22j9mX/maf+3T/ANrUf8My/wDU3f8AlN/+20f8nGf9S9/YX/b35/n/APfvbt8n3zu7Y59A+GXwy/4Vz/an/E3/ALQ+3+V/y7eVs2b/APbbOd/t0rz/APZl/wCZp/7dP/a1H/DMv/U3f+U3/wC216B8Tfib/wAK5/sv/iUf2h9v83/l58rZs2f7DZzv9ulef/sy/wDM0/8Abp/7WrgPhl8Mv+Fjf2p/xN/7P+weV/y7ebv37/8AbXGNnv1rv/8AhmX/AKm7/wApv/22j9mX/maf+3T/ANrUf8m5/wDUw/27/wBunkeR/wB/N27zvbG3vnj0D4ZfE3/hY39qf8Sj+z/sHlf8vPm79+//AGFxjZ79a9Aooor5A+GXwy/4WN/an/E3/s/7B5X/AC7ebv37/wDbXGNnv1rv/wDhmX/qbv8Aym//AG2j/hmX/qbv/Kb/APbaP2Zf+Zp/7dP/AGtR/wANNf8AUo/+VL/7VXoHwy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpXgHwy+GX/Cxv7U/wCJv/Z/2Dyv+Xbzd+/f/trjGz3613//ACbn/wBTD/bv/bp5Hkf9/N27zvbG3vnjwCvr/wCJvxN/4Vz/AGX/AMSj+0Pt/m/8vPlbNmz/AGGznf7dK8//AOTc/wDqYf7d/wC3TyPI/wC/m7d53tjb3zwfsy/8zT/26f8Ataj9mX/maf8At0/9rV6B8Mvhl/wrn+1P+Jv/AGh9v8r/AJdvK2bN/wDttnO/26V4B8Mvib/wrn+1P+JR/aH2/wAr/l58rZs3/wCw2c7/AG6V7/8ADL4m/wDCxv7U/wCJR/Z/2Dyv+Xnzd+/f/sLjGz3615/+01/zK3/b3/7Ro/5Nz/6mH+3f+3TyPI/7+bt3ne2NvfPB/wAm5/8AUw/27/26eR5H/fzdu872xt7544D4ZfE3/hXP9qf8Sj+0Pt/lf8vPlbNm/wD2Gznf7dKPhl8Mv+Fjf2p/xN/7P+weV/y7ebv37/8AbXGNnv1rv/8Ak4z/AKl7+wv+3vz/AD/+/e3b5Pvnd2xyfsy/8zT/ANun/tavQPhl8Mv+Fc/2p/xN/wC0Pt/lf8u3lbNm/wD22znf7dK8/wD2Zf8Amaf+3T/2tX0BXn/wy+Jv/Cxv7U/4lH9n/YPK/wCXnzd+/f8A7C4xs9+tegUUUV8//sy/8zT/ANun/tavAK9//Zl/5mn/ALdP/a1H7Mv/ADNP/bp/7WrgPhl8Tf8AhXP9qf8AEo/tD7f5X/Lz5WzZv/2Gznf7dK9/+JvxN/4Vz/Zf/Eo/tD7f5v8Ay8+Vs2bP9hs53+3Sj4ZfDL/hXP8Aan/E3/tD7f5X/Lt5WzZv/wBts53+3Sj4m/E3/hXP9l/8Sj+0Pt/m/wDLz5WzZs/2Gznf7dK8/wD+Tc/+ph/t3/t08jyP+/m7d53tjb3zx9AV8/8A/Juf/Uw/27/26eR5H/fzdu872xt754P+Tc/+ph/t3/t08jyP+/m7d53tjb3zx4BXoHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrXf8A/DMv/U3f+U3/AO216B8Tfhl/wsb+y/8Aib/2f9g83/l283fv2f7a4xs9+tef/wDDMv8A1N3/AJTf/ttegfE34m/8K5/sv/iUf2h9v83/AJefK2bNn+w2c7/bpR8Tfib/AMK5/sv/AIlH9ofb/N/5efK2bNn+w2c7/bpXn/8Aybn/ANTD/bv/AG6eR5H/AH83bvO9sbe+ePQPhl8Tf+Fjf2p/xKP7P+weV/y8+bv37/8AYXGNnv1rz/8AZl/5mn/t0/8Aa1eAV7//AMMy/wDU3f8AlN/+21wHxN+GX/Cuf7L/AOJv/aH2/wA3/l28rZs2f7bZzv8AbpR8Mvhl/wALG/tT/ib/ANn/AGDyv+Xbzd+/f/trjGz3619f0UUUV8//ALMv/M0/9un/ALWo/wCGZf8Aqbv/ACm//ba9A+GXwy/4Vz/an/E3/tD7f5X/AC7eVs2b/wDbbOd/t0rz/wDZl/5mn/t0/wDa1H/Juf8A1MP9u/8Abp5Hkf8Afzdu872xt7549A+Jvwy/4WN/Zf8AxN/7P+web/y7ebv37P8AbXGNnv1o+JvxN/4Vz/Zf/Eo/tD7f5v8Ay8+Vs2bP9hs53+3SvAPhl8Tf+Fc/2p/xKP7Q+3+V/wAvPlbNm/8A2Gznf7dKPhl8Mv8AhY39qf8AE3/s/wCweV/y7ebv37/9tcY2e/Wj4ZfDL/hY39qf8Tf+z/sHlf8ALt5u/fv/ANtcY2e/WvP6+v8A4ZfDL/hXP9qf8Tf+0Pt/lf8ALt5WzZv/ANts53+3Sj4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3SvkCvQPhl8Mv8AhY39qf8AE3/s/wCweV/y7ebv37/9tcY2e/Wj4ZfE3/hXP9qf8Sj+0Pt/lf8ALz5WzZv/ANhs53+3SvP6K9//AOTc/wDqYf7d/wC3TyPI/wC/m7d53tjb3zwf8My/9Td/5Tf/ALbR/wAnGf8AUvf2F/29+f5//fvbt8n3zu7Y5+gK+f8A9pr/AJlb/t7/APaNeAV6B8Tfhl/wrn+y/wDib/2h9v8AN/5dvK2bNn+22c7/AG6V7/8AE34m/wDCuf7L/wCJR/aH2/zf+XnytmzZ/sNnO/26V6BRRRRXz/8A8My/9Td/5Tf/ALbR/wAMy/8AU3f+U3/7bR/wzL/1N3/lN/8AttegfDL4Zf8ACuf7U/4m/wDaH2/yv+Xbytmzf/ttnO/26V5//wAMy/8AU3f+U3/7bXoHxN+GX/Cxv7L/AOJv/Z/2Dzf+Xbzd+/Z/trjGz360fE34Zf8ACxv7L/4m/wDZ/wBg83/l283fv2f7a4xs9+tegV8//wDDMv8A1N3/AJTf/ttfQFfP/wDwzL/1N3/lN/8AttfQFfP/APwzL/1N3/lN/wDttfQFef8Awy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpR8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXoFFef8Awy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpR8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpR8Tfhl/wsb+y/wDib/2f9g83/l283fv2f7a4xs9+tHwy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulHwy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpR8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpR8Mvhl/wrn+1P+Jv/aH2/wAr/l28rZs3/wC22c7/AG6UfDL4Zf8ACuf7U/4m/wDaH2/yv+Xbytmzf/ttnO/26V6BRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRRX//Z"
  },
  "payment_notice_data": {
    "payment_method": "account_debit",
    "payment_origin": "internet",
    "payment_notice_date": "2024-07-01"
  },
  "payment_data": {
    "paid_amount": 850.0,
    "paid_rebate_amount": 200.0,
    "paid_discount_amount": 0.0,
    "paid_fine_amount": 0.0,
    "paid_interest_amount": 50.0,
    "payment_method": "account_debit",
    "payment_origin": "internet",
    "payment_credit_date": "2024-07-02",
    "payment_date": "2024-07-01",
    "payment_bank": {
      "code": "341",
      "ispb": 60701190,
      "name": "ITAU UNIBANCO S.A."
    },
    "payment_branch": "0216"
  },
  "bank_slip_status": "registered",
  "occurrences": [
    {
      "request_control_key": "0dcb3182-4d7e-4526-8f92-c15cdbc51bad",
      "occurrence_key": "ec67408c-a149-418a-b89b-b9c9d3b6c403",
      "occurrence_type": "registration",
      "occurrence_status": "confirmed",
      "created_at": "2024-06-23T09:15:32Z"
    },
    {
      "request_control_key": "9618c632-7f4d-490b-8817-2bb72ec1e84a",
      "occurrence_key": "70d3e632-644d-499f-baac-f65f21fb8574",
      "occurrence_type": "rebate",
      "occurrence_status": "confirmed",
      "created_at": "2024-06-26T12:36:04Z"
    },
    {
      "request_control_key": "c2b2ba59-9c37-488d-823d-2c3bfc1e9108",
      "occurrence_key": "dbdd513c-e918-4d17-b194-b5ae3d979988",
      "occurrence_type": "cancel_rebate",
      "occurrence_status": "confirmed",
      "created_at": "2024-06-26T12:53:47Z"
    }
  ]
}
```

### Response Body Params

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `bank_slip_key      ` *    | uuidv4  | Chave única de identificação do boleto no formato uuid v4                          | 36                                                |
| `request_control_key` *    | uuidv4  | Chave única de identificação da request utilizada pelo cliente no formato uuid v4  | 36                                                |
| `our_number` *             | integer | Número único de identificação do boleto junto à carteira                           | 11                                                |
| `bank_slip_status` *       | string | Status do boleto                                                                    | **[Enumeradores bank_slip_status](#enumeradores-bank_slip_status)** |
| `protest_status` *         | string | Status de protesto, em cartório, do boleto                                          | **[Enumeradores protest_status](#enumeradores-protest_status)** |
| `document_number` *        | string  | Número de identificação do boleto                                                  | 10                                                |
| `amount` *                 | float   | Valor base do boleto                                                               | -                                                 |
| `expiration` *             | string  | Data de vencimento                                                                 | 10                                                |
| `barcode` *               | string  | Código de barras do boleto                                                         | 44                                                |
| `digitable_line` *         | string  | Linha digitável do boleto                                                          | 47                                                |
| `bank_teller_instructions` | string  | Instruções adicionais de registro, que constarão no PDF do boleto                  | 320                                               |
| `rebate_amount`            | float   | Valor de abatimento do boleto, que será aplicado em cima do valor base             | -                                                 |
| `max_payment_days` *      | integer | Máximo de dias corridos que o boleto ficará disponível para pagamento, após o vencimento (pode ser no máximo 365) | -          |
| `write_off_data`       | object  | Configuração de baixa      | **[Objeto write_off_data](#objeto-write_off_settings)** |
| `protest_data`         | object  | Configuração de protesto       | **[Objeto protest_data](#objeto-protest_settings)** |
| `bankruptcy_protest_data` | object  | Configuração de protesto falimentar | **[Objeto bankruptcy_protest_data](#objeto-bankruptcy_protest_settings)** |
| `fine_data`            | object  | Configuração de multa                 | **[Objeto fine_data](#objeto-fine_settings)** |
| `interest_data`        | object  | Configuração de juros        | **[Objeto interest_data](#objeto-interest_settings)** |
| `discounts_data`           | object array | Descontos           | **[Objeto discount](#objeto-discounts_data)** |
| `payer_data` *             | object  | Dados do pagador                                                                   | **[Objeto payer_data](#objetos-payer_data-e-guarantor_data)** |
| `guarantor_data` *         | object  | Dados do sacador avalista                                                          | **[Objeto guarantor_data](#objetos-payer_data-e-guarantor_data)** |
| `qr_code_data`             | object  | Dados do QR Code                                                         | **[Objeto qr_code_data](#objeto-qr_code_data)** |
| `payment_notice_data`             | object ou array  | Dados do aviso de pagamento                                                         | **[Objeto ou array payment_notice_data](#objeto-ou-array-payment_notice_data)** |
| `payment_data`             | object ou array  | Dados do pagamento                                                         | **[Objeto ou array payment_data](#objeto-ou-array-payment_data)** |
| `guarantor_data`           | object  | Dados do sacador avalista                                                          | **[Objeto guarantor_data](#objetos-payer_data-e-guarantor_data)** |
| `occurrences`              | object array | Instruções referentes ao boleto                                               | **[Objeto bank_slip_occurrence](#objeto-bank_slip_occurrence)** |

:::info Informação
O campo `amount` é o valor base do boleto, ou seja, não considera o valor da multa (fine), juros (interest), abatimento (rebate) e descontos (discounts).
:::

### Enumeradores bank_slip_status

| Enumerador                   | Descrição                                                                      |
|------------------------------|--------------------------------------------------------------------------------|
| accepted                     | Aceito e enviado para a Nuclea/CIP para análise                                |
| rejected                     | Registro rejeitado pela Nuclea/CIP                                             |
| payment_notice               | Aviso de pagamento (boleto pago mas pagamento ainda não liquidado)             |
| notary_office_payment_notice | Aviso de pagamento em cartório (boleto pago mas pagamento ainda não liquidado) |
| registered                   | Registro confirmado pela Nuclea/CIP                                            |
| payment_blocked              | Bloqueado para pagamento (em fluxo de protesto)                                |
| paid                         | Pago                                                                           |
| written_off                  | Baixado                                                                        |

### Enumeradores protest_status

| Enumerador                   | Descrição                                                                      |
|------------------------------|--------------------------------------------------------------------------------|
| not_protested                | Boleto sem fluxo de protesto iniciado                                          |
| protest_requested            | Protesto em cartório solicitado                                                |
| notary_office_entry          | Boleto no cartório, em período de tríduo                                       |
| protest_cancel_requested     | Desistência do protesto solicitada                                             |
| notary_office_exit           | Boleto saiu do cartório                                                        |
| protested                    | Boleto protestado                                                              |
| paid_at_notary_office        | Pago no cartório                                                               |
| judicially_suspended         | Protesto suspenso judicialmente                                                |
| protest_remove_requested     | Remoção do protesto solicitada                                                 |

### Objeto write_off_data

| Campo                     | Tipo    | Descrição                                                                   | Caracteres |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_write_off` *     | integer | Dias, após o vencimento, para que o boleto seja baixado automaticamente     | -          |

### Objeto protest_data

| Campo                     | Tipo    | Descrição                                                                   | Caracteres |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_protest` *       | integer | Dias, após o vencimento, para que o boleto seja protestado automaticamente  | -          |

### Objeto bankruptcy_protest_data

| Campo                          | Tipo    | Descrição                                                                   | Caracteres  |
|--------------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_bankruptcy_protest` * | integer | Dias, após o vencimento, para que o boleto seja protestado automaticamente  | -           |

### Objeto fine_data

Opção 1: multa em valor absoluto (`fine_type=absolute`)

| Campo                     | Tipo    | Descrição                                               | Caracteres                |
|---------------------------|---------|---------------------------------------------------------|-------------------------------------------------------------------------|
| `fine_type` *             | string  | Tipo da multa                                                       | **[Enumeradores fine_type](#enumeradores-fine_type)**                                              |
| `fine_amount` *           | float   | Valor absoluto da multa                                             | -                                                                        |
| `days_to_fine` *          | integer | Dias, após o vencimento, para que a multa seja cobrada              | -                                                                        |

Opção 2: multa em valor percentual (`fine_type=percentage`)

| Campo                     | Tipo    | Descrição                                                 | Caracteres                             |
|---------------------------|---------|-----------------------------------------------------------|---------------------------------------|
| `fine_type` *             | string  | Tipo da multa                                             | **[Enumeradores fine_type](#enumeradores-fine_type)** |
| `fine_percentage` *       | integer | Valor percentual da multa, de 1 a 100                     | -                                      |
| `days_to_fine` *          | integer | Dias, após o vencimento, para que a multa seja cobrada    | -                                      |

### Enumeradores fine_type

| Enumerador         | Descrição             |
|--------------------|-----------------------|
| absolute           | valor absoluto        |
| percentage         | valor percentual      |

### Objeto interest_data

Opção 1: juros utilizando valores absolutos (`interest_type=calendar_days_daily_amount` ou `interest_type=workdays_daily_amount`)

| Campo                     | Tipo    | Descrição                                                                     | Caracteres                                                                                      |
|---------------------------|---------|-------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| `interest_type` *         | string  | Tipo de juros       | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_amount` *       | float   | Valor a ser cobrado por unidade de tempo determinada (dias úteis ou corridos) | -                                                                                               |
| `days_to_interest` *      | integer | Dias, após o vencimento, para que comece a cobrar os juros                    | -                                                                                               |

Opção 2: juros utilizando valores percentuais (`interest_type=calendar_days_monthly_percentage`)

| Campo                    | Tipo    | Descrição                                                                             | Caracteres                                                                                          |
|--------------------------|---------|---------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
| `interest_type` *        | string  | Tipo de juros       | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_percentage` *  | integer | Porcentagem a ser cobrada por unidade de tempo determinada (dias úteis ou corridos)                                                                      | -                                                                           |
| `days_to_interest` *     | integer | Dias, após o vencimento, para que comece a cobrar os juros                             | -                                                                                                   |

### Enumeradores interest_type

| Enumerador                       | Descrição                                                            |
|----------------------------------|----------------------------------------------------------------------|
| calendar_days_daily_amount       | Valor diário sobre dias corridos                                     |
| workdays_daily_amount            | Valor diário sobre dias úteis                                        |
| calendar_days_monthly_percentage | Porcentagem de juros cobrados mensalmente, com base em dias corridos |

### Objeto discount

Opção 1: descontos utilizando valores absolutos (`discount_type in ["absolute", "anticipation_calendar_days_daily_amount", "anticipation_workdays_daily_amount"]`)

| Campo                     | Tipo    | Descrição                                           | Caracteres                                                |
|---------------------------|---------|-----------------------------------------------------|-----------------------------------------------------------|
| `discount_amount` *       | float   | Valor absoluto de desconto por unidade de tempo                                            | -                                                          |
| `discount_number` *       | integer | Número do desconto                                     | -                                                         |
| `discount_type` *         | string  | Configuração do desconto em valores absolutos                                    | **[Enumerador discount_type](#enumeradores-discount_type)** |                                                       |
| `discount_limit_date` *   | string  | Data limite para aplicação do desconto   | 10                                                        |

Opção 2: descontos utilizando valores percentuais (`discount_type in ["percentage", "anticipation_calendar_days_daily_percentage", "anticipation_workdays_daily_percentage"]`)

| Campo                     | Tipo    | Descrição                                           | Caracteres                                                |
|---------------------------|---------|-----------------------------------------------------|-----------------------------------------------------------|
| `discount_percentage` *   | float   | Valor percentual de desconto por unidade de tempo                                            | -                                                          |
| `discount_number` *       | integer | Número do desconto                                     | -                                                         |
| `discount_type` *         | string  | Configuração do desconto em valores percentuais                                    | **[Enumerador discount_type](#enumeradores-discount_type)** |                                                       |
| `discount_limit_date` *   | string  | Data limite para aplicação do desconto   | 10                                                        |

:::caution Atenção!
O boleto pode ter até três descontos, sendo que os descontos devem ser todos do mesmo tipo , isto é, devem ter o mesmo `discount_type`. Os descontos devem ser numerados de 1 a 3, de maneira crescente e começando necessariamente em 1. Ou seja, caso sejam enviados dois descontos na requisição, devem necessariamente ser numerados com 1 e 2.
:::

### Enumeradores discount_type

| Enumerador                                  | Descrição                                                                |
|---------------------------------------------|--------------------------------------------------------------------------|
| absolute                                    | Valor fixo                                                               |
| anticipation_calendar_days_daily_amount     | Valor diário de desconto de antecipação, sobre dias corridos             |
| anticipation_workdays_daily_amount          | Valor diário de desconto de antecipação, sobre dias úteis                |
| percentage                                  | Porcentagem fixa                                                         |
| anticipation_calendar_days_daily_percentage | Porcentagem mensal de desconto de antecipação, com base em dias corridos |
| anticipation_workdays_daily_percentage      | Porcentagem anual de desconto de antecipação, com base em dias úteis     |

### Objetos payer_data e guarantor_data

| Campo                     | Tipo   | Descrição                                                  | Caracteres|
|---------------------------|--------|-------------------------------------|-----------------------------------------------------------|
| `name` *                  | string | Nome completo                       | 100                                                       |
| `document_number` *       | string | Número do documento (CPF/CNPJ)      | 11 ou 14                                                  |
| `person_type` *           | string | Tipo da pessoa (física ou jurídica) | **[Enumeradores person_type](#enumeradores-person_type)** |
| `contact`                 | object | Informações de contato              | **[Objeto contact](#objeto-contact)**                     |
| `address`                 | object | Endereço                            | **[Objeto address](#objeto-address)**                     |

### Enumeradores person_type

| Enumerador         | Descrição             |
|--------------------|-----------------------|
| natural            | pessoa física         |
| legal              | pessoa jurídica       |

### Objeto contact

| Campo                     | Tipo   | Descrição                         | Caracteres                         |
|---------------------------|--------|-----------------------------------|------------------------------------|
| `email`                   | string | E-mail de contato                 | 320                                |
| `phone`                   | object | Telefone de contato               | **[Objeto phone](#objeto-phone)**  |

### Objeto phone

| Campo                           | Tipo   | Descrição                                    | Caracteres |
|---------------------------------|--------|----------------------------------------------|------------|
| `international_dial_code` *     | string | Código DDI (Discagem Direta Internacional)   | 3          |
| `area_code` *                   | string | Código DDD (Discagem Direta à Distância)     | 2          |
| `number` *                      | string | Complemento                                  | 9          |

### Objeto address

| Campo                     | Tipo   | Descrição                                    | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `street` *                | string | Logradouro                                   | 500        |
| `number` *                | string | Número                                       | 6          |
| `complement`              | string | Complemento                                  | 500        |
| `neighborhood` *          | string | Bairro                                       | 100        |
| `postal_code` *           | string | CEP                                          | 8          |
| `city` *                  | string | Cidade                                       | 100        |
| `state` *                 | string | Estado (UF) | **[Enumerador state](#enumeradores-state)** |

### Enumeradores state

| Enumerador         | Descrição             |
|--------------------|-----------------------|
| AC                 | Acre                  |
| AL                 | Alagoas               |
| AM                 | Amazonas              |
| AP                 | Amapá                 |
| BA                 | Bahia                 |
| CE                 | Ceará                 |
| DF                 | Distrito federal      |
| ES                 | Espírito Santo        |
| GO                 | Goiás                 |
| MA                 | Maranhão              |
| MG                 | Minas Gerais          |
| MS                 | Mato Grosso do Sul    |
| MT                 | Mato Grosso           |
| PA                 | Pará                  |
| PB                 | Paraíba               |
| PE                 | Pernambuco            |
| PI                 | Piauí                 |
| PR                 | Paraná                |
| RJ                 | Rio de Janeiro        |
| RN                 | Rio Grande do Norte   |
| RO                 | Rondônia              |
| RR                 | Roraima               |
| RS                 | Rio Grande do Sul     |
| SC                 | Santa Catarina        |
| SE                 | Sergipe               |
| SP                 | São Paulo             |
| TO                 | Tocantins             |
| EX                 | Exceção               |

### Objeto qr_code_data
| Campo                      | Tipo   | Descrição                                             | Caracteres              |
|----------------------------|--------|-------------------------------------------------------|-------------------------|
| `qr_code_key`              | uuidv4 | Chave única de identificação do QR Code               | 36                      |
| `pix_key`                  | uuidv4 | Chave PIX vinculada ao QR Code                        | 36                      |
| `receiver_conciliation_id` | uuidv4 | Identificador de conciliação do QR Code               | 36                      |
| `url`                      | string | URL (Pix Copia e Cola) do QR Code                     | -                       |
| `image`                    | string | base64 da URL (Pix Copia e Cola) do QR Code           | -                       |

### Objeto ou array payment_notice_data

:::caution Atenção!
O campo `payment_notice_data` será retornado como um **objeto** para boletos sem configuração de pagamento parcial. Para boletos com configuração de pagamento parcial, será retornado como um **array de objetos**, já que pode haver múltiplos pagamentos.
Além disso, caso o boleto seja pago via **QR Code**, esse campo não será retornado, dado que a liquidação ocorre no dia do pagamento.
:::

| Campo                     | Tipo    | Descrição                                                                     | Caracteres                                                                                      |
|---------------------------|---------|-------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| `payment_method`      | string  | Método de pagamento  | **[Enumeradores payment_method](#enumeradores-payment_method)** |
| `payment_origin`      | string  | Origem de pagamento       | **[Enumeradores payment_origin](#enumeradores-payment_origin)** |
| `payment_notice_date`      | string | Data do aviso do pagamento | 10

### Objeto ou array payment_data

:::caution Atenção!
O campo `payment_data` será retornado como um **objeto** para boletos sem configuração de pagamento parcial. Para boletos com configuração de pagamento parcial, será retornado como um **array de objetos**, já que pode haver múltiplos pagamentos.
:::

| Campo                     | Tipo    | Descrição                                                                     | Caracteres                                                                                      |
|---------------------------|---------|-------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| `paid_amount`         | float  | Valor do pagamento       | - |
| `paid_rebate_amount`       | float   | Valor pago de abatimento | -                                                                                               |
| `paid_discount_amount`      | float | Valor pago de desconto                    | -                                                                                               |
| `paid_fine_amount`      | float | Valor pago de multa                    | -
| `paid_interest_amount`      | float | Valor pago de juros                    | -
| `payment_method`      | string  | Método de pagamento  | **[Enumeradores payment_method](#enumeradores-payment_method)** |
| `payment_origin`      | string  | Origem de pagamento       | **[Enumeradores payment_origin](#enumeradores-payment_origin)** |
| `payment_credit_date`      | string | Data do crédito do pagamento | 10
| `payment_bank`      | object | Banco em que o boleto foi pago. Retornado somente após o pagamento do boleto | **[Objeto payment_bank](#objeto-payment_bank)** |
| `payment_branch`      | string | Agência em que o boleto foi pago. Retornado somente após o pagamento do boleto | -

:::info Informação
Os campos `payment_bank` e `payment_branch` só são retornados quando o boleto já foi pago, ou seja, quando existe uma ocorrência de pagamento confirmada. Enquanto o boleto não for pago, esses campos não estarão presentes na resposta.
:::

### Objeto payment_bank

| Campo  | Tipo    | Descrição                                  | Caracteres |
|--------|---------|--------------------------------------------|------------|
| `code` | string  | Código de compensação do banco (3 dígitos) | 3          |
| `ispb` | integer | ISPB do banco                              | 8          |
| `name` | string  | Nome do banco                              | -          |

### Enumeradores payment_method

| Enumerador         | Descrição                               |
|--------------------|-----------------------------------------|
| cash       | Espécie                  |
| account_debit             | Débito em conta                |
| credit_card      | Cartão de crédito |
| check          | Cheque                  |

### Enumeradores payment_origin

| Enumerador         | Descrição                               |
|--------------------|-----------------------------------------|
| cash       | Espécie                  |
| account_debit             | Débito em conta                |
| credit_card      | Cartão de crédito |
| check          | Cheque                  |

### Enumeradores payment_origin

| Enumerador           | Descrição                                |
|----------------------|------------------------------------------|
| phisical_cashier     | Agências - Postos tradicionais           |
| taa                  | Terminal de Auto-atendimento             |
| internet             | Internet (home/office bank)              |
| corban               | Correspondente bancário                  |
| call_center          | Central de atendimento (call center)     |
| eletronic_file       | Arquivo eletrônico                       |
| dda                  | DDA                                      |
| digital_correspondent| Correspondente Digital                   |
| qr_code              | Pagamento via Pix QR Code                |

### Objeto bank_slip_occurrence

| Campo                   | Tipo   | Descrição                                                                         | Caracteres |
|-------------------------|--------|-----------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4 | 36         |
| `occurrence_key` *      | uuidv4 | Chave única de identificação do boleto no formato uuid v4                         | 36         |
| `occurrence_type` *     | string | Tipo da ocorrência                                                                    | **[Enumerador occurrence_type](#enumeradores-occurrence_type)** |
| `occurrence_status` *   | string | Status da ocorrência                                                                  | **[Enumerador occurrence_status](#enumeradores-occurrence_status)** |
| `created_at` *          | string | Data, no formato ISO (UTC - "YYYY-MM-DDTHH:MM:SSZ"), da criação da ocorrência     | 20         |

### Enumeradores occurrence_type

| Enumerador         | Descrição                               |
|--------------------|-----------------------------------------|
| registration       | Ocorrência de registro                  |
| write_off          | Ocorrência de pedido de baixa           |
| rebate             | Ocorrência de adição de abatimento      |
| cancel_rebate      | Ocorrência de cancelamento de abatimento|
| discount           | Ocorrência de alteração de descontos    |
| fine               | Ocorrência de alteração de multa        |
| interest           | Ocorrência de alteração de juros        |
| extension          | Ocorrência de extensão                  |
| bank_slip_edit     | Ocorrência de alteração de outros dados do boleto |
| payment_notice     | Ocorrência de aviso de pagamento        |
| payment            | Ocorrência de liquidação do pagamento   |
| protest_request    | Ocorrência de pedido de protesto        |
| protest_request    | Ocorrência de pedido de protesto falimentar |

### Enumeradores occurrence_status

| Enumerador         | Descrição                               |
|--------------------|-----------------------------------------|
| pending            | Enviada para a Nuclea/CIP para análise  |
| rejected           | Rejeitada                               |
| confirmed          | Confirmada                              |

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (ptbr)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 404                      | BKS000006            | Not Found                                  | The source account key was not found.                                                                                | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                  | It was not possible to consult the source account at this time. Please try again in a few minutes.                                                                                      | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                                                                                    |
| 400                      | BKS000008            | Bad Request | The source account is closed.         |               A conta de origem está fechada.                                                                 |
| 400                      | BKS000009            | Bad Request | The source account is blocked.         |               A conta de origem está bloqueada.                                                                 |
| 404                      | BKS000013            | Not Found | Requester profile not found         |               Carteira não encontrada                                                                 |
| 400                      | BKS000022            | Bad Request                                        | Requester profile is not opened.                                                              | Carteira não está aberta.                          |
| 404                      | BKS000029            | Not Found                                        | Bank slip not found for the given key (`{bank_slip_key}`).                                                              | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`).                          |

---

# Listar boletos

URL: /documentation/boletos/consulta/listar_boletos

A listagem de boletos retornará todos os boletos da carteira que se enquadrarem nos query parameters enviados na request.

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slips
MÉTODO GET

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36         |

### Query parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres              |
|-------------------------|--------|--------------------------------------------------------------|-------------------------|
| `request_control_key`   | uuidv4 | Chave única de identificação da request, no formato uuid v4  | 36                      |
| `bank_slip_key`         | uuidv4 | Chave única de identificação do boleto, no formato uuid v4   | 36                      |
| `bank_slip_status`      | string | Status do boleto | **[Enumeradores bank_slip_status](#enumeradores-bank_slip_status)** |
| `page`                  | integer| Número da página                                             | -                       |
| `page_size`             | integer| Tamanho da página                                            | -                       |
| `from_date`             | string | Data de registro inicial (formato "AAAA-MM-DD")              | 10                      |
| `to_date`               | string | Data de registro final (formato "AAAA-MM-DD")                | 10                      |

### Enumeradores bank_slip_status

| Enumerador                   | Descrição                                                                      |
|------------------------------|--------------------------------------------------------------------------------|
| accepted                     | Aceito e enviado para a Nuclea/CIP para análise                                |
| rejected                     | Registro rejeitado pela Nuclea/CIP                                             |
| payment_notice               | Aviso de pagamento (boleto pago mas pagamento ainda não liquidado)             |
| notary_office_payment_notice | Aviso de pagamento em cartório (boleto pago mas pagamento ainda não liquidado) |
| registered                   | Registro confirmado pela Nuclea/CIP                                            |
| payment_blocked              | Bloqueado para pagamento (em fluxo de protesto)                                |
| paid                         | Pago                                                                           |
| written_off                  | Baixado                                                                        |

## Response

STATUS 200

Response Body

```json
{
  "data": [
    {
      "bank_slip_key": "b58ce415-5428-45c4-8e33-b2df0d3ab6e8",
      "request_control_key": "53529224-330d-44b5-9f4d-59d55bc3cb8c",
      "our_number": 24384760943,
      "document_number": "DOC4561237",
      "amount": "8000.00",
      "rebate_amount": "200.00",
      "expiration": "2024-07-13",
      "barcode": "32994978900005000000001594438621284040114400",
      "digitable_line": "32990001529443862128940401144007497890000500000",
      "bank_teller_instructions": "Confirm payment",
      "protest_data": {
        "days_to_protest": 7
      },
      "bankruptcy_protest_data": {
        "days_to_bankruptcy_protest": 14
      },
      "max_payment_days": 45,
      "fine_data": {
        "fine_type": "absolute",
        "fine_amount": 100.0,
        "days_to_fine": 10
      },
      "interest_data": {
        "interest_type": "workdays_daily_amount",
        "interest_amount": 5.0,
        "days_to_interest": 10
      },
      "discounts_data": [
        {
          "discount_type": "anticipation_workdays_daily_percentage",
          "discount_number": 1,
          "discount_limit_date": "2024-07-13",
          "discount_percentage": 10
        }
      ],
      "payer_data": {
        "name": "Country Tech",
        "address": {
          "city": "Innovation City",
          "state": "RS",
          "number": "202",
          "street": "101 High St.",
          "complement": "Building A",
          "postal_code": "57099999",
          "neighborhood": "Tech Park"
        },
        "person_type": "legal",
        "document_number": "12345678000195"
      },
      "guarantor_data": {
        "name": "Jamie Doe",
        "address": {
          "city": "Peaceful Town",
          "state": "MG",
          "number": "303",
          "street": "202 Elm St.",
          "complement": "House 1",
          "postal_code": "57099999",
          "neighborhood": "Quiet Neighborhood"
        },
        "person_type": "natural",
        "document_number": "98765432100"
      },
      "bank_slip_status": "paid",
      "payment_data": {
        "paid_amount": 8000.0,
        "payment_credit_date": "2024-07-15",
        "payment_date": "2024-07-14"
      }
    }
  ],
  "pagination": {
    "current_page": 1,
    "rows_per_page": 100
  }
}
```

### Response Body Params

| Campo            | Tipo         | Descrição                             | Caracteres                                  |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `data` *         | object array | Boletos                               | **[Objeto bank_slip](#objeto-bank_slip)**   |
| `pagination` *   | object       | Informações de paginação              | **[Objeto pagination](#objeto-pagination)** |

### Objeto bank_slip

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `bank_slip_key      ` *    | uuidv4  | Chave única de identificação do boleto no formato uuid v4                          | 36                                                |
| `request_control_key` *    | uuidv4  | Chave única de identificação da request utilizada pelo cliente no formato uuid v4  | 36                                                |
| `our_number` *             | integer | Número único de identificação do boleto junto à carteira                           | 11                                                |
| `bank_slip_status` *       | string | Status do boleto                                                                    | **[Enumeradores bank_slip_status](#enumeradores-bank_slip_status)** |
| `protest_status` *         | string | Status de protesto, em cartório, do boleto                                          | **[Enumeradores protest_status](#enumeradores-protest_status)** |
| `document_number` *        | string  | Número de identificação do boleto                                                  | 10                                                |
| `amount` *                 | float   | Valor base do boleto                                                               | -                                                 |
| `expiration` *             | string  | Data de vencimento                                                                 | 10                                                |
| `barcode` *               | string  | Código de barras do boleto                                                         | 44                                                |
| `digitable_line` *         | string  | Linha digitável do boleto                                                          | 47                                                |
| `bank_teller_instructions` | string  | Instruções adicionais de registro, que constarão no PDF do boleto                  | 320                                               |
| `rebate_amount`            | float   | Valor de abatimento do boleto, que será aplicado em cima do valor base             | -                                                 |
| `max_payment_days` *      | integer | Máximo de dias corridos que o boleto ficará disponível para pagamento, após o vencimento (pode ser no máximo 365) | -          |
| `write_off_data`       | object  | Configuração de baixa      | **[Objeto write_off_data](#objeto-write_off_settings)** |
| `protest_data`         | object  | Configuração de protesto       | **[Objeto protest_data](#objeto-protest_settings)** |
| `bankruptcy_protest_data` | object  | Configuração de protesto falimentar | **[Objeto bankruptcy_protest_data](#objeto-bankruptcy_protest_settings)** |
| `fine_data`            | object  | Configuração de multa                 | **[Objeto fine_data](#objeto-fine_settings)** |
| `interest_data`        | object  | Configuração de juros        | **[Objeto interest_data](#objeto-interest_settings)** |
| `discounts_data`           | object array | Descontos           | **[Objeto discount](#objeto-discounts_data)** |
| `payer_data` *             | object  | Dados do pagador                                                                   | **[Objeto payer_data](#objetos-payer_data-e-guarantor_data)** |
| `guarantor_data` *         | object  | Dados do sacador avalista                                                          | **[Objeto guarantor_data](#objetos-payer_data-e-guarantor_data)** |

### Objeto pagination

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `current_page` *           | integer | Página atual                                                 | -      |
| `rows_per_page` *          | integer | Itens por página                                             | -      |

### Enumeradores protest_status

| Enumerador                   | Descrição                                                                      |
|------------------------------|--------------------------------------------------------------------------------|
| not_protested                | Boleto sem fluxo de protesto iniciado                                          |
| protest_requested            | Protesto em cartório solicitado                                                |
| notary_office_entry          | Boleto no cartório, em período de tríduo                                       |
| protest_cancel_requested     | Desistência do protesto solicitada                                             |
| notary_office_exit           | Boleto saiu do cartório                                                        |
| protested                    | Boleto protestado                                                              |
| paid_at_notary_office        | Pago no cartório                                                               |
| judicially_suspended         | Protesto suspenso judicialmente                                                |
| protest_remove_requested     | Remoção do protesto solicitada                                                 |

### Objeto write_off_data

| Campo                     | Tipo    | Descrição                                                                   | Caracteres |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_write_off` *     | integer | Dias, após o vencimento, para que o boleto seja baixado automaticamente     | -          |

### Objeto protest_data

| Campo                     | Tipo    | Descrição                                                                   | Caracteres |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_protest` *       | integer | Dias, após o vencimento, para que o boleto seja protestado automaticamente  | -          |

### Objeto bankruptcy_protest_data

| Campo                          | Tipo    | Descrição                                                                   | Caracteres  |
|--------------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_bankruptcy_protest` * | integer | Dias, após o vencimento, para que o boleto seja protestado automaticamente  | -           |

### Objeto fine_data

Opção 1: multa em valor absoluto (`fine_type=absolute`)

| Campo                     | Tipo    | Descrição                                               | Caracteres                |
|---------------------------|---------|---------------------------------------------------------|-------------------------------------------------------------------------|
| `fine_type` *             | string  | Tipo da multa                                                       | **[Enumeradores fine_type](#enumeradores-fine_type)**                                              |
| `fine_amount` *           | float   | Valor absoluto da multa                                             | -                                                                        |
| `days_to_fine` *          | integer | Dias, após o vencimento, para que a multa seja cobrada              | -                                                                        |

Opção 2: multa em valor percentual (`fine_type=percentage`)

| Campo                     | Tipo    | Descrição                                                 | Caracteres                             |
|---------------------------|---------|-----------------------------------------------------------|---------------------------------------|
| `fine_type` *             | string  | Tipo da multa                                             | **[Enumeradores fine_type](#enumeradores-fine_type)** |
| `fine_percentage` *       | integer | Valor percentual da multa, de 1 a 100                     | -                                      |
| `days_to_fine` *          | integer | Dias, após o vencimento, para que a multa seja cobrada    | -                                      |

### Enumeradores fine_type

| Enumerador         | Descrição             |
|--------------------|-----------------------|
| absolute           | valor absoluto        |
| percentage         | valor percentual      |

### Objeto interest_data

Opção 1: juros utilizando valores absolutos (`interest_type=calendar_days_daily_amount` ou `interest_type=workdays_daily_amount`)

| Campo                     | Tipo    | Descrição                                                                     | Caracteres                                                                                      |
|---------------------------|---------|-------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| `interest_type` *         | string  | Tipo de juros       | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_amount` *       | float   | Valor a ser cobrado por unidade de tempo determinada (dias úteis ou corridos) | -                                                                                               |
| `days_to_interest` *      | integer | Dias, após o vencimento, para que comece a cobrar os juros                    | -                                                                                               |

Opção 2: juros utilizando valores percentuais (`interest_type=calendar_days_monthly_percentage`)

| Campo                    | Tipo    | Descrição                                                                             | Caracteres                                                                                          |
|--------------------------|---------|---------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
| `interest_type` *        | string  | Tipo de juros       | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_percentage` *  | integer | Porcentagem a ser cobrada por unidade de tempo determinada (dias úteis ou corridos)                                                                      | -                                                                           |
| `days_to_interest` *     | integer | Dias, após o vencimento, para que comece a cobrar os juros                             | -                                                                                                   |

### Enumeradores interest_type

| Enumerador                       | Descrição                                                            |
|----------------------------------|----------------------------------------------------------------------|
| calendar_days_daily_amount       | Valor diário sobre dias corridos                                     |
| workdays_daily_amount            | Valor diário sobre dias úteis                                        |
| calendar_days_monthly_percentage | Porcentagem de juros cobrados mensalmente, com base em dias corridos |

### Objeto discount

Opção 1: descontos utilizando valores absolutos (`discount_type in ["absolute", "anticipation_calendar_days_daily_amount", "anticipation_workdays_daily_amount"]`)

| Campo                     | Tipo    | Descrição                                           | Caracteres                                                |
|---------------------------|---------|-----------------------------------------------------|-----------------------------------------------------------|
| `discount_amount` *       | float   | Valor absoluto de desconto por unidade de tempo                                            | -                                                          |
| `discount_number` *       | integer | Número do desconto                                     | -                                                         |
| `discount_type` *         | string  | Configuração do desconto em valores absolutos                                    | **[Enumerador discount_type](#enumeradores-discount_type)** |                                                       |
| `discount_limit_date` *   | string  | Data limite para aplicação do desconto   | 10                                                        |

Opção 2: descontos utilizando valores percentuais (`discount_type in ["percentage", "anticipation_calendar_days_daily_percentage", "anticipation_workdays_daily_percentage"]`)

| Campo                     | Tipo    | Descrição                                           | Caracteres                                                |
|---------------------------|---------|-----------------------------------------------------|-----------------------------------------------------------|
| `discount_percentage` *   | float   | Valor percentual de desconto por unidade de tempo                                            | -                                                          |
| `discount_number` *       | integer | Número do desconto                                     | -                                                         |
| `discount_type` *         | string  | Configuração do desconto em valores percentuais                                    | **[Enumerador discount_type](#enumeradores-discount_type)** |                                                       |
| `discount_limit_date` *   | string  | Data limite para aplicação do desconto   | 10                                                        |

:::caution Atenção!
O boleto pode ter até três descontos, sendo que os descontos devem ser todos do mesmo tipo , isto é, devem ter o mesmo `discount_type`. Os descontos devem ser numerados de 1 a 3, de maneira crescente e começando necessariamente em 1. Ou seja, caso sejam enviados dois descontos na requisição, devem necessariamente ser numerados com 1 e 2.
:::

### Enumeradores discount_type

| Enumerador                                  | Descrição                                                                |
|---------------------------------------------|--------------------------------------------------------------------------|
| absolute                                    | Valor fixo                                                               |
| anticipation_calendar_days_daily_amount     | Valor diário de desconto de antecipação, sobre dias corridos             |
| anticipation_workdays_daily_amount          | Valor diário de desconto de antecipação, sobre dias úteis                |
| percentage                                  | Porcentagem fixa                                                         |
| anticipation_calendar_days_daily_percentage | Porcentagem mensal de desconto de antecipação, com base em dias corridos |
| anticipation_workdays_daily_percentage      | Porcentagem anual de desconto de antecipação, com base em dias úteis     |

### Objetos payer_data e guarantor_data

| Campo                     | Tipo   | Descrição                                                  | Caracteres|
|---------------------------|--------|-------------------------------------|-----------------------------------------------------------|
| `name` *                  | string | Nome completo                       | 100                                                       |
| `document_number` *       | string | Número do documento (CPF/CNPJ)      | 11 ou 14                                                  |
| `person_type` *           | string | Tipo da pessoa (física ou jurídica) | **[Enumeradores person_type](#enumeradores-person_type)** |
| `contact`                 | object | Informações de contato              | **[Objeto contact](#objeto-contact)**                     |
| `address`                 | object | Endereço                            | **[Objeto address](#objeto-address)**                     |

### Enumeradores person_type

| Enumerador         | Descrição             |
|--------------------|-----------------------|
| natural            | pessoa física         |
| legal              | pessoa jurídica       |

### Objeto contact

| Campo                     | Tipo   | Descrição                         | Caracteres                         |
|---------------------------|--------|-----------------------------------|------------------------------------|
| `email`                   | string | E-mail de contato                 | 320                                |
| `phone`                   | object | Telefone de contato               | **[Objeto phone](#objeto-phone)**  |

### Objeto phone

| Campo                           | Tipo   | Descrição                                    | Caracteres |
|---------------------------------|--------|----------------------------------------------|------------|
| `international_dial_code` *     | string | Código DDI (Discagem Direta Internacional)   | 3          |
| `area_code` *                   | string | Código DDD (Discagem Direta à Distância)     | 2          |
| `number` *                      | string | Complemento                                  | 9          |

### Objeto address

| Campo                     | Tipo   | Descrição                                    | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `street` *                | string | Logradouro                                   | 500        |
| `number` *                | string | Número                                       | 6          |
| `complement`              | string | Complemento                                  | 500        |
| `neighborhood` *          | string | Bairro                                       | 100        |
| `postal_code` *           | string | CEP                                          | 8          |
| `city` *                  | string | Cidade                                       | 100        |
| `state` *                 | string | Estado (UF) | **[Enumerador state](#enumeradores-state)** |

### Enumeradores state

| Enumerador         | Descrição             |
|--------------------|-----------------------|
| AC                 | Acre                  |
| AL                 | Alagoas               |
| AM                 | Amazonas              |
| AP                 | Amapá                 |
| BA                 | Bahia                 |
| CE                 | Ceará                 |
| DF                 | Distrito federal      |
| ES                 | Espírito Santo        |
| GO                 | Goiás                 |
| MA                 | Maranhão              |
| MG                 | Minas Gerais          |
| MS                 | Mato Grosso do Sul    |
| MT                 | Mato Grosso           |
| PA                 | Pará                  |
| PB                 | Paraíba               |
| PE                 | Pernambuco            |
| PI                 | Piauí                 |
| PR                 | Paraná                |
| RJ                 | Rio de Janeiro        |
| RN                 | Rio Grande do Norte   |
| RO                 | Rondônia              |
| RR                 | Roraima               |
| RS                 | Rio Grande do Sul     |
| SC                 | Santa Catarina        |
| SE                 | Sergipe               |
| SP                 | São Paulo             |
| TO                 | Tocantins             |
| EX                 | Exceção               |

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 403                      | BKS000005            | Forbidden                         | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404                      | BKS000006            | Not Found                                  | The source account key was not found.                                                                                | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                  | It was not possible to consult the source account at this time. Please try again in a few minutes.                                                                                      | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                                                                                    |
| 400                      | BKS000008            | Bad Request | The source account is closed.         |               A conta de origem está fechada.                                                                 |
| 400                      | BKS000009            | Bad Request | The source account is blocked.         |               A conta de origem está bloqueada.                                                                 |
| 400                      | BKS000012            | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
| 404                      | BKS000013            | Not Found | Requester profile not found         |               Carteira não encontrada                                                                 |

---

# Consulta de carteiras de cobrança

URL: /documentation/boletos/consultar_v1/consulta_de_carteira

## Request

ENDPOINT /bank_slip/requester_profiles
MÉTODO GET

## Response

STATUS 200

Response Body

```json
{
    "requester_profile_codes": [
        "329-09-0001-1467576",
        "329-09-0001-5747500",
        "329-09-0001-2730579",
        "329-09-0001-2359934"
    ]
}
```

---

# Consultar arquivo retorno

URL: /documentation/boletos/consultar_v1/consultar_arquivo_retorno

:::info Aviso
Para garantir que o arquivo retorno para o dia corrente estará com as informações atualizadas verifique se as
informações do dia foram conciliadas através de pooling como apresentado em [Rotina de conciliação de arquivo retorno](/documentation/boletos/consultar/rotina_de_conciliacao_de_arquivo_retorno)
:::

## Request

ENDPOINT /bank_slip/requester_profile/ REQUESTER_PROFILE_CODE /cnab_files
MÉTODO GET

### Path params

| Campo                      | Tipo   | Descrição                       | Caracteres |
|----------------------------|--------|---------------------------------|------------|
| `requester_profile_code` * | string | Código da carteira de cobrança. | 10         |

### Query params

| Campo         | Tipo   | Descrição                          | Caracteres                                  |
|---------------|--------|------------------------------------|---------------------------------------------|
| `cnab_type` * | enum   | Tipo de Arquivo                    | **[Enumeradores](#enumeradores-cnab_type)** |
| `from` *      | string | Início do período a ser analisado. | 10                                          |
| `to` *        | string | Fim do período a ser analisado.    | 10                                          |

### Enumeradores cnab_type

| Campo               | Descrição          | 
|---------------------|--------------------|
| requester_discharge | Arquivo de retorno | 

## Response

STATUS 200

Response Body

```json
{
  "data": [
    {
      "cnab_key": "47361262-0853-4c51-9c2a-5284e0d8a5e1",
      "company_code": null,
      "created_at": "2020-05-06T11:04:25",
      "downloads": [],
      "file_size": "None",
      "filename": "CNAB.RET",
      "line_length": "400",
      "remitter_key": "ab871cc8-8369-4b72-95f1-b074b30c7208",
      "requester_profile_code": "329-01-0001-0000002",
      "type": {
        "created_at": "2019-03-12T12:59:32",
        "enumerator": "requester_discharge",
        "translation_path": "bank_slip.CNABFileType.requester_discharge"
      },
      "url": "https://linkparadownload.com/CNAB.RET",
      "version": "11"
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "rows_per_page": 100,
    "total_pages": 1,
    "total_rows": 1
  }
}

```

STATUS 400

Response Body

```json

{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

---

# Consultar boleto

URL: /documentation/boletos/consultar_v1/consultar_boleto

## Request

ENDPOINT /bank_slip/ BANK_SLIP_KEY
MÉTODO GET

### Path params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `bank_slip_key` *| string | Chave de identificação do boleto | chave uuid |

## Response

STATUS 200

Response Body

```json
{
    "amount": 3,
    "asset_type": {
        "created_at": "2019-02-01T16:44:11",
        "enumerator": "invoice",
        "translation_path": "bank_slip.AssetType.invoice"
    },
    "automatic_bankruptcy_protest": true,
    "automatic_protest": false,
    "automatic_write_off": false,
    "bank_slip_file": [],
    "bank_slip_key": "96b32f1a-c2bd-41a4-b4b1-a169235be68b",
    "bank_slip_status": {
        "created_at": "2019-02-01T16:44:07",
        "enumerator": "registered",
        "translation_path": "bank_slip.BankSlipStatus.registered"
    },
    "bank_teller_instructions": "Não aceitar após vencimento",
    "barcode": "32991918600000900000001090000000000457475000",
    "beneficiary_account_branch": "0001",
    "beneficiary_account_digit": "5",
    "beneficiary_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
    "beneficiary_account_number": "5747500",
    "beneficiary_document_number": "12345678905",
    "beneficiary_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
    "beneficiary_name": "Greg Brown",
    "billing_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
    "business_date_expiration": "2020-06-01",
    "created_at": "2020-05-15T21:00:25",
    "days_before_fine": null,
    "days_before_interest": null,
    "days_to_bankruptcy_protest": 1,
    "days_to_protest": null,
    "days_to_write_off": null,
    "digitable_line": "32990001039000000000104574750008191860000090000",
    "discount_limit_date": null,
    "discount_value": null,
    "discounts": [],
    "document_number": "123456/01",
    "expenses": [
        {
            "amount": 3.9,
            "created_at": "2022-11-19T10:42:47",
            "expense_key": "6f21f308-f6c6-4198-a8bc-bc0e853bb8b5",
            "paid": true,
            "reason": {
                "created_at": "2019-02-14T17:30:50",
                "reason_code": "Tarifa de registro",
                "translation_en_us": "Registration Fee",
                "translation_pt_br": "Tarifa de registro"
            },
            "subject": {
                "created_at": "2019-02-14T17:30:43",
                "enumerator": "requester",
                "translation_path": "bank_slip.AssetType.requester"
            },
            "subject_account_key": "9223d7ae-320a-411c-8ff4-861e054da4d4",
            "updated_at": "2022-11-19T10:46:31"
        }
    ],
    "expiration": "2020-06-01",
    "fine_percentage": 0.1,
    "guarantor_address": null,
    "guarantor_city": null,
    "guarantor_document": null,
    "guarantor_name": null,
    "guarantor_person_type": null,
    "guarantor_postal_code": "00000000",
    "guarantor_state": null,
    "has_protest_pending_feedback": false,
    "historical_our_number": 2,
    "institution_registration_date": null,
    "interest_daily_value": 0.34,
    "lock_origin_type": null,
    "max_payment_days": 180,
    "nfe_key": null,
    "nfe_url": null,
    "notary_office_number": null,
    "notary_office_protocol": null,
    "notification": [],
    "occurrences": [
        {
            "agent_type": "integration",
            "automatic_bankruptcy_protest": null,
            "automatic_protest": null,
            "automatic_write_off": null,
            "created_at": "2020-05-15T21:00:25",
            "discount_amount": null,
            "discounts": [],
            "fine_percentage": 2,
            "interest_daily_value": 0.34,
            "iof_amount": null,
            "new_bank_slip_status": {
                "created_at": "2019-02-14T17:30:39",
                "enumerator": "registered",
                "translation_path": "bank_slip.BankSlipStatus.registered"
            },
            "new_due_date": "2020-06-01",
            "new_protest_status": {
                "created_at": "2019-02-01T16:44:08",
                "enumerator": "not_protested",
                "translation_path": "bank_slip.ProtestStatus.not_protested"
            },
            "notary_office_number": null,
            "notary_office_protocol": null,
            "notification": [],
            "occurrence_expenses": null,
            "occurrence_feedback": {
                "created_at": "2019-02-14T17:30:46",
                "enumerator": "confirmed",
                "translation_path": "bank_slip.OccurrenceFeedback.confirmed"
            },
            "occurrence_key": "c3ab3e01-f198-4e7e-9e01-7a8091b8bd72",
            "occurrence_reasons": [],
            "occurrence_type": {
                "created_at": "2019-02-01T16:44:14",
                "enumerator": "registration",
                "translation_path": "bank_slip.OccurrenceType.registration"
            },
            "old_bank_slip_status": {
                "created_at": "2019-02-01T16:44:07",
                "enumerator": "accepted",
                "translation_path": "bank_slip.BankSlipStatus.accepted"
            },
            "old_due_date": null,
            "old_protest_status": null,
            "paid_amount": null,
            "paid_fine_amount": null,
            "paid_interest_amount": null,
            "payer_address": null,
            "payer_postal_code": null,
            "payment_bank": null,
            "payment_branch": null,
            "payment_credit_date": null,
            "payment_method": null,
            "payment_origin": null,
            "protest_confirmation": null,
            "protest_distribution_cost": null,
            "protest_electronic_cost": null,
            "protest_emolument": null,
            "protest_expenses": null,
            "protest_other_expenses": null,
            "protocol_date": null,
            "protocol_region": null,
            "rebate_amount": null,
            "registration_institution_occurrence_date": "2020-05-15",
            "registration_institution_occurrence_event": [
                {
                    "cnab_file": {
                        "cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
                        "company_code": null,
                        "created_at": "2020-05-15T21:00:22",
                        "downloads": [],
                        "file_size": "None",
                        "filename": null,
                        "line_length": null,
                        "remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
                        "requester_profile_code": null,
                        "type": {
                            "created_at": "2019-02-01T16:44:17",
                            "enumerator": "api_instruction",
                            "translation_path": "bank_slip.CNABFileType.api_instruction"
                        },
                        "url": null,
                        "version": null
                    },
                    "cnab_file_occurrence_order": 1,
                    "created_at": "2020-05-15T21:00:25",
                    "new_status": {
                        "created_at": "2019-02-01T16:44:15",
                        "enumerator": "waiting_submission",
                        "translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
                    },
                    "old_status": null
                }
            ],
            "registration_institution_occurrence_status": {
                "created_at": "2019-02-01T16:44:15",
                "enumerator": "waiting_submission",
                "translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
            },
            "requester_occurrence_event": [
                {
                    "cnab_file": {
                        "cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
                        "company_code": null,
                        "created_at": "2020-05-15T21:00:22",
                        "downloads": [],
                        "file_size": "None",
                        "filename": null,
                        "line_length": null,
                        "remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
                        "requester_profile_code": null,
                        "type": {
                            "created_at": "2019-02-01T16:44:17",
                            "enumerator": "api_instruction",
                            "translation_path": "bank_slip.CNABFileType.api_instruction"
                        },
                        "url": null,
                        "version": null
                    },
                    "cnab_file_occurrence_order": 1,
                    "created_at": "2020-05-15T21:00:25",
                    "new_status": {
                        "created_at": "2019-02-01T16:44:16",
                        "enumerator": "confirmed",
                        "translation_path": "bank_slip.RequesterOccurrenceStatus.confirmed"
                    },
                    "old_status": {
                        "created_at": "2019-02-01T16:44:16",
                        "enumerator": "accepted",
                        "translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
                    }
                }
            ],
            "requester_occurrence_status": {
                "created_at": "2019-02-01T16:44:16",
                "enumerator": "confirmed",
                "translation_path": "bank_slip.RequesterOccurrenceStatus.confirmed"
            },
            "selected_user_agent": null
        }
    ],
    "original_expiration": "2022-12-01",
    "our_number": 2,
    "paid_amount": null,
    "paid_fine_amount": null,
    "paid_interest_amount": null,
    "participant_control_number": null,
    "payer_account_digit": null,
    "payer_account_number": null,
    "payer_account_type": null,
    "payer_address": "Rua Carlos Tampaio, 112",
    "payer_bank": null,
    "payer_branch_digit": null,
    "payer_branch_number": null,
    "payer_document": "45508922008",
    "payer_name": "John Nobody",
    "payer_person_type": {
        "created_at": "2019-02-01T16:44:09",
        "enumerator": "natural",
        "translation_path": "bank_slip.PersonType.natural"
    },
    "payer_postal_code": "00000000",
    "payment_date": null,
    "printing_policy": {
        "created_at": "2019-02-01T16:44:10",
        "enumerator": "no_printing",
        "translation_path": "bank_slip.PrintingPolicy.no_printing"
    },
    "protest_status": {
        "created_at": "2019-02-01T16:44:08",
        "enumerator": "not_protested",
        "translation_path": "bank_slip.ProtestStatus.not_protested"
    },
    "protocol_date": null,
    "protocol_region": null,
    "qr_code": null,
    "rebate_amount": null,
    "reference_requester_profile_code": null,
    "registration_institution": {
        "created_at": "2020-03-26T19:36:16",
        "enumerator": "qi_scd",
        "febraban_code": "329",
        "remittance_sequence": 72,
        "settlement_resource_account_key": "3e46d266-4fdb-4fd2-b87a-3e3de366afd4"
    },
    "requester_profile": 1,
    "requester_profile_code": "329-01-0001-0067049",
    "requester_registration_date": "2020-05-15",
    "settlement_account_key": "9223d7ae-320a-411c-8ff4-861e054da4d4",
    "settlements": [],
    "tags": null
}
```

STATUS 400

Response Body

```json
{
    {"title": "Bad Request", "description": "Invalid request body.", "translation": "Corpo da requisição inválido.", "extra_fields": {}, "code": "LEG000069"}
    
}
```

---

# Emitir PDF

URL: /documentation/boletos/consultar_v1/emitir_pdf

## Request

ENDPOINT /bank_slip/2-way/ BANK_SLIP_KEY
MÉTODO GET

### Path params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `BANK_SLIP_KEY` *|  string | Chave de identificação do boleto. | 10 |

## Response

STATUS 200

Response Body

```json
[
  {
    "barcode": "32998827300000003000001010000000000200670490",
    "created_at": "2020-05-19T18:46:41",
    "digitable_line": "32990001031000000000902006704908882730000000300",
    "url": "https://linkparadownload.com/arquivo.pdf"
  }
]
```

STATUS 400

Response Body

```json

    { }
    

```

---

# Francesinha

URL: /documentation/boletos/consultar_v1/francesinha

## Request

- ENDPOINT /bank_slip/little_french
- MÉTODO GET

### Body params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `requester_profile_code` *| string |  Código da carteira. | 10 | 
| `date` | date |  Data para a geração do relatorio, caso nulo, a data do relatório será HOJE (Formato YYYY-MM-DD). |  10 | 

## Response

status: 200

Body.json

    O body de resposta da francesinha será um arquivo excel encodado em base64.

status: 400

Body.json

```json

    { }
    

```

---

# Listar boletos

URL: /documentation/boletos/consultar_v1/listar_boletos

## Request

ENDPOINT /bank_slip/person/ BENEFICIARY_KEY
MÉTODO GET

:::caution **Atenção**

Note que em ambos os exemplos a lista bank_slip_file é vazia. Isto significa que não existe um arquivo pdf para este boleto. Caso o cliente deseje uma via PDF do boleto explicaremos como fazê-lo nos próximos passos.
:::

### Path params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `beneficiary_key` *| string | Chave de identificação do beneficiário | chave uuid |

### Query params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `payer_document` | string | Número do documento do pagador | - |
| `bank_slip_status` | enum | Status do boleto. | **[Enumeradores](#enumeradores-bank_slip_status)** | 
| `requester_profile` | string | Número da carteira de boletos| - |
| `protest_status` | enum | Status de protesto. | **[Enumeradores](#enumeradores-protest_status)** |
| `from` | date | Data inicial de criação do boleto. | 10 |
| `to` |  date | Data final de criação do boleto. | 10 |
| `number_search` | string | Nosso número (our_number) ou numero do documento (document_number). | - |
| `page` | integer | Pagina a ser consultada >= 1. | - |
| `page_size` | integer | Número máximo de registros retornados \<\= 100. | - |

### Enumeradores bank_slip_status
| Campo | Descrição | 
|---|---|
| accepted | Boleto na fila para registro | 
| rejected | Boleto rejeitado | 
| registered | Boleto registrado (disponível para pagamento) | 
| payment_notice | Boleto pago - mas sem liquidação financeira | 
| notary_office_payment_notice | rejected | 
| paid | Boleto pago - baixado com liquidação financeira. | 
| written_off | Boleto baixado sem liquidação financeira. | 

### Enumeradores protest_status
| Campo | Descrição | 
|---|---|
| accepted | Boleto na fila para registro | 

## Response

STATUS 200

Response Body

```json

{
  "data": [
    {
      "amount": 3,
      "asset_type": {
        "created_at": "2019-02-01T16:44:11",
        "enumerator": "invoice",
        "translation_path": "bank_slip.AssetType.invoice"
      },
      "automatic_bankruptcy_protest": true,
      "automatic_protest": false,
      "automatic_write_off": false,
      "bank_slip_file": [],
      "bank_slip_key": "96b32f1a-c2bd-41a4-b4b1-a169235be68b",
      "bank_slip_status": {
        "created_at": "2019-02-01T16:44:07",
        "enumerator": "accepted",
        "translation_path": "bank_slip.BankSlipStatus.accepted"
      },
      "bank_teller_instructions": "Não aceitar após vencimento",
      "beneficiary_account_branch": "0001",
      "beneficiary_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
      "beneficiary_account_number": "67049",
      "beneficiary_document_number": "12345678905",
      "beneficiary_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
      "beneficiary_name": "Greg Brown",
      "billing_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
      "business_date_expiration": "2020-06-01",
      "created_at": "2020-05-15T21:00:25",
      "days_before_fine": null,
      "days_before_interest": null,
      "days_to_bankruptcy_protest": 1,
      "days_to_protest": null,
      "days_to_write_off": null,
      "discount_limit_date": null,
      "discount_value": null,
      "document_number": "123456/01",
      "expenses": [],
      "expiration": "2020-06-01",
      "fine_percentage": 0.1,
      "guarantor_address": null,
      "guarantor_city": null,
      "guarantor_document": null,
      "guarantor_name": null,
      "guarantor_person_type": null,
      "guarantor_postal_code": "00000000",
      "guarantor_state": null,
      "historical_our_number": 2,
      "institution_registration_date": null,
      "interest_daily_value": 0.34,
      "lock_origin_type": null,
      "nfe_key": null,
      "nfe_url": null,
      "occurrences": [
        {
          "created_at": "2020-05-15T21:00:25",
          "discount_amount": null,
          "discount_limit_date": null,
          "iof_amount": null,
          "new_bank_slip_status": null,
          "new_due_date": "2020-06-01",
          "new_protest_status": {
            "created_at": "2019-02-01T16:44:08",
            "enumerator": "not_protested",
            "translation_path": "bank_slip.ProtestStatus.not_protested"
          },
          "notary_office_number": null,
          "notary_office_protocol": null,
          "occurrence_expenses": null,
          "occurrence_feedback": null,
          "occurrence_key": "c3ab3e01-f198-4e7e-9e01-7a8091b8bd72",
          "occurrence_reasons": [],
          "occurrence_type": {
            "created_at": "2019-02-01T16:44:14",
            "enumerator": "registration",
            "translation_path": "bank_slip.OccurrenceType.registration"
          },
          "old_bank_slip_status": {
            "created_at": "2019-02-01T16:44:07",
            "enumerator": "accepted",
            "translation_path": "bank_slip.BankSlipStatus.accepted"
          },
          "old_due_date": null,
          "old_protest_status": null,
          "paid_amount": null,
          "paid_fine_amount": null,
          "paid_interest_amount": null,
          "payment_bank": null,
          "payment_branch": null,
          "payment_credit_date": null,
          "payment_method": null,
          "payment_origin": null,
          "protest_confirmation": null,
          "protest_expenses": null,
          "rebate_amount": null,
          "registration_institution_occurrence_date": "2020-05-15",
          "registration_institution_occurrence_event": [
            {
              "cnab_file": {
                "cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
                "company_code": null,
                "created_at": "2020-05-15T21:00:22",
                "downloads": [],
                "file_size": "None",
                "filename": null,
                "line_length": null,
                "remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
                "requester_profile_code": null,
                "type": {
                  "created_at": "2019-02-01T16:44:17",
                  "enumerator": "api_instruction",
                  "translation_path": "bank_slip.CNABFileType.api_instruction"
                },
                "url": null,
                "version": null
              },
              "cnab_file_occurrence_order": 1,
              "created_at": "2020-05-15T21:00:25",
              "new_status": {
                "created_at": "2019-02-01T16:44:15",
                "enumerator": "waiting_submission",
                "translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
              },
              "old_status": null
            }
          ],
          "registration_institution_occurrence_status": {
            "created_at": "2019-02-01T16:44:15",
            "enumerator": "waiting_submission",
            "translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
          },
          "requester_occurrence_event": [
            {
              "cnab_file": {
                "cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
                "company_code": null,
                "created_at": "2020-05-15T21:00:22",
                "downloads": [],
                "file_size": "None",
                "filename": null,
                "line_length": null,
                "remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
                "requester_profile_code": null,
                "type": {
                  "created_at": "2019-02-01T16:44:17",
                  "enumerator": "api_instruction",
                  "translation_path": "bank_slip.CNABFileType.api_instruction"
                },
                "url": null,
                "version": null
              },
              "cnab_file_occurrence_order": 1,
              "created_at": "2020-05-15T21:00:25",
              "new_status": {
                "created_at": "2019-02-01T16:44:16",
                "enumerator": "accepted",
                "translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
              },
              "old_status": null
            }
          ],
          "requester_occurrence_status": {
            "created_at": "2019-02-01T16:44:16",
            "enumerator": "accepted",
            "translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
          }
        }
      ],
      "our_number": 2,
      "paid_amount": null,
      "paid_fine_amount": null,
      "paid_interest_amount": null,
      "participant_control_number": null,
      "payer_account_digit": null,
      "payer_account_number": null,
      "payer_account_type": null,
      "payer_address": "Rua Carlos Tampaio, 112",
      "payer_bank": null,
      "payer_branch_digit": null,
      "payer_branch_number": null,
      "payer_document": "45508922008",
      "payer_name": "John Nobody",
      "payer_person_type": {
        "created_at": "2019-02-01T16:44:09",
        "enumerator": "natural",
        "translation_path": "bank_slip.PersonType.natural"
      },
      "payer_postal_code": "00000000",
      "payment_date": null,
      "printing_policy": {
        "created_at": "2019-02-01T16:44:10",
        "enumerator": "no_printing",
        "translation_path": "bank_slip.PrintingPolicy.no_printing"
      },
      "protest_status": {
        "created_at": "2019-02-01T16:44:08",
        "enumerator": "not_protested",
        "translation_path": "bank_slip.ProtestStatus.not_protested"
      },
      "rebate_amount": null,
      "registration_institution": {
        "created_at": "2020-03-26T19:36:16",
        "enumerator": "qi_scd",
        "febraban_code": "329",
        "remittance_sequence": 72,
        "settlement_resource_account_key": "3e46d266-4fdb-4fd2-b87a-3e3de366afd4"
      },
      "requester_profile": 1,
      "requester_profile_code": "329-01-0001-0067049",
      "requester_registration_date": "2020-05-15"
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "rows_per_page": 100,
  },
  "totals": {
    "delayed_bank_slip_amount": 0,
    "delayed_bank_slip_number": 0,
    "due_bank_slip_amount": 3,
    "due_bank_slip_number": 2,
    "paid_bank_slip_amount": 0,
    "paid_bank_slip_number": 0,
    "total_bank_slip_amount": 3,
    "total_bank_slip_number": 1,
    "written_off_bank_slip_amount": 0,
    "written_off_bank_slip_number": 0
  }
}
```

STATUS 400

Response Body

```json
{
    {"title": "Bad Request", "description": "Invalid request body.", "translation": "Corpo da requisição inválido.", "extra_fields": {}, "code": "LEG000069"}
    
}
```

:::danger Observações Gerais:
- O tamanho máximo da página (page_size) é 100.
- Caso o número de registros retornados na página corrente seja menor que o page_size o atributo next_page virá nulo.
:::

---

# Relatório de posição diária em Excel

URL: /documentation/boletos/consultar_v1/posicao_diaria_excel

## Request

ENDPOINT /bank_slip/duplicates_balance_excel
MÉTODO GET

:::caution Atenção
O body de resposta desta request será um arquivo excel encodado em base64.
:::

### Query params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `beneficiary_key` | string | Chave de identificação do beneficiário (obrigatória caso não haja um requester_profile_code). | chave uuid | 
| `requester_profile_code` | string | Código da carteira (obrigatório caso não haja uma beneficiary_key). | 10 | 
| `expiration_date` | date | Data máxima de vencimento (Formato YYYY-MM-DD). | 10 | 
| `content_type` | string | Filtra os boletos incluídos no relatório pelo status. Valores aceitos: `paid`, `unpaid`, `expired`, `written_off`. | - | 

## Response

STATUS 200

Response Body

```json

O body de resposta desta request será um arquivo excel encodado em base64.

```

STATUS 400

Response Body

```json

{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
  
```

---

# Relatório de posição diária em JSON

URL: /documentation/boletos/consultar_v1/posicao_diaria_json

## Request

ENDPOINT /bank_slip/duplicates_balance
MÉTODO GET

### Query params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `beneficiary_key` | string | Chave de identificação do beneficiário (obrigatória caso não haja um requester_profile_code). | 10 | 
| `requester_profile_code` | string | Código da carteira (obrigatório caso não haja uma beneficiary_key). | 10 | 
| `expiration_date` | date | Data máxima de vencimento (Formato YYYY-MM-DD). | 10 | 

## Response

STATUS 200

Response Body

```json

{
  "expire_after_90_days": 0,
  "expire_between_31_and_60_days": 0,
  "expire_between_61_and_90_days": 0,
  "expire_in_30_days": 0,
  "expired": 3,
  "expired_in_notary_office": 0,
  "expired_not_in_notary_office": 0,
  "paid": 0,
  "paid_after_due_date": 2,
  "paid_before_due_date": 0,
  "paid_on_due_date": 0,
  "to_expire": 0,
  "unpaid": 0
}
    

```

STATUS 400

Response Body

```json

{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
    

```

---

# Rotina de conciliação de arquivo retorno

URL: /documentation/boletos/consultar_v1/rotina_de_conciliacao_de_arquivo_retorno

Diariamente ocorre a conciliação de retornos para os boletos. Para garantir que os dados do dia estão atualizados,
utilize o endpoint especificado nesta página para verificar se os arquivos retorno estão disponíveis para
consulta. Recomendamos que o pooling seja feito a uma frequência não superior a uma requisição 2 minutos.

## Request

ENDPOINT /bank_slip/cnab_discharge_status
MÉTODO GET

## Response

STATUS 200

Response Body: Rotina concluída

```json
{
  "discharge_ready": true
}
```

Response Body: Rotina pendente

```json
{
  "discharge_ready": false
}
```

---

# Solicitar 2ª via de boleto

URL: /documentation/boletos/consultar_v1/segunda_via_de_boleto

## Request

ENDPOINT /bank_slip/2-way/ BANK_SLIP_KEY
MÉTODO POST

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `bank_slip_key`         | uuidv4 | Chave única de identificação do boleto, no formato uuid v4   | 36         |

## Response

STATUS 200

Response Body

```json
{
  "amount": 3,
  "asset_type": {
    "created_at": "2019-02-01T16:44:11",
    "enumerator": "invoice",
    "translation_path": "bank_slip.AssetType.invoice"
  },
  "automatic_bankruptcy_protest": true,
  "automatic_protest": false,
  "automatic_write_off": false,
  "bank_slip_file": [
    {
      "barcode": "32998827300000003000001010000000000200670490",
      "created_at": "2020-05-19T18:46:41",
      "digitable_line": "32990001031000000000902006704908882730000000300",
      "url": "https://linkparadownload.com/arquivo.pdf"
    }
  ],
  "bank_slip_key": "96b32f1a-c2bd-41a4-b4b1-a169235be68b",
  "bank_slip_status": {
    "created_at": "2019-02-01T16:44:07",
    "enumerator": "accepted",
    "translation_path": "bank_slip.BankSlipStatus.accepted"
  },
  "bank_teller_instructions": "Boleto Teste",
  "beneficiary_account_branch": "0001",
  "beneficiary_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
  "beneficiary_account_number": "67049",
  "beneficiary_document_number": "12345678905",
  "beneficiary_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
  "beneficiary_name": "Greg Brown",
  "billing_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
  "business_date_expiration": "2020-06-01",
  "created_at": "2020-05-15T21:00:25",
  "days_before_fine": null,
  "days_before_interest": null,
  "days_to_bankruptcy_protest": 1,
  "days_to_protest": null,
  "days_to_write_off": null,
  "discount_limit_date": null,
  "discount_value": null,
  "document_number": "Parcela 1",
  "expenses": [],
  "expiration": "2020-06-01",
  "fine_percentage": 0.1,
  "guarantor_address": null,
  "guarantor_city": null,
  "guarantor_document": null,
  "guarantor_name": null,
  "guarantor_person_type": null,
  "guarantor_postal_code": "00000000",
  "guarantor_state": null,
  "historical_our_number": 2,
  "institution_registration_date": null,
  "interest_daily_value": 0.34,
  "lock_origin_type": null,
  "nfe_key": null,
  "nfe_url": null,
  "occurrences": [
    {
      "created_at": "2020-05-15T21:00:25",
      "discount_amount": null,
      "discount_limit_date": null,
      "iof_amount": null,
      "new_bank_slip_status": null,
      "new_due_date": "2020-06-01",
      "new_protest_status": {
        "created_at": "2019-02-01T16:44:08",
        "enumerator": "not_protested",
        "translation_path": "bank_slip.ProtestStatus.not_protested"
      },
      "notary_office_number": null,
      "notary_office_protocol": null,
      "occurrence_expenses": null,
      "occurrence_feedback": null,
      "occurrence_key": "c3ab3e01-f198-4e7e-9e01-7a8091b8bd72",
      "occurrence_reasons": [],
      "occurrence_type": {
        "created_at": "2019-02-01T16:44:14",
        "enumerator": "registration",
        "translation_path": "bank_slip.OccurrenceType.registration"
      },
      "old_bank_slip_status": {
        "created_at": "2019-02-01T16:44:07",
        "enumerator": "accepted",
        "translation_path": "bank_slip.BankSlipStatus.accepted"
      },
      "old_due_date": null,
      "old_protest_status": null,
      "paid_amount": null,
      "paid_fine_amount": null,
      "paid_interest_amount": null,
      "payment_bank": null,
      "payment_branch": null,
      "payment_credit_date": null,
      "payment_method": null,
      "payment_origin": null,
      "protest_confirmation": null,
      "protest_expenses": null,
      "rebate_amount": null,
      "registration_institution_occurrence_date": "2020-05-15",
      "registration_institution_occurrence_event": [
        {
          "cnab_file": {
            "cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
            "company_code": null,
            "created_at": "2020-05-15T21:00:22",
            "downloads": [],
            "file_size": "None",
            "filename": null,
            "line_length": null,
            "remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
            "requester_profile_code": null,
            "type": {
              "created_at": "2019-02-01T16:44:17",
              "enumerator": "api_instruction",
              "translation_path": "bank_slip.CNABFileType.api_instruction"
            },
            "url": null,
            "version": null
          },
          "cnab_file_occurrence_order": 1,
          "created_at": "2020-05-15T21:00:25",
          "new_status": {
            "created_at": "2019-02-01T16:44:15",
            "enumerator": "waiting_submission",
            "translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
          },
          "old_status": null
        }
      ],
      "registration_institution_occurrence_status": {
        "created_at": "2019-02-01T16:44:15",
        "enumerator": "waiting_submission",
        "translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
      },
      "requester_occurrence_event": [
        {
          "cnab_file": {
            "cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
            "company_code": null,
            "created_at": "2020-05-15T21:00:22",
            "downloads": [],
            "file_size": "None",
            "filename": null,
            "line_length": null,
            "remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
            "requester_profile_code": null,
            "type": {
              "created_at": "2019-02-01T16:44:17",
              "enumerator": "api_instruction",
              "translation_path": "bank_slip.CNABFileType.api_instruction"
            },
            "url": null,
            "version": null
          },
          "cnab_file_occurrence_order": 1,
          "created_at": "2020-05-15T21:00:25",
          "new_status": {
            "created_at": "2019-02-01T16:44:16",
            "enumerator": "accepted",
            "translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
          },
          "old_status": null
        }
      ],
      "requester_occurrence_status": {
        "created_at": "2019-02-01T16:44:16",
        "enumerator": "accepted",
        "translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
      }
    }
  ],
  "our_number": 2,
  "paid_amount": null,
  "paid_fine_amount": null,
  "paid_interest_amount": null,
  "participant_control_number": null,
  "payer_account_digit": null,
  "payer_account_number": null,
  "payer_account_type": null,
  "payer_address": "Rua Carlos tampaio, 204",
  "payer_bank": null,
  "payer_branch_digit": null,
  "payer_branch_number": null,
  "payer_document": "41651732825",
  "payer_name": "Beatriz Couto",
  "payer_person_type": {
    "created_at": "2019-02-01T16:44:09",
    "enumerator": "natural",
    "translation_path": "bank_slip.PersonType.natural"
  },
  "payer_postal_code": "00000000",
  "payment_date": null,
  "printing_policy": {
    "created_at": "2019-02-01T16:44:10",
    "enumerator": "no_printing",
    "translation_path": "bank_slip.PrintingPolicy.no_printing"
  },
  "protest_status": {
    "created_at": "2019-02-01T16:44:08",
    "enumerator": "not_protested",
    "translation_path": "bank_slip.ProtestStatus.not_protested"
  },
  "rebate_amount": null,
  "registration_institution": {
    "created_at": "2020-03-26T19:36:16",
    "enumerator": "qi_scd",
    "febraban_code": "329",
    "remittance_sequence": 72,
    "settlement_resource_account_key": "3e46d266-4fdb-4fd2-b87a-3e3de366afd4"
  },
  "requester_profile": 1,
  "requester_profile_code": "329-01-0001-0067049",
  "requester_registration_date": "2020-05-15"
}{
  "amount": 3,
  "asset_type": {
    "created_at": "2019-02-01T16:44:11",
    "enumerator": "invoice",
    "translation_path": "bank_slip.AssetType.invoice"
  },
  "automatic_bankruptcy_protest": true,
  "automatic_protest": false,
  "automatic_write_off": false,
  "bank_slip_file": [
    {
      "barcode": "32998827300000003000001010000000000200670490",
      "created_at": "2020-05-19T18:46:41",
      "digitable_line": "32990001031000000000902006704908882730000000300",
      "url": "https://linkparadownload.com/arquivo.pdf"
    }
  ],
  "bank_slip_key": "96b32f1a-c2bd-41a4-b4b1-a169235be68b",
  "bank_slip_status": {
    "created_at": "2019-02-01T16:44:07",
    "enumerator": "accepted",
    "translation_path": "bank_slip.BankSlipStatus.accepted"
  },
  "bank_teller_instructions": "Boleto Teste",
  "beneficiary_account_branch": "0001",
  "beneficiary_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
  "beneficiary_account_number": "67049",
  "beneficiary_document_number": "12345678905",
  "beneficiary_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
  "beneficiary_name": "Greg Brown",
  "billing_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
  "business_date_expiration": "2020-06-01",
  "created_at": "2020-05-15T21:00:25",
  "days_before_fine": null,
  "days_before_interest": null,
  "days_to_bankruptcy_protest": 1,
  "days_to_protest": null,
  "days_to_write_off": null,
  "discount_limit_date": null,
  "discount_value": null,
  "document_number": "Parcela 1",
  "expenses": [],
  "expiration": "2020-06-01",
  "fine_percentage": 0.1,
  "guarantor_address": null,
  "guarantor_city": null,
  "guarantor_document": null,
  "guarantor_name": null,
  "guarantor_person_type": null,
  "guarantor_postal_code": "00000000",
  "guarantor_state": null,
  "historical_our_number": 2,
  "institution_registration_date": null,
  "interest_daily_value": 0.34,
  "lock_origin_type": null,
  "nfe_key": null,
  "nfe_url": null,
  "occurrences": [
    {
      "created_at": "2020-05-15T21:00:25",
      "discount_amount": null,
      "discount_limit_date": null,
      "iof_amount": null,
      "new_bank_slip_status": null,
      "new_due_date": "2020-06-01",
      "new_protest_status": {
        "created_at": "2019-02-01T16:44:08",
        "enumerator": "not_protested",
        "translation_path": "bank_slip.ProtestStatus.not_protested"
      },
      "notary_office_number": null,
      "notary_office_protocol": null,
      "occurrence_expenses": null,
      "occurrence_feedback": null,
      "occurrence_key": "c3ab3e01-f198-4e7e-9e01-7a8091b8bd72",
      "occurrence_reasons": [],
      "occurrence_type": {
        "created_at": "2019-02-01T16:44:14",
        "enumerator": "registration",
        "translation_path": "bank_slip.OccurrenceType.registration"
      },
      "old_bank_slip_status": {
        "created_at": "2019-02-01T16:44:07",
        "enumerator": "accepted",
        "translation_path": "bank_slip.BankSlipStatus.accepted"
      },
      "old_due_date": null,
      "old_protest_status": null,
      "paid_amount": null,
      "paid_fine_amount": null,
      "paid_interest_amount": null,
      "payment_bank": null,
      "payment_branch": null,
      "payment_credit_date": null,
      "payment_method": null,
      "payment_origin": null,
      "protest_confirmation": null,
      "protest_expenses": null,
      "rebate_amount": null,
      "registration_institution_occurrence_date": "2020-05-15",
      "registration_institution_occurrence_event": [
        {
          "cnab_file": {
            "cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
            "company_code": null,
            "created_at": "2020-05-15T21:00:22",
            "downloads": [],
            "file_size": "None",
            "filename": null,
            "line_length": null,
            "remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
            "requester_profile_code": null,
            "type": {
              "created_at": "2019-02-01T16:44:17",
              "enumerator": "api_instruction",
              "translation_path": "bank_slip.CNABFileType.api_instruction"
            },
            "url": null,
            "version": null
          },
          "cnab_file_occurrence_order": 1,
          "created_at": "2020-05-15T21:00:25",
          "new_status": {
            "created_at": "2019-02-01T16:44:15",
            "enumerator": "waiting_submission",
            "translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
          },
          "old_status": null
        }
      ],
      "registration_institution_occurrence_status": {
        "created_at": "2019-02-01T16:44:15",
        "enumerator": "waiting_submission",
        "translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
      },
      "requester_occurrence_event": [
        {
          "cnab_file": {
            "cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
            "company_code": null,
            "created_at": "2020-05-15T21:00:22",
            "downloads": [],
            "file_size": "None",
            "filename": null,
            "line_length": null,
            "remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
            "requester_profile_code": null,
            "type": {
              "created_at": "2019-02-01T16:44:17",
              "enumerator": "api_instruction",
              "translation_path": "bank_slip.CNABFileType.api_instruction"
            },
            "url": null,
            "version": null
          },
          "cnab_file_occurrence_order": 1,
          "created_at": "2020-05-15T21:00:25",
          "new_status": {
            "created_at": "2019-02-01T16:44:16",
            "enumerator": "accepted",
            "translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
          },
          "old_status": null
        }
      ],
      "requester_occurrence_status": {
        "created_at": "2019-02-01T16:44:16",
        "enumerator": "accepted",
        "translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
      }
    }
  ],
  "our_number": 2,
  "paid_amount": null,
  "paid_fine_amount": null,
  "paid_interest_amount": null,
  "participant_control_number": null,
  "payer_account_digit": null,
  "payer_account_number": null,
  "payer_account_type": null,
  "payer_address": "Rua Carlos tampaio, 204",
  "payer_bank": null,
  "payer_branch_digit": null,
  "payer_branch_number": null,
  "payer_document": "41651732825",
  "payer_name": "Beatriz Couto",
  "payer_person_type": {
    "created_at": "2019-02-01T16:44:09",
    "enumerator": "natural",
    "translation_path": "bank_slip.PersonType.natural"
  },
  "payer_postal_code": "00000000",
  "payment_date": null,
  "printing_policy": {
    "created_at": "2019-02-01T16:44:10",
    "enumerator": "no_printing",
    "translation_path": "bank_slip.PrintingPolicy.no_printing"
  },
  "protest_status": {
    "created_at": "2019-02-01T16:44:08",
    "enumerator": "not_protested",
    "translation_path": "bank_slip.ProtestStatus.not_protested"
  },
  "rebate_amount": null,
  "registration_institution": {
    "created_at": "2020-03-26T19:36:16",
    "enumerator": "qi_scd",
    "febraban_code": "329",
    "remittance_sequence": 72,
    "settlement_resource_account_key": "3e46d266-4fdb-4fd2-b87a-3e3de366afd4"
  },
  "requester_profile": 1,
  "requester_profile_code": "329-01-0001-0067049",
  "requester_registration_date": "2020-05-15"
}{
  "amount": 3,
  "asset_type": {
    "created_at": "2019-02-01T16:44:11",
    "enumerator": "invoice",
    "translation_path": "bank_slip.AssetType.invoice"
  },
  "automatic_bankruptcy_protest": true,
  "automatic_protest": false,
  "automatic_write_off": false,
  "bank_slip_file": [
    {
      "barcode": "32998827300000003000001010000000000200670490",
      "created_at": "2020-05-19T18:46:41",
      "digitable_line": "32990001031000000000902006704908882730000000300",
      "url": "https://linkparadownload.com/arquivo.pdf"
    }
  ],
  "bank_slip_key": "96b32f1a-c2bd-41a4-b4b1-a169235be68b",
  "bank_slip_status": {
    "created_at": "2019-02-01T16:44:07",
    "enumerator": "accepted",
    "translation_path": "bank_slip.BankSlipStatus.accepted"
  },
  "bank_teller_instructions": "Boleto Teste",
  "beneficiary_account_branch": "0001",
  "beneficiary_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
  "beneficiary_account_number": "67049",
  "beneficiary_document_number": "12345678905",
  "beneficiary_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
  "beneficiary_name": "Greg Brown",
  "billing_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
  "business_date_expiration": "2020-06-01",
  "created_at": "2020-05-15T21:00:25",
  "days_before_fine": null,
  "days_before_interest": null,
  "days_to_bankruptcy_protest": 1,
  "days_to_protest": null,
  "days_to_write_off": null,
  "discount_limit_date": null,
  "discount_value": null,
  "document_number": "Parcela 1",
  "expenses": [],
  "expiration": "2020-06-01",
  "fine_percentage": 0.1,
  "guarantor_address": null,
  "guarantor_city": null,
  "guarantor_document": null,
  "guarantor_name": null,
  "guarantor_person_type": null,
  "guarantor_postal_code": "00000000",
  "guarantor_state": null,
  "historical_our_number": 2,
  "institution_registration_date": null,
  "interest_daily_value": 0.34,
  "lock_origin_type": null,
  "nfe_key": null,
  "nfe_url": null,
  "occurrences": [
    {
      "created_at": "2020-05-15T21:00:25",
      "discount_amount": null,
      "discount_limit_date": null,
      "iof_amount": null,
      "new_bank_slip_status": null,
      "new_due_date": "2020-06-01",
      "new_protest_status": {
        "created_at": "2019-02-01T16:44:08",
        "enumerator": "not_protested",
        "translation_path": "bank_slip.ProtestStatus.not_protested"
      },
      "notary_office_number": null,
      "notary_office_protocol": null,
      "occurrence_expenses": null,
      "occurrence_feedback": null,
      "occurrence_key": "c3ab3e01-f198-4e7e-9e01-7a8091b8bd72",
      "occurrence_reasons": [],
      "occurrence_type": {
        "created_at": "2019-02-01T16:44:14",
        "enumerator": "registration",
        "translation_path": "bank_slip.OccurrenceType.registration"
      },
      "old_bank_slip_status": {
        "created_at": "2019-02-01T16:44:07",
        "enumerator": "accepted",
        "translation_path": "bank_slip.BankSlipStatus.accepted"
      },
      "old_due_date": null,
      "old_protest_status": null,
      "paid_amount": null,
      "paid_fine_amount": null,
      "paid_interest_amount": null,
      "payment_bank": null,
      "payment_branch": null,
      "payment_credit_date": null,
      "payment_method": null,
      "payment_origin": null,
      "protest_confirmation": null,
      "protest_expenses": null,
      "rebate_amount": null,
      "registration_institution_occurrence_date": "2020-05-15",
      "registration_institution_occurrence_event": [
        {
          "cnab_file": {
            "cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
            "company_code": null,
            "created_at": "2020-05-15T21:00:22",
            "downloads": [],
            "file_size": "None",
            "filename": null,
            "line_length": null,
            "remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
            "requester_profile_code": null,
            "type": {
              "created_at": "2019-02-01T16:44:17",
              "enumerator": "api_instruction",
              "translation_path": "bank_slip.CNABFileType.api_instruction"
            },
            "url": null,
            "version": null
          },
          "cnab_file_occurrence_order": 1,
          "created_at": "2020-05-15T21:00:25",
          "new_status": {
            "created_at": "2019-02-01T16:44:15",
            "enumerator": "waiting_submission",
            "translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
          },
          "old_status": null
        }
      ],
      "registration_institution_occurrence_status": {
        "created_at": "2019-02-01T16:44:15",
        "enumerator": "waiting_submission",
        "translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
      },
      "requester_occurrence_event": [
        {
          "cnab_file": {
            "cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
            "company_code": null,
            "created_at": "2020-05-15T21:00:22",
            "downloads": [],
            "file_size": "None",
            "filename": null,
            "line_length": null,
            "remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
            "requester_profile_code": null,
            "type": {
              "created_at": "2019-02-01T16:44:17",
              "enumerator": "api_instruction",
              "translation_path": "bank_slip.CNABFileType.api_instruction"
            },
            "url": null,
            "version": null
          },
          "cnab_file_occurrence_order": 1,
          "created_at": "2020-05-15T21:00:25",
          "new_status": {
            "created_at": "2019-02-01T16:44:16",
            "enumerator": "accepted",
            "translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
          },
          "old_status": null
        }
      ],
      "requester_occurrence_status": {
        "created_at": "2019-02-01T16:44:16",
        "enumerator": "accepted",
        "translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
      }
    }
  ],
  "our_number": 2,
  "paid_amount": null,
  "paid_fine_amount": null,
  "paid_interest_amount": null,
  "participant_control_number": null,
  "payer_account_digit": null,
  "payer_account_number": null,
  "payer_account_type": null,
  "payer_address": "Rua Carlos tampaio, 204",
  "payer_bank": null,
  "payer_branch_digit": null,
  "payer_branch_number": null,
  "payer_document": "41651732825",
  "payer_name": "Beatriz Couto",
  "payer_person_type": {
    "created_at": "2019-02-01T16:44:09",
    "enumerator": "natural",
    "translation_path": "bank_slip.PersonType.natural"
  },
  "payer_postal_code": "00000000",
  "payment_date": null,
  "printing_policy": {
    "created_at": "2019-02-01T16:44:10",
    "enumerator": "no_printing",
    "translation_path": "bank_slip.PrintingPolicy.no_printing"
  },
  "protest_status": {
    "created_at": "2019-02-01T16:44:08",
    "enumerator": "not_protested",
    "translation_path": "bank_slip.ProtestStatus.not_protested"
  },
  "rebate_amount": null,
  "registration_institution": {
    "created_at": "2020-03-26T19:36:16",
    "enumerator": "qi_scd",
    "febraban_code": "329",
    "remittance_sequence": 72,
    "settlement_resource_account_key": "3e46d266-4fdb-4fd2-b87a-3e3de366afd4"
  },
  "requester_profile": 1,
  "requester_profile_code": "329-01-0001-0067049",
  "requester_registration_date": "2020-05-15"
}{
  "amount": 3,
  "asset_type": {
    "created_at": "2019-02-01T16:44:11",
    "enumerator": "invoice",
    "translation_path": "bank_slip.AssetType.invoice"
  },
  "automatic_bankruptcy_protest": true,
  "automatic_protest": false,
  "automatic_write_off": false,
  "bank_slip_file": [
    {
      "barcode": "32998827300000003000001010000000000200670490",
      "created_at": "2020-05-19T18:46:41",
      "digitable_line": "32990001031000000000902006704908882730000000300",
      "url": "https://linkparadownload.com/arquivo.pdf"
    }
  ],
  "bank_slip_key": "96b32f1a-c2bd-41a4-b4b1-a169235be68b",
  "bank_slip_status": {
    "created_at": "2019-02-01T16:44:07",
    "enumerator": "accepted",
    "translation_path": "bank_slip.BankSlipStatus.accepted"
  },
  "bank_teller_instructions": "Boleto Teste",
  "beneficiary_account_branch": "0001",
  "beneficiary_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
  "beneficiary_account_number": "67049",
  "beneficiary_document_number": "12345678905",
  "beneficiary_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
  "beneficiary_name": "Greg Brown",
  "billing_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
  "business_date_expiration": "2020-06-01",
  "created_at": "2020-05-15T21:00:25",
  "days_before_fine": null,
  "days_before_interest": null,
  "days_to_bankruptcy_protest": 1,
  "days_to_protest": null,
  "days_to_write_off": null,
  "discount_limit_date": null,
  "discount_value": null,
  "document_number": "Parcela 1",
  "expenses": [],
  "expiration": "2020-06-01",
  "fine_percentage": 0.1,
  "guarantor_address": null,
  "guarantor_city": null,
  "guarantor_document": null,
  "guarantor_name": null,
  "guarantor_person_type": null,
  "guarantor_postal_code": "00000000",
  "guarantor_state": null,
  "historical_our_number": 2,
  "institution_registration_date": null,
  "interest_daily_value": 0.34,
  "lock_origin_type": null,
  "nfe_key": null,
  "nfe_url": null,
  "occurrences": [
    {
      "created_at": "2020-05-15T21:00:25",
      "discount_amount": null,
      "discount_limit_date": null,
      "iof_amount": null,
      "new_bank_slip_status": null,
      "new_due_date": "2020-06-01",
      "new_protest_status": {
        "created_at": "2019-02-01T16:44:08",
        "enumerator": "not_protested",
        "translation_path": "bank_slip.ProtestStatus.not_protested"
      },
      "notary_office_number": null,
      "notary_office_protocol": null,
      "occurrence_expenses": null,
      "occurrence_feedback": null,
      "occurrence_key": "c3ab3e01-f198-4e7e-9e01-7a8091b8bd72",
      "occurrence_reasons": [],
      "occurrence_type": {
        "created_at": "2019-02-01T16:44:14",
        "enumerator": "registration",
        "translation_path": "bank_slip.OccurrenceType.registration"
      },
      "old_bank_slip_status": {
        "created_at": "2019-02-01T16:44:07",
        "enumerator": "accepted",
        "translation_path": "bank_slip.BankSlipStatus.accepted"
      },
      "old_due_date": null,
      "old_protest_status": null,
      "paid_amount": null,
      "paid_fine_amount": null,
      "paid_interest_amount": null,
      "payment_bank": null,
      "payment_branch": null,
      "payment_credit_date": null,
      "payment_method": null,
      "payment_origin": null,
      "protest_confirmation": null,
      "protest_expenses": null,
      "rebate_amount": null,
      "registration_institution_occurrence_date": "2020-05-15",
      "registration_institution_occurrence_event": [
        {
          "cnab_file": {
            "cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
            "company_code": null,
            "created_at": "2020-05-15T21:00:22",
            "downloads": [],
            "file_size": "None",
            "filename": null,
            "line_length": null,
            "remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
            "requester_profile_code": null,
            "type": {
              "created_at": "2019-02-01T16:44:17",
              "enumerator": "api_instruction",
              "translation_path": "bank_slip.CNABFileType.api_instruction"
            },
            "url": null,
            "version": null
          },
          "cnab_file_occurrence_order": 1,
          "created_at": "2020-05-15T21:00:25",
          "new_status": {
            "created_at": "2019-02-01T16:44:15",
            "enumerator": "waiting_submission",
            "translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
          },
          "old_status": null
        }
      ],
      "registration_institution_occurrence_status": {
        "created_at": "2019-02-01T16:44:15",
        "enumerator": "waiting_submission",
        "translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
      },
      "requester_occurrence_event": [
        {
          "cnab_file": {
            "cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
            "company_code": null,
            "created_at": "2020-05-15T21:00:22",
            "downloads": [],
            "file_size": "None",
            "filename": null,
            "line_length": null,
            "remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
            "requester_profile_code": null,
            "type": {
              "created_at": "2019-02-01T16:44:17",
              "enumerator": "api_instruction",
              "translation_path": "bank_slip.CNABFileType.api_instruction"
            },
            "url": null,
            "version": null
          },
          "cnab_file_occurrence_order": 1,
          "created_at": "2020-05-15T21:00:25",
          "new_status": {
            "created_at": "2019-02-01T16:44:16",
            "enumerator": "accepted",
            "translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
          },
          "old_status": null
        }
      ],
      "requester_occurrence_status": {
        "created_at": "2019-02-01T16:44:16",
        "enumerator": "accepted",
        "translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
      }
    }
  ],
  "our_number": 2,
  "paid_amount": null,
  "paid_fine_amount": null,
  "paid_interest_amount": null,
  "participant_control_number": null,
  "payer_account_digit": null,
  "payer_account_number": null,
  "payer_account_type": null,
  "payer_address": "Rua Carlos tampaio, 204",
  "payer_bank": null,
  "payer_branch_digit": null,
  "payer_branch_number": null,
  "payer_document": "41651732825",
  "payer_name": "Beatriz Couto",
  "payer_person_type": {
    "created_at": "2019-02-01T16:44:09",
    "enumerator": "natural",
    "translation_path": "bank_slip.PersonType.natural"
  },
  "payer_postal_code": "00000000",
  "payment_date": null,
  "printing_policy": {
    "created_at": "2019-02-01T16:44:10",
    "enumerator": "no_printing",
    "translation_path": "bank_slip.PrintingPolicy.no_printing"
  },
  "protest_status": {
    "created_at": "2019-02-01T16:44:08",
    "enumerator": "not_protested",
    "translation_path": "bank_slip.ProtestStatus.not_protested"
  },
  "rebate_amount": null,
  "registration_institution": {
    "created_at": "2020-03-26T19:36:16",
    "enumerator": "qi_scd",
    "febraban_code": "329",
    "remittance_sequence": 72,
    "settlement_resource_account_key": "3e46d266-4fdb-4fd2-b87a-3e3de366afd4"
  },
  "requester_profile": 1,
  "requester_profile_code": "329-01-0001-0067049",
  "requester_registration_date": "2020-05-15"
}{
  "amount": 3,
  "asset_type": {
    "created_at": "2019-02-01T16:44:11",
    "enumerator": "invoice",
    "translation_path": "bank_slip.AssetType.invoice"
  },
  "automatic_bankruptcy_protest": true,
  "automatic_protest": false,
  "automatic_write_off": false,
  "bank_slip_file": [
    {
      "barcode": "32998827300000003000001010000000000200670490",
      "created_at": "2020-05-19T18:46:41",
      "digitable_line": "32990001031000000000902006704908882730000000300",
      "url": "https://linkparadownload.com/arquivo.pdf"
    }
  ],
  "bank_slip_key": "96b32f1a-c2bd-41a4-b4b1-a169235be68b",
  "bank_slip_status": {
    "created_at": "2019-02-01T16:44:07",
    "enumerator": "accepted",
    "translation_path": "bank_slip.BankSlipStatus.accepted"
  },
  "bank_teller_instructions": "Boleto Teste",
  "beneficiary_account_branch": "0001",
  "beneficiary_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
  "beneficiary_account_number": "67049",
  "beneficiary_document_number": "12345678905",
  "beneficiary_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
  "beneficiary_name": "Greg Brown",
  "billing_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
  "business_date_expiration": "2020-06-01",
  "created_at": "2020-05-15T21:00:25",
  "days_before_fine": null,
  "days_before_interest": null,
  "days_to_bankruptcy_protest": 1,
  "days_to_protest": null,
  "days_to_write_off": null,
  "discount_limit_date": null,
  "discount_value": null,
  "document_number": "Parcela 1",
  "expenses": [],
  "expiration": "2020-06-01",
  "fine_percentage": 0.1,
  "guarantor_address": null,
  "guarantor_city": null,
  "guarantor_document": null,
  "guarantor_name": null,
  "guarantor_person_type": null,
  "guarantor_postal_code": "00000000",
  "guarantor_state": null,
  "historical_our_number": 2,
  "institution_registration_date": null,
  "interest_daily_value": 0.34,
  "lock_origin_type": null,
  "nfe_key": null,
  "nfe_url": null,
  "occurrences": [
    {
      "created_at": "2020-05-15T21:00:25",
      "discount_amount": null,
      "discount_limit_date": null,
      "iof_amount": null,
      "new_bank_slip_status": null,
      "new_due_date": "2020-06-01",
      "new_protest_status": {
        "created_at": "2019-02-01T16:44:08",
        "enumerator": "not_protested",
        "translation_path": "bank_slip.ProtestStatus.not_protested"
      },
      "notary_office_number": null,
      "notary_office_protocol": null,
      "occurrence_expenses": null,
      "occurrence_feedback": null,
      "occurrence_key": "c3ab3e01-f198-4e7e-9e01-7a8091b8bd72",
      "occurrence_reasons": [],
      "occurrence_type": {
        "created_at": "2019-02-01T16:44:14",
        "enumerator": "registration",
        "translation_path": "bank_slip.OccurrenceType.registration"
      },
      "old_bank_slip_status": {
        "created_at": "2019-02-01T16:44:07",
        "enumerator": "accepted",
        "translation_path": "bank_slip.BankSlipStatus.accepted"
      },
      "old_due_date": null,
      "old_protest_status": null,
      "paid_amount": null,
      "paid_fine_amount": null,
      "paid_interest_amount": null,
      "payment_bank": null,
      "payment_branch": null,
      "payment_credit_date": null,
      "payment_method": null,
      "payment_origin": null,
      "protest_confirmation": null,
      "protest_expenses": null,
      "rebate_amount": null,
      "registration_institution_occurrence_date": "2020-05-15",
      "registration_institution_occurrence_event": [
        {
          "cnab_file": {
            "cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
            "company_code": null,
            "created_at": "2020-05-15T21:00:22",
            "downloads": [],
            "file_size": "None",
            "filename": null,
            "line_length": null,
            "remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
            "requester_profile_code": null,
            "type": {
              "created_at": "2019-02-01T16:44:17",
              "enumerator": "api_instruction",
              "translation_path": "bank_slip.CNABFileType.api_instruction"
            },
            "url": null,
            "version": null
          },
          "cnab_file_occurrence_order": 1,
          "created_at": "2020-05-15T21:00:25",
          "new_status": {
            "created_at": "2019-02-01T16:44:15",
            "enumerator": "waiting_submission",
            "translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
          },
          "old_status": null
        }
      ],
      "registration_institution_occurrence_status": {
        "created_at": "2019-02-01T16:44:15",
        "enumerator": "waiting_submission",
        "translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
      },
      "requester_occurrence_event": [
        {
          "cnab_file": {
            "cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
            "company_code": null,
            "created_at": "2020-05-15T21:00:22",
            "downloads": [],
            "file_size": "None",
            "filename": null,
            "line_length": null,
            "remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
            "requester_profile_code": null,
            "type": {
              "created_at": "2019-02-01T16:44:17",
              "enumerator": "api_instruction",
              "translation_path": "bank_slip.CNABFileType.api_instruction"
            },
            "url": null,
            "version": null
          },
          "cnab_file_occurrence_order": 1,
          "created_at": "2020-05-15T21:00:25",
          "new_status": {
            "created_at": "2019-02-01T16:44:16",
            "enumerator": "accepted",
            "translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
          },
          "old_status": null
        }
      ],
      "requester_occurrence_status": {
        "created_at": "2019-02-01T16:44:16",
        "enumerator": "accepted",
        "translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
      }
    }
  ],
  "our_number": 2,
  "paid_amount": null,
  "paid_fine_amount": null,
  "paid_interest_amount": null,
  "participant_control_number": null,
  "payer_account_digit": null,
  "payer_account_number": null,
  "payer_account_type": null,
  "payer_address": "Rua Carlos tampaio, 204",
  "payer_bank": null,
  "payer_branch_digit": null,
  "payer_branch_number": null,
  "payer_document": "41651732825",
  "payer_name": "Beatriz Couto",
  "payer_person_type": {
    "created_at": "2019-02-01T16:44:09",
    "enumerator": "natural",
    "translation_path": "bank_slip.PersonType.natural"
  },
  "payer_postal_code": "00000000",
  "payment_date": null,
  "printing_policy": {
    "created_at": "2019-02-01T16:44:10",
    "enumerator": "no_printing",
    "translation_path": "bank_slip.PrintingPolicy.no_printing"
  },
  "protest_status": {
    "created_at": "2019-02-01T16:44:08",
    "enumerator": "not_protested",
    "translation_path": "bank_slip.ProtestStatus.not_protested"
  },
  "rebate_amount": null,
  "registration_institution": {
    "created_at": "2020-03-26T19:36:16",
    "enumerator": "qi_scd",
    "febraban_code": "329",
    "remittance_sequence": 72,
    "settlement_resource_account_key": "3e46d266-4fdb-4fd2-b87a-3e3de366afd4"
  },
  "requester_profile": 1,
  "requester_profile_code": "329-01-0001-0067049",
  "requester_registration_date": "2020-05-15"
}{
  "amount": 3,
  "asset_type": {
    "created_at": "2019-02-01T16:44:11",
    "enumerator": "invoice",
    "translation_path": "bank_slip.AssetType.invoice"
  },
  "automatic_bankruptcy_protest": true,
  "automatic_protest": false,
  "automatic_write_off": false,
  "bank_slip_file": [
    {
      "barcode": "32998827300000003000001010000000000200670490",
      "created_at": "2020-05-19T18:46:41",
      "digitable_line": "32990001031000000000902006704908882730000000300",
      "url": "https://linkparadownload.com/arquivo.pdf"
    }
  ],
  "bank_slip_key": "96b32f1a-c2bd-41a4-b4b1-a169235be68b",
  "bank_slip_status": {
    "created_at": "2019-02-01T16:44:07",
    "enumerator": "accepted",
    "translation_path": "bank_slip.BankSlipStatus.accepted"
  },
  "bank_teller_instructions": "Boleto Teste",
  "beneficiary_account_branch": "0001",
  "beneficiary_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
  "beneficiary_account_number": "67049",
  "beneficiary_document_number": "12345678905",
  "beneficiary_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
  "beneficiary_name": "Greg Brown",
  "billing_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
  "business_date_expiration": "2020-06-01",
  "created_at": "2020-05-15T21:00:25",
  "days_before_fine": null,
  "days_before_interest": null,
  "days_to_bankruptcy_protest": 1,
  "days_to_protest": null,
  "days_to_write_off": null,
  "discount_limit_date": null,
  "discount_value": null,
  "document_number": "Parcela 1",
  "expenses": [],
  "expiration": "2020-06-01",
  "fine_percentage": 0.1,
  "guarantor_address": null,
  "guarantor_city": null,
  "guarantor_document": null,
  "guarantor_name": null,
  "guarantor_person_type": null,
  "guarantor_postal_code": "00000000",
  "guarantor_state": null,
  "historical_our_number": 2,
  "institution_registration_date": null,
  "interest_daily_value": 0.34,
  "lock_origin_type": null,
  "nfe_key": null,
  "nfe_url": null,
  "occurrences": [
    {
      "created_at": "2020-05-15T21:00:25",
      "discount_amount": null,
      "discount_limit_date": null,
      "iof_amount": null,
      "new_bank_slip_status": null,
      "new_due_date": "2020-06-01",
      "new_protest_status": {
        "created_at": "2019-02-01T16:44:08",
        "enumerator": "not_protested",
        "translation_path": "bank_slip.ProtestStatus.not_protested"
      },
      "notary_office_number": null,
      "notary_office_protocol": null,
      "occurrence_expenses": null,
      "occurrence_feedback": null,
      "occurrence_key": "c3ab3e01-f198-4e7e-9e01-7a8091b8bd72",
      "occurrence_reasons": [],
      "occurrence_type": {
        "created_at": "2019-02-01T16:44:14",
        "enumerator": "registration",
        "translation_path": "bank_slip.OccurrenceType.registration"
      },
      "old_bank_slip_status": {
        "created_at": "2019-02-01T16:44:07",
        "enumerator": "accepted",
        "translation_path": "bank_slip.BankSlipStatus.accepted"
      },
      "old_due_date": null,
      "old_protest_status": null,
      "paid_amount": null,
      "paid_fine_amount": null,
      "paid_interest_amount": null,
      "payment_bank": null,
      "payment_branch": null,
      "payment_credit_date": null,
      "payment_method": null,
      "payment_origin": null,
      "protest_confirmation": null,
      "protest_expenses": null,
      "rebate_amount": null,
      "registration_institution_occurrence_date": "2020-05-15",
      "registration_institution_occurrence_event": [
        {
          "cnab_file": {
            "cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
            "company_code": null,
            "created_at": "2020-05-15T21:00:22",
            "downloads": [],
            "file_size": "None",
            "filename": null,
            "line_length": null,
            "remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
            "requester_profile_code": null,
            "type": {
              "created_at": "2019-02-01T16:44:17",
              "enumerator": "api_instruction",
              "translation_path": "bank_slip.CNABFileType.api_instruction"
            },
            "url": null,
            "version": null
          },
          "cnab_file_occurrence_order": 1,
          "created_at": "2020-05-15T21:00:25",
          "new_status": {
            "created_at": "2019-02-01T16:44:15",
            "enumerator": "waiting_submission",
            "translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
          },
          "old_status": null
        }
      ],
      "registration_institution_occurrence_status": {
        "created_at": "2019-02-01T16:44:15",
        "enumerator": "waiting_submission",
        "translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
      },
      "requester_occurrence_event": [
        {
          "cnab_file": {
            "cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
            "company_code": null,
            "created_at": "2020-05-15T21:00:22",
            "downloads": [],
            "file_size": "None",
            "filename": null,
            "line_length": null,
            "remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
            "requester_profile_code": null,
            "type": {
              "created_at": "2019-02-01T16:44:17",
              "enumerator": "api_instruction",
              "translation_path": "bank_slip.CNABFileType.api_instruction"
            },
            "url": null,
            "version": null
          },
          "cnab_file_occurrence_order": 1,
          "created_at": "2020-05-15T21:00:25",
          "new_status": {
            "created_at": "2019-02-01T16:44:16",
            "enumerator": "accepted",
            "translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
          },
          "old_status": null
        }
      ],
      "requester_occurrence_status": {
        "created_at": "2019-02-01T16:44:16",
        "enumerator": "accepted",
        "translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
      }
    }
  ],
  "our_number": 2,
  "paid_amount": null,
  "paid_fine_amount": null,
  "paid_interest_amount": null,
  "participant_control_number": null,
  "payer_account_digit": null,
  "payer_account_number": null,
  "payer_account_type": null,
  "payer_address": "Rua Carlos tampaio, 204",
  "payer_bank": null,
  "payer_branch_digit": null,
  "payer_branch_number": null,
  "payer_document": "41651732825",
  "payer_name": "Beatriz Couto",
  "payer_person_type": {
    "created_at": "2019-02-01T16:44:09",
    "enumerator": "natural",
    "translation_path": "bank_slip.PersonType.natural"
  },
  "payer_postal_code": "00000000",
  "payment_date": null,
  "printing_policy": {
    "created_at": "2019-02-01T16:44:10",
    "enumerator": "no_printing",
    "translation_path": "bank_slip.PrintingPolicy.no_printing"
  },
  "protest_status": {
    "created_at": "2019-02-01T16:44:08",
    "enumerator": "not_protested",
    "translation_path": "bank_slip.ProtestStatus.not_protested"
  },
  "rebate_amount": null,
  "registration_institution": {
    "created_at": "2020-03-26T19:36:16",
    "enumerator": "qi_scd",
    "febraban_code": "329",
    "remittance_sequence": 72,
    "settlement_resource_account_key": "3e46d266-4fdb-4fd2-b87a-3e3de366afd4"
  },
  "requester_profile": 1,
  "requester_profile_code": "329-01-0001-0067049",
  "requester_registration_date": "2020-05-15"
}{
  "amount": 3,
  "asset_type": {
    "created_at": "2019-02-01T16:44:11",
    "enumerator": "invoice",
    "translation_path": "bank_slip.AssetType.invoice"
  },
  "automatic_bankruptcy_protest": true,
  "automatic_protest": false,
  "automatic_write_off": false,
  "bank_slip_file": [
    {
      "barcode": "32998827300000003000001010000000000200670490",
      "created_at": "2020-05-19T18:46:41",
      "digitable_line": "32990001031000000000902006704908882730000000300",
      "url": "https://linkparadownload.com/arquivo.pdf"
    }
  ],
  "bank_slip_key": "96b32f1a-c2bd-41a4-b4b1-a169235be68b",
  "bank_slip_status": {
    "created_at": "2019-02-01T16:44:07",
    "enumerator": "accepted",
    "translation_path": "bank_slip.BankSlipStatus.accepted"
  },
  "bank_teller_instructions": "Boleto Teste",
  "beneficiary_account_branch": "0001",
  "beneficiary_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
  "beneficiary_account_number": "67049",
  "beneficiary_document_number": "12345678905",
  "beneficiary_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
  "beneficiary_name": "Greg Brown",
  "billing_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
  "business_date_expiration": "2020-06-01",
  "created_at": "2020-05-15T21:00:25",
  "days_before_fine": null,
  "days_before_interest": null,
  "days_to_bankruptcy_protest": 1,
  "days_to_protest": null,
  "days_to_write_off": null,
  "discount_limit_date": null,
  "discount_value": null,
  "document_number": "Parcela 1",
  "expenses": [],
  "expiration": "2020-06-01",
  "fine_percentage": 0.1,
  "guarantor_address": null,
  "guarantor_city": null,
  "guarantor_document": null,
  "guarantor_name": null,
  "guarantor_person_type": null,
  "guarantor_postal_code": "00000000",
  "guarantor_state": null,
  "historical_our_number": 2,
  "institution_registration_date": null,
  "interest_daily_value": 0.34,
  "lock_origin_type": null,
  "nfe_key": null,
  "nfe_url": null,
  "occurrences": [
    {
      "created_at": "2020-05-15T21:00:25",
      "discount_amount": null,
      "discount_limit_date": null,
      "iof_amount": null,
      "new_bank_slip_status": null,
      "new_due_date": "2020-06-01",
      "new_protest_status": {
        "created_at": "2019-02-01T16:44:08",
        "enumerator": "not_protested",
        "translation_path": "bank_slip.ProtestStatus.not_protested"
      },
      "notary_office_number": null,
      "notary_office_protocol": null,
      "occurrence_expenses": null,
      "occurrence_feedback": null,
      "occurrence_key": "c3ab3e01-f198-4e7e-9e01-7a8091b8bd72",
      "occurrence_reasons": [],
      "occurrence_type": {
        "created_at": "2019-02-01T16:44:14",
        "enumerator": "registration",
        "translation_path": "bank_slip.OccurrenceType.registration"
      },
      "old_bank_slip_status": {
        "created_at": "2019-02-01T16:44:07",
        "enumerator": "accepted",
        "translation_path": "bank_slip.BankSlipStatus.accepted"
      },
      "old_due_date": null,
      "old_protest_status": null,
      "paid_amount": null,
      "paid_fine_amount": null,
      "paid_interest_amount": null,
      "payment_bank": null,
      "payment_branch": null,
      "payment_credit_date": null,
      "payment_method": null,
      "payment_origin": null,
      "protest_confirmation": null,
      "protest_expenses": null,
      "rebate_amount": null,
      "registration_institution_occurrence_date": "2020-05-15",
      "registration_institution_occurrence_event": [
        {
          "cnab_file": {
            "cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
            "company_code": null,
            "created_at": "2020-05-15T21:00:22",
            "downloads": [],
            "file_size": "None",
            "filename": null,
            "line_length": null,
            "remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
            "requester_profile_code": null,
            "type": {
              "created_at": "2019-02-01T16:44:17",
              "enumerator": "api_instruction",
              "translation_path": "bank_slip.CNABFileType.api_instruction"
            },
            "url": null,
            "version": null
          },
          "cnab_file_occurrence_order": 1,
          "created_at": "2020-05-15T21:00:25",
          "new_status": {
            "created_at": "2019-02-01T16:44:15",
            "enumerator": "waiting_submission",
            "translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
          },
          "old_status": null
        }
      ],
      "registration_institution_occurrence_status": {
        "created_at": "2019-02-01T16:44:15",
        "enumerator": "waiting_submission",
        "translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
      },
      "requester_occurrence_event": [
        {
          "cnab_file": {
            "cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
            "company_code": null,
            "created_at": "2020-05-15T21:00:22",
            "downloads": [],
            "file_size": "None",
            "filename": null,
            "line_length": null,
            "remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
            "requester_profile_code": null,
            "type": {
              "created_at": "2019-02-01T16:44:17",
              "enumerator": "api_instruction",
              "translation_path": "bank_slip.CNABFileType.api_instruction"
            },
            "url": null,
            "version": null
          },
          "cnab_file_occurrence_order": 1,
          "created_at": "2020-05-15T21:00:25",
          "new_status": {
            "created_at": "2019-02-01T16:44:16",
            "enumerator": "accepted",
            "translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
          },
          "old_status": null
        }
      ],
      "requester_occurrence_status": {
        "created_at": "2019-02-01T16:44:16",
        "enumerator": "accepted",
        "translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
      }
    }
  ],
  "our_number": 2,
  "paid_amount": null,
  "paid_fine_amount": null,
  "paid_interest_amount": null,
  "participant_control_number": null,
  "payer_account_digit": null,
  "payer_account_number": null,
  "payer_account_type": null,
  "payer_address": "Rua Carlos tampaio, 204",
  "payer_bank": null,
  "payer_branch_digit": null,
  "payer_branch_number": null,
  "payer_document": "41651732825",
  "payer_name": "Beatriz Couto",
  "payer_person_type": {
    "created_at": "2019-02-01T16:44:09",
    "enumerator": "natural",
    "translation_path": "bank_slip.PersonType.natural"
  },
  "payer_postal_code": "00000000",
  "payment_date": null,
  "printing_policy": {
    "created_at": "2019-02-01T16:44:10",
    "enumerator": "no_printing",
    "translation_path": "bank_slip.PrintingPolicy.no_printing"
  },
  "protest_status": {
    "created_at": "2019-02-01T16:44:08",
    "enumerator": "not_protested",
    "translation_path": "bank_slip.ProtestStatus.not_protested"
  },
  "rebate_amount": null,
  "registration_institution": {
    "created_at": "2020-03-26T19:36:16",
    "enumerator": "qi_scd",
    "febraban_code": "329",
    "remittance_sequence": 72,
    "settlement_resource_account_key": "3e46d266-4fdb-4fd2-b87a-3e3de366afd4"
  },
  "requester_profile": 1,
  "requester_profile_code": "329-01-0001-0067049",
  "requester_registration_date": "2020-05-15"
}{
  "amount": 3,
  "asset_type": {
    "created_at": "2019-02-01T16:44:11",
    "enumerator": "invoice",
    "translation_path": "bank_slip.AssetType.invoice"
  },
  "automatic_bankruptcy_protest": true,
  "automatic_protest": false,
  "automatic_write_off": false,
  "bank_slip_file": [
    {
      "barcode": "32998827300000003000001010000000000200670490",
      "created_at": "2020-05-19T18:46:41",
      "digitable_line": "32990001031000000000902006704908882730000000300",
      "url": "https://linkparadownload.com/arquivo.pdf"
    }
  ],
  "bank_slip_key": "96b32f1a-c2bd-41a4-b4b1-a169235be68b",
  "bank_slip_status": {
    "created_at": "2019-02-01T16:44:07",
    "enumerator": "accepted",
    "translation_path": "bank_slip.BankSlipStatus.accepted"
  },
  "bank_teller_instructions": "Boleto Teste",
  "beneficiary_account_branch": "0001",
  "beneficiary_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
  "beneficiary_account_number": "67049",
  "beneficiary_document_number": "12345678905",
  "beneficiary_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
  "beneficiary_name": "Greg Brown",
  "billing_account_key": "7cc3b1f7-8015-4073-8471-a3ba57e34975",
  "business_date_expiration": "2020-06-01",
  "created_at": "2020-05-15T21:00:25",
  "days_before_fine": null,
  "days_before_interest": null,
  "days_to_bankruptcy_protest": 1,
  "days_to_protest": null,
  "days_to_write_off": null,
  "discount_limit_date": null,
  "discount_value": null,
  "document_number": "Parcela 1",
  "expenses": [],
  "expiration": "2020-06-01",
  "fine_percentage": 0.1,
  "guarantor_address": null,
  "guarantor_city": null,
  "guarantor_document": null,
  "guarantor_name": null,
  "guarantor_person_type": null,
  "guarantor_postal_code": "00000000",
  "guarantor_state": null,
  "historical_our_number": 2,
  "institution_registration_date": null,
  "interest_daily_value": 0.34,
  "lock_origin_type": null,
  "nfe_key": null,
  "nfe_url": null,
  "occurrences": [
    {
      "created_at": "2020-05-15T21:00:25",
      "discount_amount": null,
      "discount_limit_date": null,
      "iof_amount": null,
      "new_bank_slip_status": null,
      "new_due_date": "2020-06-01",
      "new_protest_status": {
        "created_at": "2019-02-01T16:44:08",
        "enumerator": "not_protested",
        "translation_path": "bank_slip.ProtestStatus.not_protested"
      },
      "notary_office_number": null,
      "notary_office_protocol": null,
      "occurrence_expenses": null,
      "occurrence_feedback": null,
      "occurrence_key": "c3ab3e01-f198-4e7e-9e01-7a8091b8bd72",
      "occurrence_reasons": [],
      "occurrence_type": {
        "created_at": "2019-02-01T16:44:14",
        "enumerator": "registration",
        "translation_path": "bank_slip.OccurrenceType.registration"
      },
      "old_bank_slip_status": {
        "created_at": "2019-02-01T16:44:07",
        "enumerator": "accepted",
        "translation_path": "bank_slip.BankSlipStatus.accepted"
      },
      "old_due_date": null,
      "old_protest_status": null,
      "paid_amount": null,
      "paid_fine_amount": null,
      "paid_interest_amount": null,
      "payment_bank": null,
      "payment_branch": null,
      "payment_credit_date": null,
      "payment_method": null,
      "payment_origin": null,
      "protest_confirmation": null,
      "protest_expenses": null,
      "rebate_amount": null,
      "registration_institution_occurrence_date": "2020-05-15",
      "registration_institution_occurrence_event": [
        {
          "cnab_file": {
            "cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
            "company_code": null,
            "created_at": "2020-05-15T21:00:22",
            "downloads": [],
            "file_size": "None",
            "filename": null,
            "line_length": null,
            "remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
            "requester_profile_code": null,
            "type": {
              "created_at": "2019-02-01T16:44:17",
              "enumerator": "api_instruction",
              "translation_path": "bank_slip.CNABFileType.api_instruction"
            },
            "url": null,
            "version": null
          },
          "cnab_file_occurrence_order": 1,
          "created_at": "2020-05-15T21:00:25",
          "new_status": {
            "created_at": "2019-02-01T16:44:15",
            "enumerator": "waiting_submission",
            "translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
          },
          "old_status": null
        }
      ],
      "registration_institution_occurrence_status": {
        "created_at": "2019-02-01T16:44:15",
        "enumerator": "waiting_submission",
        "translation_path": "bank_slip.RegistrationInstitutionOccurrenceStatus.waiting_submission"
      },
      "requester_occurrence_event": [
        {
          "cnab_file": {
            "cnab_key": "abfc9fba-28fb-4e75-afcb-f4647d7031bc",
            "company_code": null,
            "created_at": "2020-05-15T21:00:22",
            "downloads": [],
            "file_size": "None",
            "filename": null,
            "line_length": null,
            "remitter_key": "b91195e3-0cf4-4fed-90cf-7f5bef29c2f0",
            "requester_profile_code": null,
            "type": {
              "created_at": "2019-02-01T16:44:17",
              "enumerator": "api_instruction",
              "translation_path": "bank_slip.CNABFileType.api_instruction"
            },
            "url": null,
            "version": null
          },
          "cnab_file_occurrence_order": 1,
          "created_at": "2020-05-15T21:00:25",
          "new_status": {
            "created_at": "2019-02-01T16:44:16",
            "enumerator": "accepted",
            "translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
          },
          "old_status": null
        }
      ],
      "requester_occurrence_status": {
        "created_at": "2019-02-01T16:44:16",
        "enumerator": "accepted",
        "translation_path": "bank_slip.RequesterOccurrenceStatus.accepted"
      }
    }
  ],
  "our_number": 2,
  "paid_amount": null,
  "paid_fine_amount": null,
  "paid_interest_amount": null,
  "participant_control_number": null,
  "payer_account_digit": null,
  "payer_account_number": null,
  "payer_account_type": null,
  "payer_address": "Rua Carlos tampaio, 204",
  "payer_bank": null,
  "payer_branch_digit": null,
  "payer_branch_number": null,
  "payer_document": "41651732825",
  "payer_name": "Beatriz Couto",
  "payer_person_type": {
    "created_at": "2019-02-01T16:44:09",
    "enumerator": "natural",
    "translation_path": "bank_slip.PersonType.natural"
  },
  "payer_postal_code": "00000000",
  "payment_date": null,
  "printing_policy": {
    "created_at": "2019-02-01T16:44:10",
    "enumerator": "no_printing",
    "translation_path": "bank_slip.PrintingPolicy.no_printing"
  },
  "protest_status": {
    "created_at": "2019-02-01T16:44:08",
    "enumerator": "not_protested",
    "translation_path": "bank_slip.ProtestStatus.not_protested"
  },
  "rebate_amount": null,
  "registration_institution": {
    "created_at": "2020-03-26T19:36:16",
    "enumerator": "qi_scd",
    "febraban_code": "329",
    "remittance_sequence": 72,
    "settlement_resource_account_key": "3e46d266-4fdb-4fd2-b87a-3e3de366afd4"
  },
  "requester_profile": 1,
  "requester_profile_code": "329-01-0001-0067049",
  "requester_registration_date": "2020-05-15"
}
```

STATUS 400

Response Body

```json
{
    {"title": "Bad Request", "description": "Invalid request body.", "translation": "Corpo da requisição inválido.", "extra_fields": {}, "code": "LEG000069"}
    
}
```

---

# Emissão de boleto único (instantânea)

URL: /documentation/boletos/emissao/emissao_boleto_unico_instantanea

:::danger Importante
Para registrar bolePix, é necessário que exista uma chave Pix aleatória ativa na conta em que os boletos serão registrados.
:::

No caso do registro de boleto único de forma instantânea, a resposta da requisição de criação (resposta síncrona) já retorna o boleto registrado (ou não, para casos de rejeição). O tempo de confirmação/rejeição da Nuclea/CIP, a respeito do registro do boleto, está incluso no tempo de resposta desse endpoint.

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/instant
MÉTODO POST

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36         |

Request Body

```json
{
  "request_control_key": "0d496b4d-01f6-48cd-8ec9-9ead1e43f156",
  "our_number": 123456789,
  "document_number": "DOC4561237",
  "amount": 5000.00,
  "expiration": "2025-01-01",
  "bank_teller_instructions": "Confirm payment",
  "protest_data": {"days_to_protest": 7},
  "bankruptcy_protest_data": {"days_to_bankruptcy_protest": 14},
  "max_payment_days": 45,
  "fine_data": {"fine_type": "absolute", "fine_amount": 100.00, "days_to_fine": 10},
  "interest_data": {
    "interest_type": "workdays_daily_amount",
    "interest_amount": 10.00,
    "days_to_interest": 2,
  },
  "financial_instrument_type": "digital_commercial_invoice",
  "write_off_data": {"days_to_write_off": 365},
  "rebate_amount": 200.00,
  "discounts_data": [
    {
      "discount_amount": 50.00,
      "discount_number": 1,
      "discount_type": "absolute",
      "discount_limit_date": "2024-12-01",
    }
  ],
  "payer_data": {
    "name": "Global Tech",
    "contact": {
      "email": "finance@globaltech.com",
      "phone": {"country_code": "055", "area_code": "11", "number": "987654321"},
    },
    "address": {
      "street": "101 High St.",
      "neighborhood": "Tech Park",
      "number": "202",
      "postal_code": "01001000",
      "city": "Innovation City",
      "state": "SP",
      "complement": "Building A",
    },
    "document_number": "12345678000195",
    "person_type": "legal",
  },
  "guarantor_data": {
    "name": "Jane Doe",
    "contact": {
      "email": "jane.doe@qitech.com.br",
      "phone": {"country_code": "055", "area_code": "11", "number": "999999999"},
    },
    "address": {
      "street": "202 Elm St.",
      "neighborhood": "Quiet Neighborhood",
      "number": "303",
      "postal_code": "01001000",
      "city": "Peaceful Town",
      "state": "RJ",
      "complement": "House 1",
    },
    "document_number": "23456789012",
    "person_type": "natural",
  },
  "pix_key": "06797774-e050-419e-a91a-c64c919b52c7",
  "notification": {
    "document_number": "12345678000195",
    "name": "Global Tech",
    "email": "finance@globaltech.com",
    "phone": {"country_code": "055", "area_code": "11", "number": "987654321"},
    "send_2_way": true,
    "send_before_due_date": false,
    "send_after_due_date": false,
    "send_on_protest": false
  }
}
```

 
### Request Body Params

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `request_control_key` *    | uuidv4  | Chave única de identificação da request utilizada pelo cliente no formato uuid v4  | 36                                                |
| `our_number`              | integer | Número único de identificação do boleto junto à carteira. Pode ser enviado pelo cliente e, caso não seja, a QI Tech irá gerar um                           | 11                                                |
| `document_number`          | string  | Número de identificação do boleto. Pode ser o número da nota fiscal eletrônica     | 10                                                |
| `participant_control_number` | string | Nº Controle do Participante                                                       |
25                                                |
| `amount` *                 | float   | Valor base do boleto                                                               | -                                                 |
| `expiration` *             | string  | Data de vencimento                                                                 | 10                                                |
| `bank_teller_instructions` | string  | Observações ao pagador do boleto. Aceita no máximo 320 caracteres, distribuídos em até 7 linhas. Cada linha pode conter no máximo 90 caracteres. Caso uma linha ultrapasse 90 caracteres, o texto será automaticamente quebrado em uma nova linha | 320                                               |
| `rebate_amount`            | float   | Valor de abatimento do boleto, que será aplicado em cima do valor base             | -                                                 |
| `max_payment_days`         | integer | Máximo de dias corridos que o boleto ficará disponível para pagamento, após o vencimento (pode ser no máximo 365) | -          |
| `financial_instrument_type`   | string  | Tipo de espécie do boleto | **[Enumeradores financial_instrument_type](#enumeradores-financial_instrument_type)** |
| `partial_payment_data`    | object  | Configurações de pagamento parcial                      | **[Objeto partial_payment_data](#objeto-partial_payment_data)** |
| `write_off_data`       | object  | Configuração de baixa      | **[Objeto write_off_data](#objeto-write_off_settings)** |
| `protest_data`         | object  | Configuração de protesto       | **[Objeto protest_data](#objeto-protest_settings)** |
| `bankruptcy_protest_data` | object  | Configuração de protesto falimentar | **[Objeto bankruptcy_protest_data](#objeto-bankruptcy_protest_settings)** |
| `fine_data`            | object  | Configuração de multa                 | **[Objeto fine_data](#objeto-fine_settings)** |
| `interest_data`        | object  | Configuração de juros        | **[Objeto interest_data](#objeto-interest_settings)** |
| `discounts_data`           | object array | Descontos           | **[Objeto discount](#objeto-discounts_data)** |
| `payer_data` *             | object  | Dados do pagador                                                                   | **[Objeto payer_data](#objetos-payer_data-e-guarantor_data)** |
| `guarantor_data`           | object  | Dados do sacador avalista                                                          | **[Objeto guarantor_data](#objetos-payer_data-e-guarantor_data)** |
| `pix_key`                  | uuidv4  | Chave pix do tipo aleatória                                                        | 36                                                |

:::info BolePix
Caso o parâmetro `pix_key`, opcional, seja enviado na request, será gerado um bolePix. BolePix é um boleto cujo pagamento é vinculado a um QR Code Pix. Sendo assim, o pagador pode realizar o pagamento do boleto tanto utilizando a linha digitável do mesmo, quanto através da leitura do QR Code Pix vinculado. Caso o pagamento seja feito via QR Code, a liquidação financeira se dá instantaneamente, enquanto os retornos bancários e webhooks envolvidos na liquidação serão gerados assim como é feito para um boleto comum.

Importante: para registrar um bolePix, é necessário que exista uma chave Pix aleatória ativa na conta em que boleto será registrado.
:::

:::tip Configurações Padrão da Carteira
Caso cada um dos campos `max_payment_days`, `write_off_data`, `protest_data`, `bankruptcy_protest_data`, `fine_data`, `interest_data` e `pix_key` não sejam enviados na request e a carteira possua configurações padrão (i.e. `max_payment_days`, `write_off_settings`, `protest_settings`, `bankruptcy_protest_settings`, `fine_settings`, `interest_settings` e `qr_code_settings`, respectivamente, no `configuration_data` do `requester_profile`), serão utilizadas tais configurações padrão para a emissão do título.
:::

:::caution Limitações e Restrições
- **Boletos de Pagamento Parcial:** Não é permitido o pagamento via QR Code Pix. Portanto, não é permitido enviar a `pix_key` no registro, nem ter uma configuração padrão de geração de bolePix para a carteira.

- **Boletos de Cartão de Crédito:** Não é necessário nem permitido enviar informações rebate, desconto, multa e juros. Isso se deve ao padrão do mercado, onde muitas Instituições Financeiras não aceitam o pagamento de boletos de cartão de crédito que contenham essas informações. A carteira também não pode ter essas configurações definidas como padrão. Sendo assim boletos desse tipo podem ser pagos parcialmente mesmo após o vencimento, sem incidência de juros, multas, descontos ou abatimentos na fatura corrente. Para aplicar esses valores é necessário incluí-los na próxima fatura, seja através da [ocorrência de edição de valor](/documentation/boletos/instrucoes/valor) do boleto ou emitindo um novo boleto que inclua esses valores. É possível enviar `amount = 0` para boletos deste tipo.

**Importante:** Boletos do tipo `credit_card` são obrigatoriamente de pagamento parcial, sendo assim é necessário fornecer as informações de `partial_payment_data` ou ter essa configuração padrão na carteira. Caso o campo `financial_instrument_type` não seja enviado, o valor padrão será `digital_commercial_invoice`.
:::

:::tip Recomendações de Carteiras
- **Carteira para Boletos Padrão:** Mantenha as configurações padrão para multas, juros e protesto
- **Carteira para Boletos de Pagamento Parcial:** Sem configuração de Pix e com regras específicas para pagamento parcial
- **Carteira para Boletos de Cartão de Crédito:** Sem configurações de multa, juros, desconto ou rebate

Criar carteiras específicas garante que as configurações padrão sejam adequadas para cada tipo de boleto e evita conflitos nas regras de negócio.
:::

:::info Máquina de Estados
A máquina de status para boletos de pagamento parcial possui algumas diferenças. Para mais detalhes, consulte a [introdução](/documentation/boletos/introducao) , onde há uma explicação sobre como aplicar a incidência de juros e multas no boleto seguindo as boas práticas do mercado.
:::

### Enumeradores financial_instrument_type

| Enumerador  | Descrição                        |
|-------------|----------------------------------|
| digital_commercial_invoice | DMI Duplicata Mercantil Indicação |
| credit_card | Cartão de Crédito |
| check | CH Cheque |
| digital_commercial | DM Duplicata Mercantil |
| digital_service_invoice | Duplicata de Serviço |
| digital_service_invoice_indication | DSI Duplicata de Serviço Indicação |
| digital_rural_invoice | DR Duplicata Rural |
| bill_of_exchange | LC Letra de Câmbio |
| commercial_credit_note | NCC Nota de Crédito Comercial |
| export_credit_note | NCE Nota de Crédito Exportação |
| industrial_credit_note | NCI Nota de Crédito Industrial |
| rural_credit_note | NCR Nota de Crédito Rural |
| promissory_note | NP Nota Promissória |
| rural_promissory_note | NPR Nota Promissória Rural |
| mercantile_triplicate | TM Triplicata Mercantil |
| service_triplicate | TS Triplicata de Serviço |
| insurance_note | NS Nota de Seguro |
| receipt | RC Recibo |
| printed_bank_slip | FAT Bloqueto |
| debit_note | ND Nota de Débito |
| insurance_policy | AP Apólice de Seguro |
| school_monthly_fee | ME Mensalidade Escolar |
| consortium_installment | PC Parcela de Consórcio |
| invoice | NF Nota Fiscal |
| debt_document | DD Documento de Dívida |
| rural_product_certificate | Cédula de Produto Rural |
| warrant | Warrant |
| state_active_debt | Dívida Ativa de Estado |
| municipal_active_debt | Dívida Ativa de Município |
| federal_active_debt | Dívida Ativa da União |
| condominium_charges | Encargos condominiais |
| proposal_bank_slip | Boleto proposta |
| deposit_and_contribution_bank_slip | Boleto de Depósito e Aporte |
| others | Outros |

### Objeto partial_payment_data

| Campo                             | Tipo    | Descrição                                                                 | Caracteres |
|-----------------------------------|---------|---------------------------------------------------------------------------|------------|
| `partial_payment_minimum_type` *  | string  | Tipo de valor mínimo para pagamento parcial                               | **[Enumeradores partial_payment_type](#enumeradores-partial_payment_type)** |
| `partial_payment_minimum_percentage` | float | Percentual mínimo permitido para o pagamento parcial                      | -          |
| `partial_payment_minimum_amount`  | float  | Valor mínimo permitido para o pagamento parcial                           | -          |
| `partial_payment_maximum_type`    | string  | Tipo de valor máximo para pagamento parcial                               | **[Enumeradores partial_payment_type](#enumeradores-partial_payment_type)** |
| `partial_payment_maximum_percentage` | float | Percentual máximo permitido para o pagamento parcial                      | -          |
| `partial_payment_maximum_amount`  | float  | Valor máximo permitido para o pagamento parcial                           | -          |
| `partial_payment_quantity` *      | integer | Quantidade de pagamentos parciais permitidos                              | -          |

:::caution Atenção!
De acordo com o valor enviado nos campos `partial_payment_minimum_type` e `partial_payment_maximum_type`, é necessário enviar o `partial_payment_minimum_amount` ou `partial_payment_minimum_percentage`, e o `partial_payment_maximum_amount` ou `partial_payment_maximum_percentage` correspondente.
:::

### Enumeradores partial_payment_type

| Enumerador  | Descrição                        |
|-------------|----------------------------------|
| absolute    | Valor absoluto                   |
| percentage  | Percentual                       |

### Objeto write_off_data

| Campo                     | Tipo    | Descrição                                                                   | Caracteres |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_write_off` *     | integer | Dias, após o vencimento, para que o boleto seja baixado automaticamente     | -          |

### Objeto protest_data

| Campo                     | Tipo    | Descrição                                                                   | Caracteres |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_protest` *       | integer | Dias, após o vencimento, para que o boleto seja protestado automaticamente  | -          |

### Objeto bankruptcy_protest_data

| Campo                          | Tipo    | Descrição                                                                   | Caracteres  |
|--------------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_bankruptcy_protest` * | integer | Dias, após o vencimento, para que o boleto seja protestado automaticamente  | -           |

### Objeto fine_data

Opção 1: multa em valor absoluto (`fine_type=absolute`)

| Campo                     | Tipo    | Descrição                                               | Caracteres                |
|---------------------------|---------|---------------------------------------------------------|-------------------------------------------------------------------------|
| `fine_type` *             | string  | Tipo da multa                                                       | **[Enumeradores fine_type](#enumeradores-fine_type)**                                              |
| `fine_amount` *           | float   | Valor absoluto da multa                                             | -                                                                        |
| `days_to_fine` *          | integer | Dias, após o vencimento, para que a multa seja cobrada              | -                                                                        |

Opção 2: multa em valor percentual (`fine_type=percentage`)

| Campo                     | Tipo    | Descrição                                                 | Caracteres                             |
|---------------------------|---------|-----------------------------------------------------------|---------------------------------------|
| `fine_type` *             | string  | Tipo da multa                                             | **[Enumeradores fine_type](#enumeradores-fine_type)** |
| `fine_percentage` *       | integer | Valor percentual da multa, de 1 a 100                     | -                                      |
| `days_to_fine` *          | integer | Dias, após o vencimento, para que a multa seja cobrada    | -                                      |

### Enumeradores fine_type

| Enumerador         | Descrição             |
|--------------------|-----------------------|
| absolute           | valor absoluto        |
| percentage         | valor percentual      |

### Objeto interest_data

Opção 1: juros utilizando valores absolutos (`interest_type=calendar_days_daily_amount` ou `interest_type=workdays_daily_amount`)

| Campo                     | Tipo    | Descrição                                                                     | Caracteres                                                                                      |
|---------------------------|---------|-------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| `interest_type` *         | string  | Tipo de juros       | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_amount` *       | float   | Valor a ser cobrado por unidade de tempo determinada (dias úteis ou corridos) | -                                                                                               |
| `days_to_interest` *      | integer | Dias, após o vencimento, para que comece a cobrar os juros                    | -                                                                                               |

Opção 2: juros utilizando valores percentuais (`interest_type=calendar_days_monthly_percentage`)

| Campo                    | Tipo    | Descrição                                                                             | Caracteres                                                                                          |
|--------------------------|---------|---------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
| `interest_type` *        | string  | Tipo de juros       | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_percentage` *  | integer | Porcentagem a ser cobrada por unidade de tempo determinada (dias úteis ou corridos)                                                                      | -                                                                           |
| `days_to_interest` *     | integer | Dias, após o vencimento, para que comece a cobrar os juros                             | -                                                                                                   |

### Enumeradores interest_type

| Enumerador                       | Descrição                                                            |
|----------------------------------|----------------------------------------------------------------------|
| calendar_days_daily_amount       | Valor diário sobre dias corridos                                     |
| workdays_daily_amount            | Valor diário sobre dias úteis                                        |
| calendar_days_monthly_percentage | Porcentagem de juros cobrados mensalmente, com base em dias corridos |

### Objeto discount

Opção 1: descontos utilizando valores absolutos (`discount_type in ["absolute", "anticipation_calendar_days_daily_amount", "anticipation_workdays_daily_amount"]`)

| Campo                     | Tipo    | Descrição                                           | Caracteres                                                |
|---------------------------|---------|-----------------------------------------------------|-----------------------------------------------------------|
| `discount_amount` *       | float   | Valor absoluto de desconto por unidade de tempo                                            | -                                                          |
| `discount_number` *       | integer | Número do desconto                                     | -                                                         |
| `discount_type` *         | string  | Configuração do desconto em valores absolutos                                    | **[Enumerador discount_type](#enumeradores-discount_type)** |                                                       |
| `discount_limit_date` *   | string  | Data limite para aplicação do desconto   | 10                                                        |

Opção 2: descontos utilizando valores percentuais (`discount_type in ["percentage", "anticipation_calendar_days_daily_percentage", "anticipation_workdays_daily_percentage"]`)

| Campo                     | Tipo    | Descrição                                           | Caracteres                                                |
|---------------------------|---------|-----------------------------------------------------|-----------------------------------------------------------|
| `discount_percentage` *   | float   | Valor percentual de desconto por unidade de tempo                                            | -                                                          |
| `discount_number` *       | integer | Número do desconto                                     | -                                                         |
| `discount_type` *         | string  | Configuração do desconto em valores percentuais                                    | **[Enumerador discount_type](#enumeradores-discount_type)** |                                                       |
| `discount_limit_date` *   | string  | Data limite para aplicação do desconto   | 10                                                        |

:::caution Atenção!
O boleto pode ter até três descontos, sendo que os descontos devem ser todos do mesmo tipo , isto é, devem ter o mesmo `discount_type`. Os descontos devem ser numerados de 1 a 3, de maneira crescente e começando necessariamente em 1. Ou seja, caso sejam enviados dois descontos na requisição, devem necessariamente ser numerados com 1 e 2.
:::

### Enumeradores discount_type

| Enumerador                                  | Descrição                                                                |
|---------------------------------------------|--------------------------------------------------------------------------|
| absolute                                    | Valor fixo                                                               |
| anticipation_calendar_days_daily_amount     | Valor diário de desconto de antecipação, sobre dias corridos             |
| anticipation_workdays_daily_amount          | Valor diário de desconto de antecipação, sobre dias úteis                |
| percentage                                  | Porcentagem fixa                                                         |
| anticipation_calendar_days_daily_percentage | Porcentagem mensal de desconto de antecipação, com base em dias corridos |
| anticipation_workdays_daily_percentage      | Porcentagem anual de desconto de antecipação, com base em dias úteis     |

### Objetos payer_data e guarantor_data

| Campo                     | Tipo   | Descrição                                                  | Caracteres|
|---------------------------|--------|-------------------------------------|-----------------------------------------------------------|
| `name` *                  | string | Nome completo                       | 100                                                       |
| `document_number` *       | string | Número do documento (CPF/CNPJ)      | 11 ou 14                                                  |
| `person_type` *           | string | Tipo da pessoa (física ou jurídica) | **[Enumeradores person_type](#enumeradores-person_type)** |
| `contact`                 | object | Informações de contato              | **[Objeto contact](#objeto-contact)**                     |
| `address`                 | object | Endereço                            | **[Objeto address](#objeto-address)**                     |

### Enumeradores person_type

| Enumerador         | Descrição             |
|--------------------|-----------------------|
| natural            | pessoa física         |
| legal              | pessoa jurídica       |

### Objeto contact

| Campo                     | Tipo   | Descrição                         | Caracteres                         |
|---------------------------|--------|-----------------------------------|------------------------------------|
| `email`                   | string | E-mail de contato                 | 320                                |
| `phone`                   | object | Telefone de contato               | **[Objeto phone](#objeto-phone)**  |

### Objeto phone

| Campo                           | Tipo   | Descrição                                    | Caracteres |
|---------------------------------|--------|----------------------------------------------|------------|
| `country_code` *     | string | Código DDI (Discagem Direta Internacional)   | 3          |
| `area_code` *                   | string | Código DDD (Discagem Direta à Distância)     | 2          |
| `number` *                      | string | Complemento                                  | 9          |

### Objeto address

| Campo                     | Tipo   | Descrição                                    | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `street` *                | string | Logradouro                                   | 500        |
| `number` *                | string | Número                                       | 6          |
| `complement`              | string | Complemento                                  | 500        |
| `neighborhood` *          | string | Bairro                                       | 100        |
| `postal_code` *           | string | CEP                                          | 8          |
| `city` *                  | string | Cidade                                       | 100        |
| `state` *                 | string | Estado (UF) | **[Enumerador state](#enumeradores-state)** |

### Enumeradores state

| Enumerador         | Descrição             |
|--------------------|-----------------------|
| AC                 | Acre                  |
| AL                 | Alagoas               |
| AM                 | Amazonas              |
| AP                 | Amapá                 |
| BA                 | Bahia                 |
| CE                 | Ceará                 |
| DF                 | Distrito federal      |
| ES                 | Espírito Santo        |
| GO                 | Goiás                 |
| MA                 | Maranhão              |
| MG                 | Minas Gerais          |
| MS                 | Mato Grosso do Sul    |
| MT                 | Mato Grosso           |
| PA                 | Pará                  |
| PB                 | Paraíba               |
| PE                 | Pernambuco            |
| PI                 | Piauí                 |
| PR                 | Paraná                |
| RJ                 | Rio de Janeiro        |
| RN                 | Rio Grande do Norte   |
| RO                 | Rondônia              |
| RR                 | Roraima               |
| RS                 | Rio Grande do Sul     |
| SC                 | Santa Catarina        |
| SE                 | Sergipe               |
| SP                 | São Paulo             |
| TO                 | Tocantins             |
| EX                 | Exceção               |

### Objeto notification

| Campo                     | Tipo    | Descrição                                                                               | Caracteres |
|---------------------------|---------|-----------------------------------------------------------------------------------------|------------|
| `document_number` *       | string  | Número do documento de quem receberá as notificações (CPF/CNPJ)                         | 11 ou 14   |
| `name` *                  | string  | Nome de quem receberá as notificações                                                   | 100        |
| `email`                   | string  | E-mail para o qual serão enviadas as notificações                                       | 320        |
| `phone`                   | object  | Telefone de contato para o qual serão enviadas as notificações | **[Objeto phone](#objeto-phone)**   |
| `send_2_way` *            | boolean | Enviar segunda via                                                                      | -          |
| `send_before_due_date` *  | boolean | Enviar notificação ao pagador antes da data de vencimento                               | -          |
| `send_after_due_date` *   | boolean | Enviar notificação ao pagador quando o boleto vencer                                    | -          |
| `send_on_protest` *       | boolean | Enviar notificação ao entrar em fluxo de protesto                                       | -          |

## Response

STATUS 201

Response Body: Boleto registrado

```json
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "bank_slip_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "bank_slip_status": "registered",
  "our_number": 92580722204,
  "barcode": "32998995900000892812147469258072220406456140",
  "digitable_line": "32992147466925807222704064561402899590000089281",
  "qr_code_data": {
    "qr_code_key": "bc5cb30c-8f98-4273-b405-3546da1d8d7a",
    "pix_key": "06797774-e050-419e-a91a-c64c919b52c7",
    "receiver_conciliation_id": "01GVGV9NXBCY287Z6CJ4S0ENW9",
    "url": "00020126830014br.gov.bcb.pix2561qrcode.qitech.app/bacen/cobv/58fd5103a8e64bbbab2fd49b0bd580145204000053039865802BR5925GONNFUNDODEINVESTIMENTOEM6012RiodeJaneiro6107226401262070503***6304EA0D",
    "image": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAALCAD0APQBAREA/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/9oACAEBAAA/APf6KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK+QPhl8Mv+Fjf2p/xN/wCz/sHlf8u3m79+/wD21xjZ79a7/wD4Zl/6m7/ym/8A22j/AIZl/wCpu/8AKb/9to/Zl/5mn/t0/wDa1egfE34Zf8LG/sv/AIm/9n/YPN/5dvN379n+2uMbPfrXgHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrR8Tfib/wsb+y/wDiUf2f9g83/l583fv2f7C4xs9+td//AMm5/wDUw/27/wBunkeR/wB/N27zvbG3vnjwCvr/AOJvxN/4Vz/Zf/Eo/tD7f5v/AC8+Vs2bP9hs53+3SvkCvf8A9mX/AJmn/t0/9rUf8m5/9TD/AG7/ANunkeR/383bvO9sbe+ePQPhl8Mv+Fc/2p/xN/7Q+3+V/wAu3lbNm/8A22znf7dK8A+GXxN/4Vz/AGp/xKP7Q+3+V/y8+Vs2b/8AYbOd/t0o+GXxN/4Vz/an/Eo/tD7f5X/Lz5WzZv8A9hs53+3Svf8A4m/DL/hY39l/8Tf+z/sHm/8ALt5u/fs/21xjZ79a8/8A+GZf+pu/8pv/ANtr0D4ZfE3/AIWN/an/ABKP7P8AsHlf8vPm79+//YXGNnv1rwD4ZfE3/hXP9qf8Sj+0Pt/lf8vPlbNm/wD2Gznf7dK7/wD4aa/6lH/ypf8A2quA+GXxN/4Vz/an/Eo/tD7f5X/Lz5WzZv8A9hs53+3Svr+vkD4ZfDL/AIWN/an/ABN/7P8AsHlf8u3m79+//bXGNnv1rv8A/hmX/qbv/Kb/APbaP+GZf+pu/wDKb/8AbaP2Zf8Amaf+3T/2tX0BRRRXz/8Asy/8zT/26f8AtavAK9//AGZf+Zp/7dP/AGtR+zL/AMzT/wBun/tavQPib8Mv+Fjf2X/xN/7P+web/wAu3m79+z/bXGNnv1rz/wDZl/5mn/t0/wDa1cB8Mvib/wAK5/tT/iUf2h9v8r/l58rZs3/7DZzv9ule/wDwy+Jv/Cxv7U/4lH9n/YPK/wCXnzd+/f8A7C4xs9+teAfE34Zf8K5/sv8A4m/9ofb/ADf+XbytmzZ/ttnO/wBule//ABN+Jv8Awrn+y/8AiUf2h9v83/l58rZs2f7DZzv9uleAfDL4Zf8ACxv7U/4m/wDZ/wBg8r/l283fv3/7a4xs9+tHxN+GX/Cuf7L/AOJv/aH2/wA3/l28rZs2f7bZzv8AbpXv/wAMvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9ulef/tNf8yt/29/+0a9A+GXxN/4WN/an/Eo/s/7B5X/Lz5u/fv8A9hcY2e/WvP8A/k3P/qYf7d/7dPI8j/v5u3ed7Y2988cB8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpXf/APDTX/Uo/wDlS/8AtVcB8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpX1/Xz//AMm5/wDUw/27/wBunkeR/wB/N27zvbG3vng/5OM/6l7+wv8At78/z/8Av3t2+T753dsc+gfDL4m/8LG/tT/iUf2f9g8r/l583fv3/wCwuMbPfrXn/wCzL/zNP/bp/wC1q8Ar3/8AZl/5mn/t0/8Aa1H7Mv8AzNP/AG6f+1q+gKKKK+f/ANmX/maf+3T/ANrUf8My/wDU3f8AlN/+216B8Mvhl/wrn+1P+Jv/AGh9v8r/AJdvK2bN/wDttnO/26V5/wDsy/8AM0/9un/taj/k4z/qXv7C/wC3vz/P/wC/e3b5Pvnd2xyf8nGf9S9/YX/b35/n/wDfvbt8n3zu7Y5P2mv+ZW/7e/8A2jR+zL/zNP8A26f+1qP+Tc/+ph/t3/t08jyP+/m7d53tjb3zx4BXv/7TX/Mrf9vf/tGj/k3P/qYf7d/7dPI8j/v5u3ed7Y2988cB8Mvhl/wsb+1P+Jv/AGf9g8r/AJdvN379/wDtrjGz3613/wDwzL/1N3/lN/8AttH7Mv8AzNP/AG6f+1q4D4m/DL/hXP8AZf8AxN/7Q+3+b/y7eVs2bP8AbbOd/t0rv/8Ahpr/AKlH/wAqX/2qj/k4z/qXv7C/7e/P8/8A797dvk++d3bHJ/ybn/1MP9u/9unkeR/383bvO9sbe+ePQPhl8Mv+Fc/2p/xN/wC0Pt/lf8u3lbNm/wD22znf7dKPib8Mv+Fjf2X/AMTf+z/sHm/8u3m79+z/AG1xjZ79a8//AGZf+Zp/7dP/AGtX0BXz/wDsy/8AM0/9un/taj/hmX/qbv8Aym//AG2vQPhl8Mv+Fc/2p/xN/wC0Pt/lf8u3lbNm/wD22znf7dK8/wD2Zf8Amaf+3T/2tX0BRRRXz/8A8My/9Td/5Tf/ALbR/wAMy/8AU3f+U3/7bR/wzL/1N3/lN/8AttegfDL4Zf8ACuf7U/4m/wDaH2/yv+Xbytmzf/ttnO/26V5//wAm5/8AUw/27/26eR5H/fzdu872xt7549A+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0rz/9mX/maf8At0/9rVwHwy+Jv/Cuf7U/4lH9ofb/ACv+Xnytmzf/ALDZzv8AbpR8Mvib/wAK5/tT/iUf2h9v8r/l58rZs3/7DZzv9ulHwy+Jv/Cuf7U/4lH9ofb/ACv+Xnytmzf/ALDZzv8AbpXf/sy/8zT/ANun/tavQPhl8Mv+Fc/2p/xN/wC0Pt/lf8u3lbNm/wD22znf7dK8/wD2Zf8Amaf+3T/2tXoHwy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpXgHwy+Jv8Awrn+1P8AiUf2h9v8r/l58rZs3/7DZzv9uld/+zL/AMzT/wBun/tavQPhl8Mv+Fc/2p/xN/7Q+3+V/wAu3lbNm/8A22znf7dK8A+GXxN/4Vz/AGp/xKP7Q+3+V/y8+Vs2b/8AYbOd/t0o+GXxN/4Vz/an/Eo/tD7f5X/Lz5WzZv8A9hs53+3Su/8A2Zf+Zp/7dP8A2tR/ybn/ANTD/bv/AG6eR5H/AH83bvO9sbe+eD9mX/maf+3T/wBrUfsy/wDM0/8Abp/7Wo/4Zl/6m7/ym/8A22j/AIZl/wCpu/8AKb/9to/4Zl/6m7/ym/8A22vQPhl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK9Aooor5/8A2Zf+Zp/7dP8A2tXAfE34m/8ACxv7L/4lH9n/AGDzf+Xnzd+/Z/sLjGz360fE34m/8LG/sv8A4lH9n/YPN/5efN379n+wuMbPfrXv/wAMvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9ulfIFFegfDL4m/8ACuf7U/4lH9ofb/K/5efK2bN/+w2c7/bpXf8A7TX/ADK3/b3/AO0a9A+GXxN/4WN/an/Eo/s/7B5X/Lz5u/fv/wBhcY2e/WvAPib8Mv8AhXP9l/8AE3/tD7f5v/Lt5WzZs/22znf7dKPib8Mv+Fc/2X/xN/7Q+3+b/wAu3lbNmz/bbOd/t0rv/wBmX/maf+3T/wBrVwHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9ulHxN+GX/Cuf7L/wCJv/aH2/zf+XbytmzZ/ttnO/26V3//AAzL/wBTd/5Tf/ttH7TX/Mrf9vf/ALRrgPhl8Tf+Fc/2p/xKP7Q+3+V/y8+Vs2b/APYbOd/t0o+Jvwy/4Vz/AGX/AMTf+0Pt/m/8u3lbNmz/AG2znf7dK7//AJOM/wCpe/sL/t78/wA//v3t2+T753dscn/Juf8A1MP9u/8Abp5Hkf8Afzdu872xt7548Ar3/wD5Nz/6mH+3f+3TyPI/7+bt3ne2NvfPHAfE34Zf8K5/sv8A4m/9ofb/ADf+XbytmzZ/ttnO/wBuld/+01/zK3/b3/7Rr6Aorz/4ZfE3/hY39qf8Sj+z/sHlf8vPm79+/wD2FxjZ79a9Aooor5A+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0o+JvxN/4WN/Zf/Eo/s/7B5v/AC8+bv37P9hcY2e/Wu//AGmv+ZW/7e//AGjXoHwy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulHwy+Jv/Cxv7U/4lH9n/YPK/5efN379/8AsLjGz3615/8A8nGf9S9/YX/b35/n/wDfvbt8n3zu7Y5+gK+QPib8Tf8AhY39l/8AEo/s/wCweb/y8+bv37P9hcY2e/Wvf/hl8Tf+Fjf2p/xKP7P+weV/y8+bv37/APYXGNnv1rz/AP4aa/6lH/ypf/aq9A+Jvwy/4WN/Zf8AxN/7P+web/y7ebv37P8AbXGNnv1r0CvkD4m/DL/hXP8AZf8AxN/7Q+3+b/y7eVs2bP8AbbOd/t0rv/8Ahpr/AKlH/wAqX/2qj/hmX/qbv/Kb/wDbaP8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPHoHxN+Jv8Awrn+y/8AiUf2h9v83/l58rZs2f7DZzv9ulHwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpXn/AO01/wAyt/29/wDtGj/hpr/qUf8Aypf/AGqj/k4z/qXv7C/7e/P8/wD797dvk++d3bHJ/wANNf8AUo/+VL/7VXAfE34Zf8K5/sv/AIm/9ofb/N/5dvK2bNn+22c7/bpR8Mvib/wrn+1P+JR/aH2/yv8Al58rZs3/AOw2c7/bpR8Mvhl/wsb+1P8Aib/2f9g8r/l283fv3/7a4xs9+tHwy+Jv/Cuf7U/4lH9ofb/K/wCXnytmzf8A7DZzv9ulfX9FFFFfP/8AwzL/ANTd/wCU3/7bXoHwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpXgHwy+GX/Cxv7U/4m/9n/YPK/5dvN379/8AtrjGz3613/8AwzL/ANTd/wCU3/7bR/w01/1KP/lS/wDtVegfDL4Zf8K5/tT/AIm/9ofb/K/5dvK2bN/+22c7/bpR8Mvib/wsb+1P+JR/Z/2Dyv8Al583fv3/AOwuMbPfrR8Mvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9uleAfE34Zf8ACuf7L/4m/wDaH2/zf+XbytmzZ/ttnO/26V3/AO01/wAyt/29/wDtGuA+GXwy/wCFjf2p/wATf+z/ALB5X/Lt5u/fv/21xjZ79a9/+Jvwy/4WN/Zf/E3/ALP+web/AMu3m79+z/bXGNnv1rwD4m/DL/hXP9l/8Tf+0Pt/m/8ALt5WzZs/22znf7dK9/8Aib8Tf+Fc/wBl/wDEo/tD7f5v/Lz5WzZs/wBhs53+3SvP/wBpr/mVv+3v/wBo0f8AJuf/AFMP9u/9unkeR/383bvO9sbe+eD9mX/maf8At0/9rV4BXoHwy+Jv/Cuf7U/4lH9ofb/K/wCXnytmzf8A7DZzv9uld/8A8m5/9TD/AG7/ANunkeR/383bvO9sbe+eOA+GXxN/4Vz/AGp/xKP7Q+3+V/y8+Vs2b/8AYbOd/t0rv/8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPHoHxN+GX/Cxv7L/wCJv/Z/2Dzf+Xbzd+/Z/trjGz3614B8Mvib/wAK5/tT/iUf2h9v8r/l58rZs3/7DZzv9ule/wDxN+Jv/Cuf7L/4lH9ofb/N/wCXnytmzZ/sNnO/26UfE34m/wDCuf7L/wCJR/aH2/zf+XnytmzZ/sNnO/26V5/+zL/zNP8A26f+1q+gKKKK+f8A/k3P/qYf7d/7dPI8j/v5u3ed7Y2988H/ACbn/wBTD/bv/bp5Hkf9/N27zvbG3vnjgPib8Mv+Fc/2X/xN/wC0Pt/m/wDLt5WzZs/22znf7dK9/wDhl8Mv+Fc/2p/xN/7Q+3+V/wAu3lbNm/8A22znf7dKPib8Mv8AhY39l/8AE3/s/wCweb/y7ebv37P9tcY2e/WvAPib8Mv+Fc/2X/xN/wC0Pt/m/wDLt5WzZs/22znf7dK8/r3/APaa/wCZW/7e/wD2jXAfDL4m/wDCuf7U/wCJR/aH2/yv+Xnytmzf/sNnO/26V7/8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXn//AA01/wBSj/5Uv/tVegfE34m/8K5/sv8A4lH9ofb/ADf+XnytmzZ/sNnO/wBulHxN+Jv/AArn+y/+JR/aH2/zf+XnytmzZ/sNnO/26V5/+01/zK3/AG9/+0aP2Zf+Zp/7dP8A2tR+zL/zNP8A26f+1qP+TjP+pe/sL/t78/z/APv3t2+T753dsc+AV7/+zL/zNP8A26f+1q9A+GXwy/4Vz/an/E3/ALQ+3+V/y7eVs2b/APbbOd/t0rwD4ZfDL/hY39qf8Tf+z/sHlf8ALt5u/fv/ANtcY2e/Wvf/AIm/E3/hXP8AZf8AxKP7Q+3+b/y8+Vs2bP8AYbOd/t0rwD4m/DL/AIVz/Zf/ABN/7Q+3+b/y7eVs2bP9ts53+3Su/wD2mv8AmVv+3v8A9o1wHwy+Jv8Awrn+1P8AiUf2h9v8r/l58rZs3/7DZzv9ulHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9ule/8Awy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpXoFFFFfIHwy+GX/Cxv7U/4m/8AZ/2Dyv8Al283fv3/AO2uMbPfrXf/APDMv/U3f+U3/wC20f8AJxn/AFL39hf9vfn+f/3727fJ987u2OfQPhl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK8//wCGmv8AqUf/ACpf/aq8Ar3/AP4aa/6lH/ypf/aq9A+GXwy/4Vz/AGp/xN/7Q+3+V/y7eVs2b/8AbbOd/t0rwD4m/DL/AIVz/Zf/ABN/7Q+3+b/y7eVs2bP9ts53+3Svf/ib8Mv+Fjf2X/xN/wCz/sHm/wDLt5u/fs/21xjZ79a8/wD+TjP+pe/sL/t78/z/APv3t2+T753dsc+gfDL4m/8ACxv7U/4lH9n/AGDyv+Xnzd+/f/sLjGz360fDL4Zf8K5/tT/ib/2h9v8AK/5dvK2bN/8AttnO/wBulef/APJxn/Uvf2F/29+f5/8A3727fJ987u2OT/hpr/qUf/Kl/wDaqP2mv+ZW/wC3v/2jR+zL/wAzT/26f+1q8Ar3/wD4Zl/6m7/ym/8A22vQPhl8Tf8AhY39qf8AEo/s/wCweV/y8+bv37/9hcY2e/Wj4m/E3/hXP9l/8Sj+0Pt/m/8ALz5WzZs/2Gznf7dKPib8Mv8AhY39l/8AE3/s/wCweb/y7ebv37P9tcY2e/Wj4ZfE3/hY39qf8Sj+z/sHlf8ALz5u/fv/ANhcY2e/Wj4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3SvQK+f/wDk4z/qXv7C/wC3vz/P/wC/e3b5Pvnd2xz9AUUUUV5/8Mvhl/wrn+1P+Jv/AGh9v8r/AJdvK2bN/wDttnO/26V5/wD8m5/9TD/bv/bp5Hkf9/N27zvbG3vnjwCvQPib8Mv+Fc/2X/xN/wC0Pt/m/wDLt5WzZs/22znf7dK7/wD5Nz/6mH+3f+3TyPI/7+bt3ne2NvfPHAfDL4m/8K5/tT/iUf2h9v8AK/5efK2bN/8AsNnO/wBulHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrXf8A7TX/ADK3/b3/AO0a4D4m/DL/AIVz/Zf/ABN/7Q+3+b/y7eVs2bP9ts53+3Sj4ZfDL/hY39qf8Tf+z/sHlf8ALt5u/fv/ANtcY2e/Wu//AGmv+ZW/7e//AGjXoHxN+GX/AAsb+y/+Jv8A2f8AYPN/5dvN379n+2uMbPfrXoFfIHwy+Jv/AArn+1P+JR/aH2/yv+Xnytmzf/sNnO/26UfDL4Zf8LG/tT/ib/2f9g8r/l283fv3/wC2uMbPfrXf/wDDTX/Uo/8AlS/+1Ufsy/8AM0/9un/tavAK9A+GXwy/4WN/an/E3/s/7B5X/Lt5u/fv/wBtcY2e/Wu//wCGmv8AqUf/ACpf/aq4D4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Su//wCTjP8AqXv7C/7e/P8AP/797dvk++d3bHPoHxN+Jv8Awrn+y/8AiUf2h9v83/l58rZs2f7DZzv9ulHxN+Jv/Cuf7L/4lH9ofb/N/wCXnytmzZ/sNnO/26UfDL4m/wDCxv7U/wCJR/Z/2Dyv+Xnzd+/f/sLjGz360fE34m/8K5/sv/iUf2h9v83/AJefK2bNn+w2c7/bpR8Mvib/AMLG/tT/AIlH9n/YPK/5efN379/+wuMbPfrXoFFFFfIHwy+Jv/Cuf7U/4lH9ofb/ACv+Xnytmzf/ALDZzv8AbpX1/XwBXoHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9ule/8Awy+Jv/Cxv7U/4lH9n/YPK/5efN379/8AsLjGz360fE34m/8ACuf7L/4lH9ofb/N/5efK2bNn+w2c7/bpR8Mvhl/wrn+1P+Jv/aH2/wAr/l28rZs3/wC22c7/AG6V5/8Asy/8zT/26f8AtauA+JvxN/4WN/Zf/Eo/s/7B5v8Ay8+bv37P9hcY2e/Wvf8A4m/E3/hXP9l/8Sj+0Pt/m/8ALz5WzZs/2Gznf7dK8A+JvxN/4WN/Zf8AxKP7P+web/y8+bv37P8AYXGNnv1r3/4m/E3/AIVz/Zf/ABKP7Q+3+b/y8+Vs2bP9hs53+3SvP/8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPB/w01/1KP/AJUv/tVegfE34m/8K5/sv/iUf2h9v83/AJefK2bNn+w2c7/bpXn/AO01/wAyt/29/wDtGj/hpr/qUf8Aypf/AGqvoCvkD4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Svf/ib8Tf8AhXP9l/8AEo/tD7f5v/Lz5WzZs/2Gznf7dK8//wCGZf8Aqbv/ACm//baP2mv+ZW/7e/8A2jR/ybn/ANTD/bv/AG6eR5H/AH83bvO9sbe+ePQPib8Tf+Fc/wBl/wDEo/tD7f5v/Lz5WzZs/wBhs53+3SvAPhl8Tf8AhXP9qf8AEo/tD7f5X/Lz5WzZv/2Gznf7dK9/+GXxN/4WN/an/Eo/s/7B5X/Lz5u/fv8A9hcY2e/Wj4ZfE3/hY39qf8Sj+z/sHlf8vPm79+//AGFxjZ79a9Aoooor5/8A2Zf+Zp/7dP8A2tR/wzL/ANTd/wCU3/7bR/ybn/1MP9u/9unkeR/383bvO9sbe+ePQPib8Tf+Fc/2X/xKP7Q+3+b/AMvPlbNmz/YbOd/t0o+JvxN/4Vz/AGX/AMSj+0Pt/m/8vPlbNmz/AGGznf7dK8A+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0r3/4m/DL/hY39l/8Tf8As/7B5v8Ay7ebv37P9tcY2e/Wj4m/E3/hXP8AZf8AxKP7Q+3+b/y8+Vs2bP8AYbOd/t0r5Ar0D4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Su//wCGmv8AqUf/ACpf/aq4D4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Su//aa/5lb/ALe//aNcB8Mvhl/wsb+1P+Jv/Z/2Dyv+Xbzd+/f/ALa4xs9+tHxN+Jv/AAsb+y/+JR/Z/wBg83/l583fv2f7C4xs9+te/wDwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpXgHwy+GX/Cxv7U/4m/9n/YPK/5dvN379/8AtrjGz360fE34Zf8ACuf7L/4m/wDaH2/zf+XbytmzZ/ttnO/26V5/Xv8A+01/zK3/AG9/+0a4D4ZfDL/hY39qf8Tf+z/sHlf8u3m79+//AG1xjZ79a9/+GXxN/wCFjf2p/wASj+z/ALB5X/Lz5u/fv/2FxjZ79aPhl8Mv+Fc/2p/xN/7Q+3+V/wAu3lbNm/8A22znf7dK+QK9/wD2Zf8Amaf+3T/2tX0BRRRRXyB8Tfhl/wAK5/sv/ib/ANofb/N/5dvK2bNn+22c7/bpXf8A/DTX/Uo/+VL/AO1VwHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrXf8A/DMv/U3f+U3/AO21wHwy+Jv/AArn+1P+JR/aH2/yv+Xnytmzf/sNnO/26UfDL4m/8K5/tT/iUf2h9v8AK/5efK2bN/8AsNnO/wBule//ABN+Jv8Awrn+y/8AiUf2h9v83/l58rZs2f7DZzv9uleAfE34m/8ACxv7L/4lH9n/AGDzf+Xnzd+/Z/sLjGz3615/XoHxN+Jv/Cxv7L/4lH9n/YPN/wCXnzd+/Z/sLjGz3613/wC01/zK3/b3/wC0a9A+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0rwD4ZfDL/hY39qf8Tf8As/7B5X/Lt5u/fv8A9tcY2e/Wu/8A+GZf+pu/8pv/ANtrgPhl8Mv+Fjf2p/xN/wCz/sHlf8u3m79+/wD21xjZ79a8/r0D4ZfDL/hY39qf8Tf+z/sHlf8ALt5u/fv/ANtcY2e/Wj4m/E3/AIWN/Zf/ABKP7P8AsHm/8vPm79+z/YXGNnv1rv8A/hpr/qUf/Kl/9qr0D4m/DL/hY39l/wDE3/s/7B5v/Lt5u/fs/wBtcY2e/WvP/wBmX/maf+3T/wBrV6B8Mvib/wALG/tT/iUf2f8AYPK/5efN379/+wuMbPfrXgHwy+GX/Cxv7U/4m/8AZ/2Dyv8Al283fv3/AO2uMbPfrXf/APDMv/U3f+U3/wC20fsy/wDM0/8Abp/7WrgPib8Mv+Fc/wBl/wDE3/tD7f5v/Lt5WzZs/wBts53+3Svf/hl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK9Aooorz/4m/DL/AIWN/Zf/ABN/7P8AsHm/8u3m79+z/bXGNnv1rwD4ZfE3/hXP9qf8Sj+0Pt/lf8vPlbNm/wD2Gznf7dK7/wDZl/5mn/t0/wDa1egfDL4Zf8K5/tT/AIm/9ofb/K/5dvK2bN/+22c7/bpXgHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrR8Tfhl/wrn+y/wDib/2h9v8AN/5dvK2bNn+22c7/AG6V3/7TX/Mrf9vf/tGuA+GXxN/4Vz/an/Eo/tD7f5X/AC8+Vs2b/wDYbOd/t0o+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0r6/rz/4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3Sj4ZfDL/hXP9qf8Tf+0Pt/lf8ALt5WzZv/ANts53+3SvP/ANmX/maf+3T/ANrV6B8Mvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9uleAfDL4m/8ACuf7U/4lH9ofb/K/5efK2bN/+w2c7/bpX1/RRXyB8Tfib/wsb+y/+JR/Z/2Dzf8Al583fv2f7C4xs9+td/8A8m5/9TD/AG7/ANunkeR/383bvO9sbe+ePAK+v/ib8Tf+Fc/2X/xKP7Q+3+b/AMvPlbNmz/YbOd/t0rz/APZl/wCZp/7dP/a1egfDL4Zf8K5/tT/ib/2h9v8AK/5dvK2bN/8AttnO/wBuleAfDL4m/wDCuf7U/wCJR/aH2/yv+Xnytmzf/sNnO/26V7/8Tfhl/wALG/sv/ib/ANn/AGDzf+Xbzd+/Z/trjGz3615/+zL/AMzT/wBun/tavoCiiivP/ib8Tf8AhXP9l/8AEo/tD7f5v/Lz5WzZs/2Gznf7dK8//wCTc/8AqYf7d/7dPI8j/v5u3ed7Y2988H/DMv8A1N3/AJTf/ttH/DMv/U3f+U3/AO214BXv/wDwzL/1N3/lN/8AttH/AA01/wBSj/5Uv/tVH/DMv/U3f+U3/wC214BXoHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrXf8A7Mv/ADNP/bp/7Wr0D4ZfE3/hY39qf8Sj+z/sHlf8vPm79+//AGFxjZ79a8//AOGZf+pu/wDKb/8Aba4D4ZfDL/hY39qf8Tf+z/sHlf8ALt5u/fv/ANtcY2e/Wj4ZfDL/AIWN/an/ABN/7P8AsHlf8u3m79+//bXGNnv1r3/4m/DL/hY39l/8Tf8As/7B5v8Ay7ebv37P9tcY2e/WvP8A9mX/AJmn/t0/9rV9AV8//wDDMv8A1N3/AJTf/ttH/Jxn/Uvf2F/29+f5/wD3727fJ987u2OfQPib8Mv+Fjf2X/xN/wCz/sHm/wDLt5u/fs/21xjZ79a9Ar5A+Jvwy/4Vz/Zf/E3/ALQ+3+b/AMu3lbNmz/bbOd/t0o+Jvwy/4Vz/AGX/AMTf+0Pt/m/8u3lbNmz/AG2znf7dK9/+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0rz//AJOM/wCpe/sL/t78/wA//v3t2+T753dscn7Mv/M0/wDbp/7Wr6Aooorz/wCGXwy/4Vz/AGp/xN/7Q+3+V/y7eVs2b/8AbbOd/t0rz/8A4Zl/6m7/AMpv/wBto/Zl/wCZp/7dP/a1H/Juf/Uw/wBu/wDbp5Hkf9/N27zvbG3vng/Zl/5mn/t0/wDa1H/Juf8A1MP9u/8Abp5Hkf8Afzdu872xt7544D4ZfDL/AIWN/an/ABN/7P8AsHlf8u3m79+//bXGNnv1o+GXwy/4WN/an/E3/s/7B5X/AC7ebv37/wDbXGNnv1o+JvxN/wCFjf2X/wASj+z/ALB5v/Lz5u/fs/2FxjZ79aPhl8Mv+Fjf2p/xN/7P+weV/wAu3m79+/8A21xjZ79a7/8A5OM/6l7+wv8At78/z/8Av3t2+T753dsc8B8Mvib/AMK5/tT/AIlH9ofb/K/5efK2bN/+w2c7/bpXv/xN+GX/AAsb+y/+Jv8A2f8AYPN/5dvN379n+2uMbPfrXn//AA01/wBSj/5Uv/tVegfDL4m/8LG/tT/iUf2f9g8r/l583fv3/wCwuMbPfrXn/wCzL/zNP/bp/wC1q4D4ZfE3/hXP9qf8Sj+0Pt/lf8vPlbNm/wD2Gznf7dKPib8Mv+Fc/wBl/wDE3/tD7f5v/Lt5WzZs/wBts53+3Su//Zl/5mn/ALdP/a1fQFef/E34Zf8ACxv7L/4m/wDZ/wBg83/l283fv2f7a4xs9+tef/8ADTX/AFKP/lS/+1VwHxN+GX/Cuf7L/wCJv/aH2/zf+XbytmzZ/ttnO/26V5/Xv/8AwzL/ANTd/wCU3/7bR/ybn/1MP9u/9unkeR/383bvO9sbe+eD9mX/AJmn/t0/9rV9AUUUV8AUV7//AMnGf9S9/YX/AG9+f5//AH727fJ987u2OfQPhl8Mv+Fc/wBqf8Tf+0Pt/lf8u3lbNm//AG2znf7dK8A+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0rv8A9pr/AJlb/t7/APaNH/DMv/U3f+U3/wC20f8ADMv/AFN3/lN/+216B8Mvhl/wrn+1P+Jv/aH2/wAr/l28rZs3/wC22c7/AG6V5/8A8nGf9S9/YX/b35/n/wDfvbt8n3zu7Y59A+Jvwy/4WN/Zf/E3/s/7B5v/AC7ebv37P9tcY2e/WvQK+QPib8Tf+Fjf2X/xKP7P+web/wAvPm79+z/YXGNnv1o+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0r3/4m/DL/hY39l/8Tf8As/7B5v8Ay7ebv37P9tcY2e/Wj4ZfE3/hY39qf8Sj+z/sHlf8vPm79+//AGFxjZ79a8//AOTjP+pe/sL/ALe/P8//AL97dvk++d3bHPoHxN+Jv/Cuf7L/AOJR/aH2/wA3/l58rZs2f7DZzv8AbpR8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXgHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9uld/8A8My/9Td/5Tf/ALbXoHxN+Jv/AArn+y/+JR/aH2/zf+XnytmzZ/sNnO/26V5/+zL/AMzT/wBun/taj/k3P/qYf7d/7dPI8j/v5u3ed7Y2988fQFfP/wDybn/1MP8Abv8A26eR5H/fzdu872xt754+gKKKKK+AK+v/AIZfE3/hY39qf8Sj+z/sHlf8vPm79+//AGFxjZ79aPhl8Tf+Fjf2p/xKP7P+weV/y8+bv37/APYXGNnv1rwD4m/DL/hXP9l/8Tf+0Pt/m/8ALt5WzZs/22znf7dK9/8Ahl8Mv+Fc/wBqf8Tf+0Pt/lf8u3lbNm//AG2znf7dK8//AOGZf+pu/wDKb/8Aba8Ar6/+Jvwy/wCFjf2X/wATf+z/ALB5v/Lt5u/fs/21xjZ79aPib8Mv+Fjf2X/xN/7P+web/wAu3m79+z/bXGNnv1rz/wD4Zl/6m7/ym/8A22j/AJNz/wCph/t3/t08jyP+/m7d53tjb3zx6B8Mvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9ulHwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpXgHwy+Jv/Cuf7U/4lH9ofb/ACv+Xnytmzf/ALDZzv8AbpXv/wAMvib/AMLG/tT/AIlH9n/YPK/5efN379/+wuMbPfrXgHxN+GX/AArn+y/+Jv8A2h9v83/l28rZs2f7bZzv9uld/wD8NNf9Sj/5Uv8A7VX0BXyB8Mvhl/wsb+1P+Jv/AGf9g8r/AJdvN379/wDtrjGz3619f18//wDDTX/Uo/8AlS/+1V6B8Tfhl/wsb+y/+Jv/AGf9g83/AJdvN379n+2uMbPfrR8Mvib/AMLG/tT/AIlH9n/YPK/5efN379/+wuMbPfrR8Mvib/wsb+1P+JR/Z/2Dyv8Al583fv3/AOwuMbPfrR8Tfhl/wsb+y/8Aib/2f9g83/l283fv2f7a4xs9+tef/sy/8zT/ANun/taj9mX/AJmn/t0/9rV9AUUUV8//ALTX/Mrf9vf/ALRo/wCGZf8Aqbv/ACm//ba+gK+f/wDk3P8A6mH+3f8At08jyP8Av5u3ed7Y2988eAUV7/8A8NNf9Sj/AOVL/wC1Uf8AJuf/AFMP9u/9unkeR/383bvO9sbe+ePQPib8Mv8AhY39l/8AE3/s/wCweb/y7ebv37P9tcY2e/WvP/8Ak4z/AKl7+wv+3vz/AD/+/e3b5Pvnd2xzwHwy+Jv/AArn+1P+JR/aH2/yv+Xnytmzf/sNnO/26UfDL4Zf8LG/tT/ib/2f9g8r/l283fv3/wC2uMbPfrXv/wATfib/AMK5/sv/AIlH9ofb/N/5efK2bNn+w2c7/bpXn/7Mv/M0/wDbp/7Wr0D4ZfDL/hXP9qf8Tf8AtD7f5X/Lt5WzZv8A9ts53+3Sj4ZfDL/hXP8Aan/E3/tD7f5X/Lt5WzZv/wBts53+3SvAPib8Mv8AhXP9l/8AE3/tD7f5v/Lt5WzZs/22znf7dKPhl8Mv+Fjf2p/xN/7P+weV/wAu3m79+/8A21xjZ79a7/8AZl/5mn/t0/8Aa1cB8Mvib/wrn+1P+JR/aH2/yv8Al58rZs3/AOw2c7/bpR8Mvib/AMK5/tT/AIlH9ofb/K/5efK2bN/+w2c7/bpXf/8AJuf/AFMP9u/9unkeR/383bvO9sbe+eOA+Jvwy/4Vz/Zf/E3/ALQ+3+b/AMu3lbNmz/bbOd/t0o+GXxN/4Vz/AGp/xKP7Q+3+V/y8+Vs2b/8AYbOd/t0rv/8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPB/w01/1KP/AJUv/tVegfDL4m/8LG/tT/iUf2f9g8r/AJefN379/wDsLjGz3616BRRRRXyB8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpR8Mvib/AMK5/tT/AIlH9ofb/K/5efK2bN/+w2c7/bpXv/wy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulHxN+GX/Cxv7L/AOJv/Z/2Dzf+Xbzd+/Z/trjGz3615/8A8My/9Td/5Tf/ALbXoHxN+Jv/AArn+y/+JR/aH2/zf+XnytmzZ/sNnO/26V4B8Mvhl/wsb+1P+Jv/AGf9g8r/AJdvN379/wDtrjGz3617/wDDL4m/8LG/tT/iUf2f9g8r/l583fv3/wCwuMbPfrXgHxN+Jv8Awsb+y/8AiUf2f9g83/l583fv2f7C4xs9+te//DL4m/8ACxv7U/4lH9n/AGDyv+Xnzd+/f/sLjGz3614B8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpXv/AMTfhl/wsb+y/wDib/2f9g83/l283fv2f7a4xs9+tegV5/8AE34Zf8LG/sv/AIm/9n/YPN/5dvN379n+2uMbPfrR8Tfib/wrn+y/+JR/aH2/zf8Al58rZs2f7DZzv9ulef8A/Jxn/Uvf2F/29+f5/wD3727fJ987u2OfAK9A+GXxN/4Vz/an/Eo/tD7f5X/Lz5WzZv8A9hs53+3Svf8A4m/E3/hXP9l/8Sj+0Pt/m/8ALz5WzZs/2Gznf7dKPhl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK9Ar5A+JvxN/wCFjf2X/wASj+z/ALB5v/Lz5u/fs/2FxjZ79aPhl8Mv+Fjf2p/xN/7P+weV/wAu3m79+/8A21xjZ79a9/8Aib8Tf+Fc/wBl/wDEo/tD7f5v/Lz5WzZs/wBhs53+3SvQK8/+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0r0CiiivkD4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Su//wCGZf8Aqbv/ACm//ba+gK8/+GXwy/4Vz/an/E3/ALQ+3+V/y7eVs2b/APbbOd/t0rz/AP4Zl/6m7/ym/wD22vQPib8Tf+Fc/wBl/wDEo/tD7f5v/Lz5WzZs/wBhs53+3SvQK8/+Jvwy/wCFjf2X/wATf+z/ALB5v/Lt5u/fs/21xjZ79a8//Zl/5mn/ALdP/a1cB8Tfib/wsb+y/wDiUf2f9g83/l583fv2f7C4xs9+te//AAy+GX/Cuf7U/wCJv/aH2/yv+Xbytmzf/ttnO/26UfE34m/8K5/sv/iUf2h9v83/AJefK2bNn+w2c7/bpR8Tfhl/wsb+y/8Aib/2f9g83/l283fv2f7a4xs9+tef/wDJuf8A1MP9u/8Abp5Hkf8Afzdu872xt754P+TjP+pe/sL/ALe/P8//AL97dvk++d3bHPoHwy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpR8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXn//AAzL/wBTd/5Tf/tteAUV9f8AxN+Jv/Cuf7L/AOJR/aH2/wA3/l58rZs2f7DZzv8AbpXgHxN+Jv8Awsb+y/8AiUf2f9g83/l583fv2f7C4xs9+tfX9FfIHwy+Jv8Awrn+1P8AiUf2h9v8r/l58rZs3/7DZzv9ulHwy+Jv/Cuf7U/4lH9ofb/K/wCXnytmzf8A7DZzv9ule/8Awy+Jv/Cxv7U/4lH9n/YPK/5efN379/8AsLjGz3616BRRRXyB8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpXf/APJxn/Uvf2F/29+f5/8A3727fJ987u2OT/hmX/qbv/Kb/wDbaP8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPB/wzL/ANTd/wCU3/7bR+01/wAyt/29/wDtGj9mX/maf+3T/wBrV6B8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXn//AAzL/wBTd/5Tf/ttH/Juf/Uw/wBu/wDbp5Hkf9/N27zvbG3vnjgPhl8Mv+Fjf2p/xN/7P+weV/y7ebv37/8AbXGNnv1r3/4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3SvP/2Zf+Zp/wC3T/2tXoHxN+GX/Cxv7L/4m/8AZ/2Dzf8Al283fv2f7a4xs9+tef8A/Jxn/Uvf2F/29+f5/wD3727fJ987u2OfQPib8Mv+Fjf2X/xN/wCz/sHm/wDLt5u/fs/21xjZ79a8/wD+Gmv+pR/8qX/2quA+JvxN/wCFjf2X/wASj+z/ALB5v/Lz5u/fs/2FxjZ79a9/+Jvwy/4WN/Zf/E3/ALP+web/AMu3m79+z/bXGNnv1rwD4m/DL/hXP9l/8Tf+0Pt/m/8ALt5WzZs/22znf7dKPib8Mv8AhXP9l/8AE3/tD7f5v/Lt5WzZs/22znf7dK9/+JvxN/4Vz/Zf/Eo/tD7f5v8Ay8+Vs2bP9hs53+3SvP8A9pr/AJlb/t7/APaNH/Juf/Uw/wBu/wDbp5Hkf9/N27zvbG3vng/Zl/5mn/t0/wDa1eAV7/8Asy/8zT/26f8AtavoCiiiivP/AIm/DL/hY39l/wDE3/s/7B5v/Lt5u/fs/wBtcY2e/WvQK8/+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0o+GXxN/4WN/an/Eo/s/7B5X/AC8+bv37/wDYXGNnv1o+Jvwy/wCFjf2X/wATf+z/ALB5v/Lt5u/fs/21xjZ79a8//aa/5lb/ALe//aNH/Jxn/Uvf2F/29+f5/wD3727fJ987u2OfAK9//wCTjP8AqXv7C/7e/P8AP/797dvk++d3bHJ/w01/1KP/AJUv/tVH/DMv/U3f+U3/AO21wHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrXf8A/DMv/U3f+U3/AO214BXv/wC01/zK3/b3/wC0aP8Ak4z/AKl7+wv+3vz/AD/+/e3b5Pvnd2xyftNf8yt/29/+0a4D4ZfE3/hXP9qf8Sj+0Pt/lf8ALz5WzZv/ANhs53+3Svf/AIZfDL/hXP8Aan/E3/tD7f5X/Lt5WzZv/wBts53+3SvAPhl8Mv8AhY39qf8AE3/s/wCweV/y7ebv37/9tcY2e/Wu/wD+Tc/+ph/t3/t08jyP+/m7d53tjb3zxwHwy+GX/Cxv7U/4m/8AZ/2Dyv8Al283fv3/AO2uMbPfrXf/APDMv/U3f+U3/wC21wHwy+Jv/Cuf7U/4lH9ofb/K/wCXnytmzf8A7DZzv9ule/8AxN+Jv/Cuf7L/AOJR/aH2/wA3/l58rZs2f7DZzv8AbpR8Mvib/wALG/tT/iUf2f8AYPK/5efN379/+wuMbPfrXoFFFFfIHwy+GX/Cxv7U/wCJv/Z/2Dyv+Xbzd+/f/trjGz3613//AAzL/wBTd/5Tf/ttH/DMv/U3f+U3/wC20fsy/wDM0/8Abp/7Wo/5OM/6l7+wv+3vz/P/AO/e3b5Pvnd2xyf8NNf9Sj/5Uv8A7VXAfDL4m/8ACuf7U/4lH9ofb/K/5efK2bN/+w2c7/bpR8Mvhl/wsb+1P+Jv/Z/2Dyv+Xbzd+/f/ALa4xs9+td//AMNNf9Sj/wCVL/7VR/ybn/1MP9u/9unkeR/383bvO9sbe+ePAK9//Zl/5mn/ALdP/a1H7Mv/ADNP/bp/7Wr0D4ZfDL/hXP8Aan/E3/tD7f5X/Lt5WzZv/wBts53+3SvAPhl8Mv8AhY39qf8AE3/s/wCweV/y7ebv37/9tcY2e/WvP69//Zl/5mn/ALdP/a1H7Mv/ADNP/bp/7Wo/aa/5lb/t7/8AaNegfDL4m/8ACxv7U/4lH9n/AGDyv+Xnzd+/f/sLjGz3615/+zL/AMzT/wBun/taj/k3P/qYf7d/7dPI8j/v5u3ed7Y2988H7Mv/ADNP/bp/7Wr0D4ZfDL/hXP8Aan/E3/tD7f5X/Lt5WzZv/wBts53+3SvkCvQPhl8Mv+Fjf2p/xN/7P+weV/y7ebv37/8AbXGNnv1r3/4ZfE3/AIWN/an/ABKP7P8AsHlf8vPm79+//YXGNnv1r0Ciiivn/wDZl/5mn/t0/wDa1eAV7/8Asy/8zT/26f8Ataj9mX/maf8At0/9rUf8nGf9S9/YX/b35/n/APfvbt8n3zu7Y59A+GXxN/4WN/an/Eo/s/7B5X/Lz5u/fv8A9hcY2e/WvP8A/hpr/qUf/Kl/9qrgPhl8Mv8AhY39qf8AE3/s/wCweV/y7ebv37/9tcY2e/WvP6+v/hl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK8//aa/5lb/ALe//aNegfDL4m/8LG/tT/iUf2f9g8r/AJefN379/wDsLjGz3615/wD8My/9Td/5Tf8A7bR/wzL/ANTd/wCU3/7bXAfDL4Zf8LG/tT/ib/2f9g8r/l283fv3/wC2uMbPfrXv/wATfhl/wsb+y/8Aib/2f9g83/l283fv2f7a4xs9+tHwy+Jv/Cxv7U/4lH9n/YPK/wCXnzd+/f8A7C4xs9+tef8A/Juf/Uw/27/26eR5H/fzdu872xt7544D4m/DL/hXP9l/8Tf+0Pt/m/8ALt5WzZs/22znf7dK7/8A5Nz/AOph/t3/ALdPI8j/AL+bt3ne2NvfPHAfDL4m/wDCuf7U/wCJR/aH2/yv+Xnytmzf/sNnO/26V7/8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXgHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9ulef0V9f8Awy+Jv/Cxv7U/4lH9n/YPK/5efN379/8AsLjGz3615/8Asy/8zT/26f8AtavoCiiivn/9mX/maf8At0/9rUf8My/9Td/5Tf8A7bXoHwy+GX/Cuf7U/wCJv/aH2/yv+Xbytmzf/ttnO/26V5/+zL/zNP8A26f+1q9A+Jvwy/4WN/Zf/E3/ALP+web/AMu3m79+z/bXGNnv1r0CvgCvr/4m/DL/AIWN/Zf/ABN/7P8AsHm/8u3m79+z/bXGNnv1o+JvxN/4Vz/Zf/Eo/tD7f5v/AC8+Vs2bP9hs53+3Sj4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3SvP/2mv+ZW/wC3v/2jR/wzL/1N3/lN/wDttcB8Mvib/wAK5/tT/iUf2h9v8r/l58rZs3/7DZzv9ule/wDwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpR8Tfib/AMK5/sv/AIlH9ofb/N/5efK2bNn+w2c7/bpR8Tfhl/wsb+y/+Jv/AGf9g83/AJdvN379n+2uMbPfrXgHwy+Jv/Cuf7U/4lH9ofb/ACv+Xnytmzf/ALDZzv8AbpR8Mvhl/wALG/tT/ib/ANn/AGDyv+Xbzd+/f/trjGz3617/APDL4Zf8K5/tT/ib/wBofb/K/wCXbytmzf8A7bZzv9ulef8A/DMv/U3f+U3/AO21wHwy+Jv/AArn+1P+JR/aH2/yv+Xnytmzf/sNnO/26V3/AO01/wAyt/29/wDtGuA+GXxN/wCFc/2p/wASj+0Pt/lf8vPlbNm//YbOd/t0r3/4m/E3/hXP9l/8Sj+0Pt/m/wDLz5WzZs/2Gznf7dK8/wD2Zf8Amaf+3T/2tXAfE34Zf8K5/sv/AIm/9ofb/N/5dvK2bNn+22c7/bpXv/wy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulegUUUV8//APDMv/U3f+U3/wC20f8ADMv/AFN3/lN/+20f8My/9Td/5Tf/ALbXoHwy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulef/8ADMv/AFN3/lN/+20f8My/9Td/5Tf/ALbR/wAMy/8AU3f+U3/7bX0BXn/xN+GX/Cxv7L/4m/8AZ/2Dzf8Al283fv2f7a4xs9+tef8A/DMv/U3f+U3/AO216B8Mvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9ulHxN+GX/Cxv7L/4m/8AZ/2Dzf8Al283fv2f7a4xs9+tHwy+GX/Cuf7U/wCJv/aH2/yv+Xbytmzf/ttnO/26V6BXn/xN+GX/AAsb+y/+Jv8A2f8AYPN/5dvN379n+2uMbPfrR8Mvhl/wrn+1P+Jv/aH2/wAr/l28rZs3/wC22c7/AG6V5/8A8My/9Td/5Tf/ALbXoHwy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulef/8ADMv/AFN3/lN/+20f8My/9Td/5Tf/ALbXoHxN+GX/AAsb+y/+Jv8A2f8AYPN/5dvN379n+2uMbPfrR8Mvhl/wrn+1P+Jv/aH2/wAr/l28rZs3/wC22c7/AG6UfE34Zf8ACxv7L/4m/wDZ/wBg83/l283fv2f7a4xs9+tegV5/8Mvhl/wrn+1P+Jv/AGh9v8r/AJdvK2bN/wDttnO/26UfE34Zf8LG/sv/AIm/9n/YPN/5dvN379n+2uMbPfrXoFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFf/2Q=="
  }
}
```

STATUS 202

Response Body: Boleto pendente de registro

```json
{
  "request_control_key": "f14e9bac-94ed-4eb1-87b4-7fd7b7a2d280",
  "bank_slip_key": "e8599844-5cad-40b4-8716-cb4770d415b4",
  "bank_slip_status": "accepted"
}
```

:::info Informação
Caso seja retornado **HTTP Status 202** com o campo `bank_slip_status` com valor `accepted`, a emissão não deve ser retentada.

Esta emissão será processada assincronamente. É necessário verificar o status do boleto por meio
da consulta de boleto, ou aguardar o recebimento do webhook de confirmação descrito na [página de webhooks](/documentation/boletos/v2/webhooks/boleto).
:::

### Response Body Params

| Campo                   | Tipo   | Descrição                                                                         | Caracteres |
|-------------------------|--------|-----------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4 | 36         |
| `bank_slip_key` *       | uuidv4 | Chave única de identificação do boleto no formato uuid v4                         | 36         |
| `bank_slip_status` *    | string | Status do boleto       | **[Enumeradores bank_slip_status](#enumeradores-bank_slip_status)**   |
| `our_number` *          | integer| Número único de identificação do boleto junto à carteira                          | 11         |
| `barcode` *             | string | Código de barras do boleto                                                        | 44         |
| `digitable_line` *      | string | Linha digitável do boleto                                                         | 47         |
| `qr_code_data`          | object | Dados do QR Code                             | **[Objeto qr_code_data](#objeto-qr_code_data)** |
| `created_at` *          | string | Data, no formato ISO (UTC - "YYYY-MM-DDTHH:MM:SSZ"), da criação da ocorrência     | 20         |

### Enumeradores bank_slip_status

| Enumerador         | Descrição                               |
|--------------------|-----------------------------------------|
| accepted           | Boleto aceito mas ainda não registrado  |
| registered         | Boleto registrado                       |

### Objeto qr_code_data
| Campo                      | Tipo   | Descrição                                             | Caracteres              |
|----------------------------|--------|-------------------------------------------------------|-------------------------|
| `qr_code_key`              | uuidv4 | Chave única de identificação do QR Code               | 36                      |
| `pix_key`                  | uuidv4 | Chave PIX vinculada ao QR Code                        | 36                      |
| `receiver_conciliation_id` | uuidv4 | Identificador de conciliação do QR Code               | 36                      |
| `url`                      | string | URL (Pix Copia e Cola) do QR Code                     | -                       |
| `image`                    | string | base64 da URL (Pix Copia e Cola) do QR Code           | -                       |

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 404                      | BKS000004            | Not Found | Pix key not found: `{pix_key}`                                               | Chave pix não encontrada: `{pix_key}`                                               |
| 403                      | BKS000005            | Forbidden                         | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404                      | BKS000006            | Not Found                                  | The source account key was not found.                                                                                | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                  | It was not possible to consult the source account at this time. Please try again in a few minutes.                                                                                      | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                                                                                    |
| 400                      | BKS000008            | Bad Request | The source account is closed.         |               A conta de origem está fechada.                                                                 |
| 400                      | BKS000009            | Bad Request | The source account is blocked.         |               A conta de origem está bloqueada.                                                                 |
| 403                      | BKS000010            | Forbidden                                 | The pix key owner does not match the account owner.                                                                                     | O proprietário da chave pix não corresponde ao proprietário da conta.                                                             |
| 404                      | BKS000013            | Not Found | Requester profile not found         |               Carteira não encontrada                                                                 |
| 409                      | BKS000014            | Conflict           | Request control key already sent or duplicated sent: `{request_control_key}`                                                              | Chave de controle da requisição já utilizada ou enviada duplicada: `{request_control_key}`                                                                        |
| 400                      | BKS000016            | Bad Request                                        | Expiration date must be greater than the current date and have a maximum of 3650 days from the current date.                                    | A data de vencimento deve ser maior que a data atual e possuir no máximo 3650 dias corridos a partir da data atual.                                     |
| 409                      | BKS000017            | Conflict                                        | Our number already used or duplicated sent: `{our_number}`                                                                                       | Nosso número já utilizado ou enviado duplicado: `{our_number}`                                                                               |
| 400                      | BKS000018            | Bad Request                                        | The discount dates must be less than the expiration date and increasing.                                                      | A data dos descontos devem ser menores que a de expiração e crescentes.                                               |
| 400                      | BKS000019            | Bad Request                                        | Payer address is required for protest.                                                                                       | Endereço do pagador é obrigatório para protesto.                                                                         |
| 500                      | BKS000021            | Internal Server Error                                  | Error while trying to generate QR Code.                                                               | Erro ao tentar gerar QR Code de pagamento.                                                           |
| 400                      | BKS000022            | Bad Request                                        | Requester profile is not opened.                                                              | Carteira não está aberta.                          |
| 400                      | BKS000023            | Bad Request             | The amount must be greater than zero.          | O valor deve ser maior que zero.                                                           |
| 400                      | BKS000024            | Bad Request             | Error while registering bank slip.          | Erro ao registrar boleto.                                                           |
| 400                      | BKS000026            | Bad Request                      | Guarantor address is required for protest.                                                                                        | Endereço do sacador é obrigatório para protesto.                                                                   |
| 404                      | BKS000028            | Not Found             | Notary office attended region not found for postal code: `{postal_code}`                                                          | Região de cartório não encontrada para o CEP: `{postal_code}`                                                                                 |
| 400                      | BKS000043            | Bad Request             | Invalid discount numbering. Discounts must be numbered in ascending order and start on 1.          | Numeração dos descontos inválida. Os descontos devem ser numerados em ordem crescente e começar em 1.                                                           |
| 400                      | BKS000045            | Bad Request                                        | Rebate amount can not be equal or greater than the bank slip amount.                                                              | O valor do rebate não pode ser igual ou maior do que o valor do boleto.                          |
| 400                      | BKS000047            | Bad Request             | It was not possible to consult the sent pix key at this time. Please try again in a few minutes.          | Não foi possível consultar a chave pix enviada no momento. Por favor, tente novamente em alguns minutos.                                                           |
| 400                      | BKS000125            | Bad Request             | Partial payment data is required for this bank slip species type.          | Os dados de pagamento parcial são obrigatórios para o tipo de boleto fornecido.                                                           |
| 400                      | BKS000128            | Bad Request             | QR code payment is not allowed for partial payment.          | Pagamento via QR code não é permitido para pagamento parcial.                                                           |
| 400                      | BKS000128            | Bad Request             | QR code payment is not allowed for partial payment.          | Pagamento via QR code não é permitido para pagamento parcial.                                                           |
| 400                      | BKS000131            | Bad Request             | Rebate amount is not allowed for this bank slip species type.          | O valor de abatimento não é permitido para o tipo de boleto fornecido.                                                           |
| 400                      | BKS000132            | Bad Request             | Discount data is not allowed for this bank slip species type.          | Os dados de desconto não são permitidos para o tipo de boleto fornecido.                                                           |
| 400                      | BKS000133            | Bad Request             | Fine data is not allowed for this bank slip species type.          | Os dados de multa não são permitidos para o tipo de boleto fornecido.                                                           |
| 400                      | BKS000134            | Bad Request             | Interest data is not allowed for this bank slip species type.          | Os dados de juros não são permitidos para o tipo de boleto fornecido.                                                           |
| 400                      | BKS000136            | Bad Request             | Only credit card financial instrument type can have zero amount.          | Apenas o tipo de instrumento financeiro cartão de crédito pode ter valor zero.                                                           |

---

# Emissão de boleto único (padrão)

URL: /documentation/boletos/emissao/emissao_boleto_unico_padrao

:::danger Importante
Para registrar bolePix, é necessário que exista uma chave Pix aleatória ativa na conta em que os boletos serão registrados.
:::

No fluxo padrão de registro de boleto, caso a requisição seja bem sucedida, a resposta retorna um boleto com o status `accepted` (o boleto foi aceito pela QI Tech). Após a confirmação/rejeição da Nuclea/CIP, o boleto passa para o status `registered` ou `rejected`.

:::caution Atenção!
Como trata-se de um registro assíncrono, o solicitante é notificado via [**webhook**](/documentation/boletos/v2/webhooks/boleto) assim que o boleto mudar de status de `accepted` para `registered` ou `rejected`.
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip
MÉTODO POST

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36         |

Request Body

```json
{
  "request_control_key": "0d496b4d-01f6-48cd-8ec9-9ead1e43f156",
  "our_number": 123456789,
  "document_number": "DOC4561237",
  "amount": 5000.00,
  "expiration": "2025-01-01",
  "bank_teller_instructions": "Confirm payment",
  "protest_data": {"days_to_protest": 7},
  "bankruptcy_protest_data": {"days_to_bankruptcy_protest": 14},
  "max_payment_days": 45,
  "fine_data": {"fine_type": "absolute", "fine_amount": 100.00, "days_to_fine": 10},
  "interest_data": {
    "interest_type": "workdays_daily_amount",
    "interest_amount": 10.00,
    "days_to_interest": 2,
  },
  "financial_instrument_type": "digital_commercial_invoice",
  "write_off_data": {"days_to_write_off": 365},
  "rebate_amount": 200.00,
  "discounts_data": [
    {
      "discount_amount": 50.00,
      "discount_number": 1,
      "discount_type": "absolute",
      "discount_limit_date": "2024-12-01",
    }
  ],
  "payer_data": {
    "name": "Global Tech",
    "contact": {
      "email": "finance@globaltech.com",
      "phone": {"country_code": "055", "area_code": "11", "number": "987654321"},
    },
    "address": {
      "street": "101 High St.",
      "neighborhood": "Tech Park",
      "number": "202",
      "postal_code": "01001000",
      "city": "Innovation City",
      "state": "SP",
      "complement": "Building A",
    },
    "document_number": "12345678000195",
    "person_type": "legal",
  },
  "guarantor_data": {
    "name": "Jane Doe",
    "contact": {
      "email": "jane.doe@qitech.com.br",
      "phone": {"country_code": "055", "area_code": "11", "number": "999999999"},
    },
    "address": {
      "street": "202 Elm St.",
      "neighborhood": "Quiet Neighborhood",
      "number": "303",
      "postal_code": "01001000",
      "city": "Peaceful Town",
      "state": "RJ",
      "complement": "House 1",
    },
    "document_number": "23456789012",
    "person_type": "natural",
  },
  "pix_key": "4d25d8fc-0074-42bb-b0a4-dd12b1cd0e98",
  "notification": {
    "document_number": "12345678000195",
    "name": "Global Tech",
    "email": "finance@globaltech.com",
    "phone": {"country_code": "055", "area_code": "11", "number": "987654321"},
    "send_2_way": true,
    "send_before_due_date": false,
    "send_after_due_date": false,
    "send_on_protest": false
  },
  "split_payment_data": {
    "beneficiary_settlement_percentage": 70,
    "split_payment_rules": [
      {
        "percentage": 20,
        "document_number": "12345678901",
        "account_owner_name": "João da Silva",
        "account_number": "1234567",
        "account_digit": "8"
      },
      {
        "percentage": 10,
        "document_number": "10987654321",
        "account_owner_name": "Maria Souza",
        "account_number": "7654321",
        "account_digit": "0"
      }
    ]
  }
}
```

### Request Body

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `request_control_key` *    | uuidv4  | Chave única de identificação da request utilizada pelo cliente no formato uuid v4  | 36                                                |
| `our_number`               | integer | Número único de identificação do boleto junto à carteira. Pode ser enviado pelo cliente e, caso não seja, a QI Tech irá gerar um                           | 11                                                |
| `document_number`          | string  | Número de identificação do boleto. Pode ser o número da nota fiscal eletrônica     | 10                                                |
| `participant_control_number` | string | Nº Controle do Participante                                                       |25                                                |
| `amount` *                 | float   | Valor base do boleto                                                               | -                                                 |
| `expiration` *             | string  | Data de vencimento                                                                 | 10                                                |
| `bank_teller_instructions` | string  | Observações ao pagador do boleto. Aceita no máximo 320 caracteres, distribuídos em até 7 linhas. Cada linha pode conter no máximo 90 caracteres. Caso uma linha ultrapasse 90 caracteres, o texto será automaticamente quebrado em uma nova linha | 320                                               |
| `rebate_amount`            | float   | Valor de abatimento do boleto, que será aplicado em cima do valor base             | -                                                 |
| `max_payment_days`         | integer | Máximo de dias corridos que o boleto ficará disponível para pagamento, após o vencimento (pode ser no máximo 365) | -          |
| `financial_instrument_type`   | string  | Tipo de espécie do boleto | **[Enumeradores financial_instrument_type](#enumeradores-financial_instrument_type)** |
| `partial_payment_data`    | object  | Configurações de pagamento parcial                      | **[Objeto partial_payment_data](#objeto-partial_payment_data)** |
| `write_off_data`       | object  | Configuração de baixa      | **[Objeto write_off_data](#objeto-write_off_settings)** |
| `protest_data`         | object  | Configuração de protesto       | **[Objeto protest_data](#objeto-protest_settings)** |
| `bankruptcy_protest_data` | object  | Configuração de protesto falimentar | **[Objeto bankruptcy_protest_data](#objeto-bankruptcy_protest_settings)** |
| `fine_data`            | object  | Configuração de multa                 | **[Objeto fine_data](#objeto-fine_settings)** |
| `interest_data`        | object  | Configuração de juros        | **[Objeto interest_data](#objeto-interest_settings)** |
| `discounts_data`           | object array | Descontos           | **[Objeto discount](#objeto-discounts_data)** |
| `payer_data` *             | object  | Dados do pagador                                                                   | **[Objeto payer_data](#objetos-payer_data-e-guarantor_data)** |
| `guarantor_data`           | object  | Dados do sacador avalista                                                          | **[Objeto guarantor_data](#objetos-payer_data-e-guarantor_data)** |
| `pix_key`                  | uuidv4  | Chave pix do tipo aleatória                                                        | 36                                                |
| `notification`             | object | Configurações de notificação do pagador                                             | **[Objeto notification](#objeto-notification)** |
| `split_payment_data`       | object | Configurações de rateio de crédito do boleto (split de pagamento)                   | **[Objeto split_payment_data](#objeto-split_payment_data)** |

:::info BolePix
Caso o parâmetro `pix_key`, opcional, seja enviado na request, será gerado um bolePix. BolePix é um boleto cujo pagamento é vinculado a um QR Code Pix. Sendo assim, o pagador pode realizar o pagamento do boleto tanto utilizando a linha digitável do mesmo, quanto através da leitura do QR Code Pix vinculado. Caso o pagamento seja feito via QR Code, a liquidação financeira se dá instantaneamente, enquanto os retornos bancários e webhooks envolvidos na liquidação serão gerados assim como é feito para um boleto comum.

Importante: para registrar um bolePix, é necessário que exista uma chave Pix aleatória ativa na conta em que boleto será registrado.
:::

:::tip Configurações Padrão da Carteira
Caso cada um dos campos `max_payment_days`, `write_off_data`, `protest_data`, `bankruptcy_protest_data`, `fine_data`, `interest_data` e `pix_key` não sejam enviados na request e a carteira possua configurações padrão (i.e. `max_payment_days`, `write_off_settings`, `protest_settings`, `bankruptcy_protest_settings`, `fine_settings`, `interest_settings` e `qr_code_settings`, respectivamente, no `configuration_data` do `requester_profile`), serão utilizadas tais configurações padrão para a emissão do título.
:::

:::caution Limitações e Restrições
- **Boletos de Pagamento Parcial:** Não é permitido o pagamento via QR Code Pix. Portanto, não é permitido enviar a `pix_key` no registro, nem ter uma configuração padrão de geração de bolePix para a carteira.

- **Boletos de Cartão de Crédito:** Não é necessário nem permitido enviar informações rebate, desconto, multa e juros. Isso se deve ao padrão do mercado, onde muitas Instituições Financeiras não aceitam o pagamento de boletos de cartão de crédito que contenham essas informações. A carteira também não pode ter essas configurações definidas como padrão. Sendo assim boletos desse tipo podem ser pagos parcialmente mesmo após o vencimento, sem incidência de juros, multas, descontos ou abatimentos na fatura corrente. Para aplicar esses valores é necessário incluí-los na próxima fatura, seja através da [ocorrência de edição de valor](/documentation/boletos/instrucoes/valor) do boleto ou emitindo um novo boleto que inclua esses valores. É possível enviar `amount = 0` para boletos deste tipo.

**Importante:** Boletos do tipo `credit_card` são obrigatoriamente de pagamento parcial, sendo assim é necessário fornecer as informações de `partial_payment_data` ou ter essa configuração padrão na carteira. Caso o campo `financial_instrument_type` não seja enviado, o valor padrão será `digital_commercial_invoice`.
:::

:::tip Recomendações de Carteiras
- **Carteira para Boletos Padrão:** Mantenha as configurações padrão para multas, juros e protesto
- **Carteira para Boletos de Pagamento Parcial:** Sem configuração de Pix e com regras específicas para pagamento parcial
- **Carteira para Boletos de Cartão de Crédito:** Sem configurações de multa, juros, desconto ou rebate

Criar carteiras específicas garante que as configurações padrão sejam adequadas para cada tipo de boleto e evita conflitos nas regras de negócio.
:::

:::info Máquina de Estados
A máquina de status para boletos de pagamento parcial possui algumas diferenças. Para mais detalhes, consulte a [introdução](/documentation/boletos/introducao) , onde há uma explicação sobre como aplicar a incidência de juros e multas no boleto seguindo as boas práticas do mercado.
:::

### Enumeradores financial_instrument_type

| Enumerador  | Descrição                        |
|-------------|----------------------------------|
| digital_commercial_invoice | DMI Duplicata Mercantil Indicação |
| credit_card | Cartão de Crédito |
| check | CH Cheque |
| digital_commercial | DM Duplicata Mercantil |
| digital_service_invoice | Duplicata de Serviço |
| digital_service_invoice_indication | DSI Duplicata de Serviço Indicação |
| digital_rural_invoice | DR Duplicata Rural |
| bill_of_exchange | LC Letra de Câmbio |
| commercial_credit_note | NCC Nota de Crédito Comercial |
| export_credit_note | NCE Nota de Crédito Exportação |
| industrial_credit_note | NCI Nota de Crédito Industrial |
| rural_credit_note | NCR Nota de Crédito Rural |
| promissory_note | NP Nota Promissória |
| rural_promissory_note | NPR Nota Promissória Rural |
| mercantile_triplicate | TM Triplicata Mercantil |
| service_triplicate | TS Triplicata de Serviço |
| insurance_note | NS Nota de Seguro |
| receipt | RC Recibo |
| printed_bank_slip | FAT Bloqueto |
| debit_note | ND Nota de Débito |
| insurance_policy | AP Apólice de Seguro |
| school_monthly_fee | ME Mensalidade Escolar |
| consortium_installment | PC Parcela de Consórcio |
| invoice | NF Nota Fiscal |
| debt_document | DD Documento de Dívida |
| rural_product_certificate | Cédula de Produto Rural |
| warrant | Warrant |
| state_active_debt | Dívida Ativa de Estado |
| municipal_active_debt | Dívida Ativa de Município |
| federal_active_debt | Dívida Ativa da União |
| condominium_charges | Encargos condominiais |
| proposal_bank_slip | Boleto proposta |
| deposit_and_contribution_bank_slip | Boleto de Depósito e Aporte |
| others | Outros |

### Objeto split_payment_data

Permite configurar o **rateio de crédito** (split de pagamento) do boleto, distribuindo o valor liquidado entre o beneficiário do boleto e até 10 contas adicionais. As contas dos rateados precisam estar abertas e cadastradas na QI Tech, e a soma dos percentuais (beneficiário + regras) deve ser exatamente 100.

| Campo                                  | Tipo         | Descrição                                                                                          | Caracteres |
|----------------------------------------|--------------|----------------------------------------------------------------------------------------------------|------------|
| `beneficiary_settlement_percentage` *  | float        | Percentual do valor liquidado destinado ao beneficiário do boleto. Aceita valor de 0 a 100         | -          |
| `beneficiary_max_amount`               | float        | Valor máximo que o beneficiário recebe na liquidação. Quando o valor pago exceder este limite, o excedente é direcionado integralmente para a primeira regra do array `split_payment_rules`. Aceita valor maior que 0 e menor ou igual ao valor do boleto | - |
| `split_payment_rules` *                | object array | Lista de regras de rateio. Mínimo 1, máximo 10 regras                                              | **[Objeto split_payment_rule](#objeto-split_payment_rule)** |

#### Objeto split_payment_rule

| Campo                  | Tipo    | Descrição                                                                                | Caracteres |
|------------------------|---------|------------------------------------------------------------------------------------------|------------|
| `percentage` *         | float   | Percentual do valor liquidado destinado a esta conta. Aceita valor de 0 a 100. Use `0` quando esta regra for destinada exclusivamente a receber o excedente do `beneficiary_max_amount` | - |
| `document_number` *    | string  | CPF/CNPJ do titular da conta destino                                                     | 11 ou 14   |
| `account_owner_name` * | string  | Nome do titular da conta destino                                                         | 100        |
| `account_number` *     | string  | Número da conta destino                                                                  | 20         |
| `account_digit` *      | string  | Dígito verificador da conta destino                                                      | 2          |

:::caution Atenção!
- A soma de `beneficiary_settlement_percentage` com os percentuais de cada item de `split_payment_rules` deve ser exatamente igual a **100**.
- O `document_number` deve ser único entre as regras e diferente do beneficiário.
- O rateio é aplicado em todos os fluxos de liquidação do boleto (SILOC, STR, cartório e Pix QR Code).
- `beneficiary_max_amount`, quando enviado, deve ser maior que 0 e menor ou igual ao valor do boleto. É obrigatório sempre que alguma regra tiver `percentage = 0`.
- Apenas **uma** regra pode ter `percentage = 0` por boleto (a destinatária do excedente).
- Após a emissão, é possível atualizar o rateio com a [**ocorrência de atualização de rateio de crédito**](/documentation/boletos/instrucoes/rateio_de_credito), desde que o boleto esteja com o status `registered` e ainda não tenha sido pago.
:::

:::tip Caso de uso: receber juros/multa em conta separada
Para que o beneficiário receba sempre o valor de face do boleto e uma conta diferente receba os juros/multa em casos de atraso, configure `beneficiary_settlement_percentage = 100` + `beneficiary_max_amount = ` + uma única regra com `percentage = 0` apontando para a conta destino do excedente. Veja o passo a passo completo em [**Atualização de Rateio de Crédito**](/documentation/boletos/instrucoes/rateio_de_credito#caso-de-uso-receber-juros-e-multa-em-uma-conta-separada).
:::

### Objeto partial_payment_data

| Campo                             | Tipo    | Descrição                                                                 | Caracteres |
|-----------------------------------|---------|---------------------------------------------------------------------------|------------|
| `partial_payment_minimum_type` *  | string  | Tipo de valor mínimo para pagamento parcial                               | **[Enumeradores partial_payment_type](#enumeradores-partial_payment_type)** |
| `partial_payment_minimum_percentage` | float | Percentual mínimo permitido para o pagamento parcial                      | -          |
| `partial_payment_minimum_amount`  | float  | Valor mínimo permitido para o pagamento parcial                           | -          |
| `partial_payment_maximum_type`    | string  | Tipo de valor máximo para pagamento parcial                               | **[Enumeradores partial_payment_type](#enumeradores-partial_payment_type)** |
| `partial_payment_maximum_percentage` | float | Percentual máximo permitido para o pagamento parcial                      | -          |
| `partial_payment_maximum_amount`  | float  | Valor máximo permitido para o pagamento parcial                           | -          |
| `partial_payment_quantity` *      | integer | Quantidade de pagamentos parciais permitidos                              | -          |

:::caution Atenção!
De acordo com o valor enviado nos campos `partial_payment_minimum_type` e `partial_payment_maximum_type`, é necessário enviar o `partial_payment_minimum_amount` ou `partial_payment_minimum_percentage`, e o `partial_payment_maximum_amount` ou `partial_payment_maximum_percentage` correspondente.
:::

### Enumeradores partial_payment_type

| Enumerador  | Descrição                        |
|-------------|----------------------------------|
| absolute    | Valor absoluto                   |
| percentage  | Percentual                       |

### Objeto write_off_data

| Campo                     | Tipo    | Descrição                                                                   | Caracteres |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_write_off` *     | integer | Dias, após o vencimento, para que o boleto seja baixado automaticamente     | -          |

### Objeto protest_data

| Campo                     | Tipo    | Descrição                                                                   | Caracteres |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_protest` *       | integer | Dias, após o vencimento, para que o boleto seja protestado automaticamente  | -          |

### Objeto bankruptcy_protest_data

| Campo                          | Tipo    | Descrição                                                                   | Caracteres  |
|--------------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_bankruptcy_protest` * | integer | Dias, após o vencimento, para que o boleto seja protestado automaticamente  | -           |

### Objeto fine_data

Opção 1: multa em valor absoluto (`fine_type=absolute`)

| Campo                     | Tipo    | Descrição                                               | Caracteres                |
|---------------------------|---------|---------------------------------------------------------|-------------------------------------------------------------------------|
| `fine_type` *             | string  | Tipo da multa                                                       | **[Enumeradores fine_type](#enumeradores-fine_type)**                                              |
| `fine_amount` *           | float   | Valor absoluto da multa                                             | -                                                                        |
| `days_to_fine` *          | integer | Dias, após o vencimento, para que a multa seja cobrada              | -                                                                        |

Opção 2: multa em valor percentual (`fine_type=percentage`)

| Campo                     | Tipo    | Descrição                                                 | Caracteres                             |
|---------------------------|---------|-----------------------------------------------------------|---------------------------------------|
| `fine_type` *             | string  | Tipo da multa                                             | **[Enumeradores fine_type](#enumeradores-fine_type)** |
| `fine_percentage` *       | integer | Valor percentual da multa, de 1 a 100                     | -                                      |
| `days_to_fine` *          | integer | Dias, após o vencimento, para que a multa seja cobrada    | -                                      |

### Enumeradores fine_type

| Enumerador         | Descrição             |
|--------------------|-----------------------|
| absolute           | valor absoluto        |
| percentage         | valor percentual      |

### Objeto interest_data

Opção 1: juros utilizando valores absolutos (`interest_type=calendar_days_daily_amount` ou `interest_type=workdays_daily_amount`)

| Campo                     | Tipo    | Descrição                                                                     | Caracteres                                                                                      |
|---------------------------|---------|-------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| `interest_type` *         | string  | Tipo de juros       | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_amount` *       | float   | Valor a ser cobrado por unidade de tempo determinada (dias úteis ou corridos) | -                                                                                               |
| `days_to_interest` *      | integer | Dias, após o vencimento, para que comece a cobrar os juros                    | -                                                                                               |

Opção 2: juros utilizando valores percentuais (`interest_type=calendar_days_monthly_percentage`)

| Campo                    | Tipo    | Descrição                                                                             | Caracteres                                                                                          |
|--------------------------|---------|---------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
| `interest_type` *        | string  | Tipo de juros       | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_percentage` *  | integer | Porcentagem a ser cobrada por unidade de tempo determinada (dias úteis ou corridos)                                                                      | -                                                                           |
| `days_to_interest` *     | integer | Dias, após o vencimento, para que comece a cobrar os juros                             | -                                                                                                   |

### Enumeradores interest_type

| Enumerador                       | Descrição                                                            |
|----------------------------------|----------------------------------------------------------------------|
| calendar_days_daily_amount       | Valor diário sobre dias corridos                                     |
| workdays_daily_amount            | Valor diário sobre dias úteis                                        |
| calendar_days_monthly_percentage | Porcentagem de juros cobrados mensalmente, com base em dias corridos |

### Objeto discount

Opção 1: descontos utilizando valores absolutos (`discount_type in ["absolute", "anticipation_calendar_days_daily_amount", "anticipation_workdays_daily_amount"]`)

| Campo                     | Tipo    | Descrição                                           | Caracteres                                                |
|---------------------------|---------|-----------------------------------------------------|-----------------------------------------------------------|
| `discount_amount` *       | float   | Valor absoluto de desconto por unidade de tempo                                            | -                                                          |
| `discount_number` *       | integer | Número do desconto                                     | -                                                         |
| `discount_type` *         | string  | Configuração do desconto em valores absolutos                                    | **[Enumerador discount_type](#enumeradores-discount_type)** |                                                       |
| `discount_limit_date` *   | string  | Data limite para aplicação do desconto   | 10                                                        |

Opção 2: descontos utilizando valores percentuais (`discount_type in ["percentage", "anticipation_calendar_days_daily_percentage", "anticipation_workdays_daily_percentage"]`)

| Campo                     | Tipo    | Descrição                                           | Caracteres                                                |
|---------------------------|---------|-----------------------------------------------------|-----------------------------------------------------------|
| `discount_percentage` *   | float   | Valor percentual de desconto por unidade de tempo                                            | -                                                          |
| `discount_number` *       | integer | Número do desconto                                     | -                                                         |
| `discount_type` *         | string  | Configuração do desconto em valores percentuais                                    | **[Enumerador discount_type](#enumeradores-discount_type)** |                                                       |
| `discount_limit_date` *   | string  | Data limite para aplicação do desconto   | 10                                                        |

:::caution Atenção!
O boleto pode ter até três descontos, sendo que os descontos devem ser todos do mesmo tipo , isto é, devem ter o mesmo `discount_type`. Os descontos devem ser numerados de 1 a 3, de maneira crescente e começando necessariamente em 1. Ou seja, caso sejam enviados dois descontos na requisição, devem necessariamente ser numerados com 1 e 2.
:::

### Enumeradores discount_type

| Enumerador                                  | Descrição                                                                |
|---------------------------------------------|--------------------------------------------------------------------------|
| absolute                                    | Valor fixo                                                               |
| anticipation_calendar_days_daily_amount     | Valor diário de desconto de antecipação, sobre dias corridos             |
| anticipation_workdays_daily_amount          | Valor diário de desconto de antecipação, sobre dias úteis                |
| percentage                                  | Porcentagem fixa                                                         |
| anticipation_calendar_days_daily_percentage | Porcentagem mensal de desconto de antecipação, com base em dias corridos |
| anticipation_workdays_daily_percentage      | Porcentagem anual de desconto de antecipação, com base em dias úteis     |

### Objetos payer_data e guarantor_data

| Campo                     | Tipo   | Descrição                                                  | Caracteres|
|---------------------------|--------|-------------------------------------|-----------------------------------------------------------|
| `name` *                  | string | Nome completo                       | 100                                                       |
| `document_number` *       | string | Número do documento (CPF/CNPJ)      | 11 ou 14                                                  |
| `person_type` *           | string | Tipo da pessoa (física ou jurídica) | **[Enumeradores person_type](#enumeradores-person_type)** |
| `contact`                 | object | Informações de contato              | **[Objeto contact](#objeto-contact)**                     |
| `address`                 | object | Endereço                            | **[Objeto address](#objeto-address)**                     |

### Enumeradores person_type

| Enumerador         | Descrição             |
|--------------------|-----------------------|
| natural            | pessoa física         |
| legal              | pessoa jurídica       |

### Objeto contact

| Campo                     | Tipo   | Descrição                         | Caracteres                         |
|---------------------------|--------|-----------------------------------|------------------------------------|
| `email`                   | string | E-mail de contato                 | 320                                |
| `phone`                   | object | Telefone de contato               | **[Objeto phone](#objeto-phone)**  |

### Objeto phone

| Campo                           | Tipo   | Descrição                                    | Caracteres |
|---------------------------------|--------|----------------------------------------------|------------|
| `country_code` *     | string | Código DDI (Discagem Direta Internacional)   | 3          |
| `area_code` *                   | string | Código DDD (Discagem Direta à Distância)     | 2          |
| `number` *                      | string | Complemento                                  | 9          |

### Objeto address

| Campo                     | Tipo   | Descrição                                    | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `street` *                | string | Logradouro                                   | 500        |
| `number` *                | string | Número                                       | 6          |
| `complement`              | string | Complemento                                  | 500        |
| `neighborhood` *          | string | Bairro                                       | 100        |
| `postal_code` *           | string | CEP                                          | 8          |
| `city` *                  | string | Cidade                                       | 100        |
| `state` *                 | string | Estado (UF) | **[Enumerador state](#enumeradores-state)** |

### Enumeradores state

| Enumerador         | Descrição             |
|--------------------|-----------------------|
| AC                 | Acre                  |
| AL                 | Alagoas               |
| AM                 | Amazonas              |
| AP                 | Amapá                 |
| BA                 | Bahia                 |
| CE                 | Ceará                 |
| DF                 | Distrito federal      |
| ES                 | Espírito Santo        |
| GO                 | Goiás                 |
| MA                 | Maranhão              |
| MG                 | Minas Gerais          |
| MS                 | Mato Grosso do Sul    |
| MT                 | Mato Grosso           |
| PA                 | Pará                  |
| PB                 | Paraíba               |
| PE                 | Pernambuco            |
| PI                 | Piauí                 |
| PR                 | Paraná                |
| RJ                 | Rio de Janeiro        |
| RN                 | Rio Grande do Norte   |
| RO                 | Rondônia              |
| RR                 | Roraima               |
| RS                 | Rio Grande do Sul     |
| SC                 | Santa Catarina        |
| SE                 | Sergipe               |
| SP                 | São Paulo             |
| TO                 | Tocantins             |
| EX                 | Exceção               |

### Objeto notification

| Campo                     | Tipo    | Descrição                                                                               | Caracteres |
|---------------------------|---------|-----------------------------------------------------------------------------------------|------------|
| `document_number` *       | string  | Número do documento de quem receberá as notificações (CPF/CNPJ)                         | 11 ou 14   |
| `name` *                  | string  | Nome de quem receberá as notificações                                                   | 100        |
| `email`                   | string  | E-mail para o qual serão enviadas as notificações                                       | 320        |
| `phone`                   | object  | Telefone de contato para o qual serão enviadas as notificações | **[Objeto phone](#objeto-phone)**   |
| `send_2_way` *            | boolean | Enviar segunda via                                                                      | -          |
| `send_before_due_date` *  | boolean | Enviar notificação ao pagador antes da data de vencimento                               | -          |
| `send_after_due_date` *   | boolean | Enviar notificação ao pagador quando o boleto vencer                                    | -          |
| `send_on_protest` *       | boolean | Enviar notificação ao entrar em fluxo de protesto                                       | -          |

## Response

STATUS 202

Response Body

```json
{
  "request_control_key": "0d496b4d-01f6-48cd-8ec9-9ead1e43f156",
  "bank_slip_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "bank_slip_status": "accepted",
  "our_number": 67215548222,
  "barcode": "32995995900000892811606496721554822228569790",
  "digitable_line": "32991606429672155482022285697904599590000089281",
  "qr_code_data": {
    "qr_code_key": "a92b180a-4aa5-47c2-8a71-4e7bbb074410",
    "pix_key": "4d25d8fc-0074-42bb-b0a4-dd12b1cd0e98",
    "receiver_conciliation_id": "01GVGV9NXBCY287Z6CJ4S0ENW9",
    "url": "00020126830014br.gov.bcb.pix2561qrcode.qitech.app/bacen/cobv/58fd5103a8e64bbbab2fd49b0bd580145204000053039865802BR5925GONNFUNDODEINVESTIMENTOEM6012RiodeJaneiro6107226401262070503***6304EA0D",
    "image": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAALCAD0APQBAREA/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/9oACAEBAAA/APf6KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK+QPhl8Mv+Fjf2p/xN/wCz/sHlf8u3m79+/wD21xjZ79a7/wD4Zl/6m7/ym/8A22j/AIZl/wCpu/8AKb/9to/Zl/5mn/t0/wDa1egfE34Zf8LG/sv/AIm/9n/YPN/5dvN379n+2uMbPfrXgHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrR8Tfib/wsb+y/wDiUf2f9g83/l583fv2f7C4xs9+td//AMm5/wDUw/27/wBunkeR/wB/N27zvbG3vnjwCvr/AOJvxN/4Vz/Zf/Eo/tD7f5v/AC8+Vs2bP9hs53+3SvkCvf8A9mX/AJmn/t0/9rUf8m5/9TD/AG7/ANunkeR/383bvO9sbe+ePQPhl8Mv+Fc/2p/xN/7Q+3+V/wAu3lbNm/8A22znf7dK8A+GXxN/4Vz/AGp/xKP7Q+3+V/y8+Vs2b/8AYbOd/t0o+GXxN/4Vz/an/Eo/tD7f5X/Lz5WzZv8A9hs53+3Svf8A4m/DL/hY39l/8Tf+z/sHm/8ALt5u/fs/21xjZ79a8/8A+GZf+pu/8pv/ANtr0D4ZfE3/AIWN/an/ABKP7P8AsHlf8vPm79+//YXGNnv1rwD4ZfE3/hXP9qf8Sj+0Pt/lf8vPlbNm/wD2Gznf7dK7/wD4aa/6lH/ypf8A2quA+GXxN/4Vz/an/Eo/tD7f5X/Lz5WzZv8A9hs53+3Svr+vkD4ZfDL/AIWN/an/ABN/7P8AsHlf8u3m79+//bXGNnv1rv8A/hmX/qbv/Kb/APbaP+GZf+pu/wDKb/8AbaP2Zf8Amaf+3T/2tX0BRRRXz/8Asy/8zT/26f8AtavAK9//AGZf+Zp/7dP/AGtR+zL/AMzT/wBun/tavQPib8Mv+Fjf2X/xN/7P+web/wAu3m79+z/bXGNnv1rz/wDZl/5mn/t0/wDa1cB8Mvib/wAK5/tT/iUf2h9v8r/l58rZs3/7DZzv9ule/wDwy+Jv/Cxv7U/4lH9n/YPK/wCXnzd+/f8A7C4xs9+teAfE34Zf8K5/sv8A4m/9ofb/ADf+XbytmzZ/ttnO/wBule//ABN+Jv8Awrn+y/8AiUf2h9v83/l58rZs2f7DZzv9uleAfDL4Zf8ACxv7U/4m/wDZ/wBg8r/l283fv3/7a4xs9+tHxN+GX/Cuf7L/AOJv/aH2/wA3/l28rZs2f7bZzv8AbpXv/wAMvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9ulef/tNf8yt/29/+0a9A+GXxN/4WN/an/Eo/s/7B5X/Lz5u/fv8A9hcY2e/WvP8A/k3P/qYf7d/7dPI8j/v5u3ed7Y2988cB8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpXf/APDTX/Uo/wDlS/8AtVcB8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpX1/Xz//AMm5/wDUw/27/wBunkeR/wB/N27zvbG3vng/5OM/6l7+wv8At78/z/8Av3t2+T753dsc+gfDL4m/8LG/tT/iUf2f9g8r/l583fv3/wCwuMbPfrXn/wCzL/zNP/bp/wC1q8Ar3/8AZl/5mn/t0/8Aa1H7Mv8AzNP/AG6f+1q+gKKKK+f/ANmX/maf+3T/ANrUf8My/wDU3f8AlN/+216B8Mvhl/wrn+1P+Jv/AGh9v8r/AJdvK2bN/wDttnO/26V5/wDsy/8AM0/9un/taj/k4z/qXv7C/wC3vz/P/wC/e3b5Pvnd2xyf8nGf9S9/YX/b35/n/wDfvbt8n3zu7Y5P2mv+ZW/7e/8A2jR+zL/zNP8A26f+1qP+Tc/+ph/t3/t08jyP+/m7d53tjb3zx4BXv/7TX/Mrf9vf/tGj/k3P/qYf7d/7dPI8j/v5u3ed7Y2988cB8Mvhl/wsb+1P+Jv/AGf9g8r/AJdvN379/wDtrjGz3613/wDwzL/1N3/lN/8AttH7Mv8AzNP/AG6f+1q4D4m/DL/hXP8AZf8AxN/7Q+3+b/y7eVs2bP8AbbOd/t0rv/8Ahpr/AKlH/wAqX/2qj/k4z/qXv7C/7e/P8/8A797dvk++d3bHJ/ybn/1MP9u/9unkeR/383bvO9sbe+ePQPhl8Mv+Fc/2p/xN/wC0Pt/lf8u3lbNm/wD22znf7dKPib8Mv+Fjf2X/AMTf+z/sHm/8u3m79+z/AG1xjZ79a8//AGZf+Zp/7dP/AGtX0BXz/wDsy/8AM0/9un/taj/hmX/qbv8Aym//AG2vQPhl8Mv+Fc/2p/xN/wC0Pt/lf8u3lbNm/wD22znf7dK8/wD2Zf8Amaf+3T/2tX0BRRRXz/8A8My/9Td/5Tf/ALbR/wAMy/8AU3f+U3/7bR/wzL/1N3/lN/8AttegfDL4Zf8ACuf7U/4m/wDaH2/yv+Xbytmzf/ttnO/26V5//wAm5/8AUw/27/26eR5H/fzdu872xt7549A+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0rz/9mX/maf8At0/9rVwHwy+Jv/Cuf7U/4lH9ofb/ACv+Xnytmzf/ALDZzv8AbpR8Mvib/wAK5/tT/iUf2h9v8r/l58rZs3/7DZzv9ulHwy+Jv/Cuf7U/4lH9ofb/ACv+Xnytmzf/ALDZzv8AbpXf/sy/8zT/ANun/tavQPhl8Mv+Fc/2p/xN/wC0Pt/lf8u3lbNm/wD22znf7dK8/wD2Zf8Amaf+3T/2tXoHwy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpXgHwy+Jv8Awrn+1P8AiUf2h9v8r/l58rZs3/7DZzv9uld/+zL/AMzT/wBun/tavQPhl8Mv+Fc/2p/xN/7Q+3+V/wAu3lbNm/8A22znf7dK8A+GXxN/4Vz/AGp/xKP7Q+3+V/y8+Vs2b/8AYbOd/t0o+GXxN/4Vz/an/Eo/tD7f5X/Lz5WzZv8A9hs53+3Su/8A2Zf+Zp/7dP8A2tR/ybn/ANTD/bv/AG6eR5H/AH83bvO9sbe+eD9mX/maf+3T/wBrUfsy/wDM0/8Abp/7Wo/4Zl/6m7/ym/8A22j/AIZl/wCpu/8AKb/9to/4Zl/6m7/ym/8A22vQPhl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK9Aooor5/8A2Zf+Zp/7dP8A2tXAfE34m/8ACxv7L/4lH9n/AGDzf+Xnzd+/Z/sLjGz360fE34m/8LG/sv8A4lH9n/YPN/5efN379n+wuMbPfrXv/wAMvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9ulfIFFegfDL4m/8ACuf7U/4lH9ofb/K/5efK2bN/+w2c7/bpXf8A7TX/ADK3/b3/AO0a9A+GXxN/4WN/an/Eo/s/7B5X/Lz5u/fv/wBhcY2e/WvAPib8Mv8AhXP9l/8AE3/tD7f5v/Lt5WzZs/22znf7dKPib8Mv+Fc/2X/xN/7Q+3+b/wAu3lbNmz/bbOd/t0rv/wBmX/maf+3T/wBrVwHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9ulHxN+GX/Cuf7L/wCJv/aH2/zf+XbytmzZ/ttnO/26V3//AAzL/wBTd/5Tf/ttH7TX/Mrf9vf/ALRrgPhl8Tf+Fc/2p/xKP7Q+3+V/y8+Vs2b/APYbOd/t0o+Jvwy/4Vz/AGX/AMTf+0Pt/m/8u3lbNmz/AG2znf7dK7//AJOM/wCpe/sL/t78/wA//v3t2+T753dscn/Juf8A1MP9u/8Abp5Hkf8Afzdu872xt7548Ar3/wD5Nz/6mH+3f+3TyPI/7+bt3ne2NvfPHAfE34Zf8K5/sv8A4m/9ofb/ADf+XbytmzZ/ttnO/wBuld/+01/zK3/b3/7Rr6Aorz/4ZfE3/hY39qf8Sj+z/sHlf8vPm79+/wD2FxjZ79a9Aooor5A+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0o+JvxN/4WN/Zf/Eo/s/7B5v/AC8+bv37P9hcY2e/Wu//AGmv+ZW/7e//AGjXoHwy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulHwy+Jv/Cxv7U/4lH9n/YPK/5efN379/8AsLjGz3615/8A8nGf9S9/YX/b35/n/wDfvbt8n3zu7Y5+gK+QPib8Tf8AhY39l/8AEo/s/wCweb/y8+bv37P9hcY2e/Wvf/hl8Tf+Fjf2p/xKP7P+weV/y8+bv37/APYXGNnv1rz/AP4aa/6lH/ypf/aq9A+Jvwy/4WN/Zf8AxN/7P+web/y7ebv37P8AbXGNnv1r0CvkD4m/DL/hXP8AZf8AxN/7Q+3+b/y7eVs2bP8AbbOd/t0rv/8Ahpr/AKlH/wAqX/2qj/hmX/qbv/Kb/wDbaP8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPHoHxN+Jv8Awrn+y/8AiUf2h9v83/l58rZs2f7DZzv9ulHwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpXn/AO01/wAyt/29/wDtGj/hpr/qUf8Aypf/AGqj/k4z/qXv7C/7e/P8/wD797dvk++d3bHJ/wANNf8AUo/+VL/7VXAfE34Zf8K5/sv/AIm/9ofb/N/5dvK2bNn+22c7/bpR8Mvib/wrn+1P+JR/aH2/yv8Al58rZs3/AOw2c7/bpR8Mvhl/wsb+1P8Aib/2f9g8r/l283fv3/7a4xs9+tHwy+Jv/Cuf7U/4lH9ofb/K/wCXnytmzf8A7DZzv9ulfX9FFFFfP/8AwzL/ANTd/wCU3/7bXoHwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpXgHwy+GX/Cxv7U/4m/9n/YPK/5dvN379/8AtrjGz3613/8AwzL/ANTd/wCU3/7bR/w01/1KP/lS/wDtVegfDL4Zf8K5/tT/AIm/9ofb/K/5dvK2bN/+22c7/bpR8Mvib/wsb+1P+JR/Z/2Dyv8Al583fv3/AOwuMbPfrR8Mvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9uleAfE34Zf8ACuf7L/4m/wDaH2/zf+XbytmzZ/ttnO/26V3/AO01/wAyt/29/wDtGuA+GXwy/wCFjf2p/wATf+z/ALB5X/Lt5u/fv/21xjZ79a9/+Jvwy/4WN/Zf/E3/ALP+web/AMu3m79+z/bXGNnv1rwD4m/DL/hXP9l/8Tf+0Pt/m/8ALt5WzZs/22znf7dK9/8Aib8Tf+Fc/wBl/wDEo/tD7f5v/Lz5WzZs/wBhs53+3SvP/wBpr/mVv+3v/wBo0f8AJuf/AFMP9u/9unkeR/383bvO9sbe+eD9mX/maf8At0/9rV4BXoHwy+Jv/Cuf7U/4lH9ofb/K/wCXnytmzf8A7DZzv9uld/8A8m5/9TD/AG7/ANunkeR/383bvO9sbe+eOA+GXxN/4Vz/AGp/xKP7Q+3+V/y8+Vs2b/8AYbOd/t0rv/8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPHoHxN+GX/Cxv7L/wCJv/Z/2Dzf+Xbzd+/Z/trjGz3614B8Mvib/wAK5/tT/iUf2h9v8r/l58rZs3/7DZzv9ule/wDxN+Jv/Cuf7L/4lH9ofb/N/wCXnytmzZ/sNnO/26UfE34m/wDCuf7L/wCJR/aH2/zf+XnytmzZ/sNnO/26V5/+zL/zNP8A26f+1q+gKKKK+f8A/k3P/qYf7d/7dPI8j/v5u3ed7Y2988H/ACbn/wBTD/bv/bp5Hkf9/N27zvbG3vnjgPib8Mv+Fc/2X/xN/wC0Pt/m/wDLt5WzZs/22znf7dK9/wDhl8Mv+Fc/2p/xN/7Q+3+V/wAu3lbNm/8A22znf7dKPib8Mv8AhY39l/8AE3/s/wCweb/y7ebv37P9tcY2e/WvAPib8Mv+Fc/2X/xN/wC0Pt/m/wDLt5WzZs/22znf7dK8/r3/APaa/wCZW/7e/wD2jXAfDL4m/wDCuf7U/wCJR/aH2/yv+Xnytmzf/sNnO/26V7/8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXn//AA01/wBSj/5Uv/tVegfE34m/8K5/sv8A4lH9ofb/ADf+XnytmzZ/sNnO/wBulHxN+Jv/AArn+y/+JR/aH2/zf+XnytmzZ/sNnO/26V5/+01/zK3/AG9/+0aP2Zf+Zp/7dP8A2tR+zL/zNP8A26f+1qP+TjP+pe/sL/t78/z/APv3t2+T753dsc+AV7/+zL/zNP8A26f+1q9A+GXwy/4Vz/an/E3/ALQ+3+V/y7eVs2b/APbbOd/t0rwD4ZfDL/hY39qf8Tf+z/sHlf8ALt5u/fv/ANtcY2e/Wvf/AIm/E3/hXP8AZf8AxKP7Q+3+b/y8+Vs2bP8AYbOd/t0rwD4m/DL/AIVz/Zf/ABN/7Q+3+b/y7eVs2bP9ts53+3Su/wD2mv8AmVv+3v8A9o1wHwy+Jv8Awrn+1P8AiUf2h9v8r/l58rZs3/7DZzv9ulHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9ule/8Awy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpXoFFFFfIHwy+GX/Cxv7U/4m/8AZ/2Dyv8Al283fv3/AO2uMbPfrXf/APDMv/U3f+U3/wC20f8AJxn/AFL39hf9vfn+f/3727fJ987u2OfQPhl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK8//wCGmv8AqUf/ACpf/aq8Ar3/AP4aa/6lH/ypf/aq9A+GXwy/4Vz/AGp/xN/7Q+3+V/y7eVs2b/8AbbOd/t0rwD4m/DL/AIVz/Zf/ABN/7Q+3+b/y7eVs2bP9ts53+3Svf/ib8Mv+Fjf2X/xN/wCz/sHm/wDLt5u/fs/21xjZ79a8/wD+TjP+pe/sL/t78/z/APv3t2+T753dsc+gfDL4m/8ACxv7U/4lH9n/AGDyv+Xnzd+/f/sLjGz360fDL4Zf8K5/tT/ib/2h9v8AK/5dvK2bN/8AttnO/wBulef/APJxn/Uvf2F/29+f5/8A3727fJ987u2OT/hpr/qUf/Kl/wDaqP2mv+ZW/wC3v/2jR+zL/wAzT/26f+1q8Ar3/wD4Zl/6m7/ym/8A22vQPhl8Tf8AhY39qf8AEo/s/wCweV/y8+bv37/9hcY2e/Wj4m/E3/hXP9l/8Sj+0Pt/m/8ALz5WzZs/2Gznf7dKPib8Mv8AhY39l/8AE3/s/wCweb/y7ebv37P9tcY2e/Wj4ZfE3/hY39qf8Sj+z/sHlf8ALz5u/fv/ANhcY2e/Wj4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3SvQK+f/wDk4z/qXv7C/wC3vz/P/wC/e3b5Pvnd2xz9AUUUUV5/8Mvhl/wrn+1P+Jv/AGh9v8r/AJdvK2bN/wDttnO/26V5/wD8m5/9TD/bv/bp5Hkf9/N27zvbG3vnjwCvQPib8Mv+Fc/2X/xN/wC0Pt/m/wDLt5WzZs/22znf7dK7/wD5Nz/6mH+3f+3TyPI/7+bt3ne2NvfPHAfDL4m/8K5/tT/iUf2h9v8AK/5efK2bN/8AsNnO/wBulHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrXf8A7TX/ADK3/b3/AO0a4D4m/DL/AIVz/Zf/ABN/7Q+3+b/y7eVs2bP9ts53+3Sj4ZfDL/hY39qf8Tf+z/sHlf8ALt5u/fv/ANtcY2e/Wu//AGmv+ZW/7e//AGjXoHxN+GX/AAsb+y/+Jv8A2f8AYPN/5dvN379n+2uMbPfrXoFfIHwy+Jv/AArn+1P+JR/aH2/yv+Xnytmzf/sNnO/26UfDL4Zf8LG/tT/ib/2f9g8r/l283fv3/wC2uMbPfrXf/wDDTX/Uo/8AlS/+1Ufsy/8AM0/9un/tavAK9A+GXwy/4WN/an/E3/s/7B5X/Lt5u/fv/wBtcY2e/Wu//wCGmv8AqUf/ACpf/aq4D4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Su//wCTjP8AqXv7C/7e/P8AP/797dvk++d3bHPoHxN+Jv8Awrn+y/8AiUf2h9v83/l58rZs2f7DZzv9ulHxN+Jv/Cuf7L/4lH9ofb/N/wCXnytmzZ/sNnO/26UfDL4m/wDCxv7U/wCJR/Z/2Dyv+Xnzd+/f/sLjGz360fE34m/8K5/sv/iUf2h9v83/AJefK2bNn+w2c7/bpR8Mvib/AMLG/tT/AIlH9n/YPK/5efN379/+wuMbPfrXoFFFFfIHwy+Jv/Cuf7U/4lH9ofb/ACv+Xnytmzf/ALDZzv8AbpX1/XwBXoHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9ule/8Awy+Jv/Cxv7U/4lH9n/YPK/5efN379/8AsLjGz360fE34m/8ACuf7L/4lH9ofb/N/5efK2bNn+w2c7/bpR8Mvhl/wrn+1P+Jv/aH2/wAr/l28rZs3/wC22c7/AG6V5/8Asy/8zT/26f8AtauA+JvxN/4WN/Zf/Eo/s/7B5v8Ay8+bv37P9hcY2e/Wvf8A4m/E3/hXP9l/8Sj+0Pt/m/8ALz5WzZs/2Gznf7dK8A+JvxN/4WN/Zf8AxKP7P+web/y8+bv37P8AYXGNnv1r3/4m/E3/AIVz/Zf/ABKP7Q+3+b/y8+Vs2bP9hs53+3SvP/8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPB/w01/1KP/AJUv/tVegfE34m/8K5/sv/iUf2h9v83/AJefK2bNn+w2c7/bpXn/AO01/wAyt/29/wDtGj/hpr/qUf8Aypf/AGqvoCvkD4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Svf/ib8Tf8AhXP9l/8AEo/tD7f5v/Lz5WzZs/2Gznf7dK8//wCGZf8Aqbv/ACm//baP2mv+ZW/7e/8A2jR/ybn/ANTD/bv/AG6eR5H/AH83bvO9sbe+ePQPib8Tf+Fc/wBl/wDEo/tD7f5v/Lz5WzZs/wBhs53+3SvAPhl8Tf8AhXP9qf8AEo/tD7f5X/Lz5WzZv/2Gznf7dK9/+GXxN/4WN/an/Eo/s/7B5X/Lz5u/fv8A9hcY2e/Wj4ZfE3/hY39qf8Sj+z/sHlf8vPm79+//AGFxjZ79a9Aoooor5/8A2Zf+Zp/7dP8A2tR/wzL/ANTd/wCU3/7bR/ybn/1MP9u/9unkeR/383bvO9sbe+ePQPib8Tf+Fc/2X/xKP7Q+3+b/AMvPlbNmz/YbOd/t0o+JvxN/4Vz/AGX/AMSj+0Pt/m/8vPlbNmz/AGGznf7dK8A+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0r3/4m/DL/hY39l/8Tf8As/7B5v8Ay7ebv37P9tcY2e/Wj4m/E3/hXP8AZf8AxKP7Q+3+b/y8+Vs2bP8AYbOd/t0r5Ar0D4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Su//wCGmv8AqUf/ACpf/aq4D4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Su//aa/5lb/ALe//aNcB8Mvhl/wsb+1P+Jv/Z/2Dyv+Xbzd+/f/ALa4xs9+tHxN+Jv/AAsb+y/+JR/Z/wBg83/l583fv2f7C4xs9+te/wDwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpXgHwy+GX/Cxv7U/4m/9n/YPK/5dvN379/8AtrjGz360fE34Zf8ACuf7L/4m/wDaH2/zf+XbytmzZ/ttnO/26V5/Xv8A+01/zK3/AG9/+0a4D4ZfDL/hY39qf8Tf+z/sHlf8u3m79+//AG1xjZ79a9/+GXxN/wCFjf2p/wASj+z/ALB5X/Lz5u/fv/2FxjZ79aPhl8Mv+Fc/2p/xN/7Q+3+V/wAu3lbNm/8A22znf7dK+QK9/wD2Zf8Amaf+3T/2tX0BRRRRXyB8Tfhl/wAK5/sv/ib/ANofb/N/5dvK2bNn+22c7/bpXf8A/DTX/Uo/+VL/AO1VwHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrXf8A/DMv/U3f+U3/AO21wHwy+Jv/AArn+1P+JR/aH2/yv+Xnytmzf/sNnO/26UfDL4m/8K5/tT/iUf2h9v8AK/5efK2bN/8AsNnO/wBule//ABN+Jv8Awrn+y/8AiUf2h9v83/l58rZs2f7DZzv9uleAfE34m/8ACxv7L/4lH9n/AGDzf+Xnzd+/Z/sLjGz3615/XoHxN+Jv/Cxv7L/4lH9n/YPN/wCXnzd+/Z/sLjGz3613/wC01/zK3/b3/wC0a9A+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0rwD4ZfDL/hY39qf8Tf8As/7B5X/Lt5u/fv8A9tcY2e/Wu/8A+GZf+pu/8pv/ANtrgPhl8Mv+Fjf2p/xN/wCz/sHlf8u3m79+/wD21xjZ79a8/r0D4ZfDL/hY39qf8Tf+z/sHlf8ALt5u/fv/ANtcY2e/Wj4m/E3/AIWN/Zf/ABKP7P8AsHm/8vPm79+z/YXGNnv1rv8A/hpr/qUf/Kl/9qr0D4m/DL/hY39l/wDE3/s/7B5v/Lt5u/fs/wBtcY2e/WvP/wBmX/maf+3T/wBrV6B8Mvib/wALG/tT/iUf2f8AYPK/5efN379/+wuMbPfrXgHwy+GX/Cxv7U/4m/8AZ/2Dyv8Al283fv3/AO2uMbPfrXf/APDMv/U3f+U3/wC20fsy/wDM0/8Abp/7WrgPib8Mv+Fc/wBl/wDE3/tD7f5v/Lt5WzZs/wBts53+3Svf/hl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK9Aooorz/4m/DL/AIWN/Zf/ABN/7P8AsHm/8u3m79+z/bXGNnv1rwD4ZfE3/hXP9qf8Sj+0Pt/lf8vPlbNm/wD2Gznf7dK7/wDZl/5mn/t0/wDa1egfDL4Zf8K5/tT/AIm/9ofb/K/5dvK2bN/+22c7/bpXgHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrR8Tfhl/wrn+y/wDib/2h9v8AN/5dvK2bNn+22c7/AG6V3/7TX/Mrf9vf/tGuA+GXxN/4Vz/an/Eo/tD7f5X/AC8+Vs2b/wDYbOd/t0o+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0r6/rz/4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3Sj4ZfDL/hXP9qf8Tf+0Pt/lf8ALt5WzZv/ANts53+3SvP/ANmX/maf+3T/ANrV6B8Mvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9uleAfDL4m/8ACuf7U/4lH9ofb/K/5efK2bN/+w2c7/bpX1/RRXyB8Tfib/wsb+y/+JR/Z/2Dzf8Al583fv2f7C4xs9+td/8A8m5/9TD/AG7/ANunkeR/383bvO9sbe+ePAK+v/ib8Tf+Fc/2X/xKP7Q+3+b/AMvPlbNmz/YbOd/t0rz/APZl/wCZp/7dP/a1egfDL4Zf8K5/tT/ib/2h9v8AK/5dvK2bN/8AttnO/wBuleAfDL4m/wDCuf7U/wCJR/aH2/yv+Xnytmzf/sNnO/26V7/8Tfhl/wALG/sv/ib/ANn/AGDzf+Xbzd+/Z/trjGz3615/+zL/AMzT/wBun/tavoCiiivP/ib8Tf8AhXP9l/8AEo/tD7f5v/Lz5WzZs/2Gznf7dK8//wCTc/8AqYf7d/7dPI8j/v5u3ed7Y2988H/DMv8A1N3/AJTf/ttH/DMv/U3f+U3/AO214BXv/wDwzL/1N3/lN/8AttH/AA01/wBSj/5Uv/tVH/DMv/U3f+U3/wC214BXoHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrXf8A7Mv/ADNP/bp/7Wr0D4ZfE3/hY39qf8Sj+z/sHlf8vPm79+//AGFxjZ79a8//AOGZf+pu/wDKb/8Aba4D4ZfDL/hY39qf8Tf+z/sHlf8ALt5u/fv/ANtcY2e/Wj4ZfDL/AIWN/an/ABN/7P8AsHlf8u3m79+//bXGNnv1r3/4m/DL/hY39l/8Tf8As/7B5v8Ay7ebv37P9tcY2e/WvP8A9mX/AJmn/t0/9rV9AV8//wDDMv8A1N3/AJTf/ttH/Jxn/Uvf2F/29+f5/wD3727fJ987u2OfQPib8Mv+Fjf2X/xN/wCz/sHm/wDLt5u/fs/21xjZ79a9Ar5A+Jvwy/4Vz/Zf/E3/ALQ+3+b/AMu3lbNmz/bbOd/t0o+Jvwy/4Vz/AGX/AMTf+0Pt/m/8u3lbNmz/AG2znf7dK9/+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0rz//AJOM/wCpe/sL/t78/wA//v3t2+T753dscn7Mv/M0/wDbp/7Wr6Aooorz/wCGXwy/4Vz/AGp/xN/7Q+3+V/y7eVs2b/8AbbOd/t0rz/8A4Zl/6m7/AMpv/wBto/Zl/wCZp/7dP/a1H/Juf/Uw/wBu/wDbp5Hkf9/N27zvbG3vng/Zl/5mn/t0/wDa1H/Juf8A1MP9u/8Abp5Hkf8Afzdu872xt7544D4ZfDL/AIWN/an/ABN/7P8AsHlf8u3m79+//bXGNnv1o+GXwy/4WN/an/E3/s/7B5X/AC7ebv37/wDbXGNnv1o+JvxN/wCFjf2X/wASj+z/ALB5v/Lz5u/fs/2FxjZ79aPhl8Mv+Fjf2p/xN/7P+weV/wAu3m79+/8A21xjZ79a7/8A5OM/6l7+wv8At78/z/8Av3t2+T753dsc8B8Mvib/AMK5/tT/AIlH9ofb/K/5efK2bN/+w2c7/bpXv/xN+GX/AAsb+y/+Jv8A2f8AYPN/5dvN379n+2uMbPfrXn//AA01/wBSj/5Uv/tVegfDL4m/8LG/tT/iUf2f9g8r/l583fv3/wCwuMbPfrXn/wCzL/zNP/bp/wC1q4D4ZfE3/hXP9qf8Sj+0Pt/lf8vPlbNm/wD2Gznf7dKPib8Mv+Fc/wBl/wDE3/tD7f5v/Lt5WzZs/wBts53+3Su//Zl/5mn/ALdP/a1fQFef/E34Zf8ACxv7L/4m/wDZ/wBg83/l283fv2f7a4xs9+tef/8ADTX/AFKP/lS/+1VwHxN+GX/Cuf7L/wCJv/aH2/zf+XbytmzZ/ttnO/26V5/Xv/8AwzL/ANTd/wCU3/7bR/ybn/1MP9u/9unkeR/383bvO9sbe+eD9mX/AJmn/t0/9rV9AUUUV8AUV7//AMnGf9S9/YX/AG9+f5//AH727fJ987u2OfQPhl8Mv+Fc/wBqf8Tf+0Pt/lf8u3lbNm//AG2znf7dK8A+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0rv8A9pr/AJlb/t7/APaNH/DMv/U3f+U3/wC20f8ADMv/AFN3/lN/+216B8Mvhl/wrn+1P+Jv/aH2/wAr/l28rZs3/wC22c7/AG6V5/8A8nGf9S9/YX/b35/n/wDfvbt8n3zu7Y59A+Jvwy/4WN/Zf/E3/s/7B5v/AC7ebv37P9tcY2e/WvQK+QPib8Tf+Fjf2X/xKP7P+web/wAvPm79+z/YXGNnv1o+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0r3/4m/DL/hY39l/8Tf8As/7B5v8Ay7ebv37P9tcY2e/Wj4ZfE3/hY39qf8Sj+z/sHlf8vPm79+//AGFxjZ79a8//AOTjP+pe/sL/ALe/P8//AL97dvk++d3bHPoHxN+Jv/Cuf7L/AOJR/aH2/wA3/l58rZs2f7DZzv8AbpR8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXgHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9uld/8A8My/9Td/5Tf/ALbXoHxN+Jv/AArn+y/+JR/aH2/zf+XnytmzZ/sNnO/26V5/+zL/AMzT/wBun/taj/k3P/qYf7d/7dPI8j/v5u3ed7Y2988fQFfP/wDybn/1MP8Abv8A26eR5H/fzdu872xt754+gKKKKK+AK+v/AIZfE3/hY39qf8Sj+z/sHlf8vPm79+//AGFxjZ79aPhl8Tf+Fjf2p/xKP7P+weV/y8+bv37/APYXGNnv1rwD4m/DL/hXP9l/8Tf+0Pt/m/8ALt5WzZs/22znf7dK9/8Ahl8Mv+Fc/wBqf8Tf+0Pt/lf8u3lbNm//AG2znf7dK8//AOGZf+pu/wDKb/8Aba8Ar6/+Jvwy/wCFjf2X/wATf+z/ALB5v/Lt5u/fs/21xjZ79aPib8Mv+Fjf2X/xN/7P+web/wAu3m79+z/bXGNnv1rz/wD4Zl/6m7/ym/8A22j/AJNz/wCph/t3/t08jyP+/m7d53tjb3zx6B8Mvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9ulHwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpXgHwy+Jv/Cuf7U/4lH9ofb/ACv+Xnytmzf/ALDZzv8AbpXv/wAMvib/AMLG/tT/AIlH9n/YPK/5efN379/+wuMbPfrXgHxN+GX/AArn+y/+Jv8A2h9v83/l28rZs2f7bZzv9uld/wD8NNf9Sj/5Uv8A7VX0BXyB8Mvhl/wsb+1P+Jv/AGf9g8r/AJdvN379/wDtrjGz3619f18//wDDTX/Uo/8AlS/+1V6B8Tfhl/wsb+y/+Jv/AGf9g83/AJdvN379n+2uMbPfrR8Mvib/AMLG/tT/AIlH9n/YPK/5efN379/+wuMbPfrR8Mvib/wsb+1P+JR/Z/2Dyv8Al583fv3/AOwuMbPfrR8Tfhl/wsb+y/8Aib/2f9g83/l283fv2f7a4xs9+tef/sy/8zT/ANun/taj9mX/AJmn/t0/9rV9AUUUV8//ALTX/Mrf9vf/ALRo/wCGZf8Aqbv/ACm//ba+gK+f/wDk3P8A6mH+3f8At08jyP8Av5u3ed7Y2988eAUV7/8A8NNf9Sj/AOVL/wC1Uf8AJuf/AFMP9u/9unkeR/383bvO9sbe+ePQPib8Mv8AhY39l/8AE3/s/wCweb/y7ebv37P9tcY2e/WvP/8Ak4z/AKl7+wv+3vz/AD/+/e3b5Pvnd2xzwHwy+Jv/AArn+1P+JR/aH2/yv+Xnytmzf/sNnO/26UfDL4Zf8LG/tT/ib/2f9g8r/l283fv3/wC2uMbPfrXv/wATfib/AMK5/sv/AIlH9ofb/N/5efK2bNn+w2c7/bpXn/7Mv/M0/wDbp/7Wr0D4ZfDL/hXP9qf8Tf8AtD7f5X/Lt5WzZv8A9ts53+3Sj4ZfDL/hXP8Aan/E3/tD7f5X/Lt5WzZv/wBts53+3SvAPib8Mv8AhXP9l/8AE3/tD7f5v/Lt5WzZs/22znf7dKPhl8Mv+Fjf2p/xN/7P+weV/wAu3m79+/8A21xjZ79a7/8AZl/5mn/t0/8Aa1cB8Mvib/wrn+1P+JR/aH2/yv8Al58rZs3/AOw2c7/bpR8Mvib/AMK5/tT/AIlH9ofb/K/5efK2bN/+w2c7/bpXf/8AJuf/AFMP9u/9unkeR/383bvO9sbe+eOA+Jvwy/4Vz/Zf/E3/ALQ+3+b/AMu3lbNmz/bbOd/t0o+GXxN/4Vz/AGp/xKP7Q+3+V/y8+Vs2b/8AYbOd/t0rv/8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPB/w01/1KP/AJUv/tVegfDL4m/8LG/tT/iUf2f9g8r/AJefN379/wDsLjGz3616BRRRRXyB8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpR8Mvib/AMK5/tT/AIlH9ofb/K/5efK2bN/+w2c7/bpXv/wy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulHxN+GX/Cxv7L/AOJv/Z/2Dzf+Xbzd+/Z/trjGz3615/8A8My/9Td/5Tf/ALbXoHxN+Jv/AArn+y/+JR/aH2/zf+XnytmzZ/sNnO/26V4B8Mvhl/wsb+1P+Jv/AGf9g8r/AJdvN379/wDtrjGz3617/wDDL4m/8LG/tT/iUf2f9g8r/l583fv3/wCwuMbPfrXgHxN+Jv8Awsb+y/8AiUf2f9g83/l583fv2f7C4xs9+te//DL4m/8ACxv7U/4lH9n/AGDyv+Xnzd+/f/sLjGz3614B8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpXv/AMTfhl/wsb+y/wDib/2f9g83/l283fv2f7a4xs9+tegV5/8AE34Zf8LG/sv/AIm/9n/YPN/5dvN379n+2uMbPfrR8Tfib/wrn+y/+JR/aH2/zf8Al58rZs2f7DZzv9ulef8A/Jxn/Uvf2F/29+f5/wD3727fJ987u2OfAK9A+GXxN/4Vz/an/Eo/tD7f5X/Lz5WzZv8A9hs53+3Svf8A4m/E3/hXP9l/8Sj+0Pt/m/8ALz5WzZs/2Gznf7dKPhl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK9Ar5A+JvxN/wCFjf2X/wASj+z/ALB5v/Lz5u/fs/2FxjZ79aPhl8Mv+Fjf2p/xN/7P+weV/wAu3m79+/8A21xjZ79a9/8Aib8Tf+Fc/wBl/wDEo/tD7f5v/Lz5WzZs/wBhs53+3SvQK8/+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0r0CiiivkD4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Su//wCGZf8Aqbv/ACm//ba+gK8/+GXwy/4Vz/an/E3/ALQ+3+V/y7eVs2b/APbbOd/t0rz/AP4Zl/6m7/ym/wD22vQPib8Tf+Fc/wBl/wDEo/tD7f5v/Lz5WzZs/wBhs53+3SvQK8/+Jvwy/wCFjf2X/wATf+z/ALB5v/Lt5u/fs/21xjZ79a8//Zl/5mn/ALdP/a1cB8Tfib/wsb+y/wDiUf2f9g83/l583fv2f7C4xs9+te//AAy+GX/Cuf7U/wCJv/aH2/yv+Xbytmzf/ttnO/26UfE34m/8K5/sv/iUf2h9v83/AJefK2bNn+w2c7/bpR8Tfhl/wsb+y/8Aib/2f9g83/l283fv2f7a4xs9+tef/wDJuf8A1MP9u/8Abp5Hkf8Afzdu872xt754P+TjP+pe/sL/ALe/P8//AL97dvk++d3bHPoHwy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpR8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXn//AAzL/wBTd/5Tf/tteAUV9f8AxN+Jv/Cuf7L/AOJR/aH2/wA3/l58rZs2f7DZzv8AbpXgHxN+Jv8Awsb+y/8AiUf2f9g83/l583fv2f7C4xs9+tfX9FfIHwy+Jv8Awrn+1P8AiUf2h9v8r/l58rZs3/7DZzv9ulHwy+Jv/Cuf7U/4lH9ofb/K/wCXnytmzf8A7DZzv9ule/8Awy+Jv/Cxv7U/4lH9n/YPK/5efN379/8AsLjGz3616BRRRXyB8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpXf/APJxn/Uvf2F/29+f5/8A3727fJ987u2OT/hmX/qbv/Kb/wDbaP8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPB/wzL/ANTd/wCU3/7bR+01/wAyt/29/wDtGj9mX/maf+3T/wBrV6B8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXn//AAzL/wBTd/5Tf/ttH/Juf/Uw/wBu/wDbp5Hkf9/N27zvbG3vnjgPhl8Mv+Fjf2p/xN/7P+weV/y7ebv37/8AbXGNnv1r3/4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3SvP/2Zf+Zp/wC3T/2tXoHxN+GX/Cxv7L/4m/8AZ/2Dzf8Al283fv2f7a4xs9+tef8A/Jxn/Uvf2F/29+f5/wD3727fJ987u2OfQPib8Mv+Fjf2X/xN/wCz/sHm/wDLt5u/fs/21xjZ79a8/wD+Gmv+pR/8qX/2quA+JvxN/wCFjf2X/wASj+z/ALB5v/Lz5u/fs/2FxjZ79a9/+Jvwy/4WN/Zf/E3/ALP+web/AMu3m79+z/bXGNnv1rwD4m/DL/hXP9l/8Tf+0Pt/m/8ALt5WzZs/22znf7dKPib8Mv8AhXP9l/8AE3/tD7f5v/Lt5WzZs/22znf7dK9/+JvxN/4Vz/Zf/Eo/tD7f5v8Ay8+Vs2bP9hs53+3SvP8A9pr/AJlb/t7/APaNH/Juf/Uw/wBu/wDbp5Hkf9/N27zvbG3vng/Zl/5mn/t0/wDa1eAV7/8Asy/8zT/26f8AtavoCiiiivP/AIm/DL/hY39l/wDE3/s/7B5v/Lt5u/fs/wBtcY2e/WvQK8/+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0o+GXxN/4WN/an/Eo/s/7B5X/AC8+bv37/wDYXGNnv1o+Jvwy/wCFjf2X/wATf+z/ALB5v/Lt5u/fs/21xjZ79a8//aa/5lb/ALe//aNH/Jxn/Uvf2F/29+f5/wD3727fJ987u2OfAK9//wCTjP8AqXv7C/7e/P8AP/797dvk++d3bHJ/w01/1KP/AJUv/tVH/DMv/U3f+U3/AO21wHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrXf8A/DMv/U3f+U3/AO214BXv/wC01/zK3/b3/wC0aP8Ak4z/AKl7+wv+3vz/AD/+/e3b5Pvnd2xyftNf8yt/29/+0a4D4ZfE3/hXP9qf8Sj+0Pt/lf8ALz5WzZv/ANhs53+3Svf/AIZfDL/hXP8Aan/E3/tD7f5X/Lt5WzZv/wBts53+3SvAPhl8Mv8AhY39qf8AE3/s/wCweV/y7ebv37/9tcY2e/Wu/wD+Tc/+ph/t3/t08jyP+/m7d53tjb3zxwHwy+GX/Cxv7U/4m/8AZ/2Dyv8Al283fv3/AO2uMbPfrXf/APDMv/U3f+U3/wC21wHwy+Jv/Cuf7U/4lH9ofb/K/wCXnytmzf8A7DZzv9ule/8AxN+Jv/Cuf7L/AOJR/aH2/wA3/l58rZs2f7DZzv8AbpR8Mvib/wALG/tT/iUf2f8AYPK/5efN379/+wuMbPfrXoFFFFfIHwy+GX/Cxv7U/wCJv/Z/2Dyv+Xbzd+/f/trjGz3613//AAzL/wBTd/5Tf/ttH/DMv/U3f+U3/wC20fsy/wDM0/8Abp/7Wo/5OM/6l7+wv+3vz/P/AO/e3b5Pvnd2xyf8NNf9Sj/5Uv8A7VXAfDL4m/8ACuf7U/4lH9ofb/K/5efK2bN/+w2c7/bpR8Mvhl/wsb+1P+Jv/Z/2Dyv+Xbzd+/f/ALa4xs9+td//AMNNf9Sj/wCVL/7VR/ybn/1MP9u/9unkeR/383bvO9sbe+ePAK9//Zl/5mn/ALdP/a1H7Mv/ADNP/bp/7Wr0D4ZfDL/hXP8Aan/E3/tD7f5X/Lt5WzZv/wBts53+3SvAPhl8Mv8AhY39qf8AE3/s/wCweV/y7ebv37/9tcY2e/WvP69//Zl/5mn/ALdP/a1H7Mv/ADNP/bp/7Wo/aa/5lb/t7/8AaNegfDL4m/8ACxv7U/4lH9n/AGDyv+Xnzd+/f/sLjGz3615/+zL/AMzT/wBun/taj/k3P/qYf7d/7dPI8j/v5u3ed7Y2988H7Mv/ADNP/bp/7Wr0D4ZfDL/hXP8Aan/E3/tD7f5X/Lt5WzZv/wBts53+3SvkCvQPhl8Mv+Fjf2p/xN/7P+weV/y7ebv37/8AbXGNnv1r3/4ZfE3/AIWN/an/ABKP7P8AsHlf8vPm79+//YXGNnv1r0Ciiivn/wDZl/5mn/t0/wDa1eAV7/8Asy/8zT/26f8Ataj9mX/maf8At0/9rUf8nGf9S9/YX/b35/n/APfvbt8n3zu7Y59A+GXxN/4WN/an/Eo/s/7B5X/Lz5u/fv8A9hcY2e/WvP8A/hpr/qUf/Kl/9qrgPhl8Mv8AhY39qf8AE3/s/wCweV/y7ebv37/9tcY2e/WvP6+v/hl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK8//aa/5lb/ALe//aNegfDL4m/8LG/tT/iUf2f9g8r/AJefN379/wDsLjGz3615/wD8My/9Td/5Tf8A7bR/wzL/ANTd/wCU3/7bXAfDL4Zf8LG/tT/ib/2f9g8r/l283fv3/wC2uMbPfrXv/wATfhl/wsb+y/8Aib/2f9g83/l283fv2f7a4xs9+tHwy+Jv/Cxv7U/4lH9n/YPK/wCXnzd+/f8A7C4xs9+tef8A/Juf/Uw/27/26eR5H/fzdu872xt7544D4m/DL/hXP9l/8Tf+0Pt/m/8ALt5WzZs/22znf7dK7/8A5Nz/AOph/t3/ALdPI8j/AL+bt3ne2NvfPHAfDL4m/wDCuf7U/wCJR/aH2/yv+Xnytmzf/sNnO/26V7/8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXgHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9ulef0V9f8Awy+Jv/Cxv7U/4lH9n/YPK/5efN379/8AsLjGz3615/8Asy/8zT/26f8AtavoCiiivn/9mX/maf8At0/9rUf8My/9Td/5Tf8A7bXoHwy+GX/Cuf7U/wCJv/aH2/yv+Xbytmzf/ttnO/26V5/+zL/zNP8A26f+1q9A+Jvwy/4WN/Zf/E3/ALP+web/AMu3m79+z/bXGNnv1r0CvgCvr/4m/DL/AIWN/Zf/ABN/7P8AsHm/8u3m79+z/bXGNnv1o+JvxN/4Vz/Zf/Eo/tD7f5v/AC8+Vs2bP9hs53+3Sj4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3SvP/2mv+ZW/wC3v/2jR/wzL/1N3/lN/wDttcB8Mvib/wAK5/tT/iUf2h9v8r/l58rZs3/7DZzv9ule/wDwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpR8Tfib/AMK5/sv/AIlH9ofb/N/5efK2bNn+w2c7/bpR8Tfhl/wsb+y/+Jv/AGf9g83/AJdvN379n+2uMbPfrXgHwy+Jv/Cuf7U/4lH9ofb/ACv+Xnytmzf/ALDZzv8AbpR8Mvhl/wALG/tT/ib/ANn/AGDyv+Xbzd+/f/trjGz3617/APDL4Zf8K5/tT/ib/wBofb/K/wCXbytmzf8A7bZzv9ulef8A/DMv/U3f+U3/AO21wHwy+Jv/AArn+1P+JR/aH2/yv+Xnytmzf/sNnO/26V3/AO01/wAyt/29/wDtGuA+GXxN/wCFc/2p/wASj+0Pt/lf8vPlbNm//YbOd/t0r3/4m/E3/hXP9l/8Sj+0Pt/m/wDLz5WzZs/2Gznf7dK8/wD2Zf8Amaf+3T/2tXAfE34Zf8K5/sv/AIm/9ofb/N/5dvK2bNn+22c7/bpXv/wy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulegUUUV8//APDMv/U3f+U3/wC20f8ADMv/AFN3/lN/+20f8My/9Td/5Tf/ALbXoHwy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulef/8ADMv/AFN3/lN/+20f8My/9Td/5Tf/ALbR/wAMy/8AU3f+U3/7bX0BXn/xN+GX/Cxv7L/4m/8AZ/2Dzf8Al283fv2f7a4xs9+tef8A/DMv/U3f+U3/AO216B8Mvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9ulHxN+GX/Cxv7L/4m/8AZ/2Dzf8Al283fv2f7a4xs9+tHwy+GX/Cuf7U/wCJv/aH2/yv+Xbytmzf/ttnO/26V6BXn/xN+GX/AAsb+y/+Jv8A2f8AYPN/5dvN379n+2uMbPfrR8Mvhl/wrn+1P+Jv/aH2/wAr/l28rZs3/wC22c7/AG6V5/8A8My/9Td/5Tf/ALbXoHwy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulef/8ADMv/AFN3/lN/+20f8My/9Td/5Tf/ALbXoHxN+GX/AAsb+y/+Jv8A2f8AYPN/5dvN379n+2uMbPfrR8Mvhl/wrn+1P+Jv/aH2/wAr/l28rZs3/wC22c7/AG6UfE34Zf8ACxv7L/4m/wDZ/wBg83/l283fv2f7a4xs9+tegV5/8Mvhl/wrn+1P+Jv/AGh9v8r/AJdvK2bN/wDttnO/26UfE34Zf8LG/sv/AIm/9n/YPN/5dvN379n+2uMbPfrXoFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFf/2Q=="
  }
}
```

### Response Body Params

| Campo                   | Tipo   | Descrição                                                                         | Caracteres |
|-------------------------|--------|-----------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4 | 36         |
| `bank_slip_key` *       | uuidv4 | Chave única de identificação do boleto no formato uuid v4                         | 36         |
| `bank_slip_status` *    | string | Status do boleto       | **[Enumeradores bank_slip_status](#enumeradores-bank_slip_status)**   |
| `our_number` *          | integer| Número único de identificação do boleto junto à carteira                          | 11         |
| `barcode` *             | string | Código de barras do boleto                                                        | 44         |
| `digitable_line` *      | string | Linha digitável do boleto                                                         | 47         |
| `qr_code_data`          | object | Dados do QR Code                             | **[Objeto qr_code_data](#objeto-qr_code_data)** |
| `created_at` *          | string | Data, no formato ISO (UTC - "YYYY-MM-DDTHH:MM:SSZ"), da criação da ocorrência     | 20         |

### Enumeradores bank_slip_status

| Enumerador         | Descrição                               |
|--------------------|-----------------------------------------|
| accepted           | Boleto aceito mas ainda não registrado  |

### Objeto qr_code_data
| Campo                      | Tipo   | Descrição                                             | Caracteres              |
|----------------------------|--------|-------------------------------------------------------|-------------------------|
| `qr_code_key`              | uuidv4 | Chave única de identificação do QR Code               | 36                      |
| `pix_key`                  | uuidv4 | Chave PIX vinculada ao QR Code                        | 36                      |
| `receiver_conciliation_id` | uuidv4 | Identificador de conciliação do QR Code               | 36                      |
| `url`                      | string | URL (Pix Copia e Cola) do QR Code                     | -                       |
| `image`                    | string | base64 da URL (Pix Copia e Cola) do QR Code           | -                       |

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 404                      | BKS000004            | Not Found | Pix key not found: `{pix_key}`                                               | Chave pix não encontrada: `{pix_key}`                                               |
| 403                      | BKS000005            | Forbidden                         | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404                      | BKS000006            | Not Found                                  | The source account key was not found.                                                                                | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                  | It was not possible to consult the source account at this time. Please try again in a few minutes.                                                                                      | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                                                                                    |
| 400                      | BKS000008            | Bad Request | The source account is closed.         |               A conta de origem está fechada.                                                                 |
| 400                      | BKS000009            | Bad Request | The source account is blocked.         |               A conta de origem está bloqueada.                                                                 |
| 403                      | BKS000010            | Forbidden                                 | The pix key owner does not match the account owner.                                                                                     | O proprietário da chave pix não corresponde ao proprietário da conta.                                                             |
| 404                      | BKS000013            | Not Found | Requester profile not found         |               Carteira não encontrada                                                                 |
| 409                      | BKS000014            | Conflict           | Request control key already sent or duplicated sent: `{request_control_key}`                                                              | Chave de controle da requisição já utilizada ou enviada duplicada: `{request_control_key}`                                                                        |
| 400                      | BKS000016            | Bad Request                                        | Expiration date must be greater than the current date and have a maximum of 3650 days from the current date.                                    | A data de vencimento deve ser maior que a data atual e possuir no máximo 3650 dias corridos a partir da data atual.                                     |
| 409                      | BKS000017            | Conflict                                        | Our number already used or duplicated sent: `{our_number}`                                                                                       | Nosso número já utilizado ou enviado duplicado: `{our_number}`                                                                               |
| 400                      | BKS000018            | Bad Request                                        | The discount dates must be less than the expiration date and increasing.                                                      | A data dos descontos devem ser menores que a de expiração e crescentes.                                               |
| 400                      | BKS000019            | Bad Request                                        | Payer address is required for protest.                                                                                       | Endereço do pagador é obrigatório para protesto.                                                                         |
| 500                      | BKS000021            | Internal Server Error                                  | Error while trying to generate QR Code.                                                               | Erro ao tentar gerar QR Code de pagamento.                                                           |
| 400                      | BKS000022            | Bad Request                                        | Requester profile is not opened.                                                              | Carteira não está aberta.                          |
| 400                      | BKS000026            | Bad Request                      | Guarantor address is required for protest.                                                                                        | Endereço do sacador é obrigatório para protesto.                                                                   |
| 404                      | BKS000028            | Not Found             | Notary office attended region not found for postal code: `{postal_code}`                                                          | Região de cartório não encontrada para o CEP: `{postal_code}`                                                                                 |
| 400                      | BKS000043            | Bad Request             | Invalid discount numbering. Discounts must be numbered in ascending order and start on 1.          | Numeração dos descontos inválida. Os descontos devem ser numerados em ordem crescente e começar em 1.                                                           |
| 400                      | BKS000045            | Bad Request                                        | Rebate amount can not be equal or greater than the bank slip amount.                                                              | O valor do rebate não pode ser igual ou maior do que o valor do boleto.                          |
| 400                      | BKS000047            | Bad Request             | It was not possible to consult the sent pix key at this time. Please try again in a few minutes.          | Não foi possível consultar a chave pix enviada no momento. Por favor, tente novamente em alguns minutos.                                                           |
| 400                      | BKS000125            | Bad Request             | Partial payment data is required for this bank slip species type.          | Os dados de pagamento parcial são obrigatórios para o tipo de boleto fornecido.                                                           |
| 400                      | BKS000128            | Bad Request             | QR code payment is not allowed for partial payment.          | Pagamento via QR code não é permitido para pagamento parcial.                                                           |
| 400                      | BKS000128            | Bad Request             | QR code payment is not allowed for partial payment.          | Pagamento via QR code não é permitido para pagamento parcial.                                                           |
| 400                      | BKS000131            | Bad Request             | Rebate amount is not allowed for this bank slip species type.          | O valor de abatimento não é permitido para o tipo de boleto fornecido.                                                           |
| 400                      | BKS000132            | Bad Request             | Discount data is not allowed for this bank slip species type.          | Os dados de desconto não são permitidos para o tipo de boleto fornecido.                                                           |
| 400                      | BKS000133            | Bad Request             | Fine data is not allowed for this bank slip species type.          | Os dados de multa não são permitidos para o tipo de boleto fornecido.                                                           |
| 400                      | BKS000134            | Bad Request             | Interest data is not allowed for this bank slip species type.          | Os dados de juros não são permitidos para o tipo de boleto fornecido.                                                           |
| 400                      | BKS000136            | Bad Request             | Only credit card financial instrument type can have zero amount.          | Apenas o tipo de instrumento financeiro cartão de crédito pode ter valor zero.                                                           |

---

# Emissão de boletos em lote

URL: /documentation/boletos/emissao/emissao_em_lote

:::danger Importante
Para registrar bolePix, é necessário que exista uma chave Pix aleatória ativa na conta em que os boletos serão registrados.
:::

A emissão de boletos em lote é feita somente de maneira assíncrona. Caso um dos boletos falhe na validação das informações fornecidas, nenhum dos boletos será registrado nessa mesma requisição.

:::caution Atenção!
Como tratam-se de um registros assíncronos, o solicitante é notificado via [**webhook**](/documentation/boletos/v2/webhooks/boleto) assim que cada um dos boletos mudar de status de `accepted` para `registered` ou `rejected`.
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/batch
MÉTODO POST

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36         |

Request Body

```json
{
  "bank_slips": [
    {
      "request_control_key": "c86d8902-a5ae-4d1f-8872-e6fea1268aab",
      "our_number": 123456789,
      "document_number": "DOC4561237",
      "amount": 5000.00,
      "expiration": "2025-01-01",
      "bank_teller_instructions": "Confirm payment",
      "protest_data": {"days_to_protest": 7},
      "bankruptcy_protest_data": {"days_to_bankruptcy_protest": 14},
      "max_payment_days": 45,
      "fine_data": {"fine_type": "absolute", "fine_amount": 100.00, "days_to_fine": 10},
      "interest_data": {
        "interest_type": "workdays_daily_amount",
        "interest_amount": 10.00,
        "days_to_interest": 2,
      },
      "financial_instrument_type": "digital_commercial_invoice",
      "write_off_data": {"days_to_write_off": 365},
      "rebate_amount": 200.00,
      "discounts_data": [
        {
          "discount_amount": 50.00,
          "discount_number": 1,
          "discount_type": "absolute",
          "discount_limit_date": "2025-01-01",
        }
      ],
      "payer_data": {
        "name": "Global Tech",
        "contact": {
          "email": "finance@globaltech.com",
          "phone": {"country_code": "055", "area_code": "11", "number": "987654321"},
        },
        "address": {
          "street": "101 High St.",
          "neighborhood": "Tech Park",
          "number": "202",
          "postal_code": "49069234",
          "city": "Innovation City",
          "state": "SP",
          "complement": "Building A",
        },
        "document_number": "12345678000195",
        "person_type": "legal",
      },
      "guarantor_data": {
        "name": "Jane Doe",
        "contact": {
          "email": "jane.doe@qitech.com.br",
          "phone": {"country_code": "055", "area_code": "11", "number": "999999999"},
        },
        "address": {
          "street": "202 Elm St.",
          "neighborhood": "Quiet Neighborhood",
          "number": "303",
          "postal_code": "35700854",
          "city": "Peaceful Town",
          "state": "RJ",
          "complement": "House 1",
        },
        "document_number": "23456789012",
        "person_type": "natural",
      },
      "pix_key": "78252991-d26d-4d6b-8c50-be3233ffabf7",
      "notification": {
        "document_number": "12345678000195",
        "name": "Global Tech",
        "email": "finance@globaltech.com",
        "phone": {"country_code": "055", "area_code": "11", "number": "987654321"},
        "send_2_way": true,
        "send_before_due_date": true,
        "send_after_due_date": true,
        "send_on_protest": true
      }
    },
    {
      "request_control_key": "b3a428fd-58ee-4d6f-8872-633874ebf5e2",
      "our_number": 987654321,
      "document_number": "DOC4561237",
      "amount": 5000.00,
      "expiration": "2025-01-01",
      "bank_teller_instructions": "Confirm payment",
      "protest_data": {"days_to_protest": 7},
      "bankruptcy_protest_data": {"days_to_bankruptcy_protest": 14},
      "max_payment_days": 45,
      "fine_data": {"fine_type": "absolute", "fine_amount": 100.00, "days_to_fine": 10},
      "interest_data": {
        "interest_type": "workdays_daily_amount",
        "interest_amount": 10.00,
        "days_to_interest": 2
      },
      "financial_instrument_type": "digital_commercial_invoice",
      "write_off_data": {"days_to_write_off": 365},
      "rebate_amount": 200.00,
      "discounts_data": [
        {
          "discount_amount": 50.00,
          "discount_number": 1,
          "discount_type": "absolute",
          "discount_limit_date": "2025-01-01"
        }
      ],
      "payer_data": {
        "name": "Global Tech",
        "contact": {
          "email": "finance@globaltech.com",
          "phone": {"country_code": "055", "area_code": "11", "number": "987654321"},
        },
        "address": {
          "street": "101 High St.",
          "neighborhood": "Tech Park",
          "number": "202",
          "postal_code": "79071231",
          "city": "Innovation City",
          "state": "SP",
          "complement": "Building A"
        },
        "document_number": "12345678000195",
        "person_type": "legal"
      },
      "guarantor_data": {
        "name": "Jane Doe",
        "contact": {
          "email": "jane.doe@qitech.com.br",
          "phone": {"country_code": "055", "area_code": "11", "number": "999999999"},
        },
        "address": {
          "street": "202 Elm St.",
          "neighborhood": "Quiet Neighborhood",
          "number": "303",
          "postal_code": "65066380",
          "city": "Peaceful Town",
          "state": "RJ",
          "complement": "House 1"
        },
        "document_number": "23456789012",
        "person_type": "natural"
      }
    }
  ]
}
```

### Request Body Params

| Campo            | Tipo          | Descrição                             | Caracteres                                |
|------------------|---------------|---------------------------------------|-------------------------------------------|
| `bank_slips` *   | Array de **[Objeto bank_slip](#objeto-bank_slip)**  | Lista de boletos a serem registrados  | - |

### Objeto bank_slip

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `request_control_key` *    | uuidv4  | Chave única de identificação da request utilizada pelo cliente no formato uuid v4  | 36                                                |
| `our_number`               | integer | Número único de identificação do boleto junto à carteira. Pode ser enviado pelo cliente e, caso não seja, a QI Tech irá gerar um                           | 11                                                |
| `document_number`          | string  | Número de identificação do boleto                                                  | 10                                                |
| `participant_control_number` | string | Nº Controle do Participante                                                       |
25                                                |
| `amount` *                 | float   | Valor base do boleto                                                               | -                                                 |
| `expiration` *             | string  | Data de vencimento                                                                 | 10                                                |
| `bank_teller_instructions` | string  | Instruções adicionais de registro, que constarão no PDF do boleto. Aceita no máximo 320 caracteres, distribuídos em até 7 linhas. Cada linha pode conter no máximo 90 caracteres. Caso uma linha ultrapasse 90 caracteres, o texto será automaticamente quebrado em uma nova linha | 320                                               |
| `rebate_amount`            | float   | Valor de abatimento do boleto, que será aplicado em cima do valor base             | -                                                 |
| `max_payment_days`         | integer | Máximo de dias corridos que o boleto ficará disponível para pagamento, após o vencimento (pode ser no máximo 365) | -          |
| `financial_instrument_type`   | string  | Tipo de espécie do boleto | **[Enumeradores financial_instrument_type](#enumeradores-financial_instrument_type)** |
| `partial_payment_data`    | object  | Configurações de pagamento parcial                      | **[Objeto partial_payment_data](#objeto-partial_payment_data)** |
| `write_off_data`       | object  | Configuração de baixa      | **[Objeto write_off_data](#objeto-write_off_settings)** |
| `protest_data`         | object  | Configuração de protesto       | **[Objeto protest_data](#objeto-protest_settings)** |
| `bankruptcy_protest_data` | object  | Configuração de protesto falimentar | **[Objeto bankruptcy_protest_data](#objeto-bankruptcy_protest_settings)** |
| `fine_data`            | object  | Configuração de multa                 | **[Objeto fine_data](#objeto-fine_settings)** |
| `interest_data`        | object  | Configuração de juros        | **[Objeto interest_data](#objeto-interest_settings)** |
| `discounts_data`           | object array | Descontos           | **[Objeto discount](#objeto-discounts_data)** |
| `payer_data` *             | object  | Dados do pagador                                                                   | **[Objeto payer_data](#objetos-payer_data-e-guarantor_data)** |
| `guarantor_data`           | object  | Dados do sacador avalista                                                          | **[Objeto guarantor_data](#objetos-payer_data-e-guarantor_data)** |
| `pix_key`                  | uuidv4  | Chave pix do tipo aleatória                                                        | 36                                                |

:::info BolePix
Caso o parâmetro `pix_key`, opcional, seja enviado na request, será gerado um bolePix. BolePix é um boleto cujo pagamento é vinculado a um QR Code Pix. Sendo assim, o pagador pode realizar o pagamento do boleto tanto utilizando a linha digitável do mesmo, quanto através da leitura do QR Code Pix vinculado. Caso o pagamento seja feito via QR Code, a liquidação financeira se dá instantaneamente, enquanto os retornos bancários e webhooks envolvidos na liquidação serão gerados assim como é feito para um boleto comum.

Importante: para registrar um bolePix, é necessário que exista uma chave Pix aleatória ativa na conta em que boleto será registrado.
:::

:::tip Configurações Padrão da Carteira
Caso cada um dos campos `max_payment_days`, `write_off_data`, `protest_data`, `bankruptcy_protest_data`, `fine_data`, `interest_data` e `pix_key` não sejam enviados na request e a carteira possua configurações padrão (i.e. `max_payment_days`, `write_off_settings`, `protest_settings`, `bankruptcy_protest_settings`, `fine_settings`, `interest_settings` e `qr_code_settings`, respectivamente, no `configuration_data` do `requester_profile`), serão utilizadas tais configurações padrão para a emissão do título.
:::

:::caution Limitações e Restrições
- **Boletos de Pagamento Parcial:** Não é permitido o pagamento via QR Code Pix. Portanto, não é permitido enviar a `pix_key` no registro, nem ter uma configuração padrão de geração de bolePix para a carteira.

- **Boletos de Cartão de Crédito:** Não é necessário nem permitido enviar informações rebate, desconto, multa e juros. Isso se deve ao padrão do mercado, onde muitas Instituições Financeiras não aceitam o pagamento de boletos de cartão de crédito que contenham essas informações. A carteira também não pode ter essas configurações definidas como padrão. Sendo assim boletos desse tipo podem ser pagos parcialmente mesmo após o vencimento, sem incidência de juros, multas, descontos ou abatimentos na fatura corrente. Para aplicar esses valores é necessário incluí-los na próxima fatura, seja através da [ocorrência de edição de valor](/documentation/boletos/instrucoes/valor) do boleto ou emitindo um novo boleto que inclua esses valores. É possível enviar `amount = 0` para boletos deste tipo.

**Importante:** Boletos do tipo `credit_card` são obrigatoriamente de pagamento parcial, sendo assim é necessário fornecer as informações de `partial_payment_data` ou ter essa configuração padrão na carteira. Caso o campo `financial_instrument_type` não seja enviado, o valor padrão será `digital_commercial_invoice`.
:::

:::tip Recomendações de Carteiras
- **Carteira para Boletos Padrão:** Mantenha as configurações padrão para multas, juros e protesto
- **Carteira para Boletos de Pagamento Parcial:** Sem configuração de Pix e com regras específicas para pagamento parcial
- **Carteira para Boletos de Cartão de Crédito:** Sem configurações de multa, juros, desconto ou rebate

Criar carteiras específicas garante que as configurações padrão sejam adequadas para cada tipo de boleto e evita conflitos nas regras de negócio.
:::

:::info Máquina de Estados
A máquina de status para boletos de pagamento parcial possui algumas diferenças. Para mais detalhes, consulte a [introdução](/documentation/boletos/introducao) , onde há uma explicação sobre como aplicar a incidência de juros e multas no boleto seguindo as boas práticas do mercado.
:::

### Enumeradores financial_instrument_type

| Enumerador  | Descrição                        |
|-------------|----------------------------------|
| digital_commercial_invoice | DMI Duplicata Mercantil Indicação |
| credit_card | Cartão de Crédito |
| check | CH Cheque |
| digital_commercial | DM Duplicata Mercantil |
| digital_service_invoice | Duplicata de Serviço |
| digital_service_invoice_indication | DSI Duplicata de Serviço Indicação |
| digital_rural_invoice | DR Duplicata Rural |
| bill_of_exchange | LC Letra de Câmbio |
| commercial_credit_note | NCC Nota de Crédito Comercial |
| export_credit_note | NCE Nota de Crédito Exportação |
| industrial_credit_note | NCI Nota de Crédito Industrial |
| rural_credit_note | NCR Nota de Crédito Rural |
| promissory_note | NP Nota Promissória |
| rural_promissory_note | NPR Nota Promissória Rural |
| mercantile_triplicate | TM Triplicata Mercantil |
| service_triplicate | TS Triplicata de Serviço |
| insurance_note | NS Nota de Seguro |
| receipt | RC Recibo |
| printed_bank_slip | FAT Bloqueto |
| debit_note | ND Nota de Débito |
| insurance_policy | AP Apólice de Seguro |
| school_monthly_fee | ME Mensalidade Escolar |
| consortium_installment | PC Parcela de Consórcio |
| invoice | NF Nota Fiscal |
| debt_document | DD Documento de Dívida |
| rural_product_certificate | Cédula de Produto Rural |
| warrant | Warrant |
| state_active_debt | Dívida Ativa de Estado |
| municipal_active_debt | Dívida Ativa de Município |
| federal_active_debt | Dívida Ativa da União |
| condominium_charges | Encargos condominiais |
| proposal_bank_slip | Boleto proposta |
| deposit_and_contribution_bank_slip | Boleto de Depósito e Aporte |
| others | Outros |

### Objeto partial_payment_data

| Campo                             | Tipo    | Descrição                                                                 | Caracteres |
|-----------------------------------|---------|---------------------------------------------------------------------------|------------|
| `partial_payment_minimum_type` *  | string  | Tipo de valor mínimo para pagamento parcial                               | **[Enumeradores partial_payment_type](#enumeradores-partial_payment_type)** |
| `partial_payment_minimum_percentage` | float | Percentual mínimo permitido para o pagamento parcial                      | -          |
| `partial_payment_minimum_amount`  | float  | Valor mínimo permitido para o pagamento parcial                           | -          |
| `partial_payment_maximum_type`    | string  | Tipo de valor máximo para pagamento parcial                               | **[Enumeradores partial_payment_type](#enumeradores-partial_payment_type)** |
| `partial_payment_maximum_percentage` | float | Percentual máximo permitido para o pagamento parcial                      | -          |
| `partial_payment_maximum_amount`  | float  | Valor máximo permitido para o pagamento parcial                           | -          |
| `partial_payment_quantity` *      | integer | Quantidade de pagamentos parciais permitidos                              | -          |

:::caution Atenção!
De acordo com o valor enviado nos campos `partial_payment_minimum_type` e `partial_payment_maximum_type`, é necessário enviar o `partial_payment_minimum_amount` ou `partial_payment_minimum_percentage`, e o `partial_payment_maximum_amount` ou `partial_payment_maximum_percentage` correspondente.
:::

### Enumeradores partial_payment_type

| Enumerador  | Descrição                        |
|-------------|----------------------------------|
| absolute    | Valor absoluto                   |
| percentage  | Percentual                       |

### Objeto write_off_data

| Campo                     | Tipo    | Descrição                                                                   | Caracteres |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_write_off` *     | integer | Dias, após o vencimento, para que o boleto seja baixado automaticamente     | -          |

### Objeto protest_data

| Campo                     | Tipo    | Descrição                                                                   | Caracteres |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_protest` *       | integer | Dias, após o vencimento, para que o boleto seja protestado automaticamente  | -          |

### Objeto bankruptcy_protest_data

| Campo                          | Tipo    | Descrição                                                                   | Caracteres  |
|--------------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_bankruptcy_protest` * | integer | Dias, após o vencimento, para que o boleto seja protestado automaticamente  | -           |

### Objeto fine_data

Opção 1: multa em valor absoluto (`fine_type=absolute`)

| Campo                     | Tipo    | Descrição                                               | Caracteres                |
|---------------------------|---------|---------------------------------------------------------|-------------------------------------------------------------------------|
| `fine_type` *             | string  | Tipo da multa                                                       | **[Enumeradores fine_type](#enumeradores-fine_type)**                                              |
| `fine_amount` *           | float   | Valor absoluto da multa                                             | -                                                                        |
| `days_to_fine` *          | integer | Dias, após o vencimento, para que a multa seja cobrada              | -                                                                        |

Opção 2: multa em valor percentual (`fine_type=percentage`)

| Campo                     | Tipo    | Descrição                                                 | Caracteres                             |
|---------------------------|---------|-----------------------------------------------------------|---------------------------------------|
| `fine_type` *             | string  | Tipo da multa                                             | **[Enumeradores fine_type](#enumeradores-fine_type)** |
| `fine_percentage` *       | integer | Valor percentual da multa, de 1 a 100                     | -                                      |
| `days_to_fine` *          | integer | Dias, após o vencimento, para que a multa seja cobrada    | -                                      |

### Enumeradores fine_type

| Enumerador         | Descrição             |
|--------------------|-----------------------|
| absolute           | valor absoluto        |
| percentage         | valor percentual      |

### Objeto interest_data

Opção 1: juros utilizando valores absolutos (`interest_type=calendar_days_daily_amount` ou `interest_type=workdays_daily_amount`)

| Campo                     | Tipo    | Descrição                                                                     | Caracteres                                                                                      |
|---------------------------|---------|-------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| `interest_type` *         | string  | Tipo de juros       | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_amount` *       | float   | Valor a ser cobrado por unidade de tempo determinada (dias úteis ou corridos) | -                                                                                               |
| `days_to_interest` *      | integer | Dias, após o vencimento, para que comece a cobrar os juros                    | -                                                                                               |

Opção 2: juros utilizando valores percentuais (`interest_type=calendar_days_monthly_percentage`)

| Campo                    | Tipo    | Descrição                                                                             | Caracteres                                                                                          |
|--------------------------|---------|---------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
| `interest_type` *        | string  | Tipo de juros       | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_percentage` *  | integer | Porcentagem a ser cobrada por unidade de tempo determinada (dias úteis ou corridos)                                                                      | -                                                                           |
| `days_to_interest` *     | integer | Dias, após o vencimento, para que comece a cobrar os juros                             | -                                                                                                   |

### Enumeradores interest_type

| Enumerador                       | Descrição                                                            |
|----------------------------------|----------------------------------------------------------------------|
| calendar_days_daily_amount       | Valor diário sobre dias corridos                                     |
| workdays_daily_amount            | Valor diário sobre dias úteis                                        |
| calendar_days_monthly_percentage | Porcentagem de juros cobrados mensalmente, com base em dias corridos |

### Objeto discount

Opção 1: descontos utilizando valores absolutos (`discount_type in ["absolute", "anticipation_calendar_days_daily_amount", "anticipation_workdays_daily_amount"]`)

| Campo                     | Tipo    | Descrição                                           | Caracteres                                                |
|---------------------------|---------|-----------------------------------------------------|-----------------------------------------------------------|
| `discount_amount` *       | float   | Valor absoluto de desconto por unidade de tempo                                            | -                                                          |
| `discount_number` *       | integer | Número do desconto                                     | -                                                         |
| `discount_type` *         | string  | Configuração do desconto em valores absolutos                                    | **[Enumerador discount_type](#enumeradores-discount_type)** |                                                       |
| `discount_limit_date` *   | string  | Data limite para aplicação do desconto   | 10                                                        |

Opção 2: descontos utilizando valores percentuais (`discount_type in ["percentage", "anticipation_calendar_days_daily_percentage", "anticipation_workdays_daily_percentage"]`)

| Campo                     | Tipo    | Descrição                                           | Caracteres                                                |
|---------------------------|---------|-----------------------------------------------------|-----------------------------------------------------------|
| `discount_percentage` *   | float   | Valor percentual de desconto por unidade de tempo                                            | -                                                          |
| `discount_number` *       | integer | Número do desconto                                     | -                                                         |
| `discount_type` *         | string  | Configuração do desconto em valores percentuais                                    | **[Enumerador discount_type](#enumeradores-discount_type)** |                                                       |
| `discount_limit_date` *   | string  | Data limite para aplicação do desconto   | 10                                                        |

:::caution Atenção!
O boleto pode ter até três descontos, sendo que os descontos devem ser todos do mesmo tipo , isto é, devem ter o mesmo `discount_type`. Os descontos devem ser numerados de 1 a 3, de maneira crescente e começando necessariamente em 1. Ou seja, caso sejam enviados dois descontos na requisição, devem necessariamente ser numerados com 1 e 2.
:::

### Enumeradores discount_type

| Enumerador                                  | Descrição                                                                |
|---------------------------------------------|--------------------------------------------------------------------------|
| absolute                                    | Valor fixo                                                               |
| anticipation_calendar_days_daily_amount     | Valor diário de desconto de antecipação, sobre dias corridos             |
| anticipation_workdays_daily_amount          | Valor diário de desconto de antecipação, sobre dias úteis                |
| percentage                                  | Porcentagem fixa                                                         |
| anticipation_calendar_days_daily_percentage | Porcentagem mensal de desconto de antecipação, com base em dias corridos |
| anticipation_workdays_daily_percentage      | Porcentagem anual de desconto de antecipação, com base em dias úteis     |

### Objetos payer_data e guarantor_data

| Campo                     | Tipo   | Descrição                                                  | Caracteres|
|---------------------------|--------|-------------------------------------|-----------------------------------------------------------|
| `name` *                  | string | Nome completo                       | 100                                                       |
| `document_number` *       | string | Número do documento (CPF/CNPJ)      | 11 ou 14                                                  |
| `person_type` *           | string | Tipo da pessoa (física ou jurídica) | **[Enumeradores person_type](#enumeradores-person_type)** |
| `contact`                 | object | Informações de contato              | **[Objeto contact](#objeto-contact)**                     |
| `address`                 | object | Endereço                            | **[Objeto address](#objeto-address)**                     |

### Enumeradores person_type

| Enumerador         | Descrição             |
|--------------------|-----------------------|
| natural            | pessoa física         |
| legal              | pessoa jurídica       |

### Objeto contact

| Campo                     | Tipo   | Descrição                         | Caracteres                         |
|---------------------------|--------|-----------------------------------|------------------------------------|
| `email`                   | string | E-mail de contato                 | 320                                |
| `phone`                   | object | Telefone de contato               | **[Objeto phone](#objeto-phone)**  |

### Objeto phone

| Campo                           | Tipo   | Descrição                                    | Caracteres |
|---------------------------------|--------|----------------------------------------------|------------|
| `country_code` *     | string | Código DDI (Discagem Direta Internacional)   | 3          |
| `area_code` *                   | string | Código DDD (Discagem Direta à Distância)     | 2          |
| `number` *                      | string | Complemento                                  | 9          |

### Objeto address

| Campo                     | Tipo   | Descrição                                    | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `street` *                | string | Logradouro                                   | 500        |
| `number` *                | string | Número                                       | 6          |
| `complement`              | string | Complemento                                  | 500        |
| `neighborhood` *          | string | Bairro                                       | 100        |
| `postal_code` *           | string | CEP                                          | 8          |
| `city` *                  | string | Cidade                                       | 100        |
| `state` *                 | string | Estado (UF) | **[Enumerador state](#enumeradores-state)** |

### Enumeradores state

| Enumerador         | Descrição             |
|--------------------|-----------------------|
| AC                 | Acre                  |
| AL                 | Alagoas               |
| AM                 | Amazonas              |
| AP                 | Amapá                 |
| BA                 | Bahia                 |
| CE                 | Ceará                 |
| DF                 | Distrito federal      |
| ES                 | Espírito Santo        |
| GO                 | Goiás                 |
| MA                 | Maranhão              |
| MG                 | Minas Gerais          |
| MS                 | Mato Grosso do Sul    |
| MT                 | Mato Grosso           |
| PA                 | Pará                  |
| PB                 | Paraíba               |
| PE                 | Pernambuco            |
| PI                 | Piauí                 |
| PR                 | Paraná                |
| RJ                 | Rio de Janeiro        |
| RN                 | Rio Grande do Norte   |
| RO                 | Rondônia              |
| RR                 | Roraima               |
| RS                 | Rio Grande do Sul     |
| SC                 | Santa Catarina        |
| SE                 | Sergipe               |
| SP                 | São Paulo             |
| TO                 | Tocantins             |
| EX                 | Exceção               |

### Objeto notification

| Campo                     | Tipo    | Descrição                                                                               | Caracteres |
|---------------------------|---------|-----------------------------------------------------------------------------------------|------------|
| `document_number` *       | string  | Número do documento de quem receberá as notificações (CPF/CNPJ)                         | 11 ou 14   |
| `name` *                  | string  | Nome de quem receberá as notificações                                                   | 100        |
| `email`                   | string  | E-mail para o qual serão enviadas as notificações                                       | 320        |
| `phone`                   | object  | Telefone de contato para o qual serão enviadas as notificações | **[Objeto phone](#objeto-phone)**   |
| `send_2_way` *            | boolean | Enviar segunda via                                                                      | -          |
| `send_before_due_date` *  | boolean | Enviar notificação ao pagador antes da data de vencimento                               | -          |
| `send_after_due_date` *   | boolean | Enviar notificação ao pagador quando o boleto vencer                                    | -          |
| `send_on_protest` *       | boolean | Enviar notificação ao entrar em fluxo de protesto                                       | -          |

## Response

STATUS 202

Response Body

```json
{
  "bank_slips": [
    {
      "request_control_key": "c86d8902-a5ae-4d1f-8872-e6fea1268aab",
      "bank_slip_key": "053c7074-c55c-49aa-b94d-629e8d2424cf",
      "bank_slip_status": "accepted",
      "our_number": 123456789,
      "barcode": "32992995900000892814549111682910713279164650",
      "digitable_line": "32994549121168291071332791646501299590000089281",
      "qr_code_data": {
        "qr_code_key": "0a6ffa83-63ec-438f-95be-76e1ab8329e5",
        "pix_key": "78252991-d26d-4d6b-8c50-be3233ffabf7",
        "receiver_conciliation_id": "01GVGV9NXBCY287Z6CJ4S0ENW9",
        "url": "00020126830014br.gov.bcb.pix2561qrcode.qitech.app/bacen/cobv/58fd5103a8e64bbbab2fd49b0bd580145204000053039865802BR5925GONNFUNDODEINVESTIMENTOEM6012RiodeJaneiro6107226401262070503***6304EA0D",
        "image": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/wAALCAD0APQBAREA/8QAHwAAAQUBAQEBAQEAAAAAAAAAAAECAwQFBgcICQoL/8QAtRAAAgEDAwIEAwUFBAQAAAF9AQIDAAQRBRIhMUEGE1FhByJxFDKBkaEII0KxwRVS0fAkM2JyggkKFhcYGRolJicoKSo0NTY3ODk6Q0RFRkdISUpTVFVWV1hZWmNkZWZnaGlqc3R1dnd4eXqDhIWGh4iJipKTlJWWl5iZmqKjpKWmp6ipqrKztLW2t7i5usLDxMXGx8jJytLT1NXW19jZ2uHi4+Tl5ufo6erx8vP09fb3+Pn6/9oACAEBAAA/APf6KKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKKK+QPhl8Mv+Fjf2p/xN/wCz/sHlf8u3m79+/wD21xjZ79a7/wD4Zl/6m7/ym/8A22j/AIZl/wCpu/8AKb/9to/Zl/5mn/t0/wDa1egfE34Zf8LG/sv/AIm/9n/YPN/5dvN379n+2uMbPfrXgHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrR8Tfib/wsb+y/wDiUf2f9g83/l583fv2f7C4xs9+td//AMm5/wDUw/27/wBunkeR/wB/N27zvbG3vnjwCvr/AOJvxN/4Vz/Zf/Eo/tD7f5v/AC8+Vs2bP9hs53+3SvkCvf8A9mX/AJmn/t0/9rUf8m5/9TD/AG7/ANunkeR/383bvO9sbe+ePQPhl8Mv+Fc/2p/xN/7Q+3+V/wAu3lbNm/8A22znf7dK8A+GXxN/4Vz/AGp/xKP7Q+3+V/y8+Vs2b/8AYbOd/t0o+GXxN/4Vz/an/Eo/tD7f5X/Lz5WzZv8A9hs53+3Svf8A4m/DL/hY39l/8Tf+z/sHm/8ALt5u/fs/21xjZ79a8/8A+GZf+pu/8pv/ANtr0D4ZfE3/AIWN/an/ABKP7P8AsHlf8vPm79+//YXGNnv1rwD4ZfE3/hXP9qf8Sj+0Pt/lf8vPlbNm/wD2Gznf7dK7/wD4aa/6lH/ypf8A2quA+GXxN/4Vz/an/Eo/tD7f5X/Lz5WzZv8A9hs53+3Svr+vkD4ZfDL/AIWN/an/ABN/7P8AsHlf8u3m79+//bXGNnv1rv8A/hmX/qbv/Kb/APbaP+GZf+pu/wDKb/8AbaP2Zf8Amaf+3T/2tX0BRRRXz/8Asy/8zT/26f8AtavAK9//AGZf+Zp/7dP/AGtR+zL/AMzT/wBun/tavQPib8Mv+Fjf2X/xN/7P+web/wAu3m79+z/bXGNnv1rz/wDZl/5mn/t0/wDa1cB8Mvib/wAK5/tT/iUf2h9v8r/l58rZs3/7DZzv9ule/wDwy+Jv/Cxv7U/4lH9n/YPK/wCXnzd+/f8A7C4xs9+teAfE34Zf8K5/sv8A4m/9ofb/ADf+XbytmzZ/ttnO/wBule//ABN+Jv8Awrn+y/8AiUf2h9v83/l58rZs2f7DZzv9uleAfDL4Zf8ACxv7U/4m/wDZ/wBg8r/l283fv3/7a4xs9+tHxN+GX/Cuf7L/AOJv/aH2/wA3/l28rZs2f7bZzv8AbpXv/wAMvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9ulef/tNf8yt/29/+0a9A+GXxN/4WN/an/Eo/s/7B5X/Lz5u/fv8A9hcY2e/WvP8A/k3P/qYf7d/7dPI8j/v5u3ed7Y2988cB8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpXf/APDTX/Uo/wDlS/8AtVcB8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpX1/Xz//AMm5/wDUw/27/wBunkeR/wB/N27zvbG3vng/5OM/6l7+wv8At78/z/8Av3t2+T753dsc+gfDL4m/8LG/tT/iUf2f9g8r/l583fv3/wCwuMbPfrXn/wCzL/zNP/bp/wC1q8Ar3/8AZl/5mn/t0/8Aa1H7Mv8AzNP/AG6f+1q+gKKKK+f/ANmX/maf+3T/ANrUf8My/wDU3f8AlN/+216B8Mvhl/wrn+1P+Jv/AGh9v8r/AJdvK2bN/wDttnO/26V5/wDsy/8AM0/9un/taj/k4z/qXv7C/wC3vz/P/wC/e3b5Pvnd2xyf8nGf9S9/YX/b35/n/wDfvbt8n3zu7Y5P2mv+ZW/7e/8A2jR+zL/zNP8A26f+1qP+Tc/+ph/t3/t08jyP+/m7d53tjb3zx4BXv/7TX/Mrf9vf/tGj/k3P/qYf7d/7dPI8j/v5u3ed7Y2988cB8Mvhl/wsb+1P+Jv/AGf9g8r/AJdvN379/wDtrjGz3613/wDwzL/1N3/lN/8AttH7Mv8AzNP/AG6f+1q4D4m/DL/hXP8AZf8AxN/7Q+3+b/y7eVs2bP8AbbOd/t0rv/8Ahpr/AKlH/wAqX/2qj/k4z/qXv7C/7e/P8/8A797dvk++d3bHJ/ybn/1MP9u/9unkeR/383bvO9sbe+ePQPhl8Mv+Fc/2p/xN/wC0Pt/lf8u3lbNm/wD22znf7dKPib8Mv+Fjf2X/AMTf+z/sHm/8u3m79+z/AG1xjZ79a8//AGZf+Zp/7dP/AGtX0BXz/wDsy/8AM0/9un/taj/hmX/qbv8Aym//AG2vQPhl8Mv+Fc/2p/xN/wC0Pt/lf8u3lbNm/wD22znf7dK8/wD2Zf8Amaf+3T/2tX0BRRRXz/8A8My/9Td/5Tf/ALbR/wAMy/8AU3f+U3/7bR/wzL/1N3/lN/8AttegfDL4Zf8ACuf7U/4m/wDaH2/yv+Xbytmzf/ttnO/26V5//wAm5/8AUw/27/26eR5H/fzdu872xt7549A+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0rz/9mX/maf8At0/9rVwHwy+Jv/Cuf7U/4lH9ofb/ACv+Xnytmzf/ALDZzv8AbpR8Mvib/wAK5/tT/iUf2h9v8r/l58rZs3/7DZzv9ulHwy+Jv/Cuf7U/4lH9ofb/ACv+Xnytmzf/ALDZzv8AbpXf/sy/8zT/ANun/tavQPhl8Mv+Fc/2p/xN/wC0Pt/lf8u3lbNm/wD22znf7dK8/wD2Zf8Amaf+3T/2tXoHwy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpXgHwy+Jv8Awrn+1P8AiUf2h9v8r/l58rZs3/7DZzv9uld/+zL/AMzT/wBun/tavQPhl8Mv+Fc/2p/xN/7Q+3+V/wAu3lbNm/8A22znf7dK8A+GXxN/4Vz/AGp/xKP7Q+3+V/y8+Vs2b/8AYbOd/t0o+GXxN/4Vz/an/Eo/tD7f5X/Lz5WzZv8A9hs53+3Su/8A2Zf+Zp/7dP8A2tR/ybn/ANTD/bv/AG6eR5H/AH83bvO9sbe+eD9mX/maf+3T/wBrUfsy/wDM0/8Abp/7Wo/4Zl/6m7/ym/8A22j/AIZl/wCpu/8AKb/9to/4Zl/6m7/ym/8A22vQPhl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK9Aooor5/8A2Zf+Zp/7dP8A2tXAfE34m/8ACxv7L/4lH9n/AGDzf+Xnzd+/Z/sLjGz360fE34m/8LG/sv8A4lH9n/YPN/5efN379n+wuMbPfrXv/wAMvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9ulfIFFegfDL4m/8ACuf7U/4lH9ofb/K/5efK2bN/+w2c7/bpXf8A7TX/ADK3/b3/AO0a9A+GXxN/4WN/an/Eo/s/7B5X/Lz5u/fv/wBhcY2e/WvAPib8Mv8AhXP9l/8AE3/tD7f5v/Lt5WzZs/22znf7dKPib8Mv+Fc/2X/xN/7Q+3+b/wAu3lbNmz/bbOd/t0rv/wBmX/maf+3T/wBrVwHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9ulHxN+GX/Cuf7L/wCJv/aH2/zf+XbytmzZ/ttnO/26V3//AAzL/wBTd/5Tf/ttH7TX/Mrf9vf/ALRrgPhl8Tf+Fc/2p/xKP7Q+3+V/y8+Vs2b/APYbOd/t0o+Jvwy/4Vz/AGX/AMTf+0Pt/m/8u3lbNmz/AG2znf7dK7//AJOM/wCpe/sL/t78/wA//v3t2+T753dscn/Juf8A1MP9u/8Abp5Hkf8Afzdu872xt7548Ar3/wD5Nz/6mH+3f+3TyPI/7+bt3ne2NvfPHAfE34Zf8K5/sv8A4m/9ofb/ADf+XbytmzZ/ttnO/wBuld/+01/zK3/b3/7Rr6Aorz/4ZfE3/hY39qf8Sj+z/sHlf8vPm79+/wD2FxjZ79a9Aooor5A+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0o+JvxN/4WN/Zf/Eo/s/7B5v/AC8+bv37P9hcY2e/Wu//AGmv+ZW/7e//AGjXoHwy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulHwy+Jv/Cxv7U/4lH9n/YPK/5efN379/8AsLjGz3615/8A8nGf9S9/YX/b35/n/wDfvbt8n3zu7Y5+gK+QPib8Tf8AhY39l/8AEo/s/wCweb/y8+bv37P9hcY2e/Wvf/hl8Tf+Fjf2p/xKP7P+weV/y8+bv37/APYXGNnv1rz/AP4aa/6lH/ypf/aq9A+Jvwy/4WN/Zf8AxN/7P+web/y7ebv37P8AbXGNnv1r0CvkD4m/DL/hXP8AZf8AxN/7Q+3+b/y7eVs2bP8AbbOd/t0rv/8Ahpr/AKlH/wAqX/2qj/hmX/qbv/Kb/wDbaP8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPHoHxN+Jv8Awrn+y/8AiUf2h9v83/l58rZs2f7DZzv9ulHwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpXn/AO01/wAyt/29/wDtGj/hpr/qUf8Aypf/AGqj/k4z/qXv7C/7e/P8/wD797dvk++d3bHJ/wANNf8AUo/+VL/7VXAfE34Zf8K5/sv/AIm/9ofb/N/5dvK2bNn+22c7/bpR8Mvib/wrn+1P+JR/aH2/yv8Al58rZs3/AOw2c7/bpR8Mvhl/wsb+1P8Aib/2f9g8r/l283fv3/7a4xs9+tHwy+Jv/Cuf7U/4lH9ofb/K/wCXnytmzf8A7DZzv9ulfX9FFFFfP/8AwzL/ANTd/wCU3/7bXoHwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpXgHwy+GX/Cxv7U/4m/9n/YPK/5dvN379/8AtrjGz3613/8AwzL/ANTd/wCU3/7bR/w01/1KP/lS/wDtVegfDL4Zf8K5/tT/AIm/9ofb/K/5dvK2bN/+22c7/bpR8Mvib/wsb+1P+JR/Z/2Dyv8Al583fv3/AOwuMbPfrR8Mvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9uleAfE34Zf8ACuf7L/4m/wDaH2/zf+XbytmzZ/ttnO/26V3/AO01/wAyt/29/wDtGuA+GXwy/wCFjf2p/wATf+z/ALB5X/Lt5u/fv/21xjZ79a9/+Jvwy/4WN/Zf/E3/ALP+web/AMu3m79+z/bXGNnv1rwD4m/DL/hXP9l/8Tf+0Pt/m/8ALt5WzZs/22znf7dK9/8Aib8Tf+Fc/wBl/wDEo/tD7f5v/Lz5WzZs/wBhs53+3SvP/wBpr/mVv+3v/wBo0f8AJuf/AFMP9u/9unkeR/383bvO9sbe+eD9mX/maf8At0/9rV4BXoHwy+Jv/Cuf7U/4lH9ofb/K/wCXnytmzf8A7DZzv9uld/8A8m5/9TD/AG7/ANunkeR/383bvO9sbe+eOA+GXxN/4Vz/AGp/xKP7Q+3+V/y8+Vs2b/8AYbOd/t0rv/8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPHoHxN+GX/Cxv7L/wCJv/Z/2Dzf+Xbzd+/Z/trjGz3614B8Mvib/wAK5/tT/iUf2h9v8r/l58rZs3/7DZzv9ule/wDxN+Jv/Cuf7L/4lH9ofb/N/wCXnytmzZ/sNnO/26UfE34m/wDCuf7L/wCJR/aH2/zf+XnytmzZ/sNnO/26V5/+zL/zNP8A26f+1q+gKKKK+f8A/k3P/qYf7d/7dPI8j/v5u3ed7Y2988H/ACbn/wBTD/bv/bp5Hkf9/N27zvbG3vnjgPib8Mv+Fc/2X/xN/wC0Pt/m/wDLt5WzZs/22znf7dK9/wDhl8Mv+Fc/2p/xN/7Q+3+V/wAu3lbNm/8A22znf7dKPib8Mv8AhY39l/8AE3/s/wCweb/y7ebv37P9tcY2e/WvAPib8Mv+Fc/2X/xN/wC0Pt/m/wDLt5WzZs/22znf7dK8/r3/APaa/wCZW/7e/wD2jXAfDL4m/wDCuf7U/wCJR/aH2/yv+Xnytmzf/sNnO/26V7/8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXn//AA01/wBSj/5Uv/tVegfE34m/8K5/sv8A4lH9ofb/ADf+XnytmzZ/sNnO/wBulHxN+Jv/AArn+y/+JR/aH2/zf+XnytmzZ/sNnO/26V5/+01/zK3/AG9/+0aP2Zf+Zp/7dP8A2tR+zL/zNP8A26f+1qP+TjP+pe/sL/t78/z/APv3t2+T753dsc+AV7/+zL/zNP8A26f+1q9A+GXwy/4Vz/an/E3/ALQ+3+V/y7eVs2b/APbbOd/t0rwD4ZfDL/hY39qf8Tf+z/sHlf8ALt5u/fv/ANtcY2e/Wvf/AIm/E3/hXP8AZf8AxKP7Q+3+b/y8+Vs2bP8AYbOd/t0rwD4m/DL/AIVz/Zf/ABN/7Q+3+b/y7eVs2bP9ts53+3Su/wD2mv8AmVv+3v8A9o1wHwy+Jv8Awrn+1P8AiUf2h9v8r/l58rZs3/7DZzv9ulHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9ule/8Awy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpXoFFFFfIHwy+GX/Cxv7U/4m/8AZ/2Dyv8Al283fv3/AO2uMbPfrXf/APDMv/U3f+U3/wC20f8AJxn/AFL39hf9vfn+f/3727fJ987u2OfQPhl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK8//wCGmv8AqUf/ACpf/aq8Ar3/AP4aa/6lH/ypf/aq9A+GXwy/4Vz/AGp/xN/7Q+3+V/y7eVs2b/8AbbOd/t0rwD4m/DL/AIVz/Zf/ABN/7Q+3+b/y7eVs2bP9ts53+3Svf/ib8Mv+Fjf2X/xN/wCz/sHm/wDLt5u/fs/21xjZ79a8/wD+TjP+pe/sL/t78/z/APv3t2+T753dsc+gfDL4m/8ACxv7U/4lH9n/AGDyv+Xnzd+/f/sLjGz360fDL4Zf8K5/tT/ib/2h9v8AK/5dvK2bN/8AttnO/wBulef/APJxn/Uvf2F/29+f5/8A3727fJ987u2OT/hpr/qUf/Kl/wDaqP2mv+ZW/wC3v/2jR+zL/wAzT/26f+1q8Ar3/wD4Zl/6m7/ym/8A22vQPhl8Tf8AhY39qf8AEo/s/wCweV/y8+bv37/9hcY2e/Wj4m/E3/hXP9l/8Sj+0Pt/m/8ALz5WzZs/2Gznf7dKPib8Mv8AhY39l/8AE3/s/wCweb/y7ebv37P9tcY2e/Wj4ZfE3/hY39qf8Sj+z/sHlf8ALz5u/fv/ANhcY2e/Wj4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3SvQK+f/wDk4z/qXv7C/wC3vz/P/wC/e3b5Pvnd2xz9AUUUUV5/8Mvhl/wrn+1P+Jv/AGh9v8r/AJdvK2bN/wDttnO/26V5/wD8m5/9TD/bv/bp5Hkf9/N27zvbG3vnjwCvQPib8Mv+Fc/2X/xN/wC0Pt/m/wDLt5WzZs/22znf7dK7/wD5Nz/6mH+3f+3TyPI/7+bt3ne2NvfPHAfDL4m/8K5/tT/iUf2h9v8AK/5efK2bN/8AsNnO/wBulHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrXf8A7TX/ADK3/b3/AO0a4D4m/DL/AIVz/Zf/ABN/7Q+3+b/y7eVs2bP9ts53+3Sj4ZfDL/hY39qf8Tf+z/sHlf8ALt5u/fv/ANtcY2e/Wu//AGmv+ZW/7e//AGjXoHxN+GX/AAsb+y/+Jv8A2f8AYPN/5dvN379n+2uMbPfrXoFfIHwy+Jv/AArn+1P+JR/aH2/yv+Xnytmzf/sNnO/26UfDL4Zf8LG/tT/ib/2f9g8r/l283fv3/wC2uMbPfrXf/wDDTX/Uo/8AlS/+1Ufsy/8AM0/9un/tavAK9A+GXwy/4WN/an/E3/s/7B5X/Lt5u/fv/wBtcY2e/Wu//wCGmv8AqUf/ACpf/aq4D4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Su//wCTjP8AqXv7C/7e/P8AP/797dvk++d3bHPoHxN+Jv8Awrn+y/8AiUf2h9v83/l58rZs2f7DZzv9ulHxN+Jv/Cuf7L/4lH9ofb/N/wCXnytmzZ/sNnO/26UfDL4m/wDCxv7U/wCJR/Z/2Dyv+Xnzd+/f/sLjGz360fE34m/8K5/sv/iUf2h9v83/AJefK2bNn+w2c7/bpR8Mvib/AMLG/tT/AIlH9n/YPK/5efN379/+wuMbPfrXoFFFFfIHwy+Jv/Cuf7U/4lH9ofb/ACv+Xnytmzf/ALDZzv8AbpX1/XwBXoHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9ule/8Awy+Jv/Cxv7U/4lH9n/YPK/5efN379/8AsLjGz360fE34m/8ACuf7L/4lH9ofb/N/5efK2bNn+w2c7/bpR8Mvhl/wrn+1P+Jv/aH2/wAr/l28rZs3/wC22c7/AG6V5/8Asy/8zT/26f8AtauA+JvxN/4WN/Zf/Eo/s/7B5v8Ay8+bv37P9hcY2e/Wvf8A4m/E3/hXP9l/8Sj+0Pt/m/8ALz5WzZs/2Gznf7dK8A+JvxN/4WN/Zf8AxKP7P+web/y8+bv37P8AYXGNnv1r3/4m/E3/AIVz/Zf/ABKP7Q+3+b/y8+Vs2bP9hs53+3SvP/8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPB/w01/1KP/AJUv/tVegfE34m/8K5/sv/iUf2h9v83/AJefK2bNn+w2c7/bpXn/AO01/wAyt/29/wDtGj/hpr/qUf8Aypf/AGqvoCvkD4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Svf/ib8Tf8AhXP9l/8AEo/tD7f5v/Lz5WzZs/2Gznf7dK8//wCGZf8Aqbv/ACm//baP2mv+ZW/7e/8A2jR/ybn/ANTD/bv/AG6eR5H/AH83bvO9sbe+ePQPib8Tf+Fc/wBl/wDEo/tD7f5v/Lz5WzZs/wBhs53+3SvAPhl8Tf8AhXP9qf8AEo/tD7f5X/Lz5WzZv/2Gznf7dK9/+GXxN/4WN/an/Eo/s/7B5X/Lz5u/fv8A9hcY2e/Wj4ZfE3/hY39qf8Sj+z/sHlf8vPm79+//AGFxjZ79a9Aoooor5/8A2Zf+Zp/7dP8A2tR/wzL/ANTd/wCU3/7bR/ybn/1MP9u/9unkeR/383bvO9sbe+ePQPib8Tf+Fc/2X/xKP7Q+3+b/AMvPlbNmz/YbOd/t0o+JvxN/4Vz/AGX/AMSj+0Pt/m/8vPlbNmz/AGGznf7dK8A+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0r3/4m/DL/hY39l/8Tf8As/7B5v8Ay7ebv37P9tcY2e/Wj4m/E3/hXP8AZf8AxKP7Q+3+b/y8+Vs2bP8AYbOd/t0r5Ar0D4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Su//wCGmv8AqUf/ACpf/aq4D4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Su//aa/5lb/ALe//aNcB8Mvhl/wsb+1P+Jv/Z/2Dyv+Xbzd+/f/ALa4xs9+tHxN+Jv/AAsb+y/+JR/Z/wBg83/l583fv2f7C4xs9+te/wDwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpXgHwy+GX/Cxv7U/4m/9n/YPK/5dvN379/8AtrjGz360fE34Zf8ACuf7L/4m/wDaH2/zf+XbytmzZ/ttnO/26V5/Xv8A+01/zK3/AG9/+0a4D4ZfDL/hY39qf8Tf+z/sHlf8u3m79+//AG1xjZ79a9/+GXxN/wCFjf2p/wASj+z/ALB5X/Lz5u/fv/2FxjZ79aPhl8Mv+Fc/2p/xN/7Q+3+V/wAu3lbNm/8A22znf7dK+QK9/wD2Zf8Amaf+3T/2tX0BRRRRXyB8Tfhl/wAK5/sv/ib/ANofb/N/5dvK2bNn+22c7/bpXf8A/DTX/Uo/+VL/AO1VwHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrXf8A/DMv/U3f+U3/AO21wHwy+Jv/AArn+1P+JR/aH2/yv+Xnytmzf/sNnO/26UfDL4m/8K5/tT/iUf2h9v8AK/5efK2bN/8AsNnO/wBule//ABN+Jv8Awrn+y/8AiUf2h9v83/l58rZs2f7DZzv9uleAfE34m/8ACxv7L/4lH9n/AGDzf+Xnzd+/Z/sLjGz3615/XoHxN+Jv/Cxv7L/4lH9n/YPN/wCXnzd+/Z/sLjGz3613/wC01/zK3/b3/wC0a9A+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0rwD4ZfDL/hY39qf8Tf8As/7B5X/Lt5u/fv8A9tcY2e/Wu/8A+GZf+pu/8pv/ANtrgPhl8Mv+Fjf2p/xN/wCz/sHlf8u3m79+/wD21xjZ79a8/r0D4ZfDL/hY39qf8Tf+z/sHlf8ALt5u/fv/ANtcY2e/Wj4m/E3/AIWN/Zf/ABKP7P8AsHm/8vPm79+z/YXGNnv1rv8A/hpr/qUf/Kl/9qr0D4m/DL/hY39l/wDE3/s/7B5v/Lt5u/fs/wBtcY2e/WvP/wBmX/maf+3T/wBrV6B8Mvib/wALG/tT/iUf2f8AYPK/5efN379/+wuMbPfrXgHwy+GX/Cxv7U/4m/8AZ/2Dyv8Al283fv3/AO2uMbPfrXf/APDMv/U3f+U3/wC20fsy/wDM0/8Abp/7WrgPib8Mv+Fc/wBl/wDE3/tD7f5v/Lt5WzZs/wBts53+3Svf/hl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK9Aooorz/4m/DL/AIWN/Zf/ABN/7P8AsHm/8u3m79+z/bXGNnv1rwD4ZfE3/hXP9qf8Sj+0Pt/lf8vPlbNm/wD2Gznf7dK7/wDZl/5mn/t0/wDa1egfDL4Zf8K5/tT/AIm/9ofb/K/5dvK2bN/+22c7/bpXgHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrR8Tfhl/wrn+y/wDib/2h9v8AN/5dvK2bNn+22c7/AG6V3/7TX/Mrf9vf/tGuA+GXxN/4Vz/an/Eo/tD7f5X/AC8+Vs2b/wDYbOd/t0o+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0r6/rz/4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3Sj4ZfDL/hXP9qf8Tf+0Pt/lf8ALt5WzZv/ANts53+3SvP/ANmX/maf+3T/ANrV6B8Mvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9uleAfDL4m/8ACuf7U/4lH9ofb/K/5efK2bN/+w2c7/bpX1/RRXyB8Tfib/wsb+y/+JR/Z/2Dzf8Al583fv2f7C4xs9+td/8A8m5/9TD/AG7/ANunkeR/383bvO9sbe+ePAK+v/ib8Tf+Fc/2X/xKP7Q+3+b/AMvPlbNmz/YbOd/t0rz/APZl/wCZp/7dP/a1egfDL4Zf8K5/tT/ib/2h9v8AK/5dvK2bN/8AttnO/wBuleAfDL4m/wDCuf7U/wCJR/aH2/yv+Xnytmzf/sNnO/26V7/8Tfhl/wALG/sv/ib/ANn/AGDzf+Xbzd+/Z/trjGz3615/+zL/AMzT/wBun/tavoCiiivP/ib8Tf8AhXP9l/8AEo/tD7f5v/Lz5WzZs/2Gznf7dK8//wCTc/8AqYf7d/7dPI8j/v5u3ed7Y2988H/DMv8A1N3/AJTf/ttH/DMv/U3f+U3/AO214BXv/wDwzL/1N3/lN/8AttH/AA01/wBSj/5Uv/tVH/DMv/U3f+U3/wC214BXoHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrXf8A7Mv/ADNP/bp/7Wr0D4ZfE3/hY39qf8Sj+z/sHlf8vPm79+//AGFxjZ79a8//AOGZf+pu/wDKb/8Aba4D4ZfDL/hY39qf8Tf+z/sHlf8ALt5u/fv/ANtcY2e/Wj4ZfDL/AIWN/an/ABN/7P8AsHlf8u3m79+//bXGNnv1r3/4m/DL/hY39l/8Tf8As/7B5v8Ay7ebv37P9tcY2e/WvP8A9mX/AJmn/t0/9rV9AV8//wDDMv8A1N3/AJTf/ttH/Jxn/Uvf2F/29+f5/wD3727fJ987u2OfQPib8Mv+Fjf2X/xN/wCz/sHm/wDLt5u/fs/21xjZ79a9Ar5A+Jvwy/4Vz/Zf/E3/ALQ+3+b/AMu3lbNmz/bbOd/t0o+Jvwy/4Vz/AGX/AMTf+0Pt/m/8u3lbNmz/AG2znf7dK9/+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0rz//AJOM/wCpe/sL/t78/wA//v3t2+T753dscn7Mv/M0/wDbp/7Wr6Aooorz/wCGXwy/4Vz/AGp/xN/7Q+3+V/y7eVs2b/8AbbOd/t0rz/8A4Zl/6m7/AMpv/wBto/Zl/wCZp/7dP/a1H/Juf/Uw/wBu/wDbp5Hkf9/N27zvbG3vng/Zl/5mn/t0/wDa1H/Juf8A1MP9u/8Abp5Hkf8Afzdu872xt7544D4ZfDL/AIWN/an/ABN/7P8AsHlf8u3m79+//bXGNnv1o+GXwy/4WN/an/E3/s/7B5X/AC7ebv37/wDbXGNnv1o+JvxN/wCFjf2X/wASj+z/ALB5v/Lz5u/fs/2FxjZ79aPhl8Mv+Fjf2p/xN/7P+weV/wAu3m79+/8A21xjZ79a7/8A5OM/6l7+wv8At78/z/8Av3t2+T753dsc8B8Mvib/AMK5/tT/AIlH9ofb/K/5efK2bN/+w2c7/bpXv/xN+GX/AAsb+y/+Jv8A2f8AYPN/5dvN379n+2uMbPfrXn//AA01/wBSj/5Uv/tVegfDL4m/8LG/tT/iUf2f9g8r/l583fv3/wCwuMbPfrXn/wCzL/zNP/bp/wC1q4D4ZfE3/hXP9qf8Sj+0Pt/lf8vPlbNm/wD2Gznf7dKPib8Mv+Fc/wBl/wDE3/tD7f5v/Lt5WzZs/wBts53+3Su//Zl/5mn/ALdP/a1fQFef/E34Zf8ACxv7L/4m/wDZ/wBg83/l283fv2f7a4xs9+tef/8ADTX/AFKP/lS/+1VwHxN+GX/Cuf7L/wCJv/aH2/zf+XbytmzZ/ttnO/26V5/Xv/8AwzL/ANTd/wCU3/7bR/ybn/1MP9u/9unkeR/383bvO9sbe+eD9mX/AJmn/t0/9rV9AUUUV8AUV7//AMnGf9S9/YX/AG9+f5//AH727fJ987u2OfQPhl8Mv+Fc/wBqf8Tf+0Pt/lf8u3lbNm//AG2znf7dK8A+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0rv8A9pr/AJlb/t7/APaNH/DMv/U3f+U3/wC20f8ADMv/AFN3/lN/+216B8Mvhl/wrn+1P+Jv/aH2/wAr/l28rZs3/wC22c7/AG6V5/8A8nGf9S9/YX/b35/n/wDfvbt8n3zu7Y59A+Jvwy/4WN/Zf/E3/s/7B5v/AC7ebv37P9tcY2e/WvQK+QPib8Tf+Fjf2X/xKP7P+web/wAvPm79+z/YXGNnv1o+Jvwy/wCFc/2X/wATf+0Pt/m/8u3lbNmz/bbOd/t0r3/4m/DL/hY39l/8Tf8As/7B5v8Ay7ebv37P9tcY2e/Wj4ZfE3/hY39qf8Sj+z/sHlf8vPm79+//AGFxjZ79a8//AOTjP+pe/sL/ALe/P8//AL97dvk++d3bHPoHxN+Jv/Cuf7L/AOJR/aH2/wA3/l58rZs2f7DZzv8AbpR8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXgHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9uld/8A8My/9Td/5Tf/ALbXoHxN+Jv/AArn+y/+JR/aH2/zf+XnytmzZ/sNnO/26V5/+zL/AMzT/wBun/taj/k3P/qYf7d/7dPI8j/v5u3ed7Y2988fQFfP/wDybn/1MP8Abv8A26eR5H/fzdu872xt754+gKKKKK+AK+v/AIZfE3/hY39qf8Sj+z/sHlf8vPm79+//AGFxjZ79aPhl8Tf+Fjf2p/xKP7P+weV/y8+bv37/APYXGNnv1rwD4m/DL/hXP9l/8Tf+0Pt/m/8ALt5WzZs/22znf7dK9/8Ahl8Mv+Fc/wBqf8Tf+0Pt/lf8u3lbNm//AG2znf7dK8//AOGZf+pu/wDKb/8Aba8Ar6/+Jvwy/wCFjf2X/wATf+z/ALB5v/Lt5u/fs/21xjZ79aPib8Mv+Fjf2X/xN/7P+web/wAu3m79+z/bXGNnv1rz/wD4Zl/6m7/ym/8A22j/AJNz/wCph/t3/t08jyP+/m7d53tjb3zx6B8Mvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9ulHwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpXgHwy+Jv/Cuf7U/4lH9ofb/ACv+Xnytmzf/ALDZzv8AbpXv/wAMvib/AMLG/tT/AIlH9n/YPK/5efN379/+wuMbPfrXgHxN+GX/AArn+y/+Jv8A2h9v83/l28rZs2f7bZzv9uld/wD8NNf9Sj/5Uv8A7VX0BXyB8Mvhl/wsb+1P+Jv/AGf9g8r/AJdvN379/wDtrjGz3619f18//wDDTX/Uo/8AlS/+1V6B8Tfhl/wsb+y/+Jv/AGf9g83/AJdvN379n+2uMbPfrR8Mvib/AMLG/tT/AIlH9n/YPK/5efN379/+wuMbPfrR8Mvib/wsb+1P+JR/Z/2Dyv8Al583fv3/AOwuMbPfrR8Tfhl/wsb+y/8Aib/2f9g83/l283fv2f7a4xs9+tef/sy/8zT/ANun/taj9mX/AJmn/t0/9rV9AUUUV8//ALTX/Mrf9vf/ALRo/wCGZf8Aqbv/ACm//ba+gK+f/wDk3P8A6mH+3f8At08jyP8Av5u3ed7Y2988eAUV7/8A8NNf9Sj/AOVL/wC1Uf8AJuf/AFMP9u/9unkeR/383bvO9sbe+ePQPib8Mv8AhY39l/8AE3/s/wCweb/y7ebv37P9tcY2e/WvP/8Ak4z/AKl7+wv+3vz/AD/+/e3b5Pvnd2xzwHwy+Jv/AArn+1P+JR/aH2/yv+Xnytmzf/sNnO/26UfDL4Zf8LG/tT/ib/2f9g8r/l283fv3/wC2uMbPfrXv/wATfib/AMK5/sv/AIlH9ofb/N/5efK2bNn+w2c7/bpXn/7Mv/M0/wDbp/7Wr0D4ZfDL/hXP9qf8Tf8AtD7f5X/Lt5WzZv8A9ts53+3Sj4ZfDL/hXP8Aan/E3/tD7f5X/Lt5WzZv/wBts53+3SvAPib8Mv8AhXP9l/8AE3/tD7f5v/Lt5WzZs/22znf7dKPhl8Mv+Fjf2p/xN/7P+weV/wAu3m79+/8A21xjZ79a7/8AZl/5mn/t0/8Aa1cB8Mvib/wrn+1P+JR/aH2/yv8Al58rZs3/AOw2c7/bpR8Mvib/AMK5/tT/AIlH9ofb/K/5efK2bN/+w2c7/bpXf/8AJuf/AFMP9u/9unkeR/383bvO9sbe+eOA+Jvwy/4Vz/Zf/E3/ALQ+3+b/AMu3lbNmz/bbOd/t0o+GXxN/4Vz/AGp/xKP7Q+3+V/y8+Vs2b/8AYbOd/t0rv/8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPB/w01/1KP/AJUv/tVegfDL4m/8LG/tT/iUf2f9g8r/AJefN379/wDsLjGz3616BRRRRXyB8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpR8Mvib/AMK5/tT/AIlH9ofb/K/5efK2bN/+w2c7/bpXv/wy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulHxN+GX/Cxv7L/AOJv/Z/2Dzf+Xbzd+/Z/trjGz3615/8A8My/9Td/5Tf/ALbXoHxN+Jv/AArn+y/+JR/aH2/zf+XnytmzZ/sNnO/26V4B8Mvhl/wsb+1P+Jv/AGf9g8r/AJdvN379/wDtrjGz3617/wDDL4m/8LG/tT/iUf2f9g8r/l583fv3/wCwuMbPfrXgHxN+Jv8Awsb+y/8AiUf2f9g83/l583fv2f7C4xs9+te//DL4m/8ACxv7U/4lH9n/AGDyv+Xnzd+/f/sLjGz3614B8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpXv/AMTfhl/wsb+y/wDib/2f9g83/l283fv2f7a4xs9+tegV5/8AE34Zf8LG/sv/AIm/9n/YPN/5dvN379n+2uMbPfrR8Tfib/wrn+y/+JR/aH2/zf8Al58rZs2f7DZzv9ulef8A/Jxn/Uvf2F/29+f5/wD3727fJ987u2OfAK9A+GXxN/4Vz/an/Eo/tD7f5X/Lz5WzZv8A9hs53+3Svf8A4m/E3/hXP9l/8Sj+0Pt/m/8ALz5WzZs/2Gznf7dKPhl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK9Ar5A+JvxN/wCFjf2X/wASj+z/ALB5v/Lz5u/fs/2FxjZ79aPhl8Mv+Fjf2p/xN/7P+weV/wAu3m79+/8A21xjZ79a9/8Aib8Tf+Fc/wBl/wDEo/tD7f5v/Lz5WzZs/wBhs53+3SvQK8/+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0r0CiiivkD4ZfE3/hXP8Aan/Eo/tD7f5X/Lz5WzZv/wBhs53+3Su//wCGZf8Aqbv/ACm//ba+gK8/+GXwy/4Vz/an/E3/ALQ+3+V/y7eVs2b/APbbOd/t0rz/AP4Zl/6m7/ym/wD22vQPib8Tf+Fc/wBl/wDEo/tD7f5v/Lz5WzZs/wBhs53+3SvQK8/+Jvwy/wCFjf2X/wATf+z/ALB5v/Lt5u/fs/21xjZ79a8//Zl/5mn/ALdP/a1cB8Tfib/wsb+y/wDiUf2f9g83/l583fv2f7C4xs9+te//AAy+GX/Cuf7U/wCJv/aH2/yv+Xbytmzf/ttnO/26UfE34m/8K5/sv/iUf2h9v83/AJefK2bNn+w2c7/bpR8Tfhl/wsb+y/8Aib/2f9g83/l283fv2f7a4xs9+tef/wDJuf8A1MP9u/8Abp5Hkf8Afzdu872xt754P+TjP+pe/sL/ALe/P8//AL97dvk++d3bHPoHwy+GX/Cuf7U/4m/9ofb/ACv+Xbytmzf/ALbZzv8AbpR8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXn//AAzL/wBTd/5Tf/tteAUV9f8AxN+Jv/Cuf7L/AOJR/aH2/wA3/l58rZs2f7DZzv8AbpXgHxN+Jv8Awsb+y/8AiUf2f9g83/l583fv2f7C4xs9+tfX9FfIHwy+Jv8Awrn+1P8AiUf2h9v8r/l58rZs3/7DZzv9ulHwy+Jv/Cuf7U/4lH9ofb/K/wCXnytmzf8A7DZzv9ule/8Awy+Jv/Cxv7U/4lH9n/YPK/5efN379/8AsLjGz3616BRRRXyB8Tfhl/wrn+y/+Jv/AGh9v83/AJdvK2bNn+22c7/bpXf/APJxn/Uvf2F/29+f5/8A3727fJ987u2OT/hmX/qbv/Kb/wDbaP8Ak3P/AKmH+3f+3TyPI/7+bt3ne2NvfPB/wzL/ANTd/wCU3/7bR+01/wAyt/29/wDtGj9mX/maf+3T/wBrV6B8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXn//AAzL/wBTd/5Tf/ttH/Juf/Uw/wBu/wDbp5Hkf9/N27zvbG3vnjgPhl8Mv+Fjf2p/xN/7P+weV/y7ebv37/8AbXGNnv1r3/4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3SvP/2Zf+Zp/wC3T/2tXoHxN+GX/Cxv7L/4m/8AZ/2Dzf8Al283fv2f7a4xs9+tef8A/Jxn/Uvf2F/29+f5/wD3727fJ987u2OfQPib8Mv+Fjf2X/xN/wCz/sHm/wDLt5u/fs/21xjZ79a8/wD+Gmv+pR/8qX/2quA+JvxN/wCFjf2X/wASj+z/ALB5v/Lz5u/fs/2FxjZ79a9/+Jvwy/4WN/Zf/E3/ALP+web/AMu3m79+z/bXGNnv1rwD4m/DL/hXP9l/8Tf+0Pt/m/8ALt5WzZs/22znf7dKPib8Mv8AhXP9l/8AE3/tD7f5v/Lt5WzZs/22znf7dK9/+JvxN/4Vz/Zf/Eo/tD7f5v8Ay8+Vs2bP9hs53+3SvP8A9pr/AJlb/t7/APaNH/Juf/Uw/wBu/wDbp5Hkf9/N27zvbG3vng/Zl/5mn/t0/wDa1eAV7/8Asy/8zT/26f8AtavoCiiiivP/AIm/DL/hY39l/wDE3/s/7B5v/Lt5u/fs/wBtcY2e/WvQK8/+GXwy/wCFc/2p/wATf+0Pt/lf8u3lbNm//bbOd/t0o+GXxN/4WN/an/Eo/s/7B5X/AC8+bv37/wDYXGNnv1o+Jvwy/wCFjf2X/wATf+z/ALB5v/Lt5u/fs/21xjZ79a8//aa/5lb/ALe//aNH/Jxn/Uvf2F/29+f5/wD3727fJ987u2OfAK9//wCTjP8AqXv7C/7e/P8AP/797dvk++d3bHJ/w01/1KP/AJUv/tVH/DMv/U3f+U3/AO21wHwy+GX/AAsb+1P+Jv8A2f8AYPK/5dvN379/+2uMbPfrXf8A/DMv/U3f+U3/AO214BXv/wC01/zK3/b3/wC0aP8Ak4z/AKl7+wv+3vz/AD/+/e3b5Pvnd2xyftNf8yt/29/+0a4D4ZfE3/hXP9qf8Sj+0Pt/lf8ALz5WzZv/ANhs53+3Svf/AIZfDL/hXP8Aan/E3/tD7f5X/Lt5WzZv/wBts53+3SvAPhl8Mv8AhY39qf8AE3/s/wCweV/y7ebv37/9tcY2e/Wu/wD+Tc/+ph/t3/t08jyP+/m7d53tjb3zxwHwy+GX/Cxv7U/4m/8AZ/2Dyv8Al283fv3/AO2uMbPfrXf/APDMv/U3f+U3/wC21wHwy+Jv/Cuf7U/4lH9ofb/K/wCXnytmzf8A7DZzv9ule/8AxN+Jv/Cuf7L/AOJR/aH2/wA3/l58rZs2f7DZzv8AbpR8Mvib/wALG/tT/iUf2f8AYPK/5efN379/+wuMbPfrXoFFFFfIHwy+GX/Cxv7U/wCJv/Z/2Dyv+Xbzd+/f/trjGz3613//AAzL/wBTd/5Tf/ttH/DMv/U3f+U3/wC20fsy/wDM0/8Abp/7Wo/5OM/6l7+wv+3vz/P/AO/e3b5Pvnd2xyf8NNf9Sj/5Uv8A7VXAfDL4m/8ACuf7U/4lH9ofb/K/5efK2bN/+w2c7/bpR8Mvhl/wsb+1P+Jv/Z/2Dyv+Xbzd+/f/ALa4xs9+td//AMNNf9Sj/wCVL/7VR/ybn/1MP9u/9unkeR/383bvO9sbe+ePAK9//Zl/5mn/ALdP/a1H7Mv/ADNP/bp/7Wr0D4ZfDL/hXP8Aan/E3/tD7f5X/Lt5WzZv/wBts53+3SvAPhl8Mv8AhY39qf8AE3/s/wCweV/y7ebv37/9tcY2e/WvP69//Zl/5mn/ALdP/a1H7Mv/ADNP/bp/7Wo/aa/5lb/t7/8AaNegfDL4m/8ACxv7U/4lH9n/AGDyv+Xnzd+/f/sLjGz3615/+zL/AMzT/wBun/taj/k3P/qYf7d/7dPI8j/v5u3ed7Y2988H7Mv/ADNP/bp/7Wr0D4ZfDL/hXP8Aan/E3/tD7f5X/Lt5WzZv/wBts53+3SvkCvQPhl8Mv+Fjf2p/xN/7P+weV/y7ebv37/8AbXGNnv1r3/4ZfE3/AIWN/an/ABKP7P8AsHlf8vPm79+//YXGNnv1r0Ciiivn/wDZl/5mn/t0/wDa1eAV7/8Asy/8zT/26f8Ataj9mX/maf8At0/9rUf8nGf9S9/YX/b35/n/APfvbt8n3zu7Y59A+GXxN/4WN/an/Eo/s/7B5X/Lz5u/fv8A9hcY2e/WvP8A/hpr/qUf/Kl/9qrgPhl8Mv8AhY39qf8AE3/s/wCweV/y7ebv37/9tcY2e/WvP6+v/hl8Mv8AhXP9qf8AE3/tD7f5X/Lt5WzZv/22znf7dK8//aa/5lb/ALe//aNegfDL4m/8LG/tT/iUf2f9g8r/AJefN379/wDsLjGz3615/wD8My/9Td/5Tf8A7bR/wzL/ANTd/wCU3/7bXAfDL4Zf8LG/tT/ib/2f9g8r/l283fv3/wC2uMbPfrXv/wATfhl/wsb+y/8Aib/2f9g83/l283fv2f7a4xs9+tHwy+Jv/Cxv7U/4lH9n/YPK/wCXnzd+/f8A7C4xs9+tef8A/Juf/Uw/27/26eR5H/fzdu872xt7544D4m/DL/hXP9l/8Tf+0Pt/m/8ALt5WzZs/22znf7dK7/8A5Nz/AOph/t3/ALdPI8j/AL+bt3ne2NvfPHAfDL4m/wDCuf7U/wCJR/aH2/yv+Xnytmzf/sNnO/26V7/8Mvhl/wAK5/tT/ib/ANofb/K/5dvK2bN/+22c7/bpXgHxN+GX/Cuf7L/4m/8AaH2/zf8Al28rZs2f7bZzv9ulef0V9f8Awy+Jv/Cxv7U/4lH9n/YPK/5efN379/8AsLjGz3615/8Asy/8zT/26f8AtavoCiiivn/9mX/maf8At0/9rUf8My/9Td/5Tf8A7bXoHwy+GX/Cuf7U/wCJv/aH2/yv+Xbytmzf/ttnO/26V5/+zL/zNP8A26f+1q9A+Jvwy/4WN/Zf/E3/ALP+web/AMu3m79+z/bXGNnv1r0CvgCvr/4m/DL/AIWN/Zf/ABN/7P8AsHm/8u3m79+z/bXGNnv1o+JvxN/4Vz/Zf/Eo/tD7f5v/AC8+Vs2bP9hs53+3Sj4ZfDL/AIVz/an/ABN/7Q+3+V/y7eVs2b/9ts53+3SvP/2mv+ZW/wC3v/2jR/wzL/1N3/lN/wDttcB8Mvib/wAK5/tT/iUf2h9v8r/l58rZs3/7DZzv9ule/wDwy+GX/Cuf7U/4m/8AaH2/yv8Al28rZs3/AO22c7/bpR8Tfib/AMK5/sv/AIlH9ofb/N/5efK2bNn+w2c7/bpR8Tfhl/wsb+y/+Jv/AGf9g83/AJdvN379n+2uMbPfrXgHwy+Jv/Cuf7U/4lH9ofb/ACv+Xnytmzf/ALDZzv8AbpR8Mvhl/wALG/tT/ib/ANn/AGDyv+Xbzd+/f/trjGz3617/APDL4Zf8K5/tT/ib/wBofb/K/wCXbytmzf8A7bZzv9ulef8A/DMv/U3f+U3/AO21wHwy+Jv/AArn+1P+JR/aH2/yv+Xnytmzf/sNnO/26V3/AO01/wAyt/29/wDtGuA+GXxN/wCFc/2p/wASj+0Pt/lf8vPlbNm//YbOd/t0r3/4m/E3/hXP9l/8Sj+0Pt/m/wDLz5WzZs/2Gznf7dK8/wD2Zf8Amaf+3T/2tXAfE34Zf8K5/sv/AIm/9ofb/N/5dvK2bNn+22c7/bpXv/wy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulegUUUV8//APDMv/U3f+U3/wC20f8ADMv/AFN3/lN/+20f8My/9Td/5Tf/ALbXoHwy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulef/8ADMv/AFN3/lN/+20f8My/9Td/5Tf/ALbR/wAMy/8AU3f+U3/7bX0BXn/xN+GX/Cxv7L/4m/8AZ/2Dzf8Al283fv2f7a4xs9+tef8A/DMv/U3f+U3/AO216B8Mvhl/wrn+1P8Aib/2h9v8r/l28rZs3/7bZzv9ulHxN+GX/Cxv7L/4m/8AZ/2Dzf8Al283fv2f7a4xs9+tHwy+GX/Cuf7U/wCJv/aH2/yv+Xbytmzf/ttnO/26V6BXn/xN+GX/AAsb+y/+Jv8A2f8AYPN/5dvN379n+2uMbPfrR8Mvhl/wrn+1P+Jv/aH2/wAr/l28rZs3/wC22c7/AG6V5/8A8My/9Td/5Tf/ALbXoHwy+GX/AArn+1P+Jv8A2h9v8r/l28rZs3/7bZzv9ulef/8ADMv/AFN3/lN/+20f8My/9Td/5Tf/ALbXoHxN+GX/AAsb+y/+Jv8A2f8AYPN/5dvN379n+2uMbPfrR8Mvhl/wrn+1P+Jv/aH2/wAr/l28rZs3/wC22c7/AG6UfE34Zf8ACxv7L/4m/wDZ/wBg83/l283fv2f7a4xs9+tegV5/8Mvhl/wrn+1P+Jv/AGh9v8r/AJdvK2bN/wDttnO/26UfE34Zf8LG/sv/AIm/9n/YPN/5dvN379n+2uMbPfrXoFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFf/2Q=="
      }
    },
    {
      "request_control_key": "b3a428fd-58ee-4d6f-8872-633874ebf5e2",
      "bank_slip_key": "4056f1f1-a6ea-4162-8bac-b1ce2546a9bf",
      "bank_slip_status": "accepted",
      "our_number": 987654321,
      "barcode": "",
      "digitable_line":
    }
  ]
}
```

STATUS 4xx

### Response Body Params

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `bank_slips`               | Array de **[Objeto bank_slip_response](#objeto-bank_slip_response)** | Descontos                                                                          | - |

### Objeto bank_slip_response

| Campo                   | Tipo   | Descrição                                                                         | Caracteres |
|-------------------------|--------|-----------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | Chave única de identificação da request utilizada pelo cliente no formato uuid v4 | 36         |
| `bank_slip_key` *       | uuidv4 | Chave única de identificação do boleto no formato uuid v4                         | 36         |
| `bank_slip_status` *    | string | Status do boleto       | **[Enumeradores bank_slip_status](#enumeradores-bank_slip_status)**   |
| `our_number` *          | integer| Número único de identificação do boleto junto à carteira                          | 11         |
| `barcode` *             | string | Código de barras do boleto                                                        | 44         |
| `digitable_line` *      | string | Linha digitável do boleto                                                         | 47         |
| `qr_code_data`          | object | Dados do QR Code                             | **[Objeto qr_code_data](#objeto-qr_code_data)** |
| `created_at` *          | string | Data, no formato ISO (UTC - "YYYY-MM-DDTHH:MM:SSZ"), da criação da ocorrência     | 20         |

### Enumeradores bank_slip_status

| Enumerador         | Descrição                               |
|--------------------|-----------------------------------------|
| accepted           | Boleto aceito mas ainda não registrado  |

### Objeto qr_code_data
| Campo                      | Tipo   | Descrição                                             | Caracteres              |
|----------------------------|--------|-------------------------------------------------------|-------------------------|
| `qr_code_key`              | uuidv4 | Chave única de identificação do QR Code               | 36                      |
| `pix_key`                  | uuidv4 | Chave PIX vinculada ao QR Code                        | 36                      |
| `receiver_conciliation_id` | uuidv4 | Identificador de conciliação do QR Code               | 36                      |
| `url`                      | string | URL (Pix Copia e Cola) do QR Code                     | -                       |
| `image`                    | string | base64 da URL (Pix Copia e Cola) do QR Code           | -                       |

## Error Response

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 404                      | BKS000004            | Not Found | Pix key not found: `{pix_key}`                                               | Chave pix não encontrada: `{pix_key}`                                               |
| 403                      | BKS000005            | Forbidden                         | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404                      | BKS000006            | Not Found                                  | The source account key was not found.                                                                                | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                  | It was not possible to consult the source account at this time. Please try again in a few minutes.                                                                                      | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                                                                                    |
| 400                      | BKS000008            | Bad Request | The source account is closed.         |               A conta de origem está fechada.                                                                 |
| 400                      | BKS000009            | Bad Request | The source account is blocked.         |               A conta de origem está bloqueada.                                                                 |
| 403                      | BKS000010            | Forbidden                                 | The pix key owner does not match the account owner.                                                                                     | O proprietário da chave pix não corresponde ao proprietário da conta.                                                             |
| 404                      | BKS000013            | Not Found | Requester profile not found         |               Carteira não encontrada                                                                 |
| 409                      | BKS000014            | Conflict           | Request control key already sent or duplicated sent: `{request_control_key}`                                                              | Chave de controle da requisição já utilizada ou enviada duplicada: `{request_control_key}`                                                                        |
| 400                      | BKS000016            | Bad Request                                        | Expiration date must be greater than the current date and have a maximum of 3650 days from the current date.                                    | A data de vencimento deve ser maior que a data atual e possuir no máximo 3650 dias corridos a partir da data atual.                                     |
| 409                      | BKS000017            | Conflict                                        | Our number already used or duplicated sent: `{our_number}`                                                                                       | Nosso número já utilizado ou enviado duplicado: `{our_number}`                                                                               |
| 400                      | BKS000018            | Bad Request                                        | The discount dates must be less than the expiration date and increasing.                                                      | A data dos descontos devem ser menores que a de expiração e crescentes.                                               |
| 400                      | BKS000019            | Bad Request                                        | Payer address is required for protest.                                                                                       | Endereço do pagador é obrigatório para protesto.                                                                         |
| 500                      | BKS000021            | Internal Server Error                                  | Error while trying to generate QR Code.                                                               | Erro ao tentar gerar QR Code de pagamento.                                                           |
| 400                      | BKS000022            | Bad Request                                        | Requester profile is not opened.                                                              | Carteira não está aberta.                          |
| 400                      | BKS000026            | Bad Request                      | Guarantor address is required for protest.                                                                                        | Endereço do sacador é obrigatório para protesto.                                                                   |
| 404                      | BKS000028            | Not Found             | Notary office attended region not found for postal code: `{postal_code}`                                                          | Região de cartório não encontrada para o CEP: `{postal_code}`                                                                                 |
| 400                      | BKS000043            | Bad Request             | Invalid discount numbering. Discounts must be numbered in ascending order and start on 1.          | Numeração dos descontos inválida. Os descontos devem ser numerados em ordem crescente e começar em 1.                                                           |
| 400                      | BKS000045            | Bad Request                                        | Rebate amount can not be equal or greater than the bank slip amount.                                                              | O valor do rebate não pode ser igual ou maior do que o valor do boleto.                          |
| 400                      | BKS000047            | Bad Request             | It was not possible to consult the sent pix key at this time. Please try again in a few minutes.          | Não foi possível consultar a chave pix enviada no momento. Por favor, tente novamente em alguns minutos.                                                           |
| 400                      | BKS000125            | Bad Request             | Partial payment data is required for this bank slip species type.          | Os dados de pagamento parcial são obrigatórios para o tipo de boleto fornecido.                                                           |
| 400                      | BKS000128            | Bad Request             | QR code payment is not allowed for partial payment.          | Pagamento via QR code não é permitido para pagamento parcial.                                                           |
| 400                      | BKS000128            | Bad Request             | QR code payment is not allowed for partial payment.          | Pagamento via QR code não é permitido para pagamento parcial.                                                           |
| 400                      | BKS000131            | Bad Request             | Rebate amount is not allowed for this bank slip species type.          | O valor de abatimento não é permitido para o tipo de boleto fornecido.                                                           |
| 400                      | BKS000132            | Bad Request             | Discount data is not allowed for this bank slip species type.          | Os dados de desconto não são permitidos para o tipo de boleto fornecido.                                                           |
| 400                      | BKS000133            | Bad Request             | Fine data is not allowed for this bank slip species type.          | Os dados de multa não são permitidos para o tipo de boleto fornecido.                                                           |
| 400                      | BKS000134            | Bad Request             | Interest data is not allowed for this bank slip species type.          | Os dados de juros não são permitidos para o tipo de boleto fornecido.                                                           |
| 400                      | BKS000136            | Bad Request             | Only credit card financial instrument type can have zero amount.          | Apenas o tipo de instrumento financeiro cartão de crédito pode ter valor zero.                                                           |

---

# Cancelamento de abatimento

URL: /documentation/boletos/instrucoes/abatimento/cancelar_abatimento

Cancelar um abatimento significa cancelar o abatimento existente para o boleto. O cancelamento deve ser efetuado caso seja de interesse remover o abatimento ou então criar um novo.

:::caution Atenção!
Caso exista algum pedido de cancelamento de abatimento pendente de confirmação, ou não exista abatimento ativo, não é possível solicitar o cancelamento de um abatimento.

Obs.: o valor de abatimento (`rebate_amount`) enviado no registro do boleto conta como um abatimento ativo (caso seja maior que R$0,00).
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /cancel_rebate
MÉTODO POST

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36         |
| `bank_slip_key`         | uuidv4 | Chave única de identificação do boleto, no formato uuid v4   | 36         |

Request Body

```json
{
  "request_control_key": "86864aec-a6c8-462e-8460-b05ef5a1eb62"
}
```

### Request Body Params

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` *    | uuidv4  | Chave única de identificação da request utilizada pelo cliente no formato uuid v4  | 36         |

## Response

STATUS 202

Response Body

```json
{
  "occurrence_key": "539cefc8-382e-4fef-80e1-978a3a178a5c",
  "bank_slip_key": "d402e91a-32ac-4428-8357-d71824b113b5"
}
```

### Response Body Params

| Campo              | Tipo   | Descrição                                                                         | Caracteres |
|--------------------|--------|-----------------------------------------------------------------------------------|------------|
| `occurrence_key` * | uuidv4 | Chave única de identificação da ocorrência (instrução) no formato uuid v4         | 36         |
| `bank_slip_key` *  | uuidv4 | Chave única de identificação do boleto no formato uuid v4                         | 36         |

### Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 404                      | BKS000006            | Not Found                                  | The source account key was not found.                                                                                | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                  | It was not possible to consult the source account at this time. Please try again in a few minutes.                                                                                      | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                                                                                    |
| 400                      | BKS000008            | Bad Request | The source account is closed.         |               A conta de origem está fechada.                                                                 |
| 400                      | BKS000009            | Bad Request | The source account is blocked.         |               A conta de origem está bloqueada.                                                                 |
| 404                      | BKS000013            | Not Found | Requester profile not found         |               Carteira não encontrada                                                                 |
| 409                      | BKS000014            | Conflict | Request control key already sent or duplicated sent: `<request_control_key>` | Chave de controle da requisição já utilizada ou enviada duplicada: `<request_control_key>` |
| 400                      | BKS000022            | Bad Request                                        | Requester profile is not opened.                                                              | Carteira não está aberta.                          |
| 404                      | BKS000029            | Not Found                                        | Bank slip not found for the given key (`{bank_slip_key}`).                                                              | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`).                          |
| 400                      | BKS000031            | Bad Request                                        | Bank slip must have an active rebate.                                                              | O boleto deve possuir um rebate ativo.                          |
| 400                      | BKS000032            | Bad Request                                        | Bank slip must be in 'registered' status.                                                              | O boleto deve possuir o status 'registered'.                          |
| 409                      | BKS000034            | Bad Request                                        | There is already a pending cancel rebate occurrence for this bank slip.                                                              | Já existe uma ocorrência de cancelamento de rebate pendente para este boleto.                          |

---

# Criar abatimento

URL: /documentation/boletos/instrucoes/abatimento/criar_abatimento

Criar um abatimento para o boleto significa abater parte do valor base do título, para diminuir o valor final.

:::caution Atenção!
Caso exista algum pedido de abatimento pendente de confirmação, ou algum abatimento ativo, não é permitida a criação de um novo abatimento. Se houver algum abatimento ativo e for de interesse mudá-lo, primeiro deve ser enviada uma requisição de cancelamento de abatimento. Assim que a mesma for confirmada, é possível criar outro abatimento.

Obs.: o valor de abatimento (`rebate_amount`) enviado no registro do boleto não conta como um pedido de abatimento em aberto , mas conta como um pedido de abatimento ativo.
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /rebate
MÉTODO POST

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36         |
| `bank_slip_key`         | uuidv4 | Chave única de identificação do boleto, no formato uuid v4   | 36         |

Request Body

```json
{
  "request_control_key": "d66b807a-25fa-4e21-b198-9beb221a29ce",
  "rebate_amount": 150.00
}
```

### Request Body Params

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` *    | uuidv4  | Chave única de identificação da request utilizada pelo cliente no formato uuid v4  | 36         |
| `rebate_amount` *          | float   | Valor absoluto do abatimento                                                       | -          |

## Response

STATUS 202

Response Body

```json
{
  "occurrence_key": "7f01165b-fdd0-4f59-b231-42170ea90131",
  "bank_slip_key": "dad779c1-5e1c-422e-9f36-c704916a87cf"
}
```

### Response Body Params

| Campo              | Tipo   | Descrição                                                                         | Caracteres |
|--------------------|--------|-----------------------------------------------------------------------------------|------------|
| `occurrence_key` * | uuidv4 | Chave única de identificação da ocorrência (instrução) no formato uuid v4         | 36         |
| `bank_slip_key` *  | uuidv4 | Chave única de identificação do boleto no formato uuid v4                         | 36         |

### Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 404                      | BKS000006            | Not Found                                  | The source account key was not found.                                                                                | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                  | It was not possible to consult the source account at this time. Please try again in a few minutes.                                                                                      | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                                                                                    |
| 400                      | BKS000008            | Bad Request | The source account is closed.         |               A conta de origem está fechada.                                                                 |
| 400                      | BKS000009            | Bad Request | The source account is blocked.         |               A conta de origem está bloqueada.                                                                 |
| 404                      | BKS000013            | Not Found | Requester profile not found         |               Carteira não encontrada                                                                 |
| 409                      | BKS000014            | Conflict | Request control key already sent or duplicated sent: `<request_control_key>` | Chave de controle da requisição já utilizada ou enviada duplicada: `<request_control_key>` |
| 400                      | BKS000022            | Bad Request                                        | Requester profile is not opened.                                                              | Carteira não está aberta.                          |
| 404                      | BKS000029            | Not Found                                        | Bank slip not found for the given key (`{bank_slip_key}`).                                                              | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`).                          |
| 409                      | BKS000030            | Conflict                                        | There is already a pending rebate occurrence for this bank slip.                                                              | Já existe uma ocorrência de rebate pendente para este boleto.                          |
| 400                      | BKS000032            | Bad Request                                        | Bank slip must be in 'registered' status.                                                              | O boleto deve possuir o status 'registered'.                          |
| 409                      | BKS000033            | Conflict                                        | This bank slip already has an active rebate. You must send a 'cancel_rebate' occurrence before trying to create another one. one.                                                              | Este boleto já possui um rebate ativo. Você deve mandar uma ocorrência do tipo 'cancel_rebate' antes de tentar criar outro.                          |
| 400                      | BKS000045            | Bad Request                                        | Rebate amount can not be equal or greater than the bank slip amount.                                                              | O valor do rebate não pode ser igual ou maior do que o valor do boleto.                          |

---

# Baixa

URL: /documentation/boletos/instrucoes/baixa

Quando um boleto é baixado, torna-se indisponível para pagamento. Ou seja, o boleto é "cancelado".

:::caution Atenção!
Caso exista algum pedido de baixa pendente de confirmação, não é permitida a criação de um novo pedido. 
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /write_off
MÉTODO POST

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36         |
| `bank_slip_key`         | uuidv4 | Chave única de identificação do boleto, no formato uuid v4   | 36         |

Request Body

```json
{
  "request_control_key": "614a451d-3b82-460e-bcc0-2caf3dde711f"
}
```

### Request Body Params

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` *    | uuidv4  | Chave única de identificação da request utilizada pelo cliente no formato uuid v4  | 36         |

## Response

STATUS 202

Response Body

```json
{
  "occurrence_key": "2552bd64-950b-437e-a53a-a133ffea03d7",
  "bank_slip_key": "960f78d4-4426-4762-98da-3ce3713ae0a5"
}
```

### Response Body Params

| Campo              | Tipo   | Descrição                                                                         | Caracteres |
|--------------------|--------|-----------------------------------------------------------------------------------|------------|
| `occurrence_key` * | uuidv4 | Chave única de identificação da ocorrência (instrução) no formato uuid v4         | 36         |
| `bank_slip_key` *  | uuidv4 | Chave única de identificação do boleto no formato uuid v4                         | 36         |

### Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 404                      | BKS000006            | Not Found                                  | The source account key was not found.                                                                                | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                  | It was not possible to consult the source account at this time. Please try again in a few minutes.                                                                                      | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                                                                                    |
| 400                      | BKS000008            | Bad Request | The source account is closed.         |               A conta de origem está fechada.                                                                 |
| 400                      | BKS000009            | Bad Request | The source account is blocked.         |               A conta de origem está bloqueada.                                                                 |
| 404                      | BKS000013            | Not Found | Requester profile not found         |               Carteira não encontrada                                                                 |
| 409                      | BKS000014            | Conflict | Request control key already sent or duplicated sent: `<request_control_key>` | Chave de controle da requisição já utilizada ou enviada duplicada: `<request_control_key>` |
| 400                      | BKS000022            | Bad Request                                        | Requester profile is not opened.                                                              | Carteira não está aberta.                          |
| 404                      | BKS000029            | Not Found                                        | Bank slip not found for the given key (`{bank_slip_key}`).                                                              | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`).                          |
| 400                      | BKS000032            | Bad Request                                        | Bank slip must be in 'registered' status.                                                              | O boleto deve possuir o status 'registered'.                          |
| 409                      | BKS000049            | Conflict                                        | There is already a pending write off occurrence for this bank slip. Please, wait for the confirmation of this occurrence before sending another one. one.                                                              | Já existe uma ocorrência de baixa pendente para este boleto. Por favor, aguarde a confirmação dessa ocorrência antes de enviar outra.                          |

---

# Desconto

URL: /documentation/boletos/instrucoes/desconto

A instrução de desconto serve para aplicar descontos com diversas possibilidades de regras de cálculo. Caso já existam descontos para o boleto em questão, e seja aceita uma instrução de desconto, os descontos existentes previamente serão sobrescritos.

:::caution Atenção!
Caso exista algum pedido de acréscimo de desconto pendente de confirmação, não é permitida a criação de um novo pedido. 
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /discount
MÉTODO POST

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36         |
| `bank_slip_key`         | uuidv4 | Chave única de identificação do boleto, no formato uuid v4   | 36         |

Request Body

```json
{
    "request_control_key": "2e2f0053-a988-40c7-ad17-41c4c4da861e",
    "discounts_data": [
        {
            "discount_type": "anticipation_workdays_daily_percentage",
            "discount_percentage": 2,
            "discount_number": 1,
            "discount_limit_date": "2024-12-01"
        },
        {
            "discount_type": "anticipation_workdays_daily_percentage",
            "discount_percentage": 1,
            "discount_number": 2,
            "discount_limit_date": "2025-01-02"
        }
    ]
}
```

### Request Body Params

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` *    | uuidv4  | Chave única de identificação da request utilizada pelo cliente no formato uuid v4  | 36         |
| `discounts_data`           | object array | Descontos                                  | **[Objeto discount](#objeto-discounts_data)** |

### Objeto discount

Opção 1: descontos utilizando valores absolutos (`discount_type in ["absolute", "anticipation_calendar_days_daily_amount", "anticipation_workdays_daily_amount"]`)

| Campo                     | Tipo    | Descrição                                           | Caracteres                                                |
|---------------------------|---------|-----------------------------------------------------|-----------------------------------------------------------|
| `discount_amount` *       | float   | Valor absoluto de desconto por unidade de tempo                                            | -                                                          |
| `discount_number` *       | integer | Número do desconto                                     | -                                                         |
| `discount_type` *         | string  | Configuração do desconto em valores absolutos                                    | **[Enumerador discount_type](#enumeradores-discount_type)** |                                                       |
| `discount_limit_date` *   | string  | Data limite para aplicação do desconto   | 10                                                        |

Opção 2: descontos utilizando valores percentuais (`discount_type in ["percentage", "anticipation_calendar_days_daily_percentage", "anticipation_workdays_daily_percentage"]`)

| Campo                     | Tipo    | Descrição                                           | Caracteres                                                |
|---------------------------|---------|-----------------------------------------------------|-----------------------------------------------------------|
| `discount_percentage` *   | float   | Valor percentual de desconto por unidade de tempo                                            | -                                                          |
| `discount_number` *       | integer | Número do desconto                                     | -                                                         |
| `discount_type` *         | string  | Configuração do desconto em valores percentuais                                    | **[Enumerador discount_type](#enumeradores-discount_type)** |                                                       |
| `discount_limit_date` *   | string  | Data limite para aplicação do desconto   | 10                                                        |

:::caution Atenção!
O boleto pode ter até três descontos, sendo que os descontos devem ser todos do mesmo tipo , isto é, devem ter o mesmo `discount_type`. Os descontos devem ser numerados de 1 a 3, de maneira crescente e começando necessariamente em 1. Ou seja, caso sejam enviados dois descontos na requisição, devem necessariamente ser numerados com 1 e 2.
:::

### Enumeradores discount_type

| Enumerador                                  | Descrição                                                                |
|---------------------------------------------|--------------------------------------------------------------------------|
| absolute                                    | Valor fixo                                                               |
| anticipation_calendar_days_daily_amount     | Valor diário de desconto de antecipação, sobre dias corridos             |
| anticipation_workdays_daily_amount          | Valor diário de desconto de antecipação, sobre dias úteis                |
| percentage                                  | Porcentagem fixa                                                         |
| anticipation_calendar_days_daily_percentage | Porcentagem mensal de desconto de antecipação, com base em dias corridos |
| anticipation_workdays_daily_percentage      | Porcentagem anual de desconto de antecipação, com base em dias úteis     |

## Response

STATUS 202

Response Body

```json
{
  "occurrence_key": "aaf64135-6bd8-4d49-be6f-e8f884b20ee7",
  "bank_slip_key": "470cfcae-159b-4de4-ad22-2d3b2dd717f7"
}
```

### Response Body Params

| Campo              | Tipo   | Descrição                                                                         | Caracteres |
|--------------------|--------|-----------------------------------------------------------------------------------|------------|
| `occurrence_key` * | uuidv4 | Chave única de identificação da ocorrência (instrução) no formato uuid v4         | 36         |
| `bank_slip_key` *  | uuidv4 | Chave única de identificação do boleto no formato uuid v4                         | 36         |

### Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 404                      | BKS000006            | Not Found                                  | The source account key was not found.                                                                                | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                  | It was not possible to consult the source account at this time. Please try again in a few minutes.                                                                                      | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                                                                                    |
| 400                      | BKS000008            | Bad Request | The source account is closed.         |               A conta de origem está fechada.                                                                 |
| 400                      | BKS000009            | Bad Request | The source account is blocked.         |               A conta de origem está bloqueada.                                                                 |
| 404                      | BKS000013            | Not Found | Requester profile not found         |               Carteira não encontrada                                                                 |
| 409                      | BKS000014            | Conflict | Request control key already sent or duplicated sent: `<request_control_key>` | Chave de controle da requisição já utilizada ou enviada duplicada: `<request_control_key>` |
| 400                      | BKS000018            | Bad Request                                        | The discount dates must be less than the expiration date and increasing.                                                              | A data dos descontos devem ser menores que a de expiração e crescentes.                         |
| 400                      | BKS000022            | Bad Request                                        | Requester profile is not opened.                                                              | Carteira não está aberta.                          |
| 404                      | BKS000029            | Not Found                                        | Bank slip not found for the given key (`{bank_slip_key}`).                                                              | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`).                          |
| 400                      | BKS000032            | Bad Request                                        | Bank slip must be in 'registered' status.                                                              | O boleto deve possuir o status 'registered'.                          |
| 400                      | BKS000043            | Bad Request                                        | Invalid discount numbering. Discounts must be numbered in ascending order and start on 1.                                                              | Numeração dos descontos inválida. Os descontos devem ser numerados em ordem crescente e começar em 1.                          |
| 400                      | BKS000046            | Bad Request                                        | Invalid discount type. All types in the discount list must be the same.                                                              | Tipo de desconto inválido. Todos os tipos da lista de descontos devem ser iguais.                          |
| 409                      | BKS000048            | Conflict                                        | There is already a pending discount occurrence for this bank slip. Please, wait for the confirmation of this occurrence before sending another one.                                                              | Já existe uma ocorrência de desconto pendente para este boleto. Por favor, aguarde a confirmação dessa ocorrência antes de enviar outra.                          |

---

# Edição

URL: /documentation/boletos/instrucoes/edicao

A instrução de edição serve para modificar dados configuráveis do boleto após sua emissão, como configurações de baixa automática, protesto, protesto falimentar e dados do pagador. Esta instrução permite atualizar múltiplos aspectos do boleto em uma única requisição.

:::caution Atenção!
O boleto deve estar no status 'registered' para que seja possível editá-lo. Ao menos um dos campos de dados (`write_off_data`, `protest_data`, `bankruptcy_protest_data` ou `payer_data`) deve ser informado junto com o `request_control_key`.
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /bank_slip_edit
MÉTODO POST

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36         |
| `bank_slip_key`         | uuidv4 | Chave única de identificação do boleto, no formato uuid v4   | 36         |

Request Body

```json
{
  "request_control_key": "c4dd443a-6e2f-4261-8f28-adfa4c0d4c5b",
  "write_off_data": {"days_to_write_off": 365},
  "protest_data": {"days_to_protest": 7},
  "bankruptcy_protest_data": {"days_to_bankruptcy_protest": 14},
  "payer_data": {
    "contact": {
      "email": "finance@globaltech.com",
      "phone": {"international_dial_code": "055", "area_code": "11", "number": "987654321"},
    },
    "address": {
      "street": "101 High St.",
      "neighborhood": "Tech Park",
      "number": "202",
      "postal_code": "01001000",
      "city": "Innovation City",
      "state": "SP",
      "complement": "Building A",
    },
  },
}
```

### Request Body Params

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` *    | uuidv4  | Chave única de identificação da request utilizada pelo cliente no formato uuid v4  | 36         |
| `write_off_data`           | object  | Configurações de baixa automática (null para remover)                             | **[Objeto write_off_data](#objeto-write_off_data)** |
| `protest_data`             | object  | Configurações de protesto (null para remover)                                     | **[Objeto protest_data](#objeto-protest_data)** |
| `bankruptcy_protest_data`  | object  | Configurações de protesto falimentar (null para remover)                          | **[Objeto bankruptcy_protest_data](#objeto-bankruptcy_protest_data)** |
| `payer_data`               | object  | Dados do pagador (`address` null ou `contact` null para remover)                                                                  | **[Objeto payer_data](#objeto-payer_data)** |

:::info Observação
Pelo menos um dos campos de dados (`write_off_data`, `protest_data`, `bankruptcy_protest_data` ou `payer_data`) deve ser informado na requisição.
:::

### Objeto write_off_data

| Campo                     | Tipo    | Descrição                                                                   | Caracteres |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_write_off` *     | integer | Dias, após o vencimento, para que o boleto seja baixado automaticamente     | -          |

### Objeto protest_data

| Campo                     | Tipo    | Descrição                                                                   | Caracteres |
|---------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_protest` *       | integer | Dias, após o vencimento, para que o boleto seja protestado automaticamente  | -          |

### Objeto bankruptcy_protest_data

| Campo                          | Tipo    | Descrição                                                                   | Caracteres  |
|--------------------------------|---------|-----------------------------------------------------------------------------|------------|
| `days_to_bankruptcy_protest` * | integer | Dias, após o vencimento, para que o boleto seja protestado automaticamente  | -           |

### Objeto payer_data

| Campo                     | Tipo   | Descrição                                                  | Caracteres|
|---------------------------|--------|-------------------------------------|-----------------------------------------------------------|
| `contact`                 | object | Informações de contato              | **[Objeto contact](#objeto-contact)**                     |
| `address`                 | object | Endereço                            | **[Objeto address](#objeto-address)**                     |

### Objeto contact

| Campo                     | Tipo   | Descrição                         | Caracteres                         |
|---------------------------|--------|-----------------------------------|------------------------------------|
| `email`                   | string | E-mail de contato                 | 320                                |
| `phone`                   | object | Telefone de contato               | **[Objeto phone](#objeto-phone)**  |

### Objeto phone

| Campo                           | Tipo   | Descrição                                    | Caracteres |
|---------------------------------|--------|----------------------------------------------|------------|
| `international_dial_code` *     | string | Código DDI (Discagem Direta Internacional)   | 3          |
| `area_code` *                   | string | Código DDD (Discagem Direta à Distância)     | 2          |
| `number` *                      | string | Complemento                                  | 9          |

### Objeto address

| Campo                     | Tipo   | Descrição                                    | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `street` *                | string | Logradouro                                   | 500        |
| `number` *                | string | Número                                       | 6          |
| `complement`              | string | Complemento                                  | 500        |
| `neighborhood` *          | string | Bairro                                       | 100        |
| `postal_code` *           | string | CEP                                          | 8          |
| `city` *                  | string | Cidade                                       | 100        |
| `state` *                 | string | Estado (UF) | **[Enumerador state](#enumeradores-state)** |

### Enumeradores state

| Enumerador         | Descrição             |
|--------------------|-----------------------|
| AC                 | Acre                  |
| AL                 | Alagoas               |
| AM                 | Amazonas              |
| AP                 | Amapá                 |
| BA                 | Bahia                 |
| CE                 | Ceará                 |
| DF                 | Distrito federal      |
| ES                 | Espírito Santo        |
| GO                 | Goiás                 |
| MA                 | Maranhão              |
| MG                 | Minas Gerais          |
| MS                 | Mato Grosso do Sul    |
| MT                 | Mato Grosso           |
| PA                 | Pará                  |
| PB                 | Paraíba               |
| PE                 | Pernambuco            |
| PI                 | Piauí                 |
| PR                 | Paraná                |
| RJ                 | Rio de Janeiro        |
| RN                 | Rio Grande do Norte   |
| RO                 | Rondônia              |
| RR                 | Roraima               |
| RS                 | Rio Grande do Sul     |
| SC                 | Santa Catarina        |
| SE                 | Sergipe               |
| SP                 | São Paulo             |
| TO                 | Tocantins             |
| EX                 | Exceção               |

## Response

STATUS 200

Response Body

```json
{
  "occurrence_key": "5a745b65-9a2c-44eb-b43e-c80ef5429d94",
  "bank_slip_key": "fdafdffa-cbd4-4f3c-8e3d-990428305161"
}
```

### Response Body Params

| Campo              | Tipo   | Descrição                                                                         | Caracteres |
|--------------------|--------|-----------------------------------------------------------------------------------|------------|
| `occurrence_key` * | uuidv4 | Chave única de identificação da ocorrência (instrução) no formato uuid v4         | 36         |
| `bank_slip_key` *  | uuidv4 | Chave única de identificação do boleto no formato uuid v4                         | 36         |

### Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 404                      | BKS000006            | Not Found                                          | The source account key was not found.                                                                                  | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                        | It was not possible to consult the source account at this time. Please try again in a few minutes.                     | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                |
| 400                      | BKS000008            | Bad Request                                        | The source account is closed.                                                                                          | A conta de origem está fechada.                                                                                         |
| 400                      | BKS000009            | Bad Request                                        | The source account is blocked.                                                                                         | A conta de origem está bloqueada.                                                                                       |
| 404                      | BKS000013            | Not Found                                          | Requester profile not found                                                                                            | Carteira não encontrada                                                                                                 |
| 409                      | BKS000014            | Conflict                                           | Request control key already sent or duplicated sent: `<request_control_key>`                                           | Chave de controle da requisição já utilizada ou enviada duplicada: `<request_control_key>`                             |
| 400                      | BKS000022            | Bad Request                                        | Requester profile is not opened.                                                                                       | Carteira não está aberta.                                                                                              |
| 404                      | BKS000029            | Not Found                                          | Bank slip not found for the given key (`{bank_slip_key}`).                                                             | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`).                                                      |
| 400                      | BKS000032            | Bad Request                                        | Bank slip must be in 'registered' status.                                                                              | O boleto deve possuir o status 'registered'.                                                                           |

---

# Prorrogação

URL: /documentation/boletos/instrucoes/extensao

O pedido de prorrogação serve para estender a data de vencimento do título.

:::caution Atenção!
Caso exista algum pedido de prorrogação pendente de confirmação, não é permitida a criação de um novo pedido. 
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /extension
MÉTODO POST

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36         |
| `bank_slip_key`         | uuidv4 | Chave única de identificação do boleto, no formato uuid v4   | 36         |

Request Body

```json
{
  "request_control_key": "2e2f0053-a988-40c7-ad17-41c4c4da861e",
  "new_expiration_date": "2025-01-01"
}
```

### Request Body Params

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` *    | uuidv4  | Chave única de identificação da request utilizada pelo cliente no formato uuid v4  | 36         |
| `new_expiration_date` *    | string  | Nova data de expiração, no formato "YYYY-MM-DD"                                    | 10         |

## Response

STATUS 202

Response Body

```json
{
  "occurrence_key": "6f2eb385-898f-4fa3-96df-80a76a30ad01",
  "bank_slip_key": "0d462dda-7412-444f-ace9-375e4ab43c2f"
}
```

### Response Body Params

| Campo              | Tipo   | Descrição                                                                         | Caracteres |
|--------------------|--------|-----------------------------------------------------------------------------------|------------|
| `occurrence_key` * | uuidv4 | Chave única de identificação da ocorrência (instrução) no formato uuid v4         | 36         |
| `bank_slip_key` *  | uuidv4 | Chave única de identificação do boleto no formato uuid v4                         | 36         |

### Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 404                      | BKS000006            | Not Found                                  | The source account key was not found.                                                                                | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                  | It was not possible to consult the source account at this time. Please try again in a few minutes.                                                                                      | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                                                                                    |
| 400                      | BKS000008            | Bad Request | The source account is closed.         |               A conta de origem está fechada.                                                                 |
| 400                      | BKS000009            | Bad Request | The source account is blocked.         |               A conta de origem está bloqueada.                                                                 |
| 404                      | BKS000013            | Not Found | Requester profile not found         |               Carteira não encontrada                                                                 |
| 409                      | BKS000014            | Conflict | Request control key already sent or duplicated sent: `<request_control_key>` | Chave de controle da requisição já utilizada ou enviada duplicada: `<request_control_key>` |
| 400                      | BKS000022            | Bad Request                                        | Requester profile is not opened.                                                              | Carteira não está aberta.                          |
| 404                      | BKS000029            | Not Found                                        | Bank slip not found for the given key (`{bank_slip_key}`).                                                              | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`).                          |
| 400                      | BKS000032            | Bad Request                                        | Bank slip must be in 'registered' status.                                                              | O boleto deve possuir o status 'registered'.                          |
| 400                      | BKS000041            | Bad Request                                        | The new expiration date must be greater than the current expiration date.                                                              | A nova data de expiração deve ser posterior à data de expiração atual.                          |
| 409                      | BKS000042            | Conflict                                        | There is already a pending extension occurrence for this bank slip. Please, wait for the confirmation of this occurrence before sending another one.                                                              | Já existe uma ocorrência de extensão pendente para este boleto. Por favor, aguarde a confirmação dessa ocorrência antes de enviar outra.                          |

---

# Juros

URL: /documentation/boletos/instrucoes/juros

A instrução de juros serve para configurar os juros que serão aplicados caso o boleto seja pago após a data limite. Caso já exista uma configuração de juros para o boleto em questão, e seja aceita uma instrução de juros, a configuração existente previamente será sobrescrita.

:::caution Atenção!
Caso exista alguma instrução de juros pendente de confirmação, não é permitido o envio de uma nova instrução. 
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /interest
MÉTODO POST

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36         |
| `bank_slip_key`         | uuidv4 | Chave única de identificação do boleto, no formato uuid v4   | 36         |

Request Body

```json
{
  "request_control_key": "c4dd443a-6e2f-4261-8f28-adfa4c0d4c5b",
  "interest_data": {
    "interest_type": "calendar_days_daily_amount",
    "interest_amount": 50.00,
    "days_to_interest": 5
  }
}
```

### Request Body Params

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` *    | uuidv4  | Chave única de identificação da request utilizada pelo cliente no formato uuid v4  | 36         |
| `interest_data`            | object  | Configurações de juros                      | **[Objeto interest_data](#objeto-interest_data)** |

### Objeto interest_data

Opção 1: juros utilizando valores absolutos (`interest_type=calendar_days_daily_amount` ou `interest_type=workdays_daily_amount`)

| Campo                     | Tipo    | Descrição                                                                     | Caracteres                                                                                      |
|---------------------------|---------|-------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|
| `interest_type` *         | string  | Tipo de juros       | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_amount` *       | float   | Valor a ser cobrado por unidade de tempo determinada (dias úteis ou corridos) | -                                                                                               |
| `days_to_interest` *      | integer | Dias, após o vencimento, para que comece a cobrar os juros                    | -                                                                                               |

Opção 2: juros utilizando valores percentuais (`interest_type=calendar_days_monthly_percentage`)

| Campo                    | Tipo    | Descrição                                                                             | Caracteres                                                                                          |
|--------------------------|---------|---------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|
| `interest_type` *        | string  | Tipo de juros       | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `interest_percentage` *  | integer | Porcentagem a ser cobrada por unidade de tempo determinada (dias úteis ou corridos)                                                                      | -                                                                           |
| `days_to_interest` *     | integer | Dias, após o vencimento, para que comece a cobrar os juros                             | -                                                                                                   |

### Enumeradores interest_type

| Enumerador                       | Descrição                                                            |
|----------------------------------|----------------------------------------------------------------------|
| calendar_days_daily_amount       | Valor diário sobre dias corridos                                     |
| workdays_daily_amount            | Valor diário sobre dias úteis                                        |
| calendar_days_monthly_percentage | Porcentagem de juros cobrados mensalmente, com base em dias corridos |

## Response

STATUS 202

Response Body

```json
{
  "occurrence_key": "5a745b65-9a2c-44eb-b43e-c80ef5429d94",
  "bank_slip_key": "fdafdffa-cbd4-4f3c-8e3d-990428305161"
}
```

### Response Body Params

| Campo              | Tipo   | Descrição                                                                         | Caracteres |
|--------------------|--------|-----------------------------------------------------------------------------------|------------|
| `occurrence_key` * | uuidv4 | Chave única de identificação da ocorrência (instrução) no formato uuid v4         | 36         |
| `bank_slip_key` *  | uuidv4 | Chave única de identificação do boleto no formato uuid v4                         | 36         |

### Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 404                      | BKS000006            | Not Found                                  | The source account key was not found.                                                                                | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                  | It was not possible to consult the source account at this time. Please try again in a few minutes.                                                                                      | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                                                                                    |
| 400                      | BKS000008            | Bad Request | The source account is closed.         |               A conta de origem está fechada.                                                                 |
| 400                      | BKS000009            | Bad Request | The source account is blocked.         |               A conta de origem está bloqueada.                                                                 |
| 404                      | BKS000013            | Not Found | Requester profile not found         |               Carteira não encontrada                                                                 |
| 409                      | BKS000014            | Conflict | Request control key already sent or duplicated sent: `<request_control_key>` | Chave de controle da requisição já utilizada ou enviada duplicada: `<request_control_key>` |
| 400                      | BKS000018            | Bad Request                                        | The discount dates must be less than the expiration date and increasing.                                                              | A data dos descontos devem ser menores que a de expiração e crescentes.                         |
| 400                      | BKS000022            | Bad Request                                        | Requester profile is not opened.                                                              | Carteira não está aberta.                          |
| 404                      | BKS000029            | Not Found                                        | Bank slip not found for the given key (`{bank_slip_key}`).                                                              | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`).                          |
| 400                      | BKS000032            | Bad Request                                        | Bank slip must be in 'registered' status.                                                              | O boleto deve possuir o status 'registered'.                          |
| 409                      | BKS000051            | Conflict                                        | There is already a pending interest occurrence for this bank slip. Please, wait for the confirmation of this occurrence before sending another one.                                                              | Já existe uma ocorrência de juros pendente para este boleto. Por favor, aguarde a confirmação dessa ocorrência antes de enviar outra.                          |

---

# Consultar lote de instruções

URL: /documentation/boletos/instrucoes/lote/consultar_lote_de_instrucoes

Retorna o detalhe de um lote previamente criado, com a lista de ocorrências geradas e o status individual de cada uma, junto com os dados básicos do boleto associado.

## Request

ENDPOINT /v2/bank_slip/account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /occurrence_batches/ BATCH_KEY /results
MÉTODO GET

### Path parameters

| Campo                   | Tipo   | Descrição                                                       | Caracteres |
|-------------------------|--------|-----------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4       | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4    | 36         |
| `batch_key`             | uuidv4 | Chave do lote (retornada pelo POST de criação)                  | 36         |

## Response

STATUS 200

Response Body

```json
{
  "batch_key": "f2d3e1b9-4a5c-46e7-8f12-9a8b7c6d5e4f",
  "requester_profile_key": "8217da98-3e26-4ca5-8b86-698bfa50b0df",
  "occurrence_type": "extension",
  "occurrence_quantity": 2,
  "accepted_quantity": 2,
  "created_at": "2026-06-09T17:08:33Z",
  "items": [
    {
      "bank_slip_key": "960f78d4-4426-4762-98da-3ce3713ae0a5",
      "occurrence_key": "2552bd64-950b-437e-a53a-a133ffea03d7",
      "request_control_key": "c86d8902-a5ae-4d1f-8872-e6fea1268aab",
      "occurrence_type": "extension",
      "payer_name": "Global Tech",
      "payer_document": "12345678000195",
      "amount": 5000.00,
      "our_number": "123456789",
      "requester_occurrence_status": "accepted",
      "registration_institution_occurrence_status": "submitted",
      "created_at": "2026-06-09T17:08:33Z"
    }
  ]
}
```

### Response Body Params

| Campo                     | Tipo    | Descrição                                                                                |
|---------------------------|---------|------------------------------------------------------------------------------------------|
| `batch_key` *             | uuidv4  | Chave do lote                                                                            |
| `requester_profile_key` * | uuidv4  | Chave da carteira dona do lote                                                           |
| `occurrence_type` *       | string  | Tipo de instrução do lote                                                                |
| `occurrence_quantity` *   | integer | Quantidade total de itens enviados no lote                                               |
| `accepted_quantity` *     | integer | Quantidade de itens aceitos no lote                                                      |
| `created_at` *            | string  | Data/hora UTC de criação do lote (ISO 8601 com sufixo `Z`)                               |
| `items` *                 | array   | Lista de ocorrências geradas pelo lote. Veja **[Objeto item](#objeto-item)**             |

### Objeto item

| Campo                                          | Tipo    | Descrição                                                                              |
|------------------------------------------------|---------|----------------------------------------------------------------------------------------|
| `bank_slip_key` *                              | uuidv4  | Chave do boleto da ocorrência                                                          |
| `occurrence_key` *                             | uuidv4  | Chave única da ocorrência criada                                                       |
| `request_control_key` *                        | string  | Chave de controle informada pelo cliente para o item                                   |
| `occurrence_type` *                            | string  | Tipo de instrução                                                                      |
| `payer_name`                                   | string  | Nome do pagador do boleto                                                              |
| `payer_document`                               | string  | Documento do pagador                                                                   |
| `amount`                                       | float   | Valor base do boleto                                                                   |
| `our_number`                                   | string  | Nosso número do boleto                                                                 |
| `requester_occurrence_status`                  | string  | Status da ocorrência do ponto de vista do solicitante (ex.: `accepted`, `rejected`)    |
| `registration_institution_occurrence_status`   | string  | Status do processamento na instituição registradora (ex.: `submitted`, `confirmed`)    |
| `created_at` *                                 | string  | Data/hora UTC de criação da ocorrência (ISO 8601 com sufixo `Z`)                       |

### Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title` | Descrição (eng)<br/>`description`                              | Descrição (pt-br)<br/>`translation`                              |
|--------------------------|----------------------|--------------------|----------------------------------------------------------------|------------------------------------------------------------------|
| 404                      | BKS000013            | Not Found          | Requester profile not found                                    | Carteira não encontrada                                          |

:::caution Atenção!
Quando o `batch_key` não existe ou não pertence à `requester_profile_key` informada, a API retorna o mesmo `BKS000013` ("Carteira não encontrada"). Verifique se o `batch_key` foi criado sob a carteira utilizada na consulta.
:::

---

# Criar lote de instruções

URL: /documentation/boletos/instrucoes/lote/criar_lote_de_instrucoes

Permite o envio, em uma única requisição, de múltiplas instruções de mesmo tipo (baixa, abatimento, prorrogação, protesto etc.) sobre boletos distintos. A QI Tech valida o lote inteiro e, ou todos os itens são aceitos, ou nenhum é processado.

- Se **qualquer** item falhar na validação semântica, **nenhum** item do lote é processado. A resposta de erro detalha, por item rejeitado, o motivo da rejeição.
- Se todos os itens passarem, as ocorrências são criadas e processadas individualmente, de forma assíncrona. O solicitante é notificado via [**webhook**](/documentation/boletos/v2/webhooks/boleto) à medida que cada ocorrência muda de status.

:::info Idempotência
A `request_control_key` do lote garante idempotência no nível do lote: reenviar a mesma chave retorna o lote já criado, sem duplicação.

Cada item do lote também possui sua própria `request_control_key` e é idempotente individualmente. Reenviar um item com `request_control_key` já existente faz o lote inteiro ser rejeitado.
:::

:::caution Atenção!
Esta operação está disponível apenas para carteiras registradas na instituição registradora **QI SCD**.
:::

## Request

ENDPOINT /v2/bank_slip/account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /occurrence_batches
MÉTODO POST

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36         |

Request Body

```json
{
  "request_control_key": "614a451d-3b82-460e-bcc0-2caf3dde711f",
  "occurrence_type": "extension",
  "items": [
    {
      "bank_slip_key": "960f78d4-4426-4762-98da-3ce3713ae0a5",
      "request_control_key": "c86d8902-a5ae-4d1f-8872-e6fea1268aab",
      "new_due_date": "2026-08-15"
    },
    {
      "bank_slip_key": "5e3a1b2c-7d9f-4e88-9012-3a4b5c6d7e8f",
      "request_control_key": "b3a428fd-58ee-4d6f-8872-633874ebf5e2",
      "new_due_date": "2026-08-20"
    }
  ]
}
```

### Request Body Params

| Campo                   | Tipo                                          | Descrição                                                                          | Caracteres |
|-------------------------|-----------------------------------------------|------------------------------------------------------------------------------------|------------|
| `request_control_key` * | string                                        | Chave única do lote, definida pelo cliente. Garante idempotência do lote           | 1–64       |
| `occurrence_type` *     | string                                        | Tipo de instrução aplicada a todos os itens. Veja **[Enumeradores occurrence_type](#enumeradores-occurrence_type)** | -          |
| `items` *               | Array de **[Objeto item](#objeto-item)**      | Lista de instruções (mínimo 1, máximo 10000)                                       | -          |

### Enumeradores occurrence_type

| Enumerador               | Descrição                                                  |
|--------------------------|------------------------------------------------------------|
| `extension`              | Prorrogação de vencimento — requer `new_due_date` no item   |
| `rebate`                 | Concessão de abatimento — requer `rebate_amount` no item    |
| `cancel_rebate`          | Cancelamento de abatimento                                  |
| `write_off`              | Baixa do boleto                                             |
| `protest_request`        | Pedido de protesto                                          |
| `protest_cancel_request` | Desistência (sustação) do pedido de protesto                |
| `protest_remove_request` | Remoção (cancelamento) do protesto                          |

### Objeto item

| Campo                   | Tipo     | Descrição                                                                            | Caracteres |
|-------------------------|----------|--------------------------------------------------------------------------------------|------------|
| `bank_slip_key` *       | uuidv4   | Chave do boleto sobre o qual a instrução será aplicada                               | 36         |
| `request_control_key` * | string   | Chave única do item, definida pelo cliente. Garante idempotência por item            | 1–64       |
| `new_due_date`          | string   | Nova data de vencimento (`YYYY-MM-DD`). Obrigatório para `occurrence_type=extension` | 10         |
| `rebate_amount`         | float    | Valor de abatimento. Obrigatório para `occurrence_type=rebate`                       | -          |

## Response

STATUS 201

Response Body

```json
{
  "batch_key": "f2d3e1b9-4a5c-46e7-8f12-9a8b7c6d5e4f",
  "occurrence_quantity": 2,
  "accepted_quantity": 2,
  "semantic_errors": []
}
```

### Response Body Params

| Campo                   | Tipo    | Descrição                                                                              | Caracteres |
|-------------------------|---------|----------------------------------------------------------------------------------------|------------|
| `batch_key` *           | uuidv4  | Chave única do lote. Utilize para consultar o detalhe do lote                          | 36         |
| `occurrence_quantity` * | integer | Quantidade total de itens enviados no lote                                             | -          |
| `accepted_quantity` *   | integer | Quantidade de itens aceitos no lote                                                    | -          |
| `semantic_errors` *     | array   | Lista vazia em caso de sucesso. Em caso de rejeição semântica, ver **[Error Response](#error-response)** | - |

### Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

Em caso de rejeição semântica (`BLP000112`), o campo `reasons` da resposta detalha cada item rejeitado:

Response Body: Rejeição semântica

```json
{
  "title": "Unprocessable Entity",
  "description": "Rejected Remittance",
  "translation": "Remessa Rejeitada",
  "code": "BLP000112",
  "reasons": [
    {
      "occurrence_sequence": "0",
      "bank_slip_key": "960f78d4-4426-4762-98da-3ce3713ae0a5",
      "request_control_key": "c86d8902-a5ae-4d1f-8872-e6fea1268aab",
      "errors": [
        {
          "reason_code": "15",
          "translation_pt_br": "Boleto não encontrado",
          "translation_en_us": "Bank slip not found",
          "created_at": "2026-06-09T17:08:33"
        }
      ]
    }
  ]
}
```

### Campos do objeto `reasons[]`

| Campo                   | Tipo    | Descrição                                                                          |
|-------------------------|---------|------------------------------------------------------------------------------------|
| `occurrence_sequence` * | string  | Posição do item no array `items` da requisição (começando em `"0"`)                |
| `bank_slip_key` *       | uuidv4  | Chave do boleto do item rejeitado                                                  |
| `request_control_key` * | string  | Chave de controle informada pelo cliente para o item                               |
| `errors` *              | array   | Lista de motivos da rejeição (um item pode ter múltiplos motivos)                  |
| `errors[].reason_code` *      | string  | Código do motivo de rejeição (padrão Febraban)                                |
| `errors[].translation_pt_br`  | string  | Descrição em português do motivo                                              |
| `errors[].translation_en_us`  | string  | Descrição em inglês do motivo                                                 |
| `errors[].created_at`         | string  | Data/hora de cadastro do motivo no catálogo                                   |

### Códigos de erro

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`        | Descrição (eng)<br/>`description`                                                                                  | Descrição (pt-br)<br/>`translation`                                                                                          |
|--------------------------|----------------------|---------------------------|---------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request               | Schema Error                                                                                                        | Schema Inválido                                                                                                              |
| 400                      | BKS000141            | Bad Request               | Bank slip registration is restricted to QI SCD.                                                                     | Registro de boleto permitido apenas para QI SCD.                                                                             |
| 404                      | BKS000013            | Not Found                 | Requester profile not found                                                                                         | Carteira não encontrada                                                                                                      |
| 409                      | BKS000014            | Conflict                  | Request control key already sent or duplicated sent: `<request_control_key>`                                        | Chave de controle da requisição já utilizada ou enviada duplicada: `<request_control_key>`                                   |
| 422                      | BLP000112            | Unprocessable Entity      | Rejected Remittance                                                                                                 | Remessa Rejeitada                                                                                                            |

---

# Listar lotes de instruções

URL: /documentation/boletos/instrucoes/lote/listar_lotes_de_instrucoes

Lista, de forma paginada, os lotes de instruções criados para uma carteira, com filtros opcionais por tipo de instrução e intervalo de datas.

## Request

ENDPOINT /v2/bank_slip/account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /occurrence_batches
MÉTODO GET

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36         |

### Query Parameters

| Campo             | Tipo    | Descrição                                                                                          |
|-------------------|---------|----------------------------------------------------------------------------------------------------|
| `page`            | integer | Página da consulta (padrão `1`)                                                                    |
| `page_size`       | integer | Quantidade de lotes por página (padrão `20`, máximo `100`)                                         |
| `occurrence_type` | string  | Filtra pelo tipo de instrução do lote. Aceita os mesmos enumeradores do POST de criação            |
| `from_date`       | string  | Data inicial, inclusiva, no formato `YYYY-MM-DD`. Filtra sobre o `created_at` do lote              |
| `to_date`         | string  | Data final, inclusiva, no formato `YYYY-MM-DD`. Filtra sobre o `created_at` do lote                |

## Response

STATUS 200

Response Body

```json
{
  "data": [
    {
      "batch_key": "f2d3e1b9-4a5c-46e7-8f12-9a8b7c6d5e4f",
      "request_control_key": "614a451d-3b82-460e-bcc0-2caf3dde711f",
      "requester_profile_key": "8217da98-3e26-4ca5-8b86-698bfa50b0df",
      "occurrence_type": "extension",
      "occurrence_quantity": 14,
      "accepted_quantity": 14,
      "created_at": "2026-06-09T17:08:33Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 1
  }
}
```

### Response Body Params

| Campo                            | Tipo    | Descrição                                                                  |
|----------------------------------|---------|----------------------------------------------------------------------------|
| `data` *                         | array   | Lista de lotes da página atual                                             |
| `data[].batch_key` *             | uuidv4  | Chave do lote                                                              |
| `data[].request_control_key` *   | string  | Chave de controle informada pelo cliente na criação do lote                |
| `data[].requester_profile_key` * | uuidv4  | Chave da carteira dona do lote                                             |
| `data[].occurrence_type` *       | string  | Tipo de instrução do lote                                                  |
| `data[].occurrence_quantity` *   | integer | Quantidade total de itens enviados no lote                                 |
| `data[].accepted_quantity` *     | integer | Quantidade de itens aceitos no lote                                        |
| `data[].created_at` *            | string  | Data/hora UTC de criação do lote (ISO 8601 com sufixo `Z`)                 |
| `pagination` *                   | object  | Metadados de paginação                                                     |
| `pagination.page` *              | integer | Página atual                                                               |
| `pagination.page_size` *         | integer | Tamanho da página                                                          |
| `pagination.total` *             | integer | Quantidade total de lotes que atendem aos filtros                          |

### Error Response

STATUS 4xx

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title` | Descrição (eng)<br/>`description` | Descrição (pt-br)<br/>`translation` |
|--------------------------|----------------------|--------------------|-----------------------------------|-------------------------------------|
| 400                      | QIT000001            | Bad Request        | Schema Error                      | Schema Inválido                     |
| 404                      | BKS000013            | Not Found          | Requester profile not found       | Carteira não encontrada             |

---

# Multa

URL: /documentation/boletos/instrucoes/multa

A instrução de multa serve para configurar a multa que será aplicada caso o boleto seja pago após a data limite. Caso já exista uma configuração de multa para o boleto em questão, e seja aceita uma instrução de multa, a configuração existente previamente será sobrescrita.

:::caution Atenção!
Caso exista alguma instrução de multa pendente de confirmação, não é permitido o envio de uma nova instrução. 
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /fine
MÉTODO POST

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36         |
| `bank_slip_key`         | uuidv4 | Chave única de identificação do boleto, no formato uuid v4   | 36         |

Request Body

```json
{
  "request_control_key": "c4dd443a-6e2f-4261-8f28-adfa4c0d4c5b",
  "fine_data": {
    "fine_type": "absolute",
    "fine_amount": 50.00,
    "days_to_fine": 5
  }
}
```

### Request Body Params

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` *    | uuidv4  | Chave única de identificação da request utilizada pelo cliente no formato uuid v4  | 36         |
| `interest_data`            | object  | Configurações de multa                              | **[Objeto fine_data](#objeto-fine_data)** |

### Objeto fine_data

Opção 1: multa em valor absoluto (`fine_type=absolute`)

| Campo                     | Tipo    | Descrição                                               | Caracteres                |
|---------------------------|---------|---------------------------------------------------------|-------------------------------------------------------------------------|
| `fine_type` *             | string  | Tipo da multa                                                       | **[Enumeradores fine_type](#enumeradores-fine_type)**                                              |
| `fine_amount` *           | float   | Valor absoluto da multa                                             | -                                                                        |
| `days_to_fine` *          | integer | Dias, após o vencimento, para que a multa seja cobrada              | -                                                                        |

Opção 2: multa em valor percentual (`fine_type=percentage`)

| Campo                     | Tipo    | Descrição                                                 | Caracteres                             |
|---------------------------|---------|-----------------------------------------------------------|---------------------------------------|
| `fine_type` *             | string  | Tipo da multa                                             | **[Enumeradores fine_type](#enumeradores-fine_type)** |
| `fine_percentage` *       | integer | Valor percentual da multa, de 1 a 100                     | -                                      |
| `days_to_fine` *          | integer | Dias, após o vencimento, para que a multa seja cobrada    | -                                      |

### Enumeradores fine_type

| Enumerador         | Descrição             |
|--------------------|-----------------------|
| absolute           | valor absoluto        |
| percentage         | valor percentual      |

## Response

STATUS 202

Response Body

```json
{
  "occurrence_key": "aaf64135-6bd8-4d49-be6f-e8f884b20ee7",
  "bank_slip_key": "470cfcae-159b-4de4-ad22-2d3b2dd717f7"
}
```

### Response Body Params

| Campo              | Tipo   | Descrição                                                                         | Caracteres |
|--------------------|--------|-----------------------------------------------------------------------------------|------------|
| `occurrence_key` * | uuidv4 | Chave única de identificação da ocorrência (instrução) no formato uuid v4         | 36         |
| `bank_slip_key` *  | uuidv4 | Chave única de identificação do boleto no formato uuid v4                         | 36         |

### Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 404                      | BKS000006            | Not Found                                  | The source account key was not found.                                                                                | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                  | It was not possible to consult the source account at this time. Please try again in a few minutes.                                                                                      | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                                                                                    |
| 400                      | BKS000008            | Bad Request | The source account is closed.         |               A conta de origem está fechada.                                                                 |
| 400                      | BKS000009            | Bad Request | The source account is blocked.         |               A conta de origem está bloqueada.                                                                 |
| 404                      | BKS000013            | Not Found | Requester profile not found         |               Carteira não encontrada                                                                 |
| 409                      | BKS000014            | Conflict | Request control key already sent or duplicated sent: `<request_control_key>` | Chave de controle da requisição já utilizada ou enviada duplicada: `<request_control_key>` |
| 400                      | BKS000018            | Bad Request                                        | The discount dates must be less than the expiration date and increasing.                                                              | A data dos descontos devem ser menores que a de expiração e crescentes.                         |
| 400                      | BKS000022            | Bad Request                                        | Requester profile is not opened.                                                              | Carteira não está aberta.                          |
| 404                      | BKS000029            | Not Found                                        | Bank slip not found for the given key (`{bank_slip_key}`).                                                              | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`).                          |
| 400                      | BKS000032            | Bad Request                                        | Bank slip must be in 'registered' status.                                                              | O boleto deve possuir o status 'registered'.                          |
| 409                      | BKS000050            | Conflict                                        | There is already a pending fine occurrence for this bank slip. Please, wait for the confirmation of this occurrence before sending another one.                                                              | Já existe uma ocorrência de multa pendente para este boleto. Por favor, aguarde a confirmação dessa ocorrência antes de enviar outra.                          |

---

# Pagamento Parcial

URL: /documentation/boletos/instrucoes/pagamento_parcial

A instrução de pagamento parcial permite editar as configurações de pagamento parcial para um boleto, desde que o boleto já tenha sido registrado com o pagamento parcial ativo. Caso já exista uma configuração de pagamento parcial para o boleto em questão, e seja aceita uma nova instrução, a configuração existente previamente será sobrescrita.

:::caution Atenção!
Caso exista alguma instrução de pagamento parcial pendente de confirmação, não é permitido o envio de uma nova instrução.
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /partial_payment
MÉTODO POST

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36         |
| `bank_slip_key`         | uuidv4 | Chave única de identificação do boleto, no formato uuid v4   | 36         |

Request Body

```json
{
    "request_control_key": "01234567-89ab-cdef-0123-456789abcdef",
    "partial_payment_data": {
        "partial_payment_minimum_type": "absolute",
        "partial_payment_minimum_amount": 50.00,
        "partial_payment_maximum_type": "absolute",
        "partial_payment_maximum_amount": 1000.00,
        "partial_payment_quantity": 3
    }
}
```

### Request Body Params

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` *    | uuidv4  | Chave única de identificação da request utilizada pelo cliente no formato uuid v4  | 36         |
| `partial_payment_data` *    | object  | Configurações de pagamento parcial                      | **[Objeto partial_payment_data](#objeto-partial_payment_data)** |

### Objeto partial_payment_data

| Campo                             | Tipo    | Descrição                                                                 | Caracteres |
|-----------------------------------|---------|---------------------------------------------------------------------------|------------|
| `partial_payment_minimum_type` *  | string  | Tipo de valor mínimo para pagamento parcial                               | **[Enumeradores partial_payment_type](#enumeradores-partial_payment_type)** |
| `partial_payment_minimum_percentage` | float | Percentual mínimo permitido para o pagamento parcial                      | -          |
| `partial_payment_minimum_amount`  | float  | Valor mínimo permitido para o pagamento parcial                           | -          |
| `partial_payment_maximum_type`    | string  | Tipo de valor máximo para pagamento parcial                               | **[Enumeradores partial_payment_type](#enumeradores-partial_payment_type)** |
| `partial_payment_maximum_percentage` | float | Percentual máximo permitido para o pagamento parcial                      | -          |
| `partial_payment_maximum_amount`  | float  | Valor máximo permitido para o pagamento parcial                           | -          |
| `partial_payment_quantity` *      | integer | Quantidade de pagamentos parciais permitidos                              | -          |

:::caution Atenção!
De acordo com o valor enviado nos campos `partial_payment_minimum_type` e `partial_payment_maximum_type`, é necessário enviar o `partial_payment_minimum_amount` ou `partial_payment_minimum_percentage`, e o `partial_payment_maximum_amount` ou `partial_payment_maximum_percentage` correspondente.
:::

### Enumeradores partial_payment_type

| Enumerador  | Descrição                        |
|-------------|----------------------------------|
| absolute    | Valor absoluto                   |
| percentage  | Percentual                       |

## Response

STATUS 202

Response Body

```json
{
  "occurrence_key": "5a745b65-9a2c-44eb-b43e-c80ef5429d94",
  "bank_slip_key": "fdafdffa-cbd4-4f3c-8e3d-990428305161"
}
```

### Response Body Params

| Campo              | Tipo   | Descrição                                                                         | Caracteres |
|--------------------|--------|-----------------------------------------------------------------------------------|------------|
| `occurrence_key` * | uuidv4 | Chave única de identificação da ocorrência (instrução) no formato uuid v4         | 36         |
| `bank_slip_key` *  | uuidv4 | Chave única de identificação do boleto no formato uuid v4                         | 36         |

### Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 404                      | BKS000006            | Not Found                                  | The source account key was not found.                                                                                | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                  | It was not possible to consult the source account at this time. Please try again in a few minutes.                                                                                      | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                                                                                    |
| 400                      | BKS000008            | Bad Request | The source account is closed.         |               A conta de origem está fechada.                                                                 |
| 400                      | BKS000009            | Bad Request | The source account is blocked.         |               A conta de origem está bloqueada.                                                                 |
| 404                      | BKS000013            | Not Found | Requester profile not found         |               Carteira não encontrada                                                                 |
| 409                      | BKS000014            | Conflict | Request control key already sent or duplicated sent: `<request_control_key>` | Chave de controle da requisição já utilizada ou enviada duplicada: `<request_control_key>` |
| 400                      | BKS000022            | Bad Request                                        | Requester profile is not opened.                                                              | Carteira não está aberta.                          |
| 404                      | BKS000029            | Not Found                                        | Bank slip not found for the given key (`{bank_slip_key}`).                                                              | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`).                          |
| 400                      | BKS000032            | Bad Request                                        | Bank slip must be in 'registered' status.                                                              | O boleto deve possuir o status 'registered'.                          |
| 409                      | BKS000126            | Conflict                                        | There is already a pending partial payment occurrence for this bank slip. Please, wait for the confirmation of this occurrence before sending another one.                                                              | Já existe uma ocorrência de pagamento parcial pendente para este boleto. Por favor, aguarde a confirmação dessa ocorrência antes de enviar outra.                          |
| 400                      | BKS000127            | Bad Request                                        | Partial payment data is not set for this bank slip.                                                              | Os dados de pagamento parcial não estão configurados para este boleto.                          |

---

# Consulta de instrumento de protesto

URL: /documentation/boletos/instrucoes/protesto/consulta_instrumento_de_protesto

O instrumento de protesto é um documento oficial emitido pelo cartório de protesto, que comprova a execução do processo de cobrança. Ele é emitido após a lavratura do protesto, caso o devedor não tenha pago a dívida após ser intimado.

:::caution Atenção!
Só é possível consultar o instrumento de protesto do título após o mesmo ser efetivamente protestado (`protest_status` possui o valor `protested`).
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /protest_instrument
MÉTODO GET

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36         |
| `bank_slip_key`         | uuidv4 | Chave única de identificação do boleto, no formato uuid v4   | 36         |

## Response

STATUS 200

Response Body

```json
{
  "bank_slip_key": "bc34e9b1-42e4-4f17-bfc0-c88f29d5230e",
  "file_url": "https://storage.googleapis.com/live-bank-slip-api/protest_instrument/bc34e9b1-42e4-4f17-bfc0-c88f29d5230e.pdf"
}
```

### Response Body Params

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `bank_slip_key` *          | uuidv4  | Chave única de identificação do boleto no formato uuid v4                          | 36                                                |
| `file_url` *               | string  | URL do arquivo, em PDF, contendo o documento do instrumento de protesto            | -                                                 |

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (ptbr)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 404                      | BKS000006            | Not Found                                  | The source account key was not found.                                                                                | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                  | It was not possible to consult the source account at this time. Please try again in a few minutes.                                                                                      | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                                                                                    |
| 400                      | BKS000008            | Bad Request | The source account is closed.         |               A conta de origem está fechada.                                                                 |
| 400                      | BKS000009            | Bad Request | The source account is blocked.         |               A conta de origem está bloqueada.                                                                 |
| 404                      | BKS000013            | Not Found | Requester profile not found         |               Carteira não encontrada                                                                 |
| 404                      | BKS000029            | Not Found                                        | Bank slip not found for the given key (`{bank_slip_key}`).                                                              | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`).                          |
| 400                      | BKS000081            | Bad Request | The protest instrument will be available only after bank slip's protest confirmation. | O instrumento de protesto só estará disponível após a confirmação do protesto do título. |
| 500                      | BKS000105            | Internal Server Error | Could not fetch protest instrument for the given 'bank_slip_key' at this moment. Please, try again later. | Não foi possível recuperar o instrumento de protesto para a chave ('bank_slip_key') fornecida. Por favor, tente novamente mais tarde. |
| 404                      | BKS000106            | Not Found | No protest found for the given bank slip. | Nenhum protesto foi encontrado para o boleto fornecido. |

---

# Consulta de protesto por chave

URL: /documentation/boletos/instrucoes/protesto/consulta_por_chave

A consulta de um protesto, utilizando sua chave, retorna informações detalhadas a respeito do mesmo.

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /protest/ BANK_SLIP_KEY
MÉTODO GET

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36         |
| `bank_slip_key`         | uuidv4 | Chave única de identificação do boleto, no formato uuid v4   | 36         |

## Response

STATUS 200

Response Body

```json
{
  "protest_key": "bc34e9b1-42e4-4f17-bfc0-c88f29d5230e",
  "request_control_key": "59515878-50e9-466b-b40d-1aac3939c3fd",
  "protest_status": "protested",
  "bank_slip_key": "7d3d262b-9b55-44cd-8355-2f00d5b1d142",
  "requester_profile_code": "329-09-0001-1467576",
  "protest_type": "protest",
  "protocol_number": "0000672016",
  "protocol_date": "2012-12-16",
  "notary_office_code": 12345,
  "notary_office": {
    "city": "VITORIA",
    "uf": "ES"
  }
}
```

### Response Body Params

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `protest_key      ` *      | uuidv4  | Chave única de identificação do protesto no formato uuid v4                        | 36                                                |
| `request_control_key` *    | uuidv4  | Chave única de identificação da request utilizada pelo cliente no formato uuid v4  | 36                                                |
| `protest_status` *         | string  | Status do protesto                                                                 | **[Enumeradores protest_status](#enumeradores-protest_status)**   |
| `bank_slip_key` *          | uuidv4  | Chave única de identificação do boleto no formato uuid v4                          | 36                                                |
| `requester_profile_code` * | string  | Código único de identificação da carteira                                          | 10                                                |
| `protest_type` *           | string  | Tipo de protesto                                                                   | **[Enumeradores protest_type](#enumeradores-protest_type)**       |
| `protocol_number`          | string  | Número do protocolo                                                                | 10                                                |
| `protocol_date`            | string  | Data do protocolo (formato "AAAA-MM-DD")                                           | 10                                                |
| `notary_office_code`       | integer | Código de identificação do cartório de protesto                                   | -                                                 |
| `notary_office`            | object  | Dados do cartório de protesto                                                      | **[Objeto notary_office](#objeto-notary_office)**                         |

### Enumeradores protest_status

| Enumerador                   | Descrição                                                                      |
|------------------------------|--------------------------------------------------------------------------------|
| accepted                     | Aceito, mas ainda não enviado para os cartórios de protesto de títulos         |
| submitted                    | Enviado para o cartório                                                        |
| cancellation_requested       | Sustação de protesto solicitada                                                |
| cancelled                    | Envio cancelado, ou protesto sustado                                           |
| rejected                     | Pedido de protesto rejeitado                                                   |
| at_notary_office             | No cartório de protesto, em período de tríduo                                  |
| paid_at_notary_office        | Título pago em cartório                                                        |
| protested                    | Título protestado e baixado                                                    |
| removal_requested            | Título já protestado, com cancelamento solicitado                              |
| removed                      | Protesto cancelado                                                             |

### Enumeradores protest_type

| Enumerador                   | Descrição                                                                      |
|------------------------------|--------------------------------------------------------------------------------|
| protest                      | Protesto comum                                                                 |
| bankruptcy_protest           | Protesto falimentar                                                            |

### Objeto notary_office

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `city` *                   | string  | Cidade do cartório de protesto                                                     |  -                                                 |
| `uf` *                     | string  | Estado (UF) do cartório de protesto                                                | 2                                                 |

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (ptbr)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 404                      | BKS000006            | Not Found                                  | The source account key was not found.                                                                                | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                  | It was not possible to consult the source account at this time. Please try again in a few minutes.                                                                                      | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                                                                                    |
| 400                      | BKS000008            | Bad Request | The source account is closed.         |               A conta de origem está fechada.                                                                 |
| 400                      | BKS000009            | Bad Request | The source account is blocked.         |               A conta de origem está bloqueada.                                                                 |
| 404                      | BKS000013            | Not Found | Requester profile not found         |               Carteira não encontrada                                                                 |
| 404                      | BKS000029            | Not Found                                        | Bank slip not found for the given key (`{bank_slip_key}`).                                                              | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`).                          |
| 404                      | BKS000106            | Not Found | No protest found for the given bank slip. | Nenhum protesto foi encontrado para o boleto fornecido. |

---

# Desistência (sustação) de protesto

URL: /documentation/boletos/instrucoes/protesto/desistencia_de_protesto

É possível desistir de um pedido de protesto enviando uma instrução de `protest_cancel_request`.

:::caution Atenção!
A ocorrência de `protest_cancel_request`, por si só, não baixa o boleto. Se a saída do cartório for ocasionada por uma ocorrência do tipo `protest_cancel_request`, é criada outra ocorrência de `notary_office_exit`, a qual é enviada para a CIP/Nuclea para desbloquear o boleto para pagamento. Assim que ela é confirmada, o boleto volta a poder ser pago via linha digitável. Caso seja de interesse que o boleto seja baixado após a desistência de protesto, o ideal é enviar uma instrução de [**desistência de protesto e baixa do boleto**](/documentation/boletos/instrucoes/protesto/desistencia_de_protesto_e_baixa_do_boleto).
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /protest_cancel_request
MÉTODO POST

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36         |
| `bank_slip_key`         | uuidv4 | Chave única de identificação do boleto, no formato uuid v4   | 36         |

Request Body

```json
{
  "request_control_key": "614a451d-3b82-460e-bcc0-2caf3dde711f"
}
```

### Request Body Params

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` *    | uuidv4  | Chave única de identificação da request utilizada pelo cliente no formato uuid v4  | 36         |

## Response

STATUS 202

Response Body

```json
{
  "occurrence_key": "2552bd64-950b-437e-a53a-a133ffea03d7",
  "bank_slip_key": "960f78d4-4426-4762-98da-3ce3713ae0a5"
}
```

### Response Body Params

| Campo              | Tipo   | Descrição                                                                         | Caracteres |
|--------------------|--------|-----------------------------------------------------------------------------------|------------|
| `occurrence_key` * | uuidv4 | Chave única de identificação da ocorrência (instrução) no formato uuid v4         | 36         |
| `bank_slip_key` *  | uuidv4 | Chave única de identificação do boleto no formato uuid v4                         | 36         |

### Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 404                      | BKS000006            | Not Found                                  | The source account key was not found.                                                                                | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                  | It was not possible to consult the source account at this time. Please try again in a few minutes.                                                                                      | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                                                                                    |
| 400                      | BKS000008            | Bad Request | The source account is closed.         |               A conta de origem está fechada.                                                                 |
| 400                      | BKS000009            | Bad Request | The source account is blocked.         |               A conta de origem está bloqueada.                                                                 |
| 404                      | BKS000013            | Not Found | Requester profile not found         |               Carteira não encontrada                                                                 |
| 409                      | BKS000014            | Conflict | Request control key already sent or duplicated sent: `<request_control_key>` | Chave de controle da requisição já utilizada ou enviada duplicada: `<request_control_key>` |
| 400                      | BKS000019            | Bad Request | Payer address is required for protest. | Endereço do pagador é obrigatório para protesto. |
| 400                      | BKS000022            | Bad Request                                        | Requester profile is not opened.                                                              | Carteira não está aberta.                          |
| 404                      | BKS000029            | Not Found                                        | Bank slip not found for the given key (`{bank_slip_key}`).                                                              | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`).                          |
| 400                      | BKS000032            | Bad Request                                        | Bank slip must be in 'registered' status.                                                              | O boleto deve possuir o status 'registered'.                          |
| 400                      | BKS000076            | Bad Request | Bank slip must have an ongoing protest request. | O boleto deve ter um pedido de protesto em vigência. |
| 400                      | BKS000077            | Bad Request | Invalid bank slip protest status to cancel protest request. | Status de protesto do boleto inválido para desistir do pedido de protesto. |

---

# Desistência (sustação) de protesto e baixa do boleto

URL: /documentation/boletos/instrucoes/protesto/desistencia_de_protesto_e_baixa_do_boleto

Outra forma de desistir de um pedido de protesto é enviando uma instrução de `protest_cancel_and_write_off_request`.

:::caution Atenção!
A instrução de `protest_cancel_and_write_off_request` também baixa o boleto na CIP/Nuclea. Assim que ela é confirmada, é automaticamente criada uma ocorrência de `write_off` e a mesma é enviada para Nuclea.
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /protest_cancel_and_write_off_request
MÉTODO POST

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36         |
| `bank_slip_key`         | uuidv4 | Chave única de identificação do boleto, no formato uuid v4   | 36         |

Request Body

```json
{
  "request_control_key": "614a451d-3b82-460e-bcc0-2caf3dde711f"
}
```

### Request Body Params

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` *    | uuidv4  | Chave única de identificação da request utilizada pelo cliente no formato uuid v4  | 36         |

## Response

STATUS 202

Response Body

```json
{
  "occurrence_key": "2552bd64-950b-437e-a53a-a133ffea03d7",
  "bank_slip_key": "960f78d4-4426-4762-98da-3ce3713ae0a5"
}
```

### Response Body Params

| Campo              | Tipo   | Descrição                                                                         | Caracteres |
|--------------------|--------|-----------------------------------------------------------------------------------|------------|
| `occurrence_key` * | uuidv4 | Chave única de identificação da ocorrência (instrução) no formato uuid v4         | 36         |
| `bank_slip_key` *  | uuidv4 | Chave única de identificação do boleto no formato uuid v4                         | 36         |

### Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 404                      | BKS000006            | Not Found                                  | The source account key was not found.                                                                                | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                  | It was not possible to consult the source account at this time. Please try again in a few minutes.                                                                                      | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                                                                                    |
| 400                      | BKS000008            | Bad Request | The source account is closed.         |               A conta de origem está fechada.                                                                 |
| 400                      | BKS000009            | Bad Request | The source account is blocked.         |               A conta de origem está bloqueada.                                                                 |
| 404                      | BKS000013            | Not Found | Requester profile not found         |               Carteira não encontrada                                                                 |
| 409                      | BKS000014            | Conflict | Request control key already sent or duplicated sent: `<request_control_key>` | Chave de controle da requisição já utilizada ou enviada duplicada: `<request_control_key>` |
| 400                      | BKS000019            | Bad Request | Payer address is required for protest. | Endereço do pagador é obrigatório para protesto. |
| 400                      | BKS000022            | Bad Request                                        | Requester profile is not opened.                                                              | Carteira não está aberta.                          |
| 404                      | BKS000029            | Not Found                                        | Bank slip not found for the given key (`{bank_slip_key}`).                                                              | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`).                          |
| 400                      | BKS000032            | Bad Request                                        | Bank slip must be in 'registered' status.                                                              | O boleto deve possuir o status 'registered'.                          |
| 400                      | BKS000076            | Bad Request | Bank slip must have an ongoing protest request. | O boleto deve ter um pedido de protesto em vigência. |
| 400                      | BKS000077            | Bad Request | Invalid bank slip protest status to cancel protest request. | Status de protesto do boleto inválido para desistir do pedido de protesto. |

---

# Introdução

URL: /documentation/boletos/instrucoes/protesto/introducao

## Protesto em cartório

Um pedido de protesto em cartório pode ser feito após a data de vencimento do boleto, e serve para fazer com que o pagador seja intimado a pagar o título em cartório. Caso não o faça, é feito um registro público, em seu nome, da inadimplência, além de ter seu nome incluído em órgãos de proteção ao crédito, como a Serasa.

## Fluxo de protesto

### Pedido de protesto

O fluxo de protesto, para um boleto, é iniciado com um pedido de protesto : uma instrução do tipo `protest_request`. A partir do momento em que o pedido de protesto é aceito pela CIP/Nuclea (a instrução de `protest_request` é confirmada), o boleto passa a ficar bloqueado para pagamento, o que significa que o pagador passa a poder pagá-lo somente junto ao cartório. Além disso, também é criada uma ocorrência de `notary_office_entry`, que diz respeito ao envio do pedido de protesto para o cartório. As remessas de pedidos de protesto são enviados diariamente aos cartórios às 9 horas da manhã, portanto, caso sejam recebidas instruções de pedido de protesto após esse horário, elas são enviadas para os cartórios somente no dia seguinte.

Nos dias subsequentes, o cartório deve confirmar a entrada do título em cartório (a ocorrência de `notary_office_entry` é confirmada) e, com isso, inicia-se o período do tríduo. O tríduo é o prazo de 3 dias úteis para que o pagador pague o boleto no cartório sendo que, caso não o faça, o título será protestado. Se o título for pago em cartório, é criada ocorrência do tipo `notary_office_payment_notice` para o boleto em questão e o mesmo é liquidado no dia seguinte. Nesse último caso, também é gerada automaticamente uma instrução de `payment_write_off`, para que o boleto seja baixado junto à CIP/Nuclea.

Caso o período do tríduo termine e o boleto não seja pago e não haja desistência do protesto, o boleto é protestado. Nesse momento, é gerada uma instrução de `protest_write_off` para baixar o boleto na CIP/Nuclea, e encerra-se o ciclo de vida do título.

### Desistência (sustação) do pedido de protesto

Caso as questões referentes ao título sejam resolvidas diretamente entre o pagador e o sacador avalista, até o boleto ser de fato protestado (isto é, até o último dia do tríduo), é possível enviar uma instrução de `protest_cancel_request`, que desiste do pedido de protesto; ou uma instrução de `protest_cancel_and_write_off_request`, que desiste do pedido de protesto e também baixa o boleto na CIP/Nuclea. Vale ressaltar que a ocorrência de `protest_cancel_request`, por si só, não baixa o boleto. Se a saída do cartório for ocasionada por uma ocorrência do tipo `protest_cancel_request`, é criada outra ocorrência de `notary_office_exit`, a qual é enviada para a CIP/Nuclea para desbloquear o boleto para pagamento. Assim que ela é confirmada, o boleto volta a poder ser pago via linha digitável. Por outro lado, se a saída do cartório for ocasionada por uma ocorrência do tipo `protest_cancel_and_write_off_request`, é criada automaticamente uma ocorrência de `write_off`, a qual baixa o boleto na CIP/Nuclea.

### Remoção (cancelamento) do pedido de protesto

Caso a pendência entre o pagador e sacador avalista seja resolvida após o boleto já ter sido protestado, é possível enviar uma instrução do tipo `protest_remove_request`, a qual remove o registro público de inadimplência e qualquer registro, atrelado a esse boleto, que tenha sujado o nome do pagador. Caso a ocorrência seja confirmada (aceita pelo cartório), o protesto é removido e não é criada mais nenhuma instrução para este boleto, uma vez que ele já está baixado na CIP/Nuclea.

---

# Listar protestos

URL: /documentation/boletos/instrucoes/protesto/listar_protestos

A listagem de protestos retornará todos os protestos em cartório de boletos da carteira que se enquadrarem nos query parameters enviados na request.

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /protests
MÉTODO GET

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36         |

### Query parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres              |
|-------------------------|--------|--------------------------------------------------------------|-------------------------|
| `protest_key`           | uuidv4 | Chave única de identificação do protesto, no formato uuid v4 | 36                      |
| `request_control_key`   | uuidv4 | Chave única de identificação da request, no formato uuid v4  | 36                      |
| `protest_status`        | string | Status do protesto | **[Enumeradores protest_status](#enumeradores-protest_status)**   |
| `bank_slip_key`         | uuidv4 | Chave única de identificação do boleto, no formato uuid v4   | 36                      |
| `protocol_number`       | string | Número do protocolo                                          | 36                      |
| `protocol_date`         | string | Data do protocolo (formato "AAAA-MM-DD")                     | 10                      |
| `page_size`             | integer| Tamanho da página                                            | -                       |
| `from_date`             | string | Data inicial (formato "AAAA-MM-DD")                          | 10                      |
| `to_date`               | string | Data final (formato "AAAA-MM-DD")                            | 10                      |

### Enumeradores protest_status

| Enumerador                   | Descrição                                                                      |
|------------------------------|--------------------------------------------------------------------------------|
| accepted                     | Aceito, mas ainda não enviado para os cartórios de protesto de títulos         |
| submitted                    | Enviado para o cartório                                                        |
| cancellation_requested       | Sustação de protesto solicitada                                                |
| cancelled                    | Envio cancelado, ou protesto sustado                                           |
| rejected                     | Pedido de protesto rejeitado                                                   |
| at_notary_office             | No cartório de protesto, em período de tríduo                                  |
| paid_at_notary_office        | Título pago em cartório                                                        |
| protested                    | Título protestado e baixado                                                    |
| removal_requested            | Título já protestado, com cancelamento solicitado                              |
| removed                      | Protesto cancelado                                                             |

## Response

STATUS 200

Response Body

```json
{
    "data": [
        {
            "protest_key": "ad44278d-7cf1-4ac7-9545-410649a47dde",
            "request_control_key": "7e40ebab-f00c-4dbf-88be-ff34434ab358",
            "protest_status": "protested",
            "bank_slip_key": "7bf086ac-f520-4498-abd4-5a7d2173fd1c",
            "requester_profile_code": "329-09-0001-1467576",
            "protest_type": "protest",
            "protocol_number": "0000000004",
            "protocol_date": "2024-11-27",
            "notary_office": {
                "city": "SAO PAULO",
                "uf": "SP"
            }
        },
        {
            "protest_key": "0087f425-5e54-4b4c-ab17-a57bc80f223a",
            "request_control_key": "c413cedc-78ac-4deb-ace8-d94d4e98197c",
            "protest_status": "at_notary_office",
            "bank_slip_key": "e345c0b3-012b-4a4b-9d6b-6981f40b1a7c",
            "requester_profile_code": "329-09-0001-1467576",
            "protest_type": "protest",
            "protocol_number": "0000000016",
            "protocol_date": "2024-12-10",
            "notary_office": {
                "city": "RIO DE JANEIRO",
                "uf": "RJ"
            }
        },
        {
            "protest_key": "bc34e9b1-42e4-4f17-bfc0-c88f29d5230e",
            "request_control_key": "59515878-50e9-466b-b40d-1aac3939c3fd",
            "protest_status": "accepted",
            "bank_slip_key": "7d3d262b-9b55-44cd-8355-2f00d5b1d142",
            "requester_profile_code": "329-09-0001-1467576",
            "protest_type": "protest"
        }
    ],
    "pagination": {
        "current_page": 1,
        "rows_per_page": 100
    }
}
```

### Response Body Params

| Campo            | Tipo         | Descrição                             | Caracteres                                  |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `data` *         | object array | Protestos                             | **[Objeto protest](#objeto-protest)**       |
| `pagination` *   | object       | Informações de paginação              | **[Objeto pagination](#objeto-pagination)** |

### Objeto protest

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `protest_key      ` *      | uuidv4  | Chave única de identificação do protesto no formato uuid v4                        | 36                                                |
| `request_control_key` *    | uuidv4  | Chave única de identificação da request utilizada pelo cliente no formato uuid v4  | 36                                                |
| `protest_status` *         | string  | Status do protesto                                                                 | **[Enumeradores protest_status](#enumeradores-protest_status)**   |
| `bank_slip_key` *          | uuidv4  | Chave única de identificação do boleto no formato uuid v4                          | 36                                                |
| `requester_profile_code` * | string  | Código único de identificação da carteira                                          | 10                                                |
| `protest_type` *           | string  | Tipo de protesto                                                                   | **[Enumeradores protest_type](#enumeradores-protest_type)**       |
| `protocol_number`          | string  | Número do protocolo                                                                | 10                                                |
| `protocol_date`            | string  | Data do protocolo (formato "AAAA-MM-DD")                                           | 10                                                |
| `notary_office`            | object  | Dados do cartório de protesto                                                      | **[Objeto notary_office](#objeto-notary_office)**                         |

### Objeto pagination

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `current_page` *           | integer | Página atual                                                 | -      |
| `rows_per_page` *          | integer | Itens por página                                             | -      |

### Enumeradores protest_type

| Enumerador                   | Descrição                                                                      |
|------------------------------|--------------------------------------------------------------------------------|
| protest                      | Protesto comum                                                                 |
| bankruptcy_protest           | Protesto falimentar                                                            |

### Enumeradores protest_status

| Enumerador                   | Descrição                                                                      |
|------------------------------|--------------------------------------------------------------------------------|
| accepted                     | Aceito, mas ainda não enviado para os cartórios de protesto de títulos         |
| submitted                    | Enviado para o cartório                                                        |
| cancellation_requested       | Sustação de protesto solicitada                                                |
| cancelled                    | Envio cancelado, ou protesto sustado                                           |
| rejected                     | Pedido de protesto rejeitado                                                   |
| at_notary_office             | No cartório de protesto, em período de tríduo                                  |
| paid_at_notary_office        | Título pago em cartório                                                        |
| protested                    | Título protestado e baixado                                                    |
| removal_requested            | Título já protestado, com cancelamento solicitado                              |
| removed                      | Protesto cancelado                                                             |

### Objeto notary_office

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `city` *                   | string  | Cidade do cartório de protesto                                                     |  -                                                 |
| `uf` *                     | string  | Estado (UF) do cartório de protesto                                                | 2                                                 |

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 403                      | BKS000005            | Forbidden                         | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404                      | BKS000006            | Not Found                                  | The source account key was not found.                                                                                | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                  | It was not possible to consult the source account at this time. Please try again in a few minutes.                                                                                      | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                                                                                    |
| 400                      | BKS000008            | Bad Request | The source account is closed.         |               A conta de origem está fechada.                                                                 |
| 400                      | BKS000009            | Bad Request | The source account is blocked.         |               A conta de origem está bloqueada.                                                                 |
| 400                      | BKS000012            | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
| 404                      | BKS000013            | Not Found | Requester profile not found         |               Carteira não encontrada                                                                 |

---

# Pedido de protesto

URL: /documentation/boletos/instrucoes/protesto/pedido_de_protesto

Um pedido de protesto em cartório pode ser feito após a data de vencimento do boleto, e serve para fazer com que o pagador seja intimado a pagar o título em cartório. Caso não o faça, é feito um registro público, em seu nome, da inadimplência, além de ter seu nome incluído em órgãos de proteção ao crédito, como a Serasa.

:::caution Atenção!
Para enviar um pedido de protesto, é obrigatório que o endereço do pagador esteja presente no boleto. Caso não esteja, é possível enviar uma instrução de edição do boleto. Ademais, caso exista um boleto esteja em fluxo de protesto, não é permitido o envio de um novo pedido.
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /protest_request
MÉTODO POST

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36         |
| `bank_slip_key`         | uuidv4 | Chave única de identificação do boleto, no formato uuid v4   | 36         |

Request Body

```json
{
  "request_control_key": "614a451d-3b82-460e-bcc0-2caf3dde711f",
  "protest_type": "protest"
}
```

### Request Body Params

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` *    | uuidv4  | Chave única de identificação da request utilizada pelo cliente no formato uuid v4  | 36         |
| `protest_type` *           | string  | Tipo de protesto (comum ou falimentar)                                             | **[Enumeradores protest_type](#enumeradores-protest_type)** |

### Enumeradores protest_type

| Enumerador                                  | Descrição                                                                |
|---------------------------------------------|--------------------------------------------------------------------------|
| protest                                     | Protesto comum                                                           |
| bankruptcy_protest                          | Protesto falimentar                                                      |

## Response

STATUS 202

Response Body

```json
{
  "occurrence_key": "2552bd64-950b-437e-a53a-a133ffea03d7",
  "bank_slip_key": "960f78d4-4426-4762-98da-3ce3713ae0a5"
}
```

### Response Body Params

| Campo              | Tipo   | Descrição                                                                         | Caracteres |
|--------------------|--------|-----------------------------------------------------------------------------------|------------|
| `occurrence_key` * | uuidv4 | Chave única de identificação da ocorrência (instrução) no formato uuid v4         | 36         |
| `bank_slip_key` *  | uuidv4 | Chave única de identificação do boleto no formato uuid v4                         | 36         |

### Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 404                      | BKS000006            | Not Found                                  | The source account key was not found.                                                                                | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                  | It was not possible to consult the source account at this time. Please try again in a few minutes.                                                                                      | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                                                                                    |
| 400                      | BKS000008            | Bad Request | The source account is closed.         |               A conta de origem está fechada.                                                                 |
| 400                      | BKS000009            | Bad Request | The source account is blocked.         |               A conta de origem está bloqueada.                                                                 |
| 404                      | BKS000013            | Not Found | Requester profile not found         |               Carteira não encontrada                                                                 |
| 409                      | BKS000014            | Conflict | Request control key already sent or duplicated sent: `<request_control_key>` | Chave de controle da requisição já utilizada ou enviada duplicada: `<request_control_key>` |
| 400                      | BKS000019            | Bad Request | Payer address is required for protest. | Endereço do pagador é obrigatório para protesto. |
| 400                      | BKS000022            | Bad Request                                        | Requester profile is not opened.                                                              | Carteira não está aberta.                          |
| 404                      | BKS000028            | Not Found | Notary office attended region not found for postal code: `<postal_code>` | Região de cartório não encontrada para o CEP: `<postal_code>` |
| 404                      | BKS000029            | Not Found                                        | Bank slip not found for the given key (`{bank_slip_key}`).                                                              | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`).                          |
| 400                      | BKS000032            | Bad Request                                        | Bank slip must be in 'registered' status.                                                              | O boleto deve possuir o status 'registered'.                          |
| 409                      | BKS000075            | Conflict                                        | An open protest request already exists for the given 'bank_slip_key'.                                                              | Já existe um pedido de protesto em aberto para a 'bank_slip_key' fornecida.                          |
| 400                      | BKS000080            | Bad Request                                        | A protest request can only be sent after bank slip's business expiration date.                                                              | Um pedido de protesto só pode ser enviado após o dia útil de expiração do boleto.                          |

---

# Sustação de protesto

URL: /documentation/boletos/instrucoes/protesto/sustacao_de_protesto

Caso a pendência entre o pagador e sacador avalista seja resolvida após o boleto já ter sido protestado, é possível enviar uma instrução do tipo `protest_remove_request`, a qual remove o registro público de inadimplência e qualquer registro, atrelado a esse boleto, que tenha sujado o nome do pagador.

:::caution Atenção!
Caso a ocorrência seja confirmada (aceita pelo cartório), o protesto é removido e não é criada mais nenhuma instrução para este boleto, uma vez que ele já está baixado na CIP/Nuclea.
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /protest_remove_request
MÉTODO POST

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36         |
| `bank_slip_key`         | uuidv4 | Chave única de identificação do boleto, no formato uuid v4   | 36         |

Request Body

```json
{
  "request_control_key": "614a451d-3b82-460e-bcc0-2caf3dde711f"
}
```

### Request Body Params

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` *    | uuidv4  | Chave única de identificação da request utilizada pelo cliente no formato uuid v4  | 36         |

## Response

STATUS 202

Response Body

```json
{
  "occurrence_key": "2552bd64-950b-437e-a53a-a133ffea03d7",
  "bank_slip_key": "960f78d4-4426-4762-98da-3ce3713ae0a5"
}
```

### Response Body Params

| Campo              | Tipo   | Descrição                                                                         | Caracteres |
|--------------------|--------|-----------------------------------------------------------------------------------|------------|
| `occurrence_key` * | uuidv4 | Chave única de identificação da ocorrência (instrução) no formato uuid v4         | 36         |
| `bank_slip_key` *  | uuidv4 | Chave única de identificação do boleto no formato uuid v4                         | 36         |

### Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 404                      | BKS000006            | Not Found                                  | The source account key was not found.                                                                                | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                  | It was not possible to consult the source account at this time. Please try again in a few minutes.                                                                                      | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                                                                                    |
| 400                      | BKS000008            | Bad Request | The source account is closed.         |               A conta de origem está fechada.                                                                 |
| 400                      | BKS000009            | Bad Request | The source account is blocked.         |               A conta de origem está bloqueada.                                                                 |
| 404                      | BKS000013            | Not Found | Requester profile not found         |               Carteira não encontrada                                                                 |
| 409                      | BKS000014            | Conflict | Request control key already sent or duplicated sent: `<request_control_key>` | Chave de controle da requisição já utilizada ou enviada duplicada: `<request_control_key>` |
| 400                      | BKS000019            | Bad Request | Payer address is required for protest. | Endereço do pagador é obrigatório para protesto. |
| 400                      | BKS000022            | Bad Request                                        | Requester profile is not opened.                                                              | Carteira não está aberta.                          |
| 404                      | BKS000029            | Not Found                                        | Bank slip not found for the given key (`{bank_slip_key}`).                                                              | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`).                          |
| 400                      | BKS000032            | Bad Request                                        | Bank slip must be in 'registered' status.                                                              | O boleto deve possuir o status 'registered'.                          |
| 400                      | BKS000076            | Bad Request | Bank slip must have an ongoing protest request. | O boleto deve ter um pedido de protesto em vigência. |
| 400                      | BKS000078            | Bad Request | Bank slip's protest_status must be 'protested' to send a protest remove request. | Status de protesto (protest_status) do boleto deve ser 'protested' para enviar um pedido de remoção de protesto. |

---

# Atualização de Rateio de Crédito

URL: /documentation/boletos/instrucoes/rateio_de_credito

Este endpoint permite atualizar o **rateio de crédito** (split de pagamento) de um boleto previamente emitido. As novas regras substituem integralmente as anteriores e passam a valer para a próxima liquidação do boleto.

:::caution Atenção!
- O boleto precisa estar com o status `registered` e ainda não pago.
- A soma de `beneficiary_settlement_percentage` com os percentuais de cada item de `split_payment_rules` deve ser exatamente igual a **100**.
- O envio do payload **substitui** todas as regras de rateio existentes (não é incremental).
- O rateio passa a valer para todos os fluxos de liquidação do boleto (SILOC, STR, cartório e Pix QR Code), inclusive em boletos com QR Code já emitido — neste caso, as regras também serão atualizadas no QR Code automaticamente.
- As contas das regras de rateio precisam estar abertas e cadastradas na QI Tech (a QI Tech consultará pelo `document_number`, `account_number` e `account_digit` informados).
:::

## Request

ENDPOINT /v2/bank_slip/account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /split_payment
MÉTODO PUT

### Path parameters

| Campo                   | Tipo   | Descrição                                                         | Caracteres |
|-------------------------|--------|-------------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta em que o boleto foi emitido | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira                          | 36         |
| `bank_slip_key`         | uuidv4 | Chave única de identificação do boleto                            | 36         |

Request Body

```json
{
  "beneficiary_settlement_percentage": 70,
  "split_payment_rules": [
    {
      "percentage": 20,
      "document_number": "12345678901",
      "account_owner_name": "João da Silva",
      "account_number": "1234567",
      "account_digit": "8"
    },
    {
      "percentage": 10,
      "document_number": "10987654321",
      "account_owner_name": "Maria Souza",
      "account_number": "7654321",
      "account_digit": "0"
    }
  ]
}
```

### Request Body Params

| Campo                                  | Tipo         | Descrição                                                                                          | Caracteres |
|----------------------------------------|--------------|----------------------------------------------------------------------------------------------------|------------|
| `beneficiary_settlement_percentage` *  | float        | Percentual do valor liquidado destinado ao beneficiário do boleto. Aceita valor de 0 a 100         | -          |
| `beneficiary_max_amount`               | float        | Valor máximo que o beneficiário recebe na liquidação. Quando o valor pago exceder este limite, o excedente é direcionado integralmente para a primeira regra do array `split_payment_rules`. Aceita valor maior que 0 e menor ou igual ao valor do boleto | - |
| `split_payment_rules` *                | object array | Lista de regras de rateio. Mínimo 1, máximo 10 regras                                              | **[Objeto split_payment_rule](#objeto-split_payment_rule)** |

### Objeto split_payment_rule

| Campo                  | Tipo    | Descrição                                                                                | Caracteres |
|------------------------|---------|------------------------------------------------------------------------------------------|------------|
| `percentage` *         | float   | Percentual do valor liquidado destinado a esta conta. Aceita valor de 0 a 100. Use `0` quando esta regra for destinada exclusivamente a receber o excedente do `beneficiary_max_amount` | - |
| `document_number` *    | string  | CPF/CNPJ do titular da conta destino                                                     | 11 ou 14   |
| `account_owner_name` * | string  | Nome do titular da conta destino                                                         | 100        |
| `account_number` *     | string  | Número da conta destino                                                                  | 20         |
| `account_digit` *      | string  | Dígito verificador da conta destino                                                      | 2          |

## Caso de uso: receber juros e multa em uma conta separada

> **Como configurar para que o juros e multa que excederem o valor de face do boleto sejam direcionados a uma conta diferente do beneficiário?**

Esse cenário é comum em plataformas que emitem boletos em nome de terceiros (escolas, condomínios, marketplaces), onde o titular do boleto deve receber sempre o valor de face e a plataforma fica com a parcela adicional de juros/multa em casos de pagamento em atraso.

A configuração é feita combinando `beneficiary_max_amount` com uma regra de rateio com `percentage = 0`:

```json
{
  "beneficiary_settlement_percentage": 100,
  "beneficiary_max_amount": 1000.00,
  "split_payment_rules": [
    {
      "percentage": 0,
      "document_number": "12345678000199",
      "account_owner_name": "Plataforma de Cobrança",
      "account_number": "1234567",
      "account_digit": "8"
    }
  ]
}
```

**Como o cálculo funciona** considerando um boleto de R$ 1.000,00:

| Cenário | Valor pago | Beneficiário recebe | Plataforma recebe |
|---|---|---|---|
| Pagamento em dia | R$ 1.000,00 | R$ 1.000,00 | R$ 0,00 (sem settlement gerado) |
| Pagamento em atraso (com R$ 100,00 de juros/multa) | R$ 1.100,00 | R$ 1.000,00 | R$ 100,00 |
| Pagamento parcial em atraso | R$ 950,00 | R$ 950,00 | R$ 0,00 |

A regra é: o beneficiário recebe **no máximo** `beneficiary_max_amount`; qualquer valor pago acima disso é direcionado integralmente para a **primeira** regra de `split_payment_rules`.

:::caution Atenção!
- `beneficiary_max_amount` deve ser maior que 0 e menor ou igual ao valor do boleto (`amount`).
- Quando alguma regra tem `percentage = 0`, o campo `beneficiary_max_amount` é obrigatório.
- Apenas **uma** regra de `split_payment_rules` pode ter `percentage = 0` por boleto (a destinatária do excedente).
:::

## Response

STATUS 204

Response Body

```json
{}
```

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`        | Descrição (eng)<br/>`description`                                                            | Descrição (pt-br)<br/>`translation`                                                                       |
|--------------------------|----------------------|---------------------------|----------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request               | Schema Error                                                                                 | Schema Inválido                                                                                           |
| 404                      | BKS000029            | Not Found                 | Bank slip not found for the given key (`{bank_slip_key}`).                                   | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`).                                         |
| 400                      | BKS000032            | Bad Request               | Bank slip must be in 'registered' status.                                                    | O boleto deve possuir o status 'registered'.                                                              |
| 422                      | BKS000157            | Unprocessable Entity      | Could not find an account matching the provided split payment account data.                 | Não foi possível encontrar uma conta com os dados informados na regra de split payment.                   |
| 400                      | BKS000158            | Bad Request               | The beneficiary_max_amount must be greater than 0 and not greater than the bank slip amount. | O beneficiary_max_amount deve ser maior que 0 e não pode ser maior que o valor do boleto.                 |
| 400                      | BKS000159            | Bad Request               | Split payment rules with percentage equal to 0 require beneficiary_max_amount to be set.     | Regras de split payment com percentual igual a 0 exigem o campo beneficiary_max_amount preenchido.        |
| 400                      | BKS000160            | Bad Request               | Only one split payment rule with percentage equal to 0 is allowed.                           | É permitido apenas uma regra de split payment com percentual igual a 0.                                   |

---

# Valor

URL: /documentation/boletos/instrucoes/valor

A instrução de valor permite alterar o valor de um boleto, desde que o boleto já tenha sido registrado. Caso já exista uma instrução de valor pendente de confirmação para o boleto em questão, não é permitido o envio de uma nova instrução.

:::caution Atenção!
Caso exista alguma instrução de valor pendente de confirmação, não é permitido o envio de uma nova instrução.
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /amount
MÉTODO POST

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36         |
| `bank_slip_key`         | uuidv4 | Chave única de identificação do boleto, no formato uuid v4   | 36         |

Request Body

```json
{
    "request_control_key": "01234567-89ab-cdef-0123-456789abcdef",
    "amount": 150.50
}
```

### Request Body Params

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key` *    | uuidv4  | Chave única de identificação da request utilizada pelo cliente no formato uuid v4  | 36         |
| `amount` *                 | number  | Novo valor do boleto (deve ser diferente do valor atual)                           | -          |

:::caution Atenção!
O valor deve ser diferente do valor atual do boleto e deve ter no máximo 2 casas decimais.
:::

## Response

STATUS 202

Response Body

```json
{
  "occurrence_key": "5a745b65-9a2c-44eb-b43e-c80ef5429d94",
  "bank_slip_key": "fdafdffa-cbd4-4f3c-8e3d-990428305161"
}
```

### Response Body Params

| Campo              | Tipo   | Descrição                                                                         | Caracteres |
|--------------------|--------|-----------------------------------------------------------------------------------|------------|
| `occurrence_key` * | uuidv4 | Chave única de identificação da ocorrência (instrução) no formato uuid v4         | 36         |
| `bank_slip_key` *  | uuidv4 | Chave única de identificação do boleto no formato uuid v4                         | 36         |

### Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 404                      | BKS000006            | Not Found                                  | The source account key was not found.                                                                                | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                  | It was not possible to consult the source account at this time. Please try again in a few minutes.                                                                                      | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                                                                                    |
| 400                      | BKS000008            | Bad Request | The source account is closed.         |               A conta de origem está fechada.                                                                 |
| 400                      | BKS000009            | Bad Request | The source account is blocked.         |               A conta de origem está bloqueada.                                                                 |
| 404                      | BKS000013            | Not Found | Requester profile not found         |               Carteira não encontrada                                                                 |
| 409                      | BKS000014            | Conflict | Request control key already sent or duplicated sent: `<request_control_key>` | Chave de controle da requisição já utilizada ou enviada duplicada: `<request_control_key>` |
| 400                      | BKS000022            | Bad Request                                        | Requester profile is not opened.                                                              | Carteira não está aberta.                          |
| 404                      | BKS000029            | Not Found                                        | Bank slip not found for the given key (`{bank_slip_key}`).                                                              | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`).                          |
| 400                      | BKS000032            | Bad Request                                        | Bank slip must be in 'registered' status.                                                              | O boleto deve possuir o status 'registered'.                          |
| 409                      | BKS000135            | Conflict                                        | An amount occurrence already exists for this bank slip.                                                              | Já existe uma ocorrência de valor para este boleto.                          |
| 400                      | BKS000136            | Bad Request                                        | Only credit card financial instrument type can have zero amount.                                                              | Apenas o tipo de instrumento financeiro cartão de crédito pode ter valor zero.                          |
| 400                      | BKS000137            | Bad Request                                        | Amount must be different from bank slip amount.                                                              | O valor deve ser diferente do valor do boleto.                          |

---

# Introdução

URL: /documentation/boletos/introducao

## Boleto bancário

Um boleto bancário geralmente está relacionado a cobranças. São caracterizados por terem linhas digitáveis que não são iniciadas com dígito 8. Possui registro na Câmara Interbancária de Pagamento (CIP/Núclea) e pode ser pago em instituições financeiras e de pagamento autorizadas a funcionar pelo Banco Central.

## Carteira de cobrança

De antemão, vale ressaltar que, nessa documentação, as carteiras de cobrança são chamadas de `requester_profile`. A carteira de cobrança está necessariamente relacionada a uma conta e carrega configurações padrão específicas (de juros, multa, protesto etc.) no que diz respeito ao registro de boletos. Uma vez atribuídas tais configurações padrão --- na criação ou edição da carteira de cobrança ---, sempre que o usuário registrar um boleto, sem mandar alguma dessas configurações, será utilizada a configuração padrão para o parâmetro em questão.

:::info Exemplo
Ao criar a carteira de cobrança, o usuário enviou uma configuração de multa para a carteira que faz com que, caso o pagador atrase o pagamento em 5 dias ou mais, será cobrado R$10,00 de multa. Ao registrar o boleto, essa configuração pode ser sobrescrita; por exemplo, pode-se optar por cobrar uma multa de R$15,00, ou até mesmo não cobrar multa nenhuma. No entanto, caso tal configuração não seja sobrescrita no momento do registro do boleto, valerá a configuração padrão da carteira (a aplicação dos R$10,00 de multa, caso o pagador atrase mais de 5 dias no pagamento).
:::

É possível criar várias carteiras de cobrança para uma mesma conta, e uma carteira inicial --- sem nenhuma configuração padrão ---, é criada juntamente com a abertura de conta na QI Tech. A possibilidade de se criar várias carteiras de cobrança permite a criação de diferentes carteiras com diferentes configurações padrão; e as configurações padrão, por sua vez, facilitam o registro de vários boletos com configurações em comum, uma vez que configurações de multa, juros etc. não precisam ser enviadas sempre que se deseja registrar um boleto.

## Máquina de estados do boleto

Os boletos, ao longo de seu ciclo de vida, podem passar pelos seguintes status:

| Enumerador                    | Tradução                 | Descrição                                                                    |
|-------------------------------|--------------------------|------------------------------------------------------------------------------|
| accepted                      | aceito                   | Boleto aceito e pendente de confirmação junto à CIP/Nuclea                   |
| rejected                      | rejeitado                | O registro do boleto não foi aceito                                          |
| registered                    | registrado               | Boleto registrado junto à CIP/Nuclea                                         |
| payment_blocked               | bloqueado para pagamento | Boleto bloqueado para pagamento na CIP/Nuclea por estar em fluxo de protesto |
| written_off                   | baixado                  | Boleto baixado (não está mais disponível para pagamento)                     |
| payment_notice                | pagamento notificado     | O boleto pago e baixado, mas ainda sem liquidação financeira                 |
| paid                          | pago                     | Boleto pago, baixado e liquidado financeiramente                             |

### Transições de estado

- `accepted` -> `rejected`: registro do boleto não foi aceito junto à CIP/Nuclea;
- `accepted` -> `registered`: registro do boleto aceito junto à CIP/Nuclea;
- `registered` -> `written_off`: boleto foi baixado sem ser pago;
- `registered` -> `payment_notice`: boleto foi pago e baixado, mas ainda não foi liquidado financeiramente;
- `payment_notice` -> `paid`: após o pagamento, boleto foi liquidado financeiramente;
- `registered` -> `payment_blocked`: pagamento do boleto foi bloqueado, devido ao início de um fluxo de protesto;
- `payment_blocked` -> `notary_office_payment_notice`: boleto foi pago em cartório e baixado, mas ainda não foi liquidado financeiramente;
- `notary_office_payment_notice` -> `paid`: após o pagamento em cartório, boleto foi liquidado financeiramente;
- `payment_blocked` -> `written_off`: boleto foi protestado.

:::caution Atenção
Para boletos com configurações de pagamento parcial, a transição de status funciona de maneira diferente. Após receber um pagamento, os boletos com configurações de pagamento parcial continuam no status de `registered` caso o pagamento enviado pelo outro banco tenha sido uma baixa parcial interbancária. Você receberá os webhooks de [payment notice](/documentation/boletos/webhooks/boleto) e [payment](/documentation/boletos/webhooks/boleto) normalmente, porém o boleto continua no status de `registered`. O boleto só mudará para o status de `payment_notice` e posteriormente para `paid` caso uma baixa integral interbancária seja enviada pelo banco pagante junto à CIP/Núclea. Caso queira baixar o boleto a qualquer momento ou quando o valor total tenha sido pago, mas nenhuma baixa integral interbancária tenha sido enviada pela outra instituição, você pode enviar uma [ocorrência de baixa](/documentation/boletos/instrucoes/baixa).

Para boletos do tipo **cartão de crédito** (`credit_card`), é importante observar que estes não recebem baixa integral interbancária. Portanto, será sempre de responsabilidade do cliente realizar a baixa manual do boleto, ou o mesmo será baixado automaticamente D+7 após a data máxima de pagamento (conforme configuração de `max_payment_days`).
:::

## Registro de boletos

### Via API

Fluxo de registro padrão

Caso o sistema receba uma requisição de registro de boleto pelo [**fluxo de registro padrão**](/documentation/boletos/emissao/emissao_boleto_unico_padrao), e tal requisição seja aceita --- isto é, caso não haja nenhuma inconsistência com as informações enviadas ---, será devolvido como resposta um boleto com o status `accepted`, mas ainda não é certeza de que o mesmo será de fato registrado. Após o envio do boleto para a CIP/Nuclea e o recebimento da resposta, o boleto passa para o status `rejected` ou para o status `accepted`.

Fluxo de registro em lote

A emissão de boletos em lote é feita de forma assíncrona, onde, se algum boleto falhar na validação, nenhum será registrado. O solicitante é notificado via [**webhook**](/documentation/boletos/v2/webhooks/boleto) quando os boletos mudam de status. Para mais detalhes, consulte a [**documentação completa**](/documentation/boletos/emissao/emissao_em_lote).

Fluxo de registro instantâneo

Há também uma outra opção para o registro de boletos: o [**fluxo de registro instantâneo**](/documentation/boletos/emissao/emissao_boleto_unico_instantanea). Nesse fluxo, o registro do boleto é processado de maneira síncrona e a resposta da API já retorna a informação se o boleto foi aceito ou rejeitado; ou seja, é devolvido como resposta um boleto que já possui status `accepted` ou `rejected`. O tempo de confirmação/rejeição da Nuclea/CIP, a respeito do registro do boleto, está incluso no tempo de resposta desse endpoint.

### Via arquivo de remessa

A solicitação de registro de boletos via arquivo surte exatamente o mesmo resultado final do registro via API. A diferença é que, quando registrando via arquivo, deve-se considerar o tempo de processamento do arquivo no tempo total para registro do boleto. Portanto, geralmente trata-se de um registro mais demorado do que o registro via API.

Em contrapartida, ao registrar via arquivo, é possível registrar um volume muito alto de boletos de uma vez só.

---

# Listar grupos de liquidação

URL: /documentation/boletos/liquidacao/listar_grupos_de_liquidacao

:::info Informação
Em nosso sistema, os grupos de liquidação são uma forma de conciliar as transações com os boletos liquidados. Esse processo (liquidação) descreve a transferência do valor de um boleto pago para a conta que deve receber esse pagamento. Resumidamente, sempre que a QI recebe a informação de que um boleto foi pago por outro banco ou, no caso de boletos protestados, pelo cartório, é criada uma liquidação para esse boleto específico. Posteriormente, são criados os **grupos de liquidação**, que representam lotes de liquidações agrupadas por tipo.

Em um momento posterior, é realizada a transação de pagamento desse grupo de liquidação para a conta do cliente. A **transaction_key** dessa transação é então salva para fins de conciliação, dessa foma você pode ver todos os boletos que foram liquidados em uma determinada transação. Por exemplo, se você tiver cinco boletos de R$ 5,00 cada, sendo que um foi pago via cartório, um foi pago via QR Code PIX e os outros três foram pagos utilizando a linha digitável ou código de barras por outro banco, serão criadas cinco liquidações referentes a esses boletos. Em seguida, essas liquidações serão agrupadas em três grupos de liquidação: um de R$ 15,00 com os três boletos pagos utilizando a linha digitável ou código de barras, para os quais será realizada uma única transação, outro de R$ 5,00 para o boleto pago via QR Code PIX e o último também de R$ 5,00 com o boleto pago via cartório.
:::

A listagem de grupos de liquidação retornará todos os grupos de liquidação da conta que se enquadrarem nos query parameters enviados na request.

## Request

ENDPOINT /account/ ACCOUNT_KEY /bank_slip_settlement_groups
MÉTODO GET

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta    | 36         |

### Query parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres              |
|-------------------------|--------|--------------------------------------------------------------|-------------------------|
| `bank_slip_settlement_group_key`         | uuidv4 | Chave única de identificação do grupo de liquidação   | 36                      |
| `transaction_key`             | uuidv4 | Chave única de identificação da transação do grupo de liquidação                           | 36                                                |
| `bank_slip_settlement_group_status`      | string | Status do grupo de liquidação | **[Enumeradores bank_slip_settlement_group_status](#enumeradores-bank_slip_settlement_group_status)** |
| `date_from`            | string    | Data inicial. Formato "YYYY-MM-DD".                                      |
| `date_to`              | string    | Data final. Formato "YYYY-MM-DD".                                        |
| `page`                  | integer| Número da página                                             | -                       |
| `page_size`             | integer| Tamanho da página                                            | -                       |

## Response

STATUS 200

Response Body

```json
{
    "data": [
        {
            "bank_slip_settlement_group_key": "5ba0b0cf-ac4a-4c91-819d-d6c46d70e3ab",
            "account_key": "96015228-4905-42fc-bda6-e70e0e552b6b",
            "transaction_key": "6704d927-9e0d-411d-8c44-c377c0c56637",
            "amount": 1069.24,
            "bank_slip_settlement_group_type": "notary_office",
            "bank_slip_settlement_group_status": "settled",
            "bank_slip_settlement_quantity": 1
        },
        {
            "bank_slip_settlement_group_key": "feda6069-c0cf-4148-b881-a475737330ab",
            "account_key": "96015228-4905-42fc-bda6-e70e0e552b6b",
            "transaction_key": "00d557de-78ca-4871-b254-2852499660e2",
            "amount": 2400.0,
            "bank_slip_settlement_group_type": "siloc",
            "bank_slip_settlement_group_status": "settled",
            "bank_slip_settlement_quantity": 303
        },
        {
            "bank_slip_settlement_group_key": "5493030c-ba1c-44de-9e85-5aaee0afe46d",
            "account_key": "96015228-4905-42fc-bda6-e70e0e552b6b",
            "transaction_key": "b42c4d0a-8060-41d7-bd00-17889cc76485",
            "amount": 250.0,
            "bank_slip_settlement_group_type": "siloc",
            "bank_slip_settlement_group_status": "settled",
            "bank_slip_settlement_quantity": 50
        },
        {
            "bank_slip_settlement_group_key": "f33c087d-cbae-47a9-bd5a-e6a8ecc04ed2",
            "account_key": "96015228-4905-42fc-bda6-e70e0e552b6b",
            "transaction_key": "6ee57aea-b589-4dff-9555-200c34380154",
            "amount": 4024800.0,
            "bank_slip_settlement_group_type": "str",
            "bank_slip_settlement_group_status": "settled",
            "bank_slip_settlement_quantity": 16
        },
        {
            "bank_slip_settlement_group_key": "27b9b2b7-549e-406e-9f41-c71e0cb08b00",
            "account_key": "96015228-4905-42fc-bda6-e70e0e552b6b",
            "transaction_key": "36aa7a00-6741-41d5-99e9-ce620fed5823",
            "amount": 300.0,
            "bank_slip_settlement_group_type": "split_payment",
            "bank_slip_settlement_group_status": "settled",
            "bank_slip_settlement_quantity": 1,
            "settlement_date": "2026-04-23"
        }
    ],
    "pagination": {
        "current_page": 1,
        "rows_per_page": 100
    }
}
```

### Response Body Params

| Campo            | Tipo         | Descrição                             | Caracteres                                  |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `data`          | object array | Boletos                               | **[Objeto bank_slip_settlement_group](#objeto-bank_slip_settlement_group)**   |
| `pagination`    | object       | Informações de paginação              | **[Objeto pagination](#objeto-pagination)** |

### Objeto bank_slip_settlement_group

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `bank_slip_settlement_group_key      `     | uuidv4  | Chave única de identificação do boleto no formato uuid v4                          | 36                                                |
| `account_key`     | uuidv4  | Chave única de identificação da conta | 36                                                |
| `transaction_key`             | uuidv4 | Chave única de identificação da transação do grupo de liquidação                           | 36                                                |
| `amount`                  | float   | Valor total liquidado                                                               | -
| `bank_slip_settlement_group_type`      | string | Tipo do grupo de liquidação | **[Enumeradores bank_slip_settlement_group_type](#enumeradores-bank_slip_settlement_group_type)** |
| `bank_slip_settlement_group_status`      | string | Status do grupo de liquidação | **[Enumeradores bank_slip_settlement_group_status](#enumeradores-bank_slip_settlement_group_status)** |
| `bank_slip_settlement_quantity`              | integer  |  Quantidade de liquidações do grupo  | - |

### Objeto pagination

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `current_page`            | integer | Página atual                                                 | -      |
| `rows_per_page`           | integer | Itens por página                                             | -      |

### Enumeradores bank_slip_settlement_group_type

| Enumerador                   | Descrição                                                                    |
|------------------------------|------------------------------------------------------------------------------|
| siloc                        | para pagamento de títulos (valor do título menor que R$ 250.000)                          |
| qr_code                      | para pagamento de títulos realizados via QR Code |
| str                          | para pagamento de títulos VR (valor do título maior que R$ 250.000) |
| notary_office                | para pagamento de títulos realizados via cartório             |
| split_payment                | grupo de liquidação destinado a uma conta rateada do [**rateio de crédito**](/documentation/boletos/instrucoes/rateio_de_credito) do boleto |

:::tip Boletos com rateio de crédito
Quando um boleto tem [**rateio de crédito**](/documentation/boletos/instrucoes/rateio_de_credito) configurado, o pagamento gera um grupo de liquidação por destinatário:
- O grupo da conta do **beneficiário do boleto** mantém o tipo original do fluxo de liquidação (`siloc`, `qr_code`, `str` ou `notary_office`).
- Os grupos das **contas rateadas** são criados com o tipo `split_payment`.

Cada conta envolvida (beneficiário e rateadas) consegue listar o seu próprio grupo de liquidação chamando este endpoint com a sua `account_key` — assim, os rateados conseguem conciliar exatamente quanto receberam de cada boleto.
:::

### Enumeradores bank_slip_settlement_group_status

| Enumerador                   | Descrição                                                                    |
|------------------------------|------------------------------------------------------------------------------|
| pending                      | grupo de liquidação criado mas a transação não foi realizada  |
| settled                      | grupo de liquidação criado e transação realizada |

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 404                      | BKS000006            | Not Found                                  | The source account key was not found.                                                                                | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                  | It was not possible to consult the source account at this time. Please try again in a few minutes.                                                                                      | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                                                                                    |
| 400                      | BKS000008            | Bad Request | The source account is closed.         |               A conta de origem está fechada.                                                                 |
| 400                      | BKS000009            | Bad Request | The source account is blocked.         |               A conta de origem está bloqueada.                                                                 |
| 400                      | BKS000095            | Bad Request | Invalid bank slip settlement group status.         |               Status de grupo de liquidação de boleto inválido. |

---

# Listar liquidações

URL: /documentation/boletos/liquidacao/listar_liquidacoes

:::info Informação
Em nosso sistema, as **liquidações** descrevem a transferência do valor de um boleto pago para a conta que deve receber esse pagamento. Resumidamente, sempre que a QI recebe a informação de que um boleto foi pago por outro banco ou, no caso de boletos protestados, pelo cartório, é criada uma liquidação para esse boleto específico. Posteriormente, são criados os grupos de liquidação aos quais elas sempre estarão atreladas, que representam lotes de liquidações agrupadas por tipo.

Em um momento posterior, é realizada a transação de pagamento desse grupo de liquidação para a conta do cliente. A **transaction_key** dessa transação é então salva para fins de conciliação, dessa foma você pode ver todos os boletos que foram liquidados em uma determinada transação. Por exemplo, se você tiver cinco boletos de R$ 5,00 cada, sendo que um foi pago via cartório, um foi pago via QR Code PIX e os outros três foram pagos utilizando a linha digitável ou código de barras por outro banco, serão criadas cinco liquidações referentes a esses boletos. Em seguida, essas liquidações serão agrupadas em três grupos de liquidação: um de R$ 15,00 com os três boletos pagos utilizando a linha digitável ou código de barras, para os quais será realizada uma única transação, outro de R$ 5,00 para o boleto pago via QR Code PIX e o último também de R$ 5,00 com o boleto pago via cartório.
:::

A listagem de liquidações retornará todas as liquidações do grupo de liquidação enviado na request.

## Request

ENDPOINT /account/ ACCOUNT_KEY /bank_slip_settlement_group/ BANK_SLIP_SETTLEMENT_GROUP_KEY /bank_slip_settlements
MÉTODO GET

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta    | 36         |
| `bank_slip_settlement_group_key`         | uuidv4 | Chave única de identificação do grupo de liquidação   | 

## Response

STATUS 200

Response Body

```json
{
    "data": [
        {
            "settlement_key": "388eac3a-4138-421c-86af-f6fe3d1a9419",
            "amount": 4800.0,
            "account_key": "96015228-4905-42fc-bda6-e70e0e552b6b",
            "bank_slip_key": "d39e243b-8532-4006-9ffd-17607d5d1620",
            "barcode": "32991981000275000002269450000000043200779790"
        },
        {
            "settlement_key": "c3d7c62e-73fa-473f-b5a2-82e9b8a7f9bb",
            "amount": 1.0,
            "account_key": "96015228-4905-42fc-bda6-e70e0e552b6b",
            "bank_slip_key": "3088ffdd-dec0-4fa3-8643-995d6809a2e6",
            "barcode": "32999980300000001000001370000000000100828480"
        }
    ],
    "pagination": {
        "current_page": 1,
        "rows_per_page": 100
    }
}
```

### Response Body Params

| Campo            | Tipo         | Descrição                             | Caracteres                                  |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `data`          | object array | Boletos                               | **[Objeto bank_slip_settlement](#objeto-bank_slip_settlement_group)**   |
| `pagination`    | object       | Informações de paginação              | **[Objeto pagination](#objeto-pagination)** |

### Objeto bank_slip_settlement

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `settlement_key      `     | uuidv4  | Chave única de identificação da liquidação                          | 36                                                |
| `account_key`     | uuidv4  | Chave única de identificação da conta | 36                                                |
| `amount`                  | float   | Valor liquidado                                                               | -
| `bank_slip_key      `     | uuidv4  | Chave única de identificação do boleto no formato uuid v4                          |
| `barcode`              | string  | Código de barras do boleto                                                         |

### Objeto pagination

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `current_page`            | integer | Página atual                                                 | -      |
| `rows_per_page`           | integer | Itens por página                                             | -      |

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 404                      | BKS000006            | Not Found                                  | The source account key was not found.                                                                                | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                  | It was not possible to consult the source account at this time. Please try again in a few minutes.                                                                                      | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                                                                                    |
| 400                      | BKS000008            | Bad Request | The source account is closed.         |               A conta de origem está fechada.                                                                 |
| 400                      | BKS000009            | Bad Request | The source account is blocked.         |               A conta de origem está bloqueada.                                                                 |
| 400                      | BKS000012            | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
| 404                      | BKS000093            | Bad Request | Settlement group not found for the given key.         |   Grupo de liquidação não encontrado para a chave fornecida. |

---

# Simulação de cenários

URL: /documentation/boletos/liquidacao/simulacao_de_cenarios_de_liquidacao

Esta página descreve como simular a efetivação de ações feitas por agentes externos para testar o fluxo de liquidação de boletos. Essas simulações são úteis para homologação e testes de integração.

:::info Informação
Não há payload de retorno (response body) nessas requisições. Elas simulam ações externas e retornam apenas o status HTTP.
:::

## 1 - Simulação de aviso de pagamento

Simula o aviso de pagamento de um boleto, alterando seu status para `payment_notice`.

ENDPOINT /mock/bank_slip/payment_notice
MÉTODO POST

Request Body

```json
{
    "bank_slip_key": "0d00b0e2-af11-472f-11f0-11f3330bae33",
    "paid_amount": 12.0,
    "payment_method": "cash",
    "payment_type": "full_interbank"
}
```

### Objeto Request Body

| Campo                            | Tipo    | Descrição                                                            | Máx. Caract. |
|----------------------------------|---------|----------------------------------------------------------------------|--------------|
| **bank_slip_key***               | string  | Chave unitária do boleto                                             | 36           |
| **paid_amount**                  | float   | Valor do pagamento. Se não informado, usa o valor original do boleto | -            |
| **payment_method**               | string  | Método de pagamento utilizado                                        | -            |
| **payment_type**                 | string  | Tipo de pagamento interbancário                                     | -            |

### Enumeradores payment_method

| Enumerador      | Descrição                    |
|-----------------|------------------------------|
| `cash`          | Dinheiro                     |
| `account_debit` | Débito em conta              |
| `credit_card`   | Cartão de crédito            |
| `check`         | Cheque                       |

### Enumeradores payment_type

| Enumerador              | Descrição                    |
|-------------------------|------------------------------|
| `full_interbank`        | Pagamento integral interbancário |
| `partial_interbank`     | Pagamento parcial interbancário  |

:::tip Comportamento
- Se `paid_amount` não for informado, será utilizado o valor original do boleto
- Se `payment_type` não for informado, será considerado como pagamento integral (`full_interbank`)
- A simulação cria uma ocorrência de aviso de pagamento
- O boleto será movido para o status `payment_notice` após a simulação
- **Importante**: Para `partial_interbank`, o status do boleto não é alterado. Esta opção é utilizada para simular casos de boletos de pagamento parcial, conforme explicado na [introdução](/documentation/boletos/introducao)
:::

## 2 - Simulação de liquidação de boleto

Simula o pagamento e liquidação financeira de um boleto, alterando seu status para `paid`.

ENDPOINT /mock/bank_slip/settlement
MÉTODO POST

Request Body

```json
{
    "bank_slip_key": "0d00b0e2-af11-472f-11f0-11f3330bae33",
    "paid_amount": 12.0,
    "payment_method": "cash"
}
```

### Objeto Request Body

| Campo                            | Tipo    | Descrição                                                            | Máx. Caract. |
|----------------------------------|---------|----------------------------------------------------------------------|--------------|
| **bank_slip_key***               | string  | Chave unitária do boleto                                             | 36           |
| **paid_amount**                  | float   | Valor do pagamento da liquidação. Se não informado, usa o valor original do boleto | -            |
| **payment_method**               | string  | Método de pagamento utilizado                                        | -            |

### Enumeradores payment_method

| Enumerador      | Descrição                    |
|-----------------|------------------------------|
| `cash`          | Dinheiro                     |
| `account_debit` | Débito em conta              |
| `credit_card`   | Cartão de crédito            |
| `check`         | Cheque                       |

:::tip Comportamento
- Se `paid_amount` não for informado, será utilizado o valor original do boleto
- A simulação cria uma ocorrência de pagamento com código 65 (pagamento) por padrão
- O boleto será movido para o status `paid` após a simulação
:::

---

# Aprovar pagamento de boleto

URL: /documentation/boletos/pagamento/aprovar_pagamento

## Request

ENDPOINT /bank_slip/payment_approval
MÉTODO POST

**body.json**

```json
{
    "operation_key": "0e241203-8c6b-4e0a-ac42-e0d2a2fc2d37",
    "feedback": True
}

```

### Body params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `operation_key` *| string  |  Chave entregue quando o pagamento foi criada (parâmetro key da resposta). | uuid  | 
| `feedback` | string  |  Booleano de aprovação ou rejeição da transferência: "true" ou "false". | -  | 

## Response

STATUS 200

Response Body

```json
{
    "data": {
        "error_list": [],
        "successful_feedback_list": [
            {
                "account_key": "21af482f-b8ac-48dd-8f9a-ea23429d28be",
                "approval_feedback": true,
                "movement_amount": 10.0,
                "movement_data": {
                    "digitable_line": "09990001029100010009895007444201283400000001000",
                    "resource_account_key": "21af482f-b8ac-48dd-8f9a-ea23429d28be"
                },
                "movement_date": "2020-08-06",
                "movement_info": null,
                "movement_request_key": "c154b5bf-66ac-4b37-b365-a4c05e68785b",
                "movement_status": "approved",
                "movement_type": "bank_slip_payment",
                "requester_key": "ba99b7f1-3db6-4a63-a386-ba2c7f31e784"
            }
        ]
    },
    "event_datetime": "2020-08-06 19:23:00",
    "key": "9a1eedb3-da45-418c-89e9-28459d4c51ed",
    "status": "ok",
    "webhook_type": "bank_slip_payment_approval"
}

```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

---

# Consultar linha digitável de boleto

URL: /documentation/boletos/pagamento/consulta_linha_digitavel

## Request

ENDPOINT /bank_slip/payment
MÉTODO GET

### Query params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `digitable_line` *| string |  Linha digitável do boleto. | 48 | 

## Response

STATUS 200

Response Body

```json
{
  "barcode": "31893833500000835480005050500512130021164946",
  "beneficiary_bank_code": "318",
  "beneficiary_document_number": "61902722000126",
  "beneficiary_legal_name": "Sport Club Corinthians Paulista",
  "beneficiary_person_type": "legal",
  "calculated_internally": true,
  "calculation_date": "2020-08-05",
  "calculation_model": 1,
  "digitable_line": "31890005025050051213700211649462383350000083548",
  "discount_amount": "0",
  "expiration_date": "2020-08-02",
  "expired_as_of_payment_date": true,
  "expired_as_of_today": true,
  "factual_expiration_date": "2020-08-03",
  "fine_amount": "16.71",
  "guarantor_document": null,
  "guarantor_name": null,
  "interest_amount": "0",
  "max_payment_date": "2020-08-08",
  "nominal_amount": "835.48",
  "payer_document_number": "15676407883",
  "payer_legal_name": "LUCIANO RENATO MOREIRA",
  "payer_person_type": "natural",
  "payment_date": "2020-08-05",
  "rebate_amount": "0.0",
  "total_amount": "852.19",
  "valid_payment_amount": true,
  "valid_payment_calculation": true,
  "valid_payment_time_frame": true
}

```

STATUS 400

Response Body

```json
{
  "code": "BLP000142",
  "title": "Bad Request",
  "description": "This digitable line is out of minimum or maximum length.", 
  "translation": "Esta linha digitável está fora do comprimento mínimo ou máximo.",
  "extra_fields": {}
}
```

STATUS 400

Response Body

```json
{
  "code": "BLP000141",
  "title": "Bad Request",
  "http_status": 400,
  "description": "The given digitable_line must have only numbers.",
  "translation": "A linha digit\u00e1vel fornecida deve conter somente n\u00fameros.",
  "extra_fields": {}
}
```

STATUS 400

Response Body

```json
{
  "code": "BLP000012",
  "title": "Bad Request",
  "http_status": 400,
  "description": "Missing mandatory parameter: digitable_line",
  "translation": "Par\u00e2metro obrigat\u00f3rio ausente: digitable_line",
  "extra_fields": {}
}
```

STATUS 422

Response Body

```json
{
  "code": "IPP000014",
  "title": "Invalid Barcode",
  "http_status": 422,
  "description": "Invalid barcode",
  "translation": "O Código de barras é inválido",
  "extra_fields": {}
}
```

STATUS 422

Response Body

```json
{
  "code": "IPP000022",
  "title": "Unprocessable Entity",
  "http_status": 422,
  "description": "Covenant not accepted",
  "translation": "Convênio não aceito",
  "extra_fields": {}
}
```

STATUS 422

Response Body

```json
{
  "code": "IPP000023",
  "title": "Unprocessable Entity",
  "http_status": 422,
  "description": "Max retries exceeded, while trying to complete payment.",
  "translation": "Número máximo de tentativas excedido, ao tentar concluir o pagamento.",
  "extra_fields": {}
}
```

STATUS 422

Response Body

```json
{
  "code": "IPP000017",
  "title": "Unprocessable Entity",
  "http_status": 422,
  "description": "The tax collection is overdue",
  "translation": "A arrecadação está vencida",
  "extra_fields": {} 
}
```

### Response Params
| Campo | Tipo | Descrição                                 | Caracteres |
| --- | -- |--------------------------------------------------------------------| --- |
|`barcode`| string | Código de barras do boleto. | 44 |
|`beneficiary_bank_code`| string | Código de bancário do banco que registrou o boleto. | 3 |
|`beneficiary_document_number`| string | CPF/CNPJ do beneficiário (recebedor) do boleto. Também é o CPF/CNPJ do titular da conta onde o boleto foi registrado. | 14 |
|`beneficiary_legal_name`| string | Nome do beneficiário (recebedor) do boleto. Também é o nome do titular da conta onde o boleto foi registrado. | - |
|`beneficiary_person_type`| enum | Natureza Jurídica do beneficiário (recebedor) do boleto. Também é a natureza jurídica do titular da conta onde o boleto foi registrado. | [Enumerador person_type](#enumeradores-person_type) |
|`calculated_internally`| boolean | Indica se o calculo foi realizado pela QI Tech ou não. | - |
|`calculation_date`| string | Data de referência do calculo de multa e juros do boleto. | 10 |
|`calculation_model`| int | Modelo de calculo utilizado no calculo de multa e juros do boleto. Este campo é informado pelo banco que registrou o boleto. | [Códigos calculation_model](#codigos-calculation_model) |
|`digitable_line`| uuid | Linha digitável do boleto. | 47 |
|`discount_amount`| string | Valor do desconto de pontualidade do boleto. | - |
|`expiration_date`| string | Data de vencimento do boleto. | 10 |
|`expired_as_of_payment_date`| boolean | Informa se o boleto estará vencido na data de agendamento do pagamento (Campo pode ser ignorado). | 10 |
|`expired_as_of_today`| string | Informa se o boleto esta vencido na data de hoje. | 10 | 
|`factual_expiration_date`| string | Data de vencimento do boleto em dia útil. Por exemplo, se o boleto tiver vencimento em `2023-12-16` este campo terá o valor informado `2023-12-18`. | 10 |
|`fine_amount`| string | Valor calculado de multa do boleto. | - |
|`guarantor_document`| string | CPF/CNPJ do sacador avalista do boleto. | 14 |
|`guarantor_name`| string | Nome do sacador avalista do boleto. | - |
|`interest_amount`| string | Valor de juros calculado após o vencimento do boleto. | - |
|`max_payment_date`| string | Data limite de pagamento do boleto. | 10 |
|`nominal_amount`| string | Valor original do boleto. | - |
|`payer_document_number`| string | CPF/CNPJ do pagador do boleto. | 14 |
|`payer_legal_name`| string | Nome do pagador do boleto. | 14 |
|`payer_person_type`| enum | Natureza jurídcia do pagador do boleto. | [Enumerador person_type](#enumeradores-person_type) |
|`payment_date`| string | Data do pagamento do boleto. | 10 |
|`rebate_amount`| string | Valor de abatimento no boleto. | - |
|`total_amount`| string | Valor do total do boleto (com juros, multa, abatimento e desconto). | - |
|`valid_payment_amount`| boolean | Informa se o valor de pagamento é válido (será sempre `true`). | - |
|`valid_payment_calculation` | boolean | Informa se o valor calculado pelo banco registrador do boleto é válido (quando o `calculation_model` for `2` ou `3`). | - |
|`valid_payment_time_frame` | boolean | Informa se a data de agendamento do pagamento é menor que a data máxima para pagamento do boleto. | - |

### Enumeradores person_type 
| Enumerador | Descrição |
| --- | -- |
| `natural` | Pessoa física |
| `legal` | Pessoa jurídica |

### Códigos calculation_model
| Enumerador | Descrição |
| --- | -- |
| 1 | Instituição pagadora do boleto calcula os valores de juros e multa do boleto (Caso seja informado no boleto consultado, o campo `calculated_internally` será retornado como `true`). |
| 2 | Instituição que registrou o boleto calcula os valores de juros e multa. Após a data de vencimento do boleto, a instituição atualiza os valores diariamente na base centralizada de boleto. |
| 3 | Instituição que registrou o boleto calcula o valor do boleto. A instituição atualiza o valor do boleto diariamente na base centralizada de boleto. |

## Ambiente de Sandbox

### Boletos de convênio/tributos

Os boletos de convênio/tributos são emitidos por órgãos governamentais, como prefeituras, governos estaduais ou federais, para a cobrança de impostos, taxas, contribuições sociais, multas, e outros valores devidos ao governo.

Em nosso ambiente de sandbox, disponibilizamos linhas digitáveis mockadas para a simulação de pagamentos bem-sucedidos e testes de cenários de erro.

### Cenários de sucesso

| Linha digitável |
|---|
| 828300000007411100972013905080001546763201900028 |
| 838000000009235700481007241345219112001474229880 |
| 848000000006308600802021201071261517689002201070 |
| 858200000015000000643025703477209504800448091020 |

### Cenários de erro

| Linha digitável | Código de erro |
|---|---|
| 858500000037350000643217212883260006147448091022 | IPP000014 |

### Boleto bancário

Um boleto bancário, também conhecido como boleto ou bloqueto, é um documento muito usado no Brasil para pagar por produtos ou serviços. Com um boleto, a pessoa ou empresa que o emite pode receber o dinheiro que está sendo cobrado do pagador.

Em nosso ambiente de sandbox, disponibilizamos linhas digitáveis mockadas para a simulação de pagamentos bem-sucedidos.

### Cenários de sucesso

| Linha digitável |
|---|
| 32990001039000210987502864982109595090000063958 |
| 32990001039000000006836762871105695090000010000 |
| 32990001031000699960099000000200195070000025527 |
| 32990001039000000000103194237800895060001000000 |
| 32990001031000699960095000000208497790000030990 |

---

# Realizar pagamento de boleto

URL: /documentation/boletos/pagamento/realizar_pagamento

### Request

ENDPOINT /bank_slip/payment
MÉTODO POST

Request Body

```json
{
    "digitable_line": "42297034020000453753620034706323183380000005000",
    "resource_account_key": "21af482f-b8ac-48dd-8f9a-ea23429d28be",
    "payment_date": "2020-08-05"
}

```

#### Body params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `digitable_line` *| string  | Linha digitável do boleto. | 10 |
| `resource_account_key` *| string | Chave da conta que será utilizada. | 10 |
| `payment_date` | date | Data para a realização do pagamento. Se não enviada a data será hoje. | 10 |

:::info Informação

Para visualizar os convênios de pagamentos aceitos, [clique aqui](https://storage.googleapis.com/live-doc-api/public_samples/active_covenants.xlsx).

:::

### Response

STATUS 200

Response Body: Pagamento através de uma conta livre

```json
{
    "data": {
        "digitable_line": "09990001029100010009895007444201283400000001000",
        "resource_account_key": "21af482f-b8ac-48dd-8f9a-ea23429d28be"
    },
    "event_datetime": "2020-08-06 19:22:06",
    "key": "e7719f95-a31d-4171-ae83-2d8b3d419dc2",
    "status": "success",
    "webhook_type": "bank_slip_payment"
}
```

STATUS 200

Response Body: Pagamento através de uma conta escrow

```json
{
    "data": {
        "digitable_line": "09990001029100010009895007444201283400000001000",
        "resource_account_key": "21af482f-b8ac-48dd-8f9a-ea23429d28be"
    },
    "event_datetime": "2020-08-06 19:22:06",
    "key": "e7719f95-a31d-4171-ae83-2d8b3d419dc2",
    "status": "waiting_approval",
    "webhook_type": "bank_slip_payment"
}

```

STATUS 400

Response Body

```json
{
    "code": "LEG000069"
    "title": "Bad Request",
    "description": "Invalid request body.",
    "translation": "Corpo da requisição inválido.",
    "extra_fields": {}
}
```

STATUS 423 - Pagamento fora do horário

Response Body

```json
{
	"code": "BLP000024",
	"title": "Locked",
	"http_status": 423,
    "description": "Operation window closed. System available from {OPENING_TIME} to {CLOSING_TIME}",
    "translation": "Opera\u00e7\u00e3o encerrada. Sistema dispon\u00edvel de {OPENING_TIME} a {CLOSING_TIME}",
	"extra_fields": {
		"next_available_datetime": "2023-08-13T18:00:00.000Z"
	}
}
```

STATUS 400

Response Body

```json
{
  "code": "IPP000015",
  "title": "Bad Request",
  "http_status": 400,
  "description": "Invalid amount",
  "translation": "O valor inserido é inválido",
  "extra_fields": {} 
}
```

STATUS 422

Response Body

```json
{
  "code": "IPP000013",
  "title": "Incompatible Payment Value",
  "http_status": 422,
  "description": "The input amount does not match tax collection value",
  "translation": "O valor do pagamento é diferente da arrecadação",
  "extra_fields": {} 
}
```

STATUS 422

Response Body

```json
{
  "code": "IPP000012",
  "title": "Tax Collection Already Paid",
  "http_status": 422,
  "description": "This tax collection is already paid",
  "translation": "A arrecadação já foi paga",
  "extra_fields": {} 
}
```

STATUS 422

Response Body

```json
{
  "code": "IPP000017",
  "title": "Unprocessable Entity",
  "http_status": 422,
  "description": "The tax collection is overdue",
  "translation": "A arrecadação está vencida",
  "extra_fields": {} 
}
```

STATUS 422

Response Body

```json
{
  "code": "IPP000023",
  "title": "Unprocessable Entity",
  "http_status": 422,
  "description": "Max retries exceeded, while trying to complete payment.",
  "translation": "Número máximo de tentativas excedido, ao tentar concluir o pagamento.",
  "extra_fields": {}
}
```

STATUS 422

Response Body

```json
{
  "code": "IPP000024",
  "title": "Unprocessable Entity",
  "http_status": 422,
  "description": "Error while processing payment output. Try again.",
  "translation": "Erro ao processar a saída do pagamento. Tente novamente.",
  "extra_fields": {}
}
```

STATUS 422

Response Body

```json
{
  "code": "IPP000025",
  "title": "Unprocessable Entity",
  "http_status": 422,
  "description": "Outside of covenant payment hours.",
  "translation": "Fora do horário de pagamento do convênio.",
  "extra_fields": {}
}
```

## Ambiente de Sandbox

### Boletos de convênio/tributos

Os boletos de convênio/tributos são emitidos por órgãos governamentais, como prefeituras, governos estaduais ou federais, para a cobrança de impostos, taxas, contribuições sociais, multas, e outros valores devidos ao governo.

Em nosso ambiente de sandbox, disponibilizamos linhas digitáveis mockadas para a simulação de pagamentos bem-sucedidos e testes de cenários de erro.

#### Cenários de sucesso

| Linha digitável |
|---|
| 828300000007411100972013905080001546763201900028 |
| 838000000009235700481007241345219112001474229880 |
| 848000000006308600802021201071261517689002201070 |
| 858200000015000000643025703477209504800448091020 |

#### Cenários de erro

| Linha digitável | Código de erro |
|---|---|
| 858900000034050002701002700011434710592720230733 | IPP000015 |
| 858400000000750002701007700011434710592720230733 | IPP000013 |
| 858800000040450004322322120716192390688090088931 | IPP000012 |
| 858900000000350004322326120716192390688090083760 | IPP000014 |

### Boleto bancário

Um boleto bancário, também conhecido como boleto ou bloqueto, é um documento muito usado no Brasil para pagar por produtos ou serviços. Com um boleto, a pessoa ou empresa que o emite pode receber o dinheiro que está sendo cobrado do pagador.

Em nosso ambiente de sandbox, disponibilizamos linhas digitáveis mockadas para a simulação de pagamentos bem-sucedidos.

#### Cenários de sucesso

| Linha digitável |
|---|
| 32990001039000210987502864982109595090000063958 |
| 32990001039000000006836762871105695090000010000 |
| 32990001031000699960099000000200195070000025527 |
| 32990001039000000000103194237800895060001000000 |
| 32990001031000699960095000000208497790000030990 |

---

# Redirecionamento da Conta de Liquidação de um Boleto

URL: /documentation/boletos/redirecionamento_de_conta_de_liquidacao

Esse endpoint será utilizado para alterar a conta de liquidação de um boleto registrado na QI Tech. 

:::caution Atenção! 
  - O boleto permanece registrado na conta original, ela deve permanecer aberta enquanto houverem boletos resgistrados nela;
  - Os webhooks permanecerão sendo enviados para o parceiro integrador da conta original;
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip/ BANK_SLIP_KEY /settlement_account
MÉTODO PATCH

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta em que o boleto foi emitido | 36 |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira| 36 |
| `bank_slip_key`         | uuidv4 | Chave única de identificação do boleto | 36 |

Request Body

```json
{
  "settlement_account_key": "614a451d-3b82-460e-bcc0-2caf3dde711f"
}
```

### Request Body Params

| Campo                        | Tipo    | Descrição                                             | Caracteres |
|------------------------------|---------|-------------------------------------------------------|------------|
| `settlement_account_key` *   | uuidv4  | Chave única que identifica a nova conta de liquidação | 36         |

## Response

STATUS 204

Response Body

```json
{}
```

### Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title` | Descrição (eng)<br/>`description`                                                                  | Descrição (pt-br)<br/>`translation`                                                                       |
|--------------------------|----------------------|--------------------|----------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request        | Schema Error                                                                                       | Schema Inválido                                                                                           |
| 404                      | BKS000025            | Not Found          | The source account key was not found.                                                              | A chave da conta de origem não foi encontrada.                                                            |
| 400                      | BKS000007            | Bad Request        | It was not possible to consult the source account at this time. Please try again in a few minutes. | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos. |
| 400                      | BKS000008            | Bad Request        | The source account is closed.                                                                      | A conta de origem está fechada.                                                                           |
| 400                      | BKS000009            | Bad Request        | The source account is blocked.                                                                     | A conta de origem está bloqueada.                                                                         |
| 404                      | BKS000013            | Not Found          | Requester profile not found                                                                        | Carteira não encontrada                                                                                   |
| 400                      | BKS000022            | Bad Request        | Requester profile is not opened.                                                                   | Carteira não está aberta.                                                                                 |
| 404                      | BKS000029            | Not Found          | Bank slip not found for the given key (`{bank_slip_key}`).                                         | Boleto não encontrado para a chave fornecida (`{bank_slip_key}`).                                         |                           |
| 400                      | BKS000032            | Bad Request        | Bank slip must be in 'registered' status.                                                          | O boleto deve possuir o status 'registered'.                                                              |
| 400                      | BKS000052            | Bad Request        | Invalid account status.                                                                            | Status da conta inválido.                                                                                 |

---

# Listar arquivos retorno

URL: /documentation/boletos/retorno/listar_arquivos_retorno

:::info
Os arquivos disponibilizados nas URLs fornecidas na resposta desse endpoint seguem o padrão de Layout de Arquivo de Retorno com 400 posições da QI Tech.
Segue link para download do manual: [Layout de Cobrança - QI Tech versão 2.1.](https://storage.googleapis.com/live-doc-api/public_samples/Layout%20de%20Cobran%C3%A7a%20-%20QI%20Tech%20v2.1.pdf)
:::

Os arquivos retorno servem para conciliação. Nele, cada linha de Registro de Transação (Tipo 1) diz respeito a uma instrução (seja de emissão, prorrogação, abatimento etc.) que foi confirmada ou rejeitada pela CIP/Nuclea no dia anterior.

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /discharge_files
MÉTODO GET

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta    | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira, no formato uuid v4 | 36         |

### Query parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres              |
|-------------------------|--------|--------------------------------------------------------------|-------------------------|
| `discharge_file_key`         | uuidv4 | Chave única de identificação do arquivo retorno, no formato uuid v4   | 36                      |
| `page`                  | integer| Número da página                                             | -                       |
| `page_size`             | integer| Tamanho da página                                            | -                       |
| `from_date`             | string| Data inicial (formato "AAAA-MM-DD")                           | 10                      |
| `to_date`               | string| Data final (formato "AAAA-MM-DD")                             | 10                      |

## Response

STATUS 200

Response Body

```json
{
    "data": [
        {
            "discharge_file_key": "f1a8fe59-29cd-49e5-8d18-55194869b45c",
            "discharge_file_name": "CB15102401.RET",
            "discharge_file_url": "https://storage.googleapis.com/local-bank-slip-api/2024/61a746ca-05bf-429d-99c3-3fba0f9fbea7/329-20-7336-3073959/discharge/CB15102401.RET",
            "reference_date": "2024-10-15"
        }
    ],
    "pagination": {
        "current_page": 1,
        "rows_per_page": 100
    }
}
```

### Response Body Params

| Campo            | Tipo         | Descrição                             | Caracteres                                  |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `data`          | object array | Arquivos retorno                               | **[Objeto discharge_file](#objeto-discharge_file)**   |
| `pagination`    | object       | Informações de paginação              | **[Objeto pagination](#objeto-pagination)** |

### Objeto discharge_file

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------|
| `discharge_file_key      `     | uuidv4  | Chave única de identificação do arquivo retorno no formato uuid v4                          | 36                                                |
| `discharge_file_name`     | string  | Nome do arquivo retorno | -                                                |
| `discharge_file_url`             | string | URL do arquivo retorno                           | -                                                |
| `reference_date`                  | string   | Data de referencia do aquivo retorno no formato YYYY-MM-DD                                                               | 10 |

### Objeto pagination

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `current_page`            | integer | Página atual                                                 | -      |
| `rows_per_page`           | integer | Itens por página                                             | -      |

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 403                      | BKS000005            | Forbidden                         | User is not allowed to do this action | Usuário não tem autorização para fazer essa ação |
| 404                      | BKS000006            | Not Found                                  | The source account key was not found.                                                                                | A chave da conta de origem não foi encontrada.                                                                           |
| 400                      | BKS000007            | Bad Request                                  | It was not possible to consult the source account at this time. Please try again in a few minutes.                                                                                      | Não foi possível consultar a conta de origem neste momento. Por favor, tente novamente em alguns minutos.                                                                                    |
| 400                      | BKS000012            | Bad Request | Invalid integer value for page or size query string parameters. | Valor inválido para parâmetros de página ou tamanho de página. |
| 404                      | BKS000013            | Not Found | Requester profile not found         |               Carteira não encontrada                                                                 |
| 400                      | BKS000052            | Bad Request        | Invalid account status.                                                                            | Status da conta inválido.                                                                                 |

---

# Emissão de um bolePix

URL: /documentation/boletos/v1/emissao/emissao_de_um_bolepix

:::caution Atenção
Antes de registrar um bolePix é necessário que a exista uma Chave Pix Aleatória ativa na conta onde o boleto será registrado. 
:::

Na QI Tech, é possível realizar a emissão de um boleto vinculado a um QR Code Pix.

Desta forma, o sacado poderá realizar o pagamento do boleto através da linha digitável do boleto registrado ou então através da leitura do QR Code Pix vinculado a este boleto.

Nos casos em que o sacado realizar o pagamento através de leitura do QR Code Pix, a liquidação financeira do pagamento será instatânea, sendo que os retornos bancários, bem com os webhooks a respeito da liquidação deste boleto serão gerados da mesma forma que um boleto comum.

## Request

ENDPOINT /multibank_instruction
MÉTODO POST

Request Body

```json
{
	"occurrences": [{
		"amount": 1000,
		"automatic_bankruptcy_protest": false,
		"bank_teller_instructions": "Não pagar após vencimento.",
		"beneficiary_account_key": "8a35e639-8420-4f6c-9647-c2515e5381ef",
		"beneficiary_key": "3c866e34-23fe-46c2-a8b0-e39ca4348923",
		"days_to_bankruptcy_protest": 0,
		"document_number": "123456/01",
		"expiration": "2020-06-01",
		"fine_percentage": "3",
		"interest_daily_value": "0.34",
		"occurrence_type": "registration",
		"payer_address": "Rua Carlos Sampaio, 123",
		"payer_document": "41184562067",
		"payer_name": "João Ninguem",
		"payer_person_type": "natural",
		"payer_postal_code_root": "15800",
		"payer_postal_code_suffix": "020",
		"printing_policy": "no_printing",
		"registration_institution_enumerator": "qi_scd",
		"requester_profile": "09",
		"requester_profile_code": "329-09-0001-0000002",
        "pix_key": "1684629c-d52a-4941-92f5-410907316129" 
	}]
}
```

### Query params

| Campo | Tipo | Descrição                                                                                                                                                                                                                                                                                           | Caracteres |
|---|---|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `use_multi_process` | boolean | Indica se o processamento das ocorrências de registro serão enviados para processamento em fila ou se serão processados de forma sequencial. Caso seja este parâmetro seja informado como `true`, é obrigatório o envio do nosso número bancário `our_number` no payload da ocorrência de registro. | -          | 

### Body params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `occurrences` * | array of objects | Lista de ocorrências a serem processadas. | **[Objeto occurrences](#objeto-occurrences)** |

### Objeto occurrences

| Campo                                | Tipo             | Descrição                                                                                                                                               | Caracteres                                      |
|--------------------------------------|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------|
| `amount` *                           | double           | Valor do boleto.                                                                                                                                        | -                                               |
| `automatic_bankruptcy_protest`       | boolean          | Configuração de protesto automático.                                                                                                                    | -                                               |
| `bank_teller_instructions`           | string           | Instruções ao caixa (Mensagem/Observações do boleto).                                                                                                   | -                                               |
| `beneficiary_account_key`            | string           | Chave da conta do beneficiário.                                                                                                                         | -                                               |
| `beneficiary_key`                    | string           | Chave do beneficiário.                                                                                                                                  | -                                               |
| `days_to_bankruptcy_protest`         | int              | Número de dias para envio automático de protesto falimentar.                                                                                            | -                                               |
| `document_number`                    | string           | Numero do documento.                                                                                                                                    | -                                               |
| `expiration` *                       | string           | Data de vencimento.                                                                                                                                     | -                                               |
| `fine_percentage`                    | string           | Porcentagem de multa                                                                                                                                    | -                                               |
| `interest_daily_value`               | string           | Valor de juros por dia em reais                                                                                                                         | -                                               |
| `occurrence_type` *                  | string           | Tipo de ocorrência.                                                                                                                                     | -                                               |
| `payer_address`                      | string           | Endereço do pagador.                                                                                                                                    | -                                               |
| `payer_document` *                   | string           | Documento do pagador (CPF ou CNPJ).                                                                                                                     | -                                               |
| `payer_name` *                       | string           | Nome do pagador.                                                                                                                                        | -                                               |
| `payer_person_type` *                | string           | Tipo de pessoa pagante.                                                                                                                                 | -                                               |
| `payer_postal_code_root`             | string           | Os cinco primeiros digitos do CEP.                                                                                                                      | -                                               |
| `payer_postal_code_suffix`           | string           | Os três últimos dígitos do CEP.                                                                                                                  | -                                               |
| `printing_policy`                    | string           | Política de impressão do boleto                                                                                                                         | -                                               |
| `registration_institution_enumerator` * | string           | Será sempre `qi_scd`.                                                                                                        | `qi_scd`                                               |
| `requester_profile` *                | string           | Número da carteira.                                                                                                                                     | 02                                              |
| `requester_profile_code` *           | string           | Código da carteira composto da seguinte forma: "329-carteira-agencia-conta_com_7_digitos". OBS: a carteira de cobrança padrão QI Tech é de numero "09". | -                                               |
| `notification`                       | object           | Número da carteira.                                                                                                                                     | **[Objeto notification](#objeto-notification)** |  
| `discounts`                          | object | Lista de objetos com informações de desconto.                                                                                                           | **[Objeto discounts](#objeto-discounts)**       |  
| `guarantor_name`                     | string           | Nome do sacador avalista.                                                                                                                               | -                                               |
| `guarantor_document_root`            | string           | Base do CNPJ do sacador avalista.                                                                                                                       | -                                               |
| `guarantor_document_subsidiary`      | string           | Informação de CNPJ de matriz ou filial.                                                                                                                 | -                                               |
| `guarantor_document_digit`           | string           | Dígito verificador do CNPJ.                                                                                                                             | -                                               |
| `pix_key` * | string           | Chave Pix onde o QR Code Pix vinculado ao bolepix será registrado.                                                                                      | 100                                             |

:::info Campo “***pix_key***”
A “***pix_key***” pode ser um **CPF**, **CNPJ**, **E-mail**, **Celular** ou uma **Chave Aleatória** (UUID), seguindo as seguintes formatações:

**CPF:** Número inteiro com 11 dígitos.

**CNPJ:** Número inteiro com 14 dígitos.

**E-mail:** Texto contendo ao menos um “@”.

**Celular:** Texto contendo os seguintes valores: “+55” + “DDD do celular“ + “Número Inteiro do Celular com no mínimo 8 e no máximo 9 dígitos”. Ex: “+5511987654321“.

**Chave Aleatória:** UUID.
:::

### Objeto notification
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `document_number` * | string | Numero de documento do usuario que vai receber a notificação. | - |
| `email` * | string | Email do usuario que vai receber a notificação. | - |
| `name` * | string | Nome do usuario que vai receber a notificação.| - |
| `phone` * | object | Objeto contento informações do telefone do usuario que vai receber a notificação. |  **[Objeto phone](#objeto-phone)** |  
| `send_2_way` * | booleano | Enviar notificações de emissão de segunda via. | true/false |  
| `send_after_due_date` * | boolean | Enviar notificações após a data de vencimento do boleto. | true/false |
| `send_before_due_date` * | boolean | Enviar notificações antes da data de vencimento do boleto. | true/false |
| `send_on_protest` * | boolean | Enviar notificações de protesto. | true/false|

### Objeto phone 

| Campo | Descrição | Exemplo |  Máx. Caracteres | 
| --- | --- | --- | --- | 
|`country_code` | string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 | 
| `area_code` | string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `number` | string |Número de telefone (apenas números) |  10 |

### Objeto discounts 
| Campo | Descrição | Exemplo |  Máx. Caracteres | 
| --- | --- | --- | --- | 
|`discount_value` | float | Valor do desconto.| 3 | 
| `discount_number` | int32 | Ordem que o desconto deve ser aplicado. | 2 |
| `discount_limit_date` | date | Data limite do desconto. |  10 |

## Response

STATUS 200

Response Body

```json
{
  "bank_slips": [
    {
      "amount": "649.73",
      "bank_slip_key": "4bc636d0-1e41-4ce6-801c-475814bf4dcf",
      "bank_slip_status": "accepted",
      "barcode": "32991916500000649730001090000699935200347340",
      "beneficiary_account_key": "1c977186-9167-4ef1-b27d-08483429f74c",
      "beneficiary_key": "f01d4877-b1cc-4f4a-a8f9-952c2cef9ca8",
      "digitable_line": "32990001039000069993552003473403191650000064973",
      "expiration": "2022-11-10",
      "nfe_key": null,
      "nfe_url": null,
      "our_number": 6999352,
      "participant_control_number": null,
      "payer_postal_code": "38050000",
      "protest_status": "not_protested",
      "qr_code": {
        "pix_key": "9de04466-0b02-4263-9c28-9cdc0fb638bb",
        "qr_code_key": "881979cb-1c15-4dea-a05e-316caae22f5e",
        "qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/881979cb-1c15-4dea-a05e-316caae22f5e5204000053039865802BR5925LOTEAMENTO RESIDENCIAL PO6014PORTO NACIONAL61087750000062070503***630414B8"
      }
    }
  ],
  "file_info": {
    "beneficiary_code": null,
    "beneficiary_name": null,
    "file_sequence_id": null,
    "file_type_identifier": null,
    "file_type_literal": null,
    "service_code": null,
    "service_literal": null,
    "wrote_at": null
  },
  "occurrence_stats": {
    "bank_slip_edit": 0,
    "bankruptcy_protest_request": 0,
    "cancel_rebate": 0,
    "extension": 0,
    "notary_office_entry": 0,
    "notary_office_exit": 0,
    "notary_office_payment": 0,
    "notification": 0,
    "payment": 0,
    "payment_notice": 0,
    "payment_write_off": 0,
    "protest_cancel_and_write_off_request": 0,
    "protest_cancel_request": 0,
    "protest_remove_request": 0,
    "protest_request": 0,
    "rebate": 0,
    "registration": 1,
    "write_off": 0
  },
  "semantic_errors": []
}

```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

### Response Params
| Campo | Tipo | Descrição                                 | Caracteres |
| --- | -- |--------------------------------------------------------------------| --- |
|`bank_slips` | list | Lista com a informações dos boletos registrados caso o parâmetro `use_multi_process` seja informado com o valor `false`. | [Objeto Bank Slip](#objeto-bank_slip) | 
| `file_info` | list | Informações do arquivo, .                            | [Objeto File Info](#objeto-file-info) |
| `occurrence_stats` | object | Informações do arquivo, .                            | [Objeto File Info](#objeto-file-info) |
| `semantic_errors` | list | Lista de erros no processamento de cada boleto. Será retornado caso exista algum erro no processamento e caso o parâmetro `use_multi_process` seja informado com o valor `false`. | [Objeto Semantic Error](#objeto-semantic-error) |

### Objeto bank_slip
| Campo | Tipo | Descrição                                 | Caracteres |
| --- | -- |--------------------------------------------------------------------| --- |
|`amount` | float | Valor do boleto. | - |
|`bank_slip_key` | uuid | Chave unica de identificação do boleto na QI Tech. | 36 |
|`bank_slip_status` | enum | Chave unica de identificação do boleto na QI Tech. | [Enumeradores bank_slip_status](#enumeradores-bank_slip_status) |
|`barcode` | string | Código de barras do boleto. | 44 |
|`beneficiary_account_key` | uuid | Chave unica de identificação da conta em que o boleto foi registrado. | 36 |
|`beneficiary_key` | uuid | Chave unica de identificação do titular da conta em que o boleto foi registrado. | 36 |
|`digitable_line` | uuid | Linha digitável do boleto. | 47 |
|`expiration` | string | Data de vencimento do boleto. | 10 |
|`nfe_key` | string | Chave unica de identificação da nota fiscal eletrônica. | - |
|`nfe_url` | string | URL da nota fiscal eletrônica. | - |
|`our_number` | int | Nosso número bancário. É um número sequencial de identificação deste boleto em relação a conta (carteira de cobrança) em que ele foi registrado. Seu valor pode ser informado na requisição de registro do boleto. Caso não seja informado, a QI Tech gerará um valor deste campo (sendo este um valor incremental, ex: 1º boleto registrado na conta terá o `our_number` de valor 1, o 16º boleto registrado na conta terá o `our_number` de valor 16). | - 
|`participant_control_number` | string | Número de controle do participante. | 10 |
|`payer_postal_code` | string | CEP do pagador do boleto. | 8 |
|`protest_status` | string | Situação do protesto do boleto, caso o protesto tenha sido solicitado. | [Enumeradores protest_status](#enumeradores-protest_status) |
|`qr_code` | object | Objeto com as informações do QR Code Pix vinculado ao boleto. | [Objeto qr_code](#objeto-qr_code) |

### Objeto qr_code
| Campo | Tipo | Descrição                                 | Caracteres |
| --- | -- |--------------------------------------------------------------------| --- |
|`pix_key` | string | Chave pix onde o QR Code Pix vinculado ao boleto foi registrado. | 100 |
|`qr_code_key` | uuid | Chave única de identificação do QR Code Pix vinculado ao boleto . | 36 |
|`qr_code_url` | uuid | URL do Pix Copia e Cola do QR Code Pix vinculado ao boleto. | 36 |

### Enumeradores bank_slip_status
| Enumerador | Descrição |
| --- | -- |
| `accepted` | Boleto aceito para processamento |
| `registered` | Registro do boleto foi concluído na câmara de registro de boletos |
| `paid` | Valor do pagamento do boleto foi creditado na conta do beneficiário do boleto |
| `written_off` | Boleto baixado (boleto não é mais pagável) |
| `rejected` | Registro de boleto rejeitado pela câmara de registro de boletos  |
| `payment_notice` | Aviso de que o pagamento do boleto foi processado no banco pagador (porém a liquidação na conta do beneficiário ainda não ocorreu) |
| `notary_office_payment_notice` | Aviso de que o pagamento de um boleto protestado foi processado no banco pagador (porém o cartório ainda não realizou o repasse do pagamento e a liquidação na conta do beneficiário ainda não ocorreu) |

### Enumeradores protest_status
| Enumerador | Descrição |
| --- | -- |
| `not_protested` | Boleto não possui solicitação de protesto. |
| `protest_requested` | Boleto com solicitação de protesto em processamento pela QI Tech. |
| `notary_office_entry` | Solicitação de protesto de boleto foi aceita pelo cartório. |
| `protest_cancel_requested` | Solicitação de cancelamento de protesto em processamento pela QI Tech. |
| `notary_office_exit` | Protesto do boleto foi retirado do cartório. |
| `protested` | Protesto foi confirmado pelo cartório e o boleto se encontrada protestado. |
| `paid_at_notary_office` | Cartório identificou o pagamento do protesto do boleto e esta processando o repasse do pagamento para a QI Tech. |
| `judicially_suspended` | Protesto suspenso judicialmente. |
| `protest_remove_requested` | Solicitação de retirada de protesto foi aceita pelo cartório. |

---

# Emissão de boleto via CNAB

URL: /documentation/boletos/v1/emissao/emissao_via_cnab

## Request

ENDPOINT /multibank_cnab
MÉTODO POST

:::caution Atenção!
A chamada deve ser autenticada seguindo o padrão descrito na seção AUTENTICAÇÃO E SEGURANÇA. Com as seguintes ressalvas:

**1 -** O valor da variável ContentMD5 deverá ser a Hash MD5 do binário arquivo a ser enviado;

**2 -** O binário do arquivo deve ser enviado no corpo da request como um FormData utilizando como chave a string "file" e no valor o arquivo a ser enviado. (Este conteúdo não é encriptado);
:::

:::info
O arquivo transmitido nesta chamada deve seguir o padrão de Layout de Arquivo de Cobrança com 400 posições da QI Tech.
Segue link para download do manual: [Layout de Cobrança - QI Tech versão 2.1.](https://storage.googleapis.com/live-doc-api/public_samples/Layout%20de%20Cobran%C3%A7a%20-%20QI%20Tech%20v2.1.pdf)
:::

STATUS 200

Response Body

```json
{
    "cnab_file": {
        "cnab_key": "52ff2ea1-a17f-4476-8eb8-617ddd16a81e",
        "company_code": null,
        "created_at": "2020-04-17T21:41:09",
        "downloads": [
            {
                "cnab_file_id": 0,
                "created_at": "2020-04-17T21:41:09",
                "document_number": "41184562067",
                "name": "João Ninguem",
                "person_key": "string"
            }
        ],
        "file_size": "None",
        "filename": "1905200807.REM",
        "line_length": 400,
        "remitter_key": "329",
        "requester_profile_code": "329-01-0001-0000002",
        "type": "requester_remittance",
        "url": "https://google.com",
        "version": "1"
    },
    "file_info": {
        "bank_warning_number": 244,
        "beneficiary_code": "1234567",
        "beneficiary_name": "QI SOCIEDADE DE CREDITO DIRETO",
        "credit_date": 190520,
        "file_type_identifier": 1,
        "file_type_literal": "REMESSA",
        "service_code": 1,
        "service_literal": "COBRANCA",
        "wrote_at": 180520
    },
    "occurrence_list": [
        {
            "amount": "1399.67",
            "asset_type": "invoice",
            "automatic_bankruptcy_protest": true,
            "automatic_protest": false,
            "automatic_write_off": false,
            "bank_teller_instructions": "SOMAR OS ENCARGOS PERTINENTES",
            "beneficiary_account_branch": 1,
            "beneficiary_account_number": 1273,
            "beneficiary_account_number_digit": "1",
            "cnab_file_occurrence_order": 1,
            "days_before_fine": 0,
            "days_before_interest": 0,
            "days_to_bankruptcy_protest": 10,
            "days_to_protest": 0,
            "days_to_write_off": 0,
            "discount_limit_date": "2020-05-14 00:00:00",
            "discount_value": "0.00",
            "document_number": "0198874/01",
            "expiration": "2020-06-18 00:00:00",
            "fine_percentage": "2.00",
            "guarantor_address": "AVENIDA DAS AMERICAS, 1321",
            "guarantor_city": "FAZENDA RIO GRANDE",
            "guarantor_document_digit": 86,
            "guarantor_document_root": 80550452,
            "guarantor_document_subsidiary": 1,
            "guarantor_name": "PLASTILIT PRODUTOS PLASTICOS DO PARANA S.A.",
            "guarantor_postal_code_root": 83820,
            "guarantor_postal_code_suffix": 23,
            "guarantor_state": "PR",
            "interest_daily_value": "4.67",
            "messages": [
                {"SOMAR OS ENCARGOS PERTINENTES"}
            ]
            "occurrence_cnab_line": 2,
            "occurrence_feedback": null,
            "occurrence_sequence": "0",
            "occurrence_type": "registration",
            "origin_type": "remittance",
            "our_number": 109001065,
            "our_number_digit": "1",
            "participant_control_number": "700000004167313",
            "payer_address": "AVENIDA 7 DE SETEMBRO, N. 1043",
            "payer_document": "77900454000143",
            "payer_name": "ARLINDO RAGAZZON ME",
            "payer_person_type": "legal",
            "payer_postal_code_root": 89874,
            "payer_postal_code_suffix": 0,
            "printing_policy": "no_printing",
            "rebate_amount": "0.00",
            "registration_institution_enumerator": "bradesco",
            "registration_institution_febraban_code": "237",
            "requester_key": "64d3bafa-2205-43ca-b6a7-2827aefe3ebc",
            "requester_profile": 19,
            "requester_profile_code": "237-19-0001-0001273",
            "requester_registration_date": "2020-05-18 00:00:00",
            }
        ]
}
```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

---

# Emissão de boleto via JSON

URL: /documentation/boletos/v1/emissao/emissao_via_json

## Request

ENDPOINT /multibank_instruction
MÉTODO POST

Request Body

```json
{
    "occurrences": [
        {
            "amount": 1000,
            "automatic_bankruptcy_protest": false,
            "bank_teller_instructions": "Não pagar após vencimento.",
            "beneficiary_account_key": "8a35e639-8420-4f6c-9647-c2515e5381ef",
            "beneficiary_key": "3c866e34-23fe-46c2-a8b0-e39ca4348923",
            "days_to_bankruptcy_protest": 0,
            "document_number": "123456/01",
            "expiration": "2020-06-01",
            "fine_percentage": "3",
            "interest_daily_value": "0.34",
            "occurrence_type": "registration",
            "payer_address": "Rua Carlos Sampaio, 123",
            "payer_document": "41184562067",
            "payer_name": "João Ninguem",
            "payer_person_type": "natural",
            "payer_postal_code_root": "15800",
            "payer_postal_code_suffix": "020",
            "printing_policy": "no_printing",
            "registration_institution_enumerator": "qi_scd",
            "requester_profile": "09",
            "requester_profile_code": "329-09-0001-0000002"
        }
    ]
}
```

:::danger Atenção!
Caso os dados de endereço do pagador do boleto não sejam informados, não será possível realizar o protesto do boleto em caso de não pagamento. 
:::

### Query params

| Campo | Tipo | Descrição                                                                                 | Caracteres    |
|---|---|-------------------------------------------------------------------------------------------|---------------|
| `use_multi_process` | boolean | Indica se o processamento das ocorrências de registro serão enviados para processamento em fila ou se serão processados de forma sequencial. Caso seja este parâmetro seja informado como `true`, é obrigatório o envio do nosso número bancário `our_number` no payload da ocorrência de registro. | -          | 

### Body params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `occurrences` * | array of objects | Lista de ocorrências a serem processadas. | **[Objeto occurrences](#objeto-occurrences)** |

### Objeto occurrences

| Campo                                | Tipo             | Descrição                                                                                                                                               | Caracteres                                      |
|--------------------------------------|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------|
| `amount` *                           | double           | Valor do boleto.                                                                                                                                        | -                                               |
| `automatic_bankruptcy_protest`       | boolean          | Configuração de protesto automático.                                                                                                                    | -                                               |
| `bank_teller_instructions`           | string           | Instruções ao caixa (Mensagem/Observações do boleto).                                                                                                   | -                                               |
| `beneficiary_account_key`            | string           | Chave da conta do beneficiário.                                                                                                                         | -                                               |
| `beneficiary_key`                    | string           | Chave do beneficiário.                                                                                                                                  | -                                               |
| `days_to_bankruptcy_protest`         | int              | Número de dias para envio automático de protesto falimentar.                                                                                            | -                                               |
| `document_number`                    | string           | Numero do documento.                                                                                                                                    | -                                               |
| `expiration` *                       | string           | Data de vencimento.                                                                                                                                     | -                                               |
| `fine_percentage`                    | string           | Porcentagem de multa                                                                                                                                    | -                                               |
| `interest_daily_value`               | string           | Valor de juros por dia em reais                                                                                                                         | -                                               |
| `occurrence_type` *                  | string           | Tipo de ocorrência.                                                                                                                                     | -                                               |
| `payer_address`                      | string           | Endereço do pagador.                                                                                                                                    | -                                               |
| `payer_document` *                   | string           | Documento do pagador (CPF ou CNPJ).                                                                                                                     | -                                               |
| `payer_name` *                       | string           | Nome do pagador.                                                                                                                                        | -                                               |
| `payer_person_type` *                | string           | Tipo de pessoa pagante.                                                                                                                                 | -                                               |
| `payer_postal_code_root`             | string           | Os cinco primeiros digitos do CEP.                                                                                                                      | -                                               |
| `payer_postal_code_suffix`           | string           | Os três últimos dígitos do CEP.                                                                                                                         | -                                               |
| `printing_policy`                    | string           | Política de impressão do boleto                                                                                                                         | -                                               |
| `registration_institution_enumerator` * | string           | Será sempre `qi_scd`.                                                                                                                                   | `qi_scd`                                          |
| `requester_profile` *                | string           | Número da carteira.                                                                                                                                     | 02                                              |
| `requester_profile_code` *           | string           | Código da carteira composto da seguinte forma: "329-carteira-agencia-conta_com_7_digitos". OBS: a carteira de cobrança padrão QI Tech é de numero "09". | -                                               |
| `notification`                       | object           | Número da carteira.                                                                                                                                     | **[Objeto notification](#objeto-notification)** |  
| `discounts`                          | object | Lista de objetos com informações de desconto.                                                                                                           | **[Objeto discounts](#objeto-discounts)**       |  
| `guarantor_name`                     | string           | Nome do sacador avalista.                                                                                                                               | -                                               |
| `guarantor_document_root`            | string           | Base do CNPJ do sacador avalista.                                                                                                                       | -                                               |
| `guarantor_document_subsidiary`      | string           | Informação de CNPJ de matriz ou filial.                                                                                                                 | -                                               |
| `guarantor_document_digit`           | string           | Dígito verificador do CNPJ.                                                                                                                             | -                                               |

### Objeto notification
| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `document_number` * | string | Numero de documento do usuario que vai receber a notificação. | - |
| `email` * | string | Email do usuario que vai receber a notificação. | - |
| `name` * | string | Nome do usuario que vai receber a notificação.| - |
| `phone` * | object | Objeto contento informações do telefone do usuario que vai receber a notificação. |  **[Objeto phone](#objeto-phone)** |  
| `send_2_way` * | booleano | Enviar notificações de emissão de segunda via. | true/false |  
| `send_after_due_date` * | boolean | Enviar notificações após a data de vencimento do boleto. | true/false |
| `send_before_due_date` * | boolean | Enviar notificações antes da data de vencimento do boleto. | true/false |
| `send_on_protest` * | boolean | Enviar notificações de protesto. | true/false|

### Objeto phone 

| Campo | Tipo | Descrição |  Caracteres | 
| --- | --- | --- | --- | 
|`country_code` | string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 | 
| `area_code` | string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `number` | string |Número de telefone (apenas números) |  10 |

### Objeto discounts 
| Campo | Tipo | Descrição                                 | Caracteres | 
| --- | --- |-----------------------------------------|------------| 
|`discount_value` | float | Valor do desconto.                      | -          | 
| `discount_number` | int | Ordem que o desconto deve ser aplicado. | -          |
| `discount_limit_date` | date | Data limite do aplicação do desconto.   | 10         |

## Response

STATUS 200

Response Body

```json
{
  "bank_slips": [
    {
      "amount": "649.73",
      "bank_slip_key": "4bc636d0-1e41-4ce6-801c-475814bf4dcf",
      "bank_slip_status": "accepted",
      "barcode": "32991916500000649730001090000699935200347340",
      "beneficiary_account_key": "1c977186-9167-4ef1-b27d-08483429f74c",
      "beneficiary_key": "f01d4877-b1cc-4f4a-a8f9-952c2cef9ca8",
      "digitable_line": "32990001039000069993552003473403191650000064973",
      "expiration": "2022-11-10",
      "nfe_key": null,
      "nfe_url": null,
      "our_number": 6999352,
      "participant_control_number": null,
      "payer_postal_code": "38050000",
      "protest_status": "not_protested"
    }
  ],
  "file_info": {
    "beneficiary_code": null,
    "beneficiary_name": null,
    "file_sequence_id": null,
    "file_type_identifier": null,
    "file_type_literal": null,
    "service_code": null,
    "service_literal": null,
    "wrote_at": null
  },
  "occurrence_stats": {
    "bank_slip_edit": 0,
    "bankruptcy_protest_request": 0,
    "cancel_rebate": 0,
    "extension": 0,
    "notary_office_entry": 0,
    "notary_office_exit": 0,
    "notary_office_payment": 0,
    "notification": 0,
    "payment": 0,
    "payment_notice": 0,
    "payment_write_off": 0,
    "protest_cancel_and_write_off_request": 0,
    "protest_cancel_request": 0,
    "protest_remove_request": 0,
    "protest_request": 0,
    "rebate": 0,
    "registration": 1,
    "write_off": 0
  },
  "semantic_errors": []
}

```

STATUS 400

Response Body

```json
{
    "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}",
    "title": "Bad Request",
    "description": "Invalid request body.",
    "translation": "Corpo da requisição inválido.",
    "extra_fields": {},
    "code": "LEG000069"
}
```

### Response Params
| Campo | Tipo | Descrição                                 | Caracteres |
| --- | -- |--------------------------------------------------------------------| --- |
|`bank_slips` | list | Lista com a informações dos boletos registrados caso o parâmetro `use_multi_process` seja informado com o valor `false`. | [Objeto Bank Slip](#objeto-bank_slip) | 
| `file_info` | list | Informações do arquivo, .                            | [Objeto File Info](#objeto-file-info) |
| `occurrence_stats` | object | Informações do arquivo, .                            | [Objeto File Info](#objeto-file-info) |
| `semantic_errors` | list | Lista de erros no processamento de cada boleto. Será retornado caso exista algum erro no processamento e caso o parâmetro `use_multi_process` seja informado com o valor `false`. | [Objeto Semantic Error](#objeto-semantic-error) |

### Objeto bank_slip
| Campo | Tipo | Descrição                                 | Caracteres |
| --- | -- |--------------------------------------------------------------------| --- |
|`amount` | float | Valor do boleto. | - |
|`bank_slip_key` | uuid | Chave unica de identificação do boleto na QI Tech. | 36 |
|`bank_slip_status` | enum | Chave unica de identificação do boleto na QI Tech. | [Enumeradores bank_slip_status](#enumeradores-bank_slip_status) |
|`barcode` | string | Código de barras do boleto. | 44 |
|`beneficiary_account_key` | uuid | Chave unica de identificação da conta em que o boleto foi registrado. | 36 |
|`beneficiary_key` | uuid | Chave unica de identificação do titular da conta em que o boleto foi registrado. | 36 |
|`digitable_line` | uuid | Linha digitável do boleto. | 47 |
|`expiration` | string | Data de vencimento do boleto. | 10 |
|`nfe_key` | string | Chave unica de identificação da nota fiscal eletrônica. | - |
|`nfe_url` | string | URL da nota fiscal eletrônica. | - |
|`our_number` | int | Nosso número bancário. É um número sequencial de identificação deste boleto em relação a conta (carteira de cobrança) em que ele foi registrado. Seu valor pode ser informado na requisição de registro do boleto. Caso não seja informado, a QI Tech gerará um valor deste campo (sendo este um valor incremental, ex: 1º boleto registrado na conta terá o `our_number` de valor 1, o 16º boleto registrado na conta terá o `our_number` de valor 16). | - 
|`participant_control_number` | string | Número de controle do participante. | 10 |
|`payer_postal_code` | string | CEP do pagador do boleto. | 8 |
|`protest_status` | string | Situação do protesto do boleto, caso o protesto tenha sido solicitado. | [Enumeradores protest_status](#enumeradores-protest_status) |

### Enumeradores bank_slip_status
| Enumerador | Descrição |
| --- | -- |
| `accepted` | Boleto aceito para processamento |
| `registered` | Registro do boleto foi concluído na câmara de registro de boletos |
| `paid` | Valor do pagamento do boleto foi creditado na conta do beneficiário do boleto |
| `written_off` | Boleto baixado (boleto não é mais pagável) |
| `rejected` | Registro de boleto rejeitado pela câmara de registro de boletos  |
| `payment_notice` | Aviso de que o pagamento do boleto foi processado no banco pagador (porém a liquidação na conta do beneficiário ainda não ocorreu) |
| `notary_office_payment_notice` | Aviso de que o pagamento de um boleto protestado foi processado no banco pagador (porém o cartório ainda não realizou o repasse do pagamento e a liquidação na conta do beneficiário ainda não ocorreu) |

### Enumeradores protest_status
| Enumerador | Descrição |
| --- | -- |
| `not_protested` | Boleto não possui solicitação de protesto. |
| `protest_requested` | Boleto com solicitação de protesto em processamento pela QI Tech. |
| `notary_office_entry` | Solicitação de protesto de boleto foi aceita pelo cartório. |
| `protest_cancel_requested` | Solicitação de cancelamento de protesto em processamento pela QI Tech. |
| `notary_office_exit` | Protesto do boleto foi retirado do cartório. |
| `protested` | Protesto foi confirmado pelo cartório e o boleto se encontrada protestado. |
| `paid_at_notary_office` | Cartório identificou o pagamento do protesto do boleto e esta processando o repasse do pagamento para a QI Tech. |
| `judicially_suspended` | Protesto suspenso judicialmente. |
| `protest_remove_requested` | Solicitação de retirada de protesto foi aceita pelo cartório. |

---

# Enviar instrução de boleto

URL: /documentation/boletos/v1/enviar_instrucao_de_boleto

## Enviar instrução de Boleto

Para solicitar uma instrução de boleto, basta fazer a requisição de emissão com o "occurrence_type" conforme abaixo:

| Valor | Descrição |
|---|---|
| `registration` | Registrar um novo boleto. |
| `bank_slip_edit` | Editar informações do pagador de um boleto existente. |
| `extension` | Prorrogação da data de vencimento de um boleto existente. |
| `write_off` | Baixa sem financeiro de um boleto. |
| `rebate` | Abatimento do pagamento. |
| `cancel_rebate` | Cancelar abatimento do pagamento. |
| `bank_slip_edit` | Edição de um boleto existente (Desconto, Endereço, Multa/juros). |
| `protest_request` | Protestar boleto. |
| `bankruptcy_protest_request` | Protesto Falimentar. |
| `protest_remove_request` | Cancelar Protesto. |
| `protest_cancel_request` | Sustar Protesto sem Baixa. |
| `protest_cancel_and_write_off_request` | Sustar Protesto com Baixa. |

**Exemplos de request**

### Prorrogação

Para solicitar essa instrução, o boleto precisa estar registrado, e deve estar pagável.

Request Body

```json
{
  "occurrences": [
    {
      "occurrence_type": "extension",
      "requester_profile_code": "329-01-0001-0000001",
      "our_number": 1000000,
      "expiration": "2022-06-15"
    }
  ]
}

```

### Baixa

Para solicitar essa instrução, o boleto precisa estar registrado.

Request Body

```json
{
  "occurrences": [
    {
      "occurrence_type": "write_off",
      "requester_profile_code": "329-01-0001-0000001",
      "our_number": 1000000
    }
  ]
}

```

### Abatimento

Para solicitar essa instrução, o boleto não pode estar vencido.

Request Body

```json
{
  "occurrences": [
    {
      "occurrence_type": "rebate",
      "our_number": 1000000,
      "rebate_amount": 10,
      "requester_profile_code": "329-01-0001-0000001"
    }
  ]
}

```

### Cancelar abatimento

Para solicitar essa instrução, o boleto deve conter um abatimento ativo, e não pode estar vencido.

Request Body

```json
{
  "occurrences": [
    {
      "our_number": 1000000008,
      "occurrence_type": "cancel_rebate",
      "requester_profile_code": "329-01-0001-0000001",
      "bank_slip_key": "ce9b6834-4c6c-423a-a337-b9815a462ae5"
    }
  ]
}

```

### Desconto

Para solicitar essa instrução, o boleto não pode estar vencido/baixado.

Request Body

```json
{
  "occurrences": [
    {
      "our_number": 1000000008,
      "occurrence_type": "bank_slip_edit",
      "requester_profile_code": "329-01-0001-0000001",
      "registration_institution_enumerator": "qi_scd",
      "discounts": [
        {
          "discount_number": 1,
          "discount_limit_date": "2022-06-14",
          "discount_value": 10
        }
      ]
    }
  ]
}

```

### Adicionar/Editar Endereço

Para solicitar essa instrução, o boleto deve estar registrado, e ser pagável.

Request Body

```json
{
  "occurrences": [
    {
      "our_number": 1000000008,
      "occurrence_type": "bank_slip_edit",
      "requester_profile_code": "329-01-0001-0000001",
      "payer_address": "Rua dos Alfeneiros, 4, Little Whinging - Surrey, City, SP",
      "payer_postal_code_root": "17057",
      "payer_postal_code_suffix": "770"
    }
  ]
}

```

### Editar Multa/Juros

Para solicitar essa instrução, o boleto deve estar registrado, e ser pagável.

Request Body

```json
{
  "occurrences": [
    {
      "our_number": 1000000008,
      "occurrence_type": "bank_slip_edit",
      "requester_profile_code": "329-01-0001-0000001",
      "fine_percentage": 1,
      "interest_daily_value": 0.33
    }
  ]
}

```

### Protesto

Para solicitar essa instrução, o boleto precisa estar vencido, e precisa ter os dados de endereço do pagador.

Request Body

```json
{
  "occurrences": [
    {
      "our_number": 1000000002,
      "occurrence_type": "protest_request",
      "requester_profile_code": "329-01-0001-0000001"
    }
  ]
}

```

### Protesto Falimentar

Para solicitar essa instrução, o boleto precisa estar vencido, e precisa ter os dados de endereço do pagador.

Request Body

```json
{
  "occurrences": [
    {
      "our_number": 1000000002,
      "occurrence_type": "bankruptcy_protest_request",
      "requester_profile_code": "329-01-0001-0000001"
    }
  ]
}

```

### Cancelar protesto

Para solicitar essa instrução, o boleto precisa estar protestado.

Request Body

```json
{
  "occurrences": [
    {
      "our_number": 1000000002,
      "occurrence_type": "protest_remove_request",
      "requester_profile_code": "329-01-0001-0000001"
    }
  ]
}

```

### Cancelar protesto automático

Para solicitar essa instrução, o boleto precisa ser registrado com essa opção ativa.

Request Body

```json
{
  "occurrences": [
    {
      "our_number": 1000000002,
      "occurrence_type": "bank_slip_edit",
      "requester_profile_code": "329-01-0001-0000001",
      "automatic_bankruptcy_protest": false,
      "automatic_protest": false
    }
  ]
}

```

### Sustar protesto sem baixa

Para solicitar essa instrução, o boleto precisa ser estar protestado.

Request Body

```json
{
  "occurrences": [
    {
      "our_number": 1000000002,
      "occurrence_type": "protest_cancel_request",
      "requester_profile_code": "329-01-0001-0000001"
    }
  ]
}

```

### Cancelar protesto automático

Para solicitar essa instrução, o boleto precisa ser estar protestado.

Request Body

```json
{
  "occurrences": [
    {
      "our_number": 1000000002,
      "occurrence_type": "protest_cancel_and_write_off_request",
      "requester_profile_code": "329-01-0001-0000001"
    }
  ]
}

```

## Exemplo de response

A resposta varia de cada tipo de instrução, geralmente resultando na mudança dos campos de occurrence_stats, na chave de cada instrução.

Já no campo semantic_errors, é devolvido uma lista com objetos de cada ocorrência com seus respectivos erros (exemplo abaixo).

Request Body

```json
{
  "file_info": {
    "beneficiary_code": null,
    "beneficiary_name": null,
    "file_sequence_id": null,
    "file_type_identifier": null,
    "file_type_literal": null,
    "service_code": null,
    "service_literal": null,
    "wrote_at": null
  },
  "occurrence_stats": {
    "bank_slip_edit": 0,
    "bankruptcy_protest_request": 0,
    "cancel_rebate": 0,
    "extension": 0,
    "notary_office_entry": 0,
    "notary_office_exit": 0,
    "notary_office_payment": 0,
    "notification": 0,
    "payment": 0,
    "payment_notice": 0,
    "payment_write_off": 0,
    "protest_cancel_and_write_off_request": 0,
    "protest_cancel_request": 0,
    "protest_remove_request": 0,
    "protest_request": 0,
    "rebate": 0,
    "registration": 0,
    "write_off": 1
  },
  "semantic_errors": [
    {
      "0": {
        "errors": [
          {
            "created_at": "2019-03-12T12:59:32",
            "reason_code": "CEP Inválido",
            "translation_en_us": "Invalid Postal Code",
            "translation_pt_br": "CEP Inválido"
          }
        ],
        "our_number": 1000000000,
        "participant_control_number": null
      }
    }
  ]
}

```

---

# Introdução

URL: /documentation/boletos/v1/introducao

Carteira de cobrança é o serviço que permite a emissão de boletos bancários. Existem diversos tipos de carteiras e cada uma define como serão gerados seus boletos, os custos, taxa de liquidação, conta a ser creditada e diversas configurações que permitirão ao banco fazer a cobrança correta. Durante a abertura de conta na QI Tech, fica disponível automaticamente para o cliente uma carteira dentro da QI e uma carteira no Bradesco, com as configurações globais de cobrança da QI Tech.

Além disso, se o cliente tiver interesse no cadastro ou alteração de uma carteira, com configurações diferentes da configuração global, ele poderá solicitar o serviço à nossa equipe.

## Como funciona a emissão de boletos?

As APIs da QI Tech permitem a abstração do ciclo de vida de um boleto através de uma maquina de estados, onde temos os seguintes status:

## Solicitação de registro
    - accepted: Solicitação de emissão de boleto entrou para fila de registro;
    - rejected : Solicitação de emissão de boleto rejeitada, quando a solicitação de registro do boleto contem erro de semântica que impede o registro.

## Registro efetivado
    registered: Boleto registrado e disponível para pagamento.

## Notificação de pagamento
    - payment_notice : Aviso de pagamento do boleto, essa notificação é enviada no momento que o boleto é pago, mas ainda não existe a liquidação financeira.
    - notary_office_payment_notice : Aviso de pagamento do boleto, essa notificação é enviada no momento que o boleto é pago em cartório, mas ainda não existe a liquidação financeira.

## Liquidação
    - paid : Boleto pago - baixado com liquidação financeira.
    - written_off : Boleto baixado sem liquidação financeira.

---

# Webhooks de boletos

URL: /documentation/boletos/webhooks/boleto

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

## Introdução

Ao longo do ciclo de vida dos boletos, dentro do nosso sistema, serão enviados webhooks com os seguintes status do boleto (`bank_slip_status`):

| Enumerador                    | Tradução                       | Descrição                                                       |
|-------------------------------|--------------------------------|------------------------------------------------------------------------------------------------|
|  registered                   | registrado                     | Boleto registrado e disponível para pagamento |
|  rejected                     | rejeitado                      | Solicitação de emissão de boleto rejeitada por erros de validação                               |
|  payment_notice               | aviso de pagamento             | Aviso de pagamento do boleto (boleto pago mas pagamento ainda não liquidado)                    |
|  notary_office_payment_notice | aviso de pagamento em cartório | Aviso de pagamento em cartório do boleto (boleto pago mas pagamento ainda não liquidado)                    |
|  paid                         | pago                           | Boleto pago e liquidado financeiramente                         |
|  written_off                  | baixado                        | Boleto baixado (não pode mais ser pago) e sem liquidação financeira                              |
|  payment_blocked              | bloqueado para pagamento       | Bloqueado para pagamento devido a fluxo de protesto                    |

E os webhooks são enviados sempre que são confirmadas ocorrências dos seguintes tipos (`occurrence_type`):

| Enumerador                    | Tradução                       | Descrição                                                                    |
|-------------------------------|--------------------------------|------------------------------------------------------------------------------|
|  registration                 | registro                       | Registro do boleto                                                           |
|  rebate                       | abatimento                     | Abatimento de parte do valor base do título                                  |
|  cancel_rebate                | cancelamento de abatimento     | Cancelamento de abatimento existente                                         |
|  extension                    | extensão                       | Extensão da data de expiração do título                                      |
|  write_off                    | baixa                          | Baixa do boleto                                                              |
|  protest_write_off            | baixa por protesto             | Baixa do boleto por protesto em cartório                                     |
|  payment_write_off            | baixa por pagamento            | Baixa do boleto por pagamento                                                |
|  discount                     | desconto                       | Alteração dos descontos                                                      |
|  fine                         | multa                          | Alteração da multa                                                           |
|  interest                     | juros                          | Alterações dos juros                                                         |
|  protest_request              | pedido de protesto             | Pedido de protesto em cartório                                               |
|  bankruptcy_protest_request   | pedido de protesto falimentar  | Pedido de protesto falimentar em cartório                                    |
|  notary_office_entry          | entrada em cartório            | Ocorrência de entrada do título em cartório                                  |
|  protest_cancel_request       | desistência de pedido de protesto | Desistência do pedido de protesto corrente                                |
|  protest_remove_request       | sustação de protesto           | Sustação do protesto do título                                               |
|  notary_office_exit           | saída do cartório              | Ocorrência de saída do título do cartório                                    |
|  payment_notice               | aviso de pagamento             | Aviso de pagamento do boleto (boleto pago mas pagamento ainda não liquidado) |
|  notary_office_payment_notice | aviso de pagamento em cartório | Aviso de pagamento em cartório do boleto (boleto pago mas pagamento ainda não liquidado)  |
|  payment                      | pagamento                      | Notificação de que o boleto foi pago e baixado                               |

:::info Informação
O timeout para resposta de nosso webhooks é de 10 segundos.
:::

## Exemplos
----

### Registro

Webhook Body: ocorrência aceita

```json
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"bank_slip_key": "11b13b2c-4204-41b3-8596-2ee7ecbde38c",
		"bank_slip_status": "registered",
		"occurrence_key": "9077cc0b-5bbd-4432-888e-6bf6384c250a",
		"occurrence_type": "registration",
		"occurrence_status": "confirmed"
	}
}
```

Webhook Body: ocorrência rejeitada

```json
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"bank_slip_key": "ae783ed7-b892-4e48-8480-b045e3b492f5",
		"bank_slip_status": "rejected",
		"occurrence_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
		"occurrence_type": "registration",
		"occurrence_status": "rejected"
	}
}
```

### Abatimento/cancelamento de abatimento

Webhook Body: abatimento

```json
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"bank_slip_key": "11b13b2c-4204-41b3-8596-2ee7ecbde38c",
		"bank_slip_status": "registered",
		"occurrence_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
		"occurrence_type": "rebate",
		"occurrence_status": "confirmed"
	}
}
```

Webhook Body: cancelamento de abatimento

```json
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"bank_slip_key": "11b13b2c-4204-41b3-8596-2ee7ecbde38c",
		"bank_slip_status": "registered",
		"occurrence_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
		"occurrence_type": "cancel_rebate",
		"occurrence_status": "confirmed"
	}
}
```

### Prorrogação

Webhook Body

```json
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"bank_slip_key": "11b13b2c-4204-41b3-8596-2ee7ecbde38c",
		"bank_slip_status": "registered",
		"occurrence_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
		"occurrence_type": "extension",
		"occurrence_status": "confirmed"
	}
}
```

### Desconto

Webhook Body

```json
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"bank_slip_key": "a8df1c2e-77ff-49ea-9e7a-8fd536a6e357",
		"bank_slip_status": "registered",
		"occurrence_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
		"occurrence_type": "discount",
		"occurrence_status": "confirmed"
	}
}
```

### Juros

Webhook Body

```json
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"bank_slip_key": "69f3f345-07c5-4c80-a8dd-51054afdad01",
		"bank_slip_status": "registered",
		"occurrence_key": "8550e47a-7554-455c-bdd8-cf0c048a277c",
		"occurrence_type": "interest",
		"occurrence_status": "confirmed"
	}
}
```

### Multa

Webhook Body

```json
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"bank_slip_key": "97e6edab-b793-4eb6-a1a7-0a27e1d5c73e",
		"bank_slip_status": "registered",
		"occurrence_key": "47b06bdb-c006-47a7-81f2-7aac7fff823b",
		"occurrence_type": "fine",
		"occurrence_status": "confirmed"
	}
}
```

### Baixa

O campo `occurrence_reason` é opcional e enviado quando o banco informa o motivo da baixa. Ele contém o código e o nome do motivo fornecidos pela instituição financeira.

Webhook Body: sem motivo

```json
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"bank_slip_key": "45c21054-57fd-4d28-8d5a-0cdc5cb29670",
		"bank_slip_status": "written_off",
		"occurrence_key": "0b92bd47-fae5-46c0-8c40-e5aebc9ecd28",
		"occurrence_type": "write_off",
		"occurrence_status": "confirmed"
	}
}
```

Webhook Body: com motivo

```json
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2026-05-04T21:12:07.877Z",
	"data": {
		"bank_slip_key": "25add0b0-cb2d-4be4-8f22-4305a4dd9793",
		"bank_slip_status": "written_off",
		"occurrence_key": "ca71f446-be05-47cc-b470-234e4806344c",
		"occurrence_type": "write_off",
		"occurrence_status": "confirmed",
		"occurrence_reason": {
			"bank_reason_code": "16",
			"bank_reason_name": "Título Baixado pelo Banco por decurso de Prazo"
		}
	}
}
```

### Baixa por protesto

Webhook Body

```json
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-10-25T18:05:01.395Z",
	"data": {
		"bank_slip_key": "7182639f-dea5-46c6-99c6-af0d94d772cb",
		"bank_slip_status": "written_off",
		"occurrence_key": "93380917-beee-4f3e-af01-6c24e140d53d",
		"occurrence_type": "protest_write_off",
		"occurrence_status": "confirmed"
	}
}
```

### Baixa por pagamento

Webhook Body

```json
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-10-18T18:02:15.152Z",
	"data": {
		"bank_slip_key": "40d6a1bc-cfed-4444-a901-e02ecc169ce5",
		"bank_slip_status": "written_off",
		"occurrence_key": "78221daa-945f-485b-b39c-97ef0e251afe",
		"occurrence_type": "payment_write_off",
		"occurrence_status": "confirmed"
	}
}
```

### Pedido de protesto

Webhook Body

```json
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-10-16T20:54:13.013Z",
	"data": {
		"bank_slip_key": "f03c5fec-b31c-402a-b832-80da8a493653",
		"bank_slip_status": "payment_blocked",
		"occurrence_key": "304958f6-cdf2-4fb1-b8f3-5482030bf0eb",
		"occurrence_type": "protest_request",
		"occurrence_status": "confirmed"
	}
}
```

### Pedido de protesto falimentar

Webhook Body

```json
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-10-16T20:54:13.013Z",
	"data": {
		"bank_slip_key": "21aeefb4-4fa1-4e32-b2bb-32a7486128f0",
		"bank_slip_status": "payment_blocked",
		"occurrence_key": "11a7e9e8-4667-471b-bc3f-2f65f77e22e9",
		"occurrence_type": "bankruptcy_protest_request",
		"occurrence_status": "confirmed"
	}
}
```

### Entrada em cartório

Webhook Body

```json
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-10-17T18:00:48.341Z",
	"data": {
		"bank_slip_key": "5bc4c1d4-d51b-4b0b-b308-81850d04e523",
		"bank_slip_status": "payment_blocked",
		"occurrence_key": "159e6e3f-fce5-4362-829e-1595fc14d66c",
		"occurrence_type": "notary_office_entry",
		"occurrence_status": "confirmed"
	}
}
```

### Cancelamento de protesto

Webhook Body

```json
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-10-23T18:00:52.374Z",
	"data": {
		"bank_slip_key": "96d2a896-f2da-484c-8d40-20fabbde15ee",
		"bank_slip_status": "registered",
		"occurrence_key": "2505fedf-0061-478b-b45e-8420b755ebbb",
		"occurrence_type": "protest_cancel_request",
		"occurrence_status": "confirmed"
	}
}
```

### Sustação de protesto

Webhook Body

```json
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-10-30T18:01:00.452Z",
	"data": {
		"bank_slip_key": "878d462e-be4e-40bd-b797-b831fef87f48",
		"bank_slip_status": "written_off",
		"occurrence_key": "cb08785d-0a4d-41f4-a64c-bafe730b175b",
		"occurrence_type": "protest_remove_request",
		"occurrence_status": "confirmed"
	}
}
```

### Saída do cartório

Webhook Body

```json
{
	"webhook_type": "baas.bank_slip.occurrence",
	"webhook_datetime": "2024-11-01T18:01:01.949Z",
	"data": {
		"bank_slip_key": "79d07a3d-3953-4195-a2e2-bbbf10635f27",
		"bank_slip_status": "registered",
		"occurrence_key": "c703b04c-7334-40fe-bf8d-b43bd991dbab",
		"occurrence_type": "notary_office_exit",
		"occurrence_status": "confirmed"
	}
}
```

### Aviso de pagamento

Primeiro webhook: boleto foi pago, mas ainda não foi liquidado

Webhook Body

```json
{
	"webhook_type": "baas.bank_slip.payment_notice",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"bank_slip_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
		"bank_slip_status": "payment_notice",
		"occurrence_key": "d0341ad7-aa87-4dad-929b-38c8c9218f23",
		"occurrence_type": "payment_notice",
		"occurrence_status": "confirmed"
	}
}
```

### Aviso de pagamento em cartório

Primeiro webhook: boleto foi pago em cartório, mas ainda não foi liquidado

Webhook Body

```json
{
	"webhook_type": "baas.bank_slip.notary_office_payment_notice",
	"webhook_datetime": "2024-10-16T18:00:43.621Z",
	"data": {
		"bank_slip_key": "05f2b81b-b241-4e72-9b2c-7312257a0284",
		"bank_slip_status": "notary_office_payment_notice",
		"occurrence_key": "3ecab7b1-c991-4d91-8d71-08a34eec1d7d",
		"occurrence_type": "notary_office_payment_notice",
		"occurrence_status": "confirmed"
	}
}
```

### Pagamento

Webhook Body

```json
{
	"webhook_type": "baas.bank_slip.payment",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"bank_slip_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
		"bank_slip_status": "paid",
		"occurrence_key": "db04719d-4370-4f3f-82b7-d72d3db2f39e",
		"occurrence_type": "payment",
		"occurrence_status": "confirmed",
		"paid_amount": 850.0,
		"paid_rebate_amount": 200.0,
		"paid_discount_amount": 0.0,
		"paid_fine_amount": 0.0,
		"paid_interest_amount": 50.0,
		"payment_method": "account_debit",
		"payment_origin": "qr_code",
		"payment_credit_date": "2024-07-02",
		"payment_date": "2024-07-02",
		"payment_bank": {
			"code": "341",
			"ispb": 60701190,
			"name": "ITAU UNIBANCO S.A."
		},
		"payment_branch": "0216"
	}
}
```

:::info Informação
Os campos `payment_bank` e `payment_branch` indicam o banco e a agência em que o boleto foi pago. Eles só são preenchidos quando essa informação é recebida na liquidação do pagamento; caso o banco pagador não seja identificado, `payment_bank` será retornado como `null`.
:::

:::info Informação
`payment_date` é a data em que o pagamento foi efetivamente informado pela instituição pagadora, enquanto `payment_credit_date` é a data em que o valor foi creditado ao beneficiário — elas podem divergir (ex: pagamento realizado fora do horário útil, com crédito no próximo dia útil). Para pagamentos com `payment_origin: "qr_code"`, `payment_date` é igual a `payment_credit_date`.
:::

### Enumeradores payment_origin

| Enumerador         | Descrição                               |
|--------------------|-----------------------------------------|
| cash       | Espécie                  |
| account_debit             | Débito em conta                |
| credit_card      | Cartão de crédito |
| check          | Cheque                  |

### Enumeradores payment_origin

| Enumerador           | Descrição                                |
|----------------------|------------------------------------------|
| phisical_cashier     | Agências - Postos tradicionais           |
| taa                  | Terminal de Auto-atendimento             |
| internet             | Internet (home/office bank)              |
| corban               | Correspondente bancário                  |
| call_center          | Central de atendimento (call center)     |
| eletronic_file       | Arquivo eletrônico                       |
| dda                  | DDA                                       |
| digital_correspondent| Correspondente Digital                   |
| qr_code              | Pagamento via Pix QR Code                |

---

# Webhooks de carteiras de boletos

URL: /documentation/boletos/webhooks/carteira

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

## Introdução

Após a criação de uma carteira (`requester_profile`) dentro do nosso sistema, serão enviados webhooks com os seguintes status:

| Enumerador                    | Tradução               | Descrição                                                  |
|-------------------------------|------------------------|------------------------------------------------------------|
|  opened                       | aberto                 | Carteira de boletos aberta e pronta para registrar boletos |

:::info Informação
O timeout para resposta de nosso webhooks é de 10 segundos.
:::

## Exemplos
----

### Confirmação de abertura

Webhook Body

```json
{
	"webhook_type": "baas.bank_slip.requester_profile",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"requester_profile_key": "fd86d9b1-2a5e-4e03-9a59-a043c7632c97",
		"request_control_key": "0868a24b-4a69-4138-ac4d-ecaeddf0005f",
		"requester_profile_code": "329-04-2338-2625918",
		"requester_profile_status": "opened"
	}
}
```

---

# Webhooks de liquidação

URL: /documentation/boletos/webhooks/liquidacao

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

## Introdução

Em nosso sistema, os grupos de liquidação são uma forma de conciliar as transações com os boletos liquidados. Esse processo (liquidação) descreve a transferência do valor de um boleto pago para a conta que deve receber esse pagamento. Resumidamente, sempre que a QI recebe a informação de que um boleto foi pago por outro banco ou, no caso de boletos protestados, pelo cartório, é criada uma liquidação para esse boleto específico. Posteriormente, são criados os **grupos de liquidação**, que representam lotes de liquidações agrupadas por tipo.

Em um momento posterior, é realizada a transação de pagamento desse grupo de liquidação para a conta do cliente. A **transaction_key** dessa transação é então salva para fins de conciliação, dessa foma você pode ver todos os boletos que foram liquidados em uma determinada transação. Por exemplo, se você tiver cinco boletos de R$ 5,00 cada, sendo que um foi pago via cartório, um foi pago via QR Code PIX e os outros três foram pagos utilizando a linha digitável ou código de barras por outro banco, serão criadas cinco liquidações referentes a esses boletos. Em seguida, essas liquidações serão agrupadas em três grupos de liquidação: um de R$ 15,00 com os três boletos pagos utilizando a linha digitável ou código de barras, para os quais será realizada uma única transação, outro de R$ 5,00 para o boleto pago via QR Code PIX e o último também de R$ 5,00 com o boleto pago via cartório.

:::info Informação
O timeout para resposta de nosso webhooks é de 10 segundos.
:::

## Exemplos
----

### Grupo de liquidação

Webhook Body

```json
{
    "webhook_type": "baas.bank_slip.bank_slip_settlement_group",
    "webhook_datetime": "2024-08-13T21:35:55.679Z",
    "data": {
        "bank_slip_settlement_group_key": "87e6687b-d02b-45dc-b5b8-b51e16ec0a03",
        "amount": 1,
        "bank_slip_settlement_group_type": "siloc",
        "bank_slip_settlement_group_status": "settled",
        "transaction_key": "fc60a57e-c6ac-4e39-a3cf-2dc3c491dac6"
    }
}
```

### Enumeradores bank_slip_settlement_group_type

| Enumerador                   | Descrição                                                                    |
|------------------------------|------------------------------------------------------------------------------|
| siloc                        | para pagamento de títulos (valor do título menor que R$ 250.000)                          |
| qr_code                      | para pagamento de títulos realizados via QR Code |
| str                          | para pagamento de títulos VR (valor do título maior que R$ 250.000) |
| notary_office                | para pagamento de títulos realizados via cartório             |

### Enumeradores bank_slip_settlement_group_status

| Enumerador                   | Descrição                                                                    |
|------------------------------|------------------------------------------------------------------------------|
| pending                      | grupo de liquidação criado mas a transação não foi realizada  |
| settled                      | grupo de liquidação criado e transação realizada |

---

# Webhooks de arquivos retorno

URL: /documentation/boletos/webhooks/retorno

Os arquivos retorno servem para conciliação. Nele, cada linha de Registro de Transação (Tipo 1) diz respeito a uma instrução (seja de emissão, prorrogação, abatimento etc.) que foi confirmada ou rejeitada pela CIP/Nuclea no dia anterior.

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

:::info Informação
O timeout para resposta de nosso webhooks é de 10 segundos.
:::

## Exemplos
----

### Arquivo retorno

Webhook Body

```json
{
    "webhook_type": "baas.bank_slip.discharge_file",
    "webhook_datetime": "2024-08-13T21:35:55.679Z",
    "data": {
        "discharge_file_key": "f1a8fe59-29cd-49e5-8d18-55194869b45c",
        "reference_date": "2024-10-15",
        "requester_profile_key": "fc60a57e-c6ac-4e39-a3cf-2dc3c491dac6",
        "discharge_file_url": "https://storage.googleapis.com/local-bank-slip-api/2024/61a746ca-05bf-429d-99c3-3fba0f9fbea7/329-20-7336-3073959/discharge/CB15102401.RET",
        "cnab_bank": "qi_scd",
        "cnab_layout": "400",
    }
}
```

:::info Bancos Suportados
Atualmente, o webhook de arquivo retorno suporta os seguintes bancos:
- Bradesco (bradesco)
- Itaú (itau)
- QI SCD (qi_scd)
- Santander (santander)
:::

:::info Layouts Suportados
Atualmente, o webhook de arquivo retorno suporta os seguintes layouts CNAB:
- CNAB 400 (400)
:::

---

# Autenticação

URL: /documentation/caas/account_event/authentication

> Para autenticar uma chamada, utilize o código seguinte:

```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição.
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

> Substitua a API Key 'EXAMPLE-OF-API-KEY' pela sua chave, que deve ser obtida através do nosso time de suporte.

Utilizamos uma API Key para permitir acesso à nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br .

Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:

`Authorization: EXAMPLE-OF-API-KEY`

:::info **Atenção**

Você deve substituir EXAMPLE-OF-API-KEY pela sua chave, que deve ser obtida através do nosso time de suporte.
:::

---

# Objeto Device Validation

URL: /documentation/caas/account_event/device_validation

A validação de um dispositivo por identificação única deve ser realizada através do endpoint de Event Type Device Validation. Os dados enviados deverão ser os dados gerados na API de Cadastro de Dispositivos, juntamente com um id de sessão de Device Scan, isto é, para realizar uma validação de dispositivo a aplicação deve utilizar o SDK para gerar um identificador único e deve ser realizado o cadastro do dispositivo para que ele possa ser identificado posteriormente.

### Dinâmica dos Status - **analysis_status**

O status **analysis_status** indica o status da decisão do motor de fraude e possui uma máquina de estados bastante simples:

* automatically_approved
* automatically_reproved
* in_manual_analysis
* manually_approved
* manually_reproved
* pending

## Definição do Objeto Device Validation

Request Body

```json
{
  "id": "12345678",
  "account_id": "12345678",
  "person_id": "12345678",
  "session_id": "12345678",
  "event_date": "2019-12-11T11:37:15.12-03:00"
}
```

Todas as trocas de informação de uma validação utilizam a seguinte definição para este objeto. Em alguns casos, para facilitar a implementação e diminuir o fluxo de dados entre as partes, algumas informações poderão ser omitidas.

nome | tipo | descrição
:----: | :----: | ---------
id | string | Identificador do evento. **É essencial que este número seja único para cada requisição** *(obrigatório)*
account_id | string | Identificador da conta cadastrada no sistema de cadastro de dispositivo. Para realizar mais de uma análise referente a um mesmo cadastro, apenas utilize o mesmo account_id nas diferentes análises.*(obrigatório)*
person_id | string | Identificador do usuário associado a conta cadastrada no sistema de cadastro de dispositivo. Para realizar mais de uma análise referente a um mesmo cadastro, apenas utilize o mesmo person_id nas diferentes análises.*(obrigatório)*
session_id | string | Identificador da sessão de análise da Device Scan.*(obrigatório)*
face_recognition_key | string | Identificador da imagem gerada no SDK para identificação facial.
event_date | datetime | Data e hora o evento *(obrigatório)*

## Enviar um Device Validation

Request Body

```json
  {
    "id": "12345",
    ...
  }
```

Response Body

```json
  {
    "id": "12345",
    "analysis_status": "automatically_approved",
    "reason": "rule_decision_enum"
  }
```

Para realizar a validação de um Dispositivo, basta enviar um objeto do tipo Device Validation ao seguinte endpoint:

`POST https://api.caas.qitech.app/account_event/event_type/device_validation/event`

---

# Status HTTP

URL: /documentation/caas/account_event/http_status

Todas as APIs da QI Tech utilizam a seguinte padronização nos status HTTP de retorno, conforme a RFC 7231 :

Status HTTP | Significado | Descrição
---------- | ------- | ---------------------------------
400 | Bad Request | A requisição enviada possui algum erro de formatação. Geralmente, retornamos no corpo da mensagem uma explicação de onde está o erro.
401 | Unauthorized | Houve algum problema na autenticação, verifique se a API Key está correta e no header correto, conforme a seção Autenticação .
403 | Forbidden | O endpoint acessado é de uso interno e não está disponível para esta API Key.
404 | Not Found | O dado requisitado não foi encontrado usando a chave utilizada. Este status também é retornado quando um endpoint inválido é requisitado.
405 | Method Not Allowed | O método HTTP utilizado não se aplica ao endpoint utilizado.
406 | Not Acceptable | Os dados enviados no corpo da requisição são inválidos. Em geral, isso significa que os dados enviados não são um JSON válido.
409 | Conflict | O id da requisição corresponde a um id já processado anteriormente. Este status é retornado no caso de requisições duplicadas enviadas ao servidor.
500 | Internal Server Error | Tivemos um problema para processar esta requisição, ao encontrarmos esse erro nossos especialistas são automaticamente notificados e iniciam a análise e solução imediatamente.
503 | Service Unavailable | Você se deparou com uma indisponibilidade, planejada ou não, de infraestrutura dos nossos servidores.

---

# Introdução

URL: /documentation/caas/account_event/introduction

Bem vindo à API de Eventos de Conta da QI Tech! Esta API dá acesso aos serviços de monitoramento e regras para eventos dentro de contas da sua plataforma!

Esta API pode ser utilizada para a validação de dispositivos juntamente com a api de Device Scan e Cadastro de Dispositivos, mas pode ser usada para outras validações como:

* Login.
* Acesso a telas.
* Alteração de senha.
* Alteração de dados cadastrais.
* Validações pré-transações.
* Validações de liveness.

Você pode utilizar a nossa API para acessar os endpoints para avaliar os seguintes tipos de eventos:

* **Device Validation** - utilizado para validação de identificação única de um dispositivo.
* **Pre Pix Transaction** - utilizado para a pré-validação de transações Pix.
* **Registration Data Validation** - utilizado para a validação de dados cadastrais.

Diferentes tipos de eventos podem ser implementados dependendo das necessidades do seu sistema.

Ao lado, você pode observar a implementação da API utilizando curl. Com isso, você possui exemplos para poder adaptar adequadamente à linguagem de programação da sua preferência.

## Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso suporte e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

### Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já notou), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

## Ambientes

Possuímos dois ambientes para os nossos clientes. As URLs base das APIs são:

* Produção - `https://api.caas.qitech.app/account_event/`
* Sandbox - `https://api.sandbox.caas.qitech.app/account_event/`

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.
:::

No ambiente de Sandbox, as análises enviadas não são cobradas e são respondidas conforme a regra configurada para o evento.

## Somente HTTPS

Por questão de segurança, toda a comunicação com as APIs da QI Tech deve ser realizada utilizando a comunicação HTTPS. Para evitar que, por desatenção ou outro motivo, sejam feitas chamadas HTTP, este servidor somente disponibiliza a porta 443 com comunicação TLS 1.2. Chamadas realizadas utilizando outros protocolos serão automaticamente negadas.

---

# Pre PIX Transaction

URL: /documentation/caas/account_event/pre_pix_transaction

No momento em que o pagador tiver a intenção de iniciar um pagamento, os dados da transação poderão ser avaliados previamente pelo nosso servidor. Deste modo, será possível realizar uma análise prévia do risco envolvido na transação, baseado naquele conjunto de dados.

## Definição do Objeto de Pre Pix Transactions

Request Body

```json
{
    "id": "082373263",
    "transaction_direction": "received",
    "client": {
        "id": "123456",
        "document_number": "056.966.649-03",
        "name": "Francisco Oliveira Benedetti",
        "type": "natural_person",
        "address": {
            "street": "Avenida 13",
            "number": "704",
            "neighbourhood": "Centro",
            "city": "Ituiutaba",
            "uf": "MG",
            "complement": "Apt 1101",
            "postal_code": "38300-140"
        },
        "phone": {
            "international_dial_code": "55",
            "area_code": "16",
            "number": "981610077",
            "type": "mobile"
        },
        "sales_channel": "inbound_sales",
        "segment": "Personalité"
    },
    "amount": 13725,
    "dict_key": {
        "key_type": "cpf",
        "key_value": "09991222669",
        "assignment_date": "2020-01-15T18:00:00-03:00"
    },
    "face_recognition_key": "ef39e206-13d5-48de-b368-6c3bbc6f0222",
    "source_account": {
        "participant": "17315359",
        "branch": "0000",
        "account_number": "10442",
        "account_digit": "6",
        "owner": {
            "type": "legal_person",
            "document_number": "07.487.735/0001-69",
            "name": "Gioconda Pizzaria e Rotisseria LTDA."
        },
        "account_type": "CACC",
        "opening_date": "2020-01-15T18:00:00-03:00"
    },
    "destination_account": {
        "participant": "60701190",
        "branch": "3675",
        "account_number": "10442",
        "account_digit": "6",
        "owner": {
            "type": "natural_person",
            "document_number": "056.966.649-03",
            "name": "Francisco Oliveira Benedetti"
        },
        "account_type": "SLRY",
        "opening_date": "2020-01-15T18:00:00-03:00"
    },
    "destination_statistics": {
        "person":{
            "settlements":{
                "d90":4,
                "m12":67,
                "m60":618
            },
            "application_frauds":{
                "d90":0,
                "m12":4,
                "m60":9
            },
            "mule_accounts":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "scammer_accounts":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "other_frauds":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "unknown_frauds":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "total_frauds_transaction_amount":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "distinct_fraud_reporters":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "open_reports":0,
            "open_reports_distinct_reporters":0,
            "rejected_reports":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "registered_accounts":0
        },
        "owner":{
            "settlements":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "application_frauds":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "mule_accounts":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "scammer_accounts":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "other_frauds":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "unknown_frauds":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "total_frauds_transaction_amount":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "distinct_fraud_reporters":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "open_reports":0,
            "open_reports_distinct_reporters":0,
            "registered_accounts":0
        },
        "key":{
            "settlements":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "application_frauds":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "mule_accounts":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "scammer_accounts":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "other_frauds":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "unknown_frauds":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "total_frauds_transaction_amount":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "distinct_fraud_reporters":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "open_reports":0,
            "open_reports_distinct_reporters":0,
            "rejected_reports":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "distinct_accounts":{
                "d90":0,
                "m12":0,
                "m60":0
            }
        }
    },
    "source": {
        "channel": "internet_banking",
        "platform": "android",
        "ip": "198.185.065.098",
        "session_id": "7839jdqd9a8wd9"
    },
    "event_date": "2019-12-11T11:37:15.12-03:00"
}
```

Uma transação deve ser enviada para a API antes de ser encaminhada para o sistema de processamento, a fim de realizar uma validação prévia de fraude.

O status da transação representa a decisão retornada pelo modelo sobre aquela transação. Os seguintes status são utilizados na flag **analysis_status**:

* `automatically_approved`
* `automatically_reproved`
* `automatically_challenged`
* `pending`

Abaixo estão listados os significados de cada uma das decisões, devolvidas na flag analysis_status:

status | descrição
:----: | ---------
automatically_approved      | Recomenda-se que esta transação seja aprovada.
automatically_reproved      | Recomenda-se que esta transação seja reprovada.
automatically_challenged    | Os algoritmos da QI Tech recomendam que esta transação seja desafiado.
pending                     | A transação está sendo processada.

nome | tipo | descrição
:----:  | :----:  | ---------
id | string | Identificador do pagamento no sistema do cliente. **É essencial que este número seja único para cada processo de pagamento** *(obrigatório)*
transaction_direction   | enumerador  | Tipo da transação cadastrada. Define se o cliente está recebendo ou enviando dinheiro. *(obrigatório)*
client                  | *client* | Objeto que representa os dados do cliente, seja ele o pagador ou o recebedor. *(obrigatório)*
amount                  | inteiro  | O valor do pagamento, em centavos- conforme descrição da seção "Padrões". *(obrigatório)*
pix_modality            | string   | Tipo de transação cadastrada. Indica se representa uma transferência, um troco ou um saque.
dict_key                | *dict_key*                | Objeto que representa os dados da chave de vínculo no DICT, utilizada pelo cliente na transação.
face_recognition_key    | string                    | Chave de reconhecimento facial, caso tenha sido feito reconhecimento facial pela nossa API de reconhecimento facial.
source_account          | *source_account* | Objeto que representa os dados da conta debitada. *(obrigatório)*
destination_account     | *destination_account* | Objeto que representa os dados da conta creditada. *(obrigatório)*
destination_statistics  | *destination_statistics*  | Objeto que representa o histórico de transações e fraudes da conta creditada provenientes da API de DICT do BACEN.
source                  | *source* | Objeto do tipo Source que descreve as informações provenientes da aplicação utilizada para envio do pagamento
event_date              | datetime | A data e hora de início da transação, com fuso horário. *(obrigatório)*

Existem os seguintes enumeradores para *transaction_direction*: `sent` e `received`.

Existem os seguintes enumeradores para *pix_modality*: `transacation`, `change` e `withdraw`.

## Enviar uma Pré Transação

Request Body

```json
  {
    "id": "12345",
    ...
  }
```

Response Body

```json
  {
    "id": "12345",
    "analysis_status": "automatically_approved",
    "reason": "rule_decision_enum",
    "reason_desciption": "Descrição da regra"
  }
```

Para realizar a avaliação de uma pre transação, basta enviar um objeto do tipo Transaction ao seguinte endpoint:

`POST https://api.caas.qitech.app/account_event/event_type/pre_pix_transaction`

## Fluxo de Desafio

É possível, após a execução da análise, ter como decisão desafiar o usuário para realizar uma nova ação em sua plataforma. Esse fluxo pode ser utilizado para, por exemplo, solicitar um 2FA, como uma análise facial, para o usuário.

## Passo-a-passo da execução do fluxo

**1.** O Evento é submetido para análise, e retornará o status *automatically_challenged*.

Request Body

```json
{
    "id": "082373263",
    ...
    "event_date": "2019-12-11T11:37:15.12-03:00"
}
```

Response Body

```json
{
  "id": "082373263",
  "analysis_status": "automatically_challenge"
  ...
}
```

**2.** Após a primeira requisição de análise ter retornado um *analysis_status* de desafio, uma nova requisição pode ser enviada com o resultado do processo do cliente caso o mesmo tenha sido finalizado. Esta requisição deve ser feita no mesmo *event_id* da requisição anterior e o status atual deve ser obrigatoriamente *automatically_challenged*. Os possíveis status para essa atualização são:

* `approved_by_client`
* `reproved_by_client`

`PATCH https://api.caas.qitech.app/account_event/event_type/pre_pix_transaction/{event_id}`

Request Body: Envio com informações adicionais

```json
{
    "analysis_status": "approved_by_client"
}
````

Response Body

```json
{
  "id": "082373263",
  "analysis_status": "approved_by_client"
  ...
}
```

Atente-se para utilizar o mesmo event_id utilizado na sua primeira análise.

---

# Recuperar um Evento de Conta

URL: /documentation/caas/account_event/query_registration

A fim de recuperar um evento de conta específico, basta realizar uma requisição GET. O resultado retornado é o JSON mais atualizado do evento em questão. Caso este identificador não esteja relacionado a nenhum objeto, o HTTP Status 404 é retornado.

## Possiveis eventos:
- device_validation
- pre_pix_transaction

`GET https://api.caas.qitech.app/event_type/{event_name}/event/{event_id}`

```shell
curl "https://api.caas.qitech.app/event_type/device_validation/event/12345678"
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

---

# Padrões

URL: /documentation/caas/account_event/standards

Para facilitar a integração e garantir a integridade da informação, foram definidos alguns padrões seguidos em toda a API.

## Valores Monetários
> Exemplos:

```
10000
12345
98741
1223
1
0
```

As APIs assumem que todos os valores monetários enviados são em reais brasileiros. Os valores devem ser enviados como inteiro em centavos.

## Data e Hora com Fuso Horário
> Alguns exemplos:

```
2019-10-15T22:35:12.232-03:00
2018-05-01T13:32:11.297+00:00
2019-05-01T00:00:00.000+00:00
```

É representada conforme a ISO 8601. Neste caso, o fuso-horário é colocado logo após o horário e deve representar o fuso do local onde aquele dado será valido.

A máscara utilizada para validação é a seguinte:

`YYYY-MM-ddThh:mm:ss.sss±hh:mm`

## Data e Hora sem Fuso Horario
> Alguns exemplos:

```
2019-10-15T22:35:12
2018-05-01T13:32:11
2019-05-01T00:00:00
```

É representada conforme a ISO 8601. Dados que independem de fuso-horário deverão ser enviados sem ele, sempre em UTC, com a letra Z indicando que este dado está em UTC. O seguinte formato, portanto, será validado:

`YYYY-MM-ddThh:mm:ss.sssZ`

## Data
> Alguns exemplos

```
2019-10-15
2019-01-01
2017-03-20
```

No caso de campos que recebem somente a data, sem nenhum horário. Deve ser enviada com o seguinte formato:

`YYYY-MM-dd`

## Documentos
Uma vez que os números de documento são bastante variados e muitos deles possuem caracteres que não se enquadram como numéricos, definem-se todos os números de documento como string. Outro bom motivo para defini-los como string é evitar que os zeros à esquerda desapareçam. Documentos previstos nesta página possuem uma máscara bem definida e estarão sujeitos à validação. O restante dos documentos, como RG, dada sua falta de padronização, não serão validados.

## CPF

> Exemplos de CPFs válidos contra a máscara definida:

```
123.456.789-12
321.987.543-23
111.283.333-00
```

> Exemplos de CPFs inválidos contra a máscara definida:

```
8.577.477-8
08.104.627/0001-23
123.456.789-1
23.456.789-01
```

O CPF é sempre definido como uma string e será validado contra a máscara:

`###.###.###-##`

## CNPJ

> Exemplos de CNPJs válidos contra a máscara definida:

```
08.104.627/0001-02
01.079.210/0114-67
32.402.502/0001-35
```

> Exemplos de CNPJs inválidos contra a máscara definida:

```
8.577.477-8
123.456.789-12
321.987.543-23
32.402.502/0001-3
032.402.502/0001-3
```

O CNPJ é sempre definido como uma string e será validado contra a máscara:

`##.###.###/####-##`

## IP

> Exemplos de IPs válidos contra a máscara definida:

```
201.81.161.86
201.081.161.86
201.81.161.086
201.81.0.1
```

> Exemplos de IPs inválidos:

```
201.81..86
358.81.161.86
201.81.161
```

IPs deverão ser enviados sempre em IPv4, zeros à esquerda poderão ou não ser enviados, respeitando a seguinte máscara:

`###.###.###.###`

---

# Dinâmica dos Status

URL: /documentation/caas/account_event/status_dynamics

O processo de análise consiste em enviar um evento, como de Device Validation, por exemplo, no endpoint adequado e esperar a resposta.

Após a QI Tech realizar a análise do evento, ela retornará uma resposta com um status referente à análise. O campo **analysis_status** representa o resultado da análise de evento realizada pela QI Tech.

### **analysis_status**

Conforme descrito anteriormente, a QI Tech possui oito **analysis_status** que indicam o status da decisão do motor de eventos de conta e possui uma máquina de estados bastante simples:

analysis_status | Descrição
:---------: | ---------
automatically_approved | Os algoritmos da QI Tech recomendam que este evento seja aprovado.
automatically_reproved | Os algoritmos da QI Tech recomendam que este evento seja reprovado.
automatically_challenge | Os algoritmos da QI Tech recomendam que o usuário tome uma ação para adquirir mais informações para a análise.
in_manual_analysis | Os algoritmos da QI Tech enviaram este evento para a análise manual.
manually_approved | Após análise manual, o analista decidiu aprovar o evento.
manually_reproved | Após análise manual, o analista decidiu reprovar o evento.
in_queue | O evento está sendo realizado de forma assíncrona. O resultado do evento será respondido via Webhook.
pending | As consultas estão demorando mais do que o esperado, este evento entrou em uma fila de análise automática e será respondido por meio de Webhook.
not_analysed | O evento foi enviado com a flag de análise falsa, o que significa que nossos sistemas não retornarão uma recomendação.

---

# Criação de Conta

URL: /documentation/caas/account_monitoring/account_registration

O Produto de Monitoramento de Conta é dividido entre Conta Pessoa Física e Conta Pessoa Jurídica, onde uma Conta Pessoa Física pode possuir apenas pessoas físicas, enquanto a Conta Pessoa Júridica pode possuir tanto pessoas jurídicas quanto físicas. Para realizar a criação de uma conta basta enviar um objeto do tipo _Account_ para um dos seguintes endpoints:

- Conta Pessoa Física

`POST https://api.caas.qitech.app/account_monitoring/natural_person_account`

> Exemplo

```json
{
    "account_id": "5ce7fab5-8165-44a5-9b89-bb2d6d61e4f4",
    "registration_date": "2019-12-20T15:23:12"
}
```
- Conta Pessoa Jurídica

`POST https://api.caas.qitech.app/account_monitoring/legal_person_account`

> Exemplo

```json
{
    "account_id": "5ce7fab5-8165-44a5-9b89-bb2d6d61e4f4",
    "registration_date": "2019-12-20T15:23:12"
}
```

Todas as trocas de informação de um cadastro utilizam a seguinte definição para este objeto. Em alguns casos, para facilitar a implementação e diminuir o fluxo de dados entre as partes, algumas informações poderão ser omitidas.

nome | tipo | descrição
:----: | :----: | ---------
account_id | string | Identificador único da conta. **É essencial que este número seja único para cada requisição**
registration_date |	string (ISO 8601) | Data e hora do cadastro.

## Desativação e Reativação de Conta

Para realizar a desativação de contas dentro do produto de monitoramento de contas, deve-se realizar uma requisição no seguinte endpoint com o seguinte payload, passando o campo de new_account_status como 'deactivated':

- Conta Pessoa Física

`PATCH https://api.caas.qitech.app/account_monitoring/natural_person_account/{account_id}`

> Exemplo

```json
{
    "new_account_status" : "deactivated"
}
```
- Conta Pessoa Jurídica

`PATCH https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}`

> Exemplo

```json
{
    "new_account_status" : "deactivated"
}
```

Isso desativará a conta e interromperá seu monitoramento. Para reativar uma conta, e consequentemente retomar seu monitoramento, basta realizar uma requisição no seguinte endpoint com o seguinte payload, passando agora o new_account_status como 'active':

- Conta Pessoa Física

`PATCH https://api.caas.qitech.app/account_monitoring/natural_person_account/{account_id}`

> Exemplo

```json
{
    "new_account_status" : "active"
}
```
- Conta Pessoa Jurídica

`PATCH https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}`

> Exemplo

```json
{
    "new_account_status" : "active"
}
```

Ao se realizar a reativação de uma conta, os interavalos de monitoramento dos tópicos da conta serão reiniciados. Por exemplo, caso todos os tópicos sejam monitorados de 24 em 24 horas, no momento da reativação da conta, as atualizações serão realizadas 24 horas após a reativação.

---

# authentication

URL: /documentation/caas/account_monitoring/authentication

## Autenticação

> Para autenticar uma chamada, utilize o código seguinte:

```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE_API_KEY"
```

> Substitua a API key 'EXAMPLE_API_KEY' com a sua chave adquirida com o nosso suporte.

Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br .

Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:

`Authorization: EXAMPLE_API_KEY`

:::info **Atenção**

Você deve substituir EXAMPLE_API_KEY com a API Key recebida do suporte.
:::

---

# Status HTTP

URL: /documentation/caas/account_monitoring/http_status

Todas as APIs da QI Tech utilizam a seguinte padronização nos status HTTP de retorno, de acordo com o RFC 7231 :

Status HTTP | Significado | Descrição
---------- | ------- | ---------------------------------
400 | Bad Request | A requisição enviada possui algum erro de formatação. Na maioria dos casos, retornamos no corpo da mensagem uma explicação de onde está o erro.
401 | Unauthorized | Houve algum problema na autenticação, verifique se a API Key está correta e no header correto, de acordo com a seção Autenticação .
403 | Forbidden | O endpoint acessado é de uso interno e não está disponível para esta API Key.
404 | Not Found | O dado requisitado não foi encontrado usando a chave utilizada. Este status também é retornado quando um endpoint inválido é requisitado.
405 | Method Not Allowed | O método HTTP utilizado não se aplica ao endpoint utilizado.
406 | Not Acceptable | Os dados enviados no corpo da requisição são inválidos. Em geral, isso significa que os dados enviados não são um JSON válido.
409 | Conflict | O id da requisição corresponde a um id já processado anteriormente. Este status é retornado no caso de requisições duplicadas enviadas ao servidor.
500 | Internal Server Error | Tivemos um problema para processar esta requisição, ao encontrarmos esse erro nossos especialistas são automaticamente notificados e iniciam a análise e solução imediatamente.
503 | Service Unavailable | Você se deparou com uma indisponibilidade, planejada ou não, de infraestrutura dos nossos servidores.

---

# Introdução

URL: /documentation/caas/account_monitoring/introduction

Bem vindo à API de Monitoramento de Conta da QI Tech! Você pode utilizar a nossa API para monitorar contas e pessoas em cima de diversos tópicos de monitoramento, respeitando intervalos de monitoramento totalmente personalizáveis de acordo com as demandas e necessidades do cliente. Hoje o produto possúi os seguintes tópicos de monitoramento:

- Para Pessoas Físicas;
  - Lista OFAC - Lista de Sanções do Escritório de Controle de Ativos Estrangeiros (Office of Foreign Assets Control)
  - Lista UNSC - Lista de Sanções do Conselho de Segurança das Nações Unidas (United Nations Security Council)
  - Lista IBAMA - Lista de Penalidades Ambientais do Instituto Brasileiro do Meio Ambiente e dos Recursos Naturais Renováveis
  - Lista PEP - Lista de Pessoas Expostas Politicamente
  - Status Receita Federal - Situação Cadastral na Receita Federal do Brasil

- Para Pessoas Jurídicas;
  - Lista OFAC - Lista de Sanções do Escritório de Controle de Ativos Estrangeiros (Office of Foreign Assets Control)
  - Lista UNSC - Lista de Sanções do Conselho de Segurança das Nações Unidas (United Nations Security Council)
  - Lista IBAMA - Lista de Penalidades Ambientais do Instituto Brasileiro do Meio Ambiente e dos Recursos Naturais Renováveis
  - Lista CEIS - Cadastro de Empresas Inidôneas e Suspensas
  - Lista CNEP - Cadastro Nacional de Empresas Punidas
  - Status Receita Federal - Situação Cadastral na Receita Federal do Brasil

Lembrando que os intervalos são definidos por tópico de monitoramento e por tipo de pessoa monitorada, podendo por exemplo a Lista OFAC ser monitorada de 10 em 10 dias para Pessoas Físicas e de 30 em 30 dias para Pessoas Jurídicas

Os intervalo de monitoramento de cada tópico segue o padrão ISO 8601, podendo ser qualquer um dos intervalos abaixo apresentados, ou uma combinação dos mesmos:

### Dias, Semanas, Meses e Anos

| Notação  | Significado |
|----------|------------|
| `"P1D"`  | 1 dia      |
| `"P7D"`  | 7 dias     |
| `"P1W"`  | 1 semana   |
| `"P1M"`  | 1 mês      |
| `"P1Y"`  | 1 ano      |

---

### Horas, Minutos e Segundos

| Notação      | Significado                      |
|-------------|----------------------------------|
| `"PT1H"`    | 1 hora                           |
| `"PT30M"`   | 30 minutos                       |
| `"PT45S"`   | 45 segundos                      |
| `"PT2H30M"` | 2 horas e 30 minutos             |
| `"PT1H15M10S"` | 1 hora, 15 minutos e 10 segundos |

---

### Exemplos Personalizados

| Notação         | Significado                              |
|----------------|----------------------------------------|
| `"P1DT12H"`    | 1 dia e 12 horas                      |
| `"P2W3DT4H30M"` | 2 semanas, 3 dias, 4 horas e 30 minutos |

Abaixo, você pode observar a implementação da API utilizando curl. Com isso você possui exemplos para poder adaptar adequadamente à linguagem de programação da sua preferência.

## Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso suporte e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

### Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

## Ambientes

Possuímos dois ambientes para os nossos clientes. As URLs base das APIs são:

* Produção - `https://api.caas.qitech.app/account_monitoring/`
* Sandbox - `https://api.sandbox.caas.qitech.app/account_monitoring/`

No ambiente de Sandbox, as análises enviadas não são cobradas e são respondidas de acordo com regras pré estabelecidas.

## Somente HTTPS

Por questão de segurança, toda a comunicação com as APIs da QI Tech deve ser realizada utilizando a comunicação HTTPS. Para evitar que, por desatenção ou outro motivo, sejam feitas chamadas HTTP, este servidor somente disponibiliza a porta 443 com comunicação TLS 1.2. Chamadas realizadas utilizando outros protocolos serão automaticamente negadas.

## Autenticação

> Para autenticar uma chamada, utilize o código seguinte:

```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE_API_KEY"
```

> Substitua a API key 'EXAMPLE_API_KEY' com a sua chave adquirida com o nosso suporte.

Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br .

Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:

`Authorization: EXAMPLE_API_KEY`

:::info **Atenção**

Você deve substituir EXAMPLE_API_KEY com a API Key recebida do suporte.
:::

---

# Criação de Pessoas

URL: /documentation/caas/account_monitoring/person_registration

Para criar as pessoas de suas respectivas contas, deve-se manter a segregação entre endpoints de natural_person_account e legal_person_account.

Para solicitar a criação de uma para uma conta, basta enviar um objeto do tipo Person a um dos seguintes endpoints, respeitando a segregação feita no momento de criação de contas:

### Conta Pessoa Física

- Criação de Pessoa Física

`POST https://api.caas.qitech.app/account_monitoring/natural_person_account/{account_id}/natural_person`

> Exemplo

```json
{
    "id": "cc2f97ba-08c8-4a91-8d0d-49313a6c1245",
    "registration_date": "2024-11-04T13:37:00Z",
    "data": {
        "name": "John Doe",
        "document_number": "123.456.789-09",
        "birthdate": "2000-07-13"
    }
}
```
### Conta Pessoa Jurídica

- Criação de Pessoa Física

`POST https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}/natural_person`

> Exemplo

```json
{
    "id": "cc2f97ba-08c8-4a91-8d0d-49313a6c1245",
    "registration_date": "2024-11-04T13:37:00Z",
    "data": {
        "name": "John Doe",
        "document_number": "123.456.789-09",
        "birthdate": "2000-07-13"
    }
}
```
O campo birthdate é obrigatório apenas para as contas que possuam monitoramento de status na receita federal, sendo necessário para consulta de pessoas menores de 18 anos.

- Criação de Pessoa Jurídica

`POST https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}/legal_person`

> Exemplo

```json
{
    "id": "cc2f97ba-08c8-4a91-8d0d-49313a6c1245",
    "registration_date": "2024-11-04T13:37:00Z",
    "data": {
        "name": "Empresa das Tampas",
        "document_number": "12.482.243/0001-34"
    }
}
```

## Desativação e Reativação de Pessoas

Para desativar pessoas, a operação é análoga a realizada para contas, nos seguintes endpoints:

### Conta Pessoa Física

- Criação de Pessoa Física

`PATCH https://api.caas.qitech.app/account_monitoring/natural_person_account/{account_id}/natural_person`

> Exemplo

```json
{
    "new_person_status" : "deactivated"
}
```
### Conta Pessoa Jurídica

- Criação de Pessoa Física

`PATCH https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}/natural_person`

> Exemplo

```json
{
    "new_person_status" : "deactivated"
}
```

- Criação de Pessoa Jurídica

`PATCH https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}/legal_person`

> Exemplo

```json
{
    "new_person_status" : "deactivated"
}
```

Para reativar pessoas previamente desativadas, a operação é a mesma realizada para desativar pessoas, porém com o envio do new_person_status como 'active nos seguintes endpoints:

### Conta Pessoa Física

- Criação de Pessoa Física

`PATCH https://api.caas.qitech.app/account_monitoring/natural_person_account/{account_id}/natural_person`

> Exemplo

```json
{
    "new_person_status" : "active"
}
```
### Conta Pessoa Jurídica

- Criação de Pessoa Física

`PATCH https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}/natural_person`

> Exemplo

```json
{
    "new_person_status" : "active"
}
```

- Criação de Pessoa Jurídica

`PATCH https://api.caas.qitech.app/account_monitoring/legal_person_account/{account_id}/legal_person`

> Exemplo

```json
{
    "new_person_status" : "active"
}
```

---

# Padrões

URL: /documentation/caas/account_monitoring/standards

Para facilitar a integração e garantir a integridade da informação, foram definidos alguns padrões que são seguidos em toda a API.

## Data e Hora com Fuso Horário
> Alguns exemplos:

```
2019-10-15T22:35:12-03:00
2018-05-01T13:32:11+00:00
2019-05-01T00:00:00+00:00
```

É representada conforme a ISO 8601. Neste caso, o fuso-horário é colocado logo após o horário e deve representar o fuso do local onde aquele dado será valido. Por exemplo, se um aluguel estiver marcado para começar às 09:30 no aeroporto de Brasília, o horário enviado deverá ser representado por 09:30-03:00, se o aluguel estiver marcado para começar às 09:30 em Manaus, deverá ser representado por 09:30-04:00.

A máscara utilizada para validação é a seguinte:

`YYYY-MM-ddThh:mm:ss±hh:mm`

## Data e Hora sem Fuso Horario
> Alguns exemplos:

```
2019-10-15T22:35:12Z
2018-05-01T13:32:11Z
2019-05-01T00:00:00Z
```

É representada conforme a ISO 8601. Dados que independem de fuso-horário deverão ser enviados sem ele, sempre em UTC, com a letra Z indicando que este dado está em UTC. O seguinte formato, portanto, será validado:

`YYYY-MM-ddThh:mm:ssZ`

## Data
> Alguns exemplos

``` 
2019-10-15
2019-01-01
2017-03-20
```

No caso de campos que recebem somente data, uma data de nascimento, por exemplo, somente a data, sem nenhum horário deve ser enviada com o seguinte formato:

`YYYY-MM-dd`
 

## Documentos
Uma vez que os números de documento são bastante variados e muitos deles possuem caracteres que não se enquadram como numéricos, definem-se todos os números de documento como string. Outro bom motivo para definí-los como string é evitar que os zeros à esquerda desapareçam. Documentos previstos nesta página possuem uma máscara bem definida e estarão sujeitos a validação. O restante dos documentos, como RG, dada sua falta de padronização, não serão validados.

## CPF

> Exemplos de CPFs válidos contra a máscara definida:

```
123.456.789-12
321.987.543-23
111.283.333-00
```

> Exemplos de CPFs inválidos contra a máscara definida:

```
8.577.477-8
08.104.627/0001-23
123.456.789-1
23.456.789-01
```

O CPF é sempre definido como uma string e será validado conta a máscara:

`###.###.###-##`

## CNPJ

> Exemplos de CNPJs válidos contra a máscara definida:

```
08.104.627/0001-02
01.079.210/0114-67
32.402.502/0001-35
```

> Exemplos de CNPJs inválidos contra a máscara definida:

```
8.577.477-8
123.456.789-12
321.987.543-23
32.402.502/0001-3
032.402.502/0001-3
```

O CNPJ é sempre definido como uma string e será validado conta a máscara:

`##.###.###/####-##`

---

# Webhook

URL: /documentation/caas/account_monitoring/webhook

Webhook

Atualizações nos tópicos de monitoramento serão notificadas por meio do envio de webhooks. Para tanto, é necessário, por meio da equipe do [suporte](mailto:suporte.caas@qitech.com.br), configurar um endereço do endpoint por onde vamos notificar as atualizações e também uma *signature_key* que será utilizada para assinar a requisição. Vale ressaltar que todos os envios de webhook serão feitos para um único endpoint.

:::info **Atenção**

Por questões de segurança, todas as requisições de Webhook serão somente realizadas em endpoints servidos por HTTPS.
:::

## Assinatura do Webhook

## Webhook de Atualização de Evento

Request Body

```json
{
    "person_type" : "natural_person",
    "account_type" : "natural_person_account",
    "person_id" : "22f5d028-0ce7-46f7-9b63-e7e38171b485",
    "account_id" : "e49ac344-f941-4668-9afb-a52ce4e5754a",
    "monitoring_topic" : "OFAC",
    "event" : "entered"
}
```

Abaixo está o significado de cada campo:

| Nome             | Tipo              | Descrição                                                          
|:----------------:|:-----------------:|-------------------------------------------------------------------------
| person_type      | string            | Tipo de pessoa (natural_person ou legal_person).                        
| account_type     | string            | Tipo de conta (natural_person_account ou legal_person_account).         
| person_id        | strin             | Identificador único da pessoa, passado na requisição de criação.       
| account_id       | string            | Identificador único da conta, passado na requisição de criação.        
| monitoring_topic | string            | Tópico monitorado em que ocorreu a mudança.                            
| event            | string            | Tipo de evento ocorrido, como "entered" (entrada) ou "exited" (saída) para os tópicos de listas restritivas. 

A requisição de atualização do tópico de monitoramento possui o formato acima e notifica a mudança no status de um dos tópico de monitoramento dentro da conta. O método utilizado é um PUT e o endereço do endpoint pode conter também o id do evento, de acordo com a necessidade do cliente. É importante ressaltar que o corpo da requisição é enviado como texto codificado em UTF-8.

## Retentativas

A notificação é considerada realizada quando recebe como resposta um HTTP Status 200. Caso as notificações falhem, serão feitas 7 retentativas, com os seguintes intervalos, até que um 200 seja retornado ou as tentativas terminem:

* 10 segundos
* 40 segundos
* 160 segundos
* 640 segundos
* 2560 segundos
* 10240 segundos
* 40960 segundos

---

# Criação de Sessão

URL: /documentation/caas/auth_session_manager/auth_session

O objeto de sessão de autenticação é uma entidade que representa o fluxo de autenticação do usuário. Através desse elemento, você poderá gerenciar o processo de coleta das informações de cadastro.

## Definição do Objeto Sessão de Autenticação

Request Body

```json
{
  "id": "12345678",
  "document_number": "111.111.111-11",
  "settings": {
    "steps": [
      {
        "step": "device_scan"
      },
      {
        "step":"face_recognition",
      },
      {
        "step":"personal_document",
        "show_success_screen": true,
        "show_introduction_screen": true,
        "document_templates":[
            "rg",
            "cnh",
            "cnh_digital"
        ]
      }
    ],
    "session_expiration_time_in_minutes": 120,
    "token_expiration_seconds": 3600,
    "open_mode": "iframe"
  }
}
```

Todas as trocas de informação de uma sessão utilizam a seguinte definição para este objeto

nome | tipo | descrição
:----: | :----: | ---------
id | string | Identificador da sessão. **É essencial que este número seja único para cada sessão** *(obrigatório)*
document_number | string | CPF do indivíduo sendo cadastrado, com pontos e hífens, de acordo com a padronização. *(obrigatório)*
settings | objeto | Objeto com as configurações personalizadas da sessão de autenticação. Caso não seja enviada, será utilizada a configuração padrão da empresa.

## Objeto settings

O objeto settings contém o campo `steps` que contempla a sequência das etapas de autenticação e suas respectivas configurações:
Os possíveis steps aceitos são:

* device_scan
* face_recognition
* personal_document

Além disso são aceitos os seguintes campos:

nome | tipo | descrição
:----: | :----: | ---------
session_expiration_time_in_minutes | integer | Data de expiração da sessão. Após essa data, a sessão não será válida.
token_expiration_seconds | interger | Tempos de expiração do token de sessão em segundos. (deve esstar entre 1 e 172800, máximo de 48 horas. O valor padrão é 1800)
open_mode | string | Define o modo de abertura da sessão, para a mensagem e botões do fuxo de finalização. (deve ser: "iframe" ou "link").

### device_scan

O step de device_scan indica a execução da coleta das informações do dispositivo. **Não possui configurações adicionais**

### face_recognition

O step de face_recognition indica a execução da coleta do fluxo de prova de vida através da biometria facial. **Não possui configurações adicionais**

### personal_document

O step de personal_document indica a execução da coleta do fluxo de OCR para leitura de documentos.

nome | tipo | descrição
:----: | :----: | ---------
document_templates | array | Lista de documentos que podem ser coletados no fluxo de cadastro. *(obrigatório)*
show_success_screen | boolean | Define a existência da tela de sucesso no fluxo de captura de documentos. Valor padrão `true`.
show_introduction_screen | boolean | Define a existência da tela de introdução no fluxo de captura de documentos. Valor padrão `true`.

Possíveis `document_templates` aceitos:

Nome | Tipo | Descrição
---- | ---- | ---------
cnh | string | Captura de CNH física FRENTE e VERSO (**fechada**), em duas etapas
rg | string | Captura de RG físico FRENTE e VERSO (**fechado**), em duas etapas
cnh_digital | string | Envio de CNH **digital** (pdf)
passport | string | Envio de Passapore FRENTE e VERSO (**fechada**), em duas etapas.
rne | string | Envio de Registro Nacional de Estrangeiros FRENTE e VERSO (**fechada**), em duas etapas.
crnm | string | Envio de Carteira de Registro Nacional Migratório FRENTE e VERSO (**fechada**), em duas etapas.
ctps | string | Envio de Carteira de Trabalho e Previdência Social FRENTE e VERSO (**fechada**), em duas etapas.
others | string | Envio de qualquer documento **isento de validação** FRENTE e VERSO (**fechada**), em duas etapas.

## Enviar um Auth Session

Request Body

```json
  {
    "id": "12345",
    ...
  }
```

Response Body

```json
  {
    "id": "12345678",
    "status": "pending",
    "expiration_date": "2025-12-11T11:37:15.12-03:00",
    "settings": {
      ...
    },
    "auth_session_hash": "1cFL1vM",
    "step": "device_scan",
    "auth_session_url": "https://auth-session.production.caas.qitech.app/s/1cFL1vM/t/fc0bae39-1c41-4bc2-a5a1-39a7ca01121b",
    "token": "fc0bae39-1c41-4bc2-a5a1-39a7ca01121b",
    "token_expiration_date": "2025-12-10T11:37:15.12-03:00",
  }
```

Para realizar a criação de uma sessão, basta enviar um objeto do tipo Auth Session ao seguinte endpoint:

`POST https://api.caas.qitech.app/auth_session_manager/auth_session`

---

# Autenticação

URL: /documentation/caas/auth_session_manager/authentication

> Para autenticar uma chamada, utilize o código seguinte:

```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

> Substitua a API Key 'EXAMPLE-OF-API-KEY' pela sua chave, que deve ser obtida através do nosso time de suporte.

Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br .

Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:

`Authorization: EXAMPLE-OF-API-KEY`

:::info **Atenção**

Você deve substituir EXAMPLE-OF-API-KEY pela sua chave, que deve ser obtida através do nosso time de suporte.
:::

---

# Status HTTP

URL: /documentation/caas/auth_session_manager/http_status

Todas as APIs da QI Tech utilizam a seguinte padronização nos status HTTP de retorno, de acordo com o RFC 7231 :

Status HTTP | Significado | Descrição
---------- | ------- | ---------------------------------
400 | Bad Request | A requisição enviada possui algum erro de formatação. Na maioria dos casos, retornamos no corpo da mensagem uma explicação de onde está o erro.
401 | Unauthorized | Houve algum problema na autenticação, verifique se a API Key está correta e no header correto, de acordo com a seção Autenticação .
403 | Forbidden | O endpoint acessado é de uso interno e não está disponível para esta API Key.
404 | Not Found | O dado requisitado não foi encontrado usando a chave utilizada. Este status também é retornado quando um endpoint inválido é requisitado.
405 | Method Not Allowed | O método HTTP utilizado não se aplica ao endpoint utilizado.
406 | Not Acceptable | Os dados enviados no corpo da requisição são inválidos. Em geral, isso significa que os dados enviados não são um JSON válido.
409 | Conflict | O id da requisição corresponde a um id já processado anteriormente. Este status é retornado no caso de requisições duplicadas enviadas ao servidor.
500 | Internal Server Error | Tivemos um problema para processar esta requisição, ao encontrarmos esse erro nossos especialistas são automaticamente notificados e iniciam a análise e solução imediatamente.
503 | Service Unavailable | Você se deparou com uma indisponibilidade, planejada ou não, de infraestrutura dos nossos servidores.

---

# Introdução

URL: /documentation/caas/auth_session_manager/introduction

Bem vindo à API de Gerenciamento de Sessões de Autenticação da QI Tech! Esta api foi projetada para controlar o fluxo completo de KYC do usuário!

Este serviço organiza o processo de autenticação. Possibilitando a criação de sessões de cadastro KYC com fluxos personalizados e uso dos demais serviços de autenticação da QI Tech:

* Device Scan
* Face Recognition
* OCR

Desse modo, é possível iniciar o fluxo de coleta das informações de cadastro através do link retornado pela API.
Assim que iniciada, a página web será responsável por guiar o usuário a executar as etapas de KYC definidas naquela sessão. 

Além disso, por estar diretamente integrada com os demais serviços descritos acima, ela é capaz de coletar as informações necessárias para a finalização do fluxo de autenticação. Com essas informações, será possível efetuar a análise desejada nos demais serviços da QI Tech, como o cadastro de pessoa física ou uma análise pré transacional, por exemplo.

## Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso suporte e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

### Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já notou), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

## Ambientes

Possuímos dois ambientes para os nossos clientes. As URLs base das APIs são:

* Produção - `https://api.caas.qitech.app/auth_session_manager/`
* Sandbox - `https://api.sandbox.caas.qitech.app/auth_session_manager/`

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.  
:::

No ambiente de Sandbox, as análises enviadas não são cobradas e são respondidas de acordo com a regra configurada para o evento.

## Somente HTTPS

Por questão de segurança, toda a comunicação com as APIs da QI Tech deve ser realizada utilizando a comunicação HTTPS. Para evitar que, por desatenção ou outro motivo, sejam feitas chamadas HTTP, este servidor somente disponibiliza a porta 443 com comunicação TLS 1.2. Chamadas realizadas utilizando outros protocolos serão automaticamente negadas.

---

# Gestão de Sessão

URL: /documentation/caas/auth_session_manager/retrieve_session

Ao criar uma sessão de autenticação, basta utilizar o link gerado para iniciar o fluxo de cadastro do usuário. Isso pode ser feito através do envio do link ou do uso dele diretamente em seu website, com ferramentas como `iframe`.

## Objeto de retorno

O objeto de retorno da criação e resgate de uma `auth_session` contém as seguintes informações:

Response Body

```json
  {
    "id": "12345678",
    "status": "pending",
    "expiration_date": "2025-12-11T11:37:15.12-03:00",
    "step_data": {
      "face_recognition": {
        "image_key": "65441d8d-015a-4a0f-97b6-b7d4fc5619b7",
        "event_date": "2025-12-11T11:37:15.12-03:00"
      },
      "personal_document": {
          "document_template": "rg",
          "ocr_keys": [
            "e13c71d0-ae0e-48e2-8c42-26f997412039",
            "3991b716-0980-409f-8e33-e3a8dd9a671c"
          ],
          "event_date": "2025-12-11T11:37:15.12-03:00"
      },
      "device_scan": {
          "session_id":  "4d450227-c77c-4487-830b-42dcd127798a",
          "event_date": "2025-12-11T11:37:15.12-03:00"
      }
    }
    "settings": {
      ...
    },
    "auth_session_hash": "1cFL1vM",
    "step": "device_scan",
    "auth_session_url": "https://auth-session.production.caas.qitech.app/s/1cFL1vM/t/fc0bae39-1c41-4bc2-a5a1-39a7ca01121b",
    "token": "fc0aaa39-1c21-1bc1-a5a1-39a7ca01121b",
    "token_expiration_date": "2025-12-10T11:37:15.12-03:00",
  }
```

Esse objeto é retornado no enpoint de resgate da sessão:

`GET https://api.caas.qitech.app/auth_session_manager/auth_session/{id}`

Descrição do campos de resposta:

nome | tipo | descrição
:----: | :----: | ---------
id | string | Id da sessão.
status | string | Status da sessão.
expiration_date | date | Data de expiração da sessão. Após essa data, a sessão é invalidada.
step_data | object | Objeto de retorno dos eventos da sessão.
settings | object | Objeto de configuração da sessão.
auth_session_hash | string | Hash de identificação da sessão.
step | string | Etapa atual do usuário.
auth_session_url | string | Url capaz de coletar as informações do cadastro.
token | string | Token de autenticação da sessão.
token_expiration_date | date | Data de expiração do token temporário de autenticação. Padrão definido para 2 horas após a geração da sessão.

### Status

Possíveis status:

* pending
* completed
* expired

### Objeto step_data

Objeto que contém os dados coletados de cada step.

:::info Informação
Caso o step não esteja listado nas settings da sessão, o mesmo não estará presente como campo do objeto `step_data`
:::

`face_recognition`

Nome | Tipo | Descrição
---- | ---- | ---------
image_key | string | Chave de identificação da etapa de face_recognition.
event_date | date | Data de finalização da etapa.

`personal_document`

Nome | Tipo | Descrição
---- | ---- | ---------
document_template | string | Template selecionado pelo usuário no momento da coleta do documento.
ocr_keys | list | Lista com as chaves de identificação de cada documento coletado.
event_date | date | Data de finalização da etapa.

`device_scan`

Nome | Tipo | Descrição
---- | ---- | ---------
session_id | string | Chave de identificação da etapa de scan do dispositivo.
event_date | date | Data de finalização da etapa.

## Autenticação do fluxo web

Para garantir mais segurança para a aplicação, retornamos um token temporário para a página web.
É possível resgatar o token, ou gerar um novo através do endpoint:

`POST https://api.caas.qitech.app/auth_session_manager/auth_session/{id}/token`

Request Body

```json
  {
    "token_expiration_seconds": 3600
  }
```

O objeto de token tem somente um campo opcional:

Nome | Tipo | Descrição
---- | ---- | ---------
token_expiration_seconds | interger | Tempos de expiração do token de sessão em segundos. (deve esstar entre 1 e 172800, máximo de 48 horas. O valor padrão é 1800)

Response Body

```json
  {
    "id": "12345678",
    "token": "e7e99a40-0b26-4bb9-a068-9fa4886eeef3",
    "token_expiration_date": "2025-12-10T13:37:15.12-03:00",
  }
```

Assim, caso o token tenha expirado, é possível seguir com a sessão de autenticação gerando um novo token.

# Webhook

A finalização da sessão será notificada por meio do envio de webhook. Para tanto, é necessário, por meio da equipe do [suporte](mailto:suporte.caas@qitech.com.br), configurar um endereço do endpoint por onde vamos notificar as atualizações e também uma *signature_key* que será utilizada para assinar a requisição. Vale ressaltar que todos os envios de webhook serão feitos para um único endpoint.

:::info **Atenção**

Por questões de segurança, todas as requisições de Webhook serão somente realizadas em endpoints servidos por HTTPS.
:::

## Comunicação com a página web

A página web poderá ser integrada através de uma ferramenta chamada `iframe`. Da seguinte maneira:

```html
<iframe id="iframe" src="" href="{auth_session_url}" allow="camera; microphone" referrerPolicy="no-referrer"></iframe>
```

> ⚠️ **Configuração Obrigatória**
>
> Para que o iframe funcione corretamente em **produção** (`auth-session.caas.qitech.app`) e **sandbox** (`auth-session.sandbox.caas.qitech.app`), é necessário configurar o seguinte header de Permissions-Policy:
>
> **Configuração com URLs específicas (recomendado):**
> ```json
> {
>   "key": "Permissions-Policy",
>   "value": "geolocation=(self \"https://auth-session.caas.qitech.app\" \"https://auth-session.sandbox.caas.qitech.app\"), microphone=(self \"https://auth-session.caas.qitech.app\" \"https://auth-session.sandbox.caas.qitech.app\"), camera=(self \"https://auth-session.caas.qitech.app\" \"https://auth-session.sandbox.caas.qitech.app\"), fullscreen=(self \"https://auth-session.caas.qitech.app\" \"https://auth-session.sandbox.caas.qitech.app\")"
> }
> ```
>
> **Configuração alternativa (menos restritiva):**
> ```json
> {
>   "key": "Permissions-Policy",
>   "value": "geolocation=*, microphone=*, camera=*, fullscreen=()"
> }
> ```
>
> Essa configuração deve ser aplicada no servidor que hospeda a página que contém o iframe para garantir que as permissões necessárias sejam concedidas.

Caso o link seja chamado dessa maneira, a página web irá enviar mensagens de retorno para a página que a requisitou. As possíveis mensagens de retorno são:

* success
* canceled
* invalid_token
* expired

Que podem ser acessadas da seeguinte maneira:

```javascript
window.addEventListener("message", (event) => {
            if (event.data === "canceled") {
              //close iframe
            }
            if (event.data === "invalid_token") {
              //close iframe
            }
            if (event.data === "success") {
              //close iframe
            }  
            if (event.data === "expired") {
              //close iframe
            }
        });
```

## Finalização do fluxo

Este serviço irá gerenciar o fluxo de coleta de dados de autenticação, que poderão ser utilizados nos demais serviços. 
Para mais informações de como utilizar as chaves retornadas nos demais produtos, segue o exemplo da análise cadastral de pessoa física [Análise Cadastral](/documentation/caas/onboarding/query_registration)

---

# authentication

URL: /documentation/caas/banking/authentication

## Autenticação

> Para autenticar uma chamada, utilize o código seguinte:

```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE_API_KEY"
```

> Substitua a API key 'EXAMPLE_API_KEY' com a sua chave adquirida com o nosso suporte.

Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br .

Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:

`Authorization: EXAMPLE_API_KEY`

:::info **Atenção**

Você deve substituir EXAMPLE_API_KEY com a API Key recebida do suporte.
:::

---

# Boleto

URL: /documentation/caas/banking/bankslips

No momento em que um usuário efetuar ou receber um pagamento por boleto, os dados do pagamento deverão ser enviados para a QI Tech. Deste modo, será possível realizar uma análise do risco envolvido na operação, baseado naquele conjunto de dados.

## Definição do Objeto de Boleto

Request Body

```json
{
    "id": "082373263",
    "bankslip_direction": "received",
    "document_amount": 13725,
    "discount_amount": 1000,
    "other_deduction_amount": 0,
    "interest_amount": 254,
    "amount": 12979,
    "bankslip_payment_date": "2020-10-07T15:06:25-03:00",
    "bankslip_due_date": "2020-10-07",
    "bankslip_issuing_date": "2020-10-07",
    "description": "BOLETO PARA PAGAMENTO DA MENSALIDADE DE SETEMBRO",
    "face_recognition_key": "ef39e206-13d5-48de-b368-6c3bbc6f0222",
    "validation_key": "69a59de3-0198-4a26-933a-c1de624c147d",
    "payer": {
        "id": "182373263",
        "type": "legal_person",
        "document_number": "07.487.735/0001-69",
        "name": "Gioconda Pizzaria e Rotisseria LTDA.",
        "address": {
            "street": "Avenida 13",
            "number": "704",
            "neighbourhood": "Centro",
            "city": "Ituiutaba",
            "uf": "MG",
            "complement": "Apt 1101",
            "postal_code": "38300-140"
        },
        "phone": {
            "international_dial_code": "55",
            "area_code": "16",
            "number": "981610077",
            "type": "mobile"
        },
        "email": "mailto@qitech.com.br",
        "account": {
            "participant": "60701190",
            "branch": "3675",
            "account_number": "13212",
            "account_digit": "5",
            "account_type": "CACC"
        },
        "sales_channel": "inbound_sales",
        "segment": "Personalité"
    },
    "recipient": {
        "id": "282373263",
        "type": "legal_person",
        "document_number": "056.966.649-03",
        "name": "Francisco Oliveira Benedetti",
        "address": {
            "street": "Avenida 13",
            "number": "704",
            "neighbourhood": "Centro",
            "city": "Ituiutaba",
            "uf": "MG",
            "complement": "Apt 1101",
            "postal_code": "38300-140"
        },
        "phone": {
            "international_dial_code": "55",
            "area_code": "16",
            "number": "981610077",
            "type": "mobile"
        },
        "account": {
            "participant": "60701190",
            "branch": "3675",
            "account_number": "10552",
            "account_digit": "6",
            "account_type": "CACC"
        }
    },
    "final_recipient": {
        "id": "382373263",
        "type": "legal_person",
        "document_number": "056.966.649-03",
        "name": "Francisco Oliveira Benedetti",
        "address": {
            "street": "Avenida 13",
            "number": "704",
            "neighbourhood": "Centro",
            "city": "Ituiutaba",
            "uf": "MG",
            "complement": "Apt 1101",
            "postal_code": "38300-140"
        },
        "phone": {
            "international_dial_code": "55",
            "area_code": "16",
            "number": "981610077",
            "type": "mobile"
        },
        "account": {
            "participant": "60701190",
            "branch": "3675",
            "account_number": "10442",
            "account_digit": "6",
            "account_type": "CACC"
        }
    },
    "source": {
        "channel": "internet_banking",
        "platform": "android",
        "ip": "198.185.056.098",
        "session_id": "7839jdqd9a8wd9"
    }
}
```

Um pagamento de boleto deve ser enviado para a API antes de ser encaminhada para o sistema de processamento, a fim de realizar uma validação prévia de fraude.

O status do pagamento representa a decisão retornada pelo modelo sobre aquele boleto. Os seguintes status são utilizados na flag **analysis_status**:

* `automatically_approved`
* `automatically_reproved`
* `in_manual_analysis`
* `pending`

Abaixo estão listados os significados de cada uma das decisões, devolvida na flag analysis_status:

status | descrição
:----: | ---------
automatically_approved      | Recomenda-se que este pagamento de boleto seja aprovado.
automatically_reproved      | Recomenda-se que este pagamento de boleto seja reprovado.
in_manual_analysis          | Recomenda-se que este pagamento de boleto seja analisado manualmente.
pending                     | O pagamento de boleto está sendo processado.

nome | tipo | descrição
:----:  | :----:  | ---------
id | string | Identificador da transação no sistema do cliente. **É essencial que este número seja único para cada pagamento de boleto**
bankslip_direction        | enumerador                | Modalidade do pagamento do boleto. Define se o cliente está pagando o boleto ou recebendo o pagamento do boleto.
document_amount         | inteiro                   | Valor do documento em centavos - conforme descrição da seção "Padrões".
discount_amount          | inteiro                   | Valor do desconto ou abatimento aplicado sobre o valor do documento em centavos - conforme descrição da seção "Padrões".
other_deduction_amount  | inteiro                   | Valor das outras deduções aplicadas sobre o valor do documento em centavos - conforme descrição da seção "Padrões".
interest_amount         | inteiro                   | Valor da multa, mora ou juros aplicados sobre o valor do documento em centavos - conforme descrição da seção "Padrões".
amount                  | inteiro                   | Valor final pago no boleto - conforme descrição da seção "Padrões".
bankslip_payment_date     | datetime                  | A data e hora do pagamento do boleto, com fuso horário.
bankslip_due_date         | date                      | Data de vencimento do boleto de acordo com a padronização
description             | string                    | Campo descrição ou observações do boleto.
face_recognition_key    | string                    | Chave de reconhecimento facial, caso tenha sido feito reconhecimento facial pela nossa API de reconhecimento facial.
validation_key          | string                    | Chave de validação, caso tenha sido feita algum teste de validação do cliente em nossa API de validações.
payer                   | *bankslip_payer*            | Objeto que representa a pessoa física ou pessoa jurídica que pagou o boleto.
recipient               | *bankslip_recipient*        | Objeto que representa a pessoa física ou pessoa jurídica beneficiária do boleto.
final_recipient         | *bankslip_recipient*        | Objeto que representa a pessoa física ou pessoa jurídica beneficiária final do boleto.
source                  | *source*                  | Objeto do tipo Source que descreve as informações provenientes da aplicação utilizada para o pagamento do boleto.

Existem os seguintes enumeradores para *bankslip_direction*: `payed` e `received`.

## Enviar um Pagamento de Boleto

Request Body

```json
  {
    "id": "12345",
    ...
  }
```

Response Body

```json
  {
    "bankslip_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf",
    "status": "automatically_approved",
    "reason": "rule_decision_enum"
  }
```

Para realizar a avaliação de um pagamento de boleto, basta enviar um objeto do tipo Boleto ao seguinte endpoint:

`POST https://api.caas.qitech.app/bankslip/bankslip`

## Recuperar um Pagamento de Boleto

Response Body

```json
  {
    "id": "082373263",
    "bankslip_direction": "received",
    ...
  }
```

Para recuperar os dados de um pagamento de boleto, basta enviar uma requisição ao seguinte endpoint:

`GET https://api.caas.qitech.app/bankslip/bankslip/{bankslip_id}`

Onde *bankslip_id* é o identificador da transação no sistema do cliente utilizado no envio do boleto.

## Atualizar um pagamento de boleto

Request Body

```json
  {
    "bankslip_status": "completed",
    "event_date": "2020-10-07T15:06:25-03:00"
  }
```

Response Body

```json
  {
    "bankslip_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf",
    "bankslip_status": "completed"
  }
```

Após um pagamento de boleto ser criado e analisado, ela será enviado à câmara de compensação para ser processado. Deste modo, é necessário que seja informada a atualizações de status do pagamento quando este for enviado, através do endpoint:

`PUT https://api.caas.qitech.app/bankslip/bankslip/{bankslip_id}`

Deste modo, garante-se que nossa base de dados seja atualizada e sejamos capazes de identificar os pagamentos de boleto que estejam realmente sucetíveis a fraude.

---

# Pagamento de Contas

URL: /documentation/caas/banking/bill_payments

No momento em que um usuário efetuar um pagamento de contas, os dados do pagamento deverão ser enviados para a QI Tech. Deste modo, será possível realizar uma análise do risco envolvido na operação, baseado naquele conjunto de dados.

## Definição do Objeto de Pagamento de Contas

Request Body

```json
{
    "id": "082373263",
    "amount": 12979,
    "bill_payment_date": "2020-10-07T15:06:25-03:00",
    "bill_due_date": "2020-10-07",
    "bill_issuing_date": "2020-10-07",
    "service_description": "CONTA DE ELETRICIDADE ENEL",
    "face_recognition_key": "ef39e206-13d5-48de-b368-6c3bbc6f0222",
    "validation_key": "69a59de3-0198-4a26-933a-c1de624c147d",
    "company": {
        "id": "451673263",
        "provided_service": "eletricity", 
        "name" : "Enel",
        "legal_name": "Eletropaulo Metropolitana Eletricidade de São Paulo S.A.",
        "document_number": "61.695.227/0001-93",
        "address": {
            "street": "Av. Dr. Marcos Penteado de Ulhôa Rodrigues",
            "number": "939",
            "neighbourhood": "Sítio Tamboré",
            "city": "Barueri",
            "uf": "SP",
            "complement": "Loja 1 e 2",
            "postal_code": "06460-040"
        }
    },
    "payer": {
        "id": "182373263",
        "type": "legal_person",
        "document_number": "07.487.735/0001-69",
        "name": "Gioconda Pizzaria e Rotisseria LTDA.",
        "email": "gioconda_pizza@bol.com.br",
        "address": {
            "street": "Avenida 13",
            "number": "704",
            "neighbourhood": "Centro",
            "city": "Ituiutaba",
            "uf": "MG",
            "complement": "Apt 1101",
            "postal_code": "38300-140"
        },
        "phone": {
            "international_dial_code": "55",
            "area_code": "16",
            "number": "981610077",
            "type": "mobile"
        },
        "account": {
            "participant": "60701190",
            "branch": "3675",
            "account_number": "13212",
            "account_digit": "5",
            "account_type": "CACC"
        },
        "sales_channel": "inbound_sales",
        "segment": "Personalité"
    },
    "source": {
        "channel": "internet_banking",
        "platform": "android",
        "ip": "198.185.105.098",
        "session_id": "7839jdqd9a8wd9"
    }
}
```

Um pagamento de conta deve ser enviado para a API antes de ser encaminhada para o sistema de processamento, a fim de realizar uma validação prévia de fraude.

O status do pagamento representa a decisão retornada pelo modelo sobre aquela conta. Os seguintes status são utilizados na flag **analysis_status**:

* `automatically_approved`
* `automatically_reproved`
* `in_manual_analysis`
* `pending`

Abaixo estão listados os significados de cada uma das decisões, devolvida na flag analysis_status:

status | descrição
:----: | ---------
automatically_approved      | Recomenda-se que este pagamento de conta seja aprovado.
automatically_reproved      | Recomenda-se que este pagamento de conta seja reprovado.
in_manual_analysis          | Recomenda-se que este pagamento de conta seja analisado manualmente.
pending                     | O pagamento de conta está sendo processado.

nome | tipo | descrição
:----:  | :----:  | ---------
id | string | Identificador da transação no sistema do cliente. **É essencial que este número seja único para cada pagamento de conta**
document_amount         | inteiro                   | Valor do documento em centavos - conforme descrição da seção "Padrões".
other_deduction_amount  | inteiro                   | Valor das outras deduções aplicadas sobre o valor do documento em centavos - conforme descrição da seção "Padrões".
interest_amount         | inteiro                   | Valor da multa, mora ou juros aplicados sobre o valor do documento em centavos - conforme descrição da seção "Padrões".
amount                  | inteiro                   | Valor final pago no conta - conforme descrição da seção "Padrões".
bill_payment_date     | datetime                  | A data e hora do pagamento do conta, com fuso horário.
bill_due_date         | date                      | Data de vencimento do conta de acordo com a padronização
description             | string                    | Campo descrição ou observações do conta.
face_recognition_key    | string                    | Chave de reconhecimento facial, caso tenha sido feito reconhecimento facial pela nossa API de reconhecimento facial.
validation_key          | string                    | Chave de validação, caso tenha sido feita algum teste de validação do cliente em nossa API de validações.
client                  | *client*                  | Objeto que representa os dados do cliente, seja ele o cliente que está efetuando o pagamento do boleto ou o recebendo o pagamento.
company                 | *company*                 | Objeto que representa a concessionária ou prestador de serviço referente àquela conta.
payer                   | *bill_payer*              | Objeto que representa a pessoa física ou pessoa jurídica que pagou a conta.
recipient               | *bill_client*             | Objeto que representa a pessoa física ou pessoa jurídica para quem a conta foi emitida.
source                  | *source*                  | Objeto do tipo Source que descreve as informações provenientes da aplicação utilizada para o pagamento da conta.

## Enviar um Pagamento de Conta

Request Body

```json
  {
    "id": "12345",
    ...
  }
```

Response Body

```json
  {
    "bill_payment_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf",
    "status": "automatically_approved",
    "reason": "rule_decision_enum"
  }
```

Para realizar a avaliação de um pagamento de conta, basta enviar um objeto do tipo BillPayment ao seguinte endpoint:

`POST https://api.caas.qitech.app/bill_payment/bill_payment`

## Recuperar um Pagamento de Conta

Response Body

```json
  {
    "id": "082373263",
    "amount": 12979,
    ...
  }
```

Para recuperar os dados de um pagamento de conta, basta enviar uma requisição ao seguinte endpoint:

`GET https://api.caas.qitech.app/bill_payment/bill_payment/{bill_payment_id}`

Onde *bill_payment_id* é o identificador da transação no sistema do cliente utilizado no envio do pagamento de conta.

## Atualizar um pagamento de conta

Request Body

```json
  {
    "bill_payment_status": "completed",
    "event_date": "2020-10-07T15:06:25-03:00"
  }
```

Response Body

```json
  {
    "bill_payment_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf",
    "bill_payment_status": "completed"
  }
```

Após um pagamento de conta ser criado e analisado, ela será enviado à câmara de compensação para ser processado. Deste modo, é necessário que seja informada a atualizações de status do pagamento quando este for enviado, através do endpoint:

`PUT https://api.caas.qitech.app/bill_payment/bill_payment/{bill_payment_id}`

Deste modo, garante-se que nossa base de dados seja atualizada e sejamos capazes de identificar os pagamentos que estejam realmente sucetíveis a fraude.

---

# Depósitos

URL: /documentation/caas/banking/deposits/introduction

No momento em que um usuário efetuar um depósito, os dados do depósito deverão ser enviados para a QI Tech. Deste modo, será possível realizar uma análise do risco de fraude e Prevenção a Lavagem de Dinheiro envolvido na operação, baseado naquele conjunto de dados.

## Definição do Objeto de Depósito

Request Body

```json
{
    "id": "082373263",
    "amount": 12979,
    "deposit_date": "2020-10-07T15:06:25-03:00",
    "client": {
        "id": "182373263",
        "type": "natural_person",
        "document_number": "123.456.789-10",
        "name": "Benedito Calixto de Jesus",
        "email": "benedito@test.com",
        "address": {
            "street": "Rua José Wasth Rodrigues",
            "number": "243",
            "neighbourhood": "Vila Maria",
            "city": "São Paulo",
            "uf": "SP",
            "complement": "Apartamento 14B",
            "postal_code": "02121-010"
        },
        "phone": {
            "international_dial_code": "55",
            "area_code": "11",
            "number": "998861708",
            "type": "mobile"
        },
        "sales_channel": "inbound_sales",
        "segment": "Personalité"
    },
    "destination_account": {
        "participant": "17315359",
        "branch": "0000",
        "account_number": "10442",
        "account_digit": "6",
        "account_type": "CACC",
        "opening_date": "2020-01-15T18:00:00-03:00"
    },
    "terminal": {
        "id": "1234566",
        "latitude": -45.2753548,
        "longitude": -15.24587,
        "address": { 
            "street": "Av. Eng. Luis Carlos Berrini",
            "number": "105",
            "neighbourhood": "Brooklin",
            "city": "São Paulo",
            "uf": "SP",
            "complement": "Cj 303",
            "postal_code": "04501-140"
        },
        "type": "atm"
    },
    "authentication": {
        "used_password": true,
        "used_card": true,
        "used_fingerprint": true,
        "typed_account_number": false
    }
}
```

Um depósito deve ser enviado para a API antes de ser encaminhada para o sistema de processamento, a fim de realizar uma validação prévia de fraude.

O status do depósito representa a decisão retornada pelo modelo sobre aquela conta. Os seguintes status são utilizados na flag **analysis_status**:

* `automatically_approved`
* `automatically_reproved`

Abaixo estão listados os significados de cada uma das decisões, devolvida na flag analysis_status:

status | descrição
:----: | ---------
automatically_approved      | Recomenda-se que este depósito seja aprovado.
automatically_reproved      | Recomenda-se que este depósito seja reprovado.

nome | tipo | descrição
:----:  | :----:  | ---------
id | string | Identificador do depósito no sistema do cliente. **É essencial que este número seja único para cada depósito**
amount                      | integer                   | Valor do depósito em centavos - conforme descrição da seção "Padrões".
deposit_date                | datetime                  | Data e hora da realização do depósito - conforme descrição da seção "Padrões".
client                      | *client*                  | Objeto com os dados do cliente detentor da conta de origem.
destination_account         | *account*                 | Objeto que determina a conta de destino do recurso a ser depositado.
terminal                    | *terminal*                | Objeto com os dados do terminal onde o depósito está sendo realizado.
authentication              | *authentication*          | Objeto com as informações de autenticação.

## Objetos do Depósito

### Objeto Terminal

Request Body

```json
{
    "id": "1234566",
    "latitude": -45.2753548,
    "longitude": -15.24587,
    "address": { 
        "street": "Av. Eng. Luis Carlos Berrini",
        "number": "105",
        "neighbourhood": "Brooklin",
        "city": "São Paulo",
        "uf": "SP",
        "complement": "Cj 303",
        "postal_code": "04501-140"
    },
    "type": "atm"
}
```

Objeto que representa o terminal que foi utilizado para o depósito.

nome | tipo | descrição
:----:  | :----:  | ---------
id                          | string                    | Identificador do terminal no sistema do cliente
latitude                    | number                    | Latitude, em graus, da localização do terminal
longitude                   | number                    | Longitude, em graus, da localização do terminal
address                     | *address*                 | Endereço do terminal
type                        | enum                      | Tipo do terminal, possíveis valores: "atm", "counter"

### Objeto Authentication

Request Body

```json
{
    "used_password": true,
    "used_card": true,
    "used_fingerprint": true,
    "typed_account_number": false
}
```

Objeto que define os parâmetros da autenticação utilizada no momento do depósito.

nome | tipo | descrição
:----: | :----: | -----------
used_password               | boolean                           | Determina se o usuário utilizou senha
used_card                   | boolean                           | Determina se o usuário está com o cartão presente na autenticação
used_card_chip_and_pin      | boolean                           | Determina se o usuário utilizou o chip e senha do cartão
used_card_magnetic_stripe   | boolean                           | Determina se o usuário utilizou a tarja magnética do cartão
used_fingerprint            | boolean                           | Determina se o usuário utilizou fingerprint
typed_account_number        | boolean                           | Determina se o usuário digitou os dados da conta

## Enviar um Depósito

Request Body

```json
  {
    "id": "12345",
    ...
  }
```

Response Body

```json
  {
		"id": "082373263",
    "analysis_status": "automatically_approved",
    "reason": "2019-10-01T10:37:25-03:00"
  }
```

Para realizar a avaliação de um depósito, basta enviar um objeto do tipo deposit ao seguinte endpoint:

`POST https://api.caas.qitech.app/deposit/deposit`

## Recuperar um Depósito

Response Body

```json
  {
		"id": "082373263",
    "analysis_status": "automatically_approved",
    "reason": "2019-10-01T10:37:25-03:00"
  }
```

Para recuperar os dados de um depósito, basta enviar uma requisição ao seguinte endpoint:

`GET https://api.caas.qitech.app/deposit/deposit/{deposit_id}`

Onde *deposit_id* é o identificador da transação no sistema do cliente utilizado no envio do depósito.

## Atualizar um depósito

Request Body

```json
  {
    "deposit_status": "completed",
    "event_date": "2020-10-07T15:06:25-03:00"
  }
```

Response Body

```json
  {
		"id": "082373263",
    "deposit_status": "completed"
  }
```

Após um depósito ser criado e analisado, o dinheiro será disponibilizado ao usuário. Este processo pode ser interrompido por alguma outra regra de negócio. Deste modo, é necessário que seja informada a atualizações de status do saque quando este for finalizado, através do endpoint:

`PUT https://api.caas.qitech.app/deposit/deposit/{deposit_id}`

Deste modo, garante-se que nossa base de dados seja atualizada e sejamos capazes de identificar os depósitos que estejam realmente sucetíveis a fraude.

---

# Status HTTP

URL: /documentation/caas/banking/http_status

Todas as APIs da QI Tech utilizam a seguinte padronização nos status HTTP de retorno, de acordo com o RFC 7231 :

Status HTTP | Significado | Descrição
---------- | ------- | ---------------------------------
400 | Bad Request | A requisição enviada possui algum erro de formatação. Na maioria dos casos, retornamos no corpo da mensagem uma explicação de onde está o erro.
401 | Unauthorized | Houve algum problema na autenticação, verifique se a API Key está correta e no header correto, de acordo com a seção Autenticação .
403 | Forbidden | O endpoint acessado é de uso interno e não está disponível para esta API Key.
404 | Not Found | O dado requisitado não foi encontrado usando a chave utilizada. Este status também é retornado quando um endpoint inválido é requisitado.
405 | Method Not Allowed | O método HTTP utilizado não se aplica ao endpoint utilizado.
406 | Not Acceptable | Os dados enviados no corpo da requisição são inválidos. Em geral, isso significa que os dados enviados não são um JSON válido.
409 | Conflict | O id da requisição corresponde a um id já processado anteriormente. Este status é retornado no caso de requisições duplicadas enviadas ao servidor.
500 | Internal Server Error | Tivemos um problema para processar esta requisição, ao encontrarmos esse erro nossos especialistas são automaticamente notificados e iniciam a análise e solução imediatamente.
503 | Service Unavailable | Você se deparou com uma indisponibilidade, planejada ou não, de infraestrutura dos nossos servidores.

---

# Introdução

URL: /documentation/caas/banking/introduction

Bem vindo à API de Banking da QI Tech! Esta API dá acesso à funcionalidade de prevenção a fraudes para operações de bancos e contas digitais, como por exemplo análises de transferências, pagamentos de contas e pagamentos de boletos.

Abaixo, você pode observar a implementação da API utilizando cUrl. Com isso você possui exemplos para poder adaptar adequadamente à linguagem de programação da sua preferência.

## Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso suporte e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

### Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já notou), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

## Ambientes

Possuímos dois ambientes para os nossos clientes. As URLs base das APIs são:

* Produção - `https://api.caas.qitech.app/`
* Sandbox - `https://api.sandbox.caas.qitech.app/`

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.  
:::

## Análises no ambiente de Sandbox

No ambiente de Sandbox, as análises não são cobradas e são respondidas de acordo com regras simplificadas.
Para o caso de *wire_transfers*, *bankslips*, *bill_payments* e *pix*, a resposta dada será baseada no valor da operação (*amount*) enviado na requisição:

mínimo | máximo | decisão
------ | ------ | -------
16000 | - | Contestado Automaticamente*
10000 | 15999 | Aprovado Automaticamente
6000 | 9999 | Derivado para Análise Manual
0 | 5999 | Reprovado Automaticamente

\* Contestado Automaticamente está disponível apenas para o serviço de *pix*.

Para o caso de *withdrawal* e *deposit* a resposta dada será baseada no valor da operação (*amount*) enviado na requisição:

mínimo | máximo | decisão
------ | ------ | -------
10000 | - | Aprovado Automaticamente
0 | 9999 | Reprovado Automaticamente

No caso de operações na DICT, a resposta dada será baseada na chave de vínculo na DICT (*dict_key*) enviada na requisição:

chave na Dict | decisão
:----------: | -------
"Approve_dict_key"      | Aprovado Automaticamente
Qualquer outra string   | Derivado para Análise Manual
"Reprove_dict_key"      | Reprovado Automaticamente

## Somente HTTPS

Por questão de segurança, toda a comunicação com as APIs da QI Tech deve ser realizada utilizando a comunicação HTTPS. Para evitar que, por desatenção ou outro motivo, sejam feitas chamadas HTTP, este servidor somente disponibiliza a porta 443 com comunicação TLS 1.2. Chamadas realizadas utilizando outros protocolos serão automaticamente negadas.

## Fluxos - Transferências

O fluxo de análise de transferências é iniciado em duas situações:

- Uma transferência está sendo efetuada pelo usuário do PSP
- Uma transferência está sendo recebida pelo usuário do PSP

Em ambos os casos, uma chamada ao endpoint de *wire_transfer* deve ser realizada e os possíveis status resultantes são:

enumerador | descrição
:--------: | ---------
automatically_approved | Aprovado Automaticamente
automatically_reproved | Reprovado Automaticamente
in_manual_analysis     | Derivado para Análise Manual
pending                | O objeto de transferência bancária está sendo processado.

Caso a transferência seja derivada para análise manual, um analista deverá aprovar ou reprovar a transferência. Neste momento, um Webhook pode ser gerado para notificar a alteração de status ao PSP ou o PSP pode acompanhar a transferência por meio de Polling. Em ambos os casos, os seguintes status podem ser retornados:

enumerador | descrição
:--------: | ---------
manually_approved | Aprovado Manualmente
manually_reproved | Reprovado Manual

## Fluxos - Boletos

O fluxo de análise de Boletos é iniciado em duas situações:

- Um pagamento de boleto está sendo efetuado pelo usuário do PSP
- Um pagamento de boleto está sendo recebido pelo usuário do PSP

Em ambos os casos, uma chamada ao endpoint de *bankslip* deve ser realizada e os possíveis status resultantes são:

enumerador | descrição
:--------: | ---------
automatically_approved | Aprovado Automaticamente
automatically_reproved | Reprovado Automaticamente
in_manual_analysis     | Derivado para Análise Manual
pending                | O objeto de boleto está sendo processado.

Caso o pagamento de boleto seja derivado para análise manual, um analista deverá aprovar ou reprovar o pagamento. Neste momento, um Webhook pode ser gerado para notificar a alteração de status ao PSP ou o PSP pode acompanhar o pagamento por meio de Polling. Em ambos os casos, os seguintes status podem ser retornados:

enumerador | descrição
:--------: | ---------
manually_approved | Aprovado Manualmente
manually_reproved | Reprovado Manual

## Fluxos - Pagamentos de Contas

O fluxo de análise de Pagamentos de Contas é iniciado quando:

- Um pagamento de conta está sendo efetuado pelo usuário do PSP

Neste caso uma chamada ao endpoint de *bill_payment* deve ser realizada e os possíveis status resultantes são:

enumerador | descrição
:--------: | ---------
automatically_approved | Aprovado Automaticamente
automatically_reproved | Reprovado Automaticamente
in_manual_analysis     | Derivado para Análise Manual
pending                | O objeto de pagamento de contas está sendo processado.

Caso o pagamento de conta seja derivado para análise manual, um analista deverá aprovar ou reprovar o pagamento. Neste momento, um Webhook pode ser gerado para notificar a alteração de status ao PSP ou o PSP pode acompanhar o pagamento por meio de Polling. Em ambos os casos, os seguintes status podem ser retornados:

enumerador | descrição
:--------: | ---------
manually_approved | Aprovado Manualmente
manually_reproved | Reprovado Manual

## Fluxos - Saques

O fluxo de análise de Saques é iniciado na seguinte situação:

- Um saque está sendo efetuado pelo usuário do PSP

Em ambos os casos, uma chamada ao endpoint de *withdrawal* deve ser realizada e os possíveis status resultantes são:

enumerador | descrição
:--------: | ---------
automatically_approved | Aprovado Automaticamente
automatically_reproved | Reprovado Automaticamente

Caso o saque seja derivado para análise manual, um analista deverá aprovar ou reprovar o saque. Neste momento, um Webhook pode ser gerado para notificar a alteração de status ao PSP ou o PSP pode acompanhar o pagamento por meio de Polling. Em ambos os casos, os seguintes status podem ser retornados:

enumerador | descrição
:--------: | ---------
manually_approved | Aprovado Manualmente
manually_reproved | Reprovado Manual

## Fluxos - Transação PIX

O fluxo de pagamento PIX é iniciado em duas situações:

- Um pagamento sendo efetuado pelo usuário do PSP integrado na QI Tech
- Um pagamento sendo recebido de outro PSP

Em ambos os casos, uma chamada ao endpoint de pagamento deve ser realizada e os possíveis status resultantes são:

enumerador | descrição
:--------: | ---------
automatically_approved | Aprovado Automaticamente
automatically_reproved | Reprovado Automaticamente
in_manual_analysis     | Derivado para Análise Manual

Caso o pagamento seja derivado para análise manual, um analista deverá aprovar ou reprovar o pagamento. Neste momento, um Webhook pode ser gerado para notificar a alteração de status ao PSP ou o PSP pode acompanhar o pagamento por meio de Polling. Em ambos os casos, os seguintes status podem ser retornados:

enumerador | descrição
:--------: | ---------
manually_approved | Aprovado Manualmente
manually_reproved | Reprovado Manualmente

## Fluxos - Alteração na DICT

O fluxo de alteração na DICT é iniciado em duas situações:

- O usuário do PSP integrado à QI Tech pede um cadastro/alteração/portabilidade/reivindicação ao PSP integrado à QI Tech
- Uma portabilidade/reivindicação é recebida pelo PSP integrado à QI Tech

Nos cadastros iniciados pelo usuário do PSP, o fluxo de validação de chave deve ser executado antes da alteração na DICT, por meio das APIs de validação da QI Tech. Caso a validação seja realizada pelo próprio PSP, esta informação também pode ser enviada na requisição à QI Tech.

Para dar início ao processo, nestes dois momentos o PSP integrado à QI Tech deverá realizar uma chamada no endpoint adequado, que responderá um dos seguintes status:

enumerador | descrição
:--------: | ---------
automatically_approved | Aprovado Automaticamente
automatically_reproved | Reprovado Automaticamente
in_manual_analysis     | Derivado para Análise Manual

Caso a alteração seja derivada para análise manual, um analista deverá aprovar ou reprovar a alteração. Neste momento, um Webhook pode ser gerado para notificar a alteração de status ao PSP ou o PSP pode acompanhar a alteração por meio de Polling. Em ambos os casos, os seguintes status podem ser retornados:

enumerador | descrição
:--------: | ---------
manually_approved | Aprovado Manualmente
manually_reproved | Reprovado Manualmente
## Autenticação

> Para autenticar uma chamada, utilize o código seguinte:

```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE_API_KEY"
```

> Substitua a API key 'EXAMPLE_API_KEY' com a sua chave adquirida com o nosso suporte.

Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br .

Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:

`Authorization: EXAMPLE_API_KEY`

:::info **Atenção**

Você deve substituir EXAMPLE_API_KEY com a API Key recebida do suporte.
:::

---

# Objetos Compartilhados

URL: /documentation/caas/banking/objects

Boa parte dos dados são compartilhados entre os diferentes eventos de uma conta. Abaixo as definições destes objetos podem ser localizadas de maneira facilitada.

## Objeto Client

Request Body

```json
{
    "id": "123456",
    "type": "natural_person",
    "document_number": "023.456.789-01",
    "name": "John Payer",
    "email": "john@payer.com",
    "address": {
        "street": "Av. Eng. Luis Carlos Berrini",
        "number": "105",
        "neighbourhood": "Brooklin",
        "city": "São Paulo",
        "uf": "SP",
        "complement": "Cj 303",
        "postal_code": "04501-140"
    },
    "phone": {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "998861708",
        "type": "mobile"
    },
    "sales_channel": "inbound_sales",
    "segment": "Personalité"
}
```

Objeto que representa os dados do detenedor da conta.

nome | tipo | descrição
:----:  | :----:  | ---------
type                        | enum *(obrigatório)* | Tipo do cliente: "natural_person" ou "legal_person"
document_number             | string *(obrigatório)* | Número do documento, de acordo co seção padronização
name                        | string *(obrigatório)* | Nome do cliente
email                       | string                    | E-mail do cliente
address                     | *address*                 | Dados de endereço do cliente
phone                       | *phone*                   | Dados telefônicos do cliente
sales_channel               | enum *(obrigatório)*| Canal por onde o cliente se cadastrou
segment                     | string *(obrigatório)*| Segmento do cliente dentro da insituição (ex.: premium, gold)

Existem os seguintes enumeradores para tipo de telefone: `inbound_sales`, `app`, `website`, `call_center` e `branch`

## Objeto Address

Request Body

```json
{
  "street": "Rua do Teste",
  "number": "111",
  "neighbourhood": "Bairro do Exemplo",
  "city": "Aparecida de Goiânia",
  "uf": "GO",
  "complement": "Térreo",
  "postal_code": "00000-000",
  "country": "BRA"
}
```

O objeto *address* é utilizado para representar endereços em toda a API, endereços no território brasileiro são representados da seguinte maneira:

nome | tipo | descrição
---- | :----: | ---------
street | string *(obrigatório)* | Rua do endereço, incluindo o logradouro, evitando, se possível, abreviações.
number | string  *(obrigatório)* | Número do imóvel, incluindo letras caso possua.
neighbourhood | string *(obrigatório)*| Bairro, sem abreviações. **e.g.: Santa Felicidade**
city | string *(obrigatório)*| Nome completo da cidade, sem abreviações
uf | string *(obrigatório)* | A unidade federativa, com duas letras maiúsculas. **e.g.: SP**
complement | string | Quaisquer complementos para localizar o imóvel. **e.g.: Apartamento 101, Conjunto 12**
postal_code  | string *(obrigatório)* | O código postal da localidade, contendo o hífen.
country | string *(obrigatório)* | Código ISO 3166-1 alfa-3 do país do endereço.

No caso dos endereços cujo país não seja Brasil ("BRA"), o postal_code e a unidade federativa poderão ser preenchidos livremente.

## Objeto Phone

Request Body

```json
{
  "international_dial_code": "1",
  "area_code": "11",
  "number": "999999999",
  "type": "mobile"
}
```

Um objeto *phone* representa um número telefônico, dentro ou fora do Brasil e sua classificação. Para isso, os campos são:

nome | tipo | descrição
---- | :----: | ---------
international_dial_code | string *(obrigatório)* | Código de discagem internacional, sem zero ou +, somente números
area_code | string *(obrigatório)* | Código de área, sem zero, somente números
number | string  *(obrigatório)* | Número do telefone, sem o hífen
type | enum  *(obrigatório)* | Tipo de número: celular, residencial, comercial, etc.

Existem os seguintes enumeradores para tipo de telefone: `residential`, `commercial` e `mobile`.

## Objeto Account

Request Body

```json
{
    "participant": "17315359",
    "branch": "0000",
    "account_number": "10442",
    "account_digit": "6",
    "account_type": "CACC",
    "opening_date": "2020-01-15T18:00:00-03:00"
}
```

Objeto que representa os dados de uma conta.

nome | tipo | descrição
:----:  | :----:  | ---------
participant                 | string *(obrigatório)* | ISPB da instituição detentora da conta
branch                      | string *(obrigatório)* | Agência da Conta
account_number              | string *(obrigatório)* | Número da Conta sem o dígito
account_digit               | string *(obrigatório)* | Dígito da conta
account_type                | enum *(obrigatório)* | Tipo da conta de origem, possíveis valores: "CACC", "SLRY" e "SVGS"
opening_date                | datetime | Data de abertura da conta.

## Objeto Source

Request Body

```json

{
    "channel": "app",
    "platform": "android",
    "ip":"255.201.26.1",
    "session_id": "54b8e3cf-15de-41e5-9305-0ecf059d6e2a"
}

```

O objeto source representa o conjunto de informações da plataforma utilizada pelo usuário para realizar a operação. Os campos são:

nome | tipo | descrição
:----: | :----: | ---------
channel     | string | Canal utilizado pelo usuário para realizar a operação, ex.: internet banking, app
platform    | string | Plataforma utilizada pela aplicação
ip          | string | IP coletado do device
session_id  | string | Identificador único da sessão, utilizado para fazer o cruzamento do Device Scan com o evento em questão

## Objeto Dict Key

Request Body

```json
  {
    "key_type": "cpf",
    "key_value": "09991222669",
    "assignment_date": "2020-01-15T18:00:00-03:00"
  }
```

O objeto **dict_key**  é utilizado para representar os dados da chave de vínculo no DICT do cliente, seja ele o recebedor ou o pagador da transação. Os campos desse objeto são:

nome | tipo | descrição
:----: | :----: | ---------
key_type        | string *(obrigatório)* | Enumerador que contém o tipo da chave de vinculo no DICT.
key_value       | string | Contém a chave de vínculo cadastrada no DICT.
assignment_date | datetime  | Data que a chave de vínculo foi cadastrada no DICT.

Os enumeradores para o campo *key_type* são os mesmos definidos na API do DICT: `cpf`,`cnpj`,`email`,`phone` e `evp`.

## Objeto Destination Statistics

Request Body

```json
{
  "account":{
      "settlements":{
          "d3":4,
          "d30":67,
          "m6":618
      },
      "rejected":{
          "d3":4,
          "d30":67,
          "m6":618
      },
      "reported_frauds":{
          "d3":0,
          "d30":0,
          "m6":0
      },
      "reported_aml_cft":{
          "d3":0,
          "d30":0,
          "m6":0
      },
      "confirmed_frauds":{
          "d3":0,
          "d30":0,
          "m6":0
      },
      "confirmed_aml_cft":{
          "d3":0,
          "d30":0,
          "m6":0
      }
  },
  "owner":{
      "settlements":{
          "d3":6,
          "d30":88,
          "m6":996
      },
      "rejected":{
          "d3":4,
          "d30":67,
          "m6":618
      },
      "reported_frauds":{
          "d3":0,
          "d30":0,
          "m6":0
      },
      "reported_aml_cft":{
          "d3":0,
          "d30":0,
          "m6":0
      },
      "confirmed_frauds":{
          "d3":0,
          "d30":0,
          "m6":0
      },
      "confirmed_aml_cft":{
          "d3":0,
          "d30":0,
          "m6":0
      }
  },
  "key":{
      "settlements":{
          "d3":3,
          "d30":51,
          "m6":312
      },
      "rejected":{
          "d3":4,
          "d30":67,
          "m6":618
      },
      "reported_frauds":{
          "d3":0,
          "d30":0,
          "m6":0
      },
      "reported_aml_cft":{
          "d3":0,
          "d30":0,
          "m6":0
      },
      "confirmed_frauds":{
          "d3":0,
          "d30":0,
          "m6":0
      },
      "confirmed_aml_cft":{
          "d3":0,
          "d30":0,
          "m6":0
      }
  }
}
```

Para que o risco de fraude em uma transação seja avaliado com maior precisão, é necessário informar o histórico transacional e de fraudes do creditado através do objeto *Destination Statistics*. Tais dados podem ser obtidos ao se consultar a chave de vinculo do creditado na base de dados do DICT. É exigência do BACEN que esses dados sejam utilizados na avaliação de fraude das transações.

nome | tipo | descrição
:----: | :----: | ---------
account | *account* *(obrigatório)* | Objeto que contém o histórico transacional e de fraudes da conta do creditado.
owner   | *owner* *(obrigatório)* | Objeto que contém o histórico transacional e de fraudes associados ao documento do creditado.
key     | *key* *(obrigatório)* | Objeto que contém o histórico transacional e de fraudes associados a chave fornecida pelo creditado.

Onde cada um dos objetos definidos acima possui os mesmos campos:

nome | tipo | descrição
:----: | :----: | ---------
settlements       | *settlements* *(obrigatório)*   | Objeto que contém o histórico transacional.
rejected          | *rejected* *(opcional)*   | Objeto que contém o histórico de operações negadas.
reported_frauds   | *reported_frauds*  *(obrigatório)* | Objeto que contém o histórico de relatos de fraudes.
reported_aml_cft  | *reported_aml_cft* *(opcional)* | Objeto que contém o histórico de relatos de PLD/FT.
confirmed_frauds  | *confirmed_frauds* *(obrigatório)* | Objeto que contém o histórico de relatos de fraudes confirmados.
confirmed_aml_cft | *confirmed_aml_cft* *(opcional)* | Objeto que contém o histórico de relatos de PLD/FT confirmados.

Onde cada um desses objetos contém os campos **d3**, **d30** e **m6**, contendo o número de ocorrências nos ultimos 3 dias, 30 dias e 6 meses, que são campos obrigatórios, respectivamente. Da mesma forma que é definido pela API do DICT do BCB.

---

# PIX Dict Operation

URL: /documentation/caas/banking/pix_dict_operations

No momento em que o usuário iniciar uma mudança na DICT, os dados deverão ser enviados para o nosso servidor, de maneira que possamos realizar uma análise do risco envolvido naquele conjunto de dados.

## Definição do Objeto de Dict Operation

Request Body

```json
{
  "id": "f58e8a19-429d-4e36-a010-ed00a323c2c5",
  "dict_key": {
      "key_type": "phone",
      "key_value": "16981610077",
      "assignment_date": "2020-01-15T18:00:00-03:00"
  },
  "dict_operation_direction": "claimer",
  "dict_operation_reason": "user_requested",
  "dict_operation_creation_date": "2020-10-14T18:00:00-03:00",
  "dict_operation_type": "claim_portability",
  "client": {
      "id": "123456",
      "document_number": "099.912.226-69",
      "name": "João Jorge da Silva",
      "type": "natural_person",
      "address": {
          "street": "Avenida 13",
          "number": "704",
          "neighbourhood": "Centro",
          "city": "Ituiutaba",
          "uf": "MG",
          "complement": "Apt 1101",
          "postal_code": "38300-140"
      },
      "phone": {
          "international_dial_code": "55",
          "area_code": "65",
          "number": "988961210",
          "type": "mobile"
      },
      "sales_channel": "inbound_sales",
      "segment": "Personalité"
  },
  "source_account": {
      "participant": "04184779",
      "branch": "0001",
      "account_number": "1122",
      "account_digit": "6",
      "owner": {
          "type": "legal_person",
          "document_number": "94.948.708/0001-12",
          "name": "Irmão Soares Ferragista LTDA."
      },
      "account_type": "CACC",
      "opening_date": "2020-01-15T18:00:00-03:00"
  },
  "destination_account": {
      "participant": "00000000",
      "branch": "3675",
      "account_number": "10442",
      "account_digit": "6",
      "owner": {
          "type": "natural_person",
          "document_number": "099.912.226-69",
          "name": "João Jorge da Silva"
      },
      "account_type": "SLRY",
      "opening_date": "2020-01-15T18:00:00-03:00"
  },
  "destination_statistics": {
      "account":{
          "settlements":{
              "d3":12,
              "d30":65,
              "m6":344
          },
          "rejected":{
              "d3":4,
              "d30":67,
              "m6":618
          },
          "reported_frauds":{
              "d3":0,
              "d30":0,
              "m6":0
          },
          "reported_aml_cft":{
              "d3":0,
              "d30":0,
              "m6":0
          },
          "confirmed_frauds":{
              "d3":0,
              "d30":0,
              "m6":0
          },
          "confirmed_aml_cft":{
              "d3":0,
              "d30":0,
              "m6":0
          }
      },
      "owner":{
          "settlements":{
              "d3":4,
              "d30":12,
              "m6":88
          },
          "rejected":{
              "d3":4,
              "d30":67,
              "m6":618
          },
          "reported_frauds":{
              "d3":0,
              "d30":0,
              "m6":0
          },
          "reported_aml_cft":{
              "d3":0,
              "d30":0,
              "m6":0
          },
          "confirmed_frauds":{
              "d3":0,
              "d30":0,
              "m6":0
          },
          "confirmed_aml_cft":{
              "d3":0,
              "d30":0,
              "m6":0
          }
      },
      "key":{
          "settlements":{
              "d3":1,
              "d30":6,
              "m6":12
          },
          "rejected":{
              "d3":4,
              "d30":67,
              "m6":618
          },
          "reported_frauds":{
              "d3":0,
              "d30":0,
              "m6":0
          },
          "reported_aml_cft":{
              "d3":0,
              "d30":0,
              "m6":0
          },
          "confirmed_frauds":{
              "d3":0,
              "d30":0,
              "m6":0
          },
          "confirmed_aml_cft":{
              "d3":0,
              "d30":0,
              "m6":0
          }
      }
  },
  "source": {
      "channel": "internet_banking",
      "platform": "android",
      "ip": "198.185.065-98",
      "session_id": "7839jdqd9a8wd9"
  }
}
```

Uma Dict Operation deve ser enviada para a API antes de ser encaminhada para o sistema de processamento do BCB, a fim de realizar uma validação prévia de fraude de cadastro.

O status da análise da Dict Operation representa a decisão retornada pelo modelo sobre aquela operação. Os seguintes status são utilizados na flag **analysis_status**:

* `automatically_approved`
* `automatically_reproved`
* `in_manual_analysis`
* `pending`

Abaixo estão listados os significados de cada uma das decisões, devolvida na flag analysis_status:

status | descrição
:----: | ---------
automatically_approved      | Recomenda-se que esta operação seja aprovada.
automatically_reproved      | Recomenda-se que esta operação seja reprovada.
in_manual_analysis          | Recomenda-se que a operação seja analisada manualmente por um analista.
pending                     | A operação está sendo processada.

nome | tipo | descrição
:----:  | :----:  | ---------
id | string | Identificador da operação no sistema do cliente. **É essencial que este número seja único para cada processo de autorização**
client                  | *client*                  | Objeto que representa os dados do cliente, seja ele o doador ou o recebedor.
transaction_date        | datetime                  | A data e hora de início da transação, com fuso horário.
dict_key                | *dict_key*                | Objeto que representa os dados da chave de vínculo no DICT, utilizada pelo cliente na trasação.
dict_key_type           | enumerador                | Tipo da chave de vínculo ao DICT.
dict_operation_direction| enumerador                | Direção de operação no DICT, isto é, se uma chave está sendo cedida ou obtida.
dict_operation_reason   | enumerador                | A razão pelo qual a Operação na Dict está sendo realizada.
dict_operation_creation_date     | datetime                  | Data da operação no DICT.
dict_operation_type     | enumerador                | Tipo de operação no DICT.
source_account          | *source_account*          | Objeto que representa os dados da conta que está cedendo a chave de vínculo.
destination_account     | *destination_account*     | Objeto que representa os dados da conta que está recebendo a chave de vínculo.
destination_statistics  | *destination_statistics*  | Objeto que representa o histórico de transações e fraudes da conta que esta recebendo a chave de vinculo.
source                  | *source*                  | Objeto do tipo Source que descreve as informações provenientes da aplicação utilizada para envio do cadastro

O campo *dict_key_type* aceita os mesmos enumeradores definidos na API do DICT: `cpf`,`cnpj`,`email`,`phone` e `evp`.

O campo *dict_operation_direction* aceita os enumeradores: `donor` e `claimer`.

O campo *dict_operation_type* aceita os enumeradores `registration`, `claim_ownership` e `claim_portability`. 
Sendo estas todos os tipos de operações na DICT definidas pelo BCB.

## Enviar uma Dict Operation

Request Body

```json
  {
    "id": "f58e8a19-429d-4e36-a010-ed00a323c2c5",
    ...
  }
```

Response Body

```json
  {
    "dict_operation_key": "7f85e162-5a7d-41fa-a578-69df6f3df958",
    "status": "automatically_approved"
  }
```

Para realizar a avaliação de um pagamento, basta enviar um objeto do tipo Payment ao seguinte endpoint:

`POST https://api.caas.qitech.app/pix/dict_operation`

## Recuperar uma Dict Operation

Response Body

```json
  {
    "id": "f58e8a19-429d-4e36-a010-ed00a323c2c5",
    ...
  }
```

Para recuperar uma Dict Operation, basta enviar uma requisição ao seguinte endpoint:

`GET https://api.caas.qitech.app/pix/dict_operation/{dict_operation_id}`

Onde *dict_operation_id* é o identificador da operação que nos foi enviado no momento do cadastro desta, no campo "id".

Será, então, retornado o objeto Dict Operation associado a chave provida.

## Atualizar uma Dict Operation

Request Body

```json
  {
    "dict_operation_status": "cancelled_by_client",
    "reason": "user_requested",
    "event_date": "2020-10-07T15:06:25-03:00"
  }
```

Uma Dict Operation possui várias fases junto ao BCB antes que seja concluída. Deste modo, é necessário que sejam informadas todas as atualizações de status das operações, através do endpoint:

`PUT https://api.caas.qitech.app/pix/dict_operation/{dict_operation_id}`

Deste modo, garate-se que nossa base de dados seja atualizada e esteja sempre coerente com a base de dados do BCB.

Algumas operações na DICT demandam que seja submetida a razão da operação juntos dos dados. Para estes casos, é necessário informar o campo *reason* no objeto de envio, contendo o mesmo enumerador provido ao sistema do BCB.
São esses:

enumerador | descrição
:--------: | ---------
user_requested    | A operação foi requisitada pelo cliente.
account_closure   | A operação foi iniciada devido ao fechamento da conta do cliente.
branch_transfer   | A operação foi requisitada devido a mudança de agência do cliente.
entry_inactivity  | A operação foi requisitada devido a inatividade na conta do cliente.
reconciliation    | A operação foi requisitada após um processo de reconcialiation.
default_operation | A operação foi requisitada por uma ação padrão do participante.
fraud             | A operação foi requisitada devido a um fraude ligada a conta do cliente.

As fases de uma operação na DICT aceitas pelo campo *dict_operation_status* são:

enumerador | descrição
:--------: | ---------
created                   | A dict_operation foi criada mas ainda não foi analisada.
reproved                  | A dict_operation foi reprovada na análise e não será enviada ao BCB.
waiting_resolution        | A dict_operation foi enviada ao BCB e está esperando a resolução.
cancelled_by_client       | A dict_operation foi cancelada pelo cliente.
cancelled_by_counterpart  | A dict_operation foi cancelada pela outra parte da operação.
confirmed                 | A dict_operation foi confirmada pela outra parte da operação.
completed                 | A dict_operation foi completada e adicionada a base de dados do BCB.

---

# PIX Infraction Report

URL: /documentation/caas/banking/pix_infraction_reports

## Definição do Objeto de Infraction Reports

Request Body

```json
{
    "infraction_report_type": "compliance",
    "infraction_report_details": "Cliente realizou várias compras de valor alto em estabelecimentos comerciais cuja atividade econômica é de alto risco de lavagem de dinheiro. Após uma investigação minuciosa, decidiu-se realizar o report ao COAF e bloquear o saldo em conta até que a origem do dinheiro seja esclarecida. ",
    "infraction_report_creator": "external",
    "infraction_report_date": "2020-10-14T00:25:42-03:00",
    "infraction_report_status": "received",
    "infraction_report_events": [               
        {
            "new_status": "received",
            "event_date": "2020-10-14T00:25:42-03:00"
        }
    ]
}
```

Caso algum comportamento suspeito seja dectado por qualquer uma das partes da transação, um Infraction Report pode ser criado para relatar a suspeita. Esse Infraction Report será então analisado pela outra parte e poderá ser confimado ou não. Seguindo o padrão estabelecido pelo BCB, um Infraction Report deverá ter os campos:

nome | tipo | descrição
:----: | :----: | ---------
infraction_report_type      | enumerador | Enumerador que define o tipo de atividade suspeita presente na transação.
infraction_report_details   | string     | Detalhes das circustâncias que levaram o criador do Infraction Report a acreditar que possa existir algum tipo de infração associada a transação.
infraction_report_creator   | enumerador | Enumerador que define quem criou o Infraction Report.
infraction_report_date      | datetime   | Data do incidente.

O campo *infraction_report_type* poderá conter os enumeradores: `fraud` e `compliance`.

O campo *infraction_report_creator* poderá conter os enumeradores: `client` e `external`.

## Enviar um Infraction Report

Request Body

```json
{
    "infraction_report_type": "compliance",
    "infraction_report_details": "Cliente realizou várias compras de valor alto em estabelecimentos comerciais cuja atividade econômica é de alto risco de lavagem de dinheiro. Após uma investigação minuciosa, decidiu-se realizar o report ao COAF e bloquear o saldo em conta até que a origem do dinheiro seja esclarecida. ",
    "infraction_report_creator": "external",
    "infraction_report_date": "2020-10-14T00:25:42-03:00"
}
```

Response Body

```json
  {
    "infraction_report_key": "7f85e162-5a7d-41fa-a578-69df6f3df958",
    "infraction_report_status": "received"
  }
```

Para realizar a o envio de um Infraction Report, basta enviar uma requisição ao endpoint:

`POST https://api.caas.qitech.app/pix/transaction/{transaction_id}/infraction_report`

Onde *transaction_id* é o identificador da transação que nos foi enviado no momento do cadastro desta, no campo "id".

## Recuperar um Infraction Report

Response Body

```json
  {
      "infraction_report_type": "compliance",
      "infraction_report_details": "Cliente realizou várias compras de valor alto em estabelecimentos comerciais cuja atividade econômica é de alto risco de lavagem de dinheiro. Após uma investigação minuciosa, decidiu-se realizar o report ao COAF e bloquear o saldo em conta até que a origem do dinheiro seja esclarecida. ",
      "infraction_report_creator": "external",
      "infraction_report_date": "2020-10-14T00:25:42-03:00",
      "infraction_report_status": "received",
      "infraction_report_events": [               
          {
              "new_status": "received",
              "event_date": "2020-10-14T00:25:42-03:00"
          }
      ],
      "transaction_data": {
        "transaction_direction": "received",
        "id": "082373263",
        ...
      }
  }
```

Para recuperar um Infraction Report, basta enviar uma requisição ao seguinte endpoint:

`GET https://api.caas.qitech.app/pix/transaction/{transaction_id}/infraction_report/{infraction_report_key}`

Será, então, retornado o objeto Infraction Report associado o *transaction_id* provido e com *infraction_report_key* idêntica a chave enviada.

## Atualizar um Infraction Report

Request Body

```json
  {
    "infraction_report_status": "acknowledged",
    "event_date": "2020-10-07T15:06:25-03:00"
  }
```

Um Infraction Report possui várias fases junto ao BCB antes que seja concluído. Deste modo, é necessário que sejam informadas todas as atualizações de status do Infraction Report, através do endpoint:

`PUT https://api.caas.qitech.app/pix/transaction/{transaction_id}/infraction_report/{infraction_report_key}`

---

# PIX Transaction

URL: /documentation/caas/banking/pix_transactions

No momento em que o pagador iniciar ou receber um pagamento, os dados  da transação deverão ser enviados para o nosso servidor. Deste modo, será possível realizar uma análise do risco envolvido na transação, baseado naquele conjunto de dados.

## Definição do Objeto de Pix Transactions

Request Body

```json
{
    "transaction_direction": "received",
    "id": "082373263",
    "client": {
        "id": "123456",
        "document_number": "056.966.649-03",
        "name": "Francisco Oliveira Benedetti",
        "type": "natural_person",
        "address": {
            "street": "Avenida 13",
            "number": "704",
            "neighbourhood": "Centro",
            "city": "Ituiutaba",
            "uf": "MG",
            "complement": "Apt 1101",
            "postal_code": "38300-140"
        },
        "email": "mailto@qitech.com.br",
        "phone": {
            "international_dial_code": "55",
            "area_code": "16",
            "number": "981610077",
            "type": "mobile"
        },
        "sales_channel": "inbound_sales",
        "segment": "Personalité"
    },
    "amount": 13725,
    "transaction_date": "2020-10-07T15:06:25-03:00",
    "dict_key": {
        "key_type": "cpf",
        "key_value": "09991222669",
        "assignment_date": "2020-01-15T18:00:00-03:00"
    },
    "capture_method": "static_qr_code",
    "face_recognition_key": "ef39e206-13d5-48de-b368-6c3bbc6f0222",
    "validation_key": "69a59de3-0198-4a26-933a-c1de624c147d",
    "source_account": {
        "participant": "17315359",
        "branch": "0000",
        "account_number": "10442",
        "account_digit": "6",
        "owner": {
            "type": "legal_person",
            "document_number": "07.487.735/0001-69",
            "name": "Gioconda Pizzaria e Rotisseria LTDA."
        },
        "account_type": "CACC",
        "opening_date": "2020-01-15T18:00:00-03:00"
    },
    "destination_account": {
        "participant": "60701190",
        "branch": "3675",
        "account_number": "10442",
        "account_digit": "6",
        "owner": {
            "type": "natural_person",
            "document_number": "056.966.649-03",
            "name": "Francisco Oliveira Benedetti"
        },
        "account_type": "SLRY",
        "opening_date": "2020-01-15T18:00:00-03:00"
    },
    "destination_statistics": {
        "person":{
            "settlements":{
                "d90":4,
                "m12":67,
                "m60":618
            },
            "application_frauds":{
                "d90":0,
                "m12":4,
                "m60":9
            },
            "mule_accounts":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "scammer_accounts":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "other_frauds":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "unknown_frauds":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "total_frauds_transaction_amount":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "distinct_fraud_reporters":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "open_reports":0,
            "open_reports_distinct_reporters":0,
            "rejected_reports":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "registered_accounts":0         
        },
        "owner":{
            "settlements":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "application_frauds":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "mule_accounts":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "scammer_accounts":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "other_frauds":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "unknown_frauds":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "total_frauds_transaction_amount":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "distinct_fraud_reporters":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "open_reports":0,
            "open_reports_distinct_reporters":0,
            "registered_accounts":0     
        },
        "key":{
            "settlements":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "application_frauds":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "mule_accounts":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "scammer_accounts":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "other_frauds":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "unknown_frauds":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "total_frauds_transaction_amount":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "distinct_fraud_reporters":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "open_reports":0,
            "open_reports_distinct_reporters":0,
            "rejected_reports":{
                "d90":0,
                "m12":0,
                "m60":0
            },
            "distinct_accounts":{
                "d90":0,
                "m12":0,
                "m60":0
            }
        }
    },
    "source": {
        "channel": "internet_banking",
        "platform": "android",
        "ip": "198.185.065.098",
        "session_id": "7839jdqd9a8wd9"
    }
}
```

Uma transação deve ser enviado para a API antes de ser encaminhada para o sistema de processamento, a fim de realizar uma validação prévia de fraude.

O status da transação representa a decisão retornada pelo modelo sobre aquela transação. Os seguintes status são utilizados na flag **analysis_status**:

* `automatically_approved`
* `automatically_reproved`
* `in_manual_analysis`
* `pending`

Abaixo estão listados os significados de cada uma das decisões, devolvida na flag analysis_status:

status | descrição
:----: | ---------
automatically_approved      | Recomenda-se que esta transação seja aprovada.
automatically_reproved      | Recomenda-se que esta transação seja reprovada.
approved_by_time            | A transação foi aprovada por expiração de tempo de análise manual
reproved_by_time            | A transação foi aprovada por expiração de tempo de análise manual
in_manual_analysis          | Recomenda-se que a transação seja analisada manualmente por um analista.
pending                     | A transação está sendo processada.

nome | tipo | descrição
:----:  | :----:  | ---------
transaction_direction   | enumerador  | Tipo da transação cadastrada. Define se o cliente está recebendo ou enviando dinheiro. *(obrigatório)*
id | string | Identificador do pagamento no sistema do cliente. **É essencial que este número seja único para cada processo de pagamento** *(obrigatório)*
client                  | *client* | Objeto que representa os dados do cliente, seja ele o pagador ou o recebedor. *(obrigatório)*
amount                  | inteiro  | O valor do pagamento, em centavos- conforme descrição da seção "Padrões". *(obrigatório)*
pix_modality            | string   | Tipo de transação cadastrada. Indica se representa uma transferência, um troco ou um saque.
transaction_date        | datetime | A data e hora de início da transação, com fuso horário. *(obrigatório)*
dict_key                | *dict_key*                | Objeto que representa os dados da chave de vínculo no DICT, utilizada pelo cliente na trasação.
capture_method          | enumerador | Método utilizado para iniciação do pagamento, se foi via QR Code estático ou dinâmico, via preenchimento de dados ou via chave da DICT. *(obrigatório)*
face_recognition_key    | string                    | Chave de reconhecimento facial, caso tenha sido feito reconhecimento facial pela nossa API de reconhecimento facial.
validation_key          | string                    | Chave de validação, caso tenha sido feita algum teste de validação do cliente em nossa API de validações.
source_account          | *source_account* | Objeto que representa os dados da conta debitada. *(obrigatório)*
destination_account     | *destination_account* | Objeto que representa os dados da conta creditada. *(obrigatório)*
destination_statistics  | *destination_statistics*  | Objeto que representa o histórico de transações e fraudes da conta creditada provenientes da API de DICT do BACEN. *(obrigatório)*
source                  | *source* | Objeto do tipo Source que descreve as informações provenientes da aplicação utilizada para envio do pagamento

Existem os seguintes enumeradores para *transaction_direction*: `sent` e `received`.

Existem os seguintes enumeradores para *pix_modality*: `transacation`, `change` e `withdraw`.

Existem os seguintes enumeradores para *capture_method*: `static_qr_code`, `dynamic_qr_code`, `offline_qr_code`, `typed`.

## Enviar uma Transação

Request Body

```json
  {
    "id": "12345",
    ...
  }
```

Response Body

```json
  {
    "transaction_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf",
    "analysis_status": "automatically_approved",
    "reason": "rule_decision_enum"
  }
```

Para realizar a avaliação de uma transação, basta enviar um objeto do tipo Transaction ao seguinte endpoint:

`POST https://api.caas.qitech.app/pix/transaction`

## Recuperar uma Transação

Response Body

```json
  {
    "transaction_direction": "received",
    "id": "082373263",
    ...
  }
```

Para recuperar os dados de uma transação, basta enviar uma requisição ao seguinte endpoint:

`GET https://api.caas.qitech.app/pix/transaction/{transaction_id}`

Onde *transaction_id* é o identificador da transação que nos foi enviado no momento do cadastro, no campo "id".

## Atualizar uma Transação

Request Body

```json
  {
    "transaction_status": "sent",
    "event_date": "2020-10-07T15:06:25-03:00"
  }
```

Após uma transação ser criada e analisada, ela deve ser enviada ao BCB para ser processada. Deste modo, é necessário que seja informada a atualizações de status da transação quando essa for enviada ao BCB, através do endpoint:

`PUT https://api.caas.qitech.app/pix/transaction/{transaction_id}`

Deste modo, garante-se que nossa base de dados seja atualizada e esteja sempre coerente com a base de dados do BCB.

## Transação não efetivada

Request Body

```json
  {
    "transaction_status": "cancelled",
    "reason": "refused_by_counterpart",
    "event_date": "2020-10-07T15:06:25-03:00"
  }
```

Caso uma transação, por qualquer motivo, não tenha sido efetivada (i.e.: Saldo debitado da conta de origem e creditado na conta de destino), a transação pode ser atualizada para o status `cancelled`, com a razão do cancelamento para que seja possível identificar perfis de fraude relacionados a transação não efetivadas. O status cancelled só pode ser utilizado em transações que ainda possuem o status created, uma vez que o status `sent` é utilizado nos casos em que a transação foi evetivada.

`PUT https://api.caas.qitech.app/pix/transaction/{transaction_id}`

As seguintes reasons são atualmente aceitas pela API, caso você veja a necessidade de enquadrar o motivo do cancelamento em outra reason, por favor, entre em contato com suporte.caas@qitech.com.br.

reason | descrição
:----:  | ---------
insufficient_balance | O cliente não possui saldo na conta para realizar a transação
fraud_prevention | A transação foi cancelada pois não foi aprovada no sistema antifraude
system_block | Algum bloqueio de sistema não permitiu a execução da transação, por exemplo conta cancelada/inativa ou limite alcançado
invalid_destination | A instituição contraparte não aceitou a transação pois a conta de destino não existe
refused_by_counterpart | A instituição contraparte rejeitou a transação
system_error | A transação foi cancelada pois houve um erro no sistema da própria instituição
invalid_authentication | A transação foi cancelada pois o cliente não passou em algum fluxo de autenticação

---

# Padrões

URL: /documentation/caas/banking/standards

Para facilitar a integração e garantir a integridade da informação, foram definidos alguns padrões que são seguidos em toda a API.

## Valores Monetários
> Exemplos:

```
10000
12345
98741
1223
1
0
```

Os valores devem ser enviados como inteiro em centavos.

## Data e Hora com Fuso Horário
> Alguns exemplos:

```
2019-10-15T22:35:12-03:00
2018-05-01T13:32:11+00:00
2019-05-01T00:00:00+00:00
```

É representada conforme a ISO 8601. Neste caso, o fuso-horário é colocado logo após o horário e deve representar o fuso do local onde aquele dado será valido. Por exemplo, se um aluguel estiver marcado para começar às 09:30 no aeroporto de Brasília, o horário enviado deverá ser representado por 09:30-03:00, se o aluguel estiver marcado para começar às 09:30 em Manaus, deverá ser representado por 09:30-04:00.

A máscara utilizada para validação é a seguinte:

`YYYY-MM-ddThh:mm:ss±hh:mm`

## Data e Hora sem Fuso Horario
> Alguns exemplos:

```
2019-10-15T22:35:12Z
2018-05-01T13:32:11Z
2019-05-01T00:00:00Z
```

É representada conforme a ISO 8601. Dados que independem de fuso-horário deverão ser enviados sem ele, sempre em UTC, com a letra Z indicando que este dado está em UTC. O seguinte formato, portanto, será validado:

`YYYY-MM-ddThh:mm:ssZ`

## Data
> Alguns exemplos

``` 
2019-10-15
2019-01-01
2017-03-20
```

No caso de campos que recebem somente data, uma data de nascimento, por exemplo, somente a data, sem nenhum horário deve ser enviada com o seguinte formato:

`YYYY-MM-dd`

---

# Webhook

URL: /documentation/caas/banking/webhook

Webhook

Atualizações no status de fraude (Para eventos que sejam derivados para análise manual ou que sejam respondidos como Pendente), são notificados por meio de Webhook. Para tanto, é necessário, por meio da equipe do [suporte](mailto:suporte.caas@qitech.com.br), configurar um endereço do endpoint por onde vamos notificar as atualizações e também uma *signature_key* que será utilizada para assinar a requisição.

O cliente pode também utilizar a técnica de [polling](https://en.wikipedia.org/wiki/Polling_(computer_science)). Neste caso, basta não configurar o endpoint de webhook e utilizar os endpoints de recuperação para proceder com o polling.

:::info **Atenção**

Por questões de segurança, todas as requisições de Webhook serão somente realizadas em endpoints servidos por HTTPS.
:::

## Assinatura do Webhook

## Webhook de Atualização de Evento

Request Body

```json
    {
        "id": "123456",
        "analysis_status": "automatically_approved",
        "event_date": "2019-10-01T10:37:25-03:00"
    }
```

A requisição de atualização do status de análise de um evento possui o formato acima e notifica a mudança no status de fraude. O método utilizado é um PUT e o endereço do endpoint pode conter também o id do evento, de acordo com a necessidade do cliente. É importante ressaltar que o corpo da requisição é enviado como texto codificado em UTF-8.

Exemplos de endpoints para atualização de evento:

* https://apidocliente.com.br/\{evento\}
* https://apidocliente.com.br/admin/\{evento\}/123456

O campo \{evento\}, localizado na URL da requisição, pode assumir os seguintes valores, a depender do evento sendo notificado:
* bill_payment
* bankslip
* wire_transfer
* withdrawal
* pix

O campo event_date indica a data e hora em que a notificação foi criada e pode estar no passado caso envios de notificação anteriores tenham falhado.

## Retentativas

A notificação é considerada realizada quando recebe como resposta um HTTP Status 200. Caso as notificações falhem, serão feitas 7 retentativas, com os seguintes intervalos, até que um 200 seja retornado ou as tentativas terminem:

* 10 segundos
* 40 segundos
* 160 segundos
* 640 segundos
* 2560 segundos
* 10240 segundos
* 40960 segundos

---

# Transferências

URL: /documentation/caas/banking/wire_transfers

No momento em que um usuário efetuar ou receber uma transferência, os dados da transferência deverão ser enviados para a QI Tech. Deste modo, será possível realizar uma análise do risco envolvido na transação, baseado naquele conjunto de dados.

## Definição do Objeto de Transferência

Request Body

```json
{
    "id": "082373263",
    "wire_transfer_direction": "received",
    "wire_transfer_type": "ted",
    "amount": 13725,
    "wire_transfer_date": "2020-10-07T15:06:25-03:00",
    "face_recognition_key": "ef39e206-13d5-48de-b368-6c3bbc6f0222",
    "validation_key": "69a59de3-0198-4a26-933a-c1de624c147d",
    "client": {
        "type": "natural_person",
        "id": "123456",
        "document_number": "056.966.649-03",
        "name": "Francisco Oliveira Benedetti",
        "address": {
            "street": "Avenida 13",
            "number": "704",
            "neighbourhood": "Centro",
            "city": "Ituiutaba",
            "uf": "MG",
            "complement": "Apt 1101",
            "postal_code": "38300-140"
        },
        "phone": {
            "international_dial_code": "55",
            "area_code": "16",
            "number": "981610077",
            "type": "mobile"
        },
        "email": "mailto@qitech.com.br",
        "sales_channel": "inbound_sales",
        "segment": "Personalité"
    },
    "source_account": {
        "participant": "17315359",
        "branch": "0000",
        "account_number": "10442",
        "account_digit": "6",
        "owner": {
            "type": "legal_person",
            "document_number": "07.487.735/0001-69",
            "name": "Gioconda Pizzaria e Rotisseria LTDA."
        },
        "account_type": "CACC",
        "opening_date": "2020-01-15T18:00:00-03:00"
    },
    "destination_account": {
        "participant": "60701190",
        "branch": "3675",
        "account_number": "10442",
        "account_digit": "6",
        "owner": {
            "type": "natural_person",
            "document_number": "056.966.649-03",
            "name": "Francisco Oliveira Benedetti"
        },
        "account_type": "SLRY",
        "opening_date": "2020-01-15T18:00:00-03:00"
    },
    "source": {
        "channel": "internet_banking",
        "platform": "android",
        "ip": "198.185.065.098",
        "session_id": "7839jdqd9a8wd9"
    }
}
```

Uma transferência deve ser enviado para a API antes de ser encaminhada para o sistema de processamento, a fim de realizar uma validação prévia de fraude.

O status da transferência representa a decisão retornada pelo modelo sobre aquela transferência. Os seguintes status são utilizados na flag **analysis_status**:

* `automatically_approved`
* `automatically_reproved`
* `in_manual_analysis`
* `pending`

Abaixo estão listados os significados de cada uma das decisões, devolvida na flag analysis_status:

status | descrição
:----: | ---------
automatically_approved      | Recomenda-se que esta transferência seja aprovada.
automatically_reproved      | Recomenda-se que esta transferência seja reprovada.
in_manual_analysis          | Recomenda-se que a transferência seja analisada manualmente por um analista.
pending                     | A transferência está sendo processada.

nome | tipo | descrição
:----:  | :----:  | ---------
id | string | Identificador da transação no sistema do cliente. **É essencial que este número seja único para cada transferência**
wire_transfer_direction | enumerador                | Modalidade da transferência cadastrada. Define se o cliente está recebendo ou enviando dinheiro.
wire_transfer_type      | enumerador                | Tipo da transferência realizada, podendo ser uma TED, um DOC ou uma transferência interna entre contas da mesma instituição.
amount                  | inteiro                   | O valor da transferência em centavos - conforme descrição da seção "Padrões".
wire_transfer_date      | datetime                  | A data e hora de início da transferência, com fuso horário.
face_recognition_key    | string                    | Chave de reconhecimento facial, caso tenha sido feito reconhecimento facial pela nossa API de reconhecimento facial.
validation_key          | string                    | Chave de validação, caso tenha sido feita algum teste de validação do cliente em nossa API de validações.
client                  | *client*                  | Objeto que representa os dados do cliente, seja ele o cliente que está efetuando a transferência ou o recebedor.
source_account          | *source_account*          | Objeto que representa os dados da conta debitada.
destination_account     | *destination_account*     | Objeto que representa os dados da conta creditada.
source                  | *source* | Objeto do tipo Source que descreve as informações provenientes da aplicação utilizada para envio da transferência

Existem os seguintes enumeradores para *wire_transfer_direction*: `sent` e `received`.

Existem os seguintes enumeradores para *wire_transfer_type*: `ted`, `doc`, `internal_transfer`.

## Enviar uma Transferência

Request Body

```json
  {
    "id": "12345",
    ...
  }
```

Response Body

```json
  {
    "wire_transfer_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf",
    "status": "automatically_approved",
    "reason": "rule_decision_enum"
  }
```

Para realizar a avaliação de uma transferência, basta enviar um objeto do tipo Wire Transfer ao seguinte endpoint:

`POST https://api.caas.qitech.app/wire_transfer/wire_transfer`

## Recuperar uma Transferência

Response Body

```json
  {
    "id": "082373263",
    "wire_transfer_direction": "received",
    ...
  }
```

Para recuperar os dados de uma transferência, basta enviar uma requisição ao seguinte endpoint:

`GET https://api.caas.qitech.app/wire_transfer/wire_transfer/{wire_transfer_id}`

Onde *wire_transfer_id* é o identificador da transação no sistema do cliente utilizado no envio da transferência.

## Atualizar uma transferência

Request Body

```json
  {
    "wire_transfer_status": "completed",
    "event_date": "2020-10-07T15:06:25-03:00"
  }
```

Response Body

```json
  {
    "wire_transfer_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf",
    "wire_transfer_status": "completed"
  }
```

Após uma transferência ser criada e analisada, ela será enviado à câmara de compensação para ser processada. Deste modo, é necessário que seja informada a atualizações de status da transferência quando esta for enviada, através do endpoint:

`PUT https://api.caas.qitech.app/wire_transfer/wire_transfer/{wire_transfer_id}`

Deste modo, garante-se que nossa base de dados seja atualizada e sejamos capazes de identificar as transferências que estejam realmente sucetíveis a fraude.

---

# Saques

URL: /documentation/caas/banking/withdrawals

No momento em que um usuário efetuar um saque, os dados do saque deverão ser enviados para a QI Tech. Deste modo, será possível realizar uma análise do risco envolvido na operação, baseado naquele conjunto de dados.

## Definição do Objeto de Saque

Request Body

```json
{
    "id": "082373263",
    "amount": 12979,
    "withdrawal_date": "2020-10-07T15:06:25-03:00",
    "service_description": "SAQUE EM CAIXA 24H",
    "source_account": {
        "participant": "17315359",
        "branch": "0000",
        "account_number": "10442",
        "account_digit": "6",
        "account_type": "CACC",
        "opening_date": "2020-01-15T18:00:00-03:00"
    },
    "client": {
        "id": "182373263",
        "type": "natural_person",
        "document_number": "023.456.789-01",
        "name": "John Payer",
        "email": "john@payer.com",
        "address": {
            "street": "Av. Eng. Luis Carlos Berrini",
            "number": "105",
            "neighbourhood": "Brooklin",
            "city": "São Paulo",
            "uf": "SP",
            "complement": "Cj 303",
            "postal_code": "04501-140"
        },
        "phone": {
            "international_dial_code": "55",
            "area_code": "11",
            "number": "998861708",
            "type": "mobile"
        },
        "sales_channel": "inbound_sales",
        "segment": "Personalité"
    },
    "terminal": {
        "id": "1234566",
        "latitude": -45.2753548,
        "longitude": -15.24587,
        "address": { 
            "street": "Av. Eng. Luis Carlos Berrini",
            "number": "105",
            "neighbourhood": "Brooklin",
            "city": "São Paulo",
            "uf": "SP",
            "complement": "Cj 303",
            "postal_code": "04501-140"
        },
        "type": "atm"
    },
    "authentication": {
        "used_password": true,
        "used_card": true,
        "used_fingerprint": true,
        "typed_account_number": false
    }
}
```

Um saque deve ser enviado para a API antes de ser encaminhada para o sistema de processamento, a fim de realizar uma validação prévia de fraude.

O status do saque representa a decisão retornada pelo modelo sobre aquela conta. Os seguintes status são utilizados na flag **analysis_status**:

* `automatically_approved`
* `automatically_reproved`

Abaixo estão listados os significados de cada uma das decisões, devolvida na flag analysis_status:

status | descrição
:----: | ---------
automatically_approved      | Recomenda-se que este saque seja aprovado.
automatically_reproved      | Recomenda-se que este saque seja reprovado.

nome | tipo | descrição
:----:  | :----:  | ---------
id | string | Identificador do saque no sistema do cliente. **É essencial que este número seja único para cada saque**
amount                      | inteiro                   | Valor do saque em centavos - conforme descrição da seção "Padrões".
withdrawal_date             | datetime                  | Data e hora da realização do saque - conforme descrição da seção "Padrões"
source_account              | *account*                 | Objeto que determina a conta de origem do recurso a ser sacado
client                      | *client*                  | Objeto com os dados do cliente detentor da conta de origem
terminal                    | *terminal*                | Objeto com os dados do terminal onde o saque está sendo realizado
authentication              | *authentication*          | Objeto com as informações de autenticação

## Objetos do Saque

### Objeto Terminal

Request Body

```json
{
    "id": "1234566",
    "latitude": -45.2753548,
    "longitude": -15.24587,
    "address": { 
        "street": "Av. Eng. Luis Carlos Berrini",
        "number": "105",
        "neighbourhood": "Brooklin",
        "city": "São Paulo",
        "uf": "SP",
        "complement": "Cj 303",
        "postal_code": "04501-140"
    },
    "type": "atm"
}
```

Objeto que representa o terminal que foi utilizado para o saque.

nome | tipo | descrição
:----:  | :----:  | ---------
id                          | string                    | Identificador do terminal no sistema do cliente
latitude                    | number                    | Latitude, em graus, da localização do terminal
longitude                   | number                    | Longitude, em graus, da localização do terminal
address                     | *address*                 | Endereço do terminal
type                        | enum                      | Tipo do terminal, possíveis valores: "atm", "counter"

### Objeto Authentication

Request Body

```json
{
    "used_password": true,
    "used_card": true,
    "used_fingerprint": true,
    "typed_account_number": false
}
```

Objeto que define os parâmetros da autenticação utilizada no momento do saque.

nome | tipo | descrição
:----: | :----: | -----------
used_password               | boolean                           | Determina se o usuário utilizou senha
used_card                   | boolean                           | Determina se o usuário está com o cartão presente na autenticação
used_card_chip_and_pin      | boolean                           | Determina se o usuário utilizou o chip e senha do cartão
used_card_magnetic_stripe   | boolean                           | Determina se o usuário utilizou a tarja magnética do cartão
used_fingerprint            | boolean                           | Determina se o usuário utilizou fingerprint
typed_account_number        | boolean                           | Determina se o usuário digitou os dados da conta

## Enviar um Saque

Request Body

```json
  {
    "id": "12345",
    ...
  }
```

Response Body

```json
  {
    "withdrawal_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf",
    "status": "automatically_approved",
    "reason": "rule_decision_enum"
  }
```

Para realizar a avaliação de um pagamento de conta, basta enviar um objeto do tipo withdrawal ao seguinte endpoint:

`POST https://api.caas.qitech.app/withdrawal/withdrawal`

## Recuperar um Saque

Request Body

```json
  {
    "id": "082373263",
    "amount": 12979,
    ...
  }
```

Para recuperar os dados de um saque, basta enviar uma requisição ao seguinte endpoint:

`GET https://api.caas.qitech.app/withdrawal/withdrawal/{withdrawal_id}`

Onde *withdrawal_id* é o identificador da transação no sistema do cliente utilizado no envio do saque.

## Atualizar um saque

Request Body

```json
  {
    "withdrawal_status": "completed",
    "event_date": "2020-10-07T15:06:25-03:00"
  }
```

Response Body

```json
  {
    "withdrawal_key": "13d680ef-4b72-4cb2-a63d-cf3d790abaaf",
    "withdrawal_status": "completed"
  }
```

Após um saque ser criada e analisada, o dinheiro será disponibilizado ao usuário. Este processo pode ser interrompido por alguma outra regra de negócio. Deste modo, é necessário que seja informada a atualizações de status do saque quando este for finalizado, através do endpoint:

`PUT https://api.caas.qitech.app/withdrawal/withdrawal/{withdrawal_id}`

Deste modo, garante-se que nossa base de dados seja atualizada e sejamos capazes de identificar os saques que estejam realmente sucetíveis a fraude.

---

# Status HTTP

URL: /documentation/caas/car_rental/http_status

Todas as APIs da QI Tech utilizam a seguinte padronização nos status HTTP de retorno, de acordo com o [RFC 7231](https://tools.ietf.org/html/rfc7231):

| Status HTTP | Significado | Descrição |
| ---------- | ------- | --------------------------------- |
| 400 | Bad Request | A requisição enviada possui algum erro de formatação. Na maioria dos casos, retornamos no corpo da mensagem uma explicação de onde está o erro. |
| 401 | Unauthorized | Houve algum problema na autenticação, verifique se a API Key está correta e no header correto, de acordo com a seção Autenticação. |
| 403 | Forbidden | O endpoint acessado é de uso interno e não está disponível para esta API Key. |
| 404 | Not Found | O dado requisitado não foi encontrado usando a chave utilizada. Este status também é retornado quando um endpoint inválido é requisitado. |
| 405 | Method Not Allowed | O método HTTP utilizado não se aplica ao endpoint utilizado. |
| 406 | Not Acceptable | Os dados enviados no corpo da requisição são inválidos. Em geral, isso significa que os dados enviados não são um JSON válido. |
| 409 | Conflict | O id da requisição corresponde a um id já processado anteriormente. Este status é retornado no caso de requisições duplicadas enviadas ao servidor. |
| 500 | Internal Server Error | Tivemos um problema para processar esta requisição, ao encontrarmos esse erro nossos especialistas são automaticamente notificados e iniciam a análise e solução imediatamente. |
| 503 | Service Unavailable | Você se deparou com uma indisponibilidade, planejada ou não, de infraestrutura dos nossos servidores. |

---

# Imagens

URL: /documentation/caas/car_rental/image

Em várias situações é necessário enviar imagens para a nossa API, a fim de realizar operações de OCR, FaceMatch e validação de documentos. Para tanto, é preciso inicialmente realizar o upload da imagem para depois enviá-la para análise.

Ao enviar uma imagem utilizando o endpoint /image uma GUID (Globally Unique Identifier) é retornada. Este valor deverá ser utilizado nas chamadas subsequentes para referenciar esta imagem.

:::warning
O tamanho máximo de uma imagem aceita é de 10MB.
:::

:::warning
Neste momento, somente imagens com formato jpg são aceitas.
:::

## Envio

Exemplo de envio utilizando o cUrl:

```shell
curl -F "data=@path/to/local/file" \
     -H "Authorization: TESTETESTETESTE" \
     -H "DocumentNumber: 000.000.000-00" \
     "https://api.caas.qitech.app/car_rental/image?type=face"
```

Exemplo de retorno:

```json
{
  "image_key": "f1c0d2e1-f950-4360-896d-36588e443fc9",
  "file_name": "05696664903.jpg",
  "file_size": 47407,
  "width_px": 0,
  "height_px": 0,
  "type": "face",
  "created_at": "2020-07-29T18:40:57Z"
}
```

Para enviar uma imagem, basta realizar o envio da imagem no formato .jpg em `multipart/form-data` com uma requisição POST no endpoint:

`POST https://api.caas.qitech.app/car_rental/image?type=$type`

Onde $type é a classificação da imagem e deve ser enviado conforme um dos seguintes enumeradores (Caso a imagem sendo enviada não se enquadre em nenhuma das classificações, entrar em contato com o [suporte](mailto:suporte.caas@qitech.com.br) para que providenciem a adição):

- `face`
- `driver_license`
- `id`
- `contract`

Após o envio, será retornado um objeto JSON com a GUID que aponta para a imagem que foi enviada.

## Análise da Imagem para App

Ao utilizar a api_key do App, o resultado contará com um valor adicional, chamado de `result` que pode receber os seguintes valores:

- `registration_approved`
- `registration_reproved`

Que indica se o cadastro da foto foi aprovado ou reprovado.

Neste momento, a qualidade da foto também é avaliada, podendo receber um resultado 400, conforme descrito no próximo item.

Exemplo de retorno para o App:

```json
{
  "image_key": "f1c0d2e1-f950-4360-896d-36588e443fc9",
  "file_name": "05696664903.jpg",
  "file_size": 47407,
  "width_px": 0,
  "height_px": 0,
  "type": "face",
  "result": "registration_approved",
  "created_at": "2020-07-29T18:40:57Z"
}
```

## Validação de qualidade da imagem

Exemplo de retorno em caso de imagem inválida:

```json
{
  "title": "image_quality",
  "description": "A imagem enviada não possui uma face"
}
```

Ao realizar um post no endpoint de imagem, caso a imagem não seja suficiente para validação, um HTTP Status Code 400 será retornado, como pode ser visto no exemplo acima.

O valor do campo description é a mensagem que explica o motivo da imagem ser inválida.

:::info
Existem outros motivos pelos quais retornaremos 400 (Todos relacionados a dados inválidos). Somente os retornos com title "image_quality" são resultantes da validação de qualidade da imagem e portanto devem ser repassados ao usuário.
:::

## Recuperação dos Arquivos

Leitura de imagem:

```shell
curl "https://api.caas.qitech.app/car_rental/image/{image_key}/file" \
     -H "Authorization: TESTETESTETESTE"
```

Após o envio de uma imagem para a API, é possível recuperá-la por meio de uma requisição GET adequadamente autenticada no endpoint:

`GET https://api.caas.qitech.app/car_rental/image/{image_key}/file`

Onde image_key é o valor retornado durante o envio da imagem.

## Recuperação dos meta-dados do arquivo

Leitura de meta dados:

```shell
curl "https://api.caas.qitech.app/car_rental/image/{image_key}" \
     -H "Authorization: TESTETESTETESTE"
```

Após o envio de uma imagem para a API, é possível recuperar os meta-dados da imagem utilizando o endpoint:

`GET https://api.caas.qitech.app/car_rental/image/{image_key}`

Onde image_key é o valor retornado durante o envio da imagem.

---

# Introdução

URL: /documentation/caas/car_rental/introduction

Bem vindo à API de Prevenção a Fraudes em aluguel de veículos da QI Tech! Você pode utilizar a nossa API para acessar os endpoints, a fim de receber a resposta de um contrato de aluguel, além de utilizar para atualizar a situação de um contrato.

## Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso [suporte](mailto:suporte.caas@qitech.com.br) e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

### Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

## Ambientes

Possuímos dois ambientes para os nossos clientes. A URL base das APIs são:

- Produção - `https://api.caas.qitech.app/car_rental/`
- Sandbox - `https://api.sandbox.caas.qitech.app/car_rental/`

No ambiente de Sandbox, as análises enviadas não são cobradas e são respondidas de acordo com a seguinte regra **baseada no valor total do aluguel**:

| Mínimo | Máximo | Decisão |
| ------ | ------ | ------- |
| 10000 | -- | Pendente (Em análise Manual) - Sem Decisão da Mesa |
| 8000 | 9999 | Aprovado Automaticamente |
| 6000 | 7999 | Reprovado Automaticamente |
| 5000 | 5999 | Derivado para Análise Manual - Com aprovação posterior |
| 4000 | 4999 | Derivado para Análise Manual - Com reprovação posterior |
| 3000 | 3999 | Derivado para Análise Manual - Com Desafio Manual |
| 0 | 2999 | Pendente (Em análise Manual) - Sem Decisão da Mesa |

As análises de upgrade em ambiente de Sandbox seguirão as decisões de análise abaixo:

| Grupos | upgrade_status |
| ------ | -------------- |
| ('C', 'CX', 'SV', 'SU') | 'automatically_approved' |
| ('IE', 'J', 'SG') | 'automatically_reproved' |

## Somente HTTPS

Por questão de segurança, toda a comunicação com as APIs da QI Tech devem ser realizadas utilizando a comunicação HTTPS. Para garantir que, por desatenção ou qualquer outro motivo, não ocorram chamadas HTTP, este servidor somente disponibiliza a porta 443 com comunicação TLS 1.2. Chamadas realizadas utilizando outros protocolos serão automaticamente negadas.

## Autenticação

```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
  -H "Authorization: API-KEY-EXAMPLE"
```

:::info
Substitua a API key `API-KEY-EXAMPLE` com a sua chave adquirida com o nosso suporte.
:::

Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para [suporte.caas@qitech.com.br](mailto:suporte.caas@qitech.com.br).

Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:

`Authorization: API-KEY-EXAMPLE`

:::note
Você deve substituir `API-KEY-EXAMPLE` com a API Key recebida do suporte.
:::

---

# Troca de Mensagens

URL: /documentation/caas/car_rental/messages

Para a troca de mensagens entre a mesa de análise manual e o atendente da loja, são disponibilizados dois endpoints:

- `POST https://api.caas.qitech.app/car_rental/rental_agreement/{rental_agreement_id}/message`
- `GET https://api.caas.qitech.app/car_rental/rental_agreement/{rental_agreement_id}/messages`

Todas as mensagens são vinculadas a uma análise, utilizando o id enviado no momento do envio da análise.

## Envio de Mensagem

Para que seja realizado o envio de uma mensagem, é necessário realizar a requisição utilizando o método POST no endpoint message, com uma payload que possui os seguintes campos:

| nome | tipo | descrição |
| ---- | :----: | --------- |
| author_document_number | string | CPF formatado de quem está enviando a mensagem |
| author_name | string | Nome de quem está enviando a mensagem |
| message | string | Mensagem sendo enviada |

Exemplo de payload para envio de uma mensagem:

```json
{
  "author_name": "John Sample",
  "author_document_number": "000.000.000-00",
  "message": "Alerta de fraude"
}
```

## Recebimento de Mensagens

Para que as mensagens possam ser exibidas para o atendente, basta realizar a recuperação das mensagens trocadas por meio do endpoint de GET. O endpoint pode receber um query parameter chamado `only_messages_to_show`, que ao receber o valor `true` retorna somente as mensagens que devem ser exibidas na tela do atendente.

Os dados do autor somente são devolvidos quando a mensagem foi produzida por um ser humano.

Retorno no endpoint de recuperação de mensagens:

```json
[
  {
    "author_name": "John Sample",
    "author_document_number": "000.000.000-00",
    "source": "analysis_screen",
    "message": "Análise finalizada",
    "message_date": "2019-11-05T13:34:12-03:00"
  },
  {...}
]
```

---

# Objetos Compartilhados

URL: /documentation/caas/car_rental/objects

Boa parte dos dados são compartilhados entre Reservation e RentalAgreement. Abaixo as definições destes objetos podem ser localizadas de maneira facilitada.

## Objeto *reservation*

```json
{
  "id": "0",
  "channel": "reservation_central",
  "reservation_date": "2020-03-31T08:15:00-03:00",
  "sales_channel" : "PARCERIA TELEFONICA"
}
```

O objeto *reservation* é utilizado no endpoint de *rental_agreement* para representar a reserva que deu origem ao aluguel que será analisado. Este campo é necessário para que um rental_agreement seja vinculado à reserva. Representada da seguinte maneira:

| nome | tipo | descrição |
| ---- | :----: | --------- |
| id | inteiro | Identificador da reserva que deu origem ao aluguel. |
| channel | enumerador | Canal pelo qual foi feito a reserva para este aluguel. |
| reservation_date | DateTime | Data e Hora com fuso-horário do momento em que ocorreu a reserva para este aluguel. |
| sales_channel | string | Canal de vendas pelo qual a reserva foi realizada (ex.: PARCERIA MASTERCARD) |

Existem os seguintes enumeradores para o campo *channel*: `walkin`, `reservation_central`, `app`, `website_mobile`, `website_desktop`, `partnerships` e `third_parties`.

## Objeto *car*

```json
{
  "model_group": "C",
  "upgrade_model_group": "SV",
  "group_description": "Sedan Médio 1.4",
  "rental_daily_price": 48496
}
```

O objeto *car* representa um veículo que está sendo reservado (endpoint de *reservation*) ou retirado (endpoint de *rental_agreement*). Os dados enviados são:

| nome | tipo | descrição |
| ---- | :----: | --------- |
| **model_group** | string | O grupo do veículo, em letras maiúsculas. *(obrigatório)* |
| upgrade_model_group | string | O grupo do veículo do upgrade, em letras maiúsculas. |
| group_description | string | Uma descrição do grupo do veículo |
| rental_daily_price | inteiro | O valor da diária cobrado |

## Objeto *client*

O objeto de *client* representa os dados referentes ao cliente que está fazendo a reserva ou retirada do veículo.

### Objeto *client (v1)*

O exemplo "v1" representa o payload de exemplo **antes da migração da scoragem principal para a reserva**. Tanto para reservas quanto para rental_agreements.

```json
{
  "type": "natural_person",
  "document_number": "123.456.789-00",
  "name": "John Sample",
  "gender": "female",
  "birthdate": "2001-01-15",
  "mother_name": "Mary Sample",
  "email": "john.sample@sample.com.br",
  "allowed_information_on_email": true,
  "face_picture": "c77d1925-0e72-4634-8393-395dbbce498d",
  "additional_pictures": [
    "718b8caa-8ef5-446c-b101-2dbf6c7e401f",
    "9c67f365-1427-4889-b963-d3729d437ff3",
    "8006f82c-3a80-4371-914e-e88c91507711",
    "42c6909e-51aa-4b6d-972f-f4684a047993",
    "b7a88947-96bd-4557-81e9-a69a3c84f428"
  ],
  "total_rents": 6,
  "fidelity_points": 1200,
  "documents": {
    "rg": {
      "document_number": "00000000",
      "issuer": "SSP"
    },
    "cnh": {
      "document_number": "000000000",
      "security_code": "00000",
      "first_issuance": "2015-07-20",
      "expiration_date": "2030-07-26",
      "state": "SP"
    }
  },
  "residential_address": {
    "street": "Av Brigadeiro Faria Lima",
    "number": "2391",
    "neighborhood": "Jardins",
    "city": "SÃO PAULO",
    "uf": "SP",
    "complement": "",
    "postal_code": "00000-000"
  },
  "commercial_address": {
    "street": "Av Brigadeiro Faria Lima",
    "number": "2391",
    "neighborhood": "Jardins",
    "city": "SÃO PAULO",
    "uf": "SP",
    "complement": "",
    "postal_code": "00000-000"
  },
  "phones": [
    {
      "international_dial_code": "55",
      "area_code": "11",
      "number": "00000-0000",
      "type": "mobile"
    },
    {
      "international_dial_code": "55",
      "area_code": "11",
      "number": "00000-0000",
      "type": "residential"
    }
  ]
}
```

| nome | tipo | descrição |
| ---- | :----: | --------- |
| **type** | enum | Enumerador que define tipo do cliente. *(obrigatório)* |
| **document_number** | string | O CPF ou Passaporte do cliente. *(obrigatório)* |
| **name** | string | O nome completo do cliente. *(obrigatório)* |
| **gender** | enum | O gênero do cliente. *(obrigatório)* |
| birthdate | date | Data de nascimento do cliente. |
| mother_name | string | O nome completo da mãe do cliente. |
| **email** | string | O email informado pelo cliente. *(obrigatório)* |
| **allowed_information_on_email** | booleano | Flag que indica se o cliente permitiu o envio de e-mails de marketing no momento do cadastro. *(obrigatório)* |
| face_picture | GUID | GUID da imagem previamente enviada cujo conteúdo é uma foto do rosto do cliente. |
| additional_pictures | List of GUIDs | Lista de GUIDs das imagens adicionais enviadas de rostos e documentos dos clientes. |
| total_rents | integer | Quantidade total de aluguéis do cliente. |
| fidelity_points | integer | Quantidade de pontos de fidelidade do cliente. |
| **documents** | *documents* | Objeto que contém o detalhamento dos documentos do cliente. *(obrigatório)* |
| residential_address | *address* | Endereço residencial do cliente. |
| commercial_address | *address* | Endereço comercial do cliente. |
| **phones** | List of *phone* | Lista com os telefones do cliente. *(obrigatório)* |

Existem os seguintes enumeradores para o campo *type*: `natural_person`, `legal_person`, `replacement`, `fleet`, `uber`, `enterprise` e `agencia`.

Existem os seguintes enumeradores para o campo *gender*: `male`, `female` e `undefined`.

### Objeto *client (v2)*

Esta seção diz respeito às informações necessárias para o fluxo de análise de fraude primariamente na reserva.

O exemplo do objeto de "client (v2)" representa o payload de exemplo **posterior à migração da scoragem principal para a reserva**. Tanto para reservas quanto para rental_agreements.

```json
{
  "type": "natural_person",
  "document_number": "123.456.789-00",
  "name": "John Sample",
  "gender": "female",
  "birthdate": "2001-01-15",
  "mother_name": "Mary Sample",
  "email": "john.sample@sample.com.br",
  "allowed_information_on_email": true,
  "face_picture": "c77d1925-0e72-4634-8393-395dbbce498d",
  "additional_pictures": [
    "718b8caa-8ef5-446c-b101-2dbf6c7e401f",
    "9c67f365-1427-4889-b963-d3729d437ff3",
    "8006f82c-3a80-4371-914e-e88c91507711",
    "42c6909e-51aa-4b6d-972f-f4684a047993",
    "b7a88947-96bd-4557-81e9-a69a3c84f428"
  ],
  "total_rents": 6,
  "fidelity_points": 1200,
  "documents": {
    "rg": {
      "document_number": "00000000",
      "issuer": "SSP"
    },
    "cnh": {
      "document_number": "000000000",
      "security_code": "00000",
      "first_issuance": "2015-07-20",
      "expiration_date": "2030-07-26",
      "state": "SP"
    }
  },
  "residential_address": {
    "street": "Av Brigadeiro Faria Lima",
    "number": "2391",
    "neighborhood": "Jardins",
    "city": "SÃO PAULO",
    "uf": "SP",
    "complement": "",
    "postal_code": "00000-000"
  },
  "commercial_address": {
    "street": "Av Brigadeiro Faria Lima",
    "number": "2391",
    "neighborhood": "Jardins",
    "city": "SÃO PAULO",
    "uf": "SP",
    "complement": "",
    "postal_code": "00000-000"
  },
  "phones": [
    {
      "international_dial_code": "55",
      "area_code": "11",
      "number": "00000-0000",
      "type": "mobile"
    },
    {
      "international_dial_code": "55",
      "area_code": "11",
      "number": "00000-0000",
      "type": "residential"
    }
  ]
}
```

| nome | tipo | descrição |
| ---- | :----: | --------- |
| **type** | enum | Enumerador que define tipo do cliente. - type esperados: "natural_person", "legal_person", "replacement", "fleet", "uber", "agencia", "uber_semanal" *(obrigatório)* |
| **document_number** | string | O CPF ou Passaporte do cliente. *(obrigatório)* |
| name | string | O nome completo do cliente. |
| **gender** | enum | O gênero do cliente. *(obrigatório)* |
| birthdate | date | Data de nascimento do cliente. |
| mother_name | string | O nome completo da mãe do cliente. |
| email | string | O email informado pelo cliente. |
| allowed_information_on_email | booleano | Flag que indica se o cliente permitiu o envio de e-mails de marketing no momento do cadastro. *(obrigatório)* |
| face_picture | GUID | GUID da imagem previamente enviada cujo conteúdo é uma foto do rosto do cliente. |
| additional_pictures | List of GUIDs | Lista de GUIDs das imagens adicionais enviadas de rostos e documentos dos clientes. |
| total_rents | integer | Quantidade total de aluguéis do cliente. |
| fidelity_points | integer | Quantidade de pontos de fidelidade do cliente. |
| **documents** | *documents* | Objeto que contém o detalhamento dos documentos do cliente. *(obrigatório)* |
| residential_address | *address* | Endereço residencial do cliente. |
| commercial_address | *address* | Endereço comercial do cliente. |
| **phones** | List of *phone* | Lista com os telefones do cliente. *(obrigatório)* |

Existem os seguintes enumeradores para o campo *type*: `natural_person`, `legal_person`, `replacement`, `fleet`, `uber`, `enterprise` e `agencia`.

Existem os seguintes enumeradores para o campo *gender*: `male`, `female` e `undefined`.

## Objeto *participant*

O objeto *participant* representa uma pessoa envolvida no aluguel que não é o locatário principal, isto é, um **motorista adicional** ou o **responsável financeiro**. É a definição utilizada tanto na lista `additional_drivers` quanto no campo `financial_manager` de um RentalAgreement.

Sua estrutura é a mesma do objeto *client*, de maneira que a mesma implementação de serialização pode ser reaproveitada.

:::note
Cada participante enviado passa pela mesma análise antifraude aplicada ao locatário principal, porém o resultado destas análises **não altera o fraud_status** do RentalAgreement.
:::

```json
{
  "type": "natural_person",
  "segment": "ota",
  "document_number": "987.654.321-00",
  "name": "Jane Sample",
  "gender": "female",
  "birthdate": "1998-05-22",
  "mother_name": "Mary Sample",
  "email": "jane.sample@sample.com.br",
  "allowed_information_on_email": true,
  "face_picture": "e3b0c442-98fc-1c14-9afb-f4c8996fb924",
  "additional_pictures": [
    "718b8caa-8ef5-446c-b101-2dbf6c7e401f"
  ],
  "total_rents": 2,
  "fidelity_points": 0,
  "documents": {
    "rg": {
      "document_number": "00000000",
      "issuer": "SSP"
    },
    "cnh": {
      "document_number": "000000000",
      "security_code": "00000",
      "first_issuance": "2018-03-10",
      "expiration_date": "2028-03-10",
      "state": "SP"
    }
  },
  "residential_address": {
    "street": "Av Brigadeiro Faria Lima",
    "number": "2391",
    "neighborhood": "Jardins",
    "city": "SÃO PAULO",
    "uf": "SP",
    "complement": "",
    "postal_code": "00000-000",
    "country": "BRA"
  },
  "phones": [
    {
      "international_dial_code": "55",
      "area_code": "11",
      "number": "00000-0000",
      "type": "mobile"
    }
  ]
}
```

| nome | tipo | descrição |
| ---- | :----: | --------- |
| **type** | enum | Enumerador que define o tipo do participante. *(obrigatório)* |
| segment | string | Segmento ao qual o participante pertence. |
| **document_number** | string | O CPF, CNPJ ou Passaporte do participante. *(obrigatório)* |
| **name** | string | O nome completo do participante. *(obrigatório)* |
| **gender** | enum | O gênero do participante. *(obrigatório)* |
| birthdate | date | Data de nascimento do participante. |
| mother_name | string | O nome completo da mãe do participante. |
| **email** | string | O email informado pelo participante. *(obrigatório)* |
| **allowed_information_on_email** | booleano | Flag que indica se o participante permitiu o envio de e-mails de marketing no momento do cadastro. *(obrigatório)* |
| face_picture | GUID | GUID da imagem previamente enviada cujo conteúdo é uma foto do rosto do participante. |
| additional_pictures | List of GUIDs | Lista de GUIDs das imagens adicionais enviadas de rostos e documentos do participante. |
| total_rents | integer | Quantidade total de aluguéis do participante. |
| fidelity_points | integer | Quantidade de pontos de fidelidade do participante. |
| **documents** | *documents* | Objeto que contém o detalhamento dos documentos do participante. *(obrigatório)* |
| residential_address | *address* | Endereço residencial do participante. |
| commercial_address | *address* | Endereço comercial do participante. |
| **phones** | List of *phone* | Lista com os telefones do participante. *(obrigatório)* |

Existem os seguintes enumeradores para o campo *type*: `natural_person`, `legal_person`, `replacement`, `fleet`, `uber`, `enterprise`, `agencia` e `uber_semanal`.

Existem os seguintes enumeradores para o campo *gender*: `male`, `female` e `undefined`.

## Objeto *billing*

```json
{
  "name": "Agência AAA",
  "document_number": "00.000.000/0001-00",
  "voucher_type":"ABCD75",
  "voucher_description": "Pagamento pela Agência"
}
```

O objeto *billing* é utilizado para representar quem é o responsável pelo pagamento do aluguel, e é representado da seguinte maneira:

| nome | tipo | descrição |
| ---- | :----: | --------- |
| name | string | Nome da pessoa ou empresa responsável pelo pagamento do aluguel. |
| document_number | string | CPF, CNPJ ou Passaporte da pessoa ou empresa responsável pelo pagamento do aluguel. |
| voucher_type | string | Código alfanumérico que representa o tipo do voucher utilizado. |
| voucher_description | string | Descrição do tipo de voucher utilizado. |

## Objeto *address*

```json
{
  "street": "Rua do Exemplo",
  "number": "111",
  "neighborhood": "Bairro do Teste",
  "city": "Aparecida de Goiânia",
  "uf": "GO",
  "complement": "",
  "postal_code": "00000-000"
}
```

O objeto *address* é utilizado para representar endereços em toda a API, endereços no território brasileiro são representados da seguinte maneira:

| nome | tipo | descrição |
| ---- | :----: | --------- |
| street | string | Rua do endereço, incluindo o logradouro, evitando, se possível, abreviações. |
| number | string | Número do imóvel, incluindo letras caso possua. |
| neighborhood | string | Bairro, sem abreviações. **e.g.: Santa Felicidade** |
| city | string | Nome completo da cidade, sem abreviações |
| uf | string | A unidade federativa, com duas letras maiúsculas. **e.g.: SP** |
| complement | string | Quaisquer complementos para localizar o imóvel. **e.g.: Apartamento 101, Conjunto 12** |
| postal_code | string | O código postal da localidade, contendo o hífen. |
| country | string | Código ISO 3166-1 alfa-3 do país do endereço. |

No caso dos endereços cujo país não seja Brasil ("BRA"), o postal_code e a unidade federativa poderão ser preenchidos livremente.

## Objeto *documents*

O objeto *documents* é utilizado para representar o detalhamento dos dados dos documentos informados pelo cliente. O objeto é representado da seguinte maneira:

| nome | tipo | descrição |
| ---- | :----: | --------- |
| rg | *rg* | Objeto que descreve as informações do RG do cliente. |
| cnh | *cnh* | Objeto que descreve as informações da CNH do cliente. |
| foreign_document | *foreign_document* | Objeto que descreve as informações do documento estrangeiro do cliente. |

## Objeto *rg*

O objeto *rg* é utilizado para representar o detalhamento dos dados do RG informados pelo cliente. O objeto é representado da seguinte maneira:

| nome | tipo | descrição |
| ---- | :----: | --------- |
| document_number | string | Número do RG do cliente. |
| issuer | string | Órgão emissor e estado de emissão do RG do cliente. |

## Objeto *cnh*

O objeto *cnh* é utilizado para representar o detalhamento dos dados da CNH informados pelo cliente. O objeto é representado da seguinte maneira:

| nome | tipo | descrição |
| ---- | :----: | --------- |
| document_number | string | Número de Registro da CNH do cliente. |
| security_code | string | Código de segurança da CNH do cliente. |
| first_issuance | date | Data da primeira emissão da CNH do cliente |
| expiration_date | string | Data de validade da CNH do cliente |
| state | string | Estado de emissão da CNH do cliente. |

## Objeto *foreign_document*

O objeto *foreign_document* é utilizado para representar o documento estrangeiro informado pelo cliente. O objeto é representado da seguinte maneira:

| nome | tipo | descrição |
| ---- | :----: | --------- |
| document_number | string | Número do documento estrangeiro do cliente. |
| document_type | enum | Tipo do documento estrangeiro. Aceita os valores `passport` e `other`. |
| issuer_country | string | Código ISO 3166-1 alfa-3 do país emissor do documento. |

## Objeto *phone*

```json
{
  "international_dial_code": "1",
  "area_code": "11",
  "number": "99999-9999",
  "type": "mobile"
}
```

Um objeto phone representa um número telefônico, dentro ou fora do Brasil e sua classificação. Para isso, os campos são:

| nome | tipo | descrição |
| ---- | :----: | --------- |
| **international_dial_code** | string | Código de discagem internacional, sem zero ou +, somente números. *(obrigatório)* |
| **area_code** | string | Código de área, sem zero, somente números. *(obrigatório)* |
| **number** | string | Número do telefone, sem o hífen. *(obrigatório)* |
| **type** | enum | Tipo de número: celular, residencial, comercial, etc. *(obrigatório)* |

Existem os seguintes enumeradores para tipo de telefone: `residential`, `commercial`, `mobile`.

## Objeto *coverage*

```json
{
  "description": "S/ PROTEÇÃO AMERICAN PLATINUM",
  "price": 0
}
```

Um objeto coverage está relacionado a uma cobertura contratada pelo locatário.

| nome | tipo | descrição |
| :----: | :----: | --------- |
| **description** | string | Descrição da cobertura contratada. *(obrigatório)* |
| **price** | integer | Preço diário da cobertura. *(obrigatório)* |

---

# Envio de Resultado Quiz

URL: /documentation/caas/car_rental/quiz

Para o envio do resultado Quiz, para que apareça na interface gráfica, o seguinte endpoint deve ser utilizado:

`POST https://api.caas.qitech.app/car_rental/rental_agreement/{rental_agreement_id}/quiz_result`

O resultado do quiz é vinculado a uma análise, utilizando o id enviado no momento do envio da análise.

## Envio do Quiz

Para que seja enviado o resultado do Quiz, é necessário realizar a requisição utilizando o método POST no endpoint quiz_result, com uma payload que possui os seguintes campos:

| nome | tipo | descrição |
| ---- | :----: | --------- |
| score | number | Valor numérico do score do Quiz |
| result_enum | string | Enumerador do resultado do quiz: `low_risk`, `medium_risk`, `high_risk` |
| result_description | string | Descrição do resultado do quiz: "Baixo Risco", "Médio Risco", "Alto Risco" e outros |

Exemplo de payload para envio do resultado do Quiz:

```json
{
  "score": 950,
  "result_enum": "low_risk",
  "result_description": "Baixo Risco"
}
```

---

# RentalAgreement-v1

URL: /documentation/caas/car_rental/rental_agreement

Ao realizar a retirada de um veículo na loja, o locatário dá início ao seu processo de anti-fraude. Os dados enviados deverão ser os dados finais, que não serão alterados. Isto é importante para garantir dois pontos:

- Consistência dos dados na base de dados do Antifraude
- Avaliação realista do risco

O processo de análise consiste em enviar um RentalAgreement no endpoint adequado e esperar a resposta. Existem oito resultados possíveis, devolvido na flag **fraud_status**:

| Resultado | Descrição |
| :---------: | --------- |
| Aprovado Automaticamente | Recomenda-se que este aluguel seja aprovado |
| Negado Automaticamente | Recomenda-se que este aluguel seja reprovado |
| Derivado para análise manual | Nossas regras ou modelos não estão confiantes da decisão e decidiram enviar este aluguel para a análise manual. |
| Aprovado Manualmente | Após análise manual, o analista escolheu aprovar o aluguel |
| Reprovado Manualmente | Após análise manual, o analista escolheu reprovar o aluguel |
| Desafiado Manualmente | Após análise manual, o analista retorna para a loja que a CNH e/ou Selfie estão incorretas e/ou com baixa qualidade |
| Pendente | As consultas estão demorando mais do que o esperado, este aluguel entrou em uma fila de análise automática e será respondido por meio de Webhook |
| Não analisado | A consulta foi enviada com a flag de análise falsa, o que significa que nossos sistemas não deverão retornar parecer |

### Dinâmica dos Status

Ao recuperar um objeto do tipo RentalAgreement os status estão disponíveis. Além dos status, um histórico de modificações também são retornados para que possa ser consultado no futuro. Estas modificações são entituladas events e possuem, além do novo status, as datas de modificação.

### Dinâmica dos Status - **car_status**

O status **car_status** relacionado a um RentalAgreement indica a situação do carro relacionado a este aluguel, isto é, se o carro foi devolvido ou não. Os seguintes enumeradores existem para este status:

- `rented`
- `returned`
- `recovered`
- `written_off`

### Dinâmica dos Status - **fraud_status**

O status **fraud_status** indica o status da decisão do motor de fraude e possui uma máquina de estados bastante simples:

- `created`
- `automatically_approved`
- `automatically_reproved`
- `in_manual_analysis`
- `manually_approved`
- `manually_reproved`
- `manually_challenged`
- `pending`
- `not_analyzed`

Além disso, o upgrade_status também possui os mesmos enumeradores.

### Motoristas adicionais e responsáveis financeiros

Além do locatário principal, enviado em `client`, um RentalAgreement pode carregar outras pessoas envolvidas no aluguel:

- **Motoristas adicionais** (`additional_drivers`): lista de pessoas autorizadas a conduzir o veículo além do locatário principal.
- **Responsável financeiro** (`financial_manager`): pessoa física ou jurídica indicada como responsável pelo pagamento do aluguel. Existe no máximo um responsável financeiro por aluguel.

Ambos os campos utilizam a definição do objeto *participant*, cuja estrutura é idêntica à do objeto *client*.

Cada participante enviado passa pelas **mesmas consultas e análises antifraude** aplicadas ao locatário principal, de maneira que estes dados também alimentam a base de dados do Antifraude. O resultado individual de cada participante é devolvido na resposta da análise, conforme descrito em [Enviar um RentalAgreement](#enviar-um-rentalagreement). No entanto, este resultado **não altera o fraud_status do RentalAgreement**, que continua sendo determinado pela avaliação do locatário principal.

Ambos os campos são opcionais e podem ser omitidos quando não houver participantes além do locatário principal.

## Definição do Objeto

```json
{
  "id": "bca6268e-918a-4658-9161-a10b00a631ab",
  "rental_agreement_code" : "12345678",
  "rental_agreement_date": "2020-03-31T10:30:00-03:00",
  "car_rental_estimated_final_date":  "2020-04-01T10:28:00-03:00",
  "reservation": {
    "id": "0",
    "channel": "reservation_central",
    "reservation_date": "2020-03-31T08:15:00-03:00",
    "sales_channel" : "PARCERIA TELEFONICA"
  },
  "rental_store": "SAOP",
  "rental_store_group": "GSP",
  "rental_store_type": "LOJA DE RUA",
  "devolution_store": "SAOP",
  "risky_antecedence": true,
  "car": {
    "model_group": "AM",
    "upgrade_model_group": "SV",
    "rental_daily_price" : 48496,
    "risky_model_group": true,
    "risky_upgrade_model_group": true
  },
  "client": {
    "type": "natural_person",
    "segment": "ota",
    "document_number": "123.456.789-00",
    "name": "John Sample",
    "gender": "female",
    "birthdate": "2001-01-15",
    "mother_name": "Mary Sample",
    "email": "john.sample@sample.com.br",
    "allowed_information_on_email": true,
    "face_picture": "c77d1925-0e72-4634-8393-395dbbce498d",
    "additional_pictures": [
      "718b8caa-8ef5-446c-b101-2dbf6c7e401f",
      "9c67f365-1427-4889-b963-d3729d437ff3",
      "8006f82c-3a80-4371-914e-e88c91507711",
      "42c6909e-51aa-4b6d-972f-f4684a047993",
      "b7a88947-96bd-4557-81e9-a69a3c84f428"
    ],
    "total_rents": 6,
    "fidelity_points": 1200,
    "documents": {
      "rg": {
        "document_number": "00000000",
        "issuer": "SSP"
      },
      "cnh": {
        "document_number": "000000000",
        "security_code": "00000",
        "first_issuance": "2015-07-20",
        "expiration_date": "2030-07-26",
        "state": "SP"
      }
    },
    "residential_address": {
      "street": "Av Brigadeiro Faria Lima",
      "number": "2391",
      "neighborhood": "Jardins",
      "city": "SÃO PAULO",
      "uf": "SP",
      "complement": "",
      "postal_code": "00000-000"
    },
    "commercial_address": {
      "street": "Av Brigadeiro Faria Lima",
      "number": "2391",
      "neighborhood": "Jardins",
      "city": "SÃO PAULO",
      "uf": "SP",
      "complement": "",
      "postal_code": "00000-000"
    },
    "phones": [
      {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "00000-0000",
        "type": "mobile"
      },
      {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "00000-0000",
        "type": "residential"
      }
    ]
  },
  "additional_drivers": [
    {
      "type": "natural_person",
      "document_number": "987.654.321-00",
      "name": "Jane Sample",
      "gender": "female",
      "email": "jane.sample@sample.com.br",
      "allowed_information_on_email": true,
      "face_picture": "e3b0c442-98fc-1c14-9afb-f4c8996fb924",
      "documents": {
        "cnh": {
          "document_number": "000000000",
          "security_code": "00000",
          "first_issuance": "2018-03-10",
          "expiration_date": "2028-03-10",
          "state": "SP"
        }
      },
      "phones": [
        {
          "international_dial_code": "55",
          "area_code": "11",
          "number": "00000-0000",
          "type": "mobile"
        }
      ]
    }
  ],
  "financial_manager": {
    "type": "legal_person",
    "document_number": "00.000.000/0001-00",
    "name": "Empresa Sample LTDA",
    "gender": "undefined",
    "email": "financeiro@sample.com.br",
    "allowed_information_on_email": false,
    "documents": {},
    "phones": [
      {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "00000-0000",
        "type": "commercial"
      }
    ]
  },
  "coverages": [
    {
      "description": "S/ PROTEÇÃO AMERICAN PLATINUM",
      "price": 0
    },
    {
      "description": "PROTEÇÃO OCUPANTES E TERCEIROS",
      "price": 1668
    }
  ],
  "billing": {
    "name": "Agência AAA",
    "document_number": "00.000.000/0001-00",
    "voucher_type": "ABCD75",
    "voucher_description": "Pagamento pela agência"
  },
  "fare_name": "Mensal",
  "rental_price": 43300,
  "extra_hours": 0,
  "extra_hours_price": 0,
  "discount": 0,
  "prepayment_discount": 100,
  "extra_kms": 0,
  "extra_kms_price": 0,
  "third_party_coverage_price": 1490,
  "coverage_price": 0,
  "additional_driver_price": 1000,
  "driver_service_price": 1000,
  "additional_expenses": 1000,
  "devolution_fee": 0,
  "administration_fee": 5374,
  "discount_partial_coverage": 50,
  "free_day_discount": 20000,
  "final_price": 50165,
  "pre_authorization_amount": 0,
  "coverage_deductible_amount": 0,
  "upgrade_reason": "granted"
}
```

Todas as trocas de informação de um RentalAgreement utilizam a seguinte definição para este objeto. Em alguns casos, para facilitar a implementação e diminuir o fluxo de dados entre as partes, algumas informações poderão ser omitidas.

| nome | tipo | descrição |
| :----: | :----: | --------- |
| **id** | string | Identificador da requisição de análise no sistema do cliente. **É essencial que este número seja único para cada aluguel.** *(obrigatório)* |
| **rental_agreement_code** | string | Identificador do RentalAgreement no sistema do cliente. *(obrigatório)* |
| **rental_agreement_date** | DateTime | Data e Hora com fuso-horário da retirada do veículo do aluguel que está ocorrendo. *(obrigatório)* |
| **car_rental_estimated_final_date** | DateTime | Data e Hora com fuso-horário de quando o carro deve ser resolvido. *(obrigatório)* |
| **reservation** | *reservation* | Objeto que carrega as propriedades da reserva que deu origem a esse aluguel. *(obrigatório)* |
| **rental_store** | *store* | Loja onde o carro está sendo retirado. *(obrigatório)* |
| rental_store_group | *store* | Filial da loja onde o carro está sendo retirado |
| rental_store_type | *store* | Tipo da loja onde o carro será retirado |
| **devolution_store** | *store* | Loja onde o carro será devolvido, pode ou não ser a mesma loja de retirada. *(obrigatório)* |
| **car** | *car* | Carro que está sendo retirado - é importante que este valor seja, de fato, o carro sendo retirado. *(obrigatório)* |
| **client** | *client* | Objeto que carrega as informações do cliente que está retirando o veículo. *(obrigatório)* |
| additional_drivers | List of *participant* | Lista com os motoristas adicionais autorizados a conduzir o veículo neste aluguel. |
| financial_manager | *participant* | Pessoa física ou jurídica indicada como responsável financeiro deste aluguel. |
| **coverages** | List of *coverage* | Lista de objetos coverage que descrevem as coberturas de seguro contratadas pelo cliente. *(obrigatório)* |
| **billing** | *billing* | Objeto que descreve os detalhes da pessoa ou empresa responsável pelo pagamento do aluguel. *(obrigatório)* |
| **rental_price** | integer | Preço do aluguel, em centavos. *(obrigatório)* |
| **extra_hours** | integer | Quantidade de horas extras contratadas. *(obrigatório)* |
| **extra_hours_price** | integer | Preço das horas extras contratadas, em centavos. *(obrigatório)* |
| **discount** | inteiro | Desconto concedido por quaisquer motivos, em centavos. *(obrigatório)* |
| **prepayment_discount** | inteiro | Desconto por pagamento antecipado. |
| **extra_kms** | integer | Quantidade de kilômetros extras contratados. *(obrigatório)* |
| **extra_kms_price** | integer | Preço de kilômetros extras contratados, em centavos. *(obrigatório)* |
| **third_party_coverage_price** | integer | Preço do seguro de terceiros, em centavos. *(obrigatório)* |
| **coverage_price** | integer | Preço do seguro contratado, em centavos. *(obrigatório)* |
| additional_driver_price | integer | Preço total do(s) motoristas adicionais contratados, em centavos. |
| driver_service_price | integer | Preço total do serviço de motorista contratado, em centavos. |
| additional_expenses | integer | Despesas adicionais, em centavos |
| **devolution_fee** | integer | Preço da taxa de devolução, em centavos. *(obrigatório)* |
| **administration_fee** | integer | Preço da taxa de administração, em centavos. *(obrigatório)* |
| **discount_partial_coverage** | integer | Desconto de proteção parcial, em centavos. |
| **free_day_discount** | integer | Desconto de Free Day, em centavos. |
| **final_price** | integer | Preço final do aluguel, em centavos. *(obrigatório)* |
| pre_authorization_amount | integer | Valor da pré-autorização, em centavos. |
| **coverage_deductible_amount** | integer | Valor dedutível da cobertura, em centavos. *(obrigatório)* |
| upgrade_reason | enum | Tipo de upgrade (Concedido ou Comprado) - Aceita os valores `granted` e `bought` respectivamente |

## Enviar um RentalAgreement

Exemplo de Request:

```json
{
  "id": "bca6268e-918a-4658-9161-a10b00a631ab",
  ...
}
```

Exemplo de Retorno:

```json
{
  "id": "bca6268e-918a-4658-9161-a10b00a631ab",
  "fraud_status": "automatically_approved",
  "financial_manager": {
    "fraud_status": "automatically_approved"
  },
  "additional_drivers": [
    {
      "id": "1111111",
      "fraud_status": "automatically_approved"
    }
  ],
  "pre_authorization_amount": 100000,
  "block_document_number": true,
  "upgrade_status": "automatically_approved",
  "highest_allowed_car_group": "SV",
  "score": 870
}
```

Caso o aluguel tenha sido enviado com motoristas adicionais e/ou responsável financeiro, o resultado individual da análise de cada um deles também é retornado:

| nome | tipo | descrição |
| ---- | :----: | --------- |
| financial_manager.fraud_status | enum | Resultado da análise antifraude do responsável financeiro. Utiliza os mesmos enumeradores do **fraud_status** do RentalAgreement. |
| additional_drivers[].id | string | Identificador do motorista adicional analisado. |
| additional_drivers[].fraud_status | enum | Resultado da análise antifraude daquele motorista adicional. Utiliza os mesmos enumeradores do **fraud_status** do RentalAgreement. |

:::note
Estes status são informativos e independentes: um motorista adicional ou responsável financeiro reprovado **não altera** o **fraud_status** do RentalAgreement. Cabe à locadora decidir o que fazer com o participante reprovado, como recusar a inclusão daquele motorista no aluguel.
:::

Para realizar a avaliação de um aluguel, basta enviar um objeto do tipo RentalAgreement ao seguinte endpoint com a flag setada adequadamente:

`POST https://api.caas.qitech.app/car_rental/rental_agreement?analyze=true`

Além do status do retorno, também é retornado, caso haja, o valor da pré autorização desejada. Caso nenhuma majoração de pré autorização seja identificada, o valor retornado é nulo e não deve ser utilizado.

O grupo máximo que pode ser fornecido naquele RA é disponibilizado na variável `highest_allowed_car_group`. Este valor é configurado na regra de avaliação do RA.

O parâmetro *analyze* existe para evitar que transações que não precisam ser analisadas passem pelos motores de fraude, sujando a base de dados. O valor padrão deste parâmetro é **true**, de maneira que somente alugueis que forem explícitamente retirados da análise não serão analisados.

## Atualizar o status de um RentalAgreement

Corpo da requisição - Na efetivação de um aluguel de um carro:

```json
{
  "car_status": "rented",
  "event_date": "2019-11-05T13:34:12-03:00"
}
```

Corpo da requisição - Na devolução sem incidentes de um carro:

```json
{
  "car_status": "returned",
  "event_date": "2019-11-05T13:34:12-03:00"
}
```

Corpo da requisição - Na devolução mediante recuperação por roubo:

```json
{
  "car_status": "recovered",
  "incident": "theft",
  "event_date": "2019-11-05T13:34:12-03:00"
}
```

Corpo da requisição - Write-off com fraude confirmada:

```json
{
  "car_status": "written_off",
  "incident": "misappropriation",
  "event_date": "2019-11-05T13:34:12-03:00"
}
```

Para garantir a retroalimentação das regras e do modelo de inteligência artificial implementado, é necessário informar ao sistema quando os carros são alugados, devolvidos, ou quando são jogados a perda por fraude. Para isso, requisições com o método PUT devem ser utilizadas, passando-se como referência o id enviado na criação do *rental_agreement*, autenticadas normalmente:

`PUT https://api.caas.qitech.app/car_rental/rental_agreement/{rental_agreement_id}`

Caso o novo status seja *written_off*, os seguintes valores podem ser utilizados no campo **incident**, enviado no body da requisição, que indica o tipo de incidente do aluguel:

| Enumerador | Descrição |
| --------- | ----------- |
| theft | RAs que sofreram um roubo |
| misappropriation | RAs que foram classificados como apropriação indébita |

## Atualizar o veículo de um RentalAgreement

Corpo da requisição - Atualização de um veículo no aluguel:

```json
{
  "car_plate": "ABC1B34",
  "car_model": "Chevrolet Onix",
  "model_group": "B",
  "event_date": "2020-10-15T13:34:12-03:00"
}
```

Para garantir a consistência entre as ocorrências de fraude e os aluguéis e garantir o retreinamento do modelo de score, é necessário informar ao sistema os dados de cada carro quando ele é atrelado ao aluguel. Para isso, requisições com o método POST devem ser utilizadas, passando-se como referência o id enviado na criação do *rental_agreement*, autenticadas normalmente:

`POST https://api.caas.qitech.app/car_rental/rental_agreement/{rental_agreement_id}/car`

No body da requisição devem ser enviados os dados do veículo que está sendo atrelado àquele aluguel:

| nome | tipo | descrição |
| ---- | :----: | --------- |
| car_plate | string | Placa do veículo. |
| car_model | string | Modelo do veículo, incluindo sua marca e modelo (ex.: Jeep Renegade). |
| model_group | string | O grupo do veículo, em letras maiúsculas. |
| event_date | DateTime | Data e Hora com fuso-horário do momento em que ocorreu a associação do carro ao aluguel. |

## Recuperar um RentalAgreement

A fim de recuperar um RentalAgreement específico, basta realizar uma requisição GET. O resultado retornado é o json mais atualizado do RentalAgreement em questão. Caso este identificador não esteja relacionado a nenhum objeto, o HTTP Status 404 é retornado.

`GET https://api.caas.qitech.app/car_rental/rental_agreements/{rental_agreement_id}`

```shell
curl "https://api.caas.qitech.app/car_rental/rental_agreements/{rental_agreement_id}"
  -H "Authorization: TESTETESTETESTE"
```

## Buscar RentalAgreements

Retorno - uma lista de objetos RentalAgreement:

```json
[
  {
    "id": "bca6268e-918a-4658-9161-a10b00a631ab",
    ...
  },
  {
    "id": "13a91409-9793-49b6-8583-9ba575075831",
    ...
  }
]
```

Caso seja necessário buscar um RentalAgreement, um GET com parâmetros de query poderá ser utilizado. O resultado retornado é um JSON que representa uma lista de RentalAgreements. Caso nenhum objeto seja encontrado com os parâmetros enviados, o HTTP Status 200 é retornado com uma lista vazia no corpo da resposta.

`GET https://api.caas.qitech.app/car_rental/rental_agreements?initial_date=2019-10-01&final_date=2019-10-05&page_number=2&page_rows=20`

Os seguintes parâmetros podem ser utilizados para buscar objetos de RentalAgreement:

| Parâmetro | Padrão | Descrição |
| --------- | ----------- | -------------- |
| initial_date | null | Primeira data que deve ser retornada a partir do campo rental_agreement_date |
| final_date | null | Última data que deve ser retornada a partir do campo rental_agreement_date |
| store_code | null | Código da loja de onde os resultados devem ser retornados |
| page_number | 1 | Número da página de resultados desejada |
| page_rows | 50 | Número de objetos máximo a ser retornados em uma consulta |

---

# RentalAgreement-v2

URL: /documentation/caas/car_rental/rental_agreement_v2

Esta seção diz respeito ao fluxo de análise de fraude com a scoragem principal ocorrendo na reserva.

Ao realizar a retirada de um veículo na loja, o locatário dá início ao seu processo de anti-fraude. Os dados enviados deverão ser os dados finais, que não serão alterados. Isto é importante para garantir dois pontos:

- Consistência dos dados na base de dados do Antifraude
- Avaliação realista do risco

O processo de análise consiste em enviar um RentalAgreement no endpoint adequado e esperar a resposta. Existem oito resultados possíveis, devolvido na flag **fraud_status**:

| Resultado | Descrição |
| :---------: | --------- |
| Aprovado Automaticamente | Recomenda-se que este aluguel seja aprovado |
| Negado Automaticamente | Recomenda-se que este aluguel seja reprovado |
| Derivado para análise manual | Nossas regras ou modelos não estão confiantes da decisão e decidiram enviar este aluguel para a análise manual. |
| Aprovado Manualmente | Após análise manual, o analista escolheu aprovar o aluguel |
| Reprovado Manualmente | Após análise manual, o analista escolheu reprovar o aluguel |
| Desafiado Manualmente | Após análise manual, o analista retorna para a loja que a CNH e/ou Selfie estão incorretas e/ou com baixa qualidade |
| Pendente | As consultas estão demorando mais do que o esperado, este aluguel entrou em uma fila de análise automática e será respondido por meio de Webhook |
| Não analisado | A consulta foi enviada com a flag de análise falsa, o que significa que nossos sistemas não deverão retornar parecer |

### Dinâmica dos Status

Ao recuperar um objeto do tipo RentalAgreement os status estão disponíveis. Além dos status, um histórico de modificações também são retornados para que possa ser consultado no futuro. Estas modificações são entituladas events e possuem, além do novo status, as datas de modificação.

### Dinâmica dos Status - **car_status**

O status **car_status** relacionado a um RentalAgreement indica a situação do carro relacionado a este aluguel, isto é, se o carro foi devolvido ou não. Os seguintes enumeradores existem para este status:

- `rented`
- `returned`
- `recovered`
- `written_off`

### Dinâmica dos Status - **fraud_status**

O status **fraud_status** indica o status da decisão do motor de fraude e possui uma máquina de estados bastante simples:

- `created`
- `automatically_approved`
- `automatically_reproved`
- `in_manual_analysis`
- `manually_approved`
- `manually_reproved`
- `manually_challenged`
- `pending`
- `not_analyzed`

Além disso, o upgrade_status também possui os mesmos enumeradores.

## Definição do Objeto

```json
{
  "id": "bca6268e-918a-4658-9161-a10b00a631ab",
  "rental_agreement_code" : "12345678",
  "rental_agreement_date": "2020-03-31T10:30:00-03:00",
  "car_rental_estimated_final_date":  "2020-04-01T10:28:00-03:00",
  "reservation": {
    "id": "0",
    "channel": "reservation_central",
    "reservation_date": "2020-03-31T08:15:00-03:00",
    "sales_channel" : "PARCERIA TELEFONICA"
  },
  "rental_store": "SAOP",
  "rental_store_group": "GSP",
  "rental_store_type": "LOJA DE RUA",
  "devolution_store": "SAOP",
  "risky_antecedence": true,
  "car": {
    "model_group": "AM",
    "upgrade_model_group": "SV",
    "rental_daily_price" : 48496,
    "risky_model_group": true,
    "risky_upgrade_model_group": true
  },
  "client": {
    "type": "natural_person",
    "segment": "ota",
    "document_number": "123.456.789-00",
    "name": "John Sample",
    "gender": "female",
    "birthdate": "2001-01-15",
    "mother_name": "Mary Sample",
    "email": "john.sample@sample.com.br",
    "allowed_information_on_email": true,
    "face_picture": "c77d1925-0e72-4634-8393-395dbbce498d",
    "additional_pictures": [
      "718b8caa-8ef5-446c-b101-2dbf6c7e401f",
      "9c67f365-1427-4889-b963-d3729d437ff3",
      "8006f82c-3a80-4371-914e-e88c91507711",
      "42c6909e-51aa-4b6d-972f-f4684a047993",
      "b7a88947-96bd-4557-81e9-a69a3c84f428"
    ],
    "total_rents": 6,
    "fidelity_points": 1200,
    "documents": {
      "rg": {
        "document_number": "00000000",
        "issuer": "SSP"
      },
      "cnh": {
        "document_number": "000000000",
        "security_code": "00000",
        "first_issuance": "2015-07-20",
        "expiration_date": "2030-07-26",
        "state": "SP"
      }
    },
    "residential_address": {
      "street": "Av Brigadeiro Faria Lima",
      "number": "2391",
      "neighborhood": "Jardins",
      "city": "SÃO PAULO",
      "uf": "SP",
      "complement": "",
      "postal_code": "00000-000"
    },
    "commercial_address": {
      "street": "Av Brigadeiro Faria Lima",
      "number": "2391",
      "neighborhood": "Jardins",
      "city": "SÃO PAULO",
      "uf": "SP",
      "complement": "",
      "postal_code": "00000-000"
    },
    "phones": [
      {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "00000-0000",
        "type": "mobile"
      },
      {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "00000-0000",
        "type": "residential"
      }
    ]
  },
  "coverages": [
    {
      "description": "S/ PROTEÇÃO AMERICAN PLATINUM",
      "price": 0
    },
    {
      "description": "PROTEÇÃO OCUPANTES E TERCEIROS",
      "price": 1668
    }
  ],
  "billing": {
    "name": "Agência AAA",
    "document_number": "00.000.000/0001-00",
    "voucher_type": "ABCD75",
    "voucher_description": "Pagamento pela agência"
  },
  "fare_name": "Mensal",
  "rental_price": 43300,
  "extra_hours": 0,
  "extra_hours_price": 0,
  "discount": 0,
  "prepayment_discount": 100,
  "extra_kms": 0,
  "extra_kms_price": 0,
  "third_party_coverage_price": 1490,
  "coverage_price": 0,
  "additional_driver_price": 1000,
  "driver_service_price": 1000,
  "additional_expenses": 1000,
  "devolution_fee": 0,
  "administration_fee": 5374,
  "discount_partial_coverage": 50,
  "free_day_discount": 20000,
  "final_price": 50165,
  "pre_authorization_amount": 0,
  "coverage_deductible_amount": 0,
  "upgrade_reason": "granted"
}
```

Todas as trocas de informação de um RentalAgreement utilizam a seguinte definição para este objeto. Em alguns casos, para facilitar a implementação e diminuir o fluxo de dados entre as partes, algumas informações poderão ser omitidas.

| nome | tipo | descrição |
| :----: | :----: | --------- |
| **id** | string | Identificador da requisição de análise no sistema do cliente. **É essencial que este número seja único para cada aluguel.** *(obrigatório)* |
| **rental_agreement_code** | string | Identificador do RentalAgreement no sistema do cliente. *(obrigatório)* |
| **rental_agreement_date** | DateTime | Data e Hora com fuso-horário da retirada do veículo do aluguel que está ocorrendo. *(obrigatório)* |
| **car_rental_estimated_final_date** | DateTime | Data e Hora com fuso-horário de quando o carro deve ser resolvido. *(obrigatório)* |
| **reservation** | *reservation* | Objeto que carrega as propriedades da reserva que deu origem a esse aluguel. *(obrigatório)* |
| **rental_store** | *store* | Loja onde o carro está sendo retirado. *(obrigatório)* |
| rental_store_group | *store* | Filial da loja onde o carro está sendo retirado |
| rental_store_type | *store* | Tipo da loja onde o carro será retirado |
| **devolution_store** | *store* | Loja onde o carro será devolvido, pode ou não ser a mesma loja de retirada. *(obrigatório)* |
| **car** | *car* | Carro que está sendo retirado - é importante que este valor seja, de fato, o carro sendo retirado. *(obrigatório)* |
| **client** | *client* | Objeto que carrega as informações do cliente que está retirando o veículo. *(obrigatório)* |
| **coverages** | List of *coverage* | Lista de objetos coverage que descrevem as coberturas de seguro contratadas pelo cliente. *(obrigatório)* |
| **billing** | *billing* | Objeto que descreve os detalhes da pessoa ou empresa responsável pelo pagamento do aluguel. *(obrigatório)* |
| **rental_price** | integer | Preço do aluguel, em centavos. *(obrigatório)* |
| **extra_hours** | integer | Quantidade de horas extras contratadas. *(obrigatório)* |
| **extra_hours_price** | integer | Preço das horas extras contratadas, em centavos. *(obrigatório)* |
| **discount** | inteiro | Desconto concedido por quaisquer motivos, em centavos. *(obrigatório)* |
| **prepayment_discount** | inteiro | Desconto por pagamento antecipado. |
| **extra_kms** | integer | Quantidade de kilômetros extras contratados. *(obrigatório)* |
| **extra_kms_price** | integer | Preço de kilômetros extras contratados, em centavos. *(obrigatório)* |
| **third_party_coverage_price** | integer | Preço do seguro de terceiros, em centavos. *(obrigatório)* |
| **coverage_price** | integer | Preço do seguro contratado, em centavos. *(obrigatório)* |
| additional_driver_price | integer | Preço total do(s) motoristas adicionais contratados, em centavos. |
| driver_service_price | integer | Preço total do serviço de motorista contratado, em centavos. |
| additional_expenses | integer | Despesas adicionais, em centavos |
| **devolution_fee** | integer | Preço da taxa de devolução, em centavos. *(obrigatório)* |
| **administration_fee** | integer | Preço da taxa de administração, em centavos. *(obrigatório)* |
| **discount_partial_coverage** | integer | Desconto de proteção parcial, em centavos. |
| **free_day_discount** | integer | Desconto de Free Day, em centavos. |
| **final_price** | integer | Preço final do aluguel, em centavos. *(obrigatório)* |
| pre_authorization_amount | integer | Valor da pré-autorização, em centavos. |
| **coverage_deductible_amount** | integer | Valor dedutível da cobertura, em centavos. *(obrigatório)* |
| upgrade_reason | enum | Tipo de upgrade (Concedido ou Comprado) - Aceita os valores `granted` e `bought` respectivamente |

## Enviar um RentalAgreement

Exemplo de Request:

```json
{
  "id": "bca6268e-918a-4658-9161-a10b00a631ab",
  ...
}
```

Exemplo de Retorno:

```json
{
  "id": "bca6268e-918a-4658-9161-a10b00a631ab",
  "fraud_status": "automatically_approved",
  "pre_authorization_amount": 100000,
  "block_document_number": true,
  "upgrade_status": "automatically_approved",
  "highest_allowed_car_group": "SV",
  "score": 870
}
```

Para realizar a avaliação de um aluguel, basta enviar um objeto do tipo RentalAgreement ao seguinte endpoint com a flag setada adequadamente:

`POST https://api.caas.qitech.app/car_rental/rental_agreement?analyze=true`

Além do status do retorno, também é retornado, caso haja, o valor da pré autorização desejada. Caso nenhuma majoração de pré autorização seja identificada, o valor retornado é nulo e não deve ser utilizado.

O grupo máximo que pode ser fornecido naquele RA é disponibilizado na variável `highest_allowed_car_group`. Este valor é configurado na regra de avaliação do RA.

O parâmetro *analyze* existe para evitar que transações que não precisam ser analisadas passem pelos motores de fraude, sujando a base de dados. O valor padrão deste parâmetro é **true**, de maneira que somente alugueis que forem explícitamente retirados da análise não serão analisados.

## Atualizar o status de um RentalAgreement

Corpo da requisição - Na efetivação de um aluguel de um carro:

```json
{
  "car_status": "rented",
  "event_date": "2019-11-05T13:34:12-03:00"
}
```

Corpo da requisição - Na devolução sem incidentes de um carro:

```json
{
  "car_status": "returned",
  "event_date": "2019-11-05T13:34:12-03:00"
}
```

Corpo da requisição - Na devolução mediante recuperação por roubo:

```json
{
  "car_status": "recovered",
  "incident": "theft",
  "event_date": "2019-11-05T13:34:12-03:00"
}
```

Corpo da requisição - Write-off com fraude confirmada:

```json
{
  "car_status": "written_off",
  "incident": "misappropriation",
  "event_date": "2019-11-05T13:34:12-03:00"
}
```

Para garantir a retroalimentação das regras e do modelo de inteligência artificial implementado, é necessário informar ao sistema quando os carros são alugados, devolvidos, ou quando são jogados a perda por fraude. Para isso, requisições com o método PUT devem ser utilizadas, passando-se como referência o id enviado na criação do *rental_agreement*, autenticadas normalmente:

`PUT https://api.caas.qitech.app/car_rental/rental_agreement/{rental_agreement_id}`

Caso o novo status seja *written_off*, os seguintes valores podem ser utilizados no campo **incident**, enviado no body da requisição, que indica o tipo de incidente do aluguel:

| Enumerador | Descrição |
| --------- | ----------- |
| theft | RAs que sofreram um roubo |
| misappropriation | RAs que foram classificados como apropriação indébita |

## Atualizar o veículo de um RentalAgreement

Corpo da requisição - Atualização de um veículo no aluguel:

```json
{
  "car_plate": "ABC1B34",
  "car_model": "Chevrolet Onix",
  "model_group": "B",
  "event_date": "2020-10-15T13:34:12-03:00"
}
```

Para garantir a consistência entre as ocorrências de fraude e os aluguéis e garantir o retreinamento do modelo de score, é necessário informar ao sistema os dados de cada carro quando ele é atrelado ao aluguel. Para isso, requisições com o método POST devem ser utilizadas, passando-se como referência o id enviado na criação do *rental_agreement*, autenticadas normalmente:

`POST https://api.caas.qitech.app/car_rental/rental_agreement/{rental_agreement_id}/car`

No body da requisição devem ser enviados os dados do veículo que está sendo atrelado àquele aluguel:

| nome | tipo | descrição |
| ---- | :----: | --------- |
| car_plate | string | Placa do veículo. |
| car_model | string | Modelo do veículo, incluindo sua marca e modelo (ex.: Jeep Renegade). |
| model_group | string | O grupo do veículo, em letras maiúsculas. |
| event_date | DateTime | Data e Hora com fuso-horário do momento em que ocorreu a associação do carro ao aluguel. |

## Recuperar um RentalAgreement

A fim de recuperar um RentalAgreement específico, basta realizar uma requisição GET. O resultado retornado é o json mais atualizado do RentalAgreement em questão. Caso este identificador não esteja relacionado a nenhum objeto, o HTTP Status 404 é retornado.

`GET https://api.caas.qitech.app/car_rental/rental_agreements/{rental_agreement_id}`

```shell
curl "https://api.caas.qitech.app/car_rental/rental_agreements/{rental_agreement_id}"
  -H "Authorization: TESTETESTETESTE"
```

## Buscar RentalAgreements

Retorno - uma lista de objetos RentalAgreement:

```json
[
  {
    "id": "bca6268e-918a-4658-9161-a10b00a631ab",
    ...
  },
  {
    "id": "13a91409-9793-49b6-8583-9ba575075831",
    ...
  }
]
```

Caso seja necessário buscar um RentalAgreement, um GET com parâmetros de query poderá ser utilizado. O resultado retornado é um JSON que representa uma lista de RentalAgreements. Caso nenhum objeto seja encontrado com os parâmetros enviados, o HTTP Status 200 é retornado com uma lista vazia no corpo da resposta.

`GET https://api.caas.qitech.app/car_rental/rental_agreements?initial_date=2019-10-01&final_date=2019-10-05&page_number=2&page_rows=20`

Os seguintes parâmetros podem ser utilizados para buscar objetos de RentalAgreement:

| Parâmetro | Padrão | Descrição |
| --------- | ----------- | -------------- |
| initial_date | null | Primeira data que deve ser retornada a partir do campo rental_agreement_date |
| final_date | null | Última data que deve ser retornada a partir do campo rental_agreement_date |
| store_code | null | Código da loja de onde os resultados devem ser retornados |
| page_number | 1 | Número da página de resultados desejada |
| page_rows | 50 | Número de objetos máximo a ser retornados em uma consulta |

---

# Reservation-v1

URL: /documentation/caas/car_rental/reservation

Ao realizar a reserva de um veículo, o locatário dá início ao seu processo de anti-fraude. Os dados enviados deverão ser os dados finais da reserva, que não serão alterados. Isto é importante para garantir dois pontos:

- Consistência dos dados na base de dados do Antifraude
- Avaliação realista do risco

O processo de análise consiste em enviar uma Reservation no endpoint adequado e esperar a resposta. Existem oito resultados possíveis, devolvido na flag **fraud_status**:

| Resultado | Descrição |
| :---------: | --------- |
| Aprovado Automaticamente | Recomenda-se que este aluguel seja aprovado |
| Negado Automaticamente | Recomenda-se que este aluguel seja reprovado |
| Derivado para análise manual | Nossas regras ou modelos não estão confiantes da decisão e decidiram enviar este aluguel para a análise manual. |
| Aprovado Manualmente | Após análise manual, o analista escolheu aprovar o aluguel |
| Reprovado Manualmente | Após análise manual, o analista escolheu reprovar o aluguel |
| Desafiado Manualmente | Após análise manual, o analista retorna para a loja que a CNH e/ou Selfie estão incorretas e/ou com baixa qualidade |
| Pendente | As consultas estão demorando mais do que o esperado, este aluguel entrou em uma fila de análise automática e será respondido por meio de Webhook |
| Não analisado | A consulta foi enviada com a flag de análise falsa, o que significa que nossos sistemas não deverão retornar parecer |

### Dinâmica dos Status

Ao recuperar um objeto do tipo Reservation os status estão disponíveis. Além dos status, um histórico de modificações também são retornados para que possa ser consultado no futuro. Estas modificações são entituladas events e possuem, além do novo status, as datas de modificação.

### Dinâmica dos Status - **fraud_status**

O status **fraud_status** indica o status da decisão do motor de fraude e possui uma máquina de estados bastante simples:

- `created`
- `automatically_approved`
- `automatically_reproved`
- `in_manual_analysis`
- `manually_approved`
- `manually_reproved`
- `pending`
- `not_analyzed`

## Definição do Objeto

```json
{
  "id": "bca6268e-918a-4658-9161-a10b00a631ab",
  "reservation_code": "211034324",
  "reservation_date": "2020-03-31T08:15:00-03:00",
  "rental_agreement_date": "2020-03-31T10:30:00-03:00",
  "car_rental_estimated_final_date":  "2020-04-01T10:28:00-03:00",
  "channel": "reservation_central",
  "sales_channel" : "PARCERIA TELEFONICA",
  "rental_store": "SAOP",
  "rental_store_group": "GSP",
  "rental_store_type": "LOJA DE RUA",
  "devolution_store": "SAOP",
  "car": {
    "model_group": "SV",
    "rental_daily_price" : 48496
  },
  "client": {
    "type": "natural_person",
    "segment": "ota",
    "document_number": "123.456.789-00",
    "name": "John Sample",
    "gender": "female",
    "birthdate": "2001-01-15",
    "mother_name": "Mary Sample",
    "email": "john.sample@sample.com.br",
    "allowed_information_on_email": true,
    "face_picture": "c77d1925-0e72-4634-8393-395dbbce498d",
    "additional_pictures": [
      "718b8caa-8ef5-446c-b101-2dbf6c7e401f",
      "9c67f365-1427-4889-b963-d3729d437ff3",
      "8006f82c-3a80-4371-914e-e88c91507711",
      "42c6909e-51aa-4b6d-972f-f4684a047993",
      "b7a88947-96bd-4557-81e9-a69a3c84f428"
    ],
    "documents": {
      "rg": {
        "document_number": "00000000",
        "issuer": "SSP"
      },
      "cnh": {
        "document_number": "000000000",
        "security_code": "00000",
        "first_issuance": "2015-07-20",
        "expiration_date": "2030-07-26",
        "state": "SP"
      }
    },
    "residential_address": {
      "street": "Av Brigadeiro Faria Lima",
      "number": "2391",
      "neighborhood": "Jardins",
      "city": "SÃO PAULO",
      "uf": "SP",
      "complement": "",
      "postal_code": "00000-000"
    },
    "commercial_address": {
      "street": "Av Brigadeiro Faria Lima",
      "number": "2391",
      "neighborhood": "Jardins",
      "city": "SÃO PAULO",
      "uf": "SP",
      "complement": "",
      "postal_code": "00000-000"
    },
    "phones": [
      {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "00000-0000",
        "type": "mobile"
      },
      {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "00000-0000",
        "type": "residential"
      }
    ]
  },
  "coverages": [
    {
      "description": "S/ PROTEÇÃO AMERICAN PLATINUM",
      "price": 0
    },
    {
      "description": "PROTEÇÃO OCUPANTES E TERCEIROS",
      "price": 1668
    }
  ],
  "billing": {
    "name": "Agência AAA",
    "document_number": "00.000.000/0001-00",
    "voucher_type": "ABCD75",
    "voucher_description": "Pagamento pela agência"
  },
  "rental_price": 43300,
  "extra_hours": 0,
  "extra_hours_price": 0,
  "discount": 0,
  "prepayment_discount": 100,
  "extra_kms": 0,
  "extra_kms_price": 0,
  "third_party_coverage_price": 1490,
  "coverage_price": 0,
  "additional_driver_price": 1000,
  "driver_service_price": 1000,
  "additional_expenses": 1000,
  "devolution_fee": 0,
  "administration_fee": 5374,
  "discount_partial_coverage": 50,
  "final_price": 50165,
  "pre_authorization_amount": 0,
  "coverage_deductible_amount": 0
}
```

Todas as trocas de informação de uma Reservation utilizam a seguinte definição para este objeto. Em alguns casos, para facilitar a implementação e diminuir o fluxo de dados entre as partes, algumas informações poderão ser omitidas.

| nome | tipo | descrição |
| :----: | :----: | --------- |
| **id** | string | Identificador da requisição de análise no sistema do cliente. **É essencial que este número seja único para cada análise.** *(obrigatório)* |
| reservation_code | string | Identificador da Reserva no sistema do cliente. - Este campo é opcional e pode ser definido utilizando o método PUT |
| **reservation_date** | DateTime | Data e Hora com fuso-horário do momento em que ocorreu a reserva para este aluguel. *(obrigatório)* |
| **rental_agreement_date** | DateTime | Data e Hora com fuso-horário da retirada do veículo do aluguel. *(obrigatório)* |
| **car_rental_estimated_final_date** | DateTime | Data e Hora com fuso-horário de quando o carro deve ser resolvido. *(obrigatório)* |
| **rental_store** | *store* | Loja onde o carro será retirado. *(obrigatório)* |
| rental_store_group | *store* | Filial da loja onde o carro será retirado |
| rental_store_type | *store* | Tipo da loja onde o carro será retirado |
| **devolution_store** | *store* | Loja onde o carro será devolvido, pode ou não ser a mesma loja de retirada. *(obrigatório)* |
| reservation_channel | string | Canal pelo qual foi feito a reserva para este aluguel. |
| **sales_channel** | string | Canal de vendas pelo qual a reserva foi realizada (ex.: PARCERIA MASTERCARD). *(obrigatório)* |
| **car** | *car* | Carro que será retirado. *(obrigatório)* |
| **client** | *client* | Objeto que carrega as informações do cliente que fará a retirada do veículo. *(obrigatório)* |
| **coverages** | List of *coverage* | Lista de objetos coverage que descrevem as coberturas de seguro contratadas pelo cliente. *(obrigatório)* |
| billing | *billing* | Objeto que descreve os detalhes da pessoa ou empresa responsável pelo pagamento do aluguel. |
| **rental_price** | integer | Preço do aluguel, em centavos. *(obrigatório)* |
| **extra_hours** | integer | Quantidade de horas extras contratadas. *(obrigatório)* |
| **extra_hours_price** | integer | Preço das horas extras contratadas, em centavos. *(obrigatório)* |
| **discount** | inteiro | Desconto concedido por quaisquer motivos, em centavos. *(obrigatório)* |
| **prepayment_discount** | inteiro | Desconto por pagamento antecipado. *(obrigatório)* |
| **extra_kms** | integer | Quantidade de kilômetros extras contratados. *(obrigatório)* |
| **extra_kms_price** | integer | Preço de kilômetros extras contratados, em centavos. *(obrigatório)* |
| **third_party_coverage_price** | integer | Preço do seguro de terceiros, em centavos. *(obrigatório)* |
| coverage_price | integer | Preço do seguro contratado, em centavos. |
| **additional_driver_price** | integer | Preço total do(s) motoristas adicionais contratados, em centavos. *(obrigatório)* |
| **driver_service_price** | integer | Preço total do serviço de motorista contratado, em centavos. *(obrigatório)* |
| **additional_expenses** | integer | Despesas adicionais, em centavos. *(obrigatório)* |
| **devolution_fee** | integer | Preço da taxa de devolução, em centavos. *(obrigatório)* |
| **administration_fee** | integer | Preço da taxa de administração, em centavos. *(obrigatório)* |
| **discount_partial_coverage** | integer | Desconto de proteção parcial, em centavos. *(obrigatório)* |
| **final_price** | integer | Preço final do aluguel, em centavos. *(obrigatório)* |
| **pre_authorization_amount** | integer | Valor da pré-autorização, em centavos. *(obrigatório)* |
| **coverage_deductible_amount** | integer | Valor dedutível da cobertura, em centavos. *(obrigatório)* |

## Enviar uma Reserva

Exemplo de Request:

```json
{
  "id": "bca6268e-918a-4658-9161-a10b00a631ab",
  ...
}
```

Exemplo de Retorno:

```json
{
  "reservation_key": "bca6268e-918a-4658-9161-a10b00a631ab",
  "fraud_status": "automatically_approved",
  "pre_authorization_amount": 10000
}
```

Para realizar a avaliação de uma reserva, basta enviar um objeto do tipo Reservation ao seguinte endpoint:

`POST https://api.caas.qitech.app/car_rental/reservation`

Além do status do retorno, também é retornado, caso haja, o valor da pré autorização desejada. Caso nenhuma majoração de pré autorização seja identificada, o valor retornado é nulo e não deve ser utilizado.

## Definir o código de uma Reserva

A QI Tech possibilita a definição do código da reserva após a análise inicial. Isto é útil em alguns fluxos operacionais. Nestes casos, basta realizar um PUT no endpoint a seguir, com o código da reserva definido no corpo:

`PUT https://api.caas.qitech.app/car_rental/reservation/{reservation_id}`

:::note
Caso o código da reserva tenha sido definido anteriormente, na requisição de POST ou utilizando um PUT, não é possível redefinir o código da reserva. Neste caso, a API retornará 409 - Conflito.
:::

```json
{
  "reservation_code": "123456789"
}
```

## Recuperar uma Reserva

A fim de recuperar uma Reserva específica, basta realizar uma requisição GET. O resultado retornado é o json mais atualizado da Reserva em questão. Caso este identificador não esteja relacionado a nenhum objeto, o HTTP Status 404 é retornado.

`GET https://api.caas.qitech.app/car_rental/reservation/{reservation_id}`

```shell
curl "https://api.caas.qitech.app/car_rental/reservation/{reservation_id}"
  -H "Authorization: TESTETESTETESTE"
```

---

# Reservation-v2

URL: /documentation/caas/car_rental/reservation_v2

Esta seção diz respeito às informações necessárias para o fluxo de análise de fraude primariamente na reserva.

Ao realizar a reserva de um veículo, o locatário dá início ao seu processo de anti-fraude. Os dados enviados deverão ser os dados finais da reserva, que não serão alterados. Isto é importante para garantir dois pontos:

- Consistência dos dados na base de dados do Antifraude
- Avaliação realista do risco

O processo de análise consiste em enviar uma Reservation no endpoint adequado e esperar a resposta. Existem oito resultados possíveis, devolvido na flag **fraud_status**:

| Resultado | Descrição |
| :---------: | --------- |
| Aprovado Automaticamente | Recomenda-se que este aluguel seja aprovado |
| Negado Automaticamente | Recomenda-se que este aluguel seja reprovado |
| Derivado para análise manual | Nossas regras ou modelos não estão confiantes da decisão e decidiram enviar este aluguel para a análise manual. |
| Aprovado Manualmente | Após análise manual, o analista escolheu aprovar o aluguel |
| Reprovado Manualmente | Após análise manual, o analista escolheu reprovar o aluguel |
| Desafiado Manualmente | Após análise manual, o analista retorna para a loja que a CNH e/ou Selfie estão incorretas e/ou com baixa qualidade |
| Pendente | As consultas estão demorando mais do que o esperado, este aluguel entrou em uma fila de análise automática e será respondido por meio de Webhook |
| Não analisado | A consulta foi enviada com a flag de análise falsa, o que significa que nossos sistemas não deverão retornar parecer |

### Dinâmica dos Status

Ao recuperar um objeto do tipo Reservation os status estão disponíveis. Além dos status, um histórico de modificações também são retornados para que possa ser consultado no futuro. Estas modificações são entituladas events e possuem, além do novo status, as datas de modificação.

### Dinâmica dos Status - **fraud_status**

O status **fraud_status** indica o status da decisão do motor de fraude e possui uma máquina de estados bastante simples:

- `created`
- `automatically_approved`
- `automatically_reproved`
- `in_manual_analysis`
- `manually_approved`
- `manually_reproved`
- `pending`
- `not_analyzed`

## Definição do Objeto

```json
{
  "id": "bca6268e-918a-4658-9161-a10b00a631ab",
  "reservation_code": "211034324",
  "reservation_date": "2024-03-19T10:30:00-03:00",
  "rental_agreement_date": "2024-03-25T10:30:00-03:00",
  "car_rental_estimated_final_date":  "2024-03-30T10:28:00-03:00",
  "channel": "reservation_central",
  "sales_channel" : "PARCERIA TELEFONICA",
  "rental_store": "SAOP",
  "rental_store_group": "GSP",
  "rental_store_type": "LOJA DE RUA",
  "devolution_store": "SAOP",
  "risky_antecedence": true,
  "car": {
    "model_group": "SV",
    "rental_daily_price" : 48496
  },
  "client": {
    "type": "natural_person",
    "segment": "ota",
    "document_number": "123.456.789-00",
    "name": "John Sample",
    "gender": "female",
    "birthdate": "2001-01-15",
    "mother_name": "Mary Sample",
    "email": "john.sample@sample.com.br",
    "allowed_information_on_email": true,
    "face_picture": "c77d1925-0e72-4634-8393-395dbbce498d",
    "additional_pictures": [
      "718b8caa-8ef5-446c-b101-2dbf6c7e401f",
      "9c67f365-1427-4889-b963-d3729d437ff3",
      "8006f82c-3a80-4371-914e-e88c91507711",
      "42c6909e-51aa-4b6d-972f-f4684a047993",
      "b7a88947-96bd-4557-81e9-a69a3c84f428"
    ],
    "total_rents": 6,
    "fidelity_points": 1200,
    "documents": {
      "rg": {
        "document_number": "00000000",
        "issuer": "SSP"
      },
      "cnh": {
        "document_number": "000000000",
        "security_code": "00000",
        "first_issuance": "2015-07-20",
        "expiration_date": "2030-07-26",
        "state": "SP"
      }
    },
    "residential_address": {
      "street": "Av Brigadeiro Faria Lima",
      "number": "2391",
      "neighborhood": "Jardins",
      "city": "SÃO PAULO",
      "uf": "SP",
      "complement": "",
      "postal_code": "00000-000"
    },
    "commercial_address": {
      "street": "Av Brigadeiro Faria Lima",
      "number": "2391",
      "neighborhood": "Jardins",
      "city": "SÃO PAULO",
      "uf": "SP",
      "complement": "",
      "postal_code": "00000-000"
    },
    "phones": [
      {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "00000-0000",
        "type": "mobile"
      },
      {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "00000-0000",
        "type": "residential"
      }
    ]
  },
  "coverages": [
    {
      "description": "S/ PROTEÇÃO AMERICAN PLATINUM",
      "price": 0
    },
    {
      "description": "PROTEÇÃO OCUPANTES E TERCEIROS",
      "price": 1668
    }
  ],
  "billing": {
    "name": "Agência AAA",
    "document_number": "00.000.000/0001-00",
    "voucher_type": "ABCD75",
    "voucher_description": "Pagamento pela agência"
  },
  "fare_name": "MENSAL - 2000KM - PRÓ-RATA",
  "rental_price": 43300,
  "extra_hours": 0,
  "extra_hours_price": 0,
  "discount": 0,
  "prepayment_discount": 100,
  "extra_kms": 0,
  "extra_kms_price": 0,
  "third_party_coverage_price": 1490,
  "coverage_price": 0,
  "additional_driver_price": 1000,
  "driver_service_price": 1000,
  "additional_expenses": 1000,
  "devolution_fee": 0,
  "administration_fee": 5374,
  "discount_partial_coverage": 50,
  "final_price": 50165,
  "pre_authorization_amount": 0,
  "coverage_deductible_amount": 0
}
```

Todas as trocas de informação de uma Reservation utilizam a seguinte definição para este objeto. Em alguns casos, para facilitar a implementação e diminuir o fluxo de dados entre as partes, algumas informações poderão ser omitidas.

| nome | tipo | descrição |
| :----: | :----: | --------- |
| **id** | string | Identificador da requisição de análise no sistema do cliente. **É essencial que este número seja único para cada análise.** *(obrigatório)* |
| reservation_code | string | Identificador da Reserva no sistema do cliente. - Este campo é opcional e pode ser definido utilizando o método PUT. |
| **reservation_date** | DateTime | Data e Hora com fuso-horário do momento em que ocorreu a reserva para este aluguel. *(obrigatório)* |
| **car_rental_estimated_final_date** | DateTime | Data e Hora com fuso-horário de quando o carro deve ser resolvido. *(obrigatório)* |
| **rental_store** | *store* | Loja onde o carro será retirado. *(obrigatório)* |
| rental_store_group | *store* | Filial da loja onde o carro será retirado |
| rental_store_type | *store* | Tipo da loja onde o carro será retirado |
| **devolution_store** | *store* | Loja onde o carro será devolvido, pode ou não ser a mesma loja de retirada. *(obrigatório)* |
| reservation_channel | string | Canal pelo qual foi feito a reserva para este aluguel. |
| **sales_channel** | string | Canal de vendas pelo qual a reserva foi realizada (ex.: PARCERIA MASTERCARD). *(obrigatório)* |
| **car** | *car* | Objeto que carrega as informações do veículo sendo reservado. *(obrigatório)* |
| **client** | *client* | Objeto que carrega as informações do cliente que fará a retirada do veículo. *(obrigatório)* |
| **coverages** | List of *coverage* | Lista de objetos coverage que descrevem as coberturas de seguro contratadas pelo cliente. *(obrigatório)* |
| **billing** | *billing* | Objeto que descreve os detalhes da pessoa ou empresa responsável pelo pagamento do aluguel. *(obrigatório)* |
| **rental_price** | integer | Preço do aluguel, em centavos. *(obrigatório)* |
| **extra_hours** | integer | Quantidade de horas extras contratadas. *(obrigatório)* |
| **extra_hours_price** | integer | Preço das horas extras contratadas, em centavos. *(obrigatório)* |
| **discount** | inteiro | Desconto concedido por quaisquer motivos, em centavos. *(obrigatório)* |
| **prepayment_discount** | inteiro | Desconto por pagamento antecipado. *(obrigatório)* |
| **extra_kms** | integer | Quantidade de kilômetros extras contratados. *(obrigatório)* |
| **extra_kms_price** | integer | Preço de kilômetros extras contratados, em centavos. *(obrigatório)* |
| **third_party_coverage_price** | integer | Preço do seguro de terceiros, em centavos. *(obrigatório)* |
| coverage_price | integer | Preço do seguro contratado, em centavos. |
| **additional_driver_price** | integer | Preço total do(s) motoristas adicionais contratados, em centavos. *(obrigatório)* |
| **driver_service_price** | integer | Preço total do serviço de motorista contratado, em centavos. *(obrigatório)* |
| **additional_expenses** | integer | Despesas adicionais, em centavos. *(obrigatório)* |
| **devolution_fee** | integer | Preço da taxa de devolução, em centavos. *(obrigatório)* |
| **administration_fee** | integer | Preço da taxa de administração, em centavos. *(obrigatório)* |
| **discount_partial_coverage** | integer | Desconto de proteção parcial, em centavos. *(obrigatório)* |
| **final_price** | integer | Preço final do aluguel, em centavos. *(obrigatório)* |
| **pre_authorization_amount** | integer | Valor da pré-autorização, em centavos. *(obrigatório)* |
| **coverage_deductible_amount** | integer | Valor dedutível da cobertura, em centavos. *(obrigatório)* |

## Enviar uma Reserva

Exemplo de Request:

```json
{
  "id": "bca6268e-918a-4658-9161-a10b00a631ab",
  "reservation_code": "211034324",
  ...
}
```

Exemplo de Retorno:

```json
{
  "reservation_key": "bca6268e-918a-4658-9161-a10b00a631ab",
  "fraud_status": "automatically_approved",
  "pre_authorization_amount": 10000
}
```

Para realizar a avaliação de uma reserva, basta enviar um objeto do tipo Reservation ao seguinte endpoint:

`POST https://api.caas.qitech.app/car_rental/reservation`

Além do status do retorno, também é retornado, caso haja, o valor da pré autorização desejada. Caso nenhuma majoração de pré autorização seja identificada, o valor retornado é nulo e não deve ser utilizado.

## Definir o código de uma Reserva

A QI Tech possibilita a definição do código da reserva após a análise inicial. Isto é útil em alguns fluxos operacionais. Nestes casos, basta realizar um PUT no endpoint a seguir, com o código da reserva definido no corpo:

`PUT https://api.caas.qitech.app/car_rental/reservation/{reservation_id}`

:::note
Caso o código da reserva tenha sido definido anteriormente, na requisição de POST ou utilizando um PUT, não é possível redefinir o código da reserva. Neste caso, a API retornará 409 - Conflito.
:::

```json
{
  "reservation_code": "123456789"
}
```

## Recuperar uma Reserva

A fim de recuperar uma Reserva específica, basta realizar uma requisição GET. O resultado retornado é o json mais atualizado da Reserva em questão. Caso este identificador não esteja relacionado a nenhum objeto, o HTTP Status 404 é retornado.

`GET https://api.caas.qitech.app/car_rental/reservation/{reservation_id}`

```shell
curl "https://api.caas.qitech.app/car_rental/reservation/{reservation_id}"
  -H "Authorization: TESTETESTETESTE"
```

---

# Padrões

URL: /documentation/caas/car_rental/standards

Para facilitar a integração e garantir a integridade da informação, foram definidos alguns padrões que são seguidos em toda a API.

## Valores Monetários

Exemplos:

```
10000
12345
98741
1223
1
0
```

As APIs assumem que todos os valores monetários enviados são em Reais Brasileiros. Os valores devem ser enviados como inteiro em centavos.

## Data e Hora com Fuso Horário

Alguns exemplos:

```
2019-10-15T22:35:12-03:00
2018-05-01T13:32:11+00:00
2019-05-01T00:00:00+00:00
```

É representada conforme a ISO 8601. Neste caso, o fuso-horário é colocado logo após o horário e deve representar o fuso do local onde aquele dado será válido. Por exemplo, se um aluguel estiver marcado para começar às 09:30 no aeroporto de Brasília, o horário enviado deverá ser representado por 09:30-03:00, se o aluguel estiver marcado para começar às 09:30 em Manaus, deverá ser representado por 09:30-04:00.

A máscara utilizada para validação é a seguinte:

`YYYY-MM-ddThh:mm:ss±hh:mm`

## Data e Hora sem Fuso Horário

Alguns exemplos:

```
2019-10-15T22:35:12Z
2018-05-01T13:32:11Z
2019-05-01T00:00:00Z
```

É representada conforme a ISO 8601. Dados que independem de fuso-horário deverão ser enviados sem ele, sempre em UTC, com a letra Z indicando que este dado está em UTC. O seguinte formato, portanto, será validado:

`YYYY-MM-ddThh:mm:ssZ`

## Data

Alguns exemplos:

```
2019-10-15
2019-01-01
2017-03-20
```

No caso de campos que recebem somente data, uma data de nascimento, por exemplo, somente a data, sem nenhum horário deve ser enviada com o seguinte formato:

`YYYY-MM-dd`

## Documentos

Uma vez que os números de documento são bastante variados e muitos deles possuem caracteres que não se enquadram como numéricos, definem-se todos os números de documento como string. Outro bom motivo para defini-los como string é evitar que os zeros à esquerda desapareçam. Documentos previstos nesta página possuem uma máscara bem definida e estarão sujeitos a validação. O restante dos documentos, como RG, dada sua falta de padronização, não serão validados.

## CPF

Exemplos de CPFs válidos contra a máscara definida:

```
123.456.789-12
321.987.543-23
111.283.333-00
```

Exemplos de CPFs inválidos contra a máscara definida:

```
8.577.477-8
08.104.627/0001-23
123.456.789-1
23.456.789-01
```

O CPF é sempre definido como uma string e será validado contra a máscara:

`###.###.###-##`

## CNPJ

Exemplos de CNPJs válidos contra a máscara definida:

```
08.104.627/0001-02
01.079.210/0114-67
32.402.502/0001-35
```

Exemplos de CNPJs inválidos contra a máscara definida:

```
8.577.477-8
123.456.789-12
321.987.543-23
32.402.502/0001-3
032.402.502/0001-3
```

O CNPJ é sempre definido como uma string e será validado contra a máscara:

`##.###.###/####-##`

---

# Webhook

URL: /documentation/caas/car_rental/webhook

Webhook

Atualizações no status de fraude (Para RentalAgreements que sejam derivados para análise manual ou que sejam respondidos como Pendente), são notificados por meio de Webhook. Para tanto, é necessário, por meio da equipe do [suporte](mailto:suporte.caas@qitech.com.br), configurar um endereço do endpoint por onde vamos notificar as atualizações e também um *secret_token* que será utilizado para assinar a requisição.

O cliente pode, apesar de não recomendável, também utilizar a técnica de [polling](https://en.wikipedia.org/wiki/Polling_(computer_science)). Neste caso, basta não configurar o endpoint de webhook e utilizar os endpoints de recuperação de RentalAgreement para proceder com o polling.

## Assinatura do Webhook

## Requisição

Exemplo de requisição:

```json
{
  "rental_agreement_id": "123456",
  "fraud_status": "automatically_approved",
  "upgrade_status": "automatically_approved",
  "event_date": "2019-10-01T10:37:25-03:00"
}
```

A requisição possui o formato acima e notifica a mudança no status de fraude.

## Retentativas

A notificação é considerada realizada quando recebe como resposta um HTTP Status 200. Caso as notificações falhem, serão feitas retentativas, com os seguintes intervalos, até que um 200 seja retornado ou as tentativas terminem:

- 10 segundos
- 30 segundos
- 60 segundos
- 120 segundos
- 120 segundos
- 3600 segundos
- 7200 segundos
- 36000 segundos

---

# Alertas de Portadores

URL: /documentation/caas/card_issuance/alerts

Alertas de Portadores

Os alertas gerados pela ferramenta antifraude são notificados por meio de Webhook. Para tanto, é necessário, por meio da equipe do [suporte](mailto:suporte.caas@qitech.com.br), configurar um endereço do endpoint por onde vamos notificar as notificações e também um *secret_token* que será utilizado para assinar a requisição.

Nesta notificação enviaremos informações dos alertas gerados, bem como de qual portador se trata, para que o cliente possa tomar alguma ação, por exemplo, enviar um *push notification* para o portador.

## Requisição

Request Body

```json
    {
        "alert_key": "123456",
        "cardholder_id": "ef47bc3f-61ac-4b85-ad67-0cfa3a422201",
        "company_name": "Cliente 1",
        "irregularity_type" : "fraud",
        "risk_level": "critical"
    }
```

A requisição possui o formato acima e notifica a abertura de um novo alerta para um Portador - descrito pelo *cardholder_id*

## Assinatura do Webhook

Para garantir que a requisição recebida no seu endpoint partiu dos nossos servidores, enviamos uma assinatura HMAC no header `Signature`. Você recalcula essa assinatura do seu lado e compara com a recebida — se forem iguais, a requisição é confiável.

### Como a assinatura é calculada

```text
Signature = HMAC-SHA1(signature_key, endpoint + method + payload)  →  hexadecimal
```

Os três componentes são concatenados **nesta ordem, sem separador**:

| Componente | O que é |
| --- | --- |
| `endpoint` | A URL completa do seu webhook, exatamente como foi configurada com o suporte (incluindo `https://` e eventual query string). |
| `method` | O verbo HTTP em **letras maiúsculas** — sempre `POST` nas notificações de alerta. |
| `payload` | O corpo da requisição **exatamente como recebido**, byte a byte. |
| `signature_key` | O `secret_token` que você combinou com o suporte. É a chave do HMAC, não parte da mensagem. |

:::danger Use o corpo bruto, nunca o JSON reserializado
A assinatura é calculada sobre os bytes exatos do corpo. Se você desserializar o JSON e serializar de novo antes de validar, a ordem das chaves e o espaçamento mudam, e a assinatura **nunca** vai bater.

Leia o corpo como string/bytes brutos primeiro, valide a assinatura, e só depois faça o parse. Nos exemplos abaixo isso aparece como `request.data`, `file_get_contents('php://input')`, `req.rawBody` etc.
:::

:::caution Acentuação no payload
Nós serializamos o corpo com `ensure_ascii=False`, ou seja, caracteres acentuados vão como UTF-8 literal (`"João"`), e não escapados (`"João"`). Trate o corpo como UTF-8 ao calcular o HMAC — é o comportamento padrão em todas as linguagens abaixo, mas é a causa mais comum de assinatura divergente quando o `company_name` tem acento.
:::

### Exemplos de validação

**Python**

```python
import hashlib
import hmac

SIGNATURE_KEY = "YOUR_SECRET_TOKEN"
WEBHOOK_URL = "https://seu-dominio.com/webhooks/qitech/alertas"

def calculate_signature(endpoint: str, method: str, payload: str) -> str:
    hmac_obj = hmac.new(
        SIGNATURE_KEY.encode("utf-8"),
        (endpoint + method + payload).encode("utf-8"),
        hashlib.sha1,
    )
    return hmac_obj.hexdigest()

def is_valid(received_signature: str, raw_body: str) -> bool:
    expected = calculate_signature(WEBHOOK_URL, "POST", raw_body)
    # compare_digest evita ataques de temporização
    return hmac.compare_digest(expected, received_signature)

# Exemplo com Flask
from flask import Flask, request

app = Flask(__name__)

@app.route("/webhooks/qitech/alertas", methods=["POST"])
def receive_alert():
    raw_body = request.get_data(as_text=True)  # corpo bruto, sem parse
    received = request.headers.get("Signature", "")

    if not is_valid(received, raw_body):
        return "", 401

    alert = request.get_json()  # parse só depois de validar
    print(alert["cardholder_id"], alert["risk_level"])
    return "", 200
```

**PHP**

```php
<?php

const SIGNATURE_KEY = 'YOUR_SECRET_TOKEN';
const WEBHOOK_URL   = 'https://seu-dominio.com/webhooks/qitech/alertas';

function calculateSignature(string $endpoint, string $method, string $payload): string
{
    return hash_hmac('sha1', $endpoint . $method . $payload, SIGNATURE_KEY);
}

function isValid(string $receivedSignature, string $rawBody): bool
{
    $expected = calculateSignature(WEBHOOK_URL, 'POST', $rawBody);
    // hash_equals evita ataques de temporização
    return hash_equals($expected, $receivedSignature);
}

// Recebendo a notificação
$rawBody  = file_get_contents('php://input');           // corpo bruto, sem parse
$received = $_SERVER['HTTP_SIGNATURE'] ?? '';

if (!isValid($received, $rawBody)) {
    http_response_code(401);
    exit;
}

$alert = json_decode($rawBody, true);                   // parse só depois de validar
error_log($alert['cardholder_id'] . ' - ' . $alert['risk_level']);

http_response_code(200);
```

**Node.js**

```javascript
const crypto = require("crypto");
const express = require("express");

const SIGNATURE_KEY = "YOUR_SECRET_TOKEN";
const WEBHOOK_URL = "https://seu-dominio.com/webhooks/qitech/alertas";

function calculateSignature(endpoint, method, payload) {
  return crypto
    .createHmac("sha1", SIGNATURE_KEY)
    .update(endpoint + method + payload, "utf8")
    .digest("hex");
}

function isValid(receivedSignature, rawBody) {
  const expected = calculateSignature(WEBHOOK_URL, "POST", rawBody);
  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(receivedSignature, "utf8");
  // timingSafeEqual exige buffers de mesmo tamanho
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

const app = express();

// express.raw preserva o corpo bruto — NÃO use express.json() nesta rota
app.post(
  "/webhooks/qitech/alertas",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const rawBody = req.body.toString("utf8");
    const received = req.get("Signature") || "";

    if (!isValid(received, rawBody)) {
      return res.sendStatus(401);
    }

    const alert = JSON.parse(rawBody); // parse só depois de validar
    console.log(alert.cardholder_id, alert.risk_level);
    res.sendStatus(200);
  },
);

app.listen(3000);
```

**Java**

```java
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class WebhookSignature {

    private static final String SIGNATURE_KEY = "YOUR_SECRET_TOKEN";
    private static final String WEBHOOK_URL =
            "https://seu-dominio.com/webhooks/qitech/alertas";

    public static String calculateSignature(String endpoint, String method, String payload)
            throws Exception {
        Mac mac = Mac.getInstance("HmacSHA1");
        mac.init(new SecretKeySpec(
                SIGNATURE_KEY.getBytes(StandardCharsets.UTF_8), "HmacSHA1"));

        byte[] digest = mac.doFinal(
                (endpoint + method + payload).getBytes(StandardCharsets.UTF_8));

        StringBuilder hex = new StringBuilder(digest.length * 2);
        for (byte b : digest) {
            hex.append(String.format("%02x", b));
        }
        return hex.toString();
    }

    public static boolean isValid(String receivedSignature, String rawBody)
            throws Exception {
        String expected = calculateSignature(WEBHOOK_URL, "POST", rawBody);
        // MessageDigest.isEqual evita ataques de temporização
        return MessageDigest.isEqual(
                expected.getBytes(StandardCharsets.UTF_8),
                receivedSignature.getBytes(StandardCharsets.UTF_8));
    }
}
```

Em Spring Boot, receba o corpo como `String` para preservar os bytes originais:

```java
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
public class AlertController {

    @PostMapping("/webhooks/qitech/alertas")
    public ResponseEntity<Void> receiveAlert(
            @RequestBody String rawBody,                       // corpo bruto, sem parse
            @RequestHeader(value = "Signature", required = false) String signature)
            throws Exception {

        if (signature == null || !WebhookSignature.isValid(signature, rawBody)) {
            return ResponseEntity.status(401).build();
        }

        // parse só depois de validar (ex.: com Jackson)
        return ResponseEntity.ok().build();
    }
}
```

**C#**

```csharp
using System;
using System.Security.Cryptography;
using System.Text;

public static class WebhookSignature
{
    private const string SignatureKey = "YOUR_SECRET_TOKEN";
    private const string WebhookUrl =
        "https://seu-dominio.com/webhooks/qitech/alertas";

    public static string CalculateSignature(string endpoint, string method, string payload)
    {
        using var hmac = new HMACSHA1(Encoding.UTF8.GetBytes(SignatureKey));
        var digest = hmac.ComputeHash(Encoding.UTF8.GetBytes(endpoint + method + payload));
        return Convert.ToHexString(digest).ToLowerInvariant();
    }

    public static bool IsValid(string receivedSignature, string rawBody)
    {
        var expected = CalculateSignature(WebhookUrl, "POST", rawBody);
        // FixedTimeEquals evita ataques de temporização
        return CryptographicOperations.FixedTimeEquals(
            Encoding.UTF8.GetBytes(expected),
            Encoding.UTF8.GetBytes(receivedSignature));
    }
}
```

Em ASP.NET Core, leia o corpo bruto antes de qualquer desserialização:

```csharp
app.MapPost("/webhooks/qitech/alertas", async (HttpRequest request) =>
{
    using var reader = new StreamReader(request.Body, Encoding.UTF8);
    var rawBody = await reader.ReadToEndAsync();          // corpo bruto, sem parse

    var received = request.Headers["Signature"].ToString();

    if (!WebhookSignature.IsValid(received, rawBody))
    {
        return Results.Unauthorized();
    }

    // parse só depois de validar
    return Results.Ok();
});
```

:::tip Assinatura não bate? Verifique nesta ordem
1. **O corpo foi reserializado?** É a causa mais frequente. Use o corpo bruto.
2. **A URL está idêntica?** Uma barra final a mais ou a menos (`/alertas` vs `/alertas/`) muda a assinatura. Use exatamente a URL configurada com o suporte.
3. **O método está em maiúsculas?** Deve ser `POST`, não `post`.
4. **A ordem da concatenação está certa?** É `endpoint + method + payload`, nessa ordem.
5. **O digest está em hexadecimal minúsculo?** Não é Base64.
:::

## Retentativas

A notificação é considerada realizada quando recebe como resposta um HTTP Status 200. Caso as notificações falhem, serão feitas 5 retentativas, com os seguintes intervalos, até que um 200 seja retornado ou as tentativas terminem:

* 30 segundos
* 60 segundos
* 120 segundos
* 240 segundos
* 360 segundos

---

# authentication

URL: /documentation/caas/card_issuance/authentication

## Autenticação

> Para autenticar uma chamada, utilize o código seguinte:

```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE_API_KEY"
```

> Substitua a API key 'EXAMPLE_API_KEY' com a sua chave adquirida com o nosso suporte.

Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br .

Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:

`Authorization: EXAMPLE_API_KEY`

:::info **Atenção**

Você deve substituir EXAMPLE_API_KEY com a API Key recebida do suporte.
:::

---

# Status HTTP

URL: /documentation/caas/card_issuance/http_status

Todas as APIs da QI Tech utilizam a seguinte padronização nos status HTTP de retorno, de acordo com o RFC 7231 :

Status HTTP | Significado | Descrição
---------- | ------- | ---------------------------------
400 | Bad Request | A requisição enviada possui algum erro de formatação. Na maioria dos casos, retornamos no corpo da mensagem uma explicação de onde está o erro.
401 | Unauthorized | Houve algum problema na autenticação, verifique se a API Key está correta e no header correto, de acordo com a seção Autenticação .
403 | Forbidden | O endpoint acessado é de uso interno e não está disponível para esta API Key.
404 | Not Found | O dado requisitado não foi encontrado usando a chave utilizada. Este status também é retornado quando um endpoint inválido é requisitado.
405 | Method Not Allowed | O método HTTP utilizado não se aplica ao endpoint utilizado.
406 | Not Acceptable | Os dados enviados no corpo da requisição são inválidos. Em geral, isso significa que os dados enviados não são um JSON válido.
409 | Conflict | O id da requisição corresponde a um id já processado anteriormente. Este status é retornado no caso de requisições duplicadas enviadas ao servidor.
500 | Internal Server Error | Tivemos um problema para processar esta requisição, ao encontrarmos esse erro nossos especialistas são automaticamente notificados e iniciam a análise e solução imediatamente.
503 | Service Unavailable | Você se deparou com uma indisponibilidade, planejada ou não, de infraestrutura dos nossos servidores.

---

# Introdução

URL: /documentation/caas/card_issuance/introduction

Bem vindo à API de Prevenção a Fraudes em emissão de cartões da QI Tech! Você pode utilizar a nossa API para acessar os endpoints, a fim de receber a resposta de uma transação, além de utilizar para atualizar a situação de uma transação.

:::info **Atenção**

Atenção, esta API é direcionada para emissores de cartão, ou seja, empresas que dão o cartão na mão do portador para que ele possa transacionar. Ela tem como objetivo realizar toda a análise de segurança nas transações do seu cliente, evitando fraudes e outros tipos de incidentes (Transações decorrentes de assaltos, por exemplo).
:::

## Como funciona

A integração tem três chamadas. Todas usam a mesma API Key no header `Authorization`.

| Passo | Chamada | O que faz |
| --- | --- | --- |
| 1 | `POST /card_issuance/transaction` | Envia a transação **antes da autorização** e devolve a recomendação em `fraud_status`. |
| 2 | `PUT /card_issuance/transaction/{id}` | Informa o desfecho real (capturada, cancelada, chargeback). Retroalimenta o modelo. |
| 3 | `GET /card_issuance/transaction/{id}` | Consulta o estado atual e o histórico de eventos. |

Além disso, alertas comportamentais sobre o portador são entregues por [Webhook](/documentation/caas/card_issuance/alerts).

O `fraud_status` devolvido no passo 1 assume um destes valores:

| Valor | Ação recomendada |
| --- | --- |
| `automatically_approved` | Gerar o código de autorização. |
| `automatically_declined` | Negar a autorização. |
| `not_analyzed` | A requisição usou `analyze=false`; siga a sua própria decisão. |

:::tip Integre em minutos
A página [Transaction](/documentation/caas/card_issuance/transaction) abre com um **payload mínimo** de 13 campos e traz exemplos prontos em Python, PHP, Node.js, Java, C# e curl.
:::

## Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso suporte e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

### Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

## Ambientes

Possuímos dois ambientes para os nossos clientes. As URLs base das APIs são:

* Produção - `https://api.caas.qitech.app/card_issuance/`
* Sandbox - `https://api.sandbox.caas.qitech.app/card_issuance/`

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.  
:::

No ambiente de Sandbox, as análises enviadas não são cobradas e são respondidas de acordo com regras pré estabelecidas.

Para a análise de uma transação, a seguinte regra é aplicada sobre o valor da transação:

Mínimo | Máximo | Decisão
------ | ------ | -------
10000 | - | automatically_approved
0 | 9999 | automatically_declined

## Somente HTTPS

Por questão de segurança, toda a comunicação com as APIs da QI Tech deve ser realizada utilizando a comunicação HTTPS. Para evitar que, por desatenção ou outro motivo, sejam feitas chamadas HTTP, este servidor somente disponibiliza a porta 443 com comunicação TLS 1.2. Chamadas realizadas utilizando outros protocolos serão automaticamente negadas.

## Autenticação

> Para autenticar uma chamada, utilize o código seguinte:

```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

> Substitua a API key 'EXAMPLE-OF-API-KEY' com a sua chave adquirida com o nosso suporte.

Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br .

Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:

`Authorization: EXAMPLE-OF-API-KEY`

:::info **Atenção**

Você deve substituir EXAMPLE-OF-API-KEY com a API Key recebida do suporte.
:::

---

# Padrões

URL: /documentation/caas/card_issuance/standards

Para facilitar a integração e garantir a integridade da informação, foram definidos alguns padrões que são seguidos em toda a API.

## Valores Monetários
> Exemplos:

```
10000
12345
98741
1223
1
0
```

Os valores devem ser enviados como inteiro em centavos.

## Data e Hora com Fuso Horário
> Alguns exemplos:

```
2019-10-15T22:35:12-03:00
2018-05-01T13:32:11+00:00
2019-05-01T00:00:00+00:00
```

É representada conforme a ISO 8601. Neste caso, o fuso-horário é colocado logo após o horário e deve representar o fuso do local onde aquele dado será valido. Por exemplo, se um aluguel estiver marcado para começar às 09:30 no aeroporto de Brasília, o horário enviado deverá ser representado por 09:30-03:00, se o aluguel estiver marcado para começar às 09:30 em Manaus, deverá ser representado por 09:30-04:00.

A máscara utilizada para validação é a seguinte:

`YYYY-MM-ddThh:mm:ss±hh:mm`

## Data e Hora sem Fuso Horario
> Alguns exemplos:

```
2019-10-15T22:35:12Z
2018-05-01T13:32:11Z
2019-05-01T00:00:00Z
```

É representada conforme a ISO 8601. Dados que independem de fuso-horário deverão ser enviados sem ele, sempre em UTC, com a letra Z indicando que este dado está em UTC. O seguinte formato, portanto, será validado:

`YYYY-MM-ddThh:mm:ssZ`

## Data
> Alguns exemplos

``` 
2019-10-15
2019-01-01
2017-03-20
```

---

# Transaction

URL: /documentation/caas/card_issuance/transaction

Transaction

O recurso `Transaction` é o coração da API de antifraude transacional de cartão. Você envia os dados da transação **antes de autorizá-la** e recebe de volta uma recomendação (`fraud_status`) para decidir se gera ou não o código de autorização.

O fluxo completo de integração tem três passos:

1. **`POST /card_issuance/transaction`** — envia a transação para análise e recebe a recomendação.
2. **`PUT /card_issuance/transaction/{id}`** — informa o desfecho real (capturada, cancelada, chargeback). Esse retorno alimenta o modelo e é o que mantém a qualidade das decisões ao longo do tempo.
3. **`GET /card_issuance/transaction/{id}`** — consulta o estado atual e o histórico de eventos de uma transação.

:::tip Comece pelo payload mínimo
Se você quer subir uma integração rápida, vá direto para [Payload mínimo](#payload-minimo). São 13 campos obrigatórios. Todo o resto é opcional e serve para aumentar a acurácia do modelo.
:::

---

## Payload mínimo

Este é o menor corpo aceito pelo `POST /card_issuance/transaction`. Ele contém **apenas** os campos obrigatórios e é suficiente para receber uma decisão.

```json title="Payload mínimo — 13 campos obrigatórios"
{
  "id": "678",
  "cardholder_id": "b812da2e-e6be-4712-8e57-6f3f2791625b",
  "amount": 13725,
  "currency": "BRL",
  "installments": 1,
  "authorization_date": "2026-08-07T13:25:42-03:00",
  "authorization_type": "authorization",
  "transaction_type": "credit",
  "pan_entry_mode": "chip",
  "pin_sent": true,
  "terminal": {
    "country_code": "BRA"
  },
  "merchant": {
    "acquirer_id": "250",
    "merchant_id": "123456",
    "mcc": "5411"
  },
  "card": {
    "brand": "visa",
    "category": "black",
    "bin": "498406",
    "last4": "1234",
    "issuer_country_code": "BRA"
  }
}
```

Resposta:

```json
{
  "id": "678",
  "fraud_status": "automatically_approved"
}
```

:::info Quanto mais dados, melhor a decisão
Os campos opcionais (localização, capacidades do terminal, limites do cartão, endereço do lojista) não são exigidos pela validação, mas alimentam diretamente os modelos e as regras. Uma integração que envia apenas o mínimo funciona, mas tende a produzir mais falsos positivos.
:::

---

## Enviar uma transação para análise

ENDPOINT /card_issuance/transaction
MÉTODO POST

### Query parameters

analyze
boolean
opcional — padrão true
Quando true , a transação passa pelos motores de fraude e a resposta traz uma recomendação. Quando false , a transação é apenas registrada no histórico do portador (sem custo de análise) e a resposta retorna not_analyzed . Use analyze=false para transações que você já decidiu por outros meios, mas que devem compor o comportamento histórico do portador.

:::caution Ao usar `analyze=false`
Envie também `transaction_status` e `response_code` no corpo, informando o desfeito que você já aplicou. Sem isso, a transação fica registrada como `pending` e o histórico do portador perde informação.
:::

### Exemplos de requisição

**Python**

```python
import requests

BASE_URL = "https://api.sandbox.caas.qitech.app"
API_KEY = "YOUR_API_KEY"

payload = {
    "id": "678",
    "cardholder_id": "b812da2e-e6be-4712-8e57-6f3f2791625b",
    "amount": 13725,
    "currency": "BRL",
    "installments": 1,
    "authorization_date": "2026-08-07T13:25:42-03:00",
    "authorization_type": "authorization",
    "transaction_type": "credit",
    "pan_entry_mode": "chip",
    "pin_sent": True,
    "terminal": {"country_code": "BRA"},
    "merchant": {"acquirer_id": "250", "merchant_id": "123456", "mcc": "5411"},
    "card": {
        "brand": "visa",
        "category": "black",
        "bin": "498406",
        "last4": "1234",
        "issuer_country_code": "BRA",
    },
}

response = requests.post(
    f"{BASE_URL}/card_issuance/transaction",
    params={"analyze": "true"},
    json=payload,
    headers={"Authorization": API_KEY},
    timeout=5,
)

response.raise_for_status()
print(response.json())  # {'id': '678', 'fraud_status': 'automatically_approved'}
```

**PHP**

```php
<?php

$baseUrl = 'https://api.sandbox.caas.qitech.app';
$apiKey  = 'YOUR_API_KEY';

$payload = [
    'id'                 => '678',
    'cardholder_id'      => 'b812da2e-e6be-4712-8e57-6f3f2791625b',
    'amount'             => 13725,
    'currency'           => 'BRL',
    'installments'       => 1,
    'authorization_date' => '2026-08-07T13:25:42-03:00',
    'authorization_type' => 'authorization',
    'transaction_type'   => 'credit',
    'pan_entry_mode'     => 'chip',
    'pin_sent'           => true,
    'terminal'           => ['country_code' => 'BRA'],
    'merchant'           => [
        'acquirer_id' => '250',
        'merchant_id' => '123456',
        'mcc'         => '5411',
    ],
    'card' => [
        'brand'               => 'visa',
        'category'            => 'black',
        'bin'                 => '498406',
        'last4'               => '1234',
        'issuer_country_code' => 'BRA',
    ],
];

$ch = curl_init($baseUrl . '/card_issuance/transaction?analyze=true');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 5,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'Authorization: ' . $apiKey,
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$body   = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status !== 200) {
    throw new RuntimeException("Antifraude retornou HTTP {$status}: {$body}");
}

$result = json_decode($body, true);
echo $result['fraud_status'];  // automatically_approved
```

**Node.js**

```javascript
const BASE_URL = "https://api.sandbox.caas.qitech.app";
const API_KEY = "YOUR_API_KEY";

const payload = {
  id: "678",
  cardholder_id: "b812da2e-e6be-4712-8e57-6f3f2791625b",
  amount: 13725,
  currency: "BRL",
  installments: 1,
  authorization_date: "2026-08-07T13:25:42-03:00",
  authorization_type: "authorization",
  transaction_type: "credit",
  pan_entry_mode: "chip",
  pin_sent: true,
  terminal: { country_code: "BRA" },
  merchant: { acquirer_id: "250", merchant_id: "123456", mcc: "5411" },
  card: {
    brand: "visa",
    category: "black",
    bin: "498406",
    last4: "1234",
    issuer_country_code: "BRA",
  },
};

async function analyzeTransaction() {
  const response = await fetch(
    `${BASE_URL}/card_issuance/transaction?analyze=true`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: API_KEY,
      },
      body: JSON.stringify(payload),
      signal: AbortSignal.timeout(5000),
    },
  );

  if (!response.ok) {
    throw new Error(`Antifraude retornou HTTP ${response.status}`);
  }

  const result = await response.json();
  console.log(result.fraud_status); // automatically_approved
  return result;
}

analyzeTransaction();
```

**Java**

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class AnalyzeTransaction {

    private static final String BASE_URL = "https://api.sandbox.caas.qitech.app";
    private static final String API_KEY = "YOUR_API_KEY";

    public static void main(String[] args) throws Exception {
        String payload = """
            {
              "id": "678",
              "cardholder_id": "b812da2e-e6be-4712-8e57-6f3f2791625b",
              "amount": 13725,
              "currency": "BRL",
              "installments": 1,
              "authorization_date": "2026-08-07T13:25:42-03:00",
              "authorization_type": "authorization",
              "transaction_type": "credit",
              "pan_entry_mode": "chip",
              "pin_sent": true,
              "terminal": { "country_code": "BRA" },
              "merchant": {
                "acquirer_id": "250",
                "merchant_id": "123456",
                "mcc": "5411"
              },
              "card": {
                "brand": "visa",
                "category": "black",
                "bin": "498406",
                "last4": "1234",
                "issuer_country_code": "BRA"
              }
            }
            """;

        HttpClient client = HttpClient.newBuilder()
                .connectTimeout(Duration.ofSeconds(5))
                .build();

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(BASE_URL + "/card_issuance/transaction?analyze=true"))
                .header("Content-Type", "application/json")
                .header("Authorization", API_KEY)
                .timeout(Duration.ofSeconds(5))
                .POST(HttpRequest.BodyPublishers.ofString(payload))
                .build();

        HttpResponse<String> response =
                client.send(request, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() != 200) {
            throw new IllegalStateException(
                    "Antifraude retornou HTTP " + response.statusCode() + ": " + response.body());
        }

        System.out.println(response.body());
        // {"id":"678","fraud_status":"automatically_approved"}
    }
}
```

**C#**

```csharp
using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

public class AnalyzeTransaction
{
    private const string BaseUrl = "https://api.sandbox.caas.qitech.app";
    private const string ApiKey = "YOUR_API_KEY";

    public static async Task Main()
    {
        var payload = new
        {
            id = "678",
            cardholder_id = "b812da2e-e6be-4712-8e57-6f3f2791625b",
            amount = 13725,
            currency = "BRL",
            installments = 1,
            authorization_date = "2026-08-07T13:25:42-03:00",
            authorization_type = "authorization",
            transaction_type = "credit",
            pan_entry_mode = "chip",
            pin_sent = true,
            terminal = new { country_code = "BRA" },
            merchant = new { acquirer_id = "250", merchant_id = "123456", mcc = "5411" },
            card = new
            {
                brand = "visa",
                category = "black",
                bin = "498406",
                last4 = "1234",
                issuer_country_code = "BRA"
            }
        };

        using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(5) };
        client.DefaultRequestHeaders.Add("Authorization", ApiKey);

        var content = new StringContent(
            JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");

        var response = await client.PostAsync(
            $"{BaseUrl}/card_issuance/transaction?analyze=true", content);

        var body = await response.Content.ReadAsStringAsync();

        if (!response.IsSuccessStatusCode)
        {
            throw new InvalidOperationException(
                $"Antifraude retornou HTTP {(int)response.StatusCode}: {body}");
        }

        Console.WriteLine(body);
        // {"id":"678","fraud_status":"automatically_approved"}
    }
}
```

**curl**

```bash
curl -X POST \
  'https://api.sandbox.caas.qitech.app/card_issuance/transaction?analyze=true' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY' \
  -d '{
    "id": "678",
    "cardholder_id": "b812da2e-e6be-4712-8e57-6f3f2791625b",
    "amount": 13725,
    "currency": "BRL",
    "installments": 1,
    "authorization_date": "2026-08-07T13:25:42-03:00",
    "authorization_type": "authorization",
    "transaction_type": "credit",
    "pan_entry_mode": "chip",
    "pin_sent": true,
    "terminal": { "country_code": "BRA" },
    "merchant": { "acquirer_id": "250", "merchant_id": "123456", "mcc": "5411" },
    "card": {
      "brand": "visa",
      "category": "black",
      "bin": "498406",
      "last4": "1234",
      "issuer_country_code": "BRA"
    }
  }'
```

### Resposta

id
string
O mesmo id que você enviou na requisição.

fraud_status
enum
A recomendação do motor antifraude. Veja fraud_status .

```json
{
  "id": "678",
  "fraud_status": "automatically_approved"
}
```

:::caution Comportamento em caso de indisponibilidade interna
Se os motores de decisão ficarem indisponíveis, a API retorna `automatically_approved` em vez de erro. Isso é intencional: o antifraude nunca deve derrubar a autorização do cartão. Ainda assim, trate timeouts do seu lado com uma política de fallback definida.
:::

---

## Objeto Transaction

### Campos raiz

id
string
obrigatório
Identificador da transação no seu sistema. Máximo de 36 caracteres. Deve ser único por processo de autorização — um id repetido retorna HTTP 409.

cardholder_id
string
obrigatório
Identificador do portador no seu sistema. Máximo de 200 caracteres. É a chave que agrupa o histórico comportamental — use sempre o mesmo valor para o mesmo portador.

amount
integer
obrigatório
Valor da transação em centavos, na moeda de currency . Entre 0 e 1000000000 .

currency
enum
obrigatório
Moeda da transação em ISO 4217 ( BRL , USD , EUR …), correspondente ao ApplicationCurrencyCode da ISO 8583.

installments
integer
obrigatório
Número de parcelas. Entre 0 e 24 . Use 1 para transações à vista.

authorization_date
datetime
obrigatório
Data e hora de início da transação, com fuso horário , no formato YYYY-MM-DDThh:mm:ss±hh:mm . Veja a nota sobre o formato .

authorization_type
enum
obrigatório
Tipo de autorização. Veja authorization_type .

transaction_type
enum
obrigatório
Função utilizada: credit , debit ou prepaid .

pan_entry_mode
enum
obrigatório
Modo de entrada do PAN, derivado do DE 22 (Sub Field 1) da ISO 8583. Veja pan_entry_mode .

pin_sent
boolean
obrigatório
Indica se uma senha foi inserida no terminal.

terminal
object
obrigatório
Dados do terminal. Veja Objeto terminal .

merchant
object
obrigatório
Dados do estabelecimento. Veja Objeto merchant .

card
object
obrigatório
Dados do cartão. Veja Objeto card .

accountholder_id
string
opcional
Identificador do titular da conta, quando diferente do portador do cartão (cartões adicionais, cartões corporativos). Máximo de 200 caracteres.

group_id
string
opcional
Grupo ou categoria a que o portador pertence no seu sistema. Máximo de 200 caracteres. Útil para segmentar regras por carteira.

brl_converted_amount
integer
opcional
Valor da transação convertido para reais, em centavos. Você não precisa enviar este campo — quando currency é diferente de BRL , a QI Tech calcula a conversão internamente; quando é BRL , o valor é igual a amount . Se enviado, é sobrescrito.

location
object
opcional
Localização geográfica da transação. Veja Objeto location .

authentication_type
string
opcional
Método de autenticação aplicado à transação (por exemplo, o resultado de um 3-D Secure). Máximo de 200 caracteres.

risk_assessment
enum
opcional
Classificação de risco atribuída pela bandeira ou pelo adquirente na mensageria. Veja risk_assessment .

cvv_presence
boolean
opcional
Indica se o CVV foi informado na transação. Sinal relevante em transações de e-commerce.

transaction_status
enum
opcional
Situação da transação. Envie no POST apenas quando usar analyze=false e a decisão de autorização já tiver sido tomada. Veja transaction_status .

response_code
string
opcional
Response code da transação conforme o campo Response Code da ISO 8583. Exatamente 1 ou 2 caracteres. Assim como transaction_status , faz sentido no POST apenas com analyze=false .

```json title="Payload completo"
{
  "id": "678",
  "cardholder_id": "b812da2e-e6be-4712-8e57-6f3f2791625b",
  "accountholder_id": "0f5e2d1c-4a3b-4c6d-9e8f-1a2b3c4d5e6f",
  "group_id": "8507884b-c30f-4b45-951c-f0bf366926fc",
  "amount": 13725,
  "currency": "BRL",
  "installments": 6,
  "authorization_date": "2026-08-07T13:25:42-03:00",
  "authorization_type": "authorization",
  "transaction_type": "credit",
  "pan_entry_mode": "chip",
  "pin_sent": true,
  "source_account": "credit_facility",
  "authentication_type": "3ds_authenticated",
  "risk_assessment": "low_risk",
  "cvv_presence": true,
  "location": {
    "latitude": -23.5613,
    "longitude": -46.6565,
    "altitude": 760
  },
  "terminal": {
    "id": "12345678",
    "country_code": "BRA",
    "terminal_type": "5",
    "pin_entry_capability": true,
    "magnetic_stripe_capability": true,
    "contactless_capability": true,
    "chip_capability": true
  },
  "merchant": {
    "acquirer_id": "250",
    "merchant_id": "123456",
    "payment_facilitator": "PAGSEGURO",
    "sub_merchant": "LOJA 042",
    "name": "SUPERMERCADO EXEMPLO",
    "street": "RUA CMDTE X, 127",
    "city": "SAO PAULO",
    "region": "SP",
    "postal_code": "04570-140",
    "mcc": "5411"
  },
  "card": {
    "brand": "visa",
    "category": "black",
    "holder_id": "b812da2e-e6be-4712-8e57-6f3f2791625b",
    "issuing_date": "2025-10-08T07:13:12-03:00",
    "unblock_date": "2025-10-12T07:13:12-03:00",
    "expiration_date": "2030-12-31",
    "bin": "498406",
    "last4": "1234",
    "total_credit_limit": 2500000,
    "used_credit_limit": 732625,
    "issuer_country_code": "BRA"
  }
}
```

:::warning Campos não previstos são rejeitados
O schema usa `additionalProperties: false` em todos os objetos. Qualquer campo fora dos listados aqui faz a requisição retornar **HTTP 400**, mesmo que o restante do payload esteja correto.
:::

#### Formato de `authorization_date`

O validador aceita apenas offsets de fuso terminados em `:00` ou `:30` (por exemplo `-03:00`, `+05:30`, `-04:00`). Sufixo `Z` e offsets como `-03:15` são rejeitados com HTTP 400. Fração de segundo é opcional e aceita de 1 a 6 dígitos:

```text
2026-08-07T13:25:42-03:00          ✅
2026-08-07T13:25:42.123456-03:00   ✅
2026-08-07T13:25:42Z               ❌  use -00:00
2026-08-07T13:25:42-03:15          ❌  offset não permitido
```

A mesma regra vale para `card.issuing_date` e `card.unblock_date`.

---

### Objeto `terminal`

country_code
enum
obrigatório
País do terminal em ISO 3166-1 alpha-3 ( BRA , USA , PRT …). Campo Terminal Country Code da ISO 8583.

id
string
opcional
Identificador do terminal enviado pela adquirente. Máximo de 8 caracteres. String vazia é tratada como ausente.

terminal_type
string
opcional
Tipo de terminal conforme TerminalType da ISO 8583. Máximo de 10 caracteres. Veja terminal_type .

pin_entry_capability
boolean
opcional
O terminal permite inserir senha? Campo TerminalPINEntryCapability da ISO 8583.

magnetic_stripe_capability
boolean
opcional
O terminal lê tarja magnética? Campo TerminalPANEntryCapability (DE 123).

contactless_capability
boolean
opcional
O terminal aceita transações por aproximação? Campo TerminalPANEntryCapability (DE 123).

chip_capability
boolean
opcional
O terminal lê chip EMV? Campo TerminalPANEntryCapability (DE 123).

```json
{
  "terminal": {
    "id": "12345678",
    "country_code": "BRA",
    "terminal_type": "5",
    "pin_entry_capability": true,
    "magnetic_stripe_capability": true,
    "contactless_capability": true,
    "chip_capability": true
  }
}
```

:::info Mudança em relação à versão anterior desta documentação
Apenas `country_code` é obrigatório dentro de `terminal`. As versões antigas desta página listavam `terminal_type`, `pin_entry_capability` e `chip_capability` como obrigatórios — eles são opcionais.
:::

---

### Objeto `merchant`

acquirer_id
string
obrigatório
Identificador da adquirente. Máximo de 11 caracteres. Campo Acquirer Identifier (DE 32) da ISO 8583.

merchant_id
string
obrigatório
Identificador do lojista na adquirente. Máximo de 15 caracteres. Campo Merchant Identifier da ISO 8583.

mcc
enum
obrigatório
Merchant Category Code de 4 dígitos, conforme ISO 18245. Aceita apenas MCCs válidos da lista oficial — um código fora da lista retorna HTTP 400.

name
string
opcional
Nome do lojista conforme a mensageria. Máximo de 200 caracteres.

payment_facilitator
string
opcional
Facilitador de pagamento (subadquirente) envolvido na transação. Máximo de 200 caracteres.

sub_merchant
string
opcional
Sublojista, quando a transação passa por um facilitador. Máximo de 200 caracteres.

street
string
opcional
Logradouro do lojista. Campo Card Acceptor Street Address .

city
string
opcional
Cidade do lojista. Campo Card Acceptor City .

region
string
opcional
Região/estado do lojista. Campo Card Acceptor Region Code .

postal_code
string
opcional
CEP do lojista. Campo Card Acceptor Postal Code .

```json
{
  "merchant": {
    "acquirer_id": "250",
    "merchant_id": "123456",
    "payment_facilitator": "PAGSEGURO",
    "sub_merchant": "LOJA 042",
    "name": "SUPERMERCADO EXEMPLO",
    "street": "RUA CMDTE X, 127",
    "city": "SAO PAULO",
    "region": "SP",
    "postal_code": "04570-140",
    "mcc": "5411"
  }
}
```

---

### Objeto `card`

brand
enum
obrigatório
Bandeira do cartão. Veja brand .

category
enum
obrigatório
Categoria do cartão. Veja category .

bin
string
obrigatório
BIN do cartão. Exatamente 6 dígitos numéricos.

last4
string
obrigatório
Quatro últimos dígitos do cartão. Exatamente 4 dígitos numéricos.

issuer_country_code
enum
obrigatório
País do emissor em ISO 3166-1 alpha-3.

holder_id
string
opcional
Identificador do portador vinculado a este plástico específico, útil quando um mesmo cardholder_id possui múltiplos cartões. Máximo de 200 caracteres.

issuing_date
datetime
opcional
Data e hora de emissão do cartão, com fuso horário. Cartões recém-emitidos são um sinal de risco relevante.

unblock_date
datetime
opcional
Data e hora em que o portador desbloqueou o cartão, com fuso horário.

expiration_date
date
opcional
Data de vencimento do cartão no formato YYYY-MM-DD (use o último dia do mês).

total_credit_limit
integer
opcional
Limite total de crédito do portador, em centavos. Para cartões pré-pagos, o saldo disponível.

used_credit_limit
integer
opcional
Limite já utilizado, em centavos, antes da transação em análise.

```json
{
  "card": {
    "brand": "visa",
    "category": "black",
    "holder_id": "b812da2e-e6be-4712-8e57-6f3f2791625b",
    "issuing_date": "2025-10-08T07:13:12-03:00",
    "unblock_date": "2025-10-12T07:13:12-03:00",
    "expiration_date": "2030-12-31",
    "bin": "498406",
    "last4": "1234",
    "total_credit_limit": 2500000,
    "used_credit_limit": 732625,
    "issuer_country_code": "BRA"
  }
}
```

:::info Mudança em relação à versão anterior desta documentação
`issuing_date` e `expiration_date` **não** são obrigatórios, ao contrário do que a versão anterior desta página indicava. Os obrigatórios em `card` são apenas `brand`, `category`, `bin`, `last4` e `issuer_country_code`.
:::

---

### Objeto `location`

latitude
number
obrigatório se location for enviado
Latitude da transação, entre -90 e 90 .

longitude
number
obrigatório se location for enviado
Longitude da transação, entre -180 e 180 .

altitude
number
opcional
Altitude em metros, entre 0 e 100000 .

```json
{
  "location": {
    "latitude": -23.5613,
    "longitude": -46.6565,
    "altitude": 760
  }
}
```

:::caution Objeto opcional com campos obrigatórios
`location` como um todo é opcional. Mas se você enviar o objeto, `latitude` e `longitude` passam a ser obrigatórios dentro dele. Se não tiver a coordenada, omita o objeto inteiro em vez de enviá-lo vazio.
:::

---

## Enumeradores

### `authorization_type`

| Valor | Significado |
| --- | --- |
| `authorization` | Autorização de compra — MTI x1xx (DMS) e x2xx (SMS). |
| `pre_authorization` | Pré-autorização para reserva de limite (hotel, locação de veículos, postos de combustível) — MTI x1xx (DMS) e *Transaction Type* `60` nos dois primeiros dígitos do Processing Code. |
| `reversal` | Cancelamento de autorização, para liberar limite antes do Clearing/BASE II — MTI x4xx. |

### `transaction_type`

| Valor | Significado |
| --- | --- |
| `credit` | Transação na função crédito. |
| `debit` | Transação na função débito. |
| `prepaid` | Transação na função pré-pago. |

### `pan_entry_mode`

Derivado do DE 22 (Sub Field 1) da ISO 8583.

| Valor | ISO 8583 | Significado |
| --- | --- | --- |
| `unknown` | 00 | Modo de entrada desconhecido. |
| `typed` | 01 | PAN digitado manualmente. |
| `bar_code` | 03 | PAN lido por código de barras. |
| `ocr` | 04 | PAN lido por OCR. |
| `chip` | 05 | PAN lido pelo chip EMV. |
| `track_1` | 06 | PAN lido pela Track 1 da tarja. |
| `contactless` | 07 | PAN lido por aproximação (Contactless EMV). |
| `fallback_typed` | 79 | Falha na leitura de chip/tarja e o PAN foi digitado. Também usado quando a adquirente não está homologada para chip ou tarja. |
| `fallback_magnetic_stripe` | 80 | Falha na leitura do chip e a transação prosseguiu pela tarja magnética. |
| `ecommerce` | 81 | Transação de e-commerce / cartão não presente. |
| `magnetic_stripe` | 90 | Transação por tarja magnética. |
| `manual` | — | Entrada manual dos dados do cartão fora do fluxo de terminal. |
| `stored_credentials` | — | Transação com credenciais armazenadas (assinaturas, cobranças recorrentes, carteiras com cartão tokenizado). |

:::tip `stored_credentials` e recorrências
Transações recorrentes marcadas como `ecommerce` tendem a receber mais recusas do que o esperado, porque o modelo as trata como cartão não presente sem contexto. Use `stored_credentials` sempre que a cobrança usar uma credencial previamente autorizada pelo portador.
:::

### `source_account`

Derivado do Processing Code da ISO 8583. Campo opcional.

| Valor | ISO 8583 | Significado |
| --- | --- | --- |
| `default` | 00 | Padrão ou não especificado. |
| `saving_account` | 10 | Conta poupança. |
| `checking_account` | 20 | Conta corrente. |
| `credit_facility` | 30 | Fatura do cartão. |
| `universal_account` | 40 | Conta universal. |
| `investment_account` | 50 | Conta de investimento. |
| `electronic_purse` | 60 | Saldo armazenado no chip do cartão. |

### `brand`

| Valor | Bandeira |
| --- | --- |
| `visa` | Visa |
| `mastercard` | Mastercard |
| `elo` | Elo |
| `diners_club` | Diners Club |
| `american_express` | American Express |

### `category`

| Valor | Categoria |
| --- | --- |
| `classic` | Classic |
| `gold` | Gold |
| `platinum` | Platinum |
| `black` | Black / Infinite |
| `travel` | Travel |
| `corporate` | Corporate / Business |
| `prepaid` | Pré-pago |
| `postpaid` | Pós-pago |

### `terminal_type`

Conforme *TerminalType* da ISO 8583. Enviado como string.

| Valor | Significado |
| --- | --- |
| `0` | Desconhecido |
| `1` | Nenhum terminal utilizado |
| `2` | Leitor de tarja magnética |
| `3` | Código de barras |
| `4` | OCR |
| `5` | Leitor de tarja magnética e de chip EMV |
| `6` | Apenas entrada por teclado |
| `7` | Leitor de tarja magnética e entrada por teclado |
| `8` | Leitor de tarja, entrada por teclado e chip EMV |
| `9` | Leitor de chip EMV |

### `risk_assessment`

Classificação de risco recebida na mensageria (por exemplo, TRA da PSD2 ou avaliação da bandeira).

| Valor | Significado |
| --- | --- |
| `not_evaluated` | Nenhuma avaliação de risco foi realizada. |
| `low_risk` | A transação foi classificada como de baixo risco. |
| `non_low_risk` | A transação **não** foi classificada como de baixo risco. |

### `transaction_status`

Situação da transação no ciclo de vida da autorização.

| Valor | Significado |
| --- | --- |
| `pending` | Autorização pendente. Estado inicial atribuído automaticamente. |
| `authorized` | Autorizada, aguardando captura. |
| `not_authorized` | Não autorizada pelo emissor. |
| `captured` | Capturada. |
| `cleared` | Recebida no Clearing / BASE II. |
| `cancelled` | Cancelada integralmente. |
| `partially_cancelled` | Cancelada parcialmente. |
| `chargeback` | Recebeu chargeback integral. |
| `partial_chargeback` | Recebeu chargeback parcial. |

:::note `pending` não é enviável
`pending` é atribuído pela própria API quando a transação é criada sem decisão. Ele não é aceito no corpo do `POST` nem do `PUT`.
:::

### `fraud_status`

A recomendação devolvida pelo motor antifraude.

| Valor | Significado | Ação recomendada |
| --- | --- | --- |
| `automatically_approved` | O padrão da transação é compatível com o comportamento do portador. | Gerar o código de autorização. |
| `automatically_declined` | A transação apresenta risco relevante de fraude. | Negar a autorização. |
| `not_analyzed` | A requisição foi enviada com `analyze=false`. Nenhuma análise foi realizada. | Seguir a sua própria decisão. |

---

## Atualizar o status de uma transação

ENDPOINT /card_issuance/transaction/ TRANSACTION_ID
MÉTODO PUT

Informar o desfecho real da transação é o que retroalimenta as regras e o modelo. Sem esse passo, a qualidade das recomendações degrada ao longo do tempo.

O `TRANSACTION_ID` no path é o mesmo `id` que você enviou no `POST`.

### Corpo da requisição

O corpo aceita **duas formas**, escolhidas conforme o status:

**Atualização total**

Para qualquer status que afete a transação por inteiro.

transaction_status
enum
obrigatório
Novo status. Aceita authorized , not_authorized , captured , cleared , cancelled , partially_cancelled , chargeback ou partial_chargeback .

response_code
string
opcional
Response code da ISO 8583. 1 ou 2 caracteres.

```json
{
  "transaction_status": "captured",
  "response_code": "00"
}
```

**Atualização parcial**

Obrigatória para `partially_cancelled` e `partial_chargeback`.

transaction_status
enum
obrigatório
Aceita apenas partially_cancelled ou partial_chargeback .

partial_amount
integer
obrigatório
Valor cancelado/estornado em centavos, de 1 a 1000000000 . Não pode exceder o valor ainda disponível da transação.

response_code
string
opcional
Response code da ISO 8583. 1 ou 2 caracteres.

```json
{
  "transaction_status": "partially_cancelled",
  "partial_amount": 3000,
  "response_code": "00"
}
```

:::danger Status finais não podem ser alterados
Uma transação que já está em `cancelled`, `partially_cancelled`, `chargeback` ou `partial_chargeback` é considerada finalizada. Um novo `PUT` sobre ela retorna **HTTP 400** com o título `Transaction has a final status`.

Consequência prática: você **não** consegue registrar dois cancelamentos parciais em sequência pela API. Planeje enviar o valor consolidado.
:::

Em caso de sucesso, a resposta é **HTTP 200** com corpo vazio (`{}`).

### Exemplos de requisição

**Python**

```python
import requests

BASE_URL = "https://api.sandbox.caas.qitech.app"
API_KEY = "YOUR_API_KEY"
TRANSACTION_ID = "678"

response = requests.put(
    f"{BASE_URL}/card_issuance/transaction/{TRANSACTION_ID}",
    json={"transaction_status": "captured", "response_code": "00"},
    headers={"Authorization": API_KEY},
    timeout=5,
)

response.raise_for_status()  # 200 com corpo vazio
```

**PHP**

```php
<?php

$baseUrl       = 'https://api.sandbox.caas.qitech.app';
$apiKey        = 'YOUR_API_KEY';
$transactionId = '678';

$payload = [
    'transaction_status' => 'captured',
    'response_code'      => '00',
];

$ch = curl_init("{$baseUrl}/card_issuance/transaction/{$transactionId}");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 5,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'Authorization: ' . $apiKey,
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$body   = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status !== 200) {
    throw new RuntimeException("Falha ao atualizar status: HTTP {$status} — {$body}");
}
```

**Node.js**

```javascript
const BASE_URL = "https://api.sandbox.caas.qitech.app";
const API_KEY = "YOUR_API_KEY";
const TRANSACTION_ID = "678";

async function updateStatus() {
  const response = await fetch(
    `${BASE_URL}/card_issuance/transaction/${TRANSACTION_ID}`,
    {
      method: "PUT",
      headers: {
        "Content-Type": "application/json",
        Authorization: API_KEY,
      },
      body: JSON.stringify({
        transaction_status: "captured",
        response_code: "00",
      }),
      signal: AbortSignal.timeout(5000),
    },
  );

  if (!response.ok) {
    throw new Error(`Falha ao atualizar status: HTTP ${response.status}`);
  }
}

updateStatus();
```

**Java**

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class UpdateTransactionStatus {

    private static final String BASE_URL = "https://api.sandbox.caas.qitech.app";
    private static final String API_KEY = "YOUR_API_KEY";
    private static final String TRANSACTION_ID = "678";

    public static void main(String[] args) throws Exception {
        String payload = """
            { "transaction_status": "captured", "response_code": "00" }
            """;

        HttpClient client = HttpClient.newHttpClient();

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(BASE_URL + "/card_issuance/transaction/" + TRANSACTION_ID))
                .header("Content-Type", "application/json")
                .header("Authorization", API_KEY)
                .timeout(Duration.ofSeconds(5))
                .PUT(HttpRequest.BodyPublishers.ofString(payload))
                .build();

        HttpResponse<String> response =
                client.send(request, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() != 200) {
            throw new IllegalStateException(
                    "Falha ao atualizar status: HTTP " + response.statusCode()
                            + " — " + response.body());
        }
    }
}
```

**C#**

```csharp
using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

public class UpdateTransactionStatus
{
    private const string BaseUrl = "https://api.sandbox.caas.qitech.app";
    private const string ApiKey = "YOUR_API_KEY";
    private const string TransactionId = "678";

    public static async Task Main()
    {
        var payload = new { transaction_status = "captured", response_code = "00" };

        using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(5) };
        client.DefaultRequestHeaders.Add("Authorization", ApiKey);

        var content = new StringContent(
            JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");

        var response = await client.PutAsync(
            $"{BaseUrl}/card_issuance/transaction/{TransactionId}", content);

        if (!response.IsSuccessStatusCode)
        {
            var body = await response.Content.ReadAsStringAsync();
            throw new InvalidOperationException(
                $"Falha ao atualizar status: HTTP {(int)response.StatusCode} — {body}");
        }
    }
}
```

**curl**

```bash
curl -X PUT \
  'https://api.sandbox.caas.qitech.app/card_issuance/transaction/678' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY' \
  -d '{ "transaction_status": "captured", "response_code": "00" }'
```

---

## Recuperar uma transação

ENDPOINT /card_issuance/transaction/ TRANSACTION_ID
MÉTODO GET

Retorna o estado atual da transação junto com o histórico completo de eventos. Se o `id` não existir para a sua API Key, a resposta é **HTTP 404**.

**Python**

```python
import requests

BASE_URL = "https://api.sandbox.caas.qitech.app"
API_KEY = "YOUR_API_KEY"
TRANSACTION_ID = "678"

response = requests.get(
    f"{BASE_URL}/card_issuance/transaction/{TRANSACTION_ID}",
    headers={"Authorization": API_KEY},
    timeout=5,
)

response.raise_for_status()
transaction = response.json()
print(transaction["fraud_status"], transaction["transaction_status"])
```

**PHP**

```php
<?php

$baseUrl       = 'https://api.sandbox.caas.qitech.app';
$apiKey        = 'YOUR_API_KEY';
$transactionId = '678';

$ch = curl_init("{$baseUrl}/card_issuance/transaction/{$transactionId}");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 5,
    CURLOPT_HTTPHEADER     => ['Authorization: ' . $apiKey],
]);

$body   = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status === 404) {
    throw new RuntimeException("Transação {$transactionId} não encontrada.");
}

$transaction = json_decode($body, true);
echo $transaction['fraud_status'];
```

**Node.js**

```javascript
const BASE_URL = "https://api.sandbox.caas.qitech.app";
const API_KEY = "YOUR_API_KEY";
const TRANSACTION_ID = "678";

async function getTransaction() {
  const response = await fetch(
    `${BASE_URL}/card_issuance/transaction/${TRANSACTION_ID}`,
    { headers: { Authorization: API_KEY } },
  );

  if (response.status === 404) {
    throw new Error(`Transação ${TRANSACTION_ID} não encontrada.`);
  }

  const transaction = await response.json();
  console.log(transaction.fraud_status, transaction.transaction_status);
  return transaction;
}

getTransaction();
```

**Java**

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class GetTransaction {

    private static final String BASE_URL = "https://api.sandbox.caas.qitech.app";
    private static final String API_KEY = "YOUR_API_KEY";
    private static final String TRANSACTION_ID = "678";

    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newHttpClient();

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(BASE_URL + "/card_issuance/transaction/" + TRANSACTION_ID))
                .header("Authorization", API_KEY)
                .timeout(Duration.ofSeconds(5))
                .GET()
                .build();

        HttpResponse<String> response =
                client.send(request, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() == 404) {
            throw new IllegalStateException("Transação " + TRANSACTION_ID + " não encontrada.");
        }

        System.out.println(response.body());
    }
}
```

**C#**

```csharp
using System;
using System.Net;
using System.Net.Http;
using System.Threading.Tasks;

public class GetTransaction
{
    private const string BaseUrl = "https://api.sandbox.caas.qitech.app";
    private const string ApiKey = "YOUR_API_KEY";
    private const string TransactionId = "678";

    public static async Task Main()
    {
        using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(5) };
        client.DefaultRequestHeaders.Add("Authorization", ApiKey);

        var response = await client.GetAsync(
            $"{BaseUrl}/card_issuance/transaction/{TransactionId}");

        if (response.StatusCode == HttpStatusCode.NotFound)
        {
            throw new InvalidOperationException($"Transação {TransactionId} não encontrada.");
        }

        Console.WriteLine(await response.Content.ReadAsStringAsync());
    }
}
```

**curl**

```bash
curl 'https://api.sandbox.caas.qitech.app/card_issuance/transaction/678' \
  -H 'Authorization: YOUR_API_KEY'
```

### Resposta

A resposta devolve todos os campos que você enviou no `POST`, acrescidos dos campos abaixo.

fraud_status
enum
Recomendação atual do antifraude.

transaction_status
enum
Situação atual da transação.

brl_converted_amount
integer
Valor convertido para reais, em centavos, calculado pela QI Tech.

transaction_events
array
Histórico de mudanças de status da transação, em ordem cronológica.

**Campos de `transaction_events[]`:**

new_status
enum
Status atribuído neste evento.

event_date
datetime
Data e hora do evento, em UTC.

partial_amount
integer
Presente apenas em eventos parciais.

response_code
string
Presente quando informado na atualização.

fraud_events
array
Histórico de decisões do antifraude.

**Campos de `fraud_events[]`:**

new_status
enum
Decisão atribuída neste evento.

event_date
datetime
Data e hora da decisão, em UTC.

decision_metadata
object
Motivo da decisão. Traz reason e reason_description explicando por que a transação foi aprovada ou recusada.

```json
{
  "id": "678",
  "cardholder_id": "b812da2e-e6be-4712-8e57-6f3f2791625b",
  "amount": 13725,
  "brl_converted_amount": 13725,
  "currency": "BRL",
  "installments": 1,
  "authorization_date": "2026-08-07T13:25:42-03:00",
  "authorization_type": "authorization",
  "transaction_type": "credit",
  "pan_entry_mode": "chip",
  "pin_sent": true,
  "terminal": { "country_code": "BRA" },
  "merchant": {
    "acquirer_id": "250",
    "merchant_id": "123456",
    "mcc": "5411"
  },
  "card": {
    "brand": "visa",
    "category": "black",
    "bin": "498406",
    "last4": "1234",
    "issuer_country_code": "BRA"
  },
  "fraud_status": "automatically_approved",
  "transaction_status": "captured",
  "fraud_events": [
    {
      "new_status": "automatically_approved",
      "event_date": "2026-08-07T16:25:43Z",
      "decision_metadata": {
        "reason": "automatically_approved",
        "reason_description": "O padrão transacional foi normal."
      }
    }
  ],
  "transaction_events": [
    {
      "new_status": "authorized",
      "event_date": "2026-08-07T16:25:43Z"
    },
    {
      "new_status": "captured",
      "event_date": "2026-08-07T18:02:10Z",
      "response_code": "00"
    }
  ]
}
```

---

## Erros

Todos os erros retornam um corpo JSON com o mesmo formato:

```json
{
  "title": "Duplicated external_id",
  "description": "id: 678 already exists for company 3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
```

| Status | Situação | Como resolver |
| --- | --- | --- |
| 400 | Payload inválido: campo obrigatório ausente, enum fora da lista, formato de data incorreto ou campo não previsto pelo schema. | Confira a `description`, que aponta o campo com problema. |
| 400 | `Transaction has a final status` no `PUT`. | A transação já está em status final e não aceita novas atualizações. |
| 400 | `partial_amount` maior que o valor disponível. | Envie um valor menor ou igual ao saldo ainda não cancelado. |
| 401 | Header `Authorization` ausente ou API Key desativada. | Verifique o header e o status da sua chave. |
| 403 | API Key inválida ou endpoint de uso interno. | Confirme a chave com o [suporte](mailto:suporte.caas@qitech.com.br). |
| 404 | Transação não encontrada para a sua API Key. | Verifique o `id` usado no path. |
| 406 | Corpo da requisição não é um JSON válido. | Verifique o `Content-Type` e a serialização. |
| 409 | `id` já processado anteriormente. | Gere um `id` único por processo de autorização. |
| 500 | Erro interno. | Nossos especialistas são notificados automaticamente. |
| 503 | Indisponibilidade de infraestrutura. | Aplique retry com backoff. |

A lista completa está em [Status HTTP](/documentation/caas/card_issuance/http_status).

---

## Testando no Sandbox

No Sandbox as análises não são cobradas e a decisão é determinística, baseada apenas no valor da transação:

| `amount` | `fraud_status` retornado |
| --- | --- |
| `>= 10000` (R$ 100,00 ou mais) | `automatically_approved` |
| `<= 9999` (até R$ 99,99) | `automatically_declined` |

Base URL de Sandbox: `https://api.sandbox.caas.qitech.app`

:::danger Aviso importante
Não utilize dados reais de pessoas físicas ou jurídicas no ambiente de Sandbox da QI Tech.
:::

---

## Checklist de integração

- [ ] `POST /card_issuance/transaction` com o payload mínimo retornando `200` no Sandbox.
- [ ] `id` único garantido por processo de autorização (teste o `409` reenviando o mesmo `id`).
- [ ] `cardholder_id` estável para o mesmo portador entre transações.
- [ ] `authorization_date` no formato com offset `:00` ou `:30`.
- [ ] Valores monetários em centavos, como inteiros.
- [ ] Tratamento de timeout com política de fallback definida (aprovar ou negar por conta própria).
- [ ] `PUT` enviado em todos os desfechos: captura, cancelamento, chargeback.
- [ ] Webhook de [Alertas de Portadores](/documentation/caas/card_issuance/alerts) configurado com o suporte.

---

# authentication

URL: /documentation/caas/card_order/authentication

## Autenticação

> Para autenticar uma chamada, utilize o código seguinte:

```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE_API_KEY"
```

> Substitua a API key 'EXAMPLE_API_KEY' com a sua chave adquirida com o nosso suporte.

Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br .

Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:

`Authorization: EXAMPLE_API_KEY`

:::info **Atenção**

Você deve substituir EXAMPLE_API_KEY com a API Key recebida do suporte.
:::

---

# Status HTTP

URL: /documentation/caas/card_order/http_status

Todas as APIs da QI Tech utilizam a seguinte padronização nos status HTTP de retorno, de acordo com o RFC 7231 :

Status HTTP | Significado | Descrição
---------- | ------- | ---------------------------------
400 | Bad Request | A requisição enviada possui algum erro de formatação. Na maioria dos casos, retornamos no corpo da mensagem uma explicação de onde está o erro.
401 | Unauthorized | Houve algum problema na autenticação, verifique se a API Key está correta e no header correto, de acordo com a seção Autenticação .
403 | Forbidden | O endpoint acessado é de uso interno e não está disponível para esta API Key.
404 | Not Found | O dado requisitado não foi encontrado usando a chave utilizada. Este status também é retornado quando um endpoint inválido é requisitado.
405 | Method Not Allowed | O método HTTP utilizado não se aplica ao endpoint utilizado.
406 | Not Acceptable | Os dados enviados no corpo da requisição são inválidos. Em geral, isso significa que os dados enviados não são um JSON válido.
409 | Conflict | O id da requisição corresponde a um id já processado anteriormente. Este status é retornado no caso de requisições duplicadas enviadas ao servidor.
500 | Internal Server Error | Tivemos um problema para processar esta requisição, ao encontrarmos esse erro nossos especialistas são automaticamente notificados e iniciam a análise e solução imediatamente.
503 | Service Unavailable | Você se deparou com uma indisponibilidade, planejada ou não, de infraestrutura dos nossos servidores.

---

# Introdução

URL: /documentation/caas/card_order/introduction

Bem vindo à API de Prevenção a Fraudes em transações de cartões da QI Tech! Você pode utilizar a nossa API para acessar os endpoints, a fim de receber a resposta de uma transação, e enviar transações para a QI Tech gerar alertas de usuários fraudadores ou sellers fraudadores, além de utilizar para atualizar a situação de uma transação.

:::info **Atenção**

Atenção, esta API é direcionada para merchants que recebam transações de cartão não presente, que estão sujeitas a chargeback de fraude, ou seja, empresas que realizam suas vendas por meio de aplicativos ou de website e recebem o pagamento por meio de cartão de crédito ou débito.
:::

Abaixo, você pode observar a implementação da API utilizando cUrl. Com isso você possui exemplos para poder adaptar adequadamente à linguagem de programação da sua preferência.

## Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso suporte e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

### Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

## Ambientes

Possuímos dois ambientes para os nossos clientes. As URLs base das APIs são:

* Produção - `https://api.caas.qitech.app/card_order/`
* Sandbox - `https://api.sandbox.caas.qitech.app/card_order/`

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.  
:::

No ambiente de Sandbox, as análises enviadas não são cobradas e são respondidas de acordo com regras pré estabelecidas.

Para a análise de uma transação, a seguinte regra é aplicada sobre o valor da transação:

Mínimo | Máximo | Decisão
------ | ------ | -------
0 | 1000 | Aprovado Automaticamente
1001 | 2000 | Derivado para análise manual - Posteriormente aprovado
2001 | 3000 | Derivado para análise manual - Posteriormente reprovado
3001 | 4000 | Reprovado Automaticamente
4001 | 5000 | Não analisado
5001 | - | Pendente

## Somente HTTPS

Por questão de segurança, toda a comunicação com as APIs da QI Tech deve ser realizada utilizando a comunicação HTTPS. Para evitar que, por desatenção ou outro motivo, sejam feitas chamadas HTTP, este servidor somente disponibiliza a porta 443 com comunicação TLS 1.2. Chamadas realizadas utilizando outros protocolos serão automaticamente negadas.

## Autenticação

> Para autenticar uma chamada, utilize o código seguinte:

```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE_API_KEY"
```

> Substitua a API key 'EXAMPLE_API_KEY' com a sua chave adquirida com o nosso suporte.

Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br .

Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:

`Authorization: EXAMPLE_API_KEY`

:::info **Atenção**

Você deve substituir EXAMPLE_API_KEY com a API Key recebida do suporte.
:::

---

# Objetos

URL: /documentation/caas/card_order/objects

## Objeto *address*

Request Body

```json
{
  "street": "Rua do Exemplo, 111",
  "neighborhood": "Bairro do Teste",
  "city": "Aparecida de Goiânia",
  "uf": "GO",
  "complement": "",
  "postal_code": "00000-000",
  "country": "BRA"
}
```

O objeto *address* é utilizado para representar endereços em toda a API, endereços no território brasileiro são representados da seguinte maneira:

nome | tipo | descrição
---- | :----: | ---------
street | string | *(obrigatório)* Rua do endereço, incluindo o logradouro, evitando, se possível, abreviações.
number | string | Número do imóvel, incluindo letras caso possua.
neighborhood | string | *(obrigatório)* Bairro, sem abreviações. **e.g.: Santa Felicidade**
city | string | *(obrigatório)* Nome completo da cidade, sem abreviações
uf | string | *(obrigatório)* A unidade federativa, com duas letras maiúsculas. **e.g.: SP**
complement | string | Quaisquer complementos para localizar o imóvel. **e.g.: Apartamento 101, Conjunto 12**
postal_code | string | *(obrigatório)* O código postal da localidade, contendo o hífen.
country | string | *(obrigatório)* Código ISO 3166-1 alfa-3 do país do endereço.

No caso dos endereços cujo país não seja Brasil ("BRA"), o postal_code e a unidade federativa poderão ser preenchidos livremente.

## Objeto *payment*

Request Body

```json
{
  "total_amount": 10000,
  "shipping_amount": 500,
  "currency": "BRL",
  "is_recurrence": false,
  "transactions": [ . . . ]
}
```

Um pagamento é representado pelo objeto *payment*, que possui os seguintes campos:

nome | tipo | descrição
---- | :----: | ---------
total_amount | inteiro | *(obrigatório)* Valor monetário total pago
shipping_amount | inteiro | Valor do frete cobrado para entrega
currency | Enumerador | *(obrigatório)* Moeda de pagamento de acordo com a ISO 4217
is_recurrence | boolean | *(obrigatório)* Caso este seja um pagamento de recorrência, indicar true nesta flag
transactions | Array de Transaction | *(obrigatório)* Lista de transações que foram realizadas para o pagamento do pedido (Pagamento com múltiplos cartões)

## Objeto *transaction* - Cartão de Crédito

Request Body

```json
{
  "id": "124234",
  "amount": 10000,
  "bin": "123456",
  "last_4": "1234",
  "cardholder_name": "JOHN SAMPLE",
  "card_fingerprint": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "expiration_date": "2020-11",
  "installments": 6,
  "processor": "stone",
  "payment_type": "credit"
}
```

Uma transação é representada pelo objeto *transaction*, que possui os seguintes campos:

nome | tipo | descrição
---- | :----: | ---------
id | string | *(obrigatório)* Um identificador no sistema do cliente da transação, deve ser único por pedido
amount | integer | *(obrigatório)* Valor monetário que representa o valor pago
bin | string | *(obrigatório)* BIN do cartão utilizado no pagamento
last4 | string | *(obrigatório)* Quatro últimos dígitos do cartão utilizado no pagamento
cardholder_name | string | *(obrigatório)* Nome do portador, como está escrito no cartão
card_fingerprint | string | *(obrigatório)* Identificador do cartão no sistema do cliente ("Token")
expiration_date | string | Data de vencimento definida pelo cartão (YYYY-DD)
installments | integer | *(obrigatório)* Número de parcelas do pagamento
processor | enumerador | *(obrigatório)* Adquirente ou subadquirente responsável pelo processamento da transação
payment_type | enumerador | *(obrigatório)* Tipo de meio de pagamento
status | enumerador | Opcional - Último status da transação no momento do envio para a QI Tech - Útil para envio de transações não autorizadas

Enumeradores disponíveis para processor:
* cielo
* rede
* stone
* getnet
* adyen
* global_payments
* pagseguro

## Objeto *transaction* - PIX

Request Body

```json
{
  "id": "124234",
  "amount": 10000,
  "payment_type": "pix"
}
```

Uma transação é representada pelo objeto *transaction*, que possui os seguintes campos:

nome | tipo | descrição
---- | :----: | ---------
id | string | *(obrigatório)* Um identificador no sistema do cliente da transação, deve ser único por pedido
amount | integer | *(obrigatório)* Valor monetário que representa o valor pago
payment_type | enumerador | *(obrigatório)* Tipo de meio de pagamento

## Objeto *dict_key*

Request Body

```json
  {
    "key_type": "cpf",
    "key_value": "09991222669"
  }
```

O objeto **dict_key**  é utilizado para representar os dados da chave de vínculo no DICT do cliente, seja ele o recebedor ou o pagador da transação. Os campos desse objeto são:

nome | tipo | descrição
:----: | :----: | ---------
key_type        | string | Enumerador que contém o tipo da chave de vinculo no DICT.
key_value       | string | Contém a chave de vínculo cadastrada no DICT.

Os enumeradores para o campo *key_type* são os mesmos definidos na API do DICT: `cpf`,`cnpj`,`email`,`phone` e `evp`.

## Objeto *account*

Request Body

```json
{
    "participant": "17315359",
    "branch": "0000",
    "account_number": "10442",
    "account_digit": "6",
    "account_type": "CACC"
}
```

Objeto que representa os dados de uma conta.

nome | tipo | descrição
:----:  | :----:  | ---------
participant                 | string | ISPB da instituição detentora da conta
branch                      | string | Agência da Conta
account_number              | string | Número da Conta sem o dígito
account_digit               | string | Dígito da conta
account_type                | enum | Tipo da conta de origem, possíveis valores: "CACC", "SLRY" e "SVGS"

## Objeto *phone*

Request Body

```json
{
  "international_dial_code": "1",
  "area_code": "11",
  "number": "999999999",
  "type": "mobile",
  "validated": false
}
```

Um objeto phone representa um número telefônico, dentro ou fora do Brasil e sua classificação. Para isso, os campos são:

nome | tipo | descrição
---- | :----: | ---------
international_dial_code | string | *(obrigatório)* Código de discagem internacional, sem zero ou +, somente números
area_code | string | *(obrigatório)* Código de área, sem zero, somente números
number | string | *(obrigatório)* Número do telefone, sem o hífen
type | enum | *(obrigatório)* Tipo de número: celular, residencial, comercial, etc.
validated | booleano | Caso o número de telefone tenha sido validado (SMS ou Ligação), enviar true neste campo

Existem os seguintes enumeradores para tipo de telefone: `residential`, `commercial`, `mobile`

## Objeto *seller*

Request Body

```json
{
  "id": "COD",
  "name": "Restaurante do Aeroporto de Congonhas",
  "type": "legal_person",
  "document_number": "00.000.000/0001-00",
  "email": "seller@gmail.com",
  "registration_date": "2019-12-20T15:23:12-03:00",
  "url": "https://www.qitech.com.br",
  "phone": {
      "international_dial_code": "1",
      "area_code": "11",
      "number": "999999999",
      "type": "mobile"
  },
  "address": {
    "street": "Rua do Exemplo",
    "neighborhood": "Bairro do Teste",
    "city": "Aparecida de Goiânia",
    "number": "1000",
    "uf": "GO",
    "complement": "Térreo",
    "postal_code": "00000-000"
  }
}
```

O objeto *seller* representa uma loja ou vendedor que realiza a venda ou entrega do pedido. Os dados a serem enviados podem ser vistos abaixo:

nome | tipo | descrição
---- | :----: | ---------
id | string | *(obrigatório)* O código identificador da loja (Ou vendedor em MarketPlace) no cliente
name | string | *(obrigatório)* O nome da loja (Ou vendedor em MarketPlace)
type | enum | Enumerador que representa se o seller é uma pessoa física ou pessoa jurídica
document_number | string | *(obrigatório)* O CNPJ ou CPF do seller
url | string | Endereço para a página do seller na plataforma
email | string | O e-mail do seller
registration_date | date | *(obrigatório)* A data de cadastro do seller
phone | *phone* | O telefone do seller
address | *address* | *(obrigatório)* O endereço da loja, caso seja uma loja física

Enumeradores de type:

* `natural_person`
* `legal_person`

## Objeto *customer*

Request Body

```json
{
  "id": "5ce7fab5-8165-44a5-9b89-bb2d6d61e4f4",
  "name": "Mary Sample",
  "gender": "female",
  "document_number": "000.000.000-00",
  "registration_date": "2019-12-20T15:23:12Z",
  "email": "test@sample.com",
  "birthdate": "1990-01-02",
  "address": { . . . },
  "phone": { . . . }
}
```

O objeto customer representa os dados de quem realizou a compra do pedido, com o próprio cartão de crédito. Ele é composto por:

nome | tipo | descrição
---- | :----: | ---------
id | string | *(obrigatório)* Um identificador único do comprador ou usuário
name | string | *(obrigatório)* Nome completo
gender | enum | O gênero do customer, de acordo com a lista de enumeradores.
document_number | string | *(obrigatório)* O CPF, formatado adequadamente
registration_date | date | A data quando o usuário se cadastrou no sistema do cliente
email | string | *(obrigatório)* O e-mail do usuário
birthdate | date | A data de nascimento do customer
address | *address* | *(obrigatório)* O endereço residencial do comprador/usuário
phone | *phone* | *(obrigatório)* O telefone colhidos do comprador/usuário

Enumeradores de gênero:

* `male`
* `female`

## Objeto *device*

Request Body

```json
{
  "session_id": "595c46c1-b8c2-449d-8a86-6aeba2e5b0da",
  "platform": "android",
  "browser": "chrome",
  "ip": "243.178.100.37"
}
```

O objeto device descreve dados do dispositivo usado para realizar a compra. Os seguintes dados são passados:

nome | tipo | descrição
---- | :----: | ---------
session_id | string | *(obrigatório)* O identificador da sessão, repassada também no device scan
platform | enumerador | Enumerador do sistema operacional em uso
browser | enumerador | Enumerador do browser em uso (Ou aplicativo)
ip | string | O ip de origem da compra, de acordo com a padronização desta documentação. **Atenção, IPs iniciados em 10.* , 172.16.* e 192.168.* em geral são internos e portanto não são aplicáveis para prevenção a fraudes**

Enumeradores de plataforma:
* `android`
* `ios`
* `windows`
* `linux`

Enumeradores de browser:
* `firefox`
* `chrome`
* `safari`
* `app`

---

# Order

URL: /documentation/caas/card_order/order

Antes de realizar a entrega/envio de um produto ou a liberação de créditos para o seu cliente ou seller, você deve enviar os dados do pedido para a nossa API para que possamos lhe responder a nossa recomendação com relação a fraude. É muito importante que os dados enviados sejam os dados finais, que não serão alterados. Isto é muito importante para garantir dois pontos:

* Consistência dos dados na base de dados do Antifraude
* Avaliação realista do risco

O processo de análise consiste em enviar uma Order no endpoint adequado e esperar a resposta. Existem quatro resultados possíveis, devolvido na flag **analysis_status**:

Resultado | Descrição
:---------: | ---------
Aprovado Automaticamente | Recomenda-se que este pedido seja aprovado
Negado Automaticamente | Recomenda-se que este pedido seja reprovado
Derivado para análise manual | Nossas regras ou modelos não estão confiantes da decisão e decidiram enviar este pedido para a análise manual.
Aprovado Manualmente | Após análise manual, o analista escolheu aprovar o pedido
Reprovado Manualmente | Após análise manual, o analista escolheu reprovar o pedido
Pendente | As consultas estão demorando mais do que o esperado, este pedido entrou em uma fila de análise automática e será respondido por meio de Webhook
Não analisado | A consulta foi enviada com a flag de análise falsa, ou trata-se de uma análise exclusivamente para geração de alertas, o que significa que nossos sistemas não deverão retornar recomendação na resposta da Order

:::info **Atenção**
Caso o seu modelo de negócio demande, o motor da QI Tech pode ser configurado para que nenhum pedido seja derivado para análise manual, e nem para o estado Pendente. Assim, o seu usuário poderá receber imediatamente a confirmação da transação.
:::

### Dinâmica dos Status

Ao recuperar um objeto do tipo Order os status estão disponíveis. Além dos status, um histórico de modificações também são retornados para que possa ser consultado no futuro. Estas modificações são entituladas events e possuem, além do novo status, as datas de modificação.

### Dinâmica dos Status - **payment_status**

O status **payment_status** relacionado a um Pedido indica a situação do pagamento relacionado a este pedido, isto é, se a transação foi efetivamente aprovada, se foi cancelada ou se recebeu um chargeback de fraude. Os seguintes status de pagamento estão disponíveis:

* open
* not_authorized
* authorized
* captured
* cancelled
* chargeback

:::info **Atenção**

É de suma importância que o status de pagamento seja enviado para a QI Tech pois ele é utilizado como base para treinamento dos nossos modelos. No caso de chargeback, é muito importante que o reason_code seja enviado corretamente, como será explicado em seguida.
:::

### Dinâmica dos Status - **analysis_status**

O status **analysis_status** indica o status da decisão do motor de fraude e possui uma máquina de estados bastante simples:

* created
* automatically_approved
* automatically_reproved
* in_manual_analysis
* manually_approved
* manually_reproved
* pending
* not_analyzed

## Definição do Objeto

Request Body

```json
{
	"id": "12345678",
	"is_one_dollar_auth": false,
	"seller": {
		"id": "COD",
		"name": "Restaurante do Aeroporto de Congonhas",
		"type": "legal_person",
		"document_number": "00.000.000/0001-00",
		"email": "seller@gmail.com",
		"registration_date": "2019-12-20T15:23:12-03:00",
		"url": "https://www.qitech.com.br",
		"phone": {
			"international_dial_code": "1",
			"area_code": "11",
			"number": "999999999",
			"type": "mobile",
			"validated": true
		},
		"address": {
			"street": "Rua do Exemplo",
			"neighborhood": "Bairro do Teste",
			"city": "Aparecida de Goiânia",
			"number": "1000",
			"uf": "GO",
			"complement": "Térreo",
			"postal_code": "00000-000",
			"country": "BRA"
		}
	},
	"payment": {
		"total_amount": 10000,
		"shipping_amount": 500,
		"currency": "BRL",
		"is_recurrence": false,
		"transactions": [{
			"id": "124234",
			"amount": 8000,
			"bin": "123456",
			"last_4": "1234",
			"cardholder_name": "JOHN SAMPLE",
			"card_fingerprint": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
			"expiration_date": "2020-11",
			"installments": 6,
			"processor": "stone",
			"payment_type": "credit",
			"status": "not_authorized"
		}]
	},
	"shipping": {
		"name": "Mary Sample",
		"gender": "female",
		"document_number": "000.000.000-00",
		"birthdate": "1990-01-02",
		"email": "test@sample.com",
		"address": {
			"street": "Rua do Exemplo, 123",
			"neighborhood": "Bairro do Teste",
			"city": "Aparecida de Goiânia",
			"number": "1000",
			"uf": "GO",
			"complement": "",
			"postal_code": "00000-000",
			"country": "BRA"
		},
		"phone": {
			"international_dial_code": "1",
			"area_code": "11",
			"number": "999999999",
			"type": "mobile",
			"validated": true
		},
		"scheduled_date": "2020-01-10",
		"shipping_method": "regular"
	},
	"customer": {
		"id": "5ce7fab5-8165-44a5-9b89-bb2d6d61e4f4",
		"name": "Mary Sample",
		"gender": "female",
		"document_number": "000.000.000-00",
		"registration_date": "2019-12-20T15:23:12-03:00",
		"email": "test@sample.com",
		"birthdate": "1990-01-02",
		"address": {
			"street": "Rua do Exemplo, 123",
			"neighborhood": "Bairro do Teste",
			"city": "Aparecida de Goiânia",
			"number": "1000",
			"uf": "GO",
			"complement": "",
			"postal_code": "00000-000",
			"country": "BRA"
		},
		"phone": {
			"international_dial_code": "1",
			"area_code": "11",
			"number": "999999999",
			"type": "mobile",
			"validated": true
		}
	},
	"device": {
		"session_id": "595c46c1-b8c2-449d-8a86-6aeba2e5b0da",
		"platform": "android",
		"browser": "chrome",
		"ip": "243.178.100.37"
	},
	"products": [{
		"product_code": "latte-machiatto-30",
		"name": "Latte Machiatto 30cl",
		"description": "Latte Machiatto 30cl para levar, leite integral",
		"sku": "1234",
		"quantity": 2,
		"unit_cost": 5000
	}],
	"order_date": "2020-01-03T15:35:12.454-03:00"
}
```

Todas as trocas de informação de um pedido utilizam a seguinte definição para este objeto. Em alguns casos, para facilitar a implementação e diminuir o fluxo de dados entre as partes, algumas informações poderão ser omitidas.

nome |                  tipo                  | descrição
:----: |:--------------------------------------:| ---------
id | string | Identificador do pedido no sistema do cliente. **É essencial que este valor seja único para cada pedido** (Obrigatório)
is_one_dollar_auth |                booleano                | Se esta for uma transação somente para validação do cartão, enviar com essa flag true (Obrigatório)
seller |             Objeto Seller              | Os dados da loja onde a venda está sendo realizada. No caso de um market place, são os dados do vendedor. No caso de um aplicativo, são os dados da loja de retirada (Obrigatório)
payment |             Objeto Payment             | Dados do pagamento do pedido (Obrigatório)
customer |            Objeto Customer             | Dados do cliente/usuário (Obrigatório)
shipping |            Objeto Shipping             | Dados da entrega do pedido - Deve ser preenchido em casos de produtos de entrega física 
device |             Objeto Device              | Dados do aparelho/navegador onde o pedido é realizado
products |            Array de Product            | Os produtos sendo comprados (Obrigatório)
order_date |          Data Hora            | Data e hora de realização do pedido (Obrigatório)

## Enviar um Pedido

Request Body

```json
  {
    "id": "12345",
    ...
  }
```

Response Body

```json
  {
    "id": "12345",
    "analysis_status": "automatically_approved"
  }
```

Para realizar a avaliação de um pedido, basta enviar um objeto do tipo Order ao seguinte endpoint:

`POST https://api.caas.qitech.app/card_order/order`

## Atualizar o status de um Pedido

Request Body

```json
{
  "transaction_status": "chargeback"
}
```

Para garantir a retroalimentação das regras e do modelo de inteligência artificial implementado, é necessário informar ao sistema quando as transações são autorizadas, capturadas, canceladas ou recebem chargeback. Para isso, requisições com o método PUT devem ser utilizadas, autenticadas normalmente:

`PUT https://api.caas.qitech.app/card_order/order/12345678/transaction/124234`

Existem os seguintes enumeradores para *transaction_status*: `open`, `not_authorized`, `authorized`, `captured`, `cancelled`, `chargeback`

## Recuperar um Pedido

A fim de recuperar um Pedido específico, basta realizar uma requisição GET. O resultado retornado é o json mais atualizado do Pedido em questão. Caso este identificador não esteja relacionado a nenhum objeto, o HTTP Status 404 é retornado.

`GET https://api.caas.qitech.app/card_order/order/12345678`

```shell
curl "https://api.caas.qitech.app/card_order/order/12345678"
  -H "Authorization: EXAMPLE_API_KEY"
```

> O comando acima retorna o JSON que representa um objeto de CardOrder.

## Buscar CardOrders

Response Body

```json
[
  {
    "id": "12345",
    ...
  },
  {
    "id": "12345",
    ...
  }
]
```

> Retorna um JSON que representa uma lista de objetos CardOrder.

Caso seja necessário buscar um CardOrder, um GET com parâmetros de query poderá ser utilizado. O resultado retornado é um JSON que representa uma lista de CardOrders. Caso nenhum objeto seja encontrado com os parâmetros enviados, o HTTP Status 200 é retornado com uma lista vazia no corpo da resposta.

`GET https://api.caas.qitech.app/card_order/order?initial_date=2019-10-01&final_date=2019-10-05&page_number=2&page_rows=20`

Os seguintes parâmetros podem ser utilizados para buscar objetos de CardOrder:

Parâmetro | Padrão | Descrição
--------- | ----------- | --------------
initial_date | null | Primeira data que deve ser retornada a partir do campo order_date
final_date | null | Última data que deve ser retornada a partir do campo order_date
page_number | 1 | Número da página de resultados desejada
page_rows | 50 | Número de objetos máximo a ser retornados em uma consulta

---

# Padrões

URL: /documentation/caas/card_order/standards

Para facilitar a integração e garantir a integridade da informação, foram definidos alguns padrões que são seguidos em toda a API.

## Valores Monetários
> Exemplos:

```
10000
12345
98741
1223
1
0
```

As APIs assumem que todos os valores monetários enviados são em Reais Brasileiros. Os valores devem ser enviados como inteiro em centavos.

## Data e Hora com Fuso Horário
> Alguns exemplos:

```
2019-10-15T22:35:12-03:00
2018-05-01T13:32:11+00:00
2019-05-01T00:00:00+00:00
```

É representada conforme a ISO 8601. Neste caso, o fuso-horário é colocado logo após o horário e deve representar o fuso do local onde aquele dado será valido. Por exemplo, se um aluguel estiver marcado para começar às 09:30 no aeroporto de Brasília, o horário enviado deverá ser representado por 09:30-03:00, se o aluguel estiver marcado para começar às 09:30 em Manaus, deverá ser representado por 09:30-04:00.

A máscara utilizada para validação é a seguinte:

`YYYY-MM-ddThh:mm:ss±hh:mm`

## Data e Hora sem Fuso Horario
> Alguns exemplos:

```
2019-10-15T22:35:12Z
2018-05-01T13:32:11Z
2019-05-01T00:00:00Z
```

É representada conforme a ISO 8601. Dados que independem de fuso-horário deverão ser enviados sem ele, sempre em UTC, com a letra Z indicando que este dado está em UTC. O seguinte formato, portanto, será validado:

`YYYY-MM-ddThh:mm:ssZ`

## Data
> Alguns exemplos

``` 
2019-10-15
2019-01-01
2017-03-20
```

No caso de campos que recebem somente data, uma data de nascimento, por exemplo, somente a data, sem nenhum horário deve ser enviada com o seguinte formato:

`YYYY-MM-dd`
 

## Documentos
Uma vez que os números de documento são bastante variados e muitos deles possuem caracteres que não se enquadram como numéricos, definem-se todos os números de documento como string. Outro bom motivo para definí-los como string é evitar que os zeros à esquerda desapareçam. Documentos previstos nesta página possuem uma máscara bem definida e estarão sujeitos a validação. O restante dos documentos, como RG, dada sua falta de padronização, não serão validados.

## CPF

> Exemplos de CPFs válidos contra a máscara definida:

```
123.456.789-12
321.987.543-23
111.283.333-00
```

> Exemplos de CPFs inválidos contra a máscara definida:

```
8.577.477-8
08.104.627/0001-23
123.456.789-1
23.456.789-01
```

O CPF é sempre definido como uma string e será validado conta a máscara:

`###.###.###-##`

## CNPJ

> Exemplos de CNPJs válidos contra a máscara definida:

```
08.104.627/0001-02
01.079.210/0114-67
32.402.502/0001-35
```

> Exemplos de CNPJs inválidos contra a máscara definida:

```
8.577.477-8
123.456.789-12
321.987.543-23
32.402.502/0001-3
032.402.502/0001-3
```

O CNPJ é sempre definido como uma string e será validado conta a máscara:

`##.###.###/####-##`

## IP

> Exemplos de IPs válidos contra a máscara definida:

```
201.81.161.86
201.081.161.86
201.81.161.086
201.81.0.1
```

> Exemplos de IPs inválidos:

```
201.81..86
358.81.161.86
201.81.161
```

IPs deverão ser enviados sempre em IPv4, zeros à esquerda poderão ou não ser enviados, respeitando a seguinte máscara:

`###.###.###.###`

---

# Webhook

URL: /documentation/caas/card_order/webhook

Webhook

Atualizações no status de fraude (Para Orders que sejam derivados para análise manual ou que sejam respondidos como Pendente) e para Sellers bloqueados, são notificados por meio de Webhook. Para tanto, é necessário, por meio da equipe do [suporte](mailto:suporte.caas@qitech.com.br), configurar um endereço do endpoint por onde vamos notificar as atualizações e também uma *signature_key* que será utilizada para assinar a requisição.

No caso da atualização do status do pedido, o cliente pode também utilizar a técnica de [polling](https://en.wikipedia.org/wiki/Polling_(computer_science)). Neste caso, basta não configurar o endpoint de webhook e utilizar os endpoints de recuperação de Order para proceder com o polling.

:::info **Atenção**

Por questões de segurança, todas as requisições de Webhook serão somente realizadas em endpoints servidos por HTTPS.
:::

## Assinatura do Webhook

## Webhook de Atualização de Order

Request Body

```json
    {
        "order_id": "123456",
        "fraud_status": "automatically_approved",
        "event_date": "2019-10-01T10:37:25-03:00"
    }
```

A requisição de atualização do status de análise de uma order possui o formato acima e notifica a mudança no status de fraude. O método utilizado é um PUT e o endereço do endpoint pode conter também o id do pedido, de acordo com a necessidade do cliente. É importante ressaltar que o corpo da requisição é enviado como texto codificado em UTF-8.

Exemplos de endpoints para atualização de pedido:

* https://apidocliente.com.br/order
* https://apidocliente.com.br/admin/order/1214

O campo event_date indica a data e hora em que a notificação foi criada e pode estar no passado caso envios de notificação anteriores tenham falhado.

## Webhook de Atualização de Seller

> Exemplo de requisição de bloqueio de liquidação

Request Body

```json
    {
        "document_number": "000.000.000-00",
        "settlement_status": "blocked",
        "event_date": "2019-10-01T10:37:25-03:00"
    }
```

> Exemplo de requisição de bloqueio transacional

Request Body

```json
    {
        "document_number": "000.000.000-00",
        "transactional_status": "blocked",
        "event_date": "2019-10-01T10:37:25-03:00"
    }
```

Caso o bloqueio ou desbloqueio de um seller seja necessário, o sistema da QI Tech realizará uma requisição com o formato acima. O método utilizado é um PUT realizado em um endpoint configurável e pode conter, a critério do cliente, o número do documento no endereço do endpoint.

:::info **Atenção**

É a presença do campo settlement_status ou do campo transactional_status que determina o tipo de bloqueio ou desbloqueio que deve ser realizado no seller.
:::

Exemplos de endpoints para atualização de seller:

* https://apidocliente.com.br/seller
* https://apidocliente.com.br/admin/seller/000.000.000-00

Os seguintes status de liquidação podem ser notificados:

enumerador | descrição
---- | ---------:
blocked | A liquidação do seller deve ser bloqueada
unblocked | A liquidação do seller deve ser liberada

O campo event_date indica a data e hora em que a notificação foi criada e pode estar no passado caso envios de notificação anteriores tenham falhado.

## Retentativas

A notificação é considerada realizada quando recebe como resposta um HTTP Status 200. Caso as notificações falhem, serão feitas 7 retentativas, com os seguintes intervalos, até que um 200 seja retornado ou as tentativas terminem:

* 10 segundos
* 40 segundos
* 160 segundos
* 640 segundos
* 2560 segundos
* 10240 segundos
* 40960 segundos

---

# authentication

URL: /documentation/caas/credit_analysis/authentication

## Autenticação

> Para autenticar uma chamada, utilize o código seguinte:

```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

> Substitua a API key 'EXAMPLE-OF-API-KEY' com a sua chave adquirida com o nosso suporte.

Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br .

Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:

`Authorization: EXAMPLE-OF-API-KEY`

:::info **Atenção**

Você deve substituir EXAMPLE-OF-API-KEY com a API Key recebida do suporte.
:::

---

# Fluxo de Desafio

URL: /documentation/caas/credit_analysis/challenge_flow

É possível, após a execução da análise, ter como decisão desafiar o usuário para realizar uma nova ação em sua plataforma. Esse fluxo pode ser utilizado para, por exemplo, solicitar um comprovante de renda para um usuário que ainda não se tem certeza que deve ser aprovado ou reprovado na análise de crédito.

Com este fluxo você pode configurar uma regra cuja decisão desafia seu cliente a enviar informações adicionais para o sistema, como uma foto de um holerite ou qualquer outra informação relevante, e, depois de coletadas, utilização essas informações adicionais na execução de uma nova regra para reavaliação do usuário.

Há duas possibilidades de utilização deste fluxo, um deles de maneira automática, e outra fruto da decisão manual de um analista. Para o primeiro, o *analysis_status* retornado será *automatically_challenged* e para o segundo será *manually_challenged*. Abaixo temos a descrição do fluxo.
## Passo-a-passo da execução do fluxo

**1.** Proposta é submetida para análise (ver seção Análise de Crédito - Pessoa Física ou Análise de Crédito - Pessoa Jurídica ), e retornará o status *automatically_challenge* ou *in_manual_analysis*.

Request Body

```json
{
  "id": "12345",
  "registration_id":"12345",
  "credit_request_date": "2021-03-31T10:30:00-03:00",
  "credit_type": "clean",
  "name": "Victor Silva Barbosa",
  "document_number": "199.208.915-92",
  ...
}
```

Response Body

```json
{
  "id": "12345",
  "analysis_status": "automatically_challenge"
}
```

Caso a requisição retorne na resposta o status de *in_manual_analysis*, o analista poderá, através da dashboard, desafiar o usuário. Neste caso o status que será enviado na requisição de webhook é *manually_challenged*.

Response Body

```json
{
  "id": "12345",
  "analysis_status": "manually_challenged"
}
```

**2.** Após a primeira requisição de análise ter retornado um dos dois *analysis_status* de desafio, uma nova requisição deverá ser enviada com as informações adicionais coletadas do cliente, como por exemplo, uma novo imagem de documento enviada. Esta requisição deve conter o mesmo *registration_id* da requisição anterior, uma vez que este campo será utilizado para que a plataforma identifique que ambas as requsições se referem ao mesmo usuário, bem como vincular as informações adicionais coletadas do cliente. 

Request Body: Envio com informações adicionais

```json
{
  "id": "67890",
  "registration_id":"12345",
  "credit_request_date": "2021-03-31T10:30:00-03:00",
  "credit_type": "clean",
  "name": "Victor Silva Barbosa",
  "document_number": "199.208.915-92",
  "documents": {    
    "cnh": {
      "ocr_key":"a5cf9c8f-2f66-4490-a7db-8a5bc70c1b76"
    }
  }
  ...
}
```

Response Body

```json
{
  "id": "12345",
  "analysis_status": "automatically_approved"
}
```

Atente-se para utilizar o mesmo registration_id utilizado na sua primeira análise.

---

# Recuperar uma Análise de Crédito

URL: /documentation/caas/credit_analysis/get_credit_analysis

A fim de recuperar uma Análise de Crédito específica, basta realizar uma requisição GET. O resultado retornado é o json mais atualizado da Análise em questão. Caso este identificador não esteja relacionado a nenhum objeto, o HTTP Status 404 é retornado.

* **Natural Person:**

`GET https://api.caas.qitech.app/credit_analysis/natural_person/12345678`

* **Legal Person:**

`GET https://api.caas.qitech.app/credit_analysis/legal_person/12345678`

```shell
curl "https://api.caas.qitech.app/credit_analysis/natural_person/12345678"
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

> O comando acima retorna o JSON que representa um objeto de Natural Person.

```shell
curl "https://api.caas.qitech.app/credit_analysis/legal_person/12345678"
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

> O comando acima retorna o JSON que representa um objeto de Legal Person.

---

# Status HTTP

URL: /documentation/caas/credit_analysis/http_status

Todas as APIs da QI Tech utilizam a seguinte padronização nos status HTTP de retorno, de acordo com o RFC 7231 :

Status HTTP | Significado | Descrição
---------- | ------- | ---------------------------------
400 | Bad Request | A requisição enviada possui algum erro de formatação. Na maioria dos casos, retornamos no corpo da mensagem uma explicação de onde está o erro.
401 | Unauthorized | Houve algum problema na autenticação, verifique se a API Key está correta e no header correto, de acordo com a seção Autenticação .
403 | Forbidden | O endpoint acessado é de uso interno e não está disponível para esta API Key.
404 | Not Found | O dado requisitado não foi encontrado usando a chave utilizada. Este status também é retornado quando um endpoint inválido é requisitado.
405 | Method Not Allowed | O método HTTP utilizado não se aplica ao endpoint utilizado.
406 | Not Acceptable | Os dados enviados no corpo da requisição são inválidos. Em geral, isso significa que os dados enviados não são um JSON válido.
409 | Conflict | O id da requisição corresponde a um id já processado anteriormente. Este status é retornado no caso de requisições duplicadas enviadas ao servidor.
500 | Internal Server Error | Tivemos um problema para processar esta requisição, ao encontrarmos esse erro nossos especialistas são automaticamente notificados e iniciam a análise e solução imediatamente.
503 | Service Unavailable | Você se deparou com uma indisponibilidade, planejada ou não, de infraestrutura dos nossos servidores.

---

# Imagens

URL: /documentation/caas/credit_analysis/image

Em várias situações é necessário enviar imagens para a nossa API, a fim de realizar operações de OCR, FaceMatch e validação de documentos. Para tanto, é preciso inicialmente realizar o upload da imagem para depois enviá-la para análise.

Ao enviar uma imagem utilizando o endpoint /image uma GUID (Globally Unique Identifier) é retornada. Este valor deverá ser utilizado nas chamadas subsequentes para referenciar esta imagem.

O tamanho máximo de uma imagem aceita é de 10MB.

Neste momento, somente imagens com formato jpeg são aceitas.

## Envio

> Exemplo de envio utilizando o cUrl

```shell
    curl    -F "data=@path/to/local/file" \
            -H "Authorization: EXAMPLE-OF-API-KEY" \
            "https://api.caas.qitech.app/image?type=face"

```

Response Body

```json
    {
        "image_id": "f4b5337a-7b50-406e-8c8e-7d0e77b5aa02",
        "image_size": "134232",
        "image_dimensions": "630x230"
    }
```

Para enviar uma imagem, basta realizar o envio da imagem no formato .jpeg em `multipart/form-data` com uma requisição POST no endpoint:

`https://api.caas.qitech.app/api/image?type=$type`

Onde $type é a classificação da imagem e deve ser enviado conforme um dos seguintes enumeradores (Caso a imagem sendo enviada não se enquadre em nenhuma das classificações, entrar em contato com o [suporte](mailto:suporte.caas@qitech.com.br) para que providenciem a adição):

* face
* driver_license
* id
* contract

Após o envio, será retornado um objeto JSON com a GUID que aponta para a imagem que foi enviada.

## Recuperação dos Arquivos

> Leitura de imagem

```shell
    curl "https://api.caas.qitech.app/api/image/f4b5337a-7b50-406e-8c8e-7d0e77b5aa02/file" \
         -H "Authorization: EXAMPLE-OF-API-KEY"
```

Após o envio de uma imagem para a API, é possível recuperá-la por meio de uma requisição GET adequadamente autenticada no endpoint:

`https://api.caas.qitech.app/api/image/{image_key}/file`

Onde image_key é o valor retornado durante o envio da imagem.

## Recuperação dos meta-dados do arquivo

> Leitura de meta dados

```shell
    curl "https://api.caas.qitech.app/api/image/f4b5337a-7b50-406e-8c8e-7d0e77b5aa02" \
         -H "Authorization: EXAMPLE-OF-API-KEY"
```

Após o envio de uma imagem para a API, é possível recuperar os meta-dados da imagem utilizando o endpoint:

`https://api.caas.qitech.app/api/image/{image_key}`

Onde image_key é o valor retornado durante o envio da imagem.

---

# Introdução

URL: /documentation/caas/credit_analysis/introduction

Bem vindo à API de análise de crédito da QI Tech! Você pode utilizar a nossa API para acessar os endpoints, a fim de executar uma análise de crédito, além de utilizar para atualizar a situação de um crédito concedido.

:::info **Atenção**
Atenção, esta API é direcionada a empresas que concedem crédito para Pessoas Físicas e Jurídicas. Ela tem como objetivo realizar toda a análise de crédito das operações do seu cliente, a partir dos dados enviados, dos dados de bureaus e fontes externas e dos dados do datalake da QI Tech, de maneira a tornar claro o retorno vs risco de cada uma das operações.

Esta API é projetada para pessoas físicas e jurídicas de pequeno porte. Não está preparada para calcular o risco de crédito de pessoas jurídicas de grande porte, onde é necessário um conhecimento aprofundado da operação e do mercado onde a empresa atua.
:::

## Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso suporte e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

### Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

## Ambientes

Possuímos dois ambientes para os nossos clientes. As URLs base das APIs são:

* Produção - `https://api.caas.qitech.app/credit_analysis/`
* Sandbox - `https://api.sandbox.caas.qitech.app/credit_analysis/`

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.  
:::

No ambiente de Sandbox, as análises enviadas não são cobradas, são respondidas de acordo com regras pré estabelecidas e retornam dados fictícios, com o intuito exclusivo de simular o ambiente de produção para auxiliar o cliente no momento da integração.

Para a análise de uma operação de crédito, no ambiente de Sandbox, a decisão é aplicada sobre o valor total do crédito ( financial.amount ) a ser concedido, de acordo com a tabela abaixo:

Mínimo | Máximo | Decisão
------ | ------ | -------
10001 | - | Reprovado
8001 | 10000 | Análise Manual - Um webhook de reprovação manual é enviado após 1 minuto
6001 | 8000 | Análise Manual - Um webhook de aprovação manual é enviado após 1 minuto
4001 | 6000 | Aguardando Dados - Um webhook de aprovação automática é enviado após 1 minuto
2001 | 4000 | Pendente
0 | 2000 | Aprovado

## Somente HTTPS

Por questão de segurança, toda a comunicação com as APIs da QI Tech deve ser realizada utilizando a comunicação HTTPS. Para evitar que, por desatenção ou outro motivo, sejam feitas chamadas HTTP, este servidor somente disponibiliza a porta 443 com comunicação TLS 1.2. Chamadas realizadas utilizando outros protocolos serão automaticamente negadas.

## Autenticação

> Para autenticar uma chamada, utilize o código seguinte:

```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

> Substitua a API key 'EXAMPLE-OF-API-KEY' com a sua chave adquirida com o nosso suporte.

Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br .

Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:

`Authorization: EXAMPLE-OF-API-KEY`

:::info **Atenção**

Você deve substituir EXAMPLE-OF-API-KEY com a API Key recebida do suporte.
:::

---

# Análise de Crédito - Pessoa Jurídica

URL: /documentation/caas/credit_analysis/legal_person

Para realizar a análise de crédito de uma pessoa jurídica, utilize o endpoint de Legal Person.

No momento em que uma análise de crédito de pessoa jurídica for realizada, os seguintes dados deverão ser enviados para o nosso servidor.

## Definição do Objeto Legal Person

Request Body

```json
{
  "id": "12345678",
  "credit_request_date": "2021-03-31T10:30:00-03:00",
  "credit_type": "student_loan",
  "legal_name": "QI Tech Tecnologia LTDA",
  "trading_name": "QI Tech",
  "document_number": "35.472.523/0001-15",
  "constitution_date": "2019-11-11",
  "constitution_type": "llc",
  "email": "suporte.caas@qitech.com.br",
  "monthly_revenue": 50000000,
  "client_category": "Premium User",
  "client_since": "2021-02-11",
  "address": {
    "country": "BRA",
    "street": "Av. Brigadeiro Faria Lima",
    "number": "2391",
    "neighborhood": "Jardim Paulistano",
    "city": "São Paulo",
    "uf": "SP",
    "postal_code": "01452-905"
  },
  "phones": [
    {
      "international_dial_code": "55",
      "area_code": "11",
      "number": "32234611",
      "type": "residential"
    }
  ],
  "shareholders": [
    {
      "name": "Anna Pinto Azevedo",
      "document_number": "261.026.462-31",
      "birthdate": "1972-08-22",
      "email": "annapintoazevedo@sample.com",
      "nationality": "BRA",
      "mother_name": "Beatrice Rodrigues Pinto",
      "father_name": "Luís Azevedo",
      "monthly_income": 800000,
      "declared_assets": 18600000,
      "occupation": "law",
      "gender": "female",
      "address": {
        "country": "BRA",
        "street": "Rua Derviche Djouki",
        "number": "598",
        "complement": "Ap 857",
        "neighborhood": "Chora Menino",
        "city": "São Paulo",
        "uf": "SP",
        "postal_code": "02463-080"
      },
      "phones": [
        {
          "international_dial_code": "55",
          "area_code": "11",
          "number": "55988644",
          "type": "mobile"
        }
      ]
    }
  ],
  "guarantors": [
    {
      "name": "Melissa Lima Melo",
      "document_number": "677.498.846-61",
      "birthdate": "1960-11-21",
      "email": "exemplo2@sample.com",
      "nationality": "BRA",
      "mother_name": "Raíssa Lima",
      "father_name": "Ronaldo Melo",
      "monthly_income": 800000,
      "declared_assets": 18600000,
      "occupation": "law",
      "gender": "female",
      "address": {
        "country": "BRA",
        "street": "Rua Castro Alves",
        "number": "100",
        "complement": "Ap 202",
        "neighborhood": "Parque Estrela Dalva I",
        "city": "Luziânia",
        "uf": "GO",
        "postal_code": "72804-050"
      },
      "phones": [
        {
          "international_dial_code": "55",
          "area_code": "11",
          "number": "21158745",
          "type": "residential"
        }
      ]
    }
  ],
  "financial": {
    "amount": 100000,
    "currency": "BRL",
    "interest_type": "cdi_plus",
    "annual_interest_rate": 2.32,
    "cdi_percentage": 100,
    "number_of_installments": 4
  },
  "warrants": [
    {
      "warrant_type": "real_estate",
      "address": {
        "country": "BRA",
        "street": "Rua Curitiba",
        "number": "150",
        "complement": "Bl 3 apt 122",
        "neighborhood": "Paraíso",
        "city": "São Paulo",
        "uf": "SP",
        "postal_code": "04005-030"
      },
      "property_type": "house",
      "estimated_value": 100000000,
      "forced_selling_value": 60000000
    }
  ],
  "source": {
    "channel": "website",
    "ip": "132.23.161.75",
    "session_id": "2bb684f9-6c00-4993-bcd7-18b9eccd7c9d"
  },
  "scr_parameters" : {
    ...
  }
}
```

Uma análise de crédito deve ser enviada para a API antes do desembolso e pode ser utilizada para se tomar a decisão de conceder ou não o crédito. Os dados enviados também podem, mediante acordo com o cliente, ser utilizados para a prevenção a fraudes.

Os objetos utilizados na composição do objeto CreditProposal e não definidos nesta seção estão disponíveis na seção [Objetos Compartilhados](#objetos-compartilhados).

|                   nome                   |      tipo      | descrição                                                                                                                                                                      |
| :--------------------------------------: | :------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|                    id                    |    string     | Identificador da proposta de crédito no seu sistema. <br /> **É essencial que este número seja único para cada processo de análise de crédito**                                |
|registration_id | string | Identificador do cadastro no sistema do cliente. Para realizar mais de uma análise referente a um mesmo cadastro, |
|           credit_request_date            |    datetime    | A data e hora quando o crédito foi requisitado pelo tomador                                                                                                                    |
|               credit_type                |   enum   | Tipo de crédito sendo concedido. No momento são suportados: **clean**, **student_loan**, **credit_card_limit**                                                                 |
| legal_name        |         string          | Razão social                                                                   |
| trading_name      |         string          | Nome fantasia                                                                  |
| document_number   |         string          | O CNPJ, formatado conforme padrão estabelecido nesta documentação              |
| monthly_revenue   |         integer         | Receita mensal bruta em centavos                                               |
|client_category    |         string          | Categoria do cliente de acordo com a classificação da sua plataforma ou seu programa de fidelidade    |
|client_since    |         date | Data de início da prestação de serviços para este cliente   
| constitution_date |          data           | A data de constituição da companhia, conforme junta comercial                  |
| constitution_type |       enum        | O tipo de constituição da empresa: **LLC**, **corp**                           |
| email             |         string          | O email do representante da empresa                                            |
| address           |        _Address_        | O endereço da matriz da companhia                                              |
| phones            |    list of _Phones_     | Os telefones colhidos da companhia                                             |
| shareholders      | list of _NaturalPerson_ | Os sócios da companhia, no modelo de pessoa física (Objeto **NaturalPerson**) |
|                guarantors                | list of _Person_ | Garantidores da operação, Pessoa física (**NaturalPerson**) ou jurídica (**LegalPerson**)                                                                                       |
|             financial.amount             |    integer     | O valor total sendo requerido pelo tomador, que será liberado em caso de aprovação                                                                                             |
|             financial.currency           |    enum     | A unidade monetária referente ao valor total: **BRL**, **USD**, **EUR**                                                                                          |
|              interest_type               |   enum   | O indexador da dívida que será utilizado: **cdi_plus**, **cdi_percentage**, **price**, **pre_fixed**                                                                           |
|           annual_interest_rate           |     number     | O valor da parte pré-fixada do juros, em percentual ao ano                                                                                                                     |
|              cdi_percentage              |     number     | O percentual do CDI (Pós) do juros a ser cobrado                                                                                                                               |
|          number_of_installments          |    integer     | Número de parcelas                                                                                                                                                             |
|                 warrants                 |     _Warrant_     | Dados de garantias reais oferecidas na operação. Deverá ser acordada antes da entrada em produçao. Atualmente os seguintes tipos são aceitos: **real_estate**                  |
|              source               |     _Source_     | O canal de venda do crédito. Atualmente são aceitos: **website** e **app**                                                                                                     |
| scr_parameters| _ScrParameters_ | Objeto com as informações necessárias para a utilização das informações do SCR na análise de crédito |

## Enviar uma Proposta de Crédito - Pessoa Jurídica

Request Body

```json
  {
    "id": "12345678",
    ...
  }
```

Response Body

```json
{
  "id": "12345678",
  "analysis_status": "automatically_approved",
  "reason": "rule_decision_enum"
}
```

Para realizar a avaliação de uma proposta de crédito, basta enviar um objeto do tipo LegalPerson ao seguinte endpoint:

`POST https://api.caas.qitech.app/credit_analysis/legal_person`

---

# Análise de Crédito - Pessoa Física

URL: /documentation/caas/credit_analysis/natural_person

Para realizar a análise de crédito de uma pessoa física, utilize o endpoint de NaturalPerson.

No momento em que uma análise de crédito de pessoa física for realizada, os seguintes dados abaixo devem ser enviados para o nosso servidor.

## Definição do Objeto Natural Person

Request Body

```json
{
  "id": "12345678",
  "registration_id":"444",
  "credit_request_date": "2021-03-31T10:30:00-03:00",
  "credit_type": "student_loan",
  "name": "Victor Silva Barbosa",
  "document_number": "199.208.915-92",
  "birthdate": "1990-01-01",
  "email": "exemplo@sample.com",
  "nationality": "BRA",
  "gender": "male",
  "mother_name": "Ana Barbosa",
  "father_name": "João Silva",
  "monthly_income": 30000,
  "declared_assets": 7500000,
  "occupation": "pedagogy",
  "address": {
    "country": "BRA",
    "street": "Rua Curitiba",
    "number": "150",
    "complement": "Bl 3 apt 122",
    "neighborhood": "Paraíso",
    "city": "São Paulo",
    "uf": "SP",
    "postal_code": "04005-030"
  },
  "phones": [
    {
      "international_dial_code": "55",
      "area_code": "11",
      "number": "32234611",
      "type": "residential"
    }
  ],
  "guarantors": [
    {
      "name": "Melissa Lima Melo",
      "document_number": "677.498.846-61",
      "birthdate": "1960-11-21",
      "email": "exemplo2@sample.com",
      "nationality": "BRA",
      "mother_name": "Raíssa Lima",
      "father_name": "Ronaldo Melo",
      "monthly_income": 800000,
      "declared_assets": 18600000,
      "occupation": "law",
      "gender": "female",
      "address": {
        "country": "BRA",
        "street": "Rua Castro Alves",
        "number": "100",
        "complement": "Ap 202",
        "neighborhood": "Parque Estrela Dalva I",
        "city": "Luziânia",
        "uf": "GO",
        "postal_code": "72804-050"
      },
      "phones": [
        {
          "international_dial_code": "55",
          "area_code": "11",
          "number": "21158745",
          "type": "residential"
        }
      ]
    }
  ],
  "financial": {
    "amount": 100000,
    "currency": "BRL",
    "interest_type": "cdi_plus",
    "annual_interest_rate": 2.32,
    "cdi_percentage": 100,
    "number_of_installments": 4
  },
  "warrants": [
    {
      "warrant_type": "real_estate",
      "address": {
        "country": "BRA",
        "street": "Rua Curitiba",
        "number": "150",
        "complement": "Bl 3 apt 122",
        "neighborhood": "Paraíso",
        "city": "São Paulo",
        "uf": "SP",
        "postal_code": "04005-030"
      },
      "property_type": "house",
      "estimated_value": 100000000,
      "forced_selling_value": 60000000
    }
  ],
  "source": {
    "channel": "website",
    "ip": "145.25.145.32",
    "session_id": "bec256b3-5265-4dcb-bc55-2e4fb43983e0"
  },
  "scr_parameters" : {
    ...
  }
}
```

Uma análise de crédito deve ser enviada para a API antes do desembolso e pode ser utilizada para se tomar a decisão de conceder ou não o crédito. Os dados enviados também podem, mediante acordo com o cliente, ser utilizados para a prevenção a fraudes.

Os objetos utilizados na composição do objeto **CreditProposal** e não definidos nesta seção estão disponíveis na seção [Objetos Compartilhados](#objetos-compartilhados).

|                   nome                   |      tipo      | descrição                                                                                                                                                                      |
| :--------------------------------------: | :------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|                    id                    |    string     | Identificador da proposta de crédito no seu sistema. <br /> **É essencial que este número seja único para cada processo de análise de crédito** *(obrigatório)*|
|registration_id | string | Identificador do cadastro no sistema do cliente. Para realizar mais de uma análise referente a um mesmo cadastro|
|           credit_request_date            |    datetime    | A data e hora quando o crédito foi requisitado pelo tomador *(obrigatório)*|
|               credit_type                |   enum   | Tipo de crédito sendo concedido. No momento são suportados: **clean**, **student_loan**, **credit_card_limit** |
| name | string | Nome completo do indivíduo sendo cadastrado |
| document_number | string | CPF do indivíduo sendo cadastrado, com pontos e hífens, de acordo com a padronização *(obrigatório)* |
| birthdate | date | Data de nascimento do indivíduo de acordo com a padronização
| gender | enum | Gênero do indivíduo: 'male', 'female' ou 'undefined'
| nationality | string | A nacionalidade do cadastro, em ISO 3166-1 alfa-3
| mother_name | string | Nome completo da mãe
| father_name | string | Nome completo do pai
| monthly_income | integer | Renda mensal bruta em centavos
| declared_assets | integer | Patrimônio declarado em centavos
|client_category    |         string          | Categoria do cliente de acordo com a classificação da sua plataforma ou seu programa de fidelidade
|client_since    |         date | Data de início da prestação de serviços para este cliente   
| occupation | string | Profissão do indivíduo sendo cadastrado
| email | string | O email da pessoa
| documents | Document | Objetos do tipo CNH e RG
| address | _Address_ | Objeto do tipo Address que descreve o endereço da moradia do indivíduo
| phones | Lista de _Phones_ | Lista de objetos do tipo phone que possui a lista de telefones do indivíduo
|                guarantors                | list of _Person_ | Garantidores da operação, Pessoa física (**NaturalPerson**) ou jurídica (**LegalPerson**)                                                                                       |
|             financial.amount             |    integer     | O valor total sendo requerido pelo tomador, que será liberado em caso de aprovação em centavos                                                                                             |
|             financial.currency           |    enum     | A unidade monetária referente ao valor total: **BRL**, **USD**, **EUR**                                                                                          |
|              interest_type               |   enum   | O indexador da dívida que será utilizado: **cdi_plus**, **cdi_percentage**, **price**, **pre_fixed**                                                                           |
|           annual_interest_rate           |     number     | O valor da parte pré-fixada do juros, em percentual ao ano                                                                                                                     |
|              cdi_percentage              |     number     | O percentual do CDI (Pós) do juros a ser cobrado                                                                                                                               |
|          number_of_installments          |    integer     | Número de parcelas                                                                                                                                                             |
|                 warrants                 |     _Warrant_     | Dados de garantias reais oferecidas na operação. Deverá ser acordada antes da entrada em produção. Atualmente os seguintes tipos são aceitos: **real_estate**                  |
|              source               |     _Source_     | O canal de venda do crédito. Atualmente são aceitos: **website** e **app**                                                                                                     |
| scr_parameters| _ScrParameters_ | Objeto com as informações necessárias para a utilização das informações do SCR na análise de crédito |

:::info **Atenção**
A propriedade scr_parameters é obrigatória apenas se o cliente contratou e deseja utilizar a consulta SCR na análise de crédito.
:::

## Enviar uma Proposta de Crédito - Pessoa Física

Request Body

```json
  {
    "id": "12345678",
    ...
  }
```

Response Body

```json
{
  "id": "12345678",
  "analysis_status": "automatically_approved",
  "reason": "rule_decision_enum"
}
```

Para realizar a avaliação de uma proposta de crédito, basta enviar um objeto do tipo **NaturalPerson** ao seguinte endpoint:

`POST https://api.caas.qitech.app/credit_analysis/natural_person`

---

# Objetos Compartilhados

URL: /documentation/caas/credit_analysis/objects

Abaixo as definições de outros objetos utilizados ao longo da documentação.

## Objeto _Address_

Request Body

```json
{
  "street": "Rua do Exemplo",
  "number": "111" ,
  "neighborhood": "Bairro do Teste",
  "city": "Aparecida de Goiânia",
  "uf": "GO",
  "complement": "Apt 903",
  "postal_code": "00000-000"
}
```

O objeto _Address_ é utilizado para representar endereços em toda a API, endereços no território brasileiro são representados da seguinte maneira:

| nome         |  tipo  | descrição                                                                                    |
| ------------ | :----: | -------------------------------------------------------------------------------------------- |
| street       | string | Rua do endereço, incluindo o logradouro, evitando, se possível, abreviações *(obrigatório)*. |
| number       | string | Número do imóvel, incluindo letras caso possua *(obrigatório)*.                              |
| neighborhood | string | Bairro, sem abreviações *(obrigatório)*. <br />**e.g.: Santa Felicidade**                    |
| city         | string | Nome completo da cidade, sem abreviações *(obrigatório)*.                                    |
| uf           | string | A unidade federativa, com duas letras maiúsculas *(obrigatório)*. <br />**e.g.: SP**         |
| complement   | string | Quaisquer complementos para localizar o imóvel. <br />**e.g.: Apartamento 101, Conjunto 12** |
| postal_code  | string | O código postal da localidade, contendo o hífen *(obrigatório)*.                             |
| country      | string | Código ISO 3166-1 alfa-3 do país do endereço *(obrigatório)*.                                |

No caso dos endereços cujo país não seja Brasil ("BRA"), o postal_code e a unidade federativa poderão ser preenchidos livremente.

## Objeto _Phone_

Request Body

```json
{
  "international_dial_code": "1",
  "area_code": "11",
  "number": "999999999",
  "type": "mobile"
}
```

Um objeto _Phone_ representa um número telefônico, dentro ou fora do Brasil e sua classificação. Para isso, os campos são:

| nome                    |  tipo  | descrição                                                        |
| ----------------------- | :----: | ---------------------------------------------------------------- |
| international_dial_code | string | Código de discagem internacional, sem zero ou +, somente números *(obrigatório)*. |
| area_code               | string | Código de área, sem zero, somente números *(obrigatório)*.                        |
| number                  | string | Número do telefone, sem o hífen *(obrigatório)*.                                  |
| type                    |  enum  | Tipo de número: celular, residencial, comercial, etc.            |

Existem os seguintes enumeradores para tipo de telefone: `residential`, `commercial`, `mobile`

## Objeto _cnh_

Request Body

```json
{
  "register_number": "05163811694",
  "issuer_state": "PR",
  "first_issuance_date":"2011-03-21",
  "issuance_date":"2016-06-29",
  "expiration_date":"2021-06-25",
  "category": "AB",
  "validation_type":"zaig_sdk",
  "ocr_key":"a5cf9c8f-2f66-4490-a7db-8a5bc70c1b76"
}
```

O objeto *cnh* é utilizado para representar as CNHs em toda a API bem como se foi utilizado algum meio de validação dos mesmos. Eles são representados da seguinte maneira:

nome | tipo | descrição
---- | :----: | ---------
register_number | string | Número do registro da CNH cadastrada.
issuer_state | enum | Enumerador do estado onde a CNH foi emitida
first_issuance_date | date | Data de primeira habilitação.
issuance_date | date | Data de emissão
expiration_date | date | Data de vencimento
category | enum | Categoria da CNH em letras maiúsculas
validation_type | enum | Tipo de validação utilizada durante o cadastro do documento.
ocr_key | guid | Id retornado pela API de [validação de documento da QI Tech](https://docs.zaig.com.br/ocr/#introducao).

Existem os seguintes enumeradores para *validation_type*: `zaig_api` e `zaig_sdk`.

## Objeto _rg_

Request Body

```json
{
  "number": "4.366.477-8",
  "issuer": "II",
  "issuer_state": "PR",
  "issuance_date":"2002-01-12",
  "validation_type":"zaig_sdk",
  "ocr_front_key":"a5cf9c8f-2f66-4490-a7db-8a5bc70c1b76",
  "ocr_back_key":"a5cf9c8f-2f66-4490-a7db-8a5bc70c1b76"
}
```

O objeto *rg* é utilizado para representar os RGs em toda a API bem como se foi utilizado algum meio de validação dos mesmos. Eles são representados da seguinte maneira:

nome | tipo | descrição
---- | :----: | ---------
number | string | Número do documento cadastrado, incluindo formatação (Pontos, Hífens, Barras e outros).
issuer | string | Órgão emissor do documento (Sigla, e.g.: II, SESP...)
issuer_state | enum | UF emissor do documento.
issuance_date | date | Data de emissão do documento.
validation_type | enum | Tipo de validação utilizada durante o cadastro do documento.
ocr_key | guid | Id retornado pela API de validação de documento da QI Tech.

Existem os seguintes enumeradores para *validation_type*: `zaig_api` e `zaig_sdk`.

## Objeto _NaturalPerson_

Request Body

```json
{
  "name": "Melissa Lima Melo",
  "document_number": "677.498.846-61",
  "birthdate": "1960-11-21",
  "email": "exemplo2@sample.com",
  "nationality": "BRA",
  "gender": "female",
  "mother_name": "Raíssa Lima",
  "father_name": "Ronaldo Melo",
  "monthly_income": 800000,
  "declared_assets": 18600000,
  "occupation": "law",
  "address": {
    "country": "BRA",
    "street": "Rua Castro Alves",
    "number": "100",
    "complement": "Ap 202",
    "neighborhood": "Parque Estrela Dalva I",
    "city": "Luziânia",
    "state": "GO",
    "postal_code": "72804-050"
  },
  "phones": [
    {
      "international_dial_code": "55",
      "area_code": "11",
      "number": "21158745",
      "type": "residential"
    }
  ]
}
```

O objeto _NaturalPerson_ representa os dados de uma pessoa que pode ser o próprio tomador, um garantidor ou um sócio de uma empresa tomadora. Ele é composto por:

| nome             |       tipo       | descrição                                                                                      |
| ---------------- | :--------------: | ---------------------------------------------------------------------------------------------- |
| name             |      string      | Nome completo *(obrigatório)*.                                                                                 |
| document_number  |      string      | O CPF, formatado adequadamente *(obrigatório)*.                                                                |
| birthdate        |       date       | A data de nascimento da pessoa.                                                              |
| email            |      string      | O email da pessoa.                                                                              |
| gender           |       enum       | O gênero da pessoa, de acordo com a lista de enumeradores.                                  |
| address          |    _Address_     | O endereço residencial da pessoa.                                                               |
| phones           | list of _Phone_ | Os telefones colhidos da pessoa.                                                                |

Enumeradores de gênero:

- `male`
- `female`
- `undefined`

## Objeto _LegalPerson_

Request Body

```json
{
  "legal_name": "QI Tech Tecnologia LTDA",
  "trading_name": "QI Tech",
  "document_number": "35.472.523/0001-15",
  "constitution_date": "1990-01-01",
  "constitution_type": "llc",
  "email": "exemplo@sample.com",
  "address": { ... },
  "phones": [ { ... } ],
  "shareholders": [ { ... }]
}
```

O objeto _LegalPerson_ representa os dados de uma empresa que está tomando crédito ou garantindo o crédito (Fiador). Ele é composto por:

| nome              |          tipo           | descrição                                                                      |
| ----------------- | :---------------------: | ------------------------------------------------------------------------------ |
| legal_name        |         string          | Razão social *(obrigatório)*.                                                                   |
| trading_name      |         string          | Nome fantasia                                                                  |
| document_number   |         string          | O CNPJ, formatado conforme padrão estabelecido nesta documentação *(obrigatório)*.              |
| constitution_date |          data           | A data de constituição da companhia, conforme junta comercial                  |
| constitution_type |       enumerador        | O tipo de constituição da empresa: **LLC**, **corp**                           |
| email             |         string          | O email do representante da empresa                                            |
| address           |        _Address_        | O endereço da matriz da companhia                                              |
| phones            |    list of _Phone_     | Os telefones colhidos da companhia                                             |
| shareholders      | list of _NaturalPerson_ | Os sócios da companhia, no modelo de pessoa física (Objeto **NaturalPerson**) |

## Objeto _Source_

Request Body: Pedidos de crédito realizados por meio do site próprio

```json
{
  "channel": "website",
  "ip": "201.81.161.86",
  "session_id": "b8da64db-e8f8-47fc-8d8e-11ce26da499f"
}
```

Request Body: Pedidos de crédito realizados por meio de aplicativo próprio

```json
{
  "channel": "app",
  "platform": "android",
  "ip": "201.81.161.86",
  "session_id": "b8da64db-e8f8-47fc-8d8e-11ce26da499f"
}
```

O objeto source representa o local onde o pedido de crédito foi realizado.

Atenção, caso o canal de venda desejado não se enquadre em nenhuma destas categorias, entrar em contato com a equipe de suporte

## Objeto _Warrant_

> Para análises de crédito que possuam algum tipo de garantia, o objeto warrant pode ser utilizado para informá-lo à nossa API. No momento, somente garantias de imóvel são aceitas e caso seja necessário outro tipo de garantia, basta entrar em contato com o nosso suporte

Request Body

```json
  {
    "warrant_type": "real_estate",
    "address": { ... },
    "property_type": "house",
    "estimated_value": 100000000,
    "forced_selling_value": 60000000
  }
```

Para a garantia do tipo **real_estate**, o objeto é formado pelos seguintes campos:

| nome                 |  tipo   | descrição                                                                                                                 |
| -------------------- | :-----: | ------------------------------------------------------------------------------------------------------------------------- |
| warrant_type         |  enum   | Define o tipo de garantia. No momento somente **real_estate** está implementado.                                          |
| address              | _Address_  | Objeto do tipo Address que identifica o imóvel dado como garantia                                                         |
| property_type        |  enum   | O tipo de imóvel em questão, no momento estão disponíveis: **house**, **commercial_building**, **office**, **appartment** |
| estimated_value      | integer | O valor estimado do imóvel                                                                                                |
| forced_selling_value | integer | O valor de venda forçada estimado do imóvel                                                                               |

Atenção, caso a garantia desejada não se enquadre em nenhuma destas categorias, entrar em contato com a equipe de suporte

## Objeto _ScrParameters_

Request Body

```json
  {
    "scr_parameters": {
      "signers": [
        {
          "document_number": "111.222.333-44",
          "name": "Felipe Marques da Silva",
          "email": "felipe.silva@qitech.com.br",
          "phone": {
            "number": "991722315",
            "area_code": "16",
            "international_dial_code": "55"
          }
        }
      ],
      "signature_evidence": {
        "ip_address": "179.104.42.245",
        "session_id": "ddb1d063-4fdf-4330-af9c-3316e9142ff3",
        "access_token":         "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQSflKxwRJSMeKKF2QT4fwpMeJf36PO6yJV_adQssw5d",
        "additional_data": {
          ...
        },
        "signed_term": {
          "raw_text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas elementum erat et tempus dapibus. Donec eu sapien tortor. Pellentesque 
            et tortor eget erat pulvinar mattis. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Proin ornare diam arcu, sit amet auctor lorem varius quis. Ut pretium venenatis magna sed ultrices. Donec quis tortor odi."
        }
      }
    }
  }
```

| nome                 |  tipo   | descrição                                                                                                                 |
| -------------------- | :-----: | ------------------------------------------------------------------------------------------------------------------------- |
| signers |  Lista de _Signer_ | Lista de pessoas que vão assinar ou assinaram a autorização de consentimento para consulta SCR. Este objeto só deve ser enviado no caso de análises de crédito de pessoas jurídicas. |
| signature_evidence | _SignatureEvidence_  | Objeto que para envio das informações coletadas no momento da autorização de consentimento quando a autorização é solicitada na plataforma do cliente. |

## Objeto *Signer*

Request Body

```json
  {
    "document_number": "111.222.333-44",
    "name": "Felipe Marques da Silva",
    "email": "felipe.silva@qitech.com.br",
    "phone": {
      "number": "991722315",
      "area_code": "16",
      "international_dial_code": "55"
    }
  }
```

| nome                 |  tipo   | descrição                                                                                                                 |
| -------------------- | :-----: | ------------------------------------------------------------------------------------------------------------------------- |
| document_number        |  string   | Número do documento do assinante. |
| name | string | Nome do assinante. |
| email | string | Email do assinante. |
| phone | _Phone_ | Telefone do assinante. |

## Objeto *Signature_Evidence*

Request Body

```json
  {
    "signature_evidence": {
      "ip_address": "179.104.42.245",
      "session_id": "ddb1d063-4fdf-4330-af9c-3316e9142ff3",
      "access_token":         "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQSflKxwRJSMeKKF2QT4fwpMeJf36PO6yJV_adQssw5d",
      "additional_data": {
        ...
      },
      "signed_term": {
        "raw_text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas elementum erat et tempus dapibus. Donec eu sapien tortor. Pellentesque 
          et tortor eget erat pulvinar mattis. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Proin ornare diam arcu, sit amet auctor lorem varius quis. Ut pretium venenatis magna sed ultrices. Donec quis tortor odi."
      }
    }
  }
```

| nome                 |  tipo   | descrição                                                                                                                 |
| -------------------- | :-----: | ------------------------------------------------------------------------------------------------------------------------- |
| ip_address | string  | IP do assinante |
| session_id | string | Identificador de sessão do usuário na sua plataforma, deve ser algum identificador que permita solicitar auditoria de um OptIn feito na sua plataforma através deste identificador. |
| access_token |  string | Identificador do usuário logado na sua plataforma, deve ser possível solicitar auditoria de cadastro deste usuário através deste identificador. |
| additional_data | objeto | Objeto JSON configurável para acomodar informações adicionais que o parceiro julgar relevantes que adicionem fidelidade/credibilidade/autent icidade na assinatura realizada dentro de sua plataforma. |
| signed_term | _SignedTerm_ | Objeto que traz informações sobre o termo que está sendo utilizado para coleta de consentimento. | 

## Objeto *SignedTerm*

Request Body

```json
  {
    "raw_text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas elementum erat et tempus dapibus. Donec eu sapien tortor. Pellentesque et tortor eget erat pulvinar mattis. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Proin ornare diam arcu, sit amet auctor lorem varius quis. Ut pretium venenatis magna sed ultrices. Donec quis tortor odi."
  }
```

| nome                 |  tipo   | descrição                                                                                                                 |
| -------------------- | :-----: | ------------------------------------------------------------------------------------------------------------------------- |
| raw_text | string | Texto plano do termo que está sendo assinado. |

---

# Dados Sistema de Informações de Créditos (SCR - BACEN)

URL: /documentation/caas/credit_analysis/scr

Caso o cliente contrate, temos a opção da utilização dos dados disponíveis no SCR da pessoa física ou jurídica no momento da análise de crédito. Para utilização dos dados do SCR, é primordial que o consentimento do consultado seja coletado. Esse consentimento pode ser coletado pela QI Tech ou pelo próprio cliente e isso influencia no fluxo de consentimento, bem como nos dados que devem ser enviados para a API, conforme abaixo:

**1. Coleta de consentimento via QI Tech -** Caso opte pela coleta do consentimento via QI Tech, um link para assinatura eletrônica é enviado diretamente, via e-mail, da QI Tech para o usuário consultado e, quando o usuário assina o link e finaliza o processo, a informação do SCR automaticamente torna-se disponível para uso. Para utilização deste fluxo, é necessário que, na integração, sejam enviados os dados do usuário final que irá assinar o termo de consentimento.

**2. Coleta do consentimento pelo próprio cliente -**  É possível coletar a assinatura do termo de consentimento em seu próprio ambiente ou esteira de crédito (pode ser feito por documento assinado ou opt-in box do termo). Para que isso seja possível, o termo de consentimento utilizado deve ser validado pelo time jurídico da QI Tech e se faz necessário o envio de informações que comprovem de maneira auditável que o consentimento para acesso à informação de SCR foi coletado através do objeto *scr_parameters*.

Atenção, ambas configurações de acesso as informações de SCR, incluindo qual fluxo será utilizado, devem ser acordadas durante contratação do produto para que a funcionalidade esteja disponível para uso.

## Coleta do Consentimento via QI Tech - Pessoa Física

No caso de uma pessoa física, para que a QI Tech envie o pedido de consentimento, basta o preenchimento dos dados pessoais do consultado no objeto de CreditProposal . Com isso, a QI Tech irá enviar o pedido de consentimento ao consultado via e-mail e, automaticamente, realizar a consulta (após autorizaçao), disponibilizando os resultados para análise de crédito.

É obrigatório o envio dos campos _document_number_ , name , email e do objeto phone para coleta do consentimento de pessoa física via QI Tech.

## Coleta do Consentimento via QI Tech - Pessoa Jurídica

Request Body

```json

  {
    "id": "32199d0s",
    "legal_name": "QI CAAS LTDA",
    "trading_name": "QI Tech",
    ...
    "scr_parameters": {
      "signers": [
        {
          "document_number": "372.989.950-30",
          "name": "Felipe Marques da Silva",
          "email": "felipe.silva@qitech.com.br",
          "phone": {
            "number": "991722315",
            "area_code": "16",
            "international_dial_code": "55"
          }
        },
        {
          "document_number": "440.896.050-08",
          "name": "Claudio Mattos",
          "email": "claudiomattos@sample.com",
          "phone": {
            "number": "991722315",
            "area_code": "16",
            "international_dial_code": "55"
          }
        }
      ]
    }
  }
```

No caso de uma pessoa jurídica, para que a QI Tech envie o pedido de consentimento, é necessário incluir o objeto adicional scr_parameters na requisição de análise. Dentro deste objeto, será necessário adicionar a lista de responsáveis legais da empresa para os quais serão enviados os pedidos de assinatura eletrônica via e-mail. Essa lista deve ser enviada dentro da propriedade signers . Após a assinatura de todos os representantes legais, a QI Tech realizará a consulta, disponibilizando os resultados para análise de crédito. Acima temos um exemplo do objeto scr_parameters para o caso descrito.

## Coleta do Consentimento pelo Próprio Cliente - Pessoa Física

Request Body

```json
  {
    "id": "678",
    "credit_request_date": "2021-03-31T10:30:00-03:00",
    "credit_type": "student_loan",
    "name": "Victor Silva Barbosa",
    "document_number": "199.208.915-92",
    ...
    "scr_parameters": {
      "signature_evidence": {
        "ip_address": "179.104.42.245",
        "session_id": "ddb1d063-4fdf-4330-af9c-3316e9142ff3",
        "access_token":         "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQSflKxwRJSMeKKF2QT4fwpMeJf36PO6yJV_adQssw5d",
        "additional_data": {
          ...
        },
        "signed_term": {
          "raw_text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas elementum erat et tempus dapibus. Donec eu sapien tortor. Pellentesque et tortor eget erat pulvinar mattis. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Proin ornare diam arcu, sit amet auctor lorem varius quis. Ut pretium venenatis magna sed ultrices. Donec quis tortor odi."
        }
      }
    }
  }
```

No caso de uma pessoa física, quando a coleta do consentimento é realizada pelo cliente, é necessário incluir o objeto adicional scr_parameters na requisição de análise. Dentro deste objeto, é necessário adicionar informações para comprovar que a pessoa analisada autorizou a consulta. Essas informações devem ser enviadas dentro da propriedade signature_evidence . Acima temos um exemplo do objeto scr_parameters para o caso descrito.

## Coleta do Consentimento pelo Próprio Cliente - Pessoa Jurídica

Request Body

```json
  {
    "id": "678",
    "credit_request_date": "2021-03-31T10:30:00-03:00",
    "credit_type": "student_loan",
    "name": "Victor Silva Barbosa",
    "document_number": "199.208.915-92",
    ...
    "scr_parameters": {
      "signers": [
        {
          "document_number": "372.989.950-30",
          "name": "Felipe Marques da Silva",
          "email": "felipe.silva@qitech.com.br",
          "phone": {
            "number": "991722315",
            "area_code": "16",
            "international_dial_code": "55"
          }
        },
        {
          "document_number": "440.896.050-08",
          "name": "Claudio Mattos",
          "email": "claudiomattos@sample.com",
          "phone": {
            "number": "991722315",
            "area_code": "16",
            "international_dial_code": "55"
          }
        }
      ],
      "signature_evidence": {
        "ip_address": "179.104.42.245",
        "session_id": "ddb1d063-4fdf-4330-af9c-3316e9142ff3",
        "access_token":         "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQSflKxwRJSMeKKF2QT4fwpMeJf36PO6yJV_adQssw5d",
        "additional_data": {
          ...
        },
        "signed_term": {
          "raw_text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas elementum erat et tempus dapibus. Donec eu sapien tortor. Pellentesque et tortor eget erat pulvinar mattis. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Proin ornare diam arcu, sit amet auctor lorem varius quis. Ut pretium venenatis magna sed ultrices. Donec quis tortor odi."
        }
      }
    }
  }
```

No caso de uma pessoa jurídica, quando a coleta do consentimento é realizada pelo cliente, é necessário incluir o objeto adicional scr_parameters na requisição de análise. Dentro deste objeto, é necessário adicionar informações para comprovar que a pessoa analisada autorizou a consulta, bem como adicionar a lista de responsáveis legais da empresa que autorizaram a consulta. As informações de autorização deverão ser enviadas dentro da propriedade signature_evidence e a lista de pssoas que autorizaram a consulta dentro da propriedade signers . Acima temos um exemplo do objeto scr_parameters para o caso descrito.

---

# Padrões

URL: /documentation/caas/credit_analysis/standards

Para facilitar a integração e garantir a integridade da informação, foram definidos alguns padrões que são seguidos em toda a API.

## Valores Monetários
> Exemplos:

```
10000
12345
98741
1223
1
0
```

As APIs assumem que todos os valores monetários enviados são em Reais Brasileiros. Os valores devem ser enviados como inteiro em centavos.

## Data e Hora com Fuso Horário
> Alguns exemplos:

```
2019-10-15T22:35:12-03:00
2018-05-01T13:32:11+00:00
2019-05-01T00:00:00+00:00
```

É representada conforme a ISO 8601. Neste caso, o fuso-horário é colocado logo após o horário e deve representar o fuso do local onde aquele dado será valido. Por exemplo, se um aluguel estiver marcado para começar às 09:30 no aeroporto de Brasília, o horário enviado deverá ser representado por 09:30-03:00, se o aluguel estiver marcado para começar às 09:30 em Manaus, deverá ser representado por 09:30-04:00.

A máscara utilizada para validação é a seguinte:

`YYYY-MM-ddThh:mm:ss±hh:mm`

## Data e Hora sem Fuso Horario
> Alguns exemplos:

```
2019-10-15T22:35:12
2018-05-01T13:32:11
2019-05-01T00:00:00
```

É representada conforme a ISO 8601. Dados que independem de fuso-horário deverão ser enviados sem ele, sempre em UTC, com a letra Z indicando que este dado está em UTC. O seguinte formato, portanto, será validado:

`YYYY-MM-ddThh:mm:ssZ`

## Data
> Alguns exemplos

``` 
2019-10-15
2019-01-01
2017-03-20
```

No caso de campos que recebem somente data, uma data de nascimento, por exemplo, somente a data, sem nenhum horário deve ser enviada com o seguinte formato:

`YYYY-MM-dd`
 

## Documentos
Uma vez que os números de documento são bastante variados e muitos deles possuem caracteres que não se enquadram como numéricos, definem-se todos os números de documento como string. Outro bom motivo para definí-los como string é evitar que os zeros à esquerda desapareçam. Documentos previstos nesta página possuem uma máscara bem definida e estarão sujeitos a validação. O restante dos documentos, como RG, dada sua falta de padronização, não serão validados.

## CPF

> Exemplos de CPFs válidos contra a máscara definida:

```
123.456.789-12
321.987.543-23
111.283.333-00
```

> Exemplos de CPFs inválidos contra a máscara definida:

```
8.577.477-8
08.104.627/0001-23
123.456.789-1
23.456.789-01
```

O CPF é sempre definido como uma string e será validado conta a máscara:

`###.###.###-##`

## CNPJ

> Exemplos de CNPJs válidos contra a máscara definida:

```
08.104.627/0001-02
01.079.210/0114-67
32.402.502/0001-35
```

> Exemplos de CNPJs inválidos contra a máscara definida:

```
8.577.477-8
123.456.789-12
321.987.543-23
32.402.502/0001-3
032.402.502/0001-3
```

O CNPJ é sempre definido como uma string e será validado conta a máscara:

`##.###.###/####-##`

## IP

> Exemplos de IPs válidos contra a máscara definida:

```
201.81.161.86
201.081.161.86
201.81.161.086
201.81.0.1
```

> Exemplos de IPs inválidos:

```
201.81..86
358.81.161.86
201.81.161
```

IPs deverão ser enviados sempre em IPv4, zeros à esquerda poderão ou não ser enviados, respeitando a seguinte máscara:

`###.###.###.###`

---

# Dinâmica dos Status

URL: /documentation/caas/credit_analysis/status_dynamics

O processo de análise de crédito consiste em enviar uma requisição, tanto de **NaturalPerson** como de **LegalPerson** no respectivo endpoint e esperar a resposta.

Após a QI Tech realizar a análise de crédito, ela retornará uma resposta com um status referente a análise. Esse status tem o nome de **analysis_status**, que representa o resultado da analise de crédito realizado pela QI Tech.

Além do **analysis_status** a QI Tech também possui o **credit_proposal_status** que tem como objetivo representar o status do crédito analisado em cada momento de sua vida na sua plataforma.

## **analysis_status**

Conforme descrito anteriormente, a QI Tech possui sete **analysis_status** que indicam o status da decisão da análise de crédito e possui uma máquina de estados bastante simples:

analysis_status | Descrição
:---------: | ---------
automatically_approved | Os algoritmos da QI Tech recomendam que este cadastro seja aprovado
automatically_reproved | Os algoritmos da QI Tech recomendam que este cadastro seja reprovado
in_manual_analysis | Os algoritmos da QI Tech enviaram este cadastro para a análise manual
manually_approved | Após análise manual, o analista decidiu aprovar o cadastro
manually_reproved | Após análise manual, o analista decidiu reprovar o cadastro
waiting_for_data | A análise de crédito está aguardado o retorno de alguma informação de bureau ou provedor de dados e será respondido por meio de Webhook
automatically_challenged | Os algoritmos da QI Tech recomendam que este cadastro seja desafiado
manually_challenged | Após análise manual, o analista decidiu desafiar o cadastro
pending | A análise de crédito está demorando mais do que o esperado, este cadastro entrou em uma fila de análise automática e será respondido por meio de Webhook

:::info **Atenção**

Você deve substituir EXAMPLE-OF-API-KEY com a API Key recebida do suporte.
:::

## **credit_proposal_status**

O **credit_proposal_status** indica o status da operação do cliente, ou seja, o status da proposta de crédito na sua empresa ou plataforma. Os seguintes enumeradores existem para este status:

credit_proposal_status | Descrição
:---------: | ---------
created | A proposta de crédito foi criada na sua plataforma
disbursed | O proposta de crédito foi desembolsada na sua plataforma
paid | O cliente realizou o pagamento integral do crédito
defaulted | O cliente está inadimplente na sua plataforma

---

# Atualizar o status de uma Análise de Crédito

URL: /documentation/caas/credit_analysis/update_credit_analysis

Request Body: Para marcar o crédito como concedido

```json
{
  "credit_proposal_status": "disbursed",
  "event_date": "2021-11-05T13:34:12-03:00"
}
```

Para garantir a retroalimentação das regras e do modelo de inteligência artificial implementado, é necessário informar ao sistema quando as operações são efetivadas. Para isso, requisições com o método PUT devem ser utilizadas, autenticadas normalmente:

* **Natural Person:**

`PUT https://api.caas.qitech.app/credit_analysis/natural_person/12345678`

* **Legal Person:**

`PUT https://api.caas.qitech.app/credit_analysis/legal_person/12345678`

---

# Webhook

URL: /documentation/caas/credit_analysis/webhook

Webhook

Atualizações no status (Para cadastros que sejam derivados para análise manual ou que sejam respondidos como Pendente), são notificados por meio de Webhook. Para tanto, é necessário, por meio da equipe do [suporte](mailto:suporte.caas@qitech.com.br), configurar um endereço do endpoint por onde vamos notificar as atualizações e também um *secret_token* que será utilizado para assinar a requisição.

O cliente pode, apesar de não recomendável, também utilizar a técnica de [polling](https://en.wikipedia.org/wiki/Polling_(computer_science)). Neste caso, basta não configurar o endpoint de webhook e utilizar os endpoints de recuperação de cadastro para proceder com o polling.

## Assinatura do Webhook

## Requisição

```bash
curl --location 'YOUR-ENDPOINT-HERE' \
--header 'Signature: CALCULATED-HASH-HMAC' \
--data '{"natural_person_id": "538509",  "analysis_status": "manually_approved", "event_date": "2024-11-13T17:52:50Z", "reason": "manually_approved"}'
```

A requisição possui o formato acima e notifica a mudança no status. É importante ressaltar que a requisição utiliza o verbo HTTP POST e o corpo da requisição é enviado como texto codificado em UTF-8.

## Retentativas

A notificação é considerada realizada quando recebe como resposta um HTTP Status 200. Caso as notificações falhem, serão feitas 5 retentativas, com os seguintes intervalos, até que um 200 seja retornado ou as tentativas terminem:

* 30 segundos
* 60 segundos
* 120 segundos
* 240 segundos
* 360 segundos

---

# Objeto Account

URL: /documentation/caas/device_manager/account

A account (conta) é uma entidade organizacional que permite o cadastramento de dispositivos. Esta API foi projetada para atender a [Normativa 491 do BACEN](https://www.bcb.gov.br/estabilidadefinanceira/exibenormativo?tipo=Instru%C3%A7%C3%A3o%20Normativa%20BCB&numero=491), portanto, dados de account devem seguir um padrão para as informações definidas pelo Banco Central, mas quaisquer outros campos necessários podem ser adicionados aos dados da account.

## Definição do Objeto Account

Request Body

```json
{
  "account_id": "12345678",
  "account_type": "natural_person",
  "registration_date": "2019-12-11T11:37:15.12-03:00",
  "account_data": {
    "account_number": "12345678",
    "agency_number": "1234"
    ...
  }
}
```

Todas as trocas de informação de uma account utilizam a seguinte definição para este objeto. Em alguns casos, para facilitar a implementação e diminuir o fluxo de dados entre as partes, algumas informações poderão ser omitidas.

nome | tipo | descrição
:----: | :----: | ---------
account_id | string | Identificador da account. **É essencial que este número seja único para cada account** *(obrigatório)*
account_type | string | Identificador do tipo de account cadastrada no sistema de cadastro de dispositivo. As accounts podem ser do tipo pessoa física `natural_person` ou pessoa jurídica `legal_person` .*(obrigatório)*
registration_date | datetime | Data e hora do registro da account, com fuso horário. *(obrigatório)*
account_data | object | objeto que pode conter quaisquer dados da account, mas se contiver o número da account `account_number` e agência `agency_number` os dois devem ser obrigatoriamente do tipo string.

## Enviar um Account

Request Body

```json
  {
    "account_id": "12345",
    ...
  }
```

Response Body

```json
  {
    "account_id": "12345678",
    "account_type": "natural_person",
    "registration_date": "2019-12-11T11:37:15.12-03:00",
    "account_data": {
      "account_number": "12345678",
      "agency_number": "1234"
      ...
    }
  }
```

Para realizar a criação de uma account, basta enviar um objeto do tipo Account ao seguinte endpoint:

`POST https://api.caas.qitech.app/device_manager/account`

---

# Autenticação

URL: /documentation/caas/device_manager/authentication

> Para autenticar uma chamada, utilize o código a seguir:

```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

> Substitua a API Key 'EXAMPLE-OF-API-KEY' pela sua chave, que deve ser obtida através do nosso time de suporte.

Utilizamos uma API Key para permitir acesso à nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br .

Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:

`Authorization: EXAMPLE-OF-API-KEY`

:::info **Atenção**

Você deve substituir EXAMPLE-OF-API-KEY pela sua chave, que deve ser obtida com o nosso time de suporte.
:::

---

# Objeto Device

URL: /documentation/caas/device_manager/device_registration

O registro de um device (dispositivo) com identificação única deve ser realizado por meio do endpoint de Device. Para que o cadastro seja efetivado, é necessária a utilização da Device Scan para que a identificação desse device seja registrada para reconhecimento posterior.

### Dinâmica dos Status - **status**

O status **status** refere-se ao status atual do device. Os seguintes status estão disponíveis:

* registered
* not_registered
* deactivated

### Dinâmica dos Status - **analysis_status**

O status **analysis_status** indica o status da decisão do motor de fraude e possui o seguinte fluxo de estados:

* automatically_approved
* automatically_reproved
* pending

## Definição do Objeto Device

Request Body

```json
{
  "device_id": "12345678",
  "session_id": "12345678",
  "face_recognition_key": "12345678",
  "document_number": "111.111.111-11",
  "mfa_status": "approved",
  "registration_date": "2019-12-11T11:37:15.12-03:00"
}
```

Todas as trocas de informação de um cadastro utilizam a seguinte definição para este objeto. Em alguns casos, para facilitar a implementação e diminuir o fluxo de dados entre as partes, algumas informações poderão ser omitidas.

nome | tipo | descrição
:----: | :----: | ---------
device_id | string | Identificador do device. **É essencial que este número seja único para cada device** *(obrigatório)*
session_id | string | Identificador da sessão na Device Scan. *(obrigatório)*
face_recognition_key | string | Identificador da imagem para biometria facial caso o produto seja contratado como 2FA do cadastro.
document_number | string | Documento do usuário para validação de rosto. Só deve ser enviado caso não tenha sido informado no momento do cadastro do objeto person.
mfa_status | string | Status do MFA do cadastro podendo estar entre os seguintes valores: *approved* *reproved*
registration_date | datetime | A data e hora de início do cadastro, com fuso horário. *(obrigatório)*

:::warning Atenção
 O campo `document_number` é necessário para a validação do rosto na base, então, caso não tenha sido informado no momento do cadastro do usuário, ele é obrigatório. Ele nunca deve ser diferente do cadastrado na person.
:::

## Enviar um Device Registration

Request Body

```json
  {
    "device_id": "12345",
    ...
  }
```

Response Body

```json
  {
    "device_id": "12345",
    "status": "registered",
    "analysis_status": "automatically_approved",
    "reason": "rule_decision_enum",
    "reason_description": "Descrição da regra"
  }
```

Para realizar o registro de um device, basta enviar um objeto do tipo Device ao seguinte endpoint:

`POST https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}/device`

---

# Status HTTP

URL: /documentation/caas/device_manager/http_status

Todas as APIs da QI Tech utilizam a seguinte padronização nos status HTTP de retorno, conforme a RFC 7231 :

Status HTTP | Significado | Descrição
:----------: | :-------: | ---------------------------------
400 | Bad Request | A requisição enviada possui algum erro de formatação. Geralmente, retornamos no corpo da mensagem uma explicação de onde está o erro.
401 | Unauthorized | Houve algum problema na autenticação, verifique se a API Key está correta e no header correto, conforme a seção Autenticação .
403 | Forbidden | O endpoint acessado é de uso interno e não está disponível para esta API Key.
404 | Not Found | O dado requisitado não foi encontrado com a chave utilizada. Este status também é retornado quando um endpoint inválido é requisitado.
405 | Method Not Allowed | O método HTTP utilizado não se aplica a este endpoint.
406 | Not Acceptable | Os dados enviados no corpo da requisição são inválidos. Em geral, isso significa que os dados enviados não são um JSON válido.
409 | Conflict | O id da requisição corresponde a um id já processado anteriormente. Este status é retornado no caso de requisições duplicadas enviadas ao servidor.
500 | Internal Server Error | Tivemos um problema para processar esta requisição. Ao encontrarmos esse erro, nossos especialistas são automaticamente notificados e iniciam a análise e solução imediatamente.
503 | Service Unavailable | Indica uma indisponibilidade temporária, planejada ou não, de infraestrutura dos nossos servidores.

---

# Introdução

URL: /documentation/caas/device_manager/introduction

Bem-vindo à API de Cadastro de Dispositivos da QI Tech! Esta api foi projetada para atender a [Normativa 491 do BACEN](https://www.bcb.gov.br/estabilidadefinanceira/exibenormativo?tipo=Instru%C3%A7%C3%A3o%20Normativa%20BCB&numero=491). Em conjunto com a Device Scan, essa API é capaz de gerar uma identificação única para cada dispositivo.

Esta API administra o processo de identificação de dispositivos, possibilitando que, posteriormente, você possa validar esse mesmo aparelho. Este fluxo é estruturado por meio das entidades a seguir:

* Account - Conta
* Person - Pessoa
* Device - Dispositivo

Você pode utilizar a nossa API para criar e recuperar cadastros de dispositivos por meio de do seguinte serviço:

* **Device Registration** - utilizado para associar um dispositivo a uma pessoa. Por meio desse cadastro, será possível realizar as validações de dispositivo para os demais acessos desta mesma pessoa.

## Ambientes

Possuímos dois ambientes para os nossos clientes. As URLs base das APIs são:

* Produção - `https://api.caas.qitech.app/device_manager/`
* Sandbox - `https://api.sandbox.caas.qitech.app/device_manager/`

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.
:::

No ambiente de Sandbox, as análises enviadas não são cobradas e são respondidas conforme a regra configurada para o evento.

## Somente HTTPS

Por questão de segurança, toda a comunicação com as APIs da QI Tech deve ser realizada utilizando a comunicação HTTPS. Para garantir que, por desatenção ou qualquer outro motivo, não ocorram chamadas HTTP, este servidor somente disponibiliza a porta 443 com comunicação TLS 1.2. Chamadas realizadas utilizando outros protocolos serão automaticamente negadas.

## Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso suporte e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

### Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (como um erro de digitação ou uma organização inadequada), envie-nos um e-mail. Assim, nós tornamos a documentação cada vez mais prática para evitar que outros desenvolvedores encontrem as mesmas dificuldades.

---

# Objeto Person

URL: /documentation/caas/device_manager/person

A conta pode ter mais de um usuário a acessando, logo, cada usuário deve ter seu registro para segregar ações em contas conjuntas. As informações citadas abaixo devem seguir os padrões estabelecidos, mas quaisquer campos podem ser adicionados aos dados da conta caso seja necessário.

## Definição do Objeto Person

Request Body

```json
{
  "person_id": "12345678",
  "document_number": "111.111.111-11",
  "registration_date": "2019-12-11T11:37:15.12-03:00",
  "person_data": {
    "name": "Joao da Silva",
    "email": "person@email.com",
    "phone": {
      "number": "999999999",
      "international_dial_code": "55",
      "area_code": "11"
    }
  }
}
```

Todas as trocas de informação de uma pessoa utilizam a seguinte definição para este objeto. Em alguns casos, para facilitar a implementação e diminuir o fluxo de dados entre as partes, algumas informações poderão ser omitidas.

nome | tipo | descrição
:----: | :----: | ---------
person_id | string | Identificador da pessoa. **É essencial que este número seja único para cada pessoa** *(obrigatório)*
document_number | string | número do documento, podendo ser CPF ou CNPJ com pontuação.
registration_date | datetime | Data e hora do registro da pessoa associada à conta, com fuso horário. *(obrigatório)*
person_data | object | objeto que pode conter quaisquer dados da pessoa. Se contiver o nome `name`, email `email`, e telefone `phone` (com seus campos `number`, `international_dial_code` e `area_code`), todos os objetos citados devem ser do tipo string.

## Criar um Person

Request Body

```json
  {
    "person_id": "12345678",
    ...
  }
```

Response Body

```json
  {
    "person_id": "12345678",
    "document_number": "111.111.111-11",
    "registration_date": "2019-12-11T11:37:15.12-03:00",
    "person_data": {
      "name": "Joao da Silva",
      "email": "person@email.com",
      "phone": {
        "number": "999999999",
        "international_dial_code": "55",
        "area_code": "11"
      }
    }
  }
```

Para realizar a criação de uma pessoa, basta enviar um objeto do tipo Person ao seguinte endpoint:

`POST https://api.caas.qitech.app/device_manager/account/{account_id}/person`

---

# Recuperar ou Desativar uma Account, Person ou Device

URL: /documentation/caas/device_manager/query_registration

## Buscar Device específico

A fim de recuperar um Device específico, basta realizar uma requisição GET. O resultado retornado é o JSON mais atualizado do Device em questão. Caso este identificador não esteja relacionado a nenhum objeto, o HTTP Status 404 é retornado.

`GET https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}/device/{device_id}`

```shell
curl "https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}/device/{device_id}"
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

## Buscar Lista de Devices

Para recuperar vários devices, basta realizar uma requisição GET. O resultado retornado é o JSON com uma lista de informações básicas de todos os devices de um usuário.

`GET https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}/devices`

```shell
curl "https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}/devices"
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

## Desativar Device específico

Para desativar um Device específico, basta realizar uma requisição DELETE. Caso este identificador não esteja relacionado a nenhum objeto, o HTTP Status 404 é retornado. Um device após ser desativado não pode mais ser validado.

`DELETE https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}/device/{device_id}`

```shell
curl -X DELETE "https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}/device/{device_id}" \
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

## Buscar Conta específica

Permite recuperar os dados de uma conta pelo seu identificador. Retorna os detalhes da conta, ou 404 caso não exista.

`GET https://api.caas.qitech.app/device_manager/account/{account_id}`

```shell
curl "https://api.caas.qitech.app/device_manager/account/{account_id}" \
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

## Buscar Pessoa específica

Permite recuperar os dados de uma pessoa específica dentro de uma conta. Retorna os dados atualizados da pessoa, ou 404 caso não exista.

`GET https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}`

```shell
curl "https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}" \
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

---

## Desativar Conta

Realiza a desativação de uma conta. Após desativada, a conta não poderá mais ser utilizada para registro ou validação de devices.

`DELETE https://api.caas.qitech.app/device_manager/account/{account_id}`

```shell
curl -X DELETE "https://api.caas.qitech.app/device_manager/account/{account_id}" \
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

## Desativar Pessoa

Realiza a desativação de uma pessoa dentro de uma conta. Após desativada, a pessoa não poderá mais registrar ou validar devices.

`DELETE https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}`

```shell
curl -X DELETE "https://api.caas.qitech.app/device_manager/account/{account_id}/person/{person_id}" \
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

---

# Padrões

URL: /documentation/caas/device_manager/standards

Para facilitar a integração e garantir a integridade da informação, foram definidos alguns padrões seguidos em toda a API.

## Valores Monetários
> Exemplos:

```
10000
12345
98741
1223
1
0
```

As APIs assumem que todos os valores monetários enviados são em reais brasileiros. Os valores devem ser enviados como números inteiros representando centavos.

## Data e Hora com Fuso Horário
> Alguns exemplos:

```
2019-10-15T22:35:12.232-03:00
2018-05-01T13:32:11.297+00:00
2019-05-01T00:00:00.000+00:00
```

É representada conforme a ISO 8601. Neste caso, o fuso-horário é colocado logo após o horário e deve representar o fuso do local onde aquele dado será valido.

A máscara utilizada para validação é a seguinte:

`YYYY-MM-ddThh:mm:ss.sss±hh:mm`

## Data e Hora sem Fuso Horário
> Alguns exemplos:

```
2019-10-15T22:35:12
2018-05-01T13:32:11
2019-05-01T00:00:00
```

É representada conforme a ISO 8601. Dados que independem de fuso-horário deverão em UTC, com a letra Z indicando que este dado está em UTC. O seguinte formato, portanto, será validado:

`YYYY-MM-ddThh:mm:ss.sssZ`

## Data
> Alguns exemplos

```
2019-10-15
2019-01-01
2017-03-20
```

No caso de campos que recebem somente a data, sem nenhum horário, ela deve ser enviada com o seguinte formato:

`YYYY-MM-dd`

## Documentos
Uma vez que os números de documento são bastante variados e muitos deles possuem caracteres que não se enquadram como numéricos, definem-se todos os números de documento como string. Outro bom motivo para defini-los como string é evitar que os zeros à esquerda desapareçam. Documentos previstos nesta página possuem uma máscara bem definida e estarão sujeitos à validação. O restante dos documentos, como RG, dada sua falta de padronização, não serão validados.

## CPF

> Exemplos de CPFs válidos contra a máscara definida:

```
123.456.789-12
321.987.543-23
111.283.333-00
```

> Exemplos de CPFs inválidos contra a máscara definida:

```
8.577.477-8
08.104.627/0001-23
123.456.789-1
23.456.789-01
```

O CPF é sempre definido como uma string e será validado contra a máscara:

`###.###.###-##`

## CNPJ

> Exemplos de CNPJs válidos contra a máscara definida:

```
08.104.627/0001-02
01.079.210/0114-67
32.402.502/0001-35
```

> Exemplos de CNPJs inválidos contra a máscara definida:

```
8.577.477-8
123.456.789-12
321.987.543-23
32.402.502/0001-3
032.402.502/0001-3
```

O CNPJ é sempre definido como uma string e será validado contra a máscara:

`##.###.###/####-##`

## IP

> Exemplos de IPs válidos contra a máscara definida:

```
201.81.161.86
201.081.161.86
201.81.161.086
201.81.0.1
```

> Exemplos de IPs inválidos:

```
201.81..86
358.81.161.86
201.81.161
```

IPs deverão ser enviados sempre em IPv4, zeros à esquerda poderão ou não ser enviados, respeitando a seguinte máscara:

`###.###.###.###`

---

# Dinâmica dos Status

URL: /documentation/caas/device_manager/status_dynamics

O processo de análise consiste em enviar um evento, como de Device Validation, por exemplo, no endpoint adequado e aguardar a resposta.

Após a QI Tech realizar a análise do evento, ela retornará uma resposta com um status referente à análise. O campo **analysis_status** representa o resultado da análise de evento realizada pela QI Tech.

### **analysis_status**

Conforme descrito anteriormente, a QI Tech possui três **analysis_status** que indicam o status da decisão do motor de análise e possui a seguinte máquina de estados:

analysis_status | Descrição
:---------: | ---------
automatically_approved | Os algoritmos da QI Tech recomendam que este evento seja aprovado.
automatically_reproved | Os algoritmos da QI Tech recomendam que este evento seja reprovado.
pending | As consultas estão demorando mais do que o esperado, este evento entrou em uma fila de análise automática e será respondido assim que possível.

---

# Compatibilidade da Biblioteca

URL: /documentation/caas/device_scan/android/compatibility

| Configuração | Versão mínima |
|------------|--------------|
|minSdkVersion|21|

---

# O objeto DeviceScan

URL: /documentation/caas/device_scan/android/device_scan_object

Para utilizar a DeviceScanSDK, é necessário instanciar a classe DeviceScan. Essa instância recebe o currentContext e pode ser configurada com token/sessão, ambiente e callback (notifier).

:::danger Aviso Importante!
A partir da versão 5.0.0, o sistema de autenticação foi atualizado para usar um **token** temporário no lugar do **mobileToken**.
:::

## Versão 5.0.0+

| Parâmetro | Função | Obrigatório |
|------------|--------------|--------------|
|currentContext|Contexto da aplicação, utilizado no acesso a dados necessários. |Sim.|
|token (via .setToken(this.token))| Token de autenticação que identifica que os dados coletados são provenientes do seu aplicativo. O token é obtido por meio de requisição à API da Device Scan. |Sim.|
|sessionId (via .setSessionId(this.sessionId))|Identificador da sessão de onde os dados coletados são provenientes.|Sim.|
|notifier (via .setNotifier(this.deviceScanNotifier))|Instância de DeviceScanNotifier. Atua como callback, retornando a situação do envio (sucesso ou falha). |Não.|
|sandbox (via .setSandboxEnvironment())|Configura a biblioteca para enviar dados ao ambiente `sandbox`. Se não configurado, as requisições são enviadas para `production`. |Não.|

 **Ambiente padrão**: caso `setSandboxEnvironment()` não seja chamado, o envio é feito para `production`. 

## Versões Anteriores (até 4.x)

| Parâmetro | Função | Obrigatório |
|------------|--------------|--------------|
|currentContext|Contexto da aplicação, utilizado no acesso a dados necessários.|Sim.|
|mobileToken (via .setMobileToken(this.mobileToken))|Chave do cliente que identifica que os dados coletados são provenientes do seu aplicativo. Caso ainda não tenha recebido o seu **mobile-token**, entre em contato com o suporte: <a href='mailto:suporte.caas@qitech.com.br'>suporte.caas@qitech.com.br</a>.|Sim.|
|sessionId (via .setSessionId(this.sessionId))|Identificador da sessão de onde os dados coletados são provenientes.|Sim.|
|notifier (via .setNotifier(this.deviceScanNotifier))|Instância de DeviceScanNotifier. Atua como callback, retornando a situação do envio (sucesso ou falha).|Não.|
|sandbox (via .setSandboxEnvironment())|Configura a biblioteca para enviar dados ao ambiente `sandbox`. Se não configurado, as requisições são enviadas para `production`. |Não.|

## Resumo Rápido (Migração)
- 5.0.0+: usar `token` temporário (`setToken(this.token)`)
- < 5.0.0: usar `mobileToken` (`setMobileToken(this.mobileToken)`)
- Em ambas: `currentContext` e `sessionId` são obrigatórios. `notifier` e `sandbox` são opcionais.

---

# Implementação

URL: /documentation/caas/device_scan/android/example

:::danger Aviso Importante!
A partir da versão 5.0.0, o sistema de autenticação foi atualizado para usar um **token** dinâmico em vez de **mobileToken**. Antes de configurar o SDK, você deve gerar um **token** temporário através de uma requisição server-to-server para a nossa API de Device Scan.
:::

```java
package com.example.zaig_device_scan_sdk_test_app;

import androidx.appcompat.app.AppCompatActivity;

import android.os.Bundle;
import android.util.Log;
import android.view.View;

import com.qitech.android.devicescan.DeviceScan;
import com.qitech.android.devicescan.DeviceScanNotifier;

import java.util.ArrayList;

public class MainActivity extends AppCompatActivity {
    private DeviceScan deviceScan;
    private DeviceScanNotifier deviceScanNotifier;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        deviceScanNotifier = new DeviceScanNotifier(this);
    }

    public void sendDeviceScan(View view) {
        try{
            deviceScan = new DeviceScan.Builder(this.getApplicationContext())
                .setToken(this.token)
                .setSessionId(this.sessionId)
                .setNotifier(this.deviceScanNotifier)
                .setSandboxEnvironment()
                .build();
        }catch (Exception ex) {
            Log.e("DeviceScan Error", "There was an error collecting DeviceScan data: " + ex.toString());
        }
    }

    @Override
    public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults){
        try{
            deviceScan.collectData(this.documentNumber,
                    this.eventId,
                    this.eventType);
        }catch (Exception ex) {
            Log.e("DeviceScan Error", "There was an error collecting DeviceScan data: " + ex.toString());
        }
    }

    private class ScanNotifier implements DeviceScanNotifier {
        AppCompatActivity activity;
        public ScanNotifier (AppCompatActivity myActivity){
            // Este método é customizável e pode ser utilizado para se armazenar a Activity, utilizada para operar a UI
            this.activity = myActivity;
        }

        public void onSuccess(){
            Log.i("DeviceScan", "DeviceScan successfully submitted");
            runOnUiThread(new Runnable() {
                @Override
                public void run() {
                    // Adicionar aqui quaisquer mudanças de UI que sejam necessárias após o envio com sucesso do device scan
                }
            });
        }

        public void onError(){
            Log.i("DeviceScan", "DeviceScan submission failed");
            runOnUiThread(new Runnable() {
                @Override
                public void run() {
                    // Adicionar aqui quaisquer mudanças de UI que sejam necessárias após o envio com sucesso do device scan
                }
            });
        }
    }
}

```

Para utilizar o SDK do device scan android, os seguintes passos são necessários:

* Inserir as autorizações ao manifest da aplicação;
* Importar a biblioteca ao projeto da aplicação;
* Ao iniciar a aplicação, instanciar a biblioteca, passando os parâmetros adequados em seu construtor, incluindo o Notifier, responsável por dar o CallBack da operação com o resultado;
* Utilizar a função `onRequestPermissionsResult` da Activity para ser notificado do resultado da aprovação ou não das permissões requeridas;
* Requisitar as permissões ao usuário. É obrigatória a permissão de acesso a internet para o funcionamento da biblioteca;
* Ao ser notificado do resultado da aprovação ou não das permissões, colete e envie os dados por meio do método `collectData`.

---

# Coleta de informações

URL: /documentation/caas/device_scan/android/information_gathering

Para disparar a coleta e o envio de informações, é necessário (após obter as permissões do usuário) chamar o método `collectData`. O método, além de capturar as informações do dispositivo, tem como objetivo mapear a jornada do cliente dentro da aplicação. Por esse motivo, o método também aceita os campos `eventId` e `eventType`. O método possui os seguintes parâmetros:

nome | tipo | descrição
---- | ---- | ---------
documentNumber | String | O número do documento do usuário, caso disponível. (CPF/CNPJ sem pontos, traços e barra)
eventId | String | Um identificador do evento que está sendo reportado
eventType | String | Um valor enumerado que define o tipo de evento que está sendo reportado. Recomenda-se cuidado para que eventos muito similares sejam reportados com o mesmo enumerador, a fim de que inteligência possa ser construída sobre esses dados.

Após a chamada de coleta dos dados, um dos dois métodos da instância de `DeviceScanNotifier` passada no construtor da classe `DeviceScan` será chamado: `onSuccess` caso tudo corra conforme o esperado ou `onError`, em caso de erro.

---

# Introdução

URL: /documentation/caas/device_scan/android/introduction

Bem-vindo(a) ao manual de integração do Device Scan Android da QI Tech! Você deve utilizar nosso SDK para coletar informações do dispositivo e do comportamento do usuário no seu aplicativo e, assim, aumentar a assertividade das decisões.

## Problemas?

Não somos uma companhia que se esconde atrás de uma API. Entre em contato com o nosso [suporte](mailto:suporte.caas@qitech.com.br) e responderemos o mais rápido possível. Fique à vontade para nos ligar caso precise de uma resposta mais rápida!

### Adoramos Feedback

Mesmo que você já tenha resolvido o problema ou que ele seja muito simples (como um erro de digitação ou uma organização inadequada), envie-nos um e-mail. Assim, tornamos a documentação cada vez mais prática, e a próxima pessoa não precisa passar pelas mesmas dores.

## Ambientes

Disponibilizamos dois ambientes para os nossos clientes. A seleção é realizada por meio de um enumerador informado no construtor do SDK. No momento, os seguintes ambientes estão disponíveis:

* Produção - `production`
* Sandbox - `sandbox`

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas no ambiente de Sandbox da QI Tech.
:::

---

# Integração nativa

URL: /documentation/caas/device_scan/android/native_java

Para importar nossos SDKs, é necessário realizar alterações nos arquivos build.gradle do projeto e do aplicativo.

## Adicionando ao Projeto
Adicione o endereço do nosso repositório Maven no build.gradle do projeto (no Android Studio, este arquivo aparece como “Project: \{nome_do_projeto\}”), conforme o exemplo abaixo:

```java
buildscript {
    ...
}

allprojects {
    repositories {
        ...
        maven { url 'https://sdks.qitech.com.br/' }
    }
}
```

## Adicionando ao Aplicativo
Em seguida, adicione a biblioteca que você pretende importar no build.gradle do app (no Android Studio, este arquivo aparece como **“Module: \{nome_do_projeto\}.app”**), incluindo a dependência abaixo:

```java
dependencies {
    ...
    implementation 'com.qitech.android:devicescan:v6.0.0'
}
```

:::warning
Desde **abril de 2025**,** novas políticas da Google Play exigem **Android API Level 35** para que aplicativos possam ser publicados ou atualizados na Google Play Store. Por isso, recomendamos fortemente que você utilize **targetSdkVersion 35**, no mínimo.
:::

:::info
A utilização de **targetSdkVersion 35** implica na utilização do **compileSdkVersion 35**, o que acarreta alguns **requisitos mínimos** para ferramentas
do ecossistema do Android:
* compileSdkVersion 35 --> AGP 8.6.0
* AGP 8.6.0 --> Gradle 8.7
* AGP 8.6.0 --> Java 17 (JDK 17)
* AGP 8.6.0 --> Kotlin 2+
:::

## Arquivo Manifest

Para utilizar o SDK, você deve adicionar a seguinte configuração ao AndroidManifest da sua aplicação:

```java
<meta-data
            android:name="com.google.android.gms.ads.AD_MANAGER_APP"
            android:value="true"/>
```

Você também deve adicionar, no mínimo, a permissão de internet, que é utilizada para enviar os dados coletados aos servidores da QI Tech:

` `

A lista de permissões deverá ser ajustada de acordo com a necessidade.

---

# Permissões

URL: /documentation/caas/device_scan/android/permissions

O SDK coleta dados do dispositivo do usuário de acordo com as permissões disponíveis no momento da coleta: quanto mais permissões o seu aplicativo solicitar e o usuário conceder, mais informações poderão ser coletadas.

:::info **Atenção**

A permissão INTERNET é obrigatória para que o SDK consiga enviar as informações aos servidores da QI Tech.
:::

## Permissões utilizadas pelo SDK

Na versão atual do SDK, as permissões abaixo podem ser utilizadas, caso estejam disponíveis:

| Permissão | Função | Obrigatória |
|------------|--------------|--------------|
|INTERNET|Envio das informações aos servidores da QI Tech.| Sim. |
|BLUETOOTH|Captura de informações do hardware de Bluetooth.| Não. |
|BLUETOOTH_CONNECT|Captura de informações de conexão Bluetooth.| Não. |
|READ_CONTACTS|Leitura da agenda de contatos.| Não. |
|ACCESS_COARSE_LOCATION|Acesso a informações de rede (Antena, operadora, etc) e à localização por este meio (menos precisa).| Não. |
|ACCESS_FINE_LOCATION|Acesso à localização por meio de GPS (mais precisa).| Não. |
|READ_PHONE_STATE|Informações de Rede, SIM, Imei e outros aspectos de telefonia.| Não. |
|QUERY_ALL_PACKAGES|Informações de aplicativos instalados no dispositivo. Necessária para devices Android 11 em diante.| Não. |

:::info **Importante**

Nosso SDK não solicita as permissões descritas. Portanto, para garantir um device scan mais completo, recomendamos solicitar e obter essas permissões antes de executar a chamada do device scan.
:::

:::info **Atenção**

A permissão QUERY_ALL_PACKAGES pode gerar atrito com o Google Play no momento do lançamento do app. Para contornar esse ponto, é possível descrever o motivo da solicitação dessa permissão.
:::

---

# Autenticação

URL: /documentation/caas/device_scan/api/authentication

:::danger Aviso Importante!
A partir da versão 5.0.0 dos SDKs de iOS e Android, o sistema de autenticação foi atualizado para usar um token temporário em vez do mobileToken.
:::

Utilizamos uma API Key para permitir o acesso à nossa API. Normalmente, essa chave é enviada por e-mail. Caso você ainda não tenha recebido a sua, envie uma mensagem para suporte.caas@qitech.com.br .

## Token temporário de autenticação

Antes de configurar o SDK, você deve gerar um token temporário por meio de uma requisição server-to-server para a nossa API.

### Gerar token

```bash
curl -X POST "https://d.viewpkg.com/device_scan/token" \
     -H "Authorization: EXAMPLE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "session_id": "unique_session_identifier" }'
```

**Endpoints**

| Ambiente | URL |
|----------|-----|
| Sandbox | https://d.sandbox.viewpkg.com/device_scan/token |
| Produção | https://d.viewpkg.com/device_scan/token |

**Detalhes da Requisição**

| Campo | Tipo | Obrigatório | Descrição|
|-------|------|------------|---------|
| session_id | string | Sim | Identificador único da sessão gerado pelo seu sistema (por exemplo, UUID). |

**Request Body**
```json
{
  "session_id": "unique_session_identifier" 
}
```

**Response Body**

A resposta bem-sucedida conterá o campo `token`.
```json
{
  "token": "eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6..."
}
```

:::info Atenção
Substitua `EXAMPLE_API_KEY` pela API Key recebida do suporte.
:::

---

# Compatibilidade da Biblioteca

URL: /documentation/caas/device_scan/flutter/compatibility

| Configuração | Versão mínima |
|------------|--------------|
|Flutter|3.3.0|
|Dart SDK|3.2.3|
|iOS|15.5|
|minSdkVersion (Android)|23|
|Datadog SDK nativo (iOS, trazido pelo plugin)|3.x|

---

# O objeto QitechDeviceScan

URL: /documentation/caas/device_scan/flutter/device_scan_object

:::danger Aviso Importante!
A partir da versão 1.0.0, o sistema de autenticação foi atualizado para usar um **token** temporário no lugar do **mobileToken**. O token é obtido por meio de requisição server-to-server à API da Device Scan.
:::

## Chamada

Para utilizar o plugin de Device Scan, é necessário realizar a chamada do método `startDeviceScan` que possui os seguintes parâmetros:

## Versão 1.0.0+

| Parâmetro | Tipo | Função | Obrigatório |
|------------|--------------|--------------|--------------|
|token|String|Token de autenticação temporário obtido por meio de requisição à API da Device Scan. Deve ser gerado com o mesmo `sessionId` passado a este método.|Sim.|
|environment|CaaSEnvironment|Enumerador utilizado para configurar o ambiente de execução para `sandbox` ou `production`. |Sim.|
|sessionId|String|Chave que identifica a sessão da qual os dados coletados são provenientes. **Deve ser enviado em letras minúsculas.**|Sim.|
|eventType|String|Um enumerador que define o tipo de evento sendo reportado - É pedido cuidado para que eventos muito similares seja reportados com o mesmo enumerador, a fim de que inteligência possa ser construída sobre esses dados.|Sim.|
|eventId|String|Um identificador do evento sendo reportado|Sim.|
|documentNumber|String?|O número do documento do usuário, caso disponível. (CPF/ CNPJ sem pontos, traços e barra). Pode ser omitido.|Não.|

## Versões Anteriores (até 0.x)

| Parâmetro | Tipo | Função | Obrigatório |
|------------|--------------|--------------|--------------|
|mobileToken|String|Chave do cliente que identifica que os dados coletados são provenientes do seu aplicativo. Caso ainda não tenha recebido o seu mobile-token, entre em contato com o <a href='mailto:suporte.caas@qitech.com.br'>suporte</a>.|Sim.|
|environment|CaaSEnvironment|Enumerador utilizado para configurar o ambiente de execução para `sandbox` ou `production`. |Sim.|
|sessionId|String|Chave que identifica a sessão da qual os dados coletados são provenientes. **Deve ser enviado em letras minúsculas.**|Sim.|
|eventType|String|Um enumerador que define o tipo de evento sendo reportado - É pedido cuidado para que eventos muito similares seja reportados com o mesmo enumerador, a fim de que inteligência possa ser construída sobre esses dados.|Sim.|
|eventId|String|Um identificador do evento sendo reportado|Sim.|
|documentNumber|String?|O número do documento do usuário, caso disponível. (CPF/ CNPJ sem pontos, traços e barra). Pode ser omitido.|Não.|

## Resumo Rápido (Migração)
- 1.0.0+: usar `token` temporário obtido via API (`token: token`)
- '`)
- Em ambas: `environment`, `sessionId`, `eventType` e `eventId` são obrigatórios. `documentNumber` é opcional.

## Migração para a 2.0.0
- `pubspec.yaml`: `qitech_device_scan: ^2.0.0`. O código Dart não muda.
- iOS: `source 'https://github.com/QITechSDKs/iOS.git'` no `Podfile`. O SDK nativo passa a exigir Datadog 3.x (`datadog_flutter_plugin` 3.x, se utilizado).
- Android: repositório Maven `https://sdks.qitech.com.br/` no `build.gradle`.

## Retorno

O método retorna uma String para indicar sucesso ou falha durante a coleta das informações:

### Sucesso

```javascript
Success collecting device scan data
```

### Erro

```javascript
Device Scan fail. Check token, environment and permissions
```

---

# Implementação

URL: /documentation/caas/device_scan/flutter/example

Antes de executar o exemplo abaixo, instale o plugin e aplique as configurações nativas de Android e iOS descritas em [Instalação](/documentation/caas/device_scan/flutter/installation).

## Pré-requisito para startDeviceScan

O método `startDeviceScan` requer um `token`. Este token é temporário e deve ser gerado no seu backend por meio de uma requisição server-to-server para a nossa API antes de chamar o método do SDK.

**Detalhes do Endpoint:**

- **Método:** POST
- **Path:** `/device_scan/token`
- **Sandbox URL:** `https://d.sandbox.viewpkg.com/device_scan/token`
- **Production URL:** `https://d.viewpkg.com/device_scan/token`

**Headers:**

```json
{
  "Authorization": "YOUR_DEVICE_SCAN_API_KEY"
}
```

**Body:**

```json
{
  "session_id": "unique_session_id"
}
```

A resposta bem-sucedida desta API conterá o `token` que você deve repassar ao método `startDeviceScan`.

:::note
O método de device scan pode ser executado de forma assíncrona. Portanto, não é necessário bloquear a thread principal para aguardar a resolução deste método. O usuário pode interagir normalmente com o app enquanto o device scan é processado em segundo plano.
:::

:::note
Recomendamos que o método de device scan seja executado o mais cedo possível. Como ele pode precisar de mais tempo de execução para coletar todos os dados, esta chamada antecipada é recomendada para que as informações mais completas do dispositivo sejam extraídas.
:::

---

```dart

import 'dart:convert';
import 'dart:io';
import 'package:http/http.dart' as http;
import 'package:qitech_device_scan/qitech_device_scan.dart';

final _qitechDeviceScanPlugin = QitechDeviceScan();

// Etapa 1: Gerar o token temporário via requisição server-to-server
Future<String?> fetchDeviceScanToken(String sessionId) async {
  final response = await http.post(
    Uri.parse('<DEVICE_SCAN_API_URL>'),
    headers: {
      HttpHeaders.authorizationHeader: '<API_KEY>',
      HttpHeaders.contentTypeHeader: 'application/json',
    },
    body: jsonEncode({'session_id': sessionId}),
  );

  if (response.statusCode == 200) {
    final data = jsonDecode(response.body);
    return data['token'] as String?;
  }
  return null;
}

// Etapa 2: Inicializar o SDK com o token obtido
final sessionId = '<SESSION_ID>';
final token = await fetchDeviceScanToken(sessionId);

if (token == null) {
  print('Failed to fetch device scan token');
  return;
}

final result = await _qitechDeviceScanPlugin.startDeviceScan(
    token: token,
    environment: CaaSEnvironment.sandbox,
    sessionId: sessionId,
    eventType: '<EVENT_TYPE>',
    eventId: '<EVENT_ID>',
);

print('Device Scan result: $result');

```

---

# Instalação

URL: /documentation/caas/device_scan/flutter/installation

## Instalando o plugin

Execute o comando abaixo na raiz do seu projeto Flutter:

```bash
flutter pub add qitech_device_scan
```

O comando instala a versão mais recente e adiciona a dependência ao seu `pubspec.yaml`:

```yaml
dependencies:
  qitech_device_scan: ^2.0.0
```

## Importação

```dart
import 'package:qitech_device_scan/qitech_device_scan.dart';
```

E instancie o plugin:

```dart
final _qitechDeviceScanPlugin = QitechDeviceScan();
```

## Configuração do Android

### 1. Repositório Maven da QI Tech

Adicione a referência do repositório Android da QI Tech no seu arquivo `build.gradle`:

```gradle
allprojects {
    repositories {
        maven { url 'https://sdks.qitech.com.br/' }
        ...
    }
}
```

### 2. AdMob

Inicialize o serviço de AdMob ao adicionar o seguinte código em seu `AndroidManifest.xml`:

```xml
<meta-data
    android:name="com.google.android.gms.ads.APPLICATION_ID"
    android:value="<ADMOB_APP_ID>"/>
```

Caso não possua um `ADMOB_APP_ID`, entre em contato com o suporte.caas@qitech.com.br .

### 3. Permissões

Declare no `AndroidManifest.xml` as permissões que deseja disponibilizar ao SDK. Veja [Permissões](/documentation/caas/device_scan/flutter/permissions) para a lista completa.

## Configuração do iOS

### 1. Source do repositório iOS da QI Tech

Adicione a referência do repositório iOS da QI Tech em seu arquivo `Podfile`:

```ruby
source 'https://cdn.cocoapods.org/'
source 'https://github.com/QITechSDKs/iOS.git'
```

### 2. Permissões

Declare no `Info.plist` as permissões que deseja disponibilizar ao SDK. Veja [Permissões](/documentation/caas/device_scan/flutter/permissions).

### 3. Instalação das dependências

Instale as dependências diretamente através do CocoaPods:

```bash
cd ios
pod install
```

ou através do Flutter:

```bash
flutter build ios
```

:::warning Atenção
A partir da versão **2.0.0**, o SDK nativo de iOS exige o Datadog `3.x`. Se o seu aplicativo já utiliza o `datadog_flutter_plugin`, use a versão mais recente dentro do major `3.x`.
:::

---

# Introdução

URL: /documentation/caas/device_scan/flutter/introduction

Bem vindo ao manual de integração da Device Scan da QI Tech em Flutter! Você deve utilizar o nosso Plugin para coletar informações do celular e do comportamento do usuário em seu aplicativo e assim melhorar a assertividade das decisões.

## Plugins disponíveis

| Plugin | Conteúdo | Quando usar |
|--------|----------|-------------|
|`qitech_device_scan`|Somente Scan de dispositivo|Quando você precisa **apenas** de scan de dispositivo — instalação mais leve, com menos dependências nativas.|
|`flutter_kyc_qitech`|Reconhecimento facial, OCR e Scan de dispositivo|Quando você também precisa de reconhecimento facial ou OCR.|

:::danger Aviso Importante!
Ambos os plugins incluem o Scan de dispositivo. **Não instale os dois** — escolha apenas um.
:::

Esta seção documenta o `qitech_device_scan`. Se o seu aplicativo utiliza o `flutter_kyc_qitech`, consulte a seção [Flutter do Reconhecimento facial](/documentation/caas/face_recognition/flutter/introduction) ou [Flutter do OCR](/documentation/caas/ocr/flutter/introduction) — naquele plugin, o método `startDeviceScan` recebe parâmetros posicionais em vez de nomeados.

## Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso [suporte](mailto:suporte.caas@qitech.com.br) e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

### Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

## Ambientes

Possuímos dois ambientes para os nossos clientes. A seleção é realizada por meio de enumerador repassado no parâmetro da chamada do plugin, no momento, os seguintes ambientes estão disponíveis:

* Produção - `production`
* Sandbox - `sandbox`

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.  
:::

---

# Permissões

URL: /documentation/caas/device_scan/flutter/permissions

O plugin coleta dados do dispositivo do usuário conforme as permissões que estão disponíveis no momento da coleta: conforme mais permissões seu aplicativo requerir e o usuário disponibilizar, mais informações são coletadas do dispositivo do usuário.

:::info **Atenção**

A permissão de INTERNET é obrigatória para que o SDK consiga enviar as informações aos servidores da QI Tech.
:::

## Permissões utilizadas pelo plugin

:::info **Importante**

Nosso plugin não solicita as permissões descritas. Portanto, para garantir um scan de dipositivo mais completo, recomendamos a coleta dessas permissões antes de executar a chamada da device scan.
:::

### Android

Para a plataforma android, as seguintes permissões são utilizadas caso estejam disponíveis:

| Permissão | Função | Obrigatória |
|------------|--------------|--------------|
|INTERNET|Obrigatória, para envio das informações aos servidores da QI Tech.| Sim. |
|BLUETOOTH|Captura de informações do hardware de Bluetooth.| Não. |
|BLUETOOTH_CONNECT|Captura de informações de conexão Bluetooth.| Não. |
|READ_CONTACTS|Leitura da agenda de contatos.| Não. |
|ACCESS_COARSE_LOCATION|Acesso a informações de rede (Antena, operadora...) e à localização por este meio (Menos preciso).| Não. |
|ACCESS_FINE_LOCATION|Acesso à localização por meio de GPS (Mais preciso).| Não. |
|READ_PHONE_STATE|Informações de Rede, SIM, Imei e outros aspectos de telefonia.| Não. |
|QUERY_ALL_PACKAGES|Informações de aplicativos instalados no dispositivo. Necessária para devices Android 11 em diante.| Não. |

:::info **Atenção**

A permissão de QUERY_ALL_PACKAGES pode gerar atrito com o Google Play no momento do lançamento do App. Para solucioná-lo é possível descrever o motivo da solicitação da permissão.
:::

### iOS

Para a plataforma iOS, as seguintes permissões são utilizadas caso estejam disponíveis:

* location - Captura de dados de geolocalização do device

#### Arquivo Info.plist

O primeiro passo para disponibilizar permissões para o plugin é configurar a permissão no arquivo Info.plist da aplicação, utilizando a seguinte linha de código para cada uma das permissões desejadas:

* location - Captura de dados de geolocalização do device:

` NSLocationWhenInUseUsageDescription `
` Adicionar a mensagem que você deseja que apareça para o usuário quando o iOS solicitar a permissão de acesso à geolocalização `

:::info **Atenção**

Para melhorar a experiência do usuário no momento da solicitação das permissões você deve personalizar a mensagem reproduzida no pop-up de solicitação conforme descrito anteriormente.
:::

---

# O objeto QITechIosDeviceScan

URL: /documentation/caas/device_scan/ios/device_scan_object

Para utilizar o DeviceScan iOS da QI Tech, é necessário importar o framework QITechIosDeviceScan e então instanciar a classe QITechIosDeviceScan que possui os seguintes parâmetros no construtor:

:::danger Aviso Importante!
A partir da versão 5.0.0, o sistema de autenticação foi atualizado para usar um **token**  temporário em vez de **mobileToken**.
:::

## Versão 5.0.0+

nome | tipo | descrição
---- | ----- | ------
environment | String | Um enumerador do ambiente onde a aplicação está sendo executada - `sandbox` ou `production` - caso um valor diferente seja enviado, uma exceção será gerada **obrigatório**
token | String | Token de autenticação que identifica que os dados coletados são provenientes do seu aplicativo. Obtida através de requisição à API da Device Scan. **obrigatório**
sessionId | String | O identificador da sessão (**Deve ser o mesmo utilizado para gerar o token**), que será enviado também no momento da avaliação do evento (Transação, Onboarding, por exemplo), para cruzamento entre os dados do device scan e o evento a ser avaliado. **obrigatório**

## Versões Anteriores

nome | tipo | descrição
---- | ----- | ------
environment | String | Um enumerador do ambiente onde a aplicação está sendo executada - `sandbox` ou `production` - caso um valor diferente seja enviado, uma exceção será gerada **obrigatório**
mobileToken | String | A chave de cliente enviada pelo suporte da QI Tech e que identifica que os dados coletados são provenientes do seu aplicativo. Por questões de segurança, caso esta chave esteja incorreta, os servidores da QI Tech recebem mas não processam a chamada. **obrigatório**
sessionId | String | O identificador da sessão, que será enviado também no momento da avaliação do evento (Transação, Onboarding, por exemplo), para cruzamento entre os dados do device scan e o evento a ser avaliado. **obrigatório**

---

# Implementação

URL: /documentation/caas/device_scan/ios/example

:::danger Aviso Importante!
A partir da versão 5.0.0, o sistema de autenticação foi atualizado para usar um **token** dinâmico em vez de **mobileToken**. Antes de configurar o SDK, você deve gerar um **token** temporário através de uma requisição server-to-server para a nossa API de Device Scan.
:::

```swift
import UIKit
import QITechIosDeviceScan

class ViewController: UIViewController {

    var qitechDeviceScan : QITechIosDeviceScan?

    override func viewDidLoad() {
        super.viewDidLoad()
        self.setupDeviceScan()
    }

    func setupDeviceScan() -> Void
    {
        // The environment can be 'sandbox' ou 'production'
        let environment = "sandbox"

        // MobileToken is the key sent to you by QI Tech. Each environment requires a different MobileToken.
        let token = "TEMPORARY_TOKEN_FROM_DEVICE_SCAN_API"

        // You must send the same session id in the moment of using the device scan and event analysis. It must be a key that uniquely identifies each user session in the app
        let sessionId = "62715840-068a-4ded-a4e2-a1ec83f857d4"

        do{
            self.qitechDeviceScan = try QITechIosDeviceScan(environment: environment, token: token, sessionId: sessionId)
        }
        catch{
            print ("Error found when instantiating QITech's DeviceScan")
        }

        let permissions = ["location"]

        do{
            try self.qitechDeviceScan?.requestPermissions(permissions: permissions)
        }
        catch{
            print ("Error found when requesting QITech's DeviceScan's permissions")
        }
    }

    func onSuccess()
    {
        // Do something if QI Tech DeviceScan's collectData method succesfully collected device data
    }

    func onError()
    {
        // Do something if QI Tech DeviceScan's collectData method found any error when collecting device data
    }

    func collectQITechDeviceScanData()
    {
        // If you have your customer's document number (CPF or CNPJ without dots, hyphen or slash), you must sent it to QI Tech
        let documentNumber = "12345678900"

        // EventType must represent with type of interation the user had with your app on the moment that collectData method was called
        let eventType = "login"

        // EventId is your code that identifies the event sent to QI Tech
        let eventId = "7038632032"

        do{
            try self.qitechDeviceScan?.collectData(documentNumber: documentNumber, eventId: eventId, eventType: eventType, onSuccessHandler: self.onSuccess, onErrorHandler: self.onError)
        }
        catch{
            print("Error found when collecting QITech's DeviceScan data")
        }
    }
}
```

Para utilizar o SDK do Device Scan iOS, os seguintes passos são necessários:

Inserir as autorizações no arquivo Info.plist
Adicionar o framework ao projeto do aplicativo
Ao iniciar a aplicação, instanciar a biblioteca, passando os parâmetros adequados
Caso sua aplicação ainda não tenha solicitado as permissões ao usuário, requisitar as permissões ao usuário por meio da função `requestPermissions` do objeto previamente instanciado
Coletar e enviar os dados por meio do método `collectData`

---

# Coleta de informações

URL: /documentation/caas/device_scan/ios/information_gathering

Para disparar a coleta e o envio de informações, é necessário chamar o método `collectData`. O método, além de capturar as informações do dispositivo, tem como objetivo mapear a jornada do cliente dentro da aplicação. É por esta razão que o método também aceita os campos `eventId` e `eventType`. Outro ponto importante é que o método envia as informações para o servidor da QI Tech via request http assíncrono, e para isso, a notificação de sucesso ou erro da requisição é feita através de Completion Handlers. O método possui os seguintes parâmetros:

nome | tipo | descrição
---- | ---- | ---------
documentNumber | String | O número do documento do usuário, caso disponível. (CPF/ CNPJ sem pontos, traços e barra)
eventId | String | Um identificador do evento sendo reportado
eventType | String | Um enumerador que define o tipo de evento sendo reportado (Exemplo: 'login') - Cuidado para que eventos muito similares sejam reportados com o mesmo enumerador, a fim de que inteligência possa ser construída sobre esses dados
onSuccessHandler | func() &#8209;> Void | Função que será chamada no caso de sucesso no envio dos dados para o servidor da QI Tech **obrigatório**
onErrorHandler | func() &#8209;> Void | Função que será chamada no caso de erro no envio dos dados para o servidor da QI Tech **obrigatório**

---

# Introdução

URL: /documentation/caas/device_scan/ios/introduction

Bem vindo ao manual de integração do Device Scan iOS da QI Tech! Você deve utilizar o nosso Framework para coletar informações do celular e do comportamento do usuário em seu aplicativo e assim melhorar a assertividade das decisões.

## Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso [suporte](mailto:suporte.caas@qitech.com.br) e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

### Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

## Ambientes

Possuímos dois ambientes para os nossos clientes. A seleção é realizada por meio de enumerador repassado no construtor da classe QITechIosDeviceScan, no momento, os seguintes ambientes estão disponíveis:

* Produção - `production`
* Sandbox - `sandbox`

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.  
:::

---

# Integração nativa

URL: /documentation/caas/device_scan/ios/native_swift

## Remotamente

> Iniciando a instalação

```shell
  pod init
```

Nosso SDK pode ser importado utilizando CocoaPods.

SDK | Versão atual
---- | -----
QITechIosDeviceScan | `pod 'QITechIosDeviceScan', '~> 6.0.0'`

:::info iOS Minimum Deployment Target
15.5
:::

Para iniciar a instalação, execute o comando ao lado na pasta raiz do seu projeto.

> Adicionando a source na podfile

```ruby
   source 'https://github.com/QITechSDKs/iOS.git'
```

O próximo passo é adicionar no arquivo `podfile` o source da QI Tech.

> Adicionando o pod na podfile

```ruby
  pod 'QITechIosDeviceScan', '~> <version>'
```
Por fim, basta adicionar o nome do `pod` de acordo com o formato acima.

:::danger Atenção: 
Mudança de Arquitetura (v5.0.0+) A partir da versão 5.0.0, o SDK passou a ser distribuída exclusivamente de forma estática. No seu Podfile, você deve utilizar a configuração :linkage => :static. 
:::

> Exemplo de podfile (Versão 5.0.0 ou superior)

```ruby
  source 'https://github.com/QITechSDKs/iOS.git'
  target 'ExampleApp' do
    use_frameworks! :linkage => :static
    pod 'QITechIosDeviceScan', '~> 6.0.0'
  end

  post_install do |installer|
    installer.pods_project.targets.each do |target|
      if ['DatadogCore', 'DatadogInternal', 'DatadogCrashReporting', 'DatadogLogs'].include?(target.name)
        target.build_configurations.each do |config|
          config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.5'
          config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
        end
      end
    end
  end
```

> Exemplo de podfile (Versões Anteriores)

```ruby
  source 'https://github.com/QITechSDKs/iOS.git'
  target 'ExampleApp' do
    use_frameworks!
    pod 'QITechIosDeviceScan', '~> 2.0.0'
  end

  post_install do |installer|
    installer.pods_project.targets.each do |target|
      if ['DatadogCore', 'DatadogInternal', 'DatadogCrashReporting', 'DatadogLogs'].include?(target.name)
        target.build_configurations.each do |config|
          config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.5'
          config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
        end
      end
    end
  end
```

:::info **Atenção**

É necessário habilitar a estabilidade do módulo para a dependência de monitoramento 'Datadog'. Para evitar possíveis problemas de compilação para diferentes versões do swift. Portanto, adicione o bloco descrito no post_install do seu arquivo Podfile (ou inclua-o no bloco post_install existente, caso já tenha um)
:::

:::warning Atenção
Ao integrar dependências no iOS, pode surgir a necessidade de usar linkagem estática para algumas bibliotecas e dinâmica para outras. Essa configuração é relevante para garantir compatibilidade, evitar erros de build e otimizar o desempenho do projeto. 
:::

### Linkagem Híbrida de Dependências (caso necessário)
A necessidade de linkagem híbrida surge porque algumas bibliotecas têm requisitos específicos, sendo que algumas precisam de linkagem estática para evitar conflitos internos e duplicação de símbolos e outras dependências podem precisar linkagem dinâmica, pois são projetadas para modularidade e compartilhamento entre projetos.

Diferenças Entre Linkagem Estática e Dinâmica
* Estática (static_framework): O código da biblioteca é incorporado diretamente no binário final, reduzindo o tempo de carregamento em runtime e eliminando dependências externas durante a execução.
* Dinâmica (dynamic_framework): A biblioteca é carregada em tempo de execução como um arquivo separado. Isso reduz o tamanho do binário final e facilita atualizações/modificações independentes.

> Configurando linkagem híbrida no Podfile

```ruby
...

use_frameworks! :linkage => :dynamic # CONFIGURANDO O MODO PADRÃO DE LINKAGEM PARA DINÂMICO

...

static_frameworks = ['framework_1', 'framework_2', ...] # INCLUIR TODAS AS DEPENDÊNCIAS QUE PRECISAM SER LINKADAS DE MODO ESTÁTICO
pre_install do |installer|
  installer.pod_targets.each do |pod|
    if static_frameworks.include?(pod.name)
      def pod.static_framework?;
        true
      end
      def pod.build_type;
        Pod::BuildType.static_framework
      end
    end
  end
end
```

> Instalando as dependencias

```shell
  pod install
```

Por fim, execute o comando `pod install` para baixar e instalar as dependências.

---

# Permissões

URL: /documentation/caas/device_scan/ios/permissions

A SDK coleta dados do dispositivo e, de acordo com o funcionamento do sistema operacional iOS, necessita de permissões específicas para cada dado a ser coletado. De maneira a oferecer uma experiência customizada para os usuários da aplicação que possua o SDK embarcado, implementamos um mecanismo que utiliza os parâmetros passados pelo desenvolvedor para solicitar as permissões ao usuário, seguindo a seguinte mecânica:

As permissões que forem enviadas como parâmetro do método `requestPermissions`, no formato de String, são solicitadas ao usuário - a menos que já tenham sido solicitadas anteriormente.
O usuário, por meio de uma caixa de diálogo disponibilizada pelo próprio sistema operacional, é questionado sobre as permissões consideradas necessárias pelo framework.
As permissões são então concedidas ou negadas e, no momento que o método `collectData`, este coletará apenas os dados cuja permissão foi concedida.

:::info **Atenção**

Caso seu aplicativo já tenha solicitado as permissões necessárias, não é necessário chamar novamente o método `requestPermissions`, o SDK irá herdar as permissões solicitadas pelo aplicativo.
:::

## Permissões utilizadas pelo SDK

Na versão atual do SDK, as seguintes permissões são utilizadas caso estejam disponíveis:

* location - Captura de dados de geolocalização do device

## Arquivo Info.plist

O primeiro passo para disponibilizar permissões para o SDK é configurar a permissão no arquivo Info.plist da aplicação, utilizando a seguinte linha de código para cada uma das permissões desejadas:

* location - Captura de dados de geolocalização do device:

` NSLocationWhenInUseUsageDescription `
` Adicionar a mensagem que você deseja que apareça para o usuário quando o iOS solicitar a permissão de acesso à geolocalização `

:::info **Atenção**

Para melhorar a experiência do usuário no momento da solicitação das permissões você deve personalizar a mensagem reproduzida no pop-up de solicitação conforme descrito anteriormente.
:::

---

# Compatibilidade

URL: /documentation/caas/device_scan/react_native/compatibility

O módulo `@qitech/react-native-device-scan` exige as seguintes versões mínimas:

| Configuração | Versão mínima |
|------------|--------------|
|React Native|0.74|
|React|18.2.0|
|iOS|15.5|
|Android API Level|35 (Android 15)|
|Datadog SDK nativo (iOS, trazido pelo módulo)|3.x|

## Versão atual do pacote

| Pacote | Versão |
|--------|--------|
|`@qitech/react-native-device-scan`|`1.2.0`|
|`@qitech/react-native-caas`|`11.3.0`|

:::warning Atenção
Nossos SDKs de iOS só suportam simuladores em máquinas com arquitetura **arm64** (M1/M2/M3/M4) com o **Rosetta** ativo, traduzindo a arquitetura x86_64. Recomendamos o uso de dispositivos físicos para testes.
:::

## Expo

O pacote inclui um _config plugin_ do Expo que aplica automaticamente as configurações nativas de iOS e Android. Veja [Instalação](/documentation/caas/device_scan/react_native/installation).

:::info **Atenção**
O módulo não funciona no _Expo managed workflow_ sem `prebuild` — é necessário gerar os projetos nativos com `npx expo prebuild`.
:::

---

# A função startDeviceScan

URL: /documentation/caas/device_scan/react_native/device_scan_object

## Chamada

Para utilizar o módulo de Device Scan, é necessário realizar a chamada da função `startDeviceScan`, que possui os seguintes parâmetros **posicionais**:

```javascript
await startDeviceScan(
  token,
  document_number,
  session_id,
  event_id,
  event_type,
  environment
);
```

| Parâmetro | Tipo | Função | Obrigatório |
|------------|--------------|--------------|--------------|
|token|string|Token de autenticação temporário obtido por meio de requisição server-to-server à API de Device Scan. Deve ser gerado com o mesmo `session_id` passado a esta função.|Sim.|
|document_number|string|O número do documento do usuário (CPF/CNPJ sem pontos, traços e barra).|Sim.|
|session_id|string|Chave que identifica a sessão da qual os dados coletados são provenientes. **Deve ser enviada em letras minúsculas.**|Sim.|
|event_id|string|Um identificador do evento sendo reportado.|Sim.|
|event_type|string|Um enumerador que define o tipo de evento sendo reportado (ex.: `'onboarding'`). É pedido cuidado para que eventos muito similares sejam reportados com o mesmo enumerador, a fim de que inteligência possa ser construída sobre esses dados.|Sim.|
|environment|CAAS_ENVIRONMENT|Enumerador utilizado para configurar o ambiente de execução para `SANDBOX` ou `PRODUCTION`.|Sim.|

:::warning Atenção
A ordem dos parâmetros importa. Note que `session_id` vem **antes** de `event_id` e `event_type` na assinatura da função, mesmo que internamente o módulo nativo receba os valores em outra ordem.
:::

## CAAS_ENVIRONMENT

```typescript
enum CAAS_ENVIRONMENT {
  PRODUCTION = 'production',
  SANDBOX = 'sandbox',
}
```

## Retorno

A função retorna uma `Promise` resolvida com uma string indicando o sucesso da coleta.

### Sucesso

```javascript
Success collecting device scan data
```

### Erro

A _Promise_ é rejeitada quando a coleta falha:

```javascript
There was an error collecting DeviceScan data
```

Quando o módulo nativo não está corretamente vinculado, a chamada lança:

```javascript
The package '@qitech/react-native-device-scan' doesn't seem to be linked. Make sure:

- You have run 'pod install'
- You rebuilt the app after installing the package
- You are not using Expo managed workflow
```

## Exemplo

```tsx
try {
  const result = await startDeviceScan(
    token,
    '<CPF_NUMBER>',
    '<SESSION_ID>',
    '1',
    'onboarding',
    CAAS_ENVIRONMENT.SANDBOX
  );

  console.log(result); // "Success collecting device scan data"
} catch (error) {
  console.log('Error executing device scan: ' + error);
}
```

## Utilizando o pacote completo

Se o seu aplicativo utiliza o `@qitech/react-native-caas`, a função `startDeviceScan` tem exatamente a mesma assinatura e o mesmo comportamento — apenas o caminho do `import` muda:

```javascript
import { CAAS_ENVIRONMENT, startDeviceScan } from '@qitech/react-native-caas';
```

---

# Implementação

URL: /documentation/caas/device_scan/react_native/example

## Pré-requisito: obtendo o token

A função `startDeviceScan` exige um `token`. Esse token é temporário e deve ser gerado no seu backend por meio de uma requisição server-to-server para a nossa API, antes de chamar a função do SDK.

### Endpoint

| Ambiente | URL |
|----------|-----|
| **Sandbox** | `https://d.sandbox.viewpkg.com/device_scan/token` |
| **Produção** | `https://d.viewpkg.com/device_scan/token` |

### Requisição

**Method:** `POST`

**Headers:**

```json
{
  "Authorization": "YOUR_DEVICE_SCAN_API_KEY"
}
```

**Body:**

```json
{
  "session_id": "unique_session_id"
}
```

### Resposta

A resposta bem-sucedida conterá o `token` que deve ser repassado à função `startDeviceScan`.

```json
{
  "token": "eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6..."
}
```

:::danger Aviso Importante!
A API Key de Device Scan nunca deve ser embarcada no aplicativo. A requisição acima deve partir exclusivamente do seu backend. O `session_id` usado para gerar o token deve ser **o mesmo** repassado à função `startDeviceScan`.
:::

:::note
O device scan pode ser executado de forma assíncrona. Portanto, não é necessário bloquear a interface para aguardar a resolução da _Promise_. O usuário pode interagir normalmente com o app enquanto o device scan é processado em segundo plano.
:::

:::note
Recomendamos que o device scan seja executado o mais cedo possível — por exemplo, dentro de um `useEffect`. Como ele pode precisar de mais tempo de execução para coletar todos os dados, essa chamada antecipada garante que as informações mais completas do dispositivo sejam extraídas.
:::

## Assinatura da função

```javascript
await startDeviceScan(
  token,            // string - token obtido na API
  document_number,  // string - CPF do usuário
  session_id,       // string - identificador da sessão
  event_id,         // string - identificador do evento
  event_type,       // string - tipo do evento (ex.: 'onboarding')
  environment       // CAAS_ENVIRONMENT.SANDBOX ou CAAS_ENVIRONMENT.PRODUCTION
);
```

Veja [A função startDeviceScan](/documentation/caas/device_scan/react_native/device_scan_object) para a descrição completa de cada parâmetro.

## Exemplo completo

```tsx
import * as React from 'react';
import { useCallback, useEffect } from 'react';
import { View, Button, Platform, PermissionsAndroid, Permission } from 'react-native';
import { request, PERMISSIONS, RESULTS } from 'react-native-permissions';
import { CAAS_ENVIRONMENT, startDeviceScan } from '@qitech/react-native-device-scan';

const DEVICE_SCAN_API_URL = 'https://d.sandbox.viewpkg.com/device_scan/token';
const DEVICE_SCAN_API_KEY = '<DEVICE_SCAN_API_KEY>';

const config = {
  environment: CAAS_ENVIRONMENT.SANDBOX,
  sessionId: '<SESSION_ID>',
  documentNumber: '<CPF_NUMBER>',
  deviceScanEventId: '1',
  deviceScanEventType: 'onboarding',
};

export default function App() {
  // Etapa 1: solicitar as permissões que ampliam a coleta
  const requestDeviceScanPermissions = async (): Promise<boolean> => {
    if (Platform.OS === 'ios') {
      const result = await request(PERMISSIONS.IOS.LOCATION_WHEN_IN_USE);
      return result === RESULTS.GRANTED;
    }

    const permissionsToRequest: Permission[] = [
      PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION,
      PermissionsAndroid.PERMISSIONS.ACCESS_COARSE_LOCATION,
      PermissionsAndroid.PERMISSIONS.READ_PHONE_STATE,
      PermissionsAndroid.PERMISSIONS.READ_CONTACTS,
    ];

    // BLUETOOTH_CONNECT só é necessária no Android 12+ (API 31+)
    if (Platform.Version >= 31) {
      permissionsToRequest.push('android.permission.BLUETOOTH_CONNECT' as Permission);
    }

    const results = await PermissionsAndroid.requestMultiple(permissionsToRequest);

    return (
      results[PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION] ===
        PermissionsAndroid.RESULTS.GRANTED ||
      results[PermissionsAndroid.PERMISSIONS.ACCESS_COARSE_LOCATION] ===
        PermissionsAndroid.RESULTS.GRANTED
    );
  };

  // Etapa 2: obter o token por meio do seu backend
  const fetchDeviceScanToken = useCallback(async () => {
    const response = await fetch(DEVICE_SCAN_API_URL, {
      method: 'POST',
      headers: {
        'Authorization': DEVICE_SCAN_API_KEY,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ session_id: config.sessionId }),
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }

    const data = await response.json();

    if (!data.token) {
      throw new Error("No 'token' found in response.");
    }

    return data.token;
  }, []);

  // Etapa 3: executar a coleta
  const captureDeviceScan = async (): Promise<void> => {
    try {
      const deviceScanToken = await fetchDeviceScanToken();

      const result = await startDeviceScan(
        deviceScanToken,
        config.documentNumber,
        config.sessionId,
        config.deviceScanEventId,
        config.deviceScanEventType,
        config.environment
      );

      console.log('Device Scan result: ' + String(result));
    } catch (error) {
      console.log('Error executing device scan: ' + error);
    }
  };

  useEffect(() => {
    const init = async () => {
      await requestDeviceScanPermissions();
      await captureDeviceScan();
    };
    init();
  }, []);

  return (
    <View>
      <Button title="Executar Device Scan" onPress={captureDeviceScan} />
    </View>
  );
}
```

## Boas práticas

* Execute o device scan **o mais cedo possível** (por exemplo, em um `useEffect`) — ele precisa de tempo para coletar os dados completos do dispositivo.
* O device scan é **assíncrono** e não bloqueia a interface. Não é necessário aguardar a resolução da _Promise_ para prosseguir com os demais fluxos.
* Solicite as permissões **antes** de chamar `startDeviceScan`. O SDK não solicita permissões por conta própria — ele apenas coleta o que já foi concedido.

## Aplicativos de exemplo

O repositório do módulo contém dois aplicativos prontos para execução, na pasta `examples`:

* **QITechReactNativeExample** — React Native puro
* **QITechExpoExample** — Expo

Em ambos, o arquivo `App_ds.tsx` demonstra o uso do Scan de dispositivo com o `@qitech/react-native-device-scan`. Substitua as API Keys de exemplo pelas suas credenciais. Caso ainda não as tenha recebido, entre em contato com o suporte.caas@qitech.com.br .

---

# Instalação

URL: /documentation/caas/device_scan/react_native/installation

## Instalando o pacote

### 1. Configurando o registro npm

Crie um arquivo `.npmrc` na raiz do seu projeto:

```sh
@qitech:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=NPM_TOKEN_SENT_BY_QI_TECH
```

Substitua `NPM_TOKEN_SENT_BY_QI_TECH` pelo token fornecido pelo suporte. Caso ainda não tenha recebido o seu token, entre em contato com o suporte.caas@qitech.com.br .

### 2. Instalando a dependência

```sh
yarn add @qitech/react-native-device-scan
```

### 3. Importação

```javascript
import {
  CAAS_ENVIRONMENT,
  startDeviceScan,
} from '@qitech/react-native-device-scan';
```

## Configuração do Android

### 1. Repositório Maven da QI Tech

Adicione o repositório Maven da QI Tech ao `build.gradle` do projeto:

```groovy
allprojects {
  repositories {
    maven { url 'https://sdks.qitech.com.br/' }
    ...
  }
}
```

### 2. AdMob

Inicialize o serviço de AdMob adicionando o seguinte código ao `AndroidManifest.xml`:

```xml
<meta-data
  android:name="com.google.android.gms.ads.APPLICATION_ID"
  android:value="<ADMOB_APP_ID>"/>
```

Caso não possua um `ADMOB_APP_ID`, entre em contato com o suporte.caas@qitech.com.br .

### 3. Permissões

Declare no `AndroidManifest.xml` as permissões que deseja disponibilizar ao SDK. Veja [Permissões](/documentation/caas/device_scan/react_native/permissions) para a lista completa.

## Configuração do iOS

### 1. Source do repositório iOS da QI Tech

Adicione as seguintes sources no topo do seu `Podfile`:

```ruby
source 'https://cdn.cocoapods.org/'
source 'https://github.com/QITechSDKs/iOS.git'
```

### 2. Frameworks estáticos

Necessário **apenas** se você utiliza o Xcode **anterior à versão 26**:

```ruby
use_frameworks! :linkage => :static
```

:::warning Atenção
O [Flipper](https://fbflipper.com/docs/getting-started/react-native/) não funciona com `use_frameworks!`. Remova a chamada `use_flipper()` do seu `Podfile` caso ela esteja presente.
:::

### 3. Estabilidade de módulo

As dependências do Datadog exigem que o `BUILD_LIBRARY_FOR_DISTRIBUTION` esteja habilitado. Adicione o `post_install` abaixo (ou incorpore ao seu `post_install` existente):

```ruby
post_install do |installer|
  installer.pods_project.targets.each do |target|
    if ['DatadogCore', 'DatadogInternal', 'DatadogCrashReporting', 'DatadogLogs'].include?(target.name)
      target.build_configurations.each do |config|
        config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.5'
        config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
      end
    end
  end
end
```

### 4. Permissões

Declare no `Info.plist` as permissões que deseja disponibilizar ao SDK. Veja [Permissões](/documentation/caas/device_scan/react_native/permissions).

### 5. Instalação dos pods

```sh
cd ios && pod install
```

## Configuração do Expo

O pacote inclui um _config plugin_ do Expo que aplica automaticamente todas as configurações nativas de iOS e Android descritas acima. No seu `app.json`:

```json
{
  "expo": {
    "plugins": ["@qitech/react-native-device-scan"]
  }
}
```

Em seguida, execute o `prebuild` para aplicar as alterações nativas:

```sh
npx expo prebuild
```

---

# Introdução

URL: /documentation/caas/device_scan/react_native/introduction

Bem vindo ao manual de integração do Device Scan da QI Tech em React Native! O módulo `@qitech/react-native-device-scan` expõe, por meio de uma interface TypeScript, os SDKs nativos de Android (Java/Kotlin) e iOS (Swift) da QI Tech. Você deve utilizá-lo para coletar informações do celular e do comportamento do usuário em seu aplicativo e assim melhorar a assertividade das decisões.

## Pacotes disponíveis

| Pacote | Conteúdo | Quando usar |
|--------|----------|-------------|
|`@qitech/react-native-device-scan`|Somente Scan de dispositivo|Quando você precisa **apenas** de scan de dispositivo — instalação mais leve, com menos dependências nativas.|
|`@qitech/react-native-caas`|Reconhecimento facial, OCR e Scan de dispositivo|Quando você também precisa de reconhecimento facial ou OCR.|

:::danger Aviso Importante!
Ambos os pacotes incluem o Scan de dispositivo e expõem a mesma função `startDeviceScan`, com a mesma assinatura. **Não instale os dois** — escolha apenas um.
:::

Esta seção documenta o `@qitech/react-native-device-scan`. Se o seu aplicativo já utiliza o `@qitech/react-native-caas`, basta trocar o caminho do `import` — todo o restante desta documentação se aplica sem alterações.

## Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso [suporte](mailto:suporte.caas@qitech.com.br) e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

### Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

## Ambientes

Possuímos dois ambientes para os nossos clientes. A seleção é realizada por meio do enumerador `CAAS_ENVIRONMENT`, repassado como último parâmetro da função `startDeviceScan`. No momento, os seguintes ambientes estão disponíveis:

* Produção - `CAAS_ENVIRONMENT.PRODUCTION`
* Sandbox - `CAAS_ENVIRONMENT.SANDBOX`

Cada ambiente exige uma API Key diferente para a geração do token.

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.
:::

## Próximos passos

1. [Compatibilidade](/documentation/caas/device_scan/react_native/compatibility) — versões mínimas de React Native, iOS e Android.
2. [Instalação](/documentation/caas/device_scan/react_native/installation) — instalação do pacote e configuração nativa de Android, iOS e Expo.
3. [Implementação](/documentation/caas/device_scan/react_native/example) — obtenção do token e exemplo completo da chamada `startDeviceScan`.
4. [A função startDeviceScan](/documentation/caas/device_scan/react_native/device_scan_object) — parâmetros e retorno.
5. [Permissões](/documentation/caas/device_scan/react_native/permissions) — permissões que ampliam a coleta de dados.

---

# Permissões

URL: /documentation/caas/device_scan/react_native/permissions

O módulo coleta dados do dispositivo do usuário conforme as permissões que estão disponíveis no momento da coleta: conforme mais permissões seu aplicativo requerir e o usuário disponibilizar, mais informações são coletadas do dispositivo do usuário.

:::info **Atenção**

A permissão de INTERNET é obrigatória para que o SDK consiga enviar as informações aos servidores da QI Tech.
:::

:::info **Importante**

Nosso módulo não solicita as permissões descritas. Portanto, para garantir um scan de dispositivo mais completo, recomendamos a coleta dessas permissões antes de executar a chamada de `startDeviceScan`.
:::

## Android

Para a plataforma Android, as seguintes permissões são utilizadas caso estejam disponíveis:

| Permissão | Função | Obrigatória |
|------------|--------------|--------------|
|INTERNET|Obrigatória, para envio das informações aos servidores da QI Tech.| Sim. |
|BLUETOOTH|Captura de informações do hardware de Bluetooth.| Não. |
|BLUETOOTH_CONNECT|Captura de informações de conexão Bluetooth. Necessária a partir do Android 12 (API 31).| Não. |
|READ_CONTACTS|Leitura da agenda de contatos.| Não. |
|ACCESS_COARSE_LOCATION|Acesso a informações de rede (Antena, operadora...) e à localização por este meio (Menos preciso).| Não. |
|ACCESS_FINE_LOCATION|Acesso à localização por meio de GPS (Mais preciso).| Não. |
|READ_PHONE_STATE|Informações de Rede, SIM, Imei e outros aspectos de telefonia.| Não. |
|QUERY_ALL_PACKAGES|Informações de aplicativos instalados no dispositivo. Necessária para devices Android 11 em diante.| Não. |

:::info **Atenção**

A permissão de QUERY_ALL_PACKAGES pode gerar atrito com o Google Play no momento do lançamento do App. Para solucioná-lo é possível descrever o motivo da solicitação da permissão.
:::

### Solicitando as permissões

```tsx
import { Platform, PermissionsAndroid, Permission } from 'react-native';

const permissionsToRequest: Permission[] = [
  PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION,
  PermissionsAndroid.PERMISSIONS.ACCESS_COARSE_LOCATION,
  PermissionsAndroid.PERMISSIONS.READ_PHONE_STATE,
  PermissionsAndroid.PERMISSIONS.READ_CONTACTS,
];

// BLUETOOTH_CONNECT só é necessária no Android 12+ (API 31+)
if (Platform.Version >= 31) {
  permissionsToRequest.push('android.permission.BLUETOOTH_CONNECT' as Permission);
}

const results = await PermissionsAndroid.requestMultiple(permissionsToRequest);
```

## iOS

Para a plataforma iOS, a seguinte permissão é utilizada caso esteja disponível:

* location - Captura de dados de geolocalização do device

### Arquivo Info.plist

O primeiro passo para disponibilizar permissões para o módulo é configurar a permissão no arquivo `Info.plist` da aplicação:

```xml
<key>NSLocationWhenInUseUsageDescription</key>
<string>Adicionar a mensagem que você deseja que apareça para o usuário quando o iOS solicitar a permissão de acesso à geolocalização</string>
```

:::info **Atenção**

Para melhorar a experiência do usuário no momento da solicitação das permissões você deve personalizar a mensagem reproduzida no pop-up de solicitação conforme descrito anteriormente.
:::

### Solicitando as permissões

```tsx
import { request, PERMISSIONS, RESULTS } from 'react-native-permissions';

const result = await request(PERMISSIONS.IOS.LOCATION_WHEN_IN_USE);

if (result === RESULTS.GRANTED) {
  // permissão concedida
}
```

## Coleta de informações

Para a lista completa das informações coletadas em cada plataforma, consulte as páginas de coleta dos SDKs nativos:

* [Coleta de informações — Android](/documentation/caas/device_scan/android/information_gathering)
* [Coleta de informações — iOS](/documentation/caas/device_scan/ios/information_gathering)

---

# Desktop Device Scan

URL: /documentation/caas/device_scan/web/desktop

Este é o **Desktop Device Scan**, nosso módulo *white label* complementar à **Web Device Scan**. Você pode utilizar nosso programa para coletar informações profundas do dispositivo, além de identificar a presença de softwares maliciosos!

Este software foi desenvolvido para atender à [Instrução Normativa BCB nº 491](https://www.bcb.gov.br/estabilidadefinanceira/exibenormativo?tipo=Instru%C3%A7%C3%A3o%20Normativa%20BCB&numero=491). Ele, em conjunto com a Web Device Scan, é capaz de gerar uma **identificação única e confiável** para cada dispositivo!

:::warning Atenção
Nosso aplicativo é *White Label*! Você pode utilizar seus próprios logotipos no instalador, além de personalizar o nome do executável e as mensagens exibidas, deixando a experiência mais amigável para o seu usuário.
:::

## Utilização

Neste passo a passo, você encontrará detalhes sobre a utilização do programa em conjunto com a biblioteca, bem como um exemplo de implementação em JavaScript. Com isso, você terá as ferramentas necessárias para adaptar a solução ao seu caso de uso.

```html
<html>
<head>
    <script src="https://ds.viewpkg.com/device-scan-2-1-1.js"></script>
</head>

<script>
    var deviceScan = new vPkg.DeviceScan('web_token', 'session_id')
    deviceScan.setSandbox()
    deviceScan.setDesktop(true)
    deviceScan.info('event_type', 'event_id')
        .then((res) => console.log(res))
        .catch((error) => console.log(error))
</script>
</html>
```

Ao utilizar a flag `deviceScan.setDesktop(true)`, o SDK web tentará identificar a presença do aplicativo instalado. Caso ele não esteja instalado ou apresente problemas, você poderá receber um dos seguintes erros:

| Erro                        | Descrição                                                                                                                                                                                         |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Timeout in Secure App**   | O aplicativo está presente, mas não está respondendo corretamente. Reinstale o aplicativo para corrigir o problema.                                                                               |
| **Invalid desktop data**    | O aplicativo foi modificado ou corrompido. Reinstale o aplicativo para restaurar a integridade.                                                                                                   |
| **Desktop App Not Present** | O aplicativo não está instalado. Ofereça o link de download fornecido pela QI Tech ao usuário.                                                                                                    |
| **Unexpected App Error**    | Um erro inesperado ocorreu na comunicação com o aplicativo. Se o problema persistir após a reinstalação, entre em contato com o suporte: <a href='mailto:suporte.caas@qitech.com.br'>suporte</a>. |

## Sistemas Operacionais Suportados

O **Desktop Device Scan** está disponível para os principais sistemas operacionais modernos, oferecendo compatibilidade nativa e desempenho otimizado em cada plataforma.

Windows 10/11 x64
macOS Intel (x86_64)
macOS Apple Silicon (M1/M2/M3)

---

# O objeto DeviceScan

URL: /documentation/caas/device_scan/web/device_scan_object

Para utilizar serviço de scan de dispositivo, é necessário instanciar a classe DeviceScan que possui os seguintes parâmetros no construtor:

| Parâmetro | Função | Obrigatório |
|------------|--------------|--------------|
|.setSandbox()|Caso este parâmetro seja utilizado no construtor, a biblioteca será configurada para enviar os dados ao ambiente de `sandbox`. Caso ausente, as requisições são enviadas para o ambiente `production`. |Não.|
|.setGeoLocation(true)|Caso este parâmetro seja definido como `true`, a biblioteca irá solicitar a permissão de coleta dos dados de GPS. Caso ausente ou definido como `false`, as informações de geo localização não são extraídas.|Não.|

:::info **Atenção**
Se o usuário negar o acesso aos dados de localização, a biblioteca será executada normalmente, mas sem coletar essas informações.
:::

## A função deviceScan.info()

Para executar a função de análise de dados do seu usuário, é necessário enviar os seguintes parâmetros para a biblioteca que identificarão sua empresa e a sessão de usuário a qual as informações pertencem. Além disso, os argumentos event_id e event_type, apesar de serem opcionais, nos auxiliam a indenfiticar o padrão de navegação do usuário em sua página, e com isso, evitar ainda mais fraudes.

Abaixo temos o detalhamento de cada um dos argumentos:

Nome | Tipo | Descrição
---- | ---- | ---------
web_token | String | Chave do cliente que identifica que os dados coletados são provenientes do seu aplicativo. Caso ainda não tenha recebido o seu web-token, entre em contato com o suporte . **obrigatório**
session_id | String | Chave que identifica a sessão da qual os dados coletados são provenientes. **obrigatório**
event_id | String | Um identificador do evento sendo reportado
event_type | String | Um enumerador que define o tipo de evento sendo reportado - É pedido cuidado para que eventos muito similares seja reportados com o mesmo enumerador, a fim de que inteligência possa ser construída sobre esses dados.

## Exemplo de Implementação
Um exemplo simples de implementação pode ser visto abaixo:

```html
   html>
    <head>
        <script src="https://ds.viewpkg.com/device-scan-2-1-1.js"></script>
    </head>

    <script>
        var deviceScan = new vPkg.DeviceScan('web_token', 'session_id')
        deviceScan.setSandbox()
        deviceScan.setGeoLocation(true)
        async function callDeviceScan(eventType, eventId) {
            await deviceScan.info(eventType, eventId)
            .then((res) => console.log(res))
            .catch((error) => console.log(error))
        }
    </script>

    <body>
        <input id="login" type="button" value="login" onclick="callDeviceScan('login', '1');" />
        <input id="buy" type="button" value="buy" onclick="callDeviceScan('buy', '2');" />
    </body> 
</html>
```

No exemplo acima, foi criada uma função de suporte **callDeviceScan** para poder atribuir o uso do Device Scan ao clique de um botão e a função de coleta de dados pode ser chamada duas vezes:

* A primeira quando o usuário pressionar o botão de login, e as características e comportamentos do usuário até este evento serão enviadas para os servidores da QI Tech com os identificadores web_token, session_id, event_type ("login") e event_id ("1").

* A segunda quando o usuário pressionar o botão de compra, coletando os comportamentos do usuário utilizando os mesmos identificadores web_token (referente a sua empresa) e session_id (referente a sessão do seu usuário) mas um event_type ("buy") e event_id("2") distintos, indicando que um evento diferente do anterior foi realizado neste passo, mapeando assim toda a jornada do usuário pelo seu website.

---

# Implementação

URL: /documentation/caas/device_scan/web/example

```html
   <html>
    <head>
        <script src="https://ds.viewpkg.com/device-scan-2-1-1.js"></script>
    </head>

    <script>
        var deviceScan = new vPkg.DeviceScan('web_token', 'session_id')
        deviceScan.setSandbox()
        deviceScan.setGeoLocation(true)
        deviceScan.info('event_type', 'event_id')
            .then((res) => console.log(res))
            .catch((error) => console.log(error))
    </script>
   </html>
```

A biblioteca realiza uma análise do usuário através de uma chamada da função **.info()**, que pertence a classe **DeviceScan**, que está contida em nossa biblioteca **vPkg**, conforme o exemplo acima. As variávies 'web_token', 'session_id', 'event_type' (**opcional**) e 'event_id' (**opcional**) devem ser substituídas pelos **seus respectivos valores reais**. Em caso de sucesso a biblioteca irá retornar uma String indicando o sucesso da coleta, e em caso de falha irá retornar uma String indicando o tipo do erro.

---

# Importando a biblioteca

URL: /documentation/caas/device_scan/web/import

Para importar a nossa biblioteca, adicione a URL em uma TAG **src** no HTML de seu website:

```html
    <script src = "https://ds.viewpkg.com/device-scan-2-1-1.js"></script>
```

---

# Coletando os Retornos

URL: /documentation/caas/device_scan/web/information_gathering

A Web Device Scan SDK devolve uma _Promise_, que irá retornar uma **String** indicando a finalização do fluxo para os casos de sucesso. 
Já em casos de erro, irá retornar uma **String** com a descrição do erro. Abaixo está um exemplo de como mapear cada um desses casos e pegar seus resultados:

```html
    <script>
        var deviceScan = new vPkg.DeviceScan('web_token', 'session_id')
        deviceScan.setSandbox()
        deviceScan.setGeoLocation(true)
        deviceScan.info('event_type', 'event_id')
            .then((res) => console.log(res))
            .catch((error) => console.log(error))
    </script>
```

### Retorno de Sucesso

Retorno | Descrição
--------- | ---------
Device Scan Successfully Sent | O escaneamento do dispositivo foi realizado com sucesso, assim como o envio das informações extraídas.

### Retorno de Erro

Erro | Descrição
--------- | ---------
Web Token Error | Web Token utilizado é inválido. Caso tenha certeza que esteja utilizando corretamente o Web Token que foi provido pela QI Tech, entre em contato com nosso suporte (suporte.caas@qitech.com.br) imediatamente.
Invalid Request | Informações do dispositivo não foram coletadas da maneira correta.
Internal Server Error | Ocorreu um erro inesperado, checar conexão com internet.

---

# Introdução

URL: /documentation/caas/device_scan/web/introduction

Bem vindo ao manual de integração do Web Device Scan da QI Tech! Você pode utilizar a nossa biblioteca para coletar informações do dispositivo, do navegador e do comportamento do usuário em seu website e assim melhorar a assertividade das decisões.

Neste passo a passo você encontrará detalhes da biblioteca bem como um exemplo de implementação em javascript. Com isso você possui as ferramentas para poder adequar ao caso de uso da sua aplicação.

## Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso suporte e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

### Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

## Ambientes

Possuímos dois ambientes para os nossos clientes. A seleção é realizada por meio de enumerador repassado no construtor do SDK, no momento, os seguintes ambientes estão disponíveis:

* Produção - `production`
* Sandbox - `sandbox`

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.  
:::

---

# Enviando um documento

URL: /documentation/caas/document_analysis/document_submission

## **Enviando um Documento para uma análise padrão**

Para iniciar a análise de um documento, envie uma requisição POST para o endpoint `/document` utilizando o formato `multipart/form-data`.

Endpoint: `https://api.caas.qitech.app/document_analysis/document`

**Formato da Requisição**

A requisição deve ser enviada como `multipart/form-data` e incluir campos de dados e um campo de arquivo. Os campos obrigatórios para uma análise são `id`, `document_analysis_type`, `document_bytes`.

Exemplo de requisição:

``` bash
curl -X POST "https://api.caas.qitech.app/document_analysis/document" \
-H "Authorization: SUA_CHAVE_API" \
-H "Content-Type: multipart/form-data" \
-F "id=solicitacao-abc-12345" \
-F "document_analysis_type=proof_of_address_default" \
-F "document_bytes=@/caminho/para/seu/comprovante.pdf"
```

## **Descrição dos Atributos de Envio**

| **Atributo** | **Descrição** |
| --- | --- |
| id (obrigatório)| Um identificador único para a requisição, fornecido por você. Este ID pode ser usado posteriormente para recuperar os resultados da análise. |
| document_analysis_type (obrigatório)| Uma string que especifica o tipo de análise a ser realizada no documento. Veja a tabela abaixo para os tipos suportados. |
| document_bytes (obrigatório)| O arquivo do documento a ser analisado. Deve ser enviado como um arquivo no corpo da requisição multipart. Atenção: Não envie este campo como uma string codificada em base64.|
| async (opcional, default=false)| Um booleano (true ou false) que define o modo de processamento. <br/>- false (síncrono): A API tentará processar o documento e retornar o resultado na mesma requisição. <br/>- true (assíncrono): A API confirmará o recebimento e processará em segundo plano. O resultado será enviado via webhook para um url configurado previamente (veja mais na sessão sobre webhooks). |

:::info **Atenção**

O campo async deve ser utilizado para indicar uma requisição assíncrona. As requisições síncronas devem ser feitas apenas para documentos pequenos e análises rápidas em que uma resposta imediata é crucial. Caso a análise não termine dentro do tempo limite da requisição síncrona, o status de retorno será `202 Accepted` e o resultado deve ser recuperado por uma requisição GET, conforme descrito abaixo . Nesse caso nenhum webhook é enviado: o webhook é exclusivo das análises assíncronas.
:::

## **Tipos de Análise Suportadas**

O campo `document_analysis_type` determina qual modelo de extração de dados será aplicado ao seu documento. Abaixo estão os tipos atualmente suportados.

| **Tipo de Análise** | Tipo de Documento | **Descrição** |
| --- | --- | --- |
| `proof_of_address_default` | Comprovantes de residência (contas de luz, gás, internet, cartas do governo, declarações) | Extrai e valida nome, endereço estruturado, endereço bruto, data de emissão e tipo de documento. |
| `company_statute_default` | Contrato ou estatuto social | Extração e validação básica: dados da empresa, capital social, órgão de registro e quadro societário. |
| `company_statute_credit_right_assignment` | Contrato ou estatuto social | Extração avançada com validação de poderes para assinar cessão de direitos creditórios: grupos de assinantes, limites financeiros e necessidade de revisão. |
| `power_of_attorney_default` | Procuração | Extrai outorgantes, outorgados, poderes concedidos, escopo, validade, irrevogabilidade e dados do tabelionato. |
| `invoice_default` | Notas fiscais e DANFEs | Extrai emissor, tomador, tipo e tributação da nota, número, datas, itens e valores. |
| `bankslip_default` | Boletos bancários | Extrai beneficiário, CNPJ do beneficiário, código de barras, valor e data de vencimento. |
| `ccb_default` | Cédulas de Crédito Bancário (CCB) | Extrai número do contrato, dados do emissor, garantias, valor financiado, taxa de juros, parcelas e vencimentos. |
| `portability_retention_evidence_analysis` | Evidências de retenção de portabilidade | Valida a evidência: número do contrato, documento e telefone do emissor, número da portabilidade, presença de assinatura e se é uma confirmação válida. |

Expanda cada tipo abaixo para ver os campos que a análise devolve em `analysis_result`, com o tipo e o significado de cada um. Campos aninhados aparecem com o caminho completo (`address.street`) e listas são marcadas com `[]`.

**proof_of_address_default — campos retornados em `analysis_result`**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `name` | `string` | Nome completo do titular, conforme extraído do documento |
| `address` | `object` | Endereço residencial estruturado. Informação não encontrada vem como string vazia |
| `address.street` | `string` | Nome da rua |
| `address.number` | `string` | Número do imóvel |
| `address.complement` | `string` | Complemento, como apartamento, sala ou andar, quando houver |
| `address.neighborhood` | `string` | Bairro |
| `address.city` | `string` | Cidade |
| `address.state` | `string` | Estado ou Distrito Federal |
| `address.cep` | `string` | CEP |
| `raw_address` | `string` | Endereço residencial completo, em texto corrido |
| `issue_date` | `string` | Data de emissão do documento no formato AAAA-MM-DD |
| `document_type` | enum: `utility_bill`, `bank_statement`, `address_declaration`, `rental_agreement`, `government_letter` … | Tipo de documento enviado (ex.: 'utility_bill', 'address_declaration') |

**company_statute_default — campos retornados em `analysis_result`**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `company_name_official` | `string` | Razão social completa da empresa |
| `company_name_trade` | `string` | Nome fantasia |
| `cnpj` | `string` | CNPJ no formato XX.XXX.XXX/XXXX-XX |
| `nire` | `string` | NIRE — Número de Identificação do Registro de Empresas |
| `headquarters_address_full` | `string` | Endereço completo da sede |
| `incorporation_date` | `string` | Data de constituição da empresa |
| `last_consolidated_amendment_date` | `string` | Data da última alteração consolidada |
| `corporate_purpose_summary` | `string` | Objeto social principal |
| `share_capital_value` | `number` | Valor TOTAL do capital social |
| `share_capital_currency` | `string` | Moeda do capital social (ex.: 'BRL') |
| `registration_office_name` | `string` | Nome do órgão de registro (ex.: JUCESP) |
| `registration_office_number` | `string` | Número de registro no órgão competente |
| `registration_office_date` | `string` | Data do registro ou arquivamento no órgão competente |
| `requires_power_of_attorney_check` | `boolean` | Verdadeiro quando os poderes de assinatura não estão claros ou há menção a procuração, indicando necessidade de verificar um documento adicional |
| `partners_data[]` | `object` | Dados de um único sócio extraídos do contrato social |
| `partners_data[].name` | `string` | Nome completo do sócio |
| `partners_data[].cpf` | `string` | CPF do sócio no formato XXX.XXX.XXX-XX |
| `partners_data[].is_administrator` | `boolean` | Verdadeiro quando o sócio é nomeado administrador de forma explícita |
| `partners_data[].role_powers` | `string` | Cargo ou poderes, APENAS quando o sócio é administrador |
| `partners_data[].share_quantity` | `integer` | Quantidade de ações ou quotas detidas pelo sócio |
| `partners_data[].share_value` | `number` | Valor total em BRL das ações ou quotas |
| `partners_data[].participation_percentage` | `number` | Percentual de participação do sócio na empresa |
| `clauses_of_interest` | `object` | Cláusulas de interesse extraídas do documento |
| `clauses_of_interest.administration_clause_summary` | `string` | Resumo da cláusula que define quem representa e assina pela empresa |

**company_statute_credit_right_assignment — campos retornados em `analysis_result`**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `requires_review` | `boolean` | Indica se o documento é complexo, se inclui muitas cláusulas ou subcláusulas sobre a administração ou se requer outros documentos em conjunto (como atlas de assembleia ou de eleição). |
| `company_data` | `object` | Dados cadastrais e societários completos da entidade analisada. |
| `company_data.company_name_official` | `string` | Nome Oficial Completo da Empresa |
| `company_data.company_name_trade` | `string` | Nome Fantasia |
| `company_data.cnpj` | `string` | CNPJ (CNPJ/MF) no formato XX.XXX.XXX/XXXX-XX |
| `company_data.nire` | `string` | Número de Identificação do Registro de Empresas |
| `company_data.headquarters_address_full` | `string` | Endereço completo da sede |
| `company_data.incorporation_date` | `string` | Data de constituição/formação da empresa |
| `company_data.last_consolidated_amendment_date` | `string` | Data deste contrato social ou alteração |
| `company_data.corporate_purpose_summary` | `string` | Objeto social principal |
| `company_data.share_capital_value` | `number` | Valor TOTAL do Capital Social |
| `company_data.share_capital_currency` | `string` | Moeda do capital social (ex: 'BRL') |
| `company_data.registration_office_name` | `string` | Nome do órgão de registro (ex: JUCESP) |
| `company_data.partners_data[]` | `object` | Modelo que representa os dados de um único sócio extraídos do Contrato Social. |
| `company_data.partners_data[].name` | `string` | Nome completo do sócio |
| `company_data.partners_data[].cpf` | `string` | CPF do sócio no formato XXX.XXX.XXX-XX |
| `company_data.partners_data[].cnpj` | `string` | CNPJ (CNPJ/MF) da empresa sócio (caso sócio seja uma pessoa jurídica) no formato XX.XXX.XXX/XXXX-XX |
| `company_data.partners_data[].is_representative` | `boolean` | Verdadeiro se o sócio pode representar a empresa. |
| `company_data.partners_data[].role_powers` | enum: `president`, `partner`, `administrator`, `director`, `manager` … | Cargo ou poderes. Use 'other' caso se refira a uma empresa, organização ou similar. |
| `company_data.partners_data[].share_quantity` | `integer` | Número de ações/quotas detidas pelo sócio |
| `company_data.partners_data[].share_value` | `number` | Valor total das ações/quotas |
| `company_data.partners_data[].participation_percentage` | `number` | Percentual de participação do sócio na empresa |
| `analyzed_operation` | `string` | O ato ou negócio jurídico específico cuja representação está sendo analisada. |
| `source_documents[]` | `string` | Lista de documentos societários que fundamentam a análise (ex: 'Estatuto Social', 'Ata de Eleição'). |
| `allows_proxies` | `boolean` | Indica se o estatuto da entidade permite a representação por meio de procuradores. |
| `signer_groups[]` | `object` | Define os diferentes grupos e regras de assinatura válidos para a entidade. |
| `signer_groups[].group_id` | `integer` | Um identificador numérico único para o grupo de assinatura. |
| `signer_groups[].description` | `string` | Um resumo claro da regra de negócio que este grupo representa. |
| `signer_groups[].source_clause` | `string` | O texto completo da cláusula ou artigo que estabelece esta regra. |
| `signer_groups[].representation_type` | enum: `Conjunta`, `Individual`, `Conforme Mandato` | Descreve se a representação é feita de forma conjunta ou individual. Caso ambas sejam permitidas, use individual. |
| `signer_groups[].minimum_signers` | `integer` | O número mínimo de membros deste grupo que devem assinar. Se a assinatura for conjunta, esse valor deve ser maior que 1 |
| `signer_groups[].limitations` | `object` | Define as condições e restrições aplicáveis a esta regra de assinatura. |
| `signer_groups[].limitations.financial_limit` | `object` | Define a alçada financeira da regra de forma estruturada. |
| `signer_groups[].limitations.financial_limit.operator` | enum: `MENOR_IGUAL`, `MAIOR_QUE`, `MAIOR`, `MENOR`, `IGUAL` … | O operador de comparação para o limite financeiro. |
| `signer_groups[].limitations.financial_limit.value` | `number` | O valor monetário da alçada. |
| `signer_groups[].limitations.financial_limit.currency` | `string` | O código da moeda do valor (ex: BRL, USD). |
| `signer_groups[].limitations.observations` | `string` | Notas ou comentários adicionais sobre a interpretação ou aplicação da regra. |
| `signer_groups[].members[]` | `object` | Define os cargos que podem compor o grupo de assinatura. |
| `signer_groups[].members[].position` | enum: `president`, `partner`, `administrator`, `director`, `manager` … | Cargo ou poderes. Use 'other' caso se refira a uma empresa, organização ou similar. |
| `signer_groups[].members[].full_name` | `string` | O nome completo do indivíduo que ocupa o cargo, se identificado. |
| `signer_groups[].members[].cpf` | `string` | O CPF do indivíduo (Cadastro de Pessoa Física), se disponível. |
| `signer_groups[].members[].mandate_end_date` | `string` | A data de expiração do mandato (ex: 'AAAA-MM-DD'). |
| `signer_groups[].members[].is_qualified` | `boolean` | Indica se a pessoa que ocupa o cargo está identificada no documento. |
| `signer_groups[].members[].is_required` | `boolean` | Indica se a presença deste membro é obrigatória. |

**power_of_attorney_default — campos retornados em `analysis_result`**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `grantors[]` | `object` | Lista de outorgantes — ao menos um é obrigatório |
| `grantors[].name` | `string` | Nome completo do outorgante |
| `grantors[].cpf` | `string` | CPF do outorgante no formato XXX.XXX.XXX-XX (pessoa física) |
| `grantors[].cnpj` | `string` | CNPJ do outorgante no formato XX.XXX.XXX/XXXX-XX (pessoa jurídica) |
| `grantees[]` | `object` | Lista de outorgados — ao menos um é obrigatório |
| `grantees[].name` | `string` | Nome completo do outorgado |
| `grantees[].cpf` | `string` | CPF do outorgado no formato XXX.XXX.XXX-XX (pessoa física) |
| `grantees[].cnpj` | `string` | CNPJ do outorgado no formato XX.XXX.XXX/XXXX-XX (pessoa jurídica) |
| `powers_granted` | `string` | Descrição dos poderes concedidos pela procuração |
| `power_scope` | `string` | Escopo ou limitações dos poderes concedidos, quando especificados |
| `expiration_date` | `string` | Data em que os poderes expiram; nulo indica validade indeterminada |
| `is_irrevocable` | `boolean` | Verdadeiro quando a procuração é declarada irrevogável de forma explícita |
| `revocation_clause` | `string` | Texto da cláusula de revogação, quando presente |
| `notary_name` | `string` | Nome do cartório onde o documento foi registrado |
| `notary_registration_number` | `string` | Número de registro ou livro no cartório |
| `notary_date` | `string` | Data do reconhecimento em cartório |
| `document_date` | `string` | Data de assinatura da procuração |
| `purpose` | `string` | Finalidade declarada da procuração (ex.: representar em juízo, movimentar contas bancárias) |

**invoice_default — campos retornados em `analysis_result`**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `company_name` | `string` | Razão social da empresa |
| `cnpj` | `string` | CNPJ da empresa |
| `invoice_type` | enum: `Documento fiscal eletrônico de serviços`, `Documento fiscal eletrônico de produto` | Tipo de nota fiscal — produto ou serviço |
| `taxation_type` | `string` | Tipo de tributação |
| `invoice_issue_date` | `string` | Data de emissão da nota |
| `invoice_number` | `string` | Número da nota fiscal |
| `contracting_company` | `string` | Empresa contratante |
| `invoice_description` | `string` | Descrição da nota fiscal |
| `invoice_value` | `number` | Valor da nota fiscal |
| `items[]` | `object` | Lista de itens da nota fiscal |
| `items[].code` | `string` | Código do item (NCM/SH) |
| `items[].description` | `string` | Descrição do item |
| `items[].quantity` | `integer` | Quantidade do item |
| `items[].value` | `number` | Valor do item |
| `rps_code` | `string` | Código do RPS — Recibo Provisório de Serviços |
| `access_key` | `string` | Chave de acesso, para notas fiscais de produto |

**bankslip_default — campos retornados em `analysis_result`**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `beneficiary_cnpj` | `string` | CNPJ do beneficiário |
| `beneficiary_company_name` | `string` | Razão social do beneficiário |
| `boleto_barcode` | `string` | Código de barras do boleto |
| `due_date` | `string` | Data de vencimento |
| `value` | `number` | Valor do boleto |

**ccb_default — campos retornados em `analysis_result`**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `contract_number` | `string` | Número da CCB |
| `issuer_document` | `string` | CPF ou CNPJ do emitente da CCB |
| `issuer_cep` | `string` | CEP do emitente |
| `guarantee_chassis` | `string` | Chassi do veículo dado em garantia, se aplicável |
| `invoice_total_value` | `number` | Valor total da nota fiscal, se aplicável |
| `annual_interest_rate` | `number` | Taxa de juros anual prefixada, em percentual |
| `financed_amount` | `number` | Valor total financiado na CCB |
| `total_installments` | `integer` | Quantidade total de prestações |
| `first_due_date` | `string` | Vencimento da primeira parcela |
| `last_due_date` | `string` | Vencimento da última parcela (ver a fluxo de pagamento) |
| `has_signature` | `boolean` | Indica se o documento possui assinatura válida (física ou digital) |
| `is_valid_contract` | `boolean` | Indica se o documento enviado é uma cédula de crédito bancária |

**portability_retention_evidence_analysis — campos retornados em `analysis_result`**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `contract_number` | `string` | Número do contrato |
| `issuer_document_number` | `string` | CPF do tomador de crédito |
| `issuer_phone_number` | `string` | Número de telefone do tomador |
| `portability_number` | `number` | Número da portabilidade |
| `has_signature` | `boolean` | Indica se o documento (especialmente se for uma CCB) contém elementos de assinatura eletrônica, como um hash, código de verificação, QR Code ou uma página de autenticação. |
| `is_valid_evidence` | `boolean` | Indica se o documento é um tipo de evidência aceitável, como uma conversa de texto ou uma Cédula de Crédito Bancário (CCB). |
| `is_confirmation` | `boolean` | Indica se a evidência confirma o cancelamento da portabilidade. Deve ser TRUE se o cliente declarar explicitamente o cancelamento ou não reconhecimento do pedido de portabilidade OU se a evidência for uma CCB com assinatura (has_signature: true). Deve ser FALSE caso não seja uma conversa OU a conversa não indique um cancelamente ou não reconhecimento. As opções aqui devem sempre ser TRUE ou FALSE. |

Para tipos de análise não listados aqui, entre em contato com nossa equipe de suporte em `suporte.caas@qitech.com.br` para consultar sobre implementações personalizadas.

## **Formatos e Limites do Arquivo**

O campo `document_bytes` aceita os formatos abaixo. O tipo real do arquivo é verificado pelo conteúdo, não pela extensão nem pelo `Content-Type` declarado — enviar um `.jpg` rotulado como `application/pdf` resulta em `DOC00202`.

| Formato | Tamanho máximo | Observações |
| --- | --- | --- |
| PDF | 30 MB | Máximo de 350 páginas (`DOC00203`). PDFs protegidos por senha são rejeitados (`DOC00305`). |
| JPEG | 30 MB | |
| PNG | 10 MB | |

## **Respostas**

### Resposta de Sucesso (`200 OK`)

Em uma análise síncrona concluída com sucesso, a API retorna `HTTP 200 OK` com o corpo abaixo. Os campos do envelope são sempre os mesmos; o que varia por `document_analysis_type` é o conteúdo de `analysis_result`.

```json
{
  "id": "solicitacao-abc-12345",
  "document_analysis_type": "proof_of_address_default",
  "validation_status": "valid",
  "file_metadata": { "file_type": "pdf" },
  "analysis_result": { "...": "campos extraídos, variam por tipo de análise" },
  "feedback_data": null
}
```

| Campo | Descrição |
| --- | --- |
| `id` | O mesmo identificador que você enviou na requisição. |
| `document_analysis_type` | O tipo de análise aplicado. |
| `validation_status` | Resultado da validação. Veja os valores possíveis abaixo. |
| `file_metadata` | Metadados do arquivo recebido, como o tipo detectado. |
| `analysis_result` | Os dados extraídos. Vazio (`{}`) quando a análise não foi concluída. |
| `feedback_data` | Feedback que você tenha registrado para este documento, se houver. |

#### Valores de `validation_status`

| Valor | Significado |
| --- | --- |
| `valid` | Análise concluída com sucesso. |
| `pending` | Ainda em processamento. |
| `missing_information` | O documento não possui informações obrigatórias. |
| `bad_quality` | Qualidade do documento insuficiente para análise. |
| `invalid_data` | O documento contém dados inválidos ou inconsistentes. |
| `incorrect_document_type` | O conteúdo não corresponde ao tipo de análise solicitado. |
| `parsing_error` | O resultado da análise não pôde ser interpretado. |
| `analysis_failed` | A análise não pôde ser concluída pelo modelo. |

### Resposta de Aceito (`202 OK`)

Se o documento for processado de forma assíncrona, a API retornará um status `HTTP 202 Accepted` e a requisição será processada de maneira assíncrona. Depois de alguns instantes é possível recuperar a análise do documento usando uma requisição GET, conforme descrito abaixo .

## **Resposta de Erro (`4xx`)**

Se houver um problema com a requisição ou com o documento, a API retornará um código de status `4xx` com um corpo JSON descrevendo o erro.

## Referência de Códigos de Erro

As tabelas a seguir listam todos os códigos de erro possíveis retornados pela API. Você pode usar esses códigos para implementar um tratamento de erros robusto em sua aplicação.

### **Categoria 1: Erros de Requisição (DOC001xx)**

| Código | Título | Descrição |
| --- | --- | --- |
| `DOC00100` | Missing required field | A requisição não contém um campo obrigatório no corpo `multipart/form-data`. |
| `DOC00101` | Invalid field length | O comprimento de um valor em um campo `form-data` é inválido. |
| `DOC00102` | Invalid content type at request | O cabeçalho `Content-Type` da requisição não é `multipart/form-data`. |
| `DOC00103` | Invalid field at request | A requisição contém um campo inesperado ou inválido no corpo `form-data`. |

### **Categoria 2: Erros no Processamento do Arquivo (DOC002xx)**

Estes erros ocorrem quando o próprio arquivo enviado possui problemas que impedem seu processamento.

| Código | Título | Descrição |
| --- | --- | --- |
| `DOC00200` | Invalid Document Analysis Type | O `document_analysis_type` não é válido para o documento enviado. (ex: uma análise `company_statute_default` apartir de uma conta de luz.) |
| `DOC00201` | Invalid File Size | O tamanho do documento enviado excede o limite máximo permitido. |
| `DOC00202` | Invalid File Type | O arquivo não pôde ser processado devido a inconsistências em seu tipo ou formato (ex: um arquivo `.jpg` foi enviado com o tipo `application/pdf`). |
| `DOC00203` | PDF exceeds page limit | O arquivo PDF fornecido contém mais páginas do que o limite máximo permitido para processamento (o limite atual é de 350 páginas). |

### **Categoria 3: Erros na Análise do Documento (DOC003xx)**

Estes erros ocorrem durante a fase de extração e análise de dados, após o arquivo ter sido aberto com sucesso.

| Código | Título | Descrição |
| --- | --- | --- |
| `DOC00300` | Missing Information | O documento não contém informações essenciais necessárias para que a análise seja concluída. |
| `DOC00301` | Bad Quality | A qualidade do documento (ex: resolução, legibilidade, nitidez) é muito baixa para ser analisada com precisão. |
| `DOC00302` | Invalid Data | O documento contém dados inconsistentes ou inválidos (ex: checksums incorretos, campos contraditórios). |
| `DOC00303` | Incorrect Document Type | O conteúdo do documento não corresponde ao tipo de documento esperado para o `document_analysis_type` selecionado. |
| `DOC00304` | Invalid PDF File | O arquivo fornecido não é um PDF válido ou bem-formado e não pôde ser aberto. |
| `DOC00305` | Password Protected PDF | O PDF enviado está criptografado com uma senha e não pode ser processado. |
| `DOC00306` | Parsing Error | A análise do documento não pôde ser processada. |

### **Categoria 4: Falhas de Serviço (DOC005xx)**

Estes erros indicam uma falha do nosso lado, não do seu documento nem da sua requisição. São retornados com status HTTP `5xx` e a ação recomendada é **repetir a requisição**.

| Código | Título | Status HTTP | Descrição |
| --- | --- | --- | --- |
| `DOC00500` | Analysis Failed | `503` | Não foi possível concluir a análise. Tente novamente; se o problema persistir, contate o suporte. |

# **Recuperar a Análise de um documento**

Você pode recuperar os resultados de uma análise de documento enviada anteriormente a qualquer momento, usando seu `id` exclusivo.

`https://api.caas.qitech.app/document_analysis/document/{document_id}` 

Substitua document_id pelo mesmo valor que você usou para fazer a requisição `POST`.

# **Registrar feedback de uma análise**

Você pode registrar um retorno sobre a qualidade de uma análise, o que nos ajuda a melhorar os modelos. Envie um POST para o endpoint abaixo usando o mesmo `id` da requisição original.

`POST https://api.caas.qitech.app/document_analysis/document/{document_id}/feedback`

```bash
curl -X POST "https://api.caas.qitech.app/document_analysis/document/solicitacao-abc-12345/feedback" \
-H "Authorization: SUA_CHAVE_API" \
-H "Content-Type: application/json" \
-d '{
  "event_date": "2026-09-02T14:30:00",
  "feedback_data": { "campo_incorreto": "issue_date", "valor_correto": "2026-07-20" }
}'
```

| Atributo | Descrição |
| --- | --- |
| `event_date` (obrigatório) | Data e hora do feedback. |
| `feedback_data` (obrigatório) | Objeto livre com o conteúdo do feedback. |

O feedback registrado passa a ser retornado no campo `feedback_data` ao recuperar a análise. Também é possível consultá-lo com um `GET` no mesmo endpoint.

---

# Status HTTP

URL: /documentation/caas/document_analysis/http_status

Todas as APIs da QI Tech utilizam a seguinte padronização nos status HTTP de retorno, de acordo com o RFC 7231 :

Status HTTP | Significado | Descrição
---------- | ------- | ---------------------------------
400 | Bad Request | A requisição enviada possui algum erro de formatação. Na maioria dos casos, retornamos no corpo da mensagem uma explicação de onde está o erro. Nesta API implementamos uma série de códigos de erro específicos para ajudar a entender o que pode estar errado.
401 | Unauthorized | Houve algum problema na autenticação, verifique se a API Key está correta e no header correto, de acordo com a seção Autenticação .
403 | Forbidden | O endpoint acessado é de uso interno e não está disponível para esta API Key.
404 | Not Found | O dado requisitado não foi encontrado usando a chave utilizada. Este status também é retornado quando um endpoint inválido é requisitado.
405 | Method Not Allowed | O método HTTP utilizado (POST, GET, PUT, ...) não se aplica ao endpoint utilizado.
406 | Not Acceptable | Os dados enviados no corpo da requisição são inválidos. Em geral, isso significa que os dados enviados não são um JSON válido.
409 | Conflict | O id do documento enviado corresponde a um id já processado anteriormente. Este status é retornado no caso de requisições duplicadas enviadas ao servidor, ou requisições e dois documentos com o mesmo id.
500 | Internal Server Error | Tivemos um problema para processar esta requisição. Quando este erro acontece nosso time é automaticamente notificado e inicia a análise e solução imediatamente.
503 | Service Unavailable | Você se deparou com uma indisponibilidade, planejada ou não, de infraestrutura dos nossos servidores.

---

# Introdução

URL: /documentation/caas/document_analysis/introduction

Bem vindo à API de Análise de Documentos da QI Tech. Está API foi especialmente feita para analisar documentos complexos que não seguem um formato padrão, como comprovantes de residencia, contratos, notas fiscais, CCBs, boletos e outros.

## **Suporte e Feedback**

Caso encontre qualquer problema técnico ou necessite de assistência, entre em contato com nossa equipe de suporte através do e-mail suporte.caas@qitech.com.br. Estamos comprometidos em fornecer uma resposta em tempo hábil.

## **Adoramos Feedback**

Valorizamos muito o feedback de nossos clientes! Se identificar quaisquer imprecisões, seções pouco claras ou tiver sugestões de melhoria, encorajamos que as compartilhe com nossa equipe. Sua contribuição nos ajuda a aprimorar a experiência de todos os usuários!

## **Ambientes**

A API está disponível em dois ambientes distintos para uso dos clientes. As URLs base para as APIs são as seguintes:

- Produção - `https://api.caas.qitech.app/document_analysis/`
- Sandbox - `https://api.sandbox.caas.qitech.app/document_analysis/`

**Aviso Importante!**

O uso de dados reais de pessoas físicas e/ou jurídicas é estritamente proibido no ambiente de Sandbox da QI Tech.

## **Somente HTTPS**

Por questão de segurança, toda a comunicação com as APIs da QI Tech deve ser realizada utilizando a comunicação HTTPS. Para garantir a conformidade e prevenir a transmissão insegura de dados, o servidor está configurado para aceitar exclusivamente conexões na porta 443 com o protocolo TLS 1.2. Chamadas realizadas utilizando outros protocolos serão automaticamente rejeitadas.

## **Autenticação**

O acesso à API é concedido através do uso de uma Chave de API (API Key). A sua chave de acesso foi ou será enviada para o seu e-mail. Caso ainda não a tenha recebido, por favor, entre em contato com nossa equipe de suporte em suporte.caas@qitech.com.br.

A API espera que a chave seja incluída no cabeçalho (header) `Authorization` de cada requisição enviada ao servidor.

**Exemplo de Requisição:**

```bash
# A flag -H adiciona o cabeçalho de autorização necessário à requisição.
curl "endpoint_da_api_aqui" \
  -H "Authorization: EXAMPLE_API_KEY"
```

:::info **Atenção**

Você deve substituir EXAMPLE-OF-API-KEY com a API Key recebida do suporte.
:::

---

# Webhook

URL: /documentation/caas/document_analysis/webhook

Webhook

Quando uma análise assíncrona é finalizada, um webhook é enviado com o resultado da análise. Para isso, é necessário configurar um endereço onde vamos notificar as atualizações e também uma *signature_key* que será utilizada para assinar a requisição. Caso ainda não tenha um webhook configurado, fale com a equipe de [suporte](mailto:suporte.caas@qitech.com.br).

## Assinatura do Webhook

## Requisição

A requisição possui o formato abaixo e notifica que a análise foi finalizada. A requisição utiliza o método HTTP POST e o corpo da requisição é enviado como texto codificado em UTF-8.

### Webhook de Sucesso

```bash
curl --location 'YOUR-ENDPOINT-HERE' \
--header 'Signature: CALCULATED-HASH-HMAC' \
--data '{"id": "e314ffci-14f3-41a1-ad5d-c9c18782jhfe", "document": {"analysis_result": {...},  "validation_status": "valid"}, "status": "successful", "status_reason": "", "status_description": "Sucessfull Analysis"}'
```

### Webhook de Erro 
```bash
curl --location 'YOUR-ENDPOINT-HERE' \
--header 'Signature: CALCULATED-HASH-HMAC' \
--data '{"id": "e314ffci-14f3-41a1-ad5d-c9c18782jhfe", "status": "bad_request", "status_reason": "missing_information
", "status_description": "The document is missing required information."}'
```

### Motivos de erro

Quando a análise não é concluída com sucesso, o campo `status_reason` indica o motivo:

| status_reason | Descrição |
| --- | --- |
| `missing_information` | O documento não possui informações obrigatórias. |
| `invalid_data` | O documento possui dados inválidos. |
| `bad_quality` | O documento enviado tem qualidade baixa e não pôde ser processado. |
| `parsing_error` | O resultado da análise não pôde ser interpretado como JSON. |
| `analysis_failed` | Falha do nosso lado: não foi possível concluir a análise. A ação recomendada é a sua integração **repetir a requisição**, sem envolver o usuário final — o documento está correto. |

### O campo `status`

O campo `status` classifica o resultado e tem três valores:

| status | Significado |
| --- | --- |
| `successful` | A análise foi concluída. O campo `document` traz o resultado. |
| `bad_request` | O documento enviado não permitiu concluir a análise. Veja `status_reason`. |
| `failed` | Falha nossa, não do documento. A ação recomendada é repetir a requisição. |

Numa análise **síncrona** essa mesma falha aparece como `HTTP 503` com o código `DOC00500`; no fluxo assíncrono ela chega por este webhook, porque não há requisição aberta para responder.

---

# builder

URL: /documentation/caas/face_recognition/android/builder

## FaceRecognition.Builder

| Parâmetro                                                                                                                                     | Função                                                                                                                                                                                                                                                                                                                                                                    | Obrigatório                                                                                                                                                                                                  |
| --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---- |
| mobileToken                                                                                                                                   | Chave do cliente que identifica que os dados coletados são provenientes do seu aplicativo. Caso ainda não tenha recebido o seu mobile-token, entre em contato com o <a href='mailto:suporte.caas@qitech.com.br'>suporte</a>.                                                                                                                                              | Sim.                                                                                                                                                                                                         |
| .setSandboxEnvironment()                                                                                                                      | Caso este parâmetro seja utilizado no construtor, a biblioteca será configurada para enviar os dados ao ambiente de sandbox. Caso ausente, as requisições são enviadas para o ambiente production.                                                                                                                                                                        | Não.                                                                                                                                                                                                         |
| .showIntroductionScreens(Boolean showIntroductionScreens)                                                                                     | Quando "false" desativa as telas de introdução à coleta da foto que aparecem para o usuário.                                                                                                                                                                                                                                                                              | Não. O padrão é "true".                                                                                                                                                                                      |
| .setShowSuccessScreen(Boolean showSuccessScreen)                                                                                              | Quando "false" desativa a tela de sucesso após a coleta da foto.                                                                                                                                                                                                                                                                                                          | Não. O padrão é "true".                                                                                                                                                                                      |
| .setBackgroundColor(String backgroundColor)                                                                                                   | Permite a configuração da cor de background das activities do SDK.                                                                                                                                                                                                                                                                                                        | Não. O padrão é "#ffffff".                                                                                                                                                                                   |
| .setFontColor(String fontColor)                                                                                                               | Permite a configuração da cor da fonte e dos ícones das activities do SDK.                                                                                                                                                                                                                                                                                                | Não. O padrão é "#000000".                                                                                                                                                                                   |
| .setFontFamily(FontFamily fontFamily)                                                                                                         | Permite a configuração da fonte das activities do SDK.                                                                                                                                                                                                                                                                                                                    | Não. Caso não seja informada o padrão é FontFamily.open_sans. Fontes disponíveis: FontFamily.open_sans, FontFamily.futura, FontFamily.verdana, FontFamily.roboto, FontFamily.poppins e FontFamily.helvetica. | Não. |
| .activeFaceLiveness(Boolean activeFaceLiveness)                                                                                               | Indica se o SDK deve realizar um procedimento de captura de selfie do usuário ou de prova de vida ativa.                                                                                                                                                                                                                                                                  | Não. O padrão é _false_.                                                                                                                                                                                     |
| .audioConfiguration(AudioConfiguration audioConfiguration)                                                                                    | Configura o guiamento por voz do SDK, que narra as instruções de captura em tempo real. As configurações aceitas são _AudioConfiguration.enable_, que exibe o botão de ligar/desligar áudio com a narração iniciando desligada; _AudioConfiguration.disable_, que desativa a narração e oculta o botão; e _AudioConfiguration.accessibility_, que exibe o botão com a narração iniciando ligada quando o dispositivo possui recursos de acessibilidade ativos. Com o TalkBack ativo, as instruções completas são entregues pelo próprio leitor de telas. | Não. O padrão é _AudioConfiguration.disable_.                                                                                                                                                                |
| .setVisualConfiguration([VisualConfiguration](https://docs.zaig.com.br/android_facerecon/#o-objeto-visualconfiguration). visualConfiguration) | Utilizado para customizar as imagens mostradas para o usuário ao longo da execução do SDK.                                                                                                                                                                                                                                                                                | Não.                                                                                                                                                                                                         |
| .setTextConfiguration([TextConfiguration](https://docs.zaig.com.br/android_facerecon/#o-objeto-textconfiguration). textConfiguration)         | Utilizado para customizar os textos da tela introdutória de onboarding mostradas para o usuário ao longo da execução do SDK.                                                                                                                                                                                                                                              | Não.                                                                                                                                                                                                         |
| .setSessionId(String sessionId)                                                                                                               | Utilizado para definir a chave que identifica a sessão iniciada no SDK. É usada para rastrear todo fluxo percorrido pelo usuário na execução da FaceRecon através de logs. Este campo aceita até 255 caracteres.                                                                                                                                                          | Não.                                                                                                                                                                                                         |
| .setLogLevel(FaceRecognition.LogLevel logLevel)                                                                                               | Utilizado para customizar o nível de verbosidade dos logs do SDK. Níveis disponíveis: LogLevel.debug, LogLevel.info, LogLevel.warn, LogLevel.error e LogLevel.trace. O padrão é LogLevel.debug.                                                                                                                                                                           | Não.                                                                                                                                                                                                         |
| .setDocumentNumber(String documentNumber)                                                                                                     | Utilizado para definir o número do documento do usuário. Este campo aceita 14 caracteres do CPF formatado da seguinte maneira 000.000.000-00                                                                                                                                                                                                                              | Sim em todas as chamadas caso use a validação 1:1 em algum momento.                                                                                                                                          |
| .setValidation(Boolean validation)                                                                                                            | Utilizado para definir se o SDK deve ou não realizar a validação 1:1 com a selfie do usuário. Na primeira sessão do usuário esta flag deve estar, **obrigatoriamente false**. Esta função depende necessita do método setDocumentNumber preenchido.                                                                                                                      | Não. O padrão é _false_.                                                                                                                                                                                     |

## O Objeto VisualConfiguration

| Parâmetro                                                             | Função                                                                                                                                                                                                                                        | Obrigatório             |
| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| .setOnboardingDrawable(int onboarding_drawable, int onboarding_width) | Utilizado para configurar a imagem mostrada para o usuário na tela de onboarding do SDK. O parâmetro _onboarding_drawable_ deve referenciar o id da imagem a ser mostrada e _onboarding_width_ é o tamanho desejado de exibição desta imagem. | Não.                    |
| .setButtonBorderSize(int border_size)                                 | Utilizado para configurar a largura de borda dos botões do SDK.                                                                                                                                                                               | Não. O padrão é _1_.    |
| .setButtonShadow(boolean button_shadow)                               | Quando setado para _false_ remove o efeito de sombra, padrão no android, utilizado pelos botões do SDK.                                                                                                                                       | Não. O padrão é _true_. |

## O Objeto TextConfiguration

| Parâmetro                                      | Função                                                                                    | Obrigatório |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------- | ----------- |
| .setCustomText(CustomLabel label, String text) | Utilizado para configurar os textos mostrados para o usuário na tela de onboarding do SDK | Não.        |

```

```

---

# Coletando os Resultados

URL: /documentation/caas/face_recognition/android/collecting_response

Para obter o objeto **FaceReconResponse**, que contém os resultados das capturas obtidas pelo SDK, incluindo os identificadores das imagens enviadas no sistema QI Tech, sobrescreva o método *onActivityResult* na mesma activity que você iniciou a **FaceReconActivity**:

```java
@Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        super.onActivityResult(requestCode, resultCode, data);
        if (requestCode == REQUEST_CODE) {
            if (resultCode == RESULT_OK && data != null) {
                faceReconResponse = data.getParcelableExtra("FaceReconResponse");
                image_key = faceReconResponse.image_key;
                device_scan_session_id = faceReconResponse.device_scan_session_id;
                Log.i(TAG_LIVENESS, "FACE RECON RESPONSE: " + faceReconResponse.image_key);
            }
            else if (resultCode == RESULT_CANCELED && data != null) {
                faceReconResponse = data.getParcelableExtra("FaceReconResponse");
                Log.i(TAG_LIVENESS, "FACE RECON RESPONSE: " + faceReconResponse.status_code + " - " + faceReconResponse.reason + " - " + faceReconResponse.description);
            }
        }
    }
```

## Descrição dos Atributos do Objeto FaceReconResponse

:::info Aviso: 
Integração com Device Scan A partir da versão 5.2.0, o serviço de Face Recognition passa a realizar automaticamente uma chamada interna ao Device Scan. Com isso, o retorno de sucesso incluirá o campo `device_scan_session_id`. Esta chave identifica a sessão de scan de dispositivo realizada internamente e pode ser utilizada de forma integrada em outros serviços do ecossistema QI Tech. 
:::

Atributo | Descrição | Resultado | Versões
--------- | --------- | --------- | ---------
image_key | Chave de identificação da imagem fornecida que pode ser utilizada em qualquer outro serviço do sistema QI Tech. | **RESULT_OK** | **Todas**
device_scan_session_id | Chave de identificação da sessão de scan de dispositivo realizada internamente que pode ser utilizada em qualquer outro serviço do sistema QI Tech. | **RESULT_OK** |  **5.2.0+**
status_code | Status code da requisição. | **RESULT_CANCELED** | **5.0.0+**
reason | Identificador do erro | **RESULT_CANCELED** | **5.0.0+**
description | Descrição do erro. | **RESULT_CANCELED** | **5.0.0+**

## Estrutura de Erro (SDK 5.0.0+)

:::danger Aviso Importante! 
A partir da versão **5.0.0**, a estrutura de erros foi reformulada para fornecer informações mais detalhadas e diagnósticas.
:::

### Exemplo: InvalidToken

```java
{
   status_code = 401
    reason = "INVALID_TOKEN"
    description = "Authentication token expired or invalid"
}
```
### Exemplo: UserCanceled

```java
{
    status_code = 0
    reason = "USER_CANCELED"
    description = "User pressed the back button."
}
```

## Versões Anteriores

```java
    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        super.onActivityResult(requestCode, resultCode, data);
        FaceRecognition.RequestResponseObject result;
        if (requestCode == REQUEST_CODE){
            if (resultCode == RESULT_OK && data != null){
                faceReconResponse = data.getParcelableExtra("FaceReconResponse");
            }
        }
    }
```

---

# Validação 1:1 - Face Match

URL: /documentation/caas/face_recognition/android/face_match

Para utilizar a funcionalidade de Validação 1:1 (Face Match) é necessário que o parâmetro _validation_ seja setado como _true_ no construtor do SDK, isso pode ser feito chamando o metodo `setValidation()`. Além disso, é necessário que o parâmetro _documentNumber_ seja preenchido com o CPF do usuário. Conforme exemplo abaixo:

```java
FaceRecognition faceRecognition = new FaceRecognition.Builder("YOUR_MOBILE_TOKEN_SENT_BY_QITECH")
    // ... Outras configurações
    .setDocumentNumber("000.000.000-00")
    .setValidation(true)
    // ...
    .build();
```

> **ATENÇÃO:** A validação 1:1 só pode ser utilizada a partir da segunda sessão do usuário, ou seja, após a primeira sessão, quando o parâmetro _documentNumber_ for preenchido com CPF do usuário e o parâmetro _validation_ com `false`, havendo um registro para ser validado.

---

# Introdução

URL: /documentation/caas/face_recognition/android/introduction

Bem-vindo ao SDK Android de Reconhecimento Facial da QI Tech. Este SDK realiza a captura da face e o seu envio para a API de Face Recognition da QI Tech . Você pode utilizá-lo para capturar uma imagem do rosto de um cliente por meio do seu aplicativo e referenciá-la por meio de uma chave nos demais produtos do sistema QI Tech.

## Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso [suporte](mailto:suporte.caas@qitech.com.br) e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

### Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.  
:::

---

# Integração nativa

URL: /documentation/caas/face_recognition/android/native_java

Para importar nossas SDKs, é necessário realizar alteração no _build.gradle_ de Projeto e de Aplicativo.

## Adicionando ao Projeto

Adicione o endereço de nosso repositório maven no _build.gradle_ do projeto (no Android Studio este arquivo aparece como: **"Project: \{nome_do_projeto\}"**), conforme exemplo abaixo.

```java
maven { url 'https://sdks.qitech.com.br/' }
```

## Adicionando ao Aplicativo

Após isso, adicione a biblioteca que você pretende importar em seu build.gradle do app (no Android Studio este arquivo aparece como: **"Module: \{nome_do_projeto\}.app"**), incluindo a dependência apresentada abaixo.

```java
dependencies {
    implementation 'com.qitech.android:facerecon:v7.1.0'
}
```

:::warning
Desde **abril de 2025**, novas políticas da Google Play requerem **Android API Level 35** para que aplicativos possam ser publicados
ou atualizados na Google Play Store. Por isso recomendamos fortemente que utilize **targetSdkVersion na versão 35** pelo menos.
:::

:::info
A utilização de **targetSdkVersion 35** implica na utilização do **compileSdkVersion 35**, o que desencadeia alguns **requisitos mínimos** para ferramentas
do ecossistema do Android:
* compileSdkVersion 35 --> AGP 8.6.0
* AGP 8.6.0 --> Gradle 8.7
* AGP 8.6.0 --> Java 17 (JDK 17)
* AGP 8.6.0 --> Kotlin 2+
:::

## Iniciando o SDK

:::danger Aviso Importante!
A partir da versão 5.0.0, o sistema de autenticação foi atualizado para usar **clientSessionKey** em vez de **mobileToken**. Além disso, foram adicionadas novas opções de configuração para telas de feedback.
:::

### Obtendo o Client Session Key

Antes de configurar o SDK, você deve gerar um **clientSessionKey** temporário através de uma requisição server-to-server para a nossa API de face recognition.

### Endpoint

| Ambiente | URL |
|----------|-----|
| **Sandbox** | `https://api.sandbox.zaig.com.br/face_recognition/client_session` |
| **Produção** | `https://api.zaig.com.br/face_recognition/client_session` |

### Requisição

**Method:** `POST`

**Headers:**
```json
{
  "Authorization": "YOUR_FACE_RECON_API_KEY"
}
```

**Body (Opcional, mas recomendado):**
```json
{
  "user_id": "unique_user_identifier" // Se disponível, utilize o CPF do usuário!
}
```

> **Importante:** O campo `user_id` é **altamente recomendado** para medidas de segurança e antifraude. Use um identificador único do usuário da sua aplicação.

### Resposta

A resposta bem-sucedida conterá o `client_session_key` que deve ser passado para a configuração do SDK.

```json
{
  "client_session_key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

Para incorporar o SDK ao seu aplicativo você deve realizar a configuração do seu aplicativo de captura personalizado através de um componente Builder e submetê-lo como parâmetro via Intent Extra para a FaceReconActivity.

### Exemplo de inicialização do SDK
```java
  Intent intent = new Intent(getApplicationContext(), FaceReconActivity.class);

  var onboardingTextConfiguration = new OnboardingTextConfiguration(
        "Conselhos relevantes",
        "Esteja com o rosto visível",
        "Encaixe seu rosto no oval",
        "Retire acessórios que cubram o rosto"
  );

  FaceRecognition mFaceRecognition = new FaceRecognition.Builder(clientSessionKey)
        .setSessionId("SESSION_ID")
        .setDocumentNumber("111.111.111-11")
        .setFontColor("#FFFFFF")
        .setBackgroundColor("#000000")
        .setFontFamily(FaceRecognition.FontFamily.futura)
        .showIntroductionScreens(true)
        .setShowSuccessScreen(true)
        .setShowInvalidTokenScreen(false)
        .setOnboardingTextConfiguration(onboardingTextConfiguration)
        .audioConfiguration(AudioConfiguration.enable)
        .setLogLevel(FaceRecognition.LogLevel.debug)
        .build();

  intent.putExtra("settings", mFaceRecognition);
  startActivityForResult(intent, REQUEST_CODE);
```

**Versões anteriores à v6.0.0**
```java
  Intent intent = new Intent(getApplicationContext(), FaceReconActivity.class);

  VisualConfiguration visualConfiguration = new VisualConfiguration()
          .setOnboardingDrawable(R.drawable.introscreen,500);

  TextConfiguration textConfiguration = new TextConfiguration()
          .setCustomText(TextConfiguration.CustomLabel.onboardingTitle, "Para tirar uma boa foto:")
          .setCustomText(TextConfiguration.CustomLabel.onboardingFirstLabel, "- Vá para um local iluminado")
          .setCustomText(TextConfiguration.CustomLabel.onboardingSecondLabel, "- Retire adereços e mostre bem o rosto")
          .setCustomText(TextConfiguration.CustomLabel.onboardingThirdLabel, "- Insira seu rosto na moldura, aguardando que fique verde para realizar a captura");

  FaceRecognition mFaceRecognition = new FaceRecognition.Builder(clientSessionKey)
          .showIntroductionScreens(true)
          .setVisualConfiguration(visualConfiguration)
          .setTextConfiguration(textConfiguration)
          .setBackgroundColor("#000000")
          .setFontColor("#FFFFFF")
          .setFontFamily(FaceRecognition.FontFamily.futura)
          .setSessionId("SESSION_ID")
          .setLogLevel(FaceRecognition.LogLevel.debug)
          .setShowSuccessScreen(false)
          .build();
  intent.putExtra("settings", mFaceRecognition);
  startActivityForResult(intent, REQUEST_CODE);
```

## FaceRecognition.Builder
| Parâmetro | Função | Obrigatório |
|------------|--------------|--------------|
|clientSessionKey |Chave do cliente que identifica que os dados coletados são provenientes do seu aplicativo. Obtida através de requisição à API da Face Recognition|Sim.|
|.setSandboxEnvironment()|Caso este parâmetro seja utilizado no construtor, a biblioteca será configurada para enviar os dados ao ambiente de sandbox. Caso ausente, as requisições são enviadas para o ambiente production.|Não.|
|.showIntroductionScreens(Boolean showIntroductionScreens)|Quando "false" desativa as telas de introdução à coleta da foto que aparecem para o usuário.|Não. O padrão é "true".|
|.setShowSuccessScreen(Boolean showSuccessScreen)|Quando "false" desativa a tela de sucesso após a coleta da foto.|Não. O padrão é "true".|
|.setShowInvalidTokenScreen(Boolean showSuccessScreen)|Quando "false" desativa a tela de falha de autenticação.|Não. O padrão é "true".|
|.setBackgroundColor(String backgroundColor)|Permite a configuração da cor de background das activities do SDK.|Não. O padrão é "#ffffff".|
|.setFontColor(String fontColor)|Permite a configuração da cor da fonte e dos ícones das activities do SDK.|Não. O padrão é "#000000".|
| .setFontFamily(FontFamily fontFamily)| Permite a configuração da fonte das activities do SDK.| Não. Caso não seja informada o padrão é FontFamily.open_sans. Fontes disponíveis: FontFamily.open_sans, FontFamily.futura, FontFamily.verdana, FontFamily.roboto, FontFamily.poppins e FontFamily.helvetica.|Não.|
|.setOnboardingTextConfiguration(OnboardingTextConfiguration onboardingTextConfiguration) | Permite a customização das instruções na tela de introdução. | Não. |
|.audioConfiguration(AudioConfiguration audioConfiguration)|Configura o guiamento por voz do SDK, que narra as instruções de captura em tempo real. As configurações aceitas são _AudioConfiguration.enable_, que exibe o botão de ligar/desligar áudio com a narração iniciando desligada; _AudioConfiguration.disable_, que desativa a narração e oculta o botão; e _AudioConfiguration.accessibility_, que exibe o botão com a narração iniciando ligada quando o dispositivo possui recursos de acessibilidade ativos. Com o TalkBack ativo, as instruções completas são entregues pelo próprio leitor de telas.|Não. O padrão é _AudioConfiguration.disable_.|
|.setSessionId(String sessionId)| Utilizado para definir a chave que identifica a sessão iniciada no SDK. É usada para rastrear todo fluxo percorrido pelo usuário na execução da FaceRecon através de logs. Este campo aceita até 255 caracteres. |Não.|
|.setLogLevel(FaceRecognition.LogLevel logLevel)| Utilizado para customizar o nível de verbosidade dos logs do SDK. Níveis disponíveis: LogLevel.debug, LogLevel.info, LogLevel.warn, LogLevel.error e LogLevel.trace. O padrão é LogLevel.debug. |Não.|
|.setDocumentNumber(String documentNumber)| Utilizado para definir o número do documento do usuário. Este campo aceita 14 caracteres. | Para Identificação utilizada internamente para anti-fraude e segurança. |

**Versões anteriores à v6.0.0**
| Parâmetro | Função | Obrigatório |
|------------|--------------|--------------|
|clientSessionKey |Chave do cliente que identifica que os dados coletados são provenientes do seu aplicativo. Obtida através de requisição à API da Face Recognition|Sim.|
|.setSandboxEnvironment()|Caso este parâmetro seja utilizado no construtor, a biblioteca será configurada para enviar os dados ao ambiente de sandbox. Caso ausente, as requisições são enviadas para o ambiente production.|Não.|
|.showIntroductionScreens(Boolean showIntroductionScreens)|Quando "false" desativa as telas de introdução à coleta da foto que aparecem para o usuário.|Não. O padrão é "true".|
|.setShowSuccessScreen(Boolean showSuccessScreen)|Quando "false" desativa a tela de sucesso após a coleta da foto.|Não. O padrão é "true".|
|.setShowInvalidTokenScreen(Boolean showSuccessScreen)|Quando "false" desativa a tela de falha de autenticação.|Não. O padrão é "true".|
|.setBackgroundColor(String backgroundColor)|Permite a configuração da cor de background das activities do SDK.|Não. O padrão é "#ffffff".|
|.setFontColor(String fontColor)|Permite a configuração da cor da fonte e dos ícones das activities do SDK.|Não. O padrão é "#000000".|
| .setFontFamily(FontFamily fontFamily)| Permite a configuração da fonte das activities do SDK.| Não. Caso não seja informada o padrão é FontFamily.open_sans. Fontes disponíveis: FontFamily.open_sans, FontFamily.futura, FontFamily.verdana, FontFamily.roboto, FontFamily.poppins e FontFamily.helvetica.|Não.|
|.activeFaceLiveness(Boolean activeFaceLiveness)|Indica se o SDK deve realizar um procedimento de captura de selfie do usuário ou de prova de vida ativa. |Não. O padrão é *false*.|
|.audioConfiguration(AudioConfiguration audioConfiguration)|Configura o guiamento por voz do SDK, que narra as instruções de captura em tempo real. As configurações aceitas são _AudioConfiguration.enable_, que exibe o botão de ligar/desligar áudio com a narração iniciando desligada; _AudioConfiguration.disable_, que desativa a narração e oculta o botão; e _AudioConfiguration.accessibility_, que exibe o botão com a narração iniciando ligada quando o dispositivo possui recursos de acessibilidade ativos. Com o TalkBack ativo, as instruções completas são entregues pelo próprio leitor de telas.|Não. O padrão é _AudioConfiguration.disable_.|
|.setVisualConfiguration(VisualConfiguration visualConfiguration)|Utilizado para customizar as imagens mostradas para o usuário ao longo da execução do SDK.|Não.|
|.setTextConfiguration(TextConfiguration textConfiguration)|Utilizado para customizar os textos da tela introdutória de onboarding mostradas para o usuário ao longo da execução do SDK.|Não.|
|.setSessionId(String sessionId)| Utilizado para definir a chave que identifica a sessão iniciada no SDK. É usada para rastrear todo fluxo percorrido pelo usuário na execução da FaceRecon através de logs. Este campo aceita até 255 caracteres. |Não.|
|.setLogLevel(FaceRecognition.LogLevel logLevel)| Utilizado para customizar o nível de verbosidade dos logs do SDK. Níveis disponíveis: LogLevel.debug, LogLevel.info, LogLevel.warn, LogLevel.error e LogLevel.trace. O padrão é LogLevel.debug. |Não.|
|.setDocumentNumber(String documentNumber)| Utilizado para definir o número do documento do usuário. Este campo aceita 14 caracteres. |Apenas para as chamadas que utilizem a validação 1:1 em algum momento. |
|.setValidation(Boolean validation)| Utilizado para definir se o SDK deve ou não realizar a validação 1:1 com a selfie do usuário. Na primeira sessão do usuário esta flag deve estar, **obrigatoriamente**, false. Esta função necessita do método setDocumentNumber preenchido.  |Não. O padrão é *false*.|

## O Objeto VisualConfiguration
:::warning
__DEPRECADO__ A PARTIR DA **v6.0.0**!
:::

| Parâmetro                                                             | Função                                                                                                                                                                                                                                        | Obrigatório             |
| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| .setOnboardingDrawable(int onboarding_drawable, int onboarding_width) | Utilizado para configurar a imagem mostrada para o usuário na tela de onboarding do SDK. O parâmetro _onboarding_drawable_ deve referenciar o id da imagem a ser mostrada e _onboarding_width_ é o tamanho desejado de exibição desta imagem. | Não.                    |
| .setButtonBorderSize(int border_size)                                 | Utilizado para configurar a largura de borda dos botões do SDK.                                                                                                                                                                               | Não. O padrão é _1_.    |
| .setButtonShadow(boolean button_shadow)                               | Quando setado para _false_ remove o efeito de sombra, padrão no android, utilizado pelos botões do SDK.                                                                                                                                       | Não. O padrão é _true_. |

## O Objeto TextConfiguration
:::warning
__DEPRECADO__ A PARTIR DA **v6.0.0**!
:::

| Parâmetro                                      | Função                                                                                    | Obrigatório |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------- | ----------- |
| .setCustomText(CustomLabel label, String text) | Utilizado para configurar os textos mostrados para o usuário na tela de onboarding do SDK | Não.        |

---

# using_sdk

URL: /documentation/caas/face_recognition/android/using_sdk

## Iniciando o SDK

Para incorporar o SDK ao seu aplicativo você deve realizar a configuração do seu aplicativo de captura personalizado através de um componente Builder e submetê-lo como parâmetro via Intent Extra para a FaceReconActivity.

```java
  Intent intent = new Intent(getApplicationContext(), FaceReconActivity.class);

  VisualConfiguration visualConfiguration = new VisualConfiguration()
          .setOnboardingDrawable(R.drawable.introscreen,500);

  TextConfiguration textConfiguration = new TextConfiguration()
          .setCustomText(TextConfiguration.CustomLabel.onboardingTitle, "Para tirar uma boa foto:")
          .setCustomText(TextConfiguration.CustomLabel.onboardingFirstLabel, "- Vá para um local iluminado")
          .setCustomText(TextConfiguration.CustomLabel.onboardingSecondLabel, "- Retire adereços e mostre bem o rosto")
          .setCustomText(TextConfiguration.CustomLabel.onboardingThirdLabel, "- Insira seu rosto na moldura, aguardando que fique verde para realizar a captura");

  FaceRecognition mFaceRecognition = new FaceRecognition.Builder("YOUR_MOBILE_TOKEN_SENT_BY_QITECH")
          .showIntroductionScreens(true)
          .setVisualConfiguration(visualConfiguration)
          .setTextConfiguration(textConfiguration)
          .setBackgroundColor("#000000")
          .setFontColor("#FFFFFF")
          .setFontFamily(FaceRecognition.FontFamily.futura)
          .setSessionId("SESSION_ID")
          .setLogLevel(FaceRecognition.LogLevel.debug)
          .setShowSuccessScreen(false)
          .build();
  intent.putExtra("settings", mFaceRecognition);
  startActivityForResult(intent, REQUEST_CODE);
```

Utilizamos um Mobile Token para permitir o acesso autenticado do seu aplicativo a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso ainda não tenha recebido o seu token, envie um e-mail para suporte.caas@qitech.com.br .

Nossa API espera receber o Mobile Token em todas as requisições ao nosso servidor vindas do SDK, portanto, este deve ser obrigatoriamente incluído como parâmetro de configuração através do método mencionado anteriormente.

:::info **Atenção**

Você deve substituir "YOUR_MOBILE_TOKEN_SENT_BY_QITECH" com o Mobile Token recebido do suporte.
:::

---

# Autenticação

URL: /documentation/caas/face_recognition/api/authentication

:::danger Aviso Importante!
A partir da versão 5.0.0 das SDKs de iOS e Android e a versão 3.0.0 do SDK de Web, o sistema de autenticação foi atualizado para usar clientSessionKey em vez de mobileToken.
:::

Utilizamos uma API Key para permitir acesso à nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br .

## Client Session Key

Antes de configurar o SDK, você deve gerar um clientSessionKey temporário através de uma requisição server-to-server para a nossa API.

### Gerar Client Session Key

```bash
curl -X POST "https://api.zaig.com.br/face_recognition/client_session" \
     -H "Authorization: EXAMPLE_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "user_id": "unique_user_identifier" }'
```

**Endpoints**

| Ambiente | URL |
|----------|-----|
| Sandbox | https://api.sandbox.zaig.com.br/face_recognition/client_session |
| Produção | https://api.zaig.com.br/face_recognition/client_session |

**Detalhes da Requisição**

| Campo | Tipo | Obrigatório | Descrição|
|----------|----------|----------|----------|
| user_id | string | Não | Identificador único do usuário da sua aplicação (ex: CPF, RG, etc) |

O campo `user_id` no corpo da requisição é altamente recomendado para medidas de segurança e antifraude.

**Request Body**
```json
{
  "user_id": "unique_user_identifier"
}
```

**Response Body**

A resposta bem-sucedida conterá o `client_session_key`.
```json
{
  "client_session_key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

:::info Atenção
Você deve substituir `EXAMPLE_API_KEY` pela API Key recebida do suporte.
:::

---

# Registro de rosto (1:1)

URL: /documentation/caas/face_recognition/api/face_registration

Para realizar um **registro de rosto** (para posterior validação 1:1), é necessário utilizar os **endpoints específicos** da API de Face Recognition descritos nesta página.

## Endpoints disponíveis

Os recursos de registro de rosto estão expostos nas seguintes rotas:

| Método | Endpoint | Descrição |
|--------|----------|-----------|
| POST | `/face_recognition/registration` | Cria um novo registro de rosto |
| GET | `/face_recognition/registration/{registration_key}` | Recupera registro pela chave |
| GET | `/face_recognition/registration/document_number/{document_number}` | Recupera registro pelo número do documento |

**URL base (produção):** `https://api.caas.qitech.app`  
**URL base (sandbox):** `https://api.sandbox.caas.qitech.app`

---

## Criação de um registro (POST)

Para cadastrar o rosto de um cliente, envie uma requisição **POST** para:

`https://api.caas.qitech.app/face_recognition/registration`

O corpo da requisição deve conter o **número do documento** e a imagem do rosto, de uma das duas formas abaixo.

### Opção 1: imagem via `image_key` (extraída da SDK)

Utilize o **image_key** retornado pela SDK após a captura do rosto.

Request Body – image_key

```json
{
    "document_number": "DOCUMENT_NUMBER",
    "image_key": "<IMAGE_KEY_FROM_SDK>"
}
```

### Opção 2: imagem em Base64

Envie a imagem diretamente em Base64 (sem cabeçalhos ou metadados adicionais).

Request Body – image (Base64)

```json
{
    "document_number": "DOCUMENT_NUMBER",
    "image": "<IMAGE_BASE64>"
}
```

### Campos do request

nome | tipo | descrição
:----: | :----: | ---------
document_number | string | Número do documento (ex.: CPF) do cliente
image_key | string | Chave da imagem retornada pela SDK (UUID). Use **ou** `image_key` **ou** `image`
image | string | Imagem do rosto em Base64. Use **ou** `image` **ou** `image_key`

:::info
É obrigatório enviar **apenas um** dos campos de imagem: `image_key` **ou** `image`. Não envie os dois no mesmo request.
:::

Após o envio com sucesso, a API retorna apenas a chave do registro de rosto:

Response Body

```json
{
    "registration_key": "chave_do_registro_do_rosto"
}
```

---

## Recuperação de registro por chave (GET)

Para obter a chave de um registro pela sua chave única:

`https://api.caas.qitech.app/face_recognition/registration/{registration_key}`

Substitua `{registration_key}` pelo identificador retornado na criação do registro.

**Response Body:**

```json
{
    "registration_key": "chave_do_registro_do_rosto"
}
```

---

## Recuperação de registro por documento (GET)

Para obter a chave de um registro pelo número do documento:

`https://api.caas.qitech.app/face_recognition/registration/document_number/{document_number}`

Substitua `{document_number}` pelo número do documento do cliente (ex.: CPF).

**Response Body:**

```json
{
    "registration_key": "chave_do_registro_do_rosto"
}
```

---

---

# Status HTTP

URL: /documentation/caas/face_recognition/api/http_status

Todas as APIs da QI Tech utilizam a seguinte padronização nos status HTTP de retorno, de acordo com o RFC 7231 :

Status HTTP | Significado | Descrição
---------- | ------- | ---------------------------------
400 | Bad Request | A requisição enviada possui algum erro de formatação. Na maioria dos casos, retornamos no corpo da mensagem uma explicação de onde está o erro.
401 | Unauthorized | Houve algum problema na autenticação, verifique se a API Key está correta e no header correto, de acordo com a seção Autenticação .
403 | Forbidden | O endpoint acessado é de uso interno e não está disponível para esta API Key.
404 | Not Found | O dado requisitado não foi encontrado usando a chave utilizada. Este status também é retornado quando um endpoint inválido é requisitado.
405 | Method Not Allowed | O método HTTP utilizado não se aplica ao endpoint utilizado.
406 | Not Acceptable | Os dados enviados no corpo da requisição são inválidos. Em geral, isso significa que os dados enviados não são um JSON válido.
409 | Conflict | O id da requisição corresponde a um id já processado anteriormente. Este status é retornado no caso de requisições duplicadas enviadas ao servidor.
500 | Internal Server Error | Tivemos um problema para processar esta requisição, ao encontrarmos esse erro nossos especialistas são automaticamente notificados e iniciam a análise e solução imediatamente.
503 | Service Unavailable | Você se deparou com uma indisponibilidade, planejada ou não, de infraestrutura dos nossos servidores.

---

# Imagem

URL: /documentation/caas/face_recognition/api/image

O envio de uma foto de rosto é mandatório para a utilização de nossa API de reconhecimento facial. Visando garantir uma maior confiabilidade das análises executadas, é necessário que o cliente siga algumas regras na hora de tirar a foto:

* A foto deve conter apenas um rosto;
* Todo o rosto deve estar visível na foto;
* O rosto deve ocupar ao menos 15% da area da foto;
* O rosto deve estar encarando a câmera e paralelo a ela;
* O rosto deve estar com os olhos abertos;
* O rosto deve estar com a boca fechada;
* O rosto deve possuir expressão neutra e sem sorrisos;
* O rosto não deve estar coberto por nenhum tipo de acessório (chapéus, óculos ou máscaras).

Além disso, somente imagens .jpeg e .png com tamanho máximo de 3MB serão aceitas.

## Envio de arquivos

Request Body

```json
{
    "image": "base64_image_code"
}
```

Response Body

```json
{ 
    "image_key": "f4b5337a-7b50-406e-8c8e-7d0e77b5aa02",
    "file_size": 47407,
    "width_px": 0,
    "height_px": 0,
    "created_at": "2020-07-29T18:40:57Z"
}
```

Em casos que seja necessário o envio de uma imagem sem a execução imediata das rotinas de cadastro ou validação facial, um objeto JSON contendo o Base64 da imagem deve ser enviado. 
Para tal deve-se enviar uma requisição do tipo **POST** para o endpoint:

`https://api.caas.qitech.app/face_recognition/image`

Uma vez enviada, a imagem será submetida a testes de qualidade e, caso aprovada, será retornado um JSON contendo a chave de acesso à imagem. Essa chave deverá ser usada para referenciar a foto durante o cadastro ou validação facial.

:::info **Atenção**

Deve ser enviado apenas o código Base64 correspondente a imagem.
:::

## Validação de qualidade da imagem

Response Body: Caso de imagem inválida

```json
{
    "title": "image_quality",
    "description": "This image was not approved in quality assessment. The face is too close to image edges.",
    "image_status": "not_center"
}
```

Ao realizar um post no endpoint de imagem, caso a imagem não seja suficiente para validação, um HTTP Status Code 400 será retornado.

O valor do campo *description* é a mensagem que explica o motivo da imagem ser inválida.

Além disso, retornamos um enumerador *image_status* para que seja maepado o motivo da imagem ser inválida. Abaixo temos a listagem dos possíveis *image_status*:

image_status |  descrição
:----: | :---------:
no_faces | Nenhum rosto identificado.
multiple_faces | Mais de um rosto identificado.
close_face | Rosto muito próximo à câmera.
distant_face | Rosto muito distante à câmera.
not_centered | Rosto não está centralizado o suficiente.
inclined_face | Rosto está inclinado.
wearing_acessories | Pessoa está utilizando acessórios que cobrem parte do rosto.
facial_expression | A pessoa está com a boca aberta, sorrindo ou com os olhos fechados.
brightness_problem | A imagem não está com a iluminação adequada.
sharpness_problem | A imagem não está nítida o suficiente.

**Atenção -** Existem outros motivos pelos quais retornaremos 400 (Todos relacionados a dados inválidos). Somente os retornos com title "image_quality" são resultantes da validação de qualidade da imagem e portanto devem ser repassados ao usuário.

## Recuperação dos arquivos
> Recuperação de imagem

```shell
    curl "https://api.caas.qitech.app/face_recognition/image/f4b5337a-7b50-406e-8c8e-7d0e77b5aa02/file" \
         -H "Authorization: EXAMPLE_API_KEY"
```

Em qualquer momento é possível recuperar as imagens enviadas. Para isso, basta enviar  uma requisição **GET** adequadamente autenticada no endpoint:

`https://api.caas.qitech.app/face_recognition/image/{image_key}/file`

Onde image_key é o valor retornado durante o envio da imagem.

## Recuperação de arquivo processado
> Recuperação de imagem processada

```shell
    curl "https://api.caas.qitech.app/face_recognition/image/f4b5337a-7b50-406e-8c8e-7d0e77b5aa02/cropped_file" \
         -H "Authorization: EXAMPLE_API_KEY"
```
Após a associação de uma imagem a um cadastro ou uma validação, essa imagem será processada e uma nova imagem contendo apenas o rosto utilizado nas rotinas de reconhecimento facial será gerada.

Esta imagem está disponível para ser recuperada através de uma requisição **GET**, adequadamente autenticada, no endpoint:

`https://api.caas.qitech.app/face_recognition/image/{image_key}/cropped_file`

Onde image_key é o valor retornado durante o envio da imagem base.

## Recuperação dos meta-dados do arquivo
> Recuperação de meta dados

```shell
    curl "https://api.caas.qitech.app/face_recognition/image/f4b5337a-7b50-406e-8c8e-7d0e77b5aa02" \
         -H "Authorization: EXAMPLE_API_KEY"
```

Após o envio de uma imagem para a API, é possível recuperar os meta-dados da imagem utilizando o endpoint:

`https://api.caas.qitech.app/face_recognition/image/{image_key}`

Onde image_key é o valor retornado durante o envio da imagem.

---

# Introdução

URL: /documentation/caas/face_recognition/api/introduction

Bem vindo à API de Reconhecimento Facial da QI Tech! Você pode usar a nossa API para acessar os endpoints, cadastrar fotos de clientes e realizar o reconhecimento facial destes antes da execução de transações.

## Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso suporte e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

### Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

## Ambientes

Possuímos dois ambientes para os nossos clientes. As URLs base das APIs são:

* Produção - `https://api.caas.qitech.app/face_recognition/`
* Sandbox - `https://api.sandbox.caas.qitech.app/face_recognition/`

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.  
:::

## Somente HTTPS

Por questão de segurança, toda a comunicação com as APIs da QI Tech deve ser realizada utilizando a comunicação HTTPS. Para evitar que, por desatenção ou outro motivo, sejam feitas chamadas HTTP, este servidor somente disponibiliza a porta 443 com comunicação TLS 1.2. Chamadas realizadas utilizando outros protocolos serão automaticamente negadas.

---

# Registration

URL: /documentation/caas/face_recognition/api/registration

Antes da utilização do recurso de Validação Facial da API é necessário que seja feito o cadastro do cliente. Esta ação gerará uma entrada inicial no banco de dados que fornecerá uma imagem para ser usada como base durante a validação.

## Definição de Objeto

Request Body

```json
{        
    "registration_key": "ee37510e-4dfe-4b9c-b1f4-667288de2190",
    "document_number": "123.456.789-00",
    "image": {
        "image_key": "f1c0d2e1-f950-4360-896d-36588e443fc9",
        "file_size": 47407,
        "width_px": 0,
        "height_px": 0,
        "created_at": "2020-07-29T18:40:57Z",
    },
    "status": "indeterminate",
    "registration_status_events": [],
    "registration_date": "2020-07-29T18:40:57Z"
} 
```

Ao cadastrar um cliente, nossa API gerará um objeto JSON contendo todas as informações relacionadas a este cadastro. Esse objeto será utilizado como referência ao realizar o reconhecimento facial deste cliente antes de uma transação.

nome | tipo | descrição
:----: | :----: | ---------
registration_key | string | Chave do objeto Registration
document_number | string | CPF do cliente
image | image | Objeto que carrega as propriedades da imagem enviada no cadastro
status | string | Situação do cadastro do cliente
registration_status_events | registration_status_events | Objeto que carrega o histórico de modificação de status do cadastro
registration_date | datetime | Data de realização do cadastro em UTC

## Dinâmica dos Status - **status**
Uma vez feito o cadastro de um cliente, será retornado sob a flag **status** a situação deste cadastro. Os resultados possíveis são:

Resultado | Descrição
--------- | ---------
authentic | Este cadastro possui histórico de transações concluídas com sucesso
undefined | Este cadastro não possui histórico de fraudes nem histórico de transações concluído com sucesso
fraud | Este cadastro possui histórico de fraudes associado

## Criação de um Registration

Request Body: Envio simultâneo de imagem (Base64)

```json
{
    "document_number": "123.456.789-00",
    "image": "base_64_image_code",
}
```

Request Body: Envio antecipado da imagem

```json
{
    "document_number": "123.456.789-00",
    "image_key": "f1c0d2e1-f950-4360-896d-36588e443fc9",
}
```

Para efetuar o cadastro de um cliente, basta realizar o envio de um objeto JSON de cadastro com uma requisição **POST** no endpoint:

`https://api.caas.qitech.app/face_recognition/registration`

São suportados dois tipos objetos JSON de cadastro. Um em caso de envio prévio da imagem através do endpoint `/image`, e outro em caso de envio da imagem simultâneamente à requisição de cadastro.

nome | tipo | descrição
:----: | :----: | ---------
document_number | String | CPF do cliente
image | String | Base64 da imagem sem cabeçalhos ou informações adicionais
image_key | String | UUID4 retornado durante o envio da imagem pelo endpoint /image

Após o envio, será retornado um objeto Registration contendo os dados de cadastro do usuário.

**Atenção -** Ao efetuar o envio simultâneo da imagem com a realização do cadastro, esta será submetida aos mesmos testes de qualidade executados quando a imagem é enviada pelo endpoint `/image`. Assim, a imagem enviada está sujeita as mesmas regras descritas na sessão **Imagem** desta documentação.

## Atualização dos Status - **status**

Request Body

```json
{
    "registration_status": "fraud",
    "incident": "misappropriation",
    "event_date": "2029-08-25T13:34:12-03:00"                  
}
```

Para garantir a retroalimentação do banco de dados de fraudadores, é necessário informar ao sistema caso um cliente cometa qualquer tipo de fraude ou caso o cliente complete a sua primeira transação com sucesso.

Para isso, a atualização do status de cadastro de um cliente como fraudador deverá sem enviada uma requisição do tipo **PUT** para o endpoint:

`https://api.caas.qitech.app/face_recognition/registration/{registration_key}/status`

Os seguintes valores podem ser utilizados no campo **incident**, que indica o tipo de fraude cometida pelo cliente:

Enumerador | Descrição
--------- | ---------
misappropriation | Indivíduo realizou apropriação indébita sobre algum produto
misrepresentation | Indivíduo cadastrado sob documentos falsos ou de terceiros
successfull_transaction | Indivíduo completou uma transação com sucesso
status_restoration | Enumerador usado em casos que se deseja restaurar o status para **undefined**

## Recuperação de objeto

Response Body

```json
{        
    "registration_key": "ee37510e-4dfe-4b9c-b1f4-667288de2190",
    "document_number": "123.456.789-00",
    "image": {
        "image_key": "f1c0d2e1-f950-4360-896d-36588e443fc9",
        "file_size": 47407,
        "width_px": 0,
        "height_px": 0,
        "created_at": "2020-07-29T18:40:57Z",
    },
    "status": "fraud",
    "registration_status_events": [
        {
        "registration_status": "fraud",
        "incident": "misappropriation",
        "event_date": "2020-08-25T13:34:12Z"        
        }
    ],
    "registration_date": "2020-07-29T18:40:57Z"
}   
```

Em qualquer momento os dados de registro de um cliente poderão ser recuperados através de uma requisição **GET** ao endpoint:

`https://api.caas.qitech.app/face_recognition/registration/{registration_key}`

---

# Padrões

URL: /documentation/caas/face_recognition/api/standards

Para facilitar a integração e garantir a integridade da informação, foram definidos alguns padrões que são seguidos em toda a API.

## Data e Hora com Fuso Horário
> Alguns exemplos:

```
2019-10-15T22:35:12-03:00
2018-05-01T13:32:11+00:00
2019-05-01T00:00:00+00:00
```

É representada conforme a ISO 8601. Neste caso, o fuso-horário é colocado logo após o horário e deve representar o fuso do local onde aquele dado será valido. Por exemplo, se um aluguel estiver marcado para começar às 09:30 no aeroporto de Brasília, o horário enviado deverá ser representado por 09:30-03:00, se o aluguel estiver marcado para começar às 09:30 em Manaus, deverá ser representado por 09:30-04:00.

A máscara utilizada para validação é a seguinte:

`YYYY-MM-ddThh:mm:ss±hh:mm`

## Data e Hora sem Fuso Horario
> Alguns exemplos:

```
2019-10-15T22:35:12Z
2018-05-01T13:32:11Z
2019-05-01T00:00:00Z
```

É representada conforme a ISO 8601. Dados que independem de fuso-horário deverão ser enviados sem ele, sempre em UTC, com a letra Z indicando que este dado está em UTC. O seguinte formato, portanto, será validado:

`YYYY-MM-ddThh:mm:ssZ`

## Data
> Alguns exemplos

``` 
2019-10-15
2019-01-01
2017-03-20
```

No caso de campos que recebem somente data, uma data de nascimento, por exemplo, somente a data, sem nenhum horário deve ser enviada com o seguinte formato:

`YYYY-MM-dd`
 

## Documentos
Uma vez que os números de documento são bastante variados e muitos deles possuem caracteres que não se enquadram como numéricos, definem-se todos os números de documento como string. Outro bom motivo para definí-los como string é evitar que os zeros à esquerda desapareçam. Documentos previstos nesta página possuem uma máscara bem definida e estarão sujeitos a validação. O restante dos documentos, como RG, dada sua falta de padronização, não serão validados.

## CPF

> Exemplos de CPFs válidos contra a máscara definida:

```
123.456.789-12
321.987.543-23
111.283.333-00
```

> Exemplos de CPFs inválidos contra a máscara definida:

```
8.577.477-8
08.104.627/0001-23
123.456.789-1
23.456.789-01
```

O CPF é sempre definido como uma string e será validado contra a máscara:

`###.###.###-##`

---

# Validation

URL: /documentation/caas/face_recognition/api/validation

Para a execução da validação por reconhecimento facial de um cliente é necessário enviar uma foto de rosto junto do CPF de um cliente cadastrado. 

A partir dai, o registro desse usuário será buscado no sistema para, então, realizar uma validação 1:1 entre uma foto do cliente guardada no banco de dados e a imagem enviada.

## Definição do Objeto

Request Body

```json
{
    "validation_key": "ee37510e-4dfe-4b9c-b1f4-667288de2190",
    "document_number": "123.456.789-00",
    "image": {
        "image_key": "f1c0d2e1-f950-4360-896d-36588e443fc9",
        "file_size": 47407,
        "width_px": 0,
        "height_px": 0,
        "created_at": "2020-07-29T18:40:57Z",
    },
    "registration": {
        "registration_key": "903dcb34-2970-4ddf-add5-87463ba51d99",
        "registration_status": "authentic",
        "registration_date": "2020-07-29T18:40:57Z"
        },
    "similarity_ratio": "99",
    "validation_result": "pass",
    "validation_date": "2020-07-29T18:40:57Z"
}   
```

Todas as validações de cliente através de reconhecimento facial gerarão um objeto Validation. Caso desejado, este objeto poderá ser recuperado futuramente através do endpoint apropriado.

nome | tipo | descrição
:----: | :----: | ---------
validation_key | string | Chave do objeto Validation
document_number | string | CPF do cliente
image | image | Objeto que carrega as propriedades da imagem enviada na validação
registration | registration | Objeto que carrega as propriedades do registro que está sendo usado como referência na validação
similarity_ratio | integer | Razão de similaridade entre a imagem cadastrada e a imagem enviada
validation_result | string | Resultado da análise 1:1 realizada
validation_date | datetime | Data de realização da validação por reconhecimento facial em UTC

## Criação de Validation

Request Body: Envio simultâneo de imagem (Base64)

```json
{
    "document_number": "123.456.789-00",
    "image": "base_64_image_code",
}
```

Request Body: Envio antecipado da imagem

```json
{
    "document_number": "123.456.789-00",
    "image_key": "f1c0d2e1-f950-4360-896d-36588e443fc9",
}
```

Assim como no cadastro, também são aceitos dois formatos de JSON, um contendo o Base64 da imagem e outro contendo a **image_key** recebida no momento do envio da imagem pelo endpoint `/image`.

`https://api.caas.qitech.app/face_recognition/validation`

Após o envio, será retornado um objeto JSON contendo o resultado da análise juntamente da UUID que aponta para a imagem que foi enviada.

**Atenção -** Ao efetuar o envio simultâneo da imagem com a realização da validação por reconhecimento facial, esta será submetida aos mesmos testes de qualidade executados quando a imagem é enviada pelo endpoint `/image`. Assim, a imagem enviada está sujeita as mesmas regras descritas na sessão **Imagem** desta documentação.

## Dinamica dos Status - **validation_result**
Após executada a análise será enviada o resultado da análise sob a flag **validation_result**. Os resultados possíveis são:

Resultado | Descrição
--------- | ---------
match | Foto enviada corresponde ao usuário cadastrado
mismatch | Foto enviada não corresponde ao usuário cadastrado

## Recuperação de objeto

Response Body

```json
{
    "validation_key": "ee37510e-4dfe-4b9c-b1f4-667288de2190",
    "document_number": "123.456.789-00",
    "validation_image": {
        "image_key": "f1c0d2e1-f950-4360-896d-36588e443fc9",
        "file_size": 47407,
        "width_px": 0,
        "height_px": 0,
        "created_at": "2020-07-29T18:40:57Z",
    },
    "registration": {
        "registration_key": "903dcb34-2970-4ddf-add5-87463ba51d99",
        "registration_status": "authentic",
        "registration_date": "2020-07-29T18:40:57Z"
        },
    "similarity_ratio": "99",
    "validation_result": "pass",
    "validation_date": "2020-07-29T18:40:57Z"
}   
```

Em qualquer momento os dados de uma validação poderão ser recuperados através de uma requisição **GET** ao endpoint:

`https://api.caas.qitech.app/face_recognition/validation/{validation_key}`

---

# Coletando os Retornos

URL: /documentation/caas/face_recognition/flutter/collecting_response

O método `startFaceRecon` retorna um `Future `. Não é necessário realizar nenhuma decodificação manual de JSON — o plugin já entrega objetos Dart tipados.

## FaceReconReturnValues

```dart
class FaceReconReturnValues {
  final String imageKey;
  final String deviceScanSessionId;
}
```

| Atributo | Tipo | Descrição |
|----------|------|-----------|
|imageKey|String|Chave de identificação da imagem fornecida, que pode ser utilizada em qualquer outro serviço do sistema QI Tech. **Importante:** armazene este valor para enviar nas APIs de validação (ex.: API de Onboarding).|
|deviceScanSessionId|String|Chave de identificação da sessão de scan de dispositivo realizada internamente pelo SDK de Reconhecimento facial, que pode ser utilizada em qualquer outro serviço do sistema QI Tech.|

## FaceReconException

Em caso de falha, o método lança uma `FaceReconException` tipada:

```dart
class FaceReconException implements Exception {
  final int? statusCode;
  final String reason;
  final String description;
}
```

| Atributo | Tipo | Descrição |
|----------|------|-----------|
|statusCode|int?|Código HTTP do erro.|
|reason|String|Identificador do motivo do erro.|
|description|String|Descrição detalhada do erro.|

### Erros mais comuns

| reason | statusCode | description |
|--------|-----------|-------------|
|`INVALID_TOKEN`|401|`Authentication token expired or invalid` — o `clientSessionKey` é inválido ou expirou.|
|`USER_CANCELED`|0|`User canceled FaceRecon.` — o usuário interrompeu o fluxo antes de concluí-lo.|

## Exemplo de tratamento

```dart
try {
  final result = await plugin.startFaceRecon(
    CaaSEnvironment.sandbox,
    clientSessionKey,
  );

  print('Image key: ${result.imageKey}');
  print('Device Scan Session Id: ${result.deviceScanSessionId}');
} on FaceReconException catch (e) {
  print('Error executing FaceRecon:');
  print('Status: ${e.statusCode}');
  print('Reason: ${e.reason}');
  print('Description: ${e.description}');
} catch (e) {
  print('An unknown error occurred: $e');
}
```

---

# Compatibilidade

URL: /documentation/caas/face_recognition/flutter/compatibility

O plugin `flutter_kyc_qitech` exige as seguintes versões mínimas:

| Configuração | Versão mínima |
|------------|--------------|
|Flutter|3.3.0|
|Dart SDK|3.2.3|
|iOS|15.5|
|Android API Level|35 (Android 15 Vanilla Ice Cream)|
|Gradle|8.6.0|
|Android Gradle Plugin (AGP)|8.7|
|Kotlin|2.0.21 (recomendado)|
|Datadog SDK nativo (iOS, trazido pelo plugin)|3.x|
|MLKit FaceDetection (iOS, caso já utilizado no seu app)|8.x|

## Versão atual do plugin

| Plugin | Versão |
|--------|--------|
|`flutter_kyc_qitech`|`^5.3.0`|

:::warning Atenção
Nossos SDKs de iOS não suportam ser compilados para simuladores em máquinas com arquitetura **arm64** (MacBooks M1/M2/M3/M4), a menos que o **Rosetta** esteja ativo, traduzindo a arquitetura x86_64 para arm64. Recomendamos o uso de dispositivos físicos para testes.
:::

---

# Implementação

URL: /documentation/caas/face_recognition/flutter/example

O método `startFaceRecon` abre o fluxo nativo de prova de vida, envia a imagem capturada para a API de Reconhecimento facial da QI Tech e devolve a chave da imagem processada.

## Pré-requisito: obtendo o Client Session Key

O método `startFaceRecon` exige um `clientSessionKey`. Essa chave é temporária e deve ser gerada no seu backend por meio de uma requisição server-to-server para a nossa API, antes de chamar o método do SDK.

### Endpoint

| Ambiente | URL |
|----------|-----|
| **Sandbox** | `https://api.sandbox.zaig.com.br/face_recognition/client_session` |
| **Produção** | `https://api.zaig.com.br/face_recognition/client_session` |

### Requisição

**Method:** `POST`

**Headers:**

```json
{
  "Authorization": "YOUR_FACE_RECON_API_KEY"
}
```

**Body (Opcional, mas recomendado):**

```json
{
  "user_id": "unique_user_identifier"
}
```

> **Importante:** O campo `user_id` é **altamente recomendado** para medidas de segurança e antifraude. Use o CPF do cliente caso tenha acesso a essa informação.

### Resposta

A resposta bem-sucedida conterá o `client_session_key` que deve ser passado para o método `startFaceRecon`.

```json
{
  "client_session_key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

:::danger Aviso Importante!
A API Key de Reconhecimento facial nunca deve ser embarcada no aplicativo. A requisição acima deve partir exclusivamente do seu backend.
:::

## Assinatura do método

```dart
Future<FaceReconReturnValues> startFaceRecon(
  CaaSEnvironment environment,
  String clientSessionKey, {
  FaceReconOptions? options,
})
```

Os dois primeiros parâmetros são posicionais e obrigatórios. As customizações são opcionais e passadas pelo parâmetro nomeado `options`, descrito em [O objeto FaceReconOptions](/documentation/caas/face_recognition/flutter/face_recon_options).

## Exemplo completo

```dart
import 'dart:convert';
import 'dart:io';
import 'package:http/http.dart' as http;
import 'package:flutter_kyc_qitech/flutter_kyc_qitech.dart';

final _qitechFlutterKycPlugin = FlutterKycQitech();

// Etapa 1: obter o clientSessionKey por meio do seu backend
Future<String?> fetchClientSessionKey() async {
  final response = await http.post(
    Uri.parse('<FACE_RECON_API_URL>'),
    headers: {
      HttpHeaders.authorizationHeader: '<API_KEY>',
      HttpHeaders.contentTypeHeader: 'application/json',
    },
    body: jsonEncode({'user_id': '<USER_IDENTIFICATION>'}),
  );

  if (response.statusCode == 200) {
    final data = jsonDecode(response.body);
    return data['client_session_key'] as String?;
  }
  return null;
}

// Etapa 2: iniciar o SDK com a chave obtida
Future<void> startFaceRecon() async {
  final clientSessionKey = await fetchClientSessionKey();

  if (clientSessionKey == null) {
    print('Failed to fetch clientSessionKey');
    return;
  }

  try {
    final result = await _qitechFlutterKycPlugin.startFaceRecon(
      CaaSEnvironment.sandbox,
      clientSessionKey,
      options: FaceReconOptions(
        sessionId: '<SESSION_ID>',
        documentNumber: '111.111.111-11',
        fontColor: '#FFFFFF',
        backgroundColor: '#000000',
        fontFamily: CaaSFontFamily.futura,
        showIntroductionScreens: true,
        showSuccessScreen: true,
        showInvalidTokenScreen: true,
        audioConfiguration: FaceReconAudioConfiguration.enable,
        onboardingTextConfiguration: OnboardingTextConfiguration(
          onboardingTitle: 'Conselhos relevantes',
          onboardingFirstLabel: 'Esteja com o rosto visível',
          onboardingSecondLabel: 'Encaixe seu rosto no oval',
          onboardingThirdLabel: 'Retire acessórios que cubram o rosto',
        ),
        logLevel: CaaSLogLevel.debug,
      ),
    );

    print('Image key: ${result.imageKey}');
    print('Device Scan Session Id: ${result.deviceScanSessionId}');
  } on FaceReconException catch (e) {
    print('Error executing FaceRecon:');
    print('Status: ${e.statusCode}');
    print('Reason: ${e.reason}');
    print('Description: ${e.description}');
  }
}
```

:::info **Atenção**
Habilite o suporte às orientações _Portrait_ e _Landscape Right_ em sua aplicação para o funcionamento correto do SDK nativo de iOS.
:::

## Aplicativo de exemplo

O repositório do plugin contém um aplicativo de exemplo pronto para execução, em `flutter_kyc_qitech/example`, que demonstra o uso dos três SDKs. Para executá-lo, crie um arquivo `.env` na pasta `example` com as credenciais abaixo e rode `flutter pub get` seguido de `flutter run` com um dispositivo físico conectado:

```
FACERECON_API_URL_SANDBOX=''
FACERECON_API_KEY_SANDBOX=''
OCR_MOBILE_TOKEN_SANDBOX=''
DEVICE_SCAN_API_URL_SANDBOX=''
DEVICE_SCAN_API_KEY_SANDBOX=''
```

Caso ainda não tenha recebido as suas credenciais, entre em contato com o suporte.caas@qitech.com.br .

---

# O objeto FaceReconOptions

URL: /documentation/caas/face_recognition/flutter/face_recon_options

## Parâmetros de startFaceRecon

| Parâmetro | Tipo | Função | Obrigatório |
|------------|--------------|--------------|--------------|
|environment|CaaSEnvironment|Enumerador utilizado para configurar o ambiente de execução para `sandbox` ou `production`.|Sim.|
|clientSessionKey|String|Chave temporária de autenticação obtida por meio de requisição server-to-server à API de Reconhecimento facial. Veja [Implementação](/documentation/caas/face_recognition/flutter/example).|Sim.|
|options|FaceReconOptions?|Objeto opcional com as customizações visuais, textuais e de comportamento do SDK.|Não.|

## FaceReconOptions

Todos os campos são opcionais. Quando um campo não é informado, o SDK nativo aplica o seu valor padrão.

| Parâmetro | Tipo | Função | Padrão |
|------------|--------------|--------------|--------------|
|sessionId|String?|Chave que identifica a sessão iniciada no SDK. É utilizada para rastrear todo o fluxo percorrido pelo usuário através de logs. Aceita até 255 caracteres.|Gerado internamente.|
|documentNumber|String?|Número do documento do usuário (CPF), utilizado exclusivamente para identificação antifraude.|Não enviado.|
|fontColor|String?|Cor da fonte e dos ícones das telas do SDK, em formato hexadecimal (ex.: `"#FFFFFF"`).|`"#000000"`|
|backgroundColor|String?|Cor de fundo das telas do SDK, em formato hexadecimal (ex.: `"#000000"`).|`"#FFFFFF"`|
|fontFamily|CaaSFontFamily?|Fonte utilizada nas telas do SDK.|`CaaSFontFamily.openSans`|
|showIntroductionScreens|bool?|Quando `false`, desativa as telas de introdução à prova de vida.|`true`|
|showSuccessScreen|bool?|Quando `false`, desativa a tela de sucesso exibida após a captura.|`true`|
|showInvalidTokenScreen|bool?|Quando `false`, desativa a tela exibida quando o `clientSessionKey` é inválido ou expirou.|`true`|
|audioConfiguration|FaceReconAudioConfiguration?|Configura o guiamento por voz, que narra as instruções de captura em tempo real.|`FaceReconAudioConfiguration.disable`|
|onboardingTextConfiguration|OnboardingTextConfiguration?|Customiza os textos da tela de onboarding.|Textos padrão do SDK.|
|logLevel|CaaSLogLevel?|Nível de verbosidade dos logs do SDK.|`CaaSLogLevel.debug`|

:::info **Atenção**
A partir da versão **5.0.0** do plugin, o campo `documentNumber` não dispara mais o registro de face — ele é utilizado somente para identificação antifraude.
:::

## OnboardingTextConfiguration

| Parâmetro | Tipo | Função |
|------------|--------------|--------------|
|onboardingTitle|String?|Título da tela de onboarding.|
|onboardingFirstLabel|String?|Primeira instrução exibida ao usuário.|
|onboardingSecondLabel|String?|Segunda instrução exibida ao usuário.|
|onboardingThirdLabel|String?|Terceira instrução exibida ao usuário.|

```dart
OnboardingTextConfiguration(
  onboardingTitle: 'Conselhos relevantes',
  onboardingFirstLabel: 'Esteja com o rosto visível',
  onboardingSecondLabel: 'Encaixe seu rosto no oval',
  onboardingThirdLabel: 'Retire acessórios que cubram o rosto',
)
```

## Enumeradores

### CaaSEnvironment

```dart
enum CaaSEnvironment {
  production,
  sandbox,
}
```

### CaaSFontFamily

```dart
enum CaaSFontFamily {
  jakarta,       // apenas iOS
  futura,        // iOS e Android
  verdana,       // iOS e Android
  trebuchetMs,   // apenas iOS
  tamilsangamMn, // apenas iOS
  openSans,      // iOS e Android
  helvetica,     // apenas Android
  poppins,       // apenas Android
  roboto,        // apenas Android
  systemFont,    // apenas iOS
}
```

:::info **Atenção**
A disponibilidade das fontes varia por plataforma. Caso uma fonte não suportada seja informada, a plataforma utiliza a sua fonte padrão. Para consistência entre iOS e Android, utilize `futura`, `verdana` ou `openSans`.
:::

### FaceReconAudioConfiguration

```dart
enum FaceReconAudioConfiguration {
  enable,        // exibe o botão de áudio, com a narração iniciando desligada
  disable,       // desativa a narração e oculta o botão
  accessibility, // exibe o botão com a narração iniciando ligada quando há recursos de acessibilidade ativos
}
```

### CaaSLogLevel

```dart
enum CaaSLogLevel {
  trace,
  debug,
  log,
  info,
  warn,
  error,
}
```

---

# Instalação

URL: /documentation/caas/face_recognition/flutter/installation

## Instalando o plugin

Execute o comando abaixo na raiz do seu projeto Flutter:

```bash
flutter pub add flutter_kyc_qitech
```

O comando instala a versão mais recente e adiciona a dependência ao seu `pubspec.yaml`:

```yaml
dependencies:
  flutter_kyc_qitech: ^5.3.0
```

Em seguida, baixe as dependências:

```bash
flutter pub get
```

## Importação

```dart
import 'package:flutter_kyc_qitech/flutter_kyc_qitech.dart';
```

E instancie o plugin:

```dart
final _qitechFlutterKycPlugin = FlutterKycQitech();
```

## Configuração do Android

### 1. Repositório Maven da QI Tech

Adicione a referência do repositório Android da QI Tech no `build.gradle` do projeto:

```gradle
allprojects {
    repositories {
        maven { url 'https://sdks.qitech.com.br/' }
        ...
    }
}
```

### 2. AdMob

Inicialize o serviço de AdMob adicionando o seguinte código no `AndroidManifest.xml`:

```xml
<meta-data
    android:name="com.google.android.gms.ads.APPLICATION_ID"
    android:value="<ADMOB_APP_ID>"/>
```

Caso não possua um `ADMOB_APP_ID`, entre em contato com o suporte.caas@qitech.com.br .

## Configuração do iOS

### 1. Permissão de câmera

Adicione a entrada `NSCameraUsageDescription` ao `Info.plist` do seu aplicativo, com o motivo pelo qual o app precisa de acesso à câmera:

```xml
<key>NSCameraUsageDescription</key>
<string>Precisamos da câmera para capturar a sua selfie</string>
```

### 2. Source do repositório iOS da QI Tech

Adicione as seguintes sources no topo do seu `Podfile`:

```ruby
source 'https://cdn.cocoapods.org/'
source 'https://github.com/QITechSDKs/iOS.git'
```

### 3. Frameworks estáticos

Por padrão, o CocoaPods constrói bibliotecas estáticas em vez de frameworks. Adicione ao seu `Podfile`:

```ruby
use_frameworks! :linkage => :static
```

### 4. Estabilidade de módulo

As dependências nativas da QI Tech exigem que o `BUILD_LIBRARY_FOR_DISTRIBUTION` esteja habilitado para os alvos do Datadog. Adicione o `post_install` abaixo (ou incorpore ao seu `post_install` existente):

```ruby
post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
    target.build_configurations.each do |config|
      config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'NO'
      # A linha abaixo só é necessária para compilar em simuladores (com Rosetta ativo)
      config.build_settings["EXCLUDED_ARCHS[sdk=iphonesimulator*]"] = "arm64"
    end
    if ['DatadogCore', 'DatadogInternal', 'DatadogCrashReporting', 'DatadogLogs'].include?(target.name)
      target.build_configurations.each do |config|
        config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.5'
        config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
      end
    end
  end
end
```

### 5. Instalação dos pods

Na pasta `ios` do seu aplicativo Flutter, execute:

```bash
cd ios
pod install
```

ou, alternativamente, através do Flutter:

```bash
flutter build ios
```

:::warning Atenção
Se o seu aplicativo já utiliza **Datadog**, use a versão mais recente dentro do major `3.x` (`datadog_flutter_plugin` 3.x). Se utiliza o **FaceDetection do MLKit**, use a versão mais recente dentro do major `8.x`.
:::

---

# Introdução

URL: /documentation/caas/face_recognition/flutter/introduction

Bem vindo ao manual de integração do SDK de Reconhecimento facial da QI Tech em Flutter! O plugin `flutter_kyc_qitech` expõe, por meio de uma interface Dart, os SDKs nativos de Android (Kotlin) e iOS (Swift) da QI Tech. Você deve utilizá-lo para realizar a prova de vida (liveness) do seu cliente diretamente do seu aplicativo Flutter e referenciar a imagem capturada, através de uma chave, nos demais produtos do sistema QI Tech.

:::info **Plugin único para os três SDKs**

O `flutter_kyc_qitech` entrega os três SDKs de Risk Solutions no mesmo pacote: `startFaceRecon` (reconhecimento facial), `startOcr` (OCR) e `startDeviceScan` (scan de dispositivo). Ao instalá-lo, os três métodos ficam disponíveis — não é necessário instalar plugins adicionais.
:::

## Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso [suporte](mailto:suporte.caas@qitech.com.br) e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

### Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

## Ambientes

Possuímos dois ambientes para os nossos clientes. A seleção é realizada por meio do enumerador `CaaSEnvironment`, repassado como primeiro parâmetro do método `startFaceRecon`. No momento, os seguintes ambientes estão disponíveis:

* Produção - `CaaSEnvironment.production`
* Sandbox - `CaaSEnvironment.sandbox`

Cada ambiente exige uma API Key diferente para a geração do `clientSessionKey`.

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.
:::

## Integração com Device Scan

O serviço de Reconhecimento facial realiza automaticamente uma chamada interna ao Device Scan. Por isso, o retorno de sucesso inclui o campo `deviceScanSessionId`, que identifica a sessão de scan de dispositivo realizada internamente e pode ser utilizada de forma integrada em outros serviços do ecossistema QI Tech.

## Próximos passos

1. [Compatibilidade](/documentation/caas/face_recognition/flutter/compatibility) — versões mínimas de Flutter, Dart, iOS e Android.
2. [Instalação](/documentation/caas/face_recognition/flutter/installation) — instalação do plugin e configuração nativa de Android e iOS.
3. [Implementação](/documentation/caas/face_recognition/flutter/example) — obtenção do `clientSessionKey` e exemplo completo da chamada `startFaceRecon`.
4. [O objeto FaceReconOptions](/documentation/caas/face_recognition/flutter/face_recon_options) — todos os parâmetros de customização.
5. [Coletando os Retornos](/documentation/caas/face_recognition/flutter/collecting_response) — estrutura de resposta e tratamento de erros.

---

# Coletando os Retornos do SDK

URL: /documentation/caas/face_recognition/ios/collecting_response

Para obter as respostas do SDK , você deve implementar o delegate **QITechIosFaceRecognitionControllerDelegate** em seu controller, conforme exemplo ao lado.

```swift
class ViewController: UIViewController, QITechIosFaceRecognitionControllerDelegate {
    
    // Do something if QI Tech FaceRecognition's SDK succesfully collected document picture
    func qitechIosFaceRecognitionController(_ faceRecognitionViewController: QITechIosFaceRecognitionController, didFinishWithResults response: QITechIosFaceRecognitionControllerResponse) {
    
    }
    
    // Do something if QI Tech FaceRecognition's SDK found any error when collecting document picture
    func qitechIosFaceRecognitionController(_ faceRecognitionViewController: QITechIosFaceRecognitionController, didFailWithError error: QITechIosFaceRecognitionControllerError) {
        
    }
    
    // Do something if the user canceled the picture collection on any steps
    func qitechIosFaceRecognitionControllerDidCancel(_ faceRecognitionViewController: QITechIosFaceRecognitionController) {

    }
}
```

## QITechIosFaceRecognitionControllerResponse

A classe **QITechIosFaceRecognitionControllerResponse** é utilizada para que você possa receber a resposta do SDK da QI Tech.

Na tabela abaixo você encontra o detalhe de todas as propriedades desta classe:

### Propriedades

:::info Aviso: 
Integração com Device Scan A partir da versão 6.1.0, o serviço de Face Recognition passa a realizar automaticamente uma chamada interna ao Device Scan. Com isso, o retorno de sucesso incluirá o campo `DeviceScanSessionId`. Esta chave identifica a sessão de scan de dispositivo realizada internamente e pode ser utilizada de forma integrada em outros serviços do ecossistema QI Tech. 
:::

| Nome | Tipo | Descrição |
|------|------|-----------|
| `FaceRecognitionKey` | `String` | Identificador único da foto do rosto armazenado na QI Tech. **Importante:** Armazene este valor para enviar nas APIs de validação (ex.: API de Onboarding). |
`DeviceScanSessionId` | `String` | Identificador único da sessão de scan de dispositivo realizada internamente. |

## QITechIosFaceRecognitionControllerError

A classe **QITechIosFaceRecognitionControllerError** é acionada quando ocorre um erro que leva ao encerramento do SDK.

:::danger Aviso Importante! 
A partir da versão **5.0.0**, a estrutura de erros foi reformulada para fornecer informações mais detalhadas e diagnósticas.
:::
#### Principais mudanças:

1. **Novos tipos de erro**: `InvalidToken` (substitui `InvalidMobileToken`)
2. **Novas propriedades disponíveis**:
   - `status_code`: Código HTTP do erro
   - `reason`: Identificador do motivo do erro
   - `description`: Descrição detalhada do erro

### Estrutura de Erro (SDK 5.0.0+)

#### Exemplo: InvalidToken

```swift
{
    status_code: 401,
    reason: "INVALID_TOKEN",
    description: "Authentication token expired or invalid"
}
```

## Tipos de Erro

### SDK 5.0.0 e posteriores

| Erro | Status Code | Descrição |
|------|-------------|-----------|
| `InvalidToken` | 401 | Token de autenticação expirado ou inválido (substitui `InvalidMobileToken`) |

### Versões anteriores à 5.0.0

| Classe de Erro | Descrição |
|----------------|-----------|
| `InvalidMobileToken` | MobileToken enviado nas configurações é inválido *(substituído por `InvalidToken` na v5.0.0+)* |
| `MissingPermission` | Alguma das permissões necessárias não foi concedida |
| `NetworkFailure` | Perda de conexão com a internet durante a validação |
| `ServerFailure` | Resposta de erro do servidor da QI Tech |
| `MissingStorage` | Espaço de armazenamento insuficiente |
| `LowImageQuality` | Qualidade da imagem insuficiente para validação |

---

# QITechIosFaceRecognitionConfiguration

URL: /documentation/caas/face_recognition/ios/configuration

## SDK 7.0.0 e posteriores
```swift
let onboardingTextConfiguration = OnboardingTextConfiguration(
        onboardingTitle: "Conselhos relevantes",
        onboardingFirstLabel: "Esteja com o rosto visível",
        onboardingSecondlabel: "Encaixe seu rosto no oval",
        onboardingThirdLabel: "Retire acessórios que cubram o rosto"
)

let faceRecognitionConfig = QITechIosFaceRecognitionConfiguration(
        environment: QITechIosFaceRecognitionEnvironment.sandbox,
        clientSessionKey: clientSessionKey,
        sessionId: "7d8c6f9a-f222-450d-9501-a07c68eb2388",
        documentNumber: "123.456.789-00",
        fontColor: "#337DFF",
        backgroundColor: "#C9CCD3",
        fontFamily: .open_sans,
        showIntroductionScreens: true,
        showSuccessScreen: true,
        showInvalidTokenScreen: false,
        audioConfiguration: AudioConfiguration.enable,
        onboardingTextConfiguration: onboardingTextConfiguration,
        logLevel: .debug
)
```

**Versões anteriores à v7.0.0**
```swift
let visualConfiguration = VisualConfiguration()
        visualConfiguration.setOnboarding(onboardingFilePath: Bundle.main.path(forResource: "onboarding", ofType: "png")!, onboardingWidth: 200)

let textConfiguration = TextConfiguration()
        textConfiguration.setCustomText(on: .onboardingTitle, text: "Para tirar uma boa foto:")
        textConfiguration.setCustomText(on: .onboardingFirstLabel, text: "- Vá para um local iluminado")
        textConfiguration.setCustomText(on: .onboardingSecondLabel, text: "- Retire adereços e mostre bem o rosto")
        textConfiguration.setCustomText(on: .onboardingThirdLabel, text: "- Insira seu rosto na moldura, aguardando que fique verde para realizar a captura")

let faceRecognitionConfig = QITechIosFaceRecognitionConfiguration(environment: QITechIosFaceRecognitionEnvironment.Sandbox,
                                            clientSessionKey: clientSessionKey,
                                            sessionId: "7d8c6f9a-f222-450d-9501-a07c68eb2388",
                                            backgroundColor: "#C9CCD3",
                                            fontColor: "#337DFF",
                                            fontFamily: .open_sans,
                                            showIntroductionScreens: true,
                                            showSuccessScreen: false,
                                            showInvalidTokenScreen: true,
                                            activeFaceLiveness: true,
                                            audioConfiguration: AudioConfiguration.Enable,
                                            logLevel: .debug
                                            )

faceRecognitionConfig.setVisualConfiguration(visualConfiguration: visualConfiguration)
faceRecognitionConfig.setTextConfiguration(textConfiguration: textConfiguration)
```

A classe **QITechIosFaceRecognitionConfiguration** é utilizada para que você possa configurar ambiente, credenciais, aspectos visuais e textuais ou seja, todas as configurações necessárias para personalização e funcionamento do SDK.

Na tabela abaixo você encontra o detalhe de todos os argumentos que devem ser utilizados na sua instanciação:

| nome                    |               tipo                | descrição                                                                                                                                                                                                                                                                                                                                   |
| ----------------------- | :-------------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| environment             | QITechIosFaceRecognitionEnvironment | _(obrigatório)_ Enumerador que descreve o ambiente.                                                                                                                                                                                                                                                                                         |
| clientSessionKey        |              string               | _(obrigatório)_ Token enviado pela API face recognition para autenticação do SDK.                                                                                                                                                                                                                                                                        |
| sessionId               |              string               | _(opcional)_ ID único usado para rastrear todo fluxo percorrido pelo usuário na execução da FaceRecon através de logs. Este campo aceita até 255 caracteres.                                                                                                                                                                                |
| documentNumber          |              string               | _(opcional)_ Utilizado para identificação do usuário para anti-fraude e segurança interna |
| fontColor               |              string               | _(opcional)_ Hexadecimal da cor da fonte. Caso não seja informada o padrão é #1C49A5.                                                                                                                                                                                                                                                       |
| backgroundColor         |              string               | _(opcional)_ Hexadecimal da cor de fundo das telas. Caso não seja informada o padrão é #FCFCFC.                                                                                                                                                                                                                                             |
| fontFamily              |            FontFamily             | _(opcional)_ Familia da fonte. Caso não seja informada o padrão é .open_sans. Fontes disponíveis: .open_sans, .futura, .verdana, .trebuchetms, .tamilsangammn e .system_font.                                                                                                                                                               |
| showIntroductionScreens |             booleano              | _(opcional)_ Flag que indica se as telas de introdução, com instruções de como a foto deve ser capturada, devem ser mostradas. Caso não seja informada o padrão é _true_.                                                                                                                                                                   |
| showSuccessScreen       |             booleano              | _(opcional)_ Flag que indica se a tela de sucesso, com a mensagem de sucesso na captura, deve ser mostrada. Caso não seja informada o padrão é _true_.                                                                                                                                                                                      |
| showInvalidTokenScreen  |             booleano              | _(opcional)_ Flag que indica se a tela de falha de autenticação, com a mensagem de expiração de token, deve ser mostrada. Caso não seja informada o padrão é _true_. |
| audioConfiguration      |        AudioConfiguration         | _(opcional)_ Configura o guiamento por voz do SDK, que narra as instruções de captura em tempo real. As configurações aceitas são: _Enable_, que exibe o botão de ligar/desligar áudio com a narração iniciando desligada; _Disable_, que desativa a narração e oculta o botão; e _Accessibility_, que exibe o botão com a narração iniciando ligada quando o dispositivo possui recursos de acessibilidade ativos. Com o VoiceOver ativo, as instruções completas são entregues pelo próprio leitor de telas. |
| onboardingTextConfiguration | OnboardingTextConfiguration | _(opcional)_ Permite configurar os textos da tela de instruções |
| logLevel                |             LogLevel              | _(opcional)_ Utilizado para customizar o nível de verbosidade dos logs do SDK. Níveis disponíveis: LogLevel.debug, LogLevel.info, LogLevel.warn, LogLevel.error e LogLevel.trace. Caso não seja informada o padrão é LogLevel.debug. |

Na tabela abaixo você encontra todos os métodos aceitos pela instância para configuração:
:::warning
__DEPRECADO__ A PARTIR DA **v7.0.0**!
:::

| método                 |                                                                                                                     argumentos                                                                                                                     | descrição                                                                                     |
| ---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | --------------------------------------------------------------------------------------------- |
| setVisualConfiguration |                                                                 visualConfiguration : VisualConfiguration                                                             | _(opcional)_ Classe que permite a modificação das imagens exibidas durante a execução do SDK; |
| setTextConfiguration   |                                                                                                       textConfiguration : TextConfiguration                                                                                                        | _(opcional)_ Classe que permite a modificação dos textos exibidos durante a execução do SDK;  |
| setDocumentNumber      |                                                    Utilizado para definir o número do documento do usuário. Este campo aceita 14 caracteres do CPF formatado da seguinte maneira 000.000.000-00                                                    | Sim em todas as chamadas caso use a validação 1:1 em algum momento.                                                                                         |
| setValidation          | Utilizado para definir se o SDK deve ou não realizar a validação 1:1 com a selfie do usuário. Na primeira sessão do usuário esta flag deve estar **obrigatoriamente false**. Esta função depende necessita do método setDocumentNumber preenchido. | Não. O padrão é _false_.                                                                      |

---

# Introdução

URL: /documentation/caas/face_recognition/ios/introduction

Bem vindo ao SDK iOS de Reconhecimento Facial da QI Tech. Este SDK realiza a captura de face e seu envio para a API de Face Recognition da QI Tech . Você pode utilizá-lo para capturar através do seu aplicativo uma imagem do rosto de um cliente e referenciá-lo através de uma chave nos demais produtos do sistema QI Tech.

## Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso [suporte](mailto:suporte.caas@qitech.com.br) e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

### Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.  
:::

---

# Importando o SDK

URL: /documentation/caas/face_recognition/ios/native_swift

## Remotamente

> Iniciando a instalação

```shell
  pod init
```

Nosso SDK pode ser importado utilizando CocoaPods.

| SDK              | Versão atual                         |
| ---------------- | ------------------------------------ |
| QITechIosFaceRecon | `pod 'QITechIosFaceRecon', '~> 8.2.0'` |

:::info iOS Minimum Deployment Target
15.5
:::

:::danger Utilização de simuladores em MacBooks com chip arm64
Atualmente, nosso SDK de FaceRecon para iOS infelizmente não suporta ser compilada para simuladores que estejam rodando
em um MacBook com **chip de arquitetura arm64** (M1/M2/M3/M4), **a não ser que seja utilizado Rosetta**, que faz a tradução
da arquitetura x86_64 para arm64.
:::

Para iniciar a instalação, execute o comando ao lado na pasta raiz do seu projeto.

> Adicionando a source no podfile

```ruby
   source 'https://github.com/QITechSDKs/iOS.git'
   source 'https://cdn.cocoapods.org/'
```

O próximo passo é adicionar no arquivo `podfile` o source da QI Tech.

> Adicionando o pod no podfile

```ruby
  pod 'QITechIosFaceRecon', '~> <version>'
```

Por fim, basta adicionar o nome do `pod` de acordo com o formato ao lado.

:::danger Atenção: 
Mudança de Arquitetura (v6.0.0+) A partir da versão 6.0.0, o SDK passou a ser distribuída exclusivamente de forma estática. No seu Podfile, você deve utilizar a configuração :linkage => :static. 
:::

> Exemplo de podfile (Versão 6.0.0 ou superior)

```ruby
  source 'https://github.com/QITechSDKs/iOS.git'
  source 'https://cdn.cocoapods.org/'
  target 'ExampleApp' do
    use_frameworks! :linkage => :static
    pod 'QITechIosFaceRecon', '~> 8.2.0'
  end

  post_install do |installer|
    installer.pods_project.targets.each do |target|
      if ['DatadogCore', 'DatadogInternal', 'DatadogCrashReporting', 'DatadogLogs'].include?(target.name)
        target.build_configurations.each do |config|
          config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.5'
          config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
        end
      end
    end
  end
```

> Exemplo de podfile (Versão Anteriores) 

```ruby
  source 'https://github.com/QITechSDKs/iOS.git'
  source 'https://cdn.cocoapods.org/'
  target 'ExampleApp' do
    use_frameworks!
    pod 'QITechIosFaceRecon', '~> 5.0.0'
  end

  post_install do |installer|
    installer.pods_project.targets.each do |target|
      if ['DatadogCore', 'DatadogInternal', 'DatadogCrashReporting', 'DatadogLogs'].include?(target.name)
        target.build_configurations.each do |config|
          config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.5'
          config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
        end
      end
    end
  end
```

:::warning Atenção
Ao integrar dependências no iOS, pode surgir a necessidade de usar linkagem estática para algumas bibliotecas e dinâmica para outras. Essa configuração é relevante para garantir compatibilidade, evitar erros de build e otimizar o desempenho do projeto. 
:::

### Linkagem Híbrida de Dependências (caso necessário)
A necessidade de linkagem híbrida surge porque algumas bibliotecas têm requisitos específicos, sendo que algumas precisam de linkagem estática para evitar conflitos internos e duplicação de símbolos e outras dependências podem precisar linkagem dinâmica, pois são projetadas para modularidade e compartilhamento entre projetos.

Diferenças Entre Linkagem Estática e Dinâmica
* Estática (static_framework): O código da biblioteca é incorporado diretamente no binário final, reduzindo o tempo de carregamento em runtime e eliminando dependências externas durante a execução.
* Dinâmica (dynamic_framework): A biblioteca é carregada em tempo de execução como um arquivo separado. Isso reduz o tamanho do binário final e facilita atualizações/modificações independentes.

> Configurando linkagem híbrida no Podfile

```ruby
...

use_frameworks! :linkage => :dynamic # CONFIGURANDO O MODO PADRÃO DE LINKAGEM PARA DINÂMICO

...

static_frameworks = ['framework_1', 'framework_2', ...] # INCLUIR TODAS AS DEPENDÊNCIAS QUE PRECISAM SER LINKADAS DE MODO ESTÁTICO
pre_install do |installer|
  installer.pod_targets.each do |pod|
    if static_frameworks.include?(pod.name)
      def pod.static_framework?;
        true
      end
      def pod.build_type;
        Pod::BuildType.static_framework
      end
    end
  end
end
```

> Instalando as dependências

```shell
  pod install
```

Por fim, execute o comando `pod install` para baixar e instalar as dependências.

## Permissões Necessárias

Para que o SDK possa acessar os recursos do dispositivo para coletar a selfie do usuário, é necessário que sejam solicitadas permissões ao usuário.

No arquivo **info.plist**, adicione as permissões abaixo:

| Permissão                          | Motivo                                             |
| ---------------------------------- | -------------------------------------------------- |
| Privacy - Camera Usage Description | Acesso à câmera para capturar a selfie do usuário. |

## Iniciando o SDK

:::danger Aviso Importante!
A partir da versão 5.0.0, o sistema de autenticação foi atualizado para usar **clientSessionKey** em vez de **mobileToken**. Além disso, foram adicionadas novas opções de configuração para telas de feedback.
:::

### Obtendo o Client Session Key

Antes de configurar o SDK, você deve gerar um **clientSessionKey** temporário através de uma requisição server-to-server para a nossa API de face recognition.

### Endpoint

| Ambiente | URL |
|----------|-----|
| **Sandbox** | `https://api.sandbox.zaig.com.br/face_recognition/client_session` |
| **Produção** | `https://api.zaig.com.br/face_recognition/client_session` |

### Requisição

**Method:** `POST`

**Headers:**
```json
{
  "Authorization": "YOUR_FACE_RECON_API_KEY"
}
```

**Body (Opcional, mas recomendado):**
```json
{
  "user_id": "unique_user_identifier"
}
```

> **Importante:** O campo `user_id` é **altamente recomendado** para medidas de segurança e antifraude. Use um identificador único do usuário da sua aplicação.

### Resposta

A resposta bem-sucedida conterá o `client_session_key` que deve ser passado para a configuração do SDK.

```json
{
  "client_session_key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

### Exemplo de inicialização do SDK

```swift

import QITechIosFaceRecognition

class ViewController: UIViewController, QITechIosFaceRecognitionControllerDelegate {

    var qitechFaceRecognitionConfiguration : QITechIosFaceRecognitionConfiguration?

    override func viewDidLoad() {
        super.viewDidLoad()
        self.setupFaceRecognition()
    }

    func setupFaceRecognition() -> Void {
      let clientSessionKey = try await fetchClientSessionKey()
                    
      let onboardingTextConfiguration = OnboardingTextConfiguration(
          onboardingTitle: "Conselhos relevantes",                     // Título
          onboardingFirstLabel: "Esteja com o rosto visível",          // Primeira Instrução
          onboardingSecondlabel: "Encaixe seu rosto no oval",          // Segunda Instrução
          onboardingThirdLabel: "Retire acessórios que cubram o rosto" // Terceira Instrução
      )

      self.faceRecognitionConfig = QITechIosFaceRecognitionConfiguration(
          environment: QITechIosFaceRecognitionEnvironment.sandbox,
          clientSessionKey: clientSessionKey,
          sessionId: "test_session_id",
          documentNumber: "123.456.789-00",
          fontColor: "#AB9FF2",
          backgroundColor: "#FFFDF8",
          fontFamily: .futura,
          showIntroductionScreens: true,
          showSuccessScreen: true,
          showInvalidTokenScreen: false,
          audioConfiguration: AudioConfiguration.enable,
          onboardingTextConfiguration: onboardingTextConfiguration,
          logLevel: .debug 
      )
    }

    // Event where you intend to call QI Tech FaceRecognition View Controller - on this example, when the user press 'next' button

    @IBAction func pressNext(_ sender: Any) {
        let qitechFaceRecognitionController = QITechIosFaceRecognitionController(faceRecognitionConfiguration: self.faceRecognitionConfig)
        qitechFaceRecognitionViewController.delegate = self
        let qitechFaceRecognitionViewController =  qitechFaceRecognitionController.getViewController()
        present(qitechFaceRecognitionViewController, animated: true, completion: nil)
    }

    // Do something if QI Tech FaceRecognition's SDK successfully collected picture
    func qitechIosFaceRecognitionController(_ faceRecognitionViewController: QITechIosFaceRecognitionController, didFinishWithResults results: QITechIosFaceRecognitionControllerResponse) {

    }

    // Do something if QI Tech FaceRecognition's SDK found any error when collecting  picture
    func qitechIosFaceRecognitionController(_ faceRecognitionViewController: QITechIosFaceRecognitionController, didFailWithError error: QITechIosFaceRecognitionControllerError) {

    }

    // Do something if the user canceled the picture collection on any steps
    func qitechIosFaceRecognitionControllerDidCancel(_ faceRecognitionViewController: QITechIosFaceRecognitionController) {

    }
}
```

**Versões anteriores à v7.0.0**
```swift

import QITechIosFaceRecognition

class ViewController: UIViewController, QITechIosFaceRecognitionControllerDelegate {

    var qitechFaceRecognitionConfiguration : QITechIosFaceRecognitionConfiguration?

    override func viewDidLoad() {
        super.viewDidLoad()
        self.setupFaceRecognition()
    }

    func setupFaceRecognition() -> Void {
        // The environment can be 'Sandbox' ou 'Production'
        let environment = QITechIosFaceRecognitionEnvironment.Sandbox

        // ClientSessionKey is the key you got via Face Recognition request. Each environment requires a different API_KEY.
        let clientSessionKey = fetchClientSessionKey()

        self.faceRecognitionConfig = QITechIosFaceRecognitionConfiguration(environment: environment,
                                            clientSessionKey: clientSessionKey,
                                            sessionId: "UNIQUE_SESSION_ID",
                                            backgroundColor: "#000000",
                                            fontColor: "#FFFFFF",
                                            fontFamily: .open_sans,
                                            showIntroductionScreens: true,
                                            showSuccessScreen: false,
                                            showInvalidTokenScreen: true,
                                            activeFaceLiveness: true,
                                            audioConfiguration: AudioConfiguration.Enable,
                                            logLevel: .debug
                                            )
    }

    // Event where you intend to call QI Tech FaceRecognition View Controller - on this example, when the user press 'next' button

    @IBAction func pressNext(_ sender: Any) {
        let qitechFaceRecognitionController = QITechIosFaceRecognitionController(faceRecognitionConfiguration: self.faceRecognitionConfig)
        qitechFaceRecognitionViewController.delegate = self
        let qitechFaceRecognitionViewController =  qitechFaceRecognitionController.getViewController()
        present(qitechFaceRecognitionViewController, animated: true, completion: nil)
    }

    // Do something if QI Tech FaceRecognition's SDK successfully collected picture
    func qitechIosFaceRecognitionController(_ faceRecognitionViewController: QITechIosFaceRecognitionController, didFinishWithResults results: QITechIosFaceRecognitionControllerResponse) {

    }

    // Do something if QI Tech FaceRecognition's SDK found any error when collecting  picture
    func qitechIosFaceRecognitionController(_ faceRecognitionViewController: QITechIosFaceRecognitionController, didFailWithError error: QITechIosFaceRecognitionControllerError) {

    }

    // Do something if the user canceled the picture collection on any steps
    func qitechIosFaceRecognitionControllerDidCancel(_ faceRecognitionViewController: QITechIosFaceRecognitionController) {

    }
}
```

Para incorporar o SDK ao seu aplicativo você deve realizar a configuração do seu aplicativo de captura personalizado através da classe **QITechIosFaceRecognitionConfiguration** e depois instanciar o **ViewController QITechIosFaceRecognitionController** passando como argumento as configurações personalizadas.

Para iniciar o processo de análise de face, basta chamar a função _present_ para chamar o ViewController da QI Tech que realizará a coleta da selfie.

Importante implementar o _Delegate_ responsável por receber os retornos em caso de sucesso, erro ou no caso de o usuário interromper a jornada em qualquer etapa da validação.

Acima temos um exemplo completo da implementação.

---

# necessary_permissions

URL: /documentation/caas/face_recognition/ios/necessary_permissions

## Permissões Necessárias

Para que o SDK possa acessar os recursos do dispositivo para coletar a selfie do usuário, é necessário que sejam solicitadas permissões ao usuário.

No arquivo **info.plist**, adicione as permissões abaixo:

| Permissão                          | Motivo                                             |
| ---------------------------------- | -------------------------------------------------- |
| Privacy - Camera Usage Description | Acesso à câmera para capturar a selfie do usuário. |

---

# using_sdk

URL: /documentation/caas/face_recognition/ios/using_sdk

## Iniciando o SDK

```swift

import QITechIosFaceRecognition

class ViewController: UIViewController, QITechIosFaceRecognitionControllerDelegate {

    var qitechFaceRecognitionConfiguration : QITechIosFaceRecognitionConfiguration?

    override func viewDidLoad() {
        super.viewDidLoad()
        self.setupFaceRecognition()
    }

    func setupFaceRecognition() -> Void {
        // The environment can be 'Sandbox' ou 'Production'
        let environment = QITechIosFaceRecognitionEnvironment.Sandbox

        // MobileToken is the key sent to you by QI Tech. Each environment requires a different MobileToken.
        let mobileToken = "YOUR_MOBILE_TOKEN_SENT_BY_QITECH"

        self.faceRecognitionConfig = QITechIosFaceRecognitionConfiguration(environment: environment,
                                            mobileToken: mobileToken,
                                            sessionId: "UNIQUE_SESSION_ID",
                                            backgroundColor: "#000000",
                                            fontColor: "#FFFFFF",
                                            fontFamily: .open_sans,
                                            showIntroductionScreens: true,
                                            activeFaceLiveness: true,
                                            audioConfiguration: AudioConfiguration.Enable,
                                            logLevel: .debug
                                            )
    }

    // Event where you intend to call QI Tech FaceRecognition View Controller - on this example, when the user press 'next' button

    @IBAction func pressNext(_ sender: Any) {
        let qitechFaceRecognitionController = QITechIosFaceRecognitionController(faceRecognitionConfiguration: self.faceRecognitionConfig)
        qitechFaceRecognitionViewController.delegate = self
        let qitechFaceRecognitionViewController =  qitechFaceRecognitionController.getViewController()
        present(qitechFaceRecognitionViewController, animated: true, completion: nil)
    }

    // Do something if QI Tech FaceRecognition's SDK successfully collected document picture
    func qitechIosFaceRecognitionController(_ faceRecognitionViewController: QITechIosFaceRecognitionController, didFinishWithResults results: QITechIosFaceRecognitionControllerResponse) {

    }

    // Do something if QI Tech FaceRecognition's SDK found any error when collecting document picture
    func qitechIosFaceRecognitionController(_ faceRecognitionViewController: QITechIosFaceRecognitionController, didFailWithError error: QITechIosFaceRecognitionControllerError) {

    }

    // Do something if the user canceled the picture collection on any steps
    func qitechIosFaceRecognitionControllerDidCancel(_ faceRecognitionViewController: QITechIosFaceRecognitionController) {

    }
}
```

Para incorporar o SDK ao seu aplicativo você deve realizar a configuração do seu aplicativo de captura personalizado através da classe **QITechIosFaceRecognitionConfiguration** e depois instanciar o **ViewController QITechIosFaceRecognitionController** passando como argumento as configurações personalizadas.

Para iniciar o processo de análise de face, basta chamar a função _present_ para chamar o ViewController da QI Tech que realizará a coleta da selfie.

Importante implementar o _Delegate_ responsável por receber os retornos em caso de sucesso, erro ou no caso de o usuário interromper a jornada em qualquer etapa da validação.

Ao lado temos um exemplo completo da implementação.

## Mobile Token

Utilizamos um Mobile Token para permitir o acesso autenticado do seu aplicativo a nossa API. Ele provavelmente já foi enviado por e-mail para você. Caso ainda não tenha recebido o seu token, envie um e-mail para suporte.caas@qitech.com.br .

Nossa API espera receber o Mobile Token em todas as requisições ao nosso servidor vindas do SDK, portanto, este deve ser obrigatoriamente incluído como parâmetro de configuração através do método mencionado anteriormente.

:::info **Atenção**

Você deve substituir "YOUR_MOBILE_TOKEN_SENT_BY_QITECH" com o Mobile Token recebido do suporte.
:::

---

# Coletando os Retornos

URL: /documentation/caas/face_recognition/react_native/collecting_response

A função `startFaceRecon` retorna uma _Promise_ que resolve com um objeto já tipado — diferentemente do `startOcr`, não é necessário chamar `JSON.parse()`.

## Resolução da Promise

```typescript
type FACE_RECON_RETURN_VALUES = {
  image_key: string;
  device_scan_session_id: string;
};
```

| Atributo | Tipo | Descrição |
|----------|------|-----------|
|image_key|string|Chave de identificação da imagem fornecida, que pode ser utilizada em qualquer outro serviço do sistema QI Tech. **Importante:** armazene este valor para enviar nas APIs de validação (ex.: API de Onboarding).|
|device_scan_session_id|string|Chave de identificação da sessão de scan de dispositivo realizada internamente pelo SDK de Reconhecimento facial, que pode ser utilizada em qualquer outro serviço do sistema QI Tech.|

```json
{
  "image_key": "5d0f0e1c-8f9e-4b6c-9c3d-2f8a1b4e7c10",
  "device_scan_session_id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d"
}
```

## Rejeição da Promise

Em caso de falha, a _Promise_ é rejeitada com um objeto do tipo `FACE_RECON_ERROR`:

```typescript
type FACE_RECON_ERROR = {
  status_code: number;
  reason: string;
  description: string;
};
```

| Atributo | Tipo | Descrição |
|----------|------|-----------|
|status_code|number|Código HTTP do erro.|
|reason|string|Identificador do motivo do erro.|
|description|string|Descrição detalhada do erro.|

### Erros mais comuns

| reason | status_code | description |
|--------|-------------|-------------|
|`INVALID_TOKEN`|401|`Authentication token expired or invalid` — o `client_session_key` é inválido ou expirou.|
|`USER_CANCELED`|0|`User canceled FaceRecon.` — o usuário interrompeu o fluxo antes de concluí-lo.|

## Exemplo de tratamento

```tsx
startFaceRecon(CAAS_ENVIRONMENT.SANDBOX, clientSessionKey)
  .then((response) => {
    console.log('Image Key: ', response.image_key);
    console.log('Device Scan Session Id: ', response.device_scan_session_id);
  })
  .catch((error) => {
    // Opcional: type assertion (cast) para FACE_RECON_ERROR.
    // Recomendado para garantir type safety em TypeScript.
    const reconError = error as FACE_RECON_ERROR;

    console.error('Status:', reconError.status_code);
    console.error('Reason:', reconError.reason);
    console.error('Description:', reconError.description);
  });
```

---

# Compatibilidade

URL: /documentation/caas/face_recognition/react_native/compatibility

O módulo `@qitech/react-native-caas` exige as seguintes versões mínimas:

| Configuração | Versão mínima |
|------------|--------------|
|React Native|0.74|
|React|18.2.0|
|iOS|15.5|
|Android API Level|35 (Android 15)|
|Datadog SDK nativo (iOS, trazido pelo módulo)|3.x|
|MLKit FaceDetection (iOS, caso já utilizado no seu app)|8.x|

## Versão atual do pacote

| Pacote | Versão |
|--------|--------|
|`@qitech/react-native-caas`|`11.3.0`|
|`@qitech/react-native-device-scan`|`1.2.0`|

:::warning Atenção
Nossos SDKs de iOS só suportam simuladores em máquinas com arquitetura **arm64** (M1/M2/M3/M4) com o **Rosetta** ativo, traduzindo a arquitetura x86_64. Recomendamos o uso de dispositivos físicos para testes.
:::

## Expo

O pacote inclui um _config plugin_ do Expo que aplica automaticamente as configurações nativas de iOS e Android. Veja [Instalação](/documentation/caas/face_recognition/react_native/installation).

:::info **Atenção**
O módulo não funciona no _Expo managed workflow_ sem `prebuild` — é necessário gerar os projetos nativos com `npx expo prebuild`.
:::

---

# Implementação

URL: /documentation/caas/face_recognition/react_native/example

A função `startFaceRecon` abre o fluxo nativo de prova de vida, envia a imagem capturada para a API de Reconhecimento facial da QI Tech e devolve a chave da imagem processada.

## Pré-requisito: obtendo o Client Session Key

A função `startFaceRecon` exige um `client_session_key`. Essa chave é temporária e deve ser gerada no seu backend por meio de uma requisição server-to-server para a nossa API, antes de chamar a função do SDK.

### Endpoint

| Ambiente | URL |
|----------|-----|
| **Sandbox** | `https://api.sandbox.zaig.com.br/face_recognition/client_session` |
| **Produção** | `https://api.zaig.com.br/face_recognition/client_session` |

### Requisição

**Method:** `POST`

**Headers:**

```json
{
  "Authorization": "YOUR_FACE_RECON_API_KEY"
}
```

**Body (Opcional, mas recomendado):**

```json
{
  "user_id": "unique_user_identifier"
}
```

> **Importante:** O campo `user_id` é **altamente recomendado** para medidas de segurança e antifraude. Use o CPF do cliente caso tenha acesso a essa informação.

### Resposta

A resposta bem-sucedida conterá o `client_session_key` que deve ser passado para a função `startFaceRecon`.

```json
{
  "client_session_key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

:::danger Aviso Importante!
A API Key de Reconhecimento facial nunca deve ser embarcada no aplicativo. A requisição acima deve partir exclusivamente do seu backend.
:::

## Assinatura da função

```javascript
const result = await startFaceRecon(
  environment,         // CAAS_ENVIRONMENT
  client_session_key,  // string
  options              // FaceReconOptions (opcional)
);
```

As customizações são opcionais e passadas pelo objeto `options`, descrito em [O objeto FaceReconOptions](/documentation/caas/face_recognition/react_native/face_recon_options).

## Exemplo completo

```tsx
import * as React from 'react';
import { useCallback } from 'react';
import { View, Button } from 'react-native';
import {
  CAAS_ENVIRONMENT,
  CAAS_FONT_FAMILY,
  CAAS_LOG_LEVEL,
  FACE_RECON_AUDIO_CONFIGURATION,
  FACE_RECON_ERROR,
  startFaceRecon,
} from '@qitech/react-native-caas';

const FACE_RECON_API_URL = 'https://api.sandbox.zaig.com.br/face_recognition/client_session';
const FACE_RECON_API_KEY = '<FACE_RECON_API_KEY>';

const config = {
  environment: CAAS_ENVIRONMENT.SANDBOX,
  sessionId: '<SESSION_ID>',
  documentNumber: '111.111.111-11',
  fontColor: '#5dcfe3',
  backgroundColor: '#f5f3f0',
  fontFamily: CAAS_FONT_FAMILY.VERDANA,
  showIntroductionScreens: true,
  showSuccessScreen: true,
  showInvalidTokenScreen: true,
  logLevel: CAAS_LOG_LEVEL.DEBUG,
};

export default function App() {
  // Etapa 1: obter o client_session_key por meio do seu backend
  const fetchClientSessionKey = useCallback(async () => {
    const response = await fetch(FACE_RECON_API_URL, {
      method: 'POST',
      headers: {
        'Authorization': FACE_RECON_API_KEY,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ user_id: '<USER_IDENTIFICATION>' }),
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }

    const data = await response.json();

    if (!data.client_session_key) {
      throw new Error("No 'client_session_key' found.");
    }

    return data.client_session_key;
  }, []);

  // Etapa 2: iniciar o SDK com a chave obtida
  const startFr = async () => {
    const clientSessionKey = await fetchClientSessionKey();

    startFaceRecon(config.environment, clientSessionKey, {
      session_id: config.sessionId,
      document_number: config.documentNumber,
      font_color: config.fontColor,
      background_color: config.backgroundColor,
      font_family: config.fontFamily,
      show_introduction_screens: config.showIntroductionScreens,
      show_success_screen: config.showSuccessScreen,
      show_invalid_token_screen: config.showInvalidTokenScreen,
      audio_configuration: FACE_RECON_AUDIO_CONFIGURATION.ENABLE,
      onboarding_text_configuration: {
        onboarding_title: 'Conselhos relevantes',
        onboarding_first_label: 'Esteja com o rosto visível',
        onboarding_second_label: 'Encaixe seu rosto no oval',
        onboarding_third_label: 'Retire acessórios que cubram o rosto',
      },
      log_level: config.logLevel,
    })
      .then((response) => {
        // image_key identifica a imagem na QI Tech — armazene e envie na API de Onboarding
        console.log('Face Recon successfully ended. Image Key: ', response.image_key);
        // device_scan_session_id identifica a chamada interna ao Device Scan
        console.log('Device Scan Session Id: ', response.device_scan_session_id);
      })
      .catch((error) => {
        const reconError = error as FACE_RECON_ERROR;

        console.error('Error executing FaceRecon:');
        console.error('Status:', reconError.status_code);
        console.error('Reason:', reconError.reason);
        console.error('Description:', reconError.description);
      });
  };

  return (
    <View>
      <Button title="Start FaceRecon" onPress={startFr} />
    </View>
  );
}
```

## Aplicativos de exemplo

O repositório do módulo contém dois aplicativos prontos para execução, na pasta `examples`:

* **QITechReactNativeExample** — React Native puro
* **QITechExpoExample** — Expo

Em ambos, o arquivo `App.tsx` demonstra o uso completo (Reconhecimento facial + OCR + Scan de dispositivo) com o `@qitech/react-native-caas`. Substitua os tokens e API Keys de exemplo pelas suas credenciais. Caso ainda não as tenha recebido, entre em contato com o suporte.caas@qitech.com.br .

---

# O objeto FaceReconOptions

URL: /documentation/caas/face_recognition/react_native/face_recon_options

## Parâmetros de startFaceRecon

| Parâmetro | Tipo | Função | Obrigatório |
|------------|--------------|--------------|--------------|
|environment|CAAS_ENVIRONMENT|Enumerador utilizado para configurar o ambiente de execução para `SANDBOX` ou `PRODUCTION`.|Sim.|
|client_session_key|string|Chave temporária de autenticação obtida por meio de requisição server-to-server à API de Reconhecimento facial. Veja [Implementação](/documentation/caas/face_recognition/react_native/example).|Sim.|
|options|FaceReconOptions|Objeto opcional com as customizações visuais, textuais e de comportamento do SDK.|Não.|

## FaceReconOptions

Todos os campos são opcionais. Quando um campo não é informado, o SDK nativo aplica o seu valor padrão.

```typescript
type FaceReconOptions = {
  session_id?: string;
  document_number?: string;
  font_color?: string;
  background_color?: string;
  font_family?: CAAS_FONT_FAMILY;
  show_introduction_screens?: boolean;
  show_success_screen?: boolean;
  show_invalid_token_screen?: boolean;
  audio_configuration?: FACE_RECON_AUDIO_CONFIGURATION;
  onboarding_text_configuration?: OnboardingTextConfiguration;
  log_level?: CAAS_LOG_LEVEL;
};
```

| Parâmetro | Tipo | Função | Padrão |
|------------|--------------|--------------|--------------|
|session_id|string|Chave que identifica a sessão iniciada no SDK. É utilizada para rastrear todo o fluxo percorrido pelo usuário através de logs. Aceita até 255 caracteres.|Gerado internamente.|
|document_number|string|Número do documento do usuário (CPF), utilizado exclusivamente para identificação antifraude.|Não enviado.|
|font_color|string|Cor da fonte e dos ícones das telas do SDK, em formato hexadecimal (ex.: `"#FFFFFF"`).|`"#000000"`|
|background_color|string|Cor de fundo das telas do SDK, em formato hexadecimal (ex.: `"#000000"`).|`"#FFFFFF"`|
|font_family|CAAS_FONT_FAMILY|Fonte utilizada nas telas do SDK.|`CAAS_FONT_FAMILY.OPEN_SANS`|
|show_introduction_screens|boolean|Quando `false`, desativa as telas de introdução à prova de vida.|`true`|
|show_success_screen|boolean|Quando `false`, desativa a tela de sucesso exibida após a captura.|`true`|
|show_invalid_token_screen|boolean|Quando `false`, desativa a tela exibida quando o `client_session_key` é inválido ou expirou.|`true`|
|audio_configuration|FACE_RECON_AUDIO_CONFIGURATION|Configura o guiamento por voz, que narra as instruções de captura em tempo real.|`FACE_RECON_AUDIO_CONFIGURATION.DISABLE`|
|onboarding_text_configuration|OnboardingTextConfiguration|Customiza os textos da tela de onboarding.|Textos padrão do SDK.|
|log_level|CAAS_LOG_LEVEL|Nível de verbosidade dos logs do SDK.|`CAAS_LOG_LEVEL.DEBUG`|

:::info **Atenção**
O campo `document_number` não dispara o registro de face — ele é utilizado somente para identificação antifraude.
:::

## OnboardingTextConfiguration

```typescript
type OnboardingTextConfiguration = {
  onboarding_title?: string;
  onboarding_first_label?: string;
  onboarding_second_label?: string;
  onboarding_third_label?: string;
};
```

| Parâmetro | Tipo | Função |
|------------|--------------|--------------|
|onboarding_title|string|Título da tela de onboarding.|
|onboarding_first_label|string|Primeira instrução exibida ao usuário.|
|onboarding_second_label|string|Segunda instrução exibida ao usuário.|
|onboarding_third_label|string|Terceira instrução exibida ao usuário.|

## Enumeradores

### CAAS_ENVIRONMENT

```typescript
enum CAAS_ENVIRONMENT {
  PRODUCTION = 'production',
  SANDBOX = 'sandbox',
}
```

### CAAS_FONT_FAMILY

```typescript
enum CAAS_FONT_FAMILY {
  JAKARTA = 'jakarta',                // apenas iOS
  FUTURA = 'futura',                  // iOS e Android
  VERDANA = 'verdana',                // iOS e Android
  TREBUCHET_MS = 'trebuchetms',       // apenas iOS
  TAMILSANGAM_MN = 'tamilsangammn',   // apenas iOS
  OPEN_SANS = 'open_sans',            // iOS e Android
  HELVETICA = 'helvetica',            // apenas Android
  POPPINS = 'poppins',                // apenas Android
  ROBOTO = 'roboto',                  // apenas Android
  SYSTEM_FONT = 'system_font',        // apenas iOS
}
```

:::info **Atenção**
A disponibilidade das fontes varia por plataforma. Caso uma fonte não suportada seja informada, a plataforma utiliza a sua fonte padrão. Para consistência entre iOS e Android, utilize `FUTURA`, `VERDANA` ou `OPEN_SANS`.
:::

### FACE_RECON_AUDIO_CONFIGURATION

```typescript
enum FACE_RECON_AUDIO_CONFIGURATION {
  ENABLE = 'enable',               // exibe o botão de áudio, com a narração iniciando desligada
  DISABLE = 'disable',             // desativa a narração e oculta o botão
  ACCESSIBILITY = 'accessibility', // exibe o botão com a narração iniciando ligada quando há recursos de acessibilidade ativos
}
```

### CAAS_LOG_LEVEL

```typescript
enum CAAS_LOG_LEVEL {
  TRACE = 'trace',
  DEBUG = 'debug',
  LOG = 'log',
  INFO = 'info',
  WARN = 'warn',
  ERROR = 'error',
}
```

---

# Instalação

URL: /documentation/caas/face_recognition/react_native/installation

## Instalando o pacote

### 1. Configurando o registro npm

Crie um arquivo `.npmrc` na raiz do seu projeto:

```sh
@qitech:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=NPM_TOKEN_SENT_BY_QI_TECH
```

Substitua `NPM_TOKEN_SENT_BY_QI_TECH` pelo token fornecido pelo suporte. Caso ainda não tenha recebido o seu token, entre em contato com o suporte.caas@qitech.com.br .

### 2. Instalando a dependência

```sh
yarn add @qitech/react-native-caas
```

### 3. Importação

```javascript
import {
  CAAS_ENVIRONMENT,
  CAAS_FONT_FAMILY,
  CAAS_LOG_LEVEL,
  FACE_RECON_AUDIO_CONFIGURATION,
  FACE_RECON_ERROR,
  startFaceRecon,
} from '@qitech/react-native-caas';
```

## Configuração do Android

### 1. Repositório Maven da QI Tech

Adicione o repositório Maven da QI Tech ao `build.gradle` do projeto:

```groovy
allprojects {
  repositories {
    maven { url 'https://sdks.qitech.com.br/' }
    ...
  }
}
```

### 2. AdMob

Inicialize o serviço de AdMob adicionando o seguinte código ao `AndroidManifest.xml`:

```xml
<meta-data
  android:name="com.google.android.gms.ads.APPLICATION_ID"
  android:value="<ADMOB_APP_ID>"/>
```

Caso não possua um `ADMOB_APP_ID`, entre em contato com o suporte.caas@qitech.com.br .

## Configuração do iOS

### 1. Permissão de câmera

Adicione a entrada `NSCameraUsageDescription` ao `Info.plist` do seu aplicativo, com o motivo pelo qual o app precisa de acesso à câmera:

```xml
<key>NSCameraUsageDescription</key>
<string>Precisamos da câmera para capturar a sua selfie</string>
```

### 2. Source do repositório iOS da QI Tech

Adicione as seguintes sources no topo do seu `Podfile`:

```ruby
source 'https://cdn.cocoapods.org/'
source 'https://github.com/QITechSDKs/iOS.git'
```

### 3. Frameworks estáticos

Necessário **apenas** se você utiliza o Xcode **anterior à versão 26**:

```ruby
use_frameworks! :linkage => :static
```

:::warning Atenção
O [Flipper](https://fbflipper.com/docs/getting-started/react-native/) não funciona com `use_frameworks!`. Remova a chamada `use_flipper()` do seu `Podfile` caso ela esteja presente.
:::

### 4. Estabilidade de módulo

As dependências do Datadog exigem que o `BUILD_LIBRARY_FOR_DISTRIBUTION` esteja habilitado. Adicione o `post_install` abaixo (ou incorpore ao seu `post_install` existente):

```ruby
post_install do |installer|
  installer.pods_project.targets.each do |target|
    if ['DatadogCore', 'DatadogInternal', 'DatadogCrashReporting', 'DatadogLogs'].include?(target.name)
      target.build_configurations.each do |config|
        config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.5'
        config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
      end
    end
  end
end
```

### 5. Instalação dos pods

```sh
cd ios && pod install
```

:::warning Atenção
Se o seu aplicativo já utiliza **Datadog**, use a versão mais recente dentro do major `3.x`. Se utiliza o **FaceDetection do MLKit**, use a versão mais recente dentro do major `8.x`.
:::

## Configuração do Expo

O pacote inclui um _config plugin_ do Expo que aplica automaticamente todas as configurações nativas de iOS e Android descritas acima. No seu `app.json`:

```json
{
  "expo": {
    "plugins": ["@qitech/react-native-caas"]
  }
}
```

Em seguida, execute o `prebuild` para aplicar as alterações nativas:

```sh
npx expo prebuild
```

---

# Introdução

URL: /documentation/caas/face_recognition/react_native/introduction

Bem vindo ao manual de integração do SDK de Reconhecimento facial da QI Tech em React Native! O módulo `@qitech/react-native-caas` expõe, por meio de uma interface TypeScript, os SDKs nativos de Android (Java/Kotlin) e iOS (Swift) da QI Tech. Você deve utilizá-lo para realizar a prova de vida (liveness) do seu cliente diretamente do seu aplicativo React Native e referenciar a imagem capturada, através de uma chave, nos demais produtos do sistema QI Tech.

## Pacotes disponíveis

| Pacote | Conteúdo | Quando usar |
|--------|----------|-------------|
|`@qitech/react-native-caas`|Reconhecimento facial, OCR e Scan de dispositivo|Quando você precisa de reconhecimento facial, OCR ou do fluxo completo de onboarding.|
|`@qitech/react-native-device-scan`|Somente Scan de dispositivo|Quando você precisa **apenas** de scan de dispositivo — instalação mais leve, com menos dependências nativas.|

:::danger Aviso Importante!
Ambos os pacotes incluem o Scan de dispositivo. **Não instale os dois** — escolha apenas um.
:::

Para o Reconhecimento facial, utilize o `@qitech/react-native-caas`.

## Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso [suporte](mailto:suporte.caas@qitech.com.br) e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

### Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

## Ambientes

Possuímos dois ambientes para os nossos clientes. A seleção é realizada por meio do enumerador `CAAS_ENVIRONMENT`, repassado como primeiro parâmetro da função `startFaceRecon`. No momento, os seguintes ambientes estão disponíveis:

* Produção - `CAAS_ENVIRONMENT.PRODUCTION`
* Sandbox - `CAAS_ENVIRONMENT.SANDBOX`

Cada ambiente exige uma API Key diferente para a geração do `client_session_key`.

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.
:::

## Integração com Device Scan

O serviço de Reconhecimento facial realiza automaticamente uma chamada interna ao Device Scan. Por isso, o retorno de sucesso inclui o campo `device_scan_session_id`, que identifica a sessão de scan de dispositivo realizada internamente e pode ser utilizada de forma integrada em outros serviços do ecossistema QI Tech.

## Próximos passos

1. [Compatibilidade](/documentation/caas/face_recognition/react_native/compatibility) — versões mínimas de React Native, iOS e Android.
2. [Instalação](/documentation/caas/face_recognition/react_native/installation) — instalação do pacote e configuração nativa de Android, iOS e Expo.
3. [Implementação](/documentation/caas/face_recognition/react_native/example) — obtenção do `client_session_key` e exemplo completo da chamada `startFaceRecon`.
4. [O objeto FaceReconOptions](/documentation/caas/face_recognition/react_native/face_recon_options) — todos os parâmetros de customização.
5. [Coletando os Retornos](/documentation/caas/face_recognition/react_native/collecting_response) — estrutura de resposta e tratamento de erros.

---

# Coletando os Retornos do SDK

URL: /documentation/caas/face_recognition/web/collecting_response

## O método .initialize()

O método `.initialize()` é responsável pela inicialização do componente de reconhecimento facial e prova de vida. A partir de sua execução, o SDK carrega o modelo de detecção de face e valida as condições do dispositivo/navegador.

**Promise resolution:**

```javascript
{
  status: "SUCCESS",
  data: null
}
```

**Cenários de Rejection:**

- **Unsupported Browser:**

```javascript
{
  status: "FAILURE",
  reason: "UNSUPPORTED_BROWSER",
  description: "User browser is not supported."
}
```

- **Not Mobile Device:**

```javascript
{
  status: "FAILURE",
  reason: "NOT_MOBILE_DEVICE",
  description: "User device is not mobile."
}
```

- **Initialization Error:**

```javascript
{
  status: "FAILURE",
  reason: "INITIALIZATION_ERROR",
  description: "..."
}
```

## O método .open()

Este método recebe o `clientSessionKey` (obtido via chamada server-to-server) e inicia a interação com o usuário para a coleta da prova de vida. Retorna uma _Promise_ que é resolvida com a chave da imagem capturada assim que o fluxo é concluído.

**Promise resolution:**

```javascript
{
  status: "SUCCESS",
  data: string // image_key que identifica a imagem no servidor
}
```

Exemplo:

```javascript
{
  status: "SUCCESS",
  data: "d8a3b1c4-9e2f-47a5-8c3d-1b2e5..."
}
```

**Promise rejection:**

```javascript
{
  status: string;
  reason: string;
  description: string;
}
```

**Cenários de Rejection:**

- **User Canceled:**

```javascript
{
  status: "FAILURE",
  reason: "USER_CANCELED",
  description: "User pressed the back button."
}
```

- **Invalid Token:** (ocorre quando o `clientSessionKey` é inválido ou expirou)

```javascript
{
  status: "FAILURE",
  reason: "INVALID_TOKEN",
  description: "Authentication token expired or invalid"
}
```

- **Session Superseded:** (ocorre quando `.open()` é chamado novamente em uma instância já aberta)

```javascript
{
  status: "FAILURE",
  reason: "SESSION_SUPERSEDED",
  description: "A new session has been started before the previous one was completed."
}
```

---

# Implementação

URL: /documentation/caas/face_recognition/web/example

:::info Novidade na versão 4.0.0
A partir da versão **4.0.0**, o construtor `WebFaceRecon` não recebe mais o `hostComponent` — o SDK gerencia seu próprio nó DOM. O `client_session_key` continua sendo obrigatório e deve ser passado ao método `.open()`.
:::

A implementação é realizada instanciando `QITechWebFaceRecon.WebFaceRecon()`, encadeando as opções de configuração e chamando `.build()`. A inicialização ocorre em `.initialize()`, e a captura da prova de vida é iniciada com `.open(clientSessionKey)`.

## Obtendo o Client Session Key

Antes de chamar `.open()`, você deve gerar um **clientSessionKey** temporário via requisição server-to-server para a nossa API de face recognition.

### Endpoint

| Ambiente | URL |
|----------|-----|
| **Sandbox** | `https://api.sandbox.zaig.com.br/face_recognition/client_session` |
| **Produção** | `https://api.zaig.com.br/face_recognition/client_session` |

### Requisição

**Method:** `POST`

**Headers:**
```json
{
  "Authorization": "YOUR_FACE_RECON_API_KEY"
}
```

**Body (Opcional, mas recomendado):**
```json
{
  "user_id": "unique_user_identifier"
}
```

> **Importante:** O campo `user_id` é **altamente recomendado** para medidas de segurança e antifraude. Use um identificador único do usuário da sua aplicação.

### Resposta

```json
{
  "client_session_key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

## Exemplo completo

```html
<script src="https://facerecon.caas.qitech.app/face-recognition-4-2-1.js"></script>

<script>
  async function iniciarReconhecimentoFacial() {
    // 1. Obtenha o clientSessionKey via chamada server-to-server
    const clientSessionKey = await fetchClientSessionKey();

    // 2. Configure e instancie o SDK
    const webFaceRecon = new QITechWebFaceRecon.WebFaceRecon()
      .setThemeConfiguration({
        primaryColor:  "#2848A8",
        tertiaryColor: "#57D9FF",
        fontFamily:    "Verdana"
      })
      .setSandboxEnvironment()
      .setSessionId("UNIQUE_SESSION_ID")
      .build();

    // 3. Inicializa (valida browser/dispositivo e carrega modelo)
    await webFaceRecon.initialize();

    // 4. Inicia a captura da prova de vida
    const response = await webFaceRecon.open(clientSessionKey);
    console.log(`Status: ${response.status}, Key: ${response.data}`);
  }
</script>
```

## Versões anteriores

:::danger Aviso Importante!
Versões anteriores à **4.0.0** recebem o `hostComponent` como primeiro argumento do construtor. A partir da **3.0.0**, o `web_token` foi removido do construtor e o fluxo de `client_session_key` foi introduzido.
:::

```html
<script>
  // Versões 3.x
  var hostComponent = document.getElementById('webfacerecon');
  var webFaceRecon = new QITechWebFaceRecon.WebFaceRecon(hostComponent)
    .setThemeConfiguration({
      "buttonColor": "#2848A8",
      "fontColor": "#FFFFFF",
      "backgroundColor": "#FFFFFF"
    })
    .setSandboxEnvironment()
    .setSessionId('UNIQUE_SESSION_ID')
    .build();

  webFaceRecon.initialize()
    .then(() => fetchClientSessionKey())
    .then(clientSessionKey => webFaceRecon.open(clientSessionKey))
    .then(response => console.log(`Status: ${response.status}, Key: ${response.data}`))
    .catch(error => {
      console.error(error);
      alert(error.reason || error);
    });
</script>
```

---

# O construtor QITechWebFaceRecon.WebFaceRecon()

URL: /documentation/caas/face_recognition/web/example_zaigwebfacerecon

O método `.WebFaceRecon()` é responsável pela configuração da instância do seu componente de reconhecimento facial. A partir da versão **4.0.0**, o construtor não recebe mais parâmetros — a renderização é gerenciada internamente pelo SDK. Utilize os métodos encadeados abaixo para personalizar o comportamento:

| Nome | Descrição | Obrigatório |
|----------|----------|----------|
| `.setSandboxEnvironment()` | Configura o ambiente para modo Sandbox. | Não |
| `.setShowInvalidTokenScreen(Boolean)` | Define se a tela de falha de autenticação deve ser exibida. Padrão: `false`. | Não |
| `.setShowBackButton(Boolean)` | Define se o botão de voltar deve ser exibido (ao ser pressionado, encerra o fluxo). Padrão: `true`. | Não |
| `.setSessionId(String)` | Define a chave que identifica a sessão iniciada no SDK — usada para rastrear o fluxo do usuário nos logs. Aceita até 255 caracteres. | Não |
| `.setThemeConfiguration(object)` | Personaliza a identidade visual do SDK. | Não |
| `.setLogLevel(String)` | Nível de verbosidade dos logs. Opções: `"info"`, `"debug"`, `"warn"`, `"error"`. Padrão: `"info"`. | Não |
| `.setCameraNotAllowedErrorDescription(String)` | Mensagem customizada exibida quando o usuário nega permissão de câmera. | Não |

O método `.setThemeConfiguration` deve receber um objeto com os seguintes campos:

| Nome | Tipo | Descrição |
| -------- | -------- | -------- |
| primaryColor | String | Hexadecimal da cor principal do SDK (fundo, header). Caso não seja informada, o padrão é `#285BB8`. |
| tertiaryColor | String | Hexadecimal da cor dos botões de ação. Caso não seja informada, o padrão é `#57D9FF`. |
| fontFamily | String | _Font Family_ a ser configurada nos textos do SDK. Caso não seja informada, será utilizada a fonte padrão do sistema. |

## Versões Anteriores

:::danger Aviso Importante!
A partir da versão **4.0.0**, o parâmetro `hostComponent` e o `web_token` no construtor foram removidos. O SDK gerencia seu próprio nó DOM internamente.
:::

Nas versões anteriores a **4.0.0**, o construtor recebia os seguintes parâmetros posicionais:

| Nome | Descrição | Obrigatório |
|----------|----------|----------|
| hostComponent | Componente HTML pai que abrigava o HTML do SDK. | Sim |
| web_token | Chave do cliente enviada pela QI Tech. | Sim (versões < 3.0.0) |

---

# Importando a biblioteca

URL: /documentation/caas/face_recognition/web/import

Para importar nossa biblioteca, adicione o endereço da nossa biblioteca em uma TAG **src** no HTML de seu website:

```html
<script src="https://facerecon.caas.qitech.app/face-recognition-4-2-1.js"></script>
```

---

# Introdução

URL: /documentation/caas/face_recognition/web/introduction

Bem vindo ao manual de integração do Web Face Recognition da QI Tech! Esta biblioteca realiza a captura de face e seu envio para a API de Face Recognition da QI Tech . Você pode utilizar esta biblioteca para capturar através do seu website uma imagem do rosto de um cliente e referenciá-lo através de uma chave nos demais produtos do sistema QI Tech.

Neste passo a passo você encontrará detalhes da biblioteca bem como um exemplo de implementação em javascript. Com isso você possui as ferramentas necessárias para poder adequar ao caso de uso da sua aplicação.

## Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso suporte e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

### Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

## Ambientes

Possuímos dois ambientes para os nossos clientes. 

* Produção
* Sandbox

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.  
:::

A seleção é realizada por meio do método `.setSandboxEnvironment()` durante a configuração do SDK, que irá alterar o ambiente para Sandbox. Caso o método não seja chamado, o ambiente de produção será utilizado.

---

# Registro de Rosto e Validação 1:1

URL: /documentation/caas/face_recognition/web/registration_and_validation

:::danger Funcionalidade Descontinuada
Os métodos `.setDocumentNumber()` e `.setValidation()` foram descontinuados e removidos do Web Face Recognition SDK. O fluxo de registro e validação 1:1 via SDK Web não é mais suportado em nenhuma versão.

Para realizar registro e validação de face, utilize diretamente a [API de Face Recognition](https://docs.qitech.com.br/documentation/caas/face_recognition/api/face_registration).
:::

---

# authentication

URL: /documentation/caas/limits/authentication

## Autenticação

> Para autenticar uma chamada, utilize o código seguinte:

```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE_API_KEY"
```

> Substitua a API key 'EXAMPLE_API_KEY' com a sua chave adquirida com o nosso suporte.

Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br .

Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:

`Authorization: EXAMPLE_API_KEY`

:::info **Atenção**

Você deve substituir EXAMPLE_API_KEY com a API Key recebida do suporte.
:::

---

# Status HTTP

URL: /documentation/caas/limits/http_status

Todas as APIs da QI Tech utilizam a seguinte padronização nos status HTTP de retorno, de acordo com o RFC 7231 :

Status HTTP | Significado | Descrição
---------- | ------- | ---------------------------------
400 | Bad Request | A requisição enviada possui algum erro de formatação. Na maioria dos casos, retornamos no corpo da mensagem uma explicação de onde está o erro.
401 | Unauthorized | Houve algum problema na autenticação, verifique se a API Key está correta e no header correto, de acordo com a seção Autenticação .
403 | Forbidden | O endpoint acessado é de uso interno e não está disponível para esta API Key.
404 | Not Found | O dado requisitado não foi encontrado usando a chave utilizada. Este status também é retornado quando um endpoint inválido é requisitado.
405 | Method Not Allowed | O método HTTP utilizado não se aplica ao endpoint utilizado.
406 | Not Acceptable | Os dados enviados no corpo da requisição são inválidos. Em geral, isso significa que os dados enviados não são um JSON válido.
409 | Conflict | O id da requisição corresponde a um id já processado anteriormente. Este status é retornado no caso de requisições duplicadas enviadas ao servidor.
500 | Internal Server Error | Tivemos um problema para processar esta requisição, ao encontrarmos esse erro nossos especialistas são automaticamente notificados e iniciam a análise e solução imediatamente.
503 | Service Unavailable | Você se deparou com uma indisponibilidade, planejada ou não, de infraestrutura dos nossos servidores.

---

# Introdução

URL: /documentation/caas/limits/introduction

Bem vindo à API de Limites Pix da QI Tech! Você pode utilizar a nossa API para gerenciar os seus limites pix:
- Cadastrar novos limites pix;
- Modificar limites pix pré-existentes;
- Recuperar limites pix pré-existentes.

Abaixo, você pode observar a implementação da API utilizando cUrl. Com isso você possui exemplos para poder adaptar adequadamente à linguagem de programação da sua preferência.

## Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso suporte e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

### Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

## Ambientes

Possuímos dois ambientes para os nossos clientes. As URLs base das APIs são:

* Produção - `https://api.caas.qitech.app/limits_pix/`
* Sandbox - `https://api.sandbox.caas.qitech.app/limits_pix/`

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.  
:::

No ambiente de Sandbox, as análises enviadas não são cobradas e são respondidas de acordo com regras pré estabelecidas.

Para a análise de uma transação, a seguinte regra é aplicada sobre o valor da transação:

Mínimo | Máximo | Decisão
------ | ------ | -------
0 | 1000 | Aprovado Automaticamente
1001 | 2000 | Derivado para análise manual - Posteriormente aprovado
2001 | 3000 | Derivado para análise manual - Posteriormente reprovado
3001 | 4000 | Reprovado Automaticamente
4001 | 5000 | Não analisado
5001 | - | Pendente

## Somente HTTPS

Por questão de segurança, toda a comunicação com as APIs da QI Tech deve ser realizada utilizando a comunicação HTTPS. Para evitar que, por desatenção ou outro motivo, sejam feitas chamadas HTTP, este servidor somente disponibiliza a porta 443 com comunicação TLS 1.2. Chamadas realizadas utilizando outros protocolos serão automaticamente negadas.

## Autenticação

> Para autenticar uma chamada, utilize o código seguinte:

```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE_API_KEY"
```

> Substitua a API key 'EXAMPLE_API_KEY' com a sua chave adquirida com o nosso suporte.

Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br .

Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:

`Authorization: EXAMPLE_API_KEY`

:::info **Atenção**

Você deve substituir EXAMPLE_API_KEY com a API Key recebida do suporte.
:::

---

# Cadastro de Novo Limite

URL: /documentation/caas/limits/limit_registration

Para realizar o cadastro de um novo limite, basta enviar um objeto do tipo _Account_ ao seguinte endpoint:

`POST https://api.caas.qitech.app/limits_pix/account`

<!-- Ao final do cadastro de uma pessoa física em sua plataforma, é necessário executar a avaliação de fraude e de KYC deste cliente, o que deve ser realizado através do endpoint de Natural Person. Os dados enviados deverão ser os dados finais, que não serão alterados em hipótese alguma, isto é, não deverá existir a possibilidade de se realizar uma alteração nos dados básicos de cadastro como CPF, Nome, Data de Nascimento e outros após este processo. Isto é muito importante para garantir dois pontos:

* Consistência dos dados na base de dados do Antifraude
* Avaliação realista do risco, evitando fraudes em momentos posteriores da operação -->

> Exemplo

```json
{
    "account_id": "5ce7fab5-8165-44a5-9b89-bb2d6d61e4f4",
    "registration_date": "2019-12-20T15:23:12",
    "limit": {
        "withdraw": {
            "daytime" : {
                "start_time": "06:00:00-03:00",
                "amount": 500000
            },
            "nighttime" : {
                "start_time": "20:00:00-03:00",
                "amount": 300000
            }
        },
        "change": {
            "daytime" : {
                "start_time": "06:00:00-03:00",
                "amount": 500000
            },
            "nighttime" : {
                "start_time": "20:00:00-03:00",
                "amount": 300000
            }
        },
        "transaction_natural_person": {
            "daytime" : {
                "start_time": "06:00:00-03:00",
                "amount": 500000
            },
            "nighttime" : {
                "start_time": "20:00:00-03:00",
                "amount": 300000
            }
        },
        "transaction_legal_person": {
            "daytime" : {
                "start_time": "06:00:00-03:00",
                "amount": 500000
            },
            "nighttime" : {
                "start_time": "20:00:00-03:00",
                "amount": 300000
            }
        }
    }
}
```

Todas as trocas de informação de um cadastro utilizam a seguinte definição para este objeto. Em alguns casos, para facilitar a implementação e diminuir o fluxo de dados entre as partes, algumas informações poderão ser omitidas.

nome | tipo | descrição
:----: | :----: | ---------
account_id | string | Identificador único da conta. **É essencial que este número seja único para cada requisição**
registration_date |	string (ISO 8601) | Data e hora do cadastro.
limit |	limit | 	Objeto do tipo _limit_.

## Objeto Limit

```json
{
    "withdraw": {
        "daytime" : {
            "start_time": "06:00:00-03:00",
            "amount": 500000
        },
        "nighttime" : {
            "start_time": "20:00:00-03:00",
            "amount": 300000 
        }
    },
    "change": {
        "daytime" : {
            "start_time": "06:00:00-03:00",
            "amount": 500000
        },
        "nighttime" : {
            "start_time": "20:00:00-03:00",
            "amount": 300000 
        }
    },
    "transaction_natural_person": {
        "daytime" : {
            "start_time": "06:00:00-03:00",
            "amount": 500000
        },
        "nighttime" : {
            "start_time": "20:00:00-03:00",
            "amount": 300000 
        }
    },
    "transaction_legal_person": {
        "daytime" : {
            "start_time": "06:00:00-03:00",
            "amount": 500000
        },
        "nighttime" : {
            "start_time": "20:00:00-03:00",
            "amount": 300000 
        }
    }
}
```

Este objeto representa os limites de valores aplicáveis aos diferentes tipos de transações em diferentes momentos do dia, levando em consideração a divisão de períodos diurno e noturno.

O objeto está organizado em quatro categorias principais (ou tipos de limites): "withdraw" (referente a modalidade PIX Saque), "change" (referente a modalidade PIX troco), "transaction_natural_person" (referente a modalidade PIX transacional para pessoas físicas) e "transaction_legal_person" (referente a modalidade PIX transacional para pessoas jurídicas). Cada categoria contém 2 períodos, "daytime" e "nighttime", representando respectivamente os períodos diurno e noturno, descrevendo o horário de início e os respectivos limites de valores a ser aplicados para a modalidade. Vale citar que as 4 categorias de PIX do objeto limit são obrigatórias, devendo estar presentes no momento de criação da conta.

Estrutura de uma Janela de Limite:

nome |	tipo |	descrição
:----: | :----: | ---------
start_time |	string (ISO 8601) |	Indica o momento em que os limites de valor para transações PIX são aplicados. Atente-se para a configuração correta do início da Janela de Limite de acordo com o fuso horário que pretende utilizar.
amount |	inteiro |	Valor do limite máximo permitido para a modalidade no período especificado pelo "start_time" em centavos de reais.

Uma vez que, de acordo com as diretrizes do Banco Central, as janelas diurnas de limites PIX devem iniciar obrigatoriamente às 6AM, apenas o valor "06:00:00-03:00" será atualmente aceito para configuração do start_time destas janelas.

De maneira similar, já que as janelas noturnas de limites PIX devem iniciar às 8PM ou às 10PM, apenas os valores "20:00:00-03:00" e "22:00:00-03:00" serão aceitos para configuração do start_time destas janelas.

*Exemplo de Uso:*
Suponhamos que o usuário esteja realizando uma transação PIX para pessoa física no horário 12:00:00-03:00. Ao consultar o objeto, localizamos a categoria "transaction_natural_person". Nessa categoria, encontramos os 2 períodos, "daytime" e "nighttime": o primeiro inicia em "06:00:00-03:00" e o segundo inicia em "20:00:00-03:00". Se a transação for realizada entre esses horários, o limite máximo de valor permitido é de 5.000,00 (cinco mil) reais, conforme especificado na primeira janela  de limite.

No entanto, caso a transação ocorra após "20:00:00-03:00" e antes do próximo horário de início (neste exemplo, às 06:00 do dia seguinte), o limite máximo de valor permitido será de 3.000,00 (três mil) reais, conforme indicado na segunda janela (janela noturna) de limite.

# Criando uma Proposta de Modificação de Limite

Para solicitar uma modificação de um limite, basta enviar um objeto do tipo Limit ao seguinte endpoint:

`POST https://api.caas.qitech.app/limits_pix/account/{account_id}/limit_update_request`

> Exemplo

```json
{
    "withdraw": {
        "daytime" : {
            "start_time": "06:00:00-03:00",
            "amount": 500000
        },
        "nighttime" : {
            "start_time": "20:00:00-03:00",
            "amount": 300000 
        }
    },
    "change": {
        "daytime" : {
            "start_time": "06:00:00-03:00",
            "amount": 550000
        },
        "nighttime" : {
            "start_time": "20:00:00-03:00",
            "amount": 350000 
        }
    },
    "transaction_natural_person": {
        "daytime" : {
            "start_time": "06:00:00-03:00",
            "amount": 500000
        },
        "nighttime" : {
            "start_time": "20:00:00-03:00",
            "amount": 300000 
        }
    }
}
```

O retorno da requisição será composto por uma lista com todas as modificações que foram realizadas, separados por período e por categoria de limite PIX. No caso do exemplo acima, as alterações foram realizadas na categoria "change" (PIX Troco) com a requisição para aumento do limite de ambos os periodos. Portanto a resposta da requisição será a seguinte:

```json
{   "limit_update_requests" : [
        { 
            "limit_update_request_id": "5ce7fab5-8165-44a5-9b89-bb2d6d61e4f4",
            "analysis_status": "automatically_approved",
            "client_notification_status": "not_applicable",
            "limit_update_request_status": "applied",
            "limit_update_request_type" : "change_daytime",
            "event_date": "2019-10-01T10:37:25-03:00"
        },
        { 
            "limit_update_request_id": "5ce7fab5-8165-44a5-9b89-bb2d6d61e4f4",
            "analysis_status": "automatically_approved",
            "client_notification_status": "not_applicable",
            "limit_update_request_status": "applied",
            "limit_update_request_type" : "change_nighttime",
            "event_date": "2019-10-01T10:37:25-03:00"
        },
    ]
}
```

nome |	tipo |	descrição
:----: | :----: | ---------
limit_update_request_id |	string |	Identificador único da Proposta de Modificação de Limite
analysis_status |	string |	Enumerador do analysis_status da proposta
client_notification_status |	string |	Enumerador do client_notification_status da proposta
limit_update_request_status |	string |	Enumerador do limit_update_request_status da proposta
limit_update_request_type |	  string |	Enumerador do limit_update_request_type da proposta
event_date |	string (ISO 8601) |	Data e hora da criação da Proposta de Modificação de Limite

Para um melhor entendimento dos status de retorno acesse dinâmica de status .

---

# Criando uma lista de beneficiários

URL: /documentation/caas/limits/recipient_list

Conforme regulamentação de limites PIX do Banco Central, é possível realizar a criação de uma lista de beneficiários que utilizarão o mesmo
limite diferenciado.

Para solicitar a criação de uma lista de beneficiários para uma conta, basta enviar um objeto do tipo Limite ao seguinte endpoint:

`POST https://api.caas.qitech.app/limits_pix/account/{account_id}/recipient_list`

```json
{
    "limit" : {
        "transaction": {
            "daytime" : {
                "start_time": "06:00:00-03:00",
                "amount": 60000
            },
            "nighttime" : {
                "start_time": "20:00:00-03:00",
                "amount": 60000 
            }
        }
    }
}
```

Que apresentará o seguinte retorno:

```json
{
    "event_date": "2019-10-01T10:37:25-03:00"
}
```

nome |	tipo |	descrição
:----: | :----: | ---------
event_date |	string (ISO 8601) |	Data e hora da criação da Lista de Beneficiários

# Adicionando um novo Beneficiário a lista de Beneficiários

Para adicionar um novo beneficiário a uma lista de beneficiários previamente criada, é necessário apenas realizar a seguinte requisição:

`POST https://api.caas.qitech.app/limits_pix/account/{account_id}/recipient_list/recipient`

```json
{
    "document_number": "123.456.789-10"
}
```

Que apresentará o seguinte retorno:

```json
{
    "recipient_id": "c7a79970-b558-4425-998a-5cd6747c1c90",
    "analysis_status": "automatically_approved",
    "client_notification_status": "awaiting_notification_period",
    "recipient_status": "created",
    "event_date": "2019-10-01T10:37:25-03:00"
}
```

nome |	tipo |	descrição
:----: | :----: | ---------
recipient_id |	string |	Identificador único do Beneficiário desta Proposta de Modificação de Limite
analysis_status |	string |	Enumerador do analysis_status da proposta
client_notification_status |	string |	Enumerador do client_notification_status da proposta
recipient_status |	string |	Enumerador do recipient_status da proposta
event_date |	string (ISO 8601) |	Data e hora da criação da Proposta de Modificação de Limite

Para um melhor entendimento dos status de retorno acesse dinâmica de status .

# Removendo um Beneficiário

Para remover um beneficiário específico para uma conta, basta enviar uma requisição do tipo DELETE para o seguinte endereço:

`DELETE https://api.caas.qitech.app/limits_pix/account/{account_id}/recipient_list/recipient/{recipient_id}`

# Editando os Limites de uma lista de Beneficiários

Para solicitar a alteração dos limites de beneficiário de uma dada conta, basta realizar o envio da seguinte requisição:

`POST https://api.caas.qitech.app/limits_pix/account/{account_id}/recipient_list/limit_update_request`

```json
{
    "limit" : {
        "transaction": {
            "daytime" : {
                "start_time": "06:00:00-03:00",
                "amount": 70000
            },
            "nighttime" : {
                "start_time": "20:00:00-03:00",
                "amount": 70000 
            }
        }
    }
}
```

O retorno da requisição será composto por uma lista com todas as modificações que foram realizadas, separados por período. No caso do exemplo acima, as alterações foram realizadas na categoria "transaction" com requisição para aumento do limite de ambos os periodos. Portanto a resposta da requisição será a seguinte:

```json
{   "recipient_list_limit_update_requests" : [
        { 
            "limit_update_request_id": "c7a79970-b558-4425-998a-5cd6747c1c90",
            "analysis_status": "automatically_approved",
            "client_notification_status": "awaiting_notification_period",
            "recipient_status": "created",
            "recipient_list_limit_update_request_type" : "transaction_daytime",
            "event_date": "2019-10-01T10:37:25-03:00"
        },
        { 
            "limit_update_request_id": "c7a79970-b558-4425-998a-5cd6747c1c90",
            "analysis_status": "automatically_approved",
            "client_notification_status": "awaiting_notification_period",
            "recipient_status": "created",
            "recipient_list_limit_update_request_type" : "transaction_nighttime",
            "event_date": "2019-10-01T10:37:25-03:00"
        },
    ]
}
```

nome |	tipo |	descrição
:----: | :----: | ---------
recipient_id |	string |	Identificador único do Beneficiário desta Proposta de Modificação de Limite
analysis_status |	string |	Enumerador do analysis_status da proposta
client_notification_status |	string |	Enumerador do client_notification_status da proposta
recipient_status |	string |	Enumerador do recipient_status da proposta
recipient_list_limit_update_request_type |	  string |	Enumerador do recipient_list_limit_update_request_type da proposta
event_date |	string (ISO 8601) |	Data e hora da criação da Proposta de Modificação de Limite

---

# Padrões

URL: /documentation/caas/limits/standards

Para facilitar a integração e garantir a integridade da informação, foram definidos alguns padrões que são seguidos em toda a API.

## Valores Monetários
> Exemplos:

```
10000
12345
98741
1223
1
0
```

As APIs assumem que todos os valores monetários enviados são em Reais Brasileiros. Os valores devem ser enviados como inteiro em centavos.

## Data e Hora com Fuso Horário
> Alguns exemplos:

```
2019-10-15T22:35:12-03:00
2018-05-01T13:32:11+00:00
2019-05-01T00:00:00+00:00
```

É representada conforme a ISO 8601. Neste caso, o fuso-horário é colocado logo após o horário e deve representar o fuso do local onde aquele dado será valido. Por exemplo, se um aluguel estiver marcado para começar às 09:30 no aeroporto de Brasília, o horário enviado deverá ser representado por 09:30-03:00, se o aluguel estiver marcado para começar às 09:30 em Manaus, deverá ser representado por 09:30-04:00.

A máscara utilizada para validação é a seguinte:

`YYYY-MM-ddThh:mm:ss±hh:mm`

## Data e Hora sem Fuso Horario
> Alguns exemplos:

```
2019-10-15T22:35:12Z
2018-05-01T13:32:11Z
2019-05-01T00:00:00Z
```

É representada conforme a ISO 8601. Dados que independem de fuso-horário deverão ser enviados sem ele, sempre em UTC, com a letra Z indicando que este dado está em UTC. O seguinte formato, portanto, será validado:

`YYYY-MM-ddThh:mm:ssZ`

## Data
> Alguns exemplos

``` 
2019-10-15
2019-01-01
2017-03-20
```

No caso de campos que recebem somente data, uma data de nascimento, por exemplo, somente a data, sem nenhum horário deve ser enviada com o seguinte formato:

`YYYY-MM-dd`
 

## Documentos
Uma vez que os números de documento são bastante variados e muitos deles possuem caracteres que não se enquadram como numéricos, definem-se todos os números de documento como string. Outro bom motivo para definí-los como string é evitar que os zeros à esquerda desapareçam. Documentos previstos nesta página possuem uma máscara bem definida e estarão sujeitos a validação. O restante dos documentos, como RG, dada sua falta de padronização, não serão validados.

## CPF

> Exemplos de CPFs válidos contra a máscara definida:

```
123.456.789-12
321.987.543-23
111.283.333-00
```

> Exemplos de CPFs inválidos contra a máscara definida:

```
8.577.477-8
08.104.627/0001-23
123.456.789-1
23.456.789-01
```

O CPF é sempre definido como uma string e será validado conta a máscara:

`###.###.###-##`

## CNPJ

> Exemplos de CNPJs válidos contra a máscara definida:

```
08.104.627/0001-02
01.079.210/0114-67
32.402.502/0001-35
```

> Exemplos de CNPJs inválidos contra a máscara definida:

```
8.577.477-8
123.456.789-12
321.987.543-23
32.402.502/0001-3
032.402.502/0001-3
```

O CNPJ é sempre definido como uma string e será validado conta a máscara:

`##.###.###/####-##`

## IP

> Exemplos de IPs válidos contra a máscara definida:

```
201.81.161.86
201.081.161.86
201.81.161.086
201.81.0.1
```

> Exemplos de IPs inválidos:

```
201.81..86
358.81.161.86
201.81.161
```

IPs deverão ser enviados sempre em IPv4, zeros à esquerda poderão ou não ser enviados, respeitando a seguinte máscara:

`###.###.###.###`

---

# Dinâmica dos Status

URL: /documentation/caas/limits/status_dynamics

## Status de Análise (analysis_status)

O "analysis_status" indica o status da decisão da Política de Limites.

Os possíveis valores do "analysis_status" são os seguintes:

analysis_status | Descrição
:---------: | ---------
automatically_approved | a Política de Limites aprovou automaticamente esta solicitação de modificação de limite.
automatically_reproved | a Política de Limites reprovou automaticamente esta solicitação de modificação de limite.
in_manual_analysis | a Política de Limites delegou esta solicitação de modificação de limite para análise manual de mesa.
manually_approved | Após análise manual, o analista decidiu aprovar a modificação de limite.
manually_reproved | Após análise manual, o analista decidiu reprovar a modificação de limite.
reproved_by_time | A requisição foi reprovada pois o tempo de análise expirou.
pending | A requisição está pendente para ser processada.

## Status de Notificação do Cliente (client_notification_status)

O "client_notification_status" está relacionado ao período em que o cliente deve ser notificado sobre o andamento da solicitação de modificação de limite.

client_notification_status | Descrição
:---------: | ---------
awaiting_notification_period | Indica que a Janela de tempo para notificação do cliente ainda não iniciou.
in_notification_period | Indica que estamos na Janela de tempo para notificação do cliente.
notification_period_expired | Indica que a Janela de tempo para notificação do cliente já expirou.

## Status de Alteração de Limite (limit_update_request_status)

O "limit_update_request_status" está relacionado ao status da solicitação de modificação de limite.

limit_update_request_status | Descrição
:---------: | ---------
created | Indica que a requisição de mudança de limite foi criada.
applied | Indica que a requisição de mudança de limite foi aplicada.
canceled | Indica que a requisição de mudança de limite foi cancelada.

## Status de Alteração na lista de Beneficiários (recipient_list_append_request_status)

O "recipient_list_append_request_status" está relacionado ao status da solicitação de modificação na lista de beneficiários.

recipient_list_append_request_status | Descrição
:---------: | ---------
created | Indica que a requisição de mudança na lista de beneficiários foi criada.
applied | Indica que a requisição de mudança na lista de beneficiários foi aplicada.
canceled | Indica que a requisição de mudança na lista de beneficiários foi cancelada.

---

# Webhook

URL: /documentation/caas/limits/webhook

Webhook

Atualizações no status de fraude (Para Orders que sejam derivados para análise manual ou que sejam respondidos como Pendente) e para Sellers bloqueados, são notificados por meio de Webhook. Para tanto, é necessário, por meio da equipe do [suporte](mailto:suporte.caas@qitech.com.br), configurar um endereço do endpoint por onde vamos notificar as atualizações e também uma *signature_key* que será utilizada para assinar a requisição. Vale ressaltar que todos os envios de webhook serão feitos para um único endpoint.

No caso da atualização do status do pedido, o cliente pode também utilizar a técnica de [polling](https://en.wikipedia.org/wiki/Polling_(computer_science)). Neste caso, basta não configurar o endpoint de webhook e utilizar os endpoints de recuperação de Order para proceder com o polling.

:::info **Atenção**

Por questões de segurança, todas as requisições de Webhook serão somente realizadas em endpoints servidos por HTTPS.
:::

## Assinatura do Webhook

## Webhook de Atualização de Evento

Request Body

```json
    {
        "id": "123456",
        "analysis_status": "automatically_approved",
        "event_date": "2019-10-01T10:37:25-03:00"
    }
```

A requisição de atualização do status de análise de um evento possui o formato acima e notifica a mudança no status de fraude. O método utilizado é um PUT e o endereço do endpoint pode conter também o id do evento, de acordo com a necessidade do cliente. É importante ressaltar que o corpo da requisição é enviado como texto codificado em UTF-8.

## Retentativas

A notificação é considerada realizada quando recebe como resposta um HTTP Status 200. Caso as notificações falhem, serão feitas 7 retentativas, com os seguintes intervalos, até que um 200 seja retornado ou as tentativas terminem:

* 10 segundos
* 40 segundos
* 160 segundos
* 640 segundos
* 2560 segundos
* 10240 segundos
* 40960 segundos

---

# builder

URL: /documentation/caas/ocr/android/builder

## DocumentRecognition.Builder

| Parâmetro | Função | Obrigatório |
|------------|--------------|--------------|
|mobileToken |Chave do cliente que identifica que os dados coletados são provenientes do seu aplicativo. Caso ainda não tenha recebido o seu mobile-token, entre em contato com o <a href='mailto:suporte.caas@qitech.com.br'>suporte</a>.|Sim.|
|.setDocumentSteps(DocumentRecognitionStep[] documentSteps)|Define o fluxo de captura de documentos realizado pelo usuário. Mais informações [aqui](https://docs.zaig.com.br/android_ocr/#documentdetectorstep)|Sim.|
|.setSandboxEnvironment()|Caso este parâmetro seja utilizado no construtor, a biblioteca será configurada para enviar os dados ao ambiente de sandbox. Caso ausente, as requisições são enviadas para o ambiente production.|Não.|
|.showIntroductionScreens(Boolean showIntroductionScreens)|Quando "false" desativa as telas de introdução à coleta de foto do documento que aparecem para o usuário.|Não. O padrão é "true".|
|.setShowSuccessScreen(Boolean showSuccessScreen)|Quando "false" desativa a tela de sucesso após a coleta da foto.|Não. O padrão é "true".|
|.setBackgroundColor(String backgroundColor)|Permite a configuração da cor de background das activities do SDK.|Não. O padrão é "#ffffff".|
|.setFontColor(String fontColor)|Permite a configuração da cor da fonte e dos ícones das activities do SDK.|Não. O padrão é "#000000".|
| .setFontFamily(FontFamily fontFamily)| Permite a configuração da fonte das activities do SDK.| Não. Caso não seja informada o padrão é FontFamily.open_sans. Fontes disponíveis: FontFamily.open_sans, FontFamily.futura, FontFamily.verdana, FontFamily.roboto, FontFamily.poppins e FontFamily.helvetica.|Não.|
|.setVisualConfiguration([VisualConfiguration](https://docs.zaig.com.br/android_ocr/#o-objeto-visualconfiguration). visualConfiguration)| Utilizado para customizar as imagens mostradas para o usuário ao longo da execução do SDK.|Não.|
|.setTextConfiguration([TextConfiguration](https://docs.zaig.com.br/android_ocr/#o-objeto-textconfiguration). textConfiguration) | Utilizado para customizar os textos da tela introdutória de onboarding mostradas para o usuário ao longo da execução do SDK.|Não.|
|.setSessionId(String sessionId)| Utilizado para definir a chave que identifica a sessão iniciada no SDK. É usada para rastrear todo fluxo percorrido pelo usuário na execução da FaceRecon através de logs. Este campo aceita até 255 caracteres. |Não.|
|.setLogLevel(DocumentRecognition.LogLevel logLevel)| Utilizado para customizar o nível de verbosidade dos logs do SDK. Níveis disponíveis: LogLevel.debug, LogLevel.info, LogLevel.warn, LogLevel.error e LogLevel.trace. O padrão é LogLevel.debug. |Não.|
|.setAudioConfiguration(AudioConfiguration audioConfiguration)|Configura o guiamento por voz do SDK, que narra as instruções de captura em tempo real. As configurações aceitas são _AudioConfiguration.enable_, que exibe o botão de ligar/desligar áudio com a narração iniciando desligada; _AudioConfiguration.disable_, que desativa a narração e oculta o botão; e _AudioConfiguration.accessibility_, que exibe o botão com a narração iniciando ligada quando o dispositivo possui recursos de acessibilidade ativos. Com o TalkBack ativo, as instruções completas são entregues pelo próprio leitor de telas.|Não. O padrão é _AudioConfiguration.disable_.|

## O Objeto VisualConfiguration

| Parâmetro                                                                      | Função                                                                                                                                                                                                                                                              | Obrigatório             |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| .setOnboardingDrawable(int onboarding_drawable, int onboarding_width)          | Utilizado para configurar a imagem mostrada para o usuário na tela de onboarding do SDK. O parâmetro _onboarding_drawable_ deve referenciar o id da imagem a ser mostrada e _onboarding_width_ é o tamanho desejado de exibição desta imagem.                       | Não.                    |
| .setDocumentFullDrawable(int documentfull_drawable, int documentfull_width)    | Utilizado para configurar a imagem mostrada para o usuário na tela de captura de CNH inteira do SDK. O parâmetro _documentfull_drawable_ deve referenciar o id da imagem a ser mostrada e _documentfull_width_ é o tamanho desejado de exibição desta imagem.       | Não.                    |
| .setDocumentFrontDrawable(int documentfront_drawable, int documentfront_width) | Utilizado para configurar a imagem mostrada para o usuário na tela de captura de CNH e RG frente do SDK. O parâmetro _documentfront_drawable_ deve referenciar o id da imagem a ser mostrada e _documentfront_width_ é o tamanho desejado de exibição desta imagem. | Não.                    |
| .setDocumentBackDrawable(int documentback_drawable, int documentback_width)    | Utilizado para configurar a imagem mostrada para o usuário na tela de captura de CNH e RG verso do SDK. O parâmetro _documentback_drawable_ deve referenciar o id da imagem a ser mostrada e _documentback_width_ é o tamanho desejado de exibição desta imagem.    | Não.                    |
| .setButtonBorderSize(int border_size)                                          | Utilizado para configurar a largura de borda dos botões do SDK.                                                                                                                                                                                                     | Não. O padrão é _1_.    |
| .setButtonShadow(boolean button_shadow)                                        | Quando setado para _false_ remove o efeito de sombra, padrão no android, utilizado pelos botões do SDK.                                                                                                                                                             | Não. O padrão é _true_. |

## O Objeto TextConfiguration

| Parâmetro                                                                      | Função                                                                                                                                                                                                                                                              | Obrigatório             |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| .setCustomText(CustomLabel label, String text) | Utilizado para configurar os textos mostrados para o usuário na tela de onboarding do SDK| Não.|

---

# Coletando os Retornos

URL: /documentation/caas/ocr/android/collecting_response

Para obter o objeto **RequestResponseObject**, que contém as capturas obtidas pelo SDK, sobrescreva o método *onActivityResult* na mesma *activity* que você iniciou a **DocumentRecognitionActivity**:

```java
    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        super.onActivityResult(requestCode, resultCode, data);
        DocumentRecognition.RequestResponseObject result;
        if (requestCode == REQUEST_CODE){
            if (resultCode == RESULT_OK && data != null){
                DocumentRecognition.RequestResponseObject mRequestResponseObject = data.ParcelableExtra("result");
            }
        }
    }
```

### Descrição dos Atributos do Objeto RequestResponseObject

Atributo | Descrição
--------- | ---------
ocr_key | Chave de identificação da imagem fornecida que pode ser utilizada em qualquer outro serviço do sistema QI Tech.
template | Identifica a qual foto aquela OCR Key se refere.

---

# DocumentRecognitionStep

URL: /documentation/caas/ocr/android/document_step

O fluxo de captura de documentos que o usuário será submetido é definido através de um array de objetos do tipo **DocumentRecognitionStep** (disponível no SDK), em que cada elemento é um dos passos de captura realizado pelo usuário. 

```java
DocumentSteps = new DocumentRecognitionStep[]{
        new DocumentRecognitionStep(Document.cnh_front),
        new DocumentRecognitionStep(Document.cnh_back)
};
```

Acima, é implementado um fluxo que coletará do usuário primeiro a frente de seu CNH (cnh_front) e, depois de validada a coleta de uma foto de qualidade, o verso do CNH.

O objeto DocumentRecognitionStep pode assumir os seguintes valores:

```java
public enum Document {
    cnh, // Carteira Nacional de Habilitação brasileira completa
    cnh_front, // Carteira Nacional de Habilitação brasileira frente (Lado da foto)
    cnh_back, // Carteira Nacional de Habilitação brasileira frente (Lado da assinatura)
    cnh_digital, // PDF da Carteira Nacional de Habilitação brasileira digital
    rg_cin_digital, // PDF do RG digital ou da CIN digital emitidos pelo gov.br
    rg_front, // Carteira de Identidade brasileira frente (Lado da foto)
    rg_back, // Carteira de Identidade brasileira verso (Lado dos dados)
    proof_of_address, // Comprovante de Residência
    other // Outros documentos de identificação
}
```

---

# DocumentDetectorStep

URL: /documentation/caas/ocr/android/implementation_demo

O código a seguir é um exemplo de referência para a implementação correta do SDK em uma _activity_:

```java

import com.qitech.documentrecognition.Document;
import com.qitech.documentrecognition.DocumentRecognition;
import com.qitech.documentrecognition.DocumentRecognitionResponse;
import com.qitech.documentrecognition.DocumentRecognitionStep;
import com.qitech.documentrecognition.DocumentRecognitionActivity;

import java.util.ArrayList;

public class MainActivity extends AppCompatActivity implements View.OnClickListener {
    ConstraintLayout constraintLayout;
    ImageView backVector, iconVector;
    TextView textViewBack, textViewTitle, textViewDescription;
    Button buttonCNHfull, buttonCNH, buttonRG;
    DocumentRecognitionStep[] DocumentSteps;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_onboarding1);
        constraintLayout = findViewById(R.id.constraintLayout);
        backVector = findViewById(R.id.backVector);
        iconVector = findViewById(R.id.iconVector);
        textViewBack = findViewById(R.id.textViewBack);
        textViewTitle = findViewById(R.id.textViewTitle);
        textViewDescription = findViewById(R.id.textViewDescription);
        buttonCNH = findViewById(R.id.buttonCNH);
        buttonRG = findViewById(R.id.buttonRG);
        buttonCNHfull = findViewById(R.id.buttonCNHfull);

        constraintLayout.setBackgroundColor(Color.parseColor("#000000"));
        backVector.setColorFilter(Color.parseColor("#FFFFFF"));
        iconVector.setColorFilter(Color.parseColor("#FFFFFF"));
        textViewBack.setTextColor(Color.parseColor("#FFFFFF"));
        textViewTitle.setTextColor(Color.parseColor("#FFFFFF"));
        textViewDescription.setTextColor(Color.parseColor("#FFFFFF"));

        backVector.setOnClickListener(this);
        textViewBack.setOnClickListener(this);
        buttonCNH.setOnClickListener(this);
        buttonRG.setOnClickListener(this);
    }

    @Override
    public void onClick(View view) {
        if (view.getId() == R.id.textViewBack || view.getId() == R.id.backVector) {
            finish();
        }
        else if (view.getId() == R.id.buttonCNH) {
            Log.i("OnboardingActivity1Tag", "CNH document was chosen");
            DocumentSteps = new DocumentRecognitionStep[]{
                    new DocumentRecognitionStep(Document.cnh_front),
                    new DocumentRecognitionStep(Document.cnh_back)};
        } else if (view.getId() == R.id.buttonRG) {
            Log.i("OnboardingActivity1Tag", "RG document was chosen");
            DocumentSteps = new DocumentRecognitionStep[]{
                    new DocumentRecognitionStep(Document.rg_front),
                    new DocumentRecognitionStep(Document.rg_back)};
        } else if (view.getId() == R.id.buttonCNHfull) {
            Log.i("OnboardingActivity1Tag", "CNH full document was chosen");
            DocumentSteps = new DocumentRecognitionStep[]{
                    new DocumentRecognitionStep(Document.cnh)};
        }

        Intent intent = new Intent(getApplicationContext(), DocumentRecognitionActivity.class);
        DocumentRecognition mDocumentRecognition = new DocumentRecognition.Builder("d782a5be-2f96-452b-bf21-4d1bbfd0d710")
                .setDocumentSteps(DocumentSteps)
                .setBackgroundColor("#000000")
                .setFontColor("#FFFFFF")
                .setFontFamily(DocumentRecognition.FontFamily.open_sans)
                .setSessionId(String.valueOf(UUID.randomUUID()))
                .setLogLevel(FaceRecognition.LogLevel.debug)
                .build();
        intent.putExtra("settings", mDocumentRecognition);
        startActivityForResult(intent, 1);
        }

    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent data) {
        if (requestCode == 1){
            if (resultCode == RESULT_OK && data != null){
                Intent resultIntent = new Intent();
                setResult(RESULT_OK, resultIntent);
                ArrayList<DocumentRecognitionResponse> mDocumentRecognitionResponse = data.getParcelableArrayListExtra("DocumentRecognitionResponse");
                resultIntent.putParcelableArrayListExtra("DocumentRecognitionResponse", mDocumentRecognitionResponse);
                finish();
            } else {
                // o usuário fechou a activity
            }
        }
        super.onActivityResult(requestCode, resultCode, data);
    }
}

```

---

# Introdução

URL: /documentation/caas/ocr/android/introduction

Bem vindo ao SDK Android de OCR (Optical Character Recognition) para leitura de documentos da QI Tech. Este SDK realiza a captura de documentos e envio a API de OCR da QI Tech . Você pode utilizá-lo para capturar através do seu aplicativo uma imagem de um documento de seu cliente a ser reconhecido, como uma Carteira de Habilitação ou Cédula de identidade, e referenciá-lo através de uma chave nos demais produtos do sistema QI Tech.

## Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso [suporte](mailto:suporte.caas@qitech.com.br) e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

### Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.  
:::

---

# Integração nativa

URL: /documentation/caas/ocr/android/native_java

Para importar nossas SDKs, é necessário realizar alteração no _build.gradle_ de Projeto e de Aplicativo.

## Adicionando ao Projeto

Adicione o endereço de nosso repositório maven no _build.gradle_ do projeto (no Android Studio este arquivo aparece como: **"Project: \{nome_do_projeto\}"**), conforme exemplo abaixo.

```java
maven { url 'https://sdks.qitech.com.br/' }
```

## Adicionando ao Aplicativo

Após isso, adicione a biblioteca que você pretende importar em seu build.gradle do app (no Android Studio este arquivo aparece como: **"Module: \{nome_do_projeto\}.app"**), incluindo a dependência apresentada abaixo.

```java
dependencies {
    implementation 'com.qitech.android:documentrecognition:v5.1.0'
}
```

:::warning
Desde **abril de 2025**, novas políticas da Google Play requerem **Android API Level 35** para que aplicativos possam ser publicados
ou atualizados na Google Play Store. Por isso recomendamos fortemente que utilize **targetSdkVersion na versão 35** pelo menos.
:::

:::info
A utilização de **targetSdkVersion 35** implica na utilização do **compileSdkVersion 35**, o que desencadeia alguns **requisitos mínimos** para ferramentas
do ecossistema do Android:
* compileSdkVersion 35 --> AGP 8.6.0
* AGP 8.6.0 --> Gradle 8.7
* AGP 8.6.0 --> Java 17 (JDK 17)
* AGP 8.6.0 --> Kotlin 2+
:::

## Iniciando o SDK

Para incorporar o SDK ao seu aplicativo você deve realizar a configuração do seu aplicativo de captura personalizado através de um componente Builder e submetê-lo como parâmetro via Intent Extra para a DocumentRecognitionActivity.

```java
Intent intent = new Intent(context, DocumentRecognitionActivity.class);

var onboardingTextConfiguration = new OnboardingTextConfiguration(
    "Conselhos relevantes",                   // Título
    "Esteja com o documento visível",         // Primeira Instrução
    "Encaixe seu documento nas marcas",       // Segunda Instrução
    "Retire o plastico que cobre o documento" // Terceira Instrução
);

DocumentRecognition mDocumentRecognition = new DocumentRecognition.Builder(sand_mobile_token)
    .setDocumentSteps(DocumentSteps)
    .setSandboxEnvironment()
    .setSessionId("SESSION_ID")
    .setFontColor("#000000")
    .setBackgroundColor("#FFFFFF")
    .setFontFamily(DocumentRecognition.FontFamily.open_sans)
    .setShowIntroductionScreens(true)
    .setShowSuccessScreen(true)
    .setOnboardingTextConfiguration(onboardingTextConfiguration)
    .setLogLevel(DocumentRecognition.LogLevel.debug)
    .build();

intent.putExtra("settings", mDocumentRecognition);
startActivityForResult(intent, REQUEST_CODE);
```

**Versões anteriores à v4.0.0**
    ```java
    Intent intent = new Intent(context, DocumentRecognitionActivity.class);

    VisualConfiguration visualConfiguration = new VisualConfiguration()
            .setOnboardingDrawable(R.drawable.introscreen,500)
            .setDocumentFrontDrawable(R.drawable.documentfront, 500)
            .setDocumentBackDrawable(R.drawable.documentback, 500);

    TextConfiguration textConfiguration = new TextConfiguration()
            .setCustomText(TextConfiguration.CustomLabel.onboardingTitle, "Vamos começar!")
            .setCustomText(TextConfiguration.CustomLabel.onboardingFirstLabel, "- Vá para um local iluminado")
            .setCustomText(TextConfiguration.CustomLabel.onboardingSecondLabel, "- Retire o documento do plástico")
            .setCustomText(TextConfiguration.CustomLabel.onboardingThirdLabel, "- Insira seu documento na moldura, aguardando que fique verde para realizar a captura.");

    DocumentRecognition mDocumentRecognition = new DocumentRecognition.Builder("YOUR_MOBILE_TOKEN_SENT_BY_QITECH")
            .setDocumentSteps(DocumentSteps)
            .setVisualConfiguration(visualConfiguration)
            .setTextConfiguration(textConfiguration)
            .showIntroductionScreens(true)
            .setShowSuccessScreen(false)
            .setBackgroundColor("#000000")
            .setFontColor("#FFFFFF")
            .setFontFamily(DocumentRecognition.FontFamily.open_sans)
            .setSessionId("SESSION_ID")
            .setLogLevel(DocumentRecognition.LogLevel.debug)
            .build();
    intent.putExtra("settings", mDocumentRecognition);
    startActivityForResult(intent, REQUEST_CODE);
    ```

Utilizamos um Mobile Token para permitir o acesso autenticado do seu aplicativo a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso ainda não tenha recebido o seu token, envie um e-mail para suporte.caas@qitech.com.br .

Nossa API espera receber o Mobile Token em todas as requisições ao nosso servidor vindas do SDK, portanto, este deve ser obrigatoriamente incluido como parâmetro de configuração através do método mencionado anteriormente.

:::info **Atenção**

Você deve substituir "YOUR_MOBILE_TOKEN_SENT_BY_QITECH" com o Mobile Token recebido do suporte.
:::

## DocumentRecognition.Builder

| Parâmetro | Função | Obrigatório |
|------------|--------------|--------------|
|mobileToken |Chave do cliente que identifica que os dados coletados são provenientes do seu aplicativo. Caso ainda não tenha recebido o seu mobile-token, entre em contato com o mailto: suporte.caas@qitech.com.br.|Sim.|
|.setDocumentSteps(DocumentRecognitionStep[] documentSteps)|Define o fluxo de captura de documentos realizado pelo usuário. Mais informações [aqui](/documentation/caas/ocr/android/document_step)|Sim.|
|.setSandboxEnvironment()|Caso este parâmetro seja utilizado no construtor, a biblioteca será configurada para enviar os dados ao ambiente de sandbox. Caso ausente, as requisições são enviadas para o ambiente production.|Não.|
|.setSessionId(String sessionId)| Utilizado para definir a chave que identifica a sessão iniciada no SDK. É usada para rastrear todo fluxo percorrido pelo usuário na execução da OCR através de logs. Este campo aceita até 255 caracteres. |Não.|
|.setFontColor(String fontColor)|Permite a configuração da cor da fonte e dos ícones das activities do SDK.|Não. O padrão é "#1C49A5".|
|.setBackgroundColor(String backgroundColor)|Permite a configuração da cor de background das activities do SDK.|Não. O padrão é "#FCFCFC".|
|.setFontFamily(FontFamily fontFamily)| Permite a configuração da fonte das activities do SDK.| Não. Caso não seja informada o padrão é FontFamily.open_sans. Fontes disponíveis: FontFamily.open_sans, FontFamily.futura, FontFamily.verdana, FontFamily.roboto, FontFamily.poppins e FontFamily.helvetica.|Não.|
|.showIntroductionScreens(Boolean showIntroductionScreens)|Quando "false" desativa as telas de introdução à coleta de foto do documento que aparecem para o usuário.|Não. O padrão é "true".|
|.setShowSuccessScreen(Boolean showSuccessScreen)|Quando "false" desativa a tela de sucesso após a coleta da foto.|Não. O padrão é "true".|
|.setOnboardingTextConfiguration(OnboardingTextConfiguration onboardingTextConfiguration) |Permite a customização das instruções na tela de introdução. | Não.|
|.setLogLevel(DocumentRecognition.LogLevel logLevel)| Utilizado para customizar o nível de verbosidade dos logs do SDK. Níveis disponíveis: LogLevel.debug, LogLevel.info, LogLevel.warn, LogLevel.error e LogLevel.trace. O padrão é LogLevel.debug. |Não.|
|.setAudioConfiguration(AudioConfiguration audioConfiguration)| Configura o guiamento por voz do SDK, que narra as instruções de captura em tempo real. As configurações aceitas são _AudioConfiguration.enable_, que exibe o botão de ligar/desligar áudio com a narração iniciando desligada; _AudioConfiguration.disable_, que desativa a narração e oculta o botão; e _AudioConfiguration.accessibility_, que exibe o botão com a narração iniciando ligada quando o dispositivo possui recursos de acessibilidade ativos. Com o TalkBack ativo, as instruções completas são entregues pelo próprio leitor de telas. |Não.|

**Versões anteriores à v4.0.0**
    | Parâmetro | Função | Obrigatório |
    |------------|--------------|--------------|
    |mobileToken |Chave do cliente que identifica que os dados coletados são provenientes do seu aplicativo. Caso ainda não tenha recebido o seu mobile-token, entre em contato com o mailto: suporte.caas@qitech.com.br.|Sim.|
    |.setDocumentSteps(DocumentRecognitionStep[] documentSteps)|Define o fluxo de captura de documentos realizado pelo usuário. Mais informações [aqui](/documentation/caas/ocr/android/document_step)|Sim.|
    |.setSandboxEnvironment()|Caso este parâmetro seja utilizado no construtor, a biblioteca será configurada para enviar os dados ao ambiente de sandbox. Caso ausente, as requisições são enviadas para o ambiente production.|Não.|
    |.showIntroductionScreens(Boolean showIntroductionScreens)|Quando "false" desativa as telas de introdução à coleta de foto do documento que aparecem para o usuário.|Não. O padrão é "true".|
    |.setShowSuccessScreen(Boolean showSuccessScreen)|Quando "false" desativa a tela de sucesso após a coleta da foto.|Não. O padrão é "true".|
    |.setBackgroundColor(String backgroundColor)|Permite a configuração da cor de background das activities do SDK.|Não. O padrão é "#ffffff".|
    |.setFontColor(String fontColor)|Permite a configuração da cor da fonte e dos ícones das activities do SDK.|Não. O padrão é "#000000".|
    | .setFontFamily(FontFamily fontFamily)| Permite a configuração da fonte das activities do SDK.| Não. Caso não seja informada o padrão é FontFamily.open_sans. Fontes disponíveis: FontFamily.open_sans, FontFamily.futura, FontFamily.verdana, FontFamily.roboto, FontFamily.poppins e FontFamily.helvetica.|Não.|
    |.setVisualConfiguration(VisualConfiguration visualConfiguration)| Utilizado para customizar as imagens mostradas para o usuário ao longo da execução do SDK.|Não.|
    |.setTextConfiguration(TextConfiguration textConfiguration) | Utilizado para customizar os textos da tela introdutória de onboarding mostradas para o usuário ao longo da execução do SDK.|Não.|
    |.setSessionId(String sessionId)| Utilizado para definir a chave que identifica a sessão iniciada no SDK. É usada para rastrear todo fluxo percorrido pelo usuário na execução da OCR através de logs. Este campo aceita até 255 caracteres. |Não.|
    |.setLogLevel(DocumentRecognition.LogLevel logLevel)| Utilizado para customizar o nível de verbosidade dos logs do SDK. Níveis disponíveis: LogLevel.debug, LogLevel.info, LogLevel.warn, LogLevel.error e LogLevel.trace. O padrão é LogLevel.debug. |Não.|

## O Objeto VisualConfiguration
:::warning
__DEPRECADO__ A PARTIR DA **v4.0.0**!
:::

| Parâmetro                                                                      | Função                                                                                                                                                                                                                                                              | Obrigatório             |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| .setOnboardingDrawable(int onboarding_drawable, int onboarding_width)          | Utilizado para configurar a imagem mostrada para o usuário na tela de onboarding do SDK. O parâmetro _onboarding_drawable_ deve referenciar o id da imagem a ser mostrada e _onboarding_width_ é o tamanho desejado de exibição desta imagem.                       | Não.                    |
| .setDocumentFullDrawable(int documentfull_drawable, int documentfull_width)    | Utilizado para configurar a imagem mostrada para o usuário na tela de captura de CNH inteira do SDK. O parâmetro _documentfull_drawable_ deve referenciar o id da imagem a ser mostrada e _documentfull_width_ é o tamanho desejado de exibição desta imagem.       | Não.                    |
| .setDocumentFrontDrawable(int documentfront_drawable, int documentfront_width) | Utilizado para configurar a imagem mostrada para o usuário na tela de captura de CNH e RG frente do SDK. O parâmetro _documentfront_drawable_ deve referenciar o id da imagem a ser mostrada e _documentfront_width_ é o tamanho desejado de exibição desta imagem. | Não.                    |
| .setDocumentBackDrawable(int documentback_drawable, int documentback_width)    | Utilizado para configurar a imagem mostrada para o usuário na tela de captura de CNH e RG verso do SDK. O parâmetro _documentback_drawable_ deve referenciar o id da imagem a ser mostrada e _documentback_width_ é o tamanho desejado de exibição desta imagem.    | Não.                    |
| .setButtonBorderSize(int border_size)                                          | Utilizado para configurar a largura de borda dos botões do SDK.                                                                                                                                                                                                     | Não. O padrão é _1_.    |
| .setButtonShadow(boolean button_shadow)                                        | Quando setado para _false_ remove o efeito de sombra, padrão no android, utilizado pelos botões do SDK.                                                                                                                                                             | Não. O padrão é _true_. |

## O Objeto TextConfiguration
:::warning
__DEPRECADO__ A PARTIR DA **v4.0.0**!
:::

| Parâmetro                                      | Função                                                                                    | Obrigatório |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------- | ----------- |
| .setCustomText(CustomLabel label, String text) | Utilizado para configurar os textos mostrados para o usuário na tela de onboarding do SDK | Não.        |

---

# using_sdk

URL: /documentation/caas/ocr/android/using_sdk

## Iniciando o SDK

Para incorporar o SDK ao seu aplicativo você deve realizar a configuração do seu aplicativo de captura personalizado através de um componente Builder e submetê-lo como parâmetro via Intent Extra para a DocumentRecognitionActivity.

```java
  Intent intent = new Intent(context, DocumentRecognitionActivity.class);

  VisualConfiguration visualConfiguration = new VisualConfiguration()
          .setOnboardingDrawable(R.drawable.introscreen,500)
          .setDocumentFrontDrawable(R.drawable.documentfront, 500)
          .setDocumentBackDrawable(R.drawable.documentback, 500);

  TextConfiguration textConfiguration = new TextConfiguration()
           .setCustomText(TextConfiguration.CustomLabel.onboardingTitle, "Vamos começar!")
           .setCustomText(TextConfiguration.CustomLabel.onboardingFirstLabel, "- Vá para um local iluminado")
           .setCustomText(TextConfiguration.CustomLabel.onboardingSecondLabel, "- Retire o documento do plástico")
           .setCustomText(TextConfiguration.CustomLabel.onboardingThirdLabel, "- Insira seu documento na moldura, aguardando que fique verde para realizar a captura.");

  DocumentRecognition mDocumentRecognition = new DocumentRecognition.Builder("YOUR_MOBILE_TOKEN_SENT_BY_QITECH")
          .setDocumentSteps(DocumentSteps)
          .setVisualConfiguration(visualConfiguration)
          .setTextConfiguration(textConfiguration)
          .showIntroductionScreens(true)
          .setShowSuccessScreen(false)
          .setBackgroundColor("#000000")
          .setFontColor("#FFFFFF")
          .setFontFamily(DocumentRecognition.FontFamily.open_sans)
          .setSessionId("SESSION_ID")
          .setLogLevel(FaceRecognition.LogLevel.debug)
          .build();
  intent.putExtra("settings", mDocumentRecognition);
  startActivityForResult(intent, REQUEST_CODE);
```

Utilizamos um Mobile Token para permitir o acesso autenticado do seu aplicativo a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso ainda não tenha recebido o seu token, envie um e-mail para suporte.caas@qitech.com.br .

Nossa API espera receber o Mobile Token em todas as requisições ao nosso servidor vindas do SDK, portanto, este deve ser obrigatoriamente incluido como parâmetro de configuração através do método mencionado anteriormente.

:::info **Atenção**

Você deve substituir "YOUR_MOBILE_TOKEN_SENT_BY_QITECH" com o Mobile Token recebido do suporte.
:::

---

# authentication

URL: /documentation/caas/ocr/api/authentication

## Autenticação
> Para autenticar uma chamada, utilize o código seguinte:

```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE_API_KEY"
```

> Substitua a API key 'EXAMPLE_API_KEY' com a sua chave adquirida com o nosso suporte.

Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br .

Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:

`Authorization: EXAMPLE_API_KEY`

:::info **Atenção**

Você deve substituir EXAMPLE_API_KEY com a API Key recebida do suporte.
:::

---

# Status HTTP

URL: /documentation/caas/ocr/api/http_status

Todas as APIs da QI Tech utilizam a seguinte padronização nos status HTTP de retorno, de acordo com o RFC 7231 :

Status HTTP | Significado | Descrição
---------- | ------- | ---------------------------------
400 | Bad Request | A requisição enviada possui algum erro de formatação. Na maioria dos casos, retornamos no corpo da mensagem uma explicação de onde está o erro.
401 | Unauthorized | Houve algum problema na autenticação, verifique se a API Key está correta e no header correto, de acordo com a seção Autenticação .
403 | Forbidden | O endpoint acessado é de uso interno e não está disponível para esta API Key.
404 | Not Found | O dado requisitado não foi encontrado usando a chave utilizada. Este status também é retornado quando um endpoint inválido é requisitado.
405 | Method Not Allowed | O método HTTP utilizado não se aplica ao endpoint utilizado.
406 | Not Acceptable | Os dados enviados no corpo da requisição são inválidos. Em geral, isso significa que os dados enviados não são um JSON válido.
409 | Conflict | O id da requisição corresponde a um id já processado anteriormente. Este status é retornado no caso de requisições duplicadas enviadas ao servidor.
500 | Internal Server Error | Tivemos um problema para processar esta requisição, ao encontrarmos esse erro nossos especialistas são automaticamente notificados e iniciam a análise e solução imediatamente.
503 | Service Unavailable | Você se deparou com uma indisponibilidade, planejada ou não, de infraestrutura dos nossos servidores.

---

# Introdução

URL: /documentation/caas/ocr/api/introduction

Bem vindo à API de OCR (Optical Character Recognition) para leitura de documentos da QI Tech. Você pode utilizar esta API para enviar uma imagem de um documento a ser reconhecido, como uma Carteira de Habilitação ou Cédula de identidade, e referenciá-lo através de uma chave nos demais produtos do sistema QI Tech.

## Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso suporte e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

### Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

## Ambientes

Possuímos dois ambientes para os nossos clientes. As URLs base das APIs são:

* Produção - `https://api.caas.qitech.app/ocr/`
* Sandbox - `https://api.sandbox.caas.qitech.app/ocr/`

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.  
:::

## Somente HTTPS

Por questão de segurança, toda a comunicação com as APIs da QI Tech deve ser realizada utilizando a comunicação HTTPS. Para evitar que, por desatenção ou outro motivo, sejam feitas chamadas HTTP, este servidor somente disponibiliza a porta 443 com comunicação TLS 1.2. Chamadas realizadas utilizando outros protocolos serão automaticamente negadas.

## Autenticação
> Para autenticar uma chamada, utilize o código seguinte:

```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE_API_KEY"
```

> Substitua a API key 'EXAMPLE_API_KEY' com a sua chave adquirida com o nosso suporte.

Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br .

Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:

`Authorization: EXAMPLE_API_KEY`

:::info **Atenção**

Você deve substituir EXAMPLE_API_KEY com a API Key recebida do suporte.
:::

---

# quality

URL: /documentation/caas/ocr/api/quality

## Validação de qualidade da imagem

Request Body: Caso de imagem inválida

```json
    {
        "title": "document_quality",
        "description": "A imagem enviada não pode ser processada com êxito."
    }
```

Ao realizar um post no endpoint de imagem, caso a imagem não seja suficiente para validação, um HTTP Status Code 400 será retornado, como pode ser visto no exemplo ao lado. O Status Code 400 também é retornado quando o documento não atende aos requisitos de imagem, citados anteriormente.

**Atenção -** Existem outros motivos pelos quais retornamos 400 (Todos relacionados a dados inválidos). Somente os retornos com o title "document_quality" são resultantes de uma validação de má qualidade da imagem e portanto devem ser repassados ao usuário.

---

# Enviando um Documento

URL: /documentation/caas/ocr/api/send_image

Envie um documento utilizando o endpoint `/image` conforme indicado abaixo. Este endpoint retornará um identificador GUID (Globally Unique Identifier) para o documento, que poderá então ser referenciado nos demais serviços do sistema QI Tech.

## Envio
Para enviar um documento, basta realizar via método POST o envio do código base64 da imagem em formato json para o seguinte endereço:

`https://api.caas.qitech.app/ocr/image`

Request Body

```json
  {
    "document_b64": "\<BASE64_IMAGE\>",
    "template": "cnh",
    "file_type": "jpeg"
  }
```

Substitua o código base64 de seu documento documento no lugar do placeholder.

### Descrição dos Atributos de Envio

Atributo | Descrição
--------- | ---------
document_b64 | Campo obrigatório. Imagem do documento a ser análisado em formato base64.
template | Campo obrigatório. Declara o template que deve ser aplicado para análise da imagem.
file_type | Campo facultativo. Identifica o formato do arquivo enviado, `jpeg` ou `pdf`. Caso não seja enviado, o valor `jpeg` é assumido.

### Templates disponíveis
Neste momento, a QI Tech apresenta os seguintes templates disponíveis para análise OCR. Caso o seu documento necessário não esteja incluso nesta lista, envie um e-mail para suporte.caas@qitech.com.br e informe-se dos detalhes quanto a implementação desta feature.

Template | Descrição
--------- | ---------
cnh | Carteira Nacional de Habilitação brasileira completa.
cnh_front | Carteira Nacional de Habilitação brasileira frente (Lado da foto).
cnh_back | Carteira Nacional de Habilitação brasileira frente (Lado da assinatura).
cnh_digital | PDF da Carteira Nacional de Habilitação brasileira digital.
rg_front | Carteira de Identidade brasileira frente (Lado da foto).
rg_back | Carteira de Identidade brasileira verso (Lado dos dados).
danfe | Documento Auxiliar da Nota Fiscal Eletrônica (NF-e).
proof_of_address | Comprovante de residência.
letter_of_attorney | Procuração que concede poderem com relação a uma empresa.
company_statute | Contrato social ou estatudo de uma empresa.

## Imagem
Visando garantir uma maior confiabilidade das análises executadas, é necessário que o cliente siga algumas regras na hora de tirar a foto:

* Remova o documento do plástico;
* Garanta que o documento encontra-se centralizado na foto;
* Garanta que o documento esteja iluminado;
* Garanta que todos os dados do documento estejam nítidos, visíveis e legíveis;
* Garanta que a foto esteja visível e nítida.

## Requisitos da Imagem
Para o funcionamento adequado da API, atente-se aos seguintes parâmetros.

* A imagem deve estar em formato JPEG ou PDF;
* A imagem deve possuir, ao menos, 500 pixels de altura e 500 pixels de largura;
* A API não suporta a leitura de documentos escritos à mão;
* O tamanho máximo da imagem varia de acordo com o formato escolhido, seguindo os limites a seguir:

Formato | Tamanho máximo suportado
--------- | ---------
.JPEG | 3MB
.PNG | 10MB
.PDF | 30MB

## Resposta
Caso sua requisição de leitura de documento seja processada com sucesso, será retornado um HTTP status 200 e um objeto JSON com o identificador que aponta para o documento que foi enviada.

Response Body

```json
    {
        "ocr_key": "f1c0d2e1-f950-4360-896d-36588e443fc9"
    }   
```

### Descrição dos Atributos de Resposta

Atributo | Descrição
--------- | ---------
ocr_key | Chave de identificação da imagem fornecida que pode ser utilizada em qualquer outro serviço do sistema QI Tech.

## Recuperação de um documento
> Recuperação de imagem

```shell
    curl "https://api.caas.qitech.app/ocr/image/f4b5337a-7b50-406e-8c8e-7d0e77b5aa02/file" \
         -H "Authorization: EXAMPLE_API_KEY"
```

Em qualquer momento é possível recuperar as imagens enviadas. Para isso, basta enviar  uma requisição **GET** adequadamente autenticada no endpoint:

`https://api.caas.qitech.app/ocr/image/{image_key}/file`

Onde image_key é o valor retornado durante o envio da imagem.

## Validação de qualidade da imagem

Response Body: Caso de imagem inválida

```json
    {
        "title": "document_quality",
        "description": "A imagem enviada não pode ser processada com êxito."
    }
```

Ao realizar um post no endpoint de imagem, caso a imagem não seja suficiente para validação, um HTTP Status Code 400 será retornado, como pode ser visto no exemplo ao lado. O Status Code 400 também é retornado quando o documento não atende aos requisitos de imagem, citados anteriormente.

**Atenção -** Existem outros motivos pelos quais retornamos 400 (Todos relacionados a dados inválidos). Somente os retornos com o title "document_quality" são resultantes de uma validação de má qualidade da imagem e portanto devem ser repassados ao usuário.

## Validação de qualidade do rosto

A validação de qualidade da imagem é aplicada **exclusivamente a documentos que contêm rostos**, como RG, CNH e passaportes. Quando uma imagem é enviada ao sistema, se ela for identificada como um dos tipos abaixo, uma **análise de face é realizada automaticamente**:

- `national_migration_registry_front`
- `passport_front`
- `ctps_front`
- `regional_nursing_council_registry_front`
- `regional_nursing_council_registry`
- `national_registry_of_foreigners_back`
- `passport`
- `national_migration_registry`
- `national_registry_of_foreigners`
- `cnh_digital`
- `rg_front`
- `rg`
- `cnh_front`
- `cnh`

Durante essa análise, o sistema verifica se há **um rosto visível na imagem** e avalia aspectos como:

- Iluminação adequada (brilho);
- Presença de acessórios como óculos escuros;
- Proximidade ou distância excessiva do rosto;
- Ausência total de rostos na imagem.

Se algum desses critérios indicar que a imagem não está adequada, será retornado um erro com `title: "face_validation"` e o respectivo `description`, conforme detalhado abaixo.

```json
{
    "title": "face_validation",
    "description": "<código_de_erro>"
}
```

### Exemplo de retorno:

**Nenhum rosto detectado**

```json
{
    "title": "face_validation",
    "description": "no_faces"
}
```

---

### Tabela de tradução de mensagens para exibição ao usuário

| Código de erro (`description`) | Mensagem amigável |
|-------------------------------|-------------------|
| `close_face`                  | A imagem foi capturada muito próxima do rosto. Reposicione o documento. |
| `distant_face`                | A imagem foi capturada muito distante do rosto. Reposicione o documento. |
| `wearing_acessories`          | A pessoa na imagem está usando óculos escuros ou acessórios que cobrem os olhos. |
| `brightness_problem`          | A imagem está muito escura. Reenvie com mais iluminação. |
| `no_faces`                    | Não foi possível detectar um rosto na imagem. Verifique se o rosto está visível. |

---

# Coletando os Retornos

URL: /documentation/caas/ocr/flutter/collecting_response

O método `startOcr` retorna um `Future `. Não é necessário realizar nenhuma decodificação manual de JSON — o plugin já entrega objetos Dart tipados.

## OcrReturnValues

```dart
class OcrReturnValues {
  final List<DocumentRecognitionItem> documentRecognitionResponse;
}
```

| Atributo | Tipo | Descrição |
|----------|------|-----------|
|documentRecognitionResponse|List<DocumentRecognitionItem>|Lista com uma entrada por captura realizada pelo usuário.|

## DocumentRecognitionItem

```dart
class DocumentRecognitionItem {
  final String? ocrKey;
  final String? ocrFrontKey;
  final String? ocrBackKey;
  final String documentType;
}
```

| Atributo | Tipo | Descrição |
|----------|------|-----------|
|ocrKey|String?|Chave de identificação da imagem, presente em documentos de captura única (`cnhFull`, `cnhDigital`, `address`, `rgCinDigital`). Pode ser utilizada em qualquer outro serviço do sistema QI Tech.|
|ocrFrontKey|String?|Chave de identificação da imagem da frente, presente em documentos de captura dupla (`cnh`, `rg`, `rne`, `crnm`).|
|ocrBackKey|String?|Chave de identificação da imagem do verso, presente em documentos de captura dupla (`cnh`, `rg`, `rne`, `crnm`).|
|documentType|String|Identifica a qual documento aquela chave se refere (ex.: `"cnh"`, `"rg"`, `"proof_of_address"`).|

:::info **Importante**
Armazene as chaves retornadas — elas são o identificador da imagem nos demais produtos do sistema QI Tech, como a API de Onboarding.
:::

## Exemplo de leitura do retorno

```dart
final result = await plugin.startOcr(
  CaaSEnvironment.sandbox,
  '<YOUR_MOBILE_TOKEN_SENT_BY_QITECH>',
  CaaSDocumentType.cnh,
);

for (final item in result.documentRecognitionResponse) {
  if (item.ocrKey != null) {
    print('Ocr key: ${item.ocrKey} document type: ${item.documentType}');
  }
  if (item.ocrFrontKey != null) {
    print('Ocr front key: ${item.ocrFrontKey} document type: ${item.documentType}');
  }
  if (item.ocrBackKey != null) {
    print('Ocr back key: ${item.ocrBackKey} document type: ${item.documentType}');
  }
}
```

## Tratamento de erros

:::warning Atenção
Diferentemente de `startFaceRecon`, que lança uma `FaceReconException` tipada, o método `startOcr` lança uma **String** com a mensagem de erro. Utilize um `catch (e)` genérico.
:::

```dart
try {
  final result = await plugin.startOcr(
    CaaSEnvironment.sandbox,
    '<YOUR_MOBILE_TOKEN_SENT_BY_QITECH>',
    CaaSDocumentType.cnh,
  );
  // ...
} catch (e) {
  print('Erro ao executar o OCR: $e');
}
```

### Mensagens de erro mais comuns

| Mensagem | Significado |
|----------|-------------|
|`User canceled OCR`|O usuário interrompeu o fluxo de captura antes de concluí-lo.|
|`Error executing OCR: <detalhe>`|O SDK nativo de iOS encerrou o fluxo com erro.|
|`at startOcr: <detalhe>`|Algum parâmetro obrigatório não foi informado na chamada.|
|`Activity is null`|No Android, o SDK não conseguiu obter a _activity_ hospedeira.|

---

# Compatibilidade

URL: /documentation/caas/ocr/flutter/compatibility

O plugin `flutter_kyc_qitech` exige as seguintes versões mínimas:

| Configuração | Versão mínima |
|------------|--------------|
|Flutter|3.3.0|
|Dart SDK|3.2.3|
|iOS|15.5|
|Android API Level|35 (Android 15 Vanilla Ice Cream)|
|Gradle|8.6.0|
|Android Gradle Plugin (AGP)|8.7|
|Kotlin|2.0.21 (recomendado)|
|Datadog SDK nativo (iOS, trazido pelo plugin)|3.x|
|MLKit FaceDetection (iOS, caso já utilizado no seu app)|8.x|

## Versão atual do plugin

| Plugin | Versão |
|--------|--------|
|`flutter_kyc_qitech`|`^5.3.0`|

:::warning Atenção
Nossos SDKs de iOS não suportam ser compilados para simuladores em máquinas com arquitetura **arm64** (MacBooks M1/M2/M3/M4), a menos que o **Rosetta** esteja ativo, traduzindo a arquitetura x86_64 para arm64. Recomendamos o uso de dispositivos físicos para testes.
:::

---

# Implementação

URL: /documentation/caas/ocr/flutter/example

O método `startOcr` abre o fluxo nativo de captura de documento, envia as imagens para a API de OCR da QI Tech e devolve as chaves das imagens processadas.

## Mobile Token

Utilizamos um Mobile Token para permitir o acesso autenticado do seu aplicativo à nossa API. Ele provavelmente já foi enviado por e-mail para você. Caso ainda não tenha recebido o seu token, envie um e-mail para suporte.caas@qitech.com.br .

:::info **Atenção**
Cada ambiente (`sandbox` e `production`) exige um Mobile Token diferente.
:::

## Assinatura do método

```dart
Future<OcrReturnValues> startOcr(
  CaaSEnvironment environment,
  String mobileToken,
  CaaSDocumentType document, {
  OcrOptions? options,
})
```

Os três primeiros parâmetros são posicionais e obrigatórios. As customizações são opcionais e passadas pelo parâmetro nomeado `options`, descrito em [O objeto OcrOptions](/documentation/caas/ocr/flutter/ocr_options).

## Exemplo mínimo

```dart
import 'package:flutter_kyc_qitech/flutter_kyc_qitech.dart';

final _qitechFlutterKycPlugin = FlutterKycQitech();

final result = await _qitechFlutterKycPlugin.startOcr(
  CaaSEnvironment.sandbox,
  '<YOUR_MOBILE_TOKEN_SENT_BY_QITECH>',
  CaaSDocumentType.cnh,
);

for (final item in result.documentRecognitionResponse) {
  print('${item.documentType}: ${item.ocrKey ?? item.ocrFrontKey ?? item.ocrBackKey}');
}
```

## Exemplo completo

```dart
import 'package:flutter/material.dart';
import 'package:flutter_kyc_qitech/flutter_kyc_qitech.dart';

class OcrButton extends StatelessWidget {
  const OcrButton({super.key});

  static const String _mobileToken = '<YOUR_MOBILE_TOKEN_SENT_BY_QITECH>';

  Future<void> _startOcr() async {
    final plugin = FlutterKycQitech();

    try {
      final result = await plugin.startOcr(
        CaaSEnvironment.sandbox,
        _mobileToken,
        CaaSDocumentType.cnh,
        options: OcrOptions(
          sessionId: '<SESSION_ID>',
          fontColor: '#FFFFFF',
          backgroundColor: '#000000',
          fontFamily: CaaSFontFamily.openSans,
          showIntroductionScreens: true,
          showSuccessScreen: false,
          audioConfiguration: FaceReconAudioConfiguration.enable,
          onboardingTextConfiguration: OnboardingTextConfiguration(
            onboardingTitle: 'Dicas Importantes',
            onboardingFirstLabel: 'Vá para um local iluminado',
            onboardingSecondLabel: 'Retire o documento do plástico',
            onboardingThirdLabel: 'Garanta que o documento está corretamente enquadrado',
          ),
          logLevel: CaaSLogLevel.debug,
        ),
      );

      for (final item in result.documentRecognitionResponse) {
        if (item.ocrKey != null) {
          print('Ocr key: ${item.ocrKey} document type: ${item.documentType}');
        }
        if (item.ocrFrontKey != null) {
          print('Ocr front key: ${item.ocrFrontKey} document type: ${item.documentType}');
        }
        if (item.ocrBackKey != null) {
          print('Ocr back key: ${item.ocrBackKey} document type: ${item.documentType}');
        }
      }
    } catch (e) {
      // startOcr lança uma String com a mensagem de erro
      print('Erro ao executar o OCR: $e');
    }
  }

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: _startOcr,
      child: const Text('Capturar documento'),
    );
  }
}
```

:::info **Atenção**
Habilite o suporte às orientações _Portrait_ e _Landscape Right_ em sua aplicação para o funcionamento correto do SDK nativo de iOS.
:::

## Fluxo de captura por tipo de documento

O parâmetro `document` define quantas capturas o usuário realizará e, consequentemente, quantos itens o retorno conterá.

| Tipo de documento | Capturas | Retorno |
|-------------------|----------|---------|
|`CaaSDocumentType.cnhFull`|1 (CNH aberta)|1 item com `ocrKey`|
|`CaaSDocumentType.cnhDigital`|1 (PDF da CNH digital)|1 item com `ocrKey`|
|`CaaSDocumentType.address`|1 (comprovante de residência)|1 item com `ocrKey`|
|`CaaSDocumentType.rgCinDigital`|1 (PDF do RG/CIN digital)|1 item com `ocrKey`|
|`CaaSDocumentType.cnh`|2 (frente e verso)|2 itens: `ocrFrontKey` e `ocrBackKey`|
|`CaaSDocumentType.rg`|2 (frente e verso)|2 itens: `ocrFrontKey` e `ocrBackKey`|
|`CaaSDocumentType.rne`|2 (frente e verso)|2 itens: `ocrFrontKey` e `ocrBackKey`|
|`CaaSDocumentType.crnm`|2 (frente e verso)|2 itens: `ocrFrontKey` e `ocrBackKey`|

## Aplicativo de exemplo

O repositório do plugin contém um aplicativo de exemplo pronto para execução, em `flutter_kyc_qitech/example`, que demonstra o uso dos três SDKs. Para executá-lo, crie um arquivo `.env` na pasta `example` com as credenciais abaixo e rode `flutter pub get` seguido de `flutter run` com um dispositivo físico conectado:

```
FACERECON_API_URL_SANDBOX=''
FACERECON_API_KEY_SANDBOX=''
OCR_MOBILE_TOKEN_SANDBOX=''
DEVICE_SCAN_API_URL_SANDBOX=''
DEVICE_SCAN_API_KEY_SANDBOX=''
```

Caso ainda não tenha recebido as suas credenciais, entre em contato com o suporte.caas@qitech.com.br .

---

# Instalação

URL: /documentation/caas/ocr/flutter/installation

## Instalando o plugin

Execute o comando abaixo na raiz do seu projeto Flutter:

```bash
flutter pub add flutter_kyc_qitech
```

O comando instala a versão mais recente e adiciona a dependência ao seu `pubspec.yaml`:

```yaml
dependencies:
  flutter_kyc_qitech: ^5.3.0
```

Em seguida, baixe as dependências:

```bash
flutter pub get
```

## Importação

```dart
import 'package:flutter_kyc_qitech/flutter_kyc_qitech.dart';
```

E instancie o plugin:

```dart
final _qitechFlutterKycPlugin = FlutterKycQitech();
```

## Configuração do Android

### 1. Repositório Maven da QI Tech

Adicione a referência do repositório Android da QI Tech no `build.gradle` do projeto:

```gradle
allprojects {
    repositories {
        maven { url 'https://sdks.qitech.com.br/' }
        ...
    }
}
```

### 2. AdMob

Inicialize o serviço de AdMob adicionando o seguinte código no `AndroidManifest.xml`:

```xml
<meta-data
    android:name="com.google.android.gms.ads.APPLICATION_ID"
    android:value="<ADMOB_APP_ID>"/>
```

Caso não possua um `ADMOB_APP_ID`, entre em contato com o suporte.caas@qitech.com.br .

## Configuração do iOS

### 1. Permissão de câmera

Adicione a entrada `NSCameraUsageDescription` ao `Info.plist` do seu aplicativo, com o motivo pelo qual o app precisa de acesso à câmera:

```xml
<key>NSCameraUsageDescription</key>
<string>Precisamos da câmera para capturar a foto do seu documento</string>
```

### 2. Source do repositório iOS da QI Tech

Adicione as seguintes sources no topo do seu `Podfile`:

```ruby
source 'https://cdn.cocoapods.org/'
source 'https://github.com/QITechSDKs/iOS.git'
```

### 3. Frameworks estáticos

Por padrão, o CocoaPods constrói bibliotecas estáticas em vez de frameworks. Adicione ao seu `Podfile`:

```ruby
use_frameworks! :linkage => :static
```

### 4. Estabilidade de módulo

As dependências nativas da QI Tech exigem que o `BUILD_LIBRARY_FOR_DISTRIBUTION` esteja habilitado para os alvos do Datadog. Adicione o `post_install` abaixo (ou incorpore ao seu `post_install` existente):

```ruby
post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
    target.build_configurations.each do |config|
      config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'NO'
      # A linha abaixo só é necessária para compilar em simuladores (com Rosetta ativo)
      config.build_settings["EXCLUDED_ARCHS[sdk=iphonesimulator*]"] = "arm64"
    end
    if ['DatadogCore', 'DatadogInternal', 'DatadogCrashReporting', 'DatadogLogs'].include?(target.name)
      target.build_configurations.each do |config|
        config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.5'
        config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
      end
    end
  end
end
```

### 5. Instalação dos pods

Na pasta `ios` do seu aplicativo Flutter, execute:

```bash
cd ios
pod install
```

ou, alternativamente, através do Flutter:

```bash
flutter build ios
```

:::warning Atenção
Se o seu aplicativo já utiliza **Datadog**, use a versão mais recente dentro do major `3.x` (`datadog_flutter_plugin` 3.x). Se utiliza o **FaceDetection do MLKit**, use a versão mais recente dentro do major `8.x`.
:::

---

# Introdução

URL: /documentation/caas/ocr/flutter/introduction

Bem vindo ao manual de integração do SDK de OCR (Optical Character Recognition) da QI Tech em Flutter! O plugin `flutter_kyc_qitech` expõe, por meio de uma interface Dart, os SDKs nativos de Android (Kotlin) e iOS (Swift) da QI Tech. Você pode utilizá-lo para capturar através do seu aplicativo uma imagem de um documento de seu cliente a ser reconhecido, como uma Carteira de Habilitação ou Cédula de identidade, e referenciá-lo através de uma chave nos demais produtos do sistema QI Tech.

:::info **Plugin único para os três SDKs**

O `flutter_kyc_qitech` entrega os três SDKs de Risk Solutions no mesmo pacote: `startFaceRecon` (reconhecimento facial), `startOcr` (OCR) e `startDeviceScan` (scan de dispositivo). Ao instalá-lo, os três métodos ficam disponíveis — não é necessário instalar plugins adicionais.

Se você precisa **apenas** de scan de dispositivo, utilize o plugin dedicado `qitech_device_scan`, documentado na seção [Flutter do Scan de dispositivo](/documentation/caas/device_scan/flutter/introduction).
:::

## Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso [suporte](mailto:suporte.caas@qitech.com.br) e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

### Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

## Ambientes

Possuímos dois ambientes para os nossos clientes. A seleção é realizada por meio do enumerador `CaaSEnvironment`, repassado como primeiro parâmetro do método `startOcr`. No momento, os seguintes ambientes estão disponíveis:

* Produção - `CaaSEnvironment.production`
* Sandbox - `CaaSEnvironment.sandbox`

Cada ambiente exige um Mobile Token diferente.

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.
:::

## Próximos passos

1. [Compatibilidade](/documentation/caas/ocr/flutter/compatibility) — versões mínimas de Flutter, Dart, iOS e Android.
2. [Instalação](/documentation/caas/ocr/flutter/installation) — instalação do plugin e configuração nativa de Android e iOS.
3. [Implementação](/documentation/caas/ocr/flutter/example) — exemplo completo da chamada `startOcr`.
4. [O objeto OcrOptions](/documentation/caas/ocr/flutter/ocr_options) — todos os parâmetros de customização.
5. [Coletando os Retornos](/documentation/caas/ocr/flutter/collecting_response) — estrutura de resposta e tratamento de erros.

---

# O objeto OcrOptions

URL: /documentation/caas/ocr/flutter/ocr_options

## Parâmetros de startOcr

| Parâmetro | Tipo | Função | Obrigatório |
|------------|--------------|--------------|--------------|
|environment|CaaSEnvironment|Enumerador utilizado para configurar o ambiente de execução para `sandbox` ou `production`.|Sim.|
|mobileToken|String|Chave do cliente que identifica que os dados coletados são provenientes do seu aplicativo. Caso ainda não tenha recebido o seu mobile-token, entre em contato com o <a href='mailto:suporte.caas@qitech.com.br'>suporte</a>. Cada ambiente exige um token diferente.|Sim.|
|document|CaaSDocumentType|Enumerador que define o fluxo de captura de documentos realizado pelo usuário.|Sim.|
|options|OcrOptions?|Objeto opcional com as customizações visuais, textuais e de comportamento do SDK.|Não.|

## OcrOptions

Todos os campos são opcionais. Quando um campo não é informado, o SDK nativo aplica o seu valor padrão.

| Parâmetro | Tipo | Função | Padrão |
|------------|--------------|--------------|--------------|
|sessionId|String?|Chave que identifica a sessão iniciada no SDK. É utilizada para rastrear todo o fluxo percorrido pelo usuário através de logs. Aceita até 255 caracteres.|Gerado internamente.|
|fontColor|String?|Cor da fonte e dos ícones das telas do SDK, em formato hexadecimal (ex.: `"#FFFFFF"`).|`"#000000"`|
|backgroundColor|String?|Cor de fundo das telas do SDK, em formato hexadecimal (ex.: `"#000000"`).|`"#FFFFFF"`|
|fontFamily|CaaSFontFamily?|Fonte utilizada nas telas do SDK.|`CaaSFontFamily.openSans`|
|showIntroductionScreens|bool?|Quando `false`, desativa as telas de introdução à captura do documento.|`true`|
|showSuccessScreen|bool?|Quando `false`, desativa a tela de sucesso exibida após a captura.|`true`|
|audioConfiguration|FaceReconAudioConfiguration?|Configura o guiamento por voz, que narra as instruções de captura em tempo real.|`FaceReconAudioConfiguration.disable`|
|onboardingTextConfiguration|OnboardingTextConfiguration?|Customiza os textos da tela de onboarding.|Textos padrão do SDK.|
|logLevel|CaaSLogLevel?|Nível de verbosidade dos logs do SDK.|`CaaSLogLevel.debug`|

:::info **Atenção**
O parâmetro `audioConfiguration` em `OcrOptions` está disponível a partir da versão **5.3.0** do plugin.
:::

## OnboardingTextConfiguration

| Parâmetro | Tipo | Função |
|------------|--------------|--------------|
|onboardingTitle|String?|Título da tela de onboarding.|
|onboardingFirstLabel|String?|Primeira instrução exibida ao usuário.|
|onboardingSecondLabel|String?|Segunda instrução exibida ao usuário.|
|onboardingThirdLabel|String?|Terceira instrução exibida ao usuário.|

```dart
OnboardingTextConfiguration(
  onboardingTitle: 'Dicas Importantes',
  onboardingFirstLabel: 'Vá para um local iluminado',
  onboardingSecondLabel: 'Retire o documento do plástico',
  onboardingThirdLabel: 'Garanta que o documento está corretamente enquadrado',
)
```

## Enumeradores

### CaaSEnvironment

```dart
enum CaaSEnvironment {
  production,
  sandbox,
}
```

### CaaSDocumentType

```dart
enum CaaSDocumentType {
  cnhFull,       // CNH brasileira aberta, em foto única
  cnhDigital,    // PDF da CNH digital brasileira
  cnh,           // CNH brasileira, frente e verso
  rg,            // RG brasileiro, frente e verso
  address,       // Comprovante de residência
  rne,           // Registro Nacional de Estrangeiro, frente e verso
  crnm,          // Carteira de Registro Nacional Migratório, frente e verso
  rgCinDigital,  // PDF do RG/CIN digital
}
```

:::info **Atenção**
O tipo `rgCinDigital` está disponível a partir da versão **5.3.0** do plugin.
:::

### CaaSFontFamily

```dart
enum CaaSFontFamily {
  jakarta,       // apenas iOS
  futura,        // iOS e Android
  verdana,       // iOS e Android
  trebuchetMs,   // apenas iOS
  tamilsangamMn, // apenas iOS
  openSans,      // iOS e Android
  helvetica,     // apenas Android
  poppins,       // apenas Android
  roboto,        // apenas Android
  systemFont,    // apenas iOS
}
```

:::info **Atenção**
A disponibilidade das fontes varia por plataforma. Caso uma fonte não suportada seja informada, a plataforma utiliza a sua fonte padrão. Para consistência entre iOS e Android, utilize `futura`, `verdana` ou `openSans`.
:::

### FaceReconAudioConfiguration

```dart
enum FaceReconAudioConfiguration {
  enable,        // exibe o botão de áudio, com a narração iniciando desligada
  disable,       // desativa a narração e oculta o botão
  accessibility, // exibe o botão com a narração iniciando ligada quando há recursos de acessibilidade ativos
}
```

### CaaSLogLevel

```dart
enum CaaSLogLevel {
  trace,
  debug,
  log,
  info,
  warn,
  error,
}
```

---

# Coletando os Retornos

URL: /documentation/caas/ocr/ios/collecting_response

```swift
class ViewController: UIViewController, QITechIosOcrControllerDelegate {
    
    // Do something if QI Tech OCR's SDK succesfully collected document picture
    func qitechIosOcrController(_ ocrViewController: QITechIosOcrController, didFinishWithResults response: QITechIosOcrControllerResponse) {
    
    }
    
    // Do something if QI Tech OCR's SDK found any error when collecting document picture
    func qitechIosOcrController(_ ocrViewController: QITechIosOcrController, didFailWithError error: QITechIosOcrControllerError) {
        
    }
    
    // Do something if the user canceled the picture collection on any steps
    func qitechIosOcrControllerDidCancel(_ ocrViewController: QITechIosOcrController) {

    }
}
```
Para obter as respostas do SDK , você deve implementar o delegate **QITechIosOcrControllerDelegate** em seu controller, conforme exemplo ao lado.

## QITechIosOcrControllerResponse

A classe **QITechIosOcrControllerResponse** é utilizada para que você possa receber a resposta do SDK da QI Tech.

Na tabela abaixo você encontra o detalhe de todas as propriedades desta classe:

nome | tipo | descrição 
---- | :----: | --------- 
OcrResponses | Lista de OcrResponse | Identifica

## Objeto OcrResponse

nome | tipo | descrição 
---- | :----: | --------- 
OcrKey | string | Identificador único da imagem na QI Tech. Você deve armazenar esse identificador para enviar na API da QI Tech que realizará a validação (ex.: API de Onboarding)
DocumentTemplate | QITechIosOcrDocumentTemplate | Enumerador que identifica a qual foto aquela OCR Key se refere.

Os valores possíveis do enumerador **QITechIosOcrDocumentTemplate** podem ser:

* `QITechIosOcrDocumentTemplate.CnhFull` - Identifica o resultado da validação da CNH inteira.
* `QITechIosOcrDocumentTemplate.CnhFront` - Identifica o resultado da validação da frente da CNH.
* `QITechIosOcrDocumentTemplate.CnhBack` - Identifica o resultado da validação do verso da CNH.
* `QITechIosOcrDocumentTemplate.RgFront` - Identifica o resultado da validação da frente do RG.
* `QITechIosOcrDocumentTemplate.RgBack` - Identifica o resultado da validação do verso do RG.
* `QITechIosOcrDocumentTemplate.RgCinDigital` - Identifica o resultado da validação do RG digital ou da CIN digital.
* `QITechIosOcrDocumentTemplate.NationalRegistryOfForeignersFront` - Identifica o resultado da validação da frente do Registro Nacional de Estrangeiros.
* `QITechIosOcrDocumentTemplate.NationalRegistryOfForeignersBack` - Identifica o resultado da validação do verso do Registro Nacional de Estrangeiros.

## QITechIosOcrControllerError

A classe **QITechIosOcrControllerError** é acionada no caso de algum erro que leve ao encerramento do SDK. Quando isso ocorrer, a QI Tech retornará uma subclasse que terá um nome correspondente ao erro que levou ao encerramento do SDK, conforme tabela abaixo:

classe | descrição 
---- | --------- 
InvalidMobileToken | MobileToken enviado nas configurações é inválido.
MissingPermission | Alguma das permissões necessárias para a validação não foi suficiente.
NetworkFailure | O usuário perdeu a conexão com a internet durante a validação.
ServerFailure | O servidor da QI Tech devolveu alguma resposta de erro para o SDK.
MissingStorage | Não há espaço de armazenamento suficiente no dispositivo do usuário para que seja realizada a coleta da imagem.
LowImageQuality | Por algum motivo a qualidade da imagem coletada não foi o suficiente para realização da validação.

Para mapear qual a subclasse, e portanto, qual o motivo do erro, utilize o método *isKindOfClass()* do swift.

---

# QITechIosOcrConfiguration

URL: /documentation/caas/ocr/ios/configuration

```swift
let onboardingTextConfiguration = OnboardingTextConfiguration(
        onboardingTitle: "Conselhos relevantes",
        onboardingFirstLabel: "Esteja em um local iluminado",
        onboardingSecondLabel: "Tire o documento do envelope",
        onboardingThirdLabel: "Enquadre o documento nas marcas"
)

let ocrConfig = QITechIosOcrConfiguration(
        environment: QITechIosOcrEnvironment.sandbox,
        mobileToken: "41fb4755-9bcf-4ae3-b981-b6009e51ce4a",
        sessionId: "288eb399-4936-4133-ab2c-5611d6e5bb7a",
        documentSteps: documentSteps,
        fontColor: "#337DFF",
        backgroundColor: "#C9CCD3",
        fontFamily: .open_sans,
        showIntroductionScreens: true,
        showSuccessScreen: false,
        onboardingTextConfiguration: onboardingTextConfiguration,
        logLevel: .debug
)
```

**Versões anteriores à v7.0.0**
```swift

let visualConfiguration = VisualConfiguration()
        visualConfiguration.setOnboarding(onboardingFilePath: Bundle.main.path(forResource: "onboarding", ofType: "png")!, onboardingWidth: 200)

let textConfiguration = TextConfiguration()
        textConfiguration.setCustomText(on: .onboardingTitle, text: "Vamos começar!")
        textConfiguration.setCustomText(on: .onboardingFirstLabel, text: "- Vá para um local com boa luminosidade")
        textConfiguration.setCustomText(on: .onboardingSecondLabel, text: "- Retire o documento do plástico")

let ocrConfig = QITechIosOcrConfiguration(environment: QITechIosOcrEnvironment.Sandbox,
                                            mobileToken: "41fb4755-9bcf-4ae3-b981-b6009e51ce4a",
                                            sessionId: "288eb399-4936-4133-ab2c-5611d6e5bb7a",
                                            documentSteps: documentSteps,
                                            backgroundColor: "#C9CCD3",
                                            fontColor: "#337DFF",
                                            fontFamily: .open_sans,
                                            showIntroductionScreens: true,
                                            showSuccessScreen: false,
                                            logLevel: .debug
                                            )

ocrConfig.setVisualConfiguration(visualConfiguration: visualConfiguration)
ocrConfig.setTextConfiguration(textConfiguration: textConfiguration)

```

A classe **QITechIosOcrConfiguration** é utilizada para que você possa configurar ambiente, credenciais, aspectos visuais e textuais, e o fluxo de coleta de imagens dos documentos, ou seja, todas as configurações necessárias para personalização e funcionamento do SDK.

Na tabela abaixo você encontra o detalhe de todos os argumentos que devem ser utilizados na sua instanciação:

| nome                    |          tipo          | descrição                                                                                                                                                                                                                              |
| ----------------------- | :--------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| environment             | QITechIosOcrEnvironment  | _(obrigatório)_ Enumerador que descreve o ambiente.                                                                                                                                                                                    |
| mobileToken             |         string         | _(obrigatório)_ Token enviado pela QI Tech para autenticação do SDK.                                                                                                                                                                      |
| sessionId               |         string         | _(opcional)_ ID único usado para rastrear todo fluxo percorrido pelo usuário na execução da OCR através de logs. Este campo aceita até 255 caracteres.                                                                                 |
| documentSteps           | QITechIosOcrDocumentFlow | _(obrigatório)_ Enumerador que descreve qual fluxo de validação será seguido, definindo qual documento e qual ordem de captura de imagem será realizado.                                                                               |
| fontColor               |         string         | _(opcional)_ Hexadecimal da cor da fonte. Caso não seja informada o padrão é #1C49A5.                                                                                                                                              |
| backgroundColor         |         string         | _(opcional)_ Hexadecimal da cor de fundo das telas. Caso não seja informada o padrão é #FCFCFC.                                                                                                                                        |
| fontFamily              |       FontFamily       | _(opcional)_ Familia da fonte. Caso não seja informada o padrão é .open_sans. Fontes disponíveis: .open_sans, .futura, .verdana, .trebuchetms, .tamilsangammn e .system_font.                                                          |
| showIntroductionScreens |        booleano        | _(opcional)_ Flag que indica se as telas de introdução, com instruções de como a foto deve ser capturada, devem ser mostradas. Caso não seja informada o padrão é _true_.                                                              |
| showSuccessScreen |             booleano              | _(opcional)_ Flag que indica se a tela de sucesso, com a mensagem de sucesso na captura, deve ser mostrada. Caso não seja informada o padrão é _true_.                                                                                                                                                                   |
| onboardingTextConfiguration | OnboardingTextConfiguration | _(opcional)_ Permite configurar os textos da tela de instruções |
| logLevel                |        LogLevel        | _(opcional)_ . Utilizado para customizar o nível de verbosidade dos logs do SDK. Níveis disponíveis: LogLevel.debug, LogLevel.info, LogLevel.warn, LogLevel.error e LogLevel.trace. Caso não seja informada o padrão é LogLevel.debug. |
| audioConfiguration      |   AudioConfiguration   | _(opcional)_ Configura o guiamento por voz do SDK, que narra as instruções de captura em tempo real. As configurações aceitas são: _Enable_, que exibe o botão de ligar/desligar áudio com a narração iniciando desligada; _Disable_, que desativa a narração e oculta o botão; e _Accessibility_, que exibe o botão com a narração iniciando ligada quando o dispositivo possui recursos de acessibilidade ativos. Com o VoiceOver ativo, as instruções completas são entregues pelo próprio leitor de telas. Caso não seja informada o padrão é _Disable_. |

Na tabela abaixo você encontra todos os métodos aceitos pela instância para configuração:
:::warning
__DEPRECADO__ A PARTIR DA **v7.0.0**!
:::

| método                 |                                                 argumentos                                                  | descrição                                                                                     |
| ---------------------- | :---------------------------------------------------------------------------------------------------------: | --------------------------------------------------------------------------------------------- |
| setVisualConfiguration | visualConfiguration : VisualConfiguration | _(opcional)_ Classe que permite a modificação das imagens exibidas durante a execução do SDK; |
| setTextConfiguration   |                                    textConfiguration : TextConfiguration                                    | _(opcional)_ Classe que permite a modificação dos textos exibidos durante a execução do SDK;  |

---

# Introdução

URL: /documentation/caas/ocr/ios/introduction

Bem vindo ao SDK iOS de OCR (Optical Character Recognition) para leitura de documentos da QI Tech. Este SDK realiza a captura de documentos e envio a API de OCR da QI Tech . Você pode utilizá-lo para capturar através do seu aplicativo uma imagem de um documento de seu cliente a ser reconhecido, como uma Carteira de Habilitação ou Cédula de identidade, e referenciá-lo através de uma chave nos demais produtos do sistema QI Tech.

## Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso [suporte](mailto:suporte.caas@qitech.com.br) e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

### Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.  
:::

---

# Importando o SDK

URL: /documentation/caas/ocr/ios/native_swift

## Remotamente

> Iniciando a instalação

```shell
  pod init
```

Nosso SDK pode ser importado utilizando CocoaPods.

| SDK        | Versão atual                   |
| ---------- | ------------------------------ |
| QITechIosOCR | `pod 'QITechIosOCR', '~> 8.2.0'` |

:::info iOS Minimum Deployment Target
15.5
:::

:::danger Utilização de simuladores em MacBooks com chip arm64
Atualmente, nosso SDK de OCR para iOS infelizmente não suporta ser compilada para simuladores que estejam rodando
em um MacBook com **chip de arquitetura arm64** (M1/M2/M3/M4), **a não ser que seja utilizado Rosetta**, que faz a tradução
da arquitetura x86_64 para arm64.
:::

Para iniciar a instalação, execute o comando ao lado na pasta raiz do seu projeto.

> Adicionando a source no podfile

```ruby
   source 'https://github.com/QITechSDKs/iOS.git'
```

O próximo passo é adicionar no arquivo `podfile` o source da QI Tech.

> Adicionando o pod no podfile

```ruby
  pod 'QITechIosOCR', '~> <version>'
```

Por fim, basta adicionar o nome do `pod` de acordo com o formato ao lado.

:::danger Atenção: 
Mudança de Arquitetura (v6.0.0+) A partir da versão 6.0.0, o SDK passou a ser distribuída exclusivamente de forma estática. No seu Podfile, você deve utilizar a configuração :linkage => :static. 
:::

> Exemplo de podfile (Versão 6.0.0 ou superior)

```ruby
  source 'https://github.com/QITechSDKs/iOS.git'
  source 'https://cdn.cocoapods.org/'
  target 'ExampleApp' do
    use_frameworks! :linkage => :static
    pod 'QITechIosOCR', '~> 8.2.0'
  end

  post_install do |installer|
    installer.pods_project.targets.each do |target|
      if ['DatadogCore', 'DatadogInternal', 'DatadogCrashReporting', 'DatadogLogs'].include?(target.name)
        target.build_configurations.each do |config|
          config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.5'
          config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
        end
      end
    end
  end
```

> Exemplo de podfile (Versões Anteriores)

```ruby
  source 'https://github.com/QITechSDKs/iOS.git'
  source 'https://cdn.cocoapods.org/'
  target 'ExampleApp' do
    use_frameworks! 
    pod 'QITechIosOCR', '~> 4.0.0'
  end

  post_install do |installer|
    installer.pods_project.targets.each do |target|
      if ['DatadogCore', 'DatadogInternal', 'DatadogCrashReporting', 'DatadogLogs'].include?(target.name)
        target.build_configurations.each do |config|
          config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.5'
          config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
        end
      end
    end
  end
```

:::warning Atenção
Ao integrar dependências no iOS, pode surgir a necessidade de usar linkagem estática para algumas bibliotecas e dinâmica para outras. Essa configuração é relevante para garantir compatibilidade, evitar erros de build e otimizar o desempenho do projeto. 
:::

### Linkagem Híbrida de Dependências (caso necessário)
A necessidade de linkagem híbrida surge porque algumas bibliotecas têm requisitos específicos, sendo que algumas precisam de linkagem estática para evitar conflitos internos e duplicação de símbolos e outras dependências podem precisar linkagem dinâmica, pois são projetadas para modularidade e compartilhamento entre projetos.

Diferenças Entre Linkagem Estática e Dinâmica
* Estática (static_framework): O código da biblioteca é incorporado diretamente no binário final, reduzindo o tempo de carregamento em runtime e eliminando dependências externas durante a execução.
* Dinâmica (dynamic_framework): A biblioteca é carregada em tempo de execução como um arquivo separado. Isso reduz o tamanho do binário final e facilita atualizações/modificações independentes.

> Configurando linkagem híbrida no Podfile

```ruby
...

use_frameworks! :linkage => :dynamic # CONFIGURANDO O MODO PADRÃO DE LINKAGEM PARA DINÂMICO

...

static_frameworks = ['framework_1', 'framework_2', ...] # INCLUIR TODAS AS DEPENDÊNCIAS QUE PRECISAM SER LINKADAS DE MODO ESTÁTICO
pre_install do |installer|
  installer.pod_targets.each do |pod|
    if static_frameworks.include?(pod.name)
      def pod.static_framework?;
        true
      end
      def pod.build_type;
        Pod::BuildType.static_framework
      end
    end
  end
end
```

> Instalando as dependências

```shell
  pod install
```

Por fim, execute o comando `pod install` para baixar e instalar as dependências.

## Permissões Necessárias

Para que o SDK possa acessar os recursos do dispositivo para coletar a foto, é necessário que sejam solicitadas permissões ao usuário.

No arquivo **info.plist**, adicione as permissões abaixo:

| Permissão                          | Motivo                                               |
| ---------------------------------- | ---------------------------------------------------- |
| Privacy - Camera Usage Description | Acesso à câmera para capturar as fotos do documento. |

## Iniciando o SDK

```swift

import QITechIosOcr

class ViewController: UIViewController, QITechIosOcrControllerDelegate {

    var qitechOcrConfiguration : QITechIosOcrConfiguration?

    override func viewDidLoad() {
        super.viewDidLoad()
        self.setupOcr()
    }

    func setupOcr() -> Void
    {
        let onboardingTextConfiguration = OnboardingTextConfiguration(
          onboardingTitle: "Conselhos relevantes",                // Título
          onboardingFirstLabel: "Esteja em um local iluminado",   // Primeira Instrução
          onboardingSecondLabel: "Tire o documento do envelope",  // Segunda Instrução
          onboardingThirdLabel: "Enquadre o documento nas marcas" // Terceira Instrução
        )

        // The environment can be 'sandbox' ou 'production'
        let environment: QITechIosOcrEnvironment = .sandbox

        // MobileToken is the key sent to you by QI Tech. Each environment requires a different MobileToken.
        let mobileToken: String = "YOUR_MOBILE_TOKEN"

        // The documentFlow can be 'CnhFull', 'CnhFrontAndBack', 'RgFrontAndBack' ou 'RgCinDigital'
        let documentFlow = QITechIosOcrDocumentFlow.CnhFrontAndBack

        let sessionId: String = "SESSION_ID"
        let fontColor: String = "#ED6C2D"
        let backgroundColor: String = "#EEEEEE"
        let fontFamily: FontFamily? = .verdana
        let showIntroductionScreens: Bool = true
        let showSuccessScreen: Bool = true
        let logLevel: QITechIosOCR.LogLevel = .debug

        self.ocrConfig = QITechIosOcrConfiguration(
          environment: environment,
          mobileToken: mobileToken,
          documentSteps: documentFlow,
          sessionId: sessionId,
          fontColor: fontColor,
          backgroundColor: backgroundColor,
          fontFamily: fontFamily,
          showIntroductionScreens: showIntroductionScreens,
          showSuccessScreen: showSuccessScreen,
          onboardingTextConfiguration: onboardingTextConfiguration,
          logLevel: logLevel
        )
    }

    // Event where you intend to call QI Tech OCR View Controller - on this example, when the user press 'next' button

    @IBAction func pressNext(_ sender: Any) {
        let qitechOcrController =  QITechIosOcrController(ocrConfiguration: self.ocrConfig)
        qitechOcrViewController.delegate = self
        let qitechOcrViewController = qitechOcrController.getViewController()
        present(qitechOcrViewController, animated: true, completion: nil)
    }

    // Do something if QI Tech OCR's SDK succesfully collected document picture
    func qitechIosOcrController(_ ocrViewController: QITechIosOcrController, didFinishWithResults results: QITechIosOcrControllerResponse) {

    }

    // Do something if QI Tech OCR's SDK found any error when collecting document picture
    func qitechIosOcrController(_ ocrViewController: QITechIosOcrController, didFailWithError error: QITechIosOcrControllerError) {

    }

    // Do something if the user canceled the picture collection on any steps
    func qitechIosOcrControllerDidCancel(_ ocrViewController: QITechIosOcrController) {

    }
}
```

**Versões anteriores à v7.0.0**
  ```swift
    import QITechIosOcr

    class ViewController: UIViewController, QITechIosOcrControllerDelegate {

        var qitechOcrConfiguration : QITechIosOcrConfiguration?

        override func viewDidLoad() {
            super.viewDidLoad()
            self.setupOcr()
        }

        func setupOcr() -> Void
        {
            // The environment can be 'Sandbox' ou 'Production'
            let environment = QITechIosOcrEnvironment.Sandbox

            // MobileToken is the key sent to you by QI Tech. Each environment requires a different MobileToken.
            let mobileToken = "YOUR_MOBILE_TOKEN_SENT_BY_QITECH"

            // The documentFlow can be 'CnhFull', 'CnhFrontAndBack', 'RgFrontAndBack' ou 'RgCinDigital'
            let documentFlow = QITechIosOcrDocumentFlow.CnhFrontAndBack

            self.ocrConfig = QITechIosOcrConfiguration(environment: environment,
                                                mobileToken: mobileToken,
                                                sessionId: "UNIQUE_SESSION_ID",
                                                documentFlow: documentFlow,
                                                backgroundColor: "#000000",
                                                fontColor: "#FFFFFF",
                                                fontFamily: .open_sans,
                                                showIntroductionScreens: true,
                                                logLevel: .debug
                                                )
        }

        // Event where you intend to call QI Tech OCR View Controller - on this example, when the user press 'next' button

        @IBAction func pressNext(_ sender: Any) {
            let qitechOcrController =  QITechIosOcrController(ocrConfiguration: self.ocrConfig)
            qitechOcrViewController.delegate = self
            let qitechOcrViewController = qitechOcrController.getViewController()
            present(qitechOcrViewController, animated: true, completion: nil)
        }

        // Do something if QI Tech OCR's SDK succesfully collected document picture
        func qitechIosOcrController(_ ocrViewController: QITechIosOcrController, didFinishWithResults results: QITechIosOcrControllerResponse) {

        }

        // Do something if QI Tech OCR's SDK found any error when collecting document picture
        func qitechIosOcrController(_ ocrViewController: QITechIosOcrController, didFailWithError error: QITechIosOcrControllerError) {

        }

        // Do something if the user canceled the picture collection on any steps
        func qitechIosOcrControllerDidCancel(_ ocrViewController: QITechIosOcrController) {

        }
    }
  ```

Para incorporar o SDK ao seu aplicativo você deve realizar a configuração do seu aplicativo de captura personalizado através da classe **QITechIosOcrConfiguration** e depois instanciar o **ViewController QITechIosOcrController** passando como argumento as configurações personalizadas.

Para iniciar o processo de análise de documento, basta chamar a função _present_ para chamar o ViewController da QI Tech que realizará a coleta das imagens.

Importante implementar o _Delegate_ responsável por receber os retornos em caso de sucesso, erro ou no caso de o usuário interromper a jornada em qualquer etapa da validação.

Acima temos um exemplo completo da implementação.

:::info **Atenção**

Habilite o suporte as orientações _Portrait_ e _Landscape Right_ em sua aplicação para um funcionamento correto do SDK.
:::

## Mobile Token

Utilizamos um Mobile Token para permitir o acesso autenticado do seu aplicativo a nossa API. Ele provavelmente já foi enviado por e-mail para você. Caso ainda não tenha recebido o seu token, envie um e-mail para suporte.caas@qitech.com.br .

Nossa API espera receber o Mobile Token em todas as requisições ao nosso servidor vindas do SDK, portanto, este deve ser obrigatoriamente incluido como parâmetro de configuração através do método mencionado anteriormente.

:::info **Atenção**

Você deve substituir "YOUR_MOBILE_TOKEN_SENT_BY_QITECH" pelo Mobile Token recebido do suporte.
:::

---

# necessary_permissions

URL: /documentation/caas/ocr/ios/necessary_permissions

## Permissões Necessárias

Para que o SDK possa acessar os recursos do dispositivo para coletar a foto, é necessário que sejam solicitadas permissões ao usuário.

No arquivo **info.plist**, adicione as permissões abaixo:

| Permissão                          | Motivo                                               |
| ---------------------------------- | ---------------------------------------------------- |
| Privacy - Camera Usage Description | Acesso à câmera para capturar as fotos do documento. |

---

# Importando o SDK

URL: /documentation/caas/ocr/ios/using_sdk

## Remotamente

> Iniciando a instalação

```shell
  pod init
```

Nosso SDK pode ser importado utilizando CocoaPods.

| SDK        | Versão atual                   |
| ---------- | ------------------------------ |
| QITechIosOCR | `pod 'QITechIosOCR', '~> 8.2.0'` |

Para iniciar a instalação, execute o comando ao lado na pasta raiz do seu projeto.

> Adicionando a source no podfile

```ruby
   source 'https://github.com/QITechSDKs/iOS.git'
```

O próximo passo é adicionar no arquivo `podfile` o source da QI Tech.

> Adicionando o pod no podfile

```ruby
  pod 'QITechIosOCR', '~> <version>'
```

Por fim, basta adicionar o nome do `pod` de acordo com o formato ao lado.

> Exemplo de podfile

```ruby
  source 'https://github.com/QITechSDKs/iOS.git'
  source 'https://cdn.cocoapods.org/'
  target 'ExampleApp' do
    use_frameworks!
    pod 'QITechIosOCR', '~> 8.2.0'
  end

  post_install do |installer|
    installer.pods_project.targets.each do |target|
      if ['DatadogCore', 'DatadogInternal', 'DatadogCrashReporting', 'DatadogLogs'].include?(target.name)
        target.build_configurations.each do |config|
          config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '12.0'
          config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
        end
      end
    end
  end
```

:::warning Atenção
Ao integrar dependências no iOS, pode surgir a necessidade de usar linkagem estática para algumas bibliotecas e dinâmica para outras. Essa configuração é relevante para garantir compatibilidade, evitar erros de build e otimizar o desempenho do projeto. 
:::

### Linkagem Híbrida de Dependências (caso necessário)
A necessidade de linkagem híbrida surge porque algumas bibliotecas têm requisitos específicos, sendo que algumas precisam de linkagem estática para evitar conflitos internos e duplicação de símbolos e outras dependências podem precisar linkagem dinâmica, pois são projetadas para modularidade e compartilhamento entre projetos.

Diferenças Entre Linkagem Estática e Dinâmica
* Estática (static_framework): O código da biblioteca é incorporado diretamente no binário final, reduzindo o tempo de carregamento em runtime e eliminando dependências externas durante a execução.
* Dinâmica (dynamic_framework): A biblioteca é carregada em tempo de execução como um arquivo separado. Isso reduz o tamanho do binário final e facilita atualizações/modificações independentes.

> Configurando linkagem híbrida no Podfile

```ruby
...

use_frameworks! :linkage => :dynamic # CONFIGURANDO O MODO PADRÃO DE LINKAGEM PARA DINÂMICO

...

static_frameworks = ['framework_1', 'framework_2', ...] # INCLUIR TODAS AS DEPENDÊNCIAS QUE PRECISAM SER LINKADAS DE MODO ESTÁTICO
pre_install do |installer|
  installer.pod_targets.each do |pod|
    if static_frameworks.include?(pod.name)
      def pod.static_framework?;
        true
      end
      def pod.build_type;
        Pod::BuildType.static_framework
      end
    end
  end
end
```

> Instalando as dependências

```shell
  pod install
```

Por fim, execute o comando `pod install` para baixar e instalar as dependências.

## Permissões Necessárias

Para que o SDK possa acessar os recursos do dispositivo para coletar a foto, é necessário que sejam solicitadas permissões ao usuário.

No arquivo **info.plist**, adicione as permissões abaixo:

| Permissão                          | Motivo                                               |
| ---------------------------------- | ---------------------------------------------------- |
| Privacy - Camera Usage Description | Acesso à câmera para capturar as fotos do documento. |

## Iniciando o SDK

```swift

import QITechIosOcr

class ViewController: UIViewController, QITechIosOcrControllerDelegate {

    var qitechOcrConfiguration : QITechIosOcrConfiguration?

    override func viewDidLoad() {
        super.viewDidLoad()
        self.setupOcr()
    }

    func setupOcr() -> Void
    {
        // The environment can be 'Sandbox' ou 'Production'
        let environment = QITechIosOcrEnvironment.Sandbox

        // MobileToken is the key sent to you by QI Tech. Each environment requires a different MobileToken.
        let mobileToken = "YOUR_MOBILE_TOKEN_SENT_BY_QITECH"

        // The documentFlow can be 'CnhFull', 'CnhFrontAndBack', 'RgFrontAndBack' ou 'RgCinDigital'
        let documentFlow = QITechIosOcrDocumentFlow.CnhFrontAndBack

        self.ocrConfig = QITechIosOcrConfiguration(environment: environment,
                                            mobileToken: mobileToken,
                                            sessionId: "UNIQUE_SESSION_ID",
                                            documentFlow: documentFlow,
                                            backgroundColor: "#000000",
                                            fontColor: "#FFFFFF",
                                            fontFamily: .open_sans,
                                            showIntroductionScreens: true,
                                            logLevel: .debug
                                            )
    }

    // Event where you intend to call QI Tech OCR View Controller - on this example, when the user press 'next' button

    @IBAction func pressNext(_ sender: Any) {
        let qitechOcrController =  QITechIosOcrController(ocrConfiguration: self.ocrConfig)
        qitechOcrViewController.delegate = self
        let qitechOcrViewController = qitechOcrController.getViewController()
        present(qitechOcrViewController, animated: true, completion: nil)
    }

    // Do something if QI Tech OCR's SDK succesfully collected document picture
    func qitechIosOcrController(_ ocrViewController: QITechIosOcrController, didFinishWithResults results: QITechIosOcrControllerResponse) {

    }

    // Do something if QI Tech OCR's SDK found any error when collecting document picture
    func qitechIosOcrController(_ ocrViewController: QITechIosOcrController, didFailWithError error: QITechIosOcrControllerError) {

    }

    // Do something if the user canceled the picture collection on any steps
    func qitechIosOcrControllerDidCancel(_ ocrViewController: QITechIosOcrController) {

    }
}
```

Para incorporar o SDK ao seu aplicativo você deve realizar a configuração do seu aplicativo de captura personalizado através da classe **QITechIosOcrConfiguration** e depois instanciar o **ViewController QITechIosOcrController** passando como argumento as configurações personalizadas.

Para iniciar o processo de análise de documento, basta chamar a função _present_ para chamar o ViewController da QI Tech que realizará a coleta das imagens.

Importante implementar o _Delegate_ responsável por receber os retornos em caso de sucesso, erro ou no caso de o usuário interromper a jornada em qualquer etapa da validação.

Ao lado temos um exemplo completo da implementação.

:::info **Atenção**

Habilite o suporte as orientações _Portrait_ e _Landscape Right_ em sua aplicação para um funcionamento correto do SDK.
:::

## Mobile Token

Utilizamos um Mobile Token para permitir o acesso autenticado do seu aplicativo a nossa API. Ele provavelmente já foi enviado por e-mail para você. Caso ainda não tenha recebido o seu token, envie um e-mail para suporte.caas@qitech.com.br .

Nossa API espera receber o Mobile Token em todas as requisições ao nosso servidor vindas do SDK, portanto, este deve ser obrigatoriamente incluido como parâmetro de configuração através do método mencionado anteriormente.

:::info **Atenção**

Você deve substituir "YOUR_MOBILE_TOKEN_SENT_BY_QITECH" com o Mobile Token recebido do suporte.
:::

---

# Coletando os Retornos

URL: /documentation/caas/ocr/react_native/collecting_response

:::warning Atenção
A _Promise_ de `startOcr` resolve com uma **string JSON**, tanto no Android quanto no iOS. É necessário chamar `JSON.parse()` antes de acessar os campos. O tipo declarado no TypeScript é `OCR_RETURN_VALUES | string`.
:::

## Estrutura do retorno

```typescript
type OCR_RETURN_VALUES = {
  DocumentRecognitionResponse: {
    ocr_key?: string;
    ocr_front_key?: string;
    ocr_back_key?: string;
    document_type: string;
  }[];
};
```

| Atributo | Tipo | Descrição |
|----------|------|-----------|
|ocr_key|string|Chave de identificação da imagem, presente em documentos de captura única (`cnh_full`, `cnh_digital`, `proof_of_address`, `rg_cin_digital`). Pode ser utilizada em qualquer outro serviço do sistema QI Tech.|
|ocr_front_key|string|Chave de identificação da imagem da frente, presente em documentos de captura dupla (`cnh`, `rg`, `rne`, `crnm`).|
|ocr_back_key|string|Chave de identificação da imagem do verso, presente em documentos de captura dupla (`cnh`, `rg`, `rne`, `crnm`).|
|document_type|string|Identifica a qual documento aquela chave se refere (ex.: `"cnh"`, `"rg"`, `"proof_of_address"`).|

:::info **Importante**
Armazene as chaves retornadas — elas são o identificador da imagem nos demais produtos do sistema QI Tech, como a API de Onboarding.
:::

### Documento de captura única

```json
{
  "DocumentRecognitionResponse": [
    { "ocr_key": "5d0f0e1c-8f9e-4b6c-9c3d-2f8a1b4e7c10", "document_type": "cnh_full" }
  ]
}
```

### Documento de captura dupla

```json
{
  "DocumentRecognitionResponse": [
    { "ocr_front_key": "5d0f0e1c-8f9e-4b6c-9c3d-2f8a1b4e7c10", "document_type": "cnh" },
    { "ocr_back_key": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "document_type": "cnh" }
  ]
}
```

## Exemplo de leitura do retorno

```tsx
startOcr(CAAS_ENVIRONMENT.SANDBOX, mobileToken, CAAS_DOCUMENT_TYPE.CNH)
  .then((response) => {
    const { DocumentRecognitionResponse } = JSON.parse(response as string);

    if (DocumentRecognitionResponse.length === 1) {
      const { ocr_key, document_type } = DocumentRecognitionResponse[0];
      console.log('Ocr key: ' + ocr_key + ' document type: ' + document_type);
    } else if (DocumentRecognitionResponse.length === 2) {
      const { ocr_front_key } = DocumentRecognitionResponse[0];
      const { ocr_back_key } = DocumentRecognitionResponse[1];
      console.log('Ocr front key: ' + ocr_front_key + ' / Ocr back key: ' + ocr_back_key);
    }
  })
  .catch((error) => {
    console.log('Error executing Ocr. Error: ' + error);
  });
```

## Tratamento de erros

A _Promise_ é rejeitada quando o usuário interrompe o fluxo ou quando o SDK nativo encontra um erro.

| Situação | Mensagem |
|----------|----------|
|Usuário cancelou o fluxo|`User canceled OCR`|
|Erro no SDK nativo de iOS|`Error executing OCR: <detalhe>`|
|Módulo nativo não vinculado|`The package 'react-native-qi-tech-module' doesn't seem to be linked...`|

:::info **Atenção**
Se você receber o erro de _linking_, verifique se executou `pod install` no iOS, se reconstruiu o aplicativo após a instalação do pacote e se não está no _Expo managed workflow_ sem `prebuild`.
:::

---

# Compatibilidade

URL: /documentation/caas/ocr/react_native/compatibility

O módulo `@qitech/react-native-caas` exige as seguintes versões mínimas:

| Configuração | Versão mínima |
|------------|--------------|
|React Native|0.74|
|React|18.2.0|
|iOS|15.5|
|Android API Level|35 (Android 15)|
|Datadog SDK nativo (iOS, trazido pelo módulo)|3.x|
|MLKit FaceDetection (iOS, caso já utilizado no seu app)|8.x|

## Versão atual do pacote

| Pacote | Versão |
|--------|--------|
|`@qitech/react-native-caas`|`11.3.0`|
|`@qitech/react-native-device-scan`|`1.2.0`|

:::warning Atenção
Nossos SDKs de iOS só suportam simuladores em máquinas com arquitetura **arm64** (M1/M2/M3/M4) com o **Rosetta** ativo, traduzindo a arquitetura x86_64. Recomendamos o uso de dispositivos físicos para testes.
:::

## Expo

O pacote inclui um _config plugin_ do Expo que aplica automaticamente as configurações nativas de iOS e Android. Veja [Instalação](/documentation/caas/ocr/react_native/installation).

:::info **Atenção**
O módulo não funciona no _Expo managed workflow_ sem `prebuild` — é necessário gerar os projetos nativos com `npx expo prebuild`.
:::

---

# Implementação

URL: /documentation/caas/ocr/react_native/example

A função `startOcr` abre o fluxo nativo de captura de documento, envia as imagens para a API de OCR da QI Tech e devolve as chaves das imagens processadas.

## Mobile Token

Utilizamos um Mobile Token para permitir o acesso autenticado do seu aplicativo à nossa API. Ele provavelmente já foi enviado por e-mail para você. Caso ainda não tenha recebido o seu token, envie um e-mail para suporte.caas@qitech.com.br .

:::info **Atenção**
Cada ambiente (`SANDBOX` e `PRODUCTION`) exige um Mobile Token diferente.
:::

## Assinatura da função

```javascript
const result = await startOcr(
  environment,   // CAAS_ENVIRONMENT
  mobile_token,  // string
  document,      // CAAS_DOCUMENT_TYPE
  options        // OcrOptions (opcional)
);
```

As customizações são opcionais e passadas pelo objeto `options`, descrito em [O objeto OcrOptions](/documentation/caas/ocr/react_native/ocr_options).

## Exemplo mínimo

```tsx
import { CAAS_ENVIRONMENT, CAAS_DOCUMENT_TYPE, startOcr } from '@qitech/react-native-caas';

const response = await startOcr(
  CAAS_ENVIRONMENT.SANDBOX,
  '<YOUR_MOBILE_TOKEN_SENT_BY_QITECH>',
  CAAS_DOCUMENT_TYPE.CNH
);

const { DocumentRecognitionResponse } = JSON.parse(response);
console.log(DocumentRecognitionResponse);
```

:::warning Atenção
A _Promise_ de `startOcr` resolve com uma **string JSON**, não com um objeto. É necessário chamar `JSON.parse()` no retorno. Veja [Coletando os Retornos](/documentation/caas/ocr/react_native/collecting_response).
:::

## Exemplo completo

```tsx
import * as React from 'react';
import { View, Button } from 'react-native';
import {
  CAAS_ENVIRONMENT,
  CAAS_DOCUMENT_TYPE,
  CAAS_FONT_FAMILY,
  CAAS_LOG_LEVEL,
  startOcr,
} from '@qitech/react-native-caas';

const config = {
  ocrMobileToken: '<YOUR_MOBILE_TOKEN_SENT_BY_QITECH>',
  environment: CAAS_ENVIRONMENT.SANDBOX,
  sessionId: '<SESSION_ID>',
  fontColor: '#5dcfe3',
  backgroundColor: '#f5f3f0',
  fontFamily: CAAS_FONT_FAMILY.VERDANA,
  showIntroductionScreens: true,
  showSuccessScreen: true,
  logLevel: CAAS_LOG_LEVEL.DEBUG,
};

export default function App() {
  const [documentType] = React.useState<CAAS_DOCUMENT_TYPE>(CAAS_DOCUMENT_TYPE.CNH);

  const startDocumentOcr = () => {
    startOcr(config.environment, config.ocrMobileToken, documentType, {
      session_id: config.sessionId,
      font_color: config.fontColor,
      background_color: config.backgroundColor,
      font_family: config.fontFamily,
      show_introduction_screens: config.showIntroductionScreens,
      show_success_screen: config.showSuccessScreen,
      onboarding_text_configuration: {
        onboarding_title: 'Dicas Importantes',
        onboarding_first_label: 'Vá para um local iluminado',
        onboarding_second_label: 'Retire o documento do plástico',
        onboarding_third_label: 'Garanta que o documento está corretamente enquadrado',
      },
      log_level: config.logLevel,
    })
      .then((response) => {
        const { DocumentRecognitionResponse } = JSON.parse(response as string);

        if (DocumentRecognitionResponse.length === 1) {
          const { ocr_key, document_type } = DocumentRecognitionResponse[0];
          console.log('Ocr key: ' + ocr_key + ' document type: ' + document_type);
        } else if (DocumentRecognitionResponse.length === 2) {
          // Fluxos de frente e verso retornam duas chaves, uma para cada foto
          const { ocr_front_key } = DocumentRecognitionResponse[0];
          const { ocr_back_key } = DocumentRecognitionResponse[1];
          console.log('Ocr front key: ' + ocr_front_key + ' / Ocr back key: ' + ocr_back_key);
        }
      })
      .catch((error) => {
        console.log('Error executing Ocr. Error: ' + error);
      });
  };

  return (
    <View>
      <Button title="Start OCR" onPress={startDocumentOcr} />
    </View>
  );
}
```

## Fluxo de captura por tipo de documento

O parâmetro `document` define quantas capturas o usuário realizará e, consequentemente, quantos itens o retorno conterá.

| Tipo de documento | Capturas | Retorno |
|-------------------|----------|---------|
|`CAAS_DOCUMENT_TYPE.CNH_FULL`|1 (CNH aberta)|1 item com `ocr_key`|
|`CAAS_DOCUMENT_TYPE.CNH_DIGITAL`|1 (PDF da CNH digital)|1 item com `ocr_key`|
|`CAAS_DOCUMENT_TYPE.ADDRESS`|1 (comprovante de residência)|1 item com `ocr_key`|
|`CAAS_DOCUMENT_TYPE.RG_CIN_DIGITAL`|1 (PDF do RG/CIN digital)|1 item com `ocr_key`|
|`CAAS_DOCUMENT_TYPE.CNH`|2 (frente e verso)|2 itens: `ocr_front_key` e `ocr_back_key`|
|`CAAS_DOCUMENT_TYPE.RG`|2 (frente e verso)|2 itens: `ocr_front_key` e `ocr_back_key`|
|`CAAS_DOCUMENT_TYPE.RNE`|2 (frente e verso)|2 itens: `ocr_front_key` e `ocr_back_key`|
|`CAAS_DOCUMENT_TYPE.CRNM`|2 (frente e verso)|2 itens: `ocr_front_key` e `ocr_back_key`|

## Aplicativos de exemplo

O repositório do módulo contém dois aplicativos prontos para execução, na pasta `examples`:

* **QITechReactNativeExample** — React Native puro
* **QITechExpoExample** — Expo

Em ambos, o arquivo `App.tsx` demonstra o uso completo (Reconhecimento facial + OCR + Scan de dispositivo) com o `@qitech/react-native-caas`, e o `App_ds.tsx` demonstra o uso apenas do Scan de dispositivo com o `@qitech/react-native-device-scan`. Substitua os tokens e API Keys de exemplo pelas suas credenciais. Caso ainda não as tenha recebido, entre em contato com o suporte.caas@qitech.com.br .

---

# Instalação

URL: /documentation/caas/ocr/react_native/installation

## Instalando o pacote

### 1. Configurando o registro npm

Crie um arquivo `.npmrc` na raiz do seu projeto:

```sh
@qitech:registry=https://registry.npmjs.org/
//registry.npmjs.org/:_authToken=NPM_TOKEN_SENT_BY_QI_TECH
```

Substitua `NPM_TOKEN_SENT_BY_QI_TECH` pelo token fornecido pelo suporte. Caso ainda não tenha recebido o seu token, entre em contato com o suporte.caas@qitech.com.br .

### 2. Instalando a dependência

```sh
yarn add @qitech/react-native-caas
```

### 3. Importação

```javascript
import {
  CAAS_ENVIRONMENT,
  CAAS_DOCUMENT_TYPE,
  CAAS_FONT_FAMILY,
  CAAS_LOG_LEVEL,
  FACE_RECON_AUDIO_CONFIGURATION,
  startOcr,
} from '@qitech/react-native-caas';
```

## Configuração do Android

### 1. Repositório Maven da QI Tech

Adicione o repositório Maven da QI Tech ao `build.gradle` do projeto:

```groovy
allprojects {
  repositories {
    maven { url 'https://sdks.qitech.com.br/' }
    ...
  }
}
```

### 2. AdMob

Inicialize o serviço de AdMob adicionando o seguinte código ao `AndroidManifest.xml`:

```xml
<meta-data
  android:name="com.google.android.gms.ads.APPLICATION_ID"
  android:value="<ADMOB_APP_ID>"/>
```

Caso não possua um `ADMOB_APP_ID`, entre em contato com o suporte.caas@qitech.com.br .

## Configuração do iOS

### 1. Permissão de câmera

Adicione a entrada `NSCameraUsageDescription` ao `Info.plist` do seu aplicativo, com o motivo pelo qual o app precisa de acesso à câmera:

```xml
<key>NSCameraUsageDescription</key>
<string>Precisamos da câmera para capturar a foto do seu documento</string>
```

### 2. Source do repositório iOS da QI Tech

Adicione as seguintes sources no topo do seu `Podfile`:

```ruby
source 'https://cdn.cocoapods.org/'
source 'https://github.com/QITechSDKs/iOS.git'
```

### 3. Frameworks estáticos

Necessário **apenas** se você utiliza o Xcode **anterior à versão 26**:

```ruby
use_frameworks! :linkage => :static
```

:::warning Atenção
O [Flipper](https://fbflipper.com/docs/getting-started/react-native/) não funciona com `use_frameworks!`. Remova a chamada `use_flipper()` do seu `Podfile` caso ela esteja presente.
:::

### 4. Estabilidade de módulo

As dependências do Datadog exigem que o `BUILD_LIBRARY_FOR_DISTRIBUTION` esteja habilitado. Adicione o `post_install` abaixo (ou incorpore ao seu `post_install` existente):

```ruby
post_install do |installer|
  installer.pods_project.targets.each do |target|
    if ['DatadogCore', 'DatadogInternal', 'DatadogCrashReporting', 'DatadogLogs'].include?(target.name)
      target.build_configurations.each do |config|
        config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.5'
        config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
      end
    end
  end
end
```

### 5. Instalação dos pods

```sh
cd ios && pod install
```

:::warning Atenção
Se o seu aplicativo já utiliza **Datadog**, use a versão mais recente dentro do major `3.x`. Se utiliza o **FaceDetection do MLKit**, use a versão mais recente dentro do major `8.x`.
:::

## Configuração do Expo

O pacote inclui um _config plugin_ do Expo que aplica automaticamente todas as configurações nativas de iOS e Android descritas acima. No seu `app.json`:

```json
{
  "expo": {
    "plugins": ["@qitech/react-native-caas"]
  }
}
```

Em seguida, execute o `prebuild` para aplicar as alterações nativas:

```sh
npx expo prebuild
```

---

# Introdução

URL: /documentation/caas/ocr/react_native/introduction

Bem vindo ao manual de integração do SDK de OCR (Optical Character Recognition) da QI Tech em React Native! O módulo `@qitech/react-native-caas` expõe, por meio de uma interface TypeScript, os SDKs nativos de Android (Java/Kotlin) e iOS (Swift) da QI Tech. Você pode utilizá-lo para capturar através do seu aplicativo uma imagem de um documento de seu cliente a ser reconhecido, como uma Carteira de Habilitação ou Cédula de identidade, e referenciá-lo através de uma chave nos demais produtos do sistema QI Tech.

## Pacotes disponíveis

| Pacote | Conteúdo | Quando usar |
|--------|----------|-------------|
|`@qitech/react-native-caas`|Reconhecimento facial, OCR e Scan de dispositivo|Quando você precisa de OCR, reconhecimento facial ou do fluxo completo de onboarding.|
|`@qitech/react-native-device-scan`|Somente Scan de dispositivo|Quando você precisa **apenas** de scan de dispositivo — instalação mais leve, com menos dependências nativas.|

:::danger Aviso Importante!
Ambos os pacotes incluem o Scan de dispositivo. **Não instale os dois** — escolha apenas um.
:::

Para o OCR, utilize o `@qitech/react-native-caas`.

## Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso [suporte](mailto:suporte.caas@qitech.com.br) e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

### Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

## Ambientes

Possuímos dois ambientes para os nossos clientes. A seleção é realizada por meio do enumerador `CAAS_ENVIRONMENT`, repassado como primeiro parâmetro da função `startOcr`. No momento, os seguintes ambientes estão disponíveis:

* Produção - `CAAS_ENVIRONMENT.PRODUCTION`
* Sandbox - `CAAS_ENVIRONMENT.SANDBOX`

Cada ambiente exige um Mobile Token diferente.

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.
:::

## Próximos passos

1. [Compatibilidade](/documentation/caas/ocr/react_native/compatibility) — versões mínimas de React Native, iOS e Android.
2. [Instalação](/documentation/caas/ocr/react_native/installation) — instalação do pacote e configuração nativa de Android, iOS e Expo.
3. [Implementação](/documentation/caas/ocr/react_native/example) — exemplo completo da chamada `startOcr`.
4. [O objeto OcrOptions](/documentation/caas/ocr/react_native/ocr_options) — todos os parâmetros de customização.
5. [Coletando os Retornos](/documentation/caas/ocr/react_native/collecting_response) — estrutura de resposta e tratamento de erros.

---

# O objeto OcrOptions

URL: /documentation/caas/ocr/react_native/ocr_options

## Parâmetros de startOcr

| Parâmetro | Tipo | Função | Obrigatório |
|------------|--------------|--------------|--------------|
|environment|CAAS_ENVIRONMENT|Enumerador utilizado para configurar o ambiente de execução para `SANDBOX` ou `PRODUCTION`.|Sim.|
|mobile_token|string|Chave do cliente que identifica que os dados coletados são provenientes do seu aplicativo. Caso ainda não tenha recebido o seu mobile-token, entre em contato com o <a href='mailto:suporte.caas@qitech.com.br'>suporte</a>. Cada ambiente exige um token diferente.|Sim.|
|document|CAAS_DOCUMENT_TYPE|Enumerador que define o fluxo de captura de documentos realizado pelo usuário.|Sim.|
|options|OcrOptions|Objeto opcional com as customizações visuais, textuais e de comportamento do SDK.|Não.|

## OcrOptions

Todos os campos são opcionais. Quando um campo não é informado, o SDK nativo aplica o seu valor padrão.

```typescript
type OcrOptions = {
  session_id?: string;
  font_color?: string;
  background_color?: string;
  font_family?: CAAS_FONT_FAMILY;
  show_introduction_screens?: boolean;
  show_success_screen?: boolean;
  onboarding_text_configuration?: OnboardingTextConfiguration;
  log_level?: CAAS_LOG_LEVEL;
  audio_configuration?: FACE_RECON_AUDIO_CONFIGURATION;
};
```

| Parâmetro | Tipo | Função | Padrão |
|------------|--------------|--------------|--------------|
|session_id|string|Chave que identifica a sessão iniciada no SDK. É utilizada para rastrear todo o fluxo percorrido pelo usuário através de logs. Aceita até 255 caracteres.|Gerado internamente.|
|font_color|string|Cor da fonte e dos ícones das telas do SDK, em formato hexadecimal (ex.: `"#FFFFFF"`).|`"#000000"`|
|background_color|string|Cor de fundo das telas do SDK, em formato hexadecimal (ex.: `"#000000"`).|`"#FFFFFF"`|
|font_family|CAAS_FONT_FAMILY|Fonte utilizada nas telas do SDK.|`CAAS_FONT_FAMILY.OPEN_SANS`|
|show_introduction_screens|boolean|Quando `false`, desativa as telas de introdução à captura do documento.|`true`|
|show_success_screen|boolean|Quando `false`, desativa a tela de sucesso exibida após a captura.|`true`|
|onboarding_text_configuration|OnboardingTextConfiguration|Customiza os textos da tela de onboarding.|Textos padrão do SDK.|
|log_level|CAAS_LOG_LEVEL|Nível de verbosidade dos logs do SDK.|`CAAS_LOG_LEVEL.DEBUG`|
|audio_configuration|FACE_RECON_AUDIO_CONFIGURATION|Configura o guiamento por voz, que narra as instruções de captura em tempo real.|`FACE_RECON_AUDIO_CONFIGURATION.DISABLE`|

## OnboardingTextConfiguration

```typescript
type OnboardingTextConfiguration = {
  onboarding_title?: string;
  onboarding_first_label?: string;
  onboarding_second_label?: string;
  onboarding_third_label?: string;
};
```

| Parâmetro | Tipo | Função |
|------------|--------------|--------------|
|onboarding_title|string|Título da tela de onboarding.|
|onboarding_first_label|string|Primeira instrução exibida ao usuário.|
|onboarding_second_label|string|Segunda instrução exibida ao usuário.|
|onboarding_third_label|string|Terceira instrução exibida ao usuário.|

## Enumeradores

### CAAS_ENVIRONMENT

```typescript
enum CAAS_ENVIRONMENT {
  PRODUCTION = 'production',
  SANDBOX = 'sandbox',
}
```

### CAAS_DOCUMENT_TYPE

```typescript
enum CAAS_DOCUMENT_TYPE {
  CNH_FULL = 'cnh_full',              // CNH brasileira aberta, em foto única
  CNH_DIGITAL = 'cnh_digital',        // PDF da CNH digital brasileira
  CNH = 'cnh',                        // CNH brasileira, frente e verso
  RG = 'rg',                          // RG brasileiro, frente e verso
  ADDRESS = 'proof_of_address',       // Comprovante de residência
  RNE = 'rne',                        // Registro Nacional de Estrangeiro, frente e verso
  CRNM = 'crnm',                      // Carteira de Registro Nacional Migratório, frente e verso
  RG_CIN_DIGITAL = 'rg_cin_digital',  // PDF do RG/CIN digital
}
```

### CAAS_FONT_FAMILY

```typescript
enum CAAS_FONT_FAMILY {
  JAKARTA = 'jakarta',                // apenas iOS
  FUTURA = 'futura',                  // iOS e Android
  VERDANA = 'verdana',                // iOS e Android
  TREBUCHET_MS = 'trebuchetms',       // apenas iOS
  TAMILSANGAM_MN = 'tamilsangammn',   // apenas iOS
  OPEN_SANS = 'open_sans',            // iOS e Android
  HELVETICA = 'helvetica',            // apenas Android
  POPPINS = 'poppins',                // apenas Android
  ROBOTO = 'roboto',                  // apenas Android
  SYSTEM_FONT = 'system_font',        // apenas iOS
}
```

:::info **Atenção**
A disponibilidade das fontes varia por plataforma. Caso uma fonte não suportada seja informada, a plataforma utiliza a sua fonte padrão. Para consistência entre iOS e Android, utilize `FUTURA`, `VERDANA` ou `OPEN_SANS`.
:::

### FACE_RECON_AUDIO_CONFIGURATION

```typescript
enum FACE_RECON_AUDIO_CONFIGURATION {
  ENABLE = 'enable',               // exibe o botão de áudio, com a narração iniciando desligada
  DISABLE = 'disable',             // desativa a narração e oculta o botão
  ACCESSIBILITY = 'accessibility', // exibe o botão com a narração iniciando ligada quando há recursos de acessibilidade ativos
}
```

### CAAS_LOG_LEVEL

```typescript
enum CAAS_LOG_LEVEL {
  TRACE = 'trace',
  DEBUG = 'debug',
  LOG = 'log',
  INFO = 'info',
  WARN = 'warn',
  ERROR = 'error',
}
```

---

# Coletando os Retornos

URL: /documentation/caas/ocr/web/collecting_results

A Web OCR SDK devolve uma _Promise_ que, em caso de sucesso, retorna um **array de objetos**, onde cada objeto representa um lado do documento capturado (frente e/ou verso). Em caso de erro, a Promise é rejeitada com uma string descrevendo o problema.

Abaixo está um exemplo de como mapear cada caso e coletar seus resultados:

```html
<script>
    webOCR.initialize(allowed_templates)
    .then((ocr_results) => {
        console.log(ocr_results)
        // Exemplo de retorno:
        // [
        //   { template: "rg_front", ocr_key: "abc123...", document_capture_session_key: "uuid..." },
        //   { template: "rg_back",  ocr_key: "def456...", document_capture_session_key: "uuid..." }
        // ]
    })
    .catch((error) => {
        console.log(error)
    })
</script>
```

## Descrição do retorno da Web OCR

### Sucesso

O retorno de sucesso é um **array** de objetos, um por lado do documento capturado:

Atributo | Tipo | Descrição
--------- | --------- | ---------
ocr_results | Array | Lista de objetos com as informações de cada captura realizada.

### Atributos de cada objeto no array

Atributo | Tipo | Descrição
--------- | --------- | ---------
ocr_key | String | Chave de identificação da imagem capturada. Pode ser utilizada em qualquer outro serviço do sistema QI Tech.
template | String | Tipo e lado do documento capturado (ex: `rg_front`, `rg_back`, `cnh_front`, `cnh_back`, `cin_digital`).
document_capture_session_key | String | Chave que identifica a sessão de captura do documento.

### Tipos de Erro

Erro | Descrição
--------- | ---------
Invalid Web Token! Please verify your Web Token. | Web Token utilizado é inválido. Caso tenha certeza que esteja utilizando corretamente o Web Token provido pela QI Tech, entre em contato com nosso suporte (suporte.caas@qitech.com.br).
Invalid Document Type! Please provide a valid document type. | Tipo de documento passado para **WebOCR.initialize()** não é válido. Verifique os tipos permitidos na página da [função initialize](./initialize_info.md).
User left Web OCR. | O usuário saiu da Web OCR SDK antes de concluir o envio do documento.

---

# O construtor QiTechWebOCR.WebOCR()

URL: /documentation/caas/ocr/web/constructor_info

:::info Novidade na versão 4.0.0
A partir da versão **4.0.0**, o construtor não recebe mais o `htmlComponent` como primeiro parâmetro — o SDK cria e gerencia seu próprio nó DOM internamente, adicionado ao `document.body`.
:::

O método `.WebOCR()` é responsável pela configuração da instância do seu componente de documentoscopia. O construtor recebe dois parâmetros obrigatórios:

| Parâmetro | Descrição | Obrigatório |
|----------|----------|----------|
| webToken | Chave do cliente que identifica que os dados coletados são provenientes do seu aplicativo. Caso ainda não tenha recebido o seu web-token, entre em contato com o <a href='mailto:suporte.caas@qitech.com.br'>suporte</a>. | Sim |
| sessionId | Utilizado para definir a chave que identifica a sessão iniciada no SDK. É usada para rastrear todo fluxo percorrido pelo usuário na execução da Web OCR através de logs. Este campo aceita uma string de até 255 caracteres. Deve ser único para cada sessão. | Sim |

Após a instanciação, utilize os seguintes métodos encadeados para personalizar o comportamento:

| Nome | Descrição | Obrigatório |
|----------|----------|----------|
| `.setThemeConfiguration(object)` | Personaliza a identidade visual do SDK. | Não |
| `.setShowInstructionScreen(boolean)` | Exibe a tela de introdução com dicas de captura. Padrão: `true`. | Não |
| `.setShowAllowedTemplatesScreen(boolean)` | Exibe a tela que informa os documentos aceitos. Recomendamos ativá-la para que o usuário saiba quais documentos pode enviar. | Não |
| `.setShowSuccessScreen(boolean)` | Exibe a tela de sucesso ao final da captura. Padrão: `true`. | Não |
| `.setSandboxEnvironment()` | Configura o SDK para apontar para o ambiente de Sandbox. | Não |

O método `.setThemeConfiguration` deve receber um objeto com os seguintes campos:

| Nome | Tipo | Descrição |
| -------- | -------- | -------- |
| primaryColor | String | _(recomendado)_ Hexadecimal da cor principal do SDK — usada em botões, ícones e elementos de destaque. Caso não seja informada, o padrão é `#555555`. |
| companyLogo | String | _(recomendado)_ Caminho ou **URL pública** do logo da sua empresa (**PNG**). Caso não seja informado, será exibido um placeholder. |
| fontFamily | String | _(recomendado)_ Nome da _Font Family_ a ser configurada nos textos do SDK. Caso não seja informada, será utilizada a fonte padrão. |

:::caution Compatibilidade
Os campos `backgroundColor` e `buttonColor` ainda são aceitos pelo método `.setThemeConfiguration`, mas são utilizados apenas como fallback para derivar o `primaryColor` quando este não for informado. Prefira usar `primaryColor` diretamente.
:::

## Versões Anteriores (< 4.0.0)

Nas versões anteriores, o construtor recebia o `htmlComponent` como primeiro parâmetro:

```js
var htmlComponent = document.getElementById('webOCR');
var webOCR = new QiTechWebOCR.WebOCR(
    htmlComponent,
    "<WEB_TOKEN>",
    "<SESSION_ID>"
)
```

---

# Implementação

URL: /documentation/caas/ocr/web/example

:::info Novidade na versão 4.0.0
A partir da versão **4.0.0**, o construtor `WebOCR` não recebe mais o `htmlComponent` — o SDK cria e gerencia seu próprio nó DOM internamente.
:::

A inicialização da Web OCR SDK é realizada através da chamada do método `.initialize()`, que pertence à classe `WebOCR`. O processo é dividido em duas etapas principais:

1. **Configuração e Instanciação:** Preparar e configurar a instância do SDK.
2. **Inicialização da Captura:** Iniciar o fluxo de captura de documentos para o usuário final.

## Exemplo completo

```html
<script>
    var webOCR = new QiTechWebOCR.WebOCR(
        "<WEB_TOKEN>",
        "<SESSION_ID>"
    )
    .setThemeConfiguration({
        "companyLogo": "<PATH_OR_URL_TO_YOUR_COMPANY_LOGO>",
        "primaryColor": "<PRIMARY_COLOR_HEX>",
        "fontFamily": "<FONT_FAMILY>"
    })
    .setShowInstructionScreen(true)
    .setShowSuccessScreen(true)
    .setShowAllowedTemplatesScreen(false)
    .setSandboxEnvironment()
    .build()

    function initOCR(allowed_templates) {
        webOCR.initialize(allowed_templates)
        .then((ocr_results) => {
            console.log(ocr_results)
        })
        .catch((error) => {
            console.log(error)
        })
    }

    initOCR(['cnh', 'rg', 'rg_digital'])
</script>
```

## Configuração e Instanciação

Para começar, crie uma nova instância da classe `WebOCR`. O construtor exige dois parâmetros obrigatórios, na ordem especificada abaixo:

- **webToken** `(String)`: Seu token de autenticação para uso da API.
- **sessionId** `(String)`: Um identificador único para a sessão do usuário.

### Personalização (Opcional)

Após criar a instância, utilize os seguintes métodos encadeados para personalizar a experiência:

- **`setThemeConfiguration`** `(object)`: Personaliza a aparência do SDK. Campos aceitos:
    - `primaryColor` `(String)`: Cor principal em formato hexadecimal — usada em botões, ícones e destaques (ex: `'#0000FF'`).
    - `companyLogo` `(String)`: URL ou path para o logo da sua empresa.
    - `fontFamily` `(String)`: Família da fonte (ex: `'Arial'`).

- **`setShowInstructionScreen`** `(boolean)`: Define se a tela inicial de instruções será exibida.

- **`setShowAllowedTemplatesScreen`** `(boolean)`: Define se a tela que informa os documentos aceitos será exibida. Recomendamos ativá-la para que o usuário saiba quais documentos pode enviar.

- **`setShowSuccessScreen`** `(boolean)`: Define se a tela de sucesso ao final da captura será exibida.

- **`setSandboxEnvironment`**: Configura o SDK para apontar para o ambiente de homologação (Sandbox).

### Build

Por fim, você **deve** chamar a função **build()** para instanciar a classe **WebOCR** com as configurações passadas. Para mais detalhes sobre o construtor, veja a página sobre o [construtor](./constructor_info.md).

## Inicializando a Captura de Documentos

Com a instância da `WebOCR` devidamente configurada, chame o método `initialize()` para iniciar o fluxo de captura. Este método recebe como parâmetro uma lista (array) de strings, onde cada string representa um tipo de documento que o usuário poderá enviar.

### Tabela com templates aceitos

Nome | Tipo | Descrição
---- | ---- | ---------
cnh | String | Captura de CNH física (fechada), em duas etapas, FRENTE e VERSO
rg | String | Captura de RG físico (fechado), em duas etapas, FRENTE e VERSO
cin_digital | String | Envio da CIN **digital** (pdf) emitida por um aplicativo oficial
rg_digital | String | Envio do RG **digital** (pdf) emitido por um aplicativo oficial
rne | String | Captura do RNE físico, em duas etapas, FRENTE e VERSO
crnm | String | Captura da CRNM física, em duas etapas, FRENTE e VERSO
others | String | Deve ser usado para permitir o envio de outros documentos além dos listados acima

:::caution Atenção
Adicionar o tipo `others` nos templates permitidos faz com que todo documento enviado seja aceito. Assim, mesmo documentos não oficiais serão aceitos.
:::

### Tratamento do Retorno

O método `initialize()` retorna uma Promise:

- **Sucesso:** A Promise é resolvida com um **array de objetos**, onde cada objeto representa um lado do documento capturado. Consulte a página [Coletando os Retornos](./collecting_results.md) para detalhes sobre o formato.
- **Erro:** A Promise é rejeitada. Você pode capturar esses erros utilizando o método `.catch()`.

---

# Importando a biblioteca

URL: /documentation/caas/ocr/web/import

Para importar a nossa biblioteca, adicione a URL no _src_ de uma TAG **script** no HTML de seu website, assim como o exemplo abaixo:

```html
    <script src="https://ocr.caas.qitech.app/4-1-1/ocr.js"></script>
```

---

# A função initialize()

URL: /documentation/caas/ocr/web/initialize_info

Para iniciar a Web OCR SDK, após ter instanciado a classe **WebOCR**, chame a função **initialize()** passando uma lista de documentos permitidos como parâmetro.

Abaixo temos o detalhamento de cada um dos possíveis tipos de documento:

Nome | Tipo | Descrição
---- | ---- | ---------
cnh | String | Captura de CNH física (fechada), em duas etapas, FRENTE e VERSO
rg | String | Captura de RG físico (fechado), em duas etapas, FRENTE e VERSO
cin_digital | String | Envio da CIN **digital** (pdf) emitida por um aplicativo oficial
rg_digital | String | Envio do RG **digital** (pdf) emitido por um aplicativo oficial
rne | String | Captura do RNE físico, em duas etapas, FRENTE e VERSO
crnm | String | Captura da CRNM física, em duas etapas, FRENTE e VERSO
others | String | Deve ser usado para permitir o envio de outros documentos além dos listados acima

:::caution Atenção
Adicionar o tipo `others` nos templates permitidos faz com que todo documento enviado seja aceito. Assim, mesmo documentos não oficiais serão aceitos.
:::

## Exemplo de Implementação

Um exemplo de implementação da Web OCR SDK pode ser visto abaixo:

```html
<!DOCTYPE html>
<html lang="pt-BR">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Web OCR</title>
    <script src="https://ocr.caas.qitech.app/4-1-1/ocr.js"></script>
</head>
<body>
    <div class="demo-app-container">
        <button onclick="initOCR(['rg', 'cnh', 'rg_digital'])">
            Iniciar coleta do documento
        </button>
    </div>
</body>

<script>
    var webOCR = new QiTechWebOCR.WebOCR(
        "<WEB_TOKEN>",
        "<SESSION_ID>"
    )
    .setThemeConfiguration({
        "companyLogo": "https://my_company/logo.png",
        "primaryColor": "#FF9900",
        "fontFamily": "Verdana"
    })
    .setShowInstructionScreen(true)
    .setShowSuccessScreen(true)
    .setShowAllowedTemplatesScreen(true)
    .setSandboxEnvironment()
    .build()

    function initOCR(allowed_templates) {
        webOCR.initialize(allowed_templates)
        .then((ocr_results) => {
            console.log(ocr_results)
        })
        .catch((error) => {
            console.log(error)
        })
    }
</script>
</html>
```

No exemplo acima, a instância da classe **WebOCR** é criada com os parâmetros obrigatórios e opcionais. Com o SDK instanciado, a função **initOCR()** inicializa o fluxo de captura e, ao final, registra em log o array de resultados retornados ou o erro, caso ocorra.

## Tratamento do Retorno

O método `initialize()` retorna uma Promise:

- **Sucesso:** A Promise é resolvida com um **array de objetos**, onde cada objeto representa um documento capturado. Consulte a página [Coletando os Retornos](./collecting_results.md) para detalhes sobre o formato.

- **Erro:** A Promise é rejeitada. Você pode capturar esses erros utilizando o método `.catch()`.

---

# Introdução

URL: /documentation/caas/ocr/web/introduction

Bem-vindo à Web OCR SDK (Optical Character Recognition) da QI Tech para leitura de documentos. Este SDK realiza a captura de documentos e o envio a API de OCR da QI Tech . Você pode utilizá-lo para capturar através do seu aplicativo web uma imagem de um documento de seu cliente a ser reconhecido, como uma Carteira de Habilitação ou Cédula de Identidade, e referenciá-lo através de uma chave nos demais produtos do sistema QI Tech.

## Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso [suporte](mailto:suporte.caas@qitech.com.br) e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

### Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já entendeu), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.  
:::

---

# Autenticação

URL: /documentation/caas/onboarding/authentication

> Para autenticar uma chamada, utilize o código seguinte:

```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

> Substitua a API Key 'EXAMPLE-OF-API-KEY' pela sua chave, que deve ser obtida através do nosso time de suporte.

Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para suporte.caas@qitech.com.br .

Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:

`Authorization: EXAMPLE-OF-API-KEY`

:::info **Atenção**

Você deve substituir EXAMPLE-OF-API-KEY pela sua chave, que deve ser obtida através do nosso time de suporte.
:::

---

# Status HTTP

URL: /documentation/caas/onboarding/http_status

Todas as APIs da QI Tech utilizam a seguinte padronização nos status HTTP de retorno, de acordo com o RFC 7231 :

Status HTTP | Significado | Descrição
---------- | ------- | ---------------------------------
400 | Bad Request | A requisição enviada possui algum erro de formatação. Na maioria dos casos, retornamos no corpo da mensagem uma explicação de onde está o erro.
401 | Unauthorized | Houve algum problema na autenticação, verifique se a API Key está correta e no header correto, de acordo com a seção Autenticação .
403 | Forbidden | O endpoint acessado é de uso interno e não está disponível para esta API Key.
404 | Not Found | O dado requisitado não foi encontrado usando a chave utilizada. Este status também é retornado quando um endpoint inválido é requisitado.
405 | Method Not Allowed | O método HTTP utilizado não se aplica ao endpoint utilizado.
406 | Not Acceptable | Os dados enviados no corpo da requisição são inválidos. Em geral, isso significa que os dados enviados não são um JSON válido.
409 | Conflict | O id da requisição corresponde a um id já processado anteriormente. Este status é retornado no caso de requisições duplicadas enviadas ao servidor.
500 | Internal Server Error | Tivemos um problema para processar esta requisição, ao encontrarmos esse erro nossos especialistas são automaticamente notificados e iniciam a análise e solução imediatamente.
503 | Service Unavailable | Você se deparou com uma indisponibilidade, planejada ou não, de infraestrutura dos nossos servidores.

---

# Integrações

URL: /documentation/caas/onboarding/integrations

Nossas soluções mobile são compatíveis com as mais diversas tecnologias como Flutter, Ionic Cordova, Capacitor, React Native, Java, Swift entre outras. Caso tenha interesse em alguma dessas integrações, entre em contato com nosso suporte para liberarmos acesso aos nossos repositórios privados.

---

# Introdução

URL: /documentation/caas/onboarding/introduction

Bem vindo à API de Onboarding da QI Tech! Esta API dá acesso aos serviços de Prevenção a Fraudes, à lavagem de dinheiro e de KYC em um Cadastro da sua plataforma! 

Esta API pode ser utilizada para a validação cadastral de clientes para:

* Abertura de Contas Digitais ou Wallets
* Emissão de Cartão
* Validação de Usuários de Aplicativos
* Cadastro para Concessão de Crédito
* Cadastro para Contratação de Seguros
* Validação de Dados Cadastrais

Você pode utilizar a nossa API para acessar os endpoints para avaliar os seguintes tipos de Cadastro:

* **Natural Person** - utilizado para validação cadastral de Pessoas Físicas
* **Legal Person** - utilizado para validação cadastral de Pessoas Jurídicas

Os diferentes tipos de Cadastro acima possuem objetos e endpoints específicos com o intuito de cobrir as particularidades de cada entidade. 

## Como funciona

| Passo | Chamada | O que faz |
| --- | --- | --- |
| 1 | `POST /onboarding/natural_person` ou `/legal_person` | Envia o cadastro; a QI Tech executa a sua árvore de decisão e devolve o resultado em `analysis_status`. |
| 2 | `PUT /onboarding/{tipo}/{id}` | Informa o desfecho na sua plataforma (`client_status`). Retroalimenta os modelos. |
| 3 | `GET /onboarding/{tipo}/{id}` | Consulta o estado atual e o histórico de eventos. |

Resultados assíncronos chegam por [Webhook](/documentation/caas/onboarding/webhook).

:::tip Integre em minutos
São apenas **3 campos obrigatórios** em cada tipo de cadastro. Comece pelo payload mínimo em [Natural Person](/documentation/caas/onboarding/natural_person#payload-minimo) ou [Legal Person](/documentation/caas/onboarding/legal_person#payload-minimo), com exemplos em Python, PHP, Node.js, Java, C# e curl.
:::

:::info Usa os SDKs de biometria, OCR ou Device Scan?
As chaves devolvidas pelos SDKs entram em lugares diferentes em PF e PJ. Veja [Dados do SDK](/documentation/caas/onboarding/sdk_integration).
:::

## Problemas?

Nós não somos uma companhia que se esconde atrás de uma API! Entre em contato com o nosso suporte e nós responderemos o mais rápido possível. Fique à vontade para nos ligar caso deseje uma resposta rápida!

### Adoramos Feedback

Mesmo que você já tenha resolvido o seu problema ou que ele seja muito simples (Até mesmo um typo ou uma organização inadequada que você já notou), envie-nos um e-mail, assim nós tornamos a documentação cada vez mais prática e a próxima pessoa não vai precisar sofrer as dores que você sofreu!

## Ambientes

Possuímos dois ambientes para os nossos clientes. As URLs base das APIs são:

* Produção - `https://api.caas.qitech.app/onboarding/`
* Sandbox - `https://api.sandbox.caas.qitech.app/onboarding/`

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.  
:::

No ambiente de Sandbox, as análises enviadas não são cobradas e são respondidas de acordo com a seguinte regra baseada no primeiro dígito do documento - CPF para Pessoas Físicas e CNPJ para Pessoas Jurídicas:

Dígito | Decisão
------ | -------
0 | Em Análise Manual
1 | Em Análise Manual
2 | Em Análise Manual
3 | Em Análise Manual
4 | Contestado Automaticamente
5 | Derivado para Análise Manual - Com reprovação posterior
6 | Derivado para Análise Manual - Com aprovação posterior
7 | Pendente
8 | Reprovado Automaticamente
9 | Aprovado Automaticamente

Nos casos de CPF ou CNPJ com início nos dígitos 1 ou 2, deve-se entrar em contato com nosso suporte para que a tratativa manual seja feita corretamente.

## Somente HTTPS

Por questão de segurança, toda a comunicação com as APIs da QI Tech deve ser realizada utilizando a comunicação HTTPS. Para evitar que, por desatenção ou outro motivo, sejam feitas chamadas HTTP, este servidor somente disponibiliza a porta 443 com comunicação TLS 1.2. Chamadas realizadas utilizando outros protocolos serão automaticamente negadas.

---

# Objeto Legal Person

URL: /documentation/caas/onboarding/legal_person

Objeto Legal Person

Envia o cadastro de uma **pessoa jurídica** para análise de fraude e KYC. A QI Tech executa a sua árvore de decisão contra os dados enviados e devolve em `analysis_status` o resultado que a **sua política** determinou — veja [Dinâmica dos status](/documentation/caas/onboarding/status_dynamics).

:::tip Comece pelo payload mínimo
São apenas **3 campos obrigatórios**. Vá direto para [Payload mínimo](#payload-minimo).
:::

:::danger Onde entram as chaves do SDK
Em Legal Person, `face` e documentos de identidade ficam **dentro de `legal_representatives[]`**, e o `source.session_id` fica na **raiz**. Essa é a principal diferença em relação a Pessoa Física — veja [Integrando os dados do SDK](/documentation/caas/onboarding/sdk_integration).
:::

---

## Payload mínimo

```json title="Payload mínimo — 3 campos obrigatórios"
{
  "id": "87654321",
  "registration_date": "2026-08-07T11:37:15-03:00",
  "document_number": "11.111.111/0001-11"
}
```

Resposta:

```json
{
  "id": "87654321",
  "analysis_status": "automatically_approved",
  "reason": "rule_decision_enum"
}
```

:::info Campos adicionais
Quanto mais dados forem enviados, mais validações são possíveis de se fazer no motor de regras.
:::

---

## Enviar um cadastro

ENDPOINT /onboarding/legal_person
MÉTODO POST

### Query parameters

analyze
boolean
opcional — padrão true
Com true , a sua árvore de decisão é executada. Com false , o cadastro é apenas registrado (sem cobrança) e a resposta retorna not_analysed .

**Python**

```python
import requests

BASE_URL = "https://api.sandbox.caas.qitech.app"
API_KEY = "YOUR_API_KEY"

payload = {
    "id": "87654321",
    "registration_date": "2026-08-07T11:37:15-03:00",
    "document_number": "11.111.111/0001-11"
}

response = requests.post(
    f"{BASE_URL}/onboarding/legal_person",
    params={"analyze": "true"},
    json=payload,
    headers={"Authorization": API_KEY},
    timeout=30,
)

response.raise_for_status()
print(response.json()["analysis_status"])
```

**PHP**

```php
<?php

$baseUrl = 'https://api.sandbox.caas.qitech.app';
$apiKey  = 'YOUR_API_KEY';

$payload = [
    'id'                => '87654321',
    'registration_date' => '2026-08-07T11:37:15-03:00',
    'document_number'   => '11.111.111/0001-11'
];

$ch = curl_init($baseUrl . '/onboarding/legal_person?analyze=true');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'Authorization: ' . $apiKey
    ],
    CURLOPT_POSTFIELDS => json_encode($payload)
]);

$body   = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status !== 200) {
    throw new RuntimeException("Onboarding retornou HTTP {$status}: {$body}");
}

echo json_decode($body, true)['analysis_status'];
```

**Node.js**

```javascript
const BASE_URL = "https://api.sandbox.caas.qitech.app";
const API_KEY = "YOUR_API_KEY";

const payload = {
  id: "87654321",
  registration_date: "2026-08-07T11:37:15-03:00",
  document_number: "11.111.111/0001-11"
};

async function createLegalPerson() {
  const response = await fetch(
    `${BASE_URL}/onboarding/legal_person?analyze=true`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: API_KEY
      },
      body: JSON.stringify(payload)
    },
  );

  if (!response.ok) {
    throw new Error(`Onboarding retornou HTTP ${response.status}`);
  }

  const result = await response.json();
  console.log(result.analysis_status);
  return result;
}

createLegalPerson();
```

**Java**

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class CreateLegalPerson {

    private static final String BASE_URL = "https://api.sandbox.caas.qitech.app";
    private static final String API_KEY = "YOUR_API_KEY";

    public static void main(String[] args) throws Exception {
        String payload = """
            {
              "id": "87654321",
              "registration_date": "2026-08-07T11:37:15-03:00",
              "document_number": "11.111.111/0001-11"
            }
            """;

        HttpClient client = HttpClient.newHttpClient();

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(BASE_URL + "/onboarding/legal_person?analyze=true"))
                .header("Content-Type", "application/json")
                .header("Authorization", API_KEY)
                .timeout(Duration.ofSeconds(30))
                .POST(HttpRequest.BodyPublishers.ofString(payload))
                .build();

        HttpResponse<String> response =
                client.send(request, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() != 200) {
            throw new IllegalStateException(
                    "Onboarding retornou HTTP " + response.statusCode() + ": " + response.body());
        }

        System.out.println(response.body());
    }
}
```

**C#**

```csharp
using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

public class CreateLegalPerson
{
    private const string BaseUrl = "https://api.sandbox.caas.qitech.app";
    private const string ApiKey = "YOUR_API_KEY";

    public static async Task Main()
    {
        var payload = new
        {
            id = "87654321",
            registration_date = "2026-08-07T11:37:15-03:00",
            document_number = "11.111.111/0001-11"
        };

        using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
        client.DefaultRequestHeaders.Add("Authorization", ApiKey);

        var content = new StringContent(
            JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");

        var response = await client.PostAsync(
            $"{BaseUrl}/onboarding/legal_person?analyze=true", content);

        var body = await response.Content.ReadAsStringAsync();

        if (!response.IsSuccessStatusCode)
        {
            throw new InvalidOperationException(
                $"Onboarding retornou HTTP {(int)response.StatusCode}: {body}");
        }

        Console.WriteLine(body);
    }
}
```

**curl**

```bash
curl -X POST \
  'https://api.sandbox.caas.qitech.app/onboarding/legal_person?analyze=true' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY' \
  -d '{
    "id": "87654321",
    "registration_date": "2026-08-07T11:37:15-03:00",
    "document_number": "11.111.111/0001-11"
  }'
```

---

## Campos do objeto

### Obrigatórios

id
string
obrigatório
Identificador da análise. 1 a 50 caracteres. Único por requisição — repetido retorna HTTP 409.

registration_date
datetime
obrigatório
Data e hora do cadastro, com fuso horário. Mesmo formato de Natural Person.

document_number
string
obrigatório
CNPJ com pontuação , no formato XX.XXX.XXX/XXXX-XX . 18 caracteres.

### Dados da empresa

registration_id
string
opcional
Identificador do cadastro no seu sistema. Assume o valor de id quando omitido.

legal_name
string
opcional
Razão social.

trading_name
string
opcional
Nome fantasia.

foundation_date
date
opcional
Data de constituição no formato YYYY-MM-DD .

website
string
opcional
Site da empresa. Até 10.000 caracteres.

activity
string
opcional
Descrição da atividade econômica.

activity_code
string
opcional
CNAE no formato XX.XX-X-XX . Exatamente 10 caracteres.

merchant_category_code
enum
opcional
MCC de 4 dígitos conforme ISO 18245. Aceita apenas códigos da lista oficial.

tier
string
opcional
Porte da empresa. Até 10 caracteres. Ex.: mei , epp , me .

annual_revenues
integer
opcional
Faturamento anual em centavos .

monthly_revenues
integer
opcional
Faturamento mensal em centavos .

### Contato e localização

emails
array
opcional
Lista de objetos Email . Cada item exige email .

phones
array
opcional
Lista de objetos Phone . Cada item exige international_dial_code , area_code e number .

address
object
opcional
Objeto Address . Se enviado, exige postal_code .

documents
object
opcional
Documentos da empresa . Aceita apenas ie , company_statute e proof_of_address — veja o aviso abaixo, Dados do SDK e Objetos compartilhados .

source
object
opcional
Origem da requisição. É aqui na raiz que o session_id do Device Scan deve ser enviado — veja Dados do SDK .

### Quadro societário

legal_representatives
array
opcional
Lista de objetos LegalRepresentative . É dentro deste array que entram face e documentos de identidade (RG, CNH) — veja Dados do SDK .

partners
array
opcional
Lista de objetos Partner com os sócios da empresa.

final_beneficiaries
array
opcional
Lista de objetos FinalBeneficiary com os beneficiários finais.

### Classificação e extras

analysis_type
string
opcional
Tipo de análise, quando sua conta tem mais de um fluxo configurado.

client_category
string
opcional
Categoria do cliente na sua plataforma.

partnership_key
string
opcional
Identificador da parceria associada.

related_account_type
string
opcional
Tipo de conta relacionada.

custom_data
object
opcional
Campos personalizados. Requer schema previamente cadastrado pela QI Tech.

```json title="Payload completo"
{
  "id": "87654321",
  "registration_id": "cad-pj-1234",
  "registration_date": "2026-08-07T11:37:15-03:00",
  "client_category": "Premium Account",
  "legal_name": "Empresa Exemplo LTDA",
  "trading_name": "Barbearia do John",
  "document_number": "11.111.111/0001-11",
  "foundation_date": "1992-09-15",
  "website": "www.exemplo.com.br",
  "activity": "Barber Shops",
  "activity_code": "96.02-5-01",
  "merchant_category_code": "0742",
  "tier": "epp",
  "annual_revenues": 180000000,
  "monthly_revenues": 15000000,
  "emails": [{ "email": "contato@exemplo.com.br" }],
  "address": {
    "street": "Rua do Teste",
    "number": "111",
    "neighborhood": "Centro",
    "city": "São Paulo",
    "uf": "SP",
    "postal_code": "04570-140",
    "country": "BRA"
  },
  "phones": [
    {
      "international_dial_code": "55",
      "area_code": "11",
      "number": "999999999",
      "type": "commercial"
    }
  ],
  "source": {
    "channel": "web",
    "platform": "web",
    "ip": "255.201.26.1",
    "session_id": "54b8e3cf-15de-41e5-9305-0ecf059d6e2a"
  },
  "documents": {
    "company_statute": {
      "ocr_key": "d8fa2fb0-5199-47c3-daae-bd8ef03f4ea9"
    },
    "proof_of_address": {
      "document_analysis_id": "e9ab3ac1-62aa-48d4-ebbf-ce9fa14a5fb0"
    }
  },
  "legal_representatives": [
    {
      "id": "rep-001",
      "name": "Maria Sample",
      "document_number": "222.222.222-22",
      "birthdate": "1985-03-22",
      "mother_name": "Ana Sample",
      "pleaded_pep": false,
      "face": {
        "type": "zaig_sdk",
        "registration_key": "46f38cf4-07b2-4de6-93e9-64b51a68378a"
      },
      "documents": {
        "cnh": {
          "register_number": "05163811694",
          "issuer_state": "SP",
          "ocr_key": "c7ef1eaf-4088-46b2-c9fd-ac7de92e3d98"
        }
      }
    }
  ],
  "partners": [
    {
      "name": "Maria Sample",
      "document_number": "222.222.222-22"
    }
  ],
  "final_beneficiaries": [
    {
      "name": "Maria Sample",
      "document_number": "222.222.222-22"
    }
  ]
}
```

:::warning Campos não previstos são rejeitados
O schema usa `additionalProperties: false`. Qualquer campo fora dos listados retorna **HTTP 400**.
:::

:::danger RG e CNH não vão na raiz
Na raiz de Legal Person, `documents` aceita **apenas** `ie`, `company_statute` e `proof_of_address`. Documentos de identidade pertencem ao representante legal, dentro de `legal_representatives[].documents`. Enviá-los na raiz retorna **HTTP 400**.
:::

---

## Formatos de campo

### `document_number` — CNPJ

Formato `XX.XXX.XXX/XXXX-XX`, com pontuação, 18 caracteres. Apenas dígitos é rejeitado.

### `activity_code` — CNAE

Formato `XX.XX-X-XX`, exatamente 10 caracteres. Ex.: `96.02-5-01`.

### `registration_date`

Mesmo formato de Natural Person: ISO 8601 com fuso horário, offset terminado em `:00`/`:30` ou sufixo `Z`.

### Valores monetários

`annual_revenues` e `monthly_revenues` são inteiros em **centavos**. R$ 150.000,00 → `15000000`.

---

## Representantes, sócios e beneficiários

Os três arrays aceitam os mesmos campos de identificação de uma pessoa física (`name`, `document_number`, `birthdate`, `gender`, `nationality`, `mother_name`, `occupation`, `emails`, `phones`, `address`, `pleaded_pep`).

**Somente `legal_representatives[]` aceita `face` e `documents`** — é ali que entram as chaves de biometria e OCR do representante. Veja [Integrando os dados do SDK](/documentation/caas/onboarding/sdk_integration).

---

## Testando no Sandbox

A decisão é determinística, definida pelo **primeiro dígito do CNPJ**:

| Primeiro dígito | Resultado |
| --- | --- |
| `9` | `automatically_approved` |
| `8` | `automatically_reproved` |
| `7` | `pending` |
| `6` | Análise manual, com aprovação posterior |
| `5` | Análise manual, com reprovação posterior |
| `4` | `automatically_challenged` |
| `0` a `3` | `in_manual_analysis` |

:::danger Aviso importante
Não utilize dados reais de pessoas jurídicas no ambiente de Sandbox.
:::

---

## Erros

| Status | Situação | Como resolver |
| --- | --- | --- |
| 400 | Campo obrigatório ausente, formato inválido ou campo não previsto. | Veja a `description` da resposta. |
| 400 | `rg`/`cnh` na raiz de `documents`. | Mova para `legal_representatives[]`. |
| 400 | `custom_data` sem schema cadastrado. | Solicite o cadastro ao suporte. |
| 401 | Header `Authorization` ausente ou chave desativada. | Verifique a chave. |
| 403 | API Key inválida. | Confirme com o suporte. |
| 409 | `id` já utilizado. | Gere um `id` único. |
| 500 | Erro interno. | Notificação automática à nossa equipe. |

Lista completa em [Status HTTP](/documentation/caas/onboarding/http_status).

---

## Checklist de integração

- [ ] `POST /onboarding/legal_person` com o payload mínimo retornando `200` no Sandbox.
- [ ] CNPJ com pontuação e CNAE no formato `XX.XX-X-XX`.
- [ ] `source.session_id` preenchido **na raiz** (sem isso, o device não aparece na dashboard de PJ).
- [ ] `face` e documentos de identidade dentro de `legal_representatives[]`.
- [ ] Na raiz de `documents`, apenas `ie`, `company_statute`, `proof_of_address`.
- [ ] Valores monetários em centavos.
- [ ] [Webhook](/documentation/caas/onboarding/webhook) configurado para o resultado assíncrono.

---

# Objeto Natural Person

URL: /documentation/caas/onboarding/natural_person

Objeto Natural Person

Envia o cadastro de uma **pessoa física** para análise de fraude e KYC. A QI Tech executa a sua árvore de decisão contra os dados enviados e devolve em `analysis_status` o resultado que a **sua política** determinou — veja [Dinâmica dos status](/documentation/caas/onboarding/status_dynamics).

:::tip Comece pelo payload mínimo
São apenas **3 campos obrigatórios**. Vá direto para [Payload mínimo](#payload-minimo) e depois adicione o que fizer sentido para o seu caso.
:::

:::caution Envie dados finais
Os dados enviados devem ser os definitivos. CPF, nome e data de nascimento não devem mudar depois desta chamada — isso garante consistência da base antifraude e uma avaliação realista de risco.
:::

:::info Usa os SDKs de biometria, OCR ou Device Scan?
As chaves devolvidas pelos SDKs entram nos blocos `face`, `documents` e `source` deste payload. Onde cada uma vai — e o que muda em relação a Pessoa Jurídica — está em **[Dados do SDK (face, documentos e device)](/documentation/caas/onboarding/sdk_integration)**.
:::

---

## Payload mínimo

Este é o menor corpo aceito pelo `POST /onboarding/natural_person`.

```json title="Payload mínimo — 3 campos obrigatórios"
{
  "id": "12345678",
  "registration_date": "2026-08-07T11:37:15-03:00",
  "document_number": "111.111.111-11"
}
```

Resposta:

```json
{
  "id": "12345678",
  "analysis_status": "automatically_approved",
  "reason": "rule_decision_enum"
}
```

:::info Campos adicionais
Quanto mais dados forem enviados, mais validações são possíveis de se fazer no motor de regras.
:::

---

## Enviar um cadastro

ENDPOINT /onboarding/natural_person
MÉTODO POST

### Query parameters

analyze
boolean
opcional — padrão true
Com true , a sua árvore de decisão é executada e a resposta traz o resultado. Com false , o cadastro é apenas registrado (sem cobrança) e passa a compor o histórico usado em análises futuras — a resposta retorna not_analysed .

### Exemplos de requisição

**Python**

```python
import requests

BASE_URL = "https://api.sandbox.caas.qitech.app"
API_KEY = "YOUR_API_KEY"

payload = {
    "id": "12345678",
    "registration_date": "2026-08-07T11:37:15-03:00",
    "document_number": "111.111.111-11"
}

response = requests.post(
    f"{BASE_URL}/onboarding/natural_person",
    params={"analyze": "true"},
    json=payload,
    headers={"Authorization": API_KEY},
    timeout=30,
)

response.raise_for_status()
result = response.json()
print(result["analysis_status"])  # automatically_approved
```

**PHP**

```php
<?php

$baseUrl = 'https://api.sandbox.caas.qitech.app';
$apiKey  = 'YOUR_API_KEY';

$payload = [
    'id'                => '12345678',
    'registration_date' => '2026-08-07T11:37:15-03:00',
    'document_number'   => '111.111.111-11'
];

$ch = curl_init($baseUrl . '/onboarding/natural_person?analyze=true');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'Authorization: ' . $apiKey
    ],
    CURLOPT_POSTFIELDS => json_encode($payload)
]);

$body   = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status !== 200) {
    throw new RuntimeException("Onboarding retornou HTTP {$status}: {$body}");
}

$result = json_decode($body, true);
echo $result['analysis_status'];
```

**Node.js**

```javascript
const BASE_URL = "https://api.sandbox.caas.qitech.app";
const API_KEY = "YOUR_API_KEY";

const payload = {
  id: "12345678",
  registration_date: "2026-08-07T11:37:15-03:00",
  document_number: "111.111.111-11"
};

async function createRegistration() {
  const response = await fetch(
    `${BASE_URL}/onboarding/natural_person?analyze=true`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: API_KEY
      },
      body: JSON.stringify(payload)
    },
  );

  if (!response.ok) {
    throw new Error(`Onboarding retornou HTTP ${response.status}`);
  }

  const result = await response.json();
  console.log(result.analysis_status);
  return result;
}

createRegistration();
```

**Java**

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class CreateNaturalPerson {

    private static final String BASE_URL = "https://api.sandbox.caas.qitech.app";
    private static final String API_KEY = "YOUR_API_KEY";

    public static void main(String[] args) throws Exception {
        String payload = """
            {
              "id": "12345678",
              "registration_date": "2026-08-07T11:37:15-03:00",
              "document_number": "111.111.111-11"
            }
            """;

        HttpClient client = HttpClient.newHttpClient();

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(BASE_URL + "/onboarding/natural_person?analyze=true"))
                .header("Content-Type", "application/json")
                .header("Authorization", API_KEY)
                .timeout(Duration.ofSeconds(30))
                .POST(HttpRequest.BodyPublishers.ofString(payload))
                .build();

        HttpResponse<String> response =
                client.send(request, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() != 200) {
            throw new IllegalStateException(
                    "Onboarding retornou HTTP " + response.statusCode() + ": " + response.body());
        }

        System.out.println(response.body());
    }
}
```

**C#**

```csharp
using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

public class CreateNaturalPerson
{
    private const string BaseUrl = "https://api.sandbox.caas.qitech.app";
    private const string ApiKey = "YOUR_API_KEY";

    public static async Task Main()
    {
        var payload = new
        {
            id = "12345678",
            registration_date = "2026-08-07T11:37:15-03:00",
            document_number = "111.111.111-11"
        };

        using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
        client.DefaultRequestHeaders.Add("Authorization", ApiKey);

        var content = new StringContent(
            JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");

        var response = await client.PostAsync(
            $"{BaseUrl}/onboarding/natural_person?analyze=true", content);

        var body = await response.Content.ReadAsStringAsync();

        if (!response.IsSuccessStatusCode)
        {
            throw new InvalidOperationException(
                $"Onboarding retornou HTTP {(int)response.StatusCode}: {body}");
        }

        Console.WriteLine(body);
    }
}
```

**curl**

```bash
curl -X POST \
  'https://api.sandbox.caas.qitech.app/onboarding/natural_person?analyze=true' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY' \
  -d '{
    "id": "12345678",
    "registration_date": "2026-08-07T11:37:15-03:00",
    "document_number": "111.111.111-11"
  }'
```

### Resposta

id
string
O mesmo id enviado na requisição.

analysis_status
enum
Resultado da execução da sua árvore de decisão. Veja Dinâmica dos status .

reason
string
Motivo da decisão, quando disponível.

```json
{
  "id": "12345678",
  "analysis_status": "automatically_approved",
  "reason": "rule_decision_enum"
}
```

:::info Resposta assíncrona
Quando a análise demora mais que o esperado, a resposta vem como `in_queue` ou `pending` e o resultado final chega por [Webhook](/documentation/caas/onboarding/webhook). Trate esses dois status como "aguardando" — não como recusa.
:::

---

## Campos do objeto

### Obrigatórios

id
string
obrigatório
Identificador da análise no seu sistema. 1 a 50 caracteres. Deve ser único por requisição — um id repetido retorna HTTP 409.

registration_date
datetime
obrigatório
Data e hora do cadastro, com fuso horário . Veja o formato aceito .

document_number
string
obrigatório
CPF com pontuação , no formato XXX.XXX.XXX-XX . Exatamente 14 caracteres.

### Identificação

registration_id
string
opcional
Identificador do cadastro no seu sistema. Use o mesmo valor em análises diferentes do mesmo cadastro para agrupá-las. Quando omitido, assume o valor de id .

name
string
opcional
Nome completo. 1 a 500 caracteres.

birthdate
date
opcional
Data de nascimento no formato YYYY-MM-DD .

gender
enum
opcional
male ou female .

nationality
string
opcional
País em ISO 3166-1 alpha-3, 3 letras maiúsculas. Ex.: BRA .

mother_name
string
opcional
Nome completo da mãe. 1 a 500 caracteres. Sinal relevante para validação em bureaus.

father_name
string
opcional
Nome completo do pai. 1 a 500 caracteres.

### Perfil financeiro

monthly_income
integer
opcional
Renda mensal bruta em centavos . R$ 5.000,00 → 500000 .

declared_assets
integer
opcional
Patrimônio declarado em centavos .

occupation
string
opcional
Profissão. 1 a 100 caracteres.

is_us_person
boolean
opcional
Indica se a pessoa tem obrigações fiscais nos EUA (relevante para FATCA).

pleaded_pep
boolean
opcional
Indica se a pessoa se declarou politicamente exposta (PEP).

### Contato e localização

emails
array
opcional
Lista de objetos Email . Dentro de cada item, apenas email é obrigatório.

phones
array
opcional
Lista de objetos Phone . Se enviado, cada item exige international_dial_code , area_code e number .

address
object
opcional
Objeto Address . Se enviado, apenas postal_code é obrigatório dentro dele.

documents
object
opcional
Documentos de identificação (RG, CNH, passaporte e outros). As chaves de OCR entram aqui — veja Dados do SDK e Objetos compartilhados .

face
object
opcional
Dados de validação facial. A chave devolvida pelo SDK de biometria entra aqui — veja Dados do SDK .

source
object
opcional
Origem da requisição (canal, plataforma, IP, sessão). É aqui que entra o session_id do Device Scan — veja Dados do SDK .

### Classificação e extras

analysis_type
string
opcional
Tipo de análise a aplicar, quando sua conta tem mais de um fluxo configurado. Combine com o suporte antes de usar.

client_category
string
opcional
Categoria do cliente na sua plataforma ou programa de fidelidade. 1 a 100 caracteres.

partnership_key
string
opcional
Identificador da parceria associada ao cadastro. 1 a 500 caracteres.

related_account_type
string
opcional
Tipo de conta relacionada ao cadastro. 1 a 50 caracteres.

vehicle_plate
string
opcional
Placa de veículo associada ao cadastro. 1 a 50 caracteres.

custom_data
object
opcional
Campos personalizados da sua conta. Requer um schema previamente cadastrado pela QI Tech — veja o aviso abaixo.

```json title="Payload completo"
{
  "id": "12345678",
  "registration_id": "cad-98765",
  "registration_date": "2026-08-07T11:37:15-03:00",
  "analysis_type": "default",
  "client_category": "Premium User",
  "name": "John Sample",
  "document_number": "111.111.111-11",
  "birthdate": "1992-09-15",
  "gender": "male",
  "nationality": "BRA",
  "mother_name": "Maria Sample",
  "father_name": "John Sample",
  "monthly_income": 500000,
  "declared_assets": 7500000,
  "occupation": "Teacher",
  "is_us_person": false,
  "pleaded_pep": false,
  "emails": [
    {
      "email": "johnsample@test.com"
    }
  ],
  "documents": {
    "rg": {
      "number": "4.366.477-8",
      "issuer": "II",
      "issuer_state": "PR",
      "issuance_date": "2002-01-12"
    },
    "cnh": {
      "register_number": "05163811694",
      "issuer_state": "PR",
      "first_issuance_date": "2011-03-21",
      "issuance_date": "2016-06-29",
      "expiration_date": "2031-06-25",
      "category": "AB"
    }
  },
  "address": {
    "street": "Rua do Teste",
    "number": "111",
    "neighborhood": "Bairro do Exemplo",
    "city": "Aparecida de Goiânia",
    "uf": "GO",
    "complement": "Térreo",
    "postal_code": "00000-000",
    "country": "BRA"
  },
  "phones": [
    {
      "international_dial_code": "55",
      "area_code": "11",
      "number": "999999999",
      "type": "mobile"
    }
  ],
  "source": {
    "channel": "app",
    "platform": "android",
    "ip": "255.201.26.1",
    "session_id": "54b8e3cf-15de-41e5-9305-0ecf059d6e2a",
    "os_version": "14"
  },
  "face": {
    "type": "zaig_sdk",
    "registration_key": "46f38cf4-07b2-4de6-93e9-64b51a68378a"
  }
}
```

:::warning Campos não previstos são rejeitados
O schema usa `additionalProperties: false`. Qualquer campo fora dos listados acima faz a requisição retornar **HTTP 400**, mesmo que o resto do payload esteja correto.
:::

:::caution `custom_data` exige schema próprio
`custom_data` é validado contra um schema específico da sua empresa, registrado pela QI Tech. Se você enviar esse campo sem ter o schema cadastrado, a resposta é **HTTP 400** com a mensagem *"Custom data not available for you account"*. Fale com o [suporte](mailto:suporte.caas@qitech.com.br) antes de usar.
:::

---

## Formatos de campo

### Formato de `registration_date`

Formato ISO 8601 **com fuso horário obrigatório**. O validador aceita offsets terminados em `:00` ou `:30`, ou o sufixo `Z`:

```text
2026-08-07T11:37:15-03:00          ✅
2026-08-07T11:37:15.123456-03:00   ✅  fração de 1 a 6 dígitos
2026-08-07T14:37:15Z               ✅  UTC
2026-08-07T11:37:15                ❌  sem fuso horário
2026-08-07T11:37:15-03:15          ❌  offset não permitido
```

### `document_number` — CPF

Deve ir **com pontuação**: `XXX.XXX.XXX-XX`, exatamente 14 caracteres. Enviar apenas dígitos (`11111111111`) retorna HTTP 400.

### `postal_code` — CEP

Dentro de `address`, o CEP exige o formato `XXXXX-XXX` (com hífen). `00000000` é rejeitado.

### Valores monetários

`monthly_income` e `declared_assets` são inteiros em **centavos de reais**. Multiplique por 100: R$ 5.000,00 → `500000`.

---

## Enumeradores

### `gender`

| Valor | Significado |
| --- | --- |
| `male` | Masculino |
| `female` | Feminino |

### `phones[].type`

| Valor | Significado |
| --- | --- |
| `mobile` | Celular |
| `residential` | Residencial |
| `commercial` | Comercial |

| `visit` | Confirmado por visita presencial |
| `zaig_sdk` | Confirmado pelo SDK da QI Tech |
| `zaig_ocr` | Confirmado por OCR de comprovante |

### `face.type`

| Valor | Significado |
| --- | --- |
| `zaig_sdk` | Captura via SDK da QI Tech (use `registration_key`) |
| `base_64` | Imagem enviada diretamente no campo `image` |

Para `analysis_status`, `client_status` e `risk_level`, veja [Dinâmica dos status](/documentation/caas/onboarding/status_dynamics).

---

## Testando no Sandbox

No Sandbox a decisão é determinística, definida pelo **primeiro dígito do CPF**:

| Primeiro dígito | Resultado |
| --- | --- |
| `9` | `automatically_approved` |
| `8` | `automatically_reproved` |
| `7` | `pending` |
| `6` | Análise manual, com aprovação posterior |
| `5` | Análise manual, com reprovação posterior |
| `4` | `automatically_challenged` |
| `0` a `3` | `in_manual_analysis` |

:::danger Aviso importante
Não utilize dados reais de pessoas físicas no ambiente de Sandbox.
:::

---

## Erros

| Status | Situação | Como resolver |
| --- | --- | --- |
| 400 | Campo obrigatório ausente, formato inválido, enum fora da lista ou campo não previsto. | Veja a `description` da resposta, que aponta o campo. |
| 400 | `custom_data` sem schema cadastrado. | Solicite o cadastro do schema ao suporte. |
| 401 | Header `Authorization` ausente ou API Key desativada. | Verifique a chave. |
| 403 | API Key inválida. | Confirme a chave com o suporte. |
| 409 | `id` já utilizado. | Gere um `id` único por requisição. |
| 500 | Erro interno. | Nossos especialistas são notificados automaticamente. |

Lista completa em [Status HTTP](/documentation/caas/onboarding/http_status).

---

## Checklist de integração

- [ ] `POST /onboarding/natural_person` com o payload mínimo retornando `200` no Sandbox.
- [ ] `id` único por requisição (teste o `409` reenviando o mesmo `id`).
- [ ] `registration_id` estável para agrupar análises do mesmo cadastro.
- [ ] CPF com pontuação e CEP com hífen.
- [ ] Valores monetários em centavos.
- [ ] `in_queue` e `pending` tratados como "aguardando", não como recusa.
- [ ] [Webhook](/documentation/caas/onboarding/webhook) configurado para receber o resultado assíncrono.

---

# Objetos Compartilhados

URL: /documentation/caas/onboarding/objects

Boa parte dos dados são compartilhados entre várias APIs. Abaixo as definições destes objetos podem ser localizadas de maneira facilitada.

## Objeto *email*

Request Body

```json
{
  "email": "johnsample@test.com"
}
```

O objeto *email* é utilizado para representar os e-mails em toda a API bem como se foi utilizado algum meio de validação dos mesmos. Eles são representados da seguinte maneira:

nome | tipo | restrições | descrição
---- | :----: | :----: | ---------
email | string | 1–100 caracteres | Endereço de e-mail cadastrado. *(obrigatório)*

## Objeto *cnh*

Request Body

```json
{
  "register_number": "05163811694",
  "issuer_state": "PR",
  "first_issuance_date":"2011-03-21",
  "issuance_date":"2016-06-29",
  "expiration_date":"2021-06-25",
  "category": "AB",
  "ocr_key":"a5cf9c8f-2f66-4490-a7db-8a5bc70c1b76"
}
```

O objeto *cnh* é utilizado para representar as CNHs em toda a API bem como se foi utilizado algum meio de validação dos mesmos. Eles são representados da seguinte maneira:

nome | tipo | descrição
---- | :----: | ---------
register_number | string | Número do registro da CNH cadastrada.
issuer_state | enum | Enumerador do estado onde a CNH foi emitida
first_issuance_date | date | Data de primeira habilitação.
issuance_date | date | Data de emissão
expiration_date | date | Data de vencimento
category | enum | Categoria da CNH em letras maiúsculas
ocr_key | guid | Id retornado pela API de validação de documento da QI Tech.

## Objeto *rg*

Request Body

```json
{
  "number": "4.366.477-8",
  "issuer": "II",
  "issuer_state": "PR",
  "issuance_date":"2002-01-12",
  "ocr_front_key":"a5cf9c8f-2f66-4490-a7db-8a5bc70c1b76",
  "ocr_back_key":"a5cf9c8f-2f66-4490-a7db-8a5bc70c1b76"
}
```

O objeto *rg* é utilizado para representar os RGs em toda a API bem como se foi utilizado algum meio de validação dos mesmos. Eles são representados da seguinte maneira:

nome | tipo | descrição
---- | :----: | ---------
number | string | Número do documento cadastrado, incluindo formatação (Pontos, Hífens, Barras e outros).
issuer | string | Órgão emissor do documento (Sigla, e.g.: II, SESP...)
issuer_state | enum | UF emissor do documento.
issuance_date | date | Data de emissão do documento.
ocr_key | guid | Id retornado pela API de validação de documento da QI Tech.

## Objeto *ie*

Request Body

```json
{
  "number": "388.108.598.269",
  "issuer": "JUCESP",
  "issuer_state": "SP",
  "issuance_date":"2002-01-12",
  "ocr_key": "c64627db-1ba4-48b6-979d-06222a25d5e9"
}
```

O objeto *ie* é utilizado para representar as Inscrições Estaduais dentro do objeto de *documents* no endpoint de *legal_person*, bem como se foi utilizado algum meio de validação do mesmo. Ele é representado da seguinte maneira:

nome | tipo | descrição
---- | :----: | ---------
number | string | Número do documento cadastrado, incluindo formatação (Pontos, Hífens, Barras e outros).
issuer | string | Órgão emissor do documento (Sigla, e.g.: JUCESP, JUCEGO...)
issuer_state | enum | UF emissor do documento.
issuance_date | date | Data de emissão do documento.
ocr_key | guid | Id retornado pela API de validação de documento da QI Tech.

## Objeto *company_statute*

Request Body

```json
{
  "ocr_key": "60ed79c4-5aba-4cc7-aebb-5de5f92b7d0d"
}
```

O objeto *company_statute* é utilizado para representar documentos de constituição de empresas, como por exemplo um Contrato Social dentro do objeto de *documents* no endpoint de *legal_person*. Ele é representado da seguinte maneira:

nome | tipo | descrição
---- | :----: | ---------
ocr_key | guid | Id retornado pela API de OCR da QI Tech após envio da imagem ou PDF de um documento de constuição de uma empresa.

## Objeto *letter_attorney*

Request Body

```json
{
  "ocr_key": "13571175-b1d9-4507-82e0-d266516fc5ae"
}
```

O objeto *letter_attorney* é utilizado para representar procurações que instituem poderes a representantes legais dentro do objeto de *documents* no endpoint de *legal_person*. Ele é representado da seguinte maneira:

nome | tipo | descrição
---- | :----: | ---------
ocr_key | guid | Id retornado pela API de OCR da QI Tech após envio da imagem ou PDF de uma procuração.
## Objeto *address*

Request Body

```json
{
  "street": "Rua do Teste",
  "number": "111",
  "neighborhood": "Bairro do Exemplo",
  "city": "Aparecida de Goiânia",
  "uf": "GO",
  "complement": "Térreo",
  "postal_code": "00000-000",
  "country": "BRA",
  "ocr_key": "265b1b74-4b93-41dc-ac78-e1c37467225d"
}
```

O objeto *address* é utilizado para representar endereços em toda a API, endereços no território brasileiro são representados da seguinte maneira:

nome | tipo | restrições | descrição
---- | :----: | :----: | ---------
street | string | 1–100 caracteres | Rua do endereço, incluindo o logradouro, evitando, se possível, abreviações.
number | string | 1–50 caracteres | Número do imóvel, incluindo letras caso possua.
neighborhood | string | 1–100 caracteres | Bairro, sem abreviações. **e.g.: Santa Felicidade**
city | string | 1–100 caracteres | Nome completo da cidade, sem abreviações
uf | enum | sigla UF (2 letras) | A unidade federativa brasileira. Aceita as 27 UFs mais `EX` (exterior), em maiúsculas ou minúsculas. **e.g.: SP, GO, MG, EX**
complement | string | 1–500 caracteres | Quaisquer complementos para localizar o imóvel. **e.g.: Apartamento 101, Conjunto 12**
postal_code | string | Formato `XXXXX-XXX` | CEP brasileiro com hífen, exatamente 9 caracteres. Exemplo: `01310-100` *(obrigatório)*
country | string | 3 letras maiúsculas | Código ISO 3166-1 alfa-3 do país do endereço. Exemplo: `BRA`
ocr_key | guid | UUID (`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`) | Id retornado pela API ou SDK de OCR da QI Tech após o envio da imagem do comprovante de residência.

No caso dos endereços cujo país não seja Brasil (`BRA`), o `postal_code` e a unidade federativa poderão ser preenchidos livremente.

## Objeto *phone*

Request Body

```json
{
  "international_dial_code": "1",
  "area_code": "11",
  "number": "999999999",
  "type": "mobile"
}
```

Um objeto *phone* representa um número telefônico, dentro ou fora do Brasil e sua classificação. Para isso, os campos são:

nome | tipo | restrições | descrição
---- | :----: | :----: | ---------
international_dial_code | string | 1–7 caracteres, somente dígitos | Código de discagem internacional, sem zero ou `+`. Exemplo: `55` para Brasil *(obrigatório)*
area_code | string | 1–10 caracteres, somente dígitos | Código de área, sem zero. Exemplo: `11` *(obrigatório)*
number | string | 1–20 caracteres | Número do telefone, sem o hífen *(obrigatório)*
type | enum | `residential`, `commercial` ou `mobile` | Tipo de número telefônico.

## Objeto *source*

Request Body

```json
  {
    "channel": "app",
    "platform": "android",
    "ip":"211.7.142.62",
    "session_id": "733adf2c-a994-4113-aa59-beb646091fea"
  }
```

Um objeto *source* representa o conjunto de informações da plataforma utilizada pelo cliente para seu cadastramento. Para isso, os campos são:

nome | tipo | descrição
---- | :----: | ---------
channel | string | Canal de venda/cadastro do cliente
platform | string | Plataforma utilizada pelo cliente para realizar seu cadastro
ip | string | IP coletado do device que o cliente foi cadastrado
session_id | string | Identificador único da sessão, utilizado para fazer o cruzamento do device scan com o cadastro em questão

## Objeto *face*

Request Body

```json
  {
    "type":"zaig_face_sdk",
    "registration_key":"46f38cf4-07b2-4de6-93e9-64b51a68378a"
  }
```

Um objeto *face* representa uma validação de reconhecimento facial feita através das APIs ou SDKs da QI Tech por você para verificar a autenticidade do cliente prévio ao envio do cadastro. Para isso, os campos são:

nome | tipo | descrição
---- | :----: | ---------
registration_key | guid | Identificador que a API ou SDK da QI Tech retornou para identificar aquele registro.

## Objeto *partner*

Request Body

```json
  {
    "name": "John Partner",
    "document_number": "111.111.111-11",
    "birthdate": "1992-09-15",
    "gender": "male",
    "nationality": "BRA",
    "mother_name": "Maria Partner's Mother",
    "occupation": "Teacher",
    "emails":[
      {
        "email": "johnsample@test.com"
      }
    ],
    "documents": {
      "rg": {
        "number": "4.366.477-8",
        "issuer": "II",
        "issuer_state": "PR",
        "issuance_date":"2002-01-12",
        "ocr_front_key":"a5cf9c8f-2f66-4490-a7db-8a5bc70c1b76",
        "ocr_back_key":"a5cf9c8f-2f66-4490-a7db-8a5bc70c1b76"
      },
      "cnh": {
        "register_number": "05163811694",
        "issuer_state": "PR",
        "first_issuance_date":"2011-03-21",
        "issuance_date":"2016-06-29",
        "expiration_date":"2021-06-25",
        "category": "AB",
        "ocr_key":"a5cf9c8f-2f66-4490-a7db-8a5bc70c1b76"
      }
    },
    "address": {
      "street": "Rua do Teste",
      "number": "111",
      "neighborhood": "Bairro do Exemplo",
      "city": "Aparecida de Goiânia",
      "uf": "GO",
      "complement": "Térreo",
      "postal_code": "00000-000",
      "country": "BRA"
    },
    "phones": [
      {
        "international_dial_code": "1",
        "area_code": "11",
        "number": "999999999",
        "type": "mobile"
      }
    ],
    "source": {
      "channel": "app",
      "platform": "android",
      "ip":"255.321.321.1",
      "session_id": "54b8e3cf-15de-41e5-9305-0ecf059d6e2a"
    },
    "face":
    {
      "type":"zaig_sdk",
      "registration_key":"46f38cf4-07b2-4de6-93e9-64b51a68378a"
    }
  }
```

Um objeto *partner* representa os dados de um sócio da empresa que está sendo cadastrada, bem como informações referentes às validações que o sócio foi submetido durante seu processo de cadastro. Para isso, os campos são:

nome | tipo | descrição
:----: | :----: | ---------
name | string | Nome completo do sócio sendo cadastrado
document_number | string | CPF do sócio sendo cadastrado, com pontos e hífens, de acordo com a padronização *(obrigatório)*. Também é possível enviar um sócio pessoa jurídica informando um CNPJ — veja [Sócio pessoa jurídica](#sócio-pessoa-jurídica)
birthdate | date | Data de nascimento do sócio de acordo com a padronização
gender | enum | Gênero do sócio: 'male' ou 'female'
nationality | string | A nacionalidade do sócio, em ISO 3166-1 alfa-3
mother_name | string | Nome completo da mãe do sócio
occupation | string | Profissão do sócio sendo cadastrado
emails | Email | Lista de objetos do tipo Email que descreve o endereço de e-mail do sócio
documents | Document | Objeto do tipo Document de quaisquer documentos enviados no momento do cadastro do sócio
address | Address | Objeto do tipo Address que descreve o endereço da moradia do sócio
phones | Lista de Phone | Lista de objetos do tipo phone que possui a lista de telefones do sócio
source | Source | Objeto do tipo Source que descreve as características da aplicação utilizada para envio do cadastro
face | Face | Objeto do tipo Face que descreve as informações da validação facial 

### Sócio pessoa jurídica

O objeto *partner* também aceita um sócio que seja, ele próprio, uma pessoa jurídica. Para isso, basta enviar `document_number` no formato de CNPJ (com pontos, barra e hífen, de acordo com a padronização) ao invés de CPF — o cadastro identifica automaticamente o tipo do sócio pelo documento informado.

Quando o sócio é pessoa jurídica, os campos enviados mudam para os equivalentes de uma empresa:

Request Body

```json
  {
    "legal_name": "Holding Partner LTDA",
    "trading_name": "Holding Partner",
    "document_number": "11.111.111/1111-11",
    "foundation_date": "2005-03-10",
    "website": "https://holdingpartner.com",
    "activity": "Participações societárias",
    "activity_code": "64.62-0-00",
    "merchant_category_code": "6011",
    "emails":[
      {
        "email": "contato@holdingpartner.com"
      }
    ],
    "documents": {
      "ie": {
        "number": "123456789"
      },
      "company_statute": {
        "ocr_key": "a5cf9c8f-2f66-4490-a7db-8a5bc70c1b76"
      }
    },
    "address": {
      "street": "Rua do Teste",
      "number": "111",
      "neighborhood": "Bairro do Exemplo",
      "city": "Aparecida de Goiânia",
      "uf": "GO",
      "complement": "Térreo",
      "postal_code": "00000-000",
      "country": "BRA"
    },
    "phones": [
      {
        "international_dial_code": "1",
        "area_code": "11",
        "number": "999999999",
        "type": "mobile"
      }
    ],
    "source": {
      "channel": "app",
      "platform": "android",
      "ip":"255.321.321.1",
      "session_id": "54b8e3cf-15de-41e5-9305-0ecf059d6e2a"
    },
    "partners": [
      {
        "name": "John Partner",
        "document_number": "111.111.111-11"
      }
    ],
    "legal_representatives": [
      {
        "name": "Frederic Attorney",
        "document_number": "111.111.111-11"
      }
    ]
  }
```

nome | tipo | descrição
:----: | :----: | ---------
legal_name | string | Razão social do sócio pessoa jurídica sendo cadastrado
trading_name | string | Nome fantasia do sócio pessoa jurídica
document_number | string | CNPJ do sócio sendo cadastrado, com pontos, barra e hífen, de acordo com a padronização *(obrigatório)*
foundation_date | date | Data de fundação do sócio pessoa jurídica
website | string | Website do sócio pessoa jurídica
activity | string | Descrição da atividade exercida pelo sócio pessoa jurídica
activity_code | string | Código CNAE da atividade do sócio pessoa jurídica
merchant_category_code | string | Código MCC do sócio pessoa jurídica
emails | Email | Lista de objetos do tipo Email que descreve o endereço de e-mail do sócio pessoa jurídica
documents | Document | Objeto do tipo Document, incluindo `ie` (Inscrição Estadual) e `company_statute` (contrato social) do sócio pessoa jurídica
address | Address | Objeto do tipo Address que descreve o endereço do sócio pessoa jurídica
phones | Lista de Phone | Lista de objetos do tipo phone do sócio pessoa jurídica
source | Source | Objeto do tipo Source que descreve as características da aplicação utilizada para envio do cadastro
partners | Lista de Partner | Lista de objetos *partner* com os sócios do próprio sócio pessoa jurídica (estrutura societária em cascata)
legal_representatives | Lista de legal_representative | Lista de objetos *legal_representative* do sócio pessoa jurídica

> **Atenção — Beneficiário Final:** essa flexibilidade vale para o campo `partners`. Já o beneficiário final (final beneficiary), quando obtido automaticamente via bureau, é sempre tratado como pessoa física — ou seja, mesmo que o sócio direto seja uma pessoa jurídica, o beneficiário final identificado na cadeia societária é sempre pessoa física.

## Objeto *legal_representative*

Request Body

```json
  {
    "name": "Frederic Attorney",
    "document_number": "111.111.111-11",
    "birthdate": "1987-06-12",
    "gender": "male",
    "nationality": "BRA",
    "mother_name": "Jackie Attorney Mother",
    "occupation": "Accountant",
    "emails":[
      {
        "email": "frederic@attorney.com"
      }
    ],
    "documents": {
      "letter_of_attorney": {
        "ocr_key": "6972894d-d2ef-4b5f-b54f-10f178bf3e5d"
      },
      "cnh": {
        "register_number": "05163811694",
        "issuer_state": "PR",
        "first_issuance_date":"2011-03-21",
        "issuance_date":"2016-06-29",
        "expiration_date":"2021-06-25",
        "category": "AB",
        "ocr_key":"a5cf9c8f-2f66-4490-a7db-8a5bc70c1b76"
      }
    },
    "address": {
      "street": "Avenida de Exemplo",
      "number": "99",
      "neighborhood": "Vila do Exemplo",
      "city": "Jundiaí",
      "uf": "SP",
      "complement": "Ap 82",
      "postal_code": "00000-000",
      "country": "BRA",
      "ocr_key": "265b1b74-4b93-41dc-ac78-e1c37467225d"
    },
    "phones": [
      {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "999998877",
        "type": "mobile"
      }
    ],
    "source": {
      "channel": "app",
      "platform": "ios",
      "ip":"175.92.122.2",
      "session_id": "93c68588-7a41-472f-95b3-835ea6ee1ede"
    },
    "face":
    {
      "type":"zaig_sdk",
      "registration_key":"d2677a8c-d575-44e1-a54d-ec00f9310f34"
    }
  }
```

Um objeto *legal_representative* representa os dados de um representante legal da empresa que está sendo cadastrada, bem como informações referentes às validações que o representante legal foi submetido durante seu processo de cadastro. Para isso, os campos são:

nome | tipo | descrição
:----: | :----: | ---------
name | string | Nome completo do representante legal sendo cadastrado
document_number | string | CPF do representante legal sendo cadastrado, com pontos e hífens, de acordo com a padronização
birthdate | date | Data de nascimento do representante legal de acordo com a padronização
gender | enum | Gênero do representante legal: 'male' ou 'female'
nationality | string | A nacionalidade do representante legal, em ISO 3166-1 alfa-3
mother_name | string | Nome completo da mãe do representante legal
occupation | string | Profissão do representante legal sendo cadastrado
emails | Email | Lista de objetos do tipo Email que descreve o endereço de e-mail do representante legal
documents | Document | Objeto do tipo Document de quaisquer documentos enviados no momento do cadastro do representante legal
address | Address | Objeto do tipo Address que descreve o endereço da moradia do representante legal
phones | Lista de Phone | Lista de objetos do tipo phone que possui a lista de telefones do representante legal
source | Source | Objeto do tipo Source que descreve as características da aplicação utilizada para envio do cadastro
face | Face | Objeto do tipo Face que descreve as informações da validação facial 
## Objeto *final_beneficiary*

Request Body

```json
  {
    "id": "benef-001",
    "name": "Maria Sample",
    "document_number": "222.222.222-22",
    "declared_income": 1200000,
    "address": {
      "street": "Rua do Teste",
      "number": "111",
      "city": "São Paulo",
      "uf": "SP",
      "postal_code": "04570-140",
      "country": "BRA"
    }
  }
```

Um objeto *final_beneficiary* representa um beneficiário final da empresa que está sendo cadastrada. Todos os campos são opcionais. Para isso, os campos são:

nome | tipo | descrição
:----: | :----: | ---------
id | string | Identificador do beneficiário final no seu sistema
name | string | Nome completo do beneficiário final
document_number | string | CPF do beneficiário final, com pontos e hífen, de acordo com a padronização
declared_income | inteiro | Renda declarada do beneficiário final, em centavos
address | Address | Objeto do tipo Address que descreve o endereço do beneficiário final

---

# Recuperar um Cadastro

URL: /documentation/caas/onboarding/query_registration

## Buscar Cadastro específico

A fim de recuperar um Cadastro específico, basta realizar uma requisição GET. O resultado retornado é o json mais atualizado do Cadastro em questão. Caso este identificador não esteja relacionado a nenhum objeto, o HTTP Status 404 é retornado.

* **Natural Person:**

`GET https://api.caas.qitech.app/onboarding/natural_person/12345678`

* **Legal Person:**

`GET https://api.caas.qitech.app/onboarding/legal_person/12345678`

```shell
curl "https://api.caas.qitech.app/onboarding/natural_person/12345678"
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

> O comando acima retorna o JSON que representa um objeto de Natural Person.

```shell
curl "https://api.caas.qitech.app/onboarding/legal_person/12345678"
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

> O comando acima retorna o JSON que representa um objeto de Legal Person.

## Buscar PDF

A fim de recuperar um PDF de um cadastro, basta realizar uma requisição GET. O resultado retornado é o arquivo PDF resultante da análise. Caso seja desejado, basta adicionar uma query string denominada base64 com o valor true para que o arquivo PDF seja retornado em base64.

:::info **Atenção**

A geração de PDF pela plataforma é assíncrona e toma alguns segundos, caso o GET seja realizado antes da geração efetiva do PDF, um erro 404 será retornado com uma descrição que aponta esta situação. Basta retentar após alguns segundos e o PDF será retornado.
:::

* **Natural Person:**

`GET https://api.caas.qitech.app/onboarding/natural_person/12345678/pdf`

`GET https://api.caas.qitech.app/onboarding/natural_person/12345678/pdf?base64=true`

* **Legal Person:**

`GET https://api.caas.qitech.app/onboarding/legal_person/12345678/pdf`

`GET https://api.caas.qitech.app/onboarding/legal_person/12345678/pdf?base64=true`

```shell
curl "https://api.caas.qitech.app/onboarding/natural_person/12345678/pdf"
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

> O comando acima retorna o arquivo PDF gerado pela consulta.

```shell
curl "https://api.caas.qitech.app/onboarding/legal_person/12345678/pdf"
  -H "Authorization: EXAMPLE-OF-API-KEY"
```

> O comando acima retorna o arquivo PDF gerado pela consulta.

---

# Integrando os dados do SDK (face, documentos e device)

URL: /documentation/caas/onboarding/sdk_integration

Integrando os dados do SDK

Os SDKs da QI Tech (biometria facial, OCR de documentos e Device Scan) não enviam dados direto para a análise cadastral. Cada um devolve uma **chave** para o seu backend, e é você que anexa essas chaves ao payload de onboarding.

Esta página trata de onde cada chave entra — que é diferente entre Pessoa Física e Pessoa Jurídica.

| Bloco | O que carrega | Origem da chave |
| --- | --- | --- |
| `face` | Biometria facial | SDK de biometria |
| `documents` | OCR de documentos | SDK/API de OCR |
| `source` | Dados de dispositivo e sessão | SDK de Device Scan |

:::danger A diferença que mais causa retrabalho
Em **Pessoa Física**, os três blocos ficam na **raiz** do payload.

Em **Pessoa Jurídica**, `face` e `documents` de identidade ficam **dentro de `legal_representatives[]`** — mas o `source` continua na **raiz**. Detalhes em [Pessoa Jurídica](#pessoa-juridica-legal-person).
:::

---

## Onde cada bloco entra

| Bloco | Pessoa Física | Pessoa Jurídica |
| --- | --- | --- |
| `source` (`session_id`) | Raiz | **Raiz** — obrigatório para aparecer na dashboard |
| `face` | Raiz | Dentro de `legal_representatives[]` |
| `documents` (RG, CNH, passaporte) | Raiz | Dentro de `legal_representatives[]` |
| `documents` (`ie`, `company_statute`, `proof_of_address`) | — | Raiz |

---

## `source` — Device Scan e `session_id`

O `session_id` é a chave devolvida pelo SDK de Device Scan. É ele que conecta a análise cadastral aos dados de dispositivo, geolocalização e comportamento coletados no app ou no site.

session_id
string
opcional — mas veja o aviso
Identificador da sessão gerado pelo SDK de Device Scan. 1 a 500 caracteres.

channel
string
opcional
Canal de origem do cadastro. Ex.: app , web , backoffice . 1 a 100 caracteres.

platform
string
opcional
Plataforma. Ex.: android , ios , web . 1 a 100 caracteres.

ip
string
opcional
IP de origem. Aceita IPv4 e IPv6 . Um valor mal formatado retorna HTTP 400.

os_version
string
opcional
Versão do sistema operacional. 1 a 100 caracteres.

gps_data
object
opcional
Coordenadas da captura.

**Campos de `gps_data`:**

lat
number
opcional
Latitude, entre -90 e 90 .

lon
number
opcional
Longitude, entre -180 e 180 .

```json title="source — sempre na raiz, PF e PJ"
{
  "source": {
    "channel": "app",
    "platform": "android",
    "ip": "255.201.26.1",
    "session_id": "54b8e3cf-15de-41e5-9305-0ecf059d6e2a",
    "os_version": "14",
    "gps_data": {
      "lat": -23.5613,
      "lon": -46.6565
    }
  }
}
```

:::danger Pessoa Jurídica: `session_id` precisa estar na raiz
Em **Legal Person**, o `source.session_id` deve estar no **objeto `source` da raiz** do payload — não dentro de `legal_representatives[]`.

**Se esse campo não estiver preenchido na raiz, os dados de device não aparecem na dashboard de análise cadastral de PJ.** O schema aceita `source` dentro de `legal_representatives[]`, mas não é de lá que a dashboard de PJ lê a sessão — colocar apenas ali faz o dado ser silenciosamente ignorado na análise.
:::

---

## `face` — biometria facial

type
enum
opcional
Como a biometria foi capturada. Define qual dos campos abaixo você deve preencher.

registration_key
string
opcional
Chave devolvida pelo SDK de biometria. Use com type: "zaig_sdk" . Formato UUID.

image
string
opcional
Imagem em Base64. Use com type: "base_64" quando não houver SDK envolvido.

### Valores de `type`

| Valor | Campo a preencher |
| --- | --- |
| `zaig_sdk` | `registration_key` |
| `base_64` | `image` |

```json title="face via SDK"
{
  "face": {
    "type": "zaig_sdk",
    "registration_key": "46f38cf4-07b2-4de6-93e9-64b51a68378a"
  }
}
```

```json title="face via Base64"
{
  "face": {
    "type": "base_64",
    "image": "iVBORw0KGgoAAAANSUhEUg..."
  }
}
```

---

## `documents` — OCR

As chaves de OCR (`ocr_key`, `ocr_front_key`, `ocr_back_key`) vêm do SDK/API de OCR e entram dentro do documento correspondente.

### Documentos aceitos em Pessoa Física

Na raiz do payload de Natural Person, `documents` aceita:

| Campo | O que é | Chaves aceitas |
| --- | --- | --- |
| `rg` | Registro Geral | `ocr_front_key`, `ocr_back_key`, `ocr_key` |
| `cnh` | Carteira Nacional de Habilitação | `ocr_key`, `ocr_front_key`, `ocr_back_key` |
| `passport` | Passaporte | `ocr_key` *(obrigatório)* |
| `ctps` | Carteira de Trabalho | `ocr_front_key` e `ocr_back_key` *(ambos obrigatórios)* |
| `cin_digital` | Carteira de Identidade Nacional digital | `ocr_key` |
| `national_registry_of_foreigners` | RNE — Registro Nacional de Estrangeiros | `ocr_key`, `ocr_front_key`, `ocr_back_key` |
| `national_migration_registry` | RNM — Registro Nacional Migratório | `ocr_key`, `ocr_front_key`, `ocr_back_key` |
| `class_entity_registry` | Carteira de entidade de classe (OAB, CRM…) | `ocr_key` *(obrigatório)* |
| `military_registry` | Documento militar | `ocr_key` *(obrigatório)* |
| `letter_of_emancipation` | Carta de emancipação | `ocr_key` *(obrigatório)* |
| `company_statute` | Contrato social / estatuto | `ocr_key`, `document_analysis_id` |
| `proof_of_address` | Comprovante de endereço | `document_analysis_id` |
| `others` | Outros documentos | `ocr_front_key` e `ocr_back_key` *(ambos obrigatórios)* |

### Documentos aceitos em Pessoa Jurídica

Na **raiz** do payload de Legal Person, `documents` aceita **apenas** documentos da empresa:

| Campo | O que é | Chaves aceitas |
| --- | --- | --- |
| `ie` | Inscrição estadual | `ocr_key` — exige o campo `number` |
| `company_statute` | Contrato social / estatuto | `ocr_key`, `document_analysis_id` |
| `proof_of_address` | Comprovante de endereço | `document_analysis_id` |

:::danger RG e CNH não existem na raiz de Legal Person
Documentos de identidade (`rg`, `cnh`, `passport`…) **não são aceitos** na raiz do payload de PJ — o schema usa `additionalProperties: false` e a requisição retorna **HTTP 400**.

Eles pertencem ao representante legal, dentro de `legal_representatives[]`.
:::

### Chaves de OCR por documento

As chaves aceitas por documento estão nas tabelas acima. Vale destacar:

- **Frente e verso:** em documentos com dois lados (`rg`, `ctps`, `others`), o padrão é enviar `ocr_front_key` e `ocr_back_key`. Em `ctps` e `others` os dois são **obrigatórios**.
- **Chave única:** quando o OCR devolve uma única chave para o documento inteiro, use `ocr_key`.
- **`document_analysis_id`:** usado em `company_statute` e `proof_of_address`, que passam pela [Análise de Documentos](/documentation/caas/document_analysis/introduction) e não por OCR de identidade.

Em `rg` e `cnh`, o campo `issuer_state` aceita as siglas de UF em maiúsculas ou minúsculas.

```json title="documents com chaves de OCR (PF)"
{
  "documents": {
    "rg": {
      "number": "4.366.477-8",
      "issuer": "SSP",
      "issuer_state": "PR",
      "issuance_date": "2002-01-12",
      "ocr_front_key": "a5cf9c8f-2f66-4490-a7db-8a5bc70c1b76",
      "ocr_back_key": "b6df0d9e-3f77-45a1-b8ec-9b6cd81d2c87"
    },
    "cnh": {
      "register_number": "05163811694",
      "issuer_state": "PR",
      "first_issuance_date": "2011-03-21",
      "issuance_date": "2016-06-29",
      "expiration_date": "2031-06-25",
      "category": "AB",
      "ocr_key": "c7ef1eaf-4088-46b2-c9fd-ac7de92e3d98"
    }
  }
}
```

---

## Pessoa Física (Natural Person)

Os três blocos ficam na raiz:

```json title="POST /onboarding/natural_person"
{
  "id": "12345678",
  "registration_date": "2026-08-07T11:37:15-03:00",
  "document_number": "111.111.111-11",
  "name": "John Sample",

  "source": {
    "channel": "app",
    "platform": "android",
    "ip": "255.201.26.1",
    "session_id": "54b8e3cf-15de-41e5-9305-0ecf059d6e2a"
  },

  "face": {
    "type": "zaig_sdk",
    "registration_key": "46f38cf4-07b2-4de6-93e9-64b51a68378a"
  },

  "documents": {
    "cnh": {
      "register_number": "05163811694",
      "issuer_state": "PR",
      "ocr_key": "c7ef1eaf-4088-46b2-c9fd-ac7de92e3d98"
    }
  }
}
```

---

## Pessoa Jurídica (Legal Person)

`source` na raiz; `face` e documentos de identidade dentro de `legal_representatives[]`:

```json title="POST /onboarding/legal_person"
{
  "id": "87654321",
  "registration_date": "2026-08-07T11:37:15-03:00",
  "document_number": "11.111.111/1111-11",
  "legal_name": "Empresa Exemplo LTDA",

  "source": {
    "channel": "web",
    "platform": "web",
    "ip": "255.201.26.1",
    "session_id": "54b8e3cf-15de-41e5-9305-0ecf059d6e2a"
  },

  "documents": {
    "company_statute": {
      "ocr_key": "d8fa2fb0-5199-47c3-daae-bd8ef03f4ea9"
    },
    "proof_of_address": {
      "document_analysis_id": "e9ab3ac1-62aa-48d4-ebbf-ce9fa14a5fb0"
    }
  },

  "legal_representatives": [
    {
      "id": "rep-001",
      "name": "Maria Sample",
      "document_number": "222.222.222-22",
      "birthdate": "1985-03-22",

      "face": {
        "type": "zaig_sdk",
        "registration_key": "46f38cf4-07b2-4de6-93e9-64b51a68378a"
      },

      "documents": {
        "cnh": {
          "register_number": "05163811694",
          "issuer_state": "SP",
          "ocr_key": "c7ef1eaf-4088-46b2-c9fd-ac7de92e3d98"
        }
      }
    }
  ]
}
```

:::tip Por que a biometria fica no representante
A biometria e o documento de identidade pertencem a uma **pessoa**, não à empresa. Em PJ, quem passa pela validação biométrica é o representante legal — por isso `face` e `documents` de identidade vivem dentro de `legal_representatives[]`.

Já os dados de device pertencem à **sessão** em que o cadastro foi feito, que é única para toda a requisição — por isso `source` fica na raiz.
:::

---

## Erros comuns

| Sintoma | Causa | Correção |
| --- | --- | --- |
| Dados de device não aparecem na dashboard de PJ | `session_id` ausente na raiz, ou enviado apenas dentro de `legal_representatives[]` | Preencha `source.session_id` na **raiz** do payload |
| HTTP 400 ao enviar `rg`/`cnh` em PJ | Documento de identidade na raiz do Legal Person | Mova para `legal_representatives[].documents` |
| HTTP 400 no `passport` | Objeto enviado sem `ocr_key` | `ocr_key` é obrigatório em `passport` |
| HTTP 400 em `source.ip` | IP mal formatado | Envie IPv4 ou IPv6 válido |
| HTTP 400 sem campo aparente | Campo fora do schema (`additionalProperties: false`) | Confira a `description` da resposta |

---

## Checklist

- [ ] `source.session_id` na **raiz**, tanto em PF quanto em PJ.
- [ ] Em PJ, confirmado que os dados de device aparecem na dashboard de análise cadastral.
- [ ] Em PJ, `face` e documentos de identidade dentro de `legal_representatives[]`.
- [ ] Em PJ, apenas `ie`, `company_statute` e `proof_of_address` na raiz de `documents`.
- [ ] `passport`, quando enviado, com `ocr_key`.

---

# Padrões

URL: /documentation/caas/onboarding/standards

Para facilitar a integração e garantir a integridade da informação, foram definidos alguns padrões que são seguidos em toda a API.

## Valores Monetários
> Exemplos:

```
10000
12345
98741
1223
1
0
```

As APIs assumem que todos os valores monetários enviados são em Reais Brasileiros. Os valores devem ser enviados como inteiro em centavos.

## Data e Hora com Fuso Horário
> Alguns exemplos:

```
2019-10-15T22:35:12.232-03:00
2018-05-01T13:32:11.297+00:00
2019-05-01T00:00:00.000+00:00
```

É representada conforme a ISO 8601. Neste caso, o fuso-horário é colocado logo após o horário e deve representar o fuso do local onde aquele dado será valido.

A máscara utilizada para validação é a seguinte:

`YYYY-MM-ddThh:mm:ss.sss±hh:mm`

## Data e Hora sem Fuso Horario
> Alguns exemplos:

```
2019-10-15T22:35:12
2018-05-01T13:32:11
2019-05-01T00:00:00
```

É representada conforme a ISO 8601. Dados que independem de fuso-horário deverão ser enviados sem ele, sempre em UTC, com a letra Z indicando que este dado está em UTC. O seguinte formato, portanto, será validado:

`YYYY-MM-ddThh:mm:ss.sssZ`

## Data
> Alguns exemplos

``` 
2019-10-15
2019-01-01
2017-03-20
```

No caso de campos que recebem somente data, uma data de nascimento, por exemplo, somente a data, sem nenhum horário deve ser enviada com o seguinte formato:

`YYYY-MM-dd`
 

## Documentos
Uma vez que os números de documento são bastante variados e muitos deles possuem caracteres que não se enquadram como numéricos, definem-se todos os números de documento como string. Outro bom motivo para definí-los como string é evitar que os zeros à esquerda desapareçam. Documentos previstos nesta página possuem uma máscara bem definida e estarão sujeitos a validação. O restante dos documentos, como RG, dada sua falta de padronização, não serão validados.

## CPF

> Exemplos de CPFs válidos contra a máscara definida:

```
123.456.789-12
321.987.543-23
111.283.333-00
```

> Exemplos de CPFs inválidos contra a máscara definida:

```
8.577.477-8
08.104.627/0001-23
123.456.789-1
23.456.789-01
```

O CPF é sempre definido como uma string e será validado contra a máscara:

`###.###.###-##`

## CNPJ

> Exemplos de CNPJs válidos contra a máscara definida:

```
08.104.627/0001-02
01.079.210/0114-67
32.402.502/0001-35
```

> Exemplos de CNPJs inválidos contra a máscara definida:

```
8.577.477-8
123.456.789-12
321.987.543-23
32.402.502/0001-3
032.402.502/0001-3
```

O CNPJ é sempre definido como uma string e será validado contra a máscara:

`##.###.###/####-##`

## IP

> Exemplos de IPs válidos contra a máscara definida:

```
201.81.161.86
201.081.161.86
201.81.161.086
201.81.0.1
```

> Exemplos de IPs inválidos:

```
201.81..86
358.81.161.86
201.81.161
```

IPs deverão ser enviados sempre em IPv4, zeros à esquerda poderão ou não ser enviados, respeitando a seguinte máscara:

`###.###.###.###`

---

# Dinâmica dos status

URL: /documentation/caas/onboarding/status_dynamics

Dinâmica dos status

A API de Análise cadastral trabalha com **três** enumeradores de status independentes. Entender a diferença entre eles é o passo que mais evita erro de integração:

| Enumerador | Quem define o valor | Quem devolve | O que representa |
| --- | --- | --- | --- |
| `analysis_status` | **Você**, na sua política | **QI Tech** | O resultado da execução da sua árvore de decisão. |
| `risk_level` | **Você**, na sua política | **QI Tech** | O nível de risco atribuído pela sua árvore de decisão. |
| `client_status` | **Você** | — | A situação do cliente na sua plataforma. |

:::info `analysis_status` e `risk_level` saem da sua própria política
Esses dois campos **não** são um veredito nosso sobre o cadastro. Eles são definidos por você, no motor de regras, através das **caixinhas de decisão** e de **nível de risco** que você posiciona ao longo da sua árvore.

A cada requisição, a QI Tech executa essa árvore contra os dados analisados e devolve o resultado que a **sua** política determinou. Se você quer que um cenário passe a cair em `in_manual_analysis` em vez de `automatically_reproved`, ou que um perfil receba `risk_level: high` em vez de `medium`, a mudança é no motor de regras — não há nada a alterar na integração.
:::

:::tip A regra prática
`analysis_status` é o **resultado da sua política**, executada por nós. `client_status` é a **sua decisão de negócio**, que você registra via [PUT](/documentation/caas/onboarding/update_registration) conforme a jornada do cliente evolui.
:::

### Como a decisão é produzida

1. Você desenha a árvore de decisão no motor de regras, posicionando as caixinhas de **decisão** (`analysis_status`) e de **nível de risco** (`risk_level`) conforme a sua política.
2. Você envia o cadastro para a API.
3. A QI Tech executa a árvore contra os dados do cadastro e os enriquecimentos disponíveis.
4. A resposta traz o `analysis_status` e o `risk_level` que a sua árvore determinou para aquele caso.

Por isso, dois clientes que enviam exatamente o mesmo cadastro podem receber respostas diferentes: cada um tem a sua própria política configurada.

---

## `analysis_status`

Resultado da execução da sua árvore de decisão. Os status abaixo se dividem em três grupos pelo que você deve fazer com cada um.

### Decisões finais

| Status | Significado | Ação |
| --- | --- | --- |
| `automatically_approved` | A sua árvore de decisão terminou em uma caixinha de aprovação automática. | Pode aprovar o cadastro. |
| `automatically_reproved` | A sua árvore de decisão terminou em uma caixinha de reprovação automática. | Recuse o cadastro. |
| `manually_approved` | Aprovado por um analista. | Pode aprovar o cadastro. |
| `manually_reproved` | Reprovado por um analista. | Recuse o cadastro. |
| `approved_by_time` | Aprovado automaticamente após expirar o prazo de análise. | Pode aprovar o cadastro. |
| `reproved_by_time` | Reprovado automaticamente após expirar o prazo de análise. | Recuse o cadastro. |

### Aguardando — o resultado chega por webhook

| Status | Significado | Ação |
| --- | --- | --- |
| `in_queue` | Análise assíncrona em fila. | Aguarde o [Webhook](/documentation/caas/onboarding/webhook). |
| `pending` | As consultas estão demorando mais que o esperado. | Aguarde o Webhook. |
| `in_manual_analysis` | Derivado para análise manual por um analista. | Aguarde o Webhook. |
| `waiting_for_data` | Aguardando dados complementares para processar. | Aguarde o Webhook. |
| `on_hold` | Análise pausada, aguardando retorno do cliente. | Aguarde o Webhook. |

:::danger Não trate "aguardando" como recusa
`in_queue`, `pending`, `in_manual_analysis`, `waiting_for_data` e `on_hold` **não são negativas**. Tratá-los como reprovação é o erro de integração mais comum nesta API — recusa cadastros legítimos que seriam aprovados minutos depois.
:::

### Contestação e casos especiais

| Status | Significado | Ação |
| --- | --- | --- |
| `automatically_challenged` | A sua árvore terminou em uma caixinha de contestação. | O cadastro precisa passar pelo fluxo de contestação. |
| `manually_challenged` | Contestado por um analista. | Idem. |
| `manually_cancelled` | Análise cancelada. | Nenhuma decisão será emitida. |
| `failed` | A análise falhou durante o processamento. | Reenvie com um novo `id` ou acione o suporte. |
| `not_analysed` | Enviado com `analyze=false`. | Nenhuma recomendação será emitida; siga sua própria decisão. |

---

## `client_status`

Situação cadastral do cliente na **sua** plataforma. Você é responsável por manter esse status atualizado via [PUT](/documentation/caas/onboarding/update_registration) — ele alimenta os modelos e melhora análises futuras.

| Status | Significado |
| --- | --- |
| `registered` | Registrado, sem decisão de aprovação ainda. |
| `approved` | Aprovado na sua plataforma. |
| `reproved` | Reprovado na sua plataforma. |
| `fraud_blocked` | Bloqueado por suspeita ou confirmação de fraude. |
| `default_blocked` | Bloqueado por inadimplência. |
| `cancelled` | O cliente cancelou o uso do serviço. |

:::info Grafia do enumerador
O valor correto é `cancelled`, com dois L. Versões antigas desta documentação grafavam `canceled` — esse valor é rejeitado com HTTP 400.
:::

### Quais valores podem ser enviados

O método usado determina os valores aceitos:

| Tipo de cadastro | Valores aceitos no `PUT` |
| --- | --- |
| Natural Person | `approved`, `reproved`, `fraud_blocked`, `default_blocked`, `cancelled` |
| Legal Person | `fraud_blocked`, `default_blocked`, `cancelled` |

:::caution Legal Person aceita menos valores
Em **Legal Person**, o `PUT` **não** aceita `approved` nem `reproved` — apenas os três valores de bloqueio e cancelamento. Enviar `approved` em um cadastro PJ retorna **HTTP 400**.
:::

Detalhes em [Atualizar um cadastro](/documentation/caas/onboarding/update_registration).

---

## `risk_level`

Nível de risco atribuído ao cadastro pela caixinha de nível de risco que a sua árvore percorreu. Presente na resposta do `GET` e nos eventos de análise.

| Valor | Significado |
| --- | --- |
| `low` | Risco baixo. |
| `medium` | Risco médio. |
| `high` | Risco alto. |
| `critical` | Risco crítico. |
| `undefined` | Nenhuma avaliação de risco foi realizada. |

---

## Fluxo típico

1. Você envia o cadastro — `POST /onboarding/natural_person`.
2. A resposta traz um `analysis_status`.
   - Se for uma **decisão final**, siga o que a sua política determinou.
   - Se for **aguardando**, espere o webhook.
3. Ao decidir na sua plataforma, envie o `client_status` via `PUT`.

---

# Atualizar um cadastro

URL: /documentation/caas/onboarding/update_registration

Atualizar um cadastro

Use o método `PUT` para atualizar o **status** de um cadastro — tanto o `client_status` (situação na sua plataforma) quanto o `analysis_status` (decisão manual de análise).

:::tip Retroalimentação importa
Informar o desfecho real via `PUT` é o que mantém a qualidade das recomendações. Sem esse retorno, os modelos não aprendem com os casos da sua carteira.
:::

O endpoint aceita os dois tipos de cadastro:

```text
/onboarding/natural_person/{external_id}
/onboarding/legal_person/{external_id}
```

O `{external_id}` é o `id` que você enviou no `POST`.

---

## PUT — atualizar status

ENDPOINT /onboarding/natural_person/ EXTERNAL_ID
MÉTODO PUT

O corpo aceita **duas formas mutuamente exclusivas**: uma para `client_status`, outra para `analysis_status`.

**client_status**

Atualiza a situação do cliente na sua plataforma.

client_status
enum
obrigatório
Em Natural Person aceita approved , reproved , fraud_blocked , default_blocked ou cancelled . Em Legal Person , apenas fraud_blocked , default_blocked ou cancelled .

event_date
datetime
obrigatório
Data e hora do evento, com fuso horário. Offset terminado em :00 / :30 ou sufixo Z .

```json title="Bloqueio por fraude"
{
  "client_status": "fraud_blocked",
  "event_date": "2026-08-07T13:34:12-03:00"
}
```

```json title="Bloqueio por inadimplência"
{
  "client_status": "default_blocked",
  "event_date": "2026-08-07T13:34:12-03:00"
}
```

```json title="Cancelamento pelo cliente"
{
  "client_status": "cancelled",
  "event_date": "2026-08-07T13:34:12-03:00"
}
```

**analysis_status**

Registra uma decisão manual de análise.

analysis_status
enum
obrigatório
Aceita manually_approved , manually_reproved , manually_challenged , manually_cancelled ou on_hold .

risk_level
enum
opcional
low , medium , high ou critical .

observation
string
opcional
Justificativa da decisão. Até 3.000 caracteres.

user_name
string
opcional
Nome do analista responsável. Até 50 caracteres.

user_email
string
opcional
E-mail do analista responsável.

```json title="Aprovação manual"
{
  "analysis_status": "manually_approved",
  "risk_level": "low",
  "observation": "Documentação conferida e validada.",
  "user_name": "Ana Analista",
  "user_email": "ana@exemplo.com.br"
}
```

### Exemplos de requisição

**Python**

```python
import requests

BASE_URL = "https://api.sandbox.caas.qitech.app"
API_KEY = "YOUR_API_KEY"
EXTERNAL_ID = "12345678"

response = requests.put(
    f"{BASE_URL}/onboarding/natural_person/{EXTERNAL_ID}",
    json={
        "client_status": "approved",
        "event_date": "2026-08-07T13:34:12-03:00",
    },
    headers={"Authorization": API_KEY},
    timeout=30,
)

response.raise_for_status()
```

**PHP**

```php
<?php

$baseUrl    = 'https://api.sandbox.caas.qitech.app';
$apiKey     = 'YOUR_API_KEY';
$externalId = '12345678';

$payload = [
    'client_status' => 'approved',
    'event_date'    => '2026-08-07T13:34:12-03:00',
];

$ch = curl_init("{$baseUrl}/onboarding/natural_person/{$externalId}");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => 'PUT',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'Authorization: ' . $apiKey,
    ],
    CURLOPT_POSTFIELDS => json_encode($payload),
]);

$body   = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status !== 200) {
    throw new RuntimeException("Falha ao atualizar: HTTP {$status} — {$body}");
}
```

**Node.js**

```javascript
const BASE_URL = "https://api.sandbox.caas.qitech.app";
const API_KEY = "YOUR_API_KEY";
const EXTERNAL_ID = "12345678";

async function updateStatus() {
  const response = await fetch(
    `${BASE_URL}/onboarding/natural_person/${EXTERNAL_ID}`,
    {
      method: "PUT",
      headers: {
        "Content-Type": "application/json",
        Authorization: API_KEY,
      },
      body: JSON.stringify({
        client_status: "approved",
        event_date: "2026-08-07T13:34:12-03:00",
      }),
    },
  );

  if (!response.ok) {
    throw new Error(`Falha ao atualizar: HTTP ${response.status}`);
  }
}

updateStatus();
```

**Java**

```java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class UpdateClientStatus {

    private static final String BASE_URL = "https://api.sandbox.caas.qitech.app";
    private static final String API_KEY = "YOUR_API_KEY";
    private static final String EXTERNAL_ID = "12345678";

    public static void main(String[] args) throws Exception {
        String payload = """
            {
              "client_status": "approved",
              "event_date": "2026-08-07T13:34:12-03:00"
            }
            """;

        HttpClient client = HttpClient.newHttpClient();

        HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(BASE_URL + "/onboarding/natural_person/" + EXTERNAL_ID))
                .header("Content-Type", "application/json")
                .header("Authorization", API_KEY)
                .timeout(Duration.ofSeconds(30))
                .PUT(HttpRequest.BodyPublishers.ofString(payload))
                .build();

        HttpResponse<String> response =
                client.send(request, HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() != 200) {
            throw new IllegalStateException(
                    "Falha ao atualizar: HTTP " + response.statusCode());
        }
    }
}
```

**C#**

```csharp
using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

public class UpdateClientStatus
{
    private const string BaseUrl = "https://api.sandbox.caas.qitech.app";
    private const string ApiKey = "YOUR_API_KEY";
    private const string ExternalId = "12345678";

    public static async Task Main()
    {
        var payload = new
        {
            client_status = "approved",
            event_date = "2026-08-07T13:34:12-03:00"
        };

        using var client = new HttpClient { Timeout = TimeSpan.FromSeconds(30) };
        client.DefaultRequestHeaders.Add("Authorization", ApiKey);

        var content = new StringContent(
            JsonSerializer.Serialize(payload), Encoding.UTF8, "application/json");

        var response = await client.PutAsync(
            $"{BaseUrl}/onboarding/natural_person/{ExternalId}", content);

        if (!response.IsSuccessStatusCode)
        {
            throw new InvalidOperationException(
                $"Falha ao atualizar: HTTP {(int)response.StatusCode}");
        }
    }
}
```

**curl**

```bash
curl -X PUT \
  'https://api.sandbox.caas.qitech.app/onboarding/natural_person/12345678' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: YOUR_API_KEY' \
  -d '{
    "client_status": "approved",
    "event_date": "2026-08-07T13:34:12-03:00"
  }'
```

## Erros

| Status | Situação | Como resolver |
| --- | --- | --- |
| 400 | Enum fora da lista aceita. | Confira os valores aceitos para `client_status` e `analysis_status`. |
| 400 | `client_status` sem `event_date`. | Envie os dois juntos. |
| 400 | Campo não previsto no schema. | O schema usa `additionalProperties: false`. |
| 404 | Cadastro não encontrado para a sua API Key. | Verifique o `external_id` do path. |

Lista completa em [Status HTTP](/documentation/caas/onboarding/http_status).

---

# Webhook

URL: /documentation/caas/onboarding/webhook

Webhook

Atualizações no status de fraude (Para cadastros que sejam derivados para análise manual ou que sejam respondidos como Pendente), são notificados por meio de Webhook. Para tanto, é necessário, por meio da equipe do [suporte](mailto:suporte.caas@qitech.com.br), configurar um endereço do endpoint por onde vamos notificar as atualizações e também um *secret_token* que será utilizado para assinar a requisição.

O cliente pode, apesar de não recomendável, também utilizar a técnica de [polling](https://en.wikipedia.org/wiki/Polling_(computer_science)). Neste caso, basta não configurar o endpoint de webhook e utilizar os endpoints de recuperação de cadastro para proceder com o polling.

## Assinatura do Webhook

## Requisição

```bash
curl --location 'YOUR-ENDPOINT-HERE' \
--header 'Signature: CALCULATED-HASH-HMAC' \
--data '{"natural_person_id": "538509",  "analysis_status": "manually_approved", "event_date": "2024-11-13T17:52:50Z", "reason": "manually_approved"}'
```

A requisição possui o formato acima e notifica a mudança no status de fraude. É importante ressaltar que a requisição utiliza o verbo HTTP POST e o corpo da requisição é enviado como texto codificado em UTF-8.

## Retentativas

A notificação é considerada realizada quando recebe como resposta um HTTP Status 200. Caso as notificações falhem, serão feitas 5 retentativas, com os seguintes intervalos, até que um 200 seja retornado ou as tentativas terminem:

* 30 segundos
* 60 segundos
* 120 segundos
* 240 segundos
* 360 segundos

---

# Requisição de Autorização (Opcional)

URL: /documentation/cards/autorizacao/

---

Uma vez que o programa está configurado, o portador do cartão foi adicionado e tem um cartão ativo, este cartão pode ser usado para fazer compras em vários pontos de venda ao redor do mundo. Sempre que uma transação for iniciada em algum ponto de captura, uma `Authorization` será criada para autorizar este movimento. Será feita uma Requisição de Autorização `Authorization Request` ao sistema do cliente para que este decida pela aprovação ou não desta autorização com base nas informações contidas neste pedido.

A entidade `Authorization` contém a situação atual dos valores autorizados e capturados e pode assumir os seguintes valores de estado:

| Estado | Descrição |
|---|---|
| pending | Requisição de autorização foi aprovada e nenhum evento de captura ou cancelamento foi processado |
| unauthorized | Requisição de autorização não foi aprovada |
| completed | Pelo menos um valor capturado com sucesso para a autorização em questão (seja um valor igual, a menor ou a maior que o valor total aprovado nas requisições de autorização) |
| reversed | Autorização foi estornada por completo ou expirou sem captura |

Detalhamento dos campos de uma Autorização pode ser encontrado em [Buscar Autorização](/documentation/cards/search/buscar_autorizacao/)

A Requisição de Autorização `Authorization Request` quando enviada para o cliente conterá os [Cabeçalhos de Autenticação](/documentation/primeiros_passos/teste_de_autenticacao/webhook_v2/index.html) e possuirá a seguinte composição:

### Requisição de Autorização

ENDPOINT (client_url)/authorization_request
METODO POST

Request Body

```json
{
	"authorization_key": "c91ce179-517c-48f9-9c28-18368457b67f",
	"authorization_request_key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"card": {
		"card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",
		"account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
		"type": "virtual",
		"card_name": "ecommerce sample",
		"printed_name": "Aurora Catarina",
		"status": "active",
		"brand": "visa",
		"bin": "123456",
		"last_four_digits": "5695"
	},
	"terminal_id": "123456",
	"terminal_country_code": "BRA",
	"terminal_type": "2",
	"terminal_pin_entry_capability": true,
	"terminal_magnetic_stripe_capability": true,
	"terminal_contactless_capability": false,
	"terminal_chip_capability": true,
	"merchant_acquirer_code": "250",
	"merchant_code": "123456",
	"merchant_name": "VASP LINHAS AEREAS",
	"merchant_street": "RUA CMDTE X, 127",
	"merchant_city": "SAO PAULO, SP",
	"merchant_region": "BRA",
	"merchant_postal_code": "04570-140",
	"merchant_mcc": "3036",
	"authorization_code": "473890",
	"nsu": "123456",
    "acquirer_reference_number": "12312423",
	"merchant_currency_code": "BRL",
	"merchant_amount": 10.59,
	"billing_currency_code": "BRL",
	"billing_amount": 10.59,
	"processing_datetime": "2023-01-10T13:45:52.000Z",
	"number_of_installments": 1,
	"authorization_type": "authorization",
	"pan_entry_mode": "chip",
	"pin_sent": true,
	"autorization": {Objeto Autorização}
}
```

#### Authorization Request

| Campo | Tipo | Descrição |
|---|---| ---|
| `authorization_request_key` | string  | Identificador único da Requisição de Autorização |
| `authorization_key` | string  | Identificador único da entidade Autorização relacionada com esta requisição |
| `card` | object |**[Objeto Card](#objeto-card)**  |
| `terminal_id` | string | O identificador do terminal enviado pela adquirente na mensageria de autenticação |
| `terminal_country_code` | string | O código do país do terminal, enviado na mensagem de autorização conforme ISO 3166-1 alpha-3 |
| `terminal_type` | string | O tipo de terminal conforme recebido na mensageria de autorização |
| `terminal_pin_entry_capability` | boolean | Existe a possibilidade de inserir a senha do cartão no terminal? |
| `terminal_magnetic_stripe_capability` | boolean | O terminal é capaz de ler tarja magnética? |
| `terminal_contactless_capability` | boolean | O terminal é capaz de iniciar transações contactless? |
| `terminal_chip_capability` | boolean | O terminal é capaz de iniciar transações utilizando o chip EMV? |
| `merchant_acquirer_code` | string | O identificador da adquirente conforme mensageria de autorização |
| `merchant_code` | string | O identificador do lojista na adquirente conforme mensageria de autorização |
| `merchant_name` | string | O nome do lojista de acordo com a mensageria de autorização |
| `merchant_street` | string | A rua do endereço do lojista |
| `merchant_city` | string | A cidade do endereço do lojista |
| `merchant_region` | string | A região do endereço do lojista |
| `merchant_postal_code` | string | O código postal (CEP) do endereço do lojista  |
| `merchant_mcc` | string | Merchant Category Code - identificação do tipo de estabelecimento - [Lista Atualizada pode ser encontrada aqui](https://usa.visa.com/content/dam/VCOM/download/merchants/visa-merchant-data-standards-manual.pdf) |
| `authorization_code` | string | Código de Autorização de 6 dígitos |
| `nsu` | string | Número sequencial único que define uma autorização |
| `acquirer_reference_number` | string | Identificador único da autorização na adquirente |
| `merchant_currency_code` | string | A moeda utilizada na transação - ISO 4217-alpha |
| `merchant_amount` | decimal | Valor da transação na moeda em que a transação foi realizada |
| `billing_currency_code` | string | A moeda de cobrança do portador do cartão - ISO 4217-alpha |
| `billing_amount` | decimal | Valor da transação na moeda de cobrança do portador do cartão |
| `processing_datetime` | timestamp utc | Horário em que a requisição de autorização foi processada |
| `number_of_installments` | int | Número de parcelas sendo autorizadas nesta requisição |
| `authorization_request_type` | enum | Enumerador de **[Tipos de Requisição de Autorização](#tipos-de-autorizacao)** |
| `pan_entry_mode` | enum | **[Modos de entrada do PAN](#modos-de-entrada-do-pan)** - Chip, Digitada, Tarja, Fallback, Contactless |
| `pin_sent` | boolean | Foi inserida uma senha no terminal? |
| `authorization` | object | Objeto Autorização detalhado em [GET Autorização](/documentation/cards/search/buscar_autorizacao/), presente apenas quando o tipo de autorização for incremental. |

#### Objeto Card

| Campo | Tipo | Descrição |
|---| ---| ---|
| `card_key` | string | Chave de identificação do cartão|
| `account_key` | string | Identificador da conta do titular |
| `type` | string | Tipo de cartão |
| `card_name` | string | Identificador alphanumérico do cartão|
| `printed_name` | string | Nome impresso no cartão |
| `status` | string | Status atual do cartão |
| `brand` | string | Bandeira do cartão |
| `bin` | string | BIN do cartão |
| `last_four_digits` | string | Últimos 4 dígitos do cartão |

#### Tipos de Requisição de Autorização

| Enumerador  | Descrição |
|---|---|
| **authorization** | Requisição de autorização comum |
| **incremental_authorization** | Requisição de autorização incremental para uma Autorização preexistente |
| **partial_reversal_authorization** | Autorização para realizar o estorno parcial de uma transação prévia, aparece apenas em eventos, não é autorizada explicitamente pelo cliente |
| **reversal_authorization** | Autorização para realizar o estorno de uma transação prévia, aparece apenas em eventos, não é autorizada explicitamente pelo cliente |

#### Modos de Entrada do PAN

Enumerador | ISO 8583 | Descrição
---------- | -------- | -----------
unknown | 00 | PAN entry mode desconhecido.
typed | 01 | PAN inserido manualmente (digitado).
bar_code | 03 | PAN inserido por meio de leitora de código de barras
ocr | 04 | PAN inserido por meio de OCR (Optical Character Recognition)
chip | 05 | PAN inserido por cartão com circuito integrado (Chip)
track_1 | 06 | PAN inserido pela Track 1 do cartão de tarja
contactless | 07 | PAN inserido por meio de Contactless EMV
fallback_typed | 79 | Foi tentado utilizar o leitor de cartão ou de tarja do dispositivo e o cartão mas não foi possível processar a transação com aquela informação (Possivelmente um problema no dispositivo ou no cartão), foi então digitada o PAN. Em alguns casos a adquirente não está homologada para utilizar o CHIP ou a tarja e envia este código.
fallback_magnetic_stripe | 80 | Foi tentado utilizar o leitor de cartão do dispositivo e o cartão mas não foi possível processar a transação com aquela informação (Possivelmente um problema no dispositivo ou no cartão), foi então utilizada a tarja magnética do cartão.
ecommerce | 81 | Transação de e-commerce / não presencial
magnetic_stripe | 90 | Transação de tarja (Cartão não possui chip ou dispositivo não possui leitor/não foi homologado)

### Resposta de aprovação ou negação de uma requisição de autorização

A resposta à Rquisição de Autorização deverá ser sempre com HTTP Status 201 e o parecer deve ser informado no campo *approve*. Caso o parecer seja negativo, um enumerador de razão de negação deverá ser escolhido e é possível enviar uma descrição em texto para detalhar essa negação.

ENDPOINT (client_url)/authorization_request
MÉTODO POST
HTTP STATUS 201

Response Body

```json
	"authorization_request_response": "unauthorized",
	"denial_reason": "fraud_suspicion",
    "denial_reason_details": "Customer tried to perform a transaction 10 times the average transactions"
```

 
#### Detalhe

| Campo | Tipo | Descrição |
|---|---| ---|
| `authorization_request_response` *(required)* | enumerator  | `authorized` caso a autorização seja aprovada ou `unauthorized` caso a autorização seja negada |
| `denial_reason` | enum  | **[Enumerador Razão de Negação](#enumerador-razao-de-negacao)** |
| `denial_reason_details` | string  |  Deny reason details | |

#### Enumerador Razão de Negação
| Enumerador  | Descrição |
|-----------------------|---------------------------------------------------------------------------|
| **fraud_suspicion** | Movimentação com comportamento suspeito |
| **blocked_customer** | Portador com restrições |

#### Resposta negativa

Qualquer HTTP status que não seja 2XX será interpretado como incapacidade do cliente de processar a autorização. Será então aplicada a regra de decisão configurada no programa do cliente para os casos de indisponibilidade.

Importante: Autorizações que sejam negadas pelos critérios básicos de validação de cartões serão respondidas automaticamente pela QI sem o envio de uma requisição de autorização. O cliente receberá apenas um webhook de autorização negada.

## Autorização Incremental

Uma `Authorization` poderá receber mais de uma `Authorization Request`, situação que chamamos de autorização incremental. Cada `Authorization Request` pode ou não ser autorizado e a entidade `Authorization` irá sempre representar o resultado do que for capturado com sucesso dentre as N autorizações.

Uma autorização incremental poderá ser identificada pelo campo `authorization_type` com valor *incremental_authorization*. Sempre que a requisição for deste tipo, o objeto `Authorization` relacionado será enviado junto ao payload da `Authorization Request`.

---

# Transações na QI Conta

URL: /documentation/cards/autorizacao/balance_transaction

---

No contexto de cartão pré-pago, as situações de débito ou crédito possuem um reflexo na QI Conta do portador do cartão. Essas transações são representadas pela entidade `Balance Transaction`. Essas transações devem obrigatoriamente ser executadas na QI Conta do portador mesmo que tardiamente. Sendo assim, caso um débito não possa ser efetuado por algum motivo, a `Balance Transaction` ficará pendente e será retentada automaticamente pelo sistema da QI até que todo o valor seja debitado.

É importante que essas transações sejam acompanhadas e caso alguma `Balance Transaction` persista em pendência o cliente deve entrar em contato com o portador do cartão para assegurar que a QI Conta esteja apta e com o saldo necessário para cobrir essa pendência.

Sempre que uma `Balance Transaction` for criada, um webhook de `Balance Transaction Event` será enviado.

Webhook de evento de transação na QI Conta

```json
{
	"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"data": {
		"balance_transaction_key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
		"transaction_key": "b64c1ca5-095d-4005-a4ed-3be09d7b111f",
		"amount": 25.32,
		"transacted_at": "2023-07-24T12:00:00.000Z",
		"balance_transaction_status": "transacted"
	},
	"webhook_type": "prepaid_card.balance_transaction_event",
	"event_datetime": "2023-07-24T12:00:00.000Z"
}
```

#### Details

| Campo | Tipo | Descrição |
|---|---| ---|
| `balance_transaction_key` | string  | Identificador único da Requisição de Autorização |
| `transaction_key` | string  | Identificador único da entidade Autorização relacionada com esta requisição |
| `amount` | string | O valor transacionado na QI Conta neste evento |
| `transacted_at` | string | O horário que a transação foi executada |
| `balance_transaction_status` | string | O estado da `Balance Transaction` após este evento |

O `balance_transaction_status` descreve se a transação foi executada na QI Conta do portador do cartão, podendo estar pendente (`pending_transaction_execution`), parcialmente transacionada (`partially_transacted`) ou transacionada (`transacted`)

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de webhooks!
A consulta e reenvio de webhooks pode ser feito conforme documentação: [Reenvio de webhooks](/documentation/notificacoes/reenvio_de_notificacoes)
:::

---

# Simulação de autorização

URL: /documentation/cards/autorizacao/simular_autorizacao

### Request

ENDPOINT /mock/card/authorization
MÉTODO POST

Request Body

```json
{
  "card_key": "ff3c4484-7a52-457e-b989-d9dcb87dfcd6",
  "merchant_name": "Supermarket XYZ",
  "merchant_city": "São Paulo",
  "merchant_region": "BR",
  "merchant_postal_code": "01001000",
  "merchant_mcc": "5411",
  "amount": 150.75,
  "authorization_type": "purchase"
}
```

### Response

```json
{
  "is_approved": true,
  "response_code": "00",
  "limit_amount": null
}
```

### Objeto Request Body

Nessa tabela, está disponível o descritivo de todas as variáveis utilizadas pelas requisições acima detalhadas.

| Campo                 | Tipo   | Descrição                                          | Máx. Caract. | Exemplo              |
|-----------------------|--------|----------------------------------------------------|--------------|----------------------|
| **card_key**          | string | Chave única do cartão (obrigatório)                | 36           | "ff3c4484-7a52-457e-b989-d9dcb87dfcd6"    |
| **authorization_type**| string | Tipo de autorização (obrigatório)                  | **[Enumeradores](#authorization-type-enumeradores)** |
| **merchant_name**     | string | Nome do estabelecimento                            | 40           | "Supermarket XYZ"    |
| **merchant_city**     | string | Cidade do estabelecimento                          | 40           | "São Paulo"          |
| **merchant_region**   | string | País do estabelecimento                            | 2            | "BR"                 |
| **merchant_postal_code** | string | Código postal do estabelecimento                | 8            | "01001000"           |
| **merchant_mcc**      | string | Código da categoria do estabelecimento (MCC)       | **[Enumeradores](#merchant-mcc-enumeradores)** |
| **amount**            | number | Valor da transação                                 | -            | 150.75               |

### Enumeradores merchant_mcc

| Enumerador | Descrição                                  |
|------------|--------------------------------------------|
| 5812       | Eating Places, Restaurants                 |
| 5499       | Miscellaneous Food Stores                  |
| 5814       | Fast Food Restaurants                      |
| 5411       | Grocery Stores, Supermarkets               |
| 4121       | Taxicabs and Limousines                    |
| 4111       | Local and Suburban Transit                 |
| 4215       | Courier Services, Air or Ground            |
| 5912       | Drug Stores and Pharmacies                 |
| 5815       | Digital Goods: Applications (Excludes Games)|
| 8999       | Professional Services (Not Elsewhere Classified)|
| 5462       | Bakeries                                   |
| 5541       | Service Stations (with or without Ancillary Services)|
| 7523       | Parking Lots, Parking Meters and Garages   |
| 5300       | Wholesale Clubs                            |
| 4899       | Cable, Satellite and Other Pay Television and Radio Services|
| 5311       | Department Stores                          |
| 5813       | Bars, Cocktail Lounges, Discotheques, Nightclubs and Taverns (Drinking Places)|
| 7372       | Computer Programming, Data Processing and Integrated Systems Design Services|
| 5099       | Durable Goods (Not Elsewhere Classified)   |
| 5943       | Stationery Stores, Office and School Supply Stores|
| 7299       | Miscellaneous Personal Services (Not Elsewhere Classified)|
| 5199       | Nondurable Goods (Not Elsewhere Classified)|
| 7230       | Beauty and Barber Shops                    |
| 5999       | Miscellaneous and Specialty Retail Stores  |
| 5651       | Family Clothing Stores                     |

### Enumeradores authorization_type

| Enumerador  | Descrição                  |
|-------------|----------------------------|
| purchase    | Purchase                   |
| reversal    | Reversal                   |
| withdrawal  | Withdrawal                 |

---

# Gerar cartão físico

URL: /documentation/cards/create/gerar_cartao_fisico

## Request

ENDPOINT /prepaid/card
MÉTODO POST

Request Body

```json
{
    "account_key": "5294ed8d-08fc-4397-b15f-6d9aa07b0041",
    "program_key": "7d405c31-ec9a-46c1-8ac8-54bab209bf41",
    "type": "plastic",
    "card_name": "ecommerce",
    "printed_name": "Aurora Catarina",
    "contactless_enabled": true,    
    "delivery_address": {
        "address": "Rua Cel. Domingos Diniz",
        "number": 124,
        "neighborhood": "Centro",
        "zip_code": "35797000",
        "city": "Presidente Juscelino",
        "state": "MG",
        "complement": "Quadra 08 Lote 259",
        "reference": "Supermercado Presidente",
        "address_type": "residential"
    }
}
```

:::info
O endereço utilizado para o envio do cartão físico, será o mesmo informado na abertura da conta de pagamento na QI Tec. 
:::

  ### Body params

| Campo                   | Tipo    | Descrição                                                                                      | Caracteres                                  |
|-------------------------|---------|------------------------------------------------------------------------------------------------|---------------------------------------------|
| `account_key` *         | string  | Chave de identificação da conta de pagamento na QI Tech.                                       | uuid                                        |
| `program_key` *         | string  | Chave de identificação do programa para emitir um cartão.                                      | uuid                                        |
| `type` *                | string  | Tipo do cartão a ser emitido (PLASTIC).                                                        | **[Enumeradores](#enumeradores-card_type)** |
| `card_name` *           | string  | Alias do cartão, como esse cartão será identificado.                                           | 15                                          |
| `printed_name` *        | string  | Nome que será impresso no cartão (não será permitido o uso de números e caracteres especiais). | 26                                          |
| `contactless_enabled` * | boolean | Habilitar ou desabilitar o uso de contactless do cartão                                        | -                                           |
| `delivery_address`   | Object | Endereco de entrega do cartão                                                                               | **[Objeto Address](#address)** |

### Enumeradores card_type

| Enumerador | Tradução       | 
|------------|----------------|
| plastic    | Cartão físico  | 
| virtual    | Cartão virtual | 

### Address

| Campo                   | Tipo    | Descrição                                                                                      | Caracteres                                  |
|-------------------------|---------|------------------------------------------------------------------------------------------------|---------------------------------------------|
| address*              | string | Endereço de entrega | 100 |
| neighborhood*| string | Bairro do endereço de entrega | 100 |
| zip_code*    | string | CEP do endereço de entrega | 8 |
| city*        | string | Cidade do endereço de entrega | 100 |
| state*       | string | Estado do endereço de entrega | 2 |
| number        | number | Número do endereço de entrega |  |
| complement   | string | Complemento do endereço de entrega | 100 |
| reference    | string | Ponto de referência do endereço de entrega | 100 |
| address_type*        | string | Tipo de entrega  | **[Enumeradores](#enumeradores-address_type)** |

:::caution Atenção!
O campo `number` é opcional. Endereços sem numeração podem ser enviados sem este campo.
:::

### Enumeradores address_type

| Enumerador | Tradução             | 
|------------|----------------------|
| residential| Endereço residencial |  
| commercial | Endereço comercial   | 
| other      | Outro endereço       | 

## Response

STATUS 201

Response Body

```json
{
    "card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",
	"created_at": "2023-06-20T19:28:16Z",
    "status":"created"
}
```

### Erros

STATUS 4XX

Response Body

```json
{
  "title": "Bad Request",
  "description": "The type of person is invalid for this program, please try another.",
  "translation": "Invalid Person",
  "code": "CARD000007"
}
```

| Code      | Status code  | Descrição                      |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400          | Invalid Json schema.|
| CARD000005| 404          | It was not possible to fetch the Program for the program_key \{program_key\}.|
| CARD000006| 404          | It was not possible to fetch the Account for the account_key \{account_key\}.|
| CARD000007| 400          | The type of person is invalid for this program, please try another.|
| CARD000008| 400          | The Card Holder with the status \{status\} is invalid for the operation.|
| CARD000009| 400          | We're sorry, but the card could not be generated. Please try again later.|
| CARD000010| 404          | It was not possible to fetch the Person for the person_key \{owner_person_key\}.|
| CARD000033| 403          | Create plastic card is not allowed for program_key \{program_key\}.|

### Webhook

WEBHOOK_TYPE baas.prepaid_card.card

Webhook Body

```json
{
    "webhook_type": "baas.prepaid_card.card",
    "event_datetime": "2023-07-24T12:00:00.000Z",
    "data": {
        "card_key": "9bd93e97-bb6d-410f-8981-06b2765f12a1",
        "account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
        "program_key": "bf74df61-557a-45cb-914f-41e127a6e18c",
        "status": "created",
        "type": "plastic"
    }
}
```

---

# Criar cartão virtual

URL: /documentation/cards/create/gerar_cartao_virtual

## Request

ENDPOINT /prepaid/card
MÉTODO POST

Request Body

```json
{
    "account_key": "5294ed8d-08fc-4397-b15f-6d9aa07b0041",
    "program_key":"7d405c31-ec9a-46c1-8ac8-54bab209bf41",
    "type": "virtual",
    "card_name": "ecommerce",
    "printed_name": "Aurora Catarina",
    "cvv_rotation_interval_hours": 72
}
```

  ### Body params

| Campo                           | Tipo   | Descrição                                                                                      | Caracteres                                  |
|---------------------------------|--------|------------------------------------------------------------------------------------------------|---------------------------------------------|
| `account_key` *                 | string | Chave de identificação da conta de pagamento na QI Tech.                                       | uuid                                        |
| `program_key` *                 | string | Chave de identificação do programa para emitir um cartão.                                      | uuid                                        |
| `type` *                        | string | Tipo do cartão a ser emitido (VIRTUAL).                                                        | **[Enumeradores](#enumeradores-card_type)** |
| `card_name` *                   | string | Alias do cartão, como esse cartão será identificado.                                           | uuid                                        |
| `printed_name` *                | string | Nome que será impresso no cartão (não será permitido o uso de números e caracteres especiais). | uuid                                        |
| `cvv_rotation_interval_hours` * | int    | Intervalo em horas para atualizar o número CVV.                                                | Number                                      |

### Enumeradores card_type

| Enumerador | Tradução       | 
|------------|----------------|
| plastic    | Cartão físico  | 
| virtual     | Cartão virtual | 

## Response

STATUS 201

Response Body

```json
{
    "card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",
	"created_at": "2023-02-20T19:28:16Z",
    "status":"created"
}
```

### Erros

STATUS 4XX

Response Body

```json
{
  "title": "Bad Request",
  "description": "The type of person is invalid for this program, please try another.",
  "translation": "Invalid Person",
  "code": "CARD000007"
}
```

| Code      | Status code  | Descrição                      |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400          | Invalid Json schema.|
| CARD000005| 404          | It was not possible to fetch the Program for the program_key \{program_key\}.|
| CARD000006| 404          | It was not possible to fetch the Account for the account_key \{account_key\}.|
| CARD000007| 400          | The type of person is invalid for this program, please try another.|
| CARD000008| 400          | The Card Holder with the status \{status\} is invalid for the operation.|
| CARD000009| 400          | We're sorry, but the card could not be generated. Please try again later.|
| CARD000010| 404          | It was not possible to fetch the Person for the person_key \{owner_person_key\}.|
| CARD000032| 403          | Create virtual card is not allowed for program_key \{program_key\}.|

### Webhook

WEBHOOK_TYPE baas.prepaid_card.card

Webhook Body

```json
{
    "webhook_type": "baas.prepaid_card.card",
    "event_datetime": "2023-07-24T12:00:00.000Z",
    "data": {
        "card_key": "9bd93e97-bb6d-410f-8981-06b2765f12a1",
        "account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
        "program_key": "bf74df61-557a-45cb-914f-41e127a6e18c",
        "status": "created",
        "type": "virtual"
    }
}
```

---

# Introdução

URL: /documentation/cards/introducao

As APIs para emissão de cartão pré pago, permitem que os clientes dos parceiros da QI Tech, solicitem e emitam Cartões Pré Pagos, sejam eles físicos ou virtuais.

Na QI Tech, oferecemos aos nossos parceiros a oportunidade de se tornarem subemissores. Por meio das nossas APIs, os parceiros podem disponibilizar aos seus próprios clientes a possibilidade de emitir tanto cartões pré pagos físicos como virtuais, permitindo assim uma solução completa para serviços bancários.

Para entender melhor nosso sistema faremos uma breve introdução de como funciona o ecossistema de cartões pré pagos, mas lembramos que assim como as demais APIs a liberação do serviço deve ser feita junto ao nosso time e as **[chamadas são autenticadas](/documentation/primeiros_passos/teste_de_autenticacao)**.

### Cartão Pré Pago

O cartão pré pago é um cartão que esta vinculado a uma conta de pagamento dentro da QI Tech.

Todas as transações executadas através deste cartão, debitarão o saldo existente na conta de pagamentos.

Caso a conta não tenha saldo a transação será negada.

### Conta de Pagamento

A QI Tech é uma instituição financeira autorizada a operar com contas de pagamento pré pago pelo Banco Central do Brasil. Um Cartão pré pago esta sempre vinculado à uma conta de pagamento pré pago.

Sendo assim, para criação de um cartão pré pago, seja ele físico ou virtual, é sempre necessário realizar a abertura de uma conta de pagamento. Confira **[aqui](/documentation/contas/abertura_de_conta/abertura_de_conta_pf)** nossa API de abertura de contas.

### Programa

Para que um parceiro possa realizar a emissão de um cartão pré pago, é necessário que ele tenha um programa associado e configurado em sua integração com a QI.

O programa é nada mais que as configurações e regras necessárias para a emissão do cartão em conformidade com a bandeira VISA.

Aqui estão algumas informações importantes sobre o programa:

* **Tipo do programa** - Refere-se à modalidade de utilização do cartão. No caso desta documentação, trata-se da modalidade Pré Pago.
* **Bandeira** -  Utilizamos a bandeira VISA para os cartões emitidos pelo programa.
* **Layout do cartão** - Refere-se ao desenho que será impresso no cartão físico e que será apresentado na interface gráfica do cartão virtual. 

:::caution Atenção
Para configuração de um novo programa em uma integração, o time comercial e o time de implantação da QI Tech deverão ser acionados.
:::

### Cartão Virtual

A API de cartões da QI Tech oferece a funcionalidade de geração de cartões virtuais, que podem ser utilizados em transações online. Essa solução proporciona segurança e comodidade aos portadores de cartão.

Ao utilizar um cartão virtual, os portadores não precisam fornecer os detalhes do cartão físico durante transações pela internet. Em vez disso, eles podem gerar um cartão virtual único, com um número e informações específicas para aquela transação em particular. Isso ajuda a reduzir o risco de fraude e aumenta a confiança nas transações online.

### Cartão Físico

A API de cartões da QI Tech oferece a opção de criação de cartões físicos, proporcionando aos portadores a possibilidade de ter um cartão de plástico para uso em transações presenciais.

Ao solicitar um cartão físico, o portador receberá um cartão de plástico personalizado.

A disponibilidade do cartão físico oferece aos portadores uma forma tradicional e amplamente aceita de realizar pagamentos, garantindo conveniência e praticidade em suas transações presenciais. Além disso, o cartão físico também pode apresentar recursos adicionais, como tecnologia de pagamento por aproximação (contactless) para agilizar as transações.

API de cartões pré pagos da QI Tech, possibilita ao portador do cartão a flexibilidade de escolher entre o uso de cartões virtuais para transações online e a utilização de cartões físicos para transações presenciais, de acordo com suas necessidades e preferências individuais.

---

# Buscar autorização pela Chave da Autorização

URL: /documentation/cards/search/buscar_autorizacao

## Request

ENDPOINT /prepaid/card/(card_key)/authorization/(authorization_key)
MÉTODO GET

## Response

STATUS 200

Response Body

```json
{
    "authorization_key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
    "merchant_currency_code": "BRL",
    "original_merchant_amount": 25.32,
    "billing_currency_code": "BRL",
    "original_billing_amount": 25.32,
    "merchant_amount": 25.32,
    "iof_amount": 0,
    "billing_amount": 25.32,
    "processing_datetime": "2023-07-24T12:00:00.000Z",
    "captured_amount": 25.32,
    "authorization_status": "completed",
    "card": {
        "card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",
        "account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
        "type": "virtual",
        "card_name": "ecommerce sample",
        "printed_name": "Aurora Catarina",
        "status": "active",
        "brand": "visa",
        "bin": "123456",
        "last_four_digits": "5695"
    },
    "balance_transactions": [
        {
            "balance_transaction_key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
            "balance_transaction_type": "debit",
            "account_transaction_key": "595e08f0-da4e-40f7-8db4-f9a25c820000",
            "account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
            "merchant_currency_code": "BRL",
            "merchant_amount": 25.32,
            "billing_currency_code": "BRL",
            "billing_amount": 25.32,
            "processing_datetime": "2023-01-10T13:45:52.000Z",
            "balance_transaction_status": "transacted",
            "transacted_amount": 25.32,
        }
    ],
    "authorization_requests": [
        {
            "authorization_request_key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
            "authorization_code": "473890",
            "nsu": "123456",
            "acquirer_reference_number": "12312423",
            "merchant_currency_code": "BRL",
            "merchant_amount": 25.32,
            "billing_currency_code": "BRL",
            "billing_amount": 25.32,
            "processing_datetime": "2023-01-10T13:45:52.000Z",
            "number_of_installments": 1,
            "authorization_type": "authorization",
            "authorization_request_response": "authorized"
        }
    ],
    "authorization_events": [
        {
            "merchant_currency_code": "BRL",
            "merchant_amount": 25.32,
            "billing_currency_code": "BRL",
            "billing_amount": 25.32,
            "processing_datetime": "2023-07-24T12:00:00.000Z",
            "authorization_event_type": "authorization"
        }
    ]
}
```

### Objeto Autorização

| Campo | Tipo | Descrição |
|---|---| ---|
| authorization_key | string | Identificador único da autorização |
| merchant_currency_code | string |  A moeda utilizada na transação - ISO 4217-alpha |
| original_merchant_amount | decimal | Valor original da transação na moeda em que a transação foi realizada |
| billing_currency_code | string | A moeda de cobrança do portador do cartão - ISO 4217-alpha |
| original_billing_amount | decimal | Valor original da transação na moeda de cobrança do portador do cartão |
| merchant_amount | decimal | Somatório do Valor da transação na moeda em que a transação foi realizada de todas requisições de autorização |
| iof_amount | decimal | Somatório do valor de IOF pago no câmbio quando as moedas da transação e de cobrança do portador forem diferentes |
| billing_amount | decimal | Somatório do valor da transação na moeda de cobrança do portador do cartão de todas requisições de autorização |
| processing_datetime | datetime UTC | Horário em que o objeto de autorização foi criado, em geral, horário da primeira requisição de autorização feita |
| captured_amount | decimal | Somatório do valor total capturado por todas requisições de autorização |
| authorization_status | enumerator | Enumerador de **[Status da Autorização](#status-da-autorizacao)** |
| card | object |**[Objeto Card](#objeto-card)**  |
| balance_transactions | list of objects |**[Objeto Balance Transaction](#objeto-balance-transaction)**  |
| authorization_requests | list of objects |**[Objeto Requisição de Autorização](#objeto-rquisicao-de-autorizacao)**  |
| authorization_events | list of objects | **[Objeto Evento de Autorização](#objeto-evento-autorizacao)**  |

### Objeto Card

| Campo | Tipo | Descrição |
|---| ---| ---|
| card_key | string | Chave de identificação do cartão|
| account_key | string | Identificador da conta do titular |
| type | string | Tipo de cartão |
| card_name | string | Identificador alphanumérico do cartão|
| printed_name | string | Nome impresso no cartão |
| cvv_rotation_interval_hours | int | Intervalo de rotação do CVV |
| status | string | Status atual do cartão |
| brand | string | Bandeira do cartão |
| bin | string | BIN do cartão |
| last_four_digits | string | Últimos 4 dígitos do cartão |

### Objeto Balance Transaction

O objeto `Balance Transaction` representa qualquer movimentação na QI Conta do titular do cartão que precise ser efetuada. Podem ser transações de *débito* por ocasião de uma Autorização aprovada, como podem ser de *crédito* numa situação de cancelamento de autorização por exemplo.

| Campo | Tipo | Descrição |
|---| ---| ---|
| balance_transaction_key | string | Identificador único da transação |
| balance_transaction_type | enumerador | *credit* quando se tratar de um crédito em conta e *debit* quando se tratar de um débito em conta|
| account_key | string | Identificador da QI Conta relacionada com o cartão usado na transação |
| merchant_currency_code | string | A moeda utilizada na transação - ISO 4217-alpha |
| merchant_amount | decimal | Equivalente de valor cobrado na moeda da transação |
| billing_currency_code | string | A moeda de cobrança do portador do cartão - ISO 4217-alpha |
| billing_amount | decimal | Valor da transação na moeda de cobrança do portador do cartão |
| processing_datetime | datetime | Representa a data de processamento e criação da transação. Como a transação efetiva na QI Conta pode não ocorrer, este valor é uma referência de quando a cobrança ou crédito foram gerados |
| balance_transaction_status | enumerator | Descreve se a transação foi executada na QI Conta do portador do cartão, podendo estar pendente (`pending_transaction_execution`), parcialmente transacionada (`partially_transacted`) ou transacionada (`transacted`)|
| transacted_amount | decimal | Valor total na moeda do portador do cartão do débito ou crédito que já foram executados na QI Conta |

### Objeto Requisição de Autorização

Detalhado em [Requisição de Autorização](/documentation/cards/autorizacao/)

### Objeto Evento de Autorização

O objeto `Authorization Event` representa os eventos que ocorrem com uma Autorização. Uma forma mais detalhada de como eles podem ocorrer está descrita em [Manuais](/documentation/manual_pre_pago/casos_uso/)
| Campo | Tipo | Descrição |
|---| ---| ---|
| merchant_currency_code | string | A moeda utilizada na transação - ISO 4217-alpha |
| merchant_amount | decimal |  Equivalente de valor cobrado na moeda da transação |
| billing_currency_code | string | A moeda de cobrança do portador do cartão - ISO 4217-alpha |
| billing_amount | decimal | Valor do evento na moeda de cobrança do portador do cartão |
| processing_datetime | datetime | Representa a data de processamento do evento |
| authorization_event_type | enumerator | **[Tipos de Evento de Autorização](#tipos-evento-autorizacao)** |

### Status da Autorização

| Estado | Descrição |
|---|---|
| pending | Requisição de autorização foi aprovada e nenhum evento de captura ou cancelamento foi processado |
| unauthorized | Requisição de autorização não foi aprovada |
| completed | Pelo menos um valor capturado com sucesso para a autorização em questão (seja um valor igual, a menor ou a maior que o valor total aprovado nas requisições de autorização) |
| reversed | Autorização foi estornada por completo ou expirou sem captura |

### Tipos de Evento de Autorização

| Tipo | Descrição |
|---|---|
| authorization | Informe de que uma requisição de autorização foi respondida |
| incremental_authorization | Informe de que uma requisição de autorização incremental foi respondida |
| authorization_reversal | Informe de que um cancelamento de autorização foi processado |
| partial_authorization_reversal | Informe de que um cancelamento parcial de autorização foi processado |
| authorization_expiration | Informe de que uma autorização expirou |
| capture | Informe de que um determinado valor foi capturado para uma autorização |
| refund | Informe de que uma autorização foi reembolsada |
| partial_refund | Informe de que uma autorização foi reembolsada parcialmente |

---

# Buscar Authorizações

URL: /documentation/cards/search/buscar_autorizacoes

## Request

ENDPOINT /prepaid/card/(card_key)/authorizations
MÉTODO GET
PARÂMETROS from_date, to_date, size, page

## QUERY PARAMS

| Campo           | Tipo   | Descrição                                                |
|-----------------|--------|----------------------------------------------------------|
| `size`          | int    | Quantidade de registros que será retornado. Default 10.  |
| `page`          | int    | Página que será realizado a busca. Default 1.            |
| `from_date`     | date   | Data de início do período desejado                       |
| `to_date`       | date   | Data de fim do período desejado                          |

## Response

STATUS 200

Response Body

```json
{
    "pagination": {
        "current_page": 1,
        "rows_per_page": 10,
        "next_page": 2
    },
    "data": [
        {
            "authorization_key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
            "merchant_currency_code": "BRL",
            "original_merchant_amount": 25.31,
            "billing_currency_code": "BRL",
            "original_billing_amount": 25.31,
            "merchant_amount": 25.31,
            "iof_amount": 0,
            "billing_amount": 25.31,
            "processing_datetime": "2023-07-24T12:00:00.000Z",
            "captured_amount": 25.31,
            "authorization_status": "completed"
        },
        {
            "authorization_key": "9a7b2586-7070-4543-99eb-989d9165814e",
            "merchant_currency_code": "BRL",
            "original_merchant_amount": 65,
            "billing_currency_code": "BRL",
            "original_billing_amount": 65,
            "merchant_amount": 65,
            "iof_amount": 0,
            "billing_amount": 65,
            "processing_datetime": "2023-07-24T13:00:00.000Z",
            "captured_amount": 65,
            "authorization_status": "completed"
        }
    ]
```

---

# Buscar cartão por chave

URL: /documentation/cards/search/buscar_cartao_by_key

## Request

ENDPOINT /prepaid/card/ CARD_KEY
MÉTODO GET

### Path params

| Campo        | Tipo   | Descrição                         | Caracteres |
|--------------|--------|-----------------------------------|------------|   
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid       |
 

## Response

STATUS 200

Response Body

```json
{
    "card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",    
    "account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
    "program_key": "6b6ebaac-043b-4390-8d62-e8098ec901e9",
    "type": "virtual",
    "card_name": "ecommerce",
    "printed_name": "Aurora Catarina",
    "cvv_rotation_interval_hours": 72,
    "created_at": "2023-02-20T19:28:16Z",
    "updated_at": "2023-02-22T19:28:16Z",
    "status": "active",
    "brand": "visa",
    "last_four_digits": "5695",
    "status_events": [
        {
            "status": "created",
            "created_at": "2023-02-20T19:28:16Z"
        },
        {
            "status": "active",
            "created_at": "2023-02-20T19:35:10Z"
        }
    ]
}
```

### Erros

STATUS 4XX

Response Body

```json
{
  "title": "Not Found",
  "description": "It was not possible to fetch the Card for the card_key f6bf148a-30b6-4a07-8c5b-3383a98ea32b.",
  "translation": "Not Found Card",
  "code": "CARD000011"
}
```

| Code      | Status code  | Descrição                      |
|:---------:|:------------:|:-------------------------------|
| CARD000011| 404          | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000016| 400          | We're sorry, but the card could not be fetch. Please try again later.|

---

# Buscar dados PCI

URL: /documentation/cards/search/buscar_dados_pci

## Request

ENDPOINT /prepaid/card/ CARD_KEY /pci
MÉTODO GET

### Path params

| Campo        | Tipo   | Descrição                         | Caracteres |
|--------------|--------|-----------------------------------|------------|   
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid       |

## Response

STATUS 200

Response Body

```json
{
    "printed_name": "Aurora Catarina",
    "valid_until": "2023-02-20T10:04:12Z",
    "expiration_date": "03/24",
    "card_number": "4539347744299311",
    "cvv": "713"
}
```

### Erros

STATUS 4XX

Response Body

```json
{
  "title": "Not Found",
  "description": "It was not possible to fetch the Card for the card_key f6bf148a-30b6-4a07-8c5b-3383a98ea32b.",
  "translation": "Not Found Card",
  "code": "CARD000011"
}
```

| Code      | Status code  | Descrição                      |
|:---------:|:------------:|:-------------------------------|
| CARD000011| 404          | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000012| 400          | It was not possible to fetch PCI for the card_key \{card_key\}.|

---

# Buscar entrega por chave de cartão

URL: /documentation/cards/search/buscar_entrega_by_key

## Request

ENDPOINT /card/ CARD_KEY /tracking
MÉTODO GET

### Path params

| Campo        | Tipo   | Descrição                         | Caracteres |
|--------------|--------|-----------------------------------|------------|
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid       |

## Response

STATUS 200

Response Body

```json
{
  "card_key": "92b4e2bd-4a6f-4c56-859e-17c729e1f0c8",
  "tracking_code": "4F68A72B902317",
  "status": "posted",
  "recipient": "João Silva",
  "address": {
    "zip_code": "1234567",
    "street": "Rua das Flores",
    "number": 123,
    "complement": "Bloco A",
    "neighborhood": "Centro",
    "city": "Cidade Exemplo",
    "state": "SP"
  },
  "event": [
    {
      "created_at": "2024-02-27T08:30:00Z",
      "old_status": "pending",
      "new_status": "posted",
      "description": "Pedido recebido e postado",
      "place": "SAO PAULO"
    }
  ]
}
```

### Enumeradores DeliveryStatus

| Enumerador         | Tradução            |
|--------------------|---------------------|
| pending            | Pendente            |
| posted             | Postado             |
| prepared           | Preparado           |
| in_transfer        | Em transferência    |
| in_delivery_unit   | Na unidade de entrega |
| on_route           | Em rota             |
| attempt_failed     | Tentativa falhou    |
| awaiting_withdrawal| Aguardando retirada |
| returning          | Retornando          |
| delivered          | Entregue            |
| returned           | Devolvido           |
| canceled           | Cancelado           |
| failed             | Falhou              |
| resend             | Reenviado           |

### Erros

STATUS 4XX

Response Body

```json
{
  "title": "Not Found",
  "description": "It was not possible to fetch the Tracking for the card_key f6bf148a-30b6-4a07-8c5b-3383a98ea32b.",
  "translation": "Not Found",
  "code": "TRACK000011"
}
```

| Code      | Status code  | Descrição                      |
|:---------:|:------------:|:-------------------------------|
| TRACK000011| 404          | It was not possible to fetch the Tracking for the card_key \{card_key\}.|
| TRACK000016| 400          | We're sorry, but the tracking could not be fetch. Please try again later.|

---

# Buscar Senha PCI

URL: /documentation/cards/search/buscar_senha

## Request

ENDPOINT /prepaid/card/ CARD_KEY /pci/password
MÉTODO GET

### Path params

| Campo        | Tipo   | Descrição                         | Caracteres |
|--------------|--------|-----------------------------------|------------|   
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid       |

## Response

STATUS 200

Response Body

```json
{
    "pin": "1234"
}
```

### Erros

STATUS 4XX

Response Body

```json
{
  "title": "Bad Request",
  "description": "It was not possible to fetch PCI for the card_key f6bf148a-30b6-4a07-8c5b-3383a98ea32b.",
  "translation": "Fetch PCI failed",
  "code": "CARD000012"
}
```

| Code      | Status code  | Descrição                      |
|:---------:|:------------:|:-------------------------------|
| CARD000011| 404          | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000012| 400          | It was not possible to fetch PCI for the card_key \{card_key\}.|

---

# Listar cartões

URL: /documentation/cards/search/listar_cartoes

## Request

ENDPOINT /prepaid/card
MÉTODO GET
PARÂMETROS account_key, size, page

## QUERY PARAMS

| Campo           | Tipo   | Descrição                                                | Caracteres |
|-----------------|--------|----------------------------------------------------------|------------| 
| `account_key` * | string | Chave de identificação da conta de pagamento na QI Tech. | uuid       |
| `size`          | int    | Quantidade de registros que será retornado. Default 10.  | -          |
| `page`          | int    | Página que será realizado a busca. Default 0.            | -          |

## Response

STATUS 200

Response Body

```json
{
    "pagination": {
        "current_page": 1,
        "rows_per_page": 0,
        "next_page": 2
    },
    "data": [
        {
            "card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",        
            "account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
            "program_key": "6b6ebaac-043b-4390-8d62-e8098ec901e9",
            "type": "virtual",
            "card_name": "ecommerce",
            "printed_name": "Aurora Catarina",
            "cvv_rotation_interval_hours": 72,
            "created_at": "2023-02-20T19:28:16Z",
            "updated_at": "2023-02-22T19:28:16Z",
            "status": "active",
            "brand": "visa"
        },
        {
            "card_key": "ee084f00-d72e-4263-87fb-3a3c11a418c6",
            "account_key": "595e08f0-da4e-40f7-8db4-f9a25c829818",
            "program_key": "6b6ebaac-043b-4390-8d62-e8098ec901e9",
            "type": "virtual",
            "card_name": "uber",
            "printed_name": "Aurora Catarina",
            "cvv_rotation_interval_hours": 72,
            "created_at": "2023-02-10T11:28:16Z",
            "updated_at": "2023-02-15T11:28:16Z",
            "status": "canceled",
            "brand": "visa"
        }
    ]
}
```

### Erros

STATUS 4XX

Response Body

```json
{
  "title": "Not Found",
  "description": "It was not possible to fetch the Account for the account_key 94f982c0-164c-45e3-8a0e-69f54ad7b155.",
  "translation": "Not Found Account",
  "code": "CARD000006"
}
```

| Code      | Status code  | Descrição                      |
|:---------:|:------------:|:-------------------------------|
| CARD000006| 404          | It was not possible to fetch the Account for the account_key \{account_key\}.|
| CARD000021| 400          | Account key can not be null when search for cards.|
| CARD000022| 400          | Invalid integer value for page or size querystring parameters.|

---

# Ativar cartão físico

URL: /documentation/cards/status/ativar_cartao

Todo cartão físico precisa ser ativado através de um código de ativação que é enviado junto do cartão físico, ao portador.

Ao receber o cartão por correspondência, o portador do cartão precisa informar ao parceiro da QI, para que o parceiro realize a ativação do cartão através deste endpoint.

:::caution Atenção
Por motivos de segurança, não existe a possibilidade de consulta do código de ativação via API por parte do parceiro.

Este código é enviado, exclusivamente ao portador do cartão, no momento da postagem do cartão físico.

Para realizar testes de integração, esse código é devolvido em ambiente de sandobox ao consultar um cartão.
:::

## Request

ENDPOINT /prepaid/card/ CARD_KEY /activate
MÉTODO PATCH

### Path params
| Campo        | Tipo   | Descrição                         | Caracteres |
|--------------|--------|-----------------------------------|------------|   
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid       |

Request Body

```json
{
    "code": "253615"
}
```

  ### Body params

| Campo     | Tipo   | Descrição                     | Caracteres |
|-----------|--------|-------------------------------|------------|
| `code`  * | string | Código de ativação do cartão. | 6          |

### Erros

STATUS 4XX

Response Body

```json
{
  "title": "Not Acceptable",
  "description": "Invalid activation code [1254].",
  "translation": "Unable to activate card",
  "code": "CARD000020"
}
```

| Code      | Status code  | Description                    |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400          | Invalid Json schema.|
| CARD000011| 404          | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000017| 406          | The activation operation is not valid for the current card status [\{card_status\}].|
| CARD000018| 400          | We're sorry, but the card could not be activate. Please try again later.|
| CARD000020| 406          | Invalid activation code [\{code\}].|
| CARD000023| 406          | The card type is invalid for this operation. Only plastic cards are allowed.|

### Webhook

WEBHOOK_TYPE baas.prepaid_card.card

Webhook Body

```json
{
    "webhook_type": "baas.prepaid_card.card",
    "event_datetime": "2023-07-25T12:00:00.000Z",
    "data": {
        "card_key": "9bd93e97-bb6d-410f-8981-06b2765f12a1",
        "type": "plastic",
        "status": "active",
        "old_status": "embossing"
    }
}
```

---

# Atualizar status

URL: /documentation/cards/status/update_status_cartao

## Request

ENDPOINT /prepaid/card/ CARD_KEY
MÉTODO PATCH

### Path params

| Campo        | Tipo   | Descrição                         | Caracteres |
|--------------|--------|-----------------------------------|------------|   
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid       |

Request Body

```json
{
    "status": "blocked"
}
```

  ### Body params

| Campo       | Tipo   | Descrição         | Caracteres                                    |
|-------------|--------|-------------------|-----------------------------------------------|
| `status`  * | string | Status do cartão. | **[Enumeradores](#enumeradores-card_status)** |

### Enumeradores card_status
| Enumerador | Tradução            | Tipo            |
|------------|---------------------|-----------------|
| created    | Criação solicitada  | Initial         |
| building   | Em construção       | Initial         |
| active     | Apto a transacionar | Active          |
| embossing  | Em produção         | Temporary block |
| blocked    | Bloqueado           | Temporary block |
| warning    | Com suspeita        | Temporary block |
| pending    | Pendente            | Temporary block |
| lost       | Perdido             | Terminated      |
| robbed     | Roubado             | Terminated      |
| fraud      | Fraudado            | Terminated      |
| canceled   | Cancelado           | Terminated      |
| theft      | Furtado             | Terminated      |

### Erros

STATUS 4XX

Response Body

```json
{
  "title": "Not Acceptable",
  "description": "The operation is not valid for the current status of the card [canceled]",
  "translation": "Unable to transition",
  "code": "CARD000014"
}
```

| Code      | Status code  | Descrição                      |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400          | Invalid Json schema.|
| CARD000011| 404          | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000013| 406          | Unable to transition from \{old_status\} to \{new_status\}.|
| CARD000014| 406          | The operation is not valid for the current status of the card [\{card_status\}].|
| CARD000015| 400          | We're sorry, but the card could not be update. Please try again later|

### Webhook

WEBHOOK_TYPE baas.prepaid_card.card

Webhook Body

```json
{
    "webhook_type": "baas.prepaid_card.card",
    "event_datetime": "2023-07-25T12:00:00.000Z",
    "data": {
        "card_key": "9bd93e97-bb6d-410f-8981-06b2765f12a1",
        "type": "virtual",
        "status": "active",
        "old_status": "created"
    }
}
```

---

# Configuração do contactless

URL: /documentation/cards/update/contactless_cartao

Ativar ou desativar a funcionalidade de pagamento por aproximação (contactless) para uso presencial.

Para ativar ou desativar o pagamento por aproximação do cartão, o status do cartão deve ser do tipo **Ativo** ou **Bloqueio temporário**. (Para obter informações sobre os tipos de status, consulte [aqui](../../cards/status/update_status_cartao#enumeradores-card_status))

## Request

ENDPOINT /prepaid/card/ CARD_KEY /contactless
MÉTODO PATCH

### Path params
| Campo        | Tipo   | Descrição                         | Caracteres |
|--------------|--------|-----------------------------------|------------|   
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid       |

Request Body

```json
{
    "contactless_enabled": false
}
```

### Body params

| Campo                     | Tipo    | Descrição                         | Caracteres |
|---------------------------|---------|-----------------------------------|------------|
| `contactless_enabled`  *  | Boolean | Indica se está habilitado ou não. | true/false |

## Response

STATUS SUCCESS 200

### Erros

STATUS 4XX

Response Body

```json
{
  "title": "Bad Request",
  "description": "We're sorry, but the card could not be update contactless. Please try again later.",
  "translation": "Unexpected error update contactless card",
  "code": "CARD000026"
}
```

| Código    | Status code  | Descrição                      |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400          | Invalid Json schema.|
| CARD000011| 404          | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000023| 406          | The card type is invalid for this operation. Only plastic cards are allowed.|
| CARD000026| 400          | We're sorry, but the card could not be update contactless. Please try again later.|
| CARD000025| 406          | The status \{status\} is invalid for the operation.|

### Webhook

WEBHOOK_TYPE baas.prepaid_card.card.updated.contactless

Webhook Body

```json
{
    "webhook_type": "baas.prepaid_card.card.updated.contactless",
    "event_datetime": "2023-07-25T12:00:00.000Z",
    "data": {
        "card_key": "9bd93e97-bb6d-410f-8981-06b2765f12a1",
        "contactless_enabled": true
    }
}
```

---

# Alterar senha cartão físico

URL: /documentation/cards/update/password_cartao

Todo cartão físico tem uma senha para autorizar a transação, e ela pode ser atualizada caso necessária.

Para atualizar a senha do cartão o status tem que ter o tipo **Active** ou **Temporary block**.(Para conhecer sobre status consulte [aqui](../../cards/status/update_status_cartao#enumeradores-card_status))

:::caution Atenção
Por motivos de segurança, cuidado ao atualizar uma senha, pois ela pode impactar na autorização de um cartão.

Crie regras para melhorar a segurança da autorização da senha, como não utilizar data de aniversário, números repetidos (ex: 3333).
:::

## Request

ENDPOINT /prepaid/card/ CARD_KEY /password
MÉTODO PATCH

### Path params
| Campo        | Tipo   | Descrição                         | Caracteres |
|--------------|--------|-----------------------------------|------------|   
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid       |

Request Body

```json
{
    "pin": "2143"
}
```

  ### Body params

| Campo     | Tipo   | Descrição                                     | Caracteres |
|-----------|--------|-----------------------------------------------|------------|
| `pin`  *  | string | Senha do cartão para autorizar uma transação. | 4          |

## Response

STATUS SUCCESS 200

### Erros

STATUS 4XX

Response Body

```json
{
  "title": "Bad Request",
  "description": "We're sorry, but the card could not be update password. Please try again later.",
  "translation": "Unexpected error update password card",
  "code": "CARD000024"
}
```

| Código    | Status code  | Descrição                      |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400          | Invalid Json schema.|
| CARD000011| 404          | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000023| 406          | The card type is invalid for this operation. Only plastic cards are allowed.|
| CARD000024| 400          | We're sorry, but the card could not be update password. Please try again later.|
| CARD000025| 406          | The status \{status\} is invalid for the operation.|

### Webhook

WEBHOOK_TYPE baas.prepaid_card.card.updated.password

Webhook Body

```json
{
    "webhook_type": "baas.prepaid_card.card.updated.password",
    "event_datetime": "2023-07-25T12:00:00.000Z",
    "data": {
        "card_key": "9bd93e97-bb6d-410f-8981-06b2765f12a1"
    }
}
```

---

# Atualizar endereço de entrega

URL: /documentation/cards/update/update_delivery_address

A atualização do endereço de entrega serve para corrigir o endereço caso alguma inconsistência seja encontrada ou a entrega seja mal sucedida três vezes.

## Request

ENDPOINT /account/ ACCOUNT_KEY /card/ CARD_KEY /address
MÉTODO POST

### Path parameters

| Campo                   | Tipo   | Descrição                                                    | Caracteres |
|-------------------------|--------|--------------------------------------------------------------|------------|
| `account_key`           | uuidv4 | Chave única de identificação da conta, no formato uuid v4    | 36         |
| `card_key`              | uuidv4 | Chave única de identificação do cartão, no formato uuid v4   | 36         |

Request Body

```json
{
    "postal_code": "5425020",
    "street": "Rua Gilberto Sabino",
    "number": 215,
    "complement": "4 andar",
    "neighborhood": "Pinheiros",
    "city": "So Paulo",
    "state": "SP",
    "reference": "Terminal Pinheiros",
    "address_type": "commercial",
    "notes": ["obs1", "obs2"],
    "phones": [
        {"country_code": "55", "area_code": "19", "number": "983151110"},
        {"country_code": "55", "area_code": "16", "number": "992334318"},
    ],
}
```

### Request Body

### Objeto address

| Campo                     | Tipo   | Descrição                                          | Caracteres |
|---------------------------|--------|----------------------------------------------------|------------|
| `street` *                | string | Logradouro                                         | 100        |
| `number`                  | string | Número                                             | 10         |
| `neighborhood` *          | string | Bairro                                             | 100        |
| `postal_code` *           | string | CEP                                                | 8          |
| `city` *                  | string | Cidade                                             | 100        |
| `complement`              | string | Complemento                                        | 100        |
| `reference`               | string | Ponto de referência                                | 100        |
| `notes`                   | string array | Observações relacionadas ao endereço         | 100        |
| `phones`                  | object array | Telefones de contato | **[Objeto phone](#objeto-phone)**  |
| `state` *                 | string | Estado (UF)       | **[Enumeradores state](#enumeradores-state)** |
| `address_type` *          | string | Tipo de endereço  | **[Enumeradores address_type](#enumeradores-address_type)** |

:::caution Atenção!
O campo `number` é opcional. Endereços sem numeração podem ser enviados sem este campo.
:::

:::caution Atenção!
Podem ser enviados até dois telefones de contato e quatro observações. Caso não haja telefone de contato e/ou observações, esses campos (`phones` e `notes`) não devem ser enviados.
:::

### Objeto phone

| Campo                           | Tipo   | Descrição                                    | Caracteres |
|---------------------------------|--------|----------------------------------------------|------------|
| `international_dial_code` *     | string | Código DDI (Discagem Direta Internacional)   | 2          |
| `area_code` *                   | string | Código DDD (Discagem Direta à Distância)     | 2          |
| `number` *                      | string | Complemento                                  | 9          |

### Enumeradores address_type

| Enumerador         | Descrição                |
|--------------------|--------------------------|
| residential        | endereço residencial     |
| commercial         | endereço comercial       |
| other              | outros tipos de endereço |

### Enumeradores state

| Enumerador         | Descrição             |
|--------------------|-----------------------|
| AC                 | Acre                  |
| AL                 | Alagoas               |
| AM                 | Amazonas              |
| AP                 | Amapá                 |
| BA                 | Bahia                 |
| CE                 | Ceará                 |
| DF                 | Distrito federal      |
| ES                 | Espírito Santo        |
| GO                 | Goiás                 |
| MA                 | Maranhão              |
| MG                 | Minas Gerais          |
| MS                 | Mato Grosso do Sul    |
| MT                 | Mato Grosso           |
| PA                 | Pará                  |
| PB                 | Paraíba               |
| PE                 | Pernambuco            |
| PI                 | Piauí                 |
| PR                 | Paraná                |
| RJ                 | Rio de Janeiro        |
| RN                 | Rio Grande do Norte   |
| RO                 | Rondônia              |
| RR                 | Roraima               |
| RS                 | Rio Grande do Sul     |
| SC                 | Santa Catarina        |
| SE                 | Sergipe               |
| SP                 | São Paulo             |
| TO                 | Tocantins             |
| EX                 | Exceção               |

## Response

STATUS 200

Response Body

```json
{
  "card_key": "1e3183f0-1bac-4e59-81e8-2d89db224040",
  "tracking_code": "FD89B071241022",
  "address": {
    "city": "So Paulo",
    "notes": [
      "obs1",
      "obs2"
    ],
    "state": "SP",
    "number": 215,
    "phones": [
      {
        "number": "983151110",
        "area_code": "19",
        "country_code": "55"
      },
      {
        "number": "992334318",
        "area_code": "16",
        "country_code": "55"
      }
    ],
    "street": "Rua Gilberto Sabino",
    "reference": "Terminal Pinheiros",
    "complement": "4 andar",
    "postal_code": "5425020",
    "address_type": "commercial",
    "neighborhood": "Pinheiros"
  }
}

```

### Response Body Params

| Campo                   | Tipo   | Descrição                                                                                       | Caracteres |
|-------------------------|--------|-------------------------------------------------------------------------------------------------|------------|
| `card_key` *            | uuidv4 | Chave única de identificação do cartão, no formato uuid v4                                      | 36         |
| `tracking_code` *       | string | Código de rastreio da entrega do cartão                                                         | 14         |
| `address`               | object | Objeto do tipo `address`, semelhante ao que é enviado na requisição | **[Objeto address](#objeto-address)**  |

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 403                      | QIT000005            | Permission Validator Error               | Selected agent and person_key are different | Agente selecionado e person_key são diferentes |
| 400                      | TRACK000004          | Bad Request                 | Invalid status to change delivery address. | Status inválido para mudar o endereço de entrega. |
| 500                      | TRACK000007          | Internal Server Error      | Failed to update delivery address at delivery service provider. Please, try again later!   | Falha ao atualizar endereço de entrega junto à provedora de serviços de delivery. Por favor, tente novamente mais tarde! |
| 404                      | TRACK000012          | Not Found                                 | Tracking not found for the given 'card_key'. | Rastreio não encontrado para a 'card_key' fornecida. |

---

# Configuração do contactless

URL: /documentation/cartao_pos_pago/cartao/atualizar/atualizar_contactless

Ativar ou desativar a funcionalidade de pagamento por aproximação (contactless) para uso presencial.

Para ativar ou desativar o pagamento por aproximação do cartão, o status do cartão deve ser do tipo **Ativo** ou **Bloqueio temporário**. (Para obter informações sobre os tipos de status, consulte [aqui](../../credit_cards/status/atualiar_status_cartao#enumeradores-card_status))

## Request

ENDPOINT /wallet/ WALLET_KEY /card/ CARD_KEY /contactless
MÉTODO PATCH

### Path params
| Campo        | Tipo   | Descrição                         | Caracteres |
|--------------|--------|-----------------------------------|------------|
| `WALLET_KEY` * | string | Chave de identificação do carteira. | uuid       |    
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid       |

Request Body

```json
{
    "contactless_enabled": false
}
```

### Body params

| Campo                     | Tipo    | Descrição                         | Caracteres |
|---------------------------|---------|-----------------------------------|------------|
| `contactless_enabled`  *  | Boolean | Indica se está habilitado ou não. | true/false |

## Response

STATUS SUCCESS 200

Response Body

```json
{
    "card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",
    "status": "active",
    "account_key": "3571e292-3a83-4011-904d-20ee963022ef",
    "program_key": "6b6ebaac-043b-4390-8d62-e8098ec901e9",
    "type": "virtual",
    "card_name": "ecommerce",
    "printed_name": "Aurora Catarina",
    "brand": "visa",
    "last_four_digits": "5695",
    "created_at": "2023-02-20T19:28:16Z",
    "updated_at": "2023-02-22T19:28:16Z",
    "cvv_rotation_interval_hours": 72
}
```

### Erros

STATUS 4XX

Response Body

```json
{
  "title": "Bad Request",
  "description": "We're sorry, but the card could not be update contactless. Please try again later.",
  "translation": "Unexpected error update contactless card",
  "code": "CARD000026"
}
```

| Código    | Status code  | Descrição                      |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400          | Invalid Json schema.|
| CARD000011| 404          | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000023| 406          | The card type is invalid for this operation. Only plastic cards are allowed.|
| CARD000026| 400          | We're sorry, but the card could not be update contactless. Please try again later.|
| CARD000025| 406          | The status \{status\} is invalid for the operation.|

---

# Atualizar endereço de entrega

URL: /documentation/cartao_pos_pago/cartao/atualizar/atualizar_endereco_entrega

A atualização do endereço de entrega serve para corrigir o endereço caso alguma inconsistência seja encontrada ou a entrega seja mal sucedida três vezes.

## Request

ENDPOINT /wallet/ WALLET_KEY /card/ CARD_KEY /address
MÉTODO PATCH

### Path params
| Campo        | Tipo   | Descrição                         | Caracteres |
|--------------|--------|-----------------------------------|------------|
| `WALLET_KEY` * | string | Chave de identificação do carteira. | uuid       |    
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid       |

Request Body

```json
{
    "postal_code": "5425020",
    "street": "Rua Gilberto Sabino",
    "number": 215,
    "complement": "4 andar",
    "neighborhood": "Pinheiros",
    "city": "So Paulo",
    "state": "SP",
    "reference": "Terminal Pinheiros",
    "address_type": "commercial",
    "notes": ["obs1", "obs2"],
    "phones": [
        {"country_code": "55", "area_code": "19", "number": "983151110"},
        {"country_code": "55", "area_code": "16", "number": "992334318"},
    ],
}
```

### Request Body

### Objeto address

| Campo                     | Tipo   | Descrição                                          | Caracteres |
|---------------------------|--------|----------------------------------------------------|------------|
| `street` *                | string | Logradouro                                         | 100        |
| `number` *                | string | Número                                             | 10         |
| `neighborhood` *          | string | Bairro                                             | 100        |
| `postal_code` *           | string | CEP                                                | 8          |
| `city` *                  | string | Cidade                                             | 100        |
| `complement`              | string | Complemento                                        | 100        |
| `reference`               | string | Ponto de referência                                | 100        |
| `notes`                   | string array | Observações relacionadas ao endereço         | 100        |
| `phones`                  | object array | Telefones de contato | **[Objeto phone](#objeto-phone)**  |
| `state` *                 | string | Estado (UF)       | **[Enumeradores state](#enumeradores-state)** |
| `address_type` *          | string | Tipo de endereço  | **[Enumeradores address_type](#enumeradores-address_type)** |

:::caution Atenção!
Podem ser enviados até dois telefones de contato e quatro observações. Caso não haja telefone de contato e/ou observações, esses campos (`phones` e `notes`) não devem ser enviados.
:::

### Objeto phone

| Campo                           | Tipo   | Descrição                                    | Caracteres |
|---------------------------------|--------|----------------------------------------------|------------|
| `international_dial_code` *     | string | Código DDI (Discagem Direta Internacional)   | 2          |
| `area_code` *                   | string | Código DDD (Discagem Direta à Distância)     | 2          |
| `number` *                      | string | Complemento                                  | 9          |

### Enumeradores address_type

| Enumerador         | Descrição                |
|--------------------|--------------------------|
| residential        | endereço residencial     |
| commercial         | endereço comercial       |
| other              | outros tipos de endereço |

### Enumeradores state

| Enumerador         | Descrição             |
|--------------------|-----------------------|
| AC                 | Acre                  |
| AL                 | Alagoas               |
| AM                 | Amazonas              |
| AP                 | Amapá                 |
| BA                 | Bahia                 |
| CE                 | Ceará                 |
| DF                 | Distrito federal      |
| ES                 | Espírito Santo        |
| GO                 | Goiás                 |
| MA                 | Maranhão              |
| MG                 | Minas Gerais          |
| MS                 | Mato Grosso do Sul    |
| MT                 | Mato Grosso           |
| PA                 | Pará                  |
| PB                 | Paraíba               |
| PE                 | Pernambuco            |
| PI                 | Piauí                 |
| PR                 | Paraná                |
| RJ                 | Rio de Janeiro        |
| RN                 | Rio Grande do Norte   |
| RO                 | Rondônia              |
| RR                 | Roraima               |
| RS                 | Rio Grande do Sul     |
| SC                 | Santa Catarina        |
| SE                 | Sergipe               |
| SP                 | São Paulo             |
| TO                 | Tocantins             |
| EX                 | Exceção               |

## Response

STATUS 200

Response Body

```json
{
  "card_key": "1e3183f0-1bac-4e59-81e8-2d89db224040",
  "tracking_code": "FD89B071241022",
  "address": {
    "city": "So Paulo",
    "notes": [
      "obs1",
      "obs2"
    ],
    "state": "SP",
    "number": 215,
    "phones": [
      {
        "number": "983151110",
        "area_code": "19",
        "country_code": "55"
      },
      {
        "number": "992334318",
        "area_code": "16",
        "country_code": "55"
      }
    ],
    "street": "Rua Gilberto Sabino",
    "reference": "Terminal Pinheiros",
    "complement": "4 andar",
    "postal_code": "5425020",
    "address_type": "commercial",
    "neighborhood": "Pinheiros"
  }
}

```

### Response Body Params

| Campo                   | Tipo   | Descrição                                                                                       | Caracteres |
|-------------------------|--------|-------------------------------------------------------------------------------------------------|------------|
| `card_key` *            | uuidv4 | Chave única de identificação do cartão, no formato uuid v4                                      | 36         |
| `tracking_code` *       | string | Código de rastreio da entrega do cartão                                                         | 14         |
| `address`               | object | Objeto do tipo `address`, semelhante ao que é enviado na requisição | **[Objeto address](#objeto-address)**  |

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 403                      | QIT000005            | Permission Validator Error               | Selected agent and person_key are different | Agente selecionado e person_key são diferentes |
| 400                      | TRACK000004          | Bad Request                 | Invalid status to change delivery address. | Status inválido para mudar o endereço de entrega. |
| 500                      | TRACK000007          | Internal Server Error      | Failed to update delivery address at delivery service provider. Please, try again later!   | Falha ao atualizar endereço de entrega junto à provedora de serviços de delivery. Por favor, tente novamente mais tarde! |
| 404                      | TRACK000012          | Not Found                                 | Tracking not found for the given 'card_key'. | Rastreio não encontrado para a 'card_key' fornecida. |

---

# Alterar senha cartão físico

URL: /documentation/cartao_pos_pago/cartao/atualizar/atualizar_senha

Todo cartão físico tem uma senha para autorizar a transação, e ela pode ser atualizada caso necessária.

Para atualizar a senha do cartão o status tem que ter o tipo **Active** ou **Temporary block**.(Para conhecer sobre status consulte [aqui](../../credit_cards/status/atualiar_status_cartao#enumeradores-card_status))

:::caution Atenção
Por motivos de segurança, cuidado ao atualizar uma senha, pois ela pode impactar na autorização de um cartão.

Crie regras para melhorar a segurança da autorização da senha, como não utilizar data de aniversário, números repetidos (ex: 3333).
:::

## Request

ENDPOINT /wallet/ WALLET_KEY /card/ CARD_KEY /password
MÉTODO PATCH

### Path params
| Campo        | Tipo   | Descrição                         | Caracteres |
|--------------|--------|-----------------------------------|------------| 
| `WALLET_KEY` * | string | Chave de identificação do carteira. | uuid       |   
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid       |

Request Body

```json
{
    "pin": "2143"
}
```

  ### Body params

| Campo     | Tipo   | Descrição                                     | Caracteres |
|-----------|--------|-----------------------------------------------|------------|
| `pin`  *  | string | Senha do cartão para autorizar uma transação. | 4          |

## Response

STATUS SUCCESS 200

Response Body

```json
{
    "card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",
    "status": "active",
    "account_key": "3571e292-3a83-4011-904d-20ee963022ef",
    "program_key": "6b6ebaac-043b-4390-8d62-e8098ec901e9",
    "type": "virtual",
    "card_name": "ecommerce",
    "printed_name": "Aurora Catarina",
    "brand": "visa",
    "last_four_digits": "5695",
    "created_at": "2023-02-20T19:28:16Z",
    "updated_at": "2023-02-22T19:28:16Z",
    "cvv_rotation_interval_hours": 72
}
```

### Erros

STATUS 4XX

Response Body

```json
{
  "title": "Bad Request",
  "description": "We're sorry, but the card could not be update password. Please try again later.",
  "translation": "Unexpected error update password card",
  "code": "CARD000024"
}
```

| Código    | Status code  | Descrição                      |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400          | Invalid Json schema.|
| CARD000011| 404          | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000023| 406          | The card type is invalid for this operation. Only plastic cards are allowed.|
| CARD000024| 400          | We're sorry, but the card could not be update password. Please try again later.|
| CARD000025| 406          | The status \{status\} is invalid for the operation.|

---

# Simulação de cenários

URL: /documentation/cartao_pos_pago/cartao/atualizar/simulacao_de_cenarios

Esta página descreve como simular a atualização do status de rastreamento de cartões pós-pagos para testar o fluxo de atualizações de entrega. Essas simulações são úteis para homologação e testes de integração.

:::info Informação

Essas requisições simulam atualizações de status de rastreamento e retornam o status HTTP com os dados atualizados do rastreamento.

:::

## 1 - Simulação de atualização de status de rastreamento

Simula a atualização do status de rastreamento de um cartão pós-pago, permitindo transicionar entre diferentes estados do processo de entrega. A atualização cria um novo evento no histórico de rastreamento.

ENDPOINT /mock/wallet/ WALLET_KEY /card/ CARD_KEY /tracking

MÉTODO PATCH

### Path Parameters

| Campo                        | Tipo   | Descrição                                    | Caracteres |
|------------------------------|--------|----------------------------------------------|------------|
| `wallet_key` *               | string | Chave única da carteira no formato UUID v4  | 36         |
| `card_key` *                 | string | Chave única do cartão no formato UUID v4     | 36         |

Request Body

```json
{
  "status": "posted",
  "place": "São Paulo - SP",
  "description": "Postado - logística iniciada",
  "reason": "Processamento concluído"
}
```

### Objeto Request Body

| Campo                                    | Tipo    | Descrição                                                                          | Máx. Caract. |
|------------------------------------------|---------|------------------------------------------------------------------------------------|--------------|
| `status` *                               | string  | Novo status do rastreamento                                                        | **[Enumeradores status](#enumeradores-status)** |
| `place` *                                | string  | Local onde ocorreu o evento                                                       | 100          |
| `description` *                          | string  | Descrição do evento de rastreamento                                               | 255          |
| `reason`                                 | string  | Motivo adicional do evento (opcional)                                             | 100          |

### Enumeradores status

| Enumerador                  | Descrição                                                                         |
|-----------------------------|-----------------------------------------------------------------------------------|
| `pending`                   | Pendente - aguardando processamento inicial                                      |
| `posted`                    | Postado - logística iniciada                                                     |
| `prepared`                  | Preparado - cartão preparado para transferência                                  |
| `in_transfer`               | Em transferência - cartão em trânsito                                            |
| `in_delivery_unit`          | Na unidade de entrega - cartão chegou à unidade de distribuição                  |
| `on_route`                  | Em rota - cartão saiu para entrega                                               |
| `attempt_failed`            | Tentativa falhou - tentativa de entrega não foi bem-sucedida                    |
| `awaiting_withdrawal`       | Aguardando retirada - cartão disponível para retirada                            |
| `returning`                 | Retornando - cartão em processo de devolução                                     |
| `delivered`                 | Entregue - cartão foi entregue com sucesso                                       |
| `returned`                  | Devolvido - cartão foi devolvido                                                 |
| `canceled`                  | Cancelado - rastreamento foi cancelado                                           |
| `failed`                    | Falhou - falha no processo de entrega                                            |
| `resend`                    | Reenvio - cartão será reenviado                                                  |
| `redispatch_error`          | Erro no redespacho - erro ao redespachar o cartão                                |
| `waiting_for_address_update`| Aguardando atualização de endereço - aguardando confirmação de endereço          |

### Response

STATUS 204

Response Body

```json
{}
```

:::tip Comportamento
- A simulação atualiza o status do rastreamento e cria um novo evento no histórico
- As transições de status seguem uma ordem específica e validações são aplicadas:
  - Não é possível retroceder para status anteriores (exceto status especiais)
  - Não é possível alterar status a partir de status finais (`delivered`, `returned`, `canceled`, `failed`)
  - Não é possível transicionar de `waiting_for_address_update` para outro status que não seja `pending`
  - Não é possível transicionar para `waiting_for_address_update` a partir de status finais
  - Status especiais (`attempt_failed`, `resend`, `redispatch_error`) podem ser utilizados em qualquer momento após o status inicial
- O campo `reason` é opcional e, quando fornecido, é concatenado à descrição do evento
:::

---

# Buscar cartão por chave

URL: /documentation/cartao_pos_pago/cartao/busca/buscar_cartao_por_chave

## Request

ENDPOINT /wallet/ WALLET_KEY /card/ CARD_KEY
MÉTODO GET

### Path params

| Campo        | Tipo   | Descrição                         | Caracteres |
|--------------|--------|-----------------------------------|------------| 
| `WALLET_KEY` * | string | Chave de identificação do carteira. | uuid       |    
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid       |
 

## Response

STATUS 200

Response Body

```json
{
    "card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",
    "status": "active",
    "account_key": "3571e292-3a83-4011-904d-20ee963022ef",
    "program_key": "6b6ebaac-043b-4390-8d62-e8098ec901e9",
    "type": "virtual",
    "card_name": "ecommerce",
    "printed_name": "Aurora Catarina",
    "brand": "visa",
    "last_four_digits": "5695",
    "created_at": "2023-02-20T19:28:16Z",
    "updated_at": "2023-02-22T19:28:16Z",
    "cvv_rotation_interval_hours": 72
}
```

### Erros

STATUS 4XX

Response Body

```json
{
  "title": "Not Found",
  "description": "It was not possible to fetch the Card for the card_key f6bf148a-30b6-4a07-8c5b-3383a98ea32b.",
  "translation": "Not Found Card",
  "code": "CARD000011"
}
```

| Code      | Status code  | Descrição                      |
|:---------:|:------------:|:-------------------------------|
| CARD000011| 404          | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000016| 400          | We're sorry, but the card could not be fetch. Please try again later.|

---

# Buscar entrega por chave de cartão

URL: /documentation/cartao_pos_pago/cartao/busca/buscar_dados_entrega_por_chave

## Request

ENDPOINT /wallet/ WALLET_KEY /card/ CARD_KEY /tracking
MÉTODO GET

### Path params
| Campo        | Tipo   | Descrição                         | Caracteres |
|--------------|--------|-----------------------------------|------------|
| `WALLET_KEY` * | string | Chave de identificação do carteira. | uuid       |    
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid       |

## Response

STATUS 200

Response Body

```json
{
  "card_key": "92b4e2bd-4a6f-4c56-859e-17c729e1f0c8",
  "tracking_code": "4F68A72B902317",
  "status": "posted",
  "recipient": "João Silva",
  "address": {
    "zip_code": "1234567",
    "street": "Rua das Flores",
    "number": 123,
    "complement": "Bloco A",
    "neighborhood": "Centro",
    "city": "Cidade Exemplo",
    "state": "SP"
  },
  "event": [
    {
      "created_at": "2024-02-27T08:30:00Z",
      "old_status": "pending",
      "new_status": "posted",
      "description": "Pedido recebido e postado",
      "place": "SAO PAULO"
    }
  ]
}
```

### Enumeradores DeliveryStatus

| Enumerador         | Tradução            |
|--------------------|---------------------|
| pending            | Pendente            |
| posted             | Postado             |
| prepared           | Preparado           |
| in_transfer        | Em transferência    |
| in_delivery_unit   | Na unidade de entrega |
| on_route           | Em rota             |
| attempt_failed     | Tentativa falhou    |
| awaiting_withdrawal| Aguardando retirada |
| returning          | Retornando          |
| delivered          | Entregue            |
| returned           | Devolvido           |
| canceled           | Cancelado           |
| failed             | Falhou              |
| resend             | Reenviado           |

### Erros

STATUS 4XX

Response Body

```json
{
  "title": "Not Found",
  "description": "It was not possible to fetch the Tracking for the card_key f6bf148a-30b6-4a07-8c5b-3383a98ea32b.",
  "translation": "Not Found",
  "code": "TRACK000011"
}
```

| Code      | Status code  | Descrição                      |
|:---------:|:------------:|:-------------------------------|
| TRACK000011| 404          | It was not possible to fetch the Tracking for the card_key \{card_key\}.|
| TRACK000016| 400          | We're sorry, but the tracking could not be fetch. Please try again later.|

---

# Buscar dados PCI

URL: /documentation/cartao_pos_pago/cartao/busca/buscar_dados_pci

## Request

ENDPOINT /wallet/ WALLET_KEY /card/ CARD_KEY /pci
MÉTODO GET

### Path params

| Campo        | Tipo   | Descrição                         | Caracteres |
|--------------|--------|-----------------------------------|------------|  
| `WALLET_KEY` * | string | Chave de identificação do carteira. | uuid       |   
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid       |

## Response

STATUS 200

Response Body

```json
{
    "printed_name": "Aurora Catarina",
    "valid_until": "2023-02-20T10:04:12Z",
    "expiration_date": "03/24",
    "card_number": "4539347744299311",
    "cvv": "713"
}
```

### Erros

STATUS 4XX

Response Body

```json
{
  "title": "Not Found",
  "description": "It was not possible to fetch the Card for the card_key f6bf148a-30b6-4a07-8c5b-3383a98ea32b.",
  "translation": "Not Found Card",
  "code": "CARD000011"
}
```

| Code      | Status code  | Descrição                      |
|:---------:|:------------:|:-------------------------------|
| CARD000011| 404          | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000012| 400          | It was not possible to fetch PCI for the card_key \{card_key\}.|

---

# Buscar Senha PCI

URL: /documentation/cartao_pos_pago/cartao/busca/buscar_senha

## Request

ENDPOINT /wallet/ WALLET_KEY /card/ CARD_KEY /pci/password
MÉTODO GET

### Path params

| Campo        | Tipo   | Descrição                         | Caracteres |
|--------------|--------|-----------------------------------|------------| 
| `WALLET_KEY` * | string | Chave de identificação do carteira. | uuid       |    
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid       |

## Response

STATUS 200

Response Body

```json
{
    "pin": "1234"
}
```

### Erros

STATUS 4XX

Response Body

```json
{
  "title": "Bad Request",
  "description": "It was not possible to fetch PCI for the card_key f6bf148a-30b6-4a07-8c5b-3383a98ea32b.",
  "translation": "Fetch PCI failed",
  "code": "CARD000012"
}
```

| Code      | Status code  | Descrição                      |
|:---------:|:------------:|:-------------------------------|
| CARD000011| 404          | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000012| 400          | It was not possible to fetch PCI for the card_key \{card_key\}.|

---

# Ativar cartão físico

URL: /documentation/cartao_pos_pago/cartao/status/ativar_cartao

Todo cartão físico precisa ser ativado através de um código de ativação que é enviado junto do cartão físico, ao portador.

Ao receber o cartão por correspondência, o portador do cartão precisa informar ao parceiro da QI, para que o parceiro realize a ativação do cartão através deste endpoint.

:::caution Atenção
Por motivos de segurança, não existe a possibilidade de consulta do código de ativação via API por parte do parceiro.

Este código é enviado, exclusivamente ao portador do cartão, no momento da postagem do cartão físico.

Para realizar testes de integração, esse código é devolvido em ambiente de sandobox ao consultar um cartão.
:::

## Request

ENDPOINT /wallet/ WALLET_KEY /card/ CARD_KEY /activate
MÉTODO PATCH

### Path params
| Campo        | Tipo   | Descrição                         | Caracteres |
|--------------|--------|-----------------------------------|------------| 
| `WALLET_KEY` * | string | Chave de identificação do carteira. | uuid       |  
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid       |

Request Body

```json
{
    "code": "253615"
}
```

  ### Body params

| Campo     | Tipo   | Descrição                     | Caracteres |
|-----------|--------|-------------------------------|------------|
| `code`  * | string | Código de ativação do cartão. | 6          |

## Response

STATUS 200

Response Body

```json
{
    "card_key": "05fd3654-1f5d-479d-ade5-64239fdf214d",
    "status": "active",
    "account_key": "3571e292-3a83-4011-904d-20ee963022ef",
    "program_key": "6b6ebaac-043b-4390-8d62-e8098ec901e9",
    "type": "virtual",
    "card_name": "ecommerce",
    "printed_name": "Aurora Catarina",
    "brand": "visa",
    "last_four_digits": "5695",
    "created_at": "2023-02-20T19:28:16Z",
    "updated_at": "2023-02-22T19:28:16Z",
    "cvv_rotation_interval_hours": 72
}
```

### Erros

STATUS 4XX

Response Body

```json
{
  "title": "Not Acceptable",
  "description": "Invalid activation code [1254].",
  "translation": "Unable to activate card",
  "code": "CARD000020"
}
```

| Code      | Status code  | Description                    |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400          | Invalid Json schema.|
| CARD000011| 404          | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000017| 406          | The activation operation is not valid for the current card status [\{card_status\}].|
| CARD000018| 400          | We're sorry, but the card could not be activate. Please try again later.|
| CARD000020| 406          | Invalid activation code [\{code\}].|
| CARD000023| 406          | The card type is invalid for this operation. Only plastic cards are allowed.|

---

# Atualizar status

URL: /documentation/cartao_pos_pago/cartao/status/atualizar_status_cartao

## Request

ENDPOINT /wallet/ WALLET_KEY /card/ CARD_KEY
MÉTODO PATCH

### Path params

| Campo        | Tipo   | Descrição                         | Caracteres |
|--------------|--------|-----------------------------------|------------| 
| `WALLET_KEY` * | string | Chave de identificação do carteira. | uuid       |   
| `CARD_KEY` * | string | Chave de identificação do cartão. | uuid       |

Request Body

```json
{
    "status": "blocked"
}
```

  ### Body params

| Campo       | Tipo   | Descrição         | Caracteres                                    |
|-------------|--------|-------------------|-----------------------------------------------|
| `status`  * | string | Status do cartão. | **[Enumeradores](#enumeradores-card_status)** |

### Enumeradores card_status
| Enumerador | Tradução            | Tipo            |
|------------|---------------------|-----------------|
| created    | Criação solicitada  | Initial         |
| building   | Em construção       | Initial         |
| active     | Apto a transacionar | Active          |
| embossing  | Em produção         | Temporary block |
| blocked    | Bloqueado           | Temporary block |
| warning    | Com suspeita        | Temporary block |
| pending    | Pendente            | Temporary block |
| lost       | Perdido             | Terminated      |
| robbed     | Roubado             | Terminated      |
| fraud      | Fraudado            | Terminated      |
| canceled   | Cancelado           | Terminated      |
| theft      | Furtado             | Terminated      |

### Erros

STATUS 4XX

Response Body

```json
{
  "title": "Not Acceptable",
  "description": "The operation is not valid for the current status of the card [canceled]",
  "translation": "Unable to transition",
  "code": "CARD000014"
}
```

| Code      | Status code  | Descrição                      |
|:---------:|:------------:|:-------------------------------|
| QIT000001 | 400          | Invalid Json schema.|
| CARD000011| 404          | It was not possible to fetch the Card for the card_key \{card_key\}.|
| CARD000013| 406          | Unable to transition from \{old_status\} to \{new_status\}.|
| CARD000014| 406          | The operation is not valid for the current status of the card [\{card_status\}].|
| CARD000015| 400          | We're sorry, but the card could not be update. Please try again later|

### Webhook

WEBHOOK_TYPE baas.pospaid_card.card

Webhook Body

```json
{
    "webhook_type": "baas.pospaid_card.card",
    "event_datetime": "2023-07-25T12:00:00.000Z",
    "data": {
        "card_key": "9bd93e97-bb6d-410f-8981-06b2765f12a1",
        "type": "virtual",
        "status": "active",
        "old_status": "created"
    }
}
```

---

# Alteração de Limite de Carteira

URL: /documentation/cartao_pos_pago/faturas/carteira/alteracao_de_limite

A alteração de limite de carteira permite alterar o valor do limite de crédito pós-pago de uma carteira existente.

## Request

ENDPOINT /wallet/ WALLET_KEY /wallet_limit/ WALLET_LIMIT_KEY
MÉTODO PATCH

### Path Parameters

| Campo                        | Tipo   | Descrição                                    | Caracteres |
|------------------------------|--------|----------------------------------------------|------------|
| `wallet_key` *               | uuidv4 | Chave única da carteira no formato UUID v4  | 36         |
| `wallet_limit_key` *         | uuidv4 | Chave única do limite de carteira no formato UUID v4 | 36 |

Request Body

```json
{
  "limit_amount": 10000.00
}
```

### Request Body Params

| Campo                        | Tipo    | Descrição                                                                          | Caracteres |
|------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `limit_amount` *             | float   | Novo valor do limite de crédito pós-pago                                          | -          |

:::info Observação
- O novo valor do limite deve ser maior ou igual ao limite utilizado (`used_limit`)
- Apenas limites do tipo `postpaid_credit_limit` podem ser atualizados
- Apenas carteiras do tipo `default` podem ter seus limites atualizados
- A atualização do limite também atualiza o limite no serviço de cartões
:::

## Response

STATUS 200

Response Body: Limite de carteira atualizado

```json
{
  "wallet_limit_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "limit_type": "postpaid_credit_limit",
  "limit_amount": 10000.00,
  "used_limit": 2500.00
}
```

### Response Body Params

| Campo                            | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `wallet_limit_key` *             | uuidv4  | Chave única de identificação do limite atualizado no formato UUID v4              | 36         |
| `limit_type` *                   | string  | Tipo do limite atualizado                                                          | **[Enumeradores limit_type](#enumeradores-limit_type)** |
| `limit_amount` *                 | float   | Novo valor do limite de crédito pós-pago após a atualização                        | -          |
| `used_limit` *                   | float   | Valor do limite utilizado no momento da atualização                                 | -          |

### Enumeradores limit_type

| Enumerador              | Descrição                               |
|-------------------------|-----------------------------------------|
| postpaid_credit_limit   | Limite de crédito pós-pago             |

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | CIN000110            | Bad Request                                        | New limit amount is less than used limit                                                                                 | Novo valor do limite é menor que o valor utilizado                                                                     |
| 400                      | CIN000111            | Bad Request                                        | Error while updating postpaid wallet limit in card service, try again in a few minutes.                                  | Erro ao atualizar limite de carteira pós-pago no serviço de cartão, tente novamente em alguns minutos.                |
| 400                      | CIN000112            | Bad Request                                        | Requester postpaid limit exceeded for this client                                                                        | Limite das carteiras pós-pagas do cliente excedido                                                                     |
| 403                      | CIN000108            | Forbidden                                          | Wallet type payroll is not allowed for this operation                                                              | Tipo de carteira payroll não é permitido para esta operação                                                       |
| 403                      | CIN000109            | Forbidden                                          | Wallet limit type payroll_withdraw_limit is not allowed for this operation                                                  | Tipo de limite de carteira payroll_withdraw_limit não é permitido para esta operação                                       |
| 404                      | CIN000007            | Wallet not Found                                   | Wallet with key: e91d68d4-2904-4f9d-a6ef-50c82c34531e was not found                                                                              | Carteira com a chave: e91d68d4-2904-4f9d-a6ef-50c82c34531e não foi encontrado                                                                 |
| 404                      | CIN000107            | Not Found                                          | Wallet limit not found                                                                                                    | Limite de carteira não foi encontrado                                                                                   |

---

# Buscar Entrada de Carteira por Chave

URL: /documentation/cartao_pos_pago/faturas/carteira/consulta_entrada_por_chave

A busca de entrada de carteira por chave retornará os detalhes completos de uma entrada específica, incluindo todos os itens da fatura relacionados.

## Request

ENDPOINT /wallet/ WALLET_KEY /wallet_entry/ WALLET_ENTRY_KEY
MÉTODO GET

### Path Parameters

| Campo             | Tipo   | Descrição                                    | Caracteres |
|-------------------|--------|----------------------------------------------|------------|
| `wallet_key`      | uuidv4 | Chave única da carteira no formato UUID v4  | 36         |
| `wallet_entry_key`| uuidv4 | Chave única da entrada no formato UUID v4    | 36         |

## Response

STATUS 200

Response Body: Detalhes da entrada de carteira

```json
{
  "wallet_entry_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "wallet_entry_amount": 150.00,
  "wallet_entry_settlement_key": "cc8fb19b-d1e4-4ce6-ad4c-61e0609a8f8d",
  "wallet_entry_type": "revolving_credit",
  "wallet_entry_status": "concluded",
  "invoice_items": [
    {
      "invoice_item_key": "3571e292-3a83-4011-904d-20ee963022ef",
      "invoice_key": "f2cad6b4-2a68-9572-99a7-2849c8d6ecf8",
      "wallet_entry_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "payment_instrument_entry_key": null,
      "installment_number": 1,
      "invoice_description": "Crédito rotativo - Taxa de juros",
      "amount": 150.00,
      "used_limit": 150.00,
      "invoice_item_status": "concluded",
      "invoice_item_due_date": "2024-02-15",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "created_at": "2024-01-15T10:30:00Z"
}
```

### Response Body Params

| Campo                        | Tipo         | Descrição                             | Caracteres                                  |
|------------------------------|--------------|---------------------------------------|---------------------------------------------|
| `wallet_entry_key` *         | uuidv4       | Chave única de identificação da entrada no formato uuid v4 | 36         |
| `wallet_entry_amount` *      | float  | Valor da entrada                                                                  | -          |
| `wallet_entry_settlement_key` * | string    | Chave de liquidação da entrada        | -          |
| `wallet_entry_type` *        | string       | Tipo da entrada da carteira           | **[Enumeradores wallet_entry_type](#enumeradores-wallet_entry_type)** |
| `wallet_entry_status` *      | string       | Status da entrada da carteira          | **[Enumeradores wallet_entry_status](#enumeradores-wallet_entry_status)** |
| `invoice_items` *            | object array | Itens da fatura relacionados          | **[Objeto invoice_item](#objeto-invoice_item)** |
| `created_at` *               | string       | Data de criação (formato ISO 8601 UTC) | -          |

### Objeto invoice_item

| Campo                              | Tipo    | Descrição                                                                         | Caracteres |
|------------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| `invoice_item_key` *               | uuidv4  | Chave única de identificação do item da fatura no formato uuid v4                | 36         |
| `invoice_key` *                    | uuidv4  | Chave única de identificação da fatura no formato uuid v4                        | 36         |
| `wallet_entry_key`                 | uuidv4  | Chave única de identificação da entrada da carteira no formato uuid v4          | 36         |
| `payment_instrument_entry_key`     | uuidv4  | Chave única de identificação da entrada do instrumento de pagamento no formato uuid v4 | 36 |
| `installment_number` *             | integer | Número da parcela                                                                 | -          |
| `invoice_description` *            | string  | Descrição do item da fatura                                                       | -          |
| `amount` *                         | float  | Valor do item                                                                     | -          |
| `used_limit` *                     | float  | Limite utilizado                                                                 | -          |
| `invoice_item_status` *            | string  | Status do item da fatura                                                          | **[Enumeradores invoice_item_status](#enumeradores-invoice_item_status)** |
| `invoice_item_due_date` *          | string  | Data de vencimento do item (formato YYYY-MM-DD)                                  | 10         |
| `created_at` *                     | string  | Data de criação (formato ISO 8601 UTC)                                           | -          |

### Enumeradores wallet_entry_type

| Enumerador        | Descrição                                                                         |
|-------------------|-----------------------------------------------------------------------------------|
| revolving_credit  | Crédito rotativo                                                                  |
| payroll_withdraw  | Saque de folha                                                                    |
| payroll_overdue   | Atraso de folha                                                                   |

:::info Tipos de Entrada de Carteira
- **`revolving_credit`**: Valores de crédito disponibilizados para o cliente
- **`payroll_withdraw`**: Dívida gerada pelo saque do limite e que vai ser descontada todo mês do INSS
- **`payroll_overdue`**: Dívida gerada pelo não pagamento da fatura e também vai ser descontada todo mês do INSS
:::

### Enumeradores wallet_entry_status

| Enumerador | Descrição                               |
|------------|-----------------------------------------|
| concluded     | Entrada concluída |

### Enumeradores invoice_item_status

| Enumerador | Descrição                               |
|------------|-----------------------------------------|
| concluded    | Item concluído   |
| canceled  | Item cancelado               |

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 404                      | CIN000007            | Wallet not Found                                   | Wallet with key: abeca0d0-a09d-4b3b-a495-40b553422ced was not found                                                   | Carteira com a chave: abeca0d0-a09d-4b3b-a495-40b553422ced não foi encontrado                                         |
| 404                      | CIN000078            | Not Found                                          | Wallet entry with key: 8cb70dea-9fb0-4a68-9572-99a72849c8d6 was not found                                             | Dívida da carteira com a chave: 8cb70dea-9fb0-4a68-9572-99a72849c8d6 não foi encontrado                                |

---

# Consulta de Carteira por Chave

URL: /documentation/cartao_pos_pago/faturas/carteira/consulta_por_chave

A consulta de carteira por chave retorna os detalhes completos de uma carteira específica, incluindo suas configurações de fatura e limites de crédito.

## Request

ENDPOINT /wallet/ WALLET_KEY
MÉTODO GET

### Path Parameters

| Campo                     | Tipo   | Descrição                                    | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `wallet_key`              | uuidv4 | Chave única de identificação da carteira     | 36         |

## Response

STATUS 200

Response Body: Detalhes da carteira

```json
{
  "request_control_key": "f7947b9d-9be3-49d8-aca2-4b3249e5fa65",
  "wallet_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "owner_person_key": "ecf87b4b-fa6e-49c0-a7f0-f2cad6b42d79",
  "owner_document_number": "12345678901",
  "invoice_configuration": {
    "closing_date_configuration": {
      "type": "fixed",
      "fixed_day": 15
    },
    "due_date_configuration": {
      "type": "fixed",
      "fixed_day": 20,
      "offset_months": 0
    },
    "invoice_payment_type": "bank_slip",
    "interest_base": "calendar_days",
    "monthly_interest_percentage": 2.0,
    "fine_percentage": 2.0
  },
  "wallet_status": "active",
  "wallet_type": "default",
  "wallet_limits": [
    {
      "wallet_limit_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "limit_type": "postpaid_credit_limit",
      "limit_amount": 5000.00,
      "used_limit": 0.00
    }
  ],
  "created_at": "2024-01-15T10:30:00Z"
}
```

### Response Body Params

| Campo                                    | Tipo    | Descrição                                                                          | Caracteres |
|------------------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `wallet_key` *                           | string  | Chave única de identificação da carteira                                          | 36         |
| `owner_person_key` *                     | string  | Chave de identificação do proprietário da carteira                                | 36      |
| `owner_document_number` *                | string  | CPF/CNPJ do proprietário da carteira                                              | 11-14      |
| `invoice_configuration` *                | object  | Configurações de fatura da carteira                                                | **[Objeto invoice_configuration](#objeto-invoice_configuration)**          |
| `wallet_status` *                         | string  | Status atual da carteira                                                           | **[Enumeradores wallet_status](#enumeradores-wallet_status)**          |
| `wallet_type` *                           | string  | Tipo da carteira                                                                   | **[Enumeradores wallet_type](#enumeradores-wallet_type)**          |
| `wallet_limits` *                         | array   | Lista de limites da carteira                                                       | **[Objeto wallet_limits](#objeto-wallet_limits)**          |
| `created_at` *                            | string  | Data de criação (formato ISO 8601 UTC)                                            | -          |

### Objeto invoice_configuration

| Campo                                    | Tipo    | Descrição                                                                          | Caracteres |
|------------------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `closing_date_configuration` *           | object  | Configuração da data de fechamento da fatura                                      | **[Objeto closing_date_configuration](#objeto-closing_date_configuration)** |
| `due_date_configuration` *               | object  | Configuração da data de vencimento da fatura                                      | **[Objeto due_date_configuration](#objeto-due_date_configuration)** |
| `invoice_payment_type` *                 | string  | Tipo de pagamento da fatura                                                       | **[Enumeradores invoice_payment_type](#enumeradores-invoice_payment_type)** |
| `interest_base`                         | string  | Base de cálculo dos juros                                                         | **[Enumeradores interest_base](#enumeradores-interest_base)** |
| `monthly_interest_percentage`           | float  | Percentual de juros mensais por atraso (0-100)                                    | -          |
| `fine_percentage`                       | float  | Percentual de multa por atraso (0-100)                                            | -          |
:::info
Nota Carteiras do tipo `payroll` não possuem os campos `interest_base`, `monthly_interest_percentage` e `fine_percentage`.
:::

### Objeto closing_date_configuration

#### Configuração Fixa (`type: "fixed"`)

| Campo                     | Tipo    | Descrição                                    | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `type` *                  | string  | Tipo de configuração (deve ser "fixed")      | -          |
| `fixed_day` *             | integer | Dia fixo do mês para fechamento (1-27)       | -          |

#### Configuração Baseada em Regras (`type: "rule_based"`)

| Campo                     | Tipo    | Descrição                                    | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `type` *                  | string  | Tipo de configuração (deve ser "rule_based") | -          |
| `rule` *                  | object  | Regra para cálculo da data                     | **[Objeto rule (closing_date_configuration)](#objeto-rule-closing_date_configuration)**          |

### Objeto rule (closing_date_configuration)

| Campo                     | Tipo    | Descrição                                    | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `day_of_week` *          | string  | Dia da semana                                | **[Enumeradores day_of_week](#enumeradores-day_of_week)**          |
| `occurrence` *            | string  | Ocorrência do dia no mês                      | **[Enumeradores occurrence](#enumeradores-occurrence)**          |
| `fallback_strategy` *     | string  | Estratégia para dias não úteis                | **[Enumeradores fallback_strategy](#enumeradores-fallback_strategy)**          |

### Objeto due_date_configuration

#### Configuração Fixa (`type: "fixed"`)

| Campo                     | Tipo    | Descrição                                    | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `type` *                  | string  | Tipo de configuração (deve ser "fixed")      | -          |
| `offset_months` *         | integer | Meses de offset a partir do fechamento       | -          |
| `fixed_day` *             | integer | Dia fixo do mês para vencimento (2-27)       | -          |

#### Configuração Baseada em Regras (`type: "rule_based"`)

| Campo                     | Tipo    | Descrição                                    | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `type` *                  | string  | Tipo de configuração (deve ser "rule_based") | -          |
| `offset_months` *         | integer | Meses de offset a partir do fechamento       | -          |
| `rule` *                  | object  | Regra para cálculo da data                     | **[Objeto rule (due_date_configuration)](#objeto-rule-due_date_configuration)**          |

### Objeto rule (due_date_configuration)

| Campo                     | Tipo    | Descrição                                    | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `day_of_week` *          | string  | Dia da semana                                | **[Enumeradores day_of_week](#enumeradores-day_of_week)**          |
| `occurrence` *            | string  | Ocorrência do dia no mês                      | **[Enumeradores occurrence](#enumeradores-occurrence)**          |
| `fallback_strategy` *     | string  | Estratégia para dias não úteis                | **[Enumeradores fallback_strategy](#enumeradores-fallback_strategy)**          |

### Objeto wallet_limits

| Campo                     | Tipo    | Descrição                                    | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `limit_type` *            | string  | Tipo do limite                               | **[Enumeradores limit_type](#enumeradores-limit_type)**          |
| `limit_amount` *          | float  | Valor total do limite                         | -          |
| `used_limit` *            | float  | Valor utilizado do limite                     | -          |

### Enumeradores wallet_status

| Enumerador         | Descrição                               |
|--------------------|-----------------------------------------|
| pending_analysis   | Carteira pendente de análise KYC        |
| active             | Carteira ativa e disponível para uso    |
| rejected           | Carteira rejeitada                      |

### Enumeradores wallet_type

| Enumerador | Descrição                    |
|-------------|------------------------------|
| default     | Carteira padrão              |
| payroll     | Carteira para cartão consignao |

### Enumeradores limit_type

| Enumerador                | Descrição                    |
|---------------------------|------------------------------|
| postpaid_credit_limit     | Limite de crédito pós-pago   |
| payroll_withdraw_limit    | Limite para saque de folha de pagamento (salário/consignado) |

:::info Limites em Carteiras Payroll
Carteiras do tipo `payroll` possuem dois limites distintos:
- **`postpaid_credit_limit`**: Limite de crédito pós-pago para compras e transações com o cartão
- **`payroll_withdraw_limit`**: Limite específico para saques de folha de pagamento (salário/consignado), que são descontados automaticamente na folha de pagamento do cliente
:::

### Enumeradores day_of_week

| Enumerador | Descrição |
|-------------|-----------|
| monday     | Segunda-feira |
| tuesday    | Terça-feira |
| wednesday  | Quarta-feira |
| thursday   | Quinta-feira |
| friday     | Sexta-feira |
| saturday   | Sábado |
| sunday     | Domingo |

### Enumeradores occurrence

| Enumerador | Descrição |
|-------------|-----------|
| first      | Primeira ocorrência |
| second     | Segunda ocorrência |
| third      | Terceira ocorrência |
| fourth     | Quarta ocorrência |
| last       | Última ocorrência |

### Enumeradores fallback_strategy

| Enumerador           | Descrição                    |
|----------------------|------------------------------|
| next_business_day    | Próximo dia útil             |
| previous_business_day| Dia útil anterior            |
| same_day             | Mesmo dia                    |

### Enumeradores invoice_payment_type

| Enumerador | Descrição      |
|-------------|----------------|
| bank_slip  | Boleto bancário |

### Enumeradores interest_base

| Enumerador      | Descrição        |
|-----------------|------------------|
| calendar_days   | Dias corridos    |

### Objeto wallet_limits

| Campo                     | Tipo    | Descrição                                    | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `wallet_limit_key` *             | uuidv4  | Chave única de identificação do limite atualizado no formato UUID v4              | 36         |
| `limit_type` *            | string  | Tipo do limite                               | **[Enumeradores limit_type](#enumeradores-limit_type)**          |
| `limit_amount` *          | float  | Valor total do limite                         | -          |
| `used_limit` *            | float  | Valor utilizado do limite                     | -          |

### Enumeradores limit_type

| Enumerador                | Descrição                    |
|---------------------------|------------------------------|
| postpaid_credit_limit     | Limite de crédito pós-pago   |

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 404                      | WLT000001            | Wallet Not Found                                   | Wallet with key 8cb70dea-9fb0-4a68-9572-99a72849c8d6 not found                                                                                  | Carteira com chave 8cb70dea-9fb0-4a68-9572-99a72849c8d6 não encontrada                                                                          |

---

# Criação de Carteira (Wallet)

URL: /documentation/cartao_pos_pago/faturas/carteira/criacao_de_carteira

A criação de carteira (wallet) permite registrar uma nova carteira de crédito para uma pessoa física ou jurídica.

:::info O que é uma Wallet
A **wallet** representa a fatura de um cliente e funciona como um centralizador para gerenciar múltiplos meios de pagamento atrelados. É importante entender que:

- **Uma wallet = fatura**: Cada carteira corresponde à fatura de um cliente específico (identificado por CPF/CNPJ)
- **Múltiplos meios de pagamento**: A mesma wallet pode ter diferentes instrumentos de pagamento (cartões, PIX, etc.)
- **Instrumentos separados**: Após criar a wallet, será necessário criar separadamente os instrumentos de pagamento (cartões de crédito, limites, etc.)
- **Gestão centralizada**: A wallet centraliza todas as operações e configurações relacionadas àquele cliente
:::

## Request

ENDPOINT /wallet
MÉTODO POST

Request Body

```json
{
  "owner": {
    "request_control_key": "f7947b9d-9be3-49d8-aca2-4b3249e5fa65",
    "person_type": "natural",
    "name": "João Silva",
    "document_number": "12345678901",
    "birthdate": "1990-01-01",
    "email": "joao.silva@email.com",
    "phone": {
      "number": "99999999",
      "area_code": "11",
      "country_code": "55"
    },
    "address": {
      "street": "Rua das Flores",
      "number": "123",
      "neighborhood": "Centro",
      "postal_code": "01234567",
      "city": "São Paulo",
      "state": "SP",
      "complement": "Apto 1"
    }
  },
  "invoice_configuration": {
    "closing_date_configuration": {
      "type": "fixed",
      "fixed_day": 15
    },
    "due_date_configuration": {
      "type": "fixed",
      "fixed_day": 20,
      "offset_months": 0
    },
    "invoice_payment_type": "bank_slip",
    "interest_base": "calendar_days",
    "monthly_interest_percentage": 2.0,
    "fine_percentage": 2.0
  },
  "limits": {
    "postpaid_credit_limit": 5000.00
  }
}
```

### Request Body Params

| Campo                                    | Tipo    | Descrição                                                                          | Caracteres |
|------------------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key`    | uuidv4     | Chave única de identificação da request utilizada pelo cliente.                                            | 36                                                                          |
| `owner`                                  | object  | Dados do proprietário da carteira (pessoa física ou jurídica)                     | **[Objeto owner](#objeto-owner)** |
| `person_key`                             | string  | Chave única de identificação da pessoa no formato UUID v4                         | 36         |
| `invoice_configuration` *                | object  | Configuração de fechamento e vencimento de faturas                                | **[Objeto invoice_configuration](#objeto-invoice_configuration)** |
| `limits` *                               | object  | Limites de crédito da carteira                                                     | **[Objeto limits](#objeto-limits)** |

:::info Campos Condicionais
- **`owner`**: Obrigatório quando não for enviado `person_key`
- **`person_key`**: Obrigatório quando não for enviado `owner`
- Os campos são mutuamente exclusivos
:::

### Objeto owner

#### Pessoa Física (`person_type: "natural"`)

| Campo                     | Tipo   | Descrição                                    | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `person_type` *           | string | Tipo da pessoa (deve ser "natural")          | -          |
| `name` *                  | string | Nome completo da pessoa                       | 100        |
| `document_number` *       | string | CPF da pessoa (apenas números)               | 11         |
| `birthdate` *             | string | Data de nascimento (formato YYYY-MM-DD)      | 10         |
| `email` *                 | string | E-mail de contato                            | 254        |
| `phone` *                 | object | Telefone de contato                          | **[Objeto phone](#objeto-phone)** |
| `address` *               | object | Endereço completo                            | **[Objeto address](#objeto-address)** |

#### Pessoa Jurídica (`person_type: "legal"`)

| Campo                     | Tipo   | Descrição                                    | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `person_type` *           | string | Tipo da pessoa (deve ser "legal")            | -          |
| `name` *                  | string | Razão social da empresa                      | 100        |
| `trading_name` *          | string | Nome fantasia da empresa                     | 100        |
| `document_number` *       | string | CNPJ da empresa (apenas números)            | 14         |
| `foundation_date` *       | string | Data de fundação (formato YYYY-MM-DD)       | 10         |
| `email` *                 | string | E-mail de contato                            | 254        |
| `phone` *                 | object | Telefone de contato                          | **[Objeto phone](#objeto-phone)** |
| `address` *               | object | Endereço completo                            | **[Objeto address](#objeto-address)** |
| `legal_representatives` * | array  | Lista de representantes legais (pessoas físicas)               | -          |

### Objeto phone

| Campo                     | Tipo   | Descrição                                    | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `country_code` *          | string | Código do país (DDI)                         | 2-3        |
| `area_code` *             | string | Código de área (DDD)                         | 2          |
| `number` *                | string | Número do telefone                           | 8-9        |

### Objeto address

| Campo                     | Tipo   | Descrição                                    | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `street` *                | string | Nome da rua/avenida                          | 500        |
| `number` *                | string | Número do endereço                           | 10         |
| `neighborhood` *          | string | Bairro                                       | 100        |
| `postal_code` *           | string | CEP (apenas números)                         | 8          |
| `city` *                  | string | Cidade                                       | 100        |
| `state` *                 | string | Estado (UF)                                  | **[Enumeradores state](#enumeradores-state)** |
| `complement`              | string | Complemento do endereço                      | 500        |

### Enumeradores state

| Enumerador | Descrição      |
|-------------|----------------|
| AC          | Acre           |
| AL          | Alagoas        |
| AM          | Amazonas       |
| AP          | Amapá          |
| BA          | Bahia          |
| CE          | Ceará          |
| DF          | Distrito Federal |
| ES          | Espírito Santo |
| GO          | Goiás          |
| MA          | Maranhão       |
| MG          | Minas Gerais    |
| MS          | Mato Grosso do Sul |
| MT          | Mato Grosso    |
| PA          | Pará           |
| PB          | Paraíba        |
| PE          | Pernambuco     |
| PI          | Piauí          |
| PR          | Paraná         |
| RJ          | Rio de Janeiro |
| RN          | Rio Grande do Norte |
| RO          | Rondônia       |
| RR          | Roraima        |
| RS          | Rio Grande do Sul |
| SC          | Santa Catarina |
| SE          | Sergipe        |
| SP          | São Paulo      |
| TO          | Tocantins      |
| EX          | Exceção        |

### Objeto invoice_configuration

| Campo                                    | Tipo    | Descrição                                                                          | Caracteres |
|------------------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `closing_date_configuration` *           | object  | Configuração da data de fechamento da fatura                                      | **[Objeto closing_date_configuration](#objeto-closing_date_configuration)** |
| `due_date_configuration` *               | object  | Configuração da data de vencimento da fatura                                      | **[Objeto due_date_configuration](#objeto-due_date_configuration)** |
| `invoice_payment_type` *                 | string  | Tipo de pagamento da fatura                                                       | **[Enumeradores invoice_payment_type](#enumeradores-invoice_payment_type)** |
| `interest_base` *                        | string  | Base de cálculo dos juros                                                         | **[Enumeradores interest_base](#enumeradores-interest_base)** |
| `monthly_interest_percentage` *          | float  | Percentual de juros mensais por atraso (0-100)                                    | -          |
| `fine_percentage` *                      | float  | Percentual de multa por atraso (0-100)                                            | -          |

### Objeto closing_date_configuration

#### Configuração Fixa (`type: "fixed"`)

| Campo                     | Tipo    | Descrição                                    | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `type` *                  | string  | Tipo de configuração (deve ser "fixed")      | -          |
| `fixed_day` *             | integer | Dia fixo do mês para fechamento (1-27)       | -          |

#### Configuração Baseada em Regras (`type: "rule_based"`)

| Campo                     | Tipo    | Descrição                                    | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `type` *                  | string  | Tipo de configuração (deve ser "rule_based") | -          |
| `rule` *                  | object  | Regra para cálculo da data                     | **[Objeto rule (closing_date_configuration)](#objeto-closing_date_configuration)**          |

### Objeto rule (closing_date_configuration)

| Campo                     | Tipo    | Descrição                                    | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `day_of_week` *          | string  | Dia da semana                                | **[Enumeradores day_of_week](#enumeradores-day_of_week)**          |
| `occurrence` *            | string  | Ocorrência do dia no mês                      | **[Enumeradores occurrence](#enumeradores-occurrence)**          |
| `fallback_strategy` *     | string  | Estratégia para dias não úteis                | **[Enumeradores fallback_strategy](#enumeradores-fallback_strategy)**          |

### Objeto due_date_configuration

#### Configuração Fixa (`type: "fixed"`)

| Campo                     | Tipo    | Descrição                                    | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `type` *                  | string  | Tipo de configuração (deve ser "fixed")      | -          |
| `offset_months` *         | integer | Meses de offset a partir do fechamento       | -          |
| `fixed_day` *             | integer | Dia fixo do mês para vencimento (2-27)       | -          |

#### Configuração Baseada em Regras (`type: "rule_based"`)

| Campo                     | Tipo    | Descrição                                    | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `type` *                  | string  | Tipo de configuração (deve ser "rule_based") | -          |
| `offset_months` *         | integer | Meses de offset a partir do fechamento       | -          |
| `rule` *                  | object  | Regra para cálculo da data                     | **[Objeto rule (closing_date_configuration)](#objeto-due_date_configuration)**          |

### Objeto rule (due_date_configuration)

| Campo                     | Tipo    | Descrição                                    | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `day_of_week` *          | string  | Dia da semana                                | **[Enumeradores day_of_week](#enumeradores-day_of_week)**          |
| `occurrence` *            | string  | Ocorrência do dia no mês                      | **[Enumeradores occurrence](#enumeradores-occurrence)**          |
| `fallback_strategy` *     | string  | Estratégia para dias não úteis                | **[Enumeradores fallback_strategy](#enumeradores-fallback_strategy)**          |

:::caution Validações de Data
- A data de vencimento deve ser pelo menos 2 dia após a data de fechamento
- Para configurações baseadas em regras, deve existir ao menos um dia de diferença entre os dias da semana escolhidos para fechamento e vencimento (ex: fechamento na segunda-feira e vencimento na quarta-feira de qualquer semana)
:::

### Enumeradores day_of_week

| Enumerador | Descrição |
|-------------|-----------|
| monday     | Segunda-feira |
| tuesday    | Terça-feira |
| wednesday  | Quarta-feira |
| thursday   | Quinta-feira |
| friday     | Sexta-feira |
| saturday   | Sábado |
| sunday     | Domingo |

### Enumeradores occurrence

| Enumerador | Descrição |
|-------------|-----------|
| first      | Primeira ocorrência |
| second     | Segunda ocorrência |
| third      | Terceira ocorrência |
| fourth     | Quarta ocorrência |
| last       | Última ocorrência |

### Enumeradores fallback_strategy

| Enumerador           | Descrição                    |
|----------------------|------------------------------|
| next_business_day    | Próximo dia útil             |
| previous_business_day| Dia útil anterior            |
| same_day             | Mesmo dia                    |

### Enumeradores invoice_payment_type

| Enumerador | Descrição      |
|-------------|----------------|
| bank_slip  | Boleto bancário |

### Enumeradores interest_base

| Enumerador      | Descrição        |
|-----------------|------------------|
| calendar_days   | Dias corridos    |

### Objeto limits

| Campo                     | Tipo    | Descrição                                    | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `postpaid_credit_limit` * | float  | Limite para crédito pós-pago                 | -          |

## Response

### Sucesso - Carteira Criada com Análise Pendente

STATUS 202

Response Body: Carteira pendente de análise

```json
{
  "wallet_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "owner_person_key": null,
  "wallet_status": "pending_analysis"
}
```

:::info Informação
Caso seja retornado **HTTP Status 202** com o campo `wallet_status` com valor `pending_analysis`, a criação será processada assincronamente.
Posteriormente será enviado posteriormente um webhook informando se a carteira foi aprovada ou rejeitada na análise KYC. Para mais detalhes sobre webhooks, consulte a [documentação de webhooks](/documentation/cartao_pos_pago/faturas/webhooks/carteira)
:::

:::note Observação
Para casos que requerem análise KYC, o campo `owner_person_key` será retornado como `null` na resposta inicial. A pessoa titular da carteira só será criada no sistema ao final do processo de KYC, caso seja aprovada. Neste caso, a chave da pessoa será enviada posteriormente através do webhook de aprovação, consulte a [documentação de webhooks](/documentation/cartao_pos_pago/faturas/webhooks/carteira)
:::

### Sucesso - Carteira Criada Ativa

STATUS 201

Response Body: Carteira ativa

```json
{
  "wallet_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "owner_person_key": "ecf87b4b-fa6e-49c0-a7f0-f2cad6b42d79",
  "wallet_status": "active"
}
```

### Response Body Params

| Campo                   | Tipo   | Descrição                                                                         | Caracteres |
|-------------------------|--------|-----------------------------------------------------------------------------------|------------|
| `wallet_key` *          | uuidv4 | Chave única de identificação da carteira no formato uuid v4                      | 36         |
| `owner_person_key` *    | string | Chave de identificação do proprietário da carteira                               | 36      |
| `wallet_status` *       | string | Status da carteira                                                               | -          |

### Enumeradores wallet_status

| Enumerador         | Descrição                               |
|--------------------|-----------------------------------------|
| pending_analysis   | Carteira pendente de análise KYC        |
| active             | Carteira ativa e disponível para uso    |
| rejected           | Carteira rejeitada                      |

:::info Status da Carteira
- **`pending_analysis`**: Retornado quando a carteira é criada com dados completos do proprietário. Será submetida a análise KYC.
- **`active`**: Retornado quando a carteira é criada com chave de pessoa existente. Disponível para uso imediato.
:::

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 404                      | CIN000020            | Requester not Found                                | No requester configuration found for requester key: 8e1e6b46-beb3-467b-965c-6c545707d467                                                     | Solicitante não encontrado para requester key: 8e1e6b46-beb3-467b-965c-6c545707d467                                                          |
| 404                      | CIN000062            | Not Found                                          | Person not found by person key: e51070e4-7494-468d-a20e-bf14789fa8ff                                                                            | Pessoa não encontrada para a person key: e51070e4-7494-468d-a20e-bf14789fa8ff                                                                   |
| 409                      | CIN000043            | Conflict                                           | Active wallet found                                                                                                     | Carteira ativa já existe                                                                                                |
| 400                      | CIN000063            | Bad Request                                        | Expiration date too close to closing date                                                                               | Data de vencimento muito próxima da data de fechamento                                                                  |
| 400                      | CIN000064            | Bad Request                                        | Invalid offset months for rule-based configuration                                                                      | Meses de offset inválidos para configuração baseada em regras                                                           |
| 400                      | CIN000065            | Bad Request                                        | Weekdays too close for rule-based configuration                                                                         | Dias da semana muito próximos para configuração baseada em regras                                                        |
| 400                      | CIN000002            | Bad Request                                        | Invalid signer document number                                                                                          | Número do documento do signatário inválido                                                                              |
| 400                      | CIN000066            | Bad Request                                        | Error while creating wallet in card service                                                                             | Erro ao criar carteira no serviço de cartão                                                                             |
| 409                      | CIN000099            | Conflict                                           | Request control key already exists.                                                                                     | Request control key já existe.                                                                                          |

---

# Listar de Carteiras (Wallets)

URL: /documentation/cartao_pos_pago/faturas/carteira/listar_carteiras

A listagem de carteiras retornará todas as carteiras que se enquadrarem nos query parameters enviados na request.

## Request

ENDPOINT /wallets
MÉTODO GET

### Query Parameters

| Campo                     | Tipo    | Descrição                                    | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `owner_document_number`   | string  | CPF/CNPJ do proprietário da carteira        | 11-14 |
| `wallet_status`                  | string  | Status da carteira para filtrar       | **[Enumeradores wallet_status](#enumeradores-wallet_status)** |
| `page`                    | integer | Número da página para paginação              | - |
| `page_size`               | integer | Quantidade de itens por página               | - |

:::caution Validações
- **Paginação**: Valores de página e tamanho devem ser inteiros válidos
- **Tamanho da página**: Máximo de 100 itens por página
:::

### Enumeradores wallet_status

| Enumerador         | Descrição                               |
|--------------------|-----------------------------------------|
| pending_analysis   | Carteira pendente de análise KYC        |
| active             | Carteira ativa e disponível para uso    |
| rejected           | Carteira rejeitada                      |

## Response

STATUS 200

Response Body: Lista de carteiras

```json
{
  "data": [
    {
      "request_control_key": "f7947b9d-9be3-49d8-aca2-4b3249e5fa65",
      "wallet_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "owner_person_key": "ecf87b4b-fa6e-49c0-a7f0-f2cad6b42d79",
      "owner_document_number": "12345678901",
      "invoice_configuration": {
        "closing_date_configuration": {
          "type": "fixed",
          "fixed_day": 15
        },
        "due_date_configuration": {
          "type": "fixed",
          "fixed_day": 20,
          "offset_months": 0
        },
        "invoice_payment_type": "bank_slip",
        "interest_base": "calendar_days",
        "monthly_interest_percentage": 2.0,
        "fine_percentage": 2.0
      },
      "wallet_status": "active",
      "wallet_type": "default",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "request_control_key": "e1d7ca45-8180-48e4-a293-1f08a046693e",
      "wallet_key": "9db81efb-0ac1-5b79-0683-00b8395a9e7",
      "owner_document_number": "98765432100",
      "invoice_configuration": {
        "closing_date_configuration": {
          "type": "rule_based",
          "rule": {
            "day_of_week": "friday",
            "occurrence": "last",
            "fallback_strategy": "previous_business_day"
          }
        },
        "due_date_configuration": {
          "type": "rule_based",
          "offset_months": 1,
          "rule": {
            "day_of_week": "monday",
            "occurrence": "first",
            "fallback_strategy": "next_business_day"
          }
        },
        "invoice_payment_type": "bank_slip",
        "interest_base": "calendar_days",
        "monthly_interest_percentage": 1.5,
        "fine_percentage": 2.0
      },
      "wallet_status": "pending_analysis",
      "wallet_type": "default",
      "created_at": "2024-01-14T14:45:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "rows_per_page": 100,
  }
}
```

### Response Body Params

| Campo            | Tipo         | Descrição                             | Caracteres                                  |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `data` *         | object array | Carteiras                               | **[Objeto wallet](#objeto-wallet)**   |
| `pagination` *   | object       | Informações de paginação              | **[Objeto pagination](#objeto-pagination)** |

### Objeto wallet

| Campo                     | Tipo   | Descrição                                    | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `wallet_key` *            | uuidv4 | Chave única de identificação da carteira     | 36         |
| `owner_person_key` *      | string | Chave de identificação do proprietário da carteira                               | 36      |
| `owner_document_number` * | string | CPF/CNPJ do proprietário da carteira         | 11 ou 14   |
| `invoice_configuration` * | object | Configuração de fechamento e vencimento      | **[Objeto invoice_configuration](#objeto-invoice_configuration)**          |
| `wallet_status` *         | string | Status atual da carteira                     | **[Enumeradores wallet_status](#enumeradores-wallet_status)**          |
| `wallet_type` *           | string | Tipo da carteira                             | **[Enumeradores wallet_type](#enumeradores-wallet_type)**          |
| `created_at` *            | string | Data de criação (formato ISO 8601 UTC)       | -          |

### Objeto pagination

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `current_page` *           | integer | Página atual                                                 | -      |
| `rows_per_page` *          | integer | Itens por página                                             | -      |

### Enumeradores wallet_type

| Enumerador | Descrição                    |
|-------------|------------------------------|
| default     | Carteira padrão                |
| payroll     | Carteira para cartão consignado |

### Objeto invoice_configuration

| Campo                                    | Tipo    | Descrição                                                                          | Caracteres |
|------------------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `closing_date_configuration` *           | object  | Configuração da data de fechamento da fatura                                      | **[Objeto closing_date_configuration](#objeto-closing_date_configuration)** |
| `due_date_configuration` *               | object  | Configuração da data de vencimento da fatura                                      | **[Objeto due_date_configuration](#objeto-due_date_configuration)** |
| `invoice_payment_type` *                 | string  | Tipo de pagamento da fatura                                                       | **[Enumeradores invoice_payment_type](#enumeradores-invoice_payment_type)** |
| `interest_base`                         | string  | Base de cálculo dos juros                                                         | **[Enumeradores interest_base](#enumeradores-interest_base)** |
| `monthly_interest_percentage`          | float  | Percentual de juros mensais por atraso (0-100)                                    | -          |
| `fine_percentage`                       | float  | Percentual de multa por atraso (0-100)                                            | -          |

:::info
Nota Carteiras do tipo `payroll` não possuem os campos `interest_base`, `monthly_interest_percentage` e `fine_percentage`.
:::

### Objeto closing_date_configuration

#### Configuração Fixa (`type: "fixed"`)

| Campo                     | Tipo    | Descrição                                    | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `type` *                  | string  | Tipo de configuração (deve ser "fixed")      | -          |
| `fixed_day` *             | integer | Dia fixo do mês para fechamento (1-27)       | -          |

#### Configuração Baseada em Regras (`type: "rule_based"`)

| Campo                     | Tipo    | Descrição                                    | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `type` *                  | string  | Tipo de configuração (deve ser "rule_based") | -          |
| `rule` *                  | object  | Regra para cálculo da data                     | **[Objeto rule (closing_date_configuration)](#objeto-closing_date_configuration)**          |

### Objeto rule (closing_date_configuration)

| Campo                     | Tipo    | Descrição                                    | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `day_of_week` *          | string  | Dia da semana                                | **[Enumeradores day_of_week](#enumeradores-day_of_week)**          |
| `occurrence` *            | string  | Ocorrência do dia no mês                      | **[Enumeradores occurrence](#enumeradores-occurrence)**          |
| `fallback_strategy` *     | string  | Estratégia para dias não úteis                | **[Enumeradores fallback_strategy](#enumeradores-fallback_strategy)**          |

### Objeto due_date_configuration

#### Configuração Fixa (`type: "fixed"`)

| Campo                     | Tipo    | Descrição                                    | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `type` *                  | string  | Tipo de configuração (deve ser "fixed")      | -          |
| `offset_months` *         | integer | Meses de offset a partir do fechamento       | -          |
| `fixed_day` *             | integer | Dia fixo do mês para vencimento (2-27)       | -          |

#### Configuração Baseada em Regras (`type: "rule_based"`)

| Campo                     | Tipo    | Descrição                                    | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `type` *                  | string  | Tipo de configuração (deve ser "rule_based") | -          |
| `offset_months` *         | integer | Meses de offset a partir do fechamento       | -          |
| `rule` *                  | object  | Regra para cálculo da data                     | **[Objeto rule (closing_date_configuration)](#objeto-due_date_configuration)**          |

### Objeto rule (due_date_configuration)

| Campo                     | Tipo    | Descrição                                    | Caracteres |
|---------------------------|---------|----------------------------------------------|------------|
| `day_of_week` *          | string  | Dia da semana                                | **[Enumeradores day_of_week](#enumeradores-day_of_week)**          |
| `occurrence` *            | string  | Ocorrência do dia no mês                      | **[Enumeradores occurrence](#enumeradores-occurrence)**          |
| `fallback_strategy` *     | string  | Estratégia para dias não úteis                | **[Enumeradores fallback_strategy](#enumeradores-fallback_strategy)**          |

### Enumeradores day_of_week

| Enumerador | Descrição |
|-------------|-----------|
| monday     | Segunda-feira |
| tuesday    | Terça-feira |
| wednesday  | Quarta-feira |
| thursday   | Quinta-feira |
| friday     | Sexta-feira |
| saturday   | Sábado |
| sunday     | Domingo |

### Enumeradores occurrence

| Enumerador | Descrição |
|-------------|-----------|
| first      | Primeira ocorrência |
| second     | Segunda ocorrência |
| third      | Terceira ocorrência |
| fourth     | Quarta ocorrência |
| last       | Última ocorrência |

### Enumeradores fallback_strategy

| Enumerador           | Descrição                    |
|----------------------|------------------------------|
| next_business_day    | Próximo dia útil             |
| previous_business_day| Dia útil anterior            |
| same_day             | Mesmo dia                    |

### Enumeradores invoice_payment_type

| Enumerador | Descrição      |
|-------------|----------------|
| bank_slip  | Boleto bancário |

### Enumeradores interest_base

| Enumerador      | Descrição        |
|-----------------|------------------|
| calendar_days   | Dias corridos    |

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | BKS000012            | Bad Request                                        | Invalid integer value for page or size query string parameters                                                           | Valor inválido para parâmetros de página ou tamanho de página                                                           |
| 400                      | BKS000013            | Bad Request                                        | Invalid query wallet status                                                                                             | Status de consulta de carteira inválido                                                                                 |

---

# Listar Entradas de Carteira

URL: /documentation/cartao_pos_pago/faturas/carteira/listar_entradas_da_carteira

A listagem de entradas de carteira retornará todas as entradas de uma carteira específica que se enquadrarem nos query parameters enviados na request.

## Request

ENDPOINT /wallet/ WALLET_KEY /wallet_entries
MÉTODO GET

### Path Parameters

| Campo        | Tipo   | Descrição                                    | Caracteres |
|--------------|--------|----------------------------------------------|------------|
| `wallet_key` | uuidv4 | Chave única da carteira no formato UUID v4  | 36         |

### Query Parameters

| Campo                        | Tipo    | Descrição                                    | Caracteres |
|------------------------------|---------|----------------------------------------------|------------|
| `wallet_entry_type` *        | string  | Tipo da entrada da carteira                  | **[Enumeradores wallet_entry_type](#enumeradores-wallet_entry_type)** |
| `wallet_entry_status` *      | string  | Status da entrada da carteira                 | **[Enumeradores wallet_entry_status](#enumeradores-wallet_entry_status)** |
| `page`                       | integer | Número da página para paginação              | -          |
| `page_size`                  | integer | Quantidade de itens por página               | -          |

:::caution Validações
- **Paginação**: Valores de página e tamanho devem ser inteiros válidos
- **Tamanho da página**: Máximo de 100 itens por página
:::

### Enumeradores wallet_entry_type

| Enumerador        | Descrição                                                                         |
|-------------------|-----------------------------------------------------------------------------------|
| revolving_credit  | Crédito rotativo                                                                  |
| payroll_withdraw  | Saque de folha                                                                    |
| payroll_overdue   | Atraso de folha                                                                   |

:::info Tipos de Entrada de Carteira
- **`revolving_credit`**: Valores de crédito disponibilizados para o cliente
- **`payroll_withdraw`**: Dívida gerada pelo saque do limite e que vai ser descontada todo mês do INSS
- **`payroll_overdue`**: Dívida gerada pelo não pagamento da fatura e também vai ser descontada todo mês do INSS
:::

### Enumeradores wallet_entry_status

| Enumerador | Descrição                               |
|------------|-----------------------------------------|
| concluded     | Entrada concluída |

## Response

STATUS 200

Response Body: Lista de entradas de carteira

```json
{
  "data": [
    {
      "wallet_entry_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "wallet_entry_amount": 150.00,
      "wallet_entry_settlement_key": "cc8fb19b-d1e4-4ce6-ad4c-61e0609a8f8d",
      "wallet_entry_type": "revolving_credit",
      "wallet_entry_status": "concluded",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "wallet_entry_key": "9db81efb-0ac1-5b79-0683-00b8395a9e7",
      "wallet_entry_amount": 150.00,
      "wallet_entry_settlement_key": "20cbf6e7-9535-44b4-88e3-f2c7a178a198",
      "wallet_entry_type": "payroll_withdraw",
      "wallet_entry_status": "concluded",
      "created_at": "2024-01-14T14:45:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "rows_per_page": 100
  }
}
```

### Response Body Params

| Campo            | Tipo         | Descrição                             | Caracteres                                  |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `data` *         | object array | Entradas de carteira                  | **[Objeto wallet_entry](#objeto-wallet_entry)** |
| `pagination` *   | object       | Informações de paginação              | **[Objeto pagination](#objeto-pagination)** |

### Objeto wallet_entry

| Campo                        | Tipo    | Descrição                                                                         | Caracteres |
|------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| `wallet_entry_key` *         | uuidv4  | Chave única de identificação da entrada no formato uuid v4                        | 36         |
| `wallet_entry_amount` *      | float  | Valor da entrada                                                                  | -          |
| `wallet_entry_settlement_key` * | string | Chave de liquidação da entrada                                                   | -          |
| `wallet_entry_type` *        | string  | Tipo da entrada da carteira                                                        | **[Enumeradores wallet_entry_type](#enumeradores-wallet_entry_type)** |
| `wallet_entry_status` *      | string  | Status da entrada da carteira                                                      | **[Enumeradores wallet_entry_status](#enumeradores-wallet_entry_status)** |
| `created_at` *               | string  | Data de criação (formato ISO 8601 UTC)                                           | -          |

### Objeto pagination

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `current_page` *           | integer | Página atual                                                 | -      |
| `rows_per_page` *          | integer | Itens por página                                             | -      |

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | CIN000069            | Bad Request                                        | Invalid integer value for page or size query string parameters                                                           | Valor inválido para parâmetros de página ou tamanho de página                                                           |
| 400                      | CIN000076            | Bad Request                                        | Invalid query wallet entry status                                                                                       | Status de consulta de dívida da carteira inválido                                                                       |
| 400                      | CIN000077            | Bad Request                                        | Invalid query wallet entry type                                                                                         | Tipo de consulta de dívida da carteira inválido                                                                         |
| 404                      | CIN000007            | Wallet not Found                                   | Wallet with key: abeca0d0-a09d-4b3b-a495-40b553422ced was not found                                                   | Carteira com a chave: abeca0d0-a09d-4b3b-a495-40b553422ced não foi encontrado                                         |

---

# Buscar Boleto da Carteira

URL: /documentation/cartao_pos_pago/faturas/fatura/boleto_de_pagamento_da_fatura

A busca de boleto da carteira retornará as informações do boleto bancário associado à carteira, incluindo código de barras e linha digitável.

:::warning Atenção
O boleto da carteira **só é gerado a partir do fechamento da primeira fatura**. 
:::

## Request

ENDPOINT /v2/invoice/wallet/ WALLET_KEY /wallet_bank_slip
MÉTODO GET

### Path Parameters

| Campo         | Tipo   | Descrição                                    | Caracteres |
|---------------|--------|----------------------------------------------|------------|
| `wallet_key`  | uuidv4 | Chave única da carteira no formato UUID v4  | 36         |

## Response

STATUS 200

Response Body: Detalhes do boleto

```json
{
  "wallet_bank_slip_key": "3571e292-3a83-4011-904d-20ee963022ef",
  "wallet_bank_slip_status": "accepted",
  "bank_slip_amount": 150.00,
  "bank_slip_due_date": "2024-02-15",
  "bank_slip_data": {
    "barcode": "32991090000000150001234567890123456789012345",
    "digitable_line": "32991234567890123456789012345678901234567890123"
  }
}
```

### Response Body Params

| Campo                    | Tipo   | Descrição                                                                         | Caracteres |
|--------------------------|--------|-----------------------------------------------------------------------------------|------------|
| `wallet_bank_slip_key` * | uuidv4 | Chave única de identificação do boleto da carteira no formato uuid v4           | 36         |
| `wallet_bank_slip_status` * | string | Status do boleto                                                                 | **[Enumeradores wallet_bank_slip_status](#enumeradores-wallet_bank_slip_status)** |
| `bank_slip_amount` *     | float  | Valor do boleto                                                                   | -          |
| `bank_slip_due_date` *   | string | Data de vencimento do boleto (formato YYYY-MM-DD)                                | 10         |
| `bank_slip_data` *       | object | Dados do boleto contendo código de barras e linha digitável                      | **[Objeto bank_slip_data](#objeto-bank_slip_data)** |

### Objeto bank_slip_data

| Campo                    | Tipo   | Descrição                                                                         | Caracteres |
|--------------------------|--------|-----------------------------------------------------------------------------------|------------|
| `barcode` *              | string | Código de barras do boleto                                                        | 44         |
| `digitable_line` *       | string | Linha digitável do boleto                                                         | 47         |

### Enumeradores wallet_bank_slip_status

| Enumerador | Descrição                               |
|------------|-----------------------------------------|
| accepted   | Boleto aceito, aguardando confirmação do registro |
| registered | Boleto registrado e disponível para pagamento |

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 404                      | CIN000007            | Wallet not Found                                   | Wallet with key: abeca0d0-a09d-4b3b-a495-40b553422ced was not found                                                   | Carteira com a chave: abeca0d0-a09d-4b3b-a495-40b553422ced não foi encontrado                                         |
| 404                      | CIN000093            | Not Found                                          | Wallet bank slip was not found                                                                                          | Boleto da carteira não foi encontrado                                                                                   |

---

# Buscar Fatura por Chave

URL: /documentation/cartao_pos_pago/faturas/fatura/consulta_por_chave

A busca de fatura por chave retornará os detalhes completos de uma fatura específica, incluindo todos os itens da fatura.

## Request

ENDPOINT /wallet/ WALLET_KEY /invoice/ INVOICE_KEY
MÉTODO GET

### Path Parameters

| Campo         | Tipo   | Descrição                                    | Caracteres |
|---------------|--------|----------------------------------------------|------------|
| `wallet_key`  | uuidv4 | Chave única da carteira no formato UUID v4  | 36         |
| `invoice_key` | uuidv4 | Chave única da fatura no formato UUID v4    | 36         |

## Response

STATUS 200

Response Body: Detalhes da fatura

```json
{
  "invoice_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "due_date": "2024-02-15",
  "closing_date": "2024-01-31",
  "invoice_status": "opened",
  "total_amount": 350.00,
  "paid_amount": 0.00,
  "invoice_items": [
    {
      "invoice_item_key": "3571e292-3a83-4011-904d-20ee963022ef",
      "invoice_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "wallet_entry_key": null,
      "payment_instrument_entry_key": "g3ebe8d6-4c8a-1794-22d9-406c0f8g3dbe",
      "installment_number": 1,
      "invoice_description": "Compra no estabelecimento XYZ",
      "amount": 150.00,
      "used_limit": 150.00,
      "paid_amount": 0.00,
      "invoice_item_status": "concluded",
      "invoice_item_due_date": "2024-02-15",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "invoice_item_key": "b2c3d4e5-f6g7-8901-bcde-f23456789012",
      "invoice_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "wallet_entry_key": null,
      "payment_instrument_entry_key": "g3ebe8d6-4c8a-1794-22d9-406c0f8g3dbe",
      "installment_number": 2,
      "invoice_description": "Parcela 2 de 3 - Compra parcelada",
      "amount": 200.00,
      "used_limit": 200.00,
      "invoice_item_status": "concluded",
      "invoice_item_due_date": "2024-02-15",
      "created_at": "2024-01-16T14:45:00Z"
    }
  ],
  "invoice_payments": [
    {
      "invoice_payment_key": "c3d4e5f6-g7h8-9012-cdef-345678901234",
      "total_amount": 350.00,
      "paid_amount": 0.00,
      "invoice_payment_type": "bank_slip",
      "invoice_payment_status": "paid"
    }
  ],
  "invoice_payments_chargebacks": [
    {
      "invoice_item_key": "3571e292-3a83-4011-904d-20ee963022ef",
      "chargeback_paid_amount": 50.00
    }
  ],
  "created_at": "2024-01-15T10:30:00Z"
}
```

### Response Body Params

| Campo            | Tipo         | Descrição                             | Caracteres                                  |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `invoice_key` *  | uuidv4       | Chave única de identificação da fatura no formato uuid v4 | 36         |
| `due_date` *     | string       | Data de vencimento da fatura (formato YYYY-MM-DD) | 10         |
| `closing_date` * | string       | Data de fechamento da fatura (formato YYYY-MM-DD) | 10         |
| `invoice_status` * | string    | Status da fatura                     | **[Enumeradores invoice_status](#enumeradores-invoice_status)** |
| `total_amount` * | number       | Valor total da fatura                 | -          |
| `paid_amount` *  | number       | Valor pago da fatura                   | -          |
| `invoice_items` * | object array | Itens da fatura                      | **[Objeto invoice_item](#objeto-invoice_item)** |
| `invoice_payments` *               | object array | Pagamentos da fatura                | [Objeto invoice_payment](#objeto-invoice_payment) |
| `invoice_payments_chargebacks` *  | object array | Estornos dos pagamentos da fatura | [Objeto invoice_payment_chargeback](#objeto-invoice_payment_chargeback) |
| `created_at` *                     | string       | Data de criação (formato ISO 8601 UTC) | -          |

### Objeto invoice_item

| Campo                              | Tipo    | Descrição                                                                         | Caracteres |
|------------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| `invoice_item_key` *               | uuidv4  | Chave única de identificação do item da fatura no formato uuid v4                | 36         |
| `invoice_key` *                    | uuidv4  | Chave única de identificação da fatura no formato uuid v4                        | 36         |
| `wallet_entry_key`                 | uuidv4  | Chave única de identificação da entrada da carteira no formato uuid v4          | 36         |
| `payment_instrument_entry_key`     | uuidv4  | Chave única de identificação da entrada do instrumento de pagamento no formato uuid v4 | 36 |
| `installment_number` *             | integer | Número da parcela                                                                 | -          |
| `invoice_description` *            | string  | Descrição do item da fatura                                                       | -          |
| `amount` *                         | float  | Valor do item                                                                     | -          |
| `used_limit` *                     | float  | Limite utilizado                                                                 | -          |
| `invoice_item_status` *            | string  | Status do item da fatura                                                          | **[Enumeradores invoice_item_status](#enumeradores-invoice_item_status)** |
| `invoice_item_due_date` *          | string  | Data de vencimento do item (formato YYYY-MM-DD)                                  | 10         |
| `created_at` *                     | string  | Data de criação (formato ISO 8601 UTC)                                           | -          |

### Objeto invoice_payment

| Campo                              | Tipo    | Descrição                                                                         | Caracteres |
|------------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| invoice_payment_key *              | uuidv4  | Chave única de identificação do pagamento da fatura no formato uuid v4           | 36         |
| total_amount                       | number  | Valor total do pagamento                                                          | -          |
| paid_amount                        | number  | Valor pago do pagamento                                                           | -          |
| invoice_payment_type *              | string  | Tipo de pagamento da fatura                                                       | [Enumeradores invoice_payment_type](#enumeradores-invoice_payment_type) |
| invoice_payment_status *           | string  | Status do pagamento da fatura                                                     | [Enumeradores invoice_payment_status](#enumeradores-invoice_payment_status) |

### Objeto invoice_payment_chargeback

| Campo                              | Tipo    | Descrição                                                                         | Caracteres |
|------------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| invoice_item_key *                 | uuidv4  | Chave única de identificação do item da fatura relacionado ao estorno no formato uuid v4 | 36         |
| chargeback_paid_amount             | number  | Valor do estorno utilizado                                                       | -          |

### Enumeradores invoice_status

| Enumerador | Descrição                               |
|------------|-----------------------------------------|
| opened                 | Fatura aberta               |
| processing_closing     | Processando fechamento      |
| processing_expiration  | Processando expiração       |
| closed                 | Fatura fechada              |
| processing_payment        | Aguardando pagamento        |
| paid                   | Fatura paga                 |

:::info Observação
O status `processing_payment` é aplicado apenas para carteiras do tipo `payroll` no cenário em que o valor possível para pagamento já foi realizado e está restando o valor a ser pago com o benefício.
:::

### Enumeradores invoice_payment_type

| Enumerador | Descrição                               |
|------------|-----------------------------------------|
| bank_slip        | Boleto bancário               |
| payroll_discount | Desconto via INSS      |

:::info Observação
O tipo `payroll_discount` existe apenas para carteiras do tipo `payroll` e representa o valor que vai ser descontado via benefício.
:::

### Enumeradores invoice_payment_status

| Enumerador | Descrição                               |
|------------|-----------------------------------------|
| processing_payment  | Aguardando pagamento               |
| paid             | Pago              |

:::info Observação
- Para pagamentos do tipo `payroll_discount`: o pagamento é criado no momento do fechamento da fatura com o status `processing_payment` e o desconto é solicitado no INSS. Quando o pagamento do desconto é realizado, o status muda para `paid`.
- Para pagamentos do tipo `bank_slip`: o pagamento é criado com status `processing_payment` quando recebemos o aviso de pagamento do boleto. No momento da liquidação do boleto, o status muda para `paid`. O pagamento pode ser criado com status `paid` diretamente caso não seja recebido um aviso de pagamento.
:::

### Enumeradores invoice_item_status

| Enumerador | Descrição                               |
|------------|-----------------------------------------|
| concluded    | Item concluído   |
| canceled  | Item cancelado               |

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 404                      | CIN000007            | Wallet not Found                                   | Wallet with key: abeca0d0-a09d-4b3b-a495-40b553422ced was not found                                                   | Carteira com a chave: abeca0d0-a09d-4b3b-a495-40b553422ced não foi encontrado                                         |
| 404                      | CIN000016            | Invoice Not Found                                  | Invoice with key: 8cb70dea-9fb0-4a68-9572-99a72849c8d6 was not found                                                  | Fatura com a chave: 8cb70dea-9fb0-4a68-9572-99a72849c8d6 não foi encontrado                                           |

---

# Listar Faturas

URL: /documentation/cartao_pos_pago/faturas/fatura/listar_faturas

A listagem de faturas retornará todas as faturas de uma carteira específica que se enquadrarem nos query parameters enviados na request.

## Request

ENDPOINT /wallet/ WALLET_KEY /invoices
MÉTODO GET

### Path Parameters

| Campo        | Tipo   | Descrição                                    | Caracteres |
|--------------|--------|----------------------------------------------|------------|
| `wallet_key` | uuidv4 | Chave única da carteira no formato UUID v4  | 36         |

### Query Parameters

| Campo                        | Tipo    | Descrição                                    | Caracteres |
|------------------------------|---------|----------------------------------------------|------------|
| `invoice_status` *           | string  | Status da fatura                                                             | **[Enumeradores invoice_status](#enumeradores-invoice_status)** |
| `page`                       | integer | Número da página para paginação              | -          |
| `page_size`                  | integer | Quantidade de itens por página               | -          |

:::caution Validações
- **Paginação**: Valores de página e tamanho devem ser inteiros válidos
- **Tamanho da página**: Máximo de 100 itens por página
:::

### Enumeradores invoice_status

| Enumerador | Descrição                               |
|------------|-----------------------------------------|
| opened                 | Fatura aberta               |
| processing_closing     | Processando fechamento      |
| processing_expiration  | Processando expiração       |
| closed                 | Fatura fechada              |
| processing_payment        | Aguardando pagamento        |
| paid                   | Fatura paga                 |

## Response

STATUS 200

Response Body: Lista de faturas

```json
{
  "data": [
    {
      "invoice_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "due_date": "2024-02-15",
      "closing_date": "2024-01-31",
      "invoice_status": "opened",
      "total_amount": 350.00,
      "paid_amount": 0.00,
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "invoice_key": "9db81efb-0ac1-5b79-0683-00b8395a9e7",
      "due_date": "2024-01-15",
      "closing_date": "2023-12-31",
      "invoice_status": "opened",
      "total_amount": 500.00,
      "paid_amount": 0.00,
      "created_at": "2024-01-14T14:45:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "rows_per_page": 100
  }
}
```

### Response Body Params

| Campo            | Tipo         | Descrição                             | Caracteres                                  |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `data` *         | object array | Faturas                               | **[Objeto invoice](#objeto-invoice)**       |
| `pagination` *   | object       | Informações de paginação              | **[Objeto pagination](#objeto-pagination)** |

### Objeto invoice

| Campo                        | Tipo    | Descrição                                                                         | Caracteres |
|------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| `invoice_key` *              | uuidv4  | Chave única de identificação da fatura no formato uuid v4                        | 36         |
| `due_date` *                 | string  | Data de vencimento da fatura (formato YYYY-MM-DD)                               | 10         |
| `closing_date` *             | string  | Data de fechamento da fatura (formato YYYY-MM-DD)                               | 10         |
| `invoice_status` *           | string  | Status da fatura                                                                 | **[Enumeradores invoice_status](#enumeradores-invoice_status)** |
| `total_amount` *             | number  | Valor total da fatura                                              | -          |
| `paid_amount` *              | number  | Valor pago da fatura                                                | -          |
| `created_at` *               | string  | Data de criação (formato ISO 8601 UTC)                                           | -          |

### Objeto pagination

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `current_page` *           | integer | Página atual                                                 | -      |
| `rows_per_page` *          | integer | Itens por página                                             | -      |

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | CIN000069            | Bad Request                                        | Invalid integer value for page or size query string parameters                                                           | Valor inválido para parâmetros de página ou tamanho de página                                                           |
| 400                      | CIN000079            | Bad Request                                        | Invalid query invoice status                                                                                             | Status de consulta de fatura inválido                                                                                  |
| 404                      | CIN000007            | Wallet not Found                                   | Wallet with key: abeca0d0-a09d-4b3b-a495-40b553422ced was not found                                                   | Carteira com a chave: abeca0d0-a09d-4b3b-a495-40b553422ced não foi encontrado                                         |

---

# Simulação de cenários - Fechamento e Vencimento de Faturas

URL: /documentation/cartao_pos_pago/faturas/fatura/simulacao_de_cenarios

Esta página descreve como simular o fechamento e vencimento de faturas para testar o fluxo de transações com cartões pós-pagos. Essas simulações são úteis para homologação e testes de integração.

## 1 - Simulação de fechamento de fatura

Simula o fechamento de uma fatura aberta, alterando seu status para `processing_closing` e publicando a mensagem na fila de fechamento. A fatura será processada conforme a configuração da carteira.

ENDPOINT /mock/invoice/ INVOICE_KEY /close
MÉTODO PATCH

### Path Parameters

| Campo                        | Tipo   | Descrição                                    | Caracteres |
|------------------------------|--------|----------------------------------------------|------------|
| `invoice_key` *           | string  | Chave única da fatura no formato UUID v4                                  | 36         |

### Headers

### Request Body

Esta requisição não possui body.

### Response

STATUS 204

Response Body

```json

{}

```

### Response Body Params

Esta resposta não possui parâmetros no body.

:::tip Comportamento

- A simulação altera o status da fatura para `processing_closing`
- A fatura deve estar com status `opened` para poder ser fechada
- Uma notificação de mudança de status é enviada ao cliente
:::

## 2 - Simulação de vencimento de fatura

Simula o vencimento de uma fatura fechada, alterando seu status para `processing_expiration` e publicando a mensagem na fila de vencimento. A fatura será processada conforme a configuração da carteira.

ENDPOINT /mock/invoice/ INVOICE_KEY /expire
MÉTODO PATCH

### Path Parameters

| Campo                        | Tipo   | Descrição                                    | Caracteres |
|------------------------------|--------|----------------------------------------------|------------|
| `invoice_key` *           | string  | Chave única da fatura no formato UUID v4                                  | 36         |

### Request Body

Esta requisição não possui body.

### Response

STATUS 204

Response Body

```json

{}

```

### Response Body Params

Esta resposta não possui parâmetros no body.

:::tip Comportamento
- A simulação altera o status da fatura para `processing_expiration`
- A fatura não pode estar com status `opened` (deve estar fechada)
- A carteira deve ter pelo menos uma fatura aberta
- A próxima data de fechamento da carteira não pode ser anterior à próxima data de vencimento
- Uma notificação de mudança de status é enviada ao cliente
:::

---

# Alteração de Limite de Instrumento de Pagamento

URL: /documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/alteracao_de_limite

A alteração de limite de instrumento de pagamento permite alterar o valor do limite de um instrumento de pagamento existente.

## Request

ENDPOINT /wallet/ WALLET_KEY /payment_instrument/ PAYMENT_INSTRUMENT_KEY
MÉTODO PATCH

### Path Parameters

| Campo                        | Tipo   | Descrição                                    | Caracteres |
|------------------------------|--------|----------------------------------------------|------------|
| `wallet_key` *               | uuidv4 | Chave única da carteira no formato UUID v4  | 36         |
| `payment_instrument_key` *   | uuidv4 | Chave única do instrumento de pagamento no formato UUID v4 | 36 |

Request Body

```json
{
  "limit_amount": 3000.00
}
```

### Request Body Params

| Campo                        | Tipo    | Descrição                                                                          | Caracteres |
|------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `limit_amount` *             | float   | Novo valor do limite do instrumento de pagamento                                  | -          |

:::info Observação
- O novo valor do limite deve ser maior ou igual ao limite utilizado (`used_limit`)
- O novo valor do limite não pode ser maior que o limite de crédito pós-pago da carteira (`postpaid_credit_limit`)
- Apenas instrumentos de pagamento do tipo `postpaid_card` podem ter seus limites atualizados
- Apenas carteiras do tipo `default` podem ter instrumentos de pagamento com limites atualizados
- O instrumento de pagamento deve estar com status `active` para ter seu limite atualizado
:::

## Response

STATUS 200

Response Body: Limite de instrumento de pagamento atualizado

```json
{
  "payment_instrument_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "limit_amount": 3000.00,
  "payment_instrument_status": "active"
}
```

### Response Body Params

| Campo                            | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `payment_instrument_key` *       | uuidv4  | Chave única de identificação do instrumento atualizado no formato UUID v4         | 36         |
| `limit_amount` *                 | float   | Novo valor do limite do instrumento após a atualização                             | -          |
| `payment_instrument_status` *    | string  | Status do instrumento de pagamento                                                 | **[Enumeradores payment_instrument_status](#enumeradores-payment_instrument_status)** |

### Enumeradores payment_instrument_status

| Enumerador | Descrição                               |
|------------|-----------------------------------------|
| active     | Instrumento ativo                       |
| canceled   | Instrumento cancelado                   |    

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | CIN000074            | Bad Request                                        | Limit amount is greater than postpaid credit limit of the wallet.                                                       | Limite é maior que o limite de crédito pós-pago da carteira.                                                           |
| 400                      | CIN000081            | Bad Request                                        | Payment instrument is not active                                                                                         | Instrumento de pagamento não está ativo                                                                                |
| 400                      | CIN000110            | Bad Request                                        | New limit amount is less than used limit                                                                                 | Novo valor do limite é menor que o valor utilizado                                                                     |
| 403                      | CIN000108            | Forbidden                                          | Wallet type payroll is not allowed for this operation                                                                    | Tipo de carteira payroll não é permitido para esta operação                                                           |
| 403                      | CIN000113            | Forbidden                                          | Payment instrument type is not allowed for this operation                                                               | Tipo de instrumento de pagamento não é permitido para esta operação                                                    |
| 404                      | CIN000007            | Wallet not Found                                   | Wallet with key: e503fa60-285e-4632-96b6-bf3ad908a23c was not found                                                    | Carteira com a chave: e503fa60-285e-4632-96b6-bf3ad908a23c não foi encontrado                                         |
| 404                      | CIN000080            | Payment Instrument Not Found                       | Payment instrument was not found                                                                                         | Instrumento de pagamento não foi encontrado                                                                            |

---

# Cancelamento de Instrumento de Pagamento

URL: /documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/cancelamento_de_instrumento_de_pagamento

O cancelamento de instrumento de pagamento permite cancelar um instrumento de pagamento existente, alterando seu status para `canceled` e cancelando o cartão pós-pago associado.

## Request

ENDPOINT /wallet/ WALLET_KEY /payment_instrument/ PAYMENT_INSTRUMENT_KEY /cancel
MÉTODO PATCH

### Path Parameters

| Campo                        | Tipo   | Descrição                                    | Caracteres |
|------------------------------|--------|----------------------------------------------|------------|
| `wallet_key` *               | uuidv4 | Chave única da carteira no formato UUID v4  | 36         |
| `payment_instrument_key` *   | uuidv4 | Chave única do instrumento de pagamento no formato UUID v4 | 36 |

:::info Observação
Esta requisição não possui request body. O cancelamento é realizado apenas através dos path parameters.
:::

## Response

STATUS 200

Response Body: Instrumento de pagamento cancelado

```json
{
  "payment_instrument_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "payment_instrument_status": "canceled"
}
```

### Response Body Params

| Campo                            | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `payment_instrument_key` *       | uuidv4  | Chave única de identificação do instrumento cancelado no formato UUID v4          | 36         |
| `payment_instrument_status` *    | string  | Status do instrumento após o cancelamento                                         | **[Enumeradores payment_instrument_status](#enumeradores-payment_instrument_status)** |

### Enumeradores payment_instrument_status

| Enumerador | Descrição                               |
|------------|-----------------------------------------|
| canceled   | Instrumento cancelado                   |

:::tip Comportamento
- O instrumento de pagamento será movido para o status `canceled` após o cancelamento
- O cartão pós-pago associado ao instrumento também será cancelado automaticamente
- O instrumento cancelado não poderá ser utilizado para novas transações
- O instrumento cancelado ainda poderá ser consultado e listado, mas aparecerá com status `canceled`
:::

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | CIN000081            | Bad Request                                        | Payment instrument is not active                                                                                         | Instrumento de pagamento não está ativo                                                                                |
| 400                      | CIN000100            | Bad Request                                        | Error canceling card in card service                                                                                    | Erro ao cancelar cartão no serviço de cartões                                                                           |
| 404                      | CIN000007            | Wallet not Found                                   | Wallet with key: abeca0d0-a09d-4b3b-a495-40b553422ced was not found                                                   | Carteira com a chave: abeca0d0-a09d-4b3b-a495-40b553422ced não foi encontrado                                         |
| 404                      | CIN000080            | Payment Instrument Not Found                       | Payment instrument was not found                                                                                         | Instrumento de pagamento não foi encontrado                                                                             |

---

# Buscar Entrada de Instrumento de Pagamento por Chave

URL: /documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/consulta_entrada_por_chave

A busca de entrada de instrumento de pagamento por chave retornará os detalhes completos de uma entrada específica, incluindo todos os itens da fatura relacionados.

## Request

ENDPOINT /wallet/ WALLET_KEY /payment_instrument/ PAYMENT_INSTRUMENT_KEY /payment_instrument_entry/ PAYMENT_INSTRUMENT_ENTRY_KEY
MÉTODO GET

### Path Parameters

| Campo                          | Tipo   | Descrição                                    | Caracteres |
|--------------------------------|--------|----------------------------------------------|------------|
| `wallet_key`                   | uuidv4 | Chave única da carteira no formato UUID v4  | 36         |
| `payment_instrument_key`       | uuidv4 | Chave única do instrumento de pagamento no formato UUID v4 | 36 |
| `payment_instrument_entry_key` | uuidv4 | Chave única da entrada no formato UUID v4    | 36         |

## Response

STATUS 200

Response Body: Detalhes da entrada de instrumento de pagamento

```json
{
  "payment_instrument_entry_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "payment_instrument_entry_amount": 150.00,
  "payment_instrument_entry_type": "purchase",
  "payment_instrument_entry_status": "concluded",
  "payment_instrument_entry_data": {
    "merchant_name": "Merchant Name",
    "merchant_country": "Merchant Country",
    "merchant_postal_code": "Merchant Postal Code",
    "merchant_city": "Merchant City",
    "merchant_street": "Merchant Street"
  },
  "invoice_items": [
    {
      "invoice_item_key": "3571e292-3a83-4011-904d-20ee963022ef",
      "invoice_key": "f2cad6b4-2a68-9572-99a7-2849c8d6ecf8",
      "wallet_entry_key": null,
      "payment_instrument_entry_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "installment_number": 1,
      "invoice_description": "Compra no estabelecimento XYZ",
      "amount": 150.00,
      "used_limit": 150.00,
      "invoice_item_status": "concluded",
      "invoice_item_due_date": "2024-02-15",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "created_at": "2024-01-15T10:30:00Z"
}
```

### Response Body Params

| Campo                                 | Tipo         | Descrição                             | Caracteres                                  |
|---------------------------------------|--------------|---------------------------------------|---------------------------------------------|
| `payment_instrument_entry_key` *      | uuidv4       | Chave única de identificação da entrada no formato uuid v4 | 36         |
| `payment_instrument_entry_amount` *   | number       | Valor da entrada                      | -          |
| `payment_instrument_entry_type` *     | string       | Tipo da entrada do instrumento de pagamento | **[Enumeradores payment_instrument_entry_type](#enumeradores-payment_instrument_entry_type)** |
| `payment_instrument_entry_status` *  | string       | Status da entrada do instrumento      | **[Enumeradores payment_instrument_entry_status](#enumeradores-payment_instrument_entry_status)** |
| `invoice_items` *                     | object array | Itens da fatura relacionados          | **[Objeto invoice_item](#objeto-invoice_item)** |
| `payment_instrument_entry_data`      | object  | Dados do adicionais | **[Objeto payment_instrument_entry_data](#objeto-payment_instrument_entry_data)** |
| `created_at` *                       | string  | Data de criação (formato ISO 8601 UTC)                                           | -          |

### Objeto payment_instrument_entry_data (purchase | withdraw)

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `merchant_name` *          | string  | Nome do estabelecimento comercial                                                 | -          |
| `merchant_country` *       | string  | País do estabelecimento comercial                                                 | -          |
| `merchant_postal_code` *   | string  | Código postal do estabelecimento comercial                                        | -          |
| `merchant_city` *          | string  | Cidade do estabelecimento comercial                                               | -          |
| `merchant_street` *        | string  | Rua do estabelecimento comercial                                                  | -          |

### Objeto payment_instrument_entry_data (postpaid_card_issuance)

| Campo                           | Tipo    | Descrição                                                                          | Caracteres |
|---------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `postpaid_card_issuance_name` * | string  | Nome da emissão do cartão pós-pago                                                 | -          |
| `payment_instrument_key` *      | string  | Chave única do instrumento de pagamento no formato UUID v4                        | 36         |
| `postpaid_card_key` *           | string  | Chave única do cartão pós-pago no formato UUID v4                                  | 36         |

:::info Observação
Esta entrada existe apenas para cartões de carteira de cartão consignado.
:::

### Enumeradores payment_instrument_entry_type

| Enumerador              | Descrição                                                                         |
|-------------------------|-----------------------------------------------------------------------------------|
| purchase                | Compra                                                                            |
| withdraw                | Saque                                                                             |
| postpaid_card_issuance  | Emissão de cartão pós-pago                                                        |

### Enumeradores payment_instrument_entry_status

| Enumerador              | Descrição                               |
|-------------------------|-----------------------------------------|
| processing_conclusion   | Entrada em processamento de conclusão    |
| processing_cancellation | Entrada em processamento de cancelamento |
| concluded                  | Entrada concluída                           |
| canceled                | Entrada cancelada                       |

:::info Observação
A entrada do instrumento de pagamento pode transicionar diretamente de `processing_conclusion` para `processing_cancellation` e `canceled`. Nesse caso, nenhum invoice item é criado.
:::

### Objeto invoice_item

| Campo                              | Tipo    | Descrição                                                                         | Caracteres |
|------------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| `invoice_item_key` *               | uuidv4  | Chave única de identificação do item da fatura no formato uuid v4                | 36         |
| `invoice_key` *                    | uuidv4  | Chave única de identificação da fatura no formato uuid v4                        | 36         |
| `wallet_entry_key`                 | uuidv4  | Chave única de identificação da entrada da carteira no formato uuid v4          | 36         |
| `payment_instrument_entry_key`     | uuidv4  | Chave única de identificação da entrada do instrumento de pagamento no formato uuid v4 | 36 |
| `installment_number` *             | integer | Número da parcela                                                                 | -          |
| `invoice_description` *            | string  | Descrição do item da fatura                                                       | -          |
| `amount` *                         | number  | Valor do item                                                                     | -          |
| `used_limit` *                     | number  | Limite utilizado                                                                 | -          |
| `invoice_item_status` *            | string  | Status do item da fatura                                                          | **[Enumeradores invoice_item_status](#enumeradores-invoice_item_status)** |
| `invoice_item_due_date` *          | string  | Data de vencimento do item (formato YYYY-MM-DD)                                  | 10         |
| `created_at` *                     | string  | Data de criação (formato ISO 8601 UTC)                                           | -          |

### Enumeradores invoice_item_status

| Enumerador | Descrição                               |
|------------|-----------------------------------------|
| concluded    | Item concluído (fatura ao qual o mesmo pertence não foi paga)   |
| canceled  | Item cancelado               |

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 404                      | CIN000007            | Wallet not Found                                   | Wallet with key: abeca0d0-a09d-4b3b-a495-40b553422ced was not found                                                   | Carteira com a chave: abeca0d0-a09d-4b3b-a495-40b553422ced não foi encontrado                                         |
| 404                      | CIN000017            | Payment Instrument Not Found                       | Payment instrument was not found                                                                                         | Instrumento de pagamento não foi encontrado                                                                             |
| 404                      | CIN000086            | Not Found                                          | Payment instrument entry was not found                                                                                   | Transação para instrumento de pagamento não foi encontrada                                                             |

---

# Criação de Instrumento de Pagamento

URL: /documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/criacao_de_instrumento_de_pagamento

A criação de instrumento de pagamento permite registrar um novo meio de pagamento (como cartão pós-pago) para uma carteira existente.

## Request

ENDPOINT /wallet/ WALLET_KEY /payment_instrument
MÉTODO POST

### Path Parameters

| Campo        | Tipo   | Descrição                                    | Caracteres |
|--------------|--------|----------------------------------------------|------------|
| `wallet_key` | uuidv4 | Chave única da carteira no formato UUID v4  | 36         |

Request Body

```json
{
  "request_control_key": "f7947b9d-9be3-49d8-aca2-4b3249e5fa65",
  "owner": {
    "person_type": "natural",
    "name": "João Silva",
    "document_number": "12345678901",
    "birthdate": "1990-01-01",
    "email": "joao.silva@email.com",
    "phone": {
      "number": "99999999",
      "area_code": "11",
      "country_code": "55"
    },
    "address": {
      "street": "Rua das Flores",
      "number": "123",
      "neighborhood": "Centro",
      "postal_code": "01234567",
      "city": "São Paulo",
      "state": "SP",
      "complement": "Apto 1"
    }
  },
  "payment_instrument_type": "postpaid_card",
  "limit_amount": 2000.00,
  "postpaid_card_data": {
    "card_type": "physical",
    "card_name": "Cartão Principal",
    "printed_name": "JOAO SILVA",
    "cvv_rotation_interval_hours": 24,
    "contactless_enabled": true,
    "delivery_address": {
      "street": "Rua das Flores",
      "number": "123",
      "neighborhood": "Centro",
      "postal_code": "01234567",
      "city": "São Paulo",
      "state": "SP",
      "complement": "Apto 1"
    }
  }
}
```

### Request Body Params

| Campo                        | Tipo    | Descrição                                                                          | Caracteres |
|------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `request_control_key`    | uuidv4     | Chave única de identificação da request utilizada pelo cliente.                                            | 36                                                                          |
| `owner`                      | object  | Dados do proprietário do instrumento (pessoa física ou jurídica)                  | **[Objeto owner](#objeto-owner)** |
| `person_key`                 | string  | Chave única de identificação da pessoa no formato UUID v4                         | 36         |
| `payment_instrument_type` *  | string  | Tipo do instrumento de pagamento                                                   | **[Enumeradores payment_instrument_type](#enumeradores-payment_instrument_type)** |
| `limit_amount`               | float  | Limite de crédito do instrumento (deve ser menor ou igual ao limite da carteira)  | -          |
| `postpaid_card_data`         | object  | Dados específicos do cartão pós-pago                                               | **[Objeto postpaid_card_data](#objeto-postpaid_card_data)** |

:::info Campos Condicionais
- **`owner`**: Obrigatório quando não for enviado `person_key`
- **`person_key`**: Obrigatório quando não for enviado `owner`
- **`postpaid_card_data`**: Obrigatório quando `payment_instrument_type` for "postpaid_card"
- Os campos `owner` e `person_key` são mutuamente exclusivos
:::

:::caution Validações de Limite
- O `limit_amount` **não é obrigatório**
- Quando informado, não pode ser maior que o limite de crédito pós-pago da carteira
- Se não informado, o instrumento utilizará o limite total da carteira
:::

### Objeto owner

#### Pessoa Física (`person_type: "natural"`)

| Campo                     | Tipo   | Descrição                                    | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `person_type` *           | string | Tipo da pessoa (deve ser "natural")          | -          |
| `name` *                  | string | Nome completo da pessoa                       | 100        |
| `document_number` *       | string | CPF da pessoa (apenas números)               | 11         |
| `birthdate` *             | string | Data de nascimento (formato YYYY-MM-DD)      | 10         |
| `email` *                 | string | E-mail de contato                            | 254        |
| `phone` *                 | object | Telefone de contato                          | **[Objeto phone](#objeto-phone)** |
| `address` *               | object | Endereço completo                            | **[Objeto address](#objeto-address)** |

#### Pessoa Jurídica (`person_type: "legal"`)

| Campo                     | Tipo   | Descrição                                    | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `person_type` *           | string | Tipo da pessoa (deve ser "legal")            | -          |
| `name` *                  | string | Razão social da empresa                      | 100        |
| `trading_name` *          | string | Nome fantasia da empresa                     | 100        |
| `document_number` *       | string | CNPJ da empresa (apenas números)            | 14         |
| `foundation_date` *       | string | Data de fundação (formato YYYY-MM-DD)       | 10         |
| `email` *                 | string | E-mail de contato                            | 254        |
| `phone` *                 | object | Telefone de contato                          | **[Objeto phone](#objeto-phone)** |
| `address` *               | object | Endereço completo                            | **[Objeto address](#objeto-address)** |
| `legal_representatives` * | array  | Lista de representantes legais (pessoas físicas)               | -          |

### Objeto phone

| Campo                     | Tipo   | Descrição                                    | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `country_code` *          | string | Código do país (DDI)                         | 2-3        |
| `area_code` *             | string | Código de área (DDD)                         | 2          |
| `number` *                | string | Número do telefone                           | 8-9        |

### Objeto address

| Campo                     | Tipo   | Descrição                                    | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `street` *                | string | Nome da rua/avenida                          | 500        |
| `number` *                | string | Número do endereço                           | 10         |
| `neighborhood` *          | string | Bairro                                       | 100        |
| `postal_code` *           | string | CEP (apenas números)                         | 8          |
| `city` *                  | string | Cidade                                       | 100        |
| `state` *                 | string | Estado (UF)                                  | **[Enumeradores state](#enumeradores-state)** |
| `complement`              | string | Complemento do endereço                      | 500        |

### Enumeradores state

| Enumerador | Descrição      |
|-------------|----------------|
| AC          | Acre           |
| AL          | Alagoas        |
| AM          | Amazonas       |
| AP          | Amapá          |
| BA          | Bahia          |
| CE          | Ceará          |
| DF          | Distrito Federal |
| ES          | Espírito Santo |
| GO          | Goiás          |
| MA          | Maranhão       |
| MG          | Minas Gerais    |
| MS          | Mato Grosso do Sul |
| MT          | Mato Grosso    |
| PA          | Pará           |
| PB          | Paraíba        |
| PE          | Pernambuco     |
| PI          | Piauí          |
| PR          | Paraná         |
| RJ          | Rio de Janeiro |
| RN          | Rio Grande do Norte |
| RO          | Rondônia       |
| RR          | Roraima        |
| RS          | Rio Grande do Sul |
| SC          | Santa Catarina |
| SE          | Sergipe        |
| SP          | São Paulo      |
| TO          | Tocantins      |
| EX          | Exceção        |

### Enumeradores payment_instrument_type

| Enumerador      | Descrição        |
|-----------------|------------------|
| postpaid_card   | Cartão pós-pago  |

### Objeto postpaid_card_data

| Campo                           | Tipo    | Descrição                                    | Caracteres |
|---------------------------------|---------|----------------------------------------------|------------|
| `card_type` *                   | string  | Tipo do cartão                               | **[Enumeradores card_type](#enumeradores-card_type)** |
| `card_name` *                   | string  | Nome do cartão                               | 1-50       |
| `printed_name` *                | string  | Nome impresso no cartão                      | 2-26       |
| `cvv_rotation_interval_hours`   | int  | Intervalo de rotação do CVV em horas         | -          |
| `contactless_enabled`           | boolean | Habilita pagamento por aproximação           | -          |
| `delivery_address`              | object  | Endereço de entrega do cartão                | **[Objeto delivery_address](#objeto-delivery_address)** |

### Enumeradores card_type

| Enumerador | Descrição        |
|-------------|------------------|
| virtual     | Cartão virtual   |
| plastic     | Cartão plástico  |

:::info Campos Condicionais
- **`cvv_rotation_interval_hours`**: Obrigatório para `card_type: "virtual"`. Não permitido para `card_type: "plastic"`.
- **`delivery_address`**: Não permitido para `card_type: "virtual"`. Opcional para `card_type: "plastic"`, se não informado será usado o endereço do `owner` ou o previamente cadastrado para a `person_key` informada
- **`contactless_enabled`**: Não permitido para `card_type: "virtual"`, obrigatório para `card_type: "plastic"`
:::

### Objeto delivery_address

| Campo                     | Tipo   | Descrição                                    | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `street` *                | string | Nome da rua/avenida                          | 500        |
| `number` *                | string | Número do endereço                           | 10         |
| `neighborhood` *          | string | Bairro                                       | 100        |
| `postal_code` *           | string | CEP (apenas números)                         | 8          |
| `city` *                  | string | Cidade                                       | 100        |
| `state` *                 | string | Estado (UF)                                  | **[Enumeradores state](#enumeradores-state)** |
| `complement`              | string | Complemento do endereço                      | 500        |

## Response

### Sucesso - Instrumento Criado

STATUS 201

Response Body: Instrumento criado

```json
{
  "request_control_key": "f7947b9d-9be3-49d8-aca2-4b3249e5fa65",
  "payment_instrument_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "postpaid_card_key": "ecf87b4b-fa6e-49c0-a7f0-f2cad6b42d79",
  "owner_person_key": "f2cad6b4-2a68-9572-99a7-2849c8d6ecf8"
}
```

### Response Body Params

| Campo                        | Tipo    | Descrição                                                                         | Caracteres |
|------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| `request_control_key`        | uuidv4  | Chave única de identificação da request utilizada pelo cliente.                   | 36         |
| `payment_instrument_key` *   | uuidv4  | Chave única de identificação do instrumento no formato uuid v4                   | 36         |
| `postpaid_card_key` *        | uuidv4  | Chave única de identificação do cartão pós-pago no formato uuid v4               | 36         |
| `owner_person_key` *         | uuidv4  | Chave única de identificação do proprietário no formato uuid v4                  | 36         |

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Schema Inválido                                                                                                         |
| 404                      | CIN000062            | Not Found                                          | Person not found by person key: e51070e4-7494-468d-a20e-bf14789fa8ff                                                                            | Pessoa não encontrada para a person key: e51070e4-7494-468d-a20e-bf14789fa8ff                                                                   |
| 404                      | CIN000007            | Wallet not Found                                   | Wallet with key: abeca0d0-a09d-4b3b-a495-40b553422ced was not found                                                                             | Carteira com a chave: abeca0d0-a09d-4b3b-a495-40b553422ced não foi encontrado                                                                   |
| 400                      | CIN000073            | Bad Request                                        | Limit amount is greater than postpaid credit limit of the wallet                                                        | Limite é maior que o limite de crédito pós-pago da carteira                                                             |
| 400                      | CIN000074            | Bad Request                                        | Limit amount is greater than ccb limit of the wallet                                                                    | Limite é maior que o limite de ccb da carteira                                                                          |
| 400                      | CIN000072            | Bad Request                                        | Error while creating postpaid card in card service, try again in a few minutes                                          | Erro ao criar postpaid card no serviço de cartão, tente novamente em alguns minutos                                     |
| 400                      | CIN000067            | Bad Request                                        | Error while creating owner of the wallet. Try again in a few minutes                                                    | Erro ao criar owner da carteira. Tente novamente em alguns minutos                                                      |
| 409                      | CIN000099            | Conflict                                           | Request control key already exists.                                                                                     | Request control key já existe.                                                                                          |

---

# Listar Entradas de Instrumentos de Pagamento

URL: /documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/listar_entradas_do_instrumento_de_pagamento

A listagem de entradas de instrumentos de pagamento retornará todas as entradas de um instrumento de pagamento específico que se enquadrarem nos query parameters enviados na request.

## Request

ENDPOINT /wallet/ WALLET_KEY /payment_instrument/ PAYMENT_INSTRUMENT_KEY /payment_instrument_entries
MÉTODO GET

### Path Parameters

| Campo                     | Tipo   | Descrição                                    | Caracteres |
|---------------------------|--------|----------------------------------------------|------------|
| `wallet_key`              | uuidv4 | Chave única da carteira no formato UUID v4  | 36         |
| `payment_instrument_key`  | uuidv4 | Chave única do instrumento de pagamento no formato UUID v4 | 36 |

### Query Parameters

| Campo                                 | Tipo    | Descrição                                    | Caracteres |
|---------------------------------------|---------|----------------------------------------------|------------|
| `payment_instrument_entry_type` *      | string  | Tipo da entrada do instrumento de pagamento  | **[Enumeradores payment_instrument_entry_type](#enumeradores-payment_instrument_entry_type)** |
| `payment_instrument_entry_status` *   | string  | Status da entrada do instrumento             | **[Enumeradores payment_instrument_entry_status](#enumeradores-payment_instrument_entry_status)** |
| `page`                                | integer | Número da página para paginação              | -          |
| `page_size`                           | integer | Quantidade de itens por página               | -          |

:::caution Validações
- **Paginação**: Valores de página e tamanho devem ser inteiros válidos
- **Tamanho da página**: Máximo de 100 itens por página
:::

### Enumeradores payment_instrument_entry_type

| Enumerador              | Descrição                                                                         |
|-------------------------|-----------------------------------------------------------------------------------|
| purchase                | Compra                                                                            |
| withdraw                | Saque                                                                             |
| postpaid_card_issuance  | Emissão de cartão pós-pago                                                        |

### Enumeradores payment_instrument_entry_status

| Enumerador              | Descrição                               |
|-------------------------|-----------------------------------------|
| processing_conclusion   | Entrada em processamento de conclusão    |
| processing_cancellation | Entrada em processamento de cancelamento |
| concluded                  | Entrada concluída     |
| canceled                | Entrada cancelada                       |

:::info Observação
A entrada do instrumento de pagamento pode transicionar diretamente de `processing_conclusion` para `processing_cancellation` e `canceled`. Nesse caso, nenhum invoice item é criado.
:::

## Response

STATUS 200

Response Body: Lista de entradas de instrumentos de pagamento

```json
{
  "data": [
    {
      "payment_instrument_entry_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "payment_instrument_entry_amount": 150.00,
      "payment_instrument_entry_type": "purchase",
      "payment_instrument_entry_status": "concluded",
      "payment_instrument_entry_data": {
        "merchant_name": "Merchant Name",
        "merchant_country": "Merchant Country",
        "merchant_postal_code": "Merchant Postal Code",
        "merchant_city": "Merchant City",
        "merchant_street": "Merchant Street"
      },
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "payment_instrument_entry_key": "9db81efb-0ac1-5b79-0683-00b8395a9e7",
      "payment_instrument_entry_amount": 200.00,
      "payment_instrument_entry_type": "withdraw",
      "payment_instrument_entry_status": "canceled",
      "payment_instrument_entry_data": {
        "merchant_name": "Merchant Name",
        "merchant_country": "Merchant Country",
        "merchant_postal_code": "Merchant Postal Code",
        "merchant_city": "Merchant City",
        "merchant_street": "Merchant Street"
      },
      "created_at": "2024-01-14T14:45:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "rows_per_page": 100
  }
}
```

### Response Body Params

| Campo            | Tipo         | Descrição                             | Caracteres                                  |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `data` *         | object array | Entradas de instrumentos de pagamento | **[Objeto payment_instrument_entry](#objeto-payment_instrument_entry)** |
| `pagination` *   | object       | Informações de paginação              | **[Objeto pagination](#objeto-pagination)** |

### Objeto payment_instrument_entry

| Campo                                 | Tipo    | Descrição                                                                         | Caracteres |
|---------------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| `payment_instrument_entry_key` *      | uuidv4  | Chave única de identificação da entrada no formato uuid v4                       | 36         |
| `payment_instrument_entry_amount` *   | float  | Valor da entrada                                                                  | -          |
| `payment_instrument_entry_type` *     | string  | Tipo da entrada do instrumento de pagamento                                      | **[Enumeradores payment_instrument_entry_type](#enumeradores-payment_instrument_entry_type)** |
| `payment_instrument_entry_status` *  | string  | Status da entrada do instrumento                                                 | **[Enumeradores payment_instrument_entry_status](#enumeradores-payment_instrument_entry_status)** |
| `payment_instrument_entry_data`      | object  | Dados do adicionais | **[Objeto payment_instrument_entry_data](#objeto-payment_instrument_entry_data)** |
| `created_at` *                       | string  | Data de criação (formato ISO 8601 UTC)                                           | -          |

### Objeto payment_instrument_entry_data (purchase | withdraw)

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `merchant_name` *          | string  | Nome do estabelecimento comercial                                                 | -          |
| `merchant_country` *       | string  | País do estabelecimento comercial                                                 | -          |
| `merchant_postal_code` *   | string  | Código postal do estabelecimento comercial                                        | -          |
| `merchant_city` *          | string  | Cidade do estabelecimento comercial                                               | -          |
| `merchant_street` *        | string  | Rua do estabelecimento comercial                                                  | -          |

### Objeto payment_instrument_entry_data (postpaid_card_issuance)

| Campo                           | Tipo    | Descrição                                                                          | Caracteres |
|---------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `postpaid_card_issuance_name` * | string  | Nome da emissão do cartão pós-pago                                                 | -          |
| `payment_instrument_key` *      | string  | Chave única do instrumento de pagamento no formato UUID v4                        | 36         |
| `postpaid_card_key` *           | string  | Chave única do cartão pós-pago no formato UUID v4                                  | 36         |

:::info Observação
Esta entrada existe apenas para cartões de carteira de cartão consignado.
:::

### Objeto pagination

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `current_page` *           | integer | Página atual                                                 | -      |
| `rows_per_page` *          | integer | Itens por página                                             | -      |

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | CIN000069            | Bad Request                                        | Invalid integer value for page or size query string parameters                                                           | Valor inválido para parâmetros de página ou tamanho de página                                                           |
| 400                      | CIN000084            | Bad Request                                        | Invalid query payment instrument entry status                                                                           | Status de consulta de instrumento de pagamento inválido                                                                |
| 400                      | CIN000085            | Bad Request                                        | Invalid query payment instrument entry type                                                                             | Tipo de consulta de instrumento de pagamento inválido                                                                  |
| 404                      | CIN000007            | Wallet not Found                                   | Wallet with key: abeca0d0-a09d-4b3b-a495-40b553422ced was not found                                                   | Carteira com a chave: abeca0d0-a09d-4b3b-a495-40b553422ced não foi encontrado                                         |
| 404                      | CIN000017            | Payment Instrument Not Found                       | Payment instrument was not found                                                                                         | Instrumento de pagamento não foi encontrado                                                                             |

---

# Listar Instrumentos de Pagamento

URL: /documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/listar_instrumentos_de_pagamento

A listagem de instrumentos de pagamento retornará todos os instrumentos de pagamento de uma carteira específica que se enquadrarem nos query parameters enviados na request.

## Request

ENDPOINT /wallet/ WALLET_KEY /payment_instruments
MÉTODO GET

### Path Parameters

| Campo        | Tipo   | Descrição                                    | Caracteres |
|--------------|--------|----------------------------------------------|------------|
| `wallet_key` | uuidv4 | Chave única da carteira no formato UUID v4  | 36         |

### Query Parameters

| Campo                        | Tipo    | Descrição                                    | Caracteres |
|------------------------------|---------|----------------------------------------------|------------|
| `owner_document_number`      | string  | CPF/CNPJ do proprietário do instrumento      | 11-14      |
| `payment_instrument_type` *  | string  | Tipo do instrumento de pagamento                                                  | **[Enumeradores payment_instrument_type](#enumeradores-payment_instrument_type)** |
| `payment_instrument_status` *| string  | Status do instrumento                                                             | **[Enumeradores payment_instrument_status](#enumeradores-payment_instrument_status)** |
| `page`                       | integer | Número da página para paginação              | -          |
| `page_size`                  | integer | Quantidade de itens por página               | -          |

:::caution Validações
- **Paginação**: Valores de página e tamanho devem ser inteiros válidos
- **Tamanho da página**: Máximo de 100 itens por página
:::

### Enumeradores payment_instrument_type

| Enumerador      | Descrição        |
|-----------------|------------------|
| postpaid_card   | Cartão pós-pago  |

### Enumeradores payment_instrument_status

| Enumerador | Descrição                               |
|------------|-----------------------------------------|
| active     | Instrumento ativo e disponível para uso |
| rejected   | Instrumento rejeitado                   |
| canceled   | Instrumento cancelado                   |

## Response

STATUS 200

Response Body: Lista de instrumentos de pagamento

```json
{
  "data": [
    {
      "request_control_key": "f7947b9d-9be3-49d8-aca2-4b3249e5fa65",
      "payment_instrument_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "postpaid_card_key": "ecf87b4b-fa6e-49c0-a7f0-f2cad6b42d79",
      "owner_person_key": "f2cad6b4-2a68-9572-99a7-2849c8d6ecf8",
      "owner_document_number": "12345678901",
      "payment_instrument_type": "postpaid_card",
      "payment_instrument_status": "active",
      "limit_amount": 2000.00,
      "used_limit": 500.00,
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "request_control_key": "3aaad5ea-3a0f-4018-93a8-ab02f5207833",
      "payment_instrument_key": "9db81efb-0ac1-5b79-0683-00b8395a9e7",
      "postpaid_card_key": "f3dad7c5-3b79-0683-11c8-395b9e7f2cad",
      "owner_person_key": "g4ebe8d6-4c8a-1794-22d9-406c0f8g3dbe",
      "owner_document_number": "98765432100",
      "payment_instrument_type": "postpaid_card",
      "payment_instrument_status": "canceled",
      "limit_amount": 1500.00,
      "used_limit": 0.00,
      "created_at": "2024-01-14T14:45:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "rows_per_page": 100,
  }
}
```

### Response Body Params

| Campo            | Tipo         | Descrição                             | Caracteres                                  |
|------------------|--------------|---------------------------------------|---------------------------------------------|
| `data` *         | object array | Instrumentos de pagamento             | **[Objeto payment_instrument](#objeto-payment_instrument)**   |
| `pagination` *   | object       | Informações de paginação              | **[Objeto pagination](#objeto-pagination)** |

### Objeto payment_instrument

| Campo                        | Tipo    | Descrição                                                                         | Caracteres |
|------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| `request_control_key`        | uuidv4  | Chave única de identificação da request utilizada pelo cliente.                   | 36         |
| `payment_instrument_key` *   | uuidv4  | Chave única de identificação do instrumento no formato uuid v4                   | 36         |
| `postpaid_card_key` *        | uuidv4  | Chave única de identificação do cartão pós-pago no formato uuid v4               | 36         |
| `owner_person_key` *         | uuidv4  | Chave única de identificação do proprietário no formato uuid v4                  | 36         |
| `owner_document_number` *    | string  | CPF/CNPJ do proprietário do instrumento                                          | 11 ou 14   |
| `payment_instrument_type` *  | string  | Tipo do instrumento de pagamento                                                  | **[Enumeradores payment_instrument_type](#enumeradores-payment_instrument_type)** |
| `payment_instrument_status` *| string  | Status do instrumento                                                             | **[Enumeradores payment_instrument_status](#enumeradores-payment_instrument_status)** |
| `limit_amount` *             | float  | Limite de crédito do instrumento                                                  | -          |
| `used_limit` *               | float  | Limite utilizado do instrumento                                                   | -          |
| `created_at` *               | string  | Data de criação (formato ISO 8601 UTC)                                           | -          |

### Objeto pagination

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|--------------------------------------------------------------|
| `current_page` *           | integer | Página atual                                                 | -      |
| `rows_per_page` *          | integer | Itens por página                                             | -      |

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (pt-br)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | CIN000069            | Bad Request                                        | Invalid integer value for page or size query string parameters                                                           | Valor inválido para parâmetros de página ou tamanho de página                                                           |
| 400                      | CIN000070            | Bad Request                                        | Invalid query payment instrument status                                                                                 | Status de consulta de instrumento de pagamento inválido                                                                |
| 400                      | CIN000071            | Bad Request                                        | Invalid query payment instrument type                                                                                   | Tipo de consulta de instrumento de pagamento inválido                                                                  |
| 404                      | CIN000007            | Wallet not Found                                   | Wallet with key: abeca0d0-a09d-4b3b-a495-40b553422ced was not found                                                   | Carteira com a chave: abeca0d0-a09d-4b3b-a495-40b553422ced não foi encontrado                                         |

---

# Simulação de cenários

URL: /documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/simulacao_de_cenarios

Esta página descreve como simular a criação e cancelamento de entradas de instrumentos de pagamento para testar o fluxo de transações com cartões pós-pagos. Essas simulações são úteis para homologação e testes de integração.

:::info Informação
Essas requisições simulam transações externas e retornam o status HTTP com a chave da entrada criada ou cancelada.
:::

## 1 - Simulação de criação de entrada de instrumento de pagamento

Simula a criação de uma entrada de instrumento de pagamento (transação), como uma compra ou saque realizado com o cartão pós-pago. A entrada será automaticamente vinculada a itens de fatura conforme a configuração de parcelamento.

ENDPOINT /mock/invoice/payment_instrument/ POSTPAID_CARD_KEY /payment_instrument_entry
MÉTODO POST

### Path Parameters

| Campo                        | Tipo   | Descrição                                    | Caracteres |
|------------------------------|--------|----------------------------------------------|------------|
| `postpaid_card_key` *           | string  | Chave única do cartão pós-pago no formato UUID v4                                  | 36         |

Request Body

```json
{
    "request_control_key": "f7947b9d-9be3-49d8-aca2-4b3249e5fa65",
    "payment_instrument_entry_amount": 100.50,
    "number_of_installments": 3,
    "installment_amount": 33.50,
    "payment_instrument_entry_type": "purchase",
    "payment_instrument_entry_data": {
        "merchant_name": "Test Merchant",
        "merchant_country": "BR",
        "merchant_postal_code": "01310-100",
        "merchant_city": "São Paulo",
        "merchant_street": "Av. Paulista"
    }
}
```

### Objeto Request Body

| Campo                                    | Tipo    | Descrição                                                                          | Máx. Caract. |
|------------------------------------------|---------|------------------------------------------------------------------------------------|--------------|
| `request_control_key` *                  | uuidv4  | Chave única de identificação da requisição utilizada pelo cliente                 | 36           |
| `payment_instrument_entry_amount` *       | float   | Valor total da transação                                                          | -            |
| `number_of_installments` *                | integer | Número de parcelas da transação                                                   | -            |
| `installment_amount` *                    | float   | Valor de cada parcela                                                             | -            |
| `payment_instrument_entry_type` *         | string  | Tipo da entrada do instrumento de pagamento                                        | **[Enumeradores payment_instrument_entry_type](#enumeradores-payment_instrument_entry_type)** |
| `payment_instrument_entry_data` *         | object  | Dados adicionais da transação                                                     | **[Objeto payment_instrument_entry_data](#objeto-payment_instrument_entry_data)** |

### Enumeradores payment_instrument_entry_type

| Enumerador              | Descrição                                                                         |
|-------------------------|-----------------------------------------------------------------------------------|
| `purchase`              | Compra realizada com o cartão                                                    |
| `withdraw`              | Saque realizado com o cartão                                                     |
| `postpaid_card_issuance`| Emissão de cartão pós-pago                                                        |

### Objeto payment_instrument_entry_data

| Campo                      | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------|---------|------------------------------------------------------------------------------------|------------|
| `merchant_name` *          | string  | Nome do estabelecimento comercial                                                 | -          |
| `merchant_country` *        | string  | País do estabelecimento comercial                                                | -          |
| `merchant_postal_code` *    | string  | Código postal do estabelecimento comercial                                        | -          |
| `merchant_city` *           | string  | Cidade do estabelecimento comercial                                               | -          |
| `merchant_street` *         | string  | Rua do estabelecimento comercial                                                  | -          |

### Response

STATUS 201

Response Body

```json
{
    "payment_instrument_entry_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6"
}
```

### Response Body Params

| Campo                            | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `payment_instrument_entry_key` * | uuidv4  | Chave única de identificação da entrada criada no formato UUID v4                | 36         |

:::tip Comportamento
- A simulação cria uma entrada de instrumento de pagamento com status `active`
- A entrada será automaticamente vinculada a itens de fatura (invoice items) conforme o número de parcelas informado
- Os itens de fatura serão organizados em faturas (invoices) conforme a configuração de fechamento da carteira
- O limite do instrumento de pagamento e da carteira serão validados antes de permitir a criação da entrada
:::

## 2 - Simulação de cancelamento de entrada de instrumento de pagamento

Simula o cancelamento de uma entrada de instrumento de pagamento existente, alterando seu status para `canceled` e liberando o limite utilizado.

ENDPOINT /mock/invoice/payment_instrument/ POSTPAID_CARD_KEY /payment_instrument_entry/ REQUEST_CONTROL_KEY /cancel
MÉTODO PATCH

### Path Parameters

| Campo                        | Tipo   | Descrição                                    | Caracteres |
|------------------------------|--------|----------------------------------------------|------------|
| `postpaid_card_key` *           | string  | Chave única do cartão pós-pago no formato UUID v4                                  | 36         |
| `request_control_key` *       | uuidv4 | Chave única de identificação da requisição original utilizada na criação da entrada | 36 |

Request Body

```json
{
    "payment_instrument_entry_amount": 100.50
}
```

### Objeto Request Body

| Campo                            | Tipo    | Descrição                                                                          | Máx. Caract. |
|----------------------------------|---------|------------------------------------------------------------------------------------|--------------|
| `payment_instrument_entry_amount` * | float   | Valor do cancelamento.                                                          | -            |

### Response

STATUS 200

Response Body

```json
{
    "payment_instrument_entry_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6"
}
```

### Response Body Params

| Campo                            | Tipo    | Descrição                                                                          | Caracteres |
|----------------------------------|---------|------------------------------------------------------------------------------------|------------|
| `payment_instrument_entry_key` * | uuidv4  | Chave única de identificação da entrada cancelada no formato UUID v4             | 36         |

:::tip Comportamento
- **Faturas abertas**: Cancelamentos em faturas abertas liberam o limite imediatamente e removem o valor da fatura
- **Faturas fechadas**: Cancelamentos em faturas fechadas criam chargebacks que aparecerão no campo `invoice_payments_chargebacks` quando forem utilizados na próxima fatura
:::

---

# Webhooks de Carteira

URL: /documentation/cartao_pos_pago/faturas/webhooks/carteira

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

## Introdução

Após a criação de uma carteira (`wallet`) dentro do nosso sistema, serão enviados webhooks com os seguintes status:

| Enumerador                    | Tradução               | Descrição                                                  |
|-------------------------------|------------------------|------------------------------------------------------------|
|  active                       | ativa                  | Carteira ativa e disponível para uso                       |
|  rejected                     | rejeitada              | Carteira rejeitada na análise KYC                          |

:::info Informação
O timeout para resposta de nosso webhooks é de 10 segundos.
:::

## Exemplos
----

### Confirmação de abertura

Webhook Body

```json
{
	"webhook_type": "baas.invoice.wallet",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"wallet_key": "fd86d9b1-2a5e-4e03-9a59-a043c7632c97",
		"owner_person_key": "ecf87b4b-fa6e-49c0-a7f0-f2cad6b42d79",
		"wallet_status": "active"
	}
}
```

### Campos do Webhook

| Campo              | Tipo    | Descrição                                                                         | Caracteres |
|--------------------|---------|-----------------------------------------------------------------------------------|------------|
| wallet_key         | string  | Chave única de identificação da carteira no formato uuid v4                       | 36         |
| owner_person_key   | string  | Chave única de identificação do proprietário da carteira no formato uuid v4       | 36         |
| wallet_status      | string  | Status da carteira                                                                | **[Enumeradores wallet_status](#enumeradores-wallet_status)** |

### Enumeradores wallet_status

| Enumerador | Descrição                                                                         |
|------------|-----------------------------------------------------------------------------------|
| active     | Carteira ativa e disponível para uso                                             |
| rejected   | Carteira rejeitada na análise KYC                                                |

---

# Webhooks de Entradas de Carteira

URL: /documentation/cartao_pos_pago/faturas/webhooks/entrada_da_carteira

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

## Introdução

Após a criação de uma entrada de carteira (`wallet_entry`) dentro do nosso sistema, serão enviados webhooks com os seguintes status:

| Enumerador                    | Tradução               | Descrição                                                  |
|-------------------------------|------------------------|------------------------------------------------------------|
|  concluded                       | concluída                  | Entrada de carteira concluída            |

:::info Informação
O timeout para resposta de nosso webhooks é de 10 segundos.
:::

## Exemplos
----

### Confirmação de criação

Webhook Body

```json
{
	"webhook_type": "baas.invoice.wallet_entry",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"wallet_key": "ecf87b4b-fa6e-49c0-a7f0-f2cad6b42d79",
		"wallet_entry_key": "fd86d9b1-2a5e-4e03-9a59-a043c7632c97",
        "wallet_entry_amount": 150.00,
		"wallet_entry_type": "revolving_credit",
		"wallet_entry_status": "concluded"
	}
}
```

### Campos do Webhook

| Campo                    | Tipo    | Descrição                                                                         | Caracteres |
|-------------------------|---------|-----------------------------------------------------------------------------------|------------|
| wallet_key              | string  | Chave única de identificação da carteira no formato uuid v4                       | 36         |
| wallet_entry_key        | string  | Chave única de identificação da entrada da carteira no formato uuid v4            | 36         |
| wallet_entry_amount     | number  | Valor da entrada da carteira                                                       | -          |
| wallet_entry_type       | string  | Tipo da entrada da carteira                                                       | **[Enumeradores wallet_entry_type](#enumeradores-wallet_entry_type)** |
| wallet_entry_status     | string  | Status da entrada da carteira                                                     | **[Enumeradores wallet_entry_status](#enumeradores-wallet_entry_status)** |

### Enumeradores wallet_entry_type

| Enumerador        | Descrição                                                                         |
|-------------------|-----------------------------------------------------------------------------------|
| revolving_credit  | Crédito rotativo                                                                  |
| payroll_withdraw  | Saque de folha                                                                    |
| payroll_overdue   | Atraso de folha                                                                   |

:::info Tipos de Entrada de Carteira
- **`revolving_credit`**: Valores de crédito disponibilizados para o cliente
- **`payroll_withdraw`**: Dívida gerada pelo saque do limite e que vai ser descontada todo mês do INSS
- **`payroll_overdue`**: Dívida gerada pelo não pagamento da fatura e também vai ser descontada todo mês do INSS
:::

### Enumeradores wallet_entry_status

| Enumerador | Descrição                                                                         |
|------------|-----------------------------------------------------------------------------------|
| concluded     | Entrada de carteira concluída                                   |

---

# Webhooks de Entradas de Instrumento de Pagamento

URL: /documentation/cartao_pos_pago/faturas/webhooks/entrada_do_instrumento_de_pagamento

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

## Introdução

Após a criação de uma entrada de instrumento de pagamento (`payment_instrument_entry`) dentro do nosso sistema, serão enviados webhooks com os seguintes status:

| Enumerador                    | Tradução               | Descrição                                                  |
|-------------------------------|------------------------|------------------------------------------------------------|
|  processing_conclusion        | processando conclusão   | Entrada de instrumento de pagamento em processamento de conclusão |
|  processing_cancellation      | processando cancelamento | Entrada de instrumento de pagamento em processamento de cancelamento |
|  concluded                       | concluída                  | Entrada de instrumento de pagamento concluída |
|  canceled                     | cancelada              | Entrada de instrumento de pagamento foi cancelada          |

:::info Informação
O timeout para resposta de nosso webhooks é de 10 segundos.
:::

## Exemplos
----

### Confirmação de criação

Webhook Body

```json
{
	"webhook_type": "baas.invoice.payment_instrument_entry",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"payment_instrument_key": "ecf87b4b-fa6e-49c0-a7f0-f2cad6b42d79",
		"payment_instrument_entry_key": "fd86d9b1-2a5e-4e03-9a59-a043c7632c97",
		"payment_instrument_entry_amount": 150.00,
		"payment_instrument_entry_type": "purchase",
		"payment_instrument_entry_status": "concluded"
	}
}
```

### Confirmação de cancelamento

Webhook Body

```json
{
	"webhook_type": "baas.invoice.payment_instrument_entry",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"payment_instrument_key": "ecf87b4b-fa6e-49c0-a7f0-f2cad6b42d79",
		"payment_instrument_entry_key": "fd86d9b1-2a5e-4e03-9a59-a043c7632c97",
		"payment_instrument_entry_amount": 150.00,
		"payment_instrument_entry_type": "purchase",
		"payment_instrument_entry_status": "canceled"
	}
}
```

### Processando ativação

Webhook Body

```json
{
	"webhook_type": "baas.invoice.payment_instrument_entry",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"payment_instrument_key": "ecf87b4b-fa6e-49c0-a7f0-f2cad6b42d79",
		"payment_instrument_entry_key": "fd86d9b1-2a5e-4e03-9a59-a043c7632c97",
		"payment_instrument_entry_amount": 150.00,
		"payment_instrument_entry_type": "purchase",
		"payment_instrument_entry_status": "processing_conclusion"
	}
}
```

### Processando cancelamento

Webhook Body

```json
{
	"webhook_type": "baas.invoice.payment_instrument_entry",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"payment_instrument_key": "ecf87b4b-fa6e-49c0-a7f0-f2cad6b42d79",
		"payment_instrument_entry_key": "fd86d9b1-2a5e-4e03-9a59-a043c7632c97",
		"payment_instrument_entry_amount": 150.00,
		"payment_instrument_entry_type": "purchase",
		"payment_instrument_entry_status": "processing_cancellation"
	}
}
```

### Campos do Webhook

| Campo                              | Tipo    | Descrição                                                                         | Caracteres |
|------------------------------------|---------|-----------------------------------------------------------------------------------|------------|
| payment_instrument_key             | string  | Chave única de identificação do instrumento de pagamento no formato uuid v4       | 36         |
| payment_instrument_entry_key       | string  | Chave única de identificação da entrada do instrumento de pagamento no formato uuid v4 | 36         |
| payment_instrument_entry_amount   | number  | Valor da entrada do instrumento de pagamento                                      | -          |
| payment_instrument_entry_type     | string  | Tipo da entrada do instrumento de pagamento                                        | **[Enumeradores payment_instrument_entry_type](#enumeradores-payment_instrument_entry_type)** |
| payment_instrument_entry_status   | string  | Status da entrada do instrumento de pagamento                                      | **[Enumeradores payment_instrument_entry_status](#enumeradores-payment_instrument_entry_status)** |

### Enumeradores payment_instrument_entry_type

| Enumerador              | Descrição                                                                         |
|-------------------------|-----------------------------------------------------------------------------------|
| purchase                | Compra                                                                            |
| withdrawal              | Saque                                                                             |
| postpaid_card_issuance  | Emissão de cartão pós-pago                                                        |

### Enumeradores payment_instrument_entry_status

| Enumerador              | Descrição                                                                         |
|-------------------------|-----------------------------------------------------------------------------------|
| processing_conclusion   | Entrada de instrumento de pagamento em processamento de conclusão                  |
| processing_cancellation | Entrada de instrumento de pagamento em processamento de cancelamento              |
| concluded                  | Entrada de instrumento de pagamento concluída                  |
| canceled                | Entrada de instrumento de pagamento foi cancelada                                 |

:::info Observação
A entrada do instrumento de pagamento pode transicionar diretamente de `processing_conclusion` para `processing_cancellation` e `canceled`. Nesse caso, nenhum invoice item é criado.
:::

---

# Webhooks de Fatura

URL: /documentation/cartao_pos_pago/faturas/webhooks/fatura

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

## Introdução

Após o fechamento de uma fatura (`invoice`) dentro do nosso sistema, será enviado um webhook com a mudança de status da fatura:

| Enumerador                    | Tradução               | Descrição                                                  |
|-------------------------------|------------------------|------------------------------------------------------------|
|  processing_closing           | processando fechamento | Fatura em processamento de fechamento                      |
|  processing_expiration       | processando expiração  | Fatura em processamento de expiração                       |
|  closed                       | fechada                | Fatura fechada, não recebe mais itens e os pagamentos foram processados |
|  processing_payment              | aguardando pagamento   | Fatura aguardando pagamento (aplicável apenas para carteiras do tipo `payroll` quando há valor restante a ser pago) |
|  paid                         | paga                   | Fatura paga                                                |

:::info Informação
O timeout para resposta de nosso webhooks é de 10 segundos.
:::

## Exemplos

### Confirmação de fechamento de fatura

Webhook Body

```json
{
	"webhook_type": "baas.invoice.invoice_status_change",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"invoice_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
		"total_amount": 350.00,
		"paid_amount": 0.00,
		"closing_date": "2024-01-31",
		"due_date": "2024-02-15",
		"invoice_status": "closed"
	}
}
```

### Fatura aguardando pagamento (carteira payroll)

Webhook Body

```json
{
	"webhook_type": "baas.invoice.invoice_status_change",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"invoice_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
		"total_amount": 350.00,
		"paid_amount": 0.00,
		"closing_date": "2024-01-31",
		"due_date": "2024-02-15",
		"invoice_status": "processing_payment"
	}
}
```

### Campos do Webhook

| Campo            | Tipo    | Descrição                                                                         | Caracteres |
|-----------------|---------|-----------------------------------------------------------------------------------|------------|
| invoice_key     | string  | Chave única de identificação da fatura no formato uuid v4                        | 36         |
| total_amount    | number  | Valor total da fatura                                                             | -          |
| paid_amount     | number  | Valor pago da fatura                                                               | -          |
| closing_date    | string  | Data de fechamento da fatura (formato YYYY-MM-DD)                                | 10         |
| due_date        | string  | Data de vencimento da fatura (formato YYYY-MM-DD)                                 | 10         |
| invoice_status  | string  | Status da fatura                                                                 | **[Enumeradores invoice_status](#enumeradores-invoice_status)** |

### Enumeradores invoice_status

| Enumerador            | Descrição                                                                         |
|-----------------------|-----------------------------------------------------------------------------------|
| processing_closing    | Fatura em processamento de fechamento                                             |
| processing_expiration | Fatura em processamento de expiração                                              |
| closed                | Fatura fechada, não recebe mais itens e os pagamentos foram processados          |
| processing_payment       | Fatura aguardando pagamento (aplicável apenas para carteiras do tipo `payroll` quando há valor restante a ser pago) |
| paid                  | Fatura paga                                                                       |

---

# Webhooks de Pagamento de Fatura

URL: /documentation/cartao_pos_pago/faturas/webhooks/pagamento_da_fatura

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

## Introdução

Após a mudança de status de um pagamento de fatura (`invoice_payment`) dentro do nosso sistema, será enviado um webhook com a mudança de status do pagamento:

| Enumerador                    | Tradução               | Descrição                                                  |
|-------------------------------|------------------------|------------------------------------------------------------|
|  processing_payment              | aguardando pagamento   | Pagamento de fatura aguardando pagamento                   |
|  paid                         | pago                   | Pagamento de fatura pago                                   |

:::info Informação
O timeout para resposta de nosso webhooks é de 10 segundos.
:::

## Exemplos

### Pagamento de fatura (payroll_discount)

Webhook Body

```json
{
	"webhook_type": "baas.invoice.invoice_payment_status_change",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"wallet_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
		"invoice_payment_key": "3571e292-3a83-4011-904d-20ee963022ef",
		"total_amount": 350.00,
		"paid_amount": 0.00,
		"payment_date": "2024-02-15",
		"invoice_payment_type": "payroll_discount",
		"invoice_payment_status": "processing_payment"
	}
}
```

### Pagamento de fatura (bank_slip)

Webhook Body

```json
{
	"webhook_type": "baas.invoice.invoice_payment_status_change",
	"webhook_datetime": "2024-08-13T21:35:55.679Z",
	"data": {
		"wallet_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
		"invoice_payment_key": "3571e292-3a83-4011-904d-20ee963022ef",
		"total_amount": 350.00,
		"paid_amount": 0.00,
		"payment_date": "2024-02-15",
		"invoice_payment_type": "bank_slip",
		"invoice_payment_status": "processing_payment"
	}
}
```

### Campos do Webhook

| Campo                    | Tipo    | Descrição                                                                         | Caracteres |
|-------------------------|---------|-----------------------------------------------------------------------------------|------------|
| wallet_key              | string  | Chave única de identificação da carteira no formato uuid v4                       | 36         |
| invoice_payment_key     | string  | Chave única de identificação do pagamento de fatura no formato uuid v4            | 36         |
| total_amount            | number  | Valor total do pagamento de fatura                                                | -          |
| paid_amount             | number  | Valor pago do pagamento de fatura                                                 | -          |
| payment_date            | string  | Data do pagamento (formato YYYY-MM-DD)                                           | 10         |
| invoice_payment_type    | string  | Tipo do pagamento de fatura                                                       | **[Enumeradores invoice_payment_type](#enumeradores-invoice_payment_type)** |
| invoice_payment_status  | string  | Status do pagamento de fatura                                                     | **[Enumeradores invoice_payment_status](#enumeradores-invoice_payment_status)** |

### Enumeradores invoice_payment_type

| Enumerador        | Descrição                                                                         |
|-------------------|-----------------------------------------------------------------------------------|
| bank_slip         | Boleto bancário                                                                  |
| payroll_discount  | Desconto via folha de pagamento                                                  |

### Enumeradores invoice_payment_status

| Enumerador            | Descrição                                                                         |
|-----------------------|-----------------------------------------------------------------------------------|
| processing_payment       | Pagamento de fatura aguardando pagamento                                         |
| paid                  | Pagamento de fatura pago                                                          |

:::info Observação
- Para pagamentos do tipo `payroll_discount`: o pagamento é criado no momento do fechamento da fatura com o status `processing_payment` e o desconto é solicitado no INSS. Quando o pagamento do desconto é realizado, o status muda para `paid`.
- Para pagamentos do tipo `bank_slip`: o pagamento é criado com status `processing_payment` quando recebemos o aviso de pagamento do boleto. No momento da liquidação do boleto, o status muda para `paid`. O pagamento pode ser criado com status `paid` diretamente caso não seja recebido um aviso de pagamento.
:::

---

# Introdução

URL: /documentation/cartao_pos_pago/introducao

## Cartão Pós-Pago

As APIs para emissão de cartões pós-pago oferecem aos parceiros da QI Tech uma maneira simples e eficiente de permitir que seus clientes solicitem e emitam Cartões Pós-Pagos, tanto **físicos** quanto **virtuais**.

Na QI Tech, proporcionamos aos nossos parceiros a oportunidade de se tornarem subemissores. Por meio de nossas APIs, eles podem oferecer aos seus próprios clientes a possibilidade de emitir cartões pós-pagos, criando uma solução completa para serviços bancários e financeiros.

Para compreender melhor nosso sistema, apresentamos uma visão geral de como funciona o ecossistema de cartões pós-pagos. Contudo, é importante ressaltar que, assim como em todas as nossas APIs, a liberação do serviço deve ser realizada junto ao nosso time, e as **[chamadas são autenticadas](/documentation/primeiros_passos/teste_de_autenticacao)**.

O cartão pós-pago é um cartão vinculado a uma linha de crédito que permite ao portador realizar transações, com o pagamento sendo feito posteriormente. Diferente dos cartões pré-pagos, os cartões pós-pagos não exigem que o saldo da conta seja pré-carregado. O usuário pode realizar compras e pagar posteriormente, conforme o limite de crédito aprovado.

As transações realizadas por meio do cartão pós-pago serão cobradas na fatura do portador, com um prazo determinado para o pagamento. Caso o pagamento não seja realizado até a data de vencimento, o portador pode estar sujeito a encargos financeiros, como juros e taxas.

## Programa

Para realizar a emissão de um cartão pós-pago, o parceiro precisa ter um programa configurado na integração com a QI Tech. O programa define as regras e parâmetros necessários para a emissão de cartões em conformidade com as bandeiras, como o VISA.

Aqui estão algumas informações importantes sobre o programa:

* **Tipo do programa** - Refere-se à modalidade de utilização do cartão. Neste caso, trata-se da modalidade Pós-Pago.
* **Bandeira** - Utilizamos a bandeira VISA para os cartões emitidos.
* **Layout do cartão** - Refere-se ao design do cartão, tanto para o modelo físico quanto virtual, que será exibido na interface gráfica.

:::caution Atenção
Para configurar um novo programa de cartões pós-pago, é necessário envolver os times comerciais e de implantação da QI Tech.
:::

## Carteira (Wallet)

Para emitir cartões de crédito pós-pagos, é necessário primeiro criar uma **carteira (wallet)** que organiza a fatura do cliente. A carteira funciona como um "conta" onde ficam todos os cartões e configurações de faturamento.

:::info O que é uma Wallet
A **wallet** é como a conta do cliente onde ficam todos os cartões e faturas:

- **Uma wallet = fatura**: Cada carteira corresponde à fatura de um cliente específico (identificado por CPF/CNPJ)
- **Múltiplos meios de pagamento**: A mesma wallet pode ter diferentes instrumentos de pagamento (cartões, PIX, etc.)
- **Instrumentos separados**: Após criar a wallet, será necessário criar separadamente os instrumentos de pagamento (cartões de crédito, limites, etc.)
- **Gestão centralizada**: A wallet centraliza todas as operações e configurações relacionadas àquele cliente
:::

Para mais detalhes sobre a criação de carteiras, consulte a **[documentação completa de criação de carteira](/documentation/cartao_pos_pago/faturas/carteira/criacao_de_carteira)**.

## Fluxo de Emissão

Para emitir cartões de crédito pós-pagos, o processo segue uma sequência lógica que começa com a criação de uma carteira (wallet) para o cliente. Esta carteira funciona como um "conta" para organizar todos os cartões e configurações de faturamento.

Após a criação da carteira, é necessário criar um **instrumento de pagamento** do tipo `postpaid_card`. Este instrumento é responsável por gerenciar todas as transações e compras realizadas com o cartão. Ao criar o instrumento, um cartão físico ou virtual é criado automaticamente conforme solicitado.

:::info Instrumento de Pagamento
O instrumento de pagamento do tipo `postpaid_card`:
- **Centraliza as transações**: Todas as compras realizadas com o cartão ficam atreladas a este instrumento para gerenciamento
- **Cria o cartão automaticamente**: Ao criar o instrumento, um cartão físico ou virtual é criado automaticamente conforme solicitado
- **Gerencia o ciclo de vida**: O acompanhamento do status e operações do cartão é feito através dos **[endpoints de gestão do cartão pós-pago](/documentation/cartao_pos_pago/cartao/busca/buscar_cartao_por_chave)**
:::

Para criar o instrumento de pagamento, consulte a **[documentação de criação de PaymentInstrument](/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/criacao_de_instrumento_de_pagamento)**.

### Configuração de Limites

A carteira possui um limite global de crédito que define o teto máximo disponível para uso. **Limites individuais para os instrumentos de pagamento também podem ser configurados**.

:::info Como Funcionam os Limites
- **Limite da carteira**: Define o teto máximo de crédito disponível para uso
- **Limite dos instrumentos**: Cada instrumento pode ter seu próprio limite configurado, desde que seja menor que o da carteira
- **Exemplo prático**: Uma carteira com limite de R$ 100 pode ter dois instrumentos com limites de R$ 100 e R$ 80, mas quando o uso dos dois instrumentos chegar a R$ 100, não será possível fazer mais compras
- **Validação em tempo real**: Tanto o limite do instrumento quanto o limite da carteira são validados antes de permitir uma nova transação
:::

:::info Limites em Carteiras Payroll
Carteiras do tipo `payroll` possuem dois limites distintos:
- **`postpaid_credit_limit`**: Limite de crédito pós-pago para compras e transações com o cartão
- **`payroll_withdraw_limit`**: Limite específico para saques de folha de pagamento (salário/benefício), que são descontados automaticamente na folha de pagamento do cliente

Ambos os limites aparecem na lista `wallet_limits` da carteira e funcionam de forma independente, permitindo que o cliente tenha um limite para compras com o cartão e outro limite específico para saques de benefício.
:::

### Gestão e Acompanhamento do Cartão

Com a carteira e o instrumento de pagamento configurados, o cartão (físico ou virtual) é criado automaticamente e fica disponível para uso. A carteira centraliza todas as informações de faturamento, permitindo o acompanhamento de transações, pagamentos e configurações de juros e multas.

O acompanhamento do status e ciclo de vida do cartão pode ser realizado através dos **[endpoints de gestão do cartão pós-pago](/documentation/cartao_pos_pago/cartao/busca/buscar_cartao_por_chave)**, que permitem monitorar todas as etapas do ciclo de vida do cartão, desde a criação até a baixa ou cancelamento.

## Entradas da Carteira (Wallet Entry)

As **entradas da carteira (wallet entries)** são dívidas que ficam registradas na carteira do cliente. Essas dívidas podem ser de diferentes tipos:

- **Crédito rotativo (`revolving_credit`)**: Valores de crédito disponibilizados para o cliente
- **Saque de folha (`payroll_withdraw`)**: Dívida gerada pelo saque do limite e que vai ser descontada todo mês do INSS
- **Atraso de folha (`payroll_overdue`)**: Dívida gerada pelo não pagamento da fatura e também vai ser descontada todo mês do INSS

:::info Como Funcionam as Wallet Entries
- **Uma entrada = uma dívida**: Cada entrada é uma dívida específica
- **Vira item na fatura**: Cada parcela vira automaticamente um item na fatura
- **Organiza na fatura**: Os itens são organizados em faturas
- **Tudo centralizado**: Todas as dívidas ficam organizadas na carteira
:::

Para mais informações e consulta das entradas da carteira (Wallet Entry), consulte a **[documentação de Wallet Entries](/documentation/cartao_pos_pago/faturas/carteira/listar_entradas_da_carteira)**.

:::tip Webhooks de Wallet Entry
Para acompanhar em tempo real as mudanças de status das entradas da carteira, utilize os **[webhooks de Wallet Entry](/documentation/cartao_pos_pago/faturas/webhooks/wallet_entry)**.
:::

## Entradas de Instrumento de Pagamento (Payment Instrument Entry)

As **entradas de instrumento de pagamento (payment instrument entries)** são as transações feitas com o cartão. Cada compra ou saque vira uma entrada:

- **Transações do cartão**: Compras realizadas com o cartão pós-pago
- **Saques do cartão**: Saques realizados com o cartão pós-pago
- **Outras operações**: Demais transações relacionadas ao instrumento

:::info Como Funcionam as Payment Instrument Entries
- **Vinculação automática**: Cada entrada é automaticamente atrelada a um **invoice item**
- **Organização em faturas**: Os invoice items são organizados em **invoices**
- **Criação automática de faturas**: Quando uma nova transação é criada, o sistema automaticamente cria as faturas necessárias para acomodar todas as parcelas da transação, baseado na configuração de fechamento da carteira
:::

:::warning Importante sobre Cancelamentos
- **Faturas abertas**: Cancelamentos em faturas abertas liberam o limite imediatamente e removem o valor da fatura
- **Faturas fechadas**: Cancelamentos em faturas fechadas criam chargebacks que aparecerão no campo `invoice_payments_chargebacks` e serão utilizados na próxima fatura
:::

Para mais informações e consulta das entradas de instrumento de pagamento (Payment Instrument Entry), consulte a **[documentação de Payment Instrument Entries](/documentation/cartao_pos_pago/faturas/instrumento_de_pagamento/listar_entradas_do_instrumento_de_pagamento)**.

:::tip Webhooks de Payment Instrument Entry
Para acompanhar em tempo real as mudanças de status das entradas de instrumento de pagamento, utilize os **[webhooks de Payment Instrument Entry](/documentation/cartao_pos_pago/faturas/webhooks/payment_instruction_entry)**.
:::

## Faturas (Invoice)

As **faturas (invoices)** são criadas automaticamente conforme a necessidade dos invoice items. Elas funcionam como contêineres que agrupam os itens relacionados:

- **Criação automática**: São criadas automaticamente quando necessário, baseadas na configuração de fechamento da carteira
- **Status inicial**: Todas começam com status `opened` (aberta)
- **Recebe novos itens**: Novas compras e transações vão para faturas abertas
- **Fechamento automático**: Faturas são fechadas automaticamente um dia após sua data de fechamento

:::info Ciclo de Vida das Faturas
- **`opened`**: Fatura aberta, recebendo novos itens. Neste status, novos invoice items podem ser adicionados à fatura
- **`closed`**: Fatura fechada, não recebe mais itens. Neste status, a fatura foi processada e o boleto da fatura é atualizado com o novo valor e vencimento. O boleto pode ser consultado através dos endpoints de boleto
- **`processing_payment`**: Aguardando pagamento. Aplicado apenas para carteiras do tipo `payroll` quando há apenas valor restante a ser pago com o benefício após o desconto em folha
:::

:::info Carteiras Payroll
Para carteiras do tipo `payroll`, o fechamento funciona de forma especial:
- **Desconto em folha**: Valores de desconto no INSS são agrupados em um invoice payment do tipo `payroll_discount` que será descontado automaticamente na folha de pagamento. Este pagamento é criado com status `processing_payment` quando o desconto é solicitado no INSS e muda para `paid` quando o pagamento do desconto é realizado
- **Boleto atualizado**: Quando há valor restante após o desconto em folha, o boleto da fatura é atualizado com o novo valor. O boleto pode ser consultado, mas o invoice payment do tipo `bank_slip` só será criado quando o boleto for efetivamente pago
- **Status processing_payment**: Se não há valor a ser pago via boleto, a fatura fica com status `processing_payment` até que o pagamento do benefício seja realizado
:::

Para mais informações e consulta dos itens da fatura (Invoice), consulte a **[documentação de Faturas](/documentation/cartao_pos_pago/faturas/fatura/listar_faturas)**.

## Itens de Fatura (Invoice Item)

Os **itens de fatura (invoice items)** são criados automaticamente para cada parcela das entradas (wallet entry ou payment instrument entry). Eles representam os componentes individuais que compõem uma fatura:

- **Parcelas de dívidas**: Cada parcela de uma wallet entry gera um invoice item
- **Transações individuais**: Cada parcela de um payment instrument entry gera um invoice item
- **Detalhamento da fatura**: Permitem o controle granular de cada item

:::info Características dos Invoice Items
- **Vinculação obrigatória**: Todo invoice item deve estar vinculado a uma **invoice**
- **Rastreabilidade**: Mantêm referência à entrada original
- **Status individual**: Cada item pode ter seu próprio status (pending, paid, canceled)
- **Valores detalhados**: Contêm informações específicas como valor, limite utilizado e valor pago
:::

Para mais informações e consulta dos itens da fatura (Invoice Item), consulte a **[documentação de Invoice Items](/documentation/cartao_pos_pago/faturas/fatura/consulta_por_chave)**.

---

# Manual BaaS - Conta Digital

URL: /documentation/casos_de_uso/manual_baas

:::warning Aviso
Antes de iniciar o processo de abertura de conta, é de responsabilidade do parceiro realizar as análises de KYC e Prevenção a Fraude.
::: 

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

Para isso, deve ser utilizado o endpoint de análise descrito em /onboarding.

## 1 - Criando uma Conta

### 1.1. Upload de documentos

Antes da abertura da conta deve ser realizado o upload dos documentos da empresa. Seguem listas de documentos exigidos para cada tipo de empresa:

Para S.A.'s:

- Estatuto Social.

- Ata de Eleição dos Representantes Legais da empresa.

- Procuração (caso aplicável).

- Documento com foto de cada representante legal ou procurador.

Para os demais casos:

- Contrato social.

- Procuração (caso aplicável).

- Documento com foto de cada representante legal ou procurador.Os documentos devem ser compactados em um arquivo “.zip” e enviados através do endpoint de upload de documentos ().

#### **Response**

ENDPOINT /upload
MÉTODO POST

Response Body

```json
{
    "document_key": "cd639c4a-2279-468a-a047-59865b8159ed",
    "document_md5": "8f5bef84cb07dc047017c0d304dbb6b8",
    "url": "https://storage.googleapis.com/sandbox-doc-api/documents/cd639c4a-2279-468a-a047-59865b8159ed/identificacao_teste.pdf"
}
```

:::caution IMPORTANTE
Guarde essa **_“document_key”_**, pois ela será necessária na etapa da criação da conta.
::: 

### 1.2. Criação da conta PJ

#### **Request**

ENDPOINT /account
MÉTODO POST

Request Body

```json
{
	"account_owner": {
		"annual_revenue_amount": 180000,
		"address": {
			"city": "Limeira",
			"complement": "complemento",
			"neighborhood": "Vila Cidade Jardim",
			"number": "662",
			"postal_code": "13480290",
			"state": "SP",
			"street": "Avenida Campinas"
		},
		"cnae_code": "4721-1/02",
        "company_statute": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
		"company_document_number": "09080702000105",
		"company_type": "ltda",
		"email": "padaria@vovolucia.com.br",
		"foundation_date": "1950-08-21",
		"annual_revenue_amount": "1000000.00",
		"name": "VOVO LUCIA CONVENIENCIA LTDA",
		"person_type": "legal",
		"phone": {
			"area_code": "19",
			"country_code": "55",
			"number": "988888888"
		},
		"trading_name": "Empadaria Vovo Lucia",
		"company_representatives": [{
				"address": {
					"city": "Recife",
					"complement": null,
					"neighborhood": "Fundão",
					"number": "137",
					"postal_code": "52221110",
					"state": "PE",
					"street": "Rua Camapuã"
				},
				"birth_date": "1972-02-02",
				"document_identification_number": "339122924",
                "document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
				"email": "marcos.alves@yopmail.com",
				"individual_document_number": "08531309069",
				"is_pep": false,
				"final_beneficiary": true,
				"marital_status": "single",
				"mother_name": "Sueli Isadora Alves",
				"name": "Marcos Felipe Henrique Alves",
				"nationality": "Brasileira",
				"person_type": "natural",
				"phone": {
					"area_code": "88",
					"country_code": "55",
					"number": "995924634"
				}
			},
			{
				"person_type": "natural",
				"name": "Juliana Tereza Bernardes",
				"mother_name": "Maria Mariane",
				"birth_date": "1990-05-06",
				"profession": "Deputada",
				"nationality": "Brasileira",
				"marital_status": "single",
				"is_pep": false,
				"final_beneficiary": true,
				"individual_document_number": "97564480084",
				"document_identification_number": "232479719",
                "document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
				"email": "juliana.tereza@yopmail.com",
				"phone": {
					"country_code": "55",
					"area_code": "11",
					"number": "912821359"
				},
				"address": {
					"street": "Passagem Mariana",
					"state": "PA",
					"city": "Ananindeua",
					"neighborhood": "Águas Lindas",
					"number": "660",
					"postal_code": "67118003",
					"complement": "complemento"
				}
			}
		]
	},
	"allowed_user": {
		"email": "juliana.tereza@yopmail.com",
		"individual_document_number": "97564480084",
		"name": "Juliana Tereza Bernardes",
		"person_type": "natural",
		"phone": {
			"country_code": "55",
			"area_code": "11",
			"number": "912828135"
		}
	},
	"signed_contract": {
        "document_key": "4d7f4e29-4b58-4905-9a69-b1f9215263f5",
        "signatures": [
            {
                "authenticity": {
                    "timestamp": "1970-01-01T00:00:01.080100Z",
                    "facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
                    "lang": "-35.8916627",
                    "lat": "-7.2226067",
                    "ip_address": "177.51.1.000",
                    "session_id": "jdifj329842"
                },
                "signer": {
                    "name": "IVANILDO DE SENA LIMA",
                    "email": "teste@gmail.com",
                    "phone": {
                        "country_code": "055",
                        "area_code": "11",
                        "number": "999999999"
                    },
                    "document_number": "99999999999"
                },
                "authentication_type": "opt-in"
            }
        ]
    }
}

```

**“account_owner”:** Os dados da empresa devem ser enviados neste objeto.

“***account_owner.company_statute***”: A “***document_key***” retornada no endpoint de upload de documentos, no momento do upload do “.zip” dos documentos societários da empresa, deve ser enviada neste campo.

“***account_owner.company_representatives***”: A lista com os dados dos representantes legais da empresa deve ser enviada neste objeto. Deve ser enviado, no mínimo, os representantes legais, suficientes para representar legalmente a empresa conforme seu respectivo estatuto/contrato social. A validação dos poderes de cada representante legal enviado fica a cargo do parceiro.

“***account_owner.company_representatives.document_identification***”: A “***document_key***” retornada no endpoint de upload de documentos, no momento do upload do “.zip” do documento com foto do representante, deve ser enviada neste campo. 

“***allowed_user***”: Neste campo devem ser enviados os dados de um dos representantes legais da empresa enviado no objeto “***account_owner.company_representatives***”. Este usuário será o usuário administrador da conta e possuirá poderes de movimentação sobre a conta e também poderes para adicionar novos usuários administradores. O SMS/e-mail de confirmação tanto para movimentação quanto adição de novos usuários será enviado para essa pessoa. 

:::info
O usuário com permissão de administrador possui plenos poderes sobre a conta (mediante autenticação de 2 fatores, via SMS ou e-mail). Sendo assim, este usuário deve possuir permissão legal para movimentá-la  segundo o contrato/estatuto social da empresa. A validação dos poderes de um usuário administrador fica a cargo do parceiro.
:::

### 1.2.1 Assinatura do Termo de Abertura de Conta
	No payload de abertura de conta deverá ser enviado o campo `signature_contract` que deverá conter as informações de device scan do momento em que o usuário (Titular da conta ou usuário master) realiza o aceite do termo de abertura de cont

### Objeto signed_contract 
| Campo | Tipo   | Descrição        | Caracteres    |
|-------|--------|------------------|---------------|
| **document_key** * | uuidv4 | Chave única de identificação do documento do **Termo de Abertura de Conta** ou **Contrato de Conta Escrow**. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36            |
| **signatures** *   | list   | Dados de assinatura do documento enviado. Cada item da lista, corresponde a um assinante do documento.      | [Objeto signatures](#objeto-signatures) |

### Objeto signatures
| Campo | Tipo       | Descrição         | Caracteres        |
|-------|------------|-------------------|-------------------|
| **authenticity** * | object     | Conjunto de dados que evidenciam a assinatura eletrônica realizada pelo assinante. | [Objeto authenticity](#objeto-authenticity) |
| **signer** * | object     | Objeto contendo os dados de um dos assinantes do documento.           | [Objeto signer](#objeto-signer)|
| **authentication_type** * | enumerator | Tipo de assinatura. Sempre será "**opt-in**"| "**opt-in**"                   |

### Objeto authenticity
| Campo | Tipo   | Descrição               | Caracteres |
|-------|--------|-------------------------|------------|
| **timestamp** *            | string | Data e hora do momento da assinatura do documento.                | 27         |
| **facial_recognition_key** | uuidv4 | Chave única de identificação da foto da selfie do titular da conta. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36         |
| **lang**                   | string | Coordenada de longitude da geolocalização do assinante capturada no momento da assinatura.                  | -          |
| **lat**                    | string | Coordenada de latitude da geolocalização do assinante capturada no momento da assinatura.                   | -          |
| **ip_address**             | string | Endereço IP do dispositivo do assinante.     | -          |
| **session_id**             | string | ID da seção do assinante no momento da assinatura.                | -          |

### Objeto signer
| Campo                 | Tipo   | Descrição                                 | Caracteres                        |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** *            | string | Nome do assinante.                        | -                                 |
| **email** *           | string | Email do assinante.                       | -                                 |
| **phone** *           | object | Objeto com dados do telefone do assinante | **[Objeto phone](#objeto-phone)** |
| **document_number** * | string | CPF do assinante.                         | 11                                |

### Objeto phone 

| Campo | Descrição | Exemplo |  Máx. Caracteres | 
| --- | --- | --- | --- | 
|`country_code` *| string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 | 
| `area_code` *| string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |Número de telefone (apenas números) |  10 |

        **Response**

- MÉTODO POST
- ENDPOINT /account

Response Body

```json

{
	"data": {
		"account_info": {
			"account_branch": "0001",
			"account_digit": "2",
			"account_number": "2359934",
			"financial_institution_code": "329"
		},
		"account_owner": {
			"document_number": "09080702000105",
			"name": "VOVO LUCIA CONVENIENCIA LTDA"
		},
		"allowed_user": {
			"document_number": "97564480084",
			"name": "Juliana Tereza Bernardes"
		}
	},
	"event_datetime": "2022-09-02 22:39:10",
	"key": "\<UUID PROPOSAL-KEY\>",
	"status": "pending_kyc_analysis",
	"webhook_type": "account"
}

```

:::info IMPORTANTE
IMPORTANTE: a “***key***” retornada nesta resposta é a PROPOSAL-KEY do pedido de abertura da conta. Ela deve ser armazenada para leitura do webhook de abertura da conta.
::: 

A resposta da solicitação de abertura de conta sempre retornará o status “***pending_kyc_analysis***”.

Um número de conta será reservado para esse cliente, porém a conta ainda estará pendente de análise de KYC por parte da QI Tech. Neste momento, a conta não estará aberta e não poderá receber ou enviar recursos.

### 1.3. Criação da conta PF

        **Request**

- ENDPOINT /account
- MÉTODO POST

Request Body

```json
{
	"account_owner": {
		"address": {
			"street": "Avenida Sargento Geraldo Sant'Ana",
			"number": "1100",
			"neighborhood": "Jardim Taquaral",
			"city": "São Paulo",
			"state": "SP",
			"postal_code": "04674225"
		},
		"phone": {
			"country_code": "55",
			"number": "912828135",
			"area_code": "11"
		},
		"email": "juliana.tereza@yopmail.com",
		"name": "Juliana Tereza Bernardes",
		"person_type": "natural",
		"nationality": "Brasil",
		"birth_date": "1993-08-02",
		"mother_name": "Patricia Monica Diaz Bascur Tieppo",
		"is_pep": false,
		"individual_document_number": "97564480084",
		"document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
		"document_identification_type": "cnh",
        "revenue_amount": 1000,
        "profession": "autonomo"
	},
	"signed_contract": {
        "document_key": "4d7f4e29-4b58-4905-9a69-b1f9215263f5",
        "signatures": [
            {
                "authenticity": {
                    "timestamp": "1970-01-01T00:00:01.080100Z",
                    "facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
                    "lang": "-35.8916627",
                    "lat": "-7.2226067",
                    "ip_address": "177.51.1.000",
                    "session_id": "jdifj329842"
                },
                "signer": {
                    "name": "IVANILDO DE SENA LIMA",
                    "email": "teste@gmail.com",
                    "phone": {
                        "country_code": "055",
                        "area_code": "11",
                        "number": "999999999"
                    },
                    "document_number": "99999999999"
                },
                "authentication_type": "opt-in"
            }
        ]
    }
}
```

**“account_owner”:** Os dados da pessoa física titular da conta devem ser enviados neste objeto.

**“account_owner.document_identification”:** A “document_key” retornada no endpoint de upload de documentos.

#### 1.3.1. Forma de envio do documento de identificação

Na abertura da conta PF, podem ser enviados dois tipos de documento (***document_identification_type***): **cnh** ou **rg**.

O documento de identificação pode ser enviado nos formatos “**.pdf**”, “**.png**” e “**.jpeg**”.

##### 1.3.1.1. Envio de documento de identificação do tipo CNH

Caso o documento seja enviado em 2 arquivos, sendo que, a frente do documento consta em um arquivo e o verso em outro, os seguintes campos devem ser infomado no objeto ***account_owner*** do endpoint ***/account*** (**1.2.2.**):

Request Body

```json

		"document_identification": "\<DOCUMENT-KEY DA FRENTE DO DOCUMENTO\>",
		"document_identification_back": "\<DOCUMENT-KEY DA VERSO DO DOCUMENTO\>",
		"document_identification_type": "cnh",
```

Caso o documento seja enviado em 1 arquivo, contendo a frente e verso do documento no mesmo arquivo (**foto do documento ou cnh digital**), os seguintes campos devem ser infomado no objeto account_owner do endpoint ***/account*** (**1.2.2.**):
Request Body

```json
		"document_identification": "\<DOCUMENT-KEY DA FRENTE DO DOCUMENTO\>",
		"document_identification_type": "cnh",
```

##### 1.3.1.2. Envio de documento de identificação do tipo RG 

Para o tipo de documento RG, sempre devem ser enviados 2 arquivos, um contendo a frente do documento e outro com o verso do documento. Para este caso os seguintes campos devem ser infomados no objeto account_owner do endpoint /account (1.2.2.):

Request Body

```json
		"document_identification": "\<DOCUMENT-KEY DA FRENTE DO DOCUMENTO\>",
		"document_identification_back": "\<DOCUMENT-KEY DA VERSO DO DOCUMENTO\>",
		"document_identification_type": "rg",

```

        **Response**

- MÉTODO POST
- ENDPOINT /account

Response Body

```json

{
	"data": {
		"account_info": {
			"account_branch": "0001",
			"account_digit": "2",
			"account_number": "2359934",
			"financial_institution_code": "329"
		},
		"account_owner": {
            "document_number": "97564480084",
			"name": "Juliana Tereza Bernardes"
		}
	},
	"event_datetime": "2022-09-02 22:39:10",
	"key": "\<UUID PROPOSAL-KEY\>",
	"status": "pending_kyc_analysis",
	"webhook_type": "account"
}
```

:::info IMPORTANTE
**IMPORTANTE:** a “***key***” retornada nesta resposta é a **PROPOSAL-KEY** do pedido de abertura da conta. Ela deve ser armazenada para leitura do webhook de abertura da conta.
:::

A resposta da solicitação de abertura de conta sempre retornará o status “***pending_kyc_analysis***”.
Um número de conta será reservado para esse cliente, porém a conta ainda estará pendente de análise de KYC por parte da QI Tech. Neste momento, a conta não estará aberta e não poderá receber ou enviar recursos.

:::info
Para simular situações de aprovação, reprovação e analise manual pode ser utilizado o primeiro digito do CPF/CNPJ do owner da conta:

- 0 à 7 -> Análise Manual

- 8 -> Reprovação Automática

- 9 -> Aprovação Automática
:::

Após a conclusão da análise de KYC/PLD pela QI Tech, será enviado um webhook de abertura da conta, conforme abaixo:

        **Webhook**

- WEBHOOK_TYPE account
- STATUS Account Opened

Response Body

```json

{
	"data": {
		"account_info": {
			"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
			"account_digit": "2",
			"account_branch": "0001",
			"account_number": "2359934",
			"financial_institution_code": "329"
		},
		"allowed_user": {
			"name": "Juliana Tereza Bernardes",
			"document_number": "97564480084"
		},
		"account_owner": {
			"name": "VOVO LUCIA CONVENIENCIA LTDA",
			"document_number": "09080702000105"
		}
	},
	"event_datetime": "2022-09-02 22:39:39",
	"key": "\<UUID PROPOSAL-KEY\>",
	"status": "account_opened",
	"webhook_type": "account"
}
```

Neste momento será retornada “account_key” da conta e ela estará pronta para utilização.

Caso a conta não passe no processo de KYC/PLD, será enviado um webhook de conta rejeitada:

        **Webhook**

- WEBHOOK_TYPE account
- STATUS Account Rejected

Response Body

```json

{
	"data": {
		"account_info": {
			"account_digit": "2",
			"account_branch": "0001",
			"account_number": "2359934",
			"financial_institution_code": "329"
		},
		"allowed_user": {
			"name": "Juliana Tereza Bernardes",
			"document_number": "97564480084"
		},
		"account_owner": {
			"name": "VOVO LUCIA CONVENIENCIA LTDA",
			"document_number": "09080702000105"
		}
	},
	"event_datetime": "2022-09-02 22:39:39",
	"key": "\<UUID PROPOSAL-KEY\>",
	"status": "account_rejected",
	"webhook_type": "account"
}
```

:::caution Atenção

A propriedade **allowed_user** retornada apenas nos webhooks de abertura de conta de PJ, em caso de PF temos apenas a propriedade de **account_info** e **account_owner** sendo retornadas dentro do objeto de **data**.

:::

#### 1.3.2 Assinatura do Termo de Abertura de Conta
	No payload de abertura de conta deverá ser enviado o campo `signature_contract` que deverá conter as informações de device scan do momento em que o usuário (Titular da conta ou usuário master) realiza o aceite do termo de abertura de cont

### Objeto signed_contract 
| Campo | Tipo   | Descrição        | Caracteres    |
|-------|--------|------------------|---------------|
| **document_key** * | uuidv4 | Chave única de identificação do documento do **Termo de Abertura de Conta** ou **Contrato de Conta Escrow**. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36            |
| **signatures** *   | list   | Dados de assinatura do documento enviado. Cada item da lista, corresponde a um assinante do documento.      | [Objeto signatures](#objeto-signatures) |

### Objeto signatures
| Campo | Tipo       | Descrição         | Caracteres        |
|-------|------------|-------------------|-------------------|
| **authenticity** * | object     | Conjunto de dados que evidenciam a assinatura eletrônica realizada pelo assinante. | [Objeto authenticity](#objeto-authenticity) |
| **signer** * | object     | Objeto contendo os dados de um dos assinantes do documento.           | [Objeto signer](#objeto-signer)|
| **authentication_type** * | enumerator | Tipo de assinatura. Sempre será "**opt-in**"| "**opt-in**"                   |

### Objeto authenticity
| Campo | Tipo   | Descrição               | Caracteres |
|-------|--------|-------------------------|------------|
| **timestamp** *            | string | Data e hora do momento da assinatura do documento.                | 27         |
| **facial_recognition_key** | uuidv4 | Chave única de identificação da foto da selfie do titular da conta. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36         |
| **lang**                   | string | Coordenada de longitude da geolocalização do assinante capturada no momento da assinatura.                  | -          |
| **lat**                    | string | Coordenada de latitude da geolocalização do assinante capturada no momento da assinatura.                   | -          |
| **ip_address**             | string | Endereço IP do dispositivo do assinante.     | -          |
| **session_id**             | string | ID da seção do assinante no momento da assinatura.                | -          |

### Objeto signer
| Campo                 | Tipo   | Descrição                                 | Caracteres                        |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** *            | string | Nome do assinante.                        | -                                 |
| **email** *           | string | Email do assinante.                       | -                                 |
| **phone** *           | object | Objeto com dados do telefone do assinante | **[Objeto phone](#objeto-phone)** |
| **document_number** * | string | CPF do assinante.                         | 11                                |

### Objeto phone 

| Campo | Descrição | Exemplo |  Máx. Caracteres | 
| --- | --- | --- | --- | 
|`country_code` *| string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 | 
| `area_code` *| string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |Número de telefone (apenas números) |  10 |

### 1.4. Recuperando dados da conta

        **Request**

- ENDPOINT /account
- MÉTODO GET
- PARAMETERS account_type[checking], owner_name, account_number, owner_document_number, account_status[opened, closed, blocked], page, page_size

        ***Response:***

Response Body

```json

{
	"data": [
		{
			"account_block_reason": null,
			"account_branch": "0001",
			"account_credentials": [{
					"account_id": 3395,
					"created_at": "2022-09-02T22:39:39",
					"credential_type": {
						"created_at": "2019-06-18T13:19:30",
						"enumerator": "observer",
						"id": 3,
						"translation_path": "account.CredentialType.observer"
					},
					"credential_type_id": 3,
					"id": 3244,
					"is_active": true,
					"person_key": "bffded45-5fcf-4d13-9d2a-566a0af338cc",
					"updated_at": null
				},
				{
					"account_id": 3395,
					"created_at": "2022-09-02T22:39:39",
					"credential_type": {
						"created_at": "2019-06-18T13:19:30",
						"enumerator": "requester",
						"id": 2,
						"translation_path": "account.CredentialType.requester"
					},
					"credential_type_id": 2,
					"id": 3245,
					"is_active": true,
					"person_key": "ef48fbe4-267b-45c1-9049-75345c075486",
					"updated_at": null
				}
			],
			"account_digit": "2",
			"account_documents": [],
			"account_events": [{
				"account_id": 3395,
				"created_at": "2022-09-02T22:39:39",
				"id": 5132,
				"new_account_status": {
					"created_at": "2019-10-11T18:58:31",
					"enumerator": "opened",
					"id": 1,
					"translation_path": "account.AccountStatus.opened"
				},
				"new_account_status_id": 1,
				"old_account_status": null,
				"old_account_status_id": null
			}],
			"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
			"account_name": "Default",
			"account_number": "2359934",
			"account_status": {
				"created_at": "2019-10-11T18:58:31",
				"enumerator": "opened",
				"translation_path": "account.AccountStatus.opened"
			},
			"account_type": {
				"created_at": "2019-03-15T13:09:15",
				"enumerator": "checking",
				"translation_path": "account.AccountType.checking"
			},
			"automatic_transfer_management_status": {
				"created_at": "2022-10-27T13:48:18",
				"enumerator": "master"
			},
			"automatic_transfers": [],
			"balance": 0,
			"blocked_balance": 0,
			"blocked_balance_events": [],
			"created_at": "2022-09-02T22:39:39",
			"destinations": [],
			"fee": 0,
			"internal_webhooks": [],
			"investment_available_amount": 0,
			"investment_configuration": null,
			"is_system_account": false,
			"owner_document_number": "09080702000105",
			"owner_name": "VOVO LUCIA CONVENIENCIA LTDA",
			"owner_person_key": "bffded45-5fcf-4d13-9d2a-566a0af338cc",
			"permitted_person_keys": [
				"bffded45-5fcf-4d13-9d2a-566a0af338cc",
				"bffded45-5fcf-4d13-9d2a-566a0af338cc",
				"ef48fbe4-267b-45c1-9049-75345c075486"
			],
			"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
			"requester_name": "Requester Name Sandbox",
			"setup_fee": null,
			"transactional_limit": null,
			"webhook_enabled": true
		}, ...
	],
	"pagination": {
		"current_page": 1,
		"next_page": null,
		"rows_per_page": 100,
		"total_pages": 1,
		"total_rows": 8
	}
}
```

:::info
Os campos mais pertinentes da resposta da consulta dos dados da conta são: **account_branch**, **account_digit**, **account_key**, **account_number**, **balance**, **owner_document_number**, **owner_name**, **owner_person_key**.
:::

## 2 - Transferência PIX

### 2.1. Realizar Transferência PIX

Para realizar um PIX é necessário realizar três chamadas:

1. Criação do pedido de transferência: /baas/pix_transfer

2. Solicitação de token de validação de transferência: /baas/token_request

3. Aprovação da transferência: /baas/movement_validation

:::info
Uma transferência PIX pode ser realizada utilizando dois payloads distintos: **chave PIX** ou **dados bancários**. 
:::

### **2.1.1. Criação do pedido de transferência**
### Transferência utilizando uma chave PIX (CPF, CNPJ, E-mail, Celular ou chave aleatória)

- ENDPOINT /baas/pix_transfer
- MÉTODO POST

Request Body

```json
{
    "pix_transfer_type": "key",
    "source_account": {
        "account_branch": "0001",
        "account_digit": "2",
        "account_number": "2359934",
        "owner_document_number": "09080702000105"
    },
    "pix_key": "65322181032",
    "transaction_amount": 45,
    "requester_document_identification": "09080702000105"
}

```

:::info
A “**pix_key**” pode ser um **CPF**, **CNPJ**, **E-mail**, **Celular** ou uma **Chave Aleatória (UUID)**, seguindo as seguintes formatações:

**CPF:** Número inteiro com 11 dígitos.

**CNPJ:** Número inteiro com 14 dígitos.

**E-mail:** Texto contendo ao menos um “@”.

**Celular:** Texto contendo os seguintes valores: “+55” + “DDD do celular“ + “Número Inteiro do Celular com no mínimo 8 e no máximo 9 dígitos”. Ex: “+5511987654321“.

**Chave Aleatória:** UUID.
:::

### Transferência utilizando dados da Conta Bancária (PIX Manual)

- ENDPOINT /baas/pix_transfer
- MÉTODO POST

Request Body

```json

{
    "pix_transfer_type": "manual",
    "source_account": {
        "account_branch": "0001",
        "account_digit": "2",
        "account_number": "2359934",
        "owner_document_number": "09080702000105"
    },
    "target_account": {
          "account_branch": "0001",
          "account_digit": "3",
          "account_number": "12345678",
          "owner_document_number": "32402502000135",
          "owner_name": "Qi Tech",
          "account_type": "checking_account",
          "ispb": "32402502"
     },
    "transaction_amount": 45
}

```

Utilizando o PIX Manual é necessário informar o ISPB da instituição destino. Este dado é utilizado, pois existem instituições de pagamento que recebem PIX, porém não possuem código de banco. O ISPB é a base do CNPJ da instituição. Para ter acesso à lista completa de ISPB’s de cada instituição participante do PIX, basta utilizar o endpoint de consulta em nossa documentação: https://docs.qitech.com.br/reference/161-consulta-de-institui%C3%A7%C3%B5es-financeiras

Response Body

```json
{
	"data": {
		"end_to_end_id": "E3240250220221120012039U3OKZZMW8",
		"fee_amount": 1,
		"pix_message": null,
		"pix_transfer_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
		"source_account": {
			"account_brach": "0001",
			"account_digit": "2",
			"account_number": "2359934",
			"account_type": "checking",
			"owner_document_number": "09080702000105",
			"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
		},
		"target_account": {
			"document_number": "***.221.81*-**",
			"financial_institution": "BANCO ORIGINAL S.A."
		},
		"transaction_amount": 45,
		"transfer_purpose": "transfer"
	},
	"event_datetime": "2022-09-02 22:20:47",
	"operation_key": "86d80cf4-430b-4e16-910a-41798810ddcf",
	"status": "pending_approval"
}
```

:::info Possíveis status da solicitação de transferência/pagamento via PIX: 

**pending_approval:** transferência pendente de aprovação pelo usuário administrador da conta (“***allowed_user***”)

**sent:** transferência enviada
:::

:::caution Atenção
O campo **end_to_end_id** retornado deve ser amarzenado e enviado no momento da aprovação da transação. É ELE QUEM GARANTE 
:::

Após realizar a primeira chamada de “***/baas/pix_transfer***”, é necessário solicitar o token para aprovar a transação. Para aprovar a transferência PIX, é necessário utilizar a “***pix_transfer_key***” retornada na solicitação de transferência e solicitar a geração de um token que será enviado ao usuário administrador da conta para aprovação (“**allowed_user**”).

### **2.1.2. Solicitação de token de validação de transferência:**

- ENDPOINT /baas/token_request
- MÉTODO POST

Request Body

```json
{
    "contact_type": "sms",
    "agent_document_number": "97564480084",
    "movement_payload": {
        "pix_transfer_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
        "approver_document_number": "97564480084"
    }
}

```

:::info
**contact_type:** é o método de autenticação de dois fatores que será utilizado no momento da aprovação da transferência, podendo ser via E-mail (“email”) ou SMS (“sms”).
:::

:::info
**approver_document_number:** Deve ser informado o CPF do usuário administrador que realizará a aprovação da transferência PIX.
:::

:::info
**agent_document_number:** neste campo pode ser informado o CPF do usuário master que receberá o token para aprovação de 2 fatores da transação.
:::

A última chamada para concluir a transferência será a do “**/baas/movement_validation**” e o Token enviado deve ser informado no momento da aprovação da transferência PIX. A validade do Token é de **2 minutos**. 

O usuário administrador deve inserir na aplicação do parceiro o token recebido via E-mail ou SMS.

### **2.1.3. Aprovação da transferência:**

- ENDPOINT /baas/movement_validation
- MÉTODO POST

Request Body

```json
{
    "token": "248358",
    "movement_payload": {
        "pix_transfer_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
        "approver_document_number": "97564480084"
    }
}

```

Reponse Body

```json

{
	"authentication_code": "287c4478a1adcd6e820e654ac1b1edf2",
	"event_datetime": "2022-09-02 23:00:07",
	"operation_key": "05283f8e-b9c0-47ff-a06f-9626be710f69",
	"pix_transaction": {
		"end_to_end_id": "E3240250220221120012039U3OKZZMW8",
		"fee_amount": 1,
		"pix_message": null,
		"pix_transfer_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
		"pix_transfer_status": "sent",
		"pix_transfer_type": "key",
		"source_account": {
			"account_branch": "0001",
			"account_digit": "2",
			"account_number": "2359934"
		},
		"target_account": {
			"document_number": "***.221.81*-**",
			"financial_institution": "BANCO ORIGINAL S.A."
		},
		"transaction_key": "d2ba3817-26d7-4957-ab82-24f78d910a8a",
		"transfer_amount": 45
	},
	"status": "sent"
}

```

STATUS 422

Response Body

```json
{
  "data": "{\"title\": \"Pending Transfer\", \"description\": \"The transaction (<END TO END ID DO PIX>) could not be completed and is pending confirmation.\", \"translation\": \"Não foi possível concluir a transação (<END TO END ID DO PIX>) e ela está pendente de confirmação\", \"code\": \"PXT000072\"}"
}

```

:::danger HTTP Error 422
Caso seja retornado **http error 422**, a solicitação de Pix **não deve ser retentada**. É preciso checar o status da solicitação de transferência Pix através de um GET na rota [/baas/pix/pix_transfer](/documentation/pix/pesquisar_por_transferencia_pix_de_saida).
:::

### 2.2. Webhook de Efetivação de um PIX

#### **Webhook**

- WEBHOOK_TYPE account_transaction
- SOURCE_SUB_TYPE pix_withdrawal

Response Body

```json

{
  "key": "508ebbba-0b1d-41f6-b9a2-975a4c2e925e",
  "data": {
    "amount": -45,
    "origin": {
      "name": "PIX",
      "branch": "0001",
      "document": "32402502000135",
      "account_key": "3d0e7d50-e898-49f3-b23b-05353c8a3c72",
      "account_digit": "3",
      "account_number": "00003"
    },
    "timestamp": "2023-01-05T18:16:03.395863",
    "description": "237 0001 1017372-2 ***.221.81*-** BANCO BRADESCO S.A.",
    "destination": {
      "name": "Default",
      "branch": "0001",
      "document": "23426525852",
      "account_key": "508ebbba-0b1d-41f6-b9a2-975a4c2e925e",
      "account_digit": "0",
      "account_number": "7058818"
    },
    "reference_key": "aafbf4bc-58eb-45fd-899c-af44f68dfd60",
    "reference_type": "pix_outgoing",
    "account_balance": 99359.15,
    "source_sub_type": "pix_withdrawal",
    "transaction_key": "3e37a0a9-d6d2-4474-8bff-5448e446c225",
    "source_sub_type_str": "Transferência de PIX"
  },
  "datetime": "2023-01-05T18:16:03.395863",
  "webhook_type": "account_transaction"
}
```

### 2.3. Webhook de Cobrança de fee de PIX

        **Webhook**

- WEBHOOK_TYPE account_transaction
- SOURCE_SUB_TYPE pix_fee

Response Body

```json
{
  "key": "508ebbba-0b1d-41f6-b9a2-975a4c2e925e",
  "data": {
    "amount": -0.85,
    "origin": {
      "name": "Fee Account",
      "branch": "0001",
      "document": "32402502000135",
      "account_key": "3679ffd0-d52e-4492-b11c-b11c655047d3",
      "account_digit": "8",
      "account_number": "00005"
    },
    "timestamp": "2023-01-05T18:16:03.554624",
    "description": "237 0001 1017372-2 ***.221.81*-** BANCO BRADESCO S.A.",
    "destination": {
      "name": "Default",
      "branch": "0001",
      "document": "23426525852",
      "account_key": "508ebbba-0b1d-41f6-b9a2-975a4c2e925e",
      "account_digit": "0",
      "account_number": "7058818"
    },
    "reference_key": "aafbf4bc-58eb-45fd-899c-af44f68dfd60",
    "reference_type": "pix_outgoing",
    "account_balance": 99358.3,
    "source_sub_type": "pix_fee",
    "transaction_key": "53c7421b-1340-4625-b383-b94d350ff9b2",
    "source_sub_type_str": "Tarifa de PIX"
  },
  "datetime": "2023-01-05T18:16:03.554624",
  "webhook_type": "account_transaction"
}
```

### 2.4. Chargeback Pix

Um Chargeback Pix (Estorno) é realizado em 3 etapas:

- 1 - Iniciação do Chargeback Pix: /baas/pix_transfer
- 2 - Solicitação do token de autorização do Chargeback Pix: /baas/token_request
- 3 - Aprovação do Chargeback Pix: /baas/movement_validation

#### 2.4.1. Iniciando Chargeback Pix

##### Request

ENDPOINT /baas/pix_transfer
MÉTODO POST

Request Body

```json
{
    "is_chargeback": true,
    "pix_transfer_key": "a180f2fb-0c7e-4708-b6a0-8d231770132e",
    "chargeback_amount": 100.46,
    "chargeback_message": "Mensagem de devolução"
}
```

:::info
A _**pix_transfer_key**_ é a chave do Pix que creditou a conta na QI, retornada via Webhook de _**account_transaction**_.

O _**chargeback_amount**_ deve ser menor ou igual ao valor do Pix que creditou a conta na QI.
:::

##### Response

ENDPOINT /baas/pix_transfer
MÉTODO POST

Response Body

```json
{
    "data": {
        "pix_transfer_key": "7a71e1f7-d8d1-4cf0-9243-c0b3837a3d26",
        "pix_transfer_status": "pending_approval",
        "pix_transfer_type": "chargeback",
        "target_account": {
            "document_number": "***45762***",
            "financial_institution": "ITAÚ UNIBANCO S.A."
        },
        "transfer_amount": 100.46
    },
    "event_datetime": "2023-04-28 18:19:30",
    "operation_key": "ab895342-988d-4d20-ba71-f82a7b9aad1b",
    "status": "pending_approval"
}
```

:::info
A _**pix_transfer_key**_ retornada na chamada é a chave de referência do Chargeback Pix que deverá ser aprovado.
:::

#### 2.4.2. Solicitação do token de autorização do Chargeback Pix

ENDPOINT /bass/token_request
MÉTODO POST

Request Body

```json
{
    "contact_type": "email",
    "movement_payload": {
        "pix_transfer_key": "7a71e1f7-d8d1-4cf0-9243-c0b3837a3d26",
        "approver_document_number": "97564480084"
    }
}
```

#### 2.4.3. Aprovação do Chargeback Pix

ENDPOINT /bass/movement_validation
MÉTODO POST

Request Body

```json
{
    "contact_type": "email",
    "movement_payload": {
        "pix_transfer_key": "7a71e1f7-d8d1-4cf0-9243-c0b3837a3d26",
        "approver_document_number": "97564480084"
    }
}
```

## 3 - Transferência TED

:::info
As transferências TED só podem ser realizadas em dias úteis das **7:00** às **17:00**.
:::

### 3.1. Realizar Transferência TED

Para realizar uma transferência via TED é necessário realizar a seguinte chamada: 

1. Solicitação de token de validação de transferência: /baas/token_request

2. Aprovação da transferência: /baas/movement_validation

        **Request**

- ENDPOINT /baas/token_request
- MÉTODO POST

Request Body

```json
{
	"contact_type": "sms",
	"agent_document_number": "97564480084",
	"movement_payload": {
		"source_account": {
			"account_branch": "0001",
			"account_number": "9477323",
			"account_digit": "0",
			"owner_document_number": "38299588000107"
		},
		"target_account": {
			"financial_institution_code": "341",
			"account_branch": "0001",
			"account_number": "4311337",
			"account_digit": "1",
			"owner_document_number": "21669721019",
			"owner_name": "Nome do Titular da Conta Destino"
		},
		"transaction_amount": 8.86
	}
}
```

O Token enviado deve ser informado no momento da aprovação da transferência TED, e o “***movement_payload***” deve ser o mesmo informado no momento da solicitação do Token.

        **Request**

- ENDPOINT /baas/movement_validation
- MÉTODO POST

Request Body

```json
{
	"token": "329329",
	"agent_document_number": "99999999999",
	"movement_payload": {
		"source_account": {
			"account_branch": "0001",
			"account_number": "0000000",
			"account_digit": "0",
			"owner_document_number": "99999999000107"
		},
		"target_account": {
			"financial_institution_code": "341",
			"account_branch": "0001",
			"account_number": "0000000",
			"account_digit": "1",
			"owner_document_number": "999999999",
			"owner_name": "Nome do Titular da Conta Destino"
		},
		"transaction_amount": 8.86,
        "approver_document_number": "999999999"
	}
}
```

        **Response**

- MÉTODO POST
- ENDPOINT /baas/movement_validation

Response Body

```json

{
	"authentication_code": "e8f0fffaeb4ebad2df0417194fe6a9e5",
	"origin_key": "d07f77f9-f157-4c35-a26b-567cba59e385",
	"pdf_encoded_string": "\<BASE 64 DO COMPROVANTE\>",
	"source_account": {
		"account_branch": "0001",
		"account_digit": "2",
		"account_number": "2359934",
		"financial_institution_compe_number": 329,
		"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"owner_document_number": "09080702000105",
		"owner_document_number_formatted": "09.080.702/0001-05",
		"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
	},
	"source_subtype": "withdrawal",
	"source_subtype_translation_ptbr": "Transferência",
	"target_account": {
		"account_branch": "0001",
		"account_digit": "1",
		"account_number": "81156",
		"account_type": "checking_account",
		"account_type_str": "Conta Corrente",
		"financial_institution_compe_number": "001",
		"financial_institution_name": "Banco do Brasil S.A.",
		"owner_document_number": "10932327656",
		"owner_document_number_formatted": "109.323.276-56",
		"owner_name": "Lucas de Jesus Clarim"
	},
	"transacted_at": "2022-09-02 14:39:56",
	"transacted_at_br": "2022-09-02 11:39:56",
	"transacted_at_br_formatted": "21/11/2022, 11:39:56",
	"transacted_at_formatted": "21/11/2022, 14:39:56",
	"transaction_amount": 550,
	"transaction_amount_formatted": "R$ 550,00",
	"transaction_key": "32ac0781-f292-4172-b58f-3310102e6fb9"
}
```

:::info
O campo de “***transacted_at***“ estão em formato UTC.
:::

:::info
A “***transaction_key***“ será utilizada posteriormente para solicitação do comprovante de transferência.
:::

### 3.2. Efetivação de uma TED

        **Webhook**

- WEBHOOK_TYPE account_transaction
- SOURCE_SUB_TYPE withdrawal

Response Body

```json
{
  "key": "508ebbba-0b1d-41f6-b9a2-975a4c2e925e",
  "data": {
    "amount": -550,
    "origin": {
      "name": "TED",
      "branch": "0001",
      "document": "32402502000135",
      "account_key": "23a4a2c8-9d82-4ebe-a90d-44fe8d839ec0",
      "account_digit": "7",
      "account_number": "00001"
    },
    "timestamp": "2023-01-05T07:35:37.127502",
    "description": "001 0001 81156-1 32.402.502/0001-35 - QI Tech",
    "destination": {
      "name": "Default",
      "branch": "0001",
      "document": "23426525852",
      "account_key": "508ebbba-0b1d-41f6-b9a2-975a4c2e925e",
      "account_digit": "0",
      "account_number": "7058818"
    },
    "reference_key": "58729e67-f490-4607-aafd-2fc7945d3d77",
    "reference_type": "ted_outgoing",
    "account_balance": 99404.15,
    "source_sub_type": "withdrawal",
    "transaction_key": "4ac9e80b-22d9-4097-8676-e19f84c89543",
    "source_sub_type_str": "Transferência"
  },
  "datetime": "2023-01-05T07:35:37.127502",
  "webhook_type": "account_transaction"
}

```

### 3.3. Estorno de uma TED

        **Webhook**

- WEBHOOK_TYPE account_transaction
- SOURCE_SUB_TYPE withdrawal_reversal

Response Body

```json
{
  "key": "508ebbba-0b1d-41f6-b9a2-975a4c2e925e",
  "data": {
    "amount": 550,
    "origin": {
      "name": "TED",
      "branch": "0001",
      "document": "32402502000135",
      "account_key": "23a4a2c8-9d82-4ebe-a90d-44fe8d839ec0",
      "account_digit": "7",
      "account_number": "00001"
    },
    "timestamp": "2023-01-05T07:42:26.631137",
    "description": "001 0001 81156-1 32.402.502/0001-35 - QI Tech",
    "destination": {
      "name": "Default",
      "branch": "0001",
      "document": "23426525852",
      "account_key": "508ebbba-0b1d-41f6-b9a2-975a4c2e925e",
      "account_digit": "0",
      "account_number": "7058818"
    },
    "reference_key": "58729e67-f490-4607-aafd-2fc7945d3d77",
    "reference_type": "ted_outgoing",
    "account_balance": 99954.15,
    "source_sub_type": "withdrawal_reversal",
    "transaction_key": "53268774-6891-42a4-a658-42e21cef867c",
    "source_sub_type_str": "Estorno de Transferência"
  },
  "datetime": "2023-01-05T07:42:26.631137",
  "webhook_type": "account_transaction"
}

```

## 4 - Pagamento QR Code PIX

### 4.1. Pagando um QR Code PIX Estático

Para realizar o pagamento de um QR Code PIX Estático, é necessário realizar quatro chamadas:

1. Decodificar o QR Code PIX: /baas/pix/qrcode

2. Criação do pedido de transferência: /baas/pix_transfer

3. Solicitação de token de validação de transferência: /baas/token_request

4. Aprovação da transferência: /baas/movement_validation

A informação que deve ser utilizada para decodificação do QR Code PIX Estático é a URI do PIX Copia e Cola vinculada ao QR Code.

:::info
**Exemplo de URI PIX Copia e Cola:** 00020126580014br.gov.bcb.pix01360598e5d1-2cfc-4857-abf8-12d495aa0a6d52040000530398654040.225802BR5925VOVO LUCIA CONVENIENCIA L6009sao paulo610912345-78062070503***63043A5A
:::

        **Request**

- ENDPOINT /baas/pix/qrcode
- MÉTODO POST

Reponse Body

```json
{
    "qr_code_payload": "\<URI DO PIX COPIA E COLA\>"
}

```

        **Response**

- MÉTODO POST
- ENDPOINT /baas/pix/qrcode

Response Body

```json
{
	"end_to_end_id": "E3240250220221120030008388062101",
	"qr_code_data": {
		"additional_data": null,
		"amount": 30,
		"ispb_number": "32402502",
		"receiver_conciliation_id": "***",
		"target_account_branch": "0001",
		"target_account_digit": "5",
		"target_account_number": "2",
		"target_account_type": "checking",
		"target_bank_code": 329,
		"target_bank_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"target_document_number": "32402502000135",
		"target_name": "QI SOCIEDADE DE CREDITO DIRETO S.A.",
		"target_person_type": "legal",
		"target_pix_key": "316bd44f-2202-4c33-9dc0-096192acd427"
	},
	"qr_code_key": "1608e022-e42d-49d8-bacf-da5844570635",
	"qr_code_payload": "00020126580014br.gov.bcb.pix0136316bd44f-2202-4c33-9dc0-096192acd427520400005303986540530.005802BR5925QI SOCIEDADE DE CREDITO D6009sao paulo610912345-78062070503***63048698",
	"qr_code_type": "static"
}
```

:::caution Atenção
A requisição para pagar um PIX QR Code Estático é a mesma utilizada na transferência PIX com a as seguintes alterações:
**1** - Adição de um novo campo “***end_to_end_id***”. Deve ser informado o mesmo valor retornado da decodificação do QR Code Estático;

**2** - Informar no campo “***transaction_amount***“ o mesmo valor retornado no campo  “qr_code_data.amount” da decodificação do QR Code Estático;

**3** - Alterar o campo “***pix_transfer_type***” para “***static***“, para solicitação do pagamento via “***/baas/pix_transfer***”.
:::

        **Request**

- MÉTODO POST
- ENDPOINT /baas/pix_transfer

Request Body

```json
{
    "pix_transfer_type": "static",
    "source_account": {
        "account_branch": "0001",
        "account_digit": "2",
        "account_number": "2359934",
        "owner_document_number": "09080702000105"
    },
    "end_to_end_id": "E3240250220221118200949955075000",
    "transaction_amount": 30,
	"pix_key": "316bd44f-2202-4c33-9dc0-096192acd427",
    "requester_document_identification": "09080702000105"
}
```

        **Response**

- MÉTODO POST
- ENDPOINT /baas/pix_transfer

Response Body

```json
{
	"data": {
		"end_to_end_id": "E3240250220221118200949955075000",
		"fee_amount": 1,
		"pix_message": null,
		"pix_transfer_key": "59a0da26-3223-4679-aa2c-020d46e923c1",
		"source_account": {
			"account_brach": "0001",
			"account_digit": "2",
			"account_number": "2359934",
			"account_type": "checking",
			"owner_document_number": "09080702000105",
			"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
		},
		"target_account": {
			"document_number": "32402502000135",
			"financial_institution": "QI SOCIEDADE DE CRÉDITO DIRETO S.A."
		},
		"transaction_amount": 30,
		"transfer_purpose": "transfer"
	},
	"event_datetime": "2022-09-02 23:00:07",
	"operation_key": "527f60a4-0118-4b90-adf8-d33f895c9f8f",
	"status": "pending_approval"
}
```

Após realizar a segunda chamada no endpoint “**/baas/pix_transfer**”, é necessário solicitar o Token para aprovar a transação. Para aprovar a transferência PIX, é necessário utilizar a “**pix_transfer_key**” retornada na solicitação de transferência e solicitar a geração de um token que será enviado ao usuário administrador da conta para aprovação (“***allowed_user***”).

        **Request**

- MÉTODO POST
- ENDPOINT /baas/token_request

Request Body

```json
{
    "contact_type": "sms",
    "agent_document_number": "97564480084",
    "movement_payload": {
        "pix_transfer_key": "59a0da26-3223-4679-aa2c-020d46e923c1",
        "approver_document_number": "97564480084"
    }
}
```

A última chamada para concluir o pagamento será a do “**/baas/movement_validation**” e o Token enviado deve ser informado no momento da aprovação da transferência PIX. A validade do Token é de 2 minutos. 
O usuário administrador deve inserir na aplicação do parceiro o token recebido via E-mail ou SMS.

        **Request**

- MÉTODO POST
- ENDPOINT /baas/movement_validation

Request Body

```json
{
    "token": "957219",
    "movement_payload": {
        "pix_transfer_key": "59a0da26-3223-4679-aa2c-020d46e923c1",
        "approver_document_number": "97564480084"
    }
}
```

        **Response**

- MÉTODO POST
- ENDPOINT /baas/movement_validation

Response Body

```json
{
	"authentication_code": "4c579663bd3f369c4f5f5cd89d8e1a24",
	"event_datetime": "2022-09-02 23:00:07",
	"operation_key": "527f60a4-0118-4b90-adf8-d33f895c9f8f",
	"pix_transaction": {
		"end_to_end_id": "E3240250220221118200949955075000",
		"fee_amount": 1,
		"pix_message": null,
		"pix_transfer_key": "59a0da26-3223-4679-aa2c-020d46e923c1",
		"pix_transfer_status": "sent",
		"pix_transfer_type": "static",
		"source_account": {
			"account_branch": "0001",
			"account_digit": "2",
			"account_number": "2359934"
		},
		"target_account": {
			"document_number": "***.221.81*-**",
			"financial_institution": "BANCO ORIGINAL S.A."
		},
		"transaction_key": "d5134c23-18d2-4279-bc99-459312b64bfc",
		"transfer_amount": 30
	},
	"status": "sent"
}
```

:::info

A única diferença desta Response em relação a Response de Aprovação de Transferência PIX, é o valor do campo “***pix_transfer_type***“, que é retornado como sendo “***static***”.

:::

### 4.2. Pagando um QR Code PIX Dinâmico

Para realizar o pagamento de um QR Code PIX Dinâmico, é necessário realizar quatro chamadas:

1. Decodificar o QR Code PIX: /baas/pix/qrcode

2. Criação do pedido de transferência: /baas/pix_transfer

3. Solicitação de token de validação de transferência: /baas/token_request

4. Aprovação da transferência: /baas/movement_validation. A informação que deve ser utilizada para decodificação do QR Code PIX Dinâmico é a URI do PIX Copia e Cola vinculada 

:::info
A única alteração no “***/baas/pix/qrcode***“ entre é QR Code PIX Estático e o QR Code PIX Dinâmico, é a resposta do endpoint.
:::

        **Response**

- MÉTODO POST
- ENDPOINT /baas/pix/qrcode

Response Body

```json
{
	"end_to_end_id": "E3240250220221120162904592385040",
	"qr_code_data": {
		"account_type": "checking",
		"additional_data": [],
		"address": "Avenida Brigadeiro Faria Lima",
		"amount": 35,
		"category_code": "0000",
		"city": "Sao Paulo",
		"created_at": "2022-09-01T20:20:11",
		"days_after_due_accepted": 180,
		"discount_amount": null,
		"due_date": "2022-11-30",
		"fee_amount": null,
		"fine_amount": null,
		"ispb_number": "32402502",
		"original_amount": null,
		"payer_document_number": "10932327656",
		"payer_name": "Payer Name",
		"payer_person_type": "natural",
		"postal_code": "01452000",
		"presented_at": "2022-09-01T16:29:04",
		"question_to_payer": "QR Code Payment",
		"receiver_conciliation_id": "a6c3f35b342047e58ac105a0ae0c0c6f",
		"receiver_url": null,
		"reduction_amount": null,
		"reusable_qrcode": "yes",
		"revision": 1,
		"state": "SP",
		"status": "active",
		"target_account_branch": "0001",
		"target_account_digit": "5",
		"target_account_number": "2",
		"target_bank_code": 329,
		"target_bank_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"target_document_number": "32402502000135",
		"target_name": "QI SOCIEDADE DE CREDITO DIRETO S.A.",
		"target_person_type": "legal",
		"target_pix_key": "316bd44f-2202-4c33-9dc0-096192acd427",
		"target_trading_name": null
	},
	"qr_code_key": "a1bcf9be-918d-431e-ae79-a75f78337423",
	"qr_code_payload": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/a6c3f35b-3420-47e5-8ac1-05a0ae0c0c6f5204000053039865802BR5902QI6009Sao Paulo61080145200062070503***6304AFEE",
	"qr_code_type": "dynamic_term"
}
```

:::caution Atenção
A requisição para pagar um PIX QR Code Dinâmico é a mesma utilizada na transferência PIX com a as seguintes alterações:

1 - Adição de um novo campo “end_to_end_id”. Deve ser informado o mesmo valor retornado da decodificação do QR Code Dinâmico.
2 - Informar no campo “transaction_amount“ o mesmo valor retornado no campo  “qr_code_data.amount” da decodificação do QR Code Dinâmico;
3 - Alterar o campo “pix_transfer_type” para “dynamic_term“, para solicitação do pagamento via “/baas/pix_trasnfer”.
4 - Adição de um novo campo “receiver_conciliation_id”. Deve ser informado o mesmo valor retornado da decodificação do QR Code Dinâmico.
:::

        **Request**

- MÉTODO POST
- ENDPOINT /baas/pix_transfer

Response Body

```json
{
    "pix_transfer_type": "dynamic_term",
    "source_account": {
        "account_branch": "0001",
        "account_digit": "2",
        "account_number": "2359934",
        "owner_document_number": "09080702000105"
    },
    "end_to_end_id": "E3240250220221120162904592385040",
    "receiver_conciliation_id": "a6c3f35b342047e58ac105a0ae0c0c6f",
    "transaction_amount": 35,
    "requester_document_identification": "09080702000105"
}
```

        **Response**

- MÉTODO POST
- ENDPOINT /baas/pix_transfer

Response Body

```json
{
	"data": {
		"end_to_end_id": "E3240250220221120162904592385040",
		"fee_amount": 0,
		"pix_message": null,
		"pix_transfer_key": "8ddd3bce-5130-4b5b-b7f1-40f17547a413",
		"source_account": {
			"account_brach": "0001",
			"account_digit": "2",
			"account_number": "2359934",
			"account_type": "checking",
			"owner_document_number": "09080702000105",
			"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
		},
		"target_account": {
			"document_number": "32402502000135",
			"financial_institution": "QI SOCIEDADE DE CRÉDITO DIRETO S.A."
		},
		"transaction_amount": 35,
		"transfer_purpose": "transfer"
	},
	"event_datetime": "2022-09-02 13:45:44",
	"operation_key": "c697d8d8-4520-4285-b5ec-d573fb6c1eb3",
	"status": "pending_approval"
}
```

Após realizar a segunda chamada no endpoint “***/baas/pix_transfer***”, é necessário solicitar o Token para aprovar a transação. Para aprovar a transferência PIX, é necessário utilizar a “***pix_transfer_key***” retornada na solicitação de transferência e solicitar a geração de um token que será enviado ao usuário administrador da conta para aprovação (“***allowed_user***”).

        **Request**

- MÉTODO POST
- ENDPOINT /baas/token_request

Response Body

```json
{
    "contact_type": "sms",
    "agent_document_number": "97564480084",
    "movement_payload": {
        "pix_transfer_key": "8ddd3bce-5130-4b5b-b7f1-40f17547a413",
        "approver_document_number": "97564480084"
    }
}
```
 

A última chamada para concluir o pagamento será a do “***/baas/movement_validation***” e o Token enviado deve ser informado no momento da aprovação da transferência PIX. A validade do Token é de 2 minutos. 
O usuário administrador deve inserir na aplicação do parceiro o token recebido via E-mail ou SMS.

        **Request**

- MÉTODO POST
- ENDPOINT /baas/movement_validation

Response Body

```json

{
    "token": "231564",
    "movement_payload": {
        "pix_transfer_key": "8ddd3bce-5130-4b5b-b7f1-40f17547a413",
        "approver_document_number": "97564480084"
    }
}
```

        **Response**

- MÉTODO POST
- ENDPOINT /baas/movement_validation

Response Body

```json
{
	"authentication_code": "936c01a20ebf73c6d474a14bc32553b0",
	"event_datetime": "2022-09-02 23:00:07",
	"operation_key": "c697d8d8-4520-4285-b5ec-d573fb6c1eb3",
	"pix_transaction": {
		"end_to_end_id": "E3240250220221120162904592385040",
		"fee_amount": 1,
		"pix_message": null,
		"pix_transfer_key": "8ddd3bce-5130-4b5b-b7f1-40f17547a413",
		"pix_transfer_status": "sent",
		"pix_transfer_type": "dynamic_term",
		"source_account": {
			"account_branch": "0001",
			"account_digit": "2",
			"account_number": "2359934"
		},
		"target_account": {
			"document_number": "***.221.81*-**",
			"financial_institution": "BANCO ORIGINAL S.A."
		},
		"transaction_key": "96e063f4-b1fb-4f93-ae30-906029764a0a",
		"transfer_amount": 35
	},
	"status": "sent"
}
```

:::info
A única diferença desta Response em relação a Response de Aprovação de Transferência PIX, é o valor do campo “***pix_transfer_type***“, que é retornado como sendo “***dynamic_term***”.
:::

## 5 - Gerenciar Chaves PIX

:::info
A “***pix_key***” pode ser um **CPF**, **CNPJ**, **E-mail**, **Celular** ou uma **Chave Aleatória** (UUID), seguindo as seguintes formatações:

**CPF:** Número inteiro com 11 dígitos.

**CNPJ:** Número inteiro com 14 dígitos.

**E-mail:** Texto contendo ao menos um “@”.

**Celular:** Texto contendo os seguintes valores: “+55” + “DDD do celular“ + “Número Inteiro do Celular com no mínimo 8 e no máximo 9 dígitos”. Ex: “+5511987654321“.

**Chave Aleatória:** UUID.
:::

### 5.1. Criar Chave PIX CPF, CNPJ ou Aleatória
Para criar uma chave PIX CNPJ ou Chave Aleatória, basta acionar o endpoint “***/baas/pix/keys***“, alterando apenas o “***pix_key_type***“ para “**cnpj**”, “**cpf**” ou “**random_key**”.

        **Request**

- MÉTODO POST
- ENDPOINT /baas/pix/keys

Request Body

```json

{
    "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
    "pix_key_type": "random_key"
}
```

ou

Request Body

```json

{
    "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
    "pix_key_type": "cnpj",
    "pix_key": "09080702000105"
}

```

ou

**payload.json**

```json

{
    "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
    "pix_key_type": "cpf",
    "pix_key": "03882617038"
}

```

        **Response**

- MÉTODO POST
- ENDPOINT /baas/pix/keys

Response Body

```json

{
	"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
	"created_at": "2022-09-02T18:20:52",
	"pix_key": {
		"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
		"created_at": "2022-09-02T18:20:51",
		"pix_key": "09080702000105",
		"pix_key_status": "pending_confirmation",
		"pix_key_type": "cnpj",
		"updated_at": "2022-09-02T18:20:51"
	},
	"pix_key_request_key": "d60abf67-ad9c-42ee-9089-d26c8fc855b9",
	"request_data": {
		"account_created_at": "2022-09-02T22:44:36",
		"account_digit": "2",
		"account_number": "2359934",
		"account_type": "checking",
		"branch_number": "0001",
		"key": "09080702000105",
		"owner_document_number": "09080702000105",
		"owner_name": "VOVO LUCIA CONVENIENCIA LTDA",
		"owner_person_type": "legal",
		"trading_name": "VOVO LUCIA"
	},
	"request_failure_reason": null,
	"request_status": "pending",
	"request_type": "inclusion",
	"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
	"updated_at": "2022-09-02T18:20:52"
}
```

:::caution Atenção
No caso da Response de criação de uma Chave PIX **Aleatória**, o campo “***pix_key***“ retornará um valor nulo, já que se trata de um
processo assíncrono onde a chave é gerada pelo Banco Central. Para recuperar o valor da chave aleatória gerada, é necessária realizar uma consulta à lista de chaves cadastradas em uma conta, conforme descrito no item “**Consultar Chaves PIX cadastradas em uma conta**, ou aguardar o webhook de inclusão.“.
:::

:::info
Como se trata de um processo assíncrono para verificar se as chave PIX **CNPJ** ou **CPF** estão ativas, é necessário realizar uma consulta à lista de chaves cadastradas em um conta, conforme descrito no item “**Consultar Chaves PIX cadastradas em uma conta**", ou aguardar o webhook de inclusão.
:::

**Webhook**

- WEBHOOK_TYPE key_inclusion

Response Body

```json
{
	"pix_key": "c232142c-ddbf-41d6-a54f-3b90c28b97dc",
	"account_key": "94945886-7a6f-43e6-a307-e36c959e4903",
	"webhook_type": "key_inclusion",
	"pix_key_status": "active",
	"pix_key_request_key": "e274eb13-40b3-4902-978e-8e5fa267af53",
	"pix_key_request_type": "inclusion",
	"pix_key_request_status": "approved"
}
```

### 5.2. Criar Chave PIX E-mail e Celular

Para criar uma chave PIX **E-mail** ou **Celular** deve-se acionar dois endpoints:

**1 - Para criação da chave:** POST no endpoint “**/baas/pix/keys**“, alterando o campo “***pix_key_type***“ para “email” ou “phone_number”. Neste momento, será enviado um Token para o E-mail ou Celular informado no campo “***pix_key***“.

**2 - Para aprovação da chave:** PATCH no endpoint “**/baas/pix/keys/\ **“, informando o Token recebido na etapa anterior.

        **Request**

- MÉTODO POST
- ENDPOINT /baas/pix/keys

Request Body

```json
{
    "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
    "pix_key_type": "email",
    "pix_key": "vovo.lucia@gmail.com.br"
}
```

ou

Request Body

```json
{
    "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
    "pix_key_type": "phone_number",
    "pix_key": "+5511987654321"
}

```

        **Response**

- MÉTODO POST
- ENDPOINT /baas/pix/keys

Response Body

```json
{
	"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
	"created_at": "2022-09-02T17:41:55",
	"pix_key": {
		"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
		"created_at": "2022-09-02T17:41:54",
		"pix_key": "pedro.pinho@qitech.com.br",
		"pix_key_status": "pending_confirmation",
		"pix_key_type": "email",
		"updated_at": "2022-09-02T17:41:54"
	},
	"pix_key_request_key": "f6209b7e-82da-44a8-9cfa-6ad0a689adb2",
	"request_data": {
		"account_created_at": "2022-09-02T22:44:36",
		"account_digit": "2",
		"account_number": "2359934",
		"account_type": "checking",
		"branch_number": "0001",
		"key": "pedro.pinho@qitech.com.br",
		"owner_document_number": "09080702000105",
		"owner_name": "VOVO LUCIA CONVENIENCIA LTDA",
		"owner_person_type": "legal",
		"trading_name": "VOVO LUCIA"
	},
	"request_failure_reason": null,
	"request_status": "pending",
	"request_type": "inclusion",
	"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
	"updated_at": "2022-09-02T17:41:55"
}
```

**IMPORTANTE:** O valor retornado no campo “pix_key_request_key“ deve ser utilizado na URL da requisição para aprovação da criação da Chave PIX.

### 5.3. Aprovação da Chave PIX E-mail ou Celular solicitada

        **Request**

- MÉTODO PATCH
- ENDPOINT /baas/pix/keys/ PIX_KEY_REQUEST_KEY /twofa_validation

Request Body

```json
{
    "verification_code": "756816"
}
```

### 5.4. Reenviar o código de verificação

        **Request**

- MÉTODO PATCH
- ENDPOINT /baas/pix/keys/ PIX_KEY_REQUEST_KEY /resend_twofa

**payload.json**

```json
{}
```

### 5.5. Consultar Chaves PIX cadastradas em uma conta

        **Request**

- MÉTODO GET
- ENDPOINT /baas/pix/keys
- PARAMETERS account_key

        ***Response***

Response Body

```json

{
  "data": [
    {
      "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
      "created_at": "2022-09-02T17:17:31",
      "pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
      "pix_key_status": "active",
      "pix_key_type": "random_key",
      "updated_at": "2022-09-02T17:17:31"
    },
    {
      "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
      "created_at": "2022-09-02T18:20:51",
      "pix_key": "09080702000105",
      "pix_key_status": "active",
      "pix_key_type": "cnpj",
      "updated_at": "2022-09-02T18:20:51"
    }
  ]
}
```

### 5.6. Exclusão de Chaves PIX

        **Request**

- MÉTODO DELETE
- ENDPOINT /baas/pix/keys/PIX-KEY

Payload: { }

        **Response**

Response Body

```json
{
	"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
	"created_at": "2022-09-02T20:00:36",
	"pix_key": {
		"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
		"created_at": "2022-09-02T18:20:51",
		"pix_key": "09080702000105",
		"pix_key_status": "inactivated",
		"pix_key_type": "cnpj",
		"updated_at": "2022-09-02T20:00:36"
	},
	"pix_key_request_key": "dced4317-c1e7-4da4-a75a-42f855c7598e",
	"request_data": {},
	"request_failure_reason": null,
	"request_status": "approved",
	"request_type": "deletion",
	"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
	"updated_at": "2022-09-02T20:00:36"
}

```

## 6 - Gerar QR Code PIX

### 6.1. Gerando QR Code PIX Estático

O QR Code é criado a partir de uma Chave PIX ativa cadastrada em uma conta. Após a geração do QR Code, serão retornados tanto a URI do PIX Copia e Cola vinculada ao QR Code, como também o base64 da imagem do QR Code (caso solicitado).

A imagem do QR Code pode ser gerada pelo próprio parceiro a partir da URI do PIX Copia e Cola.

Para gerar um QR Code PIX Estático será usada apenas uma requisição:

        **Request**

- MÉTODO POST
- ENDPOINT /baas/qrcode/static

Request Body

```json
{
    "pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
    "amount": 35.00,
    "receiver_name": "Tywin Lannister",
    "qr_code_format": "both"
}

```

:::info
No campo **qr_code_format** poderá ser informado os valores “***image***”, “***payload***“ e “***both***”.
- “***image***”: será retornado o campo com o base64 da imagem do QR Code PIX.
- “***payload***”: será retornado o campo com o base64 da URI do PIX Copia e Cola do QR Code PIX.
- “***both***”: serão retornados os dois campos.
:::

        **Response**

- MÉTODO POST
- ENDPOINT /baas/qrcode/static

Response Body

```json
{
    "external_reference_key": null,
    "image": "\<BASE 64 DO QR CODE PIX\>",
    "payload": "MDAwMjAxMjY0NzAwMTRici5nb3YuYmNiLnBpeDAxMjVwZWRyby5waW5ob0BxaXRlY2guY29tLmJyNTIwNDAwMDA1MzAzOTg2NTQwNTM1LjAwNTgwMkJSNTkxNVR5d2luIExhbm5pc3RlcjYwMDlzYW8gcGF1bG82MTA5MTIzNDUtNzgwNjIwNzA1MDMqKio2MzA0M0QzMA",
    "revision": null
}

```

### 6.2. Gerando QR Code PIX Dinâmico

Existem dois tipos de QR Code Dinâmico. O QR Code Dinâmico com Pagamento Instantâneo e o QR Code Dinâmico com Vencimento.

#### 6.2.1. Gerando QR Code PIX Dinâmico com Vencimento

É um tipo de QR Code PIX que funciona de forma muito semelhante a um boleto bancário, podendo possuir informação de vencimento, multa, juros por atraso e desconto por pagamento antecipado. Para gerar ester tipo de QR Code PIX é necessário apenas uma requisição no Endpoint “***/baas/qrcode/dynamic***“.

        **Request**

- MÉTODO POST
- ENDPOINT /baas/qrcode/dynamic

Request Body

```json
{
	"amount": 100,
	"qr_code_type": "dynamic_term",
	"occurrence_type": "registration",
	"max_payment_days": 180,
	"expiration_date": "2025-09-24",
	"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
	"payer_name": "QI Tech",
	"payer_document_number": "98765432100",
	"payer_person_type": "natural",
	"payer_request": "O que voce achou da experiencia",
	"rebate_amount": 0,
	"interest_amount": 1,
	"fine_amount": 2,
	"discounts": [{
		"limit_date": "2023-02-24",
		"amount": 20,
		"discount_type": "absolute"
	}],
	"additional_data": [{
		"\<tag_name\>": "\<tag_value\>"
	}]
}

```

:::info
**occurrence_type:** neste campo é informada a ação pretendida. Podem ser: registration, edit, write_off 
- **registration:** Para criar um novo QR Code
- **edit:** Para editar um QR Code já existente (Conforme descrito no item abaixo).
- **write_off:** para baixar um QR Code ativo.

**interest_amount:** valor em reais (R$) de juros cobrados por dia de atraso.

**fine_amount:** valor da multa por atraso, em reais (R$).

**discounts:** informação do desconto por pagamento antecipado. Caso não seja aplicável, enviar uma lista vazia ([]). 

**additional_data:** são metatags customizáveis que podem ser apresentadas para o pagador no momento do pagamento. Seguem o seguinte padrão: ”\ ”: “\ “.

**tag_name** possui uma limitação de 100 caracteres e **tag_value** possui uma limitação de 320 caracteres.
:::

        **Response**

- MÉTODO POST
- ENDPOINT /baas/qrcode/dynamic

Response Body

```json
{
	"qr_code_type": "dynamic_term",
	"amount": 100,
	"expiration_seconds": null,
	"max_payment_days": 180,
	"receiver_conciliation_id": "3bd19ada234141bf9f1fc5ce0b216723",
	"payer_name": "QI Tech",
	"payer_document_number": "98765432100",
	"payer_person_type": "natural",
	"payer_request": "O que voce achou da experiencia",
	"pix_message": null,
	"modality_alteration": false,
	"expiration_date": "2025-09-24",
	"rebate_amount": 10,
	"interest_amount": 10,
	"fine_amount": 10,
	"paid_amount": null,
	"discounts": [{
		"discount_type": "absolute",
		"limit_date": "2023-02-24",
		"amount": 20
	}],
	"additional_data": [{
		"\<tag_name\>": "\<tag_value\>"
	}],
	"origin": "system",
	"origin_key": null,
	"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
	"qr_code_key": "3bd19ada-2341-41bf-9f1f-c5ce0b216723",
	"occurrence_type": "registration",
	"end_to_end_id": null,
	"base_64": "MDAwMjAxMjY5NzAwMTRici5nb3YuYmNiLnBpeDI1NzVxcmNvZGUtaC5zYW5kYm94LnFpdGVjaC5hcHAvYmFjZW4vY29idi8zYmQxOWFkYS0yMzQxLTQxYmYtOWYxZi1jNWNlMGIyMTY3MjM1MjA0MDAwMDUzMDM5ODY1ODAyQlI1OTI1Vk9WTyBMVUNJQSBDT05WRU5JRU5DSUEgTDYwMDdMaW1laXJhNjEwODEzNDgwMjkwNjIwNzA1MDMqKio2MzA0QzNGNg",
	"image": "\<BASE 64 DO QR CODE PIX\>",
	"source_account_branch": null,
	"source_account_financial_institution": null,
	"source_account_ispb": null,
	"source_account_number": null,
	"source_account_digit": null,
	"qr_code_occurrence_key": "b6777e78-e00c-4e9f-9b44-aa7b551c11e4"
}
```

:::info
O campo “**base_64**“ é a URI do PIX Copia e Cola vinculado a este QR Code PIX Dinâmico.
:::
 

#### 6.2.2. Gerando QR Code PIX Dinâmico com Pagamento Instantâneo

É um tipo de QR Code PIX semelhante ao Estático, porém facilita a conciliação por parte do recebedor do pagamento e pode ter vencimento intradia (podendo durar apenas 5 minutos, por exemplo). 
Para gerar este tipo de QR Code PIX é necessário apenas uma requisição no Endpoint ***“/baas/qrcode/dynamic”***. 

        **Request**

- MÉTODO POST
- ENDPOINT /baas/qrcode/dynamic

Request Body

```json
{
	"amount": 100,
	"occurrence_type": "registration",
	"qr_code_type": "dynamic_instant",
	"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
	"expiration_seconds": 360,
	"payer_name": "QI Tech",
	"payer_document_number": "98765432100",
	"payer_person_type": "natural",
	"payer_request": "Valor referente a compra 1234",
	"additional_data": [{
		"\<tag_name\>": "\<tag_value\>"
	}]
}
```

        **Response**

- MÉTODO POST
- ENDPOINT /baas/qrcode/dynamic

Response Body

```json
{
	"qr_code_type": "dynamic_instant",
	"amount": 100,
	"expiration_seconds": 360,
	"max_payment_days": null,
	"receiver_conciliation_id": "8e5af204fa5844eca9707c4facc5e5f5",
	"payer_name": "QI Tech",
	"payer_document_number": "98765432100",
	"payer_person_type": "natural",
	"payer_request": "Valor referente a compra 1234",
	"pix_message": null,
	"modality_alteration": false,
	"expiration_date": null,
	"rebate_amount": null,
	"interest_amount": null,
	"fine_amount": null,
	"paid_amount": null,
	"discounts": [],
	"additional_data": [{
		"\<tag_name\>": "\<tag_value\>"
	}],
	"origin": "system",
	"origin_key": null,
	"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
	"qr_code_key": "8e5af204-fa58-44ec-a970-7c4facc5e5f5",
	"occurrence_type": "registration",
	"end_to_end_id": null,
	"base_64": "MDAwMjAxMjY4ODAwMTRici5nb3YuYmNiLnBpeDI1NjZxcmNvZGUtaC5zYW5kYm94LnFpdGVjaC5hcHAvYmFjZW4vOGU1YWYyMDRmYTU4NDRlY2E5NzA3YzRmYWNjNWU1ZjU1MjA0MDAwMDUzMDM5ODY1ODAyQlI1OTI1Vk9WTyBMVUNJQSBDT05WRU5JRU5DSUEgTDYwMDdMaW1laXJhNjEwODEzNDgwMjkwNjIwNzA1MDMqKio2MzA0M0RBRA",
	"image": "\<BASE 64 DO QR CODE PIX\>",
	"source_account_branch": null,
	"source_account_financial_institution": null,
	"source_account_ispb": null,
	"source_account_number": null,
	"source_account_digit": null,
	"qr_code_occurrence_key": "838e4bd3-36c9-4aa8-9be8-04079bbe8d1a"
}

```

 

#### 6.2.3. Editar dados de QR Code PIX Dinâmico

Para editar os dados de um QR Code PIX Dinâmico, é necessário informar a “***qr_code_key***“ do QR Code PIX e “***occurrence_type***” igual a “***edit***”. Nesse caso, é preciso reenviar todos os dados novamente.

        **Request**

- MÉTODO POST
- ENDPOINT /baas/qrcode/dynamic

Request Body

```json
{
    "qr_code_key": "3bd19ada-2341-41bf-9f1f-c5ce0b216723",
	"amount": 200,
	"qr_code_type": "dynamic_term",
	"occurrence_type": "edit",
	"max_payment_days": 180,
	"expiration_date": "2025-09-24",
	"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
	"payer_name": "QI Tech",
	"payer_document_number": "98765432100",
	"payer_person_type": "natural",
	"payer_request": "O que voce achou da experiencia",
	"rebate_amount": 0,
	"interest_amount": 1,
	"fine_amount": 2,
	"discounts": [{
		"limit_date": "2023-02-24",
		"amount": 20,
		"discount_type": "absolute"
	}],
	"additional_data": [{
		"\<tag_name\>": "\<tag_value\>"
	}]
}
```

        **Request**

- MÉTODO POST
- ENDPOINT /baas/qrcode/dynamic

Response Body

```json
{
	"qr_code_type": "dynamic_term",
	"amount": 200,
	"expiration_seconds": null,
	"max_payment_days": 180,
	"receiver_conciliation_id": "3bd19ada234141bf9f1fc5ce0b216723",
	"payer_name": "QI Tech",
	"payer_document_number": "98765432100",
	"payer_person_type": "natural",
	"payer_request": "O que voce achou da experiencia",
	"pix_message": null,
	"modality_alteration": false,
	"expiration_date": "2025-09-24",
	"rebate_amount": 10,
	"interest_amount": 10,
	"fine_amount": 10,
	"paid_amount": null,
	"discounts": [{
		"discount_type": "absolute",
		"limit_date": "2023-02-24",
		"amount": 20
	}],
	"additional_data": [{
		"\<tag_name\>": "\<tag_value\>"
	}],
	"origin": "system",
	"origin_key": null,
	"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
	"qr_code_key": "3bd19ada-2341-41bf-9f1f-c5ce0b216723",
	"occurrence_type": "edit",
	"end_to_end_id": null,
	"base_64": "MDAwMjAxMjY5NzAwMTRici5nb3YuYmNiLnBpeDI1NzVxcmNvZGUtaC5zYW5kYm94LnFpdGVjaC5hcHAvYmFjZW4vY29idi8zYmQxOWFkYS0yMzQxLTQxYmYtOWYxZi1jNWNlMGIyMTY3MjM1MjA0MDAwMDUzMDM5ODY1ODAyQlI1OTI1Vk9WTyBMVUNJQSBDT05WRU5JRU5DSUEgTDYwMDdMaW1laXJhNjEwODEzNDgwMjkwNjIwNzA1MDMqKio2MzA0QzNGNg",
	"image": "\<BASE 64 DO QR CODE PIX\>",
	"source_account_branch": null,
	"source_account_financial_institution": null,
	"source_account_ispb": null,
	"source_account_number": null,
	"source_account_digit": null,
	"qr_code_occurrence_key": "d9c01f70-26bc-429d-afd1-038bd3c235b2"
}

```

 

### 6.3. Baixar QR Code PIX Dinâmico

Para baixar um QR Code PIX Dinâmico, é necessário informar a “***qr_code_key***“ do QR Code PIX e “***occurrence_type***” igual a “***write_off***”.

        **Request**

- MÉTODO POST
- ENDPOINT /baas/qrcode/dynamic

Request Body

```json
{
    "qr_code_key": "3bd19ada-2341-41bf-9f1f-c5ce0b216723",
    "occurrence_type": "write_off"
}

```

        **Response**

- MÉTODO POST
- ENDPOINT /baas/qrcode/dynamic

Response Body

```json
{
	"qr_code_type": "dynamic_term",
	"amount": null,
	"expiration_seconds": 86400,
	"max_payment_days": null,
	"receiver_conciliation_id": "3bd19ada234141bf9f1fc5ce0b216723",
	"payer_name": null,
	"payer_document_number": null,
	"payer_person_type": "natural",
	"payer_request": null,
	"pix_message": null,
	"modality_alteration": false,
	"expiration_date": null,
	"rebate_amount": null,
	"interest_amount": null,
	"fine_amount": null,
	"paid_amount": null,
	"discounts": [],
	"additional_data": [],
	"origin": "system",
	"origin_key": null,
	"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
	"qr_code_key": "3bd19ada-2341-41bf-9f1f-c5ce0b216723",
	"occurrence_type": "write_off",
	"end_to_end_id": null,
	"base_64": null,
	"image": null,
	"source_account_branch": null,
	"source_account_financial_institution": null,
	"source_account_ispb": null,
	"source_account_number": null,
	"source_account_digit": null,
	"qr_code_occurrence_key": "46001adf-ffe2-4534-b60e-f6c16b9af56e"
}
```

## 7 - Registrar, Alterar e Pagar boletos bancários

### 7.1. Consulta de Carteiras de Cobrança

Para registrar, alterar e pagar boletos, é preciso, primeiramente, possuir o Código da Carteira de Cobrança (Requester Profile Code) vinculada a uma conta. Toda conta já nasce com uma Carteira de Cobrança vinculada. 

O Código da Carteira de Cobrança segue o seguinte padrão:

”No. do banco” + “código da carteira” + “No. agência da conta” + “No. da Conta com 7 caracteres e sem dígito“.
Por padrão, na QI Tech, os números do banco, do código da carteira e agência sempre serão “329”, “09” e “0001”, respectivamente.
ex: “**329-09-0001-2359934**”.

Caso seja necessário recuperar a lista de Códigos de Carteira de Cobrança de cada conta, deve ser utilizado o seguinte endpoint:

        **Request**

- MÉTODO GET
- ENDPOINT /bank_slip/requester_profiles

        ***Response***

Response Body

```json
{
    "requester_profile_codes": [
        "329-09-0001-1467576",
        "329-09-0001-5747500",
        "329-09-0001-2730579",
        "329-09-0001-2359934"
    ]
}
```
 

:::tip NOTA
O registro, alteração e baixa de boletos, funciona através da dinâmica de ocorrências. Cada ocorrência é enviada para a QI Tech e encaminhada para a base centralizadora de boletos.
As ocorrências podem ser aceitas ou rejeitadas pelo base centralizadora de boletos.
A resposta a respeito da aceitação ou rejeição das ocorrências é enviada via webhook ao parceiro
:::

### 7.2. Registrar Boleto 
Para realizar o registro de um boleto, é necessário enviar uma ocorrência de registro, conforme descrito no endpoint abaixo:

        **Request**

- MÉTODO POST
- ENDPOINT /multibank_instruction?use_multi_process=true

Request Body

```json

{
    "occurrences": [
        {
            "amount": 800,
            "our_number": 1,
            "automatic_bankruptcy_protest": false,
            "bank_teller_instructions": "Não aceitar após vencimento",
            "days_to_bankruptcy_protest": 0,
            "document_number": "123456/01",
            "expiration": "2022-12-01",
            "fine_percentage": "2",
            "interest_daily_value": "0.34",
            "occurrence_type": "registration",
            "payer_address": "Rua Carlos Sampaio, 123",
            "payer_document": "41184562067",
            "payer_name": "João Ninguem",
            "payer_person_type": "natural",
            "payer_postal_code_root": "15800",
            "payer_postal_code_suffix": "020",
            "registration_institution_enumerator": "qi_scd",
            "requester_profile": 9,
            "requester_profile_code": "329-09-0001-2359934"
        }
    ]
}
```

:::info
O nosso número bancário (“***our_number***”) é o ID do boleto dentro da carteira de cobrança. Ele deve ser um ID incremental.
O nosso número bancário (“***our_number”) deve ser gerado pelo parceiro e informado no momento do registro do boleto.

**IMPORTANTE:** O boleto deve ser localizado através da chave: nosso número bancário (“***our_number***”) + Código da Carteira de Cobrança (“***requester_profile_code***“).
:::

        **Response**

- MÉTODO POST
- ENDPOINT /multibank_instruction?use_multi_process=true

Response Body

```json
{
	"file_info": {
		"beneficiary_code": null,
		"beneficiary_name": null,
		"file_sequence_id": null,
		"file_type_identifier": null,
		"file_type_literal": null,
		"service_code": null,
		"service_literal": null,
		"wrote_at": null
	},
	"occurrence_stats": {
		"bank_slip_edit": 0,
		"bankruptcy_protest_request": 0,
		"cancel_rebate": 0,
		"extension": 0,
		"notary_office_entry": 0,
		"notary_office_exit": 0,
		"notary_office_payment": 0,
		"notification": 0,
		"payment": 0,
		"payment_notice": 0,
		"payment_write_off": 0,
		"protest_cancel_and_write_off_request": 0,
		"protest_cancel_request": 0,
		"protest_remove_request": 0,
		"protest_request": 0,
		"rebate": 0,
		"registration": 1,
		"write_off": 0
	},
	"semantic_errors": []
}
```

A resposta sobre a aceitação ou rejeição do registro do boleto será informada através do seguinte webhook.

        **Webhook**

- WEBHOOK_TYPE bank_slip.status_change
- STATUS registered

Response Body

```json
{
	"key": "41927fa9-f9ed-4797-b48a-6ac68e58dc17",
	"data": {
		"expiration": "2022-12-01",
		"our_number": 1,
		"bank_slip_key": "41927fa9-f9ed-4797-b48a-6ac68e58dc17",
		"rebate_amount": 0,
		"occurrence_type": "registration",
		"occurrence_feedback": "confirmed",
		"occurrence_sequence": 0,
		"requester_profile_code": "329-09-0001-2359934",
		"glados_occurrence_reasons": null,
		"cnab_file_occurrence_order": 1,
		"registration_institution_occurrence_date": "2022-11-21"
	},
	"status": "registered",
	"webhook_type": "bank_slip.status_change",
	"event_datetime": "2022-11-22 00:41:32"
}
```

Para vincular o webhook enviado a um boleto, deve-se utilizar o nosso número bancário (“***our_number***”) e o Código da Carteira de Cobrança (“requester_profile_code“).

Assim que o registro do boleto é aceito pela base centralizadora, é retornado no webhook a chave UUID do boleto (“***bank_slip_key***“). Guarde essa chave pois através dela será possível recuperar as informações do boleto.

### 7.2. Alterar Dados do Boleto

Para alterar os dados de um boleto, é necessário enviar uma ocorrência. Cada possível alteração possui sua ocorrência correspondente. A lista de ocorrências para alteração dos dados de um boleto pode ser verificada em nossa documentação Enviar instrução de Boleto[LINK]).

### 7.3. Solicitação de 2ª via de boleto

Após o registro do boleto, pode ser solicitada a geração de um arquivo “.pdf” do boleto, contendo os dados para pagamento.

        **Request**

- MÉTODO POST
- ENDPOINT /bank_slip/2-way/BANKSLIP-KEY

Payload: { }

        **Response**

Response Body

```json
{
	...
	"bank_slip_file": [{
		"barcode": "32991918600000800000001090000000000123599340",
		"created_at": "2022-11-21T23:29:45",
		"digitable_line": "32990001039000000000101235993407191860000080000",
		"url": "https://storage.googleapis.com/sandbox-bank-slip-api/bank-slip-pdf/41927fa9-f9ed-4797-b48a-6ac68e58dc17_1.pdf"
	}],
	...
}
```

:::info
Serão retornados todos os dados do boleto e o link para download do “.pdf” será informado no objeto “bank_slip_file.url“.
:::

### 7.4. Consultar dados de um Boleto

Os dados de um boleto podem ser consultados de duas formas diferentes.

#### 7.4.1. Consulta através da linha digitável

A linha digitável de um boleto é uma série numérica que traz em si as informações do boleto. Esta série numérica é digitada pelo usuário pagador do boleto no internet-banking do banco pagador.

:::info
Exemplo de linha digitável: 32990001031000000000902000000204685640000100000
:::

Através da linha digitável, podem ser consultados os dados do boleto:

        **Request**

- MÉTODO GET
- ENDPOINT /bank_slip/payment
- PARAMETERS digitable_line

        **Response**

Response Body

```json
{
	"barcode": "32991918600000800000001090000000000123599340",
	"beneficiary_bank_code": "329",
	"beneficiary_document_number": "09080702000105",
	"beneficiary_legal_name": "VOVO LUCIA CONVENIENCIA LTDA",
	"beneficiary_person_type": "legal",
	"calculated_internally": true,
	"calculation_date": "2022-11-21",
	"calculation_model": 1,
	"digitable_line": "32990001039000000000101235993407191860000080000",
	"discount_amount": "0",
	"expiration_date": "2022-12-01",
	"expired_as_of_payment_date": false,
	"expired_as_of_today": false,
	"factual_expiration_date": "2022-12-01",
	"fine_amount": "0",
	"guarantor_document": null,
	"guarantor_name": null,
	"interest_amount": "0",
	"max_payment_date": "2023-05-30",
	"nominal_amount": "800.00",
	"payer_document_number": "41184562067",
	"payer_legal_name": "Jo_o Ninguem",
	"payer_person_type": "natural",
	"payment_date": "2022-11-21",
	"rebate_amount": "0.0",
	"total_amount": "800.0",
	"valid_payment_amount": true,
	"valid_payment_calculation": true,
	"valid_payment_time_frame": true
}
```

#### 7.4.2. Consulta através da Chave do Boleto

Assim que o registro do boleto é aceito pela base centralizadora, é retornado no webhook a chave UUID do boleto (“***bank_slip_key***“). Através dessa chave é possível recuperar as informações do boleto:

        **Request**

- MÉTODO GET
- ENDPOINT /bank_slip/BANKSLIP-KEY

Request Body

```json
{
	"barcode": "32991918600000800000001090000000000123599340",
	"beneficiary_bank_code": "329",
	"beneficiary_document_number": "09080702000105",
	"beneficiary_legal_name": "VOVO LUCIA CONVENIENCIA LTDA",
	"beneficiary_person_type": "legal",
	"calculated_internally": true,
	"calculation_date": "2022-11-21",
	"calculation_model": 1,
	"digitable_line": "32990001039000000000101235993407191860000080000",
	"discount_amount": "0",
	"expiration_date": "2022-12-01",
	"expired_as_of_payment_date": false,
	"expired_as_of_today": false,
	"factual_expiration_date": "2022-12-01",
	"fine_amount": "0",
	"guarantor_document": null,
	"guarantor_name": null,
	"interest_amount": "0",
	"max_payment_date": "2023-05-30",
	"nominal_amount": "800.00",
	"payer_document_number": "41184562067",
	"payer_legal_name": "Jo_o Ninguem",
	"payer_person_type": "natural",
	"payment_date": "2022-11-21",
	"rebate_amount": "0.0",
	"total_amount": "800.0",
	"valid_payment_amount": true,
	"valid_payment_calculation": true,
	"valid_payment_time_frame": true
}
```

### 7.5. Pagar Boleto

Para realizar o pagamento de um Boleto é necessário realizar duas chamadas: 

1. Solicitação de token de validação de transferência: /baas/token_request

2. Aprovação da transferência: /baas/movement_validation

        **Request**

- MÉTODO POST
- ENDPOINT /baas/token_request

Request Body

```json
{
    "contact_type": "email",
    "agent_document_number": "97564480084",
    "movement_payload": {
        "resource_account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
        "digitable_line": "32990001031000699926165000000201993810000003500"
    }
}

```

:::info
O Token enviado deve ser informado no momento da aprovação do pagamento do boleto, e o “***movement_payload***” deve ser o mesmo informado no momento da solicitação do Token.
:::

        **Request**

- MÉTODO POST
- ENDPOINT /baas/movement_validation

Request Body

```json
{
    "token": "358192",
    "movement_payload": {
        "resource_account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
        "digitable_line": "32990001031000699926165000000201993810000003500"
    }
}

```

        **Response**

- MÉTODO POST
- ENDPOINT /baas/movement_validation

Response Body

```json
{
	"authentication_code": "7bf20f1721ecc043d2a16a20ae668b01",
	"bank_slip": {
		"beneficiary": {
			"document_number": "32402502000135",
			"document_number_formatted": "32.402.502/0001-35",
			"name": "QI SCD"
		},
		"digitable_line": "32990001031000699926165000000201993810000003500",
		"expiration_date": "2023-06-14",
		"expiration_date_formatted": "14/06/2023",
		"financial_institution_compe_number": "329",
		"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"payer": {
			"document_number": "10932327656",
			"document_number_formatted": "109.323.276-56",
			"name": "Lucas Clarim"
		},
		"payment_date": "2022-11-22",
		"payment_date_formatted": "22/11/2022",
		"payment_key": "13b35108-0fdc-44ab-b86d-5dda12dc8dce"
	},
	"origin_key": "13b35108-0fdc-44ab-b86d-5dda12dc8dce",
	"pdf_encoded_string": "\<BASE 64 DO COMPROVANTE\>",
	"source_account": {
		"account_branch": "0001",
		"account_digit": "2",
		"account_number": "2359934",
		"financial_institution_compe_number": 329,
		"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"owner_document_number": "09080702000105",
		"owner_document_number_formatted": "09.080.702/0001-05",
		"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
	},
	"source_subtype": "bank_slip_payment",
	"source_subtype_translation_ptbr": "Pagamento de Boleto",
	"transacted_at": "2022-11-22 12:26:21",
	"transacted_at_br": "2022-11-22 09:26:21",
	"transacted_at_br_formatted": "22/11/2022, 09:26:21",
	"transacted_at_formatted": "22/11/2022, 12:26:21",
	"transaction_amount": 35,
	"transaction_amount_formatted": "R$ 35,00",
	"transaction_key": "eee862b9-7f2e-4eea-b04a-fa0e89442618"
}
```

 
### 7.6. Notificação de aviso de recebimento de um Boleto

No momento em que um boleto é pago em outro banco, é enviado um aviso de que este boleto foi pago em tempo real. A Liquidação financeira do pagamento ocorrerá no próximo dia útil.

        **Webhook**

- WEBHOOK_TYPE bank_slip.status_change
- STATUS payment_notice

Response Body

```json
{
	"key": "945e191d-1a78-4a28-8669-000b7e4a3522",
	"data": {
		"our_number": 1,
		"paid_amount": 800,
		"payment_bank": 341,
		"bank_slip_key": "41927fa9-f9ed-4797-b48a-6ac68e58dc17",
		"payment_method": 2,
		"payment_origin": 3,
		"occurrence_type": "payment_notice",
		"occurrence_feedback": "confirmed",
		"occurrence_sequence": 0,
		"requester_profile_code": "329-09-0001-2359934",
		"registration_institution": "qi_scd",
		"cnab_file_occurrence_order": 1,
		"registration_institution_occurrence_date": "2022-11-02"
	},
	"status": "payment_notice",
	"webhook_type": "bank_slip.status_change",
	"event_datetime": "2022-11-21 23:02:02"
}
```

:::info
**payment_method:** é o meio de pagamento do boleto, podendo ser:

**“credit_card”:** cartão de crédito 

**”cash”:** dinheiro

**”account_debit”:** débito em conta 

**”check”:** cheque
:::

:::info
**payment_origin:** é a origem do local do pagamento do boleto, podendo ser:

**“internet”:** Internet Banking

**”phisical_cashier”:** Caixa do Banco (“boca do caixa”)

**”taa”:** Terminal de auto-atendimento

**”eletronic_file”:** CNAB de liquidação

**”call_center”:** Call Center

**”dda”:** DDA (Débito Direto Autorizado)

**”corban”:** Lotérica - Correspondente Bancário
:::

:::caution Atenção
A informação de Método de Pagamento (“***payment_method***“) e Origem do Pagamento (“***payment_origin***“), são dados informados no momento do pagamento do boleto, sua consistência e veracidade fica a cargo da instituição que processou tal pagamento.
:::

## 8 - Movimentações, Comprovantes e Extratos

:::info
Esse manual contém a estrutura/informações dos nossos produtos de Banking as a Service, porém também cabe a utilização como forma documentação de nossos endpoints.
:::

### 8.1. Movimentações
Para toda e qualquer movimentação será enviado um webhook de “***account_transaction***“.

Cada transação possui um tipo de classificação (**Source Sub Type**). Essa classificação é utilizada para categorizar cada movimentação na conta. A lista de Source Sub Types pode ser vista no **Anexo I** deste manual.

Os créditos em conta resultarão em um webhook com “***data.amount***” positivo, “***data.origin***“ sendo a conta de origem dos recursos e a “***data.destination***“ sendo a conta de destino dos recursos:

        **Webhook**

- WEBHOOK_TYPE account_transaction

Response Body: Pix

```json
{
    "key": "\<ACCOUNT-KEY\>",
	"data": {
		"amount": 1000000,
		"origin": {
			"name": "Treasury Account",
			"branch": "0001",
			"document": "32402502000135",
			"account_key": "5d068423-6094-49e4-b15b-7740038295a8",
			"account_digit": "5",
			"account_number": "00002"
		},
		"timestamp": "2022-09-02T21:36:33.446120",
		"description": "329 0001 00002-5 32.402.502/0001-35 - QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"destination": {
			"name": "Default",
			"branch": "0001",
			"document": "09080702000105",
			"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
			"account_digit": "2",
			"account_number": "2359934"
		},
		"reference_key": "983b4a28-7de6-4e71-97ef-60fb50c7b013",
		"reference_type": "movement_request",
		"account_balance": 1000000,
		"source_sub_type": "internal_funds_transfer",
		"transaction_key": "67a62397-2c32-4768-8485-ec9129a46654",
		"source_sub_type_str": "Transferência Interna",
		"transaction_details": {
			"payer_name": "0001",
			"receiver_name": "Default",
			"payer_account_digit": "5",
			"payer_account_branch": "",
			"payer_account_number": "1111111",
			"payer_document_number": "66681638999999",
			"receiver_account_digit": "6",
			"receiver_account_branch": "0000",
			"receiver_account_number": "34256449809",
			"receiver_conciliation_id": null,
			"receiver_document_number": "00809641658"
		}
	},
	"datetime": "2022-09-02T21:36:33.446120",
	"webhook_type": "account_transaction"
}
```

Response Body: Outras transações

```json
{
    "key": "\<ACCOUNT-KEY\>",
	"data": {
		"amount": 1000000,
		"origin": {
			"name": "Treasury Account",
			"branch": "0001",
			"document": "32402502000135",
			"account_key": "5d068423-6094-49e4-b15b-7740038295a8",
			"account_digit": "5",
			"account_number": "00002"
		},
		"timestamp": "2022-09-02T21:36:33.446120",
		"description": "329 0001 00002-5 32.402.502/0001-35 - QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"destination": {
			"name": "Default",
			"branch": "0001",
			"document": "09080702000105",
			"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
			"account_digit": "2",
			"account_number": "2359934"
		},
		"reference_key": "983b4a28-7de6-4e71-97ef-60fb50c7b013",
		"reference_type": "movement_request",
		"account_balance": 1000000,
		"source_sub_type": "internal_funds_transfer",
		"transaction_key": "67a62397-2c32-4768-8485-ec9129a46654",
		"source_sub_type_str": "Transferência Interna",
	},
	"datetime": "2022-09-02T21:36:33.446120",
	"webhook_type": "account_transaction"
}
```

Os débitos em conta resultarão em um webhook com “***data.amount***” negativo, “***data.origin***“ sendo a conta destinatária dos recursos e a “***data.destination***“ sendo a conta de origem dos recursos:

        **Webhook**

- WEBHOOK_TYPE account_transaction

Response Body

```json
{
	"key": "\<ACCOUNT-KEY\>",
	"data": {
		"amount": -45,
		"origin": {
			"name": "PIX",
			"branch": "0001",
			"document": "32402502000135",
			"account_key": "3d0e7d50-e898-49f3-b23b-05353c8a3c72",
			"account_digit": "3",
			"account_number": "00003"
		},
		"timestamp": "2022-09-02T23:00:05.326738",
		"description": "212 0001 1017372-2 ***.221.81*-** BANCO ORIGINAL S.A.",
		"destination": {
			"name": "Default",
			"branch": "0001",
			"document": "09080702000105",
			"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
			"account_digit": "2",
			"account_number": "2359934"
		},
		"reference_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
		"reference_type": "pix_outgoing",
		"account_balance": 999955,
		"source_sub_type": "pix_withdrawal",
		"transaction_key": "d2ba3817-26d7-4957-ab82-24f78d910a8a",
		"source_sub_type_str": "Transferência de PIX"
	},
	"datetime": "2022-09-02T23:00:05.326738",
	"webhook_type": "account_transaction"
}
```
 

**Lista de source_sub_types’s:**

| Enum                                    | Descrição                                       |
|-----------------------------------------|-------------------------------------------------|
| operation_disbursement                  | Desembolso da Operação                          |
| protest_expense                         | Despesas de Protesto                            |
| automatic_integrated_payment            | Pagamento Automático Integrado                  |
| tax                                     | Impostos                                        |
| electronic_funds_fee                    | Tarifa de TED                                   |
| credit_operation_fee                    | Tarifa de Abertura de Crédito                   |
| internal_funds_transfer                 | Transferência Interna                           |
| incoming_funds_transfer                 | Transferência de Entrada                        |
| outgoing_funds_transfer                 | TED                                             |
| deposit                                 | Depósito                                        |
| withdrawal                              | Transferência                                   |
| withdrawal_reversal                     | Estorno de Transferência                        |
| trade_funds_transfer                    | Transferência de Pagamento de Cessão            |
| settlement_funds_transfer               | Transferência para Liquidação                   |
| bank_slip_fee                           | Tarifa de Boleto                                |
| bank_slip_settlement                    | Liquidação de Boleto                            |
| outgoing_funds_transfer_reversal        | Estorno de TED                                  |
| incoming_funds_transfer_refusal         | Transferência Negada                            |
| electronic_funds_fee_reversal           | Estorno de Tarifa de TED                        |
| monthly_account_fee_reversal            | Estorno de Tarifa de Manutenção de Conta        |
| bank_slip_fee_reversal                  | Estorno de Tarifa de Boleto                     |
| correspondent_bank_transfer             | Repasse de Correspondente Bancário              |
| credit_analysis_fee                     | Tarifa de Análise de Crédito                    |
| credit_operation_fee_reversal           | Estorno de Tarifa de Abertura de Crédito        |
| financial_investments_income            | Renda de Aplicação Financeira                   |
| bank_slip_settlement_reversal           | Estorno de Liquidação de Boleto                 |
| bank_slip_settlement_expense_reversal   | Estorno de Tarifa de liquidação de Boleto       |
| bank_slip_settlement_incoming_reversal  | Estorno de Recebimento de Liquidação de Boleto  |
| correspondent_bank_transfer_reversal    | Estrono de Repasse de Correspondente Bancário   |
| credit_analysis_fee_reversal            | Estorno de Tarifa de Análise de Crédito         |
| doc_expense_reversal                    | Estorno de Tarifa de DOC                        |
| incoming_doc_reversal                   | Estorno de Entrada de DOC                       |
| operation_disbursement_reversal         | Estorno de Desembolso da Operação               |
| operation_settling_reversal             | Estorno de Pagamento de Operação                |
| outgoing_doc_reversal                   | Estorno de Saída de DOC                         |
| rebate_reversal                         | Estorno de Rebate                               |
| settlement_funds_transfer_reversal      | Estorno de Transferência para Liquidação        |
| tax_reversal                            | Estorno de Impostos                             |
| trade_funds_transfer_reversal           | Estorno de Transferência de Pagamento de Cessão |
| bank_slip_permanency_fee                | Tarifa de Permanência do Título                 |
| bank_slip_cancel_protest_fee            | Tarifa de Permanência do Título                 |
| bank_slip_protest_fee                   | Tarifa de Pedido de Protesto                    |
| bank_slip_notary_office_fee             | Custas de Protesto                              |
| bank_slip_registration_fee              | Tarifa de Registro                              |
| bank_slip_extension_fee                 | Tarifa de Prorrogação                           |
| bank_slip_rebate_fee                    | Tarifa de Abatimento                            |
| bank_slip_discount_fee                  | Tarifa de Desconto                              |
| bank_slip_settlement_fee                | Tarifa de Liquidação                            |
| bank_slip_write_off_term_fee            | Tarifa de Baixa por Decurso de Prazo            |
| bank_slip_write_off_fee                 | Tarifa de Baixa                                 |
| bank_slip_cancel_protest_write_off_fee  | Tarifa de Sustação de Protesto com Baixa        |
| bank_slip_notary_office_settlement_fee  | Tarifa de Liquidação em Cartório                |
| rebate_tax_free                         | Repasse por Conta e Ordem                       |
| rebate_tax_free_reversal                | Estorno de Repasse por Conta e Ordem            |
| incoming_funds_transfer_reversal        | Estorno de Transferência Interna                |
| bank_slip_payment                       | Pagamento de Boleto                             |
| bank_slip_payment_reversal              | Estorno de Pagamento de Boleto                  |
| warranty_analysis_fee                   | Tarifa de Análise de Garantia                   |
| bank_slip_settlement_deposit            | Liquidação de Boleto                            |
| bank_slip_payment_withdrawal            | Pagamento de Boleto                             |
| account_setup_fee                       | Tarifa de Abertura de Conta                     |
| account_setup_fee_reversal              | Estorno de Tarifa de Abertura de Conta          |
| bank_slip_payment_withdrawal_reversal   | Estorno de Pagamento de Boleto                  |
| incoming_anticipation_of_receivable     | -                                               |
| incoming_credit_card_settlement         | Liquidação de cartão de crédito                 |
| incoming_debit_card_settlement          | Liquidação de cartão de débito                  |
| assignment_automatic_transfer           | Débito de Cessão Automática                     |
| assignment_automatic_transfer_reversal  | Estorno de Débito de Cessão Automática          |
| pix_fee                                 | Tarifa de PIX                                   |
| incoming_pix_transfer                   | Entrada de PIX                                  |
| outgoing_pix_transfer                   | Saída de PIX                                    |
| pix_fee_reversal                        | Estorno de Tarifa de PIX                        |
| incoming_pix_transfer_reversal          | Estorno de entrada de PIX                       |
| outgoing_pix_transfer_reversal          | Estorno de saída de PIX                         |
| pix_deposit                             | Depósito de PIX                                 |
| pix_withdrawal                          | Transferência de PIX                            |
| pix_withdrawal_reversal                 | Estorno de transferência de PIX                 |
| pix_chargeback_withdrawal               | Envio de devolução PIX                          |
| outgoing_pix_chargeback                 | Saída de PIX por devolução                      |
| incoming_pix_chargeback                 | Recebimento de devolução PIX                    |
| pix_chargeback_deposit                  | Entrada de PIX por devolução                    |
| pix_chargeback_withdrawal_reversal      | Estorno de envio de devolução PIX               |
| outgoing_pix_chargeback_reversal        | Estorno de saída de PIX por devolução           |
| incoming_pix_chargeback_reversal        | Estorno de recebimento de devolução PIX         |
| operation_pix_disbursement              | Desembolso PIX da Operação                      |
| operation_pix_disbursement_reversal     | Estorno de Desembolso PIX da Operação           |
| receivables_inquiry_fee                 | Tarifa de Consulta de Agenda de Recebíveis      |
| pix_deposit_reversal                    | Estorno de Depósito de PIX                      |
| internal_pix_transfer                   | Transferência de PIX                            |
| automatic_integrated_payment_reversal   | Estorno de Pagamento Automático Integrado       |
| operation_dibursement_reversal          | Estorno de Desembolso da Operação               |
| available_yield                         | Depósito de Investimento Liquido                |

 

### 8.2. Comprovantes 

O comprovante de uma transferência/pagamento pode ter seus dados recuperados através da “**transaction_key** ”.

        **Request**

- MÉTODO GET
- ENDPOINT /transaction_receipt/TRANSACTION-KEY

        **Response** - Para transferências/pagamentos PIX

Response Body

```json
{
	"chargeback_reason": null,
	"chargeback_returned_amount": null,
	"chargeback_unexpected_reason": null,
	"end_to_end_id": "E3240250220221120012039U3OKZZMW8",
	"origin_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
	"original_transfer_data": null,
	"pix_message": null,
	"pix_transfer_type": "key",
	"receiver_conciliation_id": null,
	"source_account": {
		"account_branch": "0001",
		"account_digit": "2",
		"account_number": "2359934",
		"financial_institution_compe_number": 329,
		"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"owner_document_number": "09080702000105",
		"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
	},
	"source_subtype": "pix_withdrawal",
	"source_subtype_translation_ptbr": "Transferência de PIX",
	"target_account": {
		"account_branch": "0001",
		"account_digit": "2",
		"account_number": "1017372",
		"financial_institution_compe_number": 212,
		"financial_institution_name": "BANCO ORIGINAL S.A.",
		"is_internal": false,
		"ispb_number": "92894922",
		"owner_document_number": "***22181***",
		"owner_name": "Vivo Test",
		"target_pix_key": "65322181032"
	},
	"transacted_at": "2022-11-20 02:00:05",
	"transacted_at_br": "2022-11-19 23:00:05",
	"transaction_amount": 45,
	"transaction_key": "d2ba3817-26d7-4957-ab82-24f78d910a8a",
	"translated_chargeback_reason": null
}
```
 

        **Response** - Para transferências Internas ou Pagamento de TED

Response Body

```json

{
	"origin_key": "983b4a28-7de6-4e71-97ef-60fb50c7b013",
	"source_account": {
		"account_branch": "0001",
		"account_digit": "5",
		"account_number": "00002",
		"financial_institution_compe_number": 329,
		"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"owner_document_number": "32402502000135",
		"owner_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A."
	},
	"source_subtype": "internal_funds_transfer",
	"source_subtype_translation_ptbr": "Transferência Interna",
	"target_account": {
		"account_branch": "0001",
		"account_digit": "2",
		"account_number": "2359934",
		"financial_institution_compe_number": 329,
		"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"owner_document_number": "09080702000105",
		"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
	},
	"transacted_at": "2022-11-20 00:36:33",
	"transacted_at_br": "2022-11-19 21:36:33",
	"transaction_amount": 1000000,
	"transaction_key": "67a62397-2c32-4768-8485-ec9129a46654"
}
```

        **Response** - Para Pagamentos de Boletos

Response Body

```json
{
	"bank_slip": {
		"beneficiary": {
			"document_number": "32402502000135",
			"name": "QI SCD"
		},
		"digitable_line": "32990001031000699926165000000201993810000003500",
		"expiration_date": "2023-06-14",
		"financial_institution_compe_number": "329",
		"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"payer": {
			"document_number": "10932327656",
			"name": "Lucas Clarim"
		},
		"payment_date": "2022-11-22",
		"payment_key": "13b35108-0fdc-44ab-b86d-5dda12dc8dce"
	},
	"origin_key": "13b35108-0fdc-44ab-b86d-5dda12dc8dce",
	"source_account": {
		"account_branch": "0001",
		"account_digit": "2",
		"account_number": "2359934",
		"financial_institution_compe_number": 329,
		"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"owner_document_number": "09080702000105",
		"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
	},
	"source_subtype": "bank_slip_payment",
	"source_subtype_translation_ptbr": "Pagamento de Boleto",
	"transacted_at": "2022-11-22 12:26:21",
	"transacted_at_br": "2022-11-22 09:26:21",
	"transaction_amount": 35,
	"transaction_key": "eee862b9-7f2e-4eea-b04a-fa0e89442618"
}
```
 

### 8.3. Extratos

O extrato de uma conta pode ser recuperado através do seguinte endpoint:

        **Request**

- MÉTODO GET
- ENDPOINT /account_statement
- PARAMETERS account_key, document_number, date_from, date_to, page, page_size

        **Response** 

Response Body

```json
{
	"data": {
		"account_info": {
			"account_block_reason": null,
			"account_branch": "0001",
			"account_credentials": [{
					"account_id": 3395,
					"credential_type": "observer",
					"credential_type_id": 3,
					"document_number": "09080702000105",
					"id": 3244,
					"is_active": true,
					"name": "VOVO LUCIA CONVENIENCIA LTDA",
					"updated_at": null
				},
				{
					"account_id": 3395,
					"credential_type": "requester",
					"credential_type_id": 2,
					"document_number": "94310345000195",
					"id": 3245,
					"is_active": true,
					"name": "Parceiro Sandbox",
					"updated_at": null
				}
			],
			"account_digit": "2",
			"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
			"account_name": "Default",
			"account_number": "2359934",
			"account_status": "opened",
			"account_type": "checking",
			"automatic_transfer_management_status": {
				"created_at": "2022-10-27T13:48:18",
				"enumerator": "master"
			},
			"automatic_transfers": [],
			"balance": 999359,
			"blocked_balance": 0,
			"destinations": [],
			"fee": 0,
			"internal_webhooks": [],
			"investment_available_amount": 0,
			"investment_configuration": null,
			"owner_document_number": "09080702000105",
			"owner_name": "VOVO LUCIA CONVENIENCIA LTDA",
			"owner_person_key": "d2fddd2c-3436-41d5-97e0-5721ee871a3a",
			"permitted_person_keys": [
				"bffded45-5fcf-4d13-9d2a-566a0af338cc",
				"ef48fbe4-267b-45c1-9049-75345c075486"
			],
			"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
			"requester_name": "Parceiro Sandbox",
			"setup_fee": null,
			"transactional_limit": null,
			"webhook_enabled": true
		},
		"transaction_list": [
			{
				"account_balance": 999359,
				"description": "001 0001 81156-1 109.323.276-56 - Lucas de Jesus Clarim",
				"source_subtype": "withdrawal",
				"transacted_at": "2022-11-21 14:39:56",
				"transaction_amount": -551,
				"transaction_key": "32ac0781-f292-4172-b58f-3310102e6fb9"
			},
			{
				"account_balance": 999910,
				"description": "329 0001 00002-5 32.402.502/0001-35 - QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
				"source_subtype": "internal_funds_transfer",
				"transacted_at": "2022-11-20 02:27:38",
				"transaction_amount": -45,
				"transaction_key": "9cee2272-b280-47ed-b9ec-00674f25db1b"
			},
			{
				"account_balance": 999955,
				"description": "212 0001 1017372-2 ***.221.81*-** BANCO ORIGINAL S.A.",
				"source_subtype": "pix_withdrawal",
				"transacted_at": "2022-11-20 02:00:05",
				"transaction_amount": -45,
				"transaction_key": "d2ba3817-26d7-4957-ab82-24f78d910a8a"
			},
			{
				"account_balance": 1000000,
				"description": "329 0001 00002-5 32.402.502/0001-35 - QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
				"source_subtype": "internal_funds_transfer",
				"transacted_at": "2022-11-20 00:36:33",
				"transaction_amount": 1000000,
				"transaction_key": "67a62397-2c32-4768-8485-ec9129a46654"
			}
		]
	},
	"event_datetime": "2022-11-22 12:57:44",
	"key": "d96fb39c-e80b-447b-aad8-191c9bd2eb17",
	"status": "success",
	"webhook_type": "account_statement"
}
```

## 9 - Gestão de Usuários

É possível realizar a inclusão e edição dos usuários administradores de uma conta aberta aberta. As inclusões sempre demanda autenticação de 2 fatores para os usuários que estão sendo adicionados.

### 9.1. Incluíndo um novo usuário a uma conta aberta

#### 9.1.1. Criação

Primeiro é necessário criar o usuário. No momento da criação a QI enviará um token para o usuário criado, por sms ou email.

        **Request**

- MÉTODO POST
- ENDPOINT /baas/token_request

 

Request Body

```json
{
	"contact_type": "sms",
	"agent_document_number": "97564480084",
	"person_creation": {
		"person": {
			"date_of_birth": "1987-01-11",
			"spouse_name": "sample spouse name",
			"birth_place": "sample birth place",
			"phone_number": {
				"country_code": "55",
				"area_code": "88",
				"number": "988887777"
			},
			"representative": null,
			"father_name": "sample father name",
			"address": {
				"street": "Rua Sample Avenue",
				"complement": "Apto 123",
				"state": "MG",
				"number": "1234",
				"neighborhood": "Cabral",
				"postal_code": "38300000",
				"city": "Ituiutaba"
			},
			"nationality": "Brasil",
			"document_identification_number": "890537823",
			"mother_name": "Sample Mama",
			"person_type": "natural",
			"name": "Sample Name Natural",
			"profession": "sample profession",
			"gender": null,
			"email": "sample@gmail.com",
			"document_number": "68346734500",
			"marital_status": null
		}
	}
}
```

A Autenticação de 2 fatores para criação/atualização de novos usuários só pode ser realizada via “sms”.

#### 9.1.2. Confirmação da criação

É necessário informar o token enviado para finalizar a criação do novo usuário:

        **Request**

- MÉTODO POST
- ENDPOINT /baas/movement_validation

Request Body

```json
{
	"token": "456785",
	"person_creation": {
		"person": {
			"date_of_birth": "1987-01-11",
			"spouse_name": "sample spouse name",
			"birth_place": "sample birth place",
			"phone_number": {
				"country_code": "55",
				"area_code": "88",
				"number": "988887777"
			},
			"representative": null,
			"father_name": "sample father name",
			"address": {
				"street": "Rua Sample Avenue",
				"complement": "Apto 123",
				"state": "MG",
				"number": "1234",
				"neighborhood": "Cabral",
				"postal_code": "38300000",
				"city": "Ituiutaba"
			},
			"nationality": "Brasil",
			"document_identification_number": "890537823",
			"mother_name": "Sample Mama",
			"person_type": "natural",
			"name": "Sample Name Natural",
			"profession": "sample profession",
			"gender": null,
			"email": "sample@gmail.com",
			"document_number": "68346734500",
			"marital_status": null
		}
	}
}
```

        **Response**

- MÉTODO POST
- ENDPOINT /baas/movement_validation

Response Body

```json
{
	"hash": "1ab3754bbe74e16c1bebfadd9b8fb9e3",
	"return_response": {
		"birth_place": null,
		"created_at": null,
		"date_of_birth": "1987-01-11T00:00:00",
		"document_identification_number": null,
		"email": "sample@gmail.com",
		"father_name": null,
		"gender": null,
		"is_pep": false,
		"kc_key": null,
		"marital_status": null,
		"mother_name": "Sample Mama",
		"nationality": "Brasil",
		"natural_revenue_range": {
			"average_amount": null,
			"created_at": "2021-03-12T13:26:08",
			"description": "Unavailable",
			"description_ptbr": "Indisponível",
			"enumerator": "0",
			"more_than_amount": null,
			"up_to_amount": null
		},
		"person": {
			"address": {
				"city": "Ituiutaba",
				"complement": "Apto 123",
				"created_at": null,
				"neighborhood": "Cabral",
				"number": "1234",
				"postal_code": "38300000",
				"state": "MG",
				"street": "Rua Sample Avenue"
			},
			"category": null,
			"category_nick": null,
			"created_at": null,
			"document_number": "44236096307",
			"domain": {
				"created_at": "2022-07-14T15:42:45",
				"domain_key": "7aa7e064-f06b-4e09-ae19-7c27694f545b",
				"domain_name": "Koin Soluções Domain Updated",
				"owner_person_key": "997d1b30-e40a-42a0-b87a-4191a5165494"
			},
			"internal_contact": null,
			"internal_contact_person_key": null,
			"name": "Sample Name Natural",
			"person_category": null,
			"person_code": 1564,
			"person_key": "9021859f-9860-41e6-af19-559a2599859c",
			"person_status": {
				"created_at": "2019-02-15T18:28:09",
				"enumerator": "pending",
				"translation_path": "onboarding.PersonStatus.pending"
			},
			"person_type": {
				"created_at": "2019-02-15T18:28:08",
				"enumerator": "natural",
				"translation_path": "onboarding.PersonType.natural"
			},
			"phone": [{
				"area_code": "16",
				"country_code": "55",
				"created_at": null,
				"number": "997239044",
				"phone_key": "b1c3f2d1-2433-4305-9d58-4dd83c30b7aa",
				"phone_type": null
			}],
			"professional_data": [],
			"qualifications": [],
			"registration_date": "2022-08-22",
			"risk": null,
			"special_attention": false,
			"terms_acknowledgement": false,
			"valid_cip_beneficiary": false
		},
		"profession": null,
		"revenue_amount": null,
		"spouse_name": null
	},
	"validation": true
}
```
 

#### 9.1.3. Criar vínculo profissional

Após a criação do usuário, é necessário vinculá-lo a uma empresa titular de uma conta aberta:

        **Request**

- MÉTODO POST
- ENDPOINT /baas/token_request

Request Body

```json
{
	"contact_type": "sms",
	"agent_document_number": "97564480084",
	"professional_data_creation": {
		"natural_person": "3ea7f034-f06b-4e28-ae19-7c23694f546b",
		"legal_person": "8bc83ae4-68e4-7bc9-8c84-077131ba2c93",
		"natural_person_roles": [{
				"product_type": "account",
				"role_type": "requester"
			},
			{
				"product_type": "escrow",
				"role_type": "requester"
			}
		],
		"post_type": "ceo"
	}
}
```
 

#### 9.1.4. Aprovar vínculo profissional

Para aprovar a inclusão do vínculo, é necessário enviar o token recebido pelo usuário administrador.

        **Request**

- MÉTODO POST
- ENDPOINT /baas/movement_validation

        ***Payload*** 

Response Body

```json
{
	"token": "076244",
	"professional_data_creation": {
		"natural_person": "3ea7f034-f06b-4e28-ae19-7c23694f546b",
		"legal_person": "8bc83ae4-68e4-7bc9-8c84-077131ba2c93",
		"natural_person_roles": [{
				"product_type": "account",
				"role_type": "requester"
			},
			{
				"product_type": "escrow",
				"role_type": "requester"
			}
		],
		"post_type": "ceo"
	}
}
```

        **Response**

- MÉTODO POST
- ENDPOINT /baas/movement_validation

        ***Body*** 

Response Body

```json
{
	"hash": "53d62e42d5299fca0d261ff1eae4bffc",
	"return_response": {
		"admission_date": "2022-08-22",
		"created_at": "2022-08-22T21:51:29",
		"email": null,
		"final_beneficiary": null,
		"is_active": true,
		"legal_person_key": "9bc89ea4-64e4-4bd9-8d84-077135ba2c93",
		"natural_person_key": "9021859f-9860-41e6-af19-559a2599859c",
		"natural_person_roles": [{
				"created_at": "2022-08-22T21:51:29",
				"natural_person_roles_events": [],
				"product_type": {
					"created_at": "2021-02-26T14:16:35",
					"enumerator": "account"
				},
				"role_type": {
					"created_at": "2021-02-26T14:14:52",
					"enumerator": "requester"
				},
				"updated_at": "2022-08-22T21:51:29"
			},
			{
				"created_at": "2022-08-22T21:51:29",
				"natural_person_roles_events": [],
				"product_type": {
					"created_at": "2022-04-08T14:51:34",
					"enumerator": "escrow"
				},
				"role_type": {
					"created_at": "2021-02-26T14:14:52",
					"enumerator": "requester"
				},
				"updated_at": "2022-08-22T21:51:29"
			}
		],
		"phone": null,
		"post_type": {
			"created_at": "2019-02-15T18:28:12",
			"enumerator": "ceo",
			"translation_path": "onboarding.PostType.ceo"
		},
		"profession_data_key": "bfe8bc59-533a-4c6a-be3a-af5137794c70",
		"updated_at": "2022-08-22T21:51:29"
	},
	"validation": true
}
```
 

### 9.2. Atualizando Dados de um Usuário Existente

Os dados de um usuário são sempre atualizados no nível do vínculo deste usuário com uma determinada empresa. Sendo assim, para realizar qualquer update, são sempre necessária a chave de identificação do usuário (“***natural_person***“) e a chave do vínculo deste usuário com a empresa (“***professional_data_key***“).

#### 9.2.1. Solicitar alteração

Primeiramente é necessário solicitar a atualização dos dados de um usuário em relação a uma determinada empresa.

        **Request**

- MÉTODO POST
- ENDPOINT /baas/token_request

Response Body

```json
{
	"contact_type": "sms",
	"agent_document_number": "97564480084",
	"professional_data_contact_update": {
		"professional_data_key": "4ba8ff34-e07b-4ea8-ae59-8c23994f546b",
		"natural_person": "3ea7f034-f06b-4e28-ae19-7c23694f546b",
		"email": "sample@gmail.com",
		"phone_number": {
			"country_code": "55",
			"area_code": "888",
			"number": "988887777"
		}
	}
}
```
 

#### 9.2.2. Aprovar solicitação de alteração

Para aprovar a alteração dos dados do usuário, é necessário enviar o token enviado ao usuário alvo da alteração:

        **Request**

- MÉTODO POST
- ENDPOINT /baas/movement_validation

Response Body

```json
{
	"token": "076244",
	"professional_data_contact_update": {
		"professional_data_key": "4ba8ff34-e07b-4ea8-ae59-8c23994f546b",
		"natural_person": "3ea7f034-f06b-4e28-ae19-7c23694f546b",
		"email": "sample@gmail.com",
		"phone_number": {
			"country_code": "55",
			"area_code": "888",
			"number": "988887777"
		}
	}
}
```

        **Response**

- MÉTODO POST
- ENDPOINT /baas/movement_validation

Response Body

```json
{
	"hash": "a355aade311f93ec87637e321f11386d",
	"return_response": {
		"admission_date": "2022-08-22",
		"created_at": "2022-08-22T21:51:29",
		"email": "contacto_info@fakemail.com",
		"final_beneficiary": null,
		"is_active": true,
		"legal_person_key": "9bc89ea4-64e4-4bd9-8d84-077135ba2c93",
		"natural_person_key": "9021859f-9860-41e6-af19-559a2599859c",
		"natural_person_roles": [{
				"created_at": "2022-08-22T21:51:29",
				"natural_person_roles_events": [],
				"product_type": {
					"created_at": "2021-02-26T14:16:35",
					"enumerator": "account"
				},
				"role_type": {
					"created_at": "2021-02-26T14:14:52",
					"enumerator": "requester"
				},
				"updated_at": "2022-08-22T21:51:29"
			},
			{
				"created_at": "2022-08-22T21:51:29",
				"natural_person_roles_events": [],
				"product_type": {
					"created_at": "2022-04-08T14:51:34",
					"enumerator": "escrow"
				},
				"role_type": {
					"created_at": "2021-02-26T14:14:52",
					"enumerator": "requester"
				},
				"updated_at": "2022-08-22T21:51:29"
			}
		],
		"phone": {
			"area_code": "16",
			"country_code": "55",
			"number": "997239044",
			"phone_type": "commercial"
		},
		"post_type": {
			"created_at": "2019-02-15T18:28:12",
			"enumerator": "ceo",
			"translation_path": "onboarding.PostType.ceo"
		},
		"profession_data_key": "bfe8bc59-533a-4c6a-be3a-af5137794c70",
		"updated_at": "2022-08-22T21:51:29"
	},
	"validation": true
}
```

---

# Manual BaaS - Serviço

URL: /documentation/casos_de_uso/manual_baas_servico

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

:::caution Atenção
Antes de iniciar o processo de abertura de conta, é de responsabilidade do parceiro realizar as análises de KYC e Prevenção a Fraude.

Para isso, deve ser utilizado o endpoint de análise descrito em [/onboarding](https://docs.zaig.com.br/onboarding/#introducao). 
:::

### 1 - Criando uma Conta

**1.1. Upload de documentos:** Antes da abertura da conta deve ser realizado o upload dos documentos da empresa. Seguem listas de documentos exigidos para cada tipo de empresa:

Para S.A.'s:

- Estatuto Social.

- Ata de Eleição dos Representantes Legais da empresa.

- Procuração (caso aplicável).

- Documento com foto de cada representante legal ou procurador.

Para os demais casos:

- Contrato social.

- Procuração (caso aplicável).

- Documento com foto de cada representante legal ou procurador.

Os documentos devem ser compactados em um arquivo “.zip” e enviados através do endpoint de [upload de documentos](/documentation/upload_de_documentos/).

        **Response**

ENDPOINT /upload
MÉTODO POST

Response Body

```json
{
    "document_key": "cd639c4a-2279-468a-a047-59865b8159ed",
    "document_md5": "8f5bef84cb07dc047017c0d304dbb6b8",
    "url": "https://storage.googleapis.com/sandbox-doc-api/documents/cd639c4a-2279-468a-a047-59865b8159ed/identificacao_teste.pdf"
}
```

:::info
**IMPORTANTE:** guarde essa “**document_key**”, pois ela será necessária na etapa da criação da conta.
:::
 

**1.2.1. Criação da conta PJ:**

        **Request**

ENDPOINT /account
MÉTODO POST

Request Body

```json

{
	"account_owner": {
		"address": {
			"city": "Limeira",
			"complement": "complemento",
			"neighborhood": "Vila Cidade Jardim",
			"number": "662",
			"postal_code": "13480290",
			"state": "SP",
			"street": "Avenida Campinas"
		},
		"cnae_code": "4721-1/02",
		"company_statute": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
		"company_document_number": "09080702000105",
		"company_type": "ltda",
		"email": "padaria@vovolucia.com.br",
		"foundation_date": "1950-08-21",
		"annual_revenue_amount": "1000000.00",
		"name": "VOVO LUCIA CONVENIENCIA LTDA",
		"person_type": "legal",
		"phone": {
			"area_code": "19",
			"country_code": "055",
			"number": "988888888"
		},
		"trading_name": "Empadaria Vovo Lucia",
		"company_representatives": [{
				"address": {
					"city": "Recife",
					"complement": null,
					"neighborhood": "Fundão",
					"number": "137",
					"postal_code": "52221110",
					"state": "PE",
					"street": "Rua Camapuã"
				},
				"birth_date": "1972-02-02",
				"document_identification_number": "339122924",
				"document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
				"email": "marcos.alves@yopmail.com",
				"individual_document_number": "08531309069",
				"is_pep": false,
				"final_beneficiary": true,
				"marital_status": "single",
				"mother_name": "Sueli Isadora Alves",
				"name": "Marcos Felipe Henrique Alves",
				"nationality": "Brasileira",
				"person_type": "natural",
				"phone": {
					"area_code": "88",
					"country_code": "055",
					"number": "995924634"
				}
			},
			{
				"person_type": "natural",
				"name": "Juliana Tereza Bernardes",
				"mother_name": "Maria Mariane",
				"birth_date": "1990-05-06",
				"profession": "Deputada",
				"nationality": "Brasileira",
				"marital_status": "single",
				"is_pep": false,
				"final_beneficiary": true,
				"individual_document_number": "97564480084",
				"document_identification_number": "232479719",
				"document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
				"email": "juliana.tereza@yopmail.com",
				"phone": {
					"country_code": "055",
					"area_code": "11",
					"number": "912821359"
				},
				"address": {
					"street": "Passagem Mariana",
					"state": "PA",
					"city": "Ananindeua",
					"neighborhood": "Águas Lindas",
					"number": "660",
					"postal_code": "67118003",
					"complement": "complemento"
				}
			}
		]
	}
}
```

“***account_owner***”: Os dados da empresa devem ser enviados neste objeto.

“***account_owner.company_statute***”: A “***document_key***” retornada no endpoint de upload de documentos, no momento do upload do “.zip” dos documentos societários da empresa, deve ser enviada neste campo.

“***account_owner.company_representatives***”: A lista com os dados dos representantes legais da empresa deve ser enviada neste objeto. Deve ser enviado, no mínimo, os representantes legais, suficientes para representar legalmente a empresa conforme seu respectivo estatuto/contrato social. A validação dos poderes de cada representante legal enviado fica a cargo do parceiro.

“***account_owner.company_representatives.document_identification***”: A “***document_key***” retornada no endpoint de upload de documentos, no momento do upload do “.zip” do documento com foto do representante, deve ser enviada neste campo.  

        **Response**

ENDPOINT /account
MÉTODO POST

Response Body

```json
{
	"data": {
		"account_info": {
			"account_branch": "0001",
			"account_digit": "2",
			"account_number": "2359934",
			"financial_institution_code": "329"
		},
		"account_owner": {
			"document_number": "09080702000105",
			"name": "VOVO LUCIA CONVENIENCIA LTDA"
		}
	},
	"event_datetime": "2022-09-02 22:39:10",
	"key": "\<UUID PROPOSAL-KEY\>",
	"status": "pending_kyc_analysis",
	"webhook_type": "account"
}
```

:::info
**IMPORTANTE:** a “***key***” retornada nesta resposta é a **PROPOSAL-KEY** do pedido de abertura da conta. Ela deve ser armazenada para leitura do webhook de abertura da conta.
:::

A resposta da solicitação de abertura de conta sempre retornará o status “***pending_kyc_analysis***”.
Um número de conta será reservado para esse cliente, porém a conta ainda estará pendente de análise de KYC por parte da QI Tech. Neste momento, a conta não estará aberta e não poderá receber ou enviar recursos.

**1.2.2. Criação da conta PF:**

        **Request**

ENDPOINT /account
MÉTODO POST

Request Body

```json
{
	"account_owner": {
		"address": {
			"street": "Avenida Sargento Geraldo Sant'Ana",
			"number": "1100",
			"neighborhood": "Jardim Taquaral",
			"city": "São Paulo",
			"state": "SP",
			"postal_code": "04674225"
		},
		"phone": {
			"country_code": "055",
			"number": "912828135",
			"area_code": "11"
		},
		"email": "juliana.tereza@yopmail.com",
		"name": "Juliana Tereza Bernardes",
		"person_type": "natural",
		"nationality": "Brasil",
		"birth_date": "1993-08-02",
		"mother_name": "Patricia Monica Diaz Bascur Tieppo",
		"is_pep": false,
		"individual_document_number": "97564480084",
		"document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
		"document_identification_type": "cnh",
        "revenue_amount": 1000,
        "profession": "autonomo"
	}
}
```

“***account_owner***”: Os dados da pessoa física titular da conta devem ser enviados neste objeto.

“***account_owner.document_identification***”: A “***document_key***” retornada no endpoint de upload de documentos.

        **1.2.2.1. Forma de envio do documento de identificação:** Na abertura da conta PF, podem ser enviados dois tipos de documento (***document_identification_type***): cnh ou rg.
O documento de identificação pode ser enviado nos formatos “.pdf”, “.png” e “.jpeg”.

           &nbsp**1.2.2.1.1. Envio de documento de identificação do tipo CNH:**

Caso o documento seja enviado em 2 arquivos, sendo que, a frente do documento consta em um arquivo e o verso em outro, os seguintes campos devem ser infomado no objeto ***account_owner*** do endpoint **/account (1.2.2.)**:

"document_identification": "\ ",
"document_identification_back": "\ ",
		"document_identification_type": "cnh",

Caso o documento seja enviado em 1 arquivo, contendo a frente e verso do documento no mesmo arquivo (**foto do documento ou cnh digital**), os seguintes campos devem ser infomado no objeto ***account_owner*** do endpoint ***/account*** (**1.2.2.**):

"document_identification": "\ ",
		"document_identification_type": "cnh",
           &nbsp**1.2.2.1.2. Envio de documento de identificação do tipo RG:** 
Para o tipo de documento RG, sempre devem ser enviados 2 arquivos, um contendo a frente do documento e outro com o verso do documento. Para este caso os seguintes campos devem ser infomados no objeto ***account_owner*** do endpoint ***/account*** (**1.2.2.**):

"document_identification": "\ ",
"document_identification_back": "\ ",
		"document_identification_type": "rg",
 

        **Response**

ENDPOINT /account
MÉTODO POST

Response Body

```json
{
	"data": {
		"account_info": {
			"account_branch": "0001",
			"account_digit": "2",
			"account_number": "2359934",
			"financial_institution_code": "329"
		},
		"account_owner": {
            "document_number": "97564480084",
			"name": "Juliana Tereza Bernardes"
		}
	},
	"event_datetime": "2022-09-02 22:39:10",
	"key": "\<UUID PROPOSAL-KEY\>",
	"status": "pending_kyc_analysis",
	"webhook_type": "account"
}
```

:::info
**IMPORTANTE:** a “**key**” retornada nesta resposta é a **PROPOSAL-KEY** do pedido de abertura da conta. Ela deve ser armazenada para leitura do webhook de abertura da conta.
:::

A resposta da solicitação de abertura de conta sempre retornará o status “***pending_kyc_analysis***”.
Um número de conta será reservado para esse cliente, porém a conta ainda estará pendente de análise de KYC por parte da QI Tech. Neste momento, a conta não estará aberta e não poderá receber ou enviar recursos.

:::info
Para simular situações de aprovação, reprovação e analise manual pode ser utilizado o primeiro digito do CPF/CNPJ do owner da conta:

- 0 à 7 -> Aprovação Automática

- 8 -> Reprovação Automática

- 9 -> Análise Manual
:::

**1.2.3.** Após a conclusão da análise de KYC/PLD pela QI Tech, será enviado um webhook de abertura da conta, conforme abaixo:

        **Webhook**

WEBHOOK_TYPE account
SOURCE_SUB_TYPE Account Opened

Body

```json
{
	"data": {
		"account_info": {
			"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
			"account_digit": "2",
			"account_branch": "0001",
			"account_number": "2359934",
			"financial_institution_code": "329"
		},
		"account_owner": {
			"name": "VOVO LUCIA CONVENIENCIA LTDA",
			"document_number": "09080702000105"
		}
	},
	"event_datetime": "2022-09-02 22:39:39",
	"key": "\<UUID PROPOSAL-KEY\>",
	"status": "account_opened",
	"webhook_type": "account"
}
```

:::info
Neste momento será retornada “***account_key***” da conta e ela estará pronta para utilização.
:::

**1.2.4.** Caso a conta não passe no processo de KYC/PLD, será enviado um webhook de conta rejeitada:

        **Webhook**

WEBHOOK_TYPE available_balance
STATUS Success

Body

```json
{
	"data": {
		"account_info": {
			"account_digit": "2",
			"account_branch": "0001",
			"account_number": "2359934",
			"financial_institution_code": "329"
		},
		"account_owner": {
			"name": "VOVO LUCIA CONVENIENCIA LTDA",
			"document_number": "09080702000105"
		}
	},
	"event_datetime": "2022-09-02 22:39:39",
	"key": "\<UUID PROPOSAL-KEY\>",
	"status": "account_rejected",
	"webhook_type": "account"
}
```

**1.3. Recuperando dados da conta:**

        **Request**

ENDPOINT /account
MÉTODO POST
PARAMETERS account_type[checking], owner_name, account_number, owner_document_number, account_status[opened, closed, blocked], page, page_size

Request Body

```json
{
	"data": [
		{
			"account_block_reason": null,
			"account_branch": "0001",
			"account_credentials": [{
					"account_id": 3395,
					"created_at": "2022-09-02T22:39:39",
					"credential_type": {
						"created_at": "2019-06-18T13:19:30",
						"enumerator": "observer",
						"id": 3,
						"translation_path": "account.CredentialType.observer"
					},
					"credential_type_id": 3,
					"id": 3244,
					"is_active": true,
					"person_key": "bffded45-5fcf-4d13-9d2a-566a0af338cc",
					"updated_at": null
				},
				{
					"account_id": 3395,
					"created_at": "2022-09-02T22:39:39",
					"credential_type": {
						"created_at": "2019-06-18T13:19:30",
						"enumerator": "requester",
						"id": 2,
						"translation_path": "account.CredentialType.requester"
					},
					"credential_type_id": 2,
					"id": 3245,
					"is_active": true,
					"person_key": "ef48fbe4-267b-45c1-9049-75345c075486",
					"updated_at": null
				}
			],
			"account_digit": "2",
			"account_documents": [],
			"account_events": [{
				"account_id": 3395,
				"created_at": "2022-09-02T22:39:39",
				"id": 5132,
				"new_account_status": {
					"created_at": "2019-10-11T18:58:31",
					"enumerator": "opened",
					"id": 1,
					"translation_path": "account.AccountStatus.opened"
				},
				"new_account_status_id": 1,
				"old_account_status": null,
				"old_account_status_id": null
			}],
			"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
			"account_name": "Default",
			"account_number": "2359934",
			"account_status": {
				"created_at": "2019-10-11T18:58:31",
				"enumerator": "opened",
				"translation_path": "account.AccountStatus.opened"
			},
			"account_type": {
				"created_at": "2019-03-15T13:09:15",
				"enumerator": "checking",
				"translation_path": "account.AccountType.checking"
			},
			"automatic_transfer_management_status": {
				"created_at": "2022-10-27T13:48:18",
				"enumerator": "master"
			},
			"automatic_transfers": [],
			"balance": 0,
			"blocked_balance": 0,
			"blocked_balance_events": [],
			"created_at": "2022-09-02T22:39:39",
			"destinations": [],
			"fee": 0,
			"internal_webhooks": [],
			"investment_available_amount": 0,
			"investment_configuration": null,
			"is_system_account": false,
			"owner_document_number": "09080702000105",
			"owner_name": "VOVO LUCIA CONVENIENCIA LTDA",
			"owner_person_key": "bffded45-5fcf-4d13-9d2a-566a0af338cc",
			"permitted_person_keys": [
				"bffded45-5fcf-4d13-9d2a-566a0af338cc",
				"bffded45-5fcf-4d13-9d2a-566a0af338cc",
				"ef48fbe4-267b-45c1-9049-75345c075486"
			],
			"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
			"requester_name": "Requester Name Sandbox",
			"setup_fee": null,
			"transactional_limit": null,
			"webhook_enabled": true
		}, ...
	],
	"pagination": {
		"current_page": 1,
		"next_page": null,
		"rows_per_page": 100,
		"total_pages": 1,
		"total_rows": 8
	}
}
```

:::info
Os campos mais pertinentes da resposta da consulta dos dados da conta são: 
**account_branch**, **account_digit**, **account_key**,**account_number**, **balance**, **owner_document_number**, **owner_name**, **owner_person_key**.
:::

--- 

### 2 - Transferência PIX
**2.1. Realizar Transferência PIX:** para realizar um PIX é necessário realizar três chamadas:

1. Criação do pedido de transferência: **/baas/pix_transfer**

2. Aprovação da transferência: **/baas/pix_transfer_approval**

:::info
Uma transferência PIX pode ser realizada utilizando dois payloads distintos: **chave PIX** ou **dados bancários**.
:::

**2.2. Transferência utilizando uma chave PIX (CPF, CNPJ, E-mail, Celular ou chave aleatória):**

        **Request**

ENDPOINT /baas/pix_transfer
MÉTODO POST

Request Body

```json
{
    "pix_transfer_type": "key",
    "source_account": {
        "account_branch": "0001",
        "account_digit": "2",
        "account_number": "2359934",
        "owner_document_number": "09080702000105"
    },
    "pix_key": "65322181032",
    "transaction_amount": 45,
    "requester_document_identification": "09080702000105"
}
```

:::info
A “***pix_key***” pode ser um **CPF**, **CNPJ**, **E-mail**, **Celular** ou uma **Chave Aleatória** (UUID), seguindo as seguintes formatações:

**CPF:** Número inteiro com 11 dígitos.

**CNPJ:** Número inteiro com 14 dígitos.

**E-mail:** Texto contendo ao menos um “@”.

**Celular:** Texto contendo os seguintes valores: “+55” + “[DDD do celular]“ + “[Número Inteiro do Celular com no mínimo 8 e no máximo 9 dígitos]”. Ex: “+5511987654321“.

**Chave Aleatória:** UUID.
:::

**2.3. Transferência utilizando dados da Conta Bancária (PIX Manual):**

        **Request**

ENDPOINT /baas/pix_transfer
MÉTODO POST

Request Body

```json
{
    "pix_transfer_type": "manual",
    "source_account": {
        "account_branch": "0001",
        "account_digit": "2",
        "account_number": "2359934",
        "owner_document_number": "09080702000105"
    },
    "target_account": {
          "account_branch": "0001",
          "account_digit": "3",
          "account_number": "12345678",
          "owner_document_number": "32402502000135",
          "owner_name": "Qi Tech",
          "account_type": "checking_account",
          "ispb": "32402502"
     },
    "transaction_amount": 45
}
```

Utilizando o PIX Manual é necessário informar o ISPB da instituição destino. Este dado é utilizado, pois existem instituições de pagamento que recebem PIX, porém não possuem código de banco. O ISPB é a base do CNPJ da instituição. Para ter acesso à lista completa de ISPB’s de cada instituição participante do PIX, basta utilizar o endpoint de consulta em nossa documentação: /documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras

 
        **Response**

ENDPOINT /baas/pix_transfer
MÉTODO POST

Response Body

```json
{
	"data": {
		"end_to_end_id": "E3240250220221120012039U3OKZZMW8",
		"fee_amount": 1,
		"pix_message": null,
		"pix_transfer_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
		"source_account": {
			"account_brach": "0001",
			"account_digit": "2",
			"account_number": "2359934",
			"account_type": "checking",
			"owner_document_number": "09080702000105",
			"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
		},
		"target_account": {
			"document_number": "***.221.81*-**",
			"financial_institution": "BANCO ORIGINAL S.A."
		},
		"transaction_amount": 45,
		"transfer_purpose": "transfer"
	},
	"event_datetime": "2022-09-02 22:20:47",
	"operation_key": "86d80cf4-430b-4e16-910a-41798810ddcf",
	"status": "pending_approval"
}
```

:::info
Possíveis status da solicitação de transferência/pagamento via PIX: 

**pending_approval:** transferência pendente de aprovação pelo solicitante

**sent:** transferência enviada
:::

Para aprovar a transferência PIX, é necessário utilizar a “***pix_transfer_key***” retornada na solicitação de transferência (***/baas/pix_transfer***):

        **Request**

ENDPOINT /baas/pix_transfer_approval
MÉTODO POST

Request Body

```json
{
    "pix_transfer_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
    "approver_document_number": "97564480084"
}
```

        **Response**

ENDPOINT /baas/pix_transfer_approval
MÉTODO POST

Response Body

```json
{
	"data": {
		"end_to_end_id": "E3240250220221120012039U3OKZZMW8",
		"fee_amount": 1,
		"pix_message": null,
		"pix_transfer_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
		"source_account": {
			"account_brach": "0001",
			"account_digit": "2",
			"account_number": "2359934",
			"account_type": "checking",
			"owner_document_number": "09080702000105",
			"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
		},
		"target_account": {
			"document_number": "***.221.81*-**",
			"financial_institution": "BANCO ORIGINAL S.A."
		},
		"transaction_amount": 45,
		"transfer_purpose": "transfer"
	},
	"event_datetime": "2022-09-02 22:20:47",
	"operation_key": "86d80cf4-430b-4e16-910a-41798810ddcf",
	"status": "sent"
}
```

STATUS 422

Response Body

```json
{
  "data": "{\"title\": \"Pending Transfer\", \"description\": \"The transaction (<END TO END ID DO PIX>) could not be completed and is pending confirmation.\", \"translation\": \"Não foi possível concluir a transação (<END TO END ID DO PIX>) e ela está pendente de confirmação\", \"code\": \"PXT000072\"}"
}

```

:::danger HTTP Error 422
Caso seja retornado **http error 422**, a solicitação de Pix **não deve ser retentada**. É preciso checar o status da solicitação de transferência Pix através de um GET na rota [/baas/pix/pix_transfer](/documentation/pix/pesquisar_por_transferencia_pix_de_saida).
:::

--- 

### 3 - Movimentações, Comprovantes e Extratos

**3.1. Movimentações:**

Para toda e qualquer movimentação será enviado um webhook de “***account_transaction***“.

Cada transação possui um tipo de classificação (**Source Sub Type**). Essa classificação é utilizada para categorizar cada movimentação na conta. A lista de Source Sub Types pode ser vista no **Anexo I** deste manual.

**3.1.1.** Os créditos em conta resultarão em um webhook com “***data.amount***” positivo, “***data.origin***“ sendo a conta de origem dos recursos e a “***data.destination***“ sendo a conta de destino dos recursos:

        **Webhook**

WEBHOOK_TYPE account_transaction

Body: Pix

```json

{
    "key": "\<ACCOUNT-KEY\>",
	"data": {
		"amount": 1000000,
		"origin": {
			"name": "Treasury Account",
			"branch": "0001",
			"document": "32402502000135",
			"account_key": "5d068423-6094-49e4-b15b-7740038295a8",
			"account_digit": "5",
			"account_number": "00002"
		},
		"timestamp": "2022-09-02T21:36:33.446120",
		"description": "329 0001 00002-5 32.402.502/0001-35 - QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"destination": {
			"name": "Default",
			"branch": "0001",
			"document": "09080702000105",
			"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
			"account_digit": "2",
			"account_number": "2359934"
		},
		"reference_key": "983b4a28-7de6-4e71-97ef-60fb50c7b013",
		"reference_type": "movement_request",
		"account_balance": 1000000,
		"source_sub_type": "internal_funds_transfer",
		"transaction_key": "67a62397-2c32-4768-8485-ec9129a46654",
		"source_sub_type_str": "Transferência Interna",
		"transaction_details": {
			"payer_name": "0001",
			"receiver_name": "Default",
			"payer_account_digit": "5",
			"payer_account_branch": "",
			"payer_account_number": "1111111",
			"payer_document_number": "66681638999999",
			"receiver_account_digit": "6",
			"receiver_account_branch": "0000",
			"receiver_account_number": "34256449809",
			"receiver_conciliation_id": null,
			"receiver_document_number": "00809641658"
		}
	},
	"datetime": "2022-09-02T21:36:33.446120",
	"webhook_type": "account_transaction"
}
```

Body: Outras transações

```json

{
    "key": "\<ACCOUNT-KEY\>",
	"data": {
		"amount": 1000000,
		"origin": {
			"name": "Treasury Account",
			"branch": "0001",
			"document": "32402502000135",
			"account_key": "5d068423-6094-49e4-b15b-7740038295a8",
			"account_digit": "5",
			"account_number": "00002"
		},
		"timestamp": "2022-09-02T21:36:33.446120",
		"description": "329 0001 00002-5 32.402.502/0001-35 - QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"destination": {
			"name": "Default",
			"branch": "0001",
			"document": "09080702000105",
			"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
			"account_digit": "2",
			"account_number": "2359934"
		},
		"reference_key": "983b4a28-7de6-4e71-97ef-60fb50c7b013",
		"reference_type": "movement_request",
		"account_balance": 1000000,
		"source_sub_type": "internal_funds_transfer",
		"transaction_key": "67a62397-2c32-4768-8485-ec9129a46654",
		"source_sub_type_str": "Transferência Interna"
	},
	"datetime": "2022-09-02T21:36:33.446120",
	"webhook_type": "account_transaction"
}
```

**3.1.2.** Os débitos em conta resultarão em um webhook com “data.amount” negativo, “***data.origin***“ sendo a conta destinatária dos recursos e a “***data.destination***“ sendo a conta de origem dos recursos:

        **Webhook**

WEBHOOK_TYPE account_transaction

Body

```json
{
	"key": "\<ACCOUNT-KEY\>",
	"data": {
		"amount": -45,
		"origin": {
			"name": "PIX",
			"branch": "0001",
			"document": "32402502000135",
			"account_key": "3d0e7d50-e898-49f3-b23b-05353c8a3c72",
			"account_digit": "3",
			"account_number": "00003"
		},
		"timestamp": "2022-09-02T23:00:05.326738",
		"description": "212 0001 1017372-2 ***.221.81*-** BANCO ORIGINAL S.A.",
		"destination": {
			"name": "Default",
			"branch": "0001",
			"document": "09080702000105",
			"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
			"account_digit": "2",
			"account_number": "2359934"
		},
		"reference_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
		"reference_type": "pix_outgoing",
		"account_balance": 999955,
		"source_sub_type": "pix_withdrawal",
		"transaction_key": "d2ba3817-26d7-4957-ab82-24f78d910a8a",
		"source_sub_type_str": "Transferência de PIX"
	},
	"datetime": "2022-09-02T23:00:05.326738",
	"webhook_type": "account_transaction"
}
```

**Lista de source_sub_types’s:**

|Enum|Descrição|
|--|--|
|operation_disbursement|		Desembolso da Operação|
|protest_expense|		Despesas de Protesto|
|automatic_integrated_payment|		Pagamento Automático Integrado|
|tax	|	Impostos|
|electronic_funds_fee|		Tarifa de TED|
|credit_operation_fee|		Tarifa de Abertura de Crédito|
|internal_funds_transfer|		Transferência Interna|
|incoming_funds_transfer|		Transferência de Entrada|
|outgoing_funds_transfer|		TED|
|deposit|		Depósito|
|withdrawal	|	Transferência|
|withdrawal_reversal	|	Estorno de Transferência|
|trade_funds_transfer|		Transferência de Pagamento de Cessão|
|settlement_funds_transfer|		Transferência para Liquidação|
|bank_slip_fee	|	Tarifa de Boleto|
|bank_slip_settlement|		Liquidação de Boleto|
|outgoing_funds_transfer_reversal|		Estorno de TED|
|incoming_funds_transfer_refusal	|	Transferência Negada|
|electronic_funds_fee_reversal|	Estorno de Tarifa de TED|
|monthly_account_fee_reversal|	Estorno de Tarifa de Manutenção de Conta|
|bank_slip_fee_reversal	|Estorno de Tarifa de Boleto|
|correspondent_bank_transfer|	Repasse de Correspondente Bancário|
|credit_analysis_fee	|Tarifa de Análise de Crédito|
|credit_operation_fee_reversal|	Estorno de Tarifa de Abertura de Crédito|
|financial_investments_income|	Renda de Aplicação Financeira|
|bank_slip_settlement_reversal|	Estorno de Liquidação de Boleto|
|bank_slip_settlement_expense_reversal|	Estorno de Tarifa de liquidação de Boleto|
|bank_slip_settlement_incoming_reversal|	Estorno de Recebimento de Liquidação de Boleto|
|correspondent_bank_transfer_reversal|	Estrono de Repasse de Correspondente Bancário|
|credit_analysis_fee_reversal|	Estorno de Tarifa de Análise de Crédito|
|doc_expense_reversal|	Estorno de Tarifa de DOC|
|incoming_doc_reversal|	Estorno de Entrada de DOC|
|operation_disbursement_reversal|	Estorno de Desembolso da Operação|
|operation_settling_reversal|	Estorno de Pagamento de Operação|
|outgoing_doc_reversal|	Estorno de Saída de DOC|
|rebate_reversal	|Estorno de Rebate|
|settlement_funds_transfer_reversal|	Estorno de Transferência para Liquidação|
|tax_reversal|	Estorno de Impostos|
|trade_funds_transfer_reversal|	Estorno de Transferência de Pagamento de Cessão|
|bank_slip_permanency_fee	|Tarifa de Permanência do Título|
|bank_slip_cancel_protest_fee	|Tarifa de Permanência do Título|
|bank_slip_protest_fee|	Tarifa de Pedido de Protesto|
|bank_slip_notary_office_fee|	Custas de Protesto|
|bank_slip_registration_fee|	Tarifa de Registro|
|bank_slip_extension_fee|	Tarifa de Prorrogação|
|bank_slip_rebate_fee	|Tarifa de Abatimento|
|bank_slip_discount_fee|	Tarifa de Desconto|
|bank_slip_settlement_fee|	Tarifa de Liquidação|
|bank_slip_write_off_term_fee|	Tarifa de Baixa por Decurso de Prazo|
|bank_slip_write_off_fee	|Tarifa de Baixa|
|bank_slip_cancel_protest_write_off_fee|	Tarifa de Sustação de Protesto com Baixa|
|bank_slip_notary_office_settlement_fee|	Tarifa de Liquidação em Cartório|
|rebate_tax_free	|Repasse por Conta e Ordem|
|rebate_tax_free_reversal|	Estorno de Repasse por Conta e Ordem|
|incoming_funds_transfer_reversal|	Estorno de Transferência Interna|
|bank_slip_payment|	Pagamento de Boleto|
|bank_slip_payment_reversal|	Estorno de Pagamento de Boleto|
|warranty_analysis_fee	|Tarifa de Análise de Garantia|
|bank_slip_settlement_deposit|	Liquidação de Boleto|
|bank_slip_payment_withdrawal	|Pagamento de Boleto|
|account_setup_fee	|Tarifa de Abertura de Conta|
|account_setup_fee_reversal|	Estorno de Tarifa de Abertura de Conta|
|bank_slip_payment_withdrawal_reversal|	Estorno de Pagamento de Boleto|
|incoming_anticipation_of_receivable|	-|
|incoming_credit_card_settlement|	Liquidação de cartão de crédito|
|incoming_debit_card_settlement|	Liquidação de cartão de débito|
|assignment_automatic_transfer	|Débito de Cessão Automática|
|assignment_automatic_transfer_reversal	|Estorno de Débito de Cessão Automática|
|pix_fee|	Tarifa de PIX|
|incoming_pix_transfer|	Entrada de PIX|
|outgoing_pix_transfer|	Saída de PIX|
|pix_fee_reversal|	Estorno de Tarifa de PIX|
|incoming_pix_transfer_reversal|	Estorno de entrada de PIX|
|outgoing_pix_transfer_reversal|	Estorno de saída de PIX|
|pix_deposit|	Depósito de PIX|
|pix_withdrawal|	Transferência de PIX|
|pix_withdrawal_reversal	|Estorno de transferência de PIX|
|pix_chargeback_withdrawal|	Envio de devolução PIX|
|outgoing_pix_chargeback	|Saída de PIX por devolução|
|incoming_pix_chargeback|	Recebimento de devolução PIX|
|pix_chargeback_deposit|	Entrada de PIX por devolução|
|pix_chargeback_withdrawal_reversal	|Estorno de envio de devolução PIX|
|outgoing_pix_chargeback_reversal	|Estorno de saída de PIX por devolução|
|incoming_pix_chargeback_reversal	|Estorno de recebimento de devolução PIX|
|operation_pix_disbursement|	Desembolso PIX da Operação|
|operation_pix_disbursement_reversal|	Estorno de Desembolso PIX da Operação|
|receivables_inquiry_fee	|Tarifa de Consulta de Agenda de Recebíveis|
|pix_deposit_reversal	|Estorno de Depósito de PIX|
|internal_pix_transfer	|Transferência de PIX|
|automatic_integrated_payment_reversal	|Estorno de Pagamento Automático Integrado|
|operation_dibursement_reversal|	Estorno de Desembolso da Operação|
|available_yield|	Depósito de Investimento Liquido|

**3.2. Comprovantes:** O comprovante de uma transferência/pagamento pode ter seus dados recuperados através da “***transaction_key***”.

        **Request**

ENDPOINT /transaction_receipt/[TRANSACTION-KEY]
MÉTODO GET

Response Body - Para transferências/pagamentos PIX

```json

{
	"chargeback_reason": null,
	"chargeback_returned_amount": null,
	"chargeback_unexpected_reason": null,
	"end_to_end_id": "E3240250220221120012039U3OKZZMW8",
	"origin_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
	"original_transfer_data": null,
	"pix_message": null,
	"pix_transfer_type": "key",
	"receiver_conciliation_id": null,
	"source_account": {
		"account_branch": "0001",
		"account_digit": "2",
		"account_number": "2359934",
		"financial_institution_compe_number": 329,
		"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"owner_document_number": "09080702000105",
		"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
	},
	"source_subtype": "pix_withdrawal",
	"source_subtype_translation_ptbr": "Transferência de PIX",
	"target_account": {
		"account_branch": "0001",
		"account_digit": "2",
		"account_number": "1017372",
		"financial_institution_compe_number": 212,
		"financial_institution_name": "BANCO ORIGINAL S.A.",
		"is_internal": false,
		"ispb_number": "92894922",
		"owner_document_number": "***22181***",
		"owner_name": "Vivo Test",
		"target_pix_key": "65322181032"
	},
	"transacted_at": "2022-11-20 02:00:05",
	"transacted_at_br": "2022-11-19 23:00:05",
	"transaction_amount": 45,
	"transaction_key": "d2ba3817-26d7-4957-ab82-24f78d910a8a",
	"translated_chargeback_reason": null
}
```

 
Response Body - Para transferências Internas ou Pagamento de TED

```json
{
	"origin_key": "983b4a28-7de6-4e71-97ef-60fb50c7b013",
	"source_account": {
		"account_branch": "0001",
		"account_digit": "5",
		"account_number": "00002",
		"financial_institution_compe_number": 329,
		"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"owner_document_number": "32402502000135",
		"owner_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A."
	},
	"source_subtype": "internal_funds_transfer",
	"source_subtype_translation_ptbr": "Transferência Interna",
	"target_account": {
		"account_branch": "0001",
		"account_digit": "2",
		"account_number": "2359934",
		"financial_institution_compe_number": 329,
		"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"owner_document_number": "09080702000105",
		"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
	},
	"transacted_at": "2022-11-20 00:36:33",
	"transacted_at_br": "2022-11-19 21:36:33",
	"transaction_amount": 1000000,
	"transaction_key": "67a62397-2c32-4768-8485-ec9129a46654"
}
 ```

Response Body - Para Pagamentos de Boletos

```json

{
	"bank_slip": {
		"beneficiary": {
			"document_number": "32402502000135",
			"name": "QI SCD"
		},
		"digitable_line": "32990001031000699926165000000201993810000003500",
		"expiration_date": "2023-06-14",
		"financial_institution_compe_number": "329",
		"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"payer": {
			"document_number": "10932327656",
			"name": "Lucas Clarim"
		},
		"payment_date": "2022-11-22",
		"payment_key": "13b35108-0fdc-44ab-b86d-5dda12dc8dce"
	},
	"origin_key": "13b35108-0fdc-44ab-b86d-5dda12dc8dce",
	"source_account": {
		"account_branch": "0001",
		"account_digit": "2",
		"account_number": "2359934",
		"financial_institution_compe_number": 329,
		"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"owner_document_number": "09080702000105",
		"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
	},
	"source_subtype": "bank_slip_payment",
	"source_subtype_translation_ptbr": "Pagamento de Boleto",
	"transacted_at": "2022-11-22 12:26:21",
	"transacted_at_br": "2022-11-22 09:26:21",
	"transaction_amount": 35,
	"transaction_key": "eee862b9-7f2e-4eea-b04a-fa0e89442618"
}
 ```

**3.3. Extratos:** O extrato de uma conta pode ser recuperado através do seguinte endpoint:

        **Request**

ENDPOINT /account_statement
MÉTODO GET
PARAMETERS account_key, document_number, date_from, date_to, page, page_size

Response Body

```json
{
	"data": {
		"account_info": {
			"account_block_reason": null,
			"account_branch": "0001",
			"account_credentials": [{
					"account_id": 3395,
					"credential_type": "observer",
					"credential_type_id": 3,
					"document_number": "09080702000105",
					"id": 3244,
					"is_active": true,
					"name": "VOVO LUCIA CONVENIENCIA LTDA",
					"updated_at": null
				},
				{
					"account_id": 3395,
					"credential_type": "requester",
					"credential_type_id": 2,
					"document_number": "94310345000195",
					"id": 3245,
					"is_active": true,
					"name": "Parceiro Sandbox",
					"updated_at": null
				}
			],
			"account_digit": "2",
			"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
			"account_name": "Default",
			"account_number": "2359934",
			"account_status": "opened",
			"account_type": "checking",
			"automatic_transfer_management_status": {
				"created_at": "2022-10-27T13:48:18",
				"enumerator": "master"
			},
			"automatic_transfers": [],
			"balance": 999359,
			"blocked_balance": 0,
			"destinations": [],
			"fee": 0,
			"internal_webhooks": [],
			"investment_available_amount": 0,
			"investment_configuration": null,
			"owner_document_number": "09080702000105",
			"owner_name": "VOVO LUCIA CONVENIENCIA LTDA",
			"owner_person_key": "d2fddd2c-3436-41d5-97e0-5721ee871a3a",
			"permitted_person_keys": [
				"bffded45-5fcf-4d13-9d2a-566a0af338cc",
				"ef48fbe4-267b-45c1-9049-75345c075486"
			],
			"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
			"requester_name": "Parceiro Sandbox",
			"setup_fee": null,
			"transactional_limit": null,
			"webhook_enabled": true
		},
		"transaction_list": [
			{
				"account_balance": 999359,
				"description": "001 0001 81156-1 109.323.276-56 - Lucas de Jesus Clarim",
				"source_subtype": "withdrawal",
				"transacted_at": "2022-11-21 14:39:56",
				"transaction_amount": -551,
				"transaction_key": "32ac0781-f292-4172-b58f-3310102e6fb9"
			},
			{
				"account_balance": 999910,
				"description": "329 0001 00002-5 32.402.502/0001-35 - QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
				"source_subtype": "internal_funds_transfer",
				"transacted_at": "2022-11-20 02:27:38",
				"transaction_amount": -45,
				"transaction_key": "9cee2272-b280-47ed-b9ec-00674f25db1b"
			},
			{
				"account_balance": 999955,
				"description": "212 0001 1017372-2 ***.221.81*-** BANCO ORIGINAL S.A.",
				"source_subtype": "pix_withdrawal",
				"transacted_at": "2022-11-20 02:00:05",
				"transaction_amount": -45,
				"transaction_key": "d2ba3817-26d7-4957-ab82-24f78d910a8a"
			},
			{
				"account_balance": 1000000,
				"description": "329 0001 00002-5 32.402.502/0001-35 - QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
				"source_subtype": "internal_funds_transfer",
				"transacted_at": "2022-11-20 00:36:33",
				"transaction_amount": 1000000,
				"transaction_key": "67a62397-2c32-4768-8485-ec9129a46654"
			}
		]
	},
	"event_datetime": "2022-11-22 12:57:44",
	"key": "d96fb39c-e80b-447b-aad8-191c9bd2eb17",
	"status": "success",
	"webhook_type": "account_statement"
}
```

---

### 4 - Transferência TED
 
:::info
As transferências TED só podem ser realizadas em dias úteis das **7:00** às **17:00**.
:::

**4.1. Realizar Transferência TED:**
Para realizar uma transferência via TED é necessário realizar a seguinte chamada: 

        **Request**

ENDPOINT /wire_transfer
MÉTODO POST

Response Body

```json
{
	"source_account": {
		"account_branch": "0001",
		"account_number": "9477323",
		"account_digit": "0",
		"owner_document_number": "38299588000107"
	},
	"target_account": {
		"financial_institution_code": "341",
		"account_branch": "0001",
		"account_number": "4311337",
		"account_digit": "1",
		"owner_document_number": "21669721019",
		"owner_name": "Nome do Titular da Conta Destino"
	},
	"transaction_amount": 8.86
}
```

        **Response**

ENDPOINT /wire_transfer
MÉTODO POST

Response Body

```json
{
	"data": {
		"source_account": {
			"account_branch": "0001",
			"account_digit": "0",
			"account_number": "9477323",
			"owner_document_number": "38299588000107"
		},
		"target_account": {
			"account_branch": "0001",
			"account_digit": "1",
			"account_number": "4311337",
			"financial_institution_code": "341",
			"owner_document_number": "21669721019",
			"owner_name": "Nome do Titular da Conta Destino"
		},
		"transaction_amount": 8.86,
		"transaction_key": "076b76b9-6177-4cd6-b164-da55df678df6"
	},
	"event_datetime": "2023-02-14 23:05:53",
	"key": "d09c5533-a8d7-4ac2-bd3b-dd4433263d80",
	"status": "success",
	"webhook_type": "wire_transfer"
}
```

O campo de “event_datetime“ esta em formato UTC.

:::info
A “***transaction_key***“ é a chave única de identificação da transferência e poderá ser utilizada posteriormente para solicitação do comprovante de transferência.
:::
 

**4.2. Estorno de uma TED:** Caso a instituição destinatária devolva a TED, será disparado o seguinte webhook:

        **Webhook**

WEBHOOK_TYPE account_transaction
SOURCE_SUB_TYPE withdrawal_reversal

Body

```json
{
	"key": "508ebbba-0b1d-41f6-b9a2-975a4c2e925e",
	"data": {
		"amount": 550,
		"origin": {
			"name": "TED",
			"branch": "0001",
			"document": "32402502000135",
			"account_key": "23a4a2c8-9d82-4ebe-a90d-44fe8d839ec0",
			"account_digit": "7",
			"account_number": "00001"
		},
		"timestamp": "2023-01-05T07:42:26.631137",
		"description": "001 0001 81156-1 32.402.502/0001-35 - QI Tech",
		"destination": {
			"name": "Default",
			"branch": "0001",
			"document": "23426525852",
			"account_key": "508ebbba-0b1d-41f6-b9a2-975a4c2e925e",
			"account_digit": "0",
			"account_number": "7058818"
		},
		"reference_key": "58729e67-f490-4607-aafd-2fc7945d3d77",
		"reference_type": "ted_outgoing",
		"account_balance": 99954.15,
		"source_sub_type": "withdrawal_reversal",
		"transaction_key": "53268774-6891-42a4-a658-42e21cef867c",
		"source_sub_type_str": "Estorno de Transferência"
	},
	"datetime": "2023-01-05T07:42:26.631137",
	"webhook_type": "account_transaction"
}
```

 
---

### 5 - Registrar e Alterar boletos bancários

**5.1. Consulta de Carteiras de Cobrança:**  Para registrar, alterar e pagar boletos, é preciso, primeiramente, possuir o Código da Carteira de Cobrança (Requester Profile Code) vinculada a uma conta. Toda conta já nasce com uma Carteira de Cobrança vinculada. 

O Código da Carteira de Cobrança segue o seguinte padrão:
”No. do banco” + “código da carteira” + “No. agência da conta” + “No. da Conta com 7 caracteres e sem dígito“.

Por padrão, na QI Tech, os números do banco, do código da carteira e agência sempre serão “329”, “09” e “0001”, respectivamente.
ex: “**329-09-0001-2359934**”.

Caso seja necessário recuperar a lista de Códigos de Carteira de Cobrança de cada conta, deve ser utilizado o seguinte endpoint:

        **Request**

ENDPOINT /bank_slip/requester_profiles
MÉTODO GET

Response Body

```json
{
    "requester_profile_codes": [
        "329-09-0001-1467576",
        "329-09-0001-5747500",
        "329-09-0001-2730579",
        "329-09-0001-2359934"
    ]
}
```

 
:::tip Dica
O registro, alteração e baixa de boletos, funciona através da dinâmica de ocorrências. Cada ocorrência é enviada para a QI Tech e encaminhada para a base centralizadora de boletos.
As ocorrências podem ser aceitas ou rejeitadas pelo base centralizadora de boletos.
A resposta a respeito da aceitação ou rejeição das ocorrências é enviada via webhook ao parceiro.
:::
 

**5.2. Registrar Boleto:** Para realizar o registro de um boleto, é necessário enviar uma ocorrência de registro, conforme descrito no endpoint abaixo:

        **Request**

ENDPOINT /multibank_instruction?use_multi_process=true
MÉTODO POST

Request Body

```json
{
    "occurrences": [
        {
            "amount": 800,
            "our_number": 1,
            "automatic_bankruptcy_protest": false,
            "bank_teller_instructions": "Não aceitar após vencimento",
            "days_to_bankruptcy_protest": 0,
            "document_number": "123456/01",
            "expiration": "2022-12-01",
            "fine_percentage": "2",
            "interest_daily_value": "0.34",
            "occurrence_type": "registration",
            "payer_address": "Rua Carlos Sampaio, 123",
            "payer_document": "41184562067",
            "payer_name": "João Ninguem",
            "payer_person_type": "natural",
            "payer_postal_code_root": "15800",
            "payer_postal_code_suffix": "020",
            "registration_institution_enumerator": "qi_scd",
            "requester_profile": 9,
            "requester_profile_code": "329-09-0001-2359934"
        }
    ]
}
```
 

:::info
O nosso número bancário (“***our_number***”) é o ID do boleto dentro da carteira de cobrança. Ele deve ser um ID incremental.
O nosso número bancário (“***our_number***”) deve ser gerado pelo parceiro e informado no momento do registro do boleto.
**IMPORTANTE:** O boleto deve ser localizado através da chave: nosso número bancário (“***our_number***”) + Código da Carteira de Cobrança (“***requester_profile_code***).
:::

        **Response**

ENDPOINT /multibank_instruction?use_multi_process=true
MÉTODO POST

Response Body

```json
{
	"file_info": {
		"beneficiary_code": null,
		"beneficiary_name": null,
		"file_sequence_id": null,
		"file_type_identifier": null,
		"file_type_literal": null,
		"service_code": null,
		"service_literal": null,
		"wrote_at": null
	},
	"occurrence_stats": {
		"bank_slip_edit": 0,
		"bankruptcy_protest_request": 0,
		"cancel_rebate": 0,
		"extension": 0,
		"notary_office_entry": 0,
		"notary_office_exit": 0,
		"notary_office_payment": 0,
		"notification": 0,
		"payment": 0,
		"payment_notice": 0,
		"payment_write_off": 0,
		"protest_cancel_and_write_off_request": 0,
		"protest_cancel_request": 0,
		"protest_remove_request": 0,
		"protest_request": 0,
		"rebate": 0,
		"registration": 1,
		"write_off": 0
	},
	"semantic_errors": []
}
```

**5.3.** A resposta sobre a aceitação ou rejeição do registro do boleto será informada através do seguinte webhook.

        **Webhook**

WEBHOOK_TYPE bank_slip.status_change
STATUS registered

Body

```json
{
	"key": "41927fa9-f9ed-4797-b48a-6ac68e58dc17",
	"data": {
		"expiration": "2022-12-01",
		"our_number": 1,
		"bank_slip_key": "41927fa9-f9ed-4797-b48a-6ac68e58dc17",
		"rebate_amount": 0,
		"occurrence_type": "registration",
		"occurrence_feedback": "confirmed",
		"occurrence_sequence": 0,
		"requester_profile_code": "329-09-0001-2359934",
		"glados_occurrence_reasons": null,
		"cnab_file_occurrence_order": 1,
		"registration_institution_occurrence_date": "2022-11-21"
	},
	"status": "registered",
	"webhook_type": "bank_slip.status_change",
	"event_datetime": "2022-11-22 00:41:32"
}
```

Para vincular o webhook enviado a um boleto, deve-se utilizar o nosso número bancário (“***our_number***”) e o Código da Carteira de Cobrança (“***requester_profile_code***“).

Assim que o registro do boleto é aceito pela base centralizadora, é retornado no webhook a chave UUID do boleto (“***bank_slip_key***“). Guarde essa chave pois através dela será possível recuperar as informações do boleto.

 

**5.4. Alterar Dados do Boleto:** Para alterar os dados de um boleto, é necessário enviar uma ocorrência. Cada possível alteração possui sua ocorrência correspondente. A lista de ocorrências para alteração dos dados de um boleto pode ser verificada em nossa documentação (/documentation/emissao_de_boleto/enviar_instrucao_de_boleto).

 

**5.5. Solicitação de 2ª via de boleto:** Após o registro do boleto, pode ser solicitada a geração de um arquivo “.pdf” do boleto, contendo os dados para pagamento.

        **Request**

ENDPOINT /bank_slip/2-way/[BANKSLIP-KEY]
MÉTODO POST

Request Body

```json

{}

```

Response Body

```json
{
	"bank_slip_file": [{
		"barcode": "32991918600000800000001090000000000123599340",
		"created_at": "2022-11-21T23:29:45",
		"digitable_line": "32990001039000000000101235993407191860000080000",
		"url": "https://storage.googleapis.com/sandbox-bank-slip-api/bank-slip-pdf/41927fa9-f9ed-4797-b48a-6ac68e58dc17_1.pdf"
	}],

}
```

:::info
Serão retornados todos os dados do boleto e o link para download do “.pdf” será informado no objeto “***bank_slip_file.url***“.
:::
 

**5.5. Consultar dados de um Boleto:** Os dados de um boleto podem ser consultados de duas formas diferentes.

        **5.5.1. Consulta através da linha digitável:** A linha digitável de um boleto é uma série numérica que traz em si as informações do boleto. Esta série numérica é digitada pelo usuário pagador do boleto no internet-banking do banco pagador.

:::info
Exemplo de linha digitável: 32990001031000000000902000000204685640000100000
:::

Através da linha digitável, podem ser consultados os dados do boleto:

        **Request**

ENDPOINT /bank_slip/payment
MÉTODO GET
PARAMETERS digitable_line

Response Body

```json
{
	"barcode": "32991918600000800000001090000000000123599340",
	"beneficiary_bank_code": "329",
	"beneficiary_document_number": "09080702000105",
	"beneficiary_legal_name": "VOVO LUCIA CONVENIENCIA LTDA",
	"beneficiary_person_type": "legal",
	"calculated_internally": true,
	"calculation_date": "2022-11-21",
	"calculation_model": 1,
	"digitable_line": "32990001039000000000101235993407191860000080000",
	"discount_amount": "0",
	"expiration_date": "2022-12-01",
	"expired_as_of_payment_date": false,
	"expired_as_of_today": false,
	"factual_expiration_date": "2022-12-01",
	"fine_amount": "0",
	"guarantor_document": null,
	"guarantor_name": null,
	"interest_amount": "0",
	"max_payment_date": "2023-05-30",
	"nominal_amount": "800.00",
	"payer_document_number": "41184562067",
	"payer_legal_name": "Jo_o Ninguem",
	"payer_person_type": "natural",
	"payment_date": "2022-11-21",
	"rebate_amount": "0.0",
	"total_amount": "800.0",
	"valid_payment_amount": true,
	"valid_payment_calculation": true,
	"valid_payment_time_frame": true
}
 ```

        **5.5.2. Consulta através da Chave do Boleto:** Assim que o registro do boleto é aceito pela base centralizadora, é retornado no webhook a chave UUID do boleto (“***bank_slip_key***“). Através dessa chave é possível recuperar as informações do boleto:

        **Request**

ENDPOINT /bank_slip/[BANKSLIP-KEY]
MÉTODO GET

Response Body

```json
{
	"barcode": "32991918600000800000001090000000000123599340",
	"beneficiary_bank_code": "329",
	"beneficiary_document_number": "09080702000105",
	"beneficiary_legal_name": "VOVO LUCIA CONVENIENCIA LTDA",
	"beneficiary_person_type": "legal",
	"calculated_internally": true,
	"calculation_date": "2022-11-21",
	"calculation_model": 1,
	"digitable_line": "32990001039000000000101235993407191860000080000",
	"discount_amount": "0",
	"expiration_date": "2022-12-01",
	"expired_as_of_payment_date": false,
	"expired_as_of_today": false,
	"factual_expiration_date": "2022-12-01",
	"fine_amount": "0",
	"guarantor_document": null,
	"guarantor_name": null,
	"interest_amount": "0",
	"max_payment_date": "2023-05-30",
	"nominal_amount": "800.00",
	"payer_document_number": "41184562067",
	"payer_legal_name": "Jo_o Ninguem",
	"payer_person_type": "natural",
	"payment_date": "2022-11-21",
	"rebate_amount": "0.0",
	"total_amount": "800.0",
	"valid_payment_amount": true,
	"valid_payment_calculation": true,
	"valid_payment_time_frame": true
}
```

**5.6. Notificação de aviso de recebimento de um Boleto:** No momento em que um boleto é pago em outro banco, é enviado um aviso de que este boleto foi pago em tempo real. A Liquidação financeira do pagamento ocorrerá no próximo dia útil.

        **Webhook**

WEBHOOK_TYPE bank_slip.status_change
STATUS payment_notice

Body

```json
{
	"key": "945e191d-1a78-4a28-8669-000b7e4a3522",
	"data": {
		"our_number": 1,
		"paid_amount": 800,
		"payment_bank": 341,
		"bank_slip_key": "41927fa9-f9ed-4797-b48a-6ac68e58dc17",
		"payment_method": 2,
		"payment_origin": 3,
		"occurrence_type": "payment_notice",
		"occurrence_feedback": "confirmed",
		"occurrence_sequence": 0,
		"requester_profile_code": "329-09-0001-2359934",
		"registration_institution": "qi_scd",
		"cnab_file_occurrence_order": 1,
		"registration_institution_occurrence_date": "2022-11-02"
	},
	"status": "payment_notice",
	"webhook_type": "bank_slip.status_change",
	"event_datetime": "2022-11-21 23:02:02"
}
```

:::info
“**payment_method:**“ é o meio de pagamento do boleto, podendo ser:

“**credit_card**”: cartão de crédito 

”**cash**”: dinheiro

”**account_debit**”: débito em conta 

”**check**”: cheque
:::

:::info
payment_origin: é a origem do local do pagamento do boleto, podendo ser:

“**internet**”: Internet Banking

”**phisical_cashier**”: Caixa do Banco (“boca do caixa”)

”**taa**”: Terminal de auto-atendimento

”**eletronic_file**”: CNAB de liquidação

”**call_center**”: Call Center

”**dda**”: DDA (Débito Direto Autorizado)

”**corban**”: Lotérica - Correspondente Bancário
:::

:::caution Atenção
A informação de Método de Pagamento (“***payment_method***“) e Origem do Pagamento (“***payment_origin***“), são dados informados no momento do pagamento do boleto, sua consistência e veracidade fica a cargo da instituição que processou tal pagamento.
:::

--- 

### 6 - Gerar QR Code PIX

**6.1. Gerando QR Code PIX Estático:** O QR Code é criado a partir de uma Chave PIX ativa cadastrada em uma conta. Após a geração do QR Code, serão retornados tanto a URI do PIX Copia e Cola vinculada ao QR Code, como também o base64 da imagem do QR Code (caso solicitado).
A imagem do QR Code pode ser gerada pelo próprio parceiro a partir da URI do PIX Copia e Cola.

Para gerar um QR Code PIX Estático será usada apenas uma requisição:

        **Request**

ENDPOINT /baas/qrcode/static
MÉTODO POST

Request Body

```json
{
    "pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
    "amount": 35.00,
    "receiver_name": "Tywin Lannister",
    "qr_code_format": "both"
}
```

:::info
No campo **qr_code_format** poderá ser informado os valores “**image**”, “**payload**“ e “**both**”.

“**image**”: será retornado o campo com o base64 da imagem do QR Code PIX.

“**payload**”: será retornado o campo com o base64 da URI do PIX Copia e Cola do QR Code PIX.

“**both**”: serão retornados os dois campos.
:::

        **Response**

ENDPOINT /baas/qrcode/static
MÉTODO POST

Response Body

```json
{
    "external_reference_key": null,
    "image": "\<BASE 64 DA IMAGEM DO QR CODE PIX\>",
    "payload": "\<BASE 64 DA URI DO QR CODE PIX\>",
    "revision": null
}
```

**6.2. Gerando QR Code PIX Dinâmico:** Existem dois tipos de QR Code Dinâmico. O QR Code Dinâmico com Pagamento Instantâneo e o QR Code Dinâmico com Vencimento.

        **6.2.1. Gerando QR Code PIX Dinâmico com Vencimento:** É um tipo de QR Code PIX que funciona de forma muito semelhante a um boleto bancário, podendo possuir informação de vencimento, multa, juros por atraso e desconto por pagamento antecipado. Para gerar ester tipo de QR Code PIX é necessário apenas uma requisição no Endpoint “/baas/qrcode/dynamic“.

        **Request**

ENDPOINT /baas/qrcode/dynamic
MÉTODO POST

Request Body

```json
{
	"amount": 100,
	"qr_code_type": "dynamic_term",
	"occurrence_type": "registration",
	"max_payment_days": 180,
	"expiration_date": "2025-09-24",
	"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
	"payer_name": "QI Tech",
	"payer_document_number": "98765432100",
	"payer_person_type": "natural",
	"payer_request": "O que voce achou da experiencia",
	"rebate_amount": 0,
	"interest_amount": 1,
	"fine_amount": 2,
	"discounts": [{
		"limit_date": "2023-02-24",
		"amount": 20,
		"discount_type": "absolute"
	}],
	"additional_data": [{
		"\<tag_name\>": "\<tag_value\>"
	}]
}
```

:::info
**occurrence_type:** neste campo é informada a ação pretendida. Podem ser: registration, edit, write_off 

**registration:** Para criar um novo QR Code

**edit:** Para editar um QR Code já existente (Conforme descrito no item abaixo).

**write_off:** para baixar um QR Code ativo.

**interest_amount:** valor em reais (R$) de juros cobrados por dia de atraso.

**fine_amount:** valor da multa por atraso, em reais (R$).

**discounts:** informação do desconto por pagamento antecipado. Caso não seja aplicável, enviar uma lista vazia ([]). 

**additional_data:** são metatags customizáveis que podem ser apresentadas para o pagador no momento do pagamento. Seguem o seguinte padrão: ”\ ”: “\ “.

**tag_name:** possui uma limitação de 100 caracteres e tag_value possui uma limitação de 320 caracteres.
:::

        **Response**

ENDPOINT /baas/qrcode/dynamic
MÉTODO POST

Response Body

```json
{
	"qr_code_type": "dynamic_term",
	"amount": 100,
	"expiration_seconds": null,
	"max_payment_days": 180,
	"receiver_conciliation_id": "3bd19ada234141bf9f1fc5ce0b216723",
	"payer_name": "QI Tech",
	"payer_document_number": "98765432100",
	"payer_person_type": "natural",
	"payer_request": "O que voce achou da experiencia",
	"pix_message": null,
	"modality_alteration": false,
	"expiration_date": "2025-09-24",
	"rebate_amount": 10,
	"interest_amount": 10,
	"fine_amount": 10,
	"paid_amount": null,
	"discounts": [{
		"discount_type": "absolute",
		"limit_date": "2023-02-24",
		"amount": 20
	}],
	"additional_data": [{
		"\<tag_name\>": "\<tag_value\>"
	}],
	"origin": "system",
	"origin_key": null,
	"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
	"qr_code_key": "3bd19ada-2341-41bf-9f1f-c5ce0b216723",
	"occurrence_type": "registration",
	"end_to_end_id": null,
	"base_64": "\<BASE 64 DA URI DO QR CODE PIX\>",
	"image": "\<BASE 64 DA IMAGEM DO QR CODE PIX\>",
	"source_account_branch": null,
	"source_account_financial_institution": null,
	"source_account_ispb": null,
	"source_account_number": null,
	"source_account_digit": null,
	"qr_code_occurrence_key": "b6777e78-e00c-4e9f-9b44-aa7b551c11e4"
}
```

O campo “base_64“ é a URI do PIX Copia e Cola vinculado a este QR Code PIX Dinâmico.

 

        **6.2.2. Gerando QR Code PIX Dinâmico com Pagamento Instantâneo:** É um tipo de QR Code PIX semelhante ao Estático, porém facilita a conciliação por parte do recebedor do pagamento e pode ter vencimento intradia (podendo durar apenas 5 minutos, por exemplo). 
Para gerar este tipo de QR Code PIX é necessário apenas uma requisição no Endpoint “***/baas/qrcode/dynamic***”. 

        **Request**

ENDPOINT /baas/qrcode/dynamic
MÉTODO POST

Request Body

```json
{
	"amount": 100,
	"occurrence_type": "registration",
	"qr_code_type": "dynamic_instant",
	"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
	"expiration_seconds": 360,
	"payer_name": "QI Tech",
	"payer_document_number": "98765432100",
	"payer_person_type": "natural",
	"payer_request": "Valor referente a compra 1234",
	"additional_data": [{
		"\<tag_name\>": "\<tag_value\>"
	}]
}
```

        **Response**

ENDPOINT /baas/qrcode/dynamic
MÉTODO POST

Response Body

```json
{
	"qr_code_type": "dynamic_instant",
	"amount": 100,
	"expiration_seconds": 360,
	"max_payment_days": null,
	"receiver_conciliation_id": "8e5af204fa5844eca9707c4facc5e5f5",
	"payer_name": "QI Tech",
	"payer_document_number": "98765432100",
	"payer_person_type": "natural",
	"payer_request": "Valor referente a compra 1234",
	"pix_message": null,
	"modality_alteration": false,
	"expiration_date": null,
	"rebate_amount": null,
	"interest_amount": null,
	"fine_amount": null,
	"paid_amount": null,
	"discounts": [],
	"additional_data": [{
		"\<tag_name\>": "\<tag_value\>"
	}],
	"origin": "system",
	"origin_key": null,
	"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
	"qr_code_key": "8e5af204-fa58-44ec-a970-7c4facc5e5f5",
	"occurrence_type": "registration",
	"end_to_end_id": null,
	"base_64": "\<BASE 64 DA URI DO QR CODE PIX\>",
	"image": "\<BASE 64 DA IMAGEM DO QR CODE PIX\>",
	"source_account_branch": null,
	"source_account_financial_institution": null,
	"source_account_ispb": null,
	"source_account_number": null,
	"source_account_digit": null,
	"qr_code_occurrence_key": "838e4bd3-36c9-4aa8-9be8-04079bbe8d1a"
}
 ```

        **6.2.3 Editar dados de QR Code PIX Dinâmico:** Para editar os dados de um QR Code PIX Dinâmico, é necessário informar a “***qr_code_key***“ do QR Code PIX e “***occurrence_type***” igual a “***edit***”. Nesse caso, é preciso reenviar todos os dados novamente.

        **Request**

ENDPOINT /baas/qrcode/dynamic
MÉTODO POST

Request Body

```json
{
    "qr_code_key": "3bd19ada-2341-41bf-9f1f-c5ce0b216723",
	"amount": 200,
	"qr_code_type": "dynamic_term",
	"occurrence_type": "edit",
	"max_payment_days": 180,
	"expiration_date": "2025-09-24",
	"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
	"payer_name": "QI Tech",
	"payer_document_number": "98765432100",
	"payer_person_type": "natural",
	"payer_request": "O que voce achou da experiencia",
	"rebate_amount": 0,
	"interest_amount": 1,
	"fine_amount": 2,
	"discounts": [{
		"limit_date": "2023-02-24",
		"amount": 20,
		"discount_type": "absolute"
	}],
	"additional_data": [{
		"\<tag_name\>": "\<tag_value\>"
	}]
}
 ```

        **Response**

ENDPOINT /baas/qrcode/dynamic
MÉTODO POST

Response Body

```json
{
	"qr_code_type": "dynamic_term",
	"amount": 200,
	"expiration_seconds": null,
	"max_payment_days": 180,
	"receiver_conciliation_id": "3bd19ada234141bf9f1fc5ce0b216723",
	"payer_name": "QI Tech",
	"payer_document_number": "98765432100",
	"payer_person_type": "natural",
	"payer_request": "O que voce achou da experiencia",
	"pix_message": null,
	"modality_alteration": false,
	"expiration_date": "2025-09-24",
	"rebate_amount": 10,
	"interest_amount": 10,
	"fine_amount": 10,
	"paid_amount": null,
	"discounts": [{
		"discount_type": "absolute",
		"limit_date": "2023-02-24",
		"amount": 20
	}],
	"additional_data": [{
		"\<tag_name\>": "\<tag_value\>"
	}],
	"origin": "system",
	"origin_key": null,
	"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
	"qr_code_key": "3bd19ada-2341-41bf-9f1f-c5ce0b216723",
	"occurrence_type": "edit",
	"end_to_end_id": null,
	"base_64": "\<BASE 64 DA URI DO QR CODE PIX\>",
	"image": "\<BASE 64 DA IMAGEM QR CODE PIX\>",
	"source_account_branch": null,
	"source_account_financial_institution": null,
	"source_account_ispb": null,
	"source_account_number": null,
	"source_account_digit": null,
	"qr_code_occurrence_key": "d9c01f70-26bc-429d-afd1-038bd3c235b2"
}
  ```

**6.3. Excluir QR Code PIX Dinâmico:** Para baixar um QR Code PIX Dinâmico, é necessário informar a “***qr_code_key***“ do QR Code PIX e “***occurrence_type***” igual a “***write_off***”.

        **Request**

ENDPOINT /baas/qrcode/dynamic
MÉTODO POST

Request Body

```json

{
    "qr_code_key": "3bd19ada-2341-41bf-9f1f-c5ce0b216723",
    "occurrence_type": "write_off"
}

  ```

        **Response**

ENDPOINT /baas/qrcode/dynamic
MÉTODO POST

Response Body

```json

{
	"qr_code_type": "dynamic_term",
	"amount": null,
	"expiration_seconds": 86400,
	"max_payment_days": null,
	"receiver_conciliation_id": "3bd19ada234141bf9f1fc5ce0b216723",
	"payer_name": null,
	"payer_document_number": null,
	"payer_person_type": "natural",
	"payer_request": null,
	"pix_message": null,
	"modality_alteration": false,
	"expiration_date": null,
	"rebate_amount": null,
	"interest_amount": null,
	"fine_amount": null,
	"paid_amount": null,
	"discounts": [],
	"additional_data": [],
	"origin": "system",
	"origin_key": null,
	"pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
	"qr_code_key": "3bd19ada-2341-41bf-9f1f-c5ce0b216723",
	"occurrence_type": "write_off",
	"end_to_end_id": null,
	"base_64": null,
	"image": null,
	"source_account_branch": null,
	"source_account_financial_institution": null,
	"source_account_ispb": null,
	"source_account_number": null,
	"source_account_digit": null,
	"qr_code_occurrence_key": "46001adf-ffe2-4534-b60e-f6c16b9af56e"
}
 
  ```

**6.4. Decodificando QR Code PIX:** Para decodificar um QR Code seja ele dinâmico ou estático, deve ser usado o seguinte endpoint:

        **Request**

ENDPOINT /baas/pix/qrcode
MÉTODO POST

Request Body

```json

{
    "qr_code_payload": "\<URI DO PIX COPIA E COLA\>"
}

```

:::info
Neste endpoint deve ser informada a URI do Pix Copia e Cola (link do Pix Copia e Cola).
:::

---

### 7 - Gerenciar Chaves PIX

:::info
A “***pix_key***” pode ser um **CPF**, **CNPJ**, **E-mail**, **Celular** ou uma **Chave Aleatória** (UUID), seguindo as seguintes formatações:

**CPF:** Número inteiro com 11 dígitos.

**CNPJ:** Número inteiro com 14 dígitos.

**E-mail:** Texto contendo ao menos um “@”.

**Celular:** Texto contendo os seguintes valores: “+55” + “[DDD do celular]“ + “\ ”. Ex: “+5511987654321“.

**Chave Aleatória:** UUID.
:::
 

        **7.1. Criar Chave PIX CNPJ e Aleatória:** Para criar uma chave PIX CNPJ ou Chave Aleatória, basta acionar o endpoint “***/baas/pix/keys***“, alterando apenas o “***pix_key_type***“ para “**cnpj**”, “**cpf**“ ou “**random_key**”.

        **Request**

ENDPOINT /baas/pix/keys
MÉTODO POST

Request Body

```json

{
    "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
    "pix_key_type": "random_key"
}
```

ou

Request Body

```json
{
    "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
    "pix_key_type": "cnpj",
    "pix_key": "09080702000105"
}
```

ou

**payload.json**

```json

{
    "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
    "pix_key_type": "cpf",
    "pix_key": "03882617038"
}

```

        **Response**

ENDPOINT /baas/pix/keys
MÉTODO POST

Response Body

```json
{
	"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
	"created_at": "2022-09-02T18:20:52",
	"pix_key": {
		"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
		"created_at": "2022-09-02T18:20:51",
		"pix_key": "09080702000105",
		"pix_key_status": "pending_confirmation",
		"pix_key_type": "cnpj",
		"updated_at": "2022-09-02T18:20:51"
	},
	"pix_key_request_key": "d60abf67-ad9c-42ee-9089-d26c8fc855b9",
	"request_data": {
		"account_created_at": "2022-09-02T22:44:36",
		"account_digit": "2",
		"account_number": "2359934",
		"account_type": "checking",
		"branch_number": "0001",
		"key": "09080702000105",
		"owner_document_number": "09080702000105",
		"owner_name": "VOVO LUCIA CONVENIENCIA LTDA",
		"owner_person_type": "legal",
		"trading_name": "VOVO LUCIA"
	},
	"request_failure_reason": null,
	"request_status": "pending",
	"request_type": "inclusion",
	"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
	"updated_at": "2022-09-02T18:20:52"
}
```

:::caution Atenção
No caso da Response de criação de uma Chave PIX **Aleatória**, o campo “***pix_key***“ retornará um valor nulo, já que se trata de um
processo assíncrono onde a chave é gerada pelo Banco Central. Para recuperar o valor da chave aleatória gerada, é necessária realizar uma consulta à lista de chaves cadastradas em uma conta, conforme descrito no item “**Consultar Chaves PIX cadastradas em uma conta**, ou aguardar o webhook de inclusão.“.
:::

:::info
Como se trata de um processo assíncrono para verificar se as chave PIX **CNPJ** ou **CPF** estão ativas, é necessário realizar uma consulta à lista de chaves cadastradas em um conta, conforme descrito no item “**Consultar Chaves PIX cadastradas em uma conta**", ou aguardar o webhook de inclusão.
:::

**Webhook**

- WEBHOOK_TYPE key_inclusion

Response Body

```json
{
	"pix_key": "c232142c-ddbf-41d6-a54f-3b90c28b97dc",
	"account_key": "94945886-7a6f-43e6-a307-e36c959e4903",
	"webhook_type": "key_inclusion",
	"pix_key_status": "active",
	"pix_key_request_key": "e274eb13-40b3-4902-978e-8e5fa267af53",
	"pix_key_request_type": "inclusion",
	"pix_key_request_status": "approved"
}
```

 

**7.2. Criar Chave PIX E-mail e Celular:** Para criar uma chave PIX **E-mail** ou **Celular** deve-se acionar dois endpoints:

1 - Para criação da chave: POST no endpoint “***/baas/pix/keys***“, alterando o campo “***pix_key_type***“ para “**email**” ou “**phone_number**”. Neste momento, será enviado um Token para o E-mail ou Celular informado no campo “pix_key“.

2 - Para aprovação da chave: PATCH no endpoint “**/baas/pix/keys/[pix_key_request_key]**“, informando o Token recebido na etapa anterior.

        **Request**

ENDPOINT /baas/pix/keys
MÉTODO POST

Request Body

```json
{
    "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
    "pix_key_type": "email",
    "pix_key": "vovo.lucia@gmail.com.br"
}
```
ou

Request Body

```json
{
    "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
    "pix_key_type": "phone_number",
    "pix_key": "+5511987654321"
}
```

        **Response**

ENDPOINT /baas/pix/keys
MÉTODO POST

Response Body

```json
{
	"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
	"created_at": "2022-09-02T17:41:55",
	"pix_key": {
		"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
		"created_at": "2022-09-02T17:41:54",
		"pix_key": "pedro.pinho@qitech.com.br",
		"pix_key_status": "pending_confirmation",
		"pix_key_type": "email",
		"updated_at": "2022-09-02T17:41:54"
	},
	"pix_key_request_key": "f6209b7e-82da-44a8-9cfa-6ad0a689adb2",
	"request_data": {
		"account_created_at": "2022-09-02T22:44:36",
		"account_digit": "2",
		"account_number": "2359934",
		"account_type": "checking",
		"branch_number": "0001",
		"key": "pedro.pinho@qitech.com.br",
		"owner_document_number": "09080702000105",
		"owner_name": "VOVO LUCIA CONVENIENCIA LTDA",
		"owner_person_type": "legal",
		"trading_name": "VOVO LUCIA"
	},
	"request_failure_reason": null,
	"request_status": "pending",
	"request_type": "inclusion",
	"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
	"updated_at": "2022-09-02T17:41:55"
}
```

:::info
**IMPORTANTE:** O valor retornado no campo “***pix_key_request_key***“ deve ser utilizado na URL da requisição para aprovação da criação da Chave PIX.
:::

 

**7.3. Aprovação da Chave PIX E-mail ou Celular solicitada:**

        **Request**

ENDPOINT /baas/pix/keys/ PIX_KEY_REQUEST_KEY /twofa_validation
MÉTODO PATCH

Request Body

```json
{
    "verification_code": "756816"
}
```

**7.4. Reenviar o código de verificação:**

        **Request**

- MÉTODO PATCH
- ENDPOINT /baas/pix/keys/ PIX_KEY_REQUEST_KEY /resend_twofa

**payload.json**

```json
{}
```

**7.5. Consultar Chaves PIX cadastradas em uma conta:**

        **Request**

ENDPOINT /baas/pix/keys
MÉTODO GET
PARAMETERS account_key

Response Body

```json
{
  "data": [
    {
      "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
      "created_at": "2022-09-02T17:17:31",
      "pix_key": "0598e5d1-2cfc-4857-abf8-12d495aa0a6d",
      "pix_key_status": "active",
      "pix_key_type": "random_key",
      "updated_at": "2022-09-02T17:17:31"
    },
    {
      "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
      "created_at": "2022-09-02T18:20:51",
      "pix_key": "09080702000105",
      "pix_key_status": "active",
      "pix_key_type": "cnpj",
      "updated_at": "2022-09-02T18:20:51"
    }
  ]
}
```

**7.6. Exclusão de Chaves PIX:**

        **Request**

ENDPOINT /baas/pix/keys
MÉTODO DELETE
PARAMETERS /baas/pix/keys/[PIX-KEY]

Payload: { }

Response Body

```json

Response:

{
	"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
	"created_at": "2022-09-02T20:00:36",
	"pix_key": {
		"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
		"created_at": "2022-09-02T18:20:51",
		"pix_key": "09080702000105",
		"pix_key_status": "inactivated",
		"pix_key_type": "cnpj",
		"updated_at": "2022-09-02T20:00:36"
	},
	"pix_key_request_key": "dced4317-c1e7-4da4-a75a-42f855c7598e",
	"request_data": {},
	"request_failure_reason": null,
	"request_status": "approved",
	"request_type": "deletion",
	"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
	"updated_at": "2022-09-02T20:00:36"
}
```
 

---

### 8 - Pagamento QR Code PIX

**8.1. Pagando um QR Code PIX Estático:**

Para realizar o pagamento de um QR Code PIX Estático, é necessário realizar três chamadas:

Decodificar o QR Code PIX: **/baas/pix/qrcode**

Criação do pedido de transferência: **/baas/pix_transfer**

Aprovação da transferência: **/baas/pix_transfer_approval**

A informação que deve ser utilizada para decodificação do QR Code PIX Estático é a URI do PIX Copia e Cola vinculada ao QR Code.

:::info
**Exemplo de URI PIX Copia e Cola:** 00020126580014br.gov.bcb.pix01360598e5d1-2cfc-4857-abf8-12d495aa0a6d52040000530398654040.225802BR5925VOVO LUCIA CONVENIENCIA L6009sao paulo610912345-78062070503***63043A5A
:::

        **Request**

ENDPOINT /baas/pix/qrcode
MÉTODO POST

Request Body

```json

{
    "qr_code_payload": "\<URI DO PIX COPIA E COLA\>"
}
```

        **Response**

ENDPOINT /baas/pix/qrcode
MÉTODO POST

Response Body

```json
{
	"end_to_end_id": "E3240250220221120030008388062101",
	"qr_code_data": {
		"additional_data": null,
		"amount": 30,
		"ispb_number": "32402502",
		"receiver_conciliation_id": "***",
		"target_account_branch": "0001",
		"target_account_digit": "5",
		"target_account_number": "2",
		"target_account_type": "checking",
		"target_bank_code": 329,
		"target_bank_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"target_document_number": "32402502000135",
		"target_name": "QI SOCIEDADE DE CREDITO DIRETO S.A.",
		"target_person_type": "legal",
		"target_pix_key": "316bd44f-2202-4c33-9dc0-096192acd427"
	},
	"qr_code_key": "1608e022-e42d-49d8-bacf-da5844570635",
	"qr_code_payload": "00020126580014br.gov.bcb.pix0136316bd44f-2202-4c33-9dc0-096192acd427520400005303986540530.005802BR5925QI SOCIEDADE DE CREDITO D6009sao paulo610912345-78062070503***63048698",
	"qr_code_type": "static"
}
```

:::caution Atenção
A requisição para pagar um PIX QR Code Estático é a mesma utilizada na transferência PIX com a as seguintes alterações:

**1 -** Adição de um novo campo “***end_to_end_id***”. Deve ser informado o mesmo valor retornado da decodificação do QR Code Estático;
**2 -** Informar no campo “***transaction_amount***“ o mesmo valor retornado no campo “***qr_code_data.amount***” da decodificação do QR Code Estático;
**3 -** Alterar o campo “***pix_transfer_typ***e” para “static“, para solicitação do pagamento via “/baas/pix_trasnfer”.
:::

:::info
A única diferença desta Response em relação a Response de Aprovação de Transferência PIX, é o valor do campo “***pix_transfer_type***“, que é retornado como sendo “***static***”.
:::
 
**8.2. Pagando um QR Code PIX Dinâmico:**

Para realizar o pagamento de um QR Code PIX Dinâmico, é necessário realizar três chamadas:

Decodificar o QR Code PIX: **/baas/pix/qrcode**

Criação do pedido de transferência: **/baas/pix_transfer**

Aprovação da transferência: **/baas/pix_transfer_approval**

A informação que deve ser utilizada para decodificação do QR Code PIX Dinâmico é a URI do PIX Copia e Cola vinculada ao QR Code.

:::info
A única alteração no “/baas/pix/qrcode“ entre é QR Code PIX Estático e o QR Code PIX Dinâmico, é a resposta do endpoint.
:::

        **Response**

ENDPOINT baas/pix/qrcode
MÉTODO POST

Response Body

```json
{
	"end_to_end_id": "E3240250220221120162904592385040",
	"qr_code_data": {
		"account_type": "checking",
		"additional_data": [],
		"address": "Avenida Brigadeiro Faria Lima",
		"amount": 35,
		"category_code": "0000",
		"city": "Sao Paulo",
		"created_at": "2022-09-01T20:20:11",
		"days_after_due_accepted": 180,
		"discount_amount": null,
		"due_date": "2022-11-30",
		"fee_amount": null,
		"fine_amount": null,
		"ispb_number": "32402502",
		"original_amount": null,
		"payer_document_number": "10932327656",
		"payer_name": "Payer Name",
		"payer_person_type": "natural",
		"postal_code": "01452000",
		"presented_at": "2022-09-01T16:29:04",
		"question_to_payer": "QR Code Payment",
		"receiver_conciliation_id": "a6c3f35b342047e58ac105a0ae0c0c6f",
		"receiver_url": null,
		"reduction_amount": null,
		"reusable_qrcode": "yes",
		"revision": 1,
		"state": "SP",
		"status": "active",
		"target_account_branch": "0001",
		"target_account_digit": "5",
		"target_account_number": "2",
		"target_bank_code": 329,
		"target_bank_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"target_document_number": "32402502000135",
		"target_name": "QI SOCIEDADE DE CREDITO DIRETO S.A.",
		"target_person_type": "legal",
		"target_pix_key": "316bd44f-2202-4c33-9dc0-096192acd427",
		"target_trading_name": null
	},
	"qr_code_key": "a1bcf9be-918d-431e-ae79-a75f78337423",
	"qr_code_payload": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/a6c3f35b-3420-47e5-8ac1-05a0ae0c0c6f5204000053039865802BR5902QI6009Sao Paulo61080145200062070503***6304AFEE",
	"qr_code_type": "dynamic_term"
}

```

:::caution Atenção
A requisição para pagar um PIX QR Code Dinâmico é a mesma utilizada na transferência PIX com a as seguintes alterações:

**1 -** Adição de um novo campo “***end_to_end_id***”. Deve ser informado o mesmo valor retornado da decodificação do QR Code Dinâmico.
**2 -**Informar no campo “***transaction_amount***“ o mesmo valor retornado no campo “qr_code_data.amount” da decodificação do QR Code Dinâmico;
**3 -** Alterar o campo “***pix_transfer_type***” para “***dynamic_term***“, para solicitação do pagamento via “**/baas/pix_transfer**”.
**4 -** Adição de um novo campo “***receiver_conciliation_id***”. Deve ser informado o mesmo valor retornado da decodificação do QR Code Dinâmico.
:::

:::info
A única diferença desta Response em relação a Response de Aprovação de Transferência PIX, é o valor do campo “***pix_transfer_type***“, que é retornado como sendo “***dynamic_term***”.
::::

---

# Ambientes

URL: /documentation/certifiqi/ambientes

Possuímos o ambiente de produção e o de sandbox.

### URL para API e Plataforma
- Sandbox:
    - plataforma:  https://sandbox.certifiqi.com.br/
    - api: [https://api.sandbox.certifiqi.com.br](https://api.sandbox.certifiqi.com.br/)
- Produção:
    - plataforma: https://certifiqi.com.br/
    - api [https://api.certifiqi.com.br](https://api.sandbox.certifiqi.com.br/)

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.  
:::

---

# Arquivos Zip

URL: /documentation/certifiqi/arquivo_zip

Todo evento de assinatura, ao ser concluído, gera pelo menos um arquivo ZIP. Em alguns casos, um mesmo evento pode conter mais de um arquivo ZIP, pois cada arquivo possui o **limite máximo de 500 documentos**. 

Para acessar o ZIP, utilize a consulta por URL disponível no tópico 4.5.  

### Arquivos por Documento Disponíveis no ZIP
- **CAdES**:   
  - **PDF original** com uma **página de assinatura informativa** 
  - Arquivo de assinatura **`.p7s`**.  
- **PAdES**: 
  - **PDF assinado**.

---

# Assinatura Automática

URL: /documentation/certifiqi/assinatura_automatica

## Funcionamento

A assinatura automática é um recurso que visa agilizar e otimizar o processo de assinatura de documentos na certificadora. Com o cadastro prévio do assinante, ao criar um evento, a certificadora identifica e assina o documento de maneira automática, eliminando a necessidade do usuário acessar e executar o processo manualmente.

## Cadastro

Para habilitar a assinatura automática em nossa certificadora, é necessário assinar um termo para a geração dos certificados privados, específicos para assinatura dos documentos da operação. Após assinatura do contrato, vamos realizar a geração dos certificados privados de cada assinante e instalaremos os certificados em nossa certificadora para assinatura automática dos pretendidos documentos.

Para efetuarmos o cadastro e passarmos o termo é necessário enviar um e-mail para certifiqi@qitech.com.br, contendo as seguintes informações:
- Modelo do(s) documento(s) que serão assinados automaticamente
- Nome completo, e-mail, CPF, celular e data de nascimento de todos os assinantes deste(s) referido(s) documento(s), para geração dos certificados privados.

Com isso, nossa equipe técnica poderá finalizar a instalação do certificado privado e fornecer as devidas orientações para a conclusão desse processo.

---

# Criação de Perfil de Acesso

URL: /documentation/certifiqi/cadastro

1. Enviar solicitação de criação de acesso para o e-mail certifiqi@qitech.com.br informando os seguintes dados:
   1. CNPJ da empresa
   2. Nome completo do usuário Master
   3. CPF do usuário Master
   4. E-mail do usuário Master
2. Após a criação do acesso pelo time da QI Tech, o usuário Master receberá um e-mail com um link para acesso a plataforma da Certifiqi para efetuar o cadastro.
3. Ao realizar o primeiro acesso à plataforma, o usuário Master pode convidar os demais usuários para que também tenham acesso à plataforma.

---

# Cancelar um Evento de Assinatura

URL: /documentation/certifiqi/cancelar_batch_group_de_assinatura

Essa requisição efetua o cancelamento de um evento pendente.

## Request

ENDPOINT /batch_group/batch_group_key/cancel_signature
MÉTODO PUT

### Path Params

| Campo | Descrição |
|---|---|
| `batch_group_key` | Chave única de identificação do evento de assinatura. |

Response Body

```json
{
    "batch_group_key": "c0394fb2-34f6-4d70-be70-776022fe15b8",
    "name": "Teste",
    "main_related_party": "ba",
    "number_of_documents": 1,
    "total_value": 0.0,
    "all_files_url": "",
    "send_to_fund_administrator": 0,
    "signature_expiration_date": null,
    "webhook_key": null,
    "client_key": "5aaf98d2-0264-48dd-8167-eab859ce5a75",
    "requester_key": null,
    "signature_status": "pending",
    "internal_status": "pending",
    "attached_document_number": "74766848000162",
    "current_signature_position": "1",
    "control_number": "Control Number",
    "internal_webhook_key": "ac73c564-989d-4c53-932b-d8f96b007584",
    "created_at": "2023-05-15 23:54:35",
    "batch_group_type": "icp_signature",
    "requester_identifier": null,
    "send_emails": false,
    "batches": [
        {
            "document_batch_key": "cd65292e-6748-4c1a-9520-de019f2f341b",
            "name": "Termo de Endosso",
            "document_type": "term_of_endorsement",
            "signature_type": "cades",
            "signature_status": "pending",
            "created_at": "2023-05-15 23:54:35",
            "related_parties": [
                {
                    "related_party_key": "41cf4d2a-fa9a-4cd1-93a0-5a1847b14fb3",
                    "name": "nome da empresa ",
                    "role": "assignor",
                    "signature_status": "pending",
                    "signature_position": "1",
                    "created_at": "2023-05-15 23:54:35",
                    "auto_signature": 0,
                    "signer_groups": [
                        {
                            "id": 38586,
                            "expiration": null,
                            "minimum_required_signers": 1,
                            "signable_limit": null,
                            "signature_status": "pending",
                            "created_at": "2023-05-15 23:54:35",
                            "signers": [
                                {
                                    "id": 65062,
                                    "signer_control_number": "1",
                                    "signature_timestamp": null,
                                    "signature_status": "pending",
                                    "name": "João",
                                    "is_group_mandatory": true,
                                    "email": "teste@qitech.com.br",
                                    "document_number": "85653681067",
                                    "created_at": "2023-05-15 23:54:35"
                                }
                            ]
                        }
                    ]
                }
            ],
            "documents": [
                {
                    "document_key": "19f3c0ib-3926-4274-b2ab-720014b35f53",
                    "control_number": "96a8cd68-76b4-4abf-8180-7d8ebe39567e",
                    "file_size": 1681,
                    "file_url": "https://storage.googleapis.com/certifier-api-storage-sandbox/093f1aef-437e-405b-9ef9-51efd73dbd57/teste_of_original.pdf",
                    "name": "teste_of.pdf",
                    "original_file_url": "https://storage.googleapis.com/certifier-api-storage-sandbox/093f1aef-437e-405b-9ef9-51efd73dbd57/teste_of_original.pdf",
                    "status": "pending",
                    "signed_file_url": null,
                    "created_at": "2023-05-15 23:54:35",
                    "signatures": []
                }
            ]
        }
    ],
    "watcher_clients": []
}
```

---

# Consultar Evento de Assinatura

URL: /documentation/certifiqi/consultar_evento

Essa requisição retorna os dados de um evento de assinatura.

## Request

ENDPOINT /batch_group/batch_group_key
MÉTODO GET

### Path Params

| Campo | Descrição |
|---|---|
| `batch_group_key` | Chave única de identificação do evento de assinatura. |

## Response Body Params

STATUS 200

Response Body

```json
{
    "batch_group_key": "c0394fb2-34f6-4d70-be70-776022fe15b8",
    "name": "Teste",
    "main_related_party": "ba",
    "number_of_documents": 1,
    "total_value": 0.0,
    "all_files_url": "",
    "send_to_fund_administrator": 0,
    "signature_expiration_date": null,
    "webhook_key": "ac73c564-989d-4c53-932b-d8f96b007585",
    "client_key": "5aaf98d2-0264-48dd-8167-eab859ce5a75",
    "requester_key": null,
    "signature_status": "pending",
    "internal_status": "pending",
    "attached_document_number": "74766848000162",
    "current_signature_position": "1",
    "internal_webhook_key": "ac73c564-989d-4c53-932b-d8f96b007584",
    "created_at": "2023-05-15 23:54:35",
    "batch_group_type": "icp_signature",
    "requester_identifier": null,
    "send_emails": false,
    "batches": [
        {
            "document_batch_key": "cd65292e-6748-4c1a-9520-de019f2f341b",
            "name": "Termo de Endosso",
            "document_type": "term_of_endorsement",
            "signature_type": "cades",
            "signature_status": "pending",
            "created_at": "2023-05-15 23:54:35",
            "related_parties": [
                {
                    "related_party_key": "41cf4d2a-fa9a-4cd1-93a0-5a1847b14fb3",
                    "name": "nome da empresa ",
                    "role": "assignor",
                    "signature_status": "pending",
                    "signature_position": "1",
                    "created_at": "2023-05-15 23:54:35",
                    "auto_signature": 0,
                    "notify_to": [],
                    "signer_groups": [
                        {
                            "id": 38586,
                            "expiration": null,
                            "minimum_required_signers": 1,
                            "signable_limit": null,
                            "signature_status": "pending",
                            "created_at": "2023-05-15 23:54:35",
                            "signers": [
                                {
                                    "id": 65062,
                                    "signer_control_number": "1",
                                    "signature_timestamp": null,
                                    "signature_status": "pending",
                                    "name": "João",
                                    "is_group_mandatory": true,
                                    "email": "teste@qitech.com.br",
                                    "document_number": "85653681067",
                                    "created_at": "2023-05-15 23:54:35"
                                }
                            ]
                        }
                    ]
                }
            ],
            "documents": [
                {
                    "document_key": "19f3c0ib-3926-4274-b2ab-720014b35f53",
                    "control_number": "96a8cd68-76b4-4abf-8180-7d8ebe39567e",
                    "file_size": 1681,
                    "file_url": "https://storage.googleapis.com/certifier-api-storage-sandbox/093f1aef-437e-405b-9ef9-51efd73dbd57/teste_of_original.pdf",
                    "name": "teste_of.pdf",
                    "original_file_url": "https://storage.googleapis.com/certifier-api-storage-sandbox/093f1aef-437e-405b-9ef9-51efd73dbd57/teste_of_original.pdf",
                    "status": "pending",
                    "signed_file_url": null,
                    "created_at": "2023-05-15 23:54:35",
                    "signatures": []
                }
            ]
        }
    ],
    "watcher_clients": [],
    "zip_file_keys_list": [
        "a1a8cd68-aab4-csbf-1180-dd8ebe395612",
        "cda8cd68-7331-qebf-1280-fw8ebe395676"
    ]
}

```

| Campo | Tipo | Descrição |
|---|---|---|
| `main_related_party` | string | Nome da parte principal responsável por assinar o evento |
| `name` | string | Nome do evento. |
| `batch_group_key` | string | Chave do evento de assinatura. |
| `signature_status` | string | Status da assinatura. |
| `internal_status` | string | Status geral do evento. |
| `total_value` | string | Valor total dos documentos do evento. |
| `client_key` | string | Chave de identificação do cliente. |
| `send_emails` | booleano | Indica se os e-mails de assinatura devem ser enviados para este evento. |
| `attached_document_number` | string | CNPJ do cedente. |
| `batches` | lista | Lista dos diferentes tipos de documentos e suas respectivas partes relacionadas. |
| `webhook_url` | string | Link para onde será enviado o webhook. |
| `webhook_url_list` | lista | Lista de links para onde será enviado o webhook. |
| `zip_file_keys_list` | lista | Chave de identificação dos arquivos ZIP. |

### Objeto Batches 

| Campo | Tipo | Descrição |
|---|---|---|
| `related_parties` | lista | Lista das partes relacionadas envolvidas na assinatura de uma lista de documentos. |
| `documents` | lista | Lista de documentos. |
| `name` | string | Nome do batch. |
| `signature_type` | enum | Tipo de assinatura. |
| `document_type` | enum | Tipo de documento. |

### Objeto Related Parties

| Campo | Tipo | Descrição |
|---|---|---|
| `role` | enum | Papel desempenhado pelos assinantes. |
| `name` | string | Nome da parte relacionada. |
| `signature_position` | inteiro | Posição de assinatura. |
| `signer_groups` | lista | Lista dos grupos de assinantes. |

### Objeto Signer Groups

| Campo | Tipo |Descrição | 
|---|---| ---|
| `minimum_required_signers` | inteiro |  Número mínimo de assinantes que devem ter assinado para que as assinaturas do grupo sejam consideradas concluídas. |
| `signers` | lista | Lista dos assinantes que compõem o grupo de assinantes.  | 

### Objeto Signer

| Campo | Tipo |Descrição |
|---|---| ---|
| `name` | string |  Nome do assinante. |
| `document_number` | string | CPF do assinante.  | 
| `email` | string | Email do assinante.  | 
| `is_group_mandatory` | booleano | indicar se o assinante é obrigatório assinar para que o grupo de assinantes ao qual pertence seja considerado concluído.  |
|`signer_control_number` | string | Campo livre que pode ser utilizado para fins de controle ou referência externa.  |
|`signature_timestamp` | date | data da assinatura.

### Objeto Documents

| Campo | Tipo | Descrição |
|---|---|---|
| `name` | string | Nome do documento. |
| `control_number` | string | Campo livre que pode ser utilizado para fins de controle ou referência externa. |
| `file_size` | float | Tamanho do documento. |
| `url` | string | URL do documento. |
| `document_key` | string | Chave de identificação do documento. |
| `original_file_url` | string | URL do documento original. |
| `signed_file_url` | string | URL do documento com página de assinatura. |
| `file_url` | string | URL do arquivo de assinatura. |

---

# Consultar URLs dos documentos

URL: /documentation/certifiqi/consultar_url

Para consultar os links de eventos de assinatura já criados é possível pelas requisições abaixo.

# Consulta de URLs do Evento de Assinatura
### Request

ENDPOINT /batch_group/batch_group_key/url
MÉTODO GET

### Path Params

| Campo              | Descrição                                             |
|--------------------|-------------------------------------------------------|
| `batch_group_key`  | Chave única de identificação do evento de assinatura. |

Response Body

```json
{
	"all_files_url": "https://google.com",
	"expiration_datetime": "2024-05-01T01:00:00.000Z"
	"batches":[
		{
			"document_batch_key": "121",
			"documents": [
				{
					"document_key": "222",
					"original_file_url": "https://google2.com",
					"signed_file_url": "https://google3.com",
					"file_url": "https://google4.com"
				}
			]
		}
]
}
```

### Body Params

| Campo                 | Tipo     | Descrição                                                    |  
|-----------------------|----------|--------------------------------------------------------------| 
| `batch_group_key`     | string   | Chave única de identificação do evento de assinatura.        |
| `all_files_url`       | string   | URL do arquivo zip que contém o PDF original e p7s.          |
| `batches`             | string   | Lista de diferentes tipos de documentos.                     |
| `document_batch_key`  | string   | Chave única de identificação do lote de documentos.          |          |
| `documents`           | Array    | Lista de objetos dos documentos.                             |           |
| `document_key`        | string   | Chave única de identificação do documento.                   | 
| `original_file_url`   | string   | URL do documento original.                                   |         |
| `signed_file_url`     | string   | URL do documento com página de assinatura.                   |         |
| `file_url`            | string   | URL do arquivo p7s.                                          |         |
| `expiration_datetime` | string   | Data e hora do momento em que ocorrerá a expiração das urls. |         |

# Consulta de URLs de um Documento
### Request

ENDPOINT /document/document_key/url
MÉTODO GET

### Path Params

| Campo          | Descrição                                  |
|----------------|--------------------------------------------|
| `document_key` | Chave única de identificação do documento  |

Response Body

```json
{
    "document_key": "222",
    "original_file_url": "https://google2.com",
    "signed_file_url": "https://google3.com",
    "file_url": "https://google4.com",
    "expiration_datetime": "2024-05-01T01:00:00.000Z"
}
```

### Body Params

| Campo                 | Tipo     | Descrição                                                    |  
|-----------------------|----------|--------------------------------------------------------------| 
| `document_key`        | string   | Chave única de identificação do documento.                   | 
| `original_file_url`   | string   | URL do documento original.                                   |         |
| `signed_file_url`     | string   | URL do documento com página de assinatura.                   |         |
| `file_url`            | string   | URL do arquivo p7s.                                          |         |
| `expiration_datetime` | string   | Data e hora do momento em que ocorrerá a expiração das urls. |         |

# Consulta de URLs de um Arquivo ZIP
### Request

ENDPOINT /certifier/zip_file/zip_file_key/url
MÉTODO GET

### Path Params

| Campo          | Descrição                                  |
|----------------|--------------------------------------------|
| `zip_file_key` | Chave de identificação do arquivo ZIP.     |

Response Body

```json
{
    "zip_file_key": "222",
    "signed_url": "https://google3.com",
    "expiration_datetime": "2024-05-01T01:00:00.000Z"
}
```

### Body Params

| Campo                 | Tipo     | Descrição                                                    |  
|-----------------------|----------|--------------------------------------------------------------| 
| `zip_file_key`        | string   | Chave de identificação do arquivo ZIP.                       | 
| `expiration_datetime` | date     | Data e hora do momento em que ocorrerá a expiração das urls. |
| `signed_url`          | string   | link do arquivo ZIP.   												  |

---

# Criar Evento de Assinatura

URL: /documentation/certifiqi/criar_batch_group

Este endpoint deve ser utilizado para o envio do evento de assinatura, que inclui os documentos e os respectivos assinantes, agrupados em um objeto denominado **batch_group**.

## Definições

### Request

ENDPOINT /batch_group
MÉTODO POST

Request Body

```json
{
    "main_related_party": "ba",
    "webhook_url": "google.com.br",
    "send_to_fund_administrator": false,
    "is_asynchronous": false,
    "name": "Teste",
    "total_value": 0,
    "webhook_url_list": [
        "https://google.com",
        "https://google2.com"
    ],
    "attached_document_number": "74766848000162",
    "send_emails": false,
    "batches": [{
        "signature_type": "cades",
        "document_type": "term_of_endorsement",
        "name": "Termo de Endosso",
        "related_parties":[
    {
            "name": "nome da empresa ",
            "role": "assignor",
            "signature_position":1,
            "signer_groups": [
                    {
                        "minimum_required_signers": 1,
                        "signers":[
                            {
                                "name": "João",
                                "document_number": "85653681067",
                                "email": "teste@qitech.com.br",
                                "is_group_mandatory": true,
                                "signer_control_number": "1"
                            }
                        ]
                    }
                ]
            }
        ],
        "documents": [{
            "name": "teste_of.pdf",
            "control_number": null,
            "url": "https://storage.googleapis.com/certifier-api-storage-sandbox/093f1aef-437e-405b-9ef9-51efd73dbd57/teste_of_original.pdf",
            "document_key": "19f3c0ib-3926-4274-b2ab-720014b35f53",
            "file_size": 1681
        }]
    }]
}

```

STATUS 200

Response Body

```json

```json
{
    "batch_group_key": "c0394fb2-34f6-4d70-be70-776022fe15b8",
    "name": "Teste",
    "main_related_party": "ba",
    "number_of_documents": 1,
    "total_value": 0.0,
    "all_files_url": "",
    "send_to_fund_administrator": 0,
    "signature_expiration_date": null,
    "webhook_key": "ac73c564-989d-4c53-932b-d8f96b007585",
    "requester_key": null,
    "signature_status": "pending",
    "internal_status": "pending",
    "attached_document_number": "74766848000162",
    "current_signature_position": "1",
    "internal_webhook_key": "ac73c564-989d-4c53-932b-d8f96b007584",
    "created_at": "2023-05-15 23:54:35",
    "batch_group_type": "icp_signature",
    "requester_identifier": null,
    "send_emails": false,
    "is_asynchronous": false,
    "batches": [
        {
            "document_batch_key": "cd65292e-6748-4c1a-9520-de019f2f341b",
            "name": "Termo de Endosso",
            "document_type": "term_of_endorsement",
            "signature_type": "cades",
            "signature_status": "pending",
            "created_at": "2023-05-15 23:54:35",
            "related_parties": [
                {
                    "related_party_key": "41cf4d2a-fa9a-4cd1-93a0-5a1847b14fb3",
                    "name": "nome da empresa ",
                    "role": "assignor",
                    "signature_status": "pending",
                    "signature_position": "1",
                    "created_at": "2023-05-15 23:54:35",
                    "auto_signature": 0,
                    "notify_to": [],
                    "signer_groups": [
                        {
                            "id": 38586,
                            "expiration": null,
                            "minimum_required_signers": 1,
                            "signable_limit": null,
                            "signature_status": "pending",
                            "created_at": "2023-05-15 23:54:35",
                            "signers": [
                                {
                                    "id": 65062,
                                    "signer_control_number": "1",
                                    "signature_timestamp": null,
                                    "signature_status": "pending",
                                    "name": "João",
                                    "is_group_mandatory": true,
                                    "email": "teste@qitech.com.br",
                                    "document_number": "85653681067",
                                    "created_at": "2023-05-15 23:54:35"
                                }
                            ]
                        }
                    ]
                }
            ],
            "documents": [
                {
                    "document_key": "19f3c0ib-3926-4274-b2ab-720014b35f53",
                    "control_number": "96a8cd68-76b4-4abf-8180-7d8ebe39567e",
                    "file_size": 1681,
                    "file_url": "https://storage.googleapis.com/certifier-api-storage-sandbox/093f1aef-437e-405b-9ef9-51efd73dbd57/teste_of_original.pdf",
                    "name": "teste_of.pdf",
                    "original_file_url": "https://storage.googleapis.com/certifier-api-storage-sandbox/093f1aef-437e-405b-9ef9-51efd73dbd57/teste_of_original.pdf",
                    "status": "pending",
                    "signed_file_url": null,
                    "created_at": "2023-05-15 23:54:35",
                    "signatures": []
                }
            ]
        }
    ],
    "watcher_clients": []
}

```
</div>
</details>

## Request Body Params

| Campo | Tipo |Descrição | Obrigatório |
|---|---| ---|  ---| 
| `main_related_party` |  string | Nome da parte principal responsável por assinar o evento. | SIM | 
| `name` | string | Nome do evento de assinatura. | SIM
| `total_value`| string | Valor total dos documentos do evento. | SIM
| `send_emails` |  booleano | Indica se os e-mails de assinatura devem ser enviados para este evento. Caso o valor seja **FALSE**, nenhum e-mail será enviado em nenhuma etapa do processo. | SIM
 `attached_document_number`  | string | CNPJ do cedente, utilizado quando o documento estiver relacionado a um cedente específico. | NÃO
| `batches` | lista | Lista dos diferentes tipos de documentos e suas respectivas partes relacionadas. | SIM
| `webhook_url`  | string | URL para a qual o webhook de notificação será enviado. | NÃO
| `webhook_url_list`  | lista | Lista de URLs para as quais os webhooks de notificação serão enviados. | NÃO
| `is_asynchronous` | booleano   | O evento inclui um documento gerado de forma assíncrona. | NÃO 
| `send_to_fund_administrador` | booleano   | Após a assinatura, o evento deve notificar via SOAP uma administradora que utiliza o software Fromtis. | NÃO

:::info
- Os campos **webhook_url** ou **webhook_url_list** devem ser enviados somente se houver interesse no recebimento de webhooks. Além disso, apenas uma dessas opções deve ser informada por requisição.
- O campo **is_asynchronous** deve ser informado como **True** quando o evento contiver um documento criado de forma assíncrona.
:::

### Objeto Batches 

| Campo | Tipo |Descrição | Obrigatório |
|---|---| ---|  ---|
| `related_parties` | lista | Lista das partes relacionadas envolvidas na assinatura de uma lista de documentos. | SIM
| `documents` | lista |lista de documentos. | SIM
| `name` |  string |Nome do batch. |   SIM
| `signature_type` | enum | Tipo de assinatura. | SIM
| `document_type` | enum |  Tipo de documento. | SIM

<details>
  <summary>Enumeradores para os tipos de assinatura (signature_type)</summary>

**cades**: Cades  
**pades**: Pades  

</details>

<details>
  <summary>Enumeradores para os tipos de documentos (document_type)</summary>

**endorsement**: Endosso  
**other**: Outros  
**contract**: Contrato  
**term_of_assignment**: Termo de cessão  
**term_of_endorsement**: Termo de Endosso  
**promissory_note**: Nota promissória  
**rural_term_of_assignment**: Termo de cessão  
**term_of_fomentation**: Termo de Fomento  
**cpr**: CPR  
**cprf**: CPRF  
**trade_bill**: Duplicata  
**subscription_note**: Boletim de Subscrição  
**adhesion_term**: Termo de Adesão  
**limited_liability_term**: Termo de responsabilidade limitada  
**account_request_document**: Contrato de abertura de conta  
**ccb_post_sac_cdi**: CCB Pós-SAC CDI  
**ccb_post_sac_ipca**: CCB Pós-SAC IPCA  
**ccb_post_sac_igpm**: CCB Pós-SAC IGPM  
**ccb_post_price_cdi**: CCB Pós-Price CDI  
**ccb_post_price_ipca**: CCB Pós-Price IPCA  
**ccb_post_price_igpm**: CCB Pós-Price IGPM  
**ccb_post_price_days_cdi**: CCB Pós-Price Days CDI  
**ccb_post_price_days_ipca**: CCB Pós-Price Days IPCA  
**ccb_post_price__days_igpm**: CCB Pós-Price Days IGPM  
**ncom_pre_sac**: Nota Comercial Pré-Sac  
**ncom_pre_price**: Nota Comercial Pré Price  
**ncom_pre_sac_days**: Nota Comercial Pré-Price Days  
**ncom_post_sac_cdi**: Nota Comercial Pós-SAC CDI  
**ncom_post_sac_ipca**: Nota Comercial Pós-SAC IPCA  
**ncom_post_sac_igpm**: Nota Comercial Pós-SAC IGPM  
**ncom_post_price_cdi**: Nota Comercial Pós-Price CDI  
**ncom_post_price_ipca**: Nota Comercial Pós-Price IPCA  
**ncom_post_price_igpm**: Nota Comercial Pós-Price IGPM  
**ncom_post_price_days_cdi**: Nota Comercial Pós-Price Days CDI  
**ncom_post_price_days_ipca**: Nota Comercial Pós-Price Days IPCA  
**ncom_post_price__days_igpm**: Nota Comercial Pós-Price Days IGPM  
**ccb_cdi_perc**: CCB CDI Perc  
**ccb_cdi_plus**: CCB CDI+  
**ccb_pre_price**: CCB Pré-Price  
**ccb_pre_sac**: CCB (pre-sac)  
**cce_cdi_perc**: CCE CDI Perc  
**cce_cdi_plus**: CCE CDI+  
**cce_pre_price**: CCE Pré-Price  
**cce_pre_sac**: CCE Pré-Sac  
**cce_post_sac_cdi**: CCE Pós-SAC CDI  
**cce_post_sac_ipca**: CCE Pós-SAC IPCA  
**cce_post_sac_igpm**: CCE Pós-SAC IGPM  
**cce_post_price_cdi**: CCE Pós-Price CDI  
**cce_post_price_ipca**: CCE Pós-Price IPCA  
**cce_post_price_igpm**: CCE Pós-Price IGPM  
**cce_post_price_days_cdi**: CCE Pós-Price Days CDI  
**cce_post_price_days_ipca**: CCE Pós-Price Days IPCA  
**cce_post_price_daysigpm**: CCE Pós-Price Days IGPM  
**cci_cdi_perc**: CCI CDI Perc  
**cci_cdi_plus**: CCI CDI+  
**cci_pre_price**: CCI Pré-Price  
**cci_pre_sac**: CCI Pré-Sac  
**cci_post_sac_cdi**: CCI Pós-SAC CDI  
**cci_post_sac_ipca**: CCI Pós-SAC IPCA  
**cci_post_sac_igpm**: CCI Pós-SAC IGPM  
**cci_post_price_cdi**: CCI Pós-Price CDI  
**cci_post_price_ipca**: CCI Pós-Price IPCA  
**cci_post_price_igpm**: CCI Pós-Price IGPM  
**cci_post_price_days_cdi**: CCI Pós-Price Days CDI  
**cci_post_price_days_ipca**: CCI Pós-Price Days IPCA  
**cci_post_price_days_igpm**: CCI Pós-Price Days IGPM  
**nce_cdi_perc**: NCE CDI Perc  
**nce_cdi_plus**: NCE CDI+  
**nce_pre_price**: NCE Pré-Price  
**nce_pre_sac**: NCE Pré-Sac  
**nce_post_sac**: NCE Pós-SAC  
**nce_post_price**: NCE Pós-Price  
**nce_post_price_days**: NCE Pós-Price Days  

</details>

### Objeto Related Parties

| Campo | Tipo |Descrição | Obrigatório |
|---|---| ---|  ---|
| `role` | enum |  Papel desempenhado pelos assinantes. | SIM
| `name` | string | Nome da parte relacionada.  | SIM
| `signature_position` | inteiro | Posição da assinatura, deve ser informada quando houver ordem de assinatura entre as partes relacionadas. A ordem segue uma sequência crescente. | NÃO 
| `signer_groups` | lista | Lista dos grupos de assinantes. | SIM 

<details>
  <summary>Enumeradores que representam os papéis das partes relacionadas (role)</summary>

**assignor**: Cedente  
**manager**: Gestor  
**underwriter**: Subscritor  
**issuer**: Emissor  
**intervening_discharger**: Interveniente Quitante  
**investor**: Cotista  
**debtor**: Devedor  
**secretary**: Secretário  
**intervening_consentor**: Interveniente Anuente  
**surety**: Garantidor
**guarantor**: Fiador  
**fund_representative**: Representante do Fundo  
**company_representative**: Representante da Empresa  
**solidary_debtor**: Devedor Solidário  
**attestant**: Testemunha  
**bestowal**: Outorga Uxória  
**owner**: Titular  
**attorney**: Procurador  
**associate**: Sócio  
**co_issuer**: Co-emissor  
**fiduciary_agent**: Agente Fiduciário  
**guest**: Convidado  
**spouse**: Cônjuge  
**intervening_guarantor**: Interveniente Fiador  
**fiduciary_debtor**: Devedor Fiduciário  
**bonafide_depositary**: Fiel Depositário  
**faithful_depositary**: Fiel Depositário  
**president**: Presidente  
**endorser**: Endossante  
**fund_administrator**: Administrador do Fundo  
**cosigner**: Avalista  
**consulting**: Consultor  
**fund_manager**: Gestor do Fundo  
**director**: Diretor  

</details>

### Objeto Signer Groups

| Campo | Tipo |Descrição | Obrigatório |
|---|---| ---|  ---|
| `minimum_required_signers` | inteiro |  Número mínimo de assinantes que devem ter assinado para que as assinaturas do grupo sejam consideradas concluídas. | SIM
| `signers` | lista | Lista dos assinantes que compõem o grupo de assinantes.  | SIM

### Objeto Signer

| Campo | Tipo |Descrição | Obrigatório |
|---|---| ---|  ---|
| `name` | string |  Nome do assinante. | SIM
| `document_number` | string | CPF do assinante.  | SIM
| `email` | string | Email do assinante.  | SIM|
| `is_group_mandatory` | booleano | Informe **TRUE** para indicar que o assinante é obrigatório assinar para que o grupo de assinantes ao qual pertence seja considerado concluído.  | SIM
|`signer_control_number` | string | Campo livre que pode ser utilizado para fins de controle ou referência externa.  | SIM

### Objeto Documents

:::info Importante
O campo documents deve ser populado com a resposta da requisição /document.
:::

| Campo | Tipo |Descrição | Obrigatório |
|---|---| ---|  ---|
| `name` | string | Nome do documento. | SIM
| `control_number` | string | Campo livre que pode ser utilizado para fins de controle ou referência externa. Na integração com o Fromtis envolvendo duplicatas, o valor deste campo deve ser mantido igual ao recebido no endpoint de geração de documentos de forma assíncrona.| SIM
| `file_size` | float |Tamanho do documento. |SIM
| `url` | string  |URL do documento. |SIM
| `document_key` | string |Chave de identificação do documento.| SIM

## Response Body Params

| Campo | Tipo |Descrição |
|---|---| ---|
| `batch_group_key` |  string | Chave de identificação do evento de assinatura.
| `signature_status` | string | Status da assinatura. 
| `internal_status`| string | Status geral do evento.                                           
| `original_file_url`   | string   | URL do documento original.                                   
| `signed_file_url`     | string   | URL do documento com página de assinatura.                   
| `file_url`            | string   | URL do arquivo de assinatura.
| `signature_timestamp` | date   | Data da assinatura.
| `webhook_key` | string   | Chave de identificação do webhook.

---

# Criar Evento de Assinatura para Notificar o Fromtis

URL: /documentation/certifiqi/criar_batch_group_fromtis

A Certifiqi oferece a opção de enviar notificações via SOAP para administradoras que utilizam o software Fromtis. Para que a notificação seja realizada corretamente, é necessário seguir alguns passos específicos. Caso algum desses passos não seja cumprido, os eventos de assinatura ficarão pendentes de notificação, pois não foi possível encontrar uma cessão passada pelo Fromtis.

A notificação da assinatura será enviada após a conclusão da assinatura de todos os documentos necessários.

## Evento com Duplicatas

1. Envio dos documentos
   1. Enviar o CNAB das duplicatas de forma assíncrona conforme o tópico 4.2.3.
   2. Enviar em PDF o termo de cessão
2. Criação do evento
    1. Enviar no body o campo is_asynchronous como True
    2. Enviar no body o campo send_to_fund_administrator como True
    3. Enviar no body o campo total_value com o valor liquido da cessão
    4. Enviar no body o document type correspondente a duplicata e seus documentos
    5. Enviar no body o document type correspondente ao termo de cessão e seu respectivo documento

## Evento com Outros Tipos de Ativos

1. Envio dos documentos
   1. Enviar em PDF o termo de cessão
2. Criação do evento
    1. Enviar no body o campo send_to_fund_administrator como True
    2. Enviar no body o campo total_value com o valor liquido da cessão
    3. Enviar no body o document type correspondente ao termo de cessão e seu respectivo documento

---

# Enviar para Assinatura

URL: /documentation/certifiqi/enviar_para_assinatura

## Request

Essa requisição envia um e-mail para os assinantes. O destinatário deve ser informado na criação do evento de assinatura.

ENDPOINT /batch_group/batch_group_key/send_to_signature
MÉTODO PUT

### Path params

| Campo | Tipo | Descrição |
|---|---|---|
| `batch_group_key`|  string | Chave única de identificação do evento de assinatura. |

Response Body

```json
{}

```

---

# Estrutura

URL: /documentation/certifiqi/estrutura

A Certifiqi possui eventos de assinatura (batch_group) que engloba diferentes documentos e seus assinantes. Abaixo será apresentado algumas nomenclaturas importantes para o entendimento do funcionamento da plataforma.

### Related Party

Representa uma pessoa física ou jurídica (empresa) associada à assinatura de documentos. Pode incluir um ou mais grupos de assinantes.

### Signer Group

Grupo de assinantes que compõem uma parte relacionada. Caso qualquer um dos grupos configurados seja satisfeito (número mínimo de assinaturas ou valor representado), a parte relacionada será considerada como assinada. Permite flexibilidade na configuração de regras de assinatura para empresas.

### Signer

Um assinante pertencente a um grupo. É possível definir se sua assinatura é obrigatória dentro do grupo para que a condição do grupo seja atendida.

### Document

Documento que deverá ser assinado.

### Document Batch	

Conjunto de documentos de um determinado tipo que deve ser assinado por uma ou mais partes relacionadas. Um evento de assinatura pode conter múltiplos batches, representando diferentes categorias de documentos.

### Batch Group	

Evento de assinatura que agrupa diversos lotes (Document Batch) de documentos a serem assinados.

## Diagrama da estrutura

## Exemplo de Uso

### Diagrama

O evento de assinatura contém dois elementos do tipo Document Batch: um para Duplicatas e outro para o Termo de Cessão.

### Document Batch – Duplicata

- Contém dois documentos: Duplicata 1 e Duplicata 2.

- Está associado a uma Related Party, que representa o Cedente.

- Essa Related Party possui dois Signer Groups:

    - Signer Group 1: composto por dois assinantes (Signer 1 e Signer 2).

    - Signer Group 2: composto por um assinante (Signer 3).

Para que a Related Party seja considerada como tendo assinado, basta que um dos Signer Groups seja satisfeito. Isso pode ocorrer de duas formas:

    - Opção 1: Signer 1 e Signer 2 realizam a assinatura, satisfazendo o Signer Group 1.

    - Opção 2: Apenas o Signer 3 assina, satisfazendo o Signer Group 2.

Uma vez que a Related Party é satisfeita por qualquer uma dessas opções, o Document Batch de Duplicatas será considerado como assinado.

### Document Batch – Termo de Cessão

- Contém um documento: Termo de cessão.
- Possui duas Related Party:
    - Cedente
    - Administrador do fundo
- Cada Related Party possui um grupo de assinante
- A Related Party da consultoria possui um Signer Group com dois assinantes, assim é necessário que os assinantes assinem para concluir a parte relacionada da consultoria.
- A Related Party do administrador do fundo possui um Signer Group com um assinante, assim é necessário que o assinante assine para concluir a parte relacionada da administradora do fundo.

Uma vez que as Related Partys são satisfeitas, o Document Batch de Termo de Cessão será considerado como assinado.

---

# Forma de Autenticação

URL: /documentation/certifiqi/forma_de_autenticacao

Para realizar uma requisição em nossa plataforma, é necessário incluir a chave de API no header da solicitação, utilizando o campo x-api-token , conforme o exemplo abaixo:

Header

```json

{"x-api-token": "\<EXAMPLE-OF-API-KEY\>"}

```

Essa chave é exclusiva para cada cliente e pode ser solicitada por e-mail, enviando sua solicitação para certifiqi@qitech.com.br.

---

# Início

URL: /documentation/certifiqi/inicio

A plataforma Certifiqi tem como objetivo efetuar assinaturas através de certificados dentro do padrão ICP-Brasil. Além disso, as assinaturas são feitas em poucos segundos para um alto volume de documentos.
Para mais informações acesse:

https://qitech.com.br

# Métodos de Assinatura

### Cades
- Forma de assinatura digital em que o arquivo da assinatura fica em um arquivo separado. 
- Arquivo no formato p7s.

### Pades
- Forma de assinatura digital em que a assinatura fica contida dentro do próprio PDF.
- Arquivo no formato PDF.

---

# Permissão do usuário

URL: /documentation/certifiqi/permissoes

Os usuários na plataforma são divididos em três categorias de acesso, sendo master, assinante e observador.

### Master: 
- Consegue editar e criar eventos.
- Visualiza todos os documentos.
- Pode alterar as permissões dos usuários.

### Assinante: 
- Consegue assinar documentos na plataforma.
- Visualiza os documentos que estiver como assinante.

### Observador
- Consegue visualizar os documentos na plataforma.

---

# Upload de Documentos em CNAB

URL: /documentation/certifiqi/upload_documentos_cnab_assincrono

#  Utilização
Esse método é utilizado para converter cada linha de um CNAB 444 em um arquivo PDF de forma assíncrona. 

O evento pode ser criado antes de finalizar a criação dos documentos.

:::warning Aviso Importante!
O campo `is_asynchronous` deve ser passado como TRUE na criação do evento. Os documentos estarão disponíveis para assinar depois de finalizar a geração dos documentos
:::

## Request

ENDPOINT /certifier/document/trade_bill/asynchronous
MÉTODO POST

### Request Body Params

Deverão ser enviados os seguintes dados, como form-data , no body da request:

| Campo | Tipo | Descrição                              | Obrigatório |
|---|---|----------------------------------------|---|
| `file` | file | Binário com o documento a ser enviado. | SIM |
|`assignor_address`| string | Endereço do cedente                    | SIM |
|`assignor_address_number`| string | Número do endereço do cedente          | SIM |
|`assignor_city`| string | Cidade dp cedente                      | SIM |
|`assignor_state`| string | Estado do cedente                      | SIM |
|`assignor_CEP`| string | CEP do cedente                         | SIM |
|`assignor_neighborhood `|string | Bairro do cedente                           | SIM |

### Response

STATUS 200

Response Body

```json
[
    {
        "control_number": "1123",
        "document_key": "d559e3dc-d19c-494e-b02e-b7199e5325ea",
        "file_size": 1679,
        "name": "trade_bill_1.pdf",
        "url": "https://storage.googleapis.com/certifier-api-storage-sandbox/d559e3dc-d19c-494e-b02e-b7199e5325ea/teste_of_original.pdf"
    },
    {
        "control_number": "1123",
        "document_key": "d559e3dc-d19c-494e-b02e-b7199e5325ea",
        "file_size": 1679,
        "name": "trade_bill_2.pdf",
        "url": "https://storage.googleapis.com/certifier-api-storage-sandbox/d559e3dc-d19c-494e-b02e-b7199e5325ea/teste_of_original.pdf"
    },
    {
        "control_number": "1123",
        "document_key": "d559e3dc-d19c-494e-b02e-b7199e5325ea",
        "file_size": 1679,
        "name": "trade_bill_3.pdf",
        "url": "https://storage.googleapis.com/certifier-api-storage-sandbox/d559e3dc-d19c-494e-b02e-b7199e5325ea/teste_of_original.pdf"
    }
]

```

STATUS 400

Response Body

```json
{
    "title": "Bad Request",
    "description": "Document size larger than 20 MB"
}
```

## Request de Exemplo
```shell
curl --location 'https://api.sandbox.certifiqi.com.br/document' \
--header 'x-api-token: chave de api' \
--form 'file=@"/seu_cnab.txt"' \
--form 'assignor_address="Rua"' \
--form 'assignor_address_number="1111"' \
--form 'assignor_city="São Paulo"' \
--form 'assignor_state="São Paulo"' \
--form 'assignor_CEP="123456789113"' \
--form 'assignor_neighborhood="Teste"'
```

---

# Upload de Documentos em PDF

URL: /documentation/certifiqi/upload_documentos_pdf

#  Utilização
Esse método deve ser utilizado para enviar os documentos no formato PDF.

## Request

ENDPOINT /document
MÉTODO POST

### Request Body Params

Deverão ser enviados os seguintes dados, como form-data , no body da request:

| Campo | Tipo | Descrição | Obrigatório| 
|---|---|---|---|
| `file` | file | Binário com o documento a ser enviado. | SIM |
| `control_number` | string | Campo livre que pode ser utilizado para fins de controle ou referência externa.  | NÃO |
|`endorsement_page` | booleano |  Caso seja passado como true será adicionado uma Página de Endosso  | NÃO |
|`endorser_name` | string |  Nome do Endossatário na página de endosso  | NÃO |
|`endorser_document_number` | string |  Número do documento do endossatário  na página de endosso  | NÃO |
|`receiver_name`| string |   Nome do recebedor   na página de endosso| NÃO |
|`receiver_document_number`| string |  Número do documento do recebedor  na página de endosso   | NÃO |
| `document_identifier` |string | Identificador do documento na página de endosso | NÃO |     
| `document_type` |string | Tipo do documento na página de endosso | NÃO |     

## Response

STATUS 200

Response Body

```json
[
    {
        "control_number": "1123",
        "document_key": "d559e3dc-d19c-494e-b02e-b7199e5325ea",
        "file_size": 1679,
        "name": "document.pdf",
        "url": "https://storage.googleapis.com/certifier-api-storage-sandbox/d559e3dc-d19c-494e-b02e-b7199e5325ea/teste_of_original.pdf"
    },
]

```

STATUS 400

Response Body

```json
{
    "title": "Bad Request",
    "description": "Document size larger than 20 MB"
}
```

Response Body

```json
{
    "title": "Bad Request",
    "description": "PDF has editable format fields"
}
```

Response Body

```json
{
    "title": "Bad Request",
    "description": "PDF file can't have a password."
}
```

## Request de Exemplo
```shell
curl --location 'https://api.certifiqi.com.br/document' \
--header 'x-api-token: chave de api' \
--form 'file=@"/seu_arquivo.pdf"' \
--form 'endorsement_page="true"' \
--form 'endorser_name="Endorser"' \
--form 'endorser_document_number="123456789112"' \
--form 'receiver_name="Receiver"' \
--form 'receiver_document_number="123456789113"' \
--form 'document_type="Termo de Cessão"' \
--form 'document_identifier="1234"' \
--form 'control_number="999"'
```

## Adição da Página de Endosso

Para adicionar uma página de endosso em preto ao final do PDF enviado, os seguintes campos devem ser informados:

- endorsement_page como True
- endorser_name
- endorser_document_number
- receiver_name
- receiver_document_number
- document_identifier
- document_type

Tendo esses campos enviados, o texto adicionado do endosso seguirá o seguinte formato: 

A instituição endorser_name , inscrita no CNPJ sob o nº endorser_document_number ,
endossa este(a) document_type de nº document_identifier para o(a)
receiver_name , inscrito no CNPJ
sob o nº receiver_document_number , nos termos da legislação aplicável, em especial do
parágrafo 1º do artigo 29 da Lei nº 10.931, de 02 de agosto de 2004, com o objetivo de transferir a propriedade plena para
a instituição ora indicada. O presente endosso é realizado em formato eletrônico, sendo que as
partes, desde já, concordam e reconhecem a validade de sua assinatura eletrônica, nos termos do
parágrafo 2º do artigo 10, da Medida Provisória nº 2.200, de 24 de agosto de 2001, ou norma que
venha a substituí-la.

---

# Webhook

URL: /documentation/certifiqi/webhook

Todas as notificações do evento de assinatura serão enviadas para o endereço registrado na criação do evento. Em todas as chamadas de webhook, o payload conterá os dados de batch_group, batches, related_parties, signer_groups e signer.

A notificação será enviada sempre que ocorrer a conclusão de uma das seguintes etapas: partes relacionadas, inicio da criação dos arquivos ZIP ou finalização do evento de assinatura.

## Notificação da Parte Relacionada Assinada

Nesse caso, o campo **signature_status** da parte relacionada, do grupo de assinantes e dos assinantes estarão com o valor **signed**. Já o campo **internal_status** estará com o valor **pending**.

### Exemplos de Webhook

Response Body

```json
{
  "batch_group_key": "d445060c-7ecf-4a18-870a-feebaadf2618",
  "name": "aaa",
  "main_related_party": "aaa",
  "number_of_documents": 1,
  "total_value": 0,
  "all_files_url": "",
  "send_to_fund_administrator": 0,
  "signature_expiration_date": null,
  "webhook_key": "e4bbb09d-97d0-4cd7-b4fc-71ed7368a650",
  "client_key": "5aaf98d2-0264-48dd-8167-eab859ce5a75",
  "requester_key": null,
  "signature_status": "pending",
  "internal_status": "pending",
  "attached_document_number": "59860422000180",
  "current_signature_position": "1",
  "control_number": null,
  "internal_webhook_key": null,
  "created_at": "2023-05-18 00:02:49",
  "batch_group_type": "icp_signature",
  "requester_identifier": null,
  "send_emails": true,
  "batches": [
    {
      "document_batch_key": "a34bd069-9ae9-4baf-8204-7559e84e6947",
      "name": "Outros",
      "document_type": "other",
      "signature_type": "cades",
      "signature_status": "pending",
      "created_at": "2023-05-18 00:02:49",
      "related_parties": [
        {
          "related_party_key": "b972beb3-7659-40ac-8999-8574cfe42191",
          "name": "Savio",
          "role": "assignor",
          "signature_status": "signed",
          "signature_position": "1",
          "created_at": "2023-05-18 00:02:49",
          "auto_signature": 0,
          "notify_to": [],
          "signer_groups": [
            {
              "id": 38598,
              "expiration": null,
              "minimum_required_signers": 1,
              "signable_limit": null,
              "signature_status": "signed",
              "created_at": "2023-05-18 00:02:49",
              "signers": [
                {
                  "id": 65095,
                  "signer_control_number": "1",
                  "signature_timestamp": "2023-05-18 00:06:08",
                  "signature_status": "signed",
                  "name": "Savio",
                  "is_group_mandatory": true,
                  "email": "savio.gama@qitech.com.br",
                  "document_number": "43141581827",
                  "created_at": "2023-05-18 00:02:49"
                }
              ]
            }
          ]
        },
        {
          "related_party_key": "e19d038e-5c60-47db-aa44-d4d948592705",
          "name": "Turing",
          "role": "guarantor",
          "signature_status": "pending",
          "signature_position": "1",
          "created_at": "2023-05-18 00:02:49",
          "auto_signature": 0,
          "notify_to": [],
          "signer_groups": [
            {
              "id": 38599,
              "expiration": null,
              "minimum_required_signers": 1,
              "signable_limit": null,
              "signature_status": "pending",
              "created_at": "2023-05-18 00:02:49",
              "signers": [
                {
                  "id": 65096,
                  "signer_control_number": "1",
                  "signature_timestamp": null,
                  "signature_status": "pending",
                  "name": "Turing",
                  "is_group_mandatory": true,
                  "email": "teste@gmail.com",
                  "document_number": "56072386105",
                  "created_at": "2023-05-18 00:02:49"
                }
              ]
            }
          ]
        }
      ],
      "documents": [
        {
          "document_key": "40c0940a-3db5-489b-86d6-ebf2717e0a9c",
          "control_number": "9f907aef-04b5-4adb-9f4e-e2c53293c4d7",
          "file_size": 1669,
          "file_url": "https://storage.googleapis.com/certifier-api-storage-sandbox/40c0940a-3db5-489b-86d6-ebf2717e0a9c/teste_of_original.pdf",
          "name": "teste_of.pdf",
          "original_file_url": "https://storage.googleapis.com/certifier-api-storage-sandbox/40c0940a-3db5-489b-86d6-ebf2717e0a9c/teste_of_original.pdf",
          "status": "pending",
          "signed_file_url": null,
          "created_at": "2023-05-18 00:02:49",
          "signatures": [
            {
              "signer": {
                "id": 65095,
                "signer_control_number": "1",
                "signature_timestamp": "2023-05-18 00:06:08",
                "signature_status": "signed",
                "name": "Savio",
                "is_group_mandatory": true,
                "email": "savio.gama@qitech.com.br",
                "document_number": "43141581827",
                "created_at": "2023-05-18 00:02:49"
              },
              "signed_hash": "ldp+t2F5MpgLtA++sIaFxEKXxsVJGnXeco2+cN7v3KSlsvxIwm2xMwQ4JjE8Mm3s93swB0dYBb5m/BBmCuRhzRsopQtVVRgRkdhKSwa5JBWVIgEd7gsb/CMIQqmG4wZLM9XZNUrx60LwfrdAnyjDEg8/JBdoeks3whOeQ1eai04dZyBAHkd6yplnFvi89PhEjLNU93C2CqyjCaSVr5HviLQovlpTxmiPYfRR+cqzlljbYLMqat2LXvjaW2T6AvtYWQRmL3HJ5GmDQytjNXsHBOQFKQ+Nyu+KnEnxg2ofqmNXlhID78YaGFpmZVLT9aLeFflJIFazaHWq6wPq8M5Hqg==",
              "signature_timestamp": "2023-05-18 00:06:08",
              "signature_status": "signed",
              "role": "assignor",
              "created_at": "2023-05-18 00:06:13"
            }
          ]
        }
      ]
    }
  ],
  "watcher_clients": [],
  "zip_file_keys_list": []
}

```

## Finalização do evento

Para a finalização do evento, será enviado primeiramente um webhook informando que todas as partes relacionadas já assinaram. Nesse momento, o campo **internal_status** estará com o valor **waiting_zip_files_creation**. O link para os documentos assinados já estará disponível.

Após o webhook mencionado anteriormente, será enviado um novo webhook informando a finalização completa do evento. Nesse momento, o campo **internal_status** estará com o valor **finished** e o evento será complementado com o arquivo ZIP que pode ser consultado através das chaves contidas em  **zip_file_keys_list**. O arquivo ZIP contém todos os documentos e o arquivo de assinatura.

Para entender como consultar o arquivo ZIP acesse o trecho 4.5. Consultar URL.

### Exemplos de Webhook Aguardando geração do ZIP

Response Body

```json
{
  "batch_group_key": "d445060c-7ecf-4a18-870a-feebaadf2618",
  "name": "aaa",
  "main_related_party": "aaa",
  "number_of_documents": 1,
  "total_value": 0,
  "all_files_url": null,
  "send_to_fund_administrator": 0,
  "signature_expiration_date": null,
  "webhook_key": "e4bbb09d-97d0-4cd7-b4fc-71ed7368a650",
  "client_key": "5aaf98d2-0264-48dd-8167-eab859ce5a75",
  "requester_key": null,
  "signature_status": "signed",
  "internal_status": "waiting_zip_files_creation",
  "attached_document_number": "59860422000180",
  "current_signature_position": "1",
  "control_number": null,
  "internal_webhook_key": null,
  "created_at": "2023-05-18 00:02:49",
  "batch_group_type": "icp_signature",
  "requester_identifier": null,
  "send_emails": true,
  "batches": [
    {
      "document_batch_key": "a34bd069-9ae9-4baf-8204-7559e84e6947",
      "name": "Outros",
      "document_type": "other",
      "signature_type": "cades",
      "signature_status": "signed",
      "created_at": "2023-05-18 00:02:49",
      "related_parties": [
        {
          "related_party_key": "b972beb3-7659-40ac-8999-8574cfe42191",
          "name": "Savio",
          "role": "assignor",
          "signature_status": "signed",
          "signature_position": "1",
          "created_at": "2023-05-18 00:02:49",
          "auto_signature": 0,
          "notify_to": [],
          "signer_groups": [
            {
              "expiration": null,
              "minimum_required_signers": 1,
              "signable_limit": null,
              "signature_status": "signed",
              "created_at": "2023-05-18 00:02:49",
              "signers": [
                {
                  "signer_control_number": "1",
                  "signature_timestamp": "2023-05-18 00:06:08",
                  "signature_status": "signed",
                  "name": "Savio",
                  "is_group_mandatory": true,
                  "email": "savio.gama@qitech.com.br",
                  "document_number": "43141581827",
                  "created_at": "2023-05-18 00:02:49"
                }
              ]
            }
          ]
        },
        {
          "related_party_key": "e19d038e-5c60-47db-aa44-d4d948592705",
          "name": "Turing",
          "role": "guarantor",
          "signature_status": "signed",
          "signature_position": "1",
          "created_at": "2023-05-18 00:02:49",
          "auto_signature": 0,
          "notify_to": [],
          "signer_groups": [
            {
              "expiration": null,
              "minimum_required_signers": 1,
              "signable_limit": null,
              "signature_status": "signed",
              "created_at": "2023-05-18 00:02:49",
              "signers": [
                {
                  "signer_control_number": "1",
                  "signature_timestamp": "2023-05-18 00:09:44",
                  "signature_status": "signed",
                  "name": "Turing",
                  "is_group_mandatory": true,
                  "email": "teste@gmail.com",
                  "document_number": "56072386105",
                  "created_at": "2023-05-18 00:02:49"
                }
              ]
            }
          ]
        }
      ],
      "documents": [
        {
          "document_key": "40c0940a-3db5-489b-86d6-ebf2717e0a9c",
          "control_number": "9f907aef-04b5-4adb-9f4e-e2c53293c4d7",
          "file_size": 1669,
          "file_url": "https://storage.googleapis.com/certifier-api-storage-sandbox/40c0940a-3db5-489b-86d6-ebf2717e0a9c/teste_of_signed.p7s",
          "name": "teste_of.pdf",
          "original_file_url": "https://storage.googleapis.com/certifier-api-storage-sandbox/40c0940a-3db5-489b-86d6-ebf2717e0a9c/teste_of_original.pdf",
          "status": "signed",
          "signed_file_url": "https://storage.googleapis.com/certifier-api-storage-sandbox/40c0940a-3db5-489b-86d6-ebf2717e0a9c/teste_of_signed.pdf",
          "created_at": "2023-05-18 00:02:49",
          "signatures": [
            {
              "signer": {
                "signer_control_number": "1",
                "signature_timestamp": "2023-05-18 00:06:08",
                "signature_status": "signed",
                "name": "Savio",
                "is_group_mandatory": true,
                "email": "savio.gama@qitech.com.br",
                "document_number": "43141581827",
                "created_at": "2023-05-18 00:02:49"
              },
              "signed_hash": "ldp+t2F5MpgLtA++sIaFxEKXxsVJGnXeco2+cN7v3KSlsvxIwm2xMwQ4JjE8Mm3s93swB0dYBb5m/BBmCuRhzRsopQtVVRgRkdhKSwa5JBWVIgEd7gsb/CMIQqmG4wZLM9XZNUrx60LwfrdAnyjDEg8/JBdoeks3whOeQ1eai04dZyBAHkd6yplnFvi89PhEjLNU93C2CqyjCaSVr5HviLQovlpTxmiPYfRR+cqzlljbYLMqat2LXvjaW2T6AvtYWQRmL3HJ5GmDQytjNXsHBOQFKQ+Nyu+KnEnxg2ofqmNXlhID78YaGFpmZVLT9aLeFflJIFazaHWq6wPq8M5Hqg==",
              "signature_timestamp": "2023-05-18 00:06:08",
              "signature_status": "signed",
              "role": "assignor",
              "created_at": "2023-05-18 00:06:13"
            },
            {
              "signer": {
                "signer_control_number": "1",
                "signature_timestamp": "2023-05-18 00:09:44",
                "signature_status": "signed",
                "name": "Turing",
                "is_group_mandatory": true,
                "email": "teste@gmail.com",
                "document_number": "56072386105",
                "created_at": "2023-05-18 00:02:49"
              },
              "signed_hash": "Djc8YDrgdrHdhpyfP6rmp/6HIPfA1NdzSU3gov1A0PbhrJhW1toOOGZ5VHCM82EHT77fB5G7gmJSIaufU9+Mz9o3pzWqY3GRQe3g9vqO01ejonIf1HOEpkx5Q/9bB23L/OlnzGfrQ2JCzsuExpTzkmG65zKMzNdHFdmz3PtdpssTl3kQNIG00piKxHE5GiRC67uYcZyFDWQbHEeNSczrCodIlKVCtfc7V8dzsfIr+4u6vtkQYhj6GTRYIxcJjgtYJfHnMlgsQUstl0Vyt3tQzfkAq021HmvlMtf/N3WZRZGThLTb1NczEEVnD/AXllQvW08mtOHQKBnVkxB8xQikEw==",
              "signature_timestamp": "2023-05-18 00:09:44",
              "signature_status": "signed",
              "role": "guarantor",
              "created_at": "2023-05-18 00:09:45"
            }
          ]
        }
      ]
    }
  ],
  "watcher_clients": [],
  "zip_file_keys_list": []
}

```

### Exemplos de Webhook Evento finalizado

Response Body

```json
{
  "batch_group_key": "d445060c-7ecf-4a18-870a-feebaadf2618",
  "name": "aaa",
  "main_related_party": "aaa",
  "number_of_documents": 1,
  "total_value": 0,
  "all_files_url": "https://storage.googleapis.com/certifier-worker-storage-sandbox/d445060c-7ecf-4a18-870a-feebaadf2618/d445060c-7ecf-4a18-870a-feebaadf2618.zip",
  "send_to_fund_administrator": 0,
  "signature_expiration_date": null,
  "webhook_key": "e4bbb09d-97d0-4cd7-b4fc-71ed7368a650",
  "client_key": "5aaf98d2-0264-48dd-8167-eab859ce5a75",
  "requester_key": null,
  "signature_status": "signed",
  "internal_status": "finished",
  "attached_document_number": "59860422000180",
  "current_signature_position": "1",
  "control_number": null,
  "internal_webhook_key": null,
  "created_at": "2023-05-18 00:02:49",
  "batch_group_type": "icp_signature",
  "requester_identifier": null,
  "send_emails": true,
  "batches": [
    {
      "document_batch_key": "a34bd069-9ae9-4baf-8204-7559e84e6947",
      "name": "Outros",
      "document_type": "other",
      "signature_type": "cades",
      "signature_status": "signed",
      "created_at": "2023-05-18 00:02:49",
      "related_parties": [
        {
          "related_party_key": "b972beb3-7659-40ac-8999-8574cfe42191",
          "name": "Savio",
          "role": "assignor",
          "signature_status": "signed",
          "signature_position": "1",
          "created_at": "2023-05-18 00:02:49",
          "auto_signature": 0,
          "notify_to": [],
          "signer_groups": [
            {
              "expiration": null,
              "minimum_required_signers": 1,
              "signable_limit": null,
              "signature_status": "signed",
              "created_at": "2023-05-18 00:02:49",
              "signers": [
                {
                  "signer_control_number": "1",
                  "signature_timestamp": "2023-05-18 00:06:08",
                  "signature_status": "signed",
                  "name": "Savio",
                  "is_group_mandatory": true,
                  "email": "savio.gama@qitech.com.br",
                  "document_number": "43141581827",
                  "created_at": "2023-05-18 00:02:49"
                }
              ]
            }
          ]
        },
        {
          "related_party_key": "e19d038e-5c60-47db-aa44-d4d948592705",
          "name": "Turing",
          "role": "guarantor",
          "signature_status": "signed",
          "signature_position": "1",
          "created_at": "2023-05-18 00:02:49",
          "auto_signature": 0,
          "notify_to": [],
          "signer_groups": [
            {
              "expiration": null,
              "minimum_required_signers": 1,
              "signable_limit": null,
              "signature_status": "signed",
              "created_at": "2023-05-18 00:02:49",
              "signers": [
                {
                  "signer_control_number": "1",
                  "signature_timestamp": "2023-05-18 00:09:44",
                  "signature_status": "signed",
                  "name": "Turing",
                  "is_group_mandatory": true,
                  "email": "teste@gmail.com",
                  "document_number": "56072386105",
                  "created_at": "2023-05-18 00:02:49"
                }
              ]
            }
          ]
        }
      ],
      "documents": [
        {
          "document_key": "40c0940a-3db5-489b-86d6-ebf2717e0a9c",
          "control_number": "9f907aef-04b5-4adb-9f4e-e2c53293c4d7",
          "file_size": 1669,
          "file_url": "https://storage.googleapis.com/certifier-api-storage-sandbox/40c0940a-3db5-489b-86d6-ebf2717e0a9c/teste_of_signed.p7s",
          "name": "teste_of.pdf",
          "original_file_url": "https://storage.googleapis.com/certifier-api-storage-sandbox/40c0940a-3db5-489b-86d6-ebf2717e0a9c/teste_of_original.pdf",
          "status": "signed",
          "signed_file_url": "https://storage.googleapis.com/certifier-api-storage-sandbox/40c0940a-3db5-489b-86d6-ebf2717e0a9c/teste_of_signed.pdf",
          "created_at": "2023-05-18 00:02:49",
          "signatures": [
            {
              "signer": {
                "signer_control_number": "1",
                "signature_timestamp": "2023-05-18 00:06:08",
                "signature_status": "signed",
                "name": "Savio",
                "is_group_mandatory": true,
                "email": "savio.gama@qitech.com.br",
                "document_number": "43141581827",
                "created_at": "2023-05-18 00:02:49"
              },
              "signed_hash": "ldp+t2F5MpgLtA++sIaFxEKXxsVJGnXeco2+cN7v3KSlsvxIwm2xMwQ4JjE8Mm3s93swB0dYBb5m/BBmCuRhzRsopQtVVRgRkdhKSwa5JBWVIgEd7gsb/CMIQqmG4wZLM9XZNUrx60LwfrdAnyjDEg8/JBdoeks3whOeQ1eai04dZyBAHkd6yplnFvi89PhEjLNU93C2CqyjCaSVr5HviLQovlpTxmiPYfRR+cqzlljbYLMqat2LXvjaW2T6AvtYWQRmL3HJ5GmDQytjNXsHBOQFKQ+Nyu+KnEnxg2ofqmNXlhID78YaGFpmZVLT9aLeFflJIFazaHWq6wPq8M5Hqg==",
              "signature_timestamp": "2023-05-18 00:06:08",
              "signature_status": "signed",
              "role": "assignor",
              "created_at": "2023-05-18 00:06:13"
            },
            {
              "signer": {
                "signer_control_number": "1",
                "signature_timestamp": "2023-05-18 00:09:44",
                "signature_status": "signed",
                "name": "Turing",
                "is_group_mandatory": true,
                "email": "teste@gmail.com",
                "document_number": "56072386105",
                "created_at": "2023-05-18 00:02:49"
              },
              "signed_hash": "Djc8YDrgdrHdhpyfP6rmp/6HIPfA1NdzSU3gov1A0PbhrJhW1toOOGZ5VHCM82EHT77fB5G7gmJSIaufU9+Mz9o3pzWqY3GRQe3g9vqO01ejonIf1HOEpkx5Q/9bB23L/OlnzGfrQ2JCzsuExpTzkmG65zKMzNdHFdmz3PtdpssTl3kQNIG00piKxHE5GiRC67uYcZyFDWQbHEeNSczrCodIlKVCtfc7V8dzsfIr+4u6vtkQYhj6GTRYIxcJjgtYJfHnMlgsQUstl0Vyt3tQzfkAq021HmvlMtf/N3WZRZGThLTb1NczEEVnD/AXllQvW08mtOHQKBnVkxB8xQikEw==",
              "signature_timestamp": "2023-05-18 00:09:44",
              "signature_status": "signed",
              "role": "guarantor",
              "created_at": "2023-05-18 00:09:45"
            }
          ]
        }
      ]
    }
  ],
  "watcher_clients": [],
  "zip_file_keys_list": [
    "a1a8cd68-aab4-csbf-1180-dd8ebe395612",
    "cda8cd68-7331-qebf-1280-fw8ebe395676"
  ]
}

```

---

# Criação de Cessões

URL: /documentation/cessoes/criacao_de_cessao_0eaeffec-ee95-4cb1-a266-bcb52f23237d

A API de cessão permite a criação e consulta de cessões diretamente pelo cliente. É possível criar uma cessão utilizando a key (UUID4) de configuração de cessão e consultar informações gerais da cessão através de endpoints específicos.

:::caution Atenção
Esse serviço está disponível apenas para parceiros com configuração de cessão cadastrados, por favor consulte nosso suporte para mais detalhes.
:::

## Criação de Cessão

Para criar uma cessão, é necessário realizar um POST no endpoint com a chave de configuração do cliente (**assignment_configuration_key**), o conjunto de **credit_operation_keys** das operações de crédito integrantes da cessão, e a **daily_assignment_interest_rate**, que corresponde à taxa de juros diária de cessão. Tal taxa está na mesma base de dias do contrato em questão.

### Request

ENDPOINT /v2/assignment/assignment_configuration/[assignment_configuration_key]/assignment
MÉTODO POST

### Params

| Campo                          | Descrição                                                 |
| ------------------------------ | --------------------------------------------------------- |
| `assignment_configuration_key` | Chave identificadora da configuração de cessão do cliente |

Request Body

```json
{
  "credit_operation_keys": ["key1", "key2", "key3"],
  "daily_assignment_interest_rate": 0.0003
}
```

:::caution Atenção
Caso a **daily_assignment_interest_rate** não seja informada no Request para os contratos específicos, será usada a taxa de cessão cadastrada na configuração de cessão do cliente.
:::

### Response

STATUS 201

Response Body

```json
[
  {
  "assignment_key": "868a2951-efff-4e41-8adf-bc36871a20fb",
  "creation_datetime": "2023-10-01T12:00:00",
  "reference_date": "2023-10-01",
  "total_amount": 120000,
  "number_of_items": 3,
  "status": "pending_items_calculation",
  "created_at": "2023-10-01T11:00:00"
  }
]
```

## Consulta de Cessão
Para consultar uma cessão específica, o cliente pode realizar um GET no endpoint utilizando a chave identificadora da cessão (**assignment_key**).

### Request

ENDPOINT /v2/assignment/[assignment_key] MÉTODO GET

### Params

| Campo            | Descrição                      |
| ---------------- | ------------------------------ |
| `assignment_key` | Chave identificadora da cessão |

### Response

STATUS 200

Response Body

```json
{
  "assignment_key": "77997168-5d61-430f-b5ae-08eb3d7b8c0e",
  "creation_datetime": "2023-10-01T12:00:00",
  "reference_date": "2023-10-01",
  "total_amount": 120000,
  "number_of_items": 5,
  "term_of_assignment_url": "https://example.com/assignment.pdf",
  "status": "settled",
  "signable_term_url": "https://example.com/signable_term.pdf"
}
```

## Consulta de Itens da Cessão
Para consultar os contratos na cessão, utilize o GET no endpoint com a mesma **assignment_key**.

### Request

ENDPOINT /v2/assignment/[assignment_key]/assignment_items MÉTODO GET

### Params

| Campo            | Descrição                      |
| ---------------- | ------------------------------ |
| `assignment_key` | Chave identificadora da cessão |

### Response

O retorno é uma lista de informações de cada contrato na cessão (status 200), paginado:

### Response

STATUS 200

Response Body

```json
{
    "data": [
        {
            "assignment_item_key": "439b1257-82ac-4741-a416-a4428a9a7327",
            "control_number": "0001",
            "credit_operation_key": "d7f2ba40-30ea-4462-890c-6a99a7d85659",
            "issuer_name": "João Santos",
            "issuer_document_number": "12345678912",
            "issue_amount": 50000,
            "disbursed_amount": 45000,
            "disbursement_date": "2023-01-01",
            "number_of_installments": 12,
            "contract_number": "XXX182938",
            "present_amount": 48000,
            "status": "settled",
            "endorsement_url": "https://example.com/endorsement.pdf",
            "purchaser_document_number": "1234567890001"
        }
    ],
    "pagination": {
        "page": 1,
        "page_size": 10
    }
}
```

---

# Abertura de conta escrow PF

URL: /documentation/contas/abertura_de_conta_escrow/abertura_de_conta_escrow_pf

## Request

ENDPOINT /escrow
MÉTODO POST

**Request Body**

```json
{
  "account_owner": {
        "person_type": "natural",
        "name": "Patrícia Tereza Bernardes",
        "mother_name": "Maria Mariane",
        "birth_date": "1990-05-06",
        "nationality": "nationality",
        "is_pep": false,
        "individual_document_number": "34651104630",
        "document_identification": "3c24579b-9810-4fa6-9b08-fe67d237160a",
        "email": "api@qitech.com.br",
        "address": {
            "street": "Av. Brigadeiro Faria Lima",
            "state": "SP",
            "city": "São Paulo",
            "neighborhood": "Jardim Paulistano",
            "number": "2391",
            "postal_code": "01452905",
            "complement": "1o. Andar"
        },
        "phone": {
            "country_code": "055",
            "area_code": "11",
            "number": "999999999"
        },
        "proof_of_residence": "780456bd-1eec-4e5f-82c0-d8c3921497ea"
    },
  "destination_list": [
        {
            "account_branch": "0001",
            "account_digit": "4",
            "account_number": "15570",
            "document_number": "34651104630",
            "financial_institutions_code_number": "329",
            "name": "Patrícia Tereza Bernardes",
            "ted_account_type": "deposit_account"
        }
    ],
  "signed_contract": {
        "document_key": "4d7f4e29-4b58-4905-9a69-b1f9215263f5",
        "signatures": [
            {
                "authenticity": {
                    "timestamp": "1970-01-01T00:00:01.080100Z",
                    "facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
                    "lang": "-35.8916627",
                    "lat": "-7.2226067",
                    "ip_address": "177.51.1.000",
                    "session_id": "jdifj329842"
                },
                "signer": {
                    "name": "IVANILDO DE SENA LIMA",
                    "email": "teste@gmail.com",
                    "phone": {
                        "country_code": "055",
                        "area_code": "11",
                        "number": "999999999"
                    },
                    "document_number": "99999999999"
                },
                "authentication_type": "opt-in"
            }
        ]
    }
}
```

### Body Params

| Campo |Tipo | Descrição | Caracteres |
|---|---| ---|---|
| `account_owner` * | object  | Objeto Dono da conta |**[Objeto account_owner](#objeto-account_owner)**  | 
| `destination_list` | object  | lista de contas de destino, que são aquelas para onde é permitida a transferência de recursos. | **[Objeto destination_list](#objeto-destination_list)**  |
| `signed_contract` *| object | Objeto contento as informações da assinatura do contrato. | **[Objeto signed_contract](#objeto-signed_contract)** |

### Objeto account_owner

| Campo | Tipo | Descrição | Caracteres |
|---| ---| ---| ---| 
| `address` | string | Endereço do cliente. | **[Objeto adress](#objeto-address)** |  |
| `birth_date` * | string |  Data de nascimento da pessoa (formato "AAAA-MM-DD") |  |
| `document_identification` * | string |  DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) |  |
| `email` * | string |  Email do cliente. |  |
| `individual_document_number` | string | CPF da pessoa (apenas números). Limitado a 11 caracteres. |  |
| `is_pep` * | string |  Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep).|  |
| `mother_name` * | string |  Nome da mãe do cliente em caso de PF. | 100 |
| `name` * | string |  Razão social em caso de operações PJ ou Nome da pessoa em caso de operações PF. | 100 |
| `nationality` * | string |  Nacionalidade do cliente. | 50 |
| `person_type` * | string | Identificador de que o objeto enviado é uma pessoa física ou jurídica.|  |
| `phone` | string | Objeto com dados do telefone | **[Objeto phone](#objeto-phone)**|
| `proof_of_residence` | string |  DOCUMENT_KEY do PDF do comprovante de endereço do endereço enviado (enviado previamente).| |

### Objeto address 

Este objeto, presente tanto no objeto PF quanto no objeto PJ, é um simples objeto para representar um endereço.

| Campo | Descrição | Exemplo |  Máx. Caracteres | 
|---|---|---|---| 
| `street` *| string | Rua do endereço  | 100 |
| `state` *| string | Estado do endereço (com dois caracteres maiúsculos) | 2 |
| `city` *| string | Cidade do endereço | 100 |
| `neighborhood` *| string |Bairro do endereço | 100 |
| `number` *| string | Número da rua | 10 |
| `postal_code` *| string |CEP do endereço (http://www.buscacep.correios.com.br/sistemas/buscacep/) (apenas números) |  8 |
| `complement` *| string |Complemento do endereço (texto livre) | 100 |

### Objeto signed_contract 
| Campo | Tipo   | Descrição        | Caracteres    |
|-------|--------|------------------|---------------|
| **document_key** * | uuidv4 | Chave única de identificação do documento do **Termo de Abertura de Conta** ou **Contrato de Conta Escrow**. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36            |
| **signatures** *   | list   | Dados de assinatura do documento enviado. Cada item da lista, corresponde a um assinante do documento.      | [Objeto signatures](#objeto-signatures) |

### Objeto signatures
| Campo | Tipo       | Descrição         | Caracteres        |
|-------|------------|-------------------|-------------------|
| **authenticity** * | object     | Conjunto de dados que evidenciam a assinatura eletrônica realizada pelo assinante. | [Objeto authenticity](#objeto-authenticity) |
| **signer** * | object     | Objeto contendo os dados de um dos assinantes do documento.           | [Objeto signer](#objeto-signer)|
| **authentication_type** * | enumerator | Tipo de assinatura. Sempre será "**opt-in**"| "**opt-in**"                   |

### Objeto authenticity
| Campo | Tipo   | Descrição               | Caracteres |
|-------|--------|-------------------------|------------|
| **timestamp** *            | string | Data e hora do momento da assinatura do documento.                | 27         |
| **facial_recognition_key** | uuidv4 | Chave única de identificação da foto da selfie do titular da conta. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36         |
| **lang**                   | string | Coordenada de longitude da geolocalização do assinante capturada no momento da assinatura.                  | -          |
| **lat**                    | string | Coordenada de latitude da geolocalização do assinante capturada no momento da assinatura.                   | -          |
| **ip_address**             | string | Endereço IP do dispositivo do assinante.     | -          |
| **session_id**             | string | ID da seção do assinante no momento da assinatura.                | -          |

### Objeto signer
| Campo                 | Tipo   | Descrição                                 | Caracteres                        |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** *            | string | Nome do assinante.                        | -                                 |
| **email** *           | string | Email do assinante.                       | -                                 |
| **phone** *           | object | Objeto com dados do telefone do assinante | **[Objeto phone](#objeto-phone)** |
| **document_number** * | string | CPF do assinante.                         | 11                                |

### Objeto phone 

| Campo | Descrição | Exemplo |  Máx. Caracteres | 
| --- | --- | --- | --- | 
|`country_code` *| string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 | 
| `area_code` *| string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |Número de telefone (apenas números) |  10 |

### Objeto phone 

| Campo | Descrição | Exemplo |  Máx. Caracteres | 
| --- | --- | --- | --- | 
|`country_code` *| string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 | 
| `area_code` *| string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |Número de telefone (apenas números) |  10 |

### Objeto destination_list 

| Campo | Descrição | Exemplo |  Máx. Caracteres | 
| --- | --- | --- | --- | 
|`account_branch` *| string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 | 
| `account_digit` *| string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `account_number` *| string |Número de telefone (apenas números) |  10 |
| `document_number` *| string |Número de telefone (apenas números) |  10 |
| `financial_institutions_code_number` *| string |Código COMPE da instituição financeira (https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf) (com 3 dígitos). |  3 |
| `name` *| string |Nome da pessoa física ou razão social da pessoa jurídica. |  10 |
| `ted_account_type` *| enum |Tipo da conta de destino. |  **[Enumeradores](#enumeradores-ted_account_type)** |

### Enumeradores ted_account_type

| Enumerador | Tradução |
|---|---|
|  checking_account  | conta corrente |
|  deposit_account  |  conta depósito  |
|  guaranteed_account  |  conta de garantia  |
|  investment_account  |  conta de investimento |
|  payment_account  | conta de pagamento |
|  saving_account  | conta poupança  |

## Response

STATUS 200

**Response Body**

```json
{
  "data": {
    "account_info": {
      "account_branch": "0001",
      "account_digit": "3",
      "account_number": "66777",
      "financial_institution_code": "329"
    },
    "account_manager": {
      "company_representatives": [
        {
          "document_number": "08141163701",
          "name": "Aurora Simone Catarina Nogueira"
        }
      ],
      "document_number": "09456933000162",
      "name": "Kaique e Giovanna Contábil ME"
    },
    "account_owner": {
      "company_representatives": [
        {
          "document_number": "38689533370",
          "name": "Priscila Rayssa Barros"
        },
        {
          "document_number": "85324558400",
          "name": "Caio Bruno Dias"
        }
      ],
      "document_number": "98916615000167",
      "name": "Alice e Isis Advocacia ME"
    },
    "allowed_transfer_account_list": [
      {
        "account_branch": "0001",
        "account_digit": "2",
        "account_number": "532312",
        "document_number": "49067117153",
        "financial_institution": {
          "code": 341,
          "ispb": 60701190,
          "name": "Itaú Unibanco  S.A."
        },
        "name": "Juan Anthony Farias"
      },
      {
        "account_branch": "0002",
        "account_digit": "9",
        "account_number": "537612",
        "document_number": "39063217000123",
        "financial_institution": {
          "code": 33,
          "ispb": 90400888,
          "name": "Banco Santander (Brasil) S. A."
        },
        "name": "Farias Advogados"
      }
    ],
    "allowed_user": {
      "document_number": "13708610440",
      "name": "Renato Noah Pinto"
    }
  },
  "event_datetime": "2019-11-07 18:15:07",
  "key": "61341599-790b-4236-b42f-060634eba88f",
  "status": "waiting_administrator_approval",
  "webhook_type": "escrow"
}
```

STATUS 400

**Response Body**

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

---

# Abertura de conta escrow PJ

URL: /documentation/contas/abertura_de_conta_escrow/abertura_de_conta_escrow_pj

## Request

ENDPOINT /escrow
MÉTODO POST

**Request Body**

```json
{
    "account_manager": {
        "address": {
            "city": "São Paulo",
            "complement": "",
            "neighborhood": "Vila Madalena",
            "number": "40",
            "postal_code": "05435030",
            "state": "SP",
            "street": "Rua das batatas"
        },
        "cnae_code": "6619-3/99",
        "company_document_number": "99999999000188",
        "company_representatives": [
            {
                "address": {
                    "city": "São Paulo",
                    "complement": "",
                    "neighborhood": "Vila Madalena",
                    "number": "40",
                    "postal_code": "05435030",
                    "state": "SP",
                    "street": "Rua da Alegria"
                },
                "birth_date": "1982-12-30",
                "email": "teste@email.tech",
                "individual_document_number": "99999999999",
                "is_pep": false,
                "final_beneficiary": true,
                "mother_name": "Ana Perdigão",
                "name": "João Victor",
                "nationality": "Brasileira",
                "person_type": "natural",
                "phone": {
                    "area_code": "12",
                    "country_code": "055",
                    "number": "999999999"
                },
                "document_identification": "a28b9c7d-f0c3-4310-ac6d-61898d29b18d",
                "proof_of_residence": "a28b9c7d-f0c3-4310-ac6d-61898d29b18d"
            }
        ],
        "company_statute": "a28b9c7d-f0c3-4310-ac6d-61898d29b18d",
        "directors_election_minute": "a28b9c7d-f0c3-4310-ac6d-61898d29b18d",
        "email": "email@teste.tech",
        "foundation_date": "2021-10-05",
        "name": "TESTE TECH LTDA.",
        "person_type": "legal",
        "phone": {
            "area_code": "11",
            "country_code": "55",
            "number": "999999999"
        },
        "trading_name": "TESTE TECH LTDA."
    },
    "account_owner": {
        "address": {
            "city": "Caraguatatuba",
            "complement": "complemento",
            "neighborhood": "Jaraguazinho",
            "number": "924",
            "postal_code": "11675200",
            "state": "SP",
            "street": "Praça da Rua"
        },
        "cnae_code": "4721-1/02",
        "company_statute": "70448962-8f01-4835-b031-755514192641",
        "company_document_number": "49999999000130",
        "company_type": "ltda",
        "email": "email@yteste.com",
        "foundation_date": "2017-09-16",
        "name": "NOME DA EMPRESA",
        "person_type": "legal",
        "phone": {
            "area_code": "19",
            "country_code": "055",
            "number": "988888888"
        },
        "trading_name": "Pães e Doces",
        "company_representatives": [
            {
                "name": "Marco Ayo",
                "address": {
                    "city": "Recife",
                    "complement": null,
                    "neighborhood": "Fundão",
                    "number": "137",
                    "postal_code": "522222220",
                    "state": "PE",
                    "street": "Rua dos Camaroes"
                },
                "email": "marcos.teste@teste.com",
                "birth_date": "1972-02-02",
                "individual_document_number": "55555555555",
                "document_identification": "70448962-8454-4835-b031-755514192641",
                "document_identification_number": "999999999",
                "is_pep": false,
                "final_beneficiary": true,
                "marital_status": "single",
                "mother_name": "Sueli da Mata",
                "nationality": "Brasileira",
                "person_type": "natural",
                "phone": {
                    "area_code": "88",
                    "country_code": "055",
                    "number": "999999999"
                }
            }
        ]
    },
    "destination_list": [
        {
            "account_branch": "0001",
            "account_digit": "2",
            "account_number": "123321",
            "document_number": "99999999999",
            "financial_institutions_code_number": "341",
            "name": "Conta Destino Teste SA."
        }
    ],
    "allowed_user": {
        "email": "teste@email.com",
        "individual_document_number": "99999999999",
        "name": "Luiz Alberto ",
        "person_type": "natural",
        "phone": {
            "country_code": "055",
            "area_code": "12",
            "number": "999999999"
        }
    },
    "signed_contract": {
        "document_key": "4d7f4e29-4b58-4905-9a69-b1f9215263f5",
        "signatures": [
            {
                "authenticity": {
                    "timestamp": "1970-01-01T00:00:01.080100Z",
                    "facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
                    "lang": "-35.8916627",
                    "lat": "-7.2226067",
                    "ip_address": "177.51.1.000",
                    "session_id": "jdifj329842"
                },
                "signer": {
                    "name": "IVANILDO DE SENA LIMA",
                    "email": "teste@gmail.com",
                    "phone": {
                        "country_code": "055",
                        "area_code": "11",
                        "number": "999999999"
                    },
                    "document_number": "99999999999"
                },
                "authentication_type": "opt-in"
            }
        ]
    }
}

```

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `account_manager` * | object | Objeto que possui pessoa responsável pelas movimentações da conta. | **[Objeto adress](#objeto-address)** |  
| `account_owner` * |  object | Objeto Dono da conta. | **[Objeto account_owner](#objeto-account_owner)** |  
| `allowed_user` * | object | Objeto que possui pessoa que terá acesso à conta para consultas. | **[Objeto allowed_user](#objeto-allowed_user)** |  
| `destination_list` * |  object | Lista de contas de destino, que são aquelas para onde é permitida a transferência de recursos. | **[Objeto destination_list](#objeto-destination_list)** |  
| `signed_contract` *| object | Objeto contento as informações da assinatura do contrato. | **[Objeto signed_contract](#objeto-signed_contract)** |

### Objeto account_manager

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `address` *| object | Endereço do cliente. |  **[Objeto address](#objeto-address)** |  
| `cnae_code` * |  string | Classificação Nacional de Atividades Econômicas | 14 |
| `company_document_number` | object | CNPJ  | 14|  
| `company_statute` *| string | DOCUMENT_KEY do PDF do estatuto da empresa (enviado previamente). | chave uuid | 
| `directors_election_minute` *| string | DOCUMENT_KEY do PDF da Ata de Representantes Legais da empresa (enviado previamente). | chave uuid | 
| `email`  *| string | Email institucional da empresa. |  | 
| `foundation_date`  *| date |  Data de abertura da empresa (formato "AAAA-MM-DD"). |  
| `name`  *| string |  Razão social. |  | 
| `person_type`  *| string |  Identificador de que o objeto enviado é uma pessoa jurídica. Deve conter SEMPRE o valor "legal" para Objeto PJ. | 
| `phone` | string | Objeto com dados do telefone | **[Objeto phone](#objeto-phone)**||
| `trading_name`  *| string |  Nome fantasia da empresa | |

### Objeto company_representatives

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---| 
| `person_type` * | string |Identificador de que o objeto enviado é uma pessoa física. Deve conter SEMPRE o valor "natural" para Objeto PF.| 11 |
| `name` * |string | Razão social em caso de operações PJ ou Nome da pessoa em caso de operações PF. Limitado a 100 caracteres.| 11 |
| `mother_name` * |  string |Nome da mãe da pessoa.| 11 |
| `birth_date` * | string | Data de nascimento da pessoa (formato "AAAA-MM-DD") | 11 |
| `nationality` * | string | Nacionalidade do cliente. Limitado a 50 caracteres.| 11 |
| `is_pep` * | string | Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep).| 11 |
| `final_beneficiary` | boolean | Declaração se o representante é beneficiário final da empresa. | - |
| `individual_document_number` |  string | CPF da pessoa (apenas números). | 11 |
| `document_identification` * | string | DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) |  UUUUID |
| `proof_of_residence` * | UUUUID | DOCUMENT_KEY do PDF do comprovante de residência (enviado previamente) | UUUUID |
| `email` * | string | Email da pessoa. | 11 |
| `address` | string |  Objeto endereço da pessoa. | 11 |

### Objeto address 

Este objeto, presente tanto no objeto PF quanto no objeto PJ, é um simples objeto para representar um endereço.

| Campo | Descrição | Exemplo |  Máx. Caracteres | 
|---|---|---|---| 
| `street` *| string | Rua do endereço  | 10 |
| `state` *| string | Estado do endereço (com dois caracteres maiúsculos) | 2 |
| `city` *| string | Cidade do endereço | 10 |
| `neighborhood` *| string |Bairro do endereço | 10 |
| `number` *| string | Número da rua | 10 |
| `postal_code` *| string |CEP do endereço (http://www.buscacep.correios.com.br/sistemas/buscacep/) (apenas números) | 8 |
| `complement` *| string |Complemento do endereço (texto livre) | 100 |

### Objeto account_owner

| Campo| Tipo   | Descrição | Caracteres  |
|------|--------|-----------|-------------|
| `address`*                 | object | Objeto endereço do titular da conta   | **[Objeto address](#objeto-address)**         |
| `cnae_code` *               | string | Classificação Nacional de Atividades Econômicas | 9 |
| `company_document_number` * | string | CNPJ      | 14|
| `company_statute` *         | string | DOCUMENT_KEY do PDF do estatuto da empresa (enviado previamente).       | 36|
| `company_type`              | enum   | Tipo da empresa         | **[Enumeradores company_type](#enumeradores-company_type)** |
| `company_representatives` * | list   | Lista dos representantes legais da empresa      | **[Objeto company_representatives](#objeto-company_representatives)** |
| `email` *         | string | Email institucional da empresa.   | 254         |
| `foundation_date` *         | string | Data de abertura da empresa (formato "AAAA-MM-DD").       | 10|
| `name` *| string | Razão social. | 100         |
| `person_type` *   | enum   | Identificador de que o objeto enviado é uma pessoa jurídica. Deve conter SEMPRE o valor "legal" para Objeto PJ.| **[Enumeradores person_type](#enumeradores-person_type)**  |
| `phone` *         | object | Telefone do titular da conta.     | **[Objeto phone](#objeto-phone)**   | - |
| `trading_name` *  | string | Nome fantasia.                    | 200                   |

### Objeto allowed_user

| Campo | Descrição | Exemplo |  Máx. Caracteres | 
|---|---|---|---|
| `email` * | string | Email do usuário da conta. | 10 | 
| `individual_document_number` * | string | CPF do usuário da conta (apenas números). | 10 | 
| `name` * | string | Nome do usuário da conta. | 10 | 
| `person_type` * | string | Identificador de que o objeto enviado é uma pessoa física. Deve conter SEMPRE o valor "natural". | 10 | 
| `phone` | string | Objeto telefone do usuário. | **[Objeto phone](#objeto-phone)** | 

### Objeto destination_list

| Campo | Descrição | Exemplo |  Máx. Caracteres | 
| --- | --- | --- | --- |  
| `account_branch` * | string | Número da agência. | 3 |
| `account_digit` * | string | Dígito verificador da conta (obrigatório caso haja). | 3 |
| `account_number` * | string | Número da conta. | 3 |
| `document_number` * | string | CPF ou CNPJ da pessoa (apenas números). | 3 |
| `financial_institutions_code_number` * | string | Código COMPE da instituição financeira (https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf)| 3 |
| `name` * | string | Nome da pessoa física ou razão social da pessoa jurídica. |  
| `ted_account_type` * | enum | Tipo da conta de destino. | **[Enumeradores](#enumeradores-ted_account_type)** |

### Objeto signed_contract 
| Campo | Tipo   | Descrição        | Caracteres    |
|-------|--------|------------------|---------------|
| **document_key** * | uuidv4 | Chave única de identificação do documento do **Termo de Abertura de Conta** ou **Contrato de Conta Escrow**. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36            |
| **signatures** *   | list   | Dados de assinatura do documento enviado. Cada item da lista, corresponde a um assinante do documento.      | [Objeto signatures](#objeto-signatures) |

### Objeto signatures
| Campo | Tipo       | Descrição         | Caracteres        |
|-------|------------|-------------------|-------------------|
| **authenticity** * | object     | Conjunto de dados que evidenciam a assinatura eletrônica realizada pelo assinante. | [Objeto authenticity](#objeto-authenticity) |
| **signer** * | object     | Objeto contendo os dados de um dos assinantes do documento.           | [Objeto signer](#objeto-signer)|
| **authentication_type** * | enumerator | Tipo de assinatura. Sempre será "**opt-in**"| "**opt-in**"                   |

### Objeto authenticity
| Campo | Tipo   | Descrição               | Caracteres |
|-------|--------|-------------------------|------------|
| **timestamp** *            | string | Data e hora do momento da assinatura do documento.                | 27         |
| **facial_recognition_key** | uuidv4 | Chave única de identificação da foto da selfie do titular da conta. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36         |
| **lang**                   | string | Coordenada de longitude da geolocalização do assinante capturada no momento da assinatura.                  | -          |
| **lat**                    | string | Coordenada de latitude da geolocalização do assinante capturada no momento da assinatura.                   | -          |
| **ip_address**             | string | Endereço IP do dispositivo do assinante.     | -          |
| **session_id**             | string | ID da seção do assinante no momento da assinatura.                | -          |

### Objeto signer
| Campo                 | Tipo   | Descrição                                 | Caracteres                        |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** *            | string | Nome do assinante.                        | -                                 |
| **email** *           | string | Email do assinante.                       | -                                 |
| **phone** *           | object | Objeto com dados do telefone do assinante | **[Objeto phone](#objeto-phone)** |
| **document_number** * | string | CPF do assinante.                         | 11                                |

### Objeto phone 

| Campo | Descrição | Exemplo |  Máx. Caracteres | 
| --- | --- | --- | --- | 
|`country_code` *| string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 | 
| `area_code` *| string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |Número de telefone (apenas números) |  10 |

## Response

STATUS 200

**Response Body**

```json
{
  "data": {
    "account_info": {
      "account_branch": "0001",
      "account_digit": "3",
      "account_number": "66777",
      "financial_institution_code": "329"
    },
    "account_manager": {
      "company_representatives": [
        {
          "document_number": "08141163701",
          "name": "Aurora Simone Catarina Nogueira"
        }
      ],
      "document_number": "09456933000162",
      "name": "Kaique e Giovanna Contábil ME"
    },
    "account_owner": {
      "company_representatives": [
        {
          "document_number": "38689533370",
          "name": "Priscila Rayssa Barros"
        },
        {
          "document_number": "85324558400",
          "name": "Caio Bruno Dias"
        }
      ],
      "document_number": "98916615000167",
      "name": "Alice e Isis Advocacia ME"
    },
    "allowed_transfer_account_list": [
      {
        "account_branch": "0001",
        "account_digit": "2",
        "account_number": "532312",
        "document_number": "49067117153",
        "financial_institution": {
          "code": 341,
          "ispb": 60701190,
          "name": "Itaú Unibanco  S.A."
        },
        "name": "Juan Anthony Farias"
      },
      {
        "account_branch": "0002",
        "account_digit": "9",
        "account_number": "537612",
        "document_number": "39063217000123",
        "financial_institution": {
          "code": 33,
          "ispb": 90400888,
          "name": "Banco Santander (Brasil) S. A."
        },
        "name": "Farias Advogados"
      }
    ],
    "allowed_user": {
      "document_number": "13708610440",
      "name": "Renato Noah Pinto"
    }
  },
  "event_datetime": "2019-11-07 18:15:07",
  "key": "61341599-790b-4236-b42f-060634eba88f",
  "status": "waiting_administrator_approval",
  "webhook_type": "escrow"
}
```

STATUS 400

**Response Body**

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

---

# Introdução

URL: /documentation/contas/abertura_de_conta_escrow/introducao

As contas de livre movimentação são quaisquer contas bancárias cujo saldo pode ser sacado movimentado pelo cliente, no todo ou em parte.

Abertura de conta
Assim como a emissão de dívidas, a solicitação de abertura de conta é feita com uma única chamada (não esquecendo que os documentos devem ser previamente enviados).

Recebido esse pedido de conta a QI Tech é responsável por executar o compliance e abrir a conta. Na prática:

1 - Solicitação da abertura de conta (solicitado via request)

2 - Validação de compliance (informado resultado via webhook)

3 - Abertura da conta (informado resultado via webhook)

---

# Abertura de conta PF

URL: /documentation/contas/abertura_de_conta/abertura_de_conta_pf

## Request

ENDPOINT /account
MÉTODO POST

Request Body

```json
{
	"account_owner": {
		"address": {
			"street": "Av. Brigadeiro Faria Lima",
			"state": "SP",
			"city": "São Paulo",
			"neighborhood": "Jardim Paulistano",
			"number": "2391",
			"postal_code": "01452905",
			"complement": "1o. Andar"
		},
		"birth_date": "1990-05-06",
		"document_identification": "3c24579b-9810-4fa6-9b08-fe67d237160a",
		"email": "api@qitech.com.br",
		"individual_document_number": "34651104630",
		"is_pep": false,
		"mother_name": "Maria Mariane",
		"name": "Qi Tech Ltda.",
		"nationality": "nationality",
		"person_type": "natural",
		"phone": {
			"country_code": "055",
			"area_code": "11",
			"number": "999999999"
		},
		"proof_of_residence": "780456bd-1eec-4e5f-82c0-d8c3921497ea"
	},
	"signed_contract": {
        "document_key": "4d7f4e29-4b58-4905-9a69-b1f9215263f5",
        "signatures": [
            {
                "authenticity": {
                    "timestamp": "1970-01-01T00:00:01.080100Z",
                    "facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
                    "lang": "-35.8916627",
                    "lat": "-7.2226067",
                    "ip_address": "177.51.1.000",
                    "session_id": "jdifj329842"
                },
                "signer": {
                    "name": "IVANILDO DE SENA LIMA",
                    "email": "teste@gmail.com",
                    "phone": {
                        "country_code": "055",
                        "area_code": "11",
                        "number": "999999999"
                    },
                    "document_number": "99999999999"
                },
                "authentication_type": "opt-in"
            }
        ]
    }
}
```

:::info Copiando e Colando o Payload de exemplo
Antes de iniciar os testes, a document_key do campo document_identification deve ser substituida pela chave retornada no upload de documentos dos titulares da conta.
:::

:::info Mock de CPF/CNPJ
Para simular situações de aprovação, reprovação e analise manual pode ser utilizado o primeiro digito do CPF/CNPJ do owner da conta:

0 à 7 -> Análise Manual

8 -> Reprovação Automática

9 -> Aprovação Automática
:::

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---|---|
| `account_owner` | object  | Objeto Dono da conta |**[Objeto account_owner](#objeto-account_owner)**  |
| `signed_contract` *| object | Objeto contento as informações da assinatura do contrato. | **[Objeto signed_contract](#objeto-signed_contract)** |

### Objeto account_owner

| Campo | Tipo | Descrição | Caracteres |
|---| ---| ---| ---| 
| `address` | string | Endereço do cliente. | **[Objeto adress](#objeto-address)** |  |
| `birth_date` * | string |  Data de nascimento da pessoa (formato "AAAA-MM-DD") |  |
| `document_identification` * | string |  DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) |  |
| `document_identification_back` * | string |  DOCUMENT_KEY do PDF do verso documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) |  |
| `document_identification_type` * | string |  Tipo do documento enviado previamente (RG ou CNH) |  |
| `email` * | string |  Email do cliente. |  |
| `individual_document_number` | string | CPF da pessoa (apenas números). Limitado a 11 caracteres. |  |
| `is_pep` * | string |  Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep).|  |
| `mother_name` * | string |  Nome da mãe do cliente em caso de PF. | 100 |
| `name` * | string |  Razão social em caso de operações PJ ou Nome da pessoa em caso de operações PF. | 100 |
| `nationality` * | string |  Nacionalidade do cliente. | 50 |
| `person_type` * | string | Identificador de que o objeto enviado é uma pessoa física ou jurídica.|  |
| `phone` | string | Objeto com dados do telefone | **[Objeto phone](#objeto-phone)**|
| `proof_of_residence` | string |  DOCUMENT_KEY do PDF do comprovante de endereço do endereço enviado (enviado previamente).| |

### Objeto address 

Este objeto, presente tanto no objeto PF quanto no objeto PJ, é um simples objeto para representar um endereço.

| Campo | Descrição | Exemplo |  Máx. Caracteres | 
|---|---|---|---| 
| `street` *| string | Rua do endereço  | 100 |
| `state` *| string | Estado do endereço (com dois caracteres maiúsculos) | 2 |
| `city` *| string | Cidade do endereço | 100 |
| `neighborhood` *| string |Bairro do endereço | 100 |
| `number` *| string | Número da rua | 10 |
| `postal_code` *| string |CEP do endereço (http://www.buscacep.correios.com.br/sistemas/buscacep/) (apenas números) |  8 |
| `complement` *| string |Complemento do endereço (texto livre) | 100 |

### Objeto signed_contract 
| Campo | Tipo   | Descrição        | Caracteres    |
|-------|--------|------------------|---------------|
| **document_key** * | uuidv4 | Chave única de identificação do documento do **Termo de Abertura de Conta** ou **Contrato de Conta Escrow**. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36            |
| **signatures** *   | list   | Dados de assinatura do documento enviado. Cada item da lista, corresponde a um assinante do documento.      | [Objeto signatures](#objeto-signatures) |

### Objeto signatures
| Campo | Tipo       | Descrição         | Caracteres        |
|-------|------------|-------------------|-------------------|
| **authenticity** * | object     | Conjunto de dados que evidenciam a assinatura eletrônica realizada pelo assinante. | [Objeto authenticity](#objeto-authenticity) |
| **signer** * | object     | Objeto contendo os dados de um dos assinantes do documento.           | [Objeto signer](#objeto-signer)|
| **authentication_type** * | enumerator | Tipo de assinatura. Sempre será "**opt-in**"| "**opt-in**"                   |

### Objeto authenticity
| Campo | Tipo   | Descrição               | Caracteres |
|-------|--------|-------------------------|------------|
| **timestamp** *            | string | Data e hora do momento da assinatura do documento.                | 27         |
| **facial_recognition_key** | uuidv4 | Chave única de identificação da foto da selfie do titular da conta. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36         |
| **lang**                   | string | Coordenada de longitude da geolocalização do assinante capturada no momento da assinatura.                  | -          |
| **lat**                    | string | Coordenada de latitude da geolocalização do assinante capturada no momento da assinatura.                   | -          |
| **ip_address**             | string | Endereço IP do dispositivo do assinante.     | -          |
| **session_id**             | string | ID da seção do assinante no momento da assinatura.                | -          |

### Objeto signer
| Campo                 | Tipo   | Descrição                                 | Caracteres                        |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** *            | string | Nome do assinante.                        | -                                 |
| **email** *           | string | Email do assinante.                       | -                                 |
| **phone** *           | object | Objeto com dados do telefone do assinante | **[Objeto phone](#objeto-phone)** |
| **document_number** * | string | CPF do assinante.                         | 11                                |

### Objeto phone 

| Campo | Descrição | Exemplo |  Máx. Caracteres | 
| --- | --- | --- | --- | 
|`country_code` *| string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 | 
| `area_code` *| string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |Número de telefone (apenas números) |  10 |

## Response

STATUS 200

Response Body

```json
{
  "data": {
    "account_info": {
      "account_branch": "0001",
      "account_digit": "3",
      "account_number": "70091",
      "financial_institution_code": "329",
      "account_key": "7986dcc7-4331-478f-af47-adfbdf7f4a36"
    },
    "account_owner": {
      "document_number": "08141163701",
      "name": "Aurora Simone Catarina Nogueira"
    }
  },
  "event_datetime": "2019-11-04 16:34:41",
  "key": "f834af4d-ab4b-442f-96c9-f9940d8066d4",
  "status": "pending_kyc_analysis",
  "webhook_type": "account"
}
```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

---

# Abertura de conta PJ

URL: /documentation/contas/abertura_de_conta/abertura_de_conta_pj

## Abertura de conta PJ com autenticação de dois fatores (2FA)

### Request

ENDPOINT /account
MÉTODO POST

Request Body

```json
{
	"account_owner": {
		"address": {
			"city": "Caraguatatuba",
			"complement": "complemento",
			"neighborhood": "Jaraguazinho",
			"number": "924",
			"postal_code": "11675200",
			"state": "SP",
			"street": "Praça Jorge Vitório de Souza"
		},
		"cnae_code": "4721-1/02",
		"company_statute": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
		"company_document_number": "46073462000130",
		"company_type": "ltda",
		"email": "marcos.alves@yopmail.com",
		"foundation_date": "2017-09-16",
		"name": "NOME DA EMPRESA",
		"person_type": "legal",
		"phone": {
			"area_code": "19",
			"country_code": "055",
			"number": "988888888"
		},
		"trading_name": "Pães e Doces",
		"company_representatives": [{
			"name": "Marcos Felipe Henrique Alves",
			"address": {
				"city": "Recife",
				"complement": null,
				"neighborhood": "Fundão",
				"number": "137",
				"postal_code": "52221110",
				"state": "PE",
				"street": "Rua Camapuã"
			},
			"email": "marcos.alves@yopmail.com",
			"birth_date": "1972-02-02",
			"individual_document_number": "08531309069",
			"document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
			"document_identification_number": "339122924",
			"is_pep": false,
			"final_beneficiary": true,
			"marital_status": "single",
			"mother_name": "Sueli Isadora Alves",
			"nationality": "Brasileira",
			"person_type": "natural",
			"phone": {
				"area_code": "88",
				"country_code": "055",
				"number": "995924634"
			}
		}]
	},
	"account_manager": {
		"address": {
			"city": "São Paulo",
			"complement": "s/c",
			"neighborhood": "Pinheiros",
			"number": "215",
			"postal_code": "05427000",
			"state": "SP",
			"street": "Rua Gilberto Sabino"
		},
		"cnae_code": "4721-1/02",
		"company_statute": "39e2bf16-26fc-4684-b4c0-97e46029e916",
		"company_document_number": "35082434000162",
		"company_type": "ltda",
		"email": "partneremail@partner.com",
		"foundation_date": "2018-09-16",
		"name": "Razão Social do Parceiro",
		"person_type": "legal",
		"phone": {
			"area_code": "11",
			"country_code": "055",
			"number": "987791122"
		},
		"trading_name": "Parceiro QI",
		"company_representatives": [{
			"name": "Nome do Socio da Empresa Parceira",
			"address": {
				"city": "São Paulo",
				"complement": null,
				"neighborhood": "Pinheiros",
				"number": "45",
				"postal_code": "04758001",
				"state": "SP",
				"street": "Rua do sócio"
			},
			"email": "nomesocio@partner.com",
			"birth_date": "1972-02-02",
			"individual_document_number": "34527070835",
			"document_identification": "ceca505b-b5ef-4e0b-ab62-a6e03d8d636a",
			"document_identification_number": "368335446",
            "document_identification_type": "rg",
			"is_pep": false,
			"final_beneficiary": true,
			"marital_status": "single",
			"mother_name": "Mãe do sócio",
			"nationality": "Brasileira",
			"person_type": "natural",
			"phone": {
				"area_code": "11",
				"country_code": "055",
				"number": "915185434"
			}
		}]
	},
	"allowed_user": {
		"email": "nomegerente@partner.com",
		"individual_document_number": "34651104630",
		"name": "Luiz Alberto Da Silva",
		"person_type": "natural",
		"phone": {
			"country_code": "055",
			"area_code": "11",
			"number": "991611135"
		}
	},
	"signed_contract": {
        "document_key": "4d7f4e29-4b58-4905-9a69-b1f9215263f5",
        "signatures": [
            {
                "authenticity": {
                    "timestamp": "1970-01-01T00:00:01.080100Z",
                    "facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
                    "lang": "-35.8916627",
                    "lat": "-7.2226067",
                    "ip_address": "177.51.1.000",
                    "session_id": "jdifj329842"
                },
                "signer": {
                    "name": "IVANILDO DE SENA LIMA",
                    "email": "teste@gmail.com",
                    "phone": {
                        "country_code": "055",
                        "area_code": "11",
                        "number": "999999999"
                    },
                    "document_number": "99999999999"
                },
                "authentication_type": "opt-in"
            }
        ]
    }
}
```

## Abertura de conta PJ

### Request

ENDPOINT /account
MÉTODO POST

Request Body

```json
{
	"account_owner": {
		"address": {
			"city": "Caraguatatuba",
			"complement": "complemento",
			"neighborhood": "Jaraguazinho",
			"number": "924",
			"postal_code": "11675200",
			"state": "SP",
			"street": "Praça Jorge Vitório de Souza"
		},
		"cnae_code": "4721-1/02",
		"company_statute": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
		"company_document_number": "46073462000130",
		"company_type": "ltda",
		"email": "marcos.alves@yopmail.com",
		"foundation_date": "2017-09-16",
		"name": "NOME DA EMPRESA",
		"person_type": "legal",
		"phone": {
			"area_code": "19",
			"country_code": "055",
			"number": "988888888"
		},
		"trading_name": "Pães e Doces",
		"company_representatives": [{
			"name": "Marcos Felipe Henrique Alves",
			"address": {
				"city": "Recife",
				"complement": null,
				"neighborhood": "Fundão",
				"number": "137",
				"postal_code": "52221110",
				"state": "PE",
				"street": "Rua Camapuã"
			},
			"email": "marcos.alves@yopmail.com",
			"birth_date": "1972-02-02",
			"individual_document_number": "08531309069",
			"document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
			"document_identification_number": "339122924",
			"is_pep": false,
			"final_beneficiary": true,
			"marital_status": "single",
			"mother_name": "Sueli Isadora Alves",
			"nationality": "Brasileira",
			"person_type": "natural",
			"phone": {
				"area_code": "88",
				"country_code": "055",
				"number": "995924634"
			}
		}]
	},
	"account_manager": {
		"address": {
			"city": "São Paulo",
			"complement": "s/c",
			"neighborhood": "Pinheiros",
			"number": "215",
			"postal_code": "05427000",
			"state": "SP",
			"street": "Rua Gilberto Sabino"
		},
		"cnae_code": "4721-1/02",
		"company_statute": "39e2bf16-26fc-4684-b4c0-97e46029e916",
		"company_document_number": "35082434000162",
		"company_type": "ltda",
		"email": "partneremail@partner.com",
		"foundation_date": "2018-09-16",
		"name": "Razão Social do Parceiro",
		"person_type": "legal",
		"phone": {
			"area_code": "11",
			"country_code": "055",
			"number": "987791122"
		},
		"trading_name": "Parceiro QI",
		"company_representatives": [{
			"name": "Nome do Socio da Empresa Parceira",
			"address": {
				"city": "São Paulo",
				"complement": null,
				"neighborhood": "Pinheiros",
				"number": "45",
				"postal_code": "04758001",
				"state": "SP",
				"street": "Rua do sócio"
			},
			"email": "nomesocio@partner.com",
			"birth_date": "1972-02-02",
			"individual_document_number": "34527070835",
			"document_identification": "ceca505b-b5ef-4e0b-ab62-a6e03d8d636a",
			"document_identification_number": "368335446",
            "document_identification_type": "rg",
			"is_pep": false,
			"final_beneficiary": true,
			"marital_status": "single",
			"mother_name": "Mãe do sócio",
			"nationality": "Brasileira",
			"person_type": "natural",
			"phone": {
				"area_code": "11",
				"country_code": "055",
				"number": "915185434"
			}
		}]
	},
	"allowed_user": {
        "email": "teste@email.com",
        "individual_document_number": "99999999999",
        "name": "Luiz Alberto ",
        "person_type": "natural",
        "phone": {
            "country_code": "055",
            "area_code": "12",
            "number": "999999999"
        }
    },
	"signed_contract": {
        "document_key": "4d7f4e29-4b58-4905-9a69-b1f9215263f5",
        "signatures": [
            {
                "authenticity": {
                    "timestamp": "1970-01-01T00:00:01.080100Z",
                    "facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
                    "lang": "-35.8916627",
                    "lat": "-7.2226067",
                    "ip_address": "177.51.1.000",
                    "session_id": "jdifj329842"
                },
                "signer": {
                    "name": "IVANILDO DE SENA LIMA",
                    "email": "teste@gmail.com",
                    "phone": {
                        "country_code": "055",
                        "area_code": "11",
                        "number": "999999999"
                    },
                    "document_number": "99999999999"
                },
                "authentication_type": "opt-in"
            }
        ]
    }
}
```

:::info Copiando e Colando o Payload de exemplo
Antes de iniciar os testes, as document_keys(UUIDs) dos campos company_statute e document_identification devem ser substituidas pelas chaves retornadas no upload de documentos dos titulares da conta.
:::

:::info Mock de CPF/CNPJ
Para simular situações de aprovação, reprovação e analise manual pode ser utilizado o primeiro digito do CPF/CNPJ do owner da conta:

0 à 7 -> Análise Manual

8 -> Reprovação Automática

9 -> Aprovação Automática
:::

### Response

STATUS 200

Response Body

```json
{
  "data": {
    "account_info": {
      "account_branch": "0001",
      "account_digit": "3",
      "account_number": "5283431",
      "financial_institution_code": "329"
    },
    "account_owner": {
      "document_number": "46073462000130",
      "name": "NOME DA EMPRESA"
    },
    "allowed_user": {
      "document_number": "34651104630",
      "name": "Luiz Alberto Da Silva"
    }
  },
  "event_datetime": "2023-05-05 14:48:32",
  "key": "5b5371ae-279c-4aa7-bc1c-776e01fea7cf",
  "status": "pending_kyc_analysis",
  "webhook_type": "account"
}
```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

### Request Body Params

| Campo                 | Tipo   | Descrição                                                                    | Caracteres                                            |
|-----------------------|--------|------------------------------------------------------------------------------|-------------------------------------------------------|
| **account_owner** *   | object | Objeto Dono da conta                                                         | **[Objeto account_owner](#objeto-account_owner)**     |
| **allowed_user** *    | object | Usuário vinculado a conta.                                                   | **[Objeto allowed_user](#objeto-allowed_user)**       |
| **account_manager**   | object | Dados do parceiro integrador que realizará a movimentação da conta via API.  | **[Objeto account_manager](#objeto-account_manager)** |
| `signed_contract` *| object | Objeto contento as informações da assinatura do contrato. | **[Objeto signed_contract](#objeto-signed_contract)** |

### Objeto account_owner

| Campo                         | Tipo   | Descrição                                                                                                                         | Caracteres                                                            |
|-------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
| **address** *                 | object | Objeto endereço do titular da conta                                                                                               | **[Objeto address](#objeto-address)**                                 |
| **cnae_code** *               | string | Classificação Nacional de Atividades Econômicas                                                                                   | 9                                                                     |
| **company_document_number** * | string | CNPJ                                                                                                                              | 14                                                                    |
| **company_statute** *         | string | DOCUMENT_KEY do PDF do estatuto da empresa (enviado previamente).                                                                 | 36                                                                    |
| **company_type**              | enum   | Tipo da empresa                                                                                                                   | **[Enumeradores company_type](#enumeradores-company_type)**           |
| **company_representatives** * | list   | Lista dos representantes legais da empresa                                                                                        | **[Objeto company_representatives](#objeto-company_representatives)** |
| **email** *                   | string | Email institucional da empresa.                                                                                                   | 254                                                                   |
| **foundation_date** *         | string | Data de abertura da empresa (formato "AAAA-MM-DD").                                                                               | 10                                                                    |
| **name** *                    | string | Razão social.                                                                                                                     | 100                                                                   |
| **person_type** *             | enum   | Identificador de que o objeto enviado é uma pessoa jurídica. Deve conter SEMPRE o valor "legal" para Objeto PJ.                   | **[Enumeradores person_type](#enumeradores-person_type)**             |
| **phone** *                   | object | Telefone do titular da conta.                                                                                                     | **[Objeto phone](#objeto-phone)**                                     | - |
| **trading_name** *            | string | Nome fantasia.                                                                                                                    | 200                                                                   |

### Objeto allowed_user

| Campo                            | Tipo   | Descrição                                                                                        | Caracteres                                                 |
|----------------------------------|--------|--------------------------------------------------------------------------------------------------|------------------------------------------------------------|
| **email** *                      | string | Email do usuário da conta.                                                                       | 254                                                        |
| **individual_document_number** * | string | CPF do usuário da conta (apenas números).                                                        | 11                                                         |
| **name** *                       | string | Nome do usuário da conta.                                                                        | 100                                                        |
| **person_type** *                | enum   | Identificador de que o objeto enviado é uma pessoa física. Deve conter SEMPRE o valor "natural". | **[Enumeradores person_type](#enumeradores-person_type)**  |
| **phone**                        | object | Telefone do usuário.                                                                             | **[Objeto phone](#objeto-phone)**                          |

### Objeto account_manager

| Campo                         | Tipo   | Descrição                                                                                                                         | Caracteres                                                             |
|-------------------------------|--------|-----------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------|
| **address** *                 | object | Objeto endereço do parceiro integrador                                                                                            | **[Objeto address](#objeto-address)**                                  |
| **cnae_code** *               | string | Classificação Nacional de Atividades Econômicas                                                                                   | 9                                                                      |
| **company_document_number** * | string | CNPJ                                                                                                                              | 14                                                                     |
| **company_statute** *         | string | DOCUMENT_KEY do PDF do estatuto da empresa (enviado previamente).                                                                 | 36                                                                     |
| **company_type**              | enum   | Tipo da empresa                                                                                                                   | **[Enumeradores company_type](#enumeradores-company_type)**            |
| **company_representatives** * | list   | Lista dos representantes legais da empresa                                                                                        | **[Objeto company_representatives](#objeto-company_representatives)**  |
| **email** *                   | string | Email institucional da empresa.                                                                                                   | 254                                                                    |
| **foundation_date** *         | string | Data de abertura da empresa (formato "AAAA-MM-DD").                                                                               | 10                                                                     |
| **name** *                    | string | Razão social.                                                                                                                     | 100                                                                    |
| **person_type** *             | enum   | Identificador de que o objeto enviado é uma pessoa jurídica. Deve conter SEMPRE o valor "legal" para Objeto PJ.                   | **[Enumeradores person_type](#enumeradores-person_type)**              |
| **phone** *                   | object | Telefone do parceiro integrador.                                                                                                  | **[Objeto phone](#objeto-phone)**                                      |
| **trading_name** *            | string | Nome fantasia.                                                                                                                    | 200                                                                    |

### Objeto company_representatives

| Campo                              | Tipo    | Descrição                                                                                              | Caracteres                                                                              |
|------------------------------------|---------|--------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
| **name** *                         | string  | Nome do representante da empresa                                                                       | 100                                                                                     |
| **address** *                      | object  | Objeto endereço do representante da empresa                                                            | **[Objeto address](#objeto-address)**                                                   |
| **email** *                        | string  | Email do representante da empresa                                                                      | 254                                                                                     |
| **birth_date** *                   | string  | Data de nascimento representante da empresa (formato "AAAA-MM-DD")                                     | 10                                                                                      |
| **individual_document_number** *   | string  | CPF do representante da empresa (apenas números).                                                      | 11                                                                                      |
| **document_identification**        | string  | DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) | 36                                                                                      |
| **document_identification_number** | string  | Número do documento de identificação com foto da pessoa (RG ou CNH)                                    | 16                                                                                      |
| **is_pep** *                       | boolean | Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep).          | -                                                                                       |
| **final_beneficiary**              | boolean | Declaração se o representante é beneficiário final da empresa.                                         | -                                                                                       |
| **marital_status**                 | enum    | Estado civil do representante da empresa                                                               | **[Enumeradores marital status](#enumeradores-marital_status)**                         |
| **mother_name** *                  | string  | Nome da mãe do representante da empresa                                                                | 100                                                                                     |
| **nationality**                    | string  | Nacionalidade do representante da empresa                                                              | 50                                                                                      |
| **person_type** *                  | enum    | Identificador de que o objeto enviado é uma pessoa física                                              | **[Enumeradores person_type](#enumeradores-person_type)**                               |
| **phone** *                        | object  | Objeto com dados do telefone do representante da empresa                                               | **[Objeto phone](#objeto-phone)**                                                       |

### Objeto address

Este objeto, presente tanto no objeto PF quanto no objeto PJ, é um simples objeto para representar um endereço.

| Campo              | Descrição | Exemplo                                                                                   | Caracteres |
|--------------------|-----------|-------------------------------------------------------------------------------------------|------------|
| **street** *       | string    | Rua do endereço                                                                           | 500        |
| **state** *        | enum      | Estado do endereço (com dois caracteres maiúsculos)                                       | 2          |
| **city** *         | string    | Cidade do endereço                                                                        | 255        |
| **neighborhood** * | string    | Bairro do endereço                                                                        | 500        |
| **number** *       | string    | Número da rua                                                                             | 10         |
| **postal_code** *  | string    | CEP do endereço (http://www.buscacep.correios.com.br/sistemas/buscacep/) (apenas números) | 8          |
| **complement**     | string    | Complemento do endereço (texto livre)                                                     | 500        |

### Objeto signed_contract 
| Campo | Tipo   | Descrição        | Caracteres    |
|-------|--------|------------------|---------------|
| **document_key** * | uuidv4 | Chave única de identificação do documento do **Termo de Abertura de Conta** ou **Contrato de Conta Escrow**. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36            |
| **signatures** *   | list   | Dados de assinatura do documento enviado. Cada item da lista, corresponde a um assinante do documento.      | [Objeto signatures](#objeto-signatures) |

### Objeto signatures
| Campo | Tipo       | Descrição         | Caracteres        |
|-------|------------|-------------------|-------------------|
| **authenticity** * | object     | Conjunto de dados que evidenciam a assinatura eletrônica realizada pelo assinante. | [Objeto authenticity](#objeto-authenticity) |
| **signer** * | object     | Objeto contendo os dados de um dos assinantes do documento.           | [Objeto signer](#objeto-signer)|
| **authentication_type** * | enumerator | Tipo de assinatura. Sempre será "**opt-in**"| "**opt-in**"                   |

### Objeto authenticity
| Campo | Tipo   | Descrição               | Caracteres |
|-------|--------|-------------------------|------------|
| **timestamp** *            | string | Data e hora do momento da assinatura do documento.                | 27         |
| **facial_recognition_key** | uuidv4 | Chave única de identificação da foto da selfie do titular da conta. (A DOCUMENT_KEY é retornada na resposta do endpoint de [Upload de documentos](./upload_de_documentos)) | 36         |
| **lang**                   | string | Coordenada de longitude da geolocalização do assinante capturada no momento da assinatura.                  | -          |
| **lat**                    | string | Coordenada de latitude da geolocalização do assinante capturada no momento da assinatura.                   | -          |
| **ip_address**             | string | Endereço IP do dispositivo do assinante.     | -          |
| **session_id**             | string | ID da seção do assinante no momento da assinatura.                | -          |

### Objeto signer
| Campo                 | Tipo   | Descrição                                 | Caracteres                        |
|-----------------------|--------|-------------------------------------------|-----------------------------------|
| **name** *            | string | Nome do assinante.                        | -                                 |
| **email** *           | string | Email do assinante.                       | -                                 |
| **phone** *           | object | Objeto com dados do telefone do assinante | **[Objeto phone](#objeto-phone)** |
| **document_number** * | string | CPF do assinante.                         | 11                                |

### Objeto phone 

| Campo | Descrição | Exemplo |  Máx. Caracteres | 
| --- | --- | --- | --- | 
|`country_code` *| string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 | 
| `area_code` *| string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |Número de telefone (apenas números) |  10 |

### Enumeradores person_type
| Enum        | Description       |
|-------------|-------------------|
| **natural** | Pessoa física     |
| **legal**   | Pessoa jurídica   |

### Enumeradores document_identification_type
| Enum    | Description                            |
|---------|----------------------------------------|
| **rg**  | RG - Registro Geral                    |
| **cnh** | CNH - Carteira Nacional de Habilitação |

### Enumeradores company_type
| Enum                       | 	Description                                                             |
|----------------------------|--------------------------------------------------------------------------|
| **ltda**                   | Limitada                                                                |
| **sa**	                    | Sociedade Anônima                                                        |
| **micro_enterprise**	      | Micro Empresa                                                            |
| **freelancer**             | Freelancer                                                              |
| **sa_opened**              | Sociedade Anônima de Capital Aberto                                     |
| **sa_closed**	             | Sociedade Anônima de Capital Fechado                                     |
| **se_ltda**                | Sociedade Empresária Limitada                                           |
| **se_cn**                  | Sociedade Empresária em Nome Coletivo                                   |
| **se_cs**                  | Sociedade Empresária em Comandita Simples                               |
| **se_ca**	                 | Sociedade Empresária em Comandita por Ações                              |
| **scp**                    | Sociedade em Conta de Participação                                      |
| **ei**	                    | Empresário Individual                                                    |
| **ese**	                   | Estabelecimento, no Brasil, de Sociedade Estrangeira                     |
| **eeab**	                  | Estabelecimento, no Brasil, de Empresa Binacional Argentino-Brasileira   |
| **ssp**                    | Sociedade Simples Pura                                                  |
| **ss_ltda**	               | Sociedade Simples Limitada                                               |
| **ss_cn**                  | Sociedade Simples em Nome Coletivo                                      |
| **ss_cs**                  | Sociedade Simples em Comandita Simples                                  |
| **eireli_ne**              | Empresa Individual de Responsabilidade Limitada (de Natureza Empresária) |
| **eireli_ns**              | Empresa Individual de Responsabilidade Limitada (de Natureza Simples)   |
| **eireli**                 | Empresa de Responsabilidade Individual                                  |
| **mei**                    | Micro Empreendedor Individual                                            |
| **me**	                    | Micro Empresa                                                            |
| **cop**	                   | Cooperativa                                                              |
| **private_association**	   | Sociedade Privada                                                        |

### Enumeradores marital_status
| Enum         | 	Description  |
|--------------|---------------|
| **single**   | Solteiro(a)   |
| **married**  | Casado(a)    |
| **widower**  | Viúvo(a)     |
| **divorced** | Divorciado(a) |
| **separated** | Separado(a) |

---

# Rascunho de Conta Livre Movimentação - Pessoa Jurídica

URL: /documentation/contas/abertura_de_conta/draft_checking_legal_person

O fluxo Draft Checking Legal Person permite criar uma solicitação de abertura de conta em duas etapas:

1. **POST**: Cria um draft (rascunho) com **flexibilidade máxima** - aceita desde dados mínimos até dados completos
2. **PATCH**: Submete o draft para processamento, **validando completude** de todos os campos obrigatórios

**Importante**: Este fluxo está sendo preparado para integração com **Monte Bravo**. A divisão de campos entre POST e PATCH será ajustada após alinhamento com Monte Bravo sobre quais dados estarão disponíveis em cada momento do processo.

## Criar Draft de Conta PJ

### Request

ENDPOINT /v2/account_request/draft_checking_legal_person
MÉTODO POST

### Descrição

Este endpoint cria um **draft** de abertura de conta para Pessoa Jurídica (Legal Person). O POST aceita **desde dados mínimos até dados completos**, oferecendo máxima flexibilidade.

### Estratégia de Flexibilidade

- **Dados mínimos**: CNPJ + Nome + Tipo de pessoa
- **Dados parciais**: Adicione campos conforme disponíveis
- **Dados completos**: Envie tudo de uma vez (menos comum)

### Exemplo 1: Payload MÍNIMO (apenas obrigatórios)

Request Body

```json
{
  "account_owner": {
    "company_document_number": "46073462000130",
    "name": "EMPRESA EXEMPLO TECNOLOGIA LTDA",
    "person_type": "legal"
  }
}
```

```json
{
  "request_control_key": "3571e292-3a83-4011-904d-20ee963022ef",
  "account_owner": {
    "company_document_number": "46073462000130",
    "name": "EMPRESA EXEMPLO TECNOLOGIA LTDA",
    "person_type": "legal"
  }
}
```

**Comportamento**: Se o mesmo `request_control_key` for usado novamente, retorna erro 409 (Conflict) ao invés de criar um novo draft.

### Exemplo 2: Payload COMPLETO (todos os dados de uma vez)

Request Body

```json
{
  "account_owner": {
    "company_document_number": "46073462000130",
    "name": "EMPRESA EXEMPLO TECNOLOGIA LTDA",
    "person_type": "legal",
    "email": "empresa@exemplo.com.br",
    "phone": {
      "country_code": "055",
      "area_code": "11",
      "number": "999999999"
    },
    "trading_name": "Empresa Exemplo",
    "company_type": "LTDA",
    "foundation_date": "2010-01-15",
    "cnae_code": "6209-1/00",
    "company_statute": "92c93e9e-b249-46b7-8c2e-95d4955a3c39",
    "monthly_revenue": 150000.00,
    "address": {
      "street": "Av. Brigadeiro Faria Lima",
      "state": "SP",
      "city": "São Paulo",
      "neighborhood": "Jardim Paulistano",
      "number": "2391",
      "postal_code": "01452905",
      "complement": "Conjunto 102"
    },
    "company_representatives": [
      {
        "name": "João Carlos da Silva",
        "email": "joao.silva@exemplo.com.br",
        "birth_date": "1985-03-20",
        "individual_document_number": "12345678901",
        "is_pep": false,
        "final_beneficiary": true,
        "mother_name": "Maria da Silva",
        "nationality": "brasileira",
        "person_type": "natural",
        "phone": {
          "country_code": "055",
          "area_code": "11",
          "number": "988888888"
        },
        "address": {
          "street": "Rua das Flores",
          "state": "SP",
          "city": "São Paulo",
          "neighborhood": "Jardins",
          "number": "123",
          "postal_code": "01310100",
          "complement": "Apto 45"
        },
        "representative_relationship": "ceo",
        "gender": "male",
        "marital_status": "married",
        "documents": {
          "cnh": {
            "ocr_key": "7a73be1a-0b66-4c0a-932a-1d1d02efdc4c"
          }
        }
      }
    ]
  }
}
```

### Response

STATUS 201

Response Body

```json
{
  "account_request_key": "abc123-def456-...",
  "account_request_status": "draft",
  "account_info": {
    "account_number": "1638634",
    "account_digit": "3",
    "account_branch": "0001"
  }
}
```

:::warning Atenção
O campo `account_request_key` deve ser armazenado e será utilizado para submeter o draft via PATCH.
:::

### Request Body Params

| Campo                         | Tipo   | Descrição                                                                    | Caracteres                                                         |
|-------------------------------|--------|------------------------------------------------------------------------------|---------------------------------------------------------------------|
| `request_control_key`         | string | UUID para garantir idempotência (36 caracteres)                             | 36                                                                  |
| `reserved_account_key`        | string | UUID de conta reservada previamente (36 caracteres)                          | 36                                                                  |
| `account_owner` *             | object | Informações do titular da conta (Pessoa Jurídica)                           | **[Objeto account_owner](#objeto-account_owner-post)**            |

### Objeto account_owner (POST)

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `company_document_number` * | string | CNPJ da empresa (14 dígitos, apenas números) | 14 |
| `name` * | string | Razão social da empresa | 100 |
| `person_type` * | enum | Tipo de pessoa (sempre "legal") | **[Enumeradores person_type](#enumeradores-person_type)** |
| `email` | string | Email da empresa (formato email válido) | 254 |
| `phone` | object | Telefone da empresa | **[Objeto phone](#objeto-phone)** |
| `trading_name` | string | Nome fantasia | 200 |
| `company_type` | enum | Tipo societário | **[Enumeradores company_type](#enumeradores-company_type)** |
| `foundation_date` | string | Data de fundação (formato: YYYY-MM-DD) | 10 |
| `cnae_code` | string | Código CNAE da atividade | 9 |
| `company_statute` | string | UUID do estatuto social (formato UUID) | 36 |
| `monthly_revenue` | number | Faturamento mensal | - |
| `address` | object | Endereço completo da empresa | **[Objeto address](#objeto-address)** |
| `company_representatives` | array | Lista de representantes legais (mínimo 1 item se enviado) | **[Objeto company_representatives](#objeto-company_representatives)** |

:::info Campos Obrigatórios no POST
Apenas 3 campos são obrigatórios no POST:
- `company_document_number`
- `name`
- `person_type`

Todos os demais campos são opcionais e podem ser enviados conforme disponibilidade.
:::

:::warning Validação de Representantes
Se `company_representatives` for enviado no POST, deve ter **pelo menos 1 item** (`minItems: 1`). Cada representante deve ter todos os campos obrigatórios (ver seção PATCH). O campo `documents` dentro de cada representante é **opcional no POST**.
:::

---

## Submeter Draft de Conta PJ

### Request

ENDPOINT /v2/account_request/{account_request_key}/draft_checking_legal_person
MÉTODO PATCH

### Descrição

Este endpoint **submete o draft** para processamento. O PATCH **valida completude** - todos os campos obrigatórios devem estar presentes no payload do PATCH.

**⚠️ IMPORTANTE**: O PATCH **sobrescreve completamente** os dados do `account_owner` com o payload enviado. Isso significa que:
- Você deve enviar **TODOS** os campos obrigatórios no payload do PATCH, mesmo que já tenham sido enviados no POST
- Dados enviados apenas no POST serão **perdidos** se não forem reenviados no PATCH
- O comportamento é de **substituição completa**, não de merge/atualização parcial
- O campo `documents` dentro de cada `company_representative` é **obrigatório** e deve conter pelo menos um tipo de documento válido (RG, CNH, RNE, CRNM, Passaporte ou CIN Digital)

Após a submissão bem-sucedida, o status muda de `draft` para `pending_bacen_validation` e inicia a validação do Bacen Protege+.

### Request Body

Request Body

```json
{
  "account_owner": {
    "company_document_number": "46073462000130",
    "name": "EMPRESA EXEMPLO TECNOLOGIA LTDA",
    "person_type": "legal",
    "email": "empresa@exemplo.com.br",
    "phone": {
      "country_code": "055",
      "area_code": "11",
      "number": "999999999"
    },
    "trading_name": "Empresa Exemplo",
    "company_type": "LTDA",
    "foundation_date": "2010-01-15",
    "cnae_code": "6209-1/00",
    "company_statute": "92c93e9e-b249-46b7-8c2e-95d4955a3c39",
    "monthly_revenue": 150000.00,
    "address": {
      "street": "Av. Brigadeiro Faria Lima",
      "state": "SP",
      "city": "São Paulo",
      "neighborhood": "Jardim Paulistano",
      "number": "2391",
      "postal_code": "01452905",
      "complement": "Conjunto 102"
    },
    "company_representatives": [
      {
        "name": "João Carlos da Silva",
        "email": "joao.silva@exemplo.com.br",
        "birth_date": "1985-03-20",
        "individual_document_number": "12345678901",
        "is_pep": false,
        "final_beneficiary": true,
        "mother_name": "Maria da Silva",
        "nationality": "brasileira",
        "person_type": "natural",
        "phone": {
          "country_code": "055",
          "area_code": "11",
          "number": "988888888"
        },
        "address": {
          "street": "Rua das Flores",
          "state": "SP",
          "city": "São Paulo",
          "neighborhood": "Jardins",
          "number": "123",
          "postal_code": "01310100",
          "complement": "Apto 45"
        },
        "representative_relationship": "ceo",
        "gender": "male",
        "marital_status": "married",
        "documents": {
          "rg": {
            "ocr_front_key": "0aa8a4ca-5873-49bd-851c-1f2c71a1cc28",
            "ocr_back_key": "29f6e346-7fae-4dcb-9ea1-2a3e4ef593ea"
          },
          "cnh": {
            "ocr_key": "7479c8e4-2a5d-4b4d-b2eb-4b841ec9390d"
          }
        },
        "face": "68da08f1-6cf4-4dce-a297-7b2f09311784"
      }
    ]
  },
  "additional_documents": [
    "61f2a65e-0ddf-4932-874f-9231794963da"
  ]
}
```

### Response

STATUS 200

Response Body

```json
{
  "account_request_key": "abc123-def456-...",
  "account_request_status": "pending_bacen_validation",
  "account_info": {
    "account_number": "1638634",
    "account_digit": "3",
    "account_branch": "0001"
  }
}
```

:::info Fluxo Bacen Protege+
Após a submissão bem-sucedida, o status muda para `pending_bacen_validation`. O sistema realiza uma validação prévia junto ao Bacen Protege+ antes de prosseguir com a análise de KYC. Após aprovação do Bacen, o status será atualizado para `pending_kyc_analysis` automaticamente.
:::

### Request Body Params

| Campo                 | Tipo   | Descrição                                                                    | Caracteres                                                         |
|-----------------------|--------|------------------------------------------------------------------------------|---------------------------------------------------------------------|
| `additional_documents` | array  | Lista de UUIDs de documentos adicionais (array de UUIDs)                    | -                                                                   |
| `account_owner` *     | object | Informações completas do titular da conta (Pessoa Jurídica)                 | **[Objeto account_owner (PATCH)](#objeto-account_owner-patch)**    |

### Objeto account_owner (PATCH)

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `company_document_number` * | string | CNPJ (14 dígitos, apenas números, padrão: `^[0-9]{14}$`) | 14 |
| `name` * | string | Razão social | 100 |
| `person_type` * | enum | Sempre `"legal"` | **[Enumeradores person_type](#enumeradores-person_type)** |
| `email` * | string | Email da empresa (formato email válido) | 254 |
| `phone` * | object | Telefone da empresa | **[Objeto phone](#objeto-phone)** |
| `trading_name` * | string | Nome fantasia | 200 |
| `company_type` * | enum | Tipo societário | **[Enumeradores company_type](#enumeradores-company_type)** |
| `foundation_date` * | string | Data de fundação (formato: YYYY-MM-DD) | 10 |
| `cnae_code` * | string | Código CNAE da atividade | 9 |
| `company_statute` * | string | UUID do estatuto social (formato UUID) | 36 |
| `monthly_revenue` * | number | Faturamento mensal | - |
| `address` * | object | Endereço completo da empresa | **[Objeto address](#objeto-address)** |
| `company_representatives` * | array | Lista de representantes legais (mínimo 1 item obrigatório) | **[Objeto company_representatives](#objeto-company_representatives)** |

:::warning Campos Obrigatórios no PATCH
**TODOS** os campos marcados com `*` são obrigatórios no PATCH. O schema JSON valida a completude de todos os campos antes de processar a submissão.
:::

### Objeto phone

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `country_code` * | string | Código do país (1-3 dígitos, padrão: `^[0-9]{1,3}$`) | 1-3 |
| `area_code` * | string | DDD (1-3 dígitos, padrão: `^[0-9]{1,3}$`) | 1-3 |
| `number` * | string | Número do telefone (1-10 dígitos, padrão: `^[0-9]{1,10}$`) | 1-10 |
| `type` | enum | Tipo de telefone (opcional: `"residential"`, `"commercial"`, `"mobile"`, `"fax"`) | - |

### Objeto address

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `street` * | string | Rua/Logradouro | 1-500 |
| `neighborhood` * | string | Bairro | 0-100 |
| `number` * | string | Número | 1-10 |
| `postal_code` * | string | CEP (8 dígitos, apenas números, padrão: `^\d{8}$`) | 8 |
| `city` * | string | Cidade | 1-100 |
| `state` * | enum | Estado (2 caracteres maiúsculos) | **[Enumeradores state](#enumeradores-state)** |
| `complement` | string | Complemento (opcional, máximo 500 caracteres) | 0-500 |

### Objeto company_representatives

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `name` * | string | Nome completo | 100 |
| `address` * | object | Endereço completo (mesma estrutura do address da empresa) | **[Objeto address](#objeto-address)** |
| `email` * | string | Email (formato email válido) | 5-200 |
| `birth_date` * | string | Data de nascimento (formato: YYYY-MM-DD, padrão: `\d{4}-((0[1-9])|(1[0-2]))-((0[1-9])|([1-2][0-9])|(3[0-1]))`) | 10 |
| `individual_document_number` * | string | CPF (11 dígitos, apenas números, padrão: `^[0-9]{11}$`) | 11 |
| `is_pep` * | boolean | Se é Pessoa Politicamente Exposta | - |
| `final_beneficiary` | boolean | Declaração se o representante é beneficiário final da empresa. | - |
| `mother_name` * | string | Nome da mãe | 100 |
| `nationality` * | string | Nacionalidade | 50 |
| `person_type` * | enum | Sempre `"natural"` | **[Enumeradores person_type](#enumeradores-person_type)** |
| `phone` * | object | Telefone (mesma estrutura do phone da empresa) | **[Objeto phone](#objeto-phone)** |
| `documents` * | object | Documentos para antifraude (obrigatório no PATCH) | **[Objeto documents](#objeto-documents)** |
| `face` | string | UUID da foto facial (36 caracteres) | 36 |
| `document_identification` | string | UUID do documento de identificação (formato UUID) | 36 |
| `document_identification_number` | string | Número do documento de identificação | 16 |
| `marital_status` | enum | Estado civil | **[Enumeradores marital_status](#enumeradores-marital_status)** |
| `gender` | enum | Gênero | **[Enumeradores gender](#enumeradores-gender)** |
| `representative_relationship` | enum | Relação com a empresa | **[Enumeradores representative_relationship](#enumeradores-representative_relationship)** |

### Objeto documents

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `rg` | object | Chaves OCR do upload da frente e verso do RG | **[Objeto rg](#objeto-rg)** |
| `cnh` | object | Chave OCR do upload da CNH | **[Objeto cnh](#objeto-cnh)** |
| `cnh_digital` | object | Chave OCR do upload da CNH digital | **[Objeto cnh_digital](#objeto-cnh_digital)** |
| `national_registry_of_foreigners` | object | Chaves OCR do upload da frente e verso do RNE | **[Objeto national_registry_of_foreigners](#objeto-national_registry_of_foreigners)** |
| `national_migration_registry` | object | Chaves OCR do upload da frente e verso do CRNM | **[Objeto national_migration_registry](#objeto-national_migration_registry)** |
| `passport` | object | Chave OCR do upload do passaporte | **[Objeto passport](#objeto-passport)** |
| `cin_digital` | object | Chave OCR do upload da Cédula de Identidade Nacional digital | **[Objeto cin_digital](#objeto-cin_digital)** |

### Objeto rg

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `ocr_front_key` * | uuidv4 | Chave OCR do upload da imagem da frente do RG | 36 |
| `ocr_back_key` * | uuidv4 | Chave OCR do upload da imagem do verso do RG | 36 |

OU

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `ocr_key` * | uuidv4 | Chave OCR do upload da imagem do RG | 36 |

### Objeto cnh

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `ocr_front_key` * | uuidv4 | Chave OCR do upload da imagem da frente da CNH | 36 |
| `ocr_back_key` * | uuidv4 | Chave OCR do upload da imagem do verso da CNH | 36 |

OU

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `ocr_key` * | uuidv4 | Chave OCR do upload da imagem da CNH | 36 |

### Objeto cnh_digital

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `ocr_key` * | uuidv4 | Chave OCR do upload da imagem da CNH digital | 36 |

### Objeto national_registry_of_foreigners

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `ocr_front_key` * | uuidv4 | Chave OCR do upload da imagem da frente do RNE | 36 |
| `ocr_back_key` * | uuidv4 | Chave OCR do upload da imagem do verso do RNE | 36 |

OU

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `ocr_key` * | uuidv4 | Chave OCR do upload da imagem do RNE | 36 |

### Objeto national_migration_registry

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `ocr_front_key` * | uuidv4 | Chave OCR do upload da imagem da frente do CRNM | 36 |
| `ocr_back_key` * | uuidv4 | Chave OCR do upload da imagem do verso do CRNM | 36 |

OU

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `ocr_key` * | uuidv4 | Chave OCR do upload da imagem do CRNM | 36 |

### Objeto passport

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `ocr_key` * | uuidv4 | Chave OCR do upload da imagem do passaporte | 36 |

### Objeto cin_digital

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `ocr_key` * | uuidv4 | Chave OCR do upload da imagem da Cédula de Identidade Nacional digital | 36 |

:::info Informação
As chaves OCR (`ocr_key` ou `ocr_front_key` e `ocr_back_key`) do upload das imagens dos documentos são fornecidas como resposta do upload das imagens no antifraude. A `face_recognition_key` é retornada na resposta do reconhecimento facial.
:::

### Response Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `account_request_key` * | string | Chave de identificação da requisição de criação | - |
| `account_request_status` * | string | Status da requisição (muda para `pending_bacen_validation` após submissão) | - |
| `account_info` * | object | Objeto contendo as informações da conta | **[Objeto account_info](#objeto-account_info)** |

### Objeto account_info

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `account_branch` * | string | Número da Agência | 4 |
| `account_digit` * | string | Dígito verificador da conta | 1 |
| `account_number` * | string | Número da conta | - |

### Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`  | Descrição (eng)<br/>`description` | Descrição(ptbr) <br></br>`translation`|
|---| --- | --- | --- | --- | 
| 400 | QIT000001 | Bad Request | Schema Error | Erro de Schema|
| 400 | - | Bad Request | Invalid request body | Corpo da requisição inválido |
| 404 | QIT000404 | Not Found | Resource could not be found | Recurso não encontrado|
| 409 | - | Conflict | Duplicate request_control_key | Chave de controle duplicada |

---

## Diferenças entre POST e PATCH

| Aspecto | POST (Criar Draft) | PATCH (Submeter Draft) |
|---------|-------------------|------------------------|
| **Objetivo** | Criar draft com flexibilidade | Validar completude e submeter ao Bacen |
| **Campos Obrigatórios** | Apenas CNPJ + Nome + Tipo | TODOS os campos + 1 representante completo **com documents** |
| **documents** | Opcional por representante | **Obrigatório por representante** (objeto com documentos OCR) |
| **Representantes** | Opcional | Obrigatório (mínimo 1) |
| **Validação** | Mínima (apenas 3 campos) | Completa (todos os campos obrigatórios) |
| **Status Inicial** | N/A | `draft` (deve estar neste status) |
| **Status Final** | `draft` | `pending_bacen_validation` |
| **Validação Bacen** | Não | Sim |
| **Análise KYC** | Não | Sim (após Bacen) |
| **Idempotência** | Sim (via `request_control_key`) | Não |

---

## Cenários de Uso

### Cenário 1: Cliente tem apenas dados básicos inicialmente
```
POST → {CNPJ, nome, tipo}  [status: draft]
...cliente coleta mais dados...
PATCH → {todos os campos + documents por representante} [status: pending_bacen_validation]
```

### Cenário 2: Cliente tem todos os dados de uma vez
```
POST → {todos os campos}  [status: draft]
PATCH → {todos os campos} [status: pending_bacen_validation]
```

### Cenário 3: Cliente envia dados parciais gradualmente
```
POST → {CNPJ, nome, tipo, email}  [status: draft]
...cliente coleta mais dados...
PATCH → {todos os campos incluindo representantes com documents} [status: pending_bacen_validation]
```
---

## Enumeradores

### Enumeradores person_type

| Enum | Descrição |
|------|-----------|
| `natural` | Pessoa física |
| `legal` | Pessoa jurídica |

### Enumeradores company_type

| Enum | Descrição |
|------|-----------|
| `ltda` | Limitada |
| `sa` | Sociedade Anônima |
| `micro_enterprise` | Micro Empresa |
| `freelancer` | Freelancer |
| `sa_opened` | Sociedade Anônima de Capital Aberto |
| `sa_closed` | Sociedade Anônima de Capital Fechado |
| `se_ltda` | Sociedade Empresária Limitada |
| `se_cn` | Sociedade Empresária em Nome Coletivo |
| `se_cs` | Sociedade Empresária em Comandita Simples |
| `se_ca` | Sociedade Empresária em Comandita por Ações |
| `scp` | Sociedade em Conta de Participação |
| `ei` | Empresário Individual |
| `ese` | Estabelecimento, no Brasil, de Sociedade Estrangeira |
| `eeab` | Estabelecimento, no Brasil, de Empresa Binacional Argentino-Brasileira |
| `ssp` | Sociedade Simples Pura |
| `ss_ltda` | Sociedade Simples Limitada |
| `ss_cn` | Sociedade Simples em Nome Coletivo |
| `ss_cs` | Sociedade Simples em Comandita Simples |
| `eireli_ne` | Empresa Individual de Responsabilidade Limitada (de Natureza Empresária) |
| `eireli_ns` | Empresa Individual de Responsabilidade Limitada (de Natureza Simples) |
| `eireli` | Empresa de Responsabilidade Individual |
| `mei` | Micro Empreendedor Individual |
| `me` | Micro Empresa |
| `cop` | Cooperativa |
| `private_association` | Sociedade Privada |

### Enumeradores state

| Enum | Descrição |
|------|-----------|
| `AC` | Acre |
| `AL` | Alagoas |
| `AM` | Amazonas |
| `AP` | Amapá |
| `BA` | Bahia |
| `CE` | Ceará |
| `DF` | Distrito Federal |
| `ES` | Espírito Santo |
| `GO` | Goiás |
| `MA` | Maranhão |
| `MG` | Minas Gerais |
| `MS` | Mato Grosso do Sul |
| `MT` | Mato Grosso |
| `PA` | Pará |
| `PB` | Paraíba |
| `PE` | Pernambuco |
| `PI` | Piauí |
| `PR` | Paraná |
| `RJ` | Rio de Janeiro |
| `RN` | Rio Grande do Norte |
| `RO` | Rondônia |
| `RR` | Roraima |
| `RS` | Rio Grande do Sul |
| `SC` | Santa Catarina |
| `SE` | Sergipe |
| `SP` | São Paulo |
| `TO` | Tocantins |
| `EX` | Exterior |

### Enumeradores marital_status

| Enum | Descrição |
|------|-----------|
| `single` | Solteiro(a) |
| `married` | Casado(a) |
| `widower` | Viúvo(a) |
| `divorced` | Divorciado(a) |
| `separated` | Separado(a) |

### Enumeradores gender

| Enum | Descrição |
|------|-----------|
| `male` | Masculino |
| `female` | Feminino |

### Enumeradores representative_relationship

| Enum | Descrição |
|------|-----------|
| `ceo` | CEO / Diretor Presidente |
| `analyst` | Analista |
| `partner` | Sócio |
| `director` | Diretor |
| `attorney` | Procurador |
| `signer` | Assinante |

---

## Fluxo Completo

1. **POST** `/v2/account_request/draft_checking_legal_person`
   - Cria draft com dados disponíveis
   - Status: `draft`
   - Retorna: `account_request_key`

2. **(Opcional)** Coletar dados adicionais

3. **PATCH** `/v2/account_request/{account_request_key}/draft_checking_legal_person`
   - Valida completude de todos os campos
   - Envia para Bacen Protege+
   - Status: `pending_bacen_validation`

4. **Bacen Protege+ valida** (assíncrono)
   - Status: `pending_kyc_analysis` (se aprovado)

5. **KYC analisa pessoa jurídica**
   - Status: `approved` (se tudo OK)

6. **Conta criada e pronta para uso**

---

---

# fluxo_de_abertura_de_conta

URL: /documentation/contas/abertura_de_conta/fluxo_de_abertura_de_conta

### Conta de livre movimentação

As contas de livre movimentação são quaisquer contas bancárias cujo saldo pode ser sacado movimentado pelo cliente, no todo ou em parte.

Abertura de conta
Assim como a emissão de dívidas, a solicitação de abertura de conta é feita com uma única chamada (não esquecendo que os documentos devem ser previamente enviados).

Recebido esse pedido de conta a QI Tech é responsável por executar o compliance e abrir a conta. Na prática:

1 - Solicitação da abertura de conta (solicitado via request)
2 - Validação de compliance (informado resultado via webhook)
3 - Abertura da conta (informado resultado via webhook)

---

# Introdução

URL: /documentation/contas/abertura_de_conta/introducao

Uma das funcionalidades que podemos oferecer em nossa integração é a possibilidade de gerenciar contas e transferências para contas da QI Tech ou de outras instituições financeiras via API, mas não é só isso, provemos a possibilidade de fazer a ABERTURA de uma conta via API. Seja para você mesmo, ou para terceiros.

Assim como as demais APIs a liberação do serviço deve ser feita junto ano nosso time e as chamadas são autenticadas.

Nas subseções abaixo veremos como abrir e gerenciar uma conta de pagamento dentro da QI Tech.

---

# Webhooks de abertura de conta

URL: /documentation/contas/abertura_de_conta/webhooks_contas

A resposta da solicitação de abertura de conta poderá retornar o status “pending_kyc_analysis” a depender da configuração de integração do parceiro.

Neste caso, a resposta sobre a aprovação ou reprovação da abertura da conta será retornada de forma assíncrona via webhook.

O número de conta será reservado no momento da solicitação de abertura, porém neste momento **a conta ainda não estará aberta**. Somente após a conclusão da análise de KYC da QI Tech a conta estará aberta.

## Contas de Pessoa Jurídica

#  Account Opened

WEBHOOK_TYPE account
STATUS account_opened

Webhook Body

```json
{
	"data": {
		"account_info": {
			"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
			"account_digit": "2",
			"account_branch": "0001",
			"account_number": "2359934",
			"financial_institution_code": "329"
		},
		"allowed_user": {
			"name": "Juliana Tereza Bernardes",
			"document_number": "12364480084"
		},
		"account_owner": {
			"name": "VOVO LUCIA CONVENIENCIA LTDA",
			"document_number": "12380702000105"
		}
	},
	"event_datetime": "2022-09-02 22:39:39",
	"key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
	"status": "account_opened",
	"webhook_type": "account"
}
```

# Account Rejected

WEBHOOK_TYPE account
STATUS account_rejected

Webhook Body

```json
{
	"data": {
		"account_info": {
			"account_digit": "2",
			"account_branch": "0001",
			"account_number": "2359934",
			"financial_institution_code": "329"
		},
		"allowed_user": {
			"name": "Juliana Tereza Bernardes",
			"document_number": "97564480084"
		},
		"account_owner": {
			"name": "VOVO LUCIA CONVENIENCIA LTDA",
			"document_number": "09080702000105"
		}
	},
	"event_datetime": "2022-09-02 22:39:39",
	"key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
	"status": "account_rejected",
	"webhook_type": "account"
}
```

## Contas de Pessoa Física

# Account Opened

WEBHOOK_TYPE account
STATUS account_opened

Webhook Body

```json
{
    "key":"b5978088-2860-4b78-bd44-77b961354014",
  	"data":{
        "account_info":{
            "account_key":"b7593804-2223-48b3-8a61-f48a651de1d4",
            "account_digit":"5",
            "account_branch":"0001",
            "account_number":"3998360",
            "financial_institution_code":"329"
        },
        "account_owner":{
            "name":"Pedro Pinho",
            "document_number":"97634408077"
        }
      },
    "status":"account_opened",
    "webhook_type":"account",
    "event_datetime":"2024-01-09 14:35:46"
}
```

# Account Rejected

WEBHOOK_TYPE account
STATUS account_rejected

Webhook Body

```json
{
    "key":"84864614-2860-4b78-bd44-77b961354014",
  	"data":{
        "account_info":{
            "account_key":"1435dbavf-2860-4b78-bd44-77b961354014",
            "account_digit":"5",
            "account_branch":"0001",
            "account_number":"3998360",
            "financial_institution_code":"329"
        },
        "account_owner":{
            "name":"Pedro Pinho",
            "document_number":"97634408077"
        }
      },
    "status":"account_rejected",
    "webhook_type":"account",
    "event_datetime":"2024-01-09 14:35:46"
}
```

---

# Emitir Carta Bancária

URL: /documentation/contas/carta_bancaria

A carta bancária ("Declaração de Relacionamento") é um documento PDF assinado digitalmente pela QI SCD que comprova o vínculo ativo entre o cliente e a instituição, incluindo dados da conta. Após a emissão, o documento assinado é enviado por e-mail para os destinatários informados.

## Request

ENDPOINT /account/ ACCOUNT_KEY /ownership_letter
MÉTODO POST

### Path parameters

| Campo | Tipo | Descrição                      |
|---|------|--------------------------------|
| `ACCOUNT_KEY` | UUID | Chave da conta da qual a carta será emitida |

### Body parameters

| Campo | Tipo | Descrição | Max. Caracteres |
|---|---|---|---|
| `emails` * | array de strings | Lista de e-mails que receberão o PDF assinado. Mínimo 1 endereço. | - |

Request Body

```json
{
  "emails": ["contato@cliente.com.br", "financeiro@cliente.com.br"]
}
```

## Response

STATUS 200

Response Body

```json
{
  "document_key": "f1b8e3a2-c5d4-4e9f-a1b2-3c4d5e6f7a8b",
  "account_key": "3e4b8746-da58-4799-bcd0-063326428d3f",
  "document_type": "ownership_letter",
  "document_status": "pending",
  "external_identifier_key": "certifiqi-batch-group-key",
  "file_url": "https://api.certifiqi.com.br/events/certifiqi-batch-group-key",
  "payload": {
    "emails": ["contato@cliente.com.br", "financeiro@cliente.com.br"]
  },
  "created_at": "2026-05-28T19:50:47",
  "updated_at": "2026-05-28T19:50:47"
}
```

### Response Body parameters

| Campo | Tipo | Descrição | Max. Caracteres |
|---|---|---|---|
| `document_key` | UUID | Identificador interno do documento na QI. | 36 |
| `account_key` | UUID | Chave da conta de origem. | 36 |
| `document_type` | string | Tipo do documento. Sempre `ownership_letter` nesta rota. | - |
| `document_status` | string | Status atual do documento. Ver [Enumeradores document_status](#enumeradores-document_status). | - |
| `external_identifier_key` | string | Identificador externo do lote de assinatura. | 300 |
| `file_url` | string | URL atual do documento. Durante `pending`, aponta para o acompanhamento da assinatura; após `sent`, aponta para o PDF assinado. | - |
| `payload` | object | Eco do corpo enviado na requisição. | - |
| `created_at` | datetime Zulu | Data de criação do documento. | 20 |
| `updated_at` | datetime Zulu | Última atualização do documento. | 20 |

### Enumeradores document_status

| Enumerador | Descrição |
|---|---|
| **pending** | Documento criado, aguardando finalização da assinatura. |
| **sent** | Documento assinado e e-mails despachados aos destinatários. |

## Obter link do documento assinado

Após a assinatura ser concluída (status `sent`), use este endpoint para obter um **link expirável** de download do PDF assinado, gerado sob demanda pela CertifIQI. Enquanto o documento estiver `pending` — ou seja, antes de o webhook de assinatura ter sido recebido — a URL ainda não existe e o endpoint retorna erro.

### Request

ENDPOINT /account/ ACCOUNT_KEY /document/ DOCUMENT_KEY /url
MÉTODO GET

### Path parameters

| Campo | Tipo | Descrição |
|---|------|-----------|
| `ACCOUNT_KEY` | UUID | Chave da conta à qual o documento está vinculado. |
| `DOCUMENT_KEY` | UUID | Identificador do documento (`document_key`) retornado na emissão da carta. |

## Response

STATUS 200

Response Body

```json
{
  "document_key": "f1b8e3a2-c5d4-4e9f-a1b2-3c4d5e6f7a8b",
  "document_type": "ownership_letter",
  "document_status": "sent",
  "url": "https://api.certifiqi.com.br/expirable/signed_document.pdf?token=abc123"
}
```

### Response Body parameters

| Campo | Tipo | Descrição | Max. Caracteres |
|---|---|---|---|
| `document_key` | UUID | Identificador interno do documento na QI. | 36 |
| `document_type` | string | Tipo do documento. `ownership_letter` para carta bancária. | - |
| `document_status` | string | Status atual do documento. A URL só é retornada quando `sent`. | - |
| `url` | string | Link **expirável** para download do PDF assinado. Gerado sob demanda; expira após curto período. | - |

### Possíveis erros

| Status | Descrição |
|---|---|
| 404 | Conta ou documento não encontrado para os identificadores informados. |
| 409 | Documento ainda em assinatura (`pending`); a URL assinada ainda não está disponível. |

---

# Emitir Carta de Circularização

URL: /documentation/contas/carta_circularizacao

A carta de circularização é um documento de auditoria assinado digitalmente pela QI SCD que confirma os saldos das contas mantidas pelo titular em uma data-base de referência. Listará todas as contas da CNPJ/CPF do titular vinculadas ao requester da conta informada no path. Após a emissão, o PDF assinado é enviado por e-mail para os destinatários informados (tipicamente o auditor).

## Request

ENDPOINT /account/ ACCOUNT_KEY /circularization_letter
MÉTODO POST

### Path parameters

| Campo | Tipo | Descrição |
|---|------|-----------|
| `ACCOUNT_KEY` | UUID | Chave de uma conta do titular. Serve apenas para identificar o documento e o requester; a carta lista **todas** as contas do mesmo documento dentro do requester. |

### Body parameters

| Campo | Tipo | Descrição | Max. Caracteres |
|---|---|---|---|
| `emails` * | array de strings | Lista de e-mails que receberão o PDF assinado. Mínimo 1 endereço. Tipicamente o e-mail do auditor solicitante. | - |
| `reference_date` * | string (YYYY-MM-DD) | Data-base para o cálculo dos saldos. A carta declara o saldo de cada conta na posição de fechamento desta data. | 10 |
| `recipient_name` | string | Nome da empresa/instituição destinatária, usado na saudação do documento ("Prezados senhores da `{recipient_name}`"). Se omitido, usa "A quem possa interessar,". | - |

Request Body

```json
{
  "emails": ["auditoria@empresa-de-auditoria.com.br"],
  "reference_date": "2026-04-30",
  "recipient_name": "BDO RCS Auditores Independentes"
}
```

## Response

STATUS 200

Response Body

```json
{
  "document_key": "f1b8e3a2-c5d4-4e9f-a1b2-3c4d5e6f7a8b",
  "account_key": "3e4b8746-da58-4799-bcd0-063326428d3f",
  "document_type": "circularization_letter",
  "document_status": "pending",
  "external_identifier_key": "certifiqi-batch-group-key",
  "file_url": "https://api.certifiqi.com.br/events/certifiqi-batch-group-key",
  "payload": {
    "emails": ["auditoria@empresa-de-auditoria.com.br"],
    "reference_date": "2026-04-30",
    "recipient_name": "BDO RCS Auditores Independentes"
  },
  "created_at": "2026-05-28T19:50:47",
  "updated_at": "2026-05-28T19:50:47"
}
```

### Response Body parameters

| Campo | Tipo | Descrição | Max. Caracteres |
|---|---|---|---|
| `document_key` | UUID | Identificador interno do documento na QI. | 36 |
| `account_key` | UUID | Chave da conta de origem. | 36 |
| `document_type` | string | Tipo do documento. Sempre `circularization_letter` nesta rota. | - |
| `document_status` | string | Status atual do documento. Ver [Enumeradores document_status](#enumeradores-document_status). | - |
| `external_identifier_key` | string | Identificador externo do lote de assinatura. | 300 |
| `file_url` | string | URL atual do documento. Durante `pending`, aponta para o acompanhamento da assinatura; após `sent`, aponta para o PDF assinado. | - |
| `payload` | object | Eco do corpo enviado na requisição. | - |
| `created_at` | datetime Zulu | Data de criação do documento. | 20 |
| `updated_at` | datetime Zulu | Última atualização do documento. | 20 |

### Enumeradores document_status

| Enumerador | Descrição |
|---|---|
| **pending** | Documento criado, aguardando finalização da assinatura. |
| **sent** | Documento assinado e e-mails despachados aos destinatários. |

## Obter link do documento assinado

Após a assinatura ser concluída (status `sent`), use este endpoint para obter um **link expirável** de download do PDF assinado, gerado sob demanda pela CertifIQI. Enquanto o documento estiver `pending` — ou seja, antes de o webhook de assinatura ter sido recebido — a URL ainda não existe e o endpoint retorna erro.

### Request

ENDPOINT /account/ ACCOUNT_KEY /document/ DOCUMENT_KEY /url
MÉTODO GET

### Path parameters

| Campo | Tipo | Descrição |
|---|------|-----------|
| `ACCOUNT_KEY` | UUID | Chave da conta à qual o documento está vinculado. |
| `DOCUMENT_KEY` | UUID | Identificador do documento (`document_key`) retornado na emissão da carta. |

## Response

STATUS 200

Response Body

```json
{
  "document_key": "f1b8e3a2-c5d4-4e9f-a1b2-3c4d5e6f7a8b",
  "document_type": "circularization_letter",
  "document_status": "sent",
  "url": "https://api.certifiqi.com.br/expirable/signed_document.pdf?token=abc123"
}
```

### Response Body parameters

| Campo | Tipo | Descrição | Max. Caracteres |
|---|---|---|---|
| `document_key` | UUID | Identificador interno do documento na QI. | 36 |
| `document_type` | string | Tipo do documento. `circularization_letter` para carta de circularização. | - |
| `document_status` | string | Status atual do documento. A URL só é retornada quando `sent`. | - |
| `url` | string | Link **expirável** para download do PDF assinado. Gerado sob demanda; expira após curto período. | - |

### Possíveis erros

| Status | Descrição |
|---|---|
| 404 | Conta ou documento não encontrado para os identificadores informados. |
| 409 | Documento ainda em assinatura (`pending`); a URL assinada ainda não está disponível. |

---

# Consulta de tarifas

URL: /documentation/contas/consulta_de_tarifas

## Request

ENDPOINT /account/ ACCOUNT_KEY /billing_configuration
MÉTODO GET

## Response

STATUS 200

**Response Body**

```json
{
   "billing_configuration_data":{
      "bank_slip":{
         "registration":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":10,
            "expense_type":"fixed_amount"
         },
         "bank_slip_instant_registration":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "permanence":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":10,
            "expense_type":"fixed_amount"
         },
         "protest_removal":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "protest_request":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "protest_costs":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"percentage"
         },
         "expiration_date_change":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "rebate_inclusion":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "discount_inclusion":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "notary_office_payment":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "expiration_write_off":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "write_off":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "protest_write_off":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "protest_removal_and_write_off":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "payment":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "payment_qr_code":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "payment":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "fine_or_interest_inclusion":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "bank_slip_fine_alteration":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "bank_slip_interest_alteration":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "bank_slip_discount_alteration":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
      },
      "ted":{
         "outgoing_ted":{
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435",
            "amount":20,
            "expense_type":"fixed_amount",
         },
         "incoming_ted":{
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435",
            "amount":20,
            "expense_type":"fixed_amount"
         }
      },
      "pix":{
         "incoming_pix":{
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435",
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "outgoing_pix":{
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435",
            "amount":20,
            "expense_type":"fixed_amount"
         },
      },
      "account": {
         "account_maintenance":{
            "amount":40,
            "expense_type": "fixed_amount",
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435"
         },
         "incoming_funds":{
            "amount":10,
            "expense_type": "percentage",
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435"
         },
         "account_creation":{
            "amount":40,
            "expense_type": "fixed_amount",
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435"
         }
      },
      "qr_code": {
         "dynamic_qr_code_expiration":{
            "amount":40,
            "expense_type": "fixed_amount",
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435"
         }
      },
      "prepaid_card": {
         "prepaid_fisical_card_creation":{
            "amount":40,
            "expense_type": "fixed_amount",
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435"
         },
         "prepaid_virtual_card_creation":{
            "amount":40,
            "expense_type": "fixed_amount",
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435"
         },
         "card_withdrawal_fee":{
            "amount":40,
            "expense_type": "fixed_amount",
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435"
         },
         "international_card_withdrawal_fee":{
            "amount":40,
            "expense_type": "fixed_amount",
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435"
         }
      }
   }
}
```

### Billing_configuration_data

| Campo | Tipo | Descrição  |
|---| ---| ---|
| `bank_slip` | object  | **[Bankslip](#bank_slip)**  |
| `ted` | object  | **[TED](#ted)**  |
| `pix` | object  | **[Pix](#pix)**  |
| `account` | object  | **[Conta](#account)**  |
| `prepaid_card` | object  | **[Conta](#prepaid_card)**  |
| `qr_code` | object  | **[Conta](#qr_code)**  |

### BankSlip 

| Campo | Tipo | Descrição | Referência
|---|---|---|---|
| `registration` | object  |  Tarifa de registro | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `permanence` | object  | Tarifa de permanência título cadastrado | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `protest_removal` | object  | Tarifa de sustação/Excl Negativação | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `protest_request` | object  | Tarifa de protesto/Incl Negativação | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `protest_costs` | object  | Custas de Protestos, para esse campo **expense_type deve ser 'percentage'** | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `expiration_date_change` | object  | Tarifa alteração de vencimento | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `rebate_inclusion` | object  | Tarifa concessão abatimento | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `discount_inclusion` | object  | Tarifa concessão desconto | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `notary_office_payment` | object  | Tarifa título Baix. Pg. Cartório | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `expiration_write_off` | object  | Tarifa título baixado decurso prazo | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `write_off` | object  | Tarifa título baixado conf. Pedido | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `protest_write_off` | object  | Tarifa título baixado protestado | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `protest_removal_and_write_off` | object  | Tarifa título baixado SUST/RET/CARTÓRIO | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `payment` | object  | Tarifa Liquidação | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `payment_qr_code` | object  | Tarifa Liquidação por QR-Code  | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `fine_or_interest_inclusion` | object  | Tarifa de inclusão de Multa e Juros | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `bank_slip_fine_alteration` | object  | Tarifa de alteração de Multa | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `bank_slip_interest_alteration` | object  | Tarifa de alteração de Juros | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `bank_slip_discount_alteration` | object  | Tarifa de alteração de Desconto | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `bank_slip_instant_registration` | object  | Tarifa de registro de boleto instantâneo | **[Objeto padrão fees](#objeto-padrão-fees)** |

### Ted 

| Campo | Tipo | Descrição | Referência
|---|---|---|
| `outgoing_ted` | object  | Tarifa de Envio de TED | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `incoming_ted` | object  | Tarifa de Entrada de TED | **[Objeto padrão fees](#objeto-padrão-fees)** |

### Pix 

| Campo | Tipo | Descrição | Referência
|---|---|---|---|
| `incoming_pix` | object  | Tarifa de Entrada de Pix | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `outgoing_pix` | object  | Tarifa de Envio de Pix | **[Objeto padrão fees](#objeto-padrão-fees)** |

### Account 

| Campo | Tipo | Descrição | Referência
|---|---|---|---|
| `incoming_funds` | object  | Tarifa de Entrada de Recurso | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `account_maintenance` | object  | Tarifa de Manutenção de Conta | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `account_creation` | object  | Tarifa de Criação de Conta | **[Objeto padrão fees](#objeto-padrão-fees)** |

### QrCode 

| Campo | Tipo | Descrição | Referência
|---|---|---|---|
| `dynamic_qr_code_expiration` | object  | Tarifa de Expiração de QR-Code Dinâmico não Liquidado | **[Objeto padrão fees](#objeto-padrão-fees)** |

### PrepaidCard 

| Campo | Tipo | Descrição | Referência
|---|---|---|---|
| `prepaid_fisical_card_creation` | object  | Tarifa de Criação de Cartão Físico | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `prepaid_virtual_card_creation` | object  | Tarifa de Criação de Cartão Virtual | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `card_withdrawal_fee` | object  | Tarifa de Saque | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `international_card_withdrawal_fee` | object  | Tarifa de Saque Internacional | **[Objeto padrão fees](#objeto-padrão-fees)** |

### Objeto padrão fees

| Campo | Tipo | Descrição | Referência
|---|---|---|---|
| `amount` | number | Valor da taxa a qual poderá representar em valor absoluto (fixed_amount) ou porcentagem (percentage), deve ser limitado a duas casas decimais|
| `expense_type` | enum | Formato de cobrança | **[Enumerador expense_type](#enumerador-expense-type)** 
| `billing_account_key` | string | id (uuid) contendo a referência para a conta a qual será cobrada a taxa | 

# Enumeradores

### Enumerador _Expense Type_
| Enumerador            | Descrição                                                                 |
|-----------------------|---------------------------------------------------------------------------|
| **percentage**        | Valor em porcentagem                                                      |
| **fixed_amount**    | Valor absoluto                                  |

STATUS 4XX

**Response Body: Error**

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                          | Descrição (eng)<br/>`Description`                 | Descrição (ptbr)<br/>`translation`                                          |
|-------------|----------------------|---------------------------------------------|---------------------------------------------------|-----------------------------------------------------------------------------|
| 400         | BLL000063            | Bad Request                                 | Not allowed to view fees in unavailable accounts   | Conta indisponível.                 |
| 404         | BLL000027            | Not Found                                   | Account not found for the given account_key        | Não foi encontrada uma conta com a chave fornecida. |

---

# Consultar conta

URL: /documentation/contas/consultar_conta

## Request

ENDPOINT /account/ ACCOUNT_KEY
MÉTODO GET

### Path Params

| Campo | Tipo | Descrição                      |
|---|------|--------------------------------|
| `ACCOUNT_KEY` | UUID | Chave da conta a ser detalhada |

## Response

Response Body

```json
{
    "account_branch": "0001",
    "account_digit": "5",
    "account_documents": ["1e4b8746-da58-4799-bcd0-063326428ssd"],
    "account_key": "3e4b8746-da58-4799-bcd0-063326428d3f",
    "account_number": "5960388",
    "account_status": "opened",
    "account_type": "checking",
    "balance": 264.76,
    "blocked_balance": 0,
    "owner_document_number": "30987145223",
    "owner_name": "Maria Luiza Vieira",
    "owner_person_key": "47d08366-a8ec-414c-a0a5-a089fc8a4ee8",
    "created_at": "2023-05-15T19:56:10"
}
```

### Body params

| Campo | Tipo          | Descrição                                    | Max. Caracteres                                             |
|-------|---------------|----------------------------------------------|-------------------------------------------------------------|
| `account_key` | uuid          | Identificador único da conta.                | 36                                                          |
| `account_branch` | string        | Agência, sem o dígito verificador.           | 4                                                           |
| `account_digit` | string        | Dígito verificador da conta.                 | 1                                                           |
| `account_number` | string        | Número de conta, sem o dígito verificador.   | 20                                                          |
| `account_type` | string        | Definição do tipo de conta.                  | 20                                                          |
| `account_status` | string        | Status da conta.                             | [Enumeradores account_status](#enumeradores-account_status) |
| `owner_document_number` | string        | Numero de CPF ou CNPJ.                       | 14                                                          |
| `owner_name` | string        | Nome do dono da conta.                       | 120                                                         |
| `balance` | double        | Saldo da conta.                              | 120                                                         |
| `blocked_balance` | double        | Saldo bloqueado da conta.                    | 120                                                         |
| `owner_person_key` | string        | Identificador único da pessoa dona da conta. | 36                                                          |
| `account_documents` | ARRAY         | Array de identificadores únicos da conta.    | -                                                           |
| `created_at` | datetime Zulu | Data de criação da requisição.               | 20                                                          |

### Enumeradores account_status
| Enumerador | Descrição       |
|------------|-----------------|
| `opened`   | Conta aberta    |
| `closed`   | Conta encerrada |
| `blocked`  | Conta bloqueada |

STATUS 404

Response Body: Usuário não possui credenciais

```json
{
    "title": "Not Found",
    "description": "Account not found for the given key 3e4b8746-da58-4799-bcd0-063326428d3f",
    "translation": "Conta não encontrada para a seguinte chave 3e4b8746-da58-4799-bcd0-063326428d3f",
    "code": "ACC000006"
}
```

STATUS 403

Response Body: Usuário não possui credenciais

```json
{
    "title": "Permission Validator Error",
    "description": "Selected agent do not own this item.",
    "translation": "O agente selecionado não é dono do item.",
    "code": "QIT000005"
}
```

---

# Listar contas

URL: /documentation/contas/consultar_contas

## Request

ENDPOINT /accounts
MÉTODO GET

## Query Params
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `owner_document_number` | string | Numero de documento do titular da conta. | - |
| `account_number` | string | Numero da conta. | - |

## Response

STATUS 200

**Response Body**

```json
{
	"data": [
	  {
			"account_block_reason": null,
			"account_branch": "0001",
			"account_credentials": [{
					"account_id": 4130,
					"created_at": "2023-05-15T19:56:10",
					"credential_type": {
						"created_at": "2019-06-18T13:19:30",
						"enumerator": "observer",
						"id": 3,
						"translation_path": "account.CredentialType.observer"
					},
					"credential_type_id": 3,
					"id": 4394,
					"is_active": true,
					"person_key": "47d08366-a8ec-414c-a0a5-a089fc8a4ee8",
					"updated_at": null
				},
				{
					"account_id": 4130,
					"created_at": "2023-05-15T19:56:10",
					"credential_type": {
						"created_at": "2019-06-18T13:19:30",
						"enumerator": "approver_requester",
						"id": 4,
						"translation_path": "account.CredentialType.approver_requester"
					},
					"credential_type_id": 4,
					"id": 4395,
					"is_active": true,
					"person_key": "77136fe2-2ddb-4593-b285-67c40b6da46a",
					"updated_at": null
				},
				{
					"account_id": 4130,
					"created_at": "2023-05-15T19:56:10",
					"credential_type": {
						"created_at": "2019-06-18T13:19:30",
						"enumerator": "requester",
						"id": 2,
						"translation_path": "account.CredentialType.requester"
					},
					"credential_type_id": 2,
					"id": 4396,
					"is_active": true,
					"person_key": "77136fe2-2ddb-4593-b285-67c40b6da46a",
					"updated_at": null
				}
			],
			"account_digit": "5",
			"account_documents": [],
			"account_events": [{
				"account_id": 4130,
				"created_at": "2023-05-15T19:56:10",
				"id": 6250,
				"new_account_status": {
					"created_at": "2019-10-11T18:58:31",
					"enumerator": "opened",
					"id": 1,
					"translation_path": "account.AccountStatus.opened"
				},
				"new_account_status_id": 1,
				"old_account_status": null,
				"old_account_status_id": null
			}],
			"account_key": "3e4b8746-da58-4799-bcd0-063326428d3f",
			"account_name": "Default",
			"account_number": "5960388",
			"account_status": {
				"created_at": "2019-10-11T18:58:31",
				"enumerator": "opened",
				"translation_path": "account.AccountStatus.opened"
			},
			"account_type": {
				"created_at": "2019-03-15T13:09:15",
				"enumerator": "checking",
				"translation_path": "account.AccountType.checking"
			},
			"automatic_transfer_management_status": {
				"created_at": "2022-10-27T13:48:18",
				"enumerator": "master"
			},
			"automatic_transfers": [],
			"balance": 264.76,
			"blocked_balance": 0,
			"blocked_balance_events": [],
			"created_at": "2023-05-15T19:56:10",
			"destinations": [],
			"fee": null,
			"internal_webhooks": [{
				"account_id": 4130,
				"created_at": "2023-05-15T16:56:10",
				"id": 144,
				"is_active": true,
				"updated_at": "2023-05-15T16:56:10",
				"webhook_tag": {
					"created_at": "2023-03-30T20:20:04",
					"enumerator": "billing",
					"id": 2
				},
				"webhook_tag_id": 2
			}],
			"investment_available_amount": 264.76,
			"investment_configuration": {
				"block_yield": false,
				"daily_yield_percentage": 1,
				"investment_configuration_status": "active",
				"monthly_yield_amount": 0
			},
			"is_system_account": false,
			"owner_document_number": "30987145223",
			"owner_name": "Maria Luiza Vieira",
			"owner_person_key": "47d08366-a8ec-414c-a0a5-a089fc8a4ee8",
			"permitted_person_keys": [
				"47d08366-a8ec-414c-a0a5-a089fc8a4ee8",
				"47d08366-a8ec-414c-a0a5-a089fc8a4ee8",
				"77136fe2-2ddb-4593-b285-67c40b6da46a",
				"77136fe2-2ddb-4593-b285-67c40b6da46a"
			],
			"requester_key": "77136fe2-2ddb-4593-b285-67c40b6da46a",
			"requester_name": "White Label Develop",
			"setup_fee": null,
			"transactional_limit": null,
			"webhook_enabled": true
		},
		{
			"account_block_reason": null,
			"account_branch": "9999",
			"account_credentials": [],
			"account_digit": "5",
			"account_documents": [],
			"account_events": [],
			"account_key": "748b456c-92fb-4832-837a-0f0a15222a21",
			"account_name": "investment-Default",
			"account_number": "5960388",
			"account_status": {
				"created_at": "2019-10-11T18:58:31",
				"enumerator": "opened",
				"translation_path": "account.AccountStatus.opened"
			},
			"account_type": {
				"created_at": "2022-09-05T20:57:05",
				"enumerator": "investment",
				"translation_path": "account.AccountType.investment"
			},
			"automatic_transfer_management_status": {
				"created_at": "2022-10-27T13:48:18",
				"enumerator": "master"
			},
			"automatic_transfers": [],
			"balance": 0,
			"blocked_balance": 0,
			"blocked_balance_events": [],
			"created_at": "2023-05-24T12:42:42",
			"destinations": [],
			"fee": null,
			"internal_webhooks": [],
			"investment_available_amount": 0,
			"investment_configuration": null,
			"is_system_account": false,
			"owner_document_number": "30987145223",
			"owner_name": "Maria Luiza Vieira",
			"owner_person_key": "47d08366-a8ec-414c-a0a5-a089fc8a4ee8",
			"permitted_person_keys": [
				"47d08366-a8ec-414c-a0a5-a089fc8a4ee8"
			],
			"requester_key": "77136fe2-2ddb-4593-b285-67c40b6da46a",
			"requester_name": "White Label Develop",
			"setup_fee": null,
			"transactional_limit": null,
			"webhook_enabled": null
		}
	],
	"pagination": {
		"current_page": 1,
		"next_page": null,
		"rows_per_page": 100,
		"total_pages": 1,
		"total_rows": 2
	}
}
```

STATUS 400

**Response Body**

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

---

# Consultar detalhes de pedido de conta

URL: /documentation/contas/consultar_detalhes_pedido_conta

Endpoint para consultar os detalhes completos de um pedido de abertura de conta, incluindo informações sobre o status da proposta, partes relacionadas, documentos anexados, eventos e configurações.

:::info Informação
Este endpoint suporta apenas contas do tipo **checking** (conta corrente) e **escrow**.
:::

## Request

ENDPOINT /v2/account_request/ ACCOUNT_REQUEST_KEY /full
MÉTODO GET

### Path Params

| Campo | Tipo | Descrição |
|---|------|-----------|
| `ACCOUNT_REQUEST_KEY` | UUID | Chave única do pedido de conta a ser consultado |

## Response

STATUS 200

Response Body

```json
{
    "proposal_key": "3e4b8746-da58-4799-bcd0-063326428d3f",
    "contract_number": "123456",
    "requester_key": "47d08366-a8ec-414c-a0a5-a089fc8a4ee8",
    "requester_name": "Nome do Solicitante",
    "requester_document_number": "30987145223",
    "request_control_key": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
    "created_account_key": "c2790f8c-2f93-5g87-b9e4-d437b3c90c78",
    "reserved_related_account": {
        "account_branch": "0001",
        "account_number": "5960388",
        "account_digit": "5",
        "document_number": "30987145223",
        "name": "Nome do Titular",
        "financial_institutions_code_number": "329",
        "financial_institutions": {
            "name": "QI Sociedade de Crédito Direto S.A.",
            "code_number": 329,
            "ispb": 32402502
        },
        "ted_account_type": {
            "enumerator": "checking_account",
            "translation_path": "...",
            "created_at": "2023-05-15T19:56:10"
        },
        "is_activated": true,
        "updated_at": "2023-05-15T19:56:10",
        "created_at": "2023-05-15T19:56:10"
    },
    "proposal_status": {
        "enumerator": "account_opened",
        "translation_path": "...",
        "created_at": "2023-05-15T19:56:10"
    },
    "account_type": {
        "enumerator": "checking",
        "translation_path": "...",
        "created_at": "2023-05-15T19:56:10"
    },
    "document_key": "3571e292-3a83-4011-904d-20ee963022ef",
    "document_template_key": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "is_simplified": false,
    "created_at": "2023-05-15T19:56:10",
    "signed_contract": null,
    "additional_documents": null,
    "events": [
        {
            "old_status": {
                "enumerator": "pending",
                "translation_path": "...",
                "created_at": "2023-05-15T19:56:10"
            },
            "new_status": {
                "enumerator": "account_opened",
                "translation_path": "...",
                "created_at": "2023-05-15T19:56:10"
            },
            "rejection_reason": null,
            "event_description": "Conta aberta com sucesso",
            "created_at": "2023-05-15T20:00:00"
        }
    ],
    "destinations": [
        {
            "account_branch": "0001",
            "account_number": "5960389",
            "account_digit": "7",
            "document_number": "30987145223",
            "name": "Nome do Destino",
            "financial_institutions_code_number": "329",
            "financial_institutions": {
                "name": "QI Sociedade de Crédito Direto S.A.",
                "code_number": 329,
                "ispb": 32402502
            },
            "ted_account_type": {
                "enumerator": "checking_account",
                "translation_path": "...",
                "created_at": "2023-05-15T19:56:10"
            },
            "is_activated": true,
            "updated_at": "2023-05-15T19:56:10",
            "created_at": "2023-05-15T19:56:10"
        }
    ],
    "attached_documents": [
        {
            "document_key": "c3d4e5f6-a7b8-9012-cdef-123456789012",
            "document_type": {
                "enumerator": "identity",
                "translation_path": "...",
                "created_at": "2023-05-15T19:56:10"
            },
            "description": "Documento de identidade",
            "document_url": "https://example.com/document.pdf",
            "is_activated": true,
            "updated_at": "2023-05-15T19:56:10",
            "created_at": "2023-05-15T19:56:10"
        }
    ],
    "related_parties": [
        {
            "person_key": "47d08366-a8ec-414c-a0a5-a089fc8a4ee8",
            "person_type": {
                "enumerator": "natural",
                "translation_path": "...",
                "created_at": "2023-05-15T19:56:10"
            },
            "individual_document_number": "30987145223",
            "company_document_number": null,
            "name": "Maria Luiza Vieira",
            "mother_name": "Dona Maria Mariane",
            "is_pep": false,
            "final_beneficiary": true,
            "is_signer": true,
            "is_activated": true,
            "address": {
                "street": "Av. Brigadeiro Faria Lima",
                "neighborhood": "Jardim Paulistano",
                "number": "2391",
                "postal_code": "01452905",
                "city": "São Paulo",
                "state": "SP",
                "country": "BR",
                "complement": "Complemento",
                "created_at": "2023-05-15T19:56:10"
            },
            "phone": {
                "phone_type": {
                    "enumerator": "mobile",
                    "translation_path": "...",
                    "created_at": "2023-05-15T19:56:10"
                },
                "country_code": "055",
                "area_code": "11",
                "number": "999999999",
                "created_at": "2023-05-15T19:56:10"
            },
            "nationality": "brasileira",
            "email": "teste@gmail.com",
            "birth_date": "1990-05-06",
            "role_type": {
                "enumerator": "account_holder",
                "translation_path": "...",
                "created_at": "2023-05-15T19:56:10"
            },
            "updated_at": "2023-05-15T19:56:10",
            "created_at": "2023-05-15T19:56:10"
        }
    ],
    "credit_operations": [],
    "automatic_transfer_config": {},
    "billing_configuration_data": null,
    "account_owner_data": null
}
```

### Response Body Params

| Campo | Tipo | Descrição |
|---|------|-----------|
| `proposal_key` | string | Chave única do pedido de conta |
| `contract_number` | string | Número do contrato |
| `requester_key` | string | Chave do solicitante |
| `requester_name` | string | Nome do solicitante |
| `requester_document_number` | string | CPF ou CNPJ do solicitante |
| `request_control_key` | string | Chave de controle da requisição |
| `created_account_key` | string | Chave da conta criada |
| `reserved_related_account` | object | Dados da conta relacionada reservada (pode ser `null`) |
| `proposal_status` | object | Status atual da proposta |
| `account_type` | object | Tipo da conta |
| `document_key` | string | Chave do documento |
| `document_template_key` | string | Chave do template do documento |
| `is_simplified` | boolean | Indica se é uma conta simplificada |
| `created_at` | datetime | Data de criação do pedido |
| `signed_contract` | object | Dados do contrato assinado (pode ser `null`) |
| `additional_documents` | array | Documentos adicionais (pode ser `null`) |
| `events` | array | Lista de eventos do pedido |
| `rejection_reason` | string | Motivo da rejeição, presente apenas se houver rejeição |
| `destinations` | array | Lista de destinos configurados |
| `attached_documents` | array | Lista de documentos anexados |
| `related_parties` | array | Lista de partes relacionadas |
| `credit_operations` | array | Lista de operações de crédito |
| `automatic_transfer_config` | object | Configuração de transferência automática |
| `billing_configuration_data` | object | Configuração de cobrança (pode ser `null`) |
| `account_owner_data` | object | Dados do titular da conta (pode ser `null`) |

### Objeto proposal_status / account_type

| Campo | Tipo | Descrição |
|---|------|-----------|
| `enumerator` | string | Valor do enumerador |
| `translation_path` | string | Caminho de tradução |
| `created_at` | datetime | Data de criação |

### Enumeradores proposal_status

| Enumerador | Descrição |
|------------|-----------|
| `pending` | Pendente |
| `pending_kyc_analysis` | Pendente de análise KYC |
| `account_opened` | Conta aberta |
| `rejected` | Rejeitado |
| `cancelled` | Cancelado |

### Enumeradores account_type

| Enumerador | Descrição |
|------------|-----------|
| `checking` | Conta corrente |
| `escrow` | Conta escrow |

### Objeto events

| Campo | Tipo | Descrição |
|---|------|-----------|
| `old_status` | object | Status anterior (mesmo formato de proposal_status) |
| `new_status` | object | Novo status (mesmo formato de proposal_status) |
| `rejection_reason` | string | Motivo da rejeição (pode ser `null`) |
| `event_description` | string | Descrição do evento |
| `created_at` | datetime | Data do evento |

### Objeto destinations / reserved_related_account

| Campo | Tipo | Descrição |
|---|------|-----------|
| `account_branch` | string | Agência |
| `account_number` | string | Número da conta |
| `account_digit` | string | Dígito verificador |
| `document_number` | string | CPF ou CNPJ |
| `name` | string | Nome do titular |
| `financial_institutions_code_number` | string | Código da instituição financeira |
| `financial_institutions` | object | Dados da instituição financeira |
| `ted_account_type` | object | Tipo da conta TED |
| `is_activated` | boolean | Se o destino está ativo |
| `updated_at` | datetime | Data de atualização |
| `created_at` | datetime | Data de criação |

### Objeto attached_documents

| Campo | Tipo | Descrição |
|---|------|-----------|
| `document_key` | string | Chave única do documento |
| `document_type` | object | Tipo do documento (formato enumerador) |
| `description` | string | Descrição do documento |
| `document_url` | string | URL do documento |
| `is_activated` | boolean | Se o documento está ativo |
| `updated_at` | datetime | Data de atualização |
| `created_at` | datetime | Data de criação |

### Objeto related_parties

| Campo | Tipo | Descrição |
|---|------|-----------|
| `person_key` | string | Chave única da pessoa |
| `person_type` | object | Tipo de pessoa (formato enumerador) |
| `individual_document_number` | string | CPF |
| `company_document_number` | string | CNPJ |
| `name` | string | Nome |
| `mother_name` | string | Nome da mãe |
| `is_pep` | boolean | Se é pessoa politicamente exposta |
| `final_beneficiary` | boolean | Se é beneficiário final |
| `is_signer` | boolean | Se é signatário |
| `is_activated` | boolean | Se está ativo |
| `address` | object | Endereço |
| `phone` | object | Telefone |
| `nationality` | string | Nacionalidade |
| `email` | string | Email |
| `birth_date` | string | Data de nascimento |
| `role_type` | object | Tipo de papel (formato enumerador) |
| `updated_at` | datetime | Data de atualização |
| `created_at` | datetime | Data de criação |

## Erros

STATUS 404

Response Body: Pedido de conta não encontrado

```json
{
    "title": "Proposal Not Found",
    "description": "Proposal not found.",
    "translation": "Proposta não encontrada.",
    "code": "ACR000003"
}
```

STATUS 400

Response Body: Tipo de conta não suportado

```json
{
    "title": "Temporarily unavailable",
    "description": "Temporarily unavailable",
    "translation": "Temporariamente indisponível",
    "code": "ACR000068"
}
```

STATUS 403

Response Body: Usuário não possui credenciais

```json
{
    "title": "Permission Validator Error",
    "description": "Selected agent do not own this item.",
    "translation": "O agente selecionado não é dono do item.",
    "code": "QIT000005"
}
```

---

# Encerramento de conta

URL: /documentation/contas/encerramento_de_conta

## Request

ENDPOINT /account/ ACCOUNT_KEY /cancel
MÉTODO PATCH

## Response

STATUS 200

**Response Body**

```json
{
	"account_block_reason": null,
	"account_branch": "0001",
	"account_credentials": [{
			"account_id": 3493,
			"created_at": "2023-01-04T11:10:53",
			"credential_type": {
				"created_at": "2019-06-18T13:19:30",
				"enumerator": "observer",
				"id": 3,
				"translation_path": "account.CredentialType.observer"
			},
			"credential_type_id": 3,
			"id": 3456,
			"is_active": true,
			"person_key": "10ffdcef-6ac7-4ca0-9932-8a0e49ff5972",
			"updated_at": null
		},
		{
			"account_id": 3493,
			"created_at": "2023-01-04T11:10:53",
			"credential_type": {
				"created_at": "2019-06-18T13:19:30",
				"enumerator": "requester",
				"id": 2,
				"translation_path": "account.CredentialType.requester"
			},
			"credential_type_id": 2,
			"id": 3457,
			"is_active": true,
			"person_key": "78269442-caa1-4767-a049-0291b0321063",
			"updated_at": null
		}
	],
	"account_digit": "9",
	"account_documents": [],
	"account_events": [{
			"account_id": 3493,
			"created_at": "2023-01-04T11:10:53",
			"id": 5284,
			"new_account_status": {
				"created_at": "2019-10-11T18:58:31",
				"enumerator": "blocked",
				"id": 3,
				"translation_path": "account.AccountStatus.blocked"
			},
			"new_account_status_id": 3,
			"old_account_status": null,
			"old_account_status_id": null
		},
		{
			"account_id": null,
			"created_at": null,
			"id": null,
			"new_account_status": {
				"created_at": "2019-10-11T18:58:31",
				"enumerator": "closed",
				"id": 2,
				"translation_path": "account.AccountStatus.closed"
			},
			"new_account_status_id": null,
			"old_account_status": {
				"created_at": "2019-10-11T18:58:31",
				"enumerator": "blocked",
				"id": 3,
				"translation_path": "account.AccountStatus.blocked"
			},
			"old_account_status_id": null
		}
	],
	"account_key": "91e42ceb-53f7-4dc5-ab75-db30b1de491f",
	"account_name": "Default",
	"account_number": "2765703",
	"account_status": {
		"created_at": "2019-10-11T18:58:31",
		"enumerator": "closed",
		"translation_path": "account.AccountStatus.closed"
	},
	"account_type": {
		"created_at": "2019-03-15T13:09:15",
		"enumerator": "checking",
		"translation_path": "account.AccountType.checking"
	},
	"automatic_transfer_management_status": {
		"created_at": "2022-10-27T13:48:18",
		"enumerator": "master"
	},
	"automatic_transfers": [],
	"balance": 0.0,
	"blocked_balance": 0.0,
	"blocked_balance_events": [],
	"created_at": "2023-01-04T11:10:53",
	"destinations": [],
	"fee": 0.0,
	"internal_webhooks": [],
	"investment_available_amount": 0.0,
	"investment_configuration": null,
	"is_system_account": false,
	"owner_document_number": "23426525852",
	"owner_name": "Murilo Almeida",
	"owner_person_key": "10ffdcef-6ac7-4ca0-9932-8a0e49ff5972",
	"permitted_person_keys": ["10ffdcef-6ac7-4ca0-9932-8a0e49ff5972",
		"10ffdcef-6ac7-4ca0-9932-8a0e49ff5972",
		"78269442-caa1-4767-a049-0291b0321063"
	],
	"requester_key": "78269442-caa1-4767-a049-0291b0321063",
	"requester_name": "Salgadinhos Show (BAAS)",
	"setup_fee": null,
	"transactional_limit": null,
	"url": "https://storage.googleapis.com/sandbox-doc-api/documents/e054a511-a8db-4c6e-abbe-f376f36fb39c/e054a511-a8db-4c6e-abbe-f376f36fb39c.pdf",
	"webhook_enabled": true
}
```

:::caution **Atenção!**

É importante que o PDF do comporvante de encerramento de conta devolvido no campo **"url"** seja apresentado para o cliente.

:::

### Path Params

| Campo | Tipo | Descrição |
|---|---| ---|
| `account_key` * | string | Chave da conta. | 

## Response

STATUS 400

**Response Body**

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

### Erros

| Codigo | Status code | Descrição | 
|---|---|---|
| ACC000006  | 404  | Account not found for the given key \{account_key\} |
| QIT000003  | 403  | The agent does not have enough roles. |
| ACC000127  | 500  | Failed to create account cancelling term |
| ACC000011  | 423  | Closed accounts can not perform this action. |
| ACC000123  | 400  | Account balance cannot be greater than 0. |
| ACC000124  | 400  | Can't perform this action. There'are few unpaid future transactions |
| ACC000125  | 400  | Can't perform this action. There'are few unpaid bankslip fees |
| ACC000126  | 400  | There'are few accepted or registered bankslips yet |

## Webhook

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

Abaixo está descrito o webhook disparado quando uma conta é encerrada.

WEBHOOK_TYPE baas.account.status_change

Webhook Body

```json
{
  "webhook_type": "baas.account.status_change",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
	"account_key":"91e42ceb-53f7-4dc5-ab75-db30b1de491f",
	"account_status":"closed"
  }
}
```

---

# Extrato de tarifas

URL: /documentation/contas/extrato_de_tarifas

Retorna uma lista das tarifas cobradas em uma conta de cobrança específica no período selecionado.

## Request

ENDPOINT /billing/requester_configuration/billing_account/ BILLING_ACCOUNT_KEY /invoices
MÉTODO GET

### Path Params

| Campo | Tipo | Descrição |
|---|---| ---|
| `BILLING_ACCOUNT_KEY` | string | id (uuid) da conta de cobrança cujas tarifas serão listadas. |

## Query Params

| Campo | Tipo | Descrição |
|---|---| ---|
| `start_date` | string | Data inicial do período, no formato `aaaa-mm-dd`. Opcional. |
| `end_date` | string | Data final do período, no formato `aaaa-mm-dd`. Opcional. |
| `status` | string | Filtra pelo status da tarifa. Opcional. **[Enumerador status](#enumerador-status)** |
| `billing_type` | string | Filtra pelo tipo de tarifa. Pode ser informado mais de uma vez para combinar tipos. Opcional. |
| `page` | integer | Número da página. Padrão `1`. |
| `page_size` | integer | Quantidade de tarifas por página. Padrão `20`, máximo `50`. |

## Response

STATUS 200

**Response Body**

```json
{
  "data": [
    {
      "invoice_key": "d1f4a2b6-8c3e-4f5a-9b7d-2e6c8a0f1d3b",
      "reference_date": "2026-06-01",
      "billing_type": "account_maintenance",
      "billing_type_description": "Tarifa de Manutenção de Conta",
      "status": "paid",
      "total_amount": 30.00,
      "paid_amount": 30.00,
      "amount_owed": 0.00
    },
    {
      "invoice_key": "b2e5c3a7-9d4f-4a6b-8c1e-3f7d9b1a2c4e",
      "reference_date": "2026-06-15",
      "billing_type": "outgoing_ted",
      "billing_type_description": "Tarifa de Envio de TED",
      "status": "open",
      "total_amount": 20.00,
      "paid_amount": 0.00,
      "amount_owed": 20.00
    }
  ],
  "page": 1,
  "page_size": 20,
  "has_next_page": false
}
```

### Response Body

| Campo | Tipo | Descrição |
|---|---| ---|
| `data` | array | Lista de tarifas cobradas. **[Data](#data)** |
| `page` | integer | Página retornada. |
| `page_size` | integer | Quantidade de tarifas por página. |
| `has_next_page` | boolean | Indica se existem mais páginas de resultados. |

### Data

| Campo | Tipo | Descrição |
|---|---| ---|
| `invoice_key` | string | id (uuid) da tarifa. |
| `reference_date` | string | Data de referência da tarifa, no formato `aaaa-mm-dd`. |
| `billing_type` | string | Tipo da tarifa (enumerador). |
| `billing_type_description` | string | Descrição do tipo da tarifa. |
| `status` | string | Status da tarifa. **[Enumerador status](#enumerador-status)** |
| `total_amount` | number | Valor total da tarifa. |
| `paid_amount` | number | Valor já pago da tarifa. |
| `amount_owed` | number | Valor em aberto da tarifa. Tarifas baixadas (`written_off`) retornam `0`. |

# Enumeradores

### Enumerador _Status_

| Enumerador | Descrição |
|---|---|
| **open** | Tarifa em aberto. |
| **pending** | Tarifa aguardando pagamento. |
| **paid** | Tarifa quitada. |
| **written_off** | Tarifa baixada. |

STATUS 4XX

**Response Body: Error**

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo"
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`          | Descrição (eng)<br/>`description`                    | Descrição (ptbr)<br/>`translation`                          |
|-------------|----------------------|-----------------------------|------------------------------------------------------|-------------------------------------------------------------|
| 400         | BLL000096            | Invalid Date Format         | Dates must be formatted as 'yyyy-mm-dd'.             | Datas devem ser formatadas como 'aaaa-mm-dd'                |
| 400         | BLL000043            | Bad Request                 | Invalid status enumerator                            | Status informado não é válido                               |
| 400         | BLL000090            | Invalid value for params    | Page Size and Page Number must be integers           | Page Size e Page Number devem ser números inteiros          |
| 400         | BLL000091            | Page size too large         | Requested page size above limit of 50                | Tamanho de página requerido acima do limite de 50           |
| 400         | BLL000063            | Bad Request                 | Not allowed to view fees in unavailable accounts     | Conta indisponível.                                         |

---

# Gestão de tarifas

URL: /documentation/contas/gestao_de_tarifas

## Request

ENDPOINT /account/ ACCOUNT_KEY /billing_configuration
MÉTODO PUT

:::danger Definição e Repasse de Tarifas
Os valores máximos e mínimos de cada tarifa devem ser alinhados com o time comercial da QI Tech.

O valor a ser repassado ao parceiro, referente a cada tarifa cobrada, também deve ser alinhado junto ao time comercial da QI Tech.
:::

:::danger Observações Gerais:
Para este endpoint, é importante que o "Request Body" seja seguido a risca visto que todos os campos são de carater obrigatório.
:::

**Request Body**

```json
{
   "billing_configuration_data":{
      "bank_slip":{
         "registration":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":10,
            "expense_type":"fixed_amount"
         },
         "bank_slip_instant_registration":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "permanence":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":10,
            "expense_type":"fixed_amount"
         },
         "protest_removal":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "protest_request":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "protest_costs":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"percentage"
         },
         "expiration_date_change":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "rebate_inclusion":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "discount_inclusion":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "notary_office_payment":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "expiration_write_off":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "write_off":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "protest_write_off":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "protest_removal_and_write_off":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "payment":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "payment_qr_code":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "payment":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "fine_or_interest_inclusion":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "bank_slip_fine_alteration":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "bank_slip_interest_alteration":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "bank_slip_discount_alteration":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
      },
      "ted":{
         "outgoing_ted":{
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435",
            "amount":20,
            "expense_type":"fixed_amount",
         },
         "incoming_ted":{
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435",
            "amount":20,
            "expense_type":"fixed_amount"
         }
      },
      "pix_transfer":{
         "incoming_pix":{
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435",
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "outgoing_pix":{
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435",
            "amount":20,
            "expense_type":"fixed_amount"
         },
      },
      "account": {
         "account_maintenance":{
            "amount":40,
            "expense_type": "fixed_amount",
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435"
         },
         "incoming_funds":{
            "amount":10,
            "expense_type": "percentage",
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435"
         },
         "account_creation":{
            "amount":40,
            "expense_type": "fixed_amount",
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435"
         }
      },
      "qr_code": {
         "dynamic_qr_code_expiration":{
            "amount":40,
            "expense_type": "fixed_amount",
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435"
         }
      },
      "prepaid_card": {
         "prepaid_fisical_card_creation":{
            "amount":40,
            "expense_type": "fixed_amount",
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435"
         },
         "prepaid_virtual_card_creation":{
            "amount":40,
            "expense_type": "fixed_amount",
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435"
         },
         "card_withdrawal_fee":{
            "amount":40,
            "expense_type": "fixed_amount",
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435"
         },
         "international_card_withdrawal_fee":{
            "amount":40,
            "expense_type": "fixed_amount",
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435"
         }
      },
      "automatic_pix": {
         "active_recurrence": {
            "amount":0.50,
            "expense_type": "fixed_amount",
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435"
         },
         "recurrence_settlement": {
            "amount":0.80,
            "expense_type": "fixed_amount",
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435"
         }
      }
   }
}

```

### Body Params

| Campo | Tipo | Descrição |
|---|---| ---|
| `billing_configuration_data` | object  | **[Billing_configuration_data](#billing_configuration_data)**  |

### Billing_configuration_data

| Campo | Tipo | Descrição  |
|---| ---| ---|
| `bank_slip` | object  | **[Bankslip](#bank_slip)**  |
| `ted` | object  | **[TED](#ted)**  |
| `pix_transfer` | object  | **[Pix](#pix)**  |
| `account` | object  | **[Conta](#account)**  |
| `prepaid_card` | object  | **[Conta](#prepaid_card)**  |
| `qr_code` | object  | **[Conta](#qr_code)**  |
| `automatic_pix` | object  | **[Pix Automático](#automatic_pix)**  |

### BankSlip 

| Campo | Tipo | Descrição | Referência
|---|---|---|---|
| `registration` | object  |  Tarifa de registro | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `permanence` | object  | Tarifa de permanência título cadastrado | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `protest_removal` | object  | Tarifa de sustação/Excl Negativação | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `protest_request` | object  | Tarifa de protesto/Incl Negativação | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `protest_costs` | object  | Custas de Protestos, para esse campo **expense_type deve ser 'percentage'** | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `expiration_date_change` | object  | Tarifa alteração de vencimento | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `rebate_inclusion` | object  | Tarifa concessão abatimento | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `discount_inclusion` | object  | Tarifa concessão desconto | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `notary_office_payment` | object  | Tarifa título Baix. Pg. Cartório | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `expiration_write_off` | object  | Tarifa título baixado decurso prazo | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `write_off` | object  | Tarifa título baixado conf. Pedido | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `protest_write_off` | object  | Tarifa título baixado protestado | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `protest_removal_and_write_off` | object  | Tarifa título baixado SUST/RET/CARTÓRIO | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `payment` | object  | Tarifa Liquidação | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `payment_qr_code` | object  | Tarifa Liquidação por QR-Code  | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `fine_or_interest_inclusion` | object  | Tarifa de inclusão de Multa e Juros | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `bank_slip_fine_alteration` | object  | Tarifa de alteração de Multa | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `bank_slip_interest_alteration` | object  | Tarifa de alteração de Juros | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `bank_slip_discount_alteration` | object  | Tarifa de alteração de Desconto | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `bank_slip_instant_registration` | object  | Tarifa de registro de boleto instantâneo | **[Objeto padrão fees](#objeto-padrão-fees)** |

### Ted 

| Campo | Tipo | Descrição | Referência
|---|---|---|----|
| `outgoing_ted` | object  | Tarifa de Envio de TED | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `incoming_ted` | object  | Tarifa de Entrada de TED | **[Objeto padrão fees](#objeto-padrão-fees)** |

### Pix 

| Campo | Tipo | Descrição | Referência
|---|---|---|---|
| `incoming_pix` | object  | Tarifa de Entrada de Pix | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `outgoing_pix` | object  | Tarifa de Envio de Pix | **[Objeto padrão fees](#objeto-padrão-fees)** |

### Account 

| Campo | Tipo | Descrição | Referência
|---|---|---|---|
| `incoming_funds` | object  | Tarifa de Entrada de Recurso | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `account_maintenance` | object  | Tarifa de Manutenção de Conta | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `account_creation` | object  | Tarifa de Criação de Conta | **[Objeto padrão fees](#objeto-padrão-fees)** |

### QrCode 

| Campo | Tipo | Descrição | Referência
|---|---|---|---|
| `dynamic_qr_code_expiration` | object  | Tarifa de Expiração de QR-Code Dinâmico não Liquidado | **[Objeto padrão fees](#objeto-padrão-fees)** |

### PrepaidCard 

| Campo | Tipo | Descrição | Referência
|---|---|---|---|
| `prepaid_fisical_card_creation` | object  | Tarifa de Criação de Cartão Físico | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `prepaid_virtual_card_creation` | object  | Tarifa de Criação de Cartão Virtual | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `card_withdrawal_fee` | object  | Tarifa de Saque | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `international_card_withdrawal_fee` | object  | Tarifa de Saque Internacional | **[Objeto padrão fees](#objeto-padrão-fees)** |

### Pix Automático

| Campo | Tipo | Descrição | Referência
|---|---|---|---|
| `active_recurrence` | object  | Tarifa de Recorrência ativa de Pix | **[Objeto padrão fees](#objeto-padrão-fees)** |
| `recurrence_settlement` | object  | Tarifa de Liquidação de Recorrência de Pix | **[Objeto padrão fees](#objeto-padrão-fees)** |

### Objeto padrão fees

| Campo | Tipo | Descrição | Referência
|---|---|---|---|
| `amount` | number | Valor da taxa a qual poderá representar em valor absoluto (fixed_amount) ou porcentagem (percentage), deve ser limitado a duas casas decimais|
| `expense_type` | enum | Formato de cobrança | **[Enumerador expense_type](#enumerador-expense-type)** 
| `billing_account_key` | string | id (uuid) contendo a referência para a conta a qual será cobrada a taxa | 

# Enumeradores

### Enumerador _Expense Type_
| Enumerador            | Descrição                                                                 |
|-----------------------|---------------------------------------------------------------------------|
| **percentage**        | Valor em porcentagem                                                      |
| **fixed_amount**    | Valor absoluto                                  |

## Response

STATUS 200

**Response Body**

```json
{
   "account_key": "3a4fe5f9-3133-4ce3-9988-9ff8827bcaa5",
   "billing_configuration_data":{
      "bank_slip":{
         "registration":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":10,
            "expense_type":"fixed_amount"
         },
         "bank_slip_instant_registration":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "permanence":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":10,
            "expense_type":"fixed_amount"
         },
         "protest_removal":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "protest_request":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "protest_costs":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"percentage"
         },
         "expiration_date_change":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "rebate_inclusion":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "discount_inclusion":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "notary_office_payment":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "expiration_write_off":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "write_off":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "protest_write_off":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "protest_removal_and_write_off":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "payment":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "payment_qr_code":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "payment":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "fine_or_interest_inclusion":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "bank_slip_fine_alteration":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "bank_slip_interest_alteration":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "bank_slip_discount_alteration":{
            "billing_account_key": "f6bc82ae-8ede-424d-9450-242a8c9d2435", 
            "amount":20,
            "expense_type":"fixed_amount"
         },
      },
      "ted":{
         "outgoing_ted":{
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435",
            "amount":20,
            "expense_type":"fixed_amount",
         },
         "incoming_ted":{
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435",
            "amount":20,
            "expense_type":"fixed_amount"
         }
      },
      "pix":{
         "incoming_pix":{
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435",
            "amount":20,
            "expense_type":"fixed_amount"
         },
         "outgoing_pix":{
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435",
            "amount":20,
            "expense_type":"fixed_amount"
         },
      },
      "account": {
         "account_maintenance":{
            "amount":40,
            "expense_type": "fixed_amount",
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435"
         },
         "incoming_funds":{
            "amount":10,
            "expense_type": "percentage",
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435"
         },
         "account_creation":{
            "amount":40,
            "expense_type": "fixed_amount",
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435"
         }
      },
      "qr_code": {
         "dynamic_qr_code_expiration":{
            "amount":40,
            "expense_type": "fixed_amount",
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435"
         }
      },
      "prepaid_card": {
         "prepaid_fisical_card_creation":{
            "amount":40,
            "expense_type": "fixed_amount",
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435"
         },
         "prepaid_virtual_card_creation":{
            "amount":40,
            "expense_type": "fixed_amount",
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435"
         },
         "card_withdrawal_fee":{
            "amount":40,
            "expense_type": "fixed_amount",
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435"
         },
         "international_card_withdrawal_fee":{
            "amount":40,
            "expense_type": "fixed_amount",
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435"
         }
      },
      "automatic_pix": {
         "active_recurrence": {
            "amount":0.50,
            "expense_type": "fixed_amount",
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435"
         },
         "recurrence_settlement": {
            "amount":0.80,
            "expense_type": "fixed_amount",
            "billing_account_key":"f6bc82ae-8ede-424d-9450-242a8c9d2435"
         }
      }
   }
}
```

STATUS 400

**Response Body**

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

---

# Informe de rendimentos

URL: /documentation/contas/informe_rendimentos

## Request

ENDPOINT /account/ ACCOUNT_KEY /income_report/ REFERENCE_YEAR
MÉTODO POST

Request Body - Titular PF

```json
{
  "partner_logo": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAHgAAAAiCAYAAACUc"
}
```

| Campo          | Descrição                                                                                                                                                                                                                                                                          | Exemplo                          |
|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------|
| `partner_logo` | logo do perceiro que será apresentada do lado esquerdo do header do informe de rendimentos caso seja forncecida, caso contrário será exibido apenas a logo da QI no canto superior direito. A imagem deve ser fornecida no padrão utilizado no html data:image/png;FORMATO,base64  | data:image/png;base64,iVBORw0... |

### Path Params
| Campo          | Tipo| Descrição                                                                                        |
|----------------|-----|--------------------------------------------------------------------------------------------------|
| `REFERENCE_YEAR` | number | Ano de referência do informe|
| `ACCOUNT_KEY` | UUUID |Chave da conta que deseja consultar o informe | 

## Response
Será retornado um blob(base64) que deve ser convertido para o pdf do imforme de rendimentos.

STATUS 200

**Response Body**

```json
{
  "income_report_blob": "JVBERi0xLjcKJfCflqQKMSAwIG9iago8PC9UeXBlIC9QYWdlcy9LaWRzIFs2IDAgUl0vQ291bnQgMT4+CmVuZG9iagoyIDAgb2JqCjw8L1Byb2R1Y2VyIChXZWFzeVByaW50IDU3LjEpPj4KZW5kb2JqCjMgMCBvYmoKPDwvVHlwZSAvQ2F0YWxvZy9QYWdlcyAxIDAgUi9PdXRsaW5lcyAxNiAwIFI+PgplbmRvYmoKNCAwIG9iago8PC9FeHRHU3RhdGUgPDwvYTEuMCA8PC9jYSAxPj4+Pi9YT2JqZWN0IDw8L2kzYWNiNTAyY2ZjMzRmMGU0N2Y0NjlkMDJiMGRjNzExMSAyOCAwIFI+Pi9QYXR0ZXJuIDw8Pj4vU2hhZGluZyA8PD4+L0ZvbnQgMjcgMCBSPj4KZW5kb2JqCjUgMCBvYmoKPDwvRmlsdGVyIC9GbGF0ZURlY29kZS9MZW5ndGggMTU1Nz4+CnN0cmVhbQp42u1Y3YscNwx/379ingOZWLLlDzgOWpo+lJI25eAKpQ+7s9lQuLQk/f+h8tgey/OVLUnuXo69vR3LsvXThyV5oFP8eQn8zxvovQ/Omm74cPh4UL2jcXZ6GMnpM9K7T+8Pr47Qq+79vwdveIfOIvVOKeddR7a3wapguk/vDl53/GfRTbNezF5eHPgBHBYaBteDclq5DsD3qDQgRc6gmQ0qW5jYUAk23tAoPc3JjW1PQRs/29corNxif1+459t/PDhQRRkNbLoQEEL3Iaoqxg9pjHXcrBP0+xeHv2fMwl6oVE8GjKFsTiGjYUPBxjjftkgJTG+MsuzkEakYP6SxruNmnaCPSFci4Ftj1zPseoZd0zp2Sd/GLtgEKGt6tGhDgS6ESi4ruJbIrYqPWlOODzFOyDmOp7FELulPgxxnyLFFbhFWkTf0beSCbQe5EPo/kHvbB2sVUUZexwm5pzpu1gn6kyB3qkUuxg9p7FaRN/Rt5IJNYALjGJSCCbqQ2rAFwbbE7jnrIyuXodfhQxrSNGwWVfJT4XYtbtfidm4VtyBv465cO4FSBV4fJ8Fgb7himwxajB/SGOq4WSfoT4HbznDbGW6r13FL+jZuwbYDXAi9Hjko9NwMgTWQoEvCQya4SmiXionHQx8/o897bmOU4SfV6bHpumcIMEKAruEY27yQ0L1k3nEBE1/9pY/DiRQOl0Gbi3pn3MXYcFZ4UufBAUD3wz8sNH2W2n1/l+Vxu8mlv0fHkRO4EQu9doFbvu6Ohfx2/92b33/kZqC7uxz+uFEsTikCpUzgX24liPireOz5n+bfIY1J53muruTS8zjvKm9cG5/H/SLdJDowHcqvvf2zu/vp8Poum8+CrUdn14yrnI9hTlDcPgfog/MaRzO+uf/l57e/8kQxozbJlFFdbZN5jE3miyYp5pDmks9ok/mOp0wfWjNjoRUTizltbzUxBmCzo4m/ycQNfuQW08IY06zA6HkWqXmJjtufb42KW5yzx2z2Fs+DE96LYy/GmJ/LN4pXeb1fg8HNFFIgN6EYksFGFLSCQEqfJK/tzMWQYzjWIKHgiao9zbEN2+mZkm/GsM2+W8AYZiIN1AuQDI0xGKQDo/MvWYDQb9Tb3ZK5SU7TvgYPmm1hG36MO4YcBgV6/J6yz45RhawO5F+Xv1s+DCuWlkgWrsy2i3akHO+NHb1wo82AKAvTO4KWnjXJm8ehem30sJmpP6m0s7vjW6hRHh8lbOL1jBuE4A14mZCBpkwyT6JDTcjFsiURT9kmBtk5Z5phyXMsmcLdOrzJWWRIKpCv3jqymY8ksk6cO2X7XjJvtjWFYu+Ziki691p5i532fBNF47ApPmAnXSGbMB+UKbuda/HYLTAbtpncYETxic/HpTsMVxV2lw6wkdmvlFlCgoRNE5aZTKtDT6Q12s6glF2kKSfQl0Aq5+YokrBZ0Ya7VM8nKto47xhuA9zk6nOpRX60Z4kTV+cXlSkmKozpZeaDcjw29TR81QOymo8bLVBJPYt+J3FiIevvVnS0ga/aY6/3NXWkff1i3C91ZMXQuaDZl26BSuoYcr5zV/gw2J7zEdrGWlfH4CXPm5wXdn1UY5HUmtQmFudleMh6RL+FpR7EfTVx8kb6OplubFXt+vwyC1nVx8TFR4sCcrfIVt044WP9ef5+wXfpe0t8N/OlXf7yIrdTuI46F6NS/PIaglpEMB/2UshKN7ZW9JrEYFJhLYWPZnMjVl8Ty14YWm40rHKW7HMYPlYYOu366KRUeJZxiCIOS9xM/p1dudrGau5n7nQc98LKds7Z3sfChxtNj63x0vSTPp2B6To4b6VV7TOJ2maoxOUi/uJLJIQe49sAt9HgXIFnaqBw9tzc7PebgBbHosBYcSkIuciUm8ppRSvjes9Hiuqt6xo9rMBuxB32s3rUQrkiWepxyjoUPXQu+lAagKUugUuvBkCAjSjdeTkgo7ZoKbPl0dToluv2MlXQpmfcZNxzpnqsTBW4SSGnORQ2YmDrPV2uYKecAaZmqWSK/O5uPBV+WWWnSug/30iBQtXroNHgc2B8y8B4fTe9mXz7Hz3zhdAKZW5kc3RyZWFtCmVuZG9iago2IDAgb2JqCjw8L1R5cGUgL1BhZ2UvUGFyZW50IDEgMCBSL01lZGlhQm94IFswIDAgNTk1LjI3NTU5MSA4NDEuODg5NzY0XS9Db250ZW50cyA1IDAgUi9SZXNvdXJjZXMgNCAwIFIvVHJpbUJveCBbMCAwIDU5NS4yNzU1OTEgODQxLjg4OTc2NF0vQmxlZWRCb3ggWzAgMCA1OTUuMjc1NTkxIDg0MS44ODk3NjRdPj4KZW5kb2JqCjcgMCBvYmoKPDwvVGl0bGUgKEluZm9ybWUgaW1wb3N0byBkZSByZW5kYSAyMDIzKS9EZXN0IFs2IDAgUiAvWFlaIDEzNSA3NjYuNDM5NzY0IDBdL0NvdW50IDgvRmlyc3QgOCAwIFIvTGFzdCAxNSAwIFIvUGFyZW50IDE2IDAgUj4+CmVuZG9iago4IDAgb2JqCjw8L1RpdGxlIDxmZWZmMDA1MjAwNjUwMDZlMDA2NDAwNjkwMDZkMDA2NTAwNmUwMDc0MDA2ZjAwNzMwMDIwMDA1MzAwNzUwMDZhMDA2NTAwNjkwMDc0MDA2ZjAwNzMwMDIwMDBlMDAwMjAwMDU0MDA3MjAwNjkwMDYyMDA3NTAwNzQwMDYxMDBlNzAwZTMwMDZmMDAyMDAwNDUwMDc4MDA2MzAwNmMwMDc1MDA3MzAwNjkwMDc2MDA2MTAwM2E+L0Rlc3QgWzYgMCBSIC9YWVogNjIuMjUgNTk1Ljk2NTM1IDBdL0NvdW50IDEvRmlyc3QgOSAwIFIvTGFzdCA5IDAgUi9QYXJlbnQgNyAwIFIvTmV4dCAxMCAwIFI+PgplbmRvYmoKOSAwIG9iago8PC9UaXRsZSAoTmF0dXJlemEgZGUgcmVuZGltZW50bzogMTIwMTcpL0Rlc3QgWzYgMCBSIC9YWVogNjIuMjUgNTY2Ljc4ODc5NyAwXS9Db3VudCAwL1BhcmVudCA4IDAgUj4+CmVuZG9iagoxMCAwIG9iago8PC9UaXRsZSAoUmVuZGltZW50b3MgSXNlbnRvczopL0Rlc3QgWzYgMCBSIC9YWVogNjIuMjUgNDI5LjA1OTI2NiAwXS9Db3VudCAwL1ByZXYgOCAwIFIvUGFyZW50IDcgMCBSL05leHQgMTEgMCBSPj4KZW5kb2JqCjExIDAgb2JqCjw8L1RpdGxlIDxmZWZmMDA1MjAwNjUwMDZlMDA2NDAwNjkwMDZkMDA2NTAwNmUwMDc0MDA2ZjAwNzMwMDIwMDA1NDAwNzIwMDY5MDA2MjAwNzUwMDc0MDBlMTAwNzYwMDY1MDA2OTAwNzMwMDIwMDA2ZTAwNjEwMDIwMDA0NDAwNjUwMDYzMDA2YzAwNjEwMDcyMDA2MTAwZTcwMGUzMDA2ZjAwMjAwMDY0MDA2NTAwMjAwMDQxMDA2YTAwNzUwMDczMDA3NDAwNjUwMDIwMDA0MTAwNmUwMDc1MDA2MTAwNmMwMDNhPi9EZXN0IFs2IDAgUiAvWFlaIDYyLjI1IDM2NC4zNjIyNDQgMF0vQ291bnQgMC9QcmV2IDEwIDAgUi9QYXJlbnQgNyAwIFIvTmV4dCAxMiAwIFI+PgplbmRvYmoKMTIgMCBvYmoKPDwvVGl0bGUgKEJlbnMgZSBEaXJlaXRvcykvRGVzdCBbNiAwIFIgL1hZWiA2Mi4yNSAyOTkuNjY1MjIzIDBdL0NvdW50IDEvUHJldiAxMSAwIFIvRmlyc3QgMTMgMCBSL0xhc3QgMTMgMCBSL1BhcmVudCA3IDAgUi9OZXh0IDE0IDAgUj4+CmVuZG9iagoxMyAwIG9iago8PC9UaXRsZSAoU2FsZG8gZW0gQ29udGEtY29ycmVudGU6KS9EZXN0IFs2IDAgUiAvWFlaIDYyLjI1IDI3MC40ODg2NyAwXS9Db3VudCAwL1BhcmVudCAxMiAwIFI+PgplbmRvYmoKMTQgMCBvYmoKPDwvVGl0bGUgPGZlZmYwMDQzMDA3MjAwZTkwMDY0MDA2OTAwNzQwMDZmMDA3MzAwMjAwMDY1MDA2ZDAwMjAwMDU0MDA3MjAwZTIwMDZlMDA3MzAwNjkwMDc0MDA2ZjAwM2E+L0Rlc3QgWzYgMCBSIC9YWVogNjIuMjUgMTcyLjcyMDA3NiAwXS9Db3VudCAwL1ByZXYgMTIgMCBSL1BhcmVudCA3IDAgUi9OZXh0IDE1IDAgUj4+CmVuZG9iagoxNSAwIG9iago8PC9UaXRsZSA8ZmVmZjAwNDkwMDZlMDA2NjAwNmYwMDcyMDA2ZDAwNjEwMGU3MDBmNTAwNjUwMDczMDAyMDAwNDMwMDZmMDA2ZDAwNzAwMDZjMDA2NTAwNmQwMDY1MDA2ZTAwNzQwMDYxMDA3MjAwNjUwMDczMDAzYT4vRGVzdCBbNiAwIFIgL1hZWiA2Mi4yNSAxMDguMDIzMDU1IDBdL0NvdW50IDAvUHJldiAxNCAwIFIvUGFyZW50IDcgMCBSPj4KZW5kb2JqCjE2IDAgb2JqCjw8L0NvdW50IDkvRmlyc3QgNyAwIFIvTGFzdCA3IDAgUj4+CmVuZG9iagoxNyAwIG9iago8PC9MZW5ndGgxIDg4MzIvRmlsdGVyIC9GbGF0ZURlY29kZS9MZW5ndGggMzYzOT4+CnN0cmVhbQp42u06a1hUR5an7gt8ERpo8BGUtnkElRhpGpMYxTjSYoYAAjJIjPIWFOhGFLhkXEXWtAhK4qggMQQJQ9SQDfE9jBGUSdQxiWOia9SMqKzjzsZNTNYkM0BXz6nbDyFrdj+/nf2++UGd795bVffUedY5dfoBBABGwTrgIc5gSHz+lfTWBgDNdZx9dN7cSIN4UfwUx/04Xh+bMDU0v+OAAYAk4zgpIz/N5DLD1R9g5KM4/t2ytCITuCCA5gKORy7Lk7NfqS78LwCP0QBuUk5WWqa27qsmfPcFXuE5OPFIuOtJpOeFY/+c/FWl1jbVPRy3AQzPyzNmpN1Rfb0SSaE84pP5aaUmrhnK8P2TiO9XkJafNeHTpyKw64dzW03GolXWq5CC/A+y98B045Yc/SF5XdjSR575Dia4AmtX/rPBzJ43PnjrlDWHPuUaJWUjritwYGu4zqWC+gK4llhzrFtdoxRKAxr3GpvB+zS02zy8Br/ncEwEM3cMRJRbJ+5EkuNtT/4SZHMeiCK58qIkcpyA+PzAxXHZkZkoux98J3lRL1LvUkF6UgHe6L7E3gofQ7aTzRl46MbHg9HRF1+FVLx68arEq2YgHo6bnHzuwbGfoifprXelLkiVlkCSdBefYyB1EL/jg8esucQxHw2g0YJynAKzeA98HkYXNN1mcSokinUwVehWnomiDyTyhRDh5D8cDNwta46j71oCBvE8Xkm2dQqd6TBDKIdkfj9Mw3dThRbcRWz+AzufKoiC/+cmAEn50ViCf+Cm2H3ANUj2btuY+eKhaCY9HP5QG2pDbagNtaE21Jw1kfnvRKdeqWRt1amXvcb1whdYm8NjWJ8KWDH7QQjoYDo8DZEwH2Lw/M6G5WCCYijFOr0HbsOf4TurVanGQ+AJBfNZBTMe0iAX8mClgnndgWnt+R/hpA1+XI//n5qbAjNR9go4aYfPFaADgUwkKaSaHCZX7XDXAZyHHaK5au6tn4Aj3D1+Ep/Mb+FP8HcYCO7CbIREoU7oEr4RgxHixC3iQfELsVfslSYhRD40JNph9d8Z1klV0g5ptx3eQfjNT8AHQzAEQ/APDJf+d3Bh2d5IGrgerpXlf0+NSmPkVlmquVb6LTsVUq094jTxLoxgn9gDQsNV7oHaiZLK3dvHD1TuoFHu3JnSRYtK2UUv0pNkFplMJpFZ9GTyFXKEHLx2hUbR+VdWkxpSgvAKNdFKhELk3Ms+eyP14QAavUYl6gOQv5qMIaPpGUSdQcbIwtGj22/2VsqIXYnYlxF7HADRqsLDdX6C2ktyIRq9TqXRT/f30Icx4YhbadnXZcSXRLT9haZyXZV9bX8k447VVBZvETLJnICAP/9h25e76ddt9Ll7O7uIx5F3DtUg9RrU1A2pT0IrOGl7e6u9BM3EwCCVzttbFxrOOGj19s5EyUXb9s9/KSZuRNPS2NVJD9EPi/sq5RG7NtW1vPPGnLBfbataX7zJTRb3abUnDpr3+E746L3z3Y89RqK2bN/7WlNb6UbzWnP5S+x7qCbU7bZ4EU9aIERLNGqtSiPcttSd5ZItEyqFSOFSX7DQ/ntyC31yzNrDTefv2HziGRauC0UpJe3EQNWA/jFjTIzJGBtbwJ6mmBgjHxJrKoyJKSiwdLGJWJMJ/Wu9CyBFI99HwAMANSMIajQor+F1ary5l3GhX3O6LZbIrS9Zzq3ZL5Bzf5LFxb3Nskym0XMyp+VmsMohFenEIx0P9I4/gA5dotVrBhqRd5hP5eikdnTwq4mKeLzffuMufY++RitaW3a/V1HTcbT9/RpZ6JGP/mbDLi/1h83XPuWz15SvL+7zrXujsYHZKwm99T16aywOJMG2DTWhgo9KG4iO4VTuHshluvj9DPoJpfRlOh93YtkG4rd7bdAne69cuPDF9vcnk323r5PdJItkk92zn6WvHvst7aAHEDpb9ih7H3WqV3yixr2vC/VQuXNaLbGrpnDkGqv+4/LnX1ZZOjs6OEq2kn10ITXKZAqZRyLJZDQTakHX0Vq6na5lciNNsQ1p+jhtpFwae5890SzirE2WamKurKQyZ65UaDReoprjlv7jluZLtNFOiU9FSiOclHDP6NTMqNDZydbIfb4yw0xBPShiejoxiR0dOzp1SkcH+YzfcJwb3kF7+/OPs6V93fweWe5tFqb3z5EdttiPNBTvEm9vH0/cJnyg4k61ZoC3AxzeFSIWlYVc2UnVX0WmJc3stAAKlkgEMu6MZUdFdW1tdQV3edTiX9BUmXRVP2/5o8z4nu/cdUhTt3nzDia3GX0cjT4OBph+P/6CggID9WH+950tqb28fXzskerfsNb3847Xmgpar1/dT4LI8Aoyrm6t7+8ObavNOXv9D7+lp+n5rfR6FEnf01K8MiVz8vQnTx299sOUKfRwfc2y7BfTwqaHfXHi5pehyB99JHYrsQFKimEGU7ykU5OiD+mySvG0mWaekoXP7pDVtOpOXwjLUpuFr7gWKZtlUxbJpJlwzbRKyqYbSSmzZCJqBcJc8MXaGohiPYkFrB6DV+dIK3olAxG9TTtUXMipo5KhteDNd/ss7WXrlheNLlz6USEmuWG0YUPG8udj4zO5zZY7sjkx7t03D+yPKH/pFxm3Jk68YLl2MS8rKzOPcZ6KnA2SF9b2GmZRpgmyCWUbGfkHoSDEy9uZ29Sn6khvSJ2ph4i0r8dUF0Il0rt0ef6iRfnLl8qittRSnbAA830fwoUFCWaZZLe3tN269W5LO1oBtRQqUEslPiWtPT69B7iMxadQEfjl7+m/0dMkjHgYb642uf/Tym1ryjatKHcj0YcPkEAygriSxyZNopfNFad/+ObculK7BXNQj5FMD2KXViEoOqzJ2OkUdnoNb0zNLViUkp+bStJrqUvITtNNaiH8TdPOENSQdOe2t7x761ZbS6tsTliAkSsSiUxakED67byEdtTDBR5FXjZWalFjl18nCVrHOcjrY5a8EMtdtQT8clPRFq+WyVb4E71DL5PHyShUYiyX/Oneli6PEtdPjpStOrQPt4Yb042eQWtFYCx3o0aMh91Aao1a4wwtnV7J7D58t8n155FxUWQE/e5jy9O1DQ03ry5sihGHx0QXlVfK/WdlmdfLG9474umJshvQ6ZeQ6giWvwaeE8QZssdMC2KNxtgFJlJRZzHW1pK/iokLjEacLOhbrRDDMyKHPsXNVOiMH0zHk20hpRek97HF535jPDt2FpiCkdbtG89snF/IzZgz/2lG1hSHZOk+uW/xm295ed4kcfOWKGefQ85hLMs6JOMi7ALJMttsdjzXKPTFEzgIV6SwG8jmlgcNWJpTUIWrz7UWHTlUZzGvnZmwJGetpXHtrPil+NzIeMxqLFjfxMvL086dt1zEk+37Uzmvvmz5dmAPTbHjxaQMuxxikxLBzsz7YHEMjPbs5jUHjtRZNpRHLlyRuV6hszTxs48ZH05vzn39baqVHXlBQKqDKy2W2wZWWq2mF1IKCxcvLqS36QkSgaXSWKy0TiR2EhSs4wSlJwux+pKICwmml+hfaS+9yCKfJokGpD0StKiAekCUBzikd2QBmw5csCPSacOP0kCzJb2Oi8q1x7oSNPezAI2SWQ7EkkCIRn6jWYazb+j/5pHoQikuetXLJyyG2iZOCHv7lxMWCTratTDho0N0sWLw940rhiG1ZIzBEKT2oHMgXDcoqTjPgcDUQrcd5XlF83O3/nrb3d4lF8sLh1WuyzPOTnj1fCO10m8yrk0gwSVrfm6YbRgbELxz/Tt7J2jovfyCyDnhs9QB+l1VB98ej7ynWXv4PWKhUmlp2SGgYnHpiH4lb5+tryfpJIhenvL07Fnc9mGvd17dxf+LTJ6jh2XL6qq5SSmN5ZVHkBbLv1VCEIwZnPeVRGxzCXaFe7VUilD2DOmdk7wio1wI6o+37Rlusmz51YcrGlrJVbQy++1KuIz03PB8IsqBThyPM9S8mksvx8wzsorUvETNKJBsSeUaZbk/Hmzfqgif4VpWS3vaF9kKP1552Clx545VkIbN9BvyzGbL4srTZ2roc3VkLD1XwlWWcy3EVZbpBmrAQBlN/x3vmwmWDYx+FNI3IP1RLEZs5axaKdSjuHSqL+GvWV4nd0pk/qnDZHJJ/6lOTIN4XKYIX/FF9rMTVeIWEx9a1czOTvZWokbuLAqOdYzG256CgoKc+4GLnzWjXH4iO4yELPR/JkKjm50flpQyatQulcfUkEfnzLVabWevlO0RCHMB3CX4WTI8YLb4QbPcxgGzSc7ZetssNbLTDmcxN7i7QBlUgR1baFdoRCnzxffnRUGhEs/muXpoVX6NNqP+Muov4UBHtEEuWmL+lkDzxYuKEW7cQJx6cRyfLSWx7ONp2/8TOMUEOptFpnJKLNQvzw6Y9/g8fop/8LQCpR9FQrAv+rpvrR0zfirna5hp65Hxhpm2n2uxUsTPgwLmYTiufB/I+gSj+Li9z2Et/K/2Pg8T4Zq9LwzoizCaONZK4EdGw8/ACCaQYSXkwjLIgVXgh7VPBsazH4RiNn8CdNhLRww/mIM4q6AIr5WQBWmQD1Nwdj4UIP7j2HsW8hD80G4OWkXKKAufWbimGO+ZiDkc/ZMFy5FCEqxGjAzETUMqyxRMP+wz+n5IpQDvJsRJR7q5iOeH643IN01592M6CQqXXMhGSY24IvMn3/s5MZKUuSKcNSrcQlE+9l3qwJX314U41zn/L2D9fPDv6IP+geCKJ7RVwVSi+orZWDPwvw/Kk70Z6Vzhidjsc787AsGRN97HIhDcU75490fvELT7FJb/EAjoUVqC8s7HezQ8j/dYlJjAQliE9xcQCLyIwD7H/hrvexEIvI1A4Aiw3Ad/A6BmRxoKZW5kc3RyZWFtCmVuZG9iagoxOCAwIG9iago8PC9MZW5ndGgxIDk2NDgvRmlsdGVyIC9GbGF0ZURlY29kZS9MZW5ndGggNDI4Nj4+CnN0cmVhbQp42u06C1RU1drfPo8ZMjIGGUkLBYZHlo9kHJCrXU2M0JTMuPxeKnkjnOEpqCmapikgguID0AzIENMUwdSLrzHxid4y8xL5yhRJMDXvTYlGZs/99pkZHO111/rX+v9//cu91z5n77O//b33t78zc4AAQHeYBzxEBQeHjV8Ws7kMwGsoPn3qpdEvBvMH+ZM4DsNx3PgXwkIeGeFXhOM6HLe/8togv+QVNZcASCKOw2NTotNFpTgc4NErOF47JTozHZRYwas/jh2nJM9MiD084e8AqpXYuifGR8d5rr65DueuY/NPxAfdPR0cEZ8Xjr0SU7LeEjb3nITjTwG6eSWnxUY3Np99HVHNAxBdUqLfSueWw3/hfAjCu6dGp8Q/eVznAOBZic8S0tMys8znIAJRObJ5YLJyk+ueOeb058jHh9+BvgiK5eyNshx2v3R4w1FzGA1UTlYk4NABOLAUXKdMoW54LTaHmU8qJ8uY7AqXx57g1Q/1qMF2/zyHYyL0JstARL614mpE2cdy55sggXNGEIWCFxUixwkIz9svnpDwYhyMRO5/VLhQF7JGmUKaowDKLzaxWeEzSOgik38/V6IrVMMfFG47ROC6A9w2GT4HmxFbPra12EYwHNjysG223t9B2MbfwiceNd8WL0GGoi9kKiTIkJ8VWO6s8P0gg9eZw+zXoIPEKZZCphiD6/CuUECGmI30wsFFYYAoxHkd/sMiHIYEsS8ME7Lle4Kw16If1pflXQpju2RfCsOUxTBW9IWxwql7cPxpHD8JmXwADMO5APhfKAKQPPh/VpgtbPb4XbhTfwzzsDwsD8vD8rA8LA/L7+URcEDOQC1ZpYs1N3XBiVy89wEnfNIds0sv+BOMhmDMjsIhHqZAEqTBNLgGP5rNcu7sBQPgBZwfA6EQLc8nY1bXxubNzb9R6831D2bKf1gm/KK+CZnwDtTCMfiZBJDXSSH5O7nM9eMSuYL76ifcdd6dH4c1Va7v8uut9YhAhP6CXlgvXBHM4rPimF+tC8VdYouil2IM1nysW+V6UKlU+infwLpCuVvZ7vCUw4v/jfra/1id7JD0i5r1sD6sD+v/8ZqDEbmanhZSFC6ggMdgMIC3v79uiI8vr1CoXXq6EpW2Z09XlY+Pboh/gEqrYgONj48vdtQuCqVKg1PctowZ06fGTZmalE5jkoXS4u92nz8UF7/nrymOi6e3H249HRf1+ehuqZHhb/Xl3lMmTZogeZhCiEveEp60jNywuKLekTjS2w6D+1Fj1qJH6PCgLUVVxx6n/yLdOS3G9AjSxEVwmexM6eGh9ojggAKXuRZnDpibyQm4CY8CBAzx1/oxljSePgfGBQaEhgYEjkscGho6NCB0vPyrinkUt01sZFiIlmg45wrTzQqx8ecUPK9yzM3CUvEW4nFF+f2cVU6cxpNTOTm7eoLKCbR+7Mrlry4tXc3aj/QHovrxNnGit4LJBPIaCSMTaA3dTLfQmlhSSlJJGimlibSILqeJjLYRD8TbiL8bgIfOQyXqvLUqDzXREIGeJsmLiSAJZw8uuG6cJTHofDxJQxH6KRxoVP4ol6B2IQol8dDhMh2R7aPxVBBFuv5MYhvpTj9/wpHmcGnTOp8nh4vnvb946Vohg3QLHH65/hw96YpzdbQyhRwqvru4ZFMhUliL8s5FCs+gRv2telMygwoenmhatLjWTyai0Vk7ngql5ui0psnn2jetrTtBr9KOaRdT07tVl62u3VkT6bd167KcnFWPpYvF/Qfu+yhnh3vvpo9PXfTTEs9lK2vX1OxIKFq+IH/e2yw3GIHS1SBtDlQon4rYpGIa8VBpuROU43eaJt0yZXGFR4gbbb5FjHzvzu+oQiLeKfztzm56eg5lqEYZZqI9+yIWXMjEALULPCAA41slKExhQ/LD/0WeoC1mmPJ1RsYjH64o27SxPCJPFy42VtIwLy96u/UG/YlxXFj8xcH6kyODuJvIYx5SKZY9w5t5hhUnbgzeRlAju4iHX09XNe4LdBuurKC0tGBpcemu0ZuTLxKetrWZ6C0yini/Uv16huP81HpD8Mn6+pPH9h39irv18lik3IwONZNMJrmkuk+f9niJnmV+sBk1tQAldMAB+oqHWqPyEBaY6lZxA0yh0/gmMc1YJA6uI2+gTzM+C6wePAjhbWyiGni7vsXIGk8vtpvlPW0xPr+7fNmyctb6LZ6dnZ+fPXtx8iYDbe/4id4xfFzyQceZMx0fkNKK2tqKD2pr+em5paW5eaWlDa6flX/Z3Pxl+WeuT27N3X7y5PbcrczG71i56cW0RhS4J0E3xLqNmIF0soGciY0t1CpvCKpO+YaaiWubiTxODfQ8aiv9sfkp9QZqKCwpKSwsKeXef3kscWxtJiqaQ9fRt+jEPn064pOJt+CJCv2iARXKqDdiVLjIz7TsZvu4oLLrN44fOnT8uMDAceOHBo4bFzh0vBwrho4fzx2yPgfOfBtAPIcW4MAZ5fAgRKfF2KFVo8vyHrxWTdZwXvSmKWQB5/IRp15hulQ1x7RkTiXnxh256yaJeuMqSSIhtE5CC2UgrjjZmirMb8Hbw+JMHrYdpkHkKo3Ow34zEiN5dnvV+h20kVaWlFRSOsNg4C5dbilfbThMW2mTtHbTxvekt3Pz5hiLJRH0u+oWljk/cbDymy+Z/2Sam8VKtIIbswEa3cfXh9MxVxXkEG6JcEg9QKwcRRtuLjdGp6eQ5WTMLOJSnuF9seGH9vYfNnz9HMk/1RQXnU7ctpM3yMcjX6Af7d2Gke5vtI5uKS9D3TDJbsuSqVEurbtsZZs4lhEx7kYPDqDH6fndshATyXyylU6gcyUyjvhjDbFIQKfTD2gFzWL8M7wBiBexai3I5OZh7WvVGQaDcCTb9GdCs7Mp94O8fvsp6riHOu0xvS1ZcXB1iONRxpnaulStIUaDaRey8ZJBktgyPcKaw2g414SwLhitddYQYgFXyS6zeSo/adKMya1chuHI+ZdW0DXfx0YXnxUD9Xrj/p/OeyK1OHOzogox9OjimFgRaPAcVcc1NJC5/NxjnGPDzM7RDYzw3QRhEK6fKVy7+76EukSbKdzkfez+4Ekkm2+IcwAGHlSqC6dUKPiQO0bjnXajsb3UjMZLSY/pXENeJMtSsRNKXiVjycvkVbqV7qA76VY9M+JTO3YQt/SYWBpOP/yEXkqLiQWrBXvJFuzF/NzqmTaHFFjIYPpGd3RYtXbtKtoh27D+W6Kgxm/p0atcxwelqyssFmw+8OkV0wVZFlony9ITPBE/8tzFvBOIqF6tGvMIOxH5KLqRSl1C0H/QDv/3Uvpu/GecVUo3sp5E3+Offk1T/hQ0cpfDqp8flNUik4J5z5NstxFMW3qg/Xl0e42qyxHkvda1E/nG4Pinz+ykFW1B6TEXT5sqUcY7Z29sMc0iviXLlpXQM1xLj9cn0hclcm7xq6btsud8sX9Nrc/S4uJCOWJj3GtBifth3FG52g4hX18Wab0w9Fj3nZxYudrOW0OmuGf/tj0ZOw9/tZV0v53YsSRDVbujbP3shl0nttBr9Ea2OQQzjE0fFuQkZwUMe6F+o+HLAc/S+rKCd7L1s4YHPL+v/Mx5P6SOfiuOQokfZ1kGO07xvLDuFJKzn47JFgdm0zH7JeF2G4lCKe86SrgqCj0uBlcxy1t81YnxrbI6Lm5eNBjpu58L2b+npWXPftJhoEZ6BOsdUdLrOzvp5cuXSR9ewH4r/Zh+R54ir+Fuuo7ctCDe7gCPcJZNp5EJkASyi9R9RHYWmb7fbLq5inMXpbuLhFm4DYoZRrRdAuoxXxiN+dLTyJWu6/jqIZuOnSfy0eVhO+F1chLDD7qRtyg3K7OgrpJWPl+hr/3i5hnCrViYOt8pMmpH+IWrJPTS9Flp8wvJXtOXUubY4L0V63eOmbkwLqapX79zbB8MQ7p1mAljGsEsyHTHMDurXTgWPpE2cbmXWaiv15Ik/w3Zhzo6DmVv8KclJGnFkoKiooIlKyRxpGRKiYukx41G2hAZVyWRaZ82XD5/4dvj+1HnTD43lK/3faejvXuwsCy4+X5T04oK7d0afyxery5YsKq0pHhGYW8yYtM2osWzcvCg5+itJfOufvdd6+w5Vr012/j3tumKRQ0Ldp0Hr7PLBgRtDS1lAvzccRgFqCYJdSuWFBYVFaIAUlVcJAkwGol/ZBzXT7p7Imn/8W8vnL/cAFY64ci/C+4ujBdWfrV2B71SFkQphHdeXVc2872+K/vfONBGW0jPy/8k3D8URblzlztx4NB0bu6crTUoSycZQptqd+8z7JLx00ChGfH3hf4sR5Sjr68tJN8nE/MnO4l0grazLenTSVHOi+asK7knGkmkpTbR+L2dr7f87ONzMTHqb4eW3pOySk+XWGX8FHkYi4xEic0YifH86WGXOfToCh9HgwYNDBo1aFDQ99WmazU1JFHMGDh69MBBo0bdfVqS+InsVIFhiGci2uQR+xOIVFab2mrRfdjxM1I+qZCecjLK/BwOLDm5NU5ZxPu1AdtNMqjgrVufuqGyinIVUWnZ71RQB+udq0KutGVxs6v4SdNmnDxlOiJJnPeHi3dvo72x1788x9Ljw5L2SenZVj6Em8iHW9cZpv51dsJk3B8m11RVUqE8aua8RRVM5n3Jqce/kunAwaI9nyB2m8dIiNX6hnUvj3a1eQym0lziypKSlStLSlcwr+/V1kZ60avB165caWu7cuVaLLoJJX70c0rpZxYvCZe9pCdomJdY2Pt956gxXav+La+4K+r1pOU3/EHWC38aqT3BaFn36YN24E9LYujLuUWNps+Ycvw3zRoQK/Sj7a+E7q2xqTlN392Sm/HbEBs7KXTa+08Khsn6MnHvpGCelykJBYtnz49cvTAv+6t9YbtjJSF3WtaMiJzlJQuvnphyaFjHjOlv/jU4fPCA/u8mLK/q/0zrlKyJE4NefWbAoIK0ki39mTciXV8xg1mhB77cqSxvXXb710d3Yd26XSSCVg0JDhnF5TsUFpW/y+/Vk7F0p970Zs64v0QWLSrYyDwlAG16TvC15Ax2kVmOmy7W9IlrJJOq6RrtOn3thioSGTkL3UTw7QyS9kppDU1coN60qn7Z3k9IM3vJyRNu8hMVCV3v6PlH6eZpigSaazZbYo4iwdkHQgCcFDB9MvzyKZfb9VSSn060wMpv4QcQ+wjErmDYe2h4XkM2f/R91okTWYwEvot32j4RiGC/XAu4Y8Eg/5bN+gQtb7D2MXLBV9Y+b/dcsOuL2P/G2legj7ZDEKRBOsyEqZAEUyARsjDHexpi0QfcwQ/3/XOgxV4MQrjDKITJgkxsUyEeoiEFI6E7jIFUhB+IvRcgGas7ymfDlSmP4vEej2um4zUOIbvBaOxJiCEcpiFELMJGI5YpMqQ79hl+d8SSitd0hIlBvEkI547r05ButDz3IJ7XZCpJkICcpmHVy7/kT0Wc7Lf8VFmigShPwH3r7q3q+u7E/DX7ZubXPxdhX8WgNXnLVzEAZ3PSltp/QyPf2Yxj14ruCM3+dWBfAhFwwihGMP/zxWs/rAS1OACvgyEQr6PRZ9i+HovXcVgJvIIaJBAGk/D6Mb5/E9iBlcg0usG30AoTYLgjKC/IxOZjpPTFLMf6fQrr3/dviHXMvleS+3/54z8kCGZL3PT/4J+LCAusrDtb3w7Hfc8j7Max9/rcUIC7TJ/Du5Y+jVJ2s32FBPBv0Q8ExAplbmRzdHJlYW0KZW5kb2JqCjE5IDAgb2JqCjw8L0xlbmd0aCA5NTQ+PgpzdHJlYW0KL0NJREluaXQgL1Byb2NTZXQgZmluZHJlc291cmNlIGJlZ2luCjEyIGRpY3QgYmVnaW4KYmVnaW5jbWFwCi9DSURTeXN0ZW1JbmZvCjw8IC9SZWdpc3RyeSAoQWRvYmUpCi9PcmRlcmluZyAoVUNTKQovU3VwcGxlbWVudCAwCj4+IGRlZgovQ01hcE5hbWUgL0Fkb2JlLUlkZW50aXR5LVVDUyBkZWYKL0NNYXBUeXBlIDIgZGVmCjEgYmVnaW5jb2Rlc3BhY2VyYW5nZQo8MDAwMD4gPGZmZmY+CmVuZGNvZGVzcGFjZXJhbmdlCjQ1IGJlZ2luYmZjaGFyCjwwMDJjPiA8MDA0OT4KPDAwNTE+IDwwMDZlPgo8MDA0OT4gPDAwNjY+CjwwMDUyPiA8MDA2Zj4KPDAwNTU+IDwwMDcyPgo8MDA1MD4gPDAwNmQ+CjwwMDQ4PiA8MDA2NT4KPDAwMDM+IDwwMDIwPgo8MDA0Yz4gPDAwNjk+CjwwMDUzPiA8MDA3MD4KPDAwNTY+IDwwMDczPgo8MDA1Nz4gPDAwNzQ+CjwwMDQ3PiA8MDA2ND4KPDAwNDQ+IDwwMDYxPgo8MDAxNT4gPDAwMzI+CjwwMDEzPiA8MDAzMD4KPDAwMTY+IDwwMDMzPgo8MDAzNT4gPDAwNTI+CjwwMDM2PiA8MDA1Mz4KPDAwNTg+IDwwMDc1Pgo8MDA0ZD4gPDAwNmE+CjwwMGEyPiA8MDBlMD4KPDAwMzc+IDwwMDU0Pgo8MDA0NT4gPDAwNjI+CjwwMGE5PiA8MDBlNz4KPDAwYTU+IDwwMGUzPgo8MDAyOD4gPDAwNDU+CjwwMDViPiA8MDA3OD4KPDAwNDY+IDwwMDYzPgo8MDA0Zj4gPDAwNmM+CjwwMDU5PiA8MDA3Nj4KPDAwMWQ+IDwwMDNhPgo8MDAzMT4gPDAwNGU+CjwwMDVkPiA8MDA3YT4KPDAwMTQ+IDwwMDMxPgo8MDAxYT4gPDAwMzc+CjwwMGEzPiA8MDBlMT4KPDAwMjc+IDwwMDQ0Pgo8MDAyND4gPDAwNDE+CjwwMDI1PiA8MDA0Mj4KPDAwMjY+IDwwMDQzPgo8MDAxMD4gPDAwMmQ+CjwwMGFiPiA8MDBlOT4KPDAwYTQ+IDwwMGUyPgo8MDBiNz4gPDAwZjU+CmVuZGJmY2hhcgplbmRjbWFwCkNNYXBOYW1lIGN1cnJlbnRkaWN0IC9DTWFwIGRlZmluZXJlc291cmNlIHBvcAplbmQKZW5kCmVuZHN0cmVhbQplbmRvYmoKMjAgMCBvYmoKPDwvVHlwZSAvRm9udERlc2NyaXB0b3IvRm9udE5hbWUgL1JXQU5YRitEZWphVnUtU2VyaWYtQm9sZC9Gb250RmFtaWx5IChEZWphVnUgU2VyaWYpL0ZsYWdzIDYvRm9udEJCb3ggWy03IC0xNCA2MjYgNzkxXS9JdGFsaWNBbmdsZSAwL0FzY2VudCA5MzgvRGVzY2VudCAtMjM1L0NhcEhlaWdodCA3OTEvU3RlbVYgODAvU3RlbUggODAvRm9udEZpbGUyIDE3IDAgUj4+CmVuZG9iagoyMSAwIG9iago8PC9UeXBlIC9Gb250L1N1YnR5cGUgL0NJREZvbnRUeXBlMi9CYXNlRm9udCAvUldBTlhGK0RlamFWdS1TZXJpZi1Cb2xkL0NJRFN5c3RlbUluZm8gPDwvUmVnaXN0cnkgKEFkb2JlKS9PcmRlcmluZyAoSWRlbnRpdHkpL1N1cHBsZW1lbnQgMD4+L0NJRFRvR0lETWFwIC9JZGVudGl0eS9XIFszIFszNDhdIDE2IFs0MTVdIDE5IFs2OTYgNjk2IDY5NiA2OTZdIDI2IFs2OTZdIDI5IFszNjldIDM2IFs3NzYgODQ1IDc5NiA4NjcgNzYyXSA0NCBbNDY4XSA0OSBbOTE0XSA1MyBbODMxIDcyMiA3NDRdIDY4IFs2NDggNjk5IDYwOSA2OTkgNjM2IDQzMF0gNzYgWzM4MCAzNjJdIDc5IFszODAgMTA1OCA3MjcgNjY3IDY5OV0gODUgWzUyNyA1NjMgNDYyIDcyNyA1ODFdIDkxIFs1OTZdIDkzIFs1NjhdIDE2MiBbNjQ4IDY0OCA2NDggNjQ4XSAxNjkgWzYwOV0gMTcxIFs2MzZdIDE4MyBbNjY3XV0vRm9udERlc2NyaXB0b3IgMjAgMCBSPj4KZW5kb2JqCjIyIDAgb2JqCjw8L1R5cGUgL0ZvbnQvU3VidHlwZSAvVHlwZTAvQmFzZUZvbnQgL1JXQU5YRitEZWphVnUtU2VyaWYtQm9sZC9Ub1VuaWNvZGUgMTkgMCBSL0VuY29kaW5nIC9JZGVudGl0eS1IL0Rlc2NlbmRhbnRGb250cyBbMjEgMCBSXT4+CmVuZG9iagoyMyAwIG9iago8PC9MZW5ndGggMTAzOD4+CnN0cmVhbQovQ0lESW5pdCAvUHJvY1NldCBmaW5kcmVzb3VyY2UgYmVnaW4KMTIgZGljdCBiZWdpbgpiZWdpbmNtYXAKL0NJRFN5c3RlbUluZm8KPDwgL1JlZ2lzdHJ5IChBZG9iZSkKL09yZGVyaW5nIChVQ1MpCi9TdXBwbGVtZW50IDAKPj4gZGVmCi9DTWFwTmFtZSAvQWRvYmUtSWRlbnRpdHktVUNTIGRlZgovQ01hcFR5cGUgMiBkZWYKMSBiZWdpbmNvZGVzcGFjZXJhbmdlCjwwMDAwPiA8ZmZmZj4KZW5kY29kZXNwYWNlcmFuZ2UKNTEgYmVnaW5iZmNoYXIKPDAwMzQ+IDwwMDUxPgo8MDAyYz4gPDAwNDk+CjwwMDAzPiA8MDAyMD4KPDAwMzY+IDwwMDUzPgo8MDA1Mj4gPDAwNmY+CjwwMDQ2PiA8MDA2Mz4KPDAwNGM+IDwwMDY5Pgo8MDA0OD4gPDAwNjU+CjwwMDQ3PiA8MDA2ND4KPDAwNDQ+IDwwMDYxPgo8MDAyNj4gPDAwNDM+CjwwMDU1PiA8MDA3Mj4KPDAwYWI+IDwwMGU5Pgo8MDA1Nz4gPDAwNzQ+CjwwMDI3PiA8MDA0ND4KPDAwMTE+IDwwMDJlPgo8MDAyND4gPDAwNDE+CjwwMDMxPiA8MDA0ZT4KPDAwMzM+IDwwMDUwPgo8MDAyZD4gPDAwNGE+CjwwMDFkPiA8MDAzYT4KPDAwMTY+IDwwMDMzPgo8MDAxNT4gPDAwMzI+CjwwMDE3PiA8MDAzND4KPDAwMTM+IDwwMDMwPgo8MDAxOD4gPDAwMzU+CjwwMDEyPiA8MDAyZj4KPDAwMTQ+IDwwMDMxPgo8MDAxMD4gPDAwMmQ+CjwwMDI1PiA8MDA0Mj4KPDAwYjU+IDwwMGYzPgo8MDA0YT4gPDAwNjc+CjwwMDQ1PiA8MDA2Mj4KPDAwNTE+IDwwMDZlPgo8MDAxYz4gPDAwMzk+CjwwMDM3PiA8MDA1ND4KPDAwNTg+IDwwMDc1Pgo8MDA0Zj4gPDAwNmM+CjwwMDM4PiA8MDA1NT4KPDAwMjk+IDwwMDQ2Pgo8MDAxYj4gPDAwMzg+CjwwMDFhPiA8MDAzNz4KPDAwMTk+IDwwMDM2Pgo8MDBhYz4gPDAwZWE+CjwwMDM1PiA8MDA1Mj4KPDAwNTA+IDwwMDZkPgo8MDAwNz4gPDAwMjQ+CjwwMDM5PiA8MDA1Nj4KPDAwMzI+IDwwMDRmPgo8MDA1Nj4gPDAwNzM+CjwwMDU0PiA8MDA3MT4KZW5kYmZjaGFyCmVuZGNtYXAKQ01hcE5hbWUgY3VycmVudGRpY3QgL0NNYXAgZGVmaW5lcmVzb3VyY2UgcG9wCmVuZAplbmQKZW5kc3RyZWFtCmVuZG9iagoyNCAwIG9iago8PC9UeXBlIC9Gb250RGVzY3JpcHRvci9Gb250TmFtZSAvTldPTFFQK0RlamFWdS1TZXJpZi9Gb250RmFtaWx5IChEZWphVnUgU2VyaWYpL0ZsYWdzIDYvRm9udEJCb3ggWy05IC0yMDggNjEwIDUzM10vSXRhbGljQW5nbGUgMC9Bc2NlbnQgOTI4L0Rlc2NlbnQgLTIzNS9DYXBIZWlnaHQgNTMzL1N0ZW1WIDgwL1N0ZW1IIDgwL0ZvbnRGaWxlMiAxOCAwIFI+PgplbmRvYmoKMjUgMCBvYmoKPDwvVHlwZSAvRm9udC9TdWJ0eXBlIC9DSURGb250VHlwZTIvQmFzZUZvbnQgL05XT0xRUCtEZWphVnUtU2VyaWYvQ0lEU3lzdGVtSW5mbyA8PC9SZWdpc3RyeSAoQWRvYmUpL09yZGVyaW5nIChJZGVudGl0eSkvU3VwcGxlbWVudCAwPj4vQ0lEVG9HSURNYXAgL0lkZW50aXR5L1cgWzMgWzMxOF0gNyBbNjM2XSAxNiBbMzM4IDMxOCAzMzcgNjM2IDYzNiA2MzYgNjM2IDYzNiA2MzYgNjM2IDYzNiA2MzYgNjM2IDMzN10gMzYgWzcyMiA3MzUgNzY1IDgwMl0gNDEgWzY5NF0gNDQgWzM5NSA0MDFdIDQ5IFs4NzUgODIwIDY3MyA4MjAgNzUzIDY4NSA2NjcgODQzIDcyMl0gNjggWzU5NiA2NDAgNTYwIDY0MCA1OTJdIDc0IFs2NDBdIDc2IFszMjBdIDc5IFszMjAgOTQ4IDY0NCA2MDJdIDg0IFs2NDAgNDc4IDUxMyA0MDIgNjQ0XSAxNzEgWzU5MiA1OTJdIDE4MSBbNjAyXV0vRm9udERlc2NyaXB0b3IgMjQgMCBSPj4KZW5kb2JqCjI2IDAgb2JqCjw8L1R5cGUgL0ZvbnQvU3VidHlwZSAvVHlwZTAvQmFzZUZvbnQgL05XT0xRUCtEZWphVnUtU2VyaWYvVG9Vbmljb2RlIDIzIDAgUi9FbmNvZGluZyAvSWRlbnRpdHktSC9EZXNjZW5kYW50Rm9udHMgWzI1IDAgUl0+PgplbmRvYmoKMjcgMCBvYmoKPDwvUldBTlhGIDIyIDAgUi9OV09MUVAgMjYgMCBSPj4KZW5kb2JqCjI4IDAgb2JqCjw8L1R5cGUgL1hPYmplY3QvU3VidHlwZSAvSW1hZ2UvV2lkdGggMTIwL0hlaWdodCAzNC9Db2xvclNwYWNlIC9EZXZpY2VSR0IvQml0c1BlckNvbXBvbmVudCA4L0ludGVycG9sYXRlIHRydWUvRmlsdGVyIC9GbGF0ZURlY29kZS9EZWNvZGVQYXJtcyA8PC9QcmVkaWN0b3IgMTUvQ29sdW1ucyAxMjAvQ29sb3JzIDM+Pi9TTWFzayAyOSAwIFIvTGVuZ3RoIDE0Mjg+PgpzdHJlYW0KeJztWk1vGzcQfcOV8nWK4zi10osBy0CvjuQC+Q+pvejfaZCFmv6edO3kPxSIpOoawDaQU63aVlTk0MaWlq+H/dB+kCvJUdI60QMPAskdjt4OhzPDFVjgtgcUAQhAHOVvr9hmLjELKsZet3tOImQZAAPmJ/SGCKBFKyqM4D9evoYpEGPvXuddwnIIR6kXjyI23d6QAbMTREaypLsECoDbOX/SPst0S96ER6nfWuvcawDIqt7tDtze8FNo+QVAuZ0BIY4otz2YdDNv6S8fTazVvAsAIRjQ/W3JtQEqscw0t+JcpOkMME4/I1rbBZLVJdcGKKOB+ts1UZfaUQTEef+q+U1mdGdNKQWx2faSawMq4lxofQOAUu/TA/52reSxX2NP8kP3VMHJe2yQ1YWqef1h87fzwe0OmOcaQvg7qwuR/wUgQ7TbG46DoDJyrhCombm2ZzrrdU9EkUHhGQZQZ4etZFoY4XwYy19vWwY5Wx6KC2ehqU+PfwFwd8O74QSOqibr2sTe3fBuVWDWMFa0f9QKV6fgz8OfjZNqmx6FCMO7EG7nnAEdCKs6E4GEo71heejmN1YLoUoYCJqWr3sCgkHo5zONUiFrdS+ey7D/tpidkbAgodAUHADfbnl3KnREpdc1il3/zrtdpVXDyDyZrK7swQFVokPSBTVJBVOUua+He513DDQDvdd5V3LKHTRWc66oEI4DoQ2mFkq31NNcr/9kVT/9T7ISonXz/RoAGVl+etQIFUQKFuSkVJ3T6aZT8Awrbm/ob68UksAoorD5FtGaotI9T9pnr3bWMn+DkTiOpV/YtrXNp4gkOLP8gf5hRkJt6xkIDfYPn6f7Nza8CxAAyZPjzJAB4Rsh/g7MjuUKSJOSeUehb6UhCQSr1q3iZzkFoJTK9cTGjCLLAG4GMb82e7sSPtyKf81gipEdYGEsI23R4lwwuAkQoIzilJtSJHqKlpLxGDInX2/ftmr1Z3M9MhcEXLfLD0TODucnV2CTqWJ/NSHaHDgL5+QZzDnbeZ//5CgzaUdfUVubzEScuUz6MXA0Oe9J8TkhYMkmk7F16OMwhWhRlwxu5DtHl59Im88AEv2jhXneWChOjs1x9PqWJyQSot3ekFoDAiJdWfa3a+7rUzqTJFt04D+uue0zigNA9Nj//sFcWsXXNri74RVPm/XvPIwJRDHZwjGLKww1lIUoQE0oJERTa8RXKrkyRcjjj78PAYS1f7c3ZBBFI1TObntwkE61JR9m5KDjeOK2wzubXm40uc2Z9xQtR/9N62H9GQEFebjpaWOEHx+GjKmu1T37i5HZdoaCaGTDuwQMaU3jxaOV5IYld7Mlgt3uJJMs8FNQtBIflgIKcy2JrfqWzXhlJJRRaMv3osNworJ15qyHvEAoMkkusvSMOd+uEWKvk3CdEVU8GPtvWnQkPJRyLXlWJq6KhBDyD0eYBQznGwzo5Og5hWHabGuQAMDJcUuJMF7aMjP0b2Gzki7MJr273UFuckk9yG2f0eIfRJg707VS6duZqahtPQUVAAH/OJqWwl0fRHypQvXHVg8C4O+saUtNqxg5zcUygJsjR4OkaKq1rbwHv76Y8FK8+ZaRKqmXGuuiOVBw0FiWpIH0YSgFIy2/kfIbq1PzEnV5jSPuxSJDVdGoAQkYvCqUihKU2DWBg+bSnCNkzjRxLgoT6Ija6wxspl1i1wJZfuaRIE+S2zlnyYcb2dBEUfnNFZTa9f7SqAEYq05u97ys7FKQsN+8BzvXAXWJ5/l6YAiH/cZ9gd2s86D7+hR2H+LITBclXzzMeYffvC/qcsaPEYJKVByxcP1/q0f/N7AWgPzt2n7znhbbZfsE6ZTEb6zacpmvHFMqbS8bD/abq6KDXK0FCM2dxdr0y50H4lwicj6GCV8n/gW+3sq2CmVuZHN0cmVhbQplbmRvYmoKMjkgMCBvYmoKPDwvRmlsdGVyIC9GbGF0ZURlY29kZS9UeXBlIC9YT2JqZWN0L1N1YnR5cGUgL0ltYWdlL0RlY29kZVBhcm1zIDw8L1ByZWRpY3RvciAxNS9Db2x1bW5zIDEyMD4+L1dpZHRoIDEyMC9IZWlnaHQgMzQvQ29sb3JTcGFjZSAvRGV2aWNlR3JheS9CaXRzUGVyQ29tcG9uZW50IDgvSW50ZXJwb2xhdGUgdHJ1ZS9MZW5ndGggNzI4Pj4Kc3RyZWFtCnicvZfbdds6EEV3slwAOhBcgXkrMFyBmQpCVyB1ILsCJRXQtwImFZCpQHQFoCogU8G5HwCfkp2VdU2fH3EGj43XDCCI2rXKDR+vTJJKAOx2/9V+GPgoSdoAtpWkcn106gC8JOkWOCjoYNblfpN2QCFJHiCPYHm7KjjyrJfaFMDpY8illAPY+60JntvcfwTZHi5sZhbR5YrgV7QP5N1qgE8AxtXNGfkRoLvuou1uDACnugZ3y/dYkG3GNi8/MG5jGApNElvBryrbdN+jkd6En7afmjFDJzGs9tEqhyOnA+xDyC8KlJO0Qz4gnNhee8oQNQC5BCF5tEBSSkc7kL2in5DYvPfet5LcFJx7773Ueu/9gWP42gz9tz5qewHcSpKJKasdyCGuHACFFP2ptJ+C4xjDMTQxRKJa+ckSzsGfgRqoO/YGwPSLS9UB3IceaZrohXFRljLQzMzQxyVdAQ+HtHqAJHjcUPa845zyak8sm/+sz8bVTyoJ4OZLP9y5XmKdv5IbyM05+HH8vho/qyz8DI4G3lrXy+q3BE5v1puAn1IDdE9/SVro+Y32zXX8yDM+g8l9aYHmroH6rnFFkSybdEOI2z9ss5m1spcrnarqCg4ZtrwG6usNJ2wJ6dMjcAPhyEOdmmMFgOtdF6fUmcw00fhZ184VfeVf1aRe1UBMFGNYFn16CjdzfA5NcpDn1ThmN8ljX0kn1jJzXcWVyxZbszMPITLCiJu7+wQAk1LBqeL3tPZLf4K/dfemd5748c/WjlYznruugZiU26F+/xDIM0nhNTTVs/TI+8jNboP5co2r08sc8jx5J3I5z9H9XbwYzwoKU568c0byyg++MkDcOXm7KjdeiFJul+SjWYv5CYC0iGZddUDzb3z5wPPDWuSgTDOV45zdumBSPyMnA7n4Y9P/KVtOwbf05OPaYMiOi7Sxk+ZvqNWUbIujJN+fblv61f6u/gc5o4ACCmVuZHN0cmVhbQplbmRvYmoKeHJlZgowIDMwCjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDAxNSAwMDAwMCBuIAowMDAwMDAwMDY4IDAwMDAwIG4gCjAwMDAwMDAxMTUgMDAwMDAgbiAKMDAwMDAwMDE3NyAwMDAwMCBuIAowMDAwMDAwMzE5IDAwMDAwIG4gCjAwMDAwMDE5NDYgMDAwMDAgbiAKMDAwMDAwMjEzMSAwMDAwMCBuIAowMDAwMDAyMjcwIDAwMDAwIG4gCjAwMDAwMDI1NzEgMDAwMDAgbiAKMDAwMDAwMjY4NyAwMDAwMCBuIAowMDAwMDAyODE4IDAwMDAwIG4gCjAwMDAwMDMxNTAgMDAwMDAgbiAKMDAwMDAwMzMwMiAwMDAwMCBuIAowMDAwMDAzNDE0IDAwMDAwIG4gCjAwMDAwMDM2MTQgMDAwMDAgbiAKMDAwMDAwMzgyNiAwMDAwMCBuIAowMDAwMDAzODc4IDAwMDAwIG4gCjAwMDAwMDc2MDEgMDAwMDAgbiAKMDAwMDAxMTk3MSAwMDAwMCBuIAowMDAwMDEyOTc1IDAwMDAwIG4gCjAwMDAwMTMxOTkgMDAwMDAgbiAKMDAwMDAxMzY4NCAwMDAwMCBuIAowMDAwMDEzODI5IDAwMDAwIG4gCjAwMDAwMTQ5MTggMDAwMDAgbiAKMDAwMDAxNTEzOCAwMDAwMCBuIAowMDAwMDE1NjEzIDAwMDAwIG4gCjAwMDAwMTU3NTMgMDAwMDAgbiAKMDAwMDAxNTgwMiAwMDAwMCBuIAowMDAwMDE3NDcyIDAwMDAwIG4gCnRyYWlsZXIKPDwKL1NpemUgMzAKL1Jvb3QgMyAwIFIKL0luZm8gMiAwIFIKPj4Kc3RhcnR4cmVmCjE4NDIwCiUlRU9GCg=="
}
```

STATUS 404

**Response Body**

```json
{
  "data": "{\"title\": \"Not Found\", \"description\": \"Account not found for the given parameters.\", \"translation\": \"Conta não encontrada para os parâmetros fornecidos.\", \"extra_fields\": {}, \"code\": \"ACC000008\"}"
}

```

---

# Consultar Bloqueios em Conta

URL: /documentation/contas/ordens_de_bloqueio

## Request

ENDPOINT /account/ ACCOUNT_KEY /account_block_records
MÉTODO GET

### Path parameters

| Campo | Tipo | Descrição                      |
|---|------|--------------------------------|
| `ACCOUNT_KEY` | UUID | Chave da conta a ser detalhada |

### Query parameters

| Campo                      | Tipo       | Descrição                                             | Caracteres                                                                  |
|----------------------------|------------|-------------------------------------------------------|-----------------------------------------------------------------------------|
| `block_order_statuses` * | enumerator | Indica o status da ordem de bloqueio. | [Enumeradores block_order_statuses](#enumeradores-block_order_statuses) |

### Enumeradores block_order_statuses

| Enumerador   | Descrição                    |
|--------------|------------------------------|
| **pending** | Ordem de bloqueio pendente |
| **open** | Ordem de bloqueio aberta   |
| **concluded** | Ordem de bloqueio concluída   |

## Response

STATUS 200

Response Body

```json
{
  [
    {
      "account_blocked_amount": 1000,
      "block_order": {
        "block_order_protocol": "100000000",
        "block_order_sequence": "00001",
        "case_number": "0000000000000",
        "court_code": "00000",
        "defendant_document_number": "00000000000000",
        "institution_document_number": null,
        "lawsuit_author_name": "NOME DO JUIZ",
        "lawsuit_type": "labor",
        "protocol_datetime": "2025-04-28T08:34:16Z",
        "requested_amount": 1000,
        "requester_judge": "JUIZ DE DIREITO"
      }
    }
  ]
}
```

### Response Body Params

| Campo                          | Tipo            | Descrição                                          | Max. Caracteres |
|--------------------------------|-----------------|----------------------------------------------------|-----------------|
| `account_blocked_amount`       | float          | Valor bloqueado na conta.                          | -               |
| `block_order`                  | object          | Detalhes da ordem de bloqueio.                     | **[Objeto block_order](#objeto-block_order)**          |

### Objeto block_order

| Campo                          | Tipo            | Descrição                                          | Max. Caracteres |
|--------------------------------|-----------------|----------------------------------------------------|-----------------|
| `block_order_protocol`      | string          | Protocolo da ordem de bloqueio.                    | -               |
| `block_order_sequence`      | string          | Sequência da ordem de bloqueio.                    | -               |
| `case_number`               | string          | Número do caso.                                    | -               |
| `court_code`                | string          | Código do tribunal.                                | -               |
| `defendant_document_number` | string          | Número de documento do réu.                        | 14              |
| `institution_document_number` | string or null| Número de documento da instituição, se aplicável.  | -               |
| `lawsuit_author_name`       | string          | Nome do autor do processo.                         | -               |
| `lawsuit_type`              | enumerator      | Tipo de processo.                                  | **[Enumeradores lawsuit_type](#enumeradores-lawsuit_type)**               |
| `protocol_datetime`         | string   | Data e hora do protocolo.                          | 20              |
| `requested_amount`          | float          | Valor solicitado.                                  | -               |
| `requester_judge`           | string          | Nome do juiz solicitante.                          | -               |

### Enumeradores lawsuit_type

| Enumerador  | Descrição              |
|-------------|------------------------|
| `labor`     | Processo trabalhista   |
| `civil`     | Processo civil         |
| `criminal`  | Processo criminal      |
| `tax`       | Processo tributário    |
| `family`    | Processo de família    |

STATUS 404

Response Body: Conta não encontrada

```json
{
    "title": "Not Found",
    "description": "Account not found for the given key 3e4b8746-da58-4799-bcd0-063326428d3f",
    "translation": "Conta não encontrada para a seguinte chave 3e4b8746-da58-4799-bcd0-063326428d3f",
    "code": "ACC000006"
}
```

STATUS 403

Response Body: Usuário não possui permissão

```json
{
    "title": "Permission Validator Error",
    "description": "Selected agent do not own this item.",
    "translation": "O agente selecionado não é dono do item.",
    "code": "QIT000005"
}
```

---

# Simulação de cenários

URL: /documentation/contas/simulacao

Passo a passo para simular o bloqueio e desbloqueio de conta de clientes.

## 1 - Simulação de bloqueio de conta

### Request

ENDPOINT /mock/account/ ACCOUNT_KEY /block
MÉTODO PATCH

Request Body

```json
{
  "account_block_reason": "\<Motivo do bloqueio da conta\>"
}
```

### Body Parameters

| Campo                | Tipo   | Descrição                          | Exemplo                                |
|----------------------|--------|------------------------------------|----------------------------------------|
| `account_block_reason` | string | Motivo do bloqueio da conta         | "judicially_suspended"                   |

:::info
Os motivos de bloqueio possíveis podem ser acessados na seção [Webhook de bloqueio de conta](../movimentacao_de_contas/webhook_movimentacoes#webhook-de-bloqueio-de-conta).
:::

## 2 - Simulação de desbloqueio de conta

### Request

ENDPOINT /mock/account/ ACCOUNT_KEY /unblock
MÉTODO PATCH

Request Body

```json
{
}
```

---

# Criar conta destino para escrow

URL: /documentation/d88ff174-100d-4b55-80b7-86e11f508400

Este endpoint permite criar uma conta destino para uma conta escrow

## Request

### Request Endpoint

ENDPOINT /account/ ACCOUNT_KEY /destination
MÉTODO POST

### Request Path Params

| Campo               | Tipo    | Descrição                               | Caracteres |
|---------------------|---------|-----------------------------------------|------------|
| `account_key` *     | uuid4   | Chave única de identificação da conta.  | 36         |

Request Body: adição de conta destino

```json
{
    "name": "Minha conta destino",
    "ted_account_type": "checking_account",
    "document_number": "51297635200133",
    "account_branch": "3422",
    "account_digit": "8",
    "account_number": "08042",
    "financial_institutions_code_number": "329"
}
```

### Body Params

| Campo                                        | Tipo   | Descrição                         |
|----------------------------------------------|--------|-----------------------------------|
| `name` *                                     | string | Nome do destinatário              |    
| `ted_account_type` *                         | enum   | Tipo de conta destino.            |
| `account_branch`  *                          | string | Agência da conta destino .        |
| `account_digit` *                            | string | digito da conta destino.          |
| `account_number` *                           | string | número da conta destino.          |
| `financial_institutions_code_number` *       | string | código do banco da conta destino. |

## Response

### Success Response

STATUS 201

Response Body:

```json
{}
```

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

| Código HTTP | Código QI | Título                                        | Descrição (eng)                                 | Descrição (pt-br)                                       |
|-------------|-----------|-----------------------------------------------|-------------------------------------------------|---------------------------------------------------------|
| 404         | ACC000006 | Not found                                     | Account not found for the given key ACCOUNT_KEY | Conta não encontrada para a seguinte chave ACCOUNT_KEY  |
| 403         | ACC000219 | Requester not allowed to perform this action  | Requester not allowed to create destination     | Requester não autorizado a criar conta destino          |

---

# Cadastrar conta no DDA

URL: /documentation/dda/cadastro_dda

Para habilitar o recebimento das informações dos boletos, que tenham o titular de uma conta QI como pagador, é necessário cadastrar esta conta no DDA.

As evidências da assinatura do termo de adesão devem ser enviadas na requisição.

## Request

ENDPOINT /account/ ACCOUNT_KEY /dda
MÉTODO POST

Request Body

```json
{
	"authorization_term": {
		"document_number": "12345678910", 
		"signature": {
			"signer": {
				"name": "Jose da Silva",
				"email": "ownermail@mail.com",
				"phone": {
					"number": "0987654321",
					"area_code": "11",
					"country_code": "55"
				},
				"document_number": "12345678910"
			},
			"authentication_type": "opt_in",
			"authenticity": {
				"timestamp": "1970-01-01T00:00:01.080100Z",
				"ip_address": "177.51.1.000",
				"fingerprint": {
					"browser": "Mozila"
				},
				"third_party_additional_data": {},
				"session_id": "10c33308-866f-47e5-bec8-2e512e9c0237"
			},
			"signed_object": {
				"raw_text": "Lorem ipsum dolor sit amet, consectetur a...."
			}
		}
	}
}
```

### Path Params

| Campo         | Tipo   | Descrição                                               | Caracteres |
| ------------- | ------ | ------------------------------------------------------- | ---------- |
| `account_key` | string | Chave de identificação da conta a ser cadastrada no DDA | 36         |

### Body Params

| Campo                | Tipo   | Descrição                                  | Caracteres |
| -------------------- | ------ | ------------------------------------------ | ---------- |
| `authorization_term` | object | Dados da autorização assinada pelo pagador | -          |

## Response

STATUS 201

**Response Body**

```json
{
	"account_key": "e1c891a1-78a0-4915-9cb8-8b6adfc2e83a",
	"dda_account_status": "active",
	"account_number": "12345",
	"account_digit": "6",
	"owner_document_number": "12345678910",
	"owner_person_key": "99784848-36bb-4049-8ce3-0e47938738de",
	"requester_key": "59a63416-073a-45d5-b821-6a39664632ca",
	"created_at": "2023-10-22T20:30:23.459Z"
}
```

| Campo                   | Tipo   | Descrição                                                | Caracteres |
| ----------------------- | ------ | -------------------------------------------------------- | ---------- |
| `account_key`           | string | Account_key da conta cadastrada no DDA.                  | 36         |
| `dda_account_status`    | enum   | [Enumeradores de status da conta.](#enumeradores-status) | -          |
| `account_number`        | string | Número da conta.                                         | 20         |
| `account_digit`         | string | Dígito da conta.                                         | 1          |
| `owner_document_number` | string | Documento do dono da conta.                              | 14         |
| `owner_person_key`      | string | Person key do dono da conta.                             | 36         |
| `requester_key`         | string | Requester key de quem abriu a conta.                     | 36         |
| `created_at`            | string | Data de criação e ativação no DDA.                       | 24         |

### Enumeradores Status

| Enumerador  | Descrição                           |
| ----------- | ----------------------------------- |
| `active`    | Conta ativa no DDA.                 |
| `cancelled` | Relacionamento com o DDA encerrado. |

---

# Remover conta do DDA

URL: /documentation/dda/cancelamento_dda

Após a remoção da conta no DDA, as notificações de registro de boletos tendo o titular da conta como pagador, não serão mais recebidas.

:::info Informação
Caso o titular da conta ainda possua outra(s) conta(s), aberta(s) pelo parceiro integrador e cadastrada(s) no DDA, as notificações continuarão sendo enviadas.

Para interrupção das notificações, é necessário remover todas as contas do titular cadastradas no DDA.
:::

As evidências da assinatura do termo de cancelamento devem ser enviadas na requisição.

## Request

ENDPOINT /account/ ACCOUNT_KEY /dda/cancel
MÉTODO PATCH

Request Body

```json
{
	"authorization_term": {
		"document_number": "12345678910", 
		"signature": {
			"signer": {
				"name": "Jose da Silva",
				"email": "ownermail@mail.com",
				"phone": {
					"number": "0987654321",
					"area_code": "11",
					"country_code": "55"
				},
				"document_number": "12345678910"
			},
			"authentication_type": "opt_in",
			"authenticity": {
				"timestamp": "1970-01-01T00:00:01.080100Z",
				"ip_address": "177.51.1.000",
				"fingerprint": {
					"browser": "Mozila"
				},
				"third_party_additional_data": {},
				"session_id": "10c33308-866f-47e5-bec8-2e512e9c0237"
			},
			"signed_object": {
				"raw_text": "Lorem ipsum dolor sit amet, consectetur a...."
			}
		}
	}
}
```

### Path Params

| Campo         | Tipo   | Descrição                                         | Caracteres |
| ------------- | ------ | ------------------------------------------------- | ---------- |
| `account_key` | string | Chave de identificação da conta cadastrada no DDA | 36         |

### Body Params

| Campo                | Tipo   | Descrição                                  | Caracteres |
| -------------------- | ------ | ------------------------------------------ | ---------- |
| `authorization_term` | object | Dados da autorização assinada pelo pagador | -          |

## Response

STATUS 200

```json
{
	"account_key": "e1c891a1-78a0-4915-9cb8-8b6adfc2e83a",
	"dda_account_status": "cancelled",
	"account_number": "12345",
	"account_digit": "6",
	"owner_document_number": "12345678910",
	"owner_person_key": "99784848-36bb-4049-8ce3-0e47938738de",
	"requester_key": "59a63416-073a-45d5-b821-6a39664632ca",
	"created_at": "2023-10-22T20:30:23.459Z"
}
```

| Campo                   | Tipo   | Descrição                                                | Caracteres |
| ----------------------- | ------ | -------------------------------------------------------- | ---------- |
| `account_key`           | string | Account_key da conta cadastrada no DDA.                  | 36         |
| `dda_account_status`    | enum   | [Enumeradores de status da conta.](#enumeradores-status) | -          |
| `account_number`        | string | Número da conta.                                         | 20         |
| `account_digit`         | string | Dígito da conta.                                         | 1          |
| `owner_document_number` | string | Documento do dono da conta.                              | 14         |
| `owner_person_key`      | string | Person key do dono da conta.                             | 36         |
| `requester_key`         | string | Requester key de quem abriu a conta.                     | 36         |
| `created_at`            | string | Data de criação e ativação no DDA.                       | 24         |

### Enumeradores Status

| Enumerador  | Descrição                           |
| ----------- | ----------------------------------- |
| `active`    | Conta ativa no DDA.                 |
| `cancelled` | Relacionamento com o DDA encerrado. |

---

# Consultar conta cadastrada no DDA

URL: /documentation/dda/consultar_dados_conta

Consulta uma conta ativa no DDA para o requester.
## Request

ENDPOINT /account/ ACCOUNT_KEY /dda
MÉTODO GET

### Path Params

| Campo         | Tipo   | Descrição                                         | Caracteres |
| ------------- | ------ | ------------------------------------------------- | ---------- |
| `account_key` | string | chave de identificação da conta cadastrada no DDA | 36         |

## Response

STATUS 200

Response Body

```json
{
	"account_key": "e1c891a1-78a0-4915-9cb8-8b6adfc2e83a",
	"dda_account_status": "active",
	"account_number": "12345",
	"account_digit": "6",
	"owner_document_number": "12345678910",
	"owner_person_key": "99784848-36bb-4049-8ce3-0e47938738de",
	"requester_key": "59a63416-073a-45d5-b821-6a39664632ca",
	"created_at": "2023-10-22T20:30:23.459Z"
}
```

| Campo                   | Tipo   | Descrição                                                | Caracteres |
| ----------------------- | ------ | -------------------------------------------------------- | ---------- |
| `account_key`           | string | Account_key da conta cadastrada no DDA.                  | 36         |
| `dda_account_status`    | enum   | [Enumeradores de status da conta.](#enumeradores-status) | -          |
| `account_number`        | string | Número da conta.                                         | 20         |
| `account_digit`         | string | Dígito da conta.                                         | 1          |
| `owner_document_number` | string | Documento do dono da conta.                              | 14         |
| `owner_person_key`      | string | Person key do dono da conta.                             | 36         |
| `requester_key`         | string | Requester key de quem abriu a conta.                     | 36         |
| `created_at`            | string | Data de criação e ativação no DDA.                       | 24         |

### Enumeradores Status

| Enumerador  | Descrição                           |
| ----------- | ----------------------------------- |
| `active`    | Conta ativa no DDA.                 |
| `cancelled` | Relacionamento com o DDA encerrado. |

---

# Erros retornados na api

URL: /documentation/dda/erros

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}",
  "title": "Bad Request", 
  "description": "Invalid request body.", 
  "translation": "Corpo da requisição inválido.", 
  "extra_fields": {}, 
  "code": "LEG000069"
}
```

STATUS 403

Response Body

```json
{
  "data": "{\"title\": \"Forbidden\", \"description\": \"Has no permission to this account\", \"translation\": \"Não possui permissão nesta conta\", \"extra_fields\": {}, \"code\": \"QIT000079\"}",
  "title": "Forbidden", 
  "description": "Has no permission to this account",
  "translation": "Não possui permissão nesta conta", 
  "extra_fields": {}, 
  "code": "QIT000079"
  
}

```

STATUS 404

Response Body

```json
{
  "data": "{\"title\": \"Not Found\", \"description\": \"Not found account for the given key\", \"translation\": \"Não foi encontrada uma conta com a chave fornecida\", \"extra_fields\": {}, \"code\": \"QIT000099\"}",
  "title": "Not Found", 
  "description": "Not found account for the given key", 
  "translation": "Não foi encontrada uma conta com a chave fornecida",
  "extra_fields": {}, 
  "code": "QIT000099"
}

```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Error on electronic payer subscription\", \"translation\": \"Erro ao inscrever pagador eletronico.\", \"extra_fields\": {}, \"code\": \"QIT000011\"}",
  "title": "Bad Request", 
  "description": "Error on electronic payer subscription", 
  "translation": "Erro ao inscrever pagador eletronico.", 
  "extra_fields": {}, 
  "code": "QIT000011"
}

```

STATUS 409

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Bank slip already registered\", \"translation\": \"Boleto já cadastrado.\", \"extra_fields\": {}, \"code\": \"QIT100012\"}",
  "title": "Duplicated Bank Slip", 
  "description": "Bank slip already registered", 
  "translation": "Boleto já cadastrado.", 
  "extra_fields": {}, 
  "code": "QIT100012"
}

```

STATUS 409

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Account already registered\", \"translation\": \"Conta já cadastrada.\", \"extra_fields\": {}, \"code\": \"QIT200012\"}",
  "title": "Account already registered", 
  "description": "Account already registered", 
  "translation": "Conta já cadastrada.", 
  "extra_fields": {}, 
  "code": "QIT200012"
}

```

---

# Introdução

URL: /documentation/dda/introducao

A API do Débito Direto Autorizado (DDA) possibilita que uma conta dentro da QI Tech, receba as informações de todos os boletos que tenham o titular da conta como pagador.

:::danger Observações Gerais:
- Para esta API, a **conta** cadastrada no DDA é obrigatoriamente conta QI.
- A divulgação e aceite dos termos é de responsabilidade do parceiro (integrador).
:::

---

# Listar contas cadastradas no DDA

URL: /documentation/dda/lista_contas_cadastradas

## Request

ENDPOINT /dda/accounts
MÉTODO GET

### QUERY PARAMS

| Campo         | Descrição                              |
| ------------- | -------------------------------------- |
| `page_number` | Página atual que está sendo consultada |
| `page_size`   | Quantidade de resultados por página    |

## Response

STATUS 200

Response Body

```json
{
  "data": [
    {
      "account_key": "e1c891a1-78a0-4915-9cb8-8b6adfc2e83a",
      "dda_account_status": "active",
      "account_number": "12345",
      "account_digit": "6",
      "owner_document_number": "12345678910",
      "owner_person_key": "99784848-36bb-4049-8ce3-0e47938738de",
      "requester_key": "59a63416-073a-45d5-b821-6a39664632ca",
      "created_at": "2023-10-22T20:30:23.459Z"
    },
    {
      "account_key": "e1c891a1-78a0-4915-9cb8-8b6adfc2e832",
      "dda_account_status": "active",
      "account_number": "54321",
      "account_digit": "6",
      "owner_document_number": "12345678911",
      "owner_person_key": "99784848-36bb-4049-8ce3-0e47938738d2",
      "requester_key": "59a63416-073a-45d5-b821-6a39664632ca",
      "created_at": "2023-11-22T20:30:23.459Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "rows_per_page": 10
  }
}

```

| Campo                   | Tipo   | Descrição                                                | Caracteres |
| ----------------------- | ------ | -------------------------------------------------------- | ---------- |
| `account_key`           | string | Account_key da conta cadastrada no DDA.                  | 36         |
| `dda_account_status`    | enum   | [Enumeradores de status da conta.](#enumeradores-status) | -          |
| `account_number`        | string | Número da conta.                                         | 20         |
| `account_digit`         | string | Dígito da conta.                                         | 1          |
| `owner_document_number` | string | Documento do dono da conta.                              | 14         |
| `owner_person_key`      | string | Person key do dono da conta.                             | 36         |
| `requester_key`         | string | Requester key de quem abriu a conta.                     | 36         |
| `created_at`            | string | Data de criação e ativação no DDA.                       | 24         |

### Enumeradores Status

| Enumerador  | Descrição                           |
| ----------- | ----------------------------------- |
| `active`    | Conta ativa no DDA.                 |
| `cancelled` | Relacionamento com o DDA encerrado. |

---

# Lista de boletos registrados no DDA (bank slip notification) com filtros

URL: /documentation/dda/lista_notificacoes_de_boletos

Método que permite a listagem de títudos de boletos de conta registrada no DDA permitindo filtragem por status e intervalo de tempo.

## Request
ENDPOINT /account/ ACCOUNT_KEY /dda/bank_slips
MÉTODO GET

### Path Params

| Campo         | Tipo   | Descrição                                         | Caracteres |
| ------------- | ------ | ------------------------------------------------- | ---------- |
| `account_key` | string | Chave de identificação da conta cadastrada no DDA | 36         |

### QUERY PARAMS

| Campo         | Descrição                              |
| ------------- | -------------------------------------- |
| `status`      | status de um boleto                    |
| `start_date`  | Data de início da listagem.            |
| `end_date`    | Data de fim da listagem.               |
| `page_number` | Página atual que está sendo consultada |
| `page_size`   | Quantidade de resultados por página    |

## Response

STATUS 200

Response Body

```json
{
  "data": [
    {
        "barcode": "00193000000001000000500000001234567890123456",
        "digitable_line": "00193000000001000000500000001234567890123456123",
        "status": "registered",
        "nominal_amount": 1050,
        "total_amount": 999,
        "total_payment_amount": null,
        "partial_payment_allowed": true,
        "paid_fine": null,
        "paid_interest": null,
        "discount_amount": null,
        "expiration": "2024-07-19",
        "max_payment_date": "2024-09-02",
        "beneficiary": {
            "name": "Tech Solutions Ltda.",
            "bank_code": "123",
            "bank_ispb": "12345678",
            "person_type": "legal",
            "document_number": "12345678000100"
        },
        "payer": {
            "name": "João Carlos",
            "person_type": "natural",
            "document_number": "12345678900"
        },
        "guarantor": { 
            "name": "Maria Junior", 
            "person_type": "natural",
            "document_number": "03903984900" 
        },
        "rebate_amount": 30.00,
        "interest": [
            {
                "interest_amount_type": "workdays_daily_amount",
                "interest_billing_start_date": "2024-07-21",
                "interest_amount": 10.00
            }
        ],
        "fine": [
            {
                "fine_billing_start_date": "2024-07-29",
                "fine_amount_type": "absolute",
                "fine_amount": 100.00
            }
        ],
        "discounts": [
            {
                "discount_limit_date": "2024-07-05",
                "discount_type": "absolute",
                "discount_amount": 50.00
            }
        ],
        "calculations": [],
        "calculation_model": "01",
    },
    {
        "barcode": "00193000000001000000500000001234567890123457",
        "digitable_line": "00193000000001000000500000001234567890123456123",
        "status": "paid",
        "nominal_amount": 1050,
        "total_amount": 1200,
        "total_payment_amount": 1200,
        "partial_payment_allowed": false,
        "paid_fine": 150,
        "paid_interest": 50,
        "discount_amount": 0,
        "expiration": "2024-05-30",
        "max_payment_date": "2024-07-01",
        "beneficiary": {
            "name": "Tech Solutions Ltda.",
            "bank_code": "123",
            "bank_ispb": "12345678",
            "person_type": "legal",
            "document_number": "12345678000100"
        },
        "payer": {
            "name": "João Carlos",
            "person_type": "natural",
            "document_number": "12345678900"
        },
        "guarantor": { 
            "name": "Maria Junior", 
            "person_type": "natural",
            "document_number": "03903984900" 
        },
        "rebate_amount": 30.00,
        "interest": [
            {
                "interest_amount_type": "workdays_daily_amount",
                "interest_billing_start_date": "2024-05-21",
                "interest_amount": 10.00
            }
        ],
        "fine": [
            {
                "fine_billing_start_date": "2024-05-29",
                "fine_amount_type": "absolute",
                "fine_amount": 100.00
            }
        ],
        "discounts": [
            {
                "discount_limit_date": "2024-05-05",
                "discount_type": "absolute",
                "discount_amount": 50.00
            }
        ],
        "calculations": [],
        "calculation_model": "01",
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "rows_per_page": 10
  }
}
```

### Body Params

| Campo                     | Tipo    | Descrição                                                                           | Caracteres |
| ------------------------- | ------- | ----------------------------------------------------------------------------------- | ---------- |
| `barcode`                 | string  | Código de barras do boleto.                                                         | 44         |
| `digitable_line`          | string  | Linha digitável do boleto.                                                          | 47         |
| `status`                  | enum    | [Enumeradores de status de um boleto.](#enumeradores-status)                        | -          |
| `nominal_amount`          | float   | Valor nominal do boleto.                                                            | -          |
| `total_amount`            | float   | Valor calculado do boleto.                                                          | -          |
| `total_payment_amount`    | float   | Valor de pagamento do boleto.                                                       | -          |
| `partial_payment_allowed` | boolean | Indicador de aceite de pagamento parcial.                                           | -          |
| `paid_fine`               | float   | Total de multa efetivado no pagamento do boleto, calculado a partir do valor total. | -          |
| `paid_interest`           | float   | Total de juros efetivado no pagamento do boleto, calculado a partir do valor total. | -          |
| `discount_amount`         | float   | Total de descontos no pagamento do boleto, calculado a partir do valor total.       | -          |
| `expiration`              | string  | Data de vencimento do boleto.                                                       | 10         |
| `max_payment_date`        | string  | Data limite de pagamento do boleto.                                                 | 10         |
| `payer`                   | object  | [Objeto pagador do boleto.](#objeto-payer)                                          | -          |
| `beneficiary`             | object  | [Objeto beneficiário do boleto.](#objeto-beneficiary)                               | -          |
| `guarantor`               | object  | [Objeto sacador avalista do boleto](#objeto-guarantor)                              | -          |
| `rebate_amount`           | float   | Valor de rebate.                                                                    | -          |
| `interest`                | list    | [Lista de objetos interest.](#objeto-interest)                                      | -          |
| `fine`                    | list    | [Lista de objetos fine.](#objeto-fine)                                              | -          |
| `discounts`               | list    | [Lista de objetos discount.](#objeto-discount)                                      | -          |
| `calculations`            | list    | Lista do grupo cálculo de boleto.                                                   | -          |
| `calculation_model`       | string  | Método de cálculo do valor atual do boleto.                                         | 2          |

### Enumeradores Status

| Enumerador       | Descrição                              |
| ---------------- | -------------------------------------- |
| `registered`     | Código de barras do boleto registrado. |
| `paid`           | Boleto pago.                           |
| `partially_paid` | Boleto pago parcialmente.              |
| `written_off`    | Boleto baixado.                        |

### Objeto Payer

| Campo             | Tipo   | Descrição                  | Caracteres |
| ----------------- | ------ | -------------------------- | ---------- |
| `name`            | string | Nome do pagador.           | -          |
| `person_type`     | string | Tipo de pessoa do pagador. | 7          |
| `document_number` | string | Documento do pagador.      | 14         |

### Objeto Beneficiary

| Campo             | Tipo   | Descrição                        | Caracteres |
| ----------------- | ------ | -------------------------------- | ---------- |
| `name`            | string | Nome do beneficiário.            | -          |
| `person_type`     | string | Tipo de pessoa do beneficiário.  | 7          |
| `document_number` | string | Documento do beneficiário.       | 14         |
| `bank_code`       | string | Código do banco do beneficiário. | 3          |
| `bank_ispb`       | string | ISPB do banco do beneficiário.   | 8          |

### Objeto guarantor

| Campo             | Tipo   | Descrição                           | Caracteres |
| ----------------- | ------ | ----------------------------------- | ---------- |
| `name`            | string | Nome do sacador avalista.           | -          |
| `person_type`     | string | Tipo de pessoa do sacador avalista. | 7          |
| `document_number` | string | Documento do sacador avalista.      | 14         |

### Objeto interest

| Campo                         | Tipo   | Descrição                | Caracteres |
| ----------------------------- | ------ | ------------------------ | ---------- |
| `interest_billing_start_date` | string | Data de início do juros. | 10         |
| `interest_amount_type`        | string | Tipo de juros.           | -          |
| `interest_amount`             | string | Valor do juros.          | -          |

### Objeto fine

| Campo                     | Tipo   | Descrição                | Caracteres |
| ------------------------- | ------ | ------------------------ | ---------- |
| `fine_billing_start_date` | string | Data de início da multa. | 10         |
| `fine_amount_type`        | string | Tipo de multa.           | -          |
| `fine_amount`             | string | Valor da multa.          | -          |

### Objeto discount

| Campo                 | Tipo   | Descrição                | Caracteres |
| --------------------- | ------ | ------------------------ | ---------- |
| `discount_limit_date` | string | Data limite do disconto. | 10         |
| `discount_type`       | string | Tipo de desconto.        | -          |
| `discount_amount`     | string | Valor do desconto.       | -          |

---

# Recuperação de termo de aceite e cancelamento de cadastro no DDA

URL: /documentation/dda/recuperacao_termo

Os termos de aceite e cancelamento do DDA (Débito Direto Autorizado) são documentos que regulamentam a autorização do cliente para utilizar o serviço de débito direto em sua conta bancária, bem como o procedimento para cancelar essa autorização, se desejado.

O termo de aceite do DDA é o documento em que o cliente formalmente consente e autoriza o débito automático das suas contas e faturas em sua conta bancária. Esse termo estabelece os direitos e responsabilidades do cliente e da instituição financeira, além de definir as condições de uso do DDA. Ele geralmente contém informações como identificação do cliente e da instituição financeira, autorização para débito automático, identificação dos pagamentos autorizados, período de vigência, direitos e responsabilidades do cliente, e direitos e responsabilidades da instituição financeira.

Já o termo de cancelamento de adesão ao DDA é o documento que permite ao cliente revogar a autorização concedida anteriormente e solicitar o cancelamento do serviço de débito direto. Esse termo geralmente requer a assinatura do cliente e a notificação da instituição financeira para interromper os débitos automáticos. É importante seguir o procedimento de cancelamento estabelecido pelo banco, que pode incluir o envio de uma solicitação por escrito, preenchimento de formulários específicos ou comunicação por meios eletrônicos.

Ambos os termos têm como objetivo garantir a transparência e a segurança nas transações financeiras do cliente, fornecendo uma base legal para o serviço de débito direto. O termo de aceite formaliza a autorização inicial e estabelece os termos e condições do serviço, enquanto o termo de cancelamento permite ao cliente encerrar a adesão ao DDA, caso não deseje mais utilizar essa forma de pagamento automático.

:::info Informação
Caso a conta seja reativada no DDA após um cancelamento, o termo de cancelamento não será retornado em consultas posteriores.
:::

## Request

ENDPOINT /account/ ACCOUNT_KEY /term/ TYPE
MÉTODO GET

### Path Params

| Campo         | Tipo   | Descrição                                                  | Caracteres |
| ------------- | ------ | ---------------------------------------------------------- | ---------- |
| `account_key` | string | Chave de identificação da conta cadastrada no DDA          | 36         |
| `type`        | enum   | [Enumeradores tipo de termo.](#enumeradores-tipo-de-termo) | -          |

### Enumeradores tipo de termo

| Enumerador     | Descrição                      |
| -------------- | ------------------------------ |
| `agreement`    | Assinatura DDA                 |
| `cancellation` | Cancelamento de assinatura DDA |

## Response

STATUS 200

Response Body

```json
{
	"authorization_term": {
		"document_number": "12345678910", 
		"signature": {
			"signer": {
				"name": "Jose da Silva",
				"email": "ownermail@mail.com",
				"phone": {
					"number": "0987654321",
					"area_code": "11",
					"country_code": "55"
				},
				"document_number": "12345678910"
			},
			"authentication_type": "opt_in",
			"authenticity": {
				"timestamp": "1970-01-01T00:00:01.080100Z",
				"ip_address": "177.51.1.000",
				"fingerprint": {
					"browser": "Mozila"
				},
				"third_party_additional_data": {},
				"session_id": "10c33308-866f-47e5-bec8-2e512e9c0237"
			},
			"signed_object": {
				"raw_text": "Lorem ipsum dolor sit amet, consectetur a...."
			}
		}
	}
}
```

| Campo                | Tipo   | Descrição                                  | Caracteres |
| -------------------- | ------ | ------------------------------------------ | ---------- |
| `authorization_term` | object | Dados da autorização assinada pelo pagador | -          |

---

# Simulação de cenários de registro e alteração de boletos

URL: /documentation/dda/simulacoes

Para gerar simulações de uma notificação de registro de um boleto onde o titular da conta seja o pagador, o parceiro integrador pode utilizar os endpoints abaixo:

:::info Informação
Para receber os webhooks de teste, a conta informada no endpoint deve ser uma conta válida do requester e ativa no DDA.
:::

## Request registro de boleto

ENDPOINT /mock/account/ ACCOUNT-KEY /dda/bank_slip
MÉTODO POST

Request Body

```json
{
  "status": "registered",
  "amount": 1050,
  "partial_payment_allowed": false,
  "expiration": "2024-05-30",
  "max_payment_date": "2024-07-01",
  "beneficiary": {
    "name": "Tech Solutions Ltda.",
    "bank_code": "123",
    "bank_ispb": "12345678",
    "person_type": "legal",
    "document_number": "12345678000100"
  },
  "guarantor": {
    "name": "Maria Junior",
    "person_type": "natural",
    "document_number": "03903984900"
  },
  "rebate_amount": 30.0,
  "interest": [
    {
      "interest_amount_type": "workdays_daily_amount",
      "interest_billing_start_date": "2024-05-21",
      "interest_amount": 10.0
    }
  ],
  "fine": [
    {
      "fine_billing_start_date": "2024-05-29",
      "fine_amount_type": "absolute",
      "fine_amount": 100.0
    }
  ],
  "discounts": [
    {
      "discount_limit_date": "2024-05-05",
      "discount_type": "absolute",
      "discount_amount": 50.0
    }
  ],
  "calculations": [],
  "calculation_model": "01"
}
```

| Campo                       | Tipo    | Descrição                                                    | Caracteres |
| --------------------------- | ------- | ------------------------------------------------------------ | ---------- |
| `status` *                  | enum    | [Enumeradores de status de um boleto.](#enumeradores-status) | -          |
| `amount` *                  | float   | Valor nominal do boleto.                                     | -          |
| `partial_payment_allowed` * | boolean | Indicador de aceite de pagamento parcial.                    | -          |
| `expiration` *              | string  | Data de vencimento do boleto.                                | 10         |
| `max_payment_date` *        | string  | Data limite de pagamento do boleto.                          | 10         |
| `beneficiary` *             | object  | [Objeto beneficiário do boleto.](#objeto-beneficiary)        | -          |
| `guarantor`                 | object  | [Objeto sacador avalista do boleto](#objeto-guarantor)       | -          |
| `rebate_amount`             | float   | Valor de rebate.                                             | -          |
| `interest`                  | list    | [Lista de objetos interest.](#objeto-interest)               | -          |
| `fine`                      | list    | [Lista de objetos fine.](#objeto-fine)                       | -          |
| `discounts`                 | list    | [Lista de objetos discount.](#objeto-discount)               | -          |
| `calculations`              | list    | Lista do grupo cálculo de boleto.                            | -          |
| `calculation_model` *       | string  | Método de cálculo do valor atual do boleto.                  | 2          |

### Enumeradores Status

| Enumerador       | Descrição                              |
| ---------------- | -------------------------------------- |
| `registered`     | Código de barras do boleto registrado. |
| `paid`           | Boleto pago.                           |
| `partially_paid` | Boleto pago parcialmente.              |
| `written_off`    | Boleto baixado.                        |

### Objeto Beneficiary

| Campo               | Tipo   | Descrição                        | Caracteres |
| ------------------- | ------ | -------------------------------- | ---------- |
| `name` *            | string | Nome do beneficiário.            | -          |
| `person_type` *     | string | Tipo de pessoa do beneficiário.  | 7          |
| `document_number` * | string | Documento do beneficiário.       | 14         |
| `bank_code` *       | string | Código do banco do beneficiário. | 3          |
| `bank_ispb` *       | string | ISPB do banco do beneficiário.   | 8          |

### Objeto guarantor

| Campo               | Tipo   | Descrição                           | Caracteres |
| ------------------- | ------ | ----------------------------------- | ---------- |
| `name` *            | string | Nome do sacador avalista.           | -          |
| `person_type` *     | string | Tipo de pessoa do sacador avalista. | 7          |
| `document_number` * | string | Documento do sacador avalista.      | 14         |

### Objeto interest

| Campo                           | Tipo   | Descrição                | Caracteres |
| ------------------------------- | ------ | ------------------------ | ---------- |
| `interest_billing_start_date` * | string | Data de início do juros. | 10         |
| `interest_amount_type` *        | string | Tipo de juros.           | -          |
| `interest_amount` *             | string | Valor do juros.          | -          |

### Objeto fine

| Campo                       | Tipo   | Descrição                | Caracteres |
| --------------------------- | ------ | ------------------------ | ---------- |
| `fine_billing_start_date` * | string | Data de início da multa. | 10         |
| `fine_amount_type` *        | string | Tipo de multa.           | -          |
| `fine_amount` *             | string | Valor da multa.          | -          |

### Objeto discount

| Campo                   | Tipo   | Descrição                | Caracteres |
| ----------------------- | ------ | ------------------------ | ---------- |
| `discount_limit_date` * | string | Data limite do disconto. | 10         |
| `discount_type` *       | string | Tipo de desconto.        | -          |
| `discount_amount` *     | string | Valor do desconto.       | -          |

## Response

STATUS 200

```json
{}
```

## Request alteração de boleto

Apenas alguns campos do boleto podem ser alterados, como ilustrado na request abaixo. Alguns campos, como beneficiário, pagador e aceite de pagamento parcial, não aceitam alteração. 

:::info Informação
Os campos que são listas de objetos não devem ser passados caso não deseje alterá-los. Se uma lista vazia for passada, ou qualquer outro valor for passado dentro da lista todos os objetos serão substituídos. 
:::

ENDPOINT /mock/account/ ACCOUNT-KEY /dda/bank_slip/ BARECODE
MÉTODO PATCH

Request Body

```json
{
  "status": "registered",
  "amount": 1200,
  "expiration": "2024-05-30",
  "max_payment_date": "2024-07-01",
  "guarantor": {
    "name": "Maria Junior",
    "person_type": "natural",
    "document_number": "03903984900"
  },
  "rebate_amount": 30.0,
  "interest": [],
  "fine": [
    {
      "fine_billing_start_date": "2024-05-29",
      "fine_amount_type": "absolute",
      "fine_amount": 100.0
    },
    {
      "fine_billing_start_date": "2024-06-29",
      "fine_amount_type": "absolute",
      "fine_amount": 100.0
    }
  ],
  "discounts": [
    {
      "discount_limit_date": "2024-05-05",
      "discount_type": "absolute",
      "discount_amount": 50.0
    }
  ],
  "calculations": [],
  "calculation_model": "01"
}
```

| Campo               | Tipo   | Descrição                                                    | Caracteres |
| ------------------- | ------ | ------------------------------------------------------------ | ---------- |
| `status` *          | enum   | [Enumeradores de status de um boleto.](#enumeradores-status) | -          |
| `amount`            | float  | Valor nominal do boleto.                                     | -          |
| `expiration`        | string | Data de vencimento do boleto.                                | 10         |
| `max_payment_date`  | string | Data limite de pagamento do boleto.                          | 10         |
| `guarantor`         | object | [Objeto sacador avalista do boleto](#objeto-guarantor)      | -          |
| `rebate_amount`     | float  | Valor de rebate.                                             | -          |
| `interest`          | list   | [Lista de objetos interest.](#objeto-interest)              | -          |
| `fine`              | list   | [Lista de objetos fine.](#objeto-fine)                      | -          |
| `discounts`         | list   | [Lista de objetos discount.](#objeto-discount)              | -          |
| `calculations`      | list   | Lista do grupo cálculo de boleto.                            | -          |
| `calculation_model` | string | Método de cálculo do valor atual do boleto.                  | 2          |

## Response

STATUS 200

```json
{}
```

## Request baixa por pagamento de boleto

ENDPOINT /mock/account/ ACCOUNT-KEY /dda/bank_slip/ BARECODE
MÉTODO PATCH

Request Body

```json
{
  "status": "paid",
  "paid_amount": 1200,
}
```

| Campo           | Tipo  | Descrição                                                    | Caracteres |
| --------------- | ----- | ------------------------------------------------------------ | ---------- |
| `status` *      | enum  | [Enumeradores de status de um boleto.](#enumeradores-status) | -          |
| `paid_amount` * | float | Valor pago do boleto.                                        | -          |

## Response

STATUS 200

```json
{}
```

## Request baixa por cancelamento de boleto

ENDPOINT /mock/account/ ACCOUNT-KEY /dda/bank_slip/ BARECODE
MÉTODO PATCH

Request Body

```json
{
  "status": "written_off",
}
```

| Campo      | Tipo | Descrição                                                    | Caracteres |
| ---------- | ---- | ------------------------------------------------------------ | ---------- |
| `status` * | enum | [Enumeradores de status de um boleto.](#enumeradores-status) | -          |

## Response

STATUS 200

```json
{}
```

---

# Formato dos Webhooks

URL: /documentation/dda/webhooks

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

Existem dois tipos de eventos no dda que serão diferenciados no webhook pelo atributo webhook_type

## Webhook de captura de boleto

Registration webhook

```json
    {
      "webhook_type": "baas.dda.bankslip.registration",
      "key": "7c52d5f6-9db1-4a3c-bb03-1f76a2e8f9d2",
      "data": {
        "barcode": "00193000000001000000500000001234567890123456",
        "digitable_line": "00193000000001000000500000001234567890123456123",
        "status": "registered",
        "nominal_amount": 1050,
        "total_amount": 999,
        "total_payment_amount": null,
        "paid_fine": null,
        "paid_interest": null,
        "discount_amount": null,
        "partial_payment_allowed": true,
        "expiration": "2024-07-19",
        "max_payment_date": "2024-09-02",
        "beneficiary": {
            "name": "Tech Solutions Ltda.",
            "bank_code": "123",
            "bank_ispb": "12345678",
            "person_type": "legal",
            "document_number": "12345678000100"
        },
        "payer": {
            "name": "João Carlos",
            "person_type": "natural",
            "document_number": "12345678900"
        },
        "guarantor": { 
            "name": "Maria Junior", 
            "person_type": "natural",
            "document_number": "03903984900" 
        },
        "rebate_amount": 30.00,
        "interest": [
            {
                "interest_amount_type": "workdays_daily_amount",
                "interest_billing_start_date": "2024-07-21",
                "interest_amount": 10.00
            }
        ],
        "fine": [
            {
                "fine_billing_start_date": "2024-07-29",
                "fine_amount_type": "absolute",
                "fine_amount": 100.00
            }
        ],
        "discounts": [
            {
                "discount_limit_date": "2024-07-05",
                "discount_type": "absolute",
                "discount_amount": 50.00
            }
        ],
        "calculations": [],
        "calculation_model": "01",
      }
    }
```

### Body Params

| Campo                     | Tipo    | Descrição                                                    | Caracteres |
| ------------------------- | ------- | ------------------------------------------------------------ | ---------- |
| `barcode`                 | string  | Código de barras do boleto.                                  | 44         |
| `digitable_line`          | string  | Linha digitável do boleto.                                   | 47         |
| `status`                  | enum    | [Enumeradores de status de um boleto.](#enumeradores-status) | -          |
| `nominal_amount`          | float   | Valor nominal do boleto.                                     | -          |
| `total_amount`            | float   | Valor calculado do boleto.                                   | -          |
| `total_payment_amount`    | float   | Valor de pagamento do boleto.                                | -          |
| `partial_payment_allowed` | boolean | Indicador de aceite de pagamento parcial.                    | -          |
| `expiration`              | string  | Data de vencimento do boleto.                                | 10         |
| `max_payment_date`        | string  | Data limite de pagamento do boleto.                          | 10         |
| `payer`                   | object  | [Objeto pagador do boleto.](#objeto-payer)                   | -          |
| `beneficiary`             | object  | [Objeto beneficiário do boleto.](#objeto-beneficiary)        | -          |
| `guarantor`               | object  | [Objeto sacador avalista do boleto](#objeto-guarantor)       | -          |
| `rebate_amount`           | float   | Valor de rebate.                                             | -          |
| `interest`                | list    | [Lista de objetos interest.](#objeto-interest)               | -          |
| `fine`                    | list    | [Lista de objetos fine.](#objeto-fine)                       | -          |
| `discounts`               | list    | [Lista de objetos discount.](#objeto-discount)               | -          |
| `calculations`            | list    | Lista do grupo cálculo de boleto.                            | -          |
| `calculation_model`       | string  | Método de cálculo do valor atual do boleto.                  | 2          |

### Enumeradores Status

| Enumerador       | Descrição                              |
| ---------------- | -------------------------------------- |
| `registered`     | Código de barras do boleto registrado. |
| `paid`           | Boleto pago.                           |
| `partially_paid` | Boleto pago parcialmente.              |
| `written_off`    | Boleto baixado.                        |

### Objeto Payer

| Campo             | Tipo   | Descrição                  | Caracteres |
| ----------------- | ------ | -------------------------- | ---------- |
| `name`            | string | Nome do pagador.           | -          |
| `person_type`     | string | Tipo de pessoa do pagador. | 7          |
| `document_number` | string | Documento do pagador.      | 14         |

### Objeto Beneficiary

| Campo             | Tipo   | Descrição                        | Caracteres |
| ----------------- | ------ | -------------------------------- | ---------- |
| `name`            | string | Nome do beneficiário.            | -          |
| `person_type`     | string | Tipo de pessoa do beneficiário.  | 7          |
| `document_number` | string | Documento do beneficiário.       | 14         |
| `bank_code`       | string | Código do banco do beneficiário. | 3          |
| `bank_ispb`       | string | ISPB do banco do beneficiário.   | 8          |

### Objeto guarantor

| Campo             | Tipo   | Descrição                           | Caracteres |
| ----------------- | ------ | ----------------------------------- | ---------- |
| `name`            | string | Nome do sacador avalista.           | -          |
| `person_type`     | string | Tipo de pessoa do sacador avalista. | 7          |
| `document_number` | string | Documento do sacador avalista.      | 14         |

### Objeto interest

| Campo                         | Tipo   | Descrição                | Caracteres |
| ----------------------------- | ------ | ------------------------ | ---------- |
| `interest_billing_start_date` | string | Data de início do juros. | 10         |
| `interest_amount_type`        | string | Tipo de juros.           | -          |
| `interest_amount`             | string | Valor do juros.          | -          |

### Objeto fine

| Campo                     | Tipo   | Descrição                | Caracteres |
| ------------------------- | ------ | ------------------------ | ---------- |
| `fine_billing_start_date` | string | Data de início da multa. | 10         |
| `fine_amount_type`        | string | Tipo de multa.           | -          |
| `fine_amount`             | string | Valor da multa.          | -          |

### Objeto discount

| Campo                 | Tipo   | Descrição                | Caracteres |
| --------------------- | ------ | ------------------------ | ---------- |
| `discount_limit_date` | string | Data limite do disconto. | 10         |
| `discount_type`       | string | Tipo de desconto.        | -          |
| `discount_amount`     | string | Valor do desconto.       | -          |

## Webhook de alteração de boleto

Update webhook

```json
    {
      "webhook_type": "baas.dda.bankslip.update",
      "key": "7c52d5f6-9db1-4a3c-bb03-1f76a2e8f9d2",
      "data": {
        "barcode": "00193000000001000000500000001234567890123457",
        "digitable_line": "00193000000001000000500000001234567890123456123",
        "status": "paid",
        "nominal_amount": 1050,
        "total_amount": 1200,
        "total_payment_amount": 1200,
        "partial_payment_allowed": false,
        "paid_fine": 150,
        "paid_interest": 50,
        "discount_amount": 0,
        "expiration": "2024-05-30",
        "max_payment_date": "2024-07-01",
        "beneficiary": {
            "name": "Tech Solutions Ltda.",
            "bank_code": "123",
            "bank_ispb": "12345678",
            "person_type": "legal",
            "document_number": "12345678000100"
        },
        "payer": {
            "name": "João Carlos",
            "person_type": "natural",
            "document_number": "12345678900"
        },
        "guarantor": { 
            "name": "Maria Junior", 
            "person_type": "natural",
            "document_number": "03903984900" 
        },
        "rebate_amount": 30.00,
        "interest": [
            {
                "interest_amount_type": "workdays_daily_amount",
                "interest_billing_start_date": "2024-05-21",
                "interest_amount": 10.00
            }
        ],
        "fine": [
            {
                "fine_billing_start_date": "2024-05-29",
                "fine_amount_type": "absolute",
                "fine_amount": 100.00
            }
        ],
        "discounts": [
            {
                "discount_limit_date": "2024-05-05",
                "discount_type": "absolute",
                "discount_amount": 50.00
            }
        ],
        "calculations": [],
        "calculation_model": "01",
      }
    }
```

### Body Params

| Campo                     | Tipo    | Descrição                                                                           | Caracteres |
| ------------------------- | ------- | ----------------------------------------------------------------------------------- | ---------- |
| `barcode`                 | string  | Código de barras do boleto.                                                         | 44         |
| `digitable_line`          | string  | Linha digitável do boleto.                                                          | 47         |
| `status`                  | enum    | [Enumeradores de status de um boleto.](#enumeradores-status)                        | -          |
| `nominal_amount`          | float   | Valor nominal do boleto.                                                            | -          |
| `total_amount`            | float   | Valor calculado do boleto.                                                          | -          |
| `total_payment_amount`    | float   | Valor de pagamento do boleto.                                                       | -          |
| `partial_payment_allowed` | boolean | Indicador de aceite de pagamento parcial.                                           | -          |
| `paid_fine`               | float   | Total de multa efetivado no pagamento do boleto, calculado a partir do valor total. | -          |
| `paid_interest`           | float   | Total de juros efetivado no pagamento do boleto, calculado a partir do valor total. | -          |
| `discount_amount`         | float   | Total de descontos no pagamento do boleto, calculado a partir do valor total.       | -          |
| `expiration`              | string  | Data de vencimento do boleto.                                                       | 10         |
| `max_payment_date`        | string  | Data limite de pagamento do boleto.                                                 | 10         |
| `payer`                   | object  | [Objeto pagador do boleto.](#objeto-payer)                                          | -          |
| `beneficiary`             | object  | [Objeto beneficiário do boleto.](#objeto-beneficiary)                               | -          |
| `guarantor`               | object  | [Objeto sacador avalista do boleto](#objeto-guarantor)                              | -          |
| `rebate_amount`           | float   | Valor de rebate.                                                                    | -          |
| `interest`                | list    | [Lista de objetos interest.](#objeto-interest)                                      | -          |
| `fine`                    | list    | [Lista de objetos fine.](#objeto-fine)                                              | -          |
| `discounts`               | list    | [Lista de objetos discount.](#objeto-discount)                                      | -          |
| `calculations`            | list    | Lista do grupo cálculo de boleto.                                                   | -          |
| `calculation_model`       | string  | Método de cálculo do valor atual do boleto.                                         | 2          |

---

# acg1

URL: /documentation/documentacoes ocultas/agc1/acg1

## Request

- ENDPOINT /baas/historic_card_settlement
- MÉTODO POST

**body.json**

```json
{
	"person_type": "natural",
	"name": "João Ninguem",
	"document_number": "42866592832",
	"signatures": [{
		"signed_object": {
			"raw_text": "Lorem ipsum dolor sit amet, consectetur a....",
			"document_key": "79003de0-2590-455d-9b73-426b8ca284eb",
			"document_md5": "7521bd5621d97af26b2c1721fc4023a8"
		},
		"authenticity": {
			"timestamp": "1970-01-01 00:00:01",
			"ip_address": "179.104.42.245",
			"session_id": "ddb1d063-4fdf-4330-af9c-3316e9142ff3",
			"facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
			"document_key": "79003de0-2590-455d-9b73-426b8ca284eb",
			"document_md5": "79003de0-2590-455d-9b73-426b8ca284eb"
		},
		"signer": {
			"name": "IVANILDO DE SENA LIMA",
			"email": "ivanlima2604@gmail.com",
			"phone": {
				"country_code": "055",
				"area_code": "11",
				"number": "999999999"
			},
			"document_number": "61766976204"
		},
		"authentication_type": "opt-in"
	}]
}

```

### Body Params

| Campo |  Tipo | Descrição |
|---|---| ---|
| `person_type`  | enum | Tipo de pessoa a ser consultada. | -- |
| `name`  | string | Nome do consultado. | -- |
| `document_number`  | string | CPF ou CNPJ do consultado. | -- |
| `signatures`  | array of objects | Lista contendo objetos de signatarios. | -- |

## Enumeradores

### Enumeradores marital_status

| Enumerador | Tradução | 
|---|---|
|  natural  |  Pessoa fisica |
|  legal  |  Pessoa juridica |

## Response

status: 201

**Response Body: PF**

```json
{
    "person_type": "natural",
    "name": "Sample Natural Person",
    "document_number": "50727483161",
    "signers": [
        {
            "name": "Sample Natural Person",
            "document_number": "50727483161",
            "email": "sample@gmail.com",
            "phone_number": "34987654321",
            "signature": {
                "authenticity": {
                    "ip_address": "127.0.0.1",
                    "session_id": "120a0a3ae723ff2858f9e0360f123723",
                    "third_party_access_token": "558f1a0b-38de-4b8d-b678-14b052adb1db",
                    "third_party_additional_data": {}
                },
                "signable_object": {
                    "document_key": "a43c1dde-0ecd-4086-8b94-714277a2dcee",
                    "document_md5": "57c0906e3c9902403ba373d9a7650f0a"
                }
            }
        }
    ],
    "historic_card_settlement_key": "74bf0f2e-8c53-4b5b-90bf-a0d21022bcff",
    "status": "signed",
    "historic_card_settlement_date": "2022-05-18T19:38:44"
}

```

status: 201

**Response Body: PJ**

```json
{
    "person_type": "legal",
    "name": "Sample Legal Person",
    "document_number": "28001500",
    "signers": [
        {
            "name": "Sample Signer",
            "document_number": "50727483161",
            "email": "sample@gmail.com",
            "phone_number": "34987654321",
            "signature": {
                "authenticity": {
                    "ip_address": "127.0.0.1",
                    "session_id": "120a0a3ae723ff2858f9e0360f123723",
                    "third_party_access_token": "candidate - 37767",
                    "third_party_additional_data": {}
                },
                "signable_object": {
                    "document_key": "a43c1dde-0ecd-4086-8b94-714277a2dcee",
                    "document_md5": "57c0906e3c9902403ba373d9a7650f0a"
                }
            }
        }
    ],
    "historic_card_settlement_key": "c2d4bfd3-6eaf-40ee-9eb1-697992336dbb",
    "status": "signed",
    "historic_card_settlement_date": "2022-05-18T19:37:38"
}

```

status: 400

**body.json**

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

## Webhooks

Após o envio de uma solicitação de consulta o resto do fluxo fica a cargo da QI Tech. Será então enviado um webhook apresentando dois modelos distintos:

- Em caso de consulta encontrada com sucesso, receberá um campo "**status**" com o valor "**completed**", neste caso, o objeto "**data**" trará as demais informações da consulta.

- Em caso de documento não encontrado na base para o período consultado, receberá um campo "**status**" com o valor "**not_found**", informando que a consulta não trouxe nenhuma informação.

## Exemplo de sucesso

No webhook temos o objeto "**data**" com os campos:

"**valueless_months**": Número de meses sem atividade.  
"**card_schemes**": São os arranjos de pagamentos que constituíram o valor total liquidado.  
"**value**": Valor total liquidado em cartões.

```json
{
   "status": "completed",
   "webhook_type": "historic_card_settlement",
   "data": {
      "valueless_months": 0,
      "card_schemes": [
         {
            "code": "003",
            "enumerator": "credit_mastercard",
            "description": "Mastercard Crédito"
         }
      ],
      "value": 847.86
   },
   "event_datetime": "2022-05-18T20:57:00",
   "key": "38934f1b-204f-4fc4-844d-5ad562ff36f6"
}
```

## Em caso de consulta não encontrada

```json
{
   "status": "not_found",
   "webhook_type": "historic_card_settlement",
   "event_datetime": "2022-05-18T20:57:00",
   "key": "38934f1b-204f-4fc4-844d-5ad562ff36f6"
}
```

---

# introducao

URL: /documentation/documentacoes ocultas/agc1/introducao

O histórico de liquidação de cartão é um novo sistema de consultas que fornece informações sobre os pagamentos liquidados de recebíveis de cartões de um determinado cliente em um período específico.

Estes dados são disponibilizados às instituições financeiras pelo banco central através de um sistema chamado ACG1. Para acessa-los a QI Tech precisa de uma autorização do consultado. Assim que as assinaturas forem efetuadas você receberá todas as informações relativas aos 12 meses anteriores à data de consulta.

Isso inclui:

- Valor Total agregado de pagamentos liquidados neste período.

- Quais os Arranjos de pagamentos que constituíram este valor total.

- Quantidade de meses em que não houve nenhum pagamento;

:::danger Atenção!

Assim como as demais APIs a liberação do serviço deve ser feita junto ao nosso time e as chamadas são autenticadas.
:::

## Fluxo de consulta

Para executar a consulta do histórico de liquidação de cartão, a QI Tech precisa enviar um documento ao Banco Central formalizando e solicitando a consulta. Este documento é gerado dentro do nosso fluxo interno com base no payload enviado ao nosso endpoint 16.1.

O Fluxo de consulta consiste em:

- Solicitação da consulta via requisição;
- Recebimento do webhook com o resultado da consulta;

---

# Permissão (Geral):

URL: /documentation/documentacoes ocultas/perfis_de_acesso

#### Observador

Não consegue realizar nenhuma ação na plataforma, somente visualiza os dados disponíveis.

- Exportar relatórios;
- Download de comprovantes
- Exportar extratos.

#### Operador

 Tem todos os poderes do "observador" e ainda tem poderes para:

- Cadastrar operação;
- Registrar boletos;
- Comandar instruções de boletos;
- Incluir pedido de abertura de conta escrow;
- Incluir solicitação de TED, PIX e pagamento de boletos;
- Solicitar consulta SCR;

#### Administrador

Tem todos os poderes do operador e ainda tem poderes para: 

- Aprovar pagamentos (ted, pix e boleto);
- fazer a gestão de acessos do portal e inclusão de chaves de integração, 
- cadastro de webhooks.

---

# cancelamento_de_solicitacao.md

URL: /documentation/documentacoes ocultas/scr/cancelamento_de_solicitacao.md

## Request

- ENDPOINT /scr
- MÉTODO DELETE

**body.json**

```json
{
	"key": "56b330f0-fb6e-4dab-bede-8ae2ecb3f4c6",
	"requester_person_key": "1da2dbd0-af45-4b4d-b685-896e449fa216"
}

```

### Body Params

| Campo |  Tipo | Descrição |
|---|---| ---|
| `key`  | enum | Chave da solicitação (SCR_KEY). | -- |
| `requester_person_key`  | string | Chave do solicitante. | -- |

## Response

status: 200

**Response Body**

```json
{
    "consent_term": null,
    "consulted_at": null,
    "created_at": "2020-04-24",
    "report_end_date": "2020-03",
    "report_start_date": "2020-01",
    "result_document": null,
    "origin_key": "353b7aea-0bc5-4981-8015-16f7ba4252d4",
    "scr_status": "canceled",
    "signers": [
        {
            "name": "Diretor 1",
            "document_number": "03030230074",
            "email": "diretor1@email.com"
        },
        {
            "name": "Diretor 2",
            "document_number": "03030230074",
            "email": "diretor2@email.com"
        }
    ],
    "subject_document_number": "05305188000108",
    "subject_name": "Padaria do Joao Ninguem",
    "subject_person_type": "legal"
}

```

status: 400

**body.json**

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

---

# consultar_solicitacao

URL: /documentation/documentacoes ocultas/scr/consultar_solicitacao

## Request

Pensando em facilitar o processo, caso o cliente queira fazer uma nova consulta com novas datas base à alguem que já fora previamente consultado, oferecemos a operação /scr/redo. A vantagem de utilizar esta operação é que, caso o documento de autorização para aquela pessoa ainda esteja válido, não haverá a criação de um novo documento para assinatura¹ e a consulta será criada imediatamente. O formato de assinatura do header e do body desta requisição é descrito em detalhes aqui.

- ENDPOINT /scr/ SCR_KEY
- MÉTODO GET

### Path Params

| Campo |  Tipo | Descrição |
|---|---| ---|
| `scr_key`  | string | Chave da solicitação de consulta SCR. | -- |

## Response

status: 200

**Response Body**

```json
{
    "consent_term": null,
    "consulted_at": null,
    "created_at": "2020-04-24",
    "report_end_date": "2020-03",
    "report_start_date": "2020-01",
    "result_document": null,
    "origin_key": "db5d1627-841f-4ddd-97f8-925557531718",
    "scr_status": "pending_signature",
    "signers": [
        {
            "name": "Diretor 1",
            "document_number": "03030230074",
            "email": "diretor1@email.com"
        },
        {
            "name": "Diretor 2",
            "document_number": "03030230074",
            "email": "diretor2@email.com"
        }
    ],
    "subject_document_number": "05305188000108",
    "subject_name": "Padaria do Joao Ninguem",
    "subject_person_type": "legal"
}

```

status: 400

**body.json**

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

---

# consultar_solicitacoes

URL: /documentation/documentacoes ocultas/scr/consultar_solicitacoes

## Request

Pensando em facilitar o processo, caso o cliente queira fazer uma nova consulta com novas datas base à alguem que já fora previamente consultado, oferecemos a operação /scr/redo. A vantagem de utilizar esta operação é que, caso o documento de autorização para aquela pessoa ainda esteja válido, não haverá a criação de um novo documento para assinatura¹ e a consulta será criada imediatamente. O formato de assinatura do header e do body desta requisição é descrito em detalhes aqui.

- ENDPOINT /scr
- MÉTODO GET

## QUERY PARAMS

| Campo |  Tipo | Descrição |
|---|---| ---|
| `origin_key`  | string | Chave de identificação da operação. Retorna todas as consultas referentes à aquela operação. | -- |
| `subject_person_type`  | enum | Filtro de tipo de pessoa consultada. | -- |
| `subject_document_number`  | string | Filtro de "CPF" ou "CNPJ", não aceita parcial. | -- |
| `created_at_start_date`  | string | Filtro de inicio da faixa de data de criação (formato: YYYY-MM-DD). | -- |
| `created_at_end_date`  | string | Filtro de fim da faixa de data de criação (formato: YYYY-MM-DD). | -- |
| `consulted_at_start_date`  | string | Filtro de inicio da faixa de data de consulta (formato: YYYY-MM-DD). | -- |
| `consulted_at_end_date`  | datetime | Filtro de fim da faixa de data de consulta (formato: YYYY-MM-DD).| -- |
| `scr_status`  | enum | Filtro de status da consulta. | -- |
| `page`  | integer | Página atual que está sendo consultada. | -- |
| `page_size`  | integer | Quantidade de resultados que cabem na página. | -- |

## Enumeradores

### Enumeradores person_type

| Enumerador | Tradução | 
|---|---|
|  natural  |  Pessoa fisica |
|  legal  |  Pessoa juridica |

### Enumeradores scr_status

| Enumerador | Tradução | 
|---|---|
|  created  |  Criado |
|  pending_signature  |  Assinatura pendente |
|  signed  |  Assinado|
|  rejected  |  Rejeitado |
|  consulted  |  Consultado |
|  error  |  Com erro |
|  canceled  |  Cancelado |

## Response

status: 200

**Response Body**

```json
{
    "data": [
        {
            "consent_term": null,
            "consulted_at": null,
            "created_at": "2020-04-24",
            "report_end_date": "2020-03",
            "report_start_date": "2020-01",
            "result_document": null,
            "origin_key": "db5d1627-841f-4ddd-97f8-925557531718",
            "scr_status": "pending_signature",
            "signers": [
                {
                    "name": "Diretor 1",
                    "document_number": "03030230074",
                    "email": "diretor1@email.com"
                },
                {
                    "name": "Diretor 2",
                    "document_number": "03030230074",
                    "email": "diretor2@email.com"
                }
            ],
            "subject_document_number": "05305188000108",
            "subject_name": "Padaria do Joao Ninguem",
            "subject_person_type": "legal"
        }
    ],
    "pagination": {
        "current_page": 1,
        "next_page": null,
        "rows_per_page": 100,
        "total_pages": 1,
        "total_rows": 55
    }
}

```

status: 400

**body.json**

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

---

# introducao

URL: /documentation/documentacoes ocultas/scr/introducao

Uma das funcionalidades que podemos oferecer em nossa integração é a possibilidade de consulta dos dados disponíveis no SCR de uma pessoa física ou jurídica via API. Com apenas uma solicitação de consulta enviada via request, a QI Tech se encarrega de enviar o pedido de autorização aos consultados, realizar a consulta (após autorizada) e despachar os resultados ao solicitante via webhook.

Além disso, para consultas PJ é possível, com uma única solicitação, consultar a empresa e seus representantes, gerando uma consulta separa para cada um dos documentos.

Assim como as demais APIs a liberação do serviço deve ser feita junto ano nosso time e as chamadas são autenticadas.

Nas subseções abaixo veremos como executar uma consulta ao SCR.

## Fluxo de consulta ao SCR

O Fluxo de consulta ao SCR consiste em:

- Solicitação da consulta (solicitado via request)
- Assinatura da autorização da consulta pelo consultado ou os representantes (enviado via e-mail)
- Realização da consulta (informado resultado via webhook)

---

# refazer_consulta

URL: /documentation/documentacoes ocultas/scr/refazer_consulta

## Request

Pensando em facilitar o processo, caso o cliente queira fazer uma nova consulta com novas datas base à alguem que já fora previamente consultado, oferecemos a operação /scr/redo. A vantagem de utilizar esta operação é que, caso o documento de autorização para aquela pessoa ainda esteja válido, não haverá a criação de um novo documento para assinatura¹ e a consulta será criada imediatamente. O formato de assinatura do header e do body desta requisição é descrito em detalhes aqui.

- ENDPOINT /scr/redo
- MÉTODO POST

**body.json**

```json
{
	"report_start_date": "2019-02",
	"report_end_date": "2020-03",
    "origin_key": "bf6b5e8b-93df-4443-b1fc-d760db6ea4ff"
}

```

### Body Params

| Campo |  Tipo | Descrição |
|---|---| ---|
| `report_start_date`  | enum | Data de início da consulta (formato "AAAA-MM"). | -- |
| `report_end_date`  | string | Data final da consulta (formato "AAAA-MM"). | -- |
| `origin_key`  | string | Chave do SCR original (SRC_KEY) que será utilizada para refazer a consulta. | -- |

## Response

status: 200

**Response Body**

```json
{
   "consent_term":"https://urldasassinaturas.com/assinaturas.zip",
   "consulted_at":"2020-05-08",
   "created_at":"2020-05-08",
   "origin_key":"353b7aea-0bc5-4981-8015-16f7ba4252d4",
   "report_end_date":"2020-03",
   "report_start_date":"2019-02",
   "result_document":"https://urldodocumento.com/documento_consulta.pdf",
   "scr_key":"10b3feb4-6afa-425b-8537-99c2aa7afd74",
   "scr_status":"consulted",
   "signers":[
      {
         "document_number":"41184562067",
         "email":"joao.ninguem@yopmail.com",
         "name":"Joao Ninguem"
      }
   ],
   "subject_document_number":"41184562067",
   "subject_name":"Joao Ninguem",
   "subject_person_type":"natural"
}

```

status: 400

**body.json**

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

---

# solicitacao_de_consulta

URL: /documentation/documentacoes ocultas/scr/solicitacao_de_consulta

## Request

- ENDPOINT /scr
- MÉTODO POST

**body.json**

```json
{
	"person_type": "natural",
	"name": "João Ninguem",
	"document_number": "42866592832",
    "check_representatives": true,
    "report_start_date": "2019-02",
    "report_end_date": "2020-03",
    "signatures": [{
		"signed_object": {
			"raw_text": "Lorem ipsum dolor sit amet, consectetur a....",
			"document_key": "79003de0-2590-455d-9b73-426b8ca284eb",
			"document_md5": "7521bd5621d97af26b2c1721fc4023a8"
		},
		"authenticity": {
			"timestamp": "1970-01-01 00:00:01",
			"ip_address": "179.104.42.245",
			"session_id": "ddb1d063-4fdf-4330-af9c-3316e9142ff3",
			"facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb",
			"document_key": "79003de0-2590-455d-9b73-426b8ca284eb",
			"document_md5": "79003de0-2590-455d-9b73-426b8ca284eb"
		},
		"signer": {
			"name": "IVANILDO DE SENA LIMA",
			"email": "ivanlima2604@gmail.com",
			"phone": {
				"country_code": "055",
				"area_code": "11",
				"number": "999999999"
			},
			"document_number": "61766976204"
		},
		"authentication_type": "opt-in"
	}]
}

```

### Body Params

| Campo |  Tipo | Descrição |
|---|---| ---|
| `person_type`  | enum | Tipo de pessoa a ser consultada. | -- |
| `name`  | string | Nome do consultado. | -- |
| `document_number`  | string | CPF ou CNPJ do consultado. | -- |
| `check_representatives`  | boolean | Campo determinante para que haja a consulta dos representantes da empresa (booleano "true" ou "false", se omitido considera-se falso). | -- |
| `report_start_date`  | string | Data de início da consulta (formato "AAAA-MM"). A data mínima disponível para consulta na QI Tech é 2019-02. | -- |
| `report_end_date`  | string | Data final da consulta (formato "AAAA-MM"). | -- |
| `signatures`  | array of objects | Lista contendo objetos de signatarios. | -- |

## Enumeradores

### Enumeradores person_type

| Enumerador | Tradução | 
|---|---|
|  natural  |  Pessoa fisica |
|  legal  |  Pessoa juridica |

## Response

status: 200

**Response Body: PF**

```json
{
	"person_type": "legal",
	"name": "Padaria do Joao Ninguem",
	"document_number": "05305188000108",
    "signers": [
        {
            "name": "Diretor 1",
            "document_number": "41184562067",
            "email": "diretor1@email.com"
        },
        {
            "name": "Diretor 2",
            "document_number": "18631260070",
            "email": "diretor2@email.com"
        }
    ],
	"report_start_date": "2019-02",
	"report_end_date": "2020-03" ,
    "check_representatives": true
}

```

status: 200

**Response Body: PJ**

```json
{
   "webhook_type": "scr",
   "key": "f33384e8-13ed-4e43-adf3-1ba20a4a6004",
   "status": "pending_signature",
   "event_datetime": "1970-01-01 00:00:01"
}

```

status: 400

**body.json**

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

---

# webhook

URL: /documentation/documentacoes ocultas/scr/webhook

Após o envio de uma solicitação de consulta SCR com sucesso o resto do fluxo fica a cargo da QI Tech. O acompanhamento do resultado da operação é dado via Webhook seguindo o fluxo previamente estipulado. O padrão utilizado é: em caso de sucesso é enviado um webhook informando os dados da consulta, em caso de falha, um webhook é enviado informando que a solicitação foi rejeitada. Além disso o cliente pode escolher durante a contratação do serviço se os dados da consulta serão entregues apenas em pdf ou completo, que no caso retorna além do PDF todos os dados da consulta em JSON. Neste momento o cliente também recebe a chave individual da consulta scr **SCR_KEY**.

## Exemplos de sucesso

Consulta somente em PDF:

```json
{
   "data": {
    "consent_term": "https://urldasassinaturas.com/assinaturas.zip",    
    "consulted_at": "2020-05-08",    
    "created_at": "2020-05-08",   
    "origin_key": OPERATION_KEY,  
    "report_end_date": "2020-03",  
    "report_start_date": "2019-02",    
    "result_document": "https://urldodocumento.com/documento_consulta.pdf",   
    "scr_key": SCR_KEY,  
    "scr_status": "consulted",  
    "signers": [
         {
          "document_number": "41184562067",      
          "email": "joao.ninguem@yopmail.com",      
          "name": "Joao Ninguem",
         }
    ],
    "subject_document_number": "41184562067",   
    "subject_name": "Joao Ninguem",
    "subject_person_type": "natural",
   },
   "webhook_type": "scr",
   "event_datetime": EVENT_DATE_TIME,
   "status": "consulted",
   "key": OPERATION_KEY,
}
```

Consulta completa:

```json
{
   "data":{
      "consent_term":"https://urldasassinaturas.com/assinaturas.zip",
      "consulted_at":"2020-05-08",
      "created_at":"2020-05-08",
      "origin_key": OPERATION_KEY,
      "report_end_date":"2020-03",
      "report_start_date":"2019-02",
      "result_document":"https://urldodocumento.com/documento_consulta.pdf",
      "scr_key": SCR_KEY,
      "scr_status":"consulted",
      "scr_data":[
         {
            "reference_date":"2020-03",
            "financial_institution_count":"3",
            "operation_count":"10",
            "assumed_coobligation":"10235",
            "receive_coobligation":"23569",
            "start_relationship":"2000-05-01",
            "disagreement_operation_count":"2",
            "disagreement_operation_value":"523",
            "subjudice_operations_count":"1",
            "subjudice_operations_value":"10000",
            "indirect_risk":"200000",
            "error":{
               "error_code":"",
               "description":"",
               "error_type":""
            },
            "operation_items":[
               {
                  "due_value": "46800",
                  "exchange_variation": "N",
                  "category_sub":{
                     "category":{
                        "category_code": 2,
                        "category_description": "Empréstimos"

                     },
                     "category_sub_code": 3,
                     "description": "crédito pessoal - sem consignação em folha de pagam."
                  },
                  "due_type":{
                      "due_type_group": "Vencido",
                      "due_code": "205",
                      "description": "Créditos vencidos de 1 a 14 dias",
                  }
               }
            ]
         }
      ],
      "signers":[
         {
            "document_number":"41184562067",
            "email":"joao.ninguem@yopmail.com",
            "name":"Joao Ninguem"
         }
      ],
      "subject_document_number":"41184562067",
      "subject_name":"Joao Ninguem",
      "subject_person_type":"natural"
   },
   "webhook_type":"scr",
   "event_datetime": EVENT_DATE_TIME,
   "status":"consulted",
   "key": OPERATION_KEY
}
```

Consulta com representantes:

```json
{
   "data":[
      {
         "consent_term":"https://urldasassinaturas.com/assinaturas.zip",
         "consulted_at":"2020-08-12",
         "created_at":"2020-08-12",
         "origin_key": OPERATION_KEY,
         "report_end_date":"2019-07",
         "report_start_date":"2019-06",
         "result_document":"https://urldodocumento.com/documento_consulta.pdf",
         "scr_key": SCR_KEY,
         "scr_status":"consulted",
         "signed_at":"2020-08-12",
         "signers":[
            {
               "document_number":"00152300074",
               "email":"joao.ninguem@yopmail.com",
               "name":"João Almeida"
            }
         ],
         "subject_document_number":"97381542000193",
         "subject_name":"Beazini Pizzas",
         "subject_person_type":"legal"
      },
      {
         "consent_term":"https://urldasassinaturas.com/assinaturas.zip",
         "consulted_at":"2020-08-12",
         "created_at":"2020-08-12",
         "origin_key":OPERATION_KEY,
         "report_end_date":"2019-07",
         "report_start_date":"2019-06",
         "result_document":"https://urldodocumento.com/documento_consulta.pdf",
         "scr_key":SCR_KEY,
         "scr_status":"consulted",
         "signed_at":"2020-08-12",
         "signers":[
            {
               "document_number":"00152300074",
               "email":"joao.ninguem@yopmail.com",
               "name":"João Almeida"
            }
         ],
         "subject_document_number":"00152300074",
         "subject_name":"João Almeida",
         "subject_person_type":"natural"
      }
   ],
   "webhook_type":"scr",
   "event_datetime":"EVENT_DATE_TIME",
   "status":"consulted",
   "key": OPERATION_KEY
}
```

## Exemplo de falha

```json
{
   "data": {
    "consent_term": null,    
    "consulted_at": "2020-05-08",    
    "created_at": "2020-05-08",   
    "origin_key": OPERATION_KEY,  
    "report_end_date": "2020-03",  
    "report_start_date": "2019-02",    
    "result_document": null,   
    "scr_key": SCR_KEY,  
    "scr_status": "rejected",  
    "signers": [
         {
            "document_number":"41184562067",
            "email":"joao.ninguem@yopmail.com",
            "name":"Joao Ninguem"
         }
    ],
    "subject_document_number": "41184562067",   
    "subject_name": "Joao Ninguem",
    "subject_person_type": "natural",
   },
   "webhook_type": "scr",
   "event_datetime": EVENT_DATE_TIME,
   "status": "rejected",
   "key": OPERATION_KEY,
}
```

---

# Atualizar cessionário do contrato de crédito

URL: /documentation/emissao_de_divida/atualizar_cessionario_047911bb-d3fb-48fe-88fd-aebdeb7e11ad

    ### Importante:

    Para atualização de cessionário, os seguintes requisitos devem ser atendidos:
    - a operação de crédito não pode estar cancelada;
    - a operação de crédito não pode estar no meio de um processo de cessão;
    - a operação de crédito não pode estar cedida;
    - deve existir uma configuração de cessão com o novo comprador.

## Request

ENDPOINT /debt/ DEBT-KEY /purchaser
MÉTODO PATCH

**Request Body**

```json
{
  "purchaser_document_number": "01234567890001"
}
```

### Path Params

| Campo | Tipo | Descrição |
|---|---|---|
| `debt_key` * | string | debt_key da operação. |

## Response

STATUS 201

**Response Body**

```json
{}
```

STATUS 400

**Response Body**

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Credit Operation is already in assignment process for changing the purchaser.\", \"translation\": \"A opera\u00e7\u00e3o de cr\u00e9dito est\u00e1 em processo de cess\u00e3o e n\u00e3o pode ter seu comprador alterado.\", \"extra_fields\": {}, \"code\": \"COP000376\"}"
}
```

---

# Atualizar informações das partes relacionadas ao contrato de crédito

URL: /documentation/emissao_de_divida/atualizar_dados_da_parte_relacionada

## Request

ENDPOINT /debt/ DEBT-KEY /related_party/ RELATED-PARTY-KEY
MÉTODO PATCH

### Pessoa Física
**Request Body**

```json
{
  "name": "Teste teste",
  "email": "teste@teste.com",
  "address": {
    "street": "Rua teste",
    "neighborhood": "Bairro teste",
    "number": "123",
    "postal_code": "09725540",
    "city": "S\u00e3o Caetano do sul",
    "state": "SP"
  },
  "phone": {
    "country_code": "55",
    "area_code": "11",
    "number": "41234123"
  },
  "mother_name": "M\u00e3e Teste",
  "document_identification_number": "1234567",
  "nationality": "Brasileiro",
  "marital_status": "single",
  "profession": "Diretor Executivo",
  "birth_date": "1999-01-01",
  "document_identification_date": "2015-01-01",
  "document_identification_type": "cnh",
  "gender": "female"
}
```

### Pessoa Jurídica
**Request Body**

```json
{
	"name": "Teste teste",
	"email": "teste@teste.com",
	"address": {
		"street": "Rua teste",
		"neighborhood": "Bairro teste",
		"number": "123",
		"postal_code": "09725540",
		"city": "S\u00e3o Caetano do sul",
		"state": "SP"
	},
	"phone": {
		"country_code": "55",
		"area_code": "11",
		"number": "41234123"
	},
	"trading_name": "Nome fantasia teste",
	"foundation_date": "2020-01-01",
	"simples_nacional_participant": false
}
```

### Path Params

| Campo | Tipo | Descrição |
|---|---|---|
| `debt_key` * | string | debt_key da operação. |
| `related_party_key` * | string |  key da parte relacionada que os documentos serão enviados. |

## Response

STATUS 201

**Response Body**

```json
{
	"status": "waiting_signature",
	"data": {
		"annual_cet": 26.0802,
		"cet": 1.95,
		"installments": [**],
		"disbursed_issue_amount": 2209.06,
		"contract_fees": [{
			"fee_amount": 22.71,
			"fee_type": "spread"
		}],
		"prefixed_interest_rate": {
			"created_at": "2023-07-21T16:30:07",
			"interest_base": "calendar_days_365",
			"annual_rate": 0.23872053,
			"monthly_rate": 0.018,
			"daily_rate": 0.00058669
		},
		"contract_fee_amount": 22.71,
		"requester_identifier_key": "af0e8a5d-650e-4348-b955-a424307c44df",
		"iof_charge_method": "financed",
		"external_contract_fee_amount": 0,
		"borrower": {
			"document_number": "04062377942",
			"related_party_key": "c3b213ee-897a-4e42-9697-6c0b56fb0020",
			"name": "TESTE TESTE"
		},
		"additional_iof": 8.629534,
		"entry": null,
		"external_contract_fees": [**],
		"collaterals": [**],
		"total_pre_fixed_amount": 1088.47822388,
		"contract": {
			"urls": [
				"https://storage.googleapis.com/live-doc-api/documents/a0e3678a-9d48-47e8-8e00-ed9435713588/teste.pdf"
			],
			"number": "0008938245/TT"
		},
		"net_external_contract_fee_amount": 0,
		"number_of_installments": 8,
		"total_iof": 61.87,
		"base_iof": 53.2421439,
		"issue_amount": 2270.93,
		"assignment_amount": 2293.64
	},
	"event_datetime": "2023-07-21 16:30:11",
	"webhook_type": "debt",
	"key": "01d62579-be1e-482f-b766-069786b44344"
}
```

STATUS 400

**Response Body**

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Collateral type social_security is not allowed for update related party.\", \"translation\": \"O tipo de garantia social_security n\u00e3o permite atualizar a parte relacionada.\", \"extra_fields\": {}, \"code\": \"COP000328\"}"
}
```

---

# Autorizar desembolso

URL: /documentation/emissao_de_divida/autorizar_desembolso

## Request

ENDPOINT /debt/ DEBT-KEY /allow_disbursement
MÉTODO POST

**Request Body**

```json
{
   "allow_disbursement": true
}

```

### Path Params

| Campo | Tipo | Descrição |
|---|---| ---|
| `debt_key` *(obrigatório)* | string | ID da divida emitida. |

### Body Params

| Campo | Tipo | Descrição |
|---|---| ---|
| `allow_disbursement` | string | Indicação de autorização para desembolso. |

## Response

STATUS 201

**Request Body**

```json
{
  "additional_iof": 45.65,
  "credit_operation_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
  "contract_number": "0000192840/AMT",
  "annual_cet": 226.17,
  "assigned": false,
  "assigned_at": null,
  "assignment_amount": 6844.51,
  "issue_amount": 6844.51,
  "disbursed_issue_amount": 6594,
  "final_disbursement_amount": 6594,
  "base_iof": 204.86,
  "calculus_correction": null,
  "cet": 10.35,
  "collateral_constituted": true,
  "collateral_type": null,
  "contract_fee_amount": 0,
  "external_contract_fee_amount": 0,
  "net_external_contract_fee_amount": 0,
  "creditor_bank_account_key": null,
  "disbursement_date": "2026-01-01",
  "disbursement_start_date": "2026-01-01",
  "disbursement_end_date": "2026-01-01",
  "first_due_date": "2026-12-10",
  "number_of_installments": 4,
  "interest_grace_period": 0,
  "interest_payment_month_period": 1,
  "interest_subsidy_amount": 0,
  "interest_subsidy_percentage": 0,
  "iof_charge_method": "financed",
  "ipoc_code": "3240250202021123456789090000542149/T",
  "issue_date": "2026-02-02",
  "issuer_document_number": "12345678909",
  "issuer_name": "teste",
  "origin_key": "8bf10bc5-345e-4d4c-b038-650bc7277c6e",
  "principal_amortization_month_period": 1,
  "principal_grace_period": 0,
  "purchaser_document_number": "32402502000135",
  "requester_key": "783ea550-9e70-4482-bcae-127a913b5b1e",
  "requester_identifier_key": "8bf10bc5-345e-4d4c-b038-650bc7277c6e",
  "settlement_bank_account_key": null,
  "share_quantity": 7,
  "third_party_account_key": "5d068423-6094-49e4-b15b-7740038295a8",
  "total_iof": 250.51,
  "original_total_iof": null,
  "facial_biometrics_enabled": false,
  "selfie_enabled": false,
  "tax_exempt_amount": 0,
  "is_allowed_to_disburse": true,
  "is_refinancing": false,
  "is_portability": false,
  "credit_rating": null,
  "first_due_date_delay": null,
  "operation_extra_fields": {},
  "if_code": null,
  "disbursement_key": "f754470c-e979-45c7-8956-bbd6960823f3",
  "created_at": "2026-02-02T20:00:12",
  "is_amendment": false,
  "all_day_disbursement": true,
  "disbursement_inelegibility_reason": null,
  "disbursement_inelegibility_reason_issued": null,
  "portability_amount": 0,
  "disburse_before_assign": true,
  "requester_name": "Requester Teste",
  "disbursed_at": null,
  "assignment_key": null,
  "isin_number": null,
  "extra_fields": {
  },
  "financial_index": null,
  "payroll_data": null,
  "kyc": null,
  "entry": null,
  "amendment_credit_operation": null,
  "disbursement_confirmed_at": null,
  "portability_origin_contract": null,
  "credit_operation_status": {
    "translation_path": "co.CreditOperationStatus.waiting_disbursement",
    "translation_ptbr": "Aguardando Desembolso",
    "enumerator": "waiting_disbursement"
  },
  "credit_operation_type": {
    "translation_path": "co.CreditOperationType.ccb",
    "enumerator": "ccb"
  },
  "operation_type": {
    "translation_path": "co.OperationType.structured_operation",
    "enumerator": "structured_operation"
  },
  "custodian": {
    "translation_path": "co.Custodian.qi_scd",
    "enumerator": "qi_scd"
  },
  "payment_and_settlement_agent": {
    "enumerator": "qi_scd",
    "translation_path": "co.PaymentAndSettlementAgent.qi_scd"
  },
  "interest_type": {
    "translation_path": "co.InterestType.pre_price_days",
    "enumerator": "pre_price_days"
  },
  "document_certifier": {
    "translation_path": "co.DocumentCertifier.qi_sign",
    "enumerator": "qi_sign"
  },
  "assignment_status": {
    "enumerator": "not_assigned"
  },
  "origin_type": {
    "enumerator": "lego-api",
    "translation_path": "co.OriginType.lego-api"
  },
  "payment_type": {
    "translation_path": "co.PaymentType.unmonitored",
    "enumerator": "unmonitored"
  },
  "signature_method": {
    "enumerator": "email"
  },
  "central_depository": null,
  "registration_institution": {
    "translation_path": "co.RegistrationInstitution.qi_scd",
    "enumerator": "qi_scd"
  },
  "tax_configuration": {
    "iof_additional_rate": 0.0038,
    "iof_rate": 0.000082
  },
  "prefixed_interest_rate": {
    "annual_rate": 2.1384283767,
    "daily_rate": 0.0031383999,
    "interest_base": {
      "translation_path": "co.InterestBase.calendar_days_365",
      "enumerator": "calendar_days_365",
      "year_days": 365
    },
    "monthly_rate": 0.1,
    "created_at": "2026-02-02T20:00:12"
  },
  "post_fixed_interest_rate": null,
  "original_prefixed_interest_rate": {
    "annual_rate": 2.13842838,
    "daily_rate": 0.0031384,
    "interest_base": {
      "translation_path": "co.InterestBase.calendar_days_365",
      "enumerator": "calendar_days_365",
      "year_days": 365
    },
    "monthly_rate": 0.1,
    "created_at": "2026-02-02T20:00:12"
  },
  "fine_configuration": {
    "contract_fine_rate": 0,
    "fine_delay_rate": {
      "annual_rate": 0,
      "daily_rate": 0,
      "interest_base": {
        "translation_path": "co.InterestBase.calendar_days",
        "enumerator": "calendar_days",
        "year_days": 360
      },
      "monthly_rate": 0,
      "created_at": "2026-02-02T20:00:12"
    }
  },
  "early_settlement_configuration": {
    "early_settlement_configuration_type": {
      "enumerator": "fixed_rate",
      "translation_path": "co.EarlySettlementConfigurationType.fixed_rate"
    },
    "effective_end_date": null,
    "fixed_interest_rate": 0
  },
  "resource_source_account": {
    "enumerator": "third_party",
    "translation_path": "co.ResourceSourceAccount.third_party"
  },
  "endorsement": null,
  "rebate_account": null,
  "contract_fees": [],
  "external_contract_fees": [],
  "disbursement_account": [
    {
      "account_branch": "2874",
      "account_digit": "0",
      "account_number": "99581339",
      "account_type": "checking_account",
      "amount_receivable": null,
      "digitable_line": null,
      "disbursement_account_key": "bfe5dd10-2fb4-41a8-b1e1-02811b2266f6",
      "disbursement_type": "pix",
      "document_number": "12345678909",
      "end_to_end_id": null,
      "financial_institutions": {
        "code_number": 1,
        "is_pix_participant": true,
        "is_active": true,
        "name": "BANCO DO BRASIL S.A.",
        "ispb": 0
      },
      "financial_institutions_code_number": 1,
      "is_pix_disbursement": true,
      "ispb": "0",
      "name": "Name",
      "percentage_receivable": 100,
      "pix_key": null,
      "pix_transfer_key": "4db1ab83-4305-46fa-8373-0dd5ee4abfe9",
      "pix_type": "manual",
      "qr_code_key": null,
      "qr_code_url": null,
      "receipt_document_key": null,
      "receipt_url": null,
      "retry_counter": 0,
      "retry_vector": null,
      "transaction_key": null,
      "webhook_key": null
    }
  ],
  "disbursement_options": [
    {
      "additional_iof": 45.65,
      "annual_cet": 226.17,
      "assignment_amount": 6844.51,
      "base_iof": 204.86,
      "calculus_correction": null,
      "cet": 10.35,
      "contract_fee_amount": 0,
      "contract_fees": [],
      "disbursed_issue_amount": 6594,
      "disbursement_date": "2026-02-02",
      "external_contract_fee_amount": 0,
      "external_contract_fees": [],
      "final_disbursement_amount": 6594,
      "first_due_date": "2026-12-10",
      "installments": [
        {
          "additional_costs": [],
          "business_due_date": "2026-12-10",
          "calendar_days": 311,
          "due_date": "2026-12-10",
          "due_interest": 0,
          "due_principal": 6844.51,
          "fine_amount": null,
          "has_interest": true,
          "installment_number": 1,
          "post_fixed_amount": 0,
          "pre_fixed_amount": 5204.15,
          "principal_amortization_amount": 0,
          "tax_amount": 0,
          "total_amount": 5204.15,
          "workdays": 213
        },
        {
          "additional_costs": [],
          "business_due_date": "2027-01-11",
          "calendar_days": 31,
          "due_date": "2027-01-10",
          "due_interest": 6088.45962499,
          "due_principal": 6844.51,
          "fine_amount": null,
          "has_interest": true,
          "installment_number": 2,
          "post_fixed_amount": 0,
          "pre_fixed_amount": 5204.15,
          "principal_amortization_amount": 0,
          "tax_amount": 0,
          "total_amount": 5204.15,
          "workdays": 19
        },
        {
          "additional_costs": [],
          "business_due_date": "2027-02-10",
          "calendar_days": 31,
          "due_date": "2027-02-10",
          "due_interest": 2203.63074342,
          "due_principal": 6844.51,
          "fine_amount": null,
          "has_interest": true,
          "installment_number": 3,
          "post_fixed_amount": 0,
          "pre_fixed_amount": 3126.65078208,
          "principal_amortization_amount": 2077.49921792,
          "tax_amount": 62.17955159,
          "total_amount": 5204.15,
          "workdays": 21
        },
        {
          "additional_costs": [],
          "business_due_date": "2027-03-10",
          "calendar_days": 28,
          "due_date": "2027-03-10",
          "due_interest": 0,
          "due_principal": 4767.01078208,
          "fine_amount": null,
          "has_interest": true,
          "installment_number": 4,
          "post_fixed_amount": 0,
          "pre_fixed_amount": 437.13921792,
          "principal_amortization_amount": 4767.01078208,
          "tax_amount": 142.67663271,
          "total_amount": 5204.15,
          "workdays": 20
        }
      ],
      "interest_subsidy_amount": 0,
      "issue_amount": 6844.51,
      "net_external_contract_fee_amount": 0,
      "prefixed_interest_rate": {
        "annual_rate": 2.1384283767,
        "daily_rate": 0.0031383999,
        "interest_base": {
          "translation_path": "co.InterestBase.calendar_days_365",
          "enumerator": "calendar_days_365",
          "year_days": 365
        },
        "monthly_rate": 0.1,
        "created_at": "2026-02-02T20:00:12"
      },
      "refinanced_credit_operations": [],
      "share_quantity": 7,
      "tax_exempt_amount": 0,
      "total_iof": 250.51
    }
  ],
  "installments": [
    {
      "additional_costs": [],
      "business_due_date": "2026-12-10",
      "calendar_days": 311,
      "due_date": "2026-12-10",
      "due_interest": 0,
      "due_principal": 6844.51,
      "fine_amount": null,
      "has_interest": true,
      "installment_number": 1,
      "post_fixed_amount": 0,
      "pre_fixed_amount": 5204.15,
      "principal_amortization_amount": 0,
      "tax_amount": 0,
      "total_amount": 5204.15,
      "workdays": 213,
      "accrual_reference_date": null,
      "advanced_paid_amount": 0,
      "bank_slip_key": null,
      "digitable_line": null,
      "installment_key": "2db9f3af-a8e2-4398-b0d8-5e26f9f8f710",
      "installment_status": {
        "enumerator": "created",
        "translation_path": "co.InstallmentStatus.created"
      },
      "installment_type": {
        "enumerator": "principal",
        "translation_path": "co.InstallmentType.principal"
      },
      "payment_type": {
        "translation_path": "co.PaymentType.unmonitored",
        "enumerator": "unmonitored"
      },
      "original_due_principal": 6844.51,
      "original_pre_fixed_amount": 5204.15,
      "original_principal_amortization_amount": 0,
      "paid_amount": 0,
      "paid_at": null,
      "original_total_amount": 5204.15,
      "qr_code_key": null,
      "qr_code_url": null,
      "renegotiation_proposal_key": null,
      "total_accrual_amount": null,
      "total_paid_amount": 0,
      "updated_at": null,
      "cetip_settlements": [],
      "events": [],
      "installment_history": [],
      "installment_payment": []
    },
    {
      "additional_costs": [],
      "business_due_date": "2027-01-11",
      "calendar_days": 31,
      "due_date": "2027-01-10",
      "due_interest": 6088.45962499,
      "due_principal": 6844.51,
      "fine_amount": null,
      "has_interest": true,
      "installment_number": 2,
      "post_fixed_amount": 0,
      "pre_fixed_amount": 5204.15,
      "principal_amortization_amount": 0,
      "tax_amount": 0,
      "total_amount": 5204.15,
      "workdays": 19,
      "accrual_reference_date": null,
      "advanced_paid_amount": 0,
      "bank_slip_key": null,
      "digitable_line": null,
      "installment_key": "89d1e77c-c9df-4716-a535-78f1d329ee49",
      "installment_status": {
        "enumerator": "created",
        "translation_path": "co.InstallmentStatus.created"
      },
      "installment_type": {
        "enumerator": "principal",
        "translation_path": "co.InstallmentType.principal"
      },
      "payment_type": {
        "translation_path": "co.PaymentType.unmonitored",
        "enumerator": "unmonitored"
      },
      "original_due_principal": 6844.51,
      "original_pre_fixed_amount": 5204.15,
      "original_principal_amortization_amount": 0,
      "paid_amount": 0,
      "paid_at": null,
      "original_total_amount": 5204.15,
      "qr_code_key": null,
      "qr_code_url": null,
      "renegotiation_proposal_key": null,
      "total_accrual_amount": null,
      "total_paid_amount": 0,
      "updated_at": null,
      "cetip_settlements": [],
      "events": [],
      "installment_history": [],
      "installment_payment": []
    },
    {
      "additional_costs": [],
      "business_due_date": "2027-02-10",
      "calendar_days": 31,
      "due_date": "2027-02-10",
      "due_interest": 2203.63074342,
      "due_principal": 6844.51,
      "fine_amount": null,
      "has_interest": true,
      "installment_number": 3,
      "post_fixed_amount": 0,
      "pre_fixed_amount": 3126.65078208,
      "principal_amortization_amount": 2077.49921792,
      "tax_amount": 62.17955159,
      "total_amount": 5204.15,
      "workdays": 21,
      "accrual_reference_date": null,
      "advanced_paid_amount": 0,
      "bank_slip_key": null,
      "digitable_line": null,
      "installment_key": "60c36ccb-ee86-4ab2-a8d6-bb84d2a35ad3",
      "installment_status": {
        "enumerator": "created",
        "translation_path": "co.InstallmentStatus.created"
      },
      "installment_type": {
        "enumerator": "principal",
        "translation_path": "co.InstallmentType.principal"
      },
      "payment_type": {
        "translation_path": "co.PaymentType.unmonitored",
        "enumerator": "unmonitored"
      },
      "original_due_principal": 6844.51,
      "original_pre_fixed_amount": 3126.65078208,
      "original_principal_amortization_amount": 2077.49921792,
      "paid_amount": 0,
      "paid_at": null,
      "original_total_amount": 5204.15,
      "qr_code_key": null,
      "qr_code_url": null,
      "renegotiation_proposal_key": null,
      "total_accrual_amount": null,
      "total_paid_amount": 0,
      "updated_at": null,
      "cetip_settlements": [],
      "events": [],
      "installment_history": [],
      "installment_payment": []
    },
    {
      "additional_costs": [],
      "business_due_date": "2027-03-10",
      "calendar_days": 28,
      "due_date": "2027-03-10",
      "due_interest": 0,
      "due_principal": 4767.01078208,
      "fine_amount": null,
      "has_interest": true,
      "installment_number": 4,
      "post_fixed_amount": 0,
      "pre_fixed_amount": 437.13921792,
      "principal_amortization_amount": 4767.01078208,
      "tax_amount": 142.67663271,
      "total_amount": 5204.15,
      "workdays": 20,
      "accrual_reference_date": null,
      "advanced_paid_amount": 0,
      "bank_slip_key": null,
      "digitable_line": null,
      "installment_key": "8c4c214c-b360-446b-8cf7-8b2cde065491",
      "installment_status": {
        "enumerator": "created",
        "translation_path": "co.InstallmentStatus.created"
      },
      "installment_type": {
        "enumerator": "principal",
        "translation_path": "co.InstallmentType.principal"
      },
      "payment_type": {
        "translation_path": "co.PaymentType.unmonitored",
        "enumerator": "unmonitored"
      },
      "original_due_principal": 4767.01078208,
      "original_pre_fixed_amount": 437.13921792,
      "original_principal_amortization_amount": 4767.01078208,
      "paid_amount": 0,
      "paid_at": null,
      "original_total_amount": 5204.15,
      "qr_code_key": null,
      "qr_code_url": null,
      "renegotiation_proposal_key": null,
      "total_accrual_amount": null,
      "total_paid_amount": 0,
      "updated_at": null,
      "cetip_settlements": [],
      "events": [],
      "installment_history": [],
      "installment_payment": []
    }
  ],
  "collaterals": [],
  "events": [],
  "cancel_reason": {},
  "after_disbursement_actions": [],
  "cetip_assignments": [],
  "cetip_settlements": [],
  "post_fixed_interest_base": {
    "translation_path": "co.InterestBase.workdays",
    "enumerator": "workdays",
    "year_days": 252
  },
  "disbursement_callback": null,
  "attached_document_list": [
    {
      "document_key": "7546e337-4bcf-4e36-b4c5-fb67b462ed1c",
      "document_type": {
        "enumerator": "ccb_pre_price_days",
        "translation_path": "co.DocumentType.ccb_pre_price_days"
      },
      "document_url": {URL},
      "related_party_key": null,
      "signature_data": null,
      "signature_required": true,
      "signature_url": null,
      "signed": false
    }
  ],
  "related_party_list": [
    {
      "address": {
        "street": "Rua Teste",
        "neighborhood": "",
        "number": "1",
        "postal_code": "99999999",
        "city": "São Paulo",
        "state": "SP",
        "complement": ""
      },
      "attached_document_list": [],
      "birth_date": "1999-01-01",
      "birth_place": null,
      "cnae_code": null,
      "company_document_number": null,
      "created_at": "2026-02-02T20:00:12",
      "document_identification_date": null,
      "document_identification_number": null,
      "document_identification_type": null,
      "email": "alan.turing@email.com",
      "foundation_date": null,
      "gender": null,
      "income": null,
      "individual_document_number": "12345678909",
      "is_pep": false,
      "marital_status": null,
      "mother_name": "Mother Name",
      "name": "Alan Mathison Turing",
      "nationality": null,
      "person_type": "natural",
      "phone": {
        "phone_key": "7d03058a-b55f-425b-a71a-d729216c6abe",
        "country_code": "55",
        "area_code": "11",
        "number": "999999999",
        "phone_type": null
      },
      "profession": null,
      "property_system": null,
      "related_party_key": "2d5ebd7f-b094-45c1-a41e-953b474ae6ce",
      "revenue": null,
      "role_type": {
        "enumerator": "issuer",
        "translation_path": "co.RoleType.issuer"
      },
      "simples_nacional_participant": null,
      "spouse_document_number": null,
      "trading_name": null
    }
  ],
  "refinanced_credit_operations": []
}

```

STATUS 400

**Request Body**

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

---

# Cancelar dívida antes de desembolsar

URL: /documentation/emissao_de_divida/cancelamento/cancelar_divida_antes_de_desembolsar

## Request

ENDPOINT /debt/ DEBT-KEY /cancel
MÉTODO PATCH

## Response

STATUS 200

Response Body

```json
{
  "data": [
    {
      "borrower": {
        "document_number": "68394265057",
        "name": "Xuxa Meneguel"
      },
      "contract_fee_amount": 5.56,
      "installments": [
        {
          "bank_slip_key": null,
          "calendar_days": 57,
          "due_date": "2020-09-30",
          "due_principal": -0.00217819,
          "fine_amount": null,
          "has_interest": true,
          "installment_key": "28eb5907-ed25-4a86-bb9d-b6dc944f13df",
          "installment_number": 1,
          "installment_status": "opened",
          "installment_type": "principal",
          "paid_amount": 0,
          "post_fixed_amount": 0,
          "pre_fixed_amount": 268.75782181,
          "principal_amortization_amount": 1111.9,
          "tax_amount": 0,
          "total_amount": 1380.66,
          "workdays": 40
        }
      ],
      "operation_key": "7986dcc7-4331-478f-af47-adfbdf7f4a36",
      "status": "opened"
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "rows_per_page": 100,
    "total_pages": 1,
    "total_rows": 55
  }
}

```

STATUS 400

Response Body

```json
{
  "title": "Bad Request",
  "description": "Operation cc5075bb-cfc3-4cd3-a9b5-527978de673c actual status does not allow cancel operation. Actual status is canceled",
  "translation": "Status da operação cc5075bb-cfc3-4cd3-a9b5-527978de673c não permite cancelamento.Status atual: canceled",
  "code": "LEG000073"
}
```

### Path Params

| Campo | Tipo | Descrição |
|---|---| ---|
| `debt_key` * | string | Chave da divida devolvida no momento da criação da operação de crédito. |

---

# Cancelar permanentemente

URL: /documentation/emissao_de_divida/cancelamento/cancelar_permanentemente

## Request

ENDPOINT /debt/ debt_key /cancel_permanently
MÉTODO POST

## Response

STATUS 200

Response Body

```json
{
  "data": {
    "additional_iof": 38000,
    "annual_cet": "253,2642%",
    "assignment_amount": 10000000,
    "base_iof": 69331,
    "borrower": {
      "document_number": "89940878025962",
      "name": "Parmalat"
    },
    "cet": "11,0900%",
    "collaterals": [],
    "contract": {
      "external_contract_key": "2f0b8b6e-0b60-47f0-b27f-e291c028549b",
      "number": "1907258737/P",
      "signature_information": [
        {
          "signature_url": "https://sign.qitech.com.br/s/hNrwjda",
          "signer_document_number": "94632180173",
          "signer_email": "pedro.alves@yopmail.com",
          "signer_external_key": "07a1c438-43a4-49a9-85a9-29667507453b",
          "signer_name": "Pedro Felipe Henrique Alves",
          "signer_role": "issuer"
        },
        {
          "signature_url": "https://sign.qitech.com.br/s/EaTajda",
          "signer_document_number": "34651104630",
          "signer_email": "patricia.tereza@yopmail.com",
          "signer_external_key": "61a1ea50-769a-410a-8ef8-09f0ce4611f6",
          "signer_name": "Patrícia Tereza Bernardes",
          "signer_role": "guarantor"
        }
      ],
      "urls": [
        "https://storage.googleapis.com/sandbox-doc-api/documents/abedfeab-dcf8-4e13-897b-da02c222cef4/SALGADINHO_SALETE_LTDA-PARMALAT-CCB-1907258737-20220512165254.pdf"
      ]
    },
    "contract_fee_amount": 50000,
    "contract_fees": [
      {
        "fee_amount": 50000,
        "fee_type": "tac"
      }
    ],
    "external_contract_fee_amount": 0,
    "external_contract_fees": [],
    "installments": [
      {
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": null,
        "business_due_date": "2019-08-26",
        "calendar_days": 32,
        "digitable_line": null,
        "due_date": "2019-08-26",
        "due_interest": null,
        "due_principal": 10000000,
        "fine_amount": null,
        "has_interest": true,
        "installment_key": "81e4a732-d300-4e39-b6d5-2d9ac8df429b",
        "installment_number": 1,
        "installment_payment": [],
        "installment_status": "created",
        "installment_type": "principal",
        "original_due_principal": 10000000,
        "original_pre_fixed_amount": 1125598.54,
        "original_principal_amortization_amount": 1000000,
        "original_total_amount": null,
        "paid_amount": 0,
        "paid_at": null,
        "payments": [],
        "post_fixed_amount": null,
        "pre_fixed_amount": 1125598.54,
        "principal_amortization_amount": 1000000,
        "tax_amount": 1312,
        "total_amount": null,
        "total_paid_amount": 0,
        "workdays": 22
      },
      {
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": null,
        "business_due_date": "2019-09-25",
        "calendar_days": 30,
        "digitable_line": null,
        "due_date": "2019-09-25",
        "due_interest": null,
        "due_principal": 9000000,
        "fine_amount": null,
        "has_interest": true,
        "installment_key": "bac4fe3e-9559-4380-9f4b-bdda3492738e",
        "installment_number": 2,
        "installment_payment": [],
        "installment_status": "created",
        "installment_type": "principal",
        "original_due_principal": 9000000,
        "original_pre_fixed_amount": 946509.06,
        "original_principal_amortization_amount": 1000000,
        "original_total_amount": null,
        "paid_amount": 0,
        "paid_at": null,
        "payments": [],
        "post_fixed_amount": null,
        "pre_fixed_amount": 946509.06,
        "principal_amortization_amount": 1000000,
        "tax_amount": 2542,
        "total_amount": null,
        "total_paid_amount": 0,
        "workdays": 22
      },
      {
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": null,
        "business_due_date": "2019-10-25",
        "calendar_days": 30,
        "digitable_line": null,
        "due_date": "2019-10-25",
        "due_interest": null,
        "due_principal": 8000000,
        "fine_amount": null,
        "has_interest": true,
        "installment_key": "aaaec4d7-94a0-418d-8a8e-ac7af6787aec",
        "installment_number": 3,
        "installment_payment": [],
        "installment_status": "created",
        "installment_type": "principal",
        "original_due_principal": 8000000,
        "original_pre_fixed_amount": 841341.39,
        "original_principal_amortization_amount": 1000000,
        "original_total_amount": null,
        "paid_amount": 0,
        "paid_at": null,
        "payments": [],
        "post_fixed_amount": null,
        "pre_fixed_amount": 841341.39,
        "principal_amortization_amount": 1000000,
        "tax_amount": 3772,
        "total_amount": null,
        "total_paid_amount": 0,
        "workdays": 22
      },
      {
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": null,
        "business_due_date": "2019-11-25",
        "calendar_days": 31,
        "digitable_line": null,
        "due_date": "2019-11-25",
        "due_interest": null,
        "due_principal": 7000000,
        "fine_amount": null,
        "has_interest": true,
        "installment_key": "bead5a38-c56e-4cfc-98f9-af6d71ec7d65",
        "installment_number": 4,
        "installment_payment": [],
        "installment_status": "created",
        "installment_type": "principal",
        "original_due_principal": 7000000,
        "original_pre_fixed_amount": 762003.23,
        "original_principal_amortization_amount": 1000000,
        "original_total_amount": null,
        "paid_amount": 0,
        "paid_at": null,
        "payments": [],
        "post_fixed_amount": null,
        "pre_fixed_amount": 762003.23,
        "principal_amortization_amount": 1000000,
        "tax_amount": 5043,
        "total_amount": null,
        "total_paid_amount": 0,
        "workdays": 20
      },
      {
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": null,
        "business_due_date": "2019-12-26",
        "calendar_days": 31,
        "digitable_line": null,
        "due_date": "2019-12-26",
        "due_interest": null,
        "due_principal": 6000000,
        "fine_amount": null,
        "has_interest": true,
        "installment_key": "350a89e3-58a7-4879-b7ff-5fa0391da39c",
        "installment_number": 5,
        "installment_payment": [],
        "installment_status": "created",
        "installment_type": "principal",
        "original_due_principal": 6000000,
        "original_pre_fixed_amount": 653145.63,
        "original_principal_amortization_amount": 1000000,
        "original_total_amount": null,
        "paid_amount": 0,
        "paid_at": null,
        "payments": [],
        "post_fixed_amount": null,
        "pre_fixed_amount": 653145.63,
        "principal_amortization_amount": 1000000,
        "tax_amount": 6314,
        "total_amount": null,
        "total_paid_amount": 0,
        "workdays": 22
      },
      {
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": null,
        "business_due_date": "2020-01-27",
        "calendar_days": 32,
        "digitable_line": null,
        "due_date": "2020-01-27",
        "due_interest": null,
        "due_principal": 5000000,
        "fine_amount": null,
        "has_interest": true,
        "installment_key": "bf935dc2-3151-4f66-91c6-35e446b57f2e",
        "installment_number": 6,
        "installment_payment": [],
        "installment_status": "created",
        "installment_type": "principal",
        "original_due_principal": 5000000,
        "original_pre_fixed_amount": 562799.27,
        "original_principal_amortization_amount": 1000000,
        "original_total_amount": null,
        "paid_amount": 0,
        "paid_at": null,
        "payments": [],
        "post_fixed_amount": null,
        "pre_fixed_amount": 562799.27,
        "principal_amortization_amount": 1000000,
        "tax_amount": 7626,
        "total_amount": null,
        "total_paid_amount": 0,
        "workdays": 20
      },
      {
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": null,
        "business_due_date": "2020-02-26",
        "calendar_days": 30,
        "digitable_line": null,
        "due_date": "2020-02-26",
        "due_interest": null,
        "due_principal": 4000000,
        "fine_amount": null,
        "has_interest": true,
        "installment_key": "76aad8ce-3ee1-464c-90db-d72a2729560e",
        "installment_number": 7,
        "installment_payment": [],
        "installment_status": "created",
        "installment_type": "principal",
        "original_due_principal": 4000000,
        "original_pre_fixed_amount": 420670.69,
        "original_principal_amortization_amount": 1000000,
        "original_total_amount": null,
        "paid_amount": 0,
        "paid_at": null,
        "payments": [],
        "post_fixed_amount": null,
        "pre_fixed_amount": 420670.69,
        "principal_amortization_amount": 1000000,
        "tax_amount": 8856,
        "total_amount": null,
        "total_paid_amount": 0,
        "workdays": 20
      },
      {
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": null,
        "business_due_date": "2020-03-25",
        "calendar_days": 28,
        "digitable_line": null,
        "due_date": "2020-03-25",
        "due_interest": null,
        "due_principal": 3000000,
        "fine_amount": null,
        "has_interest": true,
        "installment_key": "fc190222-5baf-4023-9e93-95b25774a37e",
        "installment_number": 8,
        "installment_payment": [],
        "installment_status": "created",
        "installment_type": "principal",
        "original_due_principal": 3000000,
        "original_pre_fixed_amount": 293473.82,
        "original_principal_amortization_amount": 1000000,
        "original_total_amount": null,
        "paid_amount": 0,
        "paid_at": null,
        "payments": [],
        "post_fixed_amount": null,
        "pre_fixed_amount": 293473.82,
        "principal_amortization_amount": 1000000,
        "tax_amount": 10004,
        "total_amount": null,
        "total_paid_amount": 0,
        "workdays": 20
      },
      {
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": null,
        "business_due_date": "2020-04-27",
        "calendar_days": 33,
        "digitable_line": null,
        "due_date": "2020-04-27",
        "due_interest": null,
        "due_principal": 2000000,
        "fine_amount": null,
        "has_interest": true,
        "installment_key": "7c2972a8-def7-4b76-b215-0ade0a5bca13",
        "installment_number": 9,
        "installment_payment": [],
        "installment_status": "created",
        "installment_type": "principal",
        "original_due_principal": 2000000,
        "original_pre_fixed_amount": 232548.93,
        "original_principal_amortization_amount": 1000000,
        "original_total_amount": null,
        "paid_amount": 0,
        "paid_at": null,
        "payments": [],
        "post_fixed_amount": null,
        "pre_fixed_amount": 232548.93,
        "principal_amortization_amount": 1000000,
        "tax_amount": 11357,
        "total_amount": null,
        "total_paid_amount": 0,
        "workdays": 21
      },
      {
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": null,
        "business_due_date": "2020-05-25",
        "calendar_days": 28,
        "digitable_line": null,
        "due_date": "2020-05-25",
        "due_interest": null,
        "due_principal": 1000000,
        "fine_amount": null,
        "has_interest": true,
        "installment_key": "d848c880-f489-4bc1-a9e4-101f8d664317",
        "installment_number": 10,
        "installment_payment": [],
        "installment_status": "created",
        "installment_type": "principal",
        "original_due_principal": 1000000,
        "original_pre_fixed_amount": 97824.6,
        "original_principal_amortization_amount": 1000000,
        "original_total_amount": null,
        "paid_amount": 0,
        "paid_at": null,
        "payments": [],
        "post_fixed_amount": null,
        "pre_fixed_amount": 97824.6,
        "principal_amortization_amount": 1000000,
        "tax_amount": 12505,
        "total_amount": null,
        "total_paid_amount": 0,
        "workdays": 19
      }
    ],
    "iof_charge_method": "financed",
    "issue_amount": 10000000,
    "net_external_contract_fee_amount": 0,
    "number_of_installments": 10,
    "post_fixed_interest_base": "workdays",
    "post_fixed_interest_rate": 1,
    "prefixed_interest_rate": {
      "annual_rate": 2.32,
      "created_at": null,
      "daily_rate": 0.0033388,
      "interest_base": "calendar_days",
      "monthly_rate": 0.10516767
    },
    "requester_identifier_key": "b7ddbcfb-3de0-49d8-8014-07972d8b27f2",
    "total_iof": 107331,
    "total_pre_fixed_amount": 5935915.16
  },
  "event_datetime": "2022-05-12 16:53:10",
  "key": "b7ddbcfb-3de0-49d8-8014-07972d8b27f2",
  "status": "waiting_signature",
  "webhook_type": "debt"
}
```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

---

# Emissão de pix qr code de devolução

URL: /documentation/emissao_de_divida/cancelamento/desistencia/cancelamento_de_divida_em_ate_sete_dias_apos_o_desembolso

## Request

ENDPOINT /debt/reversal
MÉTODO POST

Request Body

**Sem informar dias de expiração**

```json
{
    "contract_number": "0000049343/TW"
}
```
  
**Informando dias corridos de expiração**

```json
{
    "contract_number": "0000049343/TW",
    "days_to_expire":8
}
```

**Informando dias úteis de expiração**

```json
{
    "contract_number": "0000049343/TW",
    "workdays_to_expire":8
}
```

:::warning Expiração do pix_qr_code
A data de expiração do pix qr code é definida por uma quantidade de dias a partir da data de desembolso da dívida, caso não seja definido no payload, serão 14 dias úteis.
:::

## Response

STATUS 200

Response Body

```json
{
  "amount": "2026.93",
  "copy_paste_pix": "00020126930014br.gov.bcb.pix2571qrcode-h.dev.qitech.app/bacen/cobv/dece8d3e-32ce-439e-8204000053039865802BR5925Joao61080150400062070503***63046ECD",
  "expiration_date": "2022-09-28",
  "payer_document_number": "000000000008",
  "payer_name": "Teste",
  "reversal_key": "f98a1b7c-5e3c-4e6f-8887-c7fedfa0d5b5",
  "status": "waiting_payment"
}

```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

## Definições
| Campo             | Tipo   | Descrição                      |
|-------------------|--------|--------------------------------|
| `contract_number` * | string | Número do contrato de crédito.  |
| `days_to_expire` * | integer | Número de dias corridos de expiração do pix qr code desde o desembolso.  |
| `workdays_to_expire` * | integer | Número de dias úteis de expiração do pix qr code desde o desembolso.  |

---

# Consulta de pix qr code de devolução

URL: /documentation/emissao_de_divida/cancelamento/desistencia/consulta_de_pix_qr_code_de_devolucao

Retorna o pix qr code de devolução previamente gerado para uma operação de crédito em processo de desistência. Utilize este endpoint após criar o estorno em `/debt/reversal` para reobter os dados do qr code (por exemplo, para reexibi-los ao pagador).

## Request

ENDPOINT /credit_operation/{credit_operation_key}/pix_qrcode
MÉTODO GET

:::info
Esta requisição não possui corpo. A `credit_operation_key` deve ser informada como parâmetro de caminho na URL.
:::

## Response

STATUS 200

Response Body

```json
{
  "amount": "2026.93",
  "copy_paste_pix": "00020126930014br.gov.bcb.pix2571qrcode-h.dev.qitech.app/bacen/cobv/dece8d3e-32ce-439e-8204000053039865802BR5925Joao61080150400062070503***63046ECD",
  "debt_key": "a1f3d9c0-8b7e-4c9f-9d1a-1234567890ab",
  "expiration_date": "2022-09-28",
  "payer_document_number": "000000000008",
  "payer_name": "Teste",
  "qr_code_key": "7c3e5b22-4d8e-4a6b-9f11-abcdef123456",
  "reversal_key": "f98a1b7c-5e3c-4e6f-8887-c7fedfa0d5b5",
  "status": "waiting_payment"
}
```

STATUS 404

Response Body — Operação não encontrada

```json
{
  "data": "{\"title\": \"Not Found\", \"description\": \"Credit Operation not found\", \"translation\": \"Operação não encontrada\", \"extra_fields\": {}, \"code\": \"COP000027\"}"
}
```

Response Body — Estorno não encontrado

```json
{
  "data": "{\"title\": \"Not Found\", \"description\": \"Reversal not found.\", \"translation\": \"Estorno não encontrado.\", \"extra_fields\": {}, \"code\": \"COP000205\"}"
}
```

## Definições

### Parâmetros de caminho

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `credit_operation_key` * | string (uuid) | Chave única da operação de crédito para a qual o pix qr code de devolução foi gerado. |

### Campos da resposta

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `amount` | string | Valor do pix qr code de devolução, em reais. |
| `copy_paste_pix` | string | Código pix copia-e-cola gerado para o pagamento. |
| `debt_key` | string (uuid) | Chave da operação de crédito (dívida) associada ao estorno. |
| `expiration_date` | string (date) | Data de expiração do pix qr code, no formato `YYYY-MM-DD`. |
| `payer_document_number` | string | CPF/CNPJ do pagador. |
| `payer_name` | string | Nome do pagador. |
| `qr_code_key` | string (uuid) | Chave única do pix qr code emitido. |
| `reversal_key` | string (uuid) | Chave única do estorno associado ao pix qr code. |
| `status` | string | Status atual do pix qr code (por exemplo, `waiting_payment`). |

---

# Introdução

URL: /documentation/emissao_de_divida/cancelamento/desistencia/introducao

Tendo em vista atender a Código de Proteção e Defesa do Consumidor que permite ao tomador do crédito através de meios digitais realizar o cancelamento da dívida em até 7 dias, a QI Tech viabilizou uma funcionalidade específica para atender a estes casos.

## Funcionamento

Nos sistemas QI Tech existem duas formas de realizar o cancelamento de uma divida por desistencia em 7 dias:

### 1 - Através de devolução do valor recebido no desembolso

Caso seja identificada a devolução do valor total desembolsado de uma operação dentro dos 7 dias após a data de desembolso, seja através do estorno do pix ou uma nova transferência para a conta de origem do desembolso, será realizado o cancelamento automático da operação com o motivo: 'disbursed_amount_refunded'.

### 2 - Através da API de cancelamento

Através do endpoint [POST /debt/reversal](cancelamento_de_divida_em_ate_sete_dias_apos_o_desembolso) é possível realizar a geração de um QR code que, uma vez pago pelo tomador, realiza o cancelamnto da operação.

Em ambos os casos, uma vez que o dinheiro chega a QI Tech, a operação é cancelada e, caso a cessão do contrato já tenha ocorrido, o montante e estornado para o cessionário.

É possivel ultilizar este endpoint até 7 dias após o desembolso e a expiração do QR Code é parametrizada para 14 dias após a sua geração - Após este perioso não é mais possivel realizar o cancelamento do contrato.

## Requisitos

Para o funcionamento correto deste endpoint é necessário entrar em contato com o time de suporte QI Tech para liberação do endpoint e a configuração da conta do cessionário para estorno dos recursos.

---

# Introdução

URL: /documentation/emissao_de_divida/cancelamento/introducao

Existem dois tipos de cancelamento de dívidas que podem ser realizados através dos sistemas QI Tech.

## Cancelamento de dívida antes de desembolsar

A utilização do serviço de cancelamento de operações de crédito da QI Tech, para antes do desembolso, consiste apenas em uma única solicitação em nossa API.

## Cancelamento de dívida em até sete dias após o desembolso

A utilização do serviço de cancelamento de operações de crédito da QI Tech, em até sete dias após o desembolso, consiste apenas em uma única solicitação em nossa API.

Após a solicitação, será devolvido o Pix QR Code. Ao ser pago, a operação será cancelada e todos os estornos são executados automaticamente.

## Webhook

Quando o pagamento é confirmado, nosso serviço executa todas as reversões e envia um webhook para o cliente, conforme exemplo a seguir:

```json
{
   "reversal":{
      "date":"2022-09-06",
      "incoming_pix_transfer_key":null,
      "status":"pending_fund",
      "amount_to_send":2026.93,
      "third_party_account_key":"17e5120f-14f7-4802-8676-b63011154edf",
      "reversal_key":"eb0bbd1d-111d-4a61-bb65-c1f66a005ea2",
      "amount":2026.93,
      "is_total":true,
      "created_at":"2022-09-06T01:14:01",
      "is_operation_canceled":true,
      "transaction_key":null
   },
   "assigned_at":"None",
   "credit_operation_key":"2893b8bd-8f4e-4e45-9325-fc7003beb869",
   "assigned":true,
   "contract_number":"0000049333/TW"
}
```

:::info **Principais pontos a serem considerados nesta operação de cancelamento após sete dias:**

- A solicitação de estorno deve ser feita em até 8 dias úteis a partir da data de desembolso.

- O pagamento por QR Code deve ser feito em até 15 dias úteis a partir da data de desembolso.

- O status atual da operação de crédito não pode ser diferente de aberto.

- Nenhuma parcela pode ter sido paga.

- Quando todas as reversões são executadas com sucesso, uma rotina é executada uma vez por dia, coletando o valor adequado e enviando para o fundo.

:::

---

# Catálogo de Erros - Lending-as-a-Service

URL: /documentation/emissao_de_divida/catalogo_de_erros_laas

Abaixo estão listados todos os erros que podem ser retornados pelas APIs do Lending-as-a-Service.
Cada código de erro possui um identificador único que pode ser usado como referência.

## Erros Comuns

Erros compartilhados entre todas as APIs da plataforma.

| Código | HTTP | Mensagem |
|-|-|-|
| <a id="QIT000001"></a>`QIT000001` | 400 | **Schema Validator Error**<br/>Payload Inválido<br/><small>{description}</small> |
| <a id="QIT000002"></a>`QIT000002` | 403 | **Permission Validator Error**<br/>Request must be internal |
| <a id="QIT000003"></a>`QIT000003` | 403 | **Permission Validator Error**<br/>O agente não tem funções suficientes.<br/><small>The agent does not have enough roles.</small> |
| <a id="QIT000004"></a>`QIT000004` | 403 | **Permission Validator Error**<br/>Agente selecionado e person_key são diferentes<br/><small>Selected agent and person_key are different</small> |
| <a id="QIT000005"></a>`QIT000005` | 403 | **Permission Validator Error**<br/>O agente selecionado não é dono do item.<br/><small>Selected agent do not own this item.</small> |
| <a id="QIT000006"></a>`QIT000006` | 403 | **Permission Validator Error**<br/>Agente selecionado não é dono deste item e não tem funções suficientes.<br/><small>Selected agent do not own this item and has not enough roles.</small> |
| <a id="QIT000007"></a>`QIT000007` | - | **External API Error (Rest Connector)**<br/>{translation}<br/><small>{description}</small> |
| <a id="QIT000010"></a>`QIT000010` | 400 | **Search Params Error**<br/>Valor inválido para parâmetros página ou tamanho de página<br/><small>Invalid integer value for page or size querystring parameters</small> |
| <a id="QIT000400"></a>`QIT000400` | 400 | **Bad Request**<br/>O servidor não pode ou não processará a requisição devido a um erro do cliente (por exemplo, corpo da requisição inválido, tamanho muito grande, formatação da mensagem inválida ou rota inválida)<br/><small>The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, size too large, invalid request message framing, or deceptive request routing)</small> |
| <a id="QIT000404"></a>`QIT000404` | 404 | **Not Found**<br/>O resource solicitado não pôde ser encontrado, mas pode estar disponível no futuro. Requests subsequentes do cliente são permitidos<br/><small>The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible</small> |
| <a id="QIT000500"></a>`QIT000500` | 500 | **Internal Error**<br/>Um erro interno aconteceu e está sendo investigado.<br/><small>An internal error has occurred and its being investigated.</small> |
| <a id="QIT000753"></a>`QIT000753` | 500 | **Internal Error**<br/>Um erro interno aconteceu e está sendo investigado.<br/><small>An internal error has occurred and its being investigated.</small> |

## Erros Específicos

### COP — Operações de Crédito

468 erros

| Código | HTTP | Mensagem |
|-|-|-|
| <a id="COP000001"></a>`COP000001` | 400 | **Bad Request**<br/>Linha: {index}. Valor enviado {value} inválido<br/><small>Line: {index}. Invalid {value} value sent</small> |
| <a id="COP000002"></a>`COP000002` | 400 | **Bad Request**<br/>[{value}] Coluna faltando<br/><small>[{value}] Column missing</small> |
| <a id="COP000003"></a>`COP000003` | 400 | **Bad Request**<br/>Posições não encontradas<br/><small>No positions found</small> |
| <a id="COP000004"></a>`COP000004` | 400 | **Bad Request**<br/>Linha: {index}. Data enviada {value} inválida<br/><small>Line: {index}. Invalid {value} date sent</small> |
| <a id="COP000005"></a>`COP000005` | 400 | **Bad Request**<br/>Arquivo CSV não enviado<br/><small>CSV file not sent</small> |
| <a id="COP000006"></a>`COP000006` | 404 | **Not Found**<br/>Cessão não encontrado para assignment_key {assignment_key}<br/><small>Assignment not found for assignment_key {assignment_key}</small> |
| <a id="COP000007"></a>`COP000007` | 404 | **Not Found**<br/>Configuração do solicitante não encontrada para a requester_key {requester_key}<br/><small>No requester_configuration found for requester_key {requester_key}</small> |
| <a id="COP000008"></a>`COP000008` | 404 | **Not Found**<br/>Configuração ativa não encontrada para requester_key {requester_key} e cessionário com CNPJ {document_number}<br/><small>Active configuration not found for requester_key {requester_key} and purchaser with CNPJ {document_number}</small> |
| <a id="COP000009"></a>`COP000009` | 404 | **Not Found**<br/>Cessionário com CNPJ {purchaser_document_number} não encontrado<br/><small>Purchaser with CNPJ {purchaser_document_number} not found</small> |
| <a id="COP000010"></a>`COP000010` | 400 | **Bad Request**<br/>Cessionário não definido para a credit_operation {credit_operation_key}. Necessário para designar a emissao de dívida<br/><small>No purchaser defined for credit_operation {credit_operation_key}. Purchaser is required to assign a debt emission</small> |
| <a id="COP000011"></a>`COP000011` | 400 | **Bad Request**<br/>Cessionários diferentes. As cessões só podem atribuir a emissão de dívidas para um mesmo cessionário.<br/><small>Different purchasers defined. Assignment operations can only assign debt emissions grouping them by the same purchaser.</small> |
| <a id="COP000012"></a>`COP000012` | 422 | **Unprocessable Entity**<br/>O status da operação {credit_operation_key} é {co_status}. Não é possivel criar a cessão<br/><small>Credit Operation {credit_operation_key} status is {co_status}. Can't create assignment</small> |
| <a id="COP000013"></a>`COP000013` | 400 | **Bad Request**<br/>third_party_account_key diferente entre o solicitante {requester_key} e credit_operation com a chave {credit_operation_key}<br/><small>Different third_party_account_key between requester {requester_key} and credit_operation with key {credit_operation_key}</small> |
| <a id="COP000014"></a>`COP000014` | 400 | **Bad Request**<br/>Propriedade diferente da operação de crédito. As cessões só podem atribuir emissões de dívida com o mesmo proprietário.<br/><small>Different credit operation ownership. Assignment operations can only assign debt emissions with the same owner.</small> |
| <a id="COP000015"></a>`COP000015` | 400 | **Bad Request**<br/>Operação {credit_operation_key} já foi cessionada {assignment_key} com status {assignment_status_enumerator}.<br/><small>Credit Operation {credit_operation_key} already has an assignment {assignment_key} with status {assignment_status_enumerator}.</small> |
| <a id="COP000016"></a>`COP000016` | 400 | **Bad Request**<br/>Chave do documento não existe e solicitante não possui assignment_template_key registrada para o cessionário com CNPJ {document_number}. Um dos dois deve existir para criar uma cessão.<br/><small>Non existent document_key received, and requester doesn't have an assignment_template_key registered for purchaser with CNPJ {document_number}. One of them must exist to create an assignment.</small> |
| <a id="COP000017"></a>`COP000017` | 400 | **Bad Request**<br/>Documento {document_key} não encontrado<br/><small>Document not found for key {document_key}</small> |
| <a id="COP000018"></a>`COP000018` | 423 | **Locked**<br/>Operação encerrada. Sistema disponível de {OPENING_TIME} até {CLOSING_TIME}<br/><small>Operation window closed. System available from {OPENING_TIME} to {CLOSING_TIME}</small> |
| <a id="COP000019"></a>`COP000019` | 423 | **Locked**<br/>Operação encerrada. Sistema disponível somente em dias úteis.<br/><small>Operation window closed. System available only during work days.</small> |
| <a id="COP000020"></a>`COP000020` | 404 | **Not Found**<br/>requester_configuration correspondente não encontrada no banco de dados. Lembre-se de que existe um fallback para issuer_document_number nulo<br/><small>No correspondent requester configuration exists in the database. Keep in mind that there is a fallback to null issuer_document_number</small> |
| <a id="COP000021"></a>`COP000021` | 422 | **Invalid Data**<br/>A operação possui dados inválidos: impossível calcular valores para o desembolso esperado<br/><small>Credit operation has invalid data: impossible to calculate values for expected disbursed amount</small> |
| <a id="COP000022"></a>`COP000022` | 404 | **Not Found**<br/>Emissor não encontrado<br/><small>Issuer not found</small> |
| <a id="COP000023"></a>`COP000023` | 400 | **Bad Request**<br/>Chave do documento ou do lote de documentos não pode ser nula<br/><small>Document Key or document batch key must not be Null</small> |
| <a id="COP000024"></a>`COP000024` | 400 | **Bad Request**<br/>Status não pode ser nulo<br/><small>Status must not be Null</small> |
| <a id="COP000025"></a>`COP000025` | 400 | **Bad Request**<br/>Chave da TED de saída (outgoing_ted_key) não pode ser nula<br/><small>Outgoing TED Key must not be Null</small> |
| <a id="COP000026"></a>`COP000026` | 400 | **Bad Request**<br/>Chave da CO (credit_operation_key) não pode ser nula<br/><small>CO Key (credit_operation_key) must not be Null</small> |
| <a id="COP000027"></a>`COP000027` | 404 | **Not Found**<br/>Operação não encontrada<br/><small>Credit Operation not found</small> |
| <a id="COP000028"></a>`COP000028` | 400 | **Bad Request**<br/>{translated_errors}<br/><small>{errors}</small> |
| <a id="COP000029"></a>`COP000029` | 400 | **Bad Request**<br/>O parâmetro key ou bank_slip_key está faltando.<br/><small>Parameter key or bank_slip_key is missing.</small> |
| <a id="COP000030"></a>`COP000030` | 422 | **Unprocessable Entity**<br/>Não há uma conta de reembolso na configuração do solicitante para enviar o valor do reembolso (payload external_contract_fee_amount é maior que 0)<br/><small>There is no rebate account in the requester configuration to send the rebate amount (payload external_contract_fee_amount is greater than 0)</small> |
| <a id="COP000031"></a>`COP000031` | 422 | **Unprocessable Entity**<br/>O tipo de taxa do contrato externo não foi especificado na configuração do solicitante (payload external_contract_fee_amount é maior que 0)<br/><small>External contract fee type was not specified in the requester configuration (payload external_contract_fee_amount is greater than 0)</small> |
| <a id="COP000032"></a>`COP000032` | 422 | **Unprocessable Entity**<br/>A configuração do solicitante possui dados de descontos incompletos. Para usar a configuração do solicitante, todos os dados de descontos devem ser preenchidos ou todos devem ser anulados<br/><small>Requester configuration has incomplete rebate data. In order to use requester configuration, either all rebate data must be filled or all of it has to be nullified</small> |
| <a id="COP000034"></a>`COP000034` | 400 | **Bad Request**<br/>Configuração do cessionário ausente<br/><small>Missing purchaser configuration</small> |
| <a id="COP000035"></a>`COP000035` | 400 | **Bad Request**<br/>Solicitante não tem permissão para criar uma operação sem o cessionário<br/><small>Requester not allowed to create a credit operation without purchaser</small> |
| <a id="COP000036"></a>`COP000036` | 422 | **Unprocessable Entity**<br/>Porcentagem inválida: o valor total é diferente de 100%<br/><small>Invalid percentage receivable: total percentage is different than 100%</small> |
| <a id="COP000037"></a>`COP000037` | 400 | **Bad Request**<br/>conta de origem de desembolso não cadastrada<br/><small>Missing third_party_account</small> |
| <a id="COP000038"></a>`COP000038` | 422 | **Unprocessable Entity**<br/>O valor da taxa da configuração do solicitante é uma porcentagem superior a 100%. Verifique os dados da configuração do solicitante.<br/><small>Requester configuration fee amount is a percentage greater than 100%. Please check requester configuration data.</small> |
| <a id="COP000039"></a>`COP000039` | 400 | **Bad Request**<br/>Operação com código da instituição financeira {if_code} não encontrada<br/><small>Credit Operation with IF Code = {if_code} not found</small> |
| <a id="COP000040"></a>`COP000040` | 400 | **Bad Request**<br/>Operação com código da instituição financeira {if_code} ainda não tem uma parcela a pagar<br/><small>Credit Operation with IF Code = {if_code} does not have a payable installment yet</small> |
| <a id="COP000041"></a>`COP000041` | 400 | **Bad Request**<br/>CSV complementar para operação de crédito com código IF = {if_code} já lido<br/><small>CSV Complement for Credit Operation with IF Code = {if_code} already read</small> |
| <a id="COP000042"></a>`COP000042` | 400 | **Bad Request**<br/>Mensagem de controle da Cetip LTR = {control_number_ltr} já foi processada<br/><small>Cetip Control Message LTR = {control_number_ltr} already processed</small> |
| <a id="COP000043"></a>`COP000043` | 400 | **Bad Request**<br/>Confirmação Cetip LTR = {control_number_if} Mensagem solicitada não encontrada<br/><small>Cetip LTR Confirmation = {control_number_if} Request Message not found</small> |
| <a id="COP000044"></a>`COP000044` | 400 | **Bad Request**<br/>Confirmação LTR da mensagem de controle Cetip = {control_number_ltr} já processada<br/><small>Cetip Control Message LTR Confirmation = {control_number_ltr} already processed</small> |
| <a id="COP000045"></a>`COP000045` | 400 | **Bad Request**<br/>Nenhuma liquidação encontrada está pendente confirmação para a Confirmação LTR {control_number_ltr}<br/><small>No CETIP Settlement found to confirm for the LTR Confirmation {control_number_ltr}</small> |
| <a id="COP000046"></a>`COP000046` | 400 | **Bad Request**<br/>Valor esperado {expected_amount} é diferente da mensagem da cetip {amount}<br/><small>Expected value {expected_amount} is different from cetip message {amount}</small> |
| <a id="COP000048"></a>`COP000048` | 409 | **Conflict**<br/>O número da parcela {installment_number} da operação com Código IF = {if_code} ainda não está pronto para o pagamento<br/><small>Installment number {installment_number} from operation with IF Code = {if_code} is not ready for payment yet</small> |
| <a id="COP000049"></a>`COP000049` | 400 | **Bad Request**<br/>O número de parcelas ou 'número de parcelas - período de carência  não pode ser zero.<br/><small>Number of installments  or 'number of installments - principal grace period' cannot be zero.</small> |
| <a id="COP000050"></a>`COP000050` | 400 | **Bad Request**<br/>Não foi possível calcular cet da operação<br/><small>Credit Operation Information can not calculate cet</small> |
| <a id="COP000051"></a>`COP000051` | 400 | **Bad Request**<br/>Para executar o método de pagamento de boleto bancário sem uma creditor_bank_account, o emissor deve ser uma pessoa válida na integração.<br/><small>To execute bankslip payment method without a creditor_bank_account, issuer must be a valid person on onboarding.</small> |
| <a id="COP000052"></a>`COP000052` | 400 | **Bad Request**<br/>Para executar o método de pagamento de boleto bancário, o emissor deve ser uma pessoa válida na integração.<br/><small>To execute bankslip payment method, issuer must be a valid person on onboarding.</small> |
| <a id="COP000053"></a>`COP000053` | 400 | **Bad Request**<br/>O método de pagamento integrado precisa de no mínimo uma conta de desembolso<br/><small>Integrated Payment Method needs minimum of one disbursement account</small> |
| <a id="COP000054"></a>`COP000054` | 400 | **Bad Request**<br/>Conta de desembolso interna com número {account_number}-{account_branch} inválida<br/><small>Internal disbursement account of number {account_number}-{account_branch} is invalid.</small> |
| <a id="COP000055"></a>`COP000055` | 400 | **Bad Request**<br/>O Método de pagamento integrado precisa da chave da conta bancária de liquidação ou de uma conta de desembolso interna para efetuar o pagamento parcelado<br/><small>Integrated Payment Method needs settlement bank account key or a internal disbursement account to perform installment payment.</small> |
| <a id="COP000056"></a>`COP000056` | 400 | **Bad Request**<br/>Chave de conta bancária de liquidação inválida.<br/><small>Invalid settlement bank account key.</small> |
| <a id="COP000057"></a>`COP000057` | 400 | **Bad Request**<br/>A especificação de recebimento das contas de desembolsos não deve ser de natureza mista (valores absolutos e percentuais).<br/><small>Disbursement accounts' receivable specification must not be of mixed nature (absolute and percentage values).</small> |
| <a id="COP000058"></a>`COP000058` | 422 | **Unprocessable Entity**<br/>Saldo inválido na conta de origem<br/><small>Resource account has invalid balance data</small> |
| <a id="COP000059"></a>`COP000059` | 422 | **Unprocessable Entity**<br/>O total de despesas é maior que o valor emitido para esta operação<br/><small>Total expenses are greater than issued amount for this operation</small> |
| <a id="COP000060"></a>`COP000060` | 422 | **Unprocessable Entity**<br/>O valor da emissão é maior que o saldo da conta de origem. A operação foi interrompida<br/><small>Issue amount is greater than resource account balance. Operation has been aborted</small> |
| <a id="COP000061"></a>`COP000061` | 422 | **Unprocessable Entity**<br/>O valor da emissão é maior que o saldo da conta de origem. A operação foi interrompida<br/><small>Rebate taxes are greater than rebate amount for this operation</small> |
| <a id="COP000062"></a>`COP000062` | 422 | **Unprocessable Entity**<br/>Esta operação não possui uma conta de reembolso para transferir o valor do reembolso<br/><small>This credit operation has no rebate account to transfer the rebate amount</small> |
| <a id="COP000063"></a>`COP000063` | 400 | **Bad Request**<br/>Não é possível garantir o valor desembolsado para contas que não são amount_receivable<br/><small>Cannot ensure disbursed amount for non amount_receivable accounts</small> |
| <a id="COP000064"></a>`COP000064` | 400 | **Validation Error**<br/>{parse_error} |
| <a id="COP000065"></a>`COP000065` | 400 | **Validation Error**<br/>{parse_error} |
| <a id="COP000066"></a>`COP000066` | 400 | **Bad Request**<br/>GET request faltando parâmetros<br/><small>Missing parameters for GET request</small> |
| <a id="COP000067"></a>`COP000067` | 404 | **Not Found**<br/>Operação não encontrada para os parâmetros fornecidos.<br/><small>Credit Operation was not found for the given parameters.</small> |
| <a id="COP000068"></a>`COP000068` | 400 | **Bad Request**<br/>Forneça apenas um dentre {issue_amount, disbursed_issue_amount, final_disbursement_amount}. Se um for válido, os outros devem ser nulos<br/><small>Please provide only one of {issue_amount, disbursed_issue_amount, final_disbursement_amount}. If one is valid, the other must be null</small> |
| <a id="COP000069"></a>`COP000069` | 404 | **Not Found**<br/>Operação com número de contrato {contract_number} não encontrada<br/><small>Credit Operation with contract number {contract_number} not found</small> |
| <a id="COP000070"></a>`COP000070` | 400 | **Bad Request**<br/>Números de controle de atribuições da cetip duplicados<br/><small>Duplicated cetip assignments control numbers</small> |
| <a id="COP000071"></a>`COP000071` | 400 | **Bad Request**<br/>O valor total esperado {total_expected_amount} é diferente do valor da operação de crédito {issue_amount}<br/><small>Total expected amount {total_expected_amount} is different from Credit Operation amount {issue_amount}</small> |
| <a id="COP000073"></a>`COP000073` | 400 | **Bad Request**<br/>Nenhuma configuração ativa encontrada para o solicitante {requester_key} e cessionário with CNPJ {purchaser_document_number}.<br/><small>No active configuration found for requester {requester_key} and purchaser with CNPJ {purchaser_document_number}.</small> |
| <a id="COP000074"></a>`COP000074` | 400 | **Bad Request**<br/>A operação de crédito com chaves {endorsed_co_key_list} já foi endossada<br/><small>Credit Operation with keys {endorsed_co_key_list} is already endorsed</small> |
| <a id="COP000075"></a>`COP000075` | 404 | **Not Found**<br/>Operação de crédito não encontrada para a seguinte chave {key}<br/><small>Credit Operation not found for the given key for {key}</small> |
| <a id="COP000076"></a>`COP000076` | 400 | **Bad Request**<br/>A operação de crédito com chaves {key} não possui documento válido<br/><small>Credit Operation with keys {key} does not have valid document</small> |
| <a id="COP000077"></a>`COP000077` | 400 | **Bad Request**<br/>A operação de crédito com chaves {key} estão esperando assinatura<br/><small>Credit Operation with keys {key} are waiting signature</small> |
| <a id="COP000078"></a>`COP000078` | 400 | **Bad Request**<br/>A operação de crédito com chaves {key} foram canceladas<br/><small>Credit Operation with keys {key} are cancelled</small> |
| <a id="COP000079"></a>`COP000079` | 400 | **Bad Request**<br/>Parâmetro obrigatório ausente: document_number<br/><small>Missing mandatory parameter: document_number</small> |
| <a id="COP000080"></a>`COP000080` | 404 | **Not Found**<br/>Cessionário com número de documento {document_number} não encontrado.<br/><small>No purchaser found with document number {document_number}.</small> |
| <a id="COP000081"></a>`COP000081` | 400 | **Bad Request**<br/>Cessionário com número de documento {document_number} já registrado. Use PUT /purchaser<br/><small>Purchaser with document number {document_number} already registered. Use PUT /purchaser</small> |
| <a id="COP000082"></a>`COP000082` | 400 | **Bad Request**<br/>Cessionário com número de documento {document_number} não registrado. Use PUT /purchaser<br/><small>Purchaser with document number {document_number} não registered. Use PUT /purchaser</small> |
| <a id="COP000083"></a>`COP000083` | 400 | **Bad Request**<br/>Parâmetro obrigatório ausente: requester_key<br/><small>Missing mandatory parameter: requester_key</small> |
| <a id="COP000084"></a>`COP000084` | 409 | **Conflict**<br/>Já existe uma configuração para o requester_key e issuer_document_number<br/><small>There already exists a configuration for the informed requester_key and issuer_document_number</small> |
| <a id="COP000085"></a>`COP000085` | 404 | **Not Found**<br/>Configuração do solicitante não encontrada para os parâmetros fornecidos<br/><small>Requester configuration not found for the given parameters</small> |
| <a id="COP000086"></a>`COP000086` | 422 | **Unprocessable Entity**<br/>Taxa de contrato inválida: o valor informado é superior a 100%<br/><small>Invalid contract fee data: amount informed is greater than 100%</small> |
| <a id="COP000087"></a>`COP000087` | 422 | **Unprocessable Entity**<br/>Taxa de contrato externa inválida: o valor informado é superior a 100%<br/><small>Invalid external contract fee data: amount informed is greater than 100%</small> |
| <a id="COP000088"></a>`COP000088` | 400 | **Bad Request**<br/>O status da parcela não permite esta operação.<br/><small>Installment actual status does not allow this operation.</small> |
| <a id="COP000089"></a>`COP000089` | 400 | **Bad Request**<br/>A operação de crédito {credit_operation_key} não tem data de desembolso<br/><small>Credit Operation {credit_operation_key} has no disbursement_date</small> |
| <a id="COP000090"></a>`COP000090` | 400 | **Bad Request**<br/>{message_br}<br/><small>{message_en}</small> |
| <a id="COP000091"></a>`COP000091` | 400 | **Bad Request**<br/>Nenhuma opção de desembolso encontrada para operação de crédito<br/><small>No disbursement option found for credit operation</small> |
| <a id="COP000092"></a>`COP000092` | 400 | **Bad Request**<br/>A data de desembolso da operação de crédito já foi definida<br/><small>Credit Operation's disbursement date has already been set</small> |
| <a id="COP000093"></a>`COP000093` | 400 | **Bad Request**<br/>Nenhuma opção de desembolso calculada para disbursement_date {disbursement_date}<br/><small>No disbursement option calculated to disbursement_date {disbursement_date}</small> |
| <a id="COP000094"></a>`COP000094` | 400 | **Bad Request**<br/>Mais de uma opção de desembolso calculada para {disbursement_date}<br/><small>More than one disbursement option calculated to {disbursement_date}</small> |
| <a id="COP000095"></a>`COP000095` | 400 | **Bad Request**<br/>Data de vencimento da primeira parcela inválida.<br/><small>First due date invalid.</small> |
| <a id="COP000096"></a>`COP000096` | 400 | **Bad Request**<br/>NÃo foi possãvel encontrar a última parcela a ser liquidada.<br/><small>Could not find last installment to early pay with provided key.</small> |
| <a id="COP000097"></a>`COP000097` | 400 | **Bad Request**<br/>NÃo foi possãvel encontrar a parcelas para serem liquidadas.<br/><small>No installment found to early pay.</small> |
| <a id="COP000098"></a>`COP000098` | 400 | **Bad Request**<br/>Propriedade diferente da operação de crédito. Os endossos só podem endossar emissões de dívida com o mesmo proprietário.<br/><small>Different credit operation ownership. Endorsement operations can only endorse debt emissions with the same owner.</small> |
| <a id="COP000099"></a>`COP000099` | 400 | **Bad Request**<br/>Propriedade diferente da operação de crédito. As cessões só podem ceder emissões de dívida com o mesmo proprietário.<br/><small>Different credit operation ownership. Assignment operations can only assign debt emissions with the same owner.</small> |
| <a id="COP000100"></a>`COP000100` | 400 | **Bad Request**<br/>A operação de crédito não pode ser liquidada antecipadamente porque tem parcelas atrasadas.<br/><small>Credit operation cannot be early paid if it has delayed installments.</small> |
| <a id="COP000101"></a>`COP000101` | 400 | **Bad Request**<br/>A operação de crédito não pode ser liquidada antecipadamente porque tem parcelas que foram pagas parcialmente ou estão aguardando pagamento.<br/><small>Credit operation cannot be early paid if it has installments that are waiting payment.</small> |
| <a id="COP000102"></a>`COP000102` | 400 | **Bad Request**<br/>A operação de crédito não pode ser liquidada antecipadamente porque ainda não foi desembolsada.<br/><small>Credit operation cannot be early paid if it is not opened yet.</small> |
| <a id="COP000103"></a>`COP000103` | 400 | **Bad Request**<br/>Email informado por assinante {related_party_name} é invalido: {email}.<br/><small>Related party {related_party_name} provided an invalid email {email}.</small> |
| <a id="COP000104"></a>`COP000104` | 400 | **Bad Request**<br/>Não foi informado celular para o assinante: {related_party_name}.<br/><small>Related party {related_party_name} has no phone provided.</small> |
| <a id="COP000105"></a>`COP000105` | 400 | **Bad Request**<br/>Telefone não encontrado<br/><small>Phone not found</small> |
| <a id="COP000106"></a>`COP000106` | 400 | **Bad Request**<br/>É necessário ter apenas uma conta de desembolso, e esta conta precisa ser da QI SCD.<br/><small>There must be only one disbursement account, and it must be a QI SCD account</small> |
| <a id="COP000107"></a>`COP000107` | 400 | **Bad Request**<br/>Operação de crédito precisa estar desembolsada para executar ação.<br/><small>Credit operation must be opened to execute action</small> |
| <a id="COP000108"></a>`COP000108` | 400 | **Bad Request**<br/>Não foi possível pagar o boleto<br/><small>Could not pay bankslip</small> |
| <a id="COP000109"></a>`COP000109` | 400 | **Bad Request**<br/>Data da primeira parcela e Prazo até a primeira parcela foram recebidos. Envie apenas um deles.<br/><small>Both first_due_date and first_due_date_delay were provided. Only one must be provided.</small> |
| <a id="COP000110"></a>`COP000110` | 400 | **Bad Request**<br/>Tipo de pagamento bankslip pode ser usado somente para operações de crédito com juros prefixados<br/><small>Payment type bankslip can only be used for credit operations with prefixed interest types</small> |
| <a id="COP000111"></a>`COP000111` | 400 | **Bad Request**<br/>Por favor, envie apenas uma configuração de rebate por tipo de tarifa.<br/><small>Received duplicated fee type. Please provide only one fee configuration per fee type.</small> |
| <a id="COP000112"></a>`COP000112` | 400 | **Bad Request**<br/>O tipo de tarifa recebido {fee_type} não está pré-configurado.<br/><small>Received fee type {fee_type} not pre-configured.</small> |
| <a id="COP000113"></a>`COP000113` | 400 | **Bad Request**<br/>Não é possível aplicar rebate sem pré-configuração. Por favor contatar equipe de operações.<br/><small>Cannot apply external fee. Missing external fee configuration. Please contact the operations team.</small> |
| <a id="COP000114"></a>`COP000114` | 400 | **Bad Request**<br/>Por favor, especifique o tipo de rebate para sobrescrever.<br/><small>Please specify fee type to overwrite.</small> |
| <a id="COP000115"></a>`COP000115` | 400 | **Bad Request**<br/>Não é possível desembolsar a operação {credit_operation_key} porque a TED está fechada.<br/><small>Cannot disburse credit operation {credit_operation_key} due to TED closing time.</small> |
| <a id="COP000116"></a>`COP000116` | 400 | **Bad Request**<br/>Cessionário {document_number} já cadastrado para o requester_key {requester_key}. Use request PUT para atualizar<br/><small>Purchaser {document_number} already registered for requester_key {requester_key}. Use PUT request to update</small> |
| <a id="COP000117"></a>`COP000117` | 400 | **Bad Request**<br/>Tomador não corresponde ao pagador do boleto, ou não é um destino de desembolso cadastrado.<br/><small>Issuer is not bank-slip payer or is not disbursable destination.</small> |
| <a id="COP000118"></a>`COP000118` | 400 | **Bad Request**<br/>Entrada duplicada de dados para requester_identifier_key e requester_key.<br/><small>Duplicate entry for requester identifier key and requester key.</small> |
| <a id="COP000119"></a>`COP000119` | 400 | **Bad Request**<br/>Valor de emissão está faltando mais do que permitido: {amount} Desembolso líquido calculado: {disbursed_amount} Rebate: {external_contract_fee_sum} Deve ser menor que 20: {delta}<br/><small>Issue amount is missing more than permitted: {amount}. Disbursed amount: {disbursed_amount} External fee: {external_contract_fee_sum} Must be less than 20: {delta}</small> |
| <a id="COP000120"></a>`COP000120` | 400 | **Bad Request**<br/>Operação não está no estado aguardando assinatura<br/><small>Credit Operation is not waiting signature</small> |
| <a id="COP000121"></a>`COP000121` | 400 | **Bad Request**<br/>Reenvio de notificação está habilitado somente para clicksign e qi sign<br/><small>Resend notification is available only for clicksign and qi sign</small> |
| <a id="COP000122"></a>`COP000122` | 400 | **Bad Request**<br/>Assinante {signer} não faz parte da operação<br/><small>Signer {signer} is not part of the operation</small> |
| <a id="COP000123"></a>`COP000123` | 400 | **Bad Request**<br/>O total de amortização das parcelas não é igual ao valor de emissão.<br/><small>Total amortization from installment flow does not equal issue amount.</small> |
| <a id="COP000124"></a>`COP000124` | 400 | **Bad Request**<br/>A credit_operation_key recebida já está registrada para outra operação. Por favor, envie uma key não utilizada.<br/><small>Received credit_operation_key already registered for another operation. Please send a new one.</small> |
| <a id="COP000125"></a>`COP000125` | 400 | **Bad Request**<br/>Não pode haver opções de desembolso quando o fluxo de parcelas é pré-determinado.<br/><small>There cannot be disbursement options when installment flow is pre-defined.</small> |
| <a id="COP000126"></a>`COP000126` | 400 | **Bad Request**<br/>Valor total das ações pós desembolso ({after_disbursement_actions_total_amount}) é maior que o valor liberado calculado ({disbursed_amount}).<br/><small>Total after disbursement actions amount ({after_disbursement_actions_total_amount}) greater than evaluated disbursed amount ({disbursed_amount}).</small> |
| <a id="COP000127"></a>`COP000127` | 400 | **Bad Request**<br/>Não é possível criar ações pós-desembolso porque a data de vencimento {expiration_date} do boleto {digitable_line} está dentro do período de desembolso.<br/><small>Can't create after disbursement action because bankslip {digitable_line} expiration date {expiration_date} is within disbursement period.</small> |
| <a id="COP000128"></a>`COP000128` | 400 | **Bad Request**<br/>Não é possível criar ações pós-desembolso porque o valor do desembolso está indefinido.<br/><small>Can't create after disbursement action because disbursed amount is undefined.</small> |
| <a id="COP000129"></a>`COP000129` | 400 | **Bad Request**<br/>Tamanho da lista de datas de vencimento recebida não é compatível com o número de parcelas.<br/><small>Size of received due_dates array does not match number of installments</small> |
| <a id="COP000130"></a>`COP000130` | 400 | **Bad Request**<br/>Uma ou mais datas de vencimento recebidas ocorre antes do desembolso.<br/><small>One or more received due dates are before the disbursement date.</small> |
| <a id="COP000131"></a>`COP000131` | 400 | **Bad Request**<br/>Todos os elementos dentro da lista de datas de vencimento devem ser únicos.<br/><small>All elements inside due dates list must be unique.</small> |
| <a id="COP000133"></a>`COP000133` | 400 | **Bad Request**<br/>O desembolso precisa ser feito para uma conta de mesma titularidade de quem está pegando o empréstimo, no caso o tomador.<br/><small>The disbursement need to be in a account with the same ownership as the borrower.</small> |
| <a id="COP000134"></a>`COP000134` | 404 | **Not Found**<br/>Nenhuma operação de crédito encontrada para o lote recebido.<br/><small>No credit operation found for given batch.</small> |
| <a id="COP000135"></a>`COP000135` | 404 | **Not Found**<br/>Algumas operações de crédito não foram encontradas para o lote recebido.<br/><small>Some credit operations were not found for given batch.</small> |
| <a id="COP000136"></a>`COP000136` | 400 | **Bad Request**<br/>Mais de um requester encontrado no lote de desembolso. Espera-se apenas um requester para todas as operações de crédito contidas no lote.<br/><small>More than one requester found inside batch. Expected only one requester for all credit operations inside batch.</small> |
| <a id="COP000137"></a>`COP000137` | 400 | **Bad Request**<br/>Não foi encontrado um RequesterConfiguration para o requester {requester_key}<br/><small>No requester configuration found for requester {requester_key}.</small> |
| <a id="COP000138"></a>`COP000138` | 400 | **Bad Request**<br/>Requester {requester_key} não está configurado para desembolsar em lote.<br/><small>Requester {requester_key} is not configured to disburse in batch.</small> |
| <a id="COP000139"></a>`COP000139` | 400 | **Bad Request**<br/>Todas as operações de crédito precisam estar waiting_disbursement para serem desembolsadas<br/><small>Credit operations must all be waiting_disbursement to be disbursed</small> |
| <a id="COP000141"></a>`COP000141` | 400 | **Bad Request**<br/>Um ou mais RequesterConfigurations estão faltando para desembolsar em lote.<br/><small>Missing one or more RequesterConfigurations to disburse in batch.</small> |
| <a id="COP000142"></a>`COP000142` | 400 | **Bad Request**<br/>Código compe {bank_compe_code} na ação pós-desembolso não é válido.<br/><small>Bank compe code {bank_compe_code} in after disbursement action is not valid.</small> |
| <a id="COP000143"></a>`COP000143` | 400 | **Bad Request**<br/>Valor desembolsado deve ser informado quando a tarifa configurada é sobre valor desembolsado<br/><small>Disbursed amount must be sent when there is a fee is over its value.</small> |
| <a id="COP000144"></a>`COP000144` | 400 | **Bad Request**<br/>O assinante {related_party_name}, tem número de telefone celular com menos de 9 dígitos.<br/><small>Related party {related_party_name} has cellphone number with less than 9 digits</small> |
| <a id="COP000145"></a>`COP000145` | 400 | **Bad Request**<br/>Operação duplicada encontrada.<br/><small>Duplicate Operation was found</small> |
| <a id="COP000146"></a>`COP000146` | 400 | **Bad Request**<br/>Impossível adicionar tarifas externas sem a conta de rebate.<br/><small>Cannot add external fees without a rebate account.</small> |
| <a id="COP000147"></a>`COP000147` | 400 | **Bad Request**<br/>Chave da conta do cessionário deve ser fornecida com configuração de débito automático ligada.<br/><small>Purchaser account key must be sent along with automatic debt set on.</small> |
| <a id="COP000148"></a>`COP000148` | 400 | **Bad Request**<br/>O campo disburse_before_assign: '{disburse_before_assign}' deve ser boleano, foi enviado {type}.<br/><small>The field disburse_before_assign: '{disburse_before_assign}' must be boolean, it was sent {type}.</small> |
| <a id="COP000149"></a>`COP000149` | 400 | **Bad Request**<br/>Desembolso já concluído.<br/><small>Disbursement already completed.</small> |
| <a id="COP000150"></a>`COP000150` | 400 | **Bad Request**<br/>Não foi possível atualizar o valor de cessão para o tipo de juros {interest_type}. Atualização automática não disponível para este tipo.<br/><small>Unable to update assignment amount for interest type {interest_type}. Automatic update not available for this type.</small> |
| <a id="COP000151"></a>`COP000151` | 404 | **Not Found**<br/>Parcela não encontrada para {attribute} {value}<br/><small>Installment not found for {attribute} {value}</small> |
| <a id="COP000152"></a>`COP000152` | 400 | **Bad Request**<br/>Data de simulação {simulation_date} é menor que data de vencimento {due_date} para parcela de número {installment_number}<br/><small>Simulation date {simulation_date} is less than due date {due_date} for installment number {installment_number}.</small> |
| <a id="COP000153"></a>`COP000153` | 400 | **Bad Request**<br/>Não foi possível consultar o boleto (linha digitável: {digitable_line}). Por favor tente novamente em alguns minutos.<br/><small>It was not possible to consult the bank slip (digitable line: {digitable_line}). Please try again in a few minutes.</small> |
| <a id="COP000154"></a>`COP000154` | 400 | **Bad Request**<br/>Ação não permitida, porque a garantia não foi constituído. Credit Operation Key {credit_operation_key}<br/><small>Unable to do action, because collaterals are not constituted. Credit operation key {credit_operation_key};</small> |
| <a id="COP000155"></a>`COP000155` | 400 | **Bad Request**<br/>Não foi possível prosseguir com o desembolso em pix. Número de documento da conta de destino não corresponde ao fornecido.<br/><small>Unable to proceed with pix disbursement. Target account document number does not match one provided.</small> |
| <a id="COP000156"></a>`COP000156` | 400 | **Bad Request**<br/>Não foi possível prosseguir com o desembolso em pix. Agência e conta fornecidos não correspondem àqueles da chave pix.<br/><small>Unable to proceed with pix disbursement. Target account number and branch do not match those retrieved from pix key.</small> |
| <a id="COP000157"></a>`COP000157` | 400 | **Bad Request**<br/>Payload da conta de desembolso inválido. Certifique que dados da instituição financeira de destino e da conta estejam contidos.<br/><small>Invalid Disbursement Account Payload. Please make sure it contains target Financial Institution and account data.</small> |
| <a id="COP000158"></a>`COP000158` | 400 | **Bad Request**<br/>Valor de payroll para crédito consignado não foi informado ou é nulo. Favor informar o payroll_amount como decimal maior que zero.<br/><small>Payroll amount has not been informed or is zero. Please set payroll amount as decimal greater than zero.</small> |
| <a id="COP000159"></a>`COP000159` | 400 | **Bad Request**<br/>Pagamento não autorizado para agente {settlement_agent}<br/><small>Payment not allowed for settlement agent {settlement_agent}</small> |
| <a id="COP000160"></a>`COP000160` | 400 | **Bad Request**<br/>Pagamento não autorizado para operações com multiplas parcelas.<br/><small>Payment for operations with multiple installments not allowed.</small> |
| <a id="COP000161"></a>`COP000161` | 400 | **Bad Request**<br/>Pagamento não autorizado para operações cetipadas.<br/><small>Payment for cetip operations not allowed.</small> |
| <a id="COP000162"></a>`COP000162` | 400 | **Bad Request**<br/>Pagamento não autorizado para o status da parcela: {installment_status}.<br/><small>Payment not allowed for current installment status: {installment_status}.</small> |
| <a id="COP000163"></a>`COP000163` | 400 | **Bad Request**<br/>Action não encontrada<br/><small>Action not found;</small> |
| <a id="COP000164"></a>`COP000164` | 400 | **Bad Request**<br/>Action e mandatoria<br/><small>action_key is mandatory;</small> |
| <a id="COP000165"></a>`COP000165` | 400 | **Bad Request**<br/>O valor da nova action deve ser menor ou igual a action a ser atualizada<br/><small>The value of the new action must be lower or equal to the action to be updated</small> |
| <a id="COP000166"></a>`COP000166` | 400 | **Bad Request**<br/>action ja realizada.<br/><small>Action is already done.</small> |
| <a id="COP000167"></a>`COP000167` | 400 | **Bad Request**<br/>Nao foi possivel rodar a acao pos desembolso<br/><small>It's not possible to run after disbursement action  .</small> |
| <a id="COP000168"></a>`COP000168` | 400 | **Bad Request**<br/>Os periodos enviados não batem com as parcelas enviadas<br/><small>Periods sent did not match the installments received.</small> |
| <a id="COP000169"></a>`COP000169` | 400 | **Bad Request**<br/>Documento do comprador diferente da operação de crédito. Os endossos só podem endossar emissões de dívida com o mesmo comprador.<br/><small>Different purchaser document number. Endorsement operations can only endorse debt emissions with the same purchaser document number.</small> |
| <a id="COP000170"></a>`COP000170` | 400 | **Bad Request**<br/>Impossível de quitar operação com as parcelas enviadas.<br/><small>Impossible to settle operation with the installments sent.</small> |
| <a id="COP000171"></a>`COP000171` | 423 | **Locked**<br/>Operação PIX encerrada. Sistema disponível de {PIX_OPENING_TIME} até {PIX_CLOSING_TIME}<br/><small>PIX Operation window closed. System available from {PIX_OPENING_TIME} to {PIX_CLOSING_TIME}</small> |
| <a id="COP000172"></a>`COP000172` | 400 | **Bad Request**<br/>Tipo de juros não permitido para este endpoint. Pagamento recusado.<br/><small>Interest type not allowed at this endpoint. Payment refused.</small> |
| <a id="COP000173"></a>`COP000173` | 400 | **Bad Request**<br/>Recálculo de operação de crédito cancelada precisa regerar documento quando a certificadora não é cartular.<br/><small>Recalculate canceled credit operation must regenerate document when certifier is not notary office</small> |
| <a id="COP000174"></a>`COP000174` | 400 | **Bad Request**<br/>Operação Negada. A conta de desembolso não é de uma instituição participante ativa do PIX.<br/><small>Denied Operation. The chosen disbursement account institution is not an active PIX participant.</small> |
| <a id="COP000175"></a>`COP000175` | 400 | **Bad Request**<br/>Operação Negada. A conta de desembolso informada não é de uma instituição financeira encontrada.<br/><small>Denied Operation. The chosen disbursement account institution was not found.</small> |
| <a id="COP000176"></a>`COP000176` | 404 | **Not Found**<br/>Cessão não encontrado para os parâmetros informados.<br/><small>Assignment not found for the given parameters.</small> |
| <a id="COP000177"></a>`COP000177` | 404 | **Not Found**<br/>Cessão não encontrado para a credit_operation_key {credit_operation_key}<br/><small>Assignment not found for credit_operation_key {credit_operation_key}</small> |
| <a id="COP000178"></a>`COP000178` | 400 | **Bad Request**<br/>status da operação não permite alteração da conta de desembolso<br/><small>transaction status does not allow changing the disbursement account</small> |
| <a id="COP000179"></a>`COP000179` | 400 | **Bad Request**<br/>Quantidade de contas diverge com as já cadastradas nessa operação<br/><small>Number of accounts differs from those already registered in this operation</small> |
| <a id="COP000180"></a>`COP000180` | 400 | **Bad Request**<br/>O status da operação de crédito não permite esta operação.<br/><small>Credit operation status does not allow this operation.</small> |
| <a id="COP000181"></a>`COP000181` | 400 | **Bad Request**<br/>Partes relacionadas com documentos inválidos foram encontrados<br/><small>Related Parties with invalid document number was found</small> |
| <a id="COP000182"></a>`COP000182` | 400 | **Bad Request**<br/>Error ao executar split do desembolso. Porcentagem diferente de 100% foi encontrada para a operação.<br/><small>Error while doing disbursement split. Percentage differ 100% was found for credit operation.</small> |
| <a id="COP000183"></a>`COP000183` | 404 | **Not Found**<br/>Não foi encontrado um RequesterConfigurationPurchaser para o requester {requester_key}<br/><small>No RequesterConfigurationPurchaser found for requester {requester_key}.</small> |
| <a id="COP000184"></a>`COP000184` | 404 | **Not Found**<br/>Não foi encontrado um RequesterConfigurationPurchaser para a key {key}<br/><small>No RequesterConfigurationPurchaser found for key {key}.</small> |
| <a id="COP000185"></a>`COP000185` | 404 | **Not Found**<br/>Não foi encontrado um RequesterConfigurationPurchaser para o requester {requester_key} com o número de documento {document_number}.<br/><small>No RequesterConfigurationPurchaser found for requester {requester_key} with document number {document_number}.</small> |
| <a id="COP000186"></a>`COP000186` | 400 | **Bad Request**<br/>O número de contrato ja existe ou está duplicado.<br/><small>The contract number already exists or is duplicated.</small> |
| <a id="COP000187"></a>`COP000187` | 400 | **Bad Request**<br/>A operação precisa estar assinada para prosseguir com a geração da entrada.<br/><small>Operation must be issued to proceed to entry generation.</small> |
| <a id="COP000188"></a>`COP000188` | 400 | **Bad Request**<br/>A data de vencimento da entrada, deve ser um dia menor que a data de desembolso da operação.<br/><small>Entry deadline must be one day less to operation disbursement date.</small> |
| <a id="COP000189"></a>`COP000189` | 400 | **Bad Request**<br/>O solicitante precisa possuir um perfil de solicitante na bankslip.<br/><small>Requester must have a requester profile in bankslip.</small> |
| <a id="COP000190"></a>`COP000190` | 400 | **Bad Request**<br/>O solicitante precisa configurar uma requester_account_key nas configurações antes de prosseguir.<br/><small>Requester need to configure a requester_account_key in configurations before proceed.</small> |
| <a id="COP000191"></a>`COP000191` | 404 | **Not Found**<br/>Tipo de entrada não encontrada.<br/><small>Entry type not found.</small> |
| <a id="COP000192"></a>`COP000192` | 400 | **Bad Request**<br/>Entrada precisa ter um tipo para continuar.<br/><small>Entry must be of one type to proceed.</small> |
| <a id="COP000193"></a>`COP000193` | 400 | **Bad Request**<br/>A entrada precisa ser paga para prosseguir.<br/><small>Entry must be paid to proceed.</small> |
| <a id="COP000194"></a>`COP000194` | 404 | **Not Found**<br/>A entrada não foi encontrada.<br/><small>Entry not found.</small> |
| <a id="COP000195"></a>`COP000195` | 400 | **Bad Request**<br/>Ação não permitida, porque a entrada não foi paga. Credit Operation Key {credit_operation_key}<br/><small>Unable to do action, because entry is not paid. Credit operation key {credit_operation_key};</small> |
| <a id="COP000196"></a>`COP000196` | 400 | **Bad Request**<br/>Data de desembolso não pode ser no passado para o recalculo da credit operation, Key= {credit_operation_key}<br/><small>Disbursement date can not be in the past when recalculate credit operation, Key=  {credit_operation_key}.</small> |
| <a id="COP000197"></a>`COP000197` | 404 | **Not Found**<br/>Não há um boleto vinculado a uma operação de crédito.<br/><small>There's no bank_slip linked to a credit transaction.</small> |
| <a id="COP000198"></a>`COP000198` | 400 | **Bad Request**<br/>Numero ISPB é nulo e não foi possível encontrar instituição financeira com o número: {code_number}<br/><small>ISPB Number is None and not found financial institution with code number: {code_number}</small> |
| <a id="COP000199"></a>`COP000199` | 400 | **Bad Request**<br/>Base day deve ser um dia útil para recalculo de juros da credit_operation: {co_key}.<br/><small>Base day must be a working day while recalculate interest for credit_operation: {co_key}.</small> |
| <a id="COP000200"></a>`COP000200` | 400 | **Bad Request**<br/>Esta ação é permitida apenas para operações de crédito canceladas<br/><small>This action is allowed only for canceled credit operations</small> |
| <a id="COP000201"></a>`COP000201` | 400 | **Bad Request**<br/>A operação de crédito só pode ser descancelada no período de desembolso<br/><small>The credit Operation can be uncanceled only in disbursement date range</small> |
| <a id="COP000202"></a>`COP000202` | 400 | **Bad Request**<br/>A operação de crédito só pode ser descancelada antes da data de desembolso<br/><small>The credit Operation can be uncanceled only before the disbursement date</small> |
| <a id="COP000203"></a>`COP000203` | 400 | **Bad Request**<br/>Parcelas devem ser após data de desembolso.<br/><small>Installments must be after disbursement_date.</small> |
| <a id="COP000204"></a>`COP000204` | 400 | **Bad Request**<br/>Cessão com a chave {assignment_key} não está cancelada e não pode ser mudada pra aguardando assinatura.<br/><small>Assignment with key {assignment_key} is not canceled and cannot be changed to waiting_signature.</small> |
| <a id="COP000205"></a>`COP000205` | 404 | **Not Found**<br/>Estorno não encontrado.<br/><small>Reversal not found.</small> |
| <a id="COP000206"></a>`COP000206` | 409 | **Conflict**<br/>Essa KYC já foi finalizada com status {kyc_status}<br/><small>This KYC was already finalized with status {kyc_status}</small> |
| <a id="COP000207"></a>`COP000207` | 404 | **Not Found**<br/>Uma KYC com chave {kyc_key} não foi encontrada para a operação {credit_operation_key}<br/><small>A KYC with key {kyc_key} was not found for operation {credit_operation_key}</small> |
| <a id="COP000208"></a>`COP000208` | 400 | **Bad Request**<br/>Motivo de cancelamento {enumerator} já existe.<br/><small>Cancel reason {enumerator} already exists.</small> |
| <a id="COP000209"></a>`COP000209` | 404 | **Not Found**<br/>Motivo de cancelamento {enumerator} não encontrado.<br/><small>Cancel reason {enumerator} not found.</small> |
| <a id="COP000210"></a>`COP000210` | 400 | **Bad Request**<br/>Data da cessão deve ser maior ou igual à data de desembolso.<br/><small>Assignment date must be after or equal disbursement date.</small> |
| <a id="COP000211"></a>`COP000211` | 409 | **Conflict**<br/>Essa parcela/entrada já está paga.<br/><small>This installment/entry is already paid.</small> |
| <a id="COP000212"></a>`COP000212` | 400 | **Bad Request**<br/>Soma das porcentagens dos impostos deve ser menor que 100%.<br/><small>The sum of the tax percentages must be less than 100%.</small> |
| <a id="COP000213"></a>`COP000213` | 400 | **Bad Request**<br/>Campos de taxa não podem ter mais de 8 casas decimais.<br/><small>Rate fields cannot have more than 8 decimal places.</small> |
| <a id="COP000214"></a>`COP000214` | 400 | **Bad Request**<br/>Campo de taxa de atraso maior que o permitido.<br/><small>Delay Rate field higher than allowed.</small> |
| <a id="COP000215"></a>`COP000215` | 400 | **Bad Request**<br/>Custo efetivo anual total maior que o permitido.<br/><small>Annual CET field higher than allowed.</small> |
| <a id="COP000216"></a>`COP000216` | 400 | **Bad Request**<br/>A data para agendar o pagamento não é válida.<br/><small>The date to schedule payment is not valid.</small> |
| <a id="COP000217"></a>`COP000217` | 400 | **Bad Request**<br/>O método de assinatura {method} não é permitido para essa certificadora.<br/><small>The {method} signature method is not allowed for this certifier</small> |
| <a id="COP000218"></a>`COP000218` | 400 | **Bad Request**<br/>A conta de desembolso precisa ser a mesma que a conta do solicitante.<br/><small>The disbursement account must be the same of requester account.</small> |
| <a id="COP000219"></a>`COP000219` | 400 | **Bad Request**<br/>O valor final do desembolso, somado com a entrada, precisa ser o mesmo que o valor total do pagamento.<br/><small>The final disbursement amount, added to the entry payment, must be the same as the total payment amount.</small> |
| <a id="COP000220"></a>`COP000220` | 409 | **Bad Request**<br/>Erro de integridade, já existe dados com esse valor no campo: {field}.<br/><small>Integrity error, already exists data with this value on field: {field}.</small> |
| <a id="COP000221"></a>`COP000221` | 400 | **Bad Request**<br/>A ação não pode ser executada, o tempo de trabalho de transferência está fora da janela.<br/><small>Action cannot be executed, transfer work time is out of window.</small> |
| <a id="COP000222"></a>`COP000222` | 400 | **Bad Request**<br/>Nova data de desembolso deve ser dentro de 15 dias da data atual de desembolso.<br/><small>New disbursement date must be within 15 days of the actual disbursement date.</small> |
| <a id="COP000223"></a>`COP000223` | 400 | **Bad Request**<br/>O document do emissor deve ter 11 ou 14 caracteres.<br/><small>Issuer document number must be 11 or 14 characters long.</small> |
| <a id="COP000224"></a>`COP000224` | 400 | **Bad Request**<br/>A operação de crédito não pode ser desembolsada até que seja permitida.<br/><small>Credit operation cannot be disbursed until is allowed.</small> |
| <a id="COP000225"></a>`COP000225` | 400 | **Bad Request**<br/>O IOF total informado está fora do intervalo calculado.<br/><small>Informed total IOF amount is out of calculated range.</small> |
| <a id="COP000226"></a>`COP000226` | 400 | **Bad Request**<br/>Solicitação de IOF customizada não permitida para este requisitante.<br/><small>Custom IOF request not allowed for this requester.</small> |
| <a id="COP000227"></a>`COP000227` | 409 | **Bad Request**<br/>Erro de integridade, já existe operação com a mesma chave de identificação do solicitante.<br/><small>Integrity error, already exists operation with the same requester identifier key.</small> |
| <a id="COP000228"></a>`COP000228` | 404 | **Not Found**<br/>Instituição Financeira não encontrada.<br/><small>Financial institution not found.</small> |
| <a id="COP000229"></a>`COP000229` | 400 | **Bad Request**<br/>Tipo de transferência pix não encontrado, ou está incorreto.<br/><small>Pix transfer type not found, or is incorrect.</small> |
| <a id="COP000230"></a>`COP000230` | 404 | **Not Found**<br/>Conta de origem não encontrada.<br/><small>Source account not found.</small> |
| <a id="COP000231"></a>`COP000231` | 400 | **Bad Request**<br/>Operação Pix negada, instituição não consta na lista de participantes.<br/><small>Pix operation denied, institution is not on list of participants.</small> |
| <a id="COP000232"></a>`COP000232` | 400 | **Bad Request**<br/>Operação Pix negada, chave pix não existe.<br/><small>Pix operation denied, pix key does not exist.</small> |
| <a id="COP000233"></a>`COP000233` | 400 | **Bad Request**<br/>O valor a receber da conta de desembolso é diferente do valor do boleto.Valor do boleto:{bankslip_amount}<br/><small>The disbursement account amount receivable is different from the amount of bankslip.Bankslip amount:{bankslip_amount}</small> |
| <a id="COP000234"></a>`COP000234` | 400 | **Bad Request**<br/>Boleto não registrado.{extra_info_br}<br/><small>Bankslip not registered.{extra_info}</small> |
| <a id="COP000235"></a>`COP000235` | 400 | **Bad Request**<br/>Não é possível desembolsar a operação {credit_operation_key} devido ao horário de fechamento do boleto.<br/><small>Cannot disburse credit operation {credit_operation_key} due to BankSlip closing time.</small> |
| <a id="COP000236"></a>`COP000236` | 400 | **Bad Request**<br/>Desembolso com boleto precisa ter o amount_receivable.<br/><small>Bankslip disbursement account must have amount_receivable.</small> |
| <a id="COP000237"></a>`COP000237` | 400 | **Bad Request**<br/>A operação de crédito precisa ter portabilidade, e o collateral_type precisa ser 'dataprev_reservation'.<br/><small>Credit operation must have portability and collateral_type must be 'dataprev_reservation' or 'social_security_portability'.</small> |
| <a id="COP000238"></a>`COP000238` | 400 | **Bad Request**<br/>O campo final_disbursement_amount só é permitido para operações de refinanciamento.<br/><small>final_disbursement_amount field is allowed only for refinancing operations.</small> |
| <a id="COP000240"></a>`COP000240` | 400 | **Bad Request**<br/>Operações do Auxílio Brasil devem ter uma única conta de desembolso<br/><small>Social benefit operation must have only one disbursement account</small> |
| <a id="COP000242"></a>`COP000242` | 400 | **Bad Request**<br/>A operação de crédito não possui instituição de registro vinculada a ela.<br/><small>The credit operation does`not have a registration institution linked to it.</small> |
| <a id="COP000243"></a>`COP000243` | 400 | **Bad Request**<br/>A operação de crédito já está no status final.<br/><small>Credit operation already in final status.</small> |
| <a id="COP000244"></a>`COP000244` | 400 | **Bad Request**<br/>Nenhuma garantia encontrada para os parâmetros informados.<br/><small>No collateral found for informed params.</small> |
| <a id="COP000245"></a>`COP000245` | 400 | **Bad Request**<br/>Essa operação com {credit_operation_status} não permite cancelamento.<br/><small>Operation with status {credit_operation_status} cannot be cancelled.</small> |
| <a id="COP000246"></a>`COP000246` | 400 | **Bad Request**<br/>Status da cessão não permite essa operação. status: {assignment_status}<br/><small>Assignment status does not allow this operation. status: {assignment_status}</small> |
| <a id="COP000247"></a>`COP000247` | 400 | **Bad Request**<br/>Não é possível realizar a cessão com a operação liquidada.Chave da operação: {key}<br/><small>It is not possible to carry out the assignment with the operation settled.Operation_key: {key}</small> |
| <a id="COP000248"></a>`COP000248` | 400 | **Bad Request**<br/>Depósitos centrais das operações de crédito não são iguais<br/><small>Central depositories of credit operations are not the same</small> |
| <a id="COP000249"></a>`COP000249` | 400 | **Bad Request**<br/>A prazo da entrada não pode ser inferior à data de desembolso.<br/><small>The entry deadline cannot be less than disbursement date.</small> |
| <a id="COP000250"></a>`COP000250` | 400 | **Bad Request**<br/>Não é possível recalcular a operação com uma entrada revertida.<br/><small>Cannot recalculate operation with a reversed entry.</small> |
| <a id="COP000251"></a>`COP000251` | 400 | **Bad Request**<br/>A operação de estorno não é permitida, porque o status da operação de crédito não está como desembolsado.<br/><small>Reversal operation is not allowed, because the status of the credit operation is not disbursed.</small> |
| <a id="COP000252"></a>`COP000252` | 400 | **Bad Request**<br/>A opera��o de estorno n�o � permitida quando h� alguma parcela paga.<br/><small>Reversal operation is not allowed when any installment is paid.</small> |
| <a id="COP000253"></a>`COP000253` | 400 | **Bad Request**<br/>A conta do fundo precisa estar cadastrada para o requester.<br/><small>Purchaser account must be registered for the requester.</small> |
| <a id="COP000254"></a>`COP000254` | 400 | **Bad Request**<br/>Operação de Credito nao pode ser cancelada depois de 7 dias<br/><small>Credit Operation cannot be reversed after 7 days</small> |
| <a id="COP000255"></a>`COP000255` | 400 | **Bad Request**<br/>Operação de crédito precisa estar desembolsada para gerar um qr code de estorno.<br/><small>Must have a transaction key for the disbursement account.</small> |
| <a id="COP000256"></a>`COP000256` | 409 | **Bad Request**<br/>A reversão para este número de contrato já está registrada.<br/><small>Reversal to this contract number is already registered.</small> |
| <a id="COP000257"></a>`COP000257` | 400 | **Bad Request**<br/>O pagamento do boleto foi rejeitado.<br/><small>Bank slip payment was rejected.</small> |
| <a id="COP000258"></a>`COP000258` | 404 | **Not Found**<br/>Parte relacionada não encontrada para a chave {related_party_key}<br/><small>Related_party not found for key {related_party_key}</small> |
| <a id="COP000259"></a>`COP000259` | 400 | **Bad Request**<br/>Parte relacionada do tipo {person_type} não permite documento do tipo {document_type}<br/><small>{person_type} type related party not allow {document_type} document type</small> |
| <a id="COP000261"></a>`COP000261` | 409 | **Conflict**<br/>Operação de crédito já cancelada: {credit_operation_key}<br/><small>Credit operation already canceled: {credit_operation_key}</small> |
| <a id="COP000262"></a>`COP000262` | 400 | **Bad Request**<br/>A garantia {collateral_type} não aceita o tipo de juros fornecido.<br/><small>The colateral {collateral_type} does not accept the given interest type.</small> |
| <a id="COP000264"></a>`COP000264` | 400 | **Bad Request**<br/>Chave da operação duplicada.<br/><small>Duplicate credit operation key.</small> |
| <a id="COP000265"></a>`COP000265` | 400 | **Bad Request**<br/>Objeto com as informações do refinancimento não foi enviado corretamente<br/><small>Refinancing object was not sent</small> |
| <a id="COP000266"></a>`COP000266` | 400 | **Bad Request**<br/>Valor desembolsado da operação não é suficiente para quitar as operações recebidas<br/><small>Disbursed amount is not enough to refinance the operations received</small> |
| <a id="COP000267"></a>`COP000267` | 400 | **Bad Request**<br/>Não há parcelas abertas para fechar uma operação refinanciada.<br/><small>There is no opened installments to settle refinanced credit operation.</small> |
| <a id="COP000268"></a>`COP000268` | 400 | **Bad Request**<br/>Status da operação refinanciada não permite essa operação.<br/><small>Refinanced operation status does not allow this operation.</small> |
| <a id="COP000269"></a>`COP000269` | 400 | **Bad Request**<br/>Faltando dados para fechar operação de refinanciamento ou portabilidade<br/><small>Missing data to settle refinancing or portability operation.</small> |
| <a id="COP000270"></a>`COP000270` | 400 | **Bad Request**<br/>Valor de desembolso do refinanciamento não está de acordo com os valores de percentage receivable.<br/><small>Refinancing disbursing amount doesn't match percentage receivable in disbursement accounts.</small> |
| <a id="COP000271"></a>`COP000271` | 400 | **Bad Request**<br/>Status da operação não permite a reapresentação.<br/><small>Operation status does not permit change disbursement date.</small> |
| <a id="COP000272"></a>`COP000272` | 400 | **Bad Request**<br/>Já eixste uma operação de crédito de refinanciamento vinculada a uma das operações enviadas.<br/><small>There is another refinancing credit operation created with the same sent refinanced operation.</small> |
| <a id="COP000273"></a>`COP000273` | 400 | **Bad Request**<br/>O assignment type ou a document key devem estar presentes na requisição.<br/><small>Assignment type or document key must be in request.</small> |
| <a id="COP000274"></a>`COP000274` | 400 | **Bad Request**<br/>O número de documento {document_number} ja existe nos destinos desembolsáveis desse solicitante.<br/><small>The document number {document_number} already exists for this requester disbursable destinations.</small> |
| <a id="COP000275"></a>`COP000275` | 400 | **Bad Request**<br/>O número de ispb enviado deve ser igual ao número ISPB da instituição financeira.<br/><small>Sent ispb number doesn't match financial institution ispb number.</small> |
| <a id="COP000276"></a>`COP000276` | 400 | **Bad Request**<br/>Garantia do contrato não permite que a operação seja recalculada.<br/><small>Collateral type doesn't allow to recalculate operation.</small> |
| <a id="COP000277"></a>`COP000277` | 400 | **Bad Request**<br/>Não é permitido alterar data de desembolso após {number_of_days} dias da reserva da garantia {collateral_type}.<br/><small>Changing disbursement date is not allowed after {number_of_days} days after {collateral_type} collateral reservation.</small> |
| <a id="COP000278"></a>`COP000278` | 400 | **Bad Request**<br/>O campo limit_days_to_disburse deve ser informado para operações com esse tipo de garantia: {collateral_type}.<br/><small>The field limit_days_to_disburse must be informed for operations with this collateral type: {collateral_type}.</small> |
| <a id="COP000279"></a>`COP000279` | 400 | **Bad Request**<br/>Data de desembolso deve ser informada para operações com esse tipo de garantia: {collateral_type}.<br/><small>Disbursement date must be informed for operations with this collateral type: {collateral_type}.</small> |
| <a id="COP000280"></a>`COP000280` | 400 | **Bad Request**<br/>O boleto ja foi pago ou agendado.<br/><small>Bank slip is already paid or scheduled.</small> |
| <a id="COP000281"></a>`COP000281` | 400 | **Bad Request**<br/>Data de pagamento da parcela não é uma data válida.<br/><small>Installment paid at date is invalid.</small> |
| <a id="COP000282"></a>`COP000282` | 403 | **Unauthorized**<br/>As operações refinanciadas devem ser do mesmo requester que está pedindo a operação de refinanciamento.<br/><small>Refinanced credit operations must be from the same requester.</small> |
| <a id="COP000283"></a>`COP000283` | 400 | **Bad Request**<br/>O número de documento das operações refinanciadas deve o mesmo que da operação de refinanciamento.<br/><small>Refinanced operations issuer document must be the same as the refinancing operation.</small> |
| <a id="COP000284"></a>`COP000284` | 400 | **Bad Request**<br/>A porcentagem entre a tc global mais seguro e o valor de emissão ({tac_percentage}%) é maior que a porcentagem máxima de tc ({maximum_tac_percentage}%). A tc global mais seguro enviada foi de R${global_tac} e, para ser válido, o valor de tc global mais seguro deve ser de até R${valid_tac}.<br/><small>The percentage between global tc plus insurance and issue amount ({tac_percentage}%) is greater than the maximum tc percentage ({maximum_tac_percentage}%). The global tc plus insurance sent was R${global_tac} and, to be valid, the global tc plus insurance amount must be until R${valid_tac}.</small> |
| <a id="COP000285"></a>`COP000285` | 400 | **Bad Request**<br/>A porcentagem entre o rebate e o valor de emissão ({rebate_percentage}%) é maior que a porcentagem máxima de rebate ({maximum_rebate_percentage}%). O valor de rebate enviado foi de R${rebate_amount} e, para ser válido, o valor de rebate deve ser de até R${valid_rebate}.<br/><small>The percentage between rebate and issue amount ({rebate_percentage}%) is greater than the maximum rebate percentage ({maximum_rebate_percentage}%). The rebate amount sent was R${rebate_amount} and, to be valid, the rebate amount must be until R${valid_rebate}.</small> |
| <a id="COP000286"></a>`COP000286` | 400 | **Bad Request**<br/>Informações de desembolso inválido. Desembolso por boleto deve possuir linha digitavel(digitable_line).<br/><small>Invalid disbursement information payload. Bank slip disbursement type must have a digitable line(digitable_line).</small> |
| <a id="COP000287"></a>`COP000287` | 400 | **Bad Request**<br/>Informações de desembolso inválido. A conta de desembolso precisa possuir número, digito e agência ou uma chave pix.<br/><small>Invalid disbursement information payload. The disbursement account must have account number, digit and branch or a pix key.</small> |
| <a id="COP000288"></a>`COP000288` | 400 | **Bad Request**<br/>Informações de desembolso inválido. O número ispb ou código da instituição financeira deve ser informado.<br/><small>Invalid disbursement information payload. The target bank ispb number or financial institution code number must be informed.</small> |
| <a id="COP000289"></a>`COP000289` | 400 | **Bad Request**<br/>Configuração do requester para gravame não encontrada. Por favor entre em contato com o suporte.<br/><small>Requester configuration for car collateral fee not found. Please contact support.</small> |
| <a id="COP000290"></a>`COP000290` | 400 | **Bad Request**<br/>O campo de data {field_pt} precisa ter uma data menor ou igual a hoje<br/><small>The date field {field_en} must have a date lower or equal from today.</small> |
| <a id="COP000291"></a>`COP000291` | 400 | **BadRequest**<br/>Accrual da parcela do dia anterior precisa ser calculado primeiro.<br/><small>Installment Accrual from day before needs to be calculated first.</small> |
| <a id="COP000292"></a>`COP000292` | 400 | **BadRequest**<br/>Operação {credit_operation_key} está cedida na data de referência.<br/><small>Operation {credit_operation_key} is assigned on reference date.</small> |
| <a id="COP000293"></a>`COP000293` | 400 | **BadRequest**<br/>Operação {credit_operation_key} está cancelada na data de referência.<br/><small>Operation {credit_operation_key} is canceled on reference date.</small> |
| <a id="COP000294"></a>`COP000294` | 400 | **BadRequest**<br/>Operação {credit_operation_key} está quitada na data de referência.<br/><small>Operation {credit_operation_key} is settled on reference date.</small> |
| <a id="COP000296"></a>`COP000296` | 400 | **Bad Request**<br/>A taxa informada/calculada da operação, ultrapassa o permitido por lei para o tipo de garantia informada.  Taxa informada/calculada da operação: {montlhy_rate}.  Limite permitido por lei para o tipo de garantia {collateral_type}: {max_interest_rate}.<br/><small>The interest rate informed/calculated for the operation exceeds what is permitted by law for the collateral type informed.  Informed/calculated interest rate: {montlhy_rate}.  Limit allowed by law for the collateral type {collateral_type}: {max_interest_rate}.</small> |
| <a id="COP000297"></a>`COP000297` | 400 | **Bad Request**<br/>O produto de INSS está temporariamente indisponível<br/><small>The INSS product is temporarily unavailable</small> |
| <a id="COP000298"></a>`COP000298` | 400 | **Bad Request**<br/>O produto de cartão benefício INSS está temporariamente indisponível<br/><small>The card benefit INSS product is temporarily unavailable</small> |
| <a id="COP000299"></a>`COP000299` | 400 | **Bad Request**<br/>A operação {credit_operation_key} está cancelada, mas não possui um evento de cancelamento.<br/><small>The operation {credit_operation_key} is canceled, but does not have a cancel event.</small> |
| <a id="COP000300"></a>`COP000300` | 400 | **Bad Request**<br/>Existe um ou mais dias de accrual não calculados para essa operação {credit_operation_key}.<br/><small>There is one or more accrual days not calculated for the operation {credit_operation_key}.</small> |
| <a id="COP000301"></a>`COP000301` | 400 | **Bad Request**<br/>A operação {credit_operation_key} não possui evento de desembolso antes da data de referência.<br/><small>The operation {credit_operation_key} does not have a disbursement event before reference date.</small> |
| <a id="COP000302"></a>`COP000302` | 404 | **Not Found**<br/>Accrual não encontrado.<br/><small>Accrual not found.</small> |
| <a id="COP000304"></a>`COP000304` | 400 | **BadRequest**<br/>Accrual da operação {credit_operation_key} do dia anterior precisa ser calculado primeiro.<br/><small>Credit Operation {credit_operation_key} Accrual from day before needs to be calculated first.</small> |
| <a id="COP000305"></a>`COP000305` | 400 | **Bad Request**<br/>A operação {credit_operation_key} está quitada, mas não possui um evento de quitação.<br/><small>The operation {credit_operation_key} is settled, but does not have a settlement event.</small> |
| <a id="COP000306"></a>`COP000306` | 400 | **Bad Request**<br/>Saldo devedor de refinanciamento ({refinancing_due_balance}) deve ser menor ou igual que o saldo devedor original da operação ({present_value}).<br/><small>Refinancing due balance ({refinancing_due_balance}) must be lower or equal than original credit operation assignment amount ({present_value}).</small> |
| <a id="COP000307"></a>`COP000307` | 400 | **Bad Request**<br/>Saldo devedor de refinanciamento ({refinancing_due_balance}) mais valor de entrada ({entry_value}), que é {refinancing_sum}, deve ser menor ou igual que o saldo devedor original da operação ({present_value}).<br/><small>Refinancing due balance ({refinancing_due_balance}) plus entry value ({entry_value}), that is {refinancing_sum}, must be lower or equal than original credit operation assignment amount ({present_value}).</small> |
| <a id="COP000308"></a>`COP000308` | 400 | **Bad Request**<br/>Endosso não encontrada<br/><small>Endorsement not found</small> |
| <a id="COP000309"></a>`COP000309` | 400 | **Bad Request**<br/>A data atual está fora do intervalo de desembolso.<br/><small>Today's date is outside the disbursement range.</small> |
| <a id="COP000310"></a>`COP000310` | 400 | **Bad Request**<br/>Data de referência é anterior à data mínima permitida (2022-12-26).<br/><small>Reference date is before permitted minimum date (2022-12-26)</small> |
| <a id="COP000311"></a>`COP000311` | 404 | **Not Found**<br/>Liquidação CETIP não encontrada<br/><small>CETIP assignment not found</small> |
| <a id="COP000312"></a>`COP000312` | 400 | **Bad Request**<br/>Operação de crédito em status de {operation_status} não pode ser recalculada.<br/><small>Credit operation in {operation_status} status can't be recalculate.</small> |
| <a id="COP000313"></a>`COP000313` | 404 | **Invalid Installment Status**<br/>Inválido para aditar parcela no status: {installment_status}.<br/><small>Invalid to amend installment on status: {installment_status}.</small> |
| <a id="COP000314"></a>`COP000314` | 400 | **Bad Request**<br/>Operação inválida para operação não-aditada. O status atual é: {credit_operation_status}.<br/><small>Invalid operation for non-amended operation. The actual status is: {credit_operation_status}.</small> |
| <a id="COP000315"></a>`COP000315` | 400 | **Bad Request**<br/>O número de contrato da operação aditada ({amendment_credit_operation_contract_number}) é diferente do número de contrato da nova operação ({credit_operation_contract_number}).<br/><small>Amendment operation contract number ({amendment_credit_operation_contract_number}) is different from the contract number of the new operation ({credit_operation_contract_number}).</small> |
| <a id="COP000316"></a>`COP000316` | 400 | **Bad Request**<br/>O valor de emissão obtido pela operação de crédito aditada (R${final_disbursed_amount}) é diferente do saldo devedor enviado (R${due_balance}).<br/><small>Final disbursed amount originated by the amendment credit operation (R${final_disbursed_amount}) is different from the due balance sent (R${due_balance}).</small> |
| <a id="COP000317"></a>`COP000317` | 400 | **Bad Request**<br/>Operação já está no status de aditada.<br/><small>Operation is already on amended status.</small> |
| <a id="COP000319"></a>`COP000319` | 400 | **Bad Request**<br/>Emissor deve ser uma pessoa jurídica para operações do tipo Nota comercial.<br/><small>Issuer must be a legal person for Commercial Paper operation type.</small> |
| <a id="COP000320"></a>`COP000320` | 400 | **Bad Request**<br/>Campo portability data deve estar no collateral data para garantias de portabilidade.<br/><small>Portability data field must be in collateral data for portability collateral reservation type.</small> |
| <a id="COP000321"></a>`COP000321` | 400 | **Bad Request**<br/>Desembolso não é permitido para conta salário.<br/><small>Disbursement is not allowed for salary account type.</small> |
| <a id="COP000322"></a>`COP000322` | 400 | **Bad Request**<br/>Valor de pagamento excede o valor devido<br/><small>Paid amount exceeds due balance</small> |
| <a id="COP000323"></a>`COP000323` | 400 | **Bad Request**<br/>A diferença entre a soma dos valores presentes das parcelas ({sum_present_values}) e a soma dos valores de amortização das parcelas ({sum_principal}) não pode ser negativa.<br/><small>The difference between the sum of installments present amounts ({sum_present_values}) and the sum of installments principal amounts ({sum_principal}) can't be negative.</small> |
| <a id="COP000324"></a>`COP000324` | 400 | **Bad Request**<br/>Valor de pagamento excede o valor devido com valor restante de {remaining_amount}<br/><small>Paid amount exceeds due balance with remaining amount {remaining_amount}</small> |
| <a id="COP000325"></a>`COP000325` | 400 | **Bad Request**<br/>Diferença entre period e valor total da parcela ou data de vencimento foi encontrada.<br/><small>Difference between period and installment total amount or due date was found.</small> |
| <a id="COP000326"></a>`COP000326` | 400 | **Bad Request**<br/>O status atual da operação de crédito não permite atualizar a parte relacionada. O status atual é :{credit_operation_status}.<br/><small>Credit operation actual status is not allowed for update related party. The actual status is: {credit_operation_status}.</small> |
| <a id="COP000327"></a>`COP000327` | 400 | **Bad Request**<br/>Valor Cetip diferente do valor total da parcela. Installment key:{installment_key}<br/><small>Cetip amount different from installment total amount. Installment key: {installment_key}.</small> |
| <a id="COP000328"></a>`COP000328` | 400 | **Bad Request**<br/>O tipo de garantia {collateral_type} não permite atualizar a parte relacionada.<br/><small>Collateral type {collateral_type} is not allowed for update related party.</small> |
| <a id="COP000329"></a>`COP000329` | 400 | **Bad Request**<br/>Parte relacionada não encontrada para a related party key informada: {related_party_key}<br/><small>Related party not found for given related party key: {related_party_key}</small> |
| <a id="COP000330"></a>`COP000330` | 400 | **Bad Request**<br/>Garantia do tipo {collateral_type} não permite essa ação.<br/><small>Collateral type {collateral_type} does not allow this action.</small> |
| <a id="COP000331"></a>`COP000331` | 400 | **Bad Request**<br/>Os dias possívies para o desembolso devem ser de no máximo 30 dias.<br/><small>The possible days to disburse must be 30 at máximum.</small> |
| <a id="COP000332"></a>`COP000332` | 400 | **Bad Request**<br/>Não é possível reverter essa operação devido devido à não existência de disbursement key.<br/><small>Cant't reverse this operation due to no disbursement key.</small> |
| <a id="COP000333"></a>`COP000333` | 400 | **Bad Request**<br/>O valor de desembolso final não pode ser negativo.<br/><small>Credit Operation final disbursement cannot be negative.</small> |
| <a id="COP000334"></a>`COP000334` | 400 | **Bad Request**<br/>Reversão não permitida devido ao status da credit operation ser diferente de canceled.<br/><small>Reversal action not allowed because credit operation is not canceled.</small> |
| <a id="COP000335"></a>`COP000335` | 400 | **Bad Request**<br/>O valor de cessão é superior ao valor final da operação.<br/><small>The assignment amount is superior than the operation final amount.</small> |
| <a id="COP000336"></a>`COP000336` | 400 | **Bad Request**<br/>Somente tipos de tarifas relacionados com cessão são permitidos<br/><small>Only assignment related fee types permitted</small> |
| <a id="COP000337"></a>`COP000337` | 400 | **Bad Request**<br/>O CET da operação, ultrapassa o permitido por lei para o tipo de garantia informada.  CET informado/calculado da operação: {cet}.  Limite permitido por lei para o tipo de garantia {collateral_type}: {max_cet}.<br/><small>The CET informed/calculated for the operation exceeds what is permitted by law for the collateral type informed.  Informed/calculated CET: {cet}.  Limit allowed by law for the collateral type {collateral_type}: {max_cet}.</small> |
| <a id="COP000338"></a>`COP000338` | 400 | **Bad Request**<br/>Operação não pode ir para opened devido ao seu status {credit_operation_status}.<br/><small>Operation cannot became opened due to it's current status {credit_operation_status}.</small> |
| <a id="COP000339"></a>`COP000339` | 400 | **Bad Request**<br/>O valor de desembolso final não pode ser negativo. Opção de desembolso: {disbursement_option} Valor de Emissão {issue_amount}<br/><small>Credit Operation final disbursement cannot be negative. Disbursement option: {disbursement_option} Issue amount: {issue_amount}</small> |
| <a id="COP000341"></a>`COP000341` | 400 | **Bad Request**<br/>Não é possível calcular valores presentes das parcelas para operação no status: {credit_operation_status}.<br/><small>It is not possible to calculate installment present values for operation in status: {credit_operation_status}.</small> |
| <a id="COP000342"></a>`COP000342` | 404 | **Not Found**<br/>Recibo de Garantia Não Encontrado para essa Operação de Crédito Informada<br/><small>No Collateral Receipt Found for Informed Credit Operation</small> |
| <a id="COP000343"></a>`COP000343` | 422 | **Unprocessable Entity**<br/>Serviço da Celcoin indisponível.<br/><small>Celcoin service unavailable.</small> |
| <a id="COP000344"></a>`COP000344` | 400 | **Bad Request**<br/>Não foi possível criar a action.<br/><small>Action could not be created.</small> |
| <a id="COP000345"></a>`COP000345` | 400 | **Bad Request**<br/>O valor final ultrapassa o desembolsado ou emitido. Garanta que a soma dos valores das installments supere o valor desembolsado ou emitido.<br/><small>The final amount exceeds the disbursed or issue amount. Ensure the sum of installments amount does surpass the disbursed or issued amount.</small> |
| <a id="COP000346"></a>`COP000346` | 400 | **Bad Request**<br/>Os dias do ano de base não podem ser null.<br/><small>Base year days must not be null.</small> |
| <a id="COP000347"></a>`COP000347` | 400 | **Bad Request**<br/>Essa requisição só pode ser feita caso a operação tenha uma data de desembolso.<br/><small>This request can only be made if the operation has a disbursement date.</small> |
| <a id="COP000348"></a>`COP000348` | 400 | **Bad Request**<br/>Operação com status {credit_operation_status} não pode ser quitada.<br/><small>Operation with status {credit_operation_status} cannot be settled.</small> |
| <a id="COP000349"></a>`COP000349` | 400 | **Bad Request**<br/>Sistema instável. Por favor, tente novamente em alguns minutos.<br/><small>Sistem with instabillity. Please, retry again in a feel minutes.</small> |
| <a id="COP000350"></a>`COP000350` | 400 | **Bad Request**<br/>A ação de reversão não é permitida, devido à disbursement key da operação de crédito não bate com a incoming disbursement key.<br/><small>The reversal action is not allowed, because the credit operation disbursement key do not match with incoming disbursement key.</small> |
| <a id="COP000351"></a>`COP000351` | 400 | **Bad Request**<br/>Operação com garantia constituída não pode ser recalculada.<br/><small>Operation with collateral constituted cannot be recalculated.</small> |
| <a id="COP000352"></a>`COP000352` | 400 | **Bad Request**<br/>Data {date_string} não é uma data valida. Campo de data: {date_name}<br/><small>Date {date_string} is not a valid date. Date field: {date_name}</small> |
| <a id="COP000353"></a>`COP000353` | 400 | **Bad Request**<br/>Existem operações em status diferente de waiting disbursement.<br/><small>There are operations status not in waiting disbursement.</small> |
| <a id="COP000354"></a>`COP000354` | 400 | **Bad Request**<br/>Operação desembolsada previamente com disbursement key não pode ser cancelada forçadamente. Por favor, reverta as transfers.<br/><small>Operation previously disbursed with disbursement key cannot force cancel. Please revert transfers.</small> |
| <a id="COP000355"></a>`COP000355` | 400 | **Bad Request**<br/>Operação não elegível para cobrança de taxa do tipo tc. Por favor, não use esse tipo de fee para esse tomador de crédito.<br/><small>Operation not eligible for tc fee charge. Please do not use this fee type for this borrower.</small> |
| <a id="COP000356"></a>`COP000356` | 400 | **Bad Request**<br/>O tamanho do número da conta deve ser menor do que 13 para transferências do tipo Ted para contas que não sejam de pagamento.<br/><small>Account number length must be less than 13 for TED transfer method to non-payment account type.</small> |
| <a id="COP000357"></a>`COP000357` | 400 | **Bad Request**<br/>O número do documento é uma propriedade obrigatória.<br/><small>Issuer document number is a required property.</small> |
| <a id="COP000358"></a>`COP000358` | 400 | **Bad Request**<br/>O valor da tc global mais seguro  ({tac_amount}) é maior que o limite ({tac_limit_amount}) permitido para essa faixa de valor de emissão.<br/><small>The global tc plus insurance amount ({tac_amount}) is greater than the limit ({tac_limit_amount}) allowed for this range of issued amount.</small> |
| <a id="COP000359"></a>`COP000359` | 409 | **Conflict**<br/>Essa parcela já foi paga há mais de um dia.<br/><small>This installment has already been paid more than a day ago.</small> |
| <a id="COP000360"></a>`COP000360` | 400 | **Bad Request**<br/>Expiração do qr code da reversal não pode estar no passado.<br/><small>Reversal qr code expiration date cannot be in past.</small> |
| <a id="COP000361"></a>`COP000361` | 400 | **Bad Request**<br/>O Requester ainda não possui o parâmetro payment_type_configuration em sua configuração. Por favor, envie-o para continuar.<br/><small>The Requester Configuration doesn't have a payment_type_configuration parameter yet. Please provide it to continue.</small> |
| <a id="COP000362"></a>`COP000362` | 409 | **Conflict**<br/>Essa parcela já foi paga hoje.<br/><small>This installment has already been paid today.</small> |
| <a id="COP000363"></a>`COP000363` | 400 | **Bad Request**<br/>Essa operação de crédito esta no status 'canceled', 'settled' ou 'canceled_permanently'.<br/><small>This credit operation is in 'canceled', 'settled' or 'canceled_permanently' status.</small> |
| <a id="COP000364"></a>`COP000364` | 400 | **Bad Request**<br/>A data de desembolso da operação refinanceada precisa ser antes ou igual da data de desembolso da que está fazendo o refinanciamento.<br/><small>Refinanced operation disbursement date must be before or equal refinancing disbursement date.</small> |
| <a id="COP000365"></a>`COP000365` | 404 | **Not Found**<br/>Método de pagamento não encontrado.<br/><small>Payment method not found.</small> |
| <a id="COP000366"></a>`COP000366` | 400 | **Bad Request**<br/>DDD: {area_code} é invalido para o número de telefone da parte relacionada.<br/><small>Area code: {area_code} is invalid for related party phone number.</small> |
| <a id="COP000367"></a>`COP000367` | 400 | **Bad Request**<br/>A configuração: {reversal_to_fund} precisa ter uma conta do comprador configurada.<br/><small>The configuration: {reversal_to_fund} must have a purchaser account configured.</small> |
| <a id="COP000368"></a>`COP000368` | 400 | **Bad Request**<br/>A operação de crédito não pode estar cedida para criar taxas de contrato externas.<br/><small>Credit operation can't be assigned to create external contract fees.</small> |
| <a id="COP000369"></a>`COP000369` | 400 | **Bad Request**<br/>Para ceder operação pracisa envar a data de cessão.<br/><small>To assign operation you must send assigned at.</small> |
| <a id="COP000370"></a>`COP000370` | 404 | **Not Found**<br/>Operação refinanciada não encontrada.<br/><small>Refinancing credit operation not found.</small> |
| <a id="COP000371"></a>`COP000371` | 400 | **Bad Request**<br/>Parte relacionada do tipo pessoa deve possuir letras no nome. Nome invalido: {related_party_name}<br/><small>Natural person type related party must have letters in name. Invalid name: {related_party_name}</small> |
| <a id="COP000372"></a>`COP000372` | 400 | **Bad Request**<br/>Limite do número de parcelas excedido. Número de parcelas máximo permitido:{number_of_installments}<br/><small>Number of installments limit exceeded. Maximum number of installments allowed:{number_of_installments}</small> |
| <a id="COP000373"></a>`COP000373` | 400 | **Bad Request**<br/>Não é possível cancelar permanentemente porque a reserva da garantia ainda está sendo processada.<br/><small>Unable to cancel permanently because the collateral reservation is still being processed.</small> |
| <a id="COP000374"></a>`COP000374` | 400 | **Bad Request**<br/>Não é possível alterar a data de desembolso por conta do horário de funcionamento da TED. Para desembolso via TED, a data de desembolso precisa ser um dia útil.<br/><small>Cannot change disbursement date due to TED working time. For TED disbursement, disbursement date must be a work day.</small> |
| <a id="COP000375"></a>`COP000375` | 400 | **Bad Request**<br/>A garantia ainda não foi averbada para realizar essa ação.<br/><small>The collateral was not reserved yet for performing this action.</small> |
| <a id="COP000376"></a>`COP000376` | 400 | **Bad Request**<br/>Não é possível aplicar rebate. O valor do fee precisa ser maior que zero.<br/><small>Cannot apply external fee. Fee amount must be greather than 0.</small> |
| <a id="COP000377"></a>`COP000377` | 400 | **Bad Request**<br/>Essa operação de crédito não atende a todos os requisitos para a troca de cessionário.<br/><small>This credit operation does not fullfil the requisites for changing its purchaser.</small> |
| <a id="COP000378"></a>`COP000378` | 400 | **Bad Request**<br/>Não é possível quitar parcelas associadas a operações de refinanciamento.<br/><small>Cannot settle installment associated with a refinanced credit operation.</small> |
| <a id="COP000379"></a>`COP000379` | 400 | **Bad Request**<br/>Para usar o seguro qi, precisa ser enviado {field_translated}<br/><small>To use qi insurance, {field} must be sent</small> |
| <a id="COP000380"></a>`COP000380` | 400 | **Bad Request**<br/>Para usar seguro qi, não pode ser enviado {filed_translator}.<br/><small>To use insurance premium qi can not send {field}.</small> |
| <a id="COP000381"></a>`COP000381` | 400 | **Bad Request**<br/>Tomador não elegível para usar seguro qi. {reason_translated}<br/><small>Issuer not eligible to use insurance premium qi. {reason}</small> |
| <a id="COP000382"></a>`COP000382` | 400 | **Bad Request**<br/>Um endereço de ip nos dados de assinatura é necessário para registro dessa garantia.<br/><small>An IP address in signature data is required to register this collateral.</small> |
| <a id="COP000383"></a>`COP000383` | 404 | **Not Found**<br/>Parte relacionada não encontrada para o cpf {related_party_individual_document_number}<br/><small>Related_party not found for document number {related_party_individual_document_number}</small> |
| <a id="COP000384"></a>`COP000384` | 400 | **Bad Request**<br/>Não é possível trocar o tipo de desembolso para TED se a data de desembolso não for dia útil.<br/><small>It's not possible change disbursement type to TED if disbursement date is not work day.</small> |
| <a id="COP000385"></a>`COP000385` | 409 | **Conflict**<br/>Metadata ja existe para essa operação de crédito.<br/><small>Metadata already exists for this credit operation.</small> |
| <a id="COP000386"></a>`COP000386` | 400 | **Bad Request**<br/>'Metadata key' e 'metadata value' devem ser informados.<br/><small>'Metadata key' and 'metadata value' must be informed.</small> |
| <a id="COP000387"></a>`COP000387` | 404 | **Not Found**<br/>'Metadata não encontrado.<br/><small>Metadata not found.</small> |
| <a id="COP000388"></a>`COP000388` | 400 | **Bad Request**<br/>O novo valor de face da parcela deve ser menor que o valor antigo. Valor antigo: {old_installment_face_value}, Valor novo: {new_installment_face_value}.<br/><small>The new installment face value must be less than the old installment face value. Old value: {old_installment_face_value}, New value: {new_installment_face_value}.</small> |
| <a id="COP000389"></a>`COP000389` | 400 | **Bad Request**<br/>Operações fora da elegibilidade do cessionário. Número de parcelas está abaixo do mínimo permitido.<br/><small>Operations outside the purchase's eligibility. Number of installments is below the minimum allowed</small> |
| <a id="COP000390"></a>`COP000390` | 400 | **Bad Request**<br/>Campos faltando para requester_required_data: {missing_fields}<br/><small>Missing fields for requester_required_data: {missing_fields}</small> |
| <a id="COP000391"></a>`COP000391` | 400 | **Bad Request**<br/>Documentos faltando para requester_required_data: {missing_documents}<br/><small>Missing documents for requester_required_data: {missing_documents}</small> |
| <a id="COP000392"></a>`COP000392` | 400 | **Bad Request**<br/>O novo valor de face da parcela está errado. Valor antigo: {old_installment_face_value}, Valor novo: {new_installment_face_value}.<br/><small>The new installment face value is wrong. Old value: {old_installment_face_value}, New value: {new_installment_face_value}.</small> |
| <a id="COP000393"></a>`COP000393` | 400 | **Bad Request**<br/>Status da operação de crédito não permite essa operação. status: {credit_operation_status}<br/><small>Credit operation status does not allow this operation. status: {credit_operation_status}</small> |
| <a id="COP000394"></a>`COP000394` | 400 | **Bad Request**<br/>Numero de telefone: {phone_number} é invalido para o número de telefone da parte relacionada.<br/><small>Phone number: {phone_number} is invalid for related party phone number.</small> |
| <a id="COP000395"></a>`COP000395` | 400 | **Bad Request**<br/>A operação de crédito não está cedida<br/><small>Credit Operation is already not assigned</small> |
| <a id="COP000396"></a>`COP000396` | 400 | **Bad Request**<br/>A data de recompra é depois da data de cessão<br/><small>The unassigned_at is before than the assigned_at.</small> |
| <a id="COP000397"></a>`COP000397` | 400 | **Bad Request**<br/>Dados do tomador são invalidos: {invalid_reason}<br/><small>Issuer data is invalid: {invalid_reason}</small> |
| <a id="COP000398"></a>`COP000398` | 400 | **Bad Request**<br/>Operações do tipo portabilidade não podem ter tarifas do tipo tc.<br/><small>Operations of type portability can not have contract fees of type tc.</small> |
| <a id="COP000399"></a>`COP000399` | 400 | **Bad Request**<br/>Tarifas só podem ser cadastradas via billing api.<br/><small>Contract fees only can be used using billing api.</small> |
| <a id="COP000400"></a>`COP000400` | 400 | **Bad Request**<br/>Tarifa do tipo {fee_type} não pode ser criada ou alterada.<br/><small>Contract fee of fee type {fee_type} can not be created or changed.</small> |
| <a id="COP000401"></a>`COP000401` | 400 | **Bad Request**<br/>Tarifa do tipo {fee_type} já existe.<br/><small>Contract fee of fee type {fee_type} already exists.</small> |
| <a id="COP000402"></a>`COP000402` | 400 | **Bad Request**<br/>Status de reversão {reversal_status} não permitido.<br/><small>Reversal status {reversal_status} not permitted.</small> |
| <a id="COP000403"></a>`COP000403` | 400 | **Bad Request**<br/>Operações fora da elegibilidade do cessionário. Taxa de juros da operação está abaixo do mínimo permitido.<br/><small>Operations outside the purchase's eligibility. Interest rate of the operation is below the minimum allowed.</small> |
| <a id="COP000404"></a>`COP000404` | 404 | **Not Found**<br/>Análise do tomador não existe para operação de crédito com chave {credit_operation_key}<br/><small>Issuer analysis does not exist for credit operation with key {credit_operation_key}</small> |
| <a id="COP000405"></a>`COP000405` | 400 | **Bad Request**<br/>Refinanciamento não permitido quando a operação de crédito refinanciada está cedida.<br/><small>Refinancing not allowed when refinanced credit operation is assigned.</small> |
| <a id="COP000406"></a>`COP000406` | 404 | **Not Found**<br/>Operação de crédito não encontrada para essa análise de tomador.<br/><small>Credit operation not found for this issuer analysis</small> |
| <a id="COP000407"></a>`COP000407` | 400 | **Bad Request**<br/>Operação de crédito já escolhida para essa data.<br/><small>Credit operation already set for this date.</small> |
| <a id="COP000408"></a>`COP000408` | 400 | **Bad Request**<br/>Validação de elegibilidade para cessão falhou.<br/><small>Assignment eligibility validation failed.</small> |
| <a id="COP000409"></a>`COP000409` | 409 | **Conflict**<br/>Operação de crédito já cancelada permanentemente: {credit_operation_key}<br/><small>Credit operation already canceled permanently: {credit_operation_key}</small> |
| <a id="COP000410"></a>`COP000410` | 400 | **Bad Request**<br/>Código cnae invalido ({cnae_code}) informado pra parte relacionada.<br/><small>Invalid cnae code ({cnae_code}) informed to related party.</small> |
| <a id="COP000417"></a>`COP000417` | 400 | **Bad Request**<br/>Tarifas Externas só podem ser cadastradas via rebate api.<br/><small>External Contract fees only can be used using rebate api.</small> |
| <a id="COP000418"></a>`COP000418` | 400 | **Bad Request**<br/>A porcentagem entre o seguro e o valor de emissão ({insurance_premium_percentage}%) é maior que a porcentagem máxima de seguro ({maximum_insurance_premium_percentage}%). O valor de seguro enviado foi de R${insurance_premium_amount} e, para ser válido, o valor de seguro deve ser de até R${insurance_premium_valid_amount}.<br/><small>The percentage between insurance premium and issue amount ({insurance_premium_percentage}%) is greater than the maximum insurance premium percentage ({maximum_insurance_premium_percentage}%). The insurance premium amount sent was R${insurance_premium_amount} and, to be valid, the insurance premium amount must be until R${insurance_premium_valid_amount}.</small> |
| <a id="COP000419"></a>`COP000419` | 400 | **Bad Request**<br/>Produto de Seguro inválido ({insurance_premium_product}).<br/><small>Invalid Insurance product ({insurance_premium_product}).</small> |
| <a id="COP000420"></a>`COP000420` | 400 | **Bad Request**<br/>Parcela não está em um status válido para gerar um pagamento do tipo {payment_type}. status: {installment_status}<br/><small>Installment is not in a valid status to generate a {payment_type} payment method. status: {installment_status}</small> |
| <a id="COP000421"></a>`COP000421` | 400 | **Bad Request**<br/>Método de pagamento já existe para esta parcela. payment_type: {payment_type}<br/><small>Payment method already exists for this installment. payment_type: {payment_type}</small> |
| <a id="COP000422"></a>`COP000422` | 400 | **Bad Request**<br/>A geração de pagamento só pode ser aplicada em parcelas com data de vencimento comercial não atingida.<br/><small>Payment generation can only be applicated in installments with not pasted business due date.</small> |
| <a id="COP000423"></a>`COP000423` | 400 | **Bad Request**<br/>Método de pagamento {payment_type} não existente.<br/><small>Payment method {payment_type} does not exist.</small> |
| <a id="COP000424"></a>`COP000424` | 400 | **Bad Request**<br/>A operação de crédito não permite a geração de pagamento de parcela, porque a QI não é o agente de liquidação.<br/><small>Credit operation does not permit installment payment generation, because QI is not the settlement agent.</small> |
| <a id="COP000425"></a>`COP000425` | 400 | **Bad Request**<br/>Operação de credito sem conta de desembolso.<br/><small>Credit operation without disbursement account.</small> |
| <a id="COP000426"></a>`COP000426` | 400 | **Bad Request**<br/>A soma dos valores das parcelas não é igual ao valor pago. Soma dos valores das parcelas: {sum_installment_amount}, Valor pago: {paid_amount}<br/><small>The sum of the installment amounts is not equal to the paid amount. Sum of installment amounts: {sum_installment_amount}, Paid amount: {paid_amount}</small> |
| <a id="COP000427"></a>`COP000427` | 400 | **Bad Request**<br/>O payload não pode conter simultaneamente os campos days_to_expire e qr_code_expiration_date<br/><small>The payload cannot contain both days_to_expire and qr_code_expiration_date at the same time.</small> |
| <a id="COP000428"></a>`COP000428` | 400 | **Bad Request**<br/>A data máxima de vencimento não pode ultrapassar 14 dias úteis a partir da data de geração.<br/><small>The maximum due date cannot exceed 14 business days from the generation date.</small> |
| <a id="COP000429"></a>`COP000429` | 400 | **Bad Request**<br/>Linha digitável duplicada informada nas ações de pós-desembolso.<br/><small>Duplicate digitable line informed in after disbursement action data.</small> |
| <a id="COP000430"></a>`COP000430` | 400 | **Bad Request**<br/>A garantia {collateral_type} deve possuir um agente de crédito na lista de partes relacionadas.<br/><small>The collateral {collateral_type} must have a credit agent in related party list.</small> |
| <a id="COP000431"></a>`COP000431` | 400 | **Bad Request**<br/>'individual_document_number' deve ser informado para agente de crédito.<br/><small>'individual_document_number' must be informed for credit agent.</small> |
| <a id="COP000432"></a>`COP000432` | 403 | **Forbidden**<br/>Requester não tem permissão para reverter operações.<br/><small>Requester is not allowed to reverse operations.</small> |
| <a id="COP000433"></a>`COP000433` | 400 | **Bad Request**<br/>Pelo menos uma operação de crédito deve estar aberta para o pagamento prosseguir para o contrato {contract_number}.<br/><small>At least one credit_operation must be open for payment to proceed for contract number {contract_number}.</small> |
| <a id="COP000434"></a>`COP000434` | 400 | **Bad Request**<br/>Pelo menos uma operação de crédito deve estar aberta ou liquidada para prosseguir com o get de deduções para o contrato {contract_number}.<br/><small>At least one credit_operation must be opened or settled to proceed with get of deductions for the contract {contract_number}.</small> |
| <a id="COP000435"></a>`COP000435` | 400 | **Bad Request**<br/>A parcela não pode estar no status 'paid_partial' com o valor pago igual ou maior que o valor total da parcela.<br/><small>The installment can't be in 'paid_partial' status with paid amount equal or greater than installment total amount.</small> |
| <a id="COP000436"></a>`COP000436` | 400 | **Bad Request**<br/>Uma parte relacionada com o tipo de função: {role_type} já existe.<br/><small>A related party with role type: {role_type} already exist.</small> |
| <a id="COP000437"></a>`COP000437` | 404 | **Not Found**<br/>Nenhuma operação de portabilidade encontrada para este refinanciamento<br/><small>No portability CO found for this refinancing</small> |
| <a id="COP000438"></a>`COP000438` | 404 | **Not Found**<br/>Nenhuma operação de crédito refinanciada liquidada encontrada para este refinanciamento<br/><small>No settled refinanced credit operation found for this refinancing</small> |
| <a id="COP000439"></a>`COP000439` | 409 | **Conflict**<br/>Todas as operações de crédito refinanciadas já estão revertidas<br/><small>All refinanced credit operations are already reversed</small> |
| <a id="COP000441"></a>`COP000441` | 404 | **Not Found**<br/>Nenhuma refinanced credit operation elegível encontrada para alteração de status.<br/><small>No eligible refinanced credit operation found for status update.</small> |
| <a id="COP000442"></a>`COP000442` | 404 | **Status not found**<br/>O status informado não foi encontrado no sistema.<br/><small>The specified status was not found in the system.</small> |
| <a id="COP000443"></a>`COP000443` | 409 | **Conflict**<br/>A operação de crédito refinanciada informada já foi revertida.<br/><small>The specified refinanced credit operation is already reversed.</small> |
| <a id="COP000444"></a>`COP000444` | 400 | **Bad Request**<br/>A operação de crédito possui mais de uma operação de crédito refinanciada.<br/><small>The credit operation has more than one refinanced credit operation.</small> |
| <a id="COP000445"></a>`COP000445` | 400 | **Bad Request**<br/>O agente de crédito: {document_number} não está autorizado a emitir operação de crédito.<br/><small>The credit agent: {document_number} is not authorized to issue a credit operation.</small> |
| <a id="COP000446"></a>`COP000446` | 404 | **Not Found**<br/>Nenhuma operação de crédito refinanciada encontrada<br/><small>No refinanced credit operations found</small> |
| <a id="COP000447"></a>`COP000447` | 404 | **Not Found**<br/>Nenhuma operação de crédito refinanciada aberta encontrada<br/><small>No refinanced credit operations opened found</small> |
| <a id="COP000448"></a>`COP000448` | 400 | **Bad Request**<br/>A operação de crédito já está liquidada<br/><small>The credit operation is settled</small> |
| <a id="COP000449"></a>`COP000449` | 400 | **Bad Request**<br/>A operação de crédito não é elegível para seguro<br/><small>The credit operation is not eligible for insurance premium</small> |
| <a id="COP000450"></a>`COP000450` | 409 | **Conflict**<br/>O endereço da parte relacionada já está definido.<br/><small>The related party address is already set.</small> |
| <a id="COP000451"></a>`COP000451` | 404 | **Not Found**<br/>O endereço da parte relacionada não está definido.<br/><small>The related party address is not set.</small> |
| <a id="COP000452"></a>`COP000452` | 400 | **Bad Request**<br/>A modalidade ncom não é permitida para operações de crédito que não são ncom.<br/><small>The modality ncom is not allowed for non ncom credit operation type.</small> |
| <a id="COP000453"></a>`COP000453` | 400 | **Bad Request**<br/>A operação de crédito deve ser uma operação de crédito ncom.<br/><small>The credit operation must be a ncom credit operation.</small> |
| <a id="COP000454"></a>`COP000454` | 400 | **Bad Request**<br/>A operação de crédito está atribuída.<br/><small>The credit operation is assigned.</small> |
| <a id="COP000455"></a>`COP000455` | 404 | **Not Found**<br/>O estado civil não foi encontrado.<br/><small>The marital status was not found.</small> |
| <a id="COP000456"></a>`COP000456` | 400 | **Bad Request**<br/>O email não é válido.<br/><small>The email is not valid.</small> |
| <a id="COP000457"></a>`COP000457` | 404 | **Not Found**<br/>O sistema de propriedade não foi encontrado.<br/><small>The property system was not found.</small> |
| <a id="COP000458"></a>`COP000458` | 400 | **Bad Request**<br/>A data não pode ser mais de 110 anos atrás.<br/><small>The date cannot be more than 110 years ago.</small> |
| <a id="COP000459"></a>`COP000459` | 400 | **Bad Request**<br/>A data de nascimento deve estar no formato YYYY-MM-DD.<br/><small>The birth date must be in YYYY-MM-DD format.</small> |
| <a id="COP000460"></a>`COP000460` | 404 | **Not Found**<br/>O tipo de documento de identificação não foi encontrado.<br/><small>The document identification type was not found.</small> |
| <a id="COP000461"></a>`COP000461` | 404 | **Not Found**<br/>O gênero não foi encontrado.<br/><small>The gender was not found.</small> |
| <a id="COP000462"></a>`COP000462` | 400 | **Bad Request**<br/>O valor pago deve ser menor que o valor presente da parcela: {present_amount}.<br/><small>The paid amount must be less than the present amount of the installment: {present_amount}.</small> |
| <a id="COP000463"></a>`COP000463` | 400 | **Bad Request**<br/>O valor pago deve ser menor ou igual ao valor presente da parcela: {present_amount}.<br/><small>The paid amount must be less than or equal to the present amount of the installment: {present_amount}.</small> |
| <a id="COP000464"></a>`COP000464` | 400 | **Bad Request**<br/>O status da parcela deve ser 'paid' ou 'paid_partial'.<br/><small>The installment status must be 'paid' or 'paid_partial'.</small> |
| <a id="COP000465"></a>`COP000465` | 400 | **Bad Request**<br/>A operação de crédito deve estar cedida para ser paga.<br/><small>The credit operation must be assigned to be paid.</small> |
| <a id="COP000466"></a>`COP000466` | 400 | **Bad Request**<br/>A data de pagamento deve ser no passado.<br/><small>The paid at date must be in the past.</small> |
| <a id="COP000467"></a>`COP000467` | 400 | **Bad Request**<br/>A parcela deve estar em um status pendente para ser paga.<br/><small>The installment must be in a pending status to be paid.</small> |
| <a id="COP000468"></a>`COP000468` | 400 | **Bad Request**<br/>Não é possível alterar a data de desembolso de uma operação de crédito que possui data de fim de desembolso no passado. disbursement_end_date: {disbursement_end_date}<br/><small>Cannot change disbursement date of a credit operation that has disbursement end date in the past. disbursement_end_date: {disbursement_end_date}</small> |
| <a id="COP000469"></a>`COP000469` | 400 | **Bad Request**<br/>Não é possível pagar para o Inbursa.<br/><small>Cannot pay to Inbursa.</small> |
| <a id="COP000470"></a>`COP000470` | 400 | **Bad Request**<br/>O valor pago não pode ser zero.<br/><small>The paid amount cannot be zero.</small> |
| <a id="COP000471"></a>`COP000471` | 400 | **Bad Request**<br/>O CET anual não é válido. Recebido: {received_annual_cet}, Calculado: {calculated_annual_cet}<br/><small>The annual CET is not valid. Received: {received_annual_cet}, Calculated: {calculated_annual_cet}</small> |
| <a id="COP000472"></a>`COP000472` | 400 | **Bad Request**<br/>O CET mensal não é válido. Recebido: {received_monthly_cet}, Calculado: {calculated_monthly_cet}<br/><small>The monthly CET is not valid. Received: {received_monthly_cet}, Calculated: {calculated_monthly_cet}</small> |
| <a id="COP000473"></a>`COP000473` | 400 | **Bad Request**<br/>O campo de data {field_pt} é inválido: {reason_pt}<br/><small>The date field {field_en} is invalid: {reason_en}</small> |
| <a id="COP000474"></a>`COP000474` | 400 | **Bad Request**<br/>Pagamento de parcela antes do início do contrato<br/><small>Installment payment before contract start</small> |
| <a id="COP000475"></a>`COP000475` | 400 | **Bad Request**<br/>O valor deve ser maior que {min_amount} e menor que {max_amount}.<br/><small>Amount must be greater than {min_amount} and less than {max_amount}.</small> |
| <a id="COP000476"></a>`COP000476` | 400 | **Bad Request**<br/>O status de reserva da operação refinanciada não permite esta operação.<br/><small>The reservation status of the refinanced credit operation does not allow this operation.</small> |
| <a id="COP000477"></a>`COP000477` | 400 | **Bad Request**<br/>A data de pagamento está há mais de 5 dias da data atual<br/><small>The paid at date is more than 5 days from the current date</small> |
| <a id="COP000478"></a>`COP000478` | 400 | **Bad Request**<br/>Valor de desconto {discount_amount} excede o valor devido {due_balance}<br/><small>Discount amount {discount_amount} exceeds due balance {due_balance}</small> |
| <a id="COP000479"></a>`COP000479` | 400 | **Bad Request**<br/>Cancelamento não permitido, quantidade máxima de cancelamentos atingida<br/><small>Cancel not permitted, maximum quantity for uncancel reached</small> |
| <a id="COP000480"></a>`COP000480` | 400 | **Bad Request**<br/>A operação de crédito já está cedida e não pode ter seu cessionário alterado<br/><small>Credit Operation already assigned and cannot have its purchaser changed</small> |
| <a id="COP000481"></a>`COP000481` | 400 | **Bad Request**<br/>A operação de crédito com cessão em andamento e não pode ter seu cessionário alterado<br/><small>Credit Operation with assignment in progress and cannot have its purchaser changed</small> |
| <a id="COP000482"></a>`COP000482` | 400 | **Bad Request**<br/>Um documento do tipo {document_type} já existe para o assinante em questão.<br/><small>A document of type {document_type} already exists for this related party.</small> |
| <a id="COP000483"></a>`COP000483` | 401 | **Unauthorized**<br/>Recalculo invalido.<br/><small>Invalid recalculation.</small> |
| <a id="COP000484"></a>`COP000484` | 400 | **Bad Request**<br/>A taxa de juros mensal ou as parcelas devem ser fornecidas.<br/><small>Monthly interest rate or installments must be provided.</small> |
| <a id="COP000485"></a>`COP000485` | 400 | **Bad Request**<br/>A ação deve ser na mesma titulação do documento do emitente.<br/><small>Action must be in the same titularity as issuer document number when the operation has insurance.</small> |
| <a id="COP000486"></a>`COP000486` | 400 | **Bad Request**<br/>A ação deve ser ted ou pix quando a operação possui seguro.<br/><small>Action must be ted or pix when the operation has insurance.</small> |
| <a id="COP000487"></a>`COP000487` | 400 | **Bad Request**<br/>O valor da ação deve ser igual ao valor final de desembolso da operação de crédito menos o valor do seguro.<br/><small>Action transaction amount must be equal to credit operation final disbursement amount minus insurance premium qi amount released.</small> |
| <a id="COP000488"></a>`COP000488` | 400 | **Bad Request**<br/>A configuração do solicitante não está ativa.<br/><small>The requester configuration is not active.</small> |
| <a id="COP000506"></a>`COP000506` | 400 | **Bad Request**<br/>Inconsistência em {mismatch_field} da proposta veicular: a soma dos itens ({items_sum}) deve ser igual a proposal.{amount_field} ({expected_amount}).<br/><small>Vehicle proposal item mismatch in {mismatch_field}: sum of items ({items_sum}) must equal proposal.{amount_field} ({expected_amount}).</small> |
| <a id="COP000530"></a>`COP000530` | 400 | **Bad Request**<br/>Partes relacionadas com número de documento de identificação CIN diferente do CPF foram encontradas: {related_parties}<br/><small>Related parties with CIN document identification number different from the CPF was found: {related_parties}</small> |

### CT — Portabilidade de Crédito

133 erros

| Código | HTTP | Mensagem |
|-|-|-|
| <a id="CT000001"></a>`CT000001` | 400 | **Bad Request**<br/>Use POST /account |
| <a id="CT000002"></a>`CT000002` | 404 | **Not Found**<br/>Proposta não encontrada<br/><small>Proposal not found</small> |
| <a id="CT000003"></a>`CT000003` | 404 | **Not Found**<br/>Operação de crédito não encontrada ({credit_operation_key}).<br/><small>Credit Operation not found ({credit_operation_key}).</small> |
| <a id="CT000004"></a>`CT000004` | 409 | **Conflict**<br/>Status da proposta ({proposal_status}) não permite solicitação de liquidação de portabilidade.<br/><small>Proposal status ({proposal_status}) does not allow portability settlement request.</small> |
| <a id="CT000006"></a>`CT000006` | 404 | **Not Found**<br/>Instituição Financeira com código {financial_institution_code_number} não encontrada.<br/><small>Financial Institution with code {financial_institution_code_number} not found</small> |
| <a id="CT000007"></a>`CT000007` | 404 | **Not Found**<br/>Configuração de requisitante com key {requester_key} não encontrada.<br/><small>Requester configuration for requester key {requester_key}.</small> |
| <a id="CT000008"></a>`CT000008` | 400 | **Bad Request**<br/>Participantes da CCB não são iguais aos signatários<br/><small>CCB participants are not the same as the signers</small> |
| <a id="CT000009"></a>`CT000009` | 400 | **Bad Request**<br/>Valor do contrato deve ser maior que o valor do desembolso<br/><small>Contract amount must be greater than the disbursement amount</small> |
| <a id="CT000010"></a>`CT000010` | 400 | **Bad Request**<br/>Status da proposta {enumerator} inválido para cancelamento.<br/><small>Invalid proposal status {enumerator} for cancellation.</small> |
| <a id="CT000011"></a>`CT000011` | 400 | **Bad Request**<br/>Ação Inválida<br/><small>Invalid Action</small> |
| <a id="CT000012"></a>`CT000012` | 400 | **Bad Request**<br/>O campo 'type' não pode ser nulo e deve conter um dos valores ('data-signature', 'pdf-signature')<br/><small>Field 'type' cannot be null and must contain one of the values ('data-signature', 'pdf-signature')</small> |
| <a id="CT000013"></a>`CT000013` | 400 | **Bad Request**<br/>Essa operação ja foi assinada.<br/><small>This operation has already been signed.</small> |
| <a id="CT000014"></a>`CT000014` | 400 | **Bad Request**<br/>Certificadora invalida.<br/><small>Invalid document certifier</small> |
| <a id="CT000015"></a>`CT000015` | 400 | **Bad Request**<br/>Falha ao validar hash MT. Razão: {reason}<br/><small>Failed validating MT hash. Reason: {reason}</small> |
| <a id="CT000016"></a>`CT000016` | 400 | **Bad Request**<br/>signature_template_key não associada a configuração do requisitante.<br/><small>signature_template_key not associated with requester configuration.</small> |
| <a id="CT000017"></a>`CT000017` | 400 | **Bad Request**<br/>A proposta não está pendente aceite.<br/><small>The proposal is not pending accptance by requester.</small> |
| <a id="CT000018"></a>`CT000018` | 400 | **Bad Request**<br/>Falha ao validar contrato na dataprev, tente novamente.<br/><small>Failed to check contract in dataprev. Please try again.</small> |
| <a id="CT000019"></a>`CT000019` | 400 | **Bad Request**<br/>Proposta não tem número de contrato.<br/><small>Proposal has no contract number.</small> |
| <a id="CT000020"></a>`CT000020` | 400 | **Bad Request**<br/>O contrato possui erros na Dataprev.<br/><small>Contract has errors on Dataprev.</small> |
| <a id="CT000021"></a>`CT000021` | 400 | **Bad Request**<br/>Horário invalido para processo de desembolso e assinatura.<br/><small>Invalid time for signature and disbursement process.</small> |
| <a id="CT000023"></a>`CT000023` | 400 | **Bad Request**<br/>Essa operação foi cancelada.<br/><small>This operation has been canceled.</small> |
| <a id="CT000024"></a>`CT000024` | 404 | **Not Found**<br/>Portabilidade não encontrada.<br/><small>Received portability not found.</small> |
| <a id="CT000025"></a>`CT000025` | 404 | **Not Found**<br/>Status da portabilidade não encontrada.<br/><small>Received portability status not found.</small> |
| <a id="CT000026"></a>`CT000026` | 404 | **Not Found**<br/>Razão de retenção não encontrada.<br/><small>Retained reason not found.</small> |
| <a id="CT000027"></a>`CT000027` | 400 | **Bad Request**<br/>Método de aprovação fora do horário permitido<br/><small>Approved method past closing time</small> |
| <a id="CT000028"></a>`CT000028` | 400 | **Bad Request**<br/>Método de retenção fora da data e horário máximo<br/><small>Retention method past max day and closing time</small> |
| <a id="CT000029"></a>`CT000029` | 400 | **Bad Request**<br/>Razao de retenção obrigatório<br/><small>Retention reason mandatory</small> |
| <a id="CT000030"></a>`CT000030` | 400 | **Bad Request**<br/>Razao de cancelamento obrigatório<br/><small>Cancel reason mandatory</small> |
| <a id="CT000031"></a>`CT000031` | 404 | **Bad Request**<br/>Contrato não encontrado no sistema do BTG. contract_number: {message}<br/><small>Contract not found in BTG system. contract_number: {message}</small> |
| <a id="CT000032"></a>`CT000032` | 400 | **Bad Request**<br/>Data do cálculo do saldo devedor do BTG não é igual à data máxima de envio da portabilidade.<br/><small>BTG due balance date doesnt match max portability date.</small> |
| <a id="CT000033"></a>`CT000033` | 400 | **Bad Request**<br/>O operation data deve possuir um dos campos: desired_installments or installment_face_value.<br/><small>The operation data must have one of the fields: desired_installments or installment_face_value.</small> |
| <a id="CT000034"></a>`CT000034` | 400 | **Bad Request**<br/>O status do fee payment não é válido para a validação de rco.<br/><small>Invalid fee payment for rco report.</small> |
| <a id="CT000035"></a>`CT000035` | 400 | **Bad Request**<br/>Configuração incompleta do solicitante. o solicitante deve ter template key de refinanciamento. Por favor, entre em contato com nosso suporte.<br/><small>Incomplete requester configuration. the requester must have a refinancing template key. Please, contact our support.</small> |
| <a id="CT000036"></a>`CT000036` | 400 | **Bad Request**<br/>O documento de contrato da operação deve estar assinado.<br/><small>Operation contract document must be signed.</small> |
| <a id="CT000037"></a>`CT000037` | 400 | **Bad Request**<br/>Erro ao enviar reserva da garantia. {ex}<br/><small>Error while send collateral reservation.{ex}</small> |
| <a id="CT000038"></a>`CT000038` | 400 | **Bad Request**<br/>Status da operação de crédito não permite assinatura.<br/><small>Credit Operation status doesnt allow signature.</small> |
| <a id="CT000039"></a>`CT000039` | 400 | **Bad Request**<br/>Tipo da operação deve ser portability_credit_operation ou refinancing_credit_operation.<br/><small>Credit operation type must be portability_credit_operation or refinancing_credit_operation.</small> |
| <a id="CT000040"></a>`CT000040` | 400 | **Bad Request**<br/>Operação de portabilidade deve estar no status 'paid' para continuar com a operação de refinanciamento.<br/><small>Portability operation must be in 'paid' status to accept refinancing operation.</small> |
| <a id="CT000041"></a>`CT000041` | 400 | **Bad Request**<br/>Colateral da operação de portabilidade deve estar constituído para continuar operação de refinanciamento.<br/><small>Collateral from portability must be constituted to continue refinancing operation.</small> |
| <a id="CT000042"></a>`CT000042` | 400 | **Bad Request**<br/>Operação de refinanciamento deve estar emitida para prosseguir.<br/><small>Refinancing operation must be issued to proceed.</small> |
| <a id="CT000043"></a>`CT000043` | 404 | **Bad Request**<br/>Operação de refinanciamento não encontrada.<br/><small>Refinancing operation not found.</small> |
| <a id="CT000044"></a>`CT000044` | 400 | **Bad Request**<br/>Status da operação de refinanciamento não permite cancelamento.<br/><small>Refinancing operation status does not allow cancellation.</small> |
| <a id="CT000045"></a>`CT000045` | 400 | **Bad Request**<br/>Essa operação só é permitida para operações de refinanciamento com garantia de INSS.<br/><small>This operation is only allowed for collateral type social_security and dataprev_reservation refinancing operations.</small> |
| <a id="CT000046"></a>`CT000046` | 400 | **Bad Request**<br/>Status da operação de refinanciamento ({operation_status}) não permite essa operação.<br/><small>Operation status ({operation_status}) does not allow this operation.</small> |
| <a id="CT000047"></a>`CT000047` | 400 | **Bad Request**<br/>Operação de refinanciamento deve estar constituída para alterar data de desembolso.<br/><small>Refinancing operation must be constituted in Dataprev to change disbursement date.</small> |
| <a id="CT000048"></a>`CT000048` | 400 | **Bad Request**<br/>Configuração do requisitante incompleta. Por favor, entre em contato com nosso suporte.<br/><small>Incomplete requester configuration. Please Contact our support.</small> |
| <a id="CT000049"></a>`CT000049` | 400 | **Bad Request**<br/>Instituição financeira enviada no contrato original não é participante da CIP. ispb: {ispb_number}<br/><small>Financial institution sent in original contract is not CIP participant. ispb: {ispb_number}</small> |
| <a id="CT000050"></a>`CT000050` | 400 | **Bad Request**<br/>Código da instituição financeira não foi enviado. portability_number: {portability_number}<br/><small>Financial institution code was not sent. portability_number: {portability_number}</small> |
| <a id="CT000051"></a>`CT000051` | 400 | **Bad Request**<br/>Não foi possível notificar o BTG sobre um ataque de portabilidade. portability_number: {portability_number}<br/><small>It wasn't possible to notificate BTG about a received portability. portability_number: {portability_number}</small> |
| <a id="CT000052"></a>`CT000052` | 400 | **Bad Request**<br/>Não foi possível confirmar uma portabilidade para o BTG. portability_number: {portability_number}<br/><small>It wasn't possible to confirm a portability for BTG. portability_number: {portability_number}</small> |
| <a id="CT000053"></a>`CT000053` | 400 | **Bad Request**<br/>Não foi possível cancelar uma portabilidade para o BTG já que a STR0047 não estava correta. portability_number: {portability_number}<br/><small>It wasn't possible to cancel a portability for BTG as STR0047 wasn't correct. portability_number: {portability_number}</small> |
| <a id="CT000054"></a>`CT000054` | 400 | **Bad Request**<br/>Proposta de portabilidade não foi cadastrad com o refinanciamento<br/><small>Portability proposal do not have refinancing</small> |
| <a id="CT000055"></a>`CT000055` | 400 | **Bad Request**<br/>Para criar um refinanciamento os dados financeiros e de conta de desembolso devem ser enviados.<br/><small>To create refinancing operation must be sent financial and disbursement bank account data.</small> |
| <a id="CT000056"></a>`CT000056` | 400 | **Bad Request**<br/>O status atual da proposta {proposal_status} não permite essa operação.<br/><small>Proposal actual status {proposal_status} does not allow this operation.</small> |
| <a id="CT000057"></a>`CT000057` | 400 | **Bad Request**<br/>O valor da parcela da nova simulação({new_installment_amount}) deve ser inferior ao valor da parcela da operação original ({origin_contract_installment_value}).<br/><small>The installment amount of the new simulation({new_installment_amount}) must be lower than original installment amount ({origin_contract_installment_value}).</small> |
| <a id="CT000058"></a>`CT000058` | 400 | **Bad Request**<br/>A proposta deve ser enviada até {default_delta_days} dias depois da criação, diferença de dias entre data de criação da proposta e envio: {days}.<br/><small>Proposal must be submitted within {default_delta_days} days after creation, difference in days between proposal creation and submission date: {days}.</small> |
| <a id="CT000059"></a>`CT000059` | 400 | **Bad Request**<br/>A taxa informada/calculada da operação de {operation_type_translate}, ultrapassa o permitido por lei para o tipo de garantia informada.  Taxa informada/calculada da operação: {montlhy_rate}.  Limite permitido por lei para o tipo de garantia {collateral_type}: {max_interest_rate}.<br/><small>The interest rate informed/calculated for the {operation_type} operation exceeds what is permitted by law for the collateral type informed.  Informed/calculated interest rate: {montlhy_rate}.  Limit allowed by law for the collateral type {collateral_type}: {max_interest_rate}.</small> |
| <a id="CT000060"></a>`CT000060` | 400 | **Bad Request**<br/>A related_party_key fornecida não é a do tomador ou do representante legal.<br/><small>The provided related_party_key is not from borrower or issuer legal representative.</small> |
| <a id="CT000061"></a>`CT000061` | 400 | **Bad Request**<br/>Collateral não encontrada para operação de credito informada.<br/><small>Collateral not found for reported credit operation.</small> |
| <a id="CT000062"></a>`CT000062` | 400 | **Bad Request**<br/>Campo {field} é obrigatório.<br/><small>Field {field} is required.</small> |
| <a id="CT000063"></a>`CT000063` | 400 | **Bad Request**<br/>Formato de data incorreto. Recebido: {signature_datetime}, formato esperado: '2023-01-01T12:30:55.000001Z'.<br/><small>Wrong datetime format. Received: {signature_datetime}, expected format: '2023-01-01T12:30:55.000001Z'.</small> |
| <a id="CT000064"></a>`CT000064` | 400 | **Bad Request**<br/>Motivo de retenção '{retention_reason}' não permitido para este tipo de operação.<br/><small>Retention reason '{retention_reason}' not allowed for this operation.</small> |
| <a id="CT000065"></a>`CT000065` | 400 | **Bad Request**<br/>O número de parcelas da operação de portabilidade é maior do que o número de parcelas remanescente da operação original.<br/><small>The number of installments of the portability operation is longer than the remaining number of installments of the original operation.</small> |
| <a id="CT000066"></a>`CT000066` | 400 | **Bad Request**<br/>Portabilidade deve estar no status settlement_sent para poder alterar para pending_settlement_confirmation<br/><small>Portability must be in status settlement_sent to be able to change to pending_settlement_confirmation</small> |
| <a id="CT000067"></a>`CT000067` | 404 | **Not Found**<br/>portability_settlement não encontrado.<br/><small>portability_settlement not found.</small> |
| <a id="CT000068"></a>`CT000068` | 400 | **Bad Request**<br/>Operação de refinanciamento não pode ser aceita sem dados de assinatura;<br/><small>Refinancing operation can not be accepted without signature data</small> |
| <a id="CT000069"></a>`CT000069` | 400 | **Bad Request**<br/>Método de deleção fora do horário permitido<br/><small>Delete method past closing time</small> |
| <a id="CT000070"></a>`CT000070` | 400 | **Bad Request**<br/>Propostas aceitas pelo solicitante não podem ser deletadas no mesmo dia de aprovação.<br/><small>Accepted by requester proposal can not be delete in the same day as approved.</small> |
| <a id="CT000071"></a>`CT000071` | 400 | **Bad Request**<br/>Horário inválido para envio de STR0047<br/><small>Invalid time to send STR0047</small> |
| <a id="CT000072"></a>`CT000072` | 400 | **Bad Request**<br/>Operação de portabilidade sem pagamento confirmado só pode continuar com o refinanciamento se o colateral estiver averbado por portabilidade ou portabilidade paga a no mínimo 4 dias.<br/><small>Pending settlement confirmation portability must be reserved by portability to continue refinancing operation or portability paid for at least 4 days.</small> |
| <a id="CT000073"></a>`CT000073` | 400 | **Bad Request**<br/>Refinanciamento já foi aceito.<br/><small>Refinancing already accepted.</small> |
| <a id="CT000074"></a>`CT000074` | 400 | **Bad Request**<br/>A taxa anual calculada ({annual_interest_rate}) é muito baixa.<br/><small>The calculated annual interest rate ({annual_interest_rate}) is too low.</small> |
| <a id="CT000075"></a>`CT000075` | 400 | **Bad Request**<br/>Documento de evidência de retenção obrigatório.<br/><small>Retention Proof document mandatory</small> |
| <a id="CT000076"></a>`CT000076` | 400 | **Bad Request**<br/>Somente operações de refinanciamento com status aberto podem ser canceladas<br/><small>Can only cancel refinancing operation with opened status.</small> |
| <a id="CT000077"></a>`CT000077` | 404 | **Bad Request**<br/>Portabilidade não encontrada para o número de portabilidade: {portability_number}.<br/><small>Portability not found for portability_number: {portability_number}.</small> |
| <a id="CT000078"></a>`CT000078` | 400 | **Bad Request**<br/>Received portability status {received_portability_status} não permite retenção.<br/><small>Received portability status {received_portability_status} does not allow retention.</small> |
| <a id="CT000079"></a>`CT000079` | 400 | **Bad Request**<br/>Operação de refinanciamento não pode estar constituída para alterar as informações financeiras e de desembolso.<br/><small>Refinancing operation must not be constituted in Dataprev to change disbursement and financial informations.</small> |
| <a id="CT000080"></a>`CT000080` | 400 | **Bad Request**<br/>Operação de refinanciamento precisa estar assinada para continuar.<br/><small>Refinancing operation must be signed to continue.</small> |
| <a id="CT000081"></a>`CT000081` | 400 | **Not Found**<br/>Operação de crédito não está no status canceled_permanently.<br/><small>Credit Operation not in canceled_permanently status.</small> |
| <a id="CT000082"></a>`CT000082` | 400 | **Bad Request**<br/>Portabilidade não pode ter collateral constituído para alterar dados.<br/><small>Portability can not be with collateral constituted to alter data.</small> |
| <a id="CT000083"></a>`CT000083` | 400 | **Bad Request**<br/>Portabilidade deve estar com erro de margem consignade excedida para alterar dados.<br/><small>Portability should be with consignable margin excceded error to alter data.</small> |
| <a id="CT000084"></a>`CT000084` | 400 | **Bad Request**<br/>Novo valor de face da parcela da portabilidade precisa ser menor que o valor antido de face.<br/><small>Portability new installment face value must be lower than old installment face value.</small> |
| <a id="CT000085"></a>`CT000085` | 404 | **Not Found**<br/>Proposta não tem liquidação.<br/><small>Proposal does not have a portability settlement.</small> |
| <a id="CT000086"></a>`CT000086` | 400 | **Bad Request**<br/>Não é permitido criar o tipo de operação portability com refinancing_data<br/><small>It's not permitted to create operation type portability with refinancing_data</small> |
| <a id="CT000087"></a>`CT000087` | 400 | **Bad Request**<br/>A portabilidade precisa estar com a garantia averbada para adicionar rebates.<br/><small>Portability collateral must be constituted to add rebates.</small> |
| <a id="CT000088"></a>`CT000088` | 400 | **Bad Request**<br/>Carência só é permitida para operações de refinanciamento.<br/><small>Grace period is just allowed to refinance operations.</small> |
| <a id="CT000089"></a>`CT000089` | 400 | **Bad Request**<br/>Carência não permitida para o tomador com o cpf '{document_number}' do estado '{state}'.<br/><small>Grace period not allowed to borrower with document number '{document_number}' from state '{state}'.</small> |
| <a id="CT000090"></a>`CT000090` | 400 | **Bad Request**<br/>O número '{number_of_grace_periods}' da carência de competências está inválido. O intervalo aceito é de 0 a 6.<br/><small>The number '{number_of_grace_periods}' of grace competencies is invalid. The accepted range is 0 to 6.</small> |
| <a id="CT000091"></a>`CT000091` | 400 | **Bad Request**<br/>Taxa de juros anual deve ser menor que {max_annual_interest_rate}. Taxa de juros anual calculada: {annual_rate}.<br/><small>Annual interest rate must be lower than {max_annual_interest_rate}. Calculated annual interest rate: {annual_rate}.</small> |
| <a id="CT000092"></a>`CT000092` | 400 | **Bad Request**<br/>O status de portabilidade recebida atual {current_received_portability_status} não permite alterar para {new_received_portability_status}.<br/><small>Current received portability status {current_received_portability_status} does not allow change to {new_received_portability_status}.</small> |
| <a id="CT000093"></a>`CT000093` | 400 | **Bad Request**<br/>O código ISPB da instituição do contrato de origem não pode ser o mesmo da QI SCD.<br/><small>The ISPB code from the institution of the origin contract cannot be the same as QI SCD.</small> |
| <a id="CT000094"></a>`CT000094` | 400 | **Bad Request**<br/>Subcorban com numero de documento {document_number} não permitido.<br/><small>Subcorban with document number {document_number} not permitted.</small> |
| <a id="CT000095"></a>`CT000095` | 400 | **Bad Request**<br/>Não é possível atualizar dados de garantia para operação de crédito constituída.<br/><small>Cannot update collateral data for constituted credit operation.</small> |
| <a id="CT000096"></a>`CT000096` | 400 | **Bad Request**<br/>Não é possível aprovar a proposta para a seguinte instituição {ispb}<br/><small>Cannot approve proposal for the following origin institution {ispb}.</small> |
| <a id="CT000097"></a>`CT000097` | 400 | **Bad Request**<br/>A portabilidade recebida não está retida.<br/><small>Received Portability not retained.</small> |
| <a id="CT000098"></a>`CT000098` | 400 | **Bad Request**<br/>Endereço de Ip inválido {ip_address} .<br/><small>Invalid Ip Address {ip_address} .</small> |
| <a id="CT000099"></a>`CT000099` | 400 | **Bad Request**<br/>O valor da parcela da nova simulação ({new_installment_amount}) tem uma diferença inferior a {percent_difference}% em relação ao valor da parcela da operação original ({origin_contract_installment_value}).<br/><small>The installment amount of the new refinancing simulation ({new_installment_amount}) has a difference of less than {percent_difference}% compared to the original installment amount ({origin_contract_installment_value}).</small> |
| <a id="CT000100"></a>`CT000100` | 400 | **Bad Request**<br/>O valor do desembolso final ({final_disbursement_amount}) é inferior a {minimum_final_disbursement_amount}.<br/><small>The final disbursement amount ({final_disbursement_amount}) is less than {minimum_final_disbursement_amount}.</small> |
| <a id="CT000101"></a>`CT000101` | 400 | **Bad Request**<br/>O código ISPB da instituição do contrato de origem {ispb_number} não pode estar nessa lista: {ispb_block_list}.<br/><small>The ISPB code from the institution of the origin contract {ispb_number} cannot be the in this list: {ispb_block_list}.</small> |
| <a id="CT000102"></a>`CT000102` | 400 | **Bad Request**<br/>Não é possível portar operação com nenhuma parcela paga.<br/><small>Operation cannot be ported with zero installments paid.</small> |
| <a id="CT000103"></a>`CT000103` | 400 | **Bad Request**<br/>Operações fora da elegibilidade do cessionário. {error_ptbr}<br/><small>Operations outside the purchase's eligibility. {error}</small> |
| <a id="CT000104"></a>`CT000104` | 400 | **Bad Request**<br/>A diferença entre o saldo devedor da portabilidade e o valor da operação de refin deve ser maior ou igual que 10% do valor do saldo devedor. Percentage: {percentage}%.<br/><small>The difference between portability due balance and refinanced operation amount must be greather or equals to 10% of the due balance value. Percentual: {percentage}%.</small> |
| <a id="CT000105"></a>`CT000105` | 400 | **Bad Request**<br/>A redução do valor de troco para o tomador não deve ser maior que 10%.<br/><small>The reduction in the final disbursed amount can't be greather than 10%.</small> |
| <a id="CT000106"></a>`CT000106` | 400 | **Bad Request**<br/>A portabilidade não pode ser aceita porque o contrato foi cedido<br/><small>The received portability cannot be accepted because the contract has been assigned</small> |
| <a id="CT000107"></a>`CT000107` | 400 | **Bad Request**<br/>Validação de elegibilidade para cessão falhou.<br/><small>Assignment eligibility validation failed.</small> |
| <a id="CT000108"></a>`CT000108` | 400 | **Bad Request**<br/>Todos os documentos devem conter uma 'document_key' válida.<br/><small>All documents must have a valid 'document_key' field.</small> |
| <a id="CT000109"></a>`CT000109` | 400 | **Bad Request**<br/>Todos os documentos devem conter um 'file_type' válido.<br/><small>All documents must have a valid 'file_type' field.</small> |
| <a id="CT000110"></a>`CT000110` | 400 | **Bad Request**<br/>Primeira data de vencimento do refinanciamento é diferente da primeira data de vencimento da portabilidade.<br/><small>First refinancing due date different from first portability due date.</small> |
| <a id="CT000111"></a>`CT000111` | 400 | **Bad Request**<br/>STR não enviado, não foi possível gerar o STR0047 receipt<br/><small>STR not sent, could not generate STR0047 receipt</small> |
| <a id="CT000112"></a>`CT000112` | 400 | **Bad Request**<br/>Aceitação de portabilidade desabilitada<br/><small>Accepting portability disabled</small> |
| <a id="CT000113"></a>`CT000113` | 400 | **Bad Request**<br/>A taxa de juros mensal {monthly_interest_rate} é menor que {min_monthly_interest_rate}<br/><small>Monthly interest rate {monthly_interest_rate} is less than {min_monthly_interest_rate}</small> |
| <a id="CT000114"></a>`CT000114` | 400 | **Bad Request**<br/>o campo assistance_type e state são obrigatórios<br/><small>the field assistance_type and state are required</small> |
| <a id="CT000115"></a>`CT000115` | 400 | **Bad Request**<br/>bank code or isbp number is required |
| <a id="CT000116"></a>`CT000116` | 400 | **Bad Request**<br/>Agente de crédito deve ser informado para proposta com garantia do tipo {collateral_type}.<br/><small>Credit agent must be informed for proposal with {collateral_type} collateral type.</small> |
| <a id="CT000117"></a>`CT000117` | 400 | **Bad Request**<br/>Só é possível recriar a operação de portabilidade com o status 'settled'.<br/><small>Can only recreate portability operation with settled status.</small> |
| <a id="CT000118"></a>`CT000118` | 400 | **Bad Request**<br/>O valor do troco é menor que {min_final_disbursement_amount_diff_percentage}% da soma do valor das parcelas do refinanciamento menos o valor soma das parcelas da portabilidade. O valor mínimo do troco permitido é de {min_final_disbursement_amount}. Valor calculado do troco: {final_disbursement_amount}.<br/><small>The final disbursement amount is less than {min_final_disbursement_amount_diff_percentage}% of the sum of refinancing installment minus the sum of portability installment. The minimum final disbursement amount allowed is {min_final_disbursement_amount}. Calculated final disbursement amount: {final_disbursement_amount}.</small> |
| <a id="CT000119"></a>`CT000119` | 400 | **Bad Request**<br/>O agente de crédito: {document_number} não está autorizado a emitir operação de crédito.<br/><small>The credit agent: {document_number} is not authorized to issue a credit operation.</small> |
| <a id="CT000120"></a>`CT000120` | 400 | **Bad Request**<br/>Atualização de Received portability após horário de fechamento<br/><small>Received portability update after closing time</small> |
| <a id="CT000121"></a>`CT000121` | 400 | **Bad Request**<br/>Não é possível portar um contrato originalmente emitido pela QI Tech.<br/><small>Cannot port a contract originally issued by QI Tech.</small> |
| <a id="CT000122"></a>`CT000122` | 409 | **Conflict**<br/>A requester_control_key já existe.<br/><small>The requester_control_key already exists.</small> |
| <a id="CT000123"></a>`CT000123` | 400 | **Bad Request**<br/>A data de desembolso da portabilidade não pode ser maior que a data de desembolso do refinanciamento.<br/><small>Portability disbursement can not be greater than refinancing disbursement date.</small> |
| <a id="CT000124"></a>`CT000124` | 400 | **Bad Request**<br/>Parte relacionada do tipo pessoa física não pode possuir números no nome e deve conter pelo menos uma letra. Nome invalido: {related_party_name}<br/><small>Natural person type related party can't have numbers in name and must contain at least one letter. Invalid name: {related_party_name}</small> |
| <a id="CT000125"></a>`CT000125` | 400 | **Bad Request**<br/>O campo Data de expedição do documento de identidade é inválido: {reason_pt}<br/><small>The field Document Identification Date is invalid: {reason_en}</small> |
| <a id="CT000126"></a>`CT000126` | 400 | **Bad Request**<br/>O campo Data de Nascimento é inválido: {reason_pt}<br/><small>The field Birth Date is invalid: {reason_en}</small> |
| <a id="CT000127"></a>`CT000127` | 400 | **Bad Request**<br/>O campo Data de Fundação é inválido: {reason_pt}<br/><small>The field Foundation Date is invalid: {reason_en}</small> |
| <a id="CT000128"></a>`CT000128` | 400 | **Bad Request**<br/>O campo company_document_number está inválido. Documento: {document_number}<br/><small>The field company_document_number is invalid. Document: {document_number}</small> |
| <a id="CT000129"></a>`CT000129` | 400 | **Bad Request**<br/>O campo individual_document_number está inválido. Documento: {document_number}<br/><small>The field individual_document_number is invalid. Document: {document_number}</small> |
| <a id="CT000130"></a>`CT000130` | 400 | **Bad Request**<br/>Formato de data incorreto. Recebido: {signature_datetime}, formato esperado: '2023-01-01'.<br/><small>Wrong date format. Received: {signature_datetime}, expected format: '2023-01-01'.</small> |
| <a id="CT000131"></a>`CT000131` | 404 | **Not Found**<br/>Não foi encontrada uma baixa de portabilidade com essa chave.<br/><small>Not found portability settlement key.</small> |
| <a id="CT000131"></a>`CT000131` | 404 | **Bad Request**<br/>Operação de portabilidade não está aberta.<br/><small>Portability credit operation is not opened.</small> |
| <a id="CT000133"></a>`CT000133` | 400 | **Bad Request**<br/>Prêmio de seguro QI não é permitido para INSS.<br/><small>Insurance premium QI is not allowed for social security collateral.</small> |
| <a id="CT000134"></a>`CT000134` | 400 | **Bad Request**<br/>O número de parcelas em atraso no contrato de origem deve ser menor ou igual a 1.<br/><small>The number of overdue installments in the origin contract must be less than or equal to 1.</small> |
| <a id="CT000135"></a>`CT000135` | 400 | **Bad Request**<br/>Portabilidade não permitida.<br/><small>Portability not allowed.</small> |

### DOC — Documentos

102 erros

| Código | HTTP | Mensagem |
|-|-|-|
| <a id="DOC000001"></a>`DOC000001` | 400 | **Payload Validation Error**<br/>{parse_error} |
| <a id="DOC000002"></a>`DOC000002` | 400 | **Certifier Type Error**<br/>Documento da certificadora {certifier_type} não suportado<br/><small>Document from certifier {certifier_type} not supported</small> |
| <a id="DOC000003"></a>`DOC000003` | 400 | **Bad Request**<br/>Falta document_key. Use GET /clicksign/{document_key}<br/><small>Missing document_key. Use GET /clicksign/{document_key}</small> |
| <a id="DOC000004"></a>`DOC000004` | 404 | **Document Not Found**<br/>Documento não encontrado para seguinte chave: {document_key}<br/><small>Document not found with provided key: {document_key}</small> |
| <a id="DOC000005"></a>`DOC000005` | 400 | **Bad Request**<br/>Use GET /document/{person_key} ou /document/{person_key}/{document_key}<br/><small>Use GET /document/{person_key} or /document/{person_key}/{document_key}</small> |
| <a id="DOC000006"></a>`DOC000006` | 400 | **Bad Request**<br/>Use POST /document |
| <a id="DOC000007"></a>`DOC000007` | 404 | **Not Found**<br/>Lote de documento não encontrado para a chave {document_batch_key}<br/><small>Document batch not found for key {document_batch_key}</small> |
| <a id="DOC000008"></a>`DOC000008` | 400 | **Bad Request**<br/>Body da request vazio.<br/><small>No body provided</small> |
| <a id="DOC000009"></a>`DOC000009` | 404 | **Not Found**<br/>Status não encontrado<br/><small>Status not found</small> |
| <a id="DOC000010"></a>`DOC000010` | 400 | **Bad Request**<br/>Use PUT /document/{person_key}/{document_key}/{status_name} ou /document/{document_key}/{status_name}<br/><small>Use PUT /document/{person_key}/{document_key}/{status_name} or /document/{document_key}/{status_name}</small> |
| <a id="DOC000011"></a>`DOC000011` | 400 | **Bad Request**<br/>Falta o parâmetro {action}. Use o dos seguintes valores: send_to_signature. Por favor, use PUT /document_batch/{document_batch_key}/{action}<br/><small>Missing {action} parameter. Use one of the followings: send_to_signature. Please use PUT /document_batch/{document_batch_key}/{action}</small> |
| <a id="DOC000012"></a>`DOC000012` | 400 | **Certifier Error**<br/>Certificadora {document_batch_certifier} não disponível para esta ação<br/><small>Certifier {document_batch_certifier} not supported for document batch</small> |
| <a id="DOC000013"></a>`DOC000013` | 400 | **Document Batch Error**<br/>Lote de documentos {document_batch_key} não possui documentos<br/><small>Document batch {document_batch_key} has no documents inside</small> |
| <a id="DOC000014"></a>`DOC000014` | 400 | **Document Batch Error**<br/>Lote de documentos já foi enviado para assinatura<br/><small>Document Batch has already been sent to signature</small> |
| <a id="DOC000015"></a>`DOC000015` | 400 | **Document Batch Error**<br/>Lote de documentos já foi enviado para assinatura e assinado<br/><small>Document Batch has already been sent to signature and signed</small> |
| <a id="DOC000016"></a>`DOC000016` | 400 | **Document Batch Error**<br/>Lote de documentos já foi cancelado e portanto não pode ser enviado para assinatura<br/><small>Document Batch status is canceled and cannot be sent to signature</small> |
| <a id="DOC000017"></a>`DOC000017` | 400 | **Document Batch Error**<br/>Documento {document_key} dentro do lote de documentos tem status {document_status}. O status do documento deve ser pending_document_batch quando está tentando enviar o lote de documentos para assinatura<br/><small>Document {document_key} inside document_batch has status {document_status}. Document status must be pending_document_batch when sending document_batch to signature</small> |
| <a id="DOC000018"></a>`DOC000018` | 400 | **Document Batch Error**<br/>Chave do lote de documentos faltando (document_batch_key). Por favor use Please use PUT /document_batch/{document_batch_key}/{action}<br/><small>Missing document_batch_key. Please use PUT /document_batch/{document_batch_key}/{action}</small> |
| <a id="DOC000019"></a>`DOC000019` | 404 | **Document Not Found**<br/>Documento não encontrado<br/><small>Document not found</small> |
| <a id="DOC000020"></a>`DOC000020` | 400 | **Document Draft Error**<br/>Arquivo final do documento já foi enviado<br/><small>Document final file has already been uploaded</small> |
| <a id="DOC000021"></a>`DOC000021` | 404 | **Template Not Found**<br/>Template não encontrado<br/><small>Template not found</small> |
| <a id="DOC000022"></a>`DOC000022` | 400 | **Document Draft Error**<br/>Documento deve ser assinável<br/><small>Document must be signable</small> |
| <a id="DOC000023"></a>`DOC000023` | 400 | **Bad Request**<br/>Use POST /draft/{document_key}/{template_key} |
| <a id="DOC000024"></a>`DOC000024` | 400 | **Bad Request**<br/>Chave do template não encontrada<br/><small>No template key found</small> |
| <a id="DOC000025"></a>`DOC000025` | 400 | **Bad Request**<br/>Use POST /resend_notification/{document_key} ou /resend_notification com document_key_list<br/><small>Use POST /resend_notification/{document_key} or /resend_notification with document_key_list</small> |
| <a id="DOC000026"></a>`DOC000026` | 404 | **Not Found**<br/>Não foi possível encontrar nenhum dos documentos {document_key_list}<br/><small>Could not find any of the following document(s) {document_key_list}</small> |
| <a id="DOC000027"></a>`DOC000027` | 400 | **Bad Request**<br/>Reenvio de notificação não disponível para {certifier}.<br/><small>Notification resend for {certifier} is not available.</small> |
| <a id="DOC000028"></a>`DOC000028` | 400 | **Bad Request**<br/>Use GET /signer_group/{signer_group_key} ou /signer_group?signer_group_key_list=key,key, ou /signer_group?owner_person_key={person_key}&referred_party_document_number_list=document_number,document_number, ou /signer_group?expiration=AAAA-MM-DD<br/><small>Use GET /signer_group/{signer_group_key} or /signer_group?signer_group_key_list=key,key, or /signer_group?owner_person_key={person_key}&referred_party_document_number_list=document_number,document_number, or /signer_group?expiration=AAAA-MM-DD</small> |
| <a id="DOC000029"></a>`DOC000029` | 400 | **Bad Request**<br/>Use GET /signer_group?owner_person_key={person_key}&referred_party_document_number_list= para usar referred_party_document_number_list<br/><small>Use GET /signer_group?owner_person_key={person_key}&referred_party_document_number_list= when using referred_party_document_number_list</small> |
| <a id="DOC000030"></a>`DOC000030` | 400 | **Bad Request**<br/>Não é possível usar signer_group_key_list e referred_party_document_number_list juntos<br/><small>Can not use signer_group_key_list and referred_party_document_number_list together</small> |
| <a id="DOC000031"></a>`DOC000031` | 400 | **Bad Request**<br/>URL errada, use /signer_group?signer_group_key_list=key,key,<br/><small>URL malformed please use /signer_group?signer_group_key_list=key,key,</small> |
| <a id="DOC000032"></a>`DOC000032` | 400 | **Bad Request**<br/>URL errada, use /signer_group?referred_party_document_number_list=document_number,document_number,<br/><small>URL malformed please use /signer_group?referred_party_document_number_list=document_number,document_number,</small> |
| <a id="DOC000033"></a>`DOC000033` | 404 | **Not Found**<br/>Grupos de assinantes com filtro não encontrados<br/><small>Signer Groups with filter not found</small> |
| <a id="DOC000034"></a>`DOC000034` | 404 | **Not Found**<br/>Grupo de assinantes com chave {signer_group_key}<br/><small>Signer Group with key {signer_group_key} not found</small> |
| <a id="DOC000035"></a>`DOC000035` | 404 | **Not Found**<br/>Grupo de assinantes com chave {signer_group_key}<br/><small>Signer Group with key {signer_group_key} not found</small> |
| <a id="DOC000036"></a>`DOC000036` | 403 | **Unauthorized**<br/>Este agente não pode criar um grupo de assinantes público<br/><small>This agent can not create a public signer group.</small> |
| <a id="DOC000037"></a>`DOC000037` | 400 | **Bad Request**<br/>Use Patch /signer_group/{signer_group_key} ou /signer_group com signer_group_key_list no payload.<br/><small>Use Patch /signer_group/{signer_group_key} or /signer_group with signer_group_key_list in payload.</small> |
| <a id="DOC000038"></a>`DOC000038` | 403 | **Unauthorized**<br/>Agente não autorizado para este update.<br/><small>Agent can not make this update.</small> |
| <a id="DOC000039"></a>`DOC000039` | 403 | **Unauthorized**<br/>Este agente não pode alterar um grupo de assinantes publico.<br/><small>This agent can not modified a public signer group.</small> |
| <a id="DOC000040"></a>`DOC000040` | 400 | **Bad Request**<br/>Grupo de assinantes com chave {signer_group_key} está inativo.<br/><small>Signer Group with key {signer_group_key} is inactivated</small> |
| <a id="DOC000041"></a>`DOC000041` | 400 | **Bad Request**<br/>Use Patch /signer_group_expired com data de expiração no payload.<br/><small>Use Patch /signer_group_expired with expiration in payload.</small> |
| <a id="DOC000042"></a>`DOC000042` | 400 | **Bad Request**<br/>Não é possível expirar grupos de assinantes com data diferente de hoje.<br/><small>Can not expire signer groups different from today</small> |
| <a id="DOC000043"></a>`DOC000043` | 400 | **Bad Request**<br/>Use GET /template/{template_key} ou /template/ com parâmetro document_type ou owner_person_key, referred_document_number, name e document_type<br/><small>Use GET /template/{template_key} or /template/ with a document_type as parameter or owner_person_key, referred_document_number, name and document_type</small> |
| <a id="DOC000044"></a>`DOC000044` | 404 | **Not Found**<br/>Template não encontrado para os parâmetros fornecidos.<br/><small>Template not found for the given parameters.</small> |
| <a id="DOC000045"></a>`DOC000045` | 400 | **Bad Request**<br/>Payload inválido<br/><small>Payload schema invalid</small> |
| <a id="DOC000046"></a>`DOC000046` | 400 | **Invalid Template**<br/>Arquivo do template deve ser .html<br/><small>Template file must have .html extension.</small> |
| <a id="DOC000047"></a>`DOC000047` | 400 | **Bad Request**<br/>Use PUT /upload/{document_key}/{template_key} |
| <a id="DOC000048"></a>`DOC000048` | 400 | **Bad Request**<br/>Por favor informe a ordem que deseja anexar o arquivo (no início ou fim)<br/><small>Please inform the order to append the file (first or last)</small> |
| <a id="DOC000049"></a>`DOC000049` | 400 | **Bad Request**<br/>Documento vazio<br/><small>Document is empty</small> |
| <a id="DOC000050"></a>`DOC000050` | 400 | **Bad Request**<br/>Request não é interna<br/><small>Request is not internal</small> |
| <a id="DOC000051"></a>`DOC000051` | 400 | **Bad Request**<br/>Use POST /webhook/{source}/{document_id} |
| <a id="DOC000052"></a>`DOC000052` | 400 | **Bad Request**<br/>document_batch_id {document_batch_id} errado para o documento com document_key {document_key}<br/><small>Document with document_key {document_key} has a wrong document batch id {document_batch_id}</small> |
| <a id="DOC000053"></a>`DOC000053` | 400 | **Bad Request**<br/>Status inválido.<br/><small>Invalid status.</small> |
| <a id="DOC000054"></a>`DOC000054` | 401 | **Invalid Header**<br/>Header inválido (content-hmac)<br/><small>Invalid header (content-hmac)</small> |
| <a id="DOC000055"></a>`DOC000055` | 401 | **Unauthorized**<br/>Evento {event} recebido mas não autorizado<br/><small>Event {event} received. Event unauthorized</small> |
| <a id="DOC000056"></a>`DOC000056` | 400 | **Bad Request**<br/>Evento {event} recebido mas não processado<br/><small>Event {event} received but cannot be processed</small> |
| <a id="DOC000057"></a>`DOC000057` | 422 | **Unprocessable Entity**<br/>Não foi possível encontrar 'ziped_file_url' ('document' -> 'downloads' -> 'ziped_file_url') na request<br/><small>Unable to retrieve 'ziped_file_url' ('document' -> 'downloads' -> 'ziped_file_url') from request</small> |
| <a id="DOC000058"></a>`DOC000058` | 400 | **Bad Request**<br/>Favor fornecer o tipo do documento<br/><small>Please provide document_type</small> |
| <a id="DOC000059"></a>`DOC000059` | 400 | **Bad Request**<br/>Use POST /edit_signer/{document_key} |
| <a id="DOC000060"></a>`DOC000060` | 404 | **Not Found**<br/>Não foi possível encontrar o documento {document_key}<br/><small>Could not find any of the following document {document_key}</small> |
| <a id="DOC000061"></a>`DOC000061` | 400 | **Bad Request**<br/>Edição de assinante não disponível para {certifier}.<br/><small>Edit signerfor {certifier} is not available.</small> |
| <a id="DOC000062"></a>`DOC000062` | 400 | **Bad Request**<br/>Não foi possível fazer o upload porque o arquivo está vazio.<br/><small>Could not upload file because it's empty.</small> |
| <a id="DOC000063"></a>`DOC000063` | 400 | **Bad Request**<br/>document_key ou document_batch_key é obrigatória para auto assinar eventos. Por favor envie um deles dentro dos params da request.<br/><small>document_key or document_batch_key is required to auto sign events. Please send one of them inside request params</small> |
| <a id="DOC000064"></a>`DOC000064` | 400 | **Bad Request**<br/>A chave control_number enviada já está em uso {control_number}<br/><small>control_number is already in use {control_number}</small> |
| <a id="DOC000065"></a>`DOC000065` | 400 | **Bad Request**<br/>Documento não foi informado<br/><small>Document was not informed</small> |
| <a id="DOC000066"></a>`DOC000066` | 400 | **Bad Request**<br/>Nome do documento '{document_name}' já existe<br/><small>Document name '{document_name}' already exist</small> |
| <a id="DOC000067"></a>`DOC000067` | 400 | **Bad Request**<br/>Arquivo pdf não encontrado<br/><small>Pdf file not found</small> |
| <a id="DOC000068"></a>`DOC000068` | 500 | **Internal Error**<br/>Erro de concorrencia. Arquivo não encontrado {file_name}<br/><small>Concurrency error! File not found {file_name}</small> |
| <a id="DOC000069"></a>`DOC000069` | 400 | **Bad Request**<br/>Número de telefone não informado para o método de assinatura escolhido.<br/><small>Missing phone number for the chosen signature method.</small> |
| <a id="DOC000070"></a>`DOC000070` | 400 | **Bad Request**<br/>O arquivo PDF está truncado ou quebrado.<br/><small>The PDF file is truncated or broken.</small> |
| <a id="DOC000071"></a>`DOC000071` | 400 | **Bad Request**<br/>Erro na validação do documento. Essa informação precisa ter exatamente {digits}. Document: {document}<br/><small>Error on document check. This information should have exactly {digits} digits. Document: {document}</small> |
| <a id="DOC000072"></a>`DOC000072` | 400 | **Bad Request**<br/>Erro na Verificação do e-mail. Formato invalido: {email}<br/><small>Error on email check. Email format invalid Email: {email}</small> |
| <a id="DOC000073"></a>`DOC000073` | 400 | **Bad Request**<br/>A provided role ({role}) não é uma das validas: {allowed_roles}<br/><small>The provided role ({role}) is not one of the valid one`s: {allowed_roles}</small> |
| <a id="DOC000074"></a>`DOC000074` | 400 | **Bad Request**<br/>Um click_sign_file_path deve ser informado.<br/><small>A click_sign_file_path must be provided.</small> |
| <a id="DOC000075"></a>`DOC000075` | 400 | **Bad Request**<br/>Pelo menos os parâmetros email, phone_number ou is_api devem ser informados.<br/><small>At least the email, phone_number or is_api parameters should be provided.</small> |
| <a id="DOC000076"></a>`DOC000076` | 400 | **Bad Request**<br/>O método de assinatura registrado no signatário não corresponde a nenhum email or sms.<br/><small>Signature method registered on signatory does not match any of email or sms.</small> |
| <a id="DOC000077"></a>`DOC000077` | 400 | **Bad Request**<br/>O arquivo PDF não pode conter senha.<br/><small>PDF file can't have a password.</small> |
| <a id="DOC000078"></a>`DOC000078` | 400 | **Bad Request**<br/>Arquivo não encontrado<br/><small>File not found</small> |
| <a id="DOC000079"></a>`DOC000079` | 400 | **Invalid Template**<br/>Erro de escrita no template. Linha:{line} Erro:{error_msg}<br/><small>Template syntax error. Line:{line} Error:{error_msg}</small> |
| <a id="DOC000080"></a>`DOC000080` | 400 | **Invalid Template**<br/>Erro no template. Erro:{error_msg}<br/><small>Template error. Error:{error_msg}</small> |
| <a id="DOC000081"></a>`DOC000081` | 400 | **Invalid document type**<br/>{document_type} não é um tipo de documento valido.<br/><small>{document_type} is not a valid document type.</small> |
| <a id="DOC000082"></a>`DOC000082` | 400 | **Bad Request**<br/>Payload de webhook de assinatura não pode ser nulo.<br/><small>Signature webhook payload should not be null.</small> |
| <a id="DOC000083"></a>`DOC000083` | 400 | **Invalid signature key**<br/>Chave de assinatura da QiSign invalida..<br/><small>Invalid QiSign signature key.</small> |
| <a id="DOC000084"></a>`DOC000084` | 400 | **Invalid webhook status**<br/>Status invalido no webhook da QISign recebido.<br/><small>Invalid status received in QiSign webhook.</small> |
| <a id="DOC000085"></a>`DOC000085` | 400 | **Signed document not found**<br/>Documento assinado não encontrado na QiSign.<br/><small>Signed document not found in QiSign.</small> |
| <a id="DOC000086"></a>`DOC000086` | 400 | **Bad Request**<br/>É necessário enviar o pdf assinado<br/><small>It is necessary to send the signed pdf</small> |
| <a id="DOC000087"></a>`DOC000087` | 400 | **Bad Request**<br/>Não foi possível renderizar o PDF. O HTML pode estar inválido.<br/><small>Could not render PDF. HTML may be malformed.</small> |
| <a id="DOC000088"></a>`DOC000088` | 400 | **Bad Request**<br/>Somente arquivos com conteúdo do tipo pdf podem ser enviados.<br/><small>Only file with pdf content type can be sent.</small> |
| <a id="DOC000089"></a>`DOC000089` | 400 | **Bad Request**<br/>Número de documento inválido. Não foi possível enviar o documento para o clicksign.<br/><small>Document number invalid. Not possible to send the document to the clicksign .</small> |
| <a id="DOC000090"></a>`DOC000090` | 400 | **Bad Request**<br/>Erro durante o envio do documento para o clicksing.<br/><small>Error while sending document to the clicksing.</small> |
| <a id="DOC000091"></a>`DOC000091` | 400 | **Bad Request**<br/>O solicitante do documento precisa ter uma configuração para usar esta certificadora. Por favor, entre em contato com o suporte.<br/><small>Document requester must have a configuration to use this certifier. Please contact support.</small> |
| <a id="DOC000092"></a>`DOC000092` | 400 | **Bad Request**<br/>Status invalido para processar documento ({document_key}) no subscriber {subscriber_name}. Status atual {document_status}.<br/><small>Invalid Status to process document ({document_key}) in {subscriber_name} subscriber. Actual status: {document_status}.</small> |
| <a id="DOC000093"></a>`DOC000093` | 400 | **Bad Request**<br/>O documento assinado e o documento original devem ser arquivos diferentes.<br/><small>Signed document and original document must be different files.</small> |
| <a id="DOC000094"></a>`DOC000094` | 400 | **Bad Request**<br/>Configuração da certificadora não encontrada.<br/><small>Certifier configuration not found.</small> |
| <a id="DOC000095"></a>`DOC000095` | 400 | **Bad Request**<br/>Assinante ja existe para o número de documento informado.<br/><small>Signer already exists for informed document number.</small> |
| <a id="DOC000096"></a>`DOC000096` | 400 | **Bad Request**<br/>Assinantenão encontrado para o número de documento informado.<br/><small>Signer not found for informed document number.</small> |
| <a id="DOC000097"></a>`DOC000097` | 412 | **Document Batch Error**<br/>Documentos dentro do Lote de Documentos possuem donos, assinantes ou certificadoras distintas.<br/><small>Documents inside document_batch has differents owners, signers or certifiers.</small> |
| <a id="DOC000098"></a>`DOC000098` | 400 | **Bad Request**<br/>Não foi possível acessar URL externa para baixar o PDF assinado.<br/><small>Cannot acess external URL to download signed PDF.</small> |
| <a id="DOC000099"></a>`DOC000099` | 400 | **Bad Request**<br/>URL ou Chave do Template deve ser enviado para o upload.<br/><small>URL or Template Key must be provided for upload.</small> |
| <a id="DOC000100"></a>`DOC000100` | 400 | **Bad Request**<br/>Arquivo muito grande. Tamanho máximo do arquivo: {max_size} bytes. Tamanho do arquivo: {file_size} bytes.<br/><small>File too large. Maximum file size: {max_size} bytes. Uploaded file size: {file_size} bytes</small> |
| <a id="DOC000101"></a>`DOC000101` | 400 | **Bad Request**<br/>Documentos dentro do lote de documentos possuem assinantes distintos.<br/><small>Documents inside document_batch has different signers.</small> |
| <a id="DOC000102"></a>`DOC000102` | 400 | **Bad Request**<br/>Dono não encontrado.<br/><small>Owner not found.</small> |

### FGTS — Antecipação de Saque Aniversário

42 erros

| Código | HTTP | Mensagem |
|-|-|-|
| <a id="FGTS00003"></a>`FGTS00003` | 404 | **Not Found**<br/>A chave reservation_request_key {key} não pode ser encontrada.<br/><small>The given reservation_request_key {key} could not be found.</small> |
| <a id="FGTS00004"></a>`FGTS00004` | 404 | **Not Found**<br/>A chave external_key {key} não pode ser encontrada.<br/><small>The given external_key {key} could not be found.</small> |
| <a id="FGTS00005"></a>`FGTS00005` | 400 | **Bad Request**<br/>Status<br/><small>Credit Operation status</small> |
| <a id="FGTS00007"></a>`FGTS00007` | 504 | **Gateway Time-out**<br/>O servidor não respondeu a tempo<br/><small>The server did not respond in time</small> |
| <a id="FGTS00008"></a>`FGTS00008` | 400 | **Bad Request**<br/>Os servidores da Caixa não responderam no tempo determinado. Tente novamente em alguns<br/><small>Caixa server did not respond in time. Try again in a few seconds.</small> |
| <a id="FGTS00009"></a>`FGTS00009` | 400 | **Bad Request**<br/>Os servidores da Caixa não responderam com um token válido. Tente novamente em alguns<br/><small>Caixa server did not respond with a valid token. Try again in a few seconds.</small> |
| <a id="FGTS00010"></a>`FGTS00010` | 400 | **Bad Request**<br/>Os servidores da Caixa retornaram um erro.<br/><small>Caixa server returned an error.</small> |
| <a id="FGTS00011"></a>`FGTS00011` | 500 | **Internal Error**<br/>Os servidores da cache retornaram um erro.<br/><small>Cache server returned an error.</small> |
| <a id="FGTS00012"></a>`FGTS00012` | 400 | **Bad Request**<br/>Reserva já está desaverbada.<br/><small>Reservation is already closed.</small> |
| <a id="FGTS00014"></a>`FGTS00014` | 429 | **Too Many Requests**<br/>Taxa limite para o documento {document_number} excedeu o máximo de {limit_per_hour} requisições com erro em 15 minutos. Retentar às {retry_at} UTC.<br/><small>Rate limit for document {document_number} exceeded the max of {limit_per_hour} failed requests per 15 minutes. Retry at UTC {retry_at}</small> |
| <a id="FGTS00017"></a>`FGTS00017` | 401 | **Unauthorized**<br/>Ação não permitida para cargo: {role}<br/><small>Action not allowed for role: {role}</small> |
| <a id="FGTS00020"></a>`FGTS00020` | 400 | **Bad Request**<br/> |
| <a id="FGTS00022"></a>`FGTS00022` | 400 | **Bad Request**<br/>Reserva com status<br/><small>Reservation status</small> |
| <a id="FGTS00023"></a>`FGTS00023` | 400 | **Bad Request**<br/>Reserva já em processo de desaverbação<br/><small>Reservation already in closure process. Key: {reservation_request_key}</small> |
| <a id="FGTS00024"></a>`FGTS00024` | 404 | **Not Found**<br/>O periodo nao pôde ser encontrado<br/><small>The period could not be found</small> |
| <a id="FGTS00025"></a>`FGTS00025` | 409 | **Reservation Status Conflict**<br/>Essa reserva não permite essa atualização de estados<br/><small>A reservation {reservation_key} with status {old_status} cannot be updated to {new_status}</small> |
| <a id="FGTS00026"></a>`FGTS00026` | 409 | **Reservation Status Conflict**<br/>Reservas no status<br/><small>Reservation with status</small> |
| <a id="FGTS00027"></a>`FGTS00027` | 404 | **Not Found**<br/>A solitação de saldo {key} não pode ser encontrada.<br/><small>The given available_balance {key} could not be found.</small> |
| <a id="FGTS00028"></a>`FGTS00028` | 500 | **Periods Status Are Not all Equal**<br/>Reserva com a chave: {key}, possui periodos com status diferentes<br/><small>Reservation with key: {key}, have periods with different status.</small> |
| <a id="FGTS00029"></a>`FGTS00029` | 500 | **Unexpected Period Status**<br/>Reserva com a chave: {key}, possui periodos com estatus inesperados.<br/><small>Reservation with key: {key}, have periods in unexpected status.</small> |
| <a id="FGTS00030"></a>`FGTS00030` | 500 | **Invalid Next Period**<br/>Reserva com a chave: {key}, possui um periodo pago que não é o próximo período válido: {original_due_date}.<br/><small>Reservation with key: {key}, has a paid period that isn</small> |
| <a id="FGTS00031"></a>`FGTS00031` | 400 | **Access Token Too Many Retries**<br/>Tentou obter um novo token de acesso muitas vezes enquanto esperava um token de cache<br/><small>Tried to get a new access token too many times while waiting a cache token</small> |
| <a id="FGTS00032"></a>`FGTS00032` | 404 | **Protocol Not Found**<br/>O protocolo não pôde ser encontrado.<br/><small>The protocol could not be found.</small> |
| <a id="FGTS00033"></a>`FGTS00033` | 503 | **Unavailable service**<br/>O serviço da CEF se encontra indisponível no momento. Por favor, tente novamente mais tarde<br/><small>The CEF service is currently unavailable. Please, try again later</small> |
| <a id="FGTS00034"></a>`FGTS00034` | 404 | **Available Balance To Requester Not Found**<br/>A consulta de saldo não pertence ao solicitante {requester_key}.<br/><small>Available Balance does not belong to the requester {requester_key}.</small> |
| <a id="FGTS00035"></a>`FGTS00035` | 409 | **Available Balance Status Conflict**<br/>Consulta de saldo com processo concluído não pode ter seu status alterado<br/><small>Balance inquiry with completed process cannot have its status changed</small> |
| <a id="FGTS00036"></a>`FGTS00036` | 429 | **Rate Limit Exceeded**<br/>O número de requisições excedeu o limite da CEF<br/><small>Number of requisitions exceeded the CEF rate limit</small> |
| <a id="FGTS00037"></a>`FGTS00037` | 400 | **Path Param Is Incorrect**<br/>O parâmetro de rota exigido precisa ser<br/><small>The required path param must be</small> |
| <a id="FGTS00038"></a>`FGTS00038` | 400 | **Payload Is Incorrect**<br/>Um payload deve ser enviado e ele não pode ser vazio<br/><small>A payload must be sent and cannot be empty</small> |
| <a id="FGTS00039"></a>`FGTS00039` | 408 | **The process exceeded the tolerance time**<br/>O processo excedeu o tempo de tolerância. Tente novamente<br/><small>The process exceeded the tolerance time. Try again</small> |
| <a id="FGTS00040"></a>`FGTS00040` | 404 | A fila {queue_name} não existe. Verifique se o nome da fila está correto.<br/><small>{queue_name} queue doesn</small> |
| <a id="FGTS00041"></a>`FGTS00041` | 409 | Já existe uma fila com o nome<br/><small>A queue with</small> |
| <a id="FGTS00042"></a>`FGTS00042` | 404 | O cliente {requester_key} não existe. Verifique se a chave do cliente está correta.<br/><small>The requester {requester_key} doesn</small> |
| <a id="FGTS00043"></a>`FGTS00043` | 400 | O cliente<br/><small>The requester</small> |
| <a id="FGTS00044"></a>`FGTS00044` | 403 | **Request not allowed at the moment**<br/>Esta solicitação não é permitida no momento. Por favor, tente novamente entre os dias 20 e 5 do mês, durante o horário das 22:00 (10 PM) às 07:00 (7 AM).<br/><small>This request is not allowed at the moment. Please try again between the 20th and 5th of the month, during the hours of 22:00 (10 PM) to 07:00 (7 AM).</small> |
| <a id="FGTS00045"></a>`FGTS00045` | 409 | **Period Status Conflict**<br/>O período<br/><small>The period</small> |
| <a id="FGTS00046"></a>`FGTS00046` | 409 | **Period Status Conflict**<br/>O período<br/><small>The period</small> |
| <a id="FGTS00047"></a>`FGTS00047` | 404 | **The reservation is not in status**<br/>A reserva não está no status<br/><small>The reservation is not in status</small> |
| <a id="FGTS00048"></a>`FGTS00048` | 409 | **Period Status Conflict**<br/>O período<br/><small>The period</small> |
| <a id="FGTS00049"></a>`FGTS00049` | 409 | **Reservation Already Locked**<br/>A reserva<br/><small>The reservation</small> |
| <a id="FGTS00401"></a>`FGTS00401` | 401 | **Unauthenticated User**<br/>Você precisa estar autenticado para realizar essa requisição.<br/><small>You need to be authenticated to send this request.</small> |
| <a id="FGTS00403"></a>`FGTS00403` | 404 | **Invalid Document Number Format**<br/>O número de documento {document_number} é inválido ou está mal formatado. Use apenas dígitos.<br/><small>The given document number {document_number} is invalid or malformed. Use only digits.</small> |

### FPL — Consignado Federal Siape

23 erros

| Código | HTTP | Mensagem |
|-|-|-|
| <a id="FPL000001"></a>`FPL000001` | 400 | **Bad Request**<br/>CPF {document_number} fornecido não é valido.<br/><small>Given {document_number} document number is invalid.</small> |
| <a id="FPL000002"></a>`FPL000002` | 400 | **Bad Request**<br/>O período da reserva deve ser maior que 0 e igual ao valor de períodos.<br/><small>Given reservation_period: {reservation_period}, must be greater than 0 and equal to the number of periods.</small> |
| <a id="FPL000003"></a>`FPL000003` | 400 | **Bad Request**<br/>Todos os períodos da reserva devem possuir valor igual ao valor reservado: {reservation_amount}<br/><small>All periods must have the amount equal to reservation amount: {reservation_amount}.</small> |
| <a id="FPL000004"></a>`FPL000004` | 400 | **Bad Request**<br/>Os períodos devem possuir data superior a hoje.<br/><small>Periods due date must be grater than today.</small> |
| <a id="FPL000006"></a>`FPL000006` | 400 | **Bad Request**<br/>Montante desenbolsado {disbursed_amount} não pode ser maior que a soma das parcelas {amount_payable}<br/><small>Amount disbursed {disbursed_amount} cannot be greater than the sum of the {amount_payable} installments</small> |
| <a id="FPL000007"></a>`FPL000007` | 400 | **Bad Request**<br/>Os períodos devem possuir datas em meses subsequentes.<br/><small>Periods due date must occur in sub sequent months.</small> |
| <a id="FPL000008"></a>`FPL000008` | 409 | **Reservation Status Conflict**<br/>Reservas no status<br/><small>Reservation with status</small> |
| <a id="FPL000009"></a>`FPL000009` | 400 | **Refinancing contract cannot be reverted**<br/>Contrato de refinanciamento não pode ser revertido após 7 dias úteis da reserva.<br/><small>Refinancing contract cannot be reverted after 7 working days from reservation.</small> |
| <a id="FPL000010"></a>`FPL000010` | 500 | **Product doesn**<br/>O produto requerido não existe.<br/><small>The requested product doesn</small> |
| <a id="FPL000012"></a>`FPL000012` | 404 | **Balance not Found**<br/>A consulta de saldo com chave {balance_key} não foi encontrada.<br/><small>Balance with key {balance_key} was not found.</small> |
| <a id="FPL000013"></a>`FPL000013` | 404 | **Reservation not Found**<br/>A reserva com chave {reservation_key} não foi encontrada.<br/><small>Reservation with key {reservation_key} was not found.</small> |
| <a id="FPL000014"></a>`FPL000014` | 404 | **External key not Found**<br/>A reserva com chave externa {external_key} não foi encontrada.<br/><small>Reservation with external key {external_key} was not found.</small> |
| <a id="FPL000015"></a>`FPL000015` | 409 |  |
| <a id="FPL000016"></a>`FPL000016` | 404 | **Contract not Found**<br/>Contrato {contract_number} não encontrado<br/><small>Contract {contract_number} not found</small> |
| <a id="FPL000018"></a>`FPL000018` | 404 | **Disbursemente Option not Found**<br/>Opção de desembolso para {disbursement_date} não foi encontrada.<br/><small>Disbursemente option for {disbursement_date} was not found.</small> |
| <a id="FPL000019"></a>`FPL000019` | - | Os servidores da cache retornaram um erro.<br/><small>Cache server returned an error.</small> |
| <a id="FPL000020"></a>`FPL000020` | 409 | **Conflict**<br/>Consulta de margem com status {status} não pode ser retentado.<br/><small>Balance Request with status {status} cannot be retried.</small> |
| <a id="FPL000021"></a>`FPL000021` | 400 | **Reservation status not permitted on refinancing**<br/>Reserva com a chave externa: {external_key}  está no status {status} que não é permitido para refinanciamento.<br/><small>Reservation with external_key: {external_key} is on status {status} which is not permitted for refinancing.</small> |
| <a id="FPL000022"></a>`FPL000022` | 404 | **Protocol not Found**<br/>Protocolo com chave {external_key} não foi encontrada.<br/><small>Protocol with key {external_key} was not found.</small> |
| <a id="FPL000023"></a>`FPL000023` | 400 | **Ivanlid protocol type**<br/>Protocolo do tipo {protocol_type} não existe.<br/><small>Protocol type {protocol_type} doesn</small> |
| <a id="FPL000024"></a>`FPL000024` | 400 | **Invalid Balance**<br/>A consulta de saldo com status {balance_status} não pode ser processada.<br/><small>Balance with status {balance_status} can</small> |
| <a id="FPL000025"></a>`FPL000025` | 500 | **Incorrect Refinanced Reservation.**<br/>O número de reservas refinanciadas está incorreto.<br/><small>The number of refinanced reservation is incorrect.</small> |
| <a id="FPL000026"></a>`FPL000026` | 400 | **Incorrect Reservation Status.**<br/>A reserva {reservation_key} está em um status incorreto para este fluxo -  status: {status_enumerator}.<br/><small>The reservation {reservation_key} is in an incorrect status for this flow - status: {status_enumerator}.</small> |

### GDF — Autenticação e Autorização

28 erros

| Código | HTTP | Mensagem |
|-|-|-|
| <a id="GDF000001"></a>`GDF000001` | 403 | **Permission Validation Error**<br/>Somente usuários master são permitidos<br/><small>Only master user's are allowed</small> |
| <a id="GDF000002"></a>`GDF000002` | 403 | **Permission Validation Error**<br/>Um SELECTED-AGENT deve ser fornecido<br/><small>A SELECTED-AGENT must be provided</small> |
| <a id="GDF000003"></a>`GDF000003` | 400 | **Bad Request**<br/>Nenhuma chave de API do cliente recebida<br/><small>No API Client Key received</small> |
| <a id="GDF000004"></a>`GDF000004` | 400 | **Bad Request**<br/>Corpo da request vazio<br/><small>Empty body received</small> |
| <a id="GDF000005"></a>`GDF000005` | 400 | **Bad Request**<br/>Cliente da API já criado para esta person_key<br/><small>API Client already created for this person_key</small> |
| <a id="GDF000006"></a>`GDF000006` | 400 | **Bad Request**<br/>allowed_endpoint duplicado<br/><small>Duplicated allowed_endpoint provided</small> |
| <a id="GDF000007"></a>`GDF000007` | 404 | **Not Found**<br/>Nenhuma ClientIntegration encontrada para client_integration_key: {client_integration_key}.<br/><small>No ClientIntegration found for client_integration_key: {client_integration_key} .</small> |
| <a id="GDF000008"></a>`GDF000008` | 400 | **Bad Request**<br/>Uma client_integration_key deve ser fornecida<br/><small>A client_integration_key must be provided</small> |
| <a id="GDF000009"></a>`GDF000009` | 400 | **Bad Request**<br/>Uma ação deve ser fornecida<br/><small>A action must be provided</small> |
| <a id="GDF000010"></a>`GDF000010` | 400 | **Bad Request**<br/>Ação não existe ({action_name}).<br/><small>Action doesnt exist ({action_name}).</small> |
| <a id="GDF000011"></a>`GDF000011` | 404 | **Not Found**<br/>Nenhuma ClientIntegration encontrada para client_integration_key / allowed_endpoint_key: {client_integration_key} / {allowed_endpoint_key}.<br/><small>No ClientIntegration found for client_integration_key / allowed_endpoint_key: {client_integration_key} / {allowed_endpoint_key}.</small> |
| <a id="GDF000012"></a>`GDF000012` | 404 | **Not Found**<br/>Nenhuma AllowedEndpoint encontrada para client_integration_key / allowed_endpoint_key: {client_integration_key} / {allowed_endpoint_key}.<br/><small>No AllowedEndpoint found for client_integration_key / allowed_endpoint_key: {client_integration_key} / {allowed_endpoint_key}.</small> |
| <a id="GDF000013"></a>`GDF000013` | 400 | **Bad Request**<br/>Uma chave allowed_endpoint_key deve ser fornecida<br/><small>A allowed_endpoint_key must be provided</small> |
| <a id="GDF000014"></a>`GDF000014` | 401 | **QI Unauthenticated**<br/>Por favor forneça credenciais válidas como parte da request. (Documentação: https://docs.qitech.com.br) Detalhes: {details_br}<br/><small>Please provide valid credentials as part of the request. (Documentation: https://docs.qitech.com.br) Details: {details}</small> |
| <a id="GDF000015"></a>`GDF000015` | 400 | **Bad Request**<br/>Por favor forneça uma chave pública válida<br/><small>Please provide a valid client_public_key</small> |
| <a id="GDF000016"></a>`GDF000016` | 400 | **Bad Request**<br/>Erro ao decodificar o JSON do corpo da requisição. Por favor verifique se o corpo é válido. Detalhes: {json_ex}<br/><small>Error while decoding request's JSON body. Please verify if body is valid. Details: {json_ex}</small> |
| <a id="GDF000017"></a>`GDF000017` | 400 | **Bad Request**<br/>Valor inválido ({info}).<br/><small>Invalid Value ({info}).</small> |
| <a id="GDF000018"></a>`GDF000018` | 404 | **Not Found**<br/>Nenhuma ClientIntegration encontrada para api_client_key: {api_client_key}.<br/><small>No ClientIntegration found for api_client_key: {api_client_key}.</small> |
| <a id="GDF000019"></a>`GDF000019` | 400 | **Bad Request**<br/>Mapeamento ainda inexistente para request_type: '{request_type}'.<br/><small>Informed request_type: '{request_type}' has not been mapped yet.</small> |
| <a id="GDF000020"></a>`GDF000020` | 500 | **Internal Error**<br/>Account Key não pode ser nulo quando solicitar uma inclusão de chave.<br/><small>Account Key can't be null when including pix key.</small> |
| <a id="GDF000021"></a>`GDF000021` | 500 | **Internal Error**<br/>Falha na requisição para autorização de SCR.<br/><small>Failed to request SCR authorization.</small> |
| <a id="GDF000022"></a>`GDF000022` | 400 | **Bad Request**<br/>Mapeamento ainda inexistente para request_type: '{request_type}'.<br/><small>Informed request_type: '{request_type}' has not been mapped yet.</small> |
| <a id="GDF000023"></a>`GDF000023` | 401 | **Unauthorized**<br/>SSL validation error<br/><small>Error na verificação SSL</small> |
| <a id="GDF000024"></a>`GDF000024` | 400 | **Bad Request**<br/>Error at client webhook endpoint<br/><small>Error no endpoint de webhook do cliente</small> |
| <a id="GDF000025"></a>`GDF000025` | 403 | **Permission Validation Error**<br/>Somente os ambientes de desenvolvimento e de sandbox são permitidos para realizar requisições na Mock API.<br/><small>Only sandbox and dev environment are allowed to request Mock API</small> |
| <a id="GDF000026"></a>`GDF000026` | 400 | **Bad Request**<br/>Versão do método de assinatura não permitida<br/><small>Signature method version not allowed</small> |
| <a id="GDF000027"></a>`GDF000027` | 404 | **Not Found**<br/>Nenhuma ClientIntegration encontrada para a person_key: {person_key}.<br/><small>No ClientIntegration found for person_key: {person_key}.</small> |
| <a id="GDF000028"></a>`GDF000028` | 404 | **Not Found**<br/>A requisição precisa de um body, mesmo que um vazio como: '{}'.<br/><small>The request needs a body, even an empty one like: '{}'.</small> |

### LEG — Lego

155 erros

| Código | HTTP | Mensagem |
|-|-|-|
| <a id="LEG000001"></a>`LEG000001` | 400 | **Bad Request**<br/>Use POST /configuration |
| <a id="LEG000002"></a>`LEG000002` | 400 | **Bad Request**<br/>Request não é interna<br/><small>Request is not internal</small> |
| <a id="LEG000003"></a>`LEG000003` | 400 | **Configuration Error**<br/>Já existe uma configuração para a pessoa: {person_key} no endpoint: {endpoint}. Para alterar uma configuração, use PUT /configuration<br/><small>A configuration already exists for the person: {person_key} on the endpoint: {endpoint}. To change a configuration use PUT /configuration</small> |
| <a id="LEG000004"></a>`LEG000004` | 400 | **Bad Request**<br/>Nenhum selected-agent fornecido<br/><small>No selected-agent provided</small> |
| <a id="LEG000005"></a>`LEG000005` | 400 | **Configuration Error**<br/>Nenhuma configuração encontrada para a pessoa: {person_key} no endpoint: {endpoint}. Para registrar uma nova, use POST / configuration<br/><small>No configuration found for the person: {person_key} on the endpoint: {endpoint}. To register a new one, use POST /configuration</small> |
| <a id="LEG0000057"></a>`LEG0000057` | 400 | **Bad Request**<br/>A operation_key recebida já está registrada para outra operação. Por favor, envie uma key não utilizada.<br/><small>Received operation_key already registered for another operation. Please send a new one.</small> |
| <a id="LEG000006"></a>`LEG000006` | 400 | **Configuration Error**<br/>Multiplas configurações encontradas para a pessoa: {person_key} no endpoint: {endpoint}. Por favor entre em contato com o administrador<br/><small>Multiple configurations found for the person: {person_key} on the endpoint: {endpoint}. Please contact the system administrator.</small> |
| <a id="LEG000007"></a>`LEG000007` | 400 | **Configuration Error**<br/>Chave da configuração não fornecida.<br/><small>No configuration key provided.</small> |
| <a id="LEG000008"></a>`LEG000008` | 404 | **Configuration Error**<br/>Nenhuma configuração encontrada para a configuration_key: {configuration_key}.<br/><small>No configuration found for the configuration_key: {configuration_key}</small> |
| <a id="LEG000009"></a>`LEG000009` | 404 | **Configuration Error**<br/>Nenhuma configuração encontrada para a pessoa: {person_key}.<br/><small>No configuration found for person: {person_key}</small> |
| <a id="LEG000010"></a>`LEG000010` | 400 | **Bad Request**<br/>A ação é nula<br/><small>Action is null</small> |
| <a id="LEG0000100"></a>`LEG0000100` | 400 | **Bad Request**<br/>Falha ao validar contrato na dataprev, tente novamente.<br/><small>Failed to check contract in dataprev. Please try again.</small> |
| <a id="LEG0000101"></a>`LEG0000101` | 400 | **Bad Request**<br/>Status inválido para solicão de abertura de conta. Status enviado {account_status}.<br/><small>Invalid status response for checking account request. Status sent {account_status}.</small> |
| <a id="LEG0000102"></a>`LEG0000102` | 400 | **Bad Request**<br/>Chave pix inválida. Chave enviada {pix_key}. Por favor entre em contato.<br/><small>Invalid pix_key. Pix key sent {pix_key}. Please contact support</small> |
| <a id="LEG0000103"></a>`LEG0000103` | 400 | **Bad Request**<br/>Chave pix inválida comprimento do email. Chave enviada {pix_key}. Email não deve ultrapassar 72 caracteres.<br/><small>Invalid pix_key email lenght. Pix key sent {pix_key}. Email must not exceed 72 chars.</small> |
| <a id="LEG0000104"></a>`LEG0000104` | 400 | **Bad Request**<br/>Chave pix inválida email. Chave enviada {pix_key}. Email não deve conter espaços.<br/><small>Invalid pix_key email type. Pix key sent {pix_key}. Email must not contains white space.</small> |
| <a id="LEG0000105"></a>`LEG0000105` | 400 | **Bad Request**<br/>Chave pix inválida email. Chave enviada {pix_key}. Email deve conter apenas caracteres minúsculos.<br/><small>Invalid pix_key email type. Pix key sent {pix_key}. Email must only contains lower chars .</small> |
| <a id="LEG0000106"></a>`LEG0000106` | 400 | **Bad Request**<br/>Chave pix inválida. Chave enviada {pix_key}. Telefone deve ser no formato internacional<br/><small>Invalid pix_key. Pix key sent {pix_key}. Phone must been in internacional format</small> |
| <a id="LEG0000107"></a>`LEG0000107` | 400 | **Bad Request**<br/>Chave pix inválida. Chave enviada {pix_key}. Documentos não devem conter caracteres especiais.<br/><small>Invalid pix_key. Pix key sent {pix_key}. Documents must not contains special chars.</small> |
| <a id="LEG0000108"></a>`LEG0000108` | 400 | **Bad Request**<br/>Chave pix inválida. Chave enviada {pix_key}. Documentos devem ser válidos.<br/><small>Invalid pix_key. Pix key sent {pix_key}. Documents must be valid.</small> |
| <a id="LEG0000109"></a>`LEG0000109` | 400 | **Bad Request**<br/>Chave pix inválida. Chave enviada {pix_key}. Chave aletória deve ser um uuid4 válido.<br/><small>Invalid pix_key. Pix key sent {pix_key}. Random key must be a valid uuid4</small> |
| <a id="LEG000011"></a>`LEG000011` | 400 | **Bad Request**<br/>Ação inválida<br/><small>Invalid action</small> |
| <a id="LEG0000110"></a>`LEG0000110` | 400 | **Bad Request**<br/>Operação cancelada não pode ser assinada.<br/><small>Operation canceled cannot be signed.</small> |
| <a id="LEG0000111"></a>`LEG0000111` | 400 | **Bad Request**<br/>O campo 'type' não pode ser nulo e deve conter um dos valores ('data-signature', 'pdf-signature')<br/><small>Field 'type' cannot be null and must contain one of the values ('data-signature', 'pdf-signature')</small> |
| <a id="LEG0000112"></a>`LEG0000112` | 400 | **Bad Request**<br/>Url enviada não é válida {url}<br/><small>Invalid url {url}</small> |
| <a id="LEG0000113"></a>`LEG0000113` | 400 | **Bad Request**<br/>Número Compe inválido. Valor de número compe: {financial_institution_code} não existe.<br/><small>Invalid code number. Value financial institution code: {financial_institution_code} does not exist.</small> |
| <a id="LEG0000114"></a>`LEG0000114` | 400 | **Bad Request**<br/>Foram encontradas parcelas com valor total menor que o mínimo de R$ 1,00.<br/><small>Found installments with total amount below the minimum of R$ 1,00</small> |
| <a id="LEG0000115"></a>`LEG0000115` | 400 | **Bad Request**<br/>É necessário informar no mínimo uma parcela<br/><small>It is necessary to inform at least one installment</small> |
| <a id="LEG0000116"></a>`LEG0000116` | 400 | **Bad Request**<br/>A operação atual não permite confirmação da reserva.<br/><small>Reserve confirmation is not possibile in current operation step.</small> |
| <a id="LEG0000117"></a>`LEG0000117` | 400 | **Bad Request**<br/>A operação atual não permite assinatura.<br/><small>Signature is not possibile in current operation step.</small> |
| <a id="LEG0000118"></a>`LEG0000118` | 400 | **Bad Request**<br/>Ignorando evento por quê não está nos status permitidos.<br/><small>Ignoring event because is not in allowed status.</small> |
| <a id="LEG0000119"></a>`LEG0000119` | 400 | **Bad Request**<br/>A operação não pode ser desembolsada antes de ser assinada<br/><small>Operation cannot be disbursed before it is signed.</small> |
| <a id="LEG000012"></a>`LEG000012` | 400 | **Bad Request**<br/>Falta chave da simulação de dívida<br/><small>Missing simulation debt key</small> |
| <a id="LEG0000120"></a>`LEG0000120` | 400 | **Bad Request**<br/>O brick está em 'dataprev_reservation_check', mas o webhook recebido é de desembolso.<br/><small>Brick flow step is 'dataprev_reservation_check', but received webhook is 'opened'.</small> |
| <a id="LEG0000121"></a>`LEG0000121` | 400 | **Bad Request**<br/>Operações que não estão canceladas não podem processar o webhook de cancelamento permanente.<br/><small>Operation that is not canceled cannot process cancel permanently webhook.</small> |
| <a id="LEG0000122"></a>`LEG0000122` | 400 | **Bad Request**<br/>Tarifa não permitida<br/><small>Contract Fee not permitted</small> |
| <a id="LEG0000123"></a>`LEG0000123` | 400 | **Bad Request**<br/>Status do evento ({event_status}) ou tipo de evento ({event_type}) inválidos para processar o brick.<br/><small>Invalid event_status ({event_status}) or event_type ({event_type}) to process brick.</small> |
| <a id="LEG000013"></a>`LEG000013` | 404 | **Not Found**<br/>Operação não encontrada para chave {debt_key}<br/><small>No operation found for key {debt_key}</small> |
| <a id="LEG000014"></a>`LEG000014` | 400 | **Bad Request**<br/>A chave {debt_key} não pertence a nenhuma operação do cliente {selected_agent}<br/><small>Key {debt_key} doesn't belong to any operation of client {selected_agent}</small> |
| <a id="LEG000015"></a>`LEG000015` | 400 | **Bad Request**<br/>Nenhuma chave de operação (operation_key) fornecida<br/><small>No operation_key provided</small> |
| <a id="LEG000016"></a>`LEG000016` | 404 | **Not Found**<br/>Operação não encontrada para chave de operação {operation_key}<br/><small>No operation found for the given operation_key {operation_key}</small> |
| <a id="LEG000017"></a>`LEG000017` | 400 | **Bad Request**<br/>Nenhuma relação encontrada para a pessoa especificada {person_key} e operação {operation_key}<br/><small>No relationship found for the given person {person_key} and operation {operation_key}</small> |
| <a id="LEG000018"></a>`LEG000018` | 400 | **Bad Request**<br/>A chave fornecida {operation_key} não está relacionada à operação {endpoint}. Por favor, use o endpoint apropriado<br/><small>The given key {operation_key} isn`t related to {endpoint} operation. Please use the appropriate endpoint</small> |
| <a id="LEG000019"></a>`LEG000019` | 400 | **Bad Request**<br/>Método {method} não permitido para o endpoint {endpoint}<br/><small>Method {method} not allowed for the endpoint {endpoint}</small> |
| <a id="LEG000020"></a>`LEG000020` | 400 | **Bad Request**<br/>Chave do documento (document_key) faltando, use GET /document/{document_key}<br/><small>Missing document_key, use GET /document/{document_key}</small> |
| <a id="LEG000021"></a>`LEG000021` | 404 | **Bad Request**<br/>Documento não encontrado para chave {document_key}<br/><small>Document not found for key {document_key}</small> |
| <a id="LEG000022"></a>`LEG000022` | 400 | **Bad Request**<br/>Para acessar informações de um documento, use GET /document/{document_key}<br/><small>To get document information, use GET /document/{document_key}</small> |
| <a id="LEG000023"></a>`LEG000023` | 400 | **Bad Request**<br/>Tipo de MiME {document_mime_type} não suportado<br/><small>MiME type {document_mime_type} not supported</small> |
| <a id="LEG000024"></a>`LEG000024` | 400 | **Bad Request**<br/>Tipo de MiME e extensão do arquivo não batem<br/><small>File MIME type and extension don't match</small> |
| <a id="LEG000025"></a>`LEG000025` | 400 | **Bad Request**<br/>Ocorreu um erro ao tentar criar um documento na doc-api: nenhuma resposta recebida<br/><small>An error occurred when trying to create document on doc-api: no response received</small> |
| <a id="LEG000026"></a>`LEG000026` | 400 | **Bad Request**<br/>A pessoa {person_key} não é dona do documento {document_key}<br/><small>Person {person_key} doesn't own document {document_key}</small> |
| <a id="LEG000027"></a>`LEG000027` | 400 | **Bad Request**<br/>A operação {operation_key} não pertence à pessoa {person_key}<br/><small>Operation key {operation_key} doesn't belong to requester {person_key}</small> |
| <a id="LEG000028"></a>`LEG000028` | 400 | **Bad Request**<br/>A chave fornecida {} não está relacionada a uma operação de crédito<br/><small>The given key {operation_key} is not related to a credit operation</small> |
| <a id="LEG000029"></a>`LEG000029` | 400 | **Bad Request**<br/>O status da operação {operation_key} é {credit_operation_status} e ainda não foi emitido<br/><small>Operation {operation_key} status is {credit_operation_status} and has not been issued yet</small> |
| <a id="LEG000030"></a>`LEG000030` | 400 | **Bad Request**<br/>Operação {operation_key} está {credit_operation_status}<br/><small>Operation {operation_key} is {credit_operation_status}</small> |
| <a id="LEG000031"></a>`LEG000031` | 400 | **Bad Request**<br/>Falta compliance_document_keys<br/><small>Missing compliance_document_keys</small> |
| <a id="LEG000032"></a>`LEG000032` | 404 | **Not Found**<br/>Nenhum documento foi encontrado para o compliance_document_key fornecido: {compliance_document_key}<br/><small>No document was found for the given compliance_document_key: {compliance_document_key}</small> |
| <a id="LEG000033"></a>`LEG000033` | 500 | **Configuration Error**<br/>Há um problema com sua configuração. Entre em contato com a administração do sistema<br/><small>There is a problem with your configuration. Please contact system administration</small> |
| <a id="LEG000034"></a>`LEG000034` | 400 | **Bad Request**<br/>Tipo de divisão mista entre valor e percentual<br/><small>Found mix of split type amount and percentage</small> |
| <a id="LEG000035"></a>`LEG000035` | 400 | **Bad Request**<br/>Para várias contas, você deve especificar os valores divididos<br/><small>For multiple accounts you must specify the split amounts</small> |
| <a id="LEG000036"></a>`LEG000036` | 400 | **Bad Request**<br/>Operação ({operation_key}) cancelada<br/><small>Operation ({operation_key}) status is cancelled</small> |
| <a id="LEG000037"></a>`LEG000037` | 400 | **Bad Request**<br/>Status não implementado<br/><small>Status not implemented</small> |
| <a id="LEG000038"></a>`LEG000038` | 400 | **Bad Request**<br/>Bloco {brick_name} não existe.<br/><small>Brick {brick_name} doesnt exist.</small> |
| <a id="LEG000039"></a>`LEG000039` | 400 | **Bad Request**<br/>Número da conta: {account_number} com o dígito {branch_number} não encontrada<br/><small>Account number: {account_number} with branch {branch_number} not found</small> |
| <a id="LEG000040"></a>`LEG000040` | 400 | **Bad Request**<br/>A conta de liquidação {account_number} não pertence ao mutuário com o número do documento {borrower_document_number}<br/><small>Settlement account {account_number} does not belong to borrower with document number {borrower_document_number}</small> |
| <a id="LEG000041"></a>`LEG000041` | 400 | **Request Validator Error**<br/>Payload Inválido<br/><small>{description}</small> |
| <a id="LEG000042"></a>`LEG000042` | 400 | **Request Validator Error**<br/>Campo ausente document_number em disbursement_bank_accounts<br/><small>Missing field document_number on disbursement_bank_accounts</small> |
| <a id="LEG000043"></a>`LEG000043` | 400 | **Request Validator Error**<br/>Falta o nome do campo em disbursement_bank_accounts<br/><small>Missing field name on disbursement_bank_accounts</small> |
| <a id="LEG000044"></a>`LEG000044` | 400 | **Request Validator Error**<br/>A soma percentual_recebível de todas as disbursement_bank_accounts não pode ser maior que 100<br/><small>The percentage_receivable sum of all disbursement_bank_accounts can't be greater than 100</small> |
| <a id="LEG000045"></a>`LEG000045` | 400 | **Request Validator Error**<br/>A soma percentage_receivable de todas as disbursement_bank_accounts deve ser 100 se foi definida para todas as contas enviadas<br/><small>The percentage_receivable sum of all disbursement_bank_accounts must be 100 if it was set for all accounts sent</small> |
| <a id="LEG000046"></a>`LEG000046` | 400 | **Request Validator Error**<br/>contract_number já registrado. Por favor, use outro<br/><small>contract_number already registered. Please use another one</small> |
| <a id="LEG000047"></a>`LEG000047` | 400 | **Request Validator Error**<br/>allowed_user ausente para criação de conta PJ<br/><small>Missing allowed_user for legal account creation</small> |
| <a id="LEG000048"></a>`LEG000048` | 400 | **Bad Request**<br/>O requester_document_number fornecido ({document_number}) não é válido<br/><small>The provided requester_document_number ({document_number}) is not valid</small> |
| <a id="LEG000049"></a>`LEG000049` | 400 | **Bad Request**<br/>Nenhuma operation_key ou transaction_request_key fornecida<br/><small>No operation_key or transaction_request_key provided</small> |
| <a id="LEG000050"></a>`LEG000050` | 400 | **Bad Request**<br/>Operação não encontrada para a chave fornecida {operation_key}<br/><small>Operation not found for the given key {operation_key}.</small> |
| <a id="LEG000051"></a>`LEG000051` | 400 | **Bad Request**<br/>A operação não pode ser emitida antes de ser assinada<br/><small>Operation cannot be issued before it is signed.</small> |
| <a id="LEG000052"></a>`LEG000052` | 400 | **Bad Request**<br/>O parâmetro action_type deve ser enviado.<br/><small>Must provide parameter action_type.</small> |
| <a id="LEG000053"></a>`LEG000053` | 400 | **Bad Request**<br/>Não é possível executar esta ação {action_type}<br/><small>Cannot perform this action {action_type}.</small> |
| <a id="LEG000054"></a>`LEG000054` | 400 | **Bad Request**<br/>Simulação inválida na requisição<br/><small>Invalid simulation within request</small> |
| <a id="LEG000055"></a>`LEG000055` | 400 | **Bad Request**<br/>Envie somente 'rebates' ou 'rebate' e/ou 'rebate_type'<br/><small>Provide either 'rebates' or 'rebate' and/or 'rebate_type'</small> |
| <a id="LEG000056"></a>`LEG000056` | 403 | **Unauthorized**<br/>O cliente não possui este item<br/><small>Client does not own this item</small> |
| <a id="LEG000058"></a>`LEG000058` | 400 | **Bad Request**<br/>Envie somente 'annual_interest_rate' ou 'monthly_interest_rate'<br/><small>Provide either 'annual_interest_rate' or 'monthly_interest_rate'</small> |
| <a id="LEG000059"></a>`LEG000059` | 400 | **Bad Request**<br/>Envie 'annual_interest_rate' quando o 'interest_type' for 'cdi_perc'<br/><small>Provide 'annual_interest_rate' when interest_type is 'cdi_perc'</small> |
| <a id="LEG000060"></a>`LEG000060` | 400 | **Bad Request**<br/>Parâmetro incorreto no body da request<br/><small>Wrong parameter on the request body</small> |
| <a id="LEG000061"></a>`LEG000061` | 401 | **Unauthorized**<br/>Payload inválido ou expirado<br/><small>Invalid or expired payload</small> |
| <a id="LEG000062"></a>`LEG000062` | 400 | **Bad Request**<br/>Operação esperando confirmação do evento de desembolso: Status recebido {operation_status}<br/><small>Operation is waiting disbursement confirmation. Status received: {operation_status}</small> |
| <a id="LEG000063"></a>`LEG000063` | 400 | **Bad Request**<br/>Status não aceito por parâmetros ausentes ou incorretos no corpo do retorno de chamada: {operation_status}<br/><small>Status not accepted by missing or wrong parameters on the callback body: {operation_status}</small> |
| <a id="LEG000064"></a>`LEG000064` | 400 | **Bad Request**<br/>Assignment não encontrado for key: {assignment_key}<br/><small>Assignment not found for key: {assignment_key}</small> |
| <a id="LEG000065"></a>`LEG000065` | 400 | **Bad Request**<br/>Parâmetro de assinatura ausente ou incorreto no body da request<br/><small>Missing or wrong signature parameter on the request body</small> |
| <a id="LEG000066"></a>`LEG000066` | 400 | **Bad Request**<br/>Operação {operation_key} já tem um endosso com status {endorsement_status}<br/><small>Operation {operation_key} already has a endorsement with status {endorsement_status}</small> |
| <a id="LEG000067"></a>`LEG000067` | 500 | **Internal Error**<br/>Erro ao gerar {errors}<br/><small>Error while generating {errors}</small> |
| <a id="LEG000068"></a>`LEG000068` | 400 | **Bad Request**<br/>Corpo da requisição inválido para simulações em lote.<br/><small>Invalid request body for batch simulation.</small> |
| <a id="LEG000069"></a>`LEG000069` | 400 | **Bad Request**<br/>Corpo da requisição inválido para simulação unitária.<br/><small>Invalid request body for single simulation.</small> |
| <a id="LEG000070"></a>`LEG000070` | 400 | **Bad Request**<br/>A operação de crédito {credit_operation_key} não pertence à pessoa {person_key}<br/><small>Credit Operation key {credit_operation_key} doesn't belong to requester {person_key}</small> |
| <a id="LEG000071"></a>`LEG000071` | 400 | **Bad Request**<br/>Não é possível desembolsar {target_disbursed_amount}, o máximo possível é {max_disbursed_amount}<br/><small>Cannot serve {target_disbursed_amount}, the max is {max_disbursed_amount}</small> |
| <a id="LEG000072"></a>`LEG000072` | 400 | **Bad Request**<br/>Falha ao validar hash MT. Razão: {reason}<br/><small>Failed validating MT hash. Reason: {reason}</small> |
| <a id="LEG000073"></a>`LEG000073` | 400 | **Bad Request**<br/>Status da operação {operation_key} não permite cancelamento.Status atual: {co_status}<br/><small>Operation {operation_key} actual status does not allow cancel operation. Actual status is {co_status}</small> |
| <a id="LEG000074"></a>`LEG000074` | 400 | **Bad Request**<br/>Devolução de Pix não é permitido para contas escrow<br/><small>Pix Chargeback is now allowed from escrow accounts.</small> |
| <a id="LEG000075"></a>`LEG000075` | 400 | **Bad Request**<br/>Conta {account_key} está fechada.<br/><small>Account {account_key} is closed.</small> |
| <a id="LEG000076"></a>`LEG000076` | 400 | **Bad Request**<br/>Conta {account_key} está bloqueada.<br/><small>Account {account_key} is blocked.</small> |
| <a id="LEG000077"></a>`LEG000077` | 403 | **Unauthorized**<br/>Usuário não tem permissão para realizar essa ação.<br/><small>User has no credentials to perform this action.</small> |
| <a id="LEG000078"></a>`LEG000078` | 400 | **Bad Request**<br/>Chave Pix e conta de destinos não podem ser ambos nulos.<br/><small>Pix key and target_account must not be null.</small> |
| <a id="LEG000079"></a>`LEG000079` | 400 | **Bad Request**<br/>Data de agendamento não pode ser menor que hoje.<br/><small>Schedule date can not be less than today.</small> |
| <a id="LEG000080"></a>`LEG000080` | 400 | **Bad Request**<br/>Conta de origem possui saldo negativo.<br/><small>Source Account has negative balance</small> |
| <a id="LEG000081"></a>`LEG000081` | 400 | **Bad Request**<br/>Conta de destino não permitida para essa conta escrow.<br/><small>Account destination not allowed for this escrow account.</small> |
| <a id="LEG000082"></a>`LEG000082` | 400 | **Bad Request**<br/>O documento de identificação do requester não pode ser nulo.<br/><small>Requester document identification can not be null</small> |
| <a id="LEG000083"></a>`LEG000083` | 400 | **Bad Request**<br/>Transferência Pix não encontrada para a pix_transfer_key {pix_transfer_key}.<br/><small>Pix Transfer not found for pix_transfer_key {pix_transfer_key}.</small> |
| <a id="LEG000084"></a>`LEG000084` | 400 | **Bad Request**<br/>O campo pix_transfer_key não deve ser nulo quando for uma devolução Pix.<br/><small>pix_transfer_key can not be null for chargeback</small> |
| <a id="LEG000085"></a>`LEG000085` | 400 | **Bad Request**<br/>Pix Key inválida.<br/><small>Invalid Pix Key.</small> |
| <a id="LEG000086"></a>`LEG000086` | 400 | **Bad Request**<br/>Conta para a account_key {account_key} não encontrada.<br/><small>Account for account key {account_key} not found.</small> |
| <a id="LEG000087"></a>`LEG000087` | 400 | **Bad Request**<br/>Valor da transação inválido<br/><small>Invalid decimal transaction amount</small> |
| <a id="LEG000088"></a>`LEG000088` | 400 | **Bad Request**<br/>Finalidade da transação deve ser transfer, payment_with_change or withdraw<br/><small>Transfer purpose must be one of transfer, payment_with_change or withdraw</small> |
| <a id="LEG000089"></a>`LEG000089` | 400 | **Bad Request**<br/>Quando o pix_transfer_type é static, dynamic_instant ou dynamic_term, end_to_end_id é obrigatório<br/><small>When pix_transfer_type is static, dynamic_instant or dynamic_term, end_to_end_id is required</small> |
| <a id="LEG000090"></a>`LEG000090` | 400 | **Bad Request**<br/>O Compliance não foi aprovado<br/><small>Compliance has not been approved</small> |
| <a id="LEG000091"></a>`LEG000091` | 400 | **Bad Request**<br/>O documento enviado {document_number} não é dono da conta de origem<br/><small>Given document number {document_number} is not source account owner.</small> |
| <a id="LEG000092"></a>`LEG000092` | 400 | **Bad Request**<br/>Payload inválida para a etapa de fluxo atual em operação {operation_key}.<br/><small>Invalid payload for current flow step in operation {operation_key}.</small> |
| <a id="LEG000093"></a>`LEG000093` | 400 | **Bad Request**<br/>Origem {origin} não esperada no fluxo da kyc<br/><small>Origin {origin} not expected for kyc flow.</small> |
| <a id="LEG000094"></a>`LEG000094` | 404 | **Bad Request**<br/>Documento de biometria facial não foi encontrado<br/><small>Facial Biometrics Document was not found</small> |
| <a id="LEG000095"></a>`LEG000095` | 423 | **Locked**<br/>TED está disponível entre {opening_time} e {closing_time}<br/><small>TED is available from {opening_time} to {closing_time}</small> |
| <a id="LEG000096"></a>`LEG000096` | 400 | **Bad Request**<br/>As taxas de juros prefixadas não foram cadastradas, favor entrar em contato.<br/><small>Prefixed interest rate not registered, please contact us.</small> |
| <a id="LEG000097"></a>`LEG000097` | 401 | **Unauthorized**<br/>Acesso negado para o cargo informado<br/><small>Access denied for informed role</small> |
| <a id="LEG000098"></a>`LEG000098` | 400 | **Bad Request**<br/>Formato de data inválido. Deve ser YYYY-MM-DD<br/><small>Invalid date format. Should be YYYY-MM-DD</small> |
| <a id="LEG000099"></a>`LEG000099` | 400 | **Bad Request**<br/>Número de parcelas desejadas deve ser igual ao número de parcelas<br/><small>Number of desired installments must be equal to number of installments</small> |
| <a id="LEG000124"></a>`LEG000124` | 400 | **Bad Request**<br/>Data de desembolso precisa ser hoje para desembolso sincrono.<br/><small>Disbursement date must be today for synchronous disbursement.</small> |
| <a id="LEG000125"></a>`LEG000125` | 400 | **Bad Request**<br/>Account key não enviada.<br/><small>Account key not sent.</small> |
| <a id="LEG000126"></a>`LEG000126` | 400 | **Bad Request**<br/>O status da operação de crédito: {co_status} não permite esta operação.<br/><small>Credit operation status: {co_status} does not allow this operation.</small> |
| <a id="LEG000127"></a>`LEG000127` | 400 | **Bad Request**<br/>A nova data de desembolso deve estar entre a data inicial de desembolso e a data final de desembolso.<br/><small>The new disbursement date must be between the disbursement start date and disbursement end date.</small> |
| <a id="LEG000128"></a>`LEG000128` | 400 | **Bad Request**<br/>Uma nova data de desembolso deve ser informada.<br/><small>A new valid disbursement date must be provided.</small> |
| <a id="LEG000129"></a>`LEG000129` | 400 | **Bad Request**<br/>Etapa não encontrada para configuralçao desta operação.<br/><small>Flow step not found for this operation configuration.</small> |
| <a id="LEG000130"></a>`LEG000130` | 400 | **Bad Request**<br/>Ação não permitida, porque a garantia não foi constituído. Credit Operation Key {credit_operation_key}<br/><small>Unable to do action, because collaterals are not constituted. Credit operation key {credit_operation_key};</small> |
| <a id="LEG000131"></a>`LEG000131` | 400 | **Bad Request**<br/>Ação não permitida, porque a entrada não foi paga. Credit Operation Key {credit_operation_key}<br/><small>Unable to do action, because entry is not paid. Credit operation key {credit_operation_key};</small> |
| <a id="LEG000132"></a>`LEG000132` | 400 | **Bad Request**<br/>A operação de crédito {credit_operation_key} não tem data de desembolso<br/><small>Credit Operation {credit_operation_key} has no disbursement_date</small> |
| <a id="LEG000133"></a>`LEG000133` | 400 | **Bad Request**<br/>Data da cessão deve ser maior ou igual à data de desembolso.<br/><small>Assignment date must be after or equal disbursement date.</small> |
| <a id="LEG000134"></a>`LEG000134` | 400 | **Bad Request**<br/>Conta com ducumento {document_number} não encontrada<br/><small>Account with document number: {document_number}</small> |
| <a id="LEG000135"></a>`LEG000135` | 400 | **Bad Request**<br/>Endereço de Ip inválido {ip_address} .<br/><small>Invalid Ip Address {ip_address} .</small> |
| <a id="LEG000136"></a>`LEG000136` | 400 | **Bad Request**<br/>Pre price não aceita parcelas personalizadas com percentual de amortização.<br/><small>Pre price do not accept custom installment with principal amortization percentage.</small> |
| <a id="LEG000137"></a>`LEG000137` | 400 | **Bad Request**<br/>'amount' ou 'disbursed_amount' deve ser informado.<br/><small>'amount' or 'disbursed_amount' must be informed.</small> |
| <a id="LEG000138"></a>`LEG000138` | 400 | **Bad Request**<br/>A ultima deve ter juros.<br/><small>Last installment must have interest.</small> |
| <a id="LEG000139"></a>`LEG000139` | 400 | **Bad Request**<br/>Porcentagem de Amortização pode ter no máximo 4 casas decimais.<br/><small>Amortization Percentage can have a maximum of 4 decimal places.</small> |
| <a id="LEG000140"></a>`LEG000140` | 400 | **Bad Request**<br/>Porcentagem da amotização principal não pode ser 0% se não há juros.<br/><small>Principal amortization percentage can not be 0 without interest.</small> |
| <a id="LEG000141"></a>`LEG000141` | 400 | **Bad Request**<br/>Valor total da porcentagem é {total}, deve ser 1<br/><small>Total amount of percentage is {total}, must be 1</small> |
| <a id="LEG000142"></a>`LEG000142` | 400 | **Bad Request**<br/>Valor de face da parcela não deve ser informado se a parcela possui porcentage de amortização.<br/><small>Installment face value must not be informed if installment has principal_amortization_percentage.</small> |
| <a id="LEG000143"></a>`LEG000143` | 400 | **Bad Request**<br/>Primeira data de vencimento não deve ser informada se a data de vencimento da parcela for informada.<br/><small>First due date should not be informed if the installment due date is informed.</small> |
| <a id="LEG000144"></a>`LEG000144` | 400 | **Bad Request**<br/>O valor de face da parcela não pode ser alterado porque não foi informado na requisição original.<br/><small>Installment face value cannot be changed because it was not informed in the original request.</small> |
| <a id="LEG000145"></a>`LEG000145` | 400 | **Bad Request**<br/>O desembolso passou de {limit_days} para reverter a operação.<br/><small>The disbursement has passed {limit_days} to reverse operation.</small> |
| <a id="LEG000146"></a>`LEG000146` | 400 | **Bad Request**<br/>A reversão é permitida apenas para desembolsos em conta interna.<br/><small>The reversal is allowed just for internal account disbursements.</small> |
| <a id="LEG000147"></a>`LEG000147` | 400 | **Bad Request**<br/>A soma do saldo das contas de desembolsos: {account_balance} deve ser igual ao valor desembolsado: {disbursed_issue_amount}.<br/><small>The sum of disbursement account balance: {account_balance} must be equal to disbursed issue amount: {disbursed_issue_amount}.</small> |
| <a id="LEG000148"></a>`LEG000148` | 400 | **Bad Request**<br/>A operação não pode ter mais de uma conta de desembolso pra criar a reversão.<br/><small>The operation cannot have more than one disbursement account to create the reversal.</small> |
| <a id="LEG000149"></a>`LEG000149` | 400 | **Bad Request**<br/>A operação não pode ser assinada antes de ter seu documento gerado.<br/><small>Operation cannot be signed before document is generated.</small> |
| <a id="LEG000150"></a>`LEG000150` | 400 | **Bad Request**<br/>Data de assinatura (signature_datetime) não está no formato esperado: YYYY-MM-DDTHH:MM:SSZ<br/><small>Signature datetime is not in the expected format: YYYY-MM-DDTHH:MM:SSZ</small> |
| <a id="LEG000151"></a>`LEG000151` | 400 | **Bad Request**<br/>similarity_score não pode ser nulo<br/><small>similarity_score cannot be null</small> |
| <a id="LEG000152"></a>`LEG000152` | 400 | **Bad Request**<br/>similarity_score deve ser maior que 0<br/><small>similarity_score must be greater than 0</small> |
| <a id="LEG000153"></a>`LEG000153` | 400 | **Bad Request**<br/>O template do documento não pode ser definido para INSS.<br/><small>Document template key must not be set for social security collateral.</small> |
| <a id="LEG000154"></a>`LEG000154` | 400 | **Bad Request**<br/>A categoria de operação 'aumento salarial' não está permitida.<br/><small>Operation category 'minimum_wage_increase' is not allowed for social security collateral.</small> |
| <a id="LEG000155"></a>`LEG000155` | 400 | **Bad Request**<br/>Prêmio de seguro não encontrado nos dados da operação.<br/><small>Insurance premium not found in operation data.</small> |

### MPR — Consignado Militar

32 erros

| Código | HTTP | Mensagem |
|-|-|-|
| <a id="MPR000001"></a>`MPR000001` | 400 | **Invalid Document Number**<br/>CPF {document_number} fornecido não é valido.<br/><small>Given {document_number} document number is invalid.</small> |
| <a id="MPR000002"></a>`MPR000002` | 500 | **Internal Error**<br/>Os servidores da cache retornaram um erro.<br/><small>Cache server returned an error.</small> |
| <a id="MPR0000029"></a>`MPR0000029` | 409 | **Reservation already locked**<br/>A reserva com o id {reservation_id} já está bloqueada sendo processada.<br/><small>Reservation with id {reservation_id} is already locked being processed.</small> |
| <a id="MPR000003"></a>`MPR000003` | 400 | **Already on deletion process**<br/>Reserva com a chave externa: {external_key} já está em processo de desaverbação<br/><small>Reservation with external_key: {external_key} already on deletion process</small> |
| <a id="MPR000004"></a>`MPR000004` | 404 | **Reservation Not Found**<br/>Reserva com a chave: {reservation_key} não encontrada<br/><small>Reservation with key: {reservation_key} not found</small> |
| <a id="MPR000005"></a>`MPR000005` | 400 | **Already finished**<br/>Reserva com a chave externa: {external_key} já está em seu status final {reservation_status}<br/><small>Reservation with external_key: {external_key} is already in its final status {reservation_status}</small> |
| <a id="MPR000006"></a>`MPR000006` | 400 | **Reservation type conflict**<br/>Tipo de Reserva: {reservation_type} não esperado para o fluxo {flow_translation}.<br/><small>Reservation Type: {reservation_type} not expected for {flow} flow.</small> |
| <a id="MPR000007"></a>`MPR000007` | 404 | **Disbursement Option not Found**<br/>Opção de desembolso para {disbursement_date} não foi encontrada.<br/><small>Disbursement option for {disbursement_date} was not found.</small> |
| <a id="MPR000009"></a>`MPR000009` | 409 | **Reservation Status Conflict**<br/>Reservas no status<br/><small>Reservation with status</small> |
| <a id="MPR000010"></a>`MPR000010` | 404 | **Balance Not Found**<br/>Pedido de Margem com a chave: {balance_key} não foi encontrado.<br/><small>Balance Request with key: {balance_key} was not found.</small> |
| <a id="MPR000011"></a>`MPR000011` | 403 | **Unauthorized Request**<br/>Requisição precisar ser internal ou da master.<br/><small>Request must be internal or from master.</small> |
| <a id="MPR000012"></a>`MPR000012` | 404 | **Accrual Not Found**<br/>Accrual não encontrado: {reference_date}<br/><small>Accrual not found: {reference_date}.</small> |
| <a id="MPR000013"></a>`MPR000013` | 404 | **Active Token Not Found**<br/>Token ativo não encontrado para a reserva: {reservation_key}<br/><small>Active token was not found for reservation: {reservation_key}.</small> |
| <a id="MPR000014"></a>`MPR000014` | 400 | **Balance Not Allowed**<br/>Pedido de Margem com o status: {status} não foi permitido a retentativa.<br/><small>Balance Request with status: {status} was not allowed to retry.</small> |
| <a id="MPR000015"></a>`MPR000015` | 400 | **Balance Not Allowed**<br/>Pedido de Margem com o status: {status} não foi permitido a retentativa.<br/><small>Balance Request with status: {status} was not allowed to retry.</small> |
| <a id="MPR000016"></a>`MPR000016` | 404 | **Balance Not Found**<br/>Consulta de contratos para portabilidade com a chave: {portability_contracts_report_key} não foi encontrado.<br/><small>Portability contracts report with key: {portability_contracts_report_key} was not found.</small> |
| <a id="MPR000017"></a>`MPR000017` | 404 | **Reservation Not Found for Debt Key**<br/>Reserva com a chave de débito: {external_key} não encontrada<br/><small>Reservation with debt_key: {external_key} not found</small> |
| <a id="MPR000018"></a>`MPR000018` | 400 | **Reservation status not permitted on refinancing**<br/>Reserva com a chave externa: {external_key}  está no status {status} que não é permitido para refinanciamento.<br/><small>Reservation with external_key: {external_key} is on status {status} which is not permitted for refinancing.</small> |
| <a id="MPR000019"></a>`MPR000019` | 404 | **Period not found for informed Reservation**<br/>Reserva com a chave: {reservation_key}  não possui uma parcela com a data de vencimento: {due_date}.<br/><small>Reservation with reservation_key: {reservation_key} does not have a Period with due_date: {due_date}.</small> |
| <a id="MPR000020"></a>`MPR000020` | 400 | **Informed period not allowed to be paid**<br/>Periodo com vencimento: {due_date} da reserva: {reservation_key} está no status: {period_status} que não permite a atualização para o status<br/><small>Period with due_date: {due_date} from reservation: {reservation_key} is on status: {period_status} which does not allow to be updated to status</small> |
| <a id="MPR000021"></a>`MPR000021` | 500 | **Encoding Error**<br/>Erro ao codificar arquivo<br/><small>Error while encoding file</small> |
| <a id="MPR000022"></a>`MPR000022` | 400 | **Invalid Registration Code**<br/>Matrícula fornecida: {registration_code} é invalida.<br/><small>Informed registration code: {registration_code} is invalid.</small> |
| <a id="MPR000023"></a>`MPR000023` | 404 | **Protocol not Found**<br/>Protocolo com chave {external_key} não foi encontrada.<br/><small>Protocol with debt key {external_key} was not found.</small> |
| <a id="MPR000024"></a>`MPR000024` | 400 | **Ivanlid protocol type**<br/>Protocolo do tipo {protocol_type} não existe.<br/><small>Protocol type {protocol_type} doesn</small> |
| <a id="MPR000025"></a>`MPR000025` | 400 | **Reservation Type Not Allowed to Change**<br/>Reserva com a chave: {external_key} é do tipo {reservation_type_enum} e não pode ser alterada.<br/><small>Reservation with debt_key: {external_key} is of type {reservation_type_enum}, which is not allowed to be changed.</small> |
| <a id="MPR000026"></a>`MPR000026` | 400 | **Reservation Status not Permitted for Type Change**<br/>Reserva com a chave: {external_key} está no status {reservation_status_enum} que não é permitido para o fluxo de alteração de tipo de reserva.<br/><small>Reservation with debt_key: {external_key} is on status {reservation_status_enum}, which is not permitted for reservation type change.</small> |
| <a id="MPR000027"></a>`MPR000027` | 400 | **Proposal has Remaining Installments**<br/>Proposal {proposal_key} não deveria ter installments sobrando.<br/><small>Proposal {proposal_key} shouldn</small> |
| <a id="MPR000028"></a>`MPR000028` | 400 | **Zetra Invalid Document Type**<br/>Erro ao enviar documento para Zetra. Tipo de arquivo inválido.<br/><small>Zetra error while uploading document. File type is invalid</small> |
| <a id="MPR000030"></a>`MPR000030` | 404 | **Contract Not Found**<br/>Reserva com o número de contrato: {contract_number} não encontrada<br/><small>Reservation with contract number: {contract_number} not found</small> |
| <a id="MPR000031"></a>`MPR000031` | 500 | Proposta não encontrada para reserva {reservation_key} - {status}<br/><small>Proposal not found for reservation {reservation_key} - {status}</small> |
| <a id="MPR000032"></a>`MPR000032` | 400 | **Renegotiation Proposal bad request**<br/>Renegotiation Proposal bad request |
| <a id="MPR000033"></a>`MPR000033` | 400 | **External System Unavailable**<br/>O sistema externo retornou um código de status superior a 500<br/><small>External system response status code is greater than 500</small> |

### PPA — Leilão Consignado Privado

23 erros

| Código | HTTP | Mensagem |
|-|-|-|
| <a id="PPA000001"></a>`PPA000001` | 404 | **Requester Proposal not Found**<br/>A entidade com<br/><small>Requester Proposal with</small> |
| <a id="PPA000002"></a>`PPA000002` | 500 | **Error publishing message on pub sub.**<br/>Erro ao publicar mensagem no Pub Sub, número máximo de tentativas excedido.<br/><small>Error publishing message on Pub Sub, max reetries exceeded.</small> |
| <a id="PPA000003"></a>`PPA000003` | 409 | **Entity already locked**<br/>A reserva com o id {reservation_id} já está bloqueada sendo processada.<br/><small>Reservation with id {reservation_id} is already locked being processed.</small> |
| <a id="PPA000004"></a>`PPA000004` | 404 | **Requester not Found**<br/>Requester com chave {requester_key} não foi encontrado.<br/><small>Requester with</small> |
| <a id="PPA000005"></a>`PPA000005` | 404 | **Proposal Request not Found**<br/>Proposal Request com<br/><small>Proposal Request with</small> |
| <a id="PPA000006"></a>`PPA000006` | 400 | **Auction has ended, invalid action**<br/>Leilão para<br/><small>The auction for</small> |
| <a id="PPA000007"></a>`PPA000007` | 409 | **Proposal was already cancelled**<br/>Proposta com chave {auction_proposal_key} já foi cancelada<br/><small>The Auction Proposal with key: {auction_proposal_key} was already cancelled</small> |
| <a id="PPA000008"></a>`PPA000008` | 400 | **Invalid requester proposal payload**<br/>payload de proposta é inválido para auction_proposal_key:{auction_proposal_key}<br/><small>Invalid requester proposal payload for auction_proposal_key:{auction_proposal_key}</small> |
| <a id="PPA000009"></a>`PPA000009` | 409 | **Duplicated Proposal for this issuer proposal request**<br/>Proposta já foi feita: {issuer_proposal_request_key}, chave da proposta: {auction_proposal_key}<br/><small>Already made a proposal for issuer_proposal_request: {issuer_proposal_request_key}, the proposal key is: {auction_proposal_key}</small> |
| <a id="PPA000010"></a>`PPA000010` | 502 | **Dataprevs system is down**<br/>Sistema da Dataprev está fora de ar<br/><small>Dataprev system is down</small> |
| <a id="PPA000011"></a>`PPA000011` | 400 | **Error when connecting to private payroll for external_id**<br/>API de consignado privado não está respondendo devidamente ao PATCH de external_id<br/><small>Private Payroll API is not responding properly to external_id PATCH</small> |
| <a id="PPA000013"></a>`PPA000013` | 400 | **Could not create credit operation for auction winner**<br/>Erro ao criar operação de credito para proposta vencedora do leilão, chave da proposta: {auction_proposal_key}<br/><small>Could not create credit operation for auction winner for auction_proposal_key: {auction_proposal_key}</small> |
| <a id="PPA000014"></a>`PPA000014` | 400 | **Could not simulate credit operation for Proposal**<br/>Erro ao simular operação de credito para proposta vencedora do leilão, chave da proposta: {issuer_proposal_request_key}<br/><small>Could not simulate credit operation for auction winner for auction_proposal_key: {issuer_proposal_request_key}</small> |
| <a id="PPA000015"></a>`PPA000015` | 400 | **The assignment amount is greater than the operation final amount**<br/>Erro ao simular operação de credito para proposta feita a solicitação com chave {issuer_proposal_request_key}. Valores de entrada devem ser modificados.<br/><small>Could not simulate credit operation for proposal made to issuer proposal request with key: {issuer_proposal_request_key}. The input values need to be changed.</small> |
| <a id="PPA000016"></a>`PPA000016` | 400 | **Requester with this key does not exist**<br/>Não foi possível obter o requester da tabela de empregadores exclusivos, requester_key: {requester_key}<br/><small>Could not get the requester from exclusive employer table, requester with key {requester_key} does not exist</small> |
| <a id="PPA000017"></a>`PPA000017` | 400 | **Invalid Disbursement Account**<br/>Conta de desembolso invalida enquanto atualizava proposta com chave {auction_proposal_key}<br/><small>Invalid Disbursement Account while updating account for auction proposal with key: {auction_proposal_key}</small> |
| <a id="PPA000018"></a>`PPA000018` | 400 | **Invalid Employer Document Number**<br/>Número de documento de empregador inválido para proposta com chave {auction_proposal_key}<br/><small>Invalid Employer Document Number for auction proposal with key: {auction_proposal_key}</small> |
| <a id="PPA000019"></a>`PPA000019` | 400 | **Error when cancelling credit operation**<br/>Erro ao cancelar operação de crédito para proposta com chave {auction_proposal_key}<br/><small>Error when cancelling credit operation for auction proposal with key: {auction_proposal_key}</small> |
| <a id="PPA000020"></a>`PPA000020` | 400 | **Auction Proposal Validation Error**<br/>Erro durante validação de proposta para solicitação com chave da solicitação: {issuer_proposal_request_key}<br/><small>Error when validating auction proposal for issuer proposal request with key {issuer_proposal_request_key}</small> |
| <a id="PPA000021"></a>`PPA000021` | 400 | **Termination alert found in existent balance inquiry during validation**<br/>Alerta de terminação de vínculo em consulta de margem existente durante validação de proposta para solicitação com chave da solicitação: {issuer_proposal_request_key}<br/><small>Termination alert in existent balance inquiry during validation of auction proposal for issuer proposal request with key {issuer_proposal_request_key}</small> |
| <a id="PPA000022"></a>`PPA000022` | 400 | **Invalid Interest Rate**<br/>A taxa de juros não pode ser maior que {max_interest_rate}% ou menor que {min_interest_rate}%.<br/><small>Interest rate can</small> |
| <a id="PPA000023"></a>`PPA000023` | 400 | **Insurance premium not allowed**<br/>Seguro não é permitido para operações de Consignado Privado<br/><small>Insurance premium is not allowed for private payroll operations</small> |
| <a id="PPA000024"></a>`PPA000024` | 404 | **Requester configuration not found**<br/>Configuração de requester com chave {requester_key} não encontrada<br/><small>Requester configuration with key {requester_key} not found</small> |

### PRP — Consignado Privado

98 erros

| Código | HTTP | Mensagem |
|-|-|-|
| <a id="PRP000002"></a>`PRP000002` | - | **Bad Request**<br/>O envio do termo de autorização é obrigatório<br/><small>The authorization term is required</small> |
| <a id="PRP000003"></a>`PRP000003` | - | **Bad Request**<br/>O número de documento do emissor é inválido<br/><small>The issuer document number is invalid</small> |
| <a id="PRP000004"></a>`PRP000004` | - | **Bad Request**<br/>O número de documento do signatário é inválido<br/><small>The signer document number is invalid</small> |
| <a id="PRP000005"></a>`PRP000005` | - | **Bad Request**<br/>O número de documento do representante legal é inválido<br/><small>The legal representative document number is invalid</small> |
| <a id="PRP000006"></a>`PRP000006` | - | **Conflict**<br/>O número de documento do signatário é diferente do esperado<br/><small>The signer document number is different from the expected</small> |
| <a id="PRP000007"></a>`PRP000007` | - | **Rate Limit Exceeded**<br/>Limite de chamadas excedido para o serviço do Dataprev. Tente novamente mais tarde.<br/><small>Rate limit exceeded for Dataprev service. Try again later.</small> |
| <a id="PRP000008"></a>`PRP000008` | - | **Bad Gateway**<br/>Erro inesperado no serviço do Dataprev<br/><small>Unexpected error on Dataprev service</small> |
| <a id="PRP000009"></a>`PRP000009` | - | **Balance Inquiry Not Found**<br/>A chave da consulta de saldo não é válida<br/><small>The balance inquiry key is not valid</small> |
| <a id="PRP000010"></a>`PRP000010` | - | **Employment Relationships Inquiry Not Found**<br/>A chave da consulta de vínculos de emprego não é válida<br/><small>The employment relationships inquiry key is not valid</small> |
| <a id="PRP000011"></a>`PRP000011` | - | **Reservation already exists**<br/>A reserva já existe para a chave externa fornecida<br/><small>A reservation already exists for the external key provided</small> |
| <a id="PRP000012"></a>`PRP000012` | - | **Balance inquiry not found**<br/>Nenhuma consulta de saldo foi encontrada para a reserva<br/><small>A balance inquiry was not found for the reservation</small> |
| <a id="PRP000013"></a>`PRP000013` | - | **Balance inquiry not completed**<br/>A consulta de saldo não foi concluída<br/><small>The balance inquiry was not completed</small> |
| <a id="PRP000014"></a>`PRP000014` | - | **Periods are required**<br/>Os períodos são obrigatórios<br/><small>The periods are required</small> |
| <a id="PRP000015"></a>`PRP000015` | - | **Periods are greater than maximum allowed**<br/>Os períodos são maiores que o máximo permitido: {max_periods}<br/><small>The periods are greater than the maximum allowed: {max_periods}</small> |
| <a id="PRP000016"></a>`PRP000016` | - | **First due date is less than disbursement date**<br/>A data de vencimento inicial deve ser maior que a data de liberação<br/><small>The first due date must be greater than the disbursement date</small> |
| <a id="PRP000017"></a>`PRP000017` | - | **Invalid due date**<br/>As datas de vencimento devem ser no dia {due_day} ou após do mês<br/><small>Due dates must be on or after the {due_day}th day of the month</small> |
| <a id="PRP000018"></a>`PRP000018` | - | **Monthly interest rate is greater than maximum allowed**<br/>A taxa de juros mensal é maior que a máxima permitida: {formatted_rate}<br/><small>The monthly interest rate is greater than the maximum allowed: {formatted_rate}</small> |
| <a id="PRP000021"></a>`PRP000021` | - | **Total amount is less than minimum allowed**<br/>O valor total é menor que o mínimo permitido: {formatted_amount}<br/><small>The total amount is less than the minimum allowed: {formatted_amount}</small> |
| <a id="PRP000022"></a>`PRP000022` | - | **Invalid number of documents**<br/>O número de documentos deve ser 3 ou 4<br/><small>The number of documents must be 3 or 4</small> |
| <a id="PRP000023"></a>`PRP000023` | - | **Duplicate document type**<br/>O tipo de documento {DOCUMENT_TYPES_TRANSLATION[document_type]} está duplicado<br/><small>The document type {document_type} is duplicated</small> |
| <a id="PRP000024"></a>`PRP000024` | - | **Document identification is required**<br/>O documento de identificação é obrigatório<br/><small>The document identification is required</small> |
| <a id="PRP000025"></a>`PRP000025` | - | **Document identification back is required**<br/>O documento de identificação de verso é obrigatório<br/><small>The document identification back is required</small> |
| <a id="PRP000026"></a>`PRP000026` | - | **Selfie is required**<br/>A selfie é obrigatória<br/><small>The selfie is required</small> |
| <a id="PRP000027"></a>`PRP000027` | - | **CCB document is required**<br/>Deve ser fornecido exatamente um contrato de {ccb_types}<br/><small>Exactly one contract of {ccb_types} must be provided</small> |
| <a id="PRP000028"></a>`PRP000028` | - | **Failed to download file**<br/>Falha ao baixar o arquivo de {url}<br/><small>Failed to download file from {url}</small> |
| <a id="PRP000029"></a>`PRP000029` | - | **Failed to convert PDF to image**<br/>Falha ao converter PDF para imagem: {error}<br/><small>Failed to convert PDF to image: {error}</small> |
| <a id="PRP000030"></a>`PRP000030` | - | **Empty PDF file**<br/>O arquivo PDF está vazio ou não contém páginas válidas para conversão<br/><small>PDF file appears to be empty or contains no valid pages to convert</small> |
| <a id="PRP000031"></a>`PRP000031` | - | **Invalid document image**<br/>A imagem do documento não pode ser processada: {error}<br/><small>The document image cannot be processed: {error}</small> |
| <a id="PRP000032"></a>`PRP000032` | - | **Invalid document image format**<br/>O documento<br/><small>The document</small> |
| <a id="PRP000033"></a>`PRP000033` | - | **Invalid document image size**<br/>O documento<br/><small>The document</small> |
| <a id="PRP000034"></a>`PRP000034` | - | **Error cancelling credit operation permanently**<br/>Falha ao cancelar permanentemente a operação de crédito: {external_key}<br/><small>Failed to cancel credit operation permanently: {external_key}</small> |
| <a id="PRP000035"></a>`PRP000035` | - | **Reservation not found**<br/>A reserva não foi encontrada<br/><small>The reservation was not found</small> |
| <a id="PRP000037"></a>`PRP000037` | - | **Reservation is not pending auction**<br/>A reserva não está pendente de leilão<br/><small>The reservation is not pending auction</small> |
| <a id="PRP000038"></a>`PRP000038` | - | **Error creating proposal**<br/>Erro ao criar proposta<br/><small>Failed to create proposal</small> |
| <a id="PRP000039"></a>`PRP000039` | - | **Error getting proposal**<br/>Erro ao obter proposta<br/><small>Failed to get proposal</small> |
| <a id="PRP000040"></a>`PRP000040` | - | **Reservation period is not equal to the number of periods**<br/>O período de reserva não é igual ao número de períodos<br/><small>The reservation period is not equal to the number of periods</small> |
| <a id="PRP000041"></a>`PRP000041` | - | **Error getting credit operation by external key**<br/>Falha ao buscar a operação de crédito: {external_key}<br/><small>Failed to get credit operation by external key: {external_key}</small> |
| <a id="PRP000042"></a>`PRP000042` | - | **Service Unavailable**<br/>Serviço indisponível para o serviço do Dataprev<br/><small>Service unavailable for Dataprev service</small> |
| <a id="PRP000043"></a>`PRP000043` | - | **Invalid reason**<br/>Exclusão de reserva falhou<br/><small>Reservation deletion failed</small> |
| <a id="PRP000044"></a>`PRP000044` | - | **Reason not found**<br/>Motivo não encontrado<br/><small>Reason not found</small> |
| <a id="PRP000045"></a>`PRP000045` | - | **Invalid reason**<br/>Inclusão de reserva falhou<br/><small>Reservation inclusion failed</small> |
| <a id="PRP000046"></a>`PRP000046` | - | **Error creating document**<br/>Falha ao criar o documento: {document_name}<br/><small>Failed to create document: {document_name}</small> |
| <a id="PRP000047"></a>`PRP000047` | - | **Error uploading document**<br/>Falha ao enviar o documento: {document_key}<br/><small>Failed to upload document: {document_key}</small> |
| <a id="PRP000048"></a>`PRP000048` | - | **Error updating disbursement date**<br/>Falha ao atualizar a data de desembolso para a operação de crédito: {external_key}<br/><small>Failed to update disbursement date for credit operation: {external_key}</small> |
| <a id="PRP000049"></a>`PRP000049` | - | **Error constituting collateral**<br/>Falha ao constituir a garantia para a operação de crédito: {external_key}<br/><small>Failed to constitute collateral for credit operation: {external_key}</small> |
| <a id="PRP000050"></a>`PRP000050` | - | **Error cancelling credit operation**<br/>Falha ao cancelar a operação de crédito: {external_key}<br/><small>Failed to cancel credit operation: {external_key}</small> |
| <a id="PRP000051"></a>`PRP000051` | - | **Document validation failed**<br/>A validação de documentos falhou<br/><small>Document validation failed</small> |
| <a id="PRP000052"></a>`PRP000052` | - | **Reservation cannot be deleted**<br/>A reserva está em fluxo de suspensão<br/><small>The reservation is in suspension flow</small> |
| <a id="PRP000053"></a>`PRP000053` | - | **Protocol type not found**<br/>O tipo de protocolo não foi encontrado<br/><small>The protocol type was not found</small> |
| <a id="PRP000054"></a>`PRP000054` | - | **Authentication Error**<br/>Falha na autenticação com serviço externo<br/><small>Failed to authenticate with external service</small> |
| <a id="PRP000055"></a>`PRP000055` | - | **Error getting document by name**<br/>Falha ao buscar o documento: {document_name}<br/><small>Failed to get document by name: {document_name}</small> |
| <a id="PRP000056"></a>`PRP000056` | - | **Empty document list**<br/>A lista de documentos está vazia: {document_name}<br/><small>Document list is empty: {document_name}</small> |
| <a id="PRP000057"></a>`PRP000057` | - | **Reservation is not pending requester authorization**<br/>A reserva não está pendente de autorização do requerente<br/><small>The reservation is not pending requester authorization</small> |
| <a id="PRP000058"></a>`PRP000058` | - | **Error creating credit analysis**<br/>Falha ao criar a análise de crédito para o número de documento {document_number}<br/><small>Failed to create credit analysis for document number {document_number}</small> |
| <a id="PRP000059"></a>`PRP000059` | - | **Invalid credit analysis status**<br/>Status de análise de crédito inválido: {analysis_status}<br/><small>Invalid credit analysis status: {analysis_status}</small> |
| <a id="PRP000060"></a>`PRP000060` | - | **Reservation is not pending credit analysis**<br/>A reserva não está pendente de análise de crédito<br/><small>The reservation is not pending credit analysis</small> |
| <a id="PRP000061"></a>`PRP000061` | - | **Requester configuration not found**<br/>A configuração do cliente com a chave {requester_key} não foi encontrada<br/><small>The requester configuration with key {requester_key} was not found</small> |
| <a id="PRP000062"></a>`PRP000062` | - | **Requester configuration already exists**<br/>A configuração do cliente com a chave {requester_key} já existe<br/><small>The requester configuration with key {requester_key} already exists</small> |
| <a id="PRP000063"></a>`PRP000063` | - | **Reservation is not pending documents submission**<br/>A reserva não está pendente de envio de documentos<br/><small>The reservation is not pending documents submission</small> |
| <a id="PRP000064"></a>`PRP000064` | - | **Invalid biometry analysis**<br/>A análise biométrica é inválida<br/><small>The biometry analysis is invalid</small> |
| <a id="PRP000067"></a>`PRP000067` | - | **Invalid status for cancellation**<br/>O status da reserva {status} não é válido para cancelamento<br/><small>The reservation status {status} is not valid for cancellation</small> |
| <a id="PRP000068"></a>`PRP000068` | - | **Reservation is not canceled**<br/>A reserva não está cancelada<br/><small>The reservation is not canceled</small> |
| <a id="PRP000069"></a>`PRP000069` | - | **Wrong status event**<br/>O evento de status da reserva {status} não é válido<br/><small>The reservation status event {status} is not valid</small> |
| <a id="PRP000070"></a>`PRP000070` | - | **Invalid status for reactivation**<br/>O evento de status da reserva {status} não é válido para reativação<br/><small>The reservation status event {status} is not valid for reactivation</small> |
| <a id="PRP000071"></a>`PRP000071` | - | **Error getting credit analysis**<br/>Falha ao obter a análise de crédito para a chave de reserva: {reservation_key}<br/><small>Failed to get credit analysis for reservation key: {reservation_key}</small> |
| <a id="PRP000072"></a>`PRP000072` | - | **Is not allowed to reserve**<br/>A reserva não é permitida para ser reservada<br/><small>The reservation is not allowed to be reserved</small> |
| <a id="PRP000073"></a>`PRP000073` | - | **Invalid status for documents submission**<br/>O status da reserva {status} não é válido para submissão dos documentos<br/><small>The reservation status {status} is not valid for documents submission</small> |
| <a id="PRP000074"></a>`PRP000074` | - | **Invalid status to delete**<br/>O status da reserva não é válido para exclusão<br/><small>The reservation status is not valid for deletion</small> |
| <a id="PRP000075"></a>`PRP000075` | - | **Bad Gateway**<br/>Erro ao incluir contrato legado<br/><small>Failed to include legacy contract</small> |
| <a id="PRP000076"></a>`PRP000076` | - | **Bad Request**<br/>Faltam campos obrigatórios<br/><small>Missing required fields</small> |
| <a id="PRP000077"></a>`PRP000077` | - | **Requester configuration is not active**<br/>A configuração do cliente com a chave {requester_key} não está ativa<br/><small>The requester configuration with key {requester_key} is not active</small> |
| <a id="PRP000078"></a>`PRP000078` | - | **Invalid configuration data**<br/>A configuração do cliente com a chave {requester_key} tem dados de configuração inválidos<br/><small>The requester configuration with key {requester_key} has invalid configuration data</small> |
| <a id="PRP000079"></a>`PRP000079` | - | **Legacy Contract not found**<br/>O contrato legado {contract_number} não foi encontrado<br/><small>The Legacy Contract {contract_number} was not found</small> |
| <a id="PRP000080"></a>`PRP000080` | - | **Bad Gateway**<br/>Erro ao excluir contrato legado<br/><small>Failed to exclude legacy contract</small> |
| <a id="PRP000081"></a>`PRP000081` | - | **Bad Gateway**<br/>Erro ao renegociar contrato legado<br/><small>Failed to renegotiate legacy contract</small> |
| <a id="PRP000082"></a>`PRP000082` | - | **Missing required fields**<br/>Os campos obrigatórios estão ausentes<br/><small>The required fields are missing</small> |
| <a id="PRP000083"></a>`PRP000083` | - | **Invalid legacy contract to refinance**<br/>O contrato legacy {contract_number} não é válido para refinanciamento<br/><small>The legacy contract {contract_number} is not valid to refinance</small> |
| <a id="PRP000084"></a>`PRP000084` | - | **Bad Request**<br/>A taxa de juros do contrato legado {contract_number} precisa ser maior que a do novo contrato: {interest_rate}<br/><small>The interest rate of the legacy contract {contract_number} must be greater than the new contract: {interest_rate}</small> |
| <a id="PRP000085"></a>`PRP000085` | - | **Success Reason not found**<br/>Motivo de sucesso não encontrado<br/><small>Success reason not found</small> |
| <a id="PRP000086"></a>`PRP000086` | - | **Failure Reason not found**<br/>Motivo de falha não encontrado<br/><small>Failure reason not found</small> |
| <a id="PRP000087"></a>`PRP000087` | - | **Outside of Dataprev working hours**<br/>Fora do horário de funcionamento da Dataprev<br/><small>Outside of Dataprev working hours</small> |
| <a id="PRP000088"></a>`PRP000088` | - | **Authorization Term Not Found**<br/>Termo de autorização não foi encontrado<br/><small>The Authorization Term key not found</small> |
| <a id="PRP000089"></a>`PRP000089` | - | **Termination alert found in balance inquiry**<br/>Alerta de terminação de vínculo encontrado em consulta de vínculo existente durante validação<br/><small>Termination alert found in existent balance inquiry during validation</small> |
| <a id="PRP000090"></a>`PRP000090` | - | **Bad Request**<br/>O contrato legado {contract_number} não está ativo<br/><small>The legacy contract {contract_number} is not active</small> |
| <a id="PRP000091"></a>`PRP000091` | - | **Bad Request**<br/>O número do documento do empregador é inválido<br/><small>The employer document number is invalid</small> |
| <a id="PRP000092"></a>`PRP000092` | - | **Invalid legacy contract refinancing reservation amount**<br/>O valor da reserva é maior que o valor total dos períodos dos contratos legacy<br/><small>Reservation amount is greater than the legacy contracts total period amount</small> |
| <a id="PRP000093"></a>`PRP000093` | - | **Failed to get registers**<br/>Falha ao obter registros<br/><small>Failed to get registers</small> |
| <a id="PRP000094"></a>`PRP000094` | - | **Failed to get payments**<br/>Falha ao obter pagamentos<br/><small>Failed to get payments</small> |
| <a id="PRP000095"></a>`PRP000095` | - | **Registers not found**<br/>Registros não encontrados<br/><small>Registers not found</small> |
| <a id="PRP000096"></a>`PRP000096` | - | **Payments not found**<br/>Pagamentos não encontrados<br/><small>Payments not found</small> |
| <a id="PRP000097"></a>`PRP000097` | - | **Already has balance inquiry**<br/>A reserva já tem uma consulta de saldo<br/><small>The reservation already has a balance inquiry</small> |
| <a id="PRP000098"></a>`PRP000098` | - | **Bad Request**<br/>Erro no termo de autorização<br/><small>Error on authorization term</small> |
| <a id="PRP000099"></a>`PRP000099` | - | **Requester Key Is Required**<br/>A chave do solicitante é obrigatória<br/><small>The requester key is required</small> |
| <a id="PRP000100"></a>`PRP000100` | - | **Invalid legacy contract for rollover**<br/>O contrato legacy {contract_number} possui CPF ou CNPJ do empregador diferente<br/><small>The legacy contract {contract_number} has different document number or employer document number</small> |
| <a id="PRP000101"></a>`PRP000101` | - | **Failed to create rollover reservation**<br/>Falha ao criar reserva de tombamento: {error_message or<br/><small>Failed to create rollover reservation: {error_message or</small> |
| <a id="PRP000102"></a>`PRP000102` | - | **Missing parameter**<br/>O parâmetro {parameter} está ausente<br/><small>The parameter {parameter} is missing</small> |
| <a id="PRP000104"></a>`PRP000104` | - | **Failed to generate a valid contract number**<br/>Falha ao criar número de contrato para reserva.<br/><small>Failed to generate a contract number for a reservation</small> |
| <a id="PRP000201"></a>`PRP000201` | - | **Employment Relationship Not Found**<br/>A chave da consulta de vínculos de emprego não é válida<br/><small>The employment relationships inquiry key is not valid</small> |

### RN — Renegociação de Dívidas

35 erros

| Código | HTTP | Mensagem |
|-|-|-|
| <a id="RN0000001"></a>`RN0000001` | 400 | **Bad Request**<br/>O status dessa operação de crédito é invalido para essa requisição. Status: {credit_operation_status}<br/><small>Credit operation status is invalid for this request. Status: {credit_operation_status}</small> |
| <a id="RN0000002"></a>`RN0000002` | 400 | **Bad Request**<br/>O status dessa parcela é invalido para essa requisição.Installment key:{installment_key}<br/><small>Installment status is invalid for this request.Installment key:{installment_key}</small> |
| <a id="RN0000003"></a>`RN0000003` | 404 | **Not Found**<br/>Nenhuma parcela encontrada para as installment keys recebidas.<br/><small>No installment found for received installment keys.</small> |
| <a id="RN0000004"></a>`RN0000004` | 400 | **Bad Request**<br/>O valor do desconto percentual deve ser menor ou igual a 1.<br/><small>The percentage discount amount must be less than or equal to 1.</small> |
| <a id="RN0000005"></a>`RN0000005` | 400 | **Bad Request**<br/>O valor do desconto não pode ser maior do que o valor das parcelas.<br/><small>The discount amount cannot be greater than the the installments values.</small> |
| <a id="RN0000006"></a>`RN0000006` | 400 | **Bad Request**<br/>A mesma installment_key foi informada mais de uma vez.Installment Key:{installment_key}<br/><small>The same installment key was informed more than once.Installment Key:{installment_key}</small> |
| <a id="RN0000007"></a>`RN0000007` | 400 | **Bad Request**<br/>Parcela não possui campo paid_amount. Installment_key:{installment_key}<br/><small>Installment doesn</small> |
| <a id="RN0000008"></a>`RN0000008` | 400 | **Bad Request**<br/>A proposta deve ter um pagamento vinculado a ela.<br/><small>Proposal must have a payment linked to it.</small> |
| <a id="RN0000009"></a>`RN0000009` | 403 | **Forbidden**<br/>O solicitante informado não é o mesmo da operação de crédito.<br/><small>The requester informed is not the same as the credit operation.</small> |
| <a id="RN0000010"></a>`RN0000010` | 404 | **Not Found**<br/>Proposta não encontrada.<br/><small>Proposal not found.</small> |
| <a id="RN0000011"></a>`RN0000011` | 400 | **Bad Request**<br/>Proposta não pode ser cancelada no status atual.Status:{status}<br/><small>Proposal cannot be canceled in current status.Status:{status}</small> |
| <a id="RN0000012"></a>`RN0000012` | 404 | **Not Found**<br/>Operação de credito não encontrada pelo número de contrato enviado.<br/><small>Credit Operation not found for sent contract number.</small> |
| <a id="RN0000013"></a>`RN0000013` | 404 | **Not found**<br/>O mecanismo de pagamento não foi encontrado.<br/><small>The payment engine has not been found.</small> |
| <a id="RN0000014"></a>`RN0000014` | 404 | **Not found**<br/>O perfil de solicitante não foi encontrado.<br/><small>The requester profile has not been found.</small> |
| <a id="RN0000015"></a>`RN0000015` | 400 | **Bad Request**<br/>A data de vencimento da renegociação ou a data de referência não podem estar no passado.<br/><small>Proposal due date or reference date cannot be in past.</small> |
| <a id="RN0000016"></a>`RN0000016` | 404 | **Not found**<br/>A configuração de solicitante não foi encontrada.<br/><small>The requester configuration has not been found.</small> |
| <a id="RN0000017"></a>`RN0000017` | 400 | **Bad Request**<br/>A renegociação não pode ser paga no status atual. Proposal Status: {status}<br/><small>The proposal cannot be paid in current status. Proposal Status: {status}</small> |
| <a id="RN0000018"></a>`RN0000018` | 400 | **Bad Request**<br/>O registro do boleto bancário foi rejeitado.<br/><small>The bank slip registration has been rejected.</small> |
| <a id="RN0000019"></a>`RN0000019` | 409 | **Conflict**<br/>Esse contrato ja está vinculado a outra proposta em andamento.<br/><small>This contract is already linked to another proposal in progress.</small> |
| <a id="RN0000020"></a>`RN0000020` | 400 | **Bad Request**<br/>A requisição de renegociação é inválida devido ao status da operação de crédito.<br/><small>Renegotiation request invalid due to credit operation status.</small> |
| <a id="RN0000021"></a>`RN0000021` | 400 | **Bad Request**<br/>Número de operações é maior que o máximo permitido. Máximo de operações permitidas: {maximum_operations}<br/><small>Number of operations is greater than the maximum allowed. Maximum operations allowed: {maximum_operations}</small> |
| <a id="RN0000022"></a>`RN0000022` | 400 | **Bad Request**<br/>Não é possível realizar uma renegociação em lote com emissores diferentes.<br/><small>It is not possible to carry out a batch renegotiation with different issuers.</small> |
| <a id="RN0000024"></a>`RN0000024` | 404 | **Not Found**<br/>Batch proposal não encontrada.<br/><small>Batch proposal not found.</small> |
| <a id="RN0000025"></a>`RN0000025` | 400 | **Bad Request**<br/>Proposta em lote não pode ser cancelada no status atual.Status:{status}<br/><small>Batch Proposal cannot be canceled in current status.Status:{status}</small> |
| <a id="RN0000026"></a>`RN0000026` | 400 | **Bad Request**<br/>Requester identifier key ja está sendo utilizada para outra proposta em lote.<br/><small>Requester identifier key is already been used for another batch proposal.</small> |
| <a id="RN0000027"></a>`RN0000027` | 400 | **Bad Request**<br/>O valor do desconto não pode ser maior do que o valor de pagamento da renegociação em lote: {payment_amount}.<br/><small>The discount amount cannot be greater than the batch proposal payment amount: {payment_amount}.</small> |
| <a id="RN0000028"></a>`RN0000028` | 400 | **Bad Request**<br/>As parcelas selecionadas para renegociação devem incluir as últimas datas de vencimento.<br/><small>Selected Installments for renegotiation must include the latest due dates.</small> |
| <a id="RN0000029"></a>`RN0000029` | 400 | **Bad Request**<br/>O tipo de amortização para a renegociação com colateral deve ser pagamento de parcelas.<br/><small>Amortization Type of collateral renegotiation must be Installment Payment.</small> |
| <a id="RN0000030"></a>`RN0000030` | 400 | **Bad Request**<br/>O campo de valor de desconto não pode ser informado para a batch proposal e para as operações na mesma requisição.<br/><small>Discount amount field can</small> |
| <a id="RN0000031"></a>`RN0000031` | 400 | **Bad Request**<br/>Valor de pagamento da parcela não pode ser 0. Installment_key: {installment_key}<br/><small>Installment payment amount can</small> |
| <a id="RN0000032"></a>`RN0000032` | 400 | **Bad Request**<br/>O valor do pagamento não pode ser maior que o valor de desembolso.<br/><small>Payment amount cannot be greater than the disbursement amount.</small> |
| <a id="RN0000033"></a>`RN0000033` | 400 | **Bad Request**<br/>O valor do pagamento não é necessário para o tipo de amortização presente.<br/><small>Payment amount is not required for present amount amortization type.</small> |
| <a id="RN0000034"></a>`RN0000034` | 400 | **Bad Request**<br/>Requester identifier key ja está sendo utilizada para outra proposta.<br/><small>Requester identifier key is already been used for another proposal.</small> |
| <a id="RN0000035"></a>`RN0000035` | 400 | **Bad Request**<br/>O valor do desconto é invalido. O valor do desconto deve ser apenas desconto de juros.<br/><small>Invalid discount amount. Discount amount must be only interest discount.</small> |
| <a id="RN0000036"></a>`RN0000036` | 500 | **Internal Server Error**<br/>Número máximo de retentativas é muito grande.<br/><small>Max retries set is too big to be executable.</small> |
| <a id="RN0000037"></a>`RN0000037` | 400 | **Bad Request**<br/>O documento do pagador não corresponde ao documento do empregador para a operação de crédito.<br/><small>The payer document number does not match the employer document for the credit operation.</small> |
| <a id="RN0000038"></a>`RN0000038` | 400 | **Renegotiation Errors**<br/>Uma ou mais operacoes falharam.<br/><small>One or more operations failed.</small> |

### SSC — INSS

91 erros

| Código | HTTP | Mensagem |
|-|-|-|
| <a id="SSC000001"></a>`SSC000001` | 404 | **Contract not Found**<br/>Contrato {contract_number} não encontrado no DataPrev<br/><small>Contract {contract_number} not found in DataPrev</small> |
| <a id="SSC000002"></a>`SSC000002` | 400 | **Contract not Found**<br/>Contrato {contract_number} não está ativo<br/><small>Contract {contract_number} is not active</small> |
| <a id="SSC000003"></a>`SSC000003` | 404 | **Benefits not Found**<br/>A reserva com chave {benefits_key} não foi encontrada.<br/><small>Benefits with key {benefits_key} was not found.</small> |
| <a id="SSC000004"></a>`SSC000004` | 404 | **Reservation not Found**<br/>A reserva com chave {reservation_key} não foi encontrada.<br/><small>Reservation with key {reservation_key} was not found.</small> |
| <a id="SSC000005"></a>`SSC000005` | 404 | **Document not Found**<br/>O documento com chave {document_key} não foi encontrada.<br/><small>Document with key {document_key} was not found.</small> |
| <a id="SSC000006"></a>`SSC000006` | 404 | **Balance not Found**<br/>A consulta de saldo com chave {balance_key} não foi encontrada.<br/><small>Balance with key {balance_key} was not found.</small> |
| <a id="SSC0000069"></a>`SSC0000069` | 404 | **Reservation not Found**<br/>A reserva com ID {reservation_id} não foi encontrada.<br/><small>Reservation with ID {reservation_id} was not found.</small> |
| <a id="SSC000007"></a>`SSC000007` | 403 | **Forbidden**<br/>Não existe uma autorização válida para a pessoa com cpf {document_number}.<br/><small>There is not an active authorization for person {document_number}.</small> |
| <a id="SSC0000071"></a>`SSC0000071` | 409 | **Reservation already locked**<br/>A reserva com a key {reservation_key} já está bloqueada sendo processada.<br/><small>Reservation with key {reservation_key} is already locked being processed.</small> |
| <a id="SSC0000072"></a>`SSC0000072` | 400 | **Refinancing contract cannot be reverted**<br/>Contrato de refinanciamento não pode ser revertido após 7 dias úteis da reserva.<br/><small>Refinancing contract cannot be reverted after 7 working days from reservation.</small> |
| <a id="SSC0000073"></a>`SSC0000073` | 400 | **The number of grace competencies is invalid**<br/>O número da carência de competências está inválido. O intervalo aceito é de 0 a 6<br/><small>The number of grace competencies is invalid. The accepted range is 0 to 6</small> |
| <a id="SSC000008"></a>`SSC000008` | 400 | **Bad Request**<br/>O documento do termo deve ser o mesmo do requisitado.<br/><small>The term</small> |
| <a id="SSC000009"></a>`SSC000009` | 400 | **Bad Request**<br/>CPF {document_number} fornecido não é valido.<br/><small>Given {document_number} document number is invalid.</small> |
| <a id="SSC000010"></a>`SSC000010` | 400 | **Bad Request**<br/>Faltou informar os dados de telefone para contato<br/><small>Contact phone data is missing</small> |
| <a id="SSC000011"></a>`SSC000011` | 400 | **Bad Request**<br/>Faltou informar os dados de email para contato<br/><small>Contact email data is missing</small> |
| <a id="SSC000012"></a>`SSC000012` | 400 | **Bad Request**<br/>O atributo tipo de contato é necessário para o objeto assinante<br/><small>Contact type attribute is required for signer object</small> |
| <a id="SSC000013"></a>`SSC000013` | 400 | **Bad Request**<br/>Não pode proceder com o webhook de um documento não assinado<br/><small>Cannot proceed with webhook from non signed document</small> |
| <a id="SSC000014"></a>`SSC000014` | 409 | **Bad Request**<br/>O termo de assinatura é inelegivel para assinatura<br/><small>Term of signature is ineligible for signing</small> |
| <a id="SSC000015"></a>`SSC000015` | 400 | **Bad Request**<br/>Valores {invalid_types} não são tipos de documentos válidos<br/><small>Values {invalid_types} are not valid document_types</small> |
| <a id="SSC000016"></a>`SSC000016` | 409 | **Reservation not deleted**<br/> |
| <a id="SSC000017"></a>`SSC000017` | 404 | **External key not Found**<br/>A reserva com chave externa {external_key} não foi encontrada.<br/><small>Reservation with external key {external_key} was not found.</small> |
| <a id="SSC000018"></a>`SSC000018` | 409 | **Reservation Status Conflict**<br/>Reservas no status<br/><small>Reservation with status</small> |
| <a id="SSC000020"></a>`SSC000020` | 400 | **Bad Request**<br/>Os períodos devem possuir datas em meses subsequentes.<br/><small>Periods due date must occur in sub sequent months.</small> |
| <a id="SSC000021"></a>`SSC000021` | 400 | **Bad Request**<br/>A reserva precisa ter mais do que 0 períodos.<br/><small>Given reservation must have more than 0 periods.</small> |
| <a id="SSC000022"></a>`SSC000022` | 400 | **Bad Request**<br/>A data de competencia do inicio do desconto precisa ser equivalente a data de competencia atual e a data de competencia do desembolso<br/><small>Accrual date of the discount initiation needs to be equivalent to the current accrual date and the disbursement accrual date</small> |
| <a id="SSC000023"></a>`SSC000023` | 400 | **Bad Request**<br/>O DataPrev está fechado e não pode processar esse pedido.<br/><small>DataPrev is closed and cannot process this request</small> |
| <a id="SSC000024"></a>`SSC000024` | 400 | **Bad Request**<br/>Faltou informar os dados da portabilidade.<br/><small>Portability Data is missing.</small> |
| <a id="SSC000025"></a>`SSC000025` | 400 | **Bad Request**<br/>O assinante do termo precisa ser o beneficiario ou seu representante legal caso existente<br/><small>The signer</small> |
| <a id="SSC000026"></a>`SSC000026` | 400 | **Bad Requests**<br/>Erro inesperado do DataPrev<br/><small>Unexpected error from DataPrev.</small> |
| <a id="SSC000027"></a>`SSC000027` | 429 | **Rate Limit Exceeded**<br/>Limite de requisições do DataPrev excedido.<br/><small>DataPrev rate limit exceeded.</small> |
| <a id="SSC000028"></a>`SSC000028` | 409 | **Conflict**<br/>Consulta de margem com status {status} não pode ser retentado.<br/><small>Balance Request with status {status} cannot be retried.</small> |
| <a id="SSC000029"></a>`SSC000029` | 409 | **Reservation Already Registered**<br/>Reserva com a chave externa {external_key} já está cadastrado para o requester {requester_key}<br/><small>Reservation with external key {external_key} already exists for requester {requester_key}</small> |
| <a id="SSC000030"></a>`SSC000030` | 404 | **Disbursement Option not Found**<br/>Opção de desembolso para {disbursement_date} não foi encontrada.<br/><small>Disbursement option for {disbursement_date} was not found.</small> |
| <a id="SSC000031"></a>`SSC000031` | 409 | **Conflict**<br/>Consulta de benefícios com status {status} não pode ser retentado.<br/><small>Benefits Request with status {status} cannot be retried.</small> |
| <a id="SSC000032"></a>`SSC000032` | 400 | **Bad Request**<br/>Faltou informar os dados de refinanciamento.<br/><small>Refinancing Data is missing.</small> |
| <a id="SSC000033"></a>`SSC000033` | 400 | **Bad Request**<br/>Faltou informar os dados de refinanciamento.<br/><small>Refinancing Data is missing.</small> |
| <a id="SSC000034"></a>`SSC000034` | 400 | **Bad Request**<br/>A(s) Reservas(s) não estão averbada(s) para realizar o refinanciamento.<br/><small>The Reservation(s) must be reserved in order to perform the refinancing.</small> |
| <a id="SSC000035"></a>`SSC000035` | 404 | **Reservation not Found**<br/>A reserva com chave externa {external_key} não foi encontrada.<br/><small>Reservation with external key {external_key} was not found.</small> |
| <a id="SSC000036"></a>`SSC000036` | 400 | **Bad Request**<br/>Tentando refinanciar reserva com titularidade trocada.<br/><small>Trying to refinance</small> |
| <a id="SSC000038"></a>`SSC000038` | 409 | **Discount Status Conflict**<br/>Disconto no status<br/><small>Discount with status</small> |
| <a id="SSC000040"></a>`SSC000040` | 404 | **Valid Balance not old than 15 days not Found**<br/>A consulta de saldo é muito antiga. A consulta mais recente é de {date}.<br/><small>The valid balance enquire is outdated. The most recent balance is from {date}.</small> |
| <a id="SSC000041"></a>`SSC000041` | 400 | **Bad Request**<br/>O benefício {benefit_number} está {translation_dict[reason]}.<br/><small>The benefit number {benefit_number} is {reason}</small> |
| <a id="SSC000042"></a>`SSC000042` | 404 | **Protocol not Found**<br/>Protocolo com chave {external_key} não foi encontrada.<br/><small>Protocol with key {external_key} was not found.</small> |
| <a id="SSC000043"></a>`SSC000043` | 404 | **Protocol not Found**<br/>Protocolo com hash de operação {hash_operation} não foi encontrada.<br/><small>Protocol with hash operation {hash_operation} was not found.</small> |
| <a id="SSC000044"></a>`SSC000044` | 400 | **Ivanlid protocol type**<br/>Protocolo do tipo {protocol_type} não existe.<br/><small>Protocol type {protocol_type} doesn</small> |
| <a id="SSC000045"></a>`SSC000045` | 409 |  |
| <a id="SSC000046"></a>`SSC000046` | 400 | **Bad Request**<br/>O produto INSS está temporariamente indisponível<br/><small>The INSS product is temporarily unavailable</small> |
| <a id="SSC000047"></a>`SSC000047` | 400 |  |
| <a id="SSC000048"></a>`SSC000048` | 500 |  |
| <a id="SSC000050"></a>`SSC000050` | 400 | **Invalid Contract Interest**<br/> |
| <a id="SSC000051"></a>`SSC000051` | 500 | **Internal Error**<br/>Erro ao criar instâncias do redis.<br/><small>Erro while creating redis instances.</small> |
| <a id="SSC000053"></a>`SSC000053` | 400 | **Reservation Cannot Be Suspended**<br/>Status {status}, reserva com status diferente de reservado não pode ser suspensa<br/><small>Status {status}, reservation other than reserved status cannot be suspended</small> |
| <a id="SSC000054"></a>`SSC000054` | 400 | **Document Submission Cannot Be Suspended**<br/>Reserva em processo de envio de documento, tente novamente mais tarde<br/><small>Reservation in document submission process, please try again later</small> |
| <a id="SSC000056"></a>`SSC000056` | 400 | **Reservation can**<br/> |
| <a id="SSC000057"></a>`SSC000057` | 400 | **Reservation can**<br/>Código de sucesso desconhecido: {code} para o endpoint requisitado.<br/><small>Unknown success code: {code} to requested endpoint.</small> |
| <a id="SSC000059"></a>`SSC000059` | 400 | **Reservation amount greater than available total balance**<br/>O valor da parcela: {reservation_amount} é maior que o valor total disponível (valor da parcela do contrato de origem + margem total disponível) : {total_amount_available}. Margem total diponível: {available_total_balance}.<br/><small>The installment face value: {reservation_amount} is greater than the available total balance (origin installment face value + available total balance):{total_amount_available}. Available total balance: {available_total_balance}.</small> |
| <a id="SSC000060"></a>`SSC000060` | 400 | **Invalid document size**<br/>O documento: {document_type} deve ter no mínimo 250x250px e no máximo 5MB.<br/><small>The document: {document_type} should have at least 250x250px and at most 5MB.</small> |
| <a id="SSC000061"></a>`SSC000061` | 400 | **Invalid document format**<br/>O documento: {document_type} deve estar no formato JPEG.<br/><small>The document: {document_type} should be in JPEG format.</small> |
| <a id="SSC000062"></a>`SSC000062` | 400 | **Status does not allow patch**<br/>Reserva {reservation_key} está no status {status_enum}. Portanto não pode ter o campo {field_name} alterado<br/><small>Reservation {reservation_key} is on status {status_enum}. Which does not allow the field {field_name} to be changed</small> |
| <a id="SSC000063"></a>`SSC000063` | 400 | **Broken Document**<br/>O documento: {document_type} está truncado ou corrompido.<br/><small>The document: {document_type} is truncated or broken.</small> |
| <a id="SSC000065"></a>`SSC000065` | 404 | **Balance not Found**<br/>Contrato de origem de portabilidade com chave {origin_contract_key} não foi encontrada.<br/><small>Portability origin contract with key {origin_contract_key} was not found.</small> |
| <a id="SSC000066"></a>`SSC000066` | 409 | **Conflict**<br/>Contrato de Origem de Portabilidade com status {status} não pode ser retentado.<br/><small>Portability Origin Contract Request with status {status} cannot be retried.</small> |
| <a id="SSC000067"></a>`SSC000067` | 409 | **Requester Configuration Already Exists**<br/>Configuração de solicitante já existe.<br/><small>Requester configuration already exists.</small> |
| <a id="SSC000068"></a>`SSC000068` | 400 | **Reservation can**<br/> |
| <a id="SSC000070"></a>`SSC000070` | 404 | **Portability Origin Contract not Found**<br/>Contrato de origem de portabilidade não foi encontrado.<br/><small>Portability Origin Contract was not found.</small> |
| <a id="SSC000074"></a>`SSC000074` | 404 | **Balance not Found**<br/>A consulta de saldo com o cpf {document_number} não foi encontrada.<br/><small>Balance with document number {document_number} was not found.</small> |
| <a id="SSC000075"></a>`SSC000075` | 400 | **Invalid last period due date**<br/>A data de vencimento da última parcela<br/><small>The last period due date</small> |
| <a id="SSC000076"></a>`SSC000076` | 400 | **Success balance request not found**<br/>Uma consulta de saldo válida para o novo número de benefício<br/><small>A success balance request for the new benefit number</small> |
| <a id="SSC000077"></a>`SSC000077` | 404 | **Balance not Found**<br/>A consulta de saldo para o cpf {document_number} com número de benefício {benefit_number} não foi encontrada.<br/><small>Balance for document number {document_number} with benefit number {benefit_number} was not found.</small> |
| <a id="SSC000078"></a>`SSC000078` | 404 | **Invalid Disbursement Date**<br/>A data de desembolso para esta operação está incorreta, ela não está entre a data limite de averbação e a próxima competência.<br/><small>Disbursement date for this operation is incorrect, it is not between the reservation limit and next accrual.</small> |
| <a id="SSC000079"></a>`SSC000079` | 400 | **Invalid Contract Interest Rate**<br/> |
| <a id="SSC000080"></a>`SSC000080` | 429 | **Rate limit exceeded**<br/> |
| <a id="SSC000081"></a>`SSC000081` | 404 | **Requester Configuration Not Found**<br/>Configuração de solicitante<br/><small>Requester configuration</small> |
| <a id="SSC000082"></a>`SSC000082` | 404 | **Bucket Configuration Not Found**<br/>Configuração de balde não encontrada.<br/><small>Bucket configuration not found.</small> |
| <a id="SSC000083"></a>`SSC000083` | 400 | **Reservation Failed**<br/>Última resposta: {cancel_reason}, Fichas disponíveis: {total_tokens}, Próxima Recarga: {next_refill_at}<br/><small>Last Response: {cancel_reason}, Tokens Available: {total_tokens}, Next Refill At: {next_refill_at}</small> |
| <a id="SSC000084"></a>`SSC000084` | 400 | **Bad Request**<br/>A reserva já foi processada e o status mudou para {reservation_status}, Fichas disponíveis: {tokens}<br/><small>The reservation has already been processed and the status has changed to {reservation_status}, Available Tokens: {tokens}</small> |
| <a id="SSC000085"></a>`SSC000085` | 400 | **Bad Request**<br/> |
| <a id="SSC000086"></a>`SSC000086` | 400 | **Bad request**<br/>Número de benefício {benefit_number} é muito longo ou está incorreto.<br/><small>Benefit with number {benefit_number} is too long or incorrect.</small> |
| <a id="SSC000087"></a>`SSC000087` | 400 | **Bad Request**<br/>A data de desembolso {disbursement_date} é muito antiga, atualize-a.<br/><small>Disbursement date {disbursement_date} is too old, update it.</small> |
| <a id="SSC000088"></a>`SSC000088` | 404 | **Reservation not Found**<br/>A reserva com chave de contrato {contract_number} não foi encontrada.<br/><small>Reservation with contract key {contract_number} was not found.</small> |
| <a id="SSC000089"></a>`SSC000089` | 404 | **Period not Found**<br/>O período com competência {competence} não foi encontrado.<br/><small>Period with competence {competence} was not found.</small> |
| <a id="SSC000090"></a>`SSC000090` | 400 | **Operation Canceled Without Installments**<br/>Operação cancelada e sem parcelas.<br/><small>Operation canceled and without installments.</small> |
| <a id="SSC000091"></a>`SSC000091` | 409 | **Refinanced Credit Operation inelegible**<br/>Refinanced Credit Operation {refinanced_co_key} inelegible for refinancing.<br/><small>Operação refinanciada {refinanced_co_key} inelegível para refinaciamento.</small> |
| <a id="SSC000092"></a>`SSC000092` | 400 | **Bad Request**<br/>O benefício {benefit_number} está bloqueado pelo beneficiário. data de bloqueio: {blocked_date}<br/><small>The benefit number {benefit_number} is blocked by the beneficiary. blocked_date: {blocked_date}</small> |
| <a id="SSC000093"></a>`SSC000093` | 400 | **Accrual not Found**<br/>A competência com data {accrual_date} não foi encontrada. O calendário de competência do DATAPREV vai até dezembro do ano atual.<br/><small>Accrual with date {accrual_date} was not found. DATAPREV accrual calendar goes until december of the current year.</small> |
| <a id="SSC000094"></a>`SSC000094` | 400 | **Suspension Reservation Failed**<br/>Suspensão da reserva falhou com código http: {http_code}.<br/><small>Suspension of reservation failed with http code {http_code}.</small> |
| <a id="SSC000095"></a>`SSC000095` | 400 | **Reservation Deleted With Canceled Operation**<br/>Reserva de external key {external_key} está deletada e operação de crédito está cancelada.<br/><small>Reservation with external key {external_key} is deleted and credit operation is canceled.</small> |
| <a id="SSC000096"></a>`SSC000096` | 501 | **Not Implemented**<br/>Não implementado<br/><small>Not implemented</small> |
| <a id="SSC000097"></a>`SSC000097` | 400 | **Deactivated Temporary**<br/>Desativado temporariamente<br/><small>Deactivated temporary</small> |
| <a id="SSC000098"></a>`SSC000098` | 400 | **Wrong reservation amount**<br/>O novo valor da reserva {new_reservation_amount} é diferente do valor da reserva a ser recalculado {reservation_amount_to_recalculate}.<br/><small>New reservation amount {new_reservation_amount} is different from reservation amount to recalculate {reservation_amount_to_recalculate}.</small> |
| <a id="SSC000099"></a>`SSC000099` | 408 | **Gateway Timeout**<br/>O DataPrev nao respondeu a tempo. Tente novamente mais tarde.<br/><small>DataPrev did not respond in time. Please retry later.</small> |

---

# Configurar data de desembolso

URL: /documentation/emissao_de_divida/configurar_data_de_desembolso

## Request

ENDPOINT /debt/ DEBT-KEY /set_disbursement_date
MÉTODO POST

**body.json**

```json
{
    "disbursement_date": "2021-09-01",
    "disbursement_bank_account": {
        "name": "Pedro Felipe Henrique Alves",
        "bank_code": "329",
        "account_digit": "1",
        "branch_number": "001",
        "account_number": "94632180173",
        "document_number": "026.923.850-63"
    }
}

```

:::caution **Atenção!**

 Caso seja optado pela emissão de dívida com múltiplas datas, após a assinatura do contrato a data de desembolso deve ser definida através deste endpoint.

:::

### Path Params

| Campo | tipo | Descrição |
|---|---| ---|
| `debt_key` * | string | Chave da divida devolvida no momento da criação da operação de crédito. |

### Body Params

| Campo | Tipo | Descrição |Caracteres |
|---|---|---|---|
| `disbursement_date` * | date | Data de desembolso da operação. | 10 | 
| `disbursement_bank_account` | object | **[Objeto Disbursement Bank Account](#objeto-disbursement_bank_accounts)** - Dados da conta bancária para desembolso da operação. |  | 

### Objeto Disbursement Bank Account

As informações bancárias para desembolso podem ser alteradas juntamente com a data de desembolso, por padrão, o desembolso é realizado em uma conta de titularidade do devedor.

| Campo                 | Tipo   | Descrição                                                                                          | Máx. Caract. | 
|-----------------------|--------|----------------------------------------------------------------------------------------------------|--------------|
| name                  | string | Nome do titular da conta                                                                           | 50           |
| document_number       | string | CPF do titular da conta                                                                            | 11           |
| bank_code *           | string | Código COMPE da instituição financeira (https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf) | 3            |
| branch_number *       | string | Número da agência (não informar o dígito verificador da agência!)                                  | 4            |
| account_number *      | string | Número da conta (sem o dígito verificador da conta!)                                               | 10           |
| account_digit *       | string | Dígito verificador da conta (informar zero no lugar de letras)                                     | 1            |
| account_type          | enum   | [Enumerador Account Type](#enumerador-account-type) Tipo da conta                                  | 1            |

## Response

STATUS 400

**body.json**

```json
{
  "key": "25dd0a85-dbd7-453f-9076-d776a9ef7c3a",
  "event_datetime": "2022-03-29 15:30:20",
  "data": {},
  "webhook_type": "debt",
  "status": "disbursement_date_set"
}

```

STATUS 400

**body.json**

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

---

# Consulta de dívida

URL: /documentation/emissao_de_divida/consulta_de_divida

## Request

ENDPOINT /debt
MÉTODO GET

## Query Params
| Campo | Tipo | Descrição                                                               | Caracteres |
|---|---|-------------------------------------------------------------------------| ---|
| `key` | string | Chave da divida devolvida no momento da criação da operação de crédito. | - |
| `requester_identifier_key` | string | Chave da UUID4 enviada na criação da dívida.        | - |
| `contract_number` | string | Número da CCB retornado na emissão de dívida.                            | - |
| `issuer_document_number` | string | Número de documento do emitente.                                        | - |
| `issuer_name` | string | Nome do emitente da dívida.                                             | - |
| `status` | string | Status da operação.                                                     | - |
| `page` | string | Página atual que está sendo consultada.                                 | - |
| `page_size` | string | Quantidade de resultados que cabem na página.                           | - |
| `total_due_balance` | boolean | Quando enviado como `true`, inclui o campo `balance_due` (saldo devedor total da operação) na resposta. Por padrão (`false` ou ausente), o `balance_due` **não** é retornado. | - |

:::tip Saldo devedor (`balance_due`)
O campo `balance_due` representa o saldo devedor total da operação e **só é retornado quando a consulta é feita com o parâmetro `total_due_balance=true`**. Sem esse parâmetro, a resposta não traz o saldo devedor.

Exemplo de requisição:

```bash
GET /debt?contract_number=ABC1234&total_due_balance=true
```

Compare os exemplos de resposta abaixo: **"Consulta sem `total_due_balance`"** (sem o campo) e **"Consulta com `total_due_balance=true`"** (com o campo `balance_due`).
:::

:::caution Não combine `total_due_balance` com `key`
O `total_due_balance` só funciona na **consulta por filtros** (sem a `key`). Quando você envia o parâmetro `key`, o endpoint usa a rota de consulta individual por chave, que **ignora** o `total_due_balance` (e os demais filtros) — por isso o `balance_due` não é retornado.

Para obter o `balance_due`, consulte **sem** a `key`, usando os demais filtros. Exemplo:

```bash
GET /debt?total_due_balance=true&contract_number=0369255657%2FMGG&issuer_document_number=05739967929&page_size=10&page=1
```

A resposta vem como uma **lista** (`data: [...]`) e cada item traz o `balance_due`.
:::

## Response

STATUS 200

Response Body: Consulta sem total_due_balance (sem balance_due )

```json
{
  "data": [
    {
      "borrower": {
        "document_number": "68394265057",
        "name": "Xuxa Meneguel"
      },
      "contract_fee_amount": 5.56,
      "installments": [
        {
          "bank_slip_key": null,
          "calendar_days": 57,
          "due_date": "2020-09-30",
          "due_principal": -0.00217819,
          "fine_amount": null,
          "has_interest": true,
          "installment_key": "28eb5907-ed25-4a86-bb9d-b6dc944f13df",
          "installment_number": 1,
          "installment_status": "opened",
          "installment_type": "principal",
          "paid_amount": 0,
          "post_fixed_amount": 0,
          "pre_fixed_amount": 268.75782181,
          "principal_amortization_amount": 1111.9,
          "tax_amount": 0,
          "total_amount": 1380.66,
          "workdays": 40
        }
      ],
      "operation_key": "7986dcc7-4331-478f-af47-adfbdf7f4a36",
      "status": "opened"
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "rows_per_page": 100,
    "total_pages": 1,
    "total_rows": 55
  }
}

```

Response Body: Consulta com total_due_balance=true (com balance_due )

```json
{
  "data": {
    "additional_iof": 11.547136,
    "after_disbursement_actions": [],
    "all_day_disbursement": true,
    "annual_cet": 41.0883,
    "assigned": false,
    "assigned_at": null,
    "assignment_amount": 3038.72,
    "attached_document_list": [
      {
        "created_at": "2022-10-19T11:53:01",
        "document_key": "5df59dca-b8d1-4dca-8358-8b4bd944f3dc",
        "document_type": {
          "enumerator": "document_identification",
          "translation_path": "co.DocumentType.document_identification"
        },
        "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/5df59dca-b8d1-4dca-8358-8b4bd944f3dc/image_1666180300436.jpg",
        "related_party_key": null,
        "signature_required": false,
        "signature_url": null,
        "signed": false
      }
    ],
    "balance_due": 3150.62,
    "base_iof": 27.17569413,
    "calculus_correction": null,
    "central_depository": null,
    "cet": 2.91,
    "cetip_assignments": [],
    "cetip_settlements": [],
    "collateral_constituted": true,
    "collateral_type": null,
    "collaterals": [],
    "contract_fee_amount": 0,
    "contract_fees": [],
    "contract_number": "TESTE118261",
    "created_at": "2022-10-19T11:53:00",
    "credit_operation_key": "438ceaa3-2906-4ee3-85f9-0dcacd5f2581",
    "credit_operation_status": {
      "enumerator": "opened",
      "translation_path": "co.CreditOperationStatus.opened",
      "translation_ptbr": "Desembolsada"
    },
    "credit_operation_type": {
      "enumerator": "ccb",
      "translation_path": "co.CreditOperationType.ccb"
    },
    "credit_rating": null,
    "creditor_bank_account_key": "5d068423-6094-49e4-b15b-7740038295a8",
    "custodian": {
      "enumerator": "qi_scd",
      "translation_path": "co.Custodian.qi_scd"
    },
    "decimal_annual_cet": 0.43241941956989105,
    "decimal_cet": 0.0304,
    "disburse_before_assign": true,
    "disbursed_at": "2022-10-19T11:54:47",
    "disbursed_issue_amount": 3000,
    "disbursement_account": [
      {
        "account_branch": "1234",
        "account_digit": "1",
        "account_number": "2345678601",
        "account_type": "checking_account",
        "amount_receivable": null,
        "created_at": "2022-10-19T11:53:01",
        "digitable_line": null,
        "disbursement_type": "pix",
        "document_number": "92147661180",
        "financial_institutions": {
          "code_number": 104,
          "is_active": true,
          "is_pix_participant": true,
          "ispb": "00360305",
          "name": "CAIXA ECONOMICA FEDERAL"
        },
        "financial_institutions_code_number": 104,
        "is_pix_disbursement": true,
        "ispb": "00360305",
        "name": "104 CAIXA ECONOMICA FEDERAL",
        "percentage_receivable": 100,
        "pix_key": null,
        "pix_transfer_key": "da80477f-412e-40a5-81b0-c830b238081e",
        "pix_type": "manual",
        "qr_code_key": null,
        "retry_counter": 0,
        "retry_vector": null,
        "transaction_key": null,
        "webhook_key": null
      }
    ],
    "disbursement_callback": {
      "installments": [
        {
          "bank_slip_key": "9d8c566a-c865-495e-8764-db8351e7ac41",
          "digitable_line": "32990001031000699925348000000207991730000055231",
          "due_date": "2022-11-18",
          "qr_code_key": "bdd41d56-8588-4468-9705-5233994cdc39",
          "qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/bdd41d56-8588-4468-9705-5233994cdc395204000053039865802BR5925QI SOCIEDADE DE CREDITO D6009Sao Paulo61080145200062070503***63044F44"
        }
      ],
      "key": "438ceaa3-2906-4ee3-85f9-0dcacd5f2581",
      "origin_type": "lego-api",
      "status": "opened",
      "transaction_receipts": [
        {
          "amount": 3000,
          "description": "00360305 1234 2345678601-1 92147661180 - 104 CAIXA ECONOMICA FEDERAL",
          "destination": {
            "account_digit": "1",
            "account_number": "2345678601",
            "bank_ispb": "00360305",
            "branch": "1234",
            "branch_digit": null,
            "document": "92147661180",
            "name": "104 CAIXA ECONOMICA FEDERAL",
            "purpose": "Crédito PIX em Conta",
            "type": "checking_account"
          },
          "fee": 0,
          "origin": {
            "account_branch": "0001",
            "account_digit": "5",
            "account_key": "5d068423-6094-49e4-b15b-7740038295a8",
            "account_number": "00002",
            "bank_code": "329",
            "branch": "0001",
            "branch_digit": null,
            "document": "32402502000135",
            "name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
            "type": "payment_account"
          },
          "origin_transaction_key": null,
          "timestamp": "2022-10-19T11:55:03",
          "transaction_key": "da80477f-412e-40a5-81b0-c830b238081e"
        }
      ]
    },
    "disbursement_confirmed_at": "2022-10-20T13:00:56",
    "disbursement_date": "2022-10-19",
    "disbursement_end_date": "2022-10-19",
    "disbursement_inelegibility_reason": null,
    "disbursement_inelegibility_reason_issued": null,
    "disbursement_options": [
      {
        "additional_iof": 11.547136,
        "annual_cet": 41.0883,
        "assignment_amount": 3038.72,
        "base_iof": 27.17569413,
        "calculus_correction": null,
        "cet": 2.91,
        "contract_fee_amount": 0,
        "contract_fees": [],
        "created_at": "2022-10-19T11:53:01",
        "disbursed_issue_amount": 3000,
        "disbursement_date": "2022-10-19",
        "external_contract_fee_amount": 0,
        "external_contract_fees": [],
        "first_due_date": "2022-11-18",
        "installments": [
          {
            "additional_costs": [],
            "business_due_date": "2022-11-21",
            "calendar_days": 30,
            "created_at": "2022-10-19T11:53:01",
            "due_date": "2022-11-18",
            "due_interest": 0,
            "due_principal": 3038.72,
            "fine_amount": null,
            "has_interest": true,
            "installment_number": 1,
            "post_fixed_amount": 0,
            "pre_fixed_amount": 75.66402982,
            "principal_amortization_amount": 476.64597018,
            "tax_amount": 1.17254909,
            "total_amount": 552.31,
            "workdays": 20
          }
        ],
        "interest_subsidy_amount": 0,
        "issue_amount": 3038.72,
        "net_external_contract_fee_amount": 0,
        "prefixed_interest_rate": null,
        "share_quantity": 4,
        "total_iof": 38.72
      }
    ],
    "disbursement_start_date": "2022-10-19",
    "document_certifier": {
      "enumerator": "electronic_client_side",
      "translation_path": "co.DocumentCertifier.electronic_client_side"
    },
    "early_settlement_configuration": {
      "created_at": "2022-10-19T11:53:00",
      "early_settlement_configuration_type": {
        "enumerator": "fixed_rate",
        "translation_path": "co.EarlySettlementConfigurationType.fixed_rate"
      },
      "effective_end_date": null,
      "fixed_interest_rate": 0
    },
    "endorsement": null,
    "entry": null,
    "events": [],
    "external_contract_fee_amount": 0,
    "external_contract_fees": [],
    "extra_fields": null,
    "facial_biometrics_enabled": false,
    "final_disbursement_amount": 3000,
    "financial_index": null,
    "fine_configuration": {
      "contract_fine_rate": 0.02,
      "created_at": "2022-10-19T11:53:00",
      "fine_delay_rate": {
        "annual_rate": 0.12682503,
        "created_at": "2022-10-19T11:53:00",
        "daily_rate": 0.00033173,
        "interest_base": {
          "enumerator": "calendar_days",
          "translation_path": "co.InterestBase.calendar_days",
          "year_days": 360
        },
        "monthly_rate": 0.01
      }
    },
    "first_due_date": "2022-11-18",
    "first_due_date_delay": null,
    "if_code": null,
    "installments": [
      {
        "accrual_reference_date": null,
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": "9d8c566a-c865-495e-8764-db8351e7ac41",
        "business_due_date": "2022-11-21",
        "calendar_days": 30,
        "cetip_settlements": [],
        "created_at": "2022-10-19T11:53:00",
        "digitable_line": "32990001031000699925348000000207991730000055231",
        "due_date": "2022-11-18",
        "due_interest": 0,
        "due_principal": 3038.72,
        "events": [
          {
            "amount": null,
            "created_at": "2022-10-19T11:54:47",
            "event_date": "2022-10-19T11:54:47",
            "installment_event_type": {
              "enumerator": "open",
              "translation_path": "co.InstallmentEventType.open"
            },
            "installment_old_status": {
              "enumerator": "created",
              "translation_path": "co.InstallmentStatus.created"
            },
            "old_due_date": null
          },
          {
            "amount": null,
            "created_at": "2022-11-18T08:00:10",
            "event_date": "2022-11-18T08:00:10",
            "installment_event_type": {
              "enumerator": "maturity",
              "translation_path": "co.InstallmentEventType.maturity"
            },
            "installment_old_status": {
              "enumerator": "opened",
              "translation_path": "co.InstallmentStatus.opened"
            },
            "old_due_date": null
          },
          {
            "amount": 11.76,
            "created_at": "2022-11-22T08:00:14",
            "event_date": "2022-11-22T08:00:14",
            "installment_event_type": {
              "enumerator": "delay_fine",
              "translation_path": "co.InstallmentEventType.delay_fine"
            },
            "installment_old_status": {
              "enumerator": "waiting_payment",
              "translation_path": "co.InstallmentStatus.waiting_payment"
            },
            "old_due_date": null
          },
          {
            "amount": 11.94,
            "created_at": "2022-11-23T09:13:46",
            "event_date": "2022-11-23T09:13:46",
            "installment_event_type": {
              "enumerator": "delay_fine",
              "translation_path": "co.InstallmentEventType.delay_fine"
            },
            "installment_old_status": {
              "enumerator": "overdue",
              "translation_path": "co.InstallmentStatus.overdue"
            },
            "old_due_date": null
          },
          {
            "amount": 12.12,
            "created_at": "2022-11-24T09:15:55",
            "event_date": "2022-11-24T09:15:55",
            "installment_event_type": {
              "enumerator": "delay_fine",
              "translation_path": "co.InstallmentEventType.delay_fine"
            },
            "installment_old_status": {
              "enumerator": "overdue",
              "translation_path": "co.InstallmentStatus.overdue"
            },
            "old_due_date": null
          },
          {
            "amount": 12.3,
            "created_at": "2022-11-25T09:24:45",
            "event_date": "2022-11-25T09:24:44",
            "installment_event_type": {
              "enumerator": "delay_fine",
              "translation_path": "co.InstallmentEventType.delay_fine"
            },
            "installment_old_status": {
              "enumerator": "overdue",
              "translation_path": "co.InstallmentStatus.overdue"
            },
            "old_due_date": null
          },
          {
            "amount": 12.84,
            "created_at": "2022-11-28T09:37:41",
            "event_date": "2022-11-28T09:37:41",
            "installment_event_type": {
              "enumerator": "delay_fine",
              "translation_path": "co.InstallmentEventType.delay_fine"
            },
            "installment_old_status": {
              "enumerator": "overdue",
              "translation_path": "co.InstallmentStatus.overdue"
            },
            "old_due_date": null
          },
          {
            "amount": 13.02,
            "created_at": "2022-11-29T09:17:44",
            "event_date": "2022-11-29T09:17:44",
            "installment_event_type": {
              "enumerator": "delay_fine",
              "translation_path": "co.InstallmentEventType.delay_fine"
            },
            "installment_old_status": {
              "enumerator": "overdue",
              "translation_path": "co.InstallmentStatus.overdue"
            },
            "old_due_date": null
          }
        ],
        "fine_amount": 13.02,
        "has_interest": true,
        "installment_key": "1d76836e-1fcc-4b67-8c01-64faa43de9c8",
        "installment_number": 1,
        "installment_payment": [],
        "installment_status": {
          "enumerator": "overdue",
          "translation_path": "co.InstallmentStatus.overdue"
        },
        "installment_type": {
          "enumerator": "principal",
          "translation_path": "co.InstallmentType.principal"
        },
        "original_due_principal": 3038.72,
        "original_pre_fixed_amount": 75.66402982,
        "original_principal_amortization_amount": 476.64597018,
        "original_total_amount": 552.31,
        "paid_amount": 0,
        "paid_at": null,
        "payment_type": {
          "enumerator": "bankslip",
          "translation_path": "co.PaymentType.bankslip"
        },
        "post_fixed_amount": 0,
        "pre_fixed_amount": 75.66402982,
        "principal_amortization_amount": 476.64597018,
        "qr_code_key": "bdd41d56-8588-4468-9705-5233994cdc39",
        "qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/bdd41d56-8588-4468-9705-5233994cdc395204000053039865802BR5925QI SOCIEDADE DE CREDITO D6009Sao Paulo61080145200062070503***63044F44",
        "renegotiation_proposal_key": null,
        "tax_amount": 1.17254909,
        "total_accrual_amount": null,
        "total_amount": 565.33,
        "total_paid_amount": 0,
        "updated_at": "2022-11-29T09:17:44",
        "workdays": 20
      },
      {
        "accrual_reference_date": null,
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": "527835e4-7b09-42f2-a7d0-befed3a326fd",
        "business_due_date": "2022-12-20",
        "calendar_days": 31,
        "cetip_settlements": [],
        "created_at": "2022-10-19T11:53:00",
        "digitable_line": "32990001031000699925349000000205492040000055231",
        "due_date": "2022-12-19",
        "due_interest": 0,
        "due_principal": 2562.07402982,
        "events": [
          {
            "amount": null,
            "created_at": "2022-10-19T11:54:47",
            "event_date": "2022-10-19T11:54:47",
            "installment_event_type": {
              "enumerator": "open",
              "translation_path": "co.InstallmentEventType.open"
            },
            "installment_old_status": {
              "enumerator": "created",
              "translation_path": "co.InstallmentStatus.created"
            },
            "old_due_date": null
          }
        ],
        "fine_amount": null,
        "has_interest": true,
        "installment_key": "dde36938-8594-4507-a87d-cd2dd5309817",
        "installment_number": 2,
        "installment_payment": [],
        "installment_status": {
          "enumerator": "opened",
          "translation_path": "co.InstallmentStatus.opened"
        },
        "installment_type": {
          "enumerator": "principal",
          "translation_path": "co.InstallmentType.principal"
        },
        "original_due_principal": 2562.07402982,
        "original_pre_fixed_amount": 65.94922003,
        "original_principal_amortization_amount": 486.36077997,
        "original_total_amount": 552.31,
        "paid_amount": 0,
        "paid_at": null,
        "payment_type": {
          "enumerator": "bankslip",
          "translation_path": "co.PaymentType.bankslip"
        },
        "post_fixed_amount": 0,
        "pre_fixed_amount": 65.94922003,
        "principal_amortization_amount": 486.36077997,
        "qr_code_key": "9d2980e9-fa0c-4b21-a7c5-5ca266c9aba8",
        "qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/9d2980e9-fa0c-4b21-a7c5-5ca266c9aba85204000053039865802BR5925QI SOCIEDADE DE CREDITO D6009Sao Paulo61080145200062070503***6304FBC3",
        "renegotiation_proposal_key": null,
        "tax_amount": 2.43277662,
        "total_accrual_amount": null,
        "total_amount": 552.31,
        "total_paid_amount": 0,
        "updated_at": "2022-10-19T11:56:43",
        "workdays": 21
      },
      {
        "accrual_reference_date": null,
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": "d69c9ab6-01f1-40bb-9519-a06ee2230c22",
        "business_due_date": "2023-01-19",
        "calendar_days": 30,
        "cetip_settlements": [],
        "created_at": "2022-10-19T11:53:00",
        "digitable_line": "32990001031000699925350000000203192340000055231",
        "due_date": "2023-01-18",
        "due_interest": 0,
        "due_principal": 2075.71324985,
        "events": [
          {
            "amount": null,
            "created_at": "2022-10-19T11:54:47",
            "event_date": "2022-10-19T11:54:47",
            "installment_event_type": {
              "enumerator": "open",
              "translation_path": "co.InstallmentEventType.open"
            },
            "installment_old_status": {
              "enumerator": "created",
              "translation_path": "co.InstallmentStatus.created"
            },
            "old_due_date": null
          }
        ],
        "fine_amount": null,
        "has_interest": true,
        "installment_key": "93273ee0-71bd-46a6-b5e2-39e03a365b16",
        "installment_number": 3,
        "installment_payment": [],
        "installment_status": {
          "enumerator": "opened",
          "translation_path": "co.InstallmentStatus.opened"
        },
        "installment_type": {
          "enumerator": "principal",
          "translation_path": "co.InstallmentType.principal"
        },
        "original_due_principal": 2075.71324985,
        "original_pre_fixed_amount": 51.68519286,
        "original_principal_amortization_amount": 500.62480714,
        "original_total_amount": 552.31,
        "paid_amount": 0,
        "paid_at": null,
        "payment_type": {
          "enumerator": "bankslip",
          "translation_path": "co.PaymentType.bankslip"
        },
        "post_fixed_amount": 0,
        "pre_fixed_amount": 51.68519286,
        "principal_amortization_amount": 500.62480714,
        "qr_code_key": "d79eb27b-7a1e-4d4c-94a1-f20045c4904e",
        "qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/d79eb27b-7a1e-4d4c-94a1-f20045c4904e5204000053039865802BR5925QI SOCIEDADE DE CREDITO D6009Sao Paulo61080145200062070503***6304E949",
        "renegotiation_proposal_key": null,
        "tax_amount": 3.73566231,
        "total_accrual_amount": null,
        "total_amount": 552.31,
        "total_paid_amount": 0,
        "updated_at": "2022-10-19T11:56:43",
        "workdays": 22
      },
      {
        "accrual_reference_date": null,
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": "5c62c50f-5326-4226-b154-a0cc6d2f62e7",
        "business_due_date": "2023-02-23",
        "calendar_days": 35,
        "cetip_settlements": [],
        "created_at": "2022-10-19T11:53:00",
        "digitable_line": "32990001031000699925351000000201192690000055231",
        "due_date": "2023-02-22",
        "due_interest": 0,
        "due_principal": 1575.08844271,
        "events": [
          {
            "amount": null,
            "created_at": "2022-10-19T11:54:47",
            "event_date": "2022-10-19T11:54:47",
            "installment_event_type": {
              "enumerator": "open",
              "translation_path": "co.InstallmentEventType.open"
            },
            "installment_old_status": {
              "enumerator": "created",
              "translation_path": "co.InstallmentStatus.created"
            },
            "old_due_date": null
          }
        ],
        "fine_amount": null,
        "has_interest": true,
        "installment_key": "1f7b16fe-04b6-4f07-a807-eb3501e44e0d",
        "installment_number": 4,
        "installment_payment": [],
        "installment_status": {
          "enumerator": "opened",
          "translation_path": "co.InstallmentStatus.opened"
        },
        "installment_type": {
          "enumerator": "principal",
          "translation_path": "co.InstallmentType.principal"
        },
        "original_due_principal": 1575.08844271,
        "original_pre_fixed_amount": 45.8505547,
        "original_principal_amortization_amount": 506.4594453,
        "original_total_amount": 552.31,
        "paid_amount": 0,
        "paid_at": null,
        "payment_type": {
          "enumerator": "bankslip",
          "translation_path": "co.PaymentType.bankslip"
        },
        "post_fixed_amount": 0,
        "pre_fixed_amount": 45.8505547,
        "principal_amortization_amount": 506.4594453,
        "qr_code_key": "b55464c8-3764-4ee2-a814-ce22396aabe7",
        "qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/b55464c8-3764-4ee2-a814-ce22396aabe75204000053039865802BR5925QI SOCIEDADE DE CREDITO D6009Sao Paulo61080145200062070503***63044215",
        "renegotiation_proposal_key": null,
        "tax_amount": 5.23273899,
        "total_accrual_amount": null,
        "total_amount": 552.31,
        "total_paid_amount": 0,
        "updated_at": "2022-10-19T11:56:43",
        "workdays": 23
      },
      {
        "accrual_reference_date": null,
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": "256be15f-dcc6-4775-8298-c3efde5a1147",
        "business_due_date": "2023-03-21",
        "calendar_days": 26,
        "cetip_settlements": [],
        "created_at": "2022-10-19T11:53:00",
        "digitable_line": "32990001031000699925352000000209192950000055231",
        "due_date": "2023-03-20",
        "due_interest": 0,
        "due_principal": 1068.62899741,
        "events": [
          {
            "amount": null,
            "created_at": "2022-10-19T11:54:47",
            "event_date": "2022-10-19T11:54:47",
            "installment_event_type": {
              "enumerator": "open",
              "translation_path": "co.InstallmentEventType.open"
            },
            "installment_old_status": {
              "enumerator": "created",
              "translation_path": "co.InstallmentStatus.created"
            },
            "old_due_date": null
          }
        ],
        "fine_amount": null,
        "has_interest": true,
        "installment_key": "3ed37dc1-61f8-44f1-af21-a55f0cf0795d",
        "installment_number": 5,
        "installment_payment": [],
        "installment_status": {
          "enumerator": "opened",
          "translation_path": "co.InstallmentStatus.opened"
        },
        "installment_type": {
          "enumerator": "principal",
          "translation_path": "co.InstallmentType.principal"
        },
        "original_due_principal": 1068.62899741,
        "original_pre_fixed_amount": 23.02305805,
        "original_principal_amortization_amount": 529.28694195,
        "original_total_amount": 552.31,
        "paid_amount": 0,
        "paid_at": null,
        "payment_type": {
          "enumerator": "bankslip",
          "translation_path": "co.PaymentType.bankslip"
        },
        "post_fixed_amount": 0,
        "pre_fixed_amount": 23.02305805,
        "principal_amortization_amount": 529.28694195,
        "qr_code_key": "64e05528-83fb-432a-8af7-491ca4eb7b90",
        "qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/64e05528-83fb-432a-8af7-491ca4eb7b905204000053039865802BR5925QI SOCIEDADE DE CREDITO D6009Sao Paulo61080145200062070503***630472F7",
        "renegotiation_proposal_key": null,
        "tax_amount": 6.59703244,
        "total_accrual_amount": null,
        "total_amount": 552.31,
        "total_paid_amount": 0,
        "updated_at": "2022-10-19T11:56:43",
        "workdays": 18
      },
      {
        "accrual_reference_date": null,
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": "a8c2edaa-ed3d-4c5b-808e-b26947a5e79e",
        "business_due_date": "2023-04-19",
        "calendar_days": 29,
        "cetip_settlements": [],
        "created_at": "2022-10-19T11:53:01",
        "digitable_line": "32990001031000699925353000000207293240000055232",
        "due_date": "2023-04-18",
        "due_interest": 0,
        "due_principal": 539.34205545,
        "events": [
          {
            "amount": null,
            "created_at": "2022-10-19T11:54:47",
            "event_date": "2022-10-19T11:54:47",
            "installment_event_type": {
              "enumerator": "open",
              "translation_path": "co.InstallmentEventType.open"
            },
            "installment_old_status": {
              "enumerator": "created",
              "translation_path": "co.InstallmentStatus.created"
            },
            "old_due_date": null
          }
        ],
        "fine_amount": null,
        "has_interest": true,
        "installment_key": "2b58b2be-89cd-4710-a6a5-81180938b501",
        "installment_number": 6,
        "installment_payment": [],
        "installment_status": {
          "enumerator": "opened",
          "translation_path": "co.InstallmentStatus.opened"
        },
        "installment_type": {
          "enumerator": "principal",
          "translation_path": "co.InstallmentType.principal"
        },
        "original_due_principal": 539.34205545,
        "original_pre_fixed_amount": 12.97660456,
        "original_principal_amortization_amount": 539.34339544,
        "original_total_amount": 552.32,
        "paid_amount": 0,
        "paid_at": null,
        "payment_type": {
          "enumerator": "bankslip",
          "translation_path": "co.PaymentType.bankslip"
        },
        "post_fixed_amount": 0,
        "pre_fixed_amount": 12.97660456,
        "principal_amortization_amount": 539.34339544,
        "qr_code_key": "dcc7d257-e6a1-4d0a-88f7-1acf662482b5",
        "qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/dcc7d257-e6a1-4d0a-88f7-1acf662482b55204000053039865802BR5925QI SOCIEDADE DE CREDITO D6009Sao Paulo61080145200062070503***6304C9A1",
        "renegotiation_proposal_key": null,
        "tax_amount": 8.00493468,
        "total_accrual_amount": null,
        "total_amount": 552.32,
        "total_paid_amount": 0,
        "updated_at": "2022-10-19T11:56:43",
        "workdays": 20
      }
    ],
    "interest_grace_period": 0,
    "interest_payment_month_period": 1,
    "interest_subsidy_amount": 0,
    "interest_subsidy_percentage": 0,
    "interest_type": {
      "enumerator": "pre_price_days",
      "translation_path": "co.InterestType.pre_price_days"
    },
    "iof_charge_method": "financed",
    "ipoc_code": "324025020203192147661180DiDi118261",
    "is_allowed_to_disburse": true,
    "is_portability": false,
    "is_refinancing": 0,
    "isin_number": null,
    "issue_amount": 3038.72,
    "issue_date": "2022-10-19",
    "issuer_document_number": "92147661180",
    "issuer_name": "Wxy  Wsx",
    "kyc": null,
    "modality": {
      "code": "0203",
      "description": "crédito pessoal - sem consignação em folha de pagam.",
      "enumerator": null,
      "visible": true
    },
    "net_external_contract_fee_amount": 0,
    "next_due_date": "2022-12-19",
    "number_of_installments": 6,
    "operation_extra_fields": null,
    "operation_type": {
      "enumerator": "structured_operation",
      "translation_path": "co.OperationType.structured_operation"
    },
    "origin_key": "438ceaa3-2906-4ee3-85f9-0dcacd5f2581",
    "origin_type": {
      "enumerator": "lego-api",
      "translation_path": "co.OriginType.lego-api"
    },
    "original_prefixed_interest_rate": {
      "annual_rate": 0.34331516,
      "created_at": "2022-10-19T11:53:00",
      "daily_rate": 0.00082017,
      "interest_base": {
        "enumerator": "calendar_days",
        "translation_path": "co.InterestBase.calendar_days",
        "year_days": 360
      },
      "monthly_rate": 0.0249
    },
    "original_total_iof": 38.72,
    "payment_and_settlement_agent": {
      "enumerator": "qi_scd",
      "translation_path": "co.PaymentAndSettlementAgent.qi_scd"
    },
    "payment_type": {
      "enumerator": "bankslip",
      "translation_path": "co.PaymentType.bankslip"
    },
    "payroll_data": null,
    "portability_amount": null,
    "portability_financial_institution_code_number": null,
    "portability_original_contract": null,
    "post_fixed_interest_base": {
      "enumerator": "workdays",
      "translation_path": "co.InterestBase.workdays",
      "year_days": 252
    },
    "post_fixed_interest_rate": null,
    "prefixed_interest_rate": {
      "annual_rate": 0.34331516,
      "created_at": "2022-10-19T11:53:00",
      "daily_rate": 0.00082017,
      "interest_base": {
        "enumerator": "calendar_days",
        "translation_path": "co.InterestBase.calendar_days",
        "year_days": 360
      },
      "monthly_rate": 0.0249
    },
    "principal_amortization_month_period": 1,
    "principal_grace_period": 0,
    "purchaser_document_number": "32402502000135",
    "rebate_account": null,
    "refinanced_credit_operations": [],
    "registration_institution": {
      "enumerator": "qi_scd",
      "translation_path": "co.RegistrationInstitution.qi_scd"
    },
    "related_party_list": [
      {
        "address": {
          "city": "Aguascalientes",
          "complement": null,
          "created_at": "2022-10-19T11:52:59",
          "neighborhood": "Aguascalientes",
          "number": "1",
          "postal_code": "20000000",
          "state": "SP",
          "street": "Zona Centro"
        },
        "attached_document_list": [
          {
            "created_at": "2022-10-19T11:53:01",
            "document_key": "5df59dca-b8d1-4dca-8358-8b4bd944f3dc",
            "document_type": {
              "enumerator": "document_identification",
              "translation_path": "co.DocumentType.document_identification"
            },
            "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/5df59dca-b8d1-4dca-8358-8b4bd944f3dc/image_1666180300436.jpg",
            "related_party_key": null,
            "signature_required": false,
            "signature_url": null,
            "signed": false
          }
        ],
        "birth_date": "1997-10-19",
        "birth_place": null,
        "cnae_code": null,
        "company_document_number": null,
        "created_at": "2022-10-19T11:53:01",
        "document_identification_date": null,
        "document_identification_number": "",
        "document_identification_type": null,
        "email": "wxr@ff.com",
        "foundation_date": null,
        "gender": null,
        "income": 0.01,
        "individual_document_number": "92147661180",
        "is_pep": false,
        "marital_status": {
          "enumerator": "single",
          "translation_path": "co.MaritalStatus.single"
        },
        "mother_name": null,
        "name": "Wxy  Wsx",
        "nationality": "nationality",
        "person_type": "natural",
        "phone": {
          "area_code": "00",
          "country_code": "055",
          "created_at": "2022-10-19T11:53:00",
          "number": "016048311",
          "phone_key": "341d7c67-963c-49a5-b585-265425d71f52",
          "phone_type": null
        },
        "profession": null,
        "property_system": null,
        "related_party_key": "203b2ada-ff3e-44a6-a843-f244aa1afbc9",
        "revenue": null,
        "role_type": {
          "enumerator": "issuer",
          "translation_path": "co.RoleType.issuer"
        },
        "simples_nacional_participant": null,
        "spouse_document_number": null,
        "trading_name": null
      }
    ],
    "requester_identifier_key": "89bb875a4a654ecfbad0c6ce0b3b5037",
    "requester_key": "75f2ab85-a5ce-40b9-9b1e-915175906d78",
    "requester_name": "DiDi Global (99Pay)",
    "resource_source_account": {
      "enumerator": "third_party",
      "translation_path": "co.ResourceSourceAccount.third_party"
    },
    "selfie_enabled": false,
    "settlement_bank_account_key": null,
    "share_quantity": 4,
    "signature_method": {
      "enumerator": "email"
    },
    "tax_configuration": {
      "created_at": "2019-03-15T13:09:32",
      "iof_additional_rate": 0.0038,
      "iof_rate": 0.000082
    },
    "tax_exempt_amount": null,
    "third_party_account_key": "5d068423-6094-49e4-b15b-7740038295a8",
    "total_iof": 38.72
  },
  "operation_key": "438ceaa3-2906-4ee3-85f9-0dcacd5f2581",
  "status": "opened",
  "webhook_type": "signed_debt"
}

```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

## Query Params
| Campo | Tipo | Descrição                                                               | Caracteres |
|---|---|-------------------------------------------------------------------------| ---|
| `key` | string | Chave da divida devolvida no momento da criação da operação de crédito. | - |
| `requester_identifier_key` | string | Chave da UUID4 enviada na criação da dívida.        | - |
| `contract_number` | string | Número da CCB retornado na emissão de dívida.                            | - |
| `issuer_document_number` | string | Número de documento do emitente.                                        | - |
| `issuer_name` | string | Nome do emitente da dívida.                                             | - |
| `status` | string | Status da operação.                                                     | - |
| `page` | string | Página atual que está sendo consultada.                                 | - |
| `page_size` | string | Quantidade de resultados que cabem na página.                           | - |
| `total_due_balance` | boolean | Quando enviado como `true`, inclui o campo `balance_due` (saldo devedor total da operação) na resposta. Por padrão, o `balance_due` **não** é retornado. | - |

---

# Consulta de dívida por Contract Number

URL: /documentation/emissao_de_divida/consulta_por_contract_number

## Request

ENDPOINT /v2/credit_operation/contract_number/ CONTRACT-NUMBER
MÉTODO GET

## ⚠️ Observação Importante

Caso o número do contrato contenha uma barra (`/`), é necessário **encodar a barra** para `%2F`.

### Exemplo prático
**Entrada original:**
```
contract_number = 02159312/FGP
```

**Deve ser enviada como:**
```
02159312%2FFGP
```

### Exemplo em Python para encodar:
```python
import urllib.parse

contract_number = "02159312/FGP"
encoded_contract_number = urllib.parse.quote(contract_number)
print(encoded_contract_number)  # 02159312%2FFGP
```

:::

### Path params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|   
| `contract_number` * | string | Número do contrato de crédito. | string |

## Response

STATUS 200

Response Body

```json
{
  "credit_operation_key": "eaf5836a-ea6f-4baa-ac26-ce5199dfa448",
  "issue_amount": 1006.77,
  "origin_key": "52539e23-5c01-4b9c-8a68-6ed750ec7bc5",
  "assigned_at": "2025-08-24T10:00:00Z",
  "total_iof": 6.77,
  "disbursement_start_date": "2022-08-24",
  "disbursement_end_date": "2022-08-24",
  "issue_date": "2022-08-24",
  "requester_identifier_key": "5cb7456c-f2e3-41b3-b17a-ad47ba3c3cda",
  "installments": [
    {
      "business_due_date": "2022-08-30",
      "due_date": "2022-08-29",
      "calendar_days": 5,
      "due_interest": 0,
      "due_principal": 1006.77,
      "fine_amount": 0,
      "has_interest": true,
      "post_fixed_amount": 0,
      "pre_fixed_amount": 18.93,
      "principal_amortization_amount": 363.14,
      "tax_amount": 0.15,
      "total_amount": 382.07,
      "workdays": 3,
      "accrual_reference_date": null,
      "advanced_paid_amount": 0.0,
      "bank_slip_key": null,
      "digitable_line": null,
      "installment_key": "b56f61ec-202c-4a7a-8a5e-11f90972bae8",
      "installment_status": "created",
      "installment_type": "principal",
      "original_due_principal": 1006.77,
      "original_pre_fixed_amount": 18.93,
      "original_principal_amortization_amount": 363.14,
      "paid_amount": 0.0,
      "original_total_amount": 382.07,
      "qr_code_key": null,
      "qr_code_url": null,
      "renegotiation_proposal_key": null,
      "total_accrual_amount": 0,
      "total_paid_amount": 0,
      "installment_number": 1,
      "paid_at": null,
      "updated_at": null,
      "principal_amortization_payment_amount": 0,
      "prefixed_interest_payment_amount": 0
    },
    {
      "business_due_date": "2022-09-30",
      "due_date": "2022-09-29",
      "calendar_days": 31,
      "due_interest": 0,
      "due_principal": 643.63499424,
      "fine_amount": 0,
      "has_interest": true,
      "post_fixed_amount": 0,
      "pre_fixed_amount": 78.82,
      "principal_amortization_amount": 303.25,
      "tax_amount": 0.9,
      "total_amount": 382.07,
      "workdays": 22,
      "accrual_reference_date": null,
      "advanced_paid_amount": 0.0,
      "bank_slip_key": null,
      "digitable_line": null,
      "installment_key": "2a95a560-bec6-4207-9a38-98c72e023c59",
      "installment_status": "created",
      "installment_type": "principal",
      "original_due_principal": 643.63,
      "original_pre_fixed_amount": 78.82,
      "original_principal_amortization_amount": 303.25,
      "paid_amount": 0.0,
      "original_total_amount": 382.07,
      "qr_code_key": null,
      "qr_code_url": null,
      "renegotiation_proposal_key": null,
      "total_accrual_amount": 0,
      "total_paid_amount": 0,
      "installment_number": 2,
      "paid_at": null,
      "updated_at": null,
      "principal_amortization_payment_amount": 0,
      "prefixed_interest_payment_amount": 0
    },
    {
      "business_due_date": "2022-11-01",
      "due_date": "2022-10-31",
      "calendar_days": 32,
      "due_interest": 0,
      "due_principal": 340.38585509,
      "fine_amount": 0,
      "has_interest": true,
      "post_fixed_amount": 0,
      "pre_fixed_amount": 41.68,
      "principal_amortization_amount": 340.39,
      "tax_amount": 1.9,
      "total_amount": 382.07,
      "workdays": 21,
      "accrual_reference_date": null,
      "advanced_paid_amount": 0.0,
      "bank_slip_key": null,
      "digitable_line": null,
      "installment_key": "61924f59-11e3-49d0-9cf7-2a1d0ce54924",
      "installment_status": "created",
      "installment_type": "principal",
      "original_due_principal": 340.39,
      "original_pre_fixed_amount": 41.68,
      "original_principal_amortization_amount": 340.39,
      "paid_amount": 0.0,
      "original_total_amount": 382.07,
      "qr_code_key": null,
      "qr_code_url": null,
      "renegotiation_proposal_key": null,
      "total_accrual_amount": 0,
      "total_paid_amount": 0,
      "installment_number": 3,
      "paid_at": null,
      "updated_at": null,
      "principal_amortization_payment_amount": 0,
      "prefixed_interest_payment_amount": 0
    }
  ],
  "first_due_date": "2022-08-29",
  "requester_key": "52f36417-368e-4f5b-8841-71e3b9caa72f",
  "original_total_iof": 6.77,
  "contract_number": "0000000001/WO",
  "credit_operation_status_enumerator": "waiting_signature",
  "operation_type_enumerator": "structured_operation",
  "disbursement_date": "2022-08-24",
  "issuer_name": "Wilker Oliveiraço",
  "issuer_document_number": "37197645832",
  "external_contract_fees": [
    {
      "amount_type": {
        "enumerator": "percentage"
      },
      "fee_amount": 0.0,
      "tax_amount": 0.0,
      "irrf_amount": 0.0,
      "amount": 0.0,
      "pis_amount": 0.0,
      "amount_released": 0.0,
      "fee_type": {
        "enumerator": "tac"
      },
      "cofins_amount": 0.0,
      "csll_amount": 0.0,
      "description": null,
      "net_fee_amount": 0.0,
      "rebate_account": null,
      "billing_type": {
        "enumerator": "disbursement"
      },
      "created_at": "2025-10-14T22:18:07"
    },
    {
      "amount_type": {
        "enumerator": "absolute"
      },
      "fee_amount": 0.0,
      "tax_amount": 0.0,
      "irrf_amount": 0.0,
      "amount": 0.0,
      "pis_amount": 0.0,
      "amount_released": 0.0,
      "fee_type": {
        "enumerator": "spread_tax_free"
      },
      "cofins_amount": 0.0,
      "csll_amount": 0.0,
      "description": null,
      "net_fee_amount": 0.0,
      "rebate_account": null,
      "billing_type": {
        "enumerator": "disbursement"
      },
      "created_at": "2025-10-14T22:18:07"
    },
    {
      "amount_type": {
        "enumerator": "absolute"
      },
      "fee_amount": 0.0,
      "tax_amount": 0.0,
      "irrf_amount": 0.0,
      "amount": 0.0,
      "pis_amount": 0.0,
      "amount_released": 0.0,
      "fee_type": {
        "enumerator": "tac_tax_free"
      },
      "cofins_amount": 0.0,
      "csll_amount": 0.0,
      "description": null,
      "net_fee_amount": 0.0,
      "rebate_account": null,
      "billing_type": {
        "enumerator": "disbursement"
      },
      "created_at": "2025-10-14T22:18:07"
    }
  ]
}
```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

---

# Consulta de dívida por Credit Operation Key

URL: /documentation/emissao_de_divida/consulta_por_credit_operation_key

## Request

ENDPOINT /v2/credit_operation/ CREDIT-OPERATION-KEY
MÉTODO GET

### Path params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|   
| `credit_operation_key` * | string | Chave da operação de crédito. | UUID |

### Query params

| Campo | Tipo | Descrição | Default |
|---|---|---|---|
| `eval_present_value` | boolean | Quando `true`, calcula o valor presente de cada parcela e retorna o campo `present_amount` em cada item de `installments`, além de um `present_amount` na raiz com a soma das parcelas. Não pode ser usado para operações nos status: `waiting_signature`, `signed`, `issued`, `canceled`, `canceled_permanently` ou `amended`. | `false` |
| `calculate_delay` | boolean | Considera juros de mora no cálculo do valor presente. Só tem efeito quando `eval_present_value=true`. | `false` |
| `calculate_spread` | boolean | Considera o spread no cálculo do valor presente. Só tem efeito quando `eval_present_value=true`. | `true` |
| `present_value_reference_date` | string (date) | Data de referência (`YYYY-MM-DD`) usada como base para o cálculo do valor presente. Só tem efeito quando `eval_present_value=true`. | hoje |

## Response

STATUS 200

### Como o retorno varia por tipo de operação

A **estrutura** do corpo é sempre a mesma, qualquer que seja o tipo da operação: os campos
que não se aplicam vêm `null` ou como lista vazia, nunca ausentes. Os únicos campos que
aparecem condicionalmente são os do cálculo de valor presente (`present_amount`,
`remaining_principal_disbursement_amount` e `remaining_principal_iof_amount`), e quem os
liga é o query param `eval_present_value`, não o tipo da operação.

O que muda entre os cenários é o **conteúdo**:

| Cenário | `operation_type_enumerator` | `refinanced_credit_operations` | `disbursement_accounts` | `final_disbursement_amount` |
|---|---|---|---|---|
| Portabilidade | `portability` | `[]` | `[]` | `0` |
| Refinanciamento | `refinancing` | um ou mais itens: os contratos quitados | conta do cliente | troco liberado |
| Port + Refin, perna de portabilidade | `portability_for_refinancing` | `[]` | `[]` | `0` |
| Port + Refin, perna de refinanciamento | `refinancing_from_portability` | 1 item: a perna de portabilidade | conta do cliente | troco liberado |

Trate `refinanced_credit_operations` como lista: um refinanciamento pode consolidar vários
contratos num só, e nesse caso a lista traz um item por contrato quitado. Só na perna de
refinanciamento de um port + refin ela tem sempre exatamente um item, que é a perna de
portabilidade.

`final_disbursement_amount` é o valor que efetivamente chega ao cliente: é o
`disbursement_issue_amount` menos o que foi usado para liquidar dívida — o saldo devedor do
contrato portado, na portabilidade, ou a soma dos `due_balance` de
`refinanced_credit_operations`, no refinanciamento. Numa portabilidade pura ele é `0`, porque
todo o valor vai liquidar o contrato de origem.

:::caution Port + Refin são duas operações, não uma
Uma operação de portabilidade com refinanciamento gera **dois `credit_operation_key`
distintos**, e cada um responde a uma chamada separada deste endpoint. As duas pernas se
reconhecem assim:

- compartilham o mesmo `origin_key`;
- a perna de portabilidade tem `operation_type_enumerator: "portability_for_refinancing"` e
  `refinanced_credit_operations: []`;
- a perna de refinanciamento tem `operation_type_enumerator: "refinancing_from_portability"`
  e um item em `refinanced_credit_operations` cujo `refinanced_credit_operation_key` é o
  `credit_operation_key` da perna de portabilidade.

Consultar apenas a perna de portabilidade e concluir que não houve refinanciamento é o erro
mais comum na integração desse fluxo.
:::

:::info Sobre os exemplos abaixo
O array `installments` foi truncado nas duas primeiras parcelas para manter os exemplos
legíveis — o campo `number_of_installments` indica o total real de cada operação. Todos os
demais campos são exibidos por inteiro, na mesma ordem em que a API os devolve.
:::

Response Body

**Portabilidade**

```json
{
  "credit_operation_key": "a1e60001-0000-4000-8000-000000000001",
  "issue_amount": 13752.54,
  "origin_key": "a1e60002-0000-4000-8000-000000000002",
  "total_iof": 0.0,
  "assigned_at": null,
  "disbursement_start_date": "2026-08-28",
  "disbursement_end_date": "2026-08-28",
  "issue_date": "2026-08-28",
  "requester_identifier_key": null,
  "installments": [
    {
      "business_due_date": "2026-10-13",
      "due_date": "2026-10-10",
      "calendar_days": 43,
      "due_interest": 0,
      "due_principal": 13752.54,
      "fine_amount": 0,
      "has_interest": true,
      "post_fixed_amount": 0,
      "pre_fixed_amount": 299.25,
      "principal_amortization_amount": 0.0,
      "tax_amount": 0,
      "total_amount": 299.25,
      "workdays": 29,
      "accrual_reference_date": "2026-09-10",
      "advanced_paid_amount": 0.0,
      "bank_slip_key": null,
      "digitable_line": null,
      "installment_key": "a1e60003-0000-4000-8000-000000000003",
      "installment_status": "unmonitored",
      "installment_type": "principal",
      "original_due_principal": 13752.54,
      "original_pre_fixed_amount": 299.25,
      "original_principal_amortization_amount": 0.0,
      "paid_amount": 0.0,
      "original_total_amount": 299.25,
      "qr_code_key": null,
      "qr_code_url": null,
      "renegotiation_proposal_key": null,
      "total_accrual_amount": 0,
      "total_paid_amount": 0,
      "installment_number": 1,
      "paid_at": null,
      "updated_at": "2026-08-28T10:00:47",
      "principal_amortization_payment_amount": 0,
      "prefixed_interest_payment_amount": 0
    },
    {
      "business_due_date": "2026-11-10",
      "due_date": "2026-11-10",
      "calendar_days": 31,
      "due_interest": 35,
      "due_principal": 13752.54,
      "fine_amount": 0,
      "has_interest": true,
      "post_fixed_amount": 0,
      "pre_fixed_amount": 276.68,
      "principal_amortization_amount": 22.57,
      "tax_amount": 0,
      "total_amount": 299.25,
      "workdays": 20,
      "accrual_reference_date": "2026-09-10",
      "advanced_paid_amount": 0.0,
      "bank_slip_key": null,
      "digitable_line": null,
      "installment_key": "a1e60004-0000-4000-8000-000000000004",
      "installment_status": "unmonitored",
      "installment_type": "principal",
      "original_due_principal": 13752.54,
      "original_pre_fixed_amount": 276.68,
      "original_principal_amortization_amount": 22.57,
      "paid_amount": 0.0,
      "original_total_amount": 299.25,
      "qr_code_key": null,
      "qr_code_url": null,
      "renegotiation_proposal_key": null,
      "total_accrual_amount": 22.73,
      "total_paid_amount": 0,
      "installment_number": 2,
      "paid_at": null,
      "updated_at": "2026-08-28T10:00:47",
      "principal_amortization_payment_amount": 0,
      "prefixed_interest_payment_amount": 0
    }
  ],
  "first_due_date": "2026-10-10",
  "requester_key": "a1e60060-0000-4000-8000-000000000096",
  "original_total_iof": null,
  "contract_number": "0000004521/AB",
  "credit_operation_status_enumerator": "opened",
  "operation_type_enumerator": "portability",
  "disbursement_date": "2026-08-28",
  "issuer_name": "Maria Aparecida Ferreira",
  "issuer_document_number": "12345678909",
  "external_contract_fees": [],
  "cet": 1.72,
  "annual_cet": 22.65,
  "final_disbursement_amount": 0.0,
  "number_of_installments": 93,
  "disbursement_issue_amount": 13752.54,
  "prefixed_interest_rate": {
    "annual_rate": 0.2230627564,
    "daily_rate": 0.0005594847,
    "interest_base": {
      "enumerator": "calendar_days",
      "year_days": 360
    },
    "monthly_rate": 0.0169214198
  },
  "fine_configuration": {
    "contract_fine_rate": 0.02,
    "fine_delay_rate": {
      "annual_rate": 0.0,
      "daily_rate": 0.0,
      "interest_base": {
        "enumerator": "calendar_days",
        "year_days": 360
      },
      "monthly_rate": 0.0
    }
  },
  "attached_documents": [
    {
      "document_key": "a1e60061-0000-4000-8000-000000000097",
      "document_url": "https://storage.googleapis.com/qi-documents-example/documento-99.jpeg",
      "signature_url": null,
      "document_type": "selfie",
      "signature_required": false,
      "signed": false
    },
    {
      "document_key": "a1e60062-0000-4000-8000-000000000098",
      "document_url": "https://storage.googleapis.com/qi-documents-example/documento-101.jpeg",
      "signature_url": null,
      "document_type": "document_identification_back",
      "signature_required": false,
      "signed": false
    },
    {
      "document_key": "a1e60063-0000-4000-8000-000000000099",
      "document_url": "https://storage.googleapis.com/qi-documents-example/documento-103.jpeg",
      "signature_url": null,
      "document_type": "document_identification",
      "signature_required": false,
      "signed": false
    },
    {
      "document_key": "a1e60064-0000-4000-8000-000000000100",
      "document_url": "https://storage.googleapis.com/qi-documents-example/documento-105.pdf",
      "signature_url": "https://storage.googleapis.com/qi-documents-example/signature-106.pdf",
      "document_type": "ccb_pre_price_days",
      "signature_required": true,
      "signed": true
    },
    {
      "document_key": "a1e60065-0000-4000-8000-000000000101",
      "document_url": "https://storage.googleapis.com/qi-documents-example/documento-108.pdf",
      "signature_url": null,
      "document_type": "issuer_informative",
      "signature_required": false,
      "signed": false
    }
  ],
  "related_parties": [
    {
      "related_party_key": "a1e60066-0000-4000-8000-000000000102",
      "role_type": "issuer",
      "person_type": "natural",
      "name": "Maria Aparecida Ferreira",
      "email": "maria.ferreira@example.com",
      "individual_document_number": "12345678909"
    },
    {
      "related_party_key": "a1e60067-0000-4000-8000-000000000103",
      "role_type": "credit_agent",
      "person_type": "natural",
      "name": "Maria Aparecida Ferreira",
      "email": null,
      "individual_document_number": "12345678909"
    }
  ],
  "disbursement_accounts": [],
  "base_iof": null,
  "additional_iof": null,
  "assignment_amount": 14919.97,
  "created_at": "2026-08-28T09:15:01Z",
  "total_prefixed_amount": 14077.71,
  "refinanced_credit_operations": []
}
```

**Refinanciamento**

```json
{
  "credit_operation_key": "a1e60068-0000-4000-8000-000000000104",
  "issue_amount": 32812.16,
  "origin_key": "a1e60068-0000-4000-8000-000000000104",
  "total_iof": 94.27,
  "assigned_at": null,
  "disbursement_start_date": "2026-09-09",
  "disbursement_end_date": "2026-09-12",
  "issue_date": "2026-09-09",
  "requester_identifier_key": "a1e60068-0000-4000-8000-000000000104",
  "installments": [
    {
      "business_due_date": "2026-11-10",
      "due_date": "2026-11-10",
      "calendar_days": 62,
      "due_interest": 0,
      "due_principal": 32812.16,
      "fine_amount": 0,
      "has_interest": true,
      "post_fixed_amount": 0,
      "pre_fixed_amount": 702.93,
      "principal_amortization_amount": 0.0,
      "tax_amount": 0,
      "total_amount": 702.93,
      "workdays": 42,
      "accrual_reference_date": null,
      "advanced_paid_amount": 0.0,
      "bank_slip_key": null,
      "digitable_line": null,
      "installment_key": "a1e60069-0000-4000-8000-000000000105",
      "installment_status": "unmonitored",
      "installment_type": "principal",
      "original_due_principal": 32812.16,
      "original_pre_fixed_amount": 702.93,
      "original_principal_amortization_amount": 0.0,
      "paid_amount": 0.0,
      "original_total_amount": 702.93,
      "qr_code_key": null,
      "qr_code_url": null,
      "renegotiation_proposal_key": null,
      "total_accrual_amount": 0,
      "total_paid_amount": 0,
      "installment_number": 1,
      "paid_at": null,
      "updated_at": "2026-09-10T09:27:00",
      "principal_amortization_payment_amount": 0,
      "prefixed_interest_payment_amount": 0
    },
    {
      "business_due_date": "2026-12-10",
      "due_date": "2026-12-10",
      "calendar_days": 30,
      "due_interest": 508,
      "due_principal": 32812.16,
      "fine_amount": 0,
      "has_interest": true,
      "post_fixed_amount": 0,
      "pre_fixed_amount": 702.93,
      "principal_amortization_amount": 0.0,
      "tax_amount": 0,
      "total_amount": 702.93,
      "workdays": 21,
      "accrual_reference_date": null,
      "advanced_paid_amount": 0.0,
      "bank_slip_key": null,
      "digitable_line": null,
      "installment_key": "a1e6006a-0000-4000-8000-000000000106",
      "installment_status": "unmonitored",
      "installment_type": "principal",
      "original_due_principal": 32812.16,
      "original_pre_fixed_amount": 702.93,
      "original_principal_amortization_amount": 0.0,
      "paid_amount": 0.0,
      "original_total_amount": 702.93,
      "qr_code_key": null,
      "qr_code_url": null,
      "renegotiation_proposal_key": null,
      "total_accrual_amount": 0,
      "total_paid_amount": 0,
      "installment_number": 2,
      "paid_at": null,
      "updated_at": "2026-09-10T09:27:00",
      "principal_amortization_payment_amount": 0,
      "prefixed_interest_payment_amount": 0
    }
  ],
  "first_due_date": "2026-11-10",
  "requester_key": "a1e600d5-0000-4000-8000-000000000213",
  "original_total_iof": null,
  "contract_number": "0000004522/AB",
  "credit_operation_status_enumerator": "opened",
  "operation_type_enumerator": "refinancing",
  "disbursement_date": "2026-09-10",
  "issuer_name": "Maria Aparecida Ferreira",
  "issuer_document_number": "12345678909",
  "external_contract_fees": [],
  "cet": 1.8,
  "annual_cet": 23.91,
  "final_disbursement_amount": 2709.78,
  "number_of_installments": 108,
  "disbursement_issue_amount": 32717.89,
  "prefixed_interest_rate": {
    "annual_rate": 0.2343470806,
    "daily_rate": 0.0005850104,
    "interest_base": {
      "enumerator": "calendar_days",
      "year_days": 360
    },
    "monthly_rate": 0.0177
  },
  "fine_configuration": {
    "contract_fine_rate": 0.0,
    "fine_delay_rate": {
      "annual_rate": 0.12682503,
      "daily_rate": 0.00033173,
      "interest_base": {
        "enumerator": "calendar_days",
        "year_days": 360
      },
      "monthly_rate": 0.01
    }
  },
  "attached_documents": [
    {
      "document_key": "a1e600d6-0000-4000-8000-000000000214",
      "document_url": "https://storage.googleapis.com/qi-documents-example/documento-223.pdf",
      "signature_url": "https://storage.googleapis.com/qi-documents-example/signature-224.pdf",
      "document_type": "ccb_pre_price_days",
      "signature_required": true,
      "signed": true
    },
    {
      "document_key": "a1e600d7-0000-4000-8000-000000000215",
      "document_url": "https://storage.googleapis.com/qi-documents-example/documento-226.jpeg",
      "signature_url": null,
      "document_type": "selfie",
      "signature_required": false,
      "signed": false
    },
    {
      "document_key": "a1e600d8-0000-4000-8000-000000000216",
      "document_url": "https://storage.googleapis.com/qi-documents-example/documento-228.jpg",
      "signature_url": null,
      "document_type": "document_identification",
      "signature_required": false,
      "signed": false
    },
    {
      "document_key": "a1e600d9-0000-4000-8000-000000000217",
      "document_url": "https://storage.googleapis.com/qi-documents-example/documento-230.jpg",
      "signature_url": null,
      "document_type": "document_identification_back",
      "signature_required": false,
      "signed": false
    },
    {
      "document_key": "a1e600da-0000-4000-8000-000000000218",
      "document_url": "https://storage.googleapis.com/qi-documents-example/documento-232.pdf",
      "signature_url": null,
      "document_type": "issuer_informative",
      "signature_required": false,
      "signed": false
    }
  ],
  "related_parties": [
    {
      "related_party_key": "a1e600db-0000-4000-8000-000000000219",
      "role_type": "issuer",
      "person_type": "natural",
      "name": "Maria Aparecida Ferreira",
      "email": "maria.ferreira@example.com",
      "individual_document_number": "12345678909"
    },
    {
      "related_party_key": "a1e600dc-0000-4000-8000-000000000220",
      "role_type": "credit_agent",
      "person_type": "natural",
      "name": "Maria Aparecida Ferreira",
      "email": null,
      "individual_document_number": "12345678909"
    }
  ],
  "disbursement_accounts": [
    {
      "account_branch": "0001",
      "account_digit": "8",
      "account_number": "1234567",
      "account_type": "checking_account",
      "amount_receivable": null,
      "digitable_line": null,
      "disbursement_type": "pix",
      "document_number": "12345678909",
      "end_to_end_id": "E00360305202609101206A1B2C3D4E5F",
      "financial_institutions_code_number": 104,
      "ispb": "00360305",
      "name": "Maria Aparecida Ferreira",
      "percentage_receivable": 100.0,
      "pix_key": null,
      "pix_transfer_key": "a1e600dd-0000-4000-8000-000000000221",
      "pix_type": "manual",
      "qr_code_key": null,
      "qr_code_url": null
    }
  ],
  "base_iof": 83.61,
  "additional_iof": 10.66,
  "assignment_amount": 32861.88,
  "created_at": "2026-09-09T19:59:42Z",
  "total_prefixed_amount": 43104.28,
  "refinanced_credit_operations": [
    {
      "refinanced_credit_operation_key": "a1e600de-0000-4000-8000-000000000222",
      "refinanced_contract_number": "0000004523/AB",
      "due_balance": 30008.11,
      "due_balance_reference_date": "2026-09-09",
      "original_deadline": 2941,
      "refinanced_credit_operation_status_enumerator": "pending_payment",
      "updated_at": "2026-09-10T09:03:56",
      "created_at": "2026-09-09T19:59:42"
    }
  ]
}
```

**Port + Refin**

**Operação 1 de 2 — perna de portabilidade** (`portability_for_refinancing`)

```json
{
  "credit_operation_key": "a1e600df-0000-4000-8000-000000000223",
  "issue_amount": 3932.52,
  "origin_key": "a1e600e0-0000-4000-8000-000000000224",
  "total_iof": 0.0,
  "assigned_at": null,
  "disbursement_start_date": "2026-09-10",
  "disbursement_end_date": "2026-09-10",
  "issue_date": "2026-09-10",
  "requester_identifier_key": null,
  "installments": [
    {
      "business_due_date": "2026-11-10",
      "due_date": "2026-11-10",
      "calendar_days": 61,
      "due_interest": 0,
      "due_principal": 3932.52,
      "fine_amount": 0,
      "has_interest": true,
      "post_fixed_amount": 0,
      "pre_fixed_amount": 134.91,
      "principal_amortization_amount": 0.0,
      "tax_amount": 0,
      "total_amount": 134.91,
      "workdays": 41,
      "accrual_reference_date": null,
      "advanced_paid_amount": 0.0,
      "bank_slip_key": null,
      "digitable_line": null,
      "installment_key": "a1e600e1-0000-4000-8000-000000000225",
      "installment_status": "unmonitored",
      "installment_type": "principal",
      "original_due_principal": 3932.52,
      "original_pre_fixed_amount": 134.91,
      "original_principal_amortization_amount": 0.0,
      "paid_amount": 0.0,
      "original_total_amount": 134.91,
      "qr_code_key": null,
      "qr_code_url": null,
      "renegotiation_proposal_key": null,
      "total_accrual_amount": 0,
      "total_paid_amount": 0,
      "installment_number": 1,
      "paid_at": null,
      "updated_at": "2026-09-10T10:37:06",
      "principal_amortization_payment_amount": 0,
      "prefixed_interest_payment_amount": 0
    },
    {
      "business_due_date": "2026-12-10",
      "due_date": "2026-12-10",
      "calendar_days": 30,
      "due_interest": 9,
      "due_principal": 3932.52,
      "fine_amount": 0,
      "has_interest": true,
      "post_fixed_amount": 0,
      "pre_fixed_amount": 79.97,
      "principal_amortization_amount": 54.94,
      "tax_amount": 0,
      "total_amount": 134.91,
      "workdays": 21,
      "accrual_reference_date": null,
      "advanced_paid_amount": 0.0,
      "bank_slip_key": null,
      "digitable_line": null,
      "installment_key": "a1e600e2-0000-4000-8000-000000000226",
      "installment_status": "unmonitored",
      "installment_type": "principal",
      "original_due_principal": 3932.52,
      "original_pre_fixed_amount": 79.97,
      "original_principal_amortization_amount": 54.94,
      "paid_amount": 0.0,
      "original_total_amount": 134.91,
      "qr_code_key": null,
      "qr_code_url": null,
      "renegotiation_proposal_key": null,
      "total_accrual_amount": 0,
      "total_paid_amount": 0,
      "installment_number": 2,
      "paid_at": null,
      "updated_at": "2026-09-10T10:37:06",
      "principal_amortization_payment_amount": 0,
      "prefixed_interest_payment_amount": 0
    }
  ],
  "first_due_date": "2026-11-10",
  "requester_key": "a1e60060-0000-4000-8000-000000000096",
  "original_total_iof": null,
  "contract_number": "0000004524/AB",
  "credit_operation_status_enumerator": "opened",
  "operation_type_enumerator": "portability_for_refinancing",
  "disbursement_date": "2026-09-10",
  "issuer_name": "Maria Aparecida Ferreira",
  "issuer_document_number": "12345678909",
  "external_contract_fees": [],
  "cet": 1.81,
  "annual_cet": 24.08,
  "final_disbursement_amount": 0.0,
  "number_of_installments": 43,
  "disbursement_issue_amount": 3932.52,
  "prefixed_interest_rate": {
    "annual_rate": 0.2371000992,
    "daily_rate": 0.0005912025,
    "interest_base": {
      "enumerator": "calendar_days",
      "year_days": 360
    },
    "monthly_rate": 0.0178889587
  },
  "fine_configuration": {
    "contract_fine_rate": 0.02,
    "fine_delay_rate": {
      "annual_rate": 0.0,
      "daily_rate": 0.0,
      "interest_base": {
        "enumerator": "calendar_days",
        "year_days": 360
      },
      "monthly_rate": 0.0
    }
  },
  "attached_documents": [
    {
      "document_key": "a1e6010c-0000-4000-8000-000000000268",
      "document_url": "https://storage.googleapis.com/qi-documents-example/documento-285.jpeg",
      "signature_url": null,
      "document_type": "selfie",
      "signature_required": false,
      "signed": false
    },
    {
      "document_key": "a1e6010d-0000-4000-8000-000000000269",
      "document_url": "https://storage.googleapis.com/qi-documents-example/documento-287.jpeg",
      "signature_url": null,
      "document_type": "document_identification_back",
      "signature_required": false,
      "signed": false
    },
    {
      "document_key": "a1e6010e-0000-4000-8000-000000000270",
      "document_url": "https://storage.googleapis.com/qi-documents-example/documento-289.jpeg",
      "signature_url": null,
      "document_type": "document_identification",
      "signature_required": false,
      "signed": false
    },
    {
      "document_key": "a1e6010f-0000-4000-8000-000000000271",
      "document_url": "https://storage.googleapis.com/qi-documents-example/documento-291.pdf",
      "signature_url": "https://storage.googleapis.com/qi-documents-example/signature-292.pdf",
      "document_type": "ccb_pre_price_days",
      "signature_required": true,
      "signed": true
    },
    {
      "document_key": "a1e60110-0000-4000-8000-000000000272",
      "document_url": "https://storage.googleapis.com/qi-documents-example/documento-294.pdf",
      "signature_url": null,
      "document_type": "issuer_informative",
      "signature_required": false,
      "signed": false
    }
  ],
  "related_parties": [
    {
      "related_party_key": "a1e60111-0000-4000-8000-000000000273",
      "role_type": "issuer",
      "person_type": "natural",
      "name": "Maria Aparecida Ferreira",
      "email": "maria.ferreira@example.com",
      "individual_document_number": "12345678909"
    },
    {
      "related_party_key": "a1e60112-0000-4000-8000-000000000274",
      "role_type": "credit_agent",
      "person_type": "natural",
      "name": "Maria Aparecida Ferreira",
      "email": null,
      "individual_document_number": "12345678909"
    }
  ],
  "disbursement_accounts": [],
  "base_iof": null,
  "additional_iof": null,
  "assignment_amount": 4050.56,
  "created_at": "2026-09-10T10:36:50Z",
  "total_prefixed_amount": 1868.61,
  "refinanced_credit_operations": []
}
```

**Operação 2 de 2 — perna de refinanciamento** (`refinancing_from_portability`)

```json
{
  "credit_operation_key": "a1e60113-0000-4000-8000-000000000275",
  "issue_amount": 6109.02,
  "origin_key": "a1e600e0-0000-4000-8000-000000000224",
  "total_iof": 73.21,
  "assigned_at": null,
  "disbursement_start_date": "2026-09-10",
  "disbursement_end_date": "2026-09-24",
  "issue_date": "2026-09-10",
  "requester_identifier_key": null,
  "installments": [
    {
      "business_due_date": "2026-11-10",
      "due_date": "2026-11-10",
      "calendar_days": 61,
      "due_interest": 0,
      "due_principal": 6109.02,
      "fine_amount": 0,
      "has_interest": true,
      "post_fixed_amount": 0,
      "pre_fixed_amount": 134.91,
      "principal_amortization_amount": 0.0,
      "tax_amount": 0,
      "total_amount": 134.91,
      "workdays": 41,
      "accrual_reference_date": null,
      "advanced_paid_amount": 0.0,
      "bank_slip_key": null,
      "digitable_line": null,
      "installment_key": "a1e60114-0000-4000-8000-000000000276",
      "installment_status": "unmonitored",
      "installment_type": "principal",
      "original_due_principal": 6109.02,
      "original_pre_fixed_amount": 134.91,
      "original_principal_amortization_amount": 0.0,
      "paid_amount": 0.0,
      "original_total_amount": 134.91,
      "qr_code_key": null,
      "qr_code_url": null,
      "renegotiation_proposal_key": null,
      "total_accrual_amount": 0,
      "total_paid_amount": 0,
      "installment_number": 1,
      "paid_at": null,
      "updated_at": "2026-09-10T13:44:25",
      "principal_amortization_payment_amount": 0,
      "prefixed_interest_payment_amount": 0
    },
    {
      "business_due_date": "2026-12-10",
      "due_date": "2026-12-10",
      "calendar_days": 30,
      "due_interest": 97,
      "due_principal": 6109.02,
      "fine_amount": 0,
      "has_interest": true,
      "post_fixed_amount": 0,
      "pre_fixed_amount": 134.91,
      "principal_amortization_amount": 0.0,
      "tax_amount": 0,
      "total_amount": 134.91,
      "workdays": 21,
      "accrual_reference_date": null,
      "advanced_paid_amount": 0.0,
      "bank_slip_key": null,
      "digitable_line": null,
      "installment_key": "a1e60115-0000-4000-8000-000000000277",
      "installment_status": "unmonitored",
      "installment_type": "principal",
      "original_due_principal": 6109.02,
      "original_pre_fixed_amount": 134.91,
      "original_principal_amortization_amount": 0.0,
      "paid_amount": 0.0,
      "original_total_amount": 134.91,
      "qr_code_key": null,
      "qr_code_url": null,
      "renegotiation_proposal_key": null,
      "total_accrual_amount": 0,
      "total_paid_amount": 0,
      "installment_number": 2,
      "paid_at": null,
      "updated_at": "2026-09-10T13:44:25",
      "principal_amortization_payment_amount": 0,
      "prefixed_interest_payment_amount": 0
    }
  ],
  "first_due_date": "2026-11-10",
  "requester_key": "a1e60060-0000-4000-8000-000000000096",
  "original_total_iof": null,
  "contract_number": "0000004525/AB",
  "credit_operation_status_enumerator": "opened",
  "operation_type_enumerator": "refinancing_from_portability",
  "disbursement_date": "2026-09-10",
  "issuer_name": "Maria Aparecida Ferreira",
  "issuer_document_number": "12345678909",
  "external_contract_fees": [],
  "cet": 1.91,
  "annual_cet": 25.46,
  "final_disbursement_amount": 2103.29,
  "number_of_installments": 108,
  "disbursement_issue_amount": 6035.81,
  "prefixed_interest_rate": {
    "annual_rate": 0.2460411933,
    "daily_rate": 0.0006112186,
    "interest_base": {
      "enumerator": "calendar_days",
      "year_days": 360
    },
    "monthly_rate": 0.0185
  },
  "fine_configuration": {
    "contract_fine_rate": 0.02,
    "fine_delay_rate": {
      "annual_rate": 0.0,
      "daily_rate": 0.0,
      "interest_base": {
        "enumerator": "calendar_days",
        "year_days": 360
      },
      "monthly_rate": 0.0
    }
  },
  "attached_documents": [
    {
      "document_key": "a1e6010c-0000-4000-8000-000000000268",
      "document_url": "https://storage.googleapis.com/qi-documents-example/documento-285.jpeg",
      "signature_url": null,
      "document_type": "selfie",
      "signature_required": false,
      "signed": false
    },
    {
      "document_key": "a1e6010d-0000-4000-8000-000000000269",
      "document_url": "https://storage.googleapis.com/qi-documents-example/documento-287.jpeg",
      "signature_url": null,
      "document_type": "document_identification_back",
      "signature_required": false,
      "signed": false
    },
    {
      "document_key": "a1e6010e-0000-4000-8000-000000000270",
      "document_url": "https://storage.googleapis.com/qi-documents-example/documento-289.jpeg",
      "signature_url": null,
      "document_type": "document_identification",
      "signature_required": false,
      "signed": false
    },
    {
      "document_key": "a1e60180-0000-4000-8000-000000000384",
      "document_url": "https://storage.googleapis.com/qi-documents-example/documento-408.pdf",
      "signature_url": "https://storage.googleapis.com/qi-documents-example/signature-409.pdf",
      "document_type": "ccb_pre_price_days",
      "signature_required": true,
      "signed": true
    },
    {
      "document_key": "a1e60181-0000-4000-8000-000000000385",
      "document_url": "https://storage.googleapis.com/qi-documents-example/documento-411.pdf",
      "signature_url": null,
      "document_type": "issuer_informative",
      "signature_required": false,
      "signed": false
    }
  ],
  "related_parties": [
    {
      "related_party_key": "a1e60182-0000-4000-8000-000000000386",
      "role_type": "issuer",
      "person_type": "natural",
      "name": "Maria Aparecida Ferreira",
      "email": "maria.ferreira@example.com",
      "individual_document_number": "12345678909"
    },
    {
      "related_party_key": "a1e60183-0000-4000-8000-000000000387",
      "role_type": "credit_agent",
      "person_type": "natural",
      "name": "Maria Aparecida Ferreira",
      "email": null,
      "individual_document_number": "12345678909"
    }
  ],
  "disbursement_accounts": [
    {
      "account_branch": "0001",
      "account_digit": "8",
      "account_number": "1234567",
      "account_type": null,
      "amount_receivable": null,
      "digitable_line": null,
      "disbursement_type": "pix",
      "document_number": "12345678909",
      "end_to_end_id": "E00360305202609101206A1B2C3D4E5F",
      "financial_institutions_code_number": 318,
      "ispb": "61186680",
      "name": "Maria Aparecida Ferreira",
      "percentage_receivable": 100.0,
      "pix_key": null,
      "pix_transfer_key": "a1e60184-0000-4000-8000-000000000388",
      "pix_type": "manual",
      "qr_code_key": null,
      "qr_code_url": null
    }
  ],
  "base_iof": 64.94,
  "additional_iof": 8.27,
  "assignment_amount": 6267.27,
  "created_at": "2026-09-10T12:06:09Z",
  "total_prefixed_amount": 8461.26,
  "refinanced_credit_operations": [
    {
      "refinanced_credit_operation_key": "a1e600df-0000-4000-8000-000000000223",
      "refinanced_contract_number": "0000004524/AB",
      "due_balance": 3932.52,
      "due_balance_reference_date": "2026-09-10",
      "original_deadline": 1338,
      "refinanced_credit_operation_status_enumerator": "pending_payment",
      "updated_at": "2026-09-10T11:28:26",
      "created_at": "2026-09-10T12:06:12"
    }
  ]
}
```

**Com eval_present_value=true**

Mesma operação de refinanciamento da aba anterior, consultada com
`?eval_present_value=true`. Os três campos adicionais são `present_amount` em cada parcela,
`present_amount` na raiz (soma das parcelas) e o par
`remaining_principal_disbursement_amount` / `remaining_principal_iof_amount`, que quebra o
principal ainda em aberto entre valor desembolsado e IOF. Os valores de `present_amount`
variam com `present_value_reference_date` e com a configuração de cessão do requester.

```json
{
  "credit_operation_key": "a1e60068-0000-4000-8000-000000000104",
  "issue_amount": 32812.16,
  "origin_key": "a1e60068-0000-4000-8000-000000000104",
  "total_iof": 94.27,
  "assigned_at": null,
  "disbursement_start_date": "2026-09-09",
  "disbursement_end_date": "2026-09-12",
  "issue_date": "2026-09-09",
  "requester_identifier_key": "a1e60068-0000-4000-8000-000000000104",
  "installments": [
    {
      "business_due_date": "2026-11-10",
      "due_date": "2026-11-10",
      "calendar_days": 62,
      "due_interest": 0,
      "due_principal": 32812.16,
      "fine_amount": 0,
      "has_interest": true,
      "post_fixed_amount": 0,
      "pre_fixed_amount": 702.93,
      "principal_amortization_amount": 0.0,
      "tax_amount": 0,
      "total_amount": 702.93,
      "workdays": 42,
      "accrual_reference_date": null,
      "advanced_paid_amount": 0.0,
      "bank_slip_key": null,
      "digitable_line": null,
      "installment_key": "a1e60069-0000-4000-8000-000000000105",
      "installment_status": "unmonitored",
      "installment_type": "principal",
      "original_due_principal": 32812.16,
      "original_pre_fixed_amount": 702.93,
      "original_principal_amortization_amount": 0.0,
      "paid_amount": 0.0,
      "original_total_amount": 702.93,
      "qr_code_key": null,
      "qr_code_url": null,
      "renegotiation_proposal_key": null,
      "total_accrual_amount": 0,
      "total_paid_amount": 0,
      "installment_number": 1,
      "paid_at": null,
      "updated_at": "2026-09-10T09:27:00",
      "principal_amortization_payment_amount": 0,
      "prefixed_interest_payment_amount": 0,
      "present_amount": 678.79
    },
    {
      "business_due_date": "2026-12-10",
      "due_date": "2026-12-10",
      "calendar_days": 30,
      "due_interest": 508,
      "due_principal": 32812.16,
      "fine_amount": 0,
      "has_interest": true,
      "post_fixed_amount": 0,
      "pre_fixed_amount": 702.93,
      "principal_amortization_amount": 0.0,
      "tax_amount": 0,
      "total_amount": 702.93,
      "workdays": 21,
      "accrual_reference_date": null,
      "advanced_paid_amount": 0.0,
      "bank_slip_key": null,
      "digitable_line": null,
      "installment_key": "a1e6006a-0000-4000-8000-000000000106",
      "installment_status": "unmonitored",
      "installment_type": "principal",
      "original_due_principal": 32812.16,
      "original_pre_fixed_amount": 702.93,
      "original_principal_amortization_amount": 0.0,
      "paid_amount": 0.0,
      "original_total_amount": 702.93,
      "qr_code_key": null,
      "qr_code_url": null,
      "renegotiation_proposal_key": null,
      "total_accrual_amount": 0,
      "total_paid_amount": 0,
      "installment_number": 2,
      "paid_at": null,
      "updated_at": "2026-09-10T09:27:00",
      "principal_amortization_payment_amount": 0,
      "prefixed_interest_payment_amount": 0,
      "present_amount": 666.96
    }
  ],
  "first_due_date": "2026-11-10",
  "requester_key": "a1e600d5-0000-4000-8000-000000000213",
  "original_total_iof": null,
  "contract_number": "0000004522/AB",
  "credit_operation_status_enumerator": "opened",
  "operation_type_enumerator": "refinancing",
  "disbursement_date": "2026-09-10",
  "issuer_name": "Maria Aparecida Ferreira",
  "issuer_document_number": "12345678909",
  "external_contract_fees": [],
  "cet": 1.8,
  "annual_cet": 23.91,
  "final_disbursement_amount": 2709.78,
  "number_of_installments": 108,
  "disbursement_issue_amount": 32717.89,
  "prefixed_interest_rate": {
    "annual_rate": 0.2343470806,
    "daily_rate": 0.0005850104,
    "interest_base": {
      "enumerator": "calendar_days",
      "year_days": 360
    },
    "monthly_rate": 0.0177
  },
  "fine_configuration": {
    "contract_fine_rate": 0.0,
    "fine_delay_rate": {
      "annual_rate": 0.12682503,
      "daily_rate": 0.00033173,
      "interest_base": {
        "enumerator": "calendar_days",
        "year_days": 360
      },
      "monthly_rate": 0.01
    }
  },
  "attached_documents": [
    {
      "document_key": "a1e600d6-0000-4000-8000-000000000214",
      "document_url": "https://storage.googleapis.com/qi-documents-example/documento-223.pdf",
      "signature_url": "https://storage.googleapis.com/qi-documents-example/signature-224.pdf",
      "document_type": "ccb_pre_price_days",
      "signature_required": true,
      "signed": true
    },
    {
      "document_key": "a1e600d7-0000-4000-8000-000000000215",
      "document_url": "https://storage.googleapis.com/qi-documents-example/documento-226.jpeg",
      "signature_url": null,
      "document_type": "selfie",
      "signature_required": false,
      "signed": false
    },
    {
      "document_key": "a1e600d8-0000-4000-8000-000000000216",
      "document_url": "https://storage.googleapis.com/qi-documents-example/documento-228.jpg",
      "signature_url": null,
      "document_type": "document_identification",
      "signature_required": false,
      "signed": false
    },
    {
      "document_key": "a1e600d9-0000-4000-8000-000000000217",
      "document_url": "https://storage.googleapis.com/qi-documents-example/documento-230.jpg",
      "signature_url": null,
      "document_type": "document_identification_back",
      "signature_required": false,
      "signed": false
    },
    {
      "document_key": "a1e600da-0000-4000-8000-000000000218",
      "document_url": "https://storage.googleapis.com/qi-documents-example/documento-232.pdf",
      "signature_url": null,
      "document_type": "issuer_informative",
      "signature_required": false,
      "signed": false
    }
  ],
  "related_parties": [
    {
      "related_party_key": "a1e600db-0000-4000-8000-000000000219",
      "role_type": "issuer",
      "person_type": "natural",
      "name": "Maria Aparecida Ferreira",
      "email": "maria.ferreira@example.com",
      "individual_document_number": "12345678909"
    },
    {
      "related_party_key": "a1e600dc-0000-4000-8000-000000000220",
      "role_type": "credit_agent",
      "person_type": "natural",
      "name": "Maria Aparecida Ferreira",
      "email": null,
      "individual_document_number": "12345678909"
    }
  ],
  "disbursement_accounts": [
    {
      "account_branch": "0001",
      "account_digit": "8",
      "account_number": "1234567",
      "account_type": "checking_account",
      "amount_receivable": null,
      "digitable_line": null,
      "disbursement_type": "pix",
      "document_number": "12345678909",
      "end_to_end_id": "E00360305202609101206A1B2C3D4E5F",
      "financial_institutions_code_number": 104,
      "ispb": "00360305",
      "name": "Maria Aparecida Ferreira",
      "percentage_receivable": 100.0,
      "pix_key": null,
      "pix_transfer_key": "a1e600dd-0000-4000-8000-000000000221",
      "pix_type": "manual",
      "qr_code_key": null,
      "qr_code_url": null
    }
  ],
  "base_iof": 83.61,
  "additional_iof": 10.66,
  "assignment_amount": 32881.06,
  "created_at": "2026-09-09T19:59:42Z",
  "total_prefixed_amount": 43104.28,
  "refinanced_credit_operations": [
    {
      "refinanced_credit_operation_key": "a1e600de-0000-4000-8000-000000000222",
      "refinanced_contract_number": "0000004523/AB",
      "due_balance": 30008.11,
      "due_balance_reference_date": "2026-09-09",
      "original_deadline": 2941,
      "refinanced_credit_operation_status_enumerator": "pending_payment",
      "updated_at": "2026-09-10T09:03:56",
      "created_at": "2026-09-09T19:59:42"
    }
  ],
  "present_amount": 32881.06,
  "remaining_principal_disbursement_amount": 32717.89,
  "remaining_principal_iof_amount": 94.27
}
```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

---

# Consulta de dívida por Requester Identifier Key

URL: /documentation/emissao_de_divida/consulta_por_requester_identifier_key

## Request

ENDPOINT /v2/credit_operation/requester_identifier_key/ REQUESTER-IDENTIFIER-KEY
MÉTODO GET

### Path params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|   
| `requester_identifier_key` * | string | Chave da UUID4 enviada na criação da dívida. | UUID |

### Query params

| Campo | Tipo | Descrição | Default |
|---|---|---|---|
| `eval_present_value` | boolean | Quando `true`, calcula o valor presente de cada parcela e retorna o campo `present_amount` em cada item de `installments`, além de um `present_amount` na raiz com a soma das parcelas. Não pode ser usado para operações nos status: `waiting_signature`, `signed`, `issued`, `canceled`, `canceled_permanently` ou `amended`. | `false` |
| `calculate_delay` | boolean | Considera juros de mora no cálculo do valor presente. Só tem efeito quando `eval_present_value=true`. | `false` |
| `calculate_spread` | boolean | Considera o spread no cálculo do valor presente. Só tem efeito quando `eval_present_value=true`. | `true` |
| `present_value_reference_date` | string (date) | Data de referência (`YYYY-MM-DD`) usada como base para o cálculo do valor presente. Só tem efeito quando `eval_present_value=true`. | hoje |

## Response

STATUS 200

Response Body

**Sem eval_present_value**

```json
{
  "credit_operation_key": "eaf5836a-ea6f-4baa-ac26-ce5199dfa448",
  "issue_amount": 1006.77,
  "origin_key": "52539e23-5c01-4b9c-8a68-6ed750ec7bc5",
  "total_iof": 6.77,
  "disbursement_start_date": "2022-08-24",
  "disbursement_end_date": "2022-08-24",
  "assigned_at": "2025-08-24T10:00:00Z",
  "issue_date": "2022-08-24",
  "requester_identifier_key": "5cb7456c-f2e3-41b3-b17a-ad47ba3c3cda",
  "installments": [
    {
      "business_due_date": "2022-08-30",
      "due_date": "2022-08-29",
      "calendar_days": 5,
      "due_interest": 0,
      "due_principal": 1006.77,
      "fine_amount": 0,
      "has_interest": true,
      "post_fixed_amount": 0,
      "pre_fixed_amount": 18.93,
      "principal_amortization_amount": 363.14,
      "tax_amount": 0.15,
      "total_amount": 382.07,
      "workdays": 3,
      "accrual_reference_date": null,
      "advanced_paid_amount": 0.0,
      "bank_slip_key": null,
      "digitable_line": null,
      "installment_key": "b56f61ec-202c-4a7a-8a5e-11f90972bae8",
      "installment_status": "created",
      "installment_type": "principal",
      "original_due_principal": 1006.77,
      "original_pre_fixed_amount": 18.93,
      "original_principal_amortization_amount": 363.14,
      "paid_amount": 0.0,
      "original_total_amount": 382.07,
      "qr_code_key": null,
      "qr_code_url": null,
      "renegotiation_proposal_key": null,
      "total_accrual_amount": 0,
      "total_paid_amount": 0,
      "installment_number": 1,
      "paid_at": null,
      "updated_at": null,
      "principal_amortization_payment_amount": 0,
      "prefixed_interest_payment_amount": 0
    },
    {
      "business_due_date": "2022-09-30",
      "due_date": "2022-09-29",
      "calendar_days": 31,
      "due_interest": 0,
      "due_principal": 643.63499424,
      "fine_amount": 0,
      "has_interest": true,
      "post_fixed_amount": 0,
      "pre_fixed_amount": 78.82,
      "principal_amortization_amount": 303.25,
      "tax_amount": 0.9,
      "total_amount": 382.07,
      "workdays": 22,
      "accrual_reference_date": null,
      "advanced_paid_amount": 0.0,
      "bank_slip_key": null,
      "digitable_line": null,
      "installment_key": "2a95a560-bec6-4207-9a38-98c72e023c59",
      "installment_status": "created",
      "installment_type": "principal",
      "original_due_principal": 643.63,
      "original_pre_fixed_amount": 78.82,
      "original_principal_amortization_amount": 303.25,
      "paid_amount": 0.0,
      "original_total_amount": 382.07,
      "qr_code_key": null,
      "qr_code_url": null,
      "renegotiation_proposal_key": null,
      "total_accrual_amount": 0,
      "total_paid_amount": 0,
      "installment_number": 2,
      "paid_at": null,
      "updated_at": null,
      "principal_amortization_payment_amount": 0,
      "prefixed_interest_payment_amount": 0
    },
    {
      "business_due_date": "2022-11-01",
      "due_date": "2022-10-31",
      "calendar_days": 32,
      "due_interest": 0,
      "due_principal": 340.38585509,
      "fine_amount": 0,
      "has_interest": true,
      "post_fixed_amount": 0,
      "pre_fixed_amount": 41.68,
      "principal_amortization_amount": 340.39,
      "tax_amount": 1.9,
      "total_amount": 382.07,
      "workdays": 21,
      "accrual_reference_date": null,
      "advanced_paid_amount": 0.0,
      "bank_slip_key": null,
      "digitable_line": null,
      "installment_key": "61924f59-11e3-49d0-9cf7-2a1d0ce54924",
      "installment_status": "created",
      "installment_type": "principal",
      "original_due_principal": 340.39,
      "original_pre_fixed_amount": 41.68,
      "original_principal_amortization_amount": 340.39,
      "paid_amount": 0.0,
      "original_total_amount": 382.07,
      "qr_code_key": null,
      "qr_code_url": null,
      "renegotiation_proposal_key": null,
      "total_accrual_amount": 0,
      "total_paid_amount": 0,
      "installment_number": 3,
      "paid_at": null,
      "updated_at": null,
      "principal_amortization_payment_amount": 0,
      "prefixed_interest_payment_amount": 0
    }
  ],
  "first_due_date": "2022-08-29",
  "requester_key": "52f36417-368e-4f5b-8841-71e3b9caa72f",
  "original_total_iof": 6.77,
  "contract_number": "0000000001/WO",
  "credit_operation_status_enumerator": "waiting_signature",
  "operation_type_enumerator": "structured_operation",
  "disbursement_date": "2022-08-24",
  "issuer_name": "Wilker Oliveiraço",
  "issuer_document_number": "37197645832",
  "external_contract_fees": [
    {
      "amount_type": {
        "enumerator": "percentage"
      },
      "fee_amount": 0.0,
      "tax_amount": 0.0,
      "irrf_amount": 0.0,
      "amount": 0.0,
      "pis_amount": 0.0,
      "amount_released": 0.0,
      "fee_type": {
        "enumerator": "tac"
      },
      "cofins_amount": 0.0,
      "csll_amount": 0.0,
      "description": null,
      "net_fee_amount": 0.0,
      "rebate_account": null,
      "billing_type": {
        "enumerator": "disbursement"
      },
      "created_at": "2025-10-14T22:18:07"
    },
    {
      "amount_type": {
        "enumerator": "absolute"
      },
      "fee_amount": 0.0,
      "tax_amount": 0.0,
      "irrf_amount": 0.0,
      "amount": 0.0,
      "pis_amount": 0.0,
      "amount_released": 0.0,
      "fee_type": {
        "enumerator": "spread_tax_free"
      },
      "cofins_amount": 0.0,
      "csll_amount": 0.0,
      "description": null,
      "net_fee_amount": 0.0,
      "rebate_account": null,
      "billing_type": {
        "enumerator": "disbursement"
      },
      "created_at": "2025-10-14T22:18:07"
    },
    {
      "amount_type": {
        "enumerator": "absolute"
      },
      "fee_amount": 0.0,
      "tax_amount": 0.0,
      "irrf_amount": 0.0,
      "amount": 0.0,
      "pis_amount": 0.0,
      "amount_released": 0.0,
      "fee_type": {
        "enumerator": "tac_tax_free"
      },
      "cofins_amount": 0.0,
      "csll_amount": 0.0,
      "description": null,
      "net_fee_amount": 0.0,
      "rebate_account": null,
      "billing_type": {
        "enumerator": "disbursement"
      },
      "created_at": "2025-10-14T22:18:07"
    }
  ]
}
```

**Com eval_present_value=true**

```json
{
  "credit_operation_key": "eaf5836a-ea6f-4baa-ac26-ce5199dfa448",
  "issue_amount": 1006.77,
  "present_amount": 889.87,
  "origin_key": "52539e23-5c01-4b9c-8a68-6ed750ec7bc5",
  "total_iof": 6.77,
  "disbursement_start_date": "2022-08-24",
  "disbursement_end_date": "2022-08-24",
  "assigned_at": "2025-08-24T10:00:00Z",
  "issue_date": "2022-08-24",
  "requester_identifier_key": "5cb7456c-f2e3-41b3-b17a-ad47ba3c3cda",
  "installments": [
    {
      "business_due_date": "2022-08-30",
      "due_date": "2022-08-29",
      "calendar_days": 5,
      "due_interest": 0,
      "due_principal": 1006.77,
      "fine_amount": 0,
      "has_interest": true,
      "post_fixed_amount": 0,
      "pre_fixed_amount": 18.93,
      "principal_amortization_amount": 363.14,
      "tax_amount": 0.15,
      "total_amount": 382.07,
      "workdays": 3,
      "accrual_reference_date": null,
      "advanced_paid_amount": 0.0,
      "bank_slip_key": null,
      "digitable_line": null,
      "installment_key": "b56f61ec-202c-4a7a-8a5e-11f90972bae8",
      "installment_status": "created",
      "installment_type": "principal",
      "original_due_principal": 1006.77,
      "original_pre_fixed_amount": 18.93,
      "original_principal_amortization_amount": 363.14,
      "paid_amount": 0.0,
      "original_total_amount": 382.07,
      "qr_code_key": null,
      "qr_code_url": null,
      "renegotiation_proposal_key": null,
      "total_accrual_amount": 0,
      "total_paid_amount": 0,
      "installment_number": 1,
      "paid_at": null,
      "updated_at": null,
      "principal_amortization_payment_amount": 0,
      "prefixed_interest_payment_amount": 0,
      "present_amount": 296.62
    },
    {
      "business_due_date": "2022-09-30",
      "due_date": "2022-09-29",
      "calendar_days": 31,
      "due_interest": 0,
      "due_principal": 643.63499424,
      "fine_amount": 0,
      "has_interest": true,
      "post_fixed_amount": 0,
      "pre_fixed_amount": 78.82,
      "principal_amortization_amount": 303.25,
      "tax_amount": 0.9,
      "total_amount": 382.07,
      "workdays": 22,
      "accrual_reference_date": null,
      "advanced_paid_amount": 0.0,
      "bank_slip_key": null,
      "digitable_line": null,
      "installment_key": "2a95a560-bec6-4207-9a38-98c72e023c59",
      "installment_status": "created",
      "installment_type": "principal",
      "original_due_principal": 643.63,
      "original_pre_fixed_amount": 78.82,
      "original_principal_amortization_amount": 303.25,
      "paid_amount": 0.0,
      "original_total_amount": 382.07,
      "qr_code_key": null,
      "qr_code_url": null,
      "renegotiation_proposal_key": null,
      "total_accrual_amount": 0,
      "total_paid_amount": 0,
      "installment_number": 2,
      "paid_at": null,
      "updated_at": null,
      "principal_amortization_payment_amount": 0,
      "prefixed_interest_payment_amount": 0,
      "present_amount": 296.62
    },
    {
      "business_due_date": "2022-11-01",
      "due_date": "2022-10-31",
      "calendar_days": 32,
      "due_interest": 0,
      "due_principal": 340.38585509,
      "fine_amount": 0,
      "has_interest": true,
      "post_fixed_amount": 0,
      "pre_fixed_amount": 41.68,
      "principal_amortization_amount": 340.39,
      "tax_amount": 1.9,
      "total_amount": 382.07,
      "workdays": 21,
      "accrual_reference_date": null,
      "advanced_paid_amount": 0.0,
      "bank_slip_key": null,
      "digitable_line": null,
      "installment_key": "61924f59-11e3-49d0-9cf7-2a1d0ce54924",
      "installment_status": "created",
      "installment_type": "principal",
      "original_due_principal": 340.39,
      "original_pre_fixed_amount": 41.68,
      "original_principal_amortization_amount": 340.39,
      "paid_amount": 0.0,
      "original_total_amount": 382.07,
      "qr_code_key": null,
      "qr_code_url": null,
      "renegotiation_proposal_key": null,
      "total_accrual_amount": 0,
      "total_paid_amount": 0,
      "installment_number": 3,
      "paid_at": null,
      "updated_at": null,
      "principal_amortization_payment_amount": 0,
      "prefixed_interest_payment_amount": 0,
      "present_amount": 296.63
    }
  ],
  "first_due_date": "2022-08-29",
  "requester_key": "52f36417-368e-4f5b-8841-71e3b9caa72f",
  "original_total_iof": 6.77,
  "contract_number": "0000000001/WO",
  "credit_operation_status_enumerator": "waiting_signature",
  "operation_type_enumerator": "structured_operation",
  "disbursement_date": "2022-08-24",
  "issuer_name": "Wilker Oliveiraço",
  "issuer_document_number": "37197645832",
  "external_contract_fees": [
    {
      "amount_type": {
        "enumerator": "percentage"
      },
      "fee_amount": 0.0,
      "tax_amount": 0.0,
      "irrf_amount": 0.0,
      "amount": 0.0,
      "pis_amount": 0.0,
      "amount_released": 0.0,
      "fee_type": {
        "enumerator": "tac"
      },
      "cofins_amount": 0.0,
      "csll_amount": 0.0,
      "description": null,
      "net_fee_amount": 0.0,
      "rebate_account": null,
      "billing_type": {
        "enumerator": "disbursement"
      },
      "created_at": "2025-10-14T22:18:07"
    },
    {
      "amount_type": {
        "enumerator": "absolute"
      },
      "fee_amount": 0.0,
      "tax_amount": 0.0,
      "irrf_amount": 0.0,
      "amount": 0.0,
      "pis_amount": 0.0,
      "amount_released": 0.0,
      "fee_type": {
        "enumerator": "spread_tax_free"
      },
      "cofins_amount": 0.0,
      "csll_amount": 0.0,
      "description": null,
      "net_fee_amount": 0.0,
      "rebate_account": null,
      "billing_type": {
        "enumerator": "disbursement"
      },
      "created_at": "2025-10-14T22:18:07"
    },
    {
      "amount_type": {
        "enumerator": "absolute"
      },
      "fee_amount": 0.0,
      "tax_amount": 0.0,
      "irrf_amount": 0.0,
      "amount": 0.0,
      "pis_amount": 0.0,
      "amount_released": 0.0,
      "fee_type": {
        "enumerator": "tac_tax_free"
      },
      "cofins_amount": 0.0,
      "csll_amount": 0.0,
      "description": null,
      "net_fee_amount": 0.0,
      "rebate_account": null,
      "billing_type": {
        "enumerator": "disbursement"
      },
      "created_at": "2025-10-14T22:18:07"
    }
  ]
}
```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

---

# Desembolso da operação

URL: /documentation/emissao_de_divida/desembolso_da_operacao

O desembolso de uma operação é a liberação dos recursos provenientes do contrato de crédito, na QI Tech, a forma de desembolso obedece as configurações do produto de crédito conforme explicitado nas configurações de desembolso.

:::info Informação
Por padrão as operações são desembolsadas via PIX na conta enviada para a operação, porém existem cinco
opções que podem ser selecionadas:

**1- Pix com informações de conta**;

**2- Pix com chave**;

**3- TED**;

**4- QR code Pix**;

**5- Boleto**;

Elas possuem campos específicos e estão detalhados na chave "disbursement_bank_accounts" da emissão de contrato.
:::

A rotina de desembolso da QI Tech roda a cada minuto observando se todos os requisitos configurados para o produto foram atendidos para aquele contrato específico e alterando seu status.

## Requisitos para Desembolso

- **Data de desembolso**

O Contrato de crédito da operação só é desembolsado na data definida como "disbursement_date".

- **Contrato de crédito emitido e assinado**

O Contrato de crédito da operação deve estar emitido e assinado.

- **Colateral constituído**

No caso de operações que exijam garantias, o colateral deve estar constituído para que o desembolso prossiga.

- **Aprovação de desembolso**

Caso a configuração de "aprovação para desembolso" esteja ativa, o contrato só será desembolsado após a chamada de API de aprovação.

- **Operações com entrada precisam estar pagas**

Caso a operação criada possua um parâmetro de entrada, o desembolso só ocorre após o pagamento e a liquidação financeira no sistema QI Tech.

- **Alinhamento de limites**

É necessário que exista limite de crédito disponível para que a operação seja desembolsada.

---

# Emissão de dívida PF

URL: /documentation/emissao_de_divida/emissao/emissao_de_divida_pf

Com a API de emissão de dívida é possível solicitar a emissão de uma dívida para uma pessoa física.
Não é necessário realizar o cadastro prévio do tomador, basta informar os dados cadastrais no momento da solicitação da dívida.

:::danger Atenção!

A QI Tech oferece uma solução de Onboarding de novos clientes e Anti-fraude.

Para receber uma cotação, entre em contato com nosso time comercial:

comercial@qitech.com.br ou (11) 3522-1301
:::

A API de dívida foi desenhada para ser executada em apenas uma
requisição, após um prévio envio dos arquivos ([upload de documentos](../../upload_de_documentos)).
O formato de assinatura do header e do body desta requisição é descrito em detalhes
[aqui](../../primeiros_passos/teste_de_autenticacao).

## Request

ENDPOINT /debt
MÉTODO POST

Request Body

```json
{
    "borrower": {
        "name": "Alan Mathison Turing",
        "email": "alan.turing@email.com",
        "phone": {
            "number": "912345678",
            "area_code": "11",
            "country_code": "055"
        },
        "is_pep": false,
        "address": {
            "city": "São Paulo",
            "state": "SP",
            "number": "1000",
            "street": "Avenida Feliz",
            "complement": "AP 801",
            "postal_code": "49026100",
            "neighborhood": "Centro"
        },
        "role_type": "issuer",
        "birth_date": "1990-11-20",
        "mother_name": "Nome da Mãe do Alan",
        "nationality": "brasileiro",
        "person_type": "natural",
        "individual_document_number": "96969879003",
        "document_identification": "494598fd-c226-4332-a500-591ae3884673"
    },
    "financial": {
        "disbursed_amount": 123456,
        "interest_type": "pre_price_days",
        "credit_operation_type": "ccb",
        "monthly_interest_rate": 0.018,
        "disbursement_date": "2026-03-01",
        "rebates": [
            {
                "amount": 10,
                "fee_type": "tac",
                "amount_type": "absolute",
                "rebate_bank_account": {
                    "name": "CONTA BANCARIA",
                    "bank_code": "329",
                    "account_digit": "1",
                    "branch_number": "0001",
                    "account_number": "00003",
                    "document_number": "32402502000135"
                }
            }
        ],
        "interest_grace_period": 0,
        "principal_grace_period": 0,
        "number_of_installments": 2,
        "fine_configuration": {
            "contract_fine_rate": 0.02,
            "interest_base": "calendar_days",
            "monthly_rate": 0.01
        }
    },
    "disbursement_bank_account": {
        "name": "Alan Mathison Turing",
        "document_number": "96969879003",
        "bank_code": "341",
        "branch_number": "8615",
        "account_number": "22110",
        "account_digit": "2",
        "account_type": "checking_account"
    },
    "purchaser_document_number": "32402502000135",
    "credit_agent": {
        "document_number": "87237271016",
        "name": "Agente de credito"
    }
}
```

:::warning Atenção
O objeto `credit_agent` representa o agente de crédito, por vezes conhecido como pastinha, responsável pela originação desta dívida. Este campo é obrigatório para a emissão de dívidas de consignados.
:::

## Response

A resposta desse pedido de dívida retornará o plano de pagamento assim como uma **DEBT-KEY**, que é o identificador da dívida na QI SCD.

STATUS 200

Response Body

```json
{
    "webhook_type": "debt",
    "key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
    "status": "waiting_signature",
    "event_datetime": "2025-03-27 22:46:10",
    "data": {
        "requester_identifier_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
        "iof_charge_method": "financed",
        "prefixed_interest_rate": {
            "annual_rate": 0.2387205316,
            "created_at": "2025-03-27T22:46:04",
            "daily_rate": 0.0005866899,
            "interest_base": "calendar_days_365",
            "monthly_rate": 0.018
        },
        "borrower": {
            "name": "Alan Mathison Turing",
            "document_number": "96969879003",
            "related_party_key": "d5cbcada-42e7-4d5b-84fc-3c2dc8038411"
        },
        "contract": {
            "number": "0000192840/AMT",
            "urls": [
                "https://storage.googleapis.com/sandbox-doc-api/documents/b2d974f9-c710-42e3-8ea4-69cc31561c38/GENERICTEST-ALAN_MATHISON_TURING-CCB-0000192840-20250327224604.pdf"
            ],
            "signers": [
                {
                    "signer_name": "Alan Mathison Turing",
                    "signer_document_number": "96969879003",
                    "signer_role": "issuer",
                    "signer_email": "alan.turing@email.com",
                    "signer_external_key": null,
                    "signature_url": null
                }
            ]
        },
        "installments": [
            {
                "accrual_reference_date": null,
                "additional_costs": [],
                "advanced_paid_amount": 0.0,
                "bank_slip_key": null,
                "business_due_date": "2026-04-01",
                "calendar_days": 31,
                "digitable_line": null,
                "due_date": "2026-04-01",
                "due_interest": 0.0,
                "due_principal": 124424.89,
                "fine_amount": null,
                "has_interest": true,
                "installment_history": [],
                "installment_key": "b4c722a1-c977-415d-891a-342308edd52f",
                "installment_number": 1,
                "installment_payment": [],
                "installment_status": "created",
                "installment_type": "principal",
                "original_due_principal": 124424.89,
                "original_pre_fixed_amount": 2282.99189209,
                "original_principal_amortization_amount": 61684.03810791,
                "original_total_amount": 63967.03,
                "paid_amount": 0.0,
                "paid_at": null,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 2282.99189209,
                "principal_amortization_amount": 61684.03810791,
                "qr_code_key": null,
                "qr_code_url": null,
                "renegotiation_proposal_key": null,
                "tax_amount": 156.80082487,
                "total_accrual_amount": null,
                "total_amount": 63967.03,
                "total_paid_amount": 0.0,
                "workdays": 23
            },
            {
                "accrual_reference_date": null,
                "additional_costs": [],
                "advanced_paid_amount": 0.0,
                "bank_slip_key": null,
                "business_due_date": "2026-05-04",
                "calendar_days": 33,
                "digitable_line": null,
                "due_date": "2026-05-04",
                "due_interest": 0.0,
                "due_principal": 62740.85189209,
                "fine_amount": null,
                "has_interest": true,
                "installment_history": [],
                "installment_key": "0d042ffc-1629-4ed4-8ec9-0972b2f715ba",
                "installment_number": 2,
                "installment_payment": [],
                "installment_status": "created",
                "installment_type": "principal",
                "original_due_principal": 62740.85189209,
                "original_pre_fixed_amount": 1226.17810791,
                "original_principal_amortization_amount": 62740.85189209,
                "original_total_amount": 63967.03,
                "paid_amount": 0.0,
                "paid_at": null,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 1226.17810791,
                "principal_amortization_amount": 62740.85189209,
                "qr_code_key": null,
                "qr_code_url": null,
                "renegotiation_proposal_key": null,
                "tax_amount": 329.26399073,
                "total_accrual_amount": null,
                "total_amount": 63967.03,
                "total_paid_amount": 0.0,
                "workdays": 20
            }
        ],
        "total_pre_fixed_amount": 3509.17,
        "contract_fees": [
            {
                "fee_type": "spread",
                "fee_amount": 497.7
            },
            {
                "fee_type": "spread_ted_fee",
                "fee_amount": 1.0
            }
        ],
        "contract_fee_amount": 498.7,
        "external_contract_fees": [
            {
                "fee_type": "tac",
                "fee_amount": 10.0,
                "tax_amount": 1.42,
                "description": null,
                "net_fee_amount": 8.58,
                "rebate_bank_account": {
                    "account_branch": "0001",
                    "account_digit": "1",
                    "account_number": "00003",
                    "created_at": "2025-03-27T22:46:04",
                    "document_number": "32402502000135",
                    "financial_institutions": {
                        "code_number": 329,
                        "is_active": true,
                        "is_pix_participant": true,
                        "ispb": 32402502,
                        "name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A."
                    },
                    "financial_institutions_code_number": "329",
                    "name": "CONTA BANCARIA"
                }
            },
            {
                "fee_type": "spread",
                "fee_amount": 0.0,
                "tax_amount": 0.0,
                "description": null,
                "net_fee_amount": 0.0,
                "rebate_bank_account": null
            },
            {
                "fee_type": "insurance_premium",
                "fee_amount": 0.0,
                "tax_amount": 0.0,
                "description": null,
                "net_fee_amount": 0.0,
                "rebate_bank_account": null
            }
        ],
        "external_contract_fee_amount": 10.0,
        "net_external_contract_fee_amount": 8.58,
        "assignment_amount": 124923.59,
        "issue_amount": 124424.89,
        "disbursed_issue_amount": 123456.0,
        "cet": "2,3100%",
        "annual_cet": "31,5716%",
        "number_of_installments": 2,
        "base_iof": 486.06,
        "additional_iof": 472.83,
        "total_iof": 958.89,
        "collaterals": [],
        "entry": null
    }
}
```

## Definições

### Objeto Request Body
| Campo                           | Tipo   | Descrição                                                                                                                                                                                                        | Máx. Caract. | 
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **borrower** *                  | object | **[Objeto Borrower](#objeto-borrower)** - Devedor da operação de crédito                                                                                                                                         | -            | 
| **disbursement_bank_account** * | object | **[Objeto Disbursement Bank Account](#objeto-disbursement_bank_accounts)** - Dados da conta bancária para desembolso da operação                                                                                 | -            |
| **financial** *                 | object | **[Objeto Financial](#objeto-financial)** - Dados da conta bancária para desembolso da operaçãoIdentificador de que o objeto enviado é uma pessoa física. Deve conter SEMPRE o  valor "natural" para borrower PF | -            |
| **purchaser_document_number** * | string | CNPJ do cessionário (comprador) da operação de crédito                                                                                                                                                           | -            |

### Objeto Borrower
| Campo                            | Tipo    | Descrição                                                                             | Máx. Caract. | 
|----------------------------------|---------|---------------------------------------------------------------------------------------|--------------|
| **name** *                       | string  | Nome do devedor                                                                       | 100          |
| **email**                        | string  | Email do devedor                                                                      | 254          |
| **phone**                        | object  | **[Objeto Phone](#objeto-phone)** - Telefone de contato do devedor                    | -            | 
| **is_pep** *                     | boolean | Indicador de PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep)      | -            |
| **address** *                    | object  | **[Objeto Address](#objeto-address)** - Endereço do devedor                           | -            | 
| **role_type** *                  | enum    | default: _issuer_                                                                     | -            |
| **birth_date** *                 | date    | Data de nascimento do devedor (formato "AAAA-MM-DD")                                  | -            |
| **mother_name** *                | string  | Nome da mãe do devedor                                                                | 100          |
| **nationality**                  | string  | Nacionalidade do devedor                                                              | 50           |
| **person_type** *                | string  | Indicador de pessoa física - default: _natural_                                       | -            |
| **individual_document_number** * | string  | CPF do devedor (apenas números)                                                       | 11           |
| **document_identification**     * | string  | **DOCUMENT_KEY** do PDF do documento de identificação do devedor com foto (RG, CNH ou CIN) | -            |
| **document_identification_back** |string | DOCUMENT_KEY do PDF da parte de trás do documento de identificação da pessoa com foto (RG, CNH ou CIN) (enviado previamente). | 11 |
| **document_identification_type** | enum | **[Enumerador Document Identification Type](#enumerador-document-identification-type)** — Tipo do documento de identificação enviado. | - |
| **document_identification_number** | string | Número do documento de identificação. Quando `document_identification_type` for `cin`, este campo deve ser igual ao CPF (`individual_document_number`). | 16 |
| **wedding_certificate**          | string | DOCUMENT_KEY do PDF do certificado de casamento da pessoa (enviado previamente). No caso de marital_status ser "single", o valor deste campo deve ser NULL. | 11 |
| **proof_of_residence** *    |string | DOCUMENT_KEY do PDF do comprovante de endereço do endereço enviado (enviado previamente). | 11 |

### Enumerador Document Identification Type

| Valor | Descrição |
|---|---|
| `rg` | RG — Registro Geral |
| `rne` | RNE — Registro Nacional de Estrangeiros |
| `cnh` | CNH — Carteira Nacional de Habilitação |
| `ctps` | CTPS — Carteira de Trabalho e Previdência Social |
| `class_document` | Documento de classe profissional (CRM, OAB, CRC, etc.) |
| `passport` | Passaporte |
| `other` | Outro |
| `cin` | CIN — Carteira de Identidade Nacional. O campo `document_identification_number` deve ser igual ao CPF do portador. |

### Objeto Address
| Campo              | Tipo   | Descrição                                                                | Máx. Caract. | 
|--------------------|--------|--------------------------------------------------------------------------|--------------| 
| **city** *         | string | Cidade do endereço                                                       | 100          |
| **state** *        | string | Estado do endereço (com dois caracteres maiúsculos)                      | 2            |
| **number** *       | string | Número do endereço                                                       | 10           |
| **street** *       | string | Rua do endereço                                                          | 100          |
| **complement** *   | string | Complemento do endereço (texto livre)                                    | 100          |
| **postal_code** *  | string | CEP do endereço (http://www.buscacep.correios.com.br/sistemas/buscacep/) | 8            |
| **neighborhood** * | string | Bairro do endereço                                                       | 100          |

### Objeto Phone
| Campo              | Descrição | Exemplo                                               | Máx. Caract. | 
|--------------------|-----------|-------------------------------------------------------|--------------| 
| **number** *       | string    | Número de telefone                                    | 10           |
| **area_code** *    | string    | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2            |
| **country_code** * | string    | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3            |

### Objeto Disbursement Bank Account

Uma emissão de dívida deve conter as informações bancárias para desembolso, por padrão, uma conta de titularidade do devedor.

| Campo                 | Tipo   | Descrição                                                                                          | Máx. Caract. | 
|-----------------------|--------|----------------------------------------------------------------------------------------------------|--------------|
| name                  | string | Nome do titular da conta                                                                           | 50           |
| document_number       | string | CPF do titular da conta                                                                            | 11           |
| bank_code *           | string | Código COMPE da instituição financeira (https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf) | 3            |
| branch_number *       | string | Número da agência (não informar o dígito verificador da agência!)                                  | 4            |
| account_number *      | string | Número da conta (sem o dígito verificador da conta!)                                               | 10           |
| account_digit *       | string | Dígito verificador da conta (informar zero no lugar de letras)                                     | 1            |
| account_type          | enum   | [Enumerador Account Type](#enumerador-account-type) Tipo da conta                                  | 1            |

### Objeto Financial

O objeto financial descreve as informações financeiras da operação de crédito.

| Campo                      | Tipo   | Descrição                                                                                                     | Máx. Caract. |
|----------------------------|--------|---------------------------------------------------------------------------------------------------------------|--------------|
| **amout**                  | float  | Valor de emissão/nominal da operação de crédito                                                               | -            |
| **interest_type**          | object | **[Enumerador Interest Type](#enumerador-interest-type)** - Método de amortização e forma de cálculo de juros | -            |
| **credit_operation_type**  | object | **[Enumerador Credit Operation Type](#enumerador-credit-operation-type)** - Tipo do contrato de crédito       | -            |
| **annual_interest_rate**   | float  | Taxa de juros pré-fixada expressa em decimal ao ano                                                           | -            |
| **disbursement_date**      | date   | Data do desembolso da operação                                                                                | -            |
| **interest_grace_period**  | int    | Carência de juros (em meses)                                                                                  | -            |
| **principal_grace_period** | int    | Período carência de principal                                                                                 | -            |
| **number_of_installments** | int    | Número de parcelas da operação de crédito                                                                     | -            |
| **fine_configuration**     | object | **[Objeto Fine Configuration](#objeto-fine-configuration)** - Configuração de juros e multa por atraso        | -            |

### Objeto Fine Configuration

No Objeto Fine Configuration são informados os valor de multa e juros por atraso da operação de crédito. 

| Campo                  | Tipo  | Descrição                                                                            | Máx. Caract. |
|------------------------|-------|--------------------------------------------------------------------------------------|--------------|
| **contract_fine_rate** | float | Percentual de multa por atraso                                                       | -            |
| **interest_base**      | enum  | **[Enumerador Interest Base](#enumerador-interest-base)** - Base de cálculo de juros | -            |
| **monthly_rate**       | float | Percentual de juros de atraso ao mês                                                 | -            |

### Objeto Rebates
| Campo                           | Tipo   | Descrição                                                                                                                                                                                                        | Máx. Caract. | 
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **fee_type** *                  | enum | Tipo da tarifa.                                                                                                                                   | -            | 
| **amount_type** * | object | Tipo do valor a ser cobrado.                                                                                 | -            |
| **amount** *                 | object | Valor da tarifa. Se o tipo da tarifa for percentual, o valor deverá ser entre 0 e 100. | -            |

### Response Body
| Campo                      | Tipo   | Descrição                                                      | Máx. Caract. |
|----------------------------|--------|----------------------------------------------------------------|--------------|
| **data[n].data**           | object | **[Objeto Data](#objeto-data)**                                | -            |
| **data[n].event_datetime** | date   | Momento da geração da operação de crédito                      | -            |
| **data[n].key**            | string | **DEBT-KEY** - Chave única da operação de crédito dentro da QI | -            |
| **data[n].status**         | string | **[Possívies Status de uma dívida](../status_de_uma_divida)**     | -            |
| **data[n].type**           | string | _debt_                                                         | -            |

# Enumeradores

### Enumerador _Person Type_
| Enumerador             | Descrição             |
|------------------------|-----------------------|
| **legal**   | Pessoa juridica        |
| **natural**    | Pesso física    |

### Enumerador _Amount Type_
| Enumerador             | Descrição             |
|------------------------|-----------------------|
| **tac**   | Tarifa cobrada do tomador. |
| **spread**    | Tarifa cobrada do fundo adicionada ao preço de cessão da operação.    |

### Enumerador _Account Type_
| Enumerador             | Descrição             |
|------------------------|-----------------------|
| **checking_account**   | Conta corrente        |
| **deposit_account**    | Conta de depósito     |
| **guaranteed_account** | Conta de garantia     |
| **investment_account** | Conta de investimento |
| **payment_account**    | Conta de pagamento    |
| **saving_account**     | Conta poupança        |
| **salary_account**     | Conta salário         |

### Enumerador _Interest Type_
| Enumerador           | Descrição                                                                                                                                                                |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **pre_price_days**   | Método de amortização Price (parcelas iguais) com cálculo do juros pré-fixado ao dia                                                                                     |
| **pre_price**        | Método de amortização Price (parcelas iguais) com cálculo do juros pré-fixado em períodos fixos (30 dias)                                                                |
| **pre_sac**          | Método de amortização SAC (amortização constante) com cálculo do juros pré-fixado ao dia                                                                                 |
| **post_sac**         | Método de amortização SAC (amortização constante) com cálculo do juros baseado em uma taxa pré-fixada + indexador pós-fixado (cdi, ipca ou igpm) ao dia                  |
| **post_price**       | Método de amortização Price (parcelas iguais) com cálculo do juros baseado em uma taxa pré-fixada + indexador pós-fixado (cdi, ipca ou igpm) em períodos fixos (30 dias) |
| **post_price_days**  | Método de amortização Price (parcelas iguais) com cálculo do juros baseado em uma taxa pré-fixada + indexador pós-fixado (cdi, ipca ou igpm) ao dia                      |

### Enumerador _Credit Operation Type_
| Enumerador    | Descrição                      |
|---------------|--------------------------------|
| **ccb**       | Cédula de Crédito Bancário     |
| **cce**       | Cédula de Crédito à Exportação |
| **cci**       | Cédula de Crédito Imobiliário  |
| **nce**       | Nota de Crédito à Exportação   |

### Enumerador _Interest Base_
| Enumerador            | Descrição                                                                 |
|-----------------------|---------------------------------------------------------------------------|
| **workdays**          | Base de cálculo de juros em dias úteis considerando um ano de 252 dias    |
| **calendar_days**     | Base de cálculo de juros em dias corridos considerando um ano de 360 dias |
| **calendar_days_365** | Base de cálculo de juros em dias corridos considerando um ano de 365 dias |

### Enumerador _Fee Type_
Cada tipo de fee deve ser previamente habilitado e configurado pela QI Tech

| Enumerador            | Descrição                                                                  |
|-----------------------|----------------------------------------------------------------------------|
| **tac**               | Tarifa de abertura de cadastro                                             |
| **spread**            | Ágio cobrado no valor de aquisição da operação de crédito                  |
| **warranty_analysis** | Tarifa de análise de garantias                                             |
| **ted_fee**           | Tarifa de TED                                                              |
| **spread_ted_fee**    | Ágio da tarifa de TED cobrado no valor de aquisição da operação de crédito |
| **spread_merchant**   | Ágio destinado à remuneração do lojista, cobrado no valor de aquisição (cessão) da operação de crédito |
| **tac_assignment_discount** | Parcela da tarifa de abertura de cadastro (TAC) destinada ao fundo (cessionário), cobrada do tomador; compõe o valor de emissão da operação |

---

# Emissão de dívida PJ

URL: /documentation/emissao_de_divida/emissao/emissao_de_divida_pj

Com a API de emissão de dívida é possível solicitar a emissão de uma dívida para uma pessoa jurídica.
Não é necessário realizar o cadastro prévio do tomador, basta informar os dados cadastrais no momento da solicitação da dívida.

:::danger Atenção!

A QI Tech oferece uma solução de Onboarding de novos clientes e Anti-fraude.

[Confira aqui a documentação das APIs deste serviço.](https://www.zaig.com.br/en/devcenter.html)

Para receber uma cotação, entre em contato com nosso time comercial:

comercial@qitech.com.br ou (11) 3522-1301
:::

A API de dívida foi desenhada para ser executada em apenas uma
requisição, após um prévio envio dos arquivos ([upload de documentos](../../upload_de_documentos)).
O formato de assinatura do header e do body desta requisição é descrito em detalhes
[aqui](../../primeiros_passos/teste_de_autenticacao).

## Request

ENDPOINT /debt
MÉTODO POST

Request Body

```json
{
    "borrower": {
        "name": "RAZAO SOCIAL EMPRESA",
        "email": "emailempresa@email.com",
        "phone": {
            "number": "991112222",
            "area_code": "11",
            "country_code": "055"
        },
        "address": {
            "city": "São Paulo",
            "state": "SP",
            "number": "215",
            "street": "Rua Gilberto Sabino",
            "complement": "3 andar",
            "postal_code": "05425020",
            "neighborhood": "Pinheiros"
        },
        "cnae_code": "6822-6/00",
        "role_type": "issuer",
        "person_type": "legal",
        "company_type": "ltda",
        "trading_name": "NOME FANTASIA DA EMPRESA",
        "foundation_date": "2019-07-05",
        "attached_documents_list": [],
        "company_document_number": "80282008000127",
        "company_statute": "aa28e598-55e2-40f1-8884-671772c541a1",
        "company_representatives": [
            {
                "name": "NOME DO REPRESENTANTE",
                "email": "nomedorepresentante@email.com",
                "phone": {
                    "number": "990121234",
                    "area_code": "11",
                    "country_code": "055"
                },
                "is_pep": false,
                "final_beneficiary": true,
                "spouse": {
                    "name": "NOME CONJUGE REPRESENTANTE",
                    "email": "conjugerepresentante@email.com",
                    "phone": {
                        "number": "988881234",
                        "area_code": "11",
                        "country_code": "055"
                    },
                    "birth_date": "1994-12-04",
                    "person_type": "natural",
                    "is_pep": false,
                    "mother_name": "NOME DA MAE DO CONJUGE DO REPRESENTANTE",
                    "individual_document_number": "26571990032",
                    "document_identification_number": "10101010100",
                    "address": {
                        "city": "São Paulo",
                        "state": "SP",
                        "number": "215",
                        "street": "Rua Gilberto Sabino",
                        "complement": "3 andar",
                        "postal_code": "05425020",
                        "neighborhood": "Pinheiros"
                    }
                },
                "address": {
                    "city": "São Paulo",
                    "state": "SP",
                    "number": "215",
                    "street": "Rua Gilberto Sabino",
                    "complement": "3 andar",
                    "postal_code": "05425020",
                    "neighborhood": "Pinheiros"
                },
                "role_type": "company_representative",
                "birth_date": "1993-09-10",
                "profession": "DIRETOR",
                "mother_name": "NOME DA MAE DO REPRESENTANTE",
                "nationality": "BRASILEIRO",
                "person_type": "natural",
                "marital_status": "married",
                "property_system": "partial_communion_of_goods",
                "attached_documents_list": [],
                "individual_document_number": "31057466093",
                "document_identification_number": "20202020200"
            }
        ]
    },
    "financial": {
        "disbursed_amount": 10000,
        "interest_type": "pre_price_days",
        "credit_operation_type": "ccb",
        "monthly_interest_rate": 0.03,
        "disbursement_date": "2023-05-04",
        "first_due_date": "2023-06-03",
        "interest_grace_period": 0,
        "principal_grace_period": 0,
        "number_of_installments": 1,
        "fine_configuration": {
            "contract_fine_rate": 0.02,
            "interest_base": "calendar_days",
            "monthly_rate": 0.01
        }
    },
    "disbursement_bank_account": {
        "name": "RAZAO SOCIAL EMPRESA",
        "document_number": "80282008000127",
        "bank_code": "341",
        "branch_number": "8615",
        "account_number": "22110",
        "account_digit": "2",
        "account_type": "checking_account"
    },
    "purchaser_document_number": "32402502000135"
}

```

## Response

A resposta desse pedido de dívida retornará o plano de pagamento assim como uma **DEBT-KEY**, que é o identificador da dívida na QI SCD.

STATUS 200

Response Body

```json
{
  "data": {
    "additional_iof": 38.57988,
    "annual_cet": "71,3492%",
    "assignment_amount": 10254.13,
    "base_iof": 12.487704111671501,
    "borrower": {
      "document_number": "80282008000127",
      "name": "RAZAO SOCIAL EMPRESA",
      "related_party_key": "7620181e-f46a-45c1-a4ea-60439b9662ad"
    },
    "cet": "4,5900%",
    "collaterals": [],
    "contract": {
      "number": "0000069971/RSE",
      "signature_information": [
        {
          "signature_url": null,
          "signer_document_number": "31057466093",
          "signer_email": "nomedorepresentante@email.com",
          "signer_external_key": null,
          "signer_name": "NOME DO REPRESENTANTE",
          "signer_role": "issuer"
        }
      ],
      "urls": [
        "https://storage.googleapis.com/sandbox-doc-api/documents/df3e4530-3deb-4ba8-ad4e-c28ebeffb831/20230504122831.pdf"
      ]
    },
    "contract_fee_amount": 101.53,
    "contract_fees": [
      {
        "fee_amount": 101.53,
        "fee_type": "tac"
      }
    ],
    "external_contract_fee_amount": 101.53,
    "external_contract_fees": [
      {
        "fee_amount": 101.53,
        "fee_type": "spread",
        "net_fee_amount": 92.14,
        "tax_amount": 9.39
      },
      {
        "fee_amount": 0,
        "fee_type": "tac",
        "net_fee_amount": 0,
        "tax_amount": 0
      }
    ],
    "installments": [
      {
        "accrual_reference_date": null,
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": null,
        "business_due_date": "2023-06-05",
        "calendar_days": 30,
        "digitable_line": null,
        "due_date": "2023-06-03",
        "due_interest": 0,
        "due_principal": 10152.6,
        "fine_amount": null,
        "has_interest": true,
        "installment_history": [],
        "installment_key": "0eb42a83-557a-437a-9819-099b5364cde9",
        "installment_number": 1,
        "installment_payment": [],
        "installment_status": "created",
        "installment_type": "principal",
        "original_due_principal": 10152.6,
        "original_pre_fixed_amount": 300.3450311613816,
        "original_principal_amortization_amount": 10152.60496883862,
        "original_total_amount": 10452.95,
        "paid_amount": 0,
        "paid_at": null,
        "post_fixed_amount": 0,
        "pre_fixed_amount": 300.3450311613816,
        "principal_amortization_amount": 10152.60496883862,
        "qr_code_key": null,
        "qr_code_url": null,
        "renegotiation_proposal_key": null,
        "tax_amount": 12.487704111671501,
        "total_accrual_amount": null,
        "total_amount": 10452.95,
        "total_paid_amount": 0,
        "workdays": 21
      }
    ],
    "iof_charge_method": "financed",
    "issue_amount": 10152.6,
    "net_external_contract_fee_amount": 92.14,
    "number_of_installments": 1,
    "prefixed_interest_rate": {
      "annual_rate": 0.42576089,
      "created_at": "2023-05-04T12:28:30",
      "daily_rate": 0.00097227,
      "interest_base": "calendar_days_365",
      "monthly_rate": 0.03
    },
    "requester_identifier_key": "feceb7fe-1305-45eb-899d-c87d36bcc534",
    "total_iof": 51.07,
    "total_pre_fixed_amount": 300.3450311613816
  },
  "event_datetime": "2023-05-04 12:28:35",
  "key": "feceb7fe-1305-45eb-899d-c87d36bcc534",
  "status": "waiting_signature",
  "webhook_type": "debt"
}

```

### Objeto Request Body
| Campo                           | Tipo   | Descrição                                                                                                                                                                                                        | Máx. Caract. | 
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **borrower** *                  | object | **[Objeto Borrower](#objeto-borrower)** - Devedor da operação de crédito                                                                                                                                         | -            |
| **guarantor**                   | object | **[Objeto Guarantor](#objeto-borrower)** - Garantidores da operação da operação de crédito                                                                                                                       | -            |  
| **disbursement_bank_account** * | object | **[Objeto Disbursement Bank Account](#objeto-disbursement_bank_accounts)** - Dados da conta bancária para desembolso da operação                                                                                 | -            |
| **financial** *                 | object | **[Objeto Financial](#objeto-financial)** - Dados da conta bancária para desembolso da operaçãoIdentificador de que o objeto enviado é uma pessoa física. Deve conter SEMPRE o  valor "natural" para borrower PF | -            |
| **purchaser_document_number** * | string | CNPJ do cessionário (comprador) da operação de crédito                                                                                                                                                           | -            |

### Objeto Borrower  
| Campo                            | Tipo    | Descrição                                                                             | Máx. Caract. | 
|----------------------------------|---------|---------------------------------------------------------------------------------------|--------------|
| **name** *                       | string  | Razão social da empresa                                                                   | 100          |
| **trading_name** * | string | Nome fantasia |  |
| **email**   *                     | string  | Email institucional da empresa                                                                 | 254          |
| **phone**  *                      | object  | **[Objeto Phone](#objeto-phone)** - Telefone da empresa                     | -            | 
| **is_pep** *                     | boolean | Indicador de PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep)      | -            |
| **address** *                    | object  | **[Objeto Address](#objeto-address)** - Endereço do devedor                           | -            | 
| **role_type** *                  | enum    | default: _issuer_                                                                     | -            |
| **person_type** *                | string  | Indicador de pessoa jurídica - default: _legal_                                       | -            |
| **company_document_number** *    | string  | CNPJ (apenas números)                                                                 | -            |
| **cnae_code** * | string |  Classificação Nacional de Atividades Econômicas | |
| **company_representatives** *    | array of objects | Lista de representante legais da empresa  | **[Objeto Company Representatives](#objeto-company_representatives)** |
| **company_type** * | enum |  Tipo da empresa: "ltda", "sa",  "micro_enterprise" ou  "freelancer"| -  |
| **company_statute** * | string | `document_key` do PDF do estatuto da empresa | |
| **directors_election_minute** | string | `document_key` do PDF da Ata de eleição da empresa (obrigatório apenas para emrpresas com company_type "sa") | |
| **foundation_date** * | date | Data de abertura da empresa (formato "AAAA-MM-DD") |  |

Como mostrado acima tanto o campo "borrower" quanto os campos "guarantors" podem ser populados por Objeto PF ou Objeto PJ. Objeto PJ é o descritivo de uma pessoa jurídica na QI Tech.

### Objeto Company Representatives

| Campo | Descrição | Exemplo | Máx. Caract. | 
|---|---|---|---| 
| **person_type** * | string | Identificador de que o objeto enviado é uma pessoa física ou jurídica. | natural |
| **name** * | string | Razão social em caso de operações PJ ou Nome da pessoa em caso de operações PF. Limitado a 100 caracteres. |  |
| **mother_name** * | string | Nome da mãe do cliente em caso de PF. Limitado a 100 caracteres. |  |
| **birth_date** * | string | Data de nascimento da pessoa (formato "AAAA-MM-DD") | - |
| **profession** * |string | Profissão do cliente. Limitado a 64 caracteres. | 64 |
| **nationality** * | string | Nacionalidade do cliente.  | 50  |
| **marital_status** * | string | Estado civil do cliente. |
| **property_system** * |string | Regime de separação de bens (obrigatório apenas para pessoas com marital_status "married"). | **[Enumeradores property_system](#enumeradores-property_system)**  |
| **wedding_certificate** * | string | DOCUMENT_KEY do PDF do certificado de casamento da pessoa (enviado previamente). No caso de marital_status ser "single", o valor deste campo deve ser NULL. |  |
| **spouse** * |string |**[Objeto Spouse](#objeto-spouse)** (obrigatório apenas quando "compulsory_separation_of_goods" for "total_communion_of_goods", "partial_communion_of_goods", "final_participation_of_acquisitions" ou "compulsory_separation_of_goods"). No caso de marital_status ser "single", o valor deste campo deve ser NULL. | **[Objeto Spouse](#objeto-spouse)** |
| **is_pep** * |  boolean |Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep). | true/false |
| **final_beneficiary** | boolean | Declaração se o representante é beneficiário final da empresa. | true/false |
| **individual_document_number** * |string | CPF da pessoa (apenas números). | 10 |
| **document_identification** * |string | DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG, CNH ou CIN) (enviado previamente) |  |
| **document_identification_back** |string | DOCUMENT_KEY do PDF da parte de trás do documento de identificação da pessoa com foto (RG, CNH ou CIN) (enviado previamente). |  |
| **document_identification_type** * | enum | Tipo do documento de identificação. Valores aceitos: `rg`, `rne`, `cnh`, `ctps`, `class_document`, `passport`, `other`, `cin`. Quando `cin`, o campo `document_identification_number` deve ser igual ao CPF. |  |
| **document_identification_number** * |string | Número do documento de identificação da pessoa enviado em "document_identification". Quando `document_identification_type` for `cin`, deve ser igual ao CPF (`individual_document_number`). | 16 |
| **email** * |string | Email do cliente. | 254 | 
| **phone** * | object | Telefone do cliente | **[Objeto Phone](#objeto-phone)** | - |
| **address** | object | Endereço do cliente. |  **[Objeto Address](#objeto-address)**  |  
| **proof_of_residence**  |string | DOCUMENT_KEY do PDF do comprovante de endereço do endereço enviado (enviado previamente). | - |

### Objeto Spouse
| Campo | Descrição | Exemplo | Máx. Caract. | 
|---|---|---|---| 
| **person_type** * | string | Identificador de que o objeto enviado é uma pessoa física ou jurídica. | natural |
| **name** * | string | Razão social em caso de operações PJ ou Nome da pessoa em caso de operações PF. Limitado a 100 caracteres. |  |
| **mother_name** * | string | Nome da mãe do cliente em caso de PF. Limitado a 100 caracteres. |  |
| **birth_date** * | string | Data de nascimento da pessoa (formato "AAAA-MM-DD") | - |
| **profession** * |string | Profissão do cliente. Limitado a 64 caracteres. | 64 |
| **is_pep** * |  boolean |Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep). | true/false |
| **individual_document_number** * |string | CPF da pessoa (apenas números). | 10 |
| **document_identification_number** * |string | Número do documento de identificação da pessoa enviado em "document_identification".  | 16 |
| **email** * |string | Email do cliente. | 254 | 
| **phone** * | object | Telefone do cliente | **[Objeto phone](#objeto-phone)** | - |
| **address** | object | Endereço do cliente. |  **[Objeto address](#objeto-address)**  |  

### Objeto Address 

| Campo              | Tipo   | Descrição                                                                | Máx. Caract. | 
|--------------------|--------|--------------------------------------------------------------------------|--------------| 
| **city** *         | string | Cidade do endereço                                                       | 100          |
| **state** *        | string | Estado do endereço (com dois caracteres maiúsculos)                      | 2            |
| **number** *       | string | Número do endereço                                                       | 10           |
| **street** *       | string | Rua do endereço                                                          | 100          |
| **complement** *   | string | Complemento do endereço (texto livre)                                    | 100          |
| **postal_code** *  | string | CEP do endereço (http://www.buscacep.correios.com.br/sistemas/buscacep/) | 8            |
| **neighborhood** * | string | Bairro do endereço                                                       | 100          |

### Objeto Phone 

| Campo              | Descrição | Exemplo                                               | Máx. Caract. | 
|--------------------|-----------|-------------------------------------------------------|--------------| 
| **number** *       | string    | Número de telefone                                    | 10           |
| **area_code** *    | string    | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2            |
| **country_code** * | string    | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3            |

### Objeto Disbursement Bank Account

Uma emissão de dívida deve conter as informações bancárias para desembolso, por padrão, uma conta de titularidade do devedor.

| Campo                 | Tipo   | Descrição                                                                                          | Máx. Caract. | 
|-----------------------|--------|----------------------------------------------------------------------------------------------------|--------------|
| name                  | string | Nome do titular da conta                                                                           | 50           |
| document_number       | string | CPF do titular da conta                                                                            | 11           |
| bank_code *           | string | Código COMPE da instituição financeira (https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf) | 3            |
| branch_number *       | string | Número da agência (não informar o dígito verificador da agência!)                                  | 4            |
| account_number *      | string | Número da conta (sem o dígito verificador da conta!)                                               | 10           |
| account_digit *       | string | Dígito verificador da conta (informar zero no lugar de letras)                                     | 1            |
| account_type          | enum   | [Enumerador Account Type](#enumerador-account-type) Tipo da conta                                  | 1            |

### Objeto Financial 

O objeto financial descreve as informações financeiras da emissão. Aqui são definidas a taxa de juros, carência e valor 
da dívida entre outros. O Objeto Financeiro possui os campos descritos abaixo, porém é importante notar que alguns
campos são opicionais e excludentes (caso um esteja disponível o outro não deverá ser enviado).

| Campo                      | Tipo   | Descrição                                                                                                     | Máx. Caract. |
|----------------------------|--------|---------------------------------------------------------------------------------------------------------------|--------------|
| **amout**                  | float  | Valor de emissão/nominal da operação de crédito                                                               | -            |
| **interest_type**          | object | **[Enumerador Interest Type](#enumerador-interest-type)** - Método de amortização e forma de cálculo de juros | -            |
| **credit_operation_type**  | object | **[Enumerador Credit Operation Type](#enumerador-credit-operation-type)** - Tipo do contrato de crédito       | -            |
| **annual_interest_rate**   | float  | Taxa de juros pré-fixada expressa em decimal ao ano                                                           | -            |
| **disbursement_date**      | date   | Data do desembolso da operação                                                                                | -            |
| **interest_grace_period**  | int    | Carência de juros (em meses)                                                                                  | -            |
| **principal_grace_period** | int    | Período carência de principal                                                                                 | -            |
| **number_of_installments** | int    | Número de parcelas da operação de crédito                                                                     | -            |
| **fine_configuration**     | object | **[Objeto Fine Configuration](#objeto-fine-configuration)** - Configuração de juros e multa por atraso        | -            |

### Objeto Fine Configuration

No Objeto Fine Configuration são informados os valor de multa e juros por atraso da operação de crédito. 

| Campo                  | Tipo  | Descrição                                                                            | Máx. Caract. |
|------------------------|-------|--------------------------------------------------------------------------------------|--------------|
| **contract_fine_rate** | float | Percentual de multa por atraso                                                       | -            |
| **interest_base**      | enum  | **[Enumerador Interest Base](#enumerador-interest-base)** - Base de cálculo de juros | -            |
| **monthly_rate**       | float | Percentual de juros de atraso ao mês                                                 | -            |

### Objeto Rebates
| Campo                           | Tipo   | Descrição                                                                                                                                                                                                        | Máx. Caract. | 
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **fee_type** *                  | enum | Tipo da tarifa.                                                                                                                                   | -            | 
| **amount_type** * | object | Tipo do valor a ser cobrado.                                                                                 | -            |
| **amount** *                 | object | Valor da tarifa. Se o tipo da tarifa for percentual, o valor deverá ser entre 0 e 100. | -            |

### Response Body
| Campo                      | Tipo   | Descrição                                                      | Máx. Caract. |
|----------------------------|--------|----------------------------------------------------------------|--------------|
| **data[n].data**           | object | **[Objeto Data](#objeto-data)**                                | -            |
| **data[n].event_datetime** | date   | Momento da geração da operação de crédito                      | -            |
| **data[n].key**            | string | **DEBT-KEY** - Chave única da operação de crédito dentro da QI | -            |
| **data[n].status**         | string | **[Possívies Status de uma dívida](../status_de_uma_divida)**     | -            |
| **data[n].type**           | string | _debt_                                                         | -            |

# Enumeradores

### Enumerador _Person Type_
| Enumerador             | Descrição             |
|------------------------|-----------------------|
| **legal**   | Pessoa juridica        |
| **natural**    | Pesso física    |

### Enumerador _Amount Type_
| Enumerador             | Descrição             |
|------------------------|-----------------------|
| **tac**   | Tarifa cobrada do tomador. |
| **spread**    | Tarifa cobrada do fundo adicionada ao preço de cessão da operação.    |

### Enumerador _Account Type_
| Enumerador             | Descrição             |
|------------------------|-----------------------|
| **checking_account**   | Conta corrente        |
| **deposit_account**    | Conta de depósito     |
| **guaranteed_account** | Conta de garantia     |
| **investment_account** | Conta de investimento |
| **payment_account**    | Conta de pagamento    |
| **saving_account**     | Conta poupança        |
| **salary_account**     | Conta salário         |

### Enumerador _Interest Type_
| Enumerador           | Descrição                                                                                                                                                                |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **pre_price_days**   | Método de amortização Price (parcelas iguais) com cálculo do juros pré-fixado ao dia                                                                                     |
| **pre_price**        | Método de amortização Price (parcelas iguais) com cálculo do juros pré-fixado em períodos fixos (30 dias)                                                                |
| **pre_sac**          | Método de amortização SAC (amortização constante) com cálculo do juros pré-fixado ao dia                                                                                 |
| **post_sac**         | Método de amortização SAC (amortização constante) com cálculo do juros baseado em uma taxa pré-fixada + indexador pós-fixado (cdi, ipca ou igpm) ao dia                  |
| **post_price**       | Método de amortização Price (parcelas iguais) com cálculo do juros baseado em uma taxa pré-fixada + indexador pós-fixado (cdi, ipca ou igpm) em períodos fixos (30 dias) |
| **post_price_days**  | Método de amortização Price (parcelas iguais) com cálculo do juros baseado em uma taxa pré-fixada + indexador pós-fixado (cdi, ipca ou igpm) ao dia                      |

### Enumerador _Credit Operation Type_
| Enumerador | Descrição                      |
|------------|--------------------------------|
| **ccb**    | Cédula de Crédito Bancário     |
| **cce**    | Cédula de Crédito à Exportação |
| **cci**    | Cédula de Crédito Imobiliário  |
| **nce**    | Nota de Crédito à Exportação   |
| **ncom**   | Nota Comercial                 |

### Enumerador _Interest Base_
| Enumerador            | Descrição                                                                 |
|-----------------------|---------------------------------------------------------------------------|
| **workdays**          | Base de cálculo de juros em dias úteis considerando um ano de 252 dias    |
| **calendar_days**     | Base de cálculo de juros em dias corridos considerando um ano de 360 dias |
| **calendar_days_365** | Base de cálculo de juros em dias corridos considerando um ano de 365 dias |

### Enumerador _Fee Type_
Cada tipo de fee deve ser previamente habilitado e configurado pela QI Tech

| Enumerador            | Descrição                                                                  |
|-----------------------|----------------------------------------------------------------------------|
| **tac**               | Tarifa de abertura de cadastro                                             |
| **spread**            | Ágio cobrado no valor de aquisição da operação de crédito                  |
| **warranty_analysis** | Tarifa de análise de garantias                                             |
| **ted_fee**           | Tarifa de TED                                                              |
| **spread_ted_fee**    | Ágio da tarifa de TED cobrado no valor de aquisição da operação de crédito |
| **spread_merchant**   | Ágio destinado à remuneração do lojista, cobrado no valor de aquisição (cessão) da operação de crédito |
| **tac_assignment_discount** | Parcela da tarifa de abertura de cadastro (TAC) destinada ao fundo (cessionário), cobrada do tomador; compõe o valor de emissão da operação |

---

# Exemplos de payload de desembolso

URL: /documentation/emissao_de_divida/emissao/exemplo_payloads_desembolso

### Desembolsar em conta interna QI Tech

ENDPOINT /debt
MÉTODO POST

```json title='Request Body'
{
	"disbursement_bank_accounts": [{
		"bank_code": "329",
		"branch_number": "001",
		"account_number": "6947216",
		"account_digit": "4",
		"document_number": "94632180173",
		"name": "Pedro Felipe Henrique Alves",
		"percentage_receivable": 100
	}]
  ...
}
```

--- 

### Desembolsar com Pix Manual

ENDPOINT /debt
MÉTODO POST

```json title='Request Body'
{
	"disbursement_bank_accounts": [{
			"document_number": "31233261000185",
			"name": "Jorge Augusto Salgado Salhani",
			"pix_transfer_type": "manual",
			"bank_code": "329",
			"branch_number": "0001",
			"account_number": "62400",
			"account_digit": "6",
			"percentage_receivable": 100
		}]
		...
}
```
:::info Tipos de Chave Pix
A “pix_key” pode ser um CPF, CNPJ, E-mail, Celular ou uma Chave Aleatória (UUID), seguindo as seguintes formatações:

CPF: Número inteiro com 11 dígitos.

CNPJ: Número inteiro com 14 dígitos.

E-mail: Texto contendo ao menos um “@”.

Celular: Texto contendo os seguintes valores: “+55” + “DDD do celular“ + “Número Inteiro do Celular com no mínimo 8 e no máximo 9 dígitos”. Ex: “+5511987654321“.

Chave Aleatória: UUID.
:::

---

### Desembolsar com chave Pix

ENDPOINT /debt
MÉTODO POST

```json title='Request Body'

{
	"disbursement_bank_accounts": [{
			"document_number": "31233261000185",
			"name": "Jorge Augusto Salgado Salhani",
			"pix_key": "2f205c99-3161-4120-badd-854039d12de6",
			"pix_transfer_type": "key"
		}]
		...
}
```
---

### Desembolsar com QR Code Pix

ENDPOINT /debt
MÉTODO POST

```json title='Request Body'

{
	"disbursement_bank_accounts": [{
			"qr_code_key": "b76e436e-4767-4b16-91e6-9bfc794f2510"
		}]
		...
}
```

---

### Desembolsar com TED

ENDPOINT /debt
MÉTODO POST

```json title='Request Body'

{
	"disbursement_bank_accounts": [{
			"transfer_method": "ted",
			"bank_code": "329",
			"branch_number": "0001",
			"account_number": "62400",
			"account_digit": "6",
			"document_number": "31233261000185",
			"name": "Jorge Conta destino de desembolso",
			"percentage_receivable": 100
		}]
		...
}
```

---

###  Desembolsar pagando um Boleto

ENDPOINT /debt
MÉTODO POST

```json title='Request Body'

{
	"disbursement_bank_accounts": [{
		"digitable_line": "836400000169072200500006763953020230059001020193",
		"amount_receivable": 1607.22
	}]
		...
}
```

---

# Assinaturas alternativas

URL: /documentation/emissao_de_divida/formalizacao/assinatura_de_contrato

Para o uso de formas alternativas de assinatura é necessario que o dossie de arquivos de comprovação sejá compactado em um arquivo .zip e enviado através do endpoint /upload QI TECH, assim o document_key retornado pode ser ultilizado neste endpoint como forma de assinatura de contrato.

Exemplos de assinaturas alternativas:

- Ligação gravada;

- Analise de crédito;

## Request

ENDPOINT /debt/ DEBT-KEY /signed
MÉTODO POST

**Request Body**

```json
{
    "type": "data-signature",
    "signatures": [
        {
            "signed_object": {
                "raw_text": "Lorem ipsum dolor sit amet, consectetur a....",
                "document_key": "79003de0-2590-455d-9b73-426b8ca284eb",
                "document_md5": "7521bd5621d97af26b2c1721fc4023a8"
            },
            "authenticity": {
                "timestamp": "1970-01-01 00:00:01",
                "document_key": "79003de0-2590-455d-9b73-426b8ca284eb",
                "document_md5": "79003de0-2590-455d-9b73-426b8ca284eb"
            },
            "signer": {
                "name": "IVANILDO DE SENA LIMA",
                "email": "ivanlima2604@gmail.com",
                "phone": {
                    "country_code": "055",
                    "area_code": "11",
                    "number": "999999999"
                },
                "document_number": "61766976204"
            },
            "authentication_type": "zip"
        }
    ]
}
```

## Path Params

| Campo |  Tipo | Descrição | Caracteres | 
|---|---|---|---|
| `debt_key` * | string |  Chave da divida devolvida no momento da criação da operação de crédito. | - |

## Body Params

| Campo |  Tipo | Descrição | Caracteres | 
|---|---|---|---|
| `type` * | string |  Tipo de assinatura que será enviada. | - |
| `signatures` * | array of objects | Lista contendo objetos de comprovação de assinatura - deve ser enviado no caso de assinatura "type": "data-signature". |  **[Objetos signatures](#objeto-signatures )**|
| `path-pdf-signed` * | string | URL com o PDF assinado - deve ser enviado no caso de assinatura "type": "pdf-signature". | - |

### Objeto signatures

| Campo |  Tipo | Descrição | Caracteres | 
|---|---|---|---|
| `signed_object` | object | Objeto contendo o documento que esta sendo assinado. | **[Objetos signed_object](#objeto-signed_object )** |
| `authenticity` | object | objeto com dados de autenticação. | **[Objetos authenticity](#objeto-authenticity )** |
| `signer` | object | Objeto com os dados do signatário. | **[Objeto signer](#objeto-signer )** |
| `authentication_type` *| string | Tipo de assinatura. | - |

### Objeto signed_object

| Campo |  Tipo | Descrição | Caracteres | 
|---|---|---|---|
| `raw_text` | string | Texto corrido com os dados do contrato que será assinado (Obrigatório para autenticação tipo opt-in). | - |
| `document_key` | string | DOCUMENT_KEY do arquivo assinado enviado a partir da API 1.1 (obrigatório apenas caso o campo "raw_text" não seja enviado). | - |
| `document_md5` | string | DOCUMENT_MD% do arquivo assinado enviado a partir da API 1.1 (obrigatório apenas caso o campo "raw_text" não seja enviado). | - |

### Objeto authenticity

| Campo |  Tipo | Descrição | Caracteres | 
|---|---|---|---|
| `timestamp` *| string | Data da assinatura. | - |
| `document_key` * | string | DOCUMET_KEY retornado pela API 1.1 após o envio do arquivo com as evidencias de assinatura. | - |
| `document_md5` * | string | DOCUMET_MD5 retornado pela API 1.1 após o envio do arquivo com as evidencias de assinatura. | - |
 
### Objeto signer

| Campo |  Tipo | Descrição | Caracteres | 
|---|---|---|---|
| `name` *| string | Nome do signatário. | - |
| `email` *| string | E-mail do signatário. | - |
| `phone` | string | Objeto de telefone do signatário. |  **[Objeto phone](#objeto-phone)** |
| `document_number` *| string | Numero de documento do signatário. | - |

### Objeto phone

| Campo |  Tipo | Descrição | Caracteres | 
|---|---|---|---|
|`country_code` *| string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 | 
| `area_code` *| string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |Número de telefone (apenas números) |  10 |

## Response

STATUS 200

**Response Body**

```json
{
  "data": {},
  "event_datetime": "2022-11-07 15:24:47",
  "key": "\<DEBT-KEY\>",
  "status": "signature_received",
  "webhook_type": "debt"
}

```

STATUS 400

**Response Body**

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

---

# Assinatura de contrato com OPT-IN

URL: /documentation/emissao_de_divida/formalizacao/assinatura_opt_in

## Request

ENDPOINT /debt/ DEBT-KEY /signed
MÉTODO POST

**Request Body**

```json
{
    "type": "data_signature",
    "signatures": [
        {
            "signed_object": {
                "raw_text": "Lorem ipsum dolor sit amet, consectetur a...."
            },
            "authenticity": {
                "timestamp": "1970-01-01 00:00:01",
                "ip_address": "179.104.42.245",
                "session_id": "ddb1d063-4fdf-4330-af9c-3316e9142ff3"
            },
            "signer": {
                "name": "IVANILDO DE SENA LIMA",
                "email": "ivanlima2604@gmail.com",
                "phone": {
                    "country_code": "055",
                    "area_code": "11",
                    "number": "999999999"
                },
                "document_number": "61766976204"
            },
            "authentication_type": "opt-in"
        }
    ]
}
```

## Path Params

| Campo |  Tipo | Descrição | Caracteres | 
|---|---|---|---|
| `debt_key` * | string |  Chave da divida devolvida no momento da criação da operação de crédito. | - |

## Body Params

| Campo |  Tipo | Descrição | Caracteres | 
|---|---|---|---|
| `type` * | string |  Tipo de assinatura que será enviada. | - |
| `signatures` * | array of objects | Lista contendo objetos de comprovação de assinatura - deve ser enviado no caso de assinatura "type": "data-signature". |  **[Objetos signatures](#objeto-signatures )**|

### Objeto signatures

| Campo |  Tipo | Descrição | Caracteres | 
|---|---|---|---|
| `signed_object` | object | Objeto contendo o documento que esta sendo assinado. | **[Objetos signed_object](#objeto-signed_object )** |
| `authenticity` | object | objeto com dados de autenticação. | **[Objetos authenticity](#objeto-authenticity )** |
| `signer` | object | Objeto com os dados do signatário. | **[Objeto signer](#objeto-signer )** |
| `authentication_type` *| string | Tipo de assinatura. | - |

### Objeto signed_object

| Campo |  Tipo | Descrição | Caracteres | 
|---|---|---|---|
| `raw_text` * | string | Texto corrido com os dados do contrato que será assinado. | - |

### Objeto authenticity

| Campo |  Tipo | Descrição | Caracteres | 
|---|---|---|---|
| `timestamp` *| string | Data da assinatura. | - |
| `ip_address` | string | Campo obrigatório para o authentication_type “opt-in” indicando o endereço de IP onde o aceite foi coletado. | - |
| `session_id` | string | ID de identificação de sessão do cliente no momento da assinatura - deve ser consultável e as evidencias da sessão devem ser armazenadas por um período de no mínimo 5 anos (Obrigatório para o authentication_type "opt-in"). | - |
| `geolocation` | object | Campo opcional de geolocalização. | - |
 
### Objeto signer

| Campo |  Tipo | Descrição | Caracteres | 
|---|---|---|---|
| `name` *| string | Nome do signatário. | - |
| `email` *| string | E-mail do signatário. | - |
| `phone` | string | Objeto de telefone do signatário. |  **[Objeto phone](#objeto-phone)** |
| `document_number` *| string | Numero de documento do signatário. | - |

### Objeto phone

| Campo |  Tipo | Descrição | Caracteres | 
|---|---|---|---|
|`country_code` *| string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 | 
| `area_code` *| string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |Número de telefone (apenas números) |  10 |

## Response

STATUS 200

**Response Body**

```json
{
  "data": {},
  "event_datetime": "2022-11-07 15:24:47",
  "key": "\<DEBT-KEY\>",
  "status": "signature_received",
  "webhook_type": "debt"
}

```

STATUS 400

**Response Body**

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

---

# Envio do PDF assinado

URL: /documentation/emissao_de_divida/formalizacao/assinatura_pdf

## Request

ENDPOINT /debt/ DEBT-KEY /signed
MÉTODO POST

**Request Body**

```json
{
    "type": "pdf-signature",
    "path-pdf-signed": "https://www.google.com/"
}
```

## Path Params

| Campo |  Tipo | Descrição | Caracteres | 
|---|---|---|---|
| `debt_key` * | string |  Chave da divida devolvida no momento da criação da operação de crédito. | - |

## Body Params

| Campo |  Tipo | Descrição | Caracteres | 
|---|---|---|---|
| `type` * | string |  Tipo de assinatura que será enviada. | - |
| `path-pdf-signed` * | string | URL com o PDF assinado - deve ser enviado no caso de assinatura "type": "pdf-signature". | - |

## Response

STATUS 200

**Response Body**

```json
{
  "data": {},
  "event_datetime": "2022-11-07 15:24:47",
  "key": "\<DEBT-KEY\>",
  "status": "signature_received",
  "webhook_type": "debt"
}

```

STATUS 400

**Response Body**

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

---

# Assinatura de contrato com selfie

URL: /documentation/emissao_de_divida/formalizacao/assinatura_selfie

A autenticação através de selfie é disponibilizada para os parceiros que utilizam os serviços de nalise de crédito QI Tech, onde a autenticação através de selfie é validada e um ID de comprovação é gerado.

Este ID gerado através dos endpoints de anaise de crédito QI Tech podem ultilizados como assinatura do contrato.

## Request

ENDPOINT /debt/ DEBT-KEY /signed
MÉTODO POST

**Request Body**

```json
{
    "type": "data-signature",
    "signatures": [
        {
            "signed_object": {
                "raw_text": "Lorem ipsum dolor sit amet, consectetur a....",
                "document_key": "79003de0-2590-455d-9b73-426b8ca284eb",
                "document_md5": "7521bd5621d97af26b2c1721fc4023a8"
            },
            "authenticity": {
                "timestamp": "1970-01-01 00:00:01",
                "facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb"
            },
            "signer": {
                "name": "IVANILDO DE SENA LIMA",
                "email": "ivanlima2604@gmail.com",
                "phone": {
                    "country_code": "055",
                    "area_code": "11",
                    "number": "999999999"
                },
                "document_number": "61766976204"
            },
            "authentication_type": "opt-in"
        }
    ]
}
```

## Path Params

| Campo |  Tipo | Descrição | Caracteres | 
|---|---|---|---|
| `debt_key` * | string |  Chave da divida devolvida no momento da criação da operação de crédito. | - |

## Body Params

| Campo |  Tipo | Descrição | Caracteres | 
|---|---|---|---|
| `type` * | string |  Tipo de assinatura que será enviada. | - |
| `signatures` * | array of objects | Lista contendo objetos de comprovação de assinatura - deve ser enviado no caso de assinatura "type": "data-signature". |  **[Objetos signatures](#objeto-signatures )**|

### Objeto signatures

| Campo |  Tipo | Descrição | Caracteres | 
|---|---|---|---|
| `signed_object` | object | Objeto contendo o documento que esta sendo assinado. | **[Objetos signed_object](#objeto-signed_object )** |
| `authenticity` | object | objeto com dados de autenticação. | **[Objetos authenticity](#objeto-authenticity )** |
| `signer` | object | Objeto com os dados do signatário. | **[Objeto signer](#objeto-signer )** |
| `authentication_type` *| string | Tipo de assinatura. | - |

### Objeto signed_object

| Campo |  Tipo | Descrição | Caracteres | 
|---|---|---|---|
| `raw_text` | string | Texto corrido com os dados do contrato que será assinado (Obrigatório para autenticação tipo opt-in). | - |
| `document_key` | string | DOCUMENT_KEY do arquivo assinado enviado a partir da API 1.1 (obrigatório apenas caso o campo "raw_text" não seja enviado). | - |
| `document_md5` | string | DOCUMENT_MD5 do arquivo assinado enviado a partir da API 1.1 (obrigatório apenas caso o campo "raw_text" não seja enviado). | - |

### Objeto authenticity

| Campo |  Tipo | Descrição | Caracteres | 
|---|---|---|---|
| `timestamp` *| string | Data da assinatura. | - |
| `facial_recognition_key` * | string | Deve conter o facial_recognition_key devolvido pela API de face recognition QI Tech - Este campo só é disponível para o authentication_type "selfie" e exclui a obrigatoriedade do envio de outras comprovações. | - |
 
### Objeto signer

| Campo |  Tipo | Descrição | Caracteres | 
|---|---|---|---|
| `name` *| string | Nome do signatário. | - |
| `email` *| string | E-mail do signatário. | - |
| `phone` | string | Objeto de telefone do signatário. |  **[Objeto phone](#objeto-phone)** |
| `document_number` *| string | Numero de documento do signatário. | - |

### Objeto phone

| Campo |  Tipo | Descrição | Caracteres | 
|---|---|---|---|
|`country_code` *| string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 | 
| `area_code` *| string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |Número de telefone (apenas números) |  10 |

## Response

STATUS 200

**Response Body**

```json
{
  "data": {},
  "event_datetime": "2022-11-07 15:24:47",
  "key": "\<DEBT-KEY\>",
  "status": "signature_received",
  "webhook_type": "debt"
}

```

STATUS 400

**Response Body**

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

---

# Assinatura de contrato

URL: /documentation/emissao_de_divida/formalizacao/introducao_formalizacao

Por padrão a QI Tech realiza a coleta de assinaturas através da QI Sign e o contrato é enviado para os assinantes no momento da emissão, porém ainda existe a possibilidade de o parceiro realizar a coleta de assinaturas de forma independente e enviar o documento assinado ou as evidencias de assinatura para a QI Tech para seguir com a operação.

:::caution **Atenção**

Para que essa coleta seja realizada pelo parceiro e depois o documento assinado seja enviado através de API é necessário solicitar a configuração desse fluxo para o time de suporte QI Tech.
:::

O processo de assinatura pode ser feito de 2 formas:

1 - A coleta de assinaturas é realizada através da plataforma QI Tech;

2 - O parceiro realiza a coleta de assinaturas de forma independente e depois envia o contrato assinado para a QI Tech - Essa possibilidade contempla tanto o envio do PDF assinado quanto o envio de um hash de assinatura;

O fluxo de chamadas muda de acordo com o processo escolhido, podendo seguis as esteiras de chamadas abaixo:

## Fluxo 1
Após solicitar a configuração de fluxo 1 de assinatura para o time de suporte QI Tech, a única chamada necessária para realizar a emissão da divida é a chamada do conjunto 3 de acordo com o tomador de crédito da operação.

A QI tech por sua vez fará a emissão do contrato de crédito pré-configurado e o disparo para assinatura - o acompanhamento da operação poderá ser realizado através da API 5.1 ou através dos callbacks enviados.

A assinatura do documento é através da plataforma QI Sign e pode ocorrer via email, whatsapp ou sms no período de 7 dias após o momento da emissão do contrato.

Por conta da assincronia da assinatura, quando o contrato é assinado pelo tomador, um evento é disparado via webhook ao originador.

## Fluxo 2
Após solicitar a configuração de fluxo 2 de assinatura para o time de suporte QI Tech, existe um fluxo de chamadas que deve ser realizado.

A primeira chamada será obrigatoriamente do conjunto de APIs 3 (de acordo com o tomador de crédito da operação) para realizar a emissão do PDF do contrato e a ultima chamada será a API 4.1 para realizar o envio do contrato já assinado;

No caso da assinatura do documento ser via certificadora, é necessário realizar o envio da url com o PDF assinado na API 4.1;

No caso de assinatura via optin no front, as informações que serão enviadas na API 4.1 serão as evidencias de aceite do cliente.

A QI tech por sua vez seguira o fluxo para o desembolso - o acompanhamento da operação poderá ser realizado através da API 5.1 ou através dos webhooks enviados.

## Tipos de assinatura aceitos

### **pdf-signature**
Esse tipo indica que o PDF emitido através da "/debt" será assinado e link com o PDF assinado será enviado através da API 4.1 como forma de autenticação.

### **data-signature**
Esse tipo indica que o PDF emitido através da "/debt" será assinado através de um hash anexado em sua ultima pagina.

A autenticação através de dados pode ter 3 tipos:

#### **Opt-in**
A assinatura através de opt-in significa que o cliente vai dar o aceite do contrato através do front.

Para que essa assinatura seja valida, alguns dados devem ser enviados obrigatoriamente.

#### **Zip**
A assinatura através de zip contempla o envio de um arquivo de comprovação, como uma ligação gravada.

#### **Selfie**
A autenticação através de selfie é disponibilizada para os parceiros que utilizam os serviços de CaaS QI Tech, onde a autenticação através de selfie é validada e um id de comprovação é gerado.

---

# Gerar Boleto ou PIX para uma Parcela

URL: /documentation/emissao_de_divida/gerar_boleto_ou_pix_para_uma_parcela

Permite gerar um boleto bancário ou código PIX para o pagamento de uma parcela específica de uma operação de crédito.

:::caution Substituição de meio de pagamento 
Caso a parcela ja possua um boleto/pix ativo para pagamento o mesmo será desativado e substituido pelo novo método de pagamento.
:::

## Endpoint

### Request

ENDPOINT /debt/ DEBT-KEY /installment/ INSTALLMENT-KEY / PAYMENT-TYPE
MÉTODO POST
Parâmetros de Caminho
| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| DEBT-KEY | string | Chave identificadora da dívida |
| INSTALLMENT-KEY | string | Chave identificadora da parcela |
| PAYMENT-TYPE | string | Tipo de pagamento desejado bankslip (boleto) ou pix (qrcode pix) |
Request Body
```json
{}
```
Response
Response Body
```json
{
  "installment_key": "installment_key",
  "due_date": "2022-09-08",
  "business_due_date": "2022-09-09",
  "pre_fixed_amount": 70.0,
  "principal_amortization_amount": 1000.0,
  "total_amount": 1070.0,
  "bank_slip_key": "bank_slip_key",
  "qr_code_key": "qr_code_key",
  "qr_code_url": "qr_code_url",
  "digitable_line": "digitable_line"
}
```
Objeto Response Body
| Campo | Tipo | Descrição |
|-------|------|-----------|
| installment_key | string | Identificador único da parcela no formato UUID |
| due_date | string | Data de vencimento da parcela no formato YYYY-MM-DD |
| business_due_date | string | Data de vencimento da parcela em dia útil no formato YYYY-MM-DD |
| pre_fixed_amount | number | Valor dos juros |
| principal_amortization_amount | number | Valor do principal a ser amortizado |
| total_amount | number | Valor total da parcela (juros + principal) |
| bank_slip_key | string | Chave identificadora do boleto bancário |
| qr_code_key | string | Chave identificadora do QR code PIX |
| qr_code_url | string | URL para pagamento do QR code PIX |
| digitable_line | string | Linha digitável do boleto bancário |

---

# Introdução

URL: /documentation/emissao_de_divida/introducao

Nesta seção você aprenderá quais os passos necessários para emissão, formalização, desembolso e cancelamento de um contrato de crédito.

## 1. Envio dos documentos necessários para a emissão da dívida

Para realizar a emissão de uma dívida, existem certos critérios regulatórios que devem ser atendidos. Dentre estes critérios, está a identificação do devedor por parte da instituição financeira emissora do crédito. Para cumprimento deste critério, se faz necessário, no mínimo, o envio dos seguintes documentos:

- **Devedor Pessoa Física**: Documento oficial com foto (RG ou CNH);
- **Devedor Pessoa Jurídica**: Contrato/Estatuto Social, Ata de Eleição (no caso de S.A.'s), Documento oficial com foto dos representantes e Procuração (caso existam procuradores);

Para realizar o envio desta documentação vocês devem utilizar nosso [endpoint de upload de documentos](../upload_de_documentos).

:::danger Atenção!

A QI Tech oferece uma solução de Onboarding, OCR para validação de documentos e Anti-fraude.

[Confira aqui a documentação das APIs deste serviço.](/documentation/caas/onboarding/natural_person)

Para receber uma cotação consulte nosso time comercial:

comercial@qitech.com.br ou (11) 2339-4763
:::

## 2. Simulação da dívida

Na QI Tech disponibilizamos aos nossos clientes a possibilidade de [simular os valores uma operação de crédito](simulacao_de_divida_novo) antes da sua emissão de fato. A simulação segue o mesmo padrão da solicitação de emissão de dívida, porém não é necessário informar os dados cadastrais e de conta de desembolso do devedor. Além disso, oferecemos a possibilidade de efetuar diversas simulações com uma única request.

## 3. Emissão da dívida
Com a minuta da operação de crédito definida, o time de suporte QI Tech realizará a parametrização do contrato na plataforma e seu PDF poderá ser emitido através do endpoint de emissão de dívida, conforme os casos abaixo:
- [Para emissão de uma dívida para uma pessoa física.](emissao/emissao_de_divida_pf)
- [Para emissão de uma dívida para uma pessoa jurídica.](emissao/emissao_de_divida_pj)

## 4. Realização da assinatura do contrato de crédito
O Processo de assinatura pode variar de acordo com o produto que será disponibilizado.
Para entender as configurações de assinatura [clique aqui](formalizacao/introducao_formalizacao).

## 5. Desembolso do crédito ao devedor
O desembolso é automático e pode ser configurado de duas formas.
Para entender as configurações de desembolso [clique aqui](emissao/exemplo_payloads_desembolso).

---
## Processo de cessão
Após realizados todos estes passos, passamos para o processo de cessão da dívida que é 100% pilotado pela QI Tech.

Para mais detalhes sobre o desembolso, [clique aqui](desembolso_da_operacao).

---

# Monitoramento do correspondente bancário

URL: /documentation/emissao_de_divida/mcb

## 1. Consultar Agente de crédito: 

### Request

ENDPOINT /mcb/credit_agent/[CPF-DO-AGENTE]
MÉTODO GET

#### QUERY PARAMETERS

| Enumerador                   | Descrição                                                        |
|------------------------------|------------------------------------------------------------------|
| **include_history**          |  Parâmetro necessário para retornar o histórico de pontuação do agente na consulta  |

### Response

ENDPOINT /mcb/credit_agent/[CPF-DO-AGENTE]
MÉTODO GET
HTTP STATUS 200

Response Body

```json
{
    "document_number": "02353050069",
    "credit_agent_status": "blocked",
    "block_reason": "limit_score_reached",
    "credit_agent_history": [
        {
            "credit_agent_status": "active",
            "block_reason": null,
            "current_score": 0,
            "total_score": 0,
            "score_expiration_date": null,
            "suspension_start_date": null,
            "suspension_end_date": null,
            "reference_date": "2025-06-26"
        },
        {
            "credit_agent_status": "blocked",
            "block_reason": "limit_score_reached",
            "current_score": 22,
            "total_score": 22,
            "score_expiration_date": null,
            "suspension_start_date": "2025-08-26",
            "suspension_end_date": null,
            "reference_date": "2025-08-26"
        }
    ]
}
```

### Response body details

| Campo | Tipo | Descrição |
|---| ---| ---|
| `document_number` | string | CPF do agente de crédito.|
| `credit_agent_status` | string | Status do agente de crédito.|
| `block_reason` | string | Motivo de bloqueio do agente de crédito.|
| `current_score` | number | Pontuação atual do agente.|
| `total_score` | number | Pontuação acumulada do agente.|
| `score_expiration_date` | string | Data de expiração da pontuação do agente.|
| `suspension_start_date` | string | Data de início da suspensão do agente.|
| `suspension_end_date` | string | Data de fim da suspensão do agente.|
| `credit_agent_history` | list | Histórico de atualizações do agente.|
| `reference_date` | string | Data de referencia da atualização.|

#### Enumeradores credit_agent_status

| Enumerador                   | Descrição                                            |
|------------------------------|------------------------------------------------------|
| **active**                   | Agente está ativo                                    |
| **blocked**                  | Agente está bloqueado para originar operação         |

#### Enumeradores block_reason

| Enumerador                   | Descrição                                            |
|------------------------------|------------------------------------------------------|
| **limit_score_reached**          | Limite de pontuação atingido informado pela núclea. |
| **expired_certificate**      | Bloqueio devido a certificação expirada.              |
| **rdr_identity_fraud**       | Bloqueio devido a fraude de identidade identificada no sistema de reclamações RDR.          |
| **fraud_report**             | Bloqueio por receber denúncia de fraude por mais de 2 instituições financeiras no MCB.          |
| **operation_irregularity**   | Bloqueio devido a irregularidade de operação         |
| **other**                    | Outros motivos de bloqueio                           |

## 2. Consultar certificação do agente de crédito no CRCP: 

### Request

ENDPOINT /mcb/credit_agent/[CPF-DO-AGENTE]/certificate
MÉTODO GET

STATUS 200

Response Body

```json
{
    "document_number": "12345678911",
    "name": "NOME DO AGENTE DE CREDITO",
    "certificate_list": [
        {
            "certifier_name": "FEBRABAN",
            "certifier_code": "6345",
            "title": "LGPD para Correspondentes no Pais Res 4 935",
            "certificate_number": "1234567891234567",
            "exam_date": "11/01/2022",
            "expiration_date": "11/01/2024",
            "certificate_status": "excluded"
        },
        {
            "certifier_name": "FEBRABAN",
            "certifier_code": "6339",
            "title": "PLDFT em Conta Corrente Poupanca para Correspondente",
            "certificate_number": "1234567891234567",
            "exam_date": "28/12/2023",
            "expiration_date": "28/12/2025",
            "certificate_status": "active"
        },
    ]
}
```

STATUS 404

Response Body

```json
{
	"title": "Not Found",
	"description": "Credit agent not found.",
	"translation": "Agente de crédito não encontrado.",
	"code": "MCB000004"
}
```

### Response body details

| Campo | Tipo | Descrição |
|---| ---| ---|
| `document_number` | string | CPF do agente de crédito.|
| `name` | string | Nome do agente certificado.|
| `certificate_list` | list | Lista de certificados vinculados ao agente de credito.|
| `certifier_name` | string | Nome da empresa certificadora.|
| `certifier_code` | string | Código do tipo do certificado .|
| `title` | string | Titulo do certificado.|
| `certificate_number` | string | Número do certificado.|
| `exam_date` | string | Data do exame da certificação.|
| `expiration_date` | string | Data de expiração do certificado.|
| `certificate_status` | string | Status do certificado na data da consulta.|

#### Enumeradores certificate_status

| Enumerador                   | Descrição                                            |
|------------------------------|------------------------------------------------------|
| **active**                   | Certificado está ativo                               |
| **excluded**                 | Certificado foi excluido pela certificadora          |

---

# Metadata

URL: /documentation/emissao_de_divida/metadata

Objeto que permite a consulta de operações de crédito através de chaves e valores personalizados.

## 1. Criar Metadata

### Objeto Request Body
| Campo                           | Tipo   | Descrição                                                                                                                                                                                                        | Máx. Caract. | 
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **metadata_key** * | string | Chave metadata                                                                                                                                                          | 100            |
| **metadata_value** * | string | Valor metadata    | 100            |

### Request

ENDPOINT /credit_operation/[CREDIT-OPERATION-KEY]/metadata
MÉTODO POST

Request Body

```json
{
    "metadata_key": "key",
    "metadata_value": "value"
}
```

## 2. Remover Metadata

### Request

ENDPOINT /credit_operation/[CREDIT-OPERATION-KEY]/metadata
MÉTODO DELETE

Request Body

```json
{
    "metadata_key": "key",
    "metadata_value": "value"
  }
```

## 3. Consulta de operação de crédito utilizando Metadata

:::caution 
Na consulta por metadata, os dois campos 'metadata_key' e 'metadata_value' devem ser informados.
:::

### Request

ENDPOINT /credit_operations
MÉTODO GET
<div className='badge
badge--primary'>PARAMETERS page, page_size, metadata_key, metadata_value, credit_operation_status

### Response

Response Body
```json
{
    "data": [
        {
            "credit_operation_key": "cc217253-e89f-4d14-bf89-fb29afaa2895",
            "contract_number": "0000000007/WO",
            "credit_operation_status": "waiting_signature",
            "additional_iof": 3.817322,
            "total_iof": 7.19,
            "original_total_iof": 7.2,
            "attached_documents": [
                {
                    "document_key": "2f7bfc50-d7c0-4d4e-a5ce-d8bba2aeb348",
                    "document_url": "https://storage.googleapis.com/dev-doc-api/documents/2f7bfc50-d7c0-4d4e-a5ce-d8bba2aeb348/sample.pdf",
                    "signature_url": null,
                    "document_type": "document_identification",
                    "signature_required": false,
                    "signed": false
                },
                {
                    "document_key": "568ca6b7-45a8-42e5-a383-e93641625040",
                    "document_url": "b",
                    "signature_url": null,
                    "document_type": "ccb_pre_price",
                    "signature_required": true,
                    "signed": false
                }
            ],
            "annual_cet": 316.4973,
            "assigned": false,
            "assigned_at": null,
            "assignment_amount": 1007.19,
            "issue_amount": 1007.19,
            "disbursed_issue_amount": 1000,
            "final_disbursement_amount": 1000,
            "base_iof": 3.37226774,
            "calculus_correction": null,
            "central_depository": null,
            "cet": 12.62,
            "collateral_constituted": true,
            "collateral_type": null,
            "contract_fee_amount": 0,
            "external_contract_fee_amount": 0,
            "credit_operation_type": "ccb",
            "operation_type": "structured_operation",
            "creditor_bank_account_key": null,
            "custodian": "qi_scd",
            "disbursement_date": "2022-08-08",
            "disbursement_start_date": "2022-08-08",
            "disbursement_end_date": "2022-08-08",
            "first_due_date": "2022-08-18",
            "disbursement_accounts": [
                {
                    "account_branch": "0001",
                    "account_digit": "3",
                    "account_number": "94134",
                    "account_type": null,
                    "disbursement_type": "pix",
                    "amount_receivable": null,
                    "digitable_line": null,
                    "financial_institutions_code_number": 329,
                    "ispb": "32402502",
                    "name": "Teste",
                    "percentage_receivable": 100,
                    "pix_key": "qitech@qitech.com.br",
                    "pix_transfer_key": "0956cf37-5ef6-4a63-9c01-f29b259e1993",
                    "pix_type": "key",
                    "qr_code_key": null
                }
            ],
            "document_certifier": "clicksign",
            "number_of_installments": 3,
            "installments": [
                {
                    "accrual_reference_date": null,
                    "advanced_paid_amount": 0,
                    "bank_slip_key": null,
                    "business_due_date": "2022-08-19",
                    "due_date": "2022-08-18",
                    "calendar_days": 10,
                    "digitable_line": null,
                    "due_interest": 0,
                    "due_principal": 1007.19,
                    "fine_amount": null,
                    "has_interest": true,
                    "installment_key": "5f45b7b4-f7f0-464b-94a7-cdea47f3811b",
                    "installment_status": "created",
                    "installment_type": "principal",
                    "original_due_principal": 1007.19,
                    "original_pre_fixed_amount": 38.24205854,
                    "original_principal_amortization_amount": 351.17794146,
                    "paid_amount": 0,
                    "post_fixed_amount": 0,
                    "original_total_amount": 389.42,
                    "pre_fixed_amount": 38.24205854,
                    "principal_amortization_amount": 351.17794146,
                    "qr_code_key": null,
                    "qr_code_url": null,
                    "renegotiation_proposal_key": null,
                    "tax_amount": 0.28796591,
                    "total_accrual_amount": null,
                    "total_amount": 389.42,
                    "total_paid_amount": 0,
                    "workdays": 8
                },
                {
                    "accrual_reference_date": null,
                    "advanced_paid_amount": 0,
                    "bank_slip_key": null,
                    "business_due_date": "2022-09-20",
                    "due_date": "2022-09-19",
                    "calendar_days": 32,
                    "digitable_line": null,
                    "due_interest": 0,
                    "due_principal": 656.01205854,
                    "fine_amount": null,
                    "has_interest": true,
                    "installment_key": "f844a3ea-bde3-4f94-ada1-607e799b9095",
                    "installment_status": "created",
                    "installment_type": "principal",
                    "original_due_principal": 656.01205854,
                    "original_pre_fixed_amount": 80.33658151,
                    "original_principal_amortization_amount": 309.08341849,
                    "paid_amount": 0,
                    "post_fixed_amount": 0,
                    "original_total_amount": 389.42,
                    "pre_fixed_amount": 80.33658151,
                    "principal_amortization_amount": 309.08341849,
                    "qr_code_key": null,
                    "qr_code_url": null,
                    "renegotiation_proposal_key": null,
                    "tax_amount": 1.06448329,
                    "total_accrual_amount": null,
                    "total_amount": 389.42,
                    "total_paid_amount": 0,
                    "workdays": 21
                },
                {
                    "accrual_reference_date": null,
                    "advanced_paid_amount": 0,
                    "bank_slip_key": null,
                    "business_due_date": "2022-10-19",
                    "due_date": "2022-10-18",
                    "calendar_days": 29,
                    "digitable_line": null,
                    "due_interest": 0,
                    "due_principal": 346.92864005,
                    "fine_amount": null,
                    "has_interest": true,
                    "installment_key": "e6d67f54-8827-40c4-ade0-1b9b8fd03689",
                    "installment_status": "created",
                    "installment_type": "principal",
                    "original_due_principal": 346.92864005,
                    "original_pre_fixed_amount": 42.49135995,
                    "original_principal_amortization_amount": 346.92864005,
                    "paid_amount": 0,
                    "post_fixed_amount": 0,
                    "original_total_amount": 389.42,
                    "pre_fixed_amount": 42.49135995,
                    "principal_amortization_amount": 346.92864005,
                    "qr_code_key": null,
                    "qr_code_url": null,
                    "renegotiation_proposal_key": null,
                    "tax_amount": 2.01981854,
                    "total_accrual_amount": null,
                    "total_amount": 389.42,
                    "total_paid_amount": 0,
                    "workdays": 20
                }
            ],
            "interest_grace_period": 0,
            "interest_payment_month_period": 1,
            "interest_subsidy_amount": 0,
            "interest_subsidy_percentage": 0,
            "interest_type": "pre_price",
            "iof_charge_method": "financed",
            "ipoc_code": "3240250202021371976458320000000007/WO",
            "issue_date": "2022-08-08",
            "issuer_document_number": "37197645832",
            "issuer_name": "Wilker Oliveira\u00e7o",
            "modality": "0202",
            "origin_key": "52539e23-5c01-4b9c-8a68-6ed750ec7bc5",
            "payment_and_settlement_agent": "qi_scd",
            "post_fixed_interest_rate": null,
            "prefixed_interest_rate": {
                "annual_rate": 3,
                "daily_rate": 0.00385824,
                "monthly_rate": 0.12246205,
                "interest_base": "calendar_days"
            },
            "fine_configuration": {
                "contract_fine_rate": 0.02,
                "fine_delay_rate": {
                    "annual_rate": 0.12682503,
                    "daily_rate": 0.00033173,
                    "interest_base": "calendar_days",
                    "monthly_rate": 0.01
                }
            },
            "principal_amortization_month_period": 1,
            "principal_grace_period": 0,
            "purchaser_document_number": "04113929151550",
            "requester_key": "52f36417-368e-4f5b-8841-71e3b9caa72f",
            "requester_identifier_key": null,
            "settlement_bank_account_key": "e7e60779-6605-4af5-bd00-1f465f2c5da5",
            "share_quantity": 2,
            "tax_configuration": {
                "iof_additional_rate": 0.000082,
                "iof_rate": 0.0038
            },
            "third_party_account_key": "96015228-4905-42fc-bda6-e70e0e552b6b",
            "disbursement_options": [
                {
                    "additional_iof": 3.817322,
                    "annual_cet": 316.4973,
                    "assignment_amount": 1007.19,
                    "base_iof": 3.37226774,
                    "calculus_correction": null,
                    "cet": 12.62,
                    "contract_fee_amount": 0,
                    "disbursed_issue_amount": 1000,
                    "disbursement_date": "2022-08-08",
                    "external_contract_fee_amount": 0,
                    "first_due_date": "2022-08-18",
                    "installments": [
                        {
                            "business_due_date": "2022-08-19",
                            "due_date": "2022-08-18",
                            "calendar_days": 10,
                            "due_interest": 0,
                            "due_principal": 1007.19,
                            "fine_amount": null,
                            "has_interest": true,
                            "post_fixed_amount": 0,
                            "pre_fixed_amount": 38.24205854,
                            "principal_amortization_amount": 351.17794146,
                            "tax_amount": 0.28796591,
                            "total_amount": 389.42,
                            "workdays": 8
                        },
                        {
                            "business_due_date": "2022-09-20",
                            "due_date": "2022-09-19",
                            "calendar_days": 32,
                            "due_interest": 0,
                            "due_principal": 656.01205854,
                            "fine_amount": null,
                            "has_interest": true,
                            "post_fixed_amount": 0,
                            "pre_fixed_amount": 80.33658151,
                            "principal_amortization_amount": 309.08341849,
                            "tax_amount": 1.06448329,
                            "total_amount": 389.42,
                            "workdays": 21
                        },
                        {
                            "business_due_date": "2022-10-19",
                            "due_date": "2022-10-18",
                            "calendar_days": 29,
                            "due_interest": 0,
                            "due_principal": 346.92864005,
                            "fine_amount": null,
                            "has_interest": true,
                            "post_fixed_amount": 0,
                            "pre_fixed_amount": 42.49135995,
                            "principal_amortization_amount": 346.92864005,
                            "tax_amount": 2.01981854,
                            "total_amount": 389.42,
                            "workdays": 20
                        }
                    ],
                    "interest_subsidy_amount": 0,
                    "issue_amount": 1007.19,
                    "net_external_contract_fee_amount": 0,
                    "share_quantity": 2,
                    "total_iof": 2,
                    "prefixed_interest_rate": {
                        "annual_rate": 3,
                        "daily_rate": 0.00385824,
                        "monthly_rate": 0.12246205,
                        "interest_base": "calendar_days"
                    }
                }
            ],
            "related_parties": [
                {
                    "company_document_number": null,
                    "email": "teste.teste@yopmail.com",
                    "foundation_date": null,
                    "gender": "male",
                    "individual_document_number": "61592798071",
                    "is_pep": null,
                    "marital_status": null,
                    "mother_name": null,
                    "nationality": null,
                    "person_type": "natural",
                    "related_party_key": "16e3b6a8-bec0-4bd2-8b23-caaad54afd8c",
                    "role_type": "issuer",
                    "trading_name": null,
                    "simples_nacional_participant": null,
                    "spouse_document_number": null,
                    "profession": null,
                    "address": {
                        "city": "Bauru",
                        "complement": null,
                        "neighborhood": "Centro",
                        "number": "343",
                        "postal_code": "17057770",
                        "state": "SP",
                        "street": "Av Um"
                    },
                    "phone": {
                        "area_code": "14",
                        "country_code": "055",
                        "number": "936180266"
                    },
                    "attached_documents": [
                        {
                            "document_key": "2f7bfc50-d7c0-4d4e-a5ce-d8bba2aeb348",
                            "document_url": "https://storage.googleapis.com/dev-doc-api/documents/2f7bfc50-d7c0-4d4e-a5ce-d8bba2aeb348/sample.pdf",
                            "signature_url": null,
                            "document_type": "document_identification",
                            "signature_required": false,
                            "signed": false
                        }
                    ]
                }
            ]
        }
    ],
    "pagination": {
        "current_page": 1,
        "next_page": 2,
        "rows_per_page": 10,
        "total_pages": 1,
        "total_rows": 1,
        "contain_last_page": true
    }
}

```

---

# Não me perturbe

URL: /documentation/emissao_de_divida/nao_me_perturbe

O "Não Me Perturbe" é uma plataforma criada pelas operadoras de telecomunicações que permite aos consumidores registrarem seus números de telefone para não receberem chamadas de telemarketing. No contexto do crédito consignado, sua utilização foi incorporada como uma das diretrizes da Autoregulação do Crédito Consignado, promovida por entidades como a Febraban, ABBC e CNF, com o objetivo de aumentar a proteção do consumidor e coibir práticas abusivas na oferta de crédito.

Como instituição financeira aderente ao "Não Me Perturbe", implementamos um mecanismo de verificação prévia para garantir que não sejam realizadas ligações ativas para números de telefone cadastrados na lista de bloqueio. Por meio desta API, é possível consultar se um número específico está inscrito na base do "Não Me Perturbe" antes de iniciar qualquer tentativa de contato com o tomador de crédito.

Essa checagem é essencial para assegurar o cumprimento das boas práticas de conduta comercial e o respeito à privacidade dos consumidores.

:::caution Atenção
É necessário realizar a consulta antes de realizar a ligação com o tomador.
:::

## Como usar

Para realizar a consulta, é necessário enviar o número de telefone do tomador para o endpoint abaixo.

ENDPOINT /do_not_disturb?phone_number=11999999999
MÉTODO GET

:::caution Atenção
O número de telefone deve ser enviado no formato DDD + Número, por exemplo: 11999999999.
:::

### Response

STATUS 200 - Número encontrado na lista do "Não me perturbe"

Response Body

```json
{
  "phone_number": 11999999999,
  "deleted_at": "2026-06-07T14:30:00Z"
}
```

STATUS 404 - Número não encontrado na lista do "Não me perturbe"

:::caution Atenção
Caso o número seja encontrado na lista do "Não me perturbe", a ligação não deverá ser realizada.
:::

---

# Introdução

URL: /documentation/emissao_de_divida/reapresentacao_de_conta_bancaria

Esta página vai auxiliar a reapresentar dados bancários após um erro no desembolso

### 1 - Atualização de conta bancária

Primeiro você deve atualizar os dados da conta bancária do tomador

#### Request

ENDPOINT /debt/DEBT/disbursement_bank_accounts
MÉTODO PUT

Request Body

**Usando dados bancários**

```json
{
	"disbursement_bank_accounts": [{
			"document_number": "31233261000185",
			"name": "Jorge Augusto Salgado Salhani",
			"pix_transfer_type": "manual",
			"bank_code": "329",
			"branch_number": "0001",
			"account_number": "62400",
			"account_digit": "6",
			"percentage_receivable": 100
		}]
}
```

**Usando chave pix**

```json
{
	"disbursement_bank_accounts": [{
			"document_number": "31233261000185",
			"name": "Jorge Augusto Salgado Salhani",
			"pix_key": "2f205c99-3161-4120-badd-854039d12de6",
			"pix_transfer_type": "key"
		}]
}
```

### 2 - Atualização da data de desembolso

Após, você deve atualizar as datas de desembolso

#### Request

ENDPOINT /debt/DEBT/disbursement_option
MÉTODO PATCH

Request Body

**Atualização de data de desembolso**

```json
{
    "disbursement_date": "2025-11-28",
    "status": "active"
}
```

---

# Reenviar documentos das partes relacionadas ao contrato de crédito

URL: /documentation/emissao_de_divida/reenviar_documentos_das_partes_relacionadas

## Request

ENDPOINT /debt/ DEBT-KEY /related_party/ RELATED-PARTY-KEY /attached_document
MÉTODO POST

**Request Body**

```json
{
    "document_identification": "2893fc74-88fd-4cc9-a5c6-8a63d9d00f41",
    "document_identification_back": "e881ddf4-bc9a-48e0-9555-cac979f65431",
    "wedding_certificate": "955a0e36-1abd-4efd-868a-f0b3d53bc585",
    "proof_of_residence": "ea5f7b08-77fd-4adb-8bf5-f86379c28ee3",
    "company_statute": "150292ad-be66-4ba0-a306-0ceda20616f0",
    "directors_election_minute": "ca37979e-6f11-4465-bf3b-69cd8307549c",
    "insurance_agreement":"4be38197-e8a9-4c96-882d-99e38a7199a7",
    "loan_agreement_evidence": "494598fd-c226-4332-a500-591ae3684673"
}

```

### Path Params

| Campo | Tipo | Descrição |
|---|---|---|
| `debt_key` * | string | debt_key da operação. |
| `related_party_key` * | string |  key da parte relacionada que os documentos serão enviados. |

### Body Params

| Campo | Tipo | Descrição | Caracteres | 
|---|---| ---| ---|
| `document_identification` | string | Frente do RG ou CNH para person_type "natural". | chave uuid | 
| `document_identification_back` | string | Verso do RG ou CNH para person_type "natural". | chave uuid | 
| `wedding_certificate` | string |Certidão de casamento para person_type "natural". | chave uuid | 
| `proof_of_residence` | string | Comprovante de residência para person_type "natural". | chave uuid | 
| `company_statute` | string | Estatuto social para person_type "legal". | chave uuid | 
| `insurance_agreement` | string | Evidência da contratação de seguro para a operação de crédito | chave uuid | 
| `loan_agreement_evidence` | string | Evidência do contrato de empréstimo. | chave uui

## Response

STATUS 201

**Response Body**

```json
"
{}
"
```

STATUS 400

**Response Body**

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

---

# Ações pós-desembolso

URL: /documentation/emissao_de_divida/reprocessar_acao_pos_desembolso

## 1. Webhooks de sucesso ou falha na execução de uma ação pós desembolso

:::info Aviso
A *action_key* é a chave identificadora de uma ação pós desembolso.

:::

### Sucesso

WEBHOOK_TYPE debt_actions
STATUS success

**Boleto**

```json title='Webhook Body'
{
    "key": "19dee101-a781-4308-b7d1-f4426c2df111",
    "data": [
        {
            "status": "done",
            "action_key": "02f6392b-65d3-4f3e-ae91-cd5b371c7111",
            "action_data": {
                "digitable_line": "11193708089000014656468000284304297860007686111"
            },
            "action_type": "bankslip_payment",
            "action_error": null,
            "execution_data": {
                "bank_slip": {
                    "payer": {
                        "name": "PAGADOR",
                        "document_number": "33128940002",
                        "document_number_formatted": "331.289.400-02"
                    },
                    "beneficiary": {
                        "name": "TESTES FINANCIAMENTO",
                        "document_number": "16832953000156",
                        "document_number_formatted": "16.832.953/0001-56"
                    },
                    "payment_key": "318aa3a0-01ca-41ac-9e0f-23c24bc67fc9",
                    "payment_date": "2024-07-23",
                    "digitable_line": "11193708089000014656468000284304297860007686111",
                    "expiration_date": "2024-07-23",
                    "tax_collection_info": {},
                    "payment_date_formatted": "23/07/2024",
                    "expiration_date_formatted": "23/07/2024",
                    "financial_institution_name": "BCO BRADESCO S.A.",
                    "financial_institution_compe_number": "237"
                },
                "origin_key": "318aa3a0-01ca-41ac-9e0f-23c24bc67111",
                "transacted_at": "2024-07-23 21:31:09",
                "source_account": {
                    "owner_name": "PAGADOR",
                    "account_digit": "5",
                    "account_branch": "0001",
                    "account_number": "4588111",
                    "owner_document_number": "33128940002",
                    "financial_institution_name": "QI SCD S.A.",
                    "owner_document_number_formatted": "331.289.400-02",
                    "financial_institution_compe_number": 329
                },
                "source_subtype": "bank_slip_payment",
                "transaction_key": "a7af6954-3bc5-4f7e-a872-b4e47800d111",
                "transacted_at_br": "2024-07-23 18:31:09",
                "pdf_encoded_string": "BASE 64 DO PDF DO COMPROVANTE",
                "transaction_amount": 76862.27,
                "transacted_at_formatted": "23/07/2024, 21:31:09",
                "transacted_at_br_formatted": "23/07/2024, 18:31:09",
                "transaction_amount_formatted": "R$ 76.862,27",
                "source_subtype_translation_ptbr": "Pagamento de Boleto"
            }
        }
    ],
    "webhook_type": "debt_actions",
    "event_datetime": "2024-07-23 21:31:18"
}
```

**TED**

```json title='Webhook Body'
{
    "key": "25f14329-3734-40d8-bc5a-c5349b3cd111",
    "data": [
        {
            "status": "done",
            "action_key": "650e9041-65ec-4fd8-9b11-01e37316cf94",
            "action_data": {
                "qr_code": null,
                "destination": {
                    "name": "TOMAR DIVIDA",
                    "account_digit": "1",
                    "account_branch": "0001",
                    "account_number": "12214111",
                    "document_number": "61359908021",
                    "financial_institution_code_number": "380"
                },
                "digitable_line": null,
                "pix_transfer_type": null,
                "transaction_amount": 500
            },
            "action_type": "funds_transfer",
            "action_error": null,
            "execution_data": {
                "origin_key": "ec2112a3-9b75-4cf3-b18e-7af06857fdc5",
                "transacted_at": "2024-07-04 10:03:25",
                "source_account": {
                    "owner_name": "Conta de Origem",
                    "account_digit": "9",
                    "account_branch": "0001",
                    "account_number": "2845000",
                    "owner_document_number": "49783394487",
                    "financial_institution_name": "QI SCD S.A.",
                    "owner_document_number_formatted": "494.924.100-10",
                    "financial_institution_compe_number": 329
                },
                "source_subtype": "withdrawal",
                "target_account": {
                    "owner_name": "CONTA DESTINO",
                    "account_type": "checking_account",
                    "account_digit": "1",
                    "account_branch": "0001",
                    "account_number": "12214111",
                    "account_type_str": "Conta Corrente",
                    "owner_document_number": "61359908021",
                    "financial_institution_name": "PICPAY",
                    "owner_document_number_formatted": "613.599.080-21",
                    "financial_institution_compe_number": "380"
                },
                "transaction_key": "eeb35946-099f-4d40-8930-881aa3730d55",
                "transacted_at_br": "2024-07-04 07:03:25",
                "pdf_encoded_string": "BASE 64 DO PDF DO COMPROVANTE",
                "transaction_amount": 500,
                "transacted_at_formatted": "04/07/2024, 10:03:25",
                "transacted_at_br_formatted": "04/07/2024, 07:03:25",
                "transaction_amount_formatted": "R$ 500,00",
                "source_subtype_translation_ptbr": "Transferência"
            }
        }
    ],
    "webhook_type": "debt_actions",
    "event_datetime": "2024-07-04 10:03:33"
}
```

  

### Erro na ação pós-desembolso

Em caso de erro no pagamento da ação pós-desembolso, o parceiro será notificado através do seguinte webhook:

WEBHOOK_TYPE after_disbursement_action_update
STATUS error

**Boleto**

```json title='Webhook Body'
{
	"key": "e358e7e3-17b8-4aab-9da1-92f6b78dea00",
	"data": {
		"status": "error",
		"action_key": "e2495e5a-df32-4826-b6f0-419014d3c35a",
		"error_data": {
			"error_code": "QIT000007",
			"description": "Account blocked balance cannot be negative."
		},
		"action_data": {
            "digitable_line": "10495419967200010004900031456924592920008049295"
		},
		"action_type": "bankslip_payment",
		"execution_data": null
	},
	"webhook_type": "after_disbursement_action_update",
	"event_datetime": "2023-03-22 12:06:38"
}
```

**TED**

```json title='Webhook Body'
{
	"key": "e358e7e3-17b8-4aab-9da1-92f6b78dea00",
	"data": {
		"status": "error",
		"action_key": "e2495e5a-df32-4826-b6f0-419014d3c35a",
		"error_data": {
			"error_code": "QIT000007",
			"description": "Account blocked balance cannot be negative."
		},
		"action_data": {
			"destination": {
			    "name": "Nome Credor Original",
				"account_digit": "0",
				"account_branch": "0897",
				"account_number": "20001",
				"document_number": "87163234000138",
				"financial_institution_code_number": "341"
			},
			"transaction_amount": 1000
		},
		"action_type": "funds_transfer",
		"execution_data": null
	},
	"webhook_type": "after_disbursement_action_update",
	"event_datetime": "2023-03-22 12:06:38"
}
```

### Estorno da TED da ação pós-desembolso

Caso a TED realizada na ação pós-desembolso seja devolvida pela instituição financeira destinatária, o parceiro será notificado através do seguinte webhook:

WEBHOOK_TYPE after_disbursement_action_update
STATUS refused

```json title='Webhook Body'
{
	"key": "f4b5c36a-2aa1-4865-9678-e5a6fa585845",
	"data": {
		"status": "refused",
		"action_key": "cf3b8809-36dc-4574-8763-3600e413cf5c",
		"error_data": {
			"code": "agencia_conta_invalida",
			"description": "Agência ou Conta Destinatária do Crédito Inválida"
		},
		"action_data": {
			"destination": {
				"name": "SILVANA RAMOS DOS SANTOS",
				"account_digit": "1",
				"account_branch": "0150",
				"account_number": "301771620",
				"document_number": "30874011884",
				"financial_institution_code_number": "237"
			},
			"transaction_amount": 3200
		},
		"action_type": "funds_transfer",
		"action_amount": 3200.0
	},
	"webhook_type": "after_disbursement_action_update",
	"event_datetime": "2023-03-23 14:46:39"
}
```

## 2. Reprocessar ação pós desembolso alterando dados da ação

Caso ocorra um erro/estorno no pagamento da ação pós-desembolso, ela pode ser retentada através do seguinte endpoint

### Path Params

| Campo | Tipo | Descrição |
|---|---| ---|
| `action_key` * | string | Chave da ação devolvida no momento da criação da operação de crédito. | 

### Request

ENDPOINT /baas/action/ ACTION-KEY
MÉTODO PATCH

Request Body

**TED**

```json
{
    "destination": {
        "name": "Nome Credor Original",
        "account_digit": "0",
        "account_branch": "0897",
        "account_number": "20001",
        "document_number": "87163234000138",
        "financial_institution_code_number": "341"
    },
    "transaction_amount": 4736.07
}
```
  
  
**Linha digitável Boleto**

```json
{
    "digitable_line": "10495419967200010004900031456924592920008041111"
}
```

**Pix Copia e Cola**

```json
{
    "qr_code": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/66e9a02c1c304b1eacf7ba984eea19ce5204000053039865802BR5925BANKSOFTTECNOLOGIALTDA(EB6008SaoPaulo61080145200062070503***6304E27B",
    "pix_transfer_type": "qr_code",
    "transaction_amount": "299.00"
}
```

## 3. Reprocessar ação pós desembolso sem alteração de dados

### Request

ENDPOINT /baas/action/action_retry/ ACTION-KEY
MÉTODO PATCH

:::info Informação
As respostas dos dois endpoints são as mesmas
:::

### Response

STATUS 200

Response Body

```json
{
	"action_data": {
		"origin_key": "8b8742f0-0b7c-4939-bfcf-9bae8c60c088",
		"pdf_encoded_string": "\<BASE 64 DO PDF DO COMPROVANTE\>",
		"source_account": {
			"account_branch": "0001",
			"account_digit": "1",
			"account_number": "2788652",
			"financial_institution_compe_number": 329,
			"financial_institution_name": "QI SCD S.A.",
			"owner_document_number": "12345678911",
			"owner_document_number_formatted": "123.456.789-11",
			"owner_name": "Nome do titular da conta"
		},
		"source_subtype": "withdrawal",
		"source_subtype_translation_ptbr": "Transferência",
		"target_account": {
			"account_branch": "1012",
			"account_digit": "1",
			"account_number": "12345",
			"account_type": "checking_account",
			"account_type_str": "Conta Corrente",
			"financial_institution_compe_number": "341",
			"financial_institution_name": "ITAÚ UNIBANCO S.A.",
			"owner_document_number": "12345678911",
			"owner_document_number_formatted": "125.220.107-94",
			"owner_name": "Nome do titular da conta destino"
		},
		"transacted_at": "2023-03-14 17:57:20",
		"transacted_at_br": "2023-03-14 14:57:20",
		"transacted_at_br_formatted": "14/03/2023, 14:57:20",
		"transacted_at_formatted": "14/03/2023, 17:57:20",
		"transaction_amount": 2000,
		"transaction_amount_formatted": "R$ 2.000,00",
		"transaction_key": "ae139d20-396e-4c7e-a675-a8cb01160f5d"
	},
	"action_key": "fe3f251d-6b85-4d35-96dd-08fc37d09a82"
}
```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

STATUS 402

Response Body

```json
{
  "data": "{\"title\": \"Block Balance Error\", \"description\": \"Impossible to block an amount greater than account balance\", \"translation\": \"Não é possível blockear uma quantidade maior do que o saldo na conta\", \"extra_fields\": {}, \"code\": \"ACC000018\"}"
}

```

---

# Recalcular contrato de crédito

URL: /documentation/emissao_de_divida/reprocessar_contrato

Este endpoint pode ser utilizado para efetuar o recálculo de uma operação de crédito, através do ajuste do valor de parcela.

## Request

ENDPOINT /debt/ DEBT-KEY /recalculate_operation
MÉTODO POST

**Request Body**

```json
{
    "financial": {
        "installment_face_value": 250,
        "disbursement_date": "2025-01-20"
    }
}
```

### Path Params

| Campo | Tipo | Descrição |
|---|---| ---|
| `debt_key` * | string | Chave da dívida devolvida no momento da criação da operação de crédito. |

### Body Params

| Campo | Tipo | Descrição |  Caracteres |
|---|---| ---| ---| 
| `financial` * | string | Objeto financial simplificado que trás a data de desembolso | [Objeto financial](#objeto-financial)   |

### Objeto financial

| Campo | Tipo | Descrição | Caracteres | 
|---|---|---|---|
| `installment_face_value` | float | Valor de parcela | 10 |

## Response

STATUS 200

**Response Body**

```json

{
  "data": {
    "additional_iof": 38000,
    "annual_cet": "253,2642%",
    "assignment_amount": 10000000,
    "base_iof": 69331,
    "borrower": {
      "document_number": "89940878025962",
      "name": "Parmalat"
    },
    "cet": "11,0900%",
    "collaterals": [],
    "contract": {
      "external_contract_key": "2f0b8b6e-0b60-47f0-b27f-e291c028549b",
      "number": "1907258737/P",
      "signature_information": [
        {
          "signature_url": "https://sign.qitech.com.br/s/hNrwjda",
          "signer_document_number": "94632180173",
          "signer_email": "pedro.alves@yopmail.com",
          "signer_external_key": "07a1c438-43a4-49a9-85a9-29667507453b",
          "signer_name": "Pedro Felipe Henrique Alves",
          "signer_role": "issuer"
        },
        {
          "signature_url": "https://sign.qitech.com.br/s/EaTajda",
          "signer_document_number": "34651104630",
          "signer_email": "patricia.tereza@yopmail.com",
          "signer_external_key": "61a1ea50-769a-410a-8ef8-09f0ce4611f6",
          "signer_name": "Patrícia Tereza Bernardes",
          "signer_role": "guarantor"
        }
      ],
      "urls": [
        "https://storage.googleapis.com/sandbox-doc-api/documents/abedfeab-dcf8-4e13-897b-da02c222cef4/SALGADINHO_SALETE_LTDA-PARMALAT-CCB-1907258737-20220512165254.pdf"
      ]
    },
    "contract_fee_amount": 50000,
    "contract_fees": [
      {
        "fee_amount": 50000,
        "fee_type": "tac"
      }
    ],
    "external_contract_fee_amount": 0,
    "external_contract_fees": [],
    "installments": [
      {
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": null,
        "business_due_date": "2019-08-26",
        "calendar_days": 32,
        "digitable_line": null,
        "due_date": "2019-08-26",
        "due_interest": null,
        "due_principal": 10000000,
        "fine_amount": null,
        "has_interest": true,
        "installment_key": "81e4a732-d300-4e39-b6d5-2d9ac8df429b",
        "installment_number": 1,
        "installment_payment": [],
        "installment_status": "created",
        "installment_type": "principal",
        "original_due_principal": 10000000,
        "original_pre_fixed_amount": 1125598.54,
        "original_principal_amortization_amount": 1000000,
        "original_total_amount": null,
        "paid_amount": 0,
        "paid_at": null,
        "payments": [],
        "post_fixed_amount": null,
        "pre_fixed_amount": 1125598.54,
        "principal_amortization_amount": 1000000,
        "tax_amount": 1312,
        "total_amount": null,
        "total_paid_amount": 0,
        "workdays": 22
      }, ... x [número de parcelas]
    ],
    "iof_charge_method": "financed",
    "issue_amount": 10000000,
    "net_external_contract_fee_amount": 0,
    "number_of_installments": 10,
    "post_fixed_interest_base": "workdays",
    "post_fixed_interest_rate": 1,
    "prefixed_interest_rate": {
      "annual_rate": 2.32,
      "created_at": null,
      "daily_rate": 0.0033388,
      "interest_base": "calendar_days",
      "monthly_rate": 0.10516767
    },
    "requester_identifier_key": "b7ddbcfb-3de0-49d8-8014-07972d8b27f2",
    "total_iof": 107331,
    "total_pre_fixed_amount": 5935915.16
  },
  "event_datetime": "2022-05-12 16:53:10",
  "key": "b7ddbcfb-3de0-49d8-8014-07972d8b27f2",
  "status": "waiting_signature",
  "webhook_type": "debt"
}
```

STATUS 400

**Response Body**

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

---

# Alterar Dados de Desembolso

URL: /documentation/emissao_de_divida/reprocessar_multiplas_datas/trocar_conta

## Request

ENDPOINT /debt/ DEBT-KEY /disbursement_bank_accounts
MÉTODO PUT

### Path Params

| Campo | Tipo | Descrição |
|---|---| ---|
| `debt_key` *(obrigatório)* | string | ID da divida emitida. |

**Request Body**

```json
{
	"disbursement_bank_accounts": [{
		"bank_code": "329",
		"branch_number": "001",
		"account_number": "6947216",
		"account_digit": "4",
		"account_type": "checking_account",
		"document_number": "946321801",
		"name": "Pedro Felipe Henrique Alves",
		"percentage_receivable": 100
	}]
}
```

### Body Params

Uma emissão de dívida deve conter as informações bancárias para desembolso, por padrão, uma conta de titularidade do devedor.

| Campo                 | Tipo   | Descrição                                                                                          | Máx. Caract. | 
|-----------------------|--------|----------------------------------------------------------------------------------------------------|--------------|
| name *                  | string | Nome do titular da conta                                                                           | 50           |
| document_number *      | string | CPF do titular da conta                                                                            | 11           |
| bank_code *           | string | Código COMPE da instituição financeira (https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf) | 3            |
| branch_number *       | string | Número da agência (não informar o dígito verificador da agência!)                                  | 4            |
| account_number *      | string | Número da conta (sem o dígito verificador da conta!)                                               | 10           |
| account_digit *       | string | Dígito verificador da conta (informar zero no lugar de letras)                                     | 1            |
| account_type          | enum   | [Enumerador Account Type](#enumerador-account-type) Tipo da conta                                  | 1            |

## Response

STATUS 200

**Request Body**

```json
{}
```

STATUS 400

**Request Body**

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

---

# Alterar Data de Desembolso

URL: /documentation/emissao_de_divida/reprocessar_multiplas_datas/trocar_data

## Request

ENDPOINT /debt/ DEBT-KEY /disbursement_option
MÉTODO PATCH

### Path Params

| Campo | Tipo | Descrição |
|---|---| ---|
| `debt_key` *(obrigatório)* | string | ID da divida emitida. |

**Request Body**

```json
{
    "disbursement_date": "2023-06-30",
    "status": "active"
}
```

### Body Params

| Campo | Tipo | Descrição |
|---|---| ---|
| `disbursement_date` | string | Data de desembolso da operação. |
| `status` | string | Indica se a data deve ser configurada ou removida. |

## Response

STATUS 200

**Request Body**

```json
{
	"data": {
		"additional_iof": 17.770586,
		"annual_cet": 31.682,
		"assignment_amount": 4676.97,
		"base_iof": 127.71954759,
		"borrower": {
			"document_number": "88229032939",
			"name": "Teste",
			"related_party_key": "13d210c8-d39a-40f9-bd16-b6ab81d35fa8"
		},
		"cet": 2.32,
		"collaterals": [],
		"contract": {
			"number": "0000051370/TG",
			"urls": [
				"https://storage.googleapis.com/dev-doc-api/documents/a715175f-8d29-4929-9576-4b692d1e9610/BEATRIZCOUTODECARVALHO-TESTE-CCB-0000051370-20230707151409.pdf"
			]
		},
		"contract_fee_amount": 0.5,
		"contract_fees": [{
			"fee_amount": 0.5,
			"fee_type": "spread"
		}],
		"disbursed_issue_amount": 4530.98,
		"entry": null,
		"external_contract_fee_amount": 0.0,
		"external_contract_fees": [{
			"description": null,
			"fee_amount": 0.0,
			"fee_type": "spread",
			"net_fee_amount": 0.0,
			"rebate_bank_account": null,
			"tax_amount": 0.0
		}],
		"installments": [{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2023-08-29",
				"calendar_days": 50,
				"digitable_line": null,
				"due_date": "2023-08-28",
				"due_interest": 0.0,
				"due_principal": 4676.47,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "29c6e226-b710-4e3b-a5d6-62119b9d9547",
				"installment_number": 1,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 4676.47,
				"original_pre_fixed_amount": 164.86042852,
				"original_principal_amortization_amount": 25.13957148,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 164.86042852,
				"principal_amortization_amount": 25.13957148,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 0.10307224,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 36
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2023-09-29",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2023-09-28",
				"due_interest": 0.0,
				"due_principal": 4651.33042852,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "322d7973-4d2a-41a6-ad1b-2fef59c551b7",
				"installment_number": 2,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 4651.33042852,
				"original_pre_fixed_amount": 100.99385125,
				"original_principal_amortization_amount": 89.00614875,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 100.99385125,
				"principal_amortization_amount": 89.00614875,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 0.59117884,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 22
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2023-10-31",
				"calendar_days": 30,
				"digitable_line": null,
				"due_date": "2023-10-28",
				"due_interest": 0.0,
				"due_principal": 4562.32427977,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "a2d43778-0342-48f7-a0d2-c385773fa545",
				"installment_number": 3,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 4562.32427977,
				"original_pre_fixed_amount": 95.83242026,
				"original_principal_amortization_amount": 94.16757974,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 95.83242026,
				"principal_amortization_amount": 94.16757974,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 0.85711331,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 20
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2023-11-29",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2023-11-28",
				"due_interest": 0.0,
				"due_principal": 4468.15670003,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "9126aa9a-6bb0-44c6-8ea4-61fd68fcd936",
				"installment_number": 4,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 4468.15670003,
				"original_pre_fixed_amount": 97.01661904,
				"original_principal_amortization_amount": 92.98338096,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 97.01661904,
				"principal_amortization_amount": 92.98338096,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 1.08269849,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 20
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2023-12-29",
				"calendar_days": 30,
				"digitable_line": null,
				"due_date": "2023-12-28",
				"due_interest": 0.0,
				"due_principal": 4375.17331907,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "f0b363f9-0aca-4154-b14a-2c7933374abc",
				"installment_number": 5,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 4375.17331907,
				"original_pre_fixed_amount": 91.90128137,
				"original_principal_amortization_amount": 98.09871863,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 91.90128137,
				"principal_amortization_amount": 98.09871863,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 1.38358433,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 21
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2024-01-30",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2024-01-28",
				"due_interest": 0.0,
				"due_principal": 4277.07460043,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "c7c41dee-28a3-4b37-b2de-256fa0c9a0a9",
				"installment_number": 6,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 4277.07460043,
				"original_pre_fixed_amount": 92.86767319,
				"original_principal_amortization_amount": 97.13232681,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 92.86767319,
				"principal_amortization_amount": 97.13232681,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 1.61686471,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 20
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2024-02-29",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2024-02-28",
				"due_interest": 0.0,
				"due_principal": 4179.94227362,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "ee5d7b27-5160-49d3-9eb0-ec5a2f20e50d",
				"installment_number": 7,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 4179.94227362,
				"original_pre_fixed_amount": 90.75864903,
				"original_principal_amortization_amount": 99.24135097,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 90.75864903,
				"principal_amortization_amount": 99.24135097,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 1.90424304,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 21
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2024-04-01",
				"calendar_days": 29,
				"digitable_line": null,
				"due_date": "2024-03-28",
				"due_interest": 0.0,
				"due_principal": 4080.70092265,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "a9ec8c98-0061-4956-8af8-93d5742f6c1f",
				"installment_number": 8,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 4080.70092265,
				"original_pre_fixed_amount": 82.82984224,
				"original_principal_amortization_amount": 107.17015776,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 82.82984224,
				"principal_amortization_amount": 107.17015776,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 2.31123162,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 21
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2024-04-30",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2024-04-28",
				"due_interest": 0.0,
				"due_principal": 3973.53076489,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "bfd2ceab-74d4-4ff4-b099-c6ab986b7acb",
				"installment_number": 9,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 3973.53076489,
				"original_pre_fixed_amount": 86.2768573,
				"original_principal_amortization_amount": 103.7231427,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 86.2768573,
				"principal_amortization_amount": 103.7231427,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 2.50055752,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 20
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2024-05-29",
				"calendar_days": 30,
				"digitable_line": null,
				"due_date": "2024-05-28",
				"due_interest": 0.0,
				"due_principal": 3869.80762219,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "eb41f47f-ffcd-4d4d-8834-600cfe95b2a4",
				"installment_number": 10,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 3869.80762219,
				"original_pre_fixed_amount": 81.2859859,
				"original_principal_amortization_amount": 108.7140141,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 81.2859859,
				"principal_amortization_amount": 108.7140141,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 2.88831393,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 21
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2024-07-01",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2024-06-28",
				"due_interest": 0.0,
				"due_principal": 3761.09360809,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "13183e83-70cf-4990-a3cc-c979e43015b9",
				"installment_number": 11,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 3761.09360809,
				"original_pre_fixed_amount": 81.6642313,
				"original_principal_amortization_amount": 108.3357687,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 81.6642313,
				"principal_amortization_amount": 108.3357687,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 3.15365423,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 22
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2024-07-30",
				"calendar_days": 30,
				"digitable_line": null,
				"due_date": "2024-07-28",
				"due_interest": 0.0,
				"due_principal": 3652.75783939,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "a2ed3748-8567-4cab-a1ff-0cf6b2698d15",
				"installment_number": 12,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 3652.75783939,
				"original_pre_fixed_amount": 76.72681698,
				"original_principal_amortization_amount": 113.27318302,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 76.72681698,
				"principal_amortization_amount": 113.27318302,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 3.39026637,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 20
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2024-08-29",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2024-08-28",
				"due_interest": 0.0,
				"due_principal": 3539.48465638,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "1e009f23-2044-40ba-8249-a9077a2391b9",
				"installment_number": 13,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 3539.48465638,
				"original_pre_fixed_amount": 76.85245907,
				"original_principal_amortization_amount": 113.14754093,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 76.85245907,
				"principal_amortization_amount": 113.14754093,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 3.3865059,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 23
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2024-10-01",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2024-09-28",
				"due_interest": 0.0,
				"due_principal": 3426.33711545,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "e475d886-a596-4541-bcae-4986bf7c3609",
				"installment_number": 14,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 3426.33711545,
				"original_pre_fixed_amount": 74.39569823,
				"original_principal_amortization_amount": 115.60430177,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 74.39569823,
				"principal_amortization_amount": 115.60430177,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 3.46003675,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 22
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2024-10-29",
				"calendar_days": 30,
				"digitable_line": null,
				"due_date": "2024-10-28",
				"due_interest": 0.0,
				"due_principal": 3310.73281367,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "5584643d-4e65-4e99-9483-b3c1b051fd63",
				"installment_number": 15,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 3310.73281367,
				"original_pre_fixed_amount": 69.54252108,
				"original_principal_amortization_amount": 120.45747892,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 69.54252108,
				"principal_amortization_amount": 120.45747892,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 3.60529234,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 21
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2024-11-29",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2024-11-28",
				"due_interest": 0.0,
				"due_principal": 3190.27533475,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "23a0002c-49bf-4c22-a506-d89ae4372249",
				"installment_number": 16,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 3190.27533475,
				"original_pre_fixed_amount": 69.27011321,
				"original_principal_amortization_amount": 120.72988679,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 69.27011321,
				"principal_amortization_amount": 120.72988679,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 3.61344551,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 22
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2024-12-31",
				"calendar_days": 30,
				"digitable_line": null,
				"due_date": "2024-12-28",
				"due_interest": 0.0,
				"due_principal": 3069.54544796,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "5efbf6d0-84bc-4041-8a33-e9ab1bf82969",
				"installment_number": 17,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 3069.54544796,
				"original_pre_fixed_amount": 64.47633798,
				"original_principal_amortization_amount": 125.52366202,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 64.47633798,
				"principal_amortization_amount": 125.52366202,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 3.7569232,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 20
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2025-01-29",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2025-01-28",
				"due_interest": 0.0,
				"due_principal": 2944.02178595,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "e9bb5d68-8c93-43a4-b240-d68b0d1d6d08",
				"installment_number": 18,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 2944.02178595,
				"original_pre_fixed_amount": 63.9232354,
				"original_principal_amortization_amount": 126.0767646,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 63.9232354,
				"principal_amortization_amount": 126.0767646,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 3.77347756,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 21
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2025-03-05",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2025-02-28",
				"due_interest": 0.0,
				"due_principal": 2817.94502134,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "d6c34059-ba9b-4345-b937-35293f34a3dd",
				"installment_number": 19,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 2817.94502134,
				"original_pre_fixed_amount": 61.18574366,
				"original_principal_amortization_amount": 128.81425634,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 61.18574366,
				"principal_amortization_amount": 128.81425634,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 3.85541069,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 23
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2025-03-31",
				"calendar_days": 28,
				"digitable_line": null,
				"due_date": "2025-03-28",
				"due_interest": 0.0,
				"due_principal": 2689.130765,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "63fa4169-f1a9-43f0-a059-70e2df35ac7e",
				"installment_number": 20,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 2689.130765,
				"original_pre_fixed_amount": 52.68330953,
				"original_principal_amortization_amount": 137.31669047,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 52.68330953,
				"principal_amortization_amount": 137.31669047,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 4.10988855,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 18
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2025-04-29",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2025-04-28",
				"due_interest": 0.0,
				"due_principal": 2551.81407453,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "859ee4fa-f781-419b-8888-731b0f8fc01b",
				"installment_number": 21,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 2551.81407453,
				"original_pre_fixed_amount": 55.40726995,
				"original_principal_amortization_amount": 134.59273005,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 55.40726995,
				"principal_amortization_amount": 134.59273005,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 4.02836041,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 19
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2025-05-29",
				"calendar_days": 30,
				"digitable_line": null,
				"due_date": "2025-05-28",
				"due_interest": 0.0,
				"due_principal": 2417.22134448,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "d6e25388-d54d-42ca-8b46-ac70fa7aeb23",
				"installment_number": 22,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 2417.22134448,
				"original_pre_fixed_amount": 50.7741553,
				"original_principal_amortization_amount": 139.2258447,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 50.7741553,
				"principal_amortization_amount": 139.2258447,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 4.16702953,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 21
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2025-07-01",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2025-06-28",
				"due_interest": 0.0,
				"due_principal": 2277.99549978,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "d92f0e38-fa48-48c2-a79e-e8316fe5c870",
				"installment_number": 23,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 2277.99549978,
				"original_pre_fixed_amount": 49.46187558,
				"original_principal_amortization_amount": 140.53812442,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 49.46187558,
				"principal_amortization_amount": 140.53812442,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 4.20630606,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 21
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2025-07-29",
				"calendar_days": 30,
				"digitable_line": null,
				"due_date": "2025-07-28",
				"due_interest": 0.0,
				"due_principal": 2137.45737535,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "04aa2658-8fbe-4147-8a14-03c7bba13577",
				"installment_number": 24,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 2137.45737535,
				"original_pre_fixed_amount": 44.89766385,
				"original_principal_amortization_amount": 145.10233615,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 44.89766385,
				"principal_amortization_amount": 145.10233615,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 4.34291292,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 21
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2025-08-29",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2025-08-28",
				"due_interest": 0.0,
				"due_principal": 1992.35503921,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "af5b3343-7d91-46cf-a908-bf24e4e79907",
				"installment_number": 25,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 1992.35503921,
				"original_pre_fixed_amount": 43.25979382,
				"original_principal_amortization_amount": 146.74020618,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 43.25979382,
				"principal_amortization_amount": 146.74020618,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 4.39193437,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 23
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2025-09-30",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2025-09-28",
				"due_interest": 0.0,
				"due_principal": 1845.61483303,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "1e7981d6-4274-49f1-ab6e-a98d97485e78",
				"installment_number": 26,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 1845.61483303,
				"original_pre_fixed_amount": 40.07363891,
				"original_principal_amortization_amount": 149.92636109,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 40.07363891,
				"principal_amortization_amount": 149.92636109,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 4.48729599,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 21
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2025-10-29",
				"calendar_days": 30,
				"digitable_line": null,
				"due_date": "2025-10-28",
				"due_interest": 0.0,
				"due_principal": 1695.68847194,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "a07e171b-e2a6-49b4-9d6d-8124fff9d736",
				"installment_number": 27,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 1695.68847194,
				"original_pre_fixed_amount": 35.61823023,
				"original_principal_amortization_amount": 154.38176977,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 35.61823023,
				"principal_amortization_amount": 154.38176977,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 4.62064637,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 22
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2025-12-01",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2025-11-28",
				"due_interest": 0.0,
				"due_principal": 1541.30670217,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "0cd84cc5-0dd0-4318-99f9-178843d3d5b5",
				"installment_number": 28,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 1541.30670217,
				"original_pre_fixed_amount": 33.46622796,
				"original_principal_amortization_amount": 156.53377204,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 33.46622796,
				"principal_amortization_amount": 156.53377204,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 4.6850558,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 23
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2025-12-30",
				"calendar_days": 30,
				"digitable_line": null,
				"due_date": "2025-12-28",
				"due_interest": 0.0,
				"due_principal": 1384.77293013,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "24dc3c8b-ac3a-496e-8646-a1e66051090b",
				"installment_number": 29,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 1384.77293013,
				"original_pre_fixed_amount": 29.08739451,
				"original_principal_amortization_amount": 160.91260549,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 29.08739451,
				"principal_amortization_amount": 160.91260549,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 4.81611428,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 19
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2026-01-29",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2026-01-28",
				"due_interest": 0.0,
				"due_principal": 1223.86032464,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "bba128ee-b195-4a65-9caf-3ebe452d9d10",
				"installment_number": 30,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 1223.86032464,
				"original_pre_fixed_amount": 26.57354762,
				"original_principal_amortization_amount": 163.42645238,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 26.57354762,
				"principal_amortization_amount": 163.42645238,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 4.89135372,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 22
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2026-03-03",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2026-02-28",
				"due_interest": 0.0,
				"due_principal": 1060.43387227,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "35a03898-607a-4194-804c-bfd375c3ea45",
				"installment_number": 31,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 1060.43387227,
				"original_pre_fixed_amount": 23.02508598,
				"original_principal_amortization_amount": 166.97491402,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 23.02508598,
				"principal_amortization_amount": 166.97491402,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 4.99755918,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 20
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2026-03-31",
				"calendar_days": 28,
				"digitable_line": null,
				"due_date": "2026-03-28",
				"due_interest": 0.0,
				"due_principal": 893.45895824,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "0a8a83db-835d-46bc-8e24-c542c44d6e68",
				"installment_number": 32,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 893.45895824,
				"original_pre_fixed_amount": 17.50393379,
				"original_principal_amortization_amount": 172.49606621,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 17.50393379,
				"principal_amortization_amount": 172.49606621,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 5.16280726,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 20
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2026-04-29",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2026-04-28",
				"due_interest": 0.0,
				"due_principal": 720.96289203,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "07e3155c-30b5-4d13-8a31-0af4c7d5c9c5",
				"installment_number": 33,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 720.96289203,
				"original_pre_fixed_amount": 15.65418772,
				"original_principal_amortization_amount": 174.34581228,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 15.65418772,
				"principal_amortization_amount": 174.34581228,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 5.21817016,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 20
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2026-05-29",
				"calendar_days": 30,
				"digitable_line": null,
				"due_date": "2026-05-28",
				"due_interest": 0.0,
				"due_principal": 546.61707975,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "d1badc80-d7a2-4428-abf6-4877ac9f4497",
				"installment_number": 34,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 546.61707975,
				"original_pre_fixed_amount": 11.48178326,
				"original_principal_amortization_amount": 178.51821674,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 11.48178326,
				"principal_amortization_amount": 178.51821674,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 5.34305023,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 21
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2026-06-30",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2026-06-28",
				"due_interest": 0.0,
				"due_principal": 368.098863,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "4b466830-c432-4478-a1b9-bff6562834ee",
				"installment_number": 35,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 368.098863,
				"original_pre_fixed_amount": 7.99248758,
				"original_principal_amortization_amount": 182.00751242,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 7.99248758,
				"principal_amortization_amount": 182.00751242,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 5.44748485,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 20
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2026-07-29",
				"calendar_days": 30,
				"digitable_line": null,
				"due_date": "2026-07-28",
				"due_interest": 0.0,
				"due_principal": 186.09135058,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "0e8843ff-1339-40ab-a0b5-c450eca68e44",
				"installment_number": 36,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 186.09135058,
				"original_pre_fixed_amount": 3.90887682,
				"original_principal_amortization_amount": 186.09112318,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 3.90887682,
				"principal_amortization_amount": 186.09112318,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 5.56970732,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 22
			}
		],
		"iof_charge_method": "financed",
		"issue_amount": 4676.47,
		"net_external_contract_fee_amount": 0.0,
		"number_of_installments": 36,
		"prefixed_interest_rate": {
			"annual_rate": 0.28777498,
			"created_at": "2023-07-07T18:13:42",
			"daily_rate": 0.00069316,
			"interest_base": "calendar_days_365",
			"monthly_rate": 0.0213
		},
		"requester_identifier_key": "7d174b91-e411-4375-b788-9ced9b941cd0",
		"total_iof": 145.49,
		"total_pre_fixed_amount": 2163.53022742
	},
	"event_datetime": "2023-07-07 19:04:20",
	"key": "7d174b91-e411-4375-b788-9ced9b941cd0",
	"status": "waiting_signature",
	"webhook_type": "debt"
}
```

STATUS 400

**Request Body**

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

---

# Seguro

URL: /documentation/emissao_de_divida/seguro

Na QI Tech disponibilizamos aos nossos clientes a possibilidade de oferecer seguro junto com a operação de crédito,
aqui você entenderá como usá-lo em nossas API's e entender melhor sobre esse novo produto.

:::caution Atenção
Esse produto está disponível apenas para parceiros cadastrados, por favor consulte um de nossos comerciais para mais detalhes.
:::

## Como usar

Para contratar ou simular uma dívida com a contratação de seguro, deverá ser adicionado a lista de rebates um rebate do tipo
"insurance_premium_qi", sem nenhum valor declarado, pois ele será calculado de acordo com o valor de emissão da proposta e
com o produto de seguro a ser contratado.

:::caution Atenção
Não é possível usar rebates do tipo tac ou **insurance_premium** junto com o **insurance_premium_qi**.
:::

Objeto Rebate

```json
{
  "rebates": [
    {
      "fee_type": "insurance_premium_qi",
      "description": "insurance_premium_plus"
    }
  ]
}
```

## Simulação de dívida

### Request

No exemplo abaixo, está descrita uma simulação de dívida, onde é pedido uma cotação de seguro.

ENDPOINT /fgts_simulation
MÉTODO POST

Request Body

```json
{
  "borrower": {
    "person_type": "natural",
    "individual_document_number": "46338864879",
    "birth_date": "1996-03-20"
  },
  "financial": {
    "desired_installments": [
      {
        "total_amount": 200,
        "due_date": "2023-10-01"
      }
    ],
    "interest_type": "pre_price_days",
    "disbursement_date": "2023-03-03",
    "fine_configuration": {
      "monthly_rate": 0,
      "interest_base": "calendar_days",
      "contract_fine_rate": 0
    },
    "monthly_interest_rate": 0.018,
    "credit_operation_type": "ccb",
    "interest_grace_period": 0,
    "number_of_installments": 1,
    "principal_grace_period": 0,
    "rebates": [
      {
        "fee_type": "insurance_premium_qi",
        "description": "insurance_premium_plus"
      }
    ]
  }
}
```

### Response

STATUS 200

Response Body

```json
{
    "type": "debt",
    "key": "a445c71c-d752-4159-82bf-097d8125b66c",
    "status": "finished",
    "event_datetime": "2024-10-03 00:26:26",
    "data": {
        "interest_type": "pre_price_days",
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "interest_payment_month_period": 1,
        "principal_grace_period": 0,
        "principal_amortization_month_period": 1,
        "operation_type": "structured_operation",
        "post_fixed_interest_base": "workdays",
        "post_fixed_interest_rate": null,
        "prefixed_interest_rate": {
            "interest_base": "calendar_days_365",
            "annual_rate": 0.23872053,
            "monthly_rate": 0.018,
            "daily_rate": 0.00058669
        },
        "issue_date": "2023-03-03",
        "number_of_installments": 1,
        "requester_key": "9cdbe6f9-0e94-45a7-af5f-2cec36356493",
        "final_disbursement_amount": 119.01,
        "total_pre_fixed_amount": 23.3844066642,
        "iof_amount": 3.74,
        "cet": 0.0773,
        "annual_cet": 1.44428,
        "disbursement_date": "2023-03-03",
        "installments": [
            {
                "calendar_days": 212,
                "workdays": 145.0,
                "business_due_date": "2023-10-02",
                "due_date": "2023-10-01",
                "due_principal": 176.62,
                "has_interest": true,
                "post_fixed_amount": null,
                "pre_fixed_amount": 23.3844066642,
                "tax_amount": 3.0702854745495474,
                "total_amount": 200,
                "principal_amortization_amount": 176.6155933358,
                "installment_number": 1
            }
        ],
        "external_contract_fees": [
            {
                "fee_type": "spread",
                "amount_type": "absolute",
                "amount": 0.0,
                "fee_amount": 0.0,
                "tax_amount": 0.0,
                "net_fee_amount": 0.0,
                "csll_amount": 0,
                "irrf_amount": 0,
                "pis_amount": 0,
                "cofins_amount": 0,
                "amount_released": 0,
                "description": null
            },
            {
                "fee_type": "tac",
                "amount_type": "absolute",
                "amount": 0.0,
                "fee_amount": 0.0,
                "tax_amount": 0.0,
                "net_fee_amount": 0.0,
                "csll_amount": 0,
                "irrf_amount": 0,
                "pis_amount": 0,
                "cofins_amount": 0,
                "amount_released": 0,
                "description": null
            },
            {
                "fee_type": "insurance_premium_qi",
                "description": "insurance_premium_plus",
                "amount_type": "percentage",
                "amount": 30.0,
                "fee_amount": 52.99,
                "tax_amount": 0.0,
                "net_fee_amount": 52.99,
                "csll_amount": 0,
                "irrf_amount": 0,
                "pis_amount": 0,
                "cofins_amount": 0,
                "amount_released": 52.99,
                "description": null
            }
        ],
        "contract_fee_amount": 0.88,
        "external_contract_fee_amount": 52.99,
        "net_external_contract_fee_amount": 52.99,
        "contract_fees": [
            {
                "fee_type": "tac",
                "amount_type": "percentage",
                "amount": 0.5,
                "fee_amount": 0.88
            }
        ],
        "issue_amount": 176.62,
        "disbursed_issue_amount": 119.01,
        "assignment_amount": 176.62,
        "disbursement_options": [
            {
                "iof_amount": 3.74,
                "total_pre_fixed_amount": 23.3844066642,
                "cet": 0.0773,
                "annual_cet": 1.44428,
                "contract_fees": [
                    {
                        "fee_type": "tac",
                        "amount_type": "percentage",
                        "amount": 0.5,
                        "fee_amount": 0.88
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "tac",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "insurance_premium_qi",
                        "description": "insurance_premium_plus",
                        "amount_type": "percentage",
                        "amount": 30.0,
                        "fee_amount": 52.99,
                        "tax_amount": 0.0,
                        "net_fee_amount": 52.99,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 52.99,
                        "description": null
                    }
                ],
                "contract_fee_amount": 0.88,
                "external_contract_fee_amount": 52.99,
                "net_external_contract_fee_amount": 52.99,
                "disbursement_date": "2023-03-03",
                "first_due_date": "2023-10-01",
                "installments": [
                    {
                        "calendar_days": 212,
                        "workdays": 145.0,
                        "business_due_date": "2023-10-02",
                        "due_date": "2023-10-01",
                        "due_principal": 176.62,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 23.3844066642,
                        "tax_amount": 3.0702854745495474,
                        "total_amount": 200,
                        "principal_amortization_amount": 176.6155933358,
                        "installment_number": 1
                    }
                ],
                "issue_amount": 176.62,
                "disbursed_issue_amount": 119.01,
                "assignment_amount": 176.62,
                "final_disbursement_amount": 119.01,
                "prefixed_interest_rate": {
                    "interest_base": "calendar_days_365",
                    "annual_rate": 0.23872053,
                    "monthly_rate": 0.018,
                    "daily_rate": 0.00058669
                }
            }
        ]
    }
}
```

:::danger AVISO
É possível validar a elegibilidade da cobrança de seguro, já na simulação.\
Para isso, é obrigatório o envio da data de nascimento (**birth_date**), CPF do devedor (**document_number**) e o rebate "**insurance_premium_qi**".\
Se o CPF for elegível, teremos um retorno de sucesso, se não for elegível, a requisição de simulação retornará um erro.
:::

:::danger AVISO
O envio da data de nascimento (**birth_date**) **não é obrigatório na simulação com seguro**. Porém, na emissão de dívida temos a obrigatoriedade do envio desse campo, caso haja a contração do produto.
:::

## Consulta de elegibilidade de CPF para o seguro

Em posse dos dados de **CPF**, é possível a consulta da elegibilidade do CPF.

### Request

ENDPOINT /debts/borrower/[document_number]/insurance_premium_eligibility?birth_date=1994-06-11&issue_amount=150
METHOD GET

### Params

| Campo             | Descrição                               |
|-------------------|-----------------------------------------|
| `document_number` | Número de CPF do devedor                |
| `birth_date`      | Data de nascimento                      |
| `issue_amount`    | Valor de emissão da operação de crédito |

### Response

STATUS 200

Response Body

```json
{
    "eligible": true
}
```

### Descrição
| Campo                        | Tipo   |
|------------------------------|--------|
| `elegible`            | boleean |

:::caution Atenção
Para um CPF com o retorno **"elegible": false**, tanto a simulação, quanto a emissão da dívida não serão possíveis com o envio de insurance_premium_qi na lista **rebates**.
:::

## Criação de dívida

Para criação de dívida com seguro é necessário alguns dados obrigatórios do tomador do crédito, como **endereço, telefone, email e
data de nascimento**. Se alguns desses dados for omtido a dívida não será emitida.

### Request

ENDPOINT /debt
MÉTODO POST

Request Body

```json
{
  "borrower": {
    "person_type": "natural",
    "individual_document_number": "46338864879",
    "name": "PATRICIA APARECIDA DO NASCIMENTO PEREIRA DA SILVA",
    "is_pep": false,
    "mother_name": "HELENA DO NASCIMENTO PEREIRA DA SILVA",
    "email": "email@email.com",
    "birth_date": "1994-06-11",
    "phone": {
      "number": "900000000",
      "area_code": "11",
      "country_code": "055"
    },
    "address": {
      "city": "São Paulo",
      "state": "SP",
      "number": "215",
      "street": "Gilberto Sabino",
      "complement": "s/c",
      "postal_code": "12345012",
      "neighborhood": "Pinheiros"
    }
  },
  "financial": {
    "desired_installments": [
      {
        "total_amount": 200,
        "due_date": "2023-10-01"
      }
    ],
    "interest_type": "pre_price_days",
    "disbursement_date": "2023-03-03",
    "fine_configuration": {
      "monthly_rate": 0,
      "interest_base": "calendar_days",
      "contract_fine_rate": 0
    },
    "monthly_interest_rate": 0.018,
    "credit_operation_type": "ccb",
    "interest_grace_period": 0,
    "number_of_installments": 1,
    "principal_grace_period": 0,
    "rebates": [
      {
        "fee_type": "insurance_premium_qi",
        "description": "insurance_premium_plus"
      }
    ]
  },
  "disbursement_bank_account": {
    "ispb_number": "18236120",
    "branch_number": "1",
    "account_number": "87823171",
    "account_digit": "0",
    "document_number": "46338864879",
    "name": "PATRICIA APARECIDA DO NASCIMENTO PEREIRA DA SILVA",
    "percentage_receivable": 1
  },
  "purchaser_document_number": "32402502000135"
}
```

### Response

STATUS 201

Response Body

```json
{
  "webhook_type": "debt",
  "key": "7a9bb512-7b38-4dbc-a109-1bc122b67a4a",
  "status": "waiting_signature",
  "event_datetime": "2023-03-03 18:06:18",
  "data": {
    "borrower": {
      "name": "PATRICIA APARECIDA DO NASCIMENTO PEREIRA DA SILVA",
      "document_number": "46338864879",
      "related_party_key": "1b98cff5-b1eb-4f3d-b337-716d76137770"
    },
    "contract": {
      "number": "0000062201/PAD",
      "urls": [
        "https://storage.googleapis.com/live-doc-api/documents/45e5b9c0-0f56-40a8-aace-d206f72c164d/QISCD-NOME_DO_DEVEDOR-CCB-0000000002-20230317183044.pdf"
      ],
      "external_contract_key": "35b882b1-9937-41d3-bf43-e0d30062dc1b",
      "signature_information": [
        {
          "signer_name": "PATRICIA APARECIDA DO NASCIMENTO PEREIRA DA SILVA",
          "signer_document_number": "46338864879",
          "signer_role": "issuer",
          "signer_email": "email@email.com",
          "signer_external_key": "3a50f3cd-8178-49c8-9fc2-984b4caa4a5b",
          "signature_url": "https://sandbox.sign.qitech.com.br/s/ml9Myfp"
        }
      ]
    },
    "requester_identifier_key": "7a9bb512-7b38-4dbc-a109-1bc122b67a4a",
    "iof_charge_method": "financed",
    "collaterals": [],
    "contract_fees": [],
    "external_contract_fees": [
      {
        "fee_type": "insurance_premium_qi",
        "description": "insurance_premium_plus",
        "fee_amount": 52.99,
        "tax_amount": 0,
        "net_fee_amount": 52.99
      }
    ],
    "external_contract_fee_amount": 52.99,
    "net_external_contract_fee_amount": 52.99,
    "contract_fee_amount": 0,
    "issue_amount": 176.62,
    "assignment_amount": 176.62,
    "cet": "7,6200%",
    "annual_cet": "141,3472%",
    "number_of_installments": 1,
    "base_iof": 3.0702854745495474,
    "additional_iof": 0.671156,
    "total_iof": 3.74,
    "prefixed_interest_rate": {
      "annual_rate": 0.23872053,
      "created_at": "2024-09-11T18:06:07",
      "daily_rate": 0.00058669,
      "interest_base": "calendar_days_365",
      "monthly_rate": 0.018
    },
    "installments": [
      {
        "accrual_reference_date": null,
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": null,
        "business_due_date": "2023-10-02",
        "calendar_days": 212,
        "digitable_line": null,
        "due_date": "2023-10-01",
        "due_interest": 0,
        "due_principal": 176.62,
        "fine_amount": null,
        "has_interest": true,
        "installment_history": [],
        "installment_key": "6087c6c1-d665-4ba8-bfb2-b447cd57d3e3",
        "installment_number": 1,
        "installment_payment": [],
        "installment_status": "created",
        "installment_type": "principal",
        "original_due_principal": 176.62,
        "original_pre_fixed_amount": 23.3844066642,
        "original_principal_amortization_amount": 176.6155933358,
        "original_total_amount": 200,
        "paid_amount": 0,
        "paid_at": null,
        "post_fixed_amount": null,
        "pre_fixed_amount": 23.3844066642,
        "principal_amortization_amount": 176.6155933358,
        "qr_code_key": null,
        "qr_code_url": null,
        "renegotiation_proposal_key": null,
        "tax_amount": 3.0702854745495474,
        "total_accrual_amount": null,
        "total_amount": 200,
        "total_paid_amount": 0,
        "workdays": 145
      }
    ],
    "total_pre_fixed_amount": 23.3844066642
  }
}
```

## Webhooks

### Seguro emitido

 A emissão do seguro será feito após o desembolso da operação, o seguinte webhook será enviado quando o
 seguro terminar de ser emitido com os dados do seguro.

:::caution Atenção
Ao receber o webhook de bilhete emitido é obrigatório a transmissão do documento do bilhete gerado para o tomador de crédito.
:::

Webhook Body

```json
{
  "data": {
    "credit_operation_key": "5ae2c008-44c1-4435-bbfa-094a4b11d962",
    "insurance_policy_document_key": "9990ce22-aeac-4728-82da-d1f22c33873f",
    "insurance_date": "2024-09-11",
    "term_start_date": "2024-09-11",
    "term_end_date": "2025-09-11",
    "insurance_amount": 1600,
    "operation_amount": 6400,
    "covers": [
      {
        "cover_amount": 200,
        "cover_type": "permanent_disability",
        "cover_prize_amount": 572.82
      },
      {
        "cover_amount": 100,
        "cover_type": "accidental_death",
        "cover_prize_amount": 572.82
      },
      {
        "capitalcover_amount_segurado": 300,
        "cover_type": "unemployment",
        "cover_prize_amount": 572.82
      }
    ],
    "policy_number": "1098200000008",
    "prize_number": "3907",
    "insurance_premium_net_amount": 1145.63,
    "iof_amount": 4.37
  },
  "event_datetime": "2023-03-03 22:39:39",
  "key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
  "status": "active",
  "webhook_type": "insurance_premium.status_change"
}
```

### Seguro cancelado

O seguro pode ser cancelado quando o tomador do crédito queira desistir de operação de créditoe a operação for revertida, se algum limite de cobertura for ultrapassado (tornando inelegível a contratação do seguro)
ou quando tomador acaba desistindo somente do seguro.

:::caution Atenção
O bilhete de seguro só pode ser cancelado totalmente dentro de 7 dias corridos do desembolso da operação de crédito,
caso queira cancelar após isso o valor devolvido vai ser proporcional a duração do seguro.
:::

Webhook Body

```json
{
    "key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
    "data": {
        "cancel_reason": "reversed_operation",
        "credit_operation_key": "2fbd6613-3228-5gdg-9377-93db394bf2d4"
    },
    "status": "canceled",
    "webhook_type": "insurance_premium.status_change",
    "event_datetime": "2023-03-03 22:39:39"
}
```

### Motivos de cancelamento

| cancel_reason                 | Descrição                              |
|-------------------------------|----------------------------------------|
| `reversed_operation`          | Operação revertida e seguro cancelados |
| `cover_limit_amount_exceeded` | Somente o seguro foi cancelado. Algum limite de cobertura foi ultrapassado e não foi possível a emissão do seguro  |
| `insurance_premium_cancel`    | Somente o seguro foi cancelado. Cancelamento do tomador direto com a seguradora  |

## Consulta do seguro

### Request

ENDPOINT /debt/[debt_key]/insurance_premiums
METHOD GET

### Response

STATUS 200

Response Body

```json
{
  "data": [
    {
      "insurance_premium_key": "e4fe84e3-cc71-481b-87ea-8a07f7d69079",
      "status": "active",
      "credit_operation_key": "5ae2c008-44c1-4435-bbfa-094a4b11d962",
      "disbursement_key": "bd0ea133-ff47-4a21-a3e6-24186e5e2fc1",
      "contract_number": "4069550961/QIT",
      "requester_key": "1040ce22-aeac-4728-82da-d1f22c33873f",
      "insurance_policy_document_key": "9990ce22-aeac-4728-82da-d1f22c33873f",
      "insurance_date": "2024-09-11",
      "term_start_date": "2024-09-11",
      "term_end_date": "2025-09-11",
      "insurance_amount": 1600,
      "operation_amount": 6400,
      "customer": {
        "customer_key": "cd587fa8-3abd-4023-99ab-957df60933a5",
        "document_number": "08556878350",
        "name": "Wilker Oliveiraço",
        "birth_date": "1998-03-21",
        "email": "urich.oliveira@yopmail.com",
        "phone": {
          "country_code": "55",
          "area_code": "11",
          "number": "966931427"
        },
        "address": {
          "postal_code": "56821686",
          "state": "CE",
          "city": "Ceará",
          "neighborhood": "Marmiteiros",
          "street": "Conjunto João Gabriel da Mata",
          "number": "95",
          "complement": ""
        }
      },
      "covers": [
        {
          "cover_amount": 200,
          "cover_type": "permanent_disability",
          "cover_prize_amount": 572.82
        },
        {
          "cover_amount": 100,
          "cover_type": "accidental_death",
          "cover_prize_amount": 572.82
        },
        {
          "cover_amount": 300,
          "cover_type": "unemployment",
          "cover_prize_amount": 572.82
        }
      ],
      "policy_number": "1098200000008",
      "prize_number": "3907",
      "insurance_premium_net_amount": 1145.63,
      "iof_amount": 4.37
    }
  ],
  "pagination": {
    "current_page": 0,
    "next_page": 0,
    "rows_per_page": 1
  }
}
```

### Request

ENDPOINT /debt/[DEBT-KEY]/insurance_premium/[INSURANCE-PREMIUM-KEY]
METHOD GET

### Response

STATUS 200

Response Body

```json
{
  "insurance_premium_key": "e4fe84e3-cc71-481b-87ea-8a07f7d69079",
  "status": "active",
  "credit_operation_key": "5ae2c008-44c1-4435-bbfa-094a4b11d962",
  "disbursement_key": "bd0ea133-ff47-4a21-a3e6-24186e5e2fc1",
  "contract_number": "4069550961/QIT",
  "requester_key": "1040ce22-aeac-4728-82da-d1f22c33873f",
  "insurance_policy_document_key": "9990ce22-aeac-4728-82da-d1f22c33873f",
  "insurance_date": "2024-09-11",
  "term_start_date": "2024-09-11",
  "term_end_date": "2025-09-11",
  "insurance_amount": 1600,
  "operation_amount": 6400,
  "customer": {
    "customer_key": "cd587fa8-3abd-4023-99ab-957df60933a5",
    "document_number": "08556878350",
    "name": "Wilker Oliveiraço",
    "birth_date": "1998-03-21",
    "gender": "male",
    "email": "urich.oliveira@yopmail.com",
    "phone": {
      "country_code": "55",
      "area_code": "11",
      "number": "966931427"
    },
    "address": {
      "postal_code": "56821686",
      "state": "CE",
      "city": "Ceará",
      "neighborhood": "Marmiteiros",
      "street": "Conjunto João Gabriel da Mata",
      "number": "95",
      "complement": ""
    }
  },
  "covers": [
    {
      "cover_amount": 300,
      "cover_type": "permanent_disability",
      "cover_prize_amount": 572.82
    },
    {
      "cover_amount": 300,
      "cover_type": "accidental_death",
      "cover_prize_amount": 572.82
    },
    {
      "cover_amount": 300,
      "cover_type": "unemployment",
      "cover_prize_amount": 572.82
    }
  ],
  "policy_number": "1098200000008",
  "prize_number": "3907",
  "insurance_premium_net_amount": 1145.63,
  "iof_amount": 4.37
}
```

## Consulta do documento bilhete

:::caution Atenção
O link do documento é expirável e tem uma duração de 15 minutos.
:::

### Request

ENDPOINT /document/[DOCUMENT-KEY]/url
METHOD GET

### Response

STATUS 200

Response Body

```json
{
    "document_key": "a11dc0fe-51ed-41aa-bb40-bca80d6e515b",
    "signed_document_url": null,
    "document_url": "https://storage.googleapis.com/dev-doc-api-private/documents/a11dc0fe-51ed-41aa-bb40-bca80d6e515b/TESTEELECTRONIC2.pdf?Expires=1726081733&GoogleAccessId=doc-api-signed-url-service-acc%40qicredit-dev.iam.gserviceaccount.com&Signature=CNY8ch%2BQ2FuLXrbRZGLhH41A7SkNJRUUq%2FJoegTIMeXEiNImD%2FkPoEHyNtOXWUUR8JtEL6ppT0s1tXA9oFfLjzOtvzMOfpal0TwJDLSsX9r4HxcxvzFZUJELAn9yIAcRhqR%2BnzUn0WYyQA%2B0hAalz%2Bj274pXhIExqJJR4LiDUAkzRE3WD0GOvsV7afAoqQ8P3Xxj4mvOM3P%2BuFhgP6hcJmq0K%2B5qHssF3DtvpQFLcLaQ7T45YoQDCnDFGztD0Un0%2BNBwv4n2142rV3rMu9h3DzLmQbEjaeYgHb4wq2kOfyfEUSbaU683d6hA7CNyrPWMeoi%2F%2BgTfFFadbcGCMGX2%2BQ%3D%3D",
    "expiration_datetime": "2023-03-03T19:08:53.000Z"
}
```

---

# Simulação de dívida antigo

URL: /documentation/emissao_de_divida/simulacao_de_divida_antigo

Na QI Tech disponibilizamos aos nossos clientes a possibilidade de simular os valores uma operação de crédito antes da
sua emissão de fato. A simulação segue o mesmo padrão da solicitação de emissão de dívida, porém não é necessário
informar os dados cadastrais e de conta de desembolso do devedor. 

## Request

No exemplo abaixo, esta descrita uma solicitação de simulação de dívida.

ENDPOINT /debt_simulation
MÉTODO POST

Request Body

**Data de vencimento e valor da parcela**

```json
{
    "borrower": {
        "person_type": "natural"
    },
    "financial": {
        "desired_installments": [
            {
                "total_amount": 578.69,
                "due_date": "2027-04-01"
            },
            {
                "total_amount": 304.25,
                "due_date": "2028-04-01"
            }
        ],
        "interest_type": "pre_price_days",
        "disbursement_date": "2026-09-06",
        "fine_configuration": {
            "monthly_rate": 0.0,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.0
        },
        "annual_interest_rate": 0.2387205,
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "number_of_installments": 2,
        "principal_grace_period": 0,
        "rebates": [
            {
                "amount": 10,
                "fee_type": "tac",
                "amount_type": "absolute",
                "rebate_bank_account": {
                    "name": "CONTA BANCARIA",
                    "bank_code": "329",
                    "account_digit": "1",
                    "branch_number": "0001",
                    "account_number": "00003",
                    "document_number": "32402502000135"
                }
            }
        ]
    }
}
```

**Taxa e data de parcela**
```json
{
  "borrower": {
    "person_type": "natural"
  },
  "financial": {
    "interest_type": "pre_price_days",
    "disbursement_start_date": "2025-09-03",
    "disbursement_end_date": "2025-09-03",
    "issue_date": "2025-09-03",
    "fine_configuration": {
        "monthly_rate": 0,
        "contract_fine_rate": 0,
        "interest_base": "calendar_days"
      },
    "monthly_interest_rate": 0.1929244498,
    "disbursed_amount": 10000.00,
    "credit_operation_type": "ccb",
    "interest_grace_period": 0,
    "number_of_installments": 18,
    "principal_grace_period": 0,
    "due_dates": [
      "2025-09-28",
      "2025-10-28",
      "2025-11-28",
      "2025-12-28",
      "2026-01-28",
      "2026-02-28",
      "2026-03-28",
      "2026-04-28",
      "2026-05-28",
      "2026-06-28",
      "2026-07-28",
      "2026-08-28",
      "2026-09-28",
      "2026-10-28",
      "2026-11-28",
      "2026-12-28",
      "2027-01-28",
      "2027-02-28"
    ]
  }
}
```

## Response

STATUS 200

Response Body

```json
{
    "type": "debt",
    "key": "bf84379c-d4cf-4f16-a63c-865c129e6fce",
    "status": "finished",
    "event_datetime": "2025-03-27 22:28:37",
    "data": {
        "interest_type": "pre_price_days",
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "interest_payment_month_period": 1,
        "principal_grace_period": 0,
        "principal_amortization_month_period": 1,
        "operation_type": "structured_operation",
        "post_fixed_interest_base": "workdays",
        "post_fixed_interest_rate": null,
        "prefixed_interest_rate": {
            "interest_base": "calendar_days_365",
            "annual_rate": 0.23872053,
            "monthly_rate": 0.0179999999,
            "daily_rate": 0.0005866899
        },
        "issue_date": "2026-09-06",
        "number_of_installments": 2,
        "requester_key": "f2b3b903-aa41-4a79-8b2f-abc3cc5a6590",
        "final_disbursement_amount": 701.6,
        "total_pre_fixed_amount": 153.0,
        "iof_amount": 18.34,
        "cet": 0.0219,
        "annual_cet": 0.297,
        "disbursement_date": "2026-09-06",
        "installments": [
            {
                "calendar_days": 207,
                "workdays": 140,
                "business_due_date": "2027-04-01",
                "due_date": "2027-04-01",
                "due_principal": 729.94,
                "has_interest": true,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 94.22564648,
                "tax_amount": 8.22329794,
                "total_amount": 578.69,
                "principal_amortization_amount": 484.46435352,
                "installment_number": 1
            },
            {
                "calendar_days": 366,
                "workdays": 253,
                "business_due_date": "2028-04-03",
                "due_date": "2028-04-01",
                "due_principal": 245.47564648,
                "has_interest": true,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 58.77435352,
                "tax_amount": 7.3470861,
                "total_amount": 304.25,
                "principal_amortization_amount": 245.47564648,
                "installment_number": 2
            }
        ],
        "external_contract_fees": [
            {
                "fee_type": "tac",
                "amount_type": "absolute",
                "amount": 10.0,
                "fee_amount": 10.0,
                "tax_amount": 1.42,
                "net_fee_amount": 8.58,
                "csll_amount": 0,
                "irrf_amount": 0,
                "pis_amount": 0,
                "cofins_amount": 0,
                "amount_released": 8.58,
                "description": null
            },
            {
                "fee_type": "spread_tax_free",
                "amount_type": "absolute",
                "amount": 0.0,
                "fee_amount": 0.0,
                "tax_amount": 0.0,
                "net_fee_amount": 0.0,
                "csll_amount": 0,
                "irrf_amount": 0,
                "pis_amount": 0,
                "cofins_amount": 0,
                "amount_released": 0,
                "description": null
            },
            {
                "fee_type": "tac_tax_free",
                "amount_type": "absolute",
                "amount": 0.0,
                "fee_amount": 0.0,
                "tax_amount": 0.0,
                "net_fee_amount": 0.0,
                "csll_amount": 0,
                "irrf_amount": 0,
                "pis_amount": 0,
                "cofins_amount": 0,
                "amount_released": 0,
                "description": null
            },
            {
                "fee_type": "insurance_premium",
                "amount_type": "absolute",
                "amount": 0.0,
                "fee_amount": 0.0,
                "tax_amount": 0.0,
                "net_fee_amount": 0.0,
                "csll_amount": 0,
                "irrf_amount": 0,
                "pis_amount": 0,
                "cofins_amount": 0,
                "amount_released": 0,
                "description": null
            }
        ],
        "contract_fee_amount": 3.65,
        "external_contract_fee_amount": 10.0,
        "net_external_contract_fee_amount": 8.58,
        "contract_fees": [
            {
                "fee_type": "spread",
                "amount_type": "percentage",
                "amount": 0.5,
                "fee_amount": 3.65
            },
            {
                "fee_type": "spread_ted_fee",
                "amount_type": "absolute",
                "amount": 3.0,
                "fee_amount": 3.0
            }
        ],
        "issue_amount": 729.94,
        "disbursed_issue_amount": 701.6,
        "assignment_amount": 736.59,
        "disbursement_options": [
            {
                "iof_amount": 18.34,
                "total_pre_fixed_amount": 153.0,
                "cet": 0.0219,
                "annual_cet": 0.297,
                "contract_fees": [
                    {
                        "fee_type": "spread",
                        "amount_type": "percentage",
                        "amount": 0.5,
                        "fee_amount": 3.65
                    },
                    {
                        "fee_type": "spread_ted_fee",
                        "amount_type": "absolute",
                        "amount": 3.0,
                        "fee_amount": 3.0
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "tac",
                        "amount_type": "absolute",
                        "amount": 10.0,
                        "fee_amount": 10.0,
                        "tax_amount": 1.42,
                        "net_fee_amount": 8.58,
                        "csll_amount": 0.0,
                        "irrf_amount": 0.0,
                        "pis_amount": 0.0,
                        "cofins_amount": 0.0,
                        "amount_released": 8.58,
                        "description": null
                    },
                    {
                        "fee_type": "spread_tax_free",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0.0,
                        "description": null
                    },
                    {
                        "fee_type": "tac_tax_free",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0.0,
                        "description": null
                    },
                    {
                        "fee_type": "insurance_premium",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0.0,
                        "description": null
                    }
                ],
                "contract_fee_amount": 3.65,
                "external_contract_fee_amount": 10.0,
                "net_external_contract_fee_amount": 8.58,
                "disbursement_date": "2026-09-06",
                "first_due_date": "2027-04-01",
                "installments": [
                    {
                        "calendar_days": 207,
                        "workdays": 140,
                        "business_due_date": "2027-04-01",
                        "due_date": "2027-04-01",
                        "due_principal": 729.94,
                        "has_interest": true,
                        "post_fixed_amount": 0,
                        "pre_fixed_amount": 94.22564648,
                        "tax_amount": 8.22329794,
                        "total_amount": 578.69,
                        "principal_amortization_amount": 484.46435352,
                        "installment_number": 1
                    },
                    {
                        "calendar_days": 366,
                        "workdays": 253,
                        "business_due_date": "2028-04-03",
                        "due_date": "2028-04-01",
                        "due_principal": 245.47564648,
                        "has_interest": true,
                        "post_fixed_amount": 0,
                        "pre_fixed_amount": 58.77435352,
                        "tax_amount": 7.3470861,
                        "total_amount": 304.25,
                        "principal_amortization_amount": 245.47564648,
                        "installment_number": 2
                    }
                ],
                "issue_amount": 729.94,
                "disbursed_issue_amount": 701.6,
                "assignment_amount": 736.59,
                "final_disbursement_amount": 701.6,
                "prefixed_interest_rate": {
                    "interest_base": "calendar_days_365",
                    "annual_rate": 0.23872053,
                    "monthly_rate": 0.0179999999,
                    "daily_rate": 0.0005866899
                }
            }
        ]
    }
}

```

## Definições

### Request Body

### Objeto Borrower
| Campo | Tipo  | Descrição  | Enum |
|---|---|---|---|
| **person_type** | object | Natureza Jurídica do devedor da operação   |  natural ou legal |

### Objeto Financial
| Campo  | Tipo   | Descrição | Máx. Caract. |
|---|--- |---|---|
| **amout**                  | float  | Valor de emissão/nominal da operação de crédito                                                             | -            |
| **interest_type**          | object | **[Enumerador Interest Type](#enumerador-interest-type)** - Método de amortização e forma de cálculo de juros | -            |
| **credit_operation_type**  | object | **[Enumerador Credit Operation Type](#enumerador-credit-operation-type)** - Tipo do contrato de crédito     | -            |
| **annual_interest_rate**   | float  | Taxa de juros pré-fixada expressa em decimal ao ano                                                         | -            |
| **disbursement_date**      | date   | Data do desembolso da operação                                                                              | -            |
| **interest_grace_period**  | int    | Carência de juros (em meses)                                                                                | -            |
| **principal_grace_period** | int    | Período carência de principal                                                                               | -            |
| **number_of_installments** | int    | Número de parcelas da operação de crédito                                                                   | -            |
| **fine_configuration**     | object | **[Objeto fine_configuration](#objeto-fine-configuration)** - Configuração de juros e multa por atraso      | -            |

### Objeto Fine Configuration
| Campo                  | Tipo  | Descrição                                                                            | Máx. Caract. |
|---|---|---|---|
| **contract_fine_rate** | float | Percentual de multa por atraso expresso em decimal                                   | -            |
| **interest_base**      | enum  | **[Enumerador Interest Base](#enumerador-interest-base)** - Base de cálculo de juros | -            |
| **monthly_rate**       | float | Percentual de juros de atraso ao mês expresso em decimal                             | -            |

### Response Body
| Campo                      | Tipo   | Descrição                       | Máx. Caract. |
|----------------------------|--------|---------------------------------|--------------|
| **data.data**           | object | **[Objeto Data](#objeto-data)** | -            |
| **data.event_datetime** | date   | Momento da geração da simulação | -            |
| **data.key**            | string | Chave única da simulação        | -            |
| **data.status**         | string | _finished_                      | -            |
| **data.type**           | string | _debt_                          | -            |

### Objeto Data
| Campo                                   | Tipo   | Descrição                                                                                                                     | Máx. Caract. |
|-----------------------------------------|--------|-------------------------------------------------------------------------------------------------------------------------------|--------------|
| **annual_cet**                          | float  | Custo efetivo total expresso em decimal ao ano                                                                                | -            |
| **assignment_amount**                   | float  | Valor de aquisição da operação de crédito                                                                                     | -            |
| **cet**                                 | float  | Custo efetivo total expresso em decimal ao mês                                                                                | -            |
| **contract_fee_amount**                 | float  | Fee da QI Tech cobrado na operação                                                                                            | -            |
| **contract_fees**                       | object | **[Objeto Contract Fees](#objeto-contract-fees)** - Lista de Fee's da QI Tech cobrados na operação                            | -            |
| **credit_operation_type**               | enum   | **[Enumerador Credit Operation Type](#enumerador-credit-operation-type)** - Tipo do contrato de crédito                       | -            |
| **disbursed_issue_amount**              | float  | Valor desembolsado na operação de crédito                                                                                     | -            |
| **disbursement_date**                   | date   | Data do desembolso da operação                                                                                                | -            |
| **disbursement_options**                | list   | Lista de opções de desembolso da operação (os valores financeiros da operação podem variar de acordo com o dia do desembolso) | -            |
| **external_contract_fee_amount**        | float  | Valor do Fee cobrado na operação rebatido pela QI ao parceiro                                                                 | -            |
| **external_contract_fees**              | list   | **[Objeto Contract Fees](#objeto-contract-fees)** - Lista de Fee's cobrados na operação rebatidos pela QI ao parceiro         | -            |
| **final_disbursement_amount**           | float  | Valor efetivamente desembolsado para o devedor                                                                                | -            |
| **installments**                        | list   | **[Objeto Installments](#objeto-installments)** - Parcelas da operação                                                        | -            |
| **interest_grace_period**               | int    | Carência de juros (em meses)                                                                                                  | -            |
| **interest_payment_month_period**       | int    | Frequência da cobrança de juros nas parcelas (em meses)                                                                       | -            |
| **interest_type**                       | enum   | **[Enumerador Interest Type](#enumerador-interest-type)** - Método de amortização e forma de cálculo de juros                 | -            |
| **iof_amount**                          | float  | Valor total do IOF (composto pela soma do IOF Base e IOF Total)                                                               | -            |
| **issue_amount**                        | float  | Valor de emissão/nominal da operação de crédito                                                                               | -            |
| **issue_date**                          | date   | Data da emissão do cotrato da operação                                                                                        | -            |
| **net_external_contract_fee_amount**    | float  | Valor líquido do Fee cobrado na operação rebatido pela QI ao parceiro                                                         | -            |
| **operation_type**                      | enum   | **[Enumerador Operation Type](#enumerador-operation-type)**                                                                   | -            |
| **post_fixed_interest_base**            | enum   | **[Enumerador Interest Base](#enumerador-interest-base)** - Base de cálculo de juros                                          | -            |
| **post_fixed_interest_rate**            | object | **[Objeto Interest Rate](#objeto-interest-rate)** - Indexador de juros pós-fixados do contrato                                | -            |
| **prefixed_interest_rate**              | object | **[Objeto Interest Rate](#objeto-interest-rate)** - Taxa de juros Nominal pré-fixada do contrato                              | -            |
| **principal_amortization_month_period** | int    | Frequência da cobrança de principal nas parcelas (em meses)                                                                   | -            |
| **principal_grace_period**              | int    | Período carência de principal (em meses)                                                                                      | -            |
| **requester_key**                       | string | Chave única identificadora do parceiro dentro da QI.                                                                          | -            |
| **total_pre_fixed_amount**              | float  | Total de juros pago pelo devedor na operação de crédito                                                                       | -            |

### Objeto Contract Fees
| Campo           | Tipo  | Descrição                                                                                           | Máx. Caract. |
|-----------------|-------|-----------------------------------------------------------------------------------------------------|--------------|
| **amount**      | float | Valor do Fee (em percentual ou valor absoluto, a depender do valor informado no campo _amount_type_ | -            |
| **amount_type** | enum  | **[Enumeradores amount_type](#enumerador-amount-type)** - Unidade do valor do Fee                   | -            |
| **fee_amount**  | float | Valor absoluto do Fee cobrado na operação                                                           | -            |
| **fee_type**    | enum  | **[Enumerador Fee Type](#enumerador-fee-type)** - Tipo do Fee cobrado na operação                   | -            |

### Objeto Installments
| Campo                             | Tipo    | Descrição                                                                      | Máx. Caract. |
|-----------------------------------|---------|--------------------------------------------------------------------------------|--------------|
| **business_due_date**             | date    | Data do vencimento em dia útil da parcela                                      | -            |
| **calendar_days**                 | int     | Quantos dias corridos entre uma parcela e outra                                | -            |
| **due_date**                      | date    | Data do vencimento em dia corrido da parcela                                   | -            |
| **due_principal**                 | float   | Principal remanescente na data de vencimento da parcela antes de seu pagamento | -            |
| **has_interest**                  | boolean | _true_ - Indicador de incidência de juros na parcela                           | -            |
| **installment_number**            | int     | Número da parcela                                                              | -            |
| **post_fixed_amount**             | float   | Valor de juros pós-fixado pago na parcela                                      | -            |
| **pre_fixed_amount**              | float   | Valor de juros pré-fixado pago na parcela                                      | -            |
| **principal_amortization_amount** | float   | Valor de amortização pago na parcela                                           | -            |
| **tax_amount**                    | float   | IOF Base da parcela                                                            | -            |
| **total_amount**                  | float   | Valor total da parcela                                                         | -            |
| **workdays**                      | int     | Quantos dias úteis entre uma parcela e outra                                   | -            |

### Objeto Interest Rate
| Campo             | Descrição                                                                             | Máx. Caract. |
|-------------------|---------------------------------------------------------------------------------------|--------------|
| **annual_rate**   | Taxa de juros pré/pós expressa em decimal ao ano                                      | -            |
| **daily_rate**    | Taxa de juros pré/pós expressa em decimal ao dia                                      | -            |
| **interest_base** | **[Enumerador Interest Base](#enumerador-interest-base)** - Base de cálculo de juros | -            |
| **monthly_rate**  | Taxa de juros pré/pós expressa em decimal ao mês                                      | -            |

# Enumeradores

### Enumerador _Person Type_
| Enumerador             | Descrição             |
|------------------------|-----------------------|
| **legal**   | Pessoa juridica        |
| **natural**    | Pesso física    |

### Enumerador _Account Type_
| Enumerador             | Descrição             |
|------------------------|-----------------------|
| **checking_account**   | Conta corrente        |
| **deposit_account**    | Conta de depósito     |
| **guaranteed_account** | Conta de garantia     |
| **investment_account** | Conta de investimento |
| **payment_account**    | Conta de pagamento    |
| **saving_account**     | Conta poupança        |
| **salary_account**     | Conta salário         |

### Enumerador _Amount Type_
| Enumerador             | Descrição             |
|------------------------|-----------------------|
| **absolute**           | Valor absoluto        |
| **percentage**         | Valor percentual      |

### Enumerador _Interest Type_
| Enumerador           | Descrição                                                                                                                                                                |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **pre_price_days**   | Método de amortização Price (parcelas iguais) com cálculo do juros pré-fixado ao dia                                                                                     |
| **pre_price**        | Método de amortização Price (parcelas iguais) com cálculo do juros pré-fixado em períodos fixos (30 dias)                                                                |
| **pre_sac**          | Método de amortização SAC (amortização constante) com cálculo do juros pré-fixado ao dia                                                                                 |
| **post_sac**         | Método de amortização SAC (amortização constante) com cálculo do juros baseado em uma taxa pré-fixada + indexador pós-fixado (cdi, ipca ou igpm) ao dia                  |
| **post_price**       | Método de amortização Price (parcelas iguais) com cálculo do juros baseado em uma taxa pré-fixada + indexador pós-fixado (cdi, ipca ou igpm) em períodos fixos (30 dias) |
| **post_price_days**  | Método de amortização Price (parcelas iguais) com cálculo do juros baseado em uma taxa pré-fixada + indexador pós-fixado (cdi, ipca ou igpm) ao dia                      |

### Enumerador _Credit Operation Type_
| Enumerador    | Descrição                      |
|---------------|--------------------------------|
| **ccb**       | Cédula de Crédito Bancário     |
| **cce**       | Cédula de Crédito à Exportação |
| **cci**       | Cédula de Crédito Imobiliário  |
| **nce**       | Nota de Crédito à Exportação   |

### Enumerador _Interest Base_
| Enumerador            | Descrição                                                                 |
|-----------------------|---------------------------------------------------------------------------|
| **workdays**          | Base de cálculo de juros em dias úteis considerando um ano de 252 dias    |
| **calendar_days**     | Base de cálculo de juros em dias corridos considerando um ano de 360 dias |
| **calendar_days_365** | Base de cálculo de juros em dias corridos considerando um ano de 365 dias |

### Enumerador _Fee Type_
Cada tipo de fee deve ser previamente habilitado e configurado pela QI Tech

| Enumerador            | Descrição                                                                  |
|-----------------------|----------------------------------------------------------------------------|
| **tac**               | Tarifa de abertura de cadastro                                             |
| **spread**            | Ágio cobrado no valor de aquisição da operação de crédito                  |
| **warranty_analysis** | Tarifa de análise de garantias                                             |
| **ted_fee**           | Tarifa de TED                                                              |
| **spread_ted_fee**    | Ágio da tarifa de TED cobrado no valor de aquisição da operação de crédito |

---

# Simulação de dívida novo

URL: /documentation/emissao_de_divida/simulacao_de_divida_novo

Na QI Tech disponibilizamos aos nossos clientes a possibilidade de simular os valores uma operação de crédito antes da
sua emissão de fato. A simulação segue o mesmo padrão da solicitação de emissão de dívida, porém não é necessário
informar os dados cadastrais e de conta de desembolso do devedor. 

## Request

No exemplo abaixo, esta descrita uma solicitação de simulação de dívida.

ENDPOINT /v2/credit_operation/simulation
MÉTODO POST

Request Body

**Data de vencimento e valor da parcela**

```json
{
    "credit_operation_type": "ccb",
    "disbursed_issue_amount": 2800,
    "disbursement_date": "2025-09-24",
    "first_due_date": "2025-10-24",
    "force_installments_on_workdays": true,
    "interest_type": "pre_price_days",
    "issuer_person_type": "natural",
    "monthly_interest_rate": 0.04488,
    "number_of_installments": 12,
    "principal_amortization_month_period": 1
}
```

**Valor desembolsado e parcelas**

 ```json
{
    "credit_operation_type": "ccb",
    "disbursed_issue_amount": 460,
    "disbursement_date": "2025-09-24",
    "first_due_date": "2025-10-24",
    "force_installments_on_workdays": true,
    "interest_type": "pre_price_days",
    "issuer_person_type": "natural",
    "number_of_installments": 3,
    "principal_amortization_month_period": 1,
    "interest_base": "calendar_days_365",
    "installments": [
      {
        "due_date": "2026-02-26",
        "amount": 137.48
      },
      {
        "due_date": "2026-03-26",
        "amount": 180.56
      },
      {
        "due_date": "2026-04-27",
        "amount": 180.56
      }
    ]
  }
 ```

## Response

STATUS 200

Response Body

```json
{
  "additional_iof": 0.14,
  "annual_cet": 145.08,
  "assignment_amount": 36.21,
  "base_iof": 0.1,
  "cet": 7.76,
  "disbursed_amount": 35.9,
  "disbursement_date": "2024-09-06",
  "fees": [
    {
      "amount": 0.0,
      "fee_amount": 0.0,
      "amount_type": "absolute",
      "fee_type": "tac",
      "type": "external"
    },
    {
      "amount": 0.0,
      "fee_amount": 0.0,
      "amount_type": "absolute",
      "fee_type": "spread",
      "type": "external"
    },
    {
      "amount": 0.2,
      "fee_amount": 0.07,
      "amount_type": "percentage",
      "fee_type": "spread",
      "type": "internal"
    }
  ],
  "first_due_date": "2024-09-25",
  "installments": [
    {
      "due_date": "2024-09-25",
      "amount": 19.5,
      "due_principal": 36.14,
      "due_interest": 0.0,
      "has_interest": true,
      "period": 0.6129032258064516,
      "period_workdays": 0.6190476190476191,
      "calendar_days": 19,
      "workdays": 13,
      "installment_number": 1,
      "period_to_disbursement": 0.6129032258064516,
      "prefixed_amount": 1.58227236,
      "period_workdays_to_disbursement": 1.0,
      "calendar_days_to_disbursement": 19,
      "workdays_to_disbursement": 13,
      "tax_amount": 0.02791582,
      "principal_amortization_amount": 17.91772764
    },
    {
      "due_date": "2024-10-25",
      "amount": 19.5,
      "due_principal": 18.22227236,
      "due_interest": 0.0,
      "has_interest": true,
      "period": 1.0,
      "period_workdays": 1.0,
      "calendar_days": 30,
      "workdays": 22,
      "installment_number": 2,
      "period_to_disbursement": 1.6129032258064515,
      "prefixed_amount": 1.27772764,
      "period_workdays_to_disbursement": 2.0,
      "calendar_days_to_disbursement": 49,
      "workdays_to_disbursement": 35,
      "tax_amount": 0.07321709,
      "principal_amortization_amount": 18.22227236
    }
  ],
  "interest_type": "pre_price_days",
  "issue_amount": 36.14,
  "prefixed_interest_rate": {
    "interest_base": "calendar_days",
    "annual_rate": 1.25219159,
    "daily_rate": 0.00225783,
    "monthly_rate": 0.07
  },
  "tax_configuration": {
    "additional_rate": 0.0038,
    "base_rate": 0.000082
  },
  "total_iof": 0.24
}

```

## Definições

### Request Body

### Payload
| Campo  | Tipo   | Descrição | Máx. Caract. |
|---|--- |---|---|
| **credit_operation_type**                 | enum    | **[Enumerador Credit Operation Type](#enumerador-credit-operation-type)** - Tipo do contrato de crédito      | -            |
| **disbursed_issue_amount**                | float   | Valor de emissão/nominal da operação de crédito      | -            |
| **disbursement_date**                     | date    | Data do desembolso da operação      | -            |
| **first_due_date**                        | date    | Data de vencimento da primeira parcela      | -            |
| **force_installments_on_workdays**        | boolean | _true_ - Indicador de parcelas agendadas em dias úteis     | -            |
| **interest_type**                         | enum    | **[Enumerador Interest Type](#enumerador-interest-type)** - Método de amortização e forma de cálculo de juros      | -            |
| **issuer_person_type**                    | enum    | **[Enumerador Person Type](#enumerador-person-type)**      | -            |
| **monthly_interest_rate**                 | float   | Taxa de juros mensal pré-fixada do contrato      | -            |
| **number_of_installments**                | int     | Número de parcelas da operação de crédito      | -            |
| **principal_amortization_month_period**   | int     | Quantidade de meses de amortização do principal      | -            |
| **installments**                          | list    | **[Objeto Installments](#objeto-installments)** - Parcelas da operação      | -            |

### Response Body

### Payload
| Campo                                   | Tipo   | Descrição                                                                                                                     | Máx. Caract. |
|-----------------------------------------|--------|-------------------------------------------------------------------------------------------------------------------------------|--------------|
| **annual_cet**                          | float  | Custo efetivo total expresso em decimal ao ano                                                                                | -            |
| **assignment_amount**                   | float  | Valor de aquisição da operação de crédito                                                                                     | -            |
| **cet**                                 | float  | Custo efetivo total expresso em decimal ao mês                                                                                | -            |
| **fees**                                | object | **[Objeto Fees](#objeto-fees)** - Lista de Fee's da QI Tech cobrados na operação                            | -            |
| **disbursed_amount**                    | float  | Valor desembolsado na operação de crédito                                                                                     | -            |
| **disbursement_date**                   | date   | Data do desembolso da operação                                                                                                | -            |
| **installments**                        | list   | **[Objeto Installments Response](#objeto-installments-response)** - Parcelas da operação                                                        | -            |
| **interest_type**                       | enum   | **[Enumerador Interest Type](#enumerador-interest-type)** - Método de amortização e forma de cálculo de juros                 | -            |
| **additional_iof**                      | float  | Valor de IOF adicional                                                                                                        | -            |
| **base_iof**                            | float  | Valor do IOF Base                                                                                                             | -            |
| **total_iof**                           | float  | Valor do IOF Total                                                                                                            | -            |
| **issue_amount**                        | float  | Valor de emissão/nominal da operação de crédito                                                                               | -            |
| **tax_configuration**                   | object | **[Objeto Tax Configuration](#objeto-tax-configuration)** - Valores das alíquotas                                             | -            |
| **first_due_date**                      | date   | Data de vencimento da primeira parcela                                                                                        | -            |
| **prefixed_interest_rate**              | object | **[Objeto Interest Rate](#objeto-interest-rate)** - Taxa de juros Nominal pré-fixada do contrato                              | -            |

### Objeto Fees
| Campo           | Tipo  | Descrição                                                                                           | Máx. Caract. |
|-----------------|-------|-----------------------------------------------------------------------------------------------------|--------------|
| **amount**      | float | Valor do Fee (em percentual ou valor absoluto, a depender do valor informado no campo _amount_type_)| -            |
| **amount_type** | enum  | **[Enumeradores amount_type](#enumerador-amount-type)** - Unidade do valor do Fee                   | -            |
| **fee_amount**  | float | Valor absoluto do Fee cobrado na operação                                                           | -            |
| **fee_type**    | enum  | **[Enumerador Fee Type](#enumerador-fee-type)** - Tipo do Fee cobrado na operação                   | -            |
| **type**        | enum  | **[Enumerador Origin Type](#enumerador-origin-type)** - Origem do Fee cobrado na operação                         | -            |

### Objeto Installments Request
| Campo                             | Tipo    | Descrição                                                                      | Máx. Caract. |
|-----------------------------------|---------|--------------------------------------------------------------------------------|--------------|
| **due_date**                      | date    | Data do vencimento em dia corrido da parcela                                   | -            |
| **total_amount**                  | float   | Valor total da parcela                                                         | -            |

### Objeto Installments Response
| Campo                             | Tipo    | Descrição                                                                      | Máx. Caract. |
|-----------------------------------|---------|--------------------------------------------------------------------------------|--------------|
| **calendar_days**                 | int     | Quantos dias corridos entre uma parcela e outra                                | -            |
| **due_date**                      | date    | Data do vencimento em dia corrido da parcela                                   | -            |
| **due_principal**                 | float   | Principal remanescente na data de vencimento da parcela antes de seu pagamento | -            |
| **has_interest**                  | boolean | _true_ - Indicador de incidência de juros na parcela                           | -            |
| **installment_number**            | int     | Número da parcela                                                              | -            |
| **prefixed_amount**               | float   | Valor de juros pré-fixado pago na parcela                                      | -            |
| **principal_amortization_amount** | float   | Valor de amortização pago na parcela                                           | -            |
| **tax_amount**                    | float   | IOF Base da parcela                                                            | -            |
| **amount**                        | float   | Valor total da parcela                                                         | -            |
| **due_interest**                  | float     | Juros remanescente após a data de vencimento da parcela antes de seu pagamento                                   | -            |
| **period**                        | float     | Período da parcela | -            |
| **period_workdays**               | float     | Período da parcela em dias úteis | -            |
| **period_to_disbursement**        | float     | Período até o desembolso | -            |
| **period_workdays_to_disbursement**| float     | Período em dias úteis até o desembolso | -            |
| **calendar_days_to_disbursement** | int     | Quantos dias corridos até o desembolso | -            |
| **workdays**                      | int     | Quantos dias úteis entre uma parcela e outra | -            |
| **workdays_to_disbursement**      | int     | Quantos dias úteis até o desembolso | -            |

### Objeto Interest Rate
| Campo             | Descrição                                                                             | Máx. Caract. |
|-------------------|---------------------------------------------------------------------------------------|--------------|
| **annual_rate**   | Taxa de juros pré/pós expressa em decimal ao ano                                      | -            |
| **daily_rate**    | Taxa de juros pré/pós expressa em decimal ao dia                                      | -            |
| **interest_base** | **[Enumerador Interest Base](#enumerador-interest-base)** - Base de cálculo de juros  | -            |
| **monthly_rate**  | Taxa de juros pré/pós expressa em decimal ao mês                                      | -            |

### Objeto Tax Configuration
| Campo                 | Descrição                                                                             | Máx. Caract. |
|-----------------------|---------------------------------------------------------------------------------------|--------------|
| **base_rate**         | Valor da alíquota base                                                                | -            |
| **additional_rate**   | Valor da alíquota adicional                                                           | -            |

# Enumeradores

### Enumerador _Person Type_
| Enumerador             | Descrição             |
|------------------------|-----------------------|
| **legal**              | Pessoa juridica       |
| **natural**            | Pesso física          |

### Enumerador _Account Type_
| Enumerador             | Descrição             |
|------------------------|-----------------------|
| **checking_account**   | Conta corrente        |
| **deposit_account**    | Conta de depósito     |
| **guaranteed_account** | Conta de garantia     |
| **investment_account** | Conta de investimento |
| **payment_account**    | Conta de pagamento    |
| **saving_account**     | Conta poupança        |
| **salary_account**     | Conta salário         |

### Enumerador _Amount Type_
| Enumerador             | Descrição             |
|------------------------|-----------------------|
| **absolute**           | Valor absoluto        |
| **percentage**         | Valor percentual      |

### Enumerador _Interest Type_
| Enumerador           | Descrição                                                                                                                                                                |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **pre_price_days**   | Método de amortização Price (parcelas iguais) com cálculo do juros pré-fixado ao dia                                                                                     |
| **pre_price**        | Método de amortização Price (parcelas iguais) com cálculo do juros pré-fixado em períodos fixos (30 dias)                                                                |
| **pre_sac**          | Método de amortização SAC (amortização constante) com cálculo do juros pré-fixado ao dia                                                                                 |
| **post_sac**         | Método de amortização SAC (amortização constante) com cálculo do juros baseado em uma taxa pré-fixada + indexador pós-fixado (cdi, ipca ou igpm) ao dia                  |
| **post_price**       | Método de amortização Price (parcelas iguais) com cálculo do juros baseado em uma taxa pré-fixada + indexador pós-fixado (cdi, ipca ou igpm) em períodos fixos (30 dias) |
| **post_price_days**  | Método de amortização Price (parcelas iguais) com cálculo do juros baseado em uma taxa pré-fixada + indexador pós-fixado (cdi, ipca ou igpm) ao dia                      |

### Enumerador _Credit Operation Type_
| Enumerador    | Descrição                      |
|---------------|--------------------------------|
| **ccb**       | Cédula de Crédito Bancário     |
| **cce**       | Cédula de Crédito à Exportação |
| **cci**       | Cédula de Crédito Imobiliário  |
| **nce**       | Nota de Crédito à Exportação   |

### Enumerador _Interest Base_
| Enumerador            | Descrição                                                                 |
|-----------------------|---------------------------------------------------------------------------|
| **workdays**          | Base de cálculo de juros em dias úteis considerando um ano de 252 dias    |
| **calendar_days**     | Base de cálculo de juros em dias corridos considerando um ano de 360 dias |
| **calendar_days_365** | Base de cálculo de juros em dias corridos considerando um ano de 365 dias |

### Enumerador _Fee Type_
Cada tipo de fee deve ser previamente habilitado e configurado pela QI Tech

| Enumerador            | Descrição                                                                  |
|-----------------------|----------------------------------------------------------------------------|
| **tac**               | Tarifa de abertura de cadastro                                             |
| **spread**            | Ágio cobrado no valor de aquisição da operação de crédito                  |
| **warranty_analysis** | Tarifa de análise de garantias                                             |
| **ted_fee**           | Tarifa de TED                                                              |
| **spread_ted_fee**    | Ágio da tarifa de TED cobrado no valor de aquisição da operação de crédito |

### Enumerador _Origin Type_
Cada tipo de fee deve ser previamente habilitado e configurado pela QI Tech

| Enumerador            | Descrição                                                                  |
|-----------------------|----------------------------------------------------------------------------|
| **internal**          | Tarifa de origem interna                                                   |
| **external**          | Tarifa de origem externa                                                   |

---

# Simulando erros em Sandbox

URL: /documentation/emissao_de_divida/simulando_erros

Esta página vai auxiliar a simular erros em ambiente Sandbox.

# Dados para simular erro no desembolso

Utilizando os seguintes dados bancários, você consegue simular um erro no desembolso de uma operação para a reapresentação de dados bancários.

```json
account_digit: 0
account_number: 11581339
bank_code: 001
branch_number: 2874
document_number: Ajustar conforme documento de tomador
Nome: Ajustar conforme nome de tomador
```

# Dados para simular erros utilizando a assinatura no QI Sign

Utilizando os seguintes números no início do documento do tomador, você consegue simular erros fluxo de assinatura do QI Sign.

Início de documento:
```json
0: Fraude detectada na assinatura
8: Falhou na validação de prova de vida
9: Validação facial não alcançou a pontuação mínima permitida
```

---

# Possíveis status de uma dívida

URL: /documentation/emissao_de_divida/status_de_uma_divida

## Máquina de estados
Após realizar a emissão do contrato de crédito, o mesmo pode ser acompanhado através dos Webhooks da plataforma QI Tech.

Os estados que o contrato passa estão descritos abaixo:

**waiting_signature**

Após emitido, o primeiro estado em que um contrato se encontra é o de "aguardando assinatura", esse status permanece até a finalização do processo de assinaturas.

**signature_finished**

Esse é um estado transitório, após receber a última assinatura o contrato passa momentaneamente para o status "signature_finished", quando o webhook é disparado e transita para o próximo estado imediatamente.

**signed** 

Após assinado o contrato fica com status "assinado".

**issued**

Este é um estado transitório, na data de desembolso de um contrato ele entra no status "issued" aguardando o desembolso para transitar para o próximo estado.

**disbursed**

Esse é um estado transitório, após o desembolso ser realizado o contrato passa momentaneamente para o status "disbursed", quando o webhook é disparado e transita para o próximo estado imediatamente.

**opened**

Após desembolsado o contrato fica com status "em aberto" - esse é o último estado caso a QI não seja o agente de cobrança da operação.

**settled**

Quando a QI Tech é o agente de cobrança da operação de crédito, o contrato é acompanhado até ser quitado, após o pagamento da última parcela seu status muda para "settled" e um Webhook é disparado.

**canceled**

Este estado, indica que ocorreu algum erro no fluxo da operação, como por exemplo falha no desembolso do crédito ao devedor ou então a não assinatura do contrato em tempo hábil.

**canceled_permanently**

Quando existir alguma garantia/averbação atrelada ao contrato, este será o estado final, que significará que a garantia/averbação foi liberada e o contrato foi permanentemente cancelado.

---

# Catálogo de Erros

URL: /documentation/erros/catalogo_de_erros

Todas as APIs da QI Tech retornam erros em um formato padronizado:

```json
{
  "title": "HTTP Status code name",
  "description": "An english description of the error",
  "translation": "Uma descrição em português do erro",
  "code": "ERROR_UNIQUE_CODE"
}
```

## Erros Globais (GDF)

Erros comuns a todas as APIs da plataforma.

| Código HTTP | Código do Erro | Título | Descrição | Resolução |
|-|-|-|-|-|
| 400 | GDF000003 | Bad Request | No API Client Key received | Inclua o header `API-CLIENT-KEY` com sua chave de API na requisição. |
| 401 | GDF000014 | QI Unauthenticated | Failed while decoding the authentication token | Verifique se o token JWT está sendo assinado corretamente com sua chave privada EC512. Consulte o [teste de autenticação](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2). |
| 404 | GDF000018 | Not Found | No ClientIntegration found for api_client_key | Verifique se a `API-CLIENT-KEY` enviada corresponde à chave cadastrada no painel QI Tech. |

## Erros de Homologação do Emissor (ISS)

| Código HTTP | Código do Erro | Título | Descrição |
|-|-|-|-|
| 400 | ISS000003 | Bad Request | Emissor já existe na base de dados. |
| 404 | ISS000004 | Not Found | Representante do emissor não encontrado. |
| 404 | ISS000005 | Not Found | Conta bancária não encontrada. |
| 404 | ISS000006 | Not Found | Documento do emissor não encontrado. |
| 404 | ISS000007 | Not Found | Documento do representante do emissor não encontrado. |
| 404 | ISS000008 | Not Found | Contato do emissor não encontrado. |
| 404 | ISS000009 | Not Found | Emissor não encontrado. |
| 404 | ISS000010 | Not Found | Grupo de assinantes não encontrado. |
| 400 | ISS000011 | Bad Request | Emissor deve estar no estado in_filling para permitir esta ação. |
| 400 | ISS000012 | Bad Request | Não é permitido deletar a conta principal, defina uma nova conta principal primeiro. |
| 400 | ISS000013 | Bad Request | Não é permitido deletar o contato principal, defina um novo contato principal primeiro. |
| 400 | ISS000014 | Bad Request | Emissor precisa ter ao menos uma informação de contato. |
| 400 | ISS000015 | Bad Request | Acesso aos dados do emissor já foi concedido. |
| 400 | ISS000016 | Bad Request | Falha ao enviar mensagem ao emissor, tente novamente. |
| 400 | ISS000017 | Bad Request | Link inválido. |
| 400 | ISS000018 | Bad Request | Documento enviado é inválido ou de baixa qualidade. |

## Erros de Homologação do Investidor (INV)

| Código HTTP | Código do Erro | Título | Descrição |
|-|-|-|-|
| 400 | INV000003 | Bad Request | Investidor já existe na base de dados. |
| 404 | INV000004 | Not Found | Representante do investidor não encontrado. |
| 404 | INV000005 | Not Found | Conta bancária não encontrada. |
| 404 | INV000006 | Not Found | Documento do investidor não encontrado. |
| 404 | INV000007 | Not Found | Documento do representante do investidor não encontrado. |
| 404 | INV000008 | Not Found | Contato do investidor não encontrado. |
| 404 | INV000009 | Not Found | Investidor não encontrado. |
| 404 | INV000010 | Not Found | Grupo de assinantes não encontrado. |
| 400 | INV000011 | Bad Request | Investidor deve estar no estado in_filling para permitir esta ação. |
| 400 | INV000012 | Bad Request | Não é permitido deletar a conta principal, defina uma nova conta principal primeiro. |
| 400 | INV000013 | Bad Request | Não é permitido deletar o contato principal, defina um novo contato principal primeiro. |
| 400 | INV000014 | Bad Request | Investidor precisa ter ao menos uma informação de contato. |
| 400 | INV000015 | Bad Request | Acesso aos dados do investidor já foi concedido. |
| 400 | INV000016 | Bad Request | Falha ao enviar mensagem ao investidor, tente novamente. |
| 400 | INV000017 | Bad Request | Link inválido. |
| 400 | INV000018 | Bad Request | Documento enviado é inválido ou de baixa qualidade. |

## Erros de Emissão de Nota Comercial (COM)

| Código HTTP | Código do Erro | Título | Descrição |
|-|-|-|-|
| 400 | COM000001 | Bad Request | Documento fornecido não é válido. |
| 400 | COM000002 | Bad Request | Tenant precisa ser configurado antes de utilizar este endpoint. |
| 409 | COM000003 | Conflict | Configuração para este tenant já existe. |
| 400 | COM000004 | Bad Request | Investidor com a chave informada não permitido. Verifique o cadastro. |
| 400 | COM000005 | Bad Request | Emissor com a chave informada não permitido. Verifique o cadastro. |
| 400 | COM000006 | Bad Request | Operação com mais de um investidor não disponível. |
| 404 | COM000007 | Not Found | Operação não encontrada. |
| 403 | COM000008 | Forbidden | Operação não pertence ao tenant. |
| 400 | COM000010 | Bad Request | Operação não pode ser atualizada fora do status in_filling. |

## Erros de Integralização (INT)

| Código HTTP | Código do Erro | Título | Descrição |
|-|-|-|-|
| 400 | INT000001 | Bad Request | Tipo de integralização inválido. |
| 404 | INT000002 | Not Found | Integralização não encontrada. |
| 400 | INT000003 | Bad Request | Integralização não pode ser atualizada fora do status in_filling. |
| 400 | INT000004 | Bad Request | Tipo de pagamento inválido. |

---

# Aditamento

URL: /documentation/escrituracao/aditamento/conceito

## Visão geral

Aditamento é o processo de alterar as condições de um título já emitido. Depois que a Nota Comercial foi assinada e emitida, qualquer mudança nas condições pactuadas — repactuar o fluxo de pagamento, substituir uma garantia, incluir ou remover um avalista, corrigir o número da emissão — precisa ser formalizada em um termo aditivo assinado pelas partes.

A QI Tech recebe esse pedido via API, valida a elegibilidade do título, calcula o novo fluxo, gera o termo aditivo, cobra a taxa do serviço, coleta as assinaturas e só então aplica as alterações no título. O resultado é um evento rastreável, com `status` próprio, histórico de transições e os documentos assinados disponíveis para download.

O integrador inicia o fluxo com uma chamada e acompanha o restante por consulta. As etapas intermediárias — geração do termo, emissão do boleto, envio do envelope de assinatura, aplicação das alterações — são orquestradas internamente pela QI Tech.

## O que pode ser aditado

Cada aditamento carrega uma ou mais alterações, no campo `changes`. Os cinco tipos ficam em `changes[].type`:

- `financial_flow` (fluxo financeiro) — repactuação do cronograma: novas datas de vencimento, novos valores e/ou nova taxa de juros.
- `collateral` (garantia) — inclusão ou remoção de uma garantia do título.
- `related_party` (parte relacionada) — inclusão, alteração ou remoção de avalista, devedor solidário, fiel depositário e demais papéis.
- `issue_number` (número da emissão) — correção do número da emissão.
- `term_clause` (cláusula do termo) — regeração do documento com campos livres preenchidos pelo solicitante.

Um mesmo aditamento pode combinar vários tipos. As alterações são aplicadas em conjunto: ou todas valem, ou nenhuma vale.

## Conceitos-chave

- **`financial_base_date`** — data em que o aditamento passa a valer e a âncora de todo o cálculo. O saldo devedor é apurado nessa data e o novo fluxo parte dela. Aditamento com data base no passado é recusado, salvo operações com origem de tombamento.
- **`outstanding_balance`** (saldo devedor) — calculado internamente na `financial_base_date` e devolvido na simulação, na validação e na consulta. O integrador não precisa calcular saldo devedor do seu lado.
- **Fechamento (`closing`)** — em uma repactuação de fluxo, a QI Tech confere se o novo cronograma fecha contra o valor presente do título dentro de uma tolerância. Um fluxo que não fecha faz o aditamento nascer recusado, com o `difference` e a `tolerance` na resposta.
- **Termo aditivo** — o documento que formaliza a alteração. Pode ser **gerado pela QI Tech** a partir dos dados do aditamento, ou **enviado pronto pelo integrador** no array `documents`. A escolha muda o caminho que o aditamento percorre (veja [Regras de Negócio](./regras-de-negocio.md)).
- **Cobrança** — o aditamento tem uma taxa, cobrada por boleto. O pagamento é o que libera o envio do termo para assinatura. O valor segue a configuração comercial do seu contrato e vem na simulação, em `charge_amount`.
- **Envelope de assinatura** — o conjunto de signatários do termo. Os signatários vêm dos grupos de assinatura cadastrados na operação; uma parte relacionada incluída pelo próprio aditamento também pode ser eleita signatária.
- **Um aditamento por vez** — um título só admite um aditamento em andamento. Enquanto o anterior não chega a um estado terminal, uma nova criação é recusada com `AMD000031`.

## O ciclo de vida

Um aditamento atravessa a esteira uma vez, e cada parada espera por uma coisa só:

| `status` | O que está acontecendo |
| --- | --- |
| `created` | Criado e roteado. Estado transitório. |
| `validation_failed` | Recusado na validação. Nada foi cobrado nem assinado. Estado terminal. |
| `pending_manual_approval` | O termo foi enviado pronto pelo integrador e aguarda conferência da QI Tech. |
| `pending_term_generation` | A QI Tech está gerando o termo aditivo. |
| `pending_charge_settlement` | Boleto emitido, aguardando o pagamento da taxa. |
| `pending_signature` | Montando e enviando o envelope de assinatura. |
| `pending_signature_confirmation` | Envelope enviado, aguardando os signatários. |
| `pending_application` | Aplicando as alterações no título. |
| `applied` | Alterações aplicadas. Estado terminal. |
| `application_failed` | Falha ao aplicar. Estado terminal até intervenção. |
| `canceled` | Cancelado ou recusado. O motivo fica em `status_reason`. Estado terminal. |

:::info Acompanhamento por consulta
Não há webhook dedicado às transições de status do aditamento. Acompanhe pelo endpoint de [consulta](./endpoints/consultar-aditamento.md) — o campo `status_history` traz cada transição com data, ator e motivo.
:::

## Próximos passos

- [Regras de Negócio](./regras-de-negocio.md) — elegibilidade, fechamento, assinatura e cancelamento.
- [Tipos de Alteração](./tipos-de-alteracao.md) — o formato de `new_value` para cada `type`.
- [Simular Aditamento](./endpoints/simular-aditamento.md) — o ensaio, sem criar nada.
- [Criar Aditamento](./endpoints/criar-aditamento.md) — o disparo do rito.
- [Exemplos](./exemplos.md) — casos completos de ponta a ponta.

---

# Baixar Documento

URL: /documentation/escrituracao/aditamento/endpoints/baixar-documento

Devolve o conteúdo de um documento do aditamento em base64 — o termo aditivo gerado pela QI Tech, o termo que você enviou, ou a versão assinada.

---

## **Request**

ENDPOINT /security_amendment/amendment/ AMENDMENT-KEY /document/ DOCUMENT-KEY
MÉTODO GET

### **Path Params**

| Campo | Tipo | Descrição | Caracteres |
| --- | --- | --- | --- |
| `AMENDMENT-KEY` | string | Chave única do aditamento (UUID v4). | 36 |
| `DOCUMENT-KEY` | string | Chave do documento (UUID v4), obtida em `documents[].document_key` na [consulta](./consultar-aditamento.md). | 36 |

### **Query Params**

| Campo | Tipo | Obrigatório | Padrão | Descrição |
| --- | --- | --- | --- | --- |
| `is_signed` | boolean | Não | `false` | Quando `true`, devolve a **versão assinada** do documento. |

---

## **Response**

STATUS 200

```json
{
  "document_base64": "JVBERi0xLjQKJeLjz9MKMyAwIG9iago8PC9UeXBlL1BhZ2UvTWVkaWFCb3hbMCAwIDU5NSA4NDJd..."
}
```

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `document_base64` | string | Conteúdo do arquivo em base64. |

:::caution A versão assinada só existe depois da assinatura
`is_signed=true` em um documento que ainda não foi assinado retorna `AMD000038`. Confira o campo `documents[].signed_file_key` na consulta: ele só é preenchido quando a versão assinada está disponível.
:::

---

## **Erros**

| Status | Código | Descrição |
| --- | --- | --- |
| 404 | `AMD000017` | Aditamento não encontrado. |
| 403 | `AMD000018` | O aditamento não pertence ao seu tenant. |
| 404 | `AMD000037` | Documento não encontrado neste aditamento. |
| 422 | `AMD000038` | O documento ainda não tem versão assinada. |

## Veja também

- [Consultar Aditamento](./consultar-aditamento.md)
- [Consultar Signatários](./consultar-signatarios.md)

---

# Cancelar Aditamento

URL: /documentation/escrituracao/aditamento/endpoints/cancelar-aditamento

Desiste de um aditamento em andamento. O aditamento vai para `canceled` com `status_reason: withdrawn_by_tenant`.

---

## **Request**

ENDPOINT /security_amendment/amendment/ AMENDMENT-KEY /cancel
MÉTODO PATCH

### **Path Params**

| Campo | Tipo | Descrição | Caracteres |
| --- | --- | --- | --- |
| `AMENDMENT-KEY` | string | Chave única do aditamento (UUID v4). | 36 |

### **Request Body**

Nenhum. A requisição não leva corpo.

---

## Quando o cancelamento é aceito

| `status` | Cancelável |
| --- | --- |
| `created` | Sim |
| `pending_manual_approval` | Sim |
| `pending_term_generation` | Sim |
| `pending_charge_settlement` | Sim |
| `pending_signature` | Sim |
| `pending_signature_confirmation` | Sim |
| `pending_application` | **Não** |
| `applied` · `canceled` · `validation_failed` · `application_failed` | **Não** |

:::caution Ponto sem volta
A partir de `pending_application` o cancelamento deixa de ser aceito — a recusa é `AMD000012`, com o status atual na mensagem. Se precisar reverter um aditamento já aplicado, fale com o seu contato comercial na QI Tech: é um procedimento próprio, não uma chamada de API.
:::

## Efeitos fora do aditamento

O cancelamento não se limita a mudar o `status`. Ele também:

- **Baixa o boleto da taxa**, se houver um em aberto. Um boleto já compensado não é baixado — nesse caso, o estorno segue o seu contrato comercial.
- **Cancela o envelope de assinatura**, se o termo já tiver sido enviado. Links de assinatura já distribuídos deixam de funcionar.

---

## **Response**

STATUS 200

A resposta é o objeto completo do aditamento, já com `status: canceled`.

Response Body

```json
{
  "amendment_key": "7f1c9a20-6c3e-4a51-9f0b-2d8e5b4c1a33",
  "status": "canceled",
  "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5",
  "amendment_number": 2,
  "operation_key": "8e2b4f10-77a1-4c3d-b9e5-1f6a0c9d2e47",
  "operation_type": "commercial_paper",
  "financial_base_date": "2026-09-20",
  "outstanding_balance": 152340.55,
  "created_by": "integration",
  "created_at": "2026-09-14T10:22:41",
  "applied_at": null,
  "envelope_key": null,
  "signature_method": "certifiqi",
  "changes": ["..."],
  "documents": ["..."],
  "charges": [
    {
      "amendment_charge_key": "9f8e7d6c-5b4a-4938-8271-6a5b4c3d2e1f",
      "charge_status": "canceled",
      "amount": 500.00,
      "settled_at": null,
      "charge_status_history": ["..."]
    }
  ],
  "status_history": [
    { "status": "created", "status_reason": null, "reason": null, "event_actor": "integration", "event_datetime": "2026-09-14T10:22:41" },
    { "status": "pending_charge_settlement", "status_reason": null, "reason": null, "event_actor": "system", "event_datetime": "2026-09-14T10:23:02" },
    { "status": "canceled", "status_reason": "withdrawn_by_tenant", "reason": null, "event_actor": "integration", "event_datetime": "2026-09-14T14:08:55" }
  ]
}
```

---

## **Erros**

| Status | Código | Descrição |
| --- | --- | --- |
| 404 | `AMD000017` | Aditamento não encontrado. |
| 403 | `AMD000018` | O aditamento não pertence ao seu tenant. |
| 409 | `AMD000012` | O `status` atual não permite o cancelamento. |

## Veja também

- [Consultar Aditamento](./consultar-aditamento.md)
- [Regras de Negócio](../regras-de-negocio.md#cancelamento)

---

# Consultar Aditamento

URL: /documentation/escrituracao/aditamento/endpoints/consultar-aditamento

Dois endpoints de consulta: um devolve o aditamento completo pela chave, outro lista os aditamentos do seu tenant de forma paginada.

Como não há webhook dedicado às transições de status do aditamento, a consulta é o caminho para acompanhar o andamento.

---

## Consulta por chave

### **Request**

ENDPOINT /security_amendment/amendment/ AMENDMENT-KEY
MÉTODO GET

### **Path Params**

| Campo | Tipo | Descrição | Caracteres |
| --- | --- | --- | --- |
| `AMENDMENT-KEY` | string | Chave única do aditamento (UUID v4). | 36 |

### **Response**

STATUS 200

A resposta é o objeto completo do aditamento — o mesmo formato devolvido pela [criação](./criar-aditamento.md#response-body-params), agora com os campos preenchidos pelas etapas já percorridas.

Response Body — aditamento aguardando o pagamento da taxa

```json
{
  "amendment_key": "7f1c9a20-6c3e-4a51-9f0b-2d8e5b4c1a33",
  "status": "pending_charge_settlement",
  "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5",
  "amendment_number": 2,
  "operation_key": "8e2b4f10-77a1-4c3d-b9e5-1f6a0c9d2e47",
  "operation_type": "commercial_paper",
  "financial_base_date": "2026-09-20",
  "outstanding_balance": 152340.55,
  "created_by": "integration",
  "created_at": "2026-09-14T10:22:41",
  "applied_at": null,
  "previous_financial_key": "b4d1e8a2-3c57-4f9b-8a06-5e2d7c1b9f34",
  "new_financial_key": null,
  "envelope_key": null,
  "signature_method": "certifiqi",
  "changes": [
    {
      "amendment_change_key": "c9e7a1b3-5d24-4f68-9b0c-3a7e6d5f2c18",
      "type": "financial_flow",
      "operation": "modification",
      "target_key": null,
      "status": "created",
      "is_term_signer": false,
      "applied_at": null,
      "failure_reason": null,
      "previous_value": { "interest_rate": { "monthly_rate": 0.0180, "interest_base": "workdays" } },
      "new_value": { "interest_rate": { "monthly_rate": 0.0199, "interest_base": "workdays" } },
      "term_wording": null,
      "status_history": [
        { "status": "created", "status_reason": null, "reason": null, "event_actor": "integration", "event_datetime": "2026-09-14T10:22:41" }
      ],
      "financial": {
        "previous_interest_rate": { "monthly_rate": 0.0180, "interest_base": "workdays" },
        "new_interest_rate": { "monthly_rate": 0.0199, "interest_base": "workdays" },
        "closing_present_value": 152340.55,
        "closing_difference": 0.00,
        "closing_tolerance": 0.01
      }
    }
  ],
  "documents": [
    {
      "document_key": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "document_type": "amendment_term",
      "description": null,
      "template_key": "de1862a0-e196-4329-9ca4-ba5068a78929",
      "signed_file_key": null,
      "externally_provided_at": null
    }
  ],
  "charges": [
    {
      "amendment_charge_key": "9f8e7d6c-5b4a-4938-8271-6a5b4c3d2e1f",
      "charge_status": "registered",
      "charge_payer_type": "issuer",
      "charge_attempt": 1,
      "amount": 500.00,
      "due_date": "2026-09-19",
      "payer_name": "Emissor Exemplo S.A.",
      "payer_document_number": "12.345.678/0001-90",
      "external_charge_key": "4c3d2e1f-9a8b-4756-b342-1e0d9c8b7a65",
      "digitable_line": "34191.79001 01043.510047 91020.150008 1 96690000050000",
      "settled_at": null,
      "charge_status_history": [
        { "status": "created", "event_actor": "system", "event_datetime": "2026-09-14T10:23:02" },
        { "status": "registration_requested", "event_actor": "system", "event_datetime": "2026-09-14T10:23:03" },
        { "status": "registered", "event_actor": "system", "event_datetime": "2026-09-14T10:23:18" }
      ]
    }
  ],
  "status_history": [
    { "status": "created", "status_reason": null, "reason": null, "event_actor": "integration", "event_datetime": "2026-09-14T10:22:41" },
    { "status": "pending_term_generation", "status_reason": null, "reason": null, "event_actor": "integration", "event_datetime": "2026-09-14T10:22:41" },
    { "status": "pending_charge_settlement", "status_reason": null, "reason": null, "event_actor": "system", "event_datetime": "2026-09-14T10:23:02" }
  ]
}
```

:::tip Onde está a linha digitável
Em `charges[].digitable_line`. Enquanto o aditamento estiver em `pending_charge_settlement`, é o pagamento desse boleto que libera o envio do termo para assinatura.
:::

---

## Consulta paginada

### **Request**

ENDPOINT /security_amendment/amendment
MÉTODO GET

### **Query Params**

| Campo | Tipo | Obrigatório | Padrão | Descrição |
| --- | --- | --- | --- | --- |
| `security_key` | string (UUID) | Não | — | Filtra os aditamentos de um título específico. |
| `page` | integer | Não | `1` | Página desejada. |
| `page_size` | integer | Não | `30` | Itens por página. |

### **Response**

STATUS 200

:::info Resposta resumida
A listagem devolve uma **versão reduzida** de cada aditamento: sem `documents`, `charges`, `status_history`, `envelope_key`, `signature_method` nem as chaves de fluxo financeiro. As alterações vêm sem `previous_value`, `new_value`, `term_wording` e histórico. Para o objeto completo, consulte pela chave.
:::

Response Body

```json
{
  "amendment_list": [
    {
      "amendment_key": "7f1c9a20-6c3e-4a51-9f0b-2d8e5b4c1a33",
      "status": "pending_charge_settlement",
      "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5",
      "amendment_number": 2,
      "operation_key": "8e2b4f10-77a1-4c3d-b9e5-1f6a0c9d2e47",
      "operation_type": "commercial_paper",
      "financial_base_date": "2026-09-20",
      "outstanding_balance": 152340.55,
      "created_by": "integration",
      "created_at": "2026-09-14T10:22:41",
      "applied_at": null,
      "changes": [
        {
          "amendment_change_key": "c9e7a1b3-5d24-4f68-9b0c-3a7e6d5f2c18",
          "type": "financial_flow",
          "operation": "modification",
          "target_key": null,
          "status": "created",
          "is_term_signer": false,
          "applied_at": null,
          "failure_reason": null,
          "financial": {
            "closing_present_value": 152340.55,
            "closing_difference": 0.00,
            "closing_tolerance": 0.01
          }
        }
      ]
    }
  ],
  "total_count": 1,
  "page": 1,
  "page_size": 30
}
```

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `amendment_list` | array | Aditamentos da página, em formato reduzido. |
| `total_count` | integer | Total de aditamentos que atendem ao filtro. |
| `page` | integer | Página devolvida. |
| `page_size` | integer | Tamanho da página. |

---

## **Erros**

| Status | Código | Descrição |
| --- | --- | --- |
| 404 | `AMD000017` | Aditamento não encontrado. |
| 403 | `AMD000018` | O aditamento não pertence ao seu tenant. |

## Veja também

- [Criar Aditamento](./criar-aditamento.md)
- [Consultar Signatários](./consultar-signatarios.md)
- [Baixar Documento](./baixar-documento.md)

---

# Consultar Signatários

URL: /documentation/escrituracao/aditamento/endpoints/consultar-signatarios

Devolve o envelope de assinatura do termo aditivo: quem precisa assinar, quem já assinou e o **link de assinatura** de cada signatário.

Use este endpoint enquanto o aditamento está em `pending_signature_confirmation` para saber quem falta e reenviar o link a quem precisa.

---

## **Request**

ENDPOINT /security_amendment/amendment/ AMENDMENT-KEY /signers
MÉTODO GET

### **Path Params**

| Campo | Tipo | Descrição | Caracteres |
| --- | --- | --- | --- |
| `AMENDMENT-KEY` | string | Chave única do aditamento (UUID v4). | 36 |

---

## **Response**

STATUS 200

Response Body

```json
{
  "envelope_key": "5b930d3d-3713-4c42-85d5-f8e9e44e30ce",
  "status": "pending_signature",
  "documents": [
    {
      "document_type": "amendment_term",
      "signers": [
        {
          "name": "Emissor Exemplo S.A.",
          "document_number": "145.736.070-56",
          "email": "financeiro@emissor-exemplo.com.br",
          "signature_url": "https://sign.qitech.com.br/s/s2S33dD",
          "status": "on_signature"
        },
        {
          "name": "Maria Oliveira",
          "document_number": "969.698.790-03",
          "email": "maria.oliveira@exemplo.com.br",
          "signature_url": "https://sign.qitech.com.br/s/k9Xp1Qa",
          "status": "signed"
        }
      ]
    }
  ]
}
```

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `envelope_key` | string (UUID) | Chave do envelope de assinatura. |
| `status` | string | Estado do envelope. |
| `documents` | array | Documentos do envelope e seus signatários. |
| `documents[].signers[].name` | string | Nome do signatário. |
| `documents[].signers[].document_number` | string | CPF do signatário. |
| `documents[].signers[].email` | string | E-mail para onde o convite foi enviado. |
| `documents[].signers[].signature_url` | string | **Link de assinatura** individual. |
| `documents[].signers[].status` | string | Estado da assinatura daquele signatário. |

:::info Só depois do envelope existir
O envelope é criado quando a taxa do aditamento é paga e o termo segue para assinatura. Antes disso, este endpoint retorna `AMD000039`.
:::

---

## **Erros**

| Status | Código | Descrição |
| --- | --- | --- |
| 404 | `AMD000017` | Aditamento não encontrado. |
| 403 | `AMD000018` | O aditamento não pertence ao seu tenant. |
| 422 | `AMD000039` | O aditamento ainda não tem envelope de assinatura. |
| 500 | `AMD000019` | Falha ao consultar o provedor de assinatura. |

## Veja também

- [Consultar Aditamento](./consultar-aditamento.md)
- [Baixar Documento](./baixar-documento.md)
- [Regras de Negócio](../regras-de-negocio.md#assinatura)

---

# Criar Aditamento

URL: /documentation/escrituracao/aditamento/endpoints/criar-aditamento

Este endpoint cria o aditamento e dispara o rito. A partir daqui a QI Tech orquestra as etapas seguintes — geração do termo, cobrança da taxa, envio para assinatura e aplicação das alterações — e você acompanha pelo endpoint de [consulta](./consultar-aditamento.md).

Valide antes de criar: um título só admite **um aditamento em andamento por vez**, e uma criação recusada no fechamento consome essa vaga até ser cancelada.

---

## **Request**

ENDPOINT /security_amendment/amendment
MÉTODO POST

### **Request Body**

```json
{
  "amendment_key": "7f1c9a20-6c3e-4a51-9f0b-2d8e5b4c1a33",
  "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5",
  "financial_base_date": "2026-09-20",
  "signature_method": "certifiqi",
  "amendment_number": 2,
  "changes": [
    {
      "type": "financial_flow",
      "operation": "modification",
      "term_wording": "As partes repactuam o cronograma de pagamento conforme abaixo.",
      "new_value": {
        "interest_rate": {
          "monthly_rate": 0.0199,
          "interest_base": "workdays"
        },
        "installments": [
          { "installment_number": 3, "due_date": "2026-10-20" },
          { "installment_number": 4, "due_date": "2026-11-20" },
          { "installment_number": 5, "due_date": "2026-12-20" }
        ]
      }
    }
  ]
}
```

### **Request Body Params**

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `security_key` | string (UUID) | Sim | Chave do título a ser aditado. |
| `financial_base_date` | string (date) | Sim | Data base em `YYYY-MM-DD`. Âncora do saldo devedor, do novo fluxo e do momento da aplicação. Retroativa é recusada com `AMD000005`. |
| `changes` | array | Sim | Mínimo 1 item. Formato de cada tipo em [Tipos de Alteração](../tipos-de-alteracao.md). |
| `amendment_key` | string (UUID) | Não | **Chave de idempotência** fornecida por você. Reenviar uma chave já usada retorna `AMD000024`. Quando omitido, a QI Tech gera a chave. |
| `signature_method` | string | Não | Por onde o termo é assinado. Valores: `qi_sign`, `certifiqi`. Ausente, vale `qi_sign`. |
| `amendment_number` | integer (≥ 1) | Não | Ordinal deste aditamento na vida do título, contando os feitos antes da entrada na plataforma. Ausente, a QI Tech usa a própria contagem de aditamentos aplicados + 1. |
| `documents` | array | Não | Documentos anexados. É aqui que você envia o termo pronto — veja abaixo. |

### **Enviar o termo pronto**

Por padrão a QI Tech gera o termo aditivo. Se você prefere enviar o seu, inclua um documento do tipo `amendment_term` no array `documents`:

```json
{
  "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5",
  "financial_base_date": "2026-09-20",
  "changes": [ "..." ],
  "documents": [
    {
      "document_type": "amendment_term",
      "document_name": "termo-aditivo-002.pdf",
      "document_base64": "JVBERi0xLjQKJeLjz9MK...",
      "description": "Termo aditivo redigido pelo escritório do emissor"
    }
  ]
}
```

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `document_type` | string | Sim | Valores: `amendment_term`, `deliberation_evidence`. |
| `document_name` | string | Sim | Nome do arquivo. Entre 1 e 255 caracteres. |
| `document_base64` | string | Sim | Conteúdo do arquivo em base64. |
| `description` | string | Não | Descrição livre. |

:::caution O termo enviado muda o caminho
Enviar um documento do tipo `amendment_term` faz o aditamento nascer em `pending_manual_approval`: a QI Tech confere o documento antes de seguir para a cobrança. Essa conferência é interna e não tem endpoint no seu contrato — acompanhe pelo `status`. Um documento acima do tamanho máximo é recusado com `AMD000016`.
:::

---

## **Response**

STATUS 201

Response Body

```json
{
  "amendment_key": "7f1c9a20-6c3e-4a51-9f0b-2d8e5b4c1a33",
  "status": "pending_term_generation",
  "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5",
  "amendment_number": 2,
  "operation_key": "8e2b4f10-77a1-4c3d-b9e5-1f6a0c9d2e47",
  "operation_type": "commercial_paper",
  "financial_base_date": "2026-09-20",
  "outstanding_balance": 152340.55,
  "created_by": "integration",
  "created_at": "2026-09-14T10:22:41",
  "applied_at": null,
  "previous_financial_key": "b4d1e8a2-3c57-4f9b-8a06-5e2d7c1b9f34",
  "new_financial_key": null,
  "envelope_key": null,
  "signature_method": "certifiqi",
  "changes": [
    {
      "amendment_change_key": "c9e7a1b3-5d24-4f68-9b0c-3a7e6d5f2c18",
      "type": "financial_flow",
      "operation": "modification",
      "target_key": null,
      "status": "created",
      "is_term_signer": false,
      "applied_at": null,
      "failure_reason": null,
      "previous_value": { "interest_rate": { "monthly_rate": 0.0180, "interest_base": "workdays" } },
      "new_value": { "interest_rate": { "monthly_rate": 0.0199, "interest_base": "workdays" } },
      "term_wording": "As partes repactuam o cronograma de pagamento conforme abaixo.",
      "status_history": [
        { "status": "created", "status_reason": null, "reason": null, "event_actor": "integration", "event_datetime": "2026-09-14T10:22:41" }
      ]
    }
  ],
  "documents": [],
  "charges": [],
  "status_history": [
    { "status": "created", "status_reason": null, "reason": null, "event_actor": "integration", "event_datetime": "2026-09-14T10:22:41" },
    { "status": "pending_term_generation", "status_reason": null, "reason": null, "event_actor": "integration", "event_datetime": "2026-09-14T10:22:41" }
  ]
}
```

### **Response Body Params**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `amendment_key` | string (UUID) | Chave única do aditamento. Use-a em todas as consultas. |
| `status` | string | Estado atual. Veja o ciclo de vida em [Conceito](../conceito.md#o-ciclo-de-vida). |
| `security_key` | string (UUID) | Título aditado. |
| `amendment_number` | integer | Ordinal deste aditamento na vida do título. |
| `operation_key` | string (UUID) | Operação de origem do título. |
| `operation_type` | string | Tipo do instrumento. Exemplo: `commercial_paper`. |
| `financial_base_date` | string (date) | Data base do aditamento. |
| `outstanding_balance` | number | Saldo devedor apurado na data base. |
| `created_by` | string | Quem criou o aditamento. |
| `created_at` | string (datetime) | Momento da criação. |
| `applied_at` | string (datetime) | Momento da aplicação. `null` enquanto não aplicado. |
| `previous_financial_key` | string (UUID) | Fluxo financeiro vigente antes do aditamento. |
| `new_financial_key` | string (UUID) | Fluxo resultante. Preenchido na aplicação. |
| `envelope_key` | string (UUID) | Envelope de assinatura. Preenchido quando o termo é enviado para assinatura. |
| `signature_method` | string | `qi_sign` ou `certifiqi`. |
| `changes` | array | As alterações do aditamento, cada uma com status próprio. |
| `documents` | array | Documentos do aditamento, incluindo o termo. |
| `charges` | array | Cobranças do aditamento. Preenchido quando o boleto é emitido. |
| `status_history` | array | Cada transição de status, com ator, motivo e data. |

**`changes[]`**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `amendment_change_key` | string (UUID) | Chave única da alteração. |
| `type` / `operation` / `target_key` | string | Ecoados da requisição. |
| `status` | string | Estado da alteração. |
| `is_term_signer` | boolean | Se a parte relacionada foi eleita signatária do termo. |
| `applied_at` | string (datetime) | Momento em que esta alteração foi aplicada. |
| `failure_reason` | string | Motivo da falha, quando a aplicação não completa. |
| `previous_value` | object | Estado anterior ao aditamento. |
| `new_value` | object | Conteúdo enviado na requisição. |
| `term_wording` | string | Redação específica desta alteração no termo. |
| `status_history` | array | Transições desta alteração. |
| `financial` | object | Presente apenas em alterações de `financial_flow`. Guarda o antes e o depois do fluxo e o resultado do fechamento. |

**`changes[].financial`**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `previous_interest_rate` | object | Taxa vigente antes do aditamento. |
| `new_interest_rate` | object | Taxa resultante. |
| `previous_installments` | array | Cronograma anterior. |
| `new_installments` | array | Cronograma resultante. |
| `closing_present_value` | number | Valor presente usado no fechamento. |
| `closing_difference` | number | Diferença apurada. |
| `closing_tolerance` | number | Tolerância aplicada. |

**`charges[]`**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `amendment_charge_key` | string (UUID) | Chave única da cobrança. |
| `charge_status` | string | Estado do boleto. |
| `charge_payer_type` | string | Quem é cobrado. |
| `charge_attempt` | integer | Número da tentativa de cobrança. |
| `amount` | number | Valor da taxa. |
| `due_date` | string (date) | Vencimento do boleto. |
| `payer_name` | string | Nome do pagador. |
| `payer_document_number` | string | Documento do pagador. |
| `digitable_line` | string | **Linha digitável do boleto.** |
| `external_charge_key` | string (UUID) | Chave do boleto no emissor. |
| `settled_at` | string (datetime) | Momento da compensação. |
| `charge_status_history` | array | Transições da cobrança. |

**`documents[]`**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `document_key` | string (UUID) | Chave do documento. Use-a para [baixar](./baixar-documento.md). |
| `document_type` | string | `amendment_term` ou `deliberation_evidence`. |
| `description` | string | Descrição livre. |
| `template_key` | string (UUID) | Template usado na geração, quando gerado pela QI Tech. |
| `signed_file_key` | string | Referência do arquivo assinado. Preenchido após a assinatura. |
| `externally_provided_at` | string (datetime) | Preenchido quando o documento foi enviado por você. |

**`status_history[]`**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `status` | string | Estado alcançado. |
| `status_reason` | string | Motivo estruturado. Valores: `manual_approval_rejected`, `expired`, `withdrawn_by_tenant`, `withdrawn_by_issuer`, `signature_rejected`, `reverted`. |
| `reason` | string | Descrição livre do motivo. |
| `event_actor` | string | Quem provocou a transição. |
| `event_datetime` | string (datetime) | Momento da transição. |

---

## **Erros**

| Status | Código | Descrição |
| --- | --- | --- |
| 404 | `AMD000001` | Título não encontrado para este tenant. |
| 422 | `AMD000002` | Título não está ativo. |
| 422 | `AMD000003` | Operação de origem não está finalizada. |
| 422 | `AMD000004` | Título já liquidado. |
| 422 | `AMD000005` | Data base retroativa. |
| 422 | `AMD000006` | Combinação de tipo e operação inexistente. |
| 422 | `AMD000007` | `target_key` obrigatório e ausente. |
| 422 | `AMD000008` | Garantia não suportada para este tipo de operação. |
| 422 | `AMD000014` | Parte relacionada de papel imutável (`issuer`, `investor`). |
| 422 | `AMD000015` | Garantia exige documentos que não foram enviados. |
| 413 | `AMD000016` | Documento acima do tamanho máximo. |
| 409 | `AMD000024` | `amendment_key` já utilizado. |
| 422 | `AMD000040` | `is_term_signer` em um tipo que não aceita. |
| 422 | `AMD000041` | Signatário do termo sem `signer_group_list`. |
| 422 | `AMD000042` | Signatário sem e-mail, exigido pelo provedor de assinatura. |
| 422 | `AMD000043` | Parte removida não tem grupo de assinatura. |
| 409 | `AMD000044` | Número de emissão já utilizado. |
| 409 | `AMD000031` | O título já tem um aditamento em andamento. |

O catálogo completo está em [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros).

## Veja também

- [Validar Aditamento](./validar-aditamento.md)
- [Consultar Aditamento](./consultar-aditamento.md)
- [Cancelar Aditamento](./cancelar-aditamento.md)
- [Tipos de Alteração](../tipos-de-alteracao.md)

---

# Simular Aditamento

URL: /documentation/escrituracao/aditamento/endpoints/simular-aditamento

Este endpoint devolve o efeito de uma repactuação de fluxo **sem criar nada**: o saldo devedor na data base, o cronograma vigente, o cronograma proposto, o resultado do fechamento e o valor da taxa do aditamento. Use a simulação para apresentar o cenário ao emissor antes de qualquer compromisso.

:::info Escopo da simulação
A simulação aceita **exatamente uma** alteração, e ela precisa ser do tipo `financial_flow`. Qualquer outro tipo é recusado com `AMD000013`. Para conferir um conjunto completo de alterações, use a [validação](./validar-aditamento.md).
:::

---

## **Request**

ENDPOINT /security_amendment/amendment/simulation
MÉTODO POST

### **Request Body**

```json
{
  "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5",
  "financial_base_date": "2026-09-20",
  "changes": [
    {
      "type": "financial_flow",
      "operation": "modification",
      "new_value": {
        "installments": [
          { "installment_number": 3, "due_date": "2026-10-20" },
          { "installment_number": 4, "due_date": "2026-11-20" },
          { "installment_number": 5, "due_date": "2026-12-20" }
        ]
      }
    }
  ]
}
```

### **Request Body Params**

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `security_key` | string (UUID) | Sim | Chave do título a ser aditado. |
| `financial_base_date` | string (date) | Sim | Data base em `YYYY-MM-DD`. Âncora do saldo devedor e do novo fluxo. |
| `changes` | array | Sim | Exatamente 1 item, do tipo `financial_flow`. Formato em [Tipos de Alteração](../tipos-de-alteracao.md). |

---

## **Response**

STATUS 200

Response Body

```json
{
  "financial_base_date": "2026-09-20",
  "outstanding_balance": 152340.55,
  "closing": {
    "present_value": 152340.55,
    "difference": 0.00,
    "tolerance": 0.01,
    "passed": true
  },
  "preserved_installments": [
    {
      "installment_number": 1,
      "due_date": "2026-07-20",
      "principal_amortization_amount": 48000.00,
      "interest_amount": 2100.00,
      "installment_status": "paid",
      "paid_amount": 50100.00,
      "paid_at": "2026-07-20T13:42:11"
    }
  ],
  "previous_financial": {
    "interest_rate": {
      "monthly_rate": 0.0180,
      "interest_base": "workdays"
    },
    "installments": [
      {
        "installment_number": 3,
        "due_date": "2026-09-20",
        "principal_amortization_amount": 50000.00,
        "interest_amount": 2680.00,
        "installment_status": "pending"
      }
    ]
  },
  "new_financial": {
    "interest_rate": {
      "monthly_rate": 0.0180,
      "interest_base": "workdays"
    },
    "installments": [
      {
        "installment_number": 3,
        "due_date": "2026-10-20",
        "principal_amortization_amount": 49210.33,
        "interest_amount": 3470.22,
        "installment_status": "pending"
      },
      {
        "installment_number": 4,
        "due_date": "2026-11-20",
        "principal_amortization_amount": 49563.87,
        "interest_amount": 3116.68,
        "installment_status": "pending"
      },
      {
        "installment_number": 5,
        "due_date": "2026-12-20",
        "principal_amortization_amount": 49920.40,
        "interest_amount": 2760.15,
        "installment_status": "pending"
      }
    ]
  },
  "charge_amount": 500.00
}
```

### **Response Body Params**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `financial_base_date` | string (date) | Data base usada no cálculo, ecoada da requisição. |
| `outstanding_balance` | number | Saldo devedor apurado na data base. |
| `closing` | object | Resultado do fechamento contra o valor presente. |
| `preserved_installments` | array | Parcelas que **não** entram na repactuação e são mantidas como estão. |
| `previous_financial` | object | Taxa e cronograma vigentes antes do aditamento. |
| `new_financial` | object | Taxa e cronograma resultantes da proposta. |
| `charge_amount` | number | Valor da taxa do aditamento, conforme seu contrato. |

**`closing`**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `present_value` | number | Valor presente do título na data base. |
| `difference` | number | Diferença entre o fluxo proposto e o valor presente. |
| `tolerance` | number | Diferença máxima aceita. |
| `passed` | boolean | `true` quando a diferença está dentro da tolerância. Um fluxo com `false` faria o aditamento nascer em `validation_failed`. |

**`installments[]`** (em `preserved_installments`, `previous_financial` e `new_financial`)

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `installment_number` | integer | Número da parcela no cronograma. |
| `due_date` | string (date) | Vencimento. |
| `principal_amortization_amount` | number | Parcela de amortização do principal. |
| `interest_amount` | number | Parcela de juros. |
| `installment_status` | string | Estado da parcela. |
| `paid_amount` | number | Valor pago. Presente apenas em parcelas com pagamento. |
| `paid_at` | string (datetime) | Momento do pagamento. Presente apenas em parcelas pagas. |

---

## **Erros**

| Status | Código | Descrição |
| --- | --- | --- |
| 404 | `AMD000001` | Título não encontrado para este tenant. |
| 422 | `AMD000002` | Título não está ativo. |
| 422 | `AMD000003` | Operação de origem não está finalizada. |
| 422 | `AMD000004` | Título já liquidado. |
| 422 | `AMD000005` | Data base retroativa. |
| 422 | `AMD000013` | A simulação aceita apenas uma alteração de `financial_flow`. |
| 422 | `AMD000020` | Parcela com pagamento já aplicado não pode ser renegociada. |

O catálogo completo está em [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros).

## Veja também

- [Validar Aditamento](./validar-aditamento.md)
- [Criar Aditamento](./criar-aditamento.md)
- [Regras de Negócio](../regras-de-negocio.md)

---

# Validar Aditamento

URL: /documentation/escrituracao/aditamento/endpoints/validar-aditamento

Este endpoint recebe **o mesmo corpo da criação** e devolve o que aconteceria, sem criar nada. Use-o como último passo antes de disparar o rito: ele confere a elegibilidade do título, resolve cada alteração contra o estado atual e informa em qual `status` o aditamento nasceria.

Diferente da [simulação](./simular-aditamento.md), a validação aceita o **conjunto completo** de alterações, de qualquer tipo.

---

## **Request**

ENDPOINT /security_amendment/amendment/validation
MÉTODO POST

### **Request Body**

Idêntico ao da [criação](./criar-aditamento.md).

```json
{
  "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5",
  "financial_base_date": "2026-09-20",
  "signature_method": "certifiqi",
  "changes": [
    {
      "type": "financial_flow",
      "operation": "modification",
      "new_value": {
        "installments": [
          { "installment_number": 3, "due_date": "2026-10-20" },
          { "installment_number": 4, "due_date": "2026-11-20" }
        ]
      }
    },
    {
      "type": "collateral",
      "operation": "removal",
      "target_key": "a1b2c3d4-0000-4000-8000-000000000001"
    }
  ]
}
```

---

## **Response**

STATUS 200

Response Body

```json
{
  "valid": true,
  "financial_base_date": "2026-09-20",
  "outstanding_balance": 152340.55,
  "closing": {
    "present_value": 152340.55,
    "difference": 0.00,
    "tolerance": 0.01,
    "passed": true
  },
  "resolved_changes": [
    {
      "type": "financial_flow",
      "operation": "modification",
      "target_key": null,
      "previous_value": {
        "interest_rate": {
          "monthly_rate": 0.0180,
          "interest_base": "workdays"
        }
      },
      "preserved_installments": [
        {
          "installment_number": 1,
          "due_date": "2026-07-20",
          "principal_amortization_amount": 48000.00,
          "interest_amount": 2100.00,
          "installment_status": "paid"
        }
      ]
    },
    {
      "type": "collateral",
      "operation": "removal",
      "target_key": "a1b2c3d4-0000-4000-8000-000000000001",
      "previous_value": {
        "collateral_type": "fiduciary_alienation_vehicle",
        "description": "Veículo dado em alienação fiduciária"
      }
    }
  ],
  "term_generation": "qi_generated",
  "next_status": "pending_term_generation"
}
```

### **Response Body Params**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `valid` | boolean | `true` quando o aditamento pode ser criado como enviado. |
| `financial_base_date` | string (date) | Data base ecoada da requisição. |
| `outstanding_balance` | number | Saldo devedor apurado na data base. |
| `closing` | object | Resultado do fechamento. Presente quando há alteração de `financial_flow`. |
| `resolved_changes` | array | Cada alteração resolvida contra o estado atual do título. |
| `term_generation` | string | Origem do termo. `qi_generated` quando a QI Tech gera; `tenant_supplied` quando você enviou o termo pronto. |
| `next_status` | string | O `status` em que o aditamento nasceria se fosse criado agora. |

**`resolved_changes[]`**

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `type` | string | Tipo da alteração. |
| `operation` | string | Operação da alteração. |
| `target_key` | string (UUID) | Registro endereçado, quando houver. |
| `previous_value` | object | Estado atual do que será alterado. Ausente quando não há valor anterior (por exemplo, em `addition`). |
| `preserved_installments` | array | Apenas em `financial_flow`: parcelas mantidas fora da repactuação. |

:::tip Antecipe a aprovação manual
O campo `next_status` é o principal motivo para validar antes de criar. Quando ele vem `pending_manual_approval`, o aditamento vai aguardar conferência da QI Tech sobre o termo que você enviou — e o prazo total muda. Veja [Regras de Negócio](../regras-de-negocio.md#o-termo-aditivo).
:::

---

## **Erros**

A validação recusa pelos mesmos motivos da criação. Os mais comuns:

| Status | Código | Descrição |
| --- | --- | --- |
| 404 | `AMD000001` | Título não encontrado para este tenant. |
| 422 | `AMD000002` | Título não está ativo. |
| 422 | `AMD000003` | Operação de origem não está finalizada. |
| 422 | `AMD000004` | Título já liquidado. |
| 422 | `AMD000005` | Data base retroativa. |
| 422 | `AMD000006` | Combinação de tipo e operação inexistente. |
| 422 | `AMD000007` | `target_key` obrigatório e ausente. |
| 422 | `AMD000008` | Garantia não suportada para este tipo de operação. |
| 422 | `AMD000014` | Parte relacionada de papel imutável. |
| 409 | `AMD000031` | O título já tem um aditamento em andamento. |

O catálogo completo está em [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros).

## Veja também

- [Criar Aditamento](./criar-aditamento.md)
- [Simular Aditamento](./simular-aditamento.md)
- [Tipos de Alteração](../tipos-de-alteracao.md)

---

# Exemplos

URL: /documentation/escrituracao/aditamento/exemplos

Casos completos, do primeiro ensaio ao aditamento aplicado.

---

## 1. Repactuar o fluxo de pagamento

O cenário mais comum: o emissor pede mais prazo e as partes acordam uma taxa nova.

### Passo 1 — Simular

Antes de qualquer compromisso, veja o efeito no fluxo e quanto custa o aditamento.

```
POST /security_amendment/amendment/simulation
```

```json
{
  "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5",
  "financial_base_date": "2026-09-20",
  "changes": [
    {
      "type": "financial_flow",
      "operation": "modification",
      "new_value": {
        "installments": [
          { "installment_number": 3, "due_date": "2026-10-20" },
          { "installment_number": 4, "due_date": "2026-11-20" },
          { "installment_number": 5, "due_date": "2026-12-20" }
        ]
      }
    }
  ]
}
```

Confira `closing.passed` na resposta. Se vier `false`, o fluxo proposto não fecha e o aditamento nasceria recusado — ajuste antes de seguir.

### Passo 2 — Validar

Mesmo corpo da criação, sem criar. Confirme o `next_status`.

```
POST /security_amendment/amendment/validation
```

### Passo 3 — Criar

```
POST /security_amendment/amendment
```

```json
{
  "amendment_key": "7f1c9a20-6c3e-4a51-9f0b-2d8e5b4c1a33",
  "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5",
  "financial_base_date": "2026-09-20",
  "signature_method": "certifiqi",
  "changes": [
    {
      "type": "financial_flow",
      "operation": "modification",
      "new_value": {
        "interest_rate": { "monthly_rate": 0.0199, "interest_base": "workdays" },
        "installments": [
          { "installment_number": 3, "due_date": "2026-10-20" },
          { "installment_number": 4, "due_date": "2026-11-20" },
          { "installment_number": 5, "due_date": "2026-12-20" }
        ]
      }
    }
  ]
}
```

### Passo 4 — Pagar a taxa

Consulte o aditamento e pegue a linha digitável em `charges[].digitable_line`. O aditamento fica em `pending_charge_settlement` até a compensação.

```
GET /security_amendment/amendment/7f1c9a20-6c3e-4a51-9f0b-2d8e5b4c1a33
```

### Passo 5 — Coletar assinaturas

Com a taxa paga, o termo vai para assinatura. Pegue os links:

```
GET /security_amendment/amendment/7f1c9a20-6c3e-4a51-9f0b-2d8e5b4c1a33/signers
```

### Passo 6 — Acompanhar a aplicação

Assinado o termo, o aditamento vai para `pending_application` e é aplicado na `financial_base_date`. Quando chega a `applied`, o campo `applied_at` é preenchido e `new_financial_key` aponta para o fluxo novo.

---

## 2. Substituir uma garantia

Remover a garantia antiga e incluir a nova **no mesmo aditamento** — assim as duas alterações valem juntas, e o título nunca fica descoberto.

```
POST /security_amendment/amendment
```

```json
{
  "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5",
  "financial_base_date": "2026-09-20",
  "changes": [
    {
      "type": "collateral",
      "operation": "removal",
      "target_key": "a1b2c3d4-0000-4000-8000-000000000001",
      "term_wording": "Fica liberada a garantia constituída sobre o veículo de placa ABC1D23."
    },
    {
      "type": "collateral",
      "operation": "addition",
      "new_value": {
        "collateral_type": "fiduciary_alienation_vehicle",
        "description": "Veículo dado em substituição",
        "value": 92000.00
      }
    }
  ]
}
```

:::tip Tudo ou nada
As alterações de um mesmo aditamento são aplicadas em conjunto. Em uma substituição, isso garante que a liberação da garantia antiga e a constituição da nova acontecem no mesmo ato.
:::

---

## 3. Incluir um avalista que assina o termo

A parte incluída pelo aditamento também precisa assinar o termo aditivo — então ela traz o próprio grupo de assinatura.

```
POST /security_amendment/amendment
```

```json
{
  "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5",
  "financial_base_date": "2026-09-20",
  "signature_method": "certifiqi",
  "changes": [
    {
      "type": "related_party",
      "operation": "addition",
      "is_term_signer": true,
      "new_value": {
        "person_type": "natural",
        "name": "Maria Oliveira",
        "document_number": "96969879003",
        "role_type": "surety",
        "street": "Avenida Brigadeiro Faria Lima",
        "number": "1234",
        "neighborhood": "Itaim Bibi",
        "city": "São Paulo",
        "state": "SP",
        "postal_code": "01451-001",
        "signer_group_list": [
          {
            "minimum_required_signers": 1,
            "signers": [
              {
                "name": "Maria Oliveira",
                "document_number": "969.698.790-03",
                "email": "maria.oliveira@exemplo.com.br",
                "is_group_mandatory": true
              }
            ]
          }
        ]
      }
    }
  ]
}
```

:::caution E-mail com CertifiQI
Com `signature_method: certifiqi`, o `email` de cada signatário é obrigatório. Sem ele, a criação é recusada com `AMD000042`.
:::

---

## 4. Enviar o termo já redigido

Quando o escritório do emissor redige o termo, envie-o na criação. O aditamento entra em conferência da QI Tech antes de seguir.

```
POST /security_amendment/amendment
```

```json
{
  "security_key": "2d35b5a7-4cd1-4960-b1d7-4a53668e85b5",
  "financial_base_date": "2026-09-20",
  "changes": [
    {
      "type": "issue_number",
      "operation": "modification",
      "new_value": { "issue_number": 2 }
    }
  ],
  "documents": [
    {
      "document_type": "amendment_term",
      "document_name": "termo-aditivo-002.pdf",
      "document_base64": "JVBERi0xLjQKJeLjz9MK..."
    }
  ]
}
```

O aditamento nasce em `pending_manual_approval`. Acompanhe pelo `status`: aprovado, ele segue para a cobrança; recusado, vai para `canceled` com `status_reason: manual_approval_rejected`.

---

## 5. Desistir de um aditamento

```
PATCH /security_amendment/amendment/7f1c9a20-6c3e-4a51-9f0b-2d8e5b4c1a33/cancel
```

Sem corpo. Aceito até `pending_signature_confirmation`. O boleto em aberto é baixado e o envelope de assinatura é cancelado.

## Veja também

- [Conceito](./conceito.md)
- [Regras de Negócio](./regras-de-negocio.md)
- [Tipos de Alteração](./tipos-de-alteracao.md)

---

# Regras de Negócio — Aditamento

URL: /documentation/escrituracao/aditamento/regras-de-negocio

Esta página consolida as invariantes que governam a criação, a assinatura e a aplicação de um aditamento. Consulte-a sempre que as páginas de endpoints citarem um código de erro, um campo ou uma condição que precise de contexto adicional.

## Elegibilidade do título

Antes de criar qualquer coisa, a QI Tech confere se o título aceita aditamento. Todas as condições abaixo precisam valer:

- O título precisa existir e pertencer ao seu tenant — caso contrário, `AMD000001`.
- O título precisa estar **ativo**. Título em outro estado é recusado com `AMD000002`, e a mensagem carrega o estado encontrado.
- A operação de origem precisa estar **finalizada** (emitida). Operação ainda em cadastro ou análise é recusada com `AMD000003`.
- O título **não pode estar liquidado** — não há o que aditar, e a recusa é `AMD000004`.
- O título **não pode ter outro aditamento em andamento**. Um por vez: enquanto o anterior não chega a `applied`, `canceled` ou `validation_failed`, a criação é recusada com `AMD000031`, e a mensagem diz qual aditamento está ocupando o título.

## Data base (`financial_base_date`)

A `financial_base_date` é **fornecida pelo integrador** e é a única referência temporal do aditamento. Ela define:

- a data em que o saldo devedor (`outstanding_balance`) é apurado;
- a data a partir da qual o novo fluxo passa a valer;
- o momento em que as alterações são efetivamente aplicadas no título.

**Data base retroativa é recusada** com `AMD000005`. A única exceção são operações com origem de tombamento, em que o histórico anterior à entrada na plataforma justifica a retroatividade.

Quando a data base é **futura**, o aditamento permanece em `pending_application` após a coleta das assinaturas e é aplicado quando a data chega. Quando é **hoje**, a aplicação ocorre assim que a última assinatura é confirmada.

## Fechamento do fluxo (`closing`)

Em alterações de `financial_flow`, a QI Tech confere se o cronograma proposto fecha contra o valor presente do título na data base. O resultado vem no objeto `closing`:

| Campo | Significado |
| --- | --- |
| `present_value` | Valor presente do título na data base. |
| `difference` | Diferença entre o fluxo proposto e o valor presente. |
| `tolerance` | Diferença máxima aceita. |
| `passed` | `true` quando a diferença está dentro da tolerância. |

Um fluxo com `passed: false` faz o aditamento nascer diretamente em `validation_failed`: nada é cobrado e nada é enviado para assinatura. Use a [validação](./endpoints/validar-aditamento.md) antes de criar para não gastar uma tentativa.

### A variável livre

O cálculo do novo fluxo resolve **uma variável livre**. O que você envia determina o que a QI Tech calcula:

- **Enviou apenas datas** (`installments[].due_date`) — os valores das parcelas são recalculados, mantida a taxa vigente.
- **Enviou nova taxa** (`interest_rate`) — os valores são recalculados com a taxa nova, mantidas as datas informadas.
- **Enviou valores** (`installments[].amount`) — a taxa é derivada.

Enviar **taxa e valores juntos** é recusado, porque sobredetermina o sistema. Dentro de uma mesma parcela, `amount` e `principal_amortization_percentage` também são excludentes.

### Parcelas preservadas

Envie **apenas a cauda renegociada**. Parcelas já pagas não entram no payload — a QI Tech as preserva automaticamente e as devolve em `preserved_installments` na simulação.

Uma parcela **parcialmente paga não pode ser renegociada**: a recusa é `AMD000020`, com o número e o estado da parcela na mensagem.

## O termo aditivo

O termo pode nascer de dois jeitos, e a escolha muda o caminho do aditamento.

**Gerado pela QI Tech** — o comportamento padrão. Você não envia nenhum documento do tipo `amendment_term` na criação; a QI Tech monta o termo a partir dos dados do aditamento e o aditamento segue direto para a cobrança.

**Enviado pronto pelo integrador** — você inclui um documento do tipo `amendment_term` no array `documents` da criação. Nesse caso o aditamento entra em `pending_manual_approval`.

:::info Conferência da QI Tech
Quando o termo é enviado pronto, a QI Tech confere o documento antes de seguir. Essa etapa é executada internamente pela equipe da QI Tech e **não tem endpoint no seu contrato de integração** — acompanhe pelo `status`. Aprovado, o aditamento segue para a cobrança. Recusado, ele vai para `canceled` com `status_reason: manual_approval_rejected`.
:::

Cada alteração aceita ainda o campo `term_wording` (até 10.000 caracteres): o texto que o termo deve carregar para aquela alteração específica, no lugar da redação padrão da plataforma.

## Cobrança

O aditamento tem uma taxa de serviço, cobrada por boleto emitido no momento em que o termo fica pronto. O valor segue a configuração comercial do seu contrato e é devolvido na simulação, em `charge_amount`.

**O pagamento do boleto é o que libera o envio para assinatura.** Enquanto a compensação não ocorre, o aditamento permanece em `pending_charge_settlement`. A linha digitável fica em `charges[].digitable_line` na consulta.

Boleto vencido sem pagamento não trava o aditamento em definitivo: a QI Tech substitui o boleto vencido por um novo quando o fluxo é retomado. Um boleto dentro do prazo continua válido, com a mesma linha digitável.

## Assinatura

Com a taxa paga, a QI Tech monta o envelope e o envia aos signatários.

- Os signatários vêm dos **grupos de assinatura cadastrados na operação**. Uma operação sem grupo de assinatura ativo para o emissor é recusada com `AMD000022`.
- Uma **parte relacionada incluída pelo próprio aditamento** pode ser eleita signatária do termo com `is_term_signer: true`. Nesse caso ela precisa trazer `signer_group_list` no `new_value` — sem isso, `AMD000041`.
- Em remoções, os grupos vêm do cadastro da operação. Uma parte sem grupo de assinatura não pode assinar: `AMD000043`.
- `is_term_signer` só existe em alterações do tipo `related_party` — em qualquer outro tipo, `AMD000040`.
- O método de assinatura vai em `signature_method` na criação. Quando omitido, vale `qi_sign`. Com `certifiqi`, **o e-mail do signatário é obrigatório** — sem ele, `AMD000042`.

Consulte o andamento pelo endpoint de [signatários](./endpoints/consultar-signatarios.md), que devolve quem já assinou, quem falta e o link de assinatura de cada um.

## Aplicação

Coletadas as assinaturas — e chegada a data base — a QI Tech aplica as alterações no título. A aplicação é **conjunta**: as alterações de um mesmo aditamento valem todas ou nenhuma.

Cada alteração carrega o próprio `status` e o `applied_at`. Uma alteração que falha registra o motivo em `failure_reason` e leva o aditamento para `application_failed`.

:::caution Alterações de `term_clause`
Uma alteração do tipo `term_clause` não altera dado estruturado no título — o efeito dela vive na redação do termo assinado. Ela é registrada e aplicada como as demais, mas não produz mudança consultável fora do documento.
:::

## Cancelamento

Você pode desistir do aditamento enquanto ele não entrou em aplicação. O cancelamento é aceito nos status `created`, `pending_manual_approval`, `pending_term_generation`, `pending_charge_settlement`, `pending_signature` e `pending_signature_confirmation`.

A partir de `pending_application` o cancelamento **não é mais aceito** — a recusa é `AMD000012`. Nos estados terminais (`applied`, `canceled`, `validation_failed`) também não.

O cancelamento tem dois efeitos fora do aditamento: **baixa o boleto em aberto**, se houver, e **cancela o envelope de assinatura**, se já tiver sido enviado. Um boleto já pago não é baixado.

O motivo registrado é `withdrawn_by_tenant`, visível em `status_history[].status_reason`.

## Veja também

- [Conceito](./conceito.md)
- [Tipos de Alteração](./tipos-de-alteracao.md)
- [Criar Aditamento](./endpoints/criar-aditamento.md)
- [Exemplos](./exemplos.md)
- [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros)

---

# Tipos de Alteração

URL: /documentation/escrituracao/aditamento/tipos-de-alteracao

Cada item do array `changes` descreve uma alteração. Esta página detalha o formato de `new_value` para cada `type`.

## O envelope da alteração

Todos os tipos compartilham a mesma estrutura externa:

```json
{
  "type": "collateral",
  "operation": "removal",
  "target_key": "a1b2c3d4-0000-4000-8000-000000000001",
  "new_value": null,
  "term_wording": "Texto livre para o termo, no lugar da redação padrão.",
  "is_term_signer": false
}
```

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `type` | string | Sim | Dimensão alterada. Valores: `financial_flow`, `collateral`, `related_party`, `issue_number`, `term_clause`. |
| `operation` | string | Sim | Valores: `addition`, `modification`, `removal`. Nem toda combinação existe — veja a matriz abaixo. |
| `target_key` | string (UUID) | Condicional | Registro existente endereçado pela alteração. Obrigatório em `modification` e `removal` de `collateral` e `related_party`. |
| `new_value` | object | Condicional | Conteúdo da alteração. O formato depende do `type`. Ausente em `removal`. |
| `term_wording` | string | Não | Até 10.000 caracteres. Redação específica que o termo deve carregar para esta alteração. |
| `is_term_signer` | boolean | Não | Apenas em `related_party`: a parte endereçada assina o termo aditivo. |

## Matriz de combinações

| `type` | `addition` | `modification` | `removal` |
| --- | --- | --- | --- |
| `financial_flow` | — | Sim, sem `target_key` | — |
| `collateral` | Sim, sem `target_key` | Sim, `target_key` obrigatório | Sim, `target_key` obrigatório |
| `related_party` | Sim, sem `target_key` | Sim, `target_key` obrigatório | Sim, `target_key` obrigatório |
| `issue_number` | — | Sim, sem `target_key` | — |
| `term_clause` | Sim | Sim | Sim — nenhum exige `target_key` |

Combinação inexistente é recusada com `AMD000006`, e a mensagem carrega o par tentado. `target_key` faltando onde é exigido retorna `AMD000007`.

---

## `financial_flow` — repactuação do fluxo

Reperfilamento do cronograma de pagamento. Aceita apenas `modification`.

```json
{
  "type": "financial_flow",
  "operation": "modification",
  "new_value": {
    "interest_rate": {
      "monthly_rate": 0.0199,
      "interest_base": "workdays"
    },
    "installments": [
      { "installment_number": 3, "due_date": "2026-10-20" },
      { "installment_number": 4, "due_date": "2026-11-20" },
      { "installment_number": 5, "due_date": "2026-12-20" }
    ]
  }
}
```

### `new_value`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `interest_rate` | object | Condicional | Nova taxa. Ausente, mantém a taxa vigente do título. |
| `installments` | array | Condicional | Somente a cauda renegociada. Mínimo 1 item. |

Pelo menos um dos dois precisa estar presente.

**`interest_rate`**

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `interest_base` | string | Sim | Base de contagem. Valores: `calendar_days`, `calendar_days_365`, `workdays`. |
| `annual_rate` | number | Condicional | Taxa anual. |
| `monthly_rate` | number | Condicional | Taxa mensal. |
| `daily_rate` | number | Condicional | Taxa diária. |

Informe **exatamente uma** entre `annual_rate`, `monthly_rate` e `daily_rate`.

**`installments[]`**

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `installment_number` | integer (≥ 1) | Sim | Número da parcela no cronograma do título. |
| `due_date` | string (date) | Sim | Novo vencimento, em `YYYY-MM-DD`. |
| `amount` | number (> 0) | Não | Novo valor da parcela. |
| `principal_amortization_percentage` | number | Não | Percentual de amortização do principal. |

:::caution Uma variável livre por vez
`amount` e `principal_amortization_percentage` são **excludentes** dentro da mesma parcela. E enviar `interest_rate` junto com `amount` nas parcelas sobredetermina o cálculo e é recusado — escolha o que a QI Tech deve calcular.
:::

Parcelas já pagas não entram no array; a QI Tech as preserva. Uma parcela parcialmente paga não pode ser renegociada (`AMD000020`).

---

## `collateral` — garantias

Inclusão ou remoção de garantia. Disponível apenas para operações do tipo `commercial_paper` e `debenture` — em qualquer outro tipo, `AMD000008`.

**Inclusão** — o `new_value` carrega a garantia completa, no mesmo formato aceito no cadastro da operação. O campo `collateral_type` discrimina o formato:

```json
{
  "type": "collateral",
  "operation": "addition",
  "new_value": {
    "collateral_type": "fiduciary_alienation_vehicle",
    "description": "Veículo dado em alienação fiduciária",
    "value": 85000.00
  }
}
```

**Remoção** — endereça a garantia existente e não leva `new_value`:

```json
{
  "type": "collateral",
  "operation": "removal",
  "target_key": "a1b2c3d4-0000-4000-8000-000000000001"
}
```

### Tipos de garantia aceitos

`bank_surety` · `contract` · `fiduciary_alienation_aircraft` · `fiduciary_alienation_artwork` · `fiduciary_alienation_equipment` · `fiduciary_alienation_property` · `fiduciary_alienation_securities` · `fiduciary_alienation_vehicle` · `fiduciary_assignment_shares` · `guarantor` · `insurance` · `monitoring_guarantee` · `mortgage_property` · `mortgage_ship` · `surety` · `vehicle_stock`

O formato de cada tipo é o mesmo do [cadastro de garantia](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/cadastro-garantia) na emissão. Garantias que exigem documentos precisam trazê-los — a falta é recusada com `AMD000015`.

---

## `related_party` — partes relacionadas

Inclusão, alteração ou remoção de avalista, devedor solidário, fiel depositário e demais papéis.

```json
{
  "type": "related_party",
  "operation": "addition",
  "is_term_signer": true,
  "new_value": {
    "person_type": "natural",
    "name": "Maria Oliveira",
    "document_number": "96969879003",
    "role_type": "surety",
    "street": "Avenida Brigadeiro Faria Lima",
    "number": "1234",
    "neighborhood": "Itaim Bibi",
    "city": "São Paulo",
    "state": "SP",
    "postal_code": "01451-001",
    "signer_group_list": [
      {
        "minimum_required_signers": 1,
        "signers": [
          {
            "name": "Maria Oliveira",
            "document_number": "969.698.790-03",
            "email": "maria.oliveira@exemplo.com.br",
            "is_group_mandatory": true
          }
        ]
      }
    ]
  }
}
```

### Papéis (`role_type`)

`cosigner` · `fiduciary_debtor` · `solidary_debtor` · `surety`

:::caution Papéis imutáveis
`issuer` e `investor` **não podem ser aditados** — a recusa é `AMD000014`. Emissor e investidor são determinados na emissão do título.
:::

### Eleger a parte como signatária

Com `is_term_signer: true`, a parte assina o termo aditivo:

- Em `addition` e `modification`, o `new_value` precisa trazer `signer_group_list` — sem ele, `AMD000041`.
- Em `removal`, os grupos vêm do cadastro da operação. Parte sem grupo de assinatura não pode assinar: `AMD000043`.
- Com `signature_method: certifiqi`, o `email` de cada signatário é **obrigatório** — sem ele, `AMD000042`.
- `is_term_signer` em qualquer outro `type` é recusado com `AMD000040`.

---

## `issue_number` — número da emissão

Correção do número da emissão. Aceita apenas `modification`.

```json
{
  "type": "issue_number",
  "operation": "modification",
  "new_value": { "issue_number": 2 }
}
```

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `issue_number` | integer (≥ 1) | Sim | Novo número da emissão. |

Um número já usado por outra operação ativa do mesmo emissor é recusado com `AMD000044`.

---

## `term_clause` — cláusulas do termo

Regeração do documento com campos livres. Não existe cláusula endereçável: o que muda é o template e o mapa de campos que ele consome.

```json
{
  "type": "term_clause",
  "operation": "modification",
  "new_value": {
    "document_type": "commercial_paper",
    "extra_fields": {
      "clausula_decima": "As partes acordam que...",
      "foro_eleito": "Comarca de São Paulo - SP"
    }
  }
}
```

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `document_type` | string | Sim | Valores: `commercial_paper`, `adhesion_term`. |
| `extra_fields` | object | Sim | Mapa plano de texto para texto, consumido pelo template. Mínimo 1 chave. |
| `template_key` | string (UUID) | Não | Template específico a ser usado. |

:::info Efeito documental
Uma alteração de `term_clause` não muda dado estruturado no título — o efeito dela vive na redação do termo assinado.
:::

## Veja também

- [Regras de Negócio](./regras-de-negocio.md)
- [Criar Aditamento](./endpoints/criar-aditamento.md)
- [Exemplos](./exemplos.md)

---

# Amortização Extraordinária

URL: /documentation/escrituracao/amortizacao-extraordinaria/conceito

## Visão geral

Amortização extraordinária é o processo de reduzir o saldo devedor de uma emissão fora do cronograma ordinário — quando o emissor antecipa um pagamento, quita parcelas adiante do vencimento ou refinancia parte da dívida. O QI Tech recebe esse pedido via API, valida os valores e registra o evento para liquidação posterior, sem interferir nas amortizações ordinárias geradas em cada `due_date` (data de vencimento).

Os cenários típicos envolvem quitação antecipada pelo emissor, pagamento antecipado de uma ou mais parcelas e operações de refinanciamento parcial. Em todos esses casos o integrador inicia o fluxo sob demanda, informando qual parcela (ou conjunto de parcelas) está sendo amortizada e qual o valor.

Você recorre a esta API sempre que precisa alterar o saldo devedor fora da agenda ordinária de pagamentos. O resultado é sempre um evento rastreável, com `status` próprio e registro financeiro. A criação é fire-and-forget: a QI Tech orquestra liquidação, finalização e cancelamento internamente, sem que o integrador precise chamar endpoints adicionais.

## Amortização ordinária vs extraordinária

A amortização ordinária é gerada automaticamente pela QI Tech: em cada `due_date` (data de vencimento), o processo de liquidação da parcela é criado internamente sem ação do integrador. Já a amortização extraordinária é sempre iniciada sob demanda, por chamada explícita à API. As duas coexistem — registrar uma amortização extraordinária não cancela nem substitui as ordinárias que ainda vão vencer; apenas adiciona um novo evento de liquidação sobre o ativo.

## Tipos de amortização

Os sete tipos suportados ficam no campo `amortization_type`. Em todos eles `installment_list` define as parcelas-alvo; o tipo define como o `amount` é distribuído entre elas:

- `equal_amount` (valores proporcionais) — distribui proporcionalmente o valor informado entre as parcelas selecionadas, vencidas primeiro e depois as futuras.
- `first_installments` (primeiras parcelas) — aplica o valor sequencialmente às N primeiras parcelas selecionadas (por vencimento) até esgotá-lo.
- `present_amount` (valor presente) — o integrador escolhe as parcelas e pode informar `total_discount`; a ordem de distribuição é juros → multa → principal.
- `matured_installments` (parcelas vencidas) — aplica o valor exclusivamente a parcelas já vencidas.
- `early_amortization` (amortização antecipada) — antecipa o pagamento de uma parcela futura.
- `nominal_amount` (valor nominal) — quita parcelas futuras pelo valor nominal (principal + juros no vencimento), sem trazê-las ao Valor Presente; não aceita parcelas vencidas.
- `full_amortization` (quitação integral) — rateia o `amount` proporcionalmente ao Valor Presente entre **todas** as parcelas selecionadas, sem cascata, e quita cada uma integralmente na liquidação, mesmo que a cota recebida seja menor que o Valor Presente; a diferença fica registrada como `discount_amount` de cada parcela.

Apenas `early_amortization` e `nominal_amount` permitem pagamento parcial — os outros cinco exigem cobertura integral do valor declarado dentro da tolerância.

## Conceitos-chave
- **`event_conciliation`** — corresponde ao evento de conciliação de uma parcela específica. Responsável pelo ato de conciliação de pagamentos e/ou amortizações extraordinárias de parcelas de um valor mobiliário.
- **`reference_date`** — data de referência fornecida pelo chamador em toda criação (deve corresponder à data de quitação). O QI Tech nunca usa `date.today()`: toda lógica relativa a datas (classificação de vencimento, projeção do Valor Presente, discriminação de parcelas vencidas vs a vencer) parte desse campo.
- **Valor Presente** — calculado internamente e consumido durante a criação do evento. O integrador não precisa calcular Valor Presente no seu lado.
- **Tolerância (`tolerance_amount`)** — diferença máxima aceita entre o valor de liquidação e o valor esperado da parcela. Default de R$ 0,01. Diferenças acima da tolerância fazem a liquidação ser rejeitada.
- **Estado parcial derivado** — quando `paid_amount > 0` e `paid_amount < expected_amount`, a parcela é considerada parcialmente paga. Não há novo status: o estado é DERIVADO das colunas `paid_amount` e `expected_amount`. O status `pending_conciliation` cobre tanto o "ainda não pago" quanto o "parcialmente pago"; `paid` só aparece quando o acumulado cobre o esperado dentro da tolerância.

## Próximos passos

Siga para o [Roteiro de Integração](../roteiro-integracao/roteiro-integracao-padrao.md) para ver o fluxo passo a passo. Para o cenário em que uma nova operação recompra amortizações extraordinárias em aberto, veja [Amortização com Recompra](./recompra-de-operacao.md).

---

# Consultar Amortização Extraordinária

URL: /documentation/escrituracao/amortizacao-extraordinaria/endpoints/consultar-amortizacao

Este endpoint retorna uma amortização extraordinária específica pela sua chave (`extraordinary_event_conciliation_key`). Use-o para acompanhar o status da conciliação do evento — desde `pending_conciliation` (ainda não pago ou parcialmente pago) até o estado terminal (`paid` ou `canceled`) definido pela orquestração interna da QI Tech.

A consulta é agnóstica de data e não dispara nenhuma transição de status: apenas reflete o estado atual do evento e de cada parcela vinculada.

---

## **Request**
ENDPOINT /event_conciliation/extraordinary_event/ EXTRAORDINARY-EVENT-CONCILIATION-KEY
MÉTODO GET

### **Path Params**

| Campo                                  | Tipo          | Obrigatório | Descrição                                                                 |
|----------------------------------------|---------------|-------------|---------------------------------------------------------------------------|
| `extraordinary_event_conciliation_key` | string (UUID) | Sim         | Chave única do evento extraordinário de amortização a consultar.          |

Exemplo de chamada:

```
GET /event_conciliation/extraordinary_event/11111111-1111-4111-8111-111111111111
```

---

## **Response**
STATUS 200

Response Body
```json
{
  "extraordinary_event_conciliation_key": "11111111-1111-4111-8111-111111111111",
  "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e",
  "investment_key": "44444444-4444-4444-8444-444444444444",
  "amortization_type": "early_amortization",
  "total_expected_amount": 1500.00,
  "total_discount_amount": 0,
  "total_paid_amount": 0.0,
  "status": "pending_conciliation",
  "reference_date": "2026-04-24",
  "due_date": "2026-04-24",
  "paid_at": null,
  "event_conciliation_list": [
    {
      "event_conciliation_key": "22222222-2222-4222-8222-222222222222",
      "installment_key": "33333333-3333-4333-8333-333333333333",
      "event_conciliation_status": "pending_conciliation",
      "event_conciliation_type": "extraordinary_event"
    }
  ]
}
```

### **Response Body Params**

| Campo                                  | Tipo            | Descrição                                                                                                           |
|----------------------------------------|-----------------|---------------------------------------------------------------------------------------------------------------------|
| `extraordinary_event_conciliation_key` | string (UUID)   | Chave do evento extraordinário de amortização consultado.                                                          |
| `security_key`                         | string (UUID)   | Chave do ativo (`security`) ao qual o evento pertence.                                                             |
| `investment_key`                       | string (UUID)   | Chave do investimento alvo do evento.                                                                              |
| `amortization_type`                    | string          | Tipo de amortização do evento — ecoa o valor usado na criação.                                                     |
| `total_expected_amount`                | number          | Valor total esperado do evento (soma distribuída entre as parcelas) em BRL.                                        |
| `total_discount_amount`                | number          | Desconto total aplicado. Diferente de zero apenas para `present_amount`.                                           |
| `total_paid_amount`                    | number          | Valor já conciliado para o evento (em BRL). `0` enquanto nenhum pagamento foi confirmado; `> 0` em pagamento parcial. |
| `status`                               | string          | Status atual do evento: `pending_conciliation`, `paid` ou `canceled`.                                              |
| `reference_date`                       | string (date)   | Data de referência informada na criação.                                                                          |
| `due_date`                             | string (date)   | Data alvo de liquidação informada na criação.                                                                     |
| `paid_at`                              | string (date)   | Data em que o evento foi liquidado. `null` enquanto não estiver `paid`.                                            |
| `event_conciliation_list`             | array           | Lista de `event_conciliation` (evento de conciliação de cada parcela) do evento. **[Objeto event_conciliation_list](#objeto-event_conciliation_list)**. |

### **Objeto event_conciliation_list**

| Campo                       | Tipo            | Descrição                                                                                 |
|-----------------------------|-----------------|-------------------------------------------------------------------------------------------|
| `event_conciliation_key`    | string (UUID)   | Chave do evento de conciliação da parcela (`event_conciliation`).                          |
| `installment_key`           | string (UUID)   | Chave da parcela afetada por este evento de conciliação.                                   |
| `event_conciliation_status` | string          | Status atual do evento de conciliação da parcela (`pending_conciliation`, `paid`, `canceled`). |
| `event_conciliation_type`   | string          | Tipo do `event_conciliation`. Sempre `extraordinary_event` para eventos criados por este fluxo. |

:::info
O `status` (e o `event_conciliation_status` de cada parcela) reflete o estado atual no momento da consulta. A transição para `paid` ou `canceled` é feita pela orquestração interna da QI Tech — o integrador não precisa acionar nenhum endpoint para isso.
:::

---

## **Erros**

| Código     | HTTP | Significado                                                                                            |
|------------|------|--------------------------------------------------------------------------------------------------------|
| EVC100011  | 404  | Nenhuma amortização extraordinária encontrada para a `extraordinary_event_conciliation_key` informada. |

Consulte o [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros) para resolução completa.

---

## **Veja também**

- [Criar Amortização Extraordinária](./criar-amortizacao.md)
- [Simular Valor Presente da Amortização Extraordinária](./simular-valor-presente.md)
- [Conceito](../conceito.md)
- [Roteiro de Integração](../../roteiro-integracao/roteiro-integracao-padrao.md)
- [Regras de Negócio](../regras-de-negocio.md)
- [Exemplos](../exemplos.md)

---

# Criar Amortização Extraordinária

URL: /documentation/escrituracao/amortizacao-extraordinaria/endpoints/criar-amortizacao

Este endpoint cria uma amortização extraordinária sobre um ou mais `installment` de uma emissão. O event-conciliation-service agrupa as parcelas em um evento extraordinário de amortização único, distribui o `amount` declarado conforme o `amortization_type` informado e obtém o Valor Presente via security-service — o integrador não calcula Valor Presente no seu lado. A `reference_date` é fornecida pelo chamador na requisição da amortização extraordinária e é a única referência temporal usada pelo serviço na classificação de vencidos e no desconto pro-rata.

---

## **Request**
ENDPOINT /event_conciliation/extraordinary_event
MÉTODO POST

### **Request Body**

`installment_list` (array de `installment_number`, inteiros ≥ 1) é obrigatório para todos os tipos: ele define as parcelas-alvo e o `amortization_type` define como o `amount` é distribuído entre elas. Os números enviados em `installment_list` são resolvidos pelo serviço contra `installment_number` da `security` correspondente.

Exemplo — `early_amortization` (uma parcela futura):

```json
{
  "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e",
  "investment_key": "<investment_key>",
  "amortization_type": "early_amortization",
  "amount": 1500.00,
  "reference_date": "2026-04-24",
  "due_date": "2026-04-24",
  "installment_list": [1]
}
```

Exemplo — `equal_amount` (proporcional entre as parcelas selecionadas):

```json
{
  "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e",
  "investment_key": "<investment_key>",
  "amortization_type": "equal_amount",
  "amount": 5000.00,
  "reference_date": "2026-04-24",
  "due_date": "2026-04-24",
  "installment_list": [1, 2, 3, 4]
}
```

Exemplo — `nominal_amount` (parcelas futuras pelo valor nominal):

```json
{
  "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e",
  "investment_key": "<investment_key>",
  "amortization_type": "nominal_amount",
  "amount": 18670.00,
  "reference_date": "2026-04-24",
  "due_date": "2026-04-24",
  "installment_list": [3, 4]
}
```

### **Request Body Params**

| Campo                     | Tipo            | Obrigatório  | Descrição                                                                                                                                                                                                  |
|---------------------------|-----------------|--------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `security_key`            | string (UUID)   | Sim          | Chave única do ativo (`security`) sobre o qual a amortização será aplicada.                                                                                                                                |
| `investment_key`          | string (UUID)   | Sim          | Chave do investimento alvo. Usado pelo security-service como base proporcional no cálculo de Valor Presente.                                                                                                |
| `amortization_type`       | string          | Sim          | Estratégia de distribuição. Valores: `equal_amount`, `first_installments`, `present_amount`, `matured_installments`, `early_amortization`, `nominal_amount`, `full_amortization`.                                                                  |
| `amount`                  | number          | Sim          | Valor total a ser amortizado (em BRL). Distribuído entre as parcelas selecionadas conforme o `amortization_type`.                                                                                           |
| `reference_date`          | string (date)   | Sim          | Data de referência em formato `YYYY-MM-DD`. **Fornecida pelo chamador** — o serviço a usa como "hoje" para classificar parcelas vencidas e aplicar o desconto pro-rata do Valor Presente.                  |
| `due_date`                | string (date)   | Sim          | Data alvo de liquidação (tipicamente igual à `reference_date`).                                                                                                                                            |
| `installment_list`        | array de inteiros (≥ 1) | Sim          | Lista de `installment_number` (não UUIDs) das parcelas-alvo, com `minItems: 1`. Obrigatório para todos os tipos — omitir retorna `EVC100002`. O serviço resolve cada número contra `installment_number` da `security`; números inexistentes retornam `EVC000007`. O legado `installment_key_list` foi removido — clientes que ainda enviarem o campo recebem `QIT000001` (400). |
| `total_discount`          | number          | Não          | Utilizado apenas com `present_amount` — distribui o desconto na ordem juros → multa → principal.                                                                                                            |
| `number_of_installments`  | integer         | Condicional  | Obrigatório com `first_installments`: quantas das parcelas selecionadas, em ordem de vencimento, recebem o valor.                                                                                            |

---

## **Response**
STATUS 201

Response Body
```json
{
  "extraordinary_event_conciliation_key": "11111111-1111-4111-8111-111111111111",
  "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e",
  "amortization_type": "early_amortization",
  "total_expected_amount": 1500.00,
  "total_discount_amount": 0,
  "status": "pending_conciliation",
  "reference_date": "2026-04-24",
  "due_date": "2026-04-24",
  "event_conciliation_list": [
    {
      "event_conciliation_key": "22222222-2222-4222-8222-222222222222",
      "installment_key": "33333333-3333-4333-8333-333333333333",
      "expected_amount": 1500.00,
      "discount_amount": 0,
      "due_date": "2026-04-24",
      "status": "pending_conciliation",
      "event_conciliation_type": "extraordinary"
    }
  ]
}
```

### **Response Body Params**

| Campo                                 | Tipo            | Descrição                                                                                                           |
|---------------------------------------|-----------------|---------------------------------------------------------------------------------------------------------------------|
| `extraordinary_event_conciliation_key`| string (UUID)   | Chave do evento geral de amortização extraordinário criado.                                                                        |
| `security_key`                        | string (UUID)   | Chave do ativo — ecoa o valor enviado.                                                                              |
| `amortization_type`                   | string          | Tipo de amortização escolhido — ecoa o valor enviado.                                                               |
| `total_expected_amount`               | number          | Soma distribuída entre os `event_conciliation` (eventos de conciliação da parcela) pelo engine do tipo escolhido.                                |
| `total_discount_amount`               | number          | Desconto total aplicado. Diferente de zero apenas para `present_amount`.                                            |
| `status`                              | string          | Status inicial do evento extraordinário. Sempre `pending_conciliation` ao criar.                                    |
| `reference_date`                      | string (date)   | Data de referência enviada na requisição (deve corresponder a data de quitação).                                                                           |
| `due_date`                            | string (date)   | Data alvo de liquidação enviada na requisição.                                                                      |
| `event_conciliation_list`             | array           | Lista de `event_conciliation` (evento de conciliação da parcela) gerado. **[Objeto event_conciliation_list](#objeto-event_conciliation_list)**. |

### **Objeto event_conciliation_list**

| Campo                    | Tipo            | Descrição                                                                                 |
|--------------------------|-----------------|-------------------------------------------------------------------------------------------|
| `event_conciliation_key` | string (UUID)   | Chave do evento de conciliação da parcela (`event_conciliation`). |
| `installment_key`        | string (UUID)   | Chave da parcela afetada por este evento de conciliação.                                                  |
| `expected_amount`        | number          | Valor atribuído a este evento de conciliação da parcela pela engine de distribuição.                                 |
| `discount_amount`        | number          | Parcela do `total_discount` alocada a este evento de conciliação da parcela (`present_amount`) ou diferença entre o Valor Presente da parcela e a cota recebida (`full_amortization`). |
| `due_date`               | string (date)   | Data de vencimento da parcela associada.                                                  |
| `status`                 | string          | Status inicial do evento de conciliação da parcela. Sempre `pending_conciliation` ao criar.                          |
| `event_conciliation_type`| string          | Tipo do `event_conciliation`. Sempre `extraordinary` para eventos de conciliação da parcela criados por este fluxo.  |

---

## **Erros**

| Código     | HTTP | Significado                                                                                            |
|------------|------|--------------------------------------------------------------------------------------------------------|
| EVC100001  | 400  | `amortization_type` inválido. Use um dos sete valores suportados.                                      |
| EVC100002  | 400  | `installment_list` é obrigatório (e não vazio) para todos os tipos de amortização.                     |
| EVC100003  | 400  | `number_of_installments` é obrigatório para `first_installments`.                                      |
| EVC100004  | 400  | Alguma parcela informada não pertence à `security` alvo.                                               |
| EVC000007  | 404  | Algum inteiro em `installment_list` não corresponde a nenhum `installment_number` da `security` (`InstallmentNumberNotFound`). |
| QIT000001  | 400  | Falha de schema — por exemplo, envio do legado `installment_key_list` (removido) ou item de `installment_list` que não é inteiro ≥ 1. |
| EVC100005  | 400  | `amount` não cobre todas as parcelas selecionadas (não aplicável a `early_amortization`).              |
| EVC100006  | 400  | `total_discount` excede a soma do Valor Presente das parcelas selecionadas.                            |
| EVC100007  | 400  | Para `matured_installments`, todas as parcelas selecionadas devem estar vencidas.                      |
| EVC100008  | 400  | Já existe uma amortização extraordinária pendente para a parcela — cancele-a antes de criar outra.     |
| EVC100013  | 424  | Security API indisponível (Failed Dependency). Transitório — repita após o restabelecimento.           |
| EVC100015  | 400  | `early_amortization` requer exatamente 1 parcela em `installment_list`.                                |
| EVC100016  | 400  | A parcela alvo de `early_amortization` não pode estar vencida.                                         |
| EVC100017  | 400  | Em `early_amortization`, `amount` deve ser menor ou igual ao Valor Presente da parcela.                |
| EVC100030  | 400  | Em `nominal_amount`, todas as parcelas selecionadas devem ser futuras (não vencidas na `reference_date`). |
| EVC100031  | 400  | Em `nominal_amount`, `amount` deve ser menor ou igual à soma dos valores nominais das parcelas selecionadas. |
| EVC100032  | 400  | Nenhuma parcela selecionada receberia `expected_amount` positivo — o evento não é criado.              |
| EVC100033  | 400  | A soma dos `expected_amount` distribuídos difere do `amount` informado em mais de R$ 0,01.            |
| EVC100034  | 400  | Alguma parcela selecionada ficaria com `expected_amount` zero — selecione apenas parcelas que o `amount` cubra. |
| EVC100035  | 400  | `amount` excede a soma dos Valores Presentes das parcelas selecionadas (tipos precificados a Valor Presente). |

Consulte o [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros) para resolução completa.

---

## **Veja também**

- [Simular Valor Presente da Amortização Extraordinária](./simular-valor-presente.md)
- [Consultar Amortização Extraordinária](./consultar-amortizacao.md)
- [Conceito](../conceito.md)
- [Roteiro de Integração](../../roteiro-integracao/roteiro-integracao-padrao.md)
- [Regras de Negócio](../regras-de-negocio.md)
- [Exemplos](../exemplos.md)

---

# Simular Valor Presente da Amortização Extraordinária

URL: /documentation/escrituracao/amortizacao-extraordinaria/endpoints/simular-valor-presente

Este endpoint simula uma amortização extraordinária do tipo `present_amount` sem criar nenhum evento — é um cálculo puro, sem efeitos colaterais. A partir das parcelas informadas em `installment_list`, o serviço calcula e devolve o `amount` total (Valor Presente) do evento extraordinário que seria criado, além do Valor Presente de cada `event_conciliation` (tipo `extraordinary`) por parcela — o integrador não calcula Valor Presente no seu lado.

O `amortization_type` não é enviado na requisição: por se tratar de uma simulação de Valor Presente, o tipo é sempre `present_amount`. O `amount` também não é enviado — ele é o resultado do cálculo. A `reference_date` é fornecida pelo chamador e é a única referência temporal usada pelo serviço na classificação de vencidos e no desconto pro-rata; na simulação, a `due_date` é assumida igual à `reference_date`.

O response é o payload de criação pronto para uso: basta remover o campo `event_conciliation_list` — que é apenas informativo — e enviá-lo como body do [Criar Amortização Extraordinária](./criar-amortizacao.md) para efetivar a amortização simulada.

---

## **Request**
ENDPOINT /event_conciliation/extraordinary_event/present_value_simulation
MÉTODO POST

### **Request Body**

```json
{
  "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e",
  "investment_key": "<investment_key>",
  "reference_date": "2026-04-24",
  "installment_list": [1, 2]
}
```

### **Request Body Params**

| Campo              | Tipo                    | Obrigatório | Descrição                                                                                                                                                                                                   |
|--------------------|-------------------------|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `security_key`     | string (UUID)           | Sim         | Chave única do ativo (`security`) sobre o qual a amortização será simulada.                                                                                                                                 |
| `investment_key`   | string (UUID)           | Sim         | Chave do investimento alvo. Usada como base proporcional no cálculo do Valor Presente.                                                                                                                       |
| `reference_date`   | string (date)           | Sim         | Data de referência em formato `YYYY-MM-DD`. **Fornecida pelo chamador** — o serviço a usa como "hoje" para classificar parcelas vencidas e aplicar o desconto pro-rata do Valor Presente. Na simulação, também é usada como `due_date`. |
| `installment_list` | array de inteiros (≥ 1) | Sim         | Lista de `installment_number` (não UUIDs) das parcelas-alvo, com `minItems: 1`. O serviço resolve cada número contra `installment_number` da `security`; números inexistentes retornam `EVC000007`.          |

Diferente da criação, `amortization_type`, `amount` e `due_date` **não são enviados**: o tipo é sempre `present_amount`, o `amount` é calculado pelo serviço e a `due_date` é assumida igual à `reference_date`.

---

## **Response**
STATUS 200

Response Body
```json
{
  "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e",
  "investment_key": "<investment_key>",
  "amortization_type": "present_amount",
  "amount": 4750.00,
  "reference_date": "2026-04-24",
  "due_date": "2026-04-24",
  "installment_list": [1, 2],
  "event_conciliation_list": [
    {
      "installment_number": 1,
      "amount": 2400.00
    },
    {
      "installment_number": 2,
      "amount": 2350.00
    }
  ]
}
```

### **Response Body Params**

| Campo                     | Tipo            | Descrição                                                                                                                                       |
|---------------------------|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
| `security_key`            | string (UUID)   | Chave do ativo — ecoa o valor enviado.                                                                                                          |
| `investment_key`          | string (UUID)   | Chave do investimento alvo — ecoa o valor enviado.                                                                                              |
| `amortization_type`       | string          | Sempre `present_amount` — preenchido pelo serviço para compor o payload de criação.                                                            |
| `amount`                  | number          | Valor Presente total calculado para o evento extraordinário (soma dos `amount` de `event_conciliation_list`).                                   |
| `reference_date`          | string (date)   | Data de referência — ecoa o valor enviado.                                                                                                      |
| `due_date`                | string (date)   | Data alvo de liquidação — igual à `reference_date` enviada.                                                                                     |
| `installment_list`        | array de inteiros | Parcelas-alvo — ecoa o valor enviado.                                                                                                         |
| `event_conciliation_list` | array           | Valor Presente por parcela dos `event_conciliation` (tipo `extraordinary`) que seriam gerados. **Apenas para visualização — não entra no payload de criação.** **[Objeto event_conciliation_list](#objeto-event_conciliation_list)**. |

:::info
O campo `event_conciliation_list` é **apenas para visualização** da simulação de cada parcela — ele **não deve ser incluído** no payload de criação do evento extraordinário. Para efetivar a amortização simulada, envie o response **sem** `event_conciliation_list` como body do [Criar Amortização Extraordinária](./criar-amortizacao.md).
:::

### **Objeto event_conciliation_list**

| Campo                | Tipo    | Descrição                                                                                              |
|----------------------|---------|----------------------------------------------------------------------------------------------------------|
| `installment_number` | integer | Número da parcela (`installment_number`) a que este evento de conciliação se refere.                   |
| `amount`             | number  | Valor Presente calculado para o `event_conciliation` (tipo `extraordinary`) desta parcela.             |

---

## **Erros**

| Código     | HTTP | Significado                                                                                                                          |
|------------|------|----------------------------------------------------------------------------------------------------------------------------------------|
| EVC100002  | 400  | `installment_list` é obrigatório e não pode ser vazio.                                                                               |
| EVC100004  | 400  | Alguma parcela informada não pertence à `security` alvo.                                                                             |
| EVC000007  | 404  | Algum inteiro em `installment_list` não corresponde a nenhum `installment_number` da `security` (`InstallmentNumberNotFound`).       |
| QIT000001  | 400  | Falha de schema — por exemplo, item de `installment_list` que não é inteiro ≥ 1.                                                     |
| EVC100008  | 400  | Já existe uma amortização extraordinária pendente para a parcela — cancele-a antes de simular/criar outra.                           |
| EVC100013  | 424  | Dependência temporariamente indisponível (Failed Dependency). Transitório — repita após o restabelecimento.                          |

O `EVC100005` (`amount` insuficiente) não se aplica à simulação — o `amount` é calculado pelo serviço, não enviado.

Consulte o [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros) para resolução completa.

---

## **Veja também**

- [Criar Amortização Extraordinária](./criar-amortizacao.md)
- [Consultar Amortização Extraordinária](./consultar-amortizacao.md)
- [Conceito](../conceito.md)
- [Roteiro de Integração](../../roteiro-integracao/roteiro-integracao-padrao.md)
- [Regras de Negócio](../regras-de-negocio.md)
- [Exemplos](../exemplos.md)

---

# Exemplos — Amortização Extraordinária

URL: /documentation/escrituracao/amortizacao-extraordinaria/exemplos

Esta página apresenta dois cenários de criação. A interação do integrador é **fire-and-forget**: realiza apenas a chamada de criação e a QI Tech orquestra liquidação, finalização e cancelamento internamente. Não há webhook tenant-facing dedicado às transições de status do `event_conciliation` extraordinário; a confirmação do efeito da operação é observada via os relatórios e webhooks já existentes para a operação subjacente (ex.: `commercial_paper.operation_status_change`).

## Cenário 1: quitação antecipada parcial de uma parcela (early_amortization)

Cobre uma única parcela futura, com pagamento parcial permitido.

`POST /event_conciliation/extraordinary_event`

```json
{
  "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e",
  "investment_key": "<investment_key>",
  "amortization_type": "early_amortization",
  "amount": 1500.00,
  "reference_date": "2026-04-24",
  "due_date": "2026-04-24",
  "installment_list": [3]
}
```

Resposta: `201 Created`

```json
{
  "extraordinary_event_conciliation_key": "11111111-1111-4111-8111-111111111111",
  "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e",
  "amortization_type": "early_amortization",
  "total_expected_amount": 1500.00,
  "total_discount_amount": 0,
  "status": "pending_conciliation",
  "reference_date": "2026-04-24",
  "due_date": "2026-04-24",
  "event_conciliation_list": [
    {
      "event_conciliation_key": "22222222-2222-4222-8222-222222222222",
      "installment_key": "33333333-3333-4333-8333-333333333333",
      "expected_amount": 1500.00,
      "discount_amount": 0,
      "due_date": "2026-04-24",
      "status": "pending_conciliation",
      "event_conciliation_type": "extraordinary"
    }
  ]
}
```

A partir desse 201 a integração está concluída do lado do integrador. Quando o pagamento de R$ 1.500,00 atingir a conta de liquidação correspondente, a QI Tech (account-liquidation-api) liquida o evento de conciliação da parcela internamente e atualiza o `paid_amount`; quando a soma cobre `total_expected_amount - tolerance_amount`, o parent transita para `paid`. Se o pagamento não entrar, o evento é cancelado ou finalizado pela rotina diária de settlement do security-service.

## Cenário 2: quitação total com desconto (present_amount com 2 installments)

Cria uma amortização com desconto consolidado cobrindo duas parcelas.

`POST /event_conciliation/extraordinary_event`

```json
{
  "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e",
  "investment_key": "<investment_key>",
  "amortization_type": "present_amount",
  "amount": 5000.00,
  "reference_date": "2026-04-24",
  "due_date": "2026-04-24",
  "installment_list": [1, 2],
  "total_discount": 100.00
}
```

Resposta `201 Created` — dois eventos de conciliação da parcela são gerados com os valores distribuídos conforme o engine de `present_amount` (juros → multa → principal). Veja [Criar Amortização Extraordinária](./endpoints/criar-amortizacao.md) para o shape completo da resposta.

A partir do 201 a interação do integrador é a mesma do Cenário 1: a QI Tech liquida cada evento de conciliação da parcela quando os pagamentos correspondentes entram, e finaliza ou cancela o evento internamente caso os valores não cheguem dentro da janela de settlement.

## Cenário 3: quitação de parcelas futuras pelo valor nominal (nominal_amount)

Emissor quer quitar as parcelas 3 e 4 antes do vencimento pagando o valor nominal de cada uma (principal + juros no vencimento), sem desconto a Valor Presente. A `reference_date` é anterior ao vencimento de ambas.

```json
{
  "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e",
  "investment_key": "<investment_key>",
  "amortization_type": "nominal_amount",
  "amount": 18670.00,
  "reference_date": "2026-02-08",
  "due_date": "2026-06-06",
  "installment_list": [3, 4]
}
```

Resposta `201 Created` — um evento de conciliação da parcela por parcela, com `expected_amount` igual ao valor nominal de cada uma (`9360.00` e `9310.00` neste exemplo). Se o `amount` fosse menor que a soma, a parcela 3 seria coberta primeiro e a parcela 4 receberia o restante. Parcelas vencidas retornam `EVC100030`; `amount` acima da soma dos valores nominais retorna `EVC100031`. A liquidação aceita pagamento parcial, como em `early_amortization`.

## Cenário 4: quitação integral com valor negociado (full_amortization)

Emissor e investidor acordam quitar as parcelas 1 e 2 por R$ 10.000,00, embora os Valores Presentes na `reference_date` sejam R$ 9.460,00 e R$ 9.410,00. O `amount` é rateado proporcionalmente ao Valor Presente e cada parcela é quitada integralmente na liquidação.

```json
{
  "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e",
  "investment_key": "<investment_key>",
  "amortization_type": "full_amortization",
  "amount": 10000.00,
  "reference_date": "2026-02-08",
  "due_date": "2026-02-08",
  "installment_list": [1, 2]
}
```

Resposta `201 Created` — dois eventos de conciliação da parcela com `expected_amount` `5013.25` e `4986.75` (a soma é igual ao `amount`) e `discount_amount` `4446.75` e `4423.25`. Um `amount` acima da soma dos Valores Presentes retorna `EVC100035`; um `amount` pequeno demais para dar cota positiva a todas as parcelas retorna `EVC100034`.

## Troubleshooting

Códigos de erro mais comuns ao chamar a criação. Para a lista completa, consulte o [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros).

- **`EVC100015`** (400, EarlyAmortizationRequiresSingleInstallment) — `early_amortization` aceita exatamente uma parcela em `installment_list`. Reduza para 1.
- **`EVC000007`** (404, InstallmentNumberNotFound) — algum `installment_number` enviado em `installment_list` não existe na `security` alvo. Confira os números retornados em `GET /security/security/{security_key}` antes de chamar.
- **`QIT000001`** (400) — schema rejeitado. Causa típica: enviar o campo legado `installment_key_list` (removido) ou itens não inteiros em `installment_list`.
- **`EVC100016`** (400, EarlyAmortizationInstallmentOverdue) — a parcela alvo de `early_amortization` está vencida e não é elegível. Selecione uma parcela futura.
- **`EVC100017`** (400, EarlyAmortizationAmountExceedsPresentValue) — em `early_amortization`, o `amount` excedeu o Valor Presente da parcela. Confirme o PV antes de chamar.
- **`EVC100030`** (400, InstallmentNotEligibleForNominalAmortization) — em `nominal_amount`, alguma parcela de `installment_list` já está vencida na `reference_date`. Selecione apenas parcelas futuras.
- **`EVC100031`** (400, NominalAmountExceedsInstallmentsNominalValue) — em `nominal_amount`, o `amount` excedeu a soma dos valores nominais (principal + juros) das parcelas selecionadas. Reduza o `amount`.
- **`EVC100033`** (400, DistributionDoesNotMatchAmount) — a soma dos `expected_amount` distribuídos difere do `amount` informado em mais de R$ 0,01. Em `present_amount`, envie `amount` igual à soma dos Valores Presentes menos o `total_discount`.
- **`EVC100034`** (400, DistributionWithZeroInstallment) — alguma parcela selecionada ficaria com `expected_amount` zero (por exemplo, `total_discount` igual ao Valor Presente, ou `amount` que se esgota antes da última parcela). Selecione apenas parcelas que o `amount` cubra.
- **`EVC100035`** (400, AmountExceedsInstallmentsPresentValue) — o `amount` excede a soma dos Valores Presentes das parcelas selecionadas. Reduza o `amount`.
- **`EVC100013`** (424, SecurityApiUnavailable) — Security API temporariamente indisponível ao buscar o Valor Presente; é transitório. Aguarde e repita a chamada.
- **`SEC000031`** (400, PostFixedSecurityNotSupported) — ativos pós-fixados (CDI, IPCA, IGPM) não são suportados na V1. Use ativos `pre_price` ou `pre_sac`.

## Veja também

- [Conceito](./conceito.md)
- [Roteiro de Integração](../roteiro-integracao/roteiro-integracao-padrao.md)
- [Regras de Negócio](./regras-de-negocio.md)
- [Criar Amortização Extraordinária](./endpoints/criar-amortizacao.md)
- [Consultar Amortização Extraordinária](./endpoints/consultar-amortizacao.md)
- [Recompra de Operação](./recompra-de-operacao.md)
- [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros)

---

# Amortização com Recompra

URL: /documentation/escrituracao/amortizacao-extraordinaria/recompra-de-operacao

## Visão geral

A **recompra** é o fluxo em que uma **nova operação** de nota comercial é emitida para "recomprar" uma ou mais amortizações extraordinárias em aberto de uma operação existente. O cenário típico: o devedor tem uma operação em aberto e, junto com o investidor, decide recomprá-la — por refinanciamento ou por qualquer outro motivo negociado. Em vez de quitar a dívida com recursos próprios, eles estruturam uma nova operação cujo desembolso liquida automaticamente as amortizações extraordinárias escolhidas.

A nova operação é emitida pelo **mesmo devedor** (`issuer`) dos eventos que estão sendo recomprados. A recompra pode abranger:

- **Uma única amortização extraordinária** — o caso mais comum, recomprando uma operação.
- **Múltiplos ativos** — passando várias `extraordinary_event_conciliation_key`, inclusive de `security` diferentes, quando o devedor quer recomprar mais de um ativo na mesma nova operação.

A recompra não é uma chamada de API separada: ela é declarada **no momento da criação da nova operação**, informando a lista de chaves dos eventos extraordinários a recomprar.

## Pré-requisito

Cada amortização extraordinária a ser recomprada precisa **já existir** — criada previamente pelo fluxo de [amortização extraordinária](./endpoints/criar-amortizacao.md) — e estar em `pending_conciliation` no momento em que a nova operação é criada. São essas chaves (`extraordinary_event_conciliation_key`) que você referencia na recompra.

:::warning Datas precisam casar com o desembolso
A `reference_date` e a `due_date` informadas **na criação do evento extraordinário** precisam corresponder à **data de desembolso** da nova operação de recompra. Se essas datas não baterem com o desembolso, os eventos **não são desembolsados corretamente e são cancelados automaticamente** — a recompra não se efetiva. Planeje a `reference_date`/`due_date` do evento extraordinário já considerando quando a nova operação será desembolsada.
:::

## Como acionar

A recompra é declarada no [Cadastro de Operação de Nota Comercial](../emissao-de-notas/cadastro-operacao/criar-operacao.md) (`POST /commercial_paper/operation`): basta enviar, junto com os campos normais de criação da operação, o campo `extraordinary_event_conciliation_key_list` com as chaves dos eventos extraordinários que deseja recomprar.

```json
{
    "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e",
    "issuer_bank_account": {
        "account_number": "4464541",
        "account_digit": "3",
        "account_branch": "0001",
        "financial_institution_code_number": "329",
        "financial_institution_ispb": "32402502",
        "account_type": "checking"
    },
    "investors": [
        {
            "investor_key": "70b1b638-ca56-4eb3-9a88-2fd5ffd077a7",
            "subscription_percentage": 100,
            "bank_account": {
                "account_number": "33400254",
                "account_digit": "3",
                "account_branch": "0001",
                "financial_institution_code_number": "329",
                "financial_institution_ispb": "32402502",
                "account_type": "checking"
            }
        }
    ],
    "issue_date": "2025-01-23",
    "financial": {
        "interest_type": "pre_price_days",
        "financial_base_date": "2025-01-23",
        "released_amount": 1000000,
        "number_of_installments": 5,
        "prefixed_interest_rate": {
            "interest_base": "calendar_days_365",
            "monthly_rate": 0.05
        },
        "fine_delay_rate": {
            "interest_base": "calendar_days_365",
            "monthly_rate": 0.01
        },
        "contract_fine_rate": 0.02,
        "fees": [
            {
                "amount": 5,
                "amount_type": "percentage",
                "fee_type": "structuring_fee"
            }
        ]
    },
    "extraordinary_event_conciliation_key_list": [
        "11111111-1111-4111-8111-111111111111"
    ]
}
```

O `extraordinary_event_conciliation_key_list` é o **único** acréscimo em relação ao cadastro de operação comum — todos os demais campos seguem o [contrato de criação de operação](../emissao-de-notas/cadastro-operacao/criar-operacao.md). Consulte aquela página para a referência completa de cada campo (`issuer_key`, `issuer_bank_account`, `investors`, `issue_date`, `financial`).

### Campo

| Campo                                      | Tipo                    | Obrigatório | Descrição                                                                                                                                              |
|--------------------------------------------|-------------------------|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
| `extraordinary_event_conciliation_key_list`| array de string (UUID)  | Não         | Lista de chaves das amortizações extraordinárias a recomprar. Itens únicos; uma chave por ativo recomprado. Pode abranger múltiplos `security`. Omita o campo em operações sem recompra. |

## Regra de valor

O valor da nova operação precisa ser suficiente para cobrir o que está sendo recomprado. A regra aplicada na **criação da operação** é:

> A soma do `expected_amount` de todos os eventos referenciados em `extraordinary_event_conciliation_key_list` deve ser **menor ou igual** ao `released_amount` da nova operação. Caso contrário, a criação é rejeitada com **`COM000050`** (400).

:::info `released_amount` e fees
`released_amount` é o **valor de emissão líquido de fees financiados**. Por isso, na prática, o valor de emissão da nova operação precisa cobrir no mínimo o valor dos eventos recomprados **+ fees** — só assim o `released_amount` resultante alcança a soma dos `expected_amount`.
:::

## Desembolso

> **Orquestração interna.** A recompra propriamente dita acontece no desembolso da nova operação e é executada internamente pela QI Tech — o integrador **não chama** nenhum endpoint adicional nesta etapa.

Ao desembolsar a nova operação:

1. As amortizações extraordinárias referenciadas são **liquidadas automaticamente**, transitando de `pending_conciliation` para `paid`.
2. O **restante** — `released_amount − Σ expected_amount`, quando positivo — é **repassado ao devedor**.

Ou seja, parte do desembolso quita os eventos recomprados e o que sobra vai para o devedor, em uma única operação.

## Veja também

- [Conceito](./conceito.md)
- [Criar Amortização Extraordinária](./endpoints/criar-amortizacao.md)
- [Consultar Amortização Extraordinária](./endpoints/consultar-amortizacao.md)
- [Regras de Negócio](./regras-de-negocio.md)
- [Exemplos](./exemplos.md)
- [Roteiro de Integração](../roteiro-integracao/roteiro-integracao-padrao.md)
- [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros)

---

# Regras de Negócio — Amortização Extraordinária

URL: /documentation/escrituracao/amortizacao-extraordinaria/regras-de-negocio

Esta página consolida as invariantes que governam a criação, a liquidação e o cancelamento de uma amortização extraordinária. Consulte-a sempre que as páginas de endpoints citarem um código de erro, um campo ou uma condição que precise de contexto adicional.

## Data de referência (`reference_date`)

A `reference_date` é **fornecida pelo chamador** na requisição de criação e é a única referência temporal usada pelo serviço — o sistema **nunca usa** `date.today()`. Toda lógica dependente de data (classificação de parcelas vencidas, desconto pro-rata do Valor Presente, seleção de parcelas elegíveis para `early_amortization` e `nominal_amount`) parte desse campo. A consulta de Valor Presente ao security-service recebe essa mesma `reference_date`.

## Tipos de amortização

Os 7 tipos suportados e como cada um distribui o `amount` entre as parcelas de `installment_list`:

| Tipo                   | Regra de distribuição entre as parcelas selecionadas                                               | Permite pagamento parcial |
|------------------------|----------------------------------------------------------------------------------------------------|---------------------------|
| `equal_amount`         | Proporcional ao Valor Presente, vencidas primeiro e depois futuras                                 | Não                       |
| `first_installments`   | Sequencial nas N primeiras parcelas selecionadas (por vencimento), N = `number_of_installments`     | Não                       |
| `present_amount`       | Explícita por parcela; desconto ordena juros → multa → principal                                    | Não                       |
| `matured_installments` | Apenas parcelas já vencidas, em ordem de vencimento                                                | Não                       |
| `early_amortization`   | Uma única parcela futura, até o Valor Presente                                                     | **Sim**                   |
| `nominal_amount`       | Parcelas futuras pelo valor nominal (principal + juros), em ordem de vencimento, sem Valor Presente | **Sim**                   |
| `full_amortization`    | Proporcional ao Valor Presente entre todas as parcelas selecionadas, sem cascata; cada parcela é quitada integralmente | Não                       |

`installment_list` (array de `installment_number` inteiros) é **obrigatório para todos os tipos** — omiti-lo retorna `EVC100002`. O serviço resolve cada `installment_number` para a parcela correspondente da `security` e consulta o Valor Presente por parcela selecionada; o `amortization_type` define apenas como o `amount` é distribuído entre essas parcelas.

## Amortização antecipada (`early_amortization`)

`early_amortization` permite pagamento parcial (assim como `nominal_amount`). Todas as seguintes condições se aplicam:

- Exatamente **1** parcela em `installment_list` — caso contrário, `EVC100015`.
- A parcela-alvo **não pode estar vencida** — caso contrário, `EVC100016`.
- O `amount` deve ser **≤ Valor Presente** da parcela — caso contrário, `EVC100017`.
- **Pagamento parcial é permitido.** O estado `paid_amount > 0 AND paid_amount = total_expected_amount - tolerance_amount`.

## Amortização pelo valor nominal (`nominal_amount`)

`nominal_amount` quita parcelas futuras pelo valor nominal — principal mais juros no vencimento — sem trazê-las ao Valor Presente da `reference_date`. Todas as seguintes condições se aplicam:

- Todas as parcelas em `installment_list` devem ter `due_date` maior ou igual à `reference_date` — parcela vencida retorna `EVC100030`.
- O `amount` é distribuído em ordem de vencimento, cobrindo cada parcela pelo valor nominal até se esgotar; a última parcela alcançada pode receber valor parcial.
- O `amount` deve ser **≤ soma dos valores nominais** das parcelas selecionadas — caso contrário, `EVC100031`.
- **Pagamento parcial é permitido** na liquidação, com o mesmo estado derivado descrito para `early_amortization`.

## Amortização integral (`full_amortization`)

`full_amortization` usa o `amount` informado para quitar **todas** as parcelas de `installment_list`, independentemente do Valor Presente de cada uma:

- O `amount` é rateado entre as parcelas proporcionalmente ao Valor Presente na `reference_date`, sem cascata — nenhuma parcela fica sem cota.
- Cada `event_conciliation` nasce com `expected_amount` igual à sua cota e `discount_amount` igual à diferença entre o Valor Presente e a cota.
- O `amount` não pode exceder a soma dos Valores Presentes das parcelas selecionadas — caso contrário, `EVC100035`.
- Na liquidação, o pagamento da cota dá baixa **integral** na parcela no security-service: o valor pago é registrado como pago e a diferença como desconto da parcela. O mesmo vale para `present_amount`.

## Consistência entre `amount` e a distribuição

Após distribuir o `amount`, o serviço valida o resultado para **todos** os tipos, nesta ordem:

1. `amount` maior que a soma dos Valores Presentes das parcelas distribuídas → `EVC100035` (tipos precificados a Valor Presente; `early_amortization` e `nominal_amount` mantêm `EVC100017` e `EVC100031`).
2. Alguma parcela selecionada ficaria com `expected_amount` igual a zero → `EVC100034`. Nenhum evento é criado com filhos zerados; selecione apenas parcelas que o `amount` cubra.
3. A soma dos `expected_amount` distribuídos difere do `amount` em mais de R$ 0,01 → `EVC100033`. Em `present_amount`, o `amount` precisa ser igual à soma dos Valores Presentes menos o `total_discount`.

Os `expected_amount` são gravados em centavos, com o resíduo de arredondamento na última parcela, de modo que `total_expected_amount` do evento seja sempre igual à soma dos filhos.

## Fluxo de liquidação

> **Orquestração interna.** A liquidação dos eventos extraordinários é executada pela QI Tech (account-liquidation-api) ao detectar o pagamento — o integrador **não chama** nenhum endpoint nesta etapa, nem recebe webhook dedicado às transições de status. As regras abaixo descrevem o comportamento interno para você entender o que ocorre após a criação.

**Liquidação ordinária emite o total completo (regra 4).** A liquidação ordinária na `due_date` continua emitindo o `total_amount` completo da parcela via SQS; não há subtração do `paid_amount`. O evento reconcilia o estado parcial-pago no seu próprio engine de `early_amortization`.

## Cancelamento e finalização

> **Orquestração interna.** Cancelamento e finalização são disparados por uma rotina diária e — o integrador **não chama** nenhum endpoint para cancelar ou finalizar uma amortização extraordinária, e não há webhook tenant-facing dedicado a essas transições. A descrição abaixo é informativa.

## Veja também

- [Conceito](./conceito.md)
- [Roteiro de Integração](../roteiro-integracao/roteiro-integracao-padrao.md)
- [Criar Amortização Extraordinária](./endpoints/criar-amortizacao.md)
- [Consultar Amortização Extraordinária](./endpoints/consultar-amortizacao.md)
- [Recompra de Operação](./recompra-de-operacao.md)
- [Exemplos](./exemplos.md)
- [Catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros)

---

# Catálogo de Erros

URL: /documentation/escrituracao/catalogo-erros/catalogo-erros

## Formatação dos erros

Todas APIs da integração de escrituração retornam os erros de API formatados segundo a descrição a seguir:

Error Response Body

```json
{
  "title": "HTTP Status code name",
  "description": "An english description of the error",
  "translation": "Uma descrição em português do erro",
  "code": "ERROR_UNIQUE_CODE"
}
```

---

## Tabela de erros possíveis no processo de homologação do emissor

| Código HTTP | Código do Erro | Título                  | Descrição (eng)                                              | Tradução (pt-BR)                                         |
|------------|----------------|-------------------------|-------------------------------------------------------------|----------------------------------------------------------|
| 400        | ISS000003      | Bad Request            | Issuer already exists in database.                         | Emissor já existe na base de dados.                     |
| 404        | ISS000004      | Not Found              | Issuer representative not found.                           | Representante do emissor não encontrado.                 |
| 404        | ISS000005      | Not Found              | Bank account not found.                                    | Conta bancária não encontrada.                          |
| 404        | ISS000006      | Not Found              | Issuer document not found.                                | Documento do emissor não encontrado.                    |
| 404        | ISS000007      | Not Found              | Issuer representative document not found.                 | Documento do representante do emissor não encontrado.   |
| 404        | ISS000008      | Not Found              | Issuer contact information not found.                     | Contato do emissor não encontrado.                      |
| 404        | ISS000009      | Not Found              | Issuer not found.                                         | Emissor não encontrado.                                 |
| 404        | ISS0000010     | Not Found              | Signer Group not found.                                   | Grupo de assinantes não encontrado.                     |
| 400        | ISS0000011     | Bad Request            | Issuer must be in status in_filling to allow this action. | Emissor deve estar no estado in_filling para permitir esta ação. |
| 400        | ISS0000018     | Bad Request            | Document sent is invalid or quality is low.               | Documento enviado é inválido ou de baixa qualidade.     |
| 400        | ISS0000012     | Bad Request            | Deleting the main account is not allowed, please set a new main account first. | Não é permitido deletar a conta principal, defina uma nova conta principal primeiro. |
| 400        | ISS0000013     | Bad Request            | Deleting the main contact is not allowed, please set a new main contact first. | Não é permitido deletar o contato principal, defina um novo contato principal primeiro. |
| 400        | ISS0000014     | Bad Request            | Issuer must have at least one contact information.        | Emissor precisa ter ao menos uma informação de contato. |
| 400        | ISS0000015     | Bad Request            | Tenant already has access to this issuer.                 | Acesso aos dados do emissor já foi concedido.           |
| 400        | ISS0000016     | Bad Request            | Failed trying to contact issuer, please retry.            | Falha ao enviar mensagem ao emissor, tente novamente.   |
| 400        | ISS0000017     | Bad Request            | Invalid link.                                             | Link inválido.                                          |
| 400        | ISS0000025     | Bad Request            | The file of the following documents is no longer stored and must be sent again: `{documents}`. | O arquivo dos seguintes documentos não está mais armazenado e precisa ser reenviado: `{documents}`. |
| 404        | ISS0000028     | Not Found              | Issuer auto signature not found.                          | Autoassinatura do emissor não encontrada.               |
| 409        | ISS0000029     | Conflict               | Issuer already has an active auto signature.              | Emissor já possui uma autoassinatura ativa.             |
| 400        | ISS0000030     | Bad Request            | Issuer auto signature is not in a status that allows this operation. | A autoassinatura do emissor não está em um status que permite esta operação. |
| 400        | ISS0000032     | Bad Request            | Issuer must be approved to allow this action.             | Emissor deve estar aprovado para permitir esta ação.    |
| 400        | ISS0000033     | Bad Request            | Tenant is not enabled for auto signature.                 | Tenant não está habilitado para autoassinatura.         |

## Tabela de erros possíveis no processo de homologação do investidor

| Código HTTP | Código do Erro | Título                  | Descrição (eng)                                              | Tradução (pt-BR)                                         |
|------------|----------------|-------------------------|-------------------------------------------------------------|----------------------------------------------------------|
| 400        | INV000003      | Bad Request            | Investor already exists in database.                        | Emissor já existe na base de dados.                     |
| 404        | INV000004      | Not Found              | Investor representative not found.                          | Representante do emissor não encontrado.                 |
| 404        | INV000005      | Not Found              | Bank account not found.                                     | Conta bancária não encontrada.                          |
| 404        | INV000006      | Not Found              | Investor document not found.                               | Documento do emissor não encontrado.                    |
| 404        | INV000007      | Not Found              | Investor representative document not found.                | Documento do representante do emissor não encontrado.   |
| 404        | INV000008      | Not Found              | Investor contact information not found.                    | Contato do emissor não encontrado.                      |
| 404        | INV000009      | Not Found              | Investor not found.                                        | Emissor não encontrado.                                 |
| 404        | INV0000010     | Not Found              | Signer Group not found.                                    | Grupo de assinantes não encontrado.                     |
| 400        | INV0000011     | Bad Request            | Investor must be in status in_filling to allow this action. | Emissor deve estar no estado in_filling para permitir esta ação. |
| 400        | INV0000018     | Bad Request            | Document sent is invalid or quality is low.                 | Documento enviado é inválido ou de baixa qualidade.     |
| 400        | INV0000012     | Bad Request            | Deleting the main account is not allowed, please set a new main account first. | Não é permitido deletar a conta principal, defina uma nova conta principal primeiro. |
| 400        | INV0000013     | Bad Request            | Deleting the main contact is not allowed, please set a new main contact first. | Não é permitido deletar o contato principal, defina um novo contato principal primeiro. |
| 400        | INV0000014     | Bad Request            | Investor must have at least one contact information.        | Emissor precisa ter ao menos uma informação de contato. |
| 400        | INV0000015     | Bad Request            | Tenant already has access to this investor.                 | Acesso aos dados do emissor já foi concedido.           |
| 400        | INV0000016     | Bad Request            | Failed trying to contact investor, please retry.            | Falha ao enviar mensagem ao emissor, tente novamente.   |
| 400        | INV0000017     | Bad Request            | Invalid link.                                              | Link inválido.                                          |

## Tabela de erros possíveis no processo de emissão da nota comercial

| Código HTTP | Código do Erro  | Título                  | Descrição (eng)                                              | Tradução (pt-BR)                                         |
|------------|----------------|-------------------------|-------------------------------------------------------------|----------------------------------------------------------|
| 400        | COM000001       | Bad Request            | Document is not valid.                                      | Documento fornecido não é válido.                        |
| 400        | COM000002       | Bad Request            | Tenant must be configured before use this endpoint.        | Tenant precisa ser configurado antes de utilizar este endpoint. |
| 409        | COM000003       | Conflict               | Tenant configuration already exists.                       | Configuração para este tenant já existe.                 |
| 400        | COM000004       | Bad Request            | Investor with key (investor_key) is not allowed. Please check. | Investidor com a chave (investor_key) não permitido. Cheque o cadastro. |
| 400        | COM000005       | Bad Request            | Issuer with key (issuer_key) is not allowed. Please check. | Emissor com a chave (issuer_key) não permitido. Cheque o cadastro. |
| 400        | COM000006       | Bad Request            | Operation with more than one investor functionality not available yet. | Operação com mais de um investidor não disponível ainda. |
| 404        | COM000007       | Not Found              | Operation (operation_key) not found.                       | Operação (operation_key) não encontrada.                 |
| 403        | COM000008       | Forbidden              | Operation (operation_key) does not belong to tenant.       | Operação (operation_key) não pertence ao tenant.         |
| 400        | COM000010       | Bad Request            | Operations cannot be updated outside of in_filling status. | Operação não pode ser atualizada fora do status in_filling. |
| 404        | COM000011       | Not Found              | Related party not found.                                   | Parte relacionada não encontrada.                        |
| 400        | COM000012       | Bad Request            | Related party (related_party_key) is not associated with operation (operation_key). | A parte relacionada (related_party_key) não está associada com a operação (operation_key). |
| 404        | COM000013       | Not Found              | Signer Group not found.                                    | Grupo de assinantes não encontrado.                      |
| 400        | COM000014       | Bad Request            | Signer group (signer_group_key) is not associated with related party (related_party_key). | O grupo de assinantes (signer_group_key) não está associado com a parte relacionada (related_party_key). |
| 400        | COM000015       | Bad Request            | Signer list does not match minimum required signers field. | Lista de assinantes não é compatível com o mínimo de assinantes enviado. |
| 404        | COM000016       | Not Found              | Document not found.                                        | Documento não encontrado.                                |
| 400        | COM000017       | Bad Request            | Document (document_key) is not associated with related party (related_party_key). | O documento (document_key) não está associado com a parte relacionada (related_party_key). |
| 400        | COM000018       | Bad Request            | Document sent is invalid or quality is low.               | Documento enviado é inválido ou de baixa qualidade.      |
| 400        | COM000019       | Bad Request            | Delete issuer or investor is not allowed.                 | Não é possível deletar o emissor ou investidor.         |
| 400        | COM000020       | Bad Request            | Operation is in a final status and cannot be modified.    | Operação já está em um estado final e não pode ser atualizada. |
| 400        | COM000021       | Bad Request            | Operation is not in analysis.                             | Operação não está em análise.                           |
| 400        | COM000022       | Bad Request            | Document not signed yet.                                  | Documento ainda não foi assinado.                        |
| 400        | COM000023       | Bad Request            | Document not available yet.                               | Documento ainda não foi gerado.                         |
| 400        | COM000024       | Bad Request            | Failed to send document to signature, please retry.      | Falha ao enviar documento para assinatura, tente novamente. |
| 404        | COM000025       | Not Found              | Collateral not found.                                     | Garantia não encontrada.                                 |
| 400        | COM000026       | Bad Request            | Collateral (collateral_key) is not associated with operation (operation_key). | A garantia (collateral_key) não está associada com a operação (operation_key). |
| 400        | COM000027       | Bad Request            | Metadata not found.                                       | Metadado não encontrado.                                |
| 400        | COM000028       | Bad Request            | Operation is canceled and cannot be modified.            | Operação está cancelada e não pode ser atualizada.      |
| 400        | COM000061       | Bad Request            | Third-party disbursement slip amount does not match the operation's `released_amount`. | Valor do boleto do desembolso a terceiro diferente do `released_amount` da operação. |
| 400        | COM000062       | Bad Request            | Tenant is not enabled for third-party disbursement.      | Tenant não habilitado para desembolso a terceiro.        |
| 400        | COM000063       | Bad Request            | Third-party disbursement beneficiary document is invalid. | Documento do beneficiário do desembolso a terceiro inválido. |
| 409        | COM000068       | Conflict               | Vehicle with chassis (chassis) is already marked and cannot be used as vehicle_stock collateral. | O veículo com chassi (chassis) já está gravado e não pode ser utilizado como garantia de estoque de veículos. |
| 422        | COM000069       | Unprocessable Entity   | Vehicle with chassis (chassis) could not be marked. | O veículo com chassi (chassis) não pôde ser gravado. |
| 422        | COM000070       | Unprocessable Entity   | Vehicles with chassis (chassis_list) are not eligible for marking. | Os veículos com chassi (chassis_list) não são elegíveis para gravação. |
| 400        | COM000071       | Bad Request            | Third-party disbursement `pix_key` of type `cpf`/`cnpj` has invalid check digits. | A `pix_key` de tipo `cpf`/`cnpj` do desembolso a terceiro tem dígito verificador inválido. |
| 400        | COM000072       | Bad Request            | The operation uses external signature and `p7s_base64` was not sent. | A operação usa assinatura externa e o `p7s_base64` não foi enviado. |
| 400        | COM000073       | Bad Request            | The signature file could not be read as a CMS structure, or exceeds the accepted size. | O arquivo de assinatura não pôde ser lido como estrutura CMS, ou excede o tamanho aceito. |
| 422        | COM000074       | Unprocessable Entity   | The signature does not match the document issued by QI Tech. | A assinatura não corresponde ao documento emitido pela QI Tech. |
| 409        | COM000075       | Conflict               | The document already had a signature accepted. | O documento já teve uma assinatura aceita. |
| 400        | COM000077       | Bad Request            | Operation issuer is not enabled for auto signature. | Emissor da operação não está habilitado para auto-assinatura. |

## Tabela de erros possíveis no processo de integralização de cotas

| Código HTTP | Código do Erro  | Título                  | Descrição (eng)                                              | Tradução (pt-BR)                                         |
|------------|----------------|-------------------------|-------------------------------------------------------------|----------------------------------------------------------|
| 400        | INT000001       | Bad Request            | Document is not valid.                                      | Documento fornecido não é válido.                        |
| 404        | INT000002       | Not Found              | Integralization process (integralizaion_key) not found.    | Processo de integralização (integralizaion_key) não encontrado. |
| 403        | INT000003       | Forbidden              | Integralization process (integralizaion_key) does not belong to tenant. | Processo de integralização (integralizaion_key) não pertence ao tenant. |
| 404        | INT000004       | Not Found              | Subscription (subscription_key) not found.                 | Subscrição (subscription_key) não encontrada.           |
| 400        | INT000005       | Bad Request            | Subscription (subscription_key) is not associated with integralization process (integralizaion_key). | A subscrição (subscription_key) não está associada com o processo de integralização (integralizaion_key). |
| 404        | INT000006       | Not Found              | Subscription payment not found.                            | Pagamento de subscrição não encontrado.                  |
| 400        | INT000007       | Bad Request            | Subscription payment (subscription_payment_key) is not associated with subscription (subscription_key). | O pagamento de subscrição (subscription_payment_key) não está associado com a subscrição (subscription_key). |
| 400        | INT000008       | Bad Request            | Subscription payment already analyzed.                     | Pagamento de subscrição já foi analisado.               |
| 409        | INT000009       | Conflict               | Integralization process for (operation_key) already exists. | Já existe um processo de integralização para a operação (operation_key). |
| 400        | INT000010       | Bad Request            | Subscripted quantity (subscripted_quantity) is bigger than the available quantity (available_quantity). | A quantidade de cotas subscritas (subscripted_quantity) é maior do que a quantidade disponível (available_quantity). |
| 400        | INT000011       | Bad Request            | Subscription is not waiting payment yet.                   | Subscrição ainda não está aguardando pagamento.         |
| 400        | INT000012       | Bad Request            | Subscription is in a final state and cannot be canceled.   | Subscrição já está em um status final e não pode ser cancelada. |
| 400        | INT000013       | Bad Request            | Subscription is not waiting payment yet.                   | Subscrição não está aguardando pagamento ainda.         |
| 400        | INT000014       | Bad Request            | Document not signed yet.                                   | Documento ainda não foi assinado.                        |
| 400        | INT000015       | Bad Request            | Integralization canceled.                                 | Integralização cancelada.                               |
| 400        | INT000016       | Bad Request            | Integralization cancellation denied. There are integralized quantities. | Cancelamento de integralização negado. Existem cotas integralizadas. |
| 400        | INT000017       | Bad Request            | Creation of subscriptions for an ongoing operation is not available yet. | Ainda não é possível criar subscrições para operações em andamento. |
| 400        | INT000018       | Bad Request            | To create a signature with data different from the original, you must define a recalculation method using the recalculation_method field. | Para criar uma subscrição com data diferente da original é preciso definir um método de recálculo através do campo recalculation_method. |

## Tabela de erros possíveis no processo de amortização extraordinária

| Código HTTP | Código do Erro  | Título             | Descrição (eng)                                                                                            | Tradução (pt-BR)                                                                                          |
|------------|----------------|--------------------|------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------|
| 404        | EVC000007       | Not Found          | An integer in `installment_list` does not match any `installment_number` in the target security (`InstallmentNumberNotFound`). | Um inteiro de `installment_list` não corresponde a nenhum `installment_number` da `security` alvo.        |
| 400        | EVC100001       | Bad Request        | The provided `amortization_type` is not one of the supported values.                                       | O valor de `amortization_type` fornecido não é um dos tipos suportados.                                   |
| 400        | EVC100002       | Bad Request        | `installment_list` is required for every `amortization_type`.     | `installment_list` é obrigatório para todos os tipos de amortização.     |
| 400        | EVC100003       | Bad Request        | `number_of_installments` is required for `first_installments`.     | `number_of_installments` é obrigatório para `first_installments`. |
| 400        | EVC100004       | Bad Request        | One or more installments do not belong to the target security.                                             | Uma ou mais parcelas informadas não pertencem ao ativo informado.                                          |
| 400        | EVC100005       | Bad Request        | The amount does not cover the sum of the selected installments.                                            | O valor informado não cobre a soma das parcelas selecionadas.                                              |
| 400        | EVC100006       | Bad Request        | `total_discount` exceeds the present value of the selected installments.                                   | `total_discount` excede o Valor Presente das parcelas selecionadas.                                        |
| 400        | EVC100007       | Bad Request        | For `matured_installments`, all selected installments must be overdue.                                     | Para `matured_installments`, todas as parcelas selecionadas devem estar vencidas.                          |
| 400        | EVC100008       | Bad Request        | An extraordinary event already exists for the installment.                                                 | Já existe uma amortização extraordinária pendente para a parcela.                                          |
| 424        | EVC100013       | Failed Dependency  | The Security API is temporarily unavailable.                                                               | A Security API está temporariamente indisponível.                                                          |
| 400        | EVC100015       | Bad Request        | `early_amortization` requires exactly one installment in `installment_list`.                               | `early_amortization` requer exatamente uma parcela em `installment_list`.                                  |
| 400        | EVC100016       | Bad Request        | The target installment is not eligible for `early_amortization` (already overdue).                         | A parcela alvo de `early_amortization` está vencida e não é elegível.                                      |
| 400        | EVC100017       | Bad Request        | The `early_amortization` amount exceeds the installment's present value.                                   | O valor de `early_amortization` excede o Valor Presente da parcela.                                        |
| 400        | EVC100030       | Bad Request        | For `nominal_amount`, all selected installments must be due on or after the `reference_date` (not overdue). | Para `nominal_amount`, todas as parcelas selecionadas devem vencer na `reference_date` ou depois (não vencidas). |
| 400        | EVC100031       | Bad Request        | The `nominal_amount` amount exceeds the sum of the selected installments' nominal values.                  | O valor de `nominal_amount` excede a soma dos valores nominais das parcelas selecionadas.                 |
| 400        | EVC100032       | Bad Request        | The amount does not allocate a positive `expected_amount` to any selected installment; no event is created. | O valor informado não atribui `expected_amount` positivo a nenhuma parcela selecionada; nenhum evento é criado. |
| 400        | EVC100033       | Bad Request        | The distributed `expected_amount` total differs from the requested `amount` by more than the tolerance.     | A soma dos `expected_amount` distribuídos difere do `amount` informado além da tolerância.               |
| 400        | EVC100034       | Bad Request        | The amount does not allocate a positive `expected_amount` to one of the selected installments; no event is created. | O valor informado não atribui `expected_amount` positivo a uma das parcelas selecionadas; nenhum evento é criado. |
| 400        | EVC100035       | Bad Request        | The amount exceeds the present value of the selected installments.                                          | O valor informado excede o Valor Presente das parcelas selecionadas.                                       |
| 404        | EVC100011       | Not Found          | No extraordinary event conciliation was found for the provided `extraordinary_event_conciliation_key`.     | Nenhuma amortização extraordinária encontrada para a `extraordinary_event_conciliation_key` informada.     |
| 400        | COM000050       | Bad Request        | On a repurchase operation, the sum of the referenced extraordinary events' `expected_amount` cannot exceed the operation's `released_amount`. | Em uma operação de recompra, a soma do `expected_amount` dos eventos extraordinários referenciados não pode exceder o `released_amount` da operação. |
| 400        | SEC000001       | Bad Request        | The referenced security was not found.                                                                     | O ativo (`security`) informado não foi encontrado.                                                         |
| 404        | SEC000027       | Not Found          | The referenced investment was not found.                                                                   | O investimento (`investment`) informado não foi encontrado.                                                |
| 404        | SEC000029       | Not Found          | The referenced installment was not found.                                                                  | A parcela (`installment`) informada não foi encontrada.                                                    |
| 400        | SEC000030       | Bad Request        | The present value request is invalid (missing `investment_key` or malformed `reference_date`).             | A requisição de Valor Presente é inválida (falta `investment_key` ou `reference_date` mal formatada).       |
| 400        | SEC000031       | Bad Request        | Post-fixed securities (CDI, IPCA, IGPM) are not supported in V1.                                           | Ativos pós-fixados (CDI, IPCA, IGPM) não são suportados na V1.                                            |

## Tabela de erros possíveis no processo de aditamento

| Código HTTP | Código do Erro | Título | Descrição (eng) | Tradução (pt-BR) |
|------------|----------------|--------|-----------------|------------------|
| 404 | AMD000001 | Not Found | Security `{security_key}` not found for this tenant. | Título `{security_key}` não encontrado para esse tenant. |
| 422 | AMD000002 | Unprocessable Entity | Security `{security_key}` is `{security_status}`, only an active security can be amended. | Título `{security_key}` está `{security_status}`, apenas um título ativo pode ser aditado. |
| 422 | AMD000003 | Unprocessable Entity | Operation `{operation_key}` is `{operation_status}`, only a finished operation can be amended. | Operação `{operation_key}` está `{operation_status}`, apenas uma operação com emissão concluída pode ser aditada. |
| 422 | AMD000004 | Unprocessable Entity | Security `{security_key}` is already settled, there is nothing left to amend. | Título `{security_key}` já foi liquidado, não há o que aditar. |
| 422 | AMD000005 | Unprocessable Entity | Financial base date `{financial_base_date}` is in the past. A retroactive amendment is only accepted with a migration origin. | A data base `{financial_base_date}` está no passado. Um aditamento retroativo só é aceito com origem de tombamento. |
| 422 | AMD000006 | Unprocessable Entity | Operation `{change_operation}` is not allowed for change type `{change_type}`. | A operação `{change_operation}` não é permitida para a alteração do tipo `{change_type}`. |
| 422 | AMD000007 | Unprocessable Entity | A target_key is required for a `{change_operation}` on change type `{change_type}`. | Um target_key é obrigatório para `{change_operation}` na alteração do tipo `{change_type}`. |
| 422 | AMD000008 | Unprocessable Entity | Collateral is not supported for instrument `{operation_type}`. | Garantia não é suportada para o instrumento `{operation_type}`. |
| 422 | AMD000009 | Unprocessable Entity | The flow calculation rejected the submitted combination of parameters. | A combinação de parâmetros enviada foi recusada pelo cálculo do fluxo. |
| 409 | AMD000012 | Conflict | Amendment `{amendment_key}` is `{amendment_status}` and does not allow this transition. | O aditamento `{amendment_key}` está `{amendment_status}` e não permite essa transição. |
| 422 | AMD000013 | Unprocessable Entity | Simulation accepts only a financial_flow change, `{change_type}` was sent. Use the validation endpoint for the full change set. | A simulação aceita apenas uma alteração de financial_flow, `{change_type}` foi enviado. Use o endpoint de validação para o conjunto completo. |
| 422 | AMD000014 | Unprocessable Entity | A related party of role_type `{role_type}` cannot be amended. | Uma parte relacionada com role_type `{role_type}` não pode ser aditada. |
| 422 | AMD000015 | Unprocessable Entity | Collateral of type `{collateral_type}` requires documents that were not sent. | A garantia do tipo `{collateral_type}` exige documentos que não foram enviados. |
| 413 | AMD000016 | Payload Too Large | Document `{document_name}` exceeds the maximum accepted size of `{max_size_bytes}` bytes. | O documento `{document_name}` excede o tamanho máximo aceito de `{max_size_bytes}` bytes. |
| 404 | AMD000017 | Not Found | Amendment `{amendment_key}` not found. | Aditamento `{amendment_key}` não encontrado. |
| 403 | AMD000018 | Forbidden | Amendment `{amendment_key}` does not belong to tenant. | O aditamento `{amendment_key}` não pertence ao tenant. |
| 502 | AMD000019 | External Api Call Failed | External api call `{base_response.method}` `{base_response.endpoint}` failed with status `{base_response.response_status}`. | A chamada externa `{base_response.method}` `{base_response.endpoint}` falhou com status `{base_response.response_status}`. |
| 422 | AMD000020 | Unprocessable Entity | Installment `{installment_number}` is `{installment_status}`: an installment with a payment already applied cannot be renegotiated. | A parcela `{installment_number}` está `{installment_status}`: uma parcela com pagamento já aplicado não pode ser renegociada. |
| 422 | AMD000021 | Unprocessable Entity | Operation type `{operation_type}` has no originator mapped. | O tipo de operação `{operation_type}` não tem originador mapeado. |
| 422 | AMD000022 | Unprocessable Entity | Amendment `{amendment_key}` has no signer to dispatch: the operation carries no active signer group for the issuer. | O aditamento `{amendment_key}` não tem signatário para envio: a operação não tem grupo de assinatura ativo para o emissor. |
| 422 | AMD000023 | Unprocessable Entity | Amendment `{amendment_key}` has no amendment_term document to send to signature. | O aditamento `{amendment_key}` não tem documento de termo para enviar à assinatura. |
| 409 | AMD000024 | Conflict | Amendment `{amendment_key}` already exists. | O aditamento `{amendment_key}` já existe. |
| 422 | AMD000025 | Unprocessable Entity | security-service refused to amend security `{security_key}` (`{refusal_code}`): `{refusal_description}` | O security-service recusou o aditamento do título `{security_key}` (`{refusal_code}`): `{refusal_description}` |
| 422 | AMD000026 | Unprocessable Entity | The originator refused to amend operation `{operation_key}` (`{refusal_code}`): `{refusal_description}` | O originador recusou o aditamento da operação `{operation_key}` (`{refusal_code}`): `{refusal_description}` |
| 404 | AMD000027 | Not Found | Tenant `{tenant_key}` has no active billing configuration. | O tenant `{tenant_key}` não tem configuração de cobrança ativa. |
| 422 | AMD000028 | Unprocessable Entity | Pricing method `{pricing_method}` requires `{missing_term}`. | O método de precificação `{pricing_method}` exige `{missing_term}`. |
| 500 | AMD000029 | Internal Server Error | Charge pricing method `{pricing_method}` is seeded but not implemented. | O método de precificação `{pricing_method}` está no banco mas não é implementado. |
| 422 | AMD000030 | Unprocessable Entity | Change `{amendment_change_key}` of type `{change_type}` has no application implemented. | O change `{amendment_change_key}` do tipo `{change_type}` não tem aplicação implementada. |
| 409 | AMD000031 | Conflict | Security `{security_key}` already has amendment `{amendment_key}` on `{amendment_status}`; one amendment at a time. | O título `{security_key}` já tem o aditamento `{amendment_key}` em `{amendment_status}`; um aditamento por vez. |
| 422 | AMD000032 | Unprocessable Entity | Vehicle `{chassis}` is already marked on Geero and can not enter this collateral. | O veículo `{chassis}` já está marcado no Geero e não pode entrar nesta garantia. |
| 422 | AMD000033 | Unprocessable Entity | Vehicle `{chassis}` is not marked on Geero and can not be released from this collateral. | O veículo `{chassis}` não está marcado no Geero e não pode sair desta garantia. |
| 422 | AMD000034 | Unprocessable Entity | Geero refused vehicle `{chassis}` (`{refusal_code}`): `{refusal_description}` | O Geero recusou o veículo `{chassis}` (`{refusal_code}`): `{refusal_description}` |
| 409 | AMD000035 | Conflict | Change `{amendment_change_key}` of amendment `{amendment_key}` waits for the vehicle additions to be applied first. | O change `{amendment_change_key}` do aditamento `{amendment_key}` espera as adições de veículo serem aplicadas primeiro. |
| 422 | AMD000036 | Unprocessable Entity | Vehicle `{chassis}` stays marked: a vehicle addition of amendment `{amendment_key}` failed, so no vehicle is released. | O veículo `{chassis}` continua marcado: uma adição de veículo do aditamento `{amendment_key}` falhou, então nenhum veículo é liberado. |
| 404 | AMD000037 | Not Found | Document `{document_key}` not found on amendment `{amendment_key}`. | O documento `{document_key}` não foi encontrado no aditamento `{amendment_key}`. |
| 422 | AMD000038 | Unprocessable Entity | Document `{document_key}` of amendment `{amendment_key}` has no signed file yet. | O documento `{document_key}` do aditamento `{amendment_key}` ainda não tem arquivo assinado. |
| 422 | AMD000039 | Unprocessable Entity | Amendment `{amendment_key}` has no signature envelope yet. | O aditamento `{amendment_key}` ainda não tem envelope de assinatura. |
| 422 | AMD000040 | Unprocessable Entity | A change of type `{change_type}` cannot elect a term signer. | Uma alteração de `{change_type}` não elege signatário do termo. |
| 422 | AMD000041 | Unprocessable Entity | The `{role_type}` elected as term signer carries no signer_group_list. | A parte relacionada de papel `{role_type}` foi eleita signatária do termo, mas não trouxe signer_group_list. |
| 422 | AMD000042 | Unprocessable Entity | Signer `{signer_name}` has no email, and the signature provider requires one. | O signatário `{signer_name}` não tem e-mail, e a assinatura não é enviada sem ele. |
| 422 | AMD000043 | Unprocessable Entity | Related party `{target_key}` has no signer group on the originator and cannot sign the term. | A parte relacionada `{target_key}` não tem grupo de assinatura no originador, então não pode assinar o termo. |
| 409 | AMD000044 | Conflict | Issue number '`{issue_number}`' is already used by an active operation of this issuer. | O número de emissão '`{issue_number}`' já está em uso por uma operação ativa deste emissor. |

---

# Configuração de Webhooks

URL: /documentation/escrituracao/configuracao-webhooks

A API de Configuração de Webhooks permite gerenciar endpoints de webhook para receber notificações em tempo real sobre eventos da escrituração. Cada tenant pode ter múltiplas configurações de webhook, permitindo que os eventos sejam enviados para diferentes destinos.

---

## Modelo de Dados

### Configuração de Webhook

```json
{
  "configuration_key": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_key": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "url": "https://example.com/webhook",
  "headers": {
    "Authorization": "Bearer token",
    "X-Custom-Header": "value"
  },
  "hmac_signature_key": "secret-key"
}
```

---

## Criar Configuração de Webhook (POST)

### Request

ENDPOINT /outgoing_webhook/webhook_configuration
MÉTODO POST

### Request Body

```json
{
  "tenant_key": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "url": "https://example.com/webhook",
  "hmac_signature_key": "your-secret-key",
  "headers": {
    "Authorization": "Bearer token",
    "X-Custom-Header": "value"
  }
}
```

### Request Body Params

| Campo                  | Tipo   | Descrição                                                 |
| ---------------------- | ------ | --------------------------------------------------------- |
| `tenant_key`*         | string | UUID do tenant (UUID v4).                               |
| `url`*                | string | URL de destino para receber os webhooks.                |
| `hmac_signature_key`* | string | Chave secreta para assinatura HMAC dos webhooks.       |
| `headers`             | object | Headers personalizados para incluir nas requisições.     |

---

### Response

STATUS 201

Response Body

```json
{
  "configuration_key": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_key": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "url": "https://example.com/webhook",
  "headers": {
    "Authorization": "Bearer token",
    "X-Custom-Header": "value"
  },
  "hmac_signature_key": "your-secret-key"
}
```

### Response Body Params

| Campo                  | Tipo   | Descrição                                                 |
| ---------------------- | ------ | --------------------------------------------------------- |
| `configuration_key`   | string | Chave única da configuração de webhook (UUID v4).       |
| `tenant_key`          | string | UUID do tenant.                                          |
| `url`                 | string | URL de destino configurada.                             |
| `headers`             | object | Headers personalizados configurados.                     |
| `hmac_signature_key`  | string | Chave secreta para assinatura HMAC.                     |

---

## Listar Configurações de Webhook (GET)

### Request

ENDPOINT /outgoing_webhook/webhook_configuration
MÉTODO GET

### Query Params

| Campo        | Tipo    | Descrição                                      |
| ------------ | ------- | ---------------------------------------------- |
| `tenant_key`* | string | UUID do tenant para filtrar as configurações. |
| `page`       | integer | Número da página (padrão: 1).                 |
| `page_size`  | integer | Itens por página (padrão: 100).               |

---

### Response

STATUS 200

Response Body

```json
{
  "data": [
    {
      "configuration_key": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_key": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "url": "https://example.com/webhook",
      "headers": {
        "Authorization": "Bearer token"
      },
      "hmac_signature_key": "your-secret-key"
    }
  ],
  "pagination": {
    "current_page": 1,
    "page_size": 100,
    "total_rows": 15,
    "total_pages": 1
  }
}
```

### Response Body Params

| Campo                  | Tipo    | Descrição                                                 |
| ---------------------- | ------- | --------------------------------------------------------- |
| `data`                | array   | Lista de configurações de webhook.                       |
| `pagination`          | object  | **[Objeto pagination](#objeto-pagination)**.            |

---

## Obter Configuração de Webhook por Chave (GET)

### Request

ENDPOINT /outgoing_webhook/webhook_configuration/ CONFIGURATION-KEY
MÉTODO GET

### Path Params

| Campo               | Tipo   | Descrição                                        | Caracteres |
| ------------------- | ------ | ------------------------------------------------ | ---------- |
| `CONFIGURATION-KEY` | string | Chave única da configuração de webhook (UUID v4). | 36         |

---

### Response

STATUS 200

Response Body

```json
{
  "configuration_key": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_key": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "url": "https://example.com/webhook",
  "headers": {
    "Authorization": "Bearer token"
  },
  "hmac_signature_key": "your-secret-key"
}
```

### Response Body Params

| Campo                  | Tipo    | Descrição                                                 |
| ---------------------- | ------- | --------------------------------------------------------- |
| `configuration_key`   | string  | Chave única da configuração de webhook (UUID v4).       |
| `tenant_key`          | string  | UUID do tenant.                                          |
| `url`                 | string  | URL de destino configurada.                             |
| `headers`             | object  | Headers personalizados configurados.                     |
| `hmac_signature_key`  | string  | Chave secreta para assinatura HMAC.                     |

---

## Atualizar Configuração de Webhook (PUT)

### Request

ENDPOINT /outgoing_webhook/webhook_configuration/ CONFIGURATION-KEY
MÉTODO PUT

### Path Params

| Campo               | Tipo   | Descrição                                        | Caracteres |
| ------------------- | ------ | ------------------------------------------------ | ---------- |
| `CONFIGURATION-KEY` | string | Chave única da configuração de webhook (UUID v4). | 36         |

---

### Request Body

```json
{
  "url": "https://new-url.com/webhook",
  "headers": {
    "New-Header": "new-value"
  },
  "hmac_signature_key": "new-secret-key"
}
```

### Request Body Params

| Campo                 | Tipo   | Descrição                                                 |
| --------------------- | ------ | --------------------------------------------------------- |
| `url`                | string | Nova URL de destino para receber os webhooks.            |
| `headers`            | object | Novos headers personalizados para incluir nas requisições. |
| `hmac_signature_key` | string | Nova chave secreta para assinatura HMAC dos webhooks.    |

---

### Response

STATUS 200

Response Body

```json
{
  "configuration_key": "550e8400-e29b-41d4-a716-446655440000",
  "tenant_key": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "url": "https://new-url.com/webhook",
  "headers": {
    "New-Header": "new-value"
  },
  "hmac_signature_key": "new-secret-key"
}
```

### Response Body Params

| Campo                  | Tipo    | Descrição                                                 |
| ---------------------- | ------- | --------------------------------------------------------- |
| `configuration_key`   | string  | Chave única da configuração de webhook (UUID v4).       |
| `tenant_key`          | string  | UUID do tenant.                                          |
| `url`                 | string  | URL de destino configurada.                             |
| `headers`             | object  | Headers personalizados configurados.                     |
| `hmac_signature_key`  | string  | Chave secreta para assinatura HMAC.                     |

---

## Deletar Configuração de Webhook (DELETE)

### Request

ENDPOINT /outgoing_webhook/webhook_configuration/ CONFIGURATION-KEY
MÉTODO DELETE

### Path Params

| Campo               | Tipo   | Descrição                                        | Caracteres |
| ------------------- | ------ | ------------------------------------------------ | ---------- |
| `CONFIGURATION-KEY` | string | Chave única da configuração de webhook (UUID v4). | 36         |

---

### Response

STATUS 200

Response Body

```json
{}
```

---

# Cadastro de Lastro (Ativo Subjacente)

URL: /documentation/escrituracao/emissao-cr/cadastro-lastro

Este endpoint cadastra o **lastro** (ativo subjacente) de uma operação de CR. O lastro representa os direitos creditórios que dão suporte à securitização. O documento do ativo é enviado em base64 e seus dados estruturados acompanham a requisição.

:::info
O lastro é enviado **após a criação da operação**, em uma requisição separada. Podem ser cadastrados múltiplos lastros para a mesma operação.
:::

---

## **Request**

ENDPOINT /cr/operation/ OPERATION-KEY /underlying_asset
MÉTODO POST

### Path Params

| Campo           | Tipo   | Descrição                          | Caracteres |
|-----------------|--------|------------------------------------|------------|
| `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36         |

---

### Request Body

Request Body

```json
{
    "underlying_asset_type": "contract",
    "underlying_asset_base64": "image_b64",
    "underlying_asset_data": {
        "contract_number": "12345",
        "debtor_document_number": "12.345.678/0001-90",
        "amount": 1075268.82,
        "due_date": "2026-01-20"
    }
}
```

### Request Body Params

| Campo                     | Tipo   | Descrição                                | Caracteres Máx.                                                       |
|---------------------------|--------|------------------------------------------|----------------------------------------------------------------------|
| `underlying_asset_type` * | string | Tipo do lastro.                          | **[Enumeradores underlying_asset_type](#enumeradores-underlying_asset_type)** |
| `underlying_asset_base64` * | string | Documento do lastro em base64.         | -                                                                    |
| `underlying_asset_data` * | object | Dados do lastro (estrutura livre).       | -                                                                    |

### Enumeradores underlying_asset_type

| Enum       | Descrição |
|------------|-----------|
| `contract` | Contrato. |

## **Response**

STATUS 201

Response Body

```json
{
    "underlying_asset_key": "5b1f9c2e-2a44-4f0e-9c0a-7b2e0d6f1a23",
    "underlying_asset_type": "contract",
    "underlying_asset_data": {
        "contract_number": "12345",
        "debtor_document_number": "12.345.678/0001-90",
        "amount": 1075268.82,
        "due_date": "2026-01-20"
    }
}
```

### Response Body Params

| Campo                     | Tipo   | Descrição                          |
|---------------------------|--------|------------------------------------|
| `underlying_asset_key` *  | string | Chave única do lastro cadastrado.  |
| `underlying_asset_type` * | string | Tipo do lastro.                    |
| `underlying_asset_data` * | object | Dados do lastro.                   |

---

---

# Cadastro de Operação de CR

URL: /documentation/escrituracao/emissao-cr/cadastro-operacao

Este endpoint cria uma operação de CR completa em uma única requisição.

:::info
O objeto `financial` é **obrigatório** e deve ser enviado já calculado, pois este endpoint não executa a simulação financeira. O emissor e sua conta bancária devem estar previamente cadastrados.
:::

---

## **Request**

ENDPOINT /cr/create_operation
MÉTODO POST

O corpo da requisição vai desde um **payload com os campos obrigatórios** (incluindo o objeto financeiro) até um **payload completo** que inclui também partes relacionadas. Veja as duas variações abaixo.

Payload com os campos obrigatórios

```json
{
    "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814",
    "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e",
    "issue_number": 10,
    "issue_series": 1,
    "issue_date": "2025-01-20",
    "investors": [
        {
            "investor_key": "70b1b638-ca56-4eb3-9a88-2fd5ffd077a7",
            "bank_account": {
                "account_number": "33400254",
                "account_digit": "3",
                "account_branch": "0001",
                "financial_institution_code_number": "329",
                "financial_institution_ispb": "32402502",
                "account_type": "checking"
            }
        }
    ],
    "financial": {
        "financial_base_date": "2025-01-20",
        "interest_type": "pre_price_days",
        "issue_amount": 1075268.82,
        "issue_quantity": 1075268,
        "unit_price": 1.0000007626,
        "released_amount": 1075268.82,
        "cet": 7.7,
        "annual_cet": 143.55,
        "first_due_date": "2025-02-20",
        "number_of_installments": 5,
        "prefixed_interest_rate": {
            "interest_base": "calendar_days_365",
            "monthly_rate": 0.05,
            "daily_rate": 0.0016053474,
            "annual_rate": 0.795856326
        },
        "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 },
        "contract_fine_rate": 0.02,
        "fees": [
            { "amount": 2.0, "fee_amount": 21505.38, "amount_type": "percentage", "fee_type": "bookkeeping_fee", "type": "internal" }
        ],
        "installments": [
            {
                "installment_number": 1,
                "due_date": "2025-02-20",
                "amount": 248113.17,
                "principal_amortization_amount": 193292.79655634,
                "principal_amortization_unit_price": 1.02,
                "interest_amount": 0.0,
                "calendar_days": 31,
                "workdays": 23
            }
        ]
    }
}
```

Payload completo (com partes relacionadas)

```json
{
    "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814",
    "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e",
    "issue_number": 10,
    "issue_series": 1,
    "contract_number": "CR-2025-0001",
    "issue_date": "2025-01-20",
    "signature_method": "certifiqi",
    "investors": [
        {
            "investor_key": "70b1b638-ca56-4eb3-9a88-2fd5ffd077a7",
            "subscription_percentage": 100,
            "bank_account": {
                "account_number": "33400254",
                "account_digit": "3",
                "account_branch": "0001",
                "financial_institution_code_number": "329",
                "financial_institution_ispb": "32402502",
                "account_type": "checking"
            }
        }
    ],
    "financial": {
        "financial_base_date": "2025-01-20",
        "interest_type": "pre_price_days",
        "issue_amount": 1075268.82,
        "issue_quantity": 1075268,
        "unit_price": 1.0000007626,
        "released_amount": 1075268.82,
        "cet": 7.7,
        "annual_cet": 143.55,
        "first_due_date": "2025-02-20",
        "number_of_installments": 5,
        "prefixed_interest_rate": {
            "interest_base": "calendar_days_365",
            "monthly_rate": 0.05,
            "daily_rate": 0.0016053474,
            "annual_rate": 0.795856326
        },
        "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 },
        "contract_fine_rate": 0.02,
        "fees": [
            { "amount": 2.0, "fee_amount": 21505.38, "amount_type": "percentage", "fee_type": "bookkeeping_fee", "type": "internal" }
        ],
        "installments": [
            {
                "installment_number": 1,
                "due_date": "2025-02-20",
                "amount": 248113.17,
                "principal_amortization_amount": 193292.79655634,
                "principal_amortization_unit_price": 1.02,
                "interest_amount": 0.0,
                "calendar_days": 31,
                "workdays": 23
            }
        ]
    },
    "related_party_list": [
        {
            "person_type": "legal",
            "name": "Garantidora S.A.",
            "document_number": "12.345.678/0001-90",
            "trading_name": "Garantidora",
            "cnae_code": "64.62-0-00",
            "company_type": "sa",
            "foundation_date": "2010-05-01",
            "street": "Av. Paulista",
            "number": "1000",
            "neighborhood": "Bela Vista",
            "postal_code": "01310-100",
            "city": "São Paulo",
            "state": "SP",
            "role_type": "guarantor"
        },
        {
            "person_type": "natural",
            "name": "João da Silva",
            "document_number": "123.456.789-00",
            "street": "Rua das Flores",
            "number": "123",
            "neighborhood": "Centro",
            "postal_code": "01001-000",
            "city": "São Paulo",
            "state": "SP",
            "role_type": "solidary_debtor",
            "is_pep": false
        }
    ]
}
```

### **Request Body Params**

| Campo               | Tipo    | Descrição                                            | Caracteres Máx.            |
| ------------------- | ------- | ---------------------------------------------------- | -------------------------- |
| `tenant_key` *      | string  | Chave única do tenant.                               | -                          |
| `issuer_key` *      | string  | Chave única do emissor (previamente cadastrado).     | -                          |
| `issue_number` *    | integer | Número da emissão.                                   | -                          |
| `issue_series` *    | integer | Série da emissão.                                    | -                          |
| `issue_date` *      | string  | Data de emissão da operação (formato "YYYY-MM-DD").  | -                          |
| `signature_method`  | string  | Método de assinatura utilizado na operação. Opcional; quando omitido, assume `certifiqi`. | **[Enumeradores signature_method](#enumeradores-signature_method)** |
| `investors` *       | array   | Lista de investidores envolvidos.                    | **Objeto investors**       |
| `financial` *       | object  | Dados financeiros já calculados da operação.         | **Objeto financial**       |
| `contract_number`   | string  | Número do contrato.                                  | -                          |
| `related_party_list` | array  | Partes relacionadas da operação (garantidores, devedores, etc.). | **Objeto related_party** |

### Objeto investors

| Campo                       | Tipo   | Descrição                                                |
| --------------------------- | ------ | -------------------------------------------------------- |
| `investor_key` *            | string | Chave única do investidor (previamente cadastrado).      |
| `bank_account` *            | object | Conta bancária do investidor (**Objeto bank_account**).  |
| `subscription_percentage`   | number | Percentual de subscrição.                                |
| `subscription_quantity`     | number | Quantidade subscrita.                                    |

### Objeto bank_account

| Campo                                 | Tipo   | Descrição                                                     |
| ------------------------------------- | ------ | ------------------------------------------------------------- |
| `account_number` *                    | string | Número da conta bancária.                                     |
| `account_digit` *                     | string | Dígito da conta bancária.                                     |
| `account_branch` *                    | string | Agência da conta bancária.                                    |
| `financial_institution_code_number`   | string | Código da instituição financeira.                            |
| `financial_institution_ispb` *        | string | Código ISPB da instituição financeira.                       |
| `account_type` *                      | string | Tipo da conta (`checking`, `savings`, `salary`, `payment`).  |

### Objeto financial

| Campo                       | Tipo    | Descrição                                          |
| --------------------------- | ------- | -------------------------------------------------- |
| `financial_base_date` *     | string  | Data base financeira (formato "YYYY-MM-DD").       |
| `interest_type` *           | string  | Tipo de juros.                                     |
| `issue_amount`              | number  | Valor total emitido.                               |
| `issue_quantity`            | integer | Quantidade de unidades emitidas.                   |
| `unit_price`                | number  | Preço unitário da emissão.                         |
| `released_amount`           | number  | Valor líquido liberado.                            |
| `cet` / `annual_cet`        | number  | Custo Efetivo Total (mensal e anual), em percentual. |
| `number_of_installments` *  | integer | Número de parcelas.                                |
| `prefixed_interest_rate` *  | object  | Taxa de juros prefixada.                           |
| `fine_delay_rate`           | object  | Taxa de multa por atraso.                          |
| `contract_fine_rate`        | number  | Multa contratual em percentual.                    |
| `fees`                      | array   | Lista de taxas.                                    |
| `installments`              | array   | Lista de parcelas já calculadas.                   |

### Objeto related_party

Cada item de `related_party_list` representa uma parte envolvida na operação.

| Campo             | Tipo    | Descrição                                                     |
| ----------------- | ------- | ------------------------------------------------------------- |
| `person_type` *   | string  | Tipo de pessoa (`natural` para PF, `legal` para PJ).         |
| `name` *          | string  | Nome da parte relacionada.                                   |
| `document_number` * | string | CPF (PF) ou CNPJ (PJ).                                      |
| `role_type` *     | string  | Papel da parte na operação. **[Enumeradores role_type](#enumeradores-role_type)** |
| `street` *        | string  | Logradouro.                                                 |
| `number` *        | string  | Número do endereço.                                         |
| `neighborhood`    | string  | Bairro.                                                     |
| `postal_code` *   | string  | CEP (formato "00000-000").                                  |
| `city` *          | string  | Cidade.                                                     |
| `state` *         | string  | UF (2 letras).                                              |
| `complement`      | string  | Complemento do endereço.                                    |
| `is_pep`          | boolean | (PF) Indica se é Pessoa Politicamente Exposta.              |
| `marital_status`  | string  | (PF) Estado civil.                                          |
| `property_system` | string  | (PF) Regime de bens.                                        |
| `birthdate`       | string  | (PF) Data de nascimento.                                    |
| `mother_name`     | string  | (PF) Nome da mãe.                                           |
| `occupation`      | string  | (PF) Ocupação.                                              |
| `trading_name`    | string  | (PJ) Nome fantasia.                                         |
| `cnae_code`       | string  | (PJ) Código CNAE (formato "00.00-0-00").                    |
| `company_type`    | string  | (PJ) Tipo de empresa.                                       |
| `foundation_date` | string  | (PJ) Data de fundação.                                      |

:::warning Atenção
Os campos obrigatórios variam conforme o `person_type`:
- **Pessoa física (`natural`)**: além dos campos comuns, `is_pep` é obrigatório.
- **Pessoa jurídica (`legal`)**: além dos campos comuns, `trading_name`, `cnae_code`, `company_type` e `foundation_date` são obrigatórios.
:::

### Enumeradores role_type

| Enum | Descrição |
|------|-----------|
| `issuer` | Emissor. |
| `investor` | Investidor. |
| `cosigner` | Coobrigado. |
| `fiduciary_debtor` | Devedor fiduciante. |
| `solidary_debtor` | Devedor solidário. |
| `guarantor` | Avalista. |
| `bonafide_depositary` | Fiel depositário. |
| `intervening_guarantor` | Interveniente garantidor. |
| `intervening_consentor` | Interveniente anuente. |
| `intervening_discharger` | Interveniente quitante. |
| `assignor` | Cedente. |
| `endorser` | Endossante. |
| `consulting` | Consultoria. |
| `fund_administrator` | Administrador do fundo. |
| `fund_representative` | Representante do fundo. |
| `company_representative` | Representante da empresa. |
| `attestant` | Anuente / testemunha. |
| `debtor` | Devedor. |
| `bestowal` | Outorgante. |
| `manager` | Gestor. |

:::tip
Garantias e lastro são enviados em um **endpoint separado**, após a criação da operação. Consulte a página **Cadastro de lastro** desta seção.
:::

### Enumeradores signature_method

| Enum | Descrição |
|------|-----------|
| `certifiqi` | Valor padrão. A operação é enviada ao serviço de assinatura; um envelope de assinatura é criado e o cliente recebe a URL de assinatura (`signature_url`). |
| `qi_sign` | A operação é enviada ao serviço de assinatura; um envelope de assinatura é criado e o cliente recebe a URL de assinatura (`signature_url`). Permite também a consulta dos signatários da operação. |

## **Response**

STATUS 201

Response Body

```json
{
    "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814",
    "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127",
    "operation_status": "finished",
    "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e",
    "issuer_name": "Dynamic Enterprises",
    "issuer_document_number": "28980395000155",
    "issue_number": 10,
    "issue_series": 1,
    "related_party_list": [ ... ],
    "financial": { ... }
}
```

A resposta retorna o JSON completo da operação criada, incluindo `operation_key`, listas de investidores e partes relacionadas, e o objeto financeiro calculado.

---

# Envio de Documento

URL: /documentation/escrituracao/emissao-cr/envio-documento

Este endpoint permite o **envio de um documento** e retorna o `document_key` que o identifica. Esse `document_key` é utilizado para referenciar documentos em outros endpoints da operação sempre que for exigida a chave de um documento previamente enviado.

---

## **Request**

ENDPOINT /cr/upload
MÉTODO POST

Request Body

```json
{
    "document_base64": "string_b64"
}
```

### **Request Body Params**

| Campo             | Tipo   | Descrição                                    | Obrigatório |
|-------------------|--------|----------------------------------------------|-------------|
| `document_base64` * | string | Conteúdo do documento codificado em Base64. | Sim         |
| `document_name`   | string | Nome do documento.                           | -           |

## **Response**

STATUS 201

Response Body

```json
{
    "document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b"
}
```

### **Response Body Params**

| Campo          | Tipo   | Descrição                                       | Caracteres Máx. |
|----------------|--------|-------------------------------------------------|-----------------|
| `document_key` * | string | Chave única do documento enviado (UUID v4).    | 36              |

---

---

# Enviar Documento Externo da Operação

URL: /documentation/escrituracao/emissao-cr/envio-documento-externo

Este endpoint permite enviar documentos assinados de forma externa para o sistema de escrituração, enviando um base64 que será analisado e aprovado pelo escriturador.

:::warning Aviso
Este endpoint deve ser usado apenas para operações que utilizam o tipo de assinatura **client_side** ou para envio da ata de aprovação de empresas do tipo SA ou Cooperativas. Para o fluxo via QI Sign ou Certifiqi, os contratos são gerados de forma normal.
:::

---

## Enviar Documento Assinado (POST)

### Request

ENDPOINT /cr/operation/ OPERATION-KEY /upload_signed_document
MÉTODO POST

### Path Params

| Campo           | Tipo   | Descrição                            | Caracteres |
|-----------------|--------|--------------------------------------|------------|
| `OPERATION-KEY` | string | Chave única da operação (UUID v4).   | 36         |

---

### Request Body

Request Body

```json
{
    "contract_base64": "image_b64",
    "contract_type": "securitization_term"
}
```

### Request Body Params

| Campo               | Tipo   | Descrição                   | Caracteres Máx.                                              |
|---------------------|--------|-----------------------------|-------------------------------------------------------------|
| `contract_type` *   | string | Tipo de documento assinado. | **[Enumeradores contract_type](#enumeradores-contract_type)** |
| `contract_base64` * | string | Documento assinado em base64. | -                                                         |

### Enumeradores contract_type

| Enum                | Descrição                                  |
|---------------------|--------------------------------------------|
| `securitization_term` | Termo de securitização do CR. |
| `adhesion_term` | Termo de adesão do CR. |
| `sa_minute` | Ata de aprovação de emissão do CR para empresa **SA**. |
| `ltda_minute` | Ata de aprovação de emissão do CR para empresa **LTDA**. |
| `cop_minute` | Ata de aprovação de emissão do CR para **Cooperativa**. |

### Response

O corpo da resposta é um JSON completo da operação atualizada.

---

---

# Cadastro de Lastro (Ativo Subjacente)

URL: /documentation/escrituracao/emissao-cra/cadastro-lastro

Este endpoint cadastra o **lastro** (ativo subjacente) de uma operação de CRA. O lastro representa os direitos creditórios que dão suporte à securitização. O documento do ativo é enviado em base64 e seus dados estruturados acompanham a requisição.

:::info
O lastro é enviado **após a criação da operação**, em uma requisição separada. Podem ser cadastrados múltiplos lastros para a mesma operação.
:::

---

## **Request**

ENDPOINT /cra/operation/ OPERATION-KEY /underlying_asset
MÉTODO POST

### Path Params

| Campo           | Tipo   | Descrição                          | Caracteres |
|-----------------|--------|------------------------------------|------------|
| `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36         |

---

### Request Body

Request Body

```json
{
    "underlying_asset_type": "contract",
    "underlying_asset_base64": "image_b64",
    "underlying_asset_data": {
        "contract_number": "12345",
        "debtor_document_number": "12.345.678/0001-90",
        "amount": 1075268.82,
        "due_date": "2026-01-20"
    }
}
```

### Request Body Params

| Campo                     | Tipo   | Descrição                                | Caracteres Máx.                                                       |
|---------------------------|--------|------------------------------------------|----------------------------------------------------------------------|
| `underlying_asset_type` * | string | Tipo do lastro.                          | **[Enumeradores underlying_asset_type](#enumeradores-underlying_asset_type)** |
| `underlying_asset_base64` * | string | Documento do lastro em base64.         | -                                                                    |
| `underlying_asset_data` * | object | Dados do lastro (estrutura livre).       | -                                                                    |

### Enumeradores underlying_asset_type

| Enum       | Descrição |
|------------|-----------|
| `contract` | Contrato. |

## **Response**

STATUS 201

Response Body

```json
{
    "underlying_asset_key": "5b1f9c2e-2a44-4f0e-9c0a-7b2e0d6f1a23",
    "underlying_asset_type": "contract",
    "underlying_asset_data": {
        "contract_number": "12345",
        "debtor_document_number": "12.345.678/0001-90",
        "amount": 1075268.82,
        "due_date": "2026-01-20"
    }
}
```

### Response Body Params

| Campo                     | Tipo   | Descrição                          |
|---------------------------|--------|------------------------------------|
| `underlying_asset_key` *  | string | Chave única do lastro cadastrado.  |
| `underlying_asset_type` * | string | Tipo do lastro.                    |
| `underlying_asset_data` * | object | Dados do lastro.                   |

---

---

# Cadastro de Operação de CRA

URL: /documentation/escrituracao/emissao-cra/cadastro-operacao

Este endpoint cria uma operação de CRA completa em uma única requisição.

:::info
O objeto `financial` é **obrigatório** e deve ser enviado já calculado, pois este endpoint não executa a simulação financeira. O emissor e sua conta bancária devem estar previamente cadastrados.
:::

---

## **Request**

ENDPOINT /cra/create_operation
MÉTODO POST

O corpo da requisição vai desde um **payload com os campos obrigatórios** (incluindo o objeto financeiro) até um **payload completo** que inclui também partes relacionadas. Veja as duas variações abaixo.

Payload com os campos obrigatórios

```json
{
    "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814",
    "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e",
    "issue_number": 10,
    "issue_series": 1,
    "issue_date": "2025-01-20",
    "investors": [
        {
            "investor_key": "70b1b638-ca56-4eb3-9a88-2fd5ffd077a7",
            "bank_account": {
                "account_number": "33400254",
                "account_digit": "3",
                "account_branch": "0001",
                "financial_institution_code_number": "329",
                "financial_institution_ispb": "32402502",
                "account_type": "checking"
            }
        }
    ],
    "financial": {
        "financial_base_date": "2025-01-20",
        "interest_type": "pre_price_days",
        "issue_amount": 1075268.82,
        "issue_quantity": 1075268,
        "unit_price": 1.0000007626,
        "released_amount": 1075268.82,
        "cet": 7.7,
        "annual_cet": 143.55,
        "first_due_date": "2025-02-20",
        "number_of_installments": 5,
        "prefixed_interest_rate": {
            "interest_base": "calendar_days_365",
            "monthly_rate": 0.05,
            "daily_rate": 0.0016053474,
            "annual_rate": 0.795856326
        },
        "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 },
        "contract_fine_rate": 0.02,
        "fees": [
            { "amount": 2.0, "fee_amount": 21505.38, "amount_type": "percentage", "fee_type": "bookkeeping_fee", "type": "internal" }
        ],
        "installments": [
            {
                "installment_number": 1,
                "due_date": "2025-02-20",
                "amount": 248113.17,
                "principal_amortization_amount": 193292.79655634,
                "principal_amortization_unit_price": 1.02,
                "interest_amount": 0.0,
                "calendar_days": 31,
                "workdays": 23
            }
        ]
    }
}
```

Payload completo (com partes relacionadas)

```json
{
    "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814",
    "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e",
    "issue_number": 10,
    "issue_series": 1,
    "contract_number": "CRA-2025-0001",
    "issue_date": "2025-01-20",
    "signature_method": "certifiqi",
    "investors": [
        {
            "investor_key": "70b1b638-ca56-4eb3-9a88-2fd5ffd077a7",
            "subscription_percentage": 100,
            "bank_account": {
                "account_number": "33400254",
                "account_digit": "3",
                "account_branch": "0001",
                "financial_institution_code_number": "329",
                "financial_institution_ispb": "32402502",
                "account_type": "checking"
            }
        }
    ],
    "financial": {
        "financial_base_date": "2025-01-20",
        "interest_type": "pre_price_days",
        "issue_amount": 1075268.82,
        "issue_quantity": 1075268,
        "unit_price": 1.0000007626,
        "released_amount": 1075268.82,
        "cet": 7.7,
        "annual_cet": 143.55,
        "first_due_date": "2025-02-20",
        "number_of_installments": 5,
        "prefixed_interest_rate": {
            "interest_base": "calendar_days_365",
            "monthly_rate": 0.05,
            "daily_rate": 0.0016053474,
            "annual_rate": 0.795856326
        },
        "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 },
        "contract_fine_rate": 0.02,
        "fees": [
            { "amount": 2.0, "fee_amount": 21505.38, "amount_type": "percentage", "fee_type": "bookkeeping_fee", "type": "internal" }
        ],
        "installments": [
            {
                "installment_number": 1,
                "due_date": "2025-02-20",
                "amount": 248113.17,
                "principal_amortization_amount": 193292.79655634,
                "principal_amortization_unit_price": 1.02,
                "interest_amount": 0.0,
                "calendar_days": 31,
                "workdays": 23
            }
        ]
    },
    "related_party_list": [
        {
            "person_type": "legal",
            "name": "Garantidora S.A.",
            "document_number": "12.345.678/0001-90",
            "trading_name": "Garantidora",
            "cnae_code": "64.62-0-00",
            "company_type": "sa",
            "foundation_date": "2010-05-01",
            "street": "Av. Paulista",
            "number": "1000",
            "neighborhood": "Bela Vista",
            "postal_code": "01310-100",
            "city": "São Paulo",
            "state": "SP",
            "role_type": "guarantor"
        },
        {
            "person_type": "natural",
            "name": "João da Silva",
            "document_number": "123.456.789-00",
            "street": "Rua das Flores",
            "number": "123",
            "neighborhood": "Centro",
            "postal_code": "01001-000",
            "city": "São Paulo",
            "state": "SP",
            "role_type": "solidary_debtor",
            "is_pep": false
        }
    ]
}
```

### **Request Body Params**

| Campo               | Tipo    | Descrição                                            | Caracteres Máx.            |
| ------------------- | ------- | ---------------------------------------------------- | -------------------------- |
| `tenant_key` *      | string  | Chave única do tenant.                               | -                          |
| `issuer_key` *      | string  | Chave única do emissor (previamente cadastrado).     | -                          |
| `issue_number` *    | integer | Número da emissão.                                   | -                          |
| `issue_series` *    | integer | Série da emissão.                                    | -                          |
| `issue_date` *      | string  | Data de emissão da operação (formato "YYYY-MM-DD").  | -                          |
| `signature_method`  | string  | Método de assinatura utilizado na operação. Opcional; quando omitido, assume `certifiqi`. | **[Enumeradores signature_method](#enumeradores-signature_method)** |
| `investors` *       | array   | Lista de investidores envolvidos.                    | **Objeto investors**       |
| `financial` *       | object  | Dados financeiros já calculados da operação.         | **Objeto financial**       |
| `contract_number`   | string  | Número do contrato.                                  | -                          |
| `related_party_list` | array  | Partes relacionadas da operação (garantidores, devedores, etc.). | **Objeto related_party** |

### Objeto investors

| Campo                       | Tipo   | Descrição                                                |
| --------------------------- | ------ | -------------------------------------------------------- |
| `investor_key` *            | string | Chave única do investidor (previamente cadastrado).      |
| `bank_account` *            | object | Conta bancária do investidor (**Objeto bank_account**).  |
| `subscription_percentage`   | number | Percentual de subscrição.                                |
| `subscription_quantity`     | number | Quantidade subscrita.                                    |

### Objeto bank_account

| Campo                                 | Tipo   | Descrição                                                     |
| ------------------------------------- | ------ | ------------------------------------------------------------- |
| `account_number` *                    | string | Número da conta bancária.                                     |
| `account_digit` *                     | string | Dígito da conta bancária.                                     |
| `account_branch` *                    | string | Agência da conta bancária.                                    |
| `financial_institution_code_number`   | string | Código da instituição financeira.                            |
| `financial_institution_ispb` *        | string | Código ISPB da instituição financeira.                       |
| `account_type` *                      | string | Tipo da conta (`checking`, `savings`, `salary`, `payment`).  |

### Objeto financial

| Campo                       | Tipo    | Descrição                                          |
| --------------------------- | ------- | -------------------------------------------------- |
| `financial_base_date` *     | string  | Data base financeira (formato "YYYY-MM-DD").       |
| `interest_type` *           | string  | Tipo de juros.                                     |
| `issue_amount`              | number  | Valor total emitido.                               |
| `issue_quantity`            | integer | Quantidade de unidades emitidas.                   |
| `unit_price`                | number  | Preço unitário da emissão.                         |
| `released_amount`           | number  | Valor líquido liberado.                            |
| `cet` / `annual_cet`        | number  | Custo Efetivo Total (mensal e anual), em percentual. |
| `number_of_installments` *  | integer | Número de parcelas.                                |
| `prefixed_interest_rate` *  | object  | Taxa de juros prefixada.                           |
| `fine_delay_rate`           | object  | Taxa de multa por atraso.                          |
| `contract_fine_rate`        | number  | Multa contratual em percentual.                    |
| `fees`                      | array   | Lista de taxas.                                    |
| `installments`              | array   | Lista de parcelas já calculadas.                   |

### Objeto related_party

Cada item de `related_party_list` representa uma parte envolvida na operação.

| Campo             | Tipo    | Descrição                                                     |
| ----------------- | ------- | ------------------------------------------------------------- |
| `person_type` *   | string  | Tipo de pessoa (`natural` para PF, `legal` para PJ).         |
| `name` *          | string  | Nome da parte relacionada.                                   |
| `document_number` * | string | CPF (PF) ou CNPJ (PJ).                                      |
| `role_type` *     | string  | Papel da parte na operação. **[Enumeradores role_type](#enumeradores-role_type)** |
| `street` *        | string  | Logradouro.                                                 |
| `number` *        | string  | Número do endereço.                                         |
| `neighborhood`    | string  | Bairro.                                                     |
| `postal_code` *   | string  | CEP (formato "00000-000").                                  |
| `city` *          | string  | Cidade.                                                     |
| `state` *         | string  | UF (2 letras).                                              |
| `complement`      | string  | Complemento do endereço.                                    |
| `is_pep`          | boolean | (PF) Indica se é Pessoa Politicamente Exposta.              |
| `marital_status`  | string  | (PF) Estado civil.                                          |
| `property_system` | string  | (PF) Regime de bens.                                        |
| `birthdate`       | string  | (PF) Data de nascimento.                                    |
| `mother_name`     | string  | (PF) Nome da mãe.                                           |
| `occupation`      | string  | (PF) Ocupação.                                              |
| `trading_name`    | string  | (PJ) Nome fantasia.                                         |
| `cnae_code`       | string  | (PJ) Código CNAE (formato "00.00-0-00").                    |
| `company_type`    | string  | (PJ) Tipo de empresa.                                       |
| `foundation_date` | string  | (PJ) Data de fundação.                                      |

:::warning Atenção
Os campos obrigatórios variam conforme o `person_type`:
- **Pessoa física (`natural`)**: além dos campos comuns, `is_pep` é obrigatório.
- **Pessoa jurídica (`legal`)**: além dos campos comuns, `trading_name`, `cnae_code`, `company_type` e `foundation_date` são obrigatórios.
:::

### Enumeradores role_type

| Enum | Descrição |
|------|-----------|
| `issuer` | Emissor. |
| `investor` | Investidor. |
| `cosigner` | Coobrigado. |
| `fiduciary_debtor` | Devedor fiduciante. |
| `solidary_debtor` | Devedor solidário. |
| `guarantor` | Avalista. |
| `bonafide_depositary` | Fiel depositário. |
| `intervening_guarantor` | Interveniente garantidor. |
| `intervening_consentor` | Interveniente anuente. |
| `intervening_discharger` | Interveniente quitante. |
| `assignor` | Cedente. |
| `endorser` | Endossante. |
| `consulting` | Consultoria. |
| `fund_administrator` | Administrador do fundo. |
| `fund_representative` | Representante do fundo. |
| `company_representative` | Representante da empresa. |
| `attestant` | Anuente / testemunha. |
| `debtor` | Devedor. |
| `bestowal` | Outorgante. |
| `manager` | Gestor. |

:::tip
Garantias e lastro são enviados em um **endpoint separado**, após a criação da operação. Consulte a página **Cadastro de lastro** desta seção.
:::

### Enumeradores signature_method

| Enum | Descrição |
|------|-----------|
| `certifiqi` | Valor padrão. A operação é enviada ao serviço de assinatura; um envelope de assinatura é criado e o cliente recebe a URL de assinatura (`signature_url`). |
| `qi_sign` | A operação é enviada ao serviço de assinatura; um envelope de assinatura é criado e o cliente recebe a URL de assinatura (`signature_url`). Permite também a consulta dos signatários da operação. |

## **Response**

STATUS 201

Response Body

```json
{
    "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814",
    "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127",
    "operation_status": "finished",
    "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e",
    "issuer_name": "Dynamic Enterprises",
    "issuer_document_number": "28980395000155",
    "issue_number": 10,
    "issue_series": 1,
    "related_party_list": [ ... ],
    "financial": { ... }
}
```

A resposta retorna o JSON completo da operação criada, incluindo `operation_key`, listas de investidores e partes relacionadas, e o objeto financeiro calculado.

---

# Envio de Documento

URL: /documentation/escrituracao/emissao-cra/envio-documento

Este endpoint permite o **envio de um documento** e retorna o `document_key` que o identifica. Esse `document_key` é utilizado para referenciar documentos em outros endpoints da operação sempre que for exigida a chave de um documento previamente enviado.

---

## **Request**

ENDPOINT /cra/upload
MÉTODO POST

Request Body

```json
{
    "document_base64": "string_b64"
}
```

### **Request Body Params**

| Campo             | Tipo   | Descrição                                    | Obrigatório |
|-------------------|--------|----------------------------------------------|-------------|
| `document_base64` * | string | Conteúdo do documento codificado em Base64. | Sim         |
| `document_name`   | string | Nome do documento.                           | -           |

## **Response**

STATUS 201

Response Body

```json
{
    "document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b"
}
```

### **Response Body Params**

| Campo          | Tipo   | Descrição                                       | Caracteres Máx. |
|----------------|--------|-------------------------------------------------|-----------------|
| `document_key` * | string | Chave única do documento enviado (UUID v4).    | 36              |

---

---

# Enviar Documento Externo da Operação

URL: /documentation/escrituracao/emissao-cra/envio-documento-externo

Este endpoint permite enviar documentos assinados de forma externa para o sistema de escrituração, enviando um base64 que será analisado e aprovado pelo escriturador.

:::warning Aviso
Este endpoint deve ser usado apenas para operações que utilizam o tipo de assinatura **client_side** ou para envio da ata de aprovação de empresas do tipo SA ou Cooperativas. Para o fluxo via QI Sign ou Certifiqi, os contratos são gerados de forma normal.
:::

---

## Enviar Documento Assinado (POST)

### Request

ENDPOINT /cra/operation/ OPERATION-KEY /upload_signed_document
MÉTODO POST

### Path Params

| Campo           | Tipo   | Descrição                            | Caracteres |
|-----------------|--------|--------------------------------------|------------|
| `OPERATION-KEY` | string | Chave única da operação (UUID v4).   | 36         |

---

### Request Body

Request Body

```json
{
    "contract_base64": "image_b64",
    "contract_type": "securitization_term"
}
```

### Request Body Params

| Campo               | Tipo   | Descrição                   | Caracteres Máx.                                              |
|---------------------|--------|-----------------------------|-------------------------------------------------------------|
| `contract_type` *   | string | Tipo de documento assinado. | **[Enumeradores contract_type](#enumeradores-contract_type)** |
| `contract_base64` * | string | Documento assinado em base64. | -                                                         |

### Enumeradores contract_type

| Enum                | Descrição                                  |
|---------------------|--------------------------------------------|
| `securitization_term` | Termo de securitização do CRA. |
| `adhesion_term` | Termo de adesão do CRA. |
| `sa_minute` | Ata de aprovação de emissão do CRA para empresa **SA**. |
| `ltda_minute` | Ata de aprovação de emissão do CRA para empresa **LTDA**. |
| `cop_minute` | Ata de aprovação de emissão do CRA para **Cooperativa**. |

### Response

O corpo da resposta é um JSON completo da operação atualizada.

---

---

# Cadastro de Lastro (Ativo Subjacente)

URL: /documentation/escrituracao/emissao-cri/cadastro-lastro

Este endpoint cadastra o **lastro** (ativo subjacente) de uma operação de CRI. O lastro representa os direitos creditórios que dão suporte à securitização. O documento do ativo é enviado em base64 e seus dados estruturados acompanham a requisição.

:::info
O lastro é enviado **após a criação da operação**, em uma requisição separada. Podem ser cadastrados múltiplos lastros para a mesma operação.
:::

---

## **Request**

ENDPOINT /cri/operation/ OPERATION-KEY /underlying_asset
MÉTODO POST

### Path Params

| Campo           | Tipo   | Descrição                          | Caracteres |
|-----------------|--------|------------------------------------|------------|
| `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36         |

---

### Request Body

Request Body

```json
{
    "underlying_asset_type": "contract",
    "underlying_asset_base64": "image_b64",
    "underlying_asset_data": {
        "contract_number": "12345",
        "debtor_document_number": "12.345.678/0001-90",
        "amount": 1075268.82,
        "due_date": "2026-01-20"
    }
}
```

### Request Body Params

| Campo                     | Tipo   | Descrição                                | Caracteres Máx.                                                       |
|---------------------------|--------|------------------------------------------|----------------------------------------------------------------------|
| `underlying_asset_type` * | string | Tipo do lastro.                          | **[Enumeradores underlying_asset_type](#enumeradores-underlying_asset_type)** |
| `underlying_asset_base64` * | string | Documento do lastro em base64.         | -                                                                    |
| `underlying_asset_data` * | object | Dados do lastro (estrutura livre).       | -                                                                    |

### Enumeradores underlying_asset_type

| Enum       | Descrição |
|------------|-----------|
| `contract` | Contrato. |

## **Response**

STATUS 201

Response Body

```json
{
    "underlying_asset_key": "5b1f9c2e-2a44-4f0e-9c0a-7b2e0d6f1a23",
    "underlying_asset_type": "contract",
    "underlying_asset_data": {
        "contract_number": "12345",
        "debtor_document_number": "12.345.678/0001-90",
        "amount": 1075268.82,
        "due_date": "2026-01-20"
    }
}
```

### Response Body Params

| Campo                     | Tipo   | Descrição                          |
|---------------------------|--------|------------------------------------|
| `underlying_asset_key` *  | string | Chave única do lastro cadastrado.  |
| `underlying_asset_type` * | string | Tipo do lastro.                    |
| `underlying_asset_data` * | object | Dados do lastro.                   |

---

---

# Cadastro de Operação de CRI

URL: /documentation/escrituracao/emissao-cri/cadastro-operacao

Este endpoint cria uma operação de CRI completa em uma única requisição.

:::info
O objeto `financial` é **obrigatório** e deve ser enviado já calculado, pois este endpoint não executa a simulação financeira. O emissor e sua conta bancária devem estar previamente cadastrados.
:::

---

## **Request**

ENDPOINT /cri/create_operation
MÉTODO POST

O corpo da requisição vai desde um **payload com os campos obrigatórios** (incluindo o objeto financeiro) até um **payload completo** que inclui também partes relacionadas. Veja as duas variações abaixo.

Payload com os campos obrigatórios

```json
{
    "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814",
    "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e",
    "issue_number": 10,
    "issue_series": 1,
    "issue_date": "2025-01-20",
    "investors": [
        {
            "investor_key": "70b1b638-ca56-4eb3-9a88-2fd5ffd077a7",
            "bank_account": {
                "account_number": "33400254",
                "account_digit": "3",
                "account_branch": "0001",
                "financial_institution_code_number": "329",
                "financial_institution_ispb": "32402502",
                "account_type": "checking"
            }
        }
    ],
    "financial": {
        "financial_base_date": "2025-01-20",
        "interest_type": "pre_price_days",
        "issue_amount": 1075268.82,
        "issue_quantity": 1075268,
        "unit_price": 1.0000007626,
        "released_amount": 1075268.82,
        "cet": 7.7,
        "annual_cet": 143.55,
        "first_due_date": "2025-02-20",
        "number_of_installments": 5,
        "prefixed_interest_rate": {
            "interest_base": "calendar_days_365",
            "monthly_rate": 0.05,
            "daily_rate": 0.0016053474,
            "annual_rate": 0.795856326
        },
        "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 },
        "contract_fine_rate": 0.02,
        "fees": [
            { "amount": 2.0, "fee_amount": 21505.38, "amount_type": "percentage", "fee_type": "bookkeeping_fee", "type": "internal" }
        ],
        "installments": [
            {
                "installment_number": 1,
                "due_date": "2025-02-20",
                "amount": 248113.17,
                "principal_amortization_amount": 193292.79655634,
                "principal_amortization_unit_price": 1.02,
                "interest_amount": 0.0,
                "calendar_days": 31,
                "workdays": 23
            }
        ]
    }
}
```

Payload completo (com partes relacionadas)

```json
{
    "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814",
    "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e",
    "issue_number": 10,
    "issue_series": 1,
    "contract_number": "CRI-2025-0001",
    "issue_date": "2025-01-20",
    "signature_method": "certifiqi",
    "investors": [
        {
            "investor_key": "70b1b638-ca56-4eb3-9a88-2fd5ffd077a7",
            "subscription_percentage": 100,
            "bank_account": {
                "account_number": "33400254",
                "account_digit": "3",
                "account_branch": "0001",
                "financial_institution_code_number": "329",
                "financial_institution_ispb": "32402502",
                "account_type": "checking"
            }
        }
    ],
    "financial": {
        "financial_base_date": "2025-01-20",
        "interest_type": "pre_price_days",
        "issue_amount": 1075268.82,
        "issue_quantity": 1075268,
        "unit_price": 1.0000007626,
        "released_amount": 1075268.82,
        "cet": 7.7,
        "annual_cet": 143.55,
        "first_due_date": "2025-02-20",
        "number_of_installments": 5,
        "prefixed_interest_rate": {
            "interest_base": "calendar_days_365",
            "monthly_rate": 0.05,
            "daily_rate": 0.0016053474,
            "annual_rate": 0.795856326
        },
        "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 },
        "contract_fine_rate": 0.02,
        "fees": [
            { "amount": 2.0, "fee_amount": 21505.38, "amount_type": "percentage", "fee_type": "bookkeeping_fee", "type": "internal" }
        ],
        "installments": [
            {
                "installment_number": 1,
                "due_date": "2025-02-20",
                "amount": 248113.17,
                "principal_amortization_amount": 193292.79655634,
                "principal_amortization_unit_price": 1.02,
                "interest_amount": 0.0,
                "calendar_days": 31,
                "workdays": 23
            }
        ]
    },
    "related_party_list": [
        {
            "person_type": "legal",
            "name": "Garantidora S.A.",
            "document_number": "12.345.678/0001-90",
            "trading_name": "Garantidora",
            "cnae_code": "64.62-0-00",
            "company_type": "sa",
            "foundation_date": "2010-05-01",
            "street": "Av. Paulista",
            "number": "1000",
            "neighborhood": "Bela Vista",
            "postal_code": "01310-100",
            "city": "São Paulo",
            "state": "SP",
            "role_type": "guarantor"
        },
        {
            "person_type": "natural",
            "name": "João da Silva",
            "document_number": "123.456.789-00",
            "street": "Rua das Flores",
            "number": "123",
            "neighborhood": "Centro",
            "postal_code": "01001-000",
            "city": "São Paulo",
            "state": "SP",
            "role_type": "solidary_debtor",
            "is_pep": false
        }
    ]
}
```

### **Request Body Params**

| Campo               | Tipo    | Descrição                                            | Caracteres Máx.            |
| ------------------- | ------- | ---------------------------------------------------- | -------------------------- |
| `tenant_key` *      | string  | Chave única do tenant.                               | -                          |
| `issuer_key` *      | string  | Chave única do emissor (previamente cadastrado).     | -                          |
| `issue_number` *    | integer | Número da emissão.                                   | -                          |
| `issue_series` *    | integer | Série da emissão.                                    | -                          |
| `issue_date` *      | string  | Data de emissão da operação (formato "YYYY-MM-DD").  | -                          |
| `signature_method`  | string  | Método de assinatura utilizado na operação. Opcional; quando omitido, assume `certifiqi`. | **[Enumeradores signature_method](#enumeradores-signature_method)** |
| `investors` *       | array   | Lista de investidores envolvidos.                    | **Objeto investors**       |
| `financial` *       | object  | Dados financeiros já calculados da operação.         | **Objeto financial**       |
| `contract_number`   | string  | Número do contrato.                                  | -                          |
| `related_party_list` | array  | Partes relacionadas da operação (garantidores, devedores, etc.). | **Objeto related_party** |

### Objeto investors

| Campo                       | Tipo   | Descrição                                                |
| --------------------------- | ------ | -------------------------------------------------------- |
| `investor_key` *            | string | Chave única do investidor (previamente cadastrado).      |
| `bank_account` *            | object | Conta bancária do investidor (**Objeto bank_account**).  |
| `subscription_percentage`   | number | Percentual de subscrição.                                |
| `subscription_quantity`     | number | Quantidade subscrita.                                    |

### Objeto bank_account

| Campo                                 | Tipo   | Descrição                                                     |
| ------------------------------------- | ------ | ------------------------------------------------------------- |
| `account_number` *                    | string | Número da conta bancária.                                     |
| `account_digit` *                     | string | Dígito da conta bancária.                                     |
| `account_branch` *                    | string | Agência da conta bancária.                                    |
| `financial_institution_code_number`   | string | Código da instituição financeira.                            |
| `financial_institution_ispb` *        | string | Código ISPB da instituição financeira.                       |
| `account_type` *                      | string | Tipo da conta (`checking`, `savings`, `salary`, `payment`).  |

### Objeto financial

| Campo                       | Tipo    | Descrição                                          |
| --------------------------- | ------- | -------------------------------------------------- |
| `financial_base_date` *     | string  | Data base financeira (formato "YYYY-MM-DD").       |
| `interest_type` *           | string  | Tipo de juros.                                     |
| `issue_amount`              | number  | Valor total emitido.                               |
| `issue_quantity`            | integer | Quantidade de unidades emitidas.                   |
| `unit_price`                | number  | Preço unitário da emissão.                         |
| `released_amount`           | number  | Valor líquido liberado.                            |
| `cet` / `annual_cet`        | number  | Custo Efetivo Total (mensal e anual), em percentual. |
| `number_of_installments` *  | integer | Número de parcelas.                                |
| `prefixed_interest_rate` *  | object  | Taxa de juros prefixada.                           |
| `fine_delay_rate`           | object  | Taxa de multa por atraso.                          |
| `contract_fine_rate`        | number  | Multa contratual em percentual.                    |
| `fees`                      | array   | Lista de taxas.                                    |
| `installments`              | array   | Lista de parcelas já calculadas.                   |

### Objeto related_party

Cada item de `related_party_list` representa uma parte envolvida na operação.

| Campo             | Tipo    | Descrição                                                     |
| ----------------- | ------- | ------------------------------------------------------------- |
| `person_type` *   | string  | Tipo de pessoa (`natural` para PF, `legal` para PJ).         |
| `name` *          | string  | Nome da parte relacionada.                                   |
| `document_number` * | string | CPF (PF) ou CNPJ (PJ).                                      |
| `role_type` *     | string  | Papel da parte na operação. **[Enumeradores role_type](#enumeradores-role_type)** |
| `street` *        | string  | Logradouro.                                                 |
| `number` *        | string  | Número do endereço.                                         |
| `neighborhood`    | string  | Bairro.                                                     |
| `postal_code` *   | string  | CEP (formato "00000-000").                                  |
| `city` *          | string  | Cidade.                                                     |
| `state` *         | string  | UF (2 letras).                                              |
| `complement`      | string  | Complemento do endereço.                                    |
| `is_pep`          | boolean | (PF) Indica se é Pessoa Politicamente Exposta.              |
| `marital_status`  | string  | (PF) Estado civil.                                          |
| `property_system` | string  | (PF) Regime de bens.                                        |
| `birthdate`       | string  | (PF) Data de nascimento.                                    |
| `mother_name`     | string  | (PF) Nome da mãe.                                           |
| `occupation`      | string  | (PF) Ocupação.                                              |
| `trading_name`    | string  | (PJ) Nome fantasia.                                         |
| `cnae_code`       | string  | (PJ) Código CNAE (formato "00.00-0-00").                    |
| `company_type`    | string  | (PJ) Tipo de empresa.                                       |
| `foundation_date` | string  | (PJ) Data de fundação.                                      |

:::warning Atenção
Os campos obrigatórios variam conforme o `person_type`:
- **Pessoa física (`natural`)**: além dos campos comuns, `is_pep` é obrigatório.
- **Pessoa jurídica (`legal`)**: além dos campos comuns, `trading_name`, `cnae_code`, `company_type` e `foundation_date` são obrigatórios.
:::

### Enumeradores role_type

| Enum | Descrição |
|------|-----------|
| `issuer` | Emissor. |
| `investor` | Investidor. |
| `cosigner` | Coobrigado. |
| `fiduciary_debtor` | Devedor fiduciante. |
| `solidary_debtor` | Devedor solidário. |
| `guarantor` | Avalista. |
| `bonafide_depositary` | Fiel depositário. |
| `intervening_guarantor` | Interveniente garantidor. |
| `intervening_consentor` | Interveniente anuente. |
| `intervening_discharger` | Interveniente quitante. |
| `assignor` | Cedente. |
| `endorser` | Endossante. |
| `consulting` | Consultoria. |
| `fund_administrator` | Administrador do fundo. |
| `fund_representative` | Representante do fundo. |
| `company_representative` | Representante da empresa. |
| `attestant` | Anuente / testemunha. |
| `debtor` | Devedor. |
| `bestowal` | Outorgante. |
| `manager` | Gestor. |

:::tip
Garantias e lastro são enviados em um **endpoint separado**, após a criação da operação. Consulte a página **Cadastro de lastro** desta seção.
:::

### Enumeradores signature_method

| Enum | Descrição |
|------|-----------|
| `certifiqi` | Valor padrão. A operação é enviada ao serviço de assinatura; um envelope de assinatura é criado e o cliente recebe a URL de assinatura (`signature_url`). |
| `qi_sign` | A operação é enviada ao serviço de assinatura; um envelope de assinatura é criado e o cliente recebe a URL de assinatura (`signature_url`). Permite também a consulta dos signatários da operação. |

## **Response**

STATUS 201

Response Body

```json
{
    "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814",
    "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127",
    "operation_status": "finished",
    "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e",
    "issuer_name": "Dynamic Enterprises",
    "issuer_document_number": "28980395000155",
    "issue_number": 10,
    "issue_series": 1,
    "related_party_list": [ ... ],
    "financial": { ... }
}
```

A resposta retorna o JSON completo da operação criada, incluindo `operation_key`, listas de investidores e partes relacionadas, e o objeto financeiro calculado.

---

# Envio de Documento

URL: /documentation/escrituracao/emissao-cri/envio-documento

Este endpoint permite o **envio de um documento** e retorna o `document_key` que o identifica. Esse `document_key` é utilizado para referenciar documentos em outros endpoints da operação sempre que for exigida a chave de um documento previamente enviado.

---

## **Request**

ENDPOINT /cri/upload
MÉTODO POST

Request Body

```json
{
    "document_base64": "string_b64"
}
```

### **Request Body Params**

| Campo             | Tipo   | Descrição                                    | Obrigatório |
|-------------------|--------|----------------------------------------------|-------------|
| `document_base64` * | string | Conteúdo do documento codificado em Base64. | Sim         |
| `document_name`   | string | Nome do documento.                           | -           |

## **Response**

STATUS 201

Response Body

```json
{
    "document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b"
}
```

### **Response Body Params**

| Campo          | Tipo   | Descrição                                       | Caracteres Máx. |
|----------------|--------|-------------------------------------------------|-----------------|
| `document_key` * | string | Chave única do documento enviado (UUID v4).    | 36              |

---

---

# Enviar Documento Externo da Operação

URL: /documentation/escrituracao/emissao-cri/envio-documento-externo

Este endpoint permite enviar documentos assinados de forma externa para o sistema de escrituração, enviando um base64 que será analisado e aprovado pelo escriturador.

:::warning Aviso
Este endpoint deve ser usado apenas para operações que utilizam o tipo de assinatura **client_side** ou para envio da ata de aprovação de empresas do tipo SA ou Cooperativas. Para o fluxo via QI Sign ou Certifiqi, os contratos são gerados de forma normal.
:::

---

## Enviar Documento Assinado (POST)

### Request

ENDPOINT /cri/operation/ OPERATION-KEY /upload_signed_document
MÉTODO POST

### Path Params

| Campo           | Tipo   | Descrição                            | Caracteres |
|-----------------|--------|--------------------------------------|------------|
| `OPERATION-KEY` | string | Chave única da operação (UUID v4).   | 36         |

---

### Request Body

Request Body

```json
{
    "contract_base64": "image_b64",
    "contract_type": "securitization_term"
}
```

### Request Body Params

| Campo               | Tipo   | Descrição                   | Caracteres Máx.                                              |
|---------------------|--------|-----------------------------|-------------------------------------------------------------|
| `contract_type` *   | string | Tipo de documento assinado. | **[Enumeradores contract_type](#enumeradores-contract_type)** |
| `contract_base64` * | string | Documento assinado em base64. | -                                                         |

### Enumeradores contract_type

| Enum                | Descrição                                  |
|---------------------|--------------------------------------------|
| `securitization_term` | Termo de securitização do CRI. |
| `adhesion_term` | Termo de adesão do CRI. |
| `sa_minute` | Ata de aprovação de emissão do CRI para empresa **SA**. |
| `ltda_minute` | Ata de aprovação de emissão do CRI para empresa **LTDA**. |
| `cop_minute` | Ata de aprovação de emissão do CRI para **Cooperativa**. |

### Response

O corpo da resposta é um JSON completo da operação atualizada.

---

---

# Atualização da conta de desembolso da operação.

URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-conta-desembolso

Este endpoint permite a atualização da conta de desembolso de uma operação.

---

## **Atualização da conta de desembolso da operação (PUT)**

### **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /issuer_bank_account
MÉTODO PUT

### **Path Params**

| Campo             | Tipo   | Descrição                                     | Caracteres Máx. |
|-------------------|--------|-----------------------------------------------|-----------------|
| `OPERATION-KEY` * | string | Chave única da operação (UUID v4).             | 36              |

Request Body

```json
{
    "issuer_bank_account": {
        "account_number": "4464541",
        "account_digit": "3",
        "account_branch": "0001",
        "financial_institution_code_number": "329",
        "financial_institution_ispb": "32402502",
        "account_type": "checking"
    }
}
```

### Request Body Params

### **Objeto issuer_bank_account**

| Campo                                   | Tipo   | Descrição                                |
| --------------------------------------- | ------ | ------------------------------------------ |
| `account_number` *                    | string | Número da conta bancária.                |
| `account_digit` *                     | string | Dígito da conta bancária.                |
| `account_branch` *                    | string | Agência da conta bancária.               |
| `financial_institution_code_number` * | string | Código da instituição financeira.       |
| `financial_institution_ispb` *        | string | Código ISPB da instituição financeira.  |
| `account_type` *                      | string | Tipo da conta (`checking`, `savings`). |

## **Response**

STATUS 200

Response Body

```json
{
    "tenant_key": "13a6a1d5-7a3c-4627-a0a6-9fd746662ca4",
    "operation_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74",
    "operation_type": "commercial_paper",
    "operation_status": "issued",
    "backoffice_analysis_status": "approved",
    "issuer_key": "9e08fd62-ce43-4c95-99e0-4386e980d618",
    "issuer_name": "Blue Logic",
    "issuer_document_number": "97.923.586/0001-06",
    "issuer_bank_account": {
        "account_type": "checking",
        "account_digit": "3",
        "account_branch": "0001",
        "account_number": "4464541",
        "financial_institution_ispb": "32402502",
        "financial_institution_code_number": "329"
    },
    "issuer_onboarding_approved": true,
    "issue_number": 1,
    "issue_series": 1,
    "contract_number": "0000000001",
    "issue_date": "2025-02-03",
    "financial_base_date": "2025-02-03",
    "commercial_paper_template_key": "68956441-d46c-44ed-93b9-b1806dd6ada9",
    "commercial_paper_document_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/commercial_paper/2cb87abc-8bdf-4df3-be98-b7afb53b14c8",
    "adhesion_term_template_key": "58743ab9-99bd-439a-93af-16e4c5fccd6f",
    "adhesion_term_document_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/adhesion_term/fe74eaed-2f44-45b4-b972-83fa222cbf1c",
    "envelope_signature_status": "signed",
    "envelope_key": "4d7f28b4-185f-482d-929e-d1af937cb27b",
    "envelope_signature_url": "https://sandbox.certifiqi.com.br/sign?batch-group=c4747fe6-2cc0-41a9-8972-84b44f8fff8a",
    "envelope_signed_files_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/signed_files",
    "financial": {
        "financial_base_date": "2025-02-03",
        "issue_quantity": 1000000,
        "unit_price": 1.0,
        "issue_amount": 1000000.0,
        "released_amount": 1000000.0,
        "cet": 5.0,
        "annual_cet": 79.59,
        "number_of_installments": 5,
        "prefixed_interest_rate": {
            "daily_rate": 0.0016053474,
            "annual_rate": 0.795856326,
            "monthly_rate": 0.05,
            "interest_base": "calendar_days_365"
        },
        "fine_delay_rate": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days_365"
        },
        "contract_fine_rate": 0.02,
        "financial_index": null,
        "post_fixed_interest_rate": null,
        "fees": [
            {
                "type": "internal",
                "amount": 2.0,
                "fee_type": "bookkeeping_fee",
                "fee_amount": 20000.0,
                "amount_type": "percentage"
            },
            {
                "type": "external",
                "amount": 5.0,
                "fee_type": "structuring_fee",
                "fee_amount": 50000.0,
                "amount_type": "percentage"
            }
        ],
        "installment_list": [
            {
                "installment_number": 1,
                "workdays": 20,
                "calendar_days": 30,
                "principal_amortization_unit_price": 0.18122484,
                "principal_amortization_amount": 181224.84138231,
                "interest_amount": 49298.45861769,
                "amount": 230523.3,
                "due_principal": 1000000.0,
                "due_interest": 0.0,
                "due_date": "2025-03-05",
                "has_interest": true
            },
            {
                "installment_number": 2,
                "workdays": 21,
                "calendar_days": 29,
                "principal_amortization_unit_price": 0.19153595,
                "principal_amortization_amount": 191535.95353305,
                "interest_amount": 38987.34646695,
                "amount": 230523.3,
                "due_principal": 818775.15861769,
                "due_interest": 0.0,
                "due_date": "2025-04-03",
                "has_interest": true
            },
            {
                "installment_number": 3,
                "workdays": 19,
                "calendar_days": 32,
                "principal_amortization_unit_price": 0.19748652,
                "principal_amortization_amount": 197486.52331007,
                "interest_amount": 33036.77668993,
                "amount": 230523.3,
                "due_principal": 627239.20508464,
                "due_interest": 0.0,
                "due_date": "2025-05-05",
                "has_interest": true
            },
            {
                "installment_number": 4,
                "workdays": 21,
                "calendar_days": 29,
                "principal_amortization_unit_price": 0.21005991,
                "principal_amortization_amount": 210059.90840452,
                "interest_amount": 20463.39159548,
                "amount": 230523.3,
                "due_principal": 429752.68177457,
                "due_interest": 0.0,
                "due_date": "2025-06-03",
                "has_interest": true
            },
            {
                "installment_number": 5,
                "workdays": 21,
                "calendar_days": 30,
                "principal_amortization_unit_price": 0.21969277,
                "principal_amortization_amount": 219692.77337005,
                "interest_amount": 10830.52662995,
                "amount": 230523.3,
                "due_principal": 219692.77337005,
                "due_interest": 0.0,
                "due_date": "2025-07-03",
                "has_interest": true
            }
        ]
    },
    "tags": [],
    "investor_list": [
        {
            "investor_key": "a1a75b66-6f7e-4bcc-9ff5-6f8adf7cae09",
            "investor_name": "Ultimate Cascade",
            "investor_document_number": "31.424.651/0001-32",
            "subscription_percentage": 100.0,
            "subscription_quantity": 1000000,
            "investor_onboarding_approved": true,
            "bank_account": {
                "account_type": "checking",
                "account_digit": "3",
                "account_branch": "0001",
                "account_number": "33400254",
                "financial_institution_ispb": "32402502",
                "financial_institution_code_number": "329"
            },
            "updated_at": null
        }
    ],
    "related_party_list": [
        {
            "related_party_key": "1ac83d43-41cb-4ad0-a7ca-add6c3a3171c",
            "name": "Blue Logic",
            "document_number": "97.923.586/0001-06",
            "role_type": "issuer",
            "is_active": true,
            "updated_at": null,
            "trading_name": "Blue Logic",
            "cnae_code": "47.21-1-02",
            "company_type": "ltda",
            "foundation_date": "2007-10-25",
            "person_type": "legal",
            "street": "Rua Romualdo de Souza Brito",
            "neighborhood": "Centro",
            "number": "89",
            "postal_code": "08150-470",
            "city": "São Paulo",
            "state": "SP",
            "complement": "Letra C",
            "signer_group_list": [
                {
                    "signer_group_key": "fa2cbede-a501-41e1-bf70-078bb0d4ac7b",
                    "minimum_required_signers": 1,
                    "signers": [
                        {
                            "name": "John Doe",
                            "email": "123.456.789-00@yopmail.com",
                            "phone_number": "+5511988887777",
                            "document_number": "123.456.789-00",
                            "is_group_mandatory": true
                        }
                    ]
                }
            ],
            "document_list": [],
            "contact_information_list": [
                {
                    "name": "John Doe",
                    "email": "123.456.789-00@yopmail.com",
                    "is_default": true,
                    "phone_number": "+5516982399722",
                    "document_number": "123.456.789-00",
                    "issuer_contact_information_key": "6e9714f4-d652-4ca0-89e2-13e9e2ec3414"
                }
            ]
        },
        {
            "related_party_key": "bab03c76-a12a-4d88-aaf8-70799e3b1b30",
            "name": "Ultimate Cascade",
            "document_number": "31.424.651/0001-32",
            "role_type": "investor",
            "is_active": true,
            "updated_at": null,
            "trading_name": "Ultimate Cascade",
            "cnae_code": "47.21-1-02",
            "company_type": "ltda",
            "foundation_date": "2007-10-25",
            "person_type": "legal",
            "street": "Rua Romualdo de Souza Brito",
            "neighborhood": "Centro",
            "number": "89",
            "postal_code": "08150-470",
            "city": "São Paulo",
            "state": "SP",
            "complement": "Letra C",
            "signer_group_list": [
                {
                    "signer_group_key": "ccb36b0b-40b5-42e0-bc41-0e8fce57f3ca",
                    "minimum_required_signers": 1,
                    "signers": [
                        {
                            "name": "John Doe",
                            "email": "123.456.789-00@yopmail.com",
                            "phone_number": "+5516982399722",
                            "document_number": "123.456.789-00",
                            "is_group_mandatory": true
                        }
                    ]
                }
            ],
            "document_list": [],
            "contact_information_list": [
                {
                    "name": "John Doe",
                    "email": "123.456.789-00@yopmail.com",
                    "is_default": true,
                    "phone_number": "+5511988887777",
                    "document_number": "123.456.789-00",
                    "investor_contact_information_key": "26299c0f-2127-45d4-b22e-f2b494d2f7ae"
                }
            ]
        }
    ],
    "collateral_list": [
        {
            "collateral_key": "d8fdb578-1e2a-4b79-8267-5b1763e56754",
            "collateral_type": "fiduciary_alienation_property"
        }
    ],
    "metadata_list": [
        {
            "metadata_key": "convenio",
            "metadata_value": "12398129038"
        }
    ],
    "signature_method": "qi_sign"
}
```

### **Response Body Params**

| Campo                        | Tipo   | Descrição                                           |
| ---------------------------- | ------ | ----------------------------------------------------- |
| `tenant_key` *             | string | Chave única do tenant.                               |
| `operation_key` *          | string | Chave única da operação.                           |
| `operation_status` *       | string | Status da operação.                                 |
| `issuer_key` *             | string | Chave única do emissor.                              |
| `issuer_name` *            | string | Nome do emissor.                                      |
| `issuer_document_number` * | string | Documento do emissor.                                 |
| `financial` *              | object | **[Objeto financial](#objeto-financial-response)** |

### Objeto financial response

| Campo                        | Tipo    | Descrição                                                | Caracteres Máx.                                                       |
| ---------------------------- | ------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- |
| `financial_base_date` *    | string  | Data base financeira da operação (formato "YYYY-MM-DD"). | -                                                                      |
| `issue_amount` *           | number  | Valor total emitido da operação.                         | -                                                                      |
| `released_amount` *        | number  | Valor líquido liberado na operação.                     | -                                                                      |
| `issue_quantity` *         | integer | Quantidade total de unidades emitidas.                     | -                                                                      |
| `unit_price` *             | number  | Preço unitário da emissão.                              | -                                                                      |
| `cet` *                    | number  | Custo Efetivo Total (CET) em percentual.                   | -                                                                      |
| `annual_cet` *             | number  | CET anual em percentual.                                   | -                                                                      |
| `number_of_installments` * | integer | Número total de parcelas.                                 | -                                                                      |
| `prefixed_interest_rate` * | object  | Objeto contendo detalhes da taxa de juros prefixada.       | **[Objeto prefixed_interest_rate](#objeto-prefixed_interest_rate)** |
| `fees`                     | array   | Lista de taxas associadas à operação.                   | **[Objeto fees](#objeto-fees)**                                     |
| `installments`             | array   | Lista de detalhes das parcelas geradas na operação.      | **[Objeto installments](#objeto-installments)**                     |
| `fine_delay_rate` *        | object  | Objeto contendo detalhes da multa por atraso.              | **[Objeto fine_delay_rate](#objeto-fine_delay_rate)**               |
| `contract_fine_rate` *     | number  | Multa contratual aplicada em percentual.                   | -                                                                      |

### Objeto prefixed_interest_rate

| Campo               | Tipo   | Descrição                     | Caracteres Máx.                                                 |
| ------------------- | ------ | ------------------------------- | ---------------------------------------------------------------- |
| `interest_base` * | string | Base de cálculo para os juros. | **[Enumeradores interest_base](#enumeradores-interest_base)** |
| `monthly_rate` *  | number | Taxa de juros mensal aplicada.  | -                                                                |
| `daily_rate` *    | number | Taxa de juros diária aplicada. | -                                                                |
| `annual_rate` *   | number | Taxa de juros anual aplicada.   | -                                                                |

### Objeto fees

| Campo             | Tipo   | Descrição                              | Caracteres Máx.                                                 |
| ----------------- | ------ | ---------------------------------------- | ---------------------------------------------------------------- |
| `amount` *      | number | Valor percentual da taxa.                | -                                                                |
| `fee_amount` *  | number | Valor monetário correspondente à taxa. | -                                                                |
| `amount_type` * | string | Tipo do valor da taxa.                   | **[Enumeradores amount_type](#enumeradores-amount_type)**     |
| `fee_type` *    | string | Tipo da taxa.                            | **[Enumeradores fee_type](#enumeradores-fee_type)**           |
| `type` *        | string | Destinatário da taxa.                   | **[Enumeradores fee_recipient](#enumeradores-fee_recipient)** |

### Objeto installments

| Campo                                   | Tipo    | Descrição                                           |
| --------------------------------------- | ------- | ----------------------------------------------------- |
| `installment_number` *                | integer | Número da parcela.                                   |
| `workdays` *                          | integer | Dias úteis até o vencimento da parcela.             |
| `calendar_days` *                     | integer | Dias corridos até o vencimento da parcela.           |
| `principal_amortization_amount` *     | number  | Valor amortizado do principal.                        |
| `principal_amortization_unit_price` * | number  | Valor amortizado por unidade.                         |
| `interest_amount` *                   | number  | Valor dos juros aplicados na parcela.                 |
| `amount` *                            | number  | Valor total da parcela.                               |
| `due_date` *                          | string  | Data de vencimento da parcela (formato "YYYY-MM-DD"). |

---

# Atualização de dados financeiros na Operação

URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-dados-financeiros

Este endpoint permite a atualização dos dados financeiros em uma operação, seguindo o padrão de objeto financial, também enviado no endpoint de simulação.

---

## **Atualização de dados financeiros na Operação (PUT)**

### **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /financial
MÉTODO PUT

### **Path Params**

| Campo             | Tipo   | Descrição                                     | Caracteres Máx. |
|-------------------|--------|-----------------------------------------------|-----------------|
| `OPERATION-KEY` * | string | Chave única da operação (UUID v4).             | 36              |

Request Body

```json
{
    "interest_type": "pre_price_days",
    "financial_base_date": "2025-02-03",
    "released_amount": 1000000,
    "number_of_installments": 5,
    "prefixed_interest_rate": {
        "interest_base": "calendar_days_365", 
        "monthly_rate": 0.05
    },
    "fine_delay_rate": {
        "interest_base": "calendar_days_365", 
        "monthly_rate": 0.01
    },
    "contract_fine_rate": 0.02,
    "fees": [
        {
            "amount": 5, 
            "amount_type": "percentage", 
            "fee_type": "structuring_fee",
            "type": "external"
        }
    ]
}
```

### Request Body Params

| Campo                        | Tipo     | Descrição                                                                                                                       | Caracteres Máx. |
|------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------|
| `interest_type` *            | string   | Tipo de juros aplicado. | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `financial_base_date` *      | string   | Data base da operação (formato "YYYY-MM-DD").                                                                                   | -               |
| `released_amount` *          | number   | Valor total liberado na operação.                                                                                               | -               |
| `number_of_installments` *   | integer  | Número total de parcelas.                                                                                                       | -               |
| `prefixed_interest_rate` *   | object   | Objeto contendo detalhes da taxa de juros prefixada.                                                                            | **[Objeto prefixed_interest_rate](#objeto-prefixed_interest_rate)** |
| `fine_delay_rate` *          | object   | Objeto contendo detalhes da multa por atraso.                                                                                   | **[Objeto fine_delay_rate](#objeto-fine_delay_rate)** |
| `contract_fine_rate` *       | number   | Multa contratual aplicada em percentual.                                                                                       | -               |
| `fees`                       | array    | Lista de taxas associadas à operação.                                                                                           | **[Objeto fees](#objeto-fees)** |

### Objeto prefixed_interest_rate

| Campo                        | Tipo     | Descrição                                                                                                                       | Caracteres Máx. |
|------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------|
| `interest_base` *            | string   | Base de cálculo para os juros. | **[Enumeradores interest_base](#enumeradores-interest_base)** |
| `monthly_rate` *             | number   | Taxa de juros mensal aplicada.                                                                                                  | -               |

### Objeto fine_delay_rate

| Campo                        | Tipo     | Descrição                                                                                                                       | Caracteres Máx. |
|------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------|
| `interest_base` *            | string   | Base para cálculo da multa. | **[Enumeradores interest_base](#enumeradores-interest_base)** |
| `monthly_rate` *             | number   | Taxa de multa mensal.                                                                                                          | -               |

### Objeto fees

| Campo                        | Tipo     | Descrição                                                                                                                       | Caracteres Máx. |
|------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------|
| `amount` *                   | number   | Valor da taxa aplicada.                                                                                                        | -               |
| `amount_type` *              | string   | Tipo do valor da taxa. | **[Enumeradores amount_type](#enumeradores-amount_type)** |
| `fee_type` *                 | string   | Tipo da taxa. | **[Enumeradores fee_type](#enumeradores-fee_type)** |
| `type` *                     | string   | Destinatário da taxa. | **[Enumeradores fee_recipient](#enumeradores-fee_recipient)** |

### Enumeradores interest_type

| Enum                | Descrição                                  |
|--------------------|------------------------------------------|
| `pre_price`       | Juros pré-fixados no modelo Price.       |
| `pre_price_days`  | Juros pré-fixados no modelo Price por dias corridos. |
| `pre_sac`         | Juros pré-fixados no modelo SAC.         |
| `post_sac`        | Juros pós-fixados no modelo SAC.         |

### Enumeradores interest_base

| Enum                | Descrição                                  |
|--------------------|------------------------------------------|
| `calendar_days`    | Base de dias corridos.                   |
| `calendar_days_365`| Base de 365 dias corridos.               |
| `workdays`        | Base de dias úteis.                      |

### Enumeradores amount_type

| Enum         | Descrição                   |
|-------------|---------------------------|
| `percentage` | Valor em percentual.       |
| `absolute`   | Valor absoluto em moeda.   |

### Enumeradores fee_type

| Enum                                | Descrição                                 |
|-------------------------------------|-------------------------------------------|
| `bookkeeping_fee`                   | Taxa de escrituração financiada.          |
| `structuring_fee`                   | Taxa de estruturação financiada.          |

### Enumeradores fee_recipient

| Enum       | Descrição                                               |
|-----------|-------------------------------------------------------|
| `internal` | Taxa paga ao escriturador.                           |
| `external` | Rebate pago ao originador.                           |

## **Response**

STATUS 200

Response Body

```json
{
    "tenant_key": "13a6a1d5-7a3c-4627-a0a6-9fd746662ca4",
    "operation_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74",
    "operation_type": "commercial_paper",
    "operation_status": "issued",
    "backoffice_analysis_status": "approved",
    "issuer_key": "9e08fd62-ce43-4c95-99e0-4386e980d618",
    "issuer_name": "Blue Logic",
    "issuer_document_number": "97.923.586/0001-06",
    "issuer_bank_account": {
        "account_type": "checking",
        "account_digit": "3",
        "account_branch": "0001",
        "account_number": "4464541",
        "financial_institution_ispb": "32402502",
        "financial_institution_code_number": "329"
    },
    "issuer_onboarding_approved": true,
    "issue_number": 1,
    "issue_series": 1,
    "contract_number": "0000000001",
    "issue_date": "2025-02-03",
    "financial_base_date": "2025-02-03",
    "commercial_paper_template_key": "68956441-d46c-44ed-93b9-b1806dd6ada9",
    "commercial_paper_document_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/commercial_paper/2cb87abc-8bdf-4df3-be98-b7afb53b14c8",
    "adhesion_term_template_key": "58743ab9-99bd-439a-93af-16e4c5fccd6f",
    "adhesion_term_document_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/adhesion_term/fe74eaed-2f44-45b4-b972-83fa222cbf1c",
    "envelope_signature_status": "signed",
    "envelope_key": "4d7f28b4-185f-482d-929e-d1af937cb27b",
    "envelope_signature_url": "https://sandbox.certifiqi.com.br/sign?batch-group=c4747fe6-2cc0-41a9-8972-84b44f8fff8a",
    "envelope_signed_files_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/signed_files",
    "financial": {
        "financial_base_date": "2025-02-03",
        "issue_quantity": 1000000,
        "unit_price": 1.0,
        "issue_amount": 1000000.0,
        "released_amount": 1000000.0,
        "cet": 5.0,
        "annual_cet": 79.59,
        "number_of_installments": 5,
        "prefixed_interest_rate": {
            "daily_rate": 0.0016053474,
            "annual_rate": 0.795856326,
            "monthly_rate": 0.05,
            "interest_base": "calendar_days_365"
        },
        "fine_delay_rate": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days_365"
        },
        "contract_fine_rate": 0.02,
        "financial_index": null,
        "post_fixed_interest_rate": null,
        "fees": [
            {
                "type": "internal",
                "amount": 2.0,
                "fee_type": "bookkeeping_fee",
                "fee_amount": 20000.0,
                "amount_type": "percentage"
            },
            {
                "type": "external",
                "amount": 5.0,
                "fee_type": "structuring_fee",
                "fee_amount": 50000.0,
                "amount_type": "percentage"
            }
        ],
        "installment_list": [
            {
                "installment_number": 1,
                "workdays": 20,
                "calendar_days": 30,
                "principal_amortization_unit_price": 0.18122484,
                "principal_amortization_amount": 181224.84138231,
                "interest_amount": 49298.45861769,
                "amount": 230523.3,
                "due_principal": 1000000.0,
                "due_interest": 0.0,
                "due_date": "2025-03-05",
                "has_interest": true
            },
            {
                "installment_number": 2,
                "workdays": 21,
                "calendar_days": 29,
                "principal_amortization_unit_price": 0.19153595,
                "principal_amortization_amount": 191535.95353305,
                "interest_amount": 38987.34646695,
                "amount": 230523.3,
                "due_principal": 818775.15861769,
                "due_interest": 0.0,
                "due_date": "2025-04-03",
                "has_interest": true
            },
            {
                "installment_number": 3,
                "workdays": 19,
                "calendar_days": 32,
                "principal_amortization_unit_price": 0.19748652,
                "principal_amortization_amount": 197486.52331007,
                "interest_amount": 33036.77668993,
                "amount": 230523.3,
                "due_principal": 627239.20508464,
                "due_interest": 0.0,
                "due_date": "2025-05-05",
                "has_interest": true
            },
            {
                "installment_number": 4,
                "workdays": 21,
                "calendar_days": 29,
                "principal_amortization_unit_price": 0.21005991,
                "principal_amortization_amount": 210059.90840452,
                "interest_amount": 20463.39159548,
                "amount": 230523.3,
                "due_principal": 429752.68177457,
                "due_interest": 0.0,
                "due_date": "2025-06-03",
                "has_interest": true
            },
            {
                "installment_number": 5,
                "workdays": 21,
                "calendar_days": 30,
                "principal_amortization_unit_price": 0.21969277,
                "principal_amortization_amount": 219692.77337005,
                "interest_amount": 10830.52662995,
                "amount": 230523.3,
                "due_principal": 219692.77337005,
                "due_interest": 0.0,
                "due_date": "2025-07-03",
                "has_interest": true
            }
        ]
    },
    "tags": [],
    "investor_list": [
        {
            "investor_key": "a1a75b66-6f7e-4bcc-9ff5-6f8adf7cae09",
            "investor_name": "Ultimate Cascade",
            "investor_document_number": "31.424.651/0001-32",
            "subscription_percentage": 100.0,
            "subscription_quantity": 1000000,
            "investor_onboarding_approved": true,
            "bank_account": {
                "account_type": "checking",
                "account_digit": "3",
                "account_branch": "0001",
                "account_number": "33400254",
                "financial_institution_ispb": "32402502",
                "financial_institution_code_number": "329"
            },
            "updated_at": null
        }
    ],
    "related_party_list": [
        {
            "related_party_key": "1ac83d43-41cb-4ad0-a7ca-add6c3a3171c",
            "name": "Blue Logic",
            "document_number": "97.923.586/0001-06",
            "role_type": "issuer",
            "is_active": true,
            "updated_at": null,
            "trading_name": "Blue Logic",
            "cnae_code": "47.21-1-02",
            "company_type": "ltda",
            "foundation_date": "2007-10-25",
            "person_type": "legal",
            "street": "Rua Romualdo de Souza Brito",
            "neighborhood": "Centro",
            "number": "89",
            "postal_code": "08150-470",
            "city": "São Paulo",
            "state": "SP",
            "complement": "Letra C",
            "signer_group_list": [
                {
                    "signer_group_key": "fa2cbede-a501-41e1-bf70-078bb0d4ac7b",
                    "minimum_required_signers": 1,
                    "signers": [
                        {
                            "name": "John Doe",
                            "email": "123.456.789-00@yopmail.com",
                            "phone_number": "+5511988887777",
                            "document_number": "123.456.789-00",
                            "is_group_mandatory": true
                        }
                    ]
                }
            ],
            "document_list": [],
            "contact_information_list": [
                {
                    "name": "John Doe",
                    "email": "123.456.789-00@yopmail.com",
                    "is_default": true,
                    "phone_number": "+5516982399722",
                    "document_number": "123.456.789-00",
                    "issuer_contact_information_key": "6e9714f4-d652-4ca0-89e2-13e9e2ec3414"
                }
            ]
        },
        {
            "related_party_key": "bab03c76-a12a-4d88-aaf8-70799e3b1b30",
            "name": "Ultimate Cascade",
            "document_number": "31.424.651/0001-32",
            "role_type": "investor",
            "is_active": true,
            "updated_at": null,
            "trading_name": "Ultimate Cascade",
            "cnae_code": "47.21-1-02",
            "company_type": "ltda",
            "foundation_date": "2007-10-25",
            "person_type": "legal",
            "street": "Rua Romualdo de Souza Brito",
            "neighborhood": "Centro",
            "number": "89",
            "postal_code": "08150-470",
            "city": "São Paulo",
            "state": "SP",
            "complement": "Letra C",
            "signer_group_list": [
                {
                    "signer_group_key": "ccb36b0b-40b5-42e0-bc41-0e8fce57f3ca",
                    "minimum_required_signers": 1,
                    "signers": [
                        {
                            "name": "John Doe",
                            "email": "123.456.789-00@yopmail.com",
                            "phone_number": "+5516982399722",
                            "document_number": "123.456.789-00",
                            "is_group_mandatory": true
                        }
                    ]
                }
            ],
            "document_list": [],
            "contact_information_list": [
                {
                    "name": "John Doe",
                    "email": "123.456.789-00@yopmail.com",
                    "is_default": true,
                    "phone_number": "+5511988887777",
                    "document_number": "123.456.789-00",
                    "investor_contact_information_key": "26299c0f-2127-45d4-b22e-f2b494d2f7ae"
                }
            ]
        }
    ],
    "collateral_list": [
        {
            "collateral_key": "d8fdb578-1e2a-4b79-8267-5b1763e56754",
            "collateral_type": "fiduciary_alienation_property"
        }
    ],
    "metadata_list": [
        {
            "metadata_key": "convenio",
            "metadata_value": "12398129038"
        }
    ],
}
```

### **Response Body Params**

| Campo                        | Tipo   | Descrição                                           |
| ---------------------------- | ------ | ----------------------------------------------------- |
| `tenant_key` *             | string | Chave única do tenant.                               |
| `operation_key` *          | string | Chave única da operação.                           |
| `operation_status` *       | string | Status da operação.                                 |
| `issuer_key` *             | string | Chave única do emissor.                              |
| `issuer_name` *            | string | Nome do emissor.                                      |
| `issuer_document_number` * | string | Documento do emissor.                                 |
| `financial` *              | object | **[Objeto financial](#objeto-financial-response)** |

### Objeto financial response

| Campo                        | Tipo    | Descrição                                                | Caracteres Máx.                                                       |
| ---------------------------- | ------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- |
| `financial_base_date` *    | string  | Data base financeira da operação (formato "YYYY-MM-DD"). | -                                                                      |
| `issue_amount` *           | number  | Valor total emitido da operação.                         | -                                                                      |
| `released_amount` *        | number  | Valor líquido liberado na operação.                     | -                                                                      |
| `issue_quantity` *         | integer | Quantidade total de unidades emitidas.                     | -                                                                      |
| `unit_price` *             | number  | Preço unitário da emissão.                              | -                                                                      |
| `cet` *                    | number  | Custo Efetivo Total (CET) em percentual.                   | -                                                                      |
| `annual_cet` *             | number  | CET anual em percentual.                                   | -                                                                      |
| `number_of_installments` * | integer | Número total de parcelas.                                 | -                                                                      |
| `prefixed_interest_rate` * | object  | Objeto contendo detalhes da taxa de juros prefixada.       | **[Objeto prefixed_interest_rate](#objeto-prefixed_interest_rate)** |
| `fees`                     | array   | Lista de taxas associadas à operação.                   | **[Objeto fees](#objeto-fees)**                                     |
| `installments`             | array   | Lista de detalhes das parcelas geradas na operação.      | **[Objeto installments](#objeto-installments)**                     |
| `fine_delay_rate` *        | object  | Objeto contendo detalhes da multa por atraso.              | **[Objeto fine_delay_rate](#objeto-fine_delay_rate)**               |
| `contract_fine_rate` *     | number  | Multa contratual aplicada em percentual.                   | -                                                                      |

### Objeto prefixed_interest_rate

| Campo               | Tipo   | Descrição                     | Caracteres Máx.                                                 |
| ------------------- | ------ | ------------------------------- | ---------------------------------------------------------------- |
| `interest_base` * | string | Base de cálculo para os juros. | **[Enumeradores interest_base](#enumeradores-interest_base)** |
| `monthly_rate` *  | number | Taxa de juros mensal aplicada.  | -                                                                |
| `daily_rate` *    | number | Taxa de juros diária aplicada. | -                                                                |
| `annual_rate` *   | number | Taxa de juros anual aplicada.   | -                                                                |

### Objeto fees

| Campo             | Tipo   | Descrição                              | Caracteres Máx.                                                 |
| ----------------- | ------ | ---------------------------------------- | ---------------------------------------------------------------- |
| `amount` *      | number | Valor percentual da taxa.                | -                                                                |
| `fee_amount` *  | number | Valor monetário correspondente à taxa. | -                                                                |
| `amount_type` * | string | Tipo do valor da taxa.                   | **[Enumeradores amount_type](#enumeradores-amount_type)**     |
| `fee_type` *    | string | Tipo da taxa.                            | **[Enumeradores fee_type](#enumeradores-fee_type)**           |
| `type` *        | string | Destinatário da taxa.                   | **[Enumeradores fee_recipient](#enumeradores-fee_recipient)** |

### Objeto installments

| Campo                                   | Tipo    | Descrição                                           |
| --------------------------------------- | ------- | ----------------------------------------------------- |
| `installment_number` *                | integer | Número da parcela.                                   |
| `workdays` *                          | integer | Dias úteis até o vencimento da parcela.             |
| `calendar_days` *                     | integer | Dias corridos até o vencimento da parcela.           |
| `principal_amortization_amount` *     | number  | Valor amortizado do principal.                        |
| `principal_amortization_unit_price` * | number  | Valor amortizado por unidade.                         |
| `interest_amount` *                   | number  | Valor dos juros aplicados na parcela.                 |
| `amount` *                            | number  | Valor total da parcela.                               |
| `due_date` *                          | string  | Data de vencimento da parcela (formato "YYYY-MM-DD"). |

---

# Atualização de dados dos investidores na Operação

URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-investidores

Este endpoint permite a atualização dos dados dos investidores em uma operação. 

---

## **Atualização de dados dos investidores na Operação (PUT)**

### **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /investors
MÉTODO PUT

### **Path Params**

| Campo             | Tipo   | Descrição                                     | Caracteres Máx. |
|-------------------|--------|-----------------------------------------------|-----------------|
| `OPERATION-KEY` * | string | Chave única da operação (UUID v4).             | 36              |

Request Body

```json
{
    "investors": [
        {
            "investor_key": "a1a75b66-6f7e-4bcc-9ff5-6f8adf7cae09",
            "investor_name": "Ultimate Cascade",
            "investor_document_number": "31.424.651/0001-32",
            "subscription_quantity": 1000000,
            "bank_account": {
                "account_type": "checking",
                "account_digit": "3",
                "account_branch": "0001",
                "account_number": "33400254",
                "financial_institution_ispb": "32402502",
                "financial_institution_code_number": "329"
            }
        }
    ]
}
```

### **Request Body Params**

### **Objeto investors**

| Campo                         | Tipo   | Descrição                    |
| ----------------------------- | ------ | ------------------------------ |
| `investor_key` *            | string | Chave única do investidor.    |
| `subscription_percentage` * | number | Percentual de subscrição.    |
| `bank_account` *            | object | Conta bancária do investidor. |

### **Objeto bank_account**

| Campo                                   | Tipo   | Descrição                                |
| --------------------------------------- | ------ | ------------------------------------------ |
| `account_number` *                    | string | Número da conta bancária.                |
| `account_digit` *                     | string | Dígito da conta bancária.                |
| `account_branch` *                    | string | Agência da conta bancária.               |
| `financial_institution_code_number` * | string | Código da instituição financeira.       |
| `financial_institution_ispb` *        | string | Código ISPB da instituição financeira.  |
| `account_type` *                      | string | Tipo da conta (`checking`, `savings`). |

## **Response**

STATUS 200

Response Body

```json
{
    "tenant_key": "13a6a1d5-7a3c-4627-a0a6-9fd746662ca4",
    "operation_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74",
    "operation_type": "commercial_paper",
    "operation_status": "issued",
    "backoffice_analysis_status": "approved",
    "issuer_key": "9e08fd62-ce43-4c95-99e0-4386e980d618",
    "issuer_name": "Blue Logic",
    "issuer_document_number": "97.923.586/0001-06",
    "issuer_bank_account": {
        "account_type": "checking",
        "account_digit": "3",
        "account_branch": "0001",
        "account_number": "4464541",
        "financial_institution_ispb": "32402502",
        "financial_institution_code_number": "329"
    },
    "issuer_onboarding_approved": true,
    "issue_number": 1,
    "issue_series": 1,
    "contract_number": "0000000001",
    "issue_date": "2025-02-03",
    "financial_base_date": "2025-02-03",
    "commercial_paper_template_key": "68956441-d46c-44ed-93b9-b1806dd6ada9",
    "commercial_paper_document_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/commercial_paper/2cb87abc-8bdf-4df3-be98-b7afb53b14c8",
    "adhesion_term_template_key": "58743ab9-99bd-439a-93af-16e4c5fccd6f",
    "adhesion_term_document_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/adhesion_term/fe74eaed-2f44-45b4-b972-83fa222cbf1c",
    "envelope_signature_status": "signed",
    "envelope_key": "4d7f28b4-185f-482d-929e-d1af937cb27b",
    "envelope_signature_url": "https://sandbox.certifiqi.com.br/sign?batch-group=c4747fe6-2cc0-41a9-8972-84b44f8fff8a",
    "envelope_signed_files_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/signed_files",
    "financial": {
        "financial_base_date": "2025-02-03",
        "issue_quantity": 1000000,
        "unit_price": 1.0,
        "issue_amount": 1000000.0,
        "released_amount": 1000000.0,
        "cet": 5.0,
        "annual_cet": 79.59,
        "number_of_installments": 5,
        "prefixed_interest_rate": {
            "daily_rate": 0.0016053474,
            "annual_rate": 0.795856326,
            "monthly_rate": 0.05,
            "interest_base": "calendar_days_365"
        },
        "fine_delay_rate": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days_365"
        },
        "contract_fine_rate": 0.02,
        "financial_index": null,
        "post_fixed_interest_rate": null,
        "fees": [
            {
                "type": "internal",
                "amount": 2.0,
                "fee_type": "bookkeeping_fee",
                "fee_amount": 20000.0,
                "amount_type": "percentage"
            },
            {
                "type": "external",
                "amount": 5.0,
                "fee_type": "structuring_fee",
                "fee_amount": 50000.0,
                "amount_type": "percentage"
            }
        ],
        "installment_list": [
            {
                "installment_number": 1,
                "workdays": 20,
                "calendar_days": 30,
                "principal_amortization_unit_price": 0.18122484,
                "principal_amortization_amount": 181224.84138231,
                "interest_amount": 49298.45861769,
                "amount": 230523.3,
                "due_principal": 1000000.0,
                "due_interest": 0.0,
                "due_date": "2025-03-05",
                "has_interest": true
            },
            {
                "installment_number": 2,
                "workdays": 21,
                "calendar_days": 29,
                "principal_amortization_unit_price": 0.19153595,
                "principal_amortization_amount": 191535.95353305,
                "interest_amount": 38987.34646695,
                "amount": 230523.3,
                "due_principal": 818775.15861769,
                "due_interest": 0.0,
                "due_date": "2025-04-03",
                "has_interest": true
            },
            {
                "installment_number": 3,
                "workdays": 19,
                "calendar_days": 32,
                "principal_amortization_unit_price": 0.19748652,
                "principal_amortization_amount": 197486.52331007,
                "interest_amount": 33036.77668993,
                "amount": 230523.3,
                "due_principal": 627239.20508464,
                "due_interest": 0.0,
                "due_date": "2025-05-05",
                "has_interest": true
            },
            {
                "installment_number": 4,
                "workdays": 21,
                "calendar_days": 29,
                "principal_amortization_unit_price": 0.21005991,
                "principal_amortization_amount": 210059.90840452,
                "interest_amount": 20463.39159548,
                "amount": 230523.3,
                "due_principal": 429752.68177457,
                "due_interest": 0.0,
                "due_date": "2025-06-03",
                "has_interest": true
            },
            {
                "installment_number": 5,
                "workdays": 21,
                "calendar_days": 30,
                "principal_amortization_unit_price": 0.21969277,
                "principal_amortization_amount": 219692.77337005,
                "interest_amount": 10830.52662995,
                "amount": 230523.3,
                "due_principal": 219692.77337005,
                "due_interest": 0.0,
                "due_date": "2025-07-03",
                "has_interest": true
            }
        ]
    },
    "tags": [],
    "investor_list": [
        {
            "investor_key": "a1a75b66-6f7e-4bcc-9ff5-6f8adf7cae09",
            "investor_name": "Ultimate Cascade",
            "investor_document_number": "31.424.651/0001-32",
            "subscription_percentage": 100.0,
            "subscription_quantity": 1000000,
            "investor_onboarding_approved": true,
            "bank_account": {
                "account_type": "checking",
                "account_digit": "3",
                "account_branch": "0001",
                "account_number": "33400254",
                "financial_institution_ispb": "32402502",
                "financial_institution_code_number": "329"
            },
            "updated_at": null
        }
    ],
    "related_party_list": [
        {
            "related_party_key": "1ac83d43-41cb-4ad0-a7ca-add6c3a3171c",
            "name": "Blue Logic",
            "document_number": "97.923.586/0001-06",
            "role_type": "issuer",
            "is_active": true,
            "updated_at": null,
            "trading_name": "Blue Logic",
            "cnae_code": "47.21-1-02",
            "company_type": "ltda",
            "foundation_date": "2007-10-25",
            "person_type": "legal",
            "street": "Rua Romualdo de Souza Brito",
            "neighborhood": "Centro",
            "number": "89",
            "postal_code": "08150-470",
            "city": "São Paulo",
            "state": "SP",
            "complement": "Letra C",
            "signer_group_list": [
                {
                    "signer_group_key": "fa2cbede-a501-41e1-bf70-078bb0d4ac7b",
                    "minimum_required_signers": 1,
                    "signers": [
                        {
                            "name": "John Doe",
                            "email": "123.456.789-00@yopmail.com",
                            "phone_number": "+5511988887777",
                            "document_number": "123.456.789-00",
                            "is_group_mandatory": true
                        }
                    ]
                }
            ],
            "document_list": [],
            "contact_information_list": [
                {
                    "name": "John Doe",
                    "email": "123.456.789-00@yopmail.com",
                    "is_default": true,
                    "phone_number": "+5516982399722",
                    "document_number": "123.456.789-00",
                    "issuer_contact_information_key": "6e9714f4-d652-4ca0-89e2-13e9e2ec3414"
                }
            ]
        },
        {
            "related_party_key": "bab03c76-a12a-4d88-aaf8-70799e3b1b30",
            "name": "Ultimate Cascade",
            "document_number": "31.424.651/0001-32",
            "role_type": "investor",
            "is_active": true,
            "updated_at": null,
            "trading_name": "Ultimate Cascade",
            "cnae_code": "47.21-1-02",
            "company_type": "ltda",
            "foundation_date": "2007-10-25",
            "person_type": "legal",
            "street": "Rua Romualdo de Souza Brito",
            "neighborhood": "Centro",
            "number": "89",
            "postal_code": "08150-470",
            "city": "São Paulo",
            "state": "SP",
            "complement": "Letra C",
            "signer_group_list": [
                {
                    "signer_group_key": "ccb36b0b-40b5-42e0-bc41-0e8fce57f3ca",
                    "minimum_required_signers": 1,
                    "signers": [
                        {
                            "name": "John Doe",
                            "email": "123.456.789-00@yopmail.com",
                            "phone_number": "+5516982399722",
                            "document_number": "123.456.789-00",
                            "is_group_mandatory": true
                        }
                    ]
                }
            ],
            "document_list": [],
            "contact_information_list": [
                {
                    "name": "John Doe",
                    "email": "123.456.789-00@yopmail.com",
                    "is_default": true,
                    "phone_number": "+5511988887777",
                    "document_number": "123.456.789-00",
                    "investor_contact_information_key": "26299c0f-2127-45d4-b22e-f2b494d2f7ae"
                }
            ]
        }
    ],
    "collateral_list": [
        {
            "collateral_key": "d8fdb578-1e2a-4b79-8267-5b1763e56754",
            "collateral_type": "fiduciary_alienation_property"
        }
    ],
    "metadata_list": [
        {
            "metadata_key": "convenio",
            "metadata_value": "12398129038"
        }
    ],
}
```

### **Response Body Params**

| Campo                        | Tipo   | Descrição                                           |
| ---------------------------- | ------ | ----------------------------------------------------- |
| `tenant_key` *             | string | Chave única do tenant.                               |
| `operation_key` *          | string | Chave única da operação.                           |
| `operation_status` *       | string | Status da operação.                                 |
| `issuer_key` *             | string | Chave única do emissor.                              |
| `issuer_name` *            | string | Nome do emissor.                                      |
| `issuer_document_number` * | string | Documento do emissor.                                 |
| `financial` *              | object | **[Objeto financial](#objeto-financial-response)** |

### Objeto financial response

| Campo                        | Tipo    | Descrição                                                | Caracteres Máx.                                                       |
| ---------------------------- | ------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- |
| `financial_base_date` *    | string  | Data base financeira da operação (formato "YYYY-MM-DD"). | -                                                                      |
| `issue_amount` *           | number  | Valor total emitido da operação.                         | -                                                                      |
| `released_amount` *        | number  | Valor líquido liberado na operação.                     | -                                                                      |
| `issue_quantity` *         | integer | Quantidade total de unidades emitidas.                     | -                                                                      |
| `unit_price` *             | number  | Preço unitário da emissão.                              | -                                                                      |
| `cet` *                    | number  | Custo Efetivo Total (CET) em percentual.                   | -                                                                      |
| `annual_cet` *             | number  | CET anual em percentual.                                   | -                                                                      |
| `number_of_installments` * | integer | Número total de parcelas.                                 | -                                                                      |
| `prefixed_interest_rate` * | object  | Objeto contendo detalhes da taxa de juros prefixada.       | **[Objeto prefixed_interest_rate](#objeto-prefixed_interest_rate)** |
| `fees`                     | array   | Lista de taxas associadas à operação.                   | **[Objeto fees](#objeto-fees)**                                     |
| `installments`             | array   | Lista de detalhes das parcelas geradas na operação.      | **[Objeto installments](#objeto-installments)**                     |
| `fine_delay_rate` *        | object  | Objeto contendo detalhes da multa por atraso.              | **[Objeto fine_delay_rate](#objeto-fine_delay_rate)**               |
| `contract_fine_rate` *     | number  | Multa contratual aplicada em percentual.                   | -                                                                      |

### Objeto prefixed_interest_rate

| Campo               | Tipo   | Descrição                     | Caracteres Máx.                                                 |
| ------------------- | ------ | ------------------------------- | ---------------------------------------------------------------- |
| `interest_base` * | string | Base de cálculo para os juros. | **[Enumeradores interest_base](#enumeradores-interest_base)** |
| `monthly_rate` *  | number | Taxa de juros mensal aplicada.  | -                                                                |
| `daily_rate` *    | number | Taxa de juros diária aplicada. | -                                                                |
| `annual_rate` *   | number | Taxa de juros anual aplicada.   | -                                                                |

### Objeto fees

| Campo             | Tipo   | Descrição                              | Caracteres Máx.                                                 |
| ----------------- | ------ | ---------------------------------------- | ---------------------------------------------------------------- |
| `amount` *      | number | Valor percentual da taxa.                | -                                                                |
| `fee_amount` *  | number | Valor monetário correspondente à taxa. | -                                                                |
| `amount_type` * | string | Tipo do valor da taxa.                   | **[Enumeradores amount_type](#enumeradores-amount_type)**     |
| `fee_type` *    | string | Tipo da taxa.                            | **[Enumeradores fee_type](#enumeradores-fee_type)**           |
| `type` *        | string | Destinatário da taxa.                   | **[Enumeradores fee_recipient](#enumeradores-fee_recipient)** |

### Objeto installments

| Campo                                   | Tipo    | Descrição                                           |
| --------------------------------------- | ------- | ----------------------------------------------------- |
| `installment_number` *                | integer | Número da parcela.                                   |
| `workdays` *                          | integer | Dias úteis até o vencimento da parcela.             |
| `calendar_days` *                     | integer | Dias corridos até o vencimento da parcela.           |
| `principal_amortization_amount` *     | number  | Valor amortizado do principal.                        |
| `principal_amortization_unit_price` * | number  | Valor amortizado por unidade.                         |
| `interest_amount` *                   | number  | Valor dos juros aplicados na parcela.                 |
| `amount` *                            | number  | Valor total da parcela.                               |
| `due_date` *                          | string  | Data de vencimento da parcela (formato "YYYY-MM-DD"). |

---

# Atualização do método de assinatura na Operação

URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/atualizar-metodo-assinatura

Este endpoint permite a atualização do método de assinatura em uma operação.

---

## **Atualização do método de assinatura na Operação (PUT)**

### **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /signature_method
MÉTODO PUT

### **Path Params**

| Campo             | Tipo   | Descrição                                     | Caracteres Máx. |
|-------------------|--------|-----------------------------------------------|-----------------|
| `OPERATION-KEY` * | string | Chave única da operação (UUID v4).             | 36              |

Request Body

```json
{
    "signature_method": "qi_sign"
}
```

### Request Body Params

| Campo                        | Tipo     | Descrição                                                                                                                       | Caracteres Máx. |
|------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------|
| `signature_method` *            | string   | Tipo de sistema de assinatura. | certifiqi ou qi_sign |

## **Response**

STATUS 200

Response Body

```json
{
    "tenant_key": "13a6a1d5-7a3c-4627-a0a6-9fd746662ca4",
    "operation_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74",
    "operation_type": "commercial_paper",
    "operation_status": "issued",
    "backoffice_analysis_status": "approved",
    "issuer_key": "9e08fd62-ce43-4c95-99e0-4386e980d618",
    "issuer_name": "Blue Logic",
    "issuer_document_number": "97.923.586/0001-06",
    "issuer_bank_account": {
        "account_type": "checking",
        "account_digit": "3",
        "account_branch": "0001",
        "account_number": "4464541",
        "financial_institution_ispb": "32402502",
        "financial_institution_code_number": "329"
    },
    "issuer_onboarding_approved": true,
    "issue_number": 1,
    "issue_series": 1,
    "contract_number": "0000000001",
    "issue_date": "2025-02-03",
    "financial_base_date": "2025-02-03",
    "commercial_paper_template_key": "68956441-d46c-44ed-93b9-b1806dd6ada9",
    "commercial_paper_document_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/commercial_paper/2cb87abc-8bdf-4df3-be98-b7afb53b14c8",
    "adhesion_term_template_key": "58743ab9-99bd-439a-93af-16e4c5fccd6f",
    "adhesion_term_document_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/adhesion_term/fe74eaed-2f44-45b4-b972-83fa222cbf1c",
    "envelope_signature_status": "signed",
    "envelope_key": "4d7f28b4-185f-482d-929e-d1af937cb27b",
    "envelope_signature_url": "https://sandbox.certifiqi.com.br/sign?batch-group=c4747fe6-2cc0-41a9-8972-84b44f8fff8a",
    "envelope_signed_files_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/signed_files",
    "financial": {
        "financial_base_date": "2025-02-03",
        "issue_quantity": 1000000,
        "unit_price": 1.0,
        "issue_amount": 1000000.0,
        "released_amount": 1000000.0,
        "cet": 5.0,
        "annual_cet": 79.59,
        "number_of_installments": 5,
        "prefixed_interest_rate": {
            "daily_rate": 0.0016053474,
            "annual_rate": 0.795856326,
            "monthly_rate": 0.05,
            "interest_base": "calendar_days_365"
        },
        "fine_delay_rate": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days_365"
        },
        "contract_fine_rate": 0.02,
        "financial_index": null,
        "post_fixed_interest_rate": null,
        "fees": [
            {
                "type": "internal",
                "amount": 2.0,
                "fee_type": "bookkeeping_fee",
                "fee_amount": 20000.0,
                "amount_type": "percentage"
            },
            {
                "type": "external",
                "amount": 5.0,
                "fee_type": "structuring_fee",
                "fee_amount": 50000.0,
                "amount_type": "percentage"
            }
        ],
        "installment_list": [
            {
                "installment_number": 1,
                "workdays": 20,
                "calendar_days": 30,
                "principal_amortization_unit_price": 0.18122484,
                "principal_amortization_amount": 181224.84138231,
                "interest_amount": 49298.45861769,
                "amount": 230523.3,
                "due_principal": 1000000.0,
                "due_interest": 0.0,
                "due_date": "2025-03-05",
                "has_interest": true
            },
            {
                "installment_number": 2,
                "workdays": 21,
                "calendar_days": 29,
                "principal_amortization_unit_price": 0.19153595,
                "principal_amortization_amount": 191535.95353305,
                "interest_amount": 38987.34646695,
                "amount": 230523.3,
                "due_principal": 818775.15861769,
                "due_interest": 0.0,
                "due_date": "2025-04-03",
                "has_interest": true
            },
            {
                "installment_number": 3,
                "workdays": 19,
                "calendar_days": 32,
                "principal_amortization_unit_price": 0.19748652,
                "principal_amortization_amount": 197486.52331007,
                "interest_amount": 33036.77668993,
                "amount": 230523.3,
                "due_principal": 627239.20508464,
                "due_interest": 0.0,
                "due_date": "2025-05-05",
                "has_interest": true
            },
            {
                "installment_number": 4,
                "workdays": 21,
                "calendar_days": 29,
                "principal_amortization_unit_price": 0.21005991,
                "principal_amortization_amount": 210059.90840452,
                "interest_amount": 20463.39159548,
                "amount": 230523.3,
                "due_principal": 429752.68177457,
                "due_interest": 0.0,
                "due_date": "2025-06-03",
                "has_interest": true
            },
            {
                "installment_number": 5,
                "workdays": 21,
                "calendar_days": 30,
                "principal_amortization_unit_price": 0.21969277,
                "principal_amortization_amount": 219692.77337005,
                "interest_amount": 10830.52662995,
                "amount": 230523.3,
                "due_principal": 219692.77337005,
                "due_interest": 0.0,
                "due_date": "2025-07-03",
                "has_interest": true
            }
        ]
    },
    "tags": [],
    "investor_list": [
        {
            "investor_key": "a1a75b66-6f7e-4bcc-9ff5-6f8adf7cae09",
            "investor_name": "Ultimate Cascade",
            "investor_document_number": "31.424.651/0001-32",
            "subscription_percentage": 100.0,
            "subscription_quantity": 1000000,
            "investor_onboarding_approved": true,
            "bank_account": {
                "account_type": "checking",
                "account_digit": "3",
                "account_branch": "0001",
                "account_number": "33400254",
                "financial_institution_ispb": "32402502",
                "financial_institution_code_number": "329"
            },
            "updated_at": null
        }
    ],
    "related_party_list": [
        {
            "related_party_key": "1ac83d43-41cb-4ad0-a7ca-add6c3a3171c",
            "name": "Blue Logic",
            "document_number": "97.923.586/0001-06",
            "role_type": "issuer",
            "is_active": true,
            "updated_at": null,
            "trading_name": "Blue Logic",
            "cnae_code": "47.21-1-02",
            "company_type": "ltda",
            "foundation_date": "2007-10-25",
            "person_type": "legal",
            "street": "Rua Romualdo de Souza Brito",
            "neighborhood": "Centro",
            "number": "89",
            "postal_code": "08150-470",
            "city": "São Paulo",
            "state": "SP",
            "complement": "Letra C",
            "signer_group_list": [
                {
                    "signer_group_key": "fa2cbede-a501-41e1-bf70-078bb0d4ac7b",
                    "minimum_required_signers": 1,
                    "signers": [
                        {
                            "name": "John Doe",
                            "email": "123.456.789-00@yopmail.com",
                            "phone_number": "+5511988887777",
                            "document_number": "123.456.789-00",
                            "is_group_mandatory": true
                        }
                    ]
                }
            ],
            "document_list": [],
            "contact_information_list": [
                {
                    "name": "John Doe",
                    "email": "123.456.789-00@yopmail.com",
                    "is_default": true,
                    "phone_number": "+5516982399722",
                    "document_number": "123.456.789-00",
                    "issuer_contact_information_key": "6e9714f4-d652-4ca0-89e2-13e9e2ec3414"
                }
            ]
        },
        {
            "related_party_key": "bab03c76-a12a-4d88-aaf8-70799e3b1b30",
            "name": "Ultimate Cascade",
            "document_number": "31.424.651/0001-32",
            "role_type": "investor",
            "is_active": true,
            "updated_at": null,
            "trading_name": "Ultimate Cascade",
            "cnae_code": "47.21-1-02",
            "company_type": "ltda",
            "foundation_date": "2007-10-25",
            "person_type": "legal",
            "street": "Rua Romualdo de Souza Brito",
            "neighborhood": "Centro",
            "number": "89",
            "postal_code": "08150-470",
            "city": "São Paulo",
            "state": "SP",
            "complement": "Letra C",
            "signer_group_list": [
                {
                    "signer_group_key": "ccb36b0b-40b5-42e0-bc41-0e8fce57f3ca",
                    "minimum_required_signers": 1,
                    "signers": [
                        {
                            "name": "John Doe",
                            "email": "123.456.789-00@yopmail.com",
                            "phone_number": "+5516982399722",
                            "document_number": "123.456.789-00",
                            "is_group_mandatory": true
                        }
                    ]
                }
            ],
            "document_list": [],
            "contact_information_list": [
                {
                    "name": "John Doe",
                    "email": "123.456.789-00@yopmail.com",
                    "is_default": true,
                    "phone_number": "+5511988887777",
                    "document_number": "123.456.789-00",
                    "investor_contact_information_key": "26299c0f-2127-45d4-b22e-f2b494d2f7ae"
                }
            ]
        }
    ],
    "collateral_list": [
        {
            "collateral_key": "d8fdb578-1e2a-4b79-8267-5b1763e56754",
            "collateral_type": "fiduciary_alienation_property"
        }
    ],
    "metadata_list": [
        {
            "metadata_key": "convenio",
            "metadata_value": "12398129038"
        }
    ],
    "signature_method": "qi_sign"
}
```

### **Response Body Params**

| Campo                        | Tipo   | Descrição                                           |
| ---------------------------- | ------ | ----------------------------------------------------- |
| `tenant_key` *             | string | Chave única do tenant.                               |
| `operation_key` *          | string | Chave única da operação.                           |
| `operation_status` *       | string | Status da operação.                                 |
| `issuer_key` *             | string | Chave única do emissor.                              |
| `issuer_name` *            | string | Nome do emissor.                                      |
| `issuer_document_number` * | string | Documento do emissor.                                 |
| `financial` *              | object | **[Objeto financial](#objeto-financial-response)** |

### Objeto financial response

| Campo                        | Tipo    | Descrição                                                | Caracteres Máx.                                                       |
| ---------------------------- | ------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- |
| `financial_base_date` *    | string  | Data base financeira da operação (formato "YYYY-MM-DD"). | -                                                                      |
| `issue_amount` *           | number  | Valor total emitido da operação.                         | -                                                                      |
| `released_amount` *        | number  | Valor líquido liberado na operação.                     | -                                                                      |
| `issue_quantity` *         | integer | Quantidade total de unidades emitidas.                     | -                                                                      |
| `unit_price` *             | number  | Preço unitário da emissão.                              | -                                                                      |
| `cet` *                    | number  | Custo Efetivo Total (CET) em percentual.                   | -                                                                      |
| `annual_cet` *             | number  | CET anual em percentual.                                   | -                                                                      |
| `number_of_installments` * | integer | Número total de parcelas.                                 | -                                                                      |
| `prefixed_interest_rate` * | object  | Objeto contendo detalhes da taxa de juros prefixada.       | **[Objeto prefixed_interest_rate](#objeto-prefixed_interest_rate)** |
| `fees`                     | array   | Lista de taxas associadas à operação.                   | **[Objeto fees](#objeto-fees)**                                     |
| `installments`             | array   | Lista de detalhes das parcelas geradas na operação.      | **[Objeto installments](#objeto-installments)**                     |
| `fine_delay_rate` *        | object  | Objeto contendo detalhes da multa por atraso.              | **[Objeto fine_delay_rate](#objeto-fine_delay_rate)**               |
| `contract_fine_rate` *     | number  | Multa contratual aplicada em percentual.                   | -                                                                      |

### Objeto prefixed_interest_rate

| Campo               | Tipo   | Descrição                     | Caracteres Máx.                                                 |
| ------------------- | ------ | ------------------------------- | ---------------------------------------------------------------- |
| `interest_base` * | string | Base de cálculo para os juros. | **[Enumeradores interest_base](#enumeradores-interest_base)** |
| `monthly_rate` *  | number | Taxa de juros mensal aplicada.  | -                                                                |
| `daily_rate` *    | number | Taxa de juros diária aplicada. | -                                                                |
| `annual_rate` *   | number | Taxa de juros anual aplicada.   | -                                                                |

### Objeto fees

| Campo             | Tipo   | Descrição                              | Caracteres Máx.                                                 |
| ----------------- | ------ | ---------------------------------------- | ---------------------------------------------------------------- |
| `amount` *      | number | Valor percentual da taxa.                | -                                                                |
| `fee_amount` *  | number | Valor monetário correspondente à taxa. | -                                                                |
| `amount_type` * | string | Tipo do valor da taxa.                   | **[Enumeradores amount_type](#enumeradores-amount_type)**     |
| `fee_type` *    | string | Tipo da taxa.                            | **[Enumeradores fee_type](#enumeradores-fee_type)**           |
| `type` *        | string | Destinatário da taxa.                   | **[Enumeradores fee_recipient](#enumeradores-fee_recipient)** |

### Objeto installments

| Campo                                   | Tipo    | Descrição                                           |
| --------------------------------------- | ------- | ----------------------------------------------------- |
| `installment_number` *                | integer | Número da parcela.                                   |
| `workdays` *                          | integer | Dias úteis até o vencimento da parcela.             |
| `calendar_days` *                     | integer | Dias corridos até o vencimento da parcela.           |
| `principal_amortization_amount` *     | number  | Valor amortizado do principal.                        |
| `principal_amortization_unit_price` * | number  | Valor amortizado por unidade.                         |
| `interest_amount` *                   | number  | Valor dos juros aplicados na parcela.                 |
| `amount` *                            | number  | Valor total da parcela.                               |
| `due_date` *                          | string  | Data de vencimento da parcela (formato "YYYY-MM-DD"). |

---

# Envio de Garantia na Operação

URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/cadastro-garantia

Este conjunto de endpoints permite a **adição de garantias** associadas a uma operação. O **collateral será submetido para assinatura junto com os documentos da operação**. Cada tipo de garantia contém as suas regras de documentos necessários e todos os tipos de garantias estão contemplados aqui nesta documentação.

---

## **Envio de Garantia (POST)**

## **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /collateral
MÉTODO POST

### **Path Params**

| Campo            | Tipo   | Descrição                                     | Caracteres Máx. |
|------------------|--------|-----------------------------------------------|-----------------|
| `OPERATION-KEY` *  | string | Chave única da operação (UUID v4).             | 36              |

---

O sistema de garantias possibilita a adição de diferentes tipos de instrumentos, cada um com sua própria configuração de documentos adicionais. Nesta sessão, tratamos todos os modelos de garantia disponíveis e seus respectivos payloads.

### **Tipos de Garantias**

**[1 - Alienação fiduciária de imóvel](#alienação-fiduciária-de-imóvel)** 

**[2 - Alienação fiduciária de veículo](#alienação-fiduciária-de-veículo)** 

**[3 - Alienação fiduciária de aeronave](#alienação-fiduciária-de-aeronave)** 

**[4 - Alienação fiduciária de equipamentos/produtos/Estoque](#alienação-fiduciária-de-equipamentos-produtos-e-estoque)** 

**[5 - Alienação fiduciária de obras de arte](#alienação-fiduciária-de-obras-de-arte)** 

**[6 - Alienação fiduciária de títulos e valores mobiliários](#alienação-fiduciária-de-títulos-e-valores-mobiliários)**

**[7 - Alienação fiduciária de Ações e Cotas](#alienação-fiduciária-de-ações-e-cotas)** 

**[8 - Alienação fiduciária de diretos creditórios](#alienação-fiduciária-de-direitos-creditórios)** 

**[9 - Hipoteca de imóveis](#hipoteca-de-imóveis)** 

**[10 - Hipoteca de embarcações](#hipoteca-de-embarcações)** 

**[11 - Aval](#aval)** 

**[12 - Fiador](#fiador)** 

**[13 - Fiança Bancária](#fiança-bancária)** 

**[14 - Recebiveis de cartão](#recebiveis-de-cartão)** 

**[15 - Garantia de estoque](#garantia-de-estoque)** 

**[16 - Monitoramento de garantias](#monitoramento-de-garantias)** 

**[17 - Garantia de estoque de veículos (Floor Plan)](#garantia-de-estoque-de-veículos-floor-plan)**

**[18 - Outras garantias](#outras-garantias)** 

## **Alienação fiduciária de imóvel**

Request Body

```json
{
    "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b",
    "collateral_type": "fiduciary_alienation_property",
    "additional_documents": [
        {
            "document_type": "property_appraisal_report",
            "document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff"
        },
        {
            "document_type": "property_registration_updated",
            "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
        },
        {
            "document_type": "property_full_content_certificate",
            "document_key": "210c38b5-6b61-4b74-b042-19ebef77e360"
        },
        {
            "document_type": "property_insurance_policy",
            "document_key": "4cc6d706-551f-4d5e-8539-1b59b2f96cff"
        }
    ]
}
```

### **Tipos de Documentos**

| Enum             | Descrição                           |
|-----------------|-----------------------------------|
| `property_appraisal_report`**      | Laudo de Avaliação do Imóvel.             |
| `property_registration_updated`**      | Matrícula atualizada.             |
| `property_full_content_certificate`**      |  Certidão de Inteiro Teor da Matrícula.            |
| `property_insurance_policy`      | Apólice de Seguros (se exigível no contrato).             |
| `others`      | Outros documentos.             |

:::warning
(**) Obrigatório para alienação fiduciária de imóvel
:::

## **Alienação fiduciária de veículo**

Request Body

```json
{
    "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
    "collateral_type": "fiduciary_alienation_vehicle",
    "additional_documents": [
        {
            "document_type": "vehicle_appraisal_report",
            "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
        },
        {
            "document_type": "vehicle_inspection_report",
            "document_key": "210c38b5-6b61-4b74-b042-19ebef77e360"
        },
        {
            "document_type": "vehicle_crv_certificate",
            "document_key": "4cc6d706-551f-4d5e-8539-1b59b2f96cff"
        }
    ]
}
```

### **Tipos de Documentos**

| Enum             | Descrição                           |
|-----------------|-----------------------------------|
| `vehicle_appraisal_report`**      | Laudo de Avaliação do Veículo (defasagem máxima de 30 dias) ou Tabela FIPE.             |
| `vehicle_inspection_report`**      | Laudo vistoria.             |
| `vehicle_crv_certificate`**      |  Certificado de Registro de Veículo (CRLV) Atualizado.            |
| `others`      | Outros documentos.             |

:::warning
(**) Obrigatório para alienação fiduciária de veículo
:::

## **Alienação fiduciária de aeronave**

Request Body

```json
{
    "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
    "collateral_type": "fiduciary_alienation_aircraft",
    "additional_documents": [
        {
            "document_type": "aircraft_certificate_anac",
            "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
        },
        {
            "document_type": "aircraft_rab_consult",
            "document_key": "210c38b5-6b61-4b74-b042-19ebef77e360"
        },
        {
            "document_type": "aircraft_insurance_policy",
            "document_key": "4cc6d706-551f-4d5e-8539-1b59b2f96cff"
        },
        {
            "document_type": "aircraft_appraisal_report",
            "document_key": "df608f78-5293-4f96-ab60-31185633b52c"
        }
    ]
}
```

### **Tipos de Documentos**

| Enum             | Descrição                           |
|-----------------|-----------------------------------|
| `aircraft_certificate_anac`**      | Certificado de Matrícula - ANAC.             |
| `aircraft_rab_consult`**      | Consulta de Aeronave no Registro Aeronáutico Brasileiro.             |
| `aircraft_insurance_policy`**      |  Apólice de Seguro - Beneficiário o Fundo.            |
| `aircraft_appraisal_report`**      |  Laudo de Avaliação de Aeronave.            |
| `others`      | Outros documentos.             |

:::warning
(**) Obrigatório para alienação fiduciária de aeronave
:::

## **Alienação fiduciária de equipamentos produtos e estoque**

Request Body

```json
{
    "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
    "collateral_type": "fiduciary_alienation_equipment",
    "additional_documents": [
        {
            "document_type": "equipment_purchase_invoice",
            "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
        },
        {
            "document_type": "fiduciary_depositary_declaration",
            "document_key": "210c38b5-6b61-4b74-b042-19ebef77e360"
        },
        {
            "document_type": "equipment_appraisal_report",
            "document_key": "4cc6d706-551f-4d5e-8539-1b59b2f96cff"
        },
        {
            "document_type": "equipment_insurance_policy",
            "document_key": "df608f78-5293-4f96-ab60-31185633b52c"
        }
    ]
}
```

### **Tipos de Documentos**

| Enum             | Descrição                           |
|-----------------|-----------------------------------|
| `equipment_purchase_invoice`**      | Nota Fiscal - Registro de Compra.             |
| `equipment_appraisal_report`**      | Laudo de Avaliação de Equipamentos (defasagem máxima de 30 dias).             |
| `equipment_insurance_policy`      |  Apólice de Seguro de Equipamentos (se exigível no contrato).            |
| `fiduciary_depositary_declaration`      |  Declaração de Fiel Depositário.            |
| `others`      | Outros documentos.             |

:::warning
(**) Obrigatório para alienação fiduciária de equipamentos/produto/estoque
:::

## **Alienação fiduciária de obras de arte**

Request Body

```json
{
    "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
    "collateral_type": "fiduciary_alienation_artwork",
    "additional_documents": [
        {
            "document_type": "artwork_appraisal_report",
            "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
        },
        {
            "document_type": "artwork_storage_certificate",
            "document_key": "210c38b5-6b61-4b74-b042-19ebef77e360"
        }
    ]
}
```

### **Tipos de Documentos**

| Enum             | Descrição                           |
|-----------------|-----------------------------------|
| `artwork_appraisal_report`**      | Laudo de avaliação de Obras de Arte.             |
| `artwork_storage_certificate`**      | Local de Armazenamento com Certificado de Adequação.             |
| `artwork_insurance_policy`      |  Apólice de Seguro (se exigível no contrato).            |
| `others`      | Outros documentos.             |

:::warning
(**) Obrigatório para alienação fiduciária de obras de arte
:::

## **Alienação fiduciária de títulos e valores mobiliários**

Request Body

```json
{
    "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
    "collateral_type": "fiduciary_alienation_securities",
    "additional_documents": [
        {
            "document_type": "securities_negotiation_block",
            "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
        }
    ]
}
```

### **Tipos de Documentos**

| Enum             | Descrição                           |
|-----------------|-----------------------------------|
| `securities_negotiation_block`**      | Bloqueio para Negociação junto ao Custodiante.             |
| `securities_registration_gravame`      | Local de Armazenamento com Certificado de Adequação.             |
| `others`      | Outros documentos.             |

:::warning
(**) Obrigatório para alienação fiduciária de títulos valores mobiliários.
:::

## **Alienação fiduciária de Ações e Cotas**

Request Body

```json
{
    "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
    "collateral_type": "fiduciary_assignment_shares",
    "additional_documents": [
        {
            "document_type": "share_registration_book",
            "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
        }
    ]
}
```

### **Tipos de Documentos**

| Enum             | Descrição                           |
|-----------------|-----------------------------------|
| `share_registration_book`**      | Livro de Registro de Ações Nominativas com Anotação do Gravame.             |
| `others`      | Outros documentos.             |

:::warning
(**) Obrigatório para alienação fiduciária/Penhor de Ações/Cotas
:::

## **Alienação fiduciária de diretos creditórios**

Request Body

```json
{
    "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
    "collateral_type": "fiduciary_assignment_shares",
}
```

### **Tipos de Documentos**

| Enum             | Descrição                           |
|-----------------|-----------------------------------|
| `others`      | Outros documentos.             |

## **Hipoteca de imóveis**

Request Body

```json
{
    "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
    "collateral_type": "mortgage_property",
    "additional_documents": [
        {
            "document_type": "property_appraisal_report",
            "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
        },
        {
            "document_type": "property_registration",
            "document_key": "210c38b5-6b61-4b74-b042-19ebef77e360"
        },
        {
            "document_type": "property_insurance_policy",
            "document_key": "4cc6d706-551f-4d5e-8539-1b59b2f96cff"
        },
        {
            "document_type": "property_full_content_certificate",
            "document_key": "df608f78-5293-4f96-ab60-31185633b52c"
        }
    ]
}
```

### **Tipos de Documentos**

| Enum             | Descrição                           |
|-----------------|-----------------------------------|
| `property_appraisal_report`**      | Laudo de Avaliação de Imóvel.             |
| `property_registration`**      | Registro de Propriedade Atualizado.             |
| `property_full_content_certificate`**      | Certidão de Inteiro Teor da Matrícula.             |
| `property_insurance_policy`      | Apólice de Seguros (se exigível no contrato).             |
| `others`      | Outros documentos.             |

:::warning
(**) Obrigatório para Hipoteca de imóveis.
:::

## **Hipoteca de Embarcações**

Request Body

```json
{
    "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
    "collateral_type": "mortgage_ship",
    "additional_documents": [
        {
            "document_type": "ship_registration",
            "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
        },
        {
            "document_type": "ship_appraisal_report",
            "document_key": "210c38b5-6b61-4b74-b042-19ebef77e360"
        },
        {
            "document_type": "ship_insurance_policy",
            "document_key": "4cc6d706-551f-4d5e-8539-1b59b2f96cff"
        }
    ]
}
```

### **Tipos de Documentos**

| Enum             | Descrição                           |
|-----------------|-----------------------------------|
| `ship_registration`**      | Registro de Propriedade de Embarcação Atualizado.             |
| `ship_appraisal_report`**      | Laudo de Avaliação de Embarcação (defasagem máxima de 3 meses).             |
| `ship_insurance_policy`      | Apólice de Seguros de embarcação (se exigível no contrato).            |
| `others`      | Outros documentos.             |

:::warning
(**) Obrigatório para Hipoteca de embarcações.
:::

## **Aval**

Request Body

```json
{
    "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
    "collateral_type": "guarantor",
    "additional_documents": [
        {
            "document_type": "guarantor_civil_status_declaration",
            "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
        },
        {
            "document_type": "guarantor_personal_document",
            "document_key": "210c38b5-6b61-4b74-b042-19ebef77e360"
        }
    ]
}
```

### **Tipos de Documentos**

| Enum             | Descrição                           |
|-----------------|-----------------------------------|
| `guarantor_civil_status_declaration`**      | Declaração de Estado Civil do Avalista.             |
| `guarantor_personal_document`**      | Documento pessoal do Avalista.             |
| `guarantor_income_tax_declaration`      | Declaração de Imposto de Renda do Avalista.            |
| `others`      | Outros documentos.             |

:::warning
(**) Obrigatório para Aval.
:::

## **Fiador**

Request Body

```json
{
    "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
    "collateral_type": "surety",
    "additional_documents": [
        {
            "document_type": "surety_civil_status_declaration",
            "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
        },
        {
            "document_type": "surety_personal_document",
            "document_key": "210c38b5-6b61-4b74-b042-19ebef77e360"
        },
        {
            "document_type": "surety_income_tax_declaration",
            "document_key": "4cc6d706-551f-4d5e-8539-1b59b2f96cff"
        }
    ]
}
```

### **Tipos de Documentos**

| Enum             | Descrição                           |
|-----------------|-----------------------------------|
| `surety_civil_status_declaration`**      | Declaração de Estado Civil do Fiador.             |
| `surety_personal_document`**      | Documento pessoal do Fiador.             |
| `surety_income_tax_declaration`      | Declaração de Imposto de Renda do Fiador.            |
| `others`      | Outros documentos.             |

:::warning
(**) Obrigatório para Fiador.
:::

## **Fiança Bancária**

Request Body

```json
{
    "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
    "collateral_type": "bank_surety",
    "additional_documents": [
        {
            "document_type": "others",
            "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
        }
    ]
}
```

### **Tipos de Documentos**

| Enum             | Descrição                           |
|-----------------|-----------------------------------|
| `others`      | Outros documentos.             |

## **Recebiveis de cartão**

Request Body

```json
{
    "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
    "collateral_type": "card_receivables",
    "additional_documents": [
        {
            "document_type": "others",
            "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
        }
    ]
}
```

### **Tipos de Documentos**

| Enum             | Descrição                           |
|-----------------|-----------------------------------|
| `others`      | Outros documentos.             |

## **Garantia de estoque**

Request Body

```json
{
    "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
    "collateral_type": "stock_guarantee",
    "additional_documents": [
        {
            "document_type": "others",
            "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
        }
    ]
}
```

### **Tipos de Documentos**

| Enum             | Descrição                           |
|-----------------|-----------------------------------|
| `others`      | Outros documentos.             |

## **Monitoramento de garantias**

Request Body

```json
{
    "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
    "collateral_type": "monitoring_guarantee",
    "additional_documents": [
        {
            "document_type": "guarantee_contract",
            "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
        },
        {
            "document_type": "guarantee_agent_contract",
            "document_key": "210c38b5-6b61-4b74-b042-19ebef77e360"
        }
    ]
}
```

### **Tipos de Documentos**

| Enum             | Descrição                           |
|-----------------|-----------------------------------|
| `guarantee_contract`**      | Contrato de Garantia.             |
| `guarantee_agent_contract`**      | Contrato de agente de Garantia.             |
| `others`      | Outros documentos.             |

:::warning
(**) Obrigatório para Monitoramento de Garantias.`
:::

## **Garantia de estoque de veículos (Floor Plan)**

Modelo de garantia utilizado em operações de **Floor Plan**, no qual o emissor disponibiliza um estoque de veículos como garantia da operação. Diferente dos demais tipos, este modelo **não utiliza `collateral_document_key` nem `additional_documents`** — a garantia é composta por uma lista de veículos, enviada no campo `vehicles`.

Ao ser cadastrada, cada veículo da lista é **consultado** (não gravado) junto à base de estoque da B3 (Geero). O cadastro segue a regra **tudo ou nada**: se qualquer veículo da lista já estiver gravado (ou a consulta falhar), a garantia inteira é rejeitada e nenhum veículo é persistido.

Request Body

```json
{
    "collateral_type": "vehicle_stock",
    "vehicles": [
        {
            "chassis": "9BWZZZ377VT004251",
            "plate": "ABC1D23",
            "plate_state": "SP",
            "renavam": "12345678901"
        },
        {
            "chassis": "9BWZZZ377VT004252"
        }
    ]
}
```

### **vehicles list**

| Campo               | Tipo   | Descrição                                                                                                    | Obrigatório |
|----------------------|--------|----------------------------------------------------------------------------------------------------------------|-------------|
| `chassis` *          | string | Chassi do veículo. 17 caracteres alfanuméricos maiúsculos.                                                     | Sim         |
| `plate`              | string | Placa do veículo, no padrão Mercosul ou antigo.                                                                | Não**       |
| `plate_state`        | string | UF de emplacamento do veículo (sigla).                                                                         | Não**       |
| `renavam`            | string | RENAVAM do veículo. 9 a 11 dígitos numéricos.                                                                  | Não**       |

:::warning
(**) `plate`, `plate_state` e `renavam` formam um grupo **tudo ou nada**: o veículo deve enviar os três campos juntos (veículo emplacado/usado) ou nenhum dos três (veículo 0km, ainda sem emplacamento). O envio de apenas parte do grupo é rejeitado com erro de validação (400).
:::

### **Status de gravação por veículo (`marking_status`)**

Cada veículo dentro do collateral carrega um `marking_status`, retornado através dos endpoints de consulta de operação/garantia:

| Status                     | Descrição                                                                                                                    |
|-----------------------------|-------------------------------------------------------------------------------------------------------------------------------|
| `pending_signature`         | Estado inicial. Nenhuma tentativa de gravação foi feita ainda — a garantia foi apenas consultada e aceita no cadastro.       |
| `ineligible_for_marking`    | Na re-consulta feita imediatamente antes da gravação (aprovação do compliance, antes do envio para assinatura), o veículo foi encontrado já gravado/indisponível. |
| `marked`                    | O veículo foi gravado com sucesso junto à B3 (Geero). O campo `reserved_at` é preenchido com a data/hora da gravação.        |
| `unmarked`                  | O veículo havia sido gravado com sucesso, mas foi desfeito (rollback) porque outro veículo do mesmo lote falhou na gravação. |
| `marking_failed`            | A tentativa de gravação deste veículo falhou — é o veículo que disparou o cancelamento/rollback do lote.                     |

### **Fluxo de gravação**

- **No cadastro (`in_filling`):** cada veículo é apenas **consultado**. Se algum já estiver gravado, a garantia inteira é rejeitada — nada é persistido.
- **Na aprovação do compliance (transição para `pending_signature_submission`, imediatamente antes do envio para assinatura):** **todos** os veículos de **todas** as garantias `vehicle_stock` ativas da operação são re-consultados em uma única varredura. Se qualquer veículo estiver inelegível, nenhum veículo do lote é gravado, a operação é cancelada e um alerta é disparado.
- Se a re-consulta passar para todos, cada veículo é gravado junto à B3 (Geero). Se a gravação de um veículo falhar, todos os veículos já gravados no mesmo lote são desfeitos (`unmarked`) e a operação é cancelada.

## **Outras garantias**

Request Body

```json
{
    "collateral_document_key": "a14e8b2c-bda7-4f3d-aebb-ae63822428ff",
    "collateral_type": "others",
    "additional_documents": [
        {
            "document_type": "others",
            "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04"
        }
    ]
}
```

### **Tipos de Documentos**

| Enum             | Descrição                           |
|-----------------|-----------------------------------|
| `others`      | Outros documentos.             |

---
## **Request Body Params**

| Campo                         | Tipo     | Descrição                                                        | Obrigatório |
|--------------------------------|----------|------------------------------------------------------------------|-------------|
| `collateral_document_key` * | string   | Chave do instrumento de Garantia.       | Sim         |
| `collateral_type` *            | string   | Tipo do collateral. | **[Enumeradores collateral_type](#enumeradores-collateral_type)** |
| `collateral_data`           | object   | Estrutura de metadados relacionados ao collateral.               | Sim         |
| `additional_documents` | list   | Documentos relacionados ao collateral. | - |

### **additional_documents list**

| Campo                         | Tipo     | Descrição                                                        | Obrigatório |
|--------------------------------|----------|------------------------------------------------------------------|-------------|
| `document_key` * | string   | Chave do instrumento de Garantia.       | Sim         |
| `document_type` *            | string   | Tipo do documento da Garantia. | Sim |

### **Enumeradores collateral_type**

| Enum             | Descrição                           |
|-----------------|-----------------------------------|
| `fiduciary_alienation_property`      | Alienação fiduciária de imóvel.             |
| `fiduciary_alienation_vehicle`      |  Alienação fiduciária de veículo.            |
| `fiduciary_alienation_aircraft`      | Alienação fiduciária de aeronave.             |
| `fiduciary_alienation_equipment`      | Alienação fiduciária de equipamentos/produtos/Estoque.             |
| `fiduciary_alienation_artwork`      | Alienação fiduciária de obras de arte.             |
| `fiduciary_alienation_securities`      | Alienação fiduciária de títulos e valores mobiliários.             |
| `fiduciary_assignment_shares`      | Alienação fiduciária/Penhor de Ações/Cotas.             |
| `fiduciary_assignment_credit_rights`      | Alienação fiduciária de diretos creditórios.             |
| `mortgage_property`      | Hipoteca de imóveis.             |
| `mortgage_ship`      | Hipoteca de embarcações.             |
| `guarantor`      | Aval.             |
| `surety`      | Fiador.             |
| `bank_surety`      | Fiança Bancária.             |
| `card_receivables`      | Recebiveis de cartão.             |
| `stock_guarantee`      | Garantia de estoque.             |
| `monitoring_guarantee`      | Monitoramento de garantias.             |
| `vehicle_stock`      | Garantia de estoque de veículos (Floor Plan). Não utiliza `collateral_document_key`/`additional_documents` — veja [Garantia de estoque de veículos (Floor Plan)](#garantia-de-estoque-de-veículos-floor-plan). |
| `others`      | Outras garantias.             |

---

# Remoção de Garantia na Operação

URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/remover-garantia

Este endpoint permite a **remoção de garantias** associadas a uma operação.

---

## **Remoção de Collateral (DELETE)**

## **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /collateral/ COLLATERAL-KEY
MÉTODO DELETE

### **Path Params**

| Campo            | Tipo   | Descrição                                       | Caracteres Máx. |
|------------------|--------|-----------------------------------------------|-----------------|
| `OPERATION-KEY` * | string | Chave única da operação (UUID v4).           | 36              |
| `COLLATERAL-KEY` * | string | Chave única do collateral a ser removido (UUID v4). | 36              |

## **Response**
STATUS 204

**Nenhum conteúdo é retornado no corpo da resposta.**

---

# Envio de documentos

URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/upload-documento

Este endpoint permite o envio de **documentos** associados a uma operação. Tais documentos podem ser utilizados no sistema de garantias para realizar a adição de documentos acessórios, além do instrumento da garantia em si.

---

## **Envio de Documento (POST)**

## **Request**
ENDPOINT /commercial_paper/upload
MÉTODO POST

Request Body

```json
{
  "document_base64": "sringb64",
}
```

### **Request Body Params**

| Campo                         | Tipo     | Descrição                                                        | Obrigatório |
|--------------------------------|----------|------------------------------------------------------------------|-------------|
| `document_base64` * | string   | Conteúdo do documento codificado em Base64.       | Sim         |

## **Response**
STATUS 201

Response Body

```json
{
  "document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b"
}
```

## **Response Body Params**

| Campo            | Tipo     | Descrição                                      | Caracteres Máx. |
|------------------|----------|----------------------------------------------|-----------------|
| `document_key` * | string   | Chave única do documento adicionado (UUID v4). | 36              |
---

---

# Cadastro e Remoção de Metadata na Operação

URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-metadata-identificacao

Este conjunto de endpoints permite o cadastro e a remoção de metadados em uma operação.

---

## **Cadastro de Metadata na Operação (POST)**

### **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /metadata
MÉTODO POST

### **Path Params**

| Campo             | Tipo   | Descrição                                     | Caracteres Máx. |
|-------------------|--------|-----------------------------------------------|-----------------|
| `OPERATION-KEY` * | string | Chave única da operação (UUID v4).             | 36              |

Request Body

```json
{
  "metadata_key": "custom_meta_field",
  "metadata_value": "custom_meta_value"
}
```

### **Request Body Params**

| Campo            | Tipo     | Descrição                            | Caracteres Máx. |
|------------------|----------|--------------------------------------|-----------------|
| `metadata_key` *   | string | Chave do metadado.                   | 255             |
| `metadata_value` * | string | Valor do metadado.                   | 1023            |

### **Response**
STATUS 201

Response Body

```json
{
  "metadata_key": "custom_meta_field",
  "metadata_value": "custom_meta_value"
}
```

### **Response Body Params**

| Campo            | Tipo     | Descrição                            | Caracteres Máx. |
|------------------|----------|--------------------------------------|-----------------|
| `metadata_key` *   | string | Chave do metadado.                   | 255             |
| `metadata_value` * | string | Valor do metadado.                   | 1023            |

---

## **Remoção de Metadata na Operação (DELETE)**

### **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /metadata
MÉTODO DELETE

### **Path Params**

| Campo            | Tipo   | Descrição                                     | Caracteres Máx. |
|------------------|--------|-----------------------------------------------|-----------------|
| `OPERATION-KEY` *  | string | Chave única da operação (UUID v4).             | 36              |

Request Body

```json
{
  "metadata_key": "custom_meta_field",
  "metadata_value": "custom_meta_value"
}
```

### **Request Body Params**

| Campo            | Tipo     | Descrição                            | Caracteres Máx. |
|------------------|----------|--------------------------------------|-----------------|
| `metadata_key` *   | string | Chave do metadado.                   | 255             |
| `metadata_value` * | string | Valor do metadado.                   | 1023            |

---

### **Response**
STATUS 204

**Nenhum conteúdo é retornado no corpo da resposta.**

---

# Envio e Remoção de Documentos de Representantes de Partes Relacionadas

URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-documento

Este conjunto de endpoints permite o envio e a remoção de documentos associados a representantes de partes relacionadas a uma operação.

---

## **Envio de Documento do Representante (POST)**

### **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party/ RELATED-PARTY-KEY /document
MÉTODO POST

### **Path Params**

| Campo               | Tipo   | Descrição                                      | Caracteres Máx. |
|---------------------|--------|----------------------------------------------|-----------------|
| `OPERATION-KEY` *     | string | Chave única da operação (UUID v4).          | 36              |
| `RELATED-PARTY-KEY` * | string | Chave única da parte relacionada (UUID v4). | 36              |

Request Body

```json
{
  "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0",
  "document_type": "cnh"
}
```

### **Request Body Params**

| Campo             | Tipo     | Descrição                                                       | Caracteres Máx. |
|------------------|----------|-----------------------------------------------------------------|-----------------|
| `document_base64` * | string   | Conteúdo do arquivo do documento codificado em Base64.         | -               |
| `document_type` *  | string   | Tipo do documento enviado. | **[Enumeradores document_type](#enumeradores-document_type)** |

## **Response**
STATUS 201

Response Body

**Cenário 1: Validação Automática (Sucesso no OCR)**

```json
{
  "document_key": "123e4567-e89b-12d3-a456-426614174000",
  "document_type": "cnh",
  "ocr_key": "6654f284-f690-4324-8c39-dcf0225ec8cf"
}
```
**Significado**: O documento foi processado e validado automaticamente pelo nosso OCR.

**Cenário 2: Verificação Manual Necessária**

```json
{
    "document_key": "8bf591a8-c184-47db-afd2-a5196de14cc3",
    "document_type": "cnh",
    "ocr_key": null
}
```
**Significado**: O documento não pôde ser validado automaticamente pelo OCR e foi encaminhado para nossa fila de verificação manual.

:::warning Atenção
A resposta para requisições bem-sucedidas (sucesso no envio) apresenta dois comportamentos distintos, dependendo do resultado da validação automática (OCR).
:::
### **Response Body Params**

| Campo            | Tipo     | Descrição                                      | Caracteres Máx. |
|------------------|----------|----------------------------------------------|-----------------|
| `document_key` * | string   | Identificador único do documento enviado.   | 36              |
| `document_type` * | string   | Tipo do documento enviado. | **[Enumeradores document_type](#enumeradores-document_type)** |
| `ocr_key`        | string   | Chave OCR associada ao documento enviado.   | 36              |

---

## **Remoção de Documento do Representante (DELETE)**

### **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party/ RELATED-PARTY-KEY /document/ DOCUMENT-KEY
MÉTODO DELETE

### **Path Params**

| Campo               | Tipo   | Descrição                                      | Caracteres Máx. |
|---------------------|--------|----------------------------------------------|-----------------|
| `OPERATION-KEY` *     | string | Chave única da operação (UUID v4).          | 36              |
| `RELATED-PARTY-KEY` * | string | Chave única da parte relacionada (UUID v4). | 36              |
| `DOCUMENT-KEY` *      | string | Chave única do documento a ser removido.   | 36              |

### **Response**
STATUS 204

**Nenhum conteúdo é retornado no corpo da resposta.**

### **Enumeradores document_type**

| Enum                      | Descrição                               |
|---------------------------|-----------------------------------------|
| `proof_of_address`        | Comprovante de Endereço.                |
| `letter_of_attorney`      | Procuração.                             |
| `company_statute`         | Estatuto da Empresa.                    |
| `cnh`                     | Carteira Nacional de Habilitação (CNH). |
| `cnh_front`               | Frente da CNH.                          |
| `cnh_back`                | Verso da CNH.                           |
| `cnh_digital`             | CNH Digital.                            |
| `rg_front`                | Frente do RG.                           |
| `rg_back`                 | Verso do RG.                            |

---

# Envio e Remoção de Grupos de Assinantes de Representantes de Partes Relacionadas

URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-grupo-assinantes

Este conjunto de endpoints permite o envio e a remoção de grupos de assinantes associados a representantes de partes relacionadas a uma operação.

---

## **Envio de Grupo de Assinantes (POST)**

### **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party/ RELATED-PARTY-KEY /signer_group
MÉTODO POST

### **Path Params**

| Campo                 | Tipo   | Descrição                                      | Caracteres Máx. |
|-----------------------|--------|----------------------------------------------|-----------------|
| `OPERATION-KEY` *     | string | Chave única da operação (UUID v4).           | 36              |
| `RELATED-PARTY-KEY` * | string | Chave única da parte relacionada (UUID v4). | 36              |

Request Body

```json
{
  "minimum_required_signers": 2,
  "signers": [
    {
      "name": "João da Silva",
      "document_number": "12345678901",
      "email": "joao.silva@example.com",
      "phone_number": "+5511999999999",
      "is_group_mandatory": true
    },
    {
      "name": "Maria Souza",
      "document_number": "98765432100",
      "email": "maria.souza@example.com",
      "phone_number": "+5511988888888",
      "is_group_mandatory": false
    }
  ]
}
```

### **Request Body Params**

| Campo                        | Tipo     | Descrição                                              | Caracteres Máx. |
|------------------------------|----------|--------------------------------------------------------|-----------------|
| `minimum_required_signers` * | integer  | Número mínimo de assinantes necessários no grupo.     | -               |
| `signers` *                  | array    | Lista de assinantes do grupo.                         | **[Objeto signers](#objeto-signers)** |

---

### **Objeto signers**

| Campo                    | Tipo     | Descrição                                         | Caracteres Máx. |
|--------------------------|----------|-------------------------------------------------|-----------------|
| `name` *                | string   | Nome completo do assinante.                     | 255             |
| `document_number` *      | string   | CPF do assinante (11 dígitos).                  | 11              |
| `email` *               | string   | Endereço de e-mail do assinante.                | 1023            |
| `phone_number` *        | string   | Número de telefone do assinante, incluindo DDI. | 20              |
| `is_group_mandatory` *  | boolean  | Indica se o assinante é obrigatório.            | -               |

## **Response**
STATUS 201

Response Body

```json
{
  "signer_group_key": "123e4567-e89b-12d3-a456-426614174000",
  "minimum_required_signers": 2,
  "signers": [
    {
      "name": "João da Silva",
      "document_number": "12345678901",
      "email": "joao.silva@example.com",
      "phone_number": "+5511999999999",
      "is_group_mandatory": true
    },
    {
      "name": "Maria Souza",
      "document_number": "98765432100",
      "email": "maria.souza@example.com",
      "phone_number": "+5511988888888",
      "is_group_mandatory": false
    }
  ]
}
```

### **Response Body Params**

| Campo                        | Tipo     | Descrição                                         | Caracteres Máx. |
|------------------------------|----------|-------------------------------------------------|-----------------|
| `signer_group_key` *         | string   | Chave única do grupo de assinantes (UUID v4).   | 36              |
| `minimum_required_signers` * | integer  | Número mínimo de assinantes no grupo.           | -               |
| `signers` *                  | array    | Lista de assinantes do grupo.                   | **[Objeto signers](#objeto-signers)** |

---

## **Remoção de Grupo de Assinantes (DELETE)**

### **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party/ RELATED-PARTY-KEY /signer_group/ SIGNER-GROUP-KEY
MÉTODO DELETE

### **Path Params**

| Campo                 | Tipo   | Descrição                                      | Caracteres Máx. |
|-----------------------|--------|----------------------------------------------|-----------------|
| `OPERATION-KEY` *     | string | Chave única da operação (UUID v4).           | 36              |
| `RELATED-PARTY-KEY` * | string | Chave única da parte relacionada (UUID v4). | 36              |
| `SIGNER-GROUP-KEY` *  | string | Chave única do grupo de assinantes.         | 36              |

### **Response**
STATUS 204

**Nenhum conteúdo é retornado no corpo da resposta.**

---

# Cadastro e Remoção de Partes Relacionadas de um documento específico

URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-parte-relacionada-em-documento

Este conjunto de endpoints permite o cadastro e a remoção de partes relacionadas a uma operação de um documento específico da operação.

---

## **Adicionar Parte Relacionada ao documento (POST)**

### **Request**

ENDPOINT /commercial_paper/operation/ OPERATION-KEY /formalization_document /FORMALIZATION-DOCUMENT-KEY /related_party
MÉTODO POST

### **Path Params**

| Campo               | Tipo   | Descrição                           | Caracteres Máx. |
| ------------------- | ------ | ------------------------------------- | ---------------- |
| `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36               |
| `FORMALIZATION-DOCUMENT-KEY` * | string | Chave única do documento da operação (UUID v4). | 36               |

Request Body

```json
{
  "related_party_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e"
}
```

### **Request Body Params**

| Campo                 | Tipo   | Descrição                                                            | Caracteres Máx.                                             |
| --------------------- | ------ | ---------------------------------------------------------------------- | ------------------------------------------------------------ |
| `related_party_key` *     | string | Chave da Parte Relacionada |                                       | 36

## **Response**

STATUS 204

**Nenhum conteúdo é retornado no corpo da resposta.**

## **Remoção de Parte Relacionada (DELETE)**

### **Request**

ENDPOINT /commercial_paper/operation/ OPERATION-KEY /formalization_document/ FORMALIZATION-DOCUMENT-KEY /related_party
MÉTODO DELETE

### **Path Params**

| Campo                   | Tipo   | Descrição                           | Caracteres Máx. |
| ----------------------- | ------ | ------------------------------------- | ---------------- |
| `OPERATION-KEY` *     | string | Chave única da operação (UUID v4). | 36               |
| `FORMALIZATION-DOCUMENT-KEY` * | string | Chave única do documento da da operação (UUID v4).    | 36               |

Request Body

```json
{
  "related_party_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e"
}
```

### **Response**

STATUS 204

**Nenhum conteúdo é retornado no corpo da resposta.**

---

# Cadastro e Remoção de Partes Relacionadas

URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/cadastrar-parte-relacionada

Este conjunto de endpoints permite o cadastro e a remoção de partes relacionadas a uma operação.

:::warning
Todas as partes relacionadas são adicionadas por padrão ao Termo Constitutivo (**commercial_paper**), caso deseje adicionar essa parte relacionada à um documento específico, preencher o campo **related_document_key** com a chave do documento desejado.
:::

---

## **Cadastro de Parte Relacionada (POST)**

### **Request**

ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party
MÉTODO POST

### **Path Params**

| Campo               | Tipo   | Descrição                           | Caracteres Máx. |
| ------------------- | ------ | ------------------------------------- | ---------------- |
| `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36               |

:::info Importante
**Atenção ao tipo de pessoa ao montar o payload:**
- **Pessoa Física (PF)**: `"person_type": "natural"`
- **Pessoa Jurídica (PJ)**: `"person_type": "legal"`
:::

Request Body - Pessoa Física (PF)

```json
{
  "person_type": "natural",
  "name": "João da Silva",
  "document_number": "123.731.320-10",
  "street": "Rua dos Exemplos",
  "neighborhood": "Centro",
  "number": "123",
  "postal_code": "29173-509",
  "city": "São Paulo",
  "state": "SP",
  "role_type": "guarantor",
  "marital_status": "single",
  "birthdate": "2000-01-01",
  "mother_name": "Mãe do João",
  "father_name": "Pai do João",
  "occupation": "Desenvolvedor",
  "is_pep": false
}
```

Request Body - Pessoa Jurídica (PJ)

  ```json
  {
    "person_type": "legal",
    "name": "João da Silva",
    "trading_name": "Padaria do João LTDA",
    "document_number": "92.123.456/0001-00",
    "street": "Rua dos Exemplo",
    "neighborhood": "Centro",
    "number": "123",
    "postal_code": "01001-000",
    "city": "São Paulo",
    "state": "SP",
    "role_type": "guarantor",
    "cnae_code": "12.34-5-67",
    "company_type": "ltda",
    "foundation_date": "2025-01-01"
  }
  ```

### **Request Body Params**

| Campo                 | Tipo   | Descrição                                                            | Caracteres Máx.                                             |
| --------------------- | ------ | ---------------------------------------------------------------------- | ------------------------------------------------------------ |
| `person_type` *     | string | Tipo da pessoa.                                                        | **[Enumeradores person_type](#enumeradores-person_type)** |
| `name` *            | string | Nome da parte relacionada.                                             | 255                                                          |
| `document_number` * | string | CPF (formato "XXX.XXX.XXX-XX") ou CNPJ (formato "XX.XXX.XXX/XXXX-XX"). | 14                                                           |
| `street` *          | string | Logradouro do endereço.                                               | 500                                                          |
| `neighborhood`      | string | Bairro do endereço.                                                   | 100                                                          |
| `number` *          | string | Número do endereço.                                                  | 10                                                           |
| `postal_code` *     | string | CEP do endereço (formato "XXXXX-XXX").                                | 8                                                            |
| `city` *            | string | Cidade do endereço.                                                   | 255                                                          |
| `state` *           | string | Sigla do estado (2 caracteres).                                        | 2                                                            |
| `role_type` *       | string | Papel da parte relacionada.                                            | **[Enumeradores role_type](#enumeradores-role_type)**     |
| `related_document_key`        | string | Chave de identificação do documento (UUIDv4)                | 36

### **Enumeradores person_type**

| Enum        | Descrição      |
| ----------- | ---------------- |
| `natural` | Pessoa Física   |
| `legal`   | Pessoa Jurídica |

### **Campos adicionais para Pessoa Física**

| Campo                              | Tipo    | Descrição                                                              | Caracteres Máx.                                                     |
| ---------------------------------- | ------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------- |
| `document_identification_number` | string  | RG (sem formatação)                                                    | 20                                                                   |
| `marital_status`                 | string  | Estado civil.                                                            | **[Enumeradores marital_status](#enumeradores-marital_status)**   |
| `property_system`                | string  | Regime de bens.                                                          | **[Enumeradores property_system](#enumeradores-property_system)** |
| `birthdate`                      | string  | Data de nascimento (YYYY-MM-DD).                                         | -                                                                    |
| `nationality`                    | string  | Nacionalidade.                                                           | 255                                                                  |
| `mother_name`                    | string  | Nome da mãe.                                                            | 255                                                                  |
| `father_name`                    | string  | Nome do pai.                                                             | 255                                                                  |
| `occupation`                     | string  | Ocupação.                                                              | 255                                                                  |
| `is_pep` *                       | boolean | Indica se a parte relacionada é uma Pessoa Politicamente Exposta (PEP). |                                                                      |

### **Campos adicionais para Pessoa Jurídica**

| Campo                 | Tipo   | Descrição                            | Caracteres Máx.                                               |
| --------------------- | ------ | -------------------------------------- | -------------------------------------------------------------- |
| `trading_name` *    | string | Nome fantasia da empresa.              | 1023                                                           |
| `cnae_code` *       | string | Código CNAE da empresa (10 dígitos). | 10                                                             |
| `company_type` *    | string | Tipo da empresa.                       | **[Enumeradores company_type](#enumeradores-company_type)** |
| `foundation_date` * | string | Data de fundação (YYYY-MM-DD).       | -                                                              |

### **Enumeradores role_type**

| Enum                       | Descrição              |
| -------------------------- | ------------------------ |
| `cosigner`               | Avalista                 |
| `fiduciary_debtor`       | Devedor Fiduciário      |
| `solidary_debtor`        | Devedor Solidário       |
| `surety`                 | Garantidor               |
| `guarantor`              | Fiador                   |
| `bonafide_depositary`    | Fiel Depositário        |
| `intervening_guarantor`  | Interveniente Fiador     |
| `intervening_consentor`  | Interveniente Anuente    |
| `intervening_discharger` | Interveniente Quitante   |
| `assignor`               | Cedente                  |
| `endorser`               | Endossante               |
| `consulting`             | Consultor                |
| `fund_administrator`     | Administrador do Fundo   |
| `fund_representative`    | Representante do Fundo   |
| `company_representative` | Representante da Empresa |
| `attestant`              | Testemunha               |
| `debtor`                 | Devedor                  |
| `bestowal`               | Outorga Uxória          |
| `manager`                | Gestor                   |

### Enumeradores marital_status

| Enum        | Descrição      |
| ----------- | ---------------- |
| `single`    | Solteiro(a)     |
| `married`   | Casado(a)       |
| `divorced`  | Divorciado(a)   |
| `widowed`   | Viúvo(a)        |
| `separated` | Separado(a)     |
| `stable_union`| União estável |

### Enumeradores property_system

| Enum                              | Descrição                              |
| --------------------------------- | -------------------------------------- |
| `total_communion_of_goods`        | Comunhão Total de Bens                |
| `partial_communion_of_goods`      | Comunhão Parcial de Bens              |
| `total_separation_of_goods`       | Separação Total de Bens               |
| `final_participation_of_acquisitions` | Participação Final nos Aquestos    |
| `compulsory_separation_of_goods`  | Separação Obrigatória de Bens         |

### Enumeradores company_type

| Enum                | Descrição                    |
| ------------------- | ---------------------------- |
| `ltda`             | Sociedade Limitada           |
| `sa`               | Sociedade Anônima            |
| `cop` | Cooperativa                 |

## **Response**

STATUS 201

Response Body

```json
{
	"related_party_key": "c642a117-ea6e-4da7-a8fd-451f556e5c38",
	"name": "João da Silva",
	"document_number": "12345678901",
	"role_type": "guarantor",
	"is_active": true,
	"updated_at": null,
	"person_type": "natural",
	"street": "Rua dos Exemplo",
	"neighborhood": "Centro",
	"number": "123",
	"postal_code": "01001000",
	"city": "São Paulo",
	"state": "SP",
	"signer_group_list": [],
	"document_list": [],
	"contact_information_list": []
}
```

### **Response Body Params**

| Campo                   | Tipo    | Descrição                                          | Caracteres Máx.                                             |
| ----------------------- | ------- | ---------------------------------------------------- | ------------------------------------------------------------ |
| `related_party_key` * | string  | Chave única da parte relacionada.                   | 36                                                           |
| `name` *              | string  | Nome da parte relacionada.                           | 255                                                          |
| `document_number` *   | string  | CPF/CNPJ da parte relacionada.                       | 14                                                           |
| `role_type` *         | string  | Papel da parte relacionada.                          | 50                                                           |
| `is_active` *         | boolean | Indica se está ativa.                               | -                                                            |
| `updated_at`          | string  | Data da última atualização (YYYY-MM-DD HH:mm:ss). | -                                                            |
| `person_type` *       | string  | Tipo da pessoa.                                      | **[Enumeradores person_type](#enumeradores-person_type)** |
| `street` *            | string  | Logradouro.                                          | 500                                                          |
| `neighborhood`        | string  | Bairro.                                              | 100                                                          |
| `number` *            | string  | Número.                                             | 10                                                           |
| `postal_code` *       | string  | CEP (somente números).                              | 8                                                            |
| `city` *              | string  | Cidade.                                              | 255                                                          |
| `state` *             | string  | Sigla do estado (2 caracteres).                      | 2                                                            |

---

## **Remoção de Parte Relacionada (DELETE)**

### **Request**

ENDPOINT /commercial_paper/operation/ OPERATION-KEY /related_party/ RELATED-PARTY-KEY
MÉTODO DELETE

### **Path Params**

| Campo                   | Tipo   | Descrição                           | Caracteres Máx. |
| ----------------------- | ------ | ------------------------------------- | ---------------- |
| `OPERATION-KEY` *     | string | Chave única da operação (UUID v4). | 36               |
| `RELATED-PARTY-KEY` * | string | Chave única da parte relacionada.    | 36               |

### **Response**

STATUS 204

**Nenhum conteúdo é retornado no corpo da resposta.**

---

# Cadastro de Operação de Nota Comercial

URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/criar-operacao

Este endpoint permite criar uma nova operação de nota comercial com base nos dados financeiros e de investidores.

---

## **Request**

ENDPOINT /commercial_paper/operation
MÉTODO POST

Request Body

```json
{
    "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e",
    "issuer_bank_account": {
        "account_number": "4464541",
        "account_digit": "3",
        "account_branch": "0001",
        "financial_institution_code_number": "329",
        "financial_institution_ispb": "32402502",
        "account_type": "checking"
    },
    "investors": [
        {
            "investor_key": "70b1b638-ca56-4eb3-9a88-2fd5ffd077a7",
            "subscription_percentage": 100,
            "bank_account": {
                "account_number": "33400254",
                "account_digit": "3",
                "account_branch": "0001",
                "financial_institution_code_number": "329",
                "financial_institution_ispb": "32402502",
                "account_type": "checking"
            }
        }
    ],
    "issue_date": "2025-01-23",
    "signature_method": "certifiqi",
    "financial": {
        "interest_type": "pre_price_days",
        "financial_base_date": "2025-01-23",
        "released_amount": 1000000,
        "number_of_installments": 5,
        "prefixed_interest_rate": {
            "interest_base": "calendar_days_365",
            "monthly_rate": 0.05
        },
        "fine_delay_rate": {
            "interest_base": "calendar_days_365",
            "monthly_rate": 0.01
        },
        "contract_fine_rate": 0.02,
        "fees": [
            {
                "amount": 5,
                "amount_type": "percentage",
                "fee_type": "structuring_fee"
            }
        ]
    }
}
```

### **Request Body Params**

| Campo                     | Tipo   | Descrição                                            | Caracteres Máx.                                                 |
| ------------------------- | ------ | ------------------------------------------------------ | ---------------------------------------------------------------- |
| `issuer_key` *          | string | Chave única do emissor.                               | -                                                                |
| `issuer_bank_account` * | object | Conta bancária do emissor.                            | **[Objeto issuer_bank_account](#objeto-issuer_bank_account)** |
| `investors` *           | array  | Lista de investidores envolvidos.                      | **[Objeto investors](#objeto-investors)**                     |
| `issue_date` *          | string | Data de emissão da operação (formato "YYYY-MM-DD"). | -                                                                |
| `signature_method`      | string | Método de assinatura utilizado na operação. Opcional; quando omitido, assume `certifiqi`. | **[Enumeradores signature_method](#enumeradores-signature_method)** |
| `financial` *           | object | Dados financeiros da operação.                       | **[Objeto financial](#objeto-financial)**                     |
| `third_party_disbursement` | object | Instrução de desembolso para terceiro. Opcional; requer habilitação prévia. | **[Objeto third_party_disbursement](#objeto-third_party_disbursement)** |

### **Objeto issuer_bank_account**

| Campo                                   | Tipo   | Descrição                                |
| --------------------------------------- | ------ | ------------------------------------------ |
| `account_number` *                    | string | Número da conta bancária.                |
| `account_digit` *                     | string | Dígito da conta bancária.                |
| `account_branch` *                    | string | Agência da conta bancária.               |
| `financial_institution_code_number` * | string | Código da instituição financeira.       |
| `financial_institution_ispb` *        | string | Código ISPB da instituição financeira.  |
| `account_type` *                      | string | Tipo da conta (`checking`, `savings`). |

### **Objeto investors**

| Campo                         | Tipo   | Descrição                    |
| ----------------------------- | ------ | ------------------------------ |
| `investor_key` *            | string | Chave única do investidor.    |
| `subscription_percentage` * | number | Percentual de subscrição.    |
| `bank_account` *            | object | Conta bancária do investidor. |

### **Objeto financial**

| Campo                        | Tipo    | Descrição                                  |
| ---------------------------- | ------- | -------------------------------------------- |
| `interest_type` *          | string  | Tipo de juros.                               |
| `financial_base_date` *    | string  | Data base financeira (formato "YYYY-MM-DD"). |
| `released_amount`         | number  | Valor liberado.                              |
| `issue_amount`         | number  | Valor de Emissão.                              |
| `number_of_installments` * | integer | Número de parcelas.                         |
| `installments`  | array  | **[Objeto installments](#objeto-installments)**                     |
| `prefixed_interest_rate` * | object  | **[Objeto prefixed_interest_rate](#objeto-prefixed_interest_rate)**                     |
| `fine_delay_rate` *        | object  | Taxa de multa por atraso.                    |
| `contract_fine_rate` *     | number  | Multa contratual em percentual.              |
| `fees`                     | array   | Lista de taxas.                              |
:::warning Atenção
 O **objeto financial** deve conter uma combinação válida de parâmetros para ser processado. As combinações aceitas são: Valor de Emissão/Liberado + Taxa de Juros, Valor de Emissão/Liberado + Valor por Parcela, Valor por Parcela + Taxa de Juros, Valor de Emissão/Liberado + Taxa de Juros + Percentual de Amortização por Parcela.
:::
### Objeto installments

| Campo                        | Tipo     | Descrição                                                                                                                       |
|------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|
| `due_date` *            | string   | Data de vencimento da parcela (formato "YYYY-MM-DD"). |
| `amount`              | number   | Valor total da parcela.                                                                                                  |
| `principal_amortization_percentage`              | number   | Valor percentual amortizado do principal.                                                                                                  |

### Objeto prefixed_interest_rate

| Campo                        | Tipo     | Descrição                                                                                                                       |
|------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|
| `interest_base` *            | string   | Base de cálculo para os juros. | - |
| `daily_rate`              | number   | Taxa de juros diária aplicada.                                                                                                  | -               |
| `monthly_rate`              | number   | Taxa de juros mensal aplicada.                                                                                                  | -               |
| `annual_rate`              | number   | Taxa de juros anual aplicada.                                                                                                  | -               |

### **Objeto third_party_disbursement**

Instrução opcional que indica que o valor liberado será pago a um beneficiário terceiro, e não à conta de liquidação do emissor. O objeto não aceita campos além dos listados (`additionalProperties: false`) e as duas trilhas — TED e boleto — são mutuamente exclusivas.

| Campo               | Tipo   | Descrição                                                                                                  | Caracteres Máx.                                             |
| ------------------- | ------ | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ |
| `payment_method` * | string | Trilha de pagamento utilizada no desembolso (`ted`, `bank_slip`, `pix`).                                 | -                                                            |
| `target_account`   | object | Conta bancária do beneficiário. Obrigatório quando `payment_method` é `ted`; proibido nas demais trilhas. | **[Objeto target_account](#objeto-target_account)**       |
| `digitable_line`   | string | Linha digitável do boleto do beneficiário, somente dígitos (padrão `^[0-9]{47}$`). Obrigatório quando `payment_method` é `bank_slip`; proibido nas demais trilhas. | 47 |
| `pix_key`          | string | Chave Pix do beneficiário, **sem formatação** para CPF e CNPJ. Obrigatório quando `payment_method` é `pix`; proibido nas demais trilhas. | 77 |
| `pix_key_type`     | string | Tipo declarado da chave Pix (`cpf`, `cnpj`, `phone`, `email`, `evp`). Obrigatório quando `payment_method` é `pix`; proibido nas demais trilhas. | - |
| `beneficiary`      | object | Qualificação do terceiro beneficiário. **Obrigatório** quando `payment_method` é `pix`; opcional em `ted` e `bank_slip`. | **[Desembolso para terceiro](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/desembolso-terceiro)** |

:::info Recurso sob habilitação
O envio de `third_party_disbursement` requer habilitação prévia junto à QI Tech; sem ela a criação é recusada com `COM000062`. As regras completas — incluindo a conferência do valor do boleto, os tipos de chave Pix e os campos do objeto `beneficiary` — estão em [Desembolso para terceiro na operação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/desembolso-terceiro).
:::

### **Objeto target_account**

| Campo                                   | Tipo             | Descrição                                                                                                    | Caracteres Máx. |
| --------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------- | --------------- |
| `account_branch` *                    | string           | Agência da conta bancária do beneficiário, somente dígitos (exatamente 4).                                 | 4               |
| `account_number` *                    | string           | Número da conta bancária do beneficiário, somente dígitos (1 a 20).                                        | 20              |
| `account_digit` *                     | string           | Dígito da conta bancária do beneficiário, somente dígitos (exatamente 1).                                  | 1               |
| `financial_institution_ispb` *        | string           | Código ISPB da instituição financeira do beneficiário, somente dígitos (exatamente 8). Define o roteamento da TED. | 8         |
| `financial_institution_code_number`   | string ou `null` | Código da instituição financeira do beneficiário, somente dígitos (3). Opcional e não utilizado no roteamento. | 3             |
| `account_type` *                      | string           | Tipo da conta do beneficiário (`checking`, `savings`, `salary`, `payment`).                            | -               |
| `owner_document_number` *             | string           | CPF ou CNPJ do titular da conta, **formatado** (`000.000.000-00` ou `00.000.000/0000-00`). Os dígitos verificadores são conferidos. | 18 |
| `owner_name` *                        | string           | Nome do titular da conta (1 a 50 caracteres).                                                                 | 50              |

### Enumeradores signature_method

| Valor         | Descrição                                                                                                                                                                                       |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `certifiqi` | Valor padrão. A operação é enviada ao serviço de assinatura; um envelope de assinatura é criado e o cliente recebe a URL de assinatura (`signature_url`).                                  |
| `qi_sign`   | A operação é enviada ao serviço de assinatura; um envelope de assinatura é criado e o cliente recebe a URL de assinatura (`signature_url`). Permite também a consulta dos signatários da operação. |
| `client_side` | Os documentos são assinados fora da plataforma da QI Tech e enviados pelo endpoint de **[envio de documentos assinados](/documentation/escrituracao/emissao-de-notas/envio-contratos-assinados)**. Nenhuma URL de assinatura é gerada. |

## **Response**

STATUS 201

Response Body

```json
{
    "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814",
    "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127",
    "operation_status": "in_filling",
    "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e",
    "issuer_name": "Dynamic Enterprises",
    "issuer_document_number": "28980395000155",
    "financial": {
        ...
    }
}
```

### **Response Body Params**

| Campo                        | Tipo   | Descrição                                           |
| ---------------------------- | ------ | ----------------------------------------------------- |
| `tenant_key` *             | string | Chave única do tenant.                               |
| `operation_key` *          | string | Chave única da operação.                           |
| `operation_status` *       | string | Status da operação.                                 |
| `issuer_key` *             | string | Chave única do emissor.                              |
| `issuer_name` *            | string | Nome do emissor.                                      |
| `issuer_document_number` * | string | Documento do emissor.                                 |
| `financial` *              | object | **[Objeto financial](#objeto-financial-response)** |

### Objeto financial response

| Campo                        | Tipo    | Descrição                                                | Caracteres Máx.                                                       |
| ---------------------------- | ------- | ---------------------------------------------------------- | ---------------------------------------------------------------------- |
| `financial_base_date` *    | string  | Data base financeira da operação (formato "YYYY-MM-DD"). | -                                                                      |
| `issue_amount` *           | number  | Valor total emitido da operação.                         | -                                                                      |
| `released_amount` *        | number  | Valor líquido liberado na operação.                     | -                                                                      |
| `issue_quantity` *         | integer | Quantidade total de unidades emitidas.                     | -                                                                      |
| `unit_price` *             | number  | Preço unitário da emissão.                              | -                                                                      |
| `cet` *                    | number  | Custo Efetivo Total (CET) em percentual.                   | -                                                                      |
| `annual_cet` *             | number  | CET anual em percentual.                                   | -                                                                      |
| `number_of_installments` * | integer | Número total de parcelas.                                 | -                                                                      |
| `prefixed_interest_rate` * | object  | Objeto contendo detalhes da taxa de juros prefixada.       | **[Objeto prefixed_interest_rate](#objeto-prefixed_interest_rate-response)** |
| `fees`                     | array   | Lista de taxas associadas à operação.                   | **[Objeto fees](#objeto-fees)**                                     |
| `installments`             | array   | Lista de detalhes das parcelas geradas na operação.      | **[Objeto installments](#objeto-installments-response)**                     |
| `fine_delay_rate` *        | object  | Objeto contendo detalhes da multa por atraso.              | **[Objeto fine_delay_rate](#objeto-fine_delay_rate)**               |
| `contract_fine_rate` *     | number  | Multa contratual aplicada em percentual.                   | -                                                                      |

### Objeto prefixed_interest_rate response

| Campo               | Tipo   | Descrição                     |
| ------------------- | ------ | ------------------------------- |
| `interest_base` * | string | Base de cálculo para os juros. |
| `monthly_rate`   | number | Taxa de juros mensal aplicada.  |
| `daily_rate`     | number | Taxa de juros diária aplicada. |
| `annual_rate`    | number | Taxa de juros anual aplicada.   |

### Objeto fees

| Campo             | Tipo   | Descrição                              |
| ----------------- | ------ | ---------------------------------------- |
| `amount` *      | number | Valor percentual da taxa.                |
| `fee_amount` *  | number | Valor monetário correspondente à taxa. |
| `amount_type` * | string | Tipo do valor da taxa.                   |
| `fee_type` *    | string | Tipo da taxa.                            |
| `type` *        | string | Destinatário da taxa.                   |

### Objeto installments response

| Campo                                   | Tipo    | Descrição                                           |
| --------------------------------------- | ------- | ----------------------------------------------------- |
| `installment_number` *                | integer | Número da parcela.                                   |
| `workdays` *                          | integer | Dias úteis até o vencimento da parcela.             |
| `calendar_days` *                     | integer | Dias corridos até o vencimento da parcela.           |
| `principal_amortization_amount` *     | number  | Valor amortizado do principal.                        |
| `principal_amortization_unit_price` * | number  | Valor amortizado por unidade.                         |
| `interest_amount` *                   | number  | Valor dos juros aplicados na parcela.                 |
| `amount` *                            | number  | Valor total da parcela.                               |
| `due_date` *                          | string  | Data de vencimento da parcela (formato "YYYY-MM-DD"). |

---

# Desembolso para terceiro na operação

URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/desembolso-terceiro

Este endpoint define ou substitui a instrução de desembolso para terceiro de uma operação, indicando que o valor liberado será pago a um beneficiário terceiro (por exemplo, um fornecedor) e não à conta de liquidação do emissor.

:::info Recurso sob habilitação
O desembolso para terceiro não vem habilitado por padrão. Solicite a habilitação à QI Tech antes de integrar — sem ela, a requisição é recusada com `COM000062`.
:::

:::warning Substituição integral e janela de alteração
A requisição **substitui a instrução inteira** — não há atualização parcial de campos. A instrução só pode ser definida ou alterada enquanto a operação está no status `in_filling`; fora desse status a requisição é recusada com `COM000010`.
:::

---

## **Desembolso para terceiro na operação (PUT)**

### **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /third_party_disbursement
MÉTODO PUT

### **Path Params**

| Campo             | Tipo   | Descrição                                     | Caracteres Máx. |
|-------------------|--------|-----------------------------------------------|-----------------|
| `OPERATION-KEY` * | string | Chave única da operação (UUID v4).             | 36              |

Request Body — TED

```json
{
    "payment_method": "ted",
    "target_account": {
        "account_branch": "0001",
        "account_number": "4464541",
        "account_digit": "3",
        "financial_institution_ispb": "32402502",
        "financial_institution_code_number": "329",
        "account_type": "checking",
        "owner_document_number": "11.222.333/0001-81",
        "owner_name": "Fornecedor Exemplo LTDA"
    }
}
```

Request Body — Boleto

```json
{
    "payment_method": "bank_slip",
    "digitable_line": "34191790010104351004791020150008291070100000000"
}
```

Request Body — Pix

```json
{
    "payment_method": "pix",
    "pix_key": "52998224725",
    "pix_key_type": "cpf",
    "beneficiary": {
        "person_type": "natural",
        "name": "João da Silva",
        "document_number": "529.982.247-25",
        "street": "Rua das Flores",
        "number": "100",
        "postal_code": "01234-567",
        "city": "São Paulo",
        "state": "SP",
        "is_pep": false
    }
}
```

### **Request Body Params**

O corpo não aceita campos além dos listados (`additionalProperties: false`). As três trilhas são mutuamente exclusivas e a exclusividade é garantida pelo schema: enviar o campo de uma trilha junto de outra, omitir o campo obrigatório da trilha escolhida ou enviar um campo desconhecido retorna `QIT000001`.

| Campo               | Tipo   | Descrição                                                                                                  | Caracteres Máx.                                             |
| ------------------- | ------ | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ |
| `payment_method` * | string | Trilha de pagamento utilizada no desembolso.                                                                 | **[Enumeradores payment_method](#enumeradores-payment_method)** |
| `target_account`   | object | Conta bancária do beneficiário. Obrigatório quando `payment_method` é `ted`; proibido nas demais trilhas. | **[Objeto target_account](#objeto-target_account)**       |
| `digitable_line`   | string | Linha digitável do boleto do beneficiário, somente dígitos (padrão `^[0-9]{47}$`). Obrigatório quando `payment_method` é `bank_slip`; proibido nas demais trilhas. | 47 |
| `pix_key`          | string | Chave Pix do beneficiário, **sem formatação** para CPF e CNPJ. Obrigatório quando `payment_method` é `pix`; proibido nas demais trilhas. | 77 |
| `pix_key_type`     | string | Tipo declarado da chave Pix. Obrigatório quando `payment_method` é `pix`; proibido nas demais trilhas. | **[Enumeradores pix_key_type](#enumeradores-pix_key_type)** |
| `beneficiary`      | object | Qualificação do terceiro beneficiário. **Obrigatório** quando `payment_method` é `pix`; opcional em `ted` e `bank_slip`. | **[Objeto beneficiary](#objeto-beneficiary)** |

### **Enumeradores payment_method**

| Valor         | Descrição                                                                    |
| ------------- | ------------------------------------------------------------------------------ |
| `ted`       | Pagamento por TED para a conta informada em `target_account`.                 |
| `bank_slip` | Pagamento do boleto informado em `digitable_line`.                           |
| `pix`       | Pagamento por Pix para a chave informada em `pix_key`.                        |

### **Enumeradores pix_key_type**

| Valor    | Descrição                                                      |
| -------- | ---------------------------------------------------------------- |
| `cpf`    | CPF, 11 dígitos, sem pontuação.                                |
| `cnpj`   | CNPJ, 14 dígitos, sem pontuação.                               |
| `phone`  | Telefone no formato `+55` seguido de 10 ou 11 dígitos.          |
| `email`  | Endereço de e-mail, até 77 caracteres.                          |
| `evp`    | Chave aleatória (UUID minúsculo).                               |

O **formato** da chave é validado pelo schema conforme o `pix_key_type` declarado — fora do formato, `QIT000001`. Para `cpf` e `cnpj`, os **dígitos verificadores** são conferidos depois: formato certo com dígito verificador errado retorna `COM000071`.

### **Objeto target_account**

| Campo                                   | Tipo             | Descrição                                                                                                    | Caracteres Máx.                                       |
| --------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| `account_branch` *                    | string           | Agência da conta bancária do beneficiário, somente dígitos (exatamente 4).                                 | 4                                                      |
| `account_number` *                    | string           | Número da conta bancária do beneficiário, somente dígitos (1 a 20).                                        | 20                                                     |
| `account_digit` *                     | string           | Dígito da conta bancária do beneficiário, somente dígitos (exatamente 1).                                  | 1                                                      |
| `financial_institution_ispb` *        | string           | Código ISPB da instituição financeira do beneficiário, somente dígitos (exatamente 8). Define o roteamento da TED. | 8                                              |
| `financial_institution_code_number`   | string ou `null` | Código da instituição financeira do beneficiário, somente dígitos (3). Opcional e não utilizado no roteamento. | 3                                                    |
| `account_type` *                      | string           | Tipo da conta do beneficiário.                                                                               | **[Enumeradores account_type](#enumeradores-account_type)** |
| `owner_document_number` *             | string           | CPF ou CNPJ do titular da conta, **formatado** (`000.000.000-00` ou `00.000.000/0000-00`). Os dígitos verificadores são conferidos. | 18                    |
| `owner_name` *                        | string           | Nome do titular da conta (1 a 50 caracteres).                                                                 | 50                                                     |

### **Enumeradores account_type**

| Valor        | Descrição            |
| ------------ | ---------------------- |
| `checking` | Conta corrente.        |
| `savings`  | Conta poupança.       |
| `salary`   | Conta salário.        |
| `payment`  | Conta de pagamento.    |

### **Objeto beneficiary**

Identifica o terceiro que recebe o valor. Obrigatório na trilha `pix` — uma chave Pix não diz quem é o recebedor — e opcional em `ted` e `bank_slip`. Viaja junto da instrução, é assinado com a operação e é usado na ata que formaliza o pagamento ao terceiro.

**Apenas `name` e `document_number` são obrigatórios.** Todos os demais campos são opcionais e servem para enriquecer a qualificação do beneficiário na ata.

| Campo | Tipo | Descrição | Obrigatório |
| ----- | ---- | ----------- | ----------- |
| `person_type` | string | `natural` (pessoa física) ou `legal` (pessoa jurídica). | Opcional |
| `name` * | string | Nome do beneficiário. | Sempre |
| `document_number` * | string | CPF ou CNPJ **formatado** (`000.000.000-00` ou `00.000.000/0000-00`). | Sempre |
| `street` | string | Logradouro. | Opcional |
| `number` | string | Número do endereço. | Opcional |
| `postal_code` | string | CEP no formato `00000-000`. | Opcional |
| `city` | string | Cidade. | Opcional |
| `state` | string | UF, duas letras maiúsculas. | Opcional |
| `is_pep` | boolean | Indica se é Pessoa Politicamente Exposta. | Opcional |
| `trading_name` | string | Nome fantasia. | Opcional |
| `cnae_code` | string | CNAE no formato `00.00-0-00`. | Opcional |
| `company_type` | string | Tipo de empresa. | Opcional |
| `foundation_date` | string | Data de fundação (`AAAA-MM-DD`). | Opcional |
| `neighborhood` | string | Bairro. | Opcional |
| `complement` | string | Complemento do endereço. | Opcional |
| `document_identification_number` | string | RG. | Opcional |
| `marital_status` | string | Estado civil. | Opcional |
| `property_system` | string | Regime de bens. | Opcional |
| `birthdate` | string | Data de nascimento (`AAAA-MM-DD`). | Opcional |
| `nationality` | string | Nacionalidade. | Opcional |
| `mother_name` | string | Nome da mãe. | Opcional |
| `father_name` | string | Nome do pai. | Opcional |
| `occupation` | string | Ocupação. | Opcional |

:::tip Quanto mais você enviar, mais completa fica a ata
Com `person_type`, a ata ganha a **qualificação** do beneficiário. Com `street`, `number`, `postal_code`, `city` e `state` — os cinco juntos —, ganha o **endereço** formatado. Enviando só nome e documento, a ata nomeia o beneficiário sem qualificar nem endereçar: nada falha, o documento apenas fica mais enxuto.
:::

:::warning TED — confira o ISPB
A instituição de destino da TED é determinada pelo `financial_institution_ispb`. Um ISPB incorreto envia o dinheiro para a instituição errada mesmo que o `financial_institution_code_number` esteja correto.
:::

:::warning Boleto — o valor precisa bater com o valor liberado
O valor do boleto é lido dos **10 últimos dígitos da linha digitável, em centavos**, e precisa ser igual ao `financial.released_amount` da operação. Qualquer diferença é recusada com `COM000061`.

Como o `released_amount` calculado difere do valor solicitado por causa das taxas, o caminho prático é: criar a operação, ler o `released_amount` da resposta e só então anexar um boleto daquele valor exato. **Não reescreva o valor de uma linha digitável real** — isso invalida seus dígitos verificadores e o boleto deixa de ser pagável.

Uma nota comercial paga exatamente um beneficiário, pelo valor integral: split de pagamento não é suportado.
:::

## **Response**

STATUS 200

A resposta traz o objeto completo da operação, na mesma forma retornada pela [consulta de operação por chave](/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-chave).

Response Body

```json
{
    "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814",
    "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127",
    "operation_type": "commercial_paper",
    "operation_status": "in_filling",
    "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e",
    "issuer_name": "Dynamic Enterprises",
    "issuer_document_number": "28.980.395/0001-55",
    "issuer_bank_account": {
        "account_type": "checking",
        "account_digit": "3",
        "account_branch": "0001",
        "account_number": "4464541",
        "financial_institution_ispb": "32402502",
        "financial_institution_code_number": "329"
    },
    "financial": {
        ...
    }
}
```

### **Response Body Params**

| Campo                        | Tipo   | Descrição                                           |
| ---------------------------- | ------ | ----------------------------------------------------- |
| `tenant_key` *             | string | Chave única do tenant.                               |
| `operation_key` *          | string | Chave única da operação.                           |
| `operation_status` *       | string | Status da operação.                                 |
| `issuer_key` *             | string | Chave única do emissor.                              |
| `issuer_name` *            | string | Nome do emissor.                                      |
| `issuer_document_number` * | string | Documento do emissor.                                 |
| `financial` *              | object | Dados financeiros da operação.                       |

:::info
A instrução aparece no objeto da operação como `third_party_disbursement`, na mesma forma em que foi
enviada. Quando a operação não tem desembolso para terceiro, a chave é **omitida** da resposta — não
retorna como `null`.
:::

---

## **Erros**

Os códigos abaixo estão descritos também no [catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros).

| Código     | HTTP | Descrição                                                                                              |
| ---------- | ---- | -------------------------------------------------------------------------------------------------------- |
| `QIT000001` | 400  | Falha de schema — por exemplo, `payment_method` ausente ou fora do enum, combinação inválida entre `target_account` e `digitable_line`, `digitable_line` fora do padrão de 47 dígitos, `pix_key` fora do formato do seu `pix_key_type`, ou campo desconhecido no corpo. |
| `COM000010` | 400  | Operação não pode ser atualizada fora do status `in_filling`.                                         |
| `COM000061` | 400  | Valor do boleto diferente do `released_amount` da operação.                                            |
| `COM000062` | 400  | Tenant não habilitado para desembolso a terceiro.                                                      |
| `COM000063` | 400  | Documento do beneficiário inválido.                                                                    |
| `COM000071` | 400  | `pix_key` de `cpf`/`cnpj` com dígito verificador inválido.                                             |
| `COM000007` | 404  | Operação não encontrada.                                                                               |
| `COM000008` | 403  | Operação não pertence ao tenant solicitante.                                                           |

---

# Campos Extras (Extra Fields)

URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/extra-fields

Este conjunto de endpoints permite consultar os campos extras disponíveis em um template de documento e salvar valores personalizados para esses campos em uma operação.

:::warning
Para utilizar os campos extras, é necessário que o template do documento já tenha sido definido. Caso contrário, gere uma pré-visualização de minuta antes de utilizar estes endpoints.
:::

:::info Importante
Os campos extras são organizados por tipo de documento (`document_type`). Ao salvar campos extras via POST, os valores anteriores para aquele `document_type` são **substituídos integralmente** — não é feito merge com valores existentes.
:::

---

## **Consulta de Campos Extras Disponíveis (GET)**

Retorna os campos extras disponíveis no template associado ao tipo de documento da operação.

### **Request**

ENDPOINT /commercial_paper/operation/ OPERATION-KEY /extra_fields
MÉTODO GET

### **Path Params**

| Campo               | Tipo   | Descrição                           | Caracteres Máx. |
| ------------------- | ------ | ------------------------------------- | ---------------- |
| `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36               |

### **Query Params**

| Campo               | Tipo   | Descrição                           | Caracteres Máx. |
| ------------------- | ------ | ------------------------------------- | ---------------- |
| `document_type` * | string | Tipo do documento. | **[Enumeradores document_type](#enumeradores-document_type)** |

### **Response**

STATUS 200

Response Body

```json
{
  "operation_key": "550e8400-e29b-41d4-a716-446655440000",
  "document_type": "commercial_paper",
  "template_key": "660e8400-e29b-41d4-a716-446655440001",
  "extra_fields": [
    {
      "field_key": "warranty_description",
      "field_label": "Descrição da Garantia",
      "field_type": "string"
    },
    {
      "field_key": "special_conditions",
      "field_label": "Condições Especiais",
      "field_type": "string"
    },
    {
      "field_key": "additional_clause",
      "field_label": "Cláusula Adicional",
      "field_type": "string"
    }
  ]
}
```

### **Response Body Params**

| Campo               | Tipo   | Descrição                                                     | Caracteres Máx. |
| ------------------- | ------ | --------------------------------------------------------------- | ---------------- |
| `operation_key` * | string | Chave única da operação (UUID v4).                           | 36               |
| `document_type` *  | string | Tipo do documento consultado.                                  | **[Enumeradores document_type](#enumeradores-document_type)** |
| `template_key` *   | string | Chave única do template associado (UUID v4).                  | 36               |
| `extra_fields` *   | array  | Lista de campos extras disponíveis no template.               | -                |

### **Campos do objeto extra_fields**

| Campo               | Tipo   | Descrição                                                     | Caracteres Máx. |
| ------------------- | ------ | --------------------------------------------------------------- | ---------------- |
| `field_key` *      | string | Identificador único do campo extra.                           | 255              |
| `field_label` *    | string | Rótulo descritivo do campo extra.                             | 255              |
| `field_type` *     | string | Tipo de dado do campo extra (ex: `string`).                   | 50               |

---

## **Salvar Campos Extras (POST)**

Salva os valores dos campos extras para um tipo de documento específico em uma operação. Os valores enviados substituem integralmente os campos extras anteriores para o `document_type` informado.

### **Request**

ENDPOINT /commercial_paper/operation/ OPERATION-KEY /extra_fields
MÉTODO POST

### **Path Params**

| Campo               | Tipo   | Descrição                           | Caracteres Máx. |
| ------------------- | ------ | ------------------------------------- | ---------------- |
| `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36               |

Request Body

```json
{
  "document_type": "commercial_paper",
  "extra_fields": {
    "warranty_description": "Garantia prestada pelo avalista",
    "special_conditions": "Condição especial de vencimento antecipado",
    "additional_clause": "Cláusula de cross default"
  }
}
```

### **Request Body Params**

| Campo               | Tipo   | Descrição                                                     | Caracteres Máx. |
| ------------------- | ------ | --------------------------------------------------------------- | ---------------- |
| `document_type` * | string | Tipo do documento.                                              | **[Enumeradores document_type](#enumeradores-document_type)** |
| `extra_fields` *  | object | Objeto contendo os campos extras e seus valores. As chaves devem corresponder aos `field_key` retornados na consulta GET. Todos os valores devem ser strings. | -                |

:::warning
As chaves enviadas no objeto `extra_fields` devem corresponder exatamente aos `field_key` disponíveis no template. Chaves inválidas resultarão em erro.
:::

### **Response**

STATUS 201

Response Body

```json
{
  "operation_key": "550e8400-e29b-41d4-a716-446655440000",
  "document_type": "commercial_paper",
  "extra_fields": {
    "warranty_description": "Garantia prestada pelo avalista",
    "special_conditions": "Condição especial de vencimento antecipado",
    "additional_clause": "Cláusula de cross default"
  }
}
```

### **Response Body Params**

| Campo               | Tipo   | Descrição                                                     | Caracteres Máx. |
| ------------------- | ------ | --------------------------------------------------------------- | ---------------- |
| `operation_key` * | string | Chave única da operação (UUID v4).                           | 36               |
| `document_type` *  | string | Tipo do documento.                                              | **[Enumeradores document_type](#enumeradores-document_type)** |
| `extra_fields` *   | object | Objeto contendo os campos extras salvos com seus respectivos valores. | -                |

---

## **Enumeradores document_type**

| Enum                 | Descrição            |
| -------------------- | ---------------------- |
| `commercial_paper` | Termo Constitutivo     |
| `adhesion_term`    | Termo de Adesão       |

---

## **Erros**

| Código     | HTTP | Descrição                                                                                              |
| ---------- | ---- | -------------------------------------------------------------------------------------------------------- |
| `COM000007` | 404  | Operação não encontrada.                                                                               |
| `COM000008` | 403  | Operação não pertence ao tenant solicitante.                                                           |
| `COM000044` | 400  | Template não definido para o tipo de documento. Gere uma pré-visualização de minuta antes de prosseguir. |
| `COM000045` | 400  | Chaves de campos extras não disponíveis no template.                                                   |

---

# Envio do log de aceite do cliente

URL: /documentation/escrituracao/emissao-de-notas/cadastro-operacao/log-aceite

Este endpoint anexa à operação um PDF com o log de aceite do cliente — o registro das evidências de que o cliente final aceitou as condições da operação. Ele existe para o fluxo de **auto-assinatura**: quando a QI Tech assina o Termo Constitutivo em nome do emissor com o certificado privado liberado na CertifiQI, nenhum link de assinatura é gerado para o cliente, e o log de aceite é o que documenta o consentimento dele.

:::info Envio opcional
O envio **não é obrigatório** e nenhuma etapa da emissão depende dele. A operação segue para análise, assinatura e emissão normalmente sem o log de aceite — o documento é guardado como evidência anexada à operação.
:::

:::warning Exige emissor com auto-assinatura habilitada
O envio só é aceito quando o emissor da operação tem a habilitação de auto-assinatura em `enabled` no sistema de emissores. Emissor sem habilitação, ou com habilitação em qualquer outro status (`pending_term_generation`, `pending_signature`, `reproved`, `canceled`), é recusado com `COM000077` e nada é armazenado.

O envio também só é aceito enquanto a operação está no status `in_filling`; fora desse status a requisição é recusada com `COM000010`.
:::

---

## **Envio do log de aceite (POST)**

### **Request**

ENDPOINT /commercial_paper/operation/ OPERATION-KEY /acceptance_log
MÉTODO POST

### **Path Params**

| Campo             | Tipo   | Descrição                          | Caracteres Máx. |
| ----------------- | ------ | ------------------------------------ | --------------- |
| `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36              |

Request Body

```json
{
    "document_base64": "JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwo..."
}
```

### **Request Body Params**

O corpo não aceita campos além do listado (`additionalProperties: false`) — um campo desconhecido, ou a ausência de `document_base64`, retorna `QIT000001`.

| Campo               | Tipo   | Descrição                                                                                  | Caracteres Máx. |
| ------------------- | ------ | -------------------------------------------------------------------------------------------- | --------------- |
| `document_base64` * | string | PDF do log de aceite do cliente, codificado em base64, sem prefixo `data:` e sem quebras de linha. | — |

## **Response**

STATUS 201

Response Body

```json
{
    "document_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127",
    "created_at": "2026-09-10T14:30:00.000000+00:00"
}
```

### **Response Body Params**

| Campo             | Tipo   | Descrição                                                       |
| ----------------- | ------ | ----------------------------------------------------------------- |
| `document_key` *  | string | Chave única do documento gerada neste envio (UUID v4).          |
| `operation_key` * | string | Chave única da operação à qual o documento foi anexado.        |
| `created_at` *    | string | Data e hora do envio, em UTC.                                     |

:::info Como conferir o que ficou anexado
A operação passa a expor o campo `acceptance_log_document_key` na [consulta de operação por chave](/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-chave), preenchido a partir do envio mais recente. Antes do primeiro envio o campo retorna `null`.
:::

:::warning Reenvio substitui o documento anterior
Um novo envio para a mesma operação gera um novo `document_key` e passa a ser o log de aceite vigente — a referência anterior deixa de ser apontada pela operação. Não há atualização parcial e não há endpoint de remoção.
:::

---

## **Erros**

Os códigos abaixo estão descritos também no [catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros).

| Código      | HTTP | Descrição                                                                                     |
| ----------- | ---- | ----------------------------------------------------------------------------------------------- |
| `QIT000001` | 400  | Falha de schema — `document_base64` ausente ou campo desconhecido no corpo.                    |
| `COM000010` | 400  | Operação não pode ser atualizada fora do status `in_filling`.                                  |
| `COM000077` | 400  | Emissor da operação não está habilitado para auto-assinatura.                                  |
| `COM000007` | 404  | Operação não encontrada.                                                                       |
| `COM000008` | 403  | Operação não pertence ao tenant solicitante.                                                   |

---

# Cancelar Operação

URL: /documentation/escrituracao/emissao-de-notas/cancelar-operacao

Este endpoint permite alterar o status de uma operação para "cancelado", status final para caso em que a operação não será mais finalizada pelo cliente.

---

## Cancelar Operação (PATCH)

### Request
ENDPOINT /commercial_paper/operation/ OPERATION-KEY
MÉTODO PATCH

### Path Params

| Campo           | Tipo   | Descrição                                                 | Caracteres |
|------------------|--------|----------------------------------------------------------|------------|
| `OPERATION-KEY`  | string | Chave única da operação (UUID v4).                       | 36         |

---

### Request Body

```json
{
  "operation_status": "canceled"
}
```

### Request Body Params

| Campo             | Tipo     | Descrição                                                    | Obrigatório |
|--------------------|----------|------------------------------------------------------------|-------------|
| `operation_status` | string   | Status da operação. Deve ser definido como `canceled`. | Sim         |

---

### Response

O corpo da resposta é um JSON completo da operação atualizado.

---

---

# Consulta do Link dos contratos assinados via QI SIGN da Operação

URL: /documentation/escrituracao/emissao-de-notas/consulta-link-assinado-qisign

Este endpoint permite consultar todos os documentos assinados de uma operação específica via QI SIGN, utilizando sua chave única.

---

:::warning Atenção
 O link do contrato assinado tem validade de 24 horas. Após isso, é necessário renovar o link fazendo uma nova requisição pelo endpoint.
:::

## Consulta de Link Assinado da Operação (GET)

### Request
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /signed_url
MÉTODO GET

### Path Params

| Campo           | Tipo   | Descrição                                                 | Caracteres |
|------------------|--------|----------------------------------------------------------|------------|
| `OPERATION-KEY`  | string | Chave única da operação (UUID v4).                       | 36         |

---

### Response
STATUS 200

Response Body

```json
{
    "envelope_key": "5b930d3d-3713-4c42-85d5-f8e9e44e30ce",
    "status": "signed",
    "documents": [
        {
            "document_type": "ncom_pre_price",
            "signed_url": "https://qisign-dossiers.com/7bcf5868-784a-4356-85fb-dd72fd53cd4a.pdf",
            "signers": []
        },
        {
            "document_type": "adhesion_term",
            "signed_url": "https://qisign-dossiers.com/7bcf5868-784a-4356-85fb-dd72fd53cd4a.pdf",
            "signers": []
        }
    ]
}
```

### Response Body Params

| Campo                             | Tipo     | Descrição                                            | Caracteres Máx.                                                 |
|-----------------------------------|----------|------------------------------------------------------|-----------------------------------------------------------------|
| `envelope_key`                    | string   | Chave única do envelope (UUID v4).                 | 36                                                              |
| `status`               | string   | Status dos envelopes                   | [Enumeradores status](#enumeradores-operation-status)
| `documents`                | list   | Lista de documentos do envelope                 | -                                                               |

### Objeto document

| Campo                              | Tipo     | Descrição                                      | Caracteres Máx. |
|-------------------------------------|----------|------------------------------------------------|-----------------|
| `document_type`                    | string   | Tipo do documento.                  | [Enumeradores document type](#enumeradores-document-type)               |
| `signed_url`                    | string   | Url do contrato assinado para download                      | -               |
| `signers`                    | list   | Lista de assinantes                             | -               |

## **Enumeradores operation-status**

| Enum                           | Descrição                                                        |
|--------------------------------|----------------------------------------------------------------|
| `waiting_signature`            | Aguardando assinaturas dos envolvidos.                        |
| `signed`                       | Assinatura finalizada.                                        |
| `signature_rejected`           | Assinatura rejeitada.                                         |
| `canceled`                     | Operação cancelada.                                           |

## **Enumeradores document-type**

| Enum                             | Descrição                                                        |
|----------------------------------|------------------------------------------------------------------|
| `contract`                       | Identificador do contrato.                                        |
| `ncom_pre_price`                 | Nota comercial Pre price.    |
| `ncom_pre_price_days`            | Nota comercial Pre price days.             |
| `ncom_pre_sac`                   | Nota comercial Pre sac.    |
| `ncom_post_sac_cdi`              | Nota comercial Pós sac vinculado ao CDI.                      |
| `ncom_post_sac_ipca`             | Nota comercial Pós sac vinculado ao IPCA.                     |
| `ncom_post_sac_igpm`             | Nota comercial Pós sac vinculado ao IGP-M.                    |
| `ncom_post_price_cdi`            | Nota comercial Pós price vinculado ao CDI.                     |
| `ncom_post_price_ipca`           | Nota comercial Pós price vinculado ao IPCA.                    |
| `ncom_post_price_igpm`           | Nota comercial Pós price vinculado ao IGP-M.                   |
| `ncom_post_price_days_cdi`       | Nota comercial Pós price days vinculado ao CDI.             |
| `ncom_post_price_days_ipca`      | Nota comercial Pós price days vinculado ao IPCA.            |
| `ncom_post_price_days_igpm`      | Nota comercial Pós price days vinculado ao IGP-M.           |
| `subscription_note`              | Boletim de subscrição.                                               |
| `adhesion_term`                  | Termo de adesão.                                                  |

---

# Consulta dos Links para assinatura via QI SIGN da Operação

URL: /documentation/escrituracao/emissao-de-notas/consulta-link-assinatura-qisign

Este endpoint permite consultar todos os links para assinatura de uma operação específica via QI SIGN, utilizando sua chave única.

---

## Consulta de Link para Assinatura da Operação (GET)

### Request
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /signers
MÉTODO GET

### Path Params

| Campo           | Tipo   | Descrição                                                 | Caracteres |
|------------------|--------|----------------------------------------------------------|------------|
| `OPERATION-KEY`  | string | Chave única da operação (UUID v4).                       | 36         |

### Query Params

| Campo                  | Tipo    | Descrição                                                              | Obrigatório |
|------------------------|---------|-------------------------------------------------------------------------|-------------|
| `exclude_qi_signers`   | boolean | Se `true`, oculta da resposta os assinantes que são da QI. Padrão: `false`. | Não         |

---

### Response
STATUS 200

Response Body

```json
{
    "envelope_key": "5b930d3d-3713-4c42-85d5-f8e9e44e30ce",
    "status": "pending_signature",
    "documents": [
        {
            "document_type": "adhesion_term",
            "signers": [
                {
                    "document_number": "145.736.070-56",
                    "signature_url": "https://sign.qitech.com.br/s/s2S33dD",
                    "name": "Emissor assinante",
                    "email": "emissor@qitech.com.br",
                    "status": "on_signature"
                },
                {
                    "document_number": "145.736.070-56",
                    "signature_url": "https://sign.qitech.com.br/s/s2S33dD",
                    "name": "Assinante QI CTVM",
                    "email": "dtvm@qitech.com.br",
                    "status": "on_signature"
                },
                {
                    "document_number": "145.736.070-56",
                    "signature_url": "https://sign.qitech.com.br/s/s2S33dD",
                    "name": "Assinante QI TECH",
                    "email": "qi@qitech.com.br",
                    "status": "on_signature"
                }
            ]
        },
        {
            "document_type": "ncom_pre_price",
            "signers": [
                {
                    "document_number": "145.736.070-56",
                    "signature_url": "https://sign.qitech.com.br/s/s2S33dD",
                    "name": "Assinante QI TECH",
                    "email": "qi@qitech.com.br",
                    "status": "on_signature"
                },
                {
                    "document_number": "145.736.070-56",
                    "signature_url": "https://sign.qitech.com.br/s/s2S33dD",
                    "name": "Emissor assinante",
                    "email": "emissor@qitech.com.br",
                    "status": "on_signature"
                },
                {
                    "document_number": "145.736.070-56",
                    "signature_url": "https://sign.qitech.com.br/s/s2S33dD",
                    "name": "Assinante QI CTVM",
                    "email": "dtvm@qitech.com.br",
                    "status": "on_signature"
                }
            ]
        }
    ]
}
```

### Response Body Params

| Campo                             | Tipo     | Descrição                                            | Caracteres Máx.                                                 |
|-----------------------------------|----------|------------------------------------------------------|-----------------------------------------------------------------|
| `envelope_key`                    | string   | Chave única do envelope (UUID v4).                 | 36                                                              |
| `status`               | string   | Status dos envelopes                   | [Enumeradores operation status](#enumeradores-operation-status)
| `documents`                | list   | Lista de documentos do envelope                 | -                                                               |

### Objeto document

| Campo                              | Tipo     | Descrição                                      | Caracteres Máx. |
|-------------------------------------|----------|------------------------------------------------|-----------------|
| `document_type`                    | string   | Tipo do documento.                  | [Enumeradores document type](#enumeradores-document-type)               |
| `signers`                    | list   | Lista de assinantes                             | -               |

### Objeto signer

| Campo                              | Tipo     | Descrição                                      | Caracteres Máx. |
|-------------------------------------|----------|------------------------------------------------|-----------------|
| `document_number`                    | string   | Documento do assinante.                 | 18                                                              |
| `signature_url`                    | string   | Link do assinante                             | -               |
| `status`                    | string   | Status do assinante.                  | [Enumeradores status](#enumeradores-status)               |
| `name`                    | string   | nome do assinante                             | -               |
| `email`                    | string   | email do assinante                             | -               |

## **Enumeradores operation-status**

| Enum                           | Descrição                                                        |
|--------------------------------|----------------------------------------------------------------|
| `waiting_signature`            | Aguardando assinaturas dos envolvidos.                        |
| `signed`                       | Assinatura finalizada.                                        |
| `signature_rejected`           | Assinatura rejeitada.                                         |
| `canceled`                     | Operação cancelada.                                           |

## **Enumeradores status**

| Enum                           | Descrição                                                        |
|--------------------------------|----------------------------------------------------------------|
| `on_signature`            | Aguardando assinaturas dos envolvidos.                        |
| `analyzed`            | Assinatura completa via API.                        |
| `signed`                       | Assinatura finalizada.                                        |
| `signature_rejected`           | Assinatura rejeitada.                                         |
| `canceled`                     | Operação cancelada.                                           |
| `created`                      | Assinatura criada. |
| `submitted`                      | Enviado para o assinante. |
| `sending_sign_receipt`                      | Enviando dossiê simplificado da assinatura. |
| `analyzing`                      | Assinantes em análise. |
| `completed`                      | Assinatura completa. |
| `expired`                      | Assinatura expirada. |
| `removed`                      | Assinante removido. |
| `failed_waiting_for_manual_fix`                      | Criação da assinatura falhou, ação manual da QI necessária. |

## **Enumeradores document-type**

| Enum                             | Descrição                                                        |
|----------------------------------|------------------------------------------------------------------|
| `contract`                       | Identificador do contrato.                                        |
| `ncom_pre_price`                 | Nota comercial Pre price.    |
| `ncom_pre_price_days`            | Nota comercial Pre price days.             |
| `ncom_pre_sac`                   | Nota comercial Pre sac.    |
| `ncom_post_sac_cdi`              | Nota comercial Pós sac vinculado ao CDI.                      |
| `ncom_post_sac_ipca`             | Nota comercial Pós sac vinculado ao IPCA.                     |
| `ncom_post_sac_igpm`             | Nota comercial Pós sac vinculado ao IGP-M.                    |
| `ncom_post_price_cdi`            | Nota comercial Pós price vinculado ao CDI.                     |
| `ncom_post_price_ipca`           | Nota comercial Pós price vinculado ao IPCA.                    |
| `ncom_post_price_igpm`           | Nota comercial Pós price vinculado ao IGP-M.                   |
| `ncom_post_price_days_cdi`       | Nota comercial Pós price days vinculado ao CDI.             |
| `ncom_post_price_days_ipca`      | Nota comercial Pós price days vinculado ao IPCA.            |
| `ncom_post_price_days_igpm`      | Nota comercial Pós price days vinculado ao IGP-M.           |
| `subscription_note`              | Boletim de subscrição.                                               |
| `adhesion_term`                  | Termo de adesão.                                                  |

---

# Consulta dos Documentos da Operação

URL: /documentation/escrituracao/emissao-de-notas/consulta/consulta-documentos-operacao

Estes endpoints devolvem, em base64, o termo constitutivo e o termo de adesão gerados para a operação.

São eles que entregam o arquivo a ser assinado no fluxo de **assinatura externa**: o documento devolvido aqui é
exatamente o que a QI Tech gerou na aprovação, e é sobre esses bytes que a assinatura precisa ser calculada.

:::warning Atenção
Os documentos só existem depois que a operação é aprovada na análise. Antes disso a consulta responde `404`.
:::

---

## Consulta do Termo Constitutivo (GET)

### Request
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /contract
MÉTODO GET

---

## Consulta do Termo de Adesão (GET)

### Request
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /adhesion_term
MÉTODO GET

### Path Params

| Campo           | Tipo   | Descrição                                                 | Caracteres |
|------------------|--------|----------------------------------------------------------|------------|
| `OPERATION-KEY`  | string | Chave única da operação (UUID v4).                       | 36         |

---

### Response
STATUS 200

Response Body

```json
{
    "document_base64": "JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSAo..."
}
```

### Response Body Params

| Campo               | Tipo   | Descrição                                  | Caracteres Máx. |
|---------------------|--------|--------------------------------------------|-----------------|
| `document_base64`   | string | Conteúdo do documento em base64.           | -               |

---

## Uso na assinatura externa

Decodifique o `document_base64` e assine o arquivo resultante sem reprocessá-lo. A QI Tech compara o resumo SHA-256 do
documento com o declarado dentro do `.p7s`, e reabrir o PDF em outra ferramenta para salvá-lo altera esse resumo.

O envio da assinatura é feito pelo endpoint de
**[envio de documentos assinados](/documentation/escrituracao/emissao-de-notas/envio-contratos-assinados)**.

---

# Consulta de Operação por Chave

URL: /documentation/escrituracao/emissao-de-notas/consulta/consulta-por-chave

Este endpoint permite consultar os detalhes completos de uma operação específica, utilizando sua chave única.

---

## Consulta de Operação (GET)

### Request
ENDPOINT /commercial_paper/operation/ OPERATION-KEY
MÉTODO GET

### Path Params

| Campo           | Tipo   | Descrição                                                 | Caracteres |
|------------------|--------|----------------------------------------------------------|------------|
| `OPERATION-KEY`  | string | Chave única da operação (UUID v4).                       | 36         |

---

### Response
STATUS 200

Response Body

```json
{
    "tenant_key": "13a6a1d5-7a3c-4627-a0a6-9fd746662ca4",
    "operation_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74",
    "operation_type": "commercial_paper",
    "operation_status": "issued",
    "backoffice_analysis_status": "approved",
    "issuer_key": "9e08fd62-ce43-4c95-99e0-4386e980d618",
    "issuer_name": "Blue Logic",
    "issuer_document_number": "97.923.586/0001-06",
    "issuer_bank_account": {
        "account_type": "checking",
        "account_digit": "3",
        "account_branch": "0001",
        "account_number": "4464541",
        "financial_institution_ispb": "32402502",
        "financial_institution_code_number": "329"
    },
    "issuer_onboarding_approved": true,
    "issue_number": 1,
    "issue_series": 1,
    "contract_number": "0000000001",
    "issue_date": "2025-02-03",
    "financial_base_date": "2025-02-03",
    "commercial_paper_template_key": "68956441-d46c-44ed-93b9-b1806dd6ada9",
    "commercial_paper_document_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/commercial_paper/2cb87abc-8bdf-4df3-be98-b7afb53b14c8",
    "adhesion_term_template_key": "58743ab9-99bd-439a-93af-16e4c5fccd6f",
    "adhesion_term_document_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/adhesion_term/fe74eaed-2f44-45b4-b972-83fa222cbf1c",
    "envelope_signature_status": "signed",
    "envelope_key": "4d7f28b4-185f-482d-929e-d1af937cb27b",
    "envelope_signature_url": "https://sandbox.certifiqi.com.br/sign?batch-group=c4747fe6-2cc0-41a9-8972-84b44f8fff8a",
    "envelope_signed_files_key": "dc368e4d-c288-4971-ad8d-5c9c31616e74/signed_files",
    "financial": {
        "financial_base_date": "2025-02-03",
        "issue_quantity": 1000000,
        "unit_price": 1.0,
        "issue_amount": 1000000.0,
        "released_amount": 1000000.0,
        "cet": 5.0,
        "annual_cet": 79.59,
        "number_of_installments": 5,
        "prefixed_interest_rate": {
            "daily_rate": 0.0016053474,
            "annual_rate": 0.795856326,
            "monthly_rate": 0.05,
            "interest_base": "calendar_days_365"
        },
        "fine_delay_rate": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days_365"
        },
        "contract_fine_rate": 0.02,
        "financial_index": null,
        "post_fixed_interest_rate": null,
        "fees": [
            {
                "type": "internal",
                "amount": 2.0,
                "fee_type": "bookkeeping_fee",
                "fee_amount": 20000.0,
                "amount_type": "percentage"
            },
            {
                "type": "external",
                "amount": 5.0,
                "fee_type": "structuring_fee",
                "fee_amount": 50000.0,
                "amount_type": "percentage"
            }
        ],
        "installment_list": [
            {
                "installment_number": 1,
                "workdays": 20,
                "calendar_days": 30,
                "principal_amortization_unit_price": 0.18122484,
                "principal_amortization_amount": 181224.84138231,
                "interest_amount": 49298.45861769,
                "amount": 230523.3,
                "due_principal": 1000000.0,
                "due_interest": 0.0,
                "due_date": "2025-03-05",
                "has_interest": true
            },
            {
                "installment_number": 2,
                "workdays": 21,
                "calendar_days": 29,
                "principal_amortization_unit_price": 0.19153595,
                "principal_amortization_amount": 191535.95353305,
                "interest_amount": 38987.34646695,
                "amount": 230523.3,
                "due_principal": 818775.15861769,
                "due_interest": 0.0,
                "due_date": "2025-04-03",
                "has_interest": true
            },
            {
                "installment_number": 3,
                "workdays": 19,
                "calendar_days": 32,
                "principal_amortization_unit_price": 0.19748652,
                "principal_amortization_amount": 197486.52331007,
                "interest_amount": 33036.77668993,
                "amount": 230523.3,
                "due_principal": 627239.20508464,
                "due_interest": 0.0,
                "due_date": "2025-05-05",
                "has_interest": true
            },
            {
                "installment_number": 4,
                "workdays": 21,
                "calendar_days": 29,
                "principal_amortization_unit_price": 0.21005991,
                "principal_amortization_amount": 210059.90840452,
                "interest_amount": 20463.39159548,
                "amount": 230523.3,
                "due_principal": 429752.68177457,
                "due_interest": 0.0,
                "due_date": "2025-06-03",
                "has_interest": true
            },
            {
                "installment_number": 5,
                "workdays": 21,
                "calendar_days": 30,
                "principal_amortization_unit_price": 0.21969277,
                "principal_amortization_amount": 219692.77337005,
                "interest_amount": 10830.52662995,
                "amount": 230523.3,
                "due_principal": 219692.77337005,
                "due_interest": 0.0,
                "due_date": "2025-07-03",
                "has_interest": true
            }
        ]
    },
    "tags": [],
    "investor_list": [
        {
            "investor_key": "a1a75b66-6f7e-4bcc-9ff5-6f8adf7cae09",
            "investor_name": "Ultimate Cascade",
            "investor_document_number": "31.424.651/0001-32",
            "subscription_percentage": 100.0,
            "subscription_quantity": 1000000,
            "investor_onboarding_approved": true,
            "bank_account": {
                "account_type": "checking",
                "account_digit": "3",
                "account_branch": "0001",
                "account_number": "33400254",
                "financial_institution_ispb": "32402502",
                "financial_institution_code_number": "329"
            },
            "updated_at": null
        }
    ],
    "related_party_list": [
        {
            "related_party_key": "1ac83d43-41cb-4ad0-a7ca-add6c3a3171c",
            "name": "Blue Logic",
            "document_number": "97.923.586/0001-06",
            "role_type": "issuer",
            "is_active": true,
            "updated_at": null,
            "trading_name": "Blue Logic",
            "cnae_code": "47.21-1-02",
            "company_type": "ltda",
            "foundation_date": "2007-10-25",
            "person_type": "legal",
            "street": "Rua Romualdo de Souza Brito",
            "neighborhood": "Centro",
            "number": "89",
            "postal_code": "08150-470",
            "city": "São Paulo",
            "state": "SP",
            "complement": "Letra C",
            "signer_group_list": [
                {
                    "signer_group_key": "fa2cbede-a501-41e1-bf70-078bb0d4ac7b",
                    "minimum_required_signers": 1,
                    "signers": [
                        {
                            "name": "John Doe",
                            "email": "123.456.789-00@yopmail.com",
                            "phone_number": "+5511988887777",
                            "document_number": "123.456.789-00",
                            "is_group_mandatory": true
                        }
                    ]
                }
            ],
            "document_list": [],
            "contact_information_list": [
                {
                    "name": "John Doe",
                    "email": "123.456.789-00@yopmail.com",
                    "is_default": true,
                    "phone_number": "+5516982399722",
                    "document_number": "123.456.789-00",
                    "issuer_contact_information_key": "6e9714f4-d652-4ca0-89e2-13e9e2ec3414"
                }
            ]
        },
        {
            "related_party_key": "bab03c76-a12a-4d88-aaf8-70799e3b1b30",
            "name": "Ultimate Cascade",
            "document_number": "31.424.651/0001-32",
            "role_type": "investor",
            "is_active": true,
            "updated_at": null,
            "trading_name": "Ultimate Cascade",
            "cnae_code": "47.21-1-02",
            "company_type": "ltda",
            "foundation_date": "2007-10-25",
            "person_type": "legal",
            "street": "Rua Romualdo de Souza Brito",
            "neighborhood": "Centro",
            "number": "89",
            "postal_code": "08150-470",
            "city": "São Paulo",
            "state": "SP",
            "complement": "Letra C",
            "signer_group_list": [
                {
                    "signer_group_key": "ccb36b0b-40b5-42e0-bc41-0e8fce57f3ca",
                    "minimum_required_signers": 1,
                    "signers": [
                        {
                            "name": "John Doe",
                            "email": "123.456.789-00@yopmail.com",
                            "phone_number": "+5516982399722",
                            "document_number": "123.456.789-00",
                            "is_group_mandatory": true
                        }
                    ]
                }
            ],
            "document_list": [],
            "contact_information_list": [
                {
                    "name": "John Doe",
                    "email": "123.456.789-00@yopmail.com",
                    "is_default": true,
                    "phone_number": "+5511988887777",
                    "document_number": "123.456.789-00",
                    "investor_contact_information_key": "26299c0f-2127-45d4-b22e-f2b494d2f7ae"
                }
            ]
        }
    ],
    "collateral_list": [
        {
            "collateral_key": "d8fdb578-1e2a-4b79-8267-5b1763e56754",
            "collateral_type": "fiduciary_alienation_property"
        }
    ],
    "metadata_list": [
        {
            "metadata_key": "convenio",
            "metadata_value": "12398129038"
        }
    ],
    "integralization_key": "d8fdb578-1e2a-4b79-8267-5b1763e56754",
    "security_key": "26299c0f-2127-45d4-b22e-f2b494d2f7ae"
}
```

### Response Body Params

| Campo                             | Tipo     | Descrição                                            | Caracteres Máx.                                                 |
|-----------------------------------|----------|------------------------------------------------------|-----------------------------------------------------------------|
| `tenant_key` *                    | string   | Chave única do tenant (UUID v4).                     | 36                                                              |
| `operation_key` *                 | string   | Chave única da operação (UUID v4).                   | 36                                                              |
| `operation_type` *                | string   | Tipo da operação. `commercial_paper`                 | -                                                               |
| `operation_status` *              | string   | Status da operação.                                  | [Enumeradores operation_status](#enumeradores-operation_status) |
| `issuer_key` *                    | string   | Chave única do emissor (UUID v4).                    | 36                                                              |
| `issuer_name` *                   | string   | Nome do emissor.                                     | -                                                               |
| `issuer_document_number` *        | string   | Número do documento do emissor (CNPJ).               | 18                                                              |
| `issuer_bank_account` *           | object   | Dados bancários do emissor.                          | [Objeto bank_account](#objeto-bank_account)                     |
| `issuer_onboarding_approved` *    | boolean  | Indica se o onboarding do emissor foi aprovado.      | -                                                               |
| `issue_number` *                  | integer  | Número da emissão.                                   | -                                                               |
| `issue_series` *                  | integer  | Série da emissão.                                    | -                                                               |
| `contract_number` *               | string   | Número do contrato.                                  | -                                                               |
| `issue_date` *                    | string   | Data da emissão (formato ISO 8601).                  | -                                                               |
| `financial_base_date` *           | string   | Data base financeira da operação (formato ISO 8601). | -                                                               |
| `commercial_paper_template_key` * | string   | Chave única do template do commercial paper.         | 36                                                              |
| `commercial_paper_document_key` * | string   | Chave do documento do commercial paper.              | -                                                               |
| `adhesion_term_template_key` *    | string   | Chave única do template do termo de adesão.          | 36                                                              |
| `adhesion_term_document_key` *    | string   | Chave do documento do termo de adesão.               | -                                                               |
| `investor_list` *                 | object   | Lista de investidores.                               | [Objeto investor](#objeto-investor)                             |

### Objeto bank_account

| Campo                              | Tipo     | Descrição                                      | Caracteres Máx. |
|-------------------------------------|----------|------------------------------------------------|-----------------|
| `account_type` *                    | string   | Tipo da conta (ex: checking).                  | -               |
| `account_digit` *                    | string   | Dígito da conta bancária.                      | -               |
| `account_branch` *                    | string   | Agência bancária.                              | -               |
| `account_number` *                    | string   | Número da conta bancária.                      | -               |
| `financial_institution_ispb` *       | string   | Código ISPB da instituição financeira.        | -               |
| `financial_institution_code_number` * | string   | Código da instituição financeira.             | -               |

### Objeto financial

| Campo                              | Tipo     | Descrição                                                       | Caracteres Máx.                                                 |
|-------------------------------------|----------|-----------------------------------------------------------------|-----------------------------------------------------------------|
| `financial_base_date` *             | string   | Data base financeira da operação (formato ISO 8601).            | -                                                               |
| `issue_quantity` *                  | integer  | Quantidade total de unidades emitidas.                          | -                                                               |
| `unit_price` *                      | float    | Preço unitário da emissão.                                      | -                                                               |
| `issue_amount` *                    | float    | Valor total da emissão.                                         | -                                                               |
| `released_amount` *                 | float    | Valor total liberado.                                           | -                                                               |
| `cet` *                             | float    | Custo Efetivo Total da operação (%).                            | -                                                               |
| `annual_cet` *                      | float    | Custo Efetivo Total anualizado (%).                             | -                                                               |
| `number_of_installments` *          | integer  | Número total de parcelas da operação.                           | -                                                               |
| `prefixed_interest_rate` *          | object   | Taxa de juros prefixada.                                        | [Objeto prefixed_interest_rate](#objeto-prefixed_interest_rate) |
| `fine_delay_rate` *                 | object   | Taxa de multa por atraso                                        | [Objeto fine_delay_rate](#objeto-fine_delay_rate).              | 
| `contract_fine_rate` *              | float    | Taxa de multa contratual (%).                                   | -                                                               |
| `financial_index`                   | string   | Índice financeiro de referência (caso exista).                  | -                                                               |
| `post_fixed_interest_rate`          | object   | Taxa de juros pós-fixada (se aplicável).                        | -                                                               |
| `fees` *                            | array    | Lista de taxas aplicáveis.|  [Objeto fees](#objeto-fees)                                                                           |
| `installment_list` *                | array    | Lista de parcelas. | [Objeto installment](#objeto-installment)                                                                     |

### Objeto prefixed_interest_rate

| Campo                 | Tipo   | Descrição                                                  | Caracteres Máx. |
|-----------------------|--------|------------------------------------------------------------|-----------------|
| `daily_rate` *        | float  | Taxa de juros diária (%).                                  | -               |
| `annual_rate` *       | float  | Taxa de juros anualizada (%).                              | -               |
| `monthly_rate` *      | float  | Taxa de juros mensal (%).                                  | -               |
| `interest_base` *     | string | Base de cálculo da taxa de juros (`calendar_days_365`).    | -               |

## Objeto fine_delay_rate

| Campo               | Tipo   | Descrição                                        | Caracteres Máx. |
|---------------------|--------|--------------------------------------------------|-----------------|
| `monthly_rate` *    | float  | Taxa de multa mensal por atraso (%).             | -               |
| `interest_base` *   | string | Base de cálculo da taxa de juros (`calendar_days_365`). | - |

## Objeto fees

| Campo          | Tipo    | Descrição                                      | Caracteres Máx. |
|---------------|---------|------------------------------------------------|-----------------|
| `type` *      | string  | Tipo da taxa (`internal`, `external`).         | -               |
| `amount` *    | float   | Percentual da taxa aplicada.                   | -               |
| `fee_type` *  | string  | Tipo da taxa.           | -               |
| `fee_amount` * | float  | Valor absoluto da taxa aplicada.               | -               |
| `amount_type` * | string | Tipo do valor (`percentage`, `fixed`).        | -               |

## Objeto installment

| Campo                                     | Tipo    | Descrição                                                | Caracteres Máx. |
|-------------------------------------------|---------|----------------------------------------------------------|-----------------|
| `installment_number` *                    | integer | Número da parcela.                                       | -               |
| `workdays` *                               | integer | Quantidade de dias úteis até o vencimento.               | -               |
| `calendar_days` *                          | integer | Quantidade de dias corridos até o vencimento.            | -               |
| `principal_amortization_unit_price` *      | float   | Valor unitário de amortização do principal.              | -               |
| `principal_amortization_amount` *          | float   | Valor total de amortização do principal.                 | -               |
| `interest_amount` *                        | float   | Valor total dos juros da parcela.                        | -               |
| `amount` *                                 | float   | Valor total da parcela.                                  | -               |
| `due_principal` *                          | float   | Valor do principal a vencer após a parcela.              | -               |
| `due_interest` *                           | float   | Valor dos juros a vencer após a parcela.                 | -               |
| `due_date` *                               | string  | Data de vencimento da parcela (formato ISO 8601).       | -               |
| `has_interest` *                           | boolean | Indica se a parcela possui cobrança de juros.           | -               |

## Objeto investor

| Campo                          | Tipo    | Descrição                                                            | Caracteres Máx.                              |
|--------------------------------|---------|----------------------------------------------------------------------|----------------------------------------------|
| `investor_key` *               | string  | Chave única do investidor (UUID v4).                                 | 36                                           |
| `investor_name` *              | string  | Nome do investidor.                                                  | -                                            |
| `investor_document_number` *   | string  | Número do documento do investidor (CNPJ/CPF).                        | 18                                           |
| `subscription_percentage` *    | float   | Percentual de participação do investidor na operação.                | -                                            |
| `subscription_quantity` *      | integer | Quantidade de unidades subscritas pelo investidor.                   | -                                            |
| `investor_onboarding_approved` * | boolean | Indica se o onboarding do investidor foi aprovado.                   | -                                            |
| `bank_account` *               | object  | Informações bancárias do investidor. | [Objeto bank_account](#objeto-bank_account). |

## **Enumeradores operation_status**

| Enum                           | Descrição                                                        |
|--------------------------------|----------------------------------------------------------------|
| `in_filling`                   | Operação em fase de preenchimento.                             |
| `in_analysis`                  | Operação em análise.                                           |
| `waiting_onboarding_approval`  | Aguardando aprovação do onboarding do emissor.                |
| `pending_signature_submission` | Aguardando envio para assinatura.                             |
| `waiting_signature`            | Aguardando assinaturas dos envolvidos.                        |
| `issued`                       | Operação emitida.                                             |
| `finished`                     | Operação concluída.                                           |
| `signature_rejected`           | Assinatura rejeitada.                                         |
| `onboarding_reproved`          | Onboarding do emissor reprovado.                              |
| `compliance_reproved`          | Reprovado por compliance.                                     |
| `canceled`                     | Operação cancelada.                                           |

---

# Consulta de Operações por Filtros

URL: /documentation/escrituracao/emissao-de-notas/consulta/consulta-por-filtros

Este endpoint permite consultar operações de **nota comercial** utilizando filtros opcionais.

---

## **Request**
ENDPOINT /commercial_paper/operation
MÉTODO GET

### **Query Params**

| Campo                      | Tipo     | Descrição                                     | Obrigatório |
|----------------------------|----------|-----------------------------------------------|-------------|
| `issuer_document_number`   | string   | Número do documento do emissor (CNPJ).        | Não         |
| `investor_document_number` | string   | Número do documento do investidor (CPF/CNPJ). | Não         |
| `operation_status`         | string   | Status da operação.                           | **[Enumeradores operation_status](#enumeradores-operation_status)** | Não |
| `metadata_key`             | array    | Chave de metadado.                            | Não         |
| `metadata_value`           | array    | Valor de metadado.                            | Não         |

---

## **Response**
STATUS 200

Response Body

```json
{
    "data": [
        {
            "tenant_key": "13edaf06-9810-4689-b00b-2367274d1a14",
            "operation_key": "34bc5da7-89df-467d-93af-ed25184ab72e",
            "operation_type": "commercial_paper",
            "operation_status": "in_filling",
            "backoffice_analysis_status": "waiting_submission_for_analysis",
            "issuer_key": "7fbe9f89-b9ca-4445-85ac-6098da86bb56",
            "issuer_name": "Global Networks",
            "issuer_document_number": "73364815000123",
            "issue_number": 1,
            "contract_number": "0000000004"
        },
        {
            "tenant_key": "13edaf06-9810-4689-b00b-2367274d1a14",
            "operation_key": "f456ee66-5844-4ebc-b69d-365ce6df7138",
            "operation_type": "commercial_paper",
            "operation_status": "in_filling",
            "backoffice_analysis_status": "waiting_submission_for_analysis",
            "issuer_key": "7fbe9f89-b9ca-4445-85ac-6098da86bb56",
            "issuer_name": "Global Networks",
            "issuer_document_number": "73364815000123",
            "issue_number": 2,
            "contract_number": "0000000005"
        }
    ],
    "pagination": {
        "current_page": 1,
        "next_page": null,
        "rows_per_page": 100,
        "total_pages": 1,
        "total_rows": 2
    }
}
```

---

### **Response Body Params**

#### **Objeto Data**

| Campo                        | Tipo     | Descrição                                                 | Caracteres Máx. |
|------------------------------|----------|-----------------------------------------------------------|-----------------|
| `tenant_key` *               | string   | Chave única do tenant (UUID v4).                          | 36              |
| `operation_key` *            | string   | Chave única da operação (UUID v4).                        | 36              |
| `operation_type` *           | string   | Tipo da operação. Sempre será `commercial_paper`.         | 50              |
| `operation_status` *         | string   | Status atual da operação. | **[Enumeradores operation_status](#enumeradores-operation_status)** | 50 |
| `backoffice_analysis_status` | string   | Status da análise de backoffice.                          | 50              |
| `issuer_key` *               | string   | Chave única do emissor associado à operação (UUID v4).    | 36              |
| `issuer_name` *              | string   | Nome do emissor associado à operação.                     | 255             |
| `issuer_document_number` *   | string   | Número do documento do emissor (CNPJ).                    | 14              |
| `issue_number` *             | integer  | Número da emissão associada à operação.                   | -               |
| `contract_number` *          | string   | Número do contrato associado à operação.                  | 20              |

#### **Objeto Pagination**

| Campo             | Tipo     | Descrição                                                  |
|-------------------|----------|----------------------------------------------------------|
| `current_page` *  | integer  | Página atual da consulta.                               |
| `next_page`       | integer  | Próxima página, caso exista.                           |
| `rows_per_page` * | integer  | Número de registros por página.                        |
| `total_pages` *   | integer  | Total de páginas disponíveis.                          |
| `total_rows` *    | integer  | Total de registros encontrados para os filtros aplicados. |

---

## **Enumeradores operation_status**

| Enum                           | Descrição                                                        |
|--------------------------------|----------------------------------------------------------------|
| `in_filling`                   | Operação em fase de preenchimento.                             |
| `in_analysis`                  | Operação em análise.                                           |
| `waiting_onboarding_approval`  | Aguardando aprovação do onboarding do emissor.                |
| `pending_signature_submission` | Aguardando envio para assinatura.                             |
| `waiting_signature`            | Aguardando assinaturas dos envolvidos.                        |
| `issued`                       | Operação emitida.                                             |
| `finished`                     | Operação concluída.                                           |
| `signature_rejected`           | Assinatura rejeitada.                                         |
| `onboarding_reproved`          | Onboarding do emissor reprovado.                              |
| `compliance_reproved`          | Reprovado por compliance.                                     |
| `canceled`                     | Operação cancelada.                                           |

---

# Consulta do Próximo Número de Emissão por Emissor

URL: /documentation/escrituracao/emissao-de-notas/consulta/consulta-proximo-numero-emissao

Este endpoint retorna o próximo `issue_number` (número de emissão) disponível para o emissor identificado por `issuer_key`. O valor retornado considera a maior numeração já utilizada em operações **não canceladas** do emissor e o controle interno de numeração na configuração do emissor — sempre é devolvido o maior entre os dois.

Caso ainda não exista configuração de numeração para o emissor, ela é criada automaticamente com `current_issue_number = 1` e esse valor é retornado.

---

## **Request**
ENDPOINT /commercial_paper/issuer/ ISSUER-KEY /issue_number
MÉTODO GET

### **Path Params**

| Campo          | Tipo        | Descrição                                                                 | Caracteres Máx. |
|----------------|-------------|---------------------------------------------------------------------------|-----------------|
| `ISSUER-KEY` * | string/uuid | Identificador único (UUID v4) do emissor cadastrado no Issuer Management. | 36              |

---

## **Response**
STATUS 200

Response Body

```json
{
    "issue_number": 42
}
```

---

### **Response Body Params**

| Campo            | Tipo    | Descrição                                                                                                            | Caracteres Máx. |
|------------------|---------|----------------------------------------------------------------------------------------------------------------------|-----------------|
| `issue_number` * | integer | Próximo número de emissão sugerido para uma nova operação do emissor. Inicia em `1` para emissores sem operações nem configuração prévia. | -               |

---

# Enviar Atas de Aprovação Assinadas

URL: /documentation/escrituracao/emissao-de-notas/envio-ata-aprovacao

Este endpoint permite enviar as atas de aprovação de empresas do tipo SA ou COP assinadas de forma externa para o sistema de escrituação, enviando um base64 que será analisado e aprovado pelo escriturador.

---

## Enviar Operação Assinada (POST)

### Request
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /upload_signed_document
MÉTODO POST

### Path Params

| Campo           | Tipo   | Descrição                                                 | Caracteres |
|------------------|--------|----------------------------------------------------------|------------|
| `OPERATION-KEY`  | string | Chave única da operação (UUID v4).                       | 36         |

---

### Request Body

Request Body

```json
{
    "contract_base64": "image_b64",
    "contract_type": "sa_minute"
}
```

### Request Body Params

| Campo                        | Tipo     | Descrição                                                                                                                       | Caracteres Máx. |
|------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------|
| `contract_type` *             | string   | Tipo de contrato assinado | **[Enumeradores contract_type](#enumeradores-contract_type)** |
| `contract_base64` *           | string   | Ata de aprovação assinada em base64. | - |

### Enumeradores contract_type

| Enum                | Descrição                                  |
|--------------------|------------------------------------------|
| `sa_minute`        | Ata de aprovação de emissão da nota comercial para empresa **SA**.         |
| `cop_minute`      | Ata de aprovação de emissão da nota comercial para empresa **COOPERATIVA**.         |

### Response

O corpo da resposta é um JSON completo da operação atualizada.

---

---

# Enviar Documentos Assinados da Operação

URL: /documentation/escrituracao/emissao-de-notas/envio-contratos-assinados

Este endpoint recebe as assinaturas dos documentos de formalização de operações com `signature_method` igual a
**client_side**.

O emissor assina os documentos na certificadora dele e envia à QI Tech apenas o arquivo de assinatura
(`p7s_base64`), sem o PDF.

:::warning Aviso
Use este endpoint apenas em operações com `signature_method` **client_side**. Nos fluxos **QI Sign** e
**CertifiQI** os contratos são gerados e assinados pela própria plataforma. Para a ata de aprovação use o endpoint de
**[envio de ata de aprovação](/documentation/escrituracao/emissao-de-notas/envio-ata-aprovacao)**.
:::

---

## Enviar Documento Assinado (POST)

### Request
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /upload_signed_document
MÉTODO POST

### Path Params

| Campo           | Tipo   | Descrição                                                 | Caracteres |
|------------------|--------|----------------------------------------------------------|------------|
| `OPERATION-KEY`  | string | Chave única da operação (UUID v4).                       | 36         |

---

### Request Body

Assinatura do termo constitutivo

```json
{
    "contract_type": "commercial_paper",
    "p7s_base64": "MIIJugYJKoZIhvcNAQcCoIIJqzCCCacC..."
}
```

Assinatura de uma garantia

```json
{
    "contract_type": "collateral",
    "collateral_key": "8f0b6f0a-1a2b-4c3d-9e8f-7a6b5c4d3e2f",
    "p7s_base64": "MIIJugYJKoZIhvcNAQcCoIIJqzCCCacC..."
}
```

### Request Body Params

| Campo               | Tipo   | Descrição                                                                                                       | Caracteres Máx. |
|---------------------|--------|-----------------------------------------------------------------------------------------------------------------|-----------------|
| `contract_type` *    | string | Tipo do documento enviado.                                                                                        | **[Enumeradores contract_type](#enumeradores-contract_type)** |
| `p7s_base64` *       | string | Assinatura CAdES em base64, destacada ou anexada.                                                                 | -               |
| `collateral_key`    | string | Chave da garantia a que a assinatura se refere. Obrigatório quando `contract_type` é `collateral`.                 | 36              |

### Enumeradores contract_type

| Enum                | Descrição                                                                   |
|---------------------|------------------------------------------------------------------------------|
| `commercial_paper`  | Termo constitutivo da nota comercial.                                         |
| `adhesion_term`     | Termo de adesão da nota comercial.                                            |
| `collateral`        | Documento de garantia da operação. Exige `collateral_key`.                    |

### Response

O corpo da resposta é o JSON completo da operação atualizada.

---

## Assinatura dos documentos de formalização

Os documentos ficam disponíveis para download depois que a operação é aprovada na análise, pelo endpoint de
**[consulta de documentos da operação](/documentation/escrituracao/emissao-de-notas/consulta/consulta-documentos-operacao)**.

Cada documento aceita um único `.p7s` e é enviado em uma requisição própria. Quando todos os documentos exigidos são
aceitos, os assinantes da QI Tech assinam e a operação é emitida.

:::danger Assine exatamente o documento baixado
A QI Tech compara o resumo (SHA-256) declarado dentro do `.p7s` com o do documento gerado na aprovação. Ferramentas que
reprocessam o PDF antes de assinar, como reabrir e salvar ou recomprimir, alteram esse resumo e a assinatura é recusada
com `COM000074`.
:::

## **Erros**

Os códigos abaixo estão descritos também no [catálogo de erros](/documentation/escrituracao/catalogo-erros/catalogo-erros).

| Código        | HTTP | Descrição                                                                                  |
|---------------|--------|--------------------------------------------------------------------------------------------|
| `COM000072`   | 400    | O documento de formalização exige o arquivo de assinatura e o `p7s_base64` não foi enviado.  |
| `COM000073`   | 400    | O arquivo enviado não pôde ser lido como estrutura CMS, ou excede o tamanho aceito.          |
| `COM000074`   | 422    | A assinatura não corresponde ao documento emitido pela QI Tech.                              |
| `COM000075`   | 409    | O documento já teve uma assinatura aceita.                                                   |

---

# Enviar Operação para Análise

URL: /documentation/escrituracao/emissao-de-notas/envio-para-analise

Este endpoint permite alterar o status de uma operação para "em análise", enviando-a para o processo de validação de compliance pelo escriturador.

---

## Enviar Operação para Análise (PATCH)

### Request
ENDPOINT /commercial_paper/operation/ OPERATION-KEY
MÉTODO PATCH

### Path Params

| Campo           | Tipo   | Descrição                                                 | Caracteres |
|------------------|--------|----------------------------------------------------------|------------|
| `OPERATION-KEY`  | string | Chave única da operação (UUID v4).                       | 36         |

---

### Request Body

```json
{
  "operation_status": "in_analysis"
}
```

### Request Body Params

| Campo             | Tipo     | Descrição                                                    | Obrigatório |
|--------------------|----------|------------------------------------------------------------|-------------|
| `operation_status` | string   | Status da operação. Deve ser definido como `in_analysis`. | Sim         |

---

### Response

O corpo da resposta é um JSON completo da operação atualizado.

---

---

# Enviar Operação para Assinatura

URL: /documentation/escrituracao/emissao-de-notas/envio-para-assinatura

:::warning Aviso
Operações aprovadas pelo compliance são enviadas automaticamente para assinatura periodicamente. Este endpoint deve ser usado apenas para realizar um envio imediato, caso necessário.
:::

---

## Enviar Operação para Assinatura (POST)

### Request
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /send_to_signature
MÉTODO POST

### Path Params

| Campo           | Tipo   | Descrição                                                 | Caracteres |
|------------------|--------|----------------------------------------------------------|------------|
| `OPERATION-KEY`  | string | Chave única da operação (UUID v4).                       | 36         |

---

### Request Body

Nenhum corpo de requisição é necessário.

---

### Response

O corpo da resposta é um JSON completo da operação atualizado.

---

---

# Alterar Template do Termo de Adesão

URL: /documentation/escrituracao/emissao-de-notas/geracao-minutas/alterar-template-ta

Este endpoint permite a alteração do template do Termo de Adesão para uma operação específica.

### **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY
MÉTODO PATCH

### **Path Params**

| Campo            | Tipo   | Descrição                                     | Caracteres Máx. |
|------------------|--------|-----------------------------------------------|-----------------|
| `OPERATION-KEY` *  | string | Chave única da operação (UUID v4).             | 36              |

---

Request Body

```json
{
  "adhesion_term_template_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e"
}
```

### **Request Body Params**

| Campo                                | Tipo     | Descrição                                        | Obrigatório |
|--------------------------------------|----------|--------------------------------------------------|-------------|
| `adhesion_term_template_key` *    | string   | Chave única do novo template a ser utilizado (UUID v4). | Sim |

## Response

O corpo da resposta é um JSON completo da operação atualizado.

---

# Alterar Template do Termo Constitutivo

URL: /documentation/escrituracao/emissao-de-notas/geracao-minutas/alterar-template-tc

Este endpoint permite a alteração do template do Termo Constitutivo para uma operação específica.

### **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY
MÉTODO PATCH

### **Path Params**

| Campo            | Tipo   | Descrição                                     | Caracteres Máx. |
|------------------|--------|-----------------------------------------------|-----------------|
| `OPERATION-KEY` *  | string | Chave única da operação (UUID v4).             | 36              |

---

Request Body

```json
{
  "commercial_paper_template_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e"
}
```

### **Request Body Params**

| Campo                                | Tipo     | Descrição                                        | Obrigatório |
|--------------------------------------|----------|--------------------------------------------------|-------------|
| `commercial_paper_template_key` *    | string   | Chave única do novo template a ser utilizado (UUID v4). | Sim |

## Response

O corpo da resposta é um JSON completo da operação atualizado.

---

# Consulta de templates disponíveis

URL: /documentation/escrituracao/emissao-de-notas/geracao-minutas/consulta-minutas-disponiveis

Este endpoint permite a consulta de todos os templates disponíveis para serem utilizados no sistema de escrituração.

### **Request**
ENDPOINT /document_template/document_template
MÉTODO GET

### **Query Params**

| Campo                      | Tipo     | Descrição                                     | Obrigatório |
|----------------------------|----------|-----------------------------------------------|-------------|
| `document_type`            | string   | Tipo do documento                             | Não         |

---

## Response

STATUS 200

Response Body

```json
{
  "data" : [
    {
      "document_key": "a846cc4a-b542-4f66-9823-b6d5458bd127",
      "document_type": "adhesion_term"
    },
    {
      "document_key": "a846cc4a-b542-4f66-9823-b6d5458bd127",
      "document_type": "commercial_paper"
    }
  ]
}
```

### **Response Body Params**

| Campo            | Tipo     | Descrição                                        | Caracteres Máx. |
|------------------|----------|------------------------------------------------|-----------------|
| `document_key` * | string   | Chave única do template (UUID v4).            | 36              |
| `document_type` * | string   | Tipo do documento gerado. | 50              |

---

# Pré-visualizar Termo de Adesão

URL: /documentation/escrituracao/emissao-de-notas/geracao-minutas/gerar-minuta-adesao

Este endpoint permite a pré-visualização de uma minuta do Termo de Adesão para uma operação específica, utilizando um template predefinido.

---
## **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /preview_adhesion_term
MÉTODO POST

### **Path Params**

| Campo            | Tipo   | Descrição                                     | Caracteres Máx. |
|------------------|--------|-----------------------------------------------|-----------------|
| `OPERATION-KEY` *  | string | Chave única da operação (UUID v4).             | 36              |

Request Body

```json
{
  "template_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e"
}
```

### **Request Body Params**

| Campo                                | Tipo     | Descrição                                        | Obrigatório |
|--------------------------------------|----------|--------------------------------------------------|-------------|
| `template_key` *    | string   | Chave única do novo template a ser utilizado (UUID v4). | Sim |

## **Response**
STATUS 201

Response Body

```json
{
  "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127",
  "document_type": "adhesion_term",
  "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0"
}
```

### **Response Body Params**

| Campo            | Tipo     | Descrição                                        | Caracteres Máx. |
|------------------|----------|------------------------------------------------|-----------------|
| `operation_key` * | string   | Chave única da operação (UUID v4).            | 36              |
| `document_type` * | string   | Tipo do documento gerado. Sempre será `adhesion_term`. | 50              |
| `document_base64` * | string   | Conteúdo do documento gerado, codificado em Base64. | - |

---

# Pré-visualizar Termo Constitutivo

URL: /documentation/escrituracao/emissao-de-notas/geracao-minutas/gerar-minuta-contrato

Este endpoint permite a geração de uma minuta do Termo Constitutivo para uma operação específica, utilizando um template predefinido.

---

## **Request**
ENDPOINT /commercial_paper/operation/ OPERATION-KEY /preview_commercial_paper
MÉTODO POST

### **Path Params**

| Campo            | Tipo   | Descrição                                     | Caracteres Máx. |
|------------------|--------|-----------------------------------------------|-----------------|
| `OPERATION-KEY` *  | string | Chave única da operação (UUID v4).             | 36              |

Request Body

```json
{
  "template_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e"
}
```

### **Request Body Params**

| Campo                                | Tipo     | Descrição                                        | Obrigatório |
|--------------------------------------|----------|--------------------------------------------------|-------------|
| `template_key` *    | string   | Chave única do novo template a ser utilizado (UUID v4). | Sim |

## **Response**
STATUS 201

Response Body

```json
{
  "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127",
  "document_type": "commercial_paper",
  "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0"
}
```

### **Response Body Params**

| Campo            | Tipo     | Descrição                                        | Caracteres Máx. |
|------------------|----------|------------------------------------------------|-----------------|
| `operation_key` * | string   | Chave única da operação (UUID v4).            | 36              |
| `document_type` * | string   | Tipo do documento gerado. Sempre será `commercial_paper`. | 50              |
| `document_base64` * | string   | Conteúdo do documento gerado, codificado em Base64. | - |

---

# Introdução à Emissão de Notas Comerciais

URL: /documentation/escrituracao/emissao-de-notas/inicio

As notas comerciais são instrumentos financeiros utilizados por empresas para captar recursos diretamente no mercado. Este processo envolve diversas etapas, desde o cadastro de emissores e investidores, passando pela definição de condições financeiras, até a emissão formal dos títulos. Cada etapa é crucial para garantir a conformidade regulatória e a eficiência no processo de captação.

---

## Visão Geral do Processo de Emissão

O processo de emissão de notas comerciais é estruturado em várias etapas, que garantem transparência, segurança e controle. Abaixo, estão os principais passos do processo:

1. **Cadastro de Emissores e Investidores**  
   Empresas que desejam emitir notas comerciais e investidores interessados em adquirir esses títulos precisam ser cadastrados no sistema. O cadastro inclui informações detalhadas, como documentos e contas bancárias.

2. **Definição das Condições da Operação**  
   O emissor define as condições financeiras da operação, incluindo taxas de juros, número de parcelas, datas de emissão e vencimento, além de eventuais taxas e encargos.

3. **Simulação**  
   Antes da emissão formal, é realizada uma simulação para calcular os valores de emissão, o fluxo de parcelas e outros detalhes financeiros. Esta etapa permite ajustar as condições da operação de acordo com as necessidades do emissor e dos investidores.

4. **Cadastro de Partes Relacionadas e Documentação**  
   Inclui o registro de partes envolvidas, como garantidores e coobrigados, e o envio de documentos relevantes, como contratos e termos.

5. **Geração e Assinatura de Documentos**  
   São geradas as minutas dos principais documentos, como o **Termo de Adesão** e o **Termo Constitutivo**. Após aprovação, os documentos são enviados para assinatura eletrônica.

6. **Envio para Análise e Aprovação**  
   A operação é submetida para análise de compliance e backoffice, garantindo que todas as exigências regulatórias e contratuais sejam atendidas.

7. **Emissão Formal e Registro**  
   Após aprovação, as notas comerciais são formalmente emitidas e disponibilizadas para os investidores.

A partir das próximas páginas, exploraremos em detalhes cada etapa do processo de emissão de notas comerciais, incluindo endpoints e exemplos práticos para integrar seu sistema à API.

---

# Simulação de condições financeiras

URL: /documentation/escrituracao/emissao-de-notas/simulacao

Este endpoint permite simular as condições financeiras e o fluxo de pagamentos de uma operação

---

:::warning Atenção
 O **Request Body** deve conter uma combinação válida de parâmetros para ser processado. As combinações aceitas são: 
 - Valor de Emissão/Liberado + Taxa de Juros
 - Valor de Emissão/Liberado + Valor por Parcela
 - Valor por Parcela + Taxa de Juros
 - Valor de Emissão/Liberado + Taxa de Juros + Percentual de Amortização por Parcela.
:::

## Request
ENDPOINT /commercial_paper/simulation
MÉTODO POST

## Operação pré-fixada

Valor de emissão + Taxa

```json
{
    "interest_type": "pre_price_days",
    "financial_base_date": "2025-01-20",
    "issue_amount": 1000000,
    "number_of_installments": 5,
    "prefixed_interest_rate": {
        "interest_base": "calendar_days_365", 
        "monthly_rate": 0.05
    },
    "fine_delay_rate": {
        "interest_base": "calendar_days_365", 
        "monthly_rate": 0.01
    },
    "contract_fine_rate": 0.02,
    "fees": [
        {
            "amount": 5, 
            "amount_type": "percentage", 
            "fee_type": "structuring_fee",
            "type": "external"
        }
    ],
    "first_due_date_delay": 60,
}
```

Valor desembolsado + Taxa

```json
{
    "interest_type": "pre_price_days",
    "financial_base_date": "2025-01-20",
    "released_amount": 1000000,
    "number_of_installments": 5,
    "prefixed_interest_rate": {
        "interest_base": "calendar_days_365", 
        "monthly_rate": 0.05
    },
    "fine_delay_rate": {
        "interest_base": "calendar_days_365", 
        "monthly_rate": 0.01
    },
    "contract_fine_rate": 0.02,
    "fees": [
        {
            "amount": 5, 
            "amount_type": "percentage", 
            "fee_type": "bookkeeping_fee",
            "type": "external"
        }
    ],
    "first_due_date": "2026-01-31"
}
```

Valor da parcela + taxa de juros

```json
{
    "interest_type": "pre_price_days",
    "financial_base_date": "2025-01-20",
    "number_of_installments": 2,
    "installments": [
        {
            "due_date": "2026-01-01",
            "amount": 500000
        },
        {
            "due_date": "2026-02-01",
            "amount": 502004.01
        }
    ],
    "prefixed_interest_rate": {
        "interest_base": "calendar_days_365", 
        "monthly_rate": 0.05
    },
    "fine_delay_rate": {
        "interest_base": "calendar_days_365", 
        "monthly_rate": 0.01
    },
    "contract_fine_rate": 0.02,
    "fees": [
        {
            "amount": 5,
            "amount_type": "percentage",
            "fee_type": "structuring_fee",
            "type": "external"
        }
    ]
}
```

Valor de emissão + Percentual de amortização da parcela + taxa de juros

```json
{
    "interest_type": "pre_sac",
    "financial_base_date": "2025-01-20",
    "issue_amount": 1000000,
    "number_of_installments": 3,
    "installments": [
        {
            "due_date": "2026-01-01",
            "principal_amortization_percentage": 0.1
        },
        {
            "due_date": "2026-02-01",
            "principal_amortization_percentage": 0.1
        },
        {
            "due_date": "2026-03-01",
            "principal_amortization_percentage": 0.8
        }
    ],
    "prefixed_interest_rate": {
        "interest_base": "calendar_days_365", 
        "monthly_rate": 0.05
    },
    "fine_delay_rate": {
        "interest_base": "calendar_days_365", 
        "monthly_rate": 0.01
    },
    "contract_fine_rate": 0.02,
    "fees": [
        {
            "amount": 5,
            "amount_type": "percentage",
            "fee_type": "bookkeeping_fee",
            "type": "external"
        }
    ]
}
```

Valor de emissão + Valor das parcelas

```json
{
    "interest_type": "pre_price_days",
    "financial_base_date": "2025-01-20",
    "issue_amount": 700000,
    "number_of_installments": 2,
    "installments": [
        {
            "due_date": "2026-01-01",
            "amount": 500000
        },
        {
            "due_date": "2026-02-01",
            "amount": 502004.01
        }
    ],
    "prefixed_interest_rate": {
        "interest_base": "calendar_days_365", 
    },
    "fine_delay_rate": {
        "interest_base": "calendar_days_365", 
        "monthly_rate": 0.01
    },
    "contract_fine_rate": 0.02,
    "fees": [
        {
            "amount": 5,
            "amount_type": "percentage",
            "fee_type": "structuring_fee",
            "type": "external"
        }
    ]
}
```

## Operação pós-fixada

Valor de emissão + Taxa + Pós fixado

```json
{
    "interest_type": "post_price_days",
    "financial_base_date": "2025-01-20",
    "issue_amount": 1000000,
    "number_of_installments": 5,
    "prefixed_interest_rate": {
        "interest_base": "calendar_days_365", 
        "monthly_rate": 0.05
    },
    "fine_delay_rate": {
        "interest_base": "calendar_days_365", 
        "monthly_rate": 0.01
    },
    "contract_fine_rate": 0.02,
    "fees": [
        {
            "amount": 1000, 
            "amount_type": "absolute", 
            "fee_type": "structuring_fee",
            "type": "external"
        }
    ],
    "post_fixed_interest_rate": 100,
    "financial_index": "CDI"
}
```

Valor desembolsado + Taxa + Pós fixado

```json
{
    "interest_type": "post_price_days",
    "financial_base_date": "2025-01-20",
    "released_amount": 1000000,
    "number_of_installments": 5,
    "prefixed_interest_rate": {
        "interest_base": "calendar_days_365", 
        "monthly_rate": 0.05
    },
    "fine_delay_rate": {
        "interest_base": "calendar_days_365", 
        "monthly_rate": 0.01
    },
    "contract_fine_rate": 0.02,
    "fees": [
        {
            "amount": 5, 
            "amount_type": "percentage", 
            "fee_type": "bookkeeping_fee",
            "type": "external"
        }
    ],
    "post_fixed_interest_rate": 100,
    "financial_index": "CDI"
}
```

Valor da parcela + taxa de juros + Pós fixado

```json
{
    "interest_type": "post_price_days",
    "financial_base_date": "2025-01-20",
    "number_of_installments": 2,
    "installments": [
        {
            "due_date": "2026-01-01",
            "amount": 500000
        },
        {
            "due_date": "2026-02-01",
            "amount": 502004.01
        }
    ],
    "prefixed_interest_rate": {
        "interest_base": "calendar_days_365", 
        "monthly_rate": 0.05
    },
    "fine_delay_rate": {
        "interest_base": "calendar_days_365", 
        "monthly_rate": 0.01
    },
    "contract_fine_rate": 0.02,
    "fees": [
        {
            "amount": 5,
            "amount_type": "percentage",
            "fee_type": "structuring_fee",
            "type": "external"
        }
    ],
    "post_fixed_interest_rate": 100,
    "financial_index": "CDI"
}
```

Valor de emissão + Percentual de amortização da parcela + taxa de juros + Pós fixado

```json
{
    "interest_type": "post_sac",
    "financial_base_date": "2025-01-20",
    "issue_amount": 1000000,
    "number_of_installments": 3,
    "installments": [
        {
            "due_date": "2026-01-01",
            "principal_amortization_percentage": 0.1
        },
        {
            "due_date": "2026-02-01",
            "principal_amortization_percentage": 0.1
        },
        {
            "due_date": "2026-03-01",
            "principal_amortization_percentage": 0.8
        }
    ],
    "prefixed_interest_rate": {
        "interest_base": "calendar_days_365", 
        "monthly_rate": 0.05
    },
    "fine_delay_rate": {
        "interest_base": "calendar_days_365", 
        "monthly_rate": 0.01
    },
    "contract_fine_rate": 0.02,
    "fees": [
        {
            "amount": 5,
            "amount_type": "percentage",
            "fee_type": "structuring_fee",
            "type": "external"
        }
    ],
    "post_fixed_interest_rate": 100,
    "financial_index": "CDI"
}
```

Valor de emissão + Valor das parcelas + Pós fixado

```json
{
    "interest_type": "post_price_days",
    "financial_base_date": "2025-01-20",
    "issue_amount": 700000,
    "number_of_installments": 2,
    "installments": [
        {
            "due_date": "2026-01-01",
            "amount": 500000
        },
        {
            "due_date": "2026-02-01",
            "amount": 502004.01
        }
    ],
    "prefixed_interest_rate": {
        "interest_base": "calendar_days_365", 
    },
    "fine_delay_rate": {
        "interest_base": "calendar_days_365", 
        "monthly_rate": 0.01
    },
    "contract_fine_rate": 0.02,
    "fees": [
        {
            "amount": 5,
            "amount_type": "percentage",
            "fee_type": "structuring_fee",
            "type": "external"
        }
    ],
    "post_fixed_interest_rate": 100,
    "financial_index": "CDI"
}
```

### Request Body Params

| Campo                        | Tipo     | Descrição                                                                                                                       | Caracteres Máx. |
|------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------|
| `interest_type` *            | string   | Tipo de juros aplicado. | **[Enumeradores interest_type](#enumeradores-interest_type)** |
| `financial_base_date` *      | string   | Data base da operação (formato "YYYY-MM-DD").                                                                                   | -               |
| `released_amount`           | number   | Valor total liberado na operação.                                                                                               | -               |
| `issue_amount`           | number   | Valor de emissão da operação.   
| `number_of_installments` *   | integer  | Número total de parcelas.                                                                                                       | -               |
| `installments`    | array   | Objeto contendo detalhes sobre cada parcela.                                                                             | **[Objeto installments](#objeto-installments)** |
| `prefixed_interest_rate` *   | object   | Objeto contendo detalhes da taxa de juros prefixada.                                                                            | **[Objeto prefixed_interest_rate](#objeto-prefixed_interest_rate)** |
| `fine_delay_rate` *          | object   | Objeto contendo detalhes da multa por atraso.                                                                                   | **[Objeto fine_delay_rate](#objeto-fine_delay_rate)** |
| `contract_fine_rate` *       | number   | Multa contratual aplicada em percentual.                                                                                       | -               |
| `fees`                       | array    | Lista de taxas associadas à operação.                                                                                           | **[Objeto fees](#objeto-fees)** |
| `post_fixed_interest_rate`    | number   |  Valor da taxa pós fixada  prefixada.                                                                            | - |
| `financial_index`   | string   | Tipo de Taxa pós-fixada.                                                                            | **[Enumeradores financial_index](#enumeradores-financial_index)** |
| `first_due_date`    | date   | Data da primeira parcela | - |
| `first_due_date_delay`    | number   | Dias para o ínicio do pagamento da primeira parcela.                                                                            | - |

### Objeto installments

| Campo                        | Tipo     | Descrição                                                                                                                       |
|------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|
| `due_date` *            | string   | Data de vencimento da parcela (formato "YYYY-MM-DD"). |
| `amount`              | number   | Valor total da parcela.                                                                                                  |
| `principal_amortization_percentage`              | number   | Valor percentual amortizado do principal.                                                                                                  |

### Objeto prefixed_interest_rate

| Campo                        | Tipo     | Descrição                                                                                                                       | Caracteres Máx. |
|------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------|
| `interest_base` *            | string   | Base de cálculo para os juros. | **[Enumeradores interest_base](#enumeradores-interest_base)** |
| `daily_rate`              | number   | Taxa de juros diária aplicada.                                                                                                  | -               |
| `monthly_rate`              | number   | Taxa de juros mensal aplicada.                                                                                                  | -               |
| `annual_rate`              | number   | Taxa de juros anual aplicada.                                                                                                  | -               |

### Objeto fine_delay_rate

| Campo                        | Tipo     | Descrição                                                                                                                       | Caracteres Máx. |
|------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------|
| `interest_base` *            | string   | Base para cálculo da multa. | **[Enumeradores interest_base](#enumeradores-interest_base)** |
| `monthly_rate` *             | number   | Taxa de multa mensal.                                                                                                          | -               |

### Objeto fees

| Campo                        | Tipo     | Descrição                                                                                                                       | Caracteres Máx. |
|------------------------------|----------|---------------------------------------------------------------------------------------------------------------------------------|-----------------|
| `amount` *                   | number   | Valor da taxa aplicada.                                                                                                        | -               |
| `amount_type` *              | string   | Tipo do valor da taxa. | **[Enumeradores amount_type](#enumeradores-amount_type)** |
| `fee_type` *                 | string   | Tipo da taxa. | **[Enumeradores fee_type](#enumeradores-fee_type)** |
| `type` *                     | string   | Destinatário da taxa. | **[Enumeradores fee_recipient](#enumeradores-fee_recipient)** |

### Enumeradores interest_type

| Enum                | Descrição                                  |
|--------------------|------------------------------------------|
| `pre_price`       | Juros pré-fixados no modelo Price.       |
| `pre_price_days`  | Juros pré-fixados no modelo Price por dias corridos. |
| `pre_sac`         | Juros pré-fixados no modelo SAC.         |
| `post_sac`        | Juros pós-fixados no modelo SAC.         |
| `post_price_days` | Juros pós-fixados no modelo Price por dias corridos. |

### Enumeradores financial_index

| Enum                | Descrição                                  |
|--------------------|------------------------------------------|
| `CDI`       | Pós fixado de CDI       |
| `IPCA`  | Pós fixado de IPCA |
| `IGPM`         | Pós fixado de IGPM         |

### Enumeradores interest_base

| Enum                | Descrição                                  |
|--------------------|------------------------------------------|
| `calendar_days`    | Base de dias corridos.                   |
| `calendar_days_365`| Base de 365 dias corridos.               |
| `workdays`        | Base de dias úteis.                      |

### Enumeradores amount_type

| Enum         | Descrição                   |
|-------------|---------------------------|
| `percentage` | Valor em percentual.       |
| `absolute`   | Valor absoluto em moeda.   |

### Enumeradores fee_type

| Enum                                | Descrição                                 |
|-------------------------------------|-------------------------------------------|
| `bookkeeping_fee`                   | Taxa de escrituração financiada.          |
| `structuring_fee`                   | Taxa de estruturação financiada.          |

### Enumeradores fee_recipient

| Enum       | Descrição                                               |
|-----------|-------------------------------------------------------|
| `internal` | Taxa paga ao escriturador.                           |
| `external` | Rebate pago ao originador.                           |

## Response
STATUS 200

Response Body

```json
{
    "financial_base_date": "2025-01-20",
    "issue_amount": 1075268.82,
    "released_amount": 1000000.0,
    "issue_quantity": 1075268,
    "unit_price": 1.00000076,
    "cet": 7.7,
    "annual_cet": 143.55,
    "number_of_installments": 5,
    "prefixed_interest_rate": {
        "interest_base": "calendar_days_365",
        "monthly_rate": 0.05,
        "daily_rate": 0.0016053474,
        "annual_rate": 0.795856326
    },
    "fees": [
        {
            "amount": 2.0,
            "fee_amount": 21505.38,
            "amount_type": "percentage",
            "fee_type": "bookkeeping_fee",
            "type": "internal"
        },
        {
            "amount": 5.0,
            "fee_amount": 53763.44,
            "amount_type": "percentage",
            "fee_type": "structuring_fee",
            "type": "external"
        }
    ],
    "installments": [
        {
            "installment_number": 1,
            "workdays": 23,
            "calendar_days": 31,
            "principal_amortization_amount": 193292.79655634,
            "principal_amortization_unit_price": 0.17976244,
            "interest_amount": 54820.37344366,
            "amount": 248113.17,
            "due_principal": 1075268.82,
            "due_interest": 0.0,
            "due_date": "2025-02-20",
            "has_interest": true
        },
        {
            "installment_number": 2,
            "workdays": 18,
            "calendar_days": 28,
            "principal_amortization_amount": 207597.32873049,
            "principal_amortization_unit_price": 0.19306566,
            "interest_amount": 40515.84126951,
            "amount": 248113.17,
            "due_principal": 881976.02344366,
            "due_interest": 0.0,
            "due_date": "2025-03-20",
            "has_interest": true
        },
        {
            "installment_number": 3,
            "workdays": 21,
            "calendar_days": 33,
            "principal_amortization_amount": 211453.91638185,
            "principal_amortization_unit_price": 0.19665229,
            "interest_amount": 36659.25361815,
            "amount": 248113.17,
            "due_principal": 674378.69471317,
            "due_interest": 0.0,
            "due_date": "2025-04-22",
            "has_interest": true
        },
        {
            "installment_number": 4,
            "workdays": 19,
            "calendar_days": 28,
            "principal_amortization_amount": 226847.52746545,
            "principal_amortization_unit_price": 0.21096836,
            "interest_amount": 21265.64253455,
            "amount": 248113.17,
            "due_principal": 462924.77833132,
            "due_interest": 0.0,
            "due_date": "2025-05-20",
            "has_interest": true
        },
        {
            "installment_number": 5,
            "workdays": 22,
            "calendar_days": 31,
            "principal_amortization_amount": 236077.25086587,
            "principal_amortization_unit_price": 0.21955201,
            "interest_amount": 12035.91913413,
            "amount": 248113.17,
            "due_principal": 236077.25086587,
            "due_interest": 0.0,
            "due_date": "2025-06-20",
            "has_interest": true
        }
    ],
    "fine_delay_rate": {
        "interest_base": "calendar_days_365",
        "monthly_rate": 0.01
    },
    "contract_fine_rate": 0.02
}
```

### Response Body Params

| Campo                        | Tipo     | Descrição                                                                                               | Caracteres Máx. |
|------------------------------|----------|---------------------------------------------------------------------------------------------------------|-----------------|
| `financial_base_date` *      | string   | Data base financeira da operação (formato "YYYY-MM-DD").                                                | -               |
| `issue_amount` *             | number   | Valor total emitido da operação.                                                                        | -               |
| `released_amount` *          | number   | Valor líquido liberado na operação.                                                                     | -               |
| `issue_quantity` *           | integer  | Quantidade total de unidades emitidas.                                                                  | -               |
| `unit_price` *               | number   | Preço unitário da emissão.                                                                              | -               |
| `cet` *                      | number   | Custo Efetivo Total (CET) em percentual.                                                                | -               |
| `annual_cet` *               | number   | CET anual em percentual.                                                                                | -               |
| `number_of_installments` *   | integer  | Número total de parcelas.                                                                               | -               |
| `prefixed_interest_rate` *   | object   | Objeto contendo detalhes da taxa de juros prefixada.                                                    | **[Objeto prefixed_interest_rate](#objeto-response-prefixed_interest_rate)** |
| `fees`                       | array    | Lista de taxas associadas à operação.                                                                   | **[Objeto fees](#objeto-fees)** |
| `installments`               | array    | Lista de detalhes das parcelas geradas na operação.                                                     | **[Objeto installments](#objeto-response-installments)** |
| `fine_delay_rate` *          | object   | Objeto contendo detalhes da multa por atraso.                                                           | **[Objeto fine_delay_rate](#objeto-fine_delay_rate)** |
| `contract_fine_rate` *       | number   | Multa contratual aplicada em percentual.                                                                | -               |

### Objeto Response prefixed_interest_rate

| Campo          | Tipo     | Descrição                                                   | Caracteres Máx. |
|---------------|----------|------------------------------------------------------------|-----------------|
| `interest_base` * | string  | Base de cálculo para os juros. | **[Enumeradores interest_base](#enumeradores-interest_base)** |
| `monthly_rate` *  | number  | Taxa de juros mensal aplicada.                            | -               |
| `daily_rate` *    | number  | Taxa de juros diária aplicada.                            | -               |
| `annual_rate` *   | number  | Taxa de juros anual aplicada.                             | -               |

### Objeto fees

| Campo      | Tipo    | Descrição                                                  | Caracteres Máx. |
|------------|--------|------------------------------------------------------------|-----------------|
| `amount` *  | number | Valor percentual da taxa.                                | -               |
| `fee_amount` * | number | Valor monetário correspondente à taxa.                   | -               |
| `amount_type` * | string  | Tipo do valor da taxa. | **[Enumeradores amount_type](#enumeradores-amount_type)** |
| `fee_type` * | string  | Tipo da taxa. | **[Enumeradores fee_type](#enumeradores-fee_type)** |
| `type` * | string  | Destinatário da taxa. | **[Enumeradores fee_recipient](#enumeradores-fee_recipient)** |

### Objeto Response installments

| Campo                       | Tipo     | Descrição                                              |
|----------------------------|----------|--------------------------------------------------------|
| `installment_number` *      | integer  | Número da parcela.                                    |
| `workdays` *               | integer  | Dias úteis até o vencimento da parcela.               |
| `calendar_days` *          | integer  | Dias corridos até o vencimento da parcela.            |
| `principal_amortization_amount` * | number  | Valor amortizado do principal.                         |
| `principal_amortization_unit_price` * | number  | Valor amortizado por unidade.                          |
| `interest_amount` *        | number   | Valor dos juros aplicados na parcela.                 |
| `amount` *                 | number   | Valor total da parcela.                               |
| `due_date` *               | string   | Data de vencimento da parcela (formato "YYYY-MM-DD"). |

---

# Cadastro de Operação de Debênture

URL: /documentation/escrituracao/emissao-debentures/cadastro-operacao

Este endpoint cria uma operação de Debênture completa em uma única requisição.

:::info
O objeto `financial` é **obrigatório** e deve ser enviado já calculado, pois este endpoint não executa a simulação financeira. O emissor e sua conta bancária devem estar previamente cadastrados.
:::

---

## **Request**

ENDPOINT /debenture/create_operation
MÉTODO POST

O corpo da requisição vai desde um **payload com os campos obrigatórios** (incluindo o objeto financeiro) até um **payload completo** que inclui também partes relacionadas. Veja as duas variações abaixo.

Payload com os campos obrigatórios

```json
{
    "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814",
    "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e",
    "issue_number": 10,
    "issue_series": 1,
    "issue_date": "2025-01-20",
    "investors": [
        {
            "investor_key": "70b1b638-ca56-4eb3-9a88-2fd5ffd077a7",
            "bank_account": {
                "account_number": "33400254",
                "account_digit": "3",
                "account_branch": "0001",
                "financial_institution_code_number": "329",
                "financial_institution_ispb": "32402502",
                "account_type": "checking"
            }
        }
    ],
    "financial": {
        "financial_base_date": "2025-01-20",
        "interest_type": "pre_price_days",
        "issue_amount": 1075268.82,
        "issue_quantity": 1075268,
        "unit_price": 1.0000007626,
        "released_amount": 1075268.82,
        "cet": 7.7,
        "annual_cet": 143.55,
        "first_due_date": "2025-02-20",
        "number_of_installments": 5,
        "prefixed_interest_rate": {
            "interest_base": "calendar_days_365",
            "monthly_rate": 0.05,
            "daily_rate": 0.0016053474,
            "annual_rate": 0.795856326
        },
        "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 },
        "contract_fine_rate": 0.02,
        "fees": [
            { "amount": 2.0, "fee_amount": 21505.38, "amount_type": "percentage", "fee_type": "bookkeeping_fee", "type": "internal" }
        ],
        "installments": [
            {
                "installment_number": 1,
                "due_date": "2025-02-20",
                "amount": 248113.17,
                "principal_amortization_amount": 193292.79655634,
                "principal_amortization_unit_price": 1.02,
                "interest_amount": 0.0,
                "calendar_days": 31,
                "workdays": 23
            }
        ]
    }
}
```

Payload completo (com partes relacionadas)

```json
{
    "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814",
    "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e",
    "issue_number": 10,
    "issue_series": 1,
    "contract_number": "DEB-2025-0001",
    "issue_date": "2025-01-20",
    "signature_method": "certifiqi",
    "investors": [
        {
            "investor_key": "70b1b638-ca56-4eb3-9a88-2fd5ffd077a7",
            "subscription_percentage": 100,
            "bank_account": {
                "account_number": "33400254",
                "account_digit": "3",
                "account_branch": "0001",
                "financial_institution_code_number": "329",
                "financial_institution_ispb": "32402502",
                "account_type": "checking"
            }
        }
    ],
    "financial": {
        "financial_base_date": "2025-01-20",
        "interest_type": "pre_price_days",
        "issue_amount": 1075268.82,
        "issue_quantity": 1075268,
        "unit_price": 1.0000007626,
        "released_amount": 1075268.82,
        "cet": 7.7,
        "annual_cet": 143.55,
        "first_due_date": "2025-02-20",
        "number_of_installments": 5,
        "prefixed_interest_rate": {
            "interest_base": "calendar_days_365",
            "monthly_rate": 0.05,
            "daily_rate": 0.0016053474,
            "annual_rate": 0.795856326
        },
        "fine_delay_rate": { "interest_base": "calendar_days_365", "monthly_rate": 0.01 },
        "contract_fine_rate": 0.02,
        "fees": [
            { "amount": 2.0, "fee_amount": 21505.38, "amount_type": "percentage", "fee_type": "bookkeeping_fee", "type": "internal" }
        ],
        "installments": [
            {
                "installment_number": 1,
                "due_date": "2025-02-20",
                "amount": 248113.17,
                "principal_amortization_amount": 193292.79655634,
                "principal_amortization_unit_price": 1.02,
                "interest_amount": 0.0,
                "calendar_days": 31,
                "workdays": 23
            }
        ]
    },
    "related_party_list": [
        {
            "person_type": "legal",
            "name": "Garantidora S.A.",
            "document_number": "12.345.678/0001-90",
            "trading_name": "Garantidora",
            "cnae_code": "64.62-0-00",
            "company_type": "sa",
            "foundation_date": "2010-05-01",
            "street": "Av. Paulista",
            "number": "1000",
            "neighborhood": "Bela Vista",
            "postal_code": "01310-100",
            "city": "São Paulo",
            "state": "SP",
            "role_type": "guarantor"
        },
        {
            "person_type": "natural",
            "name": "João da Silva",
            "document_number": "123.456.789-00",
            "street": "Rua das Flores",
            "number": "123",
            "neighborhood": "Centro",
            "postal_code": "01001-000",
            "city": "São Paulo",
            "state": "SP",
            "role_type": "solidary_debtor",
            "is_pep": false
        }
    ]
}
```

### **Request Body Params**

| Campo               | Tipo    | Descrição                                            | Caracteres Máx.            |
| ------------------- | ------- | ---------------------------------------------------- | -------------------------- |
| `tenant_key` *      | string  | Chave única do tenant.                               | -                          |
| `issuer_key` *      | string  | Chave única do emissor (previamente cadastrado).     | -                          |
| `issue_number` *    | integer | Número da emissão.                                   | -                          |
| `issue_series` *    | integer | Série da emissão.                                    | -                          |
| `issue_date` *      | string  | Data de emissão da operação (formato "YYYY-MM-DD").  | -                          |
| `signature_method`  | string  | Método de assinatura utilizado na operação. Opcional; quando omitido, assume `certifiqi`. | **[Enumeradores signature_method](#enumeradores-signature_method)** |
| `investors` *       | array   | Lista de investidores envolvidos.                    | **Objeto investors**       |
| `financial` *       | object  | Dados financeiros já calculados da operação.         | **Objeto financial**       |
| `contract_number`   | string  | Número do contrato.                                  | -                          |
| `related_party_list` | array  | Partes relacionadas da operação (garantidores, devedores, etc.). | **Objeto related_party** |

### Objeto investors

| Campo                       | Tipo   | Descrição                                                |
| --------------------------- | ------ | -------------------------------------------------------- |
| `investor_key` *            | string | Chave única do investidor (previamente cadastrado).      |
| `bank_account` *            | object | Conta bancária do investidor (**Objeto bank_account**).  |
| `subscription_percentage`   | number | Percentual de subscrição.                                |
| `subscription_quantity`     | number | Quantidade subscrita.                                    |

### Objeto bank_account

| Campo                                 | Tipo   | Descrição                                                     |
| ------------------------------------- | ------ | ------------------------------------------------------------- |
| `account_number` *                    | string | Número da conta bancária.                                     |
| `account_digit` *                     | string | Dígito da conta bancária.                                     |
| `account_branch` *                    | string | Agência da conta bancária.                                    |
| `financial_institution_code_number`   | string | Código da instituição financeira.                            |
| `financial_institution_ispb` *        | string | Código ISPB da instituição financeira.                       |
| `account_type` *                      | string | Tipo da conta (`checking`, `savings`, `salary`, `payment`).  |

### Objeto financial

| Campo                       | Tipo    | Descrição                                          |
| --------------------------- | ------- | -------------------------------------------------- |
| `financial_base_date` *     | string  | Data base financeira (formato "YYYY-MM-DD").       |
| `interest_type` *           | string  | Tipo de juros.                                     |
| `issue_amount`              | number  | Valor total emitido.                               |
| `issue_quantity`            | integer | Quantidade de unidades emitidas.                   |
| `unit_price`                | number  | Preço unitário da emissão.                         |
| `released_amount`           | number  | Valor líquido liberado.                            |
| `cet` / `annual_cet`        | number  | Custo Efetivo Total (mensal e anual), em percentual. |
| `number_of_installments` *  | integer | Número de parcelas.                                |
| `prefixed_interest_rate` *  | object  | Taxa de juros prefixada.                           |
| `fine_delay_rate`           | object  | Taxa de multa por atraso.                          |
| `contract_fine_rate`        | number  | Multa contratual em percentual.                    |
| `fees`                      | array   | Lista de taxas.                                    |
| `installments`              | array   | Lista de parcelas já calculadas.                   |

### Objeto related_party

Cada item de `related_party_list` representa uma parte envolvida na operação.

| Campo             | Tipo    | Descrição                                                     |
| ----------------- | ------- | ------------------------------------------------------------- |
| `person_type` *   | string  | Tipo de pessoa (`natural` para PF, `legal` para PJ).         |
| `name` *          | string  | Nome da parte relacionada.                                   |
| `document_number` * | string | CPF (PF) ou CNPJ (PJ).                                      |
| `role_type` *     | string  | Papel da parte na operação. **[Enumeradores role_type](#enumeradores-role_type)** |
| `street` *        | string  | Logradouro.                                                 |
| `number` *        | string  | Número do endereço.                                         |
| `neighborhood`    | string  | Bairro.                                                     |
| `postal_code` *   | string  | CEP (formato "00000-000").                                  |
| `city` *          | string  | Cidade.                                                     |
| `state` *         | string  | UF (2 letras).                                              |
| `complement`      | string  | Complemento do endereço.                                    |
| `is_pep`          | boolean | (PF) Indica se é Pessoa Politicamente Exposta.              |
| `marital_status`  | string  | (PF) Estado civil.                                          |
| `property_system` | string  | (PF) Regime de bens.                                        |
| `birthdate`       | string  | (PF) Data de nascimento.                                    |
| `mother_name`     | string  | (PF) Nome da mãe.                                           |
| `occupation`      | string  | (PF) Ocupação.                                              |
| `trading_name`    | string  | (PJ) Nome fantasia.                                         |
| `cnae_code`       | string  | (PJ) Código CNAE (formato "00.00-0-00").                    |
| `company_type`    | string  | (PJ) Tipo de empresa.                                       |
| `foundation_date` | string  | (PJ) Data de fundação.                                      |

:::warning Atenção
Os campos obrigatórios variam conforme o `person_type`:
- **Pessoa física (`natural`)**: além dos campos comuns, `is_pep` é obrigatório.
- **Pessoa jurídica (`legal`)**: além dos campos comuns, `trading_name`, `cnae_code`, `company_type` e `foundation_date` são obrigatórios.
:::

### Enumeradores role_type

| Enum | Descrição |
|------|-----------|
| `issuer` | Emissor. |
| `investor` | Investidor. |
| `cosigner` | Coobrigado. |
| `fiduciary_debtor` | Devedor fiduciante. |
| `solidary_debtor` | Devedor solidário. |
| `guarantor` | Avalista. |
| `bonafide_depositary` | Fiel depositário. |
| `intervening_guarantor` | Interveniente garantidor. |
| `intervening_consentor` | Interveniente anuente. |
| `intervening_discharger` | Interveniente quitante. |
| `assignor` | Cedente. |
| `endorser` | Endossante. |
| `consulting` | Consultoria. |
| `fund_administrator` | Administrador do fundo. |
| `fund_representative` | Representante do fundo. |
| `company_representative` | Representante da empresa. |
| `attestant` | Anuente / testemunha. |
| `debtor` | Devedor. |
| `bestowal` | Outorgante. |
| `manager` | Gestor. |

:::tip
Garantias e lastro são enviados em um **endpoint separado**, após a criação da operação. Consulte a página **Envio de garantia** desta seção.
:::

### Enumeradores signature_method

| Enum | Descrição |
|------|-----------|
| `certifiqi` | Valor padrão. A operação é enviada ao serviço de assinatura; um envelope de assinatura é criado e o cliente recebe a URL de assinatura (`signature_url`). |
| `qi_sign` | A operação é enviada ao serviço de assinatura; um envelope de assinatura é criado e o cliente recebe a URL de assinatura (`signature_url`). Permite também a consulta dos signatários da operação. |

## **Response**

STATUS 201

Response Body

```json
{
    "tenant_key": "1d29d606-649a-487f-af1c-c0f5cb3e9814",
    "operation_key": "a846cc4a-b542-4f66-9823-b6d5458bd127",
    "operation_status": "finished",
    "issuer_key": "48e2c597-f2ca-487e-9f06-2b628ecb831e",
    "issuer_name": "Dynamic Enterprises",
    "issuer_document_number": "28980395000155",
    "issue_number": 10,
    "issue_series": 1,
    "related_party_list": [ ... ],
    "financial": { ... }
}
```

A resposta retorna o JSON completo da operação criada, incluindo `operation_key`, listas de investidores e partes relacionadas, e o objeto financeiro calculado.

---

# Envio de Documento

URL: /documentation/escrituracao/emissao-debentures/envio-documento

Este endpoint permite o **envio de um documento** e retorna o `document_key` que o identifica. Esse `document_key` é utilizado para referenciar documentos em outros endpoints — por exemplo, no `collateral_document_key` e nos `additional_documents` do [Envio de garantia](./envio-garantia.md).

---

## **Request**

ENDPOINT /debenture/upload
MÉTODO POST

Request Body

```json
{
    "document_base64": "string_b64"
}
```

### **Request Body Params**

| Campo             | Tipo   | Descrição                                    | Obrigatório |
|-------------------|--------|----------------------------------------------|-------------|
| `document_base64` * | string | Conteúdo do documento codificado em Base64. | Sim         |
| `document_name`   | string | Nome do documento.                           | -           |

## **Response**

STATUS 201

Response Body

```json
{
    "document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b"
}
```

### **Response Body Params**

| Campo          | Tipo   | Descrição                                       | Caracteres Máx. |
|----------------|--------|-------------------------------------------------|-----------------|
| `document_key` * | string | Chave única do documento enviado (UUID v4).    | 36              |

---

---

# Enviar Documento Externo da Operação

URL: /documentation/escrituracao/emissao-debentures/envio-documento-externo

Este endpoint permite enviar documentos assinados de forma externa para o sistema de escrituração, enviando um base64 que será analisado e aprovado pelo escriturador.

:::warning Aviso
Este endpoint deve ser usado apenas para operações que utilizam o tipo de assinatura **client_side** ou para envio da ata de aprovação de empresas do tipo SA ou Cooperativas. Para o fluxo via QI Sign ou Certifiqi, os contratos são gerados de forma normal.
:::

---

## Enviar Documento Assinado (POST)

### Request

ENDPOINT /debenture/operation/ OPERATION-KEY /upload_signed_document
MÉTODO POST

### Path Params

| Campo           | Tipo   | Descrição                            | Caracteres |
|-----------------|--------|--------------------------------------|------------|
| `OPERATION-KEY` | string | Chave única da operação (UUID v4).   | 36         |

---

### Request Body

Request Body

```json
{
    "contract_base64": "image_b64",
    "contract_type": "debenture"
}
```

### Request Body Params

| Campo               | Tipo   | Descrição                   | Caracteres Máx.                                              |
|---------------------|--------|-----------------------------|-------------------------------------------------------------|
| `contract_type` *   | string | Tipo de documento assinado. | **[Enumeradores contract_type](#enumeradores-contract_type)** |
| `contract_base64` * | string | Documento assinado em base64. | -                                                         |

### Enumeradores contract_type

| Enum                | Descrição                                  |
|---------------------|--------------------------------------------|
| `debenture` | Escritura de emissão da debênture. |
| `adhesion_term` | Termo de adesão da debênture. |
| `sa_minute` | Ata de aprovação de emissão da debênture para empresa **SA**. |
| `ltda_minute` | Ata de aprovação de emissão da debênture para empresa **LTDA**. |
| `cop_minute` | Ata de aprovação de emissão da debênture para **Cooperativa**. |

### Response

O corpo da resposta é um JSON completo da operação atualizada.

---

---

# Envio de Garantia na Operação

URL: /documentation/escrituracao/emissao-debentures/envio-garantia

Este endpoint permite a **adição de garantias (collateral)** a uma operação de Debênture. A garantia é submetida para assinatura junto com os documentos da operação. Cada tipo de garantia (`collateral_type`) possui suas próprias regras de documentos obrigatórios, listadas abaixo.

:::info Origem do `document_key`
Os campos `collateral_document_key` e `document_key` (em `additional_documents`) referenciam documentos previamente enviados. Cada chave é obtida no endpoint [Envio de documento](./envio-documento.md) (`POST /debenture/upload`), que recebe o arquivo em Base64 e retorna o `document_key` correspondente.
:::

---

## **Request**

ENDPOINT /debenture/operation/ OPERATION-KEY /collateral
MÉTODO POST

### Path Params

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `OPERATION-KEY` * | string | Chave única da operação (UUID v4). | 36 |

---

## Tipos de garantia

:::warning
Documentos marcados como **obrigatórios** são exigidos para o respectivo tipo de garantia.
:::

### Alienação fiduciária de imóvel (`fiduciary_alienation_property`)

Request Body

```json
{
    "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b",
    "collateral_type": "fiduciary_alienation_property",
    "additional_documents": [
        { "document_type": "property_appraisal_report", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" },
        { "document_type": "property_registration_updated", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" },
        { "document_type": "property_full_content_certificate", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }
    ]
}
```

#### Tipos de documentos

| Enum | Descrição | Obrigatório |
|------|-----------|-------------|
| `property_appraisal_report` | Laudo de avaliação do imóvel. | Sim |
| `property_registration_updated` | Matrícula atualizada. | Sim |
| `property_full_content_certificate` | Certidão de inteiro teor da matrícula. | Sim |
| `property_insurance_policy` | Apólice de seguro (se exigível no contrato). | - |
| `others` | Outros documentos. | - |

### Alienação fiduciária de veículo (`fiduciary_alienation_vehicle`)

Request Body

```json
{
    "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b",
    "collateral_type": "fiduciary_alienation_vehicle",
    "additional_documents": [
        { "document_type": "vehicle_appraisal_report", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" },
        { "document_type": "vehicle_inspection_report", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" },
        { "document_type": "vehicle_crv_certificate", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }
    ]
}
```

#### Tipos de documentos

| Enum | Descrição | Obrigatório |
|------|-----------|-------------|
| `vehicle_appraisal_report` | Laudo de avaliação do veículo ou Tabela FIPE. | Sim |
| `vehicle_inspection_report` | Laudo de vistoria. | Sim |
| `vehicle_crv_certificate` | CRLV atualizado. | Sim |
| `others` | Outros documentos. | - |

### Alienação fiduciária de aeronave (`fiduciary_alienation_aircraft`)

Request Body

```json
{
    "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b",
    "collateral_type": "fiduciary_alienation_aircraft",
    "additional_documents": [
        { "document_type": "aircraft_certificate_anac", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" },
        { "document_type": "aircraft_rab_consult", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" },
        { "document_type": "aircraft_insurance_policy", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" },
        { "document_type": "aircraft_appraisal_report", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }
    ]
}
```

#### Tipos de documentos

| Enum | Descrição | Obrigatório |
|------|-----------|-------------|
| `aircraft_certificate_anac` | Certificado de matrícula - ANAC. | Sim |
| `aircraft_rab_consult` | Consulta no Registro Aeronáutico Brasileiro (RAB). | Sim |
| `aircraft_insurance_policy` | Apólice de seguro - beneficiário o fundo. | Sim |
| `aircraft_appraisal_report` | Laudo de avaliação da aeronave. | Sim |
| `others` | Outros documentos. | - |

### Alienação fiduciária de equipamentos/produtos/estoque (`fiduciary_alienation_equipment`)

Request Body

```json
{
    "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b",
    "collateral_type": "fiduciary_alienation_equipment",
    "additional_documents": [
        { "document_type": "equipment_purchase_invoice", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" },
        { "document_type": "equipment_appraisal_report", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }
    ]
}
```

#### Tipos de documentos

| Enum | Descrição | Obrigatório |
|------|-----------|-------------|
| `equipment_purchase_invoice` | Nota fiscal de compra. | Sim |
| `equipment_appraisal_report` | Laudo de avaliação de equipamentos. | Sim |
| `equipment_insurance_policy` | Apólice de seguro de equipamentos (se exigível). | - |
| `fiduciary_depositary_declaration` | Declaração de fiel depositário. | - |
| `others` | Outros documentos. | - |

### Alienação fiduciária de obras de arte (`fiduciary_alienation_artwork`)

Request Body

```json
{
    "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b",
    "collateral_type": "fiduciary_alienation_artwork",
    "additional_documents": [
        { "document_type": "artwork_appraisal_report", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" },
        { "document_type": "artwork_storage_certificate", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }
    ]
}
```

#### Tipos de documentos

| Enum | Descrição | Obrigatório |
|------|-----------|-------------|
| `artwork_appraisal_report` | Laudo de avaliação de obras de arte. | Sim |
| `artwork_storage_certificate` | Certificado de adequação do local de armazenamento. | Sim |
| `artwork_insurance_policy` | Apólice de seguro (se exigível). | - |
| `others` | Outros documentos. | - |

### Alienação fiduciária de títulos e valores mobiliários (`fiduciary_alienation_securities`)

Request Body

```json
{
    "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b",
    "collateral_type": "fiduciary_alienation_securities",
    "additional_documents": [
        { "document_type": "securities_negotiation_block", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }
    ]
}
```

#### Tipos de documentos

| Enum | Descrição | Obrigatório |
|------|-----------|-------------|
| `securities_negotiation_block` | Bloqueio para negociação junto ao custodiante. | Sim |
| `securities_registration_gravame` | Registro do gravame. | - |
| `others` | Outros documentos. | - |

### Alienação fiduciária / penhor de ações e cotas (`fiduciary_assignment_shares`)

Request Body

```json
{
    "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b",
    "collateral_type": "fiduciary_assignment_shares",
    "additional_documents": [
        { "document_type": "share_registration_book", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }
    ]
}
```

#### Tipos de documentos

| Enum | Descrição | Obrigatório |
|------|-----------|-------------|
| `share_registration_book` | Livro de registro de ações nominativas com anotação do gravame. | Sim |
| `others` | Outros documentos. | - |

### Hipoteca de imóveis (`mortgage_property`)

Request Body

```json
{
    "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b",
    "collateral_type": "mortgage_property",
    "additional_documents": [
        { "document_type": "property_appraisal_report", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" },
        { "document_type": "property_registration", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" },
        { "document_type": "property_full_content_certificate", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }
    ]
}
```

#### Tipos de documentos

| Enum | Descrição | Obrigatório |
|------|-----------|-------------|
| `property_appraisal_report` | Laudo de avaliação do imóvel. | Sim |
| `property_registration` | Registro de propriedade atualizado. | Sim |
| `property_full_content_certificate` | Certidão de inteiro teor da matrícula. | Sim |
| `property_insurance_policy` | Apólice de seguro (se exigível no contrato). | - |
| `others` | Outros documentos. | - |

### Hipoteca de embarcações (`mortgage_ship`)

Request Body

```json
{
    "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b",
    "collateral_type": "mortgage_ship",
    "additional_documents": [
        { "document_type": "ship_registration", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" },
        { "document_type": "ship_appraisal_report", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }
    ]
}
```

#### Tipos de documentos

| Enum | Descrição | Obrigatório |
|------|-----------|-------------|
| `ship_registration` | Registro de propriedade da embarcação atualizado. | Sim |
| `ship_appraisal_report` | Laudo de avaliação da embarcação. | Sim |
| `ship_insurance_policy` | Apólice de seguro da embarcação (se exigível). | - |
| `others` | Outros documentos. | - |

### Aval (`guarantor`)

Request Body

```json
{
    "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b",
    "collateral_type": "guarantor",
    "additional_documents": [
        { "document_type": "guarantor_civil_status_declaration", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }
    ]
}
```

#### Tipos de documentos

| Enum | Descrição | Obrigatório |
|------|-----------|-------------|
| `guarantor_civil_status_declaration` | Declaração de estado civil do avalista. | Sim |
| `guarantor_personal_document` | Documento pessoal do avalista. | - |
| `guarantor_income_tax_declaration` | Declaração de imposto de renda do avalista. | - |
| `others` | Outros documentos. | - |

### Fiança (fiador) (`surety`)

Request Body

```json
{
    "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b",
    "collateral_type": "surety",
    "additional_documents": [
        { "document_type": "surety_civil_status_declaration", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" },
        { "document_type": "surety_personal_document", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" },
        { "document_type": "surety_income_tax_declaration", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }
    ]
}
```

#### Tipos de documentos

| Enum | Descrição | Obrigatório |
|------|-----------|-------------|
| `surety_civil_status_declaration` | Declaração de estado civil do fiador. | Sim |
| `surety_personal_document` | Documento pessoal do fiador. | Sim |
| `surety_income_tax_declaration` | Declaração de imposto de renda do fiador. | Sim |
| `others` | Outros documentos. | - |

### Seguro (`insurance`)

Request Body

```json
{
    "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b",
    "collateral_type": "insurance",
    "additional_documents": [
        { "document_type": "insurance_policy_endorsed", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" },
        { "document_type": "insurance_policy_with_expiration_and_renewal", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }
    ]
}
```

#### Tipos de documentos

| Enum | Descrição | Obrigatório |
|------|-----------|-------------|
| `insurance_policy_endorsed` | Apólice de seguro endossada. | Sim |
| `insurance_policy_with_expiration_and_renewal` | Apólice de seguro com vigência e renovação. | Sim |
| `others` | Outros documentos. | - |

### Monitoramento de garantias (`monitoring_guarantee`)

Request Body

```json
{
    "collateral_document_key": "25dd10b8-7364-4abe-b0e8-0e419b04194b",
    "collateral_type": "monitoring_guarantee",
    "additional_documents": [
        { "document_type": "guarantee_contract", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" },
        { "document_type": "guarantee_agent_contract", "document_key": "1bffe8c6-0a54-4854-b693-745b3dba9e04" }
    ]
}
```

#### Tipos de documentos

| Enum | Descrição | Obrigatório |
|------|-----------|-------------|
| `guarantee_contract` | Contrato de garantia. | Sim |
| `guarantee_agent_contract` | Contrato de agente de garantia. | Sim |
| `others` | Outros documentos. | - |

---

## Request Body Params

| Campo | Tipo | Descrição | Obrigatório |
|-------|------|-----------|-------------|
| `collateral_document_key` * | string | Chave do documento do instrumento de garantia. | Sim |
| `collateral_type` * | string | Tipo da garantia. | **[Enumeradores collateral_type](#enumeradores-collateral_type)** |
| `additional_documents` | array | Documentos adicionais da garantia. | - |

### additional_documents

| Campo | Tipo | Descrição | Obrigatório |
|-------|------|-----------|-------------|
| `document_key` * | string | Chave do documento. | Sim |
| `document_type` * | string | Tipo do documento. | Sim |

### Enumeradores collateral_type

| Enum | Descrição |
|------|-----------|
| `fiduciary_alienation_property` | Alienação fiduciária de imóvel. |
| `fiduciary_alienation_vehicle` | Alienação fiduciária de veículo. |
| `fiduciary_alienation_aircraft` | Alienação fiduciária de aeronave. |
| `fiduciary_alienation_equipment` | Alienação fiduciária de equipamentos/produtos/estoque. |
| `fiduciary_alienation_artwork` | Alienação fiduciária de obras de arte. |
| `fiduciary_alienation_securities` | Alienação fiduciária de títulos e valores mobiliários. |
| `fiduciary_assignment_shares` | Alienação fiduciária / penhor de ações e cotas. |
| `mortgage_property` | Hipoteca de imóveis. |
| `mortgage_ship` | Hipoteca de embarcações. |
| `guarantor` | Aval. |
| `surety` | Fiança (fiador). |
| `insurance` | Seguro. |
| `monitoring_guarantee` | Monitoramento de garantias. |
| `bank_surety` | Fiança bancária. |
| `fiduciary_assignment_credit_rights` | Cessão fiduciária de direitos creditórios. |
| `card_receivables` | Recebíveis de cartão. |
| `stock_guarantee` | Garantia de estoque. |
| `others` | Outras garantias. |

## Response

O corpo da resposta é um JSON completo da operação atualizada, com a nova garantia em `collateral_list`.

---

---

# Alteração de Cadastro do Emissor

URL: /documentation/escrituracao/homologacao-emissor/alteracao-cadastro/

Para realizar alterações no cadastro do Emissor, é necessário que seu status seja definido para "in_filling", isto irá habilitar novamente todos os endpoints de inclusão/remoção.

Após realizadas as modificações, o cadastro deve ser novamente enviado para análise com o status "in_analysis".

---

## Request

ENDPOINT /issuer_management/issuer/ ISSUER-KEY
MÉTODO PATCH

### Path Params

| Campo          | Tipo   | Descrição                        | Caracteres |
| -------------- | ------ | ---------------------------------- | ---------- |
| `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36         |

### Request Body

Request Body
```json
{
  "issuer_status": "in_filling"
}
```

### Request Body Params

| Campo              | Tipo   | Descrição                                          | Obrigatório |
| ------------------ | ------ | ---------------------------------------------------- | ------------ |
| `issuer_status`* | string | Novo status do emissor. Valor aceito:`in_filling`. | Sim          |

## Response

A resposta é um json completo atualizado do emissor.

---

# Consulta da Auto-assinatura

URL: /documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-auto-assinatura

Este endpoint permite consultar a auto-assinatura ativa de um emissor — status atual, dados do termo de adesão e histórico de eventos.

Os links de assinatura de cada assinante ficam em um endpoint próprio: [consulta dos links de assinatura](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-links-assinatura).

Consulte o [fluxo da auto-assinatura](/documentation/escrituracao/homologacao-emissor/auto-assinatura/inicio) para entender como a habilitação é criada e quais são os status possíveis.

---

## Consulta da Auto-assinatura (GET)

### Request
ENDPOINT /issuer_management/issuer/ ISSUER-KEY /auto_signature
MÉTODO GET

### Path Params

| Campo        | Tipo   | Descrição                         | Caracteres |
|--------------|--------|-----------------------------------|------------|
| `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36         |

---

### Response
STATUS 200

Response Body — aguardando assinatura do termo

```json
{
    "issuer_auto_signature_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34",
    "status": "pending_signature",
    "signed_at": null,
    "enabled_at": null,
    "issuer_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e",
    "term_document_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e/adhesion_auto_signature_term/5d1c8b30-2f44-4a9e-8c7b-1e0a6f2d9b55",
    "envelope_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34",
    "created_at": "2026-02-10T09:15:44",
    "event_list": [
        {
            "event_type": "auto_signature_creation",
            "status": "pending_term_generation",
            "event_data": {
                "tenant_key": "5e3045af-8be8-4cbd-9aab-9e15c4e92154"
            },
            "created_at": "2026-02-10T09:15:44"
        },
        {
            "event_type": "adhesion_term_generation",
            "status": "pending_term_generation",
            "event_data": {
                "term_document_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e/adhesion_auto_signature_term/5d1c8b30-2f44-4a9e-8c7b-1e0a6f2d9b55",
                "template_key": "b71f1a2c-9e44-4c1d-8f3a-6d2c0b5e7a19"
            },
            "created_at": "2026-02-10T09:16:02"
        },
        {
            "event_type": "envelope_creation",
            "status": "pending_signature",
            "event_data": {
                "envelope_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34"
            },
            "created_at": "2026-02-10T09:16:03"
        }
    ]
}
```

Response Body — termo assinado (habilitado)

```json
{
    "issuer_auto_signature_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34",
    "status": "enabled",
    "signed_at": "2026-02-11T14:02:31",
    "enabled_at": "2026-02-11T14:02:31",
    "issuer_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e",
    "term_document_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e/adhesion_auto_signature_term/5d1c8b30-2f44-4a9e-8c7b-1e0a6f2d9b55",
    "envelope_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34",
    "created_at": "2026-02-10T09:15:44",
    "event_list": [
        {
            "event_type": "signature_webhook_received",
            "status": "pending_signature",
            "event_data": {
                "envelope_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34",
                "envelope_status": "signed"
            },
            "created_at": "2026-02-11T14:02:31"
        },
        {
            "event_type": "auto_signature_status_change",
            "status": "enabled",
            "event_data": {
                "status": "enabled"
            },
            "created_at": "2026-02-11T14:02:31"
        }
    ]
}
```

---

### Response Body Params

| Campo                       | Tipo   | Descrição                                                                                                  |
|-----------------------------|--------|--------------------------------------------------------------------------------------------------------------|
| `issuer_auto_signature_key` | string | Chave única da auto-assinatura.                                                                             |
| `status`                    | string | Status atual: `pending_term_generation`, `pending_signature`, `enabled`, `reproved` ou `canceled`.          |
| `signed_at`                 | string | Data e hora da assinatura do termo. `null` enquanto o termo não é assinado.                                 |
| `enabled_at`                | string | Data e hora da habilitação. `null` enquanto o status não é `enabled`.                                       |
| `issuer_key`                | string | Chave única do emissor.                                                                                     |
| `term_document_key`         | string | Caminho do documento do termo de adesão gerado.                                                             |
| `envelope_key`              | string | Chave única do envelope de assinatura do termo.                                                             |
| `created_at`                | string | Data e hora de criação da auto-assinatura.                                                                  |
| `event_list`                | array  | Histórico de eventos da auto-assinatura, em ordem cronológica.                                              |

**Campos de `event_list`:**

| Campo        | Tipo   | Descrição                                                                                                                                                                                      |
|--------------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `event_type` | string | Tipo do evento: `auto_signature_creation`, `adhesion_term_generation`, `adhesion_term_generation_failure`, `envelope_creation`, `envelope_creation_failure`, `signature_webhook_received` ou `auto_signature_status_change`. |
| `status`     | string | Status da auto-assinatura no momento do evento.                                                                                                                                                |
| `event_data` | object | Dados do evento. O conteúdo varia conforme o `event_type`.                                                                                                                                     |
| `created_at` | string | Data e hora do evento.                                                                                                                                                                          |

---

### Erros

| HTTP | Código                                | Quando ocorre                                                                                     |
|------|---------------------------------------|-----------------------------------------------------------------------------------------------------|
| 403  | `ISS000011` (`TenantForbidden`)       | O cliente não possui acesso completo ao cadastro do emissor informado.                              |
| 404  | `ISS000009` (`IssuerNotFound`)        | Não existe emissor para a chave informada.                                                          |
| 404  | `ISS0000028` (`AutoSignatureNotFound`)| O emissor não possui auto-assinatura ativa.                                                         |

:::info Auto-assinaturas encerradas
A consulta retorna apenas a auto-assinatura **ativa** — aquela em `pending_term_generation`, `pending_signature` ou `enabled`. Depois que uma auto-assinatura vai para `reproved` ou `canceled`, este endpoint responde `ISS0000028` até que uma nova habilitação seja criada. O último estado conhecido continua visível no campo `auto_signature` da [consulta do emissor](/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-chave).
:::

---

# Consulta dos Links de Assinatura do Termo de Adesão

URL: /documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-links-assinatura

Este endpoint retorna **um link de assinatura por assinante** do termo de adesão da auto-assinatura, com o status individual de cada um. Cada assinante do emissor assina pelo seu próprio link.

Os links ficam disponíveis assim que a [solicitação da habilitação](/documentation/escrituracao/homologacao-emissor/auto-assinatura/solicitacao-auto-assinatura) responde — é ela que abre o envelope e leva a auto-assinatura a `pending_signature`. Se a geração do termo tiver falhado, a auto-assinatura fica em `pending_term_generation`, sem envelope, e este endpoint responde `ISS0000030` até que a solicitação seja repetida.

---

## Consulta dos Links de Assinatura (GET)

### Request

ENDPOINT /issuer_management/issuer/ ISSUER-KEY /auto_signature/signers
MÉTODO GET

### Path Params

| Campo        | Tipo   | Descrição                         | Caracteres |
| ------------ | ------ | --------------------------------- | ---------- |
| `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36         |

### Query Params

| Campo                | Tipo    | Descrição                                                                    | Obrigatório |
| -------------------- | ------- | ------------------------------------------------------------------------------ | ----------- |
| `exclude_qi_signers` | boolean | Se `true`, oculta da resposta os assinantes que são da QI. Padrão: `false`. | Não         |

---

### Response

STATUS 200

Response Body

```json
{
  "envelope_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34",
  "status": "pending_signature",
  "documents": [
    {
      "document_type": "adhesion_auto_signature_term",
      "signers": [
        {
          "document_number": "123.456.789-01",
          "signature_url": "https://sign.qitech.com.br/s/s2S33dD",
          "name": "Joao da Silva",
          "email": "joao.silva@example.com",
          "status": "on_signature"
        },
        {
          "document_number": "987.654.321-00",
          "signature_url": "https://sign.qitech.com.br/s/f7Kd91P",
          "name": "Maria de Souza",
          "email": "maria.souza@example.com",
          "status": "signed"
        },
        {
          "document_number": "421.820.518-30",
          "signature_url": "https://sign.qitech.com.br/s/q1W2e3R",
          "name": "Assinante QI CTVM",
          "email": "assinaturas.estruturadas@qitech.com.br",
          "status": "on_signature"
        }
      ]
    }
  ],
  "issuer_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e",
  "issuer_auto_signature_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34"
}
```

---

### Response Body Params

| Campo                       | Tipo   | Descrição                                                          |
| --------------------------- | ------ | -------------------------------------------------------------------- |
| `envelope_key`              | string | Chave única do envelope de assinatura do termo de adesão.           |
| `status`                    | string | Status do envelope no QI SIGN.                                      |
| `documents`                 | array  | Documentos do envelope. O termo de adesão é o único documento.      |
| `issuer_key`                | string | Chave única do emissor.                                             |
| `issuer_auto_signature_key` | string | Chave única da auto-assinatura.                                     |

**Campos de `documents`:**

| Campo           | Tipo   | Descrição                                                  |
| --------------- | ------ | ------------------------------------------------------------ |
| `document_type` | string | Sempre `adhesion_auto_signature_term`.                     |
| `signers`       | array  | Assinantes do documento, um item por assinante.            |

**Campos de `signers`:**

| Campo             | Tipo   | Descrição                                                                    |
| ----------------- | ------ | ------------------------------------------------------------------------------ |
| `document_number` | string | CPF do assinante.                                                            |
| `signature_url`   | string | Link individual de assinatura desse assinante.                               |
| `name`            | string | Nome do assinante.                                                           |
| `email`           | string | E-mail do assinante.                                                         |
| `status`          | string | Status individual da assinatura — por exemplo `on_signature` ou `signed`.   |

---

### Erros

| HTTP | Código                                     | Quando ocorre                                                                                            |
| ---- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| 400  | `ISS0000030` (`AutoSignatureInWrongStatus`) | O termo de adesão ainda não foi enviado para assinatura — a auto-assinatura está em `pending_term_generation`. |
| 403  | `ISS000011` (`TenantForbidden`)            | O cliente não possui acesso completo ao cadastro do emissor informado.                                   |
| 404  | `ISS000009` (`IssuerNotFound`)             | Não existe emissor para a chave informada.                                                               |
| 404  | `ISS0000028` (`AutoSignatureNotFound`)     | O emissor não possui auto-assinatura ativa.                                                              |

---

# Auto-assinatura do Emissor

URL: /documentation/escrituracao/homologacao-emissor/auto-assinatura/inicio

A auto-assinatura permite que a QI Tech assine automaticamente, em nome do emissor, os documentos das emissões seguintes — sem que um representante precise assinar operação por operação.

Para isso, o emissor assina **uma única vez** um **termo de adesão à auto-assinatura**. Enquanto esse termo não estiver assinado, as emissões continuam seguindo o fluxo normal de assinatura manual.

:::info Habilitação por cliente
A auto-assinatura não vem habilitada por padrão. Ela é configurada pela QI Tech por cliente (`tenant`), incluindo o template do termo de adesão utilizado. Para habilitar, entre em contato com o time [suporte-dcm@qitech.com.br](mailto:suporte-dcm@qitech.com.br).
:::

---

## Pré-requisitos

| Pré-requisito | Como é atendido |
|---------------|-----------------|
| Cliente habilitado para auto-assinatura | Configurado pela QI Tech, com o template do termo de adesão |
| Emissor com cadastro **aprovado** | Fluxo normal de [homologação do emissor](/documentation/escrituracao/homologacao-emissor/inicio) |
| Emissor com **grupo de assinantes** ativo | [Cadastro de assinantes do emissor](/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor) |

O grupo de assinantes cadastrado no emissor é exatamente quem assina o termo de adesão. Se ele estiver vazio ou desatualizado no momento da aprovação, corrija o cadastro antes de prosseguir.

---

## Fluxo ponta a ponta

A habilitação é **solicitada pelo integrador**, e só é aceita depois que o cadastro do emissor está aprovado. Não há criação automática: enquanto a solicitação não for feita, o emissor não tem auto-assinatura.

1. **Emissor aprovado.** O cadastro passa pelo fluxo normal de homologação até o status `approved`. Nada é criado nesse momento.
2. **Solicitação da habilitação.** O integrador chama [`POST /issuer_management/issuer/{issuer_key}/auto_signature`](/documentation/escrituracao/homologacao-emissor/auto-assinatura/solicitacao-auto-assinatura). Na mesma chamada, a QI Tech cria a auto-assinatura, gera o termo de adesão a partir do template configurado para o cliente e abre o envelope de assinatura — independente de qualquer operação. A resposta já vem no status `pending_signature`, com `issuer_auto_signature_key` e `envelope_key`.
3. **Assinatura do termo.** O integrador consulta os [links de assinatura](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-links-assinatura) e direciona **cada assinante do emissor ao seu próprio link**. O termo é assinado fora de qualquer operação, e pode ser assinado antes da primeira emissão.
4. **Termo assinado.** Quando todas as assinaturas necessárias são concluídas, a auto-assinatura passa para `enabled` e os campos `signed_at` e `enabled_at` são preenchidos. A QI Tech emite então o certificado privado do emissor, utilizado para assinar os documentos das emissões.
5. **Recusa ou expiração.** Se o envelope for recusado, cancelado ou expirado, a auto-assinatura vai para `reproved` e as emissões seguem pelo fluxo de assinatura manual. Uma nova habilitação precisa ser solicitada.

Os passos 2, 4 e 5 disparam o webhook [`issuer_management.auto_signature_status_change`](/documentation/escrituracao/webhooks-escrituracao) — ou seja, os status `pending_signature`, `enabled` e `reproved`. O cancelamento (`canceled`) não gera webhook e é observado por consulta. Como o `pending_signature` já vem na resposta da solicitação, o webhook desse status é redundante para quem chamou o endpoint — ele é útil para outros consumidores do mesmo tenant.

:::caution Não assuma a auto-assinatura ativa
A solicitação abre o envelope, mas não conclui a habilitação: o termo ainda precisa ser assinado. Só considere a assinatura automática disponível para uma emissão depois que a auto-assinatura estiver em `enabled`. Em qualquer outro status, o documento segue para assinatura manual — a integração precisa tratar os dois caminhos.
:::

---

## Máquina de status

| Status | Significado | Assinatura de uma nova emissão |
|--------|-------------|--------------------------------|
| `pending_term_generation` | Estado transitório durante a solicitação | Manual |
| `pending_signature` | Termo gerado e enviado para assinatura; links dos assinantes disponíveis | Manual |
| `enabled` | Termo assinado; emissor habilitado à assinatura automática | **Automática** |
| `reproved` | Envelope do termo recusado, cancelado ou expirado | Manual |
| `canceled` | Auto-assinatura cancelada | Manual |

**Transições possíveis:**

- `pending_term_generation` → `pending_signature` (ambos dentro da solicitação) → `enabled`
- `pending_signature` → `reproved` (envelope recusado, cancelado ou expirado)
- `pending_term_generation` ou `pending_signature` → `canceled`

A auto-assinatura é cancelada automaticamente quando o emissor deixa o status `approved` — ou seja, quando passa para `reproved`, `expired` ou `canceled`. Nesse caso, a habilitação precisa ser refeita após a nova aprovação do cadastro.

---

## Endpoints

| Endpoint | Para quê |
|---|---|
| [`POST .../auto_signature`](/documentation/escrituracao/homologacao-emissor/auto-assinatura/solicitacao-auto-assinatura) | Solicitar a habilitação para um emissor aprovado |
| [`GET .../auto_signature`](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-auto-assinatura) | Consultar o estado atual e o histórico de eventos |
| [`GET .../auto_signature/signers`](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-links-assinatura) | Obter o link de assinatura de cada assinante do termo |

## Como acompanhar

Há dois caminhos, complementares:

- **Webhook** — [`issuer_management.auto_signature_status_change`](/documentation/escrituracao/webhooks-escrituracao) é enviado nos status `pending_signature`, `enabled` e `reproved`. Ao receber `pending_signature`, consulte os links de assinatura.
- **Consulta** — [consulta da auto-assinatura](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-auto-assinatura) retorna o estado atual e o histórico completo de eventos.

O bloco resumido também aparece na [consulta do emissor](/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-chave), no campo `auto_signature`:

```json
{
    "issuer_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e",
    "status": "approved",
    "auto_signature": {
        "issuer_auto_signature_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34",
        "status": "enabled",
        "signed_at": "2026-02-11T14:02:31",
        "enabled_at": "2026-02-11T14:02:31"
    }
}
```

O campo é `null` para emissores que nunca tiveram uma auto-assinatura solicitada.

---

# Solicitação da Auto-assinatura

URL: /documentation/escrituracao/homologacao-emissor/auto-assinatura/solicitacao-auto-assinatura

Este endpoint solicita a habilitação da auto-assinatura para um emissor **aprovado**. Na mesma chamada, a QI Tech gera o termo de adesão e abre o envelope de assinatura, de modo que a resposta já volta com a habilitação pronta para ser assinada.

Consulte o [fluxo da auto-assinatura](/documentation/escrituracao/homologacao-emissor/auto-assinatura/inicio) para o encadeamento completo.

:::info Emissor aprovado
A solicitação só é aceita quando o cadastro do emissor está no status `approved` e o cliente está habilitado para auto-assinatura. Não há criação automática — nada acontece até que este endpoint seja chamado.
:::

---

## Solicitação da Auto-assinatura (POST)

### Request

ENDPOINT /issuer_management/issuer/ ISSUER-KEY /auto_signature
MÉTODO POST

### Path Params

| Campo        | Tipo   | Descrição                         | Caracteres |
| ------------ | ------ | --------------------------------- | ---------- |
| `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36         |

### Request Body

Este endpoint não recebe corpo. O grupo de assinantes e o template do termo de adesão são resolvidos pela QI Tech a partir do cadastro do emissor e da configuração do cliente.

---

### Response

STATUS 201

Response Body

```json
{
  "issuer_auto_signature_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34",
  "status": "pending_signature",
  "signed_at": null,
  "enabled_at": null,
  "issuer_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e",
  "term_document_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e/adhesion_auto_signature_term/5d1c8b30-2f44-4a9e-8c7b-1e0a6f2d9b55",
  "envelope_key": "5b930d3d-3713-4c42-85d5-f8e9e44e30ce",
  "created_at": "2026-02-10T09:15:44",
  "event_list": [
    {
      "event_type": "auto_signature_creation",
      "status": "pending_term_generation",
      "event_data": {
        "tenant_key": "5e3045af-8be8-4cbd-9aab-9e15c4e92154"
      },
      "created_at": "2026-02-10T09:15:44"
    },
    {
      "event_type": "adhesion_term_generation",
      "status": "pending_term_generation",
      "event_data": {
        "term_document_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e/adhesion_auto_signature_term/5d1c8b30-2f44-4a9e-8c7b-1e0a6f2d9b55",
        "template_key": "b71f1a2c-9e44-4c1d-8f3a-6d2c0b5e7a19"
      },
      "created_at": "2026-02-10T09:15:46"
    },
    {
      "event_type": "envelope_creation",
      "status": "pending_signature",
      "event_data": {
        "envelope_key": "5b930d3d-3713-4c42-85d5-f8e9e44e30ce"
      },
      "created_at": "2026-02-10T09:15:47"
    }
  ]
}
```

A resposta é o mesmo objeto da [consulta da auto-assinatura](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-auto-assinatura), normalmente já em `pending_signature`, com `term_document_key` e `envelope_key` preenchidos. Em seguida, consulte os [links de assinatura](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-links-assinatura) para obter o link de cada assinante.

---

### Erros

| HTTP | Código                                              | Quando ocorre                                                                       |
| ---- | --------------------------------------------------- | ------------------------------------------------------------------------------------- |
| 400  | `ISS0000032` (`IssuerNotApproved`)                  | O emissor não está no status `approved`.                                              |
| 400  | `ISS0000033` (`AutoSignatureNotEnabledForTenant`)   | O cliente não está habilitado para auto-assinatura.                                   |
| 403  | `ISS000011` (`TenantForbidden`)                     | O cliente não possui acesso completo ao cadastro do emissor informado.                |
| 404  | `ISS000009` (`IssuerNotFound`)                      | Não existe emissor para a chave informada.                                            |
| 404  | `ISS0000026` (`TenantConfigurationNotFound`)        | O cliente não possui configuração de auto-assinatura cadastrada.                      |
| 409  | `ISS0000029` (`AutoSignatureAlreadyExists`)         | O emissor já possui uma auto-assinatura ativa em `pending_signature` ou `enabled`. Cancele a atual antes de solicitar outra. |

---

# Cadastro de Grupos de Assinantes do Emissor

URL: /documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor

Este endpoint permite o cadastro de grupos de assinantes associados a um emissor previamente cadastrado.

---

## Request

ENDPOINT /issuer_management/issuer/ ISSUER-KEY /signer_group
MÉTODO POST

### Path Params

| Campo          | Tipo   | Descrição                        | Caracteres |
| -------------- | ------ | ---------------------------------- | ---------- |
| `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36         |

### Request Body

Request Body
```json
{
  "minimum_required_signers": 2,
  "signers": [
    {
      "name": "João da Silva",
      "document_number": "123.456.789-01",
      "email": "joao.silva@email.com",
      "phone_number": "+5511999999999",
      "is_group_mandatory": true
    },
    {
      "name": "Maria Souza",
      "document_number": "123.456.789-01",
      "email": "maria.souza@email.com",
      "phone_number": "+5511988888888",
      "is_group_mandatory": false
    }
  ]
}
```

### Request Body Params

| Campo                          | Tipo    | Descrição                                                      | Máximo de Caracteres                  |
| ------------------------------ | ------- | ---------------------------------------------------------------- | -------------------------------------- |
| `minimum_required_signers` * | integer | Número mínimo de assinantes necessários para validar o grupo. | -                                      |
| `signers` *                  | array   | Lista de Objetos Signer que compõem o grupo de assinantes       | **[Objeto Signer](#objeto-signer)** |

### Objeto Signer

| Campo                    | Tipo    | Descrição                                                                                                         | Máximo de Caracteres |
| ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------- | --------------------- |
| `name` *               | string  | Nome completo do assinante.                                                                                         | 255                   |
| `document_number` *    | string  | CPF do assinante (formatação "XXX.XXX.XXX-XX").                                                                   | 11                    |
| `email` *              | string  | Endereço de email do assinante.                                                                                    | 1023                  |
| `phone_number`*        | string  | Número de telefone do assinante (formatação completa: código do país, DDD e número. Exemplo: +5511999999999). | 20                    |
| `is_group_mandatory` * | boolean | Indica se o assinante é obrigatório ou opcional dentro do grupo.                                                  | -                     |

## Response

STATUS 201

Response Body

```json
{
  "signer_group_key": "123e4567-e89b-12d3-a456-426614174000",
  "minimum_required_signers": 2,
  "signers": [
    {
      "name": "João da Silva",
      "document_number": "123.456.789-01",
      "email": "joao.silva@email.com",
      "phone_number": "+5511999999999",
      "is_group_mandatory": true
    },
    {
      "name": "Maria Souza",
      "document_number": "123.456.789-01",
      "email": "maria.souza@email.com",
      "phone_number": "+5511988888888",
      "is_group_mandatory": false
    }
  ]
}
```

### Response Body Params

| Campo                        | Tipo    | Descrição                                                | Máximo de Caracteres                  |
| ---------------------------- | ------- | ---------------------------------------------------------- | -------------------------------------- |
| `signer_group_key`         | string  | Identificador único do grupo de assinantes (UUID v4).     | 36                                     |
| `minimum_required_signers` | integer | Número mínimo de assinantes necessários no grupo.       | -                                      |
| `signers` *                | array   | Lista de Objetos Signer que compõem o grupo de assinantes | **[Objeto Signer](#objeto-signer)** |

---

# Remoção de Grupos de Assinantes do Emissor

URL: /documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor-remocao

Este endpoint permite a remoção de grupos de assinantes associados a um emissor previamente cadastrado.

---

## Request
ENDPOINT /issuer_management/issuer/ ISSUER-KEY /signer_group/ SIGNER-GROUP-KEY
MÉTODO DELETE

### Path Params

| Campo              | Tipo   | Descrição                                                 | Caracteres |
|--------------------|--------|----------------------------------------------------------|------------|
| `ISSUER-KEY`       | string | Chave única do emissor (UUID v4).                         | 36         |
| `SIGNER-GROUP-KEY` | string | Chave única do grupo de assinantes a ser removido (UUID v4). | 36         |

## Response
STATUS 204

Nenhum conteúdo é retornado no corpo da resposta.

---

# Cadastro Básico do Emissor

URL: /documentation/escrituracao/homologacao-emissor/cadastro/cadastro-basico

Este endpoint permite cadastrar as informações básicas de um emissor.

## Request

ENDPOINT /issuer_management/issuer
MÉTODO POST

### Request Body

Request Body
```json
{
  "name": "Empresa Exemplo S.A.",
  "document_number": "12.345.678/0001-95",
  "trading_name": "Exemplo Comércio",
  "cnae_code": "62.02-3-00",
  "company_type": "sa",
  "foundation_date": "2000-01-01",
  "address": {
      "street": "Rua das Empresas",
      "neighborhood": "Centro",
      "number": "123",
      "postal_code": "01001-000",
      "city": "São Paulo",
      "state": "SP",
      "complement": "Sala 101"
  },
  "annual_revenues": 150000,
  "is_in_national_financial_system": false
}
```

### Request Body Params

| Campo                 | Tipo   | Descrição                                           | Caracteres Máx.                                               |
| --------------------- | ------ | ----------------------------------------------------- | -------------------------------------------------------------- |
| `name` *            | string | Nome completo da empresa.                             | 255                                                            |
| `document_number` * | string | CNPJ da empresa (formato "XX.XXX.XXX/XXXX-XX").       | 14                                                             |
| `trading_name`*     | string | Nome fantasia da empresa.                             | 1023                                                           |
| `cnae_code`*        | string | Código CNAE da empresa (formato "XX.XX-X-XX").       | 7                                                              |
| `company_type`*     | string | Tipo da empresa.                                      | **[Enumeradores company_type](#enumeradores-company_type)** |
| `foundation_date`*  | string | Data de fundação da empresa (formato "YYYY-MM-DD"). | -                                                              |
| `address` *         | string | Objeto referenciando o endereço                      | **[Objeto address](#objeto-address)
| `annual_revenues`  | number | Declaração de faturamento anual do cedente. | - |
| `is_in_national_financial_system`  | boolean | Indicador se o cedente é integrante do SFN. | - |

### Objeto Address

| Campo             | Tipo   | Descrição                              | Caracteres Máx. |
| ----------------- | ------ | ---------------------------------------- | ---------------- |
| `street` *      | string | Nome da rua do endereço da empresa.     | 500              |
| `neighborhood` * | string | Nome do bairro do endereço da empresa.  | 100              |
| `number` *      | string | Número do endereço.                    | 10               |
| `postal_code` * | string | CEP do endereço (formato "XXXXX-XXX").  | 8                |
| `city` *        | string | Nome da cidade do endereço.             | 255              |
| `state` *       | string | Sigla do estado (2 caracteres).          | 2                |
| `complement`    | string | Complemento do endereço, se aplicável. | 100              |

### Enumeradores company_type

| Enum     | Description        |
| -------- | ------------------ |
| `ltda` | Limitada           |
| `sa`   | Sociedade Anônima |
| `cop`  | Cooperativa        |

## Response

STATUS 201

Response Body

```json
{
    "issuer_key": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Empresa Exemplo S.A.",
    "document_number": "12.345.678/0001-95",
    "status": "in_filling",
    "person_type": "legal",
    "trading_name": "Exemplo Comércio",
    "cnae_code": "62.02-3-00",
    "company_type": "sa",
    "foundation_date": "2000-01-01",
    "address": {
      "street": "Rua das Empresas",
      "neighborhood": "Centro",
      "number": "123",
      "postal_code": "01001-000",
      "city": "São Paulo",
      "state": "SP",
      "complement": "Sala 101"
    },
    "registration_datetime": "2023-01-01T12:00:00Z",
    "expiration_date": "2024-01-01T12:00:00Z",
    "payment_bank_account": {
        "account_number": "19500",
        "account_digit": "7",
        "account_branch": "0001"
    },
    "annual_revenues": 150000,
    "is_in_national_financial_system": false
  }
```

### Response Body Params

| Campo                     | Tipo   | Descrição                         | Caracteres Máx.                                               |
| ------------------------- | ------ | ----------------------------------- | -------------------------------------------------------------- |
| `issuer_key`            | string | Chave única do emissor (UUID).     | 36                                                             |
| `name`                  | string | Nome completo do emissor.           | 255                                                            |
| `document_number`       | string | CNPJ do emissor.                    | 14                                                             |
| `status`                | string | Status do emissor.                  | -                                                              |
| `person_type`           | string | Tipo de pessoa                      | **[Enumeradores person_type](#enumeradores-person_type)**   |
| `trading_name`          | string | Nome fantasia do emissor.           | 1023                                                           |
| `cnae_code`             | string | Código CNAE do emissor.            | 7                                                              |
| `company_type`          | string | Tipo da empresa                     | **[Enumeradores company_type](#enumeradores-company_type)** |
| `foundation_date`       | string | Data de fundação do emissor.      | -                                                              |
| `address`               | string | Objeto referenciando o endereço    | **[Objeto address](#objeto-address)**                       |
| `registration_datetime` | string | Data e hora de registro do emissor. | -                                                              |
| `expiration_date`       | string | Data de expiração do emissor.     | -                                                              |
| `annual_revenues`  | number | Declaração de faturamento anual do cedente. | - |
| `is_in_national_financial_system`  | boolean | Indicador se o cedente é integrante do SFN. | - |

### Enumeradores person_type

| Enum        | Description      |
| ----------- | ---------------- |
| `legal`   | Pessoa Jurídica |
| `natural` | Pessoa Física   |

:::warning Aviso
Ao cadastrar um emissor é reservada uma conta interna que será aberta somente se uma operação for concretizada.
:::

### Objeto payment_bank_account

| Campo                | Tipo   | Descrição                 | Caracteres Máx. |
| -------------------- | ------ | --------------------------- | ---------------- |
| `account_digit` *  | string | Dígito da conta bancária. | -                |
| `account_branch` * | string | Agência bancária.         | -                |
| `account_number` * | string | Número da conta bancária. | -                |

---

# Cadastro de Conta Bancária do Emissor

URL: /documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor

Este endpoint permite o cadastro de conta bancária associada a um emissor previamente cadastrado.

---

## Request

ENDPOINT /issuer_management/issuer/ ISSUER-KEY /bank_account
MÉTODO POST

### Path Params

| Campo          | Tipo   | Descrição                        | Caracteres |
| -------------- | ------ | ---------------------------------- | ---------- |
| `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36         |

### Request Body

Request Body
```json
{
  "account_number": "12345678",
  "account_digit": "1",
  "account_branch": "1234",
  "financial_institution_code_number": "001",
  "financial_institution_ispb": "00000000",
  "account_type": "checking"
}
```

### Request Body Params

| Campo                                  | Tipo   | Descrição                                                  | Máximo de Caracteres                                          |
| -------------------------------------- | ------ | ------------------------------------------------------------ | -------------------------------------------------------------- |
| `account_number` *                   | string | Número da conta bancária. Deve conter apenas dígitos.     | 20                                                             |
| `account_digit` *                    | string | Dígito verificador da conta. Deve conter um único dígito. | 1                                                              |
| `account_branch` *                   | string | Número da agência bancária. Deve conter apenas dígitos.  | 6                                                              |
| `financial_institution_code_number`* | string | Código da instituição financeira (3 dígitos).            | 3                                                              |
| `financial_institution_ispb` *       | string | Código ISPB da instituição financeira (8 dígitos).       | 8                                                              |
| `account_type` *                     | string | Tipo da conta bancária.                                     | **[Enumeradores account_type](#enumeradores-account_type)** |

### Enumeradores account_type

| Enum         | Description        |
| ------------ | ------------------ |
| `checking` | Conta corrente     |
| `savings`  | Conta Poupança    |
| `salary`   | Conta Salário     |
| `payment`  | Conta de Pagamento |

## Response

STATUS 201

Response Body

```json
{
  "bank_account_key": "123e4567-e89b-12d3-a456-426614174000",
  "account_number": "12345678",
  "account_digit": "1",
  "account_branch": "1234",
  "financial_institution_code_number": "001",
  "financial_institution_ispb": "00000000",
  "account_type": "checking"
}
```

### Response Body Params

| Campo                                 | Tipo   | Descrição                                                   | Máximo de Caracteres                                          |
| ------------------------------------- | ------ | ------------------------------------------------------------- | -------------------------------------------------------------- |
| `bank_account_key`                  | string | Identificador único da conta bancária cadastrada (UUID v4). | 36                                                             |
| `account_number`                    | string | Número da conta bancária.                                   | 20                                                             |
| `account_digit`                     | string | Dígito verificador da conta bancária.                       | 1                                                              |
| `account_branch`                    | string | Número da agência bancária.                                | 6                                                              |
| `financial_institution_code_number` | string | Código da instituição financeira.                          | 3                                                              |
| `financial_institution_ispb`        | string | Código ISPB da instituição financeira.                     | 8                                                              |
| `account_type`                      | string | Tipo da conta bancária.                                      | **[Enumeradores account_type](#enumeradores-account_type)** |

---

# Definição de Conta Bancária Principal do Emissor

URL: /documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor-principal

Este endpoint promove uma conta bancária existente do emissor a conta principal (`is_default: true`). A conta anteriormente marcada como principal passa automaticamente a `is_default: false`.

---

## Trocando a conta bancária principal do emissor

O emissor pode ter várias contas bancárias cadastradas, e apenas uma é marcada como principal. Para corrigir uma conta principal com dados incorretos (dígito, agência, ISPB), use o fluxo abaixo.

:::warning Pré-requisito
O emissor precisa estar no status `in_filling`. Após esse status, a conta principal não pode ser alterada — comportamento intencional, dado que a conta principal é referenciada em operações financeiras.
:::

### Fluxo de troca (3 chamadas)

1. **POST** `.../bank_account` → cria a nova conta (correta).
2. **POST** `.../bank_account/{key}/set_default` → promove a nova conta a principal.
3. **DELETE** `.../bank_account/{old_key}` → remove a conta antiga.

A mesma restrição de ordem se aplica: como não é permitido deletar a conta principal, a promoção precisa vir antes da remoção. Tentar inverter retorna `HTTP 400 / ISS0000012`.

---

## Request

ENDPOINT /issuer_management/issuer/ ISSUER-KEY /bank_account/ BANK-ACCOUNT-KEY /set_default
MÉTODO POST

### Path Params

| Campo              | Tipo   | Descrição                                                          | Caracteres |
|--------------------|--------|--------------------------------------------------------------------|------------|
| `ISSUER-KEY`       | string | Chave única do emissor (UUID v4).                                  | 36         |
| `BANK-ACCOUNT-KEY` | string | Chave única da conta bancária que será promovida a principal (UUID v4). | 36         |

### Request Body

Nenhum conteúdo é enviado no corpo da requisição.

---

## Response

STATUS 204

Conta promovida a principal. Nenhum conteúdo é retornado no corpo da resposta.

---

## Erros

| HTTP | Código       | Cenário                                                                |
|------|--------------|------------------------------------------------------------------------|
| 400  | `ISS0000011` | Emissor não está em `in_filling`.                                      |
| 403  | `ISS000011`  | Tenant não tem acesso a esse emissor.                                  |
| 404  | `ISS000005`  | `bank_account_key` não encontrado para esse emissor.                   |
| 404  | `ISS000009`  | `issuer_key` não encontrado.                                           |

---

# Remoção de Conta Bancária do Emissor

URL: /documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor-remocao

Este endpoint permite a remoção de conta bancária associada a um emissor previamente cadastrado.

---

## Request
ENDPOINT /issuer_management/issuer/ ISSUER-KEY /bank_account/ BANK-ACCOUNT-KEY
MÉTODO DELETE

### Path Params

| Campo              | Tipo   | Descrição                                              | Caracteres |
|--------------------|--------|------------------------------------------------------|------------|
| `ISSUER-KEY`       | string | Chave única do emissor (UUID v4).                     | 36         |
| `BANK-ACCOUNT-KEY` | string | Chave única da conta bancária a ser removida (UUID v4).| 36         |

---

## Response
STATUS 204

Nenhum conteúdo é retornado no corpo da resposta.

---

## Observações

- Não é permitido remover a conta marcada como principal (`is_default: true`). A tentativa retorna `HTTP 400 / ISS0000012`. Para trocar a conta principal, veja o fluxo completo em [Definição de conta bancária principal](./conta-bancaria-emissor-principal.md).
- Alterações em conta principal só são permitidas com o emissor em `in_filling`. Fora desse status, a operação retorna `HTTP 400 / ISS0000011`.

---

---

# Envio de Documentos do Emissor

URL: /documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor

Este endpoint permite o envio de documentos associados a um emissor previamente cadastrado.

---

## Request

ENDPOINT /issuer_management/issuer/ ISSUER-KEY /document
MÉTODO POST

### Path Params

| Campo          | Tipo   | Descrição                        | Caracteres |
| -------------- | ------ | ---------------------------------- | ---------- |
| `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36         |

### Request Body

Request Body
```json
{
  "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0",
  "document_type": "proof_of_address"
}
```

### Request Body Params

| Campo                 | Tipo   | Descrição                                             | Caracteres Máx.                                                 |
| --------------------- | ------ | ------------------------------------------------------- | ---------------------------------------------------------------- |
| `document_base64` * | string | Conteúdo do arquivo do documento codificado em Base64. | -                                                                |
| `document_type` *   | string | Tipo do documento enviado.                              | **[Enumeradores document_type](#enumeradores-document_type)** |

### Enumeradores document_type

| Enum                            | Description                        |
| ------------------------------- | ---------------------------------- |
| `proof_of_address`              | Comprovante de Endereço            |
| `letter_of_attorney`            | Procuração                         |
| `company_statute` *               | Contrato ou Estatuto Social        |
| `commercial_board_certificate`  | Certificado da Junta Comercial     |
| `board_election_record`         | Ata de Eleição da Diretoria        |
| `manager_declaration`           | Declaração do Gestor               |
| `financial_statement`           | Balanço Financeiro                 |
| `credit_report`                 | Relatório de Crédito               |
| `manager_statement`             | Declaração do Administrador        |
| `compliance_statement`          | Declaração de Conformidade         |
| `cnpj_card`                     | Cartão CNPJ                        |
| `additional_document`           | Documento Adicional                |

:::warning Atenção
 O **company_statute** é obrigatório para todos os cadastros.
:::

## Response

STATUS 201

Response Body

**Cenário 1: Validação Automática (Sucesso no OCR)**

```json
{
    "document_key": "123e4567-e89b-12d3-a456-426614174000",
    "document_type": "proof_of_address",
    "ocr_key": "6654f284-f690-4324-8c39-dcf0225ec8cf"
}
```
**Significado**: O documento foi processado e validado automaticamente pelo nosso OCR.

**Cenário 2: Verificação Manual Necessária**

```json
{
    "document_key": "8bf591a8-c184-47db-afd2-a5196de14cc3",
    "document_type": "cnpj_card",
    "ocr_key": null
}
```
**Significado**: O documento não pôde ser validado automaticamente pelo OCR e foi encaminhado para nossa fila de verificação manual.

:::warning Atenção
A resposta para requisições bem-sucedidas (sucesso no envio) apresenta dois comportamentos distintos, dependendo do resultado da validação automática (OCR).
:::
### Response Body Params

| Field             | Type   | Description                                          | Max Length                                                       |
| ----------------- | ------ | ---------------------------------------------------- | ---------------------------------------------------------------- |
| `document_key`  | string | Identificador único do documento enviado (UUID v4). | 36                                                               |
| `document_type` | string | Tipo do documento enviado.                           | **[Enumeradores document_type](#enumeradores-document_type)** |
| `ocr_key`       | string | Chave OCR associada ao documento enviado.            | 36                                                               |

---

# Remoção de Documentos do Emissor

URL: /documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor-remocao

Este endpoint permite a remoção de documentos enviados para o cadastro do emissor.

---

## Request
ENDPOINT /issuer_management/issuer/ ISSUER-KEY /document/ DOCUMENT-KEY
MÉTODO DELETE

### Path Params

| Campo          | Tipo   | Descrição                                | Caracteres |
|----------------|--------|------------------------------------------|------------|
| `ISSUER-KEY`   | string | Chave única do emissor (UUID v4).         | 36         |
| `DOCUMENT-KEY` | string | Chave única do documento a ser removido (UUID v4). | 36         |

## Response
STATUS 204

Nenhum conteúdo é retornado no corpo da resposta.

---

# Envio de Documentos do Representante do Emissor

URL: /documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor

Este endpoint permite o envio de documentos associados a um representante de um emissor previamente cadastrado.

---
## Request
ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_representative/ ISSUER-REPRESENTATIVE-KEY /document
MÉTODO POST

### Path Params

| Campo                       | Tipo   | Descrição                                           | Caracteres |
|-----------------------------|--------|---------------------------------------------------|------------|
| `ISSUER-KEY`                | string | Chave única do emissor (UUID v4).                  | 36         |
| `ISSUER-REPRESENTATIVE-KEY` | string | Chave única do representante do emissor (UUID v4). | 36         |

### Request Body
Request Body
```json
{
  "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0",
  "document_type": "cnh"
}
```

### Request Body Params

| Campo             | Tipo     | Descrição                                                                                   | Máximo de Caracteres |
|--------------------|----------|-------------------------------------------------------------------------------------------|-----------------------|
| `document_base64` *| string   | Conteúdo do arquivo do documento codificado em Base64.                                     | -                     |
| `document_type` *  | string   | Tipo do documento enviado. Valores aceitos:          | **[Enumeradores document_type](#enumeradores-document_type)** |

### Enumeradores document_type
| Enum                            | Description                        |
| ------------------------------- | ---------------------------------- |
| `cnh`                           | Carteira Nacional de Habilitação   |
| `cnh_front`                     | Frente da CNH                      |
| `cnh_back`                      | Verso da CNH                       |
| `cnh_digital`                   | CNH Digital                        |
| `rg_front`                      | Frente do RG                       |
| `rg_back`                       | Verso do RG                        |
| `proof_of_address`              | Comprovante de Endereço            |
| `letter_of_attorney`            | Procuração                         |
| `passport`                      | Passaporte                         |
| `national_registry_of_foreigners`| Registro Nacional de Estrangeiros |

:::warning Atenção
É obrigatório para todos os cadastros pelo menos um documento identificador (cnh, rg, passport ou national_registry_of_foreigners) e caso o tipo do representante seja **attorney**, é necessário também uma procuração (letter_of_attorney).
:::

## Response
STATUS 201

Response Body

**Cenário 1: Validação Automática (Sucesso no OCR)**

```json
{
  "document_key": "123e4567-e89b-12d3-a456-426614174000",
  "document_type": "cnh",
  "ocr_key": "6654f284-f690-4324-8c39-dcf0225ec8cf"
}
```
**Significado**: O documento foi processado e validado automaticamente pelo nosso OCR.

**Cenário 2: Verificação Manual Necessária**

```json
{
    "document_key": "8bf591a8-c184-47db-afd2-a5196de14cc3",
    "document_type": "cnh",
    "ocr_key": null
}
```
**Significado**: O documento não pôde ser validado automaticamente pelo OCR e foi encaminhado para nossa fila de verificação manual.

:::warning Atenção
A resposta para requisições bem-sucedidas (sucesso no envio) apresenta dois comportamentos distintos, dependendo do resultado da validação automática (OCR).
:::
### Response Body Params

| Campo           | Tipo     | Descrição                                           | Máximo de Caracteres |
|------------------|----------|-----------------------------------------------------|-----------------------|
| `document_key`   | string   | Identificador único do documento enviado (UUID v4). | 36                    |
| `document_type`  | string   | Tipo do documento enviado.                          | **[Enumeradores document_type](#enumeradores-document_type)** |
| `ocr_key`        | string   | Chave OCR associada ao documento enviado.           | 36                    |

---

# Remoção de Documentos do Representante do Emissor

URL: /documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor-remocao

Este endpoint permite a remoção de documentos associados a um representante de um emissor previamente cadastrado.

---

## Request
ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_representative/ ISSUER-REPRESENTATIVE-KEY /document/ DOCUMENT-KEY
MÉTODO DELETE

### Path Params

| Campo                       | Tipo   | Descrição                                           | Caracteres |
|-----------------------------|--------|---------------------------------------------------|------------|
| `ISSUER-KEY`                | string | Chave única do emissor (UUID v4).                  | 36         |
| `ISSUER-REPRESENTATIVE-KEY` | string | Chave única do representante do emissor (UUID v4). | 36         |
| `DOCUMENT-KEY`              | string | Chave única do documento a ser removido (UUID v4). | 36         |

## Response
STATUS 204

Nenhum conteúdo é retornado no corpo da resposta.

---

# Cadastro de Informações de Contato do Emissor

URL: /documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor

Este endpoint permite o cadastro de informações de contato associadas a um emissor previamente cadastrado.

---

## Request

ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_contact_information
MÉTODO POST

### Path Params

| Campo          | Tipo   | Descrição                        | Caracteres |
| -------------- | ------ | ---------------------------------- | ---------- |
| `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36         |

### Request Body

Request Body
```json
{
  "name": "João da Silva",
  "document_number": "123.456.789-01",
  "email": "joao.silva@email.com",
  "phone_number": "+5511999999999"
}
```

### Request Body Params

| Campo                 | Tipo   | Descrição                                                                                                       | Máximo de Caracteres |
| --------------------- | ------ | ----------------------------------------------------------------------------------------------------------------- | --------------------- |
| `name` *            | string | Nome completo do contato.                                                                                         | 255                   |
| `document_number` * | string | Número do documento do contato (formato CPF, formato "XXX.XXX.XXX-XX").                                          | 14                    |
| `email`*            | string | Endereço de email do contato.                                                                                    | 1023                  |
| `phone_number`*     | string | Número de telefone do contato (formatação completa: código do país, DDD e número. Exemplo: +5511999999999). | 20                    |

## Response

STATUS 201

Response Body

```json
{
  "issuer_contact_information_key": "123e4567-e89b-12d3-a456-426614174000",
  "name": "João da Silva",
  "document_number": "123.456.789-01",
  "email": "joao.silva@email.com",
  "phone_number": "+5511999999999"
}
```

### Response Body Params

| Campo                              | Tipo   | Descrição                                                           | Máximo de Caracteres |
| ---------------------------------- | ------ | --------------------------------------------------------------------- | --------------------- |
| `issuer_contact_information_key` | string | Identificador único da informação de contato cadastrada (UUID v4). | 36                    |
| `name`                           | string | Nome completo do contato.                                             | 255                   |
| `document_number`                | string | Número do documento do contato (CPF).                                | 11                    |
| `email`                          | string | Endereço de email do contato.                                        | 1023                  |
| `phone_number`                   | string | Número de telefone do contato.                                       | 20                    |

---

# Definição de Contato Principal do Emissor

URL: /documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor-principal

Este endpoint promove um contato existente do emissor a contato principal (`is_default: true`). O contato anteriormente marcado como principal passa automaticamente a `is_default: false`.

---

## Trocando o contato principal do emissor

O emissor pode ter múltiplos contatos cadastrados, mas apenas um é marcado como principal. Caso o contato principal tenha sido cadastrado com um dado incorreto (typo no e-mail, dígito errado no telefone), use o fluxo abaixo para substituí-lo.

:::warning Pré-requisito
O emissor precisa estar no status `in_filling`. Após o emissor sair desse status, alterações em contato/conta principal não são permitidas — o endpoint retornará `HTTP 400 / ISS0000011`.
:::

### Fluxo de troca (3 chamadas)

1. **POST** `.../issuer_contact_information` → cria o novo contato (correto).
2. **POST** `.../issuer_contact_information/{key}/set_default` → promove o novo contato a principal.
3. **DELETE** `.../issuer_contact_information/{old_key}` → remove o contato antigo (com o typo).

A ordem importa: como não é permitido deletar um contato marcado como principal, é obrigatório promover o novo contato antes de deletar o antigo. Tentar inverter retorna `HTTP 400 / ISS0000013`.

---

## Request

ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_contact_information/ ISSUER-CONTACT-INFORMATION-KEY /set_default
MÉTODO POST

### Path Params

| Campo                            | Tipo   | Descrição                                                       | Caracteres |
|----------------------------------|--------|-----------------------------------------------------------------|------------|
| `ISSUER-KEY`                     | string | Chave única do emissor (UUID v4).                               | 36         |
| `ISSUER-CONTACT-INFORMATION-KEY` | string | Chave única do contato que será promovido a principal (UUID v4).| 36         |

### Request Body

Nenhum conteúdo é enviado no corpo da requisição.

---

## Response

STATUS 204

Contato promovido a principal. Nenhum conteúdo é retornado no corpo da resposta.

---

## Erros

| HTTP | Código       | Cenário                                                                |
|------|--------------|------------------------------------------------------------------------|
| 400  | `ISS0000011` | Emissor não está em `in_filling`.                                      |
| 403  | `ISS000011`  | Tenant não tem acesso a esse emissor.                                  |
| 404  | `ISS000008`  | `issuer_contact_information_key` não encontrado para esse emissor.     |
| 404  | `ISS000009`  | `issuer_key` não encontrado.                                           |

---

# Remoção de Informações de Contato do Emissor

URL: /documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor-remocao

Este endpoint a remoção de informações de contato associadas a um emissor previamente cadastrado.

---

## Request
ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_contact_information/ ISSUER-CONTACT-INFORMATION-KEY
MÉTODO DELETE

### Path Params

| Campo                            | Tipo   | Descrição                                                   | Caracteres |
|----------------------------------|--------|-----------------------------------------------------------|------------|
| `ISSUER-KEY`                     | string | Chave única do emissor (UUID v4).                          | 36         |
| `ISSUER-CONTACT-INFORMATION-KEY` | string | Chave única da informação de contato a ser removida (UUID v4).| 36         |

## Response
STATUS 204

Nenhum conteúdo é retornado no corpo da resposta.

---

## Observações

- Não é permitido remover o contato marcado como principal (`is_default: true`). A tentativa retorna `HTTP 400 / ISS0000013`. Para trocar o contato principal, veja o fluxo completo em [Definição de contato principal](./informacao-contato-emissor-principal.md).
- Alterações em contato principal só são permitidas com o emissor em `in_filling`. Fora desse status, a operação retorna `HTTP 400 / ISS0000011`.

---

# Cadastro de Representantes do Emissor

URL: /documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor

Este endpoint permite o cadastro de representantes associados a um emissor previamente cadastrado.

---

## Request

ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_representative
MÉTODO POST

### Path Params

| Campo          | Tipo   | Descrição                        | Caracteres |
| -------------- | ------ | ---------------------------------- | ---------- |
| `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36         |

### Request Body

Request Body
```json
{
  "name": "João da Silva",
  "document_number": "123.456.789-01",
  "birthdate": "1990-01-01",
  "nationality": "BRA",
  "mother_name": "Maria da Silva",
  "address": {
      "street": "Rua das Empresas",
      "neighborhood": "Centro",
      "number": "123",
      "postal_code": "01001-000",
      "city": "São Paulo",
      "state": "SP",
      "complement": "Sala 101"
  },
  "related_party_type": "attorney",
  "annual_revenues": 150000,
}
```

### Request Body Params

| Campo                              | Tipo    | Descrição                                                           | Máximo de Caracteres                                                |
| ---------------------------------- | ------- | --------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `name` *                         | string  | Nome completo do representante do emissor.                            | 255                                                                  |
| `document_number` *              | string  | Número do documento (CPF, no formato "XXX.XXX.XXX-XX").             | 11                                                                   |
| `birthdate`                      | string  | Data de nascimento do representante no formato ISO 8601 (YYYY-MM-DD). | -                                                                    |
| `document_identification_number` | string  | Número do documento de identificação.                              | 255                                                                  |
| `marital_status`                 | string  | Estado civil do representante.                                        | **[Enumeradores marital_status](#enumeradores-marital_status)**   |
| `property_system`                | string  | Regime de bens.                                                       | **[Enumeradores property_system](#enumeradores-property_system)** |
| `nationality` * | string | País de origem do beneficiário. | 3, de acordo com a ISO 3166-1 alpha-3 |
| `mother_name`                    | string  | Nome completo da mãe do representante.                               | 1023                                                                 |
| `father_name`                    | string  | Nome completo do pai do representante.                                | 1023                                                                 |
| `occupation`                     | string  | Ocupação ou profissão do representante.                            | 255                                                                  |
| `is_pep`                         | boolean | Indica se o representante é uma Pessoa Politicamente Exposta (PEP).  | -                                                                    |
| `address` *                      | string  | Objeto referenciando o endereço                                      | **[Objeto address](#objeto-address)**                             |
| `annual_revenues`  | number | Declaração de faturamento anual do cedente. | - |
| `related_party_type` * | enumerador | Tipo de vínculo da parte relacionada. | Ver **[Enumeradores de tipo de parte relacionada](#related-party-type)** |

### Objeto Address

| Campo             | Tipo   | Descrição                              | Caracteres Máx. |
| ----------------- | ------ | ---------------------------------------- | ---------------- |
| `street` *      | string | Nome da rua do endereço da empresa.     | 500              |
| `neighborhood`  | string | Nome do bairro do endereço da empresa.  | 100              |
| `number` *      | string | Número do endereço.                    | 10               |
| `postal_code` * | string | CEP do endereço (formato "XXXXX-XXX").  | 8                |
| `city` *        | string | Nome da cidade do endereço.             | 255              |
| `state` *       | string | Sigla do estado (2 caracteres).          | 2                |
| `complement`    | string | Complemento do endereço, se aplicável. | 100              |

### Enumeradores marital_status

| Enum             | Description        |
| ---------------- | ------------------ |
| `single`       | Solteiro(a)        |
| `married`      | Casado(a)          |
| `widower`      | Viúvo(a)          |
| `separated`    | Separado(a)        |
| `stable_union` | em União Estável |
| `divorced`     | Divorciado(a)      |

### Enumeradores property_system

| Enum                                    | Description                       |
| --------------------------------------- | --------------------------------- |
| `total_communion_of_goods`            | Comunhão Total de Bens           |
| `partial_communion_of_goods`          | Comunhão Parcial de Bens         |
| `total_separation_of_goods`           | Separação Total de Bens         |
| `final_participation_of_acquisitions` | Participação Final nos Aquestos |
| `compulsory_separation_of_goods`      | Separação Compulsória de Bens  |

### Related Party Type

| Enumerador              | Descrição   |
| ----------------------- | ------------- |
| **president**     | Presidente    |
| **partner**       | Sócio        |
| **administrator** | Administrador |
| **director**      | Diretor       |
| **manager**       | Gestor        |
| **attorney**      | Procurador    |

---

## Response

STATUS 201

Response Body

```json
{
  "issuer_representative_key": "123e4567-e89b-12d3-a456-426614174000",
  "name": "João da Silva",
  "document_number": "123.456.789-01",
  "document_identification_number": "987654321",
  "marital_status": "single",
  "property_system": "partial_communion_of_goods",
  "birthdate": "1990-01-01",
  "nationality": "BRA",
  "mother_name": "Maria da Silva",
  "father_name": "José da Silva",
  "occupation": "Advogado",
  "is_pep": false,
  "address": {
      "street": "Rua das Empresas",
      "neighborhood": "Centro",
      "number": "123",
      "postal_code": "01001-000",
      "city": "São Paulo",
      "state": "SP",
      "complement": "Sala 101"
  },
  "related_party_type": "attorney",
  "annual_revenues": 150000,
  "issuer_representative_document_list": []
}
```

### Response Body Params

| Campo                                   | Tipo    | Descrição                                                          | Máximo de Caracteres                                                |
| --------------------------------------- | ------- | -------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `issuer_representative_key`           | string  | Identificador único do representante do emissor (UUID v4).          | 36                                                                   |
| `name`                                | string  | Nome completo do representante do emissor.                           | 255                                                                  |
| `document_number`                     | string  | Número do documento do representante (formato "XXX.XXX.XXX-XX").    | 11                                                                   |
| `document_identification_number`      | string  | Número do documento de identificação.                             | 255                                                                  |
| `marital_status`                      | string  | Estado civil do representante.                                       | **[Enumeradores marital_status](#enumeradores-marital_status)**   |
| `property_system`                     | string  | Regime de bens.                                                      | **[Enumeradores property_system](#enumeradores-property_system)** |
| `birthdate`                           | string  | Data de nascimento do representante.                                 | -                                                                    |
| `nationality` * | string | País de origem do beneficiário. | 3, de acordo com a ISO 3166-1 alpha-3 |
| `mother_name`                         | string  | Nome completo da mãe do representante.                              | 1023                                                                 |
| `father_name`                         | string  | Nome completo do pai do representante.                               | 1023                                                                 |
| `occupation`                          | string  | Ocupação ou profissão do representante.                           | 255                                                                  |
| `is_pep`                              | boolean | Indica se o representante é uma Pessoa Politicamente Exposta (PEP). | -                                                                    |
| `address` *                           | string  | Objeto referenciando o endereço                                     | **[Objeto address](#objeto-address)**                             |
| `issuer_representative_document_list` | array   | Lista de documentos associados ao representante.                     | -                                                                    |
| `annual_revenues`  | number | Declaração de faturamento anual do cedente. | - |
| `related_party_type` * | enumerador | Tipo de vínculo da parte relacionada. | Ver **[Enumeradores de tipo de parte relacionada](#related-party-type)** |

---

# Remoção de Representante do Emissor

URL: /documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor-remocao

Este endpoint permite a remoção de representantes enviados para o cadastro do emissor.

---

## Request
ENDPOINT /issuer_management/issuer/ ISSUER-KEY /issuer_representative/ ISSUER-REPRESENTATIVE-KEY
MÉTODO DELETE

### Path Params

| Campo                       | Tipo   | Descrição                                              | Caracteres |
|-----------------------------|--------|--------------------------------------------------------|------------|
| `ISSUER-KEY`                | string | Chave única do emissor (UUID v4).                      | 36         |
| `ISSUER-REPRESENTATIVE-KEY` | string | Chave única do representante a ser removido (UUID v4). | 36         |

## Response
STATUS 204

Nenhum conteúdo é retornado no corpo da resposta.

---

# Consulta de Emissor

URL: /documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-chave

Este endpoint permite consultar os detalhes completos de um emissor cadastrado no sistema, utilizando sua chave única.

---

## Request
ENDPOINT /issuer_management/issuer/ ISSUER-KEY
MÉTODO GET

### Path Params

| Campo        | Tipo   | Descrição                                | Caracteres |
|--------------|--------|------------------------------------------|------------|
| `ISSUER-KEY` | string | Chave única do emissor (UUID v4).         | 36         |

## Response
RESPONSE STATUS 200

Response Body com status *in_filling*

```json
{
    "issuer_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e",
    "name": "Fabrica Exemplo S.A.",
    "document_number": "96.146.194/0001-07",
    "status": "in_filling",
    "backoffice_analysis_status": "in_analysis",
    "person_type": "legal",
    "trading_name": "Fabrica Comércio",
    "cnae_code": "62.02-3-00",
    "company_type": "sa",
    "foundation_date": "2000-01-01",
    "address": {
      "street": "Rua das Empresas",
      "neighborhood": "Centro",
      "number": "123",
      "postal_code": "01001-000",
      "city": "São Paulo",
      "state": "SP",
      "complement": "Sala 101"
    },
    "registration_datetime": "2025-01-23T13:47:57.354528",
    "expiration_date": "2026-01-23",
    "signer_group_list": [],
    "bank_account_list": [],
    "issuer_representative_list": [],
    "issuer_contact_information_list": [],
    "issuer_document_list": [],
    "issuer_analysis_list": [],
    "payment_bank_account": {
        "account_number": "19500",
        "account_digit": "7",
        "account_branch": "0001"
    },
    "annual_revenues": 150000,
    "is_in_national_financial_system": false
}
```

RESPONSE STATUS 200

Response Body com status *reproved*

```json
{
    "issuer_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e",
    "name": "Fabrica Exemplo S.A.",
    "document_number": "96.146.194/0001-07",
    "status": "reproved",
    "backoffice_analysis_status": "reproved",
    "person_type": "legal",
    "trading_name": "Fabrica Comércio",
    "cnae_code": "62.02-3-00",
    "company_type": "sa",
    "foundation_date": "2000-01-01",
    "address": {
      "street": "Rua das Empresas",
      "neighborhood": "Centro",
      "number": "123",
      "postal_code": "01001-000",
      "city": "São Paulo",
      "state": "SP",
      "complement": "Sala 101"
    },
    "registration_datetime": "2025-01-23T13:47:57.354528",
    "expiration_date": "2026-01-23",
    "bank_account_list": [
        {
            "bank_account_key": "b6546f3b-329a-4703-addd-ac2fb34a8eea",
            "account_number": "7567236",
            "account_digit": "9",
            "account_branch": "0001",
            "financial_institution_code_number": "329",
            "financial_institution_ispb": "32402502",
            "account_type": "checking",
            "is_default": true
        }
    ],
    "signer_group_list": [
        {
            "minimum_required_signers": 1,
            "signers": [
                {
                    "name": "Jose Representante",
                    "document_number": "037.208.830-94",
                    "email": "037.208.830-94@yopmail.com",
                    "is_group_mandatory": false
                }
            ]
        }
    ],
    "issuer_representative_list": [
        {
            "name": "Jose Representante",
            "document_number": "037.208.830-94",
            "nationality": "BRA",
            "related_party_type": "partner",
            "issuer_representative_document_list": []
        }
    ],
    "issuer_contact_information_list": [
        {
            "name": "Fabrica Exemplo S.A.",
            "phone_number": "+5516282399722",
            "is_default": true,
            "email": "email@yopmail.com",
            "document_number": "96.146.194/0001-07"
        }
    ],
    "issuer_document_list": [],
    "issuer_analysis_list": [],
    "last_analysis": {
        "analysis_key": "a274106e-5dbe-4a87-8999-6e41020f09b9",
        "analysis_number": 3,
        "status": "reproved",
        "analysis_datetime": "2025-10-24 02:52:15.886432",
        "analysis_related_parties": [
            {
                "analysis_related_party_key": "e634cbb5-6b6a-42b6-9348-7cb449f646ca",
                "name": "Jose Representante",
                "document_number": "037.208.830-94",
                "analysis_roles": [
                    {
                        "related_party_type": "partner"
                    }
                ],
                "documents": [
                    {
                        "document_key": "2b8ab03b-3896-43e9-9e5a-5e3c461164ef",
                        "status": "canceled",
                        "document_type": "cnh",
                        "observation": null
                    },
                    {
                        "document_key": "77f38757-4688-4027-a19a-b7066747b3b5",
                        "status": "valid",
                        "document_type": "cnh",
                        "observation": null
                    }
                ]
            }
        ],
        "documents": [
            {
                "document_key": "0ced115e-c008-4fae-93cd-b78c3f7d384d",
                "document_type": "social_contract",
                "status": "valid",
                "observation": null
            }
        ],
        "annotations": [],
        "last_updated": "2025-10-24 02:52:20.169204",
        "analysis_origin_type": "nce_integration",
        "reproval_reason": "missing_related_parties",
        "reproval_details": "parte relacionada João Representante consta no contrato social mas não está cadastrado"
    },
    "annual_revenues": 150000,
    "is_in_national_financial_system": false
}
```

RESPONSE STATUS 200

Response Body com status *approved*

```json
{
    "issuer_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e",
    "name": "Fabrica Exemplo S.A.",
    "document_number": "96.146.194/0001-07",
    "status": "approved",
    "backoffice_analysis_status": "approved",
    "person_type": "legal",
    "trading_name": "Fabrica Comércio",
    "cnae_code": "62.02-3-00",
    "company_type": "sa",
    "foundation_date": "2000-01-01",
    "address": {
      "street": "Rua das Empresas",
      "neighborhood": "Centro",
      "number": "123",
      "postal_code": "01001-000",
      "city": "São Paulo",
      "state": "SP",
      "complement": "Sala 101"
    },
    "registration_datetime": "2025-01-23T13:47:57.354528",
    "expiration_date": "2026-01-23",
    "bank_account_list": [
        {
            "bank_account_key": "b6546f3b-329a-4703-addd-ac2fb34a8eea",
            "account_number": "7567236",
            "account_digit": "9",
            "account_branch": "0001",
            "financial_institution_code_number": "329",
            "financial_institution_ispb": "32402502",
            "account_type": "checking",
            "is_default": true
        }
    ],
    "signer_group_list": [
        {
            "minimum_required_signers": 1,
            "signers": [
                {
                    "name": "Jose Representante",
                    "document_number": "037.208.830-94",
                    "email": "037.208.830-94@yopmail.com",
                    "is_group_mandatory": false
                }
            ]
        }
    ],
    "issuer_representative_list": [
        {
            "name": "Jose Representante",
            "document_number": "037.208.830-94",
            "nationality": "BRA",
            "related_party_type": "partner",
            "issuer_representative_document_list": []
        }
    ],
    "issuer_contact_information_list": [
        {
            "name": "Fabrica Exemplo S.A.",
            "phone_number": "+5516282399722",
            "is_default": true,
            "email": "email@yopmail.com",
            "document_number": "96.146.194/0001-07"
        }
    ],
    "issuer_document_list": [],
    "issuer_analysis_list": [],
    "last_analysis": {
        "analysis_key": "a274106e-5dbe-4a87-8999-6e41020f09b9",
        "analysis_number": 3,
        "status": "approved",
        "analysis_datetime": "2025-10-24 02:52:15.886432",
        "analysis_related_parties": [
            {
                "analysis_related_party_key": "e634cbb5-6b6a-42b6-9348-7cb449f646ca",
                "name": "Jose Representante",
                "document_number": "037.208.830-94",
                "analysis_roles": [
                    {
                        "related_party_type": "partner"
                    }
                ],
                "documents": [
                    {
                        "document_key": "2b8ab03b-3896-43e9-9e5a-5e3c461164ef",
                        "status": "canceled",
                        "document_type": "cnh",
                        "observation": null
                    },
                    {
                        "document_key": "77f38757-4688-4027-a19a-b7066747b3b5",
                        "status": "valid",
                        "document_type": "cnh",
                        "observation": null
                    }
                ]
            }
        ],
        "documents": [
            {
                "document_key": "0ced115e-c008-4fae-93cd-b78c3f7d384d",
                "document_type": "social_contract",
                "status": "valid",
                "observation": null
            }
        ],
        "annotations": [],
        "last_updated": "2025-10-24 02:52:20.169204",
        "analysis_origin_type": "nce_integration",
        "reproval_reason": null,
        "reproval_details": null
    },
    "annual_revenues": 150000,
    "is_in_national_financial_system": false
}
```

### Response Body Params

| Campo  | Tipo     | Descrição                                              | Máximo de Caracteres                            |
|--------|----------|--------------------------------------------------------|-------------------------------------------------|
| `issuer_key` | string   | Identificador único do emissor.                        | 36                                              |
| `name` | string   | Nome completo do emissor.                              | 255                                             |
| `document_number` | string   | Número do documento do emissor (CNPJ).                 | 14                                              |
| `status` | string   | Status do emissor                                      | **[Enumeradores status](#enumeradores-status)** |
| `backoffice_analysis_status`| string   | Status de análise do backoffice.                       | -                                               |
| `person_type` | string   | Tipo de pessoa (`legal` ou `natural`).                 | -                                               |
| `trading_name` | string   | Nome fantasia do emissor.                              | 1023                                            |
| `cnae_code` | string   | Código CNAE do emissor.                                | 10                                              |
| `company_type` | string   | Tipo de empresa: ´sa´, ´ltda´, ´cop´, ´-´                          | 50                                              |
| `foundation_date` | string   | Data de fundação do emissor.                           | -                                               |
| `signer_group_list` | array    | Lista de grupos de assinantes associados ao emissor.   | -                                               |
| `bank_account_list` | array    | Lista de contas bancárias associadas ao emissor.       | -                                               |
| `issuer_representative_list` | array    | Lista de representantes do emissor.                    | -                                               |
| `issuer_contact_information_list` | array    | Lista de informações de contato associadas ao emissor. | -                                               |
| `issuer_document_list` | array    | Lista de documentos cadastrados para o emissor.        | -                                               |
| `address`         | string   | Objeto referenciando o endereço                   | **[Objeto address](#objeto-address)**           |
| `annual_revenues`  | number | Declaração de faturamento anual do cedente. | - |
| `is_in_national_financial_system`  | boolean | Indicador se o cedente é integrante do SFN. | - |
| `last_analysis`  | object | Objeto de análise. | **[Definição de Análise](#definição-de-análise)**. |

### Objeto Address

| Campo               | Tipo     | Descrição                                           | Caracteres Máx. |
|---------------------|----------|-----------------------------------------------------|-----------------|
| `street`          | string   | Nome da rua do endereço da empresa.                 | 500             |
| `neighborhood`      | string   | Nome do bairro do endereço da empresa.              | 100             |
| `number`         | string   | Número do endereço.                                 | 10              |
| `postal_code`     | string   | CEP do endereço (somente números).                  | 8               |
| `city`           | string   | Nome da cidade do endereço.                         | 255             |
| `state`           | string   | Sigla do estado (2 caracteres).                     | 2               |
| `complement`        | string   | Complemento do endereço, se aplicável.              | 100             |

### Enumeradores status
| Enum   | 	Description    |
|--------|-----------------|
| `in_filling` | Em preenchimento |
| `in_analysis`	  | Em análise      |
| `canceled`	 | Cancelado       |
| `approved`	 | Aprovado        |
| `reproved`	 | Reprovado       |
| `expired`	 | Expirado        |

### Objeto payment_bank_account

| Campo                              | Tipo     | Descrição                                      | Caracteres Máx. |
|-------------------------------------|----------|------------------------------------------------|-----------------|
| `account_digit`                    | string   | Dígito da conta bancária.                      | -               |
| `account_branch`                    | string   | Agência bancária.                              | -               |
| `account_number`                    | string   | Número da conta bancária.                      | -               |

### Definição de Análise

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `analysis_key` | string | Identificador da análise. | 36 |
| `analysis_number` | integer | Número sequencial da análise. | - |
| `status` | string | Status da análise. | Ver **[Enumeradores de status de análise](#analysis-status)**. |
| `analysis_related_parties` | array | Partes Relacionadas da análise. | Ver **[Definição de Partes Relacionadas de Análise](#definição-de-partes-relacionadas-de-análise)**. |
| `documents` | array | Documentos da anáise. | Ver **[Definição de Documentos de análise](#definição-de-documentos)**. |
| `analysis_data` | object | Payload da request que originou a análise. | - |
| `analysis_datetime` | string | Objeto date time da criação da análise. | - |
| `reproval_reason` | string | Enumerador com o motivo de rejeição da análise. | Ver **[Enumeradores de motivo de reprovação](#analysis-reproval-reason)**. |
| `reproval_details` | string | Campo livre com detalhes da rejeição da análise. | - |

---

### Analysis Status

| Enumerador              | Descrição           |
| ----------------------- | --------------------- |
| **pending_documents**  | Pendente Documentos   |
| **sent_to_analysis**   | Enviado para Análise |
| **pending_internal_validation** | Em Validação de documentos    |
| **in_manual_analysis** | Em Análise Manual de Compliance    |
| **approved**           | Aprovado              |
| **reproved**           | Reprovado             |

---

### Definição de Documentos

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `document_key` | string | Identificador do documento. | 36 |
| `document_type` | string | Tipo do documento. |  |
| `status` | string | Status do documento. |  |
| `observation` | string | Observações enviadas. | - |

---

### Definição de Partes Relacionadas de análise

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `analysis_related_party_key` | string | Identificador da parte relacionada. | 36 |
| `document_number` | string | Número de documento da parte relacionada. | 14 a 18 |
| `name` | string | Nome da parte relacionada. | 1 a 255 |
| `documents` | array | Documentos da anáise da parte relacionada. |  |

---

### Analysis Reproval Reason
| Enum         | 	Description  |
|--------------|---------------|
| **assignor_update**   | Análise cancelada devido à atualização cadastral posterior |
| **insuficient_documents**  | Documentação mínima para comprovação de poderes não enviada |
| **compliance_reproval**  | Reprovação de vínculo por análise do time de compliance |
| **unidentified_related_parties** | Parte relacionada enviada, porém vinculo não comprovado |
| **invalid_documents** | Documentação inválida/expirada |
| **missing_related_parties** | Parte relacionada obrigatória não enviada |

---

---

# Consulta de Emissores por filtros

URL: /documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-filtro

Este endpoint permite consultar emissores cadastrados no sistema utilizando o número de documento (CNPJ) ou Nome.

---

## Request
ENDPOINT /issuer_management/issuer
MÉTODO GET

### Query Params

| Campo             | Tipo     | Descrição                          | Obrigatório |
|-------------------|----------|------------------------------------|-------------|
| `document_number` | string   | Número do documento do emissor.    | Não         |
| `name`            | string   | Nome do emissor.                   | Não         |
| `page`            | integer  | Página atual da consulta.          | Não         |
| `rows_per_page`   | integer  | Número de registros por página.    | Não         |

## Response
STATUS 200

Response Body

```json
{
  "data": [
    {
        "issuer_key": "495ae701-5c38-49b1-b517-a3b910fe8d8f",
        "name": "Empresa Exemplo S.A.",
        "document_number": "12.345.678/0001-95",
        "status": "in_filling"
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "rows_per_page": 100,
    "total_pages": 1,
    "total_rows": 1
  }
}
```

### Response Body Params

| Campo        | Tipo   | Descrição           |                                                                 |
|--------------|--------|---------------------|-----------------------------------------------------------------|
| `data`       | list   | Lista de resultados | **[Objeto Emissor Simplificado](#objeto-emissor-simplificado)** |
| `pagination` | object | Dados de paginação  | **[Objeto Paginação](#objeto-paginacao)**                       |

### Objeto Emissor Simplificado

| Campo            | Tipo     | Descrição                                                     | Máximo de Caracteres                            |
|-------------------|----------|-------------------------------------------------------------|-------------------------------------------------|
| `issuer_key` | string   | Identificador único do emissor (UUID v4).                  | 36                                              |
| `name`     | string   | Nome completo do emissor.                                   | 255                                             |
| `document_number` | string | Número do documento do emissor (CNPJ).                   | 14                                              |
| `status`   | string   | Status atual do emissor.                 | **[Enumeradores status](#enumeradores-status)** |

### Enumeradores status
| Enum   | 	Description    |
|--------|-----------------|
| `in_filling` | Em preenchimento |
| `in_analysis`	  | Em análise      |
| `canceled`	 | Cancelado       |
| `approved`	 | Aprovado        |
| `reproved`	 | Reprovado       |
| `expired`	 | Expirado        |

### Objeto Pagination

| Campo             | Tipo     | Descrição                                |
|-------------------|----------|------------------------------------------|
| `current_page`    | integer  | Página atual da consulta.                |
| `next_page`       | integer  | Próxima página, caso exista.             |
| `rows_per_page`   | integer  | Número de registros por página.          |
| `total_pages`     | integer  | Número total de páginas.                 |
| `total_rows`      | integer  | Número total de registros encontrados.   |

---

# Envio para Análise do Emissor

URL: /documentation/escrituracao/homologacao-emissor/envio-analise/

Este endpoint permite alterar o status de um emissor para análise, enviando-o para o processo de validação.

---

## Request

ENDPOINT /issuer_management/issuer/ ISSUER-KEY
MÉTODO PATCH

### Path Params

| Campo          | Tipo   | Descrição                        | Caracteres |
| -------------- | ------ | ---------------------------------- | ---------- |
| `ISSUER-KEY` | string | Chave única do emissor (UUID v4). | 36         |

### Request Body

Request Body
```json
{
  "issuer_status": "in_analysis"
}
```

### Request Body Params

| Campo             | Tipo   | Descrição                                             | Obrigatório |
| ----------------- | ------ | ------------------------------------------------------- | ------------ |
| `issuer_status` | string | Novo status do emissor. Valor aceito: `in_analysis`. | Sim          |

## Response

 A resposta é um json completo atualizado do emissor.

---

# Introdução

URL: /documentation/escrituracao/homologacao-emissor/inicio

A parte de cadastro de Emissores é essencial para o início da emissão de Notas Comerciais. Nessa seção iremos explicar todo o fluxo, desde o envio das primeiras informações, até o envio para análise.

Para ter acesso aos serviços discutidos nas próximas sessões, entre em contato com o time [suporte-dcm@qitech.com.br](mailto:suporte-dcm@qitech.com.br), para que seja feito as devidas liberações, tanto em ambiente de Homologação (Sandbox) quanto em ambiente de produção.

### Cadastro do Emissor

Nessa etapa, deve-se enviar todas as informações tanto do Emissor quanto dos seus representantes, documentos, informações de contato, grupos de assinantes e contas bancárias.

Uma vez que o envio das informações estiver concluído, o cadastro é enviado para análise do time de cadastro de cedentes e após aprovação este emissor estará apto a participar da emissão de Notas.

Caso o cadastro já tenha sido feito na plataforma da QI CTVM de cadastro de cedentes, é possível reaproveitar esse cadastro de forma simples, utilizando o endpoint de solicitação de acesso ao cadastro.

### Auto-assinatura do Emissor

Clientes habilitados para auto-assinatura contam com um fluxo adicional: após a aprovação do cadastro, o emissor assina uma única vez um termo de adesão e passa a ter os documentos das emissões seguintes assinados automaticamente. Veja [Auto-assinatura do emissor](/documentation/escrituracao/homologacao-emissor/auto-assinatura/inicio).

### Atualização de Emissor

Em caso de necessidade de atualização cadastral, deve-se enviar novamente todas as informações do Emissor com as modificações desejadas. Após envio, é gerada uma nova Análise para validação. 

Assim que esta nova Análise for aprovada, os novos dados cadastrais do Emissor são efetivamente alterados.

---

# Solicitação de Acesso aos Dados do Emissor

URL: /documentation/escrituracao/homologacao-emissor/solicitacao-acesso

Clientes que cadastraram um emissor que já possui um **cadastro na homologação de cedente** precisam **solicitar acesso aos dados do emissor** para que possam emitir operações com esse emissor como parte no sistema de escrituração.   

---

## **Solicitação de Acesso (POST)**

### **Request**
ENDPOINT /issuer_management/issuer/data_access_request
MÉTODO POST

---

## **Request Body**  

Request Body

```json
{
    "document_number": "96.146.194/0001-07",
}
```

---

## **Response**
STATUS 201

Response Body

```json
{
    "issuer_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e",
    "name": "Fabrica Exemplo S.A.",
    "document_number": "96.146.194/0001-07",
    "status": "approved",
    "backoffice_analysis_status": "approved",
    "person_type": "legal",
    "trading_name": "Fabrica Comércio",
    "cnae_code": "62.02-3-00",
    "company_type": "sa",
    "foundation_date": "2000-01-01",
    "address": {
      "street": "Rua das Empresas",
      "neighborhood": "Centro",
      "number": "123",
      "postal_code": "01001-000",
      "city": "São Paulo",
      "state": "SP",
      "complement": "Sala 101"
    },
    "registration_datetime": "2025-01-23T13:47:57.354528",
    "expiration_date": "2026-01-23",
    "signer_group_list": [
        {
            "signer_group_key": "123e4567-e89b-12d3-a456-426614174000",
            "minimum_required_signers": 2,
            "signers": [
                {
                "name": "João da Silva",
                "document_number": "123.456.789-01",
                "email": "joao.silva@email.com",
                "phone_number": "+5511999999999",
                "is_group_mandatory": true
                },
                {
                "name": "Maria Souza",
                "document_number": "123.456.789-01",
                "email": "maria.souza@email.com",
                "phone_number": "+5511988888888",
                "is_group_mandatory": false
                }
            ]
        }
    ],
    "bank_account_list": [
        {
            "bank_account_key": "123e4567-e89b-12d3-a456-426614174000",
            "account_number": "12345678",
            "account_digit": "1",
            "account_branch": "1234",
            "financial_institution_code_number": "001",
            "financial_institution_ispb": "00000000",
            "account_type": "checking"
        }
    ],
    "issuer_representative_list": [
        {
            "issuer_representative_key": "123e4567-e89b-12d3-a456-426614174000",
            "name": "João da Silva",
            "document_number": "123.456.789-01",
            "document_identification_number": "987654321",
            "marital_status": "single",
            "property_system": "partial_communion_of_goods",
            "birthdate": "1990-01-01",
            "nationality": "BRA",
            "mother_name": "Maria da Silva",
            "father_name": "José da Silva",
            "occupation": "Advogado",
            "is_pep": false,
            "address": {
                "street": "Rua das Empresas",
                "neighborhood": "Centro",
                "number": "123",
                "postal_code": "01001-000",
                "city": "São Paulo",
                "state": "SP",
                "complement": "Sala 101"
            },
            "related_party_type": "attorney",
            "annual_revenues": 150000,
            "issuer_representative_document_list": [
                {
                    "document_key": "123e4567-e89b-12d3-a456-426614174000",
                    "document_type": "cnh",
                    "ocr_key": "123e4567-e89b-12d3-a456-426614174000"
                }
            ]
        }
    ],
    "issuer_contact_information_list": [
        {
            "name": "João da Silva",
            "document_number": "123.456.789-01",
            "email": "joao.silva@email.com",
            "phone_number": "+5511999999999"
        }
    ],
    "issuer_document_list": [
        {
            "document_key": "123e4567-e89b-12d3-a456-426614174000",
            "document_type": "proof_of_address",
            "ocr_key": "123e4567-e89b-12d3-a456-426614174000"
        }
    ],
    "issuer_analysis_list": [],
    "payment_bank_account": {
        "account_number": "19500",
        "account_digit": "7",
        "account_branch": "0001"
    }
}
```

### Response Body Params

| Campo  | Tipo     | Descrição                                              | Máximo de Caracteres                            |
|--------|----------|--------------------------------------------------------|-------------------------------------------------|
| `issuer_key` | string   | Identificador único do emissor.                        | 36                                              |
| `name` | string   | Nome completo do emissor.                              | 255                                             |
| `document_number` | string   | Número do documento do emissor (CNPJ).                 | 14                                              |
| `status` | string   | Status do emissor                                      | **[Enumeradores status](#enumeradores-status)** |
| `backoffice_analysis_status`| string   | Status de análise do backoffice.                       | -                                               |
| `person_type` | string   | Tipo de pessoa (`legal` ou `natural`).                 | -                                               |
| `trading_name` | string   | Nome fantasia do emissor.                              | 1023                                            |
| `cnae_code` | string   | Código CNAE do emissor.                                | 10                                              |
| `company_type` | string   | Tipo de empresa Aceitos: ´sa´, ´ltda´, ´cop´                          | 50                                              |
| `foundation_date` | string   | Data de fundação do emissor.                           | -                                               |
| `signer_group_list` | array    | Lista de grupos de assinantes associados ao emissor.   | -                                               |
| `bank_account_list` | array    | Lista de contas bancárias associadas ao emissor.       | -                                               |
| `issuer_representative_list` | array    | Lista de representantes do emissor.                    | -                                               |
| `issuer_contact_information_list` | array    | Lista de informações de contato associadas ao emissor. | -                                               |
| `issuer_document_list` | array    | Lista de documentos cadastrados para o emissor.        | -                                               |
| `address` *         | string   | Objeto referenciando o endereço                   | **[Objeto address](#objeto-address)**           |

### Objeto Address

| Campo               | Tipo     | Descrição                                           | Caracteres Máx. |
|---------------------|----------|-----------------------------------------------------|-----------------|
| `street` *          | string   | Nome da rua do endereço da empresa.                 | 500             |
| `neighborhood`      | string   | Nome do bairro do endereço da empresa.              | 100             |
| `number` *          | string   | Número do endereço.                                 | 10              |
| `postal_code` *     | string   | CEP do endereço (somente números).                  | 8               |
| `city` *            | string   | Nome da cidade do endereço.                         | 255             |
| `state` *           | string   | Sigla do estado (2 caracteres).                     | 2               |
| `complement`        | string   | Complemento do endereço, se aplicável.              | 100             |

### Enumeradores status
| Enum   | 	Description    |
|--------|-----------------|
| `in_filling` | Em preenchimento |
| `in_analysis`	  | Em análise      |
| `canceled`	 | Cancelado       |
| `approved`	 | Aprovado        |
| `reproved`	 | Reprovado       |
| `expired`	 | Expirado        |

### Objeto payment_bank_account

| Campo                              | Tipo     | Descrição                                      | Caracteres Máx. |
|-------------------------------------|----------|------------------------------------------------|-----------------|
| `account_digit` *                    | string   | Dígito da conta bancária.                      | -               |
| `account_branch` *                    | string   | Agência bancária.                              | -               |
| `account_number` *                    | string   | Número da conta bancária.                      | -               |

---

# Alteraçao de Cadastro do Investidor

URL: /documentation/escrituracao/homologacao-investidor/alteracao-cadastro/

Para realizar alterações no cadastro do Investidor, é necessário que seu status seja definido para "in_filling", isto irá habilitar novamente todos os endpoints de inclusão/remoção.

Após realizadas as modificações, o cadastro deve ser novamente enviado para análise com o status "in_analysis".

---

## Request
ENDPOINT /investor_management/investor/ INVESTOR-KEY
MÉTODO PATCH

### Path Params

| Campo        | Tipo   | Descrição                                | Caracteres |
|--------------|--------|------------------------------------------|------------|
| `INVESTOR-KEY` | string | Chave única do investidor (UUID v4).         | 36         |

### Request Body

Request Body
```json
{
  "investor_status": "in_filling"
}
```

### Request Body Params

| Campo           | Tipo     | Descrição                                           | Obrigatório |
|------------------|----------|-----------------------------------------------------|-------------|
| `investor_status`  | string   | Novo status do investidor. Valor aceito: `in_filling`. | Sim         |

## Response

A resposta é um json completo atualizado do investidor.

---

# Cadastro de Grupos de Assinantes do Investidor

URL: /documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor

Este endpoint permite o cadastro de grupos de assinantes associados a um investidor previamente cadastrado.

:::danger Atenção
Não é possível adicionar grupo de assinantes para um investidor Pessoa Física (PF).
:::

---

## Request

ENDPOINT /investor_management/investor/ INVESTOR-KEY /signer_group
MÉTODO POST

### Path Params

| Campo            | Tipo   | Descrição                           | Caracteres |
| ---------------- | ------ | ------------------------------------- | ---------- |
| `INVESTOR-KEY` | string | Chave única do investidor (UUID v4). | 36         |

### Request Body

Request Body
```json
{
  "minimum_required_signers": 2,
  "signers": [
    {
      "name": "João da Silva",
      "document_number": "123.456.789-01",
      "email": "joao.silva@email.com",
      "phone_number": "+5511999999999",
      "is_group_mandatory": true
    },
    {
      "name": "Maria Souza",
      "document_number": "123.456.789-01",
      "email": "maria.souza@email.com",
      "phone_number": "+5511988888888",
      "is_group_mandatory": false
    }
  ]
}
```

### Request Body Params

| Campo                          | Tipo    | Descrição                                                      | Máximo de Caracteres                  |
| ------------------------------ | ------- | ---------------------------------------------------------------- | -------------------------------------- |
| `minimum_required_signers` * | integer | Número mínimo de assinantes necessários para validar o grupo. | -                                      |
| `signers` *                  | array   | Lista de Objetos Signer que compõem o grupo de assinantes       | **[Objeto Signer](#objeto-signer)** |

### Objeto Signer

| Campo                    | Tipo    | Descrição                                                                                                         | Máximo de Caracteres |
| ------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------- | --------------------- |
| `name` *               | string  | Nome completo do assinante.                                                                                         | 255                   |
| `document_number` *    | string  | CPF do assinante (formato "XX.XXX.XXX/XXXX-XX").                                                                    | 11                    |
| `email` *              | string  | Endereço de email do assinante.                                                                                    | 1023                  |
| `phone_number`*        | string  | Número de telefone do assinante (formatação completa: código do país, DDD e número. Exemplo: +5511999999999). | 20                    |
| `is_group_mandatory` * | boolean | Indica se o assinante é obrigatório ou opcional dentro do grupo.                                                  | -                     |

## Response

STATUS 201

Response Body

```json
{
  "signer_group_key": "123e4567-e89b-12d3-a456-426614174000",
  "minimum_required_signers": 2,
  "signers": [
    {
      "name": "João da Silva",
      "document_number": "123.456.789-01",
      "email": "joao.silva@email.com",
      "phone_number": "+5511999999999",
      "is_group_mandatory": true
    },
    {
      "name": "Maria Souza",
      "document_number": "123.456.789-01",
      "email": "maria.souza@email.com",
      "phone_number": "+5511988888888",
      "is_group_mandatory": false
    }
  ]
}
```

### Response Body Params

| Campo                        | Tipo    | Descrição                                                | Máximo de Caracteres                  |
| ---------------------------- | ------- | ---------------------------------------------------------- | -------------------------------------- |
| `signer_group_key`         | string  | Identificador único do grupo de assinantes (UUID v4).     | 36                                     |
| `minimum_required_signers` | integer | Número mínimo de assinantes necessários no grupo.       | -                                      |
| `signers` *                | array   | Lista de Objetos Signer que compõem o grupo de assinantes | **[Objeto Signer](#objeto-signer)** |

---

# Remoção de Grupos de Assinantes do Investidor

URL: /documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor-remocao

Este endpoint permite a remoção de grupos de assinantes associados a um investidor previamente cadastrado.

:::danger Atenção
Não é possível remover grupo de assinantes de um investidor Pessoa Física (PF).
:::

---

## Request
ENDPOINT /investor_management/investor/ INVESTOR-KEY /signer_group/ SIGNER-GROUP-KEY
MÉTODO DELETE

### Path Params

| Campo              | Tipo   | Descrição                                                 | Caracteres |
|--------------------|--------|----------------------------------------------------------|------------|
| `INVESTOR-KEY`       | string | Chave única do investidor (UUID v4).                         | 36         |
| `SIGNER-GROUP-KEY` | string | Chave única do grupo de assinantes a ser removido (UUID v4). | 36         |

## Response
STATUS 204

Nenhum conteúdo é retornado no corpo da resposta.

---

# Cadastro Básico do Investidor

URL: /documentation/escrituracao/homologacao-investidor/cadastro/cadastro-basico

Este endpoint permite cadastrar as informações básicas de um investidor. O mesmo endpoint é utilizado tanto para investidores **pessoa jurídica (PJ)** quanto **pessoa física (PF)** — o corpo da requisição varia de acordo com o campo `person_type`.

## Request

ENDPOINT /investor_management/investor
MÉTODO POST

### Request Body

Caso 01: Pessoa Jurídica
```json
{
  "name": "Empresa Exemplo S.A.",
  "document_number": "12.345.678/0001-95",
  "trading_name": "Exemplo Comércio",
  "cnae_code": "62.02-3-00",
  "company_type": "sa",
  "foundation_date": "2000-01-01",
  "address": {
      "street": "Rua das Empresas",
      "neighborhood": "Centro",
      "number": "123",
      "postal_code": "01001-000",
      "city": "São Paulo",
      "state": "SP",
      "complement": "Sala 101"
  }
}
```

Caso 02: Pessoa Física
```json
{
  "person_type": "natural",
  "name": "Maria Exemplo da Silva",
  "document_number": "123.456.789-00",
  "document_identification_number": "12.345.678-9",
  "marital_status": "single",
  "property_system": null,
  "birthdate": "1990-05-14",
  "nationality": "BRA",
  "mother_name": "Joana Exemplo da Silva",
  "father_name": "José Exemplo da Silva",
  "occupation": "engenheira de software",
  "is_pep": false,
  "email": "maria.exemplo@example.com",
  "phone_number": "+5511999999999",
  "investor_category": "retail",
  "investment_suitability": "moderate",
  "address": {
      "street": "Rua Exemplo",
      "neighborhood": "Centro",
      "number": "45",
      "postal_code": "01001-000",
      "city": "São Paulo",
      "state": "SP",
      "complement": "Apto 12"
  }
}
```

:::warning Atenção
Se o campo `person_type` for omitido, o cadastro é tratado como **Pessoa Jurídica** (`legal`). Para cadastrar um investidor **Pessoa Física**, envie `person_type: "natural"`.
:::

### Request Body Params — Pessoa Jurídica

| Campo                 | Tipo   | Descrição                                           | Caracteres Máx.                                               |
| --------------------- | ------ | ----------------------------------------------------- | -------------------------------------------------------------- |
| `person_type`        | string | Opcional. Se omitido, o cadastro é tratado como Pessoa Jurídica (`legal`). | **[Enumeradores person_type](#enumeradores-person_type)** |
| `name` *            | string | Nome completo da empresa.                             | 255                                                            |
| `document_number` * | string | CNPJ da empresa (formato "XX.XXX.XXX/XXXX-XX").       | 14                                                             |
| `trading_name`*     | string | Nome fantasia da empresa.                             | 1023                                                           |
| `cnae_code`*        | string | Código CNAE da empresa (formato "XXXXX-XXX").        | 7                                                              |
| `company_type`*     | string | Tipo da empresa.                                      | **[Enumeradores company_type](#enumeradores-company_type)** |
| `foundation_date`*  | string | Data de fundação da empresa (formato "YYYY-MM-DD"). | -                                                              |
| `address` *         | object | Objeto referenciando o endereço                      | **[Objeto address](#objeto-address)**                       |

### Request Body Params — Pessoa Física

| Campo                              | Tipo    | Descrição                                                                 | Caracteres Máx.                                                 |
| ----------------------------------- | ------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `person_type` *                   | string | Deve ser enviado como `"natural"`.                                          | **[Enumeradores person_type](#enumeradores-person_type)**       |
| `name` *                          | string | Nome completo do investidor.                                                | 255                                                              |
| `document_number` *               | string | CPF do investidor (formato "XXX.XXX.XXX-XX").                              | 14                                                               |
| `document_identification_number`* | string | Número do documento de identidade do investidor (RG, CNH ou passaporte).    | 255                                                               |
| `marital_status`*                 | string | Estado civil do investidor.                                                  | **[Enumeradores marital_status](#enumeradores-marital_status)** |
| `property_system`                  | string | Regime de bens. Obrigatório apenas quando `marital_status` exigir regime de bens. | **[Enumeradores property_system](#enumeradores-property_system)** |
| `birthdate`*                      | string | Data de nascimento do investidor (formato "YYYY-MM-DD").                    | -                                                                 |
| `nationality`*                    | string | Nacionalidade do investidor.                                                 | **[Enumeradores nationality](#enumeradores-nationality)**       |
| `mother_name`*                    | string | Nome da mãe do investidor.                                                   | 1023                                                              |
| `father_name`*                    | string | Nome do pai do investidor.                                                   | 1023                                                              |
| `occupation`*                     | string | Ocupação/profissão do investidor.                                           | 255                                                               |
| `is_pep`*                         | boolean | Indica se o investidor é uma Pessoa Politicamente Exposta.                  | -                                                                 |
| `email`*                          | string | E-mail de contato do investidor.                                             | 1023                                                              |
| `phone_number`*                   | string | Telefone de contato do investidor.                                          | 20                                                                |
| `investor_category`                | string | Categoria autodeclarada do investidor. Opcional.                            | **[Enumeradores investor_category](#enumeradores-investor_category)** |
| `investment_suitability`           | string | Perfil de suitability autodeclarado do investidor. Opcional.                | **[Enumeradores investment_suitability](#enumeradores-investment_suitability)** |
| `address` *                        | object | Objeto referenciando o endereço                                             | **[Objeto address](#objeto-address)**                            |

### Objeto Address

| Campo             | Tipo   | Descrição                                  | Caracteres Máx. |
| ----------------- | ------ | -------------------------------------------- | ---------------- |
| `street` *      | string | Nome da rua do endereço.                     | 500              |
| `neighborhood` * | string | Nome do bairro do endereço.                  | 100              |
| `number` *      | string | Número do endereço.                        | 10               |
| `postal_code` * | string | CEP do endereço (formatação "XXXXX-XXX"). | 8                |
| `city` *        | string | Nome da cidade do endereço.                 | 255              |
| `state` *       | string | Sigla do estado (2 caracteres).              | 2                |
| `complement`    | string | Complemento do endereço, se aplicável.     | 100              |

### Enumeradores company_type

| Enum     | Description        |
| -------- | ------------------ |
| `ltda` | Limitada           |
| `sa`   | Sociedade Anônima |
| `cop`  | Cooperativa        |

### Enumeradores marital_status

| Enum          | Description  |
| ------------- | ------------ |
| `single`    | Solteiro(a)  |
| `married`   | Casado(a)    |
| `divorced`  | Divorciado(a)|
| `widowed`   | Viúvo(a)    |
| `separated` | Separado(a)  |

### Enumeradores property_system

| Enum                                    | Description                            |
| ---------------------------------------- | --------------------------------------- |
| `total_communion_of_goods`             | Comunhão universal de bens             |
| `partial_communion_of_goods`           | Comunhão parcial de bens                |
| `total_separation_of_goods`            | Separação total de bens                |
| `final_participation_of_acquisitions`  | Participação final nos aquestos        |
| `compulsory_separation_of_goods`       | Separação obrigatória de bens          |

### Enumeradores nationality

Lista completa de códigos [ISO 3166-1 alpha-3](https://www.iso.org/obp/ui/#search) (ex.: `BRA` para Brasil, `USA` para Estados Unidos).

### Enumeradores investor_category

| Enum              | Description       |
| ------------------ | ------------------ |
| `not_applicable` | Não aplicável      |
| `retail`         | Varejo             |
| `qualified`      | Qualificado        |
| `professional`   | Profissional       |

### Enumeradores investment_suitability

| Enum          | Description   |
| ------------- | ------------- |
| `conservative` | Conservador  |
| `moderate`    | Moderado      |
| `bold`        | Arrojado      |

## Response

STATUS 201

Caso 01: Pessoa Jurídica

```json
{
    "investor_key": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Empresa Exemplo S.A.",
    "document_number": "12.345.678/0001-95",
    "status": "in_filling",
    "person_type": "legal",
    "trading_name": "Exemplo Comércio",
    "cnae_code": "62.02-3-00",
    "company_type": "sa",
    "foundation_date": "2000-01-01",
    "address": {
      "street": "Rua das Empresas",
      "neighborhood": "Centro",
      "number": "123",
      "postal_code": "01001-000",
      "city": "São Paulo",
      "state": "SP",
      "complement": "Sala 101"
    },
    "registration_datetime": "2023-01-01T12:00:00Z",
    "expiration_date": "2024-01-01T12:00:00Z"
  }
```

Caso 02: Pessoa Física

```json
{
  "investor_key": "9f8e7d6c-5b4a-3210-9876-543210fedcba",
  "name": "Maria Exemplo da Silva",
  "document_number": "123.456.789-00",
  "status": "in_filling",
  "person_type": "natural",
  "document_identification_number": "12.345.678-9",
  "marital_status": "single",
  "birthdate": "1990-05-14",
  "nationality": "BRA",
  "occupation": "engenheira de software",
  "is_pep": false,
  "investor_category": "retail",
  "investment_suitability": "moderate",
  "address": {
    "street": "Rua Exemplo",
    "neighborhood": "Centro",
    "number": "45",
    "postal_code": "01001-000",
    "city": "São Paulo",
    "state": "SP",
    "complement": "Apto 12"
  },
  "registration_datetime": "2023-01-01T12:00:00Z",
  "expiration_date": "2024-01-01T12:00:00Z",
  "investor_contact_information_list": [
    {
      "investor_contact_information_key": "3f1e2d3c-4b5a-6978-8899-aabbccddeeff",
      "name": "Maria Exemplo da Silva",
      "document_number": "123.456.789-00",
      "email": "maria.exemplo@example.com",
      "phone_number": "+5511999999999",
      "is_default": true
    }
  ],
  "signer_group_list": [
    {
      "signer_group_key": "7a6b5c4d-3e2f-1a0b-9c8d-1234567890ab",
      "minimum_required_signers": 1,
      "signers": [
        {
          "name": "Maria Exemplo da Silva",
          "document_number": "123.456.789-00",
          "email": "maria.exemplo@example.com",
          "phone_number": "+5511999999999",
          "is_group_mandatory": true
        }
      ]
    }
  ]
}
```

:::info Informação
`investor_contact_information_list` e `signer_group_list` só são retornados quando o cadastro é feito com acesso completo (`data_access_type == full_access`).
:::

### Response Body Params

| Campo                     | Tipo    | Pessoa      | Descrição                              | Caracteres Máx.                                                 |
| ------------------------- | ------- | ----------- | ----------------------------------------- | ----------------------------------------------------------------- |
| `investor_key`          | string | Ambos       | Chave única do investidor (UUID).        | 36                                                                |
| `name`                  | string | Ambos       | Nome completo (PF) ou razão social (PJ). | 255                                                                |
| `document_number`       | string | Ambos       | CPF (PF) ou CNPJ (PJ) do investidor.      | 14                                                                 |
| `status`                | string | Ambos       | Status do investidor.                     | -                                                                  |
| `person_type`           | string | Ambos       | Tipo de pessoa                            | **[Enumeradores person_type](#enumeradores-person_type)**       |
| `trading_name`          | string | Somente PJ  | Nome fantasia do investidor.              | 1023                                                               |
| `cnae_code`             | string | Somente PJ  | Código CNAE do investidor.               | 7                                                                  |
| `company_type`          | string | Somente PJ  | Tipo da empresa                           | **[Enumeradores company_type](#enumeradores-company_type)**     |
| `foundation_date`       | string | Somente PJ  | Data de fundação do investidor.         | -                                                                  |
| `document_identification_number` | string | Somente PF | Número do documento de identidade do investidor. | 255                                                     |
| `marital_status`        | string | Somente PF  | Estado civil do investidor.               | **[Enumeradores marital_status](#enumeradores-marital_status)** |
| `birthdate`             | string | Somente PF  | Data de nascimento do investidor.        | -                                                                  |
| `nationality`           | string | Somente PF  | Nacionalidade do investidor.              | **[Enumeradores nationality](#enumeradores-nationality)**       |
| `occupation`            | string | Somente PF  | Ocupação/profissão do investidor.        | 255                                                                |
| `is_pep`                | boolean | Somente PF  | Indica se o investidor é PEP.             | -                                                                  |
| `investor_category`     | string | Somente PF  | Categoria autodeclarada do investidor.    | **[Enumeradores investor_category](#enumeradores-investor_category)** |
| `investment_suitability`| string | Somente PF  | Perfil de suitability autodeclarado.      | **[Enumeradores investment_suitability](#enumeradores-investment_suitability)** |
| `address`               | object | Ambos       | Objeto referenciando o endereço          | **[Objeto address](#objeto-address)**                            |
| `investor_contact_information_list` | array | Somente PF | Lista de informações de contato do investidor. Apenas com `data_access_type == full_access`. | - |
| `signer_group_list`     | array  | Somente PF  | Lista de grupos de assinantes do investidor. Apenas com `data_access_type == full_access`. | - |
| `registration_datetime` | string | Ambos       | Data e hora de registro do investidor.    | -                                                                  |
| `expiration_date`       | string | Ambos       | Data de expiração do investidor.         | -                                                                  |

### Enumeradores person_type

| Enum        | Description      |
| ----------- | ---------------- |
| `legal`   | Pessoa Jurídica |
| `natural` | Pessoa Física   |

---

# Cadastro de Conta Bancária do Investidor

URL: /documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor

Este endpoint permite o cadastro de conta bancária associada a um investidor previamente cadastrado.

---

## Request

ENDPOINT /investor_management/investor/ INVESTOR-KEY /bank_account
MÉTODO POST

### Path Params

| Campo            | Tipo   | Descrição                           | Caracteres |
| ---------------- | ------ | ------------------------------------- | ---------- |
| `INVESTOR-KEY` | string | Chave única do investidor (UUID v4). | 36         |

### Request Body

Request Body
```json
{
  "account_number": "12345678",
  "account_digit": "1",
  "account_branch": "1234",
  "financial_institution_code_number": "001",
  "financial_institution_ispb": "00000000",
  "account_type": "checking"
}
```

### Request Body Params

| Campo                                  | Tipo   | Descrição                                                  | Máximo de Caracteres                                          |
| -------------------------------------- | ------ | ------------------------------------------------------------ | -------------------------------------------------------------- |
| `account_number` *                   | string | Número da conta bancária. Deve conter apenas dígitos.     | 20                                                             |
| `account_digit` *                    | string | Dígito verificador da conta. Deve conter um único dígito. | 1                                                              |
| `account_branch` *                   | string | Número da agência bancária. Deve conter apenas dígitos.  | 6                                                              |
| `financial_institution_code_number`* | string | Código da instituição financeira (3 dígitos).            | 3                                                              |
| `financial_institution_ispb` *       | string | Código ISPB da instituição financeira (8 dígitos).       | 8                                                              |
| `account_type` *                     | string | Tipo da conta bancária.                                     | **[Enumeradores account_type](#enumeradores-account_type)** |

### Enumeradores account_type

| Enum         | Description        |
| ------------ | ------------------ |
| `checking` | Conta corrente     |
| `savings`  | Conta Poupança    |
| `salary`   | Conta Salário     |
| `payment`  | Conta de Pagamento |

## Response

STATUS 201

Response Body

```json
{
  "bank_account_key": "123e4567-e89b-12d3-a456-426614174000",
  "account_number": "12345678",
  "account_digit": "1",
  "account_branch": "1234",
  "financial_institution_code_number": "001",
  "financial_institution_ispb": "00000000",
  "account_type": "checking"
}
```

### Response Body Params

| Campo                                 | Tipo   | Descrição                                                   | Máximo de Caracteres                                          |
| ------------------------------------- | ------ | ------------------------------------------------------------- | -------------------------------------------------------------- |
| `bank_account_key`                  | string | Identificador único da conta bancária cadastrada (UUID v4). | 36                                                             |
| `account_number`                    | string | Número da conta bancária.                                   | 20                                                             |
| `account_digit`                     | string | Dígito verificador da conta bancária.                       | 1                                                              |
| `account_branch`                    | string | Número da agência bancária.                                | 6                                                              |
| `financial_institution_code_number` | string | Código da instituição financeira.                          | 3                                                              |
| `financial_institution_ispb`        | string | Código ISPB da instituição financeira.                     | 8                                                              |
| `account_type`                      | string | Tipo da conta bancária.                                      | **[Enumeradores account_type](#enumeradores-account_type)** |

---

# Remoção de Conta Bancária do Investidor

URL: /documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor-remocao

Este endpoint permite a remoção de conta bancária associada a um investidor previamente cadastrado.

---

## Request
ENDPOINT /investor_management/investor/ INVESTOR-KEY /bank_account/ BANK-ACCOUNT-KEY
MÉTODO DELETE

### Path Params

| Campo              | Tipo   | Descrição                                              | Caracteres |
|--------------------|--------|------------------------------------------------------|------------|
| `INVESTOR-KEY`       | string | Chave única do investidor (UUID v4).                     | 36         |
| `BANK-ACCOUNT-KEY` | string | Chave única da conta bancária a ser removida (UUID v4).| 36         |

---

## Response
STATUS 204

Nenhum conteúdo é retornado no corpo da resposta.

---

---

# Envio de Documentos do Investidor

URL: /documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor

Este endpoint permite o envio de documentos associados a um investidor previamente cadastrado.

---

## Request
ENDPOINT /investor_management/investor/ INVESTOR-KEY /document
MÉTODO POST

### Path Params

| Campo         | Tipo   | Descrição                                | Caracteres |
|---------------|--------|------------------------------------------|------------|
| `INVESTOR-KEY`  | string | Chave única do investidor (UUID v4).         | 36         |

### Request Body

Request Body
```json
{
  "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0",
  "document_type": "proof_of_address"
}
```

### Request Body Params

| Campo             | Tipo     | Descrição                                                                                  | Caracteres Máx.                                               |
|--------------------|----------|------------------------------------------------------------------------------------------|---------------------------------------------------------------|
| `document_base64` *| string   | Conteúdo do arquivo do documento codificado em Base64.                                    | -                                                             |
| `document_type` *  | string   | Tipo do documento enviado. Os valores aceitos variam de acordo com o `person_type` do investidor. | **[Enumeradores document_type](#enumeradores-document_type)** |

### Enumeradores document_type

Os valores aceitos dependem do `person_type` do investidor.

**Pessoa Jurídica**

| Enum   | Description                |
|--------|-----------------------------|
| `danfe` | DANFE                       |
| `proof_of_address` | Comprovante de Endereço     |
| `letter_of_attorney` | Procuração                  |
| `company_statute` | Contrato ou Estatuto Social |

**Pessoa Física**

| Enum   | Description                |
|--------|-----------------------------|
| `cnh` | CNH                       |
| `cnh_front` | Frente da CNH               |
| `cnh_back` | Verso da CNH                |
| `cnh_digital` | PDF CNH Digital          |
| `rg_front` | Frente do RG                |
| `rg_back` | Verso do RG                  |
| `passport` | Passaporte                  |

## Response
STATUS 201

Response Body

```json
{
    "document_key": "123e4567-e89b-12d3-a456-426614174000",
    "document_type": "proof_of_address",
    "ocr_key": "123e4567-e89b-12d3-a456-426614174000"
}
```

### Response Body Params

| Field          | Type     | Description                                                        | Max Length |
|-----------------|----------|--------------------------------------------------------------------|------------|
| `document_key`   | string   | Identificador único do documento enviado (UUID v4). | 36                    |
| `document_type`  | string   | Tipo do documento enviado.                          | **[Enumeradores document_type](#enumeradores-document_type)** |
| `ocr_key`        | string   | Chave OCR associada ao documento enviado.           | 36                    |

---

# Remoção de Documentos do Investidor

URL: /documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor-remocao

Este endpoint permite a remoção de documentos enviados para o cadastro do investidor.

---

## Request
ENDPOINT /investor_management/investor/ INVESTOR-KEY /document/ DOCUMENT-KEY
MÉTODO DELETE

### Path Params

| Campo          | Tipo   | Descrição                                | Caracteres |
|----------------|--------|------------------------------------------|------------|
| `INVESTOR-KEY`   | string | Chave única do investidor (UUID v4).         | 36         |
| `DOCUMENT-KEY` | string | Chave única do documento a ser removido (UUID v4). | 36         |

## Response
STATUS 204

Nenhum conteúdo é retornado no corpo da resposta.

---

# Envio de Documentos do Representante do Investidor

URL: /documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor

Este endpoint permite o envio de documentos associados a um representante de um investidor previamente cadastrado.

:::danger Atenção
Não é possível adicionar documentos de representante para um investidor Pessoa Física (PF).
:::

---
## Request
ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_representative/ INVESTOR-REPRESENTATIVE-KEY /document
MÉTODO POST

### Path Params

| Campo                       | Tipo   | Descrição                                           | Caracteres |
|-----------------------------|--------|---------------------------------------------------|------------|
| `INVESTOR-KEY`                | string | Chave única do investidor (UUID v4).                  | 36         |
| `INVESTOR-REPRESENTATIVE-KEY` | string | Chave única do representante do investidor (UUID v4). | 36         |

### Request Body
Request Body
```json
{
  "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0",
  "document_type": "cnh"
}
```

### Request Body Params

| Campo             | Tipo     | Descrição                                                                                   | Máximo de Caracteres |
|--------------------|----------|-------------------------------------------------------------------------------------------|-----------------------|
| `document_base64` *| string   | Conteúdo do arquivo do documento codificado em Base64.                                     | -                     |
| `document_type` *  | string   | Tipo do documento enviado. Valores aceitos:          | **[Enumeradores document_type](#enumeradores-document_type)** |

### Enumeradores document_type
| Enum   | 	Description            |
|--------|-------------------------|
| `cnh` | CNH                     |
| `cnh_front`	  | Frente da CNH           |
| `cnh_back`	 | Verso da CNH            |
| `cnh_digital`	 | PDF CNH DIGITAL         
| `rg_front`	 | Frente do RG            |
|  `rg_back`	 | Verso do RG             |
|  `danfe`	 | DANFE                   |
|   `proof_of_address`	 | Comprovante de Endereço |
|  `letter_of_attorney`	 | Procuração              |

## Response
STATUS 201

Response Body

```json
{
  "document_key": "123e4567-e89b-12d3-a456-426614174000",
  "document_type": "cnh",
  "ocr_key": "123e4567-e89b-12d3-a456-426614174000"
}
```

### Response Body Params

| Campo           | Tipo     | Descrição                                           | Máximo de Caracteres |
|------------------|----------|-----------------------------------------------------|-----------------------|
| `document_key`   | string   | Identificador único do documento enviado (UUID v4). | 36                    |
| `document_type`  | string   | Tipo do documento enviado.                          | **[Enumeradores document_type](#enumeradores-document_type)** |
| `ocr_key`        | string   | Chave OCR associada ao documento enviado.           | 36                    |

---

# Remoção de Documentos do Representante do Investidor

URL: /documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor-remocao

Este endpoint permite a remoção de documentos associados a um representante de um investidor previamente cadastrado.

:::danger Atenção
Não é possível remover documentos de representante de um investidor Pessoa Física (PF).
:::

---

## Request
ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_representative/ INVESTOR-REPRESENTATIVE-KEY /document/ DOCUMENT-KEY
MÉTODO DELETE

### Path Params

| Campo                       | Tipo   | Descrição                                           | Caracteres |
|-----------------------------|--------|---------------------------------------------------|------------|
| `INVESTOR-KEY`                | string | Chave única do investidor (UUID v4).                  | 36         |
| `INVESTOR-REPRESENTATIVE-KEY` | string | Chave única do representante do investidor (UUID v4). | 36         |
| `DOCUMENT-KEY`              | string | Chave única do documento a ser removido (UUID v4). | 36         |

## Response
STATUS 204

Nenhum conteúdo é retornado no corpo da resposta.

---

# Cadastro de Informações de Contato do Investidor

URL: /documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor

Este endpoint permite o cadastro de informações de contato associadas a um investidor previamente cadastrado.

---

## Request

ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_contact_information
MÉTODO POST

### Path Params

| Campo            | Tipo   | Descrição                           | Caracteres |
| ---------------- | ------ | ------------------------------------- | ---------- |
| `INVESTOR-KEY` | string | Chave única do investidor (UUID v4). | 36         |

### Request Body

Request Body
```json
{
  "name": "João da Silva",
  "document_number": "123.456.789-01",
  "email": "joao.silva@email.com",
  "phone_number": "+5511999999999"
}
```

### Request Body Params

| Campo                 | Tipo   | Descrição                                                                                                       | Máximo de Caracteres |
| --------------------- | ------ | ----------------------------------------------------------------------------------------------------------------- | --------------------- |
| `name` *            | string | Nome completo do contato.                                                                                         | 255                   |
| `document_number` * | string | Número do documento do contato (formato CPF, "XX.XXX.XXX/XXXX-XX").                                              | 11                    |
| `email`*            | string | Endereço de email do contato.                                                                                    | 1023                  |
| `phone_number`*     | string | Número de telefone do contato (formatação completa: código do país, DDD e número. Exemplo: +5511999999999). | 20                    |

## Response

STATUS 201

Response Body

```json
{
  "investor_contact_information_key": "123e4567-e89b-12d3-a456-426614174000",
  "name": "João da Silva",
  "document_number": "123.456.789-01",
  "email": "joao.silva@email.com",
  "phone_number": "+5511999999999"
}
```

### Response Body Params

| Campo                                | Tipo   | Descrição                                                           | Máximo de Caracteres |
| ------------------------------------ | ------ | --------------------------------------------------------------------- | --------------------- |
| `investor_contact_information_key` | string | Identificador único da informação de contato cadastrada (UUID v4). | 36                    |
| `name`                             | string | Nome completo do contato.                                             | 255                   |
| `document_number`                  | string | Número do documento do contato (CPF).                                | 11                    |
| `email`                            | string | Endereço de email do contato.                                        | 1023                  |
| `phone_number`                     | string | Número de telefone do contato.                                       | 20                    |

---

# Remoção de Informações de Contato do Investidor

URL: /documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor-remocao

Este endpoint a remoção de informações de contato associadas a um investidor previamente cadastrado.

---

## Request
ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_contact_information/ INVESTOR-CONTACT-INFORMATION-KEY
MÉTODO DELETE

### Path Params

| Campo                            | Tipo   | Descrição                                                   | Caracteres |
|----------------------------------|--------|-----------------------------------------------------------|------------|
| `INVESTOR-KEY`                     | string | Chave única do investidor (UUID v4).                          | 36         |
| `INVESTOR-CONTACT-INFORMATION-KEY` | string | Chave única da informação de contato a ser removida (UUID v4).| 36         |

## Response
STATUS 204

Nenhum conteúdo é retornado no corpo da resposta.

---

# Cadastro de Representantes do Investidor

URL: /documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor

Este endpoint permite o cadastro de representantes associados a um investidor previamente cadastrado.

:::danger Atenção
Não é possível adicionar representante para um investidor Pessoa Física (PF).
:::

---

## Request

ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_representative
MÉTODO POST

### Path Params

| Campo            | Tipo   | Descrição                           | Caracteres |
| ---------------- | ------ | ------------------------------------- | ---------- |
| `INVESTOR-KEY` | string | Chave única do investidor (UUID v4). | 36         |

### Request Body

Request Body
```json
{
  "name": "João da Silva",
  "document_number": "123.456.789-01",
  "birthdate": "1990-01-01",
  "nationality": "Brasileiro",
  "mother_name": "Maria da Silva",
  "address": {
      "street": "Rua das Empresas",
      "neighborhood": "Centro",
      "number": "123",
      "postal_code": "01001-000",
      "city": "São Paulo",
      "state": "SP",
      "complement": "Sala 101"
  }
}
```

### Request Body Params

| Campo                               | Tipo    | Descrição                                                           | Máximo de Caracteres                                                |
| ----------------------------------- | ------- | --------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `name` *                          | string  | Nome completo do representante do investidor.                         | 255                                                                  |
| `document_number` *               | string  | Número do documento (CPF, formato "XX.XXX.XXX/XXXX-XX").            | 11                                                                   |
| `birthdate`*                      | string  | Data de nascimento do representante no formato ISO 8601 (YYYY-MM-DD). | -                                                                    |
| `document_identification_number`* | string  | Número do documento de identificação.                              | 255                                                                  |
| `marital_status`*                 | string  | Estado civil do representante.                                        | **[Enumeradores marital_status](#enumeradores-marital_status)**   |
| `property_system`*                | string  | Regime de bens.                                                       | **[Enumeradores property_system](#enumeradores-property_system)** |
| `nationality`*                    | string  | Nacionalidade do representante do investidor.                         | 255                                                                  |
| `mother_name`                     | string  | Nome completo da mãe do representante.                               | 1023                                                                 |
| `father_name`                     | string  | Nome completo do pai do representante.                                | 1023                                                                 |
| `occupation`*                     | string  | Ocupação ou profissão do representante.                            | 255                                                                  |
| `is_pep`*                         | boolean | Indica se o representante é uma Pessoa Politicamente Exposta (PEP).  | -                                                                    |
| `address` *                       | string  | Objeto referenciando o endereço                                      | **[Objeto address](#objeto-address)**                             |

### Objeto Address

| Campo             | Tipo   | Descrição                              | Caracteres Máx. |
| ----------------- | ------ | ---------------------------------------- | ---------------- |
| `street` *      | string | Nome da rua do endereço da empresa.     | 500              |
| `neighborhood`  | string | Nome do bairro do endereço da empresa.  | 100              |
| `number` *      | string | Número do endereço.                    | 10               |
| `postal_code` * | string | CEP do endereço (somente números).     | 8                |
| `city` *        | string | Nome da cidade do endereço.             | 255              |
| `state` *       | string | Sigla do estado (2 caracteres).          | 2                |
| `complement`    | string | Complemento do endereço, se aplicável. | 100              |

### Enumeradores marital_status

| Enum             | Description        |
| ---------------- | ------------------ |
| `single`       | Solteiro(a)        |
| `married`      | Casado(a)          |
| `widower`      | Viúvo(a)          |
| `separated`    | Separado(a)        |
| `stable_union` | em União Estável |
| `divorced`     | Divorciado(a)      |

### Enumeradores property_system

| Enum                                    | Description                       |
| --------------------------------------- | --------------------------------- |
| `total_communion_of_goods`            | Comunhão Total de Bens           |
| `partial_communion_of_goods`          | Comunhão Parcial de Bens         |
| `total_separation_of_goods`           | Separação Total de Bens         |
| `final_participation_of_acquisitions` | Participação Final nos Aquestos |
| `compulsory_separation_of_goods`      | Separação Compulsória de Bens  |

## Response

STATUS 201

Response Body

```json
{
  "investor_representative_key": "123e4567-e89b-12d3-a456-426614174000",
  "name": "João da Silva",
  "document_number": "123.456.789-01",
  "document_identification_number": "987654321",
  "marital_status": "single",
  "property_system": "partial_communion_of_goods",
  "birthdate": "1990-01-01",
  "nationality": "Brasileiro",
  "mother_name": "Maria da Silva",
  "father_name": "José da Silva",
  "occupation": "Advogado",
  "is_pep": false,
  "address": {
      "street": "Rua das Empresas",
      "neighborhood": "Centro",
      "number": "123",
      "postal_code": "01001-000",
      "city": "São Paulo",
      "state": "SP",
      "complement": "Sala 101"
  },
  "investor_representative_document_list": []
}
```

### Response Body Params

| Campo                                     | Tipo    | Descrição                                                          | Máximo de Caracteres                                                |
| ----------------------------------------- | ------- | -------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `investor_representative_key`           | string  | Identificador único do representante do investidor (UUID v4).       | 36                                                                   |
| `name`                                  | string  | Nome completo do representante do investidor.                        | 255                                                                  |
| `document_number`                       | string  | Número do documento do representante (formato CPF).                 | 11                                                                   |
| `document_identification_number`        | string  | Número do documento de identificação.                             | 255                                                                  |
| `marital_status`                        | string  | Estado civil do representante.                                       | **[Enumeradores marital_status](#enumeradores-marital_status)**   |
| `property_system`                       | string  | Regime de bens.                                                      | **[Enumeradores property_system](#enumeradores-property_system)** |
| `birthdate`                             | string  | Data de nascimento do representante.                                 | -                                                                    |
| `nationality`                           | string  | Nacionalidade do representante do investidor.                        | 255                                                                  |
| `mother_name`                           | string  | Nome completo da mãe do representante.                              | 1023                                                                 |
| `father_name`                           | string  | Nome completo do pai do representante.                               | 1023                                                                 |
| `occupation`                            | string  | Ocupação ou profissão do representante.                           | 255                                                                  |
| `is_pep`                                | boolean | Indica se o representante é uma Pessoa Politicamente Exposta (PEP). | -                                                                    |
| `address` *                             | string  | Objeto referenciando o endereço                                     | **[Objeto address](#objeto-address)**                             |
| `investor_representative_document_list` | array   | Lista de documentos associados ao representante.                     | -                                                                    |

---

# Remoção de Representante do Investidor

URL: /documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor-remocao

Este endpoint permite a remoção de representantes enviados para o cadastro do investidor.

:::danger Atenção
Não é possível remover representante de um investidor Pessoa Física (PF).
:::

---

## Request
ENDPOINT /investor_management/investor/ INVESTOR-KEY /investor_representative/ INVESTOR-REPRESENTATIVE-KEY
MÉTODO DELETE

### Path Params

| Campo                       | Tipo   | Descrição                                              | Caracteres |
|-----------------------------|--------|--------------------------------------------------------|------------|
| `INVESTOR-KEY`                | string | Chave única do investidor (UUID v4).                      | 36         |
| `INVESTOR-REPRESENTATIVE-KEY` | string | Chave única do representante a ser removido (UUID v4). | 36         |

## Response
STATUS 204

Nenhum conteúdo é retornado no corpo da resposta.

---

# Consulta de Investidor

URL: /documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-chave

Este endpoint permite consultar os detalhes completos de um investidor cadastrado no sistema, utilizando sua chave única.

---

## Request
ENDPOINT /investor_management/investor/ INVESTOR-KEY
MÉTODO GET

### Path Params

| Campo        | Tipo   | Descrição                                | Caracteres |
|--------------|--------|------------------------------------------|------------|
| `INVESTOR-KEY` | string | Chave única do investidor (UUID v4).         | 36         |

## Response
STATUS 200

Response Body

```json
{
    "investor_key": "07b1ac01-5fc4-475f-930b-19595f24bc1e",
    "name": "Fabrica Exemplo S.A.",
    "document_number": "96.146.194/0001-07",
    "status": "in_filling",
    "backoffice_analysis_status": "in_analysis",
    "person_type": "legal",
    "trading_name": "Fabrica Comércio",
    "cnae_code": "62.02-3-00",
    "company_type": "sa",
    "foundation_date": "2000-01-01",
    "address": {
      "street": "Rua das Empresas",
      "neighborhood": "Centro",
      "number": "123",
      "postal_code": "01001-000",
      "city": "São Paulo",
      "state": "SP",
      "complement": "Sala 101"
    },
    "registration_datetime": "2025-01-23T13:47:57.354528",
    "expiration_date": "2026-01-23",
    "signer_group_list": [],
    "bank_account_list": [],
    "investor_representative_list": [],
    "investor_contact_information_list": [],
    "investor_document_list": [],
    "investor_analysis_list": []
}
```

### Response Body Params

| Campo  | Tipo     | Descrição                                              | Máximo de Caracteres |
|--------|----------|--------------------------------------------------------|-----------------------|
| `investor_key` | string   | Identificador único do investidor.                        | 36                    |
| `name` | string   | Nome completo do investidor.                              | 255                   |
| `document_number` | string   | Número do documento do investidor (CNPJ).                 | 14                    |
| `status` | string   | Status do investidor                                      | **[Enumeradores status](#enumeradores-status)** |
| `backoffice_analysis_status`| string   | Status de análise do backoffice.                       | -                     |
| `person_type` | string   | Tipo de pessoa (`legal` ou `natural`).                 | -                     |
| `trading_name` | string   | Nome fantasia do investidor.                              | 1023                  |
| `cnae_code` | string   | Código CNAE do investidor.                                | 7                     |
| `company_type` | string   | Tipo de empresa Aceitos: ´sa´, ´ltda´, ´cop´                          | 50                    |
| `foundation_date` | string   | Data de fundação do investidor.                           | -                     |
| `signer_group_list` | array    | Lista de grupos de assinantes associados ao investidor.   | -                     |
| `bank_account_list` | array    | Lista de contas bancárias associadas ao investidor.       | -                     |
| `investor_representative_list` | array    | Lista de representantes do investidor.                    | -                     |
| `investor_contact_information_list` | array    | Lista de informações de contato associadas ao investidor. | -                     |
| `investor_document_list` | array    | Lista de documentos cadastrados para o investidor.        | -                     |
| `address` *         | string   | Objeto referenciando o endereço                   | **[Objeto address](#objeto-address)**|

### Objeto Address

| Campo               | Tipo     | Descrição                                           | Caracteres Máx. |
|---------------------|----------|-----------------------------------------------------|-----------------|
| `street` *          | string   | Nome da rua do endereço da empresa.                 | 500             |
| `neighborhood`      | string   | Nome do bairro do endereço da empresa.              | 100             |
| `number` *          | string   | Número do endereço.                                 | 10              |
| `postal_code` *     | string   | CEP do endereço (somente números).                  | 8               |
| `city` *            | string   | Nome da cidade do endereço.                         | 255             |
| `state` *           | string   | Sigla do estado (2 caracteres).                     | 2               |
| `complement`        | string   | Complemento do endereço, se aplicável.              | 100             |

### Enumeradores status
| Enum   | 	Description    |
|--------|-----------------|
| `in_filling` | Em preenchimento |
| `in_analysis`	  | Em análise      |
| `canceled`	 | Cancelado       |
| `approved`	 | Aprovado        |
| `reproved`	 | Reprovado       |
| `expired`	 | Expirado        |

---

# Consulta de Investidores por filtros

URL: /documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-filtro

Este endpoint permite consultar investidores cadastrados no sistema utilizando o número de documento (CNPJ) ou Nome.

---

## Request
ENDPOINT /investor_management/investor
MÉTODO GET

### Query Params

| Campo             | Tipo     | Descrição                          | Obrigatório |
|-------------------|----------|------------------------------------|-------------|
| `document_number` | string   | Número do documento do investidor.    | Não         |
| `name`            | string   | Nome do investidor.                   | Não         |
| `page`            | integer  | Página atual da consulta.          | Não         |
| `rows_per_page`   | integer  | Número de registros por página.    | Não         |

## Response
STATUS 200

Response Body

```json
{
  "data": [
    {
        "investor_key": "495ae701-5c38-49b1-b517-a3b910fe8d8f",
        "name": "Empresa Exemplo S.A.",
        "document_number": "12.345.678/0001-95",
        "status": "in_filling"
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "rows_per_page": 100,
    "total_pages": 1,
    "total_rows": 1
  }
}
```

### Response Body Params

| Campo        | Tipo   | Descrição           |                                                                 |
|--------------|--------|---------------------|-----------------------------------------------------------------|
| `data`       | list   | Lista de resultados | **[Objeto Investidor Simplificado](#objeto-investidor-simplificado)** |
| `pagination` | object | Dados de paginação  | **[Objeto Paginação](#objeto-paginacao)**                       |

### Objeto Investidor Simplificado

| Campo            | Tipo     | Descrição                                                     | Máximo de Caracteres                            |
|-------------------|----------|-------------------------------------------------------------|-------------------------------------------------|
| `investor_key` | string   | Identificador único do investidor (UUID v4).                  | 36                                              |
| `name`     | string   | Nome completo do investidor.                                   | 255                                             |
| `document_number` | string | Número do documento do investidor (CNPJ).                   | 14                                              |
| `status`   | string   | Status atual do investidor.                 | **[Enumeradores status](#enumeradores-status)** |

### Enumeradores status
| Enum   | 	Description    |
|--------|-----------------|
| `in_filling` | Em preenchimento |
| `in_analysis`	  | Em análise      |
| `canceled`	 | Cancelado       |
| `approved`	 | Aprovado        |
| `reproved`	 | Reprovado       |
| `expired`	 | Expirado        |

### Objeto Pagination

| Campo             | Tipo     | Descrição                                |
|-------------------|----------|------------------------------------------|
| `current_page`    | integer  | Página atual da consulta.                |
| `next_page`       | integer  | Próxima página, caso exista.             |
| `rows_per_page`   | integer  | Número de registros por página.          |
| `total_pages`     | integer  | Número total de páginas.                 |
| `total_rows`      | integer  | Número total de registros encontrados.   |

---

# Envio para Análise do Investidor

URL: /documentation/escrituracao/homologacao-investidor/envio-analise/

Este endpoint permite alterar o status de um investidor para análise, enviando-o para o processo de validação.

---

## Request
ENDPOINT /investor_management/investor/ INVESTOR-KEY
MÉTODO PATCH

### Path Params

| Campo        | Tipo   | Descrição                                | Caracteres |
|--------------|--------|------------------------------------------|------------|
| `INVESTOR-KEY` | string | Chave única do investidor (UUID v4).         | 36         |

### Request Body

Request Body
```json
{
  "investor_status": "in_analysis"
}
```

### Request Body Params

| Campo           | Tipo     | Descrição                                         | Obrigatório |
|------------------|----------|-------------------------------------------------|-------------|
| `investor_status`  | string   | Novo status do investidor. Valor aceito: `in_analysis`. | Sim         |

## Response
 A resposta é um json completo atualizado do investidor.

---

# Introdução

URL: /documentation/escrituracao/homologacao-investidor/inicio

A parte de cadastro de Investidores é essencial para o início da emissão de Notas Comerciais. Nessa seção iremos explicar todo o fluxo, desde o envio das primeiras informações, até o envio para análise.

Para ter acesso aos serviços discutidos nas próximas sessões, entre em contato com o time [suporte-dcm@qitech.com.br](mailto:suporte-dcm@qitech.com.br), para que seja feito as devidas liberações, tanto em ambiente de Homologação (Sandbox) quanto em ambiente de produção.

### Cadastro do Investidor

Nessa etapa, deve-se enviar todas as informações tanto do Investidor quanto dos seus representantes, documentos, informações de contato, grupos de assinantes e contas bancárias.

Uma vez que o envio das informações estiver concluído, o cadastro é enviado para análise e após aprovação este investidor estará apto a participar da emissão de Notas.

### Atualização de Investidor

Em caso de necessidade de atualização cadastral, deve-se enviar novamente todas as informações do Investidor com as modificações desejadas. Após envio, é gerada uma nova Análise para validação. 

Assim que esta nova Análise for aprovada, os novos dados cadastrais do Investidor são efetivamente alterados.

---

# **Solicitação de Acesso aos Dados do Investidor**

URL: /documentation/escrituracao/homologacao-investidor/solicitacao-acesso

Clientes que cadastraram um investidor que já possui um **cadastro único** precisam **solicitar acesso aos dados do investidor** para que possam emitir operações com esse investidor como parte.  

Ao realizar essa solicitação, o **investidor receberá um e-mail com instruções para aprovar ou recusar o acesso**.

---

## **Solicitação de Acesso (POST)**

### **Request**
ENDPOINT /investor_management/investor/ INVESTOR-KEY /data_access_request
MÉTODO POST

### **Path Params**

| Campo          | Tipo   | Descrição                                     | Caracteres Máx. |
|---------------|--------|-----------------------------------------------|-----------------|
| `INVESTOR-KEY` * | string | Chave única do investidor (UUID v4).             | 36              |

---

## **Request Body**  

Nenhum corpo de requisição é necessário.

---

## **Response**
STATUS 201

Response Body

```json
{
    "data_access_request_key": "6beb9e44-1513-4d3b-9af5-f3c39ebbf2d0",
    "requested_at": "2025-02-22T10:45:49.609517",
    "responded_at": null,
    "data_access_request_status": "in_analysis"
}
```

### **Response Body Params**

| Campo                          | Tipo     | Descrição                                                   | Caracteres Máx. |
|--------------------------------|----------|-------------------------------------------------------------|-----------------|
| `data_access_request_key` *    | string   | Chave única da solicitação de acesso (UUID v4).             | 36              |
| `requested_at` *               | string   | Data e hora da solicitação (formato ISO 8601).              | -               |
| `responded_at`                 | string   | Data e hora da resposta à solicitação, se já respondida.    | -               |
| `data_access_request_status` * | string   | Status da solicitação. | **[Enumeradores data_access_request_status](#enumeradores-data_access_request_status)** |

---

## **Consulta do Status da Solicitação (GET)**

Os clientes podem verificar se sua solicitação foi aprovada, recusada ou ainda está em análise.

## **Request**
ENDPOINT /investor_management/investor/ INVESTOR-KEY /data_access_request
MÉTODO GET

### **Path Params**

| Campo          | Tipo   | Descrição                                     | Caracteres Máx. |
|---------------|--------|-----------------------------------------------|-----------------|
| `INVESTOR-KEY` * | string | Chave única do investidor (UUID v4).             | 36              |

## **Response**
STATUS 200

Response Body

```json
[
    {
        "data_access_request_key": "6beb9e44-1513-4d3b-9af5-f3c39ebbf2d0",
        "requested_at": "2025-02-22T10:45:49.609517",
        "responded_at": null,
        "data_access_request_status": "in_analysis"
    }
]
```

### **Response Body Params**

| Campo                          | Tipo     | Descrição                                                   | Caracteres Máx. |
|--------------------------------|----------|-------------------------------------------------------------|-----------------|
| `data_access_request_key` *    | string   | Chave única da solicitação de acesso (UUID v4).             | 36              |
| `requested_at` *               | string   | Data e hora da solicitação (formato ISO 8601).              | -               |
| `responded_at`                 | string   | Data e hora da resposta à solicitação, se já respondida.    | -               |
| `data_access_request_status` * | string   | Status da solicitação. | **[Enumeradores data_access_request_status](#enumeradores-data_access_request_status)** |

---

## **Enumeradores data_access_request_status**

| Enum         | Descrição                                             |
|-------------|------------------------------------------------------|
| `in_analysis` | A solicitação está em análise pelo investidor.         |
| `approved`   | O acesso foi aprovado e o cliente pode visualizar os dados do investidor. |
| `reproved`   | A solicitação foi recusada e o cliente não poderá acessar os dados do investidor. |

---

# Consulta de Comprovante de Transação

URL: /documentation/escrituracao/integralizacao-cotas/consulta-comprovante-transacao

Este endpoint permite obter o comprovante (PDF + metadados) de uma das TEDs executadas pela QI Tech para uma integralização. Em um ciclo de integralização (pagamento do investidor → tarifas → desembolso) podem ser geradas múltiplas TEDs — você escolhe qual delas quer pelo parâmetro `transaction_type`.

Quando houver mais de uma TED do mesmo tipo para a mesma integralização (por exemplo, vários `extraordinary_event_payment`), o endpoint retorna apenas a mais recente. Para listar todas, utilize **[Consulta de Transações da Integralização](./consulta-transacoes-integralizacao.md)**.

---

## Consulta de Comprovante (GET)

### Request
ENDPOINT /account_liquidation/integralization/ INTEGRALIZATION-KEY /transaction_receipt
MÉTODO GET

### Path Params

| Campo                 | Tipo   | Descrição                                  | Caracteres |
|-----------------------|--------|--------------------------------------------|------------|
| `INTEGRALIZATION-KEY` | string | Chave única da integralização (UUID v4).  | 36         |

### Query Params

| Campo              | Tipo   | Descrição                                                                                | Obrigatório |
|--------------------|--------|------------------------------------------------------------------------------------------|-------------|
| `transaction_type` | string | Tipo da TED a ser consultada. **[Enumeradores transaction_type](#enumeradores-transaction_type)** | Sim         |

---

### Response
STATUS 200

Response Body

```json
{
    "transaction_key": "46804f32-101e-4702-8fbc-c2dbc4c2caec",
    "transaction_amount": 12345.67,
    "transaction_status": "settled",
    "pdf_encoded_string": "JVBERi0xLi4u..."
}
```

---

### Response Body Params

| Campo                | Tipo   | Descrição                                                                                          |
|----------------------|--------|----------------------------------------------------------------------------------------------------|
| `transaction_key`    | string | Chave única da TED no BaaS — mesmo valor retornado por `consulta-transacoes-integralizacao`.       |
| `transaction_amount` | number | Valor da TED conforme registrado pela QI Tech.                                                     |
| `transaction_status` | string | Status da TED no BaaS (ex.: `settled`, `paid`).                                                    |
| `pdf_encoded_string` | string | Comprovante bancário em base64. Decodifique para obter o PDF.                                      |

---

### Enumeradores transaction_type

| Enum                          | Descrição                                                                              |
|-------------------------------|----------------------------------------------------------------------------------------|
| `disbursement`                | TED de desembolso do valor líquido para a conta bancária do emissor.                   |
| `bookkeeping_fee_internal`    | TED para a QI CTVM referente à tarifa de escrituração interna.                         |
| `bookkeeping_fee_external`    | TED para a conta de escrituração externa do cliente.                                   |
| `structuring_fee`             | TED para a conta de estruturação do cliente.                                           |
| `extraordinary_event_payment` | TED para um investidor referente a um evento extraordinário de liquidação.             |

---

### Erros

| HTTP | Código                                              | Quando ocorre                                                                                                        |
|------|-----------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|
| 400  | `HTTPMissingParam`                                  | Parâmetro `transaction_type` não foi informado.                                                                      |
| 400  | `HTTPInvalidParam`                                  | `transaction_type` não corresponde a nenhum dos valores permitidos.                                                  |
| 404  | `ACL000004` (`IntegralizationTransactionNotFound`)  | Não existe TED do tipo informado para essa integralização, OU a integralização nunca foi liquidada (sem TEDs).       |

:::note
O 404 com `ACL000004` é retornado de forma idêntica em todos os cenários (chave inexistente, integralização nunca liquidada, ou tipo de TED ausente) — por design, não diferenciamos os casos. Se precisar saber se a integralização existe, liste suas transações primeiro.
:::

---

# Consulta de Conta de Liquidação

URL: /documentation/escrituracao/integralizacao-cotas/consulta-conta-liquidacao

Este endpoint permite consultar os detalhes da conta de liquidação de um emissor — dados bancários (agência, conta, dígito), status e, quando a conta já está aberta, informações do titular e saldos.

Enquanto a conta ainda não foi aberta no BaaS, o endpoint retorna apenas os dados básicos com `account_status: "pending"`. Após a abertura, a resposta inclui os campos adicionais do titular e de saldo.

---

## Consulta de Conta de Liquidação (GET)

### Request
ENDPOINT /account_liquidation/issuer/ ISSUER-KEY
MÉTODO GET

### Path Params

| Campo        | Tipo   | Descrição                            | Caracteres |
|--------------|--------|--------------------------------------|------------|
| `ISSUER-KEY` | string | Chave única do emissor (UUID v4).    | 36         |

---

### Response
STATUS 200

Response Body — conta aberta

```json
{
    "issuer_key": "23d933e9-88ba-4291-a6a4-33f025ab361f",
    "tenant_key": "5e3045af-8be8-4cbd-9aab-9e15c4e92154",
    "bank_account_key": "8f2a6f10-3c43-4a3b-9f5e-2a9a1d4be0c1",
    "request_account_key": "1c0a2e54-77a8-4f0e-8d8e-6f2b9b3c1d22",
    "account_key": "46804f32-101e-4702-8fbc-c2dbc4c2caec",
    "account_branch": "0001",
    "account_number": "1234567",
    "account_digit": "8",
    "account_status": "opened",
    "account_type": "payment_account",
    "account_documents": [],
    "balance": 12345.67,
    "blocked_balance": 0.0,
    "owner_document_number": "12345678000190",
    "owner_name": "Emissor Exemplo LTDA",
    "owner_person_key": "9b1f3c77-5a2d-4e8f-b6a0-3d2c1e0f9a88",
    "created_at": "2026-01-15T12:34:56"
}
```

Response Body — conta pendente

```json
{
    "issuer_key": "23d933e9-88ba-4291-a6a4-33f025ab361f",
    "tenant_key": "5e3045af-8be8-4cbd-9aab-9e15c4e92154",
    "bank_account_key": "8f2a6f10-3c43-4a3b-9f5e-2a9a1d4be0c1",
    "request_account_key": "1c0a2e54-77a8-4f0e-8d8e-6f2b9b3c1d22",
    "account_branch": "0001",
    "account_number": "1234567",
    "account_digit": "8",
    "account_status": "pending"
}
```

---

### Response Body Params

| Campo                   | Tipo   | Descrição                                                                                   |
|-------------------------|--------|---------------------------------------------------------------------------------------------|
| `issuer_key`            | string | Chave única do emissor.                                                                     |
| `tenant_key`            | string | Chave única do cliente dono da conta.                                                       |
| `bank_account_key`      | string | Chave única da conta bancária no BaaS.                                                      |
| `request_account_key`   | string | Chave única da solicitação de abertura da conta.                                            |
| `account_key`           | string | Chave única da conta no BaaS. Presente apenas quando a conta já foi aberta.                 |
| `account_branch`        | string | Agência da conta.                                                                           |
| `account_number`        | string | Número da conta.                                                                            |
| `account_digit`         | string | Dígito da conta.                                                                            |
| `account_status`        | string | Status da conta. `pending` enquanto a abertura não foi concluída.                           |
| `account_type`          | string | Tipo da conta no BaaS. Presente apenas quando a conta já foi aberta.                        |
| `account_documents`     | array  | Documentos associados à conta. Presente apenas quando a conta já foi aberta.                |
| `balance`               | number | Saldo disponível da conta. Presente apenas quando a conta já foi aberta.                    |
| `blocked_balance`       | number | Saldo bloqueado da conta. Presente apenas quando a conta já foi aberta.                     |
| `owner_document_number` | string | CPF/CNPJ do titular da conta. Presente apenas quando a conta já foi aberta.                 |
| `owner_name`            | string | Nome do titular da conta. Presente apenas quando a conta já foi aberta.                     |
| `owner_person_key`      | string | Chave única do titular no BaaS. Presente apenas quando a conta já foi aberta.               |
| `created_at`            | string | Data de criação da conta. Presente apenas quando a conta já foi aberta.                     |

---

### Erros

| HTTP | Código                                                  | Quando ocorre                                                                 |
|------|---------------------------------------------------------|-------------------------------------------------------------------------------|
| 404  | `ACL000002` (`IssuerAccountLiquidationNotFound`)        | Não existe conta de liquidação para o emissor informado.                      |
| 400  | `ACL000003` (`IssuerAccountLiquidationNotBelongToTenant`) | A conta de liquidação do emissor não pertence ao cliente que fez a requisição. |

---

# Consulta de Integralização por Chave

URL: /documentation/escrituracao/integralizacao-cotas/consulta-processo-integralizacao

Este endpoint permite consultar os detalhes de um processo de integralização utilizando sua chave única.

---

## Consulta de Processo de Integralização (GET)

### Request
ENDPOINT /integralization/integralization_process/ INTEGRALIZATION-KEY
MÉTODO GET

### Path Params

| Campo                 | Tipo   | Descrição                                                         | Caracteres |
|------------------------|--------|------------------------------------------------------------------|------------|
| `INTEGRALIZATION-KEY`  | string | Chave única da integralização (UUID v4).                        | 36         |

---

### Response
STATUS 200

Response Body

```json
{
    "tenant_key": "39a0d458-c06f-41e7-92cf-a335cea90675",
    "integralization_key": "072a7cc4-1fbf-419b-8a41-f57bd86ee753",
    "operation_key": "c9cc8980-25b2-49ec-ac40-2a12b8df9dfc",
    "operation_type": "commercial_paper",
    "contract_number": "0000000002",
    "issue_number": 1,
    "issue_series": 1,
    "issuer_key": "1bc06a53-9503-4520-916c-38b5a6bb5912",
    "issuer_name": "Advanced Solutions",
    "issuer_document_number": "05120047000102",
    "issuer_bank_account": {
        "account_type": "checking",
        "account_digit": "3",
        "account_branch": "0001",
        "account_number": "4464541",
        "financial_institution_ispb": "32402502",
        "financial_institution_code_number": "329"
    },
    "subscripted_quantity": 1000000,
    "subscripted_total_amount": 1000000.0,
    "integralized_quantity": 1000000,
    "issue_quantity": 1000000,
    "integralization_status": "finished",
    "subscription_list": [
        {
            "subscription_key": "5a2100db-6bad-4fc7-9b5f-390543c63c55",
            "investor_key": "2d14cfef-7b95-4aa4-be0c-860ec8a60934",
            "investor_name": "Dynamic Group",
            "investor_document_number": "99525109000100",
            "investor_bank_account": {
                "account_digit": "0",
                "account_branch": "1234",
                "account_number": "12345678",
                "financial_institution_ispb": "12345678",
                "financial_institution_code_number": "001"
            },
            "subscription_date": "2025-01-27",
            "financial_base_date": "2025-01-27",
            "subscripted_quantity": 1000000,
            "unit_price": 1.0,
            "expected_amount": 1000000.0,
            "paid_amount": 1000000.0,
            "subscription_note_template_key": "8bfba2a3-1cda-45c4-9a97-05b2bf31e486",
            "subscription_note_document_key": "c9cc8980-25b2-49ec-ac40-2a12b8df9dfc/5a2100db-6bad-4fc7-9b5f-390543c63c55/subscription_note/8b6867d8-95c8-4e0d-b670-6a7d06f3acf7",
            "subscription_note_signature_status": "pending_creation",
            "subscription_payment_list": [
                {
                    "subscription_payment_key": "edf8a4cc-24c9-4dd9-8cae-9cb9151b40bf",
                    "payment_receipt_document_key": "072a7cc4-1fbf-419b-8a41-f57bd86ee753/5a2100db-6bad-4fc7-9b5f-390543c63c55/subscription_payment/edf8a4cc-24c9-4dd9-8cae-9cb9151b40bf",
                    "description": "Comprovante itau",
                    "amount": 1000000.0,
                    "subscription_payment_status": "confirmed",
                    "updated_at": "2025-01-27T14:30:18.741983"
                }
            ]
        }
    ]
}
```

---

### Response Body Params

| Campo                                                                  | Tipo       | Descrição                                                                                            |
|------------------------------------------------------------------------|------------|------------------------------------------------------------------------------------------------------|
| `tenant_key`                                                           | string     | Chave única do tenant associado à integralização.                                                    |
| `integralization_key`                                                  | string     | Chave única da integralização.                                                                       |
| `operation_key`                                                        | string     | Chave única da operação associada.                                                                   |
| `operation_type`                                                       | string     | Tipo da operação. Valores possíveis: `commercial_paper`.                                             |
| `contract_number`                                                      | string     | Número do contrato associado à integralização.                                                       |
| `issue_number`                                                         | integer    | Número da emissão associada à integralização.                                                        |
| `issue_series`                                                         | integer    | Série da emissão associada à integralização.                                                         |
| `issuer_key`                                                           | string     | Chave única do emissor associado.                                                                    |
| `issuer_name`                                                          | string     | Nome do emissor associado à integralização.                                                          |
| `issuer_document_number`                                               | string     | Número do documento do emissor                                                                       |
| `issuer_bank_account`                                                  | object     | Dados da conta bancária do emissor.                                                                  |
| `issuer_bank_account.account_type`                                     | string   | Tipo da conta bancária (`checking`, etc.).                                                           |
| `issuer_bank_account.account_digit`                                    | string   | Dígito verificador da conta bancária.                                                                |
| `issuer_bank_account.account_branch`                                   | string   | Agência bancária.                                                                                    |
| `issuer_bank_account.account_number`                                   | string   | Número da conta bancária.                                                                            |
| `issuer_bank_account.financial_institution_ispb`                       | string   | ISPB da instituição financeira.                                                                      |
| `issuer_bank_account.financial_institution_code_number`                | string | Código da instituição financeira.                                                                    |
| `subscripted_quantity`                                                 | integer    | Quantidade total de cotas subscritas.                                                                |
| `subscripted_total_amount`                                             | number     | Valor total das cotas subscritas.                                                                    |
| `integralized_quantity`                                                | integer    | Quantidade total de cotas integralizadas.                                                            |
| `issue_quantity`                                                       | integer    | Quantidade total de cotas emitidas na operação.                                                      |
| `integralization_status`                                               | string     | **[Enumeradores integralization_status](#enumeradores-integralization_status)**                                  |
| `subscription_list`                                                    | array      | Lista de subscrições associadas à integralização.    **[Objeto subscription](#objeto-subscription)** |

### Objeto subscription

| Campo                                                                  | Tipo       | Descrição                                                                                                     |
|------------------------------------------------------------------------|------------|---------------------------------------------------------------------------------------------------------------|
| `subscription_key`                                   | string   | Chave única da subscrição.                                                                                    |
| `investor_key`                                       | string   | Chave única do investidor associado à subscrição.                                                             |
| `investor_name`                                      | string   | Nome do investidor.                                                                                           |
| `investor_document_number`                           | string   | Número do documento do investidor (CPF ou CNPJ).                                                              |
| `investor_bank_account`                              | object   | Dados bancários do investidor.                                                                                |
| `subscription_date`                                  | string   | Data da subscrição (formato: YYYY-MM-DD).                                                                     |
| `financial_base_date`                                | string   | Data base financeira da subscrição (formato: YYYY-MM-DD).                                                     |
| `subscripted_quantity`                               | integer  | Quantidade de cotas subscritas.                                                                               |
| `unit_price`                                         | number   | Preço unitário das cotas.                                                                                     |
| `expected_amount`                                    | number   | Valor total esperado da subscrição.                                                                           |
| `paid_amount`                                        | number   | Valor pago ja confrimado da subscrição.                                                                       |
| `subscription_note_template_key`                     | string   | Chave do template da nota de subscrição.                                                                      |
| `subscription_note_document_key`                     | string   | Chave do documento da nota de subscrição.                                                                     |
| `subscription_note_signature_status`                 | string | Status da assinatura da nota de subscrição.                                                                   |
| `subscription_payment_list`                          | array    | Lista de pagamentos associados à subscrição. **[Objeto subscription_payment](#objeto-subscription_payment)]** |

### Objeto subscription_payment

| Campo                                                                  | Tipo       | Descrição                                                                              |
|------------------------------------------------------------------------|------------|----------------------------------------------------------------------------------------|
| `subscription_payment_key` | string   | Chave única do pagamento da subscrição.                                                |
| `payment_receipt_document_key`                                         | string   | Chave do documento do comprovante de pagamento.                                        |
| `description`                                                          | string   | Descrição do comprovante de pagamento.                                                 |
| `amount`                                                               | number   | Valor do pagamento registrado.                                                         |
| `subscription_payment_status`                                          | string   | Status do pagamento. Valores possíveis: `waiting_confirmation`, `confirmed`, `denied`. |
| `updated_at`                                                           | string   | Data e hora da última atualização do pagamento (formato: ISO 8601).                    |

### Enumeradores integralization_status

| Enum                            | Description                        |
| ------------------------------- | ---------------------------------- |
| `pending`              | Pendente Subscrição.            |
| `finished`            | Integralização finalizada.                         |
| `canceled`               | Integralização cancelada.        |

---

# Consulta de Transações da Integralização

URL: /documentation/escrituracao/integralizacao-cotas/consulta-transacoes-integralizacao

Este endpoint retorna os metadados de todas as TEDs executadas pela QI Tech para uma integralização — sem o PDF. Útil para descobrir quantos comprovantes existem, em qual ordem foram executados e os respectivos `transaction_key`. Para obter o PDF de uma TED específica, use **[Consulta de Comprovante de Transação](./consulta-comprovante-transacao.md)**.

A resposta vem em ordem cronológica (`created_at` ASC) e inclui todas as TEDs do ciclo (desembolso, tarifas e eventos extraordinários). Quando há múltiplas TEDs do mesmo tipo (por exemplo, vários `extraordinary_event_payment`), todas aparecem aqui — diferente do endpoint de comprovante, que retorna apenas a mais recente.

---

## Consulta de Transações (GET)

### Request
ENDPOINT /account_liquidation/integralization/ INTEGRALIZATION-KEY /transactions
MÉTODO GET

### Path Params

| Campo                 | Tipo   | Descrição                                  | Caracteres |
|-----------------------|--------|--------------------------------------------|------------|
| `INTEGRALIZATION-KEY` | string | Chave única da integralização (UUID v4).  | 36         |

---

### Response
STATUS 200

Response Body

```json
[
    {
        "transaction_key": "46804f32-101e-4702-8fbc-c2dbc4c2caec",
        "external_id": "072a7cc4-1fbf-419b-8a41-f57bd86ee753",
        "transaction_amount": 12345.67,
        "transaction_type": "disbursement",
        "transaction_status": "paid",
        "created_at": "2026-05-05T13:22:01"
    }
]
```

---

### Response Body Params

| Campo                | Tipo   | Descrição                                                                                                |
|----------------------|--------|----------------------------------------------------------------------------------------------------------|
| `transaction_key`    | string | Chave única da TED no BaaS.                                                                              |
| `external_id`        | string | `integralization_key` à qual a TED pertence.                                                             |
| `transaction_amount` | number | Valor registrado pela QI Tech para a TED. Não use como fonte oficial para conciliação contábil.          |
| `transaction_type`   | string | Tipo da TED. **[Enumeradores transaction_type](./consulta-comprovante-transacao.md#enumeradores-transaction_type)** |
| `transaction_status` | string | Status atual da TED (ex.: `paid`, `settled`).                                                            |
| `created_at`         | string | Data e hora de criação do registro (ISO 8601).                                                           |

---

# Introdução à Integralização de Cotas

URL: /documentation/escrituracao/integralizacao-cotas/inicio

Após a conclusão do processo de Emissão da Nota Comercial, a operação restará no status emitido (issued).

Por padrão o processo de subscrição de cotas para integralização ocorre de forma automática após a assinatura do termo constitutivo.

Ao consultar uma operação no estado emitida, estará disponível um campo chamado `integralization_key` pelo quando o processo de integralização poderá ser acompanhado.

O processo de integralização consiste de 

- Subscrição de cotas
- Assinatura do boletim de subscrição
- Registro de Pagamento
- Confirmação de Pagamento

---

# Cadastro de Subscrição

URL: /documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cadastro-subscricao

Este endpoint permite registrar a intenção de um investidor em subscrever uma quantidade específica de cotas de uma integralização.

---

## Cadastro de Subscrição (POST)

### Request

ENDPOINT /integralization/integralization_process/ INTEGRALIZATION-KEY /subscription
MÉTODO POST

### Path Params

| Campo                   | Tipo   | Descrição                                 | Caracteres |
| ----------------------- | ------ | ------------------------------------------- | ---------- |
| `INTEGRALIZATION-KEY` | string | Chave única da integralização (UUID v4). | 36         |

---

### Request Body

Request Body

```json
{
  "investor_key": "123e4567-e89b-12d3-a456-426614174000",
  "investor_bank_account": {
    "account_number": "12345678",
    "account_digit": "0",
    "account_branch": "1234",
    "financial_institution_code_number": "001",
    "financial_institution_ispb": "12345678"
  },
  "subscription_date": "2025-01-01",
  "financial_base_date": "2025-01-01",
  "subscription_note_template_key": "c649c01a-dd24-47b7-b93e-5a6bac50bcf0",
  "subscripted_quantity": 100000
}
```

### Request Body Params

| Campo                                                        | Tipo    | Descrição                                             |
| ------------------------------------------------------------ | ------- | ------------------------------------------------------- |
| `investor_key`*                                            | string  | Chave única do investidor (UUID v4).                   |
| `investor_bank_account`*                                   | object  | Dados da conta bancária do investidor.                 |
| `investor_bank_account.account_number`*                    | string  | Número da conta bancária do investidor.               |
| `investor_bank_account.account_digit`*                     | string  | Dígito verificador da conta bancária do investidor.   |
| `investor_bank_account.account_branch`*                    | string  | Agência bancária do investidor.                       |
| `investor_bank_account.financial_institution_code_number`* | string  | Código da instituição financeira do investidor.      |
| `investor_bank_account.financial_institution_ispb`*        | string  | ISPB da instituição financeira do investidor.         |
| `subscripted_quantity`*                                    | integer | Quantidade de cotas que o investidor deseja subscrever. |
| `financial_base_date`*                                     | string  | Data base financeira.                                   |
| `subscription_date`*                                       | string  | Data da subscrição.                                   |
| `subscription_note_template_key`*                          | string  | Template do boletim de subscrição.                    |

---

### Response

STATUS 201

Response Body

```json
{
    "subscription_key": "2f7e00b5-988f-4214-bb46-4728d9081148",
    "investor_key": "a76e408a-c733-4a68-963a-dc93ff0bc3e3",
    "investor_name": "Global Enterprises",
    "investor_document_number": "89206257000108",
    "investor_bank_account": {
        "account_digit": "0",
        "account_branch": "1234",
        "account_number": "12345678",
        "financial_institution_ispb": "12345678",
        "financial_institution_code_number": "001"
    },
    "subscription_date": "2025-01-27",
    "financial_base_date": "2025-01-27",
    "subscripted_quantity": 1000000,
    "unit_price": 1.0,
    "expected_amount": 1000000.0,
    "paid_amount": 1000000.0,
    "subscription_note_template_key": "6d4c5168-b7c7-4092-9931-4c76aea6af80",
    "subscription_note_document_key": "5ea88fca-4ca3-4dfe-aea4-35e431aef3c5/2f7e00b5-988f-4214-bb46-4728d9081148/subscription_note/f206d799-cb94-48d5-81c5-5988ecef8079",
    "envelope_signature_status": "pending_creation",
    "envelope_signature_url": "https://certifiqi.com.br/envelope_key",
    "envelope_key": "6d4c5168-b7c7-4092-9931-4c76aea6af80",
    "subscription_payment_list": [
        {
            "subscription_payment_key": "7e51be5b-fdfd-4f2f-ba1a-0d81cdb08177",
            "payment_receipt_document_key": "f352de14-222f-4787-bd67-2063524f8d9f/2f7e00b5-988f-4214-bb46-4728d9081148/subscription_payment/7e51be5b-fdfd-4f2f-ba1a-0d81cdb08177",
            "description": "Comprovante itau",
            "amount": 1000000.0,
            "subscription_payment_status": "confirmed",
            "updated_at": "2025-01-27T14:33:54.214891"
        }
    ]
}
```

### **Response Body Params**

| Campo                              | Tipo    | Descrição                                                                                                                  |
| ---------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `subscription_key`               | string  | Chave única da subscrição (UUID v4).                                                                                      |
| `investor_key`                   | string  | Chave única do investidor associado à subscrição (UUID v4).                                                              |
| `investor_name`                  | string  | Nome do investidor.                                                                                                          |
| `investor_document_number`       | string  | Número do documento do investidor (CPF ou CNPJ).                                                                            |
| `investor_bank_account`          | object  | **[Objeto investor_bank_account](#objeto-investor_bank_account)**.                                                        |
| `subscription_date`              | string  | Data da subscrição (formato: YYYY-MM-DD).                                                                                  |
| `financial_base_date`            | string  | Data base financeira da subscrição (formato: YYYY-MM-DD).                                                                  |
| `subscripted_quantity`           | integer | Quantidade de cotas subscritas.                                                                                              |
| `unit_price`                     | number  | Preço unitário das cotas subscritas.                                                                                       |
| `expected_amount`                | number  | Valor total esperado da subscrição.                                                                                        |
| `paid_amount`                    | number  | Valor total pago na subscrição.                                                                                            |
| `subscription_note_template_key` | string  | Chave única do template da nota de subscrição (UUID v4).                                                                  |
| `subscription_note_document_key` | string  | Chave única do documento da nota de subscrição.                                                                           |
| `envelope_signature_status`      | string  | Status de assinatura da nota de subscrição.                                                                                |
| `envelope_signature_url`         | string  | URL de assinatura da nota de subscrição.                                                                                   |
| `envelope_key`                   | string  | Chave do envelope de assinatura.                                                                                             |
| `subscription_payment_list`      | array   | Lista de pagamentos associados à subscrição.**[Objeto subscription_payment_list](#objeto-subscription_payment_list)**. |

---

### Objeto investor_bank_account

| Campo                                 | Tipo   | Descrição                                           |
| ------------------------------------- | ------ | ----------------------------------------------------- |
| `account_number`                    | string | Número da conta bancária do investidor.             |
| `account_digit`                     | string | Dígito verificador da conta bancária do investidor. |
| `account_branch`                    | string | Agência bancária do investidor.                     |
| `financial_institution_code_number` | string | Código da instituição financeira do investidor.    |
| `financial_institution_ispb`        | string | ISPB da instituição financeira do investidor.       |

### Objeto subscription_payment_list

| Campo                            | Tipo   | Descrição                                                                                  |
| -------------------------------- | ------ | -------------------------------------------------------------------------------------------- |
| `subscription_payment_key`     | string | Chave única do pagamento da subscrição (UUID v4).                                         |
| `payment_receipt_document_key` | string | Chave do documento do comprovante de pagamento.                                              |
| `description`                  | string | Descrição do comprovante de pagamento.                                                     |
| `amount`                       | number | Valor do pagamento registrado.                                                               |
| `subscription_payment_status`  | string | Status do pagamento. Valores possíveis:`waiting_confirmation`, `confirmed`, `denied`. |
| `updated_at`                   | string | Data e hora da última atualização do pagamento (formato: ISO 8601).                       |

---

# Cancelar subscrição

URL: /documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cancelar-subscricao

---

### Request
ENDPOINT /integralization/integralization_process/ INTEGRALIZATION-KEY /subscription/ SUBSCRIPTION-KEY
MÉTODO PATCH

### Path Params

| Campo           | Tipo   | Descrição                                            | Caracteres |
|------------------|--------|------------------------------------------------------|------------|
| `INTEGRALIZATION-KEY`  | string | Chave única do processo de integralização (UUID v4). | 36         |
| `SUBSCRIPTION-KEY`  | string | Chave única da subscrição (UUID v4).                 | 36         |

---

### Request Body

```json
{
  "subscription_status": "canceled"
}
```
### Request Body Params

| Campo             | Tipo     | Descrição                               | Obrigatório |
|-------------------|----------|-----------------------------------------|-------------|
| `subscription_status` | string   | Valores aceitos: `canceled`.            | Sim         |

---

### Response

STATUS 200

Será retornado um exemplar atualizado da Subscrição.

---

---

# Confirmação ou Rejeição do Pagamento de Subscrição

URL: /documentation/escrituracao/integralizacao-cotas/subscricao-cotas/confirmacao-pagamento

Este endpoint permite confirmar ou rejeitar o pagamento associado a uma subscrição de integralização. O status do pagamento é atualizado conforme o valor fornecido no corpo da requisição.

---

## Atualização do Status do Pagamento (PATCH)

### Request

ENDPOINT /integralization_integralization_process/ INTEGRALIZATION-KEY /subscription/ SUBSCRIPTION-KEY /subscription_payment/ SUBSCRIPTION-PAYMENT-KEY
MÉTODO PATCH

### Path Params

| Campo                        | Tipo   | Descrição                                          | Caracteres |
| ---------------------------- | ------ | ---------------------------------------------------- | ---------- |
| `INTEGRALIZATION-KEY`      | string | Chave única da integralização (UUID v4).          | 36         |
| `SUBSCRIPTION-KEY`         | string | Chave única da subscrição associada (UUID v4).    | 36         |
| `SUBSCRIPTION-PAYMENT-KEY` | string | Chave única do pagamento da subscrição (UUID v4). | 36         |

---

### Request Body

```json
{
  "subscription_payment_status": "confirmed"
}
```

### Request Body Params

| Campo                            | Tipo   | Descrição                                                               | Obrigatório |
| -------------------------------- | ------ | ------------------------------------------------------------------------- | ------------ |
| `subscription_payment_status`* | string | Novo status do pagamento. Valores possíveis:`confirmed` ou `denied`. | Sim          |

---

### Response

STATUS 200

Response Body

```json
{
    "subscription_payment_key": "7e51be5b-fdfd-4f2f-ba1a-0d81cdb08177",
    "payment_receipt_document_key": "f352de14-222f-4787-bd67-2063524f8d9f/2f7e00b5-988f-4214-bb46-4728d9081148/subscription_payment/7e51be5b-fdfd-4f2f-ba1a-0d81cdb08177",
    "description": "Comprovante de pagamento Itau R$100.000,00",
    "amount": 100000.0,
    "subscription_payment_status": "waiting_confirmation",
    "updated_at": "2025-01-24T11:30:00Z"
}
```

---

### Response Body Params

| Campo                           | Tipo   | Descrição                                                                                            |
| ------------------------------- | ------ | ------------------------------------------------------------------------------------------------------ |
| `subscription_payment_key`    | string | Chave única do pagamento da subscrição (UUID v4).                                                   |
| `amount`                      | number | Valor declarado do pagamento registrado.                                                               |
| `description`                 | number | Descrição do conteudo do recibo.                                                                     |
| `subscription_payment_status` | string | Status atualizado do pagamento. Valores possíveis:`waiting_confirmation` `confirmed`, `denied`. |
| `updated_at`                  | string | Data e hora da atualização do status do pagamento (formato: ISO 8601).                               |

---

# Consulta de Subscrição

URL: /documentation/escrituracao/integralizacao-cotas/subscricao-cotas/consulta-subscricao-cotas

Este endpoint permite consultar uma subcrição em andamento.

---

## Consulta de Subscrição (GET)

### Request
ENDPOINT /integralization/integralization_process/ INTEGRALIZATION-KEY /subscription/ SUBSCRIPTION-KEY
MÉTODO GET

### Path Params

| Campo                 | Tipo   | Descrição                                | Caracteres |
|-----------------------|--------|------------------------------------------|------------|
| `INTEGRALIZATION-KEY` | string | Chave única da integralização (UUID v4). | 36         |
| `SUBSCRIPTION-KEY`    | string | Chave única da subscrição (UUID v4).     | 36         |

---

### Response
STATUS 201

Response Body

```json
{
    "subscription_key": "2f7e00b5-988f-4214-bb46-4728d9081148",
    "investor_key": "a76e408a-c733-4a68-963a-dc93ff0bc3e3",
    "investor_name": "Global Enterprises",
    "investor_document_number": "89206257000108",
    "investor_bank_account": {
        "account_digit": "0",
        "account_branch": "1234",
        "account_number": "12345678",
        "financial_institution_ispb": "12345678",
        "financial_institution_code_number": "001"
    },
    "subscription_date": "2025-01-27",
    "financial_base_date": "2025-01-27",
    "subscripted_quantity": 1000000,
    "unit_price": 1.0,
    "expected_amount": 1000000.0,
    "paid_amount": 1000000.0,
    "subscription_note_template_key": "6d4c5168-b7c7-4092-9931-4c76aea6af80",
    "subscription_note_document_key": "5ea88fca-4ca3-4dfe-aea4-35e431aef3c5/2f7e00b5-988f-4214-bb46-4728d9081148/subscription_note/f206d799-cb94-48d5-81c5-5988ecef8079",
    "envelope_signature_status": "pending_creation",
    "envelope_signature_url": "https://certifiqi.com.br/envelope_key",
    "envelope_key": "6d4c5168-b7c7-4092-9931-4c76aea6af80",
    "subscription_payment_list": [
        {
            "subscription_payment_key": "7e51be5b-fdfd-4f2f-ba1a-0d81cdb08177",
            "payment_receipt_document_key": "f352de14-222f-4787-bd67-2063524f8d9f/2f7e00b5-988f-4214-bb46-4728d9081148/subscription_payment/7e51be5b-fdfd-4f2f-ba1a-0d81cdb08177",
            "description": "Comprovante itau",
            "amount": 1000000.0,
            "subscription_payment_status": "confirmed",
            "updated_at": "2025-01-27T14:33:54.214891"
        }
    ]
}
```

---

### **Response Body Params**

| Campo                                                     | Tipo       | Descrição                                                                 |
|-----------------------------------------------------------|------------|---------------------------------------------------------------------------|
| `subscription_key`                                        | string     | Chave única da subscrição (UUID v4).                                     |
| `investor_key`                                            | string     | Chave única do investidor associado à subscrição (UUID v4).              |
| `investor_name`                                           | string     | Nome do investidor.                                                      |
| `investor_document_number`                                | string     | Número do documento do investidor (CPF ou CNPJ).                         |
| `investor_bank_account`                                   | object     | **[Objeto investor_bank_account](#objeto-investor_bank_account)**.       |
| `subscription_date`                                       | string     | Data da subscrição (formato: YYYY-MM-DD).                                |
| `financial_base_date`                                     | string     | Data base financeira da subscrição (formato: YYYY-MM-DD).                |
| `subscripted_quantity`                                    | integer    | Quantidade de cotas subscritas.                                          |
| `unit_price`                                              | number     | Preço unitário das cotas subscritas.                                     |
| `expected_amount`                                         | number     | Valor total esperado da subscrição.                                      |
| `paid_amount`                                             | number     | Valor total pago na subscrição.                                          |
| `subscription_note_template_key`                          | string     | Chave única do template da nota de subscrição (UUID v4).                 |
| `subscription_note_document_key`                          | string     | Chave única do documento da nota de subscrição.                          |
| `envelope_signature_status`                               | string     | Status de assinatura da nota de subscrição.                              |
| `envelope_signature_url`                                  | string     | URL de assinatura da nota de subscrição.                                 |
| `envelope_key`                                            | string     | Chave do envelope de assinatura.                                         |
| `subscription_payment_list`                               | array      | Lista de pagamentos associados à subscrição. **[Objeto subscription_payment_list](#objeto-subscription_payment_list)**. |

---

### Objeto investor_bank_account

| Campo                          | Tipo       | Descrição                                               |
|--------------------------------|------------|---------------------------------------------------------|
| `account_number`              | string     | Número da conta bancária do investidor.                 |
| `account_digit`               | string     | Dígito verificador da conta bancária do investidor.     |
| `account_branch`              | string     | Agência bancária do investidor.                         |
| `financial_institution_code_number` | string | Código da instituição financeira do investidor.         |
| `financial_institution_ispb`   | string     | ISPB da instituição financeira do investidor.           |

### Objeto subscription_payment_list

| Campo                                                     | Tipo       | Descrição                                                                 |
|-----------------------------------------------------------|------------|---------------------------------------------------------------------------|
| `subscription_payment_key`                                | string     | Chave única do pagamento da subscrição (UUID v4).                        |
| `payment_receipt_document_key`                            | string     | Chave do documento do comprovante de pagamento.                          |
| `description`                                             | string     | Descrição do comprovante de pagamento.                                   |
| `amount`                                                 | number     | Valor do pagamento registrado.                                           |
| `subscription_payment_status`                             | string     | Status do pagamento. Valores possíveis: `waiting_confirmation`, `confirmed`, `denied`. |
| `updated_at`                                              | string     | Data e hora da última atualização do pagamento (formato: ISO 8601).      |

---

# Registro de Pagamento de Subscrição

URL: /documentation/escrituracao/integralizacao-cotas/subscricao-cotas/registro-de-pagamento

Este endpoint permite registrar um pagamento associado a uma subscrição de integralização. O pagamento inclui um valor declarado e um comprovante em Base64.

---

## Registro de Pagamento (POST)

### Request

ENDPOINT /integralization_integralization_process/ INTEGRALIZATION-KEY /subscription/ SUBSCRIPTION-KEY /subscription_payment
MÉTODO POST

### Path Params

| Campo                   | Tipo   | Descrição                                       | Caracteres |
| ----------------------- | ------ | ------------------------------------------------- | ---------- |
| `INTEGRALIZATION-KEY` | string | Chave única da integralização (UUID v4).       | 36         |
| `SUBSCRIPTION-KEY`    | string | Chave única da subscrição associada (UUID v4). | 36         |

---

### Request Body

```json
{
  "document_base64": "dGVzdGVfZG9jdW1lbnRfYmFzZTY0",
  "amount": 100000.00,
  "description": "Comprovante de pagamento Itau R$100.000,00"
}
```

### Request Body Params

| Campo                | Tipo    | Descrição                                    | Obrigatório |
| -------------------- | ------- | ---------------------------------------------- | ------------ |
| `document_base64`* | string  | Comprovante de pagamento codificado em Base64. | Sim          |
| `amount`*          | number  | Valor declarado do pagamento realizado.        | Sim          |
| `description`      | *number | Descrição do conteúdo do comprovante.       | Sim          |

---

### Response

STATUS 201

Response Body

```json
{
    "subscription_payment_key": "7e51be5b-fdfd-4f2f-ba1a-0d81cdb08177",
    "payment_receipt_document_key": "f352de14-222f-4787-bd67-2063524f8d9f/2f7e00b5-988f-4214-bb46-4728d9081148/subscription_payment/7e51be5b-fdfd-4f2f-ba1a-0d81cdb08177",
    "description": "Comprovante de pagamento Itau R$100.000,00",
    "amount": 100000.0,
    "subscription_payment_status": "waiting_confirmation",
    "updated_at": null
}
```

---

### Response Body Params

| Campo                           | Tipo   | Descrição                                                                                     |
| ------------------------------- | ------ | ----------------------------------------------------------------------------------------------- |
| `subscription_payment_key`    | string | Chave única do pagamento da subscrição (UUID v4).                                            |
| `amount`                      | number | Valor declarado do pagamento registrado.                                                        |
| `subscription_payment_status` | string | Status atual do pagamento. Valores possíveis:`waiting_confirmation` `confirmed` `denied` |
| `description`                 | number | Descrição do conteúdo do comprovante.                                                        |

---

---

# Recebimento de Webhooks

URL: /documentation/escrituracao/introducao/autenticacao_webhooks

A assinatura dos Webhooks utiliza-se de uma estratégia de criptografia com chaves simétricas, ou seja, 
tanto a QI CTVM quanto o Parceiro integrador compartilham de uma mesma chave. 
Ao realizarmos uma configuração de Webhooks, iremos gerar uma Signature Key e disponibiliza-lá. Toda requisição originada no sistema da QI,
irá carregar um header SIGNATURE que será um JWT assinado com essa chave. O encoding é realizado com o algoritmo HS256.

Abaixo temos um exemplo em python de como realizar o decoding da assinatura:
```python
from jose import jwt

signature_key = "CHAVE UNICA CONFIGURADA"

signature_token = headers["SIGNATURE"]

decoded_token = jwt.decode(signature_token, key=signature_key, algorithms=["HS256"])
print(decoded_token)
```

Sugerimos que, além de comparar a assinatura, o parceiro integrador valide o nosso IP, dado que todas as nossas requisições são originadas de um mesmo IP, 
conforme o ambiente:

|Ambiente| IP |
|--------|----|
|Produção| -  |
|Sandbox | -  |

:::danger Atenção!
Os webhooks da QI CTVM não devem ser mapeados de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

---

# Escrituração de Notas Comerciais

URL: /documentation/escrituracao/introducao/

Essa documentação tem como objetivo descrever os fluxos, endpoints e estruturas de dados necessárias para operar e emissão de **Notas Comerciais**.

Obs.: Em caso de dúvidas em qualquer etapa do processo favor entre em contato com [suporte-dcm@qitech.com.br](mailto:suporte-dcm@qitech.com.br) detalhando seu problema/dúvida que te auxiliaremos.

## Ambientes (Hosts)

A QI CTVM possui dois ambientes, SANDBOX e PRODUÇÃO. Ambos os ambientes possuem código e comportamento completamente idênticos, porém, o ambiente de SANDBOX apresenta valores monetários totalmente fictícios, e o ambiente de Produção realiza transações financeiras válidas.

O ambiente Sandbox foi criado para os desenvolvedores realizarem suas integrações, e quando estiverem prontos para entrada em produção, atualizarem apenas as variáveis de ambiente com os parâmetros de Produção.

| Ambiente | Host                                         |
|----------|----------------------------------------------|
| Sandbox | https://api.sandbox.securities.qidtvm.com.br |
| Produção | https://api.securities.qidtvm.com.br |

---

# Endpoints de teste

URL: /documentation/escrituracao/introducao/teste-autenticacao/endpoints_de_teste

## Método GET

### Request

ENDPOINT /authentication_test
MÉTODO GET

### Response

STATUS 200

Response Body

```json
{
  "success": "Congrats!"
}
```

## Metodo POST

### Request

ENDPOINT /authentication_test
MÉTODO POST

Request Body

```json
{
  "name": "QI Tech"
}
```

### Response

STATUS 200

Response Body

```json
{
  "name": "QI Tech",
  "success": "Congrats!"
}

```

---

# Teste de autenticação

URL: /documentation/escrituracao/introducao/teste-autenticacao/teste_de_autenticacao

### 1. Introdução

Nessa seção iremos explicar como deve funcionar a requisição para que possa ser aceita pelo nosso sistema. 
Em primeiro Lugar deve-se colocar no header API-CLIENT-KEY a Api Key fornecida pelo time da QI CTVM. 
Depois deve-se criar um Header de AUTHORIZATION assinando com a Chave Privada do parceiro integrador; 

Abaixo iremos ensinar o passo a passo utilizando de Python para exemplificar o processo de criação da AUTHORIZATION.

### 2. Importar bibliotecas
Neste exemplo em python estamos usando 5 bibliotecas para poder realizar o processo de autenticação.

```python
from datetime import datetime
import json
from jose import jwt
from hashlib import md5
import requests
```

### 3. Inserir a chave privada e a chave de integração
```python title="Dados da criptografia"
api_key = "\<API KEY FORNECIDA PELA QI\>"

client_private_key = '''-----BEGIN EC PRIVATE KEY-----
MIHbAgEBBEH7OuewosJfz4zKF+Gm0ogJxhb8G6LSMDVQQbFYz335mHCx9/Pr6Yk+
yYwsVozeXhlry3/vnUn1zCasU+4O+yseZ6AHBgUrgQQAI6GBiQOBhgAEAa46fN/2
8vI64shRhu9erMA6JLl3zHFX8gFHQrbb0g4IDfjXCKMCILiwdtL8QecstsgepTa7
yo1pTXOVNDbmLX2TAK38xb2Gv6OC+PA+5drF2wWajWbVLpR2R7mYEzr5HNIAJYHb
5C1jvM2ItK2R22HAbYfH25nsvGhkCGbrRNWQVF9g
-----END EC PRIVATE KEY-----'''

```

### 4. Definir variáveis
Definir as variáveis método, endpoint e conteúdo particular a cada requisição (neste exemplo, utilizaremos o método "POST" para o endpoint "/authentication_test")
```python title="Dados da requisição"
base_url = "https://api.securities.qidtvm.com.br"
today_str = datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S")
method = "POST"
endpoint = "/authentication_test"
body = {"name": "QI Tech"}
```

### 5. Construir Dicionário Base de Assinatura
```python title="Dicionário base"

dict_to_sign = {"timestamp": today_str, "method": method, "uri": endpoint}

```

#### 5.1. Se necessário, adicionar o conteúdo
Para as requisições que tenham _body_, deve-se adicionar o md5 do bytes desse conteúdo. Como todas as requisições no nosso sistema são através de JSON, 
pode-se usar o seguinte:

```python title="Dicionário base"
body_bytes = json.dumps(body).encode()

md5_instance = md5()
md5_instance.update(body_bytes)
md5_body = md5_instance.hexdigest()

dict_to_sign["payload_md5"] = md5_body
```

### 6. Realizar criptografia do header
Realizar criptografia utilizando biblioteca JWT (neste exemplo de código, utilizamos jsonwebtoken como jwt em javascript)

```python
jwt_headers = {"alg": "ES512", "typ": "JWT"}
encoded_header_token = jwt.encode(
    claims=dict_to_sign,
    key=client_private_key,
    algorithm="ES512",
    headers=jwt_headers,
)
```

### 7. Montando o header final

```python
headers = {"API-CLIENT-KEY": api_key, "AUTHORIZATION": encoded_header_token}
```

```python title="Definindo url final"
url = f"{base_url}{endpoint}"
```

### Realizando requisição

```python
resp = requests.post(url=url, headers=headers, json=body)
print(resp.json())
```

---

# Troca de Chaves

URL: /documentation/escrituracao/introducao/troca_de_chaves

## 1. Requisição Assinada

Todas as requisições em nossas APIs devem usar o protocolo **HTTPs**, utilizando **TLS 1.2 ou 1.3**, contendo dois Headers:

1. API-CLIENT-KEY: Uma chave disponibilizada pelo nosso time de Integração que identifica uma integração específica;
2. AUTHORIZATION: Uma assinatura da requisição que deve ser realizada conforme explicado nesse manual;

Como padrão a QI CTVM utiliza-se do padrão de chaves assimétricas, onde existem duas chaves diferentes, uma para assinatura, denominada chave privada , e uma para leitura, denominada de chave pública . Com a chave privada, o parceiro integrador deverá realizar a assinatura utilizando-se do padrão JWT.
O parceiro integrador é responsável por gerar o par e fornecer ao time da QI CTVM a chave pública para que possamos validar as suas requisições.

:::caution **Atenção**
 A chave privada é de uso exclusivo do parceiro integrador, e deve ser armazenada com segurança. A QI CTVM nunca irá pedir, em hipótese alguma, que voce a compartilhe conosco.
:::
## 2. Gerando o par

Para gerar uma chave privada em um computador UNIX faça:

```bash
$ ssh-keygen -t ecdsa -b 521 -m PEM -f private.key
```

E a partir desta chave privada gere sua chave pública.

```bash
$ openssl ec -in private.key -pubout -outform PEM -out public.key.pub
```

A chave pública gerada (arquivo public.key.pub) deve ser enviada para o time da QI Tech, e aguardar a integração ser configurada;

---

# Consulta de Ativo

URL: /documentation/escrituracao/operacoes-ativas/consulta-security

Este endpoint permite consultar os detalhes de um ativo utilizando sua chave única.

---

## **Request**
ENDPOINT /security/security/ SECURITY-KEY
MÉTODO GET

### **Path Params**

| Campo         | Tipo   | Descrição                                       | Caracteres |
|--------------|--------|-----------------------------------------------|------------|
| `SECURITY-KEY` | string | Chave única do security (UUID v4).          | 36         |

---

## **Response**
STATUS 200

Response Body
```json
{
    "tenant_key": "13a6a1d5-7a3c-4627-a0a6-9fd746662ca4",
    "security_key": "42bd7161-5ec1-4f64-ac0c-861d93ffb4c2",
    "operation_key": "8eb2291e-2dbf-4af1-9d12-f29fac665ed2",
    "operation_type": "commercial_paper",
    "contract_number": "0000000027",
    "issuer_key": "9e08fd62-ce43-4c95-99e0-4386e980d618",
    "issuer_name": "Blue Logic",
    "issuer_document_number": "97.923.586/0001-06",
    "issuer_bank_account": {
        "account_type": "checking",
        "account_digit": "3",
        "account_branch": "0001",
        "account_number": "4464541",
        "financial_institution_ispb": "32402502",
        "financial_institution_code_number": "329"
    },
    "financial_base_date": "2025-02-18",
    "current_unit_price": 1.0,
    "latest_accrual_date": "2025-02-18",
    "integralized_quantity": 100000,
    "issue_quantity": 100000,
    "security_status": "active",
    "is_defaulted": false,
    "financial": {
        "financial_base_date": "2025-02-18",
        "issue_quantity": 100000,
        "unit_price": 1.0,
        "issue_amount": 100000.0,
        "released_amount": 100000.0,
        "cet": 1.0,
        "annual_cet": 12.68,
        "number_of_installments": 5,
        "prefixed_interest_rate": {
            "daily_rate": 0.0003271877,
            "annual_rate": 0.1268250301,
            "monthly_rate": 0.01,
            "interest_base": "calendar_days_365"
        },
        "post_fixed_interest_rate": null,
        "financial_index": null,
        "fine_delay_rate": {
            "daily_rate": 0.00032719,
            "annual_rate": 0.12682503,
            "monthly_rate": 0.01,
            "interest_base": "calendar_days_365"
        },
        "contract_fine_rate": 0.02,
        "fees": [
            {
                "type": "internal",
                "amount": 2.0,
                "fee_type": "bookkeeping_fee",
                "fee_amount": 2000.0,
                "amount_type": "percentage"
            },
            {
                "type": "external",
                "amount": 5.0,
                "fee_type": "structuring_fee",
                "fee_amount": 5000.0,
                "amount_type": "percentage"
            }
        ],
        "installment_list": [
            {
                "installment_key": "959a1d8f-9f7f-4b5b-b963-828693caad58",
                "installment_status": "opened",
                "installment_number": 5,
                "workdays": 21,
                "calendar_days": 30,
                "principal_amortization_unit_price": 0.20395804,
                "principal_amortization_amount": 20395.80431829,
                "interest_amount": 201.13568171,
                "interest_amount_unit_price": 0.00201136,
                "post_fixed_interest_amount": 0.0,
                "post_fixed_interest_amount_unit_price": 0.0,
                "amount": 20596.94,
                "due_principal": 20395.80431829,
                "due_interest": 0.0,
                "due_date": "2025-07-18",
                "has_interest": true,
                "current_unit_price": 0.20395804,
                "latest_accrual_date": "2025-02-18",
                "paid_at": null,
                "paid_amount": 0.0,
                "settlement_process_list": []
            },
            {
                "installment_key": "b1f4fc31-7b73-45b8-bce7-4256394b974e",
                "installment_status": "paid",
                "installment_number": 1,
                "workdays": 18,
                "calendar_days": 28,
                "principal_amortization_unit_price": 0.19676756,
                "principal_amortization_amount": 19676.75638427,
                "interest_amount": 920.18361573,
                "interest_amount_unit_price": 0.00920184,
                "post_fixed_interest_amount": 0.0,
                "post_fixed_interest_amount_unit_price": 0.0,
                "amount": 20596.94,
                "due_principal": 100000.0,
                "due_interest": 0.0,
                "due_date": "2025-03-18",
                "has_interest": true,
                "current_unit_price": 0.19676756,
                "latest_accrual_date": "2025-02-18",
                "paid_at": "2025-02-18T18:39:47.174392",
                "paid_amount": 20596.94,
                "settlement_process_list": [
                    {
                        "settlement_process_key": "a9030b64-5003-4f82-be4f-8296a4e0b140",
                        "installment_key": "b1f4fc31-7b73-45b8-bce7-4256394b974e",
                        "due_date": "2025-03-18",
                        "reference_date": "2025-03-18",
                        "current_integralized_quantity": 100000,
                        "principal_amortization_amount": 19676.75638427,
                        "interest_amount": 920.18361573,
                        "post_fixed_interest_amount": 0.0,
                        "fine_amount": 0.0,
                        "total_amount": 20596.94,
                        "expected_total_amount": 20596.94,
                        "paid_amount": 20596.94,
                        "settlement_process_status": "paid",
                        "paid_at": "2025-02-18T18:39:47.185004",
                        "settlement_process_payment_list": [
                            {
                                "settlement_process_payment_key": "69615875-ed71-44f2-9a06-20f6ea4276f3",
                                "investment": {
                                    "investment_key": "4b705afb-18cb-4fe5-922a-5eab71c2b558",
                                    "acquisition_date": "2025-02-18",
                                    "acquisition_unit_price": 1.0,
                                    "acquisition_amount": 100000.0,
                                    "acquisition_quantity": 100000.0,
                                    "investor_key": "a1a75b66-6f7e-4bcc-9ff5-6f8adf7cae09",
                                    "investor_name": "Ultimate Cascade",
                                    "investor_document_number": "31.424.651/0001-32",
                                    "investor_bank_account": {
                                        "account_type": "checking",
                                        "account_digit": "3",
                                        "account_branch": "0001",
                                        "account_number": "33400254",
                                        "financial_institution_ispb": "32402502",
                                        "financial_institution_code_number": "329"
                                    },
                                    "total_sell_amount": 0.0,
                                    "total_yield_amount": 920.18,
                                    "total_amortization_amount": 20596.94,
                                    "current_quantity": 100000,
                                    "investment_transaction_list": [
                                        {
                                            "transaction_type": "integralization",
                                            "transaction_date": "2025-02-18",
                                            "transaction_unit_price": 1.0,
                                            "transaction_amount": 100000.0,
                                            "transaction_quantity": 100000.0,
                                            "amortization_amount": 0.0,
                                            "yield_amount": 0.0,
                                            "old_quantity": 0.0,
                                            "new_quantity": 100000.0,
                                            "investment_transaction_origin": "subscription",
                                            "investment_transaction_origin_key": "8549efc4-76e3-4e62-abd1-71162b383b4e"
                                        },
                                        {
                                            "transaction_type": "maturity",
                                            "transaction_date": "2025-03-18",
                                            "transaction_unit_price": 0.2059694,
                                            "transaction_amount": 20596.94,
                                            "transaction_quantity": 0.0,
                                            "amortization_amount": 20596.94,
                                            "yield_amount": 920.18,
                                            "old_quantity": 100000.0,
                                            "new_quantity": 100000.0,
                                            "investment_transaction_origin": "settlement_process_payment",
                                            "investment_transaction_origin_key": "69615875-ed71-44f2-9a06-20f6ea4276f3"
                                        }
                                    ]
                                },
                                "investment_quantity": 100000,
                                "amount": 20596.94,
                                "paid_at": "2025-02-18T18:39:47.159822",
                                "settlement_process_payment_status": "paid",
                                "settlement_process_payment_type": "manual",
                                "settlement_process_payment_receipt_list": [
                                    {
                                        "settlement_process_payment_receipt_key": "47fa434a-68cc-47d4-af8c-6a84061f38a6",
                                        "settlement_process_payment_receipt_status": "confirmed",
                                        "updated_at": "2025-02-18T18:39:47.153603"
                                    }
                                ]
                            }
                        ]
                    }
                ]
            },
            {
                "installment_key": "dafc9683-a2b3-4bde-bf9a-ff4b2ea2599f",
                "installment_status": "opened",
                "installment_number": 2,
                "workdays": 23,
                "calendar_days": 35,
                "principal_amortization_unit_price": 0.19671978,
                "principal_amortization_amount": 19671.97807672,
                "interest_amount": 924.96192328,
                "interest_amount_unit_price": 0.00924962,
                "post_fixed_interest_amount": 0.0,
                "post_fixed_interest_amount_unit_price": 0.0,
                "amount": 20596.94,
                "due_principal": 80323.24361573,
                "due_interest": 0.0,
                "due_date": "2025-04-22",
                "has_interest": true,
                "current_unit_price": 0.19671978,
                "latest_accrual_date": "2025-02-18",
                "paid_at": null,
                "paid_amount": 0.0,
                "settlement_process_list": []
            },
            {
                "installment_key": "aab04935-763e-4431-b0e8-d3d341d5c563",
                "installment_status": "opened",
                "installment_number": 3,
                "workdays": 18,
                "calendar_days": 27,
                "principal_amortization_unit_price": 0.20058857,
                "principal_amortization_amount": 20058.85739386,
                "interest_amount": 538.08260614,
                "interest_amount_unit_price": 0.00538083,
                "post_fixed_interest_amount": 0.0,
                "post_fixed_interest_amount_unit_price": 0.0,
                "amount": 20596.94,
                "due_principal": 60651.26553901,
                "due_interest": 0.0,
                "due_date": "2025-05-19",
                "has_interest": true,
                "current_unit_price": 0.20058857,
                "latest_accrual_date": "2025-02-18",
                "paid_at": null,
                "paid_amount": 0.0,
                "settlement_process_list": []
            },
            {
                "installment_key": "6a76fd8f-631b-4b42-ac2e-daae8f87401d",
                "installment_status": "opened",
                "installment_number": 4,
                "workdays": 22,
                "calendar_days": 30,
                "principal_amortization_unit_price": 0.20196604,
                "principal_amortization_amount": 20196.60382686,
                "interest_amount": 400.33617314,
                "interest_amount_unit_price": 0.00400336,
                "post_fixed_interest_amount": 0.0,
                "post_fixed_interest_amount_unit_price": 0.0,
                "amount": 20596.94,
                "due_principal": 40592.40814515,
                "due_interest": 0.0,
                "due_date": "2025-06-18",
                "has_interest": true,
                "current_unit_price": 0.20196604,
                "latest_accrual_date": "2025-02-18",
                "paid_at": null,
                "paid_amount": 0.0,
                "settlement_process_list": []
            }
        ]
    },
    "investment_list": [
        {
            "investment_key": "4b705afb-18cb-4fe5-922a-5eab71c2b558",
            "acquisition_date": "2025-02-18",
            "acquisition_unit_price": 1.0,
            "acquisition_amount": 100000.0,
            "acquisition_quantity": 100000.0,
            "investor_key": "a1a75b66-6f7e-4bcc-9ff5-6f8adf7cae09",
            "investor_name": "Ultimate Cascade",
            "investor_document_number": "31.424.651/0001-32",
            "investor_bank_account": {
                "account_type": "checking",
                "account_digit": "3",
                "account_branch": "0001",
                "account_number": "33400254",
                "financial_institution_ispb": "32402502",
                "financial_institution_code_number": "329"
            },
            "total_sell_amount": 0.0,
            "total_yield_amount": 920.18,
            "total_amortization_amount": 20596.94,
            "current_quantity": 100000,
            "investment_transaction_list": [
                {
                    "transaction_type": "integralization",
                    "transaction_date": "2025-02-18",
                    "transaction_unit_price": 1.0,
                    "transaction_amount": 100000.0,
                    "transaction_quantity": 100000.0,
                    "amortization_amount": 0.0,
                    "yield_amount": 0.0,
                    "old_quantity": 0.0,
                    "new_quantity": 100000.0,
                    "investment_transaction_origin": "subscription",
                    "investment_transaction_origin_key": "8549efc4-76e3-4e62-abd1-71162b383b4e"
                },
                {
                    "transaction_type": "maturity",
                    "transaction_date": "2025-03-18",
                    "transaction_unit_price": 0.2059694,
                    "transaction_amount": 20596.94,
                    "transaction_quantity": 0.0,
                    "amortization_amount": 20596.94,
                    "yield_amount": 920.18,
                    "old_quantity": 100000.0,
                    "new_quantity": 100000.0,
                    "investment_transaction_origin": "settlement_process_payment",
                    "investment_transaction_origin_key": "69615875-ed71-44f2-9a06-20f6ea4276f3"
                }
            ]
        }
    ]
}
```

## **Response Body Params**

| Campo                        | Tipo     | Descrição                                                    |
|------------------------------|----------|--------------------------------------------------------------|
| `tenant_key`                 | string   | Chave única do tenant associado ao security.                 |
| `security_key`               | string   | Chave única do security.                                     |
| `operation_key`              | string   | Chave única da operação associada ao security.               |
| `operation_type`             | string   | Tipo da operação. Valores possíveis: `commercial_paper`.     |
| `contract_number`            | string   | Número do contrato associado ao security.                    |
| `issuer_key`                 | string   | Chave única do emissor associado.                            |
| `issuer_name`                | string   | Nome do emissor do security.                                 |
| `issuer_document_number`     | string   | Número do documento do emissor (CPF/CNPJ).                   |
| `issuer_bank_account`        | object   | **[Objeto issuer_bank_account](#objeto-bank_account)**.      |
| `financial_base_date`        | string   | Data base financeira do security.                            |
| `current_unit_price`         | number   | Preço unitário atual do security.                            |
| `latest_accrual_date`        | string   | Data do último accrual realizado.                            |
| `integralized_quantity`      | integer  | Quantidade total de cotas integralizadas.                    |
| `issue_quantity`             | integer  | Quantidade total de cotas emitidas na operação.              |
| `security_status`            | string   | Status do security. Valores possíveis: `active`, `inactive`. |
| `is_defaulted`              | boolean  | Indica se o security está inadimplente (`true` ou `false`).  |
| `financial`                  | object   | **[Objeto financial](#objeto-financial)**.                   |
| `investment_list`            | array    | Lista de investimentos. **[Objeto investment](#objeto-investment)**. |

---

### **Objeto bank_account**

| Campo                          | Tipo     | Descrição                                       |
|--------------------------------|----------|-------------------------------------------------|
| `account_number`              | string   | Número da conta bancária do emissor.           |
| `account_digit`               | string   | Dígito verificador da conta bancária do emissor. |
| `account_branch`              | string   | Agência bancária do emissor.                   |
| `financial_institution_ispb`  | string   | ISPB da instituição financeira do emissor.     |
| `financial_institution_code_number` | string | Código da instituição financeira do emissor. |

---

### **Objeto financial**

| Campo                          | Tipo     | Descrição                                       |
|--------------------------------|----------|-------------------------------------------------|
| `financial_base_date`          | string   | Data base financeira.                           |
| `issue_quantity`               | integer  | Quantidade de cotas emitidas.                   |
| `unit_price`                   | number   | Preço unitário das cotas.                       |
| `issue_amount`                 | number   | Valor total da emissão.                         |
| `released_amount`              | number   | Valor total liberado.                           |
| `cet`                          | number   | Custo efetivo total (CET).                      |
| `annual_cet`                   | number   | Custo efetivo total anualizado.                 |
| `number_of_installments`       | integer  | Número total de parcelas.                       |
| `prefixed_interest_rate`       | object   | **[Objeto prefixed_interest_rate](#objeto-prefixed_interest_rate)**. |
| `post_fixed_interest_rate`     | object   | **[Objeto post_fixed_interest_rate](#objeto-post_fixed_interest_rate)**. |
| `financial_index`              | object   | **[Objeto financial_index](#objeto-financial_index)**. |
| `fine_delay_rate`              | object   | **[Objeto fine_delay_rate](#objeto-fine_delay_rate)**. |
| `contract_fine_rate`           | number   | Multa contratual.                              |
| `fees`                         | array    | Lista de taxas. **[Objeto fees](#objeto-fees)**. |
| `installment_list`             | array    | Lista de parcelas. **[Objeto installment](#objeto-installment)**. |

---

### **Objeto investment**

| Campo                          | Tipo     | Descrição                                       |
|--------------------------------|----------|-------------------------------------------------|
| `investment_key`               | string   | Chave única do investimento.                    |
| `acquisition_date`             | string   | Data de aquisição do investimento.              |
| `acquisition_unit_price`       | number   | Preço unitário na aquisição.                    |
| `acquisition_amount`           | number   | Valor total da aquisição.                       |
| `acquisition_quantity`         | integer  | Quantidade de cotas adquiridas.                 |
| `investor_key`                 | string   | Chave única do investidor.                      |
| `investor_name`                | string   | Nome do investidor.                             |
| `investor_document_number`     | string   | Documento do investidor (CPF/CNPJ).             |
| `investor_bank_account`        | object   | **[Objeto investor_bank_account](#objeto-bank_account)**. |
| `total_sell_amount`            | number   | Valor total de vendas realizadas.               |
| `total_yield_amount`           | number   | Valor total de rendimentos.                     |
| `total_amortization_amount`    | number   | Valor total de amortizações.                    |
| `current_quantity`             | integer  | Quantidade atual de cotas.                      |
| `investment_transaction_list`  | array    | Lista de transações. **[Objeto investment_transaction](#objeto-investment_transaction)**. |

---

### **Objeto investment_transaction**

| Campo                          | Tipo     | Descrição                                       |
|--------------------------------|----------|-------------------------------------------------|
| `transaction_type`             | string   | Tipo da transação (`integralization`, `maturity`). |
| `transaction_date`             | string   | Data da transação.                              |
| `transaction_unit_price`       | number   | Preço unitário na transação.                    |
| `transaction_amount`           | number   | Valor total da transação.                       |
| `transaction_quantity`         | integer  | Quantidade de cotas transacionadas.             |
| `amortization_amount`          | number   | Valor de amortização na transação.              |
| `yield_amount`                 | number   | Valor de rendimento na transação.               |
| `old_quantity`                 | integer  | Quantidade de cotas antes da transação.         |
| `new_quantity`                 | integer  | Quantidade de cotas após a transação.           |
| `investment_transaction_origin`| string   | Origem da transação (`subscription`, `settlement_process_payment`). |
| `investment_transaction_origin_key` | string | Chave da origem da transação. |

### **Objeto prefixed_interest_rate**

| Campo               | Tipo   | Descrição                                          |
|---------------------|--------|--------------------------------------------------|
| `daily_rate`       | number | Taxa de juros diária prefixada.                  |
| `annual_rate`      | number | Taxa de juros anual prefixada.                   |
| `monthly_rate`     | number | Taxa de juros mensal prefixada.                  |
| `interest_base`    | string | Base de cálculo dos juros (`calendar_days_365`). |

---

### **Objeto post_fixed_interest_rate**

| Campo               | Tipo   | Descrição                                           |
|---------------------|--------|---------------------------------------------------|
| `daily_rate`       | number | Taxa de juros diária pós-fixada.                   |
| `annual_rate`      | number | Taxa de juros anual pós-fixada.                    |
| `monthly_rate`     | number | Taxa de juros mensal pós-fixada.                   |
| `interest_base`    | string | Base de cálculo dos juros (`calendar_days_365`).   |

---

### **Objeto financial_index**

| Campo            | Tipo   | Descrição                                         |
|------------------|--------|-------------------------------------------------|
| `index_type`    | string | Tipo do índice financeiro (`CDI`, `IPCA`, etc.). |
| `index_value`   | number | Valor do índice financeiro.                      |

---

### **Objeto fine_delay_rate**

| Campo               | Tipo   | Descrição                                        |
|---------------------|--------|------------------------------------------------|
| `daily_rate`       | number | Taxa de juros diária para atraso no pagamento.  |
| `annual_rate`      | number | Taxa de juros anual para atraso no pagamento.   |
| `monthly_rate`     | number | Taxa de juros mensal para atraso no pagamento.  |
| `interest_base`    | string | Base de cálculo dos juros (`calendar_days_365`).|

---

### **Objeto fees**

| Campo        | Tipo    | Descrição                                    |
|-------------|---------|--------------------------------------------|
| `type`      | string  | Tipo da taxa (`internal`, `external`).     |
| `amount`    | number  | Percentual ou valor absoluto da taxa.      |
| `fee_type`  | string  | Tipo da taxa.                              |
| `fee_amount`| number  | Valor monetário da taxa aplicada.          |
| `amount_type` | string | Tipo do valor (`percentage`, `absolute`). |

---

### **Objeto installment**

| Campo                                  | Tipo    | Descrição                                                   |
|----------------------------------------|---------|-----------------------------------------------------------|
| `installment_key`                      | string  | Chave única da parcela.                                     |
| `installment_status`                   | string  | Status da parcela                      |
| `installment_number`                   | integer | Número da parcela na sequência do cronograma.               |
| `workdays`                              | integer | Quantidade de dias úteis até o vencimento.                  |
| `calendar_days`                         | integer | Quantidade de dias corridos até o vencimento.               |
| `principal_amortization_unit_price`     | number  | Valor unitário da amortização do principal.                 |
| `principal_amortization_amount`         | number  | Valor total da amortização do principal.                    |
| `interest_amount`                       | number  | Valor total dos juros da parcela.                           |
| `interest_amount_unit_price`            | number  | Valor unitário dos juros da parcela.                        |
| `post_fixed_interest_amount`            | number  | Valor total dos juros pós-fixados da parcela.               |
| `post_fixed_interest_amount_unit_price` | number  | Valor unitário dos juros pós-fixados da parcela.            |
| `amount`                                | number  | Valor total da parcela.                                     |
| `due_principal`                         | number  | Valor do principal pendente antes da parcela.               |
| `due_interest`                          | number  | Valor dos juros pendentes antes da parcela.                 |
| `due_date`                              | string  | Data de vencimento da parcela.                              |
| `has_interest`                          | boolean | Indica se a parcela contém juros (`true` ou `false`).       |
| `current_unit_price`                    | number  | Preço unitário atualizado da parcela.                       |
| `latest_accrual_date`                   | string  | Data do último accrual da parcela.                          |
| `paid_at`                               | string  | Data do pagamento da parcela (se aplicável).                |
| `paid_amount`                           | number  | Valor total pago da parcela (se aplicável).                 |
| `settlement_process_list`               | array   | Lista de processos de liquidação. **[Objeto settlement_process](#objeto-settlement_process)** |

### **Objeto settlement_process**

| Campo                                   | Tipo    | Descrição                                                                                                                |
|-----------------------------------------|---------|--------------------------------------------------------------------------------------------------------------------------|
| `settlement_process_key`                | string  | Chave única do processo de liquidação.                                                                                   |
| `installment_key`                        | string  | Chave única da parcela associada à liquidação.                                                                           |
| `due_date`                               | string  | Data de vencimento da parcela associada.                                                                                 |
| `reference_date`                         | string  | Data de referência da liquidação.                                                                                        |
| `current_integralized_quantity`          | integer | Quantidade de cotas integralizadas no momento da liquidação.                                                             |
| `principal_amortization_amount`          | number  | Valor da amortização do principal.                                                                                       |
| `interest_amount`                        | number  | Valor total dos juros pagos na liquidação.                                                                               |
| `post_fixed_interest_amount`             | number  | Valor dos juros pós-fixados pagos na liquidação.                                                                         |
| `fine_amount`                            | number  | Valor da multa aplicada (se houver).                                                                                     |
| `total_amount`                           | number  | Valor total da liquidação.                                                                                               |
| `expected_total_amount`                   | number  | Valor total esperado da liquidação.                                                                                      |
| `paid_amount`                            | number  | Valor total pago na liquidação.                                                                                          |
| `settlement_process_status`              | string  | Status da liquidação (`waiting_payment`, `paid`, `canceled`).                                                            |
| `paid_at`                                | string  | Data do pagamento da liquidação (se aplicável).                                                                          |
| `settlement_process_payment_list`        | array   | Lista de pagamentos associados à liquidação. **[Objeto settlement_process_payment](#objeto-settlement_process_payment)** |

### **Objeto settlement_process_payment**  

| Campo                                       | Tipo    | Descrição                                                                                                                   |
|---------------------------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------|
| `settlement_process_payment_key`           | string  | Chave única do pagamento do processo de liquidação.                                                                         |
| `investment`                                | object  | Informações do investimento. **[Objeto investment](#objeto-investment)**.                                                   |
| `investment_quantity`                       | integer | Quantidade de cotas do investimento envolvidas no pagamento.                                                                |
| `amount`                                    | number  | Valor do pagamento realizado.                                                                                               |
| `paid_at`                                   | string  | Data e hora do pagamento (formato ISO 8601).                                                                                |
| `settlement_process_payment_status`        | string  | Status do pagamento (`waiting_payment`, `paid`, `canceled`).                                                                |
| `settlement_process_payment_type`          | string  | Tipo do pagamento (`manual`).                                                                                               |
| `settlement_process_payment_receipt_list`  | array   | Lista de recibos do pagamento. **[Objeto settlement_process_payment_receipt](#objeto-settlement_process_payment_receipt)**. |

### **Objeto settlement_process_payment_receipt**  

| Campo                                       | Tipo   | Descrição                                                         |
|---------------------------------------------|--------|-------------------------------------------------------------------|
| `settlement_process_payment_receipt_key`    | string | Chave única do recibo de pagamento do processo de liquidação.     |
| `settlement_process_payment_receipt_status` | string | Status do recibo (`waiting_confirmation`, `confirmed`, `denied`). |
| `amount`                                    | number | Valor do recibo.                                                  |
| `updated_at`                                | string | Data e hora da última atualização do recibo (formato ISO 8601).   |

### **Enumeradores security_status**

| Enum      | Descrição                                             |
|-----------|------------------------------------------------------|
| `issued`  | A security foi emitida, mas ainda não está ativa.   |
| `active`  | A security está ativa e em andamento.               |
| `matured` | A security chegou ao vencimento.                    |
| `canceled` | A security foi cancelada.                          |

### **Enumeradores installment_status**

| Enum                        | Descrição                                                              |
|-----------------------------|-----------------------------------------------------------------------|
| `created`                   | A parcela foi criada, mas ainda não está disponível para pagamento.   |
| `opened`                    | A parcela está aberta.                         |
| `waiting_payment`           | A parcela está aguardando o pagamento pelo investidor.               |
| `paid_partial`              | A parcela foi parcialmente paga.                                      |
| `paid`                      | A parcela foi totalmente paga.                                       |
| `paid_early`                | A parcela foi paga antecipadamente.                                  |
| `overdue`                   | A parcela venceu e não foi paga.                                     |
| `paid_partial_overdue`      | A parcela foi parcialmente paga após o vencimento.                  |
| `paid_overdue`              | A parcela foi paga após o vencimento.                               |
| `canceled`                  | A parcela foi cancelada e não precisa ser paga.                     |
| `unmonitored`               | A parcela não é monitorada para pagamentos.                         |

---

# Consulta de Posição do Investidor

URL: /documentation/escrituracao/operacoes-ativas/posicao-investidor

Este endpoint permite consultar a posição consolidada de um investidor, retornando informações sobre suas participações em securities.

---

## Request
ENDPOINT /security/investor/ INVESTOR-KEY
MÉTODO GET

### Path Params

| Campo         | Tipo   | Descrição                                      | Caracteres |
|--------------|--------|-----------------------------------------------|------------|
| `INVESTOR-KEY` | string | Chave única do investidor (UUID v4).         | 36         |

---

### Response
STATUS 200

Response Body

```json
{
    "investor_key": "a1a75b66-6f7e-4bcc-9ff5-6f8adf7cae09",
    "investor_name": "Ultimate Cascade",
    "investor_document_number": "31.424.651/0001-32",
    "total_current_amount": 100000.0,
    "investment_list": [
        {
            "current_unit_price": 1.0,
            "current_quantity": 100000,
            "security_key": "42bd7161-5ec1-4f64-ac0c-861d93ffb4c2",
            "contract_number": "0000000027",
            "investment_key": "4b705afb-18cb-4fe5-922a-5eab71c2b558",
            "current_amount": 100000.0
        }
    ]
}
```

---

### Response Body Params

| Campo                      | Tipo     | Descrição                                                        |
|----------------------------|----------|--------------------------------------------------------------------|
| `investor_key`             | string   | Chave única do investidor.                                        |
| `investor_name`            | string   | Nome do investidor.                                              |
| `investor_document_number` | string   | Número do documento do investidor (CNPJ).                   |
| `total_current_amount`     | number   | Valor total consolidado do investidor.                            |
| `investment_list`          | array    | Lista das participações do investidor em securities. **[Objeto investment](#objeto-investment)** |

### Objeto investment

| Campo                 | Tipo     | Descrição                                        |
|-----------------------|----------|--------------------------------------------------|
| `current_unit_price`  | number   | Preço unitário atual da security.               |
| `current_quantity`    | integer  | Quantidade atual da security do investidor.     |
| `security_key`        | string   | Chave única da security associada.              |
| `contract_number`     | string   | Número do contrato da security.                 |
| `investment_key`      | string   | Chave única do investimento do investidor.      |
| `current_amount`      | number   | Valor atual da participação do investidor.      |

---

# Roteiro de Integração — API de Escrituração de Notas Comerciais (NC) com Auto-Assinatura

URL: /documentation/escrituracao/roteiro-integracao/integration-guide-nc-auto-signature

Este roteiro descreve todos os recursos e funcionalidades que precisam ser testados pelo parceiro
integrador no ambiente de **Sandbox** da QI Tech, antes da entrada em ambiente de produção para
emissão de notas comerciais (NC).

Trata-se de uma versão personalizada do roteiro padrão de integração de NC da QI Tech, adaptada para
o **fluxo de emissão totalmente automatizado**: uma vez que o emissor esteja cadastrado, aprovado e
habilitado para auto-assinatura, todas as emissões seguintes ocorrem de ponta a ponta via API, sem
etapa manual de assinatura.

:::warning Atenção
**Todos os testes devem ser obrigatoriamente realizados no ambiente de Sandbox da QI Tech. As
operações realizadas em ambiente de Sandbox são operações financeiras fictícias, servindo apenas para
teste de funcionalidade das APIs.**
:::

---

## 1. Escopo e fases

O fluxo é dividido em seis fases. As fases 0 a 4 se apoiam em funcionalidades já disponíveis na API, incluindo a habilitação da auto-assinatura (Fase 2), que já está publicada. A Fase 6 é dividida em duas: a transferência de recursos para a conta de liquidação da WL (6.1) utiliza endpoints de BaaS que já existem e podem ser homologados hoje; o pagamento ao fornecedor (6.2) depende de novo desenvolvimento.

| Legenda | Significado |
| --- | --- |
| ✅ | Disponível hoje — pode ser homologado em Sandbox imediatamente |
| 🆕 | Novo desenvolvimento — contrato do endpoint a ser publicado; a homologação começa após a liberação |
| ⚙️ | Executado pela QI Tech (sem ação do integrador, mas o integrador precisa observar o status resultante) |
| `*` | Etapa obrigatória para o aceite da homologação |

:::warning Premissa de sequenciamento
**A habilitação só pode ser solicitada depois que o cadastro do emissor é aprovado** — e pode, e
deve, ser concluída **antes da primeira emissão**. O termo de adesão é assinado em um **envelope
próprio, com um link por assinante**, independente de qualquer operação: não é preciso criar uma NC
para habilitá-la, nem existe uma "primeira emissão manual" obrigatória. A Fase 2 é, portanto, um portão único por
emissor, e não uma etapa por operação — concluída antes da primeira emissão, todas as emissões
daquele emissor já saem com assinatura automática.
:::

---

## 2. Fluxo ponta a ponta

```mermaid
flowchart TD
    A[Fase 0 · Troca de chaves, autenticação, webhooks] --> B{Emissor já<br/>cadastrado na QI Tech?}
    B -- Sim --> C[Fase 1A · Reutilizar cadastro existente]
    B -- Não --> D[Fase 1B · Cadastrar emissor do zero]
    C --> E[Emissor aprovado]
    D --> E
    E --> F[Fase 2 · Integrador solicita a habilitação<br/>POST auto_signature]
    F --> F2[Mesma chamada gera o termo<br/>e abre o envelope de assinatura]
    F2 --> G[Termo de adesão assinado uma única vez<br/>cada assinante no seu próprio link]
    G --> H[QI Tech emite certificado privado<br/>na CertifiQI — apenas documentos de NC ⚙️]
    H --> I[Status da auto-assinatura: enabled]
    I --> J[Fase 4 · NC criada via API]
    J --> K[Enviada para análise → aprovada automaticamente]
    K --> L[Termo Constitutivo assinado automaticamente<br/>via certificado privado]
    L --> M[Fase 5 · Boletim de subscrição<br/>emitido e assinado automaticamente]
    M --> N[Webhook · Boletim de subscrição assinado]
    N --> O[Fase 6.1 · Sistema do cliente comanda transferência<br/>BaaS para a conta de liquidação da WL 🆕]
    O --> P[Fase 6.2 · Pagamento da conta de liquidação<br/>para o fornecedor 🆕]
```

---

## 3. Fase 0 — Cadastro e autenticação na API

| Código | Etapa | Descrição | Documentação | Pré-requisito | Status |
| --- | --- | --- | --- | --- | --- |
| CAB0001* | Troca de chave pública | Realizar a troca de chave pública com o time de operações da plataforma (suporte-dcm@qitech.com.br) | [Documentação](/documentation/escrituracao/introducao/troca_de_chaves) | — | ✅ |
| CAB0002* | Teste de autenticação | Após o recebimento da chave de API, realizar os testes de autenticação de chamada | [Documentação](/documentation/escrituracao/introducao/teste-autenticacao/teste_de_autenticacao) <br/><br/> [Documentação](/documentation/escrituracao/introducao/teste-autenticacao/endpoints_de_teste) | CAB0001 | ✅ |
| CAB0003* | Configuração de webhooks | Configurar a URL para a qual a QI Tech enviará os webhooks | [Documentação](/documentation/escrituracao/introducao/autenticacao_webhooks) <br/><br/> [Documentação](/documentation/escrituracao/configuracao-webhooks) <br/><br/> [Documentação](/documentation/escrituracao/webhooks-escrituracao) | CAB0001, CAB0002 | ✅ |

:::warning Atenção
Neste fluxo, a configuração de webhooks é obrigatória, e não opcional. Como a análise, a aprovação e a
assinatura são automáticas, o integrador não possui nenhum ponto de conferência manual — os webhooks
são a única forma de acompanhar o avanço da operação sem polling.
:::

---

## 4. Fase 1 — Homologação do emissor

:::warning Atenção
**Caso o cliente já tenha realizado a integração com os cadastros de cedente da QI Tech, é possível
reutilizar esses cadastros, o que simplifica consideravelmente a homologação no sistema.**
:::

### 4.1 Fase 1A — Emissor cadastrado no sistema de cedentes da QI Tech

| Código | Etapa | Descrição | Documentação | Pré-requisito | Status |
| --- | --- | --- | --- | --- | --- |
| CED1001* | Reutilizar cadastro de cedente | Reutilizar um cadastro de cedente existente por CNPJ | [Documentação](/documentation/escrituracao/homologacao-emissor/solicitacao-acesso) | CAB0002 | ✅ |
| CED1002* | Listar emissores cadastrados | Listar os emissores cadastrados, filtrando por CNPJ ou nome | [Documentação](/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-filtro) | CED1001 | ✅ |
| CED1003* | Detalhes do emissor | Consultar os detalhes de um emissor cadastrado pela `issuer_key` | [Documentação](/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-chave) | CED1001 | ✅ |

### 4.2 Fase 1B — Emissor cadastrado pelo sistema

| Código | Etapa | Descrição | Documentação | Pré-requisito | Status |
| --- | --- | --- | --- | --- | --- |
| CED0001* | Cadastro básico do emissor | Criar o emissor com seus dados cadastrais básicos | [Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/cadastro-basico) | CAB0002 | ✅ |
| CED0002* | Upload / remoção de documentos do emissor | Anexar e remover documentos associados a um emissor cadastrado | [Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor) <br/><br/> [Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor-remocao) | CED0001 | ✅ |
| CED0003* | Cadastro / remoção de representantes do emissor | Adicionar e remover representantes associados a um emissor cadastrado | [Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor) <br/><br/> [Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor-remocao) | CED0001 | ✅ |
| CED0004* | Upload / remoção de documentos de representantes | Anexar e remover documentos associados a um representante de um emissor cadastrado | [Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor) <br/><br/> [Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor-remocao) | CED0001, CED0003 | ✅ |
| CED0005* | Cadastro / remoção de conta bancária do emissor | Adicionar e remover uma conta bancária associada a um emissor cadastrado | [Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor) <br/><br/> [Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor-remocao) | CED0001 | ✅ |
| CED0006* | Cadastro / remoção de grupos de assinantes do emissor | Adicionar e remover grupos de assinantes associados a um emissor cadastrado | [Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor) <br/><br/> [Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor-remocao) | CED0001, CED0003 | ✅ |
| CED0007* | Cadastro / remoção de informações de contato do emissor | Adicionar e remover informações de contato associadas a um emissor cadastrado | [Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor) <br/><br/> [Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor-remocao) | CED0001 | ✅ |
| CED0008* | Envio do emissor para análise | Mover o emissor para o status de análise, enviando-o ao processo de validação | [Documentação](/documentation/escrituracao/homologacao-emissor/envio-analise/) | CED0001 → CED0007 | ✅ |
| CED0009* | Alteração do cadastro do emissor | Reabrir o emissor para edição | [Documentação](/documentation/escrituracao/homologacao-emissor/alteracao-cadastro/) | CED0001 → CED0007 | ✅ |
| CED0010* | Listar emissores cadastrados | Listar os emissores cadastrados, filtrando por CNPJ ou nome | [Documentação](/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-filtro) | CED0001 | ✅ |
| CED0011* | Detalhes do emissor | Consultar os detalhes de um emissor cadastrado pela `issuer_key` | [Documentação](/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-chave) | CED0001 | ✅ |

:::warning Portão para a Fase 2
O grupo de assinantes cadastrado em **CED0006** define qual representante assinará em nome do
emissor. Esse mesmo grupo de assinantes é quem assina o termo de adesão da auto-assinatura na Fase 2 e cuja
alçada o certificado privado representa. Cadastre-o corretamente antes de enviar o emissor para
análise — uma alteração posterior exige repetir a Fase 2.
:::

---

## 5. Fase 2 — Habilitação da auto-assinatura ✅

Esta fase ocorre **uma única vez por emissor**, logo após a aprovação do cadastro, e resulta em um
certificado privado da QI Tech com escopo exclusivo aos documentos de NC desta integração.

**A habilitação é solicitada pelo integrador**, com um `POST` que só é aceito depois que o cadastro
do emissor está aprovado. Não há criação automática. O cliente precisa estar habilitado para
auto-assinatura — uma configuração feita pela QI Tech, que inclui o template do termo de adesão.

**A solicitação já abre o envelope.** A geração do termo e a criação do envelope acontecem dentro
da própria chamada, que responde em `pending_signature` com a `envelope_key` — os links de
assinatura podem ser consultados na sequência, sem esperar por webhook.

**O que o termo de adesão autoriza.** Ele concede à QI Tech um mandato limitado para emitir e
custodiar um certificado privado interno, liberado na CertifiQI, a ser utilizado exclusivamente para
assinar os documentos deste fluxo de NC em nome do emissor — nunca para qualquer outro documento,
produto ou contraparte. É assinado uma única vez pelo grupo de assinantes cadastrado no emissor —
**cada assinante recebe o seu próprio link de assinatura**.

**Quando é assinado.** O termo tem **envelope e link de assinatura próprios**, gerados na
habilitação e independentes de qualquer operação. Ele pode ser assinado assim que o emissor é
aprovado, **antes da primeira emissão** — que é o caminho recomendado, porque leva o emissor à
primeira operação já com a assinatura automática ativa. Se a Fase 2 ainda não tiver sido concluída
quando a operação for criada, ela simplesmente segue pelo fallback manual do QI SIGN, como qualquer
emissor em status diferente de `enabled`.

| Código | Etapa | Descrição | Documentação | Pré-requisito | Status |
| --- | --- | --- | --- | --- | --- |
| ASG0001* | Habilitação do cliente para auto-assinatura | A QI Tech habilita o cliente e configura o template do termo de adesão. Sem isso, nenhum emissor do cliente tem auto-assinatura criada | [Documentação](/documentation/escrituracao/homologacao-emissor/auto-assinatura/inicio) | — | ⚙️ |
| ASG0002* | Solicitar a habilitação | `POST /issuer_management/issuer/{issuer_key}/auto_signature` para um emissor aprovado. A mesma chamada gera o termo de adesão e abre o envelope: retorna a `issuer_auto_signature_key` e a `envelope_key` já em `pending_signature`. Recusado com `ISS0000032` se o emissor não estiver aprovado | [Documentação](/documentation/escrituracao/homologacao-emissor/auto-assinatura/solicitacao-auto-assinatura) | ASG0001, CED0011 ou CED1003 | ✅ |
| ASG0003 | Webhook — termo enviado para assinatura | Receber o webhook `issuer_management.auto_signature_status_change` com status `pending_signature`. Confirma o que a resposta do ASG0002 já trouxe, e avisa os demais consumidores do tenant | [Documentação](/documentation/escrituracao/webhooks-escrituracao) | CAB0003, ASG0002 | ✅ |
| ASG0004* | Consultar os links de assinatura | `GET .../auto_signature/signers` devolve um link por assinante, com o status individual de cada um. Direcionar **cada assinante do emissor ao seu próprio link**. Os links independem de qualquer operação — podem ser usados antes da primeira emissão | [Documentação](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-links-assinatura) | ASG0002 | ✅ |
| ASG0005* | Webhook — auto-assinatura habilitada | Receber o webhook com status `enabled`, que confirma que o termo foi assinado e o emissor está habilitado à assinatura automática | [Documentação](/documentation/escrituracao/webhooks-escrituracao) | CAB0003, ASG0004 | ✅ |
| ASG0006* | Consultar status da auto-assinatura | Consultar a habilitação pela `issuer_key` e confirmar a transição para `enabled`, com o histórico de eventos. Nenhuma NC pode depender da assinatura automática antes de esse status ser atingido | [Documentação](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-auto-assinatura) | ASG0002 | ✅ |
| ASG0007 | Emissão do certificado privado | A QI Tech cria o certificado privado e o libera na CertifiQI, com escopo restrito aos documentos de NC deste emissor. Hoje é manual (uma única vez por emissor, executado pela QI Tech); a automação está no roadmap e não bloqueia o go-live | — | ASG0005 | ⚙️ |
| ASG0008 | Cancelar a auto-assinatura | Cancelar a habilitação — necessário quando o grupo de assinantes muda ou a pedido do emissor. Solicitado à QI Tech; não há endpoint público. Após o cancelamento, as emissões voltam ao fluxo manual até que uma nova habilitação seja solicitada | — | ASG0006 | ⚙️ |

:::info Cancelamento automático
A auto-assinatura é cancelada automaticamente quando o emissor deixa o status `approved` — ou seja,
quando passa para `reproved`, `expired` ou `canceled`. A habilitação precisa ser refeita após a nova
aprovação do cadastro.
:::

### 5.1 Máquina de status da habilitação

| Status | Significado | Comportamento de assinatura de uma nova NC |
| --- | --- | --- |
| _sem auto-assinatura_ | Habilitação nunca solicitada, ou cliente não habilitado | Assinatura manual (QI SIGN) |
| `pending_term_generation` | Habilitação solicitada; termo de adesão ainda não gerado | Assinatura manual |
| `pending_signature` | Termo gerado e enviado para assinatura; links dos assinantes disponíveis | Assinatura manual — o termo é assinado em links próprios, fora da operação |
| `enabled` | Termo assinado; emissor habilitado à assinatura automática | **Automática** |
| `reproved` | Envelope do termo recusado, cancelado ou expirado | Assinatura manual (QI SIGN) |
| `canceled` | Habilitação cancelada | Assinatura manual (QI SIGN) |

:::warning Requisito de homologação
O integrador deve demonstrar, em Sandbox, que seu sistema lê o status da habilitação antes de criar
uma operação e roteia corretamente nos dois sentidos: assinatura automática quando `enabled` e o
fallback do QI SIGN (COM0015 / COM0016) em todos os demais status. Uma integração que assume `enabled`
vai quebrar para todo emissor cuja Fase 2 ainda não tenha sido concluída.
:::

---

## 6. Fase 3 — Homologação do investidor

:::warning Atenção
**Caso o cliente opere com fundos fixos, estes podem ser cadastrados durante o setup, o que simplifica
consideravelmente a integração.** Para este fluxo, o caminho de fundos fixos é a configuração
esperada.
:::

### 6.1 Investidores cadastrados durante o setup — caminho recomendado

| Código | Etapa | Descrição | Documentação | Pré-requisito | Status |
| --- | --- | --- | --- | --- | --- |
| INV1001* | Listar investidores cadastrados | Listar os fundos cadastrados, filtrando por CNPJ ou nome | [Documentação](/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-filtro) | CAB0002 | ✅ |
| INV1002* | Detalhes do investidor | Consultar os detalhes de um investidor cadastrado pela `investor_key` | [Documentação](/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-chave) | CAB0002 | ✅ |

### 6.2 Investidores cadastrados pelo sistema — apenas se não forem utilizados fundos fixos

| Código | Etapa | Descrição | Documentação | Pré-requisito | Status |
| --- | --- | --- | --- | --- | --- |
| INV0001* | Cadastro básico do investidor | Criar o investidor com seus dados cadastrais básicos | [Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/cadastro-basico) | CAB0002 | ✅ |
| INV0002* | Upload / remoção de documentos do investidor | Anexar e remover documentos associados a um investidor cadastrado | [Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor) <br/><br/> [Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor-remocao) | INV0001 | ✅ |
| INV0003* | Cadastro / remoção de representantes do investidor | Adicionar e remover representantes associados a um investidor cadastrado | [Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor) <br/><br/> [Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor-remocao) | INV0001 | ✅ |
| INV0004* | Upload / remoção de documentos de representantes | Anexar e remover documentos associados a um representante de um investidor cadastrado | [Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor) <br/><br/> [Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor-remocao) | INV0001, INV0003 | ✅ |
| INV0005* | Cadastro / remoção de conta bancária do investidor | Adicionar e remover uma conta bancária associada a um investidor cadastrado | [Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor) <br/><br/> [Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor-remocao) | INV0001 | ✅ |
| INV0006* | Cadastro / remoção de grupos de assinantes do investidor | Adicionar e remover grupos de assinantes associados a um investidor cadastrado | [Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor) <br/><br/> [Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor-remocao) | INV0001 | ✅ |
| INV0007* | Cadastro / remoção de informações de contato do investidor | Adicionar e remover informações de contato associadas a um investidor cadastrado | [Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor) <br/><br/> [Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor-remocao) | INV0001 | ✅ |
| INV0008* | Envio do investidor para análise | Mover o investidor para o status de análise, enviando-o ao processo de validação | [Documentação](/documentation/escrituracao/homologacao-investidor/envio-analise/) | INV0001 → INV0007 | ✅ |
| INV0009* | Alteração do cadastro do investidor | Reabrir o investidor para edição | [Documentação](/documentation/escrituracao/homologacao-investidor/alteracao-cadastro/) | INV0001 → INV0007 | ✅ |
| INV0010* | Listar investidores cadastrados | Listar os fundos cadastrados, filtrando por CNPJ ou nome | [Documentação](/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-filtro) | INV0001 | ✅ |
| INV0011* | Detalhes do investidor | Consultar os detalhes de um investidor cadastrado pela `investor_key` | [Documentação](/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-chave) | INV0001 | ✅ |

---

## 7. Fase 4 — Emissão da NC

Com emissores e investidores cadastrados, as notas comerciais podem ser emitidas. A emissão via API é
a premissa central desta integração: o fluxo por tela não funciona no volume pretendido.

### 7.1 Criação da operação

| Código | Etapa | Descrição | Documentação | Pré-requisito | Status |
| --- | --- | --- | --- | --- | --- |
| COM0001* | Simular condições financeiras | Simular as condições financeiras e o cronograma de pagamento de uma operação | [Documentação](/documentation/escrituracao/emissao-de-notas/simulacao) | CAB0002 | ✅ |
| COM0002* | Criar operação de NC | Criar uma nova operação de nota comercial a partir dos dados financeiros e do investidor | [Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/criar-operacao) | COM0001, CED0011/CED1003, INV1002 | ✅ |
| COM0003* | Cadastro / remoção de partes relacionadas | Adicionar e remover partes relacionadas a uma operação | [Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/cadastrar-parte-relacionada) | COM0002 | ✅ |
| COM0004* | Upload / remoção de documentos de representantes de partes relacionadas | Anexar e remover documentos associados a representantes de partes relacionadas | [Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-documento) | COM0002, COM0003 | ✅ |
| COM0005* | Cadastro / remoção de grupos de assinantes de partes relacionadas | Adicionar e remover grupos de assinantes associados a representantes de partes relacionadas | [Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-grupo-assinantes) | COM0002, COM0003 | ✅ |
| COM0006 | Prévia do Termo Constitutivo | Gerar uma minuta do Termo Constitutivo de uma operação a partir de um template predefinido | [Documentação](/documentation/escrituracao/emissao-de-notas/geracao-minutas/gerar-minuta-contrato) | COM0002 | ✅ |
| COM0007* | Alterar template do Termo Constitutivo | Alterar o template do Termo Constitutivo utilizado por uma operação | [Documentação](/documentation/escrituracao/emissao-de-notas/geracao-minutas/alterar-template-tc) | COM0002 | ✅ |
| COM0008* | Upload de documentos | Realizar o upload de documentos associados a uma operação. A `document_key` retornada pode ser utilizada, por exemplo, no sistema de garantias | [Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/upload-documento) | COM0002 | ✅ |
| COM0009* | Cadastro de garantias | Adicionar garantias associadas a uma operação | [Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/cadastro-garantia) | COM0002, COM0008 | ✅ |
| COM0010* | Cadastro / remoção de partes relacionadas de um contrato ou garantia | Adicionar e remover partes relacionadas a um contrato ou garantia específica da operação | [Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-parte-relacionada-em-documento) | COM0002, COM0003 | ✅ |
| COM0011* | Envio da operação para análise | Mover a operação para "em análise", enviando-a ao processo de validação de compliance | [Documentação](/documentation/escrituracao/emissao-de-notas/envio-para-analise) | COM0002 → COM0009 | ✅ |
| COM0012* | Envio de ata de aprovação assinada | Enviar a ata de aprovação assinada externamente para emissores SA ou COP, em payload base64, analisada e aprovada | [Documentação](/documentation/escrituracao/emissao-de-notas/envio-ata-aprovacao) | COM0002 | ✅ |
| COM0013* | Consulta de operações por filtro | Consultar operações de nota comercial utilizando filtros opcionais | [Documentação](/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-filtros) | COM0002 → COM0009 | ✅ |
| COM0014* | Consulta de operação por chave | Consultar os detalhes completos de uma operação específica pela sua chave única | [Documentação](/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-chave) | COM0002 → COM0009 | ✅ |
| COM0024* | Declarar o beneficiário terceiro na criação | Enviar `third_party_disbursement` no corpo da criação da operação, indicando que o valor liberado será pago a um fornecedor e não à conta de liquidação do emissor. Requer habilitação prévia | [Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/criar-operacao) | COM0002 | ⚙️ 🆕 |
| COM0025* | Alterar o beneficiário terceiro | Substituir a instrução de desembolso a terceiro de uma operação ainda em `in_filling` — trocar entre TED, boleto e Pix ou corrigir os dados do beneficiário | [Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/desembolso-terceiro) | COM0002 | ⚙️ 🆕 |

:::info Desembolso para terceiro — recurso sob habilitação 🆕
O recurso não vem habilitado por padrão; solicite a habilitação à QI Tech antes de integrar. Sem ela
a criação da operação é recusada com `COM000062` e nada é persistido.

Três trilhas, mutuamente exclusivas:

- **TED** — `payment_method: "ted"` com `target_account`.
- **Boleto** — `payment_method: "bank_slip"` com `digitable_line` de 47 dígitos, cujos 10 últimos
  dígitos (em centavos) precisam ser exatamente o `released_amount` da operação.
- **Pix** 🆕 — `payment_method: "pix"` com `pix_key` e `pix_key_type` (`cpf`, `cnpj`, `phone`,
  `email` ou `evp`). A chave viaja **sem formatação** para CPF e CNPJ.

Em TED e boleto o beneficiário é identificado pelos próprios dados de pagamento. Como uma chave
Pix não diz quem recebe, a trilha Pix exige também o objeto **`beneficiary`** 🆕 — a qualificação
completa do terceiro, com os mesmos campos de uma parte relacionada, usada para registrar o
pagamento na ata. Esse objeto é aceito, opcionalmente, também em TED e boleto.

O beneficiário viaja junto da operação e é assinado com ela. O pagamento é executado
automaticamente no desembolso — **não há endpoint de pagamento a ser chamado** (ver §9.2).
:::

### 7.2 Assinatura — caminho automático (emissor com auto-assinatura `enabled`) 🆕

| Código | Etapa | Descrição | Documentação | Pré-requisito | Status |
| --- | --- | --- | --- | --- | --- |
| COM0020* | Aprovação automática | Com a auto-assinatura em `enabled` e as condições operacionais previamente aprovadas, a operação passa de análise para aprovada sem intervenção manual. O integrador observa a transição via webhook | [Documentação](/documentation/escrituracao/emissao-de-notas/aprovacao-automatica) *(pendente de publicação)* | COM0011, ASG0006 | ⚙️ 🆕 |
| COM0021* | Assinatura automática do Termo Constitutivo | A QI Tech assina o Termo Constitutivo em nome do emissor utilizando o certificado privado liberado na CertifiQI. Nenhum link de assinatura é gerado para o emissor | [Documentação](/documentation/escrituracao/emissao-de-notas/assinatura-automatica) *(pendente de publicação)* | COM0020 | ⚙️ 🆕 |
| COM0022* | Webhook — operação assinada | Receber o webhook que confirma que todas as assinaturas da operação foram concluídas | [Documentação](/documentation/escrituracao/webhooks-escrituracao) | CAB0003, COM0021 | 🆕 |
| COM0023* | Consulta de documentos assinados | Consultar os documentos assinados da operação pela sua chave única, incluindo o relatório de evidências de assinatura | [Documentação](/documentation/escrituracao/emissao-de-notas/consulta-link-assinado-qisign) | COM0022 | ✅ |
| COM0026* | Envio do log de aceite do cliente | Anexar à operação, em payload base64, o PDF com as evidências de aceite do cliente final. Envio opcional, aceito apenas em `in_filling` e apenas quando o emissor tem a auto-assinatura em `enabled` | [Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/log-aceite) | COM0002, ASG0006 | ⚙️ 🆕 |

:::info Log de aceite — a evidência do consentimento do cliente 🆕
No caminho automático nenhum link de assinatura é gerado para o cliente final, então o consentimento
dele não fica registrado pelo envelope de assinatura. O log de aceite é onde essa evidência entra: um
PDF com o registro do aceite, anexado à operação enquanto ela está em `in_filling`.

O envio é **opcional** — a emissão não depende dele e nada é bloqueado na sua ausência. O documento é
guardado como evidência: não entra no envelope de assinatura, não entra no pacote de documentos
assinados (COM0023) e não altera a aprovação automática (COM0020). A operação passa a expor
`acceptance_log_document_key` na consulta por chave.

Emissor sem auto-assinatura em `enabled` é recusado com `COM000077`. Um reenvio substitui o documento
vigente; não há endpoint de remoção.
:::

### 7.3 Assinatura — fallback manual (QI SIGN)

Obrigatório para qualquer emissor cujo status de habilitação não seja `enabled` — inclusive um
emissor cuja Fase 2 ainda não tenha sido concluída. **Não há uma "primeira emissão manual"
obrigatória**: se a auto-assinatura já estiver ativa quando a operação for criada, a primeira
emissão já é automática.

| Código | Etapa | Descrição | Documentação | Pré-requisito | Status |
| --- | --- | --- | --- | --- | --- |
| COM0015* | Consulta de links de assinatura QI SIGN | Consultar todos os links de assinatura de uma operação específica via QI SIGN, pela sua chave única | [Documentação](/documentation/escrituracao/emissao-de-notas/consulta-link-assinatura-qisign) | COM0002 → COM0009 | ✅ |
| COM0016* | Consulta de links de contratos assinados | Consultar todos os documentos assinados de uma operação específica via QI SIGN, pela sua chave única | [Documentação](/documentation/escrituracao/emissao-de-notas/consulta-link-assinado-qisign) | COM0002 → COM0009 | ✅ |

---

## 8. Fase 5 — Subscrição e integralização

Com a operação assinada, o boletim de subscrição é gerado automaticamente e disponibilizado para
assinatura do investidor. Quando o investidor também está habilitado para auto-assinatura, esta etapa
também não exige interação humana.

| Código | Etapa | Descrição | Documentação | Pré-requisito | Status |
| --- | --- | --- | --- | --- | --- |
| INT0001* | Consulta de processo de integralização por chave | Consultar os detalhes de um processo de integralização pela sua chave única | [Documentação](/documentation/escrituracao/integralizacao-cotas/consulta-processo-integralizacao) | COM0022 | ✅ |
| INT0002* | Consulta de subscrição | Consultar uma subscrição em andamento | [Documentação](/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/consulta-subscricao-cotas) | INT0001 | ✅ |
| INT0003 | Cadastro de subscrição | Cadastrar a intenção de um investidor de subscrever um número específico de cotas — útil quando a data de subscrição precisa ser deslocada | [Documentação](/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cadastro-subscricao) | INT0001, INT0002 | ✅ |
| INT0004 | Cancelamento de subscrição | Cancelar uma subscrição — útil quando a data de subscrição precisa ser deslocada | [Documentação](/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cancelar-subscricao) | INT0001, INT0002 | ✅ |
| INT0005* | Webhook — boletim de subscrição assinado | Receber o webhook que confirma que o boletim de subscrição foi assinado. Este é o gatilho que o sistema do cliente utiliza para comandar a transferência de recursos da Fase 6.1 (TFI0002) | [Documentação](/documentation/escrituracao/webhooks-escrituracao) | CAB0003, INT0002 | 🆕 |

---

## 9. Fase 6 — Transferência de recursos e pagamento 🆕

A Fase 6 possui duas pernas. A primeira (**6.1**) é disparada pelo próprio sistema do integrador ao
receber o webhook de assinatura do boletim de subscrição, e move os recursos para a conta de
liquidação da WL. A segunda (**6.2**) paga o fornecedor a partir dessa conta.

### 9.1 Perna 1 — Transferência para a conta de liquidação da WL 🆕

**Gatilho.** O webhook de `boletim de subscrição assinado` (**INT0005**) é o evento que autoriza a
transferência de recursos. Ao recebê-lo, o sistema do cliente comanda um pagamento na API de BaaS,
enviando uma transferência para a conta de liquidação da WL. A QI Tech não inicia essa transferência —
é uma ação do lado do integrador, e o webhook é seu único gatilho. Nada nesta perna pode ser disparado
antes da chegada do INT0005: uma transferência comandada contra um boletim não assinado não possui
operação que a lastreie.

Como origem e destino são QI Contas, trata-se de uma **transferência interna** (QI Conta → QI Conta),
que liquida em tempo real e não depende dos trilhos de Pix ou TED.

| Código | Etapa | Descrição | Documentação | Pré-requisito | Status |
| --- | --- | --- | --- | --- | --- |
| TFI0001* | Consultar a conta de liquidação da WL | Consultar a conta de liquidação da WL que receberá os recursos, incluindo seus identificadores e saldo | [Documentação](/documentation/movimentacao_de_contas/consulta_de_transacoes) | CAB0002 | ✅ |
| TFI0002* | Comandar a transferência interna | Ao receber o INT0005, comandar a transferência da QI Conta de origem para a conta de liquidação da WL. A requisição deve carregar a chave única da operação para que o crédito possa ser conciliado de volta à NC | [Documentação](/documentation/baas/ted/realizar_transferencia) | INT0005, TFI0001 | ✅ |
| TFI0003* | Consultar a transferência | Consultar a transferência comandada e confirmar que ela liquidou na conta de liquidação da WL | [Documentação](/documentation/movimentacao_de_contas/consulta_de_transferencias_realizadas) | TFI0002 | ✅ |
| TFI0004* | Webhook — transação liquidada | Receber o webhook de movimentação que confirma o crédito na conta de liquidação da WL. Este é o gatilho da perna 6.2 | [Documentação](/documentation/movimentacao_de_contas/webhook_movimentacoes) | CAB0003, TFI0002 | ✅ |
| TFI0005 | Comprovante de transferência | Solicitar o comprovante da transferência para registro e trilha de auditoria do próprio integrador | [Documentação](/documentation/movimentacao_de_contas/comprovante_de_transferencia) | TFI0002 | ✅ |

:::warning Idempotência
O webhook pode ser entregue mais de uma vez. O integrador deve chavear a transferência pela operação,
de modo que um INT0005 reentregue não comande uma segunda transferência para a mesma NC. A
conciliação entre a chave da operação e a transação creditada é responsabilidade do integrador.
:::

#### TFI0002 — Comandar a transferência interna

ENDPOINT /account/ ACCOUNT_KEY /ted
MÉTODO POST

A `ACCOUNT_KEY` é a QI Conta de origem que será debitada. O `target_account` é a conta de liquidação
da WL — no caminho interno, seu `ispb` é o da própria QI Tech (`32402502`), o que faz a transferência
liquidar conta a conta em vez de sair pelo trilho de TED.

Request Body

```json
{
  "request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
  "target_account": {
    "account_branch": "0001",
    "account_number": "2359934",
    "account_digit": "2",
    "owner_document_number": "09080702000105",
    "owner_name": "Conta de Liquidação WL",
    "ispb": "32402502",
    "account_type": "checking_account"
  },
  "transaction_amount": 150000.00
}
```

:::warning A `request_control_key` é a chave de idempotência
Derive-a de forma determinística a partir da chave da operação de NC, em vez de gerar um UUID novo a
cada tentativa. Um INT0005 reentregue que produza a mesma `request_control_key` é rejeitado como
duplicidade, em vez de pagar a conta de liquidação duas vezes.
:::

Response Body — 201

```json
{
  "request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
  "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "created_at": "2021-10-22T20:30:23.459Z",
  "ted_status": "sent",
  "transaction_amount": 150000.00,
  "fee_amount": 0.0,
  "transaction_key": "46804f32-101e-4702-8fbc-c2dbc4c2caec"
}
```

#### TFI0004 — Webhook de confirmação do crédito

O crédito na conta de liquidação da WL chega como um webhook `account_transaction`, com `data.amount`
positivo e `source_sub_type` = `internal_funds_transfer`. Faça o casamento de `data.transaction_key`
com a `transaction_key` retornada pelo TFI0002 para fechar o ciclo de volta à operação de NC.

WEBHOOK_TYPE account_transaction

Webhook Body

```json
{
    "key": "<ACCOUNT-KEY>",
    "data": {
        "amount": 150000.00,
        "origin": {
            "name": "Conta de Origem",
            "branch": "0001",
            "document": "32402502000135",
            "account_key": "5d068423-6094-49e4-b15b-7740038295a8",
            "account_digit": "5",
            "account_number": "00002"
        },
        "timestamp": "2022-09-02T21:36:33.446120",
        "destination": {
            "name": "Conta de Liquidação WL",
            "branch": "0001",
            "document": "09080702000105",
            "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
            "account_digit": "2",
            "account_number": "2359934"
        },
        "reference_key": "983b4a28-7de6-4e71-97ef-60fb50c7b013",
        "reference_type": "movement_request",
        "account_balance": 150000.00,
        "source_sub_type": "internal_funds_transfer",
        "transaction_key": "46804f32-101e-4702-8fbc-c2dbc4c2caec",
        "source_sub_type_str": "Transferência Interna"
    },
    "datetime": "2022-09-02T21:36:33.446120",
    "webhook_type": "account_transaction"
}
```

:::danger Não mapeie os webhooks de forma restrita
Campos adicionais podem ser incluídos aos payloads dos webhooks da QI Tech a qualquer momento. Faça um
parsing defensivo — uma integração que rejeita campos desconhecidos vai quebrar em uma release futura.
:::

### 9.2 Perna 2 — Pagamento ao fornecedor 🆕

A conta de liquidação do emissor é aberta gratuitamente pela QI Tech no momento da emissão e é
referenciada no pacote de assinatura da NC. Pagar o fornecedor a partir da conta de liquidação do
próprio emissor preserva a relação comercial: o fornecedor vê o pagamento chegando do seu próprio
cliente.

**O pagamento não é uma chamada do integrador.** O beneficiário é declarado na própria operação
(`third_party_disbursement`, ver COM0024/COM0025 no §7.1), assinado junto do Termo Constitutivo, e o
desembolso é executado automaticamente pela QI Tech quando os recursos liquidam. O integrador
acompanha por webhook — não existe endpoint de "iniciar pagamento" a ser chamado nesta trilha.

| Código | Etapa | Descrição | Documentação | Pré-requisito | Status |
| --- | --- | --- | --- | --- | --- |
| PAY0001* | Consultar a conta de liquidação do emissor | Consultar a conta de liquidação aberta para o emissor na emissão, incluindo seus identificadores e saldo | [Documentação](/documentation/baas/contas/consulta-conta) *(a confirmar)* | COM0022 | 🆕 |
| PAY0002* | Confirmar recursos disponíveis | Confirmar que os recursos transferidos na perna 6.1 liquidaram na conta de liquidação | [Documentação](/documentation/movimentacao_de_contas/consulta_de_transacoes) | TFI0004 | ✅ |
| PAY0003* | Desembolso automático ao beneficiário | Com `third_party_disbursement` declarado na operação, a QI Tech paga o fornecedor a partir da conta de liquidação do emissor, por TED, boleto ou Pix, sem ação do integrador | [Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/desembolso-terceiro) | PAY0002, COM0024 | ⚙️ 🆕 |
| PAY0004* | Consultar status do pagamento | Consultar o status do desembolso pela chave da transação na conta de liquidação | [Documentação](/documentation/movimentacao_de_contas/consulta_de_transacoes) | PAY0003 | 🆕 |
| PAY0005* | Webhook — pagamento liquidado | Receber o webhook que confirma que o fornecedor foi pago | [Documentação](/documentation/baas/webhooks) *(a confirmar)* | CAB0003, PAY0003 | 🆕 |

#### Trilhas disponíveis

| Trilha | `payment_method` | Campo | Roteamento |
| --- | --- | --- | --- |
| TED | `ted` | `target_account` | Pelo `financial_institution_ispb` |
| Boleto | `bank_slip` | `digitable_line` (47 dígitos) | Pela própria linha digitável |
| Pix | `pix` | `pix_key` + `pix_key_type` | Pela chave, no arranjo Pix |

Na trilha Pix, o objeto `beneficiary` é obrigatório — a chave sozinha não identifica o recebedor.
**QR code** não é uma trilha suportada e não está previsto.

:::warning Boleto — o valor precisa bater com o valor liberado
O valor do boleto é lido dos **10 últimos dígitos da linha digitável, em centavos**, e precisa ser
igual ao `financial.released_amount` da operação. Qualquer diferença é recusada com `COM000061`.

Como o `released_amount` calculado difere do valor solicitado em `financial` por causa das taxas, o
caminho prático é: criar a operação, ler o `released_amount` da resposta e só então anexar um boleto
daquele valor exato. **Não altere o valor de uma linha digitável real** — isso invalida seus dígitos
verificadores e o boleto deixa de ser pagável.
:::

:::warning Escopo da fase 1
**Uma NC por pagamento.** O boleto tem de cobrir o valor liberado integral: split de pagamento — uma
nota financiando vários pagamentos, ou parte ao fornecedor e parte ao emissor — não é suportado nesta
fase e está previsto para a fase 2. O integrador deve modelar suas requisições de acordo: uma
operação, um beneficiário, valor integral.
:::

---

## 10. Resumo dos webhooks

Como o fluxo elimina todos os pontos de conferência manual, estes são os eventos que o integrador
precisa consumir para acompanhar uma operação de ponta a ponta.

| Evento | Fase | O que ele libera |
| --- | --- | --- |
| Status do emissor alterado | 1 | Portão de aprovação — libera a solicitação da habilitação da Fase 2 |
| Auto-assinatura em `pending_signature` | 2 | Envelope aberto na solicitação — confirma que os links de assinatura estão disponíveis |
| Auto-assinatura em `enabled` | 2 | Todas as emissões seguintes podem ocorrer automaticamente |
| Status da operação alterado | 4 | Visibilidade sobre análise → aprovada |
| Operação assinada | 4 | Geração do boletim de subscrição |
| Boletim de subscrição assinado | 5 | **Gatilho da transferência de recursos para a conta de liquidação da WL (TFI0002)** |
| Movimentação de conta (`internal_funds_transfer`) | 6.1 | Recursos confirmados na conta de liquidação da WL — libera o pagamento ao fornecedor |
| Pagamento liquidado | 6.2 | Fecha o ciclo |

---

## 11. Pontos em aberto a serem fechados antes do go-live

| # | Ponto em aberto | Responsável | Impacto |
| --- | --- | --- | --- |
| 1 | Confirmar as condições operacionais da NC — número de parcelas, formas de pagamento e template de contrato. A auto-assinatura precisa cobrir todos os modos operacionais utilizados pelo cliente; qualquer coisa fora do conjunto previamente aprovado cai no fluxo de assinatura manual | Cliente | Bloqueia a definição do escopo da auto-assinatura |
| 2 | ~~Definir a forma de pagamento ao fornecedor~~ **Resolvido em parte 🆕** — TED e boleto estão implementados e disponíveis mediante habilitação. **Pix por chave** também está implementado e disponível mediante habilitação, exigindo o objeto `beneficiary`; **QR code** não é suportado nem previsto | Cliente | Não bloqueia mais a Fase 6 |
| 3 | ~~Pagamento a terceiros — estimativa de 4 semanas~~ **Resolvido 🆕** — entregue por um caminho diferente do previsto: o beneficiário é declarado na operação e o desembolso é automático, sem endpoint de pagamento. Pendente apenas a publicação da documentação e a habilitação dos clientes | QI Tech | Desbloqueado |
| 4 | Criação do certificado via API — hoje é manual (uma única vez por emissor, executado pela QI Tech); prazo em avaliação. **Não bloqueia o go-live** | QI Tech | Afeta a escalabilidade do onboarding, não as primeiras operações |
| 5 | ~~Publicação dos contratos dos endpoints da Fase 2 (ASG)~~ **Resolvido** — a Fase 2 está documentada em [Auto-assinatura do emissor](/documentation/escrituracao/homologacao-emissor/auto-assinatura/inicio). Pendente apenas o comportamento de aprovação/assinatura automática (COM0020–COM0022) | QI Tech | Bloqueia a homologação da Fase 4 automática |
| 6 | Split de pagamento confirmado como escopo da fase 2 — **confirmado pela implementação 🆕**: o boleto tem de igualar o valor liberado integral, portanto uma operação paga exatamente um beneficiário | Cliente + QI Tech | Define a fronteira da fase 1 |
| 7 | Confirmar qual QI Conta é debitada como **origem** da transferência da perna 6.1, e se a conta de liquidação da WL é a mesma conta referenciada no pacote de assinatura da NC ou uma conta separada | Cliente + QI Tech | Define a `ACCOUNT_KEY` e o `target_account` do TFI0002 |
| 8 | Habilitar o desembolso para terceiro para os clientes que vão utilizá-lo — não vem habilitado por padrão, e sem isso a criação da operação é recusada com `COM000062` 🆕 | QI Tech | Bloqueia o uso do recurso pelo cliente |
| 9 | Publicar a página do objeto `third_party_disbursement` e adicionar `COM000061`, `COM000062` e `COM000063` ao catálogo de erros 🆕 | QI Tech | Bloqueia a homologação da trilha de desembolso a terceiro |
| 10 | Publicar a trilha **Pix por chave** na documentação — o objeto `beneficiary`, os tipos de `pix_key_type` e o código `COM000071` no catálogo de erros 🆕 | QI Tech | Bloqueia a homologação da trilha Pix |

---

## 12. Mapeamento de erros

Os erros originados das APIs de emissor, investidor e nota comercial estão catalogados no
[**Catálogo de Erros**](/documentation/escrituracao/catalogo-erros/catalogo-erros).

A solicitação da habilitação recusa com `ISS0000032` quando o emissor não está aprovado,
`ISS0000033` quando o cliente não está habilitado e `ISS0000029` quando já existe uma habilitação
ativa. A consulta retorna `ISS0000028` quando o emissor não possui habilitação ativa — o que também
acontece depois de um `reproved` ou `canceled`. Os demais erros específicos de
auto-assinatura — tentativa de emissão com a habilitação fora de `enabled`, condição operacional fora
do escopo aprovado ou divergência entre o grupo de assinantes e o titular do certificado — serão
adicionados ao mesmo catálogo quando o comportamento de assinatura automática (COM0020–COM0022) for
publicado.

---

# Roteiro de Integração de escrituração de notas comerciais

URL: /documentation/escrituracao/roteiro-integracao/roteiro-integracao-padrao

O roteiro de homologação descreve todos os recursos e funcionalidades que precisam
ser testados pelo parceiro integrador no ambiente de sandbox da QI Tech (ambiente de testes), 
antes da entrada em ambiente de produção para emissão de notas comerciais.

Este roteiro descreve todos os recursos e funcionalidades envolvidos no produto. 

:::warning Atenção
**Todos os testes devem ser obrigatoriamente realizados no ambiente de Sandbox da QI Tech (ambiente de testes).
As operações realizadas em ambiente de Sandbox são operações financeiras fictícias, servindo apenas para teste de funcionalidade das APIs.**
:::

## Cadastro e Autenticação API Escrituração
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| CAB0001* | Troca de chaves públicas | Realizar a troca de chaves públicas com o time operações de plataforma (suporte-dcm@qitech.com.br) | [Link Documentação](/documentation/escrituracao/introducao/troca_de_chaves) |  |
| CAB0002* | Teste de autenticação de chamadas | Após receber a chave de api com o time de plataformas, finalizar teste de autenticação de chamadas |[Link Documentação](/documentation/escrituracao/introducao/teste-autenticacao/teste_de_autenticacao) <br/><br/> [Link Documentação](/documentation/escrituracao/introducao/teste-autenticacao/endpoints_de_teste) | CAB0001 |
| CAB0003* | Configuração de webhooks | Realizar a configuração da url para envio dos webhooks por parte da QI. | [Link Documentação](/documentation/escrituracao/introducao/autenticacao_webhooks) <br/><br/> [Link Documentação](/documentation/escrituracao/configuracao-webhooks) <br/><br/> [Link Documentação](/documentation/escrituracao/webhooks-escrituracao) | CAB0001 e CAB0002 |

## Homologação do Emissor

:::warning Atenção
**Para o fluxo de homologação do emissor, caso o cliente já tenha realizado a integração com o cadastros de cedentes QI TECH, é possível reutilizar esses cadastros, simplificando a homologação no sistema de escrituração**
:::

### Homologação do emissor para cadastros feitos no sistema de cedentes QI TECH

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| CED1001* | Reaproveitar cadastro cedente | Realizar o reaproveitamento do cadastro de cedente utilizando o CNPJ do mesmo. | [Link Documentação](/documentation/escrituracao/homologacao-emissor/solicitacao-acesso) |  
| CED1002* | Listagem dos emissores cadastrados | Listagem dos cedentes cadastrados, com filtros por CNPJ, nome | [Link Documentação](/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-filtro) |  
| CED1003* | Detalhes do emissor | Visualizar os detalhes de um emissor cadastrado, por issuer_key | [Link Documentação](/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-chave) |  

### Homologação do emissor para cadastros feitos pelo sistema de escrituração

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| CED0001* | Cadastro Básico do emissor | Criar o emissor, informando as informações básicas do cadastro. | [Link Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/cadastro-basico) |
| CED0002* | Envio e remoção de Documentos do Emissor | Envio e remoção de documentos associados a um emissor previamente cadastrado | [Link Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor) <br/><br/> [Link Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor-remocao) | CED0001 |
| CED0003* | Cadastro e remoção de Representantes do Emissor | Envio e remoção de representantes associados a um emissor previamente cadastrado | [Link Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor) <br/><br/> [Link Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor-remocao) | CED0001 | 
| CED0004* | Envio e remoção de Documentos do Representante do Emissor | envio e remoção de documentos associados a um representante de um emissor previamente cadastrado | [Link Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor) <br/><br/> [Link Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor-remocao) | CED0001, CED0003 |
| CED0005* | Cadastro e remoção de Conta Bancária do Emissor | cadastro e remoção de conta bancária associada a um emissor previamente cadastrado | [Link Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor) <br/><br/> [Link Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor-remocao) | CED0001 |
| CED0006* | Cadastro e remoção de Grupos de Assinantes do Emissor | cadastro e remoção de grupos de assinantes associados a um emissor previamente cadastrado | [Link Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor) <br/><br/> [Link Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor-remocao) | CED0001 |
| CED0007* | Cadastro e remoção de Informações de Contato do Emissor | cadastro e remoção de informações de contato associadas a um emissor previamente cadastrado | [Link Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor) <br/><br/> [Link Documentação](/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor-remocao) | CED0001 |
| CED0008* | Envio para Análise do Emissor | Este endpoint permite alterar o status de um emissor para análise, enviando-o para o processo de validação. | [Link Documentação](/documentation/escrituracao/homologacao-emissor/envio-analise/) | CED0001, CED0002, CED0003, CED0004, CED0005, CED0006, CED0007 |
| CED0009* | Alteração de Cadastro do Emissor | alterar emissor para permitir edição | [Link Documentação](/documentation/escrituracao/homologacao-emissor/alteracao-cadastro/) | CED0001, CED0002, CED0003, CED0004, CED0005, CED0006, CED0007 |
| CED0010* | Listagem dos emissores cadastrados | Listagem dos cedentes cadastrados, com filtros por CNPJ, nome | [Link Documentação](/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-filtro) 
| CED0011* | Detalhes do emissor | Visualizar os detalhes de um emissor cadastrado, por issuer_key | [Link Documentação](/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-chave) |  

## Homologação do Investidor

:::warning Atenção
**Para o fluxo de homologação do investidor, caso o cliente tenha fundos fixos, é possível realizar o cadastro desses no setup, simplificando a integração.**
:::

### Homologação do investidor para cadastros feitos no setup

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| INV1001* | Listagem dos investidores cadastrados | Listagem dos fundos cadastrados, com filtros por CNPJ, nome | [Link Documentação](/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-filtro) |  
| INV1002* | Detalhes do investidor | Visualizar os detalhes de um investidor cadastro, por investor_key | [Link Documentação](/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-chave) |  

### Homologação do investidor para cadastros feitos pelo sistema de escrituração

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| INV0001* | Cadastro Básico do investidor | Criar o investidor, informando as informações básicas do cadastro. | [Link Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/cadastro-basico) |
| INV0002* | Envio e remoção de Documentos do investidor | Envio e remoção de documentos associados a um investidor previamente cadastrado | [Link Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor) <br/><br/> [Link Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/documentos-investidor-remocao) | INV0001 |
| INV0003* | Cadastro e remoção de Representantes do investidor | Envio e remoção de representantes associados a um investidor previamente cadastrado | [Link Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor) <br/><br/> [Link Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/representantes-investidor-remocao) | INV0001 | 
| INV0004* | Envio e remoção de Documentos do Representante do investidor | envio e remoção de documentos associados a um representante de um investidor previamente cadastrado | [Link Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor) <br/><br/> [Link Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/documentos-representantes-investidor-remocao) | INV0001, INV0003 |
| INV0005* | Cadastro e remoção de Conta Bancária do investidor | cadastro e remoção de conta bancária associada a um investidor previamente cadastrado | [Link Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor) <br/><br/> [Link Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/conta-bancaria-investidor-remocao) | INV0001 |
| INV0006* | Cadastro e remoção de Grupos de Assinantes do investidor | cadastro e remoção de grupos de assinantes associados a um investidor previamente cadastrado | [Link Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor) <br/><br/> [Link Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/assinantes-investidor-remocao) | INV0001 |
| INV0007* | Cadastro e remoção de Informações de Contato do investidor | cadastro e remoção de informações de contato associadas a um investidor previamente cadastrado | [Link Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor) <br/><br/> [Link Documentação](/documentation/escrituracao/homologacao-investidor/cadastro/informacao-contato-investidor-remocao) | INV0001 |
| INV0008* | Envio para Análise do investidor | Este endpoint permite alterar o status de um investidor para análise, enviando-o para o processo de validação. | [Link Documentação](/documentation/escrituracao/homologacao-investidor/envio-analise/) | INV0001, INV0002, INV0003, INV0004, INV0005, INV0006, INV0007 |
| INV0009* | Alteração de Cadastro do investidor | alterar investidor para permitir edição | [Link Documentação](/documentation/escrituracao/homologacao-investidor/alteracao-cadastro/) | INV0001, INV0002, INV0003, INV0004, INV0005, INV0006, INV0007 |
| INV0010* | Listagem dos investidores cadastrados | Listagem dos fundos cadastrados, com filtros por CNPJ, nome | [Link Documentação](/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-filtro) 
| INV0011* | Detalhes do investidor | Visualizar os detalhes de um investidor cadastrado, por investor_key | [Link Documentação](/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-chave) |  

## Emissão de nota comercial

Após os cadastros de emissores e investidores, é possível realizar a emissão de notas comerciais. Para isso, existem algumas combinações de fluxos de emissão, que serão contempladas abaixo.

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| COM0001* | Simulação de condições financeiras | simular as condições financeiras e o fluxo de pagamentos de uma operação | [Link Documentação](/documentation/escrituracao/emissao-de-notas/simulacao) |
| COM0002* | Cadastro de Operação de Nota Comercial | criar uma nova operação de nota comercial com base nos dados financeiros e de investidores. | [Link Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/criar-operacao) | COM0001 |
| COM0003* | Cadastro e Remoção de Partes Relacionadas | cadastro e a remoção de partes relacionadas a uma operação | [Link Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/cadastrar-parte-relacionada) | COM0002 | 
| COM0004* | Envio e Remoção de Documentos de Representantes de Partes Relacionadas | envio e a remoção de documentos associados a representantes de partes relacionadas a uma operação | [Link Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-documento)| COM0002, COM0003 |
| COM0005* | Envio e Remoção de Grupos de Assinantes de Representantes de Partes Relacionadas | envio e a remoção de grupos de assinantes associados a representantes de partes relacionadas a uma operação | [Link Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-grupo-assinantes) | COM0002, COM0003 |
| COM0006 | Pré-visualizar Termo Constitutivo | geração de uma minuta do Termo Constitutivo para uma operação específica, utilizando um template predefinido. | [Link Documentação](/documentation/escrituracao/emissao-de-notas/geracao-minutas/gerar-minuta-contrato) | COM0002 |
| COM0007* | Alterar Template do Termo Constitutivo | alteração do template do Termo Constitutivo para uma operação específica | [Link Documentação](/documentation/escrituracao/emissao-de-notas/geracao-minutas/alterar-template-tc) | COM0002 |
| COM0008* | Envio de documentos | envio de documentos associados a uma operação. O "document_key" retornado poderá ser utilizado, por exemplo, no sistema de garantias | [Link Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/upload-documento) | COM0002 |
| COM0009* | Envio de Garantia na Operação | adição de garantias associadas a uma operação | [Link Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-garantias/cadastro-garantia) | COM0002, COM0008 |
| COM0010* | Cadastro e Remoção de Partes Relacionadas de um contrato/Garantia | cadastro e a remoção de partes relacionadas de um contrato/garantia específicos da operação | [Link Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-parte-relacionada-em-documento) | COM0002, COM0003 |
| COM0011* | Enviar Operação para Análise | alterar o status de uma operação para "em análise", enviando-a para o processo de validação de compliance pelo escriturador | [Link Documentação](/documentation/escrituracao/emissao-de-notas/envio-para-analise) | COM0002, COM0003, COM0004, COM0005, COM0006, COM0007, COM0008, COM0009 |
| COM0012* | Enviar Atas de Aprovação Assinadas | Este endpoint permite enviar as atas de aprovação de empresas do tipo SA ou COP assinadas de forma externa para o sistema de escrituação, enviando um base64 que será analisado e aprovado pelo escriturador. | [Link Documentação](/documentation/escrituracao/emissao-de-notas/envio-ata-aprovacao) | COM0002 |
| COM0013* | Consulta de Operações por Filtros | consultar operações de nota comercial utilizando filtros opcionais | [Link Documentação](/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-filtros) | COM0002, COM0003, COM0004, COM0005, COM0006, COM0007, COM0008, COM0009 |
| COM0014* | Consulta de Operação por Chave | consultar os detalhes completos de uma operação específica, utilizando sua chave única. | [Link Documentação](/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-chave) | COM0002, COM0003, COM0004, COM0005, COM0006, COM0007, COM0008, COM0009 |

### Caso assinatura seja via QI SIGN

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| COM0015* | Consulta dos Links para assinatura via QI SIGN da Operação | consultar todos os links para assinatura de uma operação específica via QI SIGN, utilizando sua chave única. | [Link Documentação](/documentation/escrituracao/emissao-de-notas/consulta-link-assinatura-qisign) | COM0002, COM0003, COM0004, COM0005, COM0006, COM0007, COM0008, COM0009 |
| COM0016* | Consulta do Link dos contratos assinados via QI SIGN da Operação | consultar todos os documentos assinados de uma operação específica via QI SIGN, utilizando sua chave única | [Link Documentação](/documentation/escrituracao/emissao-de-notas/consulta-link-assinado-qisign) | COM0002, COM0003, COM0004, COM0005, COM0006, COM0007, COM0008, COM0009 |

## Processo de integralização/Subscrição

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| INT0001* | Consulta de Integralização por Chave | consultar os detalhes de um processo de integralização utilizando sua chave única | [Link Documentação](/documentation/escrituracao/integralizacao-cotas/consulta-processo-integralizacao) |
| INT0002* | Consulta de Subscrição | consultar uma subcrição em andamento | [Link Documentação](/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/consulta-subscricao-cotas) | INT0001 |
 | INT0003 | Cadastro de Subscrição | registrar a intenção de um investidor em subscrever uma quantidade específica de cotas de uma integralização (útil caso seja necessário deslocar a data de uma subscrição) | [Link Documentação](/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cadastro-subscricao) | INT0001, INT0002 |
 | INT0004 | Cancelar subscrição | cancelar subscrição (útil caso seja necessário deslocar a data de uma subscrição) | [Link Documentação](/documentation/escrituracao/integralizacao-cotas/subscricao-cotas/cancelar-subscricao) | INT0001, INT0002 |

# Roteiro de Integração de Amortização Extraordinária

Este roteiro descreve, em ordem, os passos que o integrador executa para registrar uma amortização extraordinária na QI Tech — desde a identificação das parcelas-alvo até o 201 da chamada de criação. A criação é fire-and-forget: o integrador apenas **cria** o evento; a liquidação, o cancelamento e a finalização são orquestrados internamente pela QI Tech (account-liquidation-api liquida quando o pagamento entra; a rotina diária de settlement do security-service decide cancelar ou finalizar). A referência completa do endpoint de criação é apresentada na seção de **Endpoints**.

Antes de começar, confirme que o [Conceito](/documentation/escrituracao/amortizacao-extraordinaria/conceito) já está claro, especialmente os cinco valores possíveis de `amortization_type` e o papel do `reference_date`.

:::warning Atenção
**Todos os testes devem ser obrigatoriamente realizados no ambiente de Sandbox da QI Tech. Chamadas de amortização extraordinária movimentam `installment.paid_amount` e consomem Valor Presente — valide o fluxo completo em sandbox antes de habilitar em produção.**
:::

## Pré-requisitos

- **API key configurada** — [Troca de chaves](/documentation/escrituracao/introducao/troca_de_chaves).
- **Security criado e integralizado** — [Emissão de notas](/documentation/escrituracao/emissao-de-notas/inicio) e [Integralização de cotas](/documentation/escrituracao/integralizacao-cotas/inicio).
- **Conceitos do produto** compreendidos — [Conceito](/documentation/escrituracao/amortizacao-extraordinaria/conceito).

## Fluxo passo a passo

O fluxo completo tem quatro etapas. Cada linha da tabela indica quem executa a ação, qual chamada ou evento ocorre e o que merece atenção durante a execução.

| # | Etapa | Responsável | Chamada / Evento | Observação |
|---|-------|-------------|------------------|------------|
| 1 | Identificar parcelas-alvo | Integrador | `GET /security/security/{security_key}` | Obtém `installment_number` e os valores correntes das parcelas, usados para escolher o tipo e o montante da amortização. Não é necessário extrair `installment_key` — a criação trabalha apenas com os números das parcelas. |
| 2 | Criar a amortização extraordinária | Integrador | [`POST /event_conciliation/extraordinary_event`](../amortizacao-extraordinaria/endpoints/criar-amortizacao.md) | Envie `security_key`, `investment_key`, `amortization_type`, `amount`, `reference_date`, `due_date` e, quando aplicável, `installment_list` (array de `installment_number`, inteiros ≥ 1). A resposta 201 traz o `extraordinary_event_conciliation_key` (evento extraordinário de amortização único) e a lista `event_conciliation_list` (evento de conciliação de cada parcela). A partir daqui é fire-and-forget para o integrador. |
| 3 | Confirmar pagamento externo | Integrador / Provedor | Conciliação de recebíveis | Aguarde a confirmação do recebimento dos valores pelo canal combinado. Os eventos de conciliação da parcela permanecem em `pending_conciliation` enquanto o pagamento não chega. Para acompanhar o status de um evento extraordinário pela sua chave, use [`GET /event_conciliation/extraordinary_event/{extraordinary_event_conciliation_key}`](../amortizacao-extraordinaria/endpoints/consultar-amortizacao.md). |
| 4 | Liquidação ou finalização automática | QI Tech | Orquestração interna | Ao detectar a entrada do pagamento, a QI Tech (via account-liquidation-api) liquida cada parcela. Caso o pagamento não chegue, a rotina diária de settlement do security-service finaliza ou cancela o evento. Em ambos os casos não há ação do integrador. |

Ao criar, o evento nasce em `pending_conciliation`. A transição para `paid` ocorre só depois da etapa 4 do fluxo acima.

## Pontos de atenção

:::warning Atenção
- **`reference_date`** é obrigatório e fornecido pelo chamador — deve corresponder à data de quitação do evento extraordinário.
- **Liquidação, finalização e cancelamento são internos** — o integrador apenas cria o evento; a QI Tech orquestra o restante. Não há webhook tenant-facing dedicado para as transições de status do `event_conciliation` extraordinário.
- Para investidores em `internal_legacy_system` (CTVM), a liquidação interna é assíncrona — o estado final (`paid` ou `settlement_failed`) é definido pelo cron de autoconciliate.
:::

## Próximos passos

Para a referência completa do endpoint de criação, consulte [Criar Amortização Extraordinária](../amortizacao-extraordinaria/endpoints/criar-amortizacao.md). Para acompanhar o status dos eventos extraordinários ainda pendentes de conciliação, consulte [Consultar Amortização Extraordinária](../amortizacao-extraordinaria/endpoints/consultar-amortizacao.md). As regras de negócio detalhadas (tolerância, discriminação por `reference_date`, ordem de distribuição por tipo, fluxo interno de liquidação e cancelamento) estão consolidadas em [Regras de Negócio](../amortizacao-extraordinaria/regras-de-negocio.md). Para cenários completos passo-a-passo com JSON bodies reais, veja [Exemplos](../amortizacao-extraordinaria/exemplos.md). Para o cenário em que uma nova operação recompra amortizações extraordinárias em aberto, consulte [Amortização com Recompra](../amortizacao-extraordinaria/recompra-de-operacao.md).

## Mapeamento de erros

Os erros originários das apis de emissores, investidores e nota comercial podem ser encontrados em [**Link Catálogo de Erros**](/documentation/escrituracao/catalogo-erros/catalogo-erros)

---

# Roteiro de Integração de escrituração de notas comerciais

URL: /documentation/escrituracao/roteiro-integracao/roteiro-integracao-padrao-external

O roteiro de homologação descreve todos os recursos e funcionalidades que precisam
ser testados pelo parceiro integrador no ambiente de sandbox da QI Tech (ambiente de testes), 
antes da entrada em ambiente de produção para emissão de notas comerciais.

Este roteiro descreve todos os recursos e funcionalidades envolvidos no produto. 

:::warning Atenção
**Todos os testes devem ser obrigatoriamente realizados no ambiente de Sandbox da QI Tech (ambiente de testes).
As operações realizadas em ambiente de Sandbox são operações financeiras fictícias, servindo apenas para teste de funcionalidade das APIs.**
:::

## Cadastro e Autenticação API Escrituração
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| CAB0001* | Troca de chaves públicas | Realizar a troca de chaves públicas com o time operações de plataforma (suporte-dcm@qitech.com.br) | [Link Documentação](/documentation/escrituracao/introducao/troca_de_chaves) |  |
| CAB0002* | Teste de autenticação de chamadas | Após receber a chave de api com o time de plataformas, finalizar teste de autenticação de chamadas |[Link Documentação](/documentation/escrituracao/introducao/teste-autenticacao/teste_de_autenticacao) <br/><br/> [Link Documentação](/documentation/escrituracao/introducao/teste-autenticacao/endpoints_de_teste) | CAB0001 |
| CAB0003* | Configuração de webhooks | Realizar a configuração da url para envio dos webhooks por parte da QI. | [Link Documentação](/documentation/escrituracao/introducao/autenticacao_webhooks) <br/><br/> [Link Documentação](/documentation/escrituracao/configuracao-webhooks) <br/><br/> [Link Documentação](/documentation/escrituracao/webhooks-escrituracao) | CAB0001 e CAB0002 |

## Homologação do Emissor

:::warning Atenção
**Para o fluxo de homologação do emissor, caso o cliente já tenha realizado a integração com o cadastros de cedentes QI TECH, é possível reutilizar esses cadastros, simplificando a homologação no sistema de escrituração**
:::

### Homologação do emissor para cadastros feitos no sistema de cedentes QI TECH

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| CED1001* | Reaproveitar cadastro cedente | Realizar o reaproveitamento do cadastro de cedente utilizando o CNPJ do mesmo. | [Link Documentação](/documentation/escrituracao/homologacao-emissor/solicitacao-acesso) |  
| CED1002* | Listagem dos emissores cadastrados | Listagem dos cedentes cadastrados, com filtros por CNPJ, nome | [Link Documentação](/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-filtro) |  
| CED1003* | Detalhes do emissor | Visualizar os detalhes de um emissor cadastrado, por issuer_key | [Link Documentação](/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-chave) |  

## Homologação do Investidor

:::warning Atenção
**Para o fluxo de homologação do investidor, caso o cliente tenha fundos fixos, é possível realizar o cadastro desses no setup, simplificando a integração.**
:::

### Homologação do investidor para cadastros feitos no setup

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| INV1001* | Listagem dos investidores cadastrados | Listagem dos fundos cadastrados, com filtros por CNPJ, nome | [Link Documentação](/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-filtro) |  
| INV1002* | Detalhes do investidor | Visualizar os detalhes de um investidor cadastro, por investor_key | [Link Documentação](/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-chave) |  

## Emissão de nota comercial

Após os cadastros de emissores e investidores, é possível realizar a emissão de notas comerciais. Para isso, existem algumas combinações de fluxos de emissão, que serão contempladas abaixo.

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| COM0001 | Simulação de condições financeiras | simular as condições financeiras e o fluxo de pagamentos de uma operação | [Link Documentação](/documentation/escrituracao/emissao-de-notas/simulacao) |
| COM0002* | Cadastro de Operação de Nota Comercial | criar uma nova operação de nota comercial com base nos dados financeiros e de investidores. | [Link Documentação](/documentation/escrituracao/emissao-de-notas/cadastro-operacao/criar-operacao) | COM0001 |
COM0002 | 
| COM003* | Enviar Operação para Análise | alterar o status de uma operação para "em análise", enviando-a para o processo de validação de compliance pelo escriturador | [Link Documentação](/documentation/escrituracao/emissao-de-notas/envio-contratos-assinados) | COM0002 |
| COM004* | Enviar Contratos Assinados | Este endpoint permite enviar os contratos assinados de forma externa para o sistema de escrituação, enviando um base64 que será analisado e aprovado pelo escriturador. | [Link Documentação](/documentation/escrituracao/emissao-de-notas/envio-ata-aprovacao) | COM0002 |
| COM0005 | Consulta de Operações por Filtros | consultar operações de nota comercial utilizando filtros opcionais | [Link Documentação](/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-filtros) | COM0002, COM0003, COM0004 |
| COM0006 | Consulta de Operação por Chave | consultar os detalhes completos de uma operação específica, utilizando sua chave única. | [Link Documentação](/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-chave) | COM0002, COM0003, COM0004 |

## Mapeamento de erros

Os erros originários das apis de emissores, investidores e nota comercial podem ser encontrados em [**Link Catálogo de Erros**](/documentation/escrituracao/catalogo-erros/catalogo-erros)

---

# Roteiro de Integração de escrituração de notas comerciais + Boletos + Sistema de baixas

URL: /documentation/escrituracao/roteiro-integracao/roteiro-integracao-securities-baas-dtvm

O roteiro de homologação descreve todos os recursos e funcionalidades que precisam
ser testados pelo parceiro integrador no ambiente de sandbox da QI Tech (ambiente de testes), 
antes da entrada em ambiente de produção para emissão de notas comerciais, boletos e baixas.

Este roteiro descreve todos os recursos e funcionalidades envolvidos no produto. 

:::warning Atenção
**Todos os testes devem ser obrigatoriamente realizados no ambiente de Sandbox da QI Tech (ambiente de testes).
As operações realizadas em ambiente de Sandbox são operações financeiras fictícias, servindo apenas para teste de funcionalidade das APIs.**
:::

## Cadastro e Autenticação API Escrituração
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| CAB0001* | Troca de chaves públicas | Realizar a troca de chaves públicas com o time operações de plataforma (suporte-dcm@qitech.com.br) | [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/introducao/troca_de_chaves) |  |
| CAB0002* | Teste de autenticação de chamadas | Após receber a chave de api com o time de plataformas, finalizar teste de autenticação de chamadas |[Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/introducao/teste-autenticacao/teste_de_autenticacao) <br/><br/> [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/introducao/teste-autenticacao/endpoints_de_teste) | CAB0001 |
| CAB0003* | Configuração de webhooks | Realizar a configuração da url para envio dos webhooks por parte da QI. | [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/introducao/autenticacao_webhooks) <br/><br/> [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/configuracao-webhooks) <br/><br/> [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/webhooks-escrituracao) | CAB0001 e CAB0002 |

### Homologação do emissor para cadastros feitos pelo sistema de escrituração

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| CED0001* | Cadastro Básico do emissor | Criar o emissor, informando as informações básicas do cadastro. | [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/homologacao-emissor/cadastro/cadastro-basico) |
| CED0002* | Envio e remoção de Documentos do Emissor | Envio e remoção de documentos associados a um emissor previamente cadastrado | [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor) <br/><br/> [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/homologacao-emissor/cadastro/documentos-emissor-remocao) | CED0001 |
| CED0003* | Cadastro e remoção de Representantes do Emissor | Envio e remoção de representantes associados a um emissor previamente cadastrado | [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor) <br/><br/> [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/homologacao-emissor/cadastro/representantes-emissor-remocao) | CED0001 | 
| CED0004* | Envio e remoção de Documentos do Representante do Emissor | envio e remoção de documentos associados a um representante de um emissor previamente cadastrado | [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor) <br/><br/> [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/homologacao-emissor/cadastro/documentos-representantes-emissor-remocao) | CED0001, CED0003 |
| CED0005* | Cadastro e remoção de Conta Bancária do Emissor | cadastro e remoção de conta bancária associada a um emissor previamente cadastrado | [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor) <br/><br/> [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/homologacao-emissor/cadastro/conta-bancaria-emissor-remocao) | CED0001 |
| CED0006* | Cadastro e remoção de Grupos de Assinantes do Emissor | cadastro e remoção de grupos de assinantes associados a um emissor previamente cadastrado | [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor) <br/><br/> [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/homologacao-emissor/cadastro/assinantes-emissor-remocao) | CED0001 |
| CED0007* | Cadastro e remoção de Informações de Contato do Emissor | cadastro e remoção de informações de contato associadas a um emissor previamente cadastrado | [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor) <br/><br/> [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/homologacao-emissor/cadastro/informacao-contato-emissor-remocao) | CED0001 |
| CED0008* | Envio para Análise do Emissor | Este endpoint permite alterar o status de um emissor para análise, enviando-o para o processo de validação. | [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/homologacao-emissor/envio-analise/) | CED0001, CED0002, CED0003, CED0004, CED0005, CED0006, CED0007 |
| CED0009* | Alteração de Cadastro do Emissor | alterar emissor para permitir edição | [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/homologacao-emissor/alteracao-cadastro/) | CED0001, CED0002, CED0003, CED0004, CED0005, CED0006, CED0007 |
| CED0010* | Listagem dos emissores cadastrados | Listagem dos cedentes cadastrados, com filtros por CNPJ, nome | [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-filtro) 
| CED0011* | Detalhes do emissor | Visualizar os detalhes de um emissor cadastrado, por issuer_key | [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/homologacao-emissor/consulta/consulta-emissor-chave) |  

## Homologação do Investidor

:::warning Atenção
**Para o fluxo de homologação do investidor, será realizado o cadastro do investidor pelo time de escrituração no momento de setup e a chave será fornecida ao time.**
:::

### Homologação do investidor para cadastros feitos no setup

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| INV1001* | Listagem dos investidores cadastrados | Listagem dos fundos cadastrados, com filtros por CNPJ, nome | [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-filtro) |  
| INV1002* | Detalhes do investidor | Visualizar os detalhes de um investidor cadastro, por investor_key | [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/homologacao-investidor/consulta/consulta-investidor-chave) |  

## Emissão de nota comercial

Após os cadastros de emissores e investidores, é possível realizar a emissão de notas comerciais. Para isso, existem algumas combinações de fluxos de emissão, que serão contempladas abaixo.

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| COM0001* | Simulação de condições financeiras | simular as condições financeiras e o fluxo de pagamentos de uma operação | [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/emissao-de-notas/simulacao) |
| COM0002* | Cadastro de Operação de Nota Comercial | criar uma nova operação de nota comercial com base nos dados financeiros e de investidores. | [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/emissao-de-notas/cadastro-operacao/criar-operacao) | COM0001 |
| COM0003 | Cadastro e Remoção de Partes Relacionadas | cadastro e a remoção de partes relacionadas a uma operação | [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/cadastrar-parte-relacionada) | COM0002 | 
| COM0004 | Envio e Remoção de Documentos de Representantes de Partes Relacionadas | envio e a remoção de documentos associados a representantes de partes relacionadas a uma operação | [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-documento)| COM0002, COM0003 |
| COM0005 | Envio e Remoção de Grupos de Assinantes de Representantes de Partes Relacionadas | envio e a remoção de grupos de assinantes associados a representantes de partes relacionadas a uma operação | [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/emissao-de-notas/cadastro-operacao/cadastro-parte-relacionada/adicionar-grupo-assinantes) | COM0002, COM0003 |
| COM0006 | Pré-visualizar Termo Constitutivo | geração de uma minuta do Termo Constitutivo para uma operação específica, utilizando um template predefinido. | [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/emissao-de-notas/geracao-minutas/gerar-minuta-contrato) | COM0002 |
| COM0007* | Alterar Template do Termo Constitutivo | alteração do template do Termo Constitutivo para uma operação específica | [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/emissao-de-notas/geracao-minutas/alterar-template-tc) | COM0002 |
| COM0008* | Enviar Operação para Análise | alterar o status de uma operação para "em análise", enviando-a para o processo de validação de compliance pelo escriturador | [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/emissao-de-notas/envio-para-analise) | COM0002, COM0003, COM0004, COM0005, COM0006, COM0007 |
| COM0009* | Enviar Atas de Aprovação Assinadas | Este endpoint permite enviar as atas de aprovação de empresas do tipo SA ou COP assinadas de forma externa para o sistema de escrituação, enviando um base64 que será analisado e aprovado pelo escriturador. | [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/emissao-de-notas/envio-ata-aprovacao) | COM0002 |
| COM0010* | Consulta de Operações por Filtros | consultar operações de nota comercial utilizando filtros opcionais | [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-filtros) | COM0002, COM0003, COM0004, COM0005, COM0006, COM0007, COM0008, COM0009 |
| COM0011* | Consulta de Operação por Chave | consultar os detalhes completos de uma operação específica, utilizando sua chave única. | [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/emissao-de-notas/consulta/consulta-por-chave) | COM0002, COM0003, COM0004, COM0005, COM0006, COM0007, COM0008, COM0009 |

### Caso assinatura seja via QI SIGN

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| COM0012* | Consulta dos Links para assinatura via QI SIGN da Operação | consultar todos os links para assinatura de uma operação específica via QI SIGN, utilizando sua chave única. | [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/emissao-de-notas/consulta-link-assinatura-qisign) | COM0002, COM0003, COM0004, COM0005, COM0006, COM0007, COM0008, COM0009 |
| COM0013* | Consulta do Link dos contratos assinados via QI SIGN da Operação | consultar todos os documentos assinados de uma operação específica via QI SIGN, utilizando sua chave única | [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/emissao-de-notas/consulta-link-assinado-qisign) | COM0002, COM0003, COM0004, COM0005, COM0006, COM0007, COM0008, COM0009 |

## Processo de integralização/Subscrição

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| INT0001* | Consulta de Integralização por Chave | consultar os detalhes de um processo de integralização utilizando sua chave única | [Link Documentação](https://docs.qitech.com.br/documentation/escrituracao/integralizacao-cotas/consulta-processo-integralizacao) |

## Mapeamento de erros

Os erros originários das apis de emissores, investidores e nota comercial podem ser encontrados em [**Link Catálogo de Erros**](https://docs.qitech.com.br/documentation/escrituracao/catalogo-erros/catalogo-erros)

# Emissão de boletos

## Cadastro e Autenticação API BaaS
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| CAB0001* | Cadastro no ambiente de Sandbox | Realizar o cadastro na plataforma da QI Tech no ambiente de Sandbox (sandbox.qitech.app) | cs@qitech.com.br |
| CAB0002* | Validação de token em Sandbox | Realizar a validação do QI Token em Sandbox | [Download Manual de Inclusão do Token](https://docs.qitech.com.br/assets/pdfs/QI%20Tech%20Manual%20Inclus%C3%A3o%20de%20Token.pdf) | CAB0001 |
| CAB0003* | Troca de chaves públicas | Realizar a troca de chaves públicas dentro da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Link Documentação](https://docs.qitech.com.br/documentation/primeiros_passos/troca_de_chaves) | CAB0001 e CAB0002 |
| CAB0004* | Teste de autenticação de chamadas | Finalizar teste de autenticação de chamadas | [Passo a Passo](https://docs.qitech.com.br/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2) <br/><br/> [Link Documentação](https://docs.qitech.com.br/documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste) | CAB0003 |
| CAB0005* | Configuração de webhooks | Realizar a configuração da url para envio dos webhooks por parte da QI, através da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Link Documentação](https://docs.qitech.com.br/documentation/primeiros_passos/configurando_webhooks) | CAB0001 e CAB0002 |

---

## QI Conta

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| QIC0001* | Consulta de dados de uma conta | Consultar dados como saldo, dados do titular, data de abertura, dentre outros | [Link Documentação](https://docs.qitech.com.br/documentation/contas/consultar_contas) | CAB0003  |

---

## Movimentações

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| QIC0008* | Consulta de Extrato | Realizar a consulta do extrato de uma conta | [Link Documentação](https://docs.qitech.com.br/documentation/movimentacao_de_contas/consulta_de_transacoes) |  CAB0003  |
| QIC0009* | Solicitação de comprovante de transferência | Solicitar um comprovante de transferência | [Link Documentação](https://docs.qitech.com.br/documentation/movimentacao_de_contas/consulta_de_transacoes)| CAB0003 |
| QIC0010* | Leitura de webhooks de transação | Recepcionar com sucesso todos os webhooks de transação |  [Link Documentação](https://docs.qitech.com.br/documentation/movimentacao_de_contas/comprovante_de_transferencia) |  CAB0003  |
| QIC0011* | Consulta de lista de instituições financeiras | Consultar lista de instituições financeiras habiliatadas para recebimento de TED e Pix |  [Link Documentação](https://docs.qitech.com.br/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras) |  CAB0003  |

---

## Boletos

### Gestão de Chave Pix
#### Criação e Exclusão de Chave pix
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0001* | Criação de chave Pix | Realizar a criação de chave Pix do tipo cpf, cnpj, aleatória, e-mail e telefone | [Link Documentação](https://docs.qitech.com.br/documentation/pix/criar_chave) | 
| PIX0010* | Listagem de chaves Pix de uma QI Conta | Listar chaves Pix vinculadas a uma QI Conta | [Link Documentação](https://docs.qitech.com.br/documentation/pix/listar_chaves_pix) | PIX0001 |

### Gestão da Carteira
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| CRT0001* | Criação de carteira | Realizar a criação de carteira para configurações específicas de pagamento, baixa, protesto, etc.  | [Link Documentação](https://docs.qitech.com.br/documentation/boletos/carteira/criar_carteira) | 
| CRT0002* | Editar carteira | Realizar a edição das configurações padrão.  | [Link Documentação](https://docs.qitech.com.br/documentation/boletos/carteira/editar_carteira) |  CRT0002  |

### Gestão de Boletos
| Nº      | Etapa | Descrição | Link  | Pré-requisito |
|---|---|---|---|---|
| BOL0001 | Registro de boleto único de cobrança (padrão)    | Realizar o registro de um boleto de cobrança | [Link Documentação](https://docs.qitech.com.br/documentation/boletos/emissao/emissao_boleto_unico_padrao) | CAB0002 ou CAB0003   |
| BOL0002 | Registro de boleto único de cobrança (instantânea) | Realizar o registro de um boleto de cobrança | [Link Documentação](https://docs.qitech.com.br/documentation/boletos/emissao/emissao_boleto_unico_instantanea) | CAB0002 ou CAB0003   |
| BOL0003 | Registro de boleto em lote  | Realizar o registro de boleto de cobrança em lote | [Link Documentação](https://docs.qitech.com.br/documentation/boletos/emissao/emissao_em_lote) | CAB0002 ou CAB0003   |
| BOL0004 | Realizar abatimento no valor de um boleto | Realizar abatimento no valor de um boleto | [Link Documentação](https://docs.qitech.com.br/documentation/boletos/instrucoes/abatimento/criar_abatimento) | BOL0001, BOL0002 ou BOL0003 |
| BOL0005 | Cancelar Abatimento     | Cancelar abatimento em um boleto | [Link Documentação](https://docs.qitech.com.br/documentation/boletos/instrucoes/abatimento/cancelar_abatimento) | BOL0001, BOL0002 ou BOL0003  |
| BOL0006 | Estender vencimento de um boleto               | Enviar extensão de prazo de um boleto | [Link Documentação](https://docs.qitech.com.br/documentation/boletos/instrucoes/extensao)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0007 | Incluir desconto em um boleto               | Incluir desconto em um boleto    | [Link Documentação](https://docs.qitech.com.br/documentation/boletos/instrucoes/desconto)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0008 | Incluir juros em um boleto                   | Incluir juros em um boleto       | [Link Documentação](https://docs.qitech.com.br/documentation/boletos/instrucoes/juros)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0009 | Incluir multa em um boleto                   | Incluir multa em um boleto       | [Link Documentação](https://docs.qitech.com.br/documentation/boletos/instrucoes/multa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0010 | Realizar baixa de um boleto                   | Baixar um boleto                 | [Link Documentação](https://docs.qitech.com.br/documentation/boletos/instrucoes/baixa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0011 | Consultar boletos por chave      | Consultar boletos por chave      | [Link Documentação](https://docs.qitech.com.br/documentation/boletos/consulta/consulta_por_chave) | BOL0001, BOL0002 ou BOL0003   |
| BOL0012 | Listar Boletos          | Listar boletos     | [Link Documentação](https://docs.qitech.com.br/documentation/boletos/consulta/listar_boletos) | BOL0001, BOL0002 ou BOL0003   |
| BOL0013 | Consulta de carteira de cobrança      | Consultar uma carteira de cobrança | [Link Documentação](https://docs.qitech.com.br/documentation/boletos/carteira/listar_carteiras) | BOL0001, BOL0002 ou BOL0003   |
| BOL0014 | Webhooks de Boleto      | Realizar a leitura de webhook para boleto | [Link Documentação](https://docs.qitech.com.br/documentation/boletos/webhooks/boleto) | BOL0001, BOL0002 ou BOL0003   |

### Protestos
| Nº      | Etapa | Descrição | Link  | Pré-requisito |
|---|---|---|---|---|
| BOL0015 | Pedido de protesto    | Realizar o pedido de protesto de um boleto | [Link Documentação](https://docs.qitech.com.br/documentation/boletos/instrucoes/protesto/pedido_de_protesto) | CAB0002 ou CAB0003   |
| BOL0016 | Desistência de pedido de protesto (sustação)    | Desistir do pedido de um pedido de protesto, mantendo o boleto registrado | [Link Documentação](https://docs.qitech.com.br/documentation/boletos/instrucoes/protesto/desistencia_de_protesto) | BOL0015   |
| BOL0017 | Desistência de pedido de protesto, com baixa do boleto    | Desistir do pedido de um pedido de protesto, baixando o boleto | [Link Documentação](https://docs.qitech.com.br/documentation/boletos/instrucoes/protesto/desistencia_de_protesto_e_baixa_do_boleto) | BOL0015  |
| BOL0018 | Remoção de protesto (cancelamento)   | Cancelar um protesto confirmado (aceito pelo cartório) | [Link Documentação](https://docs.qitech.com.br/documentation/boletos/instrucoes/protesto/sustacao_de_protesto) | BOL0015  |
| BOL0019 | Listar protestos   | Listar os protestos da carteira de uma conta | [Link Documentação](https://docs.qitech.com.br/documentation/boletos/instrucoes/protesto/listar_protestos) | BOL0015   |
| BOL0020 | Consultar protesto por chave   | Consultar as informações de protesto de um boleto | [Link Documentação](https://docs.qitech.com.br/documentation/boletos/instrucoes/protesto/consulta_por_chave) | BOL0015  |
| BOL0021 | Consultar instrumento de protesto   | Consultar o instrumento de protesto (documento oficial emitido pelo cartório) | [Link Documentação](https://docs.qitech.com.br/documentation/boletos/instrucoes/protesto/consulta_instrumento_de_protesto) | BOL0015  |

### Conciliação de Boletos
| Nº      | Etapa | Descrição | Link  | Pré-requisito |
|---|---|---|---|---|
| CON0001 | Listar grupos de liquidação  | Realizar a listagem dos grupos de liquidação dos boletos liquidados | [Link Documentação](https://docs.qitech.com.br/documentation/boletos/liquidacao/listar_grupos_de_liquidacao) | BOL0001, BOL0002 ou BOL0003   |
| CON0002 | Listar liquidações | Realizar a listagem dos boletos dos grupos de liquidação | [Link Documentação](https://docs.qitech.com.br/documentation/boletos/liquidacao/listar_liquidacoes) | BOL0001, BOL0002 ou BOL0003   |
| CON0003 | Webhooks de Boleto      | Realizar a leitura de webhook para boleto | [Link Documentação](https://docs.qitech.com.br/documentation/boletos/webhooks/liquidacao) | BOL0001, BOL0002 ou BOL0003   |

## Integração QI DTVM - Baixa parcelas

| Nº      | Etapa | Descrição | Link  | Pré-requisito |
|---|---|---|---|---|
| BAX0001 | Criação do Lote de Pagamento  | Criação do Lote de Pagamento das parcelas | [Link Documentação](https://docs.qitech.com.br/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao) |    |
| BAX0002 | Inserção de liquidações | Realizar a liquidação de parcelas | [Link Documentação](https://docs.qitech.com.br/documentation/iaas/liquidacao_ativos/ativos) | BAX0001   |

---

# Webhooks de Escrituração

URL: /documentation/escrituracao/webhooks-escrituracao

## 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](./introducao/autenticacao_webhooks.md) 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](./introducao/autenticacao_webhooks.md).

## 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:**
```json
{
  "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:**
```json
{
  "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"
  }
}
```

#### Auto-assinatura do Emissor — Mudança de Status

Enviado quando o envelope do termo de adesão é aberto e quando esse envelope é resolvido. O envelope é aberto durante a própria [solicitação da habilitação](/documentation/escrituracao/homologacao-emissor/auto-assinatura/solicitacao-auto-assinatura), que já responde em `pending_signature` — para quem fez a chamada, este webhook confirma o que a resposta trouxe; para os demais consumidores do tenant, é o aviso de que o termo está disponível para assinatura. A habilitação é solicitada pelo integrador em [`POST .../auto_signature`](/documentation/escrituracao/homologacao-emissor/auto-assinatura/solicitacao-auto-assinatura). Consulte o [fluxo da auto-assinatura](/documentation/escrituracao/homologacao-emissor/auto-assinatura/inicio) para o significado de cada status.

O evento é disparado em três momentos: `pending_signature`, `enabled` e `reproved`. A criação da auto-assinatura (`pending_term_generation`) e o cancelamento (`canceled`) **não** geram webhook — a criação é a resposta da própria solicitação, e o cancelamento é observado pela [consulta da auto-assinatura](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-auto-assinatura).

**Event Type:** `issuer_management.auto_signature_status_change`

**Payload:**

```json
{
  "event_type": "issuer_management.auto_signature_status_change",
  "event_datetime": "2026-02-10T09:16:03Z",
  "event_data": {
    "issuer_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43",
    "issuer_auto_signature_key": "9c3f0f1e-6a2b-4c58-9c9c-0f6b1d2a7e34",
    "status": "pending_signature"
  }
}
```

| Campo | Tipo | Descrição |
|---|---|---|
| `issuer_key` | string | Chave única do emissor. |
| `issuer_auto_signature_key` | string | Chave única da auto-assinatura. |
| `status` | string | Status atual. No webhook, sempre `pending_signature`, `enabled` ou `reproved`. |

Como tratar cada status recebido:

| Status recebido | O que fazer |
|---|---|
| `pending_signature` | Consultar os [links de assinatura](/documentation/escrituracao/homologacao-emissor/auto-assinatura/consulta-links-assinatura) e direcionar cada assinante do emissor ao seu próprio link. |
| `enabled` | O emissor está habilitado: as emissões seguintes são assinadas automaticamente. |
| `reproved` | O envelope do termo foi recusado, cancelado ou expirou. As emissões seguem pelo fluxo de assinatura manual até que uma nova habilitação seja criada. |

### Gestão de Contas de Liquidação

#### Abertura de Conta de Liquidação Rejeitada

Enviado quando o BaaS rejeita a abertura da conta de liquidação do emissor — por exemplo, por bloqueio no Bacen Protege+. A conta não é aberta, e a integralização do emissor fica impedida até que uma nova solicitação seja aprovada.

Não há evento correspondente de aprovação: a abertura bem-sucedida é observada pela [consulta da conta de liquidação](./integralizacao-cotas/consulta-conta-liquidacao.md).

**Event Type:** `liquidation_account.account_request_status_change`

**Payload:**

```json
{
  "event_type": "liquidation_account.account_request_status_change",
  "event_datetime": "2025-07-30T16:05:00Z",
  "event_data": {
    "issuer_key": "18c4d162-1b1b-4c3a-b7a7-5f1200723c43",
    "account_request_key": "7e1c53d6-d372-4020-be6b-ed94248d7ae9",
    "status": "rejected",
    "rejection_reason": "Rejeitado devido ao Bacen Protege+",
    "account_info": {
      "account_branch": "0001",
      "account_number": "1234567",
      "account_digit": "3"
    }
  }
}
```

O campo `account_info` é opcional e só é enviado quando o BaaS informa os dados da conta recusada. O `rejection_reason` é repassado como recebido do BaaS.

### 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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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 Reprovada

Enviado quando uma operação é reprovada na análise (pré-análise automática ou análise manual do compliance). A operação não segue para assinatura.

**Event Type:** `commercial_paper.operation_status_change`

**Payload:**
```json
{
  "event_type": "commercial_paper.operation_status_change",
  "event_datetime": "2025-07-30T15:45:00Z",
  "event_data": {
    "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f",
    "status": "compliance_reproved",
    "reproval_reason": {
      "maximum_overdue_by_debtor": "Issuer 12.345.678/0001-90 holds another asset that is more than 0 days overdue."
    }
  }
}
```

O campo `reproval_reason` traz os motivos da reprovação em um objeto de chave e descrição. Na pré-análise automática, cada chave é a regra de elegibilidade que reprovou a operação. O campo pode vir `null` quando a reprovação não registrou nenhum motivo.

#### Operação Enviada para Assinatura

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

**Event Type:** `commercial_paper.operation_status_change`

**Payload:**
```json
{
  "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:**
```json
{
  "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",
    "signed_files_url": "https://storage.googleapis.com/commercial-paper-bucket/89c7f73a-c184-400c-bb2a-dd4424075a4f/signed_files?X-Goog-Algorithm=..."
  }
}
```

O campo `signed_files_url` traz o link para download de um arquivo compactado com todos os contratos assinados da operação, disponível independentemente do método de assinatura utilizado. O link tem validade de 7 dias a partir do envio do webhook.

#### Operação Cancelada

Enviado quando uma operação é cancelada.

**Event Type:** `commercial_paper.operation_status_change`

**Payload:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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"
  }
}
```

#### Subscrição Cancelada

Enviado quando a subscrição é cancelada por reprovação na análise de elegibilidade da integralização. A boleta e o envelope de assinatura são cancelados junto.

**Event Type:** `subscription.subscription_status_change`

**Payload:**
```json
{
  "event_type": "subscription.subscription_status_change",
  "event_datetime": "2025-07-30T16:05:00Z",
  "event_data": {
    "operation_key": "89c7f73a-c184-400c-bb2a-dd4424075a4f",
    "integralization_key": "491e4f5c-a173-4ab8-8ec6-24e7aa228099",
    "subscription_key": "eb791639-2931-41df-b087-731d40f07a7c",
    "status": "canceled",
    "cancellation_reason": "ineligible",
    "ineligible_reasons": {
      "maximum_overdue_by_debtor": "Issuer 12.345.678/0001-90 holds another asset that is more than 0 days overdue."
    }
  }
}
```

O campo `cancellation_reason` identifica o motivo do cancelamento de forma estável. Para `ineligible`, o campo `ineligible_reasons` traz um objeto em que cada chave é a regra de elegibilidade que reprovou a integralização e cada valor é a descrição correspondente.

### 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:**
```json
{
  "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:**
```json
{
  "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

- [Configuração de Webhooks](./introducao/autenticacao_webhooks.md)

---

# Aprovação de Reserva

URL: /documentation/garantia_veicular/aprovacao_reserva

:::caution API em desenvolvimento
A API ainda está em fase de desenvolvimento, sendo assim, este manual está sujeito a alterações.
:::

Quando a configuração do requester define que reservas precisam de aprovação manual (`allow_reservation: false`), toda nova reserva é criada com `is_allowed_to_reserve = false`. Nesse estado, a reserva permanece em `pending_reservation` e **não é processada** pela rotina automática — fica aguardando uma aprovação explícita.

Este endpoint libera a reserva manualmente, alterando `is_allowed_to_reserve` para `true`. A partir daí, o próximo ciclo da rotina automática avança a reserva para `pending_reservation_confirmation` (veja [Mapa de Status](/documentation/garantia_veicular/mapa_de_status)).

:::info O `status` da reserva não muda com a chamada
O `reservation_status` continua `pending_reservation` antes e depois do approve. O que muda é o flag `is_allowed_to_reserve`, que destrava o processamento automático. O avanço para `pending_reservation_confirmation` acontece na próxima execução da rotina.
:::

## Aprovar Reserva

ENDPOINT /debt/ OPERATION-KEY /vehicle_collateral/reservation/approve
MÉTODO POST

O `OPERATION-KEY` é o `operation_key` da operação de crédito. A requisição **não exige body**.

Response Body (200)

```json
{
    "reservation_key": "a1b2c3d4-e5f6-7890-abcd-ef0123456789",
    "external_key": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "reservation_status": "pending_reservation",
    "is_allowed_to_reserve": true,
    "document_number": "12345678901",
    "inclusion_date": "2026-06-15"
}
```

### Campos da Response

| Campo | Tipo | Descrição |
|-------|------|-----------|
| reservation_key | String (UUID) | Identificador interno da reserva |
| external_key | String (UUID) | Identificador da operação (mesmo enviado na URL) |
| reservation_status | String | Status atual da reserva. Permanece `pending_reservation` após o approve (ver [Mapa de Status](/documentation/garantia_veicular/mapa_de_status)) |
| is_allowed_to_reserve | Boolean | `true` após a aprovação — libera o processamento automático |
| document_number | String | CPF/CNPJ do tomador |
| inclusion_date | String (`YYYY-MM-DD`) | Data de criação da reserva |

:::tip Idempotência
Chamar o endpoint quando `is_allowed_to_reserve` já é `true` retorna 200 normalmente, sem alterar o estado. Pode ser usado com segurança em retries.
:::

:::caution Validação de propriedade
A reserva precisa pertencer ao requester autenticado. Caso contrário, a resposta é `404 Not Found`.
:::

---

# Cancelamento

URL: /documentation/garantia_veicular/cancelamento

O cancelamento de uma operação de Crédito Veículo pode ocorrer em três cenários distintos, cada um com um endpoint próprio. Em todos os casos, **a alienação fiduciária / gravame é removida automaticamente do veículo** após a confirmação do cancelamento.

| Cenário | Quando usar | Endpoint |
|---------|-------------|----------|
| Antes do desembolso | Operação criada mas ainda não desembolsada para a concessionária | `PATCH /debt/{DEBT-KEY}/cancel` |
| Devolução pela concessionária | Operação já desembolsada — a concessionária devolve o valor via Pix QR Code | `POST /debt/reversal` |
| Cancelamento permanente | Desistência definitiva da operação (encerramento sem possibilidade de reativação) | `POST /debt/{DEBT-KEY}/cancel_permanently` |

**Antes do desembolso**

Enquanto a operação ainda não foi desembolsada, é possível cancelá-la diretamente pelo endpoint `PATCH /debt/{DEBT-KEY}/cancel`. Como não há valor a ser devolvido (nenhum recurso saiu da QI Tech para a concessionária), o cancelamento é imediato.

ENDPOINT /debt/ DEBT-KEY /cancel
MÉTODO PATCH

A referência completa do endpoint, incluindo o response body, está em [Cancelar dívida antes de desembolsar](/documentation/emissao_de_divida/cancelamento/cancelar_divida_antes_de_desembolsar).

:::info Quando usar
Use este endpoint sempre que a operação ainda **não tenha sido desembolsada** (status anterior ao desembolso à concessionária). Após o desembolso, utilize o fluxo de devolução via `/debt/reversal`.
:::

**Devolução via /debt/reversal**

Após o desembolso, o cancelamento se dá pela devolução do valor à QI Tech via Pix QR Code. **No Crédito Veículo, quem paga o QR Code é a concessionária** (que recebeu o desembolso original), e não o tomador. Confirmado o pagamento, a operação é cancelada e a alienação/gravame é removida do veículo no SNG/Detran. Se a cessão já tiver ocorrido, o valor é estornado para o cessionário.

**Passo a passo**

1. O parceiro chama o endpoint **`POST /debt/reversal`** informando o `contract_number` da operação a ser cancelada.
2. A QI Tech responde com um Pix QR Code de devolução (`copy_paste_pix`, `amount`, `expiration_date`).
3. O parceiro **repassa o QR Code à concessionária** (que recebeu o desembolso original).
4. A concessionária paga o QR Code.
5. Uma vez confirmado o pagamento, a operação é cancelada automaticamente e a **alienação fiduciária / gravame é removida** do veículo no SNG/Detran. Se a cessão já tiver ocorrido, o valor é estornado para o cessionário.

**Request**

```json title='POST /debt/reversal'
{
    "contract_number": "0000049343/TW"
}
```

Campos opcionais: `days_to_expire` (dias corridos) ou `workdays_to_expire` (dias úteis) para customizar a expiração do QR Code (padrão: 14 dias úteis).

**Response**

```json
{
    "amount": "10641.24",
    "copy_paste_pix": "00020126930014br.gov.bcb.pix2571qrcode-...",
    "expiration_date": "2025-05-24",
    "payer_document_number": "98765432000100",
    "payer_name": "CONCESSIONARIA EXEMPLO VEICULOS",
    "reversal_key": "f98a1b7c-5e3c-4e6f-8887-c7fedfa0d5b5",
    "status": "waiting_payment"
}
```

:::info Referências completas
- [Geração do Pix QR Code de devolução (`POST /debt/reversal`)](/documentation/emissao_de_divida/cancelamento/desistencia/cancelamento_de_divida_em_ate_sete_dias_apos_o_desembolso) — referência completa do endpoint, incluindo campos e respostas de erro.
- [Consulta do Pix QR Code de devolução](/documentation/emissao_de_divida/cancelamento/desistencia/consulta_de_pix_qr_code_de_devolucao) — para acompanhar o status do pagamento.
:::

:::tip Pré-requisito
Para utilizar o endpoint é necessário solicitar à QI Tech a liberação e a configuração da conta de estorno do cessionário.
:::

**Cancelamento permanente**

O cancelamento permanente encerra a operação de crédito de forma definitiva, **sem possibilidade de reativação**. Use este endpoint quando a desistência for definitiva e nenhum dos fluxos de retomada (reapresentação de conta, reenvio de documentos, etc.) for aplicável.

ENDPOINT /debt/ debt_key /cancel_permanently
MÉTODO POST

A referência completa do endpoint, incluindo o response body, está em [Cancelar permanentemente](/documentation/emissao_de_divida/cancelamento/cancelar_permanentemente).

:::danger Operação irreversível
Após o `cancel_permanently`, a operação **não pode ser reativada**. Avalie se as alternativas (`/cancel` antes do desembolso, ou `/debt/reversal` após) atendem ao seu caso de uso antes de utilizar este endpoint.
:::

---

# Consultas

URL: /documentation/garantia_veicular/consultas

:::caution API em desenvolvimento
A API ainda está em fase de desenvolvimento, sendo assim, este manual está sujeito a alterações.
:::

## Consultar Dívida

Retorna os dados de uma dívida ou uma lista paginada de dívidas. Os filtros são passados como query parameters.

ENDPOINT /debt
MÉTODO GET

### Query Parameters

| Parâmetro | Tipo | Descrição | Obrig. |
|-----------|------|-----------|--------|
| key | String (UUID) | Identificador único da dívida | NÃO |
| contract_number | String | Número do contrato | NÃO |
| issuer_document_number | String | CPF ou CNPJ do tomador | NÃO |
| status | String | Status da dívida (ex: `opened`, `waiting_signature`, `disbursed`, `canceled`, `settled`) | NÃO |
| page | Integer | Número da página (padrão: 1) | NÃO |
| page_size | Integer | Quantidade de registros por página (padrão: 10, máx: 100) | NÃO |

### Response — Busca por key (registro único)

STATUS 200

Response Body

```json
{
    "data": {
        "key": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "contract_number": "OP-000000000000001",
        "status": "disbursed",
        "borrower": {
            "name": "João da Silva",
            "document_number": "12345678901",
            "person_type": "natural"
        },
        "financial": {
            "interest_type": "pre_price_days",
            "credit_operation_type": "ccb",
            "monthly_interest_rate": 0.018,
            "number_of_installments": 12,
            "issue_amount": 5419.55,
            "disbursement_date": "2025-05-10",
            "first_due_date": "2025-06-15"
        },
        "collaterals": [
            {
                "collateral_type": "vehicle",
                "collateral_key": "f1e2d3c4-b5a6-7890-fedc-ba0987654321",
                "collateral_data": {
                    "vehicle_type": "automobile",
                    "plate": "ABC1D23",
                    "license_state": "SP",
                    "chassi_number": "9BWZZZ37780001234",
                    "renavam": "12345678901"
                }
            }
        ],
        "created_at": "2025-05-10T14:30:00.000000",
        "updated_at": "2025-05-10T16:00:00.000000"
    }
}
```

### Response — Busca paginada (lista)

Response Body

```json
{
    "data": [
        {
            "key": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "contract_number": "OP-000000000000001",
            "status": "disbursed",
            "borrower": {
                "name": "João da Silva",
                "document_number": "12345678901",
                "person_type": "natural"
            },
            "financial": {
                "issue_amount": 5419.55,
                "number_of_installments": 12,
                "disbursement_date": "2025-05-10"
            },
            "created_at": "2025-05-10T14:30:00.000000"
        }
    ],
    "pagination": {
        "current_page": 1,
        "page_size": 10,
        "total_pages": 1,
        "total_items": 1
    }
}
```

---

## Consultar Reserva (Gravame)

Retorna o status atual do registro de gravame no SNG/B3.

ENDPOINT /debt/ DEBT-KEY /vehicle_collateral/reservation
MÉTODO GET

Response Body (200)

```json
{
    "status": "reserved",
    "last_updated_at": "2026-02-13 20:38:07",
    "chassi_number": "9BWZZZ37780001234",
    "license_state": "SP",
    "collateral_number": "12345678"
}
```

### Campos da Response

| Campo | Tipo | Descrição |
|-------|------|-----------|
| status | String | Status atual do gravame (ver [Mapa de Status](/documentation/garantia_veicular/mapa_de_status)). Valores possíveis: `pending_reservation`, `pending_reservation_confirmation`, `reserved`, `pending_requester_action`, `refused` |
| last_updated_at | String | Timestamp da última atualização (`YYYY-MM-DD HH:MM:SS`) |
| chassi_number | String | Número do chassi do veículo |
| license_state | String | UF de licenciamento do veículo (2 chars, caixa alta) |
| collateral_number | String | Número da garantia (até 8 chars; `"0"` se ainda não disponível) |

---

## Consultar Contrato (Registro DETRAN)

Retorna o status atual do registro de contrato no DETRAN/Registradora.

ENDPOINT /debt/ DEBT-KEY /vehicle_collateral/contract
MÉTODO GET

Response Body (200)

```json
{
    "status": "pending_registration_confirmation",
    "last_updated_at": "2026-02-14 10:45:07",
    "chassi_number": "9BWZZZ37780001234",
    "license_state": "SP"
}
```

### Campos da Response

| Campo | Tipo | Descrição |
|-------|------|-----------|
| status | String | Status atual do contrato (ver [Mapa de Status](/documentation/garantia_veicular/mapa_de_status)). Valores possíveis: `pending_registration_confirmation`, `pending_send_contract`, `pending_send_contract_confirmation`, `deleted` |
| last_updated_at | String | Timestamp da última atualização (`YYYY-MM-DD HH:MM:SS`) |
| chassi_number | String | Número do chassi do veículo |
| license_state | String | UF de licenciamento do veículo (2 chars, caixa alta) |

---

## Endpoints Auxiliares

| Endpoint | Método | Descrição |
|----------|--------|-----------|
| `/` | GET | Nome do serviço e PID |
| `/health_check` | GET | `204 No Content` — health check |
| `/vehicle_collateral/fees?state=&vehicle_type=` | GET | Cálculo de tarifas por estado e tipo de veículo |
| `/vehicle_collateral/mock_time` | GET | Datetime atual — disponível apenas em DEV/LOCAL/SANDBOX |

---

# Mapa de Status e Etapas

URL: /documentation/garantia_veicular/mapa_de_status

:::caution API em desenvolvimento
A API ainda está em fase de desenvolvimento, sendo assim, este manual está sujeito a alterações.
:::

## Visão Geral — Ciclo de Vida Completo

O diagrama abaixo apresenta o ciclo de vida completo de uma operação com garantia veicular, desde a criação da dívida até a conclusão do registro de contrato e imagem.

![Ciclo de vida completo de uma operação com garantia veicular](/img/diagrams/garantia-veicular-mapa-de-status-1.svg)

---

## Ciclo de Vida do Colateral (Gravame)

Após a assinatura do contrato, a QI Tech envia automaticamente a solicitação de inclusão de gravame ao SNG/B3.

![Ciclo de vida do colateral (gravame)](/img/diagrams/garantia-veicular-mapa-de-status-2.svg)

| Status | Enumerador | Descrição |
|--------|------------|-----------|
| Reserva Pendente | `pending_reservation` | Dados inseridos na plataforma, aguardando envio ao SNG/B3 |
| Confirmação de Reserva Pendente | `pending_reservation_confirmation` | Dados enviados ao SNG/B3. Aguardando confirmação do registro de gravame |
| Reservado | `reserved` | Gravame registrado com sucesso no SNG/B3. Operação pronta para desembolso e registro de contrato |
| Ação do Requester Pendente | `pending_requester_action` | Erro nos dados enviados ou restrição detectada. Parceiro deve corrigir e reenviar |
| Cancelado | `canceled` | Solicitação cancelada na plataforma |

### Ciclo de Cancelamento (Exclusão do Gravame)

Quando uma operação precisa ser cancelada após o gravame ter sido registrado, o fluxo de exclusão é acionado:

![Ciclo de cancelamento e exclusão do gravame](/img/diagrams/garantia-veicular-mapa-de-status-3.svg)

| Status | Enumerador | Descrição |
|--------|------------|-----------|
| Exclusão Pendente | `pending_deletion` | Cancelamento solicitado, aguardando envio da exclusão ao SNG/B3 |
| Confirmação de Exclusão Pendente | `pending_deletion_confirmation` | Solicitação de exclusão enviada. Aguardando confirmação do SNG/B3 |
| Excluído | `deleted` | Colateral e contrato totalmente cancelados no SNG/B3 e DETRAN |

---

## Ciclo de Vida do Contrato

Após o gravame ser confirmado (`reserved`) e o desembolso realizado, a QI Tech envia automaticamente o registro de contrato ao DETRAN/Registradora.

![Ciclo de vida do contrato](/img/diagrams/garantia-veicular-mapa-de-status-4.svg)

| Status | Enumerador | Descrição |
|--------|------------|-----------|
| Confirmação de Registro Pendente | `pending_registration_confirmation` | Contrato enviado ao DETRAN/Registradora. Aguardando validação e registro |
| Registrado | `registered` | Contrato registrado com sucesso no DETRAN. Próximo passo: envio de imagem |
| Envio de Contrato Pendente | `pending_send_contract` | Contrato registrado, aguardando envio de imagem do contrato |
| Confirmação de Envio de Contrato Pendente | `pending_send_contract_confirmation` | Imagem enviada ao DETRAN/Registradora. Aguardando validação |
| Ação do Requester Pendente | `pending_requester_action` | Balcão DETRAN (DF/TO: devedor deve comparecer fisicamente) ou dados/imagem inválidos |
| Excluído | `deleted` | Contrato cancelado na plataforma |

:::info Status Internos
Os status de validação de imagem (ex: `invalid_image`) são exclusivamente internos e **não** são enviados aos clientes externos via webhook.
:::

---

# Simulação e Emissão

URL: /documentation/garantia_veicular/simulacao_e_emissao

:::caution API em desenvolvimento
A API ainda está em fase de desenvolvimento, sendo assim, este manual está sujeito a alterações.
:::

## Simulação da dívida

Antes de emitir a operação, simule as condições financeiras enviando os dados básicos com o tipo de garantia `vehicle`. As taxas de registro variam por região do Detran, por isso os dados da garantia são necessários para uma simulação financeira precisa.

### Request

ENDPOINT /debt_simulation
MÉTODO POST

Testar no Playground

Request Body

**Valor de desembolso com taxa**

```json
{
    "borrower": {
        "person_type": "natural"
    },
    "financial": {
        "interest_type": "pre_price_days",
        "disbursement_date": "2025-05-10",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "monthly_interest_rate": 0.018,
        "disbursed_amount": 10000.00,
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "number_of_installments": 12,
        "principal_grace_period": 0,
        "due_dates": ["2025-06-15"]
    },
    "collaterals": [
        {
            "collateral_type": "vehicle",
            "collateral_data": {
                "vehicle": {
                    "vehicle_type": "automobile",
                    "license_state": "SP"
                }
            }
        }
    ]
}
```

**Valor de parcela com valor de desembolso**

```json
{
    "borrower": {
        "person_type": "natural"
    },
    "financial": {
        "first_due_date": "2025-06-15",
        "installment_face_value": 500,
        "disbursed_amount": 5000.00,
        "disbursement_date": "2025-05-10",
        "limit_days_to_disburse": 3,
        "number_of_installments": 12,
        "interest_type": "pre_price_days",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0
    },
    "collaterals": [
        {
            "collateral_type": "vehicle",
            "collateral_data": {
                "vehicle": {
                    "vehicle_type": "automobile",
                    "license_state": "SP"
                }
            }
        }
    ]
}
```

:::info
A simulação aceita tanto `installment_face_value` (fixando o valor de parcela, variando o desembolso) quanto `disbursed_amount` (fixando o valor desembolsado, variando a parcela). Ao usar `disbursed_amount`, informe as datas de vencimento no array `due_dates`. O campo `collateral_type` deve ser `"vehicle"`. Para simulação, os campos obrigatórios em `collateral_data` são `vehicle_type` e `license_state` — as taxas variam por região do Detran.
:::

### Response

STATUS 200

Response Body

```json
{
    "type": "debt",
    "key": "<Debt Key>",
    "status": "finished",
    "event_datetime": "2025-05-10 03:18:18",
    "data": {
        "interest_type": "pre_price_days",
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0,
        "operation_type": "structured_operation",
        "prefixed_interest_rate": {
            "interest_base": "calendar_days_365",
            "annual_rate": 0.2387205316,
            "monthly_rate": 0.018,
            "daily_rate": 0.0005866899
        },
        "issue_date": "2025-05-10",
        "number_of_installments": 1,
        "final_disbursement_amount": 10000.00,
        "total_pre_fixed_amount": 195.25,
        "iof_amount": 67.49,
        "cet": 0.082,
        "annual_cet": 1.575,
        "disbursement_date": "2025-05-10",
        "installments": [
            {
                "calendar_days": 31,
                "workdays": 22,
                "business_due_date": "2025-06-10",
                "due_date": "2025-06-10",
                "due_principal": 10641.24,
                "has_interest": true,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 195.25,
                "tax_amount": 27.05,
                "total_amount": 10836.49,
                "principal_amortization_amount": 10641.24,
                "installment_number": 1
            }
        ],
        "external_contract_fees": [],
        "contract_fee_amount": 605.67,
        "external_contract_fee_amount": 0,
        "net_external_contract_fee_amount": 0,
        "contract_fees": [
            {
                "fee_type": "spread",
                "amount_type": "percentage",
                "amount": 0.3,
                "fee_amount": 31.92
            },
            {
                "fee_type": "tac_vehicle_fee",
                "amount_type": "absolute",
                "amount": 573.75,
                "fee_amount": 573.75
            }
        ],
        "issue_amount": 10641.24,
        "disbursed_issue_amount": 10000.00,
        "assignment_amount": 10673.16,
        "disbursement_options": [
            {
                "iof_amount": 67.49,
                "total_pre_fixed_amount": 195.25,
                "cet": 0.082,
                "annual_cet": 1.575,
                "contract_fees": [
                    {
                        "fee_type": "spread",
                        "amount_type": "percentage",
                        "amount": 0.3,
                        "fee_amount": 31.92
                    },
                    {
                        "fee_type": "tac_vehicle_fee",
                        "amount_type": "absolute",
                        "amount": 573.75,
                        "fee_amount": 573.75
                    }
                ],
                "external_contract_fees": [],
                "contract_fee_amount": 605.67,
                "external_contract_fee_amount": 0,
                "net_external_contract_fee_amount": 0,
                "disbursement_date": "2025-05-10",
                "first_due_date": "2025-06-10",
                "installments": [
                    {
                        "calendar_days": 31,
                        "workdays": 22,
                        "business_due_date": "2025-06-10",
                        "due_date": "2025-06-10",
                        "due_principal": 10641.24,
                        "has_interest": true,
                        "post_fixed_amount": 0,
                        "pre_fixed_amount": 195.25,
                        "tax_amount": 27.05,
                        "total_amount": 10836.49,
                        "principal_amortization_amount": 10641.24,
                        "installment_number": 1
                    }
                ],
                "issue_amount": 10641.24,
                "disbursed_issue_amount": 10000.00,
                "assignment_amount": 10673.16,
                "final_disbursement_amount": 10000.00,
                "prefixed_interest_rate": {
                    "interest_base": "calendar_days_365",
                    "annual_rate": 0.2387205316,
                    "monthly_rate": 0.018,
                    "daily_rate": 0.0005866899
                }
            }
        ]
    }
}
```

### Objeto Installments

| Campo | Descrição |
|-------|-----------|
| calendar_days | Dias corridos |
| workdays | Dias úteis |
| business_due_date | Data de vencimento em dia útil |
| due_date | Data de vencimento |
| due_principal | Principal do vencimento |
| has_interest | Indica se o vencimento possui juros |
| pre_fixed_amount | Valor pré-fixado da parcela |
| post_fixed_amount | Valor pós-fixado da parcela |
| tax_amount | Valor de IOF da parcela |
| total_amount | Valor total da parcela |
| principal_amortization_amount | Valor da amortização do principal |
| installment_number | Número da parcela |

### Objeto Prefixed Interest Rate

| Campo | Descrição |
|-------|-----------|
| monthly_rate | Taxa mensal |
| daily_rate | Taxa diária |
| annual_rate | Taxa anual |
| interest_base | Base de cálculo da taxa de juros |

### Objeto Contract Fees

| Campo | Tipo | Descrição |
|-------|------|-----------|
| fee_type | String | Tipo da taxa (ver tabela abaixo) |
| amount_type | String | Tipo de valor: `absolute` (valor fixo) ou `percentage` (percentual sobre o desembolso) |
| amount | Float | Valor da taxa: multiplicador (se `percentage`) ou valor fixo (se `absolute`) |
| fee_amount | Float | Valor monetário final da taxa cobrada |

#### Tipos de fee (fee_type)

| Valor | Descrição |
|-------|-----------|
| `tac_vehicle_fee` | Custos de gravame e registro no DETRAN — variam por estado (UF de licenciamento do veículo). Inclui taxas do SNG/B3 e da Registradora. |
| `spread` | Spread da operação, calculado como percentual sobre o valor desembolsado. |

:::info Contract Fees na Garantia Veicular
O campo `contract_fees` retornado na simulação pode conter uma combinação de `tac_vehicle_fee` e/ou `spread`. O `tac_vehicle_fee` corresponde aos custos de gravame (SNG/B3) e registro de contrato (DETRAN/Registradora), que **variam por estado** conforme o UF de licenciamento informado em `license_state`. O total de todas as taxas é somado em `contract_fee_amount`.
:::

---

## Emissão da operação

Após simular e validar as condições, emita a operação de crédito com garantia veicular. O request body inclui os dados do tomador (pessoa física — comprador do veículo), dados financeiros, garantia veicular e conta para desembolso.

A API de dívida foi desenhada para ser executada em apenas uma requisição, após um prévio envio dos arquivos ([upload de documentos](/documentation/upload_de_documentos/upload_de_documentos)).

:::danger Tomador e Desembolso
O tomador da dívida (`borrower`) é a **pessoa física que está comprando o veículo**. O desembolso (`disbursement_bank_accounts`) é realizado para a **concessionária ou revenda de veículos** — ou seja, os dados bancários informados devem ser da concessionária que está vendendo o veículo.
:::

### Envio de Documentos

Antes de emitir a dívida, envie os documentos do tomador via `POST /upload`. Cada documento retorna um UUID (`document_key`) que deve ser incluído no payload do borrower.

| Documento | Campo no borrower | Descrição | Obrig. |
|-----------|-------------------|-----------|--------|
| Documento de identidade (frente) | `document_identification` | RG, CNH ou outro documento com foto (frente) | SIM |
| Documento de identidade (verso) | `document_identification_back` | Verso do documento de identidade | SIM |
| Comprovante de residência | `proof_of_residence` | Comprovante de endereço atualizado | SIM |

:::info Upload de Documentos
Consulte a documentação completa de upload: [Upload de Documentos](/documentation/upload_de_documentos/upload_de_documentos). Não é necessário enviar documentos do veículo.
:::

### Request

ENDPOINT /debt
MÉTODO POST

Testar no Playground

Request Body

```json
{
    "borrower": {
        "name": "João da Silva",
        "email": "joao.silva@email.com",
        "phone": {
            "number": "999998888",
            "area_code": "11",
            "country_code": "055"
        },
        "is_pep": false,
        "address": {
            "city": "São Paulo",
            "state": "SP",
            "number": "100",
            "street": "Rua Exemplo",
            "complement": "Apto 42",
            "postal_code": "01001000",
            "neighborhood": "Centro"
        },
        "role_type": "issuer",
        "birth_date": "1990-01-15",
        "mother_name": "MARIA DA SILVA",
        "nationality": "Brasileiro",
        "person_type": "natural",
        "marital_status": "single",
        "individual_document_number": "12345678901",
        "document_identification": "<uuid-frente>",
        "document_identification_back": "<uuid-verso>",
        "proof_of_residence": "<uuid-comprovante>"
    },
    "financial": {
        "interest_type": "pre_price_days",
        "first_due_date_delay": 30,
        "start_disbursement_date": "2025-05-10",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "installment_face_value": 500,
        "disbursed_amount": 5000.00,
        "limit_days_to_disburse": 3,
        "number_of_installments": 12
    },
    "collaterals": [
        {
            "percentage": 1,
            "collateral_data": {
                "vehicle": {
                    "plate_state": "SP",
                    "renavam": "12345678901",
                    "vehicle_type": "automobile",
                    "model": "GOL 1.0",
                    "chassis": "9BWZZZ377VT004251",
                    "model_year": 2024,
                    "chassis_type": "normal",
                    "manufacturing_year": 2023,
                    "license_state": "SP",
                    "plate": "ABC1234"
                },
                "seller": {
                    "document_number": "37197645832",
                    "name": "Seller Test"
                },
                "credit_release_postal_code": "17057770"
            },
            "collateral_type": "vehicle"
        }
    ],
    "purchaser_document_number": "32402502000135",
    "document_template_key": "<template-key-da-ccb-auto>",
    "disbursement_bank_accounts": [
        {
            "name": "CONCESSIONARIA EXEMPLO VEICULOS",
            "bank_code": "329",
            "branch_number": "0001",
            "account_number": "62400",
            "account_digit": "6",
            "document_number": "98765432000100",
            "percentage_receivable": 100
        }
    ],
    "additional_data": {
        "vehicle_color": "Prata",
        "vehicle_condition": "used",
        "guarantors": [
            {
                "name": "Maria da Silva",
                "document_number": "12345678901",
                "email": "maria.guarantor@email.com",
                "birth_date": "1980-05-15"
            },
            {
                "name": "João Pereira",
                "document_number": "98765432100",
                "email": "joao.guarantor@email.com",
                "birth_date": "1975-11-02"
            }
        ],
        "proposal": {
            "vehicle_amount": 50000.00,
            "down_payment_amount": 5000.00,
            "associated_services_amount": 2000.00,
            "documentation_amount": 570.00
        },
        "accessories": [
            { "description": "Insulfilm", "amount": 800.00 },
            { "description": "Som automotivo", "amount": 1200.00 }
        ],
        "documentation": [
            { "description": "Transferência DETRAN", "amount": 350.00 },
            { "description": "Emplacamento", "amount": 220.00 }
        ]
    }
}
```

:::info Importante
Não é necessário chamar endpoints separados para registrar gravame ou contrato. Basta enviar os dados do veículo no objeto `collaterals` na criação da dívida e a QI Tech cuida de todo o processo internamente (inclusão de gravame no SNG/B3, registro do contrato no DETRAN/Registradora, envio de imagem).
:::

:::tip reservation_method
Após a criação, a API adiciona automaticamente `reservation_method` ao `collateral_data` (valor: `"creation"` ou `"issuing"` conforme configuração do requester). Este campo não deve ser enviado na requisição.
:::

:::info Valor de desembolso (`disbursed_amount`)
O `POST /debt` aceita `installment_face_value` (valor da parcela), `disbursed_amount` (valor desembolsado) ou ambos no objeto `financial`. Use o(s) campo(s) que correspondem à entrada que você quer fixar — para mais detalhes do comportamento ver a [seção de Simulação](#simulação-da-dívida).
:::

:::info Vencimento da primeira parcela
O exemplo usa `first_due_date_delay` (em dias corridos a partir da data de desembolso) — alternativa ao `first_due_date` (data explícita). Use um ou outro.
:::

### Modalidade da operação (`modality`)

A operação de crédito com garantia veicular exige que o parceiro informe a **modalidade da operação** segundo a classificação do BACEN (Documento 3040 / SCR). A modalidade é enviada no objeto `modality` no root do payload de `POST /debt` e determina o **tipo de gravame** da operação e as **regras de desembolso** aplicadas na criação da dívida.

```json title='modality no root do POST /debt'
{
    "modality": {
        "code": "0203"
    }
}
```

| Campo | Tipo | Descrição | Obrig. |
|-------|------|-----------|--------|
| `modality.code` | String (4 dígitos) | Código da modalidade BACEN (Doc 3040). Ver tabela de modalidades suportadas abaixo. | SIM |
| `modality.enumerator` | String | Enumerador opcional da modalidade. Pode ser omitido ou enviado como `null`. | NÃO |

:::danger `modality` é obrigatória na garantia veicular
Se a modalidade não for enviada (ou o código não for suportado), a emissão é recusada com `COP000539`. Envie sempre um dos códigos da tabela abaixo.
:::

#### Modalidades suportadas

| `modality.code` | Modalidade BACEN | Tipo de operação | Regra de desembolso |
|-----------------|------------------|------------------|---------------------|
| `0401` | Aquisição de veículos | Compra (financiamento do veículo) | Desembolso para a **concessionária/revenda** (documento CNPJ) |
| `0203` | Crédito pessoal sem consignação | Crédito com garantia do veículo (*vehicle equity* / refinanciamento) | Desembolso para o **próprio tomador** |

:::info Tipo de operação derivado da modalidade
A QI Tech identifica o tipo de operação a partir do `modality.code` e salva o tipo de gravame correspondente na reserva. A modalidade `0401` configura uma **compra** (o crédito paga a concessionária); a modalidade `0203` configura uma operação de **crédito com garantia do veículo** (o crédito vai para o próprio tomador). Qualquer outro código é recusado com `COP000539`.
:::

#### Erros de validação da modalidade e do desembolso

Na criação da dívida, a modalidade e a conta de desembolso são validadas em conjunto. Os erros abaixo podem ser retornados:

| Código | HTTP | Mensagem |
|-|-|-|
| <a id="COP000539"></a>`COP000539` | 400 | **Bad Request**<br/>Modalidade de crédito não suportada para garantia de veículo.<br/><small>Unsupported credit modality for vehicle collateral.</small> |
| <a id="COP000540"></a>`COP000540` | 400 | **Bad Request**<br/>Operações de *vehicle equity* exigem que o documento da conta de desembolso seja o mesmo do tomador.<br/><small>Vehicle equity operations require the disbursement account document to match the borrower document.</small> |
| <a id="COP000541"></a>`COP000541` | 400 | **Bad Request**<br/>Operações de compra de veículo exigem que o documento da conta de desembolso seja um CNPJ.<br/><small>Vehicle purchase operations require the disbursement account document to be a CNPJ.</small> |

:::warning Coerência entre modalidade e conta de desembolso
- **Compra (`0401`)**: a conta em `disbursement_bank_accounts` deve ser da concessionária/revenda e o `document_number` precisa ser um **CNPJ** (14 dígitos) — caso contrário a emissão é recusada com `COP000541`.
- **Crédito com garantia do veículo (`0203`)**: o desembolso deve ser feito para o **próprio tomador**. Desembolso para um documento diferente do tomador é recusado com `COP000540`.
:::

### Seguro (`vehicle_credit_insurance`)

O produto Crédito Veículo suporta a contratação de seguro prestamista junto à emissão da dívida. O seguro é informado dentro de `financial.rebates` e o prêmio (**2,75% sobre o valor de emissão**) é calculado automaticamente pela QI Tech — o parceiro apenas sinaliza a contratação com o `fee_type` e a `description` corretos.

```json title='financial.rebates — seguro Auto'
{
    "rebates": [
        {
            "fee_type": "insurance_premium_qi_gross_up",
            "description": "vehicle_credit_insurance"
        }
    ]
}
```

| Campo | Valor | Descrição |
|-------|-------|-----------|
| `fee_type` | `"insurance_premium_qi_gross_up"` | Indica que o prêmio do seguro deve ser embutido (gross-up) no valor da operação pela QI Tech. |
| `description` | `"vehicle_credit_insurance"` | Identifica o produto de seguro do Crédito Veículo. |

:::info Cálculo do prêmio
A alíquota de **2,75% sobre o valor de emissão** é aplicada pela QI Tech no momento da emissão. Não é necessário enviar `amount` nem `amount_type` para este `fee_type` — basta sinalizar a contratação.
:::

### Rebate

É possível informar `rebates` no `POST /debt`, permitindo ao parceiro repassar ao tomador descontos sobre as taxas da operação. O campo é um array de objetos, cada um com:

| Campo | Tipo | Descrição |
|-------|------|----------|
| `fee_type` | String | Tipo da taxa: `"tac"` (Tarifa de Abertura de Crédito), `"insurance_premium"` (prêmio de seguro) ou `"insurance_premium_qi_gross_up"` (prêmio do seguro Auto embutido pela QI Tech — ver [Seguro](#seguro-vehicle_credit_insurance)) |
| `amount` | Float | Valor do desconto |
| `amount_type` | String | Tipo do valor: `"absolute"` (valor fixo) ou `"percentage"` (percentual) |
| `rebate_bank_account` | Object | Conta bancária destinatária do rebate |

```json
{
    "rebates": [
        {
            "amount": 100.00,
            "fee_type": "tac",
            "amount_type": "absolute",
            "rebate_bank_account": {
                "name": "CONCESSIONARIA EXEMPLO VEICULOS",
                "bank_code": "329",
                "account_digit": "1",
                "branch_number": "0001",
                "account_number": "00003",
                "document_number": "32402502000135"
            }
        }
    ]
}
```

### Template da CCB Auto (`document_template_key`)

A CCB do produto Crédito Veículo possui template próprio, com Quadros específicos para dados do veículo, fornecedor, avalista e composição comercial da operação. Para emitir a CCB com esse layout, informe o `document_template_key` da template Auto no root do payload de `POST /debt`.

| Campo | Tipo | Descrição | Obrig. |
|-------|------|-----------|--------|
| `document_template_key` | String | UUID da template HTML da CCB Auto cadastrada no doc-api. A QI Tech fornece a chave durante o onboarding. | SIM |

:::info Como obter a template_key
A `document_template_key` da CCB Auto é gerada via cadastro da template HTML no doc-api da QI Tech. A QI Tech disponibiliza a chave correspondente ao seu produto durante o onboarding em sandbox e produção. Caso precise customizar o layout (logo, dados do correspondente, textos), entre em contato com seu ponto focal.
:::

### Avalistas / fiadores (`guarantors`) — signatários da CCB {#avalistas-guarantors}

Para incluir **avalista(s)** que **assinam** a CCB (respondendo solidariamente pela dívida), envie o array **`guarantors` no root** do payload de `POST /debt` — no mesmo nível de `borrower`, `financial` e `collaterals`.

Cada item de `guarantors` é registrado como uma **parte relacionada** (`related_party`) com papel `guarantor` e vira **signatário** do contrato: assina a CCB junto com o tomador, pela certificadora configurada para o requester (ex.: QI Sign). O tomador principal permanece em `borrower` (papel `issuer`).

:::danger `guarantors` (root) ≠ `additional_data.guarantors`
São campos diferentes e com efeitos diferentes:
- **`guarantors` (root)** → o avalista **assina** a CCB (é signatário e se obriga).
- **`additional_data.guarantors`** → **apenas exibição** no Quadro III-A da CCB (não gera assinatura).

Para um avalista que de fato se obriga, use o **`guarantors` do root**. Se enviar somente em `additional_data`, ele aparece impresso na CCB mas **não assina**.
:::

| Campo | Tipo | Descrição | Obrig. |
|-------|------|-----------|--------|
| `guarantors[].person_type` | String | `"natural"` (PF) ou `"legal"` (PJ) | SIM |
| `guarantors[].name` | String | Nome completo do avalista | SIM |
| `guarantors[].individual_document_number` | String | CPF (11 dígitos, somente números) — para PF | SIM (PF) |
| `guarantors[].birth_date` | String | Data de nascimento (`YYYY-MM-DD`). **Necessária para assinar** — a certificadora usa no enriquecimento/biometria; sem ela o avalista não consegue assinar. | SIM (PF) |
| `guarantors[].is_pep` | Boolean | Pessoa Exposta Politicamente | SIM (PF) |
| `guarantors[].address` | Object | Endereço do avalista (mesmo shape do `borrower.address`) | SIM |
| `guarantors[].email` | String | E-mail — canal de assinatura quando `signature_method = email` | Condicional |
| `guarantors[].phone` | Object | `{area_code, number, country_code}` — canal quando `signature_method = sms`/`whatsapp` (número com 9 dígitos) | Condicional |
| `guarantors[].mother_name` | String | Nome da mãe (usado no enriquecimento da assinatura) | Recomendado |

:::info Canal de assinatura por avalista
Cada avalista assina pelo `signature_method` da operação. Se `email`, o `email` do avalista precisa ser válido; se `sms`/`whatsapp`, o `phone` precisa estar completo (DDD + 9 dígitos). Sem o canal correspondente, a coleta de assinatura daquele avalista falha.
:::

:::tip Cônjuge e procurador
Um avalista PF pode carregar:
- **`spouse`** (objeto de pessoa): em regime de bens que exija anuência, o cônjuge entra automaticamente como **anuente** (`intervening_consentor`) e **também assina**.
- **`attorney_list`** (array): procurador(es) que assinam em nome do avalista (`issuer_attorney`).
:::

```json title='guarantors no root do POST /debt'
{
    "borrower": { "...": "tomador (role_type: issuer)" },
    "guarantors": [
        {
            "person_type": "natural",
            "name": "Maria da Silva",
            "individual_document_number": "12345678901",
            "birth_date": "1980-05-15",
            "is_pep": false,
            "email": "maria.avalista@email.com",
            "phone": { "area_code": "11", "number": "999999999", "country_code": "055" },
            "address": {
                "postal_code": "01310100", "street": "Rua Exemplo", "number": "100",
                "neighborhood": "Centro", "city": "São Paulo", "state": "SP"
            }
        }
    ],
    "financial": { "...": "..." },
    "collaterals": [ { "collateral_type": "vehicle", "...": "..." } ]
}
```

### Campos `additional_data` (metadados da CCB)

O objeto `additional_data` no root do payload de `POST /debt` (ou `POST /signed_debt`) agrupa **metadados que aparecem apenas na CCB** — são exibidos no Quadro III (Avalista), Quadro VI (Dados da Proposta), Quadro IV (Cor/Condição do Veículo) e na seção de detalhamento de acessórios/documentação.

:::danger Os valores em `additional_data` são display-only
**Nenhum campo de `additional_data` afeta o cálculo financeiro da operação** (IOF, Valor Liberado, parcelas, CET). A concessionária continua recebendo exatamente o valor configurado em `disbursement_bank_accounts`, com o IOF e demais encargos calculados a partir do `financial`. O `additional_data` apenas alimenta o template da CCB para exibição.
:::

| Campo | Tipo | Descrição | Obrig. |
|-------|------|-----------|--------|
| `additional_data.vehicle_color` | String | Cor do veículo (ex: "Prata", "Preto", "Vermelho"). Exibida no Quadro IV item 5 da CCB. | NÃO |
| `additional_data.vehicle_condition` | String | Condição do veículo: `"new"` (Novo) ou `"used"` (Usado). Exibida no Quadro IV item 11 (checkbox marcado conforme valor). | NÃO |
| `additional_data.guarantors` | Array | Lista de avalistas **apenas para exibição** no **Quadro III-A** + Cláusula 4 da CCB. **Não gera assinatura** — para o avalista assinar/se obrigar, use o `guarantors` no root (ver [Avalistas / fiadores](#avalistas-guarantors)). Aceita 0 ou N avalistas. | NÃO |
| `additional_data.guarantor` | Object | (Deprecado, retrocompatibilidade) Dados de um único avalista. Use `guarantors` (array) preferencialmente — o template converte automaticamente este objeto em uma lista de tamanho 1. | NÃO |
| `additional_data.proposal` | Object | Dados comerciais da proposta de financiamento (Valor do Veículo, Entrada, Serviços, Documentação). Exibidos no Quadro VI da CCB. | NÃO |
| `additional_data.accessories` | Array | Lista de acessórios do veículo (insulfilm, som, blindagem etc.) — exibidos na seção "Detalhamento de acessórios" do Quadro VI. | NÃO |
| `additional_data.documentation` | Array | Lista de custos de documentação (transferência DETRAN, emplacamento etc.) — exibidos na seção "Detalhamento de documentação" do Quadro VI. | NÃO |

#### Array `additional_data.guarantors` (exibição na CCB)

Este array preenche o **Quadro III-A – AVALISTAS** da CCB (impressão). Cada avalista aparece em uma linha do quadro e a Cláusula 4 das Condições Gerais os referencia. **Não confundir com o `guarantors` do root**: este aqui é só o texto impresso; a assinatura/obrigação do avalista vem do [`guarantors` do root](#avalistas-guarantors).

| Campo | Tipo | Descrição | Obrig. |
|-------|------|-----------|--------|
| `additional_data.guarantors[].name` | String | Nome completo do avalista | SIM (se enviar item) |
| `additional_data.guarantors[].document_number` | String | CPF do avalista (11 dígitos, somente números) | SIM (se enviar item) |
| `additional_data.guarantors[].email` | String | E-mail do avalista | NÃO |
| `additional_data.guarantors[].birth_date` | String | Data de nascimento (YYYY-MM-DD) | NÃO |

```json
{
    "guarantors": [
        {
            "name": "Maria da Silva",
            "document_number": "12345678901",
            "email": "maria.guarantor@email.com",
            "birth_date": "1980-05-15"
        },
        {
            "name": "João Pereira",
            "document_number": "98765432100"
        }
    ]
}
```

:::info Compatibilidade — `guarantor` (objeto único)
Para retrocompatibilidade, o template aceita também `additional_data.guarantor` (objeto único, sem array). Internamente é convertido para uma lista de tamanho 1 e renderizado no Quadro III-A da mesma forma. Recomendamos migrar para `guarantors` (array).
:::

#### Objeto `proposal`

Os valores comerciais da proposta de financiamento aparecem no **Quadro VI – Dados da Proposta** da CCB. Os campos são numéricos (Float, em BRL, com até duas casas decimais) — o template faz a formatação para exibição (ex.: `50000.00` → `"R$ 50.000,00"`).

| Campo | Tipo | Descrição | Obrig. |
|-------|------|-----------|--------|
| `additional_data.proposal.vehicle_amount` | Number (float) | Valor do Veículo em BRL (Quadro VI item 1) | NÃO |
| `additional_data.proposal.down_payment_amount` | Number (float) | Valor da Entrada paga pelo tomador em BRL (Quadro VI item 2) | NÃO |
| `additional_data.proposal.associated_services_amount` | Number (float) | Totalizador de Produtos/Serviços Associados em BRL (Quadro VI item 4) — deve ser igual à soma de `accessories[].amount` | NÃO |
| `additional_data.proposal.documentation_amount` | Number (float) | Totalizador de Documentação em BRL (Quadro VI item 5) — deve ser igual à soma de `documentation[].amount` | NÃO |

:::warning Consistência dos totalizadores
`associated_services_amount` precisa bater com `sum(accessories[].amount)` e `documentation_amount` precisa bater com `sum(documentation[].amount)`. A QI Tech não recalcula esses totalizadores a partir dos arrays — quem envia é o parceiro, e divergência aparece como inconsistência no Quadro VI da CCB.
:::

:::info Valor Financiado é derivado automaticamente
O **Valor Financiado** (Quadro VI item 3) e o **CET Mensal/Anual** (Quadro VI itens 6 e 7) são derivados automaticamente do `issue_amount` e dos dados financeiros da operação — não precisam ser enviados em `additional_data.proposal`.
:::

#### Arrays `accessories` e `documentation`

Listas de itens que serão exibidos na CCB na seção **"Detalhamento de acessórios e documentação"** do Quadro VI, agrupados por categoria. O total de cada categoria também é exibido no campo correspondente da **Tabela de Despesas Acessórias** (itens 16 e 17).

| Campo | Tipo | Descrição | Obrig. |
|-------|------|-----------|--------|
| `additional_data.accessories[].description` | String | Descrição livre do item, exibida na CCB (até 255 caracteres) | SIM (se enviar item) |
| `additional_data.accessories[].amount` | Number | Valor do item em BRL (mínimo 0) | SIM (se enviar item) |
| `additional_data.documentation[].description` | String | Descrição livre do item, exibida na CCB (até 255 caracteres) | SIM (se enviar item) |
| `additional_data.documentation[].amount` | Number | Valor do item em BRL (mínimo 0) | SIM (se enviar item) |

#### Exemplo completo

```json
{
    "additional_data": {
        "vehicle_color": "Prata",
        "vehicle_condition": "used",
        "guarantors": [
            {
                "name": "Maria da Silva",
                "document_number": "12345678901",
                "email": "maria.guarantor@email.com",
                "birth_date": "1980-05-15"
            },
            {
                "name": "João Pereira",
                "document_number": "98765432100",
                "email": "joao.guarantor@email.com",
                "birth_date": "1975-11-02"
            }
        ],
        "proposal": {
            "vehicle_amount": 50000.00,
            "down_payment_amount": 5000.00,
            "associated_services_amount": 2000.00,
            "documentation_amount": 570.00
        },
        "accessories": [
            { "description": "Insulfilm", "amount": 800.00 },
            { "description": "Som automotivo", "amount": 1200.00 }
        ],
        "documentation": [
            { "description": "Transferência DETRAN", "amount": 350.00 },
            { "description": "Emplacamento", "amount": 220.00 }
        ]
    }
}
```

:::info Mapeamento `additional_data` → Quadros da CCB
| Campo `additional_data` | Onde aparece na CCB |
|-------------------------|---------------------|
| `vehicle_color` | Quadro IV item 5 (Cor) |
| `vehicle_condition` | Quadro IV item 11 (Condição: Novo/Usado) |
| `guarantors[].name` / `guarantors[].document_number` / `guarantors[].email` | Quadro III-A (uma linha por avalista) + Cláusula 4 |
| `proposal.vehicle_amount` | Quadro VI item 1 (Valor do Veículo) |
| `proposal.down_payment_amount` | Quadro VI item 2 (Valor da Entrada) |
| `proposal.associated_services_amount` | Quadro VI item 4 (Produtos/Serviços Associados) |
| `proposal.documentation_amount` | Quadro VI item 5 (Documentação) |
| `accessories[]` | Quadro VI seção "Detalhamento de acessórios" + Tabela Despesas Acessórias item 16 |
| `documentation[]` | Quadro VI seção "Detalhamento de documentação" + Tabela Despesas Acessórias item 17 |
:::

### Exemplos de payload de desembolso

O campo `disbursement_bank_accounts` aceita diferentes métodos de pagamento. O desembolso é realizado para a **concessionária/revenda**:

**Pix (chave)**

```json
{
    "disbursement_bank_accounts": [
        {
            "document_number": "98765432000100",
            "name": "CONCESSIONARIA EXEMPLO VEICULOS",
            "pix_key": "2f205c99-3161-4120-badd-854039d12de6",
            "pix_transfer_type": "key",
            "percentage_receivable": 100
        }
    ]
}
```

**Pix (manual)**

```json
{
    "disbursement_bank_accounts": [
        {
            "document_number": "98765432000100",
            "name": "CONCESSIONARIA EXEMPLO VEICULOS",
            "pix_transfer_type": "manual",
            "bank_code": "329",
            "branch_number": "0001",
            "account_number": "62400",
            "account_digit": "6",
            "percentage_receivable": 100
        }
    ]
}
```

**TED**

```json
{
    "disbursement_bank_accounts": [
        {
            "transfer_method": "ted",
            "bank_code": "341",
            "branch_number": "8615",
            "account_number": "22110",
            "account_digit": "2",
            "document_number": "98765432000100",
            "name": "CONCESSIONARIA EXEMPLO VEICULOS",
            "percentage_receivable": 100
        }
    ]
}
```

**QR Code Pix**

```json
{
    "disbursement_bank_accounts": [
        {
            "qr_code_key": "b76e436e-4767-4b16-91e6-9bfc794f2510"
        }
    ]
}
```

**Boleto**

```json
{
    "disbursement_bank_accounts": [
        {
            "digitable_line": "836400000169072200500006763953020230059001020193",
            "amount_receivable": 1607.22
        }
    ]
}
```

### Campos do borrower (Pessoa Física)

| Campo | Tipo | Descrição | Obrig. |
|-------|------|-----------|--------|
| name | String | Nome completo do comprador | SIM |
| email | String | E-mail de contato | SIM |
| phone | Object | Telefone de contato | SIM |
| is_pep | Boolean | Pessoa politicamente exposta | SIM |
| address | Object | Endereço do comprador | SIM |
| role_type | String | Papel do tomador (`issuer`) | SIM |
| birth_date | String | Data de nascimento (YYYY-MM-DD) | SIM |
| mother_name | String | Nome da mãe | SIM |
| nationality | String | Nacionalidade | SIM |
| person_type | String | Sempre `"natural"` | SIM |
| marital_status | String | Estado civil (`single`, `married`, `divorced`, `widowed`) | SIM |
| individual_document_number | String | CPF do comprador (11 dígitos) | SIM |
| document_identification | String | UUID do documento de identidade (frente), enviado via `/upload` | SIM |
| document_identification_back | String | UUID do documento de identidade (verso), enviado via `/upload` | SIM |
| proof_of_residence | String | UUID do comprovante de residência, enviado via `/upload` | SIM |

### Campos do collateral_data

| Campo | Tipo | Descrição | Obrig. |
|-------|------|-----------|--------|
| vehicle | Object | Dados do veículo | SIM |
| seller | Object | Dados do vendedor | SIM |
| credit_release_postal_code | String | CEP para liberação de crédito (8 dígitos) | SIM |

#### Objeto vehicle

| Campo | Tipo | Descrição | Obrig. |
|-------|------|-----------|--------|
| vehicle_type | String | Tipo de veículo (ver [Enumeradores](#vehicle_type)) | SIM |
| plate | String | Placa do veículo | SIM |
| plate_state | String | UF da placa do veículo (2 chars, caixa alta) | SIM |
| license_state | String | UF de licenciamento do veículo (2 chars, caixa alta) | SIM |
| renavam | String | Número do RENAVAM (11 dígitos) | SIM |
| chassis | String | Número do chassi do veículo | SIM |
| chassis_type | String | Tipo de chassi (`normal` ou `remarcado`) | SIM |
| model | String | Modelo do veículo | SIM |
| model_year | Integer | Ano do modelo | SIM |
| manufacturing_year | Integer | Ano de fabricação | SIM |

#### Objeto seller

| Campo | Tipo | Descrição | Obrig. |
|-------|------|-----------|--------|
| name | String | Nome da concessionária/vendedor | SIM |
| document_number | String | CPF (11 dígitos) ou CNPJ (14 dígitos) do vendedor | SIM |

### Campos do additional_data

Metadados exibidos exclusivamente na CCB Auto. Nenhum desses campos altera IOF, Valor Liberado, parcelas ou CET da operação — são display-only no template da CCB.

| Campo | Tipo | Descrição | Obrig. |
|-------|------|-----------|--------|
| vehicle_color | String | Cor do veículo (ex: "Prata", "Preto"). Quadro IV item 5 da CCB. | NÃO |
| vehicle_condition | String | Condição do veículo: `new` (Novo) ou `used` (Usado). Quadro IV item 11 da CCB. | NÃO |
| guarantors | Array | Lista de avalistas (cada um responde solidariamente). **Quadro III-A** + Cláusula 4 da CCB. | NÃO |
| guarantor | Object | (Deprecado, retrocompat) Avalista único. Use `guarantors`. | NÃO |
| proposal | Object | Dados comerciais da proposta (Valor do Veículo, Entrada, Serviços, Documentação). Quadro VI da CCB. | NÃO |
| accessories | Array | Lista de acessórios do veículo (insulfilm, som etc.). Quadro VI seção "Detalhamento de acessórios" + Tabela Despesas Acessórias item 16. | NÃO |
| documentation | Array | Lista de custos de documentação (transferência DETRAN, emplacamento etc.). Quadro VI seção "Detalhamento de documentação" + Tabela Despesas Acessórias item 17. | NÃO |

#### Array guarantors

Cada item da lista representa um avalista, exibido como uma linha do Quadro III-A da CCB.

| Campo | Tipo | Descrição | Obrig. |
|-------|------|-----------|--------|
| name | String | Nome completo do avalista | SIM (se enviar item) |
| document_number | String | CPF do avalista (11 dígitos, somente números) | SIM (se enviar item) |
| email | String | E-mail do avalista | NÃO |
| birth_date | String | Data de nascimento (YYYY-MM-DD) | NÃO |

A chave `guarantor` (objeto único) ainda é aceita por retrocompatibilidade e tratada como uma lista de tamanho 1.

#### Objeto proposal

| Campo | Tipo | Descrição | Obrig. |
|-------|------|-----------|--------|
| vehicle_amount | Number (float) | Valor do Veículo em BRL (Quadro VI item 1) | NÃO |
| down_payment_amount | Number (float) | Valor da Entrada paga pelo tomador em BRL (Quadro VI item 2) | NÃO |
| associated_services_amount | Number (float) | Totalizador de Produtos/Serviços Associados em BRL (Quadro VI item 4) — deve ser igual à soma de `accessories[].amount` | NÃO |
| documentation_amount | Number (float) | Totalizador de Documentação em BRL (Quadro VI item 5) — deve ser igual à soma de `documentation[].amount` | NÃO |

#### Array accessories

| Campo | Tipo | Descrição | Obrig. |
|-------|------|-----------|--------|
| description | String | Descrição livre do item, exibida na CCB (até 255 caracteres) | SIM (se enviar item) |
| amount | Number | Valor do item em BRL (mínimo 0) | SIM (se enviar item) |

#### Array documentation

| Campo | Tipo | Descrição | Obrig. |
|-------|------|-----------|--------|
| description | String | Descrição livre do item, exibida na CCB (até 255 caracteres) | SIM (se enviar item) |
| amount | Number | Valor do item em BRL (mínimo 0) | SIM (se enviar item) |

### Response

STATUS 201

Response Body

```json
{
    "webhook_type": "debt",
    "key": "<Debt Key>",
    "status": "waiting_signature",
    "event_datetime": "2025-05-10 14:30:00",
    "data": {
        "borrower": {
            "name": "João da Silva",
            "document_number": "12345678901",
            "related_party_key": "3571e292-3a83-4011-904d-20ee963022ef"
        },
        "contract": {
            "number": "OP-000000000000001",
            "urls": [
                "https://storage.googleapis.com/doc-api/documents/<uuid>/JOAO_DA_SILVA-CCB-OP000000000000001.pdf"
            ],
            "signature_information": [
                {
                    "signer_name": "João da Silva",
                    "signer_document_number": "12345678901",
                    "signer_role": "issuer",
                    "signer_email": "joao.silva@email.com",
                    "signer_external_key": null,
                    "signature_url": null
                }
            ]
        },
        "collaterals": [
            {
                "absolute_amount": null,
                "collateral_constituted": false,
                "collateral_data": {
                    "vehicle": {
                        "plate_state": "SP",
                        "renavam": "12345678901",
                        "vehicle_type": "automobile",
                        "model": "GOL 1.0",
                        "chassis": "9BWZZZ377VT004251",
                        "model_year": 2024,
                        "chassis_type": "normal",
                        "manufacturing_year": 2023,
                        "license_state": "SP",
                        "plate": "ABC1234"
                    },
                    "seller": {
                        "document_number": "37197645832",
                        "name": "Seller Test"
                    },
                    "credit_release_postal_code": "17057770"
                },
                "collateral_key": "f1e2d3c4-b5a6-7890-fedc-ba0987654321",
                "collateral_type": "vehicle",
                "created_at": "2025-05-10T14:30:00.000000",
                "external_key": null,
                "percentage": 1,
                "updated_at": "2025-05-10T14:30:00.000000"
            }
        ],
        "disbursement_options": [
            {
                "disbursement_date": "2025-05-10",
                "contract_fees": [
                    {
                        "fee_type": "registration_fee",
                        "amount_type": "absolute",
                        "amount": 1.0,
                        "fee_amount": 350.00
                    }
                ],
                "external_contract_fees": [],
                "contract_fee_amount": 350.00,
                "external_contract_fee_amount": 0.0,
                "assignment_amount": 5419.55,
                "issue_amount": 5419.55,
                "cet": "2,3000%",
                "annual_cet": "31,2000%",
                "total_iof": 25.50,
                "total_pre_fixed_amount": 580.45,
                "installments": [
                    {
                        "business_due_date": "2025-06-15",
                        "calendar_days": 36,
                        "due_date": "2025-06-15",
                        "due_principal": 5419.55,
                        "has_interest": true,
                        "installment_number": 1,
                        "pre_fixed_amount": 114.65,
                        "principal_amortization_amount": 385.35,
                        "tax_amount": 1.25,
                        "total_amount": 500,
                        "installment_status": null,
                        "installment_type": null
                    }
                ],
                "first_due_date": "2025-06-15",
                "prefixed_interest_rate": {
                    "monthly_rate": 0.018,
                    "daily_rate": 0.00058669,
                    "annual_rate": 0.23872053,
                    "interest_base": "calendar_days_365"
                }
            }
        ]
    }
}
```

### Enumeradores

#### collateral_type

| Valor | Descrição |
|-------|-----------|
| vehicle | Garantia veicular (gravame) |

#### vehicle_type

| Valor | Descrição |
|-------|-----------|
| automobile | Automóvel |
| moped | Ciclomotor |
| scooter | Scooter |
| motorcycle | Motocicleta |
| tricycle | Triciclo |
| minibus | Micro-ônibus |
| bus | Ônibus |
| trailer | Reboque |
| semi-trailer | Semirreboque |
| suv | SUV |
| truck | Caminhão |
| semi-truck | Caminhão-trator |
| wheel-tractor | Trator de rodas |
| crawler-tractor | Trator de esteira |
| mixed-type-tractor | Trator misto |
| quad-bike | Quadriciclo |
| platform-chassis | Chassi plataforma |
| pickup-truck | Camionete |
| utility-vehicle | Utilitário |
| motorhome | Motorhome |
| attachments | Implementos |

#### chassi_type

| Valor | Descrição |
|-------|-----------|
| remarked | Chassi remarcado |
| normal | Chassi normal (padrão) |

---

## Atualização de Dados do Colateral Veicular

:::caution API em desenvolvimento
Este endpoint está em fase de desenvolvimento, sendo assim, sujeito a alterações.
:::

Permite corrigir os dados do colateral veicular em caso de falha no registro do gravame. Utilize o endpoint abaixo para reenviar os dados corrigidos do veículo:

ENDPOINT /debt/ DEBT-KEY /vehicle_collateral/reservation
MÉTODO PATCH

Request Body

```json
{
    "collateral_data": {
        "vehicle": {
            "chassis": "9BWZZZ377VT004251",
            "chassis_type": "normal",
            "renavam": "12345678901",
            "plate": "ABC1234",
            "plate_state": "SP",
            "license_state": "SP",
            "vehicle_type": "automobile",
            "model": "GOL 1.0",
            "model_year": 2024,
            "manufacturing_year": 2023
        }
    }
}
```

---

## Cancelamento

Os fluxos de cancelamento da operação (antes do desembolso, devolução via `/debt/reversal` ou cancelamento permanente) estão documentados na página dedicada: [Cancelamento](/documentation/garantia_veicular/cancelamento).

## Outras ações disponíveis

Após a emissão da dívida, existem outras funcionalidades disponíveis na API de dívidas que podem ser utilizadas em conjunto com operações de garantia veicular:

| Ação | Descrição | Documentação |
|------|-----------|--------------|
| Autorizar desembolso | Autorizar ou bloquear o desembolso de uma operação | [Autorizar Desembolso](/documentation/emissao_de_divida/autorizar_desembolso) |
| Atualizar dados da parte relacionada | Atualizar informações cadastrais (endereço, telefone, e-mail) das partes relacionadas ao contrato | [Atualizar Parte Relacionada](/documentation/emissao_de_divida/atualizar_dados_da_parte_relacionada) |
| Reenviar documentos | Reenviar documentos das partes relacionadas ao contrato de crédito | [Reenviar Documentos](/documentation/emissao_de_divida/reenviar_documentos_das_partes_relacionadas) |
| Reapresentação de conta bancária | Atualizar dados bancários para desembolso após erro na transferência | [Reapresentação de Conta Bancária](/documentation/emissao_de_divida/reapresentacao_de_conta_bancaria) |
| Cancelar dívida | Cancelar a operação antes do desembolso | [Cancelamento de Dívida](/documentation/emissao_de_divida/cancelamento/cancelar_divida_antes_de_desembolsar) |
| Cancelar permanentemente | Cancelar permanentemente a operação de crédito | [Cancelar Permanentemente](/documentation/emissao_de_divida/cancelamento/cancelar_permanentemente) |
| Devolução pela concessionária | Gerar Pix QR Code para a concessionária devolver o valor desembolsado e liberar a alienação | [`/debt/reversal`](/documentation/emissao_de_divida/cancelamento/desistencia/cancelamento_de_divida_em_ate_sete_dias_apos_o_desembolso) |

---

# Mocks (Sandbox)

URL: /documentation/garantia_veicular/testes_homologacao

:::caution API em desenvolvimento
A API ainda está em fase de desenvolvimento, sendo assim, este manual está sujeito a alterações.
:::

O ambiente de homologação (sandbox) possui um sistema de mocks que simula diferentes cenários de resposta do SNG/B3 durante o registro de gravame. O comportamento é controlado pelo campo `name` do tomador (borrower) na criação da dívida (`POST /debt`).

:::tip Fluxo Padrão (Sucesso)
Qualquer `name` que **não esteja** na lista de cenários abaixo seguirá o fluxo padrão de sucesso: o gravame será registrado (`reserved`), seguido pela criação automática do contrato (`pending_registration_confirmation`) e prosseguimento até o desembolso. Dois webhooks são enviados em sequência: `reservation.status_change` (status `reserved`) e `contract.status_change` (status `pending_registration_confirmation`). Para detalhes sobre a estrutura dos webhooks, consulte a página de [Webhooks](/documentation/garantia_veicular/webhooks).
:::

---

## Cenários Disponíveis

### Erro de Validação de Campos (HTTP 400)

Ao utilizar o nome `bob`, a criação do gravame é rejeitada com erros de validação de campos no payload.

| Nome | Etapa | Status Resultante | Webhook |
| :---: | --- | :---: | :---: |
| `bob` | Criação do gravame | `pending_requester_action` | Sim |

**Exemplo de webhook completo**

```json
{
  "event_key": "a23bc45d-67ef-8901-abcd-234567890abc",
  "event_type": "laas.vehicle_collateral.reservation.status_change",
  "origin": "vehicle_collateral",
  "origin_key": "<reservation_key>",
  "person_key": "<requester_key>",
  "receiver_contact": null,
  "data": {
    "callback": {
      "webhook_type": "laas.vehicle_collateral.reservation.status_change",
      "status": "pending_requester_action",
      "event_datetime": "2026-04-08T15:30:00.000Z",
      "data": {
        "contract_number": "CTR-2026-001",
        "rejection_details": [
          {
            "campo": "logradouroDevedor",
            "mensagem": "caracter inválido / acima do tamanho permitido / tipo inválido / Ausência do campo"
          },
          {
            "campo": "numTelDevedor",
            "mensagem": "caracter inválido / acima do tamanho permitido"
          }
        ]
      }
    }
  }
}
```

---

### Erros de Negócio na Confirmação do Gravame

Os cenários abaixo são acionados na etapa de confirmação de status. Todos resultam em `pending_requester_action` e enviam webhook com `error_code`.

| Nome | Erro | `error_code` |
| :---: | --- | --- |
| `carol` | Veículo com restrição financeira já cadastrada | `vehicle_has_financial_restriction_already_registered` |
| `dave` | Chassi não localizado na BIN | `chassis_not_found_in_bin` |
| `frank` | Placa na BIN, informe a placa do veículo | `plate_in_bin_inform_plate_of_vehicle` |
| `george` | Placa divergente da base BIN | `plate_informed_different_from_plate_informed_by_uf_of_registration_in_bin_base` |
| `ian` | Número do imóvel não corresponde ao CEP | `property_number_does_not_correspond_to_informed_postal_code` |
| `jack` | RENAVAM divergente | `renavam_informed_different_from_renavam_informed_by_uf_of_registration_in_bin_base` |
| `kate` | UF do imóvel inválida | `property_uf_invalid` |
| `mary` | Endereço com preenchimento inválido | `financied_address_with_invalid_fill` |
| `olive` | Ano modelo divergente da BIN | `model_year_informed_different_from_model_year_in_bin` |
| `quinn` | Protocolo em aberto na UF de licenciamento | `protocol_open_in_uf_of_registration` |
| `sara` | Nome e endereço do financiado inválidos | `financied_name_and_address_with_invalid_fill` |
| `taylor` | Nome do financiado inválido | `financied_name_with_invalid_fill` |
| `vincent` | Veículo já alienado na base estadual | `vehicle_already_reserved_in_state_base` |

**Exemplo de webhook completo (cenário carol )**

```json
{
  "event_key": "<uuid>",
  "event_type": "laas.vehicle_collateral.reservation.status_change",
  "origin": "vehicle_collateral",
  "origin_key": "<reservation_key>",
  "person_key": "<requester_key>",
  "receiver_contact": null,
  "data": {
    "callback": {
      "webhook_type": "laas.vehicle_collateral.reservation.status_change",
      "key": "<reservation_key>",
      "status": "pending_requester_action",
      "event_datetime": "2026-04-08T15:30:00.000Z",
      "data": {
        "contract_number": "CTR-2026-001",
        "error_code": "vehicle_has_financial_restriction_already_registered",
        "error_reason_en": "Vehicle has financial restriction already registered",
        "error_reason_pt": "Veículo com restrição financeira já cadastrada"
      }
    }
  }
}
```

---

### Recusa Definitiva (sem webhook)

Nestes casos, a reserva é recusada definitivamente. **Nenhum webhook é enviado ao cliente.**

| Nome | Erro | Status Resultante |
| :---: | --- | :---: |
| `eve` | Restrição na BIN fabril | `refused` |
| `robert` | Veículo com restrição | `refused` |

---

### Reprocessamento Automático (sem webhook)

Nestes casos, a mensagem é devolvida para reprocessamento automático. **Nenhum webhook é enviado ao cliente.**

| Nome | Erro | Comportamento |
| :---: | --- | --- |
| `gabriel` | Erro desconhecido | Reprocessamento automático |
| `henry` | Proprietário divergente na comunicação de venda | Reprocessamento automático |
| `linda` | Restrição na UF de licenciamento | Reprocessamento automático |
| `nancy` | Nome do endereço acima de 30 caracteres | Reprocessamento automático |
| `paul` | Telefone acima de 9 caracteres | Reprocessamento automático |
| `william` | Erro desconhecido | Reprocessamento automático |

---

## Tabela Resumo

| Nome | Etapa | Status Resultante | Webhook | Tipo |
| :---: | --- | :---: | :---: | --- |
| `bob` | Criação (HTTP 400) | `pending_requester_action` | Sim | `reservation.status_change` com `rejection_details` |
| `carol` | Confirmação | `pending_requester_action` | Sim | `reservation.status_change` com `error_code` |
| `dave` | Confirmação | `pending_requester_action` | Sim | `reservation.status_change` com `error_code` |
| `eve` | Confirmação | `refused` | Não | — |
| `frank` | Confirmação | `pending_requester_action` | Sim | `reservation.status_change` com `error_code` |
| `george` | Confirmação | `pending_requester_action` | Sim | `reservation.status_change` com `error_code` |
| `gabriel` | Confirmação | Reprocessamento | Não | — |
| `henry` | Confirmação | Reprocessamento | Não | — |
| `ian` | Confirmação | `pending_requester_action` | Sim | `reservation.status_change` com `error_code` |
| `jack` | Confirmação | `pending_requester_action` | Sim | `reservation.status_change` com `error_code` |
| `kate` | Confirmação | `pending_requester_action` | Sim | `reservation.status_change` com `error_code` |
| `linda` | Confirmação | Reprocessamento | Não | — |
| `mary` | Confirmação | `pending_requester_action` | Sim | `reservation.status_change` com `error_code` |
| `nancy` | Confirmação | Reprocessamento | Não | — |
| `olive` | Confirmação | `pending_requester_action` | Sim | `reservation.status_change` com `error_code` |
| `paul` | Confirmação | Reprocessamento | Não | — |
| `quinn` | Confirmação | `pending_requester_action` | Sim | `reservation.status_change` com `error_code` |
| `robert` | Confirmação | `refused` | Não | — |
| `sara` | Confirmação | `pending_requester_action` | Sim | `reservation.status_change` com `error_code` |
| `taylor` | Confirmação | `pending_requester_action` | Sim | `reservation.status_change` com `error_code` |
| `vincent` | Confirmação | `pending_requester_action` | Sim | `reservation.status_change` com `error_code` |
| `william` | Confirmação | Reprocessamento | Não | — |
| *(outro)* | — | `reserved` + `pending_registration_confirmation` | Sim (2x) | `reservation.status_change` + `contract.status_change` |

:::warning Atenção
Os mocks acima simulam apenas a etapa de **registro de gravame** (reserva). O fluxo de registro de contrato e envio de imagem não possui mocks dedicados no ambiente de homologação.
:::

---

# Webhooks — Garantia Veicular

URL: /documentation/garantia_veicular/webhooks

:::caution API em desenvolvimento
A API ainda está em fase de desenvolvimento, sendo assim, este manual está sujeito a alterações.
:::

Notificações assíncronas enviadas via POST pela QI Tech para reportar mudanças de status no ciclo de vida do colateral (gravame), contrato e dívida. A requisição deve ser respondida em até **5 segundos** com HTTP 200.

:::info Webhooks de Dívida
Esta seção cobre tanto os webhooks de **garantia veicular** quanto os webhooks padrão de **dívida**. Para a documentação completa de todos os webhooks relacionados a dívidas, consulte: [Webhooks de Dívida](/documentation/webhooks/dividas).
:::

---

## Webhooks de Garantia Veicular — Reserva (SNG/B3)

WEBHOOK TYPE
laas.vehicle_collateral.reservation.status_change

Notificações relacionadas ao registro de **gravame** no SNG/B3.

### Estrutura Base do Webhook

```json
{
    "key": "<UUID v4 — identificador único do webhook>",
    "reservation_key": "<UUID — identificador único da reserva>",
    "credit_operation_key": "<UUID — identificador da operação de crédito>",
    "status": "<enumerador de status>",
    "webhook_type": "laas.vehicle_collateral.reservation.status_change",
    "event_datetime": "<timestamp ISO 8601>",
    "data": {
        "contract_number": "<número do contrato>",
        "...": "<campos específicos do status>"
    }
}
```

#### Campos Base

| Campo | Tipo | Descrição |
|-------|------|-----------|
| key | String | Identificador único do webhook (UUID v4) |
| reservation_key | String | Identificador único da reserva (UUID) |
| credit_operation_key | String | Identificador da operação de crédito (UUID) |
| status | String | Enumerador de status (ver [Mapa de Status](/documentation/garantia_veicular/mapa_de_status)) |
| webhook_type | String | Sempre `laas.vehicle_collateral.reservation.status_change` |
| event_datetime | String | Timestamp do evento (ISO 8601) |
| data | Object | Payload específico do status (ver exemplos abaixo) |

---

### `pending_reservation_confirmation`

Colateral em processamento. Dados foram enviados para SNG/B3 e o sistema aguarda confirmação.

**Payload**

```json
{
    "key": "1f975b68-7895-4c72-9d79-e73c7b0986b0",
    "reservation_key": "e73c7b68-4c72-9d79-7895-1f975b0986b0",
    "credit_operation_key": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "pending_reservation_confirmation",
    "webhook_type": "laas.vehicle_collateral.reservation.status_change",
    "event_datetime": "2026-03-10T10:05:00Z",
    "data": {
        "contract_number": "123insd"
    }
}
```

---

### `reserved`

Colateral reservado com sucesso no SNG/B3. Gravame registrado e operação pronta para a próxima etapa.

**Payload**

```json
{
    "key": "1f975b68-7895-4c72-9d79-e73c7b0986b0",
    "reservation_key": "e73c7b68-4c72-9d79-7895-1f975b0986b0",
    "credit_operation_key": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "reserved",
    "webhook_type": "laas.vehicle_collateral.reservation.status_change",
    "event_datetime": "2026-03-10T10:10:00Z",
    "data": {
        "contract_number": "123insd",
        "collateral_number": "00123456",
        "reservation_date": "2026-03-10"
    }
}
```

---

### `pending_requester_action` (Reserva)

Erro durante o processamento do gravame no SNG/B3. Dados inválidos ou restrição detectada. O parceiro deve corrigir as informações e reenviar.

**Payload**

```json
{
    "key": "1f975b68-7895-4c72-9d79-e73c7b0986b0",
    "reservation_key": "e73c7b68-4c72-9d79-7895-1f975b0986b0",
    "credit_operation_key": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "pending_requester_action",
    "webhook_type": "laas.vehicle_collateral.reservation.status_change",
    "event_datetime": "2026-03-10T10:12:00Z",
    "data": {
        "contract_number": "123insd",
        "error_code": "INVALID_CHASSIS",
        "error_reason": "Chassi informado não corresponde aos registros do veículo",
        "error_details": {
            "field": "chassis",
            "expected": "LISD931",
            "received": "LISD930"
        }
    }
}
```

---

### `deleted`

Colateral e contrato cancelados. A operação foi revertida no SNG/B3 e DETRAN.

**Payload**

```json
{
    "key": "1f975b68-7895-4c72-9d79-e73c7b0986b0",
    "reservation_key": "e73c7b68-4c72-9d79-7895-1f975b0986b0",
    "credit_operation_key": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "deleted",
    "webhook_type": "laas.vehicle_collateral.reservation.status_change",
    "event_datetime": "2026-03-10T15:30:00Z",
    "data": {
        "contract_number": "123insd",
        "collateral_number": "00123456",
        "cancellation_date": "2026-03-10",
        "reason": "client_request"
    }
}
```

---

### Campos de Data por Status (Reserva)

| Status | Campos em data | Descrição |
|--------|----------------|-----------|
| `pending_reservation_confirmation` | `contract_number` | Gravame enviado ao SNG/B3, aguardando confirmação |
| `reserved` | `contract_number`, `collateral_number`, `reservation_date` | Gravame registrado com sucesso |
| `pending_requester_action` | `contract_number`, `error_code`, `error_reason`, `error_details` | Erro — parceiro deve corrigir os dados |
| `deleted` | `contract_number`, `collateral_number`, `cancellation_date`, `reason` | Operação cancelada |

:::caution Atenção
Os status relacionados a imagens são exclusivamente internos e **não** são enviados ao cliente externo via webhook.
:::

---

## Webhooks de Garantia Veicular — Registro (DETRAN)

WEBHOOK TYPE
laas.vehicle_collateral.contract.status_change

Notificações relacionadas ao **registro de contrato** no DETRAN/Registradora.

### Estrutura Base do Webhook

```json
{
    "key": "<UUID v4 — identificador único do webhook>",
    "reservation_key": "<UUID — identificador único da reserva>",
    "credit_operation_key": "<UUID — identificador da operação de crédito>",
    "status": "<enumerador de status>",
    "webhook_type": "laas.vehicle_collateral.contract.status_change",
    "event_datetime": "<timestamp ISO 8601>",
    "data": {
        "contract_number": "<número do contrato>",
        "...": "<campos específicos do status>"
    }
}
```

#### Campos Base

| Campo | Tipo | Descrição |
|-------|------|-----------|
| key | String | Identificador único do webhook (UUID v4) |
| reservation_key | String | Identificador único da reserva (UUID) |
| credit_operation_key | String | Identificador da operação de crédito (UUID) |
| status | String | Enumerador de status (ver [Mapa de Status](/documentation/garantia_veicular/mapa_de_status)) |
| webhook_type | String | Sempre `laas.vehicle_collateral.contract.status_change` |
| event_datetime | String | Timestamp do evento (ISO 8601) |
| data | Object | Payload específico do status (ver exemplos abaixo) |

---

### `pending_registration_confirmation`

Contrato em processamento no DETRAN. Documento enviado e o sistema aguarda validação.

**Payload**

```json
{
    "key": "1f975b68-7895-4c72-9d79-e73c7b0986b0",
    "reservation_key": "e73c7b68-4c72-9d79-7895-1f975b0986b0",
    "credit_operation_key": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "pending_registration_confirmation",
    "webhook_type": "laas.vehicle_collateral.contract.status_change",
    "event_datetime": "2026-03-10T10:15:00Z",
    "data": {
        "contract_number": "123insd",
        "stage": "contract_registration"
    }
}
```

---

### `registered`

Contrato registrado com sucesso no DETRAN. Ciclo completo finalizado. Colateral e contrato estão ativos e válidos.

**Payload**

```json
{
    "key": "1f975b68-7895-4c72-9d79-e73c7b0986b0",
    "reservation_key": "e73c7b68-4c72-9d79-7895-1f975b0986b0",
    "credit_operation_key": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "registered",
    "webhook_type": "laas.vehicle_collateral.contract.status_change",
    "event_datetime": "2026-03-10T10:20:00Z",
    "data": {
        "contract_number": "123insd",
        "collateral_number": "00123456",
        "registration_date": "2026-03-10",
        "completion_timestamp": "2026-03-10T10:20:00Z"
    }
}
```

---

### `pending_requester_action` (Registro)

Erro durante o processamento do contrato no DETRAN. Dados inválidos ou balcão detectado. O parceiro deve corrigir as informações e reenviar.

**Payload**

```json
{
    "key": "1f975b68-7895-4c72-9d79-e73c7b0986b0",
    "reservation_key": "e73c7b68-4c72-9d79-7895-1f975b0986b0",
    "credit_operation_key": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "status": "pending_requester_action",
    "webhook_type": "laas.vehicle_collateral.contract.status_change",
    "event_datetime": "2026-03-10T10:22:00Z",
    "data": {
        "contract_number": "123insd",
        "error_code": "INVALID_CONTRACT_DATA",
        "error_reason": "Dados do contrato inválidos ou balcão DETRAN",
        "error_details": {
            "stage": "contract_registration"
        }
    }
}
```

---

### Campos de Data por Status (Registro)

| Status | Campos em data | Descrição |
|--------|----------------|-----------|
| `pending_registration_confirmation` | `contract_number`, `stage` | Contrato enviado ao DETRAN, aguardando validação |
| `registered` | `contract_number`, `collateral_number`, `registration_date`, `completion_timestamp` | Ciclo completo finalizado |
| `pending_requester_action` | `contract_number`, `error_code`, `error_reason`, `error_details` | Erro — parceiro deve corrigir os dados |

---

## Webhooks de Dívida

WEBHOOK TYPE
debt

Os webhooks abaixo notificam sobre mudanças no ciclo de vida da **dívida** associada à garantia veicular. Estes são os mesmos webhooks padrão de dívida documentados em [Webhooks de Dívida](/documentation/webhooks/dividas).

---

### `waiting_signature`

Contrato gerado e disponível para assinatura. A URL de assinatura é enviada neste webhook.

**Payload**

```json
{
    "key": "<Debt Key>",
    "status": "waiting_signature",
    "webhook_type": "debt",
    "event_datetime": "2025-05-10 14:30:00",
    "data": {
        "borrower": {
            "name": "RAZAO SOCIAL CONCESSIONARIA",
            "document_number": "12345678000199"
        },
        "contract": {
            "number": "OP-000000000000001",
            "urls": [
                "https://storage.googleapis.com/doc-api/documents/<uuid>/CONCESSIONARIA-CCB-OP000000000000001.pdf"
            ],
            "signature_information": [
                {
                    "signer_name": "NOME DO REPRESENTANTE",
                    "signer_document_number": "31057466093",
                    "signer_role": "issuer",
                    "signer_email": "representante@concessionaria.com.br",
                    "signature_url": "https://sign.qitech.com.br/<uuid>"
                }
            ]
        }
    }
}
```

---

### `signature_finished`

Todas as assinaturas do contrato foram concluídas.

**Payload**

```json
{
    "key": "<Debt Key>",
    "status": "signature_finished",
    "webhook_type": "debt",
    "event_datetime": "2025-05-10 15:00:00",
    "data": {
        "borrower": {
            "name": "RAZAO SOCIAL CONCESSIONARIA",
            "document_number": "12345678000199"
        },
        "contract": {
            "number": "OP-000000000000001",
            "urls": [
                "https://storage.googleapis.com/doc-api/documents/<uuid>/CONCESSIONARIA-CCB-OP000000000000001-signed.pdf"
            ]
        }
    }
}
```

---

### `disbursed`

Desembolso realizado com sucesso. Recursos transferidos para a conta indicada.

**Payload**

```json
{
    "key": "<Debt Key>",
    "status": "disbursed",
    "webhook_type": "debt",
    "event_datetime": "2025-05-10 16:00:00",
    "data": {
        "borrower": {
            "name": "RAZAO SOCIAL CONCESSIONARIA",
            "document_number": "12345678000199"
        },
        "contract": {
            "number": "OP-000000000000001"
        },
        "disbursement_date": "2025-05-10"
    }
}
```

---

### `canceled`

Operação cancelada. Caso a operação não seja assinada ou averbada até a última opção de data de desembolso, o parceiro recebe este webhook informando o cancelamento.

**Payload**

```json
{
    "key": "<Debt Key>",
    "status": "canceled",
    "webhook_type": "debt",
    "event_datetime": "2025-05-20 10:00:00",
    "data": {
        "cancel_reason": "<CANCEL_REASON>",
        "cancel_reason_enumerator": "<CANCEL_REASON_ENUMERATOR>"
    }
}
```

#### Enumeradores de cancelamento

| Enumerador | Descrição |
|------------|-----------|
| requester_request | Cancelado a pedido do parceiro |
| expiration | Vencimento da operação |
| regulatory | Cancelamento regulatório |
| duplicity | Operação duplicada |
| internal_error | Erro interno |

---

### `settled`

Operação liquidada. Todas as parcelas foram pagas e a operação está encerrada.

**Payload**

```json
{
    "key": "<Debt Key>",
    "status": "settled",
    "webhook_type": "debt",
    "event_datetime": "2026-05-15 10:00:00",
    "data": {
        "borrower": {
            "name": "RAZAO SOCIAL CONCESSIONARIA",
            "document_number": "12345678000199"
        },
        "contract": {
            "number": "OP-000000000000001"
        },
        "settlement_date": "2026-05-15"
    }
}
```

---

:::info Configuração
O Webhook de Garantia Veicular requer URLs cadastradas. Consulte o time de onboarding para configurar.
:::

---

# Alteração de contato de pessoa

URL: /documentation/gestao_de_usuarios/alteracao_de_contato_de_pessoa

## Request

### Token Request

ENDPOINT /baas/token_request
MÉTODO POST

Request Body

```json
{
  "contact_type": "email",
  "person_contact_update": {
    "person_key": "3ea7f034-f06b-4e28-ae19-7c23694f546b",
    "phone_number": {
      "country_code": "55",
      "area_code": "888",
      "number": "988887777"
    }
  },
  "agent_document_number": "99988877765"
}

```

### Token Validation

ENDPOINT /baas/movement_validation
MÉTODO POST

Request Body

```json
{
  "token": "123456",
  "person_contact_update": {
    "person_key": "3ea7f034-f06b-4e28-ae19-7c23694f546b",
    "phone_number": {
      "country_code": "55",
      "area_code": "888",
      "number": "988887777"
    }
  }
}

```

### Body Params

| Campo                   | Tipo   | Descrição                                                                                                                                 | Caracteres                                                                   |
|-------------------------|--------|-------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------|
| `contact_type` *        | string | `(/baas/token_request)` Forma de envio escolhida para o token. Para envios de sms, apenas números brasileiros (+55) receberão a mensagem. | "sms"                                                                        |
| `token` *               | string | `(/baas/token_validation)` Código de seis (6) dígitos enviado ao aprovador da operação. Ex: "123456"                                      | 6                                                                            |
| `person_contact_update` | Object | Informações de alteração de contato                                                                                                       | **[Objeto person_contact_update](#objeto-professional_data_contact_update)** |
| `agent_document_number` | string | CPF de um dos administradores da conta que receberá o SMS para validação Ex: "99977766654"                                                | 11                                                                           |

### Objeto person_contact_update

| Campo          | Tipo   | Descrição                                                                                          | Caracteres                                      |
|----------------|--------|----------------------------------------------------------------------------------------------------|-------------------------------------------------|
| `person_key` * | string | Chave de identificação da pessoa física. Formato uuid v4. Ex: 1ed6dc4e-a0a8-42bb-8cc0-0bb3b0233fb9 | 36                                              |
| `phone_number` | Object | Objeto contendo informações do novo número de telefone                                             | **[Objeto phone_number](#objeto-phone_number)** |
| `email`        | string | Novo email a ser cadastrado                                                                        |                                                 |

### Objeto phone_number

| Campo            | Tipo   | Descrição               | Caracteres |
|------------------|--------|-------------------------|------------|
| `country_code` * | string | DDI do país             | 1-3        |
| `area_code` *    | string | DDD da área do telefone | 1-3        |
| `number` *       | string | Número de telefone      | 10         |

:::info Formas de contato implementadas
`contact_type` permitido para esta operação é **sms** e **email**.
:::

:::info Limitações para modificação
Para alteração de número de telefone a forma de contato deve ser email e para a alteração de email, a forma de contato deve ser sms.
:::

:::info Número a receber token
A pessoa física que está tendo seu cadastro alterado receberá o token.
:::

## Response

### Token Request

STATUS 200

Response Body

```json
{}
```

STATUS 400

Response Body: Tipo de contato não implementado

```json
{
  "title": "Bad Request",
  "description": "Contact type {contact_type} not allowed",
  "translation": "Forma de contato por {contact_type} não permitida",
  "code": "ACC000152",
  "additional_data": {}
}
```

STATUS 400

Response Body: Contato não existente inválido

```json
{
  "title": "Bad Request",
  "description": "Contact does not exist",
  "translation": "Contato nao existe",
  "code": "ACC000135",
  "additional_data": {}
}
```

### Token Validation

STATUS 200

Response Body

```json
{
  "hash": "8e11308086ea336edb113a6ff5746778",
  "return_response": {
    "email": "test.email@email.com",
    "person_key": "110b3ee3-cae2-44de-ba2c-494434d5cb18",
    "phone": [
      {
        "area_code": "11",
        "country_code": "55",
        "number": "988887777"
      }
    ]
  },
  "validation": true
}
```

STATUS 401

Response Body: Token enviado expirado

```json
{
  "title": "Unauthorized",
  "description": "Expired token",
  "translation": "Token Expirado",
  "code": "ACC000134",
  "additional_data": {}
}
```

STATUS 401

Response Body: Token enviado inválido

```json
{
  "title": "Unauthorized",
  "description": "Invalid token",
  "translation": "Token Inválido",
  "code": "ACC000133",
  "additional_data": {}
}
```

---

# Alteração de contato de vínculo

URL: /documentation/gestao_de_usuarios/alteracao_de_contato_de_vinculo

## Request

### Token Request

ENDPOINT /baas/token_request
MÉTODO POST

Request Body

```json
{
  "contact_type": "sms",
  "professional_data_contact_update": {
    "professional_data_key": "4ba8ff34-e07b-4ea8-ae59-8c23994f546b",
    "natural_person": "3ea7f034-f06b-4e28-ae19-7c23694f546b",
    "email": "sample@gmail.com",
    "phone_number": {
      "country_code": "55",
      "area_code": "888",
      "number": "988887777"
    }
  },
  "agent_document_number": "99988877765"
}

```

### Token Validation

ENDPOINT /baas/movement_validation
MÉTODO POST

Request Body

```json
{
  "token": "123456",
  "professional_data_contact_update": {
    "professional_data_key": "4ba8ff34-e07b-4ea8-ae59-8c23994f546b",
    "natural_person": "3ea7f034-f06b-4e28-ae19-7c23694f546b",
    "email": "sample@gmail.com",
    "phone_number": {
      "country_code": "55",
      "area_code": "888",
      "number": "988887777"
    }
  }
}

```

### Body Params

| Campo                              | Tipo   | Descrição                                                                                                                                 | Caracteres                                                                              |
|------------------------------------|--------|-------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
| `contact_type` *                   | string | `(/baas/token_request)` Forma de envio escolhida para o token. Para envios de sms, apenas números brasileiros (+55) receberão a mensagem. | "sms"                                                                                   |
| `token` *                          | string | `(/baas/token_validation)` Código de seis (6) dígitos enviado ao aprovador da operação. Ex: "123456"                                      | 6                                                                                       |
| `professional_data_contact_update` | Object | Informações de vínculo de pessoa física a pessoa jurídica                                                                                 | **[Objeto professional_data_contact_update](#objeto-professional_data_contact_update)** |
| `agent_document_number`            | string | CPF de um dos administradores da conta que receberá o SMS para validação Ex: "99977766654"                                                | 11                                                                                      |

### Objeto professional_data_contact_update

| Campo                     | Tipo   | Descrição                                                                                            | Caracteres                                      |
|---------------------------|--------|------------------------------------------------------------------------------------------------------|-------------------------------------------------|
| `natural_person` *        | string | Chave de identificação da pessoa física. Formato uuid v4. Ex: 1ed6dc4e-a0a8-42bb-8cc0-0bb3b0233fb9   | 36                                              |
| `professional_data_key` * | string | Chave de identificação da pessoa jurídica. Formato uuid v4. Ex: 1ed6dc4e-a0a8-42bb-8cc0-0bb3b0233fb9 | 36                                              |
| `phone_number` *          | Object | Objeto contendo informações do novo número de telefone.                                              | **[Objeto phone_number](#objeto-phone_number)** |
| `email` *                 | string | Novo email a ser cadastrado                                                                          |                                                 |

### Objeto phone_number

| Campo            | Tipo   | Descrição               | Caracteres |
|------------------|--------|-------------------------|------------|
| `country_code` * | string | DDI do país             | 1-3        |
| `area_code` *    | string | DDD da área do telefone | 1-3        |
| `number` *       | string | Número de telefone      | 10         |

:::info Formas de contato implementadas
`contact_type` permitido para esta operação é **sms**.
:::

:::info Número a receber token
A pessoa física que está tendo seu cadastro alterado receberá o token.
:::

## Response

### Token Request

STATUS 200

Response Body

```json
{}
```

STATUS 400

Response Body: Tipo de contato não implementado expirado

```json
{
  "title": "Bad Request",
  "description": "Contact type {contact_type} not allowed",
  "translation": "Forma de contato por {contact_type} não permitida",
  "code": "ACC000152",
  "additional_data": {}
}
```

STATUS 400

Response Body: Contato não existente inválido

```json
{
  "title": "Bad Request",
  "description": "Contact does not exist",
  "translation": "Contato nao existe",
  "code": "ACC000135",
  "additional_data": {}
}
```

### Token Validation

STATUS 200

Response Body

```json
{
  "hash": "8e11308086ea336edb113a6ff5746778",
  "return_response": {
    "admission_date": "2023-06-13",
    "created_at": "2023-06-13T17:26:57",
    "email": "sampl1e@gmail.com",
    "final_beneficiary": null,
    "is_active": true,
    "legal_person_key": "b678ae5c-5797-4bd9-8a4c-9cbd1a0829a4",
    "natural_person_key": "1ed6dc4e-a0a8-42bb-8cc0-0bb3b0233fb9",
    "natural_person_roles": [
      {
        "created_at": "2023-06-13T17:26:57",
        "natural_person_roles_events": [],
        "product_type": {
          "created_at": "2022-04-08T14:51:34",
          "enumerator": "escrow"
        },
        "role_type": {
          "created_at": "2021-02-26T14:14:52",
          "enumerator": "viewer"
        },
        "updated_at": "2023-06-14T20:11:45"
      },
      {
        "created_at": "2023-06-13T17:26:57",
        "natural_person_roles_events": [],
        "product_type": {
          "created_at": "2021-02-26T14:16:35",
          "enumerator": "account"
        },
        "role_type": {
          "created_at": "2021-02-26T14:14:52",
          "enumerator": "viewer"
        },
        "updated_at": "2023-06-14T20:11:46"
      }
    ],
    "phone": {
      "area_code": "61",
      "country_code": "55",
      "number": "988887777",
      "phone_type": "commercial"
    },
    "post_type": {
      "created_at": "2019-02-15T18:28:12",
      "enumerator": "analyst",
      "translation_path": "onboarding.PostType.analyst"
    },
    "profession_data_key": "78c8b92f-4e44-4725-a5fd-aa1fca78366d",
    "updated_at": "2023-06-14T20:11:46"
  },
  "validation": true
}
```

STATUS 401

Response Body: Token enviado expirado

```json
{
  "title": "Unauthorized",
  "description": "Expired token",
  "translation": "Token Expirado",
  "code": "ACC000134",
  "additional_data": {}
}
```

STATUS 401

Response Body: Token enviado inválido

```json
{
  "title": "Unauthorized",
  "description": "Invalid token",
  "translation": "Token Inválido",
  "code": "ACC000133",
  "additional_data": {}
}
```

---

# Editar dados de uma pessoa

URL: /documentation/gestao_de_usuarios/alteracao_de_dados_pessoais

## Request

ENDPOINT /person/PERSON_KEY/personal_data
MÉTODO PATCH

### Path Params

| Campo                   | Tipo | Descrição                     | Caracteres |
|-------------------------|------|-------------------------------|------------|
| `PERSON_KEY` *          | UUID | identificador único da person | 36         |

Request Body

```json
{
    "name": "Mateus da Silva",
    "date_of_birth": "1995-05-01",
    "profession": "programer",
    "mother_name": "Maria de Jesus",
    "father_name": "João dos Santos",
    "birth_place": "Taguatinga",
    "spouse_name": "Luis dos anjos",
    "is_pep": true,
    "revenue_amount": 100.52,
    "onboarding_key": "bc90744e-4f9a-42b1-9410-d5fa3c183fa8"
}

```

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `name` | string | Nome completo | - | 
| `date_of_birth` |  string | Data de aniversário, no formato YYYY-MM-DD | date | 
| `profession` | string | Profissão | - |
| `mother_name` | string |  Nome da mãe| - |
| `father_name` | string | Nome do pai | - | 
| `birth_place` | string | Local de nascimento | - | 
| `spouse_name` | string | Nome do cônjuge | - |
| `is_pep` | Boolean | Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep).  | boolean |
| `revenue_amount` | number | Renda mensal | - |
| `onboarding_key` | string | Chave utilizada na validação do antifraude | uuuidv4 |

## Response

STATUS 204

Response Body

```json
{}
```

STATUS 4XX

Response Body

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo"
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title` | Descrição (eng)<br/>`Description`                                       | Descrição (ptbr)<br/>`translation`                                               |
|-------------|----------------------|--------------------|-------------------------------------------------------------------------|----------------------------------------------------------------------------------|
| 404         | OBD000019            | Not found          | Person not found                                                        | Pessoa não encontrada.                                                           |
| 403         | OBD000073            | Unauthorized       | User does not have permission to add or modify persons to this domain   | Usuário não tem permissão para adicionar ou modificar pessoas a este domínio.    |

---

# Editar endereço de uma pessoa

URL: /documentation/gestao_de_usuarios/alteracao_de_endereco

## Request

ENDPOINT /person/PERSON_KEY/address
MÉTODO PUT

### Path Params

| Campo                   | Tipo | Descrição                     | Caracteres |
|-------------------------|------|-------------------------------|------------|
| `PERSON_KEY` *          | UUID | identificador único da person | 36         |

Request Body

```json
{
    "street": "Rua Sample after test",
    "complement": "Apto 125",
    "state": "MG",
    "number": "1234",
    "neighborhood": "Cabral",
    "postal_code": "38300000",
    "city": "Ituiutaba"
}

```

## Response

STATUS 204

Response Body

```json
{}
```

STATUS 4XX

Response Body

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo"
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title` | Descrição (eng)<br/>`Description`                                       | Descrição (ptbr)<br/>`translation`                                               |
|-------------|----------------------|--------------------|-------------------------------------------------------------------------|----------------------------------------------------------------------------------|
| 404         | OBD000019            | Not found          | Person not found                                                        | Pessoa não encontrada.                                                           |
| 403         | OBD000073            | Unauthorized       | User does not have permission to add or modify persons to this domain   | Usuário não tem permissão para adicionar ou modificar pessoas a este domínio.    |

---

# Consultar partes relacionadas a uma conta PJ

URL: /documentation/gestao_de_usuarios/consulta_partes_relacionadas

## Request

ENDPOINT /account/ ACCOUNT_KEY /related_parties
MÉTODO GET

### Path Params

| Campo | Tipo | Descrição                      |
|---|------|--------------------------------|
| `ACCOUNT_KEY` | uuidv4 | Chave única de identificação da conta |

## Response

STATUS 200

Response Body

```json
{
    "allowed_users": [
        {
            "natural_person_document_number": "49875468975",
            "natural_person_key": "69850ae3-28bc-4779-a871-e73e1e993412",
            "natural_person_name": "Gabriel Pomodoro",
            "professional_data_key": "3532ea7d-855b-4033-8e1c-7a28d4440d4a"
        },
        {
            "natural_person_document_number": "79857848695",
            "natural_person_key": "7f775i35-da9b-493b-8d43-c5c34282f6cb",
            "natural_person_name": "Fernando Teixeira",
            "professional_data_key": "fd6b4ta8-0c1a-481f-a046-6e0e6edcfb43"
        }
    ],
    "legal_person_key": "40e841e1-edc6-44f2-9a55-7f97eed1bef5",
    "owner_document_number": "10479846950100",
    "owner_name": "EMPRESA DE TESTE S.A"
}
```

### Body params

| Campo | Tipo          | Descrição                                    |
|-------|---------------|----------------------------------------------|
| `allowed_users` | list        | Objeto contendo os usuários vinculados a conta. (**[Objeto allowed_users](#objeto-allowed_users)**) |
| `legal_person_key` | uuidv4 | Chave única de identificação do titular da conta |
| `owner_document_number` | string        | Número CNPJ do Titular da conta. |
| `owner_name` | string        | Razão Social do Titular da Conta. |

### Objeto allowed_users

| Campo | Tipo          | Descrição                                    | 
|-------|---------------|----------------------------------------------|
| `natural_person_document_number` | string        | Número do CPF do usuário vinculado à conta. |
| `natural_person_key` | uuidv4 | Chave única de identificação do usuário vinculado à conta. |
| `natural_person_name` | string        | Nome do usuário vinculado à conta. |
| `professional_data_key` | uuidv4 | Chave única de identificação do vínculo entre usuário e a pessoa jurídica titular da conta. |

---

# Criação de pessoa

URL: /documentation/gestao_de_usuarios/criacao_de_pessoa

## Request

### Token Request

ENDPOINT /baas/token_request
MÉTODO POST

Request Body

```json
{
    "contact_type": "sms",
    "person_creation": {
        "person": {
            "date_of_birth": "1987-01-11",
            "spouse_name": "sample spouse name",
            "birth_place": "sample birth place",
            "phone_number": {
                "country_code": "55",
                "area_code": "888",
                "number": "988887777"
            },
            "representative": null,
            "father_name": "sample father name",
            "address": {
                "street": "Rua Sample Avenue",
                "complement": "Apto 123",
                "state": "MG",
                "number": "1234",
                "neighborhood": "Cabral",
                "postal_code": "38300000",
                "city": "Ituiutaba"
            },
            "nationality": "Brasil",
            "document_identification_number": "sample identification number",
            "mother_name": "Sample Mama",
            "person_type": "natural",
            "name": "Sample Name Natural",
            "profession": "sample profession",
            "gender": null,
            "email": "sample@gmail.com",
            "document_number": "68346734500",
            "marital_status": null
        }
    },
	"agent_document_number": "99988877765"
    }

```

### Token Validation

ENDPOINT /baas/movement_validation
MÉTODO POST

Request Body

```json
{
    "token": "076244",
    "person_creation": {
        "person": {
            "date_of_birth": "1987-01-11",
            "spouse_name": "sample spouse name",
            "birth_place": "sample birth place",
            "phone_number": {
                "country_code": "55",
                "area_code": "888",
                "number": "988887777"
            },
            "representative": null,
            "father_name": "sample father name",
            "address": {
                "street": "Rua Sample Avenue",
                "complement": "Apto 123",
                "state": "MG",
                "number": "1234",
                "neighborhood": "Cabral",
                "postal_code": "38300000",
                "city": "Ituiutaba"
            },
            "nationality": "Brasil",
            "document_identification_number": "sample identification number",
            "mother_name": "Sample Mama",
            "person_type": "natural",
            "name": "Sample Name Natural",
            "profession": "sample profession",
            "gender": null,
            "email": "sample@gmail.com",
            "document_number": "68346734500",
            "marital_status": null
        }
    }
    }

```

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `contact_type` * | string | `(/baas/token_request)` Forma de envio escolhida para o token. Para envios de sms, apenas números brasileiros (+55) receberão a mensagem. | "sms" |
| `token` * | string | `(/baas/token_validation)` Código de seis (6) dígitos enviado ao aprovador da operação. Ex: "123456" | 6 |
| `person_creation` | object | Contêm objeto com as informações da pessoa a ser cadastrada | **[Objeto person_creation](#objeto-person_creation)** |
| `agent_document_number` | string | CPF de um dos administradores da conta que receberá o SMS para validação Ex: "99977766654" | 11 |

### Objeto person_creation

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `person` * | object | Informações da pessoa a ser cadastrada. | **[Objeto person](#objeto-person)**|

### Objeto person
| Campo | Tipo | Descrição | Caracteres |
|---| ---| ---| ---| 
| `address` | object | Endereço da pessoa. | **[Objeto adress](#objeto-address)** |  |
| `date_of_birth` * | string |  Data de nascimento da pessoa (formato "AAAA-MM-DD") |  |
| `document_identification_number`  | string |  Campo destinado ao envio do número de uma documentação adicional, como a CNH (limitado a 16 caracteres). |  |
| `email` * | string |  Email da pessoa. |  |
| `document_number` * | string | CPF da pessoa (apenas números). Limitado a 11 caracteres. |  |
| `is_pep` * | string |  Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep).|  |
| `mother_name` * | string |  Nome da mãe da pessoa em caso de PF. | 100 |
| `name` * | string |  Razão social em caso de operações PJ ou Nome da pessoa em caso de operações PF. | 100 |
| `nationality` * | string |  Nacionalidade da pessoa. | 50 |
| `birth_place` * | string |  Local de nascimento da pessoa. | 50 |
| `person_type` * | string | Identificador de que o objeto enviado é uma pessoa física ou jurídica.| "natural", "legal" |
| `phone_number` * | object | Objeto com dados do telefone | **[Objeto phone](#objeto-phone)**|
| `proof_of_residence` | string |  DOCUMENT_KEY do PDF do comprovante de endereço do endereço enviado (enviado previamente).| |
| `spouse_name` | string |  Nome do cônjuge| |
| `father_name` | string |  Nome do pai da pessoa em caso de PF.| |
| `profession` | string |  Profissão da pessoa em caso de PF.| |

### Objeto address 

| Campo | Descrição | Exemplo |  Máx. Caracteres | 
|---|---|---|---| 
| `street` *| string | Rua do endereço  | 100 |
| `state` *| string | Estado do endereço (com dois caracteres maiúsculos) | 2 |
| `city` *| string | Cidade do endereço | 100 |
| `neighborhood` *| string |Bairro do endereço | 100 |
| `number` *| string | Número da rua | 10 |
| `postal_code` *| string |CEP do endereço (http://www.buscacep.correios.com.br/sistemas/buscacep/) (apenas números) |  8 |
| `complement` *| string |Complemento do endereço (texto livre) | 100 |

### Objeto phone 

| Campo | Descrição | Exemplo |  Máx. Caracteres | 
| --- | --- | --- | --- | 
|`country_code` *| string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 | 
| `area_code` *| string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `number` *| string |Número de telefone (apenas números) |  10 |

:::info Formas de contato implementadas
`contact_type` permitido para esta operação é **sms**.
::: 

:::info Número a receber token
A pessoa a ser cadastrada receberá o token.
:::

## Response

### Token Request

STATUS 200

Response Body

```json
{}
```

STATUS 400

Response Body: Tipo de contato não implementado expirado

```json
{
	"title": "Bad Request",
	"description": "Contact type {contact_type} not allowed",
	"translation": "Forma de contato por {contact_type} não permitida",
	"code": "ACC000152",
	"additional_data": {}
}
```

STATUS 400

Response Body: Contato não existente inválido

```json
{
	"title": "Bad Request",
	"description": "Contact does not exist",
	"translation": "Contato nao existe",
	"code": "ACC000135",
	"additional_data": {}
}
```

### Token Validation

STATUS 200

Response Body

```json
{
	"hash": "bd707fdcb3f78abcab8b5c5b7459f9aa",
	"return_response": {
		"birth_place": "sample birth place",
		"created_at": "2023-06-14T20:51:32",
		"date_of_birth": "1987-01-11T00:00:00",
		"document_identification_number": "sample",
		"email": "sample@gmail.com",
		"father_name": "sample father name",
		"gender": null,
		"is_pep": false,
		"kc_key": "2eedef51-7638-4874-bb98-661080bdfbfd",
		"marital_status": null,
		"mother_name": "Sample Mama",
		"nationality": "Brasil",
		"natural_revenue_range": {
			"average_amount": null,
			"created_at": "2021-03-12T13:26:08",
			"description": "Unavailable",
			"description_ptbr": "Indisponível",
			"enumerator": "0",
			"more_than_amount": null,
			"up_to_amount": null
		},
		"person": {
			"address": {
				"city": "Ituiutaba",
				"complement": "Apto 123",
				"created_at": "2023-06-14T20:51:32",
				"neighborhood": "Cabral",
				"number": "1234",
				"postal_code": "38300000",
				"state": "MG",
				"street": "Rua Sample Avenue"
			},
			"category": null,
			"category_nick": null,
			"created_at": "2023-06-14T20:51:32",
			"document_number": "68346734500",
			"domain": {
				"created_at": "2022-06-29T19:35:17",
				"domain_key": "abc36183-9845-40b9-8a6d-3805b48057e1",
				"domain_name": "QI SCD Domain",
				"owner_person_key": "bf623fcf-6e03-42b7-8664-55141c8acddb"
			},
			"internal_contact": null,
			"internal_contact_person_key": null,
			"name": "Sample Name Natural",
			"person_category": null,
			"person_code": 1681,
			"person_key": "2eedef51-7638-4874-bb98-661080bdfbfd",
			"person_status": {
				"created_at": "2019-02-15T18:28:09",
				"enumerator": "pending",
				"translation_path": "onboarding.PersonStatus.pending"
			},
			"person_type": {
				"created_at": "2019-02-15T18:28:08",
				"enumerator": "natural",
				"translation_path": "onboarding.PersonType.natural"
			},
			"phone": [
				{
					"area_code": "888",
					"country_code": "55",
					"created_at": "2023-06-14T20:51:32",
					"number": "988887777",
					"phone_key": "9a39e3ce-e4fd-447a-9856-83df19989895",
					"phone_type": null
				}
			],
			"professional_data": [],
			"qualifications": [],
			"registration_date": "2023-06-14",
			"risk": null,
			"special_attention": false,
			"terms_acknowledgement": false,
			"valid_cip_beneficiary": false
		},
		"profession": "sample profession",
		"revenue_amount": null,
		"spouse_name": null
	},
	"validation": true
}
```

STATUS 401

Response Body: Token enviado expirado

```json
{
	"title": "Unauthorized",
	"description": "Expired token",
	"translation": "Token Expirado",
	"code": "ACC000134",
	"additional_data": {}
}
```

STATUS 401

Response Body: Token enviado inválido

```json
{
	"title": "Unauthorized",
	"description": "Invalid token",
	"translation": "Token Inválido",
	"code": "ACC000133",
	"additional_data": {}
}
```

---

# Exclusão de vínculo

URL: /documentation/gestao_de_usuarios/exclusao_de_vinculo

## Request

### Token Request

ENDPOINT /baas/token_request
MÉTODO POST

Request Body

```json
{
	"contact_type":"sms",
	"professional_data_deletion":{
		"natural_person": "1ed6dc4e-a0a8-42bb-8cc0-0bb3b0233fb9",
		"legal_person": "b678ae5c-5797-4bd9-8a4c-9cbd1a0829a4"
	},
	"agent_document_number": "99988877765"
}

```

### Token Validation

ENDPOINT /baas/movement_validation
MÉTODO POST

Request Body

```json
{
	"token": "746116",
	"professional_data_deletion":{
		"natural_person": "1ed6dc4e-a0a8-42bb-8cc0-0bb3b0233fb9",
		"legal_person": "b678ae5c-5797-4bd9-8a4c-9cbd1a0829a4",
	}
}

```

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `contact_type` * | string | `(/baas/token_request)` Forma de envio escolhida para o token. Para envios de sms, apenas números brasileiros (+55) receberão a mensagem. | "sms" |
| `token` * | string | `(/baas/token_validation)` Código de seis (6) dígitos enviado ao aprovador da operação. Ex: "123456" | 6 |
| `professional_data_deletion` | Object | Vínculo de pessoa física a pessoa jurídica a ser removido | **[Objeto professional_data_deletion](#objeto-professional_data_)** |
| `agent_document_number` | string | CPF de um dos administradores da conta que receberá o SMS para validação Ex: "99977766654" | 11 |

### Objeto professional_data_deletion

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `natural_person` * | string | Chave de identificação da pessoa física. Formato uuid v4. Ex: 1ed6dc4e-a0a8-42bb-8cc0-0bb3b0233fb9| 36 |
| `legal_person` * |string | Chave de identificação da pessoa jurídica. Formato uuid v4. Ex: 1ed6dc4e-a0a8-42bb-8cc0-0bb3b0233fb9| 36 |

:::info Formas de contato implementadas
`contact_type` permitido para esta operação é **sms**.
::: 

:::info Número a receber token
Uma das pessoas cadastradas como **administrador de conta da pessoa jurídica** a ser vinculada receberá o token.
:::

## Response

### Token Request

STATUS 200

Response Body

```json
{}
```

STATUS 400

Response Body: Tipo de contato não implementado expirado

```json
{
	"title": "Bad Request",
	"description": "Contact type {contact_type} not allowed",
	"translation": "Forma de contato por {contact_type} não permitida",
	"code": "ACC000152",
	"additional_data": {}
}
```

STATUS 400

Response Body: Contato não existente inválido

```json
{
	"title": "Bad Request",
	"description": "Contact does not exist",
	"translation": "Contato nao existe",
	"code": "ACC000135",
	"additional_data": {}
}
```

### Token Validation

STATUS 200

Response Body

```json
{
	"hash": "b6e2643b15493d8f604a3083a20f2476",
	"return_response": {
		"deleted": "OK",
		"legal_person": "b678ae5c-5797-4bd9-8a4c-9cbd1a0829a4",
		"natural_person": "1ed6dc4e-a0a8-42bb-8cc0-0bb3b0233fb9"
	},
	"validation": true
}
```

STATUS 401

Response Body: Token enviado expirado

```json
{
	"title": "Unauthorized",
	"description": "Expired token",
	"translation": "Token Expirado",
	"code": "ACC000134",
	"additional_data": {}
}
```

STATUS 401

Response Body: Token enviado inválido

```json
{
	"title": "Unauthorized",
	"description": "Invalid token",
	"translation": "Token Inválido",
	"code": "ACC000133",
	"additional_data": {}
}
```

---

# Inclusão de vínculo

URL: /documentation/gestao_de_usuarios/inclusao_de_vinculo

## Request

### Token Request

ENDPOINT /baas/token_request
MÉTODO POST

Request Body

```json
{
	"contact_type":"sms",
	"professional_data_creation":{
	"natural_person": "1ed6dc4e-a0a8-42bb-8cc0-0bb3b0233fb9",
	"legal_person": "b678ae5c-5797-4bd9-8a4c-9cbd1a0829a4",
	"natural_person_roles": [
		{
			"product_type":"account",
			"role_type": "viewer"
		}
	],
	"post_type":"analyst"
	},
	"agent_document_number": "99988877765"
}

```

### Token Validation

ENDPOINT /baas/movement_validation
MÉTODO POST

Request Body

```json
{
	"token": "746116",
	"professional_data_creation":{
	"natural_person": "1ed6dc4e-a0a8-42bb-8cc0-0bb3b0233fb9",
	"legal_person": "b678ae5c-5797-4bd9-8a4c-9cbd1a0829a4",
	"natural_person_roles": [
		{
			"product_type":"account",
			"role_type": "viewer"
		}
	],
	"post_type":"analyst"
	}
}

```

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `contact_type` * | string | `(/baas/token_request)` Forma de envio escolhida para o token. Para envios de sms, apenas números brasileiros (+55) receberão a mensagem. | "sms" |
| `token` * | string | `(/baas/token_validation)` Código de seis (6) dígitos enviado ao aprovador da operação. Ex: "123456" | 6 |
| `professional_data_creation` | Object | Informações de vínculo de pessoa física a pessoa jurídica | **[Objeto professional_data_creation](#objeto-professional_data_creation)** |
| `agent_document_number` | string | CPF de um dos administradores da conta que receberá o SMS para validação Ex: "99977766654" | 11 |

### Objeto professional_data_creation

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `natural_person` * | string | Chave de identificação da pessoa física. Formato uuid v4. Ex: 1ed6dc4e-a0a8-42bb-8cc0-0bb3b0233fb9| 36 |
| `legal_person` * |string | Chave de identificação da pessoa jurídica. Formato uuid v4. Ex: 1ed6dc4e-a0a8-42bb-8cc0-0bb3b0233fb9| 36 |
| `natural_person_roles` * | array | Informações de permissionamento e produto. | Array de  **[Objeto natural_person_roles](#objeto-natural_person_role)**|
| `post_type` * | string | Número da conta.| "ceo", "analyst", "partner", "director", "attorney", "signer" |

### Objeto natural_person_role
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `product_type` * | string | Tipo de produto a ser dado permissionamento sobre. | "account", "escrow" |
| `role_type` * |string | Tipo de permissionamento a ser dado ao produto.| "administrator", "requester", "viewer" |

:::info Formas de contato implementadas
`contact_type` permitido para esta operação é **sms**.
::: 

:::info Número a receber token
Uma das pessoas cadastradas como **administrador de conta da pessoa jurídica** a ser vinculada receberá o token.
:::

## Response

### Token Request

STATUS 200

Response Body

```json
{}
```

STATUS 400

Response Body: Tipo de contato não implementado expirado

```json
{
	"title": "Bad Request",
	"description": "Contact type {contact_type} not allowed",
	"translation": "Forma de contato por {contact_type} não permitida",
	"code": "ACC000152",
	"additional_data": {}
}
```

STATUS 400

Response Body: Contato não existente inválido

```json
{
	"title": "Bad Request",
	"description": "Contact does not exist",
	"translation": "Contato nao existe",
	"code": "ACC000135",
	"additional_data": {}
}
```

### Token Validation

STATUS 200

Response Body

```json
{
	"hash": "c5ad79fc14d8447ae272c671fe6dc27e",
	"return_response": {
		"admission_date": "2023-06-13",
		"created_at": "2023-06-13T17:26:57",
		"email": null,
		"final_beneficiary": null,
		"is_active": true,
		"legal_person_key": "b678ae5c-5797-4bd9-8a4c-9cbd1a0829a4",
		"natural_person_key": "1ed6dc4e-a0a8-42bb-8cc0-0bb3b0233fb9",
		"natural_person_roles": [
			{
				"created_at": "2023-06-13T17:26:57",
				"natural_person_roles_events": [],
				"product_type": {
					"created_at": "2022-04-08T14:51:34",
					"enumerator": "escrow"
				},
				"role_type": {
					"created_at": "2021-02-26T14:14:52",
					"enumerator": "viewer"
				},
				"updated_at": "2023-06-13T18:24:35"
			},
			{
				"created_at": "2023-06-13T17:26:57",
				"natural_person_roles_events": [],
				"product_type": {
					"created_at": "2021-02-26T14:16:35",
					"enumerator": "account"
				},
				"role_type": {
					"created_at": "2021-02-26T14:14:52",
					"enumerator": "viewer"
				},
				"updated_at": "2023-06-13T18:24:35"
			}
		],
		"phone": null,
		"post_type": {
			"created_at": "2019-02-15T18:28:12",
			"enumerator": "analyst",
			"translation_path": "onboarding.PostType.analyst"
		},
		"profession_data_key": "78c8b92f-4e44-4725-a5fd-aa1fca78366d",
		"updated_at": "2023-06-13T18:24:35"
	},
	"validation": true
}
```

STATUS 401

Response Body: Token enviado expirado

```json
{
	"title": "Unauthorized",
	"description": "Expired token",
	"translation": "Token Expirado",
	"code": "ACC000134",
	"additional_data": {}
}
```

STATUS 401

Response Body: Token enviado inválido

```json
{
	"title": "Unauthorized",
	"description": "Invalid token",
	"translation": "Token Inválido",
	"code": "ACC000133",
	"additional_data": {}
}
```

---

# Introdução

URL: /documentation/gestao_de_usuarios/tfa_introducao

O sistema de Autorização em Dois Fatores, doravante referido como tfa, tem o objetivo de garantir a autorização via token enviado à pessoa responsável por aprovar a alteração ou inclusão de cadastro.

## Requisição de Token

ENDPOINT /baas/token_request
MÉTODO POST

Para realizar a requisição de token é necessário realizar uma requisição com a forma de contato de envio do token e um objeto específico para o tipo de operação a ser realizada. A explicação completa sobre o payload a ser enviado para cada operação é explicitada na sua própria **[página](#operações)**.

Todos os payloads enviados seguem o mesmo formato básico abaixo:

```json
{
	"contact_type":"sms",
	"\<nome_do_objeto_da_operação\>":"\<objeto_da_operação\>"
}
```
:::info Aviso
`contact_type` implementados podem variar de operação para operação.
::: 

:::warning Aviso
O `token` gerado em ambiente de **Sandbox** será sempre **329329**
::: 

## Validação de Token

ENDPOINT /baas/movement_validation
MÉTODO POST

Para efetivar a operação é necessário que seja enviado no payload o token recebido, juntamente com o **mesmo** `objeto_da_operação` enviado na requisição de token.

Todos os payloads enviados seguem o mesmo formato básico abaixo:

```json
{
	"token":"123456",
	"\<nome_do_objeto_da_operação\>":"\<objeto_da_operação\>"
}
```

:::info Aviso
O token enviado é valido por 120 segundos a partir de sua geração
::: 

## Operações

- **[Criação de Pessoa](/documentation/gestao_de_usuarios/criacao_de_pessoa)**
- **[Inclusão de Vínculo](/documentation/gestao_de_usuarios/inclusao_de_vinculo)**
- **[Exclusão de Vínculo](/documentation/gestao_de_usuarios/exclusao_de_vinculo)**
- **[Alteração de contato de vínculo](/documentation/gestao_de_usuarios/alteracao_de_contato_de_vinculo)**

---

# Consulta de Dados do Benefício

URL: /documentation/guides/INSS/inquiries/dados-do-beneficio

Consulta de Dados do Benefício

Consulta saldo, margem e situação de um benefício (`POST /social_security/balance_request`). Uma consulta de dados **válida** é pré-requisito da averbação: sem ela, o pedido de averbação fica pendente de ação do parceiro.

A consulta pode ser feita com o Termo de Autorização já enviado na [consulta da lista de benefícios](/documentation/guides/INSS/inquiries/lista-de-beneficios), ou enviando o termo na própria requisição.

## Caso 1 — Termo de Autorização previamente enviado

Consulta de dados do benefício com o Termo de Autorização previamente enviado.

### Request

ENDPOINT /social_security/balance_request
MÉTODO POST

Testar no Playground

Request Body

```json
{
	"document_number": "14950479032",
	"benefit_number": "22255220"
}
```

### Response

ENDPOINT /social_security/balance_request
MÉTODO POST

Response Body

```json
{
	"balance_request_key": "<GUID DA CONSULTA DE DADOS DO BENEFÍCIO>",
	"status": "pending_search"
}
```

## Caso 2 — Termo de Autorização enviado na própria consulta

Consulta de dados do benefício com envio do Termo de Autorização.

### Request

ENDPOINT /social_security/balance_request
MÉTODO POST

Request Body

```json
{
	"document_number": "14950479032",
	"benefit_number": "22255220",
	"authorization_term": {
		"document_number": "14950479032",
		"legal_representative_document_number": "87237271016",
		"signature": {
			"signer": {
				"name": "Maria da Silva",
				"email": "maria.silva@email.com",
				"phone": {
					"number": "999538380",
					"area_code": "11",
					"country_code": "55"
				},
				"document_number": "87237271016"
			},
			"authentication_type": "opt_in",
			"authenticity": {
				"timestamp": "2024-11-07T14:28:23.382748Z",
				"ip_address": "179.145.48.219",
				"fingerprint": {},
				"third_party_additional_data": {},
				"session_id": "3571e292-3a83-4011-904d-20ee963022ef"
			},
			"signed_object": {
				"document_key": "93a0f18b-f58f-4a22-ab63-2b796cbf7383"
			}
		}
	}
}
```

:::info Duração de Termo de Autorização
O termo de autorização tem validade de 30 dias após a assinatura. Durante o periodo hábil, é possível consultar os dados do benefício sem reenviar autorização do cliente. Caso não tenha sido enviada a autorização, é necessário enviar o termo durante esta requisição.
:::

:::caution Atenção
Nos casos em que houver representante legal, é necessário preencher o campo **"legal_representative_document_number"** com o CPF do representante legal, e os dados do objeto **"signer"** devem ser preenchidos com os dados do mesmo.
:::

--- 

### Response

ENDPOINT /social_security/balance_request
MÉTODO POST

Response Body

```json
{
	"balance_request_key": "<GUID DA CONSULTA DE DADOS DO BENEFÍCIO>",
	"status": "pending_authorization"
}

```

## Webhook de sucesso

Em caso de sucesso na consulta de dados do benefício

WEBHOOK_TYPE social_security_balance_request
STATUS Success

Webhook Body

```json
{
	"webhook_type": "social_security_balance_request",
	"key": "<GUID balance_request_key>",
	"event_datetime": "<DATA E HORA DO ENVIO DO WEBHOOK>",
	"status": "success",
	"data": {
            "name": "IVOLANDO MIRANDA",
            "state": "SP",
            "alimony": "not_payer",
            "birth_date": "07021961",
            "grant_date": "2022-09-02",
            "credit_type": "checking_account",
            "block_type": "not_blocked",
            "benefit_card": {
                "limit": 2083.2,
                "balance": 0
            },
            "benefit_number": "22255220",
            "benefit_status": "elegible",
            "payroll_card": {
                "limit": 2083.2,
                "balance": 0
            },
            "assistance_type": "retirement_by_age",
            "document_number": "14950479032",
            "benefit_end_date": "2020-12-01",
            "consigned_credit": {
                "balance": 1000
            },
            "benefit_situation": "active",
            "max_total_balance": 2000,
            "used_total_balance": 1000,
            "politically_exposed": {
                "type": "politically_exposed_level_1",
                "is_politically_exposed": true
            },
            "has_power_of_attorney": false,
            "available_total_balance": 1000,
            "has_judicial_concession": false,
            "number_of_portabilities": 0,
            "disbursement_bank_account": {
                "bank_code": "341",
                "account_digit": "6",
                "account_branch": "0155",
                "account_number": "000059923"
            },
            "has_entity_representation": false,
            "social_benefit_max_balance": 2000,
            "social_benefit_used_balance": 1000,
            "benefit_quota_expiration_date": null,
            "number_of_active_reservations": 0,
            "number_of_suspended_reservations": 0,
            "number_of_refinanced_reservations": 0,
            "number_of_active_suspended_reservations": 3
        }
}
```

### Detalhamento de campos no webhook de sucesso

| Campo                     | Descrição                                                                                                                   | Valores                                       |
|---------------------------|-----------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------|
| assistance_type           | Tipo do benefício                                                                                                           | [Enumeradores](/documentation/guides/INSS/reference/enumeradores#benefit_type_enumerator)      |
| benefit_status            | Status do beneficio                                                                                                         | [Enumeradores](/documentation/guides/INSS/reference/enumeradores#benefit_status_enumerator)    |
| has_entity_representation | Possui entidade de representação (não permite averbação)                                                                    | True ou False                                 |
| alimony_code              | Classificador da Pensão alimentícia                                                                                         | not_payer, payer, benefit                     |
| has_judicial_concession   | Benefício concedido por liminar                                                                                             | True ou False                                 |
| has_power_of_attorney     | Possui procurador?                                                                                                          | True ou False                                 |
| credit_type               | Tipo de crédito - recebimento do benefício                                                                                  | Magnetic_card, checking_account               |
| benefit_situation         | Situação do benefício                                                                                                       | [Enumeradores](/documentation/guides/INSS/reference/enumeradores#benefit_situation_enumerator) |
| used_total_balance        | Valor total comprometido em averbações de empréstimos, reservado para portabilidade, refinanciamento, alterações, RMC e RCC | Numérico                                      |
| max_total_balance         | Valor comprometido possível para a respectiva espécie do benefício                                                          | Numérico                                      |
| available_total_balance   | Valor total disponível para empréstimo, somando todas as modalidades (diferença entre max_total_balance e used_total_balance)         | Numérico                                      |
| benefit_quota_expiration_date   | Data de extinção do benefício. A informação está disponível apenas para alguns benefícios de pensão por morte. | String ou nulo     
| block_type                | Tipo de bloqueio do benefício                                                                                               | [Enumeradores](/documentation/guides/INSS/reference/enumeradores#block_type_enumerator)
| politically_exposed.type    | Pessoa politicamente exposta                                                                                                | [Enumeradores](/documentation/guides/INSS/reference/enumeradores#politically_exposed_enumerator)
| is_politically_exposed      | Pessoa politicamente exposta                                                                                                | True ou False

## Webhook de bloqueio

Para os casos que o benefício está bloqueado

WEBHOOK_TYPE social_security_balance_request
STATUS Blocked

Webhook Body

```json
{
	"webhook_type": "social_security_balance_request",
	"key": "<GUID balance_request_key>",
	"event_datetime": "<DATA E HORA DO ENVIO DO WEBHOOK>",
	"status": "blocked",
	"data": {
            "benefit_blocked": true,
            "document_number": "12345678910",
            "balance_request_date": "2025-12-01",
            "block_date": "2025-11-17",
            "assistance_type": "retirement_by_age",
            "block_type": "blocked_by_benefitiary"
    }
}
```

### Detalhamento de campos no webhook de bloqueio

| Campo                     | Descrição                           | Valores                          |
|---------------------------|-------------------------------------|----------------------------------|
| benefit_blocked                | Status do bloqueio  | True |
| balance_request_date                | Data da consulta  | String |
| block_date                | Data do bloqueio  | String ou nulo |
| block_type                | Tipo de bloqueio  | [Enumeradores](/documentation/guides/INSS/reference/enumeradores#block_type_enumerator) |

## Webhook de falha

Em caso de falha na consulta da lista de benefícios

WEBHOOK_TYPE social_security_balance_request
STATUS Failure

Webhook Body

```json
{
	"webhook_type": "social_security_balance_request",
	"key": "<GUID balance_request_key>",
	"event_datetime": "<DATA E HORA DO ENVIO DO WEBHOOK>",
	"status": "failure",
	"data": {
		"enumerator": "not_found_legal_representative",
		"description": "no legal representative for the beneficiary"
	}
}
```

### Detalhamento de campos no webhook de falha

| Campo                     | Descrição                           | Valores                          |
|---------------------------|-------------------------------------|----------------------------------|
| enumerator                | Retorno mapeado do código Dataprev  | [Enumeradores](/documentation/guides/INSS/reference/enumeradores#dataprev_balance_errors_enumerators) |

## Simulando cenários de sucesso e insucesso na consulta de benefício em Sandbox:
A simulação de cenários é baseado no primeiro dígito do CPF informado na operação.

**11.1.** Para CPFs iniciados com o número 1, será retornado uma resposta assíncrona de sucesso através do Webhook.

**11.2.** Para os demais CPFs, será retornado uma resposta assíncrona de erro, baseado no primeiro dígito do CPF digitado, de acordo com a tabela abaixo.

| Início do CPF | Enumerador             | Descrição            |
|---------------|------------------------|----------------------|
| 2             | inexistent_beneficiary | no beneficiary found |

:::caution Atenção
Todos os CPFs que não tiverem um cenário mapeado para o primeiro dígito, receberão um webhook com um erro padrão de cenário de teste não mapeado. 

| Enumerador    | Descrição                                                        |
|---------------|------------------------------------------------------------------|
| mock_error    | Informed document number is not a valid mock on test environment |
:::

**11.3.** O CPF `18166261553` simula, com sucesso (HTTP 200, sem erro), um benefício com **margem consignável negativa** (`available_total_balance: -7.84`). Use este CPF para testar a rejeição de novas operações quando o beneficiário já excedeu a margem disponível. Lista completa de CPFs e cenários mockados: [Mocks (Sandbox)](/documentation/guides/INSS/mocks-sandbox).

---

---

# Consulta da Lista de Benefícios

URL: /documentation/guides/INSS/inquiries/lista-de-beneficios

Consulta da Lista de Benefícios

Consulta os benefícios do INSS de um CPF (`POST /social_security/benefits_request`), com a formalização do Termo de Autorização feita pelo parceiro. É o **primeiro passo de qualquer operação INSS** — crédito novo, refinanciamento ou portabilidade.

Próximo passo: [Consulta de dados do benefício](/documentation/guides/INSS/inquiries/dados-do-beneficio).

## Request

Caso 1: Titular do benefício é o assinante do Termo de Autorização.

ENDPOINT /social_security/benefits_request
MÉTODO POST

Testar no Playground

Request Body

```json
{
	"document_number": "14950479032",
	"authorization_term": {
		"document_number": "14950479032",
		"signature": {
			"signer": {
				"name": "Maria da Silva",
				"email": "maria.silva@email.com",
				"phone": {
					"number": "999538380",
					"area_code": "11",
					"country_code": "55"
				},
				"document_number": "87237271016"
			},
			"authentication_type": "opt_in",
			"authenticity": {
				"timestamp": "2024-11-07T14:28:23.382748Z",
				"ip_address": "179.145.48.219",
				"fingerprint": {},
				"third_party_additional_data": {},
				"session_id": "3571e292-3a83-4011-904d-20ee963022ef"
			},
			"signed_object": {
				"document_key": "93a0f18b-f58f-4a22-ab63-2b796cbf7383"
			}
		}
	}
}
```

Caso 2: Titular do benefício não é o assinante do Termo de Autorização (com representante legal).

:::caution O assinante é o representante legal
Quando o titular do benefício **não** é o assinante do Termo de Autorização, os dados que preenchem o objeto `signature.signer` são os **do representante legal**, não os do titular.
:::

ENDPOINT /social_security/benefits_request
MÉTODO POST

Request Body

```json
{
	"document_number": "14950479032",
	"authorization_term": {
		"document_number": "14950479032",
		"legal_representative_document_number": "87237271016",
		"signature": {
			"signer": {
				"name": "Maria da Silva",
				"email": "maria.silva@email.com",
				"phone": {
					"number": "999538380",
					"area_code": "11",
					"country_code": "55"
				},
				"document_number": "87237271016"
			},
			"authentication_type": "opt_in",
			"authenticity": {
				"timestamp": "2024-11-07T14:28:23.382748Z",
				"ip_address": "179.145.48.219",
				"fingerprint": {},
				"third_party_additional_data": {},
				"session_id": "3571e292-3a83-4011-904d-20ee963022ef"
			},
			"signed_object": {
				"document_key": "93a0f18b-f58f-4a22-ab63-2b796cbf7383"
			}
		}
	}
}
```

:::caution Atenção
Nos casos em que houver representante legal, é necessário preencher o campo **"legal_representative_document_number"** com o CPF do representante legal, e os dados do objeto **"signer"** devem ser preenchidos com os dados do mesmo.
:::

--- 

"***document_key***": utilizar a GUID retornada no endpoint /upload

Ao invés da chave do documento pdf assinado no objeto "authorization_term.signed_object.document_key", também é possível enviar o texto corrido do Termo de Autorização, através do objeto "authorization_term.signed_object.raw_text".

## Response

ENDPOINT /social_security/benefits_request
MÉTODO POST

Response Body

```json
{
	"benefits_request_key": "<GUID DA CONSULTA DE BENEFÍCIO>",
	"status": "pending_search"
}
```

Resposta quando o Termo de Autorização ainda está pendente de autorização:

Response Body

```json
{
    "benefits_request_key": "c9d2aa83-006b-4753-92ad-64411a7aa700",
    "document_number": "18028522041",
    "status": "pending_authorization",
    "authorization_term": {
        "authorization_term_key": "5a7b6489-8a47-4b61-a85a-6986b058fda6",
        "status": "signed"
    },
    "status_events": [
        {
        "status": "pending_authorization",
        "event_date": "2023-12-22T16:12:50"
        }
    ]
}
```

Em caso de sucesso na consulta da lista de benefícios:

## Webhooks

WEBHOOK_TYPE social_security_benefits_request
STATUS Success

Webhook Body

```json
{
	"webhook_type": "social_security_benefits_request",
	"key": "<GUID benefits_request_key>",
	"event_datetime": "<DATA E HORA DO ENVIO DO WEBHOOK>",
	"status": "success",
	"data": [{
		"benefit_number": "<No. DO BENEFÍCIO>",
		"benefit_status": "inelegible",
        "grant_date": "2023-06-13"
	}]
}
```

| Campo                     | Descrição                           | Valores                          |
|---------------------------|-------------------------------------|----------------------------------|
| benefit_number            | Número do benefício                 | - |
| benefit_status            | Status do beneficio                 | [Enumeradores](/documentation/guides/INSS/reference/enumeradores#benefit_status_enumerator) |

Em caso de falha na consulta da lista de benefícios

WEBHOOK_TYPE social_security_benefits_request
STATUS Failure

Webhook Body

```json
{
	"webhook_type": "social_security_benefits_request",
	"key": "<GUID benefits_request_key>",
	"event_datetime": "<DATA E HORA DO ENVIO DO WEBHOOK>",
	"status": "failure",
	"data": {
		"enumerator": "not_found_legal_representative",
		"description": "no legal representative for the beneficiary"
	}
}
```

## Detalhamento de campos no webhook de falha

| Campo                     | Descrição                           | Valores                          |
|---------------------------|-------------------------------------|----------------------------------|
| enumerator                | Retorno mapeado do código Dataprev  | [Enumeradores](/documentation/guides/INSS/reference/enumeradores#dataprev_benefits_errors_enumerators) |

## Simulando cenários de sucesso e insucesso na consulta de benefício em Sandbox:
A simulação de cenários é baseado no primeiro dígito do CPF informado na operação.

**11.1.** Para CPFs iniciados com o número 1, será retornado uma resposta assíncrona de sucesso através do Webhook.

**11.2.** Para os demais CPFs, será retornado uma resposta assíncrona de erro, baseado no primeiro dígito do CPF digitado, de acordo com a tabela abaixo.

| Início do CPF | Enumerador             | Descrição            |
|---------------|------------------------|----------------------|
| 2             | inexistent_beneficiary | no beneficiary found |

:::caution Atenção
Todos os CPFs que não tiverem um cenário mapeado para o primeiro dígito, receberão um webhook com um erro padrão de cenário de teste não mapeado. 

| Enumerador    | Descrição                                                        |
|---------------|------------------------------------------------------------------|
| mock_error    | Informed document number is not a valid mock on test environment |
:::

---

---

# Consulta Offline de Saldo

URL: /documentation/guides/INSS/inquiries/offline-balance-request

Consulta Offline de Saldo

Consulta os dados de saldo mais recentes salvos no nosso banco, de forma instantânea.

:::tip Vantagens Técnicas
- **Retorno síncrono** — sem fila de processamento ou espera por webhook;
- **Acesso a benefícios bloqueados** — retorna os últimos dados salvos no sistema, mesmo que o benefício esteja bloqueado;
- **Consulta em cache** — independe da disponibilidade da Dataprev e não gera consumo de chamadas.
:::

Request

ENDPOINT /social_security/balance_request/offline
MÉTODO GET

Query Params

document_number
string
obrigatório
CPF do beneficiário (apenas números, 11 dígitos).

benefit_number
string
obrigatório
Número do benefício INSS.

**Python**

```python title="ENDPOINT"
GET /social_security/balance_request/offline?document_number=14950479032&benefit_number=22255220
```

**curl**

```bash title="ENDPOINT"
curl -X GET \
  'https://api-auth.sandbox.qitech.app/social_security/balance_request/offline?document_number=14950479032&benefit_number=22255220' \
  -H 'AUTHORIZATION: eyJhbGciOiJFUzUxMiJ9.eyJwYXlsb2FkX21kNSI6...' \
  -H 'API-CLIENT-KEY: YOUR_API_CLIENT_KEY' \
  -H 'Content-Type: application/json'
```

Response

STATUS 200

Atributos

last_successful_balance_request
object | null
Última consulta bem-sucedida. `null` se nunca houve sucesso.

**Atributos de last_successful_balance_request**

consulted_at
string
Data e hora da consulta (ISO 8601).

data
object
Dados completos de saldo do benefício. Mesma estrutura do [webhook de consulta de saldo](/documentation/roteiros_laas/webhooks_inss). Veja [detalhamento dos campos](#campos-de-data).
**Atributos de data**

name
string
Nome do beneficiário.

document_number
string
CPF do beneficiário.

benefit_number
string
Status do benefício (`elegible`, `inelegible`).

block_type
string
Tipo de bloqueio (`not_blocked`, `blocked_by_tbm`, etc.).

benefit_situation
string
Situação do benefício (`active`, `inactive`, etc.).

assistance_type
string
Tipo de assistência/aposentadoria.

available_total_balance
number
Margem total disponível para consignação.

consigned_credit
object
Saldo de crédito consignado (`balance`).

payroll_card
object
Cartão consignado (`balance`, `limit`).

benefit_card
object
Cartão benefício (`balance`, `limit`).

number_of_active_reservations
integer
Número de reservas ativas.

disbursement_bank_account
object
Dados da conta bancária de desembolso (`bank_code`, `account_digit`, `account_branch`, `account_number`).

last_blocked_status
object | null
Status de bloqueio mais recente. `null` se não há informação disponível. Derivado automaticamente da fonte **mais recente** — seja consulta de saldo, tentativa de reserva ou verificação do benefício.

**Atributos de last_blocked_status**

consulted_at
string
Data e hora da verificação mais recente (ISO 8601).

status
string
`"blocked"` ou `"unblocked"`.

:::info
Ao menos um dos dois campos será preenchido em uma resposta 200. Caso não exista nenhum dado para a combinação informada, o endpoint retorna 404.
:::

```json title="RESPONSE BODY"
{
    "last_successful_balance_request": {
        "consulted_at": "2025-01-15T14:32:10-03:00",
        "data": {
            "name": "NOME BENEFICIARIO",
            "state": "RS",
            "alimony": "not_payer",
            "birth_date": "18021978",
            "block_type": "not_blocked",
            "grant_date": "2006-05-22",
            "credit_type": "checking_account",
            "benefit_card": {
                "limit": 2259.20,
                "balance": 0
            },
            "benefit_number": "22255220",
            "benefit_status": "elegible",
            "payroll_card": {
                "limit": 2259.20,
                "balance": 0
            },
            "assistance_type": "retirement_invalidity_social_security",
            "document_number": "14950479032",
            "benefit_end_date": null,
            "consigned_credit": {
                "balance": 0
            },
            "benefit_situation": "active",
            "last_inquiry_date": "2018-06-18",
            "max_total_balance": 635.40,
            "used_total_balance": 635.40,
            "politically_exposed": {
                "type": "not_politically_exposed",
                "is_politically_exposed": false
            },
            "has_power_of_attorney": false,
            "available_total_balance": 0,
            "has_judicial_concession": false,
            "number_of_portabilities": 0,
            "disbursement_bank_account": {
                "bank_code": "748",
                "account_digit": "4",
                "account_branch": "0155",
                "account_number": "000070963"
            },
            "has_entity_representation": false,
            "social_benefit_max_balance": 635.40,
            "social_benefit_used_balance": 635.40,
            "benefit_quota_expiration_date": null,
            "number_of_active_reservations": 3,
            "number_of_suspended_reservations": 0,
            "number_of_refinanced_reservations": 0,
            "number_of_active_suspended_reservations": 3
        }
    },
    "last_blocked_status": {
        "consulted_at": "2025-01-15T14:32:10-03:00",
        "status": "unblocked"
    }
}
```

### Cenários de resposta

| Cenário | `last_successful_balance_request` | `last_blocked_status.status` |
|---------|-----------------------------------|------------------------------|
| Apenas consultas com sucesso | Dados da última consulta | `"unblocked"` |
| Apenas consultas com bloqueio | `null` | `"blocked"` |
| Consulta com sucesso seguida de bloqueio posterior | Dados da última consulta | `"blocked"` |
| Bloqueio seguido de consulta com sucesso | Dados da última consulta | `"unblocked"` |

---

## Erros

| Código HTTP | Código QI | Descrição |
|-------------|-----------|-----------|
| 401/403 | (padrão) | Headers de autenticação ausentes ou inválidos |
| 404 | `SSC000101` | Nenhum dado encontrado para a combinação de `document_number` + `benefit_number` |

**Exemplo de resposta 404**

```json
{
    "title": "Offline Balance Not Found",
    "description": "No balance data found for document_number {document_number} and benefit_number {benefit_number}.",
    "translation": "Nenhum dado de saldo encontrado para document_number {document_number} e benefit_number {benefit_number}",
    "code": "SSC000101"
}
```

---

# Lista de Participantes do CTC

URL: /documentation/guides/INSS/inquiries/participantes-ctc

Lista de Participantes do CTC

Consulta as instituições financeiras participantes do CTC (Núclea/CIP) — a lista de onde sai a instituição credora original de uma portabilidade.

        **Request**

- MÉTODO GET
- ENDPOINT /v2/credit_transfer/participants

Testar no Playground

        *Response:*

**response.json**

```json
[
    {
        "name": "<NOME DO BANCO>",
        "bank_code": "<CÓDIGO DO BANCO>",
        "ispb": "<BASE DO CNPJ DO BANCO>"
    }
]
 
```

---

# Consulta de Portabilidade de Origem

URL: /documentation/guides/INSS/inquiries/portabilidade-de-origem

Consulta de Portabilidade de Origem

Recupera os dados do contrato de origem de uma portabilidade — o contrato que está sendo portado da instituição credora original.

É possível consultar os dados da portabilidade do banco de origem como, por exemplo, o número do benefício, a data de início da portabilidade, o número dos contratos excluídos, os valores das parcelas desaverbadas, ultima parcela paga, data de exclusão, entre outros.

        **Request**
- MÉTODO POST
- ENDPOINT /social_security/reservation/external_key/CREDIT-OPERATION-KEY/portability_origin_contract

        *Payload:*

**payload.json**

```json
{
    "request_type":"portability_number",
    "portability_number": "202402070000298096242"
}

```

        **Response**

- MÉTODO POST
- ENDPOINT /social_security/reservation/external_key/CREDIT-OPERATION-KEY/portability_origin_contract

**body.json**

```json
{
    "origin_contract_request_key": "9bb68c89-4b88-400d-9359-99ad8d42a69e",
    "status": "pending_search",
    "status_events": [
        {
            "status": "pending_search"
        }
    ]
}

```

Em caso de sucesso na consulta do número de benefício

         **Webhook**

- WEBHOOK_TYPE social_security_portability_origin_contract_request
- STATUS Success

**body.json**

```json
{
    "webhook": {
        "key": "25e93655-4713-488b-8800-7ac4fddf745f",
        "data": {
          "portability_number": 9223372036854776000,
          "portability_status": "open",
          "benefit_number": 1544326820,
          "portability_start_date": "2024-02-22",
          "deleted_contracts": [
            {
              "origin_bank": {
                "bank_code": 752,
                "name": "CETELEM-BNP"
              },
              "contract_number": "22-844817807/20",
              "last_installment_paid": 84,
              "exclusion_date": "22022024",
              "period_amount": 165.73
            }
          ]
        },
        "status": "success",
        "webhook_type": "social_security_portability_origin_contract_request",
        "event_datetime": "2024-02-26T21:36:22"
    }
}

```

Em caso de falha na consulta do número de benefício

        **Webhook**

- WEBHOOK_TYPE social_security_portability_origin_contract_request
- STATUS Failure

**body.json**

```json
{
    "webhook": {
        "key": "522b5d7d-2dfc-4e92-99b7-d4df3d97edb2",
        "data": {
            "enumerator": "invalid_bank_code",
            "description": "Invalid bank code"
        },
        "status": "failure",
        "webhook_type": "social_security_portability_origin_contract_request",
        "event_datetime": "2024-02-26T21:36:22"
    }
}

```

---

# Última Resposta da Averbação

URL: /documentation/guides/INSS/inquiries/ultima-resposta

Última Resposta da Averbação

Recupera, sob demanda, o **último retorno da Dataprev** para a averbação de uma operação — sem esperar um novo webhook. Use quando o webhook foi perdido, quando a operação está em retentativa ("teimosinha") ou para reconciliar o estado da garantia.

O endpoint muda conforme a família da operação: a operação de crédito responde por `/debt/.../collateral`; a proposta de portabilidade, por `/v2/credit_transfer/proposal/.../collateral`.

## Crédito novo e refinanciamento

A garantia da operação de crédito responde em `GET /debt/{credit_operation_key}/collateral`.

O last response é uma forma de mapear, de forma simples e objetiva, a resposta da comunicação entre a QI e a Dataprev, possibilitando saber quando essa requisição foi feita e qual o retorno obtido (através de um enumerador). Os enumeradores estão diretamente relacionados aos códigos de retorno da Dataprev e são divididos em duas formas: "errors" e "success". 

Cada enumerador tem uma descrição detalhada e o código de referência da Dataprev. Podemos conferir abaixo, com mais detalhes, como serão apresentados os dados do last response.

### Casos de sucesso

#### Request
ENDPOINT /debt/DEBT-KEY/collateral
MÉTODO GET

Testar no Playground

#### Response

Response Body

```json
{
  "collateral_constituted": true,
  "collateral_type": "type",
  "updated_at": "2023-05-24 19:13:02",
  "collateral_data": {
    "state": "SP",
    "benefit_number": 1976703155,
    "status": "reserved",
    "last_response": {
      "success": [
        {
          "enumerator": "succesfully_included",
          "reservation_method" : "new_credit"
        }
      ]
    },
    "last_response_event_datetime": "2023-05-22T19:13:02Z"
  }
}
```

### Detalhamento de campos no retorno da request
| Campo                     | Descrição                           | Valores                          |
|---------------------------|-------------------------------------|----------------------------------|
| enumerator                | Retorno mapeado do código Dataprev  | [Enumeradores](/documentation/guides/INSS/reference/enumeradores#dataprev_response_enumerator_success)|
| reservation_method        | Método de averbação da reserva      | portability, new_credit, refinancing|

### Casos de erro

#### Request
ENDPOINT /debt/DEBT-KEY/collateral
MÉTODO GET

#### Response

Response Body

```json
{
  "collateral_constituted": false,
  "collateral_type": "type",
  "updated_at": "2023-05-24 19:13:02",
  "collateral_data": {
    "state": "SP",
    "benefit_number": 1976703155,
    "status": "pending_reservation",
    "last_response": {
      "errors": [
        {
          "enumerator": "benefit_blocked_by_tbm",
          "reservation_method" : "new_credit"
        }
      ]
    },
    "last_response_event_datetime": "2023-05-22T19:13:02Z"
  }
}
```

### Detalhamento de campos no retorno da request
| Campo                     | Descrição                           | Valores                          |
|---------------------------|-------------------------------------|----------------------------------|
| enumerator                | Retorno mapeado do código Dataprev  | [Enumeradores](/documentation/guides/INSS/reference/enumeradores#dataprev_response_enumerator_errors)|
| reservation_method        | Método de averbação da reserva      | portability, new_credit, refinancing|

## Portabilidade e refinanciamento (Troco)

Na portabilidade a garantia é consultada pela proposta, informando em `credit-operation-type` qual das duas operações se quer ler.

O last response é uma forma de mapear, de forma simples e objetiva, a resposta da comunicação entre a QI e a Dataprev, possibilitando saber quando essa requisição foi feita e qual o retorno obtido (através de um enumerador). Os enumeradores estão diretamente relacionados aos códigos de retorno da Dataprev e são divididos em duas formas: "errors" e "success". 

Cada enumerador tem uma descrição detalhada e o código de referência da Dataprev. Podemos conferir abaixo, com mais detalhes, como serão apresentados os dados do last response.

### Casos de sucesso

#### Request
ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /CREDIT-OPERATION-TYPE/collateral
MÉTODO GET

#### Path Params — `credit-operation-type`
| Enumerador               					| Descrição                  		|
|-------------------------------------------|--------------------------------|
| refinancing_credit_operation  			| Operação de refinanciamento    |
| portability_credit_operation     			| Operação de portabilidade      |

#### Response

Response Body

```json
{
   "collateral_data":{
      "benefit_number":1976703155,
      "state":"PI",
      "last_response":{
         "success":[
            {
               "enumerator":"succesfully_included",
               "reservation_method":"portability"
            }
         ]
      },
      "last_response_event_datetime":"2023-05-22T19:13:02Z",
      "status":"reserved"
   },
   "collateral_constituted":true,
   "collateral_type":"social_security"
}
```

### Detalhamento de campos no retorno da request
| Campo                     | Descrição                           | Valores                          |
|---------------------------|-------------------------------------|----------------------------------|
| enumerator                | Retorno mapeado do código Dataprev  | [Enumeradores](/documentation/guides/INSS/reference/enumeradores#dataprev_response_enumerator_success)|
| reservation_method        | Método de averbação da reserva      | portability, new_credit, refinancing|

### Casos de erro

#### Request
ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /CREDIT-OPERATION-TYPE/collateral
MÉTODO GET

#### Response

Response Body

```json
{
  "collateral_constituted": false,
  "collateral_type": "type",
  "updated_at": "2023-05-24 19:13:02",
  "collateral_data": {
    "state": "SP",
    "benefit_number": 1976703155,
    "status": "pending_reservation",
    "last_response": {
      "errors": [
        {
          "enumerator": "benefit_blocked_by_tbm",
          "reservation_method" : "portability"
        },
        {
          "enumerator": "benefit_blocked_by_tbm",
          "reservation_method" : "new_credit"
        }
      ]
    },
    "last_response_event_datetime": "2023-05-22T19:13:02Z"
  }
}
```

### Detalhamento de campos no webhook de falha
| Campo                     | Descrição                           | Valores                          |
|---------------------------|-------------------------------------|----------------------------------|
| enumerator                | Retorno mapeado do código Dataprev  | [Enumeradores](/documentation/guides/INSS/reference/enumeradores#dataprev_response_enumerator_errors) |
| reservation_method        | Método de averbação da reserva      | portability, new_credit, refinancing|

## Última consulta do benefício

Por esse endpoint é possível consultar quando foi a última consulta do benefício na Dataprev.

### Request
ENDPOINT /social_security/benefit/BENEFIT-NUMBER
MÉTODO GET

Testar no Playground

### Response

Response Body

```json
{
    "last_balance_check": "2025-08-22T19:13:02Z",
    "status": "pending_balance_request"
}
```

## Webhook da última tentativa de averbação

Caso a operação não tenha sucesso na averbação, a mesma ficará em retentativa e será enviado o seguinte webhook, detalhando o motivo da não averbação, o horário desta tentativa e o método de averbação utilizado:

**Ver exemplos de webhook**

**Webhook portabilidade**

WEBHOOK_TYPE credit_transfer.proposal.credit_operation

  ```json

  {
    "webhook_type": "credit_transfer.proposal.collateral",
    "proposal_key": "<PROPOSAL-KEY>",
    "event_datetime": "2022-11-24T15:42:12",
    "data": {
      "credit_operation_type": "portability",
      "credit_operation_key": "<CREDIT-OPERATION-KEY>",
      "collateral_type": "social_security",
      "collateral_constituted": false,
      "collateral_data": {
        "status": "pending_reservation",
        "last_response": {
          "errors": [{
            "enumerator": "consignable_margin_excceded"
          }]
        },
        "last_response_event_datetime": "2023-05-22T19:13:02Z",
        "reservation_method": "new_credit",
      }
    }
  }

  ```
**Webhook refinanciamento**

WEBHOOK_TYPE credit_operation.collateral

  ```json

  {
    "webhook_type": "credit_operation.collateral",
    "key": "<CREDIT-OPERATION-KEY>",
    "event_time": "2022-11-24T15:42:12",
    "data": {
      "collateral_type": "social_security",
      "collateral_constituted": false,
      "collateral_data": {
        "status": "pending_reservation",
        "last_response": {
          "errors": [{
            "enumerator": "consignable_margin_excceded"
          }]
        },
        "last_response_event_datetime": "2023-05-22T19:13:02Z",
        "reservation_method": "refinancing",
      }
    }
  }

  ```

### Detalhamento de campos no webhook de falha
| Campo                     | Descrição                           | Valores                          |
|---------------------------|-------------------------------------|----------------------------------|
| enumerator                | Retorno mapeado do código Dataprev  | [Enumeradores](/documentation/guides/INSS/reference/enumeradores#dataprev_response_enumerator_errors) |
| reservation_method        | Método de averbação da reserva      | portability, new_credit, refinancing|

---

# Crédito Consignado INSS

URL: /documentation/guides/INSS/intro

Guias de integração para operações de crédito consignado destinadas a beneficiários do INSS. As páginas
estão agrupadas por **família de endpoint**: uma consulta é documentada uma vez e serve as duas jornadas.

## Consultas

Endpoints de consulta ao INSS/Dataprev, comuns a todas as jornadas.

- **[Lista de Benefícios](/documentation/guides/INSS/inquiries/lista-de-beneficios)** — `POST /social_security/benefits_request`, com o Termo de Autorização. Primeiro passo de qualquer operação.
- **[Dados do Benefício](/documentation/guides/INSS/inquiries/dados-do-beneficio)** — `POST /social_security/balance_request`: saldo, margem e situação. Pré-requisito da averbação.
- **[Consulta Offline de Saldo](/documentation/guides/INSS/inquiries/offline-balance-request)** — últimos dados salvos, de forma síncrona, sem consumir consulta na Dataprev.
- **[Última Resposta da Averbação](/documentation/guides/INSS/inquiries/ultima-resposta)** — recupera sob demanda o último retorno da Dataprev.
- **[Portabilidade de Origem](/documentation/guides/INSS/inquiries/portabilidade-de-origem)** — dados do contrato portado da instituição credora original.
- **[Participantes do CTC](/documentation/guides/INSS/inquiries/participantes-ctc)** — instituições participantes da Núclea/CIP.

## Crédito Novo e Refinanciamento Puro

- **[Fluxo Completo](/documentation/guides/INSS/new-credit-and-refinancing/end-to-end)** — a ordem das chamadas, da consulta ao desembolso.
- **[Simulação](/documentation/guides/INSS/new-credit-and-refinancing/simulacao)** — `POST /debt_simulation`.
- **[Emissão](/documentation/guides/INSS/new-credit-and-refinancing/emissao)** — `POST /debt` com a garantia `social_security`.
- **[Formalização](/documentation/guides/INSS/new-credit-and-refinancing/formalizacao)** — dados complementares da IN 138 e assinatura da CCB.
- **[Recálculo](/documentation/guides/INSS/new-credit-and-refinancing/recalculate)** — ajusta parcelas e taxas de uma operação existente.
- **[Falha no Desembolso](/documentation/guides/INSS/new-credit-and-refinancing/pos-desembolso)** — TED e Pix devolvidos, e a reapresentação de pagamento.

## Portabilidade + Refinanciamento

- **[Fluxo Completo](/documentation/guides/INSS/portability+refinancing/end-to-end)** — a ordem das chamadas de uma portabilidade com ou sem Troco.
- **[Simulação](/documentation/guides/INSS/portability+refinancing/simulacao)** — fixando a taxa ou o valor liberado.
- **[Digitação da Proposta](/documentation/guides/INSS/portability+refinancing/proposta)** — `POST /v2/credit_transfer/proposal`.
- **[Formalização](/documentation/guides/INSS/portability+refinancing/formalizacao)** — documentos e assinatura da proposta.
- **[Máquinas de Status](/documentation/guides/INSS/portability+refinancing/maquinas-de-status)** — status da portabilidade e do refinanciamento (Troco).
- **[Correção de Dados](/documentation/guides/INSS/portability+refinancing/correcao-de-dados)** — com ou sem nova assinatura da CCB.
- **[Recálculo e Reformalização](/documentation/guides/INSS/portability+refinancing/reformalization)** — corrige o refinanciamento e a carência.
- **[Recálculo da Portabilidade](/documentation/guides/INSS/portability+refinancing/recalculate-portability)** — reduz o saldo devedor para caber na margem.
- **[Diminuir o Valor das Parcelas](/documentation/guides/INSS/portability+refinancing/diminuir-parcela)**.
- **[Alterando o Cessionário](/documentation/guides/INSS/portability+refinancing/alterando-cessionario)** — `purchaser_document_number` no aceite.

## Reservas

- **[Averbação e Desaverbação](/documentation/guides/INSS/reservations/averbacao-e-desaverbacao)** — a constituição da garantia na Dataprev, a teimosinha e a desaverbação.
- **[Fila Prioritária](/documentation/guides/INSS/reservations/priority-reservation)** — marca a reserva como `fixed_rate` para priorização no processamento.
- **[Fura-fila](/documentation/guides/INSS/reservations/priority-request)** — requisição síncrona com balde de fichas.
- **[Anuência](/documentation/guides/INSS/pending_confirmation)** — quando o beneficiário precisa confirmar a operação.

## Assinaturas

- **[Em grupo](/documentation/guides/INSS/signatures/batch-group-signature)** — agrupa múltiplas operações do mesmo beneficiário em uma única assinatura.

## Referência

- **[Enumeradores](/documentation/guides/INSS/reference/enumeradores)** — retornos da Dataprev, status e tipos de benefício. Única definição; as outras páginas linkam para cá.
- **[Mocks (Sandbox)](/documentation/guides/INSS/mocks-sandbox)** — CPFs e cenários de teste.

---

# Mocks (Sandbox)

URL: /documentation/guides/INSS/mocks-sandbox

Mocks (Sandbox)

:::danger Aviso Importante!
Não utilize dados pessoais reais (CPF, CNPJ etc.) em ambiente sandbox.
:::

A `social-security-api` intercepta as chamadas à Dataprev em ambiente sandbox/dev e retorna respostas mockadas via [`dataprev_mocker.py`](https://gitlab.qitech.com.br/qilaas/social-security-api/-/blob/master/src/connectors/dataprev_mocker.py). Cada etapa da jornada tem sua própria chave de simulação:

| Etapa | O que decide o cenário |
|---|---|
| [Consulta de saldo/margem](#consulta-de-saldo) | CPF — match exato ou **primeiro dígito** |
| [Averbação da reserva](#averbacao) | **Primeiro dígito** do CPF |
| [Anuência (`pending_confirmation`)](#anuencia) | **Último dígito** do número do benefício |

:::tip Jornada completa em sandbox
Para que a operação percorra a jornada inteira até o desembolso, o CPF e o número do benefício precisam cair, ao mesmo tempo, num cenário de sucesso de **saldo**, de **averbação** e de **anuência**. Combinação recomendada: CPF iniciado em `1` e benefício terminado em `0`.
:::

## Consulta de saldo {#consulta-de-saldo}

A consulta de saldo/margem (`DataprevMocker.get_balance_mocker`) resolve o `document_number` em duas etapas:

1. Tenta um **match exato** do CPF contra a massa de teste.
2. Se não encontrar, usa o **primeiro dígito** do CPF como chave.

Se nenhuma das duas resolver, retorna o erro fixo:

```json
{
    "erros": [
        {
            "codigo": "QIE",
            "mensagem": "CPF divergente da massa de teste informada na documentação."
        }
    ]
}
```

com HTTP `412`.

### Cenários por primeiro dígito (fallback)

Qualquer CPF de teste cujo primeiro dígito seja um dos abaixo cai num destes cenários genéricos — útil quando você não precisa de um CPF fixo:

| 1º dígito | Cenário | `margemDisponivel` | Status |
|---|---|---|---|
| `1` | Margem completa, elegível, sem bloqueios | 431.3 | 200 |
| `2` | Erro Dataprev `D1` — dados do benefício incompletos/inconsistentes/nulos | — | 412 |
| `3` | Margem de cartão/RCC reduzida (R$ 75,90) | 431.3 | 200 |
| `4` | Margem completa (idêntico ao dígito `1`) | 431.3 | 200 |
| `8` | Margem de cartão/RCC zerada | 431.3 | 200 |

CPFs com primeiro dígito `0`, `5`, `6`, `7` ou `9` (e que não tenham match exato) caem no erro `QIE` acima.

Além desses, o mocker reconhece 42 CPFs com match exato — a tabela completa está abaixo.

### CPFs com match exato

Campos já mapeados para o schema público da QI: `consigned_credit.balance` vem de `margemDisponivel`, `available_total_balance` vem de `valorDisponivelAverbacaoEmprestimo`. Boa parte dos CPFs com `retirement_invalidity_work_accident` existe só pra cobrir uma faixa de valores de `available_total_balance` (de R$ 50 a R$ 900) — útil pra testar simulação de dívida contra um teto de margem específico.

| CPF | Benefício (código) | Elegível | Situação | Bloqueio | `consigned_credit.balance` | `available_total_balance` | Status |
|---|---|---|---|---|---|---|---|
| `18166261553` | retirement_by_contribution_time (42) — **margem negativa** | Sim | ATIVO | - | **-7.84** | **-7.84** | 200 |
| `30449750345` | pension_by_death_statute (22) | Não | INATIVO | Bloqueado por TBM | 1000 | 0 | 200 |
| `58992386400` | pension_by_death_statute (22) | Não | ATIVO | Bloqueado por TBM | 1000 | 0 | 200 |
| `15588881010` | retirement_capin_extra_emploee (37) | Sim | ATIVO | - | 1000 | 200 | 200 |
| `80436724154` | retirement_invalidity_work_accident (92) | Não | INATIVO | Bloqueado por TBM | 1000 | 5000 | 200 |
| `34166302540` | pension_by_death_federal_emploee (27) | Não | ATIVO | Bloqueado por TBM | 1000 | 5000 | 200 |
| `71020884851` | pension_by_death_diplomat (20) | Não | ATIVO | Bloqueado por TBM | 1000 | 5000 | 200 |
| `76241089684` | retirement_invalidity_work_accident (92) | Não | ATIVO | Bloqueado por TBM | 1000 | 5000 | 200 |
| `44559483922` | pension_by_death (21) | Não | ATIVO | Bloqueado por TBM | 1000 | 5000 | 200 |
| `14429281238` | pension_by_death_statute (22) | Sim | ATIVO | - | 1000 | 300 | 200 |
| `15843101037` | retirement_by_contribution_time (42) | Sim | ATIVO | - | 1000 | 2000 | 200 |
| `13686315092` | retirement_by_contribution_time (42) | Sim | ATIVO | - | 1000 | 2000 | 200 |
| `14937159097` | retirement_by_contribution_time (42) | Sim | ATIVO | - | 1000 | 50 | 200 |
| `15986213009` | retirement_by_contribution_time (42) | Sim | ATIVO | - | 1000 | 1000 | 200 |
| `17427272048` | retirement_by_age (41) | Sim | ATIVO | - | 1000 | 1600 | 200 |
| `16110575070` | retirement_by_age (41) | Sim | ATIVO | - | 1000 | 2000 | 200 |
| `14996024054` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 100 | 200 |
| `17702273003` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 150 | 200 |
| `12228342009` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 200 | 200 |
| `11709160071` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 250 | 200 |
| `12452312002` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 300 | 200 |
| `10650137019` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 350 | 200 |
| `17287554097` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 400 | 200 |
| `19815793039` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 450 | 200 |
| `11985375079` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 500 | 200 |
| `14732376029` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 750 | 200 |
| `10178596043` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 600 | 200 |
| `17859801060` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 650 | 200 |
| `11524380857` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 700 | 200 |
| `19447847056` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 800 | 200 |
| `10813389038` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 850 | 200 |
| `35776131499` | retirement_invalidity_work_accident (92) | Sim | ATIVO | - | 1000 | 900 | 200 |
| `17283313079` | retirement_by_contribution_time (42) | Sim | ATIVO | - | 1000 | 300 | 200 |
| `14552515004` | retirement_by_age (41) | Sim | ATIVO | - | 1000 | 300 | 200 |
| `14036419005` | retirement_invalidity_social_security (32) | Sim | ATIVO | - | 1000 | 300 | 200 |
| `13423241020` | retirement_by_contribution_time (42) | Sim | ATIVO | - | 1000 | 200 | 200 |
| `12382929090` | retirement_special (46) | Sim | ATIVO | - | 1000 | 200 | 200 |
| `73527133011` | retirement_by_contribution_time (42) | Sim | ATIVO | - | 1000 | 300 | 200 |
| `55111830081` | retirement_by_contribution_time (42) | Sim | ATIVO | - | 1000 | 300 | 200 |
| `83995332030` | retirement_by_contribution_time (42) | Sim | ATIVO | - | 1000 | 300 | 200 |
| `65954790019` | retirement_by_contribution_time (42) | Sim | ATIVO | - | 1000 | 300 | 200 |
| `16257311080` | retirement_by_contribution_time (42) | Sim | ATIVO | - | 1000 | 300 | 200 |

Todos os CPFs acima retornam `bloqueadoParaEmprestimo: false`, exceto os marcados com "Bloqueado por TBM" na coluna Bloqueio (que ainda assim respondem HTTP 200 com `elegivelEmprestimo: false`).

**Exemplo de requisição** (funciona com qualquer CPF da tabela):

ENDPOINT /social_security/balance_request/synchronous
MÉTODO POST

```python title="ENDPOINT"
POST /social_security/balance_request/synchronous
{
    "document_number": "18166261553",
    "benefit_number": "2052711150"
}
```

Resposta (HTTP 200) para o CPF de margem negativa, já mapeada para o schema público:

```json
{
    "assistance_type": "retirement_by_contribution_time",
    "available_total_balance": -7.84,
    "consigned_credit": {
        "balance": -7.84
    },
    "payroll_card": {
        "balance": 0,
        "limit": 2083.2
    },
    "benefit_card": {
        "balance": 0,
        "limit": 2083.2
    },
    "block_type": "not_blocked",
    "benefit_situation": "active"
}
```

## Averbação {#averbacao}

O envio da reserva à Dataprev (`DataprevMocker.send_reserve_balance`) é resolvido **apenas pelo primeiro dígito do CPF** — o número do benefício não influencia esta etapa:

| 1º dígito do CPF | Retorno mockado | Status |
|---|---|---|
| `1` | Sucesso `BZ` — "Averbação registrada" | 200 |
| `2` | Erro `AN` — "Conta corrente/DV do favorecido inválidos" | 412 |
| `3` | Depende do valor da operação: até R$ 1.000,00 sucesso `BZ`; acima disso, erro `HW` — "Margem consignável excedida" | 200 / 412 |
| `4` | Sucesso `BZ` — "Averbação registrada" | 200 |

Qualquer outro primeiro dígito retorna o erro `QIE` ("CPF divergente da massa de teste informada na documentação"), com HTTP `412`.

:::note
Averbação bem-sucedida **não** conclui a reserva: em crédito novo e refinanciamento ela entra em [anuência](#anuencia). Portabilidade não exige anuência e segue direto para `reserved`.
:::

## Anuência {#anuencia}

Depois da averbação, crédito novo e refinanciamento ficam em `pending_confirmation` até a Dataprev informar a confirmação do beneficiário — veja [Anuência (pending confirmation)](/documentation/guides/INSS/pending_confirmation) para o fluxo e os webhooks.

Em sandbox, a resposta dessa consulta é determinada pelo **último dígito do número do benefício** informado na reserva:

| Último dígito do benefício | Situação Dataprev simulada | Desfecho da reserva |
|---|---|---|
| `0`, `1`, `6` | 0 — Ativo | ✅ Confirmada → `reserved`, webhook de averbação e desembolso |
| `5` | 5 — Averbação programada | ✅ Confirmada → `reserved` |
| `3` | 18 na 1ª página, 0 na 2ª | ✅ Confirmada → `reserved` (exercita a paginação) |
| `8` | 18 — Pendente de confirmação | ⏳ Permanece em `pending_confirmation` |
| `9` | 19 — Não confirmado pelo beneficiário | ❌ Cancelada — `social_security_confirmation_denied_by_beneficiary` |
| `7` | 20 — Confirmação expirada | ❌ Nova tentativa de reserva ou cancelamento — `social_security_confirmation_expired` |
| `2` | Resposta sem registros | ⏳ Permanece em `pending_confirmation` |
| `4` | Erro `GR` — "O período está inválido" | ⏳ Permanece em `pending_confirmation` |

:::warning Benefícios terminados em `2` e `4`
Nesses dois cenários a consulta nunca devolve uma situação conclusiva, então a reserva fica em `pending_confirmation` indefinidamente e os webhooks de averbação e de pagamento não são emitidos. Se o objetivo é testar a jornada completa, use um benefício terminado em `0`, `1`, `3`, `5` ou `6`.
:::

## Referências

- [`dataprev_mocker.py`](https://gitlab.qitech.com.br/qilaas/social-security-api/-/blob/master/src/connectors/dataprev_mocker.py) — massa de teste completa
- [Consulta Offline de Saldo](/documentation/guides/INSS/inquiries/offline-balance-request) — schema de resposta completo

---

# Emissão da Operação

URL: /documentation/guides/INSS/new-credit-and-refinancing/emissao

Emissão da Operação

Cria a operação de crédito (`POST /debt`) para um benefício do INSS, com a garantia `social_security` que dá origem ao pedido de averbação na Dataprev.

Antes: [Simulação da Dívida](/documentation/guides/INSS/new-credit-and-refinancing/simulacao) e [Consulta de dados do benefício](/documentation/guides/INSS/inquiries/dados-do-beneficio). Depois: [Formalização](/documentation/guides/INSS/new-credit-and-refinancing/formalizacao).

:::caution Atenção
Para operações em que ainda não se passaram 90 dias desde a data de Despacho Benefício e a averbação não é permitida, é necessário garantir que a soma de disbursement_date e limit_days_to_disburse resulte em uma data posterior aos 90 dias.
Caso essa regra não seja cumprida, a operação será cancelada permanentemente, com o CancelReason: social_security_margin_release_after_disbursement_end_date.
:::
O campo "assistance_type", localizado dentro do objeto "collateral_data", refere-se ao tipo de benefício que está sendo utilizado para o empréstimo. O mesmo é retornado na consulta de dados do benefício. Para visualizar os valores possíveis (enumeradores), consultar a tabela [Tabela de enumerador](/documentation/guides/INSS/reference/enumeradores#benefit_type_enumerator)

:::warning Atenção
O objeto `credit_agent` representa o agente de crédito, por vezes conhecido como pastinha, responsável pela originação desta dívida. Este campo é obrigatório para a emissão de dívidas de consignados.
:::

:::warning CIN — Carteira de Identidade Nacional
O campo `document_identification_type` agora aceita o valor `cin` (Carteira de Identidade Nacional). Quando utilizado, o campo `document_identification_number` **deve ser igual ao CPF** do portador (`individual_document_number`). O número do CIN é o próprio CPF.

Valores aceitos em `document_identification_type`: `rg`, `rne`, `cnh`, `ctps`, `class_document`, `passport`, `other`, `cin`.

**Atenção:** o envio do documento de identificação (`document_identification`) passará a ser **obrigatório** nas operações de crédito INSS (crédito novo e portabilidade). Comunique seus integradores com antecedência.
:::

:::info Assinatura em grupo (opcional)
Para reunir esta dívida com outras operações INSS do **mesmo beneficiário** e coletar **uma única assinatura**, envie `document_batch_group_key` na **raiz** do payload (mesmo nível de `borrower`, `financial` etc.). Nesse caso, a assinatura fica vinculada à pasta do grupo e o link único é obtido no envio do grupo para assinatura. Consulte o fluxo de [Assinatura em grupo](/documentation/guides/INSS/signatures/batch-group-signature).
:::

## Request

Caso 1: Emissão sem representante legal

ENDPOINT /debt
MÉTODO POST

Testar no Playground

**Crédito Novo**

```json title='Request Body'
{
    "borrower": {
        "name": "Nome devedor",
        "phone": {
            "number": "999538380",
            "area_code": "84",
            "country_code": "055"
        },
        "gender": "female",
        "is_pep": false,
        "address": {
            "city": "Natal",
            "state": "RN",
            "number": "1984",
            "street": "Rua",
            "complement": "complemento",
            "postal_code": "59065720",
            "neighborhood": "bairro"
        },
        "role_type": "issuer",
        "birth_date": "1959-07-08",
        "mother_name": "NOME DA MAE",
        "nationality": "Brasileiro",
        "person_type": "natural",
        "marital_status": "single",
        "attached_documents_list": [],
        "individual_document_number": "14471835092",
        "document_identification_date": "2015-10-02",
        "document_identification_type": "rg",
        "document_identification_number": "003709888"
    },
    "financial": {
        "interest_type": "pre_price_days",
        "first_due_date": "2023-09-20",
        "disbursement_date": "2024-11-07",
        "fine_configuration": {
            "monthly_rate": 0.0166,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "monthly_interest_rate": 0.0166,
        "installment_face_value": 101.84,
        "limit_days_to_disburse": 7,
        "number_of_installments": 10,
        "principal_grace_period": 0
    },
    "simplified": true,
    "collaterals": [
        {
            "percentage": 1,
            "collateral_data": {
                "state": "SP",
                "benefit_number": 2052711150,
                "subcorban_document_number": "12123456000101"
            },
            "collateral_type": "social_security"
        }
    ],
    "additional_data": {
        "contract": {
            "contract_number": "TST0000644799"
        }
    },
    "purchaser_document_number": "32402502000135",
    "credit_agent": {
        "document_number": "87237271016",
        "name": "Agente de credito"
    },
    "disbursement_bank_accounts": [
        {
            "name": "NOME DEVEDOR",
            "bank_code": "001",
            "account_digit": "0",
            "branch_number": "2874",
            "account_number": "000057555",
            "document_number": "14471835092",
            "transfer_method": "pix",
            "percentage_receivable": 100
        }
    ]
}
  ```
**Refinanciamento**

```json title='Request Body'
{
    "borrower": {
        "name": "Nome devedor",
        "phone": {
            "number": "999538380",
            "area_code": "84",
            "country_code": "055"
        },
        "gender": "female",
        "is_pep": false,
        "address": {
            "city": "Natal",
            "state": "RN",
            "number": "1984",
            "street": "Rua",
            "complement": "complemento",
            "postal_code": "59065720",
            "neighborhood": "bairro"
        },
        "role_type": "issuer",
        "birth_date": "1959-07-08",
        "mother_name": "NOME DA MAE",
        "nationality": "Brasileiro",
        "person_type": "natural",
        "marital_status": "single",
        "attached_documents_list": [],
        "individual_document_number": "14471835092",
        "document_identification_date": "2015-10-02",
        "document_identification_type": "rg",
        "document_identification_number": "003709888"
    },
    "financial": {
        "interest_type": "pre_price_days",
        "first_due_date": "2024-09-20",
        "disbursement_date": "2024-11-07",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "monthly_interest_rate": 0.0166,
        "installment_face_value": 1000,
        "limit_days_to_disburse": 7,
        "number_of_installments": 84,
        "principal_grace_period": 0
    },
    "simplified": true,
    "collaterals": [
        {
            "percentage": 1,
            "collateral_data": {
                "state": "SP",
                "benefit_number": 2052711150,
                "subcorban_document_number": "12123456000101"
            },
            "collateral_type": "social_security"
        }
    ],
    "additional_data": {
        "contract": {
            "contract_number": "TST0000644715"
        }
    },
    "purchaser_document_number": "32402502000135",
    "credit_agent": {
        "document_number": "87237271016",
        "name": "Agente de credito"
    },
    "disbursement_bank_accounts": [
        {
            "name": "NOME DEVEDOR",
            "bank_code": "001",
            "account_digit": "0",
            "branch_number": "2874",
            "account_number": "000057555",
            "document_number": "14471835092",
            "transfer_method": "pix",
            "percentage_receivable": 100
        }
    ],
    "refinanced_credit_operations": [
        {
            "operation_key": "4f32e501-212c-4129-8ac3-d9943b78583b"
        }
    ]
}

  ```

**Crédito Novo - Aumento Salarial**

```json title='Request Body'
{
    "borrower": {
        "name": "Nome devedor",
        "phone": {
            "number": "999538380",
            "area_code": "84",
            "country_code": "055"
        },
        "gender": "female",
        "is_pep": false,
        "address": {
            "city": "Natal",
            "state": "RN",
            "number": "1984",
            "street": "Rua",
            "complement": "complemento",
            "postal_code": "59065720",
            "neighborhood": "bairro"
        },
        "role_type": "issuer",
        "birth_date": "1959-07-08",
        "mother_name": "NOME DA MAE",
        "nationality": "Brasileiro",
        "person_type": "natural",
        "marital_status": "single",
        "attached_documents_list": [],
        "individual_document_number": "14471835092",
        "document_identification_date": "2015-10-02",
        "document_identification_type": "rg",
        "document_identification_number": "003709888"
    },
    "financial": {
        "interest_type": "pre_price_days",
        "first_due_date": "2024-09-20",
        "disbursement_date": "2024-11-07",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "monthly_interest_rate": 0.0166,
        "installment_face_value": 1000,
        "limit_days_to_disburse": 7,
        "number_of_installments": 84,
        "principal_grace_period": 0
    },
    "simplified": true,
    "collaterals": [
        {
            "percentage": 1,
            "collateral_data": {
                "state": "SP",
                "benefit_number": 2052711150,
                "operation_category": "minimum_wage_increase",
                "subcorban_document_number": "12123456000101"
            },
            "collateral_type": "social_security"
        }
    ],
    "additional_data": {
        "contract": {
            "contract_number": "TST0000644715"
        }
    },
    "purchaser_document_number": "32402502000135",
    "credit_agent": {
        "document_number": "87237271016",
        "name": "Agente de credito"
    },
    "disbursement_bank_accounts": [
        {
            "name": "NOME DEVEDOR",
            "bank_code": "001",
            "account_digit": "0",
            "branch_number": "2874",
            "account_number": "000057555",
            "document_number": "14471835092",
            "transfer_method": "pix",
            "percentage_receivable": 100
        }
    ]
}

  ```

Caso 2: Emissão com representante legal

ENDPOINT /debt
MÉTODO POST

**Crédito Novo**

```json
{
    "borrower": {
        "name": "Nome devedor",
        "phone": {
            "number": "999538380",
            "area_code": "84",
            "country_code": "055"
        },
        "gender": "female",
        "is_pep": false,
        "address": {
            "city": "Natal",
            "state": "RN",
            "number": "1984",
            "street": "Rua",
            "complement": "complemento",
            "postal_code": "59065720",
            "neighborhood": "bairro"
        },
        "role_type": "issuer",
        "birth_date": "1959-07-08",
        "mother_name": "NOME DA MAE",
        "nationality": "Brasileiro",
        "person_type": "natural",
        "marital_status": "single",
        "attached_documents_list": [],
        "individual_document_number": "14471835092",
        "document_identification_date": "2015-10-02",
        "document_identification_type": "rg",
        "document_identification_number": "003709888"
    },
    "related_parties": [
        {
            "name": "Representante legal",
            "email": "teste@qitech.com.br",
            "phone": {
                "number": "991294043",
                "area_code": "55",
                "country_code": "055"
            },
            "address": {
                "street": "AV LEONOR",
                "state": "SP",
                "city": "GUARULHOS",
                "neighborhood": "",
                "number": "1",
                "postal_code": "07025200",
                "complement": ""
            },
            "role_type": "issuer_legal_representative",
            "person_type": "natural",
            "is_pep": false,
            "individual_document_number": "19125869086",
            "birth_date": "1970-04-20",
            "mother_name": " Ana Lúcia"
        }
    ],
    "financial": {
        "interest_type": "pre_price_days",
        "first_due_date": "2024-09-20",
        "disbursement_date": "2024-11-07",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "monthly_interest_rate": 0.0166,
        "installment_face_value": 1000,
        "limit_days_to_disburse": 7,
        "number_of_installments": 84,
        "principal_grace_period": 0
    },
    "simplified": true,
    "collaterals": [
        {
            "percentage": 1,
            "collateral_data": {
                "state": "SP",
                "benefit_number": 2052711150,
                "subcorban_document_number": "12123456000101"
            },
            "collateral_type": "social_security"
        }
    ],
    "additional_data": {
        "contract": {
            "contract_number": "TST0000644715"
        }
    },
    "purchaser_document_number": "32402502000135",
    "credit_agent": {
        "document_number": "87237271016",
        "name": "Agente de credito"
    },
    "disbursement_bank_accounts": [
        {
            "name": "NOME DEVEDOR",
            "bank_code": "001",
            "account_digit": "0",
            "branch_number": "2874",
            "account_number": "000057555",
            "document_number": "14471835092",
            "transfer_method": "pix",
            "percentage_receivable": 100
        }
    ]
}
```
**Refinanciamento**

```json
{
    "borrower": {
        "name": "Nome devedor",
        "phone": {
            "number": "999538380",
            "area_code": "84",
            "country_code": "055"
        },
        "gender": "female",
        "is_pep": false,
        "address": {
            "city": "Natal",
            "state": "RN",
            "number": "1984",
            "street": "Rua",
            "complement": "complemento",
            "postal_code": "59065720",
            "neighborhood": "bairro"
        },
        "role_type": "issuer",
        "birth_date": "1959-07-08",
        "mother_name": "NOME DA MAE",
        "nationality": "Brasileiro",
        "person_type": "natural",
        "marital_status": "single",
        "attached_documents_list": [],
        "individual_document_number": "14471835092",
        "document_identification_date": "2015-10-02",
        "document_identification_type": "rg",
        "document_identification_number": "003709888"
    },
    "related_parties": [
        {
            "name": "Representante legal",
            "email": "teste@qitech.com.br",
            "phone": {
                "number": "991294043",
                "area_code": "55",
                "country_code": "055"
            },
            "address": {
                "street": "AV LEONOR",
                "state": "SP",
                "city": "GUARULHOS",
                "neighborhood": "",
                "number": "1",
                "postal_code": "07025200",
                "complement": ""
            },
            "role_type": "issuer_legal_representative",
            "person_type": "natural",
            "is_pep": false,
            "individual_document_number": "19125869086",
            "birth_date": "1970-04-20",
            "mother_name": " Ana Lúcia"
        }
    ],
    "financial": {
        "interest_type": "pre_price_days",
        "first_due_date": "2024-09-20",
        "disbursement_date": "2024-11-07",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "monthly_interest_rate": 0.0166,
        "installment_face_value": 1000,
        "limit_days_to_disburse": 7,
        "number_of_installments": 84,
        "principal_grace_period": 0
    },
    "simplified": true,
    "collaterals": [
        {
            "percentage": 1,
            "collateral_data": {
                "state": "SP",
                "benefit_number": 2052711150,
                "subcorban_document_number": "12123456000101"
            },
            "collateral_type": "social_security"
        }
    ],
    "additional_data": {
        "contract": {
            "contract_number": "TST0000644715"
        }
    },
    "purchaser_document_number": "32402502000135",
    "credit_agent": {
        "document_number": "87237271016",
        "name": "Agente de credito"
    },
    "disbursement_bank_accounts": [
        {
            "name": "NOME DEVEDOR",
            "bank_code": "001",
            "account_digit": "0",
            "branch_number": "2874",
            "account_number": "000057555",
            "document_number": "14471835092",
            "transfer_method": "pix",
            "percentage_receivable": 100
        }
    ],
    "refinanced_credit_operations": [
        {
            "operation_key": "4f32e501-212c-4129-8ac3-d9943b78583b"
        }
    ]
}
```
**Crédito Novo - Aumento Salarial**

```json
{
    "borrower": {
        "name": "Nome devedor",
        "phone": {
            "number": "999538380",
            "area_code": "84",
            "country_code": "055"
        },
        "gender": "female",
        "is_pep": false,
        "address": {
            "city": "Natal",
            "state": "RN",
            "number": "1984",
            "street": "Rua",
            "complement": "complemento",
            "postal_code": "59065720",
            "neighborhood": "bairro"
        },
        "role_type": "issuer",
        "birth_date": "1959-07-08",
        "mother_name": "NOME DA MAE",
        "nationality": "Brasileiro",
        "person_type": "natural",
        "marital_status": "single",
        "attached_documents_list": [],
        "individual_document_number": "14471835092",
        "document_identification_date": "2015-10-02",
        "document_identification_type": "rg",
        "document_identification_number": "003709888"
    },
    "related_parties": [
        {
            "name": "Representante legal",
            "email": "teste@qitech.com.br",
            "phone": {
                "number": "991294043",
                "area_code": "55",
                "country_code": "055"
            },
            "address": {
                "street": "AV LEONOR",
                "state": "SP",
                "city": "GUARULHOS",
                "neighborhood": "",
                "number": "1",
                "postal_code": "07025200",
                "complement": ""
            },
            "role_type": "issuer_legal_representative",
            "person_type": "natural",
            "is_pep": false,
            "individual_document_number": "19125869086",
            "birth_date": "1970-04-20",
            "mother_name": " Ana Lúcia"
        }
    ],
    "financial": {
        "interest_type": "pre_price_days",
        "first_due_date": "2024-09-20",
        "disbursement_date": "2024-11-07",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "monthly_interest_rate": 0.0166,
        "installment_face_value": 1000,
        "limit_days_to_disburse": 7,
        "number_of_installments": 84,
        "principal_grace_period": 0
    },
    "simplified": true,
    "collaterals": [
        {
            "percentage": 1,
            "collateral_data": {
                "state": "SP",
                "benefit_number": 2052711150,
                "operation_category": "minimum_wage_increase",
                "subcorban_document_number": "12123456000101"
            },
            "collateral_type": "social_security"
        }
    ],
    "additional_data": {
        "contract": {
            "contract_number": "TST0000644715"
        }
    },
    "purchaser_document_number": "32402502000135",
    "credit_agent": {
        "document_number": "87237271016",
        "name": "Agente de credito"
    },
    "disbursement_bank_accounts": [
        {
            "name": "NOME DEVEDOR",
            "bank_code": "001",
            "account_digit": "0",
            "branch_number": "2874",
            "account_number": "000057555",
            "document_number": "14471835092",
            "transfer_method": "pix",
            "percentage_receivable": 100
        }
    ],
    "refinanced_credit_operations": [
        {
            "operation_key": "4f32e501-212c-4129-8ac3-d9943b78583b"
        }
    ]
}
```

Exemplo de objeto financial com rebates

```json
{
    "financial": {
        "first_due_date": "2022-12-07",
        "installment_face_value": 100,
        "disbursement_date": "2022-11-03",
        "limit_days_to_disburse": 3,
        "number_of_installments": 24,
        "disbursed_amount": 1876,
        "interest_type": "pre_price_days",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0,
        "rebates": [
            {
                "amount": 20,
                "rebate_bank_account": {
                    "name": "Teste Ltda",
                    "document_number": "18533555000164",
                    "account_digit": "0",
                    "account_number": "4290001",
                    "branch_number": "0001",
                    "bank_code": "329"
                },
                "amount_type": "percentage",
                "fee_type": "spread"
            }
        ]
    }
}
```

## Response

ENDPOINT /debt
MÉTODO POST

A resposta traz **uma opção por data de desembolso disponível** em `disbursement_options`, todas idênticas em estrutura e diferindo apenas na data e nos valores que ela move (juros, IOF, valor de cessão e o cronograma de parcelas). No exemplo real desta operação vieram 8 opções, de 2024-11-07 a 2024-11-14; o corpo abaixo mantém as **duas primeiras**.

Response Body

```json
{
    "webhook_type": "debt",
    "key": "eb859ebe-3a41-49bf-a6c3-d6902039ec00",
    "status": "waiting_signature",
    "event_datetime": "2024-11-07 23:19:22",
    "data": {
        "borrower": {
            "name": "Nome devedor",
            "document_number": "14471835092",
            "related_party_key": "28b7fc16-6d1f-467d-9667-62a8c13daea6"
        },
        "contract": {
            "number": "TST0000644710",
            "urls": [
                "https://storage.googleapis.com/sandbox-doc-api/documents/a2e9c83a-3666-4def-8b27-e96fabb8705c/NOME_DEVEDOR-CCB-TST0000644710-20241107231916.pdf"
            ],
            "signature_information": [
                {
                    "signer_name": "Nome devedor",
                    "signer_document_number": "14471835092",
                    "signer_role": "issuer",
                    "signer_email": null,
                    "signer_external_key": null,
                    "signature_url": null
                }
            ]
        },
        "requester_identifier_key": "eb859ebe-3a41-49bf-a6c3-d6902039ec00",
        "iof_charge_method": "financed",
        "collaterals": [
            {
                "absolute_amount": null,
                "collateral_constituted": false,
                "collateral_data": {
                    "state": "SP",
                    "benefit_number": 2052711150,
                    "reservation_method": "issuing",
                    "subcorban_document_number": "12123456000101"
                },
                "collateral_key": "26c7f4f4-51f3-41fa-b880-9691211136aa",
                "collateral_type": "social_security",
                "created_at": "2024-11-07T23:19:16.413448",
                "external_key": null,
                "percentage": 1,
                "reservation_method": {
                    "enumerator": "issuing"
                },
                "updated_at": "2024-11-07T23:19:16.413441"
            }
        ],
        "disbursement_options": [
            {
                "disbursement_date": "2024-11-07",
                "contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 4.55
                    },
                    {
                        "fee_type": "ted_fee",
                        "fee_amount": 1.5
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0
                    }
                ],
                "contract_fee_amount": 6.05,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "assignment_amount": 914.3,
                "issue_amount": 909.75,
                "cet": "2,0100%",
                "annual_cet": "27,0481%",
                "base_iof": 16.259002146803677,
                "additional_iof": 3.45705,
                "total_iof": 19.72,
                "total_pre_fixed_amount": 108.6508885851,
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-01-20",
                        "calendar_days": 74,
                        "due_date": "2025-01-20",
                        "due_interest": 0.0,
                        "due_principal": 909.75,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 37.1789024864,
                        "principal_amortization_amount": 64.6610975136,
                        "tax_amount": 0.3923635397125248,
                        "total_amount": 101.84,
                        "workdays": 49.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-02-20",
                        "calendar_days": 31,
                        "due_date": "2025-02-20",
                        "due_interest": 0.0,
                        "due_principal": 845.0889024864,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 2,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 14.2997636051,
                        "principal_amortization_amount": 87.5402363949,
                        "tax_amount": 0.753721435360089,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-03-20",
                        "calendar_days": 28,
                        "due_date": "2025-03-20",
                        "due_interest": 0.0,
                        "due_principal": 757.5486660915,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 3,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 11.5685715131,
                        "principal_amortization_amount": 90.2714284869,
                        "tax_amount": 0.9845001990781314,
                        "total_amount": 101.84,
                        "workdays": 18.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-04-22",
                        "calendar_days": 33,
                        "due_date": "2025-04-22",
                        "due_interest": 0.0,
                        "due_principal": 667.2772376046,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 4,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 12.025984633,
                        "principal_amortization_amount": 89.814015367,
                        "tax_amount": 1.222548377175604,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-05-20",
                        "calendar_days": 28,
                        "due_date": "2025-05-20",
                        "due_interest": 0.0,
                        "due_principal": 577.4632222376,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 5,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.8184725787,
                        "principal_amortization_amount": 93.0215274213,
                        "tax_amount": 1.4797864582180404,
                        "total_amount": 101.84,
                        "workdays": 19.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-06-20",
                        "calendar_days": 31,
                        "due_date": "2025-06-20",
                        "due_interest": 0.0,
                        "due_principal": 484.4416948163,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 6,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.1972396908,
                        "principal_amortization_amount": 93.6427603092,
                        "tax_amount": 1.72770892770474,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-07-21",
                        "calendar_days": 31,
                        "due_date": "2025-07-21",
                        "due_interest": 0.0,
                        "due_principal": 390.7989345071,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 7,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 6.6127072945,
                        "principal_amortization_amount": 95.2272927055,
                        "tax_amount": 1.999011328473856,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-08-20",
                        "calendar_days": 30,
                        "due_date": "2025-08-20",
                        "due_interest": 0.0,
                        "due_principal": 295.5716418016,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 8,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 4.8387153664,
                        "principal_amortization_amount": 97.0012846336,
                        "tax_amount": 2.274874127227187,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-09-22",
                        "calendar_days": 33,
                        "due_date": "2025-09-22",
                        "due_interest": 0.0,
                        "due_principal": 198.570357168,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 9,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.5787172455,
                        "principal_amortization_amount": 98.2612827545,
                        "tax_amount": 2.570318634292211,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-10-20",
                        "calendar_days": 28,
                        "due_date": "2025-10-20",
                        "due_interest": 0.0,
                        "due_principal": 100.3090744135,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 10,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.5318141716,
                        "principal_amortization_amount": 100.3081858284,
                        "tax_amount": 2.8541691195612935,
                        "total_amount": 101.84,
                        "workdays": 20.0,
                        "installment_status": null,
                        "installment_type": null
                    }
                ],
                "first_due_date": "2025-01-20",
                "prefixed_interest_rate": {
                    "monthly_rate": 0.0166,
                    "daily_rate": 0.00054142,
                    "annual_rate": 0.21843191,
                    "interest_base": "calendar_days_365"
                }
            },
            {
                "disbursement_date": "2024-11-08",
                "contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 4.55
                    },
                    {
                        "fee_type": "ted_fee",
                        "fee_amount": 1.5
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0
                    }
                ],
                "contract_fee_amount": 6.05,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "assignment_amount": 914.79,
                "issue_amount": 910.24,
                "cet": "2,0200%",
                "annual_cet": "27,0539%",
                "base_iof": 16.187351160427028,
                "additional_iof": 3.458912,
                "total_iof": 19.65,
                "total_pre_fixed_amount": 108.1583324947,
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-01-20",
                        "calendar_days": 73,
                        "due_date": "2025-01-20",
                        "due_interest": 0.0,
                        "due_principal": 910.24,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 36.6863463961,
                        "principal_amortization_amount": 65.1536536039,
                        "tax_amount": 0.3900097704729454,
                        "total_amount": 101.84,
                        "workdays": 48.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-02-20",
                        "calendar_days": 31,
                        "due_date": "2025-02-20",
                        "due_interest": 0.0,
                        "due_principal": 845.0863463961,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 2,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 14.2997636051,
                        "principal_amortization_amount": 87.5402363949,
                        "tax_amount": 0.7465431359757072,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-03-20",
                        "calendar_days": 28,
                        "due_date": "2025-03-20",
                        "due_interest": 0.0,
                        "due_principal": 757.5461100012,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 3,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 11.5685715131,
                        "principal_amortization_amount": 90.2714284869,
                        "tax_amount": 0.9770979419422056,
                        "total_amount": 101.84,
                        "workdays": 18.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-04-22",
                        "calendar_days": 33,
                        "due_date": "2025-04-22",
                        "due_interest": 0.0,
                        "due_principal": 667.2746815143,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 4,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 12.025984633,
                        "principal_amortization_amount": 89.814015367,
                        "tax_amount": 1.21518362791551,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-05-20",
                        "calendar_days": 28,
                        "due_date": "2025-05-20",
                        "due_interest": 0.0,
                        "due_principal": 577.4606661473,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 5,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.8184725787,
                        "principal_amortization_amount": 93.0215274213,
                        "tax_amount": 1.4721586929694939,
                        "total_amount": 101.84,
                        "workdays": 19.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-06-20",
                        "calendar_days": 31,
                        "due_date": "2025-06-20",
                        "due_interest": 0.0,
                        "due_principal": 484.439138726,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 6,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.1972396908,
                        "principal_amortization_amount": 93.6427603092,
                        "tax_amount": 1.7200302213593857,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-07-21",
                        "calendar_days": 31,
                        "due_date": "2025-07-21",
                        "due_interest": 0.0,
                        "due_principal": 390.7963784168,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 7,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 6.6127072945,
                        "principal_amortization_amount": 95.2272927055,
                        "tax_amount": 1.991202690472005,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-08-20",
                        "calendar_days": 30,
                        "due_date": "2025-08-20",
                        "due_interest": 0.0,
                        "due_principal": 295.5690857113,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 8,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 4.8387153664,
                        "principal_amortization_amount": 97.0012846336,
                        "tax_amount": 2.266920021887232,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-09-22",
                        "calendar_days": 33,
                        "due_date": "2025-09-22",
                        "due_interest": 0.0,
                        "due_principal": 198.5678010777,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 9,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.5787172455,
                        "principal_amortization_amount": 98.2612827545,
                        "tax_amount": 2.562261209106342,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-10-20",
                        "calendar_days": 28,
                        "due_date": "2025-10-20",
                        "due_interest": 0.0,
                        "due_principal": 100.3065183232,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 10,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.5318141715,
                        "principal_amortization_amount": 100.3081858285,
                        "tax_amount": 2.845943848326202,
                        "total_amount": 101.84,
                        "workdays": 20.0,
                        "installment_status": null,
                        "installment_type": null
                    }
                ],
                "first_due_date": "2025-01-20",
                "prefixed_interest_rate": {
                    "monthly_rate": 0.0166,
                    "daily_rate": 0.00054142,
                    "annual_rate": 0.21843191,
                    "interest_base": "calendar_days_365"
                }
            }
        ]
    }
}
```

Caso a operação não seja assinada ou averbada até a última opção de data de desembolso o parceiro receberá um webhook informando a respeito do cancelamento da operação:

WEBHOOK_TYPE debt
STATUS Canceled
**Webhook Body**

```json
{
	"key": "<DEBT-KEY>",
	"data": {
		"cancel_reason": "Operacao cancelada manualmente",
		"cancel_reason_enumerator": "manual"
	},
	"status": "canceled",
	"webhook_type": "debt",
	"event_datetime": "2022-11-01 03:46:31"
}
```

## Simulando cenários de sucesso e insucesso na averbação em Sandbox:
A simulação de cenários é baseado no primeiro dígito do CPF informado na operação.

**11.1.** Para CPFs iniciados com o número 1, será retornado uma resposta assíncrona de sucesso através do Webhook.

**11.2.** Para os demais CPFs, será retornado uma resposta assíncrona de erro, baseado no primeiro dígito do CPF digitado, de acordo com a tabela abaixo.

**11.3.** Erros com Ação "cancel" receberá um webhook com o resultado final da operação.

| Início do cpf | Enumerador                   | Descrição                                                                         | Ação   |
|---------------|------------------------------|-----------------------------------------------------------------------------------|--------|
| 2             | invalid_disbursement_account | Invalid disbursemente bank account                                                | cancel |
| 3             | operation_not_allowed_IR     | Operation not allowed due to operation deadline greatter than benefit termination | cancel |

:::caution Atenção
Todos os CPFs que não tiverem um cenário mapeado para o primeiro dígito, receberão um webhook com um erro padrão de cenário de teste não mapeado. 

| Enumerador    | Descrição                                                        |
|---------------|------------------------------------------------------------------|
| mock_error    | Informed document number is not a valid mock on test environment |
:::

---

# Novo e Refin Puro

URL: /documentation/guides/INSS/new-credit-and-refinancing/end-to-end

Fluxo Completo - Crédito Novo e Refinanciamento Puro

Ordem das chamadas de uma operação de crédito novo ou refinanciamento puro para beneficiário do INSS.
Cada etapa tem a sua própria página, com request, response, webhooks e cenários de sandbox.

:::info Duração do Termo de Autorização
O termo de autorização tem validade de 30 dias após a assinatura. Durante o período hábil, é possível
consultar os dados do benefício sem enviar um novo termo.
:::

## Fluxo

1. **[Consulta da lista de benefícios](/documentation/guides/INSS/inquiries/lista-de-beneficios)** — `POST /social_security/benefits_request`, com o Termo de Autorização assinado.
2. **[Consulta de dados do benefício](/documentation/guides/INSS/inquiries/dados-do-beneficio)** — `POST /social_security/balance_request`. Pré-requisito da averbação.
3. **[Simulação da dívida](/documentation/guides/INSS/new-credit-and-refinancing/simulacao)** — `POST /debt_simulation`.
4. **[Emissão da operação](/documentation/guides/INSS/new-credit-and-refinancing/emissao)** — `POST /debt`, com a garantia `social_security`.
5. **[Envio de documentos e formalização](/documentation/guides/INSS/new-credit-and-refinancing/formalizacao)** — dados complementares da IN 138 e assinatura da CCB.
6. **[Averbação e desaverbação](/documentation/guides/INSS/reservations/averbacao-e-desaverbacao)** — constituição da garantia na Dataprev, teimosinha e correção de dados.
7. **[Falha no desembolso e reapresentação](/documentation/guides/INSS/new-credit-and-refinancing/pos-desembolso)** — TED e Pix devolvidos, e como reapresentar.

## Consultas e referência

- **[Última resposta da averbação](/documentation/guides/INSS/inquiries/ultima-resposta)** — recupera o último retorno da Dataprev sob demanda.
- **[Consulta offline de saldo](/documentation/guides/INSS/inquiries/offline-balance-request)** — últimos dados de saldo salvos, de forma síncrona.
- **[Recálculo](/documentation/guides/INSS/new-credit-and-refinancing/recalculate)** — ajusta parcela e taxa de uma operação existente.
- **[Enumeradores](/documentation/guides/INSS/reference/enumeradores)** — retornos da Dataprev, status e tipos de benefício.
- **[Mocks (Sandbox)](/documentation/guides/INSS/mocks-sandbox)** — CPFs e cenários de teste.

## Aceleradores da averbação

- **[Fila prioritária](/documentation/guides/INSS/reservations/priority-reservation)** — marca a reserva como `fixed_rate`.
- **[Fura-fila](/documentation/guides/INSS/reservations/priority-request)** — averbação síncrona consumindo ficha do balde.
- **[Anuência](/documentation/guides/INSS/pending_confirmation)** — quando o beneficiário precisa confirmar a operação.
- **[Assinatura em grupo](/documentation/guides/INSS/signatures/batch-group-signature)** — uma assinatura para várias operações do mesmo beneficiário.

---

# Envio de Documentos e Formalização

URL: /documentation/guides/INSS/new-credit-and-refinancing/formalizacao

Envio de Documentos e Formalização

Envio dos dados complementares exigidos pela IN 138 do INSS e formalização da operação (assinatura da CCB). Depois da formalização, a operação entra na fila de [averbação](/documentation/guides/INSS/reservations/averbacao-e-desaverbacao).

## Envio de documentos

É obrigatório o envio (segundo IN 138 do INSS) dos dados complementares do contrato.

Os documentos devem ser enviados através do [endpoint de upload de documentos](/documentation/upload_de_documentos/upload_de_documentos) e devem seguir a seguinte formatação:

| Validações     | Valores      |
|----------------|--------------|
| Formato        | JPEG         |
| Tamanho mínimo | 250 x 250 px |
| Tamanho máximo |     2 MB     |

:::caution Atenção
Contratos que tiverem documentos vinculados que não respeitam as regras de tamanho mínimo ou máximo serão cancelados permanentemente.
:::

Após o upload dos documentos, as chaves dos documentos enviados devem ser informadas no payload de criação da operação ou após, através do seguinte endpoint:

ENDPOINT /debt/ DEBT-KEY /related_party/ RELATED-PARTY-KEY /attached_document
MÉTODO POST

Testar no Playground

Request Body

```json
{
    "document_identification": "2893fc74-88fd-4cc9-a5c6-8a63d9d00f41",
    "document_identification_back": "e881ddf4-bc9a-48e0-9555-cac979f65431",
    "selfie": "ca37979e-6f11-4465-bf3b-69cd8307549c"
}
```

:::info Informação
A **related_party_key** é retornada na response da criação de dívida dentro do objeto **borrower**
:::

## Formalização da operação

Após o input dos documentos a operação pode seguir para formalização.

No caso de assinatura por parte do representante legal, no campo "**data.contract.signers[i]**" serão retornados os dados do representante legal, e o valor do objeto "**data.contract.signers[i].signer_role**" será "**issuer_legal_representative**".

**No payload de assinatura devem conter os campos obrigatórios relacionados aos documentos enviados no item 5. Os campos obrigatórios são os seguintes: _ip_address_ e _signature_datetime_.**

### Request

ENDPOINT /debt/ DEBT-KEY /signed
MÉTODO POST

Testar no Playground

Request Body

```json
{
	...,
	"ip_address": "192.168.0.0",
	"signature_datetime": "2020-03-20T14:28:23.382748Z",
	"similarity_score": 0.98000,
    "biometry_analysis_reference": "serpro",
	"type": "data-signature"
}
```

:::caution Atenção
O payload de envio da assinatura varia de acordo com o processo de formalização do parceiro e deve ser alinhado com o time de integração da QI Tech.
:::

### Enumeradores _Biometry Analysis Reference_
| Enumerador    | Descrição                                                                                                                                                                                                                                                          |
|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **serpro**    | Utilizado quando o similarity_score for retornado através de consulta realizada na base de documentos com foto do Detran (Serviço prestado através da Serpro)                                                                                                      |
| **tse**       | Utilizado quando o similarity_score for retornado através de consulta realizada na base de documentos com foto do TSE                                                                                                                                              |
| **not_found** | Deve ser informado quando a biometria facial não for localizada em nenhuma das bases governamentais anteriores (serpro ou tse). Neste caso o similarity_score deve ser null ou o grau de similaridade da selfie com o documento oficial com foto, retornado pelo parceiro. |

:::danger QI Sign
A QI Tech oferece o serviço de assinatura que atende ao determinado pela IN 138. Com biometria facial e envio de documentos.

Para receber uma cotação consulte nosso time comercial:

comercial@qitech.com.br ou (11) 2339-4763
:::

### Response

ENDPOINT /debt/ DEBT-KEY /signed
MÉTODO POST

Response Body

```json
{
  "data": {},
    "event_datetime": "2022-11-07 15:24:47",
    "key": "<DEBT-KEY>",
    "status": "signature_received",
    "webhook_type": "debt"
}
```

  Após o recebimento da assinatura, uma validação dos documentos enviados e do campo assistance type será feita.
  
  Caso seja enviado um tipo de benefício [(assistance_type)](/documentation/guides/INSS/reference/enumeradores#benefit_type_enumerator) que não esteja mapeado, a operação será cancelada permanentemente.
  
  O mesmo vale para as validações de documentos, caso haja duplicidade, falta ou documentos fora dos padrões mínimos exigidos, a operação será cancelada permanente.

  Em ambos os casos, um webhook será enviado com o seguinte payload:

WEBHOOK_TYPE debt
STATUS Canceled Permanently

Webhook Body

```json
{
	"key": "<DEBT-KEY>",
	"data": {},
	"status": "canceled_permanently",
	"webhook_type": "debt",
	"event_datetime": "2022-11-01 03:46:31"
}
```

---

# Falha no Desembolso e Reapresentação

URL: /documentation/guides/INSS/new-credit-and-refinancing/pos-desembolso

Falha no Desembolso e Reapresentação

O que acontece quando o desembolso falha (TED ou Pix) e como reapresentar o pagamento com novos dados bancários.

## TED

Em caso de falha no desembolso via TED

WEBHOOK_TYPE debt
STATUS canceled
Webhook Body

```json
 {
 	"status": "canceled",
 	"key": "<DEBT-KEY>",
 	"data": {
 		"ted_refusal": {
 			"transaction_key": "16faabfc-3876-437d-a4f6-aae17a1d68c9",
 			"description": "341 0000 000000-7 12345678900 - NOME BENEFICIÁRIO",
 			"origin": {
 				"account_key": "a1d2dea5-fa90-4676-a125-da355fdc3ed0",
 				"account_number": "00086",
 				"bank_code": "329",
 				"name": "ACCOUNT TRANSITORY",
 				"type": "payment_account",
 				"document": "32402502000135",
 				"branch_digit": null,
 				"account_digit": "8",
 				"branch": "0001"
 			},
 			"fee": 0,
 			"reason_enumerator": "agencia_conta_invalida",
 			"timestamp": "2022-11-07T14:36:05",
 			"amount": 483.6,
 			"reason": "Agência ou Conta Destinatária do Crédito Inválida",
 			"destination": {
 				"branch": "0000",
 				"account_number": "000000",
 				"name": "NOME BENEFICIÁRIO",
 				"purpose": "Crédito em Conta",
 				"type": "checking_account",
 				"branch_digit": null,
 				"document": "12345678900",
 				"bank_code": "341",
 				"account_digit": "7"
 			}
 		},
 		"cancel_reason": "ted_refusal"
 	}
 }
```

## Pix

Em caso de falha no desembolso via Pix

WEBHOOK_TYPE debt
STATUS canceled
Webhook Body

```json
{
        "webhook_type": "debt",
        "data": {
          "pix_refusal": {
            "reason": "Número da conta de destino é inexistente ou inválido.",
            "reason_enumerator": "invalid_account",
            "cancel_reason_enumerator": "invalid_account"
          },
          "cancel_reason": "pix_refusal",
          "cancel_reason_enumerator": "pix_refusal"
        },
        "status": "canceled",
        "key": "<DEBT-KEY>",
        "event_datetime": "2025-09-04 15:29:37"
      }
```

## Reapresentação de Pagamento

Altera a data de desembolso sem afetar os valores financeiros da operação.

### Request

ENDPOINT /debt/ DEBT-KEY /change_disbursement_date
MÉTODO POST

Testar no Playground

Request Body

```json
{
    "disbursement_date": "2022-11-04",
    "disbursement_bank_accounts": [
        {
            "branch_number": "1232",
            "account_digit": "4",
            "account_number": "412412412",
            "account_type": "checking_account",
            "document_number": "14950479032",
            "bank_code": 184,
            "ispb_number": "17298092",
            "name": "Maria da Silva",
            "percentage_receivable": 100
        }
    ]
}
```
 

### Response

ENDPOINT /debt/ DEBT-KEY /change_disbursement_date
MÉTODO POST

Response Body

```json
{
    "disbursement_accounts": [
        {
            "account_branch": "1232",
            "account_digit": "4",
            "account_number": "412412412",
            "account_type": "checking_account",
            "amount_receivable": null,
            "created_at": "2022-05-24T14:51:46",
            "digitable_line": null,
            "disbursement_type": "ted",
            "document_number": "37197645832",
            "financial_institutions": {
                "code_number": 184,
                "ispb": 17298092,
                "name": "BCO ITAÚ BBA S.A."
            },
            "financial_institutions_code_number": 184,
            "is_pix_disbursement": false,
            "ispb": "17298092",
            "name": "Márcio e Catarina Gráfica Ltda",
            "percentage_receivable": 50.0,
            "pix_key": null,
            "pix_transfer_key": null,
            "pix_type": null,
            "qr_code_key": null,
            "retry_counter": 0,
            "retry_vector": null,
            "transaction_key": null,
            "webhook_key": null
        }
    ],
    "disbursement_date": "2022-11-04"
}
```

---

![Competence Diagram](@site/static/img/imagem_manual_credito_novo_inss.webp)

---

# Recálculo

URL: /documentation/guides/INSS/new-credit-and-refinancing/recalculate

Recálculo

Recalcula as condições financeiras de uma operação de crédito existente a partir de um **novo valor de parcela**. Ideal para quando a margem consignável do beneficiário muda e o valor da parcela precisa ser ajustado.

## Request

ENDPOINT /v2/credit_operation/ CREDIT_OPERATION_KEY /recalculate
MÉTODO POST

### Path Params

credit_operation_key
string (UUID)
obrigatório
Chave única da operação de crédito a ser recalculada.

### Body Params

installment_face_value
number
obrigatório
Novo valor de face da parcela. Deve ser menor ou igual ao valor original e acima do mínimo permitido (20.00).

```python
{
    "installment_face_value": 180.50
}
```

:::caution Atenção
O novo `installment_face_value` precisa ser **menor** que o valor original. O endpoint rejeita valores superiores ao original ou fora da redução máxima permitida (30%).
:::

### Pré-condições

A operação deve atender **todas** as condições abaixo para ser recalculada:

| Condição | Erro se não atendida |
|----------|----------------------|
| Operação existe | [`COP000027`](#COP000027) (404) |
| Requisitante é dono da operação | [`QIT000005`](#QIT000005) (403) |
| Garantia do tipo `social_security` | [`COP000276`](#COP000276) |
| Status: `waiting_signature`, `issued` ou `canceled` | [`COP000489`](#COP000489) |
| Garantia ainda não constituída | [`COP000489`](#COP000489) |
| Tipo de operação: `structured_operation` | [`COP000489`](#COP000489) |
| Data limite de desembolso não expirada | [`COP000489`](#COP000489) |
| Operação original possui `installment_face_value` | [`COP000489`](#COP000489) |
| Novo valor dentro dos limites permitidos | [`COP000490`](#COP000490) |

## Response

STATUS 200

Retorna o objeto completo da operação de crédito recalculada — mesma estrutura da [consulta por credit_operation_key](/documentation/emissao_de_divida/consulta_por_credit_operation_key).

## Erros

| Código HTTP | Código QI | Descrição | Tradução |
|-------------|-----------|-----------|----------|
| 404 | <span id="COP000027">`COP000027`</span> | Credit Operation not found | Operação não encontrada |
| 403 | <span id="QIT000005">`QIT000005`</span> | Selected agent does not own this item | O agente selecionado não é dono do item |
| 400 | <span id="COP000276">`COP000276`</span> | Collateral type doesn't allow recalculation | Garantia do contrato não permite que a operação seja recalculada |
| 400 | <span id="COP000335">`COP000335`</span> | Assignment amount exceeds operation final amount | O valor de cessão é superior ao valor final da operação |
| 400 | <span id="COP000339">`COP000339`</span> | Final disbursement amount cannot be negative | O valor de desembolso final não pode ser negativo |
| 400 | <span id="COP000489">`COP000489`</span> | Operation not allowed to be recalculated | A operação de crédito não está permitida para ser recalculada |
| 400 | <span id="COP000490">`COP000490`</span> | Installment face value variance not allowed | A variação do valor da parcela não está permitida |

Motivos detalhados do erro COP000489

O código `COP000489` é retornado para diferentes pré-condições não atendidas. O campo `reason` na resposta indica o motivo específico:

| Motivo | Descrição |
|--------|-----------|
| Status inválido | O status da operação de crédito não permite ser recalculada |
| Garantia já constituída | A operação de crédito já possui garantia constituída |
| Tipo de operação inválido | O tipo de operação de crédito não permite ser recalculada |
| Data de desembolso expirada | A data de término do desembolso da operação de crédito está no passado |
| Valor de parcela ausente | O valor da parcela não foi informado na operação original |

---

# Simulação da Dívida

URL: /documentation/guides/INSS/new-credit-and-refinancing/simulacao

Simulação da Dívida

Simula os valores da operação antes da emissão — crédito novo ou refinanciamento puro — sem criar reserva de margem nem exigir os dados cadastrais completos do beneficiário.

Próximo passo: [Emissão da Operação](/documentation/guides/INSS/new-credit-and-refinancing/emissao).

## Request crédito novo

ENDPOINT /debt_simulation
MÉTODO POST

Testar no Playground

**Valor de parcela**

```json title='Request Body'
{
    "borrower": {
        "person_type": "natural"
    },
    "financial": {
        "first_due_date": "2024-12-07",
        "installment_face_value": 100,
        "disbursement_date": "2024-11-05",
        "limit_days_to_disburse": 3,
        "number_of_installments": 4,
        "monthly_interest_rate": 0.018,
        "interest_type": "pre_price_days",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0
    },
    "collaterals": [
        {
            "collateral_type": "social_security"
        }
    ]
}
```

**Valor desembolsado**

```json title='Request Body'
{
    "borrower": {
        "person_type": "natural"
    },
    "financial": {
        "first_due_date": "2024-12-07",
        "disbursed_amount": 1000,
        "disbursement_date": "2024-11-05",
        "limit_days_to_disburse": 3,
        "number_of_installments": 4,
        "monthly_interest_rate": 0.018,
        "interest_type": "pre_price_days",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0
    },
    "collaterals": [
        {
            "collateral_type": "social_security"
        }
    ]
}
```

    

## Request refinanciamento

ENDPOINT /debt_simulation
MÉTODO POST

**Valor de Parcela**

```json
{
    "borrower": {
        "person_type": "natural"
    },
    "financial": {
        "first_due_date": "2024-12-07",
        "installment_face_value": 100,
        "disbursement_date": "2024-11-05",
        "limit_days_to_disburse": 3,
        "number_of_installments": 4,
        "monthly_interest_rate": 0.018,
        "interest_type": "pre_price_days",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0
    },
    "collaterals": [
        {
            "collateral_type": "social_security"
        }
    ],
    "refinanced_credit_operations": [
        {
            "operation_key": "324caa35-ba10-4590-ae2b-5efef71709c3"
        }
    ]
}
```
  

**Valor desembolsado**

```json
{
    "borrower": {
        "person_type": "natural"
    },
    "financial": {
        "first_due_date": "2024-12-07",
        "disbursed_amount": 1000,
        "disbursement_date": "2024-11-05",
        "limit_days_to_disburse": 3,
        "number_of_installments": 4,
        "monthly_interest_rate": 0.018,
        "interest_type": "pre_price_days",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0
    },
    "collaterals": [
        {
            "collateral_type": "social_security"
        }
    ],
    "refinanced_credit_operations": [
        {
            "operation_key": "324caa35-ba10-4590-ae2b-5efef71709c3"
        }
    ]
}
```

:::info
Na request acima existem 2 simulações sendo realizadas. A primeira está fixando o valor de parcela ao cliente (varia o valor desembolsado) e a segunda, esta fixando o valor desembolsado (varia o valor desembolsado).
::: 

## Response

ENDPOINT /debt_simulation
MÉTODO POST

Response Body

```json
{
    "type": "debt",
    "key": "8f01672d-9910-43a6-9e7d-07c031bc6fed",
    "status": "finished",
    "event_datetime": "2024-11-05 16:50:00",
    "data": {
        "interest_type": "pre_price_days",
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "interest_payment_month_period": 1,
        "principal_grace_period": 0,
        "principal_amortization_month_period": 1,
        "operation_type": "structured_operation",
        "post_fixed_interest_base": "workdays",
        "post_fixed_interest_rate": null,
        "prefixed_interest_rate": {
            "interest_base": "calendar_days_365",
            "annual_rate": 0.23872053,
            "monthly_rate": 0.018,
            "daily_rate": 0.00058669
        },
        "issue_date": "2024-11-05",
        "number_of_installments": 4,
        "requester_key": "e5eb6a0a-e003-4cbd-b702-5a25bf71af0a",
        "final_disbursement_amount": 0.0,
        "disbursement_options": [
            {
                "iof_amount": 3.93,
                "total_pre_fixed_amount": 17.8715883143,
                "cet": 0.0257,
                "annual_cet": 0.355163,
                "contract_fees": [
                    {
                        "fee_type": "tac",
                        "amount_type": "percentage",
                        "amount": 0.6,
                        "fee_amount": 2.29
                    },
                    {
                        "fee_type": "ted_fee",
                        "amount_type": "absolute",
                        "amount": 1.0,
                        "fee_amount": 1.0
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "insurance_premium",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "tac",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    }
                ],
                "contract_fee_amount": 2.29,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "disbursement_date": "2024-11-05",
                "first_due_date": "2024-12-09",
                "installments": [
                    {
                        "calendar_days": 34,
                        "workdays": 23.0,
                        "business_due_date": "2024-12-09",
                        "due_date": "2024-12-09",
                        "due_principal": 382.13,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 7.6967422515,
                        "tax_amount": 0.257341482602818,
                        "total_amount": 100,
                        "principal_amortization_amount": 92.3032577485,
                        "installment_number": 1
                    },
                    {
                        "calendar_days": 29,
                        "workdays": 19.0,
                        "business_due_date": "2025-01-07",
                        "due_date": "2025-01-07",
                        "due_principal": 289.8267422515,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 4.9718040699,
                        "tax_amount": 0.4909156601748966,
                        "total_amount": 100,
                        "principal_amortization_amount": 95.0281959301,
                        "installment_number": 2
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 23.0,
                        "business_due_date": "2025-02-07",
                        "due_date": "2025-02-07",
                        "due_principal": 194.7985463214,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.5742034136,
                        "tax_amount": 0.7432500400879712,
                        "total_amount": 100,
                        "principal_amortization_amount": 96.4257965864,
                        "installment_number": 3
                    },
                    {
                        "calendar_days": 28,
                        "workdays": 18.0,
                        "business_due_date": "2025-03-07",
                        "due_date": "2025-03-07",
                        "due_principal": 98.372749735,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.6288385793,
                        "tax_amount": 0.9841050988526828,
                        "total_amount": 100,
                        "principal_amortization_amount": 98.3711614207,
                        "installment_number": 4
                    }
                ],
                "issue_amount": 382.13,
                "disbursed_issue_amount": 374.91,
                "assignment_amount": 382.13,
                "final_disbursement_amount": 374.91,
                "prefixed_interest_rate": {
                    "interest_base": "calendar_days_365",
                    "annual_rate": 0.23872053,
                    "monthly_rate": 0.018,
                    "daily_rate": 0.00058669
                }
            },
            {
                "iof_amount": 4.77,
                "total_pre_fixed_amount": 24.2597288075,
                "cet": 0.0243,
                "annual_cet": 0.334037,
                "contract_fees": [
                    {
                        "fee_type": "tac",
                        "amount_type": "percentage",
                        "amount": 0.6,
                        "fee_amount": 2.25
                    },
                    {
                        "fee_type": "ted_fee",
                        "amount_type": "absolute",
                        "amount": 1.0,
                        "fee_amount": 1.0
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "insurance_premium",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "tac",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    }
                ],
                "contract_fee_amount": 2.25,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "disbursement_date": "2024-11-06",
                "first_due_date": "2025-01-07",
                "installments": [
                    {
                        "calendar_days": 62,
                        "workdays": 41.0,
                        "business_due_date": "2025-01-07",
                        "due_date": "2025-01-07",
                        "due_principal": 375.74,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 13.9149280115,
                        "tax_amount": 0.437656505989534,
                        "total_amount": 100,
                        "principal_amortization_amount": 86.0850719885,
                        "installment_number": 1
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 23.0,
                        "business_due_date": "2025-02-07",
                        "due_date": "2025-02-07",
                        "due_principal": 289.6549280115,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 5.3146959395,
                        "tax_amount": 0.722070128765373,
                        "total_amount": 100,
                        "principal_amortization_amount": 94.6853040605,
                        "installment_number": 2
                    },
                    {
                        "calendar_days": 28,
                        "workdays": 18.0,
                        "business_due_date": "2025-03-07",
                        "due_date": "2025-03-07",
                        "due_principal": 194.969623951,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.2283291407,
                        "tax_amount": 0.9601685182659746,
                        "total_amount": 100,
                        "principal_amortization_amount": 96.7716708593,
                        "installment_number": 3
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 21.0,
                        "business_due_date": "2025-04-07",
                        "due_date": "2025-04-07",
                        "due_principal": 98.1979530917,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.8017757158,
                        "tax_amount": 1.2239426674782687,
                        "total_amount": 100,
                        "principal_amortization_amount": 98.1982242842,
                        "installment_number": 4
                    }
                ],
                "issue_amount": 375.74,
                "disbursed_issue_amount": 367.72,
                "assignment_amount": 375.74,
                "final_disbursement_amount": 367.72,
                "prefixed_interest_rate": {
                    "interest_base": "calendar_days_365",
                    "annual_rate": 0.23872053,
                    "monthly_rate": 0.018,
                    "daily_rate": 0.00058669
                }
            },
            {
                "iof_amount": 4.74,
                "total_pre_fixed_amount": 24.0392857898,
                "cet": 0.0243,
                "annual_cet": 0.334673,
                "contract_fees": [
                    {
                        "fee_type": "tac",
                        "amount_type": "percentage",
                        "amount": 0.6,
                        "fee_amount": 2.26
                    },
                    {
                        "fee_type": "ted_fee",
                        "amount_type": "absolute",
                        "amount": 1.0,
                        "fee_amount": 1.0
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "insurance_premium",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "tac",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    }
                ],
                "contract_fee_amount": 2.26,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "disbursement_date": "2024-11-07",
                "first_due_date": "2025-01-07",
                "installments": [
                    {
                        "calendar_days": 61,
                        "workdays": 40.0,
                        "business_due_date": "2025-01-07",
                        "due_date": "2025-01-07",
                        "due_principal": 375.96,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 13.6944849939,
                        "tax_amount": 0.4317001860605122,
                        "total_amount": 100,
                        "principal_amortization_amount": 86.3055150061,
                        "installment_number": 1
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 23.0,
                        "business_due_date": "2025-02-07",
                        "due_date": "2025-02-07",
                        "due_principal": 289.6544849939,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 5.3146959395,
                        "tax_amount": 0.714305933832412,
                        "total_amount": 100,
                        "principal_amortization_amount": 94.6853040605,
                        "installment_number": 2
                    },
                    {
                        "calendar_days": 28,
                        "workdays": 18.0,
                        "business_due_date": "2025-03-07",
                        "due_date": "2025-03-07",
                        "due_principal": 194.9691809334,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.2283291407,
                        "tax_amount": 0.952233241255512,
                        "total_amount": 100,
                        "principal_amortization_amount": 96.7716708593,
                        "installment_number": 3
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 21.0,
                        "business_due_date": "2025-04-07",
                        "due_date": "2025-04-07",
                        "due_principal": 98.1975100741,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.8017757157,
                        "tax_amount": 1.2158904130882027,
                        "total_amount": 100,
                        "principal_amortization_amount": 98.1982242843,
                        "installment_number": 4
                    }
                ],
                "issue_amount": 375.96,
                "disbursed_issue_amount": 367.96,
                "assignment_amount": 375.96,
                "final_disbursement_amount": 367.96,
                "prefixed_interest_rate": {
                    "interest_base": "calendar_days_365",
                    "annual_rate": 0.23872053,
                    "monthly_rate": 0.018,
                    "daily_rate": 0.00058669
                }
            },
            {
                "iof_amount": 4.71,
                "total_pre_fixed_amount": 23.8187134405,
                "cet": 0.0244,
                "annual_cet": 0.335196,
                "contract_fees": [
                    {
                        "fee_type": "tac",
                        "amount_type": "percentage",
                        "amount": 0.6,
                        "fee_amount": 2.26
                    },
                    {
                        "fee_type": "ted_fee",
                        "amount_type": "absolute",
                        "amount": 1.0,
                        "fee_amount": 1.0
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "insurance_premium",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "tac",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    }
                ],
                "contract_fee_amount": 2.26,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "disbursement_date": "2024-11-08",
                "first_due_date": "2025-01-07",
                "installments": [
                    {
                        "calendar_days": 60,
                        "workdays": 39.0,
                        "business_due_date": "2025-01-07",
                        "due_date": "2025-01-07",
                        "due_principal": 376.18,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 13.4739126445,
                        "tax_amount": 0.42570834978906,
                        "total_amount": 100,
                        "principal_amortization_amount": 86.5260873555,
                        "installment_number": 1
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 23.0,
                        "business_due_date": "2025-02-07",
                        "due_date": "2025-02-07",
                        "due_principal": 289.6539126445,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 5.3146959395,
                        "tax_amount": 0.706541738899451,
                        "total_amount": 100,
                        "principal_amortization_amount": 94.6853040605,
                        "installment_number": 2
                    },
                    {
                        "calendar_days": 28,
                        "workdays": 18.0,
                        "business_due_date": "2025-03-07",
                        "due_date": "2025-03-07",
                        "due_principal": 194.968608584,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.2283291407,
                        "tax_amount": 0.9442979642450494,
                        "total_amount": 100,
                        "principal_amortization_amount": 96.7716708593,
                        "installment_number": 3
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 21.0,
                        "business_due_date": "2025-04-07",
                        "due_date": "2025-04-07",
                        "due_principal": 98.1969377247,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.8017757158,
                        "tax_amount": 1.20783815869566,
                        "total_amount": 100,
                        "principal_amortization_amount": 98.1982242842,
                        "installment_number": 4
                    }
                ],
                "issue_amount": 376.18,
                "disbursed_issue_amount": 368.21,
                "assignment_amount": 376.18,
                "final_disbursement_amount": 368.21,
                "prefixed_interest_rate": {
                    "interest_base": "calendar_days_365",
                    "annual_rate": 0.23872053,
                    "monthly_rate": 0.018,
                    "daily_rate": 0.00058669
                }
            }
        ]
    }
}
```

---

# Anuência (pending confirmation)

URL: /documentation/guides/INSS/pending_confirmation

Anuência (pending confirmation)

Após a averbação, a reserva entra em **`pending_confirmation`** aguardando a confirmação do beneficiário no INSS. A QI Tech notifica o parceiro via webhook e segue consultando a Dataprev até a confirmação, recusa ou expiração do prazo.

:::info Escopo
Aplica-se a **crédito novo** e **refinanciamento**. **Portabilidade não exige anuência.**
:::

:::tip Vigência
**19/05/2026 às 06:00.** Mapeie o novo webhook para acionar o beneficiário com agilidade.
:::

## Fluxo

- Averbação bem-sucedida → reserva entra em `pending_confirmation`.
- QI Tech envia o webhook `laas.social_security.reservation.status_change` e dispara SMS ao beneficiário.
- Consulta à Dataprev **a cada 3 horas**; **cada consulta redispara o webhook**.
- SMS adicional ao beneficiário **uma vez por dia** enquanto a operação estiver pendente.
- **Prazo máximo:** 5 dias corridos. Se expirar ou for recusada, ocorre **desaverbação** automática.

| Desfecho | Webhook |
|---|---|
| Beneficiário confirma | `credit_operation.collateral` com `collateral_constituted: true` |
| Beneficiário recusa | `debt` / `canceled` — `social_security_confirmation_denied_by_beneficiary` |
| Prazo expira | `debt` / `canceled` — `social_security_confirmation_expired` |

## Webhook — anuência pendente

WEBHOOK_TYPE laas.social_security.reservation.status_change
STATUS pending_confirmation

```json
{
  "key": "<CREDIT-OPERATION-KEY>",
  "webhook_type": "laas.social_security.reservation.status_change",
  "status": "pending_confirmation",
  "event_datetime": "2026-05-19 06:15:00",
  "data": {
      "confirmation_deadline": "2026-05-20T14:25:03Z"
  }
}
```

## Webhook — anuência concluída

Mesmo webhook de averbação já existente. Veja [Sucesso na averbação](/documentation/guides/INSS/new-credit-and-refinancing/end-to-end#sucesso-na-averbação).

WEBHOOK_TYPE credit_operation.collateral

```json
{
  "key": "<CREDIT-OPERATION-KEY>",
  "data": {
    "collateral_type": "social_security",
    "collateral_constituted": true
  },
  "event_time": "2026-05-19 12:42:00",
  "webhook_type": "credit_operation.collateral"
}
```

## Webhook — recusa ou expiração

Mesmo webhook de cancelamento já existente, distinguindo o motivo via `cancel_reason_enumerator`:

| Enumerador | Quando |
|---|---|
| `social_security_confirmation_denied_by_beneficiary` | Beneficiário recusou a confirmação |
| `social_security_confirmation_expired` | Prazo de 5 dias expirou |

WEBHOOK_TYPE debt
STATUS canceled

```json
{
  "key": "<CREDIT-OPERATION-KEY>",
  "status": "canceled",
  "data": {
    "cancel_reason": "Beneficiário recusou a confirmação da reserva",
    "cancel_reason_enumerator": "social_security_confirmation_denied_by_beneficiary"
  },
  "webhook_type": "debt",
  "event_datetime": "2026-05-21 09:10:00"
}
```

## Testando em sandbox

Em sandbox o desfecho da anuência é simulado pelo **último dígito do número do benefício** — terminados em `0`, `1`, `3`, `5` ou `6` confirmam automaticamente; `9` recusa; `7` expira; `8`, `2` e `4` permanecem pendentes. Tabela completa em [Mocks (Sandbox)](/documentation/guides/INSS/mocks-sandbox#anuencia).

## Forçar consulta imediata (Fura-fila)

O [Fura-fila](/documentation/guides/INSS/reservations/priority-request) passa a aceitar reservas em `pending_confirmation`, forçando uma consulta imediata à Dataprev.

:::warning Consumo de ficha
Se a reserva **ainda não tiver sido confirmada**, retorna `ReservationFailed` com `last_response = confirmation_still_pending` e **consome uma ficha** do balde. Ajuste sua lógica de retentativas.
:::

---

# Alterando o Cessionário

URL: /documentation/guides/INSS/portability+refinancing/alterando-cessionario

Alterando o Cessionário

Em uma operação de Portabilidade + Refinanciamento, é possível definir um cessionário diferente do padrão no momento de aceite do refinanciamento. Isso é feito por meio do campo `purchaser_document_number` no corpo da requisição de aceite.

## Endpoint de Aceite

O cessionário é configurado ao aceitar a operação de refinanciamento (Troco) via:

- MÉTODO POST
- ENDPOINT /v2/credit_transfer/proposal/**\{proposal_key\}**/refinancing_credit_operation/acceptance

Consulte o [Fluxo Completo](./end-to-end) para o contexto completo da chamada de aceite, incluindo os demais campos obrigatórios.

## Campo `purchaser_document_number`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `purchaser_document_number` | string | Opcional | CNPJ (14 dígitos) do cessionário a ser utilizado nesta operação. Sobrescreve o cessionário padrão do parceiro. |

:::info
Se o campo `purchaser_document_number` for omitido, a operação utilizará o cessionário padrão configurado para o parceiro na QI Tech.
:::

:::caution
O campo `purchaser_document_number` só pode ser definido no momento do aceite (POST). Não é possível alterá-lo posteriormente via endpoints de correção (PUT).
:::

## Exemplo de Request Body

O exemplo abaixo destaca o uso do campo `purchaser_document_number` junto aos campos `financial` e `disbursement_bank_accounts`:

```json
{
    "financial": {
        "installment_face_value": 379.87,
        "monthly_interest_rate": 0.0166,
        "number_of_installments": 84,
        "limit_days_to_disburse": 7,
        "disbursement_date": "2024-07-02",
        "rebates": []
    },
    "disbursement_bank_accounts": [
        {
            "document_number": "92093764000197",
            "branch_number": "0001",
            "name": "TESTE LTDA",
            "percentage_receivable": 100,
            "account_number": "120012",
            "account_digit": "3",
            "bank_code": "329"
        }
    ],
    "purchaser_document_number": "28534595027164"
}
```

O campo `purchaser_document_number` deve conter o CNPJ do cessionário desejado, com 14 dígitos numéricos sem formatação.

---

# Consultas e Enumeradores

URL: /documentation/guides/INSS/portability+refinancing/consultas-e-enumeradores

Consultas e Enumeradores

Os endpoints auxiliares e as tabelas de referência desta página foram reorganizados por família, para
que a mesma consulta não seja documentada duas vezes — uma por jornada.

| O que estava aqui | Onde está agora |
|---|---|
| Consulta de Lista de Participantes do CTC - CIP | [Lista de participantes do CTC](/documentation/guides/INSS/inquiries/participantes-ctc) |
| Recuperar resposta da última request | [Última resposta da averbação](/documentation/guides/INSS/inquiries/ultima-resposta) |
| Webhook de resposta da última tentativa de averbação | [Última resposta da averbação](/documentation/guides/INSS/inquiries/ultima-resposta#webhook-da-ultima-tentativa-de-averbacao) |
| Consulta de portabilidade de origem | [Consulta de portabilidade de origem](/documentation/guides/INSS/inquiries/portabilidade-de-origem) |
| Diminuir o valor das parcelas | [Diminuir o valor das parcelas](/documentation/guides/INSS/portability+refinancing/diminuir-parcela) |
| Mapeamento de enumeradores | [Enumeradores](/documentation/guides/INSS/reference/enumeradores) |

---

# Correção de Dados da Proposta

URL: /documentation/guides/INSS/portability+refinancing/correcao-de-dados

Correção de Dados da Proposta

Corrige os dados de uma proposta de portabilidade e/ou refinanciamento já criada, antes da averbação — com nova assinatura da CCB quando a correção altera as condições do refinanciamento, e sem nova assinatura quando não altera.

Para reduzir apenas o **valor da parcela**, veja [Diminuir o Valor das Parcelas](/documentation/guides/INSS/portability+refinancing/diminuir-parcela). Para o recálculo do saldo devedor da portabilidade, veja [Recálculo da Portabilidade](/documentation/guides/INSS/portability+refinancing/recalculate-portability).

## Correção de dados para refinanciamento com nova assinatura da CCB:
É possível corrigir os dados financeiros e os bancários da operação de refinanciamento enquanto o refinanciamento original não for averbado.

ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /refinancing_credit_operation
MÉTODO PUT

Testar no Playground

Request Body

```json
{
    "financial": {
        "interest_type": "pre_price_days",
        "first_due_date": "2024-06-10",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "monthly_interest_rate": 0.0167,
        "installment_face_value": 410,
        "limit_days_to_disburse": 7,
        "number_of_installments": 84
		},
    "disbursement_bank_account": {
        "account_digit": "1",
        "account_number": "00001",
        "bank_code": "033",
        "branch_number": "0001"
    }
}

```

        *Response:*

**response.json**

```json

{
	"credit_operation_key": "<CREDIT-OPERATION-KEY>",
	"contract_number": "00000002",
	"document_key": "<DOCUMENT-KEY da CCB de Refinanciamento>",
	"document_url": "<URL da CCB de Refinanciamento>",
	"credit_operation_status": "issued",
	"fine_configuration": {
		"contract_fine_rate": 0.02,
		"interest_base": "calendar_days",
		"monthly_rate": 0.01
	},
	"disbursement_options": [{
		"installments": [{
				"additional_costs": [],
				"bank_slip_key": null,
				"business_due_date": "2021-08-09",
				"calendar_days": 53,
				"digitable_line": null,
				"due_date": "2021-08-08",
				"due_interest": 0,
				"due_principal": 997.87,
				"fine_amount": null,
				"has_interest": true,
				"installment_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036",
				"installment_number": 1,
				"installment_status": "created",
				"installment_type": "principal",
				"paid_amount": 0,
				"paid_at": null,
				"post_fixed_amount": 0,
				"pre_fixed_amount": 54.84865004983954,
				"principal_amortization_amount": 306.98134995016045,
				"total_amount": 361.83,
				"workdays": 37
			},
			{
				"additional_costs": [],
				"bank_slip_key": null,
				"business_due_date": "2021-09-08",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2021-09-08",
				"due_interest": 0,
				"due_principal": 690.8886500498395,
				"fine_amount": null,
				"has_interest": true,
				"installment_key": "e8406cdb-844c-4e6d-9620-3635fab9d8d1",
				"installment_number": 2,
				"installment_status": "created",
				"installment_type": "principal",
				"paid_amount": 0,
				"paid_at": null,
				"post_fixed_amount": 0,
				"pre_fixed_amount": 21.964874249804833,
				"principal_amortization_amount": 339.86512575019515,
				"tax_amount": 0,
				"total_amount": 361.83,
				"workdays": 22
			}
		],
		"prefixed_interest_rate": {
				"annual_rate": 0.44556431,
				"daily_rate": 0.00564312,
				"monthly_rate": 0.0556431,
				"interest_base": "calendar_days_365"
		},
		"iof_amount": 50,
		"external_contract_fee_amount": 0,
		"external_contract_fees": [],
		"contract_fee_amount": 0,
		"contract_fees": [],
		"number_of_installments": 2,
		"disbursed_issue_amount": 997.87,
		"final_disbursement_amount": 100,
		"issue_amount": 1147.87,
		"disbursement_date": "2021-05-31",
		"cet": 1.212,
		"annual_cet": 32.122
	}],
	"disbursement_bank_account": {
		"account_digit": "1",
		"account_number": "00001",
		"ispb": "00000000",
		"branch_number": "0001"
	}
}

```

:::caution 
A key da operação de refinanciamento, a document key, a document url, a related_party_key e a borrower related_party_key mudarão após essa ação, sendo necessário a reassinatura da CCB.
:::

## Correção de dados para refinanciamento:
É possível recalcular o valor da parcela da operação de refinanciamento sem gerar uma nova CCB. O novo valor de parcela deve ser menor que o valor original.

ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /refinancing_credit_operation/recalculate
MÉTODO PUT

Testar no Playground

Request Body

```json
{
    "financial": {
        "interest_type": "pre_price_days",
        "first_due_date": "2024-06-10",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "monthly_interest_rate": 0.0167,
        "installment_face_value": 410,
        "limit_days_to_disburse": 7,
        "number_of_installments": 84
		},
    "disbursement_bank_account": {
        "account_digit": "1",
        "account_number": "00001",
        "bank_code": "033",
        "branch_number": "0001"
    }
}

```

        *Response:*

**response.json**

```json

{
	"credit_operation_key": "<CREDIT-OPERATION-KEY>",
	"contract_number": "00000002",
	"document_key": "<DOCUMENT-KEY da CCB de Refinanciamento>",
	"document_url": "<URL da CCB de Refinanciamento>",
	"credit_operation_status": "issued",
	"fine_configuration": {
		"contract_fine_rate": 0.02,
		"interest_base": "calendar_days",
		"monthly_rate": 0.01
	},
	"disbursement_options": [{
		"installments": [{
				"additional_costs": [],
				"bank_slip_key": null,
				"business_due_date": "2021-08-09",
				"calendar_days": 53,
				"digitable_line": null,
				"due_date": "2021-08-08",
				"due_interest": 0,
				"due_principal": 997.87,
				"fine_amount": null,
				"has_interest": true,
				"installment_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036",
				"installment_number": 1,
				"installment_status": "created",
				"installment_type": "principal",
				"paid_amount": 0,
				"paid_at": null,
				"post_fixed_amount": 0,
				"pre_fixed_amount": 54.84865004983954,
				"principal_amortization_amount": 306.98134995016045,
				"total_amount": 361.83,
				"workdays": 37
			},
			{
				"additional_costs": [],
				"bank_slip_key": null,
				"business_due_date": "2021-09-08",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2021-09-08",
				"due_interest": 0,
				"due_principal": 690.8886500498395,
				"fine_amount": null,
				"has_interest": true,
				"installment_key": "e8406cdb-844c-4e6d-9620-3635fab9d8d1",
				"installment_number": 2,
				"installment_status": "created",
				"installment_type": "principal",
				"paid_amount": 0,
				"paid_at": null,
				"post_fixed_amount": 0,
				"pre_fixed_amount": 21.964874249804833,
				"principal_amortization_amount": 339.86512575019515,
				"tax_amount": 0,
				"total_amount": 361.83,
				"workdays": 22
			}
		],
		"prefixed_interest_rate": {
				"annual_rate": 0.44556431,
				"daily_rate": 0.00564312,
				"monthly_rate": 0.0556431,
				"interest_base": "calendar_days_365"
		},
		"iof_amount": 50,
		"external_contract_fee_amount": 0,
		"external_contract_fees": [],
		"contract_fee_amount": 0,
		"contract_fees": [],
		"number_of_installments": 2,
		"disbursed_issue_amount": 997.87,
		"final_disbursement_amount": 100,
		"issue_amount": 1147.87,
		"disbursement_date": "2021-05-31",
		"cet": 1.212,
		"annual_cet": 32.122
	}],
	"disbursement_bank_account": {
		"account_digit": "1",
		"account_number": "00001",
		"ispb": "00000000",
		"branch_number": "0001"
	}
}

```

## Correção de dados para portabilidade e refin:
É possível corrigir os dados bancários, número do benefício e nome até que o contrato de portabilidade seja averbado. Tanto os dados do operação de portabilidade quanto do refinanciamento serão ajustados. Para isso basta utilizar a seguinte chamada:

ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /collateral
MÉTODO PATCH

Testar no Playground

Request Body

**Dados Bancários**

```json
{
	"disbursement_bank_account": {
		"bank_code": "123",
		"account_digit": "1",
		"account_branch": "1234",
		"account_number": "5678",
		"document_number": "12345678901"
	}
}

```
  
**Número do Benefício**

```json
{
	"benefit_number": 1234567890
}
```

**Nome**

```json
{
	"name": "Nome do Beneficiário"
}
```

**Nome da Mãe**

```json
{
	"mother_name": "Nome da Mãe do Beneficiário"
}
```

---

# Diminuir o Valor das Parcelas

URL: /documentation/guides/INSS/portability+refinancing/diminuir-parcela

Diminuir o Valor das Parcelas

Reduz o valor da parcela de uma proposta já criada, antes da averbação.

Este endpoint permite a redução do valor das parcelas de um contrato de portabilidade de crédito. Esta funcionalidade é especialmente útil em casos onde a margem consignável é excedida devido ao banco de origem desaverbar uma quantia menor do que a esperada.

        **Request**
- MÉTODO PUT
- ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /portability_credit_operation

        *Payload:*

**payload.json**

```json
{
    "installment_face_value": 382.18
}

```

        **Response sucesso - HTTP 200**

**body.json**

```json
{
        "credit_operation_key": "7aa77bca-c724-4c1a-bfae-9b1b7bd81ab2",
        "contract_number": "0000000007/WO",
        "document_key": "045a8f35-6170-4112-8d83-29a753d0c78e",
        "document_url": "http://teste.com",
        "signed_url": "signed_url_test",
        "credit_operation_status": "waiting_signature",
        "fine_configuration": {
            "contract_fine_rate": 0.02,
            "interest_base": "calendar_days",
            "monthly_rate": 0.01
        },
        "disbursement_accounts": [
            {
                "account_digit": "3",
                "account_branch": "0001",
                "account_number": "94134",
                "ispb": "32402502",
                "name": "Wilker Teste",
                "document_number": "37197645832"
            }
        ],
        "disbursement_options": [
            {
                "prefixed_interest_rate": {
                    "annual_rate": 3.0,
                    "daily_rate": 0.00385824,
                    "interest_base": "calendar_days",
                    "monthly_rate": 0.12246205
                },
                "total_iof": 7.03,
                "external_contract_fee_amount": 0.0,
                "external_contract_fees": [],
                "contract_fee_amount": 0.0,
                "number_of_installments": 3,
                "contract_fees": [],
                "disbursed_issue_amount": 1000.0,
                "issue_amount": 1007.03,
                "disbursement_date": "2022-08-24",
                "cet": 12.6,
                "annual_cet": 315.3944,
                "installments": [
                    {
                        "business_due_date": "2022-08-30",
                        "calendar_days": 5,
                        "due_date": "2022-08-29",
                        "due_principal": 1007.03,
                        "installment_number": 1,
                        "pre_fixed_amount": 84.43554587915118,
                        "principal_amortization_amount": 297.73445412084885,
                        "total_amount": 382.17,
                        "workdays": 3
                    },
                    {
                        "business_due_date": "2022-09-30",
                        "calendar_days": 31,
                        "due_date": "2022-09-29",
                        "due_principal": 709.2955458791512,
                        "installment_number": 2,
                        "pre_fixed_amount": 47.97894031795043,
                        "principal_amortization_amount": 334.19105968204957,
                        "total_amount": 382.17,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2022-11-01",
                        "calendar_days": 32,
                        "due_date": "2022-10-31",
                        "due_principal": 375.1044861971016,
                        "installment_number": 3,
                        "pre_fixed_amount": 7.055513802898396,
                        "principal_amortization_amount": 375.1044861971016,
                        "total_amount": 382.16,
                        "workdays": 21
                    }
                ],
                "final_disbursement_amount": 997.87
            }
        ],
        "final_disbursement_amount": 997.87,
        "collateral_is_constituted": false
    }
```

---

# Portabilidade + Refin

URL: /documentation/guides/INSS/portability+refinancing/end-to-end

Fluxo Completo - Portabilidade + Refinanciamento

Ordem das chamadas de uma portabilidade INSS, com ou sem o refinanciamento do Troco. Cada etapa tem a
sua própria página, com request, response, webhooks e cenários de sandbox.

## Fluxo

1. **[Consulta da lista de benefícios](/documentation/guides/INSS/inquiries/lista-de-beneficios)** — `POST /social_security/benefits_request`, com o Termo de Autorização assinado.
2. **[Consulta de dados do benefício](/documentation/guides/INSS/inquiries/dados-do-beneficio)** — `POST /social_security/balance_request`. Pré-requisito da averbação.
3. **[Simulação da proposta](/documentation/guides/INSS/portability+refinancing/simulacao)** — portabilidade e/ou refinanciamento, fixando taxa ou valor liberado.
4. **[Digitação da proposta](/documentation/guides/INSS/portability+refinancing/proposta)** — `POST /v2/credit_transfer/proposal` e recuperação dos dados da proposta.
5. **[Envio de documentos e formalização](/documentation/guides/INSS/portability+refinancing/formalizacao)** — dados complementares da IN 138 e assinatura.
6. **[Acompanhamento](/documentation/guides/INSS/portability+refinancing/maquinas-de-status)** — máquinas de status da portabilidade e do refinanciamento (Troco).

## Ajustes na proposta

- **[Correção de dados](/documentation/guides/INSS/portability+refinancing/correcao-de-dados)** — com ou sem nova assinatura da CCB.
- **[Recálculo e reformalização do refinanciamento](/documentation/guides/INSS/portability+refinancing/reformalization)** — corrige o refin e a carência.
- **[Recálculo da portabilidade](/documentation/guides/INSS/portability+refinancing/recalculate-portability)** — reduz o saldo devedor para caber na margem.
- **[Diminuir o valor das parcelas](/documentation/guides/INSS/portability+refinancing/diminuir-parcela)**.
- **[Alterando o cessionário](/documentation/guides/INSS/portability+refinancing/alterando-cessionario)** — `purchaser_document_number` no aceite.

## Consultas e referência

- **[Lista de participantes do CTC](/documentation/guides/INSS/inquiries/participantes-ctc)** — instituições participantes da Núclea/CIP.
- **[Consulta de portabilidade de origem](/documentation/guides/INSS/inquiries/portabilidade-de-origem)** — dados do contrato portado.
- **[Última resposta da averbação](/documentation/guides/INSS/inquiries/ultima-resposta)**.
- **[Enumeradores](/documentation/guides/INSS/reference/enumeradores)** — motivos de retenção, retornos da Dataprev e status.
- **[Mocks (Sandbox)](/documentation/guides/INSS/mocks-sandbox)**.

---

# Envio de Documentos e Formalização

URL: /documentation/guides/INSS/portability+refinancing/formalizacao

Envio de Documentos e Formalização

Envio dos dados complementares exigidos pela IN 138 do INSS e formalização da proposta de portabilidade e refinanciamento.

## Envio de documentos

Segundo IN 138 do INSS é obrigatório o envio dos dados complementares do contrato.

Os documentos devem ser enviados através do [endpoint de upload de documentos.](/documentation/upload_de_documentos/upload_de_documentos) e devem seguir a seguinte formatação:

| Validações     | Valores      |
|----------------|--------------|
| Formato        | JPEG         |
| Tamanho mínimo | 250 x 250 px |
| Tamanho máximo |     2 MB     |

:::caution Atenção
Contratos que tiverem documentos vinculados que não respeitam as regras de tamanho mínimo ou máximo serão cancelados permanentemente.
:::

Caso as validações não sejam atendidas, no momento que o parceiro seguir com a proposta após receber o saldo devedor, iremos devolver os seguintes erros :

**Ver exemplos de erro**

**Formato inválido**

```json
{
    "title": "Invalid document format",
    "description": "The document: document_identification_back should be in JPEG format.",
    "translation": "O documento: document_identification_back deve estar no formato JPEG.",
    "code": "SSC000061"
}
```
  
**Tamanho inválido**

```json
{
    "title": "Invalid document size",
    "description": "The document: document_identification_back should have at least 250x250px.",
    "translation": "O documento: document_identification_back deve ter no mínimo 250x250px.",
    "code": "SSC000060"
}
```

Após o upload de documentos, as chaves dos documentos enviados devem ser informadas no payload de criação da proposta no tópico anterior dentro do campo *borrower* ou dentro do objeto de *related_parties** correspondente ao representante legal (*"role_type": "issuer_legal_representative"*):

```json
{
    "document_identification": "2893fc74-88fd-4cc9-a5c6-8a63d9d00f41",
    "document_identification_back": "e881ddf4-bc9a-48e0-9555-cac979f65431",
    "selfie": "ca37979e-6f11-4465-bf3b-69cd8307549c"
}
```

Ou ainda, após a criação da proposta, podem ser informadas através do seguinte endpoint:

ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /related_party/ RELATED-PARTY-KEY /attached_document
MÉTODO POST

Testar no Playground

Request Body

```json
{
    "document_identification": "2893fc74-88fd-4cc9-a5c6-8a63d9d00f41",
    "document_identification_back": "e881ddf4-bc9a-48e0-9555-cac979f65431",
    "selfie": "ca37979e-6f11-4465-bf3b-69cd8307549c"
}
```

:::info Informação
A **related_party_key** é retornada na response da criação de dívida dentro do objeto **borrower** e dentro de cada uma das partes relacionadas dentro de **related_party_list** se for o caso.
:::

## Formalização da Proposta

:::caution Atenção
Para propostas que envolvam troco após o refinanciamento, é necessário o valor do troco calculado de acordo com as condições do contrato seja de pelo menos 5% da diferença entre a soma de todas as parcelas do refinanciamento subtraida da soma de todas as parcelas da portabilidade. Caso contrário, a requisição receberá o seguinte erro:

STATUS 400

**Response Body**

```json
{
    "title": "Bad Request", 
    "code": "CT000118",
    "description": "The final disbursement amount is less than 5% of the sum of refinancing installment minus the sum of portability installment. The minimum final disbursement amount allowed is 500.00. Calculated final disbursement amount: 400.00.", 
    "translation": "O valor do troco é menor que 5% da soma do valor das parcelas do refinanciamento menos o valor soma das parcelas da portabilidade. O valor mínimo do troco permitido é de 500.00. Valor calculado do troco: 400.00."
}

```
:::

        Para formalização das operações de Portabilidade e/ou Refinanciamento (Troco), deve-se enviar as evidências de assinatura dos contratos gerados na digitação da Proposta.

**No payload de assinatura devem conter os campos obrigatórios relacionados aos documentos enviados no item 5. Os campos obrigatórios são os seguintes: _ip_address_ e _signature_datetime_.**

        **6.1.** Para assinatura da Operação de Portabilidade o Parceiro deve realizar a seguinte chamada:

        **Request**
- MÉTODO POST
- STATUS /v2/credit_transfer/proposal/ PROPOSAL-KEY /portability_credit_operation/signature

Testar no Playground

        *Payload:*

**payload.json**

```json
{
    "type": "pdf-signature",
    "biometry_analysis_reference": "SERPRO",
    "signature_datetime": "2023-12-22T15:01:32.482Z",
    "signed_pdf_path": "https://termos-originacao.s3.amazonaws.com/5cd2a7f9",
    "ip_address": "179.145.48.219",
    "similarity_score": "0.9750000000000001"
}

```

## Enumeradores _Biometry Analysis Reference_
| Enumerador    | Descrição                                                                                                                                                                                                                                                          |
|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **serpro**    | Utilizado quando o similarity_score for retornado através de consulta realizada na base de documentos com foto do Detran (Serviço prestado através da Serpro)                                                                                                      |
| **tse**       | Utilizado quando o similarity_score for retornado através de consulta realizada na base de documentos com foto do TSE                                                                                                                                              |
| **not_found** | Deve ser informado quando a biometria facial não for localizada em nenhuma das bases governamentais anteriores (serpro ou tse). Neste caso o similarity_score deve ser null ou o grau de similaridade da selfie com o documento oficial com foto, retornado pelo parceiro. |

        A conclusão da assinatura será notificada de forma assíncrona:

        **Webhook**

- WEBHOOK_TYPE credit_transfer.proposal.credit_operation

**body.json**

```json
{
	"webhook_type": "credit_transfer.proposal.credit_operation",
	"proposal_key": "<PROPOSAL-KEY>",
	"event_datetime": "2022-11-24T15:42:12",
	"data": {
		"credit_operation_type": "portability",
		"credit_operation_key": "<CREDIT-OPERATION-KEY>",
		"document_key": "<GUID DO DOCUMENTO NA QI>",
		"signed_document_url": "<LINK DO URL DO PDF ASSINADO>",
		"credit_operation_status": "signed"
	}
}

```

        **6.2.** Para assinatura da Operação de Refinanciamento (Troco) o Parceiro deve realizar a seguinte chamada:

        **Request**

- MÉTODO POST
- ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /refinancing_credit_operation/signature

Testar no Playground

        *Payload:*

**payload.json**

```json
{
    "type": "pdf-signature",
    "signed_pdf_path": "https://termos-originacao.s3.amazonaws.com/5cd2a7f9",
	"ip_address": "192.168.0.0",
	"signature_datetime": "2020-03-20T14:28:23.382748Z",
	"similarity_score": "0.98",
	"biometry_analysis_reference": "serpro"
}
```

        A conclusão da assinatura será notificada de forma assíncrona:

        **Webhook**

- WEBHOOK_TYPE credit_transfer.proposal.credit_operation

**body.json**

```json

{
	"webhook_type": "credit_transfer.proposal.credit_operation",
	"proposal_key": "<PROPOSAL-KEY>",
	"event_datetime": "2022-11-24T15:42:12",
	"data": {
		"credit_operation_type": "refinancing",
		"credit_operation_key": "<CREDIT-OPERATION-KEY>",
		"document_key": "<GUID DO DOCUMENTO NA QI>",
		"signed_document_url": "<LINK DO URL DO PDF ASSINADO>",
		"credit_operation_status": "signed"
	}
}

```

---

# Máquinas de Status

URL: /documentation/guides/INSS/portability+refinancing/maquinas-de-status

Máquinas de Status — Port+Refin

:::info
Esta página descreve as máquinas de status que cobrem o que acontece **após a formalização da proposta**. Para o fluxo completo de digitação e pré-aprovação, consulte o [Fluxo Completo](./end-to-end).
:::

## Portabilidade — Máquina de Status

![Máquina de estados da proposta de portabilidade](/img/diagrams/inss-port-refin-maquinas-de-status-1.svg)

        Os estados da Proposta de Portabilidade refletem as etapas envolvidas no processo de portabilidade de crédito dentro do CTC (Central de Transferência de Crédito) da CIP.
Segue abaixo a descrição do fluxo e do significado de cada status envolvido em uma Proposta de Portabilidade, desde sua digitação até sua liquidação.

        **7.1. pending_response:**
Status da proposta após realização da digitação. Neste status a proposta foi recebida com sucesso pela QI e enviada para o CTC - CIP.

                **7.1.1 rejected:** 
Caso a digitação da proposta seja rejeitada pelo CTC - CIP, será enviado um webhook com o motivo da rejeição:

        **Webhook**

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS rejected

**body.json**

```json
{
  "webhook_type": "credit_transfer.proposal",
  "proposal_key": "\<PROPOSAL-KEY\>",
  "proposal_status": "rejected",
  "event_datetime": "2022-11-24T15:42:12",
  "data": {
    "error": {
        "code": "ECTC0023",
        "reason": "Contrato com portabilidade em andamento"
    }
  }
}

```

                **7.1.1 rejected reasons:** 
Caso a digitação da proposta seja rejeitada pelo CTC - CIP, será enviado um webhook com o motivo da rejeição:

 
| reason                             | description                                                                                                                   | external_code |
|------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|---------------|
| portability_in_progress            | Contrato com portabilidade em andamento                                                                                       | ECTC0023      |
| portability_finished               | Portabilidade já finalizada para o contrato informado                                                                         | ECTC0028      |
| portability_in_expiration_progress | Portabilidade não permitida. Contrato com portabilidade em situação de "Decurso de prazo" por não efetivação da portabilidade | ECTC0085      |
| unexpected_error                   | Erro inesperado                                                                                                               | ECTC9999      |
| portability_payment_rejected       | Pagamento de portabilidade rejeitado.                                                                                         |               |
| divergent_due_balance              | Saldo devedor final deve ser menor que saldo devedor devolvido pela cip.                                                      |               |

        **7.2. pending_acceptance:** Status da Proposta após envio/aceite pelo CTC - CIP. A Proposta, neste momento, está aguardando resposta de saldo devedor pelo banco credor original. Neste momento é enviado um webhook com o número da Portabilidade no CTC - CIP:

        **Webhook**

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS pending_acceptance

**body.json**

```json

{
    "webhook_type": "credit_transfer.proposal",
    "proposal_key": "\<PROPOSAL-KEY\>",
    "proposal_status": "pending_acceptance",
    "event_datetime": "2022-11-24T15:42:12",
    "data": {
        "portability_number": "202211230000246536429",
        "inclusion_date": "2022-11-24",
        "due_balance_expected_return_date": "2022-12-01"
    }
}
```

:::info
O **"portability_number"** é o Número da Portabilidade dentro do CTC - CIP, e é o número utilizado pela instituição proponente e instituição credora original para localizar a Proposta de Portabilidade.
:::

        Assim que o banco credor original responder à solicitação de portabilidade, será enviado um webhook com a resposta do valor do saldo devedor no caso da não retenção, e com a informação de "retido", no caso da retenção:

        **7.2.1. accepted:** Status da Proposta quando o banco credor original retorna o saldo devedor e não retem o crédito. Será enviado um webhook com a informação do saldo devedor.
O banco credor original tem até 5 d.u. após a recepção da Proposta de Portabilidade, para envio da resposta com a informação do saldo devedor da operação.

        **Webhook**

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS accepted

**body.json**

```json

{
	"webhook_type": "credit_transfer.proposal",
	"proposal_key": "\<PROPOSAL-KEY\>",
	"proposal_status": "accepted",
	"event_datetime": "2022-11-24T15:42:12",
	"data": {
		"final_due_balance": 1000,
		"portability_number": "202211230000246536429",
		"original_contract": {
			"origin_contract_number": "5584745",
			"origin_ispb_number": "60746948",
			"origin_document_number": "90406718261",
			"origin_operation_type": "0202",
			"installment_face_value": 1000,
			"total_iof": 1,
			"first_due_date": "2021-05-31",
			"last_due_date": "2022-05-31",
			"interest": 1,
			"cet": 1,
			"installment_number": 12,
			"amortization": 1,
			"final_due_balance": 1000,
			"final_due_date": "2021-08-31",
			"contract_date": "2021-04-31"
		}
	}
}
```

        Com a informação do saldo devedor retornado pela instituição credora original, o parceiro tomará a decisão se seguir ou não com a Portabilidade. 

:::info
Horário limite para envio do saldo devedor pela instituição credora original é às 10:00.
:::

        Após o recebimento do saldo devedor, caso o Parceiro decida seguir com a Proposta Portabilidade, ele deve realizar a seguinte chamada:

        **Request**

- MÉTODO PATCH
- ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY

Testar no Playground

        *Payload:*

**payload.json**

```json
{
    "status":"accepted_by_requester"
}
```

:::caution Atenção
Para propostas que envolvam troco após o refinanciamento, é necessário que o valor do troco calculado de acordo com as novas condições do contrato após o retorno do saldo devedor seja de pelo menos 5% da diferença entre a soma de todas as parcelas do refinanciamento subtraida da soma de todas as parcelas da portabilidade. Caso contrário, a requisição receberá o seguinte erro:

STATUS 400

**Response Body**

```json
{
    "title": "Bad Request", 
    "code": "CT000118",
    "description": "The final disbursement amount is less than 5% of the sum of refinancing installment minus the sum of portability installment. The minimum final disbursement amount allowed is 500.00. Calculated final disbursement amount: 400.00.", 
    "translation": "O valor do troco é menor que 5% da soma do valor das parcelas do refinanciamento menos o valor soma das parcelas da portabilidade. O valor mínimo do troco permitido é de 500.00. Valor calculado do troco: 400.00."
}

```
::: 

        O Parceiro pode adicionar dados de novo valor de parcela ou nova taxa nessa chamada, caso queira alterá-los:

        **Request**

- MÉTODO PATCH
- ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY

        *Payload:*

**payload.json**

```json
{
    "status":"accepted_by_requester",
	"financial": {
		"installment_face_value": 100
	}
	
}
```

        **Request**

- MÉTODO PATCH
- ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY

        *Payload:*

**payload.json**

```json
{
    "status":"accepted_by_requester",
	"financial": {
		"monthly_interest_rate": 0.01
	}
	
}
```

:::info Campos adicionais opcionais
Além dos campos `status` e `financial`, o endpoint de aceite da proposta também aceita os seguintes campos opcionais:
- **`borrower.document_identification_type`** (string ou null): Tipo do documento de identificação
- **`borrower.document_identification_number`** (string, máx. 16 caracteres): Número do documento de identificação
- **`borrower.gender`** (string ou null): Gênero do tomador. Valores aceitos: `"male"`, `"female"` ou `null`
- **`credit_agent`** (objeto): Agente de crédito com `name` (string, máx. 100) e `document_number` (string, 11 ou 14 dígitos)
:::

:::danger Atenção!
Caso o valor da parcela seja maior que valor total disponível (valor da parcela do contrato de origem + margem total disponível do benefício),
será retornado o seguinte erro: 
```json
{
    "title": "Reservation amount greater than available total balance",
    "description": "The installment face value: 54.4 is greater than the available total balance (origin installment face value + available total balance):30.4. Available total balance: -20.0.",
    "translation": "O valor da parcela: 54.4 é maior que o valor total disponível (valor da parcela do contrato de origem + margem total disponível) : 30.4. Margem total diponível: -20.0.",
    "code": "SSC000059"
}

```
Ao receber esta crítica, é possível que uma nova chamada seja feita, alterando o valor da parcela para que ela se ajuste ao valor total disponível.

Se o ajuste no valor da parcela não for feito até o horário limite para aceite do saldo devedor, será necessária uma nova digitação de proposta.
:::

        Caso o Parceiro decida por não prosseguir com a Proposta de Portabilidade, ele deve, **obrigatoriamente** realizar a seguinte chamada para informar a desistência da Portabilidade:

        **Request**

- MÉTODO DELETE
- ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY

Testar no Playground

        Após o envio do cancelamento da Proposta de Portabilidade ao CTC - CIP, será enviado um webhook de Proposta Cancelada:

        **Webhook**

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS canceled

**body.json**

```json

{
    "webhook_type": "credit_transfer.proposal",
    "proposal_status": "canceled",
    "proposal_key": "\<PROPOSAL-KEY\>",
    "event_datetime": "2022-11-24T15:42:12"
}

```

:::info
O horário limite para aceite do saldo devedor é 16:30. 
Não é possível retomar uma Proposta com status "canceled". Caso a Proposta esteja com este status, será necessária a realização de uma nova digitação.
:::
 

        **7.2.2. retained:**  Status da Proposta quando o banco credor original retem o crédito, será enviado o webhook com a informação de retenção. O banco credor original do crédito tem até 2 d.u. após a recepção da Proposta de Portabilidade, para envio da resposta de retenção do crédito.

        **Webhook**

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS retained

**body.json**

```json

{
  "webhook_type": "credit_transfer.proposal",
  "proposal_key": "\<PROPOSAL-KEY\>",
  "proposal_status": "retained",
  "event_datetime": "2022-11-24T15:42:12",
  "data": {
    "retained_reason": {
      "reason": "issuer_retention",
      "description": "Retenção do Cliente"
    }
  }
}
```

### Detalhamento de campos no webhook de proposal
| Campo                     | Descrição                           | Valores                          |
|---------------------------|-------------------------------------|----------------------------------|
| reason                    | lista dos motivos de retenção de uma Proposta  | [Enumeradores](/documentation/guides/INSS/reference/enumeradores#retention_reason_enumerator) |
 

        **7.3. accepted_by_requester:** Após aprovada pelo parceiro, a Proposta segue o fluxo interno da QI para liquidação.

        **7.4. settlement_sent:** 
Após conclusão do fluxo interno da QI para liquidação da Proposta de Portabilidade o recurso para pagamento do saldo devedor é enviado ao credor original disparando o seguinte webhook para o Parceiro:

        **Webhook**

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS settlement_sent

**body.json**

```json

{
	"webhook_type": "credit_transfer.proposal",
	"proposal_key": "\<PROPOSAL KEY\>",
	"proposal_status": "settlement_sent",
	"event_datetime": "2022-11-24T15:42:12",
	"data": {
		"receipt": {
			"amount": 1000,
			"timestamp": "2022-09-14 11:55:31",
			"description": "237 0001 1000093 1000093-3 59588111000103 - BCO BRADESCO S.A.",
			"ted_receipt_document_key": "a34e84a2-1628-4f23-8c11-2b2f4656ced1",
			"ted_receipt_url": "https://qitech.com.br/",
			"transaction_key": "ed3e84a2-1628-4f23-8c11-2b2f4656cedf",
			"origin": {
				"account_key": "ed3e84a2-1628-4f23-8c11-2b2f4656cedf",
				"bank_code": "329",
				"branch": "0001",
				"branch_digit": null,
				"account_number": "1000361",
				"account_digit": "3",
				"type": "checking_account",
				"name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
				"document": "32402502000135"
			},
			"destination": {
				"bank_code": "237",
				"branch": "0001",
				"branch_digit": null,
				"account_number": "1000093",
				"account_digit": "3",
				"type": "checking_account",
				"name": "BCO BRADESCO S.A.",
				"document": "59588111000103",
				"purpose": "Saída Liquidação de Portabilidade"
			}
		}
	}
}
```

Neste momento será iniciada averbação da Operação de Portabilidade na Dataprev. O processo de averbação acontecerá em paralelo aos itens seguintes (itens 7.5., 7.5.1. e 7.5.2.)

 

        **7.5. pending_settlement_confirmation:** Após a confirmação do envio dos recursos para pagamento do saldo devedor, é aguardada a confirmação da quitação do contrato por parte da Instituição Credora Original. Nesta etapa o Parceiro receberá o seguinte webhook:

        **Webhook**

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS pending_settlement_confirmation

**body.json**

```json
{
    "webhook_type": "credit_transfer.proposal",
    "proposal_key": "\<PROPOSAL-KEY\>",
    "proposal_status": "pending_settlement_confirmation",
    "event_datetime": "2022-11-24T15:42:12"
}
```

:::info
A confirmação da quitação do contrato é encaminhada pela Instituição Credora Original ao CTC - CIP e posteriormente encaminhado pelo CTC - CIP à QI.

O SLA para confirmação da quitação da Portabilidade é de **2 d.u.** contados a partir do envio dos recursos para pagamento do saldo devedor do contrato original.
:::
 
        **7.5.1. paid:** Assim que a QI receber do CTC - CIP a confirmação da quitação do Contrato Original, a Proposta constará como paga e a Portabilidade estará finalizada. 

        **Webhook**

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS paid

**body.json**

```json

{
    "webhook_type": "credit_transfer.proposal",
    "proposal_key": "\<PROPOSAL-KEY\>",
    "proposal_status": "paid",
    "event_datetime": "2022-11-24T15:42:12"
}
```

        Nesta etapa, caso a averbação da Operação de Portabilidade já esteja concluída, a Operação de Refinanciamento (Troco), poderá ser iniciada (fluxo descrito no item 7).

        **7.5.1.1.** A notificação sobre a averbação da Operação de Portabilidade será enviada através do seguinte webhook:

        **Webhook**

- WEBHOOK_TYPE credit_transfer.proposal.collateral

**body.json**

```json

{
    "webhook_type": "credit_transfer.proposal.collateral",
    "proposal_key": "\<PROPOSAL-KEY\>",
    "event_datetime": "2022-11-24T15:42:12",
    "data": {
        "credit_operation_type": "portability",
		"credit_operation_key": "\<CREDIT-OPERATION-KEY\>",
		"collateral_type": "social_security",
		"collateral_constituted": true,
		"collateral_data": {
                    "reservation_method": "portability", 
                }
	}
}
```
 
        data.collateral_data.reservation_method: [portability, new_credit ]

        **7.5.2. rejected:** 
Caso o banco credor original rejeite a quitação do contrato, o recurso enviado para quitação do saldo devedor do contrato original será devolvido, e a proposta será finalizada. O parceiro receberá o webhook de **"rejected"**.

        **Webhook**

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS rejected

**body.json**

```json

{
    "webhook_type": "credit_transfer.proposal",
    "proposal_key": "\<PROPOSAL-KEY\>",
    "proposal_status": "rejected",
    "event_datetime": "2022-11-24T15:42:12",
    "data": {
        "error": {
            "code": "QCTC0001",
            "reason": "Pagamento de portabilidade rejeitado."
        }
    }
}
```
 

        Caso nesta etapa a Operação de Portabilidada já esteja averbada na Dataprev, será realizada a desaverbação da margem.

:::info
Não é possível retomar uma Proposta com status "**rejected**". É sempre necessário realizar uma nova digitação.
:::

--- 

## Refinanciamento (Troco) — Máquina de Status

![Máquina de estados da operação de refinanciamento](/img/diagrams/inss-port-refin-maquinas-de-status-2.svg)

        **8.1** 
No momento em que a Operação de Portabilidade é paga, o Parceiro pode optar por seguir com a Operação de Refinanciamento (Troco) ou não.

#### Enumeradores credit_operation_status
| Enumerador               					| Descrição                  	 		|
|-------------------------------------------|---------------------------------------|
| waiting_signature  						| Operação aguardando assinatura 		|
| signed     								| Operação assinada			     		|
| issued  									| Operação emitida			     		|
| disbursed									| Operação desembolsada		     		|
| settled     								| Operação liquidada	         		|
| canceled     								| Operação cancelada		     		|
| canceled_permanently  					| Operação cancelada permanentemente    |

        **8.1.1.** Para prosseguir com o Refinanciamento (Troco), o Parceiro deve realizar a seguinte chamada passando os campos 'Financial' e 'Disbursement Bank Accounts':

*Adicionalmente, pode-se passar o campo 'purchaser_document_number' para alterar o cessionário da operação.

        **Request**

- MÉTODO POST
- ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /refinancing_credit_operation/acceptance

Testar no Playground

**Request Body**

```json
{
    "financial": {
        "installment_face_value": 379.87,
        "monthly_interest_rate": 0.0166,
        "number_of_installments": 84,
        "limit_days_to_disburse": 7,
        "disbursement_date": "2024-07-02",
        "rebates": [
            {
                "rebate_bank_account": {
                    "bank_code": "329",
                    "account_digit": "9",
                    "document_number": "18533555000164",
                    "name": "Teste Ltda",
                    "account_number": "4290002",
                    "branch_number": "0001"
                },
                "amount_type": "percentage",
                "fee_type": "spread",
                "amount": 9.5
            },
            {
                "amount": 20,
                "rebate_bank_account": {
                    "name": "Teste Ltda",
                    "document_number": "18533555000164",
                    "account_digit": "0",
                    "account_number": "4290001",
                    "branch_number": "0001",
                    "bank_code": "329"
                },
                "amount_type": "percentage",
                "fee_type": "insurance_premium"
            }
        ]
    },
    "disbursement_bank_accounts": [
        {
            "document_number": "92093764000197",
            "branch_number": "0001",
            "name": "TESTE LTDA",
            "percentage_receivable": 100,
            "account_number": "120012",
            "account_digit": "3",
            "bank_code": "329"
        }
    ],
    "purchaser_document_number": "28534595027164"
}
```

        **Response:**

**Response**

```json

{
	"credit_operation_key": "\<CREDIT-OPERATION-KEY\>",
	"contract_number": "00000002",
	"document_key": "\<DOCUMENT-KEY da CCB de Refinanciamento\>",
	"document_url": "\<URL da CCB de Refinanciamento\>",
	"credit_operation_status": "issued",
	"fine_configuration": {
		"contract_fine_rate": 0.02,
		"interest_base": "calendar_days",
		"monthly_rate": 0.01
	},
	"disbursement_options": [{
		"installments": [{
				"additional_costs": [],
				"bank_slip_key": null,
				"business_due_date": "2021-08-09",
				"calendar_days": 53,
				"digitable_line": null,
				"due_date": "2021-08-08",
				"due_interest": 0,
				"due_principal": 997.87,
				"fine_amount": null,
				"has_interest": true,
				"installment_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036",
				"installment_number": 1,
				"installment_status": "created",
				"installment_type": "principal",
				"paid_amount": 0,
				"paid_at": null,
				"post_fixed_amount": 0,
				"pre_fixed_amount": 54.84865004983954,
				"principal_amortization_amount": 306.98134995016045,
				"total_amount": 361.83,
				"workdays": 37
			},
			{
				"additional_costs": [],
				"bank_slip_key": null,
				"business_due_date": "2021-09-08",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2021-09-08",
				"due_interest": 0,
				"due_principal": 690.8886500498395,
				"fine_amount": null,
				"has_interest": true,
				"installment_key": "e8406cdb-844c-4e6d-9620-3635fab9d8d1",
				"installment_number": 2,
				"installment_status": "created",
				"installment_type": "principal",
				"paid_amount": 0,
				"paid_at": null,
				"post_fixed_amount": 0,
				"pre_fixed_amount": 21.964874249804833,
				"principal_amortization_amount": 339.86512575019515,
				"tax_amount": 0,
				"total_amount": 361.83,
				"workdays": 22
			}
		],
		"prefixed_interest_rate": {
				"annual_rate": 0.44556431,
				"daily_rate": 0.00564312,
				"monthly_rate": 0.0556431,
				"interest_base": "calendar_days_365"
		},
		"iof_amount": 50,
		"external_contract_fee_amount": 0,
		"external_contract_fees": [],
		"contract_fee_amount": 0,
		"contract_fees": [],
		"number_of_installments": 2,
		"disbursed_issue_amount": 997.87,
		"final_disbursement_amount": 100,
		"issue_amount": 1147.87,
		"disbursement_date": "2021-05-31",
		"cet": 1.212,
		"annual_cet": 32.122
	}],
	"disbursement_bank_account": {
		"account_digit": "1",
		"account_number": "00001",
		"ispb": "00000000",
		"branch_number": "0001"
	}
}
```

        **8.1.2.** Caso o Parceiro opte por não prosseguir com a Operação de Refinanciamento (Troco), ele deve realizar a seguinte chamada:

**Request**

- MÉTODO DELETE
- ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /refinancing_credit_operation
 

        **8.2. Averbação do Refinanciamento (Troco):** 
Assim que o Parceiro optar por prosseguir com a Operação de Refinanciamento, a rotina para averbação da margem consignável terá início. Assim que a averbação da margem consignável do INSS for concluída o parceiro recebera o seguinte webhook:

        **Webhook**

- WEBHOOK_TYPE credit_transfer.proposal.collateral

**Body**

```json

{
    "webhook_type": "credit_transfer.proposal.collateral",
    "proposal_key": "\<PROPOSAL-KEY\>",
    "event_datetime": "2022-11-24T15:42:12",
    "data": {
        "credit_operation_type": "refinancing",
		"credit_operation_key": "\<CREDIT-OPERATION-KEY\>",
		"collateral_type": "social_security",
		"collateral_constituted": true
	}
}
```

        **8.3. Desembolo do Refinanciamento (Troco):**

        Assim que a averbação da margem consignável do INSS for concluída a operação estará pronta para desembolso.
No desembolso da Operação de Refinanciamento, a Operação de Portabilidade será quitada e caso exista valor desembolsado remanescente (**7.1.1. "disbursement_options.final_disbursement_amount"**), este valor será liberado para o cliente (Troco) na conta para desembolso da Operação (**"disbursement_bank_account"**).
A liberação do troco para o cliente pode ser realizada via PIX ou TED, em qualquer horário do dia (obedecendo horário comercial de 7:00 às 17:00 em dias úteis, no caso da TED).

        **8.3.1.** Caso o desembolso do troco para o cliente seja bem sucedido, será enviado um webhook com os dados da comprovação do desembolso:

        **Webhook**

- WEBHOOK_TYPE credit_transfer.proposal.credit_operation

**body.json**

```json

{
	"webhook_type": "credit_transfer.proposal.credit_operation",
	"proposal_key": "\<PROPOSAL-KEY\>",
	"event_datetime": "2022-11-24T15:42:12",
	"data": {
		"credit_operation_status": "disbursed",
		"credit_operation_type": "refinancing",
		"credit_operation_key": "\<CREDIT-OPERATION-KEY\>",
		"ted_receipt_list": [{
			"fee": 0,
			"url": "https://qitech.com.br/",
			"amount": 500,
			"origin": {
				"name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
				"type": "payment_account",
				"branch": "0001",
				"document": "32402502000135",
				"bank_code": "329",
				"account_key": "871059bd-4014-41ad-82b4-28275ff0e67b",
				"branch_digit": null,
				"account_digit": "5",
				"account_branch": "0001",
				"account_number": "00002"
			},
			"timestamp": "2022-09-28T13:00:47",
			"description": "DESCRIPTION",
			"destination": {
				"name": "Elaine Isadora da Cruz",
				"type": "checking_account",
				"bank_code": "033",
				"branch": "0001",
				"purpose": "Crédito PIX em Conta",
				"document_number": "90406718261",
				"bank_ispb": "90400888",
				"branch_digit": null,
				"account_digit": "1",
				"account_number": "00001"
			},
			"end_to_end_id": null,
			"transaction_key": "871059bd-4014-41ad-82b4-28275ff0e67b",
			"origin_transaction_key": null
		}]
	}
}
```
 

        **8.3.2.** Caso ocorra falha no desembolso, o parceiro receberá o seguinte webhook:

                **7.3.2.1.** Falha no desembolso via PIX:

        **Webhook**

- WEBHOOK_TYPE credit_transfer.proposal.credit_operation

**body.json**

```json

{
	"webhook_type": "credit_transfer.proposal.credit_operation",
	"proposal_key": "60fbbfe2-eb52-4825-9ed5-f169a58b9999",
	"event_datetime": "2022-11-24T15:42:12",
	"data": {
		"credit_operation_status": "canceled",
		"credit_operation_type": "refinancing",
		"credit_operation_key": "1a1a44df-29b6-431c-89af-53657d906333",
		"pix_refusal": {
            "reason_enumerator": "invalid_document_number",
            "reason": "CPF/CNPJ do usuário recebedor não é compatível com o titular da conta de destino."
        },
        "cancel_reason": "pix_refusal"
	}
}
```

                **7.3.2.2.** Falha no desembolso via TED:

        **Webhook**

- WEBHOOK_TYPE credit_transfer.proposal.credit_operation

**body.json**

```json
{
    "webhook": {
        "data": {
            "cancel_reason": "Agência ou Conta Destinatária do Crédito Inválida",
            "credit_operation_key": "1a1a44df-29b6-431c-89af-53657d906333",
            "credit_operation_type": "refinancing",
            "credit_operation_status": "canceled",
            "cancel_reason_enumerator": "agencia_conta_invalida"
        },
        "proposal_key": "60fbbfe2-eb52-4825-9ed5-f169a58b9999",
        "webhook_type": "credit_transfer.proposal.credit_operation",
        "event_datetime": "2023-12-22T10:15:25"
    }
}

```
 

        **8.3.3.**
No caso de falha no desembolso da Operação, o desembolso pode ser retentato alterando-se os dados bancários:

        **Request**

- MÉTODO PATCH
- ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /refinancing_credit_operation

Testar no Playground

        *Payload:*

**payload.json**

```json
{
	"disbursement_date": "2022-11-04",
	"disbursement_bank_account": {
		"account_branch": "1232",
		"account_digit": "4",
		"account_number": "412412412",
		"account_type": "checking_account",
		"document_number": "14950479032",
		"ispb": "17298092",
		"name": "Maria da Silva"
	}
}

```

---

# Digitação da Proposta

URL: /documentation/guides/INSS/portability+refinancing/proposta

Digitação da Proposta

Cria a proposta de portabilidade (com ou sem refinanciamento do Troco) em `POST /v2/credit_transfer/proposal`, recupera e corrige os dados da proposta.

Para acompanhar os status depois da formalização, veja [Máquinas de Status](/documentation/guides/INSS/portability+refinancing/maquinas-de-status).

:::caution Atenção
    Para que os pedidos de averbação, tanto da portabilidade, como do refinanciamento sejam criados com sucesso, é preciso que seja feita uma consulta de dados válida para o benefício **previamente**. 
    Para isso basta seguir os passos do item [2 - Consulta de dados do benefício](/documentation/guides/INSS/inquiries/dados-do-beneficio).
:::

:::info Assinatura em grupo (opcional)
Para reunir esta proposta com outras operações INSS do **mesmo beneficiário** e coletar **uma única assinatura**, envie `document_batch_group_key` na **raiz** do payload de criação da proposta. Nesse caso, a resposta **não retorna** `signature_information` — o link de assinatura é único e obtido no envio do grupo para assinatura. Consulte o fluxo de [Assinatura em grupo](/documentation/guides/INSS/signatures/batch-group-signature).
:::

## Falha na averbação por falta de uma consulta de dados válida do benefício

Se uma consulta dos dados do benefício não for realizada com sucesso antes do pedido de averbação, o status do pedido de averbação ficará como "aguardando ação do parceiro" e será enviado um webhook no seguinte formato para informar o ocorrido:

WEBHOOK_TYPE social_security_success_balance_request_not_found
STATUS Pending requester action

Webhook Body

```json
{
    "webhook": {
        "key": "<DEBT-KEY>",
        "data": {
            "enumerator": "success_balance_request_not_found",
            "description": "Success balance request not found for the specified benefit number"
        },
        "status": "pending_requester_action",
        "webhook_type": "social_security_success_balance_request_not_found",
        "event_datetime": "2024-02-26T21:36:22"
    }
}
```

Para prosseguir, as seguintes ações deverão ser tomadas:

1. Realizar a consulta dos dados do benefício em questão seguindo os passos do item 2 - [Consulta de dados do benefício](/documentation/guides/INSS/inquiries/dados-do-beneficio);  
2. Enviar uma requisição no formato abaixo para informar que a consulta foi realizada.

ENDPOINT /social_security/reservation/external_key/ DEBT-KEY /validate_reservation
MÉTODO POST

Testar no Playground

:::info Importante
    Essa requisição não apenas confirma a existência de uma consulta válida dos dados do benefício, mas também verifica se as informações enviadas para a criação da averbação estão corretas, permitindo assim a continuidade do processo.
:::

:::warning CIN — Carteira de Identidade Nacional
O campo `document_identification_type` agora aceita o valor `cin` (Carteira de Identidade Nacional). Quando utilizado, o campo `document_identification_number` **deve ser igual ao CPF** do portador (`individual_document_number`). O número do CIN é o próprio CPF.

Valores aceitos em `document_identification_type`: `rg`, `rne`, `cnh`, `ctps`, `class_document`, `passport`, `other`, `cin`.

**Atenção:** o envio do documento de identificação (`document_identification`) passará a ser **obrigatório** nas operações de portabilidade INSS. Comunique seus integradores com antecedência.
:::

**4.1. Digitação da Proposta de Portabilidade com Refinanciamento:** Essa forma de digitação é utilizada para realizar a portabilidade de um contrato de crédito, liberando, ao final, mais dinheiro para o devedor. O valor liberado após a portabilidade é chamado de "Troco". A Proposta de Portabilidade e a Proposta de Refinanciamento podem ser geradas em uma mesma Request.

Para a digitação da proposta devem ser enviadas as seguintes informações:

- Dados cadastrais do tomador do crédito.

- Dados cadastrais do Representante Legal (caso aplicável).

- Dados financeiros da operação de portabilidade informando sempre o número de parcelas e uma das opções entre taxa de juros e valor de face da parcela.

- Dados financeiros da operação de refinanciamento (operação que quita a operação de portabilidade e libera o troco) juntamente com os dados de conta bancária para pagamento do troco, conforme retornado na consulta dos dados do benefício.

- Agente de crédito responsável pela originação da proposta, também conhecido como 'pastinha.

- Saldo devedor, número do contrato original e ispb do credor original. Como a operação de Refinanciamento não possui data de desembolso fixa, a mudança na data de desembolso altera os valores da operação, sendo necessário informar se a taxa ("**monthly_interest_rate**") deve ser fixa ou se o valor liberado ao cliente ("**disbursed_amount**") deve ser fixo.

**Caso a proposta seja de cliente analfabeto, os dados do rogado e testemunhas devem ser enviados no campo additional_data do payload de criação da proposta. Porém, deve ser previamente alinhado com a QI Tech quais informações e formato serão utilizados**

:::danger Documento de identificação obrigatório (a partir de 03/08/2026)
A Núclea passará a exigir o documento de identificação do tomador no registro da portabilidade a partir de **06/08/2026**. Por isso, a partir de **segunda-feira, 03/08/2026**, `borrower.document_identification_type` e `borrower.document_identification_number` passam a ser **obrigatórios** na digitação da proposta — propostas sem esses campos retornam erro.

Quando `document_identification_type` for `cin`, o `document_identification_number` **pode** ser igual ao `individual_document_number` (CPF), já que a CIN usa o número do CPF. Para os demais tipos (`rg`, `cnh`), enviar o CPF em `document_identification_number` retorna erro.
:::

### Documento de identificação do tomador

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `borrower.document_identification_type` | string | ✅ | Tipo do documento de identificação. Valores: `rg`, `cnh`, `cin`. |
| `borrower.document_identification_number` | string (máx. 16) | ✅ | Número do documento informado em `document_identification_type`. Igual ao CPF **somente** quando o tipo for `cin`. |
| `borrower.document_identification_date` | string | — | Data de emissão do documento (`YYYY-MM-DD`). |

Os mesmos campos existem em cada item de `related_parties` (representante legal) e seguem a mesma regra de preenchimento.

**Ver exemplos de payload (Taxa Fixa / Valor Liberado Fixo)**

**Com Taxa Fixa**

        **4.1.1. Digitação da Proposta de Portabilidade com Refinanciamento com taxa fixa:** Segue abaixo, exemplo de digitação da proposta fixando a taxa da operação:

        **Request**

- MÉTODO POST
- STATUS /v2/credit_transfer/proposal

Testar no Playground

        *Payload:*

**Sem Registro na C3**

```json title='Request Body'

{
    "proposal_type": "inss",
    "purchaser_document_number": "32402502000135",
    "credit_agent": {
        "document_number": "87237271016",
        "name": "Agente de credito"
    },
    "borrower": {
        "person_type": "natural",
        "name": "Marilene da Silva",
        "mother_name": "Maria Mariane",
        "birth_date": "1990-05-06",
        "profession": "Desenvolvedora",
        "nationality": "Brasileira",
        "marital_status": "single",
        "is_pep": false,
        "individual_document_number": "20676928013",
        "document_identification_number": "381803326",  // obrigatório
        "document_identification_type": "rg",  // obrigatório — rg | cnh | cin
        "document_identification_date": "2019-01-28",
        "email": "elaineisadoradacruz@hotmal.com",
        "phone": {
            "country_code": "055",
            "area_code": "11",
            "number": "912828135"
        },
        "address": {
            "street": "Passagem Mariana",
            "state": "PA",
            "city": "Ananindeua",
            "neighborhood": "Águas Lindas",
            "number": "660",
            "postal_code": "67118003",
            "complement": "complemento"
        },
        "document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
        "document_identification_back": "7b8f7848-78b5-405b-a62c-f23a432fde1a",
        "selfie": "2a2d000e-9f2b-4c4e-95f9-1561950db076"
    },
    "related_parties": [
        {
            "name": "Nome Representante Legal",
            "email": "email@email.com.br",
            "birth_date": "2000-12-12",
            "is_pep": false,
            "mother_name": "maria",
            "phone": {
                "number": "991294043",
                "area_code": "11",
                "country_code": "055"
            },
            "address": {
                "street": "Avenida das Castanheiras",
                "state": "SP",
                "city": "Brasília",
                "neighborhood": "bairro",
                "number": "12",
                "postal_code": "71900100",
                "complement": ""
            },
            "role_type": "issuer_legal_representative",
            "person_type": "natural",
            "individual_document_number": "20676928013",
            "document_identification": "359530eb-41dc-41bd-8385-b86d6bd6e650",
            "document_identification_type": "rg",
            "document_identification_back": "ae320312-532c-467c-b11f-48e3ec87452b",
            "document_identification_number": "123456789",
            "selfie": "f28e1a70-32e8-4620-9d72-c89ac8c7adb1"
        }
    ],
    "collaterals": [
        {
            "collateral_type": "social_security",
            "collateral_data": {
                "benefit_number": "22255220",
                "state": "SP",
            "subcorban_document_number": "12123456000101"
            }
        }
    ],
    "portability_credit_operation": {
        "financial": {
            "monthly_interest_rate": 0.0132,
            "number_of_installments": 10
        },
        "contract_number": "300523588BF"
    },
    "refinancing_credit_operation": {
        "financial": {
            "monthly_interest_rate": 0.0132,
            "installment_face_value": 100,
            "number_of_installments": 10
        },
        "disbursement_bank_account": {
            "account_digit": "1",
            "account_number": "000059923",
            "ispb": "341",
            "bank_code": "341",
            "branch_number": "0155"
        },
        "contract_number": "200523588BF"
    },
    "origin_contract": {
        "ispb": "60746948",
        "contract_number": "558472",
        "last_due_balance": 997.87
    },
    "additional_data": {}
}

```
**Com Registro na C3**

```json title='Request Body'
{
    "proposal_type": "inss",
    "purchaser_document_number": "32402502000135",
    "credit_agent": {
        "document_number": "87237271016",
        "name": "Agente de credito"
    },
    "borrower": {
        "person_type": "natural",
        "name": "Marilene da Silva",
        "mother_name": "Maria Mariane",
        "gender": "female",
        "birth_date": "1990-05-06",
        "profession": "Desenvolvedora",
        "nationality": "Brasileira",
        "marital_status": "single",
        "is_pep": false,
        "individual_document_number": "20676928013",
        "document_identification_number": "381803326",  // obrigatório
        "document_identification_type": "rg",  // obrigatório — rg | cnh | cin
        "document_identification_date": "2019-01-28",
        "email": "elaineisadoradacruz@hotmal.com",
        "phone": {
            "country_code": "055",
            "area_code": "11",
            "number": "912828135"
        },
        "address": {
            "street": "Passagem Mariana",
            "state": "PA",
            "city": "Ananindeua",
            "neighborhood": "Águas Lindas",
            "number": "660",
            "postal_code": "67118003",
            "complement": "complemento"
        },
        "document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
        "document_identification_back": "7b8f7848-78b5-405b-a62c-f23a432fde1a",
        "selfie": "2a2d000e-9f2b-4c4e-95f9-1561950db076"
    },
    "related_parties": [
        {
            "name": "Nome Representante Legal",
            "email": "email@email.com.br",
            "birth_date": "2000-12-12",
            "is_pep": false,
            "mother_name": "maria",
            "phone": {
                "number": "991294043",
                "area_code": "11",
                "country_code": "055"
            },
            "address": {
                "street": "Avenida das Castanheiras",
                "state": "SP",
                "city": "Brasília",
                "neighborhood": "bairro",
                "number": "12",
                "postal_code": "71900100",
                "complement": ""
            },
            "role_type": "issuer_legal_representative",
            "person_type": "natural",
            "individual_document_number": "20676928013",
            "document_identification": "359530eb-41dc-41bd-8385-b86d6bd6e650",
            "document_identification_type": "rg",
            "document_identification_back": "ae320312-532c-467c-b11f-48e3ec87452b",
            "document_identification_number": "123456789",
            "selfie": "f28e1a70-32e8-4620-9d72-c89ac8c7adb1"
        }
    ],
    "collaterals": [
        {
            "collateral_type": "social_security",
            "collateral_data": {
                "benefit_number": "22255220",
                "state": "SP",
                "subcorban_document_number": "12123456000101"
            }
        }
    ],
    "portability_credit_operation": {
        "financial": {
            "monthly_interest_rate": 0.0132,
            "number_of_installments": 10
        },
        "contract_number": "300523588PF"
    },
    "refinancing_credit_operation": {
        "financial": {
            "monthly_interest_rate": 0.0132,
            "installment_face_value": 100,
            "number_of_installments": 10
        },
        "disbursement_bank_account": {
            "account_digit": "1",
            "account_number": "000059923",
            "ispb": "341",
            "bank_code": "341",
            "branch_number": "0155"
        },
        "contract_number": "200523588PK"
    },
    "origin_contract": {
        "ispb": "60746948",
        "contract_number": "558472",
        "last_due_balance": 997.87
    },
    "additional_data": {}
}
```

:::info Carência
Conforme mudança da IN 204, a partir de 19/05, as operações poderão ter carência. Para tal, basta digitar dentro do "**collateral_data**" o campo "**number_of_grace_periods**". contendo o valor do número de meses desejados de carência, como no exemplo abaixo:
```json
"collaterals": [
    {
        "collateral_type": "social_security",
        "collateral_data": {
            "benefit_number": "22255220",
            "state": "RS",
            "number_of_grace_periods": 3,
            "subcorban_document_number": "12123456000101"
        }
    }
]
```
:::

:::caution Atenção
A lista "**related_parties**", só deve ser enviada caso seja uma operação com Representante Legal.
Quando enviado, deve conter os dados cadastrais do representante legal e o campo "**role_type**" deve ser enviado contendo o valor: "**issuer_legal_representative**".
:::

:::info
No campo "**origin_contract.ispb**" é informado o **ISPB** da instituição Credora Original.
O **ISPB** é a base do CNPJ da instituição. Para ter acesso à lista completa de **ISPB's** de cada instituição participante do CTC - CIP (Central de Transferência de Crédito), basta utilizar o endpoint de consulta de participantes do CTC (índice):
:::

**Com Valor Liberado Fixo**

        **4.1.2. Digitação da Proposta de Portabilidade com Refinanciamento com valor liberado fixo:** 

         Segue abaixo, exemplo de digitação da proposta fixando o valor liberado ao cliente:

        **Request**

- MÉTODO POST
- STATUS /v2/credit_transfer/proposal

        *Payload:*

**Sem Registro na C3**

```json title='Request Body'
{
	"proposal_type": "inss",
	"purchaser_document_number": "32402502000135",
    "credit_agent": {
        "document_number": "87237271016",
        "name": "Agente de credito"
    },
	"borrower": {
		"person_type": "natural",
		"name": "Elaine Isadora da Cruz",
		"mother_name": "Maria Mariane",
		"birth_date": "1990-05-06",
		"profession": "Desenvolvedora",
		"nationality": "Brasileira",
		"marital_status": "single",
		"is_pep": false,
		"individual_document_number": "90406718261",
		"document_identification_number": "381803326",  // obrigatório
		"document_identification_type": "rg",  // obrigatório — rg | cnh | cin
		"document_identification_date": "2019-01-28",
		"email": "elaineisadoradacruz@hotmal.com",
		"phone": {
			"country_code": "055",
			"area_code": "11",
			"number": "996363253"
		},
		"address": {
			"street": "Passagem Mariana",
			"state": "PA",
			"city": "Ananindeua",
			"neighborhood": "Aguas Lindas",
			"number": "660",
			"postal_code": "67118003",
			"complement": "complemento"
		},
		"document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
		"document_identification_back": "7b8f7848-78b5-405b-a62c-f23a432fde1a",
		"selfie": "2a2d000e-9f2b-4c4e-95f9-1561950db076"
	},
	"related_parties": [{
		"name": "Nome Representante Legal",
		"email": "email@email.com.br",
		"birth_date": "2000-12-12",
		"is_pep": false,
		"mother_name": "maria",
		"phone": {
			"number": "991294043",
			"area_code": "11",
			"country_code": "055"
		},
		"address": {
			"street": "Avenida das Castanheiras",
			"state": "SP",
			"city": "Brasília",
			"neighborhood": "bairro",
			"number": "12",
			"postal_code": "71900100",
			"complement": ""
		},
		"role_type": "issuer_legal_representative",
		"person_type": "natural",
		"individual_document_number": "45102538004",
		"document_identification": "359530eb-41dc-41bd-8385-b86d6bd6e650",
        "document_identification_type": "rg",
		"document_identification_back": "ae320312-532c-467c-b11f-48e3ec87452b",
        "document_identification_number": "123456789",
		"selfie": "f28e1a70-32e8-4620-9d72-c89ac8c7adb1"

	}],
	"collaterals": [{
		"collateral_type": "social_security",
		"collateral_data": {
			"benefit_number": "12345678",
			"state": "SP",
            "subcorban_document_number": "12123456000101"
		}
	}],
	"portability_credit_operation": {
		"financial": {
			"monthly_interest_rate": 0.0132,
			"number_of_installments": 10
		},
		"contract_number": "3635259610"
	},
	"refinancing_credit_operation": {
		"financial": {
			"disbursed_amount": 1000,
			"installment_face_value": 110,
			"number_of_installments": 10
		},
		"disbursement_bank_account": {
			"account_digit": "1",
			"account_number": "00001",
			"bank_code": "033",
			"branch_number": "0001"
		},
		"contract_number": "3635259632"
	},
	"origin_contract": {
		"ispb": "60746948",
		"contract_number": "5584745",
		"last_due_balance": 800
	},
    "additional_data": {}
}
```
**Com Registro na C3**

```json title='Request Body'
{
	"proposal_type": "inss",
	"purchaser_document_number": "32402502000135",
    "credit_agent": {
        "document_number": "87237271016",
        "name": "Agente de credito"
    },
	"borrower": {
		"person_type": "natural",
		"name": "Elaine Isadora da Cruz",
		"mother_name": "Maria Mariane",
		"birth_date": "1990-05-06",
        "gender": "female",
		"profession": "Desenvolvedora",
		"nationality": "Brasileira",
		"marital_status": "single",
		"is_pep": false,
		"individual_document_number": "90406718261",
		"document_identification_number": "381803326",  // obrigatório
		"document_identification_type": "rg",  // obrigatório — rg | cnh | cin
		"document_identification_date": "2019-01-28",
		"email": "elaineisadoradacruz@hotmal.com",
		"phone": {
			"country_code": "055",
			"area_code": "11",
			"number": "996363253"
		},
		"address": {
			"street": "Passagem Mariana",
			"state": "PA",
			"city": "Ananindeua",
			"neighborhood": "Aguas Lindas",
			"number": "660",
			"postal_code": "67118003",
			"complement": "complemento"
		},
		"document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
		"document_identification_back": "7b8f7848-78b5-405b-a62c-f23a432fde1a",
		"selfie": "2a2d000e-9f2b-4c4e-95f9-1561950db076"
	},
	"related_parties": [{
		"name": "Nome Representante Legal",
		"email": "email@email.com.br",
		"birth_date": "2000-12-12",
		"is_pep": false,
		"mother_name": "maria",
		"phone": {
			"number": "991294043",
			"area_code": "11",
			"country_code": "055"
		},
		"address": {
			"street": "Avenida das Castanheiras",
			"state": "SP",
			"city": "Brasília",
			"neighborhood": "bairro",
			"number": "12",
			"postal_code": "71900100",
			"complement": ""
		},
		"role_type": "issuer_legal_representative",
		"person_type": "natural",
		"individual_document_number": "45102538004",
		"document_identification": "359530eb-41dc-41bd-8385-b86d6bd6e650",
        "document_identification_type": "rg",
		"document_identification_back": "ae320312-532c-467c-b11f-48e3ec87452b",
        "document_identification_number": "123456789",
		"selfie": "f28e1a70-32e8-4620-9d72-c89ac8c7adb1"
	}],
	"collaterals": [{
		"collateral_type": "social_security",
		"collateral_data": {
			"benefit_number": "12345678",
			"state": "SP",
            "subcorban_document_number": "12123456000101"
		}
	}],
	"portability_credit_operation": {
		"financial": {
			"monthly_interest_rate": 0.0132,
			"number_of_installments": 10
		},
		"contract_number": "3635259611"
	},
	"refinancing_credit_operation": {
		"financial": {
			"disbursed_amount": 1000,
			"installment_face_value": 110,
			"number_of_installments": 10
		},
		"disbursement_bank_account": {
			"account_digit": "1",
			"account_number": "00001",
			"bank_code": "033",
			"branch_number": "0001"
		},
		"contract_number": "3635259663"
	},
	"origin_contract": {
		"ispb": "60746948",
		"contract_number": "5584745",
		"last_due_balance": 800
	},
    "additional_data": {}
}
```

        **4.1.3. Response**

- MÉTODO POST
- STATUS /v2/credit_transfer/proposal

**body.json**

```json
{
    "borrower": {
        "individual_document_number": "90406718261",
        "name": "Elaine Isadora da Cruz",
        "related_party_key": "d7f84a9d-28ba-4355-8e5e-a436ff4c3c2d",
        "role_type": "issuer"
    },
    "portability_credit_operation": {
        "collateral_is_constituted": false,
        "contract_number": "3635259611",
        "credit_operation_key": "235ce3a5-eea1-4b13-9335-3de577318f8b",
        "credit_operation_status": "waiting_signature",
        "disbursement_accounts": [],
        "disbursement_options": [
            {
                "annual_cet": 0.17295,
                "cet": 0.0134,
                "contract_fee_amount": 0.0,
                "contract_fees": [
                    {
                        "amount": 0.5,
                        "amount_type": "percentage",
                        "fee_amount": 0.0,
                        "fee_type": "tac"
                    }
                ],
                "disbursed_issue_amount": 800.0,
                "disbursement_date": "2023-12-22",
                "external_contract_fee_amount": 0.0,
                "external_contract_fees": [
                    {
                        "amount": 0.0,
                        "amount_released": 0,
                        "amount_type": "absolute",
                        "cofins_amount": 0,
                        "csll_amount": 0,
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "spread",
                        "irrf_amount": 0,
                        "net_fee_amount": 0.0,
                        "pis_amount": 0,
                        "tax_amount": 0.0
                    },
                    {
                        "amount": 0.0,
                        "amount_released": 0,
                        "amount_type": "absolute",
                        "cofins_amount": 0,
                        "csll_amount": 0,
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "tac",
                        "irrf_amount": 0,
                        "net_fee_amount": 0.0,
                        "pis_amount": 0,
                        "tax_amount": 0.0
                    },
                    {
                        "amount": 0.0,
                        "amount_released": 0,
                        "amount_type": "absolute",
                        "cofins_amount": 0,
                        "csll_amount": 0,
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "insurance_premium",
                        "irrf_amount": 0,
                        "net_fee_amount": 0.0,
                        "pis_amount": 0,
                        "tax_amount": 0.0
                    }
                ],
                "installments": [
                    {
                        "business_due_date": "2024-02-22",
                        "calendar_days": 62,
                        "due_date": "2024-02-22",
                        "due_principal": 800.0,
                        "installment_number": 1,
                        "pre_fixed_amount": 21.977846031814607,
                        "principal_amortization_amount": 65.21215396818539,
                        "total_amount": 87.19,
                        "workdays": 40
                    },
                    {
                        "business_due_date": "2024-03-22",
                        "calendar_days": 29,
                        "due_date": "2024-03-22",
                        "due_principal": 734.7878460318146,
                        "installment_number": 2,
                        "pre_fixed_amount": 9.373907348762184,
                        "principal_amortization_amount": 77.81609265123781,
                        "total_amount": 87.19,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2024-11-22",
                        "calendar_days": 31,
                        "due_date": "2024-11-22",
                        "due_principal": 86.03031050776795,
                        "installment_number": 10,
                        "pre_fixed_amount": 1.1637189988799015,
                        "principal_amortization_amount": 86.0262810011201,
                        "total_amount": 87.19,
                        "workdays": 22
                    }
                ],
                "issue_amount": 800.0,
                "number_of_installments": 10,
                "prefixed_interest_rate": {
                    "annual_rate": 0.17042118,
                    "daily_rate": 0.00043722,
                    "interest_base": "calendar_days",
                    "monthly_rate": 0.0132
                },
                "total_iof": 0.0
            }
        ],
        "document_key": "c4cedeaf-23bf-450d-9fba-5ec6b5d45afb",
        "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/c4cedeaf-23bf-450d-9fba-5ec6b5d45afb/TESTEINSSS.A.-ELAINEISADORADACRUZ-CCB-3635259611.pdf",
        "final_disbursement_amount": 0.0
    },
    "proposal_key": "2f7e320c-2a35-4e78-bfd7-a298b28a7497",
    "proposal_number": "17032782193414588",
    "proposal_status": "pending_submission",
    "refinancing_credit_operation": {
        "collateral_is_constituted": false,
        "contract_number": "3635259663",
        "credit_operation_key": "f73ba4d2-cd0a-4405-a47e-a51f325a9756",
        "credit_operation_status": "waiting_signature",
        "disbursement_accounts": [
            {
                "account_branch": "0001",
                "account_digit": "1",
                "account_number": "00001",
                "bank_code": "033"
            }
        ],
        "disbursement_options": [
            {
                "annual_cet": 0.193423,
                "cet": 0.0148,
                "contract_fee_amount": 1.03,
                "disbursed_issue_amount": 1000.0,
                "disbursement_date": "2023-12-22",
                "issue_amount": 1005.24,
                "number_of_installments": 10,
                "final_disbursement_amount": 200.0
            }
        ],
        "document_key": "f4dfb505-3cec-4a97-9b16-dadc39bb4c7e",
        "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/f4dfb505-3cec-4a97-9b16-dadc39bb4c7e/TESTEINSSS.A.-ELAINEISADORADACRUZ-CCB-3635259663.pdf",
        "final_disbursement_amount": 200.0
    },
    "related_party_list": [
        {
            "individual_document_number": "45102538004",
            "name": "Nome Representante Legal",
            "related_party_key": "632fa6c5-40e8-4e76-862e-e10951ed8bff",
            "role_type": "issuer_legal_representative"
        }
    ]
}

```

Segue abaixo definições e descrições de alguns campos retornados na resposta da digitação da Proposta: 

**[A]**: ***"portability_credit_operation.disbursement_options.iof_amount"***: Na Operação de Portabilidade o IOF sempre será zero.

**[B]**: ***"portability_credit_operation.disbursement_options.disbursed_issue_amount"***: É igual ao valor do saldo devedor do Contrato Original.

**[C]**: ***"portability_credit_operation.disbursement_options.issue_amount"***: É o valor da Operação de Portabilidade.

:::tip Relação
[C] = [A] + [B]
:::

**[D]**: ***"refinancing_credit_operation.disbursement_options.iof_amount"***: Valor de IOF da Operação de Refinanciamento (Troco).

**[E]**: ***"refinancing_credit_operation.disbursement_options.disbursed_issue_amount"***: É o valor destinado à quitação do saldo devedor da Operação de Portabilidade.

:::tip Relação
[E] = [C]
::: 

**[F]**: **"refinancing_credit_operation.disbursement_options.final_disbursement_amount"**: É o valor do Troco liberado para o cliente na conta de desembolso informada no momento da digitação da Proposta (deve ser a conta informação da consulta dos dados do benefício).

**[G]**: **"refinancing_credit_operation.disbursement_options.issue_amount"**: É o valor do Refinanciamento.

:::tip Relação
{"\n"}
[G] = [F] + [E] + [D]
{"\n"}
:::

Os campos "**portability_credit_operation.disbursement_options.collateral_constituted**" e "**refinancing_credit_operation.disbursement_options.collateral_constituted**" informam se a margem do cliente esta averbada na Dataprev. O processo de averbação da Portabilidade será iniciado assim que os recursos para quitação do contrato original forem enviados a Instituição Credora Original (Item **6.4.**). O Processo de averbação do Refinanciamento é iniciado no momento em que o Parceiro decide por prosseguir com a Operação de Refinanciamento (Item **7.1.1.** e **7.2.**).

 

        **4.2. Digitação da Proposta de Portabilidade:**

        A Proposta de Portabilidade (Portabilidade Pura) deve ser digitada de forma semelhante ao descrito no item 4.1.1, porém deve ser enviada sem o objeto **"refinancing_credit_operation"**.

        **Request**

- MÉTODO POST
- STATUS /v2/credit_transfer/proposal

**body.json**

```json

{
	"proposal_type": "inss",
	"purchaser_document_number": "32402502000135",
    "credit_agent": {
        "document_number": "87237271016",
        "name": "Agente de credito"
    },
	"borrower": {
		"person_type": "natural",
		"name": "Elaine Isadora da Cruz",
		"mother_name": "Maria Mariane",
		"birth_date": "1990-05-06",
        "gender": "female",
		"profession": "Desenvolvedora",
		"nationality": "Brasileira",
		"marital_status": "single",
		"is_pep": false,
		"individual_document_number": "90406718261",
		"document_identification_number": "381803326",  // obrigatório
		"document_identification_type": "rg",  // obrigatório — rg | cnh | cin
		"document_identification_date": "2019-01-28",
		"email": "elaineisadoradacruz@hotmal.com",
		"phone": {
			"country_code": "055",
			"area_code": "11",
			"number": "996363253"
		},
		"address": {
			"street": "Passagem Mariana",
			"state": "PA",
			"city": "Ananindeua",
			"neighborhood": "Aguas Lindas",
			"number": "660",
			"postal_code": "67118003",
			"complement": "complemento"
		},
		"document_identification": "8b0d8c33-01c9-4cf5-a0fa-1d2a96f4b34d",
		"document_identification_back": "7b8f7848-78b5-405b-a62c-f23a432fde1a",
		"selfie": "2a2d000e-9f2b-4c4e-95f9-1561950db076"
	},
	"related_parties": [{
		"name": "Nome Representante Legal",
		"email": "email@email.com.br",
		"birth_date": "2000-12-12",
		"is_pep": false,
		"mother_name": "maria",
		"phone": {
			"number": "991294043",
			"area_code": "11",
			"country_code": "055"
		},
		"address": {
			"street": "Avenida das Castanheiras",
			"state": "SP",
			"city": "Brasília",
			"neighborhood": "bairro",
			"number": "12",
			"postal_code": "71900100",
			"complement": ""
		},
		"role_type": "issuer_legal_representative",
		"person_type": "natural",
		"individual_document_number": "45102538004",
		"document_identification": "359530eb-41dc-41bd-8385-b86d6bd6e650",
        "document_identification_type": "rg",
		"document_identification_back": "ae320312-532c-467c-b11f-48e3ec87452b",
        "document_identification_number": "123456789",
		"selfie": "f28e1a70-32e8-4620-9d72-c89ac8c7adb1"
	}],
	"collaterals": [{
		"collateral_type": "social_security",
		"collateral_data": {
			"benefit_number": "12345678",
			"state": "SP",
            "subcorban_document_number": "12123456000101"
		}
	}],
	"portability_credit_operation": {
		"financial": {
			"monthly_interest_rate": 0.0132,
			"number_of_installments": 10
		},
		"contract_number": "1020252636"
	},

	"origin_contract": {
		"ispb": "60746948",
		"contract_number": "558474520",
		"last_due_balance": 800
	},
    "additional_data": {}
}

```

        **Response**

- MÉTODO POST
- STATUS /v2/credit_transfer/proposal

        *Payload:*

**payload.json**

```json
{
    "borrower": {
        "individual_document_number": "90406718261",
        "name": "Elaine Isadora da Cruz",
        "related_party_key": "f9fbaa93-4d57-494f-b60f-dcba8cb64a45",
        "role_type": "issuer"
    },
    "portability_credit_operation": {
        "collateral_is_constituted": false,
        "contract_number": "1020252636",
        "credit_operation_key": "1cd34a63-5a61-49a3-90a5-7a515ee98932",
        "credit_operation_status": "waiting_signature",
        "disbursement_accounts": [],
        "disbursement_options": [
            {
                "annual_cet": 0.17295,
                "cet": 0.0134,
                "disbursed_issue_amount": 800.0,
                "disbursement_date": "2023-12-22",
                "issue_amount": 800.0,
                "number_of_installments": 10,
                "prefixed_interest_rate": {
                    "annual_rate": 0.17042118,
                    "daily_rate": 0.00043722,
                    "interest_base": "calendar_days",
                    "monthly_rate": 0.0132
                },
                "total_iof": 0.0
            }
        ],
        "document_key": "2f9ac920-a5e8-4386-b049-dc971e1fc20b",
        "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/2f9ac920-a5e8-4386-b049-dc971e1fc20b/TESTEINSSS.A.-ELAINEISADORADACRUZ-CCB-1020252636.pdf",
        "final_disbursement_amount": 0.0
    },
    "proposal_key": "9661aef8-e897-4405-a44f-ca8a43d9cee3",
    "proposal_number": "17032785232138245",
    "proposal_status": "pending_submission",
    "related_party_list": [
        {
            "individual_document_number": "45102538004",
            "name": "Nome Representante Legal",
            "related_party_key": "c8166f37-b496-455a-96e7-f75e24f084a1",
            "role_type": "issuer_legal_representative"
        }
    ]
}
```
 

### 4.3. Recuperando dados de uma proposta

ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY ou REQUESTER-CONTROL-KEY
MÉTODO GET

#### Path Params
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `proposal_key` | string | Chave identificadora da proposta | - |
| `requester_control_key` | string | Chave identificadora do cliente para recuperar os dados de uma proposta (casos de timeout ou operação duplicada), enviar no lugar da proposal_key | - |

        *Response:*

**response.json**

```json

{
    "borrower": {
        "address": {
            "city": "SAO PAULO",
            "complement": "Moradia",
            "neighborhood": "CENTRO",
            "number": "10",
            "postal_code": "01153000",
            "state": "SP",
            "street": "RUA CENTRAL"
        },
        "birth_date": "1976-05-25",
        "document_identification_number": "306385466",
        "email": "ivanete@windowslive.com",
        "individual_document_number": "25500337874",
        "is_pep": false,
        "marital_status": "single",
        "mother_name": "EDITE MARIA DANTAS",
        "name": "IVANETE SATURNINO DE SOUZA",
        "nationality": "Brasleira",
        "person_type": "natural",
        "phone": {
            "area_code": "11",
            "country_code": "055",
            "number": "985814768"
        },
        "profession": "Aposentado",
        "related_party_key": "511d7186-3c17-4f35-8887-c4aefaf270be",
        "role_type": "issuer"
    },
    "collaterals": [
        {
            "collateral_data": {
                "benefit_number": 2045043317,
                "state": "SP"
            },
            "collateral_type": "social_security"
        }
    ],
    "origin_operation": {
        "contract_date": "2025-06-02",
        "contract_number": "0123489618691",
        "financial_institution_code_number": "237",
        "installment_number": 84,
        "ispb_number": "60746948",
        "last_due_balance": 17879.22,
        "opened_installment_number": 67,
        "overdue_installment_number": 0
    },
    "portability_credit_operation": {
        "collateral_is_constituted": false,
        "contract_number": "CTC0000024971",
        "credit_operation_key": "e5bfbd28-0144-4eaa-b7f1-d0efb0b6b155",
        "credit_operation_status": "waiting_signature",
        "disbursement_accounts": [],
        "disbursement_options": [
            {
                "annual_cet": 0.2321,
                "cet": 0.0175,
                "disbursed_issue_amount": 17879.22,
                "disbursement_date": "2025-06-02",
                "issue_amount": 17879.22,
                "number_of_installments": 67,
                "prefixed_interest_rate": {
                    "annual_rate": 0.2285378296,
                    "daily_rate": 0.0005718988,
                    "interest_base": "calendar_days",
                    "monthly_rate": 0.0173
                },
                "total_iof": 0
            }
        ],
        "document_key": "f85d9799-e29f-4133-80c3-3e95f16f2a54",
        "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/f85d9799-e29f-4133-80c3-3e95f16f2a54/MMRIOLTDA-IVANETESATURNINODESOUZA-CCB-CTC0000024971.pdf",
        "final_disbursement_amount": 17879.22
    },
    "proposal_key": "1e1d3f4d-21aa-4b6f-8515-6d978dc2afa5",
    "proposal_number": "17488903030996687",
    "proposal_status": "pending_submission",
    "refinancing_credit_operation": {
        "collateral_is_constituted": false,
        "contract_number": "CTC0000024972",
        "credit_operation_key": "7cc4d931-34d5-4b03-b04b-9ae4b6721f45",
        "credit_operation_status": "waiting_signature",
        "disbursement_accounts": [
            {
                "account_branch": "1261",
                "account_digit": "1",
                "account_number": "000062293",
                "bank_code": "237"
            }
        ],
        "disbursement_options": [
            {
                "annual_cet": 0.2517,
                "cet": 0.0189,
                "disbursed_issue_amount": 20373.27,
                "disbursement_date": "2025-06-02",
                "final_disbursement_amount": 2494.05,
                "issue_amount": 20458.57,
                "number_of_installments": 96,
                "prefixed_interest_rate": {
                    "annual_rate": 0.2460411933,
                    "daily_rate": 0.0006112186,
                    "interest_base": "calendar_days",
                    "monthly_rate": 0.0185
                },
                "total_iof": 85.3
            }
        ],
        "document_key": "60763cba-da54-4826-bf76-b8f3d26c6326",
        "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/60763cba-da54-4826-bf76-b8f3d26c6326/MMRIOLTDA-A-CCB-CTC0000024972.pdf",
        "final_disbursement_amount": 2494.05
    },
    "requester_control_key": "0e856d23-0746-4444-a71a-2957a64c869a"
}

```

:::info
No caso da recuperação dos dados de uma proposta de portabilidade pura o objeto "refinancing_credit_operation" não será retornado.
:::

## Correção de dados

A correção dos dados de uma proposta já criada — com ou sem nova assinatura da CCB — está em **[Correção de Dados da Proposta](/documentation/guides/INSS/portability+refinancing/correcao-de-dados)**.

## Simulando cenários de sucesso e insucesso na averbação em Sandbox:
A simulação de cenários é baseado no primeiro dígito do CPF informado na operação.

**11.1.** Para CPFs iniciados com o número 1, será retornado uma resposta assíncrona de sucesso através do Webhook.

**11.2.** Para os demais CPFs, será retornado uma resposta assíncrona de erro, baseado no primeiro dígito do CPF digitado, de acordo com a tabela abaixo.

**11.3.** Erros com Ação "cancel" receberá um webhook com o resultado final da operação.

| Início do cpf | Enumerador                   | Descrição                                                                         | Ação   |
|---------------|------------------------------|-----------------------------------------------------------------------------------|--------|
| 2             | invalid_disbursement_account | Invalid disbursemente bank account                                                | cancel |
| 3             | operation_not_allowed_IR     | Operation not allowed due to operation deadline greatter than benefit termination | cancel |

:::caution Atenção
Todos os CPFs que não tiverem um cenário mapeado para o primeiro dígito, receberão um webhook com um erro padrão de cenário de teste não mapeado. 

| Enumerador    | Descrição                                                        |
|---------------|------------------------------------------------------------------|
| mock_error    | Informed document number is not a valid mock on test environment |
:::

---

# Recálculo da Portabilidade

URL: /documentation/guides/INSS/portability+refinancing/recalculate-portability

Recálculo da Portabilidade

Reduz o **saldo devedor** de uma operação de portabilidade a partir de um **novo valor de parcela**, sem gerar uma nova CCB. Use quando a margem consignável disponível do beneficiário no INSS não comporta a parcela originalmente contratada e a operação precisa ser ajustada para caber na margem.

O recálculo altera, na mesma operação:

- o **valor da parcela**, que passa a ser o valor informado;
- o **valor de emissão** (`issue_amount`), ou seja, o saldo devedor pago ao credor original;
- o valor comunicado à Dataprev como saldo devedor quitado da portabilidade.

A diferença entre o valor de emissão original e o recalculado é lançada automaticamente como **desconto na remuneração do requisitante**, com a observação "Recálculo de portabilidade para adequação de margem disponível".

:::info Diferença para o recálculo do refinanciamento
Este endpoint atua sobre a **operação de portabilidade**. Para ajustar a operação de **refinanciamento** da mesma proposta, com ou sem nova CCB, veja [Recálculo e Reformalização do Refinanciamento](/documentation/guides/INSS/portability+refinancing/reformalization).
:::

## Request

ENDPOINT /v2/credit_operation/ CREDIT_OPERATION_KEY /recalculate_portability
MÉTODO POST

### Path Params

credit_operation_key
string (UUID)
obrigatório
Chave única da operação de portabilidade a ser recalculada.

### Body Params

new_installment_amount
number
obrigatório
Novo valor total da parcela. Precisa ser menor que o valor da parcela atual e maior ou igual a 10,00.

new_monthly_interest_rate
number
opcional
Nova taxa de juros mensal. Se omitida, a taxa atual da operação é mantida.

```json
{
    "new_installment_amount": 123.51,
    "new_monthly_interest_rate": 0.018
}
```

:::caution Atenção
O número de parcelas e as datas de vencimento **não mudam**. O que muda é o valor da parcela e, por consequência, o valor de emissão da operação.
:::

### Pré-condições

A operação precisa atender **todas** as condições abaixo para ser recalculada:

| Condição | Erro se não atendida |
|----------|----------------------|
| Operação existe | [`COP000027`](#COP000027) (404) |
| Requisitante é dono da operação | [`QIT000005`](#QIT000005) (403) |
| Operação é de portabilidade | [`COP000489`](#COP000489) |
| Garantia do tipo `social_security` ou `social_security_portability` | [`COP000276`](#COP000276) |
| Status da operação: `opened` | [`COP000489`](#COP000489) |
| Nova parcela maior ou igual a 10,00 | [`COP000510`](#COP000510) |
| Nova parcela menor que a parcela atual | [`COP000512`](#COP000512) |
| Operação possui exatamente uma opção de desembolso | [`COP000513`](#COP000513) |
| Valor de emissão recalculado menor que o original | [`COP000514`](#COP000514) |
| Valor de emissão recalculado de ao menos 15% do original | [`COP000511`](#COP000511) |

## Response

STATUS 200

Retorna o objeto completo da operação de crédito recalculada, na mesma estrutura da [consulta por credit_operation_key](/documentation/emissao_de_divida/consulta_por_credit_operation_key). Os campos que mudam são `issue_amount`, `disbursed_issue_amount` e os valores das parcelas em `disbursement_options`.

Além deles, a resposta traz o objeto `negative_rebate` com o desconto lançado na remuneração do requisitante por causa do recálculo. É o mesmo valor enviado ao serviço de remuneração, então não é preciso deduzi-lo da diferença entre os valores de emissão.

negative_rebate.amount
number
Valor do desconto, sempre negativo. É a diferença entre o valor de emissão recalculado e o original.

negative_rebate.original_issue_amount
number
Valor de emissão antes do recálculo.

negative_rebate.recalculated_issue_amount
number
Valor de emissão depois do recálculo.

negative_rebate.reference_date
string (date)
Data de referência do lançamento.

negative_rebate.fee_type
string
Tipo da tarifa lançada. Sempre net_payment_discount .

negative_rebate.discount_observation
string
Observação que acompanha o lançamento.

```json
{
    "negative_rebate": {
        "amount": -133.11,
        "original_issue_amount": 1000.0,
        "recalculated_issue_amount": 866.89,
        "reference_date": "2026-09-03",
        "fee_type": "net_payment_discount",
        "discount_observation": "Recálculo de portabilidade para adequação de margem disponível"
    }
}
```

## Erros

| Código HTTP | Código QI | Descrição | Tradução |
|-------------|-----------|-----------|----------|
| 403 | <span id="QIT000403">`QIT000403`</span> | You are not allowed to perform this action at this endpoint | Você não está autorizado a performar esta ação neste endpoint |
| 403 | <span id="QIT000005">`QIT000005`</span> | Selected agent do not own this item | O agente selecionado não é dono do item |
| 404 | <span id="COP000027">`COP000027`</span> | Credit Operation not found | Operação não encontrada |
| 400 | <span id="COP000276">`COP000276`</span> | Collateral type doesn't allow to recalculate operation | Garantia do contrato não permite que a operação seja recalculada |
| 400 | <span id="COP000335">`COP000335`</span> | Assignment amount is greater than final amount | O valor de cessão é superior ao valor final da operação |
| 400 | <span id="COP000339">`COP000339`</span> | Final disbursement amount cannot be negative | O valor de desembolso final não pode ser negativo |
| 400 | <span id="COP000489">`COP000489`</span> | The credit operation is not allowed to be recalculated | A operação de crédito não está permitida para ser recalculada |
| 400 | <span id="COP000510">`COP000510`</span> | The new installment amount is below the minimum allowed | O novo valor da parcela está abaixo do mínimo permitido |
| 400 | <span id="COP000511">`COP000511`</span> | The recalculated issue amount is below the minimum allowed | O valor de emissão recalculado está abaixo do mínimo permitido |
| 400 | <span id="COP000512">`COP000512`</span> | The new installment amount must be lower than the original installment amount | O novo valor da parcela deve ser menor que o valor da parcela original |
| 400 | <span id="COP000513">`COP000513`</span> | The credit operation must have exactly one disbursement option to be recalculated | A operação de crédito deve possuir exatamente uma opção de desembolso para ser recalculada |
| 400 | <span id="COP000514">`COP000514`</span> | The recalculated issue amount must be lower than the original issue amount | O valor de emissão recalculado deve ser menor que o valor de emissão original |

Motivos detalhados do erro COP000489

O código `COP000489` é retornado para diferentes pré-condições não atendidas. O campo `reason` na resposta indica o motivo específico:

| Motivo | Descrição |
|--------|-----------|
| Operação não é portabilidade | A operação de crédito não é uma operação de portabilidade |
| Status inválido | O status da operação de crédito não a permite ser recalculada |

---

# Recálculo e Reformalização do Refinanciamento

URL: /documentation/guides/INSS/portability+refinancing/reformalization

Recálculo e Reformalização do Refinanciamento

Enquanto a operação de **refinanciamento ainda não foi averbada na Dataprev**, é possível corrigir seus dados financeiros e bancários. Existem dois endpoints para isso:

| Endpoint | Gera nova CCB? | Quando usar |
|----------|----------------|-------------|
| `PUT …/refinancing_credit_operation` | **Sim** (reassinatura) | Corrigir condições e **emitir uma nova CCB** para reassinatura. |
| `PUT …/refinancing_credit_operation/recalculate` | **Não** | Ajustar o **valor da parcela** sem gerar nova CCB. |

Ambos aceitam o objeto `collateral_data` para **adicionar, alterar ou remover a carência** (`number_of_grace_periods`) informada pelo requisitante — veja [Carência](#carência).

:::info Pré-condição comum
A operação de refinanciamento **não pode estar averbada** (constituída na Dataprev). Caso contrário, retornamos [`CT000079`](#errors).
:::

---

## Correção com nova CCB

Corrige os dados financeiros e bancários da operação de refinanciamento gerando uma **nova CCB**. Use quando for necessário reemitir o contrato.

ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /refinancing_credit_operation
MÉTODO PUT

Testar no Playground

**Request Body**

```json
{
    "financial": {
        "interest_type": "pre_price_days",
        "first_due_date": "2024-06-10",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "monthly_interest_rate": 0.0167,
        "installment_face_value": 410,
        "limit_days_to_disburse": 7,
        "number_of_installments": 84
    },
    "disbursement_bank_account": {
        "account_digit": "1",
        "account_number": "00001",
        "bank_code": "033",
        "branch_number": "0001"
    }
}
```

A resposta (`200`) retorna o objeto da operação de refinanciamento — mesma estrutura apresentada no [Fluxo Completo](/documentation/guides/INSS/portability+refinancing/end-to-end).

:::caution Reassinatura obrigatória
A `credit_operation_key`, a `document_key`, a `document_url`, a `related_party_key` e a `borrower.related_party_key` **mudam** após essa ação, sendo necessária a **reassinatura da CCB**.
:::

---

## Recálculo sem nova CCB

Recalcula o **valor da parcela** da operação de refinanciamento **sem gerar uma nova CCB**. O novo valor de parcela deve ser **menor** que o original.

ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /refinancing_credit_operation/recalculate
MÉTODO PUT

Testar no Playground

**Request Body**

```json
{
    "financial": {
        "interest_type": "pre_price_days",
        "first_due_date": "2024-06-10",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "monthly_interest_rate": 0.0167,
        "installment_face_value": 410,
        "limit_days_to_disburse": 7,
        "number_of_installments": 84
    },
    "disbursement_bank_account": {
        "account_digit": "1",
        "account_number": "00001",
        "bank_code": "033",
        "branch_number": "0001"
    }
}
```

A resposta (`200`) retorna o objeto da operação de refinanciamento — mesma estrutura apresentada no [Fluxo Completo](/documentation/guides/INSS/portability+refinancing/end-to-end).

:::caution Atenção
O novo `installment_face_value` precisa ser **menor** que o valor original. A redução do valor de troco para o tomador não pode ultrapassar **30%** (caso contrário, retornamos [`CT000105`](#errors)).
:::

---

## Carência

Conforme a IN 204, as operações de INSS podem ter **carência** (`number_of_grace_periods`), informada dentro de `collateral_data` na criação da proposta. Tanto a **correção com nova CCB** quanto o **recálculo** permitem **alterar ou remover** essa carência, enviando o objeto `collateral_data` no corpo da requisição.

collateral_data.number_of_grace_periods
integer
opcional
Número de meses de carência (de 0 a 3). Aplica-se à garantia social_security da operação.

| Valor enviado | Comportamento |
|---------------|---------------|
| `1`, `2` ou `3` | **Define/atualiza** a carência da operação. |
| `0` | **Remove** a carência previamente informada. |
| Campo ausente (sem `collateral_data`) | Mantém a carência atual, sem alteração. |
| Fora do intervalo (`< 0` ou `> 3`) | Erro [`CT000090`](#errors). |

**Exemplo — removendo a carência no recálculo**

```json
{
    "financial": {
        "installment_face_value": 380,
        "number_of_installments": 84,
        "monthly_interest_rate": 0.0166
    },
    "disbursement_bank_account": {
        "account_digit": "1",
        "account_number": "00001",
        "bank_code": "033",
        "branch_number": "0001"
    },
    "collateral_data": {
        "number_of_grace_periods": 0
    }
}
```

:::info
Ao alterar a carência, a **primeira data de vencimento** (`first_due_date`) é recalculada junto à Dataprev a partir do novo número de meses de carência.
:::

---

## Erros {#errors}

| Código HTTP | Código QI | Descrição |
|-------------|-----------|-----------|
| 404 | `CT000002` | Proposta não encontrada. |
| 404 | `CT000043` | Operação de refinanciamento não encontrada. |
| 400 | `CT000046` | O status da operação de refinanciamento não permite essa operação. |
| 400 | `CT000079` | Operação de refinanciamento não pode estar constituída (averbada) para alterar dados. |
| 400 | `CT000090` | Número de carências inválido. O intervalo aceito é de 0 a 3. |
| 400 | `CT000100` | O valor do desembolso final é inferior ao mínimo permitido. |
| 400 | `CT000105` | A redução do valor de troco para o tomador não pode ser maior que 30%. |
| 400 | `CT000133` | Prêmio de seguro QI não é permitido para INSS. |

---

# Simulação da Proposta

URL: /documentation/guides/INSS/portability+refinancing/simulacao

Simulação da Proposta

Simula a proposta de portabilidade e/ou refinanciamento (o Troco) a partir do saldo devedor informado, antes da digitação.

Próximo passo: [Digitação da Proposta](/documentation/guides/INSS/portability+refinancing/proposta).

:::caution Atenção
Para propostas que envolvam troco após o refinanciamento, é necessário o valor do troco calculado de acordo com as condições do contrato seja de pelo menos 5% da diferença entre a soma de todas as parcelas do refinanciamento subtraida da soma de todas as parcelas da portabilidade. Caso contrário, a requisição receberá o seguinte erro:

STATUS 400

**Response Body**

```json
{
    "title": "Bad Request", 
    "code": "CT000118",
    "description": "The final disbursement amount is less than 5% of the sum of refinancing installment minus the sum of portability installment. The minimum final disbursement amount allowed is 500.00. Calculated final disbursement amount: 400.00.", 
    "translation": "O valor do troco é menor que 5% da soma do valor das parcelas do refinanciamento menos o valor soma das parcelas da portabilidade. O valor mínimo do troco permitido é de 500.00. Valor calculado do troco: 400.00."
}

```
:::

        **3.1. Simulação de Portabilidade com Refinanciamento:** 
Antes de realizar a digitação da Proposta de Portabilidade com Refinanciamento, é possível simular as condições financeiras da proposta, sem a necessidade de coletar os dados cadastrais do cliente.

**Ver exemplos de payload (Taxa Fixa / Valor Liberado Fixo)**

**Com Taxa Fixa**

        **3.1.1. Simulação de Portabilidade com Refinanciamento, com taxa fixa:**
Assim como na Digitação da Proposta (4.1.1), é possível realizar a simulação fixando a taxa do contrato:

        **Request**
- MÉTODO POST
- STATUS /v2/credit_transfer/proposal_simulation

        *Request:*

**body.json**

```json
{
	"borrower": {
		"person_type": "natural"
	},
	"collaterals": [{
		"collateral_type": "social_security"
	}],
	"portability_credit_operation": {
		"financial": {
			"monthly_interest_rate": 0.0132,
			"number_of_installments": 10
		}
	},
	"refinancing_credit_operation": {
		"financial": {
                        "days_to_accrual": 0,
			"monthly_interest_rate": 0.0132,
			"installment_face_value": 100,
			"number_of_installments": 10
		}
	},
	"origin_contract": {
		"last_due_balance": 997.87
	}
}
```

:::info
No payload acima, são descritos os dados mínimos para realização da simulação.
:::

        **Response**
- MÉTODO POST
- STATUS /v2/credit_transfer/proposal_simulation

        *Payload:*

**response.json**

```json

{
    "borrower": {
        "individual_document_number": "98765432100",
        "related_party_key": "fa55dca3-3147-45d2-bb8d-941f2d7191da",
        "role_type": "issuer"
    },
    "portability_credit_operation": {
        "credit_operation_key": "a66675e6-bdc2-4468-8420-2889d5cec0a8",
        "credit_operation_status": "waiting_signature",
        "disbursement_accounts": [],
        "disbursement_options": [
            {
                "annual_cet": 0.173044,
                "cet": 0.0134,
                "contract_fee_amount": 0.0,
                "contract_fees": [
                    {
                        "amount": 0.5,
                        "amount_type": "percentage",
                        "fee_amount": 0.0,
                        "fee_type": "tac"
                    }
                ],
                "disbursed_issue_amount": 997.87,
                "disbursement_date": "2023-12-22",
                "external_contract_fee_amount": 0.0,
                "external_contract_fees": [
                    {
                        "amount": 0.0,
                        "amount_released": 0,
                        "amount_type": "absolute",
                        "cofins_amount": 0,
                        "csll_amount": 0,
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "spread",
                        "irrf_amount": 0,
                        "net_fee_amount": 0.0,
                        "pis_amount": 0,
                        "tax_amount": 0.0
                    },
                    {
                        "amount": 0.0,
                        "amount_released": 0,
                        "amount_type": "absolute",
                        "cofins_amount": 0,
                        "csll_amount": 0,
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "tac",
                        "irrf_amount": 0,
                        "net_fee_amount": 0.0,
                        "pis_amount": 0,
                        "tax_amount": 0.0
                    },
                    {
                        "amount": 0.0,
                        "amount_released": 0,
                        "amount_type": "absolute",
                        "cofins_amount": 0,
                        "csll_amount": 0,
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "insurance_premium",
                        "irrf_amount": 0,
                        "net_fee_amount": 0.0,
                        "pis_amount": 0,
                        "tax_amount": 0.0
                    }
                ],
                "installments": [
                    {
                        "business_due_date": "2024-02-22",
                        "calendar_days": 62,
                        "due_date": "2024-02-22",
                        "due_principal": 997.87,
                        "installment_number": 1,
                        "pre_fixed_amount": 27.413791524708554,
                        "principal_amortization_amount": 81.34620847529145,
                        "total_amount": 108.76,
                        "workdays": 40
                    },
                    {
                        "business_due_date": "2024-03-22",
                        "calendar_days": 29,
                        "due_date": "2024-03-22",
                        "due_principal": 916.5237915247086,
                        "installment_number": 2,
                        "pre_fixed_amount": 11.692366920719124,
                        "principal_amortization_amount": 97.06763307928088,
                        "total_amount": 108.76,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2024-04-22",
                        "calendar_days": 31,
                        "due_date": "2024-04-22",
                        "due_principal": 819.4561584454277,
                        "installment_number": 3,
                        "pre_fixed_amount": 11.179911547915339,
                        "principal_amortization_amount": 97.58008845208467,
                        "total_amount": 108.76,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2024-05-22",
                        "calendar_days": 30,
                        "due_date": "2024-05-22",
                        "due_principal": 721.876069993343,
                        "installment_number": 4,
                        "pre_fixed_amount": 9.5288330736045,
                        "principal_amortization_amount": 99.2311669263955,
                        "total_amount": 108.76,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2024-06-24",
                        "calendar_days": 33,
                        "due_date": "2024-06-24",
                        "due_principal": 622.6449030669476,
                        "installment_number": 5,
                        "pre_fixed_amount": 9.046812945831448,
                        "principal_amortization_amount": 99.71318705416856,
                        "total_amount": 108.76,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2024-07-22",
                        "calendar_days": 28,
                        "due_date": "2024-07-22",
                        "due_principal": 522.9317160127789,
                        "installment_number": 6,
                        "pre_fixed_amount": 6.439743824282488,
                        "principal_amortization_amount": 102.32025617571752,
                        "total_amount": 108.76,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2024-08-22",
                        "calendar_days": 31,
                        "due_date": "2024-08-22",
                        "due_principal": 420.61145983706143,
                        "installment_number": 7,
                        "pre_fixed_amount": 5.738438681013405,
                        "principal_amortization_amount": 103.0215613189866,
                        "total_amount": 108.76,
                        "workdays": 23
                    },
                    {
                        "business_due_date": "2024-09-23",
                        "calendar_days": 32,
                        "due_date": "2024-09-23",
                        "due_principal": 317.58989851807485,
                        "installment_number": 8,
                        "pre_fixed_amount": 4.473657660291388,
                        "principal_amortization_amount": 104.28634233970861,
                        "total_amount": 108.76,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2024-10-22",
                        "calendar_days": 29,
                        "due_date": "2024-10-22",
                        "due_principal": 213.30355617836625,
                        "installment_number": 9,
                        "pre_fixed_amount": 2.721176981322744,
                        "principal_amortization_amount": 106.03882301867725,
                        "total_amount": 108.76,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2024-11-22",
                        "calendar_days": 31,
                        "due_date": "2024-11-22",
                        "due_principal": 107.26473315968899,
                        "installment_number": 10,
                        "pre_fixed_amount": 1.4934220715493307,
                        "principal_amortization_amount": 107.26657792845067,
                        "total_amount": 108.76,
                        "workdays": 22
                    }
                ],
                "issue_amount": 997.87,
                "number_of_installments": 10,
                "prefixed_interest_rate": {
                    "annual_rate": 0.17042118,
                    "daily_rate": 0.00043722,
                    "interest_base": "calendar_days",
                    "monthly_rate": 0.0132
                },
                "total_iof": 0.0
            }
        ],
        "final_disbursement_amount": 0.0
    },
    "proposal_key": "28a925f6-570e-4724-9132-3bd42f267c4f",
    "proposal_number": "17032788499215403",
    "proposal_status": "pending_submission",
    "refinancing_credit_operation": {
        "credit_operation_key": "aaf9abe0-2b8a-4688-8e09-413e1bd5285e",
        "credit_operation_status": "waiting_signature",
        "disbursement_accounts": [],
        "disbursement_options": [
            {
                "annual_cet": 0.172031,
                "cet": 0.0133,
                "contract_fee_amount": -0.4,
                "contract_fees": [
                    {
                        "amount": 0.5,
                        "amount_type": "percentage",
                        "fee_amount": -0.4,
                        "fee_type": "tac"
                    }
                ],
                "disbursed_issue_amount": 918.04,
                "disbursement_date": "2023-12-22",
                "external_contract_fee_amount": 0.0,
                "external_contract_fees": [
                    {
                        "amount": 0.0,
                        "amount_released": 0,
                        "amount_type": "absolute",
                        "cofins_amount": 0,
                        "csll_amount": 0,
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "spread",
                        "irrf_amount": 0,
                        "net_fee_amount": 0.0,
                        "pis_amount": 0,
                        "tax_amount": 0.0
                    },
                    {
                        "amount": 0.0,
                        "amount_released": 0,
                        "amount_type": "absolute",
                        "cofins_amount": 0,
                        "csll_amount": 0,
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "tac",
                        "irrf_amount": 0,
                        "net_fee_amount": 0.0,
                        "pis_amount": 0,
                        "tax_amount": 0.0
                    },
                    {
                        "amount": 0.0,
                        "amount_released": 0,
                        "amount_type": "absolute",
                        "cofins_amount": 0,
                        "csll_amount": 0,
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "insurance_premium",
                        "irrf_amount": 0,
                        "net_fee_amount": 0.0,
                        "pis_amount": 0,
                        "tax_amount": 0.0
                    }
                ],
                "installments": [
                    {
                        "business_due_date": "2024-02-22",
                        "calendar_days": 62,
                        "due_date": "2024-02-22",
                        "due_principal": 917.64,
                        "installment_number": 1,
                        "pre_fixed_amount": 25.2095730147,
                        "principal_amortization_amount": 74.7904269853,
                        "total_amount": 100.0,
                        "workdays": 40
                    },
                    {
                        "business_due_date": "2024-03-22",
                        "calendar_days": 29,
                        "due_date": "2024-03-22",
                        "due_principal": 842.8495730147,
                        "installment_number": 2,
                        "pre_fixed_amount": 10.7524369787,
                        "principal_amortization_amount": 89.2475630213,
                        "total_amount": 100.0,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2024-04-22",
                        "calendar_days": 31,
                        "due_date": "2024-04-22",
                        "due_principal": 753.6020099934,
                        "installment_number": 3,
                        "pre_fixed_amount": 10.2814172859,
                        "principal_amortization_amount": 89.7185827141,
                        "total_amount": 100.0,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2024-05-22",
                        "calendar_days": 30,
                        "due_date": "2024-05-22",
                        "due_principal": 663.8834272793,
                        "installment_number": 4,
                        "pre_fixed_amount": 8.7632941742,
                        "principal_amortization_amount": 91.2367058258,
                        "total_amount": 100.0,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2024-06-24",
                        "calendar_days": 31,
                        "due_date": "2024-06-22",
                        "due_principal": 572.6467214535,
                        "installment_number": 5,
                        "pre_fixed_amount": 7.8126464787,
                        "principal_amortization_amount": 92.1873535213,
                        "total_amount": 100.0,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2024-07-22",
                        "calendar_days": 30,
                        "due_date": "2024-07-22",
                        "due_principal": 480.4593679322,
                        "installment_number": 6,
                        "pre_fixed_amount": 6.3420966342,
                        "principal_amortization_amount": 93.6579033658,
                        "total_amount": 100.0,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2024-08-22",
                        "calendar_days": 31,
                        "due_date": "2024-08-22",
                        "due_principal": 386.8014645664,
                        "installment_number": 7,
                        "pre_fixed_amount": 5.2771618926,
                        "principal_amortization_amount": 94.7228381074,
                        "total_amount": 100.0,
                        "workdays": 23
                    },
                    {
                        "business_due_date": "2024-09-23",
                        "calendar_days": 31,
                        "due_date": "2024-09-22",
                        "due_principal": 292.078626459,
                        "installment_number": 8,
                        "pre_fixed_amount": 3.9848593609,
                        "principal_amortization_amount": 96.0151406391,
                        "total_amount": 100.0,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2024-10-22",
                        "calendar_days": 30,
                        "due_date": "2024-10-22",
                        "due_principal": 196.0634858199,
                        "installment_number": 9,
                        "pre_fixed_amount": 2.5880710578,
                        "principal_amortization_amount": 97.4119289422,
                        "total_amount": 100.0,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2024-11-22",
                        "calendar_days": 31,
                        "due_date": "2024-11-22",
                        "due_principal": 98.6515568777,
                        "installment_number": 10,
                        "pre_fixed_amount": 1.3459361963,
                        "principal_amortization_amount": 98.6540638037,
                        "total_amount": 100.0,
                        "workdays": 22
                    }
                ],
                "issue_amount": 917.64,
                "number_of_installments": 10,
                "prefixed_interest_rate": {
                    "annual_rate": 0.17042118,
                    "daily_rate": 0.00043722,
                    "interest_base": "calendar_days",
                    "monthly_rate": 0.0132
                },
                "total_iof": 0.0
            }
        ],
        "final_disbursement_amount": -79.83
    }
}

```

**Com Valor Liberado Fixo**

        **3.1.2. Simulação de Portabilidade com Refinanciamento, com valor liberado fixo:** 
Assim como na digitação da proposta (**4.1.2**), é possível realizar a simulação fixando o valor liberado ao cliente:

        **Request**
- MÉTODO POST
- STATUS /v2/credit_transfer/proposal_simulation

        *Payload:*

**payload.json**

```json

{
	"borrower": {
		"person_type": "natural"
	},
	"collaterals": [{
		"collateral_type": "social_security"
	}],
	"portability_credit_operation": {
		"financial": {
			"installment_face_value": 100,
			"number_of_installments": 10
		}
	},
	"refinancing_credit_operation": {
		"financial": {
            "days_to_accrual": 0,
            "disbursed_amount": 1000,
			"installment_face_value": 100,
			"number_of_installments": 10
		}
	},
	"origin_contract": {
		"last_due_balance": 997.87
	}
}
```

        **Response**
- MÉTODO POST
- STATUS /v2/credit_transfer/proposal_simulation

        *Payload:*

**payload.json**

```json

{
	"portability_credit_operation": {
		"fine_configuration": {
			"contract_fine_rate": 0.02,
			"interest_base": "calendar_days",
			"monthly_rate": 0.01
		},
		"disbursement_options": [{
			"installments": [{
					"bank_slip_key": null,
					"digitable_line": null,
					"business_due_date": "2021-08-09",
					"calendar_days": 53,
					"due_date": "2021-08-08",
					"due_principal": 997.87,
					"installment_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036",
					"installment_number": 1,
					"pre_fixed_amount": 54.84865004983954,
					"principal_amortization_amount": 306.98134995016045,
					"total_amount": 361.83,
					"workdays": 37
				},
				{
					"bank_slip_key": null,
					"digitable_line": null,
					"business_due_date": "2021-09-08",
					"calendar_days": 31,
					"due_date": "2021-09-08",
					"due_principal": 690.89,
					"installment_key": "e8406cdb-844c-4e6d-9620-3635fab9d8d1",
					"installment_number": 2,
					"pre_fixed_amount": 21.964874249804833,
					"principal_amortization_amount": 339.86512575019515,
					"total_amount": 361.83,
					"workdays": 22
				}
			],
			"prefixed_interest_rate": {
				"annual_rate": 0.44556431,
				"daily_rate": 0.00564312,
				"monthly_rate": 0.0556431,
				"interest_base": "calendar_days_365"
			},
			"iof_amount": 0,
			"external_contract_fee_amount": 0,
			"external_contract_fees": [],
			"contract_fee_amount": 0,
			"contract_fees": [],
			"number_of_installments": 2,
			"disbursed_issue_amount": 1000,
			"issue_amount": 1000,
			"disbursement_date": "2021-05-31",
			"cet": 1.212,
			"annual_cet": 32.122
		}]
	},
	"refinancing_credit_operation": {
		"fine_configuration": {
			"contract_fine_rate": 0.02,
			"interest_base": "calendar_days",
			"monthly_rate": 0.01
		},
		"disbursement_options": [{
			"installments": [{
					"bank_slip_key": null,
					"digitable_line": null,
					"business_due_date": "2021-08-09",
					"calendar_days": 53,
					"due_date": "2021-08-08",
					"due_principal": 997.87,
					"installment_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036",
					"installment_number": 1,
					"pre_fixed_amount": 54.84865004983954,
					"principal_amortization_amount": 306.98134995016045,
					"total_amount": 361.83,
					"workdays": 37
				},
				{
					"bank_slip_key": null,
					"digitable_line": null,
					"business_due_date": "2021-09-08",
					"calendar_days": 31,
					"due_date": "2021-09-08",
					"due_principal": 690.89,
					"installment_key": "e8406cdb-844c-4e6d-9620-3635fab9d8d1",
					"installment_number": 2,
					"pre_fixed_amount": 21.964874249804833,
					"principal_amortization_amount": 339.86512575019515,
					"total_amount": 361.83,
					"workdays": 22
				}
			],
			"prefixed_interest_rate": {
				"annual_rate": 0.44556431,
				"daily_rate": 0.00564312,
				"monthly_rate": 0.0556431,
				"interest_base": "calendar_days_365"
			},
			"iof_amount": 0,
			"external_contract_fee_amount": 0,
			"external_contract_fees": [],
			"contract_fee_amount": 0,
			"contract_fees": [],
			"number_of_installments": 2,
			"disbursed_issue_amount": 1000,
			"issue_amount": 1000,
			"disbursement_date": "2021-05-31",
			"cet": 1.212,
			"annual_cet": 32.122
		}]
	}
}

```

        **3.2. Simulação de Portabilidade:**
Também é possível simular as condições financeiras de uma Proposta de Portabilidade (Portabilidade Pura), sem a necessidade de coletar os dados cadastrais do cliente.

        **Request**
- MÉTODO POST
- STATUS /v2/credit_transfer/proposal_simulation

        *Payload:*

**payload.json**

```json
{
	"borrower": {
		"person_type": "natural"
	},
	"collaterals": [{
		"collateral_type": "social_security"
	}],
	"portability_credit_operation": {
		"financial": {
			"monthly_interest_rate": 0.0132,
			"installment_face_value": 100,
			"number_of_installments": 10
		}
	},
	"origin_contract": {
		"last_due_balance": 997.87
	}
}
```
 

        **Response**
- MÉTODO POST
- STATUS /v2/credit_transfer/proposal_simulation

        *Payload:*

**payload.json**

```json
{
	"portability_credit_operation": {
		"fine_configuration": {
			"contract_fine_rate": 0.02,
			"interest_base": "calendar_days",
			"monthly_rate": 0.01
		},
		"disbursement_options": [{
			"installments": [{
					"bank_slip_key": null,
					"digitable_line": null,
					"business_due_date": "2021-08-09",
					"calendar_days": 53,
					"due_date": "2021-08-08",
					"due_principal": 997.87,
					"installment_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036",
					"installment_number": 1,
					"pre_fixed_amount": 54.84865004983954,
					"principal_amortization_amount": 306.98134995016045,
					"total_amount": 361.83,
					"workdays": 37
				},
				{
					"bank_slip_key": null,
					"digitable_line": null,
					"business_due_date": "2021-09-08",
					"calendar_days": 31,
					"due_date": "2021-09-08",
					"due_principal": 690.89,
					"installment_key": "e8406cdb-844c-4e6d-9620-3635fab9d8d1",
					"installment_number": 2,
					"pre_fixed_amount": 21.964874249804833,
					"principal_amortization_amount": 339.86512575019515,
					"total_amount": 361.83,
					"workdays": 22
				}
			],
			"prefixed_interest_rate": {
				"annual_rate": 0.44556431,
				"daily_rate": 0.00564312,
				"monthly_rate": 0.0556431,
				"interest_base": "calendar_days_365"
			},
			"iof_amount": 0,
			"external_contract_fee_amount": 0,
			"external_contract_fees": [],
			"contract_fee_amount": 0,
			"contract_fees": [],
			"number_of_installments": 2,
			"disbursed_issue_amount": 1000,
			"issue_amount": 1000,
			"disbursement_date": "2021-05-31",
			"cet": 1.212,
			"annual_cet": 32.122
		}]
	}
}

```

---

# Enumeradores

URL: /documentation/guides/INSS/reference/enumeradores

Enumeradores

Tabelas de referência compartilhadas por **todos** os fluxos INSS — crédito novo, refinanciamento, portabilidade e cartão consignado. Esta é a única página onde estes enumeradores são definidos; as demais páginas linkam para as âncoras daqui.

:::info Retorno da Dataprev
Os códigos de duas letras (`HW`, `BD`, `CR`…) são os da própria Dataprev. O campo que a QI Tech entrega nos webhooks e nas consultas é o **enumerador**, na segunda coluna.
:::

## Enumeradores Retention Reason {#retention_reason_enumerator}
| Enumerador                               | Descrição                                              |
|------------------------------------------|--------------------------------------------------------|
| **issuer_retention**                     | Retenção do Cliente                                    |
| **different_from_original**              | Condições da proposta divergentes do contrato original |
| **issuer_lawsuit**                       | Cliente com ação judicial                              |
| **insurance_in_progress**                | Indenização de seguro em andamento                     |
| **collateral_in_execution**              | Garantia em Execução                                   |
| **contract_not_found**                   | Contrato não encontrado                                |
| **invalid_contract_type**                | Tipo de contrato inválido                              |
| **portability_in_progress**              | Portabilidade em andamento                             |
| **assigned_contract**                    | Contrato cedido                                        |
| **issuer_document_number_invalid**       | CPF não é do contrato                                  |
| **unrelated_issuer_document_number**     | CPF informado não é o do titular                       |
| **assigned_without_co_obligation**       | Contrato cedido sem coobrigação                        |
| **fgts_in_use**                          | FGTS AMORTIZAR em uso                                  |
| **fgts_funding**                         | FGTS funding                                           |
| **portability_not_requested**            | O cliente não solicitou a portabilidade                |
| **wrong_original_financial_institution** | IF Credora Original Incorreta                          |

## Tabela de retorno de erros Dataprev - averbação {#dataprev_response_enumerator_errors}
| Código Dataprev | Enumerador                                       | Descrição                                                   | Ação Qi              |
|-----------------|--------------------------------------------------|-------------------------------------------------------------|----------------------|
| HW              | consignable_margin_excceded                      | Exceeded consignable margin                                 | Teimosinha           |
| IT              | benefit_blocked_by_tbm                           | Benefit blocked due to benefit transfer                     | Teimosinha           |
| IE              | benefit_blocked_by_beneficiary                   | Benefit blocked by beneficiary                              | Teimosinha           |
| AN              | invalid_disbursement_account                     | Invalid disbursement bank account                           | Pendente de ação do parceiro (corrigir os dados bancários) |
| HX              | reservation_already_included                     | Reservation already included                                | Confirmar averbação  |
| IF              | benefit_blocked_by_granting_process              | Benefit blocked during granting process                     | Teimosinha           |
| AV              | processing_payroll                               | Operation couldn`t be done during processing payroll period | Teimosinha           |
| OF              | invalid_cbc                                      | Invalid cbc                                                 | Teimosinha           |
| IA              | first_name_mismatch                              | First name mismatch benefit owner or legal representative   | Teimosinha           |
| OS              | legal_representative_document_number_mismatch    | Document number mismatch legal representative               | Teimosinha           |
| AY              | invalid_state                                    | Invalid state                                               | Teimosinha           |
| HZ              | operation_not_allowed_on_this_reservation_status | Operation couldn`t be done with current reservation status  | Teimosinha           |
| AP              | invalid_contract_date                            | Accrual, end or start contract date is invalid              | Teimosinha           |
| GA              | required_fields_missing                          | Required fields are missing                                 | Teimosinha           |
| BC              | cbc_missing                                      | CBC is missing                                              | Teimosinha           |
| NC              | contract_number_missing                          | Contract number is missing                                  | Teimosinha           |
| NB              | benefit_number_missing                           | Benefit number is missing                                   | Teimosinha           |
| CA              | invalid_bank_code                                | Invalid bank code                                           | Teimosinha           |
| HR              | exceeded_number_of_allowed_contracts             | Amount of contracts is above the limit                      | Teimosinha           |
| PV              | invalid_image_format                             | Image with wrong format                                     | Teimosinha           |
| IR              | operation_not_allowed_IR                         | Operation date is greater than benefit expiration           | Cancelar             |
| PK              | wrong_bank_code_destination                      | Portability number was found with wrong bank code destination| Teimosinha          |
| PH              | wrong_benefit_number_on_portability              | Portability number was found with wrong benefit number      | Teimosinha           |
| PI              | invalid_contract_total_amount         | Reservation contract total amount should be greater than Dataprev reference amount     | Teimosinha           |

:::danger Atenção!
Todas as taxas e valores do contrato são validados no momento da criação da reserva.

A crítica "invalid_contract_total_amount" ocorre nos casos em que os contratos se estendem por muito tempo sem serem averbados, o que impacta os valores previamente estabelecidos.
:::

## Tabela de retorno de sucesso - averbação {#dataprev_response_enumerator_success}
| Código Dataprev | Enumerador               | Descrição                               |
|--------|--------------------------|-----------------------------------------|
| BD     | successfully_included    | Inclusion has been successfully done    |
| BF     | successfully_removed     | Removal has been successfully done      |
| BR     | successfully_reactivated | Reactivation has been successfully done |
| BS     | successfully_suspended   | Suspension has been successfully done   |

## Tabela de retorno de erros na consulta de saldo {#dataprev_balance_errors_enumerators}
| Código | Enumerador                            | Descrição                                                                       |
|--------|---------------------------------------|---------------------------------------------------------------------------------|
| CR     | not_found_legal_representative        | no legal representative for the beneficiary                                     |
| CD     | inexistent_beneficiary                | no beneficiary found                                                            |
| AS     | benefity_without_legal_representative | beneficiary does not have a legal representative                                |
| BI     | inexistent_benefit                    | no benefit found                                                                |
| D1     | inconsistent_balance_benefit_data     | The balance benefit data registered is either inconsistent, null or incomplete. |

## Tabela de retorno de erros na consulta de benefícios {#dataprev_benefits_errors_enumerators}
| Código | Enumerador                            | Descrição                                                                       |
|--------|---------------------------------------|---------------------------------------------------------------------------------|
| CR     | not_found_legal_representative        | no legal representative for the beneficiary                                     |
| CD     | inexistent_beneficiary                | no beneficiary found                                                            |
| AS     | benefity_without_legal_representative | beneficiary does not have a legal representative                                |

## Tabela de situação de benefícios {#benefit_situation_enumerator}
| Items |
|-------|
| active |
| excluded |
| terminated |
| suspended |
| suspended_by_CONPAG |
| terminated_by_SISOBI |
| receiving_monthly_recover_6_months |
| receiving_monthly_recover_18_months |
| suspended_by_name_error |
| suspended_by_credentialed_payer |
| suspended_by_inspection |
| suspended_by_audit |
| terminated_by_inspection |
| terminated_by_audit |
| receiving_monthly_recover_6_months_inspection |
| receiving_monthly_recover_18_months_inspection |
| suspended_by_SISOBI |
| canceled_by_audit |

## Tabela de status de benefícios {#benefit_status_enumerator}

| Enumerador | Descrição                                           |
|------------|-----------------------------------------------------|
| Elegible   | Elegível para empréstimo                            |
| Inelegible | Benefício inelegível para empréstimo                |
| Blocked    | Benefício elegível, porém bloqueado para empréstimo |

## Tabela de tipos de bloqueio {#block_type_enumerator}

A Dataprev devolve o **código** em `tipoBloqueio.codigo`; a QI Tech entrega o **enumerador** correspondente no campo `block_type`.

| Código Dataprev | Enumerador (`block_type`) | Descrição |
|---|---|---|
| 0 | `not_blocked` | Sem bloqueio |
| 1 | `blocked_by_benefitiary` | Bloqueado pelo Segurado |
| 2 | `blocked_by_tbm` | Bloqueado por TBM |
| 3 | `blocked_in_concession` | Bloqueado na Concessão |

## Tabela de tipos de politicamente exposto {#politically_exposed_enumerator}

| Enumerador | Descrição                                           |
|------------|-----------------------------------------------------|
| 0          | Pessoa Não Exposta Politicamente                    |
| 1          | Pessoa Exposta Politicamente - Nível 1              |

## Tabela de benefícios {#benefit_type_enumerator}

| código   | benefício                                                |
| --- | ------------------------------------------------ |
| 1   | pension_by_death_rural_worker                    |
| 2   | pension_by_death_accident_rural_worker           |
| 3   | pension_by_death_rural_employer                  |
| 4   | retirement_invalidity_rural_emploee              |
| 5   | retirement_invalidity_accident_rural_worker      |
| 6   | retirement_invalidity_rural_employer             |
| 7   | retirement_by_eldness_rural_worker               |
| 8   | retirement_by_age_rural_employer                 |
| 9   | complement_by_work_accident_rural_worker         |
| 11  | support_invalidity_rural_worker                  |
| 12  | support_by_age_rural_worker                      |
| 13  | aid_sickness_rural_worker                        |
| 15  | aid_time_off_rural_worker                        |
| 16  | aid_federal                                      |
| 17  | international_agreement                          |
| 18  | inclusion_benefit                                |
| 19  | pension_student_law7004                          |
| 20  | pension_by_death_diplomat                        |
| 21  | pension_by_death                                 |
| 22  | pension_by_death_statute                         |
| 23  | pension_by_death_veteran                         |
| 24  | pension_special_institutional_act                |
| 25  | aid_time_off                                     |
| 26  | pension_by_death_special_law593                  |
| 27  | pension_by_death_federal_emploee                 |
| 28  | pension_by_death_general_regime_law20465         |
| 29  | pension_by_death_marine_veteran                  |
| 30  | monthly_income_lifetime_invalidity               |
| 31  | aid_sickness                                     |
| 32  | retirement_invalidity_social_security            |
| 33  | retirement_invalidity_aeronautic                 |
| 34  | retirement_invalidity_marine_law1756             |
| 35  | aid_sickness_veteran                             |
| 36  | aid_social_security_accident                     |
| 37  | retirement_capin_extra_emploee                   |
| 38  | retirement_federal_extra_emploee                 |
| 39  | aid_invalidity_student_law7004                   |
| 40  | monthly_income_lifetime_by_age_upper70_law6179   |
| 41  | retirement_by_age                                |
| 42  | retirement_by_contribution_time                  |
| 43  | retirement_by_time_of_service_veteran            |
| 44  | retirement_special_aeronautic                    |
| 45  | retirement_by_time_of_service_journalist         |
| 46  | retirement_special                               |
| 47  | allowance_25                                     |
| 48  | allowance_20                                     |
| 49  | retirement_ordinary                              |
| 50  | aid_sickness_extinct_basic_plan                  |
| 51  | retirement_invalidity_extinct_basic_plan         |
| 52  | retirement_by_age_extinct_basic_plan             |
| 53  | aid_time_off_extinct_basic_plan                  |
| 54  | pension_indemnity_federal                        |
| 55  | pension_by_death_extinct_basic_plan              |
| 56  | pension_lifetime_syndrome_thalidomide            |
| 57  | retirement_by_teacher_labor_time                 |
| 58  | retirement_anisty                                |
| 59  | pension_by_death_amnesty                         |
| 60  | indemnity                                        |
| 61  | aid_birth                                        |
| 62  | aid_funeral                                      |
| 63  | aid_funeral_rural_worker                         |
| 64  | aid_funeral_rural_employer                       |
| 65  | savings_special_autarchy                         |
| 67  | savings_mandatory_ipase_law5128                  |
| 68  | savings_special_retirement_ps_affiliated_upper60 |
| 69  | savings_student_law7004                          |
| 70  | restitution                                      |
| 71  | monthly_income                                   |
| 72  | retirement_by_time_of_service_law1756            |
| 73  | monthly_income_family_statute                    |
| 74  | complement_pension_federal                       |
| 75  | complement_retirement_federal                    |
| 76  | monthly_income_statute                           |
| 77  | monthly_income_sinpas_family_statute             |
| 78  | retirement_by_age_law1756                        |
| 79  | advantage                                        |
| 80  | monthly_income_maternity                         |
| 81  | compulsory_retirement                            |
| 82  | retirement_by_time_of_service_sasse              |
| 83  | retirement_invalidity_ex_sasse                   |
| 84  | pension_by_death_sasse                           |
| 85  | pension_lifetime_rubber_tapper_law7986           |
| 86  | pension_lifetime_rubber_tapper_dependent_law7986 |
| 87  | continuous_aid_physical_disabilities             |
| 88  | continuous_aid_eldness                           |
| 89  | pension_special_hemodialysis_victim_caruaru      |
| 90  | medic_assistency_work_accident                   |
| 91  | aid_sickness_by_work_accident                    |
| 92  | retirement_invalidity_work_accident              |
| 93  | pension_by_death_work_accident                   |
| 94  | aid_work_accident                                |
| 95  | aid_additional_work_accident                     |
| 96  | pension_special_leprosy_law11520                 |
| 97  | savings_by_death_work_accident                   |
| 98  | aid_longshoreman                                 |
| 99  | time_off_15                                      |

---

# Averbação e Desaverbação

URL: /documentation/guides/INSS/reservations/averbacao-e-desaverbacao

Averbação e Desaverbação

A constituição da garantia na Dataprev depois da formalização: os webhooks de sucesso e falha, a retentativa automática ("teimosinha"), a correção de dados e a desaverbação.

A garantia só está de fato constituída (`collateral_constituted: true`) depois da averbação aceita. Para os motivos de falha, veja [Enumeradores](/documentation/guides/INSS/reference/enumeradores#dataprev_response_enumerator_errors).

:::caution Atenção
	Para que o pedido de averbação seja criado com sucesso, é preciso que seja feita uma consulta de dados válida para o benefício **previamente**. 
	Para isso basta seguir os passos do item [2 - Consulta de dados do benefício](/documentation/guides/INSS/inquiries/dados-do-beneficio).
:::
## Falha na averbação por margem exedida
Se uma reserva com categoria de novo beneficiário ou de aumento salarial receber margem excedida na tentativa de averbação, o status do pedido de averbação ficará como "aguardando ação do parceiro", e será enviado um webhook no seguinte formato para informar o ocorrido:

WEBHOOK_TYPE social_security_margin_exceeded_for_new_beneficiary ou social_security_margin_exceeded_for_minimum_wage_increase
STATUS Pending requester action

Webhook Body

**Novo Beneficiario**

```json
{
    "webhook": {
        "key": "<DEBT-KEY>",
        "data": {
            "enumerator": "margin_exceeded_for_new_beneficiary",
            "description": "The margin for this reservation has been exceeded. Reservation Amount: 551.18",
        },
        "status": "pending_requester_action",
        "webhook_type": "social_security_margin_exceeded_for_new_beneficiary",
        "event_datetime": "2024-10-15T15:33:59"
    }
}
```
  
**Aumento Salarial**

```json
{
    "webhook": {
        "key": "<DEBT-KEY>",
        "data": {
            "enumerator": "margin_exceeded_for_minimum_wage_increase",
            "description": "The margin for this reservation has been exceeded. Reservation Amount: 551.18",
        },
        "status": "pending_requester_action",
        "webhook_type": "social_security_margin_exceeded_for_minimum_wage_increase",
        "event_datetime": "2024-10-15T15:33:59"
    }
}
```

## Falha na averbação por falta de uma consulta de dados válida do benefício

Se uma consulta dos dados do benefício não for realizada com sucesso antes do pedido de averbação, o status do pedido de averbação ficará como "aguardando ação do parceiro" e será enviado um webhook no seguinte formato para informar o ocorrido:

WEBHOOK_TYPE social_security_success_balance_request_not_found
STATUS Pending requester action

Webhook Body

```json
{
    "webhook": {
        "key": "<DEBT-KEY>",
        "data": {
            "enumerator": "success_balance_request_not_found",
            "description": "Success balance request not found for the specified benefit number"
        },
        "status": "pending_requester_action",
        "webhook_type": "social_security_success_balance_request_not_found",
        "event_datetime": "2024-10-15T15:33:59"
    }
}
```

Para prosseguir, as seguintes ações deverão ser tomadas:

1. Realizar a consulta dos dados do benefício em questão seguindo os passos do item 2 - [Consulta de dados do benefício](/documentation/guides/INSS/inquiries/dados-do-beneficio);  
2. Enviar uma requisição no formato abaixo para informar que a consulta foi realizada.

ENDPOINT /social_security/reservation/external_key/ DEBT-KEY /validate_reservation
MÉTODO POST

Testar no Playground

:::info Importante
	Essa requisição não apenas confirma a existência de uma consulta válida dos dados do benefício, mas também verifica se as informações enviadas para a criação da averbação estão corretas, permitindo assim a continuidade do processo.
:::

## Sistema de priorização de requisições (Fura fila)

Devido à limitação da Dataprev, que permite no máximo **25 requisições por segundo**, o sistema de requisições opera de maneira assíncrona, ou seja, as tentativas de averbação são organizadas em uma fila para processamento. Dessa forma, as requisições são priorizadas com base no tipo de operação e probabilidade de sucesso. 

Nesse contexto, pensando em evitar a perda de margem em situações em que há alta probabilidade de sucesso na averbação, mas ainda vai demorar para ocorrer a próxima tentativa de averbação, foi desenvolvido esse sistema que permite realizar uma requisição de forma síncrona, ou seja, sem precisar esperar passar pela fila.

Todavia, para garantir o controle adequado e evitar o uso indevido desse sistema, foi implementado um mecanismo de **balde de fichas**, que funciona da seguinte forma:

- Cada requisição consome uma ficha para ser realizada;
- Se a requisição resultar em uma averbação bem-sucedida, a ficha é devolvida ao balde;
- Caso contrário, a ficha é perdida;
- Existe um limite máximo de fichas por balde;
- Uma rotina de reposição de fichas é ativada periodicamente, para reabastecer as fichas perdidas até atingir o limite máximo;
- Se as fichas se esgotarem, novas requisições não poderão ser feitas até que a rotina reponha uma nova ficha.

Exemplo Sistema de Balde

Nesse exemplo, a configuração do balde é:
- **Número máximo de fichas:** 10
- **Tempo de reposição:** 30min

**HORA 0:** O balde é criado com sua capacidade máxima; 

**9min:** Uma requisição é feita, mas o contrato não é averbado (erro), ocasionando na perda de 1 ficha;

**17min:** Uma requisição é feita e o contrato é averbado (sucesso), mantendo inalterado o número de fichas;

**30min:** Ocorre a primeira reposição de fichas, levando o balde a sua capacidade máxima novamente;

**47min:** 10 requisições são realizadas com sucesso e nenhuma ficha é perdida;

**1h:** Ocorre a segunda reposição de fichas, mas como o balde já está cheio, o número de fichas permanece inalterado;

**1:12h:** 5 requisições são realizadas com erro, levando a perda de 5 fichas;

**1:30h:** Ocorre a terceira reposição de fichas, deixando o balde com 6 fichas;

**1:38h:** 6 requisições são realizadas com erro, esgotando todas as fichas;

**1:51h:** Uma tentativa de requisição é feita, mas como o balde não possui nenhuma ficha, a requisição é barrada;

**2h:** Ocorre a quarta reposição de fichas, levando a balde a 1 ficha e permitindo novas tentativas de requisições;

Para fazer a requisição prioritária, basta bater no seguinte endpoint utilizando a DEBT-KEY correspondente à operação que deseja averbar:

### Request

ENDPOINT /social_security/reservation/external_key/ DEBT-KEY /priority_request
MÉTODO POST

Testar no Playground

### Response

Response Body - Sucesso
```json
{
    "max_bucket_capacity": 10, 
    "bucket_fill_rate_minutes": 30, 
    "available_tokens": 7, 
    "status": "pending_document_submission", 
    "next_refill_at": "2025-02-04T20:28:35Z"
}
```

Response Body - Erros

```json
Erro na averbação:
{
    "title": "Reservation Failed", 
    "description": "Last Response: consignable_margin_excceded, Tokens Available: 9, Next Refill At: 2025-02-04T20:18:35Z", 
    "translation": "Ultima resposta: consignable_margin_excceded, Fichas disponiveis: 9, Proxima Recarga: 2025-02-04T20:18:35Z", 
    "extra_fields": {}, 
    "code": "SSC000083"
}

Erro de nenhuma ficha disponível:
{
    "title": "Rate limit exceeded", 
    "description": "Request limit exceeded. No tokens available, next refill in 8 minutes.", 
    "translation": "Limite de solicitacoes excedido. Nenhuma ficha disponivel, proxima recarga em 8 minutos.", 
    "extra_fields": {}, 
    "code": "SSC000080"
}

```

Por fim, é possível consultar as configurações atuais do balde sem a necessidade de realizar uma requisição no endpoint de priorização. Para isso, disponibilizamos o seguinte endpoint para consulta:

### Request

ENDPOINT /social_security/bucket_configuration
MÉTODO GET

Testar no Playground

### Response

Response Body

```json
{
    "max_bucket_capacity": 10, 
    "bucket_fill_rate_minutes": 30, 
    "available_tokens": 7, 
    "next_refill_at": "2025-02-04T20:08:35Z"
}

```

## Sucesso na averbação
Em caso de sucesso na averbação o parceiro receberá o seguinte webhook:

WEBHOOK_TYPE credit_operation.collateral
STATUS Success

Webhook Body

```json
{
	"key": "<DEBT-KEY>",
	"data": {
		"collateral_type": "social_security",
		"collateral_constituted": true
	},
	"event_time": "2022-10-31 15:23:46",
	"webhook_type": "credit_operation.collateral"
}
```

## Correção de dados no caso de falha na averbação
É possível corrigir os dados bancários, número do benefício e o nome do contrato em tentativa de averbação. Para isso basta utilizar a seguinte chamada:

ENDPOINT /debt/ DEBT-KEY /collateral
MÉTODO PATCH

Testar no Playground

Request Body

**Dados Bancários**

```json
{
	"disbursement_bank_account": {
		"bank_code": "123",
		"account_digit": "1",
		"account_branch": "1234",
		"account_number": "5678",
		"document_number": "12345678901"
	}
}

```
  
**Número do Benefício**

```json
{
	"benefit_number": 1234567890
}
```

**Nome**

```json
{
	"name": "Nome do Beneficiário"
}
```

## Desaverbação

A desaverbação de um contrato é realizada através da rota de cancelamento permanente. Essa rota coloca um status final no contrato, o qual não é passível de retentativa e dispara a desaverbação da margem averbada.

Para realizar o cancelamento definitivo, deve ser utilizado o seguinte endpoint:

ENDPOINT /debt/ DEBT-KEY /cancel_permanently
MÉTODO POST

Testar no Playground

### Webhooks

WEBHOOK_TYPE debt
STATUS canceled_permanently
Webhook Body

```json
{
	"key": "<DEBT-KEY>",
	"data": {},
	"status": "canceled_permanently",
	"webhook_type": "debt",
	"event_datetime": "2022-11-01 03:46:31"
}
```

---

# Fura-fila (priority request)

URL: /documentation/guides/INSS/reservations/priority-request

Fura-fila (priority request)

Mecanismo para tentar uma **averbação de forma síncrona**, sem esperar a fila assíncrona da Dataprev, usando um **balde de fichas** por requester. Cada chamada consome uma ficha; em caso de sucesso na averbação a ficha pode ser devolvida; em falha, a ficha é perdida até a próxima reposição periódica.

:::info Não confunda com reserva prioritária (fixed rate)
Este guia trata de **`POST …/priority_request`** e **`GET /social_security/bucket_configuration`** (balde de fichas / fura-fila). É **diferente** da marcação de reserva **`fixed_rate`** em [Reserva prioritária (fixed rate)](/documentation/guides/INSS/reservations/priority-reservation) (`PATCH` / `DELETE` em `/priority_reservation`).
:::

## Contexto

A Dataprev limita o throughput (**ordem de 25 requisições por segundo**). Por isso as tentativas de averbação costumam ser processadas em **fila**. O endpoint `priority_request` permite pular essa fila quando há **ficha disponível** no balde.

**Resumo do balde:**

- Cada requisição **consome** uma ficha.
- Averbação **bem-sucedida** → a ficha pode ser **devolvida** ao balde.
- Averbação com **erro** → a ficha é **perdida** até a reposição.
- Existe **capacidade máxima** e **intervalo de reposição** configurados para o seu requester.
- Sem fichas → nova tentativa falha até a próxima reposição.

**Exemplo ilustrativo do balde**

Configuração de exemplo: **10 fichas** máximas, **30 minutos** entre reposições.

**Hora 0:** balde criado na capacidade máxima.

**9 min:** uma requisição falha na averbação → perde 1 ficha.

**17 min:** uma requisição tem sucesso → número de fichas inalterado.

**30 min:** primeira reposição → balde volta ao máximo.

**47 min:** dez requisições com sucesso → nenhuma ficha perdida.

**1 h:** segunda reposição; se o balde já estiver cheio, nada muda.

**1 h 12 min:** cinco falhas → perda de 5 fichas.

**1 h 30 min:** terceira reposição → ex.: 6 fichas disponíveis.

**1 h 38 min:** seis falhas → balde esgota.

**1 h 51 min:** tentativa sem fichas → barrada.

**2 h:** quarta reposição → novas tentativas liberadas.

Para o passo a passo completo da operação (validação de reserva, webhooks de sucesso, correção de dados), veja o [Fluxo completo — crédito novo e refinanciamento](/documentation/guides/INSS/new-credit-and-refinancing/end-to-end#sistema-de-priorização-de-requisições-fura-fila).

---

## Disparar requisição prioritária

Request

ENDPOINT /social_security/reservation/external_key/ EXTERNAL_KEY /priority_request
MÉTODO POST

Path params

external_key
string
obrigatório
Chave da operação no fluxo (mesmo conceito de DEBT-KEY nos roteiros INSS ou payroll_card_reservation_key nos fluxos de cartão consignado INSS).

**Body:** não há corpo na requisição.

Testar no Playground

**Python**

```python title="ENDPOINT"
POST /social_security/reservation/external_key/YOUR_EXTERNAL_KEY/priority_request
```

**curl**

```bash title="ENDPOINT"
curl -X POST \
  'https://api-auth.sandbox.qitech.app/social_security/reservation/external_key/YOUR_EXTERNAL_KEY/priority_request' \
  -H 'AUTHORIZATION: eyJhbGciOiJFUzUxMiJ9.eyJwYXlsb2FkX21kNSI6...' \
  -H 'API-CLIENT-KEY: YOUR_API_CLIENT_KEY' \
  -H 'SELECTED-AGENT: YOUR_REQUESTER_KEY' \
  -H 'Content-Type: application/json'
```

Response (sucesso)

STATUS 200

Atributos

max_bucket_capacity
integer
Capacidade máxima do balde (fichas).

bucket_fill_rate_minutes
integer
Intervalo de reposição, em minutos.

available_tokens
integer
Fichas disponíveis após a operação.

status
string
Status da reserva após a tentativa (ex.: pending_document_submission ).

next_refill_at
string
Próximo instante de reposição do balde (ISO 8601).

:::tip Webhook de sucesso
Se a averbação for concluída com sucesso, o parceiro recebe o webhook credit_operation.collateral com status de sucesso. Detalhes no [mesmo capítulo do fluxo completo](/documentation/guides/INSS/new-credit-and-refinancing/end-to-end#sucesso-na-averbação).
:::

```json title="RESPONSE BODY"
{
  "max_bucket_capacity": 10,
  "bucket_fill_rate_minutes": 30,
  "available_tokens": 7,
  "status": "pending_document_submission",
  "next_refill_at": "2025-02-04T20:28:35Z"
}
```

---

## Consultar configuração do balde

Permite ver capacidade, fichas disponíveis e próxima reposição **sem** disparar uma requisição prioritária.

Request

ENDPOINT /social_security/bucket_configuration
MÉTODO GET

Sem path params nem query obrigatórios.

Testar no Playground

**Python**

```python title="ENDPOINT"
GET /social_security/bucket_configuration
```

**curl**

```bash title="ENDPOINT"
curl -X GET \
  'https://api-auth.sandbox.qitech.app/social_security/bucket_configuration' \
  -H 'AUTHORIZATION: eyJhbGciOiJFUzUxMiJ9.eyJwYXlsb2FkX21kNSI6...' \
  -H 'API-CLIENT-KEY: YOUR_API_CLIENT_KEY' \
  -H 'SELECTED-AGENT: YOUR_REQUESTER_KEY' \
  -H 'Content-Type: application/json'
```

Response

STATUS 200

Atributos

max_bucket_capacity
integer
Capacidade máxima do balde.

bucket_fill_rate_minutes
integer
Intervalo de reposição, em minutos.

available_tokens
integer
Fichas disponíveis no momento.

next_refill_at
string
Próxima reposição (ISO 8601).

```json title="RESPONSE BODY"
{
  "max_bucket_capacity": 10,
  "bucket_fill_rate_minutes": 30,
  "available_tokens": 7,
  "next_refill_at": "2025-02-04T20:08:35Z"
}
```

---

## Erros

| HTTP | Código | Título (exemplo) | Quando ocorre |
|------|--------|------------------|---------------|
| 400 / 4xx | SSC000083 | Reservation Failed | Tentativa prioritária executada, mas a averbação falhou (mensagem costuma citar última resposta da Dataprev, fichas restantes e próxima reposição). |
| 429 / 4xx | SSC000080 | Rate limit exceeded | Nenhuma ficha disponível; aguardar a próxima reposição do balde. |

**Exemplos de corpo de erro (JSON)**

```json
{
  "title": "Reservation Failed",
  "description": "Last Response: consignable_margin_excceded, Tokens Available: 9, Next Refill At: 2025-02-04T20:18:35Z",
  "translation": "Ultima resposta: consignable_margin_excceded, Fichas disponiveis: 9, Proxima Recarga: 2025-02-04T20:18:35Z",
  "extra_fields": {},
  "code": "SSC000083"
}
```

```json
{
  "title": "Rate limit exceeded",
  "description": "Request limit exceeded. No tokens available, next refill in 8 minutes.",
  "translation": "Limite de solicitacoes excedido. Nenhuma ficha disponivel, proxima recarga em 8 minutos.",
  "extra_fields": {},
  "code": "SSC000080"
}
```

---

# Fila prioritária

URL: /documentation/guides/INSS/reservations/priority-reservation

Fila prioritária (fixed rate)

Marca a reserva INSS como `fixed_rate`, respeitando o **limite de reservas prioritárias ativas**.

**Quando usar**

- **Desbloqueio:** o benefício está em liberação.
- **Concorrência por margem:** operações concorridas e críticas (ex.: novo entrante).

**Antes de priorizar múltiplas reservas:** `GET /social_security/priority_reservation_configuration` mostra uso atual e limite.

## Status da reserva permitidos

Só é possível **definir** ou **remover** prioridade `fixed_rate` quando a reserva está em um destes status:

| Status | Descrição resumida |
|--------|-------------------|
| `pending_reservation` | Reserva pendente |
| `in_queue_pending_reservation` | Na fila, aguardando reserva |
| `pending_balance_request` | Aguardando consulta de saldo |
| `in_queue_pending_balance_request` | Na fila, aguardando consulta de saldo |

Fora desses status, a API retorna erro indicando status não permitido.

:::tip Limite simultâneo
Se o número de reservas já marcadas como prioritárias atingir o máximo configurado, um novo `PATCH` retorna erro de limite excedido. Use o `GET` de configuração para acompanhar o uso atual sem priorizar outra reserva.
:::

---

## Definir prioridade

Request

ENDPOINT /social_security/reservation/external_key/ EXTERNAL_KEY /priority_reservation
MÉTODO PATCH

Path params

external_key
string
obrigatório
Identificador externo da reserva no seu fluxo (mesmo conceito de DEBT-KEY nos roteiros de crédito consignado INSS).

**Python**

```python title="ENDPOINT"
PATCH /social_security/reservation/external_key/YOUR_EXTERNAL_KEY/priority_reservation
```

**curl**

```bash title="ENDPOINT"
curl -X PATCH \
  'https://api-auth.sandbox.qitech.app/social_security/reservation/external_key/YOUR_EXTERNAL_KEY/priority_reservation' \
  -H 'AUTHORIZATION: eyJhbGciOiJFUzUxMiJ9.eyJwYXlsb2FkX21kNSI6...' \
  -H 'API-CLIENT-KEY: YOUR_API_CLIENT_KEY' \
  -H 'SELECTED-AGENT: YOUR_REQUESTER_KEY' \
  -H 'Content-Type: application/json'
```

Response

STATUS 200

Atributos

external_key
string
Chave externa da reserva.

reservation_priority_type
string
Tipo de prioridade; em sucesso, fixed_rate .

current_number_of_priority_reservations
integer
Quantidade atual de reservas prioritárias do requester após a operação.

max_number_of_priority_reservations
integer
Limite máximo configurado.

```json title="RESPONSE BODY"
{
  "external_key": "550e8400-e29b-41d4-a716-446655440000",
  "reservation_priority_type": "fixed_rate",
  "current_number_of_priority_reservations": 1,
  "max_number_of_priority_reservations": 10
}
```

---

## Remover prioridade

Request

ENDPOINT /social_security/reservation/external_key/ EXTERNAL_KEY /priority_reservation
MÉTODO DELETE

Path params

external_key
string
obrigatório
Identificador externo da reserva.

Remove a prioridade da reserva (`reservation_priority_type` passa a `null`). Exige que a prioridade atual seja `fixed_rate` (se houver outro tipo, a API retorna erro). Status da reserva deve continuar na lista permitida.

**Python**

```python title="ENDPOINT"
DELETE /social_security/reservation/external_key/YOUR_EXTERNAL_KEY/priority_reservation
```

**curl**

```bash title="ENDPOINT"
curl -X DELETE \
  'https://api-auth.sandbox.qitech.app/social_security/reservation/external_key/YOUR_EXTERNAL_KEY/priority_reservation' \
  -H 'AUTHORIZATION: eyJhbGciOiJFUzUxMiJ9.eyJwYXlsb2FkX21kNSI6...' \
  -H 'API-CLIENT-KEY: YOUR_API_CLIENT_KEY' \
  -H 'SELECTED-AGENT: YOUR_REQUESTER_KEY' \
  -H 'Content-Type: application/json'
```

Response

STATUS 200

Atributos

external_key
string
Chave externa da reserva.

reservation_priority_type
null
Sem prioridade após a remoção.

current_number_of_priority_reservations
integer
Contagem após a remoção.

max_number_of_priority_reservations
integer
Limite máximo configurado.

```json title="RESPONSE BODY"
{
  "external_key": "550e8400-e29b-41d4-a716-446655440000",
  "reservation_priority_type": null,
  "current_number_of_priority_reservations": 0,
  "max_number_of_priority_reservations": 10
}
```

---

## Consultar limite e uso atual

Request

ENDPOINT /social_security/priority_reservation_configuration
MÉTODO GET

Retorna o resumo de quantas reservas prioritárias o requester tem no momento, o máximo permitido e a lista completa das reservas atualmente na fila prioritária.

**Python**

```python title="ENDPOINT"
GET /social_security/priority_reservation_configuration
```

**curl**

```bash title="ENDPOINT"
curl -X GET \
  'https://api-auth.sandbox.qitech.app/social_security/priority_reservation_configuration' \
  -H 'AUTHORIZATION: eyJhbGciOiJFUzUxMiJ9.eyJwYXlsb2FkX21kNSI6...' \
  -H 'API-CLIENT-KEY: YOUR_API_CLIENT_KEY' \
  -H 'SELECTED-AGENT: YOUR_REQUESTER_KEY' \
  -H 'Content-Type: application/json'
```

Response

STATUS 200

Atributos

current_number_of_priority_reservations
integer
Reservas prioritárias ativas no momento.

max_number_of_priority_reservations
integer
Teto configurado para o requester.

reservations
array of objects
Lista das reservas atualmente na fila prioritária, ordenadas por fixed_rate_set_at crescente. Máximo de 100 itens.

**Atributos de reservations**

credit_operation_key
string
Chave externa da reserva.

contract_number
string
Número do contrato.

status
string
Status atual da reserva. Valores possíveis: pending_reservation , in_queue_pending_reservation , pending_balance_request , in_queue_pending_balance_request .

type
string
Enumerador do tipo da reserva.

fixed_rate_set_at
string (ISO 8601)
Data e hora em que a reserva foi adicionada à fila prioritária.

```json title="RESPONSE BODY"
{
  "current_number_of_priority_reservations": 2,
  "max_number_of_priority_reservations": 10,
  "reservations": [
    {
      "credit_operation_key": "550e8400-e29b-41d4-a716-446655440000",
      "contract_number": "BYX2000013373",
      "status": "pending_reservation",
      "type": "new",
      "fixed_rate_set_at": "2026-04-13T14:00:00Z"
    }
  ]
}
```

---

## Erros

### PATCH — definir prioridade

| HTTP | Código | Título (exemplo) | Quando ocorre |
|------|--------|------------------|---------------|
| 400 | QIT000006 | Priority reservation configuration not set | Requester sem configuração de prioridade de reserva |
| 400 | QIT000006 | Reservation status not allowed | Status da reserva fora da lista permitida |
| 400 | QIT000006 | Priority reservation limit exceeded | Limite simultâneo atingido |
| 404 | SSC000035 | Reservation not Found | Reserva inexistente para requester + `external_key` |
| 409 | QIT000008 | Priority reservation already fixed_rate | Já está `fixed_rate` |

### DELETE — remover prioridade

| HTTP | Código | Título (exemplo) | Quando ocorre |
|------|--------|------------------|---------------|
| 400 | QIT000006 | Reservation priority type not fixed_rate | Há prioridade, mas não é `fixed_rate` |
| 400 | QIT000006 | Reservation status not allowed | Status não permitido |
| 404 | SSC000035 | Reservation not Found | Reserva não encontrada |

### GET — configuração

| HTTP | Código | Título (exemplo) | Quando ocorre |
|------|--------|------------------|---------------|
| 404 | QIT000007 | Priority reservation configuration not found | Sem configuração para o requester |

**Exemplos de corpo de erro (JSON)**

```json
{
  "title": "Reservation not Found",
  "description": "...",
  "translation": "...",
  "code": "SSC000035"
}
```

```json
{
  "title": "Priority reservation already fixed_rate",
  "description": "...",
  "translation": "...",
  "code": "QIT000008"
}
```

---

# Assinatura em grupo (INSS)

URL: /documentation/guides/INSS/signatures/batch-group-signature

:::caution Disponibilidade
Este fluxo está em implantação. Por ora, ele cobre operações **INSS** (`social_security`) com o certificador **`qi_sign`**. Alinhe com o time de integração da QI Tech a liberação para o seu requester antes de iniciar a integração em produção.
:::

O fluxo de **assinatura em grupo** agrupa **várias operações** em **uma única pasta de assinatura** do QI Sign. O beneficiário faz **uma única jornada de assinatura** (prova de vida, documento e OTP) e assina **todas as operações do grupo de uma só vez**, com **um único link**.

:::info Fluxo
0. (opcional) Faça upload do [documento de identificação](#documento-de-identificacao-pre-coletado) do beneficiário, para que ele não precise fotografá-lo durante a assinatura
1. Abra o grupo com `POST /document/document_batch_group` e guarde a `document_batch_group_key`.
2. Crie cada operação (`/debt`, `/v2/credit_transfer/proposal`, etc) enviando `document_batch_group_key` na raiz do payload.
3. (Opcional) Consulte o grupo e remova operações antes do envio.
4. Envie o grupo para assinatura com `PUT /document/document_batch_group/{key}/send_to_signature` e obtenha o **link único** do beneficiário.
5. O beneficiário assina todas as operações de uma vez; cada operação evolui individualmente e o grupo é concluído quando todas chegam a um status terminal.
:::

:::info Grupo × lote
Cada operação (dívida, proposta de portabilidade/refin ou reserva de cartão) continua sendo **um lote** (envelope). O **grupo** é a camada acima dos lotes (pasta), responsável por reunir os envelopes e disparar **uma única assinatura**. Se você ainda utiliza o fluxo de [lote externo](/documentation/guides/INSS/signatures/batch-signature), consulte a [tabela de migração](#migracao) ao final desta página.
:::

:::caution Regras do grupo
- **Assinante único:** o grupo suporta **apenas um assinante** (o beneficiário). Não é possível informar múltiplos assinantes na pasta.
- **Mesma titularidade:** o assinante informado na abertura do grupo deve ser **o mesmo** de todas as operações anexadas. Operação com assinante divergente retorna **erro síncrono** (`DOC000121`).
- **Tipos permitidos:** o grupo aceita operações INSS de Crédito Novo, Portabilidade/Refinanciamento e Cartão Consignado, desde que compartilhem o mesmo assinante.
- **Limite de operações:** o grupo aceita **no máximo 7 operações** (lotes). A inclusão de uma operação além do limite retorna **erro síncrono** (`DOC000127`).
- **Contato obrigatório:** informe `signer_email` e/ou `signer_phone` no assinante. Sem um meio de contato, não é possível gerar o link de assinatura.
- **Certificador:** derivado automaticamente da configuração do requester (`qi_sign`); não é enviado na requisição.
:::

:::info Convivência com os fluxos atuais (período de transição)
O fluxo de grupo é **opcional e aditivo**: ele só é acionado quando `document_batch_group_key` é enviado na criação da operação. Os fluxos existentes — assinatura individual por operação com o certificador configurado para o requester (inclusive certificadores externos, como `client_side`) e o [lote externo](/documentation/guides/INSS/signatures/batch-signature) — **continuam funcionando sem alteração** durante o período de transição. Dentro do grupo, a assinatura é sempre coletada via **QI Sign**, mesmo que o requester utilize outro certificador nos fluxos regulares.
:::

---

## 1. Abrir o grupo

ENDPOINT /document/document_batch_group
MÉTODO POST

Request Body

```json
{
    "batch_group_type": "social_security",
    "request_control_key": "5ed20003-0610-46d2-88cc-a5d0de640696",
    "signer": {
        "signer_document_number": "14471835092",
        "signer_name": "Nome devedor",
        "signer_email": "maria.silva@email.com",
        "signer_phone": {
            "country_code": "55",
            "area_code": "11",
            "number": "999538380"
        },
        "signer_role": "issuer",
        "signature_method": "whatsapp"
    },
    "personal_document": {
        "type": "rg",
        "document_identification_front_key": "3b28a1a6-51c0-4f0e-9b64-2c98d6a3f1e0",
        "document_identification_back_key": "9d47c2b1-8f3a-4e5d-a1c2-7b6e5d4f3a2b"
    }
}
```

### Body Params

:::info Certificador
O certificador (`qi_sign`) é **derivado** da configuração do requester e **não** é enviado na requisição. Requesters cuja configuração não use `qi_sign` recebem `DOC000118`.
:::

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `batch_group_type` | string | Tipo do grupo. Atualmente o único valor é `social_security`. | **[Batch Group Type](#batch-group-type)** |
| `request_control_key` | string | Chave de **idempotência** (UUID v4), **obrigatória**. Reenviar o mesmo valor retorna o grupo já existente (evita grupos/pastas duplicados em retentativas). Não reutilize entre grupos distintos. | 36 |
| `signer` | object | Dados do beneficiário que assinará todas as operações do grupo. | **[Signer Object](#signer-object)** |
| `personal_document` | object | (Opcional) Documento de identificação do beneficiário coletado previamente, para dispensar a foto do documento durante a jornada de assinatura. | **[Documento pré-coletado](#documento-de-identificacao-pre-coletado)** |

### Signer Object

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `signer_document_number` | string | CPF/CNPJ do assinante (apenas dígitos). | 11 a 14 |
| `signer_name` | string | Nome do assinante. | 100 |
| `signer_email` | string | E-mail para envio do link de assinatura. (opcional) | 255 |
| `signer_phone.country_code` | string | Código do país (ex.: `"55"`). (opcional) | 5 |
| `signer_phone.area_code` | string | DDD do assinante. (opcional) | 5 |
| `signer_phone.number` | string | Número de telefone do assinante. (opcional) | 15 |
| `signer_role` | string | Papel do assinante (ex.: `issuer`). **Deve ser igual ao papel do assinante nas operações anexadas**, caso contrário a inclusão retorna `DOC000121`. | 100 |
| `signature_method` | string | Canal de envio do link de assinatura. (opcional) | **[Signature Method](#signature-method)** |
| `birth_date` | string | Data de nascimento do assinante (`AAAA-MM-DD`). (opcional) | 10 |

### Documento de identificação pré-coletado {#documento-de-identificacao-pre-coletado}

Se o seu fluxo já coleta o documento de identificação do beneficiário (RG, CNH etc.) antes da assinatura, envie-o na abertura do grupo pelo objeto **`personal_document`**. As imagens são encaminhadas ao QI Sign junto com a criação da pasta e a etapa de captura do documento chega **pré-atendida** na jornada — o beneficiário não precisa fotografar o documento novamente durante a assinatura.

O envio acontece em duas etapas:

1. **Faça o upload dos arquivos previamente** pelo [fluxo de upload de documentos](../../../upload_de_documentos/upload_de_documentos.md) e guarde a `document_key` de cada arquivo (um arquivo por lado do documento, ou um arquivo único no caso de documento digital).
2. **Referencie as chaves** no objeto `personal_document` da abertura do grupo.

```json title="Trecho ilustrativo (raiz do payload de abertura do grupo)"
{
    "personal_document": {
        "type": "rg",
        "document_identification_front_key": "3b28a1a6-51c0-4f0e-9b64-2c98d6a3f1e0",
        "document_identification_back_key": "9d47c2b1-8f3a-4e5d-a1c2-7b6e5d4f3a2b"
    }
}
```

#### Personal Document Object

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `type` | string | Tipo do documento de identificação. | **[Personal Document Type](#personal-document-type)** |
| `document_identification_front_key` | string | `document_key` do arquivo com a **frente** do documento. Obrigatório no modo frente e verso (junto com `..._back_key`). | 36 |
| `document_identification_back_key` | string | `document_key` do arquivo com o **verso** do documento. Obrigatório no modo frente e verso (junto com `..._front_key`). | 36 |
| `document_identification_full_key` | string | `document_key` do arquivo **único** com o documento completo (documento digital). Não pode ser combinado com as chaves de frente/verso. | 36 |

:::caution Regras do documento pré-coletado
- Envie **frente + verso** (`document_identification_front_key` + `document_identification_back_key`) **ou** o **arquivo único** (`document_identification_full_key`) — nunca os dois modos juntos.
- Cada `type` suporta modos específicos — veja **[Personal Document Type](#personal-document-type)**. Combinação inválida retorna `DOC000128`.
- Os documentos referenciados devem pertencer ao seu requester e já ter o **arquivo enviado** (upload concluído). Chave inexistente ou de outro requester retorna `DOC000004`; documento sem arquivo retorna `DOC000049`.
- O envio é feito **apenas na abertura do grupo** — não é possível adicionar ou trocar o documento depois que o grupo foi criado. Se algum arquivo for rejeitado, a criação do grupo falha por inteiro (nenhum grupo é criado).
:::

O objeto `personal_document` enviado é ecoado nas [consultas do grupo](#3-consultar-o-grupo).

---

### Response

STATUS 201

Response Body

```json
{
    "document_batch_group_key": "17f35e19-a039-468f-aaa7-84aa8edec3dc",
    "status": "pending_batches"
}
```

| Campo | Tipo | Descrição |
|---|---|---|
| `document_batch_group_key` | string | Identificador do grupo. Guarde para os próximos passos. |
| `status` | string | Status inicial do grupo: `pending_batches`. Veja **[Status do grupo](#status-do-grupo)**. |

---

## 2. Incluir operações no grupo

Ao criar cada operação, envie **`document_batch_group_key` na raiz do JSON** (mesmo nível dos demais campos principais do produto). A operação é criada normalmente, mas a sua assinatura fica **vinculada à pasta do grupo** — não é gerado link de assinatura individual.

Crédito Novo / Refin POST /debt
Portabilidade / Refin POST /v2/credit_transfer/proposal
Cartão POST /payroll_card_reservation/social_security

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `document_batch_group_key` | string | A `document_batch_group_key` retornada na abertura do grupo; enviada na raiz do payload de criação da operação. Obrigatório no fluxo com grupo. | 36 |

```json title="Trecho ilustrativo (raiz do payload)"
{
    "document_batch_group_key": "17f35e19-a039-468f-aaa7-84aa8edec3dc"
}
```

O restante do body segue o contrato de cada endpoint. Consulte os [roteiros de crédito consignado INSS](/documentation/guides/INSS/intro) conforme o produto.

:::info Resposta da operação no fluxo com grupo
Como o link de assinatura passa a ser **único e no nível do grupo**, a resposta de criação da operação **não retorna** dados de assinatura individuais (ex.: `signature_information` na proposta de portabilidade/refin). O link é obtido apenas no [envio do grupo para assinatura](#5-enviar-para-assinatura).
:::

---

## 3. Consultar o grupo

ENDPOINT /document/document_batch_group/{document_batch_group_key}
MÉTODO GET

Recomendado antes de enviar para assinatura, para conferir as operações agrupadas e seus status.

### Path Params

| Campo | Tipo | Descrição |
|---|---|---|
| `document_batch_group_key` | string | Chave do grupo. |

:::info Consulta por idempotência
Também é possível consultar pela `request_control_key`: `GET /document/document_batch_group/request_control_key/{request_control_key}`.
:::

### Exemplo de chamada

```
GET /document/document_batch_group/17f35e19-a039-468f-aaa7-84aa8edec3dc
```

---

### Response

STATUS 200

Response Body

```json
{
    "document_batch_group_key": "17f35e19-a039-468f-aaa7-84aa8edec3dc",
    "request_control_key": "5ed20003-0610-46d2-88cc-a5d0de640696",
    "external_key": "c109d589-ae18-4f4f-ad31-2879bf714c71",
    "group_name": "Assinatura de operações INSS",
    "batch_group_type": "social_security",
    "status": "pending_batches",
    "signature_url": null,
    "personal_document": {
        "type": "rg",
        "document_identification_front_key": "3b28a1a6-51c0-4f0e-9b64-2c98d6a3f1e0",
        "document_identification_back_key": "9d47c2b1-8f3a-4e5d-a1c2-7b6e5d4f3a2b"
    },
    "batches": [
        {
            "document_batch_key": "5cca1dad-28fe-4f19-8bbb-0edd6f042384",
            "origin_key": "324caa35-ba10-4590-ae2b-5efef71709c3",
            "origin_type": "credit_operation",
            "status": "pending_signature"
        },
        {
            "document_batch_key": "085e3098-0bdb-4472-a4ae-dafc1bafda53",
            "origin_key": "2f7e320c-2a35-4e78-bfd7-a298b28a7497",
            "origin_type": "credit_transfer_proposal",
            "status": "pending_signature"
        }
    ]
}
```

| Campo | Tipo | Descrição |
|---|---|---|
| `document_batch_group_key` | string | Identificador do grupo. |
| `request_control_key` | string | Chave de idempotência informada na abertura do grupo. |
| `external_key` | string | Identificador da pasta no QI Sign. |
| `group_name` | string | Nome gerado para o grupo (ex.: `Assinatura de operações INSS`). |
| `batch_group_type` | string | Tipo do grupo. Veja **[Batch Group Type](#batch-group-type)**. |
| `status` | string | Status do grupo. Veja **[Status do grupo](#status-do-grupo)**. |
| `signature_url` | string | Link único de assinatura do beneficiário. Disponível após o envio para assinatura. Com o [preenchimento automático do login](#5-enviar-para-assinatura) habilitado, retorna o link já autenticado. |
| `personal_document` | object | [Documento de identificação pré-coletado](#documento-de-identificacao-pre-coletado) informado na abertura do grupo (`null` se não enviado). |
| `batches` | array | Operações anexadas ao grupo. **[Batch Object](#batch-object)** |

### Batch Object

| Campo | Tipo | Descrição |
|---|---|---|
| `document_batch_key` | string | Chave do lote (envelope) da operação. |
| `origin_key` | string | Chave da operação de origem. Veja **[Origin Type](#origin-type)**. |
| `origin_type` | string | Tipo da operação de origem. Veja **[Origin Type](#origin-type)**. |
| `status` | string | Status da operação dentro do grupo. Veja **[Status da operação](#status-da-operação)**. |

---

## 4. Remover operação do grupo

Desvincula e cancela uma operação específica antes do envio para assinatura (para reagrupar, se necessário). Só é permitido enquanto o grupo está em `pending_batches`.

ENDPOINT /document/document_batch_group/{document_batch_group_key}/remove_batch
MÉTODO PUT

### Path Params

| Campo | Tipo | Descrição |
|---|---|---|
| `document_batch_group_key` | string | Chave do grupo. |

Request Body

```json
{
    "origin_key": "324caa35-ba10-4590-ae2b-5efef71709c3"
}
```

### Body Params

| Campo | Tipo | Descrição |
|---|---|---|
| `origin_key` | string | Chave da operação a remover (a mesma `origin_key` retornada na consulta do grupo). |

---

### Response

STATUS 201

Retorna o grupo atualizado, já sem a operação removida em `batches` (mesmo formato da [consulta do grupo](#3-consultar-o-grupo)).

Response Body

```json
{
    "document_batch_group_key": "17f35e19-a039-468f-aaa7-84aa8edec3dc",
    "status": "pending_batches",
    "signature_url": null,
    "batches": [
        {
            "document_batch_key": "085e3098-0bdb-4472-a4ae-dafc1bafda53",
            "origin_key": "2f7e320c-2a35-4e78-bfd7-a298b28a7497",
            "origin_type": "credit_transfer_proposal",
            "status": "pending_signature"
        }
    ]
}
```

---

## 5. Enviar para assinatura

Fecha o grupo e dispara a pasta para assinatura no QI Sign. Retorna o **link único** (`signature_url`) que o beneficiário usa para assinar todas as operações de uma só vez.

ENDPOINT /document/document_batch_group/{document_batch_group_key}/send_to_signature
MÉTODO PUT

### Path Params

| Campo | Tipo | Descrição |
|---|---|---|
| `document_batch_group_key` | string | Chave do grupo. |

**Body:** objeto JSON vazio `{}`.

:::caution Pré-condições do envio
- O grupo precisa estar em `pending_batches`.
- Deve haver **ao menos uma** operação anexada (`DOC000120`).
- Todas as operações devem ter o **mesmo assinante** do grupo (`DOC000121`).
:::

---

### Response

STATUS 201

O grupo passa para `pending_signature` e a `signature_url` é preenchida.

Response Body

```json
{
    "document_batch_group_key": "17f35e19-a039-468f-aaa7-84aa8edec3dc",
    "status": "pending_signature",
    "signature_url": "https://sign.sandbox.qitech.app/f/17f35e19-a039-468f-aaa7-84aa8edec3dc",
    "batches": [
        {
            "document_batch_key": "085e3098-0bdb-4472-a4ae-dafc1bafda53",
            "origin_key": "2f7e320c-2a35-4e78-bfd7-a298b28a7497",
            "origin_type": "credit_transfer_proposal",
            "status": "pending_signature"
        }
    ]
}
```

| Campo | Tipo | Descrição |
|---|---|---|
| `status` | string | Status do grupo após o envio: `pending_signature`. |
| `signature_url` | string | Link único de assinatura do beneficiário. |
| `batches` | array | Operações do grupo. **[Batch Object](#batch-object)** |

:::info Link com preenchimento automático do login
Sob demanda, é possível habilitar o **preenchimento automático do login**. Com a opção habilitada, a `signature_url` retornada no envio para assinatura e nas [consultas do grupo](#3-consultar-o-grupo) passa a ser um **link autenticado**: a tela de login da jornada de assinatura já vem preenchida com os dados do beneficiário.
:::

---

## Acompanhamento

Após o envio, o beneficiário assina todas as operações com **um único link**. Na jornada de assinatura, o beneficiário pode **aceitar ou recusar cada operação individualmente** — desfechos parciais são normais (ex.: duas operações assinadas e uma recusada no mesmo grupo). Cada operação evolui de forma independente e o grupo é concluído (`completed`) quando **nenhuma** operação permanece em `pending_signature`, independentemente da combinação de desfechos. Acompanhe o desfecho de cada operação pelos webhooks do respectivo produto (abaixo) ou pela [consulta do grupo](#3-consultar-o-grupo).

:::info Submissão automática (Portabilidade/Refin)
No fluxo com grupo, após a assinatura da proposta de portabilidade/refin a submissão à registradora é feita **automaticamente** — a proposta avança para `pending_response` sem necessidade do `PATCH` manual de submissão.
:::

### Webhook de operação assinada

Cada operação assinada segue o **mesmo fluxo de webhooks do produto** (dívida emitida, proposta submetida etc.) — nenhum campo muda em relação ao fluxo sem grupo. Consulte os webhooks de cada produto nos [roteiros INSS](/documentation/guides/INSS/intro).

### Webhook de assinatura recusada

Quando o beneficiário **recusa** uma operação do grupo, a operação é **cancelada** no respectivo produto e o parceiro recebe o webhook de mudança de status com o motivo `signature_rejected`:

**Crédito Novo / Refin (dívida):**

```json
{
    "key": "324caa35-ba10-4590-ae2b-5efef71709c3",
    "data": {
        "cancel_reason": "Operação cancelada porque o assinante recusou a assinatura.",
        "cancel_reason_enumerator": "signature_rejected"
    },
    "status": "canceled",
    "webhook_type": "debt",
    "event_datetime": "2026-07-06 14:30:00"
}
```

**Portabilidade / Refin (proposta):**

```json
{
    "webhook_type": "credit_transfer.proposal",
    "proposal_key": "2f7e320c-2a35-4e78-bfd7-a298b28a7497",
    "event_datetime": "2026-07-06T14:30:00",
    "proposal_status": "canceled",
    "cancel_reason": "signature_rejected"
}
```

| Produto | `webhook_type` | Campo de status | Motivo da recusa |
|---|---|---|---|
| Crédito Novo / Refin | `debt` | `status: "canceled"` | `data.cancel_reason_enumerator: "signature_rejected"` |
| Portabilidade / Refin | `credit_transfer.proposal` | `proposal_status: "canceled"` | `cancel_reason: "signature_rejected"` |

Na [consulta do grupo](#3-consultar-o-grupo), a operação recusada aparece com status `sign_rejected`.

---

## Erros

| HTTP | Código | Quando ocorre |
|---|---|---|
| 400 | `DOC000118` | O certificador configurado para o requester não é suportado (apenas `qi_sign`). |
| 404 | `DOC000117` | Grupo não encontrado para a chave informada. |
| 409 | `DOC000119` | Grupo não está em `pending_batches` e não pode ser modificado. |
| 400 | `DOC000120` | Envio para assinatura sem nenhuma operação anexada. |
| 400 | `DOC000121` | Assinante de uma operação difere do assinante do grupo. |
| 400 | `DOC000122` | `origin_key` não informado na remoção. |
| 404 | `DOC000123` | `origin_key` não encontrado entre as operações do grupo. |
| 400 | `DOC000127` | O grupo já possui o número máximo de operações (5). |
| 400 | `DOC000128` | O `type` do documento pré-coletado não suporta o modo enviado (frente e verso × arquivo único). Veja **[Personal Document Type](#personal-document-type)**. |
| 400 | `DOC000129` | A jornada de assinatura configurada para o requester não coleta documento de identificação — o envio de documento pré-coletado não se aplica. |
| 400 | `DOC000130` | O `type` do documento pré-coletado não está entre os tipos aceitos pela configuração do requester. |
| 404 | `DOC000004` | `document_key` do documento pré-coletado não encontrada (inclui documento pertencente a outro requester). |
| 400 | `DOC000049` | Documento pré-coletado sem arquivo — o upload não foi concluído antes da abertura do grupo. |
| 400 | `DOC000126` | Configuração do requester incompleta. |
| 404 | `DOC000091` | Configuração de certificador não encontrada para o requester. |

---

## Enumeradores

### Batch Group Type

| Enumerador | Descrição |
|---|---|
| `social_security` | Operações de crédito consignado INSS. |

### Signature Method

| Enumerador | Descrição |
|---|---|
| `email` | Link de assinatura enviado por e-mail. |
| `sms` | Link de assinatura enviado por SMS. |
| `whatsapp` | Link de assinatura enviado por WhatsApp. |

### Personal Document Type

Tipos aceitos no [documento de identificação pré-coletado](#documento-de-identificacao-pre-coletado) e os modos de envio suportados por cada um:

| Enumerador | Documento | Frente e verso | Arquivo único |
|---|---|---|---|
| `rg` | Registro Geral (RG) | ✔ | — |
| `cnh` | Carteira Nacional de Habilitação | ✔ | ✔ |
| `cin` | Carteira de Identidade Nacional | — | ✔ |

- **Frente e verso:** envie `document_identification_front_key` + `document_identification_back_key`.
- **Arquivo único:** envie apenas `document_identification_full_key` (documento digital, ex.: CNH digital).

### Origin Type

| Enumerador | Operação | `origin_key` |
|---|---|---|
| `credit_operation` | Crédito Novo / Refin (`POST /debt`) | `credit_operation_key` |
| `credit_transfer_proposal` | Portabilidade / Refin (`POST /v2/credit_transfer/proposal`) | `proposal_key` |
| `payroll_card_reservation` | Cartão Consignado (`POST /payroll_card_reservation/social_security`) | chave da reserva |

### Status do grupo

| Status | Descrição |
|---|---|
| `pending_batches` | Grupo aberto, recebendo operações. Permite incluir/remover operações. |
| `pending_signature` | Enviado para assinatura; aguardando o beneficiário assinar. |
| `completed` | Todas as operações do grupo chegaram a um status terminal. |
| `canceled` | Grupo cancelado. |

### Status da operação

| Status | Descrição |
|---|---|
| `pending_signature` | Operação anexada ao grupo, aguardando assinatura. |
| `signed` | Operação assinada com sucesso. |
| `sign_rejected` | Beneficiário recusou a assinatura da pasta. |
| `canceled` | Operação/pasta cancelada. |

---

## Migração do lote externo para o grupo {#migracao}

O fluxo de [lote externo](/documentation/guides/INSS/signatures/batch-signature) (`document_batch_key`) é substituído pelo fluxo de grupo (`document_batch_group_key`). Principais diferenças:

- Você **não** cria mais o lote e adiciona documentos manualmente: cada operação (`/debt`, `/v2/credit_transfer/proposal`, cartão) já é um lote, e o **grupo** apenas os reúne.
- O link de assinatura passa a ser **único e no nível do grupo**, retornado no envio para assinatura — não há link por operação.

| Antigo (lote externo) | Novo (grupo) |
|---|---|
| `POST /document/document_batch` (`type: social_security_external_batch`) | `POST /document/document_batch_group` |
| `document_batch_key` na raiz da operação | `document_batch_group_key` na raiz da operação |
| `GET /document/document_batch/{key}` | `GET /document/document_batch_group/{key}` |
| `DELETE /document/document_batch/{key}/documents` (limpar tudo) | `PUT /document/document_batch_group/{key}/remove_batch` (remover uma operação) |
| `PUT /document/document_batch/{key}/send_to_signature` | `PUT /document/document_batch_group/{key}/send_to_signature` |

---

# Assinatura em lote (INSS)

URL: /documentation/guides/INSS/signatures/batch-signature

Assinatura em lote (INSS)

Fluxo para agrupar **várias operações** em **um único envelope de assinatura** do QI Sign: você abre o lote, cria as operações referenciando o lote, confere (opcionalmente limpa) e dispara o envio para assinatura.

:::caution Fluxo legado
Este é o fluxo de **lote externo** (`document_batch_key`). Ele permanece disponível, mas o caminho recomendado para novas integrações é a **[Assinatura em grupo](/documentation/guides/INSS/signatures/batch-group-signature)** (`document_batch_group_key`), que reúne as operações em uma pasta e dispara **uma única assinatura** para o beneficiário. Consulte a [tabela de migração](/documentation/guides/INSS/signatures/batch-group-signature#migracao).
:::

:::caution Regras do lote
**Mesma titularidade:** todas as operações do lote devem ser do **CPF** ou do **mesmo representante legal**. Incluir CPF “A” e CPF “B” no mesmo lote gera **erro síncrono** no `POST` da operação.

**Tipos permitidos:** por ora o fluxo aceita operações INSS de Crédito Novo e Cartão Consignado no mesmo lote.
:::

---

## Abrir o lote

Request

ENDPOINT /document/document_batch
MÉTODO POST

Body

type
string
obrigatório
Fixo: social_security_external_batch .

certifier_type
string
obrigatório
Fixo: qi_sign .

batch_name
string
obrigatório
Nome do lote para identificação; **máximo 100 caracteres**. Use um identificador único por lote na sua operação.

request_control_key
string (UUID v4)
obrigatório
Chave de **idempotência**; não reutilize entre lotes distintos.

personal_document
object
opcional
Documento de identificação do tomador já coletado pelo parceiro, para dispensar a foto do documento durante a assinatura. Veja **[Documento de identificação pré-coletado](#documento-de-identificacao-pre-coletado)**.

**Python**

```python title="ENDPOINT"
POST /document/document_batch
```

**curl**

```bash title="ENDPOINT"
curl -X POST \
  'https://api-auth.sandbox.qitech.app/document/document_batch' \
  -H 'AUTHORIZATION: eyJhbGciOiJFUzUxMiJ9.eyJwYXlsb2FkX21kNSI6...' \
  -H 'API-CLIENT-KEY: YOUR_API_CLIENT_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "social_security_external_batch",
    "certifier_type": "qi_sign",
    "batch_name": "Lote INSS - pedido-2025-03-001",
    "request_control_key": "5ed20003-0610-46d2-88cc-a5d0de640696"
  }'
```

```json title="REQUEST BODY (exemplo)"
{
  "type": "social_security_external_batch",
  "certifier_type": "qi_sign",
  "batch_name": "Lote INSS - pedido-2025-03-001",
  "request_control_key": "5ed20003-0610-46d2-88cc-a5d0de640696"
}
```

Response

STATUS 201

Atributos

document_batch_key
string
Identificador do lote. Guarde para os próximos passos.

```json title="RESPONSE BODY"
{
  "document_batch_key": "17f35e19-a039-468f-aaa7-84aa8edec3dc"
}
```

---

## Documento de identificação pré-coletado {#documento-de-identificacao-pre-coletado}

Se o seu fluxo já coleta o documento de identificação do tomador (RG, CNH etc.) antes da assinatura, envie-o na **abertura do lote** pelo objeto `personal_document`. As imagens são encaminhadas ao QI Sign junto com a criação do envelope e a etapa de captura do documento chega **pré-atendida** na jornada — o tomador não precisa fotografar o documento novamente.

Os arquivos ficam vinculados ao lote, mas **não são assinados**: eles não entram no envelope como documentos assináveis e não participam do `send_to_signature`.

O envio acontece em duas etapas.

### 1. Suba os arquivos

Faça o upload de cada arquivo pelo [fluxo de upload de documentos](/documentation/upload_de_documentos/upload_de_documentos) e guarde a `document_key` retornada — **um arquivo por lado** do documento, ou **um arquivo único** no caso de documento digital.

Não é preciso classificar o arquivo no upload: é o **campo** em que você informa a chave que declara qual lado do documento ela representa.

| Campo | Arquivo esperado |
|---|---|
| `document_identification_front_key` | Frente do documento de identificação |
| `document_identification_back_key` | Verso do documento de identificação |
| `document_identification_full_key` | Documento digital completo, em arquivo único |

### 2. Referencie as chaves na abertura do lote

Personal Document Object

type
string
obrigatório
Tipo do documento de identificação. Veja **[Tipos aceitos](#tipos-de-documento-aceitos)**.

document_identification_front_key
string
condicional
`document_key` da **frente**. Obrigatório no modo frente e verso, junto com `..._back_key`.

document_identification_back_key
string
condicional
`document_key` do **verso**. Obrigatório no modo frente e verso, junto com `..._front_key`.

document_identification_full_key
string
condicional
`document_key` do **arquivo único** (documento digital). Não pode ser combinado com as chaves de frente e verso.

```json title="REQUEST BODY (abertura do lote com documento pré-coletado)"
{
  "type": "social_security_external_batch",
  "certifier_type": "qi_sign",
  "batch_name": "Lote INSS - pedido-2025-03-001",
  "request_control_key": "5ed20003-0610-46d2-88cc-a5d0de640696",
  "personal_document": {
    "type": "rg",
    "document_identification_front_key": "3b28a1a6-51c0-4f0e-9b64-2c98d6a3f1e0",
    "document_identification_back_key": "9d47c2b1-8f3a-4e5d-a1c2-7b6e5d4f3a2b"
  }
}
```

### Tipos de documento aceitos {#tipos-de-documento-aceitos}

| `type` | Documento | Frente e verso | Arquivo único |
|---|---|---|---|
| `rg` | Registro Geral (RG) | ✔ | — |
| `cnh` | Carteira Nacional de Habilitação | ✔ | ✔ |
| `cin` | Carteira de Identidade Nacional | — | ✔ |

- **Frente e verso:** envie `document_identification_front_key` + `document_identification_back_key`.
- **Arquivo único:** envie apenas `document_identification_full_key` (documento digital, ex.: CNH digital).

O conjunto de tipos efetivamente aceito também depende da jornada de assinatura configurada para o seu requester. Um `type` fora dessa configuração retorna `DOC000130`.

:::caution Regras do documento pré-coletado
- Envie **frente + verso** **ou** o **arquivo único** — nunca os dois modos juntos.
- Cada `type` suporta modos específicos; combinação inválida retorna `DOC000128`.
- Os arquivos devem pertencer ao seu requester e já ter o **upload concluído**. Chave inexistente ou de outro requester retorna `DOC000004`; arquivo ausente retorna `DOC000049`.
- Cada arquivo só pode ser usado em **um lote**. Reaproveitar uma `document_key` já vinculada retorna `DOC000137`.
- O envio é feito **apenas na abertura do lote** — não é possível adicionar ou trocar o documento depois. Se algum arquivo for rejeitado, a criação do lote falha por inteiro (nenhum lote é criado).
- A requisição precisa identificar o **titular** dos arquivos: envie o header `SELECTED-AGENT`. Sem ele, a abertura retorna `QIT000004`.
:::

---

## Incluir operações no lote

Ao criar cada operação, envie **`document_batch_key` na raiz do JSON** (mesmo nível dos demais campos principais do produto).

Cartão POST /payroll_card_reservation/social_security
Empréstimo POST /debt

document_batch_key
string
obrigatório no fluxo com lote
O mesmo document_batch_key retornado na abertura do lote; envie na raiz do payload de criação da operação.

```json title="Trecho ilustrativo (raiz do payload)"
{
  "document_batch_key": "17f35e19-a039-468f-aaa7-84aa8edec3dc"
}
```

O restante do body segue o contrato de cada endpoint. Consulte os [roteiros de crédito consignado INSS](/documentation/guides/INSS/new-credit-and-refinancing/end-to-end) conforme o produto.

---

## Consultar documentos do lote

Request

ENDPOINT /document/document_batch/ DOCUMENT_BATCH_KEY
MÉTODO GET

Path params

document_batch_key
string
obrigatório
Chave do lote.

Recomendado antes de fechar o lote para conferir tipos e chaves de documento agrupados.

**Python**

```python title="ENDPOINT"
GET /document/document_batch/YOUR_DOCUMENT_BATCH_KEY
```

**curl**

```bash title="ENDPOINT"
curl -X GET \
  'https://api-auth.sandbox.qitech.app/document/document_batch/YOUR_DOCUMENT_BATCH_KEY' \
  -H 'AUTHORIZATION: eyJhbGciOiJFUzUxMiJ9.eyJwYXlsb2FkX21kNSI6...' \
  -H 'API-CLIENT-KEY: YOUR_API_CLIENT_KEY' \
  -H 'Content-Type: application/json'
```

Response

STATUS 200

Atributos

document_batch_key
string
Chave do lote.

documents
array
Lista de documentos; cada item costuma trazer document_key e document_type (ex.: ccb_pre_price_days , payroll_card_term ).

```json title="RESPONSE BODY (exemplo)"
{
  "document_batch_key": "1eee4ec2-05f5-45ef-aa64-38bb3d9de02f",
  "documents": [
    {
      "document_key": "5cca1dad-28fe-4f19-8bbb-0edd6f042384",
      "document_type": "ccb_pre_price_days"
    },
    {
      "document_key": "c109d589-ae18-4f4f-ad31-2879bf714c71",
      "document_type": "withdrawal_operation_term"
    },
    {
      "document_key": "085e3098-0bdb-4472-a4ae-dafc1bafda53",
      "document_type": "payroll_card_term"
    },
    {
      "document_key": "eafdb3bd-5c21-415f-bdc2-8e366d54094c",
      "document_type": "payroll_card_consent_term"
    }
  ]
}
```

---

## Limpar documentos do lote

Remove todos os documentos vinculados ao lote (para reagrupar do zero, se necessário).

Request

ENDPOINT /document/document_batch/ DOCUMENT_BATCH_KEY /documents
MÉTODO DELETE

Path params

document_batch_key
string
obrigatório
Chave do lote.

**Python**

```python title="ENDPOINT"
DELETE /document/document_batch/YOUR_DOCUMENT_BATCH_KEY/documents
```

**curl**

```bash title="ENDPOINT"
curl -X DELETE \
  'https://api-auth.sandbox.qitech.app/document/document_batch/YOUR_DOCUMENT_BATCH_KEY/documents' \
  -H 'AUTHORIZATION: eyJhbGciOiJFUzUxMiJ9.eyJwYXlsb2FkX21kNSI6...' \
  -H 'API-CLIENT-KEY: YOUR_API_CLIENT_KEY' \
  -H 'Content-Type: application/json'
```

Response

STATUS 200

Corpo de resposta conforme padrão da API para sucesso neste recurso (pode ser vazio ou objeto mínimo).

```json title="RESPONSE BODY (exemplo)"
{}
```

---

## Enviar para assinatura

Fecha o lote e dispara os documentos para assinatura no QI Sign.

Request

ENDPOINT /document/document_batch/ DOCUMENT_BATCH_KEY /send_to_signature
MÉTODO PUT

Path params

document_batch_key
string
obrigatório
Chave do lote.

**Body:** objeto JSON vazio `{}`.

**Python**

```python title="ENDPOINT"
PUT /document/document_batch/YOUR_DOCUMENT_BATCH_KEY/send_to_signature
```

**curl**

```bash title="ENDPOINT"
curl -X PUT \
  'https://api-auth.sandbox.qitech.app/document/document_batch/YOUR_DOCUMENT_BATCH_KEY/send_to_signature' \
  -H 'AUTHORIZATION: eyJhbGciOiJFUzUxMiJ9.eyJwYXlsb2FkX21kNSI6...' \
  -H 'API-CLIENT-KEY: YOUR_API_CLIENT_KEY' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

```json title="REQUEST BODY"
{}
```

Response

STATUS 200

```json title="RESPONSE BODY (exemplo)"
{}
```

---

## Erros

| HTTP | Código | Título (exemplo) | Endpoint | Quando ocorre |
|------|--------|------------------|----------|---------------|
| 404 | DOC000007 | (lote não encontrado) | `GET /document/document_batch/DOCUMENT_BATCH_KEY` | `document_batch_key` inexistente |
| 409 | DOC000103 | Bad Request | POST /document/document_batch | `request_control_key` duplicado (idempotência violada de forma inválida) |
| 400 | DOC000128 | Bad Request | POST /document/document_batch | O `type` não suporta o modo enviado (frente e verso × arquivo único) |
| 400 | DOC000129 | Bad Request | POST /document/document_batch | A jornada configurada para o requester não coleta documento de identificação |
| 400 | DOC000130 | Bad Request | POST /document/document_batch | O `type` não está entre os tipos aceitos pela configuração do requester |
| 400 | DOC000137 | Bad Request | POST /document/document_batch | `document_key` do documento pré-coletado já vinculada a outro lote |
| 404 | DOC000004 | Bad Request | POST /document/document_batch | `document_key` do documento pré-coletado não encontrada (inclui arquivo de outro requester) |
| 400 | DOC000049 | Bad Request | POST /document/document_batch | Documento pré-coletado sem arquivo — upload não concluído antes da abertura |
| 403 | QIT000004 | Bad Request | POST /document/document_batch | `personal_document` enviado sem o header `SELECTED-AGENT` |

**Exemplo de erro (idempotência)**

```json
{
  "code": "DOC000103",
  "title": "Bad Request",
  "description": "request_control_key already exists",
  "translation": "Chave de controle da request já existe.",
  "http_status": 409
}
```

:::info Conflito de titularidade ou tipo
Validações de **mesmo CPF/representante** e de **tipo de operação** no lote costumam retornar erro no POST da operação ( /debt ou /payroll_card_reservation/social_security ), não no endpoint do lote. O corpo de erro segue o catálogo do recurso chamado.
:::

:::info Migração de paths
Endpoints antigos foram substituídos pelos paths abaixo:

| Antigo | Novo |
|--------|------|
| `POST /document_batch/external` | `POST /document/document_batch` |
| `GET /document_batch/external/DOCUMENT_BATCH_KEY` | `GET /document/document_batch/DOCUMENT_BATCH_KEY` |
| `PUT /document_batch/DOCUMENT_BATCH_KEY/send_to_signature` | `PUT /document/document_batch/DOCUMENT_BATCH_KEY/send_to_signature` |
:::

---

# Consignado Público - Consulta de Margem

URL: /documentation/guides/publico/consulta-de-margem

A consulta de margem pergunta ao ente consignante **quais vínculos um CPF tem** e **quanta margem há em cada um**. É o primeiro passo de qualquer operação: uma averbação só é aceita sobre um vínculo que uma consulta já observou.

:::caution API em desenvolvimento
Esta API está em fase de desenvolvimento, sendo assim, esta página está sujeita a alterações.
:::

A consulta é **assíncrona**. A criação devolve `202` com a chave da consulta, o resultado chega por [webhook](/documentation/guides/publico/webhooks#balance_inquiry_status_change) e o documento fica disponível na consulta por chave.

## Criar uma consulta

**POST**
/public_payroll/{entity_level}/{consignment_entity}/balance_inquiry

`entity_level` e `consignment_entity` identificam o ente. Ver [Entes Consignantes](/documentation/guides/publico/entes#entes-disponiveis).

### Request

**Request Body**

```json
{
  "employee_document_number": "12345678901",
  ...
}
```

**Request Body Details**

| Campo | Tipo | Descrição | Obrigatório |
|---|---|---|---|
| employee_document_number | string | CPF do servidor, apenas dígitos | Sim |

O restante do corpo depende do [perfil de consignação](/documentation/guides/publico/entes#perfis-de-consignacao) do ente, porque cada plataforma possui um escopo e esquema de autorização próprio para a consulta:

**Perfil 1**

**Request Body**

```json
{
  "employee_document_number": "12345678901",
  "authorization": {
    "granted_at": "2026-08-26",
    "channel": "app"
  }
}
```

**Request Body Details**

| Campo | Tipo | Descrição | Obrigatório |
|---|---|---|---|
| authorization | object | Evidência da anuência do servidor para a consulta | Não |
| authorization.granted_at | string | Data em que o servidor autorizou a consulta, `YYYY-MM-DD` | Sim, se `authorization` |
| authorization.channel | string | Canal em que a autorização foi colhida. Enum: [Canais de autorização](/documentation/guides/publico/entes#sp-canais-de-autorizacao) | Sim, se `authorization` |

A consulta de margem no perfil 1 ocorre a nível de ente, retornando todas as matrículas deste servidor em todos os órgãos do ente.

Essa consulta depende da autorização do servidor no ente. Quando o parceiro já colheu essa autorização, `authorization` permite registrá-la antes da consulta; quando não é enviado, a consulta é feita direto e o próprio ente informa se está autorizada.

Se o ente aceita o registro da anuência por esse caminho, e quais valores de `channel` reconhece, é informado na secção de [entes](/documentation/guides/publico/entes#particularidades).

### Response

STATUS
**202** (Accepted)

**Response Body**

```json
{
  "balance_inquiry_key": "b1b9f0a6-9a3e-4f9b-9d6f-3a5f8c1d2e7b",
  "status": "pending",
  "created_at": "2026-08-26T10:02:11-03:00"
}
```

**Response Body Details**

| Campo | Tipo | Descrição |
|---|---|---|
| balance_inquiry_key | string | Chave da consulta. É por ela que o resultado é recuperado |
| status | string | Situação da consulta. Enum: [Status da consulta](/documentation/guides/publico/enumeradores#balance_inquiry_status) |
| created_at | string | Momento da criação da consulta |

## Consultar o resultado

**GET**
/public_payroll/{entity_level}/{consignment_entity}/balance_inquiry/{balance_inquiry_key}

### Response

STATUS
**200** (OK)

**Response Body**

```json
{
  "balance_inquiry_key": "b1b9f0a6-9a3e-4f9b-9d6f-3a5f8c1d2e7b",
  "status": "completed",
  "reason": null,
  "observed_at": "2026-08-26T10:02:40-03:00",
  "valid_until": "2026-08-31",
  "consignment_entity": {
    "code": "46379400",
    "enumerator": "sp",
    "name": "Governo do Estado de São Paulo"
  },
  "employee": {
    "document_number": "12345678901",
    "name": "Nome do Servidor"
  },
  "employment_relationships": [
    ...
  ]
}
```

**Response Body Details**

| Campo | Tipo | Descrição |
|---|---|---|
| balance_inquiry_key | string | Chave da consulta |
| status | string | Situação da consulta. Enum: [Status da consulta](/documentation/guides/publico/enumeradores#balance_inquiry_status) |
| reason | object | Motivo, quando a consulta falha. `null` nos demais casos. Ver [Motivos](/documentation/guides/publico/enumeradores#reason) |
| observed_at | string | Momento da resposta do ente. É a idade real do dado |
| valid_until | string | Último dia em que uma averbação pode se apoiar nesta consulta |
| consignment_entity | object | Ente consultado, no formato `{code, enumerator, name}` |
| employee | object | Dados do servidor observados pelo ente |
| employment_relationships | array | Os vínculos encontrados. Vazio quando a consulta falha |

O conteúdo de `employment_relationships` é o que muda com o [perfil](/documentation/guides/publico/entes#perfis-de-consignacao), porque é a plataforma do ente que define como a margem é estruturada:

**Perfil 1**

Um item por **matrícula**, com a margem já consolidada.

**Response Body**

```json
{
  "employee": {
    "document_number": "12345678901",
    "name": "Nome do Servidor",
    "has_inquiry_authorization": true
  },
  "employment_relationships": [
    {
      "agency": {
        "code": "20065",
        "enumerator": "spprev",
        "name": "SPPREV"
      },
      "registration_number": "1234567890123",
      "next_payroll_date": "2026-09-05",
      "has_inflight_operation": false,
      "margins": [
        {
          "product": {
            "code": 2,
            "enumerator": "credit_card",
            "name": "Cartão de Crédito"
          },
          "available_value": 1400.00,
          "situation": {
            "code": 1,
            "enumerator": "available",
            "translation": "Margem disponível"
          },
          "rule": "largest_appointment"
        }
      ]
    }
  ]
}
```

**Response Body Details**

| Campo | Tipo | Descrição |
|---|---|---|
| employee.has_inquiry_authorization | boolean | Se o servidor autorizou a consulta de margem no ente |
| employment_relationships[].agency | object | Órgão da matrícula, no formato `{code, enumerator, name}`. Enum: [Órgãos](/documentation/guides/publico/entes#sp-orgaos) |
| employment_relationships[].registration_number | string | Matrícula, exatamente como o órgão a emite |
| employment_relationships[].next_payroll_date | string | Próxima data de processamento da folha |
| employment_relationships[].has_inflight_operation | boolean | Indica que há operação em andamento sobre a matrícula |
| employment_relationships[].margins | array | Margem por produto, consolidada no nível da matrícula |
| margins[].product | object | Produto — o "balde" de margem consumido. Enum: [Produtos](/documentation/guides/publico/enumeradores#product) |
| margins[].available_value | number | Margem disponível, em reais, **sem nenhuma reserva de segurança aplicada** |
| margins[].situation | object | Situação da margem. Enum: [Situação da margem](/documentation/guides/publico/enumeradores#margin_situation) |
| margins[].rule | string | Regra usada para consolidar os provimentos: `largest_appointment` ou `summed` |

#### Detalhar por provimento {#expansoes}

Por padrão o documento vai até o nível da **matrícula**, com a margem já consolidada pela regra do ente. Esse é o nível em que a averbação acontece e, portanto, o nível que interessa para ofertar.

**Query Params**

| Campo | Tipo | Descrição |
|---|---|---|
| expand | string | `appointments` — acrescenta os provimentos de cada matrícula |

:::caution Não some as margens dos provimentos
Os valores por provimento existem para conferência. Quando o ente consolida pela regra do **maior provimento**, somar os provimentos produz uma margem que não existe — e a averbação será recusada. Use sempre o valor consolidado da matrícula.
:::

**Response Body**

```json
{
  "registration_number": "1234567890123",
  "appointments": [
    {
      "appointment_number": "01",
      "relationship_type": {
        "code": 1,
        "enumerator": "statutory",
        "translation": "Estatutário"
      },
      "margins": [
        {
          "product": {
            "code": 2,
            "enumerator": "credit_card",
            "name": "Cartão de Crédito"
          },
          "gross_value": 1800.00,
          "available_value": 1400.00,
          "situation": {
            "code": 1,
            "enumerator": "available",
            "translation": "Margem disponível"
          },
          "history": [
            { "reference_month": "2026-07", "available_value": 1350.00 }
          ]
        }
      ]
    }
  ]
}
```

**Response Body Details**

| Campo | Tipo | Descrição |
|---|---|---|
| appointments[].appointment_number | string | Número do provimento |
| appointments[].relationship_type | object | Tipo de vínculo. Enum: [Tipo de vínculo](/documentation/guides/publico/enumeradores#relationship_type) |
| margins[].gross_value | number | Margem bruta do provimento, antes dos descontos já consignados |
| margins[].history | array | Margem disponível nas competências que vieram nesta resposta |

## Consulta estática

Os dados retornados como resultado de uma consulta são estáticos: consultar a mesma chave no futuro devolve exatamente o mesmo conteúdo, com o mesmo `observed_at`, independente de alterações na margem e novas consultas que possam ter ocorrido  no meio tempo. 

Não existe endpoint que devolva "a margem mais recente consultada" de um CPF. Para dados atualizados, crie e referencie uma **nova consulta**. 

O campo `valid_until` é o **último dia do mês da observação**. Depois dele, a consulta continua legível, mas não serve mais de base para uma averbação. Ver [Pré-requisitos da reserva](/documentation/guides/publico/reserva#pre-requisitos).

## A margem é indicativa {#a-margem-e-indicativa}

Dentro do prazo de validade, a margem informada ainda assim é **indicativa**: ela muda sempre que qualquer instituição averba ou desaverba naquele servidor, inclusive entre a consulta e a averbação. Nenhuma política de validade torna uma consulta segura para contratar às cegas.

**A margem só é garantida no momento da averbação.** A API devolve o valor bruto informado pelo ente, sem descontar nenhuma reserva de segurança — a margem de segurança que o parceiro deduz antes de ofertar é uma regra do parceiro, aplicada sobre o valor que recebe.

A regra de validade que a QI Tech aplica é única e não configurável: **a averbação exige uma consulta do mês corrente** para aquele vínculo. Ver [Pré-requisitos da reserva](/documentation/guides/publico/reserva#pre-requisitos).

## Quando a consulta falha {#quando-a-consulta-falha}

Uma consulta termina em `failed` quando o ente não pôde respondê-la — tipicamente porque o servidor não autorizou a consulta de margem. O corpo vem com o mesmo envelope, `employment_relationships` vazio e o motivo preenchido:

```json
{
  "status": "failed",
  "reason": {
    "enumerator": "employee_not_authorized",
    "code": "...",
    "description": "...",
    "translation": "O servidor não autorizou a consulta de margem"
  },
  "employment_relationships": []
}
```

Os motivos possíveis são definidos pela plataforma do ente. Ver [Motivos](/documentation/guides/publico/enumeradores#reason).

**Margem zerada não é falha.** Um vínculo sem margem disponível, ou com margem insuficiente, produz uma consulta `completed` com o valor que o ente informou — o vínculo e os seus dados continuam válidos e utilizáveis.

---

# Consignado Público - Emissão

URL: /documentation/guides/publico/credito-novo/emissao

:::caution Em desenvolvimento
Esta etapa ainda não está disponível. A documentação de criação da operação e do instrumento de crédito será publicada junto com a modalidade.
:::

Enquanto isso, as etapas já disponíveis do Consignado Público são a [Consulta de Margem](/documentation/guides/publico/consulta-de-margem) e a [Reserva de Margem](/documentation/guides/publico/reserva). Para a visão do produto inteiro, ver [Visão Geral](/documentation/guides/publico/visao_geral#a-jornada).

---

# Consignado Público - Formalização

URL: /documentation/guides/publico/credito-novo/formalizacao

:::caution Em desenvolvimento
Esta etapa ainda não está disponível. A documentação de envio de documentos e assinatura do servidor será publicada junto com a modalidade.
:::

Enquanto isso, as etapas já disponíveis do Consignado Público são a [Consulta de Margem](/documentation/guides/publico/consulta-de-margem) e a [Reserva de Margem](/documentation/guides/publico/reserva). Para a visão do produto inteiro, ver [Visão Geral](/documentation/guides/publico/visao_geral#a-jornada).

---

# Consignado Público - Simulação

URL: /documentation/guides/publico/credito-novo/simulacao

:::caution Em desenvolvimento
Esta etapa ainda não está disponível. A documentação de cálculo das condições de uma operação a partir da margem consignável do servidor será publicada junto com a modalidade.
:::

Enquanto isso, as etapas já disponíveis do Consignado Público são a [Consulta de Margem](/documentation/guides/publico/consulta-de-margem) e a [Reserva de Margem](/documentation/guides/publico/reserva). Para a visão do produto inteiro, ver [Visão Geral](/documentation/guides/publico/visao_geral#a-jornada).

---

# Consignado Público - Entes Consignantes

URL: /documentation/guides/publico/entes

Esta é a página de referência dos **entes consignantes** atendidos pelo Consignado Público: quais existem, como nomeá-los nas rotas, qual [perfil de consignação](#perfis-de-consignacao) cada um usa e o que cada um exige de diferente. As demais páginas desta seção — e o [Manual Cartão Consignado](/documentation/manual_cartao_beneficio/visao_geral), na fonte `public_payroll` — apontam para as âncoras daqui.

:::caution API em desenvolvimento
Os enumeradores de ente e de esfera ainda estão em definição e podem mudar até o lançamento.
:::

## Entes atendidos {#entes-disponiveis}

| Ente | `consignment_entity` | `entity_level` | Quem atende | Perfil | |
|---|---|---|---|---|---|
| Governo do Estado de São Paulo | `sp` | `state` | Servidores estaduais de São Paulo, ativos e inativos | [Perfil 1](#perfis-de-consignacao) | |
| Município de São Paulo | `sao_paulo_sp` | `municipal` | Servidores municipais de São Paulo | [Perfil 1](#perfis-de-consignacao) | Em desenvolvimento |

O par (`entity_level`, `consignment_entity`) identifica o ente em toda a API:

```
POST /public_payroll/state/sp/balance_inquiry
```

## Perfis de consignação {#perfis-de-consignacao}

Cada ente mantém a sua folha em uma plataforma de consignação, e as plataformas diferem em três coisas: **como identificam o servidor**, **como informam a margem** e **quais enumeradores usam**. O conjunto dessas três é o que chamamos de **perfil**.

Entes na mesma plataforma compartilham o perfil e, portanto, os mesmos payloads — o perfil é documentado uma vez, aqui, e a [tabela de entes](#entes-disponiveis) diz qual perfil cada ente usa.

**Perfil 1**

O servidor é identificado pelo **órgão** em que trabalha e pela **matrícula** que tem nesse órgão. A margem é apurada por cargo e consolidada no nível da matrícula.

#### Identificação do servidor

| Campo | Tipo | Descrição | Obrigatório |
|---|---|---|---|
| agency | string | Enumerador do órgão do servidor — a unidade pagadora dentro do ente: secretaria, autarquia, instituto de previdência | Sim |
| registration_number | string | Matrícula do servidor no órgão. Um mesmo CPF pode ter mais de uma | Sim |

```json
{
  "employment_relationship": {
    "agency": "spprev",
    "registration_number": "1234567890123"
  }
}
```

Os dois valores vêm da [Consulta de Margem](/documentation/guides/publico/consulta-de-margem).

**A averbação é registrada no nível da matrícula**, e o órgão é o que determina o calendário de folha e os limites comerciais da operação.

#### Estrutura da margem

Abaixo da matrícula existe o **provimento**: cada cargo concorrente que o servidor ocupa sob a mesma matrícula. A margem é apurada por provimento e por **produto** — o "balde" de margem que cada tipo de operação consome.

A consulta entrega a margem já **consolidada no nível da matrícula**, aplicando a regra do ente: somar os provimentos, ou considerar apenas o maior. A regra usada vem no campo `rule`. Os valores por provimento ficam disponíveis sob demanda, com `expand=appointments`.

#### Enumeradores deste perfil

- [Produtos](/documentation/guides/publico/enumeradores#product)
- [Situação da margem](/documentation/guides/publico/enumeradores#margin_situation)
- [Tipo de vínculo](/documentation/guides/publico/enumeradores#relationship_type)

## Particularidades por ente {#particularidades}

**São Paulo (Estado)**

| Item | Valor |
|---|---|
| `consignment_entity` | `sp` |
| `entity_level` | `state` |
| Perfil | [Perfil 1](#perfis-de-consignacao) |
| Regra de margem entre provimentos | Maior provimento — os provimentos **não** somam |
| Aprovação do servidor | **Obrigatória** em toda averbação nova |

#### Aprovação do servidor {#sp-aprovacao}

Desde 01.05.2026, o Governo do Estado de São Paulo exige que o próprio servidor aprove cada nova averbação no **aplicativo do ente**, com validação biométrica. A aprovação acontece depois que a averbação é registrada e vale **até o fim do mesmo dia**: o que não for aprovado nesse prazo é cancelado pelo ente por decurso de prazo.

Duas consequências para a integração:

- A averbação passa por um período de confirmação antes de ser considerada efetiva. Ver [Confirmação](/documentation/guides/publico/reserva#confirmacao).
- Averbações enviadas perto do fim do dia são retidas pela QI Tech e submetidas na janela seguinte, para não nascerem sem tempo hábil de aprovação.

#### Margem entre provimentos

Quando um servidor tem mais de um provimento na mesma matrícula, a margem considerada é a do **maior provimento**, não a soma. A [Consulta de Margem](/documentation/guides/publico/consulta-de-margem) já entrega o valor consolidado com essa regra aplicada, e informa no campo `rule` qual regra usou.

#### Órgãos {#sp-orgaos}

O enumerador do órgão é o valor enviado em `agency`.

| Órgão | `agency` | Calendário de folha |
|---|---|---|
| São Paulo Previdência | `spprev` | Em construção |
| *Demais órgãos* | Em construção | Em construção |

Os exemplos desta seção usam `spprev`.

#### Tipos de reserva e produtos {#sp-tipos-de-reserva}

Cada [tipo de reserva](/documentation/guides/publico/enumeradores#reservation_type) oferecido pelo ente consome a margem de um [produto](/documentation/guides/publico/enumeradores#product).

| Tipo de reserva | Produto |
|---|---|
| `payroll_card` | `credit_card` (`2`) |
| `benefit_card` | Em construção |
| `payroll_loan` | Em construção |

#### Canais de autorização {#sp-canais-de-autorizacao}

Valores aceitos em `authorization.channel` na [consulta de margem](/documentation/guides/publico/consulta-de-margem#criar-uma-consulta).

| `channel` | Onde a anuência é colhida |
|---|---|
| *Em construção* | Em construção |

#### Limites comerciais

Prazo máximo e carência máxima da operação são definidos por órgão e por tipo de reserva. Para o cartão consignado, o [Manual Cartão Consignado](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_emissao) descreve como esses limites são aplicados na contratação.

**São Paulo (Município)**

Em desenvolvimento. Órgãos, tipos de reserva, produtos e canais de autorização deste ente são publicados aqui quando ele for habilitado.

---

# Consignado Público - Enumeradores

URL: /documentation/guides/publico/enumeradores

Tabelas de referência do Consignado Público. Esta é a única página onde estes enumeradores são definidos; as demais páginas linkam para as âncoras daqui.

Os enumeradores estão em dois grupos. Os **gerais** são do contrato da QI Tech e valem em todo ente. Os **por perfil** são definidos pela plataforma de consignação do ente, e por isso mudam com o [perfil](/documentation/guides/publico/entes#perfis-de-consignacao).

:::caution API em desenvolvimento
Esta API está em fase de desenvolvimento, sendo assim, esta página está sujeita a alterações.
:::

## Enumeradores gerais

### Status da reserva {#reservation_status}

| Status | Significado |
|---|---|
| `pending_reservation` | A reserva foi criada e aguarda o registro no ente |
| `reserved` | **A averbação está ativa e a margem está comprometida.** É o único status em que a operação é garantida |
| `suspended` | A averbação existe, mas está bloqueada no ente. Pode voltar a `reserved` no desbloqueio |
| `canceled` | A operação **nunca existiu** no ente: foi desistida antes do registro, ou as tentativas de registro se esgotaram |
| `deleted` | A operação **existiu** no ente e foi removida — pela QI Tech, pelo servidor, pelo órgão ou pelo decurso de um prazo |
| `settled` | A operação existiu no ente e chegou ao fim: todas as parcelas foram processadas |

Os três status finais se distinguem pelo que aconteceu **no ente**: `canceled` nunca chegou lá, `deleted` chegou e saiu, `settled` chegou e terminou.

Entre `pending_reservation` e `reserved` pode haver status intermediários, conforme o número de etapas que o ente exige para registrar uma averbação. Ver [Status adicionais do Perfil 1](#reservation_status_perfil_1).

Cada transição gera um [webhook](/documentation/guides/publico/webhooks#reservation_status_change).

### Status da consulta de margem {#balance_inquiry_status}

| Status | Significado |
|---|---|
| `pending` | A consulta foi criada e ainda não foi respondida pelo ente |
| `completed` | O ente respondeu. O documento com os vínculos e as margens está disponível |
| `failed` | A consulta não pôde ser respondida pelo ente |

Margem zerada ou insuficiente produz `completed`, não `failed`.

### Tipos de reserva {#reservation_type}

O tipo de reserva é a modalidade comercial da operação, e determina de qual produto a margem é consumida.

| Enumerador | Modalidade |
|---|---|
| `payroll_loan` | Empréstimo consignado |
| `payroll_card` | Cartão consignado |
| `benefit_card` | Cartão benefício |

Quais tipos cada ente oferece está em [Entes Consignantes](/documentation/guides/publico/entes#particularidades).

### Esferas do ente {#entity_level}

| Enumerador | Esfera |
|---|---|
| `state` | Ente estadual |
| `municipal` | Ente municipal |

É o primeiro segmento da rota, antes do enumerador do ente. Ver [Entes Consignantes](/documentation/guides/publico/entes#entes-disponiveis).

### Motivos {#reason}

Sempre que um status precisa ser explicado — uma consulta que falhou, uma averbação recusada ou removida — a resposta traz um objeto `reason`. **A estrutura é geral; os valores são do ente**, e vêm da plataforma em que a folha é consignada.

| Campo | Descrição |
|---|---|
| enumerator | O motivo, em forma estável. É por ele que a integração deve ramificar |
| code | O código devolvido pelo ente consignante |
| description | Texto operacional, para diagnóstico |
| translation | Texto em português, apresentável ao usuário final |

```json
{
  "enumerator": "employee_not_authorized",
  "code": "...",
  "description": "...",
  "translation": "O servidor não autorizou a consulta de margem"
}
```

`reason` é `null` quando o status não precisa de explicação — uma consulta `completed`, uma reserva `reserved`.

## Enumeradores por perfil de consignação

**Perfil 1**

### Status adicionais da reserva {#reservation_status_perfil_1}

Neste perfil o registro da averbação tem até duas etapas, e a situação da averbação precisa ser confirmada depois do registro. Daí dois status além dos [gerais](#reservation_status):

| Status | Significado |
|---|---|
| `pending_finalization` | O ente aceitou a reserva e aguarda a finalização da operação. Ocorre apenas nas modalidades registradas em duas etapas |
| `pending_confirmation` | A averbação foi registrada e a QI Tech aguarda o ente definir a sua situação — inclusive a aprovação do servidor, onde ela é exigida. Ver [Confirmação](/documentation/guides/publico/reserva#confirmacao) |

### Produtos {#product}

O produto é o "balde" de margem consumido pela operação. O servidor tem um saldo de margem por produto, e tipos de reserva diferentes consomem produtos diferentes. Devolvido como `{code, enumerator, name}`.

| Código | Enumerador | Nome |
|---|---|---|
| `1` | `optional_consignment` | Consignações Facultativas |
| `2` | `credit_card` | Cartão de Crédito |
| *Demais códigos* | Em construção | Em construção |

Quais produtos existem em cada ente está em [Entes Consignantes](/documentation/guides/publico/entes#particularidades).

### Situação da margem {#margin_situation}

Acompanha cada valor de margem na [consulta de margem](/documentation/guides/publico/consulta-de-margem), e é devolvida como `{code, enumerator, translation}`.

| Código | Situação | Efeito na consulta |
|---|---|---|
| `1` | Margem disponível | `completed`, com o valor informado |
| `2` | Consulta não autorizada pelo servidor | `failed` quando é a situação de todos os itens |
| `3` | Margem indisponível | `completed`, com margem zerada |
| `4` | Margem insuficiente | `completed`, com o valor informado |

Os códigos `3` e `4` **não são erro**: a consulta foi respondida, e os vínculos descobertos continuam válidos para operações futuras.

### Tipo de vínculo {#relationship_type}

Acompanha cada provimento quando a consulta é feita com `expand=appointments`, e é devolvido como `{code, enumerator, translation}`.

| Código | Enumerador | Tradução |
|---|---|---|
| `1` | `statutory` | Estatutário |
| *Demais códigos* | Em construção | Em construção |

### Motivos {#reason_perfil_1}

Motivos devolvidos por este perfil, na estrutura descrita em [Motivos](#reason).

| Enumerador | Quando ocorre |
|---|---|
| `employee_not_authorized` | O servidor não autorizou a consulta de margem no ente |
| *Demais motivos* | Em construção |

---

# Consignado Público - Portabilidade

URL: /documentation/guides/publico/portabilidade

:::caution Em desenvolvimento
Esta etapa ainda não está disponível. A documentação de transferência de uma operação consignada de outra instituição para a QI Tech será publicada junto com a modalidade.
:::

Enquanto isso, as etapas já disponíveis do Consignado Público são a [Consulta de Margem](/documentation/guides/publico/consulta-de-margem) e a [Reserva de Margem](/documentation/guides/publico/reserva). Para a visão do produto inteiro, ver [Visão Geral](/documentation/guides/publico/visao_geral#a-jornada).

---

# Consignado Público - Refinanciamento

URL: /documentation/guides/publico/refinanciamento

:::caution Em desenvolvimento
Esta etapa ainda não está disponível. A documentação de renegociação de uma operação consignada ativa será publicada junto com a modalidade.
:::

Enquanto isso, as etapas já disponíveis do Consignado Público são a [Consulta de Margem](/documentation/guides/publico/consulta-de-margem) e a [Reserva de Margem](/documentation/guides/publico/reserva). Para a visão do produto inteiro, ver [Visão Geral](/documentation/guides/publico/visao_geral#a-jornada).

---

# Consignado Público - Reserva de Margem

URL: /documentation/guides/publico/reserva

A reserva é a **averbação**: o registro da operação no ente consignante, que compromete a margem do servidor e ordena o desconto em folha. É o que transforma uma proposta em garantia.

:::caution API em desenvolvimento
Esta API está em fase de desenvolvimento, sendo assim, esta página está sujeita a alterações.
:::

:::info A reserva não é criada diretamente
Esta página é o que o parceiro precisa para **acompanhar** essa reserva: as regras que ela obedece, o que cada status significa, como consultá-la e como obter o comprovante.

Para mais informações sobre a emissão de uma dívida com consignação no Consignado Público, acessar as páginas referentes ao produto: [cartão consignado](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_emissao), [crédito novo](/documentation/guides/publico/credito-novo/simulacao) e [portabilidade](/documentation/guides/publico/portabilidade).

:::

## Pré-requisitos {#pre-requisitos}

Uma averbação só é aceita quando as duas condições abaixo são verdadeiras. Uma contratação que as viole é recusada antes de chegar ao ente:

1. **O vínculo já foi observado por uma [consulta de margem](/documentation/guides/publico/consulta-de-margem).** O vínculo informado precisa ter sido descoberto em uma consulta daquele CPF naquele ente. A averbação nunca espera por uma consulta: se o vínculo é desconhecido, a operação é recusada na hora.
2. **A observação é do mês corrente.** O ente informa a margem por competência e a folha fecha mensalmente, então uma consulta de um mês anterior não sustenta uma averbação. O `valid_until` da consulta é o último dia do mês em que ela foi observada.

:::caution A margem enviada é a que o parceiro ofertou
O valor averbado é o que o parceiro decidiu ofertar, já com a sua própria margem de segurança aplicada. A QI Tech não relê a margem antes de averbar: envia o valor e trata a recusa do ente, se houver. É assim porque a margem muda a qualquer momento, e só a averbação garante o valor. Ver [A margem é indicativa](/documentation/guides/publico/consulta-de-margem#a-margem-e-indicativa).
:::

## Validar um vínculo

**POST**
/public_payroll/{entity_level}/{consignment_entity}/reservation/validation

Confere se o CPF e o vínculo digitados resolvem para um vínculo conhecido e observado no mês corrente — as duas condições de [Pré-requisitos](#pre-requisitos).

### Request

**Request Body**

```json
{
  "employee_document_number": "12345678901",
  "employment_relationship": { ... }
}
```

**Request Body Details**

| Campo | Tipo | Descrição | Obrigatório |
|---|---|---|---|
| employee_document_number | string | CPF do servidor, apenas dígitos | Sim |
| employment_relationship | object | Identificação do vínculo, conforme o [perfil do ente](/documentation/guides/publico/entes#perfis-de-consignacao) | Sim |

**Perfil 1**

**Request Body**

```json
{
  "employee_document_number": "12345678901",
  "employment_relationship": {
    "agency": "spprev",
    "registration_number": "1234567890123"
  }
}
```

**Request Body Details**

| Campo | Tipo | Descrição | Obrigatório |
|---|---|---|---|
| employment_relationship.agency | string | Enumerador do órgão do servidor. Enum: [Órgãos](/documentation/guides/publico/entes#sp-orgaos) | Sim |
| employment_relationship.registration_number | string | Matrícula do servidor no órgão, exatamente como o órgão a emite | Sim |

### Response

STATUS
**200** (OK)

**Response Body**

```json
{
  "balance_inquiry_key": "b1b9f0a6-9a3e-4f9b-9d6f-3a5f8c1d2e7b",
  "observed_at": "2026-08-26T10:02:40-03:00",
  "valid_until": "2026-08-31"
}
```

**Response Body Details**

| Campo | Tipo | Descrição |
|---|---|---|
| balance_inquiry_key | string | A consulta em que o vínculo foi observado |
| observed_at | string | Momento da observação |
| valid_until | string | Último dia em que uma averbação pode se apoiar nessa consulta |

STATUS
**422** (Unprocessable Entity)

Quando o vínculo não existe no registro, ou quando a observação é de um mês anterior. O corpo nomeia qual dos dois casos ocorreu. A saída é a mesma nos dois: criar uma nova [consulta de margem](/documentation/guides/publico/consulta-de-margem).

## Acompanhar a reserva

**GET**
/public_payroll/{entity_level}/{consignment_entity}/reservation/{reservation_key}

**GET**
/public_payroll/{entity_level}/{consignment_entity}/reservation/external_key/{origin_key}

A segunda forma endereça a reserva pela **chave da operação de origem** — a chave do cartão ou da operação de crédito que a originou.

#### Query Params

**Query Params**

| Campo | Tipo | Descrição |
|---|---|---|
| expand | string | `events` (histórico de status) · `contract_data` (condições da operação) · `protocols` (comprovantes) |

### Response

STATUS
**200** (OK)

**Response Body**

```json
{
  "reservation_key": "6f4c2a19-8e3b-4d7a-b0c5-1e2f3a4b5c6d",
  "origin": {
    "type": "payroll_card_reservation",
    "key": "a7c3e1f0-4b2d-4c8e-9f11-5d6a7b8c9d0e"
  },
  "status": "reserved",
  "reason": null,
  "created_at": "2026-08-17T14:03:00-03:00",
  "consignment_entity": {
    "code": "46379400",
    "enumerator": "sp",
    "name": "Governo do Estado de São Paulo"
  },
  "employee_document_number": "12345678901",
  "employment_relationship": { ... },
  "reservation": { ... }
}
```

**Response Body Details**

| Campo | Tipo | Descrição |
|---|---|---|
| reservation_key | string | Chave da reserva |
| origin | object | A operação que originou a reserva, `{type, key}` |
| status | string | Situação da reserva. Enum: [Status da reserva](/documentation/guides/publico/enumeradores#reservation_status) |
| reason | object | Motivo do status atual, quando há. Ver [Motivos](/documentation/guides/publico/enumeradores#reason) |
| created_at | string | Momento da criação da reserva |
| consignment_entity | object | Ente, no formato `{code, enumerator, name}` |
| employee_document_number | string | CPF do servidor |
| employment_relationship | object | O vínculo averbado |
| reservation | object | Dados da averbação no ente |

O conteúdo de `employment_relationship` e de `reservation` muda com o [perfil](/documentation/guides/publico/entes#perfis-de-consignacao):

**Perfil 1**

**Response Body**

```json
{
  "employment_relationship": {
    "agency": {
      "code": "20065",
      "enumerator": "spprev",
      "name": "SPPREV"
    },
    "registration_number": "1234567890123"
  },
  "reservation": {
    "type": {
      "enumerator": "payroll_card",
      "name": "Cartão consignado"
    },
    "contract_number": "PCR0001234567890",
    "amount": 180.00,
    "contract_start_date": "2026-08-17",
    "external_reservation_number": "...",
    "approval_deadline": "2026-08-18",
    "next_payroll_date": "2026-09-05"
  }
}
```

**Response Body Details**

| Campo | Tipo | Descrição |
|---|---|---|
| employment_relationship.agency | object | Órgão da matrícula, no formato `{code, enumerator, name}`. Enum: [Órgãos](/documentation/guides/publico/entes#sp-orgaos) |
| employment_relationship.registration_number | string | Matrícula, exatamente como o órgão a emite |
| reservation.type | object | Tipo de reserva. Enum: [Tipos de reserva](/documentation/guides/publico/enumeradores#reservation_type) |
| reservation.contract_number | string | Número do contrato no ente. Identifica a averbação para sempre, e não é reaproveitável |
| reservation.amount | number | Valor mensal reservado, em reais |
| reservation.contract_start_date | string | Data de início do contrato |
| reservation.external_reservation_number | string | Número da averbação no ente |
| reservation.approval_deadline | string | Prazo para a aprovação do servidor, quando o órgão a exige |
| reservation.next_payroll_date | string | Próxima data de processamento da folha |

Cada mudança de status também é notificada por [webhook](/documentation/guides/publico/webhooks#reservation_status_change), o que dispensa consultar em laço.

## Confirmação {#confirmacao}

Alguns entes exigem uma **etapa de confirmação** como parte da averbação: o registro é aceito, mas a operação só passa a valer depois que o ente confirma a sua situação. Enquanto isso a reserva fica em um status intermediário, e a QI Tech acompanha o ente até a situação se definir.

Se o ente exige essa etapa, e o que decide o seu desfecho, depende do perfil:

**Perfil 1**

A confirmação acontece em toda reserva, de qualquer modalidade: a resposta do registro não informa se a averbação ficou ativa, então a reserva passa por `pending_confirmation` até o ente responder.

O que muda é **quem decide** o desfecho, e isso é definido pelo órgão:

- Onde o órgão **não exige aprovação do servidor**, a confirmação se resolve na primeira leitura da situação no ente.
- Onde o órgão **exige aprovação do servidor**, a averbação só fica ativa depois que o servidor aprova, dentro de `approval_deadline`. Ver [Entes Consignantes](/documentation/guides/publico/entes#particularidades).

Nos dois casos há dois desfechos possíveis:

- **`reserved`** — a averbação está ativa e a margem está comprometida.
- **`deleted`** — a averbação foi removida antes de se efetivar. O caso mais comum é o servidor não ter aprovado a operação dentro do prazo do ente.

## Cancelamento

O cancelamento também parte da operação de origem: cancelar o cartão ou a operação de crédito é o que faz a QI Tech **desaverbar** a margem no ente.

## Comprovante

**GET**
/public_payroll/{entity_level}/{consignment_entity}/reservation/{reservation_key}/protocol

**GET**
/public_payroll/{entity_level}/{consignment_entity}/reservation/external_key/{origin_key}/protocol

Devolve os comprovantes da reserva — a evidência de que a operação foi executada no ente. Um comprovante de **averbação** é emitido quando a reserva é confirmada; um de **desaverbação**, quando o cancelamento é concluído. Uma reserva que nunca chegou a ser confirmada não gera comprovante.

### Response

STATUS
**200** (OK)

**Response Body**

```json
[
  {
    "protocol_key": "3c9d1e2f-7a8b-4c5d-9e0f-1a2b3c4d5e6f",
    "type": "reservation",
    "created_at": "2026-08-18T09:12:00-03:00",
    "receipt_url": "https://...",
    "receipt": { }
  }
]
```

**Response Body Details**

| Campo | Tipo | Descrição |
|---|---|---|
| protocol_key | string | Chave do comprovante |
| type | string | `reservation` (averbação) ou `deletion` (desaverbação) |
| created_at | string | Momento em que a operação foi comprovada |
| receipt_url | string | O documento renderizado |
| receipt | object | A mesma evidência em campos |

## Ciclo de vida

A sequência completa de status, com o que provoca cada transição, está em [Enumeradores](/documentation/guides/publico/enumeradores#reservation_status).

---

# Consignado Público - Visão Geral

URL: /documentation/guides/publico/visao_geral

**Consignado Público** é a consignação em folha de **servidores públicos estaduais e municipais**. O ente consignante — o estado ou o município que paga a folha — mantém o registro da margem consignável de cada servidor, e é nele que a QI Tech reserva a parcela mensal que garante a operação.

:::caution API em desenvolvimento
Esta seção documenta um produto em construção. As páginas marcadas como *em desenvolvimento* ainda não têm conteúdo, e o que já está publicado pode mudar até o lançamento.
:::

:::info O que esta seção cobre
O **cartão consignado** de servidor público é contratado pelo [Manual Cartão Consignado](/documentation/manual_cartao_beneficio/visao_geral), na fonte `public_payroll` — esta seção contém a referência de margem, entes e averbação que aquele manual consulta. Além disso, o fluxo de averbação do crédito consignado sem ser de cartão se encontra aqui.
:::

## Como uma operação é endereçada {#como-uma-operacao-e-enderecada}

Uma operação de Consignado Público é endereçada em dois passos.

**A rota nomeia o ente.** A esfera — `state` ou `municipal` — e o enumerador do ente são os dois primeiros segmentos:

```
/public_payroll/{entity_level}/{consignment_entity}/...
```

**O corpo identifica o servidor.** Quais campos fazem isso **depende do ente**: cada ente mantém a sua folha em uma plataforma de consignação, e as plataformas não identificam o servidor da mesma forma. Umas exigem o órgão pagador, outras uma senha do servidor, outras apenas a matrícula.

É por isso que a seção trabalha com **perfis de consignação**. Ver [Perfis de consignação](#perfis-de-consignacao) e, para os campos de cada perfil, [Entes Consignantes](/documentation/guides/publico/entes#perfis-de-consignacao).

## Perfis de consignação {#perfis-de-consignacao}

Um **perfil** é o conjunto do que varia entre plataformas de consignação:

- **Como o servidor é identificado** — quais campos o corpo precisa carregar.
- **Como a margem é informada** — a estrutura do documento de consulta, e se ele detalha a margem por cargo, por produto ou em um valor único.
- **Quais enumeradores valem** — produtos, situações de margem, tipos de vínculo e motivos de recusa são definidos pela plataforma, não pela QI Tech.

Entes na mesma plataforma compartilham um perfil, e portanto compartilham exatamente os mesmos payloads. Cada perfil é documentado uma vez; a tabela de entes diz qual perfil cada ente usa.

## A jornada de uma contratação {#a-jornada}

1. **Consulta de margem** — descobre os vínculos do CPF no ente e a margem disponível em cada um. Assíncrona. Ver [Consulta de Margem](/documentation/guides/publico/consulta-de-margem).
2. **Simulação** — calcula as condições da operação a partir da margem. *Em desenvolvimento.*
3. **Emissão** — cria a operação e o instrumento de crédito. *Em desenvolvimento.*
4. **Formalização** — assinatura e documentos do servidor. *Em desenvolvimento.*
5. **Averbação** — reserva a margem no ente. É a etapa que pode falhar por margem insuficiente e, em alguns entes, depende da aprovação do próprio servidor. Ver [Reserva de Margem](/documentation/guides/publico/reserva).
6. **Desembolso** — liberação do valor contratado. *Em desenvolvimento.*

Cada mudança de status é notificada por webhook. Ver [Webhooks](/documentation/guides/publico/webhooks).

## Conteúdo desta seção

| Página | Conteúdo | |
|---|---|---|
| **[Entes Consignantes](/documentation/guides/publico/entes)** | Entes atendidos, perfis de consignação e particularidades de cada ente | |
| **[Consulta de Margem](/documentation/guides/publico/consulta-de-margem)** | Descoberta de vínculos e margem disponível | |
| **[Reserva de Margem](/documentation/guides/publico/reserva)** | Acompanhamento da averbação, cancelamento e comprovante | |
| **[Crédito Novo](/documentation/guides/publico/credito-novo/simulacao)** | Simulação, emissão e formalização | Em desenvolvimento |
| **[Portabilidade](/documentation/guides/publico/portabilidade)** | Transferência de operação de outra instituição | Em desenvolvimento |
| **[Refinanciamento](/documentation/guides/publico/refinanciamento)** | Renegociação de operação ativa | Em desenvolvimento |
| **[Webhooks](/documentation/guides/publico/webhooks)** | Notificações de mudança de status | |
| **[Enumeradores](/documentation/guides/publico/enumeradores)** | Status, motivos, produtos e tipos de reserva | |

## Glossário

| Termo | Significado |
|---|---|
| **Ente consignante** (`consignment_entity`) | O governo estadual ou municipal que paga a folha e mantém o registro de margem consignável. |
| **Vínculo** | A relação do servidor com o ente que sustenta a consignação. Como ele é identificado depende do [perfil](#perfis-de-consignacao) do ente. |
| **Margem consignável** | Valor mensal do salário ou provento que pode ser comprometido com consignações. |
| **Averbação** | Registro da operação no ente, que reserva a margem e ordena o desconto em folha. |
| **Desaverbação** | Remoção de uma averbação existente, liberando a margem. |
| **Consulta de margem** (`balance_inquiry`) | Pergunta ao ente sobre os vínculos e a margem de um CPF. O resultado é uma fotografia, com validade no mês da observação. |
| **Perfil de consignação** | O que varia entre plataformas de consignação: identificação do servidor, estrutura do documento de margem e enumeradores. |
| **Comprovante** (`protocol`) | Recibo que prova que uma averbação ou desaverbação foi executada no ente. |

---

# Consignado Público - Webhooks

URL: /documentation/guides/publico/webhooks

Os fluxos do Consignado Público são assíncronos: a requisição registra a intenção e devolve `202`, e o resultado chega por webhook. Esta página lista as notificações publicadas hoje.

:::caution API em desenvolvimento
Esta API está em fase de desenvolvimento, sendo assim, esta página está sujeita a alterações. Os webhooks das etapas de crédito — simulação, emissão, formalização e desembolso — são publicados junto com aquelas modalidades.
:::

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeados de forma restrita.
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

## Notificações

| `webhook_type` | Quando é enviado |
|---|---|
| `laas.public_payroll.balance_inquiry_status_change` | A [consulta de margem](/documentation/guides/publico/consulta-de-margem) termina, em `completed` ou `failed` |
| `laas.public_payroll.reservation_status_change` | A [reserva](/documentation/guides/publico/reserva) muda de status |

Cada parceiro recebe apenas as suas operações, e a reserva é endereçada pela chave da operação que a originou (`origin_key`) — a mesma chave que o parceiro já usa para acompanhar o cartão ou a operação de crédito.

## Consulta de margem {#balance_inquiry_status_change}

| Campo | Tipo | Descrição |
|---|---|---|
| balance_inquiry_key | string | Chave da consulta |
| status | string | Situação final. Enum: [Status da consulta](/documentation/guides/publico/enumeradores#balance_inquiry_status) |
| reason | object | Motivo, quando a consulta falha. `null` em `completed`. Ver [Motivos](/documentation/guides/publico/enumeradores#reason) |

```json
{
  "webhook_type": "laas.public_payroll.balance_inquiry_status_change",
  "balance_inquiry_key": "b1b9f0a6-9a3e-4f9b-9d6f-3a5f8c1d2e7b",
  "status": "completed",
  "reason": null
}
```

:::info A margem não vem no webhook
A notificação carrega apenas a chave, o status e o motivo. Os dados da consulta — matrículas, órgãos e margens — ficam no `GET` da consulta, que é autenticado e devolve o documento completo. Ver [Consultar o resultado](/documentation/guides/publico/consulta-de-margem#consultar-o-resultado).
:::

## Reserva de margem {#reservation_status_change}

| Campo | Tipo | Descrição |
|---|---|---|
| reservation_key | string | Chave da reserva |
| origin_key | string | Chave da operação que originou a reserva — o cartão ou a operação de crédito |
| status | string | Novo status. Enum: [Status da reserva](/documentation/guides/publico/enumeradores#reservation_status) |
| reason | object | Motivo da mudança, quando há. Ver [Motivos](/documentation/guides/publico/enumeradores#reason) |

```json
{
  "webhook_type": "laas.public_payroll.reservation_status_change",
  "reservation_key": "6f4c2a19-8e3b-4d7a-b0c5-1e2f3a4b5c6d",
  "origin_key": "a7c3e1f0-4b2d-4c8e-9f11-5d6a7b8c9d0e",
  "status": "reserved",
  "reason": null
}
```

Os status que encerram a contratação são **`reserved`** — margem comprometida, operação garantida — e **`deleted`** ou **`canceled`**, quando a averbação não existe mais ou nunca chegou a existir. O `reason` é o que distingue os motivos, e em particular identifica a falta de aprovação do servidor, o único caso em que refazer a contratação é o caminho. Ver [Confirmação](/documentation/guides/publico/reserva#confirmacao).

---

# Inserção de Documentos

URL: /documentation/iaas/aditamento_recebiveis/envio_documento

### Request

ENDPOINT /asset_amendment/fund_class/FUND_CLASS_KEY/amendment_configuration/AMENDMENT_CONFIGURATION_KEY/asset_amendment/ASSET_AMENDMENT_KEY/document
MÉTODO POST

```json title='Request Body'
{
    "document_type":"amendment_term",
    "document_b64": "aGVsbG8gd29ybGQgaWYgeW91IGRlY29kZWQgbWUsIGJlIGNhcmVmdWwuIEl0IG11c3QgYmUgYSBQREYgRmlsZSBvdGhlcndpc2UgSSB3aWxsIHJhaXNlIGFuIEVycm9yLg=="
}
```

#### Body Params

| Campo | Tipo | Descrição
|-|-|-|
| `document_type` * | string | Tipo do documento (sempre amendment_term).|
| `document_b64` * | string | Deve ser o binário do arquivo, em PDF, encodado em Base64.

### Response

STATUS 201

```json title='Response Body'
{
    "document_key": "8e515a17-8b4d-49a3-aed6-47c9574e426a"
}
```

---

# Introdução

URL: /documentation/iaas/aditamento_recebiveis/inicio

O sistema de Aditamento de Recebíveis é uma solução que permite a modificação e atualização de contratos e acordos existentes relacionados a recebíveis. Este módulo oferece funcionalidades essenciais para:

- Realizar alterações em contratos de recebíveis já existentes
- Gerenciar modificações em condições de pagamento

Esta documentação fornece uma visão detalhada sobre como utilizar o sistema de aditamento, incluindo seus principais recursos e fluxos. Aqui você encontrará informações sobre:

- Processos de aditamento
- Endpoints e payloads

Para começar a utilizar o sistema, navegue pelos tópicos disponíveis nesta documentação para entender melhor cada aspecto do módulo de aditamento.

---

# Criação de pedido de aditamento

URL: /documentation/iaas/aditamento_recebiveis/pedido_aditamento_contrato

---
Para realizar um pedido de aditamento é necessário realizar uma requisição usando a chave única que representa o fundo(FUND_CLASS_KEY, fornecida pela Qi Tech) e a chave única que representa as configurações da esteira de aditamento(AMENDMENT_CONFIGURATION_KEY, fornecida pela Qi Tech).

Nos aditamentos realizados por este sistema é permitido a alteração do fluxo de pagamento ou taxa nominal do contrato ou ambos. Também é possível definir que o aditamento será realizado juntamente com uma entrada realizada pelo devedor.

### Request

ENDPOINT /asset_amendment/fund_class/FUND_CLASS_KEY/amendment_configuration/AMENDMENT_CONFIGURATION_KEY/asset_amendment
MÉTODO POST

```json title='Request Body'
{
	"asset_external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
    "amendment_date": "2024-04-01",
    "amendment_type": "all_contract",
    "down_payment_value": 400.23,
    "installments":[
        {
            "maturity_date": "2025-01-31",
            "face_value": 1000.31,
            "installment_number": 1
        },
        {
            "maturity_date": "2025-02-31",
            "face_value": 1000.31,
            "installment_number": 2
        }
    ],
    "pre_fixed":{
        "monthly_rate": 0.02,
        "calendar_base": "workdays"
    }
}
```

#### Body Params

| Campo | Tipo | Descrição | Obrigatório |
|-|-|-|-|
| `asset_external_id` | string | Chave única de identificação do contrato que está sendo aditado. | Sim |
| `amendment_date` | string | Data que o aditamento está sendo realizado (formato: YYYY-MM-DD) | Sim |
| `amendment_type` | string | Tipo de aditamento a ser realizado. Ver **[Enumerador Tipo de Aditamento](#enumerador-tipo-de-aditamento) | Sim |
| `down_payment_value` | number | Valor da entrada a ser paga pelo devedor no momento do aditamento | Não |
| `installments` | array | Lista de parcelas do contrato após o aditamento | Sim |
| `installments[].maturity_date` | string | Data de vencimento da parcela (formato: YYYY-MM-DD) | Sim |
| `installments[].face_value` | number | Valor nominal da parcela | Sim |
| `installments[].installment_number` | number | Número sequencial da parcela | Sim |
| `pre_fixed` | object | Configurações de taxa pré-fixada | Sim |
| `pre_fixed.monthly_rate` | number | Taxa mensal a ser aplicada | Sim |
| `pre_fixed.calendar_base` | string | Base de calendário para cálculo (ex: "workdays") | Sim |

### Response

STATUS 201

```json title='Response Body'
{
    "asset_amendment_key": "a914aac6-93ff-45ee-8574-f4dbaf6c0642",
    "status": "pending_assets_insertion",
}
```

### Enumerador Tipo de Aditamento
| Enumerador   | Descrição     |
|--------------|---------------|
| **payment_flow**   | Aditamento apenas de fluxo de pagamento |
| **nominal_rate** | Aditamento apenas de taxa nominal do contrato |
| **all_contract** | Aditamento do fluxo de pagament e taxa nominal do contrato |

:::caution **Atenção**
Os campos de installments e pre_fixed devem o não existir de acordo com o tipo de aditamento a ser realizado conforme a seguinte tabela
:::

| Tipo de aditamento | installments | pre_fixed |
|------------------- | ------------ | --------- |
| all_contract | Obrigatório | Obrigatório |
| pre_fixed | Não deve ser enviado | Obrigatório |
| payment_flow | Obrigatório | Não deve ser enviado |

---

# Boletador de Títulos Públicos

URL: /documentation/iaas/boletador/boletador_titulos_publicos

## Request

ENDPOINT /trade_treasury/fund_class/{fund_class_key}/operation
MÉTODO POST

### Path params

| Parâmetro | Tipo | Descrição |
| :---- | :---- | :---- |
| `fund_class_key` | string | Identificador único do fundo. |

```json title="Request Body"
{
    "external_id": "a3f1c2e4-7b8d-4e6f-9a0b-1c2d3e4f5a6b",
    "operation_date": "2025-12-04",
    "payment_date": "2025-12-04",
    "operation_part": "assignee",
    "operation_type": "outright_operation",
    "counterparty": {
        "iselic_number": "20824264",
        "selic_account_number": "123456789",
        "document_number": "20.824.264/0001-77"
    },
    "treasury_type": "ntn_b",
    "unit_price": 1234.567891,
    "units": 10,
    "maturity_date": "2035-05-15"
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
| :---- | :---- | :---- | :---- |
| `external_id` | string | opcional | Identificador externo para idempotência (UUID). Se não informado, será gerado automaticamente. Máximo de 36 caracteres. |
| `operation_date` | string (date) | obrigatório | Data da operação no formato `YYYY-MM-DD`. Deve ser um dia útil e igual à `accounting_date` do fundo. |
| `payment_date` | string (date) | obrigatório | Data de liquidação no formato `YYYY-MM-DD`. Deve ser `>= operation_date`. Em operações não-a-prazo (`outright_operation`, `buyback_operation`), deve ser igual à `operation_date`. |
| `operation_part` | string | obrigatório | Papel do fundo na operação: `assignee` (comprador) ou `assignor` (vendedor). |
| `operation_type` | string | obrigatório | Tipo de operação: `outright_operation`, `buyback_operation`. `buyback_operation` exige `operation_part == "assignee"`. |
| `counterparty` | object | obrigatório | Dados da contraparte. Ver objeto abaixo. |
| `treasury_type` | string | obrigatório | Tipo de título: `lft`, `ltn`, `ntn_b` ou `ntn_f`. |
| `unit_price` | number | obrigatório | Preço unitário do título. Aceita qualquer precisão decimal; o servidor trunca para baixo conforme o tipo: `buyback_operation` → 8 casas decimais; demais → 6 casas decimais. |
| `units` | integer | obrigatório | Quantidade de títulos (inteiro positivo). |
| `maturity_date` | string (date) | obrigatório | Data de vencimento do título (`YYYY-MM-DD`). Deve ser estritamente posterior à `operation_date`. |
| `yearly_negotiated_rate` | number | condicional | Taxa negociada anual (%). **Obrigatório para** `buyback_operation`. |
| `return_date` | string (date) | condicional | Data de retorno (`YYYY-MM-DD`). **Obrigatório para** `buyback_operation`. Deve ser `> operation_date`. |

#### Objeto `counterparty`

| Campo | Tipo | Obrigatoriedade | Descrição |
| :---- | :---- | :---- | :---- |
| `iselic_number` | string | obrigatório | Número iSELIC da contraparte (8 dígitos). |
| `selic_account_number` | string | obrigatório | Conta SELIC da contraparte (9 dígitos). |
| `document_number` | string | obrigatório | CNPJ da contraparte com pontuação (formato `XX.XXX.XXX/XXXX-XX`). |

## Response

STATUS 201

```json title="Response Body"
{
    "operation_key": "85cfd700-54a4-40f4-bc61-2ece992864ea",
    "external_id": "a3f1c2e4-7b8d-4e6f-9a0b-1c2d3e4f5a6b",
    "fund_class": {
        "fund_class_key": "5122bf31-660a-4f61-a447-38e5e17162dd",
        "manager_key": "bea7581a-f901-4995-a486-46e18ae61aab",
        "name": "FUNDO EXEMPLO DTVM",
        "document_number": "81.692.758/0001-30",
        "accounting_date": "2025-12-04"
    },
    "status": "pending_manager_approval",
    "operation_part": "assignee",
    "operation_type": {
        "enumerator": "outright_operation",
        "code": 1052
    },
    "treasury": {
        "enumerator": "ntn_b",
        "code": 760199
    },
    "operation_date": "2025-12-04",
    "payment_date": "2025-12-04",
    "maturity_date": "2035-05-15",
    "total_operation_value": 12345.67,
    "units": 10,
    "unit_price": 1234.567891,
    "counterparty": {
        "iselic_number": "20824264",
        "document_number": "20.824.264/0001-77",
        "selic_account_number": "123456789"
    },
    "isin_code": "BRSTNCNTB633",
    "issue_date": "2025-11-04",
    "operation_data": {}
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
| :---- | :---- | :---- |
| `operation_key` | string | Identificador único da operação gerado pela QI Tech (UUID). |
| `external_id` | string | Identificador externo fornecido ou gerado automaticamente. |
| `fund_class` | object | Dados do fundo associado à operação. |
| `status` | string | Status inicial da operação. |
| `operation_part` | string | `assignee` (comprador) ou `assignor` (vendedor). |
| `operation_type` | object | `{ enumerator, code }` — tipo de operação e código SELIC correspondente. |
| `treasury` | object | `{ enumerator, code }` — tipo de título e código SELIC correspondente. |
| `operation_date` | string | Data da operação (`YYYY-MM-DD`). |
| `payment_date` | string | Data de liquidação (`YYYY-MM-DD`). |
| `maturity_date` | string | Data de vencimento do título (`YYYY-MM-DD`). |
| `total_operation_value` | decimal | Valor total da operação (units × unit_price). |
| `units` | integer | Quantidade de títulos. |
| `unit_price` | number | Preço unitário do título. |
| `counterparty` | object | Dados da contraparte (`iselic_number`, `document_number`, `selic_account_number`). |
| `isin_code` | string | Código ISIN do título. |
| `issue_date` | string | Data de emissão do título (`YYYY-MM-DD`). |
| `operation_data` | object | Metadados internos adicionais da operação. |

---

# Listagem de Títulos Públicos

URL: /documentation/iaas/boletador/listagem_titulos_publicos

## Request

ENDPOINT /trade_treasury/fund_class/{fund_class_key}/operations
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
| :---- | :---- | :---- |
| `fund_class_key` | string | Identificador único do fundo. |

### Query params

| Parâmetro | Tipo | Padrão | Máximo | Descrição |
| :---- | :---- | :---- | :---- | :---- |
| `limit` | integer | 100 | 500 | Quantidade de itens por página. |
| `page` | integer | 0 | — | Número da página (base 0). |
| `status` | string | — | — | Filtra pelo status exato da operação. |
| `not_status` | string | — | — | Exclui operações com determinado status. |
| `treasury_type` | string | — | — | Filtra por tipo de título (`lft`, `ltn`, `ntn_b`, `ntn_f`). |
| `operation_type` | string | — | — | Filtra por tipo de operação (`outright_operation`, `buyback_operation`). |
| `operation_date` | string | — | — | Filtra pela data exata da operação (`YYYY-MM-DD`). |
| `from_operation_date` | string | — | — | Filtra operações com data `>=` ao valor (`YYYY-MM-DD`). |
| `to_operation_date` | string | — | — | Filtra operações com data `<=` ao valor (`YYYY-MM-DD`). |
| `maturity_date` | string | — | — | Filtra pela data exata de vencimento (`YYYY-MM-DD`). |
| `from_maturity_date` | string | — | — | Filtra vencimentos `>=` ao valor (`YYYY-MM-DD`). |
| `to_maturity_date` | string | — | — | Filtra vencimentos `<=` ao valor (`YYYY-MM-DD`). |

## Response

STATUS 200

```json title="Response Body"
{
    "data": [
        {
            "operation_key": "e96ff035-e0bc-4819-931a-6a9f7fc1c597",
            "external_id": "a3f1c2e4-7b8d-4e6f-9a0b-1c2d3e4f5a6b",
            "fund_class": {
                "fund_class_key": "9b6145dc-2207-428d-84c1-2f949461891a",
                "manager_key": "73a21e11-0ab7-461d-a93f-1e90c0a5dc0d",
                "name": "FUNDO DE INVESTIMENTO TESTE",
                "document_number": "41.202.838/0001-45",
                "accounting_date": "2025-04-14",
                "custodian": {
                    "name": "QI DISTRIBUIDORA DE TITULOS E VALORES MOBILIARIOS LTDA",
                    "document_number": "46.955.383/0001-52",
                    "iselic_number": "46955383"
                },
                "selic_account_number": "000216832",
                "target_account_key": "d3dcbf3c-1bbf-495b-b792-ac448ee20ac4"
            },
            "status": "pending_manager_approval",
            "operation_part": "assignee",
            "operation_type": {
                "enumerator": "outright_operation",
                "code": 1052
            },
            "treasury": {
                "enumerator": "ntn_b",
                "code": 760199
            },
            "operation_date": "2025-04-14",
            "payment_date": "2025-04-14",
            "maturity_date": "2025-05-15",
            "total_operation_value": 250.0,
            "units": 5,
            "unit_price": 50.0,
            "counterparty": {
                "iselic_number": "20824264",
                "document_number": "20.824.264/0001-77",
                "selic_account_number": "123456789"
            },
            "isin_code": "BRSTNCNTB633",
            "issue_date": "2000-07-15",
            "operation_data": {}
        }
    ],
    "limit": 100,
    "page": 0,
    "is_last_page": true
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
| :---- | :---- | :---- |
| `data` | array | Lista de operações. Cada item contém os mesmos campos da consulta individual. |
| `limit` | integer | Quantidade de itens retornados na página. |
| `page` | integer | Página atual (base 0). |
| `is_last_page` | boolean | Indica se esta é a última página de resultados. |

---

# Introdução

URL: /documentation/iaas/boletos/inicio

Nesta seção iremos explicar como funciona o ecossistema de **emissão de boletos** no contexto de uma **cessão de recebíveis para Fundos de Investimento**.  

## Estrutura de Emissão de Boletos

O processo de emissão de boletos dentro da cessão de recebíveis segue a seguinte estrutura:

1. **Cadastro do conta cobrança e geração do contrato de cessão**  
   - [5.2.4. Contrato de Cessão](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato)

2. **Registro do Boleto**  
   - O boleto é registrado no banco emissor assim que a cessão é paga.  
   - Informações obrigatórias:  
     - Identificação do cedente  
     - Identificação do sacado (pagador)  
     - Valor nominal  
     - Data de vencimento  

3. **Confirmação do Registro**  
   - A confirmação do registro do boleto é feita no proximo dia útil no processamento do retorno bancário

4. **Liquidação**  
   - Quando o boleto é pago pelo sacado, a liquidação é capturada e atualizada automaticamente.  
   - O fluxo financeiro segue para a conta principal do Fundo, compondo o caixa disponível.

5. **Baixa**  
   - Caso o pagamento do titulo seja feito por uma baixa cedente ou substituição, o boleto é baixado automaticamente

:::warning
Para que a emissão de boletos ocorra de forma **automática**, é obrigatório que o **Contrato de Cessão** contenha todas as informações de cobrança necessárias e que exista uma **conta de cobrança devidamente cadastrada** no sistema.  
:::

Para ter acesso a esses serviços, entre em contato com o time [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br), para que seja feito as devidas liberações, tanto em ambiente de Homologação (Sandbox), quanto em ambiente produtivo.

---

# Instruções de Boleto

URL: /documentation/iaas/boletos/instrucoes_boleto

Este endpoint permite enviar instruções a um boleto já registrado, como prorrogação de vencimento, atualização de juros e multa, inclusão de descontos, abatimento, baixa e solicitação de protesto.

## Request

ENDPOINT /bankslip_collection/fund_class/ FUND_CLASS_KEY /bankslip_configuration/ BANKSLIP_CONFIGURATION_KEY /bankslip/ BANKSLIP_KEY
MÉTODO PUT

### Path Parameters

| Campo                          | Tipo   | Descrição                                                              | Caracteres |
|--------------------------------|--------|------------------------------------------------------------------------|------------|
| `fund_class_key`               | uuidv4 | Chave única de identificação da classe de fundo, no formato uuid v4    | 36         |
| `bankslip_configuration_key`   | uuidv4 | Chave única de identificação da configuração do boleto, no formato uuid v4 | 36     |
| `bankslip_key`                 | uuidv4 | Chave única de identificação do boleto, no formato uuid v4             | 36         |

### Request Body Params

O campo `occurrence_type` define qual instrução será enviada ao boleto. O campo `occurrence_data` contém os dados específicos da instrução, quando aplicável.

| Campo             | Tipo   | Descrição                                                                 | Caracteres                                                              |
|-------------------|--------|---------------------------------------------------------------------------|-------------------------------------------------------------------------|
| `occurrence_type` | string | Tipo da instrução a ser enviada ao boleto.                                | **[Enumerador occurrence_type](#enumeradores-occurrence_type)**          |
| `occurrence_data` | object | Dados da instrução. Obrigatório para os tipos que exigem parâmetros adicionais. | Varia conforme o `occurrence_type`                                |

### Enumeradores occurrence_type

| Enumerador             | Descrição                                           |
|------------------------|-----------------------------------------------------|
| `due_date_extension`   | Prorrogação da data de vencimento                   |
| `delay_interest_update`| Atualização dos juros de mora                       |
| `delay_fine_update`    | Atualização da multa por atraso                     |
| `rebate`               | Aplicação de abatimento                             |
| `rebate_withdrawn`     | Cancelamento do abatimento                          |
| `discount_inclusion`   | Inclusão de descontos                               |
| `write_off`            | Baixa do boleto                                     |
| `protest_request`      | Solicitação de protesto                             |

---

### Instrução: `due_date_extension` — Prorrogação de Vencimento

Request Body

```json
{
  "occurrence_type": "due_date_extension",
  "occurrence_data": {
    "due_date": "2026-12-31"
  }
}
```

#### Objeto occurrence_data — due_date_extension

| Campo      | Tipo   | Descrição                                         | Caracteres |
|------------|--------|---------------------------------------------------|------------|
| `due_date` | string | Nova data de vencimento do boleto (formato `YYYY-MM-DD`) | 10  |

---

### Instrução: `delay_interest_update` — Atualização de Juros de Mora

Request Body

```json
{
  "occurrence_type": "delay_interest_update",
  "occurrence_data": {
    "interest": {
      "method": "pre_fixed",
      "pre_fixed": {
        "monthly_rate": 1.5,
        "calendar_base": "calendar_360"
      }
    }
  }
}
```

#### Objeto occurrence_data — delay_interest_update

| Campo      | Tipo   | Descrição                             |
|------------|--------|---------------------------------------|
| `interest` | object | Configuração dos juros de mora (ver abaixo). |

#### Objeto interest

| Campo        | Tipo   | Descrição                                                     |
|--------------|--------|---------------------------------------------------------------|
| `method`     | string | Método de cálculo dos juros. Valor: `pre_fixed`               |
| `pre_fixed`  | object | Parâmetros para o cálculo de juros pré-fixados (ver abaixo).  |

#### Objeto pre_fixed

| Campo           | Tipo   | Descrição                                                                                    |
|-----------------|--------|----------------------------------------------------------------------------------------------|
| `monthly_rate`  | number | Taxa mensal de juros (0.01 Equivale a 1% ao mes).             |
| `calendar_base` | string | Base de calendário para cálculo. **[Enumerador calendar_base](#enumeradores-calendar_base)** |

#### Enumeradores calendar_base

| Enumerador      | Descrição              |
|-----------------|------------------------|
| `calendar_360`  | Base de 360 dias       |
| `workdays`      | Dias úteis             |
| `calendar_365`  | Base de 365 dias       |

---

### Instrução: `delay_fine_update` — Atualização de Multa por Atraso

Request Body

```json
{
  "occurrence_type": "delay_fine_update",
  "occurrence_data": {
    "fine": {
      "fine_type": "percentage",
      "percentage_value": 2.0
    }
  }
}
```

#### Objeto occurrence_data — delay_fine_update

| Campo  | Tipo   | Descrição                              |
|--------|--------|----------------------------------------|
| `fine` | object | Configuração da multa por atraso (ver abaixo). |

#### Objeto fine

| Campo              | Tipo   | Descrição                                                        |
|--------------------|--------|------------------------------------------------------------------|
| `fine_type`        | string | Tipo da multa. Valor: `percentage`                               |
| `percentage_value` | number | Percentual da multa. Deve ser maior ou igual a `0`.              |

---

### Instrução: `rebate` — Abatimento

Request Body

```json
{
  "occurrence_type": "rebate",
  "occurrence_data": {
    "rebate": 50.00
  }
}
```

#### Objeto occurrence_data — rebate

| Campo    | Tipo   | Descrição                          |
|----------|--------|------------------------------------|
| `rebate` | number | Valor do abatimento a ser aplicado. |

---

### Instrução: `rebate_withdrawn` — Cancelamento de Abatimento

Esta instrução não requer `occurrence_data`.

Request Body

```json
{
  "occurrence_type": "rebate_withdrawn"
}
```

---

### Instrução: `discount_inclusion` — Inclusão de Descontos

Request Body

```json
{
  "occurrence_type": "discount_inclusion",
  "occurrence_data": {
    "discounts": [
      {
        "discount_type": "percentage",
        "discount_number": 1,
        "discount_limit_date": "2026-11-30",
        "discount_amount": 5.0
      }
    ]
  }
}
```

#### Objeto occurrence_data — discount_inclusion

| Campo       | Tipo        | Descrição                                          |
|-------------|-------------|----------------------------------------------------|
| `discounts` | array       | Lista de descontos a serem aplicados (ver abaixo). |

#### Objeto discount (item do array discounts)

| Campo                 | Tipo   | Descrição                                                                                    | Caracteres |
|-----------------------|--------|----------------------------------------------------------------------------------------------|------------|
| `discount_type`       | string | Tipo do desconto. **[Enumerador discount_type](#enumeradores-discount_type)**               | -          |
| `discount_number`     | number | Número sequencial do desconto.                                                               | -          |
| `discount_limit_date` | string | Data limite para aplicação do desconto (formato `YYYY-MM-DD`).                               | 10         |
| `discount_amount`     | number | Valor do desconto.                                                                           | -          |

#### Enumeradores discount_type

| Enumerador                                    | Descrição                                                                  |
|-----------------------------------------------|----------------------------------------------------------------------------|
| `absolute`                                    | Valor fixo                                                                 |
| `percentage`                                  | Porcentagem fixa                                                           |
| `anticipation_workdays_daily_amount`          | Valor diário de antecipação sobre dias úteis                               |
| `anticipation_workdays_daily_percentage`      | Porcentagem diária de antecipação sobre dias úteis                         |
| `anticipation_calendar_days_daily_amount`     | Valor diário de antecipação sobre dias corridos                            |
| `anticipation_calendar_days_daily_percentage` | Porcentagem diária de antecipação sobre dias corridos                      |

---

### Instrução: `write_off` — Baixa do Boleto

Esta instrução não requer `occurrence_data`.

Request Body

```json
{
  "occurrence_type": "write_off"
}
```

---

### Instrução: `protest_request` — Solicitação de Protesto

Request Body

```json
{
  "occurrence_type": "protest_request",
  "occurrence_data": {
    "protest_type": "protest"
  }
}
```

#### Objeto occurrence_data — protest_request

| Campo          | Tipo   | Descrição                                                                              |
|----------------|--------|----------------------------------------------------------------------------------------|
| `protest_type` | string | Tipo do protesto. **[Enumerador protest_type](#enumeradores-protest_type)**             |

#### Enumeradores protest_type

| Enumerador           | Descrição                    |
|----------------------|------------------------------|
| `protest`            | Protesto padrão              |
| `bankruptcy_protest` | Protesto por falência         |

---

## Response

STATUS 201

Response Body

```json title='Response Body'
{
  "bankslip_key": "c9eb109c-800f-4cf5-b209-2119c9d77a72",
  "external_participant_control_number": "801KFZFNB4UZ34MLGJG2X9WNG",
  "bankslip_configuration": {
    "bankslip_configuration_key": "1b382eb7-7006-4389-975b-afa76b0ad7b4",
    "bankslip_profile": {
      "bankslip_profile_key": "5910d4a3-f5df-432a-902f-849a1a77cd86",
      "bankslip_profile_code": "329-09-0001-4993010",
      "bankslip_profile_number": 1,
      "bankslip_provider": "qi_scd",
      "additional_information": {
        "external_beneficiary_key": "2666e7a3-0bd7-46fc-8f6b-725f2ef9b13f"
      },
      "internal_account_key": "6b5335ed-1380-4348-9520-8998ca6e388b",
      "fund_class": {
        "fund_class_key": "7f03069e-1854-4cee-8e59-a6a548976015",
        "document_number": "51.620.927/0001-65",
        "name": "Sample Fund Class",
        "manager": {
          "name": "Sample Manager",
          "manager_key": "5cb734e9-c33b-4e7e-bb40-f894aa82b153",
          "document_number": "51.620.927/0001-65"
        }
      }
    }
  },
  "due_date": "2026-12-31",
  "face_value": 629.33,
  "status": "registered",
  "participant_control_number": "801KFZFNB4UZ34MLGJG2X9WNG",
  "borrower": {
    "document_number": "755.510.684-12",
    "name": "Tomador Exemplo",
    "person_type": "natural_person",
    "address": {
      "postal_code": "05425-020"
    }
  },
  "assignor": {
    "name": "Cedente LTDA",
    "document_number": "37.341.966/0001-00",
    "person_type": "legal_person"
  },
  "bankslip_type": "simple",
  "delay": null,
  "our_number": "00000012345",
  "our_number_digit": "6",
  "digitable_line": "32991.23456 78901.234567 89012.345678 9 00010000062933",
  "barcode": "32999000010000062933123456789012345678901234",
  "occurrences": [
    {
      "occurrence_key": "e9898e50-cd2b-492f-9201-7e5c5f231853",
      "status": "pending_submission",
      "type": "due_date_extension",
      "occurrence_data": {
        "due_date": "2026-12-31"
      }
    }
  ],
  "settlement_instructions": [
    {
      "settlement_instruction_key": "fe419363-bf04-4b3a-90bd-185618baa720",
      "status": "pending_bankslip_payment",
      "asset_type": "duplicata_mercantil",
      "asset_key": "22fc5c95-3622-48ad-b26a-99f8d0499e69",
      "external_id": "758638e4-6fe6-4b69-8799-30728ca16a22",
      "issue_date": "2025-01-17",
      "maturity_date": "2026-12-31",
      "face_value": 629.33,
      "order_number": "49761-1"
    }
  ]
}
```

### Bankslip

| Campo                                 | Tipo   | Descrição                                                              |
|---------------------------------------|--------|------------------------------------------------------------------------|
| `bankslip_key`                        | string | Identificador único do boleto.                                         |
| `external_participant_control_number` | string | Número de controle externo do participante.                            |
| `bankslip_configuration`              | object | Configuração do boleto (ver abaixo).                                   |
| `due_date`                            | date   | Data de vencimento do boleto.                                          |
| `face_value`                          | number | Valor nominal do boleto.                                               |
| `status`                              | string | Status atual do boleto.                                                |
| `participant_control_number`          | string | Número de controle interno do participante.                            |
| `borrower`                            | object | Objeto que representa o tomador (sacado).                              |
| `assignor`                            | object | Objeto que representa o cedente do recebível.                          |
| `bankslip_type`                       | string | Tipo do boleto.                                                        |
| `delay`                               | object | Dados de mora do boleto, quando aplicável.                             |
| `order_number`                        | string | Número do pedido, quando disponível.                                   |
| `our_number`                          | string | Nosso número, quando disponível.                                       |
| `our_number_digit`                    | string | Dígito verificador do nosso número, quando disponível.                 |
| `digitable_line`                      | string | Linha digitável do boleto, quando disponível.                          |
| `barcode`                             | string | Código de barras do boleto, quando disponível.                         |
| `occurrences`                         | array  | Lista de ocorrências relacionadas ao boleto (cada item é um objeto).   |
| `settlement_instructions`             | array  | Lista de instruções de liquidação relacionadas ao boleto.              |

### Bankslip Configuration

| Campo                        | Tipo   | Descrição                        |
|------------------------------|--------|----------------------------------|
| `bankslip_configuration_key` | string | Chave de configuração do boleto. |
| `bankslip_profile`           | object | Perfil de boleto associado.      |

### Bankslip Profile

| Campo                      | Tipo   | Descrição                                                    |
|----------------------------|--------|--------------------------------------------------------------|
| `bankslip_profile_key`     | string | Identificador do perfil de boleto.                           |
| `bankslip_profile_code`    | string | Código do perfil.                                            |
| `bankslip_profile_number`  | number | Número do perfil.                                            |
| `bankslip_provider`        | string | Provedor do boleto.                                          |
| `additional_information`   | object | Informações adicionais do perfil.                            |
| `internal_account_key`     | string | Identificador da conta interna associada.                    |
| `fund_class`               | object | Objeto representando a classe de fundo (ver abaixo).         |

### Fund Class

| Campo             | Tipo   | Descrição                                       | Caracteres |
|-------------------|--------|-------------------------------------------------|------------|
| `fund_class_key`  | string | Chave única de identificação da classe de fundo | 36         |
| `document_number` | string | CNPJ da classe de fundo                         | -          |
| `name`            | string | Nome da classe de fundo                         | até 255    |

### Borrower

| Campo             | Tipo   | Descrição                      |
|-------------------|--------|--------------------------------|
| `name`            | string | Nome do tomador.               |
| `document_number` | string | Documento (CPF/CNPJ).          |
| `person_type`     | string | Tipo de pessoa.                |
| `address`         | object | Endereço do tomador.           |

### Assignor

| Campo             | Tipo   | Descrição             |
|-------------------|--------|-----------------------|
| `name`            | string | Nome do cedente.      |
| `document_number` | string | Documento (CNPJ).     |
| `person_type`     | string | Tipo de pessoa.       |

### Occurrences

Cada item do array é um objeto com os seguintes campos:

| Campo             | Tipo   | Descrição                       |
|-------------------|--------|---------------------------------|
| `occurrence_key`  | string | Identificador da ocorrência.    |
| `status`          | string | Status da ocorrência.           |
| `type`            | string | Tipo da ocorrência.             |
| `occurrence_data` | object | Dados adicionais da ocorrência. |

### Settlement Instructions

Cada item do array é um objeto com os seguintes campos:

| Campo                        | Tipo   | Descrição                                            |
|------------------------------|--------|------------------------------------------------------|
| `settlement_instruction_key` | string | Identificador da instrução de liquidação.            |
| `status`                     | string | Status da instrução de liquidação.                   |
| `asset_type`                 | string | Tipo do ativo.                                       |
| `asset_key`                  | string | Chave única do ativo no sistema.                     |
| `external_id`                | string | Identificador externo do cliente.                    |
| `issue_date`                 | date   | Data de emissão.                                     |
| `maturity_date`              | date   | Data de vencimento.                                  |
| `face_value`                 | number | Valor de face do ativo.                              |
| `order_number`               | string | Número do contrato.                                  |

---

## Error Response

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`    | Descrição (eng)<br/>`description`                            | Descrição (pt-br)<br/>`translation`                              |
|--------------------------|----------------------|-----------------------|--------------------------------------------------------------|------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request           | Schema Error                                                 | Schema Inválido                                                  |
| 404                      | BSC000009            | Bankslip not Found    | Bankslip with key `{bankslip_key}` was not found.            | Boleto com chave `{bankslip_key}` não foi encontrado.            |

---

# Recuperação de Arquivos CNAB

URL: /documentation/iaas/boletos/recuperar_arquivo_retorno

---

## Listar arquivos CNAB

Retorna uma lista paginada de arquivos CNAB (arquivos de remessa e retorno trocados com o banco) pertencentes a um perfil de boleto de uma classe de fundo.

### Request

ENDPOINT /bankslip_collection/fund_class/FUND_CLASS_KEY/bankslip_profile/BANKSLIP_PROFILE_KEY/cnab_files
MÉTODO GET

### Path Params

| Parâmetro              | Descrição                                                                                                                   |
|------------------------|-----------------------------------------------------------------------------------------------------------------------------|
| `fund_class_key`       | Chave da classe de fundo. Retorna `404` (`NotFoundFundClass`) caso não exista.                                                |
| `bankslip_profile_key` | Chave do perfil de boleto, que deve pertencer à classe de fundo. Retorna `404` (`NotFoundBankslipConfiguration`) caso não seja encontrado. |

### Query Params

Todos os parâmetros são opcionais.

| Parâmetro      | Tipo   | Descrição                                                                     |
|----------------|--------|-------------------------------------------------------------------------------|
| `initial_date` | date   | Filtra arquivos com `cnab_date` maior ou igual à data informada (YYYY-MM-DD).  |
| `final_date`   | date   | Filtra arquivos com `cnab_date` menor ou igual à data informada (YYYY-MM-DD).  |
| `cnab_type`    | string | Filtra pelo tipo do arquivo (ver **[Tipo de CNAB](#tipo-de-cnab)**).           |
| `limit`        | int    | Valor entre 0 e 20 com o número de itens por página. Padrão: `10`.             |
| `page`         | int    | Número da página (começando por zero). Padrão: `0`.                            |

Quando `is_last_page` for `false`, solicite a próxima `page` para recuperar os demais resultados.

### Response

Response Body

```json title='Response Body'
{
    "data": [
        {
            "cnab_file_key": "79f21d3e-ed99-413c-8e05-39cf84fbab7c",
            "bankslip_profile": {
                "bankslip_profile_key": "a1d7f09b-cb77-48da-a23d-b83d97d4b46b",
                "bankslip_profile_code": "329-09-0001-0000000",
                "bankslip_profile_number": 9,
                "bankslip_provider": "qi_scd",
                "additional_information": {
                    "requester_profile_key": "30f72181-042c-4aae-9be7-b2794916416f"
                },
                "internal_account_key": "18809219-17d9-4845-a830-51e7f2beaf28",
                "fund_class": {
                    "fund_class_key": "92c63a0f-25d6-45cb-90a2-6026c0ce2ef9",
                    "document_number": "00.000.000/0001-01",
                    "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS",
                    "manager": {
                        "name": "GESTÃO DE RECURSOS",
                        "manager_key": "7a5ff2f5-f127-451c-98d8-001826c35c3c",
                        "document_number": "00.100.100/0001-00"
                    }
                }
            },
            "cnab_date": "2025-07-30",
            "type": "return",
            "status": "completed",
            "download_filename": "cnab-retorno-2025-07-30-79f21d3e.ret",
            "url": "https://s3.amazonaws.com/...",
            "external_cnab_file_key": "e8b5e962-eb5f-4b9d-8d2b-70cd6d3d5252",
            "number_of_occurrences": 6
        },
        {
            "cnab_file_key": "ff7aaa47-a901-4f66-98d7-46f76ca4fa16",
            "bankslip_profile": {
                "bankslip_profile_key": "e0771a02-4f3e-4162-a468-a872fc6975e4",
                "bankslip_profile_code": "329-09-0001-0000000",
                "bankslip_profile_number": 9,
                "bankslip_provider": "qi_scd",
                "additional_information": {
                    "requester_profile_key": "cdec985f-e629-44ce-8511-a323f38bd63e"
                },
                "internal_account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e",
                "fund_class": {
                    "fund_class_key": "92c63a0f-25d6-45cb-90a2-6026c0ce2ef9",
                    "document_number": "00.000.000/0001-01",
                    "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS",
                    "manager": {
                        "name": "GESTÃO DE RECURSOS",
                        "manager_key": "7a5ff2f5-f127-451c-98d8-001826c35c3c",
                        "document_number": "00.100.100/0001-00"
                    }
                }
            },
            "cnab_date": "2025-07-30",
            "type": "external_return",
            "status": "completed",
            "download_filename": "cnab-retorno-2025-07-30-ff7aaa47.ret",
            "url": "https://s3.amazonaws.com/...",
            "external_cnab_file_key": "d3b1f7c4-9e2a-4f6b-8c1d-5a7e9b3f2c8e",
            "number_of_occurrences": 3,
            "bankslip_expenses": [
                {
                    "bankslip_expense_key": "4d727b05-00df-454e-93e3-160ec9ee596c",
                    "type": "fee_or_costs.payment",
                    "number_of_expenses": 3,
                    "total_value": 2.25,
                    "status": "completed"
                }
            ]
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true
}
```

### Objeto Paginado

| Campo          | Tipo    | Descrição                                                |
|----------------|---------|----------------------------------------------------------|
| `data`         | array   | Lista de objetos de **[CNAB File](#cnab-file)**          |
| `limit`        | int     | Limite de objetos recuperados por página                 |
| `page`         | int     | Número da página recuperada                              |
| `is_last_page` | boolean | Informação que indica se a página recuperada é a última  |

### CNAB File

| Campo                    | Tipo   | Descrição                                                                                                                     |
|--------------------------|--------|-------------------------------------------------------------------------------------------------------------------------------|
| `cnab_file_key`          | string | Identificador único do arquivo CNAB.                                                                                            |
| `bankslip_profile`       | object | Perfil de boleto associado (ver **[Bankslip Profile](/documentation/iaas/boletos/recuperar_boletos#bankslip-profile)**).                                  |
| `cnab_date`              | date   | Data do arquivo CNAB.                                                                                                           |
| `type`                   | string | Tipo do arquivo (ver **[Tipo de CNAB](#tipo-de-cnab)**).                                                                        |
| `status`                 | string | Status do arquivo (ver **[Status do CNAB](#status-do-cnab)**).                                                                  |
| `download_filename`      | string | Nome com o qual o arquivo é baixado.                                                                                            |
| `url`                    | string | URL pré-assinada para download do arquivo, válida por **1 hora**. Omitida caso não seja possível gerá-la.                       |
| `external_cnab_file_key` | string | Identificador do arquivo CNAB externo. Presente apenas quando o arquivo possui esse valor.                                      |
| `header`                 | string | Header do arquivo. Presente apenas quando o arquivo possui esse valor.                                                          |
| `trailer`                | string | Trailer do arquivo. Presente apenas quando o arquivo possui esse valor.                                                         |
| `number_of_occurrences`  | int    | Número de ocorrências do arquivo. Presente apenas quando o arquivo possui esse valor.                                           |
| `expectation`            | object | Dados de expectativa do arquivo. Presente apenas quando o arquivo possui esse valor.                                            |
| `bankslip_expenses`      | array  | Lista de objetos de **[Bankslip Expense](#bankslip-expense)**. Presente apenas quando o arquivo possui despesas associadas.     |

### Bankslip Expense

| Campo                  | Tipo   | Descrição                              |
|------------------------|--------|-----------------------------------------|
| `bankslip_expense_key` | string | Identificador único da despesa.         |
| `type`                 | string | Tipo da despesa.                        |
| `number_of_expenses`   | int    | Quantidade de despesas agrupadas.       |
| `total_value`          | number | Valor total das despesas.               |
| `status`               | string | Status da despesa.                      |

## Tipo de CNAB

| Enumerador           | Descrição               |
|----------------------|-------------------------|
| `return`             | Arquivo Retorno         |
| `external_return`    | Arquivo Retorno Externo |
| `remittance`         | Remessa                 |
| `external_remittance`| Remessa Externa         |

## Status do CNAB

| Enumerador           | Descrição                 |
|----------------------|---------------------------|
| `created`            | Criado                    |
| `pending_processing` | Processamento pendente    |
| `completed`          | Concluído                 |
| `canceled`           | Cancelado                 |

---

# Recuperação de Boleto e Segunda via

URL: /documentation/iaas/boletos/recuperar_boleto

---

## Lista de Boletos

### Request

ENDPOINT /bankslip_collection/fund_class/FUND_CLASS_KEY/bankslip_profile/BANKSLIP_PROFILE_KEY/bankslip/BANKSLIP_KEY
MÉTODO GET

### Response 
Response Body

```json title='Response Body'
{
        
    "bankslip_key": "c9eb109c-800f-4cf5-b209-2119c9d77a72",
    "external_participant_control_number": "801KFZFNB4UZ34MLGJG2X9WNG",
    "asset_type": "duplicata_mercantil",
    "bankslip_configuration": {
        "bankslip_configuration_key": "1b382eb7-7006-4389-975b-afa76b0ad7b4",
        "bankslip_profile": {
            "bankslip_profile_key": "5910d4a3-f5df-432a-902f-849a1a77cd86",
            "bankslip_profile_code": "329-09-0001-4993010",
            "bankslip_profile_number": 1,
            "bankslip_provider": "qi_scd",
            "additional_information": {
                "external_beneficiary_key": "2666e7a3-0bd7-46fc-8f6b-725f2ef9b13f"
            },
            "internal_account_key": "6b5335ed-1380-4348-9520-8998ca6e388b",
            "fund_class": {
                "fund_class_key": "7f03069e-1854-4cee-8e59-a6a548976015",
                "document_number": "51.620.927/0001-65",
                "name": "Sample_Name",
                "manager": {
                    "name": "Sample name",
                    "manager_key": "5cb734e9-c33b-4e7e-bb40-f894aa82b153",
                    "document_number": "51.620.927/0001-65"
                }
            }
        }
    },
    "due_date": "2026-04-21",
    "face_value": 629.33,
    "status": "pending_registration",
    "participant_control_number": "801KFZFNB4UZ34MLGJG2X9WNG",
    "borrower": {
        "document_number": "755.510.684-12",
        "name": "Tomador",
        "person_type": "legal_person",
        "address": {
            "postal_code": "05425-020"
        }
    },
    "assignor": {
        "name": "Assignor LTDA",
        "document_number": "37.341.966/0001-00",
        "person_type": "legal_person"
    },
    "occurrences": [
        {
            "occurrence_key": "e9898e50-cd2b-492f-9201-7e5c5f231853",
            "status": "pending_submission",
            "type": "registration",
            "occurrence_data": null
        }
    ],
    "settlement_instructions": [
        {
            "settlement_instruction_key": "fe419363-bf04-4b3a-90bd-185618baa720",
            "status": "pending_bankslip_payment",
            "asset_type": "duplicata_mercantil",
            "asset_key": "22fc5c95-3622-48ad-b26a-99f8d0499e69",
            "external_id": "758638e4-6fe6-4b69-8799-30728ca16a22",
            "issue_date": "2025-01-17",
            "maturity_date": "2026-09-17",
            "face_value": 629.33,
            "order_number": "49761-1"
        }
    ],
    "bankslip_url": "https://bankslip-proxys-bucket-production.s3.amazonaws.com/"

        
}
```

### Bankslip

| Campo                                 | Tipo     | Descrição                                                            |
|---------------------------------------|----------|----------------------------------------------------------------------|
| `bankslip_key`                        | string   | Identificador único do boleto.                                       |
| `external_participant_control_number` | string   | Número de controle externo do participante.                          |
| `asset_type`                          | string   | Tipo de ativo atrelado.                                              |
| `due_date`                            | date     | Data de vencimento do boleto.                                        |
| `face_value`                          | number   | Valor nominal do boleto.                                             |
| `status`                              | string   | Status atual do boleto.                                              |
| `participant_control_number`          | string   | Número de controle interno do participante.                          |
| `bankslip_configuration`              | object   | Objeto que contém a configuração do boleto (ver abaixo).             |
| `borrower`                            | object   | Objeto que representa o tomador (sacado).                            |
| `assignor`                            | object   | Objeto que representa o cedente do recebível.                        |
| `occurrences`                         | array    | Lista de ocorrências relacionadas ao boleto (cada item é um objeto). |
| `settlement_instructions`             | array    | Lista de instruções de liquidação relacionadas ao boleto.            |
| `bankslip_url`                        | array    | Link para recuperação de segunda via.                                |

### Bankslip Configuration

| Campo                                | Tipo     | Descrição                        |
|--------------------------------------|----------|----------------------------------|
| `bankslip_configuration_key`         | string   | Chave de configuração do boleto. |
| `bankslip_profile`                   | object   | Perfil de boleto associado.      |

---

### Bankslip Profile

| Campo                                | Tipo     | Descrição |
|--------------------------------------|----------|-------------------------------|
| `bankslip_profile_key`               | string   | Identificador do perfil de boleto. |
| `bankslip_profile_code`              | string   | Código do perfil. |
| `bankslip_profile_number`            | number   | Número do perfil. |
| `bankslip_provider`                  | string   | Provedor do boleto. |
| `additional_information`             | object   | Informações adicionais (ver abaixo). |
| `internal_account_key`               | string   | Identificador da conta interna associada. |
| `fund_class`                         | object   | Objeto representando o fundo de investimento (ver abaixo). |

### Fund Class

| Campo                         | Tipo     | Descrição                                         | Caracteres |
|-------------------------------|----------|---------------------------------------------------|------------|
| `name`                        | string   | Nome da classe de fundo                           | até 255    |
| `fund_class_key`              | string   | Chave única de identificação da classe de fundo   | 36         |
| `document_number`             | string   | CNPJ da classe de fundo                           | -          |

### Borrower 

| Campo                                | Tipo     | Descrição                     |
|--------------------------------------|----------|-------------------------------|
|  `name`                              | string   | Nome do tomador. |
|  `document_number`                   | string   | Documento (CPF/CNPJ). |
|  `person_type`                       | string   | Tipo de pessoa. |
|  `address`                           | object   | Endereço do tomador (ver abaixo). |

### Address

| Campo                                | Tipo     | Descrição                     |
|--------------------------------------|----------|-------------------------------|
| `street`                             | string   | Logradouro do endereço. |
| `number`                             | string   | Número do endereço. |
| `neighborhood`                       | string   | Bairro. |
| `city`                               | string   | Cidade. |
| `postal_code`                        | string   | CEP. |
| `uf`                                 | string   | Unidade federativa (sigla do estado). |
| `country`                            | string   | País no formato ISO Alpha-3. |

---

## Assignor (Cedente)

| Campo                                | Tipo     | Descrição         |
|--------------------------------------|----------|-------------------|
| `name`                               | string   | Nome do cedente.  |
| `document_number`                    | string   | Documento (CNPJ). |
| `person_type`                        | string   | Tipo de pessoa.   |

---

## Occurrences

Cada item do array é um objeto com os seguintes campos:

| Campo                                | Tipo     | Descrição                       |
|--------------------------------------|----------|---------------------------------|
| `occurrence_key`                     | string   | Identificador da ocorrência.    |
| `status`                             | string   | Status da ocorrência.           |
| `type`                               | string   | Tipo da ocorrência.             |
| `occurrence_data`                    | object   | Dados adicionais da ocorrência. |

## Settlement Instructions

Cada item do array é um objeto com os seguintes campos:

| Campo                         | Tipo     | Descrição                                            |
|-------------------------------|----------|------------------------------------------------------|
| `settlement_instruction_key`  | string   | Identificador da instrução de liquidação.            |
| `status`                      | string   | Status da instrução de liquidação.                   |
| `asset_type`                  | string   | Tipo do ativo.                                       |
| `asset_key`                   | string   | Chave única do ativo no sistema.                     |
| `external_id`                 | string   | Identifica externo do cliente (utilizado na cessão). |
| `issue_date`                  | date     | Data de emissão.                                     |
| `maturity_date`               | date     | Data de vencimento.                                  |
| `face_value`                  | number   | Valor de face do ativo.                              |
| `order_number`                | string   | Número do contrato.                                  |
| `installment_number`          | number   | Número da parcela do ativo.                          |

---

# Recuperação de Boletos

URL: /documentation/iaas/boletos/recuperar_boletos

---

## Lista de Boletos

### Request

ENDPOINT /bankslip_collection/fund_class/FUND_CLASS_KEY/bankslip_profile/BANKSLIP_PROFILE_KEY/bankslips
MÉTODO GET

### Query Params
| Parâmetro                    | Descrição                                                  |
|------------------------------|------------------------------------------------------------|
| `limit`                      | Valor entre 0 e 100 com o número de itens por página.      |
| `page`                       | Número da pagina (começando por zero).                     |
| `borrower_document_number`   | Número de documento do tomador (somente números).          |
| `assignor_document_number`   | Número de documento do cedente (somente números).          |
| `participant_control_number` | Número de controle do participante.                        |
| `order_number`               | Número do contrato.                                        |
| `our_number`                 | Nosso número do boleto no banco.                           |

### Response 
Response Body

```json title='Response Body'
{
    "data": [
        {
            "bankslip_key": "c9eb109c-800f-4cf5-b209-2119c9d77a72",
            "external_participant_control_number": "801KFZFNB4UZ34MLGJG2X9WNG",
            "asset_type": "duplicata_mercantil",
            "bankslip_configuration": {
                "bankslip_configuration_key": "1b382eb7-7006-4389-975b-afa76b0ad7b4",
                "bankslip_profile": {
                    "bankslip_profile_key": "5910d4a3-f5df-432a-902f-849a1a77cd86",
                    "bankslip_profile_code": "329-09-0001-4993010",
                    "bankslip_profile_number": 1,
                    "bankslip_provider": "qi_scd",
                    "additional_information": {
                        "external_beneficiary_key": "2666e7a3-0bd7-46fc-8f6b-725f2ef9b13f"
                    },
                    "internal_account_key": "6b5335ed-1380-4348-9520-8998ca6e388b",
                    "fund_class": {
                        "fund_class_key": "7f03069e-1854-4cee-8e59-a6a548976015",
                        "document_number": "51.620.927/0001-65",
                        "name": "Sample_Name",
                        "manager": {
                            "name": "Sample name",
                            "manager_key": "5cb734e9-c33b-4e7e-bb40-f894aa82b153",
                            "document_number": "51.620.927/0001-65"
                        }
                    }
                }
            },
            "due_date": "2024-02-17",
            "face_value": 629.33,
            "status": "pending_registration",
            "participant_control_number": "801KFZFNB4UZ34MLGJG2X9WNG",
            "borrower": {
                "document_number": "755.510.684-12",
                "name": "Tomador",
                "person_type": "legal_person",
                "address": {
                    "postal_code": "05425-020"
                }
            },
            "assignor": {
                "name": "Assignor LTDA",
                "document_number": "37.341.966/0001-00",
                "person_type": "legal_person"
            },
            "occurrences": [
                {
                    "occurrence_key": "e9898e50-cd2b-492f-9201-7e5c5f231853",
                    "status": "pending_submission",
                    "type": "registration",
                    "occurrence_data": null
                }
            ],
            "settlement_instructions": [
                {
                    "settlement_instruction_key": "fe419363-bf04-4b3a-90bd-185618baa720",
                    "status": "pending_bankslip_payment",
                    "asset_type": "duplicata_mercantil",
                    "asset_key": "22fc5c95-3622-48ad-b26a-99f8d0499e69",
                    "external_id": "758638e4-6fe6-4b69-8799-30728ca16a22",
                    "issue_date": "2025-01-17",
                    "maturity_date": "2026-09-17",
                    "face_value": 629.33,
                    "order_number": "49761-1"
                }
            ],
        },
        {
            "bankslip_key": "4584e60c-752f-479d-831a-50f09c2c7de2",
            "external_participant_control_number": "TBFBDWKTEWJ7UTR6CPL4BAE4P",
            "asset_type": "duplicata_mercantil",
            "bankslip_configuration": {
                "bankslip_configuration_key": "1b382eb7-7006-4389-975b-afa76b0ad7b4",
                "bankslip_profile": {
                    "bankslip_profile_key": "5910d4a3-f5df-432a-902f-849a1a77cd86",
                    "bankslip_profile_code": "329-09-0001-4993010",
                    "bankslip_profile_number": 1,
                    "bankslip_provider": "qi_scd",
                    "additional_information": {
                        "external_beneficiary_key": "2666e7a3-0bd7-46fc-8f6b-725f2ef9b13f"
                    },
                    "internal_account_key": "6b5335ed-1380-4348-9520-8998ca6e388b",
                    "fund_class": {
                        "fund_class_key": "7f03069e-1854-4cee-8e59-a6a548976015",
                        "document_number": "51.620.927/0001-65",
                        "name": "Sample_Name",
                        "manager": {
                            "name": "Sample name",
                            "manager_key": "5cb734e9-c33b-4e7e-bb40-f894aa82b153",
                            "document_number": "51.620.927/0001-65"
                        }
                    }
                }
            },
            "due_date": "2024-02-17",
            "face_value": 629.33,
            "status": "pending_registration",
            "participant_control_number": "TBFBDWKTEWJ7UTR6CPL4BAE4P",
            "borrower": {
                "document_number": "784.508.035-78",
                "name": "mgkstsdibe",
                "person_type": "legal_person",
                "address": {
                    "postal_code": "05425-020"
                }
            },
            "assignor": {
                "name": "Assignor LTDA",
                "document_number": "37.341.966/0001-00",
                "person_type": "legal_person"
            },
            "occurrences": [
                {
                    "occurrence_key": "07ad7fce-fec6-40ac-be22-1ffd031f36bc",
                    "status": "pending_submission",
                    "type": "registration",
                    "occurrence_data": null
                }
            ],
            "settlement_instructions": [
                {
                    "settlement_instruction_key": "fe419363-bf04-4b3a-90bd-185618baa720",
                    "status": "pending_bankslip_payment",
                    "asset_type": "duplicata_mercantil",
                    "asset_key": "22fc5c95-3622-48ad-b26a-99f8d0499e69",
                    "external_id": "758638e4-6fe6-4b69-8799-30728ca16a22",
                    "issue_date": "2025-01-17",
                    "maturity_date": "2026-09-17",
                    "face_value": 629.33,
                    "order_number": "49761-1"
                }
            ],
        }
    ],
    "limit": 15,
    "page": 0,
    "is_last_page": true
}
```

### Objeto Paginado

| Campo         | Tipo     | Descrição                                                      |
|---------------|----------|----------------------------------------------------------------|
| `data`        | array    | Lista de objetos de **[Bankslip](#bankslip)**                  |
| `limit`       | int      | Limite de objetos recuperados por página                       |
| `page`        | int      | Número da página recuperada                                    |
| `is_last_page`| boolean  | Informação que indica se a página recuperada é a última        |

### Bankslip

| Campo                                 | Tipo     | Descrição                                                            |
|---------------------------------------|----------|----------------------------------------------------------------------|
| `bankslip_key`                        | string   | Identificador único do boleto.                                       |
| `external_participant_control_number` | string   | Número de controle externo do participante.                          |
| `asset_type`                          | string   | Tipo de ativo atrelado.                                              |
| `due_date`                            | date     | Data de vencimento do boleto.                                        |
| `face_value`                          | number   | Valor nominal do boleto.                                             |
| `status`                              | string   | Status atual do boleto.                                              |
| `participant_control_number`          | string   | Número de controle interno do participante.                          |
| `bankslip_configuration`              | object   | Objeto que contém a configuração do boleto (ver abaixo).             |
| `borrower`                            | object   | Objeto que representa o tomador (sacado).                            |
| `assignor`                            | object   | Objeto que representa o cedente do recebível.                        |
| `occurrences`                         | array    | Lista de ocorrências relacionadas ao boleto (cada item é um objeto). |
| `settlement_instructions`             | array    | Lista de instruções de liquidação relacionadas ao boleto.            |

### Bankslip Configuration

| Campo                                | Tipo     | Descrição                        |
|--------------------------------------|----------|----------------------------------|
| `bankslip_configuration_key`         | string   | Chave de configuração do boleto. |
| `bankslip_profile`                   | object   | Perfil de boleto associado.      |

---

### Bankslip Profile

| Campo                                | Tipo     | Descrição |
|--------------------------------------|----------|-------------------------------|
| `bankslip_profile_key`               | string   | Identificador do perfil de boleto. |
| `bankslip_profile_code`              | string   | Código do perfil. |
| `bankslip_profile_number`            | number   | Número do perfil. |
| `bankslip_provider`                  | string   | Provedor do boleto. |
| `additional_information`             | object   | Informações adicionais (ver abaixo). |
| `internal_account_key`               | string   | Identificador da conta interna associada. |
| `fund_class`                         | object   | Objeto representando o fundo de investimento (ver abaixo). |

### Fund Class

| Campo                         | Tipo     | Descrição                                         | Caracteres |
|-------------------------------|----------|---------------------------------------------------|------------|
| `name`                        | string   | Nome da classe de fundo                           | até 255    |
| `fund_class_key`              | string   | Chave única de identificação da classe de fundo   | 36         |
| `document_number`             | string   | CNPJ da classe de fundo                           | -          |

### Borrower 

| Campo                                | Tipo     | Descrição                     |
|--------------------------------------|----------|-------------------------------|
|  `name`                              | string   | Nome do tomador. |
|  `document_number`                   | string   | Documento (CPF/CNPJ). |
|  `person_type`                       | string   | Tipo de pessoa. |
|  `address`                           | object   | Endereço do tomador (ver abaixo). |

### Address

| Campo                                | Tipo     | Descrição                     |
|--------------------------------------|----------|-------------------------------|
| `street`                             | string   | Logradouro do endereço. |
| `number`                             | string   | Número do endereço. |
| `neighborhood`                       | string   | Bairro. |
| `city`                               | string   | Cidade. |
| `postal_code`                        | string   | CEP. |
| `uf`                                 | string   | Unidade federativa (sigla do estado). |
| `country`                            | string   | País no formato ISO Alpha-3. |

---

## Assignor (Cedente)

| Campo                                | Tipo     | Descrição         |
|--------------------------------------|----------|-------------------|
| `name`                               | string   | Nome do cedente.  |
| `document_number`                    | string   | Documento (CNPJ). |
| `person_type`                        | string   | Tipo de pessoa.   |

---

## Occurrences

Cada item do array é um objeto com os seguintes campos:

| Campo                                | Tipo     | Descrição                       |
|--------------------------------------|----------|---------------------------------|
| `occurrence_key`                     | string   | Identificador da ocorrência.    |
| `status`                             | string   | Status da ocorrência.           |
| `type`                               | string   | Tipo da ocorrência.             |
| `occurrence_data`                    | object   | Dados adicionais da ocorrência. |

## Settlement Instructions

Cada item do array é um objeto com os seguintes campos:

| Campo                         | Tipo     | Descrição                                            |
|-------------------------------|----------|------------------------------------------------------|
| `settlement_instruction_key`  | string   | Identificador da instrução de liquidação.            |
| `status`                      | string   | Status da instrução de liquidação.                   |
| `asset_type`                  | string   | Tipo do ativo.                                       |
| `asset_key`                   | string   | Chave única do ativo no sistema.                     |
| `external_id`                 | string   | Identifica externo do cliente (utilizado na cessão). |
| `issue_date`                  | date     | Data de emissão.                                     |
| `maturity_date`               | date     | Data de vencimento.                                  |
| `face_value`                  | number   | Valor de face do ativo.                              |
| `order_number`                | string   | Número do contrato.                                  |
| `installment_number`          | number   | Número da parcela do ativo.                          |

---

# Recuperação de Carteiras de Cobrança

URL: /documentation/iaas/boletos/recuperar_carteiras_cobranca

---

## Listar carteiras de cobrança

Retorna uma lista paginada das carteiras de cobrança (bankslip profiles) de uma classe de fundo. O acesso é permitido apenas ao gestor responsável pela classe de fundo.

### Request

ENDPOINT /bankslip_collection/fund_class/FUND_CLASS_KEY/bankslip_profiles
MÉTODO GET

### Path Params

| Parâmetro        | Descrição                                                                      |
|------------------|----------------------------------------------------------------------------------|
| `fund_class_key` | Chave da classe de fundo. Retorna `404` (`NotFoundFundClass`) caso não exista.    |

### Query Params

Todos os parâmetros são opcionais.

| Parâmetro | Tipo | Descrição                                                            |
|-----------|------|-----------------------------------------------------------------------|
| `limit`   | int  | Valor entre 0 e 50 com o número de itens por página. Padrão: `10`.    |
| `page`    | int  | Número da página (começando por zero). Padrão: `0`.                   |

Quando `is_last_page` for `false`, solicite a próxima `page` para recuperar os demais resultados.

### Response

Response Body

```json title='Response Body'
{
    "data": [
        {
            "bankslip_profile_key": "a1d7f09b-cb77-48da-a23d-b83d97d4b46b",
            "bankslip_profile_code": "329-09-0001-0000000",
            "bankslip_profile_number": 9,
            "bankslip_provider": "qi_scd",
            "additional_information": {
                "requester_profile_key": "30f72181-042c-4aae-9be7-b2794916416f"
            },
            "internal_account_key": "18809219-17d9-4845-a830-51e7f2beaf28",
            "fund_class": {
                "fund_class_key": "92c63a0f-25d6-45cb-90a2-6026c0ce2ef9",
                "document_number": "00.000.000/0001-01",
                "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS",
                "manager": {
                    "name": "GESTÃO DE RECURSOS",
                    "manager_key": "7a5ff2f5-f127-451c-98d8-001826c35c3c",
                    "document_number": "00.100.100/0001-00"
                }
            },
            "total_value": 12345.67,
            "total_overdue_value": 890.12
        },
        {
            "bankslip_profile_key": "e0771a02-4f3e-4162-a468-a872fc6975e4",
            "bankslip_profile_code": "329-09-0001-0000001",
            "bankslip_profile_number": 10,
            "bankslip_provider": "qi_scd",
            "additional_information": {
                "requester_profile_key": "cdec985f-e629-44ce-8511-a323f38bd63e"
            },
            "internal_account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e",
            "fund_class": {
                "fund_class_key": "92c63a0f-25d6-45cb-90a2-6026c0ce2ef9",
                "document_number": "00.000.000/0001-01",
                "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS",
                "manager": {
                    "name": "GESTÃO DE RECURSOS",
                    "manager_key": "7a5ff2f5-f127-451c-98d8-001826c35c3c",
                    "document_number": "00.100.100/0001-00"
                }
            }
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true,
    "elapsed_time_ms": 12.34
}
```

### Objeto Paginado

| Campo             | Tipo    | Descrição                                                       |
|-------------------|---------|------------------------------------------------------------------|
| `data`            | array   | Lista de objetos de **[Bankslip Profile](#bankslip-profile)**    |
| `limit`           | int     | Limite de objetos recuperados por página                         |
| `page`            | int     | Número da página recuperada                                      |
| `is_last_page`    | boolean | Informação que indica se a página recuperada é a última          |
| `elapsed_time_ms` | number  | Tempo de execução da consulta no servidor, em milissegundos      |

### Bankslip Profile

| Campo                     | Tipo   | Descrição                                                                                                        |
|---------------------------|--------|--------------------------------------------------------------------------------------------------------------------|
| `bankslip_profile_key`    | string | Identificador da carteira de cobrança.                                                                                   |
| `bankslip_profile_code`   | string | Código da carteira de cobrança.                                                                                                    |
| `bankslip_profile_number` | number | Número da carteira de cobrança.                                                                                                    |
| `bankslip_provider`       | string | Provedor do boleto.                                                                                                  |
| `additional_information`  | object | Informações adicionais da carteira de cobrança.                                                                                    |
| `internal_account_key`    | string | Identificador da conta interna associada.                                                                            |
| `fund_class`              | object | Objeto representando a classe de fundo (ver **[Fund Class](/documentation/iaas/boletos/recuperar_boletos#fund-class)**).                       |
| `total_value`             | number | Valor total em aberto da carteira. Presente apenas após o cálculo periódico de saldo da carteira.                        |
| `total_overdue_value`     | number | Valor total vencido da carteira. Presente apenas após o cálculo periódico de saldo da carteira.                          |

---

# Recuperação de Configurações de Boleto

URL: /documentation/iaas/boletos/recuperar_configuracoes_boleto

---

## Listar configurações de boleto

Retorna uma lista paginada das configurações de boleto de uma carteira de cobrança de uma classe de fundo. O acesso é permitido apenas ao gestor responsável pela classe de fundo.

### Request

ENDPOINT /bankslip_collection/fund_class/FUND_CLASS_KEY/bankslip_profile/BANKSLIP_PROFILE_KEY/bankslip_configurations
MÉTODO GET

### Path Params

| Parâmetro              | Descrição                                                                                                                |
|------------------------|----------------------------------------------------------------------------------------------------------------------------|
| `fund_class_key`       | Chave da classe de fundo. Retorna `404` (`NotFoundFundClass`) caso não exista.                                               |
| `bankslip_profile_key` | Chave da carteira de cobrança, que deve pertencer à classe de fundo. Retorna `404` (`NotFoundBankslipProfile`) caso não seja encontrada. |

### Query Params

Todos os parâmetros são opcionais.

| Parâmetro     | Tipo   | Descrição                                                                                                      |
|---------------|--------|------------------------------------------------------------------------------------------------------------------|
| `issuer_type` | string | Filtra pelo tipo do emissor (ver **[Tipo de Emissor](#tipo-de-emissor)**). Um valor desconhecido retorna o erro `InvalidValueForEntity`. |
| `limit`       | int    | Valor entre 0 e 30 com o número de itens por página. Padrão: `10`.                                                 |
| `page`        | int    | Número da página (começando por zero). Padrão: `0`.                                                                |

Quando `is_last_page` for `false`, solicite a próxima `page` para recuperar os demais resultados.

### Response

Response Body

```json title='Response Body'
{
    "data": [
        {
            "bankslip_configuration_key": "1b382eb7-7006-4389-975b-afa76b0ad7b4",
            "bankslip_profile": {
                "bankslip_profile_key": "a1d7f09b-cb77-48da-a23d-b83d97d4b46b",
                "bankslip_profile_code": "329-09-0001-0000000",
                "bankslip_profile_number": 9,
                "bankslip_provider": "qi_scd",
                "additional_information": {
                    "requester_profile_key": "30f72181-042c-4aae-9be7-b2794916416f"
                },
                "internal_account_key": "18809219-17d9-4845-a830-51e7f2beaf28",
                "fund_class": {
                    "fund_class_key": "92c63a0f-25d6-45cb-90a2-6026c0ce2ef9",
                    "document_number": "00.000.000/0001-01",
                    "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS",
                    "manager": {
                        "name": "GESTÃO DE RECURSOS",
                        "manager_key": "7a5ff2f5-f127-451c-98d8-001826c35c3c",
                        "document_number": "00.100.100/0001-00"
                    }
                }
            },
            "bankslip_issuer_type": "manager",
            "delay": 0,
            "our_number_range": {
                "our_number_range_initial": 1,
                "our_number_range_final": 99999
            }
        },
        {
            "bankslip_configuration_key": "9c47d1a8-3f2e-4b6d-8a1c-5e7f9b3d2c80",
            "bankslip_profile": {
                "bankslip_profile_key": "a1d7f09b-cb77-48da-a23d-b83d97d4b46b",
                "bankslip_profile_code": "329-09-0001-0000000",
                "bankslip_profile_number": 9,
                "bankslip_provider": "qi_scd",
                "additional_information": {
                    "requester_profile_key": "30f72181-042c-4aae-9be7-b2794916416f"
                },
                "internal_account_key": "18809219-17d9-4845-a830-51e7f2beaf28",
                "fund_class": {
                    "fund_class_key": "92c63a0f-25d6-45cb-90a2-6026c0ce2ef9",
                    "document_number": "00.000.000/0001-01",
                    "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS",
                    "manager": {
                        "name": "GESTÃO DE RECURSOS",
                        "manager_key": "7a5ff2f5-f127-451c-98d8-001826c35c3c",
                        "document_number": "00.100.100/0001-00"
                    }
                }
            },
            "bankslip_issuer_type": "internal",
            "delay": 1
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true,
    "elapsed_time_ms": 12.34
}
```

### Objeto Paginado

| Campo             | Tipo    | Descrição                                                              |
|-------------------|---------|--------------------------------------------------------------------------|
| `data`            | array   | Lista de objetos de **[Bankslip Configuration](#bankslip-configuration)** |
| `limit`           | int     | Limite de objetos recuperados por página                                  |
| `page`            | int     | Número da página recuperada                                               |
| `is_last_page`    | boolean | Informação que indica se a página recuperada é a última                   |
| `elapsed_time_ms` | number  | Tempo de execução da consulta no servidor, em milissegundos               |

### Bankslip Configuration

| Campo                        | Tipo   | Descrição                                                                                                              |
|------------------------------|--------|----------------------------------------------------------------------------------------------------------------------------|
| `bankslip_configuration_key` | string | Identificador único da configuração de boleto.                                                                               |
| `bankslip_profile`           | object | Carteira de cobrança associada (ver **[Bankslip Profile](/documentation/iaas/boletos/recuperar_boletos#bankslip-profile)**).                           |
| `bankslip_issuer_type`       | string | Tipo do emissor do boleto (ver **[Tipo de Emissor](#tipo-de-emissor)**).                                                     |
| `delay`                      | int    | Delay configurado para a emissão dos boletos.                                                                                |
| `our_number_range`           | object | Faixa de "nosso número" atribuída à configuração (ver **[Our Number Range](#our-number-range)**). Presente apenas quando a configuração possui uma faixa atribuída. |

### Our Number Range

| Campo                      | Tipo | Descrição                        |
|----------------------------|------|-----------------------------------|
| `our_number_range_initial` | int  | Início da faixa de "nosso número". |
| `our_number_range_final`   | int  | Fim da faixa de "nosso número".    |

## Tipo de Emissor

| Enumerador   | Descrição  |
|--------------|------------|
| `internal`   | Interno    |
| `manager`    | Gestor     |
| `consultant` | Consultor  |

---

# Webhooks

URL: /documentation/iaas/boletos/webhook

Ao longo do ciclo de vida do boleto, o sistema envia webhooks para notificar o parceiro integrador sobre mudanças de status. Todos os eventos utilizam o tipo `bankslip_collection.bankslip_status_change`.

:::info Configuração de webhooks
Para receber webhooks, é necessário ter uma URL de callback configurada junto à QI Tech. Entre em contato com [integracao@qitech.com.br](mailto:integracao@qitech.com.br) para configurar.
:::

## Estrutura do webhook

Todos os webhooks de boleto seguem a mesma estrutura base:

| Campo | Tipo | Descrição |
|---|---|---|
| `webhook_type` | string | Tipo do webhook. Sempre `bankslip_collection.bankslip_status_change`. |
| `webhook_datetime` | string | Data e hora do evento no formato ISO 8601. |
| `data` | object | Dados do evento. Veja tabela abaixo. |

#### Atributos de `data`

| Campo | Tipo | Descrição |
|---|---|---|
| `bankslip_key` | string (UUID) | Identificador único do boleto. |
| `bankslip_configuration_key` | string (UUID) | Identificador da configuração do boleto. |
| `bankslip_profile_key` | string (UUID) | Identificador do perfil do boleto. |
| `status` | string | Status atual do boleto. |
| `fund_class` | object | Dados da classe do fundo associada ao boleto. |
| `external_participant_control_number` | string | Número de controle externo do participante. |
| `participant_control_number` | string | Número de controle interno do participante. |
| `face_value` | float | Valor de face do boleto. |
| `due_date` | string | Data de vencimento no formato `YYYY-MM-DD`. |
| `borrower` | object | Dados do sacado (devedor). |
| `assignor` | object | Dados do cedente. |
| `settlement_instructions` | array | Lista de instruções de liquidação vinculadas ao boleto. |
| `our_number` | integer | **(Opcional)** Nosso número atribuído pelo banco emissor. |
| `our_number_digit` | string | **(Opcional)** Dígito verificador do nosso número. |
| `order_number` | string | **(Opcional)** Número do pedido. |
| `digitable_line` | string | **(Opcional)** Linha digitável do boleto. Presente quando disponível após o registro. |
| `barcode` | string | **(Opcional)** Código de barras do boleto. Presente quando disponível após o registro. |

#### Atributos de `fund_class`

| Campo | Tipo | Descrição |
|---|---|---|
| `document_number` | string | CNPJ da classe do fundo. |
| `fund_class_key` | string (UUID) | Identificador da classe do fundo. |
| `name` | string | Nome da classe do fundo. |

#### Atributos de `settlement_instructions`

| Campo | Tipo | Descrição |
|---|---|---|
| `asset_key` | string (UUID) | Identificador do ativo associado. |
| `asset_type` | string | Tipo do ativo (ex: `duplicata_mercantil`, `duplicata_servicos`, `ccb`). |
| `issue_date` | string | Data de emissão do ativo no formato `YYYY-MM-DD`. |
| `maturity_date` | string | Data de vencimento do ativo no formato `YYYY-MM-DD`. |
| `face_value` | float | Valor de face do ativo. |
| `status` | string | Status da instrução de liquidação. |
| `external_id` | string | **(Opcional)** Identificador externo do ativo. |
| `installment_number` | integer | **(Opcional)** Número da parcela, quando aplicável (ex: CCBs parceladas). |
| `order_number` | string | **(Opcional)** Número do pedido da instrução. |

---

## Eventos por status

### Registro do Boleto

STATUS pending_registration

Enviado quando um boleto é criado e submetido ao banco emissor para registro. O boleto aguarda a confirmação da instituição bancária. Dependendo do banco, os campos `digitable_line`, `barcode` e `our_number` podem estar presentes quando o banco os retorna imediatamente no ato do registro. Para outros bancos, esses campos são preenchidos somente após a confirmação via arquivo de retorno.

```json title='Webhook Body'
{
    "webhook_type": "bankslip_collection.bankslip_status_change",
    "webhook_datetime": "2026-04-15T12:55:35Z",
    "data": {
        "bankslip_key": "7a26c259-1b1f-4d73-9a5b-48230022b8f2",
        "bankslip_configuration_key": "b6b4ff70-917c-4003-bc4d-ebc4ccdd606c",
        "bankslip_profile_key": "5666937c-944a-44c6-98e6-3591f99fe4ff",
        "status": "pending_registration",
        "fund_class": {
            "document_number": "17.645.194/0001-85",
            "fund_class_key": "d81118d0-527b-45b0-8c60-76e9d3ab3aa3",
            "name": "Nome da Classe do Fundo"
        },
        "external_participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9",
        "participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9",
        "face_value": 629.33,
        "due_date": "2026-09-17",
        "borrower": {
            "document_number": "631.430.668-06",
            "name": "Nome do Sacado",
            "person_type": "natural_person",
            "address": {
                "postal_code": "05425-020"
            }
        },
        "assignor": {
            "name": "Nome do Cedente",
            "document_number": "37.341.966/0001-00",
            "person_type": "legal_person"
        },
        "settlement_instructions": [
            {
                "asset_key": "22fc5c95-3622-48ad-b26a-99f8d0499e69",
                "external_id": "758638e4-6fe6-4b69-8799-30728ca16a22",
                "asset_type": "duplicata_mercantil",
                "issue_date": "2025-01-17",
                "maturity_date": "2026-09-17",
                "face_value": 629.33,
                "status": "pending_bankslip_payment"
            }
        ],
        "our_number": 10507,
        "our_number_digit": "0"
    }
}
```

---

### Boleto Registrado

STATUS registered

Enviado quando o banco emissor **confirma o registro** do boleto. A partir deste momento, o boleto está apto para pagamento pelo sacado. Neste webhook, os campos `digitable_line`, `barcode`, `our_number` e `our_number_digit` estarão presentes.

```json title='Webhook Body'
{
    "webhook_type": "bankslip_collection.bankslip_status_change",
    "webhook_datetime": "2026-04-15T13:10:22Z",
    "data": {
        "bankslip_key": "7a26c259-1b1f-4d73-9a5b-48230022b8f2",
        "bankslip_configuration_key": "b6b4ff70-917c-4003-bc4d-ebc4ccdd606c",
        "bankslip_profile_key": "5666937c-944a-44c6-98e6-3591f99fe4ff",
        "status": "registered",
        "fund_class": {
            "document_number": "17.645.194/0001-85",
            "fund_class_key": "d81118d0-527b-45b0-8c60-76e9d3ab3aa3",
            "name": "Nome da Classe do Fundo"
        },
        "external_participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9",
        "participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9",
        "face_value": 629.33,
        "due_date": "2026-09-17",
        "borrower": {
            "document_number": "631.430.668-06",
            "name": "Nome do Sacado",
            "person_type": "natural_person",
            "address": {
                "postal_code": "05425-020"
            }
        },
        "assignor": {
            "name": "Nome do Cedente",
            "document_number": "37.341.966/0001-00",
            "person_type": "legal_person"
        },
        "settlement_instructions": [
            {
                "asset_key": "22fc5c95-3622-48ad-b26a-99f8d0499e69",
                "external_id": "758638e4-6fe6-4b69-8799-30728ca16a22",
                "asset_type": "duplicata_mercantil",
                "issue_date": "2025-01-17",
                "maturity_date": "2026-09-17",
                "face_value": 629.33,
                "status": "pending_bankslip_payment"
            }
        ],
        "our_number": 10507,
        "our_number_digit": "0",
        "digitable_line": "03399.87654 32100.012345 67890.123456 1 00000000062933",
        "barcode": "03391000000000629333987654321000123456789012345"
    }
}
```

---

### Boleto Rejeitado

STATUS rejected

Enviado quando o banco emissor **rejeita o registro** do boleto. O boleto não estará disponível para pagamento e não avançará no fluxo. As instruções de liquidação vinculadas também são marcadas como `rejected`.

```json title='Webhook Body'
{
    "webhook_type": "bankslip_collection.bankslip_status_change",
    "webhook_datetime": "2026-04-15T13:10:22Z",
    "data": {
        "bankslip_key": "7a26c259-1b1f-4d73-9a5b-48230022b8f2",
        "bankslip_configuration_key": "b6b4ff70-917c-4003-bc4d-ebc4ccdd606c",
        "bankslip_profile_key": "5666937c-944a-44c6-98e6-3591f99fe4ff",
        "status": "rejected",
        "fund_class": {
            "document_number": "17.645.194/0001-85",
            "fund_class_key": "d81118d0-527b-45b0-8c60-76e9d3ab3aa3",
            "name": "Nome da Classe do Fundo"
        },
        "external_participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9",
        "participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9",
        "face_value": 629.33,
        "due_date": "2026-09-17",
        "borrower": {
            "document_number": "631.430.668-06",
            "name": "Nome do Sacado",
            "person_type": "natural_person",
            "address": {
                "postal_code": "05425-020"
            }
        },
        "assignor": {
            "name": "Nome do Cedente",
            "document_number": "37.341.966/0001-00",
            "person_type": "legal_person"
        },
        "settlement_instructions": [
            {
                "asset_key": "22fc5c95-3622-48ad-b26a-99f8d0499e69",
                "external_id": "758638e4-6fe6-4b69-8799-30728ca16a22",
                "asset_type": "duplicata_mercantil",
                "issue_date": "2025-01-17",
                "maturity_date": "2026-09-17",
                "face_value": 629.33,
                "status": "rejected"
            }
        ],
        "our_number": 10507,
        "our_number_digit": "0"
    }
}
```

---

### Boleto Baixado

STATUS written_off

Enviado quando o boleto é **baixado** na instituição emissora. Isso pode ocorrer por solicitação de cancelamento.

```json title='Webhook Body'
{
    "webhook_type": "bankslip_collection.bankslip_status_change",
    "webhook_datetime": "2026-04-15T14:30:00Z",
    "data": {
        "bankslip_key": "7a26c259-1b1f-4d73-9a5b-48230022b8f2",
        "bankslip_configuration_key": "b6b4ff70-917c-4003-bc4d-ebc4ccdd606c",
        "bankslip_profile_key": "5666937c-944a-44c6-98e6-3591f99fe4ff",
        "status": "written_off",
        "fund_class": {
            "document_number": "17.645.194/0001-85",
            "fund_class_key": "d81118d0-527b-45b0-8c60-76e9d3ab3aa3",
            "name": "Nome da Classe do Fundo"
        },
        "external_participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9",
        "participant_control_number": "XO0QYVBF1JU9LFBBKGT7XYQV9",
        "face_value": 629.33,
        "due_date": "2026-09-17",
        "borrower": {
            "document_number": "631.430.668-06",
            "name": "Nome do Sacado",
            "person_type": "natural_person",
            "address": {
                "postal_code": "05425-020"
            }
        },
        "assignor": {
            "name": "Nome do Cedente",
            "document_number": "37.341.966/0001-00",
            "person_type": "legal_person"
        },
        "settlement_instructions": [
            {
                "asset_key": "22fc5c95-3622-48ad-b26a-99f8d0499e69",
                "external_id": "758638e4-6fe6-4b69-8799-30728ca16a22",
                "asset_type": "duplicata_mercantil",
                "issue_date": "2025-01-17",
                "maturity_date": "2026-09-17",
                "face_value": 629.33,
                "status": "written_off"
            }
        ],
        "our_number": 10507,
        "our_number_digit": "0",
        "digitable_line": "03399.87654 32100.012345 67890.123456 1 00000000062933",
        "barcode": "03391000000000629333987654321000123456789012345"
    }
}
```

---

# Carteira - Aprovação

URL: /documentation/iaas/composicao_carteira/aprovar_carteira

---

### Request

ENDPOINT /composition/fund_class/FUND_CLASS_KEY/composition/COMPOSITION_KEY
MÉTODO PUT

```json title='Request Body'
{
    "new_status":"confirmed"
}

```

### Enumeradores do "new_status"

| Enumerador                    | Descrição   |
|--------------------------|--------|
| `confirmed`        | Aprovar a carteira |
| `reproved`                 | Reprovar a carteira |

---

# Carteira - Baixar a Carteira

URL: /documentation/iaas/composicao_carteira/baixar_carteira

## Introdução

Este recurso tem como objetivo baixar, de forma síncrona, um relatório baseado na **Composition**. Os relatórios que são suportados são:

- **wallet_composition_by_composition.xlsx**
- **xml_401_by_composition.xml**
- **xml_5_by_composition.xml**

### Request

ENDPOINT /composition/fund_class/FUND_CLASS_KEY/report
MÉTODO POST
STATUS 201

```json title='Request Body'
{
    "composition_type": "final_quota | pre_quota",
    "report_type": "wallet_composition_by_composition | xml_401_by_composition | xml_5_by_composition",
    "reference_date": "2025-01-20"
}
```

### Response

```json title='Response Body'
{
    "document_b64": "BASE64"
}
```

:::warning Atenção
Para baixar a carteira, ela deve estar no status final **confirmed (Confirmada)**, caso contrário a resposta será um **400**.

:::

---

# Introdução

URL: /documentation/iaas/composicao_carteira/inicio

Nesta seção iremos explicar como funciona o consumo da Carteira por meio de APIs. Todos os dias as carteiras de todos os Fundos de Investimento dos Fundos administrados pela QI CTVM são disponibilizadas por essa API, com as informações que compõe a cota daquele determinado dia.

Durante o processamento do fechamento do Fundo, e consequentemente de disponibilização da sua carteira, geramos uma primeira carteira, chamada de **Carteira de Validação**, e uma vez que esta é aprovada, seguimos para a disponibilização da **Carteira Final**.

A principal diferença entre ambas as carteiras é que a de validação é gerada anterior ao processamento do passivo, isso inclui amortizações, aplicações e resgates, enquanto a final, já sensibiliza essas movimentações. Informações dos ativos, despesas, conciliações, e caixa, são sempre idênticas entre as duas carteiras. De forma prática o que muda, é que eventuais "A Pagar" de Resgates a Cotizar, ou "A Receber" de Aplicações Financeiras a Cotizar, são cotizados e sensibilizam o número de Cotas das Séries de Emissão, sem alterar portanto a Cota Divulgada.  

:::warning
É muito importante que quaisquer criticas, ou validações sejam feitos em cima da **Carteira de Validação** antes da sua aprovação, pois uma vez que esta é aprovada, o sistema segue para o processamento do passivo e consequentemente para a disponibilização da carteira final.  Nesta etapa, como já houve o processamento do passivo, eventuais resgates e amortizações já podem ter sido até liquidados.
:::

Para ter acesso a esses serviços, entre em contato com o time [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br), para que seja feito as devidas liberações, tanto em ambiente de Homologação (Sandbox), quanto em ambiente produtivo.

---

# Carteira - Recuperação da Carteira

URL: /documentation/iaas/composicao_carteira/recuperar_carteira

---

## Lista de Carteiras

### Request

ENDPOINT /composition/fund_class/FUND_CLASS_KEY/compositions
MÉTODO GET

### Query Params
| Parâmetro        | Descrição |
|------------------|-----------------------------------------------------------------------------------------------------|
| `not_status`     | Filtra os resultados excluindo composições que esteja no status informado.                          |
| `status`         | Filtra os resultados trazendo apenas composições que esteja no status informado.                    |
| `reference_date` | Data de referência para a consulta das composições. Deve estar no formato `YYYY-MM-DD`.             |
| `type`           | Tipo da composição a ser filtrada pre_quota/final_quota.                                            |
| `start_date`     | Data inicial do intervalo de busca. Obrigatório se `end_date` for informado. Formato: `YYYY-MM-DD`. |
| `end_date`       | Data final do intervalo de busca. Obrigatório se `start_date` for informado. Formato: `YYYY-MM-DD`. |

:::warning Atenção
    Existem duas formas de filtrar por data:
- Consumindo uma data em específico , enviando como *query param* o campo *reference_date* .
- Consumindo um período , enviando como *query param* os campos *start_date* e *end_date*
:::

```json title='Response Body'
{
    "data": [
        {
            "composition_key": "f2208257-1489-4937-8862-031bca34016f",
            "status": "confirmed",
            "composition_type": "pre_quota",
            "composition_date": "2024-11-13",
            "fund_class": {
                "name": "A SAMPLE CLASS",
                "fund_class_key": "5dac941c-c779-4049-a4ee-7cee583b6860",
                "document_number": "18.687.469/0001-06"
            }
        },
        {
            "composition_key": "f2208257-1489-4937-8862-031bca34016f",
            "status": "confirmed",
            "composition_type": "final_quota",
            "composition_date": "2024-11-13",
            "fund_class": {
                "name": "A SAMPLE CLASS",
                "fund_class_key": "5dac941c-c779-4049-a4ee-7cee583b6860",
                "document_number": "18.687.469/0001-06"
            }
        }
    ],
    "limit": 50,
    "page": 0,
    "is_last_page": true
}

```

### Objeto Paginado

| Campo         | Tipo   | Descrição                                                      |
|---------------|--------|----------------------------------------------------------------|
| `data`        | array  | Lista de objetos de **[Composition](#composition)**            |
| `limit`       | int    | Limite de objetos recuperados por página                       |
| `page`        | int    | Número da página recuperada                                    |
| `is_last_page`| boolean| Informação que indica se a página recuperada é a última        |

### Composition

| Campo                    | Tipo   | Descrição                                       |
|--------------------------|--------|-------------------------------------------------|
| `composition_key`        | string | Chave única de identificação da carteira        |
| `status`                 | string | O status daquela carteira                       |
| `composition_type`       | string | O tipo daquela carteira, pre_quota/final_quota  |
| `composition_date`       | string | Data de referência da carteira                  |
| `fund_class`             | object | Objeto de **[Fund Class](#fund_class)**         |

### Fund Class {#fund_class}

| Campo                         | Tipo     | Descrição                                         | Caracteres |
|-------------------------------|----------|---------------------------------------------------|------------|
| `name`                        | string   | Nome da classe de fundo                           | até 255    |
| `fund_class_key`              | string   | Chave única de identificação da classe de fundo   | 36         |
| `document_number`             | string   | CNPJ da classe de fundo                           | -          |

---

## Informações da Carteira

### Request

ENDPOINT /composition/fund_class/FUND_CLASS_KEY/composition/COMPOSITION_KEY
MÉTODO GET

```json title='Response Body'
{
    "composition_key": "f2208257-1489-4937-8862-031bca34016f",
    "status": "confirmed",
    "composition_type": "pre_quota",
    "composition_date": "2024-12-02",
    "fund_class": {
        "name": "A SAMPLE CLASS",
        "fund_class_key": "5dac941c-c779-4049-a4ee-7cee583b6860",
        "document_number": "18.687.469/0001-06"
    },
    "issuance_series": [
      {
        "issuance_serie_key": "840e01e9-0df8-4719-83c4-f10b839d8384",
        "name": "SUBORDINADA - 1",
        "gross_net_worth": 1891397.29,
        "net_net_worth": 1891397.29,
        "gross_quota_value": 1.76821576,
        "net_quota_value": 1.76821576,
        "number_of_quotas": 1069664.309518427,
        "applied_value": 0.0,
        "applied_quotas": 0.0,
        "redeemed_value": 0.0,
        "redeemed_quotas": 0.0,
        "amortized_value": 0.0,
        "tax_anticipated_value": 0.0,
        "tax_anticipated_quotas": 0.0,
        "profitabilities": [
            {
                "reference_date": "2024-11-29",
                "quota_value": 1.76065188,
                "di_benchmark_quota_value": 1.7613906,
                "quota_percentage": 100.43,
                "di_benchmark_percentage": 100.43,
                "type": "monthly"
            },
            {
                "reference_date": "2024-11-25",
                "quota_value": 1.7568068,
                "di_benchmark_quota_value": 1.76049545,
                "quota_percentage": 99.79,
                "di_benchmark_percentage": 100.0,
                "type": "monthly"
            },
            {
                "reference_date": "2024-11-01",
                "quota_value": 1.74121452,
                "di_benchmark_quota_value": 1.75502225,
                "quota_percentage": 99.21,
                "di_benchmark_percentage": 100.0,
                "type": "monthly"
            },
            {
                "reference_date": "2024-10-03",
                "quota_value": 1.72167143,
                "di_benchmark_quota_value": 1.75002091,
                "quota_percentage": 98.38,
                "di_benchmark_percentage": 100.0,
                "type": "monthly"
            },
            {
                "reference_date": "2024-09-03",
                "quota_value": 1.70128747,
                "di_benchmark_quota_value": 1.74445962,
                "quota_percentage": 97.52,
                "di_benchmark_percentage": 100.0,
                "type": "monthly"
            },
            {
                "reference_date": "2024-06-05",
                "quota_value": 1.63380383,
                "di_benchmark_quota_value": 1.7178922,
                "quota_percentage": 95.1,
                "di_benchmark_percentage": 100.0,
                "type": "monthly"
            },
            {
                "reference_date": "2023-12-08",
                "quota_value": 1.52421994,
                "di_benchmark_quota_value": 1.68553599,
                "quota_percentage": 90.43,
                "di_benchmark_percentage": 100.0,
                "type": "daily"
            }
        ]
      }
    ],
    "assets": [
        {
            "asset_key": "34f42521-f27f-424a-958f-8b53f15cc80d",
            "asset_type": "fixed_income_fund_quota",
            "purchase_date": "2024-11-27",
            "total_purchase_value": 1009320,
            "bad_debt_percentage": 0,
            "bad_debt_value": 0,
            "overdue_accounting_value": 0,
            "current_accounting_value": 1234335,
            "current_fair_accounting_value": 1234335
        }
    ],
    "consolidated_assets": [
        {
            "asset_type": "ccb",
            "asset_category": "credit",
            "total_units": 175623,
            "bad_debt_value": 0,
            "overdue_accounting_value": 75642,
            "current_accounting_value": 187762590,
            "current_fair_accounting_value": 187762590,
            "post_maturity_interest_value": 0,
            "delay_interest_value": 0,
            "delay_fine_value": 0
        }
    ],
    "receivables": [
        {
          "origin_key": "a60f9226-edac-488e-9a58-6205a334e6ba",
          "origin_type": "expense",
          "description": "Taxa CVM - 2024",
          "total_value": 711515,
          "recognized_value": 654125,
          "start_date": "2024-01-09",
          "end_date": "2024-12-31",
          "payment_date": "2024-05-10"
        }
    ],
    "payables": [
      {
        "origin_key": "19b83b17-d36c-4edd-97fe-99af6a0a4a63",
        "origin_type": "expense",
        "description": "Taxa de Gestão - 2024/12",
        "total_value": 14586,
        "recognized_value": 14586,
        "start_date": "2024-12-02",
        "end_date": "2024-12-31",
        "payment_date": "2025-01-08"
      },
    ],
    "cash_accounts": [
      {
        "account_key": "a41e4fa8-6950-485e-9a5b-70f21cc6774a",
        "balance": 100000,
        "unconcilied_cash_in": 0,
        "unconcilied_cash_out": 0,
        "account_branch": "0001",
        "account_digit": "1",
        "account_number": "372832",
        "accounting_identification": 1,
        "financial_institution": {
            "code": "329",
            "ispb": "32402502",
            "name": "QI Sociedade de Crédito Direto"
        }
      }
    ]
}

```

### Composition Completo

| Campo                    | Tipo   | Descrição                                                   |
|--------------------------|--------|-------------------------------------------------------------|
| `composition_key`        | string | Chave única de identificação da carteira                    |
| `status`                 | string | O status daquela carteira                                   |
| `composition_type`       | string | O tipo daquela carteira, pre_quota/final_quota              |
| `composition_date`       | string | Data de referência da carteira                              |
| `fund_class`             | object | Objeto de **[Fund Class](#fund_class)**                     |
| `issuance_series`        | array  | Lista de objetos de **[Issuance Series](#issuance_serie)** |
| `assets`                 | array  | Lista de objetos de **[Assets](#composition)**              |
| `consolidated_assets`    | array  | Lista de objetos de **[Consolidated Assets](#composition)** |
| `receivables`            | array  | Lista de objetos de **[Receivables](#composition)**         |
| `payables`               | array  | Lista de objetos de **[Paybles](#composition)**             |
| `cash_accounts`          | array  | Lista de objetos de **[Cash Accounts](#composition)**       |

### Issuance Serie {#issuance_serie}

| Campo                    | Tipo   | Descrição                                                   |
|--------------------------|--------|-------------------------------------------------------------|
| `issuance_serie_key`      | string | Chave única de identificação da série de emissão            |
| `name`                    | string | O nome daquela série                                        |
| `gross_net_worth`         | float  | O PL Bruto daquela série                                    |
| `net_net_worth`           | float  | O PL Líquido daquela série                                  |
| `gross_quota_value`       | float  | Valor da Cota Bruta                                         |
| `net_quota_value`         | float  | Valor da Cota Líquida                                       |
| `number_of_quotas`        | float  | Número Total de Cotas                                       |
| `applied_value`           | float  | Valor total aplicado no período (opcional)                  |
| `applied_quotas`          | float  | Quantidade de cotas aplicadas no período (opcional)         |
| `redeemed_value`          | float  | Valor total resgatado no período (opcional)                 |
| `redeemed_quotas`         | float  | Quantidade de cotas resgatadas no período (opcional)        |
| `amortized_value`         | float  | Valor total amortizado no período (opcional)                |
| `tax_anticipated_value`   | float  | Valor do imposto antecipado (opcional)                      |
| `tax_anticipated_quotas`  | float  | Quantidade de cotas do imposto antecipado (opcional)        |
| `isin_code`               | string | Código ISIN da série (opcional)                             |
| `profitabilities`         | array  | Lista de objetos de **[Profitability](#profitability)**     |

### Profitability

| Campo                       | Tipo   | Descrição                                                            |
|-----------------------------|--------|----------------------------------------------------------------------|
| `reference_date`             | string | Data de Referência no qual a performance é analisada                 |
| `quota_value`                | float  | O valor da Cota da Série na Data de Referência                       |
| `di_benchmark_quota_value`   | float  | O valor da Cota hoje caso a Cota de referência rodasse a 100% do DI  |
| `quota_percentage`           | float  | Rentabilidade acumulada da cota no período (%)                        |
| `di_benchmark_percentage`    | float  | Rentabilidade acumulada do benchmark DI no período (%)               |
| `type`                       | string | Tipo do período de rentabilidade      |

### Assets

| Campo                           | Tipo    | Descrição                                             |
|---------------------------------|---------|-------------------------------------------------------|
| `asset_key`                     | string  | Chave única de identificação do ativo                 |
| `asset_type`                    | string  | O Tipo do ativo                                       |
| `purchase_date`                 | string  | Data de Aquisição do ativo                            |
| `total_purchase_value`          | string  | Valor Total de Aquisição do Ativo                     |
| `bad_debt_percentage`           | string  | % de PDD aplicado                                     |
| `bad_debt_value`                | integer | Valor total de PDD considerado - Inteiro em centavos  |
| `overdue_accounting_value`      | integer | Valor vencido do Ativo - Inteiro em centavos          |
| `current_accounting_value`      | integer | Valor total do Ativo  - Inteiro em centavos           |
| `current_fair_accounting_value` | integer | Valor total do Ativo  - Inteiro em centavos           |

### Consolidated Assets

| Campo                           | Tipo    | Descrição                                                            |
|---------------------------------|---------|----------------------------------------------------------------------|
| `asset_type`                    | string  | O Tipo do ativo                                                      |
| `asset_category`                | string  | A categoria do ativo                                                 |
| `total_units`                   | integer | O número total de Ativos consolidados desse tipo                     |
| `bad_debt_value`                | integer | Valor total de PDD considerado - Inteiro em centavos                 |
| `overdue_accounting_value`      | integer | Valor vencido do Ativo - Inteiro em centavos                         |
| `current_accounting_value`      | integer | Valor total do Ativo - Inteiro em centavos                           |
| `current_fair_accounting_value` | integer | Valor justo total do Ativo - Inteiro em centavos                     |
| `post_maturity_interest_value`  | integer | Juros pós-vencimento - Inteiro em centavos                           |
| `delay_interest_value`          | integer | Juros de mora - Inteiro em centavos                                  |
| `delay_fine_value`              | integer | Multa por atraso - Inteiro em centavos                               |

### Receivables

| Campo                       | Tipo   | Descrição                                                            |
|-----------------------------|--------|----------------------------------------------------------------------|
| `origin_key`                | string | Chave única de identificação do recurso que origina esse A Receber   |
| `origin_type`               | string | O Tipo do recurso que origina esse A Receber                         |
| `description`               | string | Descrição do item                                                    |
| `total_value`               | float  | O valor Total A Receber                                              |
| `recognized_value`          | float  | O valor que já foi apropriado                                        |
| `start_date`                | string | A data de início de apropriação                                      |
| `end_date`                  | string | O data de fim da apropriação                                         |
| `payment_date`              | string | A data de Liquidação                                                 |

### Payables

| Campo                       | Tipo   | Descrição                                                            |
|-----------------------------|--------|----------------------------------------------------------------------|
| `origin_key`                | string | Chave única de identificação do recurso que origina esse A Pagar     |
| `origin_type`               | string | O Tipo do recurso que origina esse A Pagar                           |
| `description`               | string | Descrição do item                                                    |
| `total_value`               | float  | O valor Total A Pagar                                                |
| `recognized_value`          | float  | O valor que já foi apropriado                                        |
| `start_date`                | string | A data de início de apropriação                                      |
| `end_date`                  | string | O data de fim da apropriação                                         |
| `payment_date`              | string | A data de Liquidação                                                 |

### Cash Accounts

| Campo                       | Tipo    | Descrição                                                         |
|-----------------------------|---------|-------------------------------------------------------------------|
| `account_key`               | string  | Chave única de identificação da conta                             |
| `balance`                   | integer | O saldo da conta - Inteiro em centavos                            |
| `unconcilied_cash_in`       | integer | O valor de Entradas A Conciliar nessa conta - Inteiro em centavos |
| `unconcilied_cash_out`      | integer | O valor de Saídas A Conciliar nessa conta - Inteiro em centavos   |
| `account_branch`            | string  | A Agência da conta                                                |
| `account_digit`             | string  | O Dígito da conta                                                 |
| `account_number`            | string  | O número da conta                                                 |
| `accounting_identification` | integer | O identificador contábil daquela conta                            |
| `financial_institution`     | object  | Objetos de **[Financial Institution](#financial_institution)**    |
| `account_data`              | object  | Objeto com os dados da conta (contém os mesmos campos acima)      |

### Financial Institution {#financial_institution}

| Campo                       | Tipo   | Descrição             |
|-----------------------------|--------|-----------------------|
| `code`                      | string | Código COMPE da IF    |
| `ispb`                      | string | O ISPB da IF          |
| `name`                      | string | O nome da IF          |

---

# Consulta de Aplicações Financeiras por Classe de Fundo

URL: /documentation/iaas/cotas_de_fundo/consulta_paginada_aplicacoes_financeiras

:::warning Atenção
Este recurso está disponível apenas para integrações que exercem o papel de  **Gestor**.
:::

### Request

ENDPOINT /trade_fund_quota/fund_class/FUND_CLASS_KEY/financial_applications
MÉTODO GET

#### Query Params

| Parâmetro                          | Tipo   | Descrição                                     |
| ---------------------------------- | ------ | --------------------------------------------- |
| `quotation_date`                   | data   | Data de cotização da aplicação                |
| `financial_application_status`     | string | Filtra as aplicações por um status específico |
| `not_financial_application_status` | string | Exclui as aplicações com um status específico |
| `document_number`                  | string | CNPJ da classe do fundo investido             |

### Response

STATUS 200

Caso 01: Retorno com uma aplicação

```json
{
  "data": [
        {
            "amount": 0.00,
            "financial_application_key": "UUID",
            "asset_key": "UUID",
            "quotation_date": "YYYY-MM-DD",
            "status": "confirmed",
            "issuance_serie": {
                "issuance_serie_key": "UUID",
                "name": "Invested Issuance Serie Name",
                "subclass_name": "Invested Sub Class Name",
                "serie": 1,
                "quota_calculation_method": "quota_value",
                "internal_code": "Internal Code",
                "fund_class_name": "Invested Fund Class Name",
                "fund_class_short_name": "Invested Fund Class short name",
                "fund_class_document_number": "00.000.000/0000-00",
                "minimum_share_capital": 0.0,
                "investment_category": "multi_market",
                "payment_type": "transfer",
                "account_data": {
                    "account_digit": "0",
                    "account_branch": "0001",
                    "account_number": "12345",
                    "financial_institution_code": "329",
                    "financial_institution_ispb": "00000000"
                },
                "last_updated_date": "YYYY-MM-DD",
                "administrator": {
                    "administrator_key": "UUID",
                    "name": "Administrator Name",
                    "document_number": "00.000.000/0000-00"
                },
                "operation_periods": {
                    "redemption_request": {
                        "payment": {
                            "days": 1,
                            "type": "until",
                            "calendar_base": "calendar_365"
                        },
                        "quotation": {
                            "days": 1,
                            "type": "fixed",
                            "calendar_base": "calendar_365"
                        }
                    },
                    "amortization_request": {
                        "payment": {
                            "days": 0,
                            "type": "fixed",
                            "calendar_base": "workdays"
                        },
                        "quotation": {
                            "days": 0,
                            "type": "fixed",
                            "calendar_base": "workdays"
                        }
                    },
                    "financial_application": {
                        "payment": {
                            "days": 0,
                            "type": "fixed",
                            "calendar_base": "workdays"
                        },
                        "quotation": {
                            "days": 0,
                            "type": "fixed",
                            "calendar_base": "workdays"
                        }
                    }
                },
                "isin_code": "BR000000000"
            },
            "fund_class": {
                "fund_class_key": "UUID",
                "name": "Fund Class Name",
                "short_name": "Fund Class Short Name",
                "document_number": "00.000.000/0000-00",
                "accounting_date": "YYYY-MM-DD",
                "distributor": {
                    "name": "Distributor Name",
                    "distributor_key": "UUID",
                    "document_number": "00.000.000/0000-00"
                },
                "manager": {
                    "manager_key": "UUID",
                    "manager_name": "Manager Name",
                    "document_number": "00.000.000/0000-00"
                }
            }
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true
}
```

### Page
| Campo         | Tipo   | Descrição                                                                    |
|---------------|--------|------------------------------------------------------------------------------|
| `data`        | array  | Lista de objetos de **[Financial Application](#financial_application)**      |
| `limit`       | int    | Limite de objetos recuperados por página                                     |
| `page`        | int    | Número da página recuperada                                                  |
| `is_last_page`| boolean| Informação que indica se a página recuperada é a última                      |

### Financial Application {#financial_application}

| Campo                                | Tipo   | Descrição                                       |
| ------------------------------------ | ------ | ----------------------------------------------- |
| amount                               | float  | Valor aplicado                                  |
| financial_application_key            | string | Chave única da aplicação financeira             |
| asset_key                            | string | Chave do ativo relacionado                      |
| quotation_date                       | string | Data de cotização (YYYY-MM-DD)                  |
| status                               | string | Status da aplicação                             |
| external_financial_application_key   | string | Identificador externo da aplicação financeira   |
| issuance_serie                       | JSON   | Objeto de **[Issuance Serie](#issuance-serie)** |
| fund_class                           | JSON   | Objeto de **[Fund Class](#fund-class)**         |

### Issuance Serie

| Campo                         | Tipo   | Descrição                                             |
| ----------------------------- | ------ | ----------------------------------------------------- |
| issuance_serie_key            | string | Chave única da série de emissão                       |
| name                          | string | Nome da série de emissão                              |
| subclass_name                 | string | Nome da subclasse (ex: SUBORDINADA)                   |
| serie                         | int    | Número da série                                       |
| quota_calculation_method      | string | Método de cálculo da cota (ex: quota_value)           |
| internal_code                 | string | Código interno da série                               |
| fund_class_name               | string | Nome da classe do fundo associado à série             |
| fund_class_short_name         | string | Nome curto da classe do fundo                         |
| fund_class_document_number    | string | CNPJ da classe do fundo                               |
| minimum_share_capital         | float  | Valor mínimo para aplicação                           |
| investment_category           | string | Categoria do investimento (ex: multi_market)          |
| payment_type                  | string | Tipo de pagamento (ex: transfer)                      |
| account_data                  | JSON   | Objeto de **[Account Data](#account-data)**           |
| last_updated_date             | string | Última data de atualização (YYYY-MM-DD)               |
| administrator                 | JSON   | Objeto de **[Administrator](#administrator)**         |
| operation_periods             | JSON   | Objeto de **[Operation Periods](#operation-periods)** |
| isin_code                     | string | Código ISIN da série                                  |

### Administrator

| Campo              | Tipo   | Descrição                    |
| ------------------ | ------ | ---------------------------- |
| administrator_key  | string | Chave única do administrador |
| name               | string | Nome do administrador        |
| document_number    | string | CNPJ do administrador        |

### Operation Periods

| Campo                  | Tipo | Descrição                                                                              |
| ---------------------- | ---- | -------------------------------------------------------------------------------------- |
| redemption_request     | JSON | Objeto de períodos de **[Cotização e Pagamento](#quotation-and-payment)** para resgates|
| amortization_request   | JSON | Objeto de períodos de **[Cotização e Pagamento](#quotation-and-payment)** amortizações |
| financial_application  | JSON | Objeto de períodos de **[Cotização e Pagamento](#quotation-and-payment)** aplicações   |

### Quotation and Payment

| Campo          | Tipo   | Descrição                                        |
| -------------- | ------ | ------------------------------------------------ |
| days           | int    | Quantidade de dias                               |
| type           | string | Tipo de contagem (ex: fixed, until)              |
| calendar_base  | string | Base de calendário (ex: workdays, calendar_365)  |

### Account Data

| Campo                        | Tipo   | Descrição                                                         |
| ---------------------------- | ------ | ----------------------------------------------------------------- |
| account_digit                | string | Dígito da conta bancária                                          |
| account_branch               | string | Número da agência bancária                                        |
| account_number               | string | Número da conta bancária                                          |
| financial_institution_code   | string | Código da instituição financeira                                  |
| financial_institution_ispb   | string | ISPB da instituição financeira (Sistema de Pagamentos Brasileiro) |

### Fund Class

| Campo            | Tipo   | Descrição                                 |
| ---------------- | ------ | ----------------------------------------- |
| fund_class_key   | string | Chave única da classe de fundo            |
| name             | string | Nome completo da classe de fundo          |
| short_name       | string | Nome curto da classe de fundo             |
| document_number  | string | CNPJ da classe de fundo                   |
| accounting_date  | string | Data contábil mais recente                |
| distributor      | JSON   | Objeto de **[Distributor](#distributor)** |
| manager          | JSON   | Objeto de **[Manager](#manager)**         |

### Distributor

| Campo            | Tipo   | Descrição                   |
| ---------------- | ------ | --------------------------- |
| name             | string | Nome do distribuidor        |
| distributor_key  | string | Chave única do distribuidor |
| document_number  | string | CNPJ do distribuidor        |

### Manager

| Campo            | Tipo   | Descrição                         |
| ---------------- | ------ | --------------------------------- |
| manager_key      | string | Chave única do gestor             |
| manager_name     | string | Nome do gestor da classe de fundo |
| document_number  | string | CNPJ do gestor                    |

---

# Consulta de Resgates por Classe de Fundo

URL: /documentation/iaas/cotas_de_fundo/consulta_paginada_resgates

:::warning Atenção
Este recurso está disponível apenas para integrações que exercem o papel de Gestor.
:::

### Request

ENDPOINT /trade_fund_quota/fund_class/FUND_CLASS_KEY/redemption_requests
MÉTODO GET

#### Query Params

| Parâmetro                       | Tipo   | Descrição                                   |
| ------------------------------- | ------ | ------------------------------------------- |
| `quotation_date`                | data   | Data de cotização do resgate                |
| `redemption_request_status`     | string | Filtra os resgates por um status específico |
| `not_redemption_request_status` | string | Exclui os resgates com um status específico |
| `document_number`               | string | CNPJ da classe do fundo investido           |

### Response

STATUS 200

Caso 01: Retorno com um resgate

```json
{
  "data": [
    {
      "redemption_request_key": "UUID",
      "status": "confirmed",
      "quotation_date": "YYYY-MM-DD",
      "payment_date": "YYYY-MM-DD",
      "amount": 0.00,
      "issuance_serie": {
        "issuance_serie_key": "UUID",
        "name": "Issuance Serie Name",
        "subclass_name": "SUBORDINADA",
        "serie": 1,
        "quota_calculation_method": "quota_value",
        "internal_code": "Internal Code",
        "fund_class_name": "Fund Class Name",
        "fund_class_short_name": "Fund Class Short Name",
        "fund_class_document_number": "00.000.000/0000-00",
        "minimum_share_capital": 0.0,
        "investment_category": "fixed_income",
        "payment_type": "automatic_debit",
        "financial_institution_code": "341",
        "account_data": {
                    "account_digit": "0",
                    "account_branch": "0001",
                    "account_number": "12345",
                    "financial_institution_code": "329",
                    "financial_institution_ispb": "00000000"
                },
        "last_updated_date": "YYYY-MM-DD",
        "administrator": {
          "administrator_key": "UUID",
          "name": "Administrator Name",
          "document_number": "00.000.000/0000-00"
        },
        "operation_periods": {
                    "redemption_request": {
                        "payment": {
                            "days": 1,
                            "type": "until",
                            "calendar_base": "calendar_365"
                        },
                        "quotation": {
                            "days": 1,
                            "type": "fixed",
                            "calendar_base": "calendar_365"
                        }
                    },
                    "amortization_request": {
                        "payment": {
                            "days": 0,
                            "type": "fixed",
                            "calendar_base": "workdays"
                        },
                        "quotation": {
                            "days": 0,
                            "type": "fixed",
                            "calendar_base": "workdays"
                        }
                    },
                    "financial_application": {
                        "payment": {
                            "days": 0,
                            "type": "fixed",
                            "calendar_base": "workdays"
                        },
                        "quotation": {
                            "days": 0,
                            "type": "fixed",
                            "calendar_base": "workdays"
                        }
                    }
                },
        "issuance_serie_data": {
          "name": "Issuance Serie Name",
          "serie": 1,
          "payment_type": "automatic_debit",
          "remuneration": "residual",
          "internal_code": "Internal Code",
          "subclass_name": "SUBORDINADA",
          "fund_class_name": "Fund Class Name",
          "issuance_serie_key": "UUID",
          "tax_classification": "long_term",
          "investment_category": "fixed_income",
          "fund_class_short_name": "Fund Class Short Name",
          "minimum_share_capital": 0.00,
          "quota_calculation_method": "quota_value",
          "financial_institution_code": "329",
          "fund_class_document_number": "00.000.000/0000-00",
          "administrator_document_number": "00.000.000/0000-00"
        }
      },
      "fund_class": {
        "fund_class_key": "UUID",
        "name": "Fund Class Name",
        "short_name": "Fund Class Short Name",
        "document_number": "00.000.000/0000-00",
        "accounting_date": "YYYY-MM-DD",
        "distributor": {
          "name": "Distributor Name",
          "distributor_key": "UUID",
          "document_number": "00.000.000/0000-00"
        },
        "manager": {
          "manager_key": "UUID",
          "manager_name": "Manager Name",
          "document_number": "00.000.000/0000-00"
        }
      }
    }
  ],
  "limit": 10,
  "page": 0,
  "is_last_page": true
}
```

### Page
| Campo          | Tipo    | Descrição                                                         |
| -------------- | ------- | ----------------------------------------------------------------- |
| `data`         | array   | Lista de objetos de **[Redemption Request](#redemption-request)** |
| `limit`        | int     | Limite de objetos recuperados por página                          |
| `page`         | int     | Número da página recuperada                                       |
| `is_last_page` | boolean | Informação que indica se a página recuperada é a última           |

### Redemption Request

| Campo                              | Tipo   | Descrição                                       |
| ---------------------------------- | ------ | ----------------------------------------------- |
| redemption_request_key             | string | Chave única do pedido de resgate                |
| external_redemption_request_key    | string | Chave externa de controle (opcional)            |
| status                             | string | Status do resgate (ex: confirmed)               |
| quotation_date                     | string | Data da cotização do resgate                    |
| payment_date                       | string | Data do pagamento do resgate                    |
| amount                             | float  | Valor resgatado                                 |
| issuance_serie                     | JSON   | Objeto de **[Issuance Serie](#issuance-serie)** |
| fund_class                         | JSON   | Objeto de **[Fund Class](#fund-class)**         |

### Issuance Serie

| Campo                         | Tipo   | Descrição                                             |
| ----------------------------- | ------ | ----------------------------------------------------- |
| issuance_serie_key            | string | Chave única da série de emissão                       |
| name                          | string | Nome da série de emissão                              |
| subclass_name                 | string | Nome da subclasse (ex: SUBORDINADA)                   |
| serie                         | int    | Número da série                                       |
| quota_calculation_method      | string | Método de cálculo da cota (ex: quota_value)           |
| internal_code                 | string | Código interno da série                               |
| fund_class_name               | string | Nome da classe do fundo associado à série             |
| fund_class_short_name         | string | Nome curto da classe do fundo                         |
| fund_class_document_number    | string | CNPJ da classe do fundo                               |
| minimum_share_capital         | float  | Valor mínimo para aplicação                           |
| investment_category           | string | Categoria do investimento (ex: multi_market)          |
| payment_type                  | string | Tipo de pagamento (ex: transfer)                      |
| account_data                  | JSON   | Objeto de **[Account Data](#account-data)**           |
| last_updated_date             | string | Última data de atualização (YYYY-MM-DD)               |
| administrator                 | JSON   | Objeto de **[Administrator](#administrator)**         |
| operation_periods             | JSON   | Objeto de **[Operation Periods](#operation-periods)** |
| isin_code                     | string | Código ISIN da série                                  |

### Administrator

| Campo              | Tipo   | Descrição                    |
| ------------------ | ------ | ---------------------------- |
| administrator_key  | string | Chave única do administrador |
| name               | string | Nome do administrador        |
| document_number    | string | CNPJ do administrador        |

### Operation Periods

| Campo                  | Tipo | Descrição                                                                              |
| ---------------------- | ---- | -------------------------------------------------------------------------------------- |
| redemption_request     | JSON | Objeto de períodos de **[Cotização e Pagamento](#quotation-and-payment)** para resgates|
| amortization_request   | JSON | Objeto de períodos de **[Cotização e Pagamento](#quotation-and-payment)** amortizações |
| financial_application  | JSON | Objeto de períodos de **[Cotização e Pagamento](#quotation-and-payment)** aplicações   |

### Quotation and Payment

| Campo          | Tipo   | Descrição                                        |
| -------------- | ------ | ------------------------------------------------ |
| days           | int    | Quantidade de dias                               |
| type           | string | Tipo de contagem (ex: fixed, until)              |
| calendar_base  | string | Base de calendário (ex: workdays, calendar_365)  |

### Account Data

| Campo                        | Tipo   | Descrição                                                         |
| ---------------------------- | ------ | ----------------------------------------------------------------- |
| account_digit                | string | Dígito da conta bancária                                          |
| account_branch               | string | Número da agência bancária                                        |
| account_number               | string | Número da conta bancária                                          |
| financial_institution_code   | string | Código da instituição financeira                                  |
| financial_institution_ispb   | string | ISPB da instituição financeira (Sistema de Pagamentos Brasileiro) |

### Fund Class

| Campo            | Tipo   | Descrição                                 |
| ---------------- | ------ | ----------------------------------------- |
| fund_class_key   | string | Chave única da classe de fundo            |
| name             | string | Nome completo da classe de fundo          |
| short_name       | string | Nome curto da classe de fundo             |
| document_number  | string | CNPJ da classe de fundo                   |
| accounting_date  | string | Data contábil mais recente                |
| distributor      | JSON   | Objeto de **[Distributor](#distributor)** |
| manager          | JSON   | Objeto de **[Manager](#manager)**         |

### Distributor

| Campo            | Tipo   | Descrição                   |
| ---------------- | ------ | --------------------------- |
| name             | string | Nome do distribuidor        |
| distributor_key  | string | Chave única do distribuidor |
| document_number  | string | CNPJ do distribuidor        |

### Manager

| Campo            | Tipo   | Descrição                         |
| ---------------- | ------ | --------------------------------- |
| manager_key      | string | Chave única do gestor             |
| manager_name     | string | Nome do gestor da classe de fundo |
| document_number  | string | CNPJ do gestor                    |

---

# Consulta de Séries de Emissão

URL: /documentation/iaas/cotas_de_fundo/consulta_paginada_series_de_emissao

:::warning Atenção
Este recurso está disponível apenas para integrações que exercem o papel de  **Gestor**.
:::

### Request

ENDPOINT /trade_fund_quota/issuance_series
MÉTODO GET

#### Query Params

| Parâmetro                    | Tipo   | Descrição                          |
| ---------------------------- | ------ | ---------------------------------- |
| `fund_class_document_number` | string | CNPJ do fundo (00.000.000/0001-00) |

### Response

STATUS 200

Caso 01: Retorno com uma série

```json
{
  "data": [
    {
        "issuance_serie_key": "UUID",
        "name": "Invested Issuance Serie Name",
        "subclass_name": "Invested Sub Class Name",
        "serie": 1,
        "quota_calculation_method": "quota_value",
        "internal_code": "Internal Code",
        "fund_class_name": "Invested Fund Class Name",
        "fund_class_short_name": "Invested Fund Class short name",
        "fund_class_document_number": "00.000.000/0000-00",
        "minimum_share_capital": 0.0,
        "investment_category": "multi_market",
        "payment_type": "transfer",
        "account_data": {
            "account_digit": "0",
            "account_branch": "0001",
            "account_number": "12345",
            "financial_institution_code": "329",
            "financial_institution_ispb": "00000000"
        },
        "last_updated_date": "YYYY-MM-DD",
        "administrator": {
            "administrator_key": "UUID",
            "name": "Administrator Name",
            "document_number": "00.000.000/0000-00"
        },
        "operation_periods": {
            "redemption_request": {
                "payment": {
                    "days": 1,
                    "type": "until",
                    "calendar_base": "calendar_365"
                },
                "quotation": {
                    "days": 1,
                    "type": "fixed",
                    "calendar_base": "calendar_365"
                }
            },
            "amortization_request": {
                "payment": {
                    "days": 0,
                    "type": "fixed",
                    "calendar_base": "workdays"
                },
                "quotation": {
                    "days": 0,
                    "type": "fixed",
                    "calendar_base": "workdays"
                }
            },
            "financial_application": {
                "payment": {
                    "days": 0,
                    "type": "fixed",
                    "calendar_base": "workdays"
                },
                "quotation": {
                    "days": 0,
                    "type": "fixed",
                    "calendar_base": "workdays"
                }
            }
        },
        "isin_code": "BR000000000"
    }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true
}
```

### Page
| Campo         | Tipo   | Descrição                                                                    |
|---------------|--------|------------------------------------------------------------------------------|
| `data`        | array  | Lista de objetos de **[Issuance Serie](#issuance_serie)**      |
| `limit`       | int    | Limite de objetos recuperados por página                                     |
| `page`        | int    | Número da página recuperada                                                  |
| `is_last_page`| boolean| Informação que indica se a página recuperada é a última                      |

### Issuance Serie {#issuance_serie}

| Campo                         | Tipo   | Descrição                                             |
| ----------------------------- | ------ | ----------------------------------------------------- |
| issuance_serie_key            | string | Chave única da série de emissão                       |
| name                          | string | Nome da série de emissão                              |
| subclass_name                 | string | Nome da subclasse (ex: SUBORDINADA)                   |
| serie                         | int    | Número da série                                       |
| quota_calculation_method      | string | Método de cálculo da cota (ex: quota_value)           |
| internal_code                 | string | Código interno da série                               |
| fund_class_name               | string | Nome da classe do fundo associado à série             |
| fund_class_short_name         | string | Nome curto da classe do fundo                         |
| fund_class_document_number    | string | CNPJ da classe do fundo                               |
| minimum_share_capital         | float  | Valor mínimo para aplicação                           |
| investment_category           | string | Categoria do investimento (ex: multi_market)          |
| payment_type                  | string | Tipo de pagamento (ex: transfer)                      |
| account_data                  | JSON   | Objeto de **[Account Data](#account-data)**           |
| last_updated_date             | string | Última data de atualização (YYYY-MM-DD)               |
| administrator                 | JSON   | Objeto de **[Administrator](#administrator)**         |
| operation_periods             | JSON   | Objeto de **[Operation Periods](#operation-periods)** |
| isin_code                     | string | Código ISIN da série                                  |

### Administrator

| Campo              | Tipo   | Descrição                    |
| ------------------ | ------ | ---------------------------- |
| administrator_key  | string | Chave única do administrador |
| name               | string | Nome do administrador        |
| document_number    | string | CNPJ do administrador        |

### Operation Periods

| Campo                  | Tipo | Descrição                                                                              |
| ---------------------- | ---- | -------------------------------------------------------------------------------------- |
| redemption_request     | JSON | Objeto de períodos de **[Cotização e Pagamento](#quotation-and-payment)** para resgates|
| amortization_request   | JSON | Objeto de períodos de **[Cotização e Pagamento](#quotation-and-payment)** amortizações |
| financial_application  | JSON | Objeto de períodos de **[Cotização e Pagamento](#quotation-and-payment)** aplicações   |

### Quotation and Payment

| Campo          | Tipo   | Descrição                                        |
| -------------- | ------ | ------------------------------------------------ |
| days           | int    | Quantidade de dias                               |
| type           | string | Tipo de contagem (ex: fixed, until)              |
| calendar_base  | string | Base de calendário (ex: workdays, calendar_365)  |

### Account Data

| Campo                        | Tipo   | Descrição                                                         |
| ---------------------------- | ------ | ----------------------------------------------------------------- |
| account_digit                | string | Dígito da conta bancária                                          |
| account_branch               | string | Número da agência bancária                                        |
| account_number               | string | Número da conta bancária                                          |
| financial_institution_code   | string | Código da instituição financeira                                  |
| financial_institution_ispb   | string | ISPB da instituição financeira (Sistema de Pagamentos Brasileiro) |

---

# Consulta de Posições em Cotas de Fundo

URL: /documentation/iaas/cotas_de_fundo/consulta_posicoes_cotas_de_fundo

---

:::warning Atenção
Este recurso está disponível apenas para integrações que exercem o papel de **Gestor**.
:::

Retorna, para cada fundo investido, **quanto o seu fundo tem aplicado**: o valor atualizado da posição em reais, a quantidade de cotas e a data da última marcação. Diferente da consulta de aplicações financeiras, que lista operação por operação, aqui a resposta já vem consolidada por série de emissão do fundo investido.

É a consulta indicada para saber o saldo aplicado em um **fundo de zeragem** — veja [Consultando a posição em um fundo de zeragem](#fundo-de-zeragem).

### Request

ENDPOINT /wallet/fund_class/FUND_CLASS_KEY/fund_quota_positions
MÉTODO GET

Onde `FUND_CLASS_KEY` é a chave da **sua** classe de fundo, aquela que detém as cotas.

#### Query Params

| Parâmetro             | Tipo   | Descrição                                                                                   | Obrigatório |
| --------------------- | ------ | ------------------------------------------------------------------------------------------- | ----------- |
| `page`                | int    | Número da página. Começa em `0`. Padrão: `0`.                                                | Não         |
| `limit`               | int    | Quantidade de registros por página. Máximo: `50`. Padrão: `10`.                              | Não         |
| `document_number`     | string | CNPJ da classe do fundo investido, com pontuação. Correspondência exata.                     | Não         |
| `internal_code`       | string | Código interno da série investida. Correspondência parcial.                                  | Não         |
| `internal_codes`      | lista  | Lista de códigos internos. Correspondência exata.                                            | Não         |
| `fund_class_name`     | string | Nome da classe do fundo investido. Correspondência parcial.                                  | Não         |
| `subclass_name`       | lista  | Senioridade da subclasse investida: `senior`, `mezzanine`, `subordinate`.                    | Não         |
| `investment_category` | lista  | Categoria do fundo investido: `fidc`, `fiagro`, `multi_market`, `fixed_income`, `private_equity`, `equity`, `real_state`. | Não |
| `asset_types`         | lista  | Tipo do ativo: `fidc_fund_quota`, `fiagro_fund_quota`, `multi_market_fund_quota`, `fixed_income_fund_quota`, `private_equity_fund_quota`. | Não |

```python title="Exemplo de chamada"
GET /wallet/fund_class/{fund_class_key}/fund_quota_positions?document_number=64.289.387/0001-20
```

:::note **Atenção**
Somente posições em ativos **ativos** entram no resultado. Cotas totalmente resgatadas ou baixadas não aparecem.
:::

### Response

STATUS 200

```json title='Response Body'
{
  "data": [
    {
      "quota_fund_class": {
        "name": "Série Única",
        "quota_fund_class_key": "UUID",
        "document_number": "00.000.000/0000-00",
        "fund_class_name": "Invested Fund Class Name",
        "fund_class_short_name": "Invested Fund Class Short Name",
        "investment_category": "fixed_income",
        "tax_classification": "long_term",
        "internal_code": "Internal Code",
        "subclass_name": "senior",
        "entity_category": "fund",
        "fund_term_target": "undetermined",
        "fund_regime": "open_ended",
        "operation_periods": {
          "redemption_request": {
            "payment": { "days": 0, "type": "fixed", "calendar_base": "workdays" },
            "quotation": { "days": 0, "type": "fixed", "calendar_base": "workdays" }
          }
        },
        "isin_code": "BR000000000"
      },
      "total_current_value": 1234567.89,
      "total_current_units": 1180000.0,
      "last_mtm_date": "YYYY-MM-DD",
      "lag": {
        "reference": "daily",
        "amount": 1
      }
    }
  ],
  "limit": 10,
  "page": 0,
  "is_last_page": true
}
```

### Response Fields

| Campo          | Tipo    | Descrição                                                        |
| -------------- | ------- | ---------------------------------------------------------------- |
| `data`         | array   | Lista de objetos de **[Posição](#posicao)**                      |
| `limit`        | int     | Limite de objetos recuperados por página                         |
| `page`         | int     | Número da página recuperada                                      |
| `is_last_page` | boolean | Indica se a página recuperada é a última                         |

### Posição {#posicao}

| Campo                 | Tipo   | Descrição                                                                                       |
| --------------------- | ------ | ------------------------------------------------------------------------------------------------ |
| `quota_fund_class`    | JSON   | Objeto de **[Fundo investido](#fundo-investido)**                                                |
| `total_current_value` | float  | **Valor atualizado da posição, em reais.** Soma do valor corrente dos ativos da série            |
| `total_current_units` | float  | Quantidade atual de cotas detidas na série                                                       |
| `last_mtm_date`       | string | Data da marcação **mais antiga** entre as posições agregadas, no formato `YYYY-MM-DD`            |
| `lag`                 | JSON   | Configuração de defasagem de precificação da série. Omitido quando a série não tem defasagem     |

:::caution **Atenção**

Diferente da API de Visibilidade de Caixa, onde os saldos vêm em centavos, aqui `total_current_value` é um número decimal em reais. Ex.: `1234.56` = R$ 1.234,56.

O `last_mtm_date` é o **mínimo** entre as datas de marcação das posições agregadas, e não a mais recente. Use-o para saber até quando o valor está garantidamente atualizado.
:::

### Fundo investido {#fundo-investido}

| Campo                    | Tipo   | Descrição                                                              |
| ------------------------ | ------ | ------------------------------------------------------------------------ |
| `name`                   | string | Nome da série de emissão investida                                       |
| `quota_fund_class_key`   | string | Chave única da série de emissão investida                                |
| `document_number`        | string | CNPJ da classe do fundo investido                                        |
| `fund_class_name`        | string | Nome da classe do fundo investido                                        |
| `fund_class_short_name`  | string | Nome curto da classe do fundo investido                                  |
| `investment_category`    | string | Categoria de investimento do fundo investido                             |
| `tax_classification`     | string | Classificação tributária do fundo investido                              |
| `internal_code`          | string | Código interno da série investida                                        |
| `subclass_name`          | string | Senioridade da subclasse investida                                       |
| `entity_category`        | string | Categoria da entidade investida                                          |
| `fund_term_target`       | string | Prazo alvo do fundo investido                                            |
| `fund_regime`            | string | Regime do fundo investido                                                |
| `operation_periods`      | JSON   | Prazos de cotização e liquidação das operações da série                  |
| `isin_code`              | string | Código ISIN da série. Omitido quando a série não tem ISIN cadastrado     |

## Consultando a posição em um fundo de zeragem {#fundo-de-zeragem}

Fundos de zeragem são fundos de liquidez usados para aplicar o caixa ocioso da sua classe, com aplicação e resgate por débito automático. A operação é feita pelos endpoints de [Criar Aplicação Financeira](/documentation/iaas/cotas_de_fundo/operacao_aplicacoes_financeiras) e [Criar Pedido de Resgate](/documentation/iaas/cotas_de_fundo/operacao_resgates), enviando o `source_account_key`.

Para consultar quanto a sua classe tem aplicado em um fundo de zeragem específico, filtre pelo CNPJ dele:

```python title="Posição no QI Cash III"
GET /wallet/fund_class/{fund_class_key}/fund_quota_positions?document_number=64.289.387/0001-20
```

O `total_current_value` da resposta é o saldo aplicado, em reais, na data indicada por `last_mtm_date`.

:::note **Atenção**
Uma mesma classe de fundo investida pode ter mais de uma série de emissão. Nesse caso a resposta traz **uma linha por série**, todas com o mesmo `document_number`, e o saldo total no fundo é a soma dos `total_current_value` retornados.
:::

Para conhecer o saldo em **conta bancária** — que é o caixa ainda não aplicado — use os endpoints de [Visibilidade de Caixa](/documentation/iaas/visibildade_de_caixa/get_accounts).

## Possíveis erros

STATUS 404

**Classe de fundo não encontrada**

```json
{
  "title": " Fund Class not Found",
  "description": "Fund Class with key {fund_class_key} was not found.",
  "translation": "A Fund Class com chave {fund_class_key} não foi encontrado.",
  "code": "WLT000001"
}
```

**Gestor não encontrado**

```json
{
  "title": "Not Found Manager",
  "description": "Manager with the key {manager_key} was not found.",
  "translation": "O gestor com a chave {manager_key} não foi encontrado.",
  "code": "WLT000066"
}
```

STATUS 403

**Classe de fundo não pertence ao gestor da integração**

```json
{
  "title": "Forbidden Agent",
  "description": "The agent with agent key ({agent_key}) can't access this resource.",
  "translation": "O agente com chave ({agent_key}) não pode acessar esse recurso.",
  "code": "WLT000098"
}
```

---

# Introdução

URL: /documentation/iaas/cotas_de_fundo/inicio

O sistema de Cotas de Fundo é uma solução que permite a compra, venda e consulta relacionado a cotas de outros fundos. Este módulo oferece funcionalidades essenciais para:

- Gerenciar aportes e resgates em outros fundos
- Criar operações

Esta documentação fornece uma visão detalhada sobre como utilizar o sistema de cotas de fundo, incluindo seus principais recursos e fluxos. Aqui você encontrará informações sobre:

- Compra, venda e consulta relacionadas a cotas de outros fundos
- Endpoints e payloads

Para começar a utilizar o sistema, navegue pelos tópicos disponíveis nesta documentação para entender melhor cada aspecto do módulo de cotas de fundo.

---

# Criar Aplicação Financeira

URL: /documentation/iaas/cotas_de_fundo/operacao_aplicacoes_financeiras

---
:::warning Atenção
Este recurso está disponível apenas para integrações que exercem o papel de Gestor.
:::

### Request

ENDPOINT /trade_fund_quota/fund_class/FUND_CLASS_KEY/financial_application
MÉTODO POST
STATUS 201

```json title='Request Body'
{
  "issuance_serie_key": "UUID",
  "source_account_key": "UUID",
  "amount": 0.00,
  "quotation_date": "YYYY-MM-DD",
  "payment_method": "string"
}
```

:::note **Atenção**.
Sempre que a operação for em uma série que o "payment_type" é "automatic_debit" (normalmente fundos de zeragem) é preciso enviar o source_account_key.

Esta operação não resultará em uma aplicação de fato, apenas na criação das expectativas e transferência para a conta de sua titularidade para que seja efetuado a operação na sequência.

Você pode recuperar essa chave através do endpoint: [`Recuperando Informações da Conta`](/documentation/iaas/visibildade_de_caixa/get_accounts)
Onde o source_account_key é a account_key da instituição onde você deseja realizar a aplicação.

Caso contrário não envie este campo.
:::

### Body params
| Campo                | Tipo   | Descrição                                        | Obrigatório |
| -------------------- | ------ | ------------------------------------------------ | ----------- |
| `issuance_serie_key` | string | Chave única de identificação da série de emissão | Sim         |
| `amount`             | float  | Valor da aplicação                               | Sim         |
| `source_account_key` | string | Chave da conta bancária de destino dos recursos  | Não         |
| `quotation_date`     | string | Data da cotização no formato `YYYY-MM-DD`        | Não         |
| `payment_method`     | string | Método de pagamento (`wire_transfer`, `pix`)     | Não         |

### Response
Response Body

```json
{
"amount": 0.00,
"financial_application_key": "UUID",
"asset_key": "UUID",
"quotation_date": "YYYY-MM-DD",
"status": "confirmed",
"issuance_serie": {
    "issuance_serie_key": "UUID",
    "name": "Invested Issuance Serie Name",
    "subclass_name": "Invested Sub Class Name",
    "serie": 1,
    "quota_calculation_method": "quota_value",
    "internal_code": "Internal Code",
    "fund_class_name": "Invested Fund Class Name",
    "fund_class_short_name": "Invested Fund Class short name",
    "fund_class_document_number": "00.000.000/0000-00",
    "minimum_share_capital": 0.0,
    "investment_category": "multi_market",
    "payment_type": "transfer",
    "account_data": {
        "account_digit": "0",
        "account_branch": "0001",
        "account_number": "12345",
        "financial_institution_code": "329",
        "financial_institution_ispb": "00000000"
    },
    "last_updated_date": "YYYY-MM-DD",
    "administrator": {
        "administrator_key": "UUID",
        "name": "Administrator Name",
        "document_number": "00.000.000/0000-00"
    },
    "operation_periods": {
        "redemption_request": {
            "payment": {
                "days": 1,
                "type": "until",
                "calendar_base": "calendar_365"
            },
            "quotation": {
                "days": 1,
                "type": "fixed",
                "calendar_base": "calendar_365"
            }
        },
        "amortization_request": {
            "payment": {
                "days": 0,
                "type": "fixed",
                "calendar_base": "workdays"
            },
            "quotation": {
                "days": 0,
                "type": "fixed",
                "calendar_base": "workdays"
            }
        },
        "financial_application": {
            "payment": {
                "days": 0,
                "type": "fixed",
                "calendar_base": "workdays"
            },
            "quotation": {
                "days": 0,
                "type": "fixed",
                "calendar_base": "workdays"
            }
        }
    },
    "isin_code": "BR000000000"
},
"fund_class": {
    "fund_class_key": "UUID",
    "name": "Fund Class Name",
    "short_name": "Fund Class Short Name",
    "document_number": "00.000.000/0000-00",
    "accounting_date": "YYYY-MM-DD",
    "distributor": {
        "name": "Distributor Name",
        "distributor_key": "UUID",
        "document_number": "00.000.000/0000-00"
    },
    "manager": {
        "manager_key": "UUID",
        "manager_name": "Manager Name",
        "document_number": "00.000.000/0000-00"
    }
}
}
```

# Aprovar Aplicação Financeira

---

### Request

ENDPOINT /trade_fund_quota/fund_class/FUND_CLASS_KEY/financial_application/FINANCIAL_APPLICATION_KEY
MÉTODO PUT
STATUS 202

```json title='Request Body'
{
  "status": "pending_payment"
}
```

### Body params
| Campo    | Tipo   | Descrição                                                            |
| -------- | ------ | -------------------------------------------------------------------- |
| `status` | string | Novo status do pedido de resgate. Veja abaixo os valores permitidos. |

### Response
Response Body

```json
{
"amount": 0.00,
"financial_application_key": "UUID",
"asset_key": "UUID",
"quotation_date": "YYYY-MM-DD",
"status": "confirmed",
"issuance_serie": {
    "issuance_serie_key": "UUID",
    "name": "Invested Issuance Serie Name",
    "subclass_name": "Invested Sub Class Name",
    "serie": 1,
    "quota_calculation_method": "quota_value",
    "internal_code": "Internal Code",
    "fund_class_name": "Invested Fund Class Name",
    "fund_class_short_name": "Invested Fund Class short name",
    "fund_class_document_number": "00.000.000/0000-00",
    "minimum_share_capital": 0.0,
    "investment_category": "multi_market",
    "payment_type": "transfer",
    "account_data": {
        "account_digit": "0",
        "account_branch": "0001",
        "account_number": "12345",
        "financial_institution_code": "329",
        "financial_institution_ispb": "00000000"
    },
    "last_updated_date": "YYYY-MM-DD",
    "administrator": {
        "administrator_key": "UUID",
        "name": "Administrator Name",
        "document_number": "00.000.000/0000-00"
    },
    "operation_periods": {
        "redemption_request": {
            "payment": {
                "days": 1,
                "type": "until",
                "calendar_base": "calendar_365"
            },
            "quotation": {
                "days": 1,
                "type": "fixed",
                "calendar_base": "calendar_365"
            }
        },
        "amortization_request": {
            "payment": {
                "days": 0,
                "type": "fixed",
                "calendar_base": "workdays"
            },
            "quotation": {
                "days": 0,
                "type": "fixed",
                "calendar_base": "workdays"
            }
        },
        "financial_application": {
            "payment": {
                "days": 0,
                "type": "fixed",
                "calendar_base": "workdays"
            },
            "quotation": {
                "days": 0,
                "type": "fixed",
                "calendar_base": "workdays"
            }
        }
    },
    "isin_code": "BR000000000"
},
"fund_class": {
    "fund_class_key": "UUID",
    "name": "Fund Class Name",
    "short_name": "Fund Class Short Name",
    "document_number": "00.000.000/0000-00",
    "accounting_date": "YYYY-MM-DD",
    "distributor": {
        "name": "Distributor Name",
        "distributor_key": "UUID",
        "document_number": "00.000.000/0000-00"
    },
    "manager": {
        "manager_key": "UUID",
        "manager_name": "Manager Name",
        "document_number": "00.000.000/0000-00"
    }
}
}
```

# Cancelar Aplicação Financeira

---

### Request

ENDPOINT /trade_fund_quota/fund_class/FUND_CLASS_KEY/financial_application/FINANCIAL_APPLICATION_KEY/cancel
MÉTODO PUT
STATUS 202

:::note **Atenção**.
Você poderá cancelar um pedido de aplicação caso ele esteja em algum destes status:
 - pending_manager_approval
 - pending_distributor_approval

Caso contrário você vai receber um erro com o seguinte código: TFQ000073
:::

### Response
Response Body

```json
{
"amount": 0.00,
"financial_application_key": "UUID",
"asset_key": "UUID",
"quotation_date": "YYYY-MM-DD",
"status": "confirmed",
"issuance_serie": {
    "issuance_serie_key": "UUID",
    "name": "Invested Issuance Serie Name",
    "subclass_name": "Invested Sub Class Name",
    "serie": 1,
    "quota_calculation_method": "quota_value",
    "internal_code": "Internal Code",
    "fund_class_name": "Invested Fund Class Name",
    "fund_class_short_name": "Invested Fund Class short name",
    "fund_class_document_number": "00.000.000/0000-00",
    "minimum_share_capital": 0.0,
    "investment_category": "multi_market",
    "payment_type": "transfer",
    "account_data": {
        "account_digit": "0",
        "account_branch": "0001",
        "account_number": "12345",
        "financial_institution_code": "329",
        "financial_institution_ispb": "00000000"
    },
    "last_updated_date": "YYYY-MM-DD",
    "administrator": {
        "administrator_key": "UUID",
        "name": "Administrator Name",
        "document_number": "00.000.000/0000-00"
    },
    "operation_periods": {
        "redemption_request": {
            "payment": {
                "days": 1,
                "type": "until",
                "calendar_base": "calendar_365"
            },
            "quotation": {
                "days": 1,
                "type": "fixed",
                "calendar_base": "calendar_365"
            }
        },
        "amortization_request": {
            "payment": {
                "days": 0,
                "type": "fixed",
                "calendar_base": "workdays"
            },
            "quotation": {
                "days": 0,
                "type": "fixed",
                "calendar_base": "workdays"
            }
        },
        "financial_application": {
            "payment": {
                "days": 0,
                "type": "fixed",
                "calendar_base": "workdays"
            },
            "quotation": {
                "days": 0,
                "type": "fixed",
                "calendar_base": "workdays"
            }
        }
    },
    "isin_code": "BR000000000"
},
"fund_class": {
    "fund_class_key": "UUID",
    "name": "Fund Class Name",
    "short_name": "Fund Class Short Name",
    "document_number": "00.000.000/0000-00",
    "accounting_date": "YYYY-MM-DD",
    "distributor": {
        "name": "Distributor Name",
        "distributor_key": "UUID",
        "document_number": "00.000.000/0000-00"
    },
    "manager": {
        "manager_key": "UUID",
        "manager_name": "Manager Name",
        "document_number": "00.000.000/0000-00"
    }
}
}
```

---

# Criar Pedido de Resgate

URL: /documentation/iaas/cotas_de_fundo/operacao_resgates

---
:::warning Atenção
Este recurso está disponível apenas para integrações que exercem o papel de Gestor.
:::

### Request

ENDPOINT /trade_fund_quota/fund_class/FUND_CLASS_KEY/redemption_request
MÉTODO POST
STATUS 201

```json title='Request Body'
{
  "issuance_serie_key": "UUID",
  "external_id": "UUID",
  "amount": 0.00,
  "source_account_key": "UUID",
  "redeem_all": false
}
```

:::note **Atenção**.
Sempre que a operação for em uma série que o "payment_type" é "automatic_debit" (normalmente fundos de zeragem) é preciso enviar o source_account_key.

Esta operação não resultará em um resgate de fato, apenas na criação das expectativas e transferência para a conta de sua titularidade para que seja efetuado a operação na sequência.

Você pode recuperar essa chave através do endpoint: [`Recuperando Informações da Conta`](/documentation/iaas/visibildade_de_caixa/get_accounts)
Onde o source_account_key é a account_key da instituição onde você deseja realizar o resgate.

Caso contrário não envie este campo.
:::

### Body params
| Campo                | Tipo    | Descrição                                                    | Obrigatório |
| -------------------- | ------- | ------------------------------------------------------------ | ----------- |
| `issuance_serie_key` | string  | Chave única da Série de Emissão                              | Sim         |
| `external_id`        | string  | Identificador externo único do pedido de resgate             | Sim         |
| `amount`             | float   | Valor bruto do resgate (ignorado se `redeem_all` for `true`) | Não         |
| `source_account_key` | string  | Chave da conta bancária de origem do fundo classe            | Não         |
| `redeem_all`         | boolean | Indica se o resgate deve ser total                           | Não         |

### Response
Response Body

```json
{
  "redemption_request_key": "UUID",
  "status": "confirmed",
  "quotation_date": "YYYY-MM-DD",
  "payment_date": "YYYY-MM-DD",
  "amount": 0.00,
  "issuance_serie": {
    "issuance_serie_key": "UUID",
    "name": "Issuance Serie Name",
    "subclass_name": "SUBORDINADA",
    "serie": 1,
    "quota_calculation_method": "quota_value",
    "internal_code": "Internal Code",
    "fund_class_name": "Fund Class Name",
    "fund_class_short_name": "Fund Class Short Name",
    "fund_class_document_number": "00.000.000/0000-00",
    "minimum_share_capital": 0.0,
    "investment_category": "fixed_income",
    "payment_type": "automatic_debit",
    "financial_institution_code": "341",
    "account_data": {
                "account_digit": "0",
                "account_branch": "0001",
                "account_number": "12345",
                "financial_institution_code": "329",
                "financial_institution_ispb": "00000000"
            },
    "last_updated_date": "YYYY-MM-DD",
    "administrator": {
      "administrator_key": "UUID",
      "name": "Administrator Name",
      "document_number": "00.000.000/0000-00"
    },
    "operation_periods": {
                "redemption_request": {
                    "payment": {
                        "days": 1,
                        "type": "until",
                        "calendar_base": "calendar_365"
                    },
                    "quotation": {
                        "days": 1,
                        "type": "fixed",
                        "calendar_base": "calendar_365"
                    }
                },
                "amortization_request": {
                    "payment": {
                        "days": 0,
                        "type": "fixed",
                        "calendar_base": "workdays"
                    },
                    "quotation": {
                        "days": 0,
                        "type": "fixed",
                        "calendar_base": "workdays"
                    }
                },
                "financial_application": {
                    "payment": {
                        "days": 0,
                        "type": "fixed",
                        "calendar_base": "workdays"
                    },
                    "quotation": {
                        "days": 0,
                        "type": "fixed",
                        "calendar_base": "workdays"
                    }
                }
            },
    "issuance_serie_data": {
      "name": "Issuance Serie Name",
      "serie": 1,
      "payment_type": "automatic_debit",
      "remuneration": "residual",
      "internal_code": "Internal Code",
      "subclass_name": "SUBORDINADA",
      "fund_class_name": "Fund Class Name",
      "issuance_serie_key": "UUID",
      "tax_classification": "long_term",
      "investment_category": "fixed_income",
      "fund_class_short_name": "Fund Class Short Name",
      "minimum_share_capital": 0.00,
      "quota_calculation_method": "quota_value",
      "financial_institution_code": "329",
      "fund_class_document_number": "00.000.000/0000-00",
      "administrator_document_number": "00.000.000/0000-00"
    }
  },
  "fund_class": {
    "fund_class_key": "UUID",
    "name": "Fund Class Name",
    "short_name": "Fund Class Short Name",
    "document_number": "00.000.000/0000-00",
    "accounting_date": "YYYY-MM-DD",
    "distributor": {
      "name": "Distributor Name",
      "distributor_key": "UUID",
      "document_number": "00.000.000/0000-00"
    },
    "manager": {
      "manager_key": "UUID",
      "manager_name": "Manager Name",
      "document_number": "00.000.000/0000-00"
    }
  }
}
```

# Aprovar um Pedido de Resgate

---

### Request

ENDPOINT /trade_fund_quota/fund_class/FUND_CLASS_KEY/redemption_request/REDEMPTION_REQUEST_KEY
MÉTODO PUT
STATUS 202

```json title='Request Body'
{
  "status": "pending_external_approval"
}

```

### Body params
| Campo    | Tipo   | Descrição                                                            |
| -------- | ------ | -------------------------------------------------------------------- |
| `status` | string | Novo status do pedido de resgate. Veja abaixo os valores permitidos. |

### Response
Response Body

```json
{
  "redemption_request_key": "UUID",
  "status": "pending_external_approval",
  "quotation_date": "YYYY-MM-DD",
  "payment_date": "YYYY-MM-DD",
  "amount": 0.00,
  "issuance_serie": {
    "issuance_serie_key": "UUID",
    "name": "Issuance Serie Name",
    "subclass_name": "SUBORDINADA",
    "serie": 1,
    "quota_calculation_method": "quota_value",
    "internal_code": "Internal Code",
    "fund_class_name": "Fund Class Name",
    "fund_class_short_name": "Fund Class Short Name",
    "fund_class_document_number": "00.000.000/0000-00",
    "minimum_share_capital": 0.0,
    "investment_category": "fixed_income",
    "payment_type": "automatic_debit",
    "financial_institution_code": "341",
    "account_data": {
                "account_digit": "0",
                "account_branch": "0001",
                "account_number": "12345",
                "financial_institution_code": "329",
                "financial_institution_ispb": "00000000"
            },
    "last_updated_date": "YYYY-MM-DD",
    "administrator": {
      "administrator_key": "UUID",
      "name": "Administrator Name",
      "document_number": "00.000.000/0000-00"
    },
    "operation_periods": {
                "redemption_request": {
                    "payment": {
                        "days": 1,
                        "type": "until",
                        "calendar_base": "calendar_365"
                    },
                    "quotation": {
                        "days": 1,
                        "type": "fixed",
                        "calendar_base": "calendar_365"
                    }
                },
                "amortization_request": {
                    "payment": {
                        "days": 0,
                        "type": "fixed",
                        "calendar_base": "workdays"
                    },
                    "quotation": {
                        "days": 0,
                        "type": "fixed",
                        "calendar_base": "workdays"
                    }
                },
                "financial_application": {
                    "payment": {
                        "days": 0,
                        "type": "fixed",
                        "calendar_base": "workdays"
                    },
                    "quotation": {
                        "days": 0,
                        "type": "fixed",
                        "calendar_base": "workdays"
                    }
                }
            },
    "issuance_serie_data": {
      "name": "Issuance Serie Name",
      "serie": 1,
      "payment_type": "automatic_debit",
      "remuneration": "residual",
      "internal_code": "Internal Code",
      "subclass_name": "SUBORDINADA",
      "fund_class_name": "Fund Class Name",
      "issuance_serie_key": "UUID",
      "tax_classification": "long_term",
      "investment_category": "fixed_income",
      "fund_class_short_name": "Fund Class Short Name",
      "minimum_share_capital": 0.00,
      "quota_calculation_method": "quota_value",
      "financial_institution_code": "329",
      "fund_class_document_number": "00.000.000/0000-00",
      "administrator_document_number": "00.000.000/0000-00"
    }
  },
  "fund_class": {
    "fund_class_key": "UUID",
    "name": "Fund Class Name",
    "short_name": "Fund Class Short Name",
    "document_number": "00.000.000/0000-00",
    "accounting_date": "YYYY-MM-DD",
    "distributor": {
      "name": "Distributor Name",
      "distributor_key": "UUID",
      "document_number": "00.000.000/0000-00"
    },
    "manager": {
      "manager_key": "UUID",
      "manager_name": "Manager Name",
      "document_number": "00.000.000/0000-00"
    }
  }
}
```

# Cancelar um Pedido de Resgate

---

### Request

ENDPOINT /trade_fund_quota/fund_class/FUND_CLASS_KEY/redemption_request/REDEMPTION_REQUEST_KEY/cancel
MÉTODO PUT
STATUS 202

:::note **Atenção**.
Você poderá cancelar um pedido de resgate caso ele esteja em algum destes status:
 - pending_manager_approval
 - pending_distributor_approval

Caso contrário você vai receber um erro com o seguinte código: TFQ000078
:::

### Response
Response Body

```json
{
  "redemption_request_key": "UUID",
  "status": "canceled",
  "quotation_date": "YYYY-MM-DD",
  "payment_date": "YYYY-MM-DD",
  "amount": 0.00,
  "issuance_serie": {
    "issuance_serie_key": "UUID",
    "name": "Issuance Serie Name",
    "subclass_name": "SUBORDINADA",
    "serie": 1,
    "quota_calculation_method": "quota_value",
    "internal_code": "Internal Code",
    "fund_class_name": "Fund Class Name",
    "fund_class_short_name": "Fund Class Short Name",
    "fund_class_document_number": "00.000.000/0000-00",
    "minimum_share_capital": 0.0,
    "investment_category": "fixed_income",
    "payment_type": "automatic_debit",
    "financial_institution_code": "341",
    "account_data": {
                "account_digit": "0",
                "account_branch": "0001",
                "account_number": "12345",
                "financial_institution_code": "329",
                "financial_institution_ispb": "00000000"
            },
    "last_updated_date": "YYYY-MM-DD",
    "administrator": {
      "administrator_key": "UUID",
      "name": "Administrator Name",
      "document_number": "00.000.000/0000-00"
    },
    "operation_periods": {
                "redemption_request": {
                    "payment": {
                        "days": 1,
                        "type": "until",
                        "calendar_base": "calendar_365"
                    },
                    "quotation": {
                        "days": 1,
                        "type": "fixed",
                        "calendar_base": "calendar_365"
                    }
                },
                "amortization_request": {
                    "payment": {
                        "days": 0,
                        "type": "fixed",
                        "calendar_base": "workdays"
                    },
                    "quotation": {
                        "days": 0,
                        "type": "fixed",
                        "calendar_base": "workdays"
                    }
                },
                "financial_application": {
                    "payment": {
                        "days": 0,
                        "type": "fixed",
                        "calendar_base": "workdays"
                    },
                    "quotation": {
                        "days": 0,
                        "type": "fixed",
                        "calendar_base": "workdays"
                    }
                }
            },
    "issuance_serie_data": {
      "name": "Issuance Serie Name",
      "serie": 1,
      "payment_type": "automatic_debit",
      "remuneration": "residual",
      "internal_code": "Internal Code",
      "subclass_name": "SUBORDINADA",
      "fund_class_name": "Fund Class Name",
      "issuance_serie_key": "UUID",
      "tax_classification": "long_term",
      "investment_category": "fixed_income",
      "fund_class_short_name": "Fund Class Short Name",
      "minimum_share_capital": 0.00,
      "quota_calculation_method": "quota_value",
      "financial_institution_code": "329",
      "fund_class_document_number": "00.000.000/0000-00",
      "administrator_document_number": "00.000.000/0000-00"
    }
  },
  "fund_class": {
    "fund_class_key": "UUID",
    "name": "Fund Class Name",
    "short_name": "Fund Class Short Name",
    "document_number": "00.000.000/0000-00",
    "accounting_date": "YYYY-MM-DD",
    "distributor": {
      "name": "Distributor Name",
      "distributor_key": "UUID",
      "document_number": "00.000.000/0000-00"
    },
    "manager": {
      "manager_key": "UUID",
      "manager_name": "Manager Name",
      "document_number": "00.000.000/0000-00"
    }
  }
}
```

---

# Consulta de despesas consolidadas

URL: /documentation/iaas/despesas/despesa_consolidada/consulta_despesas

Endpoints para consultar as despesas de uma classe de fundo. Existem dois modos de consulta: a **listagem paginada** de todas as despesas de uma classe de fundo, e a **consulta individual** de uma despesa específica.

:::tip Quando utilizar
Utilize estes endpoints para acompanhar o status das despesas cadastradas, verificar valores provisionados e consolidados, e consultar os dados de pagamento de cada despesa.
:::

## Listagem de despesas

Retorna a lista paginada de todas as despesas de uma classe de fundo, com suporte a diversos filtros.

### Request

ENDPOINT /expense/fund_class/{fund_class_key}/expenses
MÉTODO GET

### Query params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `page` | integer | opcional | Número da página (começa em 0). Padrão: `0`. |
| `limit` | integer | opcional | Quantidade de registros por página. Mínimo: `0`. Máximo: `100`. Padrão: `10`. |
| `reference_date` | string | opcional | Filtra despesas pela data de referência exata, no formato `YYYY-MM-DD`. |
| `from_end_deferral_date` | string | opcional | Filtra despesas com data de encerramento de diferimento maior ou igual à data informada, no formato `YYYY-MM-DD`. |
| `to_end_deferral_date` | string | opcional | Filtra despesas com data de encerramento de diferimento menor ou igual à data informada, no formato `YYYY-MM-DD`. |
| `status` | string | opcional | Filtra pelo status da despesa. Aceita múltiplos valores separados por vírgula (ex: `paid,consolidated`). Veja [enumeradores de `status`](#enumeradores-de-status). |
| `expense_type` | string | opcional | Filtra pelo tipo da despesa. Aceita múltiplos valores separados por vírgula (ex: `management_tax,custody_tax`). Veja [enumeradores de `type`](#enumeradores-de-type). |
| `expense_status_to_ignore` | string | opcional | Exclui da listagem despesas com o status informado. |
| `expense_type_to_ignore` | string | opcional | Exclui da listagem despesas com o tipo informado. |
| `ignore_paid_on_future` | boolean | opcional | Quando `true`, exclui despesas que já foram pagas mas com data de confirmação posterior à data de referência. |

```python title="Exemplo de chamada"
GET /expense/fund_class/{fund_class_key}/expenses?page=0&limit=10&status=consolidated,paid
```

### Response

STATUS 200

```json title="Response Body"
{
    "data": [
        {
            "expense_key": "3571e292-3a83-4011-904d-20ee963022ef",
            "fund_class": {
                "name": "Fundo de Investimento XYZ",
                "manager": {
                    "name": "Gestora ABC",
                    "manager_key": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
                    "document_number": "12.345.678/0001-90"
                },
                "fund_class_key": "c1d2e3f4-a5b6-7890-abcd-ef1234567890",
                "document_number": "98.765.432/0001-10",
                "accounting_date": "2025-06-10"
            },
            "status": "consolidated",
            "type": "management_tax",
            "reference_date": "2025-06-10",
            "start_deferral_date": "2025-06-01",
            "end_deferral_date": "2025-06-30",
            "consolidated_value": 1500.00,
            "provisioned_value": 1500.00,
            "recognized_value": 1500.00,
            "payment": null,
            "expense_datetime": "2025-06-01T00:00:00Z",
            "description": "Taxa de gestão referente ao mês de junho/2025",
            "payment_method": "transfer",
            "payment_date": "2025-06-30",
            "payment_confirmation": {
                "confirmation_date": "2025-06-30"
            }
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Lista de objetos de despesa. Veja [Atributos de cada despesa](#atributos-de-cada-despesa-objetos-dentro-de-data). |
| `page` | integer | Número da página atual. |
| `limit` | integer | Quantidade de registros por página. |
| `is_last_page` | boolean | Indica se esta é a última página de resultados. |

#### Atributos de cada despesa (objetos dentro de `data`)

| Campo | Tipo | Descrição |
|---|---|---|
| `expense_key` | string | Identificador único da despesa (UUID). |
| `fund_class` | object | Dados da classe de fundo à qual a despesa pertence. Veja [Atributos de `fund_class`](#atributos-de-fund_class). |
| `status` | string | Status atual da despesa. Veja [enumeradores de `status`](#enumeradores-de-status). |
| `type` | string | Tipo da despesa. Veja [enumeradores de `type`](#enumeradores-de-type). |
| `reference_date` | string | Data de referência da despesa no formato `YYYY-MM-DD`. |
| `start_deferral_date` | string | Data de início do diferimento no formato `YYYY-MM-DD`. |
| `end_deferral_date` | string | Data de encerramento do diferimento no formato `YYYY-MM-DD`. |
| `consolidated_value` | number | Valor consolidado da despesa. Pode ser `null` quando a despesa ainda não foi consolidada. |
| `provisioned_value` | number | Valor provisionado da despesa. Pode ser `null` quando ainda não há provisão. |
| `recognized_value` | number | Valor reconhecido da despesa. |
| `payment` | object | Dados do pagamento associado à despesa. Pode ser `null` quando não há pagamento vinculado. |
| `expense_datetime` | string | Data e hora de criação da despesa no formato ISO 8601 (ex: `2025-06-01T00:00:00Z`). |
| `description` | string | Descrição textual da despesa. |
| `payment_method` | string | Método de pagamento da despesa. Veja [enumeradores de `payment_method`](#enumeradores-de-payment_method). |
| `payment_date` | string | Data de pagamento no formato `YYYY-MM-DD`. Presente somente quando a despesa possui data de pagamento definida. |
| `payment_confirmation` | object | Dados de confirmação de pagamento. Presente somente quando o pagamento foi confirmado. Veja [Atributos de `payment_confirmation`](#atributos-de-payment_confirmation). |

#### Atributos de `fund_class`

| Campo | Tipo | Descrição |
|---|---|---|
| `name` | string | Nome da classe de fundo. |
| `fund_class_key` | string | Identificador único da classe de fundo (UUID). |
| `document_number` | string | CNPJ da classe de fundo. |
| `accounting_date` | string | Data de contabilização da classe de fundo no formato `YYYY-MM-DD`. |
| `manager` | object | Dados do gestor responsável. Veja [Atributos de `manager`](#atributos-de-manager). |

#### Atributos de `manager`

| Campo | Tipo | Descrição |
|---|---|---|
| `name` | string | Nome do gestor. |
| `manager_key` | string | Identificador único do gestor (UUID). |
| `document_number` | string | CNPJ do gestor. |

#### Atributos de `payment_confirmation`

| Campo | Tipo | Descrição |
|---|---|---|
| `confirmation_date` | string | Data de confirmação do pagamento no formato `YYYY-MM-DD`. |

---

## Consulta de despesa específica

Retorna os dados completos de uma despesa específica de uma classe de fundo.

### Request

ENDPOINT /expense/fund_class/{fund_class_key}/expense/{expense_key}
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Identificador único (UUID) da classe de fundo à qual a despesa pertence. |
| `expense_key` | string | Identificador único (UUID) da despesa a ser consultada. |

```python title="Exemplo de chamada"
GET /expense/fund_class/{fund_class_key}/expense/{expense_key}
```

### Response

STATUS 200

```json title="Response Body"
{
    "expense_key": "3571e292-3a83-4011-904d-20ee963022ef",
    "fund_class": {
        "name": "Fundo de Investimento XYZ",
        "manager": {
            "name": "Gestora ABC",
            "manager_key": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
            "document_number": "12.345.678/0001-90"
        },
        "fund_class_key": "c1d2e3f4-a5b6-7890-abcd-ef1234567890",
        "document_number": "98.765.432/0001-10",
        "accounting_date": "2025-06-10"
    },
    "status": "consolidated",
    "type": "management_tax",
    "reference_date": "2025-06-10",
    "start_deferral_date": "2025-06-01",
    "end_deferral_date": "2025-06-30",
    "consolidated_value": 1500.00,
    "provisioned_value": 1500.00,
    "recognized_value": 1500.00,
    "payment": null,
    "expense_datetime": "2025-06-01T00:00:00Z",
    "description": "Taxa de gestão referente ao mês de junho/2025",
    "payment_method": "transfer",
    "payment_date": "2025-06-30",
    "payment_confirmation": {
        "confirmation_date": "2025-06-30"
    }
}
```

### Atributos da resposta

A resposta possui a mesma estrutura de cada objeto do array `data` retornado pela [listagem de despesas](#atributos-de-cada-despesa-objetos-dentro-de-data).

---

## Possíveis erros

STATUS 404

**Despesa não encontrada**

O `expense_key` informado não corresponde a nenhuma despesa cadastrada para esta classe de fundo. Verifique se os identificadores estão corretos.

```json
{
  "title": "Expense not Found",
  "description": "The Expense with key {expense_key} was not found in Fund Class with key {fund_class_key}.",
  "translation": "A Despesa com a chave {expense_key} nao foi encontrada na classe de fundos com a chave {fund_class_key}.",
  "code": "EXP000010"
}
```

---

## Enumeradores de `status`

| Valor | Descrição |
|---|---|
| `created` | Despesa criada, ainda não iniciou o processo de provisionamento. |
| `in_provision` | Despesa em processo de provisionamento diário. |
| `on_demand_recognition` | Despesa com reconhecimento sob demanda (manual). |
| `consolidated` | Despesa consolidada — valor total reconhecido e pronto para pagamento. |
| `paid` | Despesa paga. |
| `canceled` | Despesa cancelada. |
| `completed` | Despesa encerrada. |

## Enumeradores de `type`

| Valor | Descrição |
|---|---|
| `administration_tax` | Taxa de administração. |
| `management_tax` | Taxa de gestão. |
| `performance_fee` | Taxa de performance. |
| `custody_tax` | Taxa de custódia. |
| `distribution_fee` | Taxa de distribuição. |
| `consulting_fee` | Taxa de consultoria. |
| `audit_tax` | Taxa de auditoria. |
| `cvm_tax` | Taxa CVM. |
| `cetip_tax` | Taxa CETIP. |
| `anbima_tax` | Taxa ANBIMA. |
| `selic_tax` | Taxa SELIC. |
| `notary` | Cartório. |
| `bank_account` | Conta bancária. |
| `bankslip_fee` | Taxa de boleto. |
| `sale_commission_tax` | Taxa de comissão de venda. |
| `certifier_fee` | Taxa de certificadora. |
| `rating_agency_fee` | Taxa de agência de rating. |
| `lawyer_fee` | Honorários advocatícios. |
| `bookkeeping_fee` | Taxa de escrituração. |
| `insurance_fee` | Taxa de seguro. |
| `collection_agent_fee` | Taxa de agente cobrador. |
| `servicing_fee` | Taxa de serviços. |
| `fund_structuring_fee` | Taxa de estruturação do fundo. |
| `credit_rights_registration_fee` | Taxa de registro de direitos creditórios. |
| `origination_fee` | Taxa de originação. |

## Enumeradores de `payment_method`

| Valor | Descrição |
|---|---|
| `transfer` | Transferência bancária. |
| `automatic_debit` | Débito automático. |
| `bank_slip` | Boleto bancário. |

---

# Atualização do Contrato

URL: /documentation/iaas/despesas/submissao_despesa/contrato/atualizacao

Edite os dados de um contrato enquanto ele ainda estiver no status `created`. Após a [submissão](/documentation/iaas/despesas/submissao_despesa/contrato/submissao), o contrato não pode mais ser alterado.

:::info
Somente contratos com status `created` podem ser atualizados.
:::

## Request

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}
MÉTODO PUT

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID) |
| `contract_key` | string | Chave única do contrato |

```json title="Request Body"
{
    "name": "Contrato de Auditoria - Exercício 2026 (revisado)",
    "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef",
    "expense_type": "audit_tax",
    "submission_nature": "manual_submission",
    "contract_value": 60000.00,
    "validity_date": "2026-12-31"
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `name` | string | opcional | Novo nome do contrato. Máximo de 255 caracteres. |
| `vendor_key` | string | opcional | Nova chave do fornecedor. |
| `expense_type` | string | opcional | Novo tipo de despesa. Ver [Tipos de despesa](/documentation/iaas/despesas/submissao_despesa/contrato/criacao#tipos-de-despesa). |
| `submission_nature` | string | opcional | Nova natureza de submissão: `manual_submission` ou `rebate`. |
| `contract_value` | number | opcional | Novo valor máximo do contrato. Mínimo: `0`. |
| `validity_date` | string | opcional | Nova data de validade no formato `YYYY-MM-DD`. |

## Response

STATUS 200

```json title="Response Body"
{
    "name": "Contrato de Auditoria - Exercício 2026 (revisado)",
    "contract_key": "contrato-auditoria-2026",
    "fund_class": {
        "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO",
        "manager": {
            "name": "EXEMPLO GESTORA LTDA",
            "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
            "document_number": "45.585.471/0001-47"
        },
        "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
        "document_number": "60.910.091/0001-24"
    },
    "vendor": {
        "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "name": "AUDITORES EXEMPLO S.A.",
        "document_number": "12.345.678/0001-90",
        "requires_invoice": "True"
    },
    "expense_type": "audit_tax",
    "status": "created",
    "contract_value": 60000.00,
    "validity_date": "2026-12-31",
    "submission_nature": "manual_submission"
}
```

Os atributos da resposta seguem a mesma estrutura da [criação do contrato](/documentation/iaas/despesas/submissao_despesa/contrato/criacao#atributos-da-resposta).

## Possíveis erros

STATUS 404

**Contrato não encontrado**

O par `fund_class_key` + `contract_key` não corresponde a nenhum contrato cadastrado.

```json
{
  "title": "Contract Not Found",
  "description": "Contract with key {contract_key} and fund class {fund_class_key} was not found.",
  "translation": "O contrato com chave {contract_key} do fundo {fund_class_key} não foi encontrado.",
  "code": "ESB000011"
}
```

STATUS 400

**Contrato não pode ser editado neste status**

O contrato não está no status `created` e não pode ser editado.

```json
{
  "title": "Cannot Update Contract In This Status",
  "description": "Contract {contract_key} cannot be updated with status {current_status}.",
  "translation": "O contrato {contract_key} não pode ser atualizado com o status {current_status}.",
  "code": "ESB000022"
}
```

## Próximos passos

1. **[Submeter o contrato](/documentation/iaas/despesas/submissao_despesa/contrato/submissao)** — envie o contrato para análise quando estiver pronto.
2. **[Cancelar o contrato](/documentation/iaas/despesas/submissao_despesa/contrato/cancelamento)** — cancele o contrato caso não seja mais necessário.

---

# Cancelamento do Contrato

URL: /documentation/iaas/despesas/submissao_despesa/contrato/cancelamento

Cancele um contrato que não seja mais necessário. O cancelamento é uma operação irreversível.

:::caution Atenção
Um contrato cancelado não pode ser reativado. Despesas que estejam sob um contrato cancelado também são impactadas. Certifique-se de que o cancelamento é realmente necessário antes de prosseguir.
:::

## Request

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/cancel
MÉTODO PUT

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID) |
| `contract_key` | string | Chave única do contrato |

Este endpoint não requer body na requisição.

## Response

STATUS 200

```json title="Response Body"
{
    "name": "Contrato de Auditoria - Exercício 2026",
    "contract_key": "contrato-auditoria-2026",
    "fund_class": {
        "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO",
        "manager": {
            "name": "EXEMPLO GESTORA LTDA",
            "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
            "document_number": "45.585.471/0001-47"
        },
        "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
        "document_number": "60.910.091/0001-24"
    },
    "vendor": {
        "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "name": "AUDITORES EXEMPLO S.A.",
        "document_number": "12.345.678/0001-90",
        "requires_invoice": "True"
    },
    "expense_type": "audit_tax",
    "status": "canceled",
    "contract_value": 50000.00,
    "validity_date": "2026-12-31",
    "submission_nature": "manual_submission"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `status` | string | Novo status do contrato. Sempre retorna `canceled` após o cancelamento bem-sucedido. |

Os demais campos seguem a mesma estrutura da [criação do contrato](/documentation/iaas/despesas/submissao_despesa/contrato/criacao#atributos-da-resposta).

## Possíveis erros

STATUS 404

**Contrato não encontrado**

O par `fund_class_key` + `contract_key` não corresponde a nenhum contrato cadastrado.

```json
{
  "title": "Contract Not Found",
  "description": "Contract with key {contract_key} and fund class {fund_class_key} was not found.",
  "translation": "O contrato com chave {contract_key} do fundo {fund_class_key} não foi encontrado.",
  "code": "ESB000011"
}
```

STATUS 400

**Contrato já em status final**

O contrato já está em um status final (`approved` ou `rejected`) e não pode ser cancelado.

```json
{
  "title": "Already In Final Contract Status",
  "description": "The contract {contract_key} is already in a final status: {current_status}.",
  "translation": "O contrato {contract_key} já está em um status final: {current_status}.",
  "code": "ESB000020"
}
```

---

# Criação do Contrato

URL: /documentation/iaas/despesas/submissao_despesa/contrato/criacao

Este é o **primeiro passo** do fluxo de submissão de despesas pelo agente integrador. O contrato define a relação comercial entre o fundo e um fornecedor, estabelecendo o tipo de despesa e as condições de pagamento.

:::info Pré-requisitos
Antes de criar um contrato, você precisa ter em mãos:
- `fund_class_key` — chave única do fundo, fornecida pela QI Tech
- `vendor_key` — chave do fornecedor cadastrado. Consulte a [listagem de fornecedores](/documentation/iaas/despesas/submissao_despesa/fornecedor/listagem) para obtê-la

Para mais detalhes sobre o fluxo completo, consulte a [página de introdução](/documentation/iaas/despesas/submissao_despesa/inicio).
:::

:::caution Atenção
O campo `submission_nature = rebate` só pode ser utilizado em conjunto com `expense_type = distribution_fee`. Para todos os demais tipos de despesa, use `submission_nature = manual_submission`.
:::

## Request

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract
MÉTODO POST

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID) |

```json title="Request Body"
{
    "name": "Contrato de Auditoria - Exercício 2026",
    "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef",
    "expense_type": "audit_tax",
    "submission_nature": "manual_submission",
    "contract_value": 50000.00,
    "validity_date": "2026-12-31",
    "contract_key": "contrato-auditoria-2026"
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `name` | string | obrigatório | Nome do contrato. Máximo de 255 caracteres. |
| `vendor_key` | string | obrigatório | Chave única do fornecedor (máximo 255 caracteres). |
| `expense_type` | string | obrigatório | Tipo de despesa. Ver [Tipos de despesa](#tipos-de-despesa). |
| `submission_nature` | string | obrigatório | Natureza de submissão: `manual_submission` ou `rebate`. |
| `contract_value` | number | opcional | Valor máximo do contrato. Quando informado, a soma das despesas não pode exceder este valor. Mínimo: `0`. |
| `validity_date` | string | opcional | Data de validade do contrato no formato `YYYY-MM-DD`. Após esta data, nenhuma nova despesa pode ser criada. |
| `contract_key` | string | opcional | Identificador personalizado do contrato no sistema do parceiro. Máximo de 255 caracteres. Quando não informado, um UUID é gerado automaticamente. |

### Tipos de despesa

| Valor | Descrição |
|---|---|
| `cvm_tax` | Taxa CVM |
| `cetip_tax` | Taxa CETIP |
| `anbima_tax` | Taxa ANBIMA |
| `notary` | Cartório |
| `audit_tax` | Taxa de auditoria |
| `administration_tax` | Taxa de administração |
| `management_tax` | Taxa de gestão |
| `bank_account` | Conta bancária |
| `selic_tax` | Taxa SELIC |
| `consulting_fee` | Honorários de consultoria |
| `custody_tax` | Taxa de custódia |
| `performance_fee` | Taxa de performance |
| `bankslip_fee` | Taxa de boleto |
| `sale_commission_tax` | Comissão de venda |
| `certifier_fee` | Honorários de certificador |
| `rating_agency_fee` | Taxa de agência de rating |
| `lawyer_fee` | Honorários advocatícios |
| `bookkeeping_fee` | Taxa de escrituração |
| `distribution_fee` | Taxa de distribuição |
| `insurance_fee` | Taxa de seguro |
| `collection_agent_fee` | Honorários de agente de cobrança |
| `servicing_fee` | Taxa de serviços |
| `fund_structuring_fee` | Taxa de estruturação do fundo |
| `credit_rights_registration_fee` | Taxa de registro de direitos creditórios |
| `origination_fee` | Taxa de originação |

## Response

STATUS 201

```json title="Response Body"
{
    "name": "Contrato de Auditoria - Exercício 2026",
    "contract_key": "contrato-auditoria-2026",
    "fund_class": {
        "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO",
        "manager": {
            "name": "EXEMPLO GESTORA LTDA",
            "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
            "document_number": "45.585.471/0001-47"
        },
        "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
        "document_number": "60.910.091/0001-24"
    },
    "vendor": {
        "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "name": "AUDITORES EXEMPLO S.A.",
        "document_number": "12.345.678/0001-90",
        "requires_invoice": "True"
    },
    "expense_type": "audit_tax",
    "status": "created",
    "contract_value": 50000.00,
    "validity_date": "2026-12-31",
    "submission_nature": "manual_submission"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `name` | string | Nome do contrato. |
| `contract_key` | string | Chave única do contrato. Guarde este valor para as próximas etapas. |
| `fund_class` | object | Dados do fundo associado. Veja [Atributos de `fund_class`](#atributos-de-fund_class). |
| `vendor` | object | Dados do fornecedor. Veja [Atributos de `vendor`](#atributos-de-vendor). |
| `expense_type` | string | Tipo de despesa do contrato. |
| `status` | string | Status inicial do contrato. Sempre retorna `created`. |
| `contract_value` | number | Valor máximo do contrato, ou `null` quando não informado. |
| `validity_date` | string | Data de validade no formato `YYYY-MM-DD`, ou `null` quando não informada. |
| `submission_nature` | string | Natureza de submissão do contrato. |

#### Atributos de `fund_class`

| Campo | Tipo | Descrição |
|---|---|---|
| `name` | string | Nome do fundo. |
| `manager` | object | Dados do gestor do fundo. |
| `manager.name` | string | Nome do gestor. |
| `manager.manager_key` | string | Chave única do gestor (UUID). |
| `manager.document_number` | string | CNPJ do gestor. |
| `fund_class_key` | string | Chave única do fundo (UUID). |
| `document_number` | string | CNPJ do fundo. |

#### Atributos de `vendor`

| Campo | Tipo | Descrição |
|---|---|---|
| `vendor_key` | string | Chave única do fornecedor. |
| `name` | string | Nome do fornecedor. |
| `document_number` | string | CPF ou CNPJ do fornecedor. |
| `requires_invoice` | string | Indica se o fornecedor exige nota fiscal (`"True"` ou `"False"`). |

## Possíveis erros

STATUS 404

**Fundo não encontrado**

A `fund_class_key` informada na URL não corresponde a nenhum fundo cadastrado.

```json
{
  "title": "Fund Class Not Found",
  "description": "Fund Class with key {fund_class_key} was not found.",
  "translation": "O Fundo com chave {fund_class_key} nao foi encontrado.",
  "code": "ESB000005"
}
```

**Fornecedor não encontrado**

A `vendor_key` informada no body não corresponde a nenhum fornecedor cadastrado.

```json
{
  "title": "Vendor Not Found",
  "description": "Vendor with key {vendor_key} was not found.",
  "translation": "O fornecedor com a chave {vendor_key} nao foi encontrado.",
  "code": "ESB000008"
}
```

STATUS 409

**Contract key duplicada**

Já existe um contrato com a `contract_key` informada neste fundo. Use um identificador diferente ou omita o campo para gerar um UUID automaticamente.

```json
{
  "title": "Contract Key Already Exists",
  "description": "A Contract with key {contract_key} already exists.",
  "translation": "Um contrato com a chave {contract_key} já existe.",
  "code": "ESB000012"
}
```

STATUS 400

**Tipo de despesa incompatível com a natureza de submissão**

O valor `rebate` em `submission_nature` só é válido quando `expense_type` é `distribution_fee`.

```json
{
  "title": "Invalid Expense Type",
  "description": "The expense type {expense_type} is not valid for submission nature {submission_nature}.",
  "translation": "O tipo de despesa {expense_type} não é válido para a natureza de submissão {submission_nature}.",
  "code": "ESB000031"
}
```

## Próximos passos

Após criar o contrato, o fluxo continua com:

1. **[Submissão do contrato](/documentation/iaas/despesas/submissao_despesa/contrato/submissao)** — envie o contrato para análise e aprovação pela QI Tech.
2. **[Atualização do contrato](/documentation/iaas/despesas/submissao_despesa/contrato/atualizacao)** — edite os dados do contrato enquanto ele ainda estiver em status `created`.

---

# Listagem de Contratos

URL: /documentation/iaas/despesas/submissao_despesa/contrato/listagem

Liste os contratos de um fundo com filtros opcionais por tipo de despesa, status ou natureza de submissão.

## Request

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contracts
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID) |

### Query params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `expense_type` | string | opcional | Filtra por tipo de despesa. Ver [tipos de despesa](/documentation/iaas/despesas/submissao_despesa/contrato/criacao#tipos-de-despesa). |
| `status` | string | opcional | Filtra por status do contrato (`created`, `pending_adm_approval`, `approved`, `rejected`, `canceled`). |
| `submission_nature` | string | opcional | Filtra por natureza: `manual_submission` ou `rebate`. |
| `limit` | integer | opcional | Número de itens por página. Mínimo: `1`. Máximo: `1000`. Padrão: `10`. |
| `page` | integer | opcional | Número da página (base zero). Padrão: `0`. |

## Response

STATUS 200

```json title="Response Body"
{
    "data": [
        {
            "name": "Contrato de Auditoria - Exercício 2026",
            "contract_key": "contrato-auditoria-2026",
            "fund_class": {
                "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO",
                "manager": {
                    "name": "EXEMPLO GESTORA LTDA",
                    "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
                    "document_number": "45.585.471/0001-47"
                },
                "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
                "document_number": "60.910.091/0001-24"
            },
            "vendor": {
                "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef",
                "name": "AUDITORES EXEMPLO S.A.",
                "document_number": "12.345.678/0001-90",
                "requires_invoice": "True"
            },
            "expense_type": "audit_tax",
            "status": "approved",
            "contract_value": 50000.00,
            "validity_date": "2026-12-31",
            "submission_nature": "manual_submission"
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Lista de contratos. Cada item segue a estrutura da [consulta individual](/documentation/iaas/despesas/submissao_despesa/contrato/recuperacao). |
| `limit` | integer | Número de itens por página utilizado na consulta. |
| `page` | integer | Número da página atual. |
| `is_last_page` | boolean | Indica se esta é a última página de resultados. |

## Possíveis erros

STATUS 404

**Fundo não encontrado**

A `fund_class_key` informada na URL não corresponde a nenhum fundo cadastrado.

```json
{
  "title": "Fund Class Not Found",
  "description": "Fund Class with key {fund_class_key} was not found.",
  "translation": "O Fundo com chave {fund_class_key} nao foi encontrado.",
  "code": "ESB000005"
}
```

---

# Consulta de Contrato

URL: /documentation/iaas/despesas/submissao_despesa/contrato/recuperacao

Recupere os dados e o status atual de um contrato específico.

## Request

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID) |
| `contract_key` | string | Chave única do contrato |

## Response

STATUS 200

```json title="Response Body"
{
    "name": "Contrato de Auditoria - Exercício 2026",
    "contract_key": "contrato-auditoria-2026",
    "fund_class": {
        "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO",
        "manager": {
            "name": "EXEMPLO GESTORA LTDA",
            "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
            "document_number": "45.585.471/0001-47"
        },
        "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
        "document_number": "60.910.091/0001-24"
    },
    "vendor": {
        "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "name": "AUDITORES EXEMPLO S.A.",
        "document_number": "12.345.678/0001-90",
        "requires_invoice": "True"
    },
    "expense_type": "audit_tax",
    "status": "approved",
    "contract_value": 50000.00,
    "validity_date": "2026-12-31",
    "submission_nature": "manual_submission"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `name` | string | Nome do contrato. |
| `contract_key` | string | Chave única do contrato. |
| `fund_class` | object | Dados do fundo associado. |
| `vendor` | object | Dados do fornecedor. |
| `expense_type` | string | Tipo de despesa do contrato. |
| `status` | string | Status atual do contrato. Ver tabela de [status do contrato](/documentation/iaas/despesas/submissao_despesa/inicio#status-do-contrato). |
| `contract_value` | number | Valor máximo do contrato, ou `null` quando não informado. |
| `validity_date` | string | Data de validade no formato `YYYY-MM-DD`, ou `null` quando não informada. |
| `submission_nature` | string | Natureza de submissão do contrato. |

## Possíveis erros

STATUS 404

**Contrato não encontrado**

O par `fund_class_key` + `contract_key` não corresponde a nenhum contrato cadastrado.

```json
{
  "title": "Contract Not Found",
  "description": "Contract with key {contract_key} and fund class {fund_class_key} was not found.",
  "translation": "O contrato com chave {contract_key} do fundo {fund_class_key} não foi encontrado.",
  "code": "ESB000011"
}
```

---

# Submissão do Contrato

URL: /documentation/iaas/despesas/submissao_despesa/contrato/submissao

Após criar o contrato, submeta-o para análise da QI Tech. A submissão encaminha o contrato para revisão manual e muda seu status para `pending_adm_approval`.

:::caution Atenção
Após a submissão, o contrato não pode mais ser editado. Verifique todos os dados antes de prosseguir. Caso precise fazer alterações, utilize o endpoint de [atualização](/documentation/iaas/despesas/submissao_despesa/contrato/atualizacao) enquanto o status ainda for `created`.
:::

## Request

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/submit
MÉTODO PUT

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID) |
| `contract_key` | string | Chave única do contrato |

Este endpoint não requer body na requisição.

## Response

STATUS 200

```json title="Response Body"
{
    "name": "Contrato de Auditoria - Exercício 2026",
    "contract_key": "contrato-auditoria-2026",
    "fund_class": {
        "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO",
        "manager": {
            "name": "EXEMPLO GESTORA LTDA",
            "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
            "document_number": "45.585.471/0001-47"
        },
        "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
        "document_number": "60.910.091/0001-24"
    },
    "vendor": {
        "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "name": "AUDITORES EXEMPLO S.A.",
        "document_number": "12.345.678/0001-90",
        "requires_invoice": "True"
    },
    "expense_type": "audit_tax",
    "status": "pending_adm_approval",
    "contract_value": 50000.00,
    "validity_date": "2026-12-31",
    "submission_nature": "manual_submission"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `status` | string | Novo status do contrato. Sempre retorna `pending_adm_approval` após a submissão bem-sucedida. |

Os demais campos seguem a mesma estrutura da [criação do contrato](/documentation/iaas/despesas/submissao_despesa/contrato/criacao#atributos-da-resposta).

## Possíveis erros

STATUS 404

**Contrato não encontrado**

O par `fund_class_key` + `contract_key` não corresponde a nenhum contrato cadastrado.

```json
{
  "title": "Contract Not Found",
  "description": "Contract with key {contract_key} and fund class {fund_class_key} was not found.",
  "translation": "O contrato com chave {contract_key} do fundo {fund_class_key} não foi encontrado.",
  "code": "ESB000011"
}
```

STATUS 400

**Transição de status inválida**

O contrato não pode ser submetido a partir do status atual. A submissão só é permitida quando o contrato está no status `created`.

```json
{
  "title": "Invalid Contract Status Change",
  "description": "It is not possible to change the contract status from {current_status} to {new_status}.",
  "translation": "Não é possível alterar o status do contrato de {current_status} para {new_status}.",
  "code": "ESB000013"
}
```

## Próximos passos

Após submeter o contrato, aguarde a análise da QI Tech. Enquanto isso, você pode:

1. **[Consultar o contrato](/documentation/iaas/despesas/submissao_despesa/contrato/recuperacao)** — acompanhe o status do contrato.
2. **[Criar despesas](/documentation/iaas/despesas/submissao_despesa/despesa/criacao)** — despesas podem ser criadas mesmo enquanto o contrato aguarda aprovação (exceto contratos com status `rejected`).

---

# Atualização da Despesa

URL: /documentation/iaas/despesas/submissao_despesa/despesa/atualizacao

Edite os dados de uma despesa enquanto ela ainda estiver no status `created`. Após a submissão ou após a criação com documentos (status `pending_adm_approval`), a despesa não pode mais ser alterada.

:::info
Somente despesas com status `created` podem ser atualizadas.
:::

## Request

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense/{expense_key}
MÉTODO PUT

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID) |
| `contract_key` | string | Chave única do contrato |
| `expense_key` | string | Chave única da despesa (UUID) |

```json title="Request Body"
{
    "payment_method": "transfer",
    "start_deferral_date": "2026-06-02",
    "end_deferral_date": "2026-06-30",
    "description": "Honorários de auditoria - 1º semestre 2026 (corrigido)",
    "payment_value": 16000.00,
    "payment_date": "2026-07-01",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90"
        },
        "target_account": {
            "account_number": "123456",
            "account_branch": "0001",
            "account_digit": "0",
            "financial_institution_code": "341"
        },
        "transfer_type": "wire_transfer",
        "source_account": {
            "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e"
        }
    }
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `payment_method` | string | opcional | Método de pagamento: `transfer`, `automatic_debit` ou `bank_slip`. |
| `start_deferral_date` | string | opcional | Data início da competência no formato `YYYY-MM-DD`. Deve ser dia útil. |
| `end_deferral_date` | string | opcional | Data fim da competência no formato `YYYY-MM-DD`. Deve ser dia útil. |
| `description` | string | opcional | Nova descrição da despesa. Máximo de 200 caracteres. |
| `payment_value` | number | opcional | Novo valor da despesa. Mínimo: `0`. |
| `payment_date` | string | opcional | Nova data de pagamento no formato `YYYY-MM-DD`. Deve ser dia útil. |
| `payment` | object | opcional | Novos dados do pagamento. Mesma estrutura da [criação da despesa](/documentation/iaas/despesas/submissao_despesa/despesa/criacao#atributos-de-payment). |

## Response

STATUS 200

A resposta segue a mesma estrutura da [criação da despesa](/documentation/iaas/despesas/submissao_despesa/despesa/criacao#atributos-da-resposta), com os campos atualizados.

## Possíveis erros

STATUS 404

**Despesa não encontrada**

O conjunto `fund_class_key` + `contract_key` + `expense_key` não corresponde a nenhuma despesa cadastrada.

```json
{
  "title": "Expense Not Found",
  "description": "Expense with key {expense_key} was not found.",
  "translation": "A despesa com chave {expense_key} não foi encontrada.",
  "code": "ESB000016"
}
```

STATUS 400

**Despesa não pode ser editada neste status**

A despesa não está no status `created` e não pode ser editada.

```json
{
  "title": "Cannot Update Expense In This Status",
  "description": "Expense {expense_key} cannot be updated with status {current_status}.",
  "translation": "A despesa {expense_key} não pode ser atualizada com o status {current_status}.",
  "code": "ESB000023"
}
```

## Próximos passos

1. **[Submeter a despesa](/documentation/iaas/despesas/submissao_despesa/despesa/submissao)** — encaminhe para análise quando estiver pronto.
2. **[Cancelar a despesa](/documentation/iaas/despesas/submissao_despesa/despesa/cancelamento)** — cancele caso não seja mais necessária.

---

# Cancelamento da Despesa

URL: /documentation/iaas/despesas/submissao_despesa/despesa/cancelamento

Cancele uma despesa que não seja mais necessária. O cancelamento é uma operação irreversível.

:::caution Atenção
Uma despesa cancelada não pode ser reativada. Certifique-se de que o cancelamento é realmente necessário antes de prosseguir. Despesas nos status `approved` ou `rejected` não podem ser canceladas.
:::

## Request

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense/{expense_key}/cancel
MÉTODO PUT

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID) |
| `contract_key` | string | Chave única do contrato |
| `expense_key` | string | Chave única da despesa (UUID) |

Este endpoint não requer body na requisição.

## Response

STATUS 200

```json title="Response Body"
{
    "expense_key": "7f3e9a1b-2c4d-5e6f-8901-abcdef234567",
    "contract_key": "contrato-auditoria-2026",
    "status": "canceled",
    "payment_method": "transfer",
    "start_deferral_date": "2026-06-02",
    "end_deferral_date": "2026-06-30",
    "description": "Honorários de auditoria referente ao 1º semestre de 2026",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90"
        },
        "target_account": {
            "account_number": "123456",
            "account_branch": "0001",
            "account_digit": "0",
            "financial_institution_code": "341"
        }
    },
    "payment_value": 15000.00,
    "payment_date": "2026-07-01",
    "rebate_expense_key": null,
    "fund_class": {
        "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO",
        "manager": {
            "name": "EXEMPLO GESTORA LTDA",
            "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
            "document_number": "45.585.471/0001-47"
        },
        "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
        "document_number": "60.910.091/0001-24"
    }
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `status` | string | Novo status da despesa. Sempre retorna `canceled` após o cancelamento bem-sucedido. |

Os demais campos seguem a mesma estrutura da [criação da despesa](/documentation/iaas/despesas/submissao_despesa/despesa/criacao#atributos-da-resposta).

## Possíveis erros

STATUS 404

**Despesa não encontrada**

O conjunto `fund_class_key` + `contract_key` + `expense_key` não corresponde a nenhuma despesa cadastrada.

```json
{
  "title": "Expense Not Found",
  "description": "Expense with key {expense_key} was not found.",
  "translation": "A despesa com chave {expense_key} não foi encontrada.",
  "code": "ESB000016"
}
```

STATUS 400

**Despesa já em status final**

A despesa já está em um status final (`approved` ou `rejected`) e não pode ser cancelada.

```json
{
  "title": "Already In Final Expense Status",
  "description": "Expense {expense_key} is already in a final status: {current_status}.",
  "translation": "A despesa {expense_key} já está em um status final: {current_status}.",
  "code": "ESB000021"
}
```

---

# Criação da Despesa

URL: /documentation/iaas/despesas/submissao_despesa/despesa/criacao

Crie uma despesa individual sob um contrato existente. A despesa contém os dados de pagamento, o período de competência e os documentos comprobatórios.

:::info Pré-requisitos
- O contrato referenciado deve existir e não pode estar no status `rejected`.
- As datas (`payment_date`, `start_deferral_date`, `end_deferral_date`) devem ser **dias úteis** (sem fins de semana ou feriados nacionais).
- `start_deferral_date` não pode ser posterior a `end_deferral_date`.
- Quando o contrato possui `contract_value`, a soma dos valores de todas as despesas não pode ultrapassar esse limite.
:::

:::tip Atalho para submissão
Se os documentos comprobatórios forem incluídos no campo `documents` durante a criação, a despesa é **automaticamente encaminhada para revisão** (status `pending_adm_approval`), sem necessidade de chamar o endpoint de submissão separadamente.
:::

## Request

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense
MÉTODO POST

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID) |
| `contract_key` | string | Chave única do contrato |

```json title="Request Body — Pagamento por transferência (TED/PIX)"
{
    "payment_method": "transfer",
    "start_deferral_date": "2026-06-02",
    "end_deferral_date": "2026-06-30",
    "description": "Honorários de auditoria referente ao 1º semestre de 2026",
    "payment_value": 15000.00,
    "payment_date": "2026-07-01",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90"
        },
        "target_account": {
            "account_number": "123456",
            "account_branch": "0001",
            "account_digit": "0",
            "financial_institution_code": "341"
        },
        "transfer_type": "wire_transfer",
        "source_account": {
            "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e"
        }
    },
    "documents": [
        {
            "name": "NF-e 001234",
            "document_type": "invoice",
            "document_b64": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoK..."
        }
    ]
}
```

```json title="Request Body — Pagamento por boleto"
{
    "payment_method": "bank_slip",
    "start_deferral_date": "2026-06-02",
    "end_deferral_date": "2026-06-30",
    "description": "Taxa de custódia - junho/2026",
    "payment_value": 3500.00,
    "payment_date": "2026-07-01",
    "payment": {
        "target": {
            "name": "CUSTODIANTE EXEMPLO S.A.",
            "document_number": "98.765.432/0001-10"
        },
        "bank_slip": {
            "digitable_line": "34191.09008 63521.510047 91020.150008 1 10010000035000"
        },
        "source_account": {
            "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e"
        }
    }
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `payment_method` | string | obrigatório | Método de pagamento: `transfer`, `automatic_debit` ou `bank_slip`. |
| `start_deferral_date` | string | obrigatório | Data início da competência no formato `YYYY-MM-DD`. Deve ser dia útil. |
| `end_deferral_date` | string | obrigatório | Data fim da competência no formato `YYYY-MM-DD`. Deve ser dia útil e ≥ `start_deferral_date`. |
| `description` | string | obrigatório | Descrição da despesa. Máximo de 200 caracteres. |
| `payment_value` | number | obrigatório | Valor da despesa. Mínimo: `0`. |
| `payment_date` | string | obrigatório | Data de pagamento no formato `YYYY-MM-DD`. Deve ser dia útil. |
| `payment` | object | obrigatório | Dados do pagamento. Ver [Atributos de `payment`](#atributos-de-payment). |
| `documents` | array | opcional | Lista de documentos comprobatórios. Quando informado, a despesa é automaticamente encaminhada para revisão. Ver [Atributos de `documents`](#atributos-de-documents). |

#### Atributos de `payment`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `target` | object | obrigatório | Dados do beneficiário. |
| `target.name` | string | obrigatório | Nome do beneficiário. |
| `target.document_number` | string | obrigatório | CPF (`###.###.###-##`) ou CNPJ (`##.###.###/####-##`) do beneficiário. |
| `target_account` | object | condicional | Dados da conta bancária de destino. Obrigatório para `payment_method = transfer`. |
| `target_account.account_number` | string | obrigatório | Número da conta (1-20 dígitos, não pode ser todos zeros). |
| `target_account.account_branch` | string | obrigatório | Agência (exatamente 4 dígitos, não pode ser todos zeros). |
| `target_account.account_digit` | string | obrigatório | Dígito verificador (1 dígito). |
| `target_account.financial_institution_code` | string | obrigatório | Código do banco (exatamente 3 dígitos, não pode ser todos zeros). |
| `target_account.financial_institution_ispb` | string | opcional | ISPB do banco (exatamente 8 dígitos). |
| `target_account.account_type` | string | opcional | Tipo da conta bancária. |
| `transfer_type` | string | condicional | Tipo de transferência: `pix` ou `wire_transfer`. Necessário para `payment_method = transfer`. |
| `target_pix_key` | string | condicional | Chave PIX do beneficiário (1-77 caracteres). Obrigatório quando `transfer_type = pix`. |
| `pix_qrcode` | string | opcional | QR Code PIX (1-255 caracteres). |
| `bank_slip` | object | condicional | Dados do boleto. Obrigatório para `payment_method = bank_slip`. |
| `bank_slip.digitable_line` | string | obrigatório | Linha digitável do boleto (47-48 caracteres). |
| `source_account` | object | opcional | Conta de débito de origem do pagamento. |
| `source_account.account_key` | string | obrigatório | Chave única da conta de origem (UUID). |
| `conciliation_metadata` | object | opcional | Metadados de conciliação. |
| `conciliation_metadata.fee_type` | string | opcional | Tipo de taxa para conciliação. |
| `conciliation_metadata.conciliation_value` | string | opcional | Valor de conciliação. |
| `conciliation_metadata.conciliation_field` | string | opcional | Campo de conciliação. |

#### Atributos de `documents`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `name` | string | obrigatório | Nome do documento. Máximo de 255 caracteres. |
| `document_type` | string | obrigatório | Tipo do documento: `invoice` (NF), `calculation_memory` (memória de cálculo), `contract` (contrato) ou `bank_slip` (boleto). |
| `document_b64` | string | obrigatório | Conteúdo do documento codificado em Base64. |

## Response

STATUS 201

```json title="Response Body"
{
    "expense_key": "7f3e9a1b-2c4d-5e6f-8901-abcdef234567",
    "contract_key": "contrato-auditoria-2026",
    "status": "pending_adm_approval",
    "payment_method": "transfer",
    "start_deferral_date": "2026-06-02",
    "end_deferral_date": "2026-06-30",
    "description": "Honorários de auditoria referente ao 1º semestre de 2026",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90"
        },
        "target_account": {
            "account_number": "123456",
            "account_branch": "0001",
            "account_digit": "0",
            "financial_institution_code": "341"
        },
        "transfer_type": "wire_transfer",
        "source_account": {
            "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e"
        }
    },
    "payment_value": 15000.00,
    "payment_date": "2026-07-01",
    "rebate_expense_key": null,
    "fund_class": {
        "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO",
        "manager": {
            "name": "EXEMPLO GESTORA LTDA",
            "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
            "document_number": "45.585.471/0001-47"
        },
        "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
        "document_number": "60.910.091/0001-24"
    }
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `expense_key` | string | Chave única da despesa (UUID). Guarde este valor para as próximas etapas. |
| `contract_key` | string | Chave do contrato ao qual a despesa pertence. |
| `status` | string | Status da despesa. Será `pending_adm_approval` se documentos foram incluídos na criação, ou `created` caso contrário. |
| `payment_method` | string | Método de pagamento da despesa. |
| `start_deferral_date` | string | Data início de competência no formato `YYYY-MM-DD`. |
| `end_deferral_date` | string | Data fim de competência no formato `YYYY-MM-DD`. |
| `description` | string | Descrição da despesa. |
| `payment` | object | Dados do pagamento conforme enviado na criação. |
| `payment_value` | number | Valor da despesa. |
| `payment_date` | string | Data de pagamento no formato `YYYY-MM-DD`. |
| `rebate_expense_key` | string | Chave da despesa original quando se tratar de um rebate, ou `null`. |
| `fund_class` | object | Dados do fundo associado. |

## Possíveis erros

STATUS 404

**Contrato não encontrado**

O par `fund_class_key` + `contract_key` não corresponde a nenhum contrato cadastrado.

```json
{
  "title": "Contract Not Found",
  "description": "Contract with key {contract_key} and fund class {fund_class_key} was not found.",
  "translation": "O contrato com chave {contract_key} do fundo {fund_class_key} não foi encontrado.",
  "code": "ESB000011"
}
```

STATUS 400

**Contrato rejeitado**

Não é possível criar despesas em um contrato com status `rejected`.

```json
{
  "title": "Cannot Create Expense On Rejected Contract",
  "description": "Cannot create expense on rejected contract {contract_key}.",
  "translation": "Não é possível criar despesa no contrato rejeitado {contract_key}.",
  "code": "ESB000035"
}
```

**Contrato vencido**

A data de validade do contrato já passou. Não é possível criar novas despesas.

```json
{
  "title": "Contract Expired",
  "description": "Contract {contract_key} has expired.",
  "translation": "O contrato {contract_key} está vencido.",
  "code": "ESB000029"
}
```

**Soma das despesas excede o valor do contrato**

A soma dos valores de todas as despesas ultrapassaria o `contract_value` definido no contrato.

```json
{
  "title": "Expense Value Sum Greater Than Contract",
  "description": "The sum of expense values exceeds the contract value for {contract_name}.",
  "translation": "A soma dos valores das despesas excede o valor do contrato {contract_name}.",
  "code": "ESB000030"
}
```

**Data inválida (não é dia útil)**

A data informada em `payment_date`, `start_deferral_date` ou `end_deferral_date` não é um dia útil.

```json
{
  "title": "Date Invalid For Expense Creation",
  "description": "The date {date} is not a valid workday for expense creation.",
  "translation": "A data {date} não é um dia útil válido para criação de despesa.",
  "code": "ESB000032"
}
```

**Data início posterior à data fim de competência**

O campo `start_deferral_date` é posterior ao `end_deferral_date`.

```json
{
  "title": "Start Deferral Date Greater Than End Deferral Date",
  "description": "The start deferral date {start_date} is greater than the end deferral date {end_date}.",
  "translation": "A data de início de competência {start_date} é maior que a data de fim de competência {end_date}.",
  "code": "ESB000033"
}
```

## Próximos passos

- Se os documentos foram incluídos na criação (status `pending_adm_approval`): aguarde a análise da QI Tech.
- Se os documentos **não** foram incluídos (status `created`):
  1. **[Upload de documentos](/documentation/iaas/despesas/submissao_despesa/documentos/upload)** — adicione ao menos um documento antes de submeter.
  2. **[Submeter a despesa](/documentation/iaas/despesas/submissao_despesa/despesa/submissao)** — encaminhe para análise da QI Tech.

---

# Listagem de Despesas

URL: /documentation/iaas/despesas/submissao_despesa/despesa/listagem

Liste as despesas submetidas de um contrato ou de um fundo com filtros opcionais.

## Listar por contrato

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expenses
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID) |
| `contract_key` | string | Chave única do contrato |

### Query params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `payment_method` | string | opcional | Filtra por método de pagamento: `transfer`, `automatic_debit` ou `bank_slip`. |
| `payment_date` | string | opcional | Filtra pela data de pagamento no formato `YYYY-MM-DD`. |
| `start_deferral_date` | string | opcional | Filtra pela data início de competência no formato `YYYY-MM-DD`. |
| `end_deferral_date` | string | opcional | Filtra pela data fim de competência no formato `YYYY-MM-DD`. |
| `status` | string | opcional | Filtra por status (`created`, `pending_adm_approval`, `approved`, `rejected`, `canceled`). |
| `limit` | integer | opcional | Número de itens por página. Mínimo: `1`. Máximo: `1000`. Padrão: `10`. |
| `page` | integer | opcional | Número da página (base zero). Padrão: `0`. |

## Response

STATUS 200

```json title="Response Body"
{
    "data": [
        {
            "expense_key": "7f3e9a1b-2c4d-5e6f-8901-abcdef234567",
            "contract_key": "contrato-auditoria-2026",
            "status": "approved",
            "payment_method": "transfer",
            "start_deferral_date": "2026-06-02",
            "end_deferral_date": "2026-06-30",
            "description": "Honorários de auditoria referente ao 1º semestre de 2026",
            "payment": {
                "target": {
                    "name": "AUDITORES EXEMPLO S.A.",
                    "document_number": "12.345.678/0001-90"
                },
                "target_account": {
                    "account_number": "123456",
                    "account_branch": "0001",
                    "account_digit": "0",
                    "financial_institution_code": "341"
                }
            },
            "payment_value": 15000.00,
            "payment_date": "2026-07-01",
            "rebate_expense_key": null,
            "fund_class": {
                "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO",
                "manager": {
                    "name": "EXEMPLO GESTORA LTDA",
                    "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
                    "document_number": "45.585.471/0001-47"
                },
                "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
                "document_number": "60.910.091/0001-24"
            }
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Lista de despesas. Cada item segue a estrutura da [consulta individual](/documentation/iaas/despesas/submissao_despesa/despesa/recuperacao). |
| `limit` | integer | Número de itens por página utilizado na consulta. |
| `page` | integer | Número da página atual. |
| `is_last_page` | boolean | Indica se esta é a última página de resultados. |

---

## Listar por fundo

Para consultar todas as despesas de um fundo, independentemente do contrato:

ENDPOINT /expense_submission/fund_class/{fund_class_key}/expenses
MÉTODO GET

Aceita os mesmos query params da listagem por contrato, com os parâmetros adicionais:

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `rebate` | boolean | opcional | Filtra apenas despesas do tipo rebate (`true`) ou apenas despesas regulares (`false`). |
| `description` | string | opcional | Filtra pela descrição da despesa (busca parcial). |

## Possíveis erros

STATUS 404

**Fundo ou contrato não encontrado**

O `fund_class_key` ou `contract_key` informado não corresponde a nenhum registro cadastrado.

```json
{
  "title": "Contract Not Found",
  "description": "Contract with key {contract_key} and fund class {fund_class_key} was not found.",
  "translation": "O contrato com chave {contract_key} do fundo {fund_class_key} não foi encontrado.",
  "code": "ESB000011"
}
```

---

# Consulta de Despesa

URL: /documentation/iaas/despesas/submissao_despesa/despesa/recuperacao

Recupere os dados e o status atual de uma despesa no fluxo de submissão.

:::tip
Este endpoint retorna o status da despesa **dentro do processo de submissão** (ex: `created`, `pending_adm_approval`, `approved`). Para consultar despesas já consolidadas no ledger do fundo, utilize a [API de consulta de despesas](/documentation/iaas/despesas/despesa_consolidada/consulta_despesas).
:::

## Request

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense/{expense_key}
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID) |
| `contract_key` | string | Chave única do contrato |
| `expense_key` | string | Chave única da despesa (UUID) |

## Response

STATUS 200

```json title="Response Body"
{
    "expense_key": "7f3e9a1b-2c4d-5e6f-8901-abcdef234567",
    "contract_key": "contrato-auditoria-2026",
    "status": "approved",
    "payment_method": "transfer",
    "start_deferral_date": "2026-06-02",
    "end_deferral_date": "2026-06-30",
    "description": "Honorários de auditoria referente ao 1º semestre de 2026",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90"
        },
        "target_account": {
            "account_number": "123456",
            "account_branch": "0001",
            "account_digit": "0",
            "financial_institution_code": "341"
        },
        "transfer_type": "wire_transfer",
        "source_account": {
            "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e"
        }
    },
    "payment_value": 15000.00,
    "payment_date": "2026-07-01",
    "rebate_expense_key": null,
    "fund_class": {
        "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO",
        "manager": {
            "name": "EXEMPLO GESTORA LTDA",
            "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
            "document_number": "45.585.471/0001-47"
        },
        "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
        "document_number": "60.910.091/0001-24"
    }
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `expense_key` | string | Chave única da despesa (UUID). |
| `contract_key` | string | Chave do contrato ao qual a despesa pertence. |
| `status` | string | Status atual no fluxo de submissão. Ver tabela de [status da despesa](/documentation/iaas/despesas/submissao_despesa/inicio#status-da-despesa). |
| `payment_method` | string | Método de pagamento: `transfer`, `automatic_debit` ou `bank_slip`. |
| `start_deferral_date` | string | Data início de competência no formato `YYYY-MM-DD`. |
| `end_deferral_date` | string | Data fim de competência no formato `YYYY-MM-DD`. |
| `description` | string | Descrição da despesa. |
| `payment` | object | Dados do pagamento conforme cadastrados. |
| `payment_value` | number | Valor da despesa. |
| `payment_date` | string | Data de pagamento no formato `YYYY-MM-DD`. |
| `rebate_expense_key` | string | Chave da despesa original quando se tratar de um rebate, ou `null`. |
| `fund_class` | object | Dados do fundo associado. |

## Possíveis erros

STATUS 404

**Despesa não encontrada**

O conjunto `fund_class_key` + `contract_key` + `expense_key` não corresponde a nenhuma despesa cadastrada.

```json
{
  "title": "Expense Not Found",
  "description": "Expense with key {expense_key} was not found.",
  "translation": "A despesa com chave {expense_key} não foi encontrada.",
  "code": "ESB000016"
}
```

---

# Submissão da Despesa

URL: /documentation/iaas/despesas/submissao_despesa/despesa/submissao

Encaminhe uma despesa para análise da QI Tech. A submissão só é necessária quando a despesa foi criada **sem documentos** — caso contrário, a despesa já é automaticamente encaminhada durante a criação.

:::caution Atenção
- É obrigatório ter ao menos um documento anexado à despesa antes de submeter.
- Somente despesas no status `created` podem ser submetidas por este endpoint. Despesas que já passaram pela criação com documentos estarão no status `pending_adm_approval` e não precisam ser submetidas novamente.
:::

## Request

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense/{expense_key}/submit
MÉTODO PUT

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID) |
| `contract_key` | string | Chave única do contrato |
| `expense_key` | string | Chave única da despesa (UUID) |

Este endpoint não requer body na requisição.

## Response

STATUS 200

```json title="Response Body"
{
    "expense_key": "7f3e9a1b-2c4d-5e6f-8901-abcdef234567",
    "contract_key": "contrato-auditoria-2026",
    "status": "pending_adm_approval",
    "payment_method": "transfer",
    "start_deferral_date": "2026-06-02",
    "end_deferral_date": "2026-06-30",
    "description": "Honorários de auditoria referente ao 1º semestre de 2026",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90"
        },
        "target_account": {
            "account_number": "123456",
            "account_branch": "0001",
            "account_digit": "0",
            "financial_institution_code": "341"
        },
        "transfer_type": "wire_transfer",
        "source_account": {
            "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e"
        }
    },
    "payment_value": 15000.00,
    "payment_date": "2026-07-01",
    "rebate_expense_key": null,
    "fund_class": {
        "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO",
        "manager": {
            "name": "EXEMPLO GESTORA LTDA",
            "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
            "document_number": "45.585.471/0001-47"
        },
        "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
        "document_number": "60.910.091/0001-24"
    }
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `status` | string | Novo status da despesa. Sempre retorna `pending_adm_approval` após a submissão bem-sucedida. |

Os demais campos seguem a mesma estrutura da [criação da despesa](/documentation/iaas/despesas/submissao_despesa/despesa/criacao#atributos-da-resposta).

## Possíveis erros

STATUS 404

**Despesa não encontrada**

O conjunto `fund_class_key` + `contract_key` + `expense_key` não corresponde a nenhuma despesa cadastrada.

```json
{
  "title": "Expense Not Found",
  "description": "Expense with key {expense_key} was not found.",
  "translation": "A despesa com chave {expense_key} não foi encontrada.",
  "code": "ESB000016"
}
```

STATUS 400

**Despesa sem documentos**

Não há documentos anexados à despesa. Faça o [upload de ao menos um documento](/documentation/iaas/despesas/submissao_despesa/documentos/upload) antes de submeter.

```json
{
  "title": "Submission Must Have At Least One Pending Analysis Document",
  "description": "Expense {expense_key} must have at least one document in pending_adm_approval or approved status.",
  "translation": "A despesa {expense_key} deve ter ao menos um documento em status pending_adm_approval ou approved.",
  "code": "ESB000025"
}
```

**Transição de status inválida**

A despesa não está no status `created` e não pode ser submetida por este endpoint.

```json
{
  "title": "Cannot Update Expense In This Status",
  "description": "Expense {expense_key} cannot be updated with status {current_status}.",
  "translation": "A despesa {expense_key} não pode ser atualizada com o status {current_status}.",
  "code": "ESB000023"
}
```

## Próximos passos

Após submeter a despesa, aguarde a análise da QI Tech. Você pode acompanhar o status via:

**[Consultar a despesa](/documentation/iaas/despesas/submissao_despesa/despesa/recuperacao)** — verifique o status atual da despesa.

---

# Listagem de Documentos

URL: /documentation/iaas/despesas/submissao_despesa/documentos/listagem

Liste todos os documentos vinculados a uma despesa ou a um contrato.

---

## Listar documentos de uma despesa

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense/{expense_key}/documents
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID) |
| `contract_key` | string | Chave única do contrato |
| `expense_key` | string | Chave única da despesa (UUID) |

## Response

STATUS 200

```json title="Response Body"
{
    "data": [
        {
            "name": "NF-e 001234 - Auditoria jun/2026",
            "expense_document_key": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
            "expense_key": "7f3e9a1b-2c4d-5e6f-8901-abcdef234567",
            "document_type": "invoice",
            "status": "approved"
        },
        {
            "name": "Memória de Cálculo - jun/2026",
            "expense_document_key": "e5f6a7b8-c9d0-1234-ef56-7890abcdef12",
            "expense_key": "7f3e9a1b-2c4d-5e6f-8901-abcdef234567",
            "document_type": "calculation_memory",
            "status": "pending_adm_approval"
        }
    ]
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Lista de documentos. |
| `data[].name` | string | Nome do documento. |
| `data[].expense_document_key` | string | Chave única do documento (UUID). |
| `data[].expense_key` | string | Chave da despesa à qual o documento pertence. |
| `data[].document_type` | string | Tipo do documento: `invoice`, `calculation_memory`, `contract` ou `bank_slip`. |
| `data[].status` | string | Status do documento: `pending_adm_approval`, `approved` ou `rejected`. |

---

## Listar documentos de um contrato

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/documents
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID) |
| `contract_key` | string | Chave única do contrato |

## Response

STATUS 200

```json title="Response Body"
{
    "data": [
        {
            "name": "Contrato de Prestação de Serviços - Auditoria 2026",
            "contract_document_key": "f6a7b8c9-d0e1-2345-fa67-890abcdef123",
            "contract_key": "contrato-auditoria-2026",
            "document_type": "contract",
            "status": "approved"
        }
    ]
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Lista de documentos. |
| `data[].name` | string | Nome do documento. |
| `data[].contract_document_key` | string | Chave única do documento de contrato (UUID). |
| `data[].contract_key` | string | Chave do contrato ao qual o documento pertence. |
| `data[].document_type` | string | Tipo do documento. |
| `data[].status` | string | Status do documento: `pending_adm_approval`, `approved` ou `rejected`. |

## Possíveis erros

STATUS 404

**Despesa ou contrato não encontrado**

As chaves informadas na URL não correspondem a nenhum registro cadastrado.

```json
{
  "title": "Expense Not Found",
  "description": "Expense with key {expense_key} was not found.",
  "translation": "A despesa com chave {expense_key} não foi encontrada.",
  "code": "ESB000016"
}
```

---

# Upload de Documentos

URL: /documentation/iaas/despesas/submissao_despesa/documentos/upload

Adicione documentos comprobatórios a uma despesa ou contrato. Os documentos passam por análise da QI Tech e são obrigatórios para a submissão da despesa.

:::tip Atalho na criação
Você pode incluir documentos diretamente no body da [criação da despesa](/documentation/iaas/despesas/submissao_despesa/despesa/criacao) — nesse caso, a despesa já entra em `pending_adm_approval` sem precisar chamar este endpoint separadamente.
:::

:::info Tipos de documento aceitos
- `invoice` — Nota fiscal eletrônica (NF-e)
- `calculation_memory` — Memória de cálculo ou planilha de apuração
- `contract` — Contrato do serviço prestado
- `bank_slip` — Boleto bancário
:::

---

## Upload de documento em despesa

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense/{expense_key}/document
MÉTODO POST

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID) |
| `contract_key` | string | Chave única do contrato |
| `expense_key` | string | Chave única da despesa (UUID) |

```json title="Request Body"
{
    "name": "NF-e 001234 - Auditoria jun/2026",
    "document_type": "invoice",
    "document_b64": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwKL0xlbmd0aCAzIDAgUgo..."
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `name` | string | obrigatório | Nome do documento. Máximo de 255 caracteres. |
| `document_type` | string | obrigatório | Tipo do documento: `invoice`, `calculation_memory`, `contract` ou `bank_slip`. |
| `document_b64` | string | obrigatório | Conteúdo do arquivo codificado em Base64. |

## Response

STATUS 201

```json title="Response Body"
{
    "name": "NF-e 001234 - Auditoria jun/2026",
    "expense_document_key": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
    "expense_key": "7f3e9a1b-2c4d-5e6f-8901-abcdef234567",
    "document_type": "invoice",
    "status": "pending_adm_approval"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `name` | string | Nome do documento. |
| `expense_document_key` | string | Chave única do documento (UUID). |
| `expense_key` | string | Chave da despesa à qual o documento pertence. |
| `document_type` | string | Tipo do documento. |
| `status` | string | Status inicial do documento. Sempre retorna `pending_adm_approval`. |

---

## Upload de documento em contrato

Documentos também podem ser vinculados diretamente ao contrato (ex: o contrato do serviço prestado).

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/document
MÉTODO POST

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID) |
| `contract_key` | string | Chave única do contrato |

O body e os atributos da resposta seguem a mesma estrutura do upload em despesa, com os campos `contract_document_key` e `contract_key` no lugar de `expense_document_key` e `expense_key`.

```json title="Response Body"
{
    "name": "Contrato de Prestação de Serviços - Auditoria 2026",
    "contract_document_key": "e5f6a7b8-c9d0-1234-ef56-7890abcdef12",
    "contract_key": "contrato-auditoria-2026",
    "document_type": "contract",
    "status": "pending_adm_approval"
}
```

---

## Consultar documento por chave

Recupere os dados de um documento e acesse o link para download do arquivo.

### Documento de despesa

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense/{expense_key}/document/{document_key}
MÉTODO GET

```json title="Response Body"
{
    "name": "NF-e 001234 - Auditoria jun/2026",
    "expense_document_key": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
    "expense_key": "7f3e9a1b-2c4d-5e6f-8901-abcdef234567",
    "document_type": "invoice",
    "status": "approved",
    "document_url": "https://storage.example.com/documents/NF-001234.pdf?X-Amz-Expires=3600&..."
}
```

| Campo | Tipo | Descrição |
|---|---|---|
| `document_url` | string | URL pré-assinada para download do arquivo. Válida por tempo limitado. |
| `status` | string | Status do documento: `pending_adm_approval`, `approved` ou `rejected`. |

## Possíveis erros

STATUS 404

**Despesa não encontrada**

O conjunto de chaves na URL não corresponde a nenhuma despesa cadastrada.

```json
{
  "title": "Expense Not Found",
  "description": "Expense with key {expense_key} was not found.",
  "translation": "A despesa com chave {expense_key} não foi encontrada.",
  "code": "ESB000016"
}
```

**Documento não encontrado**

O `document_key` informado não corresponde a nenhum documento cadastrado para esta despesa.

```json
{
  "title": "Document Not Found",
  "description": "Document with key {document_key} was not found.",
  "translation": "O documento com chave {document_key} não foi encontrado.",
  "code": "ESB000015"
}
```

STATUS 400

**Formato do documento inválido**

O conteúdo em `document_b64` não é um Base64 válido ou o formato do arquivo não é suportado.

```json
{
  "title": "Invalid Document Format",
  "description": "The document format is invalid.",
  "translation": "Formato do documento invalido.",
  "code": "ESB000014"
}
```

## Próximos passos

Com ao menos um documento em `pending_adm_approval` ou `approved`, a despesa está pronta para ser submetida:

**[Submeter a despesa](/documentation/iaas/despesas/submissao_despesa/despesa/submissao)** — encaminhe para análise da QI Tech.

---

# Fluxo de submissão de despesas

URL: /documentation/iaas/despesas/submissao_despesa/fluxo_despesas

Esta página oferece uma visão holística do fluxo de submissão de despesas: desde a criação do contrato até a aprovação das despesas individuais pela QI Tech. Acompanhe a evolução dos **status do contrato**, dos **status de cada despesa** e as ações esperadas em cada etapa.

:::tip Como usar este fluxograma
Passe o mouse sobre cada etapa para ver os detalhes do endpoint e acessar a documentação completa. As trilhas coloridas mostram simultaneamente o que acontece com o contrato e com cada despesa.
:::

{`
.cf-legend{display:flex;flex-wrap:wrap;gap:8px;margin-bottom:24px}
.cf-legend-item{display:flex;align-items:center;gap:6px;font-size:0.8rem;font-weight:600}
.cf-legend-dot{width:12px;height:12px;border-radius:3px}

.cf-step{position:relative;margin-bottom:4px}
.cf-step:not(:last-child)::after{content:'';display:block;width:2px;height:16px;margin:0 auto;background:var(--ifm-color-emphasis-300)}

.cf-card{border:1.5px solid var(--ifm-color-emphasis-200);border-radius:10px;padding:16px 20px;transition:box-shadow 0.2s,border-color 0.2s;cursor:pointer;background:var(--ifm-background-surface-color,var(--ifm-background-color))}
.cf-card:hover{box-shadow:0 4px 16px rgba(0,0,0,0.08);border-color:var(--ifm-color-primary)}

.cf-card-header{display:flex;align-items:center;gap:10px;flex-wrap:wrap}
.cf-num{width:28px;height:28px;border-radius:50%;display:flex;align-items:center;justify-content:center;font-size:0.8rem;font-weight:800;color:#fff;flex-shrink:0}
.cf-num-int{background:#3b82f6}
.cf-num-qi{background:#8b5cf6}
.cf-title{font-size:1rem;font-weight:700;color:var(--ifm-font-color-base)}
.cf-actor{font-size:0.7rem;font-weight:700;padding:2px 8px;border-radius:12px;margin-left:auto}
.cf-actor-int{background:rgba(59,130,246,0.12);color:#2563eb}
.cf-actor-qi{background:rgba(139,92,246,0.12);color:#7c3aed}
.cf-subtitle{font-size:0.82rem;color:var(--ifm-color-emphasis-700);margin-top:4px;margin-left:38px}

.cf-tracks{display:flex;flex-wrap:wrap;gap:8px;margin-top:12px;margin-left:38px}
.cf-track{display:inline-flex;align-items:center;gap:5px;padding:3px 10px;border-radius:6px;font-size:0.75rem;font-family:var(--ifm-font-family-monospace);border:1px solid}
.cf-track-contrato{background:rgba(34,197,94,0.1);color:#16a34a;border-color:rgba(34,197,94,0.25)}
.cf-track-despesa{background:rgba(59,130,246,0.1);color:#2563eb;border-color:rgba(59,130,246,0.25)}
.cf-track-err{background:rgba(239,68,68,0.1);color:#dc2626;border-color:rgba(239,68,68,0.25)}
.cf-track-label{font-family:var(--ifm-font-family-base);font-weight:700;font-size:0.7rem;text-transform:uppercase;letter-spacing:0.03em}
.cf-new{font-weight:700}
.cf-unchanged{opacity:0.5}

.cf-details{max-height:0;overflow:hidden;opacity:0;transition:max-height 0.35s ease,opacity 0.25s ease,margin 0.3s ease;margin-left:38px}
.cf-card:hover .cf-details{max-height:300px;opacity:1;margin-top:14px;padding-top:12px;border-top:1px solid var(--ifm-color-emphasis-200)}

.cf-endpoint{font-family:var(--ifm-font-family-monospace);font-size:0.82rem;padding:8px 12px;border-radius:6px;background:var(--ifm-color-emphasis-100);margin-bottom:8px;display:flex;align-items:center;gap:8px;flex-wrap:wrap}
.cf-method{font-weight:800;padding:2px 6px;border-radius:4px;font-size:0.72rem}
.cf-method-post{background:#f97316;color:#fff}
.cf-method-put{background:#3b82f6;color:#fff}
.cf-method-get{background:#22c55e;color:#fff}
.cf-desc{font-size:0.82rem;color:var(--ifm-color-emphasis-700);margin-bottom:8px}
.cf-link{font-size:0.82rem;font-weight:600;color:var(--ifm-color-primary);text-decoration:none}
.cf-link:hover{text-decoration:underline}

.cf-branch{margin-top:12px;margin-left:38px;display:flex;gap:12px;flex-wrap:wrap}
.cf-branch-path{flex:1;min-width:200px;border-radius:8px;padding:10px 14px;border:1.5px dashed}
.cf-branch-ok{border-color:rgba(34,197,94,0.4);background:rgba(34,197,94,0.05)}
.cf-branch-err{border-color:rgba(239,68,68,0.4);background:rgba(239,68,68,0.05)}
.cf-branch-label{font-size:0.78rem;font-weight:700;margin-bottom:4px}
.cf-branch-label-ok{color:#16a34a}
.cf-branch-label-err{color:#dc2626}

html[data-theme='dark'] .cf-track-contrato{background:rgba(34,197,94,0.15);color:#4ade80;border-color:rgba(34,197,94,0.3)}
html[data-theme='dark'] .cf-track-despesa{background:rgba(59,130,246,0.15);color:#60a5fa;border-color:rgba(59,130,246,0.3)}
html[data-theme='dark'] .cf-track-err{background:rgba(239,68,68,0.15);color:#f87171;border-color:rgba(239,68,68,0.3)}
html[data-theme='dark'] .cf-branch-ok{background:rgba(34,197,94,0.08)}
html[data-theme='dark'] .cf-branch-err{background:rgba(239,68,68,0.08)}
html[data-theme='dark'] .cf-actor-int{background:rgba(59,130,246,0.2);color:#60a5fa}
html[data-theme='dark'] .cf-actor-qi{background:rgba(139,92,246,0.2);color:#a78bfa}
`}

## Legenda

Agente Integrador
QI Tech (análise manual)
Status do Contrato
Status da Despesa

## Fluxograma

1
Criação do contrato
Agente Integrador
Cria um contrato vinculando o fundo a um fornecedor e definindo o tipo de despesa ( expense_type ) e a natureza de submissão ( submission_nature ).
Contrato: created
POST /expense_submission/fund_class/{fund_class_key}/contract
O contrato fica pronto para ser atualizado ou submetido para aprovação.
Ver documentação completa →

2
Submissão do contrato para aprovação
Agente Integrador
Sinaliza que o contrato está pronto para análise da QI Tech. Após a submissão, o contrato não pode mais ser editado.
Contrato: pending_adm_approval
PUT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/submit
O contrato aguarda revisão manual pela equipe da QI Tech.
Ver documentação completa →

3
Análise e aprovação do contrato
QI Tech
A equipe da QI Tech analisa o contrato. Em caso de dúvidas, podem criar anotações que o agente integrador poderá responder.
Contrato aprovado
approved
Despesas podem ser criadas e submetidas.
Contrato rejeitado
rejected
Nenhuma despesa poderá ser criada neste contrato.
Use o endpoint de consulta para acompanhar o status do contrato.
GET /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}
Ver documentação completa →

4
Criação da despesa
Agente Integrador
Cria uma despesa individual sob o contrato aprovado, informando dados de pagamento, período de competência e documentos comprobatórios. Ao incluir documentos na criação, a despesa é automaticamente encaminhada para revisão.
Contrato: approved
Despesa: created → pending_adm_approval*
POST /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense
*Se documentos forem incluídos no body da criação, a despesa vai diretamente para pending_adm_approval . Caso contrário, fica em created .
Ver documentação completa →

5
Upload de documentos (quando necessário)
Agente Integrador
Se os documentos não foram enviados na criação da despesa, faça o upload separadamente antes de submeter. Ao menos um documento é obrigatório para submissão.
Despesa: created
POST /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense/{expense_key}/document
Envie os documentos comprobatórios (NF, memória de cálculo, contrato ou boleto) em Base64.
Ver documentação completa →

6
Submissão da despesa para aprovação
Agente Integrador
Encaminha a despesa para análise da QI Tech. Obrigatório ter ao menos um documento anexado.
Despesa: pending_adm_approval
PUT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense/{expense_key}/submit
Somente aplicável quando a despesa foi criada sem documentos ( status = created ). Caso contrário, a despesa já estará em pending_adm_approval .
Ver documentação completa →

7
Análise e aprovação da despesa
QI Tech
A QI Tech analisa os dados de pagamento e os documentos comprobatórios. Após aprovação, a despesa é processada internamente e registrada na carteira do fundo.
Despesa aprovada
approved
Despesa registrada. Fluxo encerrado com sucesso.
Despesa rejeitada
rejected
Verifique as anotações da QI Tech para entender o motivo da rejeição.
Use o endpoint de consulta para acompanhar o status da despesa.
GET /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense/{expense_key}
Ver documentação completa →

---

# Anotações da Análise

URL: /documentation/iaas/despesas/submissao_despesa/fornecedor/anotacoes

Durante a revisão, a equipe da QI Tech pode abrir **anotações** — solicitações de esclarecimento ou correção sobre os dados do fornecedor ou os documentos enviados. O agente integrador deve responder a essas anotações para que a análise prossiga.

:::info Status das anotações
| Status | Descrição |
|---|---|
| `created` | Anotação criada pela QI Tech |
| `opened` | Anotação aberta, aguardando resposta |
| `closed` | Anotação respondida ou encerrada |
:::

---

## Listar anotações de uma análise

ENDPOINT /vendor_registry/analysis/{analysis_key}/annotations
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `analysis_key` | string | Chave única da análise (UUID) |

### Query params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `status` | string (lista) | opcional | Filtra anotações pelo status. Valores: `created`, `opened`, `closed`. Aceita múltiplos valores. |
| `limit` | integer | opcional | Número de itens por página. Mínimo: `0`. Máximo: `1000`. Padrão: `10`. |
| `page` | integer | opcional | Número da página (base zero). Padrão: `0`. |

## Response

STATUS 200

```json title="Response Body"
{
    "data": [
        {
            "annotation_key": "f6a7b8c9-d0e1-2345-f678-90abcdef1234",
            "annotation_message": "Por favor, envie o contrato social atualizado com as últimas alterações societárias.",
            "annotation_response": null,
            "annotation_datetime": "2026-06-10 14:32:00",
            "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234",
            "status": "opened"
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Lista de anotações. |
| `limit` | integer | Número de itens por página utilizado na consulta. |
| `page` | integer | Número da página atual. |
| `is_last_page` | boolean | Indica se esta é a última página de resultados. |

#### Atributos de cada anotação em `data`

| Campo | Tipo | Descrição |
|---|---|---|
| `annotation_key` | string | Chave única da anotação (UUID). |
| `annotation_message` | string | Mensagem da anotação criada pela QI Tech. |
| `annotation_response` | string \| null | Resposta do agente integrador, ou `null` se ainda não respondida. |
| `annotation_datetime` | string | Data e hora em que a anotação foi criada. |
| `analysis_key` | string | Chave da análise à qual a anotação pertence. |
| `status` | string | Status da anotação: `created`, `opened` ou `closed`. |

---

## Consultar anotação por chave

ENDPOINT /vendor_registry/analysis/{analysis_key}/annotation/{annotation_key}
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `analysis_key` | string | Chave única da análise (UUID) |
| `annotation_key` | string | Chave única da anotação (UUID) |

## Response

STATUS 200

```json title="Response Body"
{
    "annotation_key": "f6a7b8c9-d0e1-2345-f678-90abcdef1234",
    "annotation_message": "Por favor, envie o contrato social atualizado com as últimas alterações societárias.",
    "annotation_response": null,
    "annotation_datetime": "2026-06-10 14:32:00",
    "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "status": "opened"
}
```

---

## Responder a uma anotação

ENDPOINT /vendor_registry/analysis/{analysis_key}/annotation/{annotation_key}/respond
MÉTODO PUT

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `analysis_key` | string | Chave única da análise (UUID) |
| `annotation_key` | string | Chave única da anotação (UUID) |

```json title="Request Body"
{
    "annotation_response": "O contrato social atualizado foi enviado no documento 'Contrato Social - AUDITORES EXEMPLO S.A.'."
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `annotation_response` | string | obrigatório | Resposta à anotação. Máximo de 200 caracteres. |

## Response

STATUS 202

```json title="Response Body"
{
    "annotation_key": "f6a7b8c9-d0e1-2345-f678-90abcdef1234",
    "annotation_message": "Por favor, envie o contrato social atualizado com as últimas alterações societárias.",
    "annotation_response": "O contrato social atualizado foi enviado no documento 'Contrato Social - AUDITORES EXEMPLO S.A.'.",
    "annotation_datetime": "2026-06-10 14:32:00",
    "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "status": "closed"
}
```

---

## Possíveis erros

STATUS 404

**Anotação não encontrada**

A `annotation_key` informada na URL não corresponde a nenhuma anotação desta análise.

```json
{
  "title": "Annotation not found",
  "description": "Annotation with the key {annotation_key} was not found.",
  "translation": "A anotação com a chave {annotation_key} não foi encontrada.",
  "code": "VRG0000012"
}
```

STATUS 409

**Anotação já respondida**

A anotação informada já possui uma resposta registrada.

```json
{
  "title": "Annotation Already Responded",
  "description": "Annotation with key {annotation_key} is already responded.",
  "translation": "Anotação com chave {annotation_key} está respondida.",
  "code": "VRG0000013"
}
```

---

## Próximos passos

Após responder às anotações, aguarde a QI Tech retomar a análise. Acompanhe o status via:

**[Consultar análise por chave](/documentation/iaas/despesas/submissao_despesa/fornecedor/listagem#consultar-análise-por-chave)** — monitore o andamento da análise.

---

# Atualização de Dados da Análise

URL: /documentation/iaas/despesas/submissao_despesa/fornecedor/atualizacao

Enquanto a análise estiver no status `pending_submission`, é possível atualizar os dados de pagamento e a flag `requires_invoice`. Após submeter para `pending_adm_approval`, a edição não é mais permitida.

:::caution Restrição de status
Este endpoint só aceita atualizações quando a análise está no status `pending_submission`. Se a análise foi retornada pela QI Tech para este status, também é possível editar antes de reenviar.
:::

---

## Request

ENDPOINT /vendor_registry/analysis/{analysis_key}/update
MÉTODO PUT

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `analysis_key` | string | Chave única da análise (UUID) |

```json title="Request Body"
{
    "requires_invoice": false,
    "payment_method": "transfer",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90"
        },
        "target_pix_key": "12345678000190",
        "transfer_type": "pix"
    }
}
```

### Atributos do body

Ao menos um campo deve ser informado.

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `requires_invoice` | boolean | opcional | Indica se esta análise exige nota fiscal. |
| `payment_method` | string | opcional | Método de pagamento padrão. Atualmente suporta apenas `transfer`. Obrigatório quando `payment` é informado. |
| `payment` | object | opcional | Dados bancários do fornecedor. Consulte os [atributos de `payment`](/documentation/iaas/despesas/submissao_despesa/fornecedor/criacao#atributos-de-payment). Obrigatório quando `payment_method` é informado. |

:::info Limpeza dos dados de pagamento
Se apenas um dos campos `payment` ou `payment_method` for informado (sem o outro), ambos serão removidos da análise.
:::

---

## Response

STATUS 200

```json title="Response Body"
{
    "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "status": "pending_submission",
    "requires_invoice": false,
    "manager": {
        "name": "EXEMPLO GESTORA LTDA",
        "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
        "document_number": "45.585.471/0001-47"
    },
    "vendor": {
        "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "name": "AUDITORES EXEMPLO S.A.",
        "document_number": "12.345.678/0001-90",
        "requires_invoice": true,
        "status": "pending_analysis"
    },
    "payment_method": "transfer",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90"
        },
        "target_pix_key": "12345678000190",
        "transfer_type": "pix"
    }
}
```

---

## Possíveis erros

STATUS 409

**Análise não editável**

A análise está em um status que não permite edição. Somente análises no status `pending_submission` podem ser editadas via este endpoint.

```json
{
  "title": "Analysis Not Editable",
  "description": "Analysis with key {analysis_key} is on status '{current_status}' and cannot be edited.",
  "translation": "A análise com chave {analysis_key} está no status '{current_status}' e não pode ser editada.",
  "code": "VRG000032"
}
```

STATUS 404

**Análise não encontrada**

A `analysis_key` informada na URL não corresponde a nenhuma análise cadastrada.

```json
{
  "title": "Analysis not found",
  "description": "Analysis with the key {analysis_key} was not found.",
  "translation": "A análise com a chave {analysis_key} não foi encontrada.",
  "code": "VRG000007"
}
```

---

## Próximos passos

Após atualizar os dados, prossiga para:

**[Submeter a análise](/documentation/iaas/despesas/submissao_despesa/fornecedor/submissao)** — encaminhe para revisão da QI Tech.

---

# Cancelamento da Análise

URL: /documentation/iaas/despesas/submissao_despesa/fornecedor/cancelamento

Cancele uma análise de cadastro de fornecedor que ainda esteja em andamento. Após o cancelamento, nenhuma alteração adicional pode ser feita nessa análise.

:::info Quando é possível cancelar
O cancelamento está disponível enquanto a análise estiver nos status `pending_submission` ou `pending_adm_approval`. Análises já `approved`, `rejected` ou `canceled` não podem ser canceladas.
:::

---

## Request

ENDPOINT /vendor_registry/analysis/{analysis_key}/cancel
MÉTODO PUT

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `analysis_key` | string | Chave única da análise (UUID) |

Este endpoint não requer body.

## Response

STATUS 202

```json title="Response Body"
{
    "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "status": "canceled"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `analysis_key` | string | Chave única da análise. |
| `status` | string | Novo status da análise. Sempre retorna `canceled`. |

---

## Possíveis erros

STATUS 409

**Transição de status não permitida**

A análise está em um status que não permite cancelamento (por exemplo, já foi aprovada ou rejeitada).

```json
{
  "title": "Analysis Status Transition Denied",
  "description": "Analysis with key {analysis_key} is not allowed to switch status from {current_status} to canceled.",
  "translation": "Análise com chave {analysis_key} não pode trocar de status de {current_status} para canceled.",
  "code": "VRG000008"
}
```

STATUS 404

**Análise não encontrada**

A `analysis_key` informada na URL não corresponde a nenhuma análise cadastrada.

```json
{
  "title": "Analysis not found",
  "description": "Analysis with the key {analysis_key} was not found.",
  "translation": "A análise com a chave {analysis_key} não foi encontrada.",
  "code": "VRG000007"
}
```

---

## Próximos passos

Para cadastrar o fornecedor novamente, inicie um novo processo via:

**[Criação de análise](/documentation/iaas/despesas/submissao_despesa/fornecedor/criacao)** — submeta os dados do fornecedor novamente.

---

# Cadastro de Fornecedor

URL: /documentation/iaas/despesas/submissao_despesa/fornecedor/criacao

O cadastro de fornecedores é o **pré-requisito** para a criação de contratos de despesa. O processo é realizado pelo próprio agente integrador via API e passa por análise e aprovação da QI Tech antes de o fornecedor ser ativado na plataforma.

:::info Fluxo de cadastro
O cadastro de um fornecedor segue as seguintes etapas:

1. **Criação da análise** — envio dos dados do fornecedor (esta página)
2. **Upload de documentos** — anexar documentos comprobatórios
3. **Submissão para revisão** — encaminhar para análise da QI Tech
4. **Resposta a anotações** (se solicitado) — responder às solicitações da equipe de análise
5. **Aprovação** — o fornecedor é ativado e a `vendor_key` fica disponível para uso em contratos

Para detalhes sobre as etapas seguintes, consulte:
- [Upload de documentos](/documentation/iaas/despesas/submissao_despesa/fornecedor/documentos)
- [Submissão para análise](/documentation/iaas/despesas/submissao_despesa/fornecedor/submissao)
- [Anotações](/documentation/iaas/despesas/submissao_despesa/fornecedor/anotacoes)
:::

---

## Request

ENDPOINT /vendor_registry/analysis
MÉTODO POST

```json title="Request Body"
{
    "vendor_document_number": "12.345.678/0001-90",
    "vendor_name": "AUDITORES EXEMPLO S.A.",
    "requires_invoice": true,
    "payment_method": "transfer",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90"
        },
        "target_account": {
            "account_number": "123456",
            "account_branch": "0001",
            "account_digit": "0",
            "financial_institution_code": "341"
        }
    }
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `vendor_document_number` | string | obrigatório | CPF ou CNPJ do fornecedor com pontuação. Mínimo 14, máximo 18 caracteres. |
| `vendor_name` | string | obrigatório | Nome completo do fornecedor. Máximo de 255 caracteres. |
| `requires_invoice` | boolean | opcional | Indica se o fornecedor exige nota fiscal para pagamento. Padrão: `false`. |
| `payment_method` | string | opcional | Método de pagamento padrão do fornecedor. Atualmente suporta apenas `transfer`. Obrigatório quando `payment` é informado. |
| `payment` | object | opcional | Dados bancários padrão do fornecedor. Ver [Atributos de `payment`](#atributos-de-payment). Obrigatório quando `payment_method` é informado. |

#### Atributos de `payment`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `target` | object | obrigatório | Dados do beneficiário do pagamento. |
| `target.name` | string | obrigatório | Nome do beneficiário. |
| `target.document_number` | string | obrigatório | CPF ou CNPJ do beneficiário com pontuação. |
| `target_account` | object | opcional | Dados da conta bancária de destino (TED/DOC). Obrigatório quando `transfer_type` não é informado ou é `wire_transfer`. |
| `target_account.account_number` | string | obrigatório | Número da conta (1–20 dígitos, não pode ser zeros). |
| `target_account.account_branch` | string | obrigatório | Agência bancária (exatamente 4 dígitos, não pode ser zeros). |
| `target_account.account_digit` | string | obrigatório | Dígito verificador da conta (1 dígito). |
| `target_account.financial_institution_code` | string | obrigatório | Código do banco (exatamente 3 dígitos, não pode ser zeros). |
| `target_account.financial_institution_ispb` | string | opcional | ISPB do banco (exatamente 8 dígitos). Quando não informado, é preenchido automaticamente com base no `financial_institution_code`. |
| `target_account.account_type` | string | opcional | Tipo da conta bancária. |
| `transfer_type` | string | opcional | Tipo de transferência. Informe `pix` para pagamento via Pix. Quando omitido, o pagamento é via TED/DOC. |
| `target_pix_key` | string | opcional | Chave Pix do destinatário (máx. 77 caracteres). Obrigatório quando `transfer_type` é `pix` e `target_account` não é informado. A chave Pix deve pertencer ao CPF/CNPJ de `target.document_number`. |

---

## Response

STATUS 201

```json title="Response Body"
{
    "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "status": "pending_submission",
    "requires_invoice": true,
    "manager": {
        "name": "EXEMPLO GESTORA LTDA",
        "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
        "document_number": "45.585.471/0001-47"
    },
    "vendor": {
        "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "name": "AUDITORES EXEMPLO S.A.",
        "document_number": "12.345.678/0001-90",
        "requires_invoice": true,
        "status": "pending_analysis"
    },
    "payment_method": "transfer",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90"
        },
        "target_account": {
            "account_number": "123456",
            "account_branch": "0001",
            "account_digit": "0",
            "financial_institution_code": "341",
            "financial_institution_ispb": "60701190"
        }
    }
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `analysis_key` | string | Chave única da análise (UUID). Guarde este valor para as próximas etapas. |
| `status` | string | Status inicial da análise. Sempre retorna `pending_submission`. |
| `requires_invoice` | boolean | Indica se esta análise exige nota fiscal. |
| `manager` | object | Dados do gestor autenticado. |
| `manager.name` | string | Nome do gestor. |
| `manager.manager_key` | string | Chave única do gestor (UUID). |
| `manager.document_number` | string | CNPJ do gestor. |
| `vendor` | object | Dados do fornecedor. |
| `vendor.vendor_key` | string | Chave única do fornecedor. Disponível após aprovação para uso em contratos. |
| `vendor.name` | string | Nome do fornecedor. |
| `vendor.document_number` | string | CPF ou CNPJ do fornecedor. |
| `vendor.requires_invoice` | boolean | Indica se o fornecedor exige nota fiscal. |
| `vendor.status` | string | Status do fornecedor: `pending_analysis` enquanto a análise estiver em curso. |
| `payment_method` | string | Método de pagamento, quando informado. |
| `payment` | object | Dados bancários, quando informados. |

---

## Possíveis erros

STATUS 409

**Fornecedor já ativo**

Já existe um fornecedor ativo (`status = active`) com o CNPJ/CPF informado. Utilize a [listagem de fornecedores](/documentation/iaas/despesas/submissao_despesa/fornecedor/listagem) para obter a `vendor_key`.

```json
{
  "title": "Vendor already exists",
  "description": "Already exists an active vendor with the document number {vendor_document_number}.",
  "translation": "Já existe um fornecedor ativo com o cnpj {vendor_document_number}.",
  "code": "VRG000015"
}
```

STATUS 404

**Gestor não encontrado**

O `manager_key` do agente autenticado não corresponde a nenhum gestor cadastrado na plataforma.

```json
{
  "title": "Manager not found",
  "description": "Manager with the key {manager_key} was not found.",
  "translation": "O gestor com a chave {manager_key} não foi encontrado.",
  "code": "VRG000001"
}
```

STATUS 400

**Número de documento inválido**

O CPF ou CNPJ informado em `vendor_document_number` não é válido.

```json
{
  "title": "Invalid document number",
  "description": "The document number {vendor_document_number} is invalid.",
  "translation": "O documento {vendor_document_number} é inválido.",
  "code": "VRG000002"
}
```

---

## Próximos passos

Com a análise criada (status `pending_submission`), as próximas etapas são:

1. **[Upload de documentos](/documentation/iaas/despesas/submissao_despesa/fornecedor/documentos)** — anexe o contrato social e documentos dos representantes.
2. **[Submissão para análise](/documentation/iaas/despesas/submissao_despesa/fornecedor/submissao)** — encaminhe a análise para revisão da QI Tech.

---

# Documentos da Análise

URL: /documentation/iaas/despesas/submissao_despesa/fornecedor/documentos

Após [criar a análise](/documentation/iaas/despesas/submissao_despesa/fornecedor/criacao), faça o upload dos documentos comprobatórios do fornecedor. É obrigatório ter ao menos um documento antes de [submeter a análise para revisão](/documentation/iaas/despesas/submissao_despesa/fornecedor/submissao).

:::info Tipos de documento aceitos
- `vendor_bylaws` — Contrato social do fornecedor
- `representative_document` — Documento de identificação do representante legal
:::

:::info Status inicial
Documentos enviados via API entram automaticamente com status `pending_adm_approval`, aguardando revisão da QI Tech.
:::

---

## Upload de documento

ENDPOINT /vendor_registry/analysis/{analysis_key}/document
MÉTODO POST

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `analysis_key` | string | Chave única da análise (UUID) |

```json title="Request Body"
{
    "name": "Contrato Social - AUDITORES EXEMPLO S.A.",
    "document_type": "vendor_bylaws",
    "document_b64": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwKL0xlbmd0aCAzIDAgUgo..."
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `name` | string | obrigatório | Nome do documento. Máximo de 255 caracteres. |
| `document_type` | string | obrigatório | Tipo do documento: `vendor_bylaws` ou `representative_document`. |
| `document_b64` | string | obrigatório | Conteúdo do arquivo codificado em Base64. |

## Response

STATUS 201

```json title="Response Body"
{
    "document_name": "Contrato Social - AUDITORES EXEMPLO S.A.",
    "document_key": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
    "document_type": "vendor_bylaws",
    "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "status": "pending_adm_approval"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `document_name` | string | Nome do documento. |
| `document_key` | string | Chave única do documento (UUID). |
| `document_type` | string | Tipo do documento: `vendor_bylaws` ou `representative_document`. |
| `analysis_key` | string | Chave da análise à qual o documento pertence. |
| `status` | string | Status do documento. Sempre retorna `pending_adm_approval`. |

---

## Listar documentos de uma análise

ENDPOINT /vendor_registry/analysis/{analysis_key}/documents
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `analysis_key` | string | Chave única da análise (UUID) |

## Response

STATUS 200

```json title="Response Body"
{
    "data": [
        {
            "document_name": "Contrato Social - AUDITORES EXEMPLO S.A.",
            "document_key": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
            "document_type": "vendor_bylaws",
            "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234",
            "status": "pending_adm_approval"
        },
        {
            "document_name": "RG - João da Silva",
            "document_key": "e5f6a7b8-c9d0-1234-ef56-7890abcdef12",
            "document_type": "representative_document",
            "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234",
            "status": "approved"
        }
    ]
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Lista de documentos da análise. |
| `data[].document_name` | string | Nome do documento. |
| `data[].document_key` | string | Chave única do documento (UUID). |
| `data[].document_type` | string | Tipo do documento. |
| `data[].analysis_key` | string | Chave da análise. |
| `data[].status` | string | Status do documento: `pending_adm_approval`, `approved` ou `rejected`. |

---

## Consultar documento por chave

Recupere os dados de um documento específico, incluindo URL de download.

ENDPOINT /vendor_registry/analysis/{analysis_key}/documents/{document_key}
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `analysis_key` | string | Chave única da análise (UUID) |
| `document_key` | string | Chave única do documento (UUID) |

## Response

STATUS 200

```json title="Response Body"
{
    "document_name": "Contrato Social - AUDITORES EXEMPLO S.A.",
    "document_key": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
    "document_type": "vendor_bylaws",
    "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "status": "approved",
    "document_url": "https://storage.example.com/documents/d4e5f6a7-b8c9-0123-def4-567890abcdef?X-Amz-Expires=86400&..."
}
```

### Atributos adicionais

| Campo | Tipo | Descrição |
|---|---|---|
| `document_url` | string | URL pré-assinada para download do arquivo. Válida por 24 horas. |

---

## Possíveis erros

STATUS 404

**Análise não encontrada**

A `analysis_key` informada na URL não corresponde a nenhuma análise cadastrada.

```json
{
  "title": "Analysis not found",
  "description": "Analysis with the key {analysis_key} was not found.",
  "translation": "A análise com a chave {analysis_key} não foi encontrada.",
  "code": "VRG000007"
}
```

**Documento não encontrado**

A `document_key` informada na URL não corresponde a nenhum documento desta análise.

```json
{
  "title": "Document not found",
  "description": "Document with the key {document_key} was not found.",
  "translation": "O documento com a chave {document_key} não foi encontrada.",
  "code": "VRG000003"
}
```

STATUS 400

**Formato do documento inválido**

O conteúdo em `document_b64` não é um Base64 válido.

```json
{
  "title": "Invalid document format",
  "description": "Invalid Document format",
  "translation": "Formato do documento invalido",
  "code": "VRG000004"
}
```

---

## Próximos passos

Com ao menos um documento enviado, prossiga para:

**[Submeter a análise](/documentation/iaas/despesas/submissao_despesa/fornecedor/submissao)** — encaminhe para revisão da QI Tech.

---

# Consulta de Fornecedores e Análises

URL: /documentation/iaas/despesas/submissao_despesa/fornecedor/listagem

Recupere os fornecedores ativos e acompanhe o andamento das análises de cadastro em curso.

---

## Listar fornecedores

ENDPOINT /vendor_registry/vendors
MÉTODO GET

### Query params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `name` | string | opcional | Filtra fornecedores cujo nome contenha o valor informado (busca parcial, sem distinção de maiúsculas/minúsculas). |
| `document_number` | string | opcional | Filtra pelo CPF ou CNPJ exato do fornecedor. |
| `status` | string (lista) | opcional | Filtra pelo status do fornecedor. Valores: `pending_analysis`, `active`, `inactive`. Aceita múltiplos valores. |
| `limit` | integer | opcional | Número de itens por página. Mínimo: `0`. Máximo: `1000`. Padrão: `10`. |
| `page` | integer | opcional | Número da página (base zero). Padrão: `0`. |

## Response

STATUS 200

```json title="Response Body"
{
    "data": [
        {
            "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef",
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90",
            "requires_invoice": true,
            "status": "active",
            "payment_method": "transfer"
        },
        {
            "vendor_key": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
            "name": "CVM",
            "document_number": "29.507.878/0001-08",
            "requires_invoice": true,
            "status": "active"
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Lista de fornecedores. |
| `limit` | integer | Número de itens por página utilizado na consulta. |
| `page` | integer | Número da página atual. |
| `is_last_page` | boolean | Indica se esta é a última página de resultados. |

#### Atributos de cada fornecedor em `data`

| Campo | Tipo | Descrição |
|---|---|---|
| `vendor_key` | string | Chave única do fornecedor. Use este valor na criação de contratos. |
| `name` | string | Nome do fornecedor. |
| `document_number` | string | CPF ou CNPJ do fornecedor. |
| `requires_invoice` | boolean | Indica se o fornecedor exige nota fiscal. |
| `status` | string | Status do fornecedor: `pending_analysis`, `active` ou `inactive`. |
| `payment_method` | string | Método de pagamento padrão, quando cadastrado. |
| `payment` | object | Dados bancários padrão, quando cadastrados. |

#### Status do fornecedor

| Status | Descrição |
|---|---|
| `pending_analysis` | Fornecedor com análise de cadastro em andamento |
| `active` | Fornecedor aprovado e disponível para uso em contratos |
| `inactive` | Fornecedor inativo |

---

## Consultar fornecedor por chave

ENDPOINT /vendor_registry/vendor/{vendor_key}
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `vendor_key` | string | Chave única do fornecedor (UUID, 36 caracteres) |

## Response

STATUS 200

```json title="Response Body"
{
    "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef",
    "name": "AUDITORES EXEMPLO S.A.",
    "document_number": "12.345.678/0001-90",
    "requires_invoice": true,
    "status": "active",
    "payment_method": "transfer",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90"
        },
        "target_account": {
            "account_number": "123456",
            "account_branch": "0001",
            "account_digit": "0",
            "financial_institution_code": "341",
            "financial_institution_ispb": "60701190"
        }
    }
}
```

## Possíveis erros

STATUS 404

**Fornecedor não encontrado**

A `vendor_key` informada não corresponde a nenhum fornecedor cadastrado.

```json
{
  "title": "Vendor not found",
  "description": "Vendor with the key {vendor_key} was not found.",
  "translation": "O fornecedor com a chave {vendor_key} não foi encontrada.",
  "code": "VRG000014"
}
```

---

## Listar análises

ENDPOINT /vendor_registry/analyses
MÉTODO GET

### Query params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `status` | string (lista) | opcional | Filtra pelo status da análise. Valores: `pending_submission`, `pending_adm_approval`, `approved`, `rejected`, `canceled`, `other_analysis_approved`. Aceita múltiplos valores. |
| `manager_key` | string | opcional | Filtra as análises de um gestor específico. |
| `vendor_key` | string | opcional | Filtra as análises de um fornecedor específico. |
| `limit` | integer | opcional | Número de itens por página. Mínimo: `0`. Máximo: `1000`. Padrão: `10`. |
| `page` | integer | opcional | Número da página (base zero). Padrão: `0`. |

## Response

STATUS 200

```json title="Response Body"
{
    "data": [
        {
            "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234",
            "status": "pending_adm_approval",
            "requires_invoice": true,
            "manager": {
                "name": "EXEMPLO GESTORA LTDA",
                "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
                "document_number": "45.585.471/0001-47"
            },
            "vendor": {
                "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef",
                "name": "AUDITORES EXEMPLO S.A.",
                "document_number": "12.345.678/0001-90",
                "requires_invoice": true,
                "status": "pending_analysis"
            }
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true
}
```

---

## Consultar análise por chave

ENDPOINT /vendor_registry/analysis/{analysis_key}
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `analysis_key` | string | Chave única da análise (UUID) |

## Response

STATUS 200

```json title="Response Body"
{
    "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "status": "pending_adm_approval",
    "requires_invoice": true,
    "manager": {
        "name": "EXEMPLO GESTORA LTDA",
        "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
        "document_number": "45.585.471/0001-47"
    },
    "vendor": {
        "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "name": "AUDITORES EXEMPLO S.A.",
        "document_number": "12.345.678/0001-90",
        "requires_invoice": true,
        "status": "pending_analysis"
    },
    "payment_method": "transfer",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90"
        },
        "target_account": {
            "account_number": "123456",
            "account_branch": "0001",
            "account_digit": "0",
            "financial_institution_code": "341",
            "financial_institution_ispb": "60701190"
        }
    }
}
```

## Possíveis erros

STATUS 404

**Análise não encontrada**

A `analysis_key` informada não corresponde a nenhuma análise cadastrada.

```json
{
  "title": "Analysis not found",
  "description": "Analysis with the key {analysis_key} was not found.",
  "translation": "A análise com a chave {analysis_key} não foi encontrada.",
  "code": "VRG000007"
}
```

---

## Próximos passos

Com a `vendor_key` de um fornecedor `active` em mãos, prossiga para:

**[Criar contrato](/documentation/iaas/despesas/submissao_despesa/contrato/criacao)** — vincule o fornecedor ao fundo e defina o tipo de despesa.

---

# Submissão para Análise

URL: /documentation/iaas/despesas/submissao_despesa/fornecedor/submissao

Após [criar a análise](/documentation/iaas/despesas/submissao_despesa/fornecedor/criacao) e [fazer upload dos documentos](/documentation/iaas/despesas/submissao_despesa/fornecedor/documentos), submeta a análise para revisão da QI Tech alterando o status para `pending_adm_approval`.

:::caution Pré-requisito
É obrigatório ter ao menos um documento com status `pending_adm_approval` ou `approved` antes de submeter a análise. Caso contrário, a requisição será rejeitada com erro `VGR000030`.
:::

---

## Submeter a análise

ENDPOINT /vendor_registry/analysis/{analysis_key}
MÉTODO PUT

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `analysis_key` | string | Chave única da análise (UUID) |

```json title="Request Body"
{
    "status": "pending_adm_approval"
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Valores aceitos | Descrição |
|---|---|---|---|---|
| `status` | string | obrigatório | `pending_adm_approval`, `pending_submission` | Novo status da análise. Use `pending_adm_approval` para submeter para revisão, ou `pending_submission` para retornar ao rascunho. |

## Response

STATUS 202

```json title="Response Body"
{
    "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "status": "pending_adm_approval"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `analysis_key` | string | Chave única da análise. |
| `status` | string | Novo status da análise. |

---

## Ciclo de vida da análise

A tabela abaixo descreve todas as transições de status possíveis e quem as executa:

| Status | Descrição | Quem transita |
|---|---|---|
| `pending_submission` | Análise criada, aguardando submissão | Estado inicial; agente retorna para edição |
| `pending_adm_approval` | Submetida, aguardando revisão da QI Tech | Agente integrador |
| `approved` | Aprovada pela QI Tech; fornecedor ativado | QI Tech (interno) |
| `rejected` | Rejeitada pela QI Tech | QI Tech (interno) |
| `canceled` | Cancelada pelo agente integrador | Agente integrador via [endpoint de cancelamento](/documentation/iaas/despesas/submissao_despesa/fornecedor/cancelamento) |
| `other_analysis_approved` | Outra análise do mesmo fornecedor foi aprovada primeiro | Automático |

### Transições permitidas pelo agente integrador

```
pending_submission ──→ pending_adm_approval  (submissão para revisão)
pending_submission ──→ canceled              (cancelamento)
pending_adm_approval ──→ pending_submission  (retorno para edição)
pending_adm_approval ──→ canceled            (cancelamento)
```

:::info Edição após retorno
Quando a QI Tech retorna a análise para `pending_submission`, é possível atualizar os dados de pagamento e a flag `requires_invoice` antes de submeter novamente. Consulte a página de [atualização de dados](/documentation/iaas/despesas/submissao_despesa/fornecedor/atualizacao).
:::

---

## Possíveis erros

STATUS 400

**Análise sem documentos**

A análise não possui nenhum documento com status `pending_adm_approval` ou `approved`. Faça o [upload de ao menos um documento](/documentation/iaas/despesas/submissao_despesa/fornecedor/documentos) antes de submeter.

```json
{
  "title": "Analysis Submission Must Have At Least One Pending Analysis Document",
  "description": "Analysis with key {analysis_key} must have at least one pending analysis document to be submitted.",
  "translation": "A análise com a chave {analysis_key} deve ter pelo menos um documento de análise pendente para ser enviada.",
  "code": "VGR000030"
}
```

STATUS 409

**Transição de status não permitida**

A transição de status solicitada não é permitida para o status atual da análise.

```json
{
  "title": "Analysis Status Transition Denied",
  "description": "Analysis with key {analysis_key} is not allowed to switch status from {current_status} to {new_status}.",
  "translation": "Análise com chave {analysis_key} não pode trocar de status de {current_status} para {new_status}.",
  "code": "VRG000008"
}
```

**Análise já rejeitada**

Análises rejeitadas não podem ter o status alterado.

```json
{
  "title": "Canceled Analysis",
  "description": "Analysis with key {analysis_key} is already rejected, it can't be updated.",
  "translation": "Análise com chave {analysis_key} está rejeitada, não pode ser atualizada.",
  "code": "VRG0000009"
}
```

**Análise já aprovada**

Análises aprovadas não podem ter o status alterado.

```json
{
  "title": "Completed Analysis",
  "description": "Analysis with key {analysis_key} is already completed, it can't be updated.",
  "translation": "Análise com chave {analysis_key} está finalizada, não pode ser atualizada.",
  "code": "VRG0000010"
}
```

STATUS 404

**Análise não encontrada**

A `analysis_key` informada na URL não corresponde a nenhuma análise cadastrada.

```json
{
  "title": "Analysis not found",
  "description": "Analysis with the key {analysis_key} was not found.",
  "translation": "A análise com a chave {analysis_key} não foi encontrada.",
  "code": "VRG000007"
}
```

---

## Próximos passos

Após submeter a análise, o processo de revisão da QI Tech se inicia. Durante este período:

- **[Acompanhar o status](/documentation/iaas/despesas/submissao_despesa/fornecedor/listagem#consultar-análise-por-chave)** — verifique o progresso da análise.
- **[Responder anotações](/documentation/iaas/despesas/submissao_despesa/fornecedor/anotacoes)** — responda eventuais solicitações da equipe de análise.

Após aprovação, a `vendor_key` do fornecedor estará disponível para uso em contratos de despesa.

---

# Submissão de Despesas

URL: /documentation/iaas/despesas/submissao_despesa/inicio

Esta seção documenta as APIs que viabilizam o processo de Submissão de Despesas para Fundos de Investimento administrados pela QI CTVM. Por meio dessas APIs, é possível registrar contratos com fornecedores, submeter despesas individuais e acompanhar o ciclo de aprovação de cada lançamento.

## Fluxo de submissão

O diagrama abaixo ilustra as etapas do fluxo:

![Etapas do fluxo de submissão de despesas](/img/diagrams/iaas-despesas-inicio.svg)

## Passo a passo

### 0. Cadastro do Fornecedor (pré-requisito)

Antes de criar um contrato, o fornecedor que prestará serviços ao fundo deve estar cadastrado na plataforma. Esse cadastro é realizado pela equipe de operações da QI Tech. Após o cadastro, a `vendor_key` é disponibilizada para uso nos contratos.

**[Acessar documentação do cadastro de fornecedor](/documentation/iaas/despesas/submissao_despesa/fornecedor/criacao)** | **[Consultar fornecedores cadastrados](/documentation/iaas/despesas/submissao_despesa/fornecedor/listagem)**

### 1. Criação do Contrato

Crie um contrato vinculando o fundo a um fornecedor e definindo o tipo de despesa. O contrato é o contêiner que agrupa todas as despesas de uma mesma relação comercial.

**[Acessar documentação da criação do contrato](/documentation/iaas/despesas/submissao_despesa/contrato/criacao)**

### 2. Submissão do Contrato para Aprovação

Após criar e revisar o contrato, submeta-o para análise da QI Tech. O contrato passará para o status `pending_adm_approval` até ser aprovado ou rejeitado.

**[Acessar documentação da submissão do contrato](/documentation/iaas/despesas/submissao_despesa/contrato/submissao)**

### 3. Criação da Despesa

Com o contrato aprovado, crie as despesas individuais informando os dados de pagamento, período de competência e documentos comprobatórios. Ao incluir documentos na criação, a despesa é automaticamente encaminhada para revisão.

**[Acessar documentação da criação da despesa](/documentation/iaas/despesas/submissao_despesa/despesa/criacao)**

### 4. Upload de Documentos (quando não incluídos na criação)

Caso os documentos não tenham sido incluídos na criação da despesa, faça o upload separadamente antes de submeter.

**[Acessar documentação de upload de documentos](/documentation/iaas/despesas/submissao_despesa/documentos/upload)**

### 5. Submissão da Despesa para Aprovação

Submeta a despesa para análise da QI Tech. É obrigatório que ao menos um documento esteja anexado antes da submissão.

**[Acessar documentação da submissão da despesa](/documentation/iaas/despesas/submissao_despesa/despesa/submissao)**

:::info Processamento interno
Após a aprovação da despesa pela QI Tech, o lançamento é processado internamente e registrado na carteira do fundo de forma automática.
:::

## Status do contrato

| Status | Descrição |
|---|---|
| `created` | Contrato criado, aguardando submissão |
| `pending_adm_approval` | Submetido, aguardando análise da QI Tech |
| `approved` | Aprovado pela QI Tech |
| `rejected` | Rejeitado pela QI Tech |
| `canceled` | Cancelado pelo agente integrador |

## Status da despesa

| Status | Descrição |
|---|---|
| `created` | Despesa criada, aguardando documentos ou submissão |
| `pending_adm_approval` | Submetida (ou criada com documentos), aguardando análise da QI Tech |
| `approved` | Aprovada pela QI Tech |
| `rejected` | Rejeitada pela QI Tech |
| `canceled` | Cancelada pelo agente integrador |

---

# Emissões - Integralização

URL: /documentation/iaas/emissoes/cadastrar_boleta

---

## Integralização

Utilizando o endpoint a seguir, é possível iniciar a integralização em uma emissão.

### Request

ENDPOINT /trade_security/fund_class/FUND_CLASS_KEY/integralization
MÉTODO POST

```json title="Request Body"
{
 "security_external_id": "a23c006c-befd-40e0-bc3d-fbd2dfbbea5d",
 "bookkeeper_document_number": "00.000.000/0000-00",
 "security_key": "272a394a-e3d0-4484-b00e-e18a4e22bb5e",
 "unit_price": "2.00",
 "number_of_units": "100.00",
 "external_id": "90b679c0-2674-4cad-917a-5c786b0bf992",
 "integralization_date": "2025-05-27",
 "payment": {
   "target_account": {
    "account_branch": "0001",
    "account_digit": "0",
    "account_number": "12345",
    "financial_institution_code": "329",
    "financial_institution_ispb": "32402502"
   }
  }
}

```

### Definições

#### Operação de Compra

| Campo                         | Tipo   | Descrição                                        | Obrigatório |
| ------------------------------| ------ | ------------------------------------------------ | ----------- |
| `security_external_id`        | string | Identificador externo do ativo                   | Sim*        |
| `bookkeeper_document_number`  | string | Número do CNPJ do escriturador                   | Sim*        |
| `security_key`                | string | Chave interna do ativo                           | Sim*        |
| `unit_price`                  | float  | Valor unitário na integralização                 | Sim         |
| `number_of_units`             | float  | Número de unidades compradas                     | Sim         |
| `external_id`                 | string | Identificador externo da operação de compra      | Sim         |
| `integralization_date`        | string | Data da integralização                           | Sim         |
| `payment`                     | dict   | Objeto de [pagamento](#pagamento) para liquidação| Sim         |

:::note ⚠️ **Importante** ( * )
A identificação do ativo estruturado pode ser feita de duas formas:

1. Informando o campo `security_key` **(chave interna)**; **ou**
2. Informando **ambos** os campos `security_external_id` e `bookkeeper_document_number`.

Pelo menos **uma das formas de identificação** deve estar presente no payload. Caso ambas estejam presentes, será considerada a chave interna como prioritária.
:::

##### Pagamento

| Campo                        | Tipo   | Descrição                                           | Obrigatório |
| ---------------------------- | ------ | --------------------------------------------------- | ----------- |
| `target_account`             | string | Objeto de [conta bancária](#conta-bancária) para liquidação | Sim         |

##### Conta bancária

| Campo                        | Tipo   | Descrição                                           | Obrigatório |
| ---------------------------- | ------ | --------------------------------------------------- | ----------- |
| `account_branch`             | string | Agência da conta bancária                           | Sim         |
| `account_digit`              | string | Dígito verificador da conta                         | Sim         |
| `account_number`             | string | Número da conta bancária                            | Sim         |
| `financial_institution_code` | string | Código da instituição financeira                    | Sim         |
| `financial_institution_ispb` | string | Código ISPB da instituição financeira               | Sim         |

### Response

STATUS 201

```json title='Response Body'
{
 "integralization_key": "1568b67b-088e-43be-938b-0f817b805f7a",
 "external_id": "90b679c0-2674-4cad-917a-5c786b0bf992",
 "status": "pending_administrator_approval",
}
```

---

# Cadastro de Ativos - Emissões

URL: /documentation/iaas/emissoes/cadastro_ativo

---

## Criação - Nota Comercial

Utilizando o endpoint a seguir, é possível cadastrar uma nova nota no orquestrador de ativos estruturados.

Os ativos cadastrados surgem no status **pre_operational** para que sejam submetidos os documentos relacionados ao ativo. Deste modo, é possível pré cadastrar um ativo e habilitá-lo para operação somente após as devidas formalizações estarem concluídas, como detalhado no próximo segmento.

A seguir consta uma listagem explicativa dos campos, e o detalhamento de suas obrigatoriedades e tipos.

### Request

ENDPOINT /security/security
MÉTODO POST

```json title='Request Body'
{
    "external_id": "string",
    "asset_type": "commercial_paper",
    "b3_code":"25M000000",
    "isin_code":"BR00ABCDE000",
    "contract_number": "SCR12345",
    "ipoc_code": "string",
    "maturity_date": "YYYY-MM-DD",
    "allowed_managers": ["00.000.000/0000-00", "00.000.000/0000-00", "00.000.000/0000-00"],
    "allowed_consultants": ["00.000.000/0000-00", "00.000.000/0000-00", "00.000.000/0000-00"],
    "issuer_document_number": "00.000.000/0000-00",
    "bookkeeper_document_number": "00.000.000/0000-00",
    "number_of_units": 1,
    "principal_unit_price": 1000000.00,
    "issue_value": 1000000.00,
    "issue_unit_price": 1000000.00,
    "issue_date": "YYYY-MM-DD",
    "amortization_type": "sac",
    "installments": [
        {
            "installment_number": 1,
            "maturity_date": "YYYY-MM-DD",
            "principal_unit_price": 1000000.00,
            "face_unit_price": 1010000.00,
            "amortization_percentage": 1
        }
    ],
    "delay": {
        "fine": {
            "fine_type": "percentage",
            "percentage_value": 0.0
        },
        "interest": {
            "method": "compound",
            "pre_fixed": {
                "monthly_rate": 0.0,
                "calendar_base": "calendar_360"
            }
        }
    },
    "pre_fixed": {
        "monthly_rate": 0.01,
        "calendar_base": "calendar_360"
    },
    "post_fixed": {
        "lag": {
            "amount": 1,
            "reference": "daily"
        },
        "rate": 1,
        "indexer": "di",
        "calendar_base": "workdays"
    }
}

```

## Definições

### Objeto Ativo (Request Body)

| Campo                         | Tipo   | Descrição                                        | Obrigatório |
| ------------------------------| ------ | ------------------------------------------------ | ----------- |
| `asset_type`                  | string | Enumerador que determina o [Tipo de Ativo](#enumerador-tipo-de-ativo) | Sim         |
| `external_id`                 | string | Identificador externo do ativo; Chave utilizada para acessar a entidade | Sim         |
| `b3_code`                     | string | Código cetip do ativo                            | Não         |
| `isin_code`                   | string | Código ISIN (International Securities Identification Number) | Não         |
| `ipoc_code`                   | string | Código IPOC do ativo                             | Não         |
| `allowed_managers`            | list   | Lista com CNPJ's de gestores com permissão de operar na emissão | Não         |
| `allowed_consultants`         | list   | Lista com CNPJ's de consultores com permissão de operar na emissão | Não         |
| `issuer_document_number`      | string | Número do CNPJ ou CPF do emissor                 | Sim         |
| `bookkeeper_document_number`  | string | Número do CNPJ do escriturador                   | Sim         |
| `number_of_units`             | float  | Número de unidades                               | Sim         |
| `issue_unit_price`            | float  | Preço unitário na emissão                        | Sim         |
| `issue_value`                 | float  | Valor do ativo na emissão                        | Sim         |
| `principal_unit_price`        | float  | Valor unitário de princial do ativo na emissão   | Sim         |
| `issue_date`                  | string | Data de emissão no formato `YYYY-MM-DD`          | Sim         |
| `disbursement_date`           | string | Data de emissão no formato `YYYY-MM-DD`          | Sim         |
| `amortization_type`           | string | Enumerador de [Tipo de Amortização](#enumerador-tipo-de-amortização) | Sim         |
| `contract_number`             | string | Número do contrato                               | Sim         |
| `maturity_date`               | string | Data de vencimento do ativo                      | Sim         |
| `installments`                | dict   | Objeto de [parcelas](#objeto-de-parcela)         | Sim         |
| `delay`                       | dict   | Objeto de [atraso](#objeto-atraso)               | Sim         |
| `pre_fixed`                   | dict   | Objeto de [pré fixado](#objeto-pré-fixado)       | Sim         |
| `post_fixed`                  | dict   | Objeto de [pós fixado](#objeto-pós-fixado)       | Não         |

#### Enumerador Tipo de Ativo

| Enumerador   | Descrição     |
|--------------|---------------|
| **commercial_paper** | Ativo do tipo Nota Comercial |
| **debenture** | Ativo do tipo Debênture |
| **cri** | Ativo do tipo CRI |
| **cra** | Ativo do tipo CRA |

#### Enumerador Tipo de Amortização

| Enumerador   | Descrição     |
|--------------|---------------|
| **sac**   | Amortização do tipo SAC |
| **price**   | Amortização do tipo Price |

#### Objeto de Parcela

| Campo                           | Tipo   | Descrição                                  | Obrigatório |
| ------------------------------- | ------ | -------------------------------------------| ----------- |
| `installment_number`            | int    | Número da Parcela                          | Sim         |
| `maturity_date`                 | string | Data de Vencimento no formato `YYYY-MM-DD` | Sim         |
| `principal_unit_price`          | float  | Valor de principal unitário do ativo       | Sim         |
| `face_unit_price`               | float  | Valor de face unitário do ativo            | Sim         |
| `amortization_percentage`       | float  | Porcentagem de Amortização                 | Não         |

#### Objeto Atraso

| Campo                | Tipo   | Descrição                                        | Obrigatório |
|-|-|-|-|
| `fine` | object | Objeto da multa no vencimento. Ver **[Objeto Multa de Atraso](#objeto-multa-de-atraso)**. | Sim |
| `interest` | object | Objeto do juros de mora. Ver **[Objeto Juros de Mora](#objeto-juros-de-mora)**. | Sim |

#### Objeto Multa de Atraso

| Campo | Tipo   | Descrição | Obrigatório |
|-|-|-|-|
| `fine_type` | string | Tipo de Multa. | Sim |
| `percentage_value` | number | Valor da Multa, se tipo da multa for `percentage`. Unidade de medida: de 0 à 1, considerando 0 à 100% | Sim |
| `amount` | number | Valor da Multa, se tipo de multa for `fixed`.  | Sim |

##### Enumerador Tipo da Multa

| Enumerador     | Descrição                                 |
|----------------|-------------------------------------------|
| **percentage** | Multa percentual sobre o valor da parcela |
| **fixed**      | Valor fixo de Multa                       |

#### Objeto Juros de Mora

| Campo | Tipo | Descrição | Obrigatório |
|-|-|-|-|
| `method` * | string | Ver **[Enumerador Método do Juros de Mora](#enumerador-método-do-juros-de-mora)**. | Sim |
| `pre_fixed` * | object | Ver **[Objeto de Pré Fixado](#objeto-pré-fixado)**. | Sim |

##### Enumerador Método do Juros de Mora

| Enumerador   | Descrição                   |
|--------------|-----------------------------|
| **compound** | Para juros de mora composto |
| **simple**   | Para juros de mora simples  |

#### Objeto Pré Fixado

| Campo | Tipo | Descrição | Obrigatório |
|-|-|-|-|
| `calendar_base` *| string | A base de cálculo utilizada. | enumerator |
| `monthly_rate` * | number | A taxa mensal do contrato. Para 1% usar 0.01 | Até 8 casas decimais |

#### Objeto Pós Fixado

| Campo         | Tipo   | Descrição                                           | Obrigatório |
|---------------|--------|-----------------------------------------------------|-------------|
| rate          | int    | Taxa fixa aplicada                                  | Sim         |
| indexer       | string | Índice de referência da correção (di, ipca)         | Sim         |
| calendar_base | string | Tipo de calendário considerado                      | Sim         |

#### Objeto de Lag

| Campo     | Tipo   | Descrição                                      | Obrigatório |
|-----------|--------|------------------------------------------------|-------------|
| amount    | int    | Quantidade de unidades de defasagem            | Sim         |
| reference | string | Unidade de tempo de defasagem                  | Sim         |

#### Enumerador Base de Cálculo

| Enumerador   | Descrição     |
|--------------|---------------|
| **daily** | Para valores diários de atraso |
| **monthly** | Para valores mensais de atraso |

#### Enumerador Referência de Atraso

| Enumerador   | Descrição     |
|--------------|---------------|
| **workdays** | Para base de cálculo dias úteis (252) |
| **calendar_365**   | Para base de cálculos 365 |
| **calendar_360**   | Para base de cálculos 360 |

### Response

STATUS 201

```json title='Response Body'
{
    "security_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "status": "pre_operational",
}
```

<!-- ### Possíveis erros

STATUS 404

Response Body

```json
{
  "title": "Assignment not found",
  "description": "Assignment not found",
  "translation": "Lote não encontrado",
  "code": "TRC000018"
}

```

STATUS 404

Response Body

```json
{
  "title": "Asset type does not exist",
  "description": "Asset type 'invalid_asset_type' does not exist",
  "translation": "Tipo do ativo 'invalid_asset_type' nao existe",
  "code": "TRC000015"
}

```

STATUS 400

Response Body

```json
{
  "title": "Invalid asset type configuration",
  "description": "This assignment can not receive this asset type: ccb",
  "translation": "Esse lote não pode receber esse tipo de ativo: ccb",
  "code": "TRC000025"
}

```

STATUS 400

Response Body

```json
{
  "title": "Assignment is closed",
  "description": "Assignment is closed to insert new assets",
  "translation": "Lote esta fechado para inserir novos ativos",
  "code": "TRC000022"
}

```

STATUS 400

Response Body

```json
{
  "title": "Invalid Document number",
  "description": "Given '000.000.000-00' document number is invalid.",
  "translation": "O numero de document '000.000.000-00' fornecido não é valido.",
  "code": "TRC000009"
}

```

STATUS 400

Response Body

```json
{
  "title": "Originator bond not found",
  "description": "Originator bond not found",
  "translation": "Vinculo com originador não foi encontrado",
  "code": "TRC000019"
}

```

STATUS 400

Response Body

```json
{
  "title": "Already Exist This External Id",
  "description": "Already exist an asset with this External Id",
  "translation": "Ja existe um ativo com esse External Id",
  "code": "TRC000054"
}

```
-->

---

# Confirmação de Emissão

URL: /documentation/iaas/emissoes/confirmacao_emissao

## Confirmação - Nota Comercial

Após ter finalizado todas formalizações, e registrar os devidos documentos no ativo, é possível aprová-lo, sinalizando que está pronto para seguir com operações.

Vale ressaltar que operações de compra podem ser lançadas em ativos pré operacionais, mas estas não poderão ser liquidadas até que a emissão do ativo esteja confirmada.

### Request

ENDPOINT /security/security/EXTERNAL_ID/confirm
MÉTODO PUT

```json title="Request Body"
{
 "bookkeeper_document_number": "00.000.000/0000-00"
}

```

| Campo                         | Tipo   | Descrição                                            | Obrigatório |
| ------------------------------| ------ | ---------------------------------------------------- | ----------- |
| `bookkeeper_document_number`  | string | CNPJ do escriturador para a identificação da emissão | Sim         |

#### Definição

### Response

STATUS 202

```json title='Response Body'
{
    "security_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "status": "active",
}
```

---

# Introdução

URL: /documentation/iaas/emissoes/inicio

O ecossistema de emissões é o responsável pela criação, compra, venda e pagamentos de ativos como Notas Comerciais, Debêntures, CRIs e CRAs. As funcionalidades disponíveis para utilização são:

- Cadastrar um novo ativo pré operacional;
- Confirmar a emissão;
- Criar boleta de compra ou venda;

Esta documentação fornece uma visão detalhada sobre como utilizar o sistema de emissões, incluindo seus principais recursos e fluxos.

Para começar a utilizar o sistema, navegue pelos tópicos disponíveis nesta documentação para entender melhor cada aspecto do módulo de cotas de fundo.

---

# Apontamentos de Compliance

URL: /documentation/iaas/homologacao_cedente/cadastro/apontamentos

Durante o processo de análise cadastral do Cedente, as equipes de Compliance, Risco ou de validação interna podem registrar **apontamentos** (também chamados de *annotations*). Um apontamento é uma solicitação ou questionamento direcionado ao agente responsável pelo cadastro, que precisa ser respondido para que a análise prossiga.

Sempre que um apontamento é criado, ele nasce no status `open` e, caso configurado, é disparado um [Webhook de Apontamento](/documentation/iaas/homologacao_cedente/cadastro/webhooks_analise#webhooks-de-apontamento) notificando a abertura. Também é enviado um e-mail aos destinatários configurados para o agente. Após o agente responder ao apontamento, ele passa para o status `closed` e um novo webhook é disparado.

:::info
Apontamentos só existem enquanto a análise estiver em um dos status `in_manual_analysis`, `pending_internal_validation` ou `in_risk_analysis`. Cada apontamento aceita apenas **uma** resposta.
:::

---

## Consulta Paginada de Apontamentos

Recupera a lista de apontamentos de uma análise, permitindo ao agente identificar o que precisa ser respondido.

### Request

ENDPOINT /assignor_registry/public/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/annotations
MÉTODO GET

### Query params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `limit` | integer | Limite de objetos por página (padrão 10, máximo 50). | - |
| `page` | integer | Página desejada (inicia em 0). | - |

### Response

STATUS 200

```json title='Response Body'
{
    "data": [
        {
            "annotation_key": "1f2e3d4c-5b6a-4c8d-9e0f-1a2b3c4d5e6f",
            "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
            "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4",
            "status": "open",
            "origin_type": "compliance",
            "annotation_datetime": "2025-01-22T20:30:23Z",
            "message": "Anexar detalhes do processo XXXXXXXXXXX."
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true
}
```

### Erros Tratáveis

| Código | HTTP | Causa | Como resolver |
|--------|------|-------|---------------|
| ASR000026 | 404 | Agente não encontrado para a `AGENT-KEY` informada. | Verificar se a chave do agente autenticado está correta. |

---

## Consulta de Apontamento por Chave

### Request

ENDPOINT /assignor_registry/public/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/annotation/ANNOTATION_KEY
MÉTODO GET

### Response

STATUS 200

```json title='Response Body'
{
    "annotation_key": "1f2e3d4c-5b6a-4c8d-9e0f-1a2b3c4d5e6f",
    "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4",
    "status": "closed",
    "origin_type": "compliance",
    "annotation_datetime": "2025-01-22T20:30:23Z",
    "message": "Anexar detalhes do processo XXXXXXXXXXX.",
    "response": "Segue autos do processo.",
    "response_datetime": "2025-01-23T14:05:11Z",
    "attached_document_key": "8e515a17-8b4d-49a3-aed6-47c9574e426a"
}
```

:::info
Os campos `response`, `response_datetime` e `attached_document_key` só são retornados quando o apontamento já foi respondido e/ou possui um documento anexado.
:::

### Erros Tratáveis

| Código | HTTP | Causa | Como resolver |
|--------|------|-------|---------------|
| ASR000026 | 404 | Agente não encontrado para a `AGENT-KEY` informada. | Verificar se a chave do agente autenticado está correta. |
| ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto e pertence ao agente autenticado. |
| ASR000033 | 404 | Análise não encontrada para o `analysis_key` informado. | Verificar se o `analysis_key` está correto. |
| ASR000043 | 404 | Apontamento não encontrado para o `annotation_key` informado. | Verificar se o `annotation_key` pertence à análise indicada. |

---

## Resposta ao Apontamento

Envia a resposta do agente a um apontamento. Opcionalmente, é possível anexar um documento em PDF que comprove ou complemente a resposta.

### Request

ENDPOINT /assignor_registry/public/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/annotation/ANNOTATION_KEY
MÉTODO PUT

```json title='Request Body'
{
    "response": "Segue autos do processo.",
    "document_b64": "aGVsbG8gd29ybGQgaWYgeW91IGRlY29kZWQgbWUsIGJlIGNhcmVmdWwuIEl0IG11c3QgYmUgYSBQREYgRmlsZSBvdGhlcndpc2UgSSB3aWxsIHJhaXNlIGFuIEVycm9yLg=="
}
```

### Objeto de Resposta

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `response` * | string | Texto de resposta ao apontamento. | 1 - 3000 |
| `document_b64` | string | Binário do arquivo em PDF, codificado em Base64. | - |

*Campos obrigatórios.

### Response

STATUS 202

```json title='Response Body'
{
    "annotation_key": "1f2e3d4c-5b6a-4c8d-9e0f-1a2b3c4d5e6f",
    "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4",
    "status": "closed",
    "origin_type": "compliance",
    "annotation_datetime": "2025-01-22T20:30:23Z",
    "message": "Anexar detalhes do processo XXXXXXXXXXX.",
    "response": "Segue autos do processo.",
    "response_datetime": "2025-01-23T14:05:11Z",
    "attached_document_key": "8e515a17-8b4d-49a3-aed6-47c9574e426a"
}
```

### Erros Tratáveis

| Código | HTTP | Causa | Como resolver |
|--------|------|-------|---------------|
| ASR000026 | 404 | Agente não encontrado para a `AGENT-KEY` informada. | Verificar se a chave do agente autenticado está correta. |
| ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto e pertence ao agente autenticado. |
| ASR000033 | 404 | Análise não encontrada para o `analysis_key` informado. | Verificar se o `analysis_key` está correto. |
| ASR000043 | 404 | Apontamento não encontrado para o `annotation_key` informado. | Verificar se o `annotation_key` pertence à análise indicada. |
| ASR000045 | 400 | O apontamento não está mais em status `open` e não aceita mais respostas. | Só é possível responder apontamentos com status `open`. |
| ASR000044 | 400 | O apontamento já foi respondido. | Cada apontamento aceita apenas uma resposta. |
| ASR000005 | 400 | Formato de arquivo inválido. | Enviar `document_b64` como string em base64 válida. |
| ASR000060 | 400 | O arquivo enviado não é um PDF válido. | O conteúdo decodificado de `document_b64` deve ser um PDF. |
| ASR000059 | 400 | Tamanho do arquivo excede o limite. | Reduzir o tamanho do PDF antes de enviar (limite informado na mensagem do erro). |

---

## Consulta de Documento do Apontamento

Recupera uma URL temporária para download do documento anexado a um apontamento.

### Request

ENDPOINT /assignor_registry/public/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/annotation/ANNOTATION_KEY/document/DOCUMENT_KEY
MÉTODO GET

### Response

STATUS 200

```json title='Response Body'
{
    "document_url": "https://assignor-bucket.s3.amazonaws.com/8e515a17-8b4d-49a3-aed6-47c9574e426a?..."
}
```

:::info
A `document_url` retornada é uma URL pré-assinada com validade de 24 horas.
:::

### Erros Tratáveis

| Código | HTTP | Causa | Como resolver |
|--------|------|-------|---------------|
| ASR000026 | 404 | Agente não encontrado para a `AGENT-KEY` informada. | Verificar se a chave do agente autenticado está correta. |
| ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto e pertence ao agente autenticado. |
| ASR000033 | 404 | Análise não encontrada para o `analysis_key` informado. | Verificar se o `analysis_key` está correto. |
| ASR000043 | 404 | Apontamento não encontrado para o `annotation_key` informado. | Verificar se o `annotation_key` pertence à análise indicada. |
| ASR000006 | 404 | Documento não encontrado para o `document_key` informado. | Verificar se o `document_key` corresponde ao documento anexado ao apontamento. |

---

## Objeto de Apontamento

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `annotation_key` | string | Identificador único do apontamento. |
| `analysis_key` | string | Chave da análise à qual o apontamento pertence. |
| `assignor_registry_key` | string | Chave do cedente. |
| `status` | string | Status atual do apontamento. Ver **[Annotation Status](#annotation-status)**. |
| `origin_type` | string | Origem do apontamento. Ver **[Annotation Origin Type](#annotation-origin-type)**. |
| `annotation_datetime` | string | Data e hora de criação do apontamento (ISO 8601). |
| `message` | string | Mensagem do apontamento registrada pela equipe da QI DTVM. |
| `response` | string | Resposta enviada pelo agente (presente após a resposta). |
| `response_datetime` | string | Data e hora da resposta (presente após a resposta). |
| `attached_document_key` | string | Chave do documento anexado à resposta (quando houver). |

### Annotation Status

| Enumerador | Descrição |
| ---------- | --------- |
| **created** | Apontamento criado, ainda não disponibilizado. |
| **open** | Aberto e aguardando resposta do agente. |
| **closed** | Respondido e encerrado. |

### Annotation Origin Type

| Enumerador | Descrição |
| ---------- | --------- |
| **compliance** | Apontamento originado pela equipe de Compliance (análise manual). |
| **risk_analysis** | Apontamento originado pela equipe de Risco. |
| **internal** | Apontamento originado na validação interna. |

---

# Atualização de Cadastro

URL: /documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro

É de responsabilidade do gestor manter os dados dos cedentes atualizados, de acordo com a situação atual da companhia. Este comprometimento é de extrema importancia, tanto para manter as análises de PLD atualizadas quanto para atualizar os grupos de assinantes, que mudam constantemente e expiram, sendo necessária uma nova análise. Além disso, a cada 2 anos, automaticamente é gerada uma nova análise para garantir a atualização periódica dos mesmos.

:::warning Aviso
É de responsabilidade do gestor manter os dados do cedente atualizados e refletindo a realidade da companhia.
:::

Ao atualizar um cadastro, independente de qual campo for alterado, uma nova análise será gerada, a qual exigirá novos documentos de acordo com as alterações relalizadas. As análises seguem um sequencial, e podem falhar inúmeras vezes até serem finalmente aprovadas pelo compliance. As alterações só serão aplicadas após a análise ser concluída com sucesso. Caso as partes relacionadas sejam alteradas, haverá uma etapa de validação dos grupos de assinantes do cedente. Vale ressaltar que caso uma parte relacionada ou um avalista NÃO for enviado, o mesmo será considerado EXCLUÍDO.

:::info
Caso uma análise esteja em andamento, e uma atualização cadastral seja enviada, a última análise em aberto será automaticamente fechada, sendo recusada, com motivo "assignor_update".
:::

---

## Atualização de Cadastro de Cedente Pessoa Jurídica

### Request

ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY
MÉTODO PUT

```json title='Request Body'
{
  "email": "qidtvm@qitech.com.br",
  "annual_revenues": 1000000,
  "is_in_national_financial_system": true,
  "address": {
    "street": "Rua Maria Carolina",
    "number": "624",
    "neighborhood": "Jardim Paulistano",
    "city": "São Paulo",
    "postal_code": "01445-000",
    "uf": "SP",
    "country": "BRA"
  },
  "phone": {
    "international_dial_code": "+55",
    "area_code": "11",
    "number": "936360268"
  },
  "related_parties": [
    {
      "name": "Natália Nascimento",
      "document_number": "883.512.866-80",
      "related_party_type": "attorney",
      "nationality": "BRA",
      "direct_beneficiary": true,
      "is_representative": true,
      "email": "natalia.nascimento@yopmail.com",
      "phone": {
        "international_dial_code": "+55",
        "area_code": "11",
        "number": "936360268"
      }
    },
    {
      "name": "Maria Vitoria",
      "related_party_type": "president",
      "nationality": "DEU",
      "passport_number": "C01X00T47",
      "direct_beneficiary": true,
      "is_representative": false

    },
    {
      "name": "Roberto Carlos",
      "document_number": "802.834.257-41",
      "related_party_type": "director",
      "nationality": "BRA",
      "direct_beneficiary": false,
      "company_country": "NZL",
      "company_registry_number": "4984037284610",
      "is_representative": true,
      "email": "roberto.carlos@yopmail.com",
      "phone": {
        "international_dial_code": "+64",
        "area_code": "11",
        "number": "936360268"
      }
    }
  ],
  "guarantors": [
    {
      "name": "Avalista PF",
      "document_number": "172.775.419-01",
      "person_type": "natural_person",
      "email": "email@avalista.com"
    },
    {
      "name": "Avalista PJ",
      "document_number": "65.679.662/0001-85",
      "person_type": "legal_person",
      "email": "email@avalista.com",
      "guarantor_representatives": [
        {
          "name": "Assinante do Avalista",
          "document_number": "244.412.084-13",
          "email": "emailrepresentante@avalista.com"
        }
      ]
    },
  ]
}
```

---

### Definição do Cedente

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `annual_revenues`  | number | Declaração de faturamento anual do cedente. | - |
| `email`  | string | Endereço de e-mail do cedente. | 1 a 255 |
| `is_in_national_financial_system`  | boolean | Indicador se o cedente é integrante do SFN. | - |
| `phone`  | object | Objeto referenciando as informações do telefone do cedente. | Ver **[Definição de Telefone](#definição-de-telefone)**. |
| `address`  | object | Objeto referenciando as informações do endereço do cedente. | Ver **[Definição de Endereço](#definição-de-endereço)**. |
| `related_parties`  | array | Lista de partes relacionadas da empresa.| Ver  **[Definição de Parte Relacionada](#definição-de-parte-relacionada)**. |
| `guarantors` | array | Lista de avalistas do cedente.| Ver  **[Definição de Avalista](#definição-de-avalista)**. |

Caso não deseje alterar um campo, basta não enviá-lo na request. Para listas, como é o caso de `related_parties` e `guarantors`, caso uma lista vazia seja enviada, ou uma parte previamente indicada na lista, e não indicada na nova, será tratado como exclusão.

### Response

STATUS 200

```json title='Response Body'
{
  "assignor_registry_key": "c4295375-4077-4092-a258-5bcdf8875907",
  "status": "registred",
  "name": "QI Tech",
  "document_number": "32.402.502/0001-35",
  "last_analysis": {
    "analysis_key": "d7805a05-98a7-486b-a440-807f1d3d5691",
    "analysis_number": 2,
    "status": "pending_documents",
    "analysis_related_parties": [
      {
        "analysis_related_party_key": "5cdcc13b-c67d-45f3-aa66-36cb4f178b59",
        "document_number": "802.834.257-41",
        "name": "Roberto Carlos",
        "documents": []
      },
      {
        "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721",
        "document_number": "883.512.866-80",
        "name": "Natália Nascimento",
        "documents": []
      },
      {
        "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721",
        "passport_number": "C01X00T47",
        "name": "Maria Vitoria",
        "documents": []
      }
    ],
    "documents": [
      {
        "document_key": "994621ac-7d3f-4f6b-90c5-74a4d8c5d017",
        "document_type": "social_contract",
        "status": "valid",
      }
    ],
    "analysis_data": {}
  }
}
```

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `assignor_registry_key` | string | Identificador do cadastro. | 36 |
| `status` | string | Status do cadastro. | Ver **[Enumeradores de status do cadastro](#assignor-registry-status)**. |
| `name` | string | Nome do Cedente. | 1 a 255 |
| `document_number` | string | Documento do Cedente. | 14 a 18 |
| `last_analysis`  | object | Objeto de análise. | Ver **[Definição de Análise](#definição-de-análise)**. |

:::info
É importante armazenar a `analysis_key` e as `analysis_related_party_key` que serão utilizadas para envio de documentos do cedente e das partes relacionadas.
:::

---

:::caution Atenção!
Ao atualizar o cadastro de um cedente, uma nova análise cadastral é gerada, resultando em uma nova `analysis_key` e novas `analysis_related_party_key`. O cadastro só será efetivamente atualizado após a aprovação desta nova análise. 
:::

:::caution Importante!
Não é possível atualizar dados essenciais do cedente como **Número do Documento**, **Tipo de Pessoa**. Os dados cadastrais passíveis de alteração incluem:
- Nome/Razão Social;
- Email;
- Endereço;
- Telefone;
- Faturamento;
- Participante do SFN;
- Partes Relacionadas (inclusão e alteração de vigentes);
- Avalistas (inclusão e alteração de vigentes);
:::

### Erros Tratáveis

| Código | HTTP | Causa | Como resolver |
|--------|------|-------|---------------|
| ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` existe e pertence ao agente autenticado. |
| ASR000100 | 400 | Campo enviado não pode ser atualizado em uma filial. | Para filiais, somente `email`, `phone`, `address` e `annual_revenues` podem ser atualizados. Para alterar `name`, `is_in_national_financial_system`, `related_parties` ou `guarantors`, atualizar o cadastro da matriz. |
| ASR000056 | 400 | Pessoa física não pode ser participante do Sistema Financeiro Nacional. | Para cedentes pessoa física, enviar `is_in_national_financial_system=false` ou omitir o campo. |
| ASR000054 | 400 | Cedente pessoa jurídica deve ter pelo menos 1 parte relacionada. | Garantir que `related_parties` (após a atualização) tenha ao menos um item para cedentes pessoa jurídica. |
| ASR000057 | 400 | Cedente pessoa jurídica deve ter pelo menos 1 representante assinante. | Garantir que ao menos uma parte relacionada tenha `is_representative=true`. |
| ASR000011 | 400 | Número de documento de parte relacionada duplicado. | Cada `document_number` em `related_parties` deve ser único. |
| ASR000041 | 400 | Email obrigatório para representante. | Para partes relacionadas com `is_representative=true`, informar `email`. |
| ASR000058 | 400 | Pessoa estrangeira sem CPF não pode ser assinante. | Estrangeiros sem `document_number` (CPF) não podem ter `is_representative=true`. |
| ASR000078 | 400 | Número de documento de avalista duplicado. | Cada avalista em `guarantors` deve ter `document_number` único. |
| ASR000079 | 400 | Avalista pessoa física não pode receber representantes. | Não enviar `guarantor_representatives` para avalistas com `person_type=natural_person`. |
| ASR000080 | 400 | Documento de representante de avalista duplicado. | Cada representante em `guarantor_representatives` deve ter `document_number` único. |
| ASR000091 | 400 | Avalista pessoa jurídica deve ter pelo menos um representante. | Para `person_type=legal_person`, enviar pelo menos um item em `guarantor_representatives`. |

---
## Definições

### Definição de Endereço

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `street` * | string | Nome da rua. | 1 a 255 |
| `number` * | string | Número do endereço. | 1 a 4 |
| `neighborhood` * | string | Bairro. | 1 a 255 |
| `city` * | string | Cidade. | 1 a 255 |
| `uf` * | string | Sigla do estado. | 2 |
| `complement` | string | Complemento do endereço. | 1 a 255 |
| `postal_code` * | string | Código postal. | 9 (formato: XXXXX-XXX) |
| `country` * | string | País (sigla). | 3 |

*Campos obrigatórios.

---

### Definição de Telefone

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `international_dial_code` * | string | Código internacional de discagem. | 1 a 3 |
| `area_code` * | string | Código de área. | 2 |
| `number` * | string | Número de telefone. | 8 a 9 |

*Campos obrigatórios.

---

### Definição de Parte Relacionada

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `name` * | string | Nome da parte relacionada. | 1 a 255 |
| `document_number` ** | string | Número de documento do beneficiário (CPF). | 14 a 18 |
| `passport_number` ** | string | Número de documento do beneficiário estrangeiro. | 8 a 9 |
| `related_party_type` * | string | Tipo de vínculo da parte relacionada. | Ver **[Enumeradores de tipo de parte relacionada](#related-party-type)** |
| `nationality` * | string | País de origem do beneficiário. | 3, de acordo com a ISO 3166-1 alpha-3 |
| `direct_beneficiary` * | boolean | Beneficiário diretamente ou indiretamente ligado ao cedente. | 1 a 255 |
| `is_representative` * | boolean | Indicador se a parte relacionada é representante assinante do cedente. | 1 a 255 |
| `company_registry_number` *** | string | Caso não seja diretamente ligado ao cedente, à qual companhia o mesmo está ligado. | 1 a 255 |
| `company_country` *** | string | País onde a companhia-elo entre o beneficiário e o cedente está registrada. | 3, de acordo com a ISO 3166-1 alpha-3 |
| `address` | object | Objeto referenciando as informações do endereço do representante. | Ver **[Definição de Endereço](#definição-de-endereço)**. |
| `email` **** | string | Endereço de e-mail do representante. | 1 a 255 |
| `phone` | object | Objeto referenciando as informações do telefone do representante. |  Ver **[Definição de Telefone](#definição-de-telefone)**. |
| `marital_status` | string | Estado civil da parte relacionada. | Ver **[Enumeradores de estado civil](#marital-status)**. |
| `property_system` | string | Regime de separação de bens. | Ver **[Enumeradores de regime de separação de bens](#property-system)**. |
| `profession` | string | Profissão da parte relacionada. | 1 a 255. |

*Campos obrigatórios.

**document_number obrigatório para brasileiros, e passport_number para estrangeiros.

***Campos obrigatórios caso a parte relacionada não seja beneficiário diretamente ligada ao cedente.

****Campos exigidos apenas para representantes assinantes.

---

### Definição de Análise

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `analysis_key` * | string | Identificador da análise. | 36 |
| `analysis_number` * | integer | Número sequencial da análise. | - |
| `status` * | string | Status da análise. | Ver **[Enumeradores de status de análise](#analysis-status)**. |
| `analysis_related_parties` * | array | Partes Relacionadas da análise. | Ver **[Definição de Partes Relacionadas de Análise](#definição-de-partes-relacionadas-de-análise)**. |
| `documents` * | array | Documentos da anáise. | Ver **[Definição de Documentos de análise](#definição-de-documentos)**. |
| `analysis_data` * | object | Payload da request que originou a análise. | - |
| `analysis_datetime` * | string | Objeto date time da criação da análise. | - |
| `reproval_reason` | string | Enumerador com o motivo de rejeição da análise. | Ver **[Enumeradores de motivo de reprovação](#analysis-reproval-reason)**. |
| `reproval_details` | string | Campo livre com detalhes da rejeição da análise. | - |

*Campos obrigatórios.

---

### Definição de Avalista

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `name` * | string | Nome do Avalista. | 3 - 255 |
| `document_number` * | string | Número de documento do avalista. | 14 a 18 |
| `person_type` * | string | Tipo de pessoa (física ou jurídica) do cedente. | - |
| `email` * | string | Endereço de e-mail do avalista. | 1 a 255 |
| `nationality` | string | País de origem do avalista. | 3, de acordo com a ISO 3166-1 alpha-3 |
| `phone` | object | Objeto referenciando as informações do telefone do avalista. |  Ver **[Definição de Telefone](#definição-de-telefone)**. |
| `address` | object | Objeto referenciando as informações do endereço do avalista. | Ver **[Definição de Endereço](#definição-de-endereço)**. |
| `guarantor_representatives` | array | Assinantes do Avalista - Apenas para avalista pessoa jurídica. | Ver  **[Definição de Representante do Avalista](#definição-de-representante-do-avalista)**. |
| `marital_status` | string | Estado civil do avalista. | Ver **[Enumeradores de estado civil](#marital-status)**. |
| `property_system` | string | Regime de separação de bens. | Ver **[Enumeradores de regime de separação de bens](#property-system)**. |
| `profession` | string | Profissão do avalista. | 1 a 255. |

*Campos obrigatórios.

Os representantes do avalista devem ser enviados apenas para o avalista pessoa jurídica.

:::warning Atenção
Tanto o avalista quanto os representantes também serão adicionados à anáise gerada, sendo necessário enviar os documentos padrão de acordo com o tipo de pessoa do mesmo. Também passarão pelo processo de compliance, podendo gerar apontamentos.
:::

---

### Definição de Representante do Avalista

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `name` * | string | Nome do Representante. | 3 - 255 |
| `document_number` * | string | Número de documento do representante do avalista - obrigatóriamente pessoa física. | 14 |
| `email` * | string | Endereço de e-mail do representante do avalista. | 1 a 255 |
| `nationality` | string | País de origem do representante do avalista. | 3, de acordo com a ISO 3166-1 alpha-3 |
| `address` | object | Objeto referenciando as informações do endereço do representante do avalista. | Ver **[Definição de Endereço](#definição-de-endereço)**. |
| `phone` | object | Objeto referenciando as informações do telefone do representante do avalista. |  Ver **[Definição de Telefone](#definição-de-telefone)**. |
| `marital_status` | string | Estado civil do representante do avalista. | Ver **[Enumeradores de estado civil](#marital-status)**. |
| `property_system` | string | Regime de separação de bens. | Ver **[Enumeradores de regime de separação de bens](#property-system)**. |
| `profession` | string | Profissão do representante do avalista. | 1 a 255. |

---

### Definição de Documentos

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `document_key` * | string | Identificador do documento. | 36 |
| `document_type` * | string | Tipo do documento. | Ver **[Enumeradores de tipo de documento](#document-type)**. |
| `status` | string | Status do documento. | Ver **[Enumeradores de status de documento](#document-status)**. |
| `observation` | string | Observações enviadas. | - |

*Campos obrigatórios.

---

### Definição de Partes Relacionadas de análise

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `analysis_representative_key` * | string | Identificador do representante. | 36 |
| `document_number` * | string | Número de documento do representante. | 14 a 18 |
| `name` | string | Nome do beneficiário. | 1 a 255 |
| `documents` * | enumerador | Documentos da anáise do representante. | Ver **[Definição de Documentos de análise](#definição-de-documentos)**. |

*Campos obrigatórios.

---

# Enumeradores

### Assignor Registry Status

| Enumerador                 | Descrição       |
| -------------------------- | ----------------- |
| **pending_registry** | Pendente Registro |
| **registered**       | Registrado        |

---

### Analysis Status

| Enumerador              | Descrição           |
| ----------------------- | --------------------- |
| **pending_documents**  | Pendente Documentos   |
| **sent_to_analysis**   | Enviado para Análise |
| **pending_internal_validation** | Em Validação de documentos    |
| **in_manual_analysis** | Em Análise Manual de Compliance    |
| **approved**           | Aprovado              |
| **reproved**           | Reprovado             |
| **canceled**           | Cancelado             |

---

### Related Party Type

| Enumerador              | Descrição   |
| ----------------------- | ------------- |
| **president**     | Presidente    |
| **partner**       | Sócio        |
| **administrator** | Administrador |
| **director**      | Diretor       |
| **manager**       | Gestor        |
| **attorney**      | Procurador    |

---

### Document Status

| Enumerador              | Descrição   |
| ----------------------- | ------------- |
| **created**     | Criado    |
| **valid**       | Válido        |
| **invalid** | Inválido |
| **canceled** | Cancelado |
| **accepted** | Aceito, porém não validado |

---

### Document Type

| Enumerador                   | Descrição                |
| ---------------------------- | -------------------------- |
| **cnh**                      | CNH.                        |
| **rg_back**                  | RG parte traseira.          |
| **rg_front**                 | RG parte frontal.           |
| **passport**                 | Passaporte - exclusivo para estrangeiros.           |
| **national_migration_registry**                 | Registro Nacional de Migração.           |
| **cin_digital**                 | Carteira de Identidade Nacional (Digital).           |
| **social_contract**          | Contrato/Estatuto Social.   |
| **cnpj_card**          | Cartão CNPJ.   |
| **commercial_board_certificate** | Certidão Simplidicada da Junta Comercial. |
| **board_election_record** | Ata de Eleição da Diretoria Vigente. |
| **power_of_attorney**        | Procuração - obrigatório caso o representante seja um procurador. |
| **marital_power_of_attorney**        | Procuração Uxória - disponível apenas para cônjuges. |
| **compliance_statement**        | Parecer de Compliance. |
| **financial_statement**        | Demonstração Financeira. |
| **credit_report**        | Ata/Parecer de Crédito. |
| **manager_statement**        | Parecer/Ficha do Gestor. |
| **visit_report**        | Relatório de Visita. |
| **proof_of_residence**        | Comprovante de Residência. |
| **credit_agency_consulation**        | Consulta aos órgãos de Proteção de Crédito. |
| **annual_revenues_declaration**        | Declaração de Faturamento. |
| **financial_institutions_declaration**        | Declaração de Relacionamento Bancário. |
| **additional_document**        | Documento adicional - livre. |

---

### Analysis Reproval Reason
| Enum         | 	Description  |
|--------------|---------------|
| **assignor_update**   | Análise cancelada devido à atualização cadastral posterior |
| **insuficient_documents**  | Documentação mínima para comprovação de poderes não enviada |
| **compliance_reproval**  | Reprovação de vínculo por análise do time de compliance |
| **unidentified_related_parties** | Parte relacionada enviada, porém vinculo não comprovado |
| **invalid_documents** | Documentação inválida/expirada |
| **missing_related_parties** | Parte relacionada obrigatória não enviada |

---

### Marital Status
| Enum         | 	Description  |
|--------------|---------------|
| **single**   | Solteiro(a)   |
| **married**  | Casado(a)    |
| **widower**  | Viúvo(a)     |
| **divorced** | Divorciado(a) |
| **separated** | Separado(a) |
| **stable_union** | Em União Estável |

---

### Property System

| Enum                              | Descrição                              |
| --------------------------------- | -------------------------------------- |
| **total_communion_of_goods**        | Comunhão Total de Bens                |
| **partial_communion_of_goods**      | Comunhão Parcial de Bens              |
| **total_separation_of_goods**       | Separação Total de Bens               |
| **final_participation_of_acquisitions** | Participação Final nos Aquestos    |
| **compulsory_separation_of_goods**  | Separação Obrigatória de Bens         |

---

# Definição de Assinantes

URL: /documentation/iaas/homologacao_cedente/cadastro/definicao_de_assinantes

Após o envio do cadastro do cedente, é possível, **opcionalmente**, definir conjuntos customizados de assinantes para a operação. Esses conjuntos determinam quais partes relacionadas (do cedente ou de avalistas) devem assinar cada tipo de documento, com possibilidade de regras por tipo de produto.

Caso nenhum conjunto customizado seja enviado, o sistema utiliza os conjuntos padrão definidos pela administradora.

:::info Informação
Os conjuntos de assinantes (`signer_group_sets`) representam grupos de assinantes vinculados a um proprietário (`owner`), que pode ser o **cedente** (`assignor_registry`) ou uma **parte relacionada de análise** (`analysis_related_party`, de avalistas).

A definição customizada permite, por exemplo, exigir múltiplos assinantes, ou restringir quem pode assinar determinado produto.
:::

:::warning Atenção
A definição de conjuntos customizados deve ocorrer antes da etapa de [Envio para Análise](/documentation/iaas/homologacao_cedente/cadastro/disparo_da_analise). Após o envio para análise, os conjuntos vigentes serão utilizados nas assinaturas dos contratos de cessão.
:::

---

## Definição de Conjunto Customizado para o Cedente

Permite ao cliente substituir o conjunto padrão de assinantes do cedente por um ou mais conjuntos customizados, organizados por produto. Os assinantes informados devem corresponder a partes relacionadas previamente cadastradas como representantes do cedente.

### Request

ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/custom_signer_groups
MÉTODO POST

```json title='Request Body'
{
  "signer_group_sets": [
    {
      "product": "assignment_contract",
      "signer_groups": [
        {
          "minimum_required_signers": 2,
          "signers": [
            {
              "document_number": "883.512.866-80",
              "is_required_signer": true
            },
            {
              "document_number": "802.834.257-41",
              "is_required_signer": false
            }
          ],
          "expiration": "2026-12-31"
        }
      ]
    },
    {
      "product": "commercial_paper",
      "signer_groups": [
        {
          "minimum_required_signers": 1,
          "signers": [
            {
              "document_number": "883.512.866-80",
              "is_required_signer": true
            }
          ],
          "expiration": "2026-12-31"
        }
      ]
    }
  ]
}
```

### Response

STATUS 204

Sem conteúdo no corpo de resposta.

:::info Informação
A criação de um conjunto customizado para o cedente substitui o conjunto `main` (padrão) vigente para o produto informado. Apenas os conjuntos com `status` igual a `valid` são utilizados nas assinaturas.
:::

:::warning Atenção
Ao enviar, o grupo de assinantes nasce no status `in_analysis`. Signer groups sets neste status não são enviados para assinatura. Com a aprovação do cadastro, o grupo passa para o status `valid`, e só então, será utilizado para assinaturas acima do `main` signer group.
:::

:::warning Atenção
Caso o `custom` signer group enviado seja **menos restritivo** que o validado pela Administradora, a análise será **negada**.
:::

### Erros Tratáveis

| Código | HTTP | Causa | Como resolver |
|--------|------|-------|---------------|
| ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto. |
| ASR000033 | 404 | Análise não encontrada para o `analysis_key` informado. | Verificar se o `analysis_key` está correto. |
| ASR000066 | 400 | Status da análise não permite definição de grupos customizados. | A análise deve estar em `pending_documents` para receber grupos customizados. |
| ASR000109 | 404 | Tipo de produto inválido. | Usar um valor válido para `product` (ver enum [Product Type](#product-type)). |
| ASR000118 | 400 | Signatário inválido. | O `document_number` enviado em `signers` deve corresponder a um representante já cadastrado para o cedente, com `is_representative=true`. |

---

## Definição de Conjunto Customizado para Parte Relacionada

Permite definir conjuntos customizados para uma parte relacionada específica do cedente — como avalistas (`guarantors`) — utilizando a `analysis_related_party_key` retornada na criação da análise.

:::info Informação
Lembre-se de que avalistas são representados como `analysis_related_party`. Logo, este endpoint é o ponto único para customizar assinantes de qualquer parte vinculada à análise (representantes do cedente, avalistas e representantes de avalistas).
:::

### Request

ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/related_party/ANALYSIS_RELATED_PARTY_KEY/custom_signer_groups
MÉTODO POST

```json title='Request Body'
{
  "signer_group_sets": [
    {
      "product": "assignment_contract",
      "signer_groups": [
        {
          "minimum_required_signers": 1,
          "signers": [
            {
              "document_number": "244.412.084-13",
              "is_required_signer": true
            }
          ],
          "expiration": "2026-12-31"
        }
      ]
    }
  ]
}
```

### Response

STATUS 204

Sem conteúdo no corpo de resposta.

:::warning Atenção
Ao enviar, o grupo de assinantes nasce no status `in_analysis`. Signer groups sets neste status não são enviados para assinatura. Com a aprovação do cadastro, o grupo passa para o status `valid`, e só então, será utilizado para assinaturas acima do `main` signer group.
:::

:::warning Atenção
Caso o `custom` signer group enviado seja **menos restritivo** que o validado pela Administradora, a análise será **negada**.
:::

### Erros Tratáveis

| Código | HTTP | Causa | Como resolver |
|--------|------|-------|---------------|
| ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto. |
| ASR000033 | 404 | Análise não encontrada para o `analysis_key` informado. | Verificar se o `analysis_key` está correto. |
| ASR000035 | 404 | Parte relacionada da análise não encontrada para o `analysis_related_party_key` informado. | Verificar se o `analysis_related_party_key` corresponde a um avalista ou representante de avalista da análise. |
| ASR000066 | 400 | Status da análise não permite definição de grupos customizados. | A análise deve estar em `pending_documents` para receber grupos customizados. |
| ASR000109 | 404 | Tipo de produto inválido. | Usar um valor válido para `product` (ver enum [Product Type](#product-type)). |
| ASR000118 | 400 | Signatário inválido. | O `document_number` enviado em `signers` deve corresponder a um representante já cadastrado para a parte relacionada (avalista ou representante de avalista). |

---

## Consulta de Conjuntos de Assinantes

Esse endpoint **paginado** permite ao cliente consultar os conjuntos de assinantes existentes para o cedente e suas partes relacionadas, incluindo os conjuntos padrão gerados automaticamente. É útil para identificar `signer_group_set_key` e estrutura atual antes de criar uma versão customizada.

### Request

ENDPOINT /assignor_registry/signer_group_sets
MÉTODO GET

#### Query Parameters

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `limit` | integer | Quantidade de itens por página (0 a 50). Padrão: 10. |
| `page` | integer | Página a ser consultada, iniciando em 0. Padrão: 0. |
| `owner_key` | string | Filtra pelo identificador do proprietário (cedente ou parte relacionada). |
| `owner_type` | string | Tipo do proprietário. Ver **[Owner Type](#owner-type)**. |
| `owner_document_number` | string | Documento do proprietário. Exige `owner_type` para ser utilizado. |
| `product_type` | string | Filtra por tipo de produto. Ver **[Product Type](#product-type)**. |
| `status` | string | Filtra pelo status do conjunto. Ver **[Signer Group Set Status](#signer-group-set-status)**. |

:::tip Dica
Para listar apenas os conjuntos que estão efetivamente sendo utilizados nas assinaturas, filtre por `status=valid`. Conjuntos em `in_analysis` ainda dependem da aprovação do cadastro e não são enviados para assinatura.
:::

### Response

STATUS 200

```json title='Response Body'
{
  "data": [
    {
      "signer_group_set_key": "f2c1e4a8-91d2-4f10-8a3b-7e5c9b2d4a6e",
      "owner_key": "c4295375-4077-4092-a258-5bcdf8875907",
      "owner_type": "assignor_registry",
      "product_type": "assignment_contract",
      "signer_group_set_type": "custom",
      "status": "valid",
      "signer_groups": [
        {
          "minimum_required_signers": 2,
          "signers": [
            {
              "document_number": "883.512.866-80",
              "is_required_signer": true
            },
            {
              "document_number": "802.834.257-41",
              "is_required_signer": false
            }
          ],
          "expiration": null
        }
      ]
    }
  ],
  "limit": 10,
  "page": 0,
  "is_last_page": true
}
```

#### Campos de Paginação

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `data` | array | Lista de conjuntos de assinantes da página atual. Ver **[Definição de Conjunto de Assinantes](#definicao-de-conjunto-de-assinantes-signer-group-set)**. |
| `limit` | integer | Quantidade de itens por página utilizada na consulta. |
| `page` | integer | Página retornada, iniciando em 0. |
| `is_last_page` | boolean | Indica se esta é a última página do resultado. |

### Erros Tratáveis

| Código | HTTP | Causa | Como resolver |
|--------|------|-------|---------------|
| ASR000121 | 400 | `owner_document_number` enviado sem `owner_type`. | Ao filtrar por `owner_document_number`, sempre informar também `owner_type`. |
| ASR000120 | 400 | Valor de `status` inválido no filtro. | Usar um valor válido para o filtro `status` (ver enum [Signer Group Set Status](#signer-group-set-status)). |

---

## Definições

### Definição de Conjunto de Assinantes (Signer Group Set)

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `signer_group_set_key` | string | Identificador único do conjunto. | 36 |
| `owner_key` | string | Identificador do proprietário. Pode ser `assignor_registry_key` ou `analysis_related_party_key`. | 36 |
| `owner_type` | string | Tipo do proprietário. | Ver **[Owner Type](#owner-type)**. |
| `product_type` | string | Tipo de produto ao qual o conjunto está associado. | Ver **[Product Type](#product-type)**. |
| `signer_group_set_type` | string | Tipo do conjunto (`main` ou `custom`). | Ver **[Signer Group Set Type](#signer-group-set-type)**. |
| `status` | string | Status do conjunto. | Ver **[Signer Group Set Status](#signer-group-set-status)**. |
| `signer_groups` | array | Lista de grupos de assinantes que compõem o conjunto. | Ver **[Definição de Grupo de Assinantes](#definicao-de-grupo-de-assinantes-signer-group)**. |

---

### Definição de Item de Envio (Signer Group Set Item)

Estrutura utilizada no corpo das requisições de criação de conjuntos customizados.

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `product` * | string | Tipo de produto ao qual o conjunto será associado. | Ver **[Product Type](#product-type)**. |
| `signer_groups` * | array | Lista de grupos de assinantes (mínimo 1). | Ver **[Definição de Grupo de Assinantes](#definicao-de-grupo-de-assinantes-signer-group)**. |

*Campos obrigatórios.

---

### Definição de Grupo de Assinantes (Signer Group)

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `minimum_required_signers` * | number | Quantidade mínima de assinantes do grupo necessários para validar a assinatura. | Mínimo 1 |
| `signers` * | array | Lista de assinantes do grupo (mínimo 1). | Ver **[Definição de Assinante](#definicao-de-assinante-signer)**. |
| `expiration` | string | Data de expiração do grupo no formato `YYYY-MM-DD`. | 10 |

*Campos obrigatórios.

---

### Definição de Assinante (Signer)

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `document_number` * | string | CPF do assinante no formato `XXX.XXX.XXX-XX`. | 14 |
| `is_required_signer` * | boolean | Indica se o assinante é obrigatório no grupo. | - |

*Campos obrigatórios.

:::info Informação
Os `document_number` enviados devem corresponder a partes relacionadas (representantes do cedente, ou representantes do avalista em questão) presentes no cadastro do cedente. Documentos que não estiverem associados ao cedente serão rejeitados.
:::

---

# Enumeradores

### Owner Type

| Enumerador | Descrição |
|------------|-----------|
| **assignor_registry** | Conjunto vinculado ao cedente. |
| **analysis_related_party** | Conjunto vinculado a uma parte relacionada da análise (avalistas). |

---

### Product Type

| Enumerador | Descrição |
|------------|-----------|
| **assignment_contract** | Contrato de cessão (utilizado por padrão). |
| **commercial_paper** | Nota Comercial (Cadastro único com a plataforma de escrituração). |

---

### Signer Group Set Type

| Enumerador | Descrição |
|------------|-----------|
| **main** | Conjunto padrão, gerado da análise da Administradora. |
| **custom** | Conjunto customizado, criado pelo cliente sobrepondo o conjunto `main`. |

---

### Signer Group Set Status

| Enumerador | Descrição |
|------------|-----------|
| **in_analysis** | Conjunto enviado e atrelado à análise em aberto. Não é utilizado nas assinaturas. |
| **valid** | Conjunto vigente e utilizado nas assinaturas. |
| **inactive** | Conjunto substituído por uma versão mais recente ou desativado. |

---

# Envio para Análise

URL: /documentation/iaas/homologacao_cedente/cadastro/disparo_da_analise

Após todos os documentos estarem devidamente anexados, deve ser disparada a análise, a qual enviará todos os dados para nosso sistema de anti-fraude, para análise de compliance. Caso recusada, deverá ser feita uma nova análise, caso aprovada, haverá uma etapa posterior de validação interna de representantes, onde será tambem monstada a estrutura de assinantes do cedente, para finalmente começar a operação com o mesmo, disponibilizando a criação de contratos mãe entre o cedente e o fundo.

---
### Request

ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY
MÉTODO PUT

```json title='Request Body'
{
    "analysis_status":"sent_to_analysis"
}
```

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `analysis_status` * | string | Novo status da análise a ser enviado (deve ser igual a **sent_to_analysis**). | 1 a 50 |

*Campo obrigatório.

### Response

STATUS 200

```json title='Response Body'
{
  "analysis_key": "2b1fa466-4d36-48e9-b6e3-776a1b700b9f",
  "analysis_number": 1,
  "assignor_registry_key": "d0a93900-457d-496a-8326-480ecaf946c3",
  "status": "sent_to_analysis"
}
```

:::caution Atenção!
Uma análise deve ser efetivamente enviada somente após anexar todos os documentos pertinentes. Uma vez enviada a análise, não será mais possível anexar novos documentos.
:::

:::warning Não deixe a análise parada
Uma análise que fica **1 mês sem movimentação** em `pending_documents` é **cancelada automaticamente** (`canceled`) e não pode mais ser disparada — a tentativa é recusada com `ASR000034`. Nesse caso, gere uma nova análise por meio da [Atualização de Cadastro](/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro).
:::

### Erros Tratáveis

| Código | HTTP | Causa | Como resolver |
|--------|------|-------|---------------|
| ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto e pertence ao agente autenticado. |
| ASR000033 | 404 | Análise não encontrada para o `analysis_key` informado. | Verificar se o `analysis_key` está correto. |
| ASR000040 | 400 | A análise não pertence ao cedente informado. | Garantir que `analysis_key` e `assignor_registry_key` correspondam à mesma análise. |
| ASR000034 | 400 | A análise não pode receber este status. | A análise só pode ser enviada quando estiver no status `pending_documents`. Verifique o status atual em [Consulta de Análise](/documentation/iaas/homologacao_cedente/consulta/consulta_de_analise). Se estiver `canceled`, ela foi cancelada por inatividade e é preciso gerar uma nova análise. |
| ASR000038 | 400 | Status enviado é inválido. | O campo `analysis_status` deve ser exatamente `sent_to_analysis`. |
| ASR000009 | 400 | A análise não possui todos os documentos obrigatórios do cedente. | Anexar os documentos exigidos para o tipo de pessoa do cedente antes de disparar a análise. Ver [Envio de Documentos](/documentation/iaas/homologacao_cedente/cadastro/envio_de_documentos). |
| ASR000015 | 400 | Uma parte relacionada da análise não possui todos os documentos obrigatórios. | Anexar os documentos exigidos da parte relacionada indicada pela `analysis_related_party_key` no erro antes de disparar a análise. |

---

# Envio de Cadastro

URL: /documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro

Na primeira etapa de cadastro do cedente, são informados os dados do mesmo, conforme definidos abaixo.
Vale relembrar que, apenas enviar os dados, não cria um cedente operacional, o mesmo só será ativado após a conclusão bem sucedida das análises dos documentos do mesmo.

Obrigatoriamente para pessoas jurídicas, e opcionalmente em pessoas físicas, é possível cadastrar partes relacionadas, que representam os beneficiários finais ligados ao cedente.

:::info Informação
Um beneficiário final é definido como o indivíduo, ou grupo de indivíduos, com relevância significativa na empresa ou conglomerado, com poder decisório ou participação significativa na grade societária. Para fins de cadastro, devem ser levados em conta quaisquer associados com participação superior a 15% na companhia, ou no conglomerado do qual fazem parte, ou, caso não haja participação tão relevante, os três maiores em ordem decrescente. 
:::

Caso o beneficiário relevante seja uma outra empresa, deve-se atribuir os seus beneficiários finais, indicados como beneficiários indiretos. Além disso, são considerados partes relacionadas quaisquer procuradores, gestores, e diretores envolvidos na operação, que serão os representantes assinantes do cedente na mesma.

Os representantes assinantes são partes relacionadas responsáveis por acompanhar e assinar os documentos direcionados ao cedente pelo nosso sistema, sendo necessária comprovação do vínculo, no caso de empresas, por meio do quadro societário, ou de diretores, ou com uma procuração. Não é possível cadastrar uma parte relacionada que não seja um procurador para um cedente pessoa física. Além disso, é necessário indicar se a parte relacionada considerada beneficiário final tem vínculo direto ou indireto com o cedente.

:::info Informação
No ambiente de Homologação, temos a seguinte regra para aprovações: CPF/CNPJ com início 1: Reprovação automática; CPF/CNPJ com início 8: Pendente Validação Manual; O restante é aprovado automaticamente. 
:::
---
## Cadastro de Cedente

### Request

ENDPOINT /assignor_registry/assignor_registry
MÉTODO POST

```json title='Request Body'
{
  "name": "QI Tech",
  "document_number": "32.402.502/0001-35",
  "person_type": "legal_person",
  "email": "qitech@qitech.com.br",
  "annual_revenues": 1000000,
  "is_in_national_financial_system": true,
  "address": {
    "street": "Rua Maria Carolina",
    "number": "624",
    "neighborhood": "Jardim Paulistano",
    "city": "São Paulo",
    "postal_code": "01445-000",
    "uf": "SP",
    "country": "BRA"
  },
  "phone": {
    "international_dial_code": "+55",
    "area_code": "11",
    "number": "936360268"
  },
  "related_parties": [
    {
      "name": "Natália Nascimento",
      "document_number": "883.512.866-80",
      "related_party_type": "attorney",
      "nationality": "BRA",
      "address": {
        "street": "Rua Maria Carolina",
        "number": "624",
        "neighborhood": "Jardim Paulistano",
        "city": "São Paulo",
        "postal_code": "01445-000",
        "uf": "SP",
        "country": "BRA"
      },
      "direct_beneficiary": true,
      "is_representative": true,
      "email": "natalia.nascimento@yopmail.com",
      "phone": {
        "international_dial_code": "+55",
        "area_code": "11",
        "number": "936360268"
      }
    },
    {
      "name": "Maria Vitoria",
      "related_party_type": "president",
      "nationality": "DEU",
      "passport_number": "C01X00T47",
      "direct_beneficiary": true,
      "is_representative": false

    },
    {
      "name": "Roberto Carlos",
      "document_number": "802.834.257-41",
      "related_party_type": "director",
      "nationality": "BRA",
      "direct_beneficiary": false,
      "company_country": "NZL",
      "company_registry_number": "4984037284610",
      "is_representative": false,
      "email": "roberto.carlos@yopmail.com",
      "phone": {
        "international_dial_code": "+64",
        "area_code": "11",
        "number": "936360268"
      }
    }
  ],
  "accounts": [
    {
      "account_branch": "0001",
      "account_number": "7912584",
      "account_digit": "1",
      "financial_institution_code": "329",
      "account_type": "checking_account",
      "default_account": true
    },
    {
      "account_branch": "0001",
      "account_number": "8758931",
      "account_digit": "5",
      "financial_institution_code": "329",
      "account_type": "escrow_account",
      "default_account": false
    }
  ],
  "guarantors": [
    {
      "name": "Avalista PF",
      "address": {
        "street": "Rua Maria Carolina",
        "number": "624",
        "neighborhood": "Jardim Paulistano",
        "city": "São Paulo",
        "postal_code": "01445-000",
        "uf": "SP",
        "country": "BRA"
      },
      "document_number": "172.775.419-01",
      "person_type": "natural_person",
      "email": "email@avalista.com"
    },
    {
      "name": "Avalista PJ",
      "document_number": "65.679.662/0001-85",
      "person_type": "legal_person",
      "email": "email@avalista.com",
      "guarantor_representatives": [
        {
          "name": "Assinante do Avalista",
          "document_number": "244.412.084-13",
          "email": "emailrepresentante@avalista.com",
          "address": {
            "street": "Rua Maria Carolina",
            "number": "624",
            "neighborhood": "Jardim Paulistano",
            "city": "São Paulo",
            "postal_code": "01445-000",
            "uf": "SP",
            "country": "BRA"
          }
        }
      ]
    },
  ]
}
```

---

### Definição do Cedente

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `name` * | string | Nome do cedente. | 1 a 255 |
| `document_number` * | string | Número de documento do cedente (CNPJ). | 14 a 18 |
| `annual_revenues` * | number | Declaração de faturamento anual do cedente, em inteiros. | Mínimo de 1 |
| `person_type` * | string | Tipo de pessoa (física ou jurídica) do cedente. | - |
| `email` * | string | Endereço de e-mail do cedente. | 1 a 255 |
| `is_in_national_financial_system` * | boolean | Indicador se o cedente é integrante do SFN. | - |
| `phone`  | object | Objeto referenciando as informações do telefone do cedente. | Ver **[Definição de Telefone](#definição-de-telefone)**. |
| `address` * | object | Objeto referenciando as informações do endereço do cedente. | Ver **[Definição de Endereço](#definição-de-endereço)**. |
| `related_parties` * | array | Lista de partes relacionadas da empresa.| Ver  **[Definição de Parte Relacionada](#definição-de-parte-relacionada)**. |
| `accounts` * | array | Lista de contas de desembolso do cedente.| Ver  **[Definição de Conta](#definição-de-conta)**. |
| `guarantors` * | array | Lista de avalistas do cedente.| Ver  **[Definição de Avalista](#definição-de-avalista)**. |

*Campos obrigatórios.

### Response

STATUS 201

```json title='Response Body'
{
  "assignor_registry_key": "c4295375-4077-4092-a258-5bcdf8875907",
  "status": "pending_registry",
  "name": "QI Tech",
  "document_number": "32.402.502/0001-35",
  "last_analysis": {
    "analysis_key": "d7805a05-98a7-486b-a440-807f1d3d5691",
    "analysis_number": 1,
	  "status": "pending_documents",
    "analysis_related_parties": [
      {
        "analysis_related_party_key": "5cdcc13b-c67d-45f3-aa66-36cb4f178b59",
        "document_number": "802.834.257-41",
        "name": "Roberto Carlos",
        "documents": []
      },
      {
        "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721",
        "document_number": "883.512.866-80",
        "name": "Natália Nascimento",
        "documents": []
      },
      {
        "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721",
        "passport_number": "C01X00T47",
        "name": "Maria Vitoria",
        "documents": []
      }
    ],
    "documents": [
      {
        "document_key": "994621ac-7d3f-4f6b-90c5-74a4d8c5d017",
        "document_type": "social_contract",
        "status": "valid",
      }
    ],
    "analysis_data": {}
  }
}
```

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `assignor_registry_key` | string | Identificador do cadastro. | 36 |
| `status` | string | Status do cadastro. | Ver **[Enumeradores de status do cadastro](#assignor-registry-status)**. |
| `name` | string | Nome do Cedente. | 1 a 255 |
| `document_number` | string | Documento do Cedente. | 14 a 18 |
| `last_analysis`  | object | Objeto de análise. | Ver **[Definição de Análise](#definição-de-análise)**. |

:::info
É importante armazenar a `assignor_registry_key` pois ela será utilizada em diversos outros processos, assim como a `analysis_key` e as `analysis_related_party_key` que serão utilizadas para envio de documentos do cedente e das partes relacionadas.
:::

:::info
Na estrutura de análise, um avalista, ou um representante de um avalista, também é representado por um `analysis_related_party`. Importante notar que o mesmo é único por `document_number`, logo, caso a mesma pessoa seja avalista e parte relacionada do cedente, por exemplo, gerará apenas um `analysis_related_party`, com uma `analysis_related_party_key`, que servirá tanto para a parte relacionada, quanto para o avalista.
:::

:::info
Os representantes de pessoa física se limitam apenas ao procurador que pode assinar por tal.
:::

### Erros Tratáveis

| Código | HTTP | Causa | Como resolver |
|--------|------|-------|---------------|
| ASR000032 | 409 | Esse agente já cadastrou esse cedente. | O `document_number` já possui um cadastro; utilize o fluxo de [atualização de cadastro](/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro). |
| ASR000054 | 400 | Cedente pessoa jurídica deve ter pelo menos 1 parte relacionada. | Incluir ao menos uma parte relacionada em `related_parties`. |
| ASR000056 | 400 | Pessoa física não pode ser participante do Sistema Financeiro Nacional. | Para `person_type=natural_person`, enviar `is_in_national_financial_system=false`. |
| ASR000057 | 400 | Cedente pessoa jurídica deve ter pelo menos 1 representante assinante. | Garantir que ao menos uma parte relacionada possua `is_representative=true`. |
| ASR000011 | 400 | Número de documento de parte relacionada duplicado. | Cada `document_number` em `related_parties` deve ser único. |
| ASR000041 | 400 | Email obrigatório para representante. | Para partes relacionadas com `is_representative=true`, informar `email`. |
| ASR000058 | 400 | Pessoa estrangeira sem CPF não pode ser assinante. | Estrangeiros sem `document_number` (CPF) não podem ter `is_representative=true`. |
| ASR000071 | 404 | Instituição financeira não encontrada. | Validar o `financial_institution_code` (código bancário) informado para a conta. |
| ASR000087 | 400 | Informação de conta deve conter apenas números. | Enviar `account_branch`, `account_number` e `account_digit` apenas com dígitos. |
| ASR000081 | 400 | Mais de uma conta padrão foi enviada. | Apenas uma conta deve ter `default_account=true`. |
| ASR000078 | 400 | Número de documento de avalista duplicado. | Cada avalista em `guarantors` deve ter `document_number` único. |
| ASR000079 | 400 | Avalista pessoa física não pode receber representantes. | Para avalistas com `person_type=natural_person`, o `guarantor_representatives` deve ser do tipo `spouse` |
| ASR000080 | 400 | Documento de representante de avalista duplicado. | Cada representante em `guarantor_representatives` deve ter `document_number` único. |
| ASR000091 | 400 | Avalista pessoa jurídica deve ter pelo menos um representante. | Para `person_type=legal_person`, enviar pelo menos um item em `guarantor_representatives`. |

---

## Definições

### Definição de Endereço

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `street` * | string | Nome da rua. | 1 a 255 |
| `number` * | string | Número do endereço. | 1 a 4 |
| `neighborhood` * | string | Bairro. | 1 a 255 |
| `city` * | string | Cidade. | 1 a 255 |
| `uf` * | string | Sigla do estado. | 2 |
| `complement` | string | Complemento do endereço. | 1 a 255 |
| `postal_code` * | string | Código postal. | 9 (formato: XXXXX-XXX) |
| `country` * | string | País (sigla). | 3, de acordo com a ISO 3166-1 alpha-3 |

*Campos obrigatórios.

---

### Definição de Telefone

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `international_dial_code` * | string | Código internacional de discagem. | 1 a 3 |
| `area_code` * | string | Código de área. | 2 |
| `number` * | string | Número de telefone. | 8 a 9 |

*Campos obrigatórios.

---

### Definição de Parte Relacionada

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `name` * | string | Nome da parte relacionada. | 1 a 255 |
| `document_number` ** | string | Número de documento do beneficiário (CPF). | 14 a 18 |
| `passport_number` ** | string | Número de documento do beneficiário estrangeiro. | 8 a 9 |
| `related_party_type` * | string | Tipo de vínculo da parte relacionada. | Ver **[Enumeradores de tipo de parte relacionada](#related-party-type)** |
| `nationality` * | string | País de origem do beneficiário. | 3, de acordo com a ISO 3166-1 alpha-3 |
| `direct_beneficiary` * | boolean | Beneficiário diretamente ou indiretamente ligado ao cedente. | 1 a 255 |
| `is_representative` * | boolean | Indicador se a parte relacionada é representante assinante do cedente. | 1 a 255 |
| `company_registry_number` *** | string | Caso não seja diretamente ligado ao cedente, à qual companhia o mesmo está ligado. | 1 a 255 |
| `company_country` *** | string | País onde a companhia-elo entre o beneficiário e o cedente está registrada. | 3, de acordo com a ISO 3166-1 alpha-3 |
| `address` | object | Objeto referenciando as informações do endereço do representante. | Ver **[Definição de Endereço](#definição-de-endereço)**. |
| `email` **** | string | Endereço de e-mail do representante. | 1 a 255 |
| `phone` | object | Objeto referenciando as informações do telefone do representante. |  Ver **[Definição de Telefone](#definição-de-telefone)**. |
| `marital_status` | string | Estado civil da parte relacionada. | Ver **[Enumeradores de estado civil](#marital-status)**. |
| `property_system` | string | Regime de separação de bens. | Ver **[Enumeradores de regime de separação de bens](#property-system)**. |
| `profession` | string | Profissão da parte relacionada. | 1 a 255. |

*Campos obrigatórios.

**document_number obrigatório para brasileiros, para estrangeiros, caso tenha CPF, é possível utilizar o document_number, caso contrário, pelo menos o  passport_number deve ser enviado.

***Campos obrigatórios caso a parte relacionada não seja beneficiário diretamente ligada ao cedente. Caso contrário, não devem ser enviados.

****Campos exigidos apenas para representantes assinantes.

:::info
Campos não obrigatorios, como `marital_status` e `address`, podem ser enviados caso deseje uma qualificação mais completa no contrato mãe de cessão, nas etapas futuras.
:::

---

### Definição de Análise

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `analysis_key` * | string | Identificador da análise. | 36 |
| `analysis_number` * | integer | Número sequencial da análise. | - |
| `status` * | string | Status da análise. | Ver **[Enumeradores de status de análise](#analysis-status)**. |
| `analysis_related_parties` * | array | Partes Relacionadas da análise. | Ver **[Definição de Partes Relacionadas de Análise](#definição-de-partes-relacionadas-de-análise)**. |
| `documents` * | array | Documentos da anáise. | Ver **[Definição de Documentos de análise](#definição-de-documentos)**. |
| `analysis_data` * | object | Payload da request que originou a análise. | - |
| `analysis_datetime` * | string | Objeto date time da criação da análise. | - |
| `reproval_reason` | string | Enumerador com o motivo de rejeição da análise. | Ver **[Enumeradores de motivo de reprovação](#analysis-reproval-reason)**. |
| `reproval_details` | string | Campo livre com detalhes da rejeição da análise. | - |

*Campos obrigatórios.

---

### Definição de Partes Relacionadas de análise

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `analysis_related_party_key` * | string | Identificador da parte relacionada. | 36 |
| `document_number` * | string | Número de documento da parte relacionada. | 14 a 18 |
| `name` * | string | Nome da parte relacionada. | 1 a 255 |
| `documents` * | array | Documentos da anáise da parte relacionada. | Ver **[Definição de Documentos de análise](#definição-de-documentos)**. |

*Campos obrigatórios.

---

### Definição de Documentos

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `document_key` * | string | Identificador do documento. | 36 |
| `document_type` * | string | Tipo do documento. | Ver **[Enumeradores de tipo de documento](#document-type)**. |
| `status` | string | Status do documento. | Ver **[Enumeradores de status de documento](#document-status)**. |
| `observation` | string | Observações enviadas. | - |

*Campos obrigatórios.

---

### Definição de Conta

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `account_branch` * | string | Agência da conta do cedente. | 4 |
| `account_number` * | string | Número da conta do cedente. | 3 - 20 |
| `account_digit` * | string | Dígito da conta do cedente. | 1 |
| `financial_institution_code` * | string | Código do banco da conta do cedente. | 3 |
| `account_type` * | string | Tipo de conta. | Ver **[Enumeradores de tipo de conta](#account-type)**. |
| `default_account` * | boolean | Conta padrão de desembolso. | - |

*Campos obrigatórios.

Apenas uma conta do cedente pode ser a conta padrão, que será a conta para qual o dinheiro das cessões será enviado caso nenhuma conta alternativa seja indicada. Caso sejam enviadas mais de uma conta padrão, um erro será retornado.

:::warning Atenção
Muito cuidado ao preencher os dados da conta. Caso a conta seja inválida, o pagamento da cessão não ocorrerá, e toda a operação será cancelada.
:::

---

### Definição de Avalista

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `name` * | string | Nome do Avalista. | 3 - 255 |
| `document_number` * | string | Número de documento do avalista. | 14 a 18 |
| `person_type` * | string | Tipo de pessoa (física ou jurídica) do cedente. | - |
| `email` * | string | Endereço de e-mail do avalista. | 1 a 255 |
| `nationality` | string | País de origem do avalista. | 3, de acordo com a ISO 3166-1 alpha-3 |
| `phone` | object | Objeto referenciando as informações do telefone do avalista. |  Ver **[Definição de Telefone](#definição-de-telefone)**. |
| `address` | object | Objeto referenciando as informações do endereço do avalista. | Ver **[Definição de Endereço](#definição-de-endereço)**. |
| `guarantor_representatives` | array | Assinantes do Avalista - Apenas para avalista pessoa jurídica. | Ver  **[Definição de Representante do Avalista](#definição-de-representante-do-avalista)**. |
| `marital_status` | string | Estado civil do avalista. | Ver **[Enumeradores de estado civil](#marital-status)**. |
| `property_system` | string | Regime de separação de bens. | Ver **[Enumeradores de regime de separação de bens](#property-system)**. |
| `profession` | string | Profissão do avalista. | 1 a 255. |

*Campos obrigatórios.

O campo `guarantor_representatives` pode ser utilizado para indicar tanto representantes de um avalista pessoa jurídica, quanto, no caso de avalista pessoa física, onde se encontrar necessário, o cônjuge para realização da Outorga Uxória.

:::warning Atenção
Tanto o avalista quanto os representantes também serão adicionados à anáise gerada, sendo necessário enviar os documentos padrão de acordo com o tipo de pessoa do mesmo. Os mesmos também passam pelo processo de compliance, podendo gerar apontamentos.
:::

---

### Definição de Representante do Avalista

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `name` * | string | Nome do Representante. | 3 - 255 |
| `document_number` * | string | Número de documento do representante do avalista - obrigatóriamente pessoa física. | 14 |
| `email` * | string | Endereço de e-mail do representante do avalista. | 1 a 255 |
| `nationality` | string | País de origem do representante do avalista. | 3, de acordo com a ISO 3166-1 alpha-3 |
| `address` | object | Objeto referenciando as informações do endereço do representante do avalista. | Ver **[Definição de Endereço](#definição-de-endereço)**. |
| `phone` | object | Objeto referenciando as informações do telefone do representante do avalista. |  Ver **[Definição de Telefone](#definição-de-telefone)**. |
| `marital_status` | string | Estado civil do representante do avalista. | Ver **[Enumeradores de estado civil](#marital-status)**. |
| `property_system` | string | Regime de separação de bens. | Ver **[Enumeradores de regime de separação de bens](#property-system)**. |
| `profession` | string | Profissão do representante do avalista. | 1 a 255. |

---

# Enumeradores

### Assignor Registry Status

| Enumerador                 | Descrição       |
| -------------------------- | ----------------- |
| **pending_registry** | Pendente Registro |
| **registered**       | Registrado        |

---

### Analysis Status

| Enumerador              | Descrição           |
| ----------------------- | --------------------- |
| **pending_documents**  | Pendente Documentos   |
| **sent_to_analysis**   | Enviado para Análise |
| **pending_internal_validation** | Em Validação de documentos    |
| **in_manual_analysis** | Em Análise Manual de Compliance    |
| **approved**           | Aprovado              |
| **reproved**           | Reprovado             |
| **canceled**           | Cancelado             |

---

### Related Party Type

| Enumerador              | Descrição   |
| ----------------------- | ------------- |
| **president**     | Presidente    |
| **partner**       | Sócio        |
| **administrator** | Administrador |
| **director**      | Diretor       |
| **manager**       | Gestor        |
| **attorney**      | Procurador    |

---

### Document Status

| Enumerador              | Descrição   |
| ----------------------- | ------------- |
| **created**     | Criado    |
| **valid**       | Válido        |
| **invalid** | Inválido |
| **canceled** | Cancelado |
| **accepted** | Aceito, porém não validado |

---

### Document Type

| Enumerador                   | Descrição                |
| ---------------------------- | -------------------------- |
| **cnh**                      | CNH.                        |
| **rg_back**                  | RG parte traseira.          |
| **rg_front**                 | RG parte frontal.           |
| **passport**                 | Passaporte - exclusivo para estrangeiros.           |
| **national_migration_registry**                 | Registro Nacional de Migração.           |
| **cin_digital**                 | Carteira de Identidade Nacional (Digital).           |
| **social_contract**          | Contrato/Estatuto Social.   |
| **cnpj_card**          | Cartão CNPJ.   |
| **commercial_board_certificate** | Certidão Simplidicada da Junta Comercial. |
| **board_election_record** | Ata de Eleição da Diretoria Vigente. |
| **power_of_attorney**        | Procuração - obrigatório caso o representante seja um procurador. |
| **marital_power_of_attorney**        | Procuração Uxória - disponível apenas para cônjuges. |
| **compliance_statement**        | Parecer de Compliance. |
| **financial_statement**        | Demonstração Financeira. |
| **credit_report**        | Ata/Parecer de Crédito. |
| **manager_statement**        | Parecer/Ficha do Gestor. |
| **visit_report**        | Relatório de Visita. |
| **proof_of_residence**        | Comprovante de Residência. |
| **credit_agency_consulation**        | Consulta aos órgãos de Proteção de Crédito. |
| **annual_revenues_declaration**        | Declaração de Faturamento. |
| **financial_institutions_declaration**        | Declaração de Relacionamento Bancário. |
| **additional_document**        | Documento adicional - livre. |

---

### Account Type

| Enumerador           | Descrição           |
|----------------------|---------------------|
| **checking_account** | Conta Corrente      |

---

### Analysis Reproval Reason
| Enum         | 	Description  |
|--------------|---------------|
| **assignor_update**   | Análise cancelada devido à atualização cadastral posterior |
| **insuficient_documents**  | Documentação mínima para comprovação de poderes não enviada |
| **compliance_reproval**  | Reprovação de vínculo por análise do time de compliance |
| **unidentified_related_parties** | Parte relacionada enviada, porém vinculo não comprovado |
| **invalid_documents** | Documentação inválida/expirada |
| **missing_related_parties** | Parte relacionada obrigatória não enviada |

---

### Marital Status
| Enum         | 	Description  |
|--------------|---------------|
| **single**   | Solteiro(a)   |
| **married**  | Casado(a)    |
| **widower**  | Viúvo(a)     |
| **divorced** | Divorciado(a) |
| **separated** | Separado(a) |
| **stable_union** | Em União Estável |

---

### Property System

| Enum                              | Descrição                              |
| --------------------------------- | -------------------------------------- |
| **total_communion_of_goods**        | Comunhão Total de Bens                |
| **partial_communion_of_goods**      | Comunhão Parcial de Bens              |
| **total_separation_of_goods**       | Separação Total de Bens               |
| **final_participation_of_acquisitions** | Participação Final nos Aquestos    |
| **compulsory_separation_of_goods**  | Separação Obrigatória de Bens         |

---

# Envio de Documentos

URL: /documentation/iaas/homologacao_cedente/cadastro/envio_de_documentos

Após o envio do cadastro do cedente, devem ser enviados os documentos relacionados ao mesmo. Para isso, é utilizada a estrutura de análise de documentos, onde, tanto na criação quanto na alteração, uma análise é gerada e os devidos documentos devem ser enviados. Cabe à gestora averiguar a operação do cedente que irá opear com os fundos geridos, e, futuramente, na etapa de criação de contrato mãe, será necessário assinar uma declaração da gestora, atestando que a mesma cumpriu toda a análise requerida pelo manual de Regras e Procedimentos de Administração e Gestão de Recursos de Terceiros, a qual encarrega à gestora tanto a análise quanto a atualização do cadastro do cedente.

:::info
Caso se trate de uma atualização, os documentos da última análise aprovada são automaticamente reaproveitados, podendo ser substituídos por novos.
:::

---

## Documentos do Cedente

### Request

ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/document
MÉTODO POST

```json title='Request Body'
{
    "document_type":"social_contract",
    "document_b64": "aGVsbG8gd29ybGQgaWYgeW91IGRlY29kZWQgbWUsIGJlIGNhcmVmdWwuIEl0IG11c3QgYmUgYSBQREYgRmlsZSBvdGhlcndpc2UgSSB3aWxsIHJhaXNlIGFuIEVycm9yLg==",
    "observation":"CONTRATO SOCIAL ATUALIZADO",
}
```

## Objeto de Documento

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `document_type` * | string | Tipo do documento. | Ver **[Tipos de Documento ](#document-type)**. |
| `document_b64` * | string | Deve ser o binário do arquivo em PDF, codificado em Base64. | - |
| `observation` | string | Campo livre para descrever arquivos enviados. | 1 - 255 |

*Campos obrigatórios.

### Response

STATUS 201

```json title='Response Body'
{
    "document_key": "8e515a17-8b4d-49a3-aed6-47c9574e426a",
    "document_type": "social_contract",
    "analysis_key": "63db95c2-9985-405a-a521-6904f9e96cc6",
    "status": "valid"
}
```

:::info
Em caso de atualização cadastral, o envio de documentos específicos do cedente na análise será necessário somente quando houver alguma atualização nas informações que sejam **específicas do cedente**.
:::

### Erros Tratáveis

| Código | HTTP | Causa | Como resolver |
|--------|------|-------|---------------|
| ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto. |
| ASR000033 | 404 | Análise não encontrada para o `analysis_key` informado. | Verificar se o `analysis_key` está correto. |
| ASR000039 | 400 | O status atual da análise não aceita novos documentos. | Documentos só podem ser anexados quando a análise estiver em `pending_documents`. Para reenviar após análise iniciada — ou se a análise tiver sido cancelada por inatividade (`canceled`) — gere uma nova análise via [Atualização de Cadastro](/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro). |
| ASR000005 | 400 | Formato de arquivo inválido. | Enviar `document_b64` como string em base64 válida. |
| ASR000060 | 400 | O arquivo enviado não é um PDF válido. | O conteúdo decodificado de `document_b64` deve ser um PDF. |
| ASR000059 | 400 | Tamanho do arquivo excede o limite. | Reduzir o tamanho do PDF antes de enviar (limite informado na mensagem do erro). |
| ASR000061 | 400 | Tipo de documento inválido para o cedente. | Usar um `document_type` compatível com o tipo de pessoa do cedente (ver tabela [Documentos padrão do cedente/avalista](#documentos-padrão-do-cedenteavalista)). |

## Documentos das partes relacionadas

### Request

ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/related_party/ANALYSIS_RELATED_PARTY_KEY/document
MÉTODO POST

```json title='Request Body'
{
    "document_type":"cnh",
    "document_b64": "aGVsbG8gd29ybGQgaWYgeW91IGRlY29kZWQgbWUsIGJlIGNhcmVmdWwuIEl0IG11c3QgYmUgYSBQREYgRmlsZSBvdGhlcndpc2UgSSB3aWxsIHJhaXNlIGFuIEVycm9yLg==",
    "observation":"CNH Válida",
}
```

### Response

STATUS 201

```json title='Response Body'
{
    "document_key": "afe8532a-4b0b-4e63-8d16-5084b2681752",
    "document_type": "cnh",
    "analysis_related_party_key": "fd1fb513-5ffc-4060-bca1-17deed680011",
    "status": "valid"
}
```

:::info
Em caso de atualização cadastral, o envio de documentos das partes relacionadas na análise será necessário somente quando houver alguma inclusão ou atualização de partes relacionadas do cedente.
:::

:::caution Atenção!
Caso um documento seja enviado com o tipo errado, ou com má qualidade ele pode retornar com o status **accepted**, indicando que a qualidade do mesmo está duvidosa, ou até **invalid**, assim sendo necessário reenviá-lo corretamente.
:::

### Erros Tratáveis

| Código | HTTP | Causa | Como resolver |
|--------|------|-------|---------------|
| ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto. |
| ASR000033 | 404 | Análise não encontrada para o `analysis_key` informado. | Verificar se o `analysis_key` está correto. |
| ASR000035 | 404 | Parte relacionada da análise não encontrada para o `analysis_related_party_key` informado. | Verificar se o `analysis_related_party_key` retornado na criação da análise está correto. |
| ASR000039 | 400 | O status atual da análise não aceita novos documentos. | Documentos só podem ser anexados quando a análise estiver em `pending_documents`. |
| ASR000005 | 400 | Formato de arquivo inválido. | Enviar `document_b64` como string em base64 válida. |
| ASR000060 | 400 | O arquivo enviado não é um PDF válido. | O conteúdo decodificado de `document_b64` deve ser um PDF. |
| ASR000059 | 400 | Tamanho do arquivo excede o limite. | Reduzir o tamanho do PDF antes de enviar (limite informado na mensagem do erro). |
| ASR000062 | 400 | Tipo de documento inválido para a parte relacionada. | Usar um `document_type` compatível com o tipo de pessoa da parte relacionada (ver tabela [Documentos padrão das partes relacionadas/representantes](#documentos-padrão-das-partes-relacionadasrepresentantes)). |

## Cancelamento do envio de documento

Com exceção do tipo additional_document, apenas um documento com status "valid" é permitido na análise. Caso, por algum motivo, deseje substituir um documento já válido, deve-se cancelá-lo.

### Request

ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/related_party/ANALYSIS_RELATED_PARTY_KEY/document/DOCUMENT_KEY
MÉTODO PUT

OU

ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY/document/DOCUMENT_KEY
MÉTODO PUT

```json title='Request Body'
{
    "status":"canceled"
}
```

### Response

STATUS 200

```json title='Response Body'
{
    "document_key": "afe8532a-4b0b-4e63-8d16-5084b2681752",
    "document_type": "cnh",
    "analysis_related_party_key": "fd1fb513-5ffc-4060-bca1-17deed680011",
    "status": "canceled"
}
```

### Erros Tratáveis

| Código | HTTP | Causa | Como resolver |
|--------|------|-------|---------------|
| ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto. |
| ASR000033 | 404 | Análise não encontrada para o `analysis_key` informado. | Verificar se o `analysis_key` está correto. |
| ASR000006 | 404 | Documento da análise não encontrado para o `document_key` informado. | Verificar se o `document_key` pertence à análise indicada. |
| ASR000036 | 404 | Documento da parte relacionada da análise não encontrado para o `document_key` informado. | Verificar se o `document_key` pertence à parte relacionada indicada (rota com `related_party`). |
| ASR000076 | 400 | Status enviado não permitido para esse fluxo. | O único valor aceito para `status` neste endpoint é `canceled`. |

---

### Documentos padrão do cedente/avalista

| Tipo de Pessoa | *document_type* | Descrição | Obrigatoriedade |
|----------------|-------------------|------------|--------------|
| Pessoa Física | cnh | CNH (Carteira Nacional de Habilitação) | * |
| Pessoa Física | cin_digital | Carteira de Identidade Nacional (Digital) | * |
| Pessoa Física | rg_back | RG (Carteira de Identidade) - Verso | * |
| Pessoa Física | rg_front | RG (Carteira de Identidade) - Frente | * |
| Pessoa Jurídica | social_contract | Contrato Social | Sempre |
| Pessoa Jurídica | commercial_board_certificate | Ceridão Simplificada da Junta Comercial | Opcional, entretanto obrigatório para contratos sociais com data superior a 3 anos |
| Pessoa Jurídica | board_election_record | Eleição da diretoria - se aplicável | Necessário para comprovação de vínculo |

*Para quaisquer pessoas físicas, é necessário apenas um dentre RG frente e verso, CNH e Carteira de Identidade Nacional.

### Documentos padrão das partes relacionadas/representantes

| Tipo de Pessoa | *document_type* | Descrição | Obrigatoriedade |
|----------------|-------------------|------------|--------------|
| Pessoa Física | cnh | CNH (Carteira Nacional de Habilitação) | * |
| Pessoa Física | cin_digital | Carteira de Identidade Nacional (Digital) | * |
| Pessoa Física | rg_back | RG (Carteira de Identidade) - Verso | * |
| Pessoa Física | rg_front | RG (Carteira de Identidade) - Frente | * |
| Pessoa Física | power_of_attorney | Procuração PF ou PJ - Obrigatório caso representante seja um procurador | Necessário para comprovação de vínculo |

*Para quaisquer pessoas físicas, é necessário apenas um dentre RG frente e verso, CNH e Carteira de Identidade Nacional.

:::warning Atenção
Alguns tipos de documentos passam por uma ferramenta de OCR para extração e verificação dos dados. Deve-se sempre atentar ao retorno do envio de documento, que síncronamente retorna a validação - valid/accepted/invalid do OCR.
:::

## Tipos de Documento

### Document Type

| Enumerador                   | Descrição                |
| ---------------------------- | -------------------------- |
| **cnh**                      | CNH.                        |
| **rg_back**                  | RG parte traseira.          |
| **rg_front**                 | RG parte frontal.           |
| **passport**                 | Passaporte - exclusivo para estrangeiros.           |
| **national_migration_registry**                 | Registro Nacional de Migração.           |
| **cin_digital**                 | Carteira de Identidade Nacional (Digital).           |
| **social_contract**          | Contrato/Estatuto Social.   |
| **cnpj_card**          | Cartão CNPJ.   |
| **commercial_board_certificate** | Certidão Simplidicada da Junta Comercial. |
| **board_election_record** | Ata de Eleição da Diretoria Vigente. |
| **power_of_attorney**        | Procuração - obrigatório caso o representante seja um procurador. |
| **marital_power_of_attorney**        | Procuração Uxória - disponível apenas para cônjuges. |
| **compliance_statement**        | Parecer de Compliance. |
| **financial_statement**        | Demonstração Financeira. |
| **credit_report**        | Ata/Parecer de Crédito. |
| **manager_statement**        | Parecer/Ficha do Gestor. |
| **visit_report**        | Relatório de Visita. |
| **proof_of_residence**        | Comprovante de Residência. |
| **credit_agency_consulation**        | Consulta aos órgãos de Proteção de Crédito. |
| **annual_revenues_declaration**        | Declaração de Faturamento. |
| **financial_institutions_declaration**        | Declaração de Relacionamento Bancário. |
| **additional_document**        | Documento adicional - livre. |

### Document Status

| Enumerador              | Descrição   |
| ----------------------- | ------------- |
| **created**     | Criado    |
| **valid**       | Válido        |
| **invalid** | Inválido |
| **canceled** | Cancelado |
| **accepted** | Aceito, porém não validado |

---

# Cadastro de Filiais

URL: /documentation/iaas/homologacao_cedente/cadastro/filiais

Para a habilitação de filiais, existem dois fluxos operacionais que podem ser seguidos:

1. **Fluxo Completo (Do zero):** É o cadastro integral da filial, abrangendo desde dados de endereço e faturamento até informações de representantes legais e avalistas. Neste fluxo, a habilitação segue o processo padrão apresentado anteriormente na documentação, passando por aprovação de documentos e validação de poderes. Este fluxo exige um novo contrato de cessão para a efetiva habilitação do cedente no fundo.
2. **Fluxo Simplificado (Cadastro Vinculado):** Apresentado nesta página, este fluxo trata o cadastro da filial como um vínculo a uma matriz previamente cadastrada. Nele, apenas dados básicos são enviados e uma nova `assignor_registry_key` é criada, porém dados como representantes e avalistas são obrigatoriamente reaproveitados da análise da matriz.

:::info
Caso a filial já esteja cadastrada como cedente, também é possível vinculá-la à matriz. Nesse caso, a documentação, representação e avalistas anteriores são descartados, e a mesma passa a herdar os dados da matriz.
:::

## Vantagens do Fluxo Facilitado

Existem duas principais vantagens no fluxo de ativação facilitada de filiais:

* **Opções de Pagamento:** Ao realizar uma operação de cessão com a filial, as contas da matriz também se tornam opções de pagamento.
* **Replicação de Configurações:** Todas as Configurações de Cessão da matriz são automaticamente replicadas para a filial assim que aprovada, evitando a necessidade da etapa de assinatura de contrato. Para recuperar as novas chaves, recomendamos a utilização do GET de configuração de cessão paginado, tópico 5.3.1.2., com parâmetros como `assignment_contract_key`, `asset_type` e `assignor_document_number`, utilizando o contrato formalizado pela matriz como referência.

:::warning Atenção
O fluxo facilitado de filiais exige a presença da seguinte cláusula no contrato mãe formalizado com a matriz para ser utilizado:

> CONSIDERANDO que o CEDENTE declara e garante que, caso aplicável, é a matriz e detém plenos poderes para representar juridicamente todas as suas filiais perante a CESSIONÁRIA, inclusive para a prática de todos os atos necessários à formalização e à execução de cessões. O CEDENTE reconhece e assume responsabilidade solidária e ilimitada por todas as obrigações assumidas por suas filiais em decorrência de cessões realizadas junto à CESSIONÁRIA, renunciando, para todos os fins, a qualquer alegação de ausência de poderes ou de autonomia.
:::

---

## Criando uma nova Filial

Por mais que o PLD da matriz já tenha sido realizado, a primeira análise (a de vínculo) de uma filial sempre passa pela etapa de consulta e validação de dados externa, sendo necessário aguardar o hook de aprovação ou reprovação da análise gerada, que é enviada automaticamente.

### Request

ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/branch
MÉTODO POST

:::info
A `assignor_registry_key` enviada na requisição deve pertencer à MATRIZ do cedente, e a mesma já deve estar habilitada.
:::

```json title='Request Body'
{
    "document_number": "32.402.502/0002-16",
    "email": "qitechfilial@qitech.com.br",
    "phone": {
        "international_dial_code": "+55",
        "area_code": "11",
        "number": "936360269"
    },
    "address": {
        "street": "Rua Maria Carolina dois",
        "number": "624",
        "neighborhood": "Jardim Paulistano",
        "city": "Campinas",
        "postal_code": "01445-000",
        "uf": "SP",
        "country": "BRA"
    },
    "annual_revenues": 20000,
    "accounts": [
        {
            "account_branch": "0001",
            "account_number": "0423223",
            "account_digit": "6",
            "financial_institution_code": "329",
            "account_type": "checking_account",
            "default_account": true
        }
    ]
}
```

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `document_number` * | string | Número de documento do cedente (CNPJ). | 14 a 18 |
| `annual_revenues` * | number | Declaração de faturamento anual do cedente, em inteiros. | Mínimo de 1 |
| `email` * | string | Endereço de e-mail do cedente. | 1 a 255 |
| `phone`  | object | Objeto referenciando as informações do telefone do cedente. | Ver **[Definição de Telefone](#definição-de-telefone)**. |
| `address` * | object | Objeto referenciando as informações do endereço do cedente. | Ver **[Definição de Endereço](#definição-de-endereço)**. |
| `accounts` * | array | Lista de contas de desembolso do cedente.| Ver  **[Definição de Conta](#definição-de-conta)**. |

*Campos obrigatórios.

### Response

STATUS 201

```json title='Response Body'
{
  "assignor_registry_key": "9c130814-1aa5-4dcb-b6af-c4abdfca2947",
  "status": "pending_registry",
  "name": "QI Tech",
  "document_number": "32.402.502/0002-16",
  "last_analysis": {
    "analysis_key": "49bcaaca-6029-4f6f-97a0-d71f7cefb7ae",
    "analysis_number": 1,
	  "status": "sent_to_analysis",
    "analysis_related_parties": [
      {
        "analysis_related_party_key": "65a74b18-0da8-4460-844b-524c9941e615",
        "document_number": "802.834.257-41",
        "name": "Roberto Carlos",
        "documents": []
      },
      {
        "analysis_related_party_key": "f2bc3473-1686-4d15-9a06-b51d25e20cb4",
        "document_number": "883.512.866-80",
        "name": "Natália Nascimento",
        "documents": []
      },
      {
        "analysis_related_party_key": "272cc251-a56d-4b89-82a1-d815a319b9fb",
        "passport_number": "C01X00T47",
        "name": "Maria Vitoria",
        "documents": []
      }
    ],
    "documents": [
      {
        "document_key": "5530af20-f52e-4a2e-b0f3-732e8121f4b3",
        "document_type": "social_contract",
        "status": "valid",
      }
    ],
    "analysis_data": {}
  }
}
```

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `assignor_registry_key` | string | Identificador do cadastro. | 36 |
| `status` | string | Status do cadastro. | Ver **[Enumeradores de status do cadastro](#assignor-registry-status)**. |
| `name` | string | Nome do Cedente. | 1 a 255 |
| `document_number` | string | Documento do Cedente. | 14 a 18 |
| `last_analysis`  | object | Objeto de análise. | Ver **[Definição de Análise](#definição-de-análise)**. |

:::info
Toda informação de representação, avalistas e documentos serão automaticamente replicadas do cadastro da matriz. Entretanto, a conta enviada deve ser de titularidade da filial, caso contrário, futuras transferências falharão.
:::

:::info
É importante armazenar a assignor_registry_key, pois ela será utilizada em diversos outros processos, assim como a analysis_key e as analysis_related_party_key.
:::

### Erros Tratáveis

| Código | HTTP | Causa | Como resolver |
|--------|------|-------|---------------|
| ASR000004 | 404 | Cedente matriz não encontrado para o `assignor_registry_key` informado. | Garantir que `assignor_registry_key` na URL corresponda ao cadastro da matriz. |
| ASR000099 | 400 | Cedente pessoa física não pode ter filiais. | Apenas matrizes pessoa jurídica (`person_type=legal_person`) podem ter filiais. |
| ASR000096 | 400 | Status da matriz não permite ativação de filial. | A matriz deve estar com `status=registered` para criar uma filial. |
| ASR000097 | 400 | O cadastro referido não é uma matriz. | O `assignor_registry_key` na URL deve ser de um cadastro com `organization_level=headquarters`. |
| ASR000098 | 400 | Raiz do CNPJ da filial não corresponde à da matriz. | A raiz (8 primeiros dígitos) do `document_number` da filial deve ser idêntica à da matriz. |
| ASR000032 | 409 | Esse agente já cadastrou um cedente com esse `document_number`. | A filial já possui um cadastro vinculado a este agente; utilize o fluxo de [vínculo de filial existente](#vinculando-uma-filial-já-existente-à-matriz). |
| ASR000071 | 404 | Instituição financeira não encontrada para a conta da filial. | Validar o `financial_institution_code` informado em `accounts`. |
| ASR000087 | 400 | Informação de conta deve conter apenas números. | Enviar `account_branch`, `account_number` e `account_digit` apenas com dígitos. |
| ASR000081 | 400 | Mais de uma conta padrão foi enviada. | Apenas uma conta deve ter `default_account=true`. |

---

## Vinculando uma filial já existente à matriz

Caso tanto a filial quanto a matriz já existam em cadastros diferentes, é possível forçar o vínculo entre as duas. Nesse fluxo, todas as informações da filial que não compunham o payload da requisição de criação serão substituídas pelas informações da matriz.

### Request

ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/branch
MÉTODO PUT

:::info
A `assignor_registry_key` enviada na requisição deve pertencer à MATRIZ do cedente, e a mesma já deve estar habilitada.
:::

```json title='Request Body'
{
    "branch_assignor_registry_key": "9c130814-1aa5-4dcb-b6af-c4abdfca2947",
}
```

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `branch_assignor_registry_key` * | string | Identificador do cadastro. | 36 |

*Campos obrigatórios.

### Response

STATUS 200

```json title='Response Body'
{
  "assignor_registry_key": "9c130814-1aa5-4dcb-b6af-c4abdfca2947",
  "status": "pending_registry",
  "name": "QI Tech",
  "document_number": "32.402.502/0002-16",
  "last_analysis": {
    "analysis_key": "49bcaaca-6029-4f6f-97a0-d71f7cefb7ae",
    "analysis_number": 1,
	  "status": "sent_to_analysis",
    "analysis_related_parties": [
      {
        "analysis_related_party_key": "65a74b18-0da8-4460-844b-524c9941e615",
        "document_number": "802.834.257-41",
        "name": "Roberto Carlos",
        "documents": []
      },
      {
        "analysis_related_party_key": "f2bc3473-1686-4d15-9a06-b51d25e20cb4",
        "document_number": "883.512.866-80",
        "name": "Natália Nascimento",
        "documents": []
      },
      {
        "analysis_related_party_key": "272cc251-a56d-4b89-82a1-d815a319b9fb",
        "passport_number": "C01X00T47",
        "name": "Maria Vitoria",
        "documents": []
      }
    ],
    "documents": [
      {
        "document_key": "5530af20-f52e-4a2e-b0f3-732e8121f4b3",
        "document_type": "social_contract",
        "status": "valid",
      }
    ],
    "analysis_data": {}
  }
}
```

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `assignor_registry_key` | string | Identificador do cadastro. | 36 |
| `status` | string | Status do cadastro. | Ver **[Enumeradores de status do cadastro](#assignor-registry-status)**. |
| `name` | string | Nome do Cedente. | 1 a 255 |
| `document_number` | string | Documento do Cedente. | 14 a 18 |
| `last_analysis`  | object | Objeto de análise. | Ver **[Definição de Análise](#definição-de-análise)**. |

### Erros Tratáveis

| Código | HTTP | Causa | Como resolver |
|--------|------|-------|---------------|
| ASR000004 | 404 | Cedente matriz ou filial não encontrado. | Garantir que `assignor_registry_key` na URL pertença à matriz e que `branch_assignor_registry_key` no body pertença a um cadastro existente do mesmo agente. |
| ASR000099 | 400 | Cedente pessoa física não pode ter filiais. | Apenas matrizes pessoa jurídica podem vincular filiais. |
| ASR000096 | 400 | Status da matriz não permite vínculo de filial. | A matriz deve estar com `status=registered`. |
| ASR000097 | 400 | O cadastro referido não é uma matriz. | O `assignor_registry_key` na URL deve ser de um cadastro com `organization_level=headquarters`. |
| ASR000098 | 400 | Raiz do CNPJ da filial não corresponde à da matriz. | A raiz (8 primeiros dígitos) do `document_number` da filial deve ser idêntica à da matriz. |

---

## Atualizando dados de uma Filial

Por mais que seja um cadastro vinculado, as informações da filial ainda podem ser atualizadas, porém com algumas restrições:

Informações como email, phone, address e annual_revenues podem ser atualizadas utilizando o mesmo endpoint utilizado para alterar dados da matriz (apresentado abaixo). Entretanto, dados como name, related_parties, guarantors e a documentação em si devem ser atualizados sempre na Matriz. Quando a alteração da matriz é aprovada, todas as filiais vinculadas replicam os dados automaticamente.

### Request

ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY
MÉTODO PUT

```json title='Request Body'
{
  "email": "qidtvm@qitech.com.br",
  "annual_revenues": 1000000,
  "address": {
    "street": "Rua Maria Carolina",
    "number": "624",
    "neighborhood": "Jardim Paulistano",
    "city": "São Paulo",
    "postal_code": "01445-000",
    "uf": "SP",
    "country": "BRA"
  },
  "phone": {
    "international_dial_code": "+55",
    "area_code": "11",
    "number": "936360268"
  }
}
```

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `annual_revenues`  | number | Declaração de faturamento anual do cedente. | - |
| `email`  | string | Endereço de e-mail do cedente. | 1 a 255 |
| `phone`  | object | Objeto referenciando as informações do telefone do cedente. | Ver **[Definição de Telefone](#definição-de-telefone)**. |
| `address`  | object | Objeto referenciando as informações do endereço do cedente. | Ver **[Definição de Endereço](#definição-de-endereço)**. |

Caso não deseje alterar um campo, basta não enviá-lo na request.

### Response

STATUS 200

```json title='Response Body'
{
  "assignor_registry_key": "9c130814-1aa5-4dcb-b6af-c4abdfca2947",
  "status": "registred",
  "name": "QI Tech",
  "document_number": "32.402.502/0002-16",
  "last_analysis": {
    "analysis_key": "f51a49e1-842c-471f-a0e1-32ee9f12625d",
    "analysis_number": 2,
    "status": "approved",
    "analysis_related_parties": [
      {
        "analysis_related_party_key": "f361763a-91f5-4688-8e28-cc3f3fbccf9a",
        "document_number": "802.834.257-41",
        "name": "Roberto Carlos",
        "documents": []
      },
      {
        "analysis_related_party_key": "7ea3193b-8e53-40b7-94cf-2d3cc62942e0",
        "document_number": "883.512.866-80",
        "name": "Natália Nascimento",
        "documents": []
      },
      {
        "analysis_related_party_key": "f321f063-5f9a-4964-a24a-52deba128160",
        "passport_number": "C01X00T47",
        "name": "Maria Vitoria",
        "documents": []
      }
    ],
    "documents": [
      {
        "document_key": "994621ac-7d3f-4f6b-90c5-74a4d8c5d017",
        "document_type": "social_contract",
        "status": "valid",
      }
    ],
    "analysis_data": {}
  }
}
```

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `assignor_registry_key` | string | Identificador do cadastro. | 36 |
| `status` | string | Status do cadastro. | Ver **[Enumeradores de status do cadastro](#assignor-registry-status)**. |
| `name` | string | Nome do Cedente. | 1 a 255 |
| `document_number` | string | Documento do Cedente. | 14 a 18 |
| `last_analysis`  | object | Objeto de análise. | Ver **[Definição de Análise](#definição-de-análise)**. |

:::info
Diferente do cadastro de uma matriz, como as alterações não envolvem dados de representação e PLD, a alteração da filial é sempre aprovada AUTOMATICAMENTE.
:::

:::info
A manutenção de contas segue exatamente a mesma lógica da manutenção de contas da matriz, segundo a aba 5.2.2.5.
:::

### Erros Tratáveis

| Código | HTTP | Causa | Como resolver |
|--------|------|-------|---------------|
| ASR000004 | 404 | Cedente filial não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` na URL corresponde a um cadastro de filial. |
| ASR000100 | 400 | Campo enviado não pode ser atualizado em uma filial. | Em filiais, somente `email`, `phone`, `address` e `annual_revenues` podem ser atualizados. Para alterar `name`, `is_in_national_financial_system`, `related_parties` ou `guarantors`, atualizar o cadastro da matriz (ver [Atualização de Cadastro](/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro)). |

---

## Definições

### Definição de Endereço

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `street` * | string | Nome da rua. | 1 a 255 |
| `number` * | string | Número do endereço. | 1 a 4 |
| `neighborhood` * | string | Bairro. | 1 a 255 |
| `city` * | string | Cidade. | 1 a 255 |
| `uf` * | string | Sigla do estado. | 2 |
| `complement` | string | Complemento do endereço. | 1 a 255 |
| `postal_code` * | string | Código postal. | 9 (formato: XXXXX-XXX) |
| `country` * | string | País (sigla). | 3, de acordo com a ISO 3166-1 alpha-3 |

*Campos obrigatórios.

---

### Definição de Telefone

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `international_dial_code` * | string | Código internacional de discagem. | 1 a 3 |
| `area_code` * | string | Código de área. | 2 |
| `number` * | string | Número de telefone. | 8 a 9 |

*Campos obrigatórios.

---

### Definição de Parte Relacionada

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `name` * | string | Nome da parte relacionada. | 1 a 255 |
| `document_number` ** | string | Número de documento do beneficiário (CPF). | 14 a 18 |
| `passport_number` ** | string | Número de documento do beneficiário estrangeiro. | 8 a 9 |
| `related_party_type` * | string | Tipo de vínculo da parte relacionada. | Ver **[Enumeradores de tipo de parte relacionada](#related-party-type)** |
| `nationality` * | string | País de origem do beneficiário. | 3, de acordo com a ISO 3166-1 alpha-3 |
| `direct_beneficiary` * | boolean | Beneficiário diretamente ou indiretamente ligado ao cedente. | 1 a 255 |
| `is_representative` * | boolean | Indicador se a parte relacionada é representante assinante do cedente. | 1 a 255 |
| `company_registry_number` *** | string | Caso não seja diretamente ligado ao cedente, à qual companhia o mesmo está ligado. | 1 a 255 |
| `company_country` *** | string | País onde a companhia-elo entre o beneficiário e o cedente está registrada. | 3, de acordo com a ISO 3166-1 alpha-3 |
| `address` | object | Objeto referenciando as informações do endereço do representante. | Ver **[Definição de Endereço](#definição-de-endereço)**. |
| `email` **** | string | Endereço de e-mail do representante. | 1 a 255 |
| `phone` | object | Objeto referenciando as informações do telefone do representante. |  Ver **[Definição de Telefone](#definição-de-telefone)**. |
| `marital_status` | string | Estado civil da parte relacionada. | Ver **[Enumeradores de estado civil](#marital-status)**. |
| `property_system` | string | Regime de separação de bens. | Ver **[Enumeradores de regime de separação de bens](#property-system)**. |
| `profession` | string | Profissão da parte relacionada. | 1 a 255. |

*Campos obrigatórios.

**document_number obrigatório para brasileiros, para estrangeiros, caso tenha CPF, é possível utilizar o document_number, caso contrário, pelo menos o  passport_number deve ser enviado.

***Campos obrigatórios caso a parte relacionada não seja beneficiário diretamente ligada ao cedente. Caso contrário, não devem ser enviados.

****Campos exigidos apenas para representantes assinantes.

:::info
Campos não obrigatorios, como `marital_status` e `address`, podem ser enviados caso deseje uma qualificação mais completa no contrato mãe de cessão, nas etapas futuras.
:::

---

### Definição de Análise

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `analysis_key` * | string | Identificador da análise. | 36 |
| `analysis_number` * | integer | Número sequencial da análise. | - |
| `status` * | string | Status da análise. | Ver **[Enumeradores de status de análise](#analysis-status)**. |
| `analysis_related_parties` * | array | Partes Relacionadas da análise. | Ver **[Definição de Partes Relacionadas de Análise](#definição-de-partes-relacionadas-de-análise)**. |
| `documents` * | array | Documentos da anáise. | Ver **[Definição de Documentos de análise](#definição-de-documentos)**. |
| `analysis_data` * | object | Payload da request que originou a análise. | - |
| `analysis_datetime` * | string | Objeto date time da criação da análise. | - |
| `reproval_reason` | string | Enumerador com o motivo de rejeição da análise. | Ver **[Enumeradores de motivo de reprovação](#analysis-reproval-reason)**. |
| `reproval_details` | string | Campo livre com detalhes da rejeição da análise. | - |

*Campos obrigatórios.

---

### Definição de Partes Relacionadas de análise

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `analysis_related_party_key` * | string | Identificador da parte relacionada. | 36 |
| `document_number` * | string | Número de documento da parte relacionada. | 14 a 18 |
| `name` * | string | Nome da parte relacionada. | 1 a 255 |
| `documents` * | array | Documentos da anáise da parte relacionada. | Ver **[Definição de Documentos de análise](#definição-de-documentos)**. |

*Campos obrigatórios.

---

### Definição de Documentos

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `document_key` * | string | Identificador do documento. | 36 |
| `document_type` * | string | Tipo do documento. | Ver **[Enumeradores de tipo de documento](#document-type)**. |
| `status` | string | Status do documento. | Ver **[Enumeradores de status de documento](#document-status)**. |
| `observation` | string | Observações enviadas. | - |

*Campos obrigatórios.

---

### Definição de Conta

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `account_branch` * | string | Agência da conta do cedente. | 4 |
| `account_number` * | string | Número da conta do cedente. | 3 - 20 |
| `account_digit` * | string | Dígito da conta do cedente. | 1 |
| `financial_institution_code` * | string | Código do banco da conta do cedente. | 3 |
| `account_type` * | string | Tipo de conta. | Ver **[Enumeradores de tipo de conta](#account-type)**. |
| `default_account` * | boolean | Conta padrão de desembolso. | - |

*Campos obrigatórios.

Apenas uma conta do cedente pode ser a conta padrão, que será a conta para qual o dinheiro das cessões será enviado caso nenhuma conta alternativa seja indicada. Caso sejam enviadas mais de uma conta padrão, um erro será retornado.

:::warning Atenção
Muito cuidado ao preencher os dados da conta. Caso a conta seja inválida, o pagamento da cessão não ocorrerá, e toda a operação será cancelada.
:::

---

### Definição de Avalista

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `name` * | string | Nome do Avalista. | 3 - 255 |
| `document_number` * | string | Número de documento do avalista. | 14 a 18 |
| `person_type` * | string | Tipo de pessoa (física ou jurídica) do cedente. | - |
| `email` * | string | Endereço de e-mail do avalista. | 1 a 255 |
| `nationality` | string | País de origem do avalista. | 3, de acordo com a ISO 3166-1 alpha-3 |
| `phone` | object | Objeto referenciando as informações do telefone do avalista. |  Ver **[Definição de Telefone](#definição-de-telefone)**. |
| `address` | object | Objeto referenciando as informações do endereço do avalista. | Ver **[Definição de Endereço](#definição-de-endereço)**. |
| `guarantor_representatives` | array | Assinantes do Avalista - Apenas para avalista pessoa jurídica. | Ver  **[Definição de Representante do Avalista](#definição-de-representante-do-avalista)**. |
| `marital_status` | string | Estado civil do avalista. | Ver **[Enumeradores de estado civil](#marital-status)**. |
| `property_system` | string | Regime de separação de bens. | Ver **[Enumeradores de regime de separação de bens](#property-system)**. |
| `profession` | string | Profissão do avalista. | 1 a 255. |

*Campos obrigatórios.

O campo `guarantor_representatives` pode ser utilizado para indicar tanto representantes de um avalista pessoa jurídica, quanto, no caso de avalista pessoa física, onde se encontrar necessário, o cônjuge para realização da Outorga Uxória.

:::warning Atenção
Tanto o avalista quanto os representantes também serão adicionados à anáise gerada, sendo necessário enviar os documentos padrão de acordo com o tipo de pessoa do mesmo. Os mesmos também passam pelo processo de compliance, podendo gerar apontamentos.
:::

---

### Definição de Representante do Avalista

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `name` * | string | Nome do Representante. | 3 - 255 |
| `document_number` * | string | Número de documento do representante do avalista - obrigatóriamente pessoa física. | 14 |
| `email` * | string | Endereço de e-mail do representante do avalista. | 1 a 255 |
| `nationality` | string | País de origem do representante do avalista. | 3, de acordo com a ISO 3166-1 alpha-3 |
| `address` | object | Objeto referenciando as informações do endereço do representante do avalista. | Ver **[Definição de Endereço](#definição-de-endereço)**. |
| `phone` | object | Objeto referenciando as informações do telefone do representante do avalista. |  Ver **[Definição de Telefone](#definição-de-telefone)**. |
| `marital_status` | string | Estado civil do representante do avalista. | Ver **[Enumeradores de estado civil](#marital-status)**. |
| `property_system` | string | Regime de separação de bens. | Ver **[Enumeradores de regime de separação de bens](#property-system)**. |
| `profession` | string | Profissão do representante do avalista. | 1 a 255. |

---

# Enumeradores

### Assignor Registry Status

| Enumerador                 | Descrição       |
| -------------------------- | ----------------- |
| **pending_registry** | Pendente Registro |
| **registered**       | Registrado        |

---

### Analysis Status

| Enumerador              | Descrição           |
| ----------------------- | --------------------- |
| **pending_documents**  | Pendente Documentos   |
| **sent_to_analysis**   | Enviado para Análise |
| **pending_internal_validation** | Em Validação de documentos    |
| **in_manual_analysis** | Em Análise Manual de Compliance    |
| **approved**           | Aprovado              |
| **reproved**           | Reprovado             |
| **canceled**           | Cancelado             |

---

### Related Party Type

| Enumerador              | Descrição   |
| ----------------------- | ------------- |
| **president**     | Presidente    |
| **partner**       | Sócio        |
| **administrator** | Administrador |
| **director**      | Diretor       |
| **manager**       | Gestor        |
| **attorney**      | Procurador    |

---

### Document Status

| Enumerador              | Descrição   |
| ----------------------- | ------------- |
| **created**     | Criado    |
| **valid**       | Válido        |
| **invalid** | Inválido |
| **canceled** | Cancelado |
| **accepted** | Aceito, porém não validado |

---

### Document Type

| Enumerador                   | Descrição                |
| ---------------------------- | -------------------------- |
| **cnh**                      | CNH.                        |
| **rg_back**                  | RG parte traseira.          |
| **rg_front**                 | RG parte frontal.           |
| **passport**                 | Passaporte - exclusivo para estrangeiros.           |
| **national_migration_registry**                 | Registro Nacional de Migração.           |
| **cin_digital**                 | Carteira de Identidade Nacional (Digital).           |
| **social_contract**          | Contrato/Estatuto Social.   |
| **cnpj_card**          | Cartão CNPJ.   |
| **commercial_board_certificate** | Certidão Simplidicada da Junta Comercial. |
| **board_election_record** | Ata de Eleição da Diretoria Vigente. |
| **power_of_attorney**        | Procuração - obrigatório caso o representante seja um procurador. |
| **marital_power_of_attorney**        | Procuração Uxória - disponível apenas para cônjuges. |
| **compliance_statement**        | Parecer de Compliance. |
| **financial_statement**        | Demonstração Financeira. |
| **credit_report**        | Ata/Parecer de Crédito. |
| **manager_statement**        | Parecer/Ficha do Gestor. |
| **visit_report**        | Relatório de Visita. |
| **proof_of_residence**        | Comprovante de Residência. |
| **credit_agency_consulation**        | Consulta aos órgãos de Proteção de Crédito. |
| **annual_revenues_declaration**        | Declaração de Faturamento. |
| **financial_institutions_declaration**        | Declaração de Relacionamento Bancário. |
| **additional_document**        | Documento adicional - livre. |

---

### Account Type

| Enumerador           | Descrição           |
|----------------------|---------------------|
| **checking_account** | Conta Corrente      |

---

### Analysis Reproval Reason
| Enum         | 	Description  |
|--------------|---------------|
| **assignor_update**   | Análise cancelada devido à atualização cadastral posterior |
| **insuficient_documents**  | Documentação mínima para comprovação de poderes não enviada |
| **compliance_reproval**  | Reprovação de vínculo por análise do time de compliance |
| **unidentified_related_parties** | Parte relacionada enviada, porém vinculo não comprovado |
| **invalid_documents** | Documentação inválida/expirada |
| **missing_related_parties** | Parte relacionada obrigatória não enviada |

---

### Marital Status
| Enum         | 	Description  |
|--------------|---------------|
| **single**   | Solteiro(a)   |
| **married**  | Casado(a)    |
| **widower**  | Viúvo(a)     |
| **divorced** | Divorciado(a) |
| **separated** | Separado(a) |
| **stable_union** | Em União Estável |

---

### Property System

| Enum                              | Descrição                              |
| --------------------------------- | -------------------------------------- |
| **total_communion_of_goods**        | Comunhão Total de Bens                |
| **partial_communion_of_goods**      | Comunhão Parcial de Bens              |
| **total_separation_of_goods**       | Separação Total de Bens               |
| **final_participation_of_acquisitions** | Participação Final nos Aquestos    |
| **compulsory_separation_of_goods**  | Separação Obrigatória de Bens         |

---

# Contas do cedente

URL: /documentation/iaas/homologacao_cedente/cadastro/manutencao_de_contas

No ato do cadastro do cedente, é obrigatório providenciar ao menos uma conta de desembolso de cessão para o cedente. Na etapa de aprovação da cessão pela gestora, é possível indicar qualquer uma das contas cadastradas para o cedente para ocorrer o desembolso da mesma. Vale ressaltar que, caso o proponente da operação entre cedente-fundo seja um consultor, a manutenção das contas será de responsabilidade da consultoria ao invś da gestora.

Diferente de dados cadastrais, como representantes, endereços, e outros dados, não será criada uma nova análise ao realizar uma alteração nas contas do cedente, sendo assim, a alteração passa a valer de imediato. Para uma conta de desembolso, obrigatóriamente o titular da conta deve ser o cedente, inclusive a titularidade da conta, e o número de documento do dono da conta já é assumido ser o do cedente.

:::warning Atenção
Muito cuidado ao preencher os dados da conta. Caso a conta seja inválida, o pagamento da cessão não ocorrerá, e toda a operação será cancelada.
:::

---

## Adição de conta alternativa

### Request

ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/account
MÉTODO POST

```json title='Request Body'
{
    "account_number": "8473124",
    "account_digit": "8",
    "account_branch": "0001",
    "account_type": "checking_account",
    "financial_institution_code": "329",
    "default_account": false
}
```

## Objeto de Conta

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `account_number` * | string | Número da conta. | 3-20 |
| `account_digit` * | string | Dígito da conta. | 1 |
| `account_branch` * | string | Agência da conta. | 4 |
| `account_type` * | string | Tipo da conta. | - |
| `financial_institution_code` * | string | Código do banco da conta. | 3 |
| `default_account` * | boolean | Conta padrão de desembolso. | - |

*Campos obrigatórios.

### Response

STATUS 201

```json title='Response Body'
{
    "account_key": "3c53a94a-2b81-4837-b7eb-8e025e69d81c",
    "account_branch": "0001",
    "account_number": "8473124",
    "account_digit": "8",
    "account_type": "checking_account",
    "status": "active",
    "financial_institution_code": "329",
    "financial_institution_ispb": "32402502",
    "default_account": false,
}
```

:::info
Caso a conta nova seja enviada com "default_account" true, a antiga conta padrão de desembolso será tornada uma conta não padrão, e a partir de então, a nova conta postada será a padrão de desembolso.
:::

### Erros Tratáveis

| Código | HTTP | Causa | Como resolver |
|--------|------|-------|---------------|
| ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto. |
| ASR000072 | 409 | Já existe uma conta ativa com a mesma combinação de banco, agência, conta e dígito. | Não enviar contas duplicadas — verificar as contas já cadastradas para o cedente. |
| ASR000087 | 400 | Informação de conta deve conter apenas números. | Enviar `account_branch`, `account_number`, `account_digit` e `financial_institution_code` apenas com dígitos. |
| ASR000071 | 404 | Instituição financeira não encontrada. | Validar o `financial_institution_code` (código bancário) informado. |

## Atualização de conta

Não é possível alterar os dados de uma conta. Caso deseje, é necessário desativar a conta errada, e criar uma nova conta com os dados válidos.

Para alterar a conta padrão de desembolso, basta indicar qual será a nova conta, que a antiga será alterada automaticamente. Não é possível definir uma conta como não padrão de desembolso, deve-se sempre indicar a nova.

### Request

ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/account/ACCOUNT_KEY
MÉTODO PUT

```json title='Request Body'
{
    "status": "active",
    "default_account": true,
}
```

## Objeto de Conta

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `status` | string | Novo status da conta. | Ver **[Enumeradores de status de conta](#account-status)**. |
| `default_account` | boolean | Conta padrão de desembolso. | - |

*Campos obrigatórios (nenhum).

### Response

STATUS 200

```json title='Response Body'
{
    "account_key": "3c53a94a-2b81-4837-b7eb-8e025e69d81c",
    "account_branch": "0001",
    "account_number": "8473124",
    "account_digit": "8",
    "account_type": "checking_account",
    "status": "active",
    "financial_institution_code": "329",
    "financial_institution_ispb": "32402502",
    "default_account": true,
}
```

:::info
Caso a atualização enviada com "default_account" true, a antiga conta padrão de desembolso será tornada uma conta não padrão, e a partir de então, a nova conta postada será a padrão de desembolso. Não é possível desativar uma conta padrão, ou definir como padrão uma conta inativa.
:::

### Erros Tratáveis

| Código | HTTP | Causa | Como resolver |
|--------|------|-------|---------------|
| ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto. |
| ASR000073 | 404 | Conta não encontrada para o `account_key` informado. | Verificar se o `account_key` pertence ao cedente. |
| ASR000074 | 400 | Não é possível desativar/desmarcar uma conta padrão. | Indicar primeiro outra conta como padrão (`default_account=true` em outra conta) antes de inativar a atual. |
| ASR000075 | 400 | Nenhuma informação foi enviada para atualização. | Informar `status` ou `default_account` no corpo da requisição. |

# Enumeradores

### Account Status

| Enumerador                 | Descrição       |
| -------------------------- | ----------------- |
| **active** | Conta ativa e disponível como opção de desembolso. |
| **inactive** | Conta inativa e indisponível para desembolo. |

---

# Webhooks

URL: /documentation/iaas/homologacao_cedente/cadastro/webhooks_analise

---
## Webhooks de Análise
---

#### Drivação para Compliance

STATUS in_manual_analysis

```json title='Webhook Body'
{
    "data":{
        "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4",
        "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
        "analysis_status": "in_manual_analysis",
        "reproval_reason": null,
        "reproval_details": null,
    },
    "webhook_type":"assignor_registry.analysis_status_change",
    "webhook_datetime":"2025-01-22T20:30:23.459Z"
}
```

#### Em análise de Documentos

STATUS pending_internal_validation

```json title='Webhook Body'
{
    "data":{
        "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4",
        "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
        "analysis_status": "pending_internal_validation",
        "reproval_reason": null,
        "reproval_details": null,
    },
    "webhook_type":"assignor_registry.analysis_status_change",
    "webhook_datetime":"2025-01-22T20:30:23.459Z"
}
```

#### Aprovado

STATUS approved

```json title='Webhook Body'
{
    "data":{
        "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4",
        "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
        "status": "approved",
        "reproval_reason": null,
        "reproval_details": null,
    },
    "webhook_type":"assignor_registry.analysis_status_change",
    "webhook_datetime":"2025-01-22T20:30:23.459Z"
}
```

#### Reprovado

STATUS reproved

```json title='Webhook Body'
{
    "data":{
        "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4",
        "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
        "status": "reproved",
        "reproval_reason": "insuficient_documents",
        "reproval_details": "Anexar procuração do sócio XXX.XXX.XXX-XX.",
    },
    "webhook_type":"assignor_registry.analysis_status_change",
    "webhook_datetime":"2025-01-22T20:30:23.459Z"
}
```

#### Cancelado

STATUS canceled

Disparado quando uma análise é cancelada. O caso mais comum é o **cancelamento automático por inatividade**: uma análise que fica **1 mês sem movimentação** — tipicamente parada em `pending_documents`, sem documentos anexados ou sem o disparo da análise — é cancelada pela QI Tech.

O status é **terminal**. Para retomar o cadastro, gere uma nova análise por meio da [Atualização de Cadastro](/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro).

```json title='Webhook Body'
{
    "data":{
        "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4",
        "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
        "analysis_status": "canceled",
        "reproval_reason": null,
        "reproval_details": null,
    },
    "webhook_type":"assignor_registry.analysis_status_change",
    "webhook_datetime":"2025-01-22T20:30:23.459Z"
}
```

## Webhooks de Apontamento
---

Disparados sempre que um [Apontamento de Compliance](/documentation/iaas/homologacao_cedente/cadastro/apontamentos) tem seu status alterado. São enviados quando o apontamento é aberto (`open`) e quando é respondido (`closed`).

:::info
Apontamentos originados por carga da Fromtis (`fromtis_load`) não disparam webhook.
:::

#### Apontamento aberto

STATUS open

```json title='Webhook Body'
{
    "data":{
        "annotation_key": "1f2e3d4c-5b6a-4c8d-9e0f-1a2b3c4d5e6f",
        "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
        "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4",
        "annotation_status": "open",
        "message": "Anexar procuração do sócio XXX.XXX.XXX-XX.",
    },
    "webhook_type":"assignor_registry.annotation_status_change",
    "webhook_datetime":"2025-01-22T20:30:23Z"
}
```

#### Apontamento respondido

STATUS closed

```json title='Webhook Body'
{
    "data":{
        "annotation_key": "1f2e3d4c-5b6a-4c8d-9e0f-1a2b3c4d5e6f",
        "analysis_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
        "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4",
        "annotation_status": "closed",
        "message": "Anexar procuração do sócio XXX.XXX.XXX-XX.",
    },
    "webhook_type":"assignor_registry.annotation_status_change",
    "webhook_datetime":"2025-01-22T20:30:23Z"
}
```

## Webhooks de Cadastro
---

#### Cedente ativado

STATUS registered

```json title='Webhook Body'
{
    "data":{
        "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4",
        "status": "registered",
    },
    "webhook_type":"assignor_registry.assignor_registry_status_change",
    "webhook_datetime":"2025-01-22T20:30:23.459Z"
}
```

#### Cedente expirado

STATUS expired

```json title='Webhook Body'
{
    "data":{
        "assignor_registry_key": "35ff6e5c-a3e7-4b04-a8be-6e49a3a906e4",
        "status": "expired",
    },
    "webhook_type":"assignor_registry.assignor_registry_status_change",
    "webhook_datetime":"2025-01-22T20:30:23.459Z"
}
```

---

# Consulta de Análise

URL: /documentation/iaas/homologacao_cedente/consulta/consulta_de_analise

---

O campo `status` da análise segue os **[Enumeradores de status de análise](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#analysis-status)**.

:::info Status `canceled`
Uma análise que fica **1 mês sem movimentação** — tipicamente parada em `pending_documents`, sem documentos anexados ou sem o disparo da análise — é **cancelada automaticamente** e passa a `canceled`. O status é terminal: a análise não aceita mais documentos nem disparo. Para retomar o cadastro, gere uma nova análise por meio da [Atualização de Cadastro](/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro).
:::

## Consulta de Análise Por Chave

### Request

ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analysis/ANALYSIS_KEY
MÉTODO GET

### Response

STATUS 200

```json title='Response Body'
{
  "analysis_key": "d7805a05-98a7-486b-a440-807f1d3d5691",
  "analysis_number": 1,
  "assignor_registry_key": "c4295375-4077-4092-a258-5bcdf8875907",
  "status": "pending_documents",
  "documents": [
    {
      "document_key": "994621ac-7d3f-4f6b-90c5-74a4d8c5d017",
      "document_type": "social_contract",
      "status": "valid",
    }
  ],
  "analysis_related_parties": [
    {
      "analysis_related_party_key": "5cdcc13b-c67d-45f3-aa66-36cb4f178b59",
      "document_number": "802.834.257-41",
      "name": "Natália Nascimento",
      "documents": [
        {
          "document_key": "72bad379-dbe6-40ca-97f2-1181257889ba",
          "document_type": "cnh",
          "status": "valid",
        }
      ]
    },
    {
      "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721",
      "document_number": "883.512.866-80",
      "name": "Natália Nascimento",
      "documents": [
        {
          "document_key": "8b9fe448-7ad7-4410-b8f7-5c920b07b9a7",
          "document_type": "cnh",
          "status": "valid",
        }
      ]
    }
  ],
  "analysis_data": {
    "assignor_registry_key": "c4295375-4077-4092-a258-5bcdf8875907",
    "status": "pending_registry",
    "name": "QI CTVM",
    "document_number": "67.987.787/0001-06",
    "person_type": "legal_person",
    "email": "qidtvm@qitech.com.br",
    "phone": {
      "number": "936360268",
      "area_code": "11"
    },
    "address": {
      "uf": "SP",
      "city": "São Paulo",
      "number": "215",
      "street": "Gilberto Sabino",
      "country": "BRA",
      "postal_code": "05425-020",
      "neighborhood": "Pinheiros"
    },
    "related_parties": [
      {
        "name": "Natália Nascimento",
        "document_number": "883.512.866-80",
        "related_party_type": "attorney",
        "nationality": "BRA",
        "direct_beneficiary": true,
        "is_representative": true,
        "email": "natalia.nascimento@yopmail.com",
        "phone": {
          "international_dial_code": "+55",
          "area_code": "11",
          "number": "936360268"
        }
      },
      {
        "name": "Maria Vitoria",
        "related_party_type": "president",
        "nationality": "DEU",
        "passport_number": "C01X00T47",
        "direct_beneficiary": true,
        "is_representative": false

      },
      {
        "name": "Roberto Carlos",
        "document_number": "802.834.257-41",
        "related_party_type": "director",
        "nationality": "BRA",
        "direct_beneficiary": false,
        "company_country": "NZL",
        "company_registry_number": "4984037284610",
        "is_representative": true,
        "email": "roberto.carlos@yopmail.com",
        "phone": {
          "international_dial_code": "+64",
          "area_code": "11",
          "number": "936360268"
        }
      }
    ]
  }
}
```

### Erros Tratáveis

| Código | HTTP | Causa | Como resolver |
|--------|------|-------|---------------|
| ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto e pertence ao agente autenticado. |
| ASR000033 | 404 | Análise não encontrada para o `analysis_key` informado. | Verificar se o `analysis_key` está correto. |

---

## Consulta Paginada de Análises

### Request

ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY/analyses
MÉTODO GET

### Path params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `limit` | integer | Limite de objetos | - |
| `page` | integer | Página desejada | - |

### Response

STATUS 200

```json title='Response Body'
{
    "data": [
      {
        "analysis_key": "d7805a05-98a7-486b-a440-807f1d3d5691",
        "analysis_number": 1,
        "assignor_registry_key": "c4295375-4077-4092-a258-5bcdf8875907",
        "status": "pending_documents",
        "documents": [
          {
            "document_key": "994621ac-7d3f-4f6b-90c5-74a4d8c5d017",
            "document_type": "social_contract",
            "status": "valid",
          }
        ],
        "analysis_related_parties": [
          {
            "analysis_related_party_key": "5cdcc13b-c67d-45f3-aa66-36cb4f178b59",
            "document_number": "802.834.257-41",
            "name": "Natália Nascimento",
            "documents": [
              {
                "document_key": "72bad379-dbe6-40ca-97f2-1181257889ba",
                "document_type": "cnh",
                "status": "valid",
              }
            ]
          },
          {
            "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721",
            "document_number": "883.512.866-80",
            "name": "Natália Nascimento",
            "documents": [
              {
                "document_key": "8b9fe448-7ad7-4410-b8f7-5c920b07b9a7",
                "document_type": "cnh",
                "status": "valid",
              }
            ]
          }
        ],
      }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true,
}
```

### Erros Tratáveis

| Código | HTTP | Causa | Como resolver |
|--------|------|-------|---------------|
| ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto e pertence ao agente autenticado. |

---

# Consulta de Assinantes

URL: /documentation/iaas/homologacao_cedente/consulta/consulta_de_assinantes

Consulta **paginada** dos conjuntos de assinantes (`signer_group_sets`) vinculados ao cedente e às suas partes relacionadas. Retorna tanto os conjuntos padrão (`main`), gerados pela análise da Administradora, quanto os conjuntos customizados (`custom`) definidos pelo cliente.

:::info Informação
Cada conjunto está vinculado a um proprietário (`owner`), que pode ser o **cedente** (`assignor_registry`) ou uma **parte relacionada de análise** (`analysis_related_party`, de avalistas), e a um tipo de produto.

Para criar conjuntos customizados, consulte [Definição de Assinantes](/documentation/iaas/homologacao_cedente/cadastro/definicao_de_assinantes).
:::

---

## Consulta Paginada de Conjuntos de Assinantes

### Request

ENDPOINT /assignor_registry/signer_group_sets
MÉTODO GET

#### Query Parameters

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `limit` | integer | Quantidade de itens por página (0 a 50). Padrão: 10. |
| `page` | integer | Página a ser consultada, iniciando em 0. Padrão: 0. |
| `owner_key` | string | Filtra pelo identificador do proprietário (cedente ou parte relacionada). |
| `owner_type` | string | Tipo do proprietário. Ver **[Owner Type](#owner-type)**. |
| `owner_document_number` | string | Documento do proprietário. Exige `owner_type` para ser utilizado. |
| `product_type` | string | Filtra por tipo de produto. Ver **[Product Type](#product-type)**. |
| `status` | string | Filtra pelo status do conjunto. Ver **[Signer Group Set Status](#signer-group-set-status)**. |

:::tip Dica
Para listar apenas os conjuntos que estão efetivamente sendo utilizados nas assinaturas, filtre por `status=valid`. Conjuntos em `in_analysis` ainda dependem da aprovação do cadastro e não são enviados para assinatura.
:::

### Response

STATUS 200

```json title='Response Body'
{
  "data": [
    {
      "signer_group_set_key": "f2c1e4a8-91d2-4f10-8a3b-7e5c9b2d4a6e",
      "owner_key": "c4295375-4077-4092-a258-5bcdf8875907",
      "owner_type": "assignor_registry",
      "product_type": "assignment_contract",
      "signer_group_set_type": "custom",
      "status": "valid",
      "signer_groups": [
        {
          "minimum_required_signers": 2,
          "signers": [
            {
              "document_number": "883.512.866-80",
              "is_required_signer": true
            },
            {
              "document_number": "802.834.257-41",
              "is_required_signer": false
            }
          ],
          "expiration": null
        }
      ]
    }
  ],
  "limit": 10,
  "page": 0,
  "is_last_page": true
}
```

#### Campos de Paginação

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `data` | array | Lista de conjuntos de assinantes da página atual. Ver **[Definição de Conjunto de Assinantes](#definicao-de-conjunto-de-assinantes-signer-group-set)**. |
| `limit` | integer | Quantidade de itens por página utilizada na consulta. |
| `page` | integer | Página retornada, iniciando em 0. |
| `is_last_page` | boolean | Indica se esta é a última página do resultado. |

### Erros Tratáveis

| Código | HTTP | Causa | Como resolver |
|--------|------|-------|---------------|
| ASR000121 | 400 | `owner_document_number` enviado sem `owner_type`. | Ao filtrar por `owner_document_number`, sempre informar também `owner_type`. |
| ASR000120 | 400 | Valor de `status` inválido no filtro. | Usar um valor válido para o filtro `status` (ver enum [Signer Group Set Status](#signer-group-set-status)). |

---

## Definições

### Definição de Conjunto de Assinantes (Signer Group Set)

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `signer_group_set_key` | string | Identificador único do conjunto. | 36 |
| `owner_key` | string | Identificador do proprietário. Pode ser `assignor_registry_key` ou `analysis_related_party_key`. | 36 |
| `owner_type` | string | Tipo do proprietário. | Ver **[Owner Type](#owner-type)**. |
| `product_type` | string | Tipo de produto ao qual o conjunto está associado. | Ver **[Product Type](#product-type)**. |
| `signer_group_set_type` | string | Tipo do conjunto (`main` ou `custom`). | Ver **[Signer Group Set Type](#signer-group-set-type)**. |
| `status` | string | Status do conjunto. | Ver **[Signer Group Set Status](#signer-group-set-status)**. |
| `signer_groups` | array | Lista de grupos de assinantes que compõem o conjunto. | Ver **[Definição de Grupo de Assinantes](#definicao-de-grupo-de-assinantes-signer-group)**. |

---

### Definição de Grupo de Assinantes (Signer Group)

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `minimum_required_signers` | number | Quantidade mínima de assinantes do grupo necessários para validar a assinatura. | Mínimo 1 |
| `signers` | array | Lista de assinantes do grupo. | Ver **[Definição de Assinante](#definicao-de-assinante-signer)**. |
| `expiration` | string | Data de expiração do grupo no formato `YYYY-MM-DD`. Retorna `null` quando o grupo não expira. | 10 |

---

### Definição de Assinante (Signer)

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `document_number` | string | CPF do assinante no formato `XXX.XXX.XXX-XX`. | 14 |
| `is_required_signer` | boolean | Indica se o assinante é obrigatório no grupo. | - |

---

# Enumeradores

### Owner Type

| Enumerador | Descrição |
|------------|-----------|
| **assignor_registry** | Conjunto vinculado ao cedente. |
| **analysis_related_party** | Conjunto vinculado a uma parte relacionada da análise (avalistas). |

---

### Product Type

| Enumerador | Descrição |
|------------|-----------|
| **assignment_contract** | Contrato de cessão (utilizado por padrão). |
| **commercial_paper** | Nota Comercial (Cadastro único com a plataforma de escrituração). |

---

### Signer Group Set Type

| Enumerador | Descrição |
|------------|-----------|
| **main** | Conjunto padrão, gerado da análise da Administradora. |
| **custom** | Conjunto customizado, criado pelo cliente sobrepondo o conjunto `main`. |

---

### Signer Group Set Status

| Enumerador | Descrição |
|------------|-----------|
| **in_analysis** | Conjunto enviado e atrelado à análise em aberto. Não é utilizado nas assinaturas. |
| **valid** | Conjunto vigente e utilizado nas assinaturas. |
| **inactive** | Conjunto substituído por uma versão mais recente ou desativado. |

---

# Consulta de Cedente

URL: /documentation/iaas/homologacao_cedente/consulta/consulta_de_cedente

---

## Consulta de Cedente Por Chave

### Request

ENDPOINT /assignor_registry/assignor_registry/ASSIGNOR_REGISTRY_KEY
MÉTODO GET

---

### Response

STATUS 200

```json title='Response Body'
{
  "assignor_registry_key": "c4295375-4077-4092-a258-5bcdf8875907",
  "status": "registred",
  "name": "QI CTVM",
  "document_number": "67.987.787/0001-06",
  "person_type": "legal_person",
  "email": "qidtvm@qitech.com.br",
  "annual_revenues": 1000000,
  "is_in_national_financial_system": true,
  "address": {
    "street": "Rua Maria Carolina",
    "number": "624",
    "neighborhood": "Jardim Paulistano",
    "city": "São Paulo",
    "postal_code": "01445-000",
    "uf": "SP",
    "country": "BRA"
  },
  "phone": {
    "international_dial_code": "+55",
    "area_code": "11",
    "number": "936360268"
  },
  "related_parties": [
    {
      "name": "Natália Nascimento",
      "document_number": "883.512.866-80",
      "related_party_type": "attorney",
      "nationality": "BRA",
      "direct_beneficiary": true,
      "is_representative": true,
      "email": "natalia.nascimento@yopmail.com",
      "phone": {
        "international_dial_code": "+55",
        "area_code": "11",
        "number": "936360268"
      }
    },
    {
      "name": "Maria Vitoria",
      "related_party_type": "president",
      "nationality": "DEU",
      "passport_number": "C01X00T47",
      "direct_beneficiary": true,
      "is_representative": false

    },
    {
      "name": "Roberto Carlos",
      "document_number": "802.834.257-41",
      "related_party_type": "director",
      "nationality": "BRA",
      "direct_beneficiary": false,
      "company_country": "NZL",
      "company_registry_number": "4984037284610",
      "is_representative": true,
      "email": "roberto.carlos@yopmail.com",
      "phone": {
        "international_dial_code": "+64",
        "area_code": "11",
        "number": "936360268"
      }
    }
  ],
  "last_analysis": {
    "analysis_key": "d7805a05-98a7-486b-a440-807f1d3d5691",
    "analysis_number": 1,
    "assignor_registry_key": "c4295375-4077-4092-a258-5bcdf8875907",
	  "status": "pending_documents",
    "analysis_related_parties": [
      {
        "analysis_related_party_key": "5cdcc13b-c67d-45f3-aa66-36cb4f178b59",
        "document_number": "802.834.257-41",
        "name": "Natália Nascimento",
      },
      {
        "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721",
        "document_number": "883.512.866-80",
        "name": "Natália Nascimento",
      }
    ],
    "documents": [],
    "analysis_data": {}
  }
}
```

### Objeto Cedente

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `assignor_registry_key` | string | Identificador do cadastro. | 36 |
| `name` * | string | Nome do cedente. | 1 a 255 |
| `document_number` * | string | Número de documento do cedente (CNPJ). | 14 a 18 |
| `status` | enumerador | Status do cadastro. | 14 a 18 |
| `annual_revenues` * | number | Declaração de faturamento anual do cedente, em inteiros. | Mínimo de 1 |
| `person_type` * | string | Tipo de pessoa (física ou jurídica) do cedente. | - |
| `email` * | string | Endereço de e-mail do cedente. | 1 a 255 |
| `is_in_national_financial_system` * | boolean | Indicador se o cedente é integrante do SFN. | - |
| `phone`  | object | Objeto referenciando as informações do telefone do cedente. | Ver **[Definição de Telefone](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-telefone)**. |
| `address` * | object | Objeto referenciando as informações do endereço do cedente. | Ver **[Definição de Endereço](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-endereco)**. |
| `related_parties` * | array | Lista de partes relacionadas da empresa.| Ver  **[Definição de Parte Relacionada](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-parte-relacionada)**. |
| `accounts` * | array | Lista de contas de desembolso do cedente.| Ver  **[Definição de Conta](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-conta)**. |
| `guarantors` * | array | Lista de avalistas do cedente.| Ver  **[Definição de Avalista](/documentation/iaas/homologacao_cedente/cadastro/envio_de_cadastro#definicao-de-avalista)**. |

### Erros Tratáveis

| Código | HTTP | Causa | Como resolver |
|--------|------|-------|---------------|
| ASR000004 | 404 | Cedente não encontrado para o `assignor_registry_key` informado. | Verificar se o `assignor_registry_key` está correto e pertence ao agente autenticado. |

---

## Consulta Paginada de Cedentes

### Request

ENDPOINT /assignor_registry/assignor_registries
MÉTODO GET

### Path params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `name` | string | Nome do cedente | 1-255 |
| `document_number` | string | Número de documento do cedente | 1-18 |
| `assignor_registry_status` | string | Status do cedente | 1-255 |
| `analysis_status` | string | Status da análise mais recente | 1-255 |
| `limit` | integer | Limite de objetos | - |
| `page` | integer | Página desejada | - |

### Response

STATUS 200

```json title='Response Body'
{
  "data": [
    {
      "assignor_registry_key": "c4295375-4077-4092-a258-5bcdf8875907",
      "status": "registred",
      "name": "QI CTVM",
      "document_number": "67.987.787/0001-06",
      "person_type": "legal_person",
      "email": "qidtvm@qitech.com.br",
      "annual_revenues": 1000000,
      "is_in_national_financial_system": true,
      "address": {
        "street": "Rua Maria Carolina",
        "number": "624",
        "neighborhood": "Jardim Paulistano",
        "city": "São Paulo",
        "postal_code": "01445-000",
        "uf": "SP",
        "country": "BRA"
      },
      "phone": {
        "international_dial_code": "+55",
        "area_code": "11",
        "number": "936360268"
      },
      "related_parties": [
        {
          "name": "Natália Nascimento",
          "document_number": "883.512.866-80",
          "related_party_type": "attorney",
          "nationality": "BRA",
          "direct_beneficiary": true,
          "is_representative": true,
          "email": "natalia.nascimento@yopmail.com",
          "phone": {
            "international_dial_code": "+55",
            "area_code": "11",
            "number": "936360268"
          }
        },
        {
          "name": "Maria Vitoria",
          "related_party_type": "president",
          "nationality": "DEU",
          "passport_number": "C01X00T47",
          "direct_beneficiary": true,
          "is_representative": false

        },
        {
          "name": "Roberto Carlos",
          "document_number": "802.834.257-41",
          "related_party_type": "director",
          "nationality": "BRA",
          "direct_beneficiary": false,
          "company_country": "NZL",
          "company_registry_number": "49.846.582/0001-10",
          "is_representative": true,
          "email": "roberto.carlos@yopmail.com",
          "phone": {
            "international_dial_code": "+64",
            "area_code": "11",
            "number": "936360268"
          }
        }
      ],
      "last_analysis": {
        "analysis_key": "d7805a05-98a7-486b-a440-807f1d3d5691",
        "analysis_number": 1,
        "assignor_registry_key": "c4295375-4077-4092-a258-5bcdf8875907",
        "status": "pending_documents",
        "analysis_related_parties": [
          {
            "analysis_related_party_key": "5cdcc13b-c67d-45f3-aa66-36cb4f178b59",
            "document_number": "802.834.257-41",
            "name": "Natália Nascimento",
          },
          {
            "analysis_related_party_key": "d4c75c93-4aa9-4567-89c4-b49334927721",
            "document_number": "883.512.866-80",
            "name": "Natália Nascimento",
          }
        ],
        "documents": [],
        "analysis_data": {}
      }
    }
  ],
  "limit": 10,
  "page": 0,
  "is_last_page": true,
}
```

---

## Consulta de Conjuntos de Assinantes

A consulta dos assinantes vinculados ao cedente e suas partes relacionadas é feita através do endpoint paginado de conjuntos de assinantes (`signer_group_sets`), que retorna tanto os conjuntos padrão (`main`) gerados pela análise quanto os conjuntos customizados (`custom`) definidos pelo cliente.

Para a especificação completa do endpoint — incluindo filtros disponíveis (`owner_key`, `owner_type`, `owner_document_number`, `product_type` e `status`), paginação, formato de resposta e enumeradores —, consulte [Consulta de Assinantes](/documentation/iaas/homologacao_cedente/consulta/consulta_de_assinantes).

---

---

# Ativação do Produto

URL: /documentation/iaas/homologacao_cedente/contrato_de_cessao/ativacao_da_esteira

---

Para ativar o produto, basta escolher dentre as opções de um contrato qual produto deseja-se ativar. Uma vez escolhido, deve-se fazer uma requisição e esperar o Webhook com a assignment_configuration_key.

### Request

ENDPOINT /assignment_contract/assignment_contract/ASSIGNMENT_CONTRACT_KEY/product/PRODUCT_KEY
MÉTODO PUT

```json title='Request Body'
{
    "disbursement":{
        "target_account": {
            "account_branch": "0001",
            "account_digit": "1",
            "account_number": "92268",
            "financial_institution_code": "329",
            "account_type": "checking_account",
            "owner": {
                "document_number": "44.450.102/0001-84"
            }
        }
    }
}
```

### Response

STATUS 200

```json title='Response Body'
{
    "product_key": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
    "status": "pending_activation"
}
```

---

# Consultar Documentos

URL: /documentation/iaas/homologacao_cedente/contrato_de_cessao/consulta_de_documentos

---

### Request

ENDPOINT /assignment_contract/assignment_contract/ASSIGNMENT_CONTRACT_KEY/attached_document/DOCUMENT_KEY
MÉTODO GET

### Path Params

| Parâmetro                    | Descrição                          |
|------------------------------|------------------------------------|
| `assignment_contract_key`    | Chave da contrato de cessão        |
| `document_key`               | Chave do documento                 |

### Response 
STATUS 200

```json
{
   "document_key":"UUID",
   "document_type":"manager_declaration | assignment_contract",
   "status":"signed | pending_signature",
   "document_template_key":"UUID",
   "required_parties":[
      "manager | consultant | attestant"
   ],
   "download_url":"url para download do documento"
}
```

:::info Observação
O campo de download url trás a URL assinada para download do documento em sua versão mais atual, ou seja caso o documento esteja assinado ele vai trazer nesta mesma URL. A mesma expira, e não deve ser utilizada para consulta atemporal.
:::

### Definição de Documento Anexo

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `document_key` * | string | Chave única de identificação do documento. | 36 |
| `document_type` * | string | Tipo do documento. | -- |
| `status` * | string | Status do documento. | Ver **[Enumeradores de status do documento](#attached-document-status)**. |
| `document_template_key` | string | Chave única de identificação do template que gerou o documento. | 36 |
| `required_parties` | array | Lista de partes que assinam o documento em questão. | -- |
| `download_url` | string | URL de download do PDF. | -- |

### Erros Tratáveis

| Código | HTTP | Causa | Como resolver |
|--------|------|-------|---------------|
| ACT000023 | 404 | Contrato de cessão não encontrado para o `assignment_contract_key` informado. | Verificar se o `assignment_contract_key` está correto. |
| ACT000087 | 404 | Documento anexo não encontrado para o `document_key` informado. | Verificar se o `document_key` pertence ao contrato indicado. |

# Enumeradores

### Attached Document Status

| Enumerador              | Descrição           |
| ----------------------- | --------------------- |
| **pending_generate**  | Pendente geração do documento |
| **approved** | Documento gerado |
| **signed**           | Documento assinado |

---

# Manipulação de contrato

URL: /documentation/iaas/homologacao_cedente/contrato_de_cessao/manutencao_do_contrato

---

Dependendo do fluxo, pode ser necessário realizar algumas chamadas para concluir o fluxo de um contrato.

---

# Aprovação do Gestor

---

Caso o contrato seja proposto por uma consultoria, após a geração dos documentos, será necessária a aprovação do gestor, antes que o mesmo sja enviado para assinatura.

### Request

ENDPOINT /assignment_contract/assignment_contract/ASSIGNMENT_CONTRACT_KEY
MÉTODO PUT

```json title='Request Body'
{
    "status": "denied",
    "denial_reason": "Documentação do cedente insuficiente",
}
```

#### Body Params

| Campo | Tipo | Descrição | Caracteres |
|-|-|-|-|
| `status` * | string | Decisão do Gestor. denied ou approved | -- |
| `denial_reason` | string | Descritivo com o motivo da recusa. | 1 a 500 |

*Campos obrigatórios

### Response

STATUS 202

### Erros Tratáveis

| Código | HTTP | Causa | Como resolver |
|--------|------|-------|---------------|
| ACT000023 | 404 | Contrato de cessão não encontrado para o `assignment_contract_key` informado. | Verificar se o `assignment_contract_key` está correto. |
| ACT000025 | 400 | Apenas gestores podem realizar a aprovação ou recusa. | A aprovação/recusa deve ser feita por um agente com `AGENT-TYPE=manager`. |
| ACT000077 | 400 | Status atual do contrato não permite aprovação ou recusa. | Para `approved`: o contrato deve estar em `pending_manager_approval`. Para `denied`: o contrato deve estar em `pending_manager_approval` ou `pending_document`. |

---

# Envio para Assinatura Manual

---

Caso o template configure envio manual para assinatura, é possível agrupar vários contratos, desde que os mesmos tenham o mesmo gestor, cedente e avalistas, para um mesmo lote de assinaturas.

### Request

ENDPOINT /assignment_contract/signature_batch
MÉTODO POST

```json title='Request Body'
{
    "assignment_contract_keys": ["assignment_contract_key", "assignment_contract_key"],
}
```

#### Body Params

| Campo | Tipo | Descrição | Caracteres |
|-|-|-|-|
| `assignment_contract_keys` * | array | Lista de contratos para serem enviados no mesmo lote | -- |

*Campos obrigatórios

### Response

STATUS 202

### Erros Tratáveis

| Código | HTTP | Causa | Como resolver |
|--------|------|-------|---------------|
| ACT000023 | 404 | Contrato de cessão não encontrado para uma das chaves informadas. | Verificar todos os `assignment_contract_keys` enviados no array. |
| ACT000088 | 400 | Status de um contrato não é válido para envio manual. | Todos os contratos do lote devem estar com `status=pending_signature_submission`. |
| ACT000089 | 404 | Contratos do lote possuem partes relacionadas (gestor, cedente, avalistas) diferentes. | Apenas contratos com as mesmas partes relacionadas podem ser agrupados em um mesmo lote de assinaturas. |

---

# Cancelamento de Contrato

---

Em qualquer etapa, menos no caso de um contrato já assinado, é possível cancelar o mesmo. Caso esteja em assinatura, o evento de assinaturas também é cancelado

### Request

ENDPOINT /assignment_contract/assignment_contract/ASSIGNMENT_CONTRACT_KEY
MÉTODO PUT

```json title='Request Body'
{
    "status": "canceled"
}
```

#### Body Params

| Campo | Tipo | Descrição | Caracteres |
|-|-|-|-|
| `status` * | string | canceled | -- |

*Campos obrigatórios

### Response

STATUS 202

### Erros Tratáveis

| Código | HTTP | Causa | Como resolver |
|--------|------|-------|---------------|
| ACT000023 | 404 | Contrato de cessão não encontrado para o `assignment_contract_key` informado. | Verificar se o `assignment_contract_key` está correto. |
| ACT000077 | 400 | Status atual do contrato não permite cancelamento. | Contratos com status `signed` ou `denied` não podem ser cancelados. |

---

# Contrato de Cessão

URL: /documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato

---

Esse processo gera um contrato de cessão entre o Fundo de Investimento e o Cedente e o envia para a assinatura. Para gerar um contrato, é necessário possuir em mãos o fund_class_key do fundo, providenciado pelo time da QI CTVM, assim como um assignment_contract_template_key, também providenciado pelo time, que define os parâmetros do contrato, como coobrigação, documentos obrigatórios de cessão, cláusulas, etc.

Na estrutura do contrato, existem os produtos, que identificam, por exemplo, uma configuração de cessão de um tipo de ativo, de recompra, e assim por diante. Serão enviados para assinatura dois documentos: o contrato propriamente dito, com todas as partes relacionadas envolvidas, como cedente, gestora, avalistas, etc.; e a declaração da gestora, a qual deve ser assinada apenas por esta, atestando que foram cumpridas todas as normas e exigências previstas pela CVM, Anbima e Banco Central quanto à operação do cedente, abrangendo desde a análise de risco até o PLD, entre outras que podem ser consultadas nos respectivos portais.

O fluxo do contrato é variável: é possível configurar o envio dos documentos para assinatura assim que gerados, ou para aguardar um envio manual dos mesmos. Além disso, caso o mesmo seja proposto por um consultor, será necessária a aprovação do gestor, antes que o mesmo seja enviado para assinatura. Por último, caso o cadastro de cedente ainda não tenha sido liberado, ou o mesmo esteja em processo de atualização, será necessário aguardar a conclusão da última análise antes de enviar para assinatura. Caso a análise seja recusada, o contrato também é cancelado.

Após a assinatura de ambos os documentos pelas partes requeridas, os produtos ficam pendentes de ativação, podendo levar alguns minutos para configurar a esteira de cessão, e finalmente, será possível usar a chave da configuração `assignment_configuration_key` de cessão do respectivo produto para realizar a cessão entre o fundo e o cedente.

Opcionalmente, é possível definir avalistas da operação entre o cedente e o fundo, desde que o template de contrato permita tal. Os avalistas devem ser previamente cadastrados junto com o cedente, e apenas indicados no contrato pelo número do documento. Vale ressaltar que as contas de desembolso são definidas no cadastro do cedente.

Todo o fluxo de assinatura do contrato é realizado pela nossa certificadora, CertifiQI, para maior comodidade e facilidade. O acompanhamento das assinaturas e posterior ativação do cedente se dá de forma automática graças a esse recurso.

### Request

ENDPOINT /assignment_contract/assignment_contract
MÉTODO POST

```json title='Request Body'
{
    "fund_class_key": "813ce253-bae5-4448-8d15-04c48d9991b7",
    "assignor_document_number": "18.458.041/0001-91",
    "assignment_contract_template_key": "2555f90a-4c6a-4d65-8bda-5d16f827840c",
    "credit_limit": 1000000,
    "external_id": "Contrato 550",
    "observation": "Contrato referente ao vínculo com coobrigação do cedente",
    "guarantors": [
        {
            "name": "Avalista da operação",
            "document_number": "81.914.413/0001-83"
        }
    ]
}
```

#### Body Params

| Campo | Tipo | Descrição | Caracteres |
|-|-|-|-|
| `fund_class_key` * | string | Chave única de identificação do Fundo. Gerada na criação do Fundo e fornecida pelo time da QI CTVM. | Chave uuid |
| `assignment_contract_template_key` * | string | Chave única de identificação do Template de Contrato. Também fornecida pelo time da QI CTVM. | Chave uuid |
| `assignor_document_number` * | string | Número do documento do cedente. | CPF ou CNPJ |
| `credit_limit` | number | Valor do limite de crédito do contrato. | - |
| `external_id` | string | Identificador externo do contrato. Normalmente o número do contrato. | 1 a 255 |
| `observation` | string | Observação. Campo livre para quaisquer anotações. | 1 a 500 |
| `guarantors` | array | Avalistas da operação. | Ver **[Definição de Avalista](#definição-de-avalista)**. |

*Campos obrigatórios

:::warning Aviso
É muito importante que os avalistas sejam indicados tanto no cadastro do cedente, quanto nessa etapa. Caso seja indicado somente no cadastro, e não no contrato, o avalista não irá assinar o documento. Caso seja indicado apenas no contrato, e não no cadastro, um erro será retornado.
:::

---

### Response

STATUS 201

```json title='Response Body'
{
    "assignment_contract_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "status": "pending_document",
    "products": [
        {
            "product_key": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
            "assignment_configuration_key": "372f0449-4043-4523-9f0f-dff70c65b9c9",
            "product_type": "assignment_term",
            "asset_type": "ccb",
            "status": "pending_contract",
            "required_documents": [
                "ccb"
            ]
        }
    ]
}
```

:::info
É de extrema importância salvar a `assignment_contract_key`, pois a mesma é utilizada para caracterizar as configurações de cessão geradas pelo contrato futuramente, principalmente as originadas pelo fluxo de filiais do tópico 5.2.2.6.. É possível recuperar as configurações geradas seguindo o GET do tópico 5.3.1.2.
:::

### Erros Tratáveis

| Código | HTTP | Causa | Como resolver |
|--------|------|-------|---------------|
| ACT000001 | 404 | Classe de Fundo não encontrada para o `fund_class_key` informado. | Verificar se o `fund_class_key` está correto e pertence ao gestor autenticado. |
| ACT000016 | 404 | Template de contrato não encontrado para o `assignment_contract_template_key` informado. | Verificar se o `assignment_contract_template_key` está correto e vinculado ao `fund_class_key`. |
| ACT000123 | 400 | Template está inativo e não pode ser usado para criar contratos. | Utilizar um template ativo. |
| ACT000065 | 404 | Cedente não cadastrado para o agente proponente. | Verificar se o `assignor_document_number` corresponde a um cedente cadastrado. |
| ACT000096 | 400 | Cedente não possui conta cadastrada. | Cadastrar pelo menos uma conta de desembolso para o cedente antes de propor um contrato (ver [Manutenção de Contas](/documentation/iaas/homologacao_cedente/cadastro/manutencao_de_contas)). |
| ACT000081 | 400 | Avalista não está cadastrado junto ao cedente. | Cada item em `guarantors` deve corresponder a um avalista previamente cadastrado para o cedente, com status `registered` ou `pending_registry`. |
| ACT000095 | 409 | Número de caso (`case_number`) duplicado para este fundo. | Utilizar um `case_number` único dentro do mesmo `fund_class_key`, ou omitir o campo para gerar um automaticamente. |

### Definição de Contrato de Cessão

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `assignment_contract_key` * | string | Chave única de identificação do contrato. | 36 |
| `fund_class` * | object | Objeto fundo | -- |
| `assignor` * | object | Objeto cedente. | -- |
| `consultant` | object | Objeto consultor. Somente quando o consultor for parte do contrato. | -- |
| `assignment_contract_template` * | object | Objeto template de contrato. | -- |
| `attached_documents` * | array | Lista de documentos anexos. | Ver **[Definição de documentos anexos](#definição-de-documento-anexo)**. |
| `products` * | array | Lista de produtos sob o contrato. | Ver **[Definição de documentos anexos](#definição-de-documento-anexo)**. |
| `proposal_agent` * | string | Tipo do agente proponente do contrato. | -- |
| `status` * | string | Status do contrato. | Ver **[Enumeradores de status do contrato de cessão](#assignment-contract-status)**. |
| `credit_limit` | number | Limite de crédito enviado. | -- |
| `external_id` | string | Identificador externo do contrato. Normalmente o número do contrato | 1 a 255 |
| `case_number` | string | Número de caso. Único por fundo | -- |
| `denial_reason` | string | Detalhes da recusa do gestor. | 1 a 255 |
| `observation` | string | Observações enviadas. |  1 a 500 |
| `creation_datetime` | string | Datetime da criação do contrato. | -- |

### Definição de Documento Anexo

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `document_key` * | string | Chave única de identificação do documento. | 36 |
| `document_type` * | string | Tipo do documento. | -- |
| `status` * | string | Status do documento. | Ver **[Enumeradores de status do documento](#attached-document-status)**. |
| `document_template_key` | string | Chave única de identificação do template que gerou o documento | 36 |
| `required_parties` | array | Lista de partes que assinam o documento em questão | -- |

### Definição de Produto

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `product_key` * | string | Chave única de identificação do produto. | 36 |
| `assignment_configuration_key` * | string | Chave única de identificação da Configuração de Cessão. | 36 |
| `asset_type` * | string | Tipo do ativo. | -- |
| `status` * | string | Status do produto. | -- |

### Definição de Avalista

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `name` * | string | Nome do avalista. | 1 a 255 |
| `document_number` * | string | CPF ou CNPJ. | 14 a 18 |

*Campos obrigatórios

:::warning Aviso
Como já indicado, o avalista deve ser previamente cadastrado, junto com o cedente em específico.
:::

# Enumeradores

### Assignment Contract Status

| Enumerador              | Descrição           |
| ----------------------- | --------------------- |
| **pending_document**  | Pendente geração dos documentos |
| **sending_to_signature**   | Em envio para assinatura |
| **pending_signature** | Disponível para assinatura das partes |
| **signed** | Assinado |
| **pending_manager_approval**           | Pendente aprovação do gestor |
| **denied**           | Reprovado na análise do gestor |
| **pending_signature_submission**           | Pendente envio manual para assinatura |
| **pending_assignor_registry_release**           | Pendente liberação do cadastro de cedente vinculado (Em fase de cadastro ou atualização) |
| **canceled**           | Cancelado |

### Attached Document Status

| Enumerador              | Descrição           |
| ----------------------- | --------------------- |
| **pending_generate**  | Pendente geração do documento |
| **approved** | Documento gerado |
| **signed**           | Documento assinado |

---

# Recuperação do Contrato

URL: /documentation/iaas/homologacao_cedente/contrato_de_cessao/recuperacao_de_contrato

---

## Recuperação do Contrato

### Request

ENDPOINT /assignment_contract/assignment_contract/ASSIGNMENT_CONTRACT_KEY
MÉTODO GET

### Response

STATUS 200

```json title='Response Body'
{
      "assignment_contract_key": "UUID",
      "fund_class": {
        "fund_class_key": "UUID",
        "name": "SAMPLE FUND NAME",
        "document_number": "00.000.000/0000-00",
        "manager": {
          "manager_key": "UUID",
          "document_number": "00.000.000/0000-00",
          "manager_name": "SAMPLE MANAGER NAME"
        }
      },
      "assignor": {
        "assignor_key": "UUID",
        "document_number": "00.000.000/0000-00",
        "name": "SAMPLE ASSIGNOR NAME"
      },
      "assignment_contract_template": {
        "assignment_contract_template_key": "UUID",
        "document_template_key": "UUID",
        "name": "NOME DO TEMPLATE",
        "borrower_agreement": null
      },
      "attached_documents": [
        {
          "document_key": "UUID",
          "document_type": "assignment_contract",
          "status": "pending_generate",
          "document_template_key": "UUID",
          "required_parties": ["manager", "assignor", "consultant"]
        }
      ],
      "proposal_agent": "consultant",
      "status": "pending_document",
      "credit_limit": 0.00,
      "external_id": "ID EXTERNO",
      "case_number": "NÚMERO DO PROCESSO",
      "denial_reason": "MOTIVO DA NEGATIVA",
      "creation_datetime": "YYYY-MM-DDTHH:MM:SSZ",
      "products": [
        {
          "product_key": "UUID",
          "assignment_configuration_key": "UUID",
          "asset_type": "ccb | duplicata_mercantil | duplicata_servico",
          "status": "pending_signature | active | canceled",
          "has_coobligation": true,
        }
      ],
      "signature_batch_key": "UUID"
    }
```

### Definição de Contrato de Cessão

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `assignment_contract_key` * | string | Chave única de identificação do contrato. | 36 |
| `fund_class` * | object | Objeto fundo | -- |
| `assignor` * | object | Objeto cedente. | -- |
| `consultant` | object | Objeto consultor. Somente quando o consultor for parte do contrato. | -- |
| `assignment_contract_template` * | object | Objeto template de contrato. | -- |
| `attached_documents` * | array | Lista de documentos anexos. | Ver **[Definição de documentos anexos](#definição-de-documento-anexo)**. |
| `products` * | array | Lista de produtos sob o contrato. | Ver **[Definição de documentos anexos](#definição-de-documento-anexo)**. |
| `proposal_agent` * | string | Tipo do agente proponente do contrato. | -- |
| `status` * | string | Status do contrato. | Ver **[Enumeradores de status do contrato de cessão](#assignment-contract-status)**. |
| `credit_limit` | number | Limite de crédito enviado. | -- |
| `external_id` | string | Identificador externo do contrato. Normalmente o número do contrato | 1 a 255 |
| `case_number` | string | Número de caso. Único por fundo | -- |
| `denial_reason` | string | Detalhes da recusa do gestor. | 1 a 255 |
| `observation` | string | Observações enviadas. |  1 a 500 |
| `signature_batch_key` | string | Identificador do lote de assinaturas. |  36 |
| `creation_datetime` | string | Datetime da criação do contrato. | -- |

### Definição de Documento Anexo

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `document_key` * | string | Chave única de identificação do documento. | 36 |
| `document_type` * | string | Tipo do documento. | -- |
| `status` * | string | Status do documento. | Ver **[Enumeradores de status do documento](#attached-document-status)**. |
| `document_template_key` | string | Chave única de identificação do template que gerou o documento | 36 |
| `required_parties` | array | Lista de partes que assinam o documento em questão | -- |

### Definição de Produto

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `product_key` * | string | Chave única de identificação do produto. | 36 |
| `assignment_configuration_key` * | string | Chave de identificação da configuração de cessão. Necssária na esteira de compra de ativos. | 36 |
| `asset_type` * | string | Tipo do ativo. | -- |
| `status` * | string | Status do produto. | -- |

### Erros Tratáveis

| Código | HTTP | Causa | Como resolver |
|--------|------|-------|---------------|
| ACT000023 | 404 | Contrato de cessão não encontrado para o `assignment_contract_key` informado. | Verificar se o `assignment_contract_key` está correto. |

---
# Listagem de Contratos de Cessão
---

### Request

ENDPOINT /assignment_contract/assignment_contracts
MÉTODO GET

### Query Params

| Parâmetro                   | Descrição                                                                 |
|-----------------------------|---------------------------------------------------------------------------|
| `assignor_document_number`  | Documento do cedente                                                      |
| `fund_class_document_number`| Documento do fundo                                                        |
| `fund_class_key`            | Identificador único do fundo (UUID)                                       |
| `status`                    | Status da cessão                                                          |
| `case_number`                    | Número do caso                                                          |
| `start_date`                    | Data de início                                                          |
| `end_date`                    | Data de fim                                                          |

### Response 
STATUS 200

```json title='Response Body'
{
  "data": [
    {
      "assignment_contract_key": "UUID",
      "fund_class": {
        "fund_class_key": "UUID",
        "name": "SAMPLE FUND NAME",
        "document_number": "00.000.000/0000-00",
        "manager": {
          "manager_key": "UUID",
          "document_number": "00.000.000/0000-00",
          "manager_name": "SAMPLE MANAGER NAME"
        }
      },
      "assignor": {
        "assignor_key": "UUID",
        "document_number": "00.000.000/0000-00",
        "name": "SAMPLE ASSIGNOR NAME"
      },
      "assignment_contract_template": {
        "assignment_contract_template_key": "UUID",
        "document_template_key": "UUID",
        "name": "NOME DO TEMPLATE",
        "borrower_agreement": null
      },
      "attached_documents": [
        {
          "document_key": "UUID",
          "document_type": "assignment_contract",
          "status": "pending_generate",
          "document_template_key": "UUID",
          "required_parties": ["manager", "assignor", "consultant"]
        }
      ],
      "proposal_agent": "consultant",
      "status": "pending_document",
      "credit_limit": 0.00,
      "external_id": "ID EXTERNO",
      "case_number": "NÚMERO DO PROCESSO",
      "denial_reason": "MOTIVO DA NEGATIVA",
      "creation_datetime": "YYYY-MM-DDTHH:MM:SSZ",
      "products": [
        {
          "product_key": "UUID",
          "assignment_configuration_key": "UUID",
          "asset_type": "ccb | duplicata_mercantil | duplicata_servico",
          "status": "pending_signature | active | canceled",
          "has_coobligation": true,
        }
      ],
      "signature_batch_key": "UUID"
    }
  ],
  "limit": 10,
  "page": 0,
  "is_last_page": true
}
```

# Enumeradores

### Assignment Contract Status

| Enumerador              | Descrição           |
| ----------------------- | --------------------- |
| **pending_document**  | Pendente geração dos documentos |
| **sending_to_signature**   | Em envio para assinatura |
| **pending_signature** | Disponível para assinatura das partes |
| **signed** | Assinado |
| **pending_manager_approval**           | Pendente aprovação do gestor |
| **denied**           | Reprovado na análise do gestor |
| **pending_signature_submission**           | Pendente envio manual para assinatura |
| **pending_assignor_registry_release**           | Pendente liberação do cadastro de cedente vinculado (Em proceso de cadastro ou atualização) |
| **canceled**           | Cancelado |

### Attached Document Status

| Enumerador              | Descrição           |
| ----------------------- | --------------------- |
| **pending_generate**  | Pendente geração do documento |
| **approved** | Documento gerado |
| **signed**           | Documento assinado |

---

# Webhooks do Contrato

URL: /documentation/iaas/homologacao_cedente/contrato_de_cessao/webhooks_contrato

---

#### Pendente Aprovação do Gestor

STATUS pending manager approval

```json title='Webhook Body'
{
    "data":{
        "assignment_contract_key": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "external_id": "Contrato número 550",
        "status": "pending_manager_approval"
    },
    "webhook_type":"assignment_contract.assignment_contract_status_change",
    "webhook_datetime":"2025-01-22T20:30:23.459Z"
}
```

#### Pendente Envio para Assinatura

STATUS pending signature submission

```json title='Webhook Body'
{
    "data":{
        "assignment_contract_key": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "external_id": "Contrato número 550",
        "status": "pending_signature_submission"
    },
    "webhook_type":"assignment_contract.assignment_contract_status_change",
    "webhook_datetime":"2025-01-22T20:30:23.459Z"
}
```

#### Pendente Liberação do Cadastro do Cedente

STATUS pending assignor registry release

```json title='Webhook Body'
{
    "data":{
        "assignment_contract_key": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "external_id": "Contrato número 550",
        "status": "pending_assignor_registry_release"
    },
    "webhook_type":"assignment_contract.assignment_contract_status_change",
    "webhook_datetime":"2025-01-22T20:30:23.459Z"
}
```

#### Recusado pelo Gestor

STATUS denied

```json title='Webhook Body'
{
    "data":{
        "assignment_contract_key": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "external_id": "Contrato número 550",
        "status": "denied"
    },
    "webhook_type":"assignment_contract.assignment_contract_status_change",
    "webhook_datetime":"2025-01-22T20:30:23.459Z"
}
```

#### Contrato Enviado para Assinatura

STATUS pending signature

```json title='Webhook Body'
{
    "data":{
        "assignment_contract_key": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "external_id": "Contrato número 550",
        "status": "pending_signature"
    },
    "webhook_type":"assignment_contract.assignment_contract_status_change",
    "webhook_datetime":"2025-01-22T20:30:23.459Z"
}
```

#### Assinado

STATUS signed

```json title='Webhook Body'
{
    "data":{
        "assignment_contract_key": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "external_id": "Contrato número 550",
        "status": "signed"
    },
    "webhook_type":"assignment_contract.assignment_contract_status_change",
    "webhook_datetime":"2025-01-22T20:30:23.459Z"
}
```

#### Contrato Cancelado

STATUS canceled

```json title='Webhook Body'
{
    "data":{
        "assignment_contract_key": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "external_id": "Contrato número 550",
        "status": "canceled"
    },
    "webhook_type":"assignment_contract.assignment_contract_status_change",
    "webhook_datetime":"2025-01-22T20:30:23.459Z"
}
```

# Webhooks do Produto

---
#### Produto Ativado

STATUS active

```json title='Webhook Body'
{
    "data":{
        "product_key": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
        "assignment_configuration_key": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
        "status": "active"
    },
    "webhook_type":"assignment_contract.product_status_change",
    "webhook_datetime":"2025-01-22T20:30:23.459Z"
}
```

#### Produto Em Ativação

STATUS pending_create_assignment_configuration

```json title='Webhook Body'
{
    "data":{
        "product_key": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
        "assignment_configuration_key": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
        "status": "pending_create_assignment_configuration"
    },
    "webhook_type":"assignment_contract.product_status_change",
    "webhook_datetime":"2025-01-22T20:30:23.459Z"
}
```

---

# Webhooks do Produto

URL: /documentation/iaas/homologacao_cedente/contrato_de_cessao/webhooks_produto

---

#### Produto Ativado

STATUS Active

```json title='Webhook Body'
{
    "product_key": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
    "assignment_configuration_key": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
    "status": "active"
}
```

---

# Introdução

URL: /documentation/iaas/homologacao_cedente/inicio

A parte de cadastro de Cedente é essencial para o início da operação de qualquer fundo que compre direitos creditórios. Nessa seção iremos explicar todo o fluxo, desde o envio das primeiras informações, até a abertura da Esteira de Cessão para envio de Ativos.

Para ter acesso aos serviços discutidos nas próximas sessões, entre em contato com o time [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br), para que seja feito as devidas liberações, tanto em ambiente de Homologação (Sandbox) quanto em ambiente de produção.

É importante mencionar que para a efetiva liberação de um Cedente, deve-se consumir dois diferentes sistemas:

1. O cadastro do Cedente em nossa base, realizado uma única vez;

2. Formalização de um Contrato de Cessão, entre o Cedente e o Fundo;

Para ambos os sistemas, tanto o gestor quanto o consultor podem atuar como agentes, propondo cadastros e contratos entre os cedentes e os fundos de acordo com o desenvolver da operação.

### Cadastro do Cedente

Nessa etapa, deve-se enviar todas as informações tanto do Cedente quanto dos seus representantes e beneficiários finais. Uma vez feito o envio, o Cedente nasce Pendente Registro, é gerada uma primeira análise e deve-se enviar a documentação necessária, validando o cadastro. Por fim, após anexar todos os documentos necessários deve-se comandar o disparo da Análise, ou seja, o envio da Análise para validação, a qual passará por um processo de anti-fraude e PLD.

Alguns documentos são necessários para a análise realizada, no caso de uma pessoa jurídica, o contrato social, com a última atualização disponível, certidão simplificada da Junta Comercial, e a ata de eleição da diretoria vigente. Além disso, devem ser enviados os documentos dos beneficiários finais da empresa, para fins de combate à lavagem de dinheiro, corrupção e financiamento ao terrorismo. Para cedentes pessoa física, apenas o documento de identificação é suficiente para a análise. 

Em ambos os casos, é necessário um termo de responsabilidade do agente de cadastro, afirmando que realizou todo o levante de documentos, como comprovantes de faturamento, compliance, entre outros, propostos pela norma da CVM e da AMBIMA.

Assim que esta primeira Análise for aprovada, o cadastro passará por uma etapa de validação interna, onde uma equipe validará as informações recebidas e dará seguimento ao mesmo, após a validação dos assinantes. Assim que efetivado, o cedente estará disponível para as próximas operações. Nesse momento, caso configurado, enviamos um Webhook notificando que a Análise foi aprovada, mas também é possível acompanhar os cedentes cadastrados pelo portal do gestor.

:::warning Análises paradas por 1 mês são canceladas automaticamente
Uma Análise que fica **1 mês sem movimentação** é cancelada automaticamente, passando para o status `canceled`. Na prática isso atinge as análises que permanecem em `pending_documents` — aquelas em que a documentação nunca foi anexada, ou em que o [Disparo da Análise](/documentation/iaas/homologacao_cedente/cadastro/disparo_da_analise) nunca foi comandado.

O cancelamento é **terminal**: a análise cancelada não volta atrás e não aceita novos documentos nem disparo. Para retomar o cadastro, gere uma nova análise por meio da [Atualização de Cadastro](/documentation/iaas/homologacao_cedente/cadastro/atualizacao_de_cadastro).

A mudança dispara o webhook `assignor_registry.analysis_status_change` com `analysis_status: canceled` — veja [Webhooks de Análise](/documentation/iaas/homologacao_cedente/cadastro/webhooks_analise).
:::

### Atualização de Cedente

Em caso de necessidade de atualização cadastral, deve-se enviar novamente todas as informações do Cedente com as modificações desejadas. Após envio, é gerada uma nova Análise em que é necessário anexar a documentação necessária para garantirmos a validade da atualização. Por fim, após anexar todos os documentos necessários deve-se comandar o disparo da Análise, ou seja, o envio da nova Análise para validação.

Vale ressaltar que os documentos que devem ser enviados, são apenas os das entidades que foram alteradas, seja a adição de um novo representante, ou alteração de algum dado cadastral da companhia.

Assim que esta nova Análise for aprovada, os novos dados cadastrais do Cedente são efetivamente alterados. Nesse momento, caso configurado, enviamos um Webhook notificando que a Análise foi aprovada. Note que, uma atualização cadastral de um Cedente não gera impedimento em realizar novas operações com ele.

### Formalização de Contrato de Cessão

Para formalizar a relação entre o Cedente e o Fundo, é necessário a assinatura de um Contrato de Cessão, que rege essa venda de ativos. Nós disponibilizamos uma API que viabiliza esse processo de maneira automática.

O processo envolve o pedido de formalização, a partir de um template, que irá disparar internamente a criação do contrato e envio para assinatura. Uma vez com o contrato assinado, os produtos definidos pelo template ficam disponíveis para ativação. Assim o cliente escolhe qual produto quer ativar, e indica a conta de desembolso. Será retornada, através da ativação do Produto, a chave da Configuração de Cessão gerada, identificador que será utilizado posteriormente no processo de compra e venda de ativos.

---

# Integração via SFTP

URL: /documentation/iaas/integracao_sftp/inicio

O SFTP (Secure File Transfer Protocol) é o canal pelo qual a QI CTVM disponibiliza os relatórios dos fundos para download . Os modelos disponíveis, o layout coluna a coluna de cada arquivo e os exemplos para download estão na [documentação de Relatórios DTVM](/documentation/iaas/relatorios_dtvm/).

Para a integração, recomendamos bibliotecas e clientes que implementem o protocolo, como o `paramiko` em Python, o `sftp` da linha de comando ou qualquer cliente SFTP padrão.

:::info Liberação de acesso
Para solicitar o acesso, entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br). A liberação é feita primeiro no ambiente de Homologação (Sandbox) e depois em Produção.
:::

## Como funciona a autenticação

O acesso é autenticado por **chave pública SSH** — não há senha. Você gera o par de chaves, mantém a chave privada sob o seu controle e nos envia apenas a chave pública, que cadastramos no seu usuário do SFTP.

| Quem            | O que fornece                                                                    |
| --------------- | -------------------------------------------------------------------------------- |
| **Você**        | A chave pública (arquivo `.pub`), no formato OpenSSH                              |
| **A QI CTVM**   | `HOSTNAME`, `PORT` (22) e `USERNAME`, além do <em>fingerprint</em> do host        |

:::danger Nunca envie a sua chave privada
Nenhum time da QI Tech vai pedir a sua chave privada. Se alguém pedir — por e-mail, por chamado ou por qualquer outro canal —, não somos nós. O compartilhamento no 1Password descrito no passo 3 é apenas para a chave **pública** (`sftp_qitech.pub`).

Se a chave privada já foi enviada a alguém ou anexada em algum lugar, considere-a comprometida: gere um par novo e nos envie a nova chave pública.
:::

## 1. Gerando o par de chaves

Gere um par **dedicado ao SFTP**. Não reutilize a chave que assina os seus tokens JWT: são credenciais de sistemas diferentes, com ciclos de vida diferentes — rotacionar uma passaria a obrigar a rotação da outra, e um vazamento em um dos lados atingiria os dois.

Troque `nome-da-empresa` pelo nome da sua empresa — por exemplo, `sftp-acme`. Esse texto é apenas um comentário dentro da chave, e serve para nos ajudar a identificá-la.

**Linux / macOS**

```bash
mkdir -p ~/.ssh && chmod 700 ~/.ssh
ssh-keygen -t ed25519 -C "sftp-nome-da-empresa" -f ~/.ssh/sftp_qitech
```

**Windows (PowerShell)**

```powershell
New-Item -ItemType Directory -Force "$env:USERPROFILE\.ssh" | Out-Null
ssh-keygen -t ed25519 -C "sftp-nome-da-empresa" -f "$env:USERPROFILE\.ssh\sftp_qitech"
```

**Windows (cmd)**

```batch
if not exist "%USERPROFILE%\.ssh" mkdir "%USERPROFILE%\.ssh"
ssh-keygen -t ed25519 -C "sftp-nome-da-empresa" -f "%USERPROFILE%\.ssh\sftp_qitech"
```

**Windows (WSL)**

```bash
mkdir -p ~/.ssh && chmod 700 ~/.ssh
ssh-keygen -t ed25519 -C "sftp-nome-da-empresa" -f ~/.ssh/sftp_qitech
```

Dentro do WSL, use o caminho do Linux (`~/.ssh`). A chave fica no sistema de arquivos do WSL, e não na pasta do usuário do Windows.

:::caution Copie o comando da aba correspondente
Cada aba escreve o caminho da pasta na forma que aquele programa entende, então os comandos não são intercambiáveis. Se você rodar o comando de uma aba em outro programa, aparece `No such file or directory` e nenhuma chave é criada — nesse caso, é só voltar e copiar o comando da aba certa.

No Windows, se você não sabe qual usar, use o **PowerShell**: é o que abre por padrão no Terminal do Windows.
:::

O comando pergunta por uma passphrase e gera dois arquivos:

| Arquivo            | O que é                                                     |
| ------------------ | ----------------------------------------------------------- |
| `sftp_qitech`      | **Chave privada.** Nunca envie e nunca compartilhe.         |
| `sftp_qitech.pub`  | **Chave pública.** É esta que você deve nos enviar.         |

Sobre a passphrase :

- **Integração automatizada** (um serviço seu baixando os relatórios): deixe em branco, apertando Enter nas duas perguntas, e proteja a chave privada onde ela for armazenada, em um gerenciador de segredos com acesso restrito. Uma passphrase que precisa ficar disponível para o processo em tempo de execução não acrescenta proteção real.
- **Uso por uma pessoa**: defina uma passphrase .

O `ssh-keygen` já cria a chave privada com permissão restrita ao seu usuário. Se você copiar o arquivo para outra máquina, restaure a permissão — clientes SSH recusam chaves privadas legíveis por outros usuários:

```bash
chmod 600 ~/.ssh/sftp_qitech
```

## 2. Conferindo o formato da chave pública

O conteúdo do arquivo `.pub` é **uma única linha**, começando pelo tipo da chave e terminando no comentário:

```
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIE1wA3uBEFYG+Yi7zIw7/YUJJ4fBB0MUZsvUVaqyyv6M sftp-acme
```

Confira o arquivo antes de nos enviar:

```bash
ssh-keygen -lf ~/.ssh/sftp_qitech.pub
```

A resposta esperada é o fingerprint da chave, no formato `256 SHA256:... sftp-acme (ED25519)`. Se o comando responder `is not a public key file`, o arquivo está corrompido ou não é uma chave pública OpenSSH.

### Se a sua chave está no formato PEM/X.509

Uma chave que começa com `-----BEGIN PUBLIC KEY-----` está no formato PEM/X.509, o padrão do OpenSSL. Esse formato **não pode ser cadastrado no SFTP**: o servidor espera o formato OpenSSH, de uma única linha.

Se essa chave já é dedicada ao SFTP, você não precisa gerar outra — basta convertê-la:

- **Você ainda tem a chave privada correspondente.** Vale para qualquer tipo de chave:

  ```bash
  ssh-keygen -y -f caminho/para/chave_privada
  ```

- **Você só tem a chave pública em PEM.** Vale para chaves RSA:

  ```bash
  ssh-keygen -i -m PKCS8 -f caminho/para/chave_publica.pem
  ```

Os dois comandos imprimem a chave no formato OpenSSH na saída padrão. A conversão não preserva o comentário original; se quiser, acrescente `sftp-nome-da-empresa` ao final da linha.

## 3. Enviando a chave pública

Envie a chave pública pelo **1Password**, compartilhando o item com o time de integração. É por esse canal que recebemos as chaves: ele preserva o conteúdo exatamente como você o gerou e deixa a origem do envio verificável — quem conseguisse substituir a sua chave pública no caminho passaria a ter acesso ao seu diretório no SFTP.

1. No 1Password, crie um item e cole nele o conteúdo do arquivo `sftp_qitech.pub` **como texto puro, em uma única linha, sem quebras**.
2. Acrescente o fingerprint da chave — a saída do `ssh-keygen -lf` do passo anterior. Comparamos com o fingerprint da chave que recebemos e confirmamos que ela não foi alterada no caminho.
3. Compartilhe o item com o time de integração e avise em [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) que o compartilhamento foi feito.

:::caution Não anexe a chave em `.docx` nem em `.pdf`
A formatação automática desses programas substitui caracteres (um `+` por um travessão, aspas retas por tipográficas) e insere quebras de linha. Qualquer uma dessas alterações invalida a chave, e o erro só aparece na hora da conexão.
:::

Com a chave pública cadastrada, confirmamos a liberação e enviamos o `HOSTNAME`, o `USERNAME` e o fingerprint do host.

## 4. Conectando ao SFTP

### Confira o host key na primeira conexão

Na primeira conexão, o seu cliente vai perguntar se você confia no servidor. Não aceite sem conferir: compare o fingerprint apresentado com o que o time de integração enviou. É essa comparação que impede que outro servidor se passe pelo nosso.

```bash
ssh-keyscan -t ed25519 <hostname> > qitech_host_key
ssh-keygen -lf qitech_host_key          # compare com o fingerprint enviado pela QI CTVM
cat qitech_host_key >> ~/.ssh/known_hosts
```

Depois de conferido, o `known_hosts` passa a ser a referência do cliente e conexões com outro host key são recusadas automaticamente.

### Credenciais da conexão

| Credencial          | Origem                                        |
| ------------------- | --------------------------------------------- |
| `HOSTNAME`          | Endereço do servidor, informado pela QI CTVM  |
| `PORT`              | 22                                            |
| `USERNAME`          | Usuário, informado pela QI CTVM               |
| **Chave privada**   | O arquivo `sftp_qitech` que você gerou        |

:::caution Atenção
Essas credenciais dão acesso direto aos relatórios do seu fundo e não devem ser compartilhadas.
:::

### Exemplo de código

**Python**

```python
import paramiko

HOSTNAME = "sftp.exemplo.com"                # informado pela QI CTVM
PORT = 22
USERNAME = "usuario"                         # informado pela QI CTVM
PRIVATE_KEY = "/caminho/para/sftp_qitech"    # a chave privada que você gerou
KNOWN_HOSTS = "/caminho/para/known_hosts"    # com o host key da QI CTVM já conferido

client = paramiko.SSHClient()
client.load_host_keys(KNOWN_HOSTS)

# Recusa a conexão se o host key não for o esperado.
# Não use AutoAddPolicy: ela aceita qualquer servidor sem verificação.
client.set_missing_host_key_policy(paramiko.RejectPolicy())

client.connect(
    hostname=HOSTNAME,
    port=PORT,
    username=USERNAME,
    key_filename=PRIVATE_KEY,  # o paramiko identifica o tipo da chave pelo arquivo
    look_for_keys=False,
    allow_agent=False,
    timeout=30,
)

try:
    with client.open_sftp() as sftp:
        # Lista os arquivos disponíveis
        for name in sftp.listdir("/"):
            print(name)

        # Faz o download de um arquivo
        sftp.get("caminho/remoto/arquivo.csv", "caminho/local/arquivo.csv")
finally:
    client.close()
```

## 5. Baixando os arquivos

Os arquivos são nomeados a partir do nome resumido do fundo , do modelo do relatório e da data de referência no formato YYYY-MM-DD:

- `example_name_assets_wallet_composition_2026-07-29.csv`

Os modelos disponíveis, o layout coluna a coluna de cada arquivo e os exemplos para download estão na [documentação de Relatórios DTVM](/documentation/iaas/relatorios_dtvm/).

:::info Informação
O SFTP de relatórios descrito nesta página é exclusivamente para download de arquivos; não é permitido realizar upload .
:::

## Rotação e revogação da chave

Para trocar a chave, gere um par novo e nos envie a nova chave pública pelo 1Password, seguindo os passos 1 a 3. Cadastramos a nova chave e informamos quando a anterior for removida — assim a troca acontece sem janela de indisponibilidade.

Se houver suspeita de comprometimento da chave privada, avise o time de integração no mesmo contato: revogamos o acesso da chave antiga imediatamente, antes de cadastrar a nova.

---

# Recebimento de Webhooks

URL: /documentation/iaas/introducao/autenticacao_webhooks

A assinatura dos Webhooks utiliza-se de uma estratégia de criptografia com chaves simétricas, ou seja, tanto a QI CTVM quanto o Parceiro integrador compartilham de uma mesma chave. Ao realizarmos uma configuração de Webhooks, iremos gerar uma Signature Key e disponibiliza-lá. Toda requisição originada no sistema da QI, irá carregar um header SIGNATURE que será um JWT assinado com essa chave. O encoding é realizado com o algoritmo HS256.

Abaixo temos um exemplo em python de como realizar o decoding da assinatura:
```python
from jose import jwt

signature_key = "CHAVE UNICA DISPONIBILIZADA PELO TIME QI"

signature_token = headers["SIGNATURE"]

decoded_token = jwt.decode(signature_token, key=signature_key, algorithms=["HS256"])
print(decoded_token)
```

## O que a assinatura carrega

O JWT decodificado traz quatro campos:

| Campo | Descrição |
|-------|-----------|
| `timestamp` | Data e hora da assinatura, em UTC, no formato `AAAA-MM-DDTHH:MM:SS`. |
| `method` | Método HTTP da requisição — sempre `POST`. |
| `uri` | A URL de destino configurada para o seu webhook. |
| `payload_md5` | Hash MD5 do corpo da requisição. |

:::tip Use o `payload_md5` para validar integridade
Calcular o MD5 do corpo recebido e comparar com `payload_md5` confirma que o payload não foi alterado em trânsito. Como o hash é calculado sobre o corpo serializado, compare os bytes recebidos — não o resultado de um *re-encode* do JSON depois de parsear.
:::

Além do `SIGNATURE`, as requisições levam o header **`AGENT-KEY`**, com o identificador do agente (classe de fundo, investidor ou gestor) a que a notificação se refere. Ele é útil para rotear a notificação quando a sua integração atende mais de um fundo pela mesma URL.

## Tentativas de entrega

Consideramos a entrega bem-sucedida quando a sua aplicação responde com um status de sucesso. Em caso de falha — resposta de erro ou erro de rede — a notificação volta para a fila e é retentada.

São feitas **até 5 tentativas** por notificação. Esgotadas as tentativas, ela é marcada como falha e não é mais retentada automaticamente.

:::info Notificação que não chegou
Uma notificação que falhou nas 5 tentativas pode ser reenviada pela QI CTVM — entre em contato com o time de integração informando o período e o tipo de evento. O reenvio não é uma operação disponível na sua integração.
:::

:::warning Trate o recebimento como idempotente
Uma tentativa pode ter chegado à sua aplicação e a resposta ter se perdido, o que faz a notificação ser retentada. Sua aplicação precisa tolerar receber a mesma notificação mais de uma vez — use as chaves do payload para reconhecer o que já foi processado.
:::

## Validação de origem

Sugerimos que, além de comparar a assinatura, o parceiro integrador valide o nosso IP, dado que todas as nossas requisições são originadas de um mesmo IP, conforme o ambiente:

|Ambiente|IP            |
|--------|--------------|
|Produção|54.205.166.229|
|Sandbox |52.72.221.4   |

:::danger Atenção!
Os webhooks da QI CTVM não devem ser mapeados de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

---

# Introdução

URL: /documentation/iaas/introducao/inicio

A QI CTVM é uma instituição financeira que presta os serviços de Administração e Custódia de Fundos de Investimento. Nós temos uma série de serviços, utilizando REST APIs que viabilizam uma nova experiência em toda a operação, visando facilidades, automações e uma total transparência para os envolvidos.

Essa documentação tem como objetivo descrever os fluxos, endpoints e estruturas de dados necessárias para operar quaisquer Fundos de Investimentos.

Obs.: Em caso de dúvidas em qualquer etapa do processo favor entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) detalhando seu problema/dúvida que te auxiliaremos.

## Perfis de Acesso

No nosso sistema nós reconhecemos o usuário pelo perfil que ele assume dentro da estrutura da QI CTVM. Possuímos 5 principais perfis:
1. Gestores;
2. Originadores;
3. Cedentes;
4. Investidores;
5. Distribuidores;

Cada um desses perfis possui um Endpoint específico para a sua integração, com as devidas rotas disponibilizadas;

Para criarmos um Perfil de Acesso para utilização das nossas APIs é necessário que se entre em contato com nosso time através do e-mail [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br).

Gestoras e consultorias solicitam apenas o **nome, e-mail e CPF** do usuário master responsável e, a partir daí, criam a integração e cadastram a chave pública pelo próprio portal — sem enviar chaves por e-mail. Veja [Integração pelo portal](/documentation/iaas/introducao/integracao_via_portal).

## Ambientes (Hosts)

A QI CTVM possui dois ambientes, SANDBOX e PRODUÇÃO. Ambos os ambientes possuem código e comportamento completamente idênticos, porém, o ambiente de SANDBOX apresenta valores monetários totalmente fictícios, e o ambiente de Produção realiza transações financeiras válidas.

O ambiente Sandbox foi criado para os desenvolvedores realizarem suas integrações, e quando estiverem prontos para entrada em produção, atualizarem apenas as variáveis de ambiente com os parâmetros de Produção.

| Perfil         | Ambiente | Host                                           |
|----------------|----------|------------------------------------------------|
| Gestores       | Sandbox  | https://manager-api.sandbox.qidtvm.com.br/     |
| Originadores   | Sandbox  | https://originator-api.sandbox.qidtvm.com.br/  |
| Cedentes       | Sandbox  | https://assignor-api.sandbox.qidtvm.com.br/    |
| Investidores   | Sandbox  | https://investor-api.sandbox.qidtvm.com.br/    |
| Distribuidores | sandbox  | https://distributor-api.sandbox.qidtvm.com.br/ |
| Consultores    | sandbox  | https://consultant-api.sandbox.qidtvm.com.br/  |
| Gestores       | Produção | https://manager-api.qidtvm.com.br/             |
| Cedentes       | Produção | https://assignor-api.qidtvm.com.br/            |
| Originadores   | Produção | https://originator-api.qidtvm.com.br/          |
| Investidores   | Produção | https://investor-api.qidtvm.com.br/            |
| Distribuidores | Produção | https://distributor-api.qidtvm.com.br/         |
| Consultores    | Produção | https://consultant-api.qidtvm.com.br/          |
| Público        | Produção | https://api.qidtvm.com.br/                     |

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.  
:::

---

# Integração pelo portal

URL: /documentation/iaas/introducao/integracao_via_portal

Gestoras e consultorias criam a própria integração de API pelo portal: criam a integração, cadastram a chave pública e recebem ali mesmo a API Key. Nenhuma chave trafega por e-mail.

:::tip Este é o caminho padrão
Cadastrar a chave pública pela tela é o procedimento recomendado para gestoras e consultorias, em sandbox e em produção. O envio da chave pública por e-mail é tratado como exceção — veja [Quando o envio por e-mail ainda é usado](#quando-o-envio-por-e-mail-ainda-e-usado).

Pelo portal a chave é cadastrada pelo próprio responsável, com confirmação explícita e fingerprint visível na tela. Isso elimina o repasse manual de arquivos entre caixas de e-mail, reduz o risco de a chave errada ser cadastrada e permite a troca da chave a qualquer momento, sem abrir chamado.
:::

## Visão geral do fluxo

| Etapa | Quem faz | Onde |
| ----- | -------- | ---- |
| 1. Cadastro do usuário master | Time de integração da QI Tech | A partir do contato por e-mail ou WhatsApp |
| 2. Acesso ao portal | Usuário master | Portal do Gestor ou Portal do Consultor |
| 3. Criação dos demais usuários e permissões | Usuário master | Portal, em **Gestão de Acesso > Usuários** |
| 4. Criação da integração | Usuário master ou usuário com permissão | Portal, em **Gestão de Acesso > Integração API** |
| 5. Cadastro da chave pública | Usuário com permissão | Portal, na tela da integração |
| 6. Liberação das permissões da integração | Time de integração da QI Tech | Aparece na própria tela quando concluída |
| 7. Configuração de webhooks (opcional) | Usuário com permissão | Portal, na tela da integração |

## 1. Solicitar o cadastro do usuário master

Entre em contato com o time de integração da QI Tech por e-mail ([integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br)) ou WhatsApp informando, do responsável pela homologação:

- **Nome completo**
- **E-mail corporativo**
- **CPF**

Com esses dados criamos o **usuário master** da gestora ou da consultoria no ambiente solicitado. Esse usuário é o ponto de partida: é ele quem cria os demais usuários, concede permissões e cria as integrações de API.

:::danger Não envie chaves por e-mail
A solicitação contém apenas nome, e-mail e CPF do responsável. **Não envie a chave pública nessa mensagem** — ela é cadastrada por você mesmo no portal, na etapa 5. E a chave privada nunca é enviada a ninguém, em nenhuma hipótese: a QI Tech jamais pedirá que você a compartilhe.
:::

## 2. Acessar o portal

| Perfil | Ambiente | Portal |
| ------ | -------- | ------ |
| Gestora | Sandbox | https://portal-do-gestor.sandbox.fundos.qitech.com.br/ |
| Gestora | Produção | https://portal-do-gestor.fundos.qitech.com.br/ |
| Consultoria | Sandbox | https://portal-do-consultor.sandbox.fundos.qitech.com.br/ |
| Consultoria | Produção | https://portal-do-consultor.fundos.qitech.com.br/ |

O acesso é feito por login único (SSO) com o e-mail cadastrado na etapa anterior.

## 3. Criar os demais usuários e conceder permissões

Somente o usuário master (ou quem ele autorizar) enxerga a tela de integração. Para dar acesso a outras pessoas do time:

1. Acesse **Gestão de Acesso > Usuários** e clique em **Criar usuário**.
2. Informe **Nome**, **Sobrenome**, **E-mail** e **CPF**.
3. Abra o usuário criado e conceda a permissão de integração:
   - Gestora: **Gerenciar Integração API** (`manager.manage_integration`)
   - Consultoria: **Gerenciar integração com a API** (`consultant.manage_integration`)

Sem essa permissão o item **Integração API** não aparece no menu.

## 4. Criar a integração

Em **Gestão de Acesso > Integração API**, clique em **Criar integração** e informe um nome que identifique o uso (por exemplo, `ETL noturno` ou `Backoffice`).

Ao confirmar, a QI Tech gera as credenciais da integração e a tela de detalhe é aberta:

| Credencial | Para que serve |
| ---------- | -------------- |
| **API Key** | Vai no header `API-CLIENT-KEY` de todas as requisições. Veja [Teste de autenticação](/documentation/iaas/introducao/teste_de_autenticacao). |
| **Client Integration Key** | Identificador da integração. Use para referenciá-la em contatos com o time de integração. |

Uma mesma gestora ou consultoria pode manter **várias integrações ativas ao mesmo tempo**, cada uma com sua própria chave pública — útil para separar sistemas ou ambientes internos.

A integração nasce com status **Criada**. Ela só passa a **Ativa** depois que a chave pública é cadastrada.

## 5. Cadastrar a chave pública

Na tela da integração, clique em **Cadastrar chave pública**. Há duas formas de fazer isso.

### Opção A — Gerar o par de chaves no navegador

O portal gera o par direto no seu navegador e baixa a chave privada para a sua máquina. **A chave privada nunca é enviada à QI Tech**: só a chave pública é transmitida.

1. Escolha o **Algoritmo da chave**.
2. Clique em **Gerar par de chaves**. O download da chave privada começa automaticamente.
3. Guarde a chave privada em local seguro — ela não é exibida novamente e não pode ser recuperada. Se necessário, use **Baixar chave privada** e **Baixar chave pública** antes de sair da tela.
4. A chave pública já vem preenchida no formulário. Confirme para cadastrá-la.

Cada algoritmo determina o `alg` que você deve usar ao assinar o JWT das requisições:

| Algoritmo no portal | Assinatura do JWT |
| ------------------- | ----------------- |
| RSA 2048 (recomendado) | `RS256` |
| RSA 4096 | `RS256` |
| EC P-256 | `ES256` |
| EC P-384 | `ES384` |
| EC P-521 | `ES512` |

### Opção B — Enviar a sua própria chave pública

Se você já gerou o par fora do portal — veja [Troca de chaves](/documentation/iaas/introducao/troca_de_chaves) — envie apenas a chave pública:

- **Arraste o arquivo** para a área indicada, ou clique para selecioná-lo (`.pem`, `.pub`, `.key`, `.crt` ou `.txt`); ou
- **Cole o conteúdo** do PEM no campo de texto.

O portal identifica o algoritmo da chave e informa, abaixo do campo, com qual `alg` você deve assinar suas requisições.

### Requisitos e recusas

A chave precisa estar em PEM, no bloco `-----BEGIN PUBLIC KEY-----`. O portal recusa o cadastro nos casos abaixo:

| Situação | Motivo |
| -------- | ------ |
| Conteúdo de chave privada (`BEGIN ... PRIVATE KEY`) | A chave privada nunca deve ser enviada |
| Certificado (`BEGIN CERTIFICATE`) | Não é uma chave pública |
| Chave no formato OpenSSH (`ssh-rsa`, `ecdsa-sha2-...`) | Converta para PEM |
| RSA com menos de 2048 bits | Abaixo do mínimo aceito |
| PEM ilegível | Conteúdo corrompido ou incompleto |

Para confirmar, digite `CADASTRAR` no campo de confirmação. **O cadastro é imediato**: a integração passa a usar essa chave assim que você confirma.

Concluído o cadastro, a tela exibe o **Fingerprint (SHA-256)** da chave e a data do cadastro. Use o fingerprint para conferir que a chave cadastrada é mesmo a sua.

## 6. Liberação das permissões da integração

:::info Apenas para gestoras
Consultorias não passam por esta etapa: a autorização é feita pelas permissões de fundo da consultoria, e a integração já fica pronta para uso depois do cadastro da chave.
:::

Para gestoras, o último passo é a liberação das permissões de **Leitura** e **Escrita** da integração, feita pelo time de integração da QI Tech. Não é preciso aguardar na tela — o status aparece em **Permissões** quando a liberação for concluída.

## 7. Configurar webhooks (opcional)

Ainda na tela da integração, o bloco **Webhooks** permite cadastrar a URL de destino das notificações. Os sistemas disponíveis são:

| Sistema | Eventos |
| ------- | ------- |
| Cadastro de cedentes | Análises, registro de cedentes e apontamentos |
| Contratos de cessão | Status de contratos de cessão e produtos |
| Recebíveis | Cessões e ativos da esteira de recebíveis |
| Liquidação | Lotes de pagamento e liquidações |

Você pode usar a mesma URL para todos os sistemas ou uma URL por sistema. Cada sistema gera uma **chave de assinatura (HMAC)** própria, usada para validar as entregas recebidas — veja [Recebimento de Webhooks](/documentation/iaas/introducao/autenticacao_webhooks).

:::caution Webhooks são configurados por agente
A configuração de webhooks vale para a gestora ou consultoria como um todo, não por integração. Se houver mais de uma integração de API, todas compartilham a mesma configuração.
:::

## Trocar a chave pública

A qualquer momento, na tela da integração, use **Trocar chave** e repita a etapa 5. Confirme digitando `TROCAR`.

:::danger A troca é imediata
A chave anterior é invalidada na hora. Requisições assinadas com ela passam a falhar assim que a nova chave é cadastrada. Faça a troca em uma janela em que você possa atualizar a chave privada usada pela sua aplicação.
:::

## Desativar e reativar a integração

**Desativar integração** (confirmando com `DESATIVAR`) faz com que toda chamada feita com aquela credencial passe a ser recusada. Nada é apagado: chave pública, permissões e webhooks continuam salvos e voltam a valer ao reativar.

Use a desativação como resposta imediata a uma suspeita de vazamento da chave privada; em seguida, gere um novo par e cadastre a nova chave pública antes de reativar.

## Entrada em produção

O procedimento em produção é o mesmo. Envie por e-mail ao time de integração o **nome, e-mail e CPF do usuário master** da gestora ou da consultoria no ambiente de produção. A partir do acesso desse usuário master, a criação dos demais usuários, a concessão de permissões e a criação das integrações de API são feitas por você, pelo portal — sem novo contato com o time.

As credenciais de sandbox não valem em produção: cada ambiente tem suas próprias integrações, chaves e API Keys.

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.
:::

## Quando o envio por e-mail ainda é usado

O cadastro pelo portal está disponível para **gestoras** e **consultorias**. Os demais perfis de acesso — cedentes, originadores, investidores e distribuidores — continuam enviando a chave pública ao time de integração, conforme descrito em [Troca de chaves](/documentation/iaas/introducao/troca_de_chaves).

Se você é gestora ou consultoria e ainda não tem acesso ao portal, solicite o usuário master pela etapa 1 em vez de enviar a chave por e-mail.

---

# Pacote de Endpoints

URL: /documentation/iaas/introducao/pacote_endpoints

Para facilitar a experiência de integração com o ecossistema da QI Tech , disponibilizamos um pacote completo contendo todos os endpoints possíveis, já organizado em uma estrutura de pastas.

Nosso objetivo é tornar o processo de integração mais ágil, claro e padronizado — reduzindo o esforço inicial e garantindo que você tenha acesso imediato a todos os recursos necessários durante a implementação.

Esse pacote centraliza:

- A lista completa dos endpoints disponíveis para cada produto;

- Estrutura organizada por temas, seguindo a documentação;

Um ponto único de referência, evitando consultas fragmentadas ou perda de informações importantes.

Ao disponibilizarmos essa pasta, buscamos garantir que parceiros integradores tenham um caminho mais simples, rápido e estruturado para iniciar suas implementações com a QI Tech, reforçando nosso compromisso com clareza, segurança e eficiência técnica.

### [📦 Baixar pacote Python completo](/downloads/integracao_python_iaas.zip)

---

# Endpoints de teste

URL: /documentation/iaas/introducao/teste_de_autenticacao/endpoints_de_teste

## Método GET

### Request

ENDPOINT /authentication_test
MÉTODO GET

### Response

STATUS 200

Response Body

```json
{
  "success": "Congrats!"
}
```

## Metodo POST

### Request

ENDPOINT /authentication_test
MÉTODO POST

Request Body

```json
{
  "name": "QI Tech"
}
```

### Response

STATUS 200

Response Body

```json
{
  "name": "QI Tech",
  "success": "Congrats!"
}

```

---

# Teste de autenticação

URL: /documentation/iaas/introducao/teste_de_autenticacao/

### 1. Introdução

Nessa seção iremos explicar como deve funcionar a requisição para que possa ser aceita pelo nosso sistema. Em primeiro Lugar deve-se colocar no header API-CLIENT-KEY a Api Key fornecida pelo time da QI CTVM. Depois deve-se criar um Header de AUTHORIZATION assinando com a Chave Privada do parceiro integrador; 

Abaixo iremos ensinar o passo a passo utilizando de Python para exemplificar o processo de criação da AUTHORIZATION.

### 2. Importar bibliotecas
Neste exemplo em python estamos usando 5 bibliotecas para poder realizar o processo de autenticação.

```python
from datetime import datetime
import json
from jose import jwt
from hashlib import md5
import requests
```

### 3. Inserir a chave privada e a chave de integração
```python title="Dados da criptografia"
api_key = "\<API KEY FORNECIDA PELA QI\>"

client_private_key = '''-----BEGIN EC PRIVATE KEY-----
MIHbAgEBBEH7OuewosJfz4zKF+Gm0ogJxhb8G6LSMDVQQbFYz335mHCx9/Pr6Yk+
yYwsVozeXhlry3/vnUn1zCasU+4O+yseZ6AHBgUrgQQAI6GBiQOBhgAEAa46fN/2
8vI64shRhu9erMA6JLl3zHFX8gFHQrbb0g4IDfjXCKMCILiwdtL8QecstsgepTa7
yo1pTXOVNDbmLX2TAK38xb2Gv6OC+PA+5drF2wWajWbVLpR2R7mYEzr5HNIAJYHb
5C1jvM2ItK2R22HAbYfH25nsvGhkCGbrRNWQVF9g
-----END EC PRIVATE KEY-----'''

```

### 4. Definir variáveis
Definir as variáveis método, endpoint e conteúdo particular a cada requisição (neste exemplo, utilizaremos o método "POST" para o endpoint "/authentication_test")
```python title="Dados da requisição"
base_url = "https://assignor-api.qidtvm.com.br"
today_str = datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S")
method = "POST"
endpoint = "/authentication_test"
body = {"name": "QI Tech"}
```

:::caution **Atenção**
O campo `uri` da assinatura deve ser **idêntico** ao caminho enviado na requisição. Se o endpoint receber parâmetros na *query string*, eles também fazem parte da URI assinada — veja [Requisições com query string](#query-string).
:::

### 5. Construir Dicionário Base de Assinatura
```python title="Dicionário base"

dict_to_sign = {"timestamp": today_str, "method": method, "uri": endpoint}

```

#### 5.1. Se necessário, adicionar o conteúdo
Para as requisições que tenham _body_, deve-se adicionar o md5 do bytes desse conteúdo. Como todas as requisições no nosso sistema são através de JSON, pode-se usar o seguinte:

```python title="Dicionário base"
body_bytes = json.dumps(body).encode()

md5_instance = md5()
md5_instance.update(body_bytes)
md5_body = md5_instance.hexdigest()

dict_to_sign["payload_md5"] = md5_body
```

### 6. Realizar criptografia do header
Realizar criptografia utilizando biblioteca JWT (neste exemplo de código, utilizamos jsonwebtoken como jwt em javascript)

```python
jwt_headers = {"alg": "ES512", "typ": "JWT"}
encoded_header_token = jwt.encode(
    claims=dict_to_sign,
    key=client_private_key,
    algorithm="ES512",
    headers=jwt_headers,
)
```

### 7. Montando o header final

```python
headers = {"API-CLIENT-KEY": api_key, "AUTHORIZATION": encoded_header_token}
```

```python title="Definindo url final"
url = f"{base_url}{endpoint}"
```

### Realizando requisição

```python
resp = requests.post(url=url, headers=headers, json=body)
print(resp.json())
```

## Requisições com query string {#query-string}

Endpoints paginados ou com filtros recebem parâmetros na *query string* — por exemplo `?page=0&limit=20`. Nesses casos, a *query string* **faz parte da URI assinada**.

O campo `uri` deve ser igual ao caminho enviado na requisição: mesmos parâmetros, na mesma ordem e com a mesma codificação. Se a URI assinada e a URI enviada não forem iguais, a requisição é recusada com status `401`:

```json title="Resposta"
{
  "title": "Invalid endpoint",
  "description": "Invalid endpoint.",
  "translation": "O endpoint e invalido",
  "code": "MIT000015"
}
```

### Exemplo

```python title="GET com paginação"
base_url = "https://manager-api.qidtvm.com.br"
path = "/quota/fund_class/{fund_class_key}/investor_positions"
query_string = "page=0&limit=20"

# a query string faz parte da uri assinada
uri = f"{path}?{query_string}"

method = "GET"
today_str = datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S")

dict_to_sign = {"timestamp": today_str, "method": method, "uri": uri}

jwt_headers = {"alg": "ES512", "typ": "JWT"}
encoded_header_token = jwt.encode(
    claims=dict_to_sign,
    key=client_private_key,
    algorithm="ES512",
    headers=jwt_headers,
)

headers = {"API-CLIENT-KEY": api_key, "AUTHORIZATION": encoded_header_token}

resp = requests.get(url=f"{base_url}{uri}", headers=headers)
print(resp.json())
```

### Recomendações

- Monte a *query string* e envie a URL completa. Evite usar o argumento `params` do `requests` junto com uma URI já assinada: o cliente HTTP pode reordenar ou recodificar os parâmetros e invalidar a assinatura.
- Requisições `GET` normalmente não têm corpo. Nesse caso, não envie *body* nem o campo `payload_md5`.
- Valores com caracteres especiais (pontuação de documentos, datas, espaços) devem ser assinados já no formato final em que serão enviados na URL.

---

# Troca de Chaves

URL: /documentation/iaas/introducao/troca_de_chaves

## 1. Requisição Assinada

Todas as requisições em nossas APIs devem usar o protocolo **HTTPs**, utilizando **TLS 1.2 ou 1.3**, contendo dois Headers:

1. API-CLIENT-KEY: Uma chave disponibilizada pelo nosso time de Integração que identifica uma integração específica;
2. AUTHORIZATION: Uma assinatura da requisição que deve ser realizada conforme explicado nesse manual;

Como padrão a QI CTVM utiliza-se do padrão de chaves assimétricas, onde existem duas chaves diferentes, uma para assinatura, denominada chave privada , e uma para leitura, denominada de chave pública . Com a chave privada, o parceiro integrador deverá realizar a assinatura utilizando-se do padrão JWT.
O parceiro integrador é responsável por gerar o par e fornecer à QI CTVM a chave pública para que possamos validar as suas requisições.

:::caution **Atenção**
 A chave privada é de uso exclusivo do parceiro integrador, e deve ser armazenada com segurança. A QI CTVM nunca irá pedir, em hipótese alguma, que voce a compartilhe conosco.
:::

## 2. Como entregar a chave pública

:::tip Gestoras e consultorias: cadastre pelo portal
Se você é uma **gestora** ou uma **consultoria**, o caminho recomendado é cadastrar a chave pública você mesmo, pela tela do Portal do Gestor ou do Portal do Consultor. Veja o guia completo em **[Integração pelo portal](/documentation/iaas/introducao/integracao_via_portal)**.

Pelo portal você cria a integração, cadastra a chave pública e recebe a API Key na própria tela — nenhuma chave trafega por e-mail. O cadastro é imediato, o fingerprint da chave fica visível para conferência e a troca pode ser feita a qualquer momento, sem abrir chamado. É o procedimento padrão tanto em sandbox quanto em produção.

Para começar, envie ao time de integração o **nome, e-mail e CPF** do usuário master responsável pela homologação — e **apenas isso**. A chave pública não deve ser anexada a essa solicitação.
:::

Os demais perfis de acesso — **cedentes, originadores, investidores e distribuidores** — continuam enviando a chave pública gerada ao time de integração da QI Tech, em [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br), e aguardando a configuração da integração.

## 3. Gerando o par

Você pode gerar o par de chaves pelo próprio portal, no momento do cadastro — a chave privada é gerada no seu navegador e baixada apenas para você (veja [Integração pelo portal](/documentation/iaas/introducao/integracao_via_portal)) — ou gerá-lo localmente pelo terminal.

Para gerar uma chave privada em um computador UNIX faça:

```bash
$ ssh-keygen -t ecdsa -b 521 -m PEM -f private.key
```

E a partir desta chave privada gere sua chave pública.

```bash
$ openssl ec -in private.key -pubout -outform PEM -out public.key.pub
```

A chave pública é o arquivo `public.key.pub`. É esse — e somente esse — arquivo que deve ser cadastrado no portal ou enviado ao time de integração.

# Vídeo explicativo

---

# Início

URL: /documentation/iaas/investidor/cadastro_investidor/inicio

Esta seção descreve o processo geral de **cadastro de investidores** na plataforma QI Tech. O cadastro é o passo inicial obrigatório antes que qualquer investidor possa participar de uma oferta, subscrever cotas ou movimentar recursos. Ao final do fluxo, a QI Tech executa uma **análise cadastral** que valida os dados, documentos e enquadramento do investidor frente às exigências regulatórias.

### Como o cadastro está estruturado

O cadastro de investidor é dividido em três fluxos, organizados de acordo com o canal pelo qual o investidor será integrado. Cada fluxo é descrito em detalhes em sua respectiva subseção.

Carteira Administrada
carteiras geridas profissionalmente em nome de um titular econômico (investor owner) `investor-integration`
Distribuição Externa
investidores cadastrados por conta e ordem por meio de distribuidores parceiros `distributor-integration`
Cadastrar como Gestor / Consultor
gestores (`manager-integration`) e consultores (`consultant-integration`) cadastram seus cotistas — **pessoa física, pessoa jurídica ou classe de fundo de investimento**

:::info Classes de fundo de investimento
O cadastro de **classes de fundo** (FIMs, FIAs, FIDCs e demais) faz parte do fluxo **Cadastrar como Gestor / Consultor** — é lá que estão todas as etapas, já com as diferenças de PF, PJ e fundo indicadas em cada página. Apenas a **gestora** ou a **administradora** da classe pode realizar esse cadastro.
:::

### Conceitos comuns a todos os fluxos

Apesar das particularidades de cada tipo, todos os fluxos compartilham um conjunto de conceitos e recursos:

- **Investor / Investor Analysis** — cada investidor possui um identificador único (`investor_key`) e, a cada ciclo de cadastro, uma nova análise cadastral (`investor_analysis_key`). É a análise que recebe os dados, documentos e o resultado final da validação.
- **Feedbacks** — durante e após a análise, a QI Tech pode solicitar correções ou complementos por meio de feedbacks, que ficam disponíveis na própria análise cadastral.
- **Etapas cadastrais** — os fluxos cadastrais seguem linearmente os seguintes passos:
  - Criação do investidor (primeiro cadastro) ou análise (atualização) - **Cliente**;
  - Envio de dados cadastrais e documentos necessários - **Cliente**;
  - Envio do cadastro para análise - **Cliente**;
  - Aprovação do cadastro ou retorno para preenchimento com feedbacks - **QI Tech**;
  - Assinatura de documentos - **Cliente**.

Uma vez que o cliente assinar os documentos enviados após a análise, o investidor estará apto a interagir com o resto do sistema, como geração de termos de adesão, boletins de subscrição e boletagem de aportes.

---

# atualizacao_cadastral

URL: /documentation/iaas/investidor/cadastro/atualizacao_cadastral



---

# atualizar_status_grupo_assinantes

URL: /documentation/iaas/investidor/cadastro/atualizar_status_grupo_assinantes



---

# busca_informacoes_de_uma_analise_cadastral_do_investidor

URL: /documentation/iaas/investidor/cadastro/busca_informacoes_de_uma_analise_cadastral_do_investidor



---

# busca_informacoes_do_investidor

URL: /documentation/iaas/investidor/cadastro/busca_informacoes_do_investidor



---

# buscar_documentos_para_assinatura

URL: /documentation/iaas/investidor/cadastro/buscar_documentos_para_assinatura



---

# Buscar Dados de investidores paginado

URL: /documentation/iaas/investidor/cadastro/buscar_investidores_paginado

---

### Introdução
Este recurso permite listar investidores aplicando filtros opcionais (documento, status e nome), com paginação.

### Input / Output

Não há corpo de requisição. Os filtros são passados via *query string*, todos opcionais.

Como ***output*** será retornada a lista de investidores que atendem aos filtros informados.

### Request

ENDPOINT `/investor_registry/investors`
MÉTODO `GET`
STATUS `200`

### Query Params

Todos os parâmetros são **opcionais**.

| Param             | Tipo   | Default | Descrição                                                    |
|-------------------|--------|:-------:|--------------------------------------------------------------|
| `document_number` | string | `None`  | Filtro por documento completo                                |
| `status`          | string | `None`  | Filtro por status                                            |
| `name`            | string | `None`  | Filtro por nome                                              |
| `limit`           | int    | `100`   | Itens por página (mín. `0`, máx. `500`)                      |
| `page`            | int    | `0`     | Página; o offset é calculado como `page * limit`             |

### Response

```json title='Response Body'
{
    "data": [
        {
            "name": "investidor 1",
            "status": "approved",
            "person_type": "natural_person",
            "investor_key": "UUID v4",
            "email": "investidor1@exemplo.com",
            "phone": "11999990001",
            "distributor": {
                "distributor_key": "UUID v4",
                "name": "Distribuidora XYZ",
                "document_number": "00000000000191",
                "registry_configuration": {}
            }
        },
        {
            "name": "investidor 2",
            "status": "pending",
            "person_type": "natural_person",
            "investor_key": "UUID v4",
            "email": "investidor2@exemplo.com",
            "phone": "11999990002",
            "distributor": {
                "distributor_key": "UUID v4",
                "name": "Distribuidora XYZ",
                "document_number": "00000000000191",
                "registry_configuration": {}
            }
        }
    ],
    "limit": 50,
    "page": 0,
    "is_last_page": true
}
```

### Response Params

| Campo          | Tipo    | Descrição                                                          |
|----------------|---------|--------------------------------------------------------------------|
| `data`         | array   | Lista de objetos de **[Investor](#investor)**                      |
| `limit`        | int     | Quantidade de itens por página utilizada na consulta               |
| `page`         | int     | Página retornada                                                   |
| `is_last_page` | boolean | Indica se esta é a última página de resultados                     |

### Investor {#investor}

| Campo           | Tipo   | Descrição                                          |
|-----------------|--------|----------------------------------------------------|
| `investor_key`  | string | Chave única de identificação do investidor         |
| `name`          | string | Nome (ou razão social) do investidor               |
| `status`        | string | Status atual do investidor                         |
| `person_type`   | string | Tipo de pessoa (`natural_person` ou `legal_person`) |
| `email`         | string | E-mail de contato do investidor                    |
| `phone`         | string | Telefone de contato do investidor                  |
| `distributor`   | object | Objeto de **Distributor**                          |

### Distributor {#distributor}

| Campo                    | Tipo   | Descrição                                        |
|--------------------------|--------|--------------------------------------------------|
| `distributor_key`        | string | Chave única do distribuidor                      |
| `name`                   | string | Nome do distribuidor                             |
| `document_number`        | string | CNPJ do distribuidor                             |
| `registry_configuration` | object | Configurações de cadastro do distribuidor        |

---

# ciclo_de_vida_da_analise

URL: /documentation/iaas/investidor/cadastro/ciclo_de_vida_da_analise



---

# consultar_analise_em_andamento

URL: /documentation/iaas/investidor/cadastro/consultar_analise_em_andamento



---

# atualizar_status_conta_bancaria

URL: /documentation/iaas/investidor/cadastro/contas_bancarias/atualizar_status_conta_bancaria



---

# definir_conta_principal

URL: /documentation/iaas/investidor/cadastro/contas_bancarias/definir_conta_principal



---

# enviar_contas_bancarias

URL: /documentation/iaas/investidor/cadastro/contas_bancarias/enviar_contas_bancarias



---

# Criar investidor

URL: /documentation/iaas/investidor/cadastro/criar_investidor

---

### Introdução
Este recurso tem como objetivo nos informar dados básicos para iniciar o cadastro de um **investidor**.

A criação de um investidor já dispara, em conjunto, a abertura de uma primeira **análise cadastral** vinculada a ele. Por isso, ao final desta chamada são retornadas duas chaves: ***investor_key*** (identifica o investidor) e ***investor_analysis_key*** (identifica a análise cadastral em andamento).

O campo **`person_type`** define se o investidor é **pessoa física** (`natural_person`) ou **pessoa jurídica** (`legal_person`). Dentro de pessoa jurídica, o campo **`investor_sub_type`** distingue uma empresa comum (`default`) de uma **classe de fundo de investimento** (`fund_class`), que segue regras próprias ao longo de todo o fluxo.

:::info Informação
No ambiente de Homologação, temos a seguinte regra para aprovações: CPF/CNPJ com início **1**: reprovação automática; CPF/CNPJ com início **8**: pendente de validação manual; o restante é aprovado automaticamente.
:::

:::info Informação
Para a integração de `gestores` ou `consultores` é possível determinar se o investidor irá preencher os dados através da plataforma, ou não. Caso o investidor vá preencher o próprio cadastro, basta passar o query param `create_investor_user = true`
:::

### Input / Output

Como ***input*** envie os dados básicos do investidor. Os campos obrigatórios variam de acordo com **`person_type`** e **`investor_sub_type`**.

Como ***output*** serão retornadas a ***investor_key*** e a ***investor_analysis_key***. A ***investor_key*** identifica o investidor; a ***investor_analysis_key*** identifica a análise cadastral aberta junto com a criação. Um mesmo investidor pode possuir mais de uma análise cadastral ao longo do tempo (renovações, atualizações).

### Request

ENDPOINT `/investor_registry/investor`
MÉTODO `POST`
STATUS `201`

### Request body

Caso 01: Pessoa Física

```json title='Request Body'
{
    "name": "João da Silva",
    "document_number": "123.456.789-00",
    "person_type": "natural_person",
    "email": "joao.silva@example.com",
    "phone": {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "987654321"
    }
}
```

Caso 02: Pessoa Jurídica

```json title='Request Body'
{
    "name": "Empresa XPTO Ltda",
    "document_number": "12.345.678/0001-90",
    "person_type": "legal_person",
    "investor_sub_type": "default",
    "registry_user": {
        "name": "José da Silva",
        "document_number": "123.456.789-00",
        "email": "jose.silva@example.com",
        "phone": {
            "international_dial_code": "55",
            "area_code": "11",
            "number": "987654321"
        }
    }
}
```

Caso 03: Classe de Fundo de Investimento ( fund_class )

```json title='Request Body'
{
    "name": "Fundo XPTO Multimercado",
    "document_number": "12.345.678/0001-90",
    "person_type": "legal_person",
    "investor_sub_type": "fund_class"
}
```

:::warning Atenção
Os campos obrigatórios mudam de acordo com o **`person_type`** e o **`investor_sub_type`**:

- **`natural_person`**: `name`, `document_number`, `person_type` (`email` e `phone` recomendados para criação de usuário)
- **`legal_person`** / `default`: `name`, `document_number`, `person_type`, `investor_sub_type` e `registry_user`
- **`legal_person`** / `fund_class`: `name`, `document_number`, `person_type` e `investor_sub_type` — **sem `registry_user`**, já que a representação é feita pelos *investor owners* (administrador e gestora)
:::

:::warning Classes de fundo: só o gestor ou o administrador cadastra
Apenas a **gestora** ou a **administradora** do fundo pode criar um investidor `fund_class`, e somente se o seu próprio cadastro estiver atualizado. Veja **[Introdução](./introducao)** para o detalhamento dessa exigência.
:::

:::warning Apenas classes em funcionamento
Somente classes **operacionais** na CVM podem ser cadastradas. Classes pré-operacionais, encerradas, canceladas ou incorporadas são recusadas na análise. Se o CNPJ não constar na base da CVM, o `submit` é recusado com `IVR000068`.
:::

:::info O que a CVM preenche por você
Para `fund_class`, parte dos dados cadastrais é preenchida **automaticamente** a partir da base pública da CVM no momento do envio para análise — incluindo razão social, data de constituição, patrimônio e os vínculos com administrador, gestora e (quando aplicável) investidor exclusivo.

Como consequência, **endereço, patrimônio, suitability, grupos de assinantes e documentos do investidor não são enviados** para esse subtipo. Consulte **[Quais etapas se aplicam a cada tipo](./introducao#etapas-por-tipo)**.
:::

:::info Sobre o `registry_user`
O **`registry_user`** representa o usuário (pessoa física) responsável por preencher os dados cadastrais do investidor. Para **pessoa física**, normalmente este usuário é o próprio investidor e o campo pode ser omitido. Para **pessoa jurídica**, é o representante que responderá pelo preenchimento.
:::

### Body params
| Campo                       | Tipo     | Descrição                                                                                   | Caracteres   | Obrigatório |
|-----------------------------|----------|---------------------------------------------------------------------------------------------|--------------|-------------|
| `name`                      | string   | Nome (ou razão social) do investidor                                                        |   1 - 255    |    Sim      |
| `person_type`               | string   | Enumerador de **[Person Type](#person-type)**                                               |      -       |    Sim      |
| `document_number`           | string   | CPF (`XXX.XXX.XXX-XX`) ou CNPJ (`XX.XXX.XXX/XXXX-XX`). Para `fund_class`, o CNPJ da classe registrada na CVM |   14 ou 18   |    Sim*     |
| `investor_sub_type`         | string   | Enumerador de **[Investor Sub Type](#investor-sub-type)**                                   |      -       |    Não      |
| `email`                     | string   | E-mail do investidor                                                                        |   1 - 255    |    Não      |
| `phone`                     | object   | Objeto de **[Phone](#phone)**                                                               |      -       |    Não      |
| `registry_user`             | object   | Objeto de **[Registry User](#registry-user)**                                               |      -       |    Não      |

### Phone
| Campo                       | Tipo     | Descrição                                                                                   | Caracteres   | Obrigatório |
|-----------------------------|----------|---------------------------------------------------------------------------------------------|--------------|-------------|
| `international_dial_code`   | string   | Código internacional (ex.: `55`)                                                            |   1 - 3      |    Sim      |
| `area_code`                 | string   | DDD                                                                                         |      2       |    Sim      |
| `number`                    | string   | Número do telefone                                                                          |   8 - 9      |    Sim      |

### Registry User
| Campo               | Tipo     | Descrição                                            | Caracteres   | Obrigatório |
|---------------------|----------|------------------------------------------------------|--------------|-------------|
| `name`              | string   | Nome do usuário cadastrador                          |   1 - 255    |    Sim      |
| `document_number`   | string   | CPF do usuário (formato `XXX.XXX.XXX-XX`)            |     14       |    Sim      |
| `email`             | string   | E-mail do usuário                                    |   1 - 255    |    Sim      |
| `phone`             | object   | Objeto de **[Phone](#phone)**                        |      -       |    Sim      |

### Person Type {#person-type}
| Enumerador          | Descrição                                            |
|---------------------|------------------------------------------------------|
| `natural_person`    | Pessoa física                                        |
| `legal_person`      | Pessoa jurídica                                      |

### Investor Sub Type {#investor-sub-type}
| Enumerador               | Descrição                                                                                  |
|--------------------------|--------------------------------------------------------------------------------------------|
| `default`                | Pessoa jurídica regular (default quando o campo não é informado)                           |
| `fund_class`             | Classe de fundo de investimento — dispara o enriquecimento automático com os dados públicos da CVM e segue regras próprias de etapas, partes relacionadas e investor owners |

### Response
```json title='Response Body'
{
    "investor_key": "UUID",
    "investor_analysis_key": "UUID"
}
```

---

# definir_grupo_assinantes_padrao

URL: /documentation/iaas/investidor/cadastro/definir_grupo_assinantes_padrao



---

# enviar_cadastro_para_analise

URL: /documentation/iaas/investidor/cadastro/enviar_cadastro_para_analise



---

# enviar_dados_cadastrais

URL: /documentation/iaas/investidor/cadastro/enviar_dados_cadastrais



---

# enviar_endereco

URL: /documentation/iaas/investidor/cadastro/enviar_endereco



---

# enviar_grupos_assinantes

URL: /documentation/iaas/investidor/cadastro/enviar_grupos_assinantes



---

# enviar_investor_document

URL: /documentation/iaas/investidor/cadastro/enviar_investor_document



---

# enviar_patrimonio

URL: /documentation/iaas/investidor/cadastro/enviar_patrimonio



---

# consultar_feedback

URL: /documentation/iaas/investidor/cadastro/feedback/consultar_feedback



---

# enviar_mensagem_feedback

URL: /documentation/iaas/investidor/cadastro/feedback/enviar_mensagem_feedback



---

# listar_feedbacks

URL: /documentation/iaas/investidor/cadastro/feedback/listar_feedbacks



---

# Introdução

URL: /documentation/iaas/investidor/cadastro/introducao

Esta seção reúne os cadastros feitos por um gestor (`manager-integration`) ou consultor (`consultant-integration`) em nome de seus cotistas, cobrindo os **três tipos de investidor** que essa integração pode cadastrar:

| Tipo | `person_type` / `investor_sub_type` | O que é |
|------|--------------------------------------|---------|
| **Pessoa Física (PF)** | `natural_person` | Investidor pessoa física |
| **Pessoa Jurídica (PJ)** | `legal_person` + `investor_sub_type: default` | Empresa investidora — inclui `financial_institution` |
| **Fundo de Investimento** | `legal_person` + `investor_sub_type: fund_class` | Classe de fundo com CNPJ próprio (FIMs, FIAs, FIDCs e demais), que aplica recursos em nome de seus cotistas |

O cadastro contempla o envio de dados cadastrais, endereço, patrimônio, contas bancárias, suitability, grupos de assinantes, documentos, partes relacionadas e, quando aplicável, *investor owner*, até o disparo da análise cadastral pela QI Tech. **As etapas exigidas variam conforme o tipo** — cada página adiante indica o que se aplica a PF, a PJ e a fundo.

Importante ressaltar que, para PF e PJ, a assinatura é sempre executada exclusivamente pelo investidor ou representante legal identificado durante a análise.

:::warning Fundos: só o gestor ou o administrador cadastra
O cadastro de uma classe de fundo **só pode ser feito pela gestora ou pela administradora** do próprio fundo. Não há outro papel autorizado a abrir esse cadastro.

Além disso, **o cadastro de quem cadastra precisa estar em dia**: apenas gestoras e administradoras com o próprio cadastro atualizado conseguem cadastrar classes de fundo. Essa manutenção é feita pela mesma API — a gestora ou administradora atualiza o próprio cadastro por **[Atualização Cadastral](./atualizacao_cadastral)** e, na sequência, mantém as suas classes de fundo enquanto investidores.
:::

:::warning Apenas classes de fundo em funcionamento
Somente classes **em funcionamento (operacionais)** na CVM podem ser cadastradas. Classes em fase pré-operacional, encerradas, canceladas, incorporadas ou de qualquer forma não operacionais são recusadas na análise.

O enquadramento é lido da base pública da CVM a partir do CNPJ informado na criação do investidor. Se o CNPJ não constar na base da CVM, o campo fica indefinido e o `submit` é recusado com `IVR000068` — em Homologação, utilize um CNPJ de classe efetivamente registrada e em funcionamento.
:::

### Fluxo de Cadastro

1. Criar Investidor
criação inicial do investidor e abertura da primeira análise cadastral
↓
2. Enviar Dados Cadastrais
PF, PJ e fundo — dados específicos da pessoa física ou jurídica
↓
3. Enviar Endereço
PF e PJ — informações de endereço. Fundo: etapa pulada
↓
4. Enviar Patrimônio
PF e PJ — patrimônio e enquadramento. Fundo: etapa pulada
↓
5. Enviar Contas Bancárias
PF, PJ e fundo — contas para movimentação
↓
6. Enviar Suitability
PF e PJ — questionário de adequação ao perfil. Fundo: etapa pulada
↓
7. Enviar Grupos de Assinantes
PF e PJ — quem deve assinar os documentos. Fundo: etapa pulada
↓
8. Enviar Documentos do Investidor
PF e PJ — upload dos documentos obrigatórios. Fundo: etapa pulada
↓
9. Criar Partes Relacionadas
PJ — sócios, diretores, beneficiários finais. Fundo: só se for exclusivo na CVM
↓
10. Enviar Documentos das Partes Relacionadas
documentos de cada parte relacionada. Fundo: só se for exclusivo na CVM
↓
11. Enviar para Análise
submissão da análise cadastral para validação
↓
12. Assinar Documentos
assinatura dos documentos gerados após aprovação

### Quais etapas se aplicam a cada tipo {#etapas-por-tipo}

| Etapa | PF | PJ | Classe de fundo |
|-------|:--:|:--:|:----------------|
| 1. Criar Investidor | ✅ | ✅ | ✅ |
| 2. Enviar Dados Cadastrais | ✅ | ✅ | ✅ *(razão social, data de constituição e patrimônio vêm da CVM)* |
| 3. Enviar Endereço | ✅ | ✅ | ⏭️ **pulado** |
| 4. Enviar Patrimônio | ✅ | ✅ | ⏭️ **pulado** |
| 5. Enviar Contas Bancárias | ✅ | ✅ | ✅ |
| 6. Enviar Suitability | ✅ | ✅ *(obrigatório em `retail`)* | ⏭️ **pulado** |
| 7. Enviar Grupos de Assinantes | ✅ | ✅ | ⏭️ **pulado** |
| 8. Enviar Documentos do Investidor | ✅ | ✅ | ⏭️ **pulado** |
| 9. Criar Partes Relacionadas | opcional | ✅ obrigatório | ⚠️ **só se exclusivo** |
| 10. Documentos das Partes Relacionadas | opcional | ✅ obrigatório | ⚠️ **só se exclusivo** |
| 11. Enviar para Análise | ✅ | ✅ | ✅ |
| 12. Assinar Documentos | ✅ | ✅ | ✅ |

:::info O que uma classe de fundo **não** envia
Endereço, patrimônio, suitability, grupos de assinantes e documentos do investidor **não fazem parte do cadastro de uma classe de fundo** — nenhum deles é exigido no `submit`, e as etapas correspondentes podem ser puladas por completo.

Os dados que sustentam a análise vêm de outra fonte: razão social, data de constituição, patrimônio e os vínculos com **administrador** e **gestora** são preenchidos automaticamente a partir da base pública da CVM no envio para análise. A representação do fundo se dá por esses *investor owners*, e não por representantes legais.
:::

:::warning Partes relacionadas: apenas em classe exclusiva
Partes relacionadas e seus documentos são exigidos **quando, e somente quando, a classe é exclusiva na CVM**. Nesse caso é obrigatória ao menos uma parte relacionada do tipo `exclusive_investor`, e a participação somada precisa fechar **exatamente 100%**.

Para uma classe **não exclusiva**, pule as etapas 9 e 10 — nenhuma parte relacionada é necessária. O caráter exclusivo (`exclusive_fund_class`) é derivado automaticamente da classe CVM na criação do investidor; consulte **[Criar Parte Relacionada — Exigências por tipo de investidor](./related_party/criar_parte_relacionada#exigencias)** para a matriz completa.
:::

Nas subseções a seguir veremos cada uma das etapas necessárias para concluir esses cadastros, com as diferenças de PF, PJ e classe de fundo indicadas em cada página.

---

# atualizar_parte_relacionada

URL: /documentation/iaas/investidor/cadastro/related_party/atualizar_parte_relacionada



---

# atualizar_status_parte_relacionada

URL: /documentation/iaas/investidor/cadastro/related_party/atualizar_status_parte_relacionada



---

# criar_parte_relacionada

URL: /documentation/iaas/investidor/cadastro/related_party/criar_parte_relacionada



---

# enviar_documento_parte_relacionada

URL: /documentation/iaas/investidor/cadastro/related_party/enviar_documento_parte_relacionada



---

# consultar_formulario_suitability

URL: /documentation/iaas/investidor/cadastro/suitability/consultar_formulario_suitability



---

# enviar_suitability

URL: /documentation/iaas/investidor/cadastro/suitability/enviar_suitability



---

# atualizacao_cadastral

URL: /documentation/iaas/investidor/carteira_administrada/atualizacao_cadastral



---

# atualizar_status_grupo_assinantes

URL: /documentation/iaas/investidor/carteira_administrada/atualizar_status_grupo_assinantes



---

# busca_informacoes_de_uma_analise_cadastral_do_investidor

URL: /documentation/iaas/investidor/carteira_administrada/busca_informacoes_de_uma_analise_cadastral_do_investidor



---

# busca_informacoes_do_investidor

URL: /documentation/iaas/investidor/carteira_administrada/busca_informacoes_do_investidor



---

# buscar_documentos_para_assinatura

URL: /documentation/iaas/investidor/carteira_administrada/buscar_documentos_para_assinatura



---

# ciclo_de_vida_da_analise

URL: /documentation/iaas/investidor/carteira_administrada/ciclo_de_vida_da_analise



---

# consultar_analise_em_andamento

URL: /documentation/iaas/investidor/carteira_administrada/consultar_analise_em_andamento



---

# atualizar_status_conta_bancaria

URL: /documentation/iaas/investidor/carteira_administrada/contas_bancarias/atualizar_status_conta_bancaria



---

# definir_conta_principal

URL: /documentation/iaas/investidor/carteira_administrada/contas_bancarias/definir_conta_principal



---

# enviar_contas_bancarias

URL: /documentation/iaas/investidor/carteira_administrada/contas_bancarias/enviar_contas_bancarias



---

# Criar investidor

URL: /documentation/iaas/investidor/carteira_administrada/criar_investidor

---

### Introdução
Este recurso tem como objetivo nos informar dados básicos para iniciar o cadastro de um **investidor**.

A criação de um investidor já dispara, em conjunto, a abertura de uma primeira **análise cadastral** vinculada a ele. Por isso, ao final desta chamada são retornadas duas chaves: ***investor_key*** (identifica o investidor) e ***investor_analysis_key*** (identifica a análise cadastral em andamento).

:::info Informação
No ambiente de Homologação, temos a seguinte regra para aprovações: CPF/CNPJ com início **1**: reprovação automática; CPF/CNPJ com início **8**: pendente de validação manual; o restante é aprovado automaticamente.
:::

### Input / Output

Como ***input*** envie os dados básicos do investidor. Os campos obrigatórios variam de acordo com **`person_type`** e **`investor_sub_type`**.

Como ***output*** serão retornadas a ***investor_key*** e a ***investor_analysis_key***. A ***investor_key*** identifica o investidor; a ***investor_analysis_key*** identifica a análise cadastral aberta junto com a criação. Um mesmo investidor pode possuir mais de uma análise cadastral ao longo do tempo (renovações, atualizações).

### Request

ENDPOINT `/investor_registry/investor`
MÉTODO `POST`
STATUS `201`

### Request body

Caso 01: Pessoa Física

```json title='Request Body'
{
    "name": "João da Silva",
    "document_number": "123.456.789-00",
    "person_type": "natural_person",
    "email": "joao.silva@example.com",
    "phone": {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "987654321"
    }
}
```

Caso 02: Pessoa Jurídica

```json title='Request Body'
{
    "name": "Empresa XPTO Ltda",
    "document_number": "12.345.678/0001-90",
    "person_type": "legal_person",
    "investor_sub_type": "default"
}
```

:::warning Atenção
Os campos obrigatórios mudam de acordo com o **`person_type`**:

- **`natural_person`**: `name`, `document_number`, `person_type` (`email` e `phone` recomendados para criação de usuário)
- **`legal_person`**: `name`, `document_number`, `person_type`, `investor_sub_type`
:::

### Body params
| Campo                       | Tipo     | Descrição                                                                                   | Caracteres   | Obrigatório |
|-----------------------------|----------|---------------------------------------------------------------------------------------------|--------------|-------------|
| `name`                      | string   | Nome (ou razão social) do investidor                                                        |   1 - 255    |    Sim      |
| `person_type`               | string   | Enumerador de **[Person Type](#person-type)**                                               |      -       |    Sim      |
| `document_number`           | string   | CPF (`XXX.XXX.XXX-XX`) ou CNPJ (`XX.XXX.XXX/XXXX-XX`)                                       |   14 ou 18   |    Sim*     |
| `investor_sub_type`         | string   | Enumerador de **[Investor Sub Type](#investor-sub-type)**                                   |      -       |    Não      |
| `email`                     | string   | E-mail do investidor                                                                        |   1 - 255    |    Não      |
| `phone`                     | object   | Objeto de **[Phone](#phone)**                                                               |      -       |    Não      |
| `investor_owner_type`       | string   | Tipo de relação de propriedade - Enumerador de **[Investor Owner Type](#investor-owner-type)**  |   1 - 255    |    Não      |

### Phone
| Campo                       | Tipo     | Descrição                                                                                   | Caracteres   | Obrigatório |
|-----------------------------|----------|---------------------------------------------------------------------------------------------|--------------|-------------|
| `international_dial_code`   | string   | Código internacional (ex.: `55`)                                                            |   1 - 3      |    Sim      |
| `area_code`                 | string   | DDD                                                                                         |      2       |    Sim      |
| `number`                    | string   | Número do telefone                                                                          |   8 - 9      |    Sim      |

### Person Type {#person-type}
| Enumerador          | Descrição                                            |
|---------------------|------------------------------------------------------|
| `natural_person`    | Pessoa física                                        |
| `legal_person`      | Pessoa jurídica                                      |

### Investor Sub Type {#investor-sub-type}
| Enumerador               | Descrição                                                                                  |
|--------------------------|--------------------------------------------------------------------------------------------|
| `default`                | Pessoa jurídica regular (default quando o campo não é informado)                           |

### Investor Owner Type {#investor-owner-type}
| Enumerador               | Descrição                                                                                  |
|--------------------------|--------------------------------------------------------------------------------------------|
| `wallet_manager`                | Gestor de Carteira         

### Response
```json title='Response Body'
{
    "investor_key": "UUID",
    "investor_analysis_key": "UUID"
}
```

---

# definir_grupo_assinantes_padrao

URL: /documentation/iaas/investidor/carteira_administrada/definir_grupo_assinantes_padrao



---

# enviar_cadastro_para_analise

URL: /documentation/iaas/investidor/carteira_administrada/enviar_cadastro_para_analise



---

# enviar_dados_cadastrais

URL: /documentation/iaas/investidor/carteira_administrada/enviar_dados_cadastrais



---

# enviar_endereco

URL: /documentation/iaas/investidor/carteira_administrada/enviar_endereco



---

# enviar_grupos_assinantes

URL: /documentation/iaas/investidor/carteira_administrada/enviar_grupos_assinantes



---

# enviar_investor_document

URL: /documentation/iaas/investidor/carteira_administrada/enviar_investor_document



---

# enviar_patrimonio

URL: /documentation/iaas/investidor/carteira_administrada/enviar_patrimonio



---

# consultar_feedback

URL: /documentation/iaas/investidor/carteira_administrada/feedback/consultar_feedback



---

# enviar_mensagem_feedback

URL: /documentation/iaas/investidor/carteira_administrada/feedback/enviar_mensagem_feedback



---

# listar_feedbacks

URL: /documentation/iaas/investidor/carteira_administrada/feedback/listar_feedbacks



---

# Introdução

URL: /documentation/iaas/investidor/carteira_administrada/introducao

Esta seção descreve o fluxo de cadastro de investidores do tipo **Carteira Administrada** — carteiras geridas profissionalmente em nome de um titular econômico (o *investor owner*).

Diferente do cadastro de uma pessoa física ou jurídica padrão, aqui o investidor é a própria carteira, e o cadastro precisa contemplar tanto os dados da carteira quanto os dados do titular que detém os recursos investidos por meio dela.

O tipo de integração utilizada para esse tipo de cadastro de investidor é a `investor-integration`, descrita na seção de introdução da documentação. Para cadastrar um investidor através de uma gestora de carteiras é necessário que o cadastro da gestora esteja atualizado, o que pode ser garantido e mantido através da mesma integração de investidor. Dessa forma, a gestora pode realizar sua atualização cadastral através da API de cadastro de investidores, bem como a manutenção de seus próprios investidores.

Um ponto muito importante é que apenas gestoras que estiverem com seus cadastros atualizados podem realizar o cadastro de investidores de carteira administrada. Portanto, é necessário realizar essa manutenção cadastral.

### Fluxo de Cadastro

1. Criar Investidor
criação inicial do investidor e abertura da primeira análise cadastral
↓
2. Enviar Dados Cadastrais
dados específicos da pessoa física ou jurídica
↓
3. Enviar Endereço
informações de endereço
↓
4. Enviar Patrimônio
informações de patrimônio e enquadramento
↓
5. Enviar Contas Bancárias
contas para movimentação
↓
6. Enviar Suitability
questionário de adequação ao perfil
↓
7. Enviar Grupos de Assinantes
definição de quem deve assinar os documentos
↓
8. Enviar Documentos do Investidor
upload de documentos obrigatórios
↓
9. Criar Partes Relacionadas
sócios, diretores, beneficiários finais
↓
10. Enviar Documentos das Partes Relacionadas
documentos de cada parte relacionada
↓
11. Enviar Contrato de Carteira Administrada
documento que atesta representação legal
↓
12. Enviar para Análise
submissão da análise cadastral para validação
↓
13. Assinar Documentos
assinatura dos documentos gerados após aprovação

Nas subseções a seguir veremos cada uma das etapas necessárias para concluir o cadastro de uma Carteira Administrada e disparar a análise cadastral pela QI Tech.

---

# enviar_documento_investor_owner

URL: /documentation/iaas/investidor/carteira_administrada/investor_owner/enviar_documento_investor_owner



---

# atualizar_parte_relacionada

URL: /documentation/iaas/investidor/carteira_administrada/related_party/atualizar_parte_relacionada



---

# atualizar_status_parte_relacionada

URL: /documentation/iaas/investidor/carteira_administrada/related_party/atualizar_status_parte_relacionada



---

# criar_parte_relacionada

URL: /documentation/iaas/investidor/carteira_administrada/related_party/criar_parte_relacionada



---

# enviar_documento_parte_relacionada

URL: /documentation/iaas/investidor/carteira_administrada/related_party/enviar_documento_parte_relacionada



---

# consultar_formulario_suitability

URL: /documentation/iaas/investidor/carteira_administrada/suitability/consultar_formulario_suitability



---

# enviar_suitability

URL: /documentation/iaas/investidor/carteira_administrada/suitability/enviar_suitability



---

# Assinar Documento

URL: /documentation/iaas/investidor/compartilhado/assinar_documento

---
### Introdução
Este recurso confirma a assinatura de um documento gerado para a formalização do cadastro do investidor via método **opt-in**. Os tipos suportados são: ficha cadastral (pessoa física ou jurídica), termo de investidor qualificado e termo de investidor profissional.

Diferente de **[Enviar Documento Assinado](/documentation/iaas/investidor/compartilhado/enviar_documento_assinado)** (que faz upload do arquivo final assinado), este recurso apenas registra a comprovação da assinatura por meio do hash de opt-in coletado pelo distribuidor.

:::warning Atenção
Este recurso está disponível apenas para integrações que atuam como **Distribuidor** com `document_signature` configurado como `opt-in`. O documento deve estar com status `generated`.
:::

### Input / Output

Como ***input*** envie o `opt_in_hash` que comprova a assinatura.

Como ***output***, quando a confirmação finaliza o lote, é retornada a chave `investor_document_key`.

### Request

ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/document_batch/{document_batch_key}/document/{investor_document_key}/sign_document`
MÉTODO `PUT`
STATUS `200`

### Request body

```json title='Request Body'
{
  "opt_in_hash": "OPT_IN_HASH"
}
```

### Body params
| Campo         | Tipo   | Descrição                                  | Obrigatório |
|---------------|--------|--------------------------------------------|-------------|
| `opt_in_hash` | string | Hash de verificação da assinatura opt-in   |    Sim      |

:::warning Atenção
Durante o processo de integração será exigido um meio de autenticação da hash enviada.
:::

### Response
```json title='Response Body'
{
    "investor_document_key": "UUID"
}
```

---

# Atualização Cadastral

URL: /documentation/iaas/investidor/compartilhado/atualizacao_cadastral

---
### Introdução

Após o cadastro inicial de um investidor já ter sido aprovado, novos ciclos de cadastro podem ser abertos sempre que houver necessidade de **atualização cadastral** — seja por mudança de dados, vencimento de documentos ou solicitação de uma nova análise pela QI Tech.

Diferente do cadastro inicial, a atualização **não cria um novo investidor**: ela apenas abre uma nova **análise cadastral** (`investor_analysis`) sobre o investidor existente. A partir disso, o fluxo segue exatamente o mesmo do cadastro original: envio dos dados, documentos, partes relacionadas e submissão para análise.

### Input / Output

Como ***input*** não é necessário enviar nenhum corpo de requisição — basta informar a `investor_key` do investidor que terá sua análise atualizada.

Como ***output*** será retornada a representação da nova análise cadastral, contendo a `investor_analysis_key` que deve ser utilizada nas etapas seguintes do fluxo.

### Request

ENDPOINT `/investor_registry/v2/investor/{investor_key}/investor_analysis`
MÉTODO `POST`
STATUS `201`

:::info
A requisição é enviada **sem corpo** (`body` vazio). Os dados da atualização serão enviados nas etapas subsequentes do fluxo, da mesma forma que no cadastro inicial.
:::

### Próximos passos

A partir do retorno da `investor_analysis_key`, o processo de atualização cadastral segue **o mesmo fluxo do cadastro inicial** descrito nesta seção:

1. Envio dos dados cadastrais (pessoa física/jurídica, endereço, patrimônio).
2. Envio de contas bancárias, suitability, grupos de assinantes, partes relacionadas e documentos — conforme aplicável ao tipo de investidor.
3. Envio do cadastro para análise.
4. Assinatura dos documentos gerados após a aprovação.

Consulte as etapas subsequentes desta seção para os detalhes de cada recurso.

---

# Atualizar Status do Grupo de Assinantes

URL: /documentation/iaas/investidor/compartilhado/atualizar_status_grupo_assinantes

---
### Introdução
Este recurso altera o status de um grupo de assinantes previamente cadastrado em uma análise cadastral — por exemplo, para inativar um grupo que não deve mais ser utilizado.

O grupo é identificado pela sua chave externa (`external_signer_group_key`), retornada na criação.

### Request

ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/signer_group/{external_signer_group_key}/status`
MÉTODO `PUT`
STATUS `202`

### Request body
```json title='Request Body'
{
    "status": "inactive"
}
```

### Body params
| Campo    | Tipo   | Descrição                                                       | Obrigatório |
|----------|--------|-----------------------------------------------------------------|-------------|
| `status` | string | Novo status do grupo. Valores típicos: `active`, `inactive`     |    Sim      |

### Response
`202 Accepted`. A representação atualizada do grupo é retornada no corpo.

---

# Consulta Informações de uma Análise Cadastral do Investidor

URL: /documentation/iaas/investidor/compartilhado/busca_informacoes_de_uma_analise_cadastral_do_investidor

---

### Introdução
Este recurso retorna a representação completa de uma **análise cadastral**, incluindo dados cadastrais preenchidos (`natural_person` / `legal_person`), endereço, patrimônio, suitability, contas bancárias, grupos de assinantes, partes relacionadas, investor owners, documentos da análise, lotes de documentos para assinatura e histórico de eventos de status.

### Input / Output

Não há corpo de requisição.

Como ***output*** será retornada a representação da análise cadastral identificada por `investor_analysis_key`.

### Request

ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}`
MÉTODO `GET`
STATUS `200`

:::info Endpoints relacionados
- **Análise em andamento** para um investidor: `GET /investor_registry/investor/{investor_key}/in_progress_investor_analysis`.
- **Listagem paginada de análises** do agente: `GET /investor_registry/investor_analyses`.
:::

### Response

Caso 01: Análise de Pessoa Jurídica — Fundo de Investimento

```json
{
   "investor_analysis_key": "UUID",
   "name": "Fundo XPTO Multimercado",
   "document_number": "12.345.678/0001-90",
   "analysis_datetime": "2025-04-29T12:07:55Z",
   "status": "manually_approved",
   "analysis_type": "v2",
   "agent_key": "UUID",
   "investor": {
      "investor_key": "UUID",
      "name": "Fundo XPTO Multimercado",
      "document_number": "12.345.678/0001-90",
      "person_type": "legal_person",
      "investor_sub_type": "fund_class",
      "status": "registered"
   },
   "registry_user": {
      "registry_user_key": "UUID",
      "name": "Sample Investor Name",
      "document_number": "123.456.789-00",
      "email": "user@example.com",
      "phone": {
         "number": "987654321",
         "area_code": "11",
         "international_dial_code": "55"
      }
   },
   "email": "fundo@example.com",
   "phone": {
      "number": "987654321",
      "area_code": "11",
      "international_dial_code": "55"
   },
   "address": {
      "uf": "SP",
      "city": "São Paulo",
      "number": "1000",
      "street": "Avenida Paulista",
      "country": "BRA",
      "complement": "Sala 1010",
      "postal_code": "01310-100",
      "neighborhood": "Bela Vista"
   },
   "legal_person": {
      "legal_name": "Fundo XPTO Multimercado FIC FIM",
      "constitution_date": "2020-01-15",
      "exclusive_fund_class": false
   },
   "net_worth": {
      "total_net_worth": 25000000,
      "total_financial_applications": 25000000,
      "monthly_income": 0,
      "other_incomes": 0,
      "real_estate": 0,
      "movable_assets": 0,
      "investor_category": "professional"
   },
   "investor_category": "professional",
   "bank_accounts": [
      {
         "bank_account_key": "UUID",
         "main_account": true,
         "account_digit": "8",
         "account_branch": "2152",
         "account_number": "43473205725488",
         "financial_institution_code": "349",
         "status": "active"
      }
   ],
   "signer_groups": [
      {
         "signer_group_key": "UUID",
         "external_signer_group_key": "UUID",
         "is_default": true,
         "minimum_required_signers": 1,
         "status": "active",
         "signers": [
            {
               "name": "Representante Legal",
               "document_number": "123.456.789-00",
               "email": "rep@example.com",
               "is_required_signer": true
            }
         ]
      }
   ],
   "investor_owners": [
      {
         "external_investor_owner_key": "UUID",
         "investor_owner_type": "fund_class_administrator",
         "document_number": "07.228.314/0001-95",
         "status": "active"
      },
      {
         "external_investor_owner_key": "UUID",
         "investor_owner_type": "fund_class_manager",
         "document_number": "77.784.920/0001-72",
         "status": "active"
      }
   ],
   "related_parties": [],
   "representatives_analyses": [
      {
         "representative_analysis_key": "UUID",
         "name": "Sample",
         "document_number": "069.800.621-66",
         "status": "pending_documents",
         "documents": [],
         "powers": [
            "investor_registry.create_investor",
            "investor_registry.update_investor_analysis"
         ]
      }
   ],
   "documents": [
      {
         "document_key": "UUID",
         "type": "cnpj_card",
         "status": "valid",
         "observation": null
      }
   ],
   "document_batches": [
      {
         "document_batch_key": "UUID",
         "status": "signed",
         "documents": [
            {
               "investor_document_key": "UUID",
               "document_type": "legal_person_registry_form",
               "status": "signed",
               "signature_method": "certifiqi"
            }
         ]
      }
   ],
   "feedbacks": [],
   "status_events": [
      {"status": "pending_registry_data", "event_datetime": "2025-04-29T12:07:55Z"},
      {"status": "sent_to_analysis",       "event_datetime": "2025-04-29T12:08:00Z"},
      {"status": "manually_approved",      "event_datetime": "2025-04-29T13:00:00Z"}
   ]
}
```

### Investor Analysis
| Campo                       | Tipo    | Descrição                                                                |
|-----------------------------|---------|--------------------------------------------------------------------------|
| `investor_analysis_key`     | string  | Chave única da análise cadastral                                         |
| `name`                      | string  | Nome (ou razão social)                                                   |
| `document_number`           | string  | CPF / CNPJ                                                               |
| `analysis_datetime`         | string  | Data/hora de criação da análise. Veja [Formato de data](#formato-data)   |
| `analysis_type`             | string  | Enumerador de **[Analysis Type](#analysis-type)**                        |
| `status`                    | string  | Enumerador de **[Investor Analysis Status](#analysis-status)**           |
| `investor_category`         | string  | Enquadramento autodeclarado (`retail`, `qualified`, `professional`)      |
| `suitability`               | string  | Perfil suitability calculado (quando aplicável)                          |
| `signature_method`          | string  | Método de assinatura definido para a análise                             |
| `expiration_date`           | string  | Data de expiração do cadastro                                            |
| `investor`                  | object  | Investidor associado                                                     |
| `email`                     | string  | E-mail                                                                   |
| `phone`                     | object  | Objeto de **[Phone](#phone)**                                            |
| `address`                   | object  | Endereço — ver doc **Enviar Endereço**                                   |
| `natural_person`            | object  | Dados de pessoa física — ver doc **Enviar Dados Cadastrais**             |
| `legal_person`              | object  | Dados de pessoa jurídica — ver doc **Enviar Dados Cadastrais**           |
| `net_worth`                 | object  | Dados patrimoniais — ver doc **Enviar Patrimônio**                       |
| `bank_accounts`             | array   | Contas bancárias                                                         |
| `signer_groups`             | array   | Grupos de assinantes                                                     |
| `investor_owners`           | array   | Vínculos de propriedade (relevante para `fund_class`)                    |
| `related_parties`           | array   | Partes relacionadas                                                      |
| `documents`                 | array   | Documentos enviados na análise                                           |
| `document_batches`          | array   | Lotes de documentos para assinatura                                      |
| `feedbacks`                 | array   | Feedbacks trocados na análise — ver **[Listar Feedbacks](./feedback/listar_feedbacks)**. Um feedback `open` não altera o `status` da análise |
| `status_events`             | array   | Histórico de eventos de status                                           |

### Legal Person — campos `fund_class`
Quando `investor.investor_sub_type` é `fund_class`, os campos abaixo são enriquecidos automaticamente a partir da base da CVM durante o envio para análise:

| Campo                  | Tipo    | Descrição                                                                |
|------------------------|---------|--------------------------------------------------------------------------|
| `legal_name`           | string  | Razão social / nome da classe do fundo                                   |
| `constitution_date`    | string  | Data de constituição                                                     |
| `exclusive_fund_class` | boolean | Indica se a classe é exclusiva                                           |

### Phone
| Campo                     | Tipo   | Descrição              | Caracteres |
|---------------------------|--------|------------------------|------------|
| `international_dial_code` | string | Código internacional   |   1 - 3    |
| `area_code`               | string | DDD                    |     2      |
| `number`                  | string | Número de telefone     |   8 - 9    |

### Investor Analysis Status {#analysis-status}
| Enumerador                | Descrição                            |
|---------------------------|--------------------------------------|
| `created`                 | Criada                               |
| `pending_registry_data`   | Pendente dados cadastrais            |
| `pending_documents`       | Pendente documentos                  |
| `sent_to_analysis`        | Enviada para análise                 |
| `in_manual_analysis`      | Em análise manual                    |
| `in_compliance_analysis`  | Em análise de compliance             |
| `automatically_approved`  | Aprovada automaticamente             |
| `automatically_reproved`  | Reprovada automaticamente            |
| `manually_approved`       | Aprovada manualmente                 |
| `manually_reproved`       | Reprovada manualmente                |
| `analysis_complete`       | Análise concluída                    |
| `expired`                 | Expirada                             |

Para entender qual status exige ação sua e qual apenas aguarda a QI Tech, veja **[Ciclo de vida da análise cadastral](./ciclo_de_vida_da_analise)**.

### Analysis Type {#analysis-type}
| Enumerador                 | Descrição                                                              |
|----------------------------|-------------------------------------------------------------------------|
| `first_analysis`           | Primeira análise cadastral do investidor                                |
| `registry_update_analysis` | Análise aberta por atualização cadastral ou renovação                   |
| `fund_class_transfer`      | Análise gerada por transferência de classe de fundo                     |

### Formato de data {#formato-data}

Os campos de data/hora — `analysis_datetime`, `event_datetime` dos `status_events`, e os equivalentes nas demais rotas — são devolvidos em **ISO-8601 UTC com sufixo `Z`**, sem microssegundos:

```
2026-07-31T21:47:46Z
```

O campo `expiration_date` é uma **data pura**, sem hora, no formato `YYYY-MM-DD`.

:::info Se você observou outro formato
Até a correção aplicada em agosto de 2026, algumas rotas — entre elas `GET /investor_registry/investor/{investor_key}` — devolviam data/hora no formato `2026-07-31 21:47:46.138686` (com espaço, com microssegundos e sem `Z`). Esse comportamento era um desvio do padrão e foi corrigido: todas as rotas agora emitem `Z`.

Se a sua integração fez o parse do formato antigo, ajuste-a para ISO-8601. Recomendamos usar um parser ISO-8601 padrão da sua linguagem em vez de um formato fixo.
:::

---

# Consulta Informações do Investidor

URL: /documentation/iaas/investidor/compartilhado/busca_informacoes_do_investidor

---

### Introdução
Este recurso retorna os dados completos de um **investidor** — incluindo suas análises cadastrais, lotes de documentos, eventos de status, distribuidor e usuário cadastrador.

### Input / Output

Não há corpo de requisição. As chaves de identificação são passadas no *path*.

Como ***output*** será retornada a representação atual do investidor.

### Request

ENDPOINT `/investor_registry/investor/{investor_key}`
MÉTODO `GET`
STATUS `200`

:::info Endpoints relacionados
- **Listar investidores do agente**: `GET /investor_registry/investors` (paginado, com filtros `name`, `document_number`, `status`).
- **Listar investidores possuídos por um investor owner** (uso típico: fund class): `GET /investor_registry/investor/{investor_key}/investors`.
:::

### Response

Caso 01: Pessoa Física

```json
{
   "investor_key": "UUID",
   "name": "João da Silva",
   "document_number": "123.456.789-00",
   "status": "pending_analysis",
   "email": "joao@example.com",
   "person_type": "natural_person",
   "phone": {
      "number": "987654321",
      "area_code": "11",
      "international_dial_code": "55"
   },
   "distributor": {
      "distributor_key": "UUID",
      "name": "Distribuidor XPTO",
      "document_number": "00.000.000/0000-00"
   },
   "analyses": [
      {
         "investor_analysis_key": "UUID",
         "analysis_datetime": "2025-04-29 12:07:55.059999",
         "status": "pending_registry_data"
      }
   ],
   "document_batches": [],
   "status_events": [
      {
         "status": "pending_analysis",
         "event_datetime": "2025-04-29 12:07:55.000000"
      }
   ]
}
```

Caso 02: Pessoa Jurídica — Fundo de Investimento

```json
{
   "investor_key": "UUID",
   "name": "Fundo XPTO Multimercado",
   "document_number": "12.345.678/0001-90",
   "status": "registered",
   "person_type": "legal_person",
   "investor_sub_type": "fund_class",
   "distributor": {
      "distributor_key": "UUID",
      "name": "Distribuidor XPTO",
      "document_number": "00.000.000/0000-00"
   },
   "analyses": [
      {
         "investor_analysis_key": "UUID",
         "analysis_datetime": "2025-04-29 12:07:55.059999",
         "status": "manually_approved",
         "registry_user": {
            "registry_user_key": "UUID",
            "kc_user_id": "UUID",
            "name": "João da Silva",
            "document_number": "000.000.000-00",
            "email": "joao.silva@example.com",
            "phone": {
               "number": "123456789",
               "area_code": "11",
               "international_dial_code": "55"
            }
         }
      }
   ],
   "document_batches": [
      {
         "document_batch_key": "UUID",
         "status": "signed",
         "documents": [
            {
               "investor_document_key": "UUID",
               "type": "legal_person_registry_form",
               "status": "signed"
            }
         ]
      }
   ],
   "status_events": [
      {
         "status": "registered",
         "event_datetime": "2025-04-29 13:08:25.673902"
      }
   ]
}
```

### Investor
| Campo               | Tipo    | Descrição                                                                       |
|---------------------|---------|---------------------------------------------------------------------------------|
| `investor_key`      | string  | Chave única de identificação do investidor                                      |
| `name`              | string  | Nome (ou razão social) do investidor                                            |
| `document_number`   | string  | CPF / CNPJ do investidor                                                        |
| `email`             | string  | E-mail de contato                                                               |
| `phone`             | object  | Objeto de **[Phone](#phone)**                                                   |
| `status`            | string  | Enumerador de **[Investor Status](#investor-status)**                           |
| `person_type`       | string  | Enumerador de **[Person Type](#person-type)**                                   |
| `investor_sub_type` | string  | Enumerador de **[Investor Sub Type](#investor-sub-type)**, quando aplicável     |
| `distributor`       | object  | Objeto de **[Distributor](#distributor)**                                       |
| `analyses`          | array   | Lista de objetos de **[Investor Analysis](#investor-analysis)**                 |
| `document_batches`  | array   | Lista de objetos de **[Document Batch](#document-batch)**                       |
| `status_events`     | array   | Lista de objetos de **[Status Event](#status-event)**                           |

### Phone
| Campo                     | Tipo   | Descrição              | Caracteres |
|---------------------------|--------|------------------------|------------|
| `international_dial_code` | string | Código internacional   |   1 - 3    |
| `area_code`               | string | DDD                    |     2      |
| `number`                  | string | Número de telefone     |   8 - 9    |

### Investor Status {#investor-status}
| Enumerador            | Descrição               |
|-----------------------|-------------------------|
| `created`             | Criado                  |
| `pending_analysis`    | Pendente análise        |
| `pending_documents`   | Pendente documentos     |
| `incomplete`          | Cadastro incompleto     |
| `pending_update`      | Pendente atualização    |
| `registered`          | Cadastrado              |
| `registry_expired`    | Cadastro expirado       |

### Person Type {#person-type}
| Enumerador        | Descrição        |
|-------------------|------------------|
| `natural_person`  | Pessoa física    |
| `legal_person`    | Pessoa jurídica  |
| `nominee`         | Nominee / PCO    |

### Investor Sub Type {#investor-sub-type}
| Enumerador               | Descrição                       |
|--------------------------|---------------------------------|
| `default`                | Pessoa jurídica regular         |
| `financial_institution`  | Instituição financeira          |
| `fund_class`             | Fundo de investimento           |
| `non-resident`           | Não-residente                   |

### Distributor {#distributor}
| Campo               | Tipo   | Descrição                                          |
|---------------------|--------|----------------------------------------------------|
| `distributor_key`   | string | Chave única do distribuidor                        |
| `name`              | string | Nome do distribuidor                               |
| `document_number`   | string | CNPJ do distribuidor                               |

### Investor Analysis {#investor-analysis}
| Campo                    | Tipo   | Descrição                                                        |
|--------------------------|--------|------------------------------------------------------------------|
| `investor_analysis_key`  | string | Chave única da análise cadastral                                 |
| `analysis_datetime`      | string | Data/hora de criação da análise                                  |
| `status`                 | string | Enumerador de **[Investor Analysis Status](#analysis-status)**   |
| `registry_user`          | object | Objeto de **[Registry User](#registry-user)**, quando presente   |

### Document Batch {#document-batch}
| Campo                | Tipo   | Descrição                                              |
|----------------------|--------|--------------------------------------------------------|
| `document_batch_key` | string | Chave única do lote de documentos                      |
| `status`             | string | Enumerador de **[Document Batch Status](#batch-status)**|
| `documents`          | array  | Lista de objetos de **[Investor Document](#investor-document)**|

### Investor Document {#investor-document}
| Campo                  | Tipo   | Descrição                                                       |
|------------------------|--------|-----------------------------------------------------------------|
| `investor_document_key`| string | Chave única do documento do investidor                          |
| `type`                 | string | Enumerador de **[Document Type](#document-type)**               |
| `status`               | string | Enumerador de **[Investor Document Status](#document-status)**  |

### Registry User {#registry-user}
| Campo               | Tipo   | Descrição                                       |
|---------------------|--------|-------------------------------------------------|
| `registry_user_key` | string | Chave única do usuário cadastrador              |
| `kc_user_id`        | string | ID do usuário no KeyCloak                       |
| `name`              | string | Nome                                            |
| `document_number`   | string | CPF                                             |
| `email`             | string | E-mail                                          |
| `phone`             | object | Objeto de **[Phone](#phone)**                   |

### Investor Analysis Status {#analysis-status}
| Enumerador                | Descrição                            |
|---------------------------|--------------------------------------|
| `created`                 | Criada                               |
| `pending_registry_data`   | Pendente dados cadastrais            |
| `pending_documents`       | Pendente documentos                  |
| `sent_to_analysis`        | Enviada para análise                 |
| `in_manual_analysis`      | Em análise manual                    |
| `automatically_approved`  | Aprovada automaticamente             |
| `automatically_reproved`  | Reprovada automaticamente            |
| `manually_approved`       | Aprovada manualmente                 |
| `manually_reproved`       | Reprovada manualmente                |
| `expired`                 | Expirada                             |

### Document Batch Status {#batch-status}
| Enumerador               | Descrição                       |
|--------------------------|---------------------------------|
| `creating_documents`     | Documentos sendo gerados        |
| `send_to_signature`      | Enviado para assinatura         |
| `pending_signature`      | Aguardando assinatura           |
| `signed`                 | Assinado                        |

### Document Type {#document-type}
| Enumerador                     | Descrição                              |
|--------------------------------|----------------------------------------|
| `cnh`                          | CNH                                    |
| `rg`                           | RG                                     |
| `rg_back`                      | RG — verso                             |
| `rg_front`                     | RG — frente                            |
| `proof_of_residence`           | Comprovante de residência              |
| `cnpj_card`                    | Cartão CNPJ                            |
| `financial_statements`         | Demonstrações financeiras              |
| `social_contract`              | Contrato social                        |
| `company_statute`              | Estatuto                               |
| `board_election_record`        | Ata de eleição                         |
| `fund_prospectus`              | Regulamento do fundo                   |
| `power_of_attorney`            | Procuração                             |
| `billing_statement`            | Fatura / extrato                       |
| `investor_qualification_proof` | Comprovação de qualificação            |
| `qualified_investor_term`      | Termo de investidor qualificado        |
| `professional_investor_term`   | Termo de investidor profissional       |
| `natural_person_registry_form` | Ficha cadastral — pessoa física        |
| `legal_person_registry_form`   | Ficha cadastral — pessoa jurídica      |

### Investor Document Status {#document-status}
| Enumerador         | Descrição                              |
|--------------------|----------------------------------------|
| `sent_to_generate` | Enviado para ser gerado                |
| `generated`        | Gerado                                 |
| `signed`           | Assinado                               |

### Status Event {#status-event}
| Campo            | Tipo   | Descrição                                                       |
|------------------|--------|-----------------------------------------------------------------|
| `status`         | string | Enumerador de status                                            |
| `event_datetime` | string | Data/hora do evento                                             |

---

# Buscar Lotes de Documentos para Assinatura

URL: /documentation/iaas/investidor/compartilhado/buscar_documentos_para_assinatura

---
### Introdução
Este recurso retorna os **lotes de documentos** (`document_batches`) gerados para um investidor após o envio da análise cadastral. Cada lote agrupa os documentos a serem assinados (ficha cadastral, termos de investidor qualificado/profissional, etc.) e expõe o status e o método de assinatura de cada documento.

### Input / Output

Não há corpo de requisição. Opcionalmente é possível filtrar por análise cadastral via query param.

Como ***output*** será retornada a lista de lotes do investidor.

### Request

ENDPOINT `/investor_registry/investor/{investor_key}/document_batches`
MÉTODO `GET`
STATUS `200`

### Query params
| Campo                   | Tipo   | Descrição                                                            | Obrigatório |
|-------------------------|--------|----------------------------------------------------------------------|-------------|
| `investor_analysis_key` | string | Filtra os lotes pertencentes a uma análise cadastral específica      |    Não      |

### Response

```json title='Response Body'
[
  {
    "document_batch_key": "UUID",
    "status": "pending_signature",
    "investor_analysis_key": "UUID",
    "url": "https://docs.qitech.com.br/...",
    "documents": [
      {
        "investor_document_key": "UUID",
        "document_type": "legal_person_registry_form",
        "status": "generated",
        "signature_method": "certifiqi"
      },
      {
        "investor_document_key": "UUID",
        "document_type": "professional_investor_term",
        "status": "generated",
        "signature_method": "certifiqi"
      }
    ]
  }
]
```

### Document Batch Status
| Enumerador              | Descrição                       |
|-------------------------|---------------------------------|
| `creating_documents`    | Documentos sendo gerados        |
| `pending_signer_groups` | Aguardando grupos de assinantes |
| `send_to_signature`     | Enviados para assinatura        |
| `pending_signature`     | Aguardando assinatura           |
| `signed`                | Assinados                       |

:::info Detalhes de assinatura
Para detalhes de cada assinatura em um lote específico, utilize `GET /investor_registry/investor/{investor_key}/document_batch/{document_batch_key}/signature_details`.
:::

---

# Ciclo de vida da análise cadastral

URL: /documentation/iaas/investidor/compartilhado/ciclo_de_vida_da_analise

---

### Introdução

Depois do `submit`, a análise cadastral deixa de depender de você e passa a evoluir de forma **assíncrona**. Esta página descreve as etapas do fluxo, **em quais situações o cadastro volta a exigir a sua ação** e como acompanhar tudo isso por webhook.

---

### As etapas do fluxo

O cadastro percorre a sequência abaixo — **sempre para a frente**. As etapas 3 e 4 são **condicionais**: um cadastro sem pendências vai direto da análise automática para a aprovação. Nenhuma etapa devolve a análise para o preenchimento: quando a compliance precisa de um esclarecimento, ela abre um **feedback** sem alterar o status da análise.

```mermaid
flowchart TD
    E1["1. Preenchimento<br/>pending_registry_data"] -->|submit| E2["2. Análise automática<br/>sent_to_analysis"]
    E2 -->|sem pendências| A1["Aprovação<br/>automatically_approved"]
    E2 -->|recusa de compliance| R1["Recusa<br/>automatically_reproved"]
    E2 -->|requer revisão| E3["3. Análise manual<br/>in_manual_analysis<br/>etapa condicional"]
    E3 -->|aprovado| A2["Aprovação<br/>manually_approved"]
    E3 -->|cadastro insuficiente| R2["Recusa<br/>manually_reproved"]
    E3 -->|requer compliance| E4["4. Análise de compliance<br/>in_compliance_analysis<br/>etapa condicional"]
    E4 -->|aprovado| A2
    E4 -->|cadastro insuficiente| R2
    E4 -->|esclarecimentos| FB["Feedback aberto<br/>feedback: open<br/>a análise permanece em<br/>in_compliance_analysis"]
    FB -->|você responde<br/>feedback: closed| E4
    A1 --> E5["5. Documentos e assinatura<br/>pending_documents"]
    A2 --> E5
    E5 --> E6["6. Cadastro concluído<br/>analysis_complete"]
    R2 --> N["Nova análise cadastral"]
```

| # | Etapa | Status da análise | Quem age |
|---|-------|-------------------|----------|
| 1 | **Preenchimento** — dados cadastrais, endereço, patrimônio, suitability, contas, partes relacionadas e documentos | `created` → `pending_registry_data` | **Você** |
| 2 | **Análise automática** — motores de risco e PLD processam o cadastro e produzem uma decisão: aprovação, recusa, ou encaminhamento para revisão humana | `sent_to_analysis` | QI Tech (automático) |
| 3 | **Análise manual** *(condicional)* — um analista revisa os dados cadastrais. **Esta etapa é pulada quando o cadastro é aprovado automaticamente** | `in_manual_analysis` | QI Tech (analista) |
| 4 | **Análise de compliance** *(condicional)* — revisão de PLD/compliance. **Também é pulada quando o cadastro é aprovado automaticamente.** É a etapa em que um **feedback** pode ser aberto pedindo esclarecimentos | `in_compliance_analysis` | QI Tech (analista) — **e você, se um feedback for aberto** |
| 5 | **Documentos e assinatura** — aprovada a análise, a QI Tech gera o lote de documentos de formalização e o cadastro segue para assinatura | `automatically_approved` / `manually_approved` → `pending_documents` | Depende da configuração da sua conta |
| 6 | **Conclusão** — o investidor está apto a operar | `analysis_complete` | — |

:::info As etapas 3 e 4 não são obrigatórias
Um cadastro completo e sem indicadores de risco vai de `sent_to_analysis` direto para `automatically_approved`. Quando você observa `in_manual_analysis` ou `in_compliance_analysis`, significa apenas que aquele cadastro foi encaminhado para revisão humana — **não é um erro e não exige ação sua enquanto durar**.
:::

:::info A etapa 5 depende da configuração da sua conta
A geração dos documentos e a coleta da assinatura variam conforme a sua integração seja configurada para que a QI Tech assuma essas responsabilidades, para assinatura por *opt-in*, ou para geração e assinatura externas. Consulte **Buscar Lotes de Documentos para Assinatura** e confirme com o seu contato técnico como a sua conta está configurada.
:::

---

### Quando o cadastro precisa da sua ação {#quando-agir}

Existem **três** situações, e só três, em que a bola está do seu lado depois do `submit`:

| Situação | Sinal | O que fazer |
|----------|-------|-------------|
| **Feedback aberto** | Um feedback com `status: open` — a **análise permanece em `in_compliance_analysis`** | Responder à mensagem do feedback. A sua resposta o encerra (`closed`) e a compliance retoma a avaliação. **Não há novo `submit`.** |
| **Recusa manual** | `manually_reproved` | Abrir uma **nova análise cadastral** com as correções do parecer. |
| **Assinatura** | `pending_documents` | Submeter documentos assinados, ou aguardar assinatura do cotista, dependendo da configuração/papel. |

Em **todos os demais status** — `sent_to_analysis`, `in_manual_analysis`, `in_compliance_analysis` sem feedback aberto, `automatically_approved`, `manually_approved` — o cadastro está com a QI Tech e não há nada a fazer além de aguardar.

#### Feedback: pedido de esclarecimento {#feedback}

Acontece na **etapa 4, a análise de compliance**. Quando o analista de compliance precisa de um complemento ou de um esclarecimento para concluir a avaliação, ele abre um **feedback** com a mensagem do que precisa ser esclarecido.

**A análise não volta atrás.** Ela permanece em `in_compliance_analysis` durante todo o ciclo do feedback — não retorna para `pending_registry_data`, não reabre para edição e não precisa de um novo `submit`. O feedback corre **em paralelo** à análise: abre em `open`, você responde, ele passa a `closed` e a compliance segue de onde parou.

1. **Receba o aviso** pelo webhook `investor_registry.feedback_status_change`, com `status: open`
2. **Leia o pedido** com [Listar Feedbacks](./feedback/listar_feedbacks), usando `origin_type=investor_analysis` com a `investor_analysis_key`, e `origin_type=related_party_analysis` com cada `external_related_party_key`. O texto está em `description` e no histórico de `messages`
3. **Responda** com [Enviar Mensagem em Feedback](./feedback/enviar_mensagem_feedback) — a sua mensagem é a resposta ao pedido
4. **O feedback é encerrado** (`closed`) e um novo `investor_registry.feedback_status_change` é disparado. Nada mais é exigido de você

:::info Feedback só existe na análise de compliance
A etapa de análise manual (etapa 3) não abre feedbacks: ela termina em aprovação ou em recusa. Se a sua integração recebeu um feedback, ele veio da análise de compliance.
:::

:::warning Não acompanhe feedbacks pelo status da análise
Como a análise continua em `in_compliance_analysis`, **nenhuma mudança de status sinaliza um feedback aberto**. A única notificação é o webhook `investor_registry.feedback_status_change`. Uma integração que só observa o status da análise não perceberá o pedido — e o cadastro ficará parado na compliance à espera de uma resposta que não virá.
:::

:::warning A análise continua bloqueada para edição
Permanecer em `in_compliance_analysis` significa que os endpoints de preenchimento — dados cadastrais, documentos, partes relacionadas, contas — continuam recusando alterações. O canal de resposta ao feedback é a **mensagem**. Se o esclarecimento exigir alterar o cadastro em si, a compliance recusará a análise e você abrirá uma nova por meio de **Atualização Cadastral**.
:::

:::info A sua resposta encerra o feedback
Enviar a mensagem move o feedback de `open` para `closed` — não é preciso aguardar um analista da QI Tech encerrá-lo. Se a resposta não for suficiente, a compliance abre um **novo** feedback.
:::

#### Recusa

A recusa é o caminho **mais comum** quando um cadastro não é aprovado, e vem em duas formas:

- **`automatically_reproved`** — recusa de **compliance**, aplicada automaticamente logo após o `submit`, ainda na etapa 2. O cadastro sequer chega à revisão humana.
- **`manually_reproved`** — recusa por um analista, na etapa 3 ou 4, quando o cadastro não reúne os dados mínimos para aprovação. Vem acompanhada de um parecer.

Nos dois casos a análise é **terminal**: ela não volta atrás, e nenhum dado dela pode mais ser alterado — tentativas de atualizar partes relacionadas, contas ou documentos são recusadas com `IVR000185`.

O caminho é abrir uma **nova análise cadastral** para o mesmo investidor, por meio de **Atualização Cadastral**, e refazer o preenchimento com as correções indicadas.

:::info Recusa e feedback são coisas diferentes
O **feedback** não altera o status da análise: ela segue em `in_compliance_analysis` e o pedido é resolvido com uma mensagem. A **recusa** encerra a análise e exige começar uma nova. Se a sua integração trata os dois casos igual, ela vai abrir análises desnecessárias — ou deixar de abrir as que precisa.
:::

---

### Referência de status da análise

| Status                   | Etapa | Significado                                                    | Ação esperada de você                          |
|--------------------------|-------|------------------------------------------------------------------|----------------------------------------------------|
| `created`                | 1     | Análise recém-aberta                                             | Preencher os dados cadastrais                      |
| `pending_registry_data`  | 1     | Aguardando dados e documentos para o envio inicial               | **Completar e enviar o `submit`**                  |
| `sent_to_analysis`       | 2     | Em processamento                                                 | Aguardar                                           |
| `in_manual_analysis`     | 3     | Em revisão por um analista *(etapa condicional)*                 | Aguardar                                           |
| `in_compliance_analysis` | 4     | Em revisão de compliance *(etapa condicional)*                   | Aguardar — **ou responder o feedback**, se algum for aberto |
| `automatically_approved` | 5     | Aprovada sem intervenção humana                                  | Aguardar a geração dos documentos                  |
| `manually_approved`      | 5     | Aprovada por um analista                                         | Aguardar a geração dos documentos                  |
| `pending_documents`      | 5     | Documentos gerados, aguardando assinatura                        | Depende da configuração da sua conta               |
| `automatically_reproved` | —     | Recusada automaticamente pela análise de compliance              | **Abrir nova análise cadastral**                   |
| `manually_reproved`      | —     | Recusada por um analista, com parecer                            | **Abrir nova análise cadastral** com as correções  |
| `analysis_complete`      | 6     | Cadastro concluído — o investidor está apto a operar             | Nenhuma                                            |
| `expired`                | —     | Cadastro vencido (2 anos após a conclusão)                       | Abrir nova análise para renovação                  |

:::info `pending_registry_data` não é status de retorno
Ele aparece **uma única vez**, no preenchimento inicial, antes do primeiro `submit`. Nenhuma etapa posterior devolve a análise para esse status — em particular, a abertura de um feedback não o faz.
:::

---

### Webhooks {#webhooks}

O acompanhamento por webhook é a forma recomendada de seguir a análise — a alternativa é consultar periodicamente **Busca informações do investidor**, o que não escala.

:::info Configuração
Os webhooks são configurados **internamente pela QI Tech**, por integração. Não há endpoint público de cadastro. Informe ao seu contato técnico a URL que deve receber as notificações e quais eventos deseja assinar.
:::

#### Eventos disponíveis

| Evento                                                | Quando dispara                                                                 |
|-------------------------------------------------------|----------------------------------------------------------------------------------|
| `investor_registry.investor_analysis_result`          | Resultado da análise automática — saída de `sent_to_analysis` para `automatically_approved`, `in_manual_analysis` ou `automatically_reproved` |
| `investor_registry.investor_analysis_status_change`   | Qualquer outra mudança de status da análise, incluindo as decisões manuais (`manually_approved`, `manually_reproved`) e a entrada em `pending_documents` |
| `investor_registry.feedback_status_change`            | **Abertura e encerramento de feedback** — ver **[Webhooks de feedback](#webhooks-feedback)** |
| `investor_registry.document_batch_status_change`      | A cada mudança de status do lote de documentos para assinatura                   |

#### Formato do evento — análise

Eventos de análise carregam a chave da análise e o novo status:

```json title='Webhook Body — análise'
{
    "webhook_type": "investor_registry.investor_analysis_status_change",
    "webhook_datetime": "2026-07-31T21:47:46Z",
    "data": {
        "investor_analysis_key": "UUID",
        "status": "in_compliance_analysis"
    }
}
```

#### Webhooks de feedback {#webhooks-feedback}

O `investor_registry.feedback_status_change` é o **único** aviso de que um feedback foi aberto ou encerrado. Como a análise permanece em `in_compliance_analysis` durante todo o ciclo do feedback, nenhum evento de análise é disparado junto — quem não assinar este evento não fica sabendo do pedido.

O mesmo `webhook_type` cobre as duas pontas do ciclo, diferenciadas pelo campo `status`:

| `status` | Quando dispara                                                     | Ação esperada de você                                    |
|----------|---------------------------------------------------------------------|-----------------------------------------------------------|
| `open`   | A compliance abriu um feedback com um pedido de esclarecimento      | Ler o pedido e **responder** com [Enviar Mensagem em Feedback](./feedback/enviar_mensagem_feedback) |
| `closed` | O feedback foi encerrado pela sua resposta                          | Nenhuma — é a confirmação de que o pedido foi resolvido    |

**Abertura do feedback:**

```json title='Webhook Body — feedback aberto'
{
    "webhook_type": "investor_registry.feedback_status_change",
    "webhook_datetime": "2026-07-31T21:47:46Z",
    "data": {
        "investor_analysis_key": "UUID",
        "feedback_key": "UUID",
        "status": "open",
        "origin_type": "investor_analysis",
        "origin_key": "UUID"
    }
}
```

**Encerramento do feedback**, disparado logo após a sua mensagem:

```json title='Webhook Body — feedback encerrado'
{
    "webhook_type": "investor_registry.feedback_status_change",
    "webhook_datetime": "2026-07-31T22:12:03Z",
    "data": {
        "investor_analysis_key": "UUID",
        "feedback_key": "UUID",
        "status": "closed",
        "origin_type": "investor_analysis",
        "origin_key": "UUID"
    }
}
```

| Campo                   | Tipo   | Descrição                                                                          |
|-------------------------|--------|--------------------------------------------------------------------------------------|
| `investor_analysis_key` | string | Análise cadastral à qual o feedback pertence                                        |
| `feedback_key`          | string | Identificador do feedback                                                            |
| `status`                | string | `open` ou `closed` — enumerador de **[Feedback Status](./feedback/listar_feedbacks#feedback-status)** |
| `origin_type`           | string | Enumerador de **[Origin Type](./feedback/listar_feedbacks#origin-type)** — `investor_analysis` ou `related_party_analysis` |
| `origin_key`            | string | Chave da entidade de origem: a `investor_analysis_key` ou a `external_related_party_key` |

O evento carrega apenas as chaves e o novo status — **não traz o texto do pedido**. Ao receber um `open`, chame [Listar Feedbacks](./feedback/listar_feedbacks) com o `origin_type` e o `origin_key` do evento para ler a `description` e o histórico de `messages`.

:::tip Os eventos que exigem ação sua
Assine, no mínimo, `investor_analysis_result`, `investor_analysis_status_change` e `feedback_status_change`. Juntos, eles cobrem as três situações da seção **[Quando o cadastro precisa da sua ação](#quando-agir)**: a recusa automática chega no primeiro; a recusa manual e a ida para assinatura, no segundo; o pedido de esclarecimento, no terceiro — e **só** no terceiro.
:::

---

# Consultar Análise em Andamento

URL: /documentation/iaas/investidor/compartilhado/consultar_analise_em_andamento

---
### Introdução
Este recurso retorna a **análise cadastral em andamento** (não finalizada) associada a um investidor. Útil para retomar um cadastro em progresso sem precisar conhecer a `investor_analysis_key`.

Considera-se "em andamento" qualquer análise cujo status ainda não tenha sido finalizado (criada, pendente de dados/documentos, enviada para análise, em análise manual).

### Request

ENDPOINT `/investor_registry/investor/{investor_key}/in_progress_investor_analysis`
MÉTODO `GET`
STATUS `200`

### Response
A análise cadastral em andamento é retornada no corpo da resposta. Para o formato completo, consulte **Busca informações de uma análise cadastral do investidor**.

---

# Adicionar Conta Bancária

URL: /documentation/iaas/investidor/compartilhado/contas_bancarias/adicionar_contas_bancarias

---

### Request

ENDPOINT /investor_registry/investor/\{investor_key\}/bank_account
MÉTODO POST
STATUS 201

### Request body
```json title='Request Body'
{
    "financial_institution_code": "329",
    "account_number": "000000",
    "account_digit": "0",
    "account_branch": "000"
}
```

### Body params
| Campo                             | Tipo     | Descrição                                                                    | Caracteres   | Obrigatório |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `financial_institution_code`                            | string   | Código da Instituição Financeira                                                           |   1  - 4   |    Sim      |
| `account_number`                 | string   | Número de Conta                                                                  |   1 - 20    |    Sim      |
| `account_digit`                     | string   | Dígito de Conta                                |      1       |    Sim      |
| `account_branch`                           | string   | Agência                                                                       |   1  - 4   |    Sim      |

### Response
```json title='Response Body'
{
    "bank_account_key": "UUID",
    "external_bank_account_key": "UUID",
    "status": "active"
}
```

| Campo                       | Tipo   | Descrição                                                                                 |
|-----------------------------|--------|----------------------------------------------------------------------------------------------|
| `bank_account_key`          | string | Identificador interno da conta bancária criada                                              |
| `external_bank_account_key` | string | Chave usada nas rotas de manutenção da conta                                                |
| `status`                    | string | Status da conta na criação — sempre `active`                                                |

### Erros Tratáveis
| Código                             | Significado     |
|------------------------------------|-----------------|
"IVR000077" | Essa conta já foi cadastrada para o investidor |

---

# Atualizar Conta Bancária

URL: /documentation/iaas/investidor/compartilhado/contas_bancarias/atualizar_conta_bancaria

---

### Request

ENDPOINT /investor_registry/investor/\{investor_key\}/bank_account/\{bank_account_key\}/update
MÉTODO PUT
STATUS 204

### Request body
```json title='Request Body'
{
    "status": "str",
    "main_account": true,
}
```

:::warning Atenção
    Existem três formas de atualizar a conta bancária:
- Atualizar o *status* para inactive , desativando o uso da conta.
- Atualizar o *status* para active , reativando o uso da conta.
- Atualizar a definição de conta principal utilizando a propriedade *main_account* , tornando a conta em questão a principal do investidor.

    Caso sejam enviados ambos os parâmetros, um erro será retornado.
:::

### Body params
| Campo                             | Tipo     | Descrição                                                                    | Caracteres   | Obrigatório |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `status`                            | string   | Novo Status da Conta                                                           |   1 - 20   |    Não      |
| `main_account`                            | bool   | Define se a conta é a principal do investidor |   -   |    Não      |

---

# Atualizar Status da Conta Bancária

URL: /documentation/iaas/investidor/compartilhado/contas_bancarias/atualizar_status_conta_bancaria

---
### Introdução
Este recurso altera o status de uma conta bancária previamente cadastrada em uma análise cadastral — por exemplo, para inativar uma conta que não deve mais ser utilizada.

A conta é identificada pela sua chave externa (`external_bank_account_key`), retornada na criação.

### Request

ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/bank_account/{external_bank_account_key}/status`
MÉTODO `PUT`
STATUS `202`

### Request body
```json title='Request Body'
{
    "status": "inactive"
}
```

### Body params
| Campo    | Tipo   | Descrição                                                     | Obrigatório |
|----------|--------|---------------------------------------------------------------|-------------|
| `status` | string | Novo status da conta. Valores típicos: `active`, `inactive`   |    Sim      |

### Response
`202 Accepted`. A representação atualizada da conta é retornada no corpo.

---

# Consultar Contas Bancárias

URL: /documentation/iaas/investidor/compartilhado/contas_bancarias/buscar_contas_bancarias

---

### Request

ENDPOINT /investor/investor/INVESTOR_KEY/bank_accounts
MÉTODO GET
STATUS 200

### Query params
| Campo                             | Tipo     | Descrição                                                                    | Opções   | Obrigatório |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `status`                            | string   | Novo Status da Conta                                                           |   "active" ou "inactive"   |    Não      |
| `main_account`                            | bool   | Define se a conta é a principal do investidor |   True ou False   |    Não      |

### Responses

```json
{
    "data": [
        {
            "bank_account_key": "UUID4",
            "financial_institution_code": "329",
            "account_number": "00000000",
            "account_digit": "0",
            "account_branch": "0001",
            "main_account": true,
            "status": "active"
        },
        {
            "bank_account_key": "UUID4",
            "financial_institution_code": "329",
            "account_number": "00000000",
            "account_digit": "0",
            "account_branch": "0001",
            "main_account": false,
            "status": "inactive"
        }
    ],
    "limit": 50,
    "page": 0,
    "is_last_page": true
}
```

---

# Definir Conta Bancária Principal

URL: /documentation/iaas/investidor/compartilhado/contas_bancarias/definir_conta_principal

---
### Introdução
Este recurso define (ou remove) uma conta bancária como **conta principal** do investidor dentro de uma análise cadastral. Apenas **uma** conta pode estar marcada como principal por vez — ao marcar uma como principal, a conta anteriormente principal é automaticamente desmarcada.

### Request

ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/bank_account/{external_bank_account_key}/default`
MÉTODO `PUT`
STATUS `202`

### Request body
```json title='Request Body'
{
    "value": true
}
```

### Body params
| Campo   | Tipo    | Descrição                                       | Obrigatório |
|---------|---------|-------------------------------------------------|-------------|
| `value` | boolean | `true` para definir esta conta como principal   |    Sim      |

### Response
`202 Accepted`. A representação atualizada da conta é retornada no corpo.

---

# Enviar Conta Bancária do Investidor

URL: /documentation/iaas/investidor/compartilhado/contas_bancarias/enviar_contas_bancarias

---
### Introdução
Este recurso cadastra uma conta bancária para o investidor dentro de uma análise cadastral. **Cada conta deve ser enviada em uma requisição independente** — para cadastrar mais de uma conta, chame o endpoint múltiplas vezes.

### Input / Output

Como ***input*** envie os dados de uma conta bancária.

Como ***output*** serão retornadas as chaves da conta criada — `bank_account_key` e `external_bank_account_key` — e o seu `status`.

### Request

ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/bank_account`
MÉTODO `POST`
STATUS `201`

### Request body

Exemplo: conta principal individual

```json title='Request Body'
{
    "financial_institution_code": "341",
    "account_number": "12345678",
    "account_digit": "9",
    "account_branch": "0001",
    "main_account": true
}
```

Exemplo: conta conjunta

```json title='Request Body'
{
    "financial_institution_code": "341",
    "account_number": "12345678",
    "account_digit": "9",
    "account_branch": "0001",
    "shared_account_owners": [
        {
            "name": "Maria Silva",
            "document_number": "068.045.160-95"
        }
    ]
}
```

### Body params
| Campo                        | Tipo    | Descrição                                                                       | Caracteres | Obrigatório |
|------------------------------|---------|---------------------------------------------------------------------------------|------------|-------------|
| `financial_institution_code` | string  | Código da instituição financeira (compe / ISPB curto)                           |   1 - 4    |    Sim      |
| `account_number`             | string  | Número da conta bancária (apenas dígitos)                                       |   1 - 20   |    Sim      |
| `account_digit`              | string  | Dígito verificador da conta                                                     |     1      |    Sim      |
| `account_branch`             | string  | Número da agência (4 dígitos)                                                   |     4      |    Sim      |
| `main_account`               | boolean | Indica se é a conta principal do investidor                                     |     -      |    Não      |
| `shared_account_owners`      | array   | Lista de objetos de **[Shared Account Owner](#shared-account-owners)**          |     -      |    Não      |

:::info
Apenas uma conta pode ser marcada como `main_account: true`. Se nenhuma conta for marcada como principal, a primeira cadastrada é assumida como principal.
:::

### Shared Account Owners {#shared-account-owners}
| Campo             | Tipo   | Descrição                                                                  | Caracteres | Obrigatório |
|-------------------|--------|----------------------------------------------------------------------------|------------|-------------|
| `name`            | string | Nome do co-titular da conta                                                |     -      |    Sim      |
| `document_number` | string | CPF do co-titular (`XXX.XXX.XXX-XX`)       |  14  |    Sim      |

### Response

```json title='Response Body'
{
    "bank_account_key": "UUID",
    "external_bank_account_key": "UUID",
    "status": "active"
}
```

| Campo                       | Tipo   | Descrição                                                                                 |
|-----------------------------|--------|----------------------------------------------------------------------------------------------|
| `bank_account_key`          | string | Identificador interno da conta bancária criada                                              |
| `external_bank_account_key` | string | Chave usada nas **rotas de manutenção** da conta: atualizar dados, atualizar status e definir conta principal |
| `status`                    | string | Status da conta na criação — sempre `active`                                                |

---

# Criar investidor

URL: /documentation/iaas/investidor/compartilhado/criar_investidor

---

### Introdução
Este recurso tem como objetivo nos informar dados básicos para iniciar o cadastro de um **investidor**.

A criação de um investidor já dispara, em conjunto, a abertura de uma primeira **análise cadastral** vinculada a ele. Por isso, ao final desta chamada são retornadas duas chaves: ***investor_key*** (identifica o investidor) e ***investor_analysis_key*** (identifica a análise cadastral em andamento).

Os tipos de investidor são definidos pelo campo **`person_type`**: **pessoa física** (`natural_person`), **pessoa jurídica** (`legal_person`) e **por conta e ordem** (`nominee`). O campo **`investor_sub_type`** distingue subtipos como **fundo de investimento** (`fund_class`), que possuem regras próprias ao longo do fluxo de cadastro.

:::info Regra de aprovação em Homologação
No ambiente de Homologação, temos a seguinte regra para aprovações: CPF/CNPJ com início **1**: reprovação automática; CPF/CNPJ com início **8**: pendente de validação manual; o restante é aprovado automaticamente.

Essa regra é **exclusiva do ambiente de Homologação**. Em Produção não há qualquer comportamento equivalente: toda análise passa pelo fluxo real de compliance.
:::

### Input / Output

Como ***input*** envie os dados básicos do investidor. Os campos obrigatórios variam de acordo com **`person_type`** e **`investor_sub_type`**.

Como ***output*** serão retornadas a ***investor_key*** e a ***investor_analysis_key***. A ***investor_key*** identifica o investidor; a ***investor_analysis_key*** identifica a análise cadastral aberta junto com a criação. Um mesmo investidor pode possuir mais de uma análise cadastral ao longo do tempo (renovações, atualizações).

### Request

ENDPOINT `/investor_registry/investor`
MÉTODO `POST`
STATUS `201`

### Request body

Caso 01: Pessoa Física

```json title='Request Body'
{
    "name": "João da Silva",
    "document_number": "123.456.789-00",
    "person_type": "natural_person",
    "email": "joao.silva@example.com",
    "phone": {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "987654321"
    }
}
```

Caso 02: Pessoa Jurídica

```json title='Request Body'
{
    "name": "Empresa XPTO Ltda",
    "document_number": "12.345.678/0001-90",
    "person_type": "legal_person",
    "investor_sub_type": "default",
    "registry_user": {
        "name": "José da Silva",
        "document_number": "123.456.789-00",
        "email": "jose.silva@example.com",
        "phone": {
            "international_dial_code": "55",
            "area_code": "11",
            "number": "987654321"
        }
    }
}
```

:::warning Campos obrigatórios por `person_type`
Os campos obrigatórios mudam de acordo com o **`person_type`**. A ausência de qualquer um deles é recusada com `IVR000009`, cuja mensagem lista a relação completa exigida.

- **`natural_person`**: `name`, `document_number`, `person_type`, **`investor_sub_type`**
- **`legal_person`**: `name`, `document_number`, `person_type`, **`investor_sub_type`**
- **`nominee`**: `name`, `person_type`, `external_distribution_key`

**`investor_sub_type` é obrigatório também para pessoa física** — envie `default` quando não houver subtipo específico. `email` e `phone` são opcionais para um distribuidor, mas recomendados: sem `email`, nenhum usuário de acesso é criado para o investidor.
:::

:::info Sobre o `registry_user`
O **`registry_user`** representa o usuário (pessoa física) responsável por preencher os dados cadastrais do investidor. Para **pessoa física**, normalmente este usuário é o próprio investidor e o campo pode ser omitido. Para **pessoa jurídica**, é o representante que responderá pelo preenchimento.

Quando enviado, o objeto exige `name`, `document_number` e `email`. Se omitido em pessoa física, o usuário é derivado do `email` do próprio investidor — e, se o investidor também não tiver `email`, nenhum usuário é criado.
:::

:::warning `investor_owner_type` não é aceito de distribuidores
O campo `investor_owner_type` existe no schema, mas é **recusado** quando o investidor é criado por uma integração de distribuidor com `person_type` `natural_person` ou `legal_person`. Vínculos de carteira administrada e de fundo são estabelecidos pelo endpoint **Criar Investor Owner**, dentro da análise cadastral.
:::

### Investidor não residente {#nao-residente}

A residência é definida **na criação do investidor** e é imutável depois disso. Ela é controlada pelo campo `resident`.

```json title='Request Body — pessoa física não residente'
{
    "name": "Maria Fernandes",
    "document_number": "123.456.789-00",
    "person_type": "natural_person",
    "investor_sub_type": "default",
    "resident": false,
    "non_resident_type": "third_party_representation",
    "investor_owners": [
        {
            "type": "non_resident_representative",
            "name": "Representante Legal Brasil Ltda",
            "document_number": "12.345.678/0001-90"
        }
    ]
}
```

| Campo                | Tipo    | Descrição                                                                                          | Obrigatório |
|----------------------|---------|-----------------------------------------------------------------------------------------------------|-------------|
| `resident`           | boolean | Define a residência da análise cadastral. Default `true`                                             |    Não      |
| `non_resident_type`  | string  | `self_representation` ou `third_party_representation`. Obrigatório quando `resident: false` (`IVR000222`) | Condicional |
| `investor_owners`    | array   | Representante legal residente no Brasil, com `type: "non_resident_representative"`                   |    Não      |

#### Tipos de representação {#non-resident-type}

`non_resident_type` declara **como o investidor não residente é representado no Brasil**. É essa escolha que determina quais entidades você precisa cadastrar e quais documentos serão exigidos no envio para análise.

| Enumerador                   | Tipo de conta                                    | Significado                                                                                                              |
|------------------------------|--------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
| `third_party_representation` | Conta **4373**                                   | O INR opera por meio de terceiros: existe um **custodiante**, responsável pela guarda dos ativos, e um **representante legal brasileiro**, responsável por representá-lo no país. Na prática, costumam ser a mesma entidade. |
| `self_representation`        | Conta **CNR** (autocustódia / representação tributária) | O investidor é seu próprio custodiante e representante. **Não** existe custodiante nem representante terceiro.        |

O que muda entre os dois:

|                              | `third_party_representation`                                                                 | `self_representation`          |
|------------------------------|-----------------------------------------------------------------------------------------------|--------------------------------|
| **Custodiante**              | Parte relacionada do tipo `asset_custodian`                                                    | Não existe                     |
| **Representante**            | Investor owner do tipo `non_resident_representative` — sempre **residente**, com CPF/CNPJ      | Não existe                     |
| **Documentos de representação** | `custody_contract` (no custodiante) **e** `representation_contract` (no representante) — **ou** uma única `simplified_declaration` na análise | Nenhum                     |

:::warning Como a exigência documental é verificada
Em `third_party_representation`, o `custody_contract` só é reconhecido quando enviado em uma parte relacionada **ativa** do tipo `asset_custodian`, e o `representation_contract` só é reconhecido quando enviado em um investor owner **ativo** do tipo `non_resident_representative`. Enviar os dois contratos como documentos da análise cadastral não satisfaz a regra.

Se a combinação não for encontrada no `submit`, a resposta é `IVR000029`.
:::

Regras que valem para **os dois** tipos:

- `nif_number` é **obrigatório** no envio dos dados cadastrais (`IVR000224`);
- parte relacionada estrangeira sem CPF/CNPJ precisa de `passport` ou `foreign_id`;
- pessoa física nascida no Brasil (`natural_person.place_of_birth.country: "BRA"`) precisa de `final_departure_tax_return`.

:::info `non_resident_type` é imutável
O valor é fixado na criação do investidor. Você pode reenviá-lo nos dados cadastrais, mas apenas com o **mesmo** valor — divergência, ou envio em um cadastro residente, resulta em `IVR000225`.
:::

:::warning Residência e endereço precisam concordar
Com `resident: true` (default), o endereço enviado na etapa de endereço precisa ter `country: "BRA"`, senão `IVR000227`. Com `resident: false`, o `country` **não** pode ser `BRA`, senão `IVR000226`.
:::

### Body params
| Campo                       | Tipo     | Descrição                                                                                   | Caracteres   | Obrigatório |
|-----------------------------|----------|---------------------------------------------------------------------------------------------|--------------|-------------|
| `name`                      | string   | Nome (ou razão social) do investidor                                                        |   1 - 255    |    Sim      |
| `person_type`               | string   | Enumerador de **[Person Type](#person-type)**                                               |      -       |    Sim      |
| `investor_sub_type`         | string   | Enumerador de **[Investor Sub Type](#investor-sub-type)**. Exigido para `natural_person` e `legal_person` |      -       |    Sim      |
| `document_number`           | string   | CPF (`XXX.XXX.XXX-XX`) ou CNPJ (`XX.XXX.XXX/XXXX-XX`). Não exigido para `nominee`           |   14 ou 18   |    Sim*     |
| `external_distribution_key` | string   | Chave da distribuição externa. Exigido apenas para `nominee`                                |   1 - 100    |    Sim*     |
| `resident`                  | boolean  | Residência da análise cadastral. Default `true`. Veja [Investidor não residente](#nao-residente) |      -       |    Não      |
| `non_resident_type`         | string   | `self_representation` ou `third_party_representation`. Exigido quando `resident: false`     |      -       | Condicional |
| `investor_owners`           | array    | Representante legal residente, para investidor não residente                                |      -       |    Não      |
| `email`                     | string   | E-mail do investidor                                                                        |   1 - 255    |    Não      |
| `phone`                     | object   | Objeto de **[Phone](#phone)**                                                               |      -       |    Não      |
| `registry_user`             | object   | Objeto de **[Registry User](#registry-user)**                                               |      -       |    Não      |
| `external_id`               | string   | Identificador do investidor no seu sistema                                                  |   1 - 50     |    Não      |

### Phone
| Campo                       | Tipo     | Descrição                                                                                   | Caracteres   | Obrigatório |
|-----------------------------|----------|---------------------------------------------------------------------------------------------|--------------|-------------|
| `international_dial_code`   | string   | Código internacional (ex.: `55`)                                                            |   1 - 3      |    Sim      |
| `area_code`                 | string   | DDD                                                                                         |      2       |    Sim      |
| `number`                    | string   | Número do telefone                                                                          |   8 - 9      |    Sim      |

### Registry User
| Campo               | Tipo     | Descrição                                            | Caracteres   | Obrigatório |
|---------------------|----------|------------------------------------------------------|--------------|-------------|
| `name`              | string   | Nome do usuário cadastrador                          |   1 - 255    |    Sim      |
| `document_number`   | string   | CPF do usuário (formato `XXX.XXX.XXX-XX`)            |     14       |    Sim      |
| `email`             | string   | E-mail do usuário                                    |   1 - 255    |    Sim      |
| `phone`             | object   | Objeto de **[Phone](#phone)**                        |      -       |    Sim      |

### Person Type {#person-type}
| Enumerador          | Descrição                                            |
|---------------------|------------------------------------------------------|
| `natural_person`    | Pessoa física                                        |
| `legal_person`      | Pessoa jurídica                                      |
| `nominee`           | Por conta e ordem (PCO)                              |

:::info Cadastro `nominee` (PCO)
O fluxo por conta e ordem precisa ser previamente habilitado e acordado para uso em Produção. Fale com seu contato comercial antes de planejar a integração desse caso.
:::

### Investor Sub Type {#investor-sub-type}
| Enumerador               | Descrição                                                                                  |
|--------------------------|--------------------------------------------------------------------------------------------|
| `default`                | Investidor regular, pessoa física ou jurídica                                              |
| `fund_class`             | Fundo de investimento. Possui regras próprias de partes relacionadas, documentos e investor owners |
| `financial_institution`  | Instituição financeira. Segue as mesmas regras de `default`                                |
| `non_resident`           | Subtipo de classificação. **Não** define a residência da análise — para isso use `resident` |

### Response
```json title='Response Body'
{
    "investor_key": "UUID",
    "investor_analysis_key": "UUID"
}
```

---

# Definir Grupo de Assinantes Padrão

URL: /documentation/iaas/investidor/compartilhado/definir_grupo_assinantes_padrao

---
### Introdução
Este recurso define (ou remove) um grupo de assinantes como **grupo padrão** da análise cadastral. Apenas **um** grupo pode estar marcado como padrão por vez — ao marcar um grupo como padrão, o grupo anteriormente padrão é automaticamente desmarcado.

O grupo padrão é o utilizado por default na geração dos documentos para assinatura, caso a análise seja submetida sem informar explicitamente um `external_signer_group_key`.

### Request

ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/signer_group/{external_signer_group_key}/default`
MÉTODO `PUT`
STATUS `202`

### Request body
```json title='Request Body'
{
    "value": true
}
```

### Body params
| Campo   | Tipo    | Descrição                                  | Obrigatório |
|---------|---------|--------------------------------------------|-------------|
| `value` | boolean | `true` para definir este grupo como padrão |    Sim      |

### Response
`202 Accepted`. A representação atualizada do grupo é retornada no corpo.

---

# Enviar Cadastro do Investidor para Análise

URL: /documentation/iaas/investidor/compartilhado/enviar_cadastro_para_analise

---
### Introdução
Este recurso submete a **análise cadastral** preenchida para validação. A partir desse momento, os dados são enviados aos serviços de compliance e os documentos são gerados para assinatura.

:::warning Atenção
A **análise cadastral** ocorre de forma assíncrona. Recomendamos integrar com os **webhooks** de mudança de status para acompanhar a evolução — veja **[Ciclo de vida da análise cadastral](./ciclo_de_vida_da_analise)**.
:::

### Pré-requisitos {#pre-requisitos}

O `submit` só é aceito quando a análise já reúne todos os dados abaixo. Estes são os erros mais comuns nesta etapa, e a validação é feita **em sequência** — cada recusa pode estar escondendo a próxima pendência, então vale conferir a lista inteira antes de reenviar.

#### 1. Blocos de dados obrigatórios

Faltando qualquer um, a recusa é `IVR000150`, cuja mensagem lista exatamente as chaves ausentes.

| Investidor                              | Blocos exigidos                                              |
|-----------------------------------------|---------------------------------------------------------------|
| `natural_person`                        | `natural_person`, `address`, `net_worth`, **`suitability`**   |
| `legal_person` (`default`, `financial_institution`) | `legal_person`, `address`, `net_worth`            |
| `legal_person` / `fund_class`           | **Nenhum** — ver abaixo                                       |

:::info Classes de fundo não têm blocos obrigatórios
Para `legal_person` / `fund_class`, os dados cadastrais, o endereço e o patrimônio são preenchidos automaticamente a partir da base pública da CVM no próprio `submit`. Suitability, grupos de assinantes e documentos do investidor também **não** são exigidos.

A única exigência condicional é a de **partes relacionadas**, e apenas quando a classe é **exclusiva** na CVM — ver o item 3 abaixo. Se o CNPJ não constar na base da CVM, o enriquecimento não acontece e o `submit` é recusado com `IVR000068`.
:::

#### 2. Suitability

- **Pessoa física**: sempre obrigatória. Sem ela, `IVR000150` acusa a chave `suitability` faltante
- **Pessoa jurídica `retail`**: obrigatória — a ausência é recusada com `IVR000133`
- **Pessoa jurídica `qualified` ou `professional`**: opcional
- **Classe de fundo (`fund_class`)**: não se aplica — a etapa é pulada

#### 3. Partes relacionadas e participação societária

Quantidade mínima, exigência de representante legal e percentual somado variam por tipo de investidor. A tabela completa está em **[Criar Parte Relacionada — Exigências por tipo de investidor](./related_party/criar_parte_relacionada#exigencias)**.

#### 4. Documentos

A matriz de documentos obrigatórios é validada aqui, e não no upload — ver a seção **Documentos Obrigatórios** na página **Enviar Documento do Investidor**. As recusas são `IVR000029` (documentos do investidor) e `IVR000030` (documentos de parte relacionada), ambas devolvendo na mensagem a matriz de opções aceitas.

Para `fund_class` **não há matriz de documentos do investidor**. Só podem ser cobrados documentos de **parte relacionada**, e apenas em classe exclusiva.

#### 5. Investor owners (apenas `fund_class`)

Uma classe de fundo precisa de um **administrador** e uma **gestora** ativos. Eles são criados **automaticamente** a partir dos dados da CVM no `submit`; o endpoint **Criar Investor Owner** cobre os vínculos adicionais. A ausência é recusada com `IVR000164` (administrador) ou `IVR000163` (gestora).

#### 6. Classe em funcionamento (apenas `fund_class`)

Somente classes **operacionais** na CVM são aceitas. Classes pré-operacionais, encerradas, canceladas ou incorporadas são recusadas na análise.

### Input / Output

O corpo é **opcional** — pode ser enviado vazio (`null` ou `{}`). Quando enviado, permite informar o método de assinatura e o grupo de assinantes que deverá ser utilizado para os documentos gerados.

Como ***output*** será retornada a representação atualizada da análise cadastral.

### Request

ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/submit`
MÉTODO `PUT`
STATUS `202`

### Request body

O corpo pode ser enviado vazio (`{}`) — neste caso a API utiliza o método de assinatura e o grupo de assinantes padrão da análise. Para sobrescrever esses valores, envie os campos opcionais abaixo.

```json title='Request Body'
{
    "signature_method": "certifiqi",
    "external_signer_group_key": "3f8a5a3e-1f0a-4d9b-8a6e-9b4c0e7d8f12"
}
```

### Body params
| Campo                       | Tipo   | Descrição                                                              | Obrigatório |
|-----------------------------|--------|------------------------------------------------------------------------|-------------|
| `signature_method`          | string | Enumerador de **[Signature Method](#signature-method)**                |    Não      |
| `external_signer_group_key` | string | Chave externa do grupo de assinantes a ser utilizado para esta análise |    Não      |

### Signature Method {#signature-method}

Os únicos valores que uma integração pode informar são:

| Enumerador          | Descrição                                                     |
|---------------------|----------------------------------------------------------------|
| `certifiqi`         | Assinatura eletrônica via CertifiQI                            |
| `qi_sign.liveness`  | Assinatura eletrônica com prova de vida                        |

:::info `opt_in` não é selecionável pela integração
`opt_in` é uma **configuração do distribuidor**, definida pela QI Tech na sua conta, e não um valor a ser enviado neste corpo. Se a sua conta estiver configurada como `opt_in`, o fluxo de assinatura é resolvido automaticamente e não é necessário informar `signature_method`.
:::

### Response
A análise cadastral atualizada é retornada no corpo da resposta.

---

# Enviar Dados Cadastrais do Investidor

URL: /documentation/iaas/investidor/compartilhado/enviar_dados_cadastrais

---
### Introdução
Este recurso tem como objetivo enviar os dados cadastrais específicos da pessoa que compõe a **análise cadastral** de um investidor.

O corpo enviado deve conter **um** dos blocos `natural_person` ou `legal_person`, coerente com o `person_type` informado na criação do investidor.

### Input / Output

Como ***input*** envie os dados cadastrais específicos do tipo de investidor.

Como ***output*** será retornada a representação atualizada da análise cadastral. As chaves ***investor_key*** e ***investor_analysis_key*** identificam o investidor e a análise atualizada.

:::info Investidor `fund_class`
Para classes de fundo (`investor_sub_type: "fund_class"`), esta etapa é **obrigatória** — envie o bloco `legal_person` com os dados de contato e, quando aplicável, o `giin_number`.

Razão social, data de constituição e patrimônio **não precisam ser enviados**: são preenchidos automaticamente a partir da base da CVM ao enviar a análise para validação.
:::

### Request

ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/registry_data`
MÉTODO `PUT`
STATUS `202`

### Request body

Exemplo: Pessoa Física

```json title='Request Body'
{
    "name": "João da Silva",
    "email": "joao.silva@example.com",
    "phone": {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "987654321"
    },
    "natural_person": {
        "birthdate": "1990-05-15",
        "gender": "male",
        "mother_name": "Maria da Silva",
        "nationality": "BRA",
        "place_of_birth": {
            "country": "BRA",
            "uf": "SP",
            "city": "São Paulo"
        },
        "marital_status": "single",
        "spouse": {
            "name": "Maria Santos",
            "document_number": "123.456.789-00"
        },
        "profession": "Engenheiro",
        "occupation": "Engenheiro de Software",
        "occupation_company": {
            "name": "Empresa XYZ Ltda",
            "document_number": "12.345.678/0001-90"
        }
    }
}
```

Exemplo: Pessoa Jurídica

```json title='Request Body'
{
    "name": "Empresa XPTO Ltda",
    "email": "contato@empresaxpto.com.br",
    "phone": {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "1234567890"
    },
    "legal_person": {
        "legal_name": "Empresa XPTO Limitada",
        "constitution_date": "2020-01-15"
    }
}
```

Exemplo: Pessoa Jurídica (`fund_class`)

```json title='Request Body'
{
    "name": "Empresa XPTO Ltda",
    "email": "contato@empresaxpto.com.br",
    "phone": {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "1234567890"
    },
    "legal_person": {
        "giin_number": "XXXXXX.XXXXX.XX.XXX",
    }
}
```

### Body params
| Campo             | Tipo     | Descrição                                                                            | Caracteres | Obrigatório |
|-------------------|----------|--------------------------------------------------------------------------------------|------------|-------------|
| `name`            | string   | Nome (ou razão social) do investidor                                                 |   1 - 255  |    Não      |
| `email`           | string   | E-mail de contato                                                                    |   1 - 255  |    Não      |
| `phone`           | object   | Objeto de **[Phone](#phone)**                                                        |     -      |    Não      |
| `natural_person`  | object   | Objeto de **[Natural Person](#natural-person)** — obrigatório para pessoa física     |     -      |    Sim*     |
| `legal_person`    | object   | Objeto de **[Legal Person](#legal-person)** — obrigatório para pessoa jurídica       |     -      |    Sim*     |

\* É obrigatório enviar **exatamente um** entre `natural_person` ou `legal_person`, de acordo com o `person_type` do investidor.

### Natural Person {#natural-person}
| Campo                  | Tipo   | Descrição                                                       | Caracteres | Obrigatório |
|------------------------|--------|-----------------------------------------------------------------|------------|-------------|
| `birthdate`            | string | Data de nascimento (`YYYY-MM-DD`)                               |     10     |    Sim      |
| `mother_name`          | string | Nome completo da mãe                                            |   1 - 255  |    Sim      |
| `nationality`          | string | Nacionalidade — código ISO de 3 letras (ex.: `BRA`)             |      3     |    Sim      |
| `place_of_birth`       | object | Objeto de **[Place of Birth](#place-of-birth)**                 |     -      |    Sim      |
| `marital_status`       | string | Enumerador de **[Marital Status](#marital-status)**             |     -      |    Sim      |
| `profession`           | string | Profissão                                                       |   1 - 255  |    Sim      |
| `occupation`           | string | Ocupação                                                        |   1 - 255  |    Sim      |
| `gender`               | string | Enumerador de **[Gender](#gender)**                             |     -      |    Não      |
| `spouse`               | object | Objeto de **[Spouse](#spouse)**                                 |     -      |    Não      |
| `occupation_company`   | object | Objeto de **[Occupation Company](#occupation-company)**         |     -      |    Não      |

### Gender {#gender}
| Enumerador | Descrição    |
|------------|--------------|
| `male`     | Masculino    |
| `female`   | Feminino     |

### Marital Status {#marital-status}
| Enumerador                                  | Descrição                                       |
|---------------------------------------------|-------------------------------------------------|
| `single`                                    | Solteiro(a)                                     |
| `married`                                   | Casado(a)                                       |
| `civil_union`                               | União estável                                   |
| `divorced`                                  | Divorciado(a)                                   |
| `widowed`                                   | Viúvo(a)                                        |
| `married_with_partial_community_property`   | Casado(a) em comunhão parcial de bens           |

### Place of Birth {#place-of-birth}
| Campo     | Tipo   | Descrição                                          | Caracteres | Obrigatório |
|-----------|--------|----------------------------------------------------|------------|-------------|
| `country` | string | Código ISO do país (3 letras, ex.: `BRA`)          |     3      |    Não      |
| `uf`      | string | Estado (UF)                                        |     -      |    Não      |
| `city`    | string | Cidade                                             |     -      |    Não      |

### Spouse {#spouse}
| Campo             | Tipo   | Descrição                                                            | Caracteres | Obrigatório |
|-------------------|--------|----------------------------------------------------------------------|------------|-------------|
| `name`            | string | Nome completo do cônjuge                                             |   1 - 255  |    Sim      |
| `document_number` | string | CPF do cônjuge (`XXX.XXX.XXX-XX`)    |   14 |    Sim      |

### Occupation Company {#occupation-company}
| Campo             | Tipo   | Descrição                                                  | Caracteres | Obrigatório |
|-------------------|--------|------------------------------------------------------------|------------|-------------|
| `name`            | string | Nome da empresa                                            |   1 - 255  |    Sim      |
| `document_number` | string | CNPJ da empresa (`XX.XXX.XXX/XXXX-XX`)                     |     18     |    Sim      |

### Legal Person {#legal-person}
| Campo               | Tipo   | Descrição                                                                | Caracteres | Obrigatório |
|---------------------|--------|--------------------------------------------------------------------------|------------|-------------|
| `legal_name`        | string | Razão social da empresa                                                  |   1 - 255  |    Não      |
| `constitution_date` | string | Data de constituição (`YYYY-MM-DD`)                                      |     10     |    Não      |
| `giin_number`       | string | GIIN (`Global Intermediary Identification Number`), quando aplicável     |   1 - 20   |    Não      |

### Phone {#phone}
| Campo                     | Tipo   | Descrição              | Caracteres | Obrigatório |
|---------------------------|--------|------------------------|------------|-------------|
| `international_dial_code` | string | Código internacional   |   1 - 3    |    Sim      |
| `area_code`               | string | DDD                    |     2      |    Sim      |
| `number`                  | string | Número de telefone     |   8 - 9    |    Sim      |

### Response
A análise cadastral atualizada é retornada no corpo da resposta. Para o formato completo, consulte **Busca informações de uma análise cadastral do investidor**.

---

---

# Enviar Documento Assinado

URL: /documentation/iaas/investidor/compartilhado/enviar_documento_assinado

---
### Introdução
Este recurso faz o **upload do arquivo assinado** de um documento gerado para a formalização do cadastro do investidor, dentro de um `document_batch`. Os tipos suportados são: ficha cadastral (pessoa física ou jurídica), termo de investidor qualificado e termo de investidor profissional.

Utilize este recurso quando o distribuidor é responsável por gerar e assinar o documento externamente (configuração `document_generation: external`) e precisa enviar o arquivo PDF/imagem final ao QI Tech. Para confirmar uma assinatura via *opt-in*, utilize **[Assinar Documento](/documentation/iaas/investidor/compartilhado/assinar_documento)**.

:::warning Atenção
Este recurso está disponível apenas para integrações que atuam como **Distribuidor** com `document_generation` configurado como `external`. O documento deve estar com status `pending_external_upload`.
:::

### Input / Output

Como ***input*** envie o conteúdo do arquivo codificado em **base64**.

Como ***output***, quando o envio finaliza o lote, é retornada a chave `investor_document_key`.

### Request

ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/document_batch/{document_batch_key}/document/{investor_document_key}/signed_document`
MÉTODO `POST`
STATUS `201`

### Request body

```json title='Request Body'
{
  "document_b64": "base64_encoded_document_content"
}
```

### Body params
| Campo          | Tipo   | Descrição                                              | Obrigatório |
|----------------|--------|--------------------------------------------------------|-------------|
| `document_b64` | string | Conteúdo do arquivo assinado codificado em **base64**  |    Sim      |

### Response
```json title='Response Body'
{
    "investor_document_key": "UUID"
}
```

---

# Enviar Endereço do Investidor

URL: /documentation/iaas/investidor/compartilhado/enviar_endereco

---
### Introdução
Este recurso tem como objetivo enviar o endereço que compõe a **análise cadastral** de um investidor.

:::info Classe de fundo (`fund_class`) — etapa pulada
Classes de fundo **não enviam endereço**. O endereço é herdado automaticamente do **administrador** vinculado à classe durante o envio para análise, e o `submit` não exige o bloco `address` para esse subtipo. Pule esta etapa.
:::

### Input / Output

Como ***input*** envie os dados de endereço.

Como ***output*** será retornada a representação atualizada da análise cadastral.

### Request

ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/address`
MÉTODO `PUT`
STATUS `202`

Exemplo

```json title='Request Body'
{
    "street": "Avenida Paulista",
    "number": "1000",
    "neighborhood": "Bela Vista",
    "city": "São Paulo",
    "postal_code": "01310-100",
    "uf": "SP",
    "country": "BRA",
    "complement": "Sala 1010"
}
```

### Body params
| Campo          | Tipo   | Descrição                                            | Caracteres | Obrigatório |
|----------------|--------|------------------------------------------------------|------------|-------------|
| `street`       | string | Logradouro                                           |   1 - 255  |    Sim      |
| `number`       | string | Número (somente dígitos)                             |   1 - 10   |    Sim      |
| `neighborhood` | string | Bairro                                               |   1 - 255  |    Sim      |
| `city`         | string | Cidade                                               |   1 - 255  |    Sim      |
| `postal_code`  | string | Código postal. No Brasil, CEP no formato `XXXXX-XXX`. No exterior, o formato local do país |   1 - 20   |    Sim      |
| `uf`           | string | Unidade Federativa — ex.: `SP`, `CE`, `MG`. No exterior, use `EX`  |   1 - 20   |    Sim      |
| `country`      | string | Código ISO do país, 3 letras — ex.: `BRA`, `PRT`     |     3      |    Sim      |
| `complement`   | string | Complemento                                          |   1 - 255  |    Não      |

### Endereço no exterior {#exterior}

`postal_code` e `uf` **não possuem validação de formato** — aceitam o padrão de qualquer país (até 20 caracteres cada). Um CEP português `1000-001` ou um ZIP norte-americano `10001` são aceitos como estão.

A única coerência exigida é entre a **residência da análise** e o `country`:

| `resident` da análise | `country` exigido       | Erro se divergir |
|-----------------------|-------------------------|------------------|
| `true` (default)      | obrigatoriamente `BRA`  | `IVR000227`      |
| `false`               | qualquer um, exceto `BRA` | `IVR000226`    |

:::warning Residência é definida na criação do investidor
`resident` **não** é um campo desta etapa e não pode ser alterado depois. Se você receber `IVR000227` ao enviar um endereço no exterior, a análise nasceu residente — é preciso criar o investidor com `resident: false` e `non_resident_type`, conforme a seção **Investidor não residente** da página **Criar Investidor**.
:::

### Response
A análise cadastral atualizada é retornada no corpo da resposta. Para o formato completo, consulte **Busca informações de uma análise cadastral do investidor**.

---

---

# Enviar Grupo de Assinantes

URL: /documentation/iaas/investidor/compartilhado/enviar_grupos_assinantes

---

### Introdução
Este recurso cadastra um **grupo de assinantes** que será responsável por assinar os documentos gerados na análise cadastral do investidor. **Cada grupo deve ser enviado em uma requisição independente** — para cadastrar mais de um grupo, chame o endpoint múltiplas vezes.

:::warning Atenção
Cada signatário enviado neste recurso será **validado contra os representantes legais** declarados em **[Criar Parte Relacionada](./related_party/criar_parte_relacionada.md)**. Portanto, todo `signer` deve **também** ser cadastrado previamente como parte relacionada com `legal_representative: true` (e, quando aplicável, `direct_beneficiary: true`). Signatários que não constarem entre os representantes legais da análise cadastral terão o cadastro recusado.
:::

:::info Classe de fundo (`fund_class`) — etapa pulada
Classes de fundo **não enviam grupos de assinantes**. A representação se dá pelos *investor owners* (administrador e gestora), e não por representantes legais — não há signatários a declarar. Pule esta etapa.
:::

### Input / Output

Como ***input*** envie a definição de um único grupo de assinantes.

Como ***output*** será retornada a representação do grupo criado.

### Request

ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/signer_group`
MÉTODO `POST`
STATUS `201`

### Request body

Exemplo

```json title='Request Body'
{
    "is_default": true,
    "minimum_required_signers": 2,
    "expiration_date": "2025-12-31",
    "signers": [
        {
            "name": "João Silva",
            "document_number": "123.456.789-00",
            "email": "joao.silva@example.com",
            "is_required_signer": true
        },
        {
            "name": "Maria Santos",
            "document_number": "987.654.321-00",
            "email": "maria.santos@example.com",
            "is_required_signer": true
        },
        {
            "name": "Pedro Oliveira",
            "document_number": "456.789.123-00",
            "email": "pedro.oliveira@example.com",
            "is_required_signer": false
        }
    ]
}
```

### Body params
| Campo                       | Tipo    | Descrição                                                                | Obrigatório |
|-----------------------------|---------|--------------------------------------------------------------------------|-------------|
| `is_default`                | boolean | Indica se este é o grupo padrão da análise                               |    Sim      |
| `minimum_required_signers`  | number  | Número mínimo de assinaturas necessárias (>= 1)                          |    Sim      |
| `signers`                   | array   | Lista de objetos de **[Signers](#signers)**                              |    Sim      |
| `expiration_date`           | string  | Data de expiração do grupo (`YYYY-MM-DD`)                                |    Não      |

### Signers {#signers}
| Campo                | Tipo    | Descrição                                                            | Caracteres | Obrigatório |
|----------------------|---------|----------------------------------------------------------------------|------------|-------------|
| `name`               | string  | Nome do signatário                                                   |   1 - 255  |    Sim      |
| `document_number`    | string  | CPF ou CNPJ do signatário                                            |  14 ou 18  |    Sim      |
| `email`              | string  | E-mail do signatário                                                 |     -      |    Sim      |
| `is_required_signer` | boolean | Indica se o signatário é obrigatório para considerar o grupo completo |     -      |    Sim      |

:::info Informação
- Apenas **um** grupo pode estar marcado como `is_default: true` por análise.
- `minimum_required_signers` deve ser menor ou igual ao total de signatários da lista.
- Pelo menos um signatário deve ter `is_required_signer: true`.
- Após `expiration_date`, o grupo não poderá mais ser utilizado para assinatura de documentos.
:::

### Response
O grupo de assinantes criado é retornado no corpo da resposta, incluindo a chave `external_signer_group_key`.

---

---

# Enviar Documento do Investidor

URL: /documentation/iaas/investidor/compartilhado/enviar_investor_document

---

### Introdução
Este recurso faz o upload de um documento que compõe a análise cadastral do investidor. Os documentos obrigatórios variam conforme o `person_type` e o `investor_sub_type` do investidor, bem como sua categoria (varejo, qualificado, profissional).

:::warning Atenção
- Este endpoint deve ser chamado **uma vez para cada documento** obrigatório
- A análise cadastral precisa estar no status `pending_registry_data`. Em outro status, a chamada é recusada com `IVR000026`
- Um mesmo `type` só aceita um envio bem-sucedido: veja [Reenvio e documento duplicado](#duplicado)
:::

:::info Classe de fundo (`fund_class`) — etapa pulada
Classes de fundo **não enviam documentos do investidor**. Não existe matriz de documentos obrigatórios para esse subtipo, e a ausência nunca bloqueia o `submit`. Pule esta etapa — ver **[Pessoa Jurídica — Fundo de Investimento](#fund-class)** abaixo.
:::

### Input / Output

Como ***input*** envie o conteúdo do arquivo em **base64**, o tipo do documento e a extensão.

Como ***output*** será retornada a representação do documento criado, identificado por `investor_analysis_document_key`, acompanhada da representação completa da análise cadastral à qual ele pertence.

### Request

ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/document`
MÉTODO `POST`
STATUS `201`

### Query params
| Campo   | Tipo    | Descrição                                                                                                                | Obrigatório |
|---------|---------|--------------------------------------------------------------------------------------------------------------------------|-------------|
| `force` | boolean | Se `true`, força o envio mesmo quando há validação prévia falha. O documento entra obrigatoriamente em análise manual.   |    Não      |

### Request body

Exemplo: CNH (Pessoa Física)

```json title='Request Body'
{
    "type": "cnh",
    "document_b64": "base64_encoded_document_content",
    "file_extension": "pdf",
    "document_data": {
        "document_type": "CNH",
        "issuer_entity": "DETRAN"
    }
}
```

Exemplo: RG (frente e verso)

```json title='Request Body — Frente'
{
    "type": "rg_front",
    "document_b64": "base64_encoded_document_content",
    "file_extension": "jpeg",
    "document_data": {
        "document_type": "RG",
        "issuer_entity": "SSP",
        "document_number": "20.932.206-8"
    }
}
```
```json title='Request Body — Verso'
{
    "type": "rg_back",
    "document_b64": "base64_encoded_document_content",
    "file_extension": "jpeg"
}
```

Exemplo: Cartão CNPJ (Pessoa Jurídica)

```json title='Request Body'
{
    "type": "cnpj_card",
    "document_b64": "base64_encoded_document_content",
    "file_extension": "pdf"
}
```

### Body params
| Campo            | Tipo   | Descrição                                                          | Caracteres | Obrigatório |
|------------------|--------|--------------------------------------------------------------------|------------|-------------|
| `type`           | string | Enumerador de **[Document Type](#document-type)**                  |     -      |    Sim      |
| `document_b64`   | string | Conteúdo do arquivo codificado em base64                           |     -      |    Sim      |
| `file_extension` | string | Extensão do arquivo. Valores aceitos: `pdf`, `jpeg`                |     -      |    Sim      |
| `document_data`  | object | Metadados livres do documento (ex.: número, órgão emissor)         |     -      |    Não      |
| `observation`    | string | Observação livre sobre o documento                                 |   até 500  |    Não      |

### Document Type {#document-type}

#### Identificação e comprovantes de pessoa física
| Enumerador                     | Descrição                                            | Extensões      |
|--------------------------------|------------------------------------------------------|----------------|
| `cnh`                          | CNH                                                  | `pdf`, `jpeg`  |
| `rg_front`                     | RG — frente                                          | `pdf`, `jpeg`  |
| `rg_back`                      | RG — verso                                           | `pdf`, `jpeg`  |
| `passport`                     | Passaporte (identificação de estrangeiro)            | `pdf`, `jpeg`  |
| `foreign_id`                   | Documento de identidade estrangeiro (ex.: RNE)       | `pdf`, `jpeg`  |
| `proof_of_residence`           | Comprovante de residência                            | `pdf`, `jpeg`  |
| `billing_statement`            | Fatura / extrato                                     | `pdf`, `jpeg`  |

#### Documentos societários de pessoa jurídica
| Enumerador                     | Descrição                                            | Extensões      |
|--------------------------------|------------------------------------------------------|----------------|
| `cnpj_card`                    | Cartão CNPJ                                          | `pdf`, `jpeg`  |
| `social_contract`              | Contrato social                                      | `pdf`, `jpeg`  |
| `company_statute`              | Estatuto                                             | `pdf`, `jpeg`  |
| `board_election_record`        | Ata de eleição estatutária                           | `pdf`, `jpeg`  |
| `financial_statements`         | Demonstrações financeiras                            | `pdf`, `jpeg`  |
| `organizational_chart`         | Organograma societário                               | `pdf`, `jpeg`  |

#### Representação, qualificação e contratos
| Enumerador                     | Descrição                                            | Extensões      |
|--------------------------------|------------------------------------------------------|----------------|
| `power_of_attorney`            | Procuração                                           | `pdf`, `jpeg`  |
| `investor_qualification_proof` | Comprovação de qualificação / enquadramento          | `pdf`, `jpeg`  |
| `wallet_manager_contract`      | Contrato de carteira administrada / intermediação    | `pdf`, `jpeg`  |
| `extra_document`               | Documento avulso, sem tipo específico                | `pdf`, `jpeg`  |

#### Investidor não residente
| Enumerador                     | Descrição                                            | Extensões      |
|--------------------------------|------------------------------------------------------|----------------|
| `custody_contract`             | Contrato de custódia                                 | `pdf`, `jpeg`  |
| `representation_contract`      | Contrato de representação                            | `pdf`, `jpeg`  |
| `simplified_declaration`       | Declaração simplificada                              | `pdf`, `jpeg`  |
| `final_departure_tax_return`   | Declaração final de saída definitiva do país         | `pdf`, `jpeg`  |

:::warning Tipos gerados pela QI Tech
Os tipos `qualified_investor_term`, `professional_investor_term`, `natural_person_registry_form`, `legal_person_registry_form`, `investor_suitability_form` e `adhesion_term` aparecem na consulta do investidor, mas são **gerados pela QI Tech** para assinatura — não devem ser enviados por este endpoint.
:::

### Documentos Obrigatórios {#documentos-obrigatorios}

As combinações abaixo são conjuntos alternativos: basta satisfazer **uma** das opções de cada lista. A validação roda no envio para análise (`submit`) e recusa com `IVR000029`, devolvendo na mensagem a matriz exata que faltou.

#### Pessoa Física (`natural_person`)
Uma das opções:

| Opção | Documentos                                       |
|-------|---------------------------------------------------|
| 1     | `cnh` **+** `proof_of_residence`                 |
| 2     | `rg_front` **+** `rg_back` **+** `proof_of_residence` |

#### Pessoa Jurídica (`legal_person` / `investor_sub_type: default`, `financial_institution`)
Uma das opções — sempre **ao menos um** documento societário **e** as demonstrações financeiras:

| Opção | Documentos                                            |
|-------|--------------------------------------------------------|
| 1     | `board_election_record` **+** `financial_statements`   |
| 2     | `company_statute` **+** `financial_statements`         |
| 3     | `social_contract` **+** `financial_statements`         |

O documento societário exigido depende do tipo jurídico da empresa — daí as três opções. Não é possível enviar apenas `financial_statements`.
:::warning Documentos obrigatórios
Embora esses documentos sejam o mínimo para envio de uma análise, caso, por exemplo, somente o `company_statute` não seja suficiente para definir firmas e poderes do cotista, a análise pode ser recusada exigindo também o `board_election_record`.
:::

#### Pessoa Jurídica — Classe de Fundo de Investimento (`investor_sub_type: fund_class`) {#fund-class}
**Nenhum documento é exigido — a etapa é pulada por completo.** Os dados da classe são obtidos por enriquecimento na base da CVM, e a representação é feita pelos investor owners (administrador e gestora).

Os únicos documentos que podem ser exigidos em um cadastro de classe de fundo são os das **partes relacionadas**, e apenas quando a classe é **exclusiva** na CVM — ver **[Enviar Documento da Parte Relacionada](./related_party/enviar_documento_parte_relacionada)**.

### Reenvio e documento duplicado {#duplicado}

Um tipo de documento é considerado **satisfeito** assim que existe, para aquela análise, um documento daquele tipo com status `valid` ou `in_manual_analysis`. A partir daí, novos envios do mesmo tipo são recusados:

```json
HTTP 409
{
  "title": "Already exists valid document for investor analysis.",
  "code": "IVR000023"
}
```

Enquanto **todos** os documentos de um tipo estiverem `invalid`, novos envios daquele tipo continuam sendo aceitos — é assim que se corrige um arquivo ilegível.

O tipo `extra_document` é a única exceção: aceita múltiplos envios sempre.

### Validação automática e `status` do documento {#validacao}

Documentos dos tipos `cnh`, `rg_front`, `rg_back` e `proof_of_residence` passam por validação automática (OCR) e voltam com um dos status abaixo. Os demais tipos entram diretamente em `in_manual_analysis`.

| Status              | Significado                                                                 |
|---------------------|------------------------------------------------------------------------------|
| `valid`             | Validado automaticamente                                                     |
| `in_manual_analysis`| Encaminhado para conferência humana                                          |
| `invalid`           | Reprovado na validação automática — reenvie, ou use `force=true`             |

`force=true` pula o efeito da reprovação automática: o documento é registrado como `in_manual_analysis` e passa a satisfazer a exigência do tipo.

:::info Sobre `investor_qualification_proof`
Este documento **não integra a matriz de obrigatórios** e sua ausência nunca bloqueia o `submit`. Ele atua depois: se o `total_financial_applications` declarado estiver abaixo do piso da categoria informada — R$ 1.000.000 para `qualified`, R$ 10.000.000 para `professional` — ele é utilizado para a validação. Investidores `fund_class` são isentos dessa verificação.
:::

### Response

```json title='Response Body'
{
    "investor_analysis_document_key": "UUID",
    "type": "cnh",
    "status": "in_manual_analysis",
    "observation": "Documento emitido em 2019, legibilidade reduzida no verso.",
    "data": {
        "type": "cnh",
        "file_extension": "pdf",
        "document_data": {
            "document_type": "CNH",
            "issuer_entity": "DETRAN"
        }
    },
    "investor_analysis": { }
}
```

| Campo                            | Tipo   | Descrição                                                                    |
|----------------------------------|--------|------------------------------------------------------------------------------|
| `investor_analysis_document_key` | string | Identificador do documento. É a chave usada nas demais rotas de documento     |
| `type`                           | string | Enumerador de **[Document Type](#document-type)**                             |
| `status`                         | string | `valid`, `invalid` ou `in_manual_analysis` — veja [Validação automática](#validacao) |
| `observation`                    | string | Observação enviada na requisição. `null` quando não informada                 |
| `data`                           | object | Eco dos campos enviados, sem o conteúdo em base64                             |
| `investor_analysis`              | object | Representação completa da análise cadastral — mesmo formato de **Busca informações de uma análise cadastral do investidor** |

---

# Enviar Patrimônio do Investidor

URL: /documentation/iaas/investidor/compartilhado/enviar_patrimonio

---
### Introdução
Este recurso registra as informações de patrimônio e enquadramento do investidor (varejo, qualificado ou profissional).

:::info Classe de fundo (`fund_class`) — etapa pulada
Classes de fundo **não enviam patrimônio**. Ele é calculado **automaticamente** a partir dos dados públicos da CVM ao enviar a análise para validação, e o `submit` não exige o bloco `net_worth` para esse subtipo. Pule esta etapa.
:::

### Input / Output

Como ***input*** envie os valores patrimoniais e a categoria autodeclarada do investidor.

Como ***output*** será retornada a representação atualizada da análise cadastral.

### Request

ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/net_worth`
MÉTODO `PUT`
STATUS `202`

Exemplo

```json title='Request Body'
{
    "investor_category": "retail",
    "total_net_worth": 250000,
    "total_financial_applications": 80000,
    "monthly_income": 15000,
    "other_incomes": 0,
    "real_estate": 150000,
    "movable_assets": 20000,
    "resource_origin": "Renda do trabalho"
}
```

### Body params
| Campo                          | Tipo   | Descrição                                                          | Obrigatório |
|--------------------------------|--------|--------------------------------------------------------------------|-------------|
| `total_net_worth`              | number | Patrimônio total (>= 0)                                            |    Sim      |
| `total_financial_applications` | number | Total em aplicações financeiras (>= 0)                             |    Sim      |
| `monthly_income`               | number | Renda ou faturamento mensal (>= 0)                                 |    Sim      |
| `other_incomes`                | number | Outras rendas mensais (>= 0)                                       |    Sim      |
| `real_estate`                  | number | Patrimônio em imóveis (>= 0)                                       |    Sim      |
| `movable_assets`               | number | Patrimônio em bens móveis (>= 0)                                   |    Sim      |
| `investor_category`            | string | Enumerador de **[Investor Category](#investor-category)**          |    Sim      |
| `resource_origin`              | string | Origem dos recursos (até 255 caracteres)                           |    Não      |

### Investor Category {#investor-category}
| Enumerador     | Descrição     |
|----------------|---------------|
| `retail`       | Varejo        |
| `qualified`    | Qualificado   |
| `professional` | Profissional  |

### Response
A análise cadastral atualizada é retornada no corpo da resposta. Para o formato completo, consulte **Busca informações de uma análise cadastral do investidor**.

---

# Consultar Feedback

URL: /documentation/iaas/investidor/compartilhado/feedback/consultar_feedback

---
### Introdução
Este recurso retorna um único **feedback** identificado por `feedback_key`, em uma representação **resumida**: chave, status, origem e o histórico de mensagens. É a rota indicada para confirmar se um feedback ainda está `open` ou já foi encerrado (`closed`) pela sua resposta.

:::info Esta rota devolve menos campos que a listagem
A resposta **não** inclui `description`, `category`, `type` nem `data`. Se você precisa do texto do pedido ou da categoria do feedback, use **[Listar Feedbacks](./listar_feedbacks)** — a listagem devolve o objeto completo. O formato das mensagens também é diferente entre as duas rotas; compare as tabelas abaixo antes de reaproveitar o seu parser.
:::

### Request

ENDPOINT `/investor_registry/investor/{investor_key}/feedback/{feedback_key}`
MÉTODO `GET`
STATUS `200`

Não há corpo de requisição nem query params.

### Response

O corpo é o **objeto direto**, sem envelope `data`.

```json title='Response Body'
{
  "feedback_key": "UUID",
  "status": "open",
  "origin_type": "investor_analysis",
  "origin_key": "UUID",
  "messages": [
    {
      "message": "O comprovante de residência apresentado tem data superior a 90 dias.",
      "sender_type": "distributor",
      "created_at": "2026-07-31T21:47:46Z"
    }
  ]
}
```

| Campo          | Tipo   | Descrição                                                                 |
|----------------|--------|---------------------------------------------------------------------------|
| `feedback_key` | string | Identificador do feedback                                                  |
| `status`       | string | Enumerador de **[Feedback Status](./listar_feedbacks#feedback-status)**    |
| `origin_type`  | string | Enumerador de **[Origin Type](./listar_feedbacks#origin-type)**            |
| `origin_key`   | string | Chave da entidade de origem                                                |
| `messages`     | array  | Histórico de mensagens — ver **[Message](#message)**. Vazio se não houver  |

### Message {#message}
| Campo        | Tipo   | Descrição                                                                          |
|--------------|--------|--------------------------------------------------------------------------------------|
| `message`    | string | Conteúdo da mensagem                                                                |
| `sender_type`| string | Tipo do agente que enviou (`distributor`, `investor`, `manager`, `administrator`, entre outros; mensagens escritas por analistas da QI Tech chegam com o tipo do agente interno) |
| `created_at` | string | Data/hora do envio, em ISO-8601 UTC (`2026-07-31T21:47:46Z`)                        |

### Escopo da busca

O feedback é localizado dentro do **cadastro do investidor** informado em `investor_key`, cobrindo as duas origens possíveis:

- feedbacks abertos sobre uma **análise cadastral** do investidor (`origin_type: investor_analysis`);
- feedbacks abertos sobre uma **parte relacionada** de qualquer análise desse investidor (`origin_type: related_party_analysis`).

Um `feedback_key` que exista, mas pertença a outro investidor, resulta em `404` com o código `IVR000089` — o mesmo retorno de uma chave inexistente.

### Erros

| Código      | HTTP | Quando ocorre                                                                 |
|-------------|------|---------------------------------------------------------------------------------|
| `IVR000089` | 404  | Feedback não encontrado para o investidor informado                             |
| `IVR000008` | 404  | Investidor não encontrado para as credenciais utilizadas                        |

---

# Enviar Mensagem em Feedback

URL: /documentation/iaas/investidor/compartilhado/feedback/enviar_mensagem_feedback

---
### Introdução
Este recurso adiciona uma nova **mensagem** a um feedback existente. É por aqui que você **responde** a um pedido de esclarecimento feito pela QI Tech — e é a mensagem que **encerra** o feedback.

:::info Como responder a um feedback
A resposta é uma única ação: **enviar a mensagem neste endpoint**. Ao recebê-la, o feedback passa de `open` para `closed` e a análise de compliance retoma a avaliação.

Não há `submit` a refazer: a análise permaneceu em `in_compliance_analysis` durante todo o ciclo do feedback. Veja **[Ciclo de vida da análise cadastral](../ciclo_de_vida_da_analise#feedback)**.
:::

### Request

ENDPOINT `/investor_registry/investor/{investor_key}/feedback/{feedback_key}/message`
MÉTODO `PUT`
STATUS `201`

### Request body
```json title='Request Body'
{
    "message": "Confirmamos que o endereço declarado permanece válido; o titular reside no imóvel desde 2019.",
    "origin_type": "investor_analysis",
    "origin_key": "UUID"
}
```

### Body params
| Campo         | Tipo   | Descrição                                                                                | Caracteres | Obrigatório |
|---------------|--------|--------------------------------------------------------------------------------------------|------------|-------------|
| `message`     | string | Conteúdo da mensagem                                                                       |  1 - 1000  |    Sim      |
| `origin_type` | string | Enumerador de **[Origin Type](./listar_feedbacks#origin-type)**. Apenas `investor_analysis` é aceito nesta rota |   1 - 50   |    Sim      |
| `origin_key`  | string | Chave da entidade de origem (UUID)                                                         |     36     |    Sim      |

:::warning `origin_type` e `origin_key` devem coincidir com os do feedback
O par informado no corpo precisa ser exatamente o mesmo devolvido pelo feedback em **Listar Feedbacks**. Se não houver feedback com aquele `feedback_key` naquela origem, a chamada é recusada com `IVR000085`.
:::

:::warning Enviar mensagem encerra o feedback
Um feedback `open` passa a `closed` assim que a sua mensagem é registrada. **Envie tudo o que precisa dizer em uma única mensagem** — um feedback já encerrado não aceita novas mensagens, e não há endpoint para reabri-lo. Se a QI Tech precisar de mais alguma coisa, ela abre um **novo** feedback, com um novo `feedback_key`.
:::

### Response
O feedback atualizado é retornado no corpo da resposta, no mesmo formato de cada item de **[Listar Feedbacks](./listar_feedbacks)**, já com a nova mensagem incluída no array `messages` e com o `status` em `closed`.

### Webhook

O encerramento dispara um `investor_registry.feedback_status_change` com `status: closed`:

```json title='Webhook Body — feedback encerrado'
{
    "webhook_type": "investor_registry.feedback_status_change",
    "webhook_datetime": "2026-07-31T22:12:03Z",
    "data": {
        "investor_analysis_key": "UUID",
        "feedback_key": "UUID",
        "status": "closed",
        "origin_type": "investor_analysis",
        "origin_key": "UUID"
    }
}
```

O detalhamento dos campos está em **[Webhooks de feedback](../ciclo_de_vida_da_analise#webhooks-feedback)**.

---

# Listar Feedbacks

URL: /documentation/iaas/investidor/compartilhado/feedback/listar_feedbacks

---
### Introdução
Este recurso lista os **feedbacks** abertos em torno de uma entidade da análise cadastral. Feedbacks são o canal pelo qual a QI Tech solicita **complementos e esclarecimentos** durante a análise — tipicamente pendências de PLD/compliance ou dados cadastrais a confirmar.

:::info O feedback não altera o status da análise
Um feedback é aberto na **análise de compliance** e corre **em paralelo** a ela: a análise permanece em `in_compliance_analysis`, não retorna para `pending_registry_data` e não exige um novo `submit`. Você responde à mensagem, o feedback é encerrado (`closed`) e a compliance retoma a avaliação.

Quando o cadastro não reúne os dados mínimos para aprovação, a análise é **recusada** e uma nova análise precisa ser aberta — não há feedback nesse caso. Veja **[Ciclo de vida da análise cadastral](../ciclo_de_vida_da_analise)** para a distinção completa.
:::

:::warning A abertura de um feedback só é notificada por webhook
Como o status da análise não muda, o único aviso é o `investor_registry.feedback_status_change` com `status: open`. Veja **[Webhooks de feedback](../ciclo_de_vida_da_analise#webhooks-feedback)**.
:::

### Request

ENDPOINT `/investor_registry/investor/{investor_key}/feedbacks`
MÉTODO `GET`
STATUS `200`

### Query params
| Campo         | Tipo    | Descrição                                                                                  | Obrigatório |
|---------------|---------|--------------------------------------------------------------------------------------------|-------------|
| `origin_type` | string  | Enumerador de **[Origin Type](#origin-type)**                                               |    Sim      |
| `origin_key`  | string  | Chave da entidade de origem (UUID)                                                          |    Sim      |
| `page`        | integer | Página (>= 0). Default: `0`                                                                 |    Não      |
| `limit`       | integer | Tamanho da página. Default: `100`                                                           |    Não      |

:::warning `origin_type` e `origin_key` são obrigatórios
Não existe listagem de todos os feedbacks de um investidor: a consulta é sempre feita **por entidade de origem**. Para varrer um cadastro, consulte a análise cadastral e itere sobre a própria análise e sobre cada parte relacionada.

Um `origin_type` fora do enumerador é recusado com `IVR000075`.
:::

### Origin Type {#origin-type}
| Enumerador               | Descrição                                        | O que enviar em `origin_key`      |
|--------------------------|--------------------------------------------------|------------------------------------|
| `investor_analysis`      | Feedback sobre a análise cadastral como um todo  | `investor_analysis_key`            |
| `related_party_analysis` | Feedback sobre uma parte relacionada específica  | `external_related_party_key`       |

:::warning Não existe `origin_type` de documento
Feedbacks são abertos sobre a **análise** ou sobre a **parte relacionada**, nunca diretamente sobre um documento. Um pedido relacionado a um documento chega como feedback de `investor_analysis`, com a descrição indicando qual documento motivou o questionamento.
:::

### Response

```json title='Response Body'
{
  "data": [
    {
      "feedback_key": "UUID",
      "description": "O comprovante de residência apresentado tem data superior a 90 dias. Favor esclarecer se o endereço declarado permanece válido.",
      "status": "open",
      "category": "registry_data",
      "type": "automatic",
      "origin_type": "investor_analysis",
      "origin_key": "UUID",
      "data": {},
      "messages": [
        {
          "text": "O comprovante de residência apresentado tem data superior a 90 dias.",
          "datetime": "2026-07-31T21:47:46Z",
          "agent": {
            "username": "analista.qitech",
            "email": "analista@qitech.com.br",
            "user_key": "UUID",
            "agent_type": "internal",
            "agent_key": "UUID"
          }
        }
      ]
    }
  ],
  "is_last_page": true
}
```

| Campo           | Tipo    | Descrição                                                                       |
|-----------------|---------|----------------------------------------------------------------------------------|
| `feedback_key`  | string  | Identificador do feedback                                                        |
| `description`   | string  | Texto do pedido, redigido pela QI Tech                                           |
| `status`        | string  | Enumerador de **[Feedback Status](#feedback-status)**                            |
| `category`      | string  | Enumerador de **[Feedback Category](#feedback-category)**                        |
| `type`          | string  | `automatic` (aberto por regra do sistema) ou `manual` (aberto por um analista)   |
| `origin_type`   | string  | Enumerador de **[Origin Type](#origin-type)**                                    |
| `origin_key`    | string  | Chave da entidade de origem                                                      |
| `data`          | object  | Metadados do feedback                                                            |
| `messages`      | array   | Histórico de mensagens — ver **[Message](#message)**                             |
| `is_last_page`  | boolean | `false` indica que há mais páginas                                               |

### Message {#message}
| Campo      | Tipo   | Descrição                                                                    |
|------------|--------|--------------------------------------------------------------------------------|
| `text`     | string | Conteúdo da mensagem                                                          |
| `datetime` | string | Data/hora do envio, em ISO-8601 UTC (`2026-07-31T21:47:46Z`)                  |
| `agent`    | object | Identificação de quem enviou: `username`, `email`, `user_key`, `agent_type`, `agent_key` |

:::info A resposta não devolve `page` nem `limit`
A paginação é sinalizada apenas por `is_last_page`. Controle o `page` do seu lado, incrementando enquanto `is_last_page` for `false`.
:::

### Feedback Status {#feedback-status}
| Enumerador | Descrição                                                                                     |
|------------|------------------------------------------------------------------------------------------------|
| `created`  | Criado, ainda não disponibilizado                                                              |
| `open`     | Aberto — aguarda sua resposta. Bloqueia a conclusão da análise                                 |
| `closed`   | Encerrado — a resposta foi registrada e o pedido está resolvido                                |

:::info A sua resposta encerra o feedback
Enviar a mensagem com **[Enviar Mensagem em Feedback](./enviar_mensagem_feedback)** move o feedback de `open` para `closed` — não é preciso aguardar um analista da QI Tech. Se a resposta não for suficiente, a compliance abre um **novo** feedback, com um novo `feedback_key`.
:::

### Feedback Category {#feedback-category}
| Enumerador      | Descrição                                                                                                        |
|-----------------|--------------------------------------------------------------------------------------------------------------------|
| `registry_data` | Dado cadastral a corrigir ou complementar — ex.: comprovação de qualificação ausente, renda declarada fora da faixa esperada |
| `compliance`    | Esclarecimento de PLD/compliance, decorrente de indicadores da análise de risco                                   |

A categoria indica **a natureza do que está sendo pedido** — um dado cadastral a esclarecer ou um esclarecimento de PLD. Para a sua integração o tratamento é o mesmo: responder ao ponto apontado com **[Enviar Mensagem em Feedback](./enviar_mensagem_feedback)**, o que encerra o feedback. A análise segue em `in_compliance_analysis` o tempo todo — não há `submit` a refazer.

---

# Criar Investor Owner

URL: /documentation/iaas/investidor/compartilhado/investor_owner/criar_investor_owner

---
### Introdução
Este recurso cria um vínculo de **propriedade / responsabilidade** (`investor_owner`) entre o investidor da análise e outro investidor já existente no sistema (identificado pelo CNPJ informado). É utilizado principalmente em fluxos de **carteira administrada** para registrar o gestor de carteira.

:::info Quando usar
- Para fundos de investimento (`fund_class`), os vínculos com **administrador** e **gestor** são criados **automaticamente** ao enviar a análise para validação, com base nos dados públicos da CVM. Este endpoint deve ser usado para registrar vínculos **adicionais** (ex.: investidor exclusivo, gestor de carteira), ou para fluxos diferentes do auto-enriquecimento.
- O investidor referenciado pelo `document_number` precisa estar previamente cadastrado no distribuidor.
:::

### Input / Output

Como ***input*** envie o CNPJ do investidor que será o "owner" e o tipo do vínculo.

Como ***output*** o status `201 Created` é retornado.

### Request

ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/investor_owner`
MÉTODO `POST`
STATUS `201`

### Request body

```json title='Request Body'
{
    "investor_owner_type": "wallet_manager",
    "document_number": "07.228.314/0001-95"
}
```

### Body params
| Campo                          | Tipo   | Descrição                                                                            | Caracteres | Obrigatório |
|--------------------------------|--------|--------------------------------------------------------------------------------------|------------|-------------|
| `investor_owner_type`          | string | Enumerador de **[Investor Owner Type](#investor-owner-type)**                        |   1 - 50   |    Sim      |
| `document_number`              | string | CNPJ do investidor que será o owner (`XX.XXX.XXX/XXXX-XX`)                           |     18     |    Sim      |
| `external_investor_owner_key`  | string | Chave externa pré-definida para este vínculo. Caso omitida, é gerada automaticamente |   1 - 36   |    Não      |

### Investor Owner Type {#investor-owner-type}
| Enumerador                  | Descrição                                                         |
|-----------------------------|-------------------------------------------------------------------|
| `fund_class_administrator`  | Administrador do fundo                                            |
| `fund_class_manager`        | Gestor do fundo                                                   |
| `wallet_manager`            | Gestor de carteira                                                |

### Atualizar status de um Investor Owner

Para inativar ou reativar um vínculo, utilize:

ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/investor_owner/{external_investor_owner_key}/status`
MÉTODO `PUT`
STATUS `202`

```json title='Request Body'
{
    "status": "active"
}
```

---

# Enviar Documento de Investor Owner

URL: /documentation/iaas/investidor/compartilhado/investor_owner/enviar_documento_investor_owner

---
### Introdução
Este recurso faz o upload de um documento associado a um **investor owner** (vínculo de propriedade) de uma análise cadastral. Aplica-se principalmente aos fluxos de fundo de investimento, onde podem ser exigidos documentos do administrador, gestor ou investidor exclusivo.

### Input / Output

Como ***input*** envie o arquivo em **base64**, o tipo e a extensão.

Como ***output*** será retornada a representação do documento criado.

### Request

ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/investor_owner/{external_investor_owner_key}/document`
MÉTODO `POST`
STATUS `201`

### Request body
```json title='Request Body'
{
    "type": "power_of_attorney",
    "document_b64": "base64_encoded_document_content",
    "file_extension": "pdf"
}
```

### Body params
| Campo            | Tipo   | Descrição                                              | Obrigatório |
|------------------|--------|--------------------------------------------------------|-------------|
| `type`           | string | Tipo do documento (ver enumerador em **Enviar Documento do Investidor**) |    Sim      |
| `document_b64`   | string | Conteúdo do arquivo em base64                          |    Sim      |
| `file_extension` | string | Extensão (`pdf` ou `jpeg`)                             |    Sim      |
| `document_data`  | object | Metadados livres do documento                          |    Não      |
| `observation`    | string | Observação livre (até 500 caracteres)                  |    Não      |

### Endpoints relacionados
- `GET .../investor_owner/{external_investor_owner_key}/document/{investor_owner_document_key}` — consultar um documento de investor owner.
- `PUT .../investor_owner/{external_investor_owner_key}/document/{investor_owner_document_key}/update` — atualizar o status de um documento.

---

# Atualizar Parte Relacionada

URL: /documentation/iaas/investidor/compartilhado/related_party/atualizar_parte_relacionada

---

### Introdução
Este recurso **corrige os dados** de uma parte relacionada já criada — percentual de participação, endereço, renda, tipo de vínculo ou qualquer outro campo enviado na criação.

É o caminho para resolver uma recusa de participação societária (`IVR000166`, `IVR000169`, `IVR000170`) sem precisar abrir uma nova análise cadastral: ajuste o percentual e reenvie o `submit`.

:::info Corrigir ou desativar?
- Para **ajustar dados** de uma parte que continua fazendo parte do cadastro, use este endpoint
- Para **remover** uma parte do cadastro, use **[Atualizar Status da Parte Relacionada](./atualizar_status_parte_relacionada)** com `status: "inactive"`. Não existe `DELETE` — partes relacionadas nunca são apagadas fisicamente
:::

### Input / Output:
Como ***input*** devem ser enviados os dados da parte relacionada. O corpo é uma **substituição completa**: envie todos os campos, não apenas os que mudaram.

Como ***output*** será retornada a representação atualizada da parte relacionada.

### Request

ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/related_party/{external_related_party_key}`
MÉTODO `PUT`
STATUS `200`

:::warning Use o `external_related_party_key`
A chave aceita nesta URL é o **`external_related_party_key`** devolvido na criação da parte relacionada — não o `related_party_key`. Uma chave desconhecida é recusada com `IVR000183`.

Atenção: as mensagens de erro do `submit` (`IVR000030`) citam a parte relacionada pelo `related_party_key` **interno**, que não funciona nesta rota. Para correlacionar as duas chaves, consulte a análise cadastral — o objeto de cada parte relacionada traz ambas.
:::

### Request body

```json title='Request Body'
{
    "name": "João Silva",
    "document_number": "123.456.789-00",
    "person_type": "natural_person",
    "related_party_type": "partner",
    "resident": true,
    "legal_representative": true,
    "direct_beneficiary": true,
    "participation_percentage": 0.85,
    "monthly_income": 50000.00,
    "address": {
        "postal_code": "01000-000",
        "street": "Rua das Flores",
        "number": "123",
        "neighborhood": "Centro",
        "city": "São Paulo",
        "uf": "SP",
        "country": "BRA"
    },
    "email": "joao.silva@example.com",
    "phone": {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "987654321"
    }
}
```

### Body params

Os campos são os mesmos de **[Criar Parte Relacionada](./criar_parte_relacionada#body-params)**, com uma diferença:

| Campo             | Diferença em relação à criação                                                        |
|-------------------|-----------------------------------------------------------------------------------------|
| `document_number` | **Sempre obrigatório** neste endpoint, inclusive para partes com `resident: false`       |

Todas as demais regras condicionais continuam valendo — `address` obrigatório para `legal_person` ou quando `direct_beneficiary: true`, `monthly_income` obrigatório para pessoa física com `direct_beneficiary: true`, e assim por diante.

:::warning A análise não pode estar em estado terminal
A atualização é recusada com `IVR000185` quando a análise cadastral já está em um dos status finais: `automatically_approved`, `automatically_reproved`, `manually_approved`, `manually_reproved`, `analysis_complete` ou `expired`.

Se o cadastro já foi analisado, a correção passa por abrir uma nova análise via **Atualização Cadastral**.
:::

### Response
```json title='Response Body'
{
    "related_party_key": "UUID",
    "external_related_party_key": "UUID",
    "name": "João Silva",
    "document_number": "123.456.789-00",
    "person_type": "natural_person",
    "related_party_type": "partner",
    "status": "active",
    "resident": true,
    "legal_representative": true,
    "direct_beneficiary": true,
    "address": {},
    "participation_percentage": 0.85,
    "monthly_income": 50000.00,
    "email": "joao.silva@example.com",
    "phone": {}
}
```

---

# Atualizar Status da Parte Relacionada

URL: /documentation/iaas/investidor/compartilhado/related_party/atualizar_status_parte_relacionada

---

### Introdução
Este recurso **ativa ou desativa** uma parte relacionada dentro de uma análise cadastral.

Para uma parte enviada por engano, ou que deixou de compor o quadro societário, é **desativada** por aqui. Partes com status `inactive` são ignoradas em todas as validações do envio para análise — não contam para a exigência de quantidade mínima, não contam para o requisito de representante legal, não somam participação societária e não têm documentos cobrados.

:::info Casos de uso
- **Sócio enviado por engano** → desative com `inactive`
- **Quadro societário mudou** → desative quem saiu e crie quem entrou
- **Participação somada acima de 100%** (`IVR000169`) → desative a parte duplicada, ou corrija o percentual com **[Atualizar Parte Relacionada](./atualizar_parte_relacionada)**
:::

### Input / Output:
Como ***input*** deve ser enviado o novo status.

Como ***output*** será retornada a confirmação da alteração.

### Request

ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/related_party/{external_related_party_key}/status`
MÉTODO `PUT`
STATUS `202`

### Request body

```json title='Request Body'
{
    "status": "inactive"
}
```

### Body params
| Campo    | Tipo   | Descrição                                            | Obrigatório |
|----------|--------|-------------------------------------------------------|-------------|
| `status` | string | Enumerador de **[Related Party Status](#status)**     |    Sim      |

### Related Party Status {#status}
| Enumerador | Descrição                                                                                  |
|------------|-----------------------------------------------------------------------------------------------|
| `active`   | Parte considerada em todas as validações do envio para análise                                |
| `inactive` | Parte desconsiderada em todas as validações. É o equivalente a remover a parte do cadastro    |

:::warning A análise não pode estar em estado terminal
A alteração é recusada com `IVR000185` quando a análise cadastral já está em um dos status finais: `automatically_approved`, `automatically_reproved`, `manually_approved`, `manually_reproved`, `analysis_complete` ou `expired`.
:::

Uma `external_related_party_key` desconhecida na análise informada é recusada com `IVR000183`.

---

# Criar Parte Relacionada

URL: /documentation/iaas/investidor/compartilhado/related_party/criar_parte_relacionada

---

### Introdução
Este recurso tem como objetivo identificar os beneficiários finais (pessoas físicas) e controladores relacionados ao investidor pessoa jurídica, como sócios, diretores, administradores, etc ou procuradores de pessoa física.

:::warning Atenção
- Este endpoint deve ser chamado múltiplas vezes, uma vez para cada parte relacionada
- Para pessoa jurídica como parte relacionada, o `related_party_type` deve ser obrigatoriamente `parent_company` (exceto em `fund_class`)
- As exigências de quantidade, de representante legal e de participação mínima **variam conforme o tipo do investidor** — veja [Exigências por tipo de investidor](#exigencias) abaixo
- Para corrigir ou desativar uma parte relacionada já criada, use **Atualizar Parte Relacionada** e **Atualizar Status da Parte Relacionada**. Partes com status `inactive` deixam de ser consideradas em todas as validações do envio para análise
:::

### Exigências por tipo de investidor {#exigencias}

As validações abaixo são aplicadas no **envio para análise** (`submit`), não na criação da parte relacionada. Cada regra é avaliada em sequência, então uma recusa pode esconder a próxima pendência.

| Investidor | Partes relacionadas | Representante legal | Participação somada |
|---|---|---|---|
| **Pessoa física** (`natural_person`) | Opcional — envie apenas se houver procurador | Não exigido | Não validada |
| **Pessoa jurídica** (`legal_person` / `default`, `financial_institution`) | **Pelo menos uma** ativa, senão `IVR000134` | **Pelo menos uma** com `legal_representative: true`, senão `IVR000136` | **≥ 80%** e nunca acima de 100%, senão `IVR000166` / `IVR000169` |
| **Fundo** (`fund_class`) **não exclusivo** | Nenhuma — pode pular a etapa | Não exigido | Não validada |
| **Fundo** (`fund_class`) **exclusivo** | **Pelo menos uma**, obrigatoriamente do tipo `exclusive_investor`, senão `IVR000134` | **Proibido** — `exclusive_investor` não pode ser representante legal (`IVR000165`) | **Exatamente 100%**, senão `IVR000170` |

:::info Fundos de investimento
Em um fundo, a representação se dá pelos **investor owners** (administrador e gestora) — não é necessário enviar representantes legais como parte relacionada. O único `related_party_type` aceito em `fund_class` é `exclusive_investor`; qualquer outro valor é recusado com `IVR000172`.

O caráter exclusivo do fundo (`exclusive_fund_class`) é derivado automaticamente da classe CVM no momento da criação do investidor. Se o CNPJ não constar na base da CVM, o campo fica indefinido e o `submit` é recusado com `IVR000068` — use um CNPJ de fundo efetivamente registrado na CVM.
:::

:::info Sobre os Beneficiários Finais
*Beneficiário Final é a pessoa natural que, em última instância exerce posição de controle ou influência significativa na empresa, especialmente as que detêm 15% ou mais de participação direta ou indireta, exercem cargo de administração ou representam a empresa para fins legais.*

*Informar os dados das pessoas físicas que detêm 15% ou mais de participação societária direta ou indireta e administradores. Se nenhum dos sócios/acionistas detém individualmente participação igual ou maior a 15%, solicitamos enviar as informações dos 03 controladores que detêm os maiores percentuais de participação.*

**Conciliando a regra de 15% com o mínimo de 80%.** As duas regras convivem: a de 15% define *quem* precisa ser qualificado, a de 80% define *quanto* da cadeia societária precisa estar declarado. Uma sócia **pessoa jurídica** (`parent_company`) também conta para a soma — em capital pulverizado, declarar a holding controladora costuma ser o caminho para atingir o mínimo. Recomendamos enviar **pelo menos 85%** somados, para não depender de arredondamento.

O procurador (`attorney`), embora não detenha participação, exerce posição de controle e por isso é considerado beneficiário final. Envie-o com `participation_percentage: 0`.

Quando um beneficiário final pessoa física não puder ser plenamente qualificado, o cadastro da controladora pode bastar — porém poderão ser solicitados esclarecimentos por meio de [feedbacks](../feedback/listar_feedbacks).
:::

### Input / Output:
Como ***input*** devem ser enviados os dados da parte relacionada.

Como ***output*** será entregue uma ***external_related_party_key*** e os detalhes da parte relacionada criada.

### Request

ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/related_party`
MÉTODO `POST`
STATUS `201`

### Request body

Exemplo: Sócio Pessoa Física

```json title='Request Body'
{
    "name": "João Silva",
    "document_number": "123.456.789-00",
    "person_type": "natural_person",
    "related_party_type": "partner",
    "resident": true,
    "legal_representative": true,
    "direct_beneficiary": true,
    "address": {
        "postal_code": "01000-000",
        "street": "Rua das Flores",
        "number": "123",
        "neighborhood": "Centro",
        "city": "São Paulo",
        "uf": "SP",
        "country": "BRA",
        "complement": "Apto 101"
    },
    "participation_percentage": 0.5,
    "monthly_income": 50000.00,
    "email": "joao.silva@example.com",
    "phone": {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "987654321"
    }
}
```

Exemplo: Empresa Controladora (Pessoa Jurídica)

```json title='Request Body'
{
    "name": "Empresa Controladora Ltda",
    "document_number": "98.765.432/0001-11",
    "person_type": "legal_person",
    "related_party_type": "parent_company",
    "resident": true,
    "legal_representative": false,
    "direct_beneficiary": true,
    "address": {
        "postal_code": "02000-000",
        "street": "Avenida Principal",
        "number": "456",
        "neighborhood": "Jardim",
        "city": "São Paulo",
        "uf": "SP",
        "country": "BRA"
    },
    "participation_percentage": 0.8,
    "email": "contato@controladora.com.br",
    "phone": {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "123456789"
    }
}
```

### Body params
| Campo                             | Tipo     | Descrição                                                                    | Caracteres   | Obrigatório |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `name`                            | string   | Nome da parte relacionada                                                    |   1  - 255   |    Sim      |
| `person_type`                     | string   | Enumerador de **[Person Type](#person-type-related-party)**                 |      -       |    Sim      |
| `related_party_type`              | string   | Enumerador de **[Related Party Type](#related-party-type)**                 |      -       |    Sim      |
| `resident`                        | boolean  | Define se é residente no Brasil                                             |      -       |    Sim      |
| `legal_representative`            | boolean  | Define se é representante legal                                              |      -       |    Sim      |
| `direct_beneficiary`              | boolean  | Define se é beneficiário final                                               |      -       |    Sim      |
| `participation_percentage`        | number   | Percentual de participação, em **fração de 0 a 1** (ex.: `0.5` = 50%)        |      -       |    Sim      |
| `document_number`                 | string   | CPF ou CNPJ. Obrigatório quando `resident: true`                             |   1  - 18    | Condicional |
| `address`                         | object   | Objeto de **[Address](#address)**. Obrigatório quando `person_type` é `legal_person` **ou** quando `direct_beneficiary: true` |      -       | Condicional |
| `monthly_income`                  | number   | Renda mensal. Obrigatório quando `person_type` é `natural_person` **e** `direct_beneficiary: true` |      -       | Condicional |
| `nationality`                     | string   | Nacionalidade, código ISO de 3 letras maiúsculas (ex.: `BRA`). Default `BRA` para pessoa física. **Não aceito** para `legal_person` |      3       |    Não      |
| `email`                           | string   | E-mail                                                                       |   1  - 100   |    Não      |
| `phone`                           | object   | Objeto de **[Phone](#phone)**                                                |      -       |    Não      |
| `expiration_date`                 | string   | Data de expiração (formato: YYYY-MM-DD)                                      |      10      |    Não      |

:::warning Campos condicionais
`address` e `monthly_income` são recusados com `IVR000068` quando a condição acima é satisfeita e o campo não é enviado — mesmo que o schema os aceite como ausentes. Como a API valida um campo por vez, envie os dois já na primeira tentativa para partes com `direct_beneficiary: true`.

`nationality` enviado para uma parte relacionada `legal_person` é recusado com `IVR000238`.
:::

### Person Type (Related Party) {#person-type-related-party}
| Enumerador                        | Descrição                                                                    |
|-----------------------------------|------------------------------------------------------------------------------|
| `natural_person`                  | Pessoa física                                                                |
| `legal_person`                    | Pessoa jurídica                                                              |

### Related Party Type {#related-party-type}
| Enumerador                        | Descrição                                                                    |
|-----------------------------------|------------------------------------------------------------------------------|
| `president`                       | Presidente                                                                   |
| `partner`                         | Sócio                                                                        |
| `administrator`                   | Administrador                                                                |
| `director`                        | Diretor                                                                      |
| `manager`                         | Gestor                                                                       |
| `attorney`                        | Procurador                                                                   |
| `parent_company`                  | Empresa controladora (apenas para pessoa jurídica)                          |
| `asset_custodian`                 | Custodiante de ativos                                                        |
| `exclusive_investor`                 | Investidor Exclusivo                                                        |

### Address {#address}
| Campo                             | Tipo     | Descrição                                                                    | Caracteres   | Obrigatório |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `postal_code`                     | string   | Código postal. Para endereço no Brasil, CEP no formato `XXXXX-XXX`. Para endereço no exterior, envie o código postal local no formato do país |   1 - 20     |    Sim      |
| `street`                          | string   | Logradouro                                                                   |   1  - 255   |    Não      |
| `number`                          | string   | Número                                                                       |   1  - 10    |    Não      |
| `neighborhood`                    | string   | Bairro                                                                       |   1  - 255   |    Não      |
| `city`                            | string   | Cidade                                                                       |   1  - 255   |    Não      |
| `uf`                              | string   | Unidade federativa (ex.: `SP`). Para endereço no exterior, use `EX`          |   1 - 20     |    Não      |
| `country`                         | string   | País, código ISO de 3 letras (ex.: `BRA`)                                    |      3       |    Não      |
| `complement`                      | string   | Complemento                                                                  |   1  - 255   |    Não      |

:::info Endereço no exterior
`postal_code` e `uf` **não** têm validação de formato — aceitam o padrão de qualquer país. A coerência exigida é entre `resident` e `country`: uma parte relacionada com `resident: true` precisa de `country: "BRA"` (senão `IVR000227`), e uma com `resident: false` não pode ter `country: "BRA"` (senão `IVR000226`).
:::

### Phone {#phone}
| Campo                             | Tipo     | Descrição                                                                    | Caracteres   | Obrigatório |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `international_dial_code`         | string   | Código internacional                                                         |   1  - 3     |    Sim      |
| `area_code`                       | string   | Código de área                                                               |      2       |    Sim      |
| `number`                          | string   | Número de telefone                                                           |   8  - 9     |    Sim      |

### Response
```json title='Response Body'
{
    "related_party_key": "UUID",
    "external_related_party_key": "UUID",
    "name": "João Silva",
    "document_number": "123.456.789-00",
    "person_type": "natural_person",
    "related_party_type": "partner",
    "status": "active",
    "resident": true,
    "legal_representative": true,
    "direct_beneficiary": true,
    "address": {...},
    "participation_percentage": 0.5,
    "monthly_income": 50000.00,
    "email": "joao.silva@example.com",
    "phone": {...}
}
```

---

# Enviar Documento da Parte Relacionada

URL: /documentation/iaas/investidor/compartilhado/related_party/enviar_documento_parte_relacionada

---

### Introdução
Este recurso tem como objetivo fazer upload dos documentos obrigatórios de cada parte relacionada criada.

:::warning Atenção
- Este endpoint deve ser chamado para **cada** parte relacionada criada que seja **pessoa física**
- A parte relacionada deve estar com status **`active`** para receber documentos
- Para pessoa física: é obrigatório enviar um documento de identificação — `cnh` **ou** o par `rg_front` + `rg_back`
- Para pessoa jurídica (`parent_company`): **nenhum** documento é exigido
- Um mesmo `type` só aceita um envio bem-sucedido: veja [Reenvio e documento duplicado](#duplicado)
:::

### Input / Output:
Como ***input*** deve ser enviado o documento em base64, o tipo do documento e a extensão do arquivo.

Como ***output*** será entregue uma ***related_party_document_key*** que identifica o documento enviado.

### Request

ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/related_party/{external_related_party_key}/document`
MÉTODO `POST`
STATUS `201`

### Request body

Exemplo: Documento de Identificação (CNH)

```json title='Request Body'
{
    "type": "cnh",
    "document_b64": "base64_encoded_document_content",
    "file_extension": "pdf"
}
```

Exemplo: RG (Frente e Verso)

```json title='Request Body - Frente'
{
    "type": "rg_front",
    "document_b64": "base64_encoded_document_content",
    "file_extension": "pdf"
}
```

```json title='Request Body - Verso'
{
    "type": "rg_back",
    "document_b64": "base64_encoded_document_content",
    "file_extension": "pdf"
}
```

Exemplo: Procuração (para tipo attorney)

```json title='Request Body'
{
    "type": "power_of_attorney",
    "document_b64": "base64_encoded_document_content",
    "file_extension": "pdf"
}
```

### Body params
| Campo                             | Tipo     | Descrição                                                                    | Caracteres   | Obrigatório |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `type`                            | string   | Tipo de documento                                                           |   1  - 50    |    Sim      |
| `document_b64`                    | string   | Base 64 do documento                                                         |      -       |    Sim      |
| `file_extension`                 | string   | Extensão do arquivo (pdf, png, jpeg)                                         |   1  - 10    |    Sim      |

### Document Type (Related Party)
| Enumerador                        | Descrição                   | Extensões Suportadas        | Uso                                 |
|-----------------------------------|-----------------------------|-----------------------------|-------------------------------------|
| `cnh`                             | CNH                         | pdf, jpeg                   | Identificação (opção 1)             |
| `rg_front`                        | Frente do RG                | pdf, jpeg                   | Identificação (opção 2, com `rg_back`) |
| `rg_back`                         | Verso do RG                 | pdf, jpeg                   | Identificação (opção 2, com `rg_front`) |
| `passport`                        | Passaporte                  | pdf, jpeg                   | Identificação de parte estrangeira  |
| `foreign_id`                      | Identidade estrangeira      | pdf, jpeg                   | Identificação de parte estrangeira  |
| `power_of_attorney`               | Procuração                  | pdf, jpeg                   | Complementar, para `attorney`       |

### Documentos Obrigatórios

A exigência é avaliada no envio para análise (`submit`) e recusada com `IVR000030`. Basta satisfazer **uma** das opções.

#### Parte relacionada pessoa física residente
| Opção | Documentos                     |
|-------|---------------------------------|
| 1     | `cnh`                           |
| 2     | `rg_front` **+** `rg_back`      |

#### Parte relacionada pessoa física não residente
| Opção | Documentos      |
|-------|------------------|
| 1     | `passport`      |
| 2     | `foreign_id`    |

#### Parte relacionada pessoa jurídica (`parent_company`)
Nenhum documento é exigido.

:::info Procuração
Para uma parte relacionada do tipo `attorney`, `power_of_attorney` é **obrigatório e complementar**: ele é exigido *além* da identificação, e não a substitui. A parte continua precisando de `cnh` ou do par `rg_front` + `rg_back`. A falta da procuração é recusada com `IVR000148`.
:::

### Reenvio e documento duplicado {#duplicado}

Um tipo é considerado satisfeito assim que existe, para aquela parte relacionada, um documento daquele tipo com status `valid` ou `in_manual_analysis`. Novos envios do mesmo tipo passam a ser recusados:

```json
HTTP 409
{
  "title": "Already exists valid document for related party.",
  "code": "IVR000141"
}
```

Enquanto **todos** os documentos de um tipo estiverem `invalid`, novos envios continuam sendo aceitos.

### Response
```json title='Response Body'
{
    "related_party_document_key": "UUID",
    "status": "in_manual_analysis"
}
```

:::info Validação automática
O documento é validado automaticamente após o upload. O status pode ser:
- `valid`: validado automaticamente
- `invalid`: reprovado na validação automática
- `in_manual_analysis`: encaminhado para conferência humana

Para documentos reprovados, é possível forçar o envio usando o parâmetro `force=true`. Ao utilizar essa flag o documento será submetido para avaliação manual, necessariamente — e passa a satisfazer a exigência do tipo.
:::

---

# Consultar Formulário Suitability

URL: /documentation/iaas/investidor/compartilhado/suitability/consultar_formulario_suitability

:::warning Atenção
 O envio do `suitability` ***NÃO*** é necessário para investidores que sejam **Fundos de Investimento** ou **Pessoas Jurídicas** enquadradas como **qualificadas** ou **profissionais**.
:::

### Request:
:::info
O formulário suitability muda de acordo com o `person_type` do investidor sendo cadastrado. Para obter o formulário suitability a ser respondido é necessário realizar uma consulta no formulário vigente para o tipo de investidor.
:::

ENDPOINT `/investor_registry/v2/suitability_form`
MÉTODO `GET`
STATUS `200`

### Query params
| Campo                             | Tipo     | Descrição                                                                    | Caracteres   | Obrigatório |
|-----------------------------------|----------|------------------------------------------------------------------------------|--------------|-------------|
| `person_type`                 | enumerator    | `natural_person` \| `legal_person`                                                        |      -       |    Sim      |

### Response

Caso 01: Pessoa Jurídica

```json
{
    "01": {
        "title": "Por quanto tempo a empresa pretende manter seu dinheiro investido?",
        "options": {
            "A": {
                "title": "Pretende manter os recursos aplicados em até 1 ano e utilizar parte importante ou a integridade dos recursos desta carteira nesse período."
            },
            "B": {
                "title": "Pretende manter os recursos aplicados entre 2 e 3 anos e utilizar parte importante ou a integridade dos recursos desta carteira nesse período."
            },
            "C": {
                "title": "Pretende manter os recursos aplicados entre 4 e 5 anos e utilizar os recursos desta carteira após esse período."
            },
            "D": {
                "title": "Pretende manter os recursos aplicados por um período acima de 5 anos e não tem planos de utilizar esses recursos, por enquanto."
            }
        }
    },
    "02": {
        "title": "Qual objetivo do investimento da empresa e a sua tolerância em relação aos riscos?",
        "options": {
            "A": {
                "title": "Preservação do capital para não perder valor ao longo do tempo, assumindo baixos riscos de perdas."
            },
            "B": {
                "title": "Aumento gradual do capital ao longo do tempo, assumindo médios riscos de perdas."
            },
            "C": {
                "title": "Aumento do capital acima da taxa de retorno média do mercado, mesmo que isso implique assumir riscos de perdas elevadas."
            },
            "D": {
                "title": "Obter no curto prazo retornos elevados e significativamente acima da taxa de retorno média do mercado, assumindo riscos elevados."
            }
        }
    },
    "03": {
        "title": "Com quais produtos de investimento a pessoa responsável pela tomada de decisões sobre investimentos em nome da empresa tem familiaridade (conhecimento do produto e dos riscos envolvidos)?",
        "options": {
            "A": {
                "title": "Renda Fixa (CDB, Tesouro Direto e Fundos de Renda Fixa)."
            },
            "B": {
                "title": "Renda Fixa (LCI, LCA, Debêntures, CRI, CRA, Fundos de Renda Fixa, etc)."
            },
            "C": {
                "title": "Renda Fixa, Fundos Multimercados, Renda Variável e Derivativos."
            },
            "D": {
                "title": "Renda Fixa, Fundos Multimercados, Renda Variável e Operações Estruturadas (Fundos Estruturados, COE, Swaps e Derivativos)."
            }
        }
    },
    "04": {
        "title": "Com quais produtos de investimento a empresa realizou operações 3 ou mais vezes nos últimos 2 anos?",
        "options": {
            "A": {
                "title": "Não investi nos últimos 2 anos ou investi menos de 3 vezes."
            },
            "B": {
                "title": "Renda Fixa (LCI, LCA, Debêntures, CRI, CRA, Fundos de Renda Fixa, etc)."
            },
            "C": {
                "title": "Renda Fixa, Fundos Multimercados, Renda Variável e Derivativos."
            },
            "D": {
                "title": "Renda Fixa, Multimercados, Renda Variável e Operações Estruturadas (Fundos Estruturados, COE, Swaps e Derivativos)."
            }
        }
    },
    "05": {
        "title": "Qual a composição mais aproximada do seu portfólio de investimentos?",
        "options": {
            "A": {
                "title": "Não possuo recursos investidos."
            },
            "B": {
                "title": "A totalidade dos recursos está aplicada em Renda Fixa (CDB, Tesouro Direto e Fundos de Renda Fixa)."
            },
            "C": {
                "title": "Entre 70% e 90% dos recursos estão aplicados em Renda Fixa (LCI, LCA, Debêntures, CRI, CRA, Fundos de Renda Fixa, etc) e entre 10% e 30% dos recursos estão aplicados em Fundos Multimercados, Renda Variável e Derivativos."
            },
            "D": {
                "title": "Mais de 50% dos recursos estão aplicados em Renda Fixa, Fundos Multimercados, Renda Variável e Operações Estruturadas (Fundos Estruturados, COE, Swaps e Derivativos)."
            }
        }
    },
    "06": {
        "title": "Qual a faixa de faturamento médio mensal?",
        "options": {
            "A": {
                "title": "Até R$ 500.000,00."
            },
            "B": {
                "title": "De R$ 500.000,01 a R$ 1.000.000,00."
            },
            "C": {
                "title": "De R$ 100.000,01 a R$ 5.000.000,00."
            },
            "D": {
                "title": "Acima de R$ 5.000.000,01."
            }
        }
    },
    "07": {
        "title": "Indique a faixa que corresponde ao valor total do patrimônio da empresa (bens móveis, imóveis, etc.:",
        "options": {
            "A": {
                "title": "Até R$ 500.000,00."
            },
            "B": {
                "title": "De R$ 500.000,01 a R$ 1.000.000,00."
            },
            "C": {
                "title": "De R$ 100.000,01 a R$ 5.000.000,00."
            },
            "D": {
                "title": "Acima de R$ 5.000.000,01."
            }
        }
    },
    "08": {
        "title": "Sobre os ativos que compõem o patrimônio da empresa, qual o percentual dos seus ativos financeiros (ex: aplicações financeiras)?",
        "options": {
            "A": {
                "title": "Cerca de 30% são ativos financeiros."
            },
            "B": {
                "title": "Cerca de 40% são ativos financeiros."
            },
            "C": {
                "title": "Cerca de 60% são ativos financeiros."
            },
            "D": {
                "title": "Cerca de 70% são ativos financeiros."
            }
        }
    }

}
```

Caso 02: Pessoa Física

```json
{
    "01": {
        "title": "Durante qual período pretende manter os seus investimentos e qual a sua necessidade de utilização dos recursos ao longo do tempo?",
        "options": {
            "A": {
                "title": "Pretende manter os recursos aplicados em até 1 ano e utilizar parte importante ou a integridade dos recursos desta carteira nesse período."
            },
            "B": {
                "title": "Pretende manter os recursos aplicados entre 2 e 3 anos e utilizar parte importante ou a integridade dos recursos desta carteira nesse período."
            },
            "C": {
                "title": "Pretende manter os recursos aplicados entre 4 e 5 anos e utilizar os recursos desta carteira após esse período."
            },
            "D": {
                "title": "Pretende manter os recursos aplicados por um período acima de 5 anos e não tem planos de utilizar esses recursos, por enquanto."
            }
        }
    },
    "02": {
        "title": "Qual objetivo do investimento e o seu perfil em relação à tolerância a riscos?",
        "options": {
            "A": {
                "title": "Preservação do capital para não perder valor ao longo do tempo, assumindo baixos riscos de perdas."
            },
            "B": {
                "title": "Aumento gradual do capital ao longo do tempo, assumindo médios riscos de perdas."
            },
            "C": {
                "title": "Aumento do capital acima da taxa de retorno média do mercado, mesmo que isso implique assumir riscos de perdas elevadas."
            },
            "D": {
                "title": "Obter no curto prazo retornos elevados e significativamente acima da taxa de retorno média do mercado, assumindo riscos elevados."
            }
        }
    },
    "03": {
        "title": "Com quais produtos de investimento você tem familiaridade (conhecimento do produto e dos riscos envolvidos)?",
        "options": {
            "A": {
                "title": "Renda Fixa (CDB, Tesouro Direto e Fundos de Renda Fixa)."
            },
            "B": {
                "title": "Renda Fixa (LCI, LCA, Debêntures, CRI, CRA, Fundos de Renda Fixa, etc)."
            },
            "C": {
                "title": "Renda Fixa, Fundos Multimercados, Renda Variável e Derivativos."
            },
            "D": {
                "title": "Renda Fixa, Fundos Multimercados, Renda Variável e Operações Estruturadas (Fundos Estruturados, COE, Swaps e Derivativos)."
            }
        }
    },
    "04": {
        "title": "Com quais produtos de investimento você operou 3 ou mais vezes nos últimos 2 anos?",
        "options": {
            "A": {
                "title": "Não investi nos últimos 2 anos ou investi menos de 3 vezes."
            },
            "B": {
                "title": "Renda Fixa (LCI, LCA, Debêntures, CRI, CRA, Fundos de Renda Fixa, etc)."
            },
            "C": {
                "title": "Renda Fixa, Fundos Multimercados, Renda Variável e Derivativos."
            },
            "D": {
                "title": "Renda Fixa, Multimercados, Renda Variável e Operações Estruturadas (Fundos Estruturados, COE, Swaps e Derivativos)."
            }
        }
    },
    "05": {
        "title": "Qual a composição mais aproximada do seu portfólio de investimentos?",
        "options": {
            "A": {
                "title": "Não possuo recursos investidos."
            },
            "B": {
                "title": "A totalidade dos recursos está aplicada em Renda Fixa (CDB, Tesouro Direto e Fundos de Renda Fixa)."
            },
            "C": {
                "title": "Entre 70% e 90% dos recursos estão aplicados em Renda Fixa (LCI, LCA, Debêntures, CRI, CRA, Fundos de Renda Fixa, etc) e entre 10% e 30% dos recursos estão aplicados em Fundos Multimercados, Renda Variável e Derivativos."
            },
            "D": {
                "title": "Mais de 50% dos recursos estão aplicados em Renda Fixa, Fundos Multimercados, Renda Variável e Operações Estruturadas (Fundos Estruturados, COE, Swaps e Derivativos)."
            }
        }
    },
    "06": {
        "title": "Qual opção melhor representa seu conhecimento sobre produtos e serviços financeiros a partir da sua formação acadêmica e experiência profissional?",
        "options": {
            "A": {
                "title": "Não concluí o ensino superior e minha experiência profissional não aprimorou meu conhecimento sobre produtos e serviços financeiros."
            },
            "B": {
                "title": "Concluí o ensino superior, mas minha experiência profissional não aprimorou meu conhecimento sobre produtos e serviços financeiros."
            },
            "C": {
                "title": "Não concluí o ensino superior, mas pela minha experiência profissional desenvolvi conhecimento suficiente sobre produtos e serviços."
            },
            "D": {
                "title": "Concluí o ensino superior e pela minha experiência profissional desenvolvi conhecimento suficiente sobre produtos e serviços financeiros."
            }
        }
    },
    "07": {
        "title": "Qual a sua renda mensal?",
        "options": {
            "A": {
                "title": "Até R$ 5.000,00."
            },
            "B": {
                "title": "De R$ 5.000,01 a R$ 15.000,00."
            },
            "C": {
                "title": "De R$ 15.000,01 a R$ 30.000,00."
            },
            "D": {
                "title": "Acima de R$ 30.000,01."
            }
        }
    },
    "08": {
        "title": "Qual é o valor do seu patrimônio? [ativos não financeiros (residência, terrenos, casa de campo e/ou praia, outros ativos) + ativos financeiros (aplicações financeiras).",
        "options": {
            "A": {
                "title": "Até R$ 500.000,00."
            },
            "B": {
                "title": "De R$ 500.000,01 a R$ 1.500.000,00."
            },
            "C": {
                "title": "De R$ 1.500.000,01 a R$ 3.000.000,00."
            },
            "D": {
                "title": "Acima de R$ 3.000.000,01."
            }
        }
    },
    "09": {
        "title": "Sobre os ativos que compõem o seu patrimônio, qual o percentual dos seus ativos financeiros (ex: aplicações financeiras)?",
        "options": {
            "A": {
                "title": "Cerca de 30% são ativos financeiros."
            },
            "B": {
                "title": "Cerca de 40% são ativos financeiros."
            },
            "C": {
                "title": "Cerca de 60% são ativos financeiros."
            },
            "D": {
                "title": "Cerca de 70% são ativos financeiros."
            }
        }
    }

}
```

---

# Enviar Resposta Suitability

URL: /documentation/iaas/investidor/compartilhado/suitability/enviar_suitability

---
### Introdução
Este recurso tem como objetivo enviar as respostas fornecidas para o formulário suitability respondido pelo investidor.

### Input / Output:
Os dados cadastrais mudam de acordo com os dados passados na etapa de **Criar investidor**. Segue abaixo exemplos de quais dados devem ser enviados para cada variação.

Como ***output*** será entregue uma ***investor_key*** e uma ***investor_analysis_key***. A ***investor_analysis_key*** é utilizada para identificar a **análise cadastral** atualizada.
A ***investor_key*** é utilizada para identificar o **investidor** ao qual a **análise cadastral** pertence.

:::warning Atenção
 O envio do `suitability` é **opcional** para investidores que sejam Pessoa Jurídica enquadradas como qualificadas ou profissionais.
:::

:::info Classe de fundo (`fund_class`) — etapa pulada
Classes de fundo **não respondem suitability**. O bloco não é exigido no `submit` para esse subtipo. Pule esta etapa.
:::

### Request

ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/suitability`
MÉTODO `PUT`
STATUS `202`

Exemplo - Pessoa Jurídica

```json title='Request Body'
{
    "01": "A",
    "02": "A",
    "03": "A",
    "04": "A",
    "05": "A",
    "06": "A",
    "07": "A",
    "08": "A",
    "09": "A"
}
```

### Body params
| Campo                   | Tipo   | Descrição                                                                                          | Caracteres | Obrigatório |
|-------------------------|--------|----------------------------------------------------------------------------------------------------|------------|-------------|
| `01`..`NN`              | string | Resposta para cada questão do formulário. Valor é a letra da alternativa (`A`–`D`)                 |     1      |    Sim*     |

\* As chaves numéricas (`01`, `02`, ...) representam o número da questão; o valor deve ser uma única letra maiúscula correspondente à alternativa escolhida.

### Response
A análise cadastral atualizada é retornada no corpo da resposta.

---

# assinar_documento

URL: /documentation/iaas/investidor/distribuicao_externa/assinar_documento



---

# atualizacao_cadastral

URL: /documentation/iaas/investidor/distribuicao_externa/atualizacao_cadastral



---

# atualizar_status_grupo_assinantes

URL: /documentation/iaas/investidor/distribuicao_externa/atualizar_status_grupo_assinantes



---

# busca_informacoes_de_uma_analise_cadastral_do_investidor

URL: /documentation/iaas/investidor/distribuicao_externa/busca_informacoes_de_uma_analise_cadastral_do_investidor



---

# busca_informacoes_do_investidor

URL: /documentation/iaas/investidor/distribuicao_externa/busca_informacoes_do_investidor



---

# buscar_documentos_para_assinatura

URL: /documentation/iaas/investidor/distribuicao_externa/buscar_documentos_para_assinatura



---

# ciclo_de_vida_da_analise

URL: /documentation/iaas/investidor/distribuicao_externa/ciclo_de_vida_da_analise



---

# consultar_analise_em_andamento

URL: /documentation/iaas/investidor/distribuicao_externa/consultar_analise_em_andamento



---

# atualizar_status_conta_bancaria

URL: /documentation/iaas/investidor/distribuicao_externa/contas_bancarias/atualizar_status_conta_bancaria



---

# definir_conta_principal

URL: /documentation/iaas/investidor/distribuicao_externa/contas_bancarias/definir_conta_principal



---

# enviar_contas_bancarias

URL: /documentation/iaas/investidor/distribuicao_externa/contas_bancarias/enviar_contas_bancarias



---

# Criar investidor

URL: /documentation/iaas/investidor/distribuicao_externa/criar_investidor

---

### Introdução
Este recurso tem como objetivo nos informar dados básicos para iniciar o cadastro de um **investidor**.

A criação de um investidor já dispara, em conjunto, a abertura de uma primeira **análise cadastral** vinculada a ele. Por isso, ao final desta chamada são retornadas duas chaves: ***investor_key*** (identifica o investidor) e ***investor_analysis_key*** (identifica a análise cadastral em andamento).

Existem 3 tipos principais de investidor, definidos pelo campo **`person_type`**: **pessoa física** (`natural_person`), **pessoa jurídica** (`legal_person`) e **PCO** ('nominee'). Para pessoas jurídicas, o campo **`investor_sub_type`** distingue subtipos como **fundo de investimento** (`fund_class`), que possuem regras próprias ao longo do fluxo de cadastro.

:::warning Atenção
Para os casos de investidores distribuídos por conta e ordem (PCO | `nominee`) não existe uma esteira cadastral e portanto, apenas o `POST` de criação é necessário para torná-lo apto em todo o sistema.
:::

:::info Informação
No ambiente de Homologação, temos a seguinte regra para aprovações: CPF/CNPJ com início **1**: reprovação automática; CPF/CNPJ com início **8**: pendente de validação manual; o restante é aprovado automaticamente.
:::

### Input / Output

Como ***input*** envie os dados básicos do investidor. Os campos obrigatórios variam de acordo com **`person_type`** e **`investor_sub_type`**.

Como ***output*** serão retornadas a ***investor_key*** e a ***investor_analysis_key***. A ***investor_key*** identifica o investidor; a ***investor_analysis_key*** identifica a análise cadastral aberta junto com a criação. Um mesmo investidor pode possuir mais de uma análise cadastral ao longo do tempo (renovações, atualizações).

### Request

ENDPOINT `/investor_registry/v2/investor`
MÉTODO `POST`
STATUS `201`

### Request body

Caso 01: Pessoa Física

```json title='Request Body'
{
    "name": "João da Silva",
    "document_number": "123.456.789-00",
    "person_type": "natural_person",
    "email": "joao.silva@example.com",
    "phone": {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "987654321"
    }
}
```

Caso 02: Pessoa Jurídica

```json title='Request Body'
{
    "name": "Empresa XPTO Ltda",
    "document_number": "12.345.678/0001-90",
    "person_type": "legal_person",
    "investor_sub_type": "default",
    "registry_user": {
        "name": "José da Silva",
        "document_number": "123.456.789-00",
        "email": "jose.silva@example.com",
        "phone": {
            "international_dial_code": "55",
            "area_code": "11",
            "number": "987654321"
        }
    }
}
```

Caso 03: Pessoa Jurídica — Fundo de Investimento ( fund_class )

```json title='Request Body'
{
    "name": "Fundo XPTO Multimercado",
    "document_number": "12.345.678/0001-90",
    "person_type": "legal_person",
    "investor_sub_type": "fund_class"
}
```

Caso 04: Nominee (PCO)

```json title='Request Body'
{
    "name": "Nominee XPTO",
    "person_type": "nominee",
    "external_distribution_key": "ID-DISTRIBUICAO-001"
}
```

:::warning Campos obrigatórios por `person_type`
Os campos obrigatórios mudam de acordo com o **`person_type`**. A ausência de qualquer um deles é recusada com `IVR000009`, cuja mensagem lista a relação completa exigida.

- **`natural_person`**: `name`, `document_number`, `person_type`, **`investor_sub_type`**
- **`legal_person`**: `name`, `document_number`, `person_type`, **`investor_sub_type`**
- **`nominee`**: `name`, `person_type`, `external_distribution_key`

**`investor_sub_type` é obrigatório também para pessoa física** — envie `default` quando não houver subtipo específico. `email` e `phone` são opcionais para um distribuidor, mas recomendados: sem `email`, nenhum usuário de acesso é criado para o investidor.
:::

:::info Sobre o `registry_user`
O **`registry_user`** representa o usuário (pessoa física) responsável por preencher os dados cadastrais do investidor. Para **pessoa física**, normalmente este usuário é o próprio investidor e o campo pode ser omitido. Para **pessoa jurídica**, é o representante que responderá pelo preenchimento.

Quando enviado, o objeto exige `name`, `document_number` e `email`. Se omitido em pessoa física, o usuário é derivado do `email` do próprio investidor — e, se o investidor também não tiver `email`, nenhum usuário é criado.
:::

:::warning `investor_owner_type` não é aceito de distribuidores
Apesar de existir no schema, `investor_owner_type` é **recusado** quando o investidor é criado por uma integração de distribuidor com `person_type` `natural_person` ou `legal_person`. Vínculos de carteira administrada e de fundo são estabelecidos pelo endpoint **Criar Investor Owner**, dentro da análise cadastral.
:::

### Investidor não residente {#nao-residente}

A residência é definida **na criação do investidor** e é imutável depois disso. Ela é controlada pelo campo `resident`.

```json title='Request Body — pessoa física não residente'
{
    "name": "Maria Fernandes",
    "document_number": "123.456.789-00",
    "person_type": "natural_person",
    "investor_sub_type": "default",
    "resident": false,
    "non_resident_type": "third_party_representation",
    "investor_owners": [
        {
            "type": "non_resident_representative",
            "name": "Representante Legal Brasil Ltda",
            "document_number": "12.345.678/0001-90"
        }
    ]
}
```

| Campo                | Tipo    | Descrição                                                                                          | Obrigatório |
|----------------------|---------|-----------------------------------------------------------------------------------------------------|-------------|
| `resident`           | boolean | Define a residência da análise cadastral. Default `true`                                             |    Não      |
| `non_resident_type`  | string  | `self_representation` ou `third_party_representation`. Obrigatório quando `resident: false` (`IVR000222`) | Condicional |
| `investor_owners`    | array   | Representante legal residente no Brasil, com `type: "non_resident_representative"`                   |    Não      |

#### Tipos de representação {#non-resident-type}

`non_resident_type` declara **como o investidor não residente é representado no Brasil**. É essa escolha que determina quais entidades você precisa cadastrar e quais documentos serão exigidos no envio para análise.

| Enumerador                   | Tipo de conta                                    | Significado                                                                                                              |
|------------------------------|--------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
| `third_party_representation` | Conta **4373**                                   | O INR opera por meio de terceiros: existe um **custodiante**, responsável pela guarda dos ativos, e um **representante legal brasileiro**, responsável por representá-lo no país. Na prática, costumam ser a mesma entidade. |
| `self_representation`        | Conta **CNR** (autocustódia / representação tributária) | O investidor é seu próprio custodiante e representante. **Não** existe custodiante nem representante terceiro.        |

O que muda entre os dois:

|                              | `third_party_representation`                                                                 | `self_representation`          |
|------------------------------|-----------------------------------------------------------------------------------------------|--------------------------------|
| **Custodiante**              | Parte relacionada do tipo `asset_custodian`                                                    | Não existe                     |
| **Representante**            | Investor owner do tipo `non_resident_representative` — sempre **residente**, com CPF/CNPJ      | Não existe                     |
| **Documentos de representação** | `custody_contract` (no custodiante) **e** `representation_contract` (no representante) — **ou** uma única `simplified_declaration` na análise | Nenhum                     |

:::warning Como a exigência documental é verificada
Em `third_party_representation`, o `custody_contract` só é reconhecido quando enviado em uma parte relacionada **ativa** do tipo `asset_custodian`, e o `representation_contract` só é reconhecido quando enviado em um investor owner **ativo** do tipo `non_resident_representative`. Enviar os dois contratos como documentos da análise cadastral não satisfaz a regra.

Se a combinação não for encontrada no `submit`, a resposta é `IVR000029`.
:::

Regras que valem para **os dois** tipos:

- `nif_number` é **obrigatório** no envio dos dados cadastrais (`IVR000224`);
- parte relacionada estrangeira sem CPF/CNPJ precisa de `passport` ou `foreign_id`;
- pessoa física nascida no Brasil (`natural_person.place_of_birth.country: "BRA"`) precisa de `final_departure_tax_return`.

:::info `non_resident_type` é imutável
O valor é fixado na criação do investidor. Você pode reenviá-lo nos dados cadastrais, mas apenas com o **mesmo** valor — divergência, ou envio em um cadastro residente, resulta em `IVR000225`.
:::

:::warning Residência e endereço precisam concordar
Com `resident: true` (default), o endereço enviado na Etapa 3 precisa ter `country: "BRA"`, senão `IVR000227`. Com `resident: false`, o `country` **não** pode ser `BRA`, senão `IVR000226`.

`postal_code` e `uf` não têm validação de formato, então códigos postais estrangeiros são aceitos como estão. Use `EX` em `uf` para endereços no exterior.
:::

:::info Investidores `fund_class`
Para fundos de investimento (`investor_sub_type: "fund_class"`), parte dos dados cadastrais é preenchida automaticamente a partir da base da CVM no momento do envio para análise — incluindo razão social, data de constituição, patrimônio e vínculos com administrador, gestor e (quando aplicável) investidor exclusivo. Veja o documento **Criar Investor Owner** para o cadastro de relações de propriedade adicionais.
:::

### Body params
| Campo                       | Tipo     | Descrição                                                                                   | Caracteres   | Obrigatório |
|-----------------------------|----------|---------------------------------------------------------------------------------------------|--------------|-------------|
| `name`                      | string   | Nome (ou razão social) do investidor                                                        |   1 - 255    |    Sim      |
| `person_type`               | string   | Enumerador de **[Person Type](#person-type)**                                               |      -       |    Sim      |
| `investor_sub_type`         | string   | Enumerador de **[Investor Sub Type](#investor-sub-type)**. Exigido para `natural_person` e `legal_person` |      -       |    Sim      |
| `document_number`           | string   | CPF (`XXX.XXX.XXX-XX`) ou CNPJ (`XX.XXX.XXX/XXXX-XX`)                                       |   14 ou 18   |    Sim*     |
| `external_distribution_key` | string   | Identificador externo da distribuição (obrigatório para `nominee`)                           |   1 - 100    |    Sim*     |
| `resident`                  | boolean  | Residência da análise cadastral. Default `true`. Veja [Investidor não residente](#nao-residente) |      -       |    Não      |
| `non_resident_type`         | string   | `self_representation` ou `third_party_representation`. Exigido quando `resident: false`      |      -       | Condicional |
| `investor_owners`           | array    | Representante legal residente, para investidor não residente                                |      -       |    Não      |
| `email`                     | string   | E-mail do investidor                                                                        |   1 - 255    |    Não      |
| `phone`                     | object   | Objeto de **[Phone](#phone)**                                                               |      -       |    Não      |
| `registry_user`             | object   | Objeto de **[Registry User](#registry-user)**                                               |      -       |    Não      |
| `external_id`               | string   | Identificador do investidor no seu sistema                                                  |   1 - 50     |    Não      |

\* `document_number` não deve ser enviado para `person_type: nominee`. `external_distribution_key` é exigido apenas para `nominee`.

### Phone
| Campo                       | Tipo     | Descrição                                                                                   | Caracteres   | Obrigatório |
|-----------------------------|----------|---------------------------------------------------------------------------------------------|--------------|-------------|
| `international_dial_code`   | string   | Código internacional (ex.: `55`)                                                            |   1 - 3      |    Sim      |
| `area_code`                 | string   | DDD                                                                                         |      2       |    Sim      |
| `number`                    | string   | Número do telefone                                                                          |   8 - 9      |    Sim      |

### Registry User
| Campo               | Tipo     | Descrição                                            | Caracteres   | Obrigatório |
|---------------------|----------|------------------------------------------------------|--------------|-------------|
| `name`              | string   | Nome do usuário cadastrador                          |   1 - 255    |    Sim      |
| `document_number`   | string   | CPF do usuário (formato `XXX.XXX.XXX-XX`)            |     14       |    Sim      |
| `email`             | string   | E-mail do usuário                                    |   1 - 255    |    Sim      |
| `phone`             | object   | Objeto de **[Phone](#phone)**                        |      -       |    Sim      |

### Person Type {#person-type}
| Enumerador          | Descrição                                            |
|---------------------|------------------------------------------------------|
| `natural_person`    | Pessoa física                                        |
| `legal_person`      | Pessoa jurídica                                      |
| `nominee`           | Nominee / PCO (sem documento obrigatório)            |

### Investor Sub Type {#investor-sub-type}
| Enumerador               | Descrição                                                                                  |
|--------------------------|--------------------------------------------------------------------------------------------|
| `default`                | Investidor regular, pessoa física ou jurídica                                              |
| `fund_class`             | Fundo de investimento — dispara enriquecimento automático com dados públicos da CVM         |
| `financial_institution`  | Instituição financeira. Segue as mesmas regras de `default`                                |
| `non_resident`           | Subtipo de classificação. **Não** define a residência da análise — para isso use `resident` |

### Response
```json title='Response Body'
{
    "investor_key": "UUID",
    "investor_analysis_key": "UUID"
}
```

---

# definir_grupo_assinantes_padrao

URL: /documentation/iaas/investidor/distribuicao_externa/definir_grupo_assinantes_padrao



---

# enviar_cadastro_para_analise

URL: /documentation/iaas/investidor/distribuicao_externa/enviar_cadastro_para_analise



---

# Enviar Dados Cadastrais do Investidor

URL: /documentation/iaas/investidor/distribuicao_externa/enviar_dados_cadastrais

---
### Introdução
Este recurso tem como objetivo enviar os dados cadastrais específicos da pessoa que compõe a **análise cadastral** de um investidor.

O corpo enviado deve conter **um** dos blocos `natural_person` ou `legal_person`, coerente com o `person_type` informado na criação do investidor.

### Input / Output

Como ***input*** envie os dados cadastrais específicos do tipo de investidor.

Como ***output*** será retornada a representação atualizada da análise cadastral. As chaves ***investor_key*** e ***investor_analysis_key*** identificam o investidor e a análise atualizada.

:::info Investidor `fund_class`
Para fundos de investimento (`investor_sub_type: "fund_class"`), as informações da pessoa jurídica (razão social, data de constituição, etc.) são preenchidas **automaticamente** a partir da base da CVM ao enviar a análise para validação. Esta etapa não é necessária para esse subtipo.
:::

### Request

ENDPOINT `/investor_registry/v2/investor/{investor_key}/investor_analysis/{investor_analysis_key}/registry_data`
MÉTODO `PUT`
STATUS `202`

### Request body

Exemplo: Pessoa Física

```json title='Request Body'
{
    "name": "João da Silva",
    "email": "joao.silva@example.com",
    "phone": {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "987654321"
    },
    "natural_person": {
        "birthdate": "1990-05-15",
        "gender": "male",
        "mother_name": "Maria da Silva",
        "nationality": "BRA",
        "place_of_birth": {
            "country": "BRA",
            "uf": "SP",
            "city": "São Paulo"
        },
        "marital_status": "single",
        "spouse": {
            "name": "Maria Santos",
            "document_number": "123.456.789-00"
        },
        "profession": "Engenheiro",
        "occupation": "Engenheiro de Software",
        "occupation_company": {
            "name": "Empresa XYZ Ltda",
            "document_number": "12.345.678/0001-90"
        }
    }
}
```

Exemplo: Pessoa Jurídica

```json title='Request Body'
{
    "name": "Empresa XPTO Ltda",
    "email": "contato@empresaxpto.com.br",
    "phone": {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "1234567890"
    },
    "legal_person": {
        "legal_name": "Empresa XPTO Limitada",
        "constitution_date": "2020-01-15"
    }
}
```

Exemplo: Pessoa Jurídica (`fund_class`)

```json title='Request Body'
{
    "name": "Empresa XPTO Ltda",
    "email": "contato@empresaxpto.com.br",
    "phone": {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "1234567890"
    },
    "legal_person": {
        "giin_number": "XXXXXX.XXXXX.XX.XXX",
    }
}
```

### Body params
| Campo             | Tipo     | Descrição                                                                            | Caracteres | Obrigatório |
|-------------------|----------|--------------------------------------------------------------------------------------|------------|-------------|
| `name`            | string   | Nome (ou razão social) do investidor                                                 |   1 - 255  |    Não      |
| `email`           | string   | E-mail de contato                                                                    |   1 - 255  |    Não      |
| `phone`           | object   | Objeto de **[Phone](#phone)**                                                        |     -      |    Não      |
| `natural_person`  | object   | Objeto de **[Natural Person](#natural-person)** — obrigatório para pessoa física     |     -      |    Sim*     |
| `legal_person`    | object   | Objeto de **[Legal Person](#legal-person)** — obrigatório para pessoa jurídica       |     -      |    Sim*     |

\* É obrigatório enviar **exatamente um** entre `natural_person` ou `legal_person`, de acordo com o `person_type` do investidor.

### Natural Person {#natural-person}
| Campo                  | Tipo   | Descrição                                                       | Caracteres | Obrigatório |
|------------------------|--------|-----------------------------------------------------------------|------------|-------------|
| `birthdate`            | string | Data de nascimento (`YYYY-MM-DD`)                               |     10     |    Sim      |
| `mother_name`          | string | Nome completo da mãe                                            |   1 - 255  |    Sim      |
| `nationality`          | string | Nacionalidade — código ISO de 3 letras (ex.: `BRA`)             |      3     |    Sim      |
| `place_of_birth`       | object | Objeto de **[Place of Birth](#place-of-birth)**                 |     -      |    Sim      |
| `marital_status`       | string | Enumerador de **[Marital Status](#marital-status)**             |     -      |    Sim      |
| `profession`           | string | Profissão                                                       |   1 - 255  |    Sim      |
| `occupation`           | string | Ocupação                                                        |   1 - 255  |    Sim      |
| `gender`               | string | Enumerador de **[Gender](#gender)**                             |     -      |    Não      |
| `spouse`               | object | Objeto de **[Spouse](#spouse)**                                 |     -      |    Não      |
| `occupation_company`   | object | Objeto de **[Occupation Company](#occupation-company)**         |     -      |    Não      |

### Gender {#gender}
| Enumerador | Descrição    |
|------------|--------------|
| `male`     | Masculino    |
| `female`   | Feminino     |

### Marital Status {#marital-status}
| Enumerador                                  | Descrição                                       |
|---------------------------------------------|-------------------------------------------------|
| `single`                                    | Solteiro(a)                                     |
| `married`                                   | Casado(a)                                       |
| `civil_union`                               | União estável                                   |
| `divorced`                                  | Divorciado(a)                                   |
| `widowed`                                   | Viúvo(a)                                        |
| `married_with_partial_community_property`   | Casado(a) em comunhão parcial de bens           |

### Place of Birth {#place-of-birth}
| Campo     | Tipo   | Descrição                                          | Caracteres | Obrigatório |
|-----------|--------|----------------------------------------------------|------------|-------------|
| `country` | string | Código ISO do país (3 letras, ex.: `BRA`)          |     3      |    Não      |
| `uf`      | string | Estado (UF)                                        |     -      |    Não      |
| `city`    | string | Cidade                                             |     -      |    Não      |

### Spouse {#spouse}
| Campo             | Tipo   | Descrição                                                            | Caracteres | Obrigatório |
|-------------------|--------|----------------------------------------------------------------------|------------|-------------|
| `name`            | string | Nome completo do cônjuge                                             |   1 - 255  |    Sim      |
| `document_number` | string | CPF do cônjuge (`XXX.XXX.XXX-XX`)    |   14 |    Sim      |

### Occupation Company {#occupation-company}
| Campo             | Tipo   | Descrição                                                  | Caracteres | Obrigatório |
|-------------------|--------|------------------------------------------------------------|------------|-------------|
| `name`            | string | Nome da empresa                                            |   1 - 255  |    Sim      |
| `document_number` | string | CNPJ da empresa (`XX.XXX.XXX/XXXX-XX`)                     |     18     |    Sim      |

### Legal Person {#legal-person}
| Campo               | Tipo   | Descrição                                                                | Caracteres | Obrigatório |
|---------------------|--------|--------------------------------------------------------------------------|------------|-------------|
| `legal_name`        | string | Razão social da empresa                                                  |   1 - 255  |    Não      |
| `constitution_date` | string | Data de constituição (`YYYY-MM-DD`)                                      |     10     |    Não      |
| `giin_number`       | string | GIIN (`Global Intermediary Identification Number`), quando aplicável     |   1 - 20   |    Não      |

### Phone {#phone}
| Campo                     | Tipo   | Descrição              | Caracteres | Obrigatório |
|---------------------------|--------|------------------------|------------|-------------|
| `international_dial_code` | string | Código internacional   |   1 - 3    |    Sim      |
| `area_code`               | string | DDD                    |     2      |    Sim      |
| `number`                  | string | Número de telefone     |   8 - 9    |    Sim      |

### Response
A análise cadastral atualizada é retornada no corpo da resposta. Para o formato completo, consulte **Busca informações de uma análise cadastral do investidor**.

---

---

# enviar_documento_assinado

URL: /documentation/iaas/investidor/distribuicao_externa/enviar_documento_assinado



---

# enviar_endereco

URL: /documentation/iaas/investidor/distribuicao_externa/enviar_endereco



---

# enviar_grupos_assinantes

URL: /documentation/iaas/investidor/distribuicao_externa/enviar_grupos_assinantes



---

# Enviar Documento do Investidor

URL: /documentation/iaas/investidor/distribuicao_externa/enviar_investor_document

---

### Introdução
Este recurso faz o upload de um documento que compõe a análise cadastral do investidor. Os documentos obrigatórios variam conforme o `person_type` e o `investor_sub_type` do investidor, bem como sua categoria (varejo, qualificado, profissional).

:::warning Atenção
- Este endpoint deve ser chamado **uma vez para cada documento** obrigatório
- A análise cadastral precisa estar no status `pending_registry_data`. Em outro status, a chamada é recusada com `IVR000026`
- Um mesmo `type` só aceita um envio bem-sucedido: veja [Reenvio e documento duplicado](#duplicado)
:::

### Input / Output

Como ***input*** envie o conteúdo do arquivo em **base64**, o tipo do documento e a extensão.

Como ***output*** será retornada a representação do documento criado, identificado por `investor_analysis_document_key`, acompanhada da representação completa da análise cadastral à qual ele pertence.

### Request

ENDPOINT `/investor_registry/v2/investor/{investor_key}/investor_analysis/{investor_analysis_key}/document`
MÉTODO `POST`
STATUS `201`

### Query params
| Campo   | Tipo    | Descrição                                                                                                                | Obrigatório |
|---------|---------|--------------------------------------------------------------------------------------------------------------------------|-------------|
| `force` | boolean | Se `true`, força o envio mesmo quando há validação prévia falha. O documento entra obrigatoriamente em análise manual.   |    Não      |

### Request body

Exemplo: CNH (Pessoa Física)

```json title='Request Body'
{
    "type": "cnh",
    "document_b64": "base64_encoded_document_content",
    "file_extension": "pdf",
    "document_data": {
        "document_type": "CNH",
        "issuer_entity": "DETRAN"
    }
}
```

Exemplo: RG (frente e verso)

```json title='Request Body — Frente'
{
    "type": "rg_front",
    "document_b64": "base64_encoded_document_content",
    "file_extension": "jpeg",
    "document_data": {
        "document_type": "RG",
        "issuer_entity": "SSP",
        "document_number": "20.932.206-8"
    }
}
```
```json title='Request Body — Verso'
{
    "type": "rg_back",
    "document_b64": "base64_encoded_document_content",
    "file_extension": "jpeg"
}
```

Exemplo: Cartão CNPJ (Pessoa Jurídica)

```json title='Request Body'
{
    "type": "cnpj_card",
    "document_b64": "base64_encoded_document_content",
    "file_extension": "pdf"
}
```

### Body params
| Campo            | Tipo   | Descrição                                                          | Caracteres | Obrigatório |
|------------------|--------|--------------------------------------------------------------------|------------|-------------|
| `type`           | string | Enumerador de **[Document Type](#document-type)**                  |     -      |    Sim      |
| `document_b64`   | string | Conteúdo do arquivo codificado em base64                           |     -      |    Sim      |
| `file_extension` | string | Extensão do arquivo. Valores aceitos: `pdf`, `jpeg`                |     -      |    Sim      |
| `document_data`  | object | Metadados livres do documento (ex.: número, órgão emissor)         |     -      |    Não      |
| `observation`    | string | Observação livre sobre o documento                                 |   até 500  |    Não      |

### Document Type {#document-type}

#### Identificação e comprovantes de pessoa física
| Enumerador                     | Descrição                                            | Extensões      |
|--------------------------------|------------------------------------------------------|----------------|
| `cnh`                          | CNH                                                  | `pdf`, `jpeg`  |
| `rg_front`                     | RG — frente                                          | `pdf`, `jpeg`  |
| `rg_back`                      | RG — verso                                           | `pdf`, `jpeg`  |
| `passport`                     | Passaporte (identificação de estrangeiro)            | `pdf`, `jpeg`  |
| `foreign_id`                   | Documento de identidade estrangeiro (ex.: RNE)       | `pdf`, `jpeg`  |
| `proof_of_residence`           | Comprovante de residência                            | `pdf`, `jpeg`  |
| `billing_statement`            | Fatura / extrato                                     | `pdf`, `jpeg`  |

#### Documentos societários de pessoa jurídica
| Enumerador                     | Descrição                                            | Extensões      |
|--------------------------------|------------------------------------------------------|----------------|
| `cnpj_card`                    | Cartão CNPJ                                          | `pdf`, `jpeg`  |
| `social_contract`              | Contrato social                                      | `pdf`, `jpeg`  |
| `company_statute`              | Estatuto                                             | `pdf`, `jpeg`  |
| `board_election_record`        | Ata de eleição estatutária                           | `pdf`, `jpeg`  |
| `financial_statements`         | Demonstrações financeiras                            | `pdf`, `jpeg`  |
| `organizational_chart`         | Organograma societário                               | `pdf`, `jpeg`  |

#### Representação, qualificação e contratos
| Enumerador                     | Descrição                                            | Extensões      |
|--------------------------------|------------------------------------------------------|----------------|
| `power_of_attorney`            | Procuração                                           | `pdf`, `jpeg`  |
| `investor_qualification_proof` | Comprovação de qualificação / enquadramento          | `pdf`, `jpeg`  |
| `wallet_manager_contract`      | Contrato de carteira administrada / intermediação    | `pdf`, `jpeg`  |
| `extra_document`               | Documento avulso, sem tipo específico                | `pdf`, `jpeg`  |

#### Investidor não residente
| Enumerador                     | Descrição                                            | Extensões      |
|--------------------------------|------------------------------------------------------|----------------|
| `custody_contract`             | Contrato de custódia                                 | `pdf`, `jpeg`  |
| `representation_contract`      | Contrato de representação                            | `pdf`, `jpeg`  |
| `simplified_declaration`       | Declaração simplificada                              | `pdf`, `jpeg`  |
| `final_departure_tax_return`   | Declaração final de saída definitiva do país         | `pdf`, `jpeg`  |

:::warning Tipos gerados pela QI Tech
Os tipos `qualified_investor_term`, `professional_investor_term`, `natural_person_registry_form`, `legal_person_registry_form`, `investor_suitability_form` e `adhesion_term` aparecem na consulta do investidor, mas são **gerados pela QI Tech** para assinatura — não devem ser enviados por este endpoint.
:::

### Documentos Obrigatórios {#documentos-obrigatorios}

As combinações abaixo são conjuntos alternativos: basta satisfazer **uma** das opções de cada lista. A validação roda no envio para análise (`submit`) e recusa com `IVR000029`, devolvendo na mensagem a matriz exata que faltou.

#### Pessoa Física (`natural_person`)
Uma das opções:

| Opção | Documentos                                       |
|-------|---------------------------------------------------|
| 1     | `cnh` **+** `proof_of_residence`                 |
| 2     | `rg_front` **+** `rg_back` **+** `proof_of_residence` |

#### Pessoa Jurídica (`legal_person` / `investor_sub_type: default`, `financial_institution`)
Uma das opções — sempre **ao menos um** documento societário **e** as demonstrações financeiras:

| Opção | Documentos                                            |
|-------|--------------------------------------------------------|
| 1     | `board_election_record` **+** `financial_statements`   |
| 2     | `company_statute` **+** `financial_statements`         |
| 3     | `social_contract` **+** `financial_statements`         |

O documento societário exigido depende do tipo jurídico da empresa — daí as três opções. Não é possível enviar apenas `financial_statements`.
:::warning Documentos obrigatórios
Embora esses documentos sejam o mínimo para envio de uma análise, caso, por exemplo, somente o `company_statute` não seja suficiente para definir firmas e poderes do cotista, a análise pode ser recusada exigindo também o `board_election_record`.
:::

#### Pessoa Jurídica — Fundo de Investimento (`investor_sub_type: fund_class`)
**Nenhum documento é exigido.** Os dados do fundo são obtidos por enriquecimento na base da CVM, e a representação é feita pelos investor owners (administrador e gestora).

### Reenvio e documento duplicado {#duplicado}

Um tipo de documento é considerado **satisfeito** assim que existe, para aquela análise, um documento daquele tipo com status `valid` ou `in_manual_analysis`. A partir daí, novos envios do mesmo tipo são recusados:

```json
HTTP 409
{
  "title": "Already exists valid document for investor analysis.",
  "code": "IVR000023"
}
```

Enquanto **todos** os documentos de um tipo estiverem `invalid`, novos envios daquele tipo continuam sendo aceitos — é assim que se corrige um arquivo ilegível.

O tipo `extra_document` é a única exceção: aceita múltiplos envios sempre.

### Validação automática e `status` do documento {#validacao}

Documentos dos tipos `cnh`, `rg_front`, `rg_back` e `proof_of_residence` passam por validação automática (OCR) e voltam com um dos status abaixo. Os demais tipos entram diretamente em `in_manual_analysis`.

| Status              | Significado                                                                 |
|---------------------|------------------------------------------------------------------------------|
| `valid`             | Validado automaticamente                                                     |
| `in_manual_analysis`| Encaminhado para conferência humana                                          |
| `invalid`           | Reprovado na validação automática — reenvie, ou use `force=true`             |

`force=true` pula o efeito da reprovação automática: o documento é registrado como `in_manual_analysis` e passa a satisfazer a exigência do tipo.

:::info Sobre `investor_qualification_proof`
Este documento **não integra a matriz de obrigatórios** e sua ausência nunca bloqueia o `submit`. Ele atua depois: se o `total_financial_applications` declarado estiver abaixo do piso da categoria informada — R$ 1.000.000 para `qualified`, R$ 10.000.000 para `professional` — ele é utilizado para a validação. Investidores `fund_class` são isentos dessa verificação.
:::

### Response

```json title='Response Body'
{
    "investor_analysis_document_key": "UUID",
    "type": "cnh",
    "status": "in_manual_analysis",
    "observation": "Documento emitido em 2019, legibilidade reduzida no verso.",
    "data": {
        "type": "cnh",
        "file_extension": "pdf",
        "document_data": {
            "document_type": "CNH",
            "issuer_entity": "DETRAN"
        }
    },
    "investor_analysis": { }
}
```

| Campo                            | Tipo   | Descrição                                                                    |
|----------------------------------|--------|------------------------------------------------------------------------------|
| `investor_analysis_document_key` | string | Identificador do documento. É a chave usada nas demais rotas de documento     |
| `type`                           | string | Enumerador de **[Document Type](#document-type)**                             |
| `status`                         | string | `valid`, `invalid` ou `in_manual_analysis` — veja [Validação automática](#validacao) |
| `observation`                    | string | Observação enviada na requisição. `null` quando não informada                 |
| `data`                           | object | Eco dos campos enviados, sem o conteúdo em base64                             |
| `investor_analysis`              | object | Representação completa da análise cadastral — mesmo formato de **Busca informações de uma análise cadastral do investidor** |

---

# enviar_patrimonio

URL: /documentation/iaas/investidor/distribuicao_externa/enviar_patrimonio



---

# Enviar Suitability

URL: /documentation/iaas/investidor/distribuicao_externa/enviar_suitability

---
### Introdução
Este recurso registra o **perfil de suitability** do investidor na análise cadastral.

:::info Na distribuição externa você envia o perfil, não as respostas
Diferente das demais superfícies, a integração de distribuição externa **não** responde ao questionário de suitability pela API — não há endpoint de formulário e não se enviam respostas numeradas. Você aplica o suitability no seu próprio canal e informa aqui apenas o **resultado**: `conservative`, `moderate` ou `bold`.
:::

### Request

ENDPOINT `/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/suitability`
MÉTODO `PUT`
STATUS `202`

### Request body

```json title='Request Body'
{
   "profile": "bold"
}
```

### Body params
| Campo     | Tipo   | Descrição                                        | Obrigatório |
|-----------|--------|--------------------------------------------------|-------------|
| `profile` | string | Enumerador de **[Profile](#profile)**            |    Sim      |

`profile` é o **único** campo aceito. Qualquer outra propriedade no corpo é recusada com `QIT000001`.

### Profile {#profile}
| Enumerador       | Descrição                                                                    |
|------------------|--------------------------------------------------------------------------------|
| `conservative`   | Conservador                                                                    |
| `moderate`       | Moderado                                                                       |
| `bold`           | Arrojado                                                                       |
| `not_applicable` | O suitability não se aplica a este investidor — ver **[Suitability não aplicável](#not-applicable)** |

### Response

A resposta devolve os **dados cadastrais da análise** já atualizados, com o objeto `suitability` preenchido:

```json title='Response Body'
{
  "natural_person": { "...": "..." },
  "address": { "...": "..." },
  "net_worth": { "...": "..." },
  "suitability": {
    "profile": "bold"
  }
}
```

---

### Quando o envio é obrigatório

| Investidor                                        | Suitability                                                        |
|---------------------------------------------------|--------------------------------------------------------------------|
| **Pessoa física**                                 | **Obrigatório** — sem ele o `submit` falha com `IVR000150`          |
| **Pessoa jurídica** enquadrada como `retail`      | **Obrigatório** — sem ele o `submit` falha com `IVR000133`          |
| **Pessoa jurídica** `qualified` ou `professional` | **Opcional** — simplesmente não chame este endpoint                 |

### Suitability não aplicável {#not-applicable}

Quando o suitability não se aplica ao investidor, envie `profile: "not_applicable"` neste mesmo endpoint:

```json title='Request Body'
{
   "profile": "not_applicable"
}
```

A análise passa a registrar `suitability: {"profile": "not_applicable"}`.

:::info `not_applicable` é exclusivo da distribuição externa
Este valor só é aceito de integrações de distribuição externa. Nas superfícies internas da QI Tech a declaração é recusada com `IVR000244`.
:::

### Pré-condições e erros

| Código      | HTTP | Quando ocorre                                                                        |
|-------------|------|----------------------------------------------------------------------------------------|
| `IVR000018` | 400  | A análise não está em `pending_registry_data`                                          |
| `QIT000001` | 400  | `profile` ausente, fora do enumerador, ou corpo com propriedade extra                  |
| `IVR000008` | 404  | Investidor não encontrado para as credenciais utilizadas                               |
| `IVR000133` | 400  | *(no `submit`)* pessoa jurídica `retail` sem suitability                               |
| `IVR000150` | 400  | *(no `submit`)* pessoa física sem suitability                                          |

O envio pode ser repetido enquanto a análise estiver em `pending_registry_data` — o último perfil enviado substitui o anterior.

---

# consultar_feedback

URL: /documentation/iaas/investidor/distribuicao_externa/feedback/consultar_feedback



---

# enviar_mensagem_feedback

URL: /documentation/iaas/investidor/distribuicao_externa/feedback/enviar_mensagem_feedback



---

# listar_feedbacks

URL: /documentation/iaas/investidor/distribuicao_externa/feedback/listar_feedbacks



---

# Introdução

URL: /documentation/iaas/investidor/distribuicao_externa/introducao

Esta seção descreve o fluxo de cadastro de investidores no contexto de **Distribuição Externa** — quando os investidores são captados por um distribuidor externo e aportam em produtos da QI Tech por meio dele — através da integração de distribuição externa (`distributor-integration`).

Embora o esqueleto do cadastro seja semelhante ao de um investidor padrão (dados cadastrais, contas bancárias, suitability, grupos de assinantes, partes relacionadas e investor owner quando aplicável), o vínculo com o distribuidor responsável é o que diferencia este fluxo dos demais.

Além disso, existem duas formas diferentes de criar investidores distribuídos externamente: uma com identificação do investidor e outra **PCO** (Por Conta e Ordem). Para o caso de investidores PCO, é necessário apenas o `POST` de criação do investidor e ele já estará apto a investir em todo o sistema.

:::warning Investor Owner
O sistema de cadastro de investidor trabalha com o conceito de investor-owner, que nada mais é do que um investidor que é "dono" de outro investidor. Os casos de uso para isso são investidores cadastrados como carteira administrada e fundos de investimento. Portanto, para fundos de investimento e investidores de carteira administrada é necessário que os gestores/administrador estejam devidamente identificados e atualizados dentro do sistema.
:::

### Fluxo de Cadastro — Investidor Identificado

1. Criar Investidor
criação inicial do investidor e abertura da primeira análise cadastral
↓
2. Enviar Dados Cadastrais
dados específicos da pessoa física ou jurídica
↓
3. Enviar Endereço
informações de endereço
↓
4. Enviar Patrimônio
informações de patrimônio e enquadramento
↓
5. Enviar Contas Bancárias
contas para movimentação
↓
6. Enviar Suitability
questionário de adequação ao perfil
↓
7. Enviar Grupos de Assinantes
definição de quem deve assinar os documentos
↓
8. Enviar Documentos do Investidor
upload de documentos obrigatórios
↓
9. Criar Partes Relacionadas
sócios, diretores, beneficiários finais
↓
10. Enviar Documentos das Partes Relacionadas
documentos de cada parte relacionada
↓
11. Enviar para Análise
submissão da análise cadastral para validação
↓
12. Assinar Documentos
assinatura dos documentos gerados após aprovação

### Fluxo de Cadastro — Por Conta e Ordem (PCO)

1. Criar Investidor
criação inicial do investidor — não há esteira cadastral adicional para PCO

Nas subseções a seguir veremos cada uma das etapas necessárias para concluir o cadastro de um investidor via Distribuição Externa e disparar a análise cadastral pela QI Tech.

---

# criar_investor_owner

URL: /documentation/iaas/investidor/distribuicao_externa/investor_owner/criar_investor_owner



---

# enviar_documento_investor_owner

URL: /documentation/iaas/investidor/distribuicao_externa/investor_owner/enviar_documento_investor_owner



---

# atualizar_parte_relacionada

URL: /documentation/iaas/investidor/distribuicao_externa/related_party/atualizar_parte_relacionada



---

# atualizar_status_parte_relacionada

URL: /documentation/iaas/investidor/distribuicao_externa/related_party/atualizar_status_parte_relacionada



---

# criar_parte_relacionada

URL: /documentation/iaas/investidor/distribuicao_externa/related_party/criar_parte_relacionada



---

# enviar_documento_parte_relacionada

URL: /documentation/iaas/investidor/distribuicao_externa/related_party/enviar_documento_parte_relacionada



---

# Recuperando Informações da Posição do Investidor

URL: /documentation/iaas/investidor/informacoes_posicao_investidor

---

### Request

ENDPOINT /quota/investor/INVESTOR_KEY/investor_positions
MÉTODO GET

### Query Params

| Parâmetro                    | Descrição                                                                            |
|------------------------------|--------------------------------------------------------------------------------------|
| `issuance_serie_key`         | Chave única de identificação da série de emissão                                     |
| `only_above_zero`            | Posições atuais com número de cotas maior que zero                                   |
| `fund_class_document_number` | CNPJ do Fundo                                                                        |

### Responses

STATUS 200

Caso 01: Investidor com Posição em somente uma série de COTA ÚNICA

```json
{
    "data": [
        {
            "investor_position_key":"UUID",
            "investor": {
                "distributor": {
                    "distributor_key": "UUID",
                    "document_number": "00.000.000/0000-00",
                    "name": "SAMPLE DISTRIBUTOR NAME",
                    "account_data": {
                        "owner": {
                            "name": "SAMPLE DISTRIBUTOR NAME",
                            "document_number": "00.000.000/0000-00"
                        },
                        "account_digit": "0",
                        "account_branch": "0000",
                        "account_number": "00000",
                        "financial_institution_code": "000",
                        "financial_institution_ispb": "00000000"
                    }
                },
                "investor_key": "UUID",
                "document_number": "00.000.000/0000-00",
                "name": "SAMPLE INVESTOR NAME",
                "person_type": "natural_person / legal_person / fund_class",
                "account_data": {
                    "account_digit": "0",
                    "account_branch": "0000",
                    "account_number": "00000",
                    "financial_institution_code": "000",
                    "financial_institution_ispb": "00000000"
                },
                "investor_sub_type": "person / financial_institution"
            },
            "total_net_worth": 0.00,
            "total_number_of_quotas": 0.00000000000000,
            "issuance_serie": {
                "name": "1",
                "cetip_code": "0000000UN1",
                "start_date": "YYYY-MM-DD",
                "maturity_date": "YYYY-MM-DD",
                "original_quota_value": 0.00000000000000,
                "remuneration_type": "residual",
                "investment_category": "fidc / multi_market",
                "condominum_type": "open_ended / close_ended",
                "tax_classification": "short_term / long_term",
                "investment_restriction_type": "just_professional",
                "issuance_serie_key": "UUID",
                "minimum_share_capital": 0.0,
                "accounting_date": "YYYY-MM-DD",
                "sub_class": {
                    "name": "COTA ÚNICA",
                    "sub_class_key": "UUID",
                    "subordination_level": 0,
                    "fund_class": {
                        "name": "SAMPLE FUND CLASS NAME",
                        "fund_class_key": "UUID",
                        "document_number": "00.000.000/0000-00"
                    }
                }
            }
        },
    ],
    "limit": 50,
    "page": 0,
    "is_last_page": true
}
```

Caso 02: Investidor com Posição em somente uma série de COTA SÊNIOR
```json
{
    "data": [
        {
            "investor_position_key":"UUID",
            "investor": {
                "distributor": {
                    "distributor_key": "UUID",
                    "document_number": "00.000.000/0000-00",
                    "name": "SAMPLE DISTRIBUTOR NAME",
                    "account_data": {
                        "owner": {
                            "name": "SAMPLE DISTRIBUTOR NAME",
                            "document_number": "00.000.000/0000-00"
                        },
                        "account_digit": "0",
                        "account_branch": "0000",
                        "account_number": "00000",
                        "financial_institution_code": "000",
                        "financial_institution_ispb": "00000000"
                    }
                },
                "investor_key": "UUID",
                "document_number": "00.000.000/0000-00",
                "name": "SAMPLE INVESTOR NAME",
                "person_type": "natural_person / legal_person / fund_class",
                "account_data": {
                    "account_digit": "0",
                    "account_branch": "0000",
                    "account_number": "00000",
                    "financial_institution_code": "000",
                    "financial_institution_ispb": "00000000"
                },
                "investor_sub_type": "person / financial_institution"
            },
            "total_net_worth": 0.00,
            "total_number_of_quotas": 0.00000000000000,
            "issuance_serie": {
                "name": "1",
                "cetip_code": "0000000SN1",
                "start_date": "YYYY-MM-DD",
                "maturity_date": "YYYY-MM-DD",
                "original_quota_value": 0.00000000000000,
                "remuneration_type": "yield_curve",
                "interest_rate_type": "post_fixed",
                "pre_fixed": {
                    "calendar_base": "workdays / calendar_360 / calendar_365",
                    "monthly_rate": 0.00000000000000
                },
                "post_fixed": {
                    "calendar_base": "workdays / calendar_360 / calendar_365",
                    "indexer": "di / ipca",
                    "rate": 1,
                    "lag": {"reference": "daily / monthly", "amount": 1},
                },
                "investment_category": "fidc / multi_market",
                "condominum_type": "open_ended / close_ended",
                "tax_classification": "short_term / long_term",
                "investment_restriction_type": "just_professional",
                "issuance_serie_key": "UUID",
                "minimum_share_capital": 0.0,
                "accounting_date": "YYYY-MM-DD",
                "sub_class": {
                    "name": "COTA SÊNIOR",
                    "sub_class_key": "UUID",
                    "subordination_level": 1,
                    "fund_class": {
                        "name": "SAMPLE FUND CLASS NAME",
                        "fund_class_key": "UUID",
                        "document_number": "00.000.000/0000-00"
                    }
                }
            }
        },
    ],
    "limit": 50,
    "page": 0,
    "is_last_page": true
}
```

Caso 03: Investidor com Posição em duas uma séries, uma COTA SÊNIOR e uma COTA SUBORDINADA
```json
{
   "data":[
      {
         "investor_position_key":"UUID",
         "investor":{
            "distributor":{
               "distributor_key":"UUID",
               "document_number":"00.000.000/0000-00",
               "name":"SAMPLE DISTRIBUTOR NAME",
               "account_data":{
                  "owner":{
                     "name":"SAMPLE DISTRIBUTOR NAME",
                     "document_number":"00.000.000/0000-00"
                  },
                  "account_digit":"0",
                  "account_branch":"0000",
                  "account_number":"00000",
                  "financial_institution_code":"000",
                  "financial_institution_ispb":"00000000"
               }
            },
            "investor_key":"UUID",
            "document_number":"00.000.000/0000-00",
            "name":"SAMPLE INVESTOR NAME",
            "person_type":"natural_person / legal_person / fund_class",
            "account_data":{
               "account_digit":"0",
               "account_branch":"0000",
               "account_number":"00000",
               "financial_institution_code":"000",
               "financial_institution_ispb":"00000000"
            },
            "investor_sub_type":"person / financial_institution"
         },
         "total_net_worth":0.00,
         "total_number_of_quotas":0.00000000000000,
         "issuance_serie":{
            "name":"1",
            "cetip_code":"0000000SN1",
            "start_date":"YYYY-MM-DD",
            "maturity_date":"YYYY-MM-DD",
            "original_quota_value":0.00000000000000,
            "remuneration_type":"yield_curve",
            "interest_rate_type":"post_fixed",
            "pre_fixed":{
               "calendar_base":"workdays / calendar_360 / calendar_365",
               "monthly_rate":0.00000000000000
            },
            "post_fixed":{
               "calendar_base":"workdays / calendar_360 / calendar_365",
               "indexer":"di / ipca",
               "rate":1,
               "lag":{
                  "reference":"daily / monthly",
                  "amount":1
               }
            },
            "investment_category":"fidc / multi_market",
            "condominum_type":"open_ended / close_ended",
            "tax_classification":"short_term / long_term",
            "investment_restriction_type":"just_professional",
            "issuance_serie_key":"UUID",
            "minimum_share_capital":0.0,
            "accounting_date":"YYYY-MM-DD",
            "sub_class":{
               "name":"COTA SÊNIOR",
               "sub_class_key":"UUID",
               "subordination_level":1,
               "fund_class":{
                  "name":"SAMPLE FUND CLASS NAME",
                  "fund_class_key":"UUID",
                  "document_number":"00.000.000/0000-00"
               }
            }
         }
      },
      {
         "investor_position_key":"UUID",
         "investor":{
            "distributor":{
               "distributor_key":"UUID",
               "document_number":"00.000.000/0000-00",
               "name":"SAMPLE DISTRIBUTOR NAME",
               "account_data":{
                  "owner":{
                     "name":"SAMPLE DISTRIBUTOR NAME",
                     "document_number":"00.000.000/0000-00"
                  },
                  "account_digit":"0",
                  "account_branch":"0000",
                  "account_number":"00000",
                  "financial_institution_code":"000",
                  "financial_institution_ispb":"00000000"
               }
            },
            "investor_key":"UUID",
            "document_number":"00.000.000/0000-00",
            "name":"SAMPLE INVESTOR NAME",
            "person_type":"natural_person / legal_person / fund_class",
            "account_data":{
               "account_digit":"0",
               "account_branch":"0000",
               "account_number":"00000",
               "financial_institution_code":"000",
               "financial_institution_ispb":"00000000"
            },
            "investor_sub_type":"person / financial_institution"
         },
         "total_net_worth":0.00,
         "total_number_of_quotas":0.00000000000000,
         "issuance_serie":{
            "name":"1",
            "cetip_code":"0000000JR1",
            "start_date":"YYYY-MM-DD",
            "maturity_date":"YYYY-MM-DD",
            "original_quota_value":0.00000000000000,
            "remuneration_type":"residual",
            "investment_category":"fidc / multi_market",
            "condominum_type":"open_ended / close_ended",
            "tax_classification":"short_term / long_term",
            "investment_restriction_type":"just_professional",
            "issuance_serie_key":"UUID",
            "minimum_share_capital":0.0,
            "accounting_date":"YYYY-MM-DD",
            "sub_class":{
               "name":"COTA SUBORDINADA",
               "sub_class_key":"UUID",
               "subordination_level":0,
               "fund_class":{
                  "name":"SAMPLE FUND CLASS NAME",
                  "fund_class_key":"UUID",
                  "document_number":"00.000.000/0000-00"
               }
            }
         }
      }
   ],
   "limit":50,
   "page":0,
   "is_last_page":true
}
```

### Response Fields

| Campo         | Tipo   | Descrição                                                      |
|---------------|--------|----------------------------------------------------------------|
| `data`        | array  | Lista de objetos de **[Investor Position](#investor_position)**|
| `limit`       | int    | Limite de objetos recuperados por página                       |
| `page`        | int    | Número da página recuperada                                    |
| `is_last_page`| boolean| Informação que indica se a página recuperada é a última        |

### Investor Position {#investor_position}
| Campo                    | Tipo   | Descrição                                             |
|--------------------------|--------|-------------------------------------------------------|
| `investor`               | JSON   | Objeto de **[Investor](#investor)**                   |
| `total_net_worth`        | float  | Patrimônio Líquido da posição do investidor           |
| `total_number_of_quotas` | float  | Número de cotas da posição do investidor              |
| `issuance_serie`         | JSON   | Objeto de **[Issuance Serie](#issuance_serie)**       |
| `investor_position_key`  | JSON   | Chave única de identificação da posição do investidor |

### Investor
| Campo                    | Tipo     | Descrição                                         | Caracteres |
|--------------------------|----------|---------------------------------------------------|------------|
| `name`                   | string   | Nome do investidor                                | até 255    |
| `investor_key`           | string   | Chave única de identificação do investidor        | 36         |
| `document_number`        | string   | CPF/CNPJ do investidor                            | 14 ou 18   |
| `person_type`            | string   | Pessoa Física / Pessoa Jurídica / Classe de Fundo | até 50     |
| `investor_sub_type`      | string   | Default / Instituição Financeira                  | até 50     |
| `distributor`            | JSON     | Objeto de **[Distributor](#distributor)**         |     -      |             
| `account_data`           | JSON     | Objeto de **[Account Data](#account_data)**       |     -      |

### Distributor
| Campo                    | Tipo     | Descrição                                         | Caracteres |
|--------------------------|----------|---------------------------------------------------|------------|
| `name`                   | string   | Nome do distribuidor                              | até 255    |
| `distributor_key`        | string   | Chave única de identificação do distribuidor      |     -      |             
| `document_number`        | string   | CPF/CNPJ do distribuidor                          | 14 ou 18   |
| `account_data`           | JSON     | Objeto de **[Account Data](#account_data)**       |     -      |

### Account Data {#account_data}
| Campo                        | Tipo     | Descrição                                                                   |
|------------------------------|----------|-----------------------------------------------------------------------------|
| `account_digit`              | string   | Dígito da conta bancária                                                    |
| `account_branch`             | string   | N° da agência da conta bancária                                             |             
| `account_number`             | string   | N° da conta bancária                                                        |
| `financial_institution_code` | string   | Código da instituição financeira                                            |
| `financial_institution_ispb` | string   | Identificador no Sistema de Pagamento Brasileiro da instituição financeira  |

### Issuance Serie {#issuance_serie}
| Campo                         | Tipo     | Descrição                                         | Caracteres |
|-------------------------------|----------|---------------------------------------------------|------------|
| `name`                        | string   | Nome da série de emissão                          | até 255    |
| `issuance_serie_key`          | string   | Chave única de identificação da série de emissão  | 36         |
| `cetip_code`                  | string   | Código da série de emissão como ativo na CETIP    | 10         |             
| `start_date`                  | string   | Data de início da série de emissão                | 10         |
| `maturity_date`               | string   | Data de vencimento da série de emissão            | 10         |
| `original_quota_value`        | float    | Valor de cota original                            | -          |
| `remuneration_type`           | string   | Curva de rendimento / Residual                    | até 50     |
| `investment_category`         | string   | FIDC / Multimercado                               | até 50     |
| `condominum_type`             | string   | Aberto / Fechado                                  | até 50     |
| `tax_classification`          | string   | Curto prazo / Longo prazo                         | até 50     |
| `investment_restriction_type` | string   | Sem restrição / Qualificado / Profissional        | até 50     |
| `minimum_share_capital`       | float    | Valor mínimo para aplicação                       | -          |
| `accounting_date`             | string   | Data contábil da série de emissão                 | 10         |
| `sub_class`                   | JSON     | Objeto de **[Sub Class](#sub_class)**             | -          |

### Sub Class {#sub_class}
| Campo                         | Tipo     | Descrição                                         | Caracteres |
|-------------------------------|----------|---------------------------------------------------|------------|
| `name`                        | string   | Nome da sub classe                                | até 255    |
| `sub_class_key`               | string   | Chave única de identificação da sub classe        | 36         |
| `subordination_level`         | int      | Nível de subordinação da sub classe               | -          |             
| `fund_class`                  | JSON     | Objeto de **[Fund Class](#fund_class)**           | -          |

### Fund Class {#fund_class}
| Campo                         | Tipo     | Descrição                                         | Caracteres |
|-------------------------------|----------|---------------------------------------------------|------------|
| `name`                        | string   | Nome da classe de fundo                           | até 255    |
| `fund_class_key`              | string   | Chave única de identificação da classe de fundo   | 36         |
| `document_number`             | string   | CNPJ da classe de fundo                           | -          |

---

# Introdução

URL: /documentation/iaas/investidor/inicio

Nesta seção iremos explicar as ferramentas disponibilizadas para consultar as informações relacionadas ao Investidor.

Para ter acesso a esses serviços, entre em contato com o time [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br), para que seja feito as devidas liberações, tanto em ambiente de Homologação (Sandbox), quanto em ambiente produtivo.

### Informações da Posição do Investidor

Nesta ferramenta é possível resgatar uma lista de informações da Posição de Investimento do investidor, conforme descrito em: [5.8.2 Informações da Posição do Investidor](/documentation/iaas/investidor/informacoes_posicao_investidor).

### Informações sobre Boletim de Subscrição

Nesta ferramenta é possível resgatar uma lista de informações sobre os boletins de subscrição do investidor, conforme descrito em: [5.8.4 Informações sobre Boletim de Subscrição](/documentation/iaas/passivo/controle_de_oferta/informacoes_boletins_de_subscricao).

---

# Layout CNAB 444 — Baixa

URL: /documentation/iaas/liquidacao_ativos/arquivo/cnab444_baixa

Layout do arquivo de **remessa de baixa** (liquidação) aceito pela QI CTVM. A estrutura é a mesma do [arquivo de cessão](/documentation/iaas/negociacao_recebiveis/arquivo/cnab444): 444 posições, header `0`, detalhes `1` e trailer `9`. O que muda é o **código de ocorrência**, o **valor pago** e a **data da liquidação**.

:::tip Reaproveite a linha da cessão
A forma mais segura de montar o arquivo de baixa é partir da linha enviada na cessão e alterar apenas três campos: ocorrência (109–110), valor pago (083–092) e data da liquidação (095–100). O identificador do ativo — nº de controle do participante — **precisa ser exatamente o mesmo** usado na cessão.
:::

## O que muda em relação ao arquivo de cessão

| Posição | Campo | Na cessão | Na baixa |
|---|---|---|---|
| 083–092 | Valor pago | Zeros | **Valor efetivamente pago**, 2 decimais |
| 095–100 | Data da liquidação | Zeros | **Data do pagamento**, `DDMMAA` |
| 109–110 | Identificação da ocorrência | `01` | `04`, `14`, `75` ou `77` |
| 150–150 | Identificação | Livre | Branco ou `0` |
| 157–158 | 1ª instrução | Livre | `00` |
| 159–159 | 2ª instrução | Livre | `0` |
| 381–394 | CNPJ do cedente | Conferido o nome | **CNPJ conferido com dígito verificador** |

Todos os demais campos seguem as mesmas regras de preenchimento, domínios e obrigatoriedades da [tabela do registro de detalhe da cessão](/documentation/iaas/negociacao_recebiveis/arquivo/cnab444#registro-detalhe).

## Ocorrências aceitas

| Código | Significado | Efeito na carteira | Origem do recurso |
|---|---|---|---|
| `77` | **Baixa por depósito do sacado** | Liquidação integral do ativo (`asset_settlement`) | Sacado |
| `14` | **Pagamento parcial** | Amortização do ativo (`asset_amortization`) | Sacado |
| `75` | **Baixa por depósito do cedente** | Liquidação integral do ativo (`asset_settlement`) | Cedente |
| `04` | **Pagamento a menor** | Liquidação do ativo (`asset_settlement`) | Sacado |

:::caution Só essas quatro
Qualquer outro código de ocorrência recusa o arquivo com a mensagem *"This field only allows one of this values: ['04', '14', '75', '77']"*. Ocorrências de aquisição (`01`, `80`, `81`, `84`) pertencem ao [arquivo de cessão](/documentation/iaas/negociacao_recebiveis/arquivo/cnab444).
:::

## Como o ativo é identificado

| Tipo de ativo | Campo usado como identificador | Complemento |
|---|---|---|
| Duplicatas, CT-e e contratos | **Nº de controle do participante** (038–062) | — |
| CCB e demais operações de crédito | **Nº do documento** (111–120), que corresponde ao número do contrato | A parcela é identificada pela **data de vencimento** (121–126) |

:::caution O identificador precisa bater com o da cessão
Se o número de controle do participante não corresponder a um ativo encarteirado no fundo, aquela liquidação falha individualmente no processamento — o lote continua, mas termina como `processed_with_failures`.
:::

## Exemplo comentado

Baixa de dois títulos cedidos no exemplo de cessão: o primeiro liquidado integralmente pelo sacado, o segundo com pagamento parcial.

```text title="CB101001.REM"
01REMESSA01COBRANCA       00000011222333000181INDUSTRIA EXEMPLO S/A         ...MX...000001
1...0CTRL000001...0000151000  101025        77000100001101025...COMERCIO EXEMPLO ALFA LTDA...000002
1...0CTRL000002...0000050000  101025        14000200002101025...COMERCIO EXEMPLO BETA LTDA...000003
9                                                                              ...000004
```

| Linha | Leitura |
|---|---|
| Detalhe 1 | Ativo `CTRL000001` liquidado em 10/10/2025 — ocorrência `77`, valor pago R$ 1.510,00 (integral) |
| Detalhe 2 | Ativo `CTRL000002` amortizado em 10/10/2025 — ocorrência `14`, valor pago R$ 500,00 (parcial) |

### Arquivos de exemplo

| Arquivo | Espécie | O que traz |
|---|---|---|
| [Baixa de duplicatas](/downloads/modelos_arquivo/exemplo_baixa_duplicatas_cnab444.rem) | `01` | Uma liquidação integral (`77`) e um pagamento parcial (`14`), identificados pelo nº de controle do participante |
| [Baixa de CCB](/downloads/modelos_arquivo/exemplo_baixa_ccb_cnab444.rem) | `41` | Duas parcelas identificadas pelo número do contrato e pela data de vencimento |

## Checklist antes de enviar

- [ ] Todas as linhas com exatamente 444 caracteres
- [ ] Ocorrência `04`, `14`, `75` ou `77` nas posições 109–110
- [ ] Valor pago preenchido nas posições 083–092, com 2 decimais e sem vírgula
- [ ] Data da liquidação preenchida nas posições 095–100, no formato `DDMMAA`
- [ ] Nº de controle do participante idêntico ao enviado na cessão
- [ ] CNPJ do cedente (381–394) e CPF/CNPJ do sacado (221–234) com dígito verificador válido
- [ ] 1ª instrução `00`, 2ª instrução `0` e identificação (150) em branco
- [ ] Sem acentos, `Ç` ou caracteres especiais
- [ ] Trailer fechando o arquivo com o sequencial da última linha

---

# Baixa por Arquivo

URL: /documentation/iaas/liquidacao_ativos/arquivo/inicio

A baixa (liquidação) de ativos já encarteirados no fundo pode ser feita de duas formas: **enviando um arquivo** com todas as liquidações do dia, pelo portal do gestor/consultor, ou **inserindo liquidação a liquidação pela API**. As duas produzem o mesmo lote de pagamento e passam pela mesma conciliação.

| | Envio por arquivo | Inserção pela API |
|---|---|---|
| **Como funciona** | Um arquivo com todas as liquidações | Uma requisição por liquidação |
| **Formatos** | CNAB 444 e CSV | JSON |
| **Disponível em** | Portal do gestor e do consultor | [API de Liquidação de Ativos](/documentation/iaas/liquidacao_ativos/inicio) |
| **Indicado para** | Rotina diária de baixas em volume, a partir do retorno bancário | Baixas pontuais e integrações em tempo real |

:::info Baixa por arquivo é um fluxo de tela
Hoje o envio de arquivo de baixa está disponível no **portal**. Pela API de integração, a baixa é feita pelo fluxo de [lote de pagamento + liquidações](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao), sem arquivo.
:::

## Formatos aceitos

| Formato | Extensão | Indicado para | Modelo |
|---|---|---|---|
| **CNAB 444** — duplicatas e CT-e | `.rem` · `.txt` | Quem já recebe retorno CNAB do banco cobrador. Layout em [Layout CNAB 444 — Baixa](/documentation/iaas/liquidacao_ativos/arquivo/cnab444_baixa) | [Exemplo](/downloads/modelos_arquivo/exemplo_baixa_duplicatas_cnab444.rem) |
| **CNAB 444** — CCB e operações de crédito | `.rem` · `.txt` | Mesmo layout, com o ativo identificado pelo número do contrato | [Exemplo](/downloads/modelos_arquivo/exemplo_baixa_ccb_cnab444.rem) |
| **CSV** | `.csv` | Planilha simples, com uma linha por liquidação, para qualquer tipo de ativo. Layout na seção [CSV de baixa](#csv-de-baixa) | [Exemplo](/downloads/modelos_arquivo/exemplo_baixa_liquidacoes.csv) |

## Passo a passo pela tela

1. Acesse **Ativos › Liquidações** e clique em **Novo lote por arquivo**.
2. Informe uma **descrição** para identificar o lote.
3. Selecione a **conta do fundo** que receberá o crédito das liquidações.
4. Arraste o arquivo (`.rem`, `.txt` ou `.csv`) e confirme.

O portal cria o lote de pagamento, envia o arquivo e dispara a validação. A tela passa a mostrar o lote com o progresso — total de liquidações, processadas e falhas.

## O que acontece depois do envio

| Etapa do lote | O que significa |
|---|---|
| Aguardando arquivo | Lote criado, arquivo ainda não enviado |
| Validação em andamento | Arquivo recebido, sendo conferido linha a linha |
| Criando o lote | Arquivo válido, lote de pagamento sendo criado |
| Inserindo as liquidações | Cada linha está virando uma liquidação |
| Concluído | Todas as liquidações processadas |
| Concluído com falhas | Lote processado, mas com liquidações que falharam individualmente |
| Recusado | Arquivo recusado na validação — nada foi processado |

:::caution Validação é tudo ou nada
Uma linha inválida recusa o arquivo inteiro. O portal informa o número da linha e a descrição do erro. Corrija e envie um lote novo, com um novo identificador.
:::

Depois que o lote é encerrado e o pagamento confirmado, cada liquidação é conciliada individualmente na carteira do fundo — o mesmo comportamento descrito no [Fluxo de liquidação](/documentation/iaas/liquidacao_ativos/fluxo_liquidacao). Uma liquidação pode falhar sozinha (por exemplo, ativo não encontrado na carteira) sem derrubar as demais.

## CSV de baixa

Arquivo com cabeçalho na primeira linha, separado por `;` ou `,`. Limite de 850.000 linhas.

```csv title="exemplo_baixa_liquidacoes.csv"
asset_type;total_value;settlement_type;external_id;installment_number;collection_origin_type
duplicata_mercantil;1510.00;asset_settlement;CTRL000001;;borrower
duplicata_mercantil;500.00;asset_amortization;CTRL000002;;borrower
ccb;350.75;installment_settlement;CONTRATO-0001;3;borrower
```

### Colunas

| Coluna | Obrigatoriedade | Descrição |
|---|---|---|
| `asset_type` | obrigatória | Tipo do ativo. Ver [valores aceitos](#tipos-de-ativo-aceitos) |
| `total_value` | obrigatória | Valor da liquidação. Aceita `.` ou `,` como separador decimal |
| `settlement_type` | obrigatória | Tipo de liquidação. Ver [tipos de liquidação](#tipos-de-liquidação) |
| `installment_number` | obrigatória (coluna) | Número da parcela. Preencha para ativos com parcelas (CCB); deixe vazio para duplicatas e contratos |
| `external_id` **ou** `contract_number` | obrigatória | Identificador do ativo. Use `external_id` para duplicatas/contratos (o mesmo número de controle enviado na cessão) e `contract_number` para CCBs |
| `collection_origin_type` | opcional | Quem pagou: `borrower` (sacado), `assignor` (cedente) ou `collection_agent` (agente de cobrança) |
| `remaining_face_value` | opcional | Saldo remanescente do valor de face. Aceito **somente** com `settlement_type: installment_amortization` |

:::caution A coluna de identificação define o lote inteiro
Um mesmo arquivo usa `external_id` **ou** `contract_number` — não os dois. Se nenhuma das duas colunas existir, o arquivo é recusado.
:::

### Tipos de liquidação

| Valor | Significado |
|---|---|
| `asset_settlement` | Liquidação integral do ativo |
| `asset_amortization` | Pagamento parcial do ativo |
| `installment_settlement` | Liquidação integral de uma parcela |
| `installment_amortization` | Pagamento parcial de uma parcela |
| `installment_partial_refund` / `asset_partial_refund` | Devolução parcial |
| `installment_refund` / `asset_refund` | Devolução integral |
| `fine_payment` / `installment_fine_payment` | Pagamento de multa |
| `gloss` | Glosa |
| `canceled` | Cancelamento |
| `rco_revenue` | Receita de RCO |

### Tipos de ativo aceitos

`ccb` · `cce` · `structured_ccb` · `structured_cce` · `structured_nce` · `structured_cci` · `duplicata_mercantil` · `duplicata_servicos` · `discounted_contract` · `cte`

**[📄 Baixar CSV de exemplo](/downloads/modelos_arquivo/exemplo_baixa_liquidacoes.csv)**

## Erros mais comuns

| Erro | Causa |
|---|---|
| `missing_fields: [...]` | Faltou uma coluna obrigatória no cabeçalho do CSV |
| `invalid asset_type: ...` | Tipo de ativo fora da lista aceita |
| `invalid settlement_type: ...` | Tipo de liquidação fora da lista aceita |
| `invalid total_value: ...` | Valor com caractere inesperado ou vazio |
| `invalid external_id` / `contract_number` | Identificador em branco |
| `remaining_face_value is only allowed for settlement_type installment_amortization` | Saldo remanescente informado no tipo errado |
| `unmapped cnab layout` | Arquivo CNAB com linhas fora de 444 ou 500 posições |

---

# Inserção de Liquidações

URL: /documentation/iaas/liquidacao_ativos/ativos/

Endpoint para inserir liquidações individuais em um lote de pagamento previamente criado. Cada liquidação representa um pagamento (total ou parcial) referente a um ativo da carteira do fundo — como liquidação de parcela, amortização, recompra ou pagamento de juros.

:::info Liquidação vs Recompra
Tanto a liquidação quanto a recompra de ativos são realizadas através deste endpoint. O campo `collection_origin_type` diferencia as duas operações:
- `borrower` — para **liquidações** (pagamento realizado pelo sacado/devedor).
- `assignor` — para **recompras** (pagamento realizado pelo cedente).
:::

:::tip Onde estou no fluxo?
Este é o **2º passo** do fluxo de liquidação. Antes deste passo, você deve ter [criado o lote de pagamento](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao).
:::

## Request

ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}/settlement
MÉTODO POST

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `external_id` | string | O `external_id` do lote de pagamento onde a liquidação será inserida. |

```json title="Request Body"
{
    "asset_type": "ccb",
    "total_value": 130.50,
    "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
    "settlement_type": "installment_settlement",
    "contract_number": "0123456789/ABC",
    "installment_number": 1,
    "collection_date": "2025-01-01",
    "collection_origin_type": "borrower"
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `asset_type` | string | obrigatório | Tipo de ativo. Veja [enumeradores de `asset_type`](#enumeradores-de-asset_type). Máximo de 255 caracteres. |
| `total_value` | number | obrigatório | Valor total do pagamento (com duas casas decimais). |
| `external_id` | string | obrigatório | Chave única de identificação desta liquidação no sistema do parceiro integrador. Máximo de 50 caracteres. |
| `settlement_type` | string | obrigatório | Tipo de liquidação. Veja [enumeradores de `settlement_type`](#enumeradores-de-settlement_type). Máximo de 50 caracteres. |
| `collection_origin_type` | string | obrigatório | Determina se a operação é uma liquidação (`borrower`) ou uma recompra (`assignor`). Veja [enumeradores de `collection_origin_type`](#enumeradores-de-collection_origin_type). |
| `contract_number` | string | opcional | Número do contrato referente ao ativo. Máximo de 50 caracteres. |
| `asset_external_id` | string | opcional | Chave única de identificação do ativo no sistema, fornecida na cessão. Máximo de 50 caracteres. |
| `asset_key` | string | opcional | Chave interna do ativo na QI Tech (UUID, 36 caracteres). |
| `if_code` | string | opcional | Código de instrumento financeiro (B3). Máximo de 36 caracteres. |
| `participant_control_number` | string | opcional | Número de controle do participante fornecido na cessão. Máximo de 50 caracteres. |
| `installment_number` | integer | opcional | Número da parcela a ser paga. Obrigatório para tipos de liquidação por parcela. |
| `installment_maturity_date` | string | opcional | Data de vencimento da parcela no formato `YYYY-MM-DD`. |
| `installment_external_id` | string | opcional | Identificador externo da parcela. Máximo de 50 caracteres. |
| `collection_date` | string | opcional | Data de pagamento no formato `YYYY-MM-DD`. Campo destinado para controle do integrador. |

:::caution Atenção
Os campos `asset_external_id`, `contract_number` e `asset_key` são formas alternativas de identificar o ativo no sistema. Informe **apenas um** deles — não envie múltiplos simultaneamente.
:::

:::info Diferença entre external_id
O campo `external_id` no corpo da requisição se refere ao identificador da **liquidação**. O campo `external_id` na URL se refere ao identificador do **lote de pagamento**.
:::

#### Enumeradores de `asset_type`

| Valor | Descrição |
|---|---|
| `ccb` | Cédula de Crédito Bancário |
| `cce` | Cédula de Crédito à Exportação |
| `structured_ccb` | Cédula de Crédito Bancário Estruturada |
| `structured_cce` | Cédula de Crédito à Exportação Estruturada |
| `structured_nce` | Nota de Crédito à Exportação Estruturada |
| `structured_cci` | Cédula de Crédito Imobiliário Estruturada |
| `duplicata_mercantil` | Duplicata Mercantil |
| `duplicata_servicos` | Duplicata de Serviços |
| `discounted_contract` | Contrato |

#### Enumeradores de `settlement_type`

| Valor | Descrição |
|---|---|
| `asset_settlement` | Liquidação total do ativo. |
| `asset_amortization` | Amortização do ativo (carência). |
| `fine_payment` | Pagamento de juros ou mora do ativo. |
| `installment_settlement` | Liquidação de parcela. Obrigatório informar `installment_number`. |
| `installment_amortization` | Amortização de parcela. Obrigatório informar `installment_number`. |
| `installment_fine_payment` | Pagamento de juros ou mora de parcela. Obrigatório informar `installment_number`. |
| `gloss` | Glosa de parcela. Obrigatório informar `installment_number`. |

#### Enumeradores de `collection_origin_type`

| Valor | Descrição |
|---|---|
| `borrower` | Liquidação — pagamento realizado pelo sacado/devedor. |
| `assignor` | Recompra — pagamento realizado pelo cedente. |

## Response

STATUS 201

```json title="Response Body"
{
    "status": "validated",
    "total_value": 130.50,
    "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
    "type": "installment_settlement",
    "settlement_key": "b2c3d4e5-f6a7-8901-abcd-ef1234567890",
    "installment_number": 1,
    "settlement_result": 0.0,
    "total_number_of_units": 1,
    "collection_origin_type": "borrower",
    "assets": [
        {
            "asset_key": "f34e9437-d025-41ab-bb53-6b94e10fd361",
            "number_of_units": 1,
            "present_value": 1250.00,
            "installment_face_value": 130.50
        }
    ]
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `status` | string | Status da liquidação. Após inserção bem-sucedida, retorna `validated`. |
| `total_value` | number | Valor total do pagamento. |
| `external_id` | string | Chave externa da liquidação fornecida pelo parceiro. |
| `type` | string | Tipo de liquidação. |
| `settlement_key` | string | Identificador único da liquidação gerado pela QI Tech (UUID). |
| `installment_number` | integer | Número da parcela. Presente quando aplicável. |
| `settlement_result` | number | Resultado da liquidação. Presente quando calculado. |
| `total_number_of_units` | integer | Quantidade total de unidades de ativo afetadas pela liquidação. |
| `collection_origin_type` | string | Tipo de origem da cobrança (`borrower` ou `assignor`). Presente quando informado na requisição. |
| `assets` | array | Lista de ativos afetados pela liquidação. Veja [Atributos de `assets`](#atributos-de-assets). |

#### Atributos de `assets`

| Campo | Tipo | Descrição |
|---|---|---|
| `asset_key` | string | Identificador único do ativo (UUID). |
| `number_of_units` | integer | Quantidade de unidades do ativo. |
| `present_value` | number | Valor presente do ativo em reais. |
| `installment_face_value` | number | Valor de face da parcela. Presente quando aplicável. |
| `installment_post_maturity_interest_value` | number | Valor de juros pós-vencimento da parcela. Presente quando aplicável. |
| `installment_delay_interest_value` | number | Valor de juros de atraso da parcela. Presente quando aplicável. |
| `installment_delay_fine_value` | number | Valor de multa de atraso da parcela. Presente quando aplicável. |

## Possíveis erros

STATUS 404

**Lote de pagamento não encontrado**

O `external_id` do lote informado na URL não corresponde a nenhum lote cadastrado para este fundo. Verifique se o identificador está correto.

```json
{
  "title": "Payment batch not found",
  "description": "The Payment Batch with external_id {payment_batch_external_id} was not found",
  "translation": "O Lote de Pagamento com identificador externo {payment_batch_external_id} não foi encontrado",
  "code": "SET000010"
}
```

STATUS 400

**Liquidação com external_id duplicado**

Já existe uma liquidação cadastrada com o `external_id` informado neste lote. Cada liquidação deve ter um identificador único. Gere um novo `external_id` e tente novamente.

```json
{
  "title": "Already Exists Settlement With External Id",
  "description": "The settlement with external_id {settlement_external_id} in payment batch with external id {payment_batch_external_id} already exists",
  "translation": "a liquidação com identificador {settlement_external_id} no lote de identificador {payment_batch_external_id} já existe",
  "code": "SET000013"
}
```

## Próximos passos

Após inserir todas as liquidações desejadas, o fluxo continua com:

1. **[Encerramento do lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento)** — sinalize que todas as liquidações foram inseridas para que o processamento seja iniciado.

---

# Remoção de Liquidações

URL: /documentation/iaas/liquidacao_ativos/ativos/remocao_liquidacoes

Endpoint para descartar uma liquidação individual previamente inserida em um lote de pagamento. Somente liquidações em lotes que ainda não foram encerrados podem ser removidas.

:::tip Quando utilizar
Use este endpoint quando precisar remover uma liquidação incorreta ou indesejada antes de [encerrar o lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento). Após o encerramento do lote, não é possível remover liquidações individuais.
:::

## Request

ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}/settlement/{settlement_external_id}
MÉTODO PUT

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `external_id` | string | O `external_id` do lote de pagamento. |
| `settlement_external_id` | string | O `external_id` da liquidação que será descartada. |

```json title="Request Body"
{
    "status": "discarded"
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `status` | string | obrigatório | Novo status da liquidação. Para descartar, envie `discarded`. |

## Response

STATUS 200

```json title="Response Body"
{
    "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
    "status": "discarded"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `external_id` | string | Chave externa da liquidação fornecida pelo parceiro. |
| `status` | string | Novo status da liquidação: `discarded`. |

## Possíveis erros

STATUS 404

**Liquidação não encontrada**

O `settlement_external_id` informado na URL não corresponde a nenhuma liquidação cadastrada neste lote. Verifique se os identificadores do lote e da liquidação estão corretos.

```json
{
  "title": "Settlement not found",
  "description": "The Settlement with external_id {external_id} was not found",
  "translation": "A Liquidação com identificador externo {external_id} não foi encontrada",
  "code": "SET000011"
}
```

STATUS 400

**Status inválido**

O valor informado no campo `status` não é válido. Para remoção, utilize apenas `discarded`.

```json
{
  "title": "Invalid status",
  "description": "The status given: {status} is not suported.",
  "translation": "O status: {status} não possui suporte.",
  "code": "SET000026"
}
```

STATUS 400

**Lote já encerrado**

O lote de pagamento já foi encerrado e não permite mais alterações nas liquidações. Não é possível remover liquidações de lotes que já passaram do status `pending_settlements_insertion`.

```json
{
  "title": "Payment Batch Status mismatch",
  "description": "Payment batch of key: {payment_batch_key} with status: {current} was expected to be: {expected}",
  "translation": "O lote de pagamento com chave: {payment_batch_key} e com status: {current} não passou, era esperado que fosse: {expected}",
  "code": "SET000016"
}
```

STATUS 400

**Status da liquidação incompatível**

A liquidação está em um status que não permite ser descartada. Apenas liquidações com status `validated` podem ser removidas.

```json
{
  "title": "Settlement type mismatch",
  "description": "The settlement given has the status: {current_status} and was expected: {expected_status}",
  "translation": "A liquidação com status: {current_status} era esperado ter: {expected_status}",
  "code": "SET000024"
}
```

---

# Webhooks de Liquidação

URL: /documentation/iaas/liquidacao_ativos/ativos/webhook

Ao longo do processamento das liquidações, o sistema envia webhooks para notificar o parceiro integrador sobre mudanças de status de cada liquidação individual. Todos os webhooks possuem o tipo `settlement.settlement_status_change` e identificam a liquidação pelo `settlement_external_id` fornecido na criação.

:::info Configuração de webhooks
Para receber webhooks, é necessário ter uma URL de callback configurada junto à QI Tech. Entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) para configurar.
:::

## Fluxo de status da liquidação

Cada liquidação inserida no lote fica em `validated` e só é processada depois que o lote de pagamento atinge `paid`. A partir daí ela chega a um dos dois status finais que geram webhook: `settled` ou `discarded`. O status `validated` **não** dispara notificação — ele é o resultado da própria chamada de [inserção da liquidação](/documentation/iaas/liquidacao_ativos/ativos).

![Fluxo de status da liquidação, destacando os dois status finais que geram webhook](/img/diagrams/iaas-liquidacao-ativos-ativos-webhook.svg)

_Como ler o diagrama: **contorno tracejado** = status sem webhook · **verde** = conclusão com sucesso · **vermelho** = encerramento sem movimentação financeira._

## Estrutura do webhook

Todos os webhooks de liquidação seguem a mesma estrutura base:

| Campo | Tipo | Descrição |
|---|---|---|
| `webhook_type` | string | Sempre `settlement.settlement_status_change`. |
| `webhook_datetime` | string | Data e hora do evento no formato ISO 8601. |
| `data` | array | Lista com os dados do evento. Veja tabela abaixo. |

#### Atributos de cada objeto em `data`

Os campos condicionais são ecoados diretamente do que foi enviado na criação da liquidação. O payload varia conforme o `settlement_type` e o método de identificação do ativo utilizado.

**Campos sempre presentes:**

| Campo | Tipo | Descrição |
|---|---|---|
| `payment_batch_external_id` | string | O `external_id` do lote de pagamento. |
| `settlement_external_id` | string | O `external_id` da liquidação. |
| `settlement_status` | string | Novo status da liquidação. |
| `settlement_type` | string | Tipo de liquidação. |
| `total_value` | number | Valor total da liquidação em reais. |
| `fund_class_document_number` | string | CNPJ do fundo associado. |
| `fund_class_key` | string | Chave do fundo na QI Tech (UUID). |
| `asset_key` | string | Chave interna do ativo na QI Tech (UUID). |

**Identificação do ativo — apenas um dos campos abaixo estará presente, conforme o que foi informado na criação:**

| Campo | Tipo | Descrição |
|---|---|---|
| `contract_number` | string | Número do contrato. Presente se informado na criação. |
| `asset_external_id` | string | `external_id` do ativo no sistema do parceiro. Presente se informado na criação. |

**Demais campos ecoados quando informados:**

| Campo | Tipo | Descrição |
|---|---|---|
| `if_code` | string | Código de instrumento financeiro (B3). Presente se informado na criação da liquidação. |
| `participant_control_number` | string | Número de controle do participante. Presente se informado na criação da liquidação. |
| `source_document_number` | string | CPF ou CNPJ da contraparte financeira. Presente se informado na [criação do lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao). |

**Campos de parcela — presentes apenas para tipos de liquidação por parcela (`installment_settlement`, `installment_amortization`, `installment_fine_payment`, `gloss`):**

| Campo | Tipo | Descrição |
|---|---|---|
| `installment_number` | integer | Número da parcela. |
| `installment_maturity_date` | string | Data de vencimento da parcela no formato `YYYY-MM-DD`. Presente quando informado na criação. |
| `installment_external_id` | string | `external_id` da parcela. Presente quando informado na criação. |

```json title="Estrutura padrão do webhook"
{
    "data": [
        {
            "payment_batch_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
            "settlement_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
            "settlement_status": "STATUS",
            "settlement_type": "installment_settlement",
            "total_value": 130.50,
            "fund_class_document_number": "60.910.091/0001-24",
            "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
            "asset_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
            "contract_number": "0032226586/NNT",
            "installment_number": 3
        }
    ],
    "webhook_type": "settlement.settlement_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

## Eventos por status

### Liquidação Concluída

STATUS settled

Enviado quando a liquidação é processada com sucesso e o valor foi devidamente conciliado na carteira do fundo. Este é o status final de uma liquidação bem-sucedida — a partir desse momento, a movimentação financeira está efetivada.

```json title="Webhook Body"
{
    "data": [
        {
            "payment_batch_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
            "settlement_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
            "settlement_status": "settled",
            "settlement_type": "installment_settlement",
            "total_value": 130.50,
            "fund_class_document_number": "60.910.091/0001-24",
            "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
            "asset_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
            "contract_number": "0032226586/NNT",
            "installment_number": 3
        }
    ],
    "webhook_type": "settlement.settlement_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### Liquidação Descartada

STATUS discarded

Enviado quando a liquidação é descartada do fluxo de processamento. Liquidações descartadas não geram movimentação financeira. Existem três situações que causam esse status:

1. **Remoção manual antes do encerramento do lote** — o parceiro integrador remove a liquidação via endpoint de [remoção de liquidações](/documentation/iaas/liquidacao_ativos/ativos/remocao_liquidacoes) enquanto o lote ainda está aberto.
2. **Descarte interno após revisão** — a equipe QI Tech descarta uma liquidação que estava em revisão manual (`pending_validation`), por exemplo por inconsistência nos dados.
3. **Rejeição** — durante o processamento, a carteira do fundo retorna uma rejeição definitiva para uma liquidação com valor zero. Nesses casos, o sistema determina que reprocessar a liquidação produziria o mesmo resultado e a descarta.

```json title="Webhook Body"
{
    "data": [
        {
            "payment_batch_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
            "settlement_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
            "settlement_status": "discarded",
            "settlement_type": "installment_settlement",
            "total_value": 130.50,
            "fund_class_document_number": "60.910.091/0001-24",
            "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
            "asset_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
            "contract_number": "0032226586/NNT",
            "installment_number": 3
        }
    ],
    "webhook_type": "settlement.settlement_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

---

# Fluxo de liquidação de ativos

URL: /documentation/iaas/liquidacao_ativos/fluxo_liquidacao

Esta página oferece uma visão holística do fluxo de liquidação de ativos já encarteirados no fundo: desde a criação do lote de pagamento até a conclusão das liquidações e a atualização da carteira. Acompanhe a evolução dos **status do lote**, dos **status de cada liquidação** e dos **webhooks** em cada etapa.

:::tip Como usar este fluxograma
Passe o mouse sobre cada etapa para ver os detalhes do endpoint e acessar a documentação completa. As trilhas coloridas mostram simultaneamente o que acontece com o lote, com cada liquidação e quais webhooks você receberá após o processamento.
:::

{`
.cf-legend{display:flex;flex-wrap:wrap;gap:8px;margin-bottom:24px}
.cf-legend-item{display:flex;align-items:center;gap:6px;font-size:0.8rem;font-weight:600}
.cf-legend-dot{width:12px;height:12px;border-radius:3px}

.cf-step{position:relative;margin-bottom:4px}
.cf-step:not(:last-child)::after{content:'';display:block;width:2px;height:16px;margin:0 auto;background:var(--ifm-color-emphasis-300)}

.cf-card{border:1.5px solid var(--ifm-color-emphasis-200);border-radius:10px;padding:16px 20px;transition:box-shadow 0.2s,border-color 0.2s;cursor:pointer;background:var(--ifm-background-surface-color,var(--ifm-background-color))}
.cf-card:hover{box-shadow:0 4px 16px rgba(0,0,0,0.08);border-color:var(--ifm-color-primary)}

.cf-card-header{display:flex;align-items:center;gap:10px;flex-wrap:wrap}
.cf-num{width:28px;height:28px;border-radius:50%;display:flex;align-items:center;justify-content:center;font-size:0.8rem;font-weight:800;color:#fff;flex-shrink:0}
.cf-num-int{background:#3b82f6}
.cf-num-qi{background:#8b5cf6}
.cf-num-ges{background:#d946ef}
.cf-title{font-size:1rem;font-weight:700;color:var(--ifm-font-color-base)}
.cf-actor{font-size:0.7rem;font-weight:700;padding:2px 8px;border-radius:12px;margin-left:auto}
.cf-actor-int{background:rgba(59,130,246,0.12);color:#2563eb}
.cf-actor-qi{background:rgba(139,92,246,0.12);color:#7c3aed}
.cf-actor-ges{background:rgba(217,70,239,0.12);color:#c026d3}
.cf-subtitle{font-size:0.82rem;color:var(--ifm-color-emphasis-700);margin-top:4px;margin-left:38px}

.cf-tracks{display:flex;flex-wrap:wrap;gap:8px;margin-top:12px;margin-left:38px}
.cf-track{display:inline-flex;align-items:center;gap:5px;padding:3px 10px;border-radius:6px;font-size:0.75rem;font-family:var(--ifm-font-family-monospace);border:1px solid}
.cf-track-lote{background:rgba(34,197,94,0.1);color:#16a34a;border-color:rgba(34,197,94,0.25)}
.cf-track-ativo{background:rgba(59,130,246,0.1);color:#2563eb;border-color:rgba(59,130,246,0.25)}
.cf-track-wh{background:rgba(245,158,11,0.1);color:#b45309;border-color:rgba(245,158,11,0.25)}
.cf-track-err{background:rgba(239,68,68,0.1);color:#dc2626;border-color:rgba(239,68,68,0.25)}
.cf-track-label{font-family:var(--ifm-font-family-base);font-weight:700;font-size:0.7rem;text-transform:uppercase;letter-spacing:0.03em}
.cf-new{font-weight:700}
.cf-unchanged{opacity:0.5}

.cf-details{max-height:0;overflow:hidden;opacity:0;transition:max-height 0.35s ease,opacity 0.25s ease,margin 0.3s ease;margin-left:38px}
.cf-card:hover .cf-details{max-height:300px;opacity:1;margin-top:14px;padding-top:12px;border-top:1px solid var(--ifm-color-emphasis-200)}

.cf-endpoint{font-family:var(--ifm-font-family-monospace);font-size:0.82rem;padding:8px 12px;border-radius:6px;background:var(--ifm-color-emphasis-100);margin-bottom:8px;display:flex;align-items:center;gap:8px;flex-wrap:wrap}
.cf-method{font-weight:800;padding:2px 6px;border-radius:4px;font-size:0.72rem}
.cf-method-post{background:#f97316;color:#fff}
.cf-method-put{background:#3b82f6;color:#fff}
.cf-method-get{background:#22c55e;color:#fff}
.cf-desc{font-size:0.82rem;color:var(--ifm-color-emphasis-700);margin-bottom:8px}
.cf-link{font-size:0.82rem;font-weight:600;color:var(--ifm-color-primary);text-decoration:none}
.cf-link:hover{text-decoration:underline}

.cf-branch{margin-top:12px;margin-left:38px;display:flex;gap:12px;flex-wrap:wrap}
.cf-branch-path{flex:1;min-width:200px;border-radius:8px;padding:10px 14px;border:1.5px dashed}
.cf-branch-ok{border-color:rgba(34,197,94,0.4);background:rgba(34,197,94,0.05)}
.cf-branch-err{border-color:rgba(239,68,68,0.4);background:rgba(239,68,68,0.05)}
.cf-branch-label{font-size:0.78rem;font-weight:700;margin-bottom:4px}
.cf-branch-label-ok{color:#16a34a}
.cf-branch-label-err{color:#dc2626}

html[data-theme='dark'] .cf-track-lote{background:rgba(34,197,94,0.15);color:#4ade80;border-color:rgba(34,197,94,0.3)}
html[data-theme='dark'] .cf-track-ativo{background:rgba(59,130,246,0.15);color:#60a5fa;border-color:rgba(59,130,246,0.3)}
html[data-theme='dark'] .cf-track-wh{background:rgba(245,158,11,0.15);color:#fbbf24;border-color:rgba(245,158,11,0.3)}
html[data-theme='dark'] .cf-track-err{background:rgba(239,68,68,0.15);color:#f87171;border-color:rgba(239,68,68,0.3)}
html[data-theme='dark'] .cf-branch-ok{background:rgba(34,197,94,0.08)}
html[data-theme='dark'] .cf-branch-err{background:rgba(239,68,68,0.08)}
html[data-theme='dark'] .cf-actor-int{background:rgba(59,130,246,0.2);color:#60a5fa}
html[data-theme='dark'] .cf-actor-qi{background:rgba(139,92,246,0.2);color:#a78bfa}
html[data-theme='dark'] .cf-actor-ges{background:rgba(217,70,239,0.2);color:#e879f9}
`}

## Legenda

Agente Integrador
QI Tech (automático)
Status do Lote
Status da Liquidação
Webhook

## Fluxograma

1
Criação do lote de pagamento
Agente Integrador
Cria um lote com identificador único ( external_id ) por fundo, contendo conta de crédito opcional e demais metadados.
Lote: pending_settlements_insertion
POST /settlement/fund_class/{fund_class_key}/payment_batch
O lote fica pronto para receber liquidações.
Ver documentação completa →

2
Inserção das liquidações
Agente Integrador
Insere cada liquidação (parcela, amortização, liquidação total, etc.) no lote. Repita para todas as operações desejadas.
Lote: pending_settlements_insertion
Liquidação: validated
POST /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}/settlement
Cada liquidação recebe status validated após inserção bem-sucedida. Não há webhook neste momento; os webhooks são enviados após o encerramento e o processamento.
Ver documentação completa →

3
Remoção de liquidação (opcional)
Agente Integrador
Antes de encerrar o lote, você pode descartar uma liquidação inserida por engano. Somente liquidações em status validated podem ser removidas.
Lote: pending_settlements_insertion
Liquidação: validated
Removeu uma liquidação
discarded
A liquidação deixa de entrar no processamento.
Não aplicável
Pule este passo se não precisar remover nenhuma liquidação.
PUT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}/settlement/{settlement_external_id}
Corpo: {"status": "discarded"} . Após o encerramento do lote não é possível remover liquidações individuais.
Ver documentação completa →

4
Encerramento do lote
Agente Integrador
Sinaliza que todas as liquidações foram inseridas (e ajustadas) e que o processamento pode iniciar — ou descarta o lote inteiro.
Lote: pending_payment / discarded
Liquidação: validated (ou discarded)
Processar lote
pending_payment
É necessário ter ao menos uma liquidação no lote.
Descartar lote
discarded
Nenhuma liquidação será processada. Fluxo encerrado.
PUT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}
Envie {"batch_status": "pending_payment"} para encerrar e processar, ou {"batch_status": "discarded"} para descartar o lote.
Ver documentação completa →

5
Pagamento do lote
QI Tech
A QI Tech confirma o pagamento do lote. Em seguida as liquidações individuais são processadas e os webhooks de liquidação são disparados.
Lote: paid
Webhook: payment_batch_status_change
Webhook settlement.payment_batch_status_change com status paid . Opcionalmente, use a listagem de lotes para acompanhar o lote.
GET /settlement/fund_class/{fund_class_key}/payment_batches
Consulta opcional para acompanhar o lote por status ou data de referência.
Webhooks do lote →

6
Conclusão das liquidações
QI Tech
Cada liquidação processada com sucesso é conciliada na carteira do fundo. Este é o status final de sucesso por liquidação.
Liquidação: settled
Webhook: settlement_status_change
Webhook settlement.settlement_status_change com settlement_status settled para cada liquidação concluída (após o pagamento do lote).
Ver documentação de webhooks de liquidação →

---

## Resumo de webhooks

A tabela abaixo consolida todos os webhooks da API de liquidação:

| # | Tipo do webhook | Campo de status | Valor | Momento no fluxo | Ação esperada |
|---|---|---|---|---|---|
| 1 | `settlement.payment_batch_status_change` | `status` | `paid` | Após confirmação do pagamento do lote (passo 5) | A partir deste evento, as liquidações são processadas e os webhooks por liquidação passam a ser enviados. |
| 2 | `settlement.settlement_status_change` | `settlement_status` | `settled` | Por liquidação, após processamento bem-sucedido (passo 6) | Liquidação concluída e conciliada na carteira. |
| 3 | `settlement.settlement_status_change` | `settlement_status` | `discarded` | Por liquidação, quando descartada por remoção manual, descarte interno ou rejeição permanente da carteira | Liquidação não será processada. Nenhuma movimentação financeira é gerada. |
| 4 | `settlement.payment_batch_status_change` | `status` | `completed` | Após todas as liquidações do lote atingirem status final (`settled` ou `discarded`) | O ciclo do lote está encerrado. Todas as liquidações foram processadas. |
| 5 | `settlement.payment_batch_status_change` | `status` | `discarded` | Quando o lote é descartado (por solicitação do parceiro, descarte automático ou falha no cancelamento em conta caixa) | Nenhuma liquidação do lote será processada. |

:::info Payload do webhook de liquidação
O payload do webhook `settlement_status_change` varia conforme os dados enviados na criação da liquidação:

- **Identificação do ativo:** apenas um dos campos `contract_number` ou `asset_external_id` estará presente, conforme o método de identificação usado na criação. Nunca os dois simultaneamente.
- **Campos de parcela** (`installment_number`, `installment_maturity_date`, `installment_external_id`): presentes somente para tipos de liquidação por parcela — `installment_settlement`, `installment_amortization`, `installment_fine_payment` e `gloss`. Ausentes em tipos de ativo total (`asset_settlement`, `asset_amortization`, `fine_payment`).

Para a estrutura completa dos payloads, consulte [Webhooks do lote de pagamento](/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook) e [Webhooks de liquidação](/documentation/iaas/liquidacao_ativos/ativos/webhook).
:::

---

# Liquidação de Ativos

URL: /documentation/iaas/liquidacao_ativos/inicio

Esta seção documenta as APIs que viabilizam o processo de Liquidação de Ativos para Fundos de Investimento administrados pela QI CTVM. Por meio dessas APIs, é possível registrar pagamentos de parcelas, amortizações, recompras e demais eventos de liquidação dos ativos que compõem a carteira do fundo.

:::tip Contexto
A liquidação de ativos descrita nesta seção aplica-se exclusivamente a direitos creditórios (CCBs, duplicatas, contratos, etc.) já encarteirados no fundo. Letras do Tesouro, Debêntures e outros ativos de renda fixa não se aplicam a esse fluxo.
:::

:::info Pré-requisitos
- Para ter acesso a esses serviços, entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) para liberação dos ambientes de Homologação (Sandbox) e Produção.
- Você precisará da `fund_class_key` (chave do fundo), que compõe a URL base de todos os endpoints desta API:

```
/settlement/fund_class/{fund_class_key}
```
:::

## Como enviar as baixas

| Caminho | Como funciona | Onde |
|---|---|---|
| **Pela API, liquidação a liquidação** | Criação do lote de pagamento, uma requisição por liquidação e encerramento do lote. É o fluxo detalhado nesta seção | API de integração |
| **Por arquivo** | Um único arquivo com todas as liquidações: **CNAB 444** ou **CSV** | Portal do gestor/consultor |

:::tip Baixa por arquivo
Se você já recebe o retorno CNAB do banco cobrador, pode enviá-lo direto. Veja [Baixa por Arquivo](/documentation/iaas/liquidacao_ativos/arquivo/inicio) e o [Layout CNAB 444 — Baixa](/documentation/iaas/liquidacao_ativos/arquivo/cnab444_baixa).
:::

## Fluxo de liquidação

O diagrama abaixo mostra o caminho principal, as bifurcações e o status resultante de cada etapa. Passe o mouse em um nó para ver o endpoint e clique para abrir a documentação.

<FlowDiagram
  columns={3}
  nodes={[
    { id: 'criacao', row: 1, col: 2, actor: 'you', num: 1,
      title: 'Criação do Lote de Pagamento',
      status: 'pending_settlements_insertion',
      desc: 'Contêiner de todas as liquidações que serão processadas em conjunto, identificado por um external_id único.',
      endpoint: { method: 'POST', path: '/settlement/fund_class/{fund_class_key}/payment_batch' },
      href: '/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao' },

    { id: 'insercao', row: 2, col: 2, actor: 'you', num: 2,
      title: 'Inserção das Liquidações',
      status: 'liquidação: validated',
      desc: 'Uma requisição por liquidação, informando tipo de ativo, valor, tipo de liquidação e identificadores.',
      endpoint: { method: 'POST', path: '.../payment_batch/{external_id}/settlement' },
      href: '/documentation/iaas/liquidacao_ativos/ativos' },

    { id: 'remocao', row: 2, col: 3, actor: 'you', tag: 'Opcional',
      title: 'Remoção de uma liquidação',
      status: 'liquidação: discarded',
      desc: 'Descarta uma liquidação inserida por engano. Só é possível enquanto o lote não foi encerrado.',
      endpoint: { method: 'PUT', path: '.../settlement/{settlement_external_id}' },
      href: '/documentation/iaas/liquidacao_ativos/ativos/remocao_liquidacoes' },

    { id: 'encerramento', row: 3, col: 2, actor: 'you', num: 3,
      title: 'Encerramento do Lote',
      desc: 'Define o batch_status. É necessário ter ao menos uma liquidação inserida.',
      endpoint: { method: 'PUT', path: '.../payment_batch/{external_id}' },
      href: '/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento' },

    { id: 'descartado', row: 4, col: 1, actor: 'you', tone: 'end',
      title: 'Lote descartado',
      status: 'discarded',
      desc: 'Nenhuma liquidação é processada e nenhuma movimentação financeira é gerada. Fluxo encerrado.' },

    { id: 'pago', row: 4, col: 2, actor: 'qitech',
      title: 'Pagamento do lote confirmado',
      status: 'paid',
      desc: 'A QI Tech confirma o pagamento. A partir deste evento as liquidações individuais passam a ser processadas.',
      href: '/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook' },

    { id: 'processa', row: 5, col: 2, actor: 'qitech',
      title: 'Processamento de cada liquidação',
      status: 'liquidação: settled',
      desc: 'Cada liquidação é conciliada na carteira do fundo e notificada individualmente por webhook.',
      href: '/documentation/iaas/liquidacao_ativos/ativos/webhook' },

    { id: 'conciliada', row: 6, col: 2, actor: 'qitech', tone: 'ok',
      title: 'Carteira do fundo conciliada',
      status: 'completed',
      desc: 'Todas as liquidações atingiram status final e o ciclo do lote está encerrado.',
      href: '/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook' },
  ]}
  edges={[
    { from: 'criacao', to: 'insercao' },
    { from: 'insercao', to: 'remocao', dashed: true },
    { from: 'insercao', to: 'encerramento' },
    { from: 'encerramento', to: 'descartado', label: 'discarded', tone: 'end' },
    { from: 'encerramento', to: 'pago', label: 'pending_payment', tone: 'ok' },
    { from: 'pago', to: 'processa', label: 'webhook' },
    { from: 'processa', to: 'conciliada', label: 'webhook' },
  ]}
/>

:::tip Fluxo completo
Para todas as transições de status, os payloads dos webhooks e os caminhos de exceção, consulte o [Fluxo de liquidação de ativos](/documentation/iaas/liquidacao_ativos/fluxo_liquidacao).
:::

## Passo a passo

### 1. Criação do Lote de Pagamento

Crie um lote de pagamento informando um identificador único (`external_id`). O lote será o contêiner para todas as liquidações que serão processadas em conjunto.

**[Acessar documentação da criação do lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao)**

### 2. Inserção das Liquidações

Adicione as liquidações ao lote criado. Cada liquidação deve ser inserida individualmente, informando o tipo de ativo, o valor, o tipo de liquidação e os identificadores necessários.

**[Acessar documentação da inserção de liquidações](/documentation/iaas/liquidacao_ativos/ativos)**

Enquanto o lote não é encerrado, uma liquidação inserida por engano pode ser removida.

**[Acessar documentação da remoção de liquidações](/documentation/iaas/liquidacao_ativos/ativos/remocao_liquidacoes)**

### 3. Encerramento do Lote

Após inserir todas as liquidações, encerre o lote para que o processamento interno seja iniciado. A conciliação de caixa e a atualização do portfólio de ativos serão realizadas automaticamente. No mesmo endpoint é possível, alternativamente, descartar o lote inteiro — nesse caso nenhuma liquidação é processada.

**[Acessar documentação do encerramento](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento)**

### 4. Acompanhamento via Webhooks

Acompanhe o progresso através dos webhooks:
- **[Webhooks do lote de pagamento](/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook)** — notificações sobre o status do lote.
- **[Webhooks das liquidações](/documentation/iaas/liquidacao_ativos/ativos/webhook)** — notificações sobre o status individual de cada liquidação.

:::info Processamento automático
O procedimento de conciliação de caixa e a atualização do portfólio de ativos é feito de forma automática pela API após o encerramento do lote.
:::

---

# Criação do Lote de Pagamento

URL: /documentation/iaas/liquidacao_ativos/lote_pagamento/criacao

Este é o **primeiro passo** do fluxo de liquidação de ativos. A criação do lote de pagamento reserva um agrupamento onde as liquidações que serão processadas serão inseridas nas etapas seguintes.

:::info Pré-requisitos
Antes de criar um lote, você precisa ter em mãos a `fund_class_key` — chave única do fundo no qual os ativos serão liquidados. Essa chave compõe o endpoint utilizado em toda esta API:

```
/settlement/fund_class/{fund_class_key}
```

Para mais detalhes sobre o fluxo completo, consulte a [página de introdução](/documentation/iaas/liquidacao_ativos/inicio).
:::

:::caution Atenção
Cada lote deve possuir um `external_id` **único** por fundo. O sistema não permitirá a criação de dois lotes com o mesmo identificador.
:::

## Request

ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batch
MÉTODO POST

```json title="Request Body"
{
    "external_id": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "description": "PAGAMENTOS - ABC - 2025-01-01",
    "account": {
        "account_number": "123456",
        "account_digit": "0",
        "account_branch": "0001",
        "financial_institution_code": "329"
    }
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `external_id` | string | obrigatório | Chave única de identificação deste lote no sistema do parceiro integrador. Máximo de 50 caracteres. |
| `description` | string | opcional | Descrição do lote de liquidação. Máximo de 255 caracteres. |
| `account` | object | opcional | Dados da conta onde a liquidação será creditada. Quando não informado, a liquidação será gerada na conta principal do fundo. Veja [Atributos de `account`](#atributos-de-account). |
| `account_key` | string | opcional | Chave da conta onde a liquidação será creditada (UUID, 36 caracteres). Alternativa ao campo `account`. |
| `reference_date` | string | opcional | Data de referência da liquidação no formato `YYYY-MM-DD`. |
| `end_to_end_id` | string | opcional | Identificador end-to-end do PIX da contraparte financeira da liquidação. Máximo de 32 caracteres. |
| `source_document_number` | string | opcional | CPF ou CNPJ da contraparte financeira da liquidação, com pontuação (ex: `12.345.678/0001-90` ou `123.456.789-00`). |

:::caution Atenção
Os campos `account` e `account_key` não devem ser passados simultaneamente. Caso nenhum dos dois seja informado, a liquidação será gerada na conta principal do fundo. As informações da conta devem ser referentes a uma conta pertencente ao fundo.
:::

#### Atributos de `account`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `account_number` | string | obrigatório | Número da conta. Máximo de 20 caracteres. |
| `account_digit` | string | obrigatório | Dígito da conta. 1 caractere. |
| `account_branch` | string | obrigatório | Agência da conta. Máximo de 4 caracteres. |
| `financial_institution_code` | string | obrigatório | Código da instituição financeira. Máximo de 20 caracteres. |

## Response

STATUS 201

```json title="Response Body"
{
    "external_id": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "description": "PAGAMENTOS - ABC - 2025-01-01",
    "fund_class": {
        "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS",
        "manager": {
            "name": "EXEMPLO CAPITAL",
            "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
            "document_number": "45.585.471/0001-47"
        },
        "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
        "document_number": "60.910.091/0001-24"
    },
    "payment_batch_key": "63f0dbec-e9c4-4943-929e-1d47b9edbb0b",
    "status": "pending_settlements_insertion",
    "reference_date": "2025-01-01",
    "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `external_id` | string | A mesma chave externa fornecida na requisição. |
| `description` | string | Descrição do lote. |
| `fund_class` | object | Dados do fundo associado ao lote. Veja [Atributos de `fund_class`](#atributos-de-fund_class). |
| `payment_batch_key` | string | Identificador único do lote gerado pela QI Tech (UUID). |
| `status` | string | Status inicial do lote. Sempre retorna `pending_settlements_insertion`, indicando que o lote está pronto para receber liquidações. |
| `reference_date` | string | Data de referência da liquidação no formato `YYYY-MM-DD`. |
| `account_key` | string | Chave da conta associada ao lote (UUID). |

#### Atributos de `fund_class`

| Campo | Tipo | Descrição |
|---|---|---|
| `name` | string | Nome do fundo. |
| `manager` | object | Dados do gestor do fundo. Veja [Atributos de `manager`](#atributos-de-manager). |
| `fund_class_key` | string | Chave única do fundo (UUID). |
| `document_number` | string | CNPJ do fundo. |

#### Atributos de `manager`

| Campo | Tipo | Descrição |
|---|---|---|
| `name` | string | Nome do gestor. |
| `manager_key` | string | Chave única do gestor (UUID). |
| `document_number` | string | CNPJ do gestor. |

## Possíveis erros

STATUS 404

**Fundo não encontrado**

A `fund_class_key` informada na URL não corresponde a nenhum fundo cadastrado. Verifique se a chave está correta.

```json
{
  "title": "Fund Class not Found",
  "description": "Fund Class with key {fund_class_key} was not found.",
  "translation": "A Classe de Fundo com chave {fund_class_key} nao foi encontrado.",
  "code": "SET000005"
}
```

STATUS 409

**External ID duplicado**

Já existe um lote cadastrado com o `external_id` informado. Cada lote deve ter um identificador único. Gere um novo `external_id` e tente novamente.

```json
{
  "title": "Payment batch external id already exists",
  "description": "The Payment Batch with external id {payment_batch_external_id} already exists",
  "translation": "O Lote de Pagamento com identificador externo {payment_batch_external_id} ja existe",
  "code": "SET000009"
}
```

STATUS 400

**Data contábil divergente**

O lote está sendo criado em uma data diferente da data contábil vigente do fundo. Verifique a data contábil do fundo e tente novamente.

```json
{
  "title": "Bad Request",
  "description": "Payment batch is being created in {accounting_date}, while fund is in {fund_class_accounting_date}",
  "translation": "Payment batch esta sendo criado em {accounting_date}, fundo esta em {fund_class_accounting_date}",
  "code": "SET000044"
}
```

STATUS 404

**Conta não encontrada**

A `account_key` informada não corresponde a nenhuma conta cadastrada. Verifique se a chave está correta e se a conta pertence ao fundo.

```json
{
  "title": "Account not found",
  "description": "The account with key ({account_key}) was not found.",
  "translation": "A conta com chave({account_key}) não foi encontrada.",
  "code": "SET000009"
}
```

## Próximos passos

Após criar o lote, o fluxo continua com:

1. **[Inserção das liquidações](/documentation/iaas/liquidacao_ativos/ativos)** — adicione as liquidações (pagamentos de parcelas, amortizações, etc.) ao lote.
2. **[Encerramento do lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento)** — sinalize que todas as liquidações foram inseridas para que o processamento seja iniciado.

---

# Encerrar Inserção no Lote de Pagamento

URL: /documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento

Após inserir todas as liquidações desejadas no lote, utilize este endpoint para sinalizar que a inserção foi concluída e o processamento pode ser iniciado. Também é possível descartar o lote por completo.

:::tip Onde estou no fluxo?
Este é o **3º passo** do fluxo de liquidação. Antes deste passo, você deve ter:
1. [Criado o lote de pagamento](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao)
2. [Inserido as liquidações](/documentation/iaas/liquidacao_ativos/ativos)
:::

## Request

ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}
MÉTODO PUT

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `external_id` | string | O `external_id` informado na criação do lote. |

```json title="Request Body"
{
    "batch_status": "pending_payment"
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `batch_status` | string | obrigatório | Status para o qual o lote será atualizado. Veja [enumeradores](#enumeradores-de-batch_status) abaixo. |

#### Enumeradores de `batch_status`

| Valor | Descrição |
|---|---|
| `pending_payment` | Encerra a inserção e inicia o processamento do lote. |
| `discarded` | Descarta o lote inteiro. Nenhuma liquidação será processada. |

## Response

STATUS 200

```json title="Response Body"
{
    "external_id": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "status": "pending_payment"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `external_id` | string | Chave externa do lote fornecida pelo parceiro. |
| `status` | string | Novo status do lote. |

## Possíveis erros

STATUS 404

**Lote não encontrado**

O `external_id` informado na URL não corresponde a nenhum lote cadastrado para este fundo. Verifique se o identificador está correto.

```json
{
  "title": "Payment batch not found",
  "description": "The Payment Batch with external_id {payment_batch_external_id} was not found",
  "translation": "O Lote de Pagamento com identificador externo {payment_batch_external_id} não foi encontrado",
  "code": "SET000010"
}
```

STATUS 400

**Status inválido**

O valor informado no campo `batch_status` não é válido. Utilize apenas `pending_payment` ou `discarded`.

```json
{
  "title": "Invalid status",
  "description": "The status given: {status} is not suported.",
  "translation": "O status: {status} não possui suporte.",
  "code": "SET000026"
}
```

STATUS 400

**Lote sem liquidações**

Você tentou encerrar o lote, mas ele ainda não possui nenhuma liquidação inserida. É necessário [inserir pelo menos uma liquidação](/documentation/iaas/liquidacao_ativos/ativos) antes de encerrar o lote.

```json
{
  "title": "Payment Batch with no settlement",
  "description": "Payment batch of external_id: {payment_batch_external_id} have no settlements to be settled",
  "translation": "O lote de pagamento com identificador: {payment_batch_external_id} não possui liquidações",
  "code": "SET000017"
}
```

## Próximos passos

Após encerrar o lote, o processamento é iniciado automaticamente. Acompanhe o resultado através dos webhooks:

1. **[Webhooks do lote de pagamento](/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook)** — notificação quando o lote for pago.
2. **[Webhooks das liquidações](/documentation/iaas/liquidacao_ativos/ativos/webhook)** — notificação individual de cada liquidação processada.

---

# Listagem de Lotes de Pagamento

URL: /documentation/iaas/liquidacao_ativos/lote_pagamento/listagem

Endpoint de consulta paginada que retorna os lotes de pagamento de uma determinada classe de fundo. Utilize os filtros disponíveis para buscar lotes por status ou data de referência.

## Request

ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batches
MÉTODO GET

### Query params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `status` | string | opcional | Filtra por um status específico do lote. Consulte os [enumeradores de status](#enumeradores-de-status-do-lote). |
| `reference_date` | string | opcional | Filtra por data de referência no formato `YYYY-MM-DD`. |
| `page` | integer | opcional | Número da página (começa em 0). Padrão: `0`. |
| `limit` | integer | opcional | Quantidade de registros por página. Padrão: `10`. Máximo: `50`. |

```python title="Exemplo de chamada"
GET /settlement/fund_class/{fund_class_key}/payment_batches?status=completed&reference_date=2025-01-01&page=0&limit=10
```

## Response

STATUS 200

```json title="Response Body"
{
    "data": [
        {
            "description": "LOTE DE LIQUIDAÇÃO 08/08",
            "fund_class": {
                "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS",
                "manager": {
                    "name": "EXEMPLO CAPITAL",
                    "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
                    "document_number": "45.585.471/0001-47"
                },
                "fund_class_key": "a3ecf74b-d280-4d3c-aefd-cb223dbf0451",
                "document_number": "60.910.091/0001-24"
            },
            "payment_batch_key": "50859e88-544c-4c79-a7aa-d373d90aa571",
            "status": "completed",
            "external_id": "5910209c-9cb5-4569-9069-f2dbc8060434",
            "reference_date": "2025-08-08",
            "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e",
            "total_value": 143.18
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": false
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Lista de objetos de lote de pagamento. Veja tabela abaixo. |
| `page` | integer | Número da página atual. |
| `limit` | integer | Quantidade de registros por página. |
| `is_last_page` | boolean | Indica se esta é a última página de resultados. |

#### Atributos de cada lote (objetos dentro de `data`)

| Campo | Tipo | Descrição |
|---|---|---|
| `description` | string | Descrição do lote. |
| `fund_class` | object | Dados do fundo associado ao lote. Consulte os [atributos de `fund_class`](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao#atributos-de-fund_class) na página de Criação. |
| `payment_batch_key` | string | Identificador único do lote (UUID). |
| `status` | string | Status atual do lote. Consulte os [enumeradores de status](#enumeradores-de-status-do-lote) abaixo. |
| `external_id` | string | Chave externa fornecida pelo parceiro. |
| `reference_date` | string | Data de referência no formato `YYYY-MM-DD`. |
| `account_key` | string | Chave da conta associada ao lote (UUID). |
| `total_value` | number | Valor total das liquidações do lote em reais. Pode não estar presente caso o lote ainda não tenha sido processado. |

## Enumeradores de status do lote

| Status | Descrição |
|---|---|
| `pending_settlements_insertion` | Lote criado, aguardando inserção de liquidações. |
| `pending_payment` | Lote encerrado, aguardando processamento do pagamento. |
| `paid` | Pagamento do lote realizado. |
| `completed` | Processamento do lote finalizado com sucesso. |
| `discarded` | Lote descartado. |

---

# Webhooks do Lote de Pagamento

URL: /documentation/iaas/liquidacao_ativos/lote_pagamento/webhook

Ao longo do fluxo de liquidação, o sistema envia webhooks para notificar o parceiro integrador sobre mudanças de status do lote de pagamento. Todos os webhooks possuem o tipo `settlement.payment_batch_status_change` e identificam o lote pelo `external_id` fornecido na criação.

:::info Configuração de webhooks
Para receber webhooks, é necessário ter uma URL de callback configurada junto à QI Tech. Entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) para configurar.
:::

## Fluxo de status do lote

O lote passa pelos status abaixo até o encerramento. Três deles geram webhook: `paid`, `completed` e `discarded`. Os dois primeiros — `pending_settlements_insertion` e `pending_payment` — são resultado das suas próprias chamadas de [criação](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao) e [encerramento](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento) do lote e **não** disparam notificação.

![Fluxo de status do lote de pagamento, destacando os três status que geram webhook](/img/diagrams/iaas-liquidacao-ativos-lote-pagamento-webhook.svg)

_Como ler o diagrama: **contorno tracejado** = status sem webhook · **azul** = webhook de andamento · **verde** = encerramento com sucesso · **vermelho** = encerramento sem processamento._

## Estrutura do webhook

Todos os webhooks do lote de pagamento seguem a mesma estrutura:

| Campo | Tipo | Descrição |
|---|---|---|
| `webhook_type` | string | Sempre `settlement.payment_batch_status_change`. |
| `webhook_datetime` | string | Data e hora do evento no formato ISO 8601. |
| `data` | object | Dados do evento. Veja tabela abaixo. |

#### Atributos de `data`

| Campo | Tipo | Descrição |
|---|---|---|
| `external_id` | string | Identificador do lote. Veja [Como o `external_id` é formado](#como-o-external_id-é-formado). |
| `status` | string | Novo status do lote. |
| `fund_class_document_number` | string | CNPJ do fundo associado ao lote. |
| `fund_class_key` | string | Chave do fundo na QI Tech (UUID). |
| `payment_batch_key` | string | Identificador único do lote gerado pela QI Tech (UUID). |
| `reference_date` | string | Data de referência do lote, no formato `AAAA-MM-DD`. |
| `total_value` | number | Valor total do lote em reais. Presente depois que o total é apurado, no encerramento do lote — ou seja, nos webhooks de `paid` e `completed`. |
| `description` | string | Descrição do lote. Presente quando o lote possui descrição. |

```json title="Estrutura padrão do webhook"
{
    "data": {
        "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
        "status": "STATUS",
        "fund_class_document_number": "60.910.091/0001-24",
        "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
        "payment_batch_key": "c1f0a9d8-7b6e-4c5d-8a9b-0f1e2d3c4b5a",
        "reference_date": "2024-04-23",
        "total_value": 4520.75,
        "description": "PAGAMENTOS - ABC - 2024-04-23"
    },
    "webhook_type": "settlement.payment_batch_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

## Como o `external_id` é formado

O `external_id` é a chave de correlação entre o lote na QI CTVM e o seu próprio controle. A origem do valor depende de como o lote foi criado:

| Origem do lote | Valor do `external_id` |
|---|---|
| [Criação via API](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao) | Exatamente o `external_id` que você informou no corpo da requisição. |
| Arquivo de liquidação enviado via SFTP | O nome do arquivo **sem a extensão**. |

:::info Lotes criados a partir de um arquivo de liquidação
O webhook **não traz um campo com o nome do arquivo**. Para correlacionar o evento ao arquivo que você enviou, compare o `external_id` com o nome do arquivo sem a extensão:

| Arquivo enviado | `external_id` do lote |
|---|---|
| `liquidacoes_20260811_001.REM` | `liquidacoes_20260811_001` |
| `CNAB_BAIXAS_liquidacoes_20260811_001.REM` | `liquidacoes_20260811_001` |

Como mostra a segunda linha, o prefixo `CNAB_BAIXAS_`, quando presente, também é removido.

O arquivo de retorno com as inconsistências encontradas no processamento, quando gerado, segue a mesma convenção — `retorno_liquidacoes_20260811_001.csv`.
:::

---

## Eventos por status

### Lote Pago

STATUS paid

Enviado quando o pagamento do lote é confirmado pela QI Tech. A partir desse momento, as liquidações individuais são processadas em sequência e os respectivos [webhooks de liquidação](/documentation/iaas/liquidacao_ativos/ativos/webhook) são enviados conforme cada uma for concluída.

```json title="Webhook Body"
{
    "data": {
        "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
        "status": "paid",
        "fund_class_document_number": "60.910.091/0001-24",
        "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
        "payment_batch_key": "c1f0a9d8-7b6e-4c5d-8a9b-0f1e2d3c4b5a",
        "reference_date": "2024-04-23",
        "total_value": 4520.75,
        "description": "PAGAMENTOS - ABC - 2024-04-23"
    },
    "webhook_type": "settlement.payment_batch_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### Lote Concluído

STATUS completed

Enviado quando todas as liquidações do lote atingiram um status final (`settled` ou `discarded`). Este é o status terminal do lote após a conclusão bem-sucedida do ciclo de liquidação. Ao receber este evento, o parceiro integrador pode considerar o lote integralmente processado.

Para identificar a que lote o evento se refere, use o `external_id` — veja [Como o `external_id` é formado](#como-o-external_id-é-formado).

```json title="Webhook Body"
{
    "data": {
        "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
        "status": "completed",
        "fund_class_document_number": "60.910.091/0001-24",
        "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
        "payment_batch_key": "c1f0a9d8-7b6e-4c5d-8a9b-0f1e2d3c4b5a",
        "reference_date": "2024-04-23",
        "total_value": 4520.75,
        "description": "PAGAMENTOS - ABC - 2024-04-23"
    },
    "webhook_type": "settlement.payment_batch_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### Lote Descartado

STATUS discarded

Enviado quando o lote é descartado. Isso pode ocorrer por solicitação explícita do parceiro integrador no [encerramento do lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento), por descarte automático de lotes em aberto pela QI Tech, ou após cancelamento junto à conta caixa. Nenhuma liquidação associada ao lote será processada após este status.

Quando o lote é descartado antes do encerramento, o valor total não chega a ser apurado e o campo `total_value` não vem no payload.

```json title="Webhook Body"
{
    "data": {
        "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
        "status": "discarded",
        "fund_class_document_number": "60.910.091/0001-24",
        "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
        "payment_batch_key": "c1f0a9d8-7b6e-4c5d-8a9b-0f1e2d3c4b5a",
        "reference_date": "2024-04-23",
        "description": "PAGAMENTOS - ABC - 2024-04-23"
    },
    "webhook_type": "settlement.payment_batch_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

# Layout CNAB 444 — Cessão

URL: /documentation/iaas/negociacao_recebiveis/arquivo/cnab444

Layout do arquivo de **remessa de cessão** aceito pela QI CTVM. É o padrão CNAB 444 de cobrança usado no mercado de FIDCs, com as regras de preenchimento e os domínios efetivamente validados pela nossa plataforma.

:::info Onde este arquivo é usado
Este é o arquivo enviado no fluxo descrito em [Cessão por Arquivo](/documentation/iaas/negociacao_recebiveis/arquivo/inicio), pelo portal do gestor ou do consultor. Para dar baixa em ativos já encarteirados, o layout é outro: veja [Layout CNAB 444 — Baixa](/documentation/iaas/liquidacao_ativos/arquivo/cnab444_baixa).
:::

## Estrutura do arquivo

| Registro | Identificação (posição 1) | Quantidade |
|---|---|---|
| **Header** | `0` | 1, sempre a primeira linha |
| **Detalhe** | `1` | 1 por título cedido |
| **Trailer** | `9` | 1, sempre a última linha |

Todas as linhas têm **exatamente 444 caracteres**, sem contar a quebra de linha.

## Nome do arquivo

`CBDDMMxx.REM` ou `CBDDMMxx.TXT` — `CB` fixo, `DD` dia, `MM` mês e `xx` sequencial alfanumérico. Exemplos: `CB120801.REM`, `CB1208AE.TXT`.

Aceitamos qualquer nome, desde que a extensão seja `.rem` ou `.txt`. A convenção acima é apenas a recomendada.

## Regras gerais de preenchimento

| Regra | Detalhe |
|---|---|
| **Tamanho fixo** | Toda linha tem 444 posições. Linhas mais curtas ou mais longas recusam o arquivo. |
| **Campos numéricos** | Alinhados à direita, completados com **zeros** à esquerda. |
| **Campos alfanuméricos** | Alinhados à esquerda, completados com **espaços** à direita. |
| **Valores monetários** | Sempre com 2 casas decimais, **sem** vírgula ou ponto. `R$ 2.470,56` → `000000000247056`. |
| **Datas** | Formato `DDMMAA`. Ex.: 12/08/2025 → `120825`. |
| **Caracteres permitidos** | Apenas `A-Z`, `a-z`, `0-9`, espaço e `. / - , ( ) &`. **Não use acentos nem `Ç`** — troque `SÃO PAULO` por `SAO PAULO` e `AÇOS` por `ACOS`. |
| **Codificação** | UTF-8 ou ASCII. Quebra de linha `CRLF` ou `LF`. |

:::caution O erro mais comum
Acento ou cedilha em nome de sacado, razão social ou endereço. A mensagem devolvida aponta a posição exata e o nome do campo — por exemplo: *"Caracteres inválidos encontrados na posição 240, dentro do campo 'Nome do sacado'."*
:::

## Registro Header

| # | Posição | Tam. | Campo | Obrig. | Conteúdo aceito |
|---|---|---|---|---|---|
| 1 | 001–001 | 1 | Identificação do registro | Sim | `0` |
| 2 | 002–002 | 1 | Identificação do arquivo remessa | Sim | `1` |
| 3 | 003–009 | 7 | Literal remessa | Sim | `REMESSA` |
| 4 | 010–011 | 2 | Código do serviço | Sim | `01` |
| 5 | 012–026 | 15 | Literal do serviço | Sim | `COBRANCA` + 7 espaços |
| 6 | 027–046 | 20 | **Código do originador** | Sim | Código fornecido pela QI CTVM no cadastro, alinhado à direita com zeros |
| 7 | 047–076 | 30 | Nome do originador | Sim | Razão social |
| 8 | 077–079 | 3 | Número do banco | Não | Livre |
| 9 | 080–094 | 15 | Nome do banco | Não | Livre |
| 10 | 095–100 | 6 | Data de gravação do arquivo | Sim | `DDMMAA` |
| 11 | 101–108 | 8 | Brancos | Sim | 8 espaços |
| 12 | 109–110 | 2 | Identificação do sistema | Sim | `MX` |
| 13 | 111–117 | 7 | Nº sequencial do arquivo | Não | Livre |
| 14 | 118–120 | 3 | Banco do cedente | Não | Dígitos ou brancos |
| 15 | 121–125 | 5 | Agência do cedente | Não | Dígitos ou brancos |
| 16 | 126–126 | 1 | DV da agência | Não | Livre |
| 17 | 127–138 | 12 | Conta corrente do cedente | Não | Dígitos ou brancos |
| 18 | 139–139 | 1 | DV da conta corrente | Não | Livre |
| 19 | 140–377 | 238 | Brancos | Sim | Exatamente 238 espaços |
| 20 | 378–391 | 14 | **CPF/CNPJ do cedente original** | Não | CNPJ com 14 caracteres, CPF com 11 dígitos + 3 espaços, ou 14 espaços |
| 21 | 392–438 | 47 | Brancos | Sim | Exatamente 47 espaços |
| 22 | 439–444 | 6 | Nº sequencial do registro | Sim | `000001` |

:::info Código do originador (posições 27–46)
É o identificador do originador **cadastrado na configuração de cessão**. Um código não cadastrado ou vinculado a outra configuração recusa o arquivo com a mensagem *"O código do originador '…' não foi encontrado"*. Solicite o código no processo de homologação do cedente.
:::

:::tip Cedente original (posições 378–391)
Campo específico da QI CTVM, que **não existe no layout de mercado**. Use quando o título já tiver passado por um endosso anterior e você precisar registrar o CNPJ/CPF do cedente de origem. Se não se aplica, deixe em branco.
:::

## Registro Detalhe

Um registro por título. Os campos em **negrito** são os que alimentam o ativo criado na carteira do fundo.

| # | Posição | Tam. | Campo | Obrig. | Conteúdo aceito |
|---|---|---|---|---|---|
| 1 | 001–001 | 1 | Identificação do registro | Sim | `1` |
| 2 | 002–007 | 6 | Data de carência | Não | `DDMMAA` ou zeros |
| 3 | 008–008 | 1 | Tipo de juros | Não | `0` sem correção, `1` juros fixo, `2` CDI, `3` IPCA-15, `4` IPCA, `5` IGPM, ou branco |
| 4 | 009–010 | 2 | Brancos | Sim | 2 espaços |
| 5 | 011–020 | 10 | Taxa de juros | Não | Dígitos (7 decimais) ou 10 espaços |
| 6 | 021–022 | 2 | Coobrigação | Sim | `01` com coobrigação, `02` sem coobrigação |
| 7 | 023–024 | 2 | Característica especial (SCR) | Não | Anexo 8 do SCR 3040, `00` ou brancos |
| 8 | 025–028 | 4 | Modalidade da operação (SCR) | Condicional | Anexo 3 do SCR 3040. Pode ficar em branco para duplicatas e CTe |
| 9 | 029–030 | 2 | Natureza da operação (SCR) | Não | Anexo 2 do SCR 3040, `00` ou brancos |
| 10 | 031–034 | 4 | Origem do recurso (SCR) | Não | Anexo 4 do SCR 3040, `0000` ou brancos |
| 11 | 035–036 | 2 | Classe de risco (SCR) | Não | `AA`, `A`…`H`, `HH`, `01`, `00` ou brancos |
| 12 | 037–037 | 1 | Zeros | Não | `0` ou branco |
| 13 | 038–062 | 25 | **Nº de controle do participante** | Sim | Identificador único do ativo no seu sistema. Alinhado à esquerda |
| 14 | 063–065 | 3 | Número do banco | Não | Dígitos ou brancos |
| 15 | 066–070 | 5 | Zeros | Não | Zeros ou brancos |
| 16 | 071–081 | 11 | Identificação do título no banco | Não | Dígitos ou 11 espaços |
| 17 | 082–082 | 1 | Dígito do nosso número | Não | Livre |
| 18 | 083–092 | 10 | Valor pago | Não | **Zeros** na cessão |
| 19 | 093–093 | 1 | Condição de emissão da papeleta | Não | Branco |
| 20 | 094–094 | 1 | Papeleta para débito automático | Não | Branco |
| 21 | 095–100 | 6 | Data da liquidação | Não | **Zeros** na cessão |
| 22 | 101–104 | 4 | Identificação da operação do banco | Não | 4 espaços ou `0000` |
| 23 | 105–105 | 1 | Indicador de rateio de crédito | Não | Branco ou `0` |
| 24 | 106–106 | 1 | Endereçamento de aviso de débito | Não | Branco |
| 25 | 107–108 | 2 | Brancos | Não | 2 espaços ou `00` |
| 26 | 109–110 | 2 | **Identificação da ocorrência** | Sim | Ver [Ocorrências](#ocorrências-aceitas) |
| 27 | 111–120 | 10 | **Nº do documento** | Sim | Número do título/duplicata. Exatamente 10 caracteres |
| 28 | 121–126 | 6 | **Data de vencimento** | Sim | `DDMMAA` |
| 29 | 127–139 | 13 | **Valor de face** | Sim | Valor nominal do título, 2 decimais |
| 30 | 140–142 | 3 | Banco encarregado da cobrança | Não | Dígitos, zeros ou brancos |
| 31 | 143–147 | 5 | Agência depositária | Não | 5 dígitos, `00000` ou brancos |
| 32 | 148–149 | 2 | **Espécie de título** | Sim | Ver [Espécies](#especies-de-titulo) |
| 33 | 150–150 | 1 | Identificação | Não | Branco |
| 34 | 151–156 | 6 | **Data de emissão do título** | Sim | `DDMMAA` |
| 35 | 157–158 | 2 | 1ª instrução | Não | `00` |
| 36 | 159–159 | 1 | 2ª instrução | Não | `0` |
| 37 | 160–161 | 2 | Tipo de pessoa do cedente | Sim | `01` pessoa física, `02` pessoa jurídica |
| 38 | 162–173 | 12 | Juros/mora por dia de atraso | Não | 12 caracteres alfanuméricos **ou** 12 espaços |
| 39 | 174–192 | 19 | Nº do termo de cessão | Não | Livre ou brancos |
| 40 | 193–205 | 13 | **Valor presente (aquisição)** | Sim | Valor pago pelo fundo por este título, 2 decimais |
| 41 | 206–218 | 13 | Valor do abatimento | Não | Zeros ou dígitos |
| 42 | 219–220 | 2 | **Tipo de inscrição do sacado** | Sim | `01` pessoa física (CPF), `02` pessoa jurídica (CNPJ) |
| 43 | 221–234 | 14 | **Nº de inscrição do sacado** | Sim | CNPJ com 14 posições; CPF com 11 dígitos alinhados à direita. **O dígito verificador é conferido** |
| 44 | 235–274 | 40 | **Nome do sacado** | Sim | Não pode ficar em branco |
| 45 | 275–314 | 40 | **Endereço do sacado** | Sim | Não pode ficar em branco. Ex.: `AV EXEMPLO, 100` |
| 46 | 315–323 | 9 | **Nº da nota fiscal** | Condicional | Obrigatório para duplicatas e CTe |
| 47 | 324–326 | 3 | Série da nota fiscal | Não | 3 alfanuméricos ou 3 espaços. Em branco assume `1` |
| 48 | 327–334 | 8 | **CEP do sacado** | Sim | 8 dígitos, sem hífen |
| 49 | 335–394 | 60 | **Cedente** | Sim | `335–380` nome do cedente (46) · `381–394` CNPJ do cedente (14) |
| 50 | 395–438 | 44 | **Chave da NF-e** | Condicional | 44 dígitos. Obrigatória para `duplicata_mercantil` e `cte` nas ocorrências `01`, `81` e `84` |
| 51 | 439–444 | 6 | Nº sequencial do registro | Sim | Sequencial da linha, começando em `000002` |

## Registro Trailer

| # | Posição | Tam. | Campo | Obrig. | Conteúdo aceito |
|---|---|---|---|---|---|
| 1 | 001–001 | 1 | Identificação do registro | Sim | `9` |
| 2 | 002–438 | 437 | Brancos | Sim | Exatamente 437 espaços |
| 3 | 439–444 | 6 | Nº sequencial do registro | Sim | Número da última linha do arquivo |

## Ocorrências aceitas

A ocorrência (posições 109–110) diz o que fazer com o título.

| Código | Significado | Quando usar |
|---|---|---|
| `01` | **Remessa — aquisição de títulos** | Padrão da cessão. É o que você usa em quase todos os casos |
| `80` | Remessa — aquisição com liquidação para a consultoria | Tratada como aquisição |
| `81` | Entrada por troca de títulos, com liquidação para a consultoria | Contrapartida de recompra dentro do mesmo arquivo |
| `84` | Entrada por troca de títulos, com liquidação para o cedente | Contrapartida de recompra dentro do mesmo arquivo |
| `72` | **Recompra parcial** | Só em lote de substituição. Gera amortização do ativo recomprado |
| `74` | **Baixa por recompra** | Só em lote de substituição. Gera liquidação do ativo recomprado |

:::caution Recompra exige lote de substituição
As ocorrências `72` e `74` só são aceitas quando a configuração de cessão é do tipo substituição e o lote foi criado com `assignment_type: substitution_assignment`. Em um lote comum, o arquivo é recusado com a mensagem *"A ocorrência de recompra '…' só é permitida em configurações de cessão de recompra (substituição)"*.
:::

:::info Ocorrências de baixa não entram aqui
Códigos como `04`, `14`, `75` e `77` pertencem ao arquivo de **baixa** e são processados por outro fluxo. Enviá-los em um arquivo de cessão faz o ativo falhar no processamento, mesmo que a linha passe na validação de estrutura. Veja [Baixa por Arquivo](/documentation/iaas/liquidacao_ativos/arquivo/inicio).
:::

## Espécies de título {#especies-de-titulo}

A espécie, nas posições 148–149, define como o título é lido. **Três códigos são processados no fluxo de cessão por arquivo:**

| Código | Espécie | Tipo de ativo | Nota fiscal | Chave da NF-e | Exemplo |
|---|---|---|---|---|---|
| `01` | Duplicata | `duplicata_mercantil` | Obrigatória | Obrigatória | [Baixar](/downloads/modelos_arquivo/exemplo_cessao_duplicata_mercantil_cnab444.rem) |
| `14` | Duplicata de serviço | `duplicata_servicos` | Obrigatória | Dispensada | [Baixar](/downloads/modelos_arquivo/exemplo_cessao_duplicata_servicos_cnab444.rem) |
| `53` | CT-e | `cte` | Obrigatória | Obrigatória | [Baixar](/downloads/modelos_arquivo/exemplo_cessao_cte_cnab444.rem) |

:::caution Outros códigos passam na estrutura, mas não são processados
O layout CNAB 444 prevê dezenas de espécies — `02` nota promissória, `41` CCB digital, `51` cheque, `60` contrato, entre outras. Elas passam pela validação estrutural do arquivo, mas **não são convertidas em ativo no fluxo de cessão por arquivo**: o processamento devolve *"Asset type … was not expected"* e o lote não avança.

Se o seu produto usa uma dessas espécies, ceda pela API de integração, ativo a ativo, ou confirme o caminho com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) antes de montar o arquivo.
:::

:::info A espécie precisa combinar com a configuração de cessão
Uma configuração de `duplicata_mercantil` espera espécie `01`. Enviar uma espécie incompatível com o tipo de ativo da configuração faz o ativo ser recusado na inserção.
:::

## De-para: do CNAB para o ativo na carteira

Cada linha de detalhe vira um ativo idêntico ao que seria criado pelo endpoint de [Criação de Ativo — Duplicata](/documentation/iaas/negociacao_recebiveis/asset/criacao_duplicata).

| Posição no CNAB | Campo do ativo (API) |
|---|---|
| 038–062 Nº de controle do participante | `discounted_credit_right.external_id` e `participant_control_number` — é por ele que o ativo é referenciado depois, inclusive na baixa |
| 111–120 Nº do documento | `discounted_credit_right.order_number` — identifica a linha dentro do arquivo e **não pode se repetir** |
| 121–126 Data de vencimento | `discounted_credit_right.maturity_date` |
| 127–139 Valor de face | `discounted_credit_right.face_value` |
| 148–149 Espécie de título | `asset_type` |
| 151–156 Data de emissão | `discounted_credit_right.invoice.issue_date` |
| 193–205 Valor presente | `total_purchase_value` |
| 219–220 / 221–234 Sacado | `borrower.person_type` e `borrower.document_number` |
| 235–274 Nome do sacado | `borrower.name` |
| 275–314 Endereço do sacado | `borrower.address.street` e `number` |
| 315–323 / 324–326 Nota fiscal | `invoice.number` e `invoice.serie` |
| 327–334 CEP | `borrower.address.postal_code` |
| 395–438 Chave da NF-e | `invoice.access_key` |
| Header 027–046 Código do originador | `originator_document_number` |
| Header 378–391 Cedente original | `original_assignor_document_number` |

:::tip Endereço do sacado
O logradouro e o número são extraídos do texto das posições 275–314, e o restante do endereço (bairro, cidade e UF) é completado automaticamente a partir do CEP. Escreva no formato `LOGRADOURO, NUMERO`.
:::

## Exemplo comentado

Cessão de duas duplicatas mercantis do cedente `11.222.333/0001-81`, com vencimento em 10/10/2025.

```text title="CB120801.REM"
01REMESSA01COBRANCA       00000011222333000181INDUSTRIA EXEMPLO S/A         ...MX...000001
1...0CTRL000001...01000100001101025000000015100...0245678912000155COMERCIO EXEMPLO ALFA LTDA...000002
1...0CTRL000002...01000200002101025000000015200...0278912345000109COMERCIO EXEMPLO BETA LTDA...000003
9                                                                              ...000004
```

| Linha | Leitura |
|---|---|
| Header | Originador `00000011222333000181`, arquivo gerado em 12/08/2025, sistema `MX` |
| Detalhe 1 | Ativo `CTRL000001`, documento `0001000010`, vence em 10/10/2025, face R$ 1.510,00, aquisição R$ 1.480,00, sacado CNPJ `45.678.912/0001-55` |
| Detalhe 2 | Ativo `CTRL000002`, documento `0002000020`, face R$ 1.520,00, aquisição R$ 1.490,00, sacado CNPJ `78.912.345/0001-09` |
| Trailer | Fecha o arquivo com o sequencial `000004` |

### Arquivos de exemplo

| Arquivo | Espécie | O que traz |
|---|---|---|
| [Duplicata mercantil](/downloads/modelos_arquivo/exemplo_cessao_duplicata_mercantil_cnab444.rem) | `01` | Dois títulos com nota fiscal e chave da NF-e preenchidas |
| [Duplicata de serviços](/downloads/modelos_arquivo/exemplo_cessao_duplicata_servicos_cnab444.rem) | `14` | Dois títulos com nota fiscal e sem chave da NF-e |
| [CT-e](/downloads/modelos_arquivo/exemplo_cessao_cte_cnab444.rem) | `53` | Dois conhecimentos de transporte com chave preenchida |

:::info Sobre os exemplos
Os três arquivos passam integralmente pela nossa validação. Os CNPJs são fictícios, mas têm dígito verificador válido — se você trocar por documentos "redondos" tipo `45678912000199`, o arquivo será recusado.
:::

## Checklist antes de enviar

- [ ] Todas as linhas com exatamente 444 caracteres
- [ ] Header começa com `01REMESSA01COBRANCA` e tem `MX` nas posições 109–110
- [ ] Código do originador cadastrado, alinhado à direita com zeros
- [ ] Sem acentos, `Ç` ou caracteres especiais em qualquer campo
- [ ] CPF/CNPJ do sacado com dígito verificador válido
- [ ] Nome e endereço do sacado preenchidos
- [ ] Chave da NF-e com 44 dígitos nas duplicatas mercantis e CT-e
- [ ] Nº de controle do participante único por ativo
- [ ] Valores monetários sem vírgula, com 2 decimais
- [ ] Ocorrência `01` (ou `72`/`74` apenas em lote de substituição)
- [ ] Sequencial de registro correto, com o trailer fechando na última linha

---

# Layout CSV — Contratos Parcelados

URL: /documentation/iaas/negociacao_recebiveis/arquivo/csv_contrato_parcelado

Layout do arquivo de **cessão de contratos parcelados** (`asset_type` igual a `contract`) aceito pela QI CTVM. É um CSV com **uma linha por parcela**: as linhas que compartilham o mesmo `external_id` são as parcelas de um mesmo contrato e formam um único ativo.

:::info Onde este arquivo é usado
Este é o arquivo enviado no fluxo descrito em [Cessão por Arquivo](/documentation/iaas/negociacao_recebiveis/arquivo/inicio), pelo portal do gestor ou do consultor. Para ceder contrato parcelado ativo a ativo pela API, veja [Criação de Ativo — Contrato Parcelado](/documentation/iaas/negociacao_recebiveis/asset/criacao_contract).
:::

**[📄 Baixar modelo CSV](/downloads/modelos_arquivo/modelo_cessao_contrato_parcelado.csv)**

O modelo já vem com linhas de exemplo preenchidas — dois contratos, um pré-fixado de pessoa física com duas parcelas e um pós-fixado de pessoa jurídica com uma parcela. Apague as linhas de exemplo antes de colocar os seus dados.

## Estrutura do arquivo

| Item | Regra |
|---|---|
| **Cabeçalho** | 1 linha, sempre a primeira, com os nomes das colunas exatamente como no modelo |
| **Linhas de dados** | 1 por **parcela**. Um contrato com 12 parcelas ocupa 12 linhas |
| **Agrupamento** | Linhas com o mesmo `external_id` são o mesmo ativo. O lote é contado em ativos, não em linhas |
| **Extensão** | `.csv` |
| **Separador** | Vírgula (`,`) ou ponto e vírgula (`;`) — detectado a partir da linha de cabeçalho |
| **Codificação** | UTF-8 (com ou sem BOM) |
| **Datas** | Formato `AAAA-MM-DD` |
| **Valores** | Ponto como separador decimal, sem separador de milhar. `R$ 900,00` → `900.00` |
| **Documentos** | CPF em `000.000.000-00` e CNPJ em `00.000.000/0000-00`, sempre com a pontuação |

:::caution O cabeçalho é fechado
Use o cabeçalho do modelo sem alterações: não traduza, não renomeie e não acrescente colunas. Qualquer coluna fora do modelo, ou a falta de uma coluna obrigatória, recusa o arquivo inteiro antes de qualquer linha ser conferida.
:::

## Colunas

### Identificação

| Coluna | Obrigatoriedade | Descrição |
|---|---|---|
| `asset_type` | obrigatória | Tipo do ativo. Para contrato parcelado, o único valor aceito é `contract`, em todas as linhas |
| `external_id` | obrigatória | Identificador do contrato no seu sistema, até 50 caracteres. É a chave do ativo: as parcelas do mesmo contrato repetem o mesmo valor |
| `originator_document_number` | obrigatória | CPF ou CNPJ do originador, com pontuação. Precisa estar cadastrado e vinculado à configuração de cessão, e ser o mesmo em todas as linhas do arquivo |
| `contract_number` | obrigatória | Número do contrato, até 50 caracteres. Enviado exatamente como escrito, sem normalização |
| `contract_issue_date` | opcional | Data de emissão do contrato, em `AAAA-MM-DD` |

### Valores e juros

| Coluna | Obrigatoriedade | Descrição |
|---|---|---|
| `total_purchase_value` | obrigatória | Valor que o fundo paga pelo contrato inteiro. Repita o mesmo valor em todas as linhas do contrato |
| `interest_rate_type` | obrigatória | `pre_fixed` ou `post_fixed`. Define quais colunas de taxa passam a ser obrigatórias |
| `calendar_base` | opcional | Base de contagem de dias do contrato: `workdays`, `calendar_360` ou `calendar_365`. Em branco, é assumido `workdays` |
| `pre_fixed_calendar_base` | condicional | Base de contagem de dias da taxa pré-fixada. Obrigatória quando `interest_rate_type` é `pre_fixed` |
| `pre_fixed_monthly_rate` | condicional | Taxa mensal pré-fixada, em fração decimal menor que 1 e com até 8 casas: `0.015` significa 1,5% ao mês. Obrigatória quando `interest_rate_type` é `pre_fixed` |
| `post_fixed_calendar_base` | condicional | Base de contagem de dias da correção pós-fixada. Obrigatória quando `interest_rate_type` é `post_fixed` |
| `post_fixed_indexer` | condicional | Índice que corrige o contrato: `di`, `selic` ou `ipca`. Obrigatória quando `interest_rate_type` é `post_fixed` |
| `post_fixed_rate` | condicional | Taxa aplicada sobre o indexador. `1` significa 100% do índice. Obrigatória quando `interest_rate_type` é `post_fixed` |
| `post_fixed_lag_reference` | condicional | Unidade da defasagem do índice: `daily` ou `monthly`. Obrigatória quando `interest_rate_type` é `post_fixed` |
| `post_fixed_lag_amount` | condicional | Quantidade de defasagem, em número inteiro (ex.: `2` com `monthly` usa o índice de dois meses antes). Obrigatória quando `interest_rate_type` é `post_fixed` |

:::caution Ágio e dedução não entram no arquivo
O CSV de contrato parcelado não tem colunas de ágio ou dedução — elas não se aplicam a este tipo de ativo. O valor de aquisição é sempre o `total_purchase_value`.
:::

### Parcelas

| Coluna | Obrigatoriedade | Descrição |
|---|---|---|
| `installment_number` | obrigatória | Número da parcela, inteiro começando em 1. Uma linha por parcela |
| `installment_maturity_date` | obrigatória | Data de vencimento da parcela, em `AAAA-MM-DD`. As datas precisam crescer junto com o número da parcela |
| `installment_face_value` | obrigatória | Valor de face da parcela — quanto o sacado paga no vencimento. Ponto como separador decimal, até 8 casas |
| `installment_principal_value` | opcional | Parte do principal amortizada nesta parcela |
| `installment_external_id` | opcional | Identificador da parcela no seu sistema, até 50 caracteres |

### Sacado

| Coluna | Obrigatoriedade | Descrição |
|---|---|---|
| `borrower_name` | obrigatória | Nome completo do sacado, até 255 caracteres |
| `borrower_document_number` | obrigatória | CPF ou CNPJ do sacado, com pontuação e compatível com o `borrower_person_type` |
| `borrower_person_type` | obrigatória | `natural_person` (pessoa física) ou `legal_person` (pessoa jurídica) |
| `borrower_gender` | condicional | `male` ou `female`. Obrigatória quando `borrower_person_type` é `natural_person`; deixe em branco para pessoa jurídica |
| `borrower_mother_name` | opcional | Nome da mãe do sacado. Usado apenas para pessoa física |
| `borrower_birthdate` | opcional | Data de nascimento do sacado, em `AAAA-MM-DD`. Usada apenas para pessoa física |
| `borrower_email` | opcional | E-mail do sacado |
| `borrower_phone_area_code` | opcional | DDD do telefone, exatamente 2 dígitos. Se informar o DDD, informe também o número |
| `borrower_phone_number` | opcional | Telefone do sacado, 8 ou 9 dígitos, sem DDD e sem pontuação |
| `borrower_address_postal_code` | opcional | CEP no formato `00000-000`. Se preencher qualquer outro campo de endereço, o CEP passa a ser obrigatório |
| `borrower_address_street` | opcional | Logradouro, até 255 caracteres |
| `borrower_address_number` | opcional | Número do endereço, até 40 caracteres |
| `borrower_address_neighborhood` | opcional | Bairro, até 255 caracteres |
| `borrower_address_city` | opcional | Cidade, até 255 caracteres |
| `borrower_address_uf` | opcional | Sigla de 2 letras do estado, em maiúsculas (ex.: `SP`) |
| `borrower_address_country` | opcional | País em 3 letras (ex.: `BRA`) |

## Regras do arquivo

- **Uma linha por parcela, um `external_id` por contrato.** O contador de ativos do lote usa os `external_id` distintos.
- **As linhas do mesmo contrato precisam ser idênticas fora das colunas de parcela.** Todas as colunas cujo nome **não** contém `installment` são conferidas entre as linhas que compartilham o `external_id`; qualquer divergência aponta os campos diferentes e recusa o arquivo.
- **O fluxo de pagamento precisa ser crescente.** Parcela maior com vencimento anterior ao de uma parcela menor recusa o arquivo.
- **`installment_number` precisa formar a sequência `1, 2, 3, …`** dentro de cada contrato, ordenado por vencimento. Uma numeração com salto ou repetição faz o ativo ser recusado com o código `TRC000174`, sem derrubar os demais ativos do arquivo.
- **Todas as linhas precisam ter o mesmo `originator_document_number`**, e esse originador precisa estar cadastrado e vinculado à configuração de cessão.
- **Não inclua as colunas de recompra** (`assignor_document_number` e `settlement_type`): com elas o arquivo passa a ser lido como substituição e é recusado. Lote de substituição de contrato parcelado não é aceito por arquivo hoje.
- **O identificador do lote é único e definitivo.** Um lote recusado não pode ser reenviado com o mesmo identificador — envie um lote novo.
- **A validação é tudo ou nada na etapa de arquivo.** Uma linha inválida recusa o arquivo inteiro, e o relatório lista no máximo **50 erros** por envio.

## Erros mais comuns

| Mensagem | Causa |
|---|---|
| Coluna obrigatória ausente no cabeçalho | O cabeçalho foi editado ou salvo de um modelo antigo |
| Linhas com o mesmo identificador possuem dados inconsistentes nos campos: … | Alguma coluna que não é de parcela mudou entre as linhas do mesmo contrato |
| Fluxo de pagamento inválido para o ativo … | Vencimentos fora de ordem em relação ao número da parcela |
| Número da parcela … inválido | `installment_number` com texto, decimal ou em branco |
| O contrato … deve ter os números das parcelas em sequência iniciando em 1 | Salto ou repetição na numeração das parcelas (`TRC000174`) |
| O número de documento … não é válido | CPF ou CNPJ sem pontuação ou com dígito verificador inválido |
| Esse lote não pode receber esse tipo de ativo | O `asset_type` do arquivo não é o da configuração de cessão selecionada |

## Exemplo

```csv title="modelo_cessao_contrato_parcelado.csv (colunas principais)"
asset_type,external_id,contract_number,total_purchase_value,interest_rate_type,borrower_name,borrower_document_number,installment_number,installment_maturity_date,installment_face_value
contract,CONTRATO_0001,1144927986/XXX,900.00,pre_fixed,Jove de Souza,593.607.530-33,1,2026-12-25,500.46
contract,CONTRATO_0001,1144927986/XXX,900.00,pre_fixed,Jove de Souza,593.607.530-33,2,2027-01-25,500.46
contract,CONTRATO_0002,2244927986/XXX,450.00,post_fixed,Empresa Souza LTDA,53.020.654/0001-43,1,2026-12-25,500.46
```

O trecho acima mostra apenas as colunas principais, para leitura. O arquivo enviado precisa ter **todas** as colunas do modelo no cabeçalho — baixe o [modelo completo](/downloads/modelos_arquivo/modelo_cessao_contrato_parcelado.csv).

## Checklist antes de enviar

- [ ] Cabeçalho igual ao do modelo, sem colunas extras nem faltando
- [ ] `asset_type` igual a `contract` em todas as linhas, e igual ao tipo da configuração de cessão
- [ ] Uma linha por parcela, com o `external_id` repetido nas parcelas do mesmo contrato
- [ ] Colunas que não são de parcela idênticas entre as linhas do mesmo contrato
- [ ] `installment_number` em sequência de 1 a N, com vencimentos crescentes
- [ ] Colunas `pre_fixed_*` **ou** `post_fixed_*` preenchidas conforme o `interest_rate_type`
- [ ] `borrower_gender` preenchido para sacado pessoa física
- [ ] CPF/CNPJ com pontuação e dígito verificador válido
- [ ] Valores com ponto decimal e sem separador de milhar
- [ ] Arquivo salvo como CSV em UTF-8

---

# Cessão por Arquivo

URL: /documentation/iaas/negociacao_recebiveis/arquivo/inicio

Além da inserção ativo a ativo pela API, é possível ceder um lote inteiro **enviando um único arquivo** pelo portal do gestor ou do consultor. O arquivo é validado linha a linha, convertido em ativos e segue exatamente o mesmo fluxo de elegibilidade, aprovação, termo de cessão e pagamento descrito na [Introdução](/documentation/iaas/negociacao_recebiveis/inicio).

:::info Envio por arquivo é um fluxo de tela
O envio de arquivo de cessão é feito **pelo portal**, não pela API de integração. Pela API, a cessão é feita pelo fluxo de [criação de lote + inserção de ativos](/documentation/iaas/negociacao_recebiveis/fluxo_cessao), ativo a ativo, sem arquivo.
:::

| | Envio por arquivo | Inserção pela API |
|---|---|---|
| **Como funciona** | Um arquivo com todos os ativos do lote | Uma requisição por ativo |
| **Formatos** | CNAB 444 (duplicatas, contratos, CTe) e CSV (CCB, honorários e contratos parcelados) | JSON |
| **Indicado para** | Quem já gera CNAB para bancos/FIDCs e quer reaproveitar o layout | Quem quer controle e retorno por ativo, em tempo real |
| **Retorno de erro** | Consolidado ao final da validação do arquivo | Imediato, na resposta de cada ativo |
| **Disponível em** | Portal do gestor e do consultor | API de integração |

Os dois caminhos produzem o mesmo lote e o mesmo resultado. Escolha um por lote — não é possível misturar arquivo e API no mesmo lote.

## Formatos aceitos

O formato é determinado pelo **tipo de ativo da configuração de cessão** que você seleciona na tela.

| Tipo de ativo da configuração | Formato do arquivo | Extensão | Modelo |
|---|---|---|---|
| `duplicata_mercantil` | **CNAB 444**, espécie `01` | `.rem` · `.txt` | [Exemplo](/downloads/modelos_arquivo/exemplo_cessao_duplicata_mercantil_cnab444.rem) |
| `duplicata_servicos` | **CNAB 444**, espécie `14` | `.rem` · `.txt` | [Exemplo](/downloads/modelos_arquivo/exemplo_cessao_duplicata_servicos_cnab444.rem) |
| `cte` | **CNAB 444**, espécie `53` | `.rem` · `.txt` | [Exemplo](/downloads/modelos_arquivo/exemplo_cessao_cte_cnab444.rem) |
| `ccb` e `structured_cci` | **CSV** | `.csv` | [Modelo](/downloads/modelos_arquivo/modelo_cessao_ccb.csv) |
| `legal_fees` (honorários advocatícios) | **CSV** | `.csv` | [Modelo](/downloads/modelos_arquivo/modelo_cessao_honorarios.csv) |
| `contract` (contratos parcelados) | **CSV** | `.csv` | [Modelo](/downloads/modelos_arquivo/modelo_cessao_contrato_parcelado.csv) |

Em lotes de substituição, as linhas de recompra entram no mesmo CSV, com as colunas de recompra: [modelo de substituição](/downloads/modelos_arquivo/modelo_cessao_substituicao.csv).

:::caution Cada formato atende tipos específicos
O CSV é aceito apenas para `ccb`, `structured_cci`, `legal_fees` e `contract`. Para **cessão de duplicatas e CT-e o formato é o CNAB 444** — o mesmo layout de remessa de cobrança usado no mercado, descrito em [Layout CNAB 444 — Cessão](/documentation/iaas/negociacao_recebiveis/arquivo/cnab444). O layout do CSV de contratos parcelados está em [Layout CSV — Contratos Parcelados](/documentation/iaas/negociacao_recebiveis/arquivo/csv_contrato_parcelado).

Demais tipos de ativo, como `discounted_contract`, são cedidos **pela API**, ativo a ativo — não há formato de arquivo para eles hoje.
:::

## Fluxo do envio

<FlowDiagram
  columns={3}
  labels={{ manager: 'Você, no portal' }}
  nodes={[
    { id: 'formulario', row: 1, col: 2, actor: 'manager', num: 1,
      title: 'Dados do lote',
      desc: 'Cedente, configuração de cessão, substituição e meio de pagamento ao cedente.' },

    { id: 'upload', row: 2, col: 2, actor: 'manager', num: 2,
      title: 'Upload do arquivo',
      desc: 'Arraste o arquivo .rem, .txt ou .csv para a área de upload e confirme o envio.' },

    { id: 'validacao', row: 3, col: 2, actor: 'qitech',
      title: 'Validação do arquivo',
      desc: 'Estrutura, posições, domínios e documentos são conferidos linha a linha.' },

    { id: 'descartado', row: 4, col: 1, actor: 'qitech', tone: 'end',
      title: 'Arquivo recusado',
      desc: 'Uma única linha inválida recusa o arquivo inteiro. O portal exibe as linhas e os motivos.' },

    { id: 'lote', row: 4, col: 2, actor: 'qitech', tone: 'ok',
      title: 'Lote criado com os ativos',
      desc: 'Cada linha vira um ativo e o lote entra no fluxo padrão de cessão.',
      href: '/documentation/iaas/negociacao_recebiveis/inicio' },

    { id: 'esteira', row: 5, col: 2, actor: 'qitech',
      title: 'Elegibilidade, aprovação, termo e pagamento',
      desc: 'A partir daqui o fluxo é idêntico ao da cessão via API.',
      href: '/documentation/iaas/negociacao_recebiveis/fluxo_cessao' },
  ]}
  edges={[
    { from: 'formulario', to: 'upload' },
    { from: 'upload', to: 'validacao' },
    { from: 'validacao', to: 'descartado', label: 'linha inválida', tone: 'end' },
    { from: 'validacao', to: 'lote', label: 'arquivo válido', tone: 'ok' },
    { from: 'lote', to: 'esteira' },
  ]}
/>

## Passo a passo pela tela

No **portal do gestor** e no **portal do consultor**:

1. Acesse **Ativos › Cessões** e clique em **Nova cessão**.
2. Informe o **cedente** (CPF/CNPJ) e selecione a **configuração de cessão** — é ela que define o fundo, o tipo de ativo e, portanto, o formato de arquivo aceito.
3. Informe o **identificador do lote** e a **data da cessão**, que precisa ser a data contábil aberta do fundo — normalmente o dia útil corrente.
4. Marque **Substituição** se o lote tiver ativos de recompra.
5. Escolha o **meio de pagamento** ao cedente (Pix ou TED), quando aplicável.
6. Arraste o arquivo (`.rem`, `.txt` ou `.csv`) para a área de upload e confirme.

O lote passa a aparecer na listagem de cessões, com o status atualizado em tempo real conforme a validação avança.

:::info Permissões
O usuário precisa da permissão de criação de cessão por arquivo no fundo em questão. A concessão é feita pelo administrador do portal em **Usuários › Associações do fundo**.
:::

## Acompanhamento e retorno de erros

A listagem de cessões mostra o andamento do lote de arquivo:

| Etapa | O que significa | O que fazer |
|---|---|---|
| Aguardando arquivo | Lote criado, arquivo ainda não enviado | Faça o upload e confirme o envio |
| Validação em andamento | Arquivo recebido, sendo conferido linha a linha | Aguarde |
| Criando o lote | Arquivo válido, lote sendo criado | Aguarde |
| Inserindo os ativos | Cada linha está virando um ativo | Aguarde |
| Concluído | Todos os ativos inseridos | Acompanhe o lote pelo [fluxo de cessão](/documentation/iaas/negociacao_recebiveis/fluxo_cessao) |
| Recusado | Arquivo recusado na validação | Corrija o arquivo e envie um **lote novo**, com um novo identificador |

Quando o arquivo é recusado, o portal lista as linhas inválidas e, para cada uma, o campo, as posições no registro e a descrição do erro em português — por exemplo:

> Linha 1, posições 218–234: o CNPJ do sacado '45678912000199' é inválido. Verifique o número do documento e tente novamente.

:::caution Validação é tudo ou nada
Uma única linha inválida recusa o arquivo inteiro — não existe processamento parcial. A análise para após **50 erros encontrados**, então corrija os erros apontados e reenvie: podem existir outros adiante.
:::

## Regras que valem para qualquer arquivo

- **O identificador do lote é único e definitivo.** Um lote recusado não pode ser reenviado com o mesmo identificador.
- **A data da cessão precisa ser a data contábil aberta do fundo.** Outra data devolve erro na criação do lote.
- **O arquivo é imutável.** Para alterar qualquer informação, envie um lote novo.
- **Cada linha vira um ativo**, identificado pelo número do documento (posições 111–120 no CNAB). Em arquivos de duplicata e CT-e, **duas linhas com o mesmo número de documento derrubam a cessão inteira** — cada título precisa de um número próprio. Em CSV de CCB e de contrato parcelado, ao contrário, várias linhas com o mesmo identificador são lidas como as parcelas de um mesmo contrato.
- **O cedente e o originador precisam estar previamente cadastrados** e vinculados à configuração de cessão — veja [Homologação de Cedente](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato).

:::info Envio por SFTP
Para operações de alto volume, a QI CTVM também disponibiliza a esteira de remessa por SFTP, com diretório dedicado por fundo e cedente e arquivo de retorno com os erros. É uma configuração sob demanda — fale com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br).
:::

---

# Criação de Ativo — CCB

URL: /documentation/iaas/negociacao_recebiveis/asset/criacao_co

Endpoint para inserir um ativo do tipo **CCB** (Cédula de Crédito Bancário) em um lote de cessão. Cada ativo representa uma operação de crédito que será cedida ao fundo.

:::tip Onde estou no fluxo?
Este é o **2º passo** do fluxo de cessão. Antes, você deve ter [criado o lote](/documentation/iaas/negociacao_recebiveis/assignment/criacao). Após inserir os ativos, envie os [documentos](/documentation/iaas/negociacao_recebiveis/asset/documents) exigidos e [encerre a inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento).
:::

:::caution Atenção
O campo `external_id` da operação de crédito deve ser único para cada ativo e não deve ser confundido com o `external_id` do lote.
:::

## Request

ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/asset
MÉTODO POST

```json title="Request Body"
{
    "asset_type": "ccb",
    "total_purchase_value": 1351.66,
    "premiums": [
      {
        "premium_type": "spread",
        "total_value": 13.38
      }
    ],
    "credit_operation": {
      "contract": {
        "number": "0008309052/NBF",
        "disbursement_date": "2023-07-06",
        "issue_date": "2023-07-06",
        "signature_date": "2023-07-06",
        "issue_value": 1338.28
      },
      "amortization_type": "sac",
      "borrower": {
        "name": "QI CTVM",
        "document_number": "19.845.976/0001-93",
        "person_type": "legal_person",
        "email": "qidtvm@qitech.com.br",
        "address": {
          "street": "Pátio de Teixeira",
          "number": "1",
          "neighborhood": "Estrela do Oriente",
          "city": "Rondônia",
          "postal_code": "01012-030",
          "uf": "RO",
          "country": "BRA"
        },
        "phone": {
          "area_code": "11",
          "number": "936360268"
        },
        "legal_person": {
          "activity_code": "11.11-1-11"
        }
      },
      "delay": {
        "fine": {
          "fine_type": "percentage",
          "percentage_value": 0.0
        },
        "interest": {
          "method": "compound",
          "pre_fixed": {
            "monthly_rate": 0.0,
            "calendar_base": "calendar_360"
          }
        }
      },
      "principal_value": 1338.28,
      "interest_rate_type": "pre_fixed",
      "external_id": "ccf6f331-d55f-46c0-a32f-fb909884dbb2",
      "originator_document_number": "75.723.105/0001-78",
      "pre_fixed": {
        "calendar_base": "calendar_365",
        "monthly_rate": 0.018
      },
      "installments": [
        {
          "maturity_date": "2023-10-01",
          "installment_number": 1,
          "face_value": 689.33
        },
        {
          "maturity_date": "2024-10-01",
          "installment_number": 2,
          "face_value": 482.53
        },
        {
          "maturity_date": "2025-10-01",
          "installment_number": 3,
          "face_value": 300.36
        },
        {
          "maturity_date": "2026-10-01",
          "installment_number": 4,
          "face_value": 162.77
        },
        {
          "maturity_date": "2027-10-01",
          "installment_number": 5,
          "face_value": 81.39
        },
        {
          "maturity_date": "2028-10-01",
          "installment_number": 6,
          "face_value": 40.69
        }
      ],
      "modality_code": "0202",
      "consignee": {
        "consignee_type": "inss",
        "name": "Consignee name",
        "document_number": "11.620.231/3105-71"
      },
      "collaterals": [
        {
          "collateral_type": "social_security",
          "benefit_number": "0000000000",
          "benefit_type": "benefit_type",
          "status": "reserved"
        }
      ]
    }
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `asset_type` | string | obrigatório | Tipo do ativo. Para CCB, informar `ccb`. |
| `total_purchase_value` | number | obrigatório | Valor total da compra do ativo — efetivamente quanto o cessionário vai pagar. Até 2 casas decimais. |
| `premiums` | array | opcional | Lista de ágios envolvidos na venda. Informação apenas para visualização posterior — não é utilizada em cálculos. |
| `credit_operation` | object | obrigatório | Dados da operação de crédito. Veja [Atributos de `credit_operation`](#atributos-de-credit_operation). |

#### Atributos de `premiums`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `premium_type` | string | obrigatório | Tipo do ágio. |
| `total_value` | number | obrigatório | Valor total do ágio. Até 2 casas decimais. |

**Enumeradores de `premium_type`:**

| Valor | Descrição |
|---|---|
| `spread` | Spread vinculado à originação e emissão do crédito. |

#### Atributos de `credit_operation`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `external_id` | string | obrigatório | Chave única de identificação deste ativo no sistema do parceiro. Máximo de 50 caracteres. |
| `originator_document_number` | string | obrigatório | CPF ou CNPJ formatado do originador/consultor que viabilizou a operação. |
| `principal_value` | number | obrigatório | Principal total em aberto da operação. Até 8 casas decimais. |
| `contract` | object | obrigatório | Dados do contrato. Veja [Atributos de `contract`](#atributos-de-contract). |
| `borrower` | object | obrigatório | Dados do sacado/devedor. Veja [Atributos de `borrower`](#atributos-de-borrower). |
| `amortization_type` | string | obrigatório | Tipo de amortização utilizado no cálculo. |
| `interest_rate_type` | string | obrigatório | Tipo de juros da operação. |
| `pre_fixed` | object | obrigatório | Dados do cálculo da parte pré-fixada. Veja [Atributos de `pre_fixed`](#atributos-de-pre_fixed). |
| `installments` | array | obrigatório | Lista de parcelas da operação. Veja [Atributos de `installments`](#atributos-de-installments). |
| `delay` | object | opcional | Dados de multa e juros por atraso. Veja [Atributos de `delay`](#atributos-de-delay). |
| `modality_code` | string | opcional | Código de 4 dígitos que especifica a categoria ou tipo de operação financeira associada ao ativo. |
| `consignee` | object | opcional | Dados do ente consignante. Veja [Atributos de `consignee`](#atributos-de-consignee). |
| `collaterals` | array | opcional | Lista de garantias associadas à operação. Veja [Atributos de `collaterals`](#atributos-de-collaterals). |

**Enumeradores de `amortization_type`:**

| Valor | Descrição |
|---|---|
| `sac` | Amortização do tipo SAC. |
| `price` | Amortização do tipo Price. |

**Enumeradores de `interest_rate_type`:**

| Valor | Descrição |
|---|---|
| `pre_fixed` | Para operações pré-fixadas. |
| `post_fixed` | Para operações pós-fixadas. |

#### Atributos de `contract`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `number` | string | obrigatório | Número do contrato. Máximo de 50 caracteres. |
| `disbursement_date` | string | obrigatório | Data de desembolso no formato `YYYY-MM-DD`. |
| `issue_date` | string | obrigatório | Data de emissão no formato `YYYY-MM-DD`. |
| `signature_date` | string | opcional | Data de assinatura do contrato no formato `YYYY-MM-DD`. |
| `issue_value` | number | obrigatório | Valor de emissão do contrato. Até 2 casas decimais. |

#### Atributos de `borrower`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `name` | string | obrigatório | Nome do sacado. Máximo de 255 caracteres. |
| `document_number` | string | obrigatório | CPF ou CNPJ do sacado. |
| `person_type` | string | obrigatório | Tipo de pessoa. |
| `email` | string | opcional | E-mail do sacado. Máximo de 255 caracteres. |
| `address` | object | obrigatório | Endereço do sacado. Veja [Atributos de `address`](#atributos-de-address). |
| `phone` | object | opcional | Telefone do sacado. Veja [Atributos de `phone`](#atributos-de-phone). |

**Enumeradores de `person_type`:**

| Valor | Descrição |
|---|---|
| `natural_person` | Pessoa Física. Quando informado, incluir o objeto `natural_person` dentro de `borrower`. Veja [Atributos de `natural_person`](#atributos-de-natural_person). |
| `legal_person` | Pessoa Jurídica. Quando informado, incluir o objeto `legal_person` dentro de `borrower`. Veja [Atributos de `legal_person`](#atributos-de-legal_person). |

#### Atributos de `address`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `street` | string | obrigatório | Logradouro. Caso não tenha todas as informações, enviar o compilado neste campo. Máximo de 255 caracteres. |
| `number` | string | opcional | Número do endereço. Máximo de 40 caracteres. |
| `neighborhood` | string | opcional | Bairro. Máximo de 255 caracteres. |
| `city` | string | opcional | Cidade. Máximo de 255 caracteres. |
| `uf` | string | opcional | Sigla do estado. 2 caracteres. |
| `complement` | string | opcional | Complemento. Máximo de 255 caracteres. |
| `postal_code` | string | obrigatório | CEP. 9 caracteres (com hífen). |
| `country` | string | opcional | País no formato ISO 3166-1 alpha-3. 3 caracteres. |

#### Atributos de `phone`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `area_code` | string | obrigatório | Código de área (DDD). 2 dígitos. |
| `number` | string | obrigatório | Número de telefone. Até 9 dígitos. |

#### Atributos de `natural_person`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `birthdate` | string | opcional | Data de nascimento no formato `YYYY-MM-DD`. |
| `gender` | string | opcional | Gênero. |
| `mother_name` | string | opcional | Nome da mãe. Máximo de 255 caracteres. |

**Enumeradores de `gender`:**

| Valor | Descrição |
|---|---|
| `male` | Masculino. |
| `female` | Feminino. |

#### Atributos de `legal_person`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `foundation_date` | string | opcional | Data de fundação no formato `YYYY-MM-DD`. |
| `activity_code` | string | obrigatório | Código de atividade no formato `11.11-1-11`. |
| `annual_revenues` | integer | opcional | Receita anual em centavos. |
| `representatives` | array | opcional | Lista de representantes legais. Veja [Atributos de `representatives`](#atributos-de-representatives). |

#### Atributos de `representatives`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `name` | string | obrigatório | Nome do representante. Máximo de 255 caracteres. |
| `document_number` | string | obrigatório | CPF ou CNPJ do representante. |
| `email` | string | opcional | E-mail do representante. Máximo de 255 caracteres. |
| `phone` | object | opcional | Telefone. Mesma estrutura de [Atributos de `phone`](#atributos-de-phone). |
| `address` | object | opcional | Endereço. Mesma estrutura de [Atributos de `address`](#atributos-de-address). |
| `person_type` | string | obrigatório | Tipo de pessoa (`natural_person` ou `legal_person`). |
| `representative_type` | string | opcional | Tipo do representante. Máximo de 50 caracteres. |

#### Atributos de `pre_fixed`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `calendar_base` | string | obrigatório | Base de cálculo utilizada. |
| `monthly_rate` | number | obrigatório | Taxa mensal do contrato. Para 1%, informar `0.01`. Até 8 casas decimais. |

**Enumeradores de `calendar_base`:**

| Valor | Descrição |
|---|---|
| `workdays` | Base de cálculo em dias úteis (252). |
| `calendar_365` | Base de cálculo em 365 dias. |
| `calendar_360` | Base de cálculo em 360 dias. |

#### Atributos de `installments`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `maturity_date` | string | obrigatório | Data de vencimento da parcela no formato `YYYY-MM-DD`. |
| `installment_number` | integer | obrigatório | Número da parcela. |
| `face_value` | number | opcional | Valor de face da parcela. Até 8 casas decimais. |
| `principal_value` | number | opcional | Principal esperado a ser amortizado na data de vencimento. Até 8 casas decimais. |

#### Atributos de `delay`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `fine` | object | opcional | Dados da multa por atraso. Veja [Atributos de `fine`](#atributos-de-fine). |
| `interest` | object | opcional | Dados do juros de mora. Veja [Atributos de `interest`](#atributos-de-interest). |

#### Atributos de `fine`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `fine_type` | string | obrigatório | Tipo da multa. |
| `percentage_value` | number | condicional | Valor da multa quando `fine_type` for `percentage`. De 0 a 1, representando 0% a 100%. Até 2 casas decimais. |
| `amount` | number | condicional | Valor fixo da multa quando `fine_type` for `fixed`. Até 2 casas decimais. |

**Enumeradores de `fine_type`:**

| Valor | Descrição |
|---|---|
| `percentage` | Multa percentual sobre o valor da parcela. |
| `fixed` | Valor fixo de multa. |

#### Atributos de `interest`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `method` | string | obrigatório | Método do juros de mora. |
| `pre_fixed` | object | obrigatório | Dados da taxa pré-fixada. Mesma estrutura de [Atributos de `pre_fixed`](#atributos-de-pre_fixed). |

**Enumeradores de `method`:**

| Valor | Descrição |
|---|---|
| `compound` | Juros de mora composto. |
| `simple` | Juros de mora simples. |

#### Atributos de `consignee`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `name` | string | obrigatório | Nome do ente consignante. Máximo de 255 caracteres. |
| `document_number` | string | obrigatório | CPF ou CNPJ do ente consignante. |
| `consignee_type` | string | obrigatório | Tipo de consignado. |

**Enumeradores de `consignee_type`:**

| Valor | Descrição |
|---|---|
| `public` | Consignado público. |
| `private` | Consignado privado. |
| `inss` | Consignado INSS. |

#### Atributos de `collaterals`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `collateral_type` | string | obrigatório | Tipo de garantia. |

:::info Como montar `collaterals`
`collaterals` é uma lista e cada item representa **uma** garantia. O `collateral_type` determina quais campos aquele item aceita — os campos de um tipo não são aceitos em outro. Qualquer propriedade fora do conjunto do tipo informado é recusada com `QIT000001`.
:::

**Enumeradores de `collateral_type`:**

| Valor | Descrição |
|---|---|
| `fgts` | Garantia de FGTS. Incluir os campos de [Atributos de garantia FGTS](#atributos-de-garantia-fgts). |
| `social_security` | Garantia de INSS. Incluir os campos de [Atributos de garantia INSS](#atributos-de-garantia-inss). |
| `home_equity` | Garantia de imóveis. Incluir os campos de [Atributos de garantia imóvel](#atributos-de-garantia-imóvel). |
| `vehicle` | Garantia de veículo. Incluir os campos de [Atributos de garantia veículo](#atributos-de-garantia-veículo). |

#### Atributos de garantia FGTS

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `protocol_number` | string | obrigatório | Número do protocolo. |
| `status` | string | obrigatório | Status da garantia. |

#### Atributos de garantia INSS

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `benefit_number` | string | obrigatório | Número do benefício. |
| `benefit_type` | string | obrigatório | Tipo do benefício. |
| `status` | string | obrigatório | Status da garantia. |

#### Atributos de garantia imóvel

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `enterprise_name` | string | obrigatório | Nome do empreendimento. |
| `registration_number` | string | obrigatório | Número do registro do imóvel. |
| `enterprise_document_number` | string | opcional | CPF ou CNPJ associado ao empreendimento. |
| `collateral_properties` | array | obrigatório | Lista de propriedades do imóvel. Veja [Atributos de `collateral_properties`](#atributos-de-collateral_properties). |

#### Atributos de `collateral_properties`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `address` | object | obrigatório | Endereço do imóvel. Mesma estrutura de [Atributos de `address`](#atributos-de-address). |
| `total_collateral_value` | number | obrigatório | Valor do imóvel. Até 8 casas decimais. |

#### Atributos de garantia veículo

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `vehicle_loan_value` | number | opcional | Valor financiado do veículo. Não pode ser negativo. |
| `vehicle_total_market_value` | number | opcional | Valor de mercado total do veículo. Não pode ser negativo. |
| `vehicle_identification` | object | obrigatório | Identificação do veículo. Veja [Atributos de `vehicle_identification`](#atributos-de-vehicle_identification). |

```json title="Exemplo de garantia de veículo"
{
  "collateral_type": "vehicle",
  "vehicle_loan_value": 30000.00,
  "vehicle_total_market_value": 55000.00,
  "vehicle_identification": {
    "brand": "Toyota",
    "model": "Corolla XEi 2.0",
    "manufacturing_year": 2022,
    "chassis_number": "9BRBLWHEXK0123456",
    "license_plate": "ABC1D23",
    "renavam": "12345678901"
  }
}
```

#### Atributos de `vehicle_identification`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `brand` | string | opcional | Marca do veículo. |
| `model` | string | obrigatório | Modelo do veículo. |
| `manufacturing_year` | integer | obrigatório | Ano de fabricação do veículo. Mínimo 1900. |
| `chassis_number` | string | obrigatório | Número do chassi do veículo. |
| `license_plate` | string | opcional | Placa do veículo. |
| `renavam` | string | opcional | Código RENAVAM do veículo. |

## Response

STATUS 201

```json title="Response Body"
{
    "asset_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "external_id": "ccf6f331-d55f-46c0-a32f-fb909884dbb2",
    "status": "pending_eligibility"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `asset_key` | string | Identificador único do ativo gerado pela QI Tech (UUID). |
| `external_id` | string | A mesma chave externa fornecida no campo `external_id` da `credit_operation`. |
| `status` | string | Status inicial do ativo. Sempre retorna `pending_eligibility`, indicando que o ativo foi inserido e aguarda análise de elegibilidade. |

## Possíveis erros

STATUS 404

**Lote não encontrado**

O `assignment_external_id` informado na URL não corresponde a nenhum lote existente nesta configuração de cessão. Verifique se o identificador está correto.

```json
{
  "title": "Assignment not found",
  "description": "Assignment not found",
  "translation": "Lote não encontrado",
  "code": "TRC000018"
}
```

STATUS 404

**Tipo de ativo não existe**

O valor informado no campo `asset_type` não é um tipo válido. Verifique se o tipo está correto (ex: `ccb`, `duplicata_mercantil`, `discounted_contract`).

```json
{
  "title": "Asset type does not exist",
  "description": "Asset type 'invalid_asset_type' does not exist",
  "translation": "Tipo do ativo 'invalid_asset_type' nao existe",
  "code": "TRC000015"
}
```

STATUS 400

**Tipo de ativo incompatível com o lote**

O lote foi configurado para receber um tipo de ativo diferente do informado. Cada configuração de cessão aceita apenas um tipo de ativo específico. Verifique a configuração de cessão utilizada.

```json
{
  "title": "Invalid asset type configuration",
  "description": "This assignment can not receive this asset type: ccb",
  "translation": "Esse lote não pode receber esse tipo de ativo: ccb",
  "code": "TRC000025"
}
```

STATUS 400

**Lote fechado para inserção**

O lote já foi encerrado para inserção de novos ativos. Após o encerramento, não é possível adicionar mais ativos. Caso precise, [reabra o lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos) antes de inserir novos ativos.

```json
{
  "title": "Assignment is closed",
  "description": "Assignment is closed to insert new assets",
  "translation": "Lote esta fechado para inserir novos ativos",
  "code": "TRC000022"
}
```

STATUS 400

**Número de documento inválido**

Um dos números de documento informados (CPF ou CNPJ) é inválido. Verifique os campos `document_number`, `originator_document_number` e demais campos de documento no request body.

```json
{
  "title": "Invalid Document number",
  "description": "Given '000.000.000-00' document number is invalid.",
  "translation": "O numero de document '000.000.000-00' fornecido não é valido.",
  "code": "TRC000009"
}
```

STATUS 400

**External ID duplicado**

Já existe um ativo cadastrado com o `external_id` informado. Cada ativo deve ter um identificador único. Gere um novo `external_id` e tente novamente.

```json
{
  "title": "Already Exist This External Id",
  "description": "Already exist an asset with this External Id",
  "translation": "Ja existe um ativo com esse External Id",
  "code": "TRC000054"
}
```

## Próximos passos

Após inserir o ativo, o fluxo continua com:

1. **[Envio dos documentos](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie a documentação exigida para cada ativo aprovado na elegibilidade.
2. **[Encerramento da inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)** — sinalize que todos os ativos foram inseridos para que o lote siga para a análise de elegibilidade.

---

# Criação de Ativo — Contrato Parcelado

URL: /documentation/iaas/negociacao_recebiveis/asset/criacao_contract

Endpoint para inserir um ativo do tipo **Contrato Parcelado** em um lote de cessão. Cada ativo representa um contrato com um fluxo de parcelas — o contrato inteiro é cedido ao fundo em uma única requisição, com todas as suas parcelas.

:::tip Onde estou no fluxo?
Este é o **2º passo** do fluxo de cessão. Antes, você deve ter [criado o lote](/documentation/iaas/negociacao_recebiveis/assignment/criacao). Após inserir os ativos, envie os [documentos](/documentation/iaas/negociacao_recebiveis/asset/documents) exigidos e [encerre a inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento).
:::

:::info Um ativo, várias parcelas
Diferente do [Contrato Descontado](/documentation/iaas/negociacao_recebiveis/asset/criacao_discounted_contract) — em que cada parcela é um ativo independente — no contrato parcelado **o ativo é o contrato**, e as parcelas são o fluxo de pagamentos dele. O array `installments` precisa conter todas as parcelas do contrato que estão sendo cedidas.
:::

:::caution Atenção
O campo `external_id` do contrato deve ser único para cada ativo e não deve ser confundido com o `external_id` do lote.
:::

## Request

ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/asset
MÉTODO POST

```json title="Request Body"
{
    "asset_type": "contract",
    "total_purchase_value": 900.00,
    "contract": {
        "external_id": "80187a08-ea7d-44b2-b65c-131f1318e904",
        "originator_document_number": "53.020.654/0001-43",
        "contract_number": "1144927986/XXX",
        "issue_date": "2026-11-01",
        "interest_rate_type": "pre_fixed",
        "calendar_base": "calendar_365",
        "pre_fixed": {
            "calendar_base": "calendar_365",
            "monthly_rate": 0.015
        },
        "borrower": {
            "name": "Jove de Souza",
            "document_number": "593.607.530-33",
            "person_type": "natural_person",
            "email": "jose.souza@yopmail.com",
            "address": {
                "street": "Rua Gilberto Sabino",
                "number": "215",
                "neighborhood": "Pinheiros",
                "city": "São Paulo",
                "postal_code": "05245-020",
                "uf": "SP",
                "country": "BRA"
            },
            "phone": {
                "area_code": "11",
                "number": "26260447"
            },
            "natural_person": {
                "birthdate": "1999-01-01",
                "gender": "male",
                "mother_name": "Maria de Souza"
            }
        },
        "installments": [
            {
                "installment_number": 1,
                "maturity_date": "2026-12-25",
                "face_value": 500.46,
                "principal_value": 450.00,
                "external_id": "parcela-1"
            },
            {
                "installment_number": 2,
                "maturity_date": "2027-01-25",
                "face_value": 500.46,
                "principal_value": 450.00,
                "external_id": "parcela-2"
            }
        ],
        "contract_data": {
            "cost_center": "SP-01"
        }
    }
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `asset_type` | string | obrigatório | Tipo do ativo. Para contrato parcelado, informar `contract`. |
| `total_purchase_value` | number | obrigatório | Valor total da compra do ativo — efetivamente quanto o cessionário vai pagar pelo contrato inteiro. Até 2 casas decimais. |
| `contract` | object | obrigatório | Dados do contrato. Veja [Atributos de `contract`](#atributos-de-contract). |

:::caution Ágios e deduções não se aplicam
Os campos `premiums` e `deductions` **não são utilizados** em cessão de contrato parcelado. O valor de aquisição do ativo é sempre o `total_purchase_value` informado.
:::

#### Atributos de `contract`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `external_id` | string | obrigatório | Chave única de identificação deste ativo no sistema do parceiro. Máximo de 50 caracteres. |
| `originator_document_number` | string | obrigatório | CPF ou CNPJ formatado do originador/consultor que viabilizou a operação. Precisa estar cadastrado e vinculado à configuração de cessão. |
| `contract_number` | string | obrigatório | Número do contrato. Máximo de 50 caracteres. Enviado exatamente como informado, sem normalização. |
| `borrower` | object | obrigatório | Dados do sacado/devedor do contrato. Veja [Atributos de `borrower`](#atributos-de-borrower). |
| `interest_rate_type` | string | obrigatório | Tipo de juros do contrato. |
| `installments` | array | obrigatório | Lista das parcelas do contrato. Precisa ter ao menos uma parcela. Veja [Atributos de `installments`](#atributos-de-installments). |
| `issue_date` | string | opcional | Data de emissão do contrato no formato `YYYY-MM-DD`. |
| `calendar_base` | string | opcional | Base de contagem de dias do contrato. Quando omitido, é assumido `workdays`. |
| `pre_fixed` | object | condicional | Dados da parte pré-fixada. Obrigatório quando `interest_rate_type` for `pre_fixed`. Veja [Atributos de `pre_fixed`](#atributos-de-pre_fixed). |
| `post_fixed` | object | condicional | Dados da parte pós-fixada. Obrigatório quando `interest_rate_type` for `post_fixed`. Veja [Atributos de `post_fixed`](#atributos-de-post_fixed). |
| `contract_data` | object | opcional | Objeto livre para informações adicionais do contrato. É armazenado e devolvido nas consultas e webhooks, sem interferir nos cálculos. |

**Enumeradores de `interest_rate_type`:**

| Valor | Descrição |
|---|---|
| `pre_fixed` | Para contratos pré-fixados. Informe o objeto `pre_fixed`. |
| `post_fixed` | Para contratos pós-fixados. Informe o objeto `post_fixed`. |

**Enumeradores de `calendar_base`:**

| Valor | Descrição |
|---|---|
| `workdays` | Base de cálculo em dias úteis (252). |
| `calendar_365` | Base de cálculo em 365 dias. |
| `calendar_360` | Base de cálculo em 360 dias. |

#### Atributos de `installments`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `installment_number` | integer | obrigatório | Número da parcela, começando em 1. Veja a regra de sequência abaixo. |
| `maturity_date` | string | obrigatório | Data de vencimento da parcela no formato `YYYY-MM-DD`. |
| `face_value` | number | obrigatório | Valor de face da parcela — quanto o sacado paga no vencimento. Maior que zero e até 8 casas decimais. |
| `principal_value` | number | opcional | Principal esperado a ser amortizado na data de vencimento. Até 8 casas decimais. |
| `external_id` | string | opcional | Chave de identificação da parcela no sistema do parceiro. Máximo de 50 caracteres. |

:::caution Sequência das parcelas
Ordenando as parcelas pela `maturity_date`, os `installment_number` precisam formar a sequência `1, 2, 3, …` sem repetições e sem saltos. Uma numeração fora de ordem devolve o erro `TRC000174`.
:::

#### Atributos de `pre_fixed`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `calendar_base` | string | obrigatório | Base de contagem de dias utilizada na taxa. Mesmos enumeradores de [`calendar_base`](#atributos-de-contract). |
| `monthly_rate` | number | obrigatório | Taxa mensal do contrato, em fração decimal entre 0 e 1. Para 1,5% ao mês, informar `0.015`. Até 8 casas decimais. |

#### Atributos de `post_fixed`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `calendar_base` | string | obrigatório | Base de contagem de dias da correção. Mesmos enumeradores de [`calendar_base`](#atributos-de-contract). |
| `indexer` | string | obrigatório | Índice que corrige o contrato. |
| `rate` | number | obrigatório | Taxa aplicada sobre o indexador. Para 100% do DI, informar `1`. |
| `lag` | object | obrigatório | Defasagem entre a data do índice e a data da correção. Veja [Atributos de `lag`](#atributos-de-lag). |

**Enumeradores de `indexer`:**

| Valor | Descrição |
|---|---|
| `di` | Taxa DI, apurada pela B3. |
| `selic` | Taxa Selic. |
| `ipca` | IPCA. |

#### Atributos de `lag`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `reference` | string | obrigatório | Unidade da defasagem: `daily` (dias) ou `monthly` (meses). |
| `amount` | number | obrigatório | Quantidade de defasagem. Para usar o índice de dois meses antes, informar `2` com `reference` igual a `monthly`. |

#### Atributos de `borrower`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `name` | string | obrigatório | Nome do sacado. Máximo de 255 caracteres. |
| `document_number` | string | obrigatório | CPF ou CNPJ formatado do sacado. |
| `person_type` | string | obrigatório | Tipo de pessoa. |
| `email` | string | opcional | E-mail do sacado. Máximo de 255 caracteres. |
| `address` | object | opcional | Endereço do sacado. Veja [Atributos de `address`](#atributos-de-address). |
| `phone` | object | opcional | Telefone do sacado. Veja [Atributos de `phone`](#atributos-de-phone). |

**Enumeradores de `person_type`:**

| Valor | Descrição |
|---|---|
| `natural_person` | Pessoa Física. Quando informado, inclua o objeto `natural_person` dentro de `borrower`. Veja [Atributos de `natural_person`](#atributos-de-natural_person). |
| `legal_person` | Pessoa Jurídica. Quando informado, inclua o objeto `legal_person` dentro de `borrower`. Veja [Atributos de `legal_person`](#atributos-de-legal_person). |

#### Atributos de `address`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `postal_code` | string | obrigatório | CEP. 9 caracteres, no formato `00000-000`. Obrigatório sempre que o objeto `address` for informado. |
| `street` | string | opcional | Logradouro. Caso não tenha todas as informações, enviar o compilado neste campo. Máximo de 255 caracteres. |
| `number` | string | opcional | Número do endereço. Máximo de 40 caracteres. |
| `neighborhood` | string | opcional | Bairro. Máximo de 255 caracteres. |
| `city` | string | opcional | Cidade. Máximo de 255 caracteres. |
| `uf` | string | opcional | Sigla do estado. 2 caracteres. |
| `complement` | string | opcional | Complemento. Máximo de 255 caracteres. |
| `country` | string | opcional | País no formato ISO 3166-1 alpha-3. 3 caracteres. |

#### Atributos de `phone`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `area_code` | string | obrigatório | Código de área (DDD). 2 dígitos. |
| `number` | string | obrigatório | Número de telefone. 8 ou 9 dígitos. |

#### Atributos de `natural_person`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `birthdate` | string | opcional | Data de nascimento no formato `YYYY-MM-DD`. |
| `gender` | string | opcional | Gênero: `male` ou `female`. |
| `mother_name` | string | opcional | Nome da mãe. Máximo de 255 caracteres. |

#### Atributos de `legal_person`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `foundation_date` | string | opcional | Data de fundação no formato `YYYY-MM-DD`. |
| `activity_code` | string | opcional | Código de atividade (CNAE) no formato `11.11-1-11`. |
| `annual_revenues` | integer | opcional | Receita anual em centavos. |
| `representatives` | array | opcional | Lista de representantes legais. |

## Response

STATUS 201

```json title="Response Body"
{
    "asset_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "external_id": "80187a08-ea7d-44b2-b65c-131f1318e904",
    "status": "pending_eligibility"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `asset_key` | string | Identificador único do ativo gerado pela QI Tech (UUID). |
| `external_id` | string | A mesma chave externa fornecida no campo `external_id` do `contract`. |
| `status` | string | Status inicial do ativo. Sempre retorna `pending_eligibility`, indicando que o ativo foi inserido e aguarda análise de elegibilidade. |

:::info Valores calculados pela QI Tech
Na inserção do ativo, a QI Tech calcula e passa a devolver nas consultas e nos webhooks a taxa interna de retorno da compra (`purchase_irr`), a duration do contrato e o `purchase_value` de cada parcela — a fatia do `total_purchase_value` alocada a cada vencimento. Esses campos não devem ser enviados no request.
:::

## Possíveis erros

STATUS 400

**Parcelas fora de sequência**

Ordenando as parcelas pela data de vencimento, os `installment_number` não formam a sequência `1, 2, 3, …`. Verifique se há número repetido, salto na numeração ou parcela com vencimento fora da ordem.

```json
{
  "title": "Contract must have an installment number sequence",
  "description": "Contract 80187a08-ea7d-44b2-b65c-131f1318e904 must have installment numbers as a sequence starting at 1 ordered by maturity date",
  "translation": "O contrato 80187a08-ea7d-44b2-b65c-131f1318e904 deve ter os numeros das parcelas em sequencia iniciando em 1 e ordenados pela data de vencimento",
  "code": "TRC000174"
}
```

STATUS 400

**Tipo de ativo incompatível com o lote**

O lote foi configurado para receber um tipo de ativo diferente do informado. Cada configuração de cessão aceita apenas um tipo de ativo específico. Verifique a configuração de cessão utilizada.

```json
{
  "title": "Invalid asset type configuration",
  "description": "This assignment can not receive this asset type: contract",
  "translation": "Esse lote não pode receber esse tipo de ativo: contract",
  "code": "TRC000025"
}
```

STATUS 400

**Payload incompatível com o tipo de ativo**

O objeto `contract` só é aceito para o tipo de ativo `contract`. Outros tipos de contrato — como `financing_contract` e `debt_acknowledgment` — não são cedidos por este fluxo.

```json
{
  "title": "Invalid assignment date.",
  "description": "The provided asset_type does not match the specific information passed.",
  "translation": "o asset_type fornecido não coincide com as informações especificas passadas",
  "code": "TRC000084"
}
```

STATUS 404

**Lote não encontrado**

O `assignment_external_id` informado na URL não corresponde a nenhum lote existente nesta configuração de cessão. Verifique se o identificador está correto.

```json
{
  "title": "Assignment not found",
  "description": "Assignment not found",
  "translation": "Lote não encontrado",
  "code": "TRC000018"
}
```

STATUS 400

**Lote fechado para inserção**

O lote já foi encerrado para inserção de novos ativos. Após o encerramento, não é possível adicionar mais ativos. Caso precise, [reabra o lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos) antes de inserir novos ativos.

```json
{
  "title": "Assignment is closed",
  "description": "Assignment is closed to insert new assets",
  "translation": "Lote esta fechado para inserir novos ativos",
  "code": "TRC000022"
}
```

STATUS 400

**Número de documento inválido**

Um dos números de documento informados (CPF ou CNPJ) é inválido. Verifique os campos `originator_document_number` e `borrower.document_number`.

```json
{
  "title": "Invalid Document number",
  "description": "Given '000.000.000-00' document number is invalid.",
  "translation": "O numero de document '000.000.000-00' fornecido não é valido.",
  "code": "TRC000009"
}
```

STATUS 400

**External ID duplicado**

Já existe um ativo cadastrado com o `external_id` informado. Cada ativo deve ter um identificador único. Gere um novo `external_id` e tente novamente.

```json
{
  "title": "Already Exist This External Id",
  "description": "Already exist an asset with this External Id",
  "translation": "Ja existe um ativo com esse External Id",
  "code": "TRC000054"
}
```

## Próximos passos

Após inserir o ativo, o fluxo continua com:

1. **[Envio dos documentos](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie o contrato assinado, com `document_type` igual a `contract`.
2. **[Encerramento da inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)** — sinalize que todos os ativos foram inseridos para que o lote siga para a análise de elegibilidade.

Para ceder contratos parcelados em volume, sem uma requisição por ativo, use a [Cessão por Arquivo](/documentation/iaas/negociacao_recebiveis/arquivo/csv_contrato_parcelado).

---

# Criação de Ativo — CTE

URL: /documentation/iaas/negociacao_recebiveis/asset/criacao_cte

Endpoint para inserir um ativo do tipo **CTE** (Conhecimento de Transporte Eletrônico) em um lote de cessão. O CTE é um documento fiscal eletrônico que comprova a prestação de serviço de transporte, utilizado como direito creditório na operação de cessão.

:::tip Onde estou no fluxo?
Este é o **2º passo** do fluxo de cessão. Antes, você deve ter [criado o lote](/documentation/iaas/negociacao_recebiveis/assignment/criacao). Após inserir os ativos, envie os [documentos](/documentation/iaas/negociacao_recebiveis/asset/documents) exigidos e [encerre a inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento).
:::

:::caution Atenção
O campo `external_id` do direito creditório deve ser único para cada ativo e não deve ser confundido com o `external_id` do lote.
:::

## Request

ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/asset
MÉTODO POST

```json title="Request Body"
{
    "asset_type": "cte",
    "total_purchase_value": 1231.21,
    "discounted_credit_right": {
        "external_id": "ccf6f331-d55f-46c0-a32f-fb909884dbb2",
        "originator_document_number": "46.282.154/0001-14",
        "maturity_date": "2023-12-10",
        "order_number": "18923619954796912",
        "face_value": 1023.01,
        "person_type": "legal_person",
        "borrower": {
            "name": "Transportadora Exemplo Ltda",
            "document_number": "46.282.154/0001-14",
            "person_type": "legal_person",
            "email": "contato@transportadora.com.br",
            "address": {
                "street": "Avenida Paulista",
                "number": "1000",
                "neighborhood": "Bela Vista",
                "city": "São Paulo",
                "postal_code": "01310-100",
                "uf": "SP",
                "country": "BRA"
            },
            "phone": {
                "area_code": "11",
                "number": "936360268"
            },
            "legal_person": {
                "activity_code": "49.30-2-01"
            }
        },
        "participant_control_number": "ICX841HWCPUGU4U101XPLDW8D",
        "bankslip": {
            "our_number": {
                "number": 2,
                "digit": "P"
            }
        },
        "delay": {
            "fine": {
                "fine_type": "percentage",
                "percentage_value": 0.0
            },
            "interest": {
                "method": "pre_fixed",
                "pre_fixed": {
                    "daily_rate": 0.0,
                    "calendar_base": "calendar_360"
                }
            }
        },
        "invoice": {
            "access_key": "35231146282154000114570000000001189236199547",
            "total_value": 1231.21,
            "serie": "001",
            "number": "958431587",
            "issue_date": "2023-10-10"
        }
    }
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `asset_type` | string | obrigatório | Tipo do ativo. Para CTE, informar `cte`. |
| `total_purchase_value` | number | obrigatório | Valor total da compra do ativo — efetivamente quanto o cessionário vai pagar. Até 2 casas decimais. |
| `discounted_credit_right` | object | obrigatório | Dados do direito creditório. Veja [Atributos de `discounted_credit_right`](#atributos-de-discounted_credit_right). |

#### Atributos de `discounted_credit_right`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `external_id` | string | obrigatório | Chave única de identificação deste ativo no sistema do parceiro. Máximo de 50 caracteres. |
| `originator_document_number` | string | obrigatório | CPF ou CNPJ formatado do originador/consultor que viabilizou a operação. |
| `maturity_date` | string | obrigatório | Data de vencimento no formato `YYYY-MM-DD`. |
| `order_number` | string | obrigatório | Número do pedido. Máximo de 45 caracteres. |
| `face_value` | number | obrigatório | Valor de face. Até 8 casas decimais. |
| `person_type` | string | opcional | Tipo de pessoa do sacado (`natural_person` ou `legal_person`). |
| `borrower` | object | obrigatório | Dados do sacado. Consulte os [Atributos de `borrower`](#atributos-de-borrower). |
| `invoice` | object | obrigatório | Dados do CT-e. Veja [Atributos de `invoice`](#atributos-de-invoice). |
| `participant_control_number` | string | opcional | Número de controle do participante no sistema do parceiro. Máximo de 25 caracteres alfanuméricos. |
| `bankslip` | object | opcional | Dados do boleto. Veja [Atributos de `bankslip`](#atributos-de-bankslip). |
| `delay` | object | opcional | Dados de multa e juros por atraso. Veja [Atributos de `delay`](#atributos-de-delay). |

#### Atributos de `invoice`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `access_key` | string | obrigatório | Chave de acesso do CT-e. 44 caracteres. Os caracteres de posição 20 a 22 devem corresponder ao modelo do documento (`57` ou `67`). |
| `total_value` | number | opcional | Valor total do CT-e. Até 2 casas decimais. |
| `serie` | string | obrigatório | Número de série do CT-e. Máximo de 3 caracteres. |
| `number` | string | obrigatório | Número do CT-e. Máximo de 9 caracteres. |
| `issue_date` | string | obrigatório | Data de emissão no formato `YYYY-MM-DD`. |

#### Atributos de `borrower`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `name` | string | obrigatório | Nome do sacado. Máximo de 255 caracteres. |
| `document_number` | string | obrigatório | CPF ou CNPJ do sacado. |
| `person_type` | string | obrigatório | Tipo de pessoa. |
| `email` | string | opcional | E-mail do sacado. Máximo de 255 caracteres. |
| `address` | object | obrigatório | Endereço do sacado. Veja [Atributos de `address`](#atributos-de-address). |
| `phone` | object | opcional | Telefone do sacado. Veja [Atributos de `phone`](#atributos-de-phone). |

**Enumeradores de `person_type`:**

| Valor | Descrição |
|---|---|
| `natural_person` | Pessoa Física. Quando informado, incluir o objeto `natural_person` dentro de `borrower`. Veja [Atributos de `natural_person`](#atributos-de-natural_person). |
| `legal_person` | Pessoa Jurídica. Quando informado, incluir o objeto `legal_person` dentro de `borrower`. Veja [Atributos de `legal_person`](#atributos-de-legal_person). |

#### Atributos de `address`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `street` | string | obrigatório | Logradouro. Caso não tenha todas as informações, enviar o compilado neste campo. Máximo de 255 caracteres. |
| `number` | string | opcional | Número do endereço. Máximo de 40 caracteres. |
| `neighborhood` | string | opcional | Bairro. Máximo de 255 caracteres. |
| `city` | string | opcional | Cidade. Máximo de 255 caracteres. |
| `uf` | string | opcional | Sigla do estado. 2 caracteres. |
| `complement` | string | opcional | Complemento. Máximo de 255 caracteres. |
| `postal_code` | string | obrigatório | CEP. 9 caracteres (com hífen). |
| `country` | string | opcional | País no formato ISO 3166-1 alpha-3. 3 caracteres. |

#### Atributos de `phone`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `area_code` | string | obrigatório | Código de área (DDD). 2 dígitos. |
| `number` | string | obrigatório | Número de telefone. Até 9 dígitos. |

#### Atributos de `natural_person`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `birthdate` | string | opcional | Data de nascimento no formato `YYYY-MM-DD`. |
| `gender` | string | opcional | Gênero. |
| `mother_name` | string | opcional | Nome da mãe. Máximo de 255 caracteres. |

**Enumeradores de `gender`:**

| Valor | Descrição |
|---|---|
| `male` | Masculino. |
| `female` | Feminino. |

#### Atributos de `legal_person`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `foundation_date` | string | opcional | Data de fundação no formato `YYYY-MM-DD`. |
| `activity_code` | string | obrigatório | Código de atividade no formato `11.11-1-11`. |
| `annual_revenues` | integer | opcional | Receita anual em centavos. |
| `representatives` | array | opcional | Lista de representantes legais. Veja [Atributos de `representatives`](#atributos-de-representatives). |

#### Atributos de `representatives`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `name` | string | obrigatório | Nome do representante. Máximo de 255 caracteres. |
| `document_number` | string | obrigatório | CPF ou CNPJ do representante. |
| `email` | string | opcional | E-mail do representante. Máximo de 255 caracteres. |
| `phone` | object | opcional | Telefone. Mesma estrutura de [Atributos de `phone`](#atributos-de-phone). |
| `address` | object | opcional | Endereço. Mesma estrutura de [Atributos de `address`](#atributos-de-address). |
| `person_type` | string | obrigatório | Tipo de pessoa (`natural_person` ou `legal_person`). |
| `representative_type` | string | opcional | Tipo do representante. Máximo de 50 caracteres. |

#### Atributos de `bankslip`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `our_number` | object | opcional | Dados do nosso número. Aplicável apenas quando o nosso número é emitido pelo cliente. Veja [Atributos de `our_number`](#atributos-de-our_number). |

#### Atributos de `our_number`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `number` | number | obrigatório | Nosso número. Número bancário para cobrança com registro. 1 a 11 caracteres numéricos. |
| `digit` | string | obrigatório | Dígito verificador de auto conferência do nosso número. 1 caractere alfanumérico. |

#### Atributos de `delay`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `fine` | object | opcional | Dados da multa por atraso. Veja [Atributos de `fine`](#atributos-de-fine). |
| `interest` | object | opcional | Dados do juros de mora. Veja [Atributos de `interest`](#atributos-de-interest). |

#### Atributos de `fine`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `fine_type` | string | obrigatório | Tipo da multa. |
| `percentage_value` | number | condicional | Valor da multa quando `fine_type` for `percentage`. De 0 a 1, representando 0% a 100%. Até 2 casas decimais. |
| `amount` | number | condicional | Valor fixo da multa quando `fine_type` for `fixed`. Até 2 casas decimais. |

**Enumeradores de `fine_type`:**

| Valor | Descrição |
|---|---|
| `percentage` | Multa percentual sobre o valor da parcela. |
| `fixed` | Valor fixo de multa. |

#### Atributos de `interest`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `method` | string | obrigatório | Método do juros de mora. |
| `pre_fixed` | object | obrigatório | Dados da taxa pré-fixada. Veja [Atributos de `pre_fixed`](#atributos-de-pre_fixed). |

**Enumeradores de `method`:**

| Valor | Descrição |
|---|---|
| `compound` | Juros de mora composto. |
| `simple` | Juros de mora simples. |
| `pre_fixed` | Juros de mora pré-fixado. |

#### Atributos de `pre_fixed`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `daily_rate` | number | condicional | Taxa diária. Informar quando `method` for `pre_fixed`. Para 1%, informar `0.01`. Até 8 casas decimais. |
| `calendar_base` | string | obrigatório | Base de cálculo utilizada. |

**Enumeradores de `calendar_base`:**

| Valor | Descrição |
|---|---|
| `workdays` | Base de cálculo em dias úteis (252). |
| `calendar_365` | Base de cálculo em 365 dias. |
| `calendar_360` | Base de cálculo em 360 dias. |

## Response

STATUS 201

```json title="Response Body"
{
    "asset_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "external_id": "ccf6f331-d55f-46c0-a32f-fb909884dbb2",
    "status": "pending_eligibility"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `asset_key` | string | Identificador único do ativo gerado pela QI Tech (UUID). |
| `external_id` | string | A mesma chave externa fornecida no campo `external_id` do `discounted_credit_right`. |
| `status` | string | Status inicial do ativo. Sempre retorna `pending_eligibility`, indicando que o ativo foi inserido e aguarda análise de elegibilidade. |

## Possíveis erros

STATUS 404

**Lote não encontrado**

O `assignment_external_id` informado na URL não corresponde a nenhum lote existente nesta configuração de cessão. Verifique se o identificador está correto.

```json
{
  "title": "Assignment not found",
  "description": "Assignment not found",
  "translation": "Lote não encontrado",
  "code": "TRC000018"
}
```

STATUS 404

**Tipo de ativo não existe**

O valor informado no campo `asset_type` não é um tipo válido. Verifique se o tipo está correto (ex: `cte`).

```json
{
  "title": "Asset type does not exist",
  "description": "Asset type 'invalid_asset_type' does not exist",
  "translation": "Tipo do ativo 'invalid_asset_type' nao existe",
  "code": "TRC000015"
}
```

STATUS 400

**Tipo de ativo incompatível com o lote**

O lote foi configurado para receber um tipo de ativo diferente do informado. Cada configuração de cessão aceita apenas um tipo de ativo específico. Verifique a configuração de cessão utilizada.

```json
{
  "title": "Invalid asset type configuration",
  "description": "This assignment can not receive this asset type: cte",
  "translation": "Esse lote não pode receber esse tipo de ativo: cte",
  "code": "TRC000025"
}
```

STATUS 400

**Lote fechado para inserção**

O lote já foi encerrado para inserção de novos ativos. Após o encerramento, não é possível adicionar mais ativos. Caso precise, [reabra o lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos) antes de inserir novos ativos.

```json
{
  "title": "Assignment is closed",
  "description": "Assignment is closed to insert new assets",
  "translation": "Lote esta fechado para inserir novos ativos",
  "code": "TRC000022"
}
```

STATUS 400

**Chave de acesso do CT-e ausente**

O campo `access_key` dentro de `invoice` é obrigatório para ativos do tipo `cte`. Inclua a chave de acesso do CT-e no request body.

```json
{
  "title": "Access Key Required",
  "description": "Access key is required for cte asset type",
  "translation": "Chave de acesso é obrigatória para o tipo de ativo cte",
  "code": "TRC000134"
}
```

STATUS 400

**Chave de acesso do CT-e inválida**

A `access_key` informada não corresponde a um CT-e válido. Os caracteres de posição 20 a 22 da chave de acesso devem ser `57` ou `67`, que identificam o modelo do documento fiscal CT-e.

```json
{
  "title": "Invalid CTE Access Key",
  "description": "Access key is not valid for a CTE document",
  "translation": "Chave de acesso não é válida para um documento CT-e",
  "code": "TRC000133"
}
```

STATUS 400

**External ID duplicado**

Já existe um ativo cadastrado com o `external_id` informado. Cada ativo deve ter um identificador único. Gere um novo `external_id` e tente novamente.

```json
{
  "title": "Already Exist This External Id",
  "description": "Already exist an asset with this External Id",
  "translation": "Ja existe um ativo com esse External Id",
  "code": "TRC000054"
}
```

## Próximos passos

Após inserir o ativo, o fluxo continua com:

1. **[Envio dos documentos](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie a documentação exigida para cada ativo aprovado na elegibilidade.
2. **[Encerramento da inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)** — sinalize que todos os ativos foram inseridos para que o lote siga para a análise de elegibilidade.

---

# Criação de Ativo — Contrato Descontado

URL: /documentation/iaas/negociacao_recebiveis/asset/criacao_discounted_contract

Endpoint para inserir um ativo do tipo **Contrato Descontado** em um lote de cessão. Este tipo de ativo representa uma parcela de um contrato de crédito cujo direito creditório será cedido ao fundo.

:::tip Onde estou no fluxo?
Este é o **2º passo** do fluxo de cessão. Antes, você deve ter [criado o lote](/documentation/iaas/negociacao_recebiveis/assignment/criacao). Após inserir os ativos, envie os [documentos](/documentation/iaas/negociacao_recebiveis/asset/documents) exigidos e [encerre a inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento).
:::

:::caution Atenção
O campo `external_id` do direito creditório deve ser único para cada ativo e não deve ser confundido com o `external_id` do lote.
:::

## Request

ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/asset
MÉTODO POST

```json title="Request Body"
{
    "asset_type": "discounted_contract",
    "total_purchase_value": 1231.21,
    "discounted_credit_right": {
        "external_id": "mdf27za1-ra5f-46c0-a32f-fb909884dbb2",
        "originator_document_number": "46.282.154/0001-14",
        "face_value": 1231.21,
        "maturity_date": "2025-12-10",
        "installment_number": 1,
        "borrower": {
            "name": "Natália Nascimento",
            "document_number": "19.845.976/0001-93",
            "person_type": "natural_person",
            "email": "natália.nascimento@yopmail.com",
            "address": {
                "street": "Gilberto Sabino",
                "number": "215",
                "neighborhood": "Pinheiros",
                "city": "São Paulo",
                "postal_code": "05425-020",
                "uf": "SP",
                "country": "BRA"
            },
            "phone": {
                "area_code": "11",
                "number": "36360268"
            },
            "natural_person": {
                "mother_name": "Lívia Santos",
                "birthdate": "2001-01-05"
            }
        },
        "contract": {
            "number_of_installments": 5,
            "total_face_value": 1231.21,
            "number": "958431587",
            "issue_date": "2023-10-10"
        }
    }
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `asset_type` | string | obrigatório | Tipo do ativo. Para contrato descontado, informar `discounted_contract`. |
| `total_purchase_value` | number | obrigatório | Valor total da compra do ativo — efetivamente quanto o cessionário vai pagar. Até 2 casas decimais. |
| `discounted_credit_right` | object | obrigatório | Dados do direito creditório. Veja [Atributos de `discounted_credit_right`](#atributos-de-discounted_credit_right). |

#### Atributos de `discounted_credit_right`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `external_id` | string | obrigatório | Chave única de identificação deste ativo no sistema do parceiro. Máximo de 50 caracteres. |
| `originator_document_number` | string | obrigatório | CPF ou CNPJ formatado do originador/consultor que viabilizou a operação. |
| `face_value` | number | obrigatório | Valor de face. Até 8 casas decimais. |
| `maturity_date` | string | obrigatório | Data de vencimento da parcela no formato `YYYY-MM-DD`. |
| `installment_number` | integer | opcional | Número da parcela. |
| `borrower` | object | obrigatório | Dados do sacado. Consulte os [Atributos de `borrower`](/documentation/iaas/negociacao_recebiveis/asset/criacao_co#atributos-de-borrower) na página de Criação de Ativo — CCB. |
| `contract` | object | obrigatório | Dados do contrato. Veja [Atributos de `contract`](#atributos-de-contract). |

#### Atributos de `contract`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `number_of_installments` | integer | obrigatório | Número total de parcelas do contrato. |
| `total_face_value` | number | obrigatório | Valor de face total do contrato. Até 2 casas decimais. |
| `number` | string | obrigatório | Número do contrato. Máximo de 50 caracteres. |
| `issue_date` | string | obrigatório | Data de emissão no formato `YYYY-MM-DD`. |

## Response

STATUS 201

```json title="Response Body"
{
    "asset_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "external_id": "mdf27za1-ra5f-46c0-a32f-fb909884dbb2",
    "status": "pending_eligibility"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `asset_key` | string | Identificador único do ativo gerado pela QI Tech (UUID). |
| `external_id` | string | A mesma chave externa fornecida no campo `external_id` do `discounted_credit_right`. |
| `status` | string | Status inicial do ativo. Sempre retorna `pending_eligibility`, indicando que o ativo foi inserido e aguarda análise de elegibilidade. |

## Possíveis erros

STATUS 404

**Lote não encontrado**

O `assignment_external_id` informado na URL não corresponde a nenhum lote existente nesta configuração de cessão. Verifique se o identificador está correto.

```json
{
  "title": "Assignment not found",
  "description": "Assignment not found",
  "translation": "Lote não encontrado",
  "code": "TRC000018"
}
```

STATUS 404

**Tipo de ativo não existe**

O valor informado no campo `asset_type` não é um tipo válido. Verifique se o tipo está correto (ex: `discounted_contract`).

```json
{
  "title": "Asset type does not exist",
  "description": "Asset type 'invalid_asset_type' does not exist",
  "translation": "Tipo do ativo 'invalid_asset_type' nao existe",
  "code": "TRC000015"
}
```

STATUS 400

**Tipo de ativo incompatível com o lote**

O lote foi configurado para receber um tipo de ativo diferente do informado. Cada configuração de cessão aceita apenas um tipo de ativo específico. Verifique a configuração de cessão utilizada.

```json
{
  "title": "Invalid asset type configuration",
  "description": "This assignment can not receive this asset type: discounted_contract",
  "translation": "Esse lote não pode receber esse tipo de ativo: discounted_contract",
  "code": "TRC000025"
}
```

STATUS 400

**Lote fechado para inserção**

O lote já foi encerrado para inserção de novos ativos. Após o encerramento, não é possível adicionar mais ativos. Caso precise, [reabra o lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos) antes de inserir novos ativos.

```json
{
  "title": "Assignment is closed",
  "description": "Assignment is closed to insert new assets",
  "translation": "Lote esta fechado para inserir novos ativos",
  "code": "TRC000022"
}
```

STATUS 400

**External ID duplicado**

Já existe um ativo cadastrado com o `external_id` informado. Cada ativo deve ter um identificador único. Gere um novo `external_id` e tente novamente.

```json
{
  "title": "Already Exist This External Id",
  "description": "Already exist an asset with this External Id",
  "translation": "Ja existe um ativo com esse External Id",
  "code": "TRC000054"
}
```

## Próximos passos

Após inserir o ativo, o fluxo continua com:

1. **[Envio dos documentos](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie a documentação exigida para cada ativo aprovado na elegibilidade.
2. **[Encerramento da inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)** — sinalize que todos os ativos foram inseridos para que o lote siga para a análise de elegibilidade.

---

# Criação de Ativo — Duplicata

URL: /documentation/iaas/negociacao_recebiveis/asset/criacao_duplicata

Endpoint para inserir um ativo do tipo **Duplicata** em um lote de cessão. Existem dois subtipos aceitos: **Duplicata Mercantil** (`duplicata_mercantil`) — vinculada a uma nota fiscal de venda de mercadorias — e **Duplicata de Serviços** (`duplicata_servicos`) — vinculada a uma nota fiscal de prestação de serviços.

:::info Diferença entre os tipos
Ambos os tipos utilizam a mesma estrutura de request body. A principal diferença é que a **duplicata mercantil** não exige envio de documentos após a elegibilidade, enquanto a **duplicata de serviços** exige. Consulte a página de [Inserção de Documentos](/documentation/iaas/negociacao_recebiveis/asset/documents) para mais detalhes.
:::

:::tip Onde estou no fluxo?
Este é o **2º passo** do fluxo de cessão. Antes, você deve ter [criado o lote](/documentation/iaas/negociacao_recebiveis/assignment/criacao). Após inserir os ativos, envie os [documentos](/documentation/iaas/negociacao_recebiveis/asset/documents) exigidos e [encerre a inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento).
:::

:::caution Atenção
O campo `external_id` do direito creditório deve ser único para cada ativo e não deve ser confundido com o `external_id` do lote.
:::

## Request

ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/asset
MÉTODO POST

```json title="Request Body"
{
    "asset_type": "duplicata_mercantil",
    "total_purchase_value": 1231.21,
    "discounted_credit_right": {
        "external_id": "ccf6f331-d55f-46c0-a32f-fb909884dbb2",
        "originator_document_number": "46.282.154/0001-14",
        "maturity_date": "2023-12-10",
        "order_number": "18923619954796912",
        "face_value": 1023.01,
        "person_type": "natural_person",
        "borrower": {
            "name": "Natália Nascimento",
            "document_number": "805.359.140-08",
            "person_type": "natural_person",
            "email": "natália.nascimento@yopmail.com",
            "address": {
                "street": "Gilberto Sabino",
                "number": "215",
                "neighborhood": "Pinheiros",
                "city": "São Paulo",
                "postal_code": "05425-020",
                "uf": "SP",
                "country": "BRA"
            },
            "phone": {
                "area_code": "11",
                "number": "36360268"
            },
            "natural_person": {
                "mother_name": "Lívia Santos",
                "birthdate": "2001-01-05"
            }
        },
        "participant_control_number": "ICX841HWCPUGU4U101XPLDW8D",
        "bankslip": {
            "our_number": {
                "number": 2,
                "digit": "P"
            }
        },
        "delay": {
            "fine": {
                "fine_type": "percentage",
                "percentage_value": 0.0
            },
            "interest": {
                "method": "pre_fixed",
                "pre_fixed": {
                    "daily_rate": 0.0,
                    "calendar_base": "calendar_360"
                }
            }
        },
        "invoice": {
            "access_key": "69037229347091328617032722238810300308237163",
            "total_value": 1231.21,
            "serie": "123",
            "number": "958431587",
            "issue_date": "2023-10-10"
        }
    }
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `asset_type` | string | obrigatório | Tipo do ativo. Valores aceitos: `duplicata_mercantil` ou `duplicata_servicos`. |
| `total_purchase_value` | number | obrigatório | Valor total da compra do ativo — efetivamente quanto o cessionário vai pagar. Até 2 casas decimais. |
| `discounted_credit_right` | object | obrigatório | Dados do direito creditório. Veja [Atributos de `discounted_credit_right`](#atributos-de-discounted_credit_right). |

#### Atributos de `discounted_credit_right`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `external_id` | string | obrigatório | Chave única de identificação deste ativo no sistema do parceiro. Máximo de 50 caracteres. |
| `originator_document_number` | string | obrigatório | CPF ou CNPJ formatado do originador/consultor que viabilizou a operação. |
| `maturity_date` | string | obrigatório | Data de vencimento no formato `YYYY-MM-DD`. |
| `order_number` | string | obrigatório | Número do pedido. Máximo de 45 caracteres. |
| `face_value` | number | obrigatório | Valor de face. Até 8 casas decimais. |
| `person_type` | string | opcional | Tipo de pessoa do sacado (`natural_person` ou `legal_person`). |
| `borrower` | object | obrigatório | Dados do sacado. Consulte os [Atributos de `borrower`](/documentation/iaas/negociacao_recebiveis/asset/criacao_co#atributos-de-borrower) na página de Criação de Ativo — CCB. |
| `participant_control_number` | string | opcional | Número de controle do participante no sistema do parceiro. Máximo de 50 caracteres alfanuméricos. |
| `bankslip` | object | opcional | Dados do boleto. Veja [Atributos de `bankslip`](#atributos-de-bankslip). |
| `delay` | object | opcional | Dados de multa e juros por atraso. Consulte os [Atributos de `delay`](/documentation/iaas/negociacao_recebiveis/asset/criacao_co#atributos-de-delay) na página de Criação de Ativo — CCB. |
| `invoice` | object | obrigatório | Dados da nota fiscal. Veja [Atributos de `invoice`](#atributos-de-invoice). |

#### Atributos de `bankslip`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `our_number` | object | opcional | Dados do nosso número. Aplicável apenas quando o nosso número é emitido pelo cliente. Veja [Atributos de `our_number`](#atributos-de-our_number). |

#### Atributos de `our_number`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `number` | number | obrigatório | Nosso número. Número bancário para cobrança com registro. 1 a 11 caracteres numéricos. |
| `digit` | string | obrigatório | Dígito verificador de auto conferência do nosso número. 1 caractere alfanumérico. |

#### Atributos de `invoice`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `access_key` | string | obrigatório | Chave de acesso da nota fiscal. 44 caracteres. |
| `total_value` | number | opcional | Valor total da nota fiscal. Até 2 casas decimais. |
| `serie` | string | obrigatório | Número de série da nota fiscal. Máximo de 3 caracteres. |
| `number` | string | obrigatório | Número da nota fiscal. Máximo de 50 caracteres. |
| `issue_date` | string | obrigatório | Data de emissão no formato `YYYY-MM-DD`. |

## Response

STATUS 201

```json title="Response Body"
{
    "asset_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "external_id": "ccf6f331-d55f-46c0-a32f-fb909884dbb2",
    "status": "pending_eligibility"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `asset_key` | string | Identificador único do ativo gerado pela QI Tech (UUID). |
| `external_id` | string | A mesma chave externa fornecida no campo `external_id` do `discounted_credit_right`. |
| `status` | string | Status inicial do ativo. Sempre retorna `pending_eligibility`, indicando que o ativo foi inserido e aguarda análise de elegibilidade. |

## Possíveis erros

STATUS 404

**Lote não encontrado**

O `assignment_external_id` informado na URL não corresponde a nenhum lote existente nesta configuração de cessão. Verifique se o identificador está correto.

```json
{
  "title": "Assignment not found",
  "description": "Assignment not found",
  "translation": "Lote não encontrado",
  "code": "TRC000018"
}
```

STATUS 404

**Tipo de ativo não existe**

O valor informado no campo `asset_type` não é um tipo válido. Verifique se o tipo está correto (ex: `duplicata_mercantil`, `duplicata_servicos`).

```json
{
  "title": "Asset type does not exist",
  "description": "Asset type 'invalid_asset_type' does not exist",
  "translation": "Tipo do ativo 'invalid_asset_type' nao existe",
  "code": "TRC000015"
}
```

STATUS 400

**Tipo de ativo incompatível com o lote**

O lote foi configurado para receber um tipo de ativo diferente do informado. Cada configuração de cessão aceita apenas um tipo de ativo específico. Verifique a configuração de cessão utilizada.

```json
{
  "title": "Invalid asset type configuration",
  "description": "This assignment can not receive this asset type: duplicata_mercantil",
  "translation": "Esse lote não pode receber esse tipo de ativo: duplicata_mercantil",
  "code": "TRC000025"
}
```

STATUS 400

**Lote fechado para inserção**

O lote já foi encerrado para inserção de novos ativos. Após o encerramento, não é possível adicionar mais ativos. Caso precise, [reabra o lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos) antes de inserir novos ativos.

```json
{
  "title": "Assignment is closed",
  "description": "Assignment is closed to insert new assets",
  "translation": "Lote esta fechado para inserir novos ativos",
  "code": "TRC000022"
}
```

STATUS 400

**External ID duplicado**

Já existe um ativo cadastrado com o `external_id` informado. Cada ativo deve ter um identificador único. Gere um novo `external_id` e tente novamente.

```json
{
  "title": "Already Exist This External Id",
  "description": "Already exist an asset with this External Id",
  "translation": "Ja existe um ativo com esse External Id",
  "code": "TRC000054"
}
```

## Próximos passos

Após inserir o ativo, o fluxo continua com:

1. **[Envio dos documentos](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie a documentação exigida para cada ativo aprovado na elegibilidade.
2. **[Encerramento da inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)** — sinalize que todos os ativos foram inseridos para que o lote siga para a análise de elegibilidade.

---

# Inserção de Ativo para Recompra

URL: /documentation/iaas/negociacao_recebiveis/asset/criacao_repurchased_asset

Endpoint para inserir um ativo que será **recomprado** pelo cedente em um lote de substituição. A recompra ocorre quando o cedente precisa retirar um ativo da carteira do fundo, substituindo-o por novos ativos.

:::info Lotes de substituição
Este endpoint é utilizado exclusivamente em **lotes de substituição**. O fluxo de substituição difere do fluxo de cessão padrão por incluir um passo adicional: a inserção dos ativos a serem recomprados, antes da inserção dos novos ativos.

Para mais detalhes, consulte o [Manual de Cessão de Direitos Creditórios](/documentation/iaas/negociacao_recebiveis/manual_api).
:::

:::tip Onde estou no fluxo?
Este é o **2º passo** do fluxo de substituição. Antes, você deve ter [criado o lote](/documentation/iaas/negociacao_recebiveis/assignment/criacao). Após inserir os ativos de recompra, insira os [novos ativos](/documentation/iaas/negociacao_recebiveis/asset/criacao_co) que substituirão os recomprados.
:::

## Request

ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/repurchased_asset
MÉTODO POST

```json title="Request Body"
{
    "asset_type": "duplicata_mercantil",
    "external_id": "88c2304e-8eb3-44e0-acb4-25811ae20cf1",
    "assignor_document_number": "66.642.277/0001-26",
    "repurchase_value": 1000.00,
    "settlement_type": "asset_settlement"
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `asset_type` | string | obrigatório | Tipo do ativo que será recomprado (ex: `ccb`, `duplicata_mercantil`, `discounted_contract`). |
| `external_id` | string | obrigatório | Identificador externo do ativo que será recomprado. Deve ser o mesmo `external_id` utilizado quando o ativo foi originalmente inserido. |
| `assignor_document_number` | string | obrigatório | CPF ou CNPJ do cedente que originalmente cedeu o ativo ao fundo. |
| `repurchase_value` | number | obrigatório | Valor de recompra do ativo. Até 2 casas decimais. |
| `settlement_type` | string | obrigatório | Modalidade de substituição [settlement_type](#settlement-type). |

### Settlement Type
| Enumerador | descrição |
|---|---|
| `asset_settlement` | Substituição total do ativo. |
| `asset_amortization` |  Substituição parcial do ativo. |

## Response

STATUS 201

```json title="Response Body"
{
    "repurchased_asset_key": "a6115a17-8b4d-49a3-aed6-47c9574eab88",
    "asset_type": "duplicata_mercantil",
    "asset_key": "65bbce6d-e0b4-4471-a702-e0ced4542e5b",
    "external_id": "88c2304e-8eb3-44e0-acb4-25811ae20cf1",
    "assignor": {
        "assignor_key": "c1d2e3f4-a5b6-7890-abcd-ef1234567890",
        "document_number": "66.642.277/0001-26",
        "name": "Cedente Exemplo Ltda"
    },
    "status": "pending_eligibility",
    "assignment": {
        "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
        "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
        "name": "CESSÃO #12345",
        "assignment_number": "00012345",
        "assignment_date": "2024-04-01",
        "status": "pending_assets_insertion",
        "origin_type": "client"
    },
    "repurchase_value": 1000.00
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `repurchased_asset_key` | string | Identificador único do registro de recompra gerado pela QI Tech (UUID). |
| `asset_type` | string | Tipo do ativo recomprado. |
| `asset_key` | string | Identificador único do ativo original na carteira do fundo (UUID). |
| `external_id` | string | Identificador externo do ativo, conforme informado na requisição. |
| `assignor` | object | Dados do cedente que originalmente cedeu o ativo. |
| `status` | string | Status atual do ativo de recompra. |
| `assignment` | object | Dados do lote de substituição ao qual o ativo de recompra pertence. Consulte os [atributos do lote](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao) na página de Recuperação do Lote. |
| `repurchase_value` | number | Valor de recompra do ativo, conforme informado na requisição. |

#### Atributos de `assignor`

| Campo | Tipo | Descrição |
|---|---|---|
| `assignor_key` | string | Identificador único do cedente (UUID). |
| `document_number` | string | CPF ou CNPJ do cedente. |
| `name` | string | Nome do cedente. |

## Possíveis erros

STATUS 404

**Lote não encontrado**

```json
{
  "title": "Assignment not found",
  "description": "Assignment not found",
  "translation": "Lote não encontrado",
  "code": "TRC000018"
}
```

STATUS 404

**Ativo não encontrado**

```json
{
  "title": "Asset not found",
  "description": "Asset not found",
  "translation": "Ativo não foi encontrado",
  "code": "TRC000020"
}
```

STATUS 400

**Lote fechado para inserção**

```json
{
  "title": "Assignment is closed",
  "description": "Assignment is closed to insert new assets",
  "translation": "Lote esta fechado para inserir novos ativos",
  "code": "TRC000022"
}
```

## Próximos passos

Após inserir os ativos de recompra, o fluxo continua com:

1. **[Inserção dos novos ativos](/documentation/iaas/negociacao_recebiveis/asset/criacao_co)** — adicione os ativos que substituirão os recomprados.
2. **[Envio dos documentos](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie a documentação exigida para cada novo ativo.
3. **[Encerramento da inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)** — sinalize que todos os ativos foram inseridos para que o lote siga para a análise de elegibilidade.

---

# Inserção de Documentos do Ativo

URL: /documentation/iaas/negociacao_recebiveis/asset/documents

Endpoint para enviar os documentos obrigatórios associados a um ativo do lote de cessão. Os documentos devem ser enviados em formato PDF codificado em Base64.

:::tip Onde estou no fluxo?
O envio de documentos ocorre após a inserção do ativo e após o ativo ter sido aprovado na elegibilidade individual. Você receberá um [webhook](/documentation/iaas/negociacao_recebiveis/asset/webhooks) com o status `pending_documentation` indicando que o ativo está aguardando documentação.
:::

:::info Quais ativos exigem documentos?
- **CCB** (`ccb`): o envio de documentos é sempre obrigatório.
- **Duplicata de serviços** (`duplicata_servicos`): o envio de documentos é obrigatório.
- **Duplicata mercantil** (`duplicata_mercantil`): o envio de documentos **não** é obrigatório — a documentação é gerada automaticamente pelo sistema a partir dos dados da nota fiscal.
- **Contrato descontado** (`discounted_contract`): consulte a configuração do produto no Contrato de Cessão.

O ativo só avança para o status `pre_approved` depois que todos os documentos exigidos forem enviados.
:::

:::info Formato do documento
O arquivo enviado deve ser um **PDF válido** codificado em Base64. Outros formatos serão rejeitados com erro.
:::

## Request

ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/asset/{asset_external_id}/document
MÉTODO POST

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID). |
| `assignment_configuration_key` | string | Chave da configuração de cessão (UUID). |
| `assignment_external_id` | string | Identificador externo do lote, informado na criação do lote. |
| `asset_external_id` | string | O `external_id` informado na criação do ativo. |

```json title="Request Body"
{
    "document_type": "ccb",
    "document_b64": "aGVsbG8gd29ybGQgaWYgeW91IGRlY29kZWQgbWUsIGJlIGNhcmVmdWwuIEl0IG11c3QgYmUgYSBQREYgRmlsZSBvdGhlcndpc2UgSSB3aWxsIHJhaXNlIGFuIEVycm9yLg=="
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `document_type` | string | obrigatório | Tipo do documento que está sendo enviado. Os valores aceitos são os configurados na configuração de cessão utilizada — veja os enumeradores abaixo. |
| `document_b64` | string | obrigatório | Conteúdo do arquivo PDF codificado em Base64. |

**Enumeradores de `document_type`:**

| Valor | Descrição |
|---|---|
| `ccb` | Cédula de Crédito Bancário — usado em ativos do tipo CCB. |
| `duplicata_servicos` | Duplicata de serviços — usado em ativos de duplicata de serviços. |
| `contract` | Contrato parcelado — usado em ativos do tipo `contract`. |
| `vehicle_reservation_receipt` | Comprovante de reserva do veículo — usado em operações de crédito com garantia de veículo. É um documento **pós-cessão**. |

:::info Dois momentos de envio de documento
Este endpoint atende a **dois momentos distintos** do fluxo, e o que muda entre eles é apenas o status do ativo:

- **Antes da cessão.** O ativo entra em `pending_documentation` depois de aprovado na elegibilidade individual e aguarda os documentos configurados como obrigatórios do produto. Com todos enviados, ele avança para `pre_approved`.
- **Depois da cessão.** Se a configuração de cessão exigir documentos pós-cessão, o ativo entra em `pending_after_assignment_documentation` após a liquidação do lote. É aqui que entra o **comprovante de reserva do veículo** (`vehicle_reservation_receipt`) das operações com garantia de veículo. Com todos enviados, o ativo avança para `completed`. **Este segundo momento não é notificado por webhook** — diferente do primeiro: acompanhe pela [recuperação do ativo](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos) e trate o `completed` como confirmação.

A lista de documentos exigidos em cada momento é definida por produto e vem na resposta da [configuração de cessão](/documentation/iaas/negociacao_recebiveis/listagem), nos campos `required_documents` (antes da cessão) e `after_assignment_required_documents` (depois da cessão). Enviar um `document_type` que existe no sistema mas não está configurado para aquela cessão devolve `TRC000032`; enviar um valor que o sistema não conhece devolve `TRC000033`.
:::

## Response

STATUS 201

```json title="Response Body"
{
    "document_key": "8e515a17-8b4d-49a3-aed6-47c9574e426a"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `document_key` | string | Identificador único do documento gerado pela QI Tech (UUID). |

## Possíveis erros

STATUS 404

**Ativo não encontrado**

O `asset_external_id` informado na URL não corresponde a nenhum ativo do lote. Verifique se o identificador está correto e se o ativo pertence ao lote informado.

```json
{
  "title": "Asset not found",
  "description": "Asset not found",
  "translation": "Ativo não foi encontrado",
  "code": "TRC000020"
}
```

STATUS 400

**Tipo de documento inválido para esta configuração**

O valor informado em `document_type` não corresponde a nenhum tipo de documento configurado para esta cessão. Verifique quais tipos de documento são aceitos na configuração de cessão utilizada.

```json
{
  "title": "Invalid documents",
  "description": "Required documents type are invalid",
  "translation": "Tipo de Documentos requeridos sao inválidos",
  "code": "TRC000032"
}
```

STATUS 400

**Tipo de documento não reconhecido**

O tipo de documento informado não é reconhecido pelo sistema. Verifique se o valor de `document_type` está correto.

```json
{
  "title": "Invalid document type",
  "description": "Invalid document type",
  "translation": "Tipo de documento invalido",
  "code": "TRC000033"
}
```

STATUS 400

**Formato do documento inválido**

O arquivo enviado não está em formato PDF válido ou a codificação Base64 está incorreta. Verifique se o arquivo é um PDF válido e se a codificação Base64 foi feita corretamente.

```json
{
  "title": "Invalid document format",
  "description": "Invalid document format",
  "translation": "Formato do documento invalido",
  "code": "TRC000034"
}
```

STATUS 400

**Status do ativo inválido para envio de documento**

O ativo não está em um status que permita o envio de documentos. Normalmente isso significa que o ativo ainda não foi aprovado na elegibilidade ou já foi descartado.

```json
{
  "title": "Invalid operation",
  "description": "Asset is not in a valid status to receive documents",
  "translation": "Ativo não está em status válido para receber documentos",
  "code": "TRC000024"
}
```

## Próximos passos

Após enviar todos os documentos exigidos, o fluxo continua com:

1. **[Encerramento da inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)** — sinalize que todos os ativos e documentos foram inseridos para que o lote siga para a análise de elegibilidade.

---

# Consulta de Ativos do Lote

URL: /documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos

Endpoints para consultar os ativos inseridos em um lote de cessão. Existem dois modos de consulta: a **listagem paginada** de todos os ativos de um lote, e a **consulta individual** de um ativo específico.

:::tip Quando utilizar
Utilize estes endpoints para acompanhar o status dos ativos após a inserção, verificar quais foram aprovados ou reprovados na elegibilidade, e consultar os motivos de reprovação quando houver.

A listagem aceita **filtros** — inclusive por status — o que permite consultar diretamente apenas os ativos reprovados, sem precisar paginar o lote inteiro. Veja [Consultar apenas os ativos reprovados](#consultar-apenas-os-ativos-reprovados).
:::

## Listagem de ativos

Retorna a lista paginada dos ativos de um lote, com suporte a filtros.

### Request

ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment/{assignment_external_id}/assets
MÉTODO GET

### Query params

Todos os filtros são opcionais e podem ser combinados entre si. Quando nenhum filtro é informado, a rota devolve todos os ativos do lote.

| Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
| `page` | integer | `0` | Número da página (começa em 0). |
| `limit` | integer | `10` | Quantidade de registros por página. Máximo: `100`. |
| `status` | string | — | Filtra por um status de ativo. Aceita **um único valor**, que deve ser um dos [enumeradores de status](#enumeradores-de-status-do-ativo). Use `denied` para obter apenas os ativos reprovados. |
| `external_id` | string | — | Filtra pelo `external_id` do ativo informado na criação. |
| `contract_number` | string | — | Filtra pelo número do contrato da operação. |
| `borrower_document_number` | string | — | Filtra pelo CPF/CNPJ do devedor (sacado ou tomador, conforme o tipo de ativo). |
| `purchase_value_min` | number | — | Valor mínimo de compra do ativo (inclusive). |
| `purchase_value_max` | number | — | Valor máximo de compra do ativo (inclusive). |
| `maturity_date_start` | string (`AAAA-MM-DD`) | — | Data de vencimento inicial do intervalo. |
| `maturity_date_end` | string (`AAAA-MM-DD`) | — | Data de vencimento final do intervalo. |

```python title="Exemplo — listagem simples"
GET /trade_receivables/fund_class/{fund_class_key}/assignment/{assignment_external_id}/assets?page=0&limit=10
```

```python title="Exemplo — filtros combinados"
GET /trade_receivables/fund_class/{fund_class_key}/assignment/{assignment_external_id}/assets?status=denied&limit=100&maturity_date_start=2024-01-01&maturity_date_end=2024-12-31
```

:::warning Status inválido
Se o valor enviado em `status` não corresponder a nenhum enumerador válido, a requisição retorna erro. Consulte a [tabela de enumeradores](#enumeradores-de-status-do-ativo) antes de montar o filtro.
:::

### Response

STATUS 200

```json title="Response Body"
{
    "data": [
        {
            "asset_key": "f4348106-01c4-4c59-a261-7c09db811c47",
            "external_id": "e292656f-f7fb-44dc-96f3-667c36c88442",
            "total_purchase_value": 1231.21,
            "asset_type": "duplicata_mercantil",
            "status": "denied",
            "duration": 9177,
            "denied_by": "document",
            "denial_reason": "Invalid documents"
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Lista de objetos de ativo. Veja tabela abaixo. |
| `page` | integer | Número da página atual. |
| `limit` | integer | Quantidade de registros por página. |
| `is_last_page` | boolean | Indica se esta é a última página de resultados. |

#### Atributos de cada ativo (objetos dentro de `data`)

| Campo | Tipo | Descrição |
|---|---|---|
| `asset_key` | string | Identificador único do ativo (UUID). |
| `external_id` | string | Chave externa fornecida pelo parceiro na criação. |
| `total_purchase_value` | number | Valor total de compra do ativo. |
| `asset_type` | string | Tipo do ativo (ex: `ccb`, `duplicata_mercantil`, `discounted_contract`). |
| `status` | string | Status atual do ativo. Consulte a [tabela de status](#enumeradores-de-status-do-ativo) abaixo. |
| `duration` | integer | Duração do ativo em dias. Pode não estar presente se ainda não foi calculada. |
| `denied_by` | string | Origem da reprovação. Presente apenas quando o ativo foi reprovado. Consulte a [tabela de origens](#origens-de-reprovação-denied_by). |
| `denial_reason` | string | Descrição do motivo da reprovação. Presente apenas quando o ativo foi reprovado. |

:::info Objetos aninhados
Dependendo do tipo de ativo, a resposta incluirá o objeto `credit_operation` (para CCBs) ou `discounted_credit_right` (para duplicatas e contratos descontados) com todos os dados da operação de crédito.
:::

## Consultar apenas os ativos reprovados

Este é o uso mais comum da listagem: descobrir **quais contratos do lote foram reprovados**, para refletir a decisão da QI Tech no controle interno do parceiro e decidir se algum ativo precisa ser [removido do lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos).

Basta informar `status=denied`:

```python title="Request"
GET /trade_receivables/fund_class/{fund_class_key}/assignment/{assignment_external_id}/assets?status=denied&limit=100
```

A resposta traz somente os ativos reprovados, cada um com `denied_by` (a origem da reprovação) e `denial_reason` (a descrição):

```json title="Response Body"
{
    "data": [
        {
            "asset_key": "f4348106-01c4-4c59-a261-7c09db811c47",
            "external_id": "e292656f-f7fb-44dc-96f3-667c36c88442",
            "total_purchase_value": 1231.21,
            "asset_type": "ccb",
            "status": "denied",
            "duration": 9177,
            "denied_by": "eligibility",
            "denial_reason": "Prazo do contrato acima do permitido pela política do fundo"
        }
    ],
    "limit": 100,
    "page": 0,
    "is_last_page": true
}
```

:::tip Recomendações de uso
- Use `limit=100` (o máximo permitido) para reduzir o número de páginas e pagine até `is_last_page` ser `true`.
- Consulte após receber o webhook [`pending_manager_approval`](/documentation/iaas/negociacao_recebiveis/assignment/webhooks#pendente-aprovação-do-gestor) — nesse momento a análise de elegibilidade de todos os ativos já foi concluída e a lista de reprovados está estável.
- Para o inverso — os ativos aprovados na elegibilidade — use `status=pre_approved`.
:::

### Origens de reprovação (`denied_by`)

| Valor | Significado |
|---|---|
| `eligibility` | Reprovado na análise de elegibilidade. |
| `document` | Reprovado na validação dos documentos enviados. |
| `inconsistency` | Reprovado por inconsistência nos dados da operação identificada na validação. |
| `invalid_invoice` | Reprovado na validação da nota fiscal. |
| `registry` | Reprovado no processo de registro do ativo. |
| `term` | Reprovado na etapa do Termo de Cessão. |
| `manager` | Reprovado/removido por ação do gestor do fundo. |
| `consultant` | Reprovado/removido por ação do consultor. |
| `assignor` | Reprovado/removido por ação do cedente. |
| `accounting_close` | Reprovado por fechamento contábil do fundo. |
| `denial_file` | Reprovado por arquivo de reprovação processado em lote. |

## Consulta de ativo específico

Retorna os dados completos de um ativo específico do lote.

### Request

ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/asset/{asset_external_id}
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `asset_external_id` | string | O `external_id` informado na criação do ativo. |

### Response

STATUS 200

```json title="Response Body"
{
    "asset_key": "074f8786-447f-4524-9f4f-a5cf8a890bb4",
    "external_id": "acfbc329-4e67-40ea-bd8d-5debdaebe144",
    "total_purchase_value": 1231.21,
    "asset_type": "duplicata_mercantil",
    "status": "denied",
    "duration": 9184,
    "denied_by": "document",
    "denial_reason": "Invalid documents"
}
```

### Atributos da resposta

A resposta possui a mesma estrutura de cada objeto do array `data` retornado pela [listagem de ativos](#atributos-de-cada-ativo-objetos-dentro-de-data), acrescida do objeto completo da operação de crédito (`credit_operation` ou `discounted_credit_right`, dependendo do tipo de ativo).

## Enumeradores de status do ativo

Qualquer um dos valores abaixo pode ser usado no filtro `status` da listagem.

| Status | Descrição |
|---|---|
| `created` | Ativo criado, ainda não submetido à análise. |
| `pending_eligibility` | Ativo inserido, aguardando análise de elegibilidade. |
| `pending_documentation` | Ativo aprovado na elegibilidade, aguardando envio de documentos. |
| `pending_invoice_validation` | Aguardando validação da nota fiscal. |
| `pre_approved` | Ativo pré-aprovado na elegibilidade individual. |
| `pending_registry` | Aguardando início do registro do ativo. |
| `pending_external_registry` | Aguardando registro em câmara externa. |
| `sending_to_registry` | Em envio para a câmara de registro. |
| `waiting_registry` | Registro submetido, aguardando retorno da câmara. |
| `pending_formalization` | Ativo formalizado e apto a seguir no lote. |
| `registry_denied` | Registro do ativo recusado pela câmara. |
| `sending_to_wallet` | Em processo de encarteiramento na carteira do fundo. |
| `denied` | Ativo reprovado. Consulte `denied_by` para a origem da reprovação. |
| `discarded` | Ativo descartado do lote. |
| `completed` | Ativo encarteirado na carteira do fundo. |

---

# Remoção de Ativos do Lote

URL: /documentation/iaas/negociacao_recebiveis/asset/remocao_ativos

Processo para retirar ativos de um lote que está aguardando aprovação do gestor. A remoção envolve **3 passos sequenciais**: reabrir o lote, remover os ativos desejados e fechar o lote novamente.

:::info Pré-requisito
A remoção de ativos só é possível quando o lote está no status `pending_manager_approval` (aguardando aprovação do gestor). Com o lote nesse status, é necessário reabri-lo antes de realizar qualquer alteração nos ativos.
:::

## Passo 1 — Reabrir o lote

Altere o status do lote para `pending_assets_insertion` para permitir a remoção de ativos.

### Request

ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}
MÉTODO PUT

```json title="Request Body"
{
    "assignment_status": "pending_assets_insertion"
}
```

#### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `assignment_status` | string | obrigatório | Status para o qual o lote será atualizado. Para reabrir, envie `pending_assets_insertion`. |

### Response

STATUS 200

```json title="Response Body"
{
    "assignment_key": "8e515a17-8b4d-49a3-aed6-47c9574e426a",
    "external_id": "9eec85be-97c9-41e0-88b3-b17a39869b36",
    "status": "pending_assets_insertion",
    "number_of_approved_assets": 10,
    "assignment_total_value": 1234.99
}
```

#### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `assignment_key` | string | Identificador único do lote (UUID). |
| `external_id` | string | Chave externa do lote fornecida pelo parceiro. |
| `status` | string | Novo status do lote: `pending_assets_insertion`. |
| `number_of_approved_assets` | integer | Quantidade de ativos aprovados no lote. |
| `assignment_total_value` | number | Valor total da cessão em reais. |

## Passo 2 — Remover ativos

Com o lote reaberto, remova cada ativo desejado alterando seu status para `denied`. Realize uma requisição para cada ativo a ser removido.

### Request

ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/asset/{asset_external_id}
MÉTODO PUT

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `asset_external_id` | string | O `external_id` do ativo que será removido. |

```json title="Request Body"
{
    "asset_status": "denied"
}
```

#### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `asset_status` | string | obrigatório | Status para o qual o ativo será atualizado. Para remover, envie `denied`. |

### Response

STATUS 200

```json title="Response Body"
{
    "external_id": "9eec85be-97c9-41e0-88b3-b17a39869b36",
    "status": "denied"
}
```

#### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `external_id` | string | Chave externa do ativo. |
| `status` | string | Novo status do ativo: `denied`. |

## Passo 3 — Fechar o lote novamente

Após remover os ativos desejados, feche o lote para que ele siga novamente para aprovação do gestor.

### Request

ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}
MÉTODO PUT

```json title="Request Body"
{
    "assignment_status": "completed_assets_insertion"
}
```

#### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `assignment_status` | string | obrigatório | Status para o qual o lote será atualizado. Para fechar, envie `completed_assets_insertion`. |

### Response

STATUS 200

```json title="Response Body"
{
    "assignment_key": "8e515a17-8b4d-49a3-aed6-47c9574e426a",
    "external_id": "9eec85be-97c9-41e0-88b3-b17a39869b36",
    "status": "completed_assets_insertion",
    "number_of_approved_assets": 10,
    "assignment_total_value": 1234.99
}
```

#### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `assignment_key` | string | Identificador único do lote (UUID). |
| `external_id` | string | Chave externa do lote fornecida pelo parceiro. |
| `status` | string | Novo status do lote: `completed_assets_insertion`. |
| `number_of_approved_assets` | integer | Quantidade de ativos aprovados remanescentes. |
| `assignment_total_value` | number | Valor total atualizado da cessão em reais. |

Após fechar o lote, ele seguirá novamente para aprovação do gestor e continuará o fluxo normalmente.

## Possíveis erros

STATUS 404

**Ativo não encontrado**

O `asset_external_id` informado na URL não corresponde a nenhum ativo do lote. Verifique se o identificador está correto e se o ativo pertence ao lote informado.

```json
{
  "title": "Asset not found",
  "description": "Asset not found",
  "translation": "Ativo não foi encontrado",
  "code": "TRC000020"
}
```

STATUS 400

**Ativo não pode ser removido**

O ativo informado não pode ser negado/removido no status atual. Isso pode ocorrer quando o ativo já foi descartado ou quando o lote não está aberto para modificação.

```json
{
  "title": "Cant deny this asset.",
  "description": "This asset cant be denied.",
  "translation": "Esse ativo não pode ser negado",
  "code": "TRC000086"
}
```

STATUS 400

**Status do lote inválido para esta operação**

O lote não está em um status que permita esta operação. Para remover ativos, o lote precisa estar no status `pending_assets_insertion`. Verifique o status atual do lote e, se necessário, reabra-o primeiro (Passo 1).

```json
{
  "title": "Invalid assignment status",
  "description": "Assignment is not in a valid status for this operation",
  "translation": "O lote não está em um status valido para essa operação",
  "code": "TRC000087"
}
```

---

# Webhooks do Ativo

URL: /documentation/iaas/negociacao_recebiveis/asset/webhooks

Ao longo do fluxo de cessão, o sistema envia webhooks para notificar o parceiro integrador sobre mudanças de status dos ativos individuais. Existem dois tipos de webhook: `trade_receivables.asset_status_change` para mudanças de status e `trade_receivables.asset_creation` para confirmação de criação do ativo.

:::info Configuração de webhooks
Para receber webhooks, é necessário ter uma URL de callback configurada junto à QI Tech. Entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) para configurar.
:::

## Fluxo de status do ativo

O ativo entra em `pending_eligibility` assim que é inserido no lote e, a partir da análise de elegibilidade, segue por um dos caminhos abaixo. Todos os nove status geram webhook — o caminho central leva ao encarteiramento, e as três saídas de recusa ou descarte são terminais.

![Fluxo de status do ativo, do pending_eligibility até completed, com as saídas para denied, registry_denied e discarded](/img/diagrams/iaas-negociacao-recebiveis-asset-webhooks.svg)

_Como ler o diagrama: **azul** = status intermediário · **verde** = ativo cedido e encarteirado · **vermelho** = status final de recusa ou descarte._

## Estrutura do webhook

Todos os webhooks de ativo seguem a mesma estrutura base:

| Campo | Tipo | Descrição |
|---|---|---|
| `webhook_type` | string | Tipo do webhook: `trade_receivables.asset_status_change` ou `trade_receivables.asset_creation`. |
| `webhook_datetime` | string | Data e hora do evento no formato ISO 8601. |
| `data` | object | Dados do evento. Veja tabela abaixo. |

#### Atributos de `data`

| Campo | Tipo | Descrição |
|---|---|---|
| `assignment_external_id` | string | O `external_id` do lote ao qual o ativo pertence. |
| `asset_external_id` | string | O `external_id` do ativo. |
| `asset_new_status` | string | Novo status do ativo. |
| `assignment_configuration_key` | string | Identificador da configuração de cessão à qual o lote pertence — a mesma chave usada nas URLs dos endpoints. |
| `fund_class_key` | string | Identificador da classe do fundo associada ao lote. |
| `asset_payload` | object | Presente apenas no webhook de criação (`asset_creation`). Contém todos os dados do ativo conforme enviados na criação. |

:::info O que é a `assignment_configuration_key`
A **configuração de cessão** é o acordo já cadastrado entre o cedente e o fundo: ela define para qual fundo os recebíveis são cedidos, qual tipo de ativo é aceito e sob quais regras a operação acontece. É a mesma chave que você já usa nas URLs dos endpoints de cessão, obtida na [Homologação de Cedente](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato).

Como um mesmo cedente pode ter mais de uma configuração ativa ao mesmo tempo, esse campo informa **sob qual acordo** o ativo está sendo cedido. Assim você direciona o webhook para o fluxo certo sem precisar consultar a API para descobrir a origem do ativo.
:::

```json title="Estrutura padrão do webhook"
{
    "data": {
        "assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
        "asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "asset_new_status": "STATUS",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c"
    },
    "webhook_type": "trade_receivables.asset_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

## Eventos por status

### Ativo Criado

STATUS pending_eligibility

Enviado quando um ativo é inserido no lote com sucesso. Este webhook inclui o campo `asset_payload` com todos os dados da operação de crédito enviados na criação. O tipo do webhook é `trade_receivables.asset_creation`.

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
        "asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "asset_new_status": "pending_eligibility",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
        "asset_payload": {
            "premiums": [
                {
                    "total_value": 1.2,
                    "premium_type": "spread"
                }
            ],
            "asset_type": "ccb",
            "credit_operation": {
                "delay": {
                    "fine": {
                        "amount": 0.0,
                        "fine_type": "percentage"
                    },
                    "interest": {
                        "method": "compound",
                        "pre_fixed": {
                            "monthly_rate": 0.0,
                            "calendar_base": "workdays"
                        }
                    }
                },
                "borrower": {
                    "name": "João Pereira",
                    "email": "exemplo3@gmail.com",
                    "phone": {
                        "number": "948386674",
                        "area_code": "11"
                    },
                    "address": {
                        "uf": "SP",
                        "city": "São Paulo",
                        "number": "84",
                        "street": "RUA GILBERTO SABINO",
                        "country": "BRA",
                        "postal_code": "05425-020",
                        "neighborhood": "Pinheiros"
                    },
                    "person_type": "natural_person",
                    "natural_person": {
                        "birthdate": "1970-02-18",
                        "mother_name": "Natalia Nascimento"
                    },
                    "document_number": "926.857.750-05"
                },
                "contract": {
                    "cet": 0.0314,
                    "number": "0032226586/NNT",
                    "iof_value": 3.04,
                    "issue_date": "2024-04-24",
                    "issue_value": 93.05,
                    "signature_date": "2024-04-24",
                    "disbursement_date": "2024-04-24",
                    "disbursement_value": 62.1
                },
                "pre_fixed": {
                    "monthly_rate": 0.0179,
                    "calendar_base": "calendar_365"
                },
                "external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
                "installments": [
                    {
                        "face_value": 30.81,
                        "maturity_date": "2025-02-01",
                        "installment_number": 1
                    },
                    {
                        "face_value": 26.19,
                        "maturity_date": "2026-02-01",
                        "installment_number": 2
                    },
                    {
                        "face_value": 29.68,
                        "maturity_date": "2027-02-01",
                        "installment_number": 3
                    },
                    {
                        "face_value": 23.74,
                        "maturity_date": "2028-02-01",
                        "installment_number": 4
                    },
                    {
                        "face_value": 28.49,
                        "maturity_date": "2029-02-01",
                        "installment_number": 5
                    },
                    {
                        "face_value": 19.94,
                        "maturity_date": "2030-02-01",
                        "installment_number": 6
                    },
                    {
                        "face_value": 13.96,
                        "maturity_date": "2031-02-01",
                        "installment_number": 7
                    },
                    {
                        "face_value": 13.03,
                        "maturity_date": "2032-02-01",
                        "installment_number": 8
                    }
                ],
                "principal_value": 93.05,
                "amortization_type": "price",
                "interest_rate_type": "pre_fixed",
                "originator_document_number": "40.940.511/0001-08"
            },
            "total_purchase_value": 94.86
        }
    },
    "webhook_type": "trade_receivables.asset_creation",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### Aprovado na Elegibilidade — Pendente Documentação

STATUS pending_documentation

Enviado quando o ativo é **aprovado** na análise de elegibilidade e está aguardando o envio dos documentos obrigatórios. Utilize o endpoint de [Inserção de Documentos](/documentation/iaas/negociacao_recebiveis/asset/documents) para enviar a documentação exigida.

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
        "asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "asset_new_status": "pending_documentation",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c"
    },
    "webhook_type": "trade_receivables.asset_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### Pré-Aprovado

STATUS pre_approved

Enviado quando o ativo é **pré-aprovado**, após validação bem-sucedida dos documentos (ou quando nenhuma documentação adicional é exigida). O ativo está apto para avançar para a etapa de formalização/registro.

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
        "asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "asset_new_status": "pre_approved",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c"
    },
    "webhook_type": "trade_receivables.asset_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### Pendente Registro

STATUS pending_registry

Enviado quando o ativo pré-aprovado é encaminhado para a **registradora**. Só ocorre em configurações de cessão cujo `registry_type` exige registro — `internal_registry`, `external_registry`, `registry_transfer` ou `unfit`. O ativo permanece nesse status até a registradora responder.

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
        "asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "asset_new_status": "pending_registry",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c"
    },
    "webhook_type": "trade_receivables.asset_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### Pendente Formalização

STATUS pending_formalization

Enviado quando o ativo pré-aprovado foi encaminhado para a etapa de formalização (registro no órgão competente). O ativo aguarda a conclusão do processo de registro para ser encarteirado.

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
        "asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "asset_new_status": "pending_formalization",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c"
    },
    "webhook_type": "trade_receivables.asset_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### Ativo Concluído

STATUS completed

Enviado quando o ativo foi **encarteirado com sucesso** na carteira do fundo. Este é o status final de um ativo bem-sucedido — a partir desse momento, o ativo encontra-se dentro do estoque do fundo.

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
        "asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "asset_new_status": "completed",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c"
    },
    "webhook_type": "trade_receivables.asset_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### Reprovado na Elegibilidade

STATUS denied

Enviado quando o ativo é **reprovado** na análise de elegibilidade ou na validação de documentos. O ativo não seguirá adiante no fluxo.

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
        "asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "asset_new_status": "denied",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c"
    },
    "webhook_type": "trade_receivables.asset_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### Registro Recusado

STATUS registry_denied

Enviado quando a **registradora recusa** o registro do ativo. É um status **terminal**: o ativo não segue para a formalização nem para o encarteiramento. O motivo da recusa é registrado pela QI Tech e não vem no corpo do webhook — consulte a [recuperação do ativo](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos) ou o time de integração para o detalhe.

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
        "asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "asset_new_status": "registry_denied",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c"
    },
    "webhook_type": "trade_receivables.asset_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### Ativo Descartado

STATUS discarded

Enviado quando o ativo é descartado do lote. Isso pode ocorrer por remoção manual ou por problemas durante o processamento.

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
        "asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "asset_new_status": "discarded",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c"
    },
    "webhook_type": "trade_receivables.asset_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

# Aprovação do Gestor

URL: /documentation/iaas/negociacao_recebiveis/assignment/aprovacao

Após a elegibilidade do lote ser aprovada, o gestor do fundo deve analisar e decidir pela aprovação ou reprovação do lote. Se aprovado, o sistema gera o Termo de Cessão e o encaminha para assinatura. Se reprovado, o lote é descartado e o processo se encerra.

:::info Rota exclusiva para Gestores
Este endpoint está disponível **somente para gestores** do fundo. Caso o gestor não seja integrado via API, essa ação pode ser realizada pelo [Portal do Gestor](https://portal-do-gestor.fundos.qitech.com.br/).
:::

:::tip Onde estou no fluxo?
Este passo ocorre após a **elegibilidade do lote** ter sido aprovada. Você receberá um [webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks) com o status `pending_manager_approval` indicando que o lote está aguardando a decisão do gestor.
:::

## Request

ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}
MÉTODO PUT

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `assignment_external_id` | string | O `external_id` informado na criação do lote. |

```json title="Request Body — Aprovação"
{
    "assignment_status": "approved",
    "disbursement_account_key": "764746ce-a530-4a71-af66-3f7c879627df"
}
```

```json title="Request Body — Reprovação"
{
    "assignment_status": "denied"
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `assignment_status` | string | obrigatório | Decisão do gestor sobre o lote. Valores aceitos: `approved` ou `denied`. |
| `disbursement_account_key` | string | opcional | Chave única (UUID, 36 caracteres) da conta de desembolso cadastrada na homologação do cedente. Se não informada, será utilizada a conta padrão configurada no contrato de cessão. |

**Enumeradores de `assignment_status`:**

| Valor | Descrição |
|---|---|
| `approved` | Aprova o lote — o sistema gerará o Termo de Cessão |
| `denied` | Reprova o lote — o lote será descartado |

## Response

STATUS 200

```json title="Response Body — Aprovação"
{
    "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
    "status": "approved",
    "number_of_approved_assets": 45,
    "assignment_total_value": 150000.00
}
```

```json title="Response Body — Reprovação"
{
    "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
    "status": "denied",
    "number_of_approved_assets": 0,
    "assignment_total_value": 0.00
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `assignment_key` | string | Identificador único do lote (UUID). |
| `external_id` | string | Chave externa do lote fornecida pelo parceiro. |
| `status` | string | Novo status do lote após a decisão do gestor (`approved` ou `denied`). |
| `number_of_approved_assets` | integer | Quantidade de ativos aprovados na elegibilidade. Em caso de reprovação, o valor será `0`. |
| `assignment_total_value` | number | Valor total da cessão em reais. Em caso de reprovação, o valor será `0.00`. |

## Possíveis erros

STATUS 400

**Lote não encontrado**

O `external_id` informado na URL não corresponde a nenhum lote existente nesta configuração de cessão. Verifique se o identificador está correto e se você está usando a `fund_class_key` e `assignment_configuration_key` corretas.

```json
{
  "title": "Assignment not found",
  "description": "Assignment not found",
  "translation": "Cessão não foi encontrada",
  "code": "TRC000018"
}
```

STATUS 400

**Operação inválida para o status atual**

O lote não está em um status que permita aprovação ou reprovação. Isso geralmente ocorre quando o lote ainda não passou pela elegibilidade, ou quando já foi aprovado/reprovado anteriormente. Consulte o status atual do lote via [Recuperação do Lote](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao) para entender em qual etapa ele se encontra.

```json
{
  "title": "Invalid operation",
  "description": "This assignment can not receive 'denied' status",
  "translation": "Esse lote não pode receber o status 'denied'",
  "code": "TRC000024"
}
```

## Próximos passos

Após a aprovação do gestor, o fluxo continua automaticamente:

1. **Assinatura do Termo de Cessão** — o sistema gera o Termo de Cessão e o envia para assinatura de todas as partes. Você receberá um [webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks) com status `pending_assignment_term_signature`. O documento pode ser consultado via [Documentos da Cessão](/documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao).
2. **Pagamento** — após a assinatura, o sistema realiza o pagamento ao cedente. Um [webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks) com status `pending_payment` será enviado.
3. **Encarteiramento** — os ativos são incluídos na carteira do fundo e o lote é finalizado com status `completed`.

---

# Criação do Lote de Cessão

URL: /documentation/iaas/negociacao_recebiveis/assignment/criacao

Este é o **primeiro passo** do fluxo de cessão de direitos creditórios. A criação do lote (*assignment*) reserva um agrupamento onde os ativos que serão cedidos ao fundo serão inseridos nas etapas seguintes.

:::info Pré-requisitos
Antes de criar um lote, você precisa ter em mãos:
- A `fund_class_key` — chave única do fundo cessionário.
- A `assignment_configuration_key` — chave única da configuração de cessão, obtida na [Homologação de Cedente](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato).

Essas duas chaves compõem os endpoints utilizados em todos os endpoints desta API:

```
/trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}
```

Para mais detalhes sobre o fluxo completo, consulte o [Manual de Cessão de Direitos Creditórios](/documentation/iaas/negociacao_recebiveis/manual_api).
:::

## Request

ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment
MÉTODO POST

```json title="Request Body"
{
    "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
    "assignment_date": "2024-04-01"
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `external_id` | string | obrigatório | Chave única de identificação deste lote no sistema do parceiro integrador. Deve ser única — o sistema não permitirá a criação de dois lotes com o mesmo identificador. Máximo de 50 caracteres. |
| `assignment_date` | string | opcional | Data da cessão no formato `YYYY-MM-DD`. Quando informada, deve corresponder à data contábil do fundo (*accounting_date*). Se não informada, será utilizada a data contábil vigente. |

## Response

STATUS 201

```json title="Response Body"
{
    "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
    "status": "pending_assets_insertion"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `assignment_key` | string | Identificador único do lote gerado pela QI Tech (UUID). |
| `external_id` | string | A mesma chave externa fornecida na requisição. |
| `status` | string | Status inicial do lote. Sempre retorna `pending_assets_insertion`, indicando que o lote está pronto para receber ativos. |

## Possíveis erros

STATUS 404

**Configuração de cessão não encontrada**

A combinação de `fund_class_key` e `assignment_configuration_key` informada não corresponde a nenhuma configuração de cessão. Verifique se as chaves estão corretas e se o contrato de cessão já foi homologado na etapa de [Homologação de Cedente](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato).

```json
{
  "title": "AssignmentConfiguration was not found",
  "description": "AssignmentConfiguration was not found",
  "translation": "Configuração de cessão não foi encontrada",
  "code": "TRC000016"
}
```

STATUS 400

**Data de cessão inválida**

A data informada no campo `assignment_date` não corresponde à data contábil atual do fundo. Cada fundo possui uma data contábil vigente, e a data da cessão precisa ser igual a essa data. Verifique a data contábil vigente do fundo ou omita o campo `assignment_date` para que o sistema utilize a data automaticamente.

```json
{
  "title": "Invalid assignment date.",
  "description": "Given assignment date is different from fund accounting date.",
  "translation": "Data de cessão fornecida diferente da data do fundo.",
  "code": "TRC000083"
}
```

STATUS 400

**External ID duplicado**

Já existe um lote cadastrado com o `external_id` informado. Cada lote deve ter um identificador único no sistema. Gere um novo `external_id` e tente novamente.

```json
{
  "title": "Already Exists This External Id",
  "description": "Already Exists This External Id",
  "translation": "Já existe lote com esse external_id",
  "code": "TRC000041"
}
```

## Próximos passos

Após criar o lote, o fluxo continua com:

1. **[Inserção dos ativos](/documentation/iaas/negociacao_recebiveis/asset/criacao_co)** — adicione os ativos (CCBs, duplicatas, etc.) que serão cedidos ao fundo.
2. **[Envio dos documentos](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie a documentação exigida para cada ativo aprovado na elegibilidade.
3. **[Encerramento da inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)** — sinalize que todos os ativos foram inseridos para que o lote siga para a análise de elegibilidade.

---

# Documentos da Cessão

URL: /documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao

Recupera os links para download do Termo de Cessão — tanto a versão original quanto a versão assinada. Este endpoint fica disponível a partir do momento em que o Termo é gerado, ou seja, após o lote atingir o status `pending_assignment_term_signature`.

:::tip Quando utilizar
Após receber o [webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks) com status `pending_assignment_term_signature`, utilize este endpoint para obter o link do Termo de Cessão e acompanhar se a assinatura já foi concluída.
:::

## Request

ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/assignment_term_link
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID). |
| `assignment_configuration_key` | string | Chave da configuração de cessão (UUID). |
| `assignment_external_id` | string | O `external_id` informado na criação do lote. |

## Response

STATUS 200

```json title="Response Body"
{
    "assignment_term_url": "https://storage.example.com/term/abc123.pdf",
    "signed_assignment_term_url": "https://storage.example.com/term/abc123_signed.pdf"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `assignment_term_url` | string | URL que direciona para o download do termo. |
| `signed_assignment_term_url` | string \| null | URL para o Termo de Cessão assinado. Retorna `null` enquanto o documento ainda não tiver sido assinado por todas as partes. |

:::info Observação
O campo `signed_assignment_term_url` será `null` enquanto o Termo de Cessão ainda não tiver sido assinado por todas as partes envolvidas. Após a conclusão da assinatura, o lote avançará para o status `pending_payment` e um [webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks) será enviado.
:::

---

# Link de Assinatura

Recupera o link para acesso à interface de assinatura do Termo de Cessão na CertifiQI, além de informações sobre os lotes e o link para download do documento. Este endpoint fica disponível a partir do momento em que o Termo é gerado, ou seja, após o lote atingir o status `pending_assignment_term_signature`.

## Request

ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/assignment_signature_url
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID). |
| `assignment_configuration_key` | string | Chave da configuração de cessão (UUID). |
| `assignment_external_id` | string | O `external_id` informado na criação do lote. |

## Response

STATUS 200

```json title="Response Body"
{
    "batches": [
        {
            "name": "Termo de Cessão - Lote 001",
            "document_type": "assignment_term",
            "status": "pending",
            "document_key": "doc-uuid-example",
            "related_parties": [...]
        }
    ],
    "signature_url": "https://certifiqi.com/events/{external_batch_group_key}",
    "download_url": "https://storage.example.com/term/abc123.pdf"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `batches` | array | Lista de lotes vinculados ao Termo de Cessão. |
| `batches[].name` | string | Nome do lote. |
| `batches[].document_type` | string | Tipo do documento (ex: `assignment_term`, `duplicata`). |
| `batches[].status` | string | Status atual da assinatura do lote. |
| `batches[].document_key` | string | Chave identificadora do documento. |
| `batches[].related_parties` | array | Partes envolvidas na assinatura do lote. |
| `signature_url` | string | URL para acesso à interface de assinatura na CertifiQI. |
| `download_url` | string | URL pré-assinada para download do Termo de Cessão. |

:::info Observação
O campo `download_url` aponta para o documento original (não assinado) enquanto o lote estiver no status `pending_assignment_term_signature`. Após a conclusão da assinatura por todas as partes, passa a apontar para o Termo de Cessão assinado.
:::

---

# Encerrar Inserção de Ativos

URL: /documentation/iaas/negociacao_recebiveis/assignment/fechamento

Após inserir todos os ativos desejados no lote, utilize este endpoint para sinalizar que a inserção foi concluída. A partir desse momento, quando todos os ativos estiverem pré-aprovados (`pre_approved`) ou descartados (`discarded`), a elegibilidade do lote como um todo será avaliada automaticamente.

:::info Não é necessário aguardar os webhooks dos ativos
Você pode encerrar a inserção a qualquer momento após inserir os ativos. Não é preciso esperar que todos os ativos passem pela elegibilidade individual. O sistema aguardará automaticamente até que todos estejam com análise finalizada antes de prosseguir com a elegibilidade do lote.
:::

:::tip Onde estou no fluxo?
Este é o **3º passo** do fluxo de cessão. Antes deste passo, você deve ter:
1. [Criado o lote](/documentation/iaas/negociacao_recebiveis/assignment/criacao)
2. [Inserido os ativos](/documentation/iaas/negociacao_recebiveis/asset/criacao_co) e [enviado os documentos](/documentation/iaas/negociacao_recebiveis/asset/documents)
:::

## Request

ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}
MÉTODO PUT

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `assignment_external_id` | string | O `external_id` informado na criação do lote. |

```json title="Request Body"
{
    "assignment_status": "completed_assets_insertion"
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `assignment_status` | string | obrigatório | Status para o qual o lote será atualizado. Para encerrar a inserção de ativos, envie `completed_assets_insertion`. |

## Response

STATUS 200

```json title="Response Body"
{
    "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
    "status": "completed_assets_insertion",
    "number_of_approved_assets": 0,
    "assignment_total_value": 0.00
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `assignment_key` | string | Identificador único do lote (UUID). |
| `external_id` | string | Chave externa do lote fornecida pelo parceiro. |
| `status` | string | Novo status do lote: `completed_assets_insertion`. |
| `number_of_approved_assets` | integer | Quantidade de ativos aprovados no lote. Nesta etapa, o valor será `0` pois a elegibilidade ainda não foi processada. |
| `assignment_total_value` | number | Valor total da cessão em reais. Nesta etapa, o valor será `0.00` pois a precificação ainda não ocorreu. |

## Possíveis erros

STATUS 400

**Lote sem ativos inseridos**

Você tentou encerrar a inserção de ativos, mas o lote ainda não possui nenhum ativo. É necessário [inserir pelo menos um ativo](/documentation/iaas/negociacao_recebiveis/asset/criacao_co) antes de fechar o lote.

```json
{
  "title": "Cannot Close This Assignment",
  "description": "Cannot close this assignment because there is no asset.",
  "translation": "Não é possível fechar este lote porque não há nenhum ativo.",
  "code": "TRC000042"
}
```

## Próximos passos

Após encerrar a inserção, o fluxo segue automaticamente:

1. **Elegibilidade dos ativos** — cada ativo será analisado individualmente. Você receberá [webhooks dos ativos](/documentation/iaas/negociacao_recebiveis/asset/webhooks) informando aprovação ou reprovação.
2. **Elegibilidade do lote** — quando todos os ativos tiverem sido analisados, a elegibilidade do lote será avaliada. O resultado será informado via [webhook do lote](/documentation/iaas/negociacao_recebiveis/assignment/webhooks).
3. **[Aprovação do gestor](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao)** — caso o lote seja aprovado na elegibilidade, o gestor do fundo deverá aprová-lo.

---

# Listagem de Lotes de Cessão

URL: /documentation/iaas/negociacao_recebiveis/assignment/listagem

Endpoint de consulta paginada que retorna os lotes de cessão de uma determinada classe de fundo. Utilize os filtros disponíveis para buscar lotes por data, status ou combinações de status.

:::info Endpoint por classe de fundo
Diferente dos demais endpoints de lote, este utiliza apenas a `fund_class_key` na URL — não é necessário informar a `assignment_configuration_key`. Isso permite listar lotes de todas as configurações de cessão de um fundo de uma vez.
:::

## Request

ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignments
MÉTODO GET

### Query params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `assignment_date` | string | opcional | Filtra por data da cessão no formato `YYYY-MM-DD`. |
| `assignment_status` | string | opcional | Filtra por um status específico do lote. |
| `in_status` | array | opcional | Lista de status para **incluir** na busca. Retorna apenas lotes que estejam em um dos status informados. |
| `not_in_status` | array | opcional | Lista de status para **excluir** da busca. Retorna apenas lotes que **não** estejam nos status informados. |
| `assignor_document_number` | string | opcional | Filtra por número de documento (CPF/CNPJ) do cedente. Deve ser enviado **com pontuação** (ex: `12.345.678/0001-90` ou `123.456.789-00`). |
| `page` | integer | opcional | Número da página (começa em 0). Padrão: `0`. |
| `limit` | integer | opcional | Quantidade de registros por página. Padrão: `25`. Máximo: `155`. |

```python title="Exemplo de chamada"
GET /trade_receivables/fund_class/{fund_class_key}/assignments?assignment_date=2024-04-01&in_status=pending_manager_approval,completed&page=0&limit=10
```

## Response

STATUS 200

```json title="Response Body"
{
  "data": [
    {
      "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
      "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
      "name": "CESSÃO #12345",
      "assignment_configuration": {
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "validation_configuration_key": "v1w2x3y4-z5a6-7890-abcd-ef1234567890",
        "assignment_configuration_name": "Config CCB Fundo Alpha",
        "assignment_contract_key": "k1l2m3n4-o5p6-7890-abcd-ef1234567890",
        "registry_type": "internal_registry",
        "asset_type": "ccb",
        "assignment_configuration_type": "standard",
        "consultant_decision_type": "manual_approval",
        "asset_fees": null,
        "assignment_reports": null,
        "fund_class": {
          "fund_class_key": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
          "name": "Fundo Alpha FIDC",
          "document_number": "12.345.678/0001-90",
          "accounting_date": "2024-04-01",
          "manager": {
            "manager_key": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
            "document_number": "11.222.333/0001-44",
            "manager_name": "Gestora Exemplo S.A."
          }
        },
        "assignor": {
          "assignor_key": "c1d2e3f4-a5b6-7890-abcd-ef1234567890",
          "document_number": "98.765.432/0001-10",
          "name": "Cedente Exemplo Ltda"
        },
        "consultant": {
          "consultant_key": "g1h2i3j4-k5l6-7890-abcd-ef1234567890",
          "document_number": "55.666.777/0001-88",
          "name": "Consultoria Exemplo Ltda"
        },
        "originator_bonds": [
          {
            "originator": {
              "originator_key": "h1i2j3k4-l5m6-7890-abcd-ef1234567890",
              "document_number": "22.333.444/0001-55",
              "name": "Originadora Exemplo Ltda"
            }
          }
        ],
        "webhook_configuration_bonds": [
          {
            "webhook_configuration_bond": {
              "webhook_configuration_key": "w1x2y3z4-a5b6-7890-abcd-ef1234567890",
              "agent_type": "assignor",
              "agent_key": "c1d2e3f4-a5b6-7890-abcd-ef1234567890"
            },
            "signature_key": "s1t2u3v4-w5x6-7890-abcd-ef1234567890",
            "webhook_url": "https://partner.example.com/webhooks/trade_receivables"
          }
        ]
      },
      "assignment_number": "00012345",
      "assignment_date": "2024-04-01",
      "status": "completed",
      "assignment_term_key": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
      "disbursement": {
        "target_account": {
          "account_key": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
          "account_type": "checking_account",
          "account_branch": "001",
          "account_number": "12345",
          "account_digit": "4",
          "financial_institution_code": "341",
          "financial_institution_ispb": "60701190",
          "owner": {
            "document_number": "98.765.432/0001-10"
          }
        }
      },
      "assignment_total_value": 150000.00,
      "assignment_irr": 0.0215
    }
  ],
  "limit": 10,
  "page": 0,
  "is_last_page": true
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Lista de objetos de lote de cessão. Veja tabela abaixo. |
| `page` | integer | Número da página atual. |
| `limit` | integer | Quantidade de registros por página. |
| `is_last_page` | boolean | Indica se esta é a última página de resultados. |

#### Atributos de cada lote (objetos dentro de `data`)

Cada objeto do array possui a mesma estrutura retornada pelo endpoint de [Recuperação do Lote](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao), com exceção do campo `status_events` que **não é retornado** na listagem.

| Campo | Tipo | Descrição |
|---|---|---|
| `assignment_key` | string | Identificador único do lote (UUID). |
| `external_id` | string | Chave externa fornecida pelo parceiro. |
| `name` | string | Nome identificador da cessão. |
| `assignment_number` | string | Número do lote de cessão. |
| `assignment_date` | string | Data da cessão no formato `YYYY-MM-DD`. |
| `status` | string | Status atual do lote. Consulte a [tabela de status](#enumeradores-de-status-do-lote) abaixo. |
| `origin_type` | string | Origem do lote (ex: `client`). |
| `assignment_term_key` | string | Chave do Termo de Cessão (UUID). Disponível após geração do termo. |
| `assignment_total_value` | number | Valor total da cessão em reais. Pode não estar presente se ainda não foi calculado. |
| `assignment_irr` | number | Taxa interna de retorno (TIR) do lote. Pode não estar presente se ainda não foi calculada. |
| `assignment_configuration` | object | Dados da configuração de cessão associada ao lote. Consulte os [atributos de `assignment_configuration`](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao#atributos-de-assignment_configuration) na página de Recuperação. |
| `disbursement` | object \| null | Dados da conta de desembolso (quando aplicável). |
| `assignor_discounts` | array | Lista de descontos do cedente. Presente apenas quando existem descontos configurados. Consulte os [atributos de `assignor_discounts`](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao#atributos-de-assignor_discounts) na página de Recuperação. |

## Enumeradores de status do lote

| Status | Descrição |
|---|---|
| `pending_assets_insertion` | Lote criado, aguardando inserção de ativos |
| `completed_assets_insertion` | Inserção de ativos encerrada, aguardando elegibilidade |
| `pending_eligibility` | Em análise de elegibilidade |
| `pending_consultant_approval` | Aguardando aprovação do consultor |
| `pending_manager_approval` | Aguardando aprovação do gestor |
| `pending_assets_registry` | Aguardando registro dos ativos |
| `pending_assignment_term` | Aguardando geração do Termo de Cessão |
| `pending_assignment_term_signature` | Aguardando assinatura do Termo de Cessão |
| `pending_custody` | Aguardando custódia |
| `pending_payment` | Aguardando pagamento ao cedente |
| `pending_assets_wallet_inclusion` | Aguardando encarteiramento dos ativos |
| `completed` | Cessão finalizada com sucesso |
| `denied` | Lote reprovado na elegibilidade |
| `discarded` | Lote descartado |

---

# Recuperação do Lote de Cessão

URL: /documentation/iaas/negociacao_recebiveis/assignment/recuperacao

Recupera os detalhes completos de um lote de cessão específico, incluindo informações da configuração, status atual, histórico de eventos, dados de desembolso e valores financeiros.

:::tip Quando utilizar
Use este endpoint para consultar o estado atual de um lote a qualquer momento do fluxo — por exemplo, para verificar se o lote já passou pela elegibilidade, se o gestor já aprovou, ou se o pagamento foi realizado.
:::

## Request

ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID). |
| `assignment_configuration_key` | string | Chave da configuração de cessão (UUID). |
| `assignment_external_id` | string | O `external_id` informado na criação do lote. |

## Response

STATUS 200

```json title="Response Body"
{
  "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
  "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
  "name": "CESSÃO #12345",
  "assignment_configuration": {
    "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
    "validation_configuration_key": "v1w2x3y4-z5a6-7890-abcd-ef1234567890",
    "assignment_configuration_name": "Config CCB Fundo Alpha",
    "assignment_contract_key": "k1l2m3n4-o5p6-7890-abcd-ef1234567890",
    "registry_type": "internal_registry",
    "asset_type": "ccb",
    "assignment_configuration_type": "standard",
    "consultant_decision_type": "manual_approval",
    "asset_fees": null,
    "assignment_reports": null,
    "fund_class": {
      "fund_class_key": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "name": "Fundo Alpha FIDC",
      "document_number": "12.345.678/0001-90",
      "accounting_date": "2024-04-01",
      "manager": {
        "manager_key": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
        "document_number": "11.222.333/0001-44",
        "manager_name": "Gestora Exemplo S.A."
      }
    },
    "assignor": {
      "assignor_key": "c1d2e3f4-a5b6-7890-abcd-ef1234567890",
      "document_number": "98.765.432/0001-10",
      "name": "Cedente Exemplo Ltda"
    },
    "consultant": {
      "consultant_key": "g1h2i3j4-k5l6-7890-abcd-ef1234567890",
      "document_number": "55.666.777/0001-88",
      "name": "Consultoria Exemplo Ltda"
    },
    "originator_bonds": [
      {
        "originator": {
          "originator_key": "h1i2j3k4-l5m6-7890-abcd-ef1234567890",
          "document_number": "22.333.444/0001-55",
          "name": "Originadora Exemplo Ltda"
        }
      }
    ],
    "webhook_configuration_bonds": [
      {
        "webhook_configuration_bond": {
          "webhook_configuration_key": "w1x2y3z4-a5b6-7890-abcd-ef1234567890",
          "agent_type": "assignor",
          "agent_key": "c1d2e3f4-a5b6-7890-abcd-ef1234567890"
        },
        "signature_key": "s1t2u3v4-w5x6-7890-abcd-ef1234567890",
        "webhook_url": "https://partner.example.com/webhooks/trade_receivables"
      }
    ]
  },
  "assignment_number": "00012345",
  "assignment_date": "2024-04-01",
  "status": "completed",
  "origin_type": "client",
  "assignment_term_key": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
  "disbursement": {
    "target_account": {
      "account_key": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
      "account_type": "checking_account",
      "account_branch": "001",
      "account_number": "12345",
      "account_digit": "4",
      "financial_institution_code": "341",
      "financial_institution_ispb": "60701190",
      "owner": {
        "document_number": "98.765.432/0001-10"
      }
    }
  },
  "assignment_total_value": 150000.00,
  "assignment_irr": 0.0215,
  "assignor_discounts": [
    {
      "assignor_discount_key": "ad12e3f4-a5b6-7890-abcd-ef1234567890",
      "assignor_discount_type": "flat_rate",
      "status": "approved",
      "total_value": 500.00,
      "description": "Taxa de administração"
    }
  ],
  "status_events": [
    {
      "status": "pending_assets_insertion",
      "event_datetime": "2024-04-01 10:00:00"
    },
    {
      "status": "completed_assets_insertion",
      "event_datetime": "2024-04-01 11:30:00"
    },
    {
      "status": "pending_eligibility",
      "event_datetime": "2024-04-01 11:35:00"
    },
    {
      "status": "completed",
      "event_datetime": "2024-04-01 16:00:00",
      "selected_agent": {
        "AGENT-TYPE": "manager",
        "AGENT-KEY": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
        "AGENT-USER": "gestor@exemplo.com"
      }
    }
  ]
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `assignment_key` | string | Identificador único do lote gerado pela QI Tech (UUID). |
| `external_id` | string | Chave externa fornecida pelo parceiro na criação. |
| `name` | string | Nome identificador da cessão. |
| `assignment_number` | string | Número sequencial do lote de cessão. |
| `assignment_date` | string | Data da cessão no formato `YYYY-MM-DD`. |
| `status` | string | Status atual do lote. Consulte os [enumeradores de status](/documentation/iaas/negociacao_recebiveis/assignment/listagem#enumeradores-de-status-do-lote) para todos os valores possíveis. |
| `assignment_term_key` | string | Chave do Termo de Cessão (UUID). Disponível após a geração do termo. |
| `assignment_total_value` | number | Valor total da cessão em reais. Disponível após a aprovação. Pode não estar presente se ainda não foi calculado. |
| `assignment_irr` | number | Taxa interna de retorno (TIR) do lote. Pode não estar presente se ainda não foi calculada. |
| `assignment_configuration` | object | Dados completos da configuração de cessão. Veja tabela abaixo. |
| `disbursement` | object \| null | Dados da conta de desembolso. `null` quando ainda não configurada. |
| `assignor_discounts` | array | Lista de descontos do cedente. Presente apenas quando existem descontos configurados. Veja tabela abaixo. |
| `status_events` | array | Histórico de transições de status do lote. Veja tabela abaixo. |

#### Atributos de `assignment_configuration`

| Campo | Tipo | Descrição |
|---|---|---|
| `assignment_configuration_key` | string | Chave da configuração (UUID). |
| `validation_configuration_key` | string | Chave da configuração de validação (UUID). |
| `assignment_configuration_name` | string | Nome da configuração de cessão. |
| `assignment_contract_key` | string | Chave do contrato de cessão (UUID). |
| `registry_type` | string | Tipo de registro dos ativos (ex: `internal_registry`, `external_registry`). |
| `asset_type` | string | Tipo de ativo aceito nesta configuração (ex: `ccb`, `duplicata_mercantil`, `duplicata_servico`). |
| `assignment_configuration_type` | string | Tipo da configuração de cessão (ex: `standard`). |
| `consultant_decision_type` | string | Tipo de decisão do consultor (ex: `manual_approval`, `auto_approval`). |
| `asset_fees` | object \| null | Configuração de taxas dos ativos, quando aplicável. |
| `assignment_reports` | object \| null | Configuração de relatórios da cessão, quando aplicável. |
| `fund_class` | object | Dados do fundo cessionário. Veja tabela abaixo. |
| `assignor` | object | Dados do cedente. Veja tabela abaixo. |
| `consultant` | object | Dados do consultor. Presente quando a configuração possui consultor vinculado. Veja tabela abaixo. |
| `originator_bonds` | array | Lista de originadores vinculados à configuração. Veja tabela abaixo. |
| `webhook_configuration_bonds` | array | Lista de configurações de webhook vinculadas. Veja tabela abaixo. |

#### Atributos de `fund_class`

| Campo | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID). |
| `name` | string | Nome do fundo. |
| `document_number` | string | CNPJ do fundo. |
| `accounting_date` | string | Data contábil vigente do fundo no formato `YYYY-MM-DD`. |
| `manager` | object | Dados do gestor do fundo. Veja tabela abaixo. |

#### Atributos de `manager`

| Campo | Tipo | Descrição |
|---|---|---|
| `manager_key` | string | Chave única do gestor (UUID). |
| `document_number` | string | CNPJ do gestor. |
| `manager_name` | string | Nome do gestor. |

#### Atributos de `assignor`

| Campo | Tipo | Descrição |
|---|---|---|
| `assignor_key` | string | Chave única do cedente (UUID). |
| `document_number` | string | CPF/CNPJ do cedente. |
| `name` | string | Nome do cedente. |

#### Atributos de `consultant`

| Campo | Tipo | Descrição |
|---|---|---|
| `consultant_key` | string | Chave única do consultor (UUID). |
| `document_number` | string | CNPJ do consultor. |
| `name` | string | Nome do consultor. |

#### Atributos de `originator_bonds`

| Campo | Tipo | Descrição |
|---|---|---|
| `originator` | object | Dados do originador. |
| `originator.originator_key` | string | Chave única do originador (UUID). |
| `originator.document_number` | string | CNPJ do originador. |
| `originator.name` | string | Nome do originador. |

#### Atributos de `webhook_configuration_bonds`

| Campo | Tipo | Descrição |
|---|---|---|
| `webhook_configuration_bond` | object | Dados da configuração de webhook. |
| `webhook_configuration_bond.webhook_configuration_key` | string | Chave única da configuração de webhook (UUID). |
| `webhook_configuration_bond.agent_type` | string | Tipo do agente que receberá o webhook (ex: `assignor`, `manager`, `consultant`). |
| `webhook_configuration_bond.agent_key` | string | Chave do agente vinculado. |
| `signature_key` | string | Chave de assinatura para validação do webhook (UUID). |
| `webhook_url` | string | URL de destino do webhook. |

#### Atributos de `assignor_discounts`

| Campo | Tipo | Descrição |
|---|---|---|
| `assignor_discount_key` | string | Chave única do desconto (UUID). |
| `assignor_discount_type` | string | Tipo de desconto do cedente (ex: `flat_rate`). |
| `status` | string | Status do desconto (ex: `approved`, `pending`). |
| `total_value` | number | Valor total do desconto em reais. |
| `description` | string | Descrição do desconto. |

#### Atributos de `status_events`

| Campo | Tipo | Descrição |
|---|---|---|
| `status` | string | Status do evento. |
| `event_datetime` | string | Data e hora do evento no formato `YYYY-MM-DD HH:MM:SS`. |
| `selected_agent` | object | Dados do agente responsável pela transição. Presente apenas quando a transição foi feita por um agente identificado. |

---

# Como criar uma cessão?

URL: /documentation/iaas/negociacao_recebiveis/assignment/video_cessao

Este guia apresenta o fluxo completo de criação de uma cessão de direitos creditórios, desde a criação do lote até o encarteiramento dos ativos no fundo. Utilize o vídeo abaixo como referência visual e os links para acessar a documentação detalhada de cada etapa.

:::tip Manual completo
Para um entendimento aprofundado das regras de negócio e do produto, consulte o [Manual de Cessão de Direitos Creditórios](/documentation/iaas/negociacao_recebiveis/manual_api).
:::

## Vídeo — Fluxo de cessão via Python

## Passo a passo

### 1. Criação do Lote

Crie um lote de cessão informando um identificador único (`external_id`). O lote será o contêiner para todos os ativos que serão cedidos ao fundo.

**[Acessar documentação da criação do lote](/documentation/iaas/negociacao_recebiveis/assignment/criacao)**

### 2. Inserção dos Ativos

Adicione os ativos (CCBs, duplicatas, etc.) ao lote criado. Cada ativo deve ser inserido individualmente com suas informações de operação, parcelas e dados do sacado.

**[Acessar documentação da inserção de ativos](/documentation/iaas/negociacao_recebiveis/asset/criacao_co)**

### 3. Envio dos Documentos

Para cada ativo aprovado na elegibilidade individual, envie os documentos exigidos pelo produto (contrato, nota fiscal, etc.). O ativo só prossegue na esteira após todos os documentos exigidos serem enviados.

**[Acessar documentação do envio de documentos](/documentation/iaas/negociacao_recebiveis/asset/documents)**

### 4. Encerramento da Inserção

Sinalize que todos os ativos foram inseridos no lote. Esse comando permite que o sistema avalie a elegibilidade do lote como um todo após todos os ativos serem analisados.

**[Acessar documentação do encerramento](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)**

### 5. Aprovação do Gestor

Após a elegibilidade do lote ser aprovada, o gestor do fundo analisa e aprova ou reprova o lote. Se aprovado, o Termo de Cessão será gerado automaticamente.

**[Acessar documentação da aprovação](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao)**

### 6. Assinatura, Pagamento e Encarteiramento

Os passos finais são automatizados: o Termo de Cessão é assinado pelas partes, o pagamento é realizado ao cedente e os ativos são encarteirados na carteira do fundo. Acompanhe o progresso através dos [webhooks do lote](/documentation/iaas/negociacao_recebiveis/assignment/webhooks).

---

# Webhooks do Lote de Cessão

URL: /documentation/iaas/negociacao_recebiveis/assignment/webhooks

Ao longo do fluxo de cessão, o sistema envia webhooks para notificar o parceiro integrador sobre mudanças de status do lote. Todos os webhooks possuem o tipo `trade_receivables.assignment_status_change` e identificam o lote pelo `assignment_external_id` fornecido na criação.

:::info Configuração de webhooks
Para receber webhooks, é necessário ter uma URL de callback configurada junto à QI Tech. Entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) para configurar.
:::

## Fluxo de status do lote

O lote percorre treze status, e **todos** geram webhook. A coluna central é o caminho de sucesso, da criação do lote até o encarteiramento dos ativos; a coluna da direita concentra as saídas de recusa, que podem ocorrer na elegibilidade, na aprovação do consultor ou na aprovação do gestor.

![Fluxo de status do lote de cessão, do pending_assets_insertion até completed, com as saídas para denied e discarded](/img/diagrams/iaas-negociacao-recebiveis-assignment-webhooks.svg)

_Como ler o diagrama: **azul** = status intermediário · **verde** = cessão concluída · **vermelho** = status final de recusa ou descarte._

## Estrutura do webhook

Todos os webhooks do lote de cessão seguem a mesma estrutura:

| Campo | Tipo | Descrição |
|---|---|---|
| `webhook_type` | string | Sempre `trade_receivables.assignment_status_change`. |
| `webhook_datetime` | string | Data e hora do evento no formato ISO 8601. |
| `data` | object | Dados do evento. Veja tabela abaixo. |

#### Atributos de `data`

| Campo | Tipo | Descrição |
|---|---|---|
| `assignment_external_id` | string | O `external_id` do lote informado na criação. |
| `assignment_new_status` | string | Novo status do lote. |
| `assignment_configuration_key` | string | Identificador da configuração de cessão à qual o lote pertence — a mesma chave usada nas URLs dos endpoints. |
| `fund_class_key` | string | Identificador da classe do fundo associada ao lote. |
| `signed_term_url` | string | URL para download do Termo de Cessão assinado. Presente apenas no webhook `pending_payment` quando o termo foi assinado digitalmente. |

:::info O que é a `assignment_configuration_key`
A **configuração de cessão** é o acordo já cadastrado entre o cedente e o fundo: ela define para qual fundo os recebíveis são cedidos, qual tipo de ativo é aceito e sob quais regras a operação acontece. É a mesma chave que você já usa nas URLs dos endpoints de cessão, obtida na [Homologação de Cedente](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato).

Como um mesmo cedente pode ter mais de uma configuração ativa ao mesmo tempo, esse campo informa **sob qual acordo** o evento aconteceu. Assim você direciona o webhook para o fluxo certo sem precisar consultar a API para descobrir a origem do lote.
:::

```json title="Estrutura padrão do webhook"
{
    "data": {
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "STATUS",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c"
    },
    "webhook_type": "trade_receivables.assignment_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

## Eventos por status

### Lote Criado — Aguardando Inserção de Ativos

STATUS pending_assets_insertion

Enviado quando um novo lote de cessão é criado com sucesso e está pronto para receber ativos. Este é o primeiro webhook do ciclo de vida do lote. O cedente pode inserir ativos enquanto o lote estiver neste status.

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "pending_assets_insertion",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c"
    },
    "webhook_type": "trade_receivables.assignment_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### Inserção de Ativos Concluída

STATUS completed_assets_insertion

Enviado quando a inserção de ativos é **encerrada** pelo cedente. A partir desse momento não é mais possível adicionar ativos ao lote, que avança automaticamente para a análise de elegibilidade.

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "completed_assets_insertion",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c"
    },
    "webhook_type": "trade_receivables.assignment_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### Em Análise de Elegibilidade

STATUS pending_eligibility

Enviado quando o lote inicia o processo de análise de elegibilidade. Todos os ativos são analisados individualmente, e o resultado agregado determina a aprovação ou reprovação do lote.

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "pending_eligibility",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c"
    },
    "webhook_type": "trade_receivables.assignment_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### Pendente Aprovação do Consultor

STATUS pending_consultant_approval

Enviado quando o lote passa na análise de elegibilidade e está aguardando a decisão do **consultor** do fundo. Esse status ocorre quando o fluxo de aprovação configurado exige aprovação prévia do consultor antes do gestor. O consultor pode aprovar ou reprovar o lote via [Portal do Consultor](https://portal-do-consultor.fundos.qitech.com.br/).

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "pending_consultant_approval",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c"
    },
    "webhook_type": "trade_receivables.assignment_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### Pendente Aprovação do Gestor

STATUS pending_manager_approval

Enviado quando o lote é **aprovado na elegibilidade** (e pelo consultor, quando aplicável) e está aguardando a decisão do gestor do fundo. O gestor deve aprovar ou reprovar o lote via [Aprovação do Gestor](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao) ou pelo [Portal do Gestor](https://portal-do-gestor.fundos.qitech.com.br/).

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "pending_manager_approval",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c"
    },
    "webhook_type": "trade_receivables.assignment_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### Aguardando Formalização dos Ativos

STATUS waiting_assets_to_formalize

Enviado quando o gestor **aprova** o lote e o sistema aguarda a conclusão da formalização (registro) de todos os ativos aprovados. O lote permanece neste status até que todos os ativos concluam o processo de registro.

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "waiting_assets_to_formalize",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c"
    },
    "webhook_type": "trade_receivables.assignment_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### Aguardando Geração do Termo de Cessão

STATUS pending_assignment_term

Enviado quando todos os ativos foram formalizados e o sistema está **gerando o Termo de Cessão**. O lote aguarda a conclusão da geração do documento antes de encaminhá-lo para assinatura.

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "pending_assignment_term",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c"
    },
    "webhook_type": "trade_receivables.assignment_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### Pendente Assinatura do Termo

STATUS pending_assignment_term_signature

Enviado após a aprovação do gestor, quando o Termo de Cessão foi gerado e encaminhado para assinatura de todas as partes envolvidas. Você pode consultar o documento via [Documentos da Cessão](/documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao).

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "pending_assignment_term_signature",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c"
    },
    "webhook_type": "trade_receivables.assignment_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### Pendente Pagamento

STATUS pending_payment

Enviado após o Termo de Cessão ter sido assinado por todas as partes. O sistema irá realizar o pagamento ao cedente na conta configurada. O valor total é a soma dos `total_purchase_value` de todos os ativos não descartados do lote.

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "pending_payment",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c"
    },
    "webhook_type": "trade_receivables.assignment_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### Aguardando Encarteiramento dos Ativos

STATUS pending_assets_wallet_inclusion

Enviado após a confirmação do pagamento ao cedente, quando os ativos estão sendo **encarteirados** na carteira do fundo. O sistema processa a inclusão dos ativos no estoque do fundo.

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "pending_assets_wallet_inclusion",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c"
    },
    "webhook_type": "trade_receivables.assignment_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### Cessão Completa

STATUS completed

Enviado quando todos os ativos do lote foram **encarteirados** na carteira do fundo. A partir desse momento, os ativos já se encontram dentro do estoque do fundo. Este é o status final de uma cessão bem-sucedida.

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "completed",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c"
    },
    "webhook_type": "trade_receivables.assignment_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### Reprovado na Elegibilidade

STATUS denied

Enviado quando o lote é **reprovado** na análise de elegibilidade ou pelo gestor/consultor do fundo. O lote ainda pode ser manipulado, porém caso nada aconteça ele será descartado.

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "denied",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c"
    },
    "webhook_type": "trade_receivables.assignment_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### Lote Descartado

STATUS discarded

Enviado quando o lote é descartado. Isso pode ocorrer por reprovação na elegibilidade, reprovação do gestor, ou por problemas no registro dos ativos. O lote não seguirá adiante no fluxo.

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "discarded",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c"
    },
    "webhook_type": "trade_receivables.assignment_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

# Fluxo de Cessão

URL: /documentation/iaas/negociacao_recebiveis/fluxo_cessao

Esta página oferece uma visão holística de todo o fluxo de cessão de direitos creditórios, desde a criação do lote até o encarteiramento dos ativos na carteira do fundo. Acompanhe a evolução dos **status do lote**, dos **status dos ativos** e dos **webhooks** recebidos em cada etapa.

:::tip Como usar este fluxograma
Passe o mouse sobre cada etapa para ver os detalhes do endpoint e acessar a documentação completa. As três trilhas coloridas mostram simultaneamente o que acontece com o lote, com os ativos e quais webhooks você receberá.
:::

{`
.cf-legend{display:flex;flex-wrap:wrap;gap:8px;margin-bottom:24px}
.cf-legend-item{display:flex;align-items:center;gap:6px;font-size:0.8rem;font-weight:600}
.cf-legend-dot{width:12px;height:12px;border-radius:3px}

.cf-step{position:relative;margin-bottom:4px}
.cf-step:not(:last-child)::after{content:'';display:block;width:2px;height:16px;margin:0 auto;background:var(--ifm-color-emphasis-300)}

.cf-card{border:1.5px solid var(--ifm-color-emphasis-200);border-radius:10px;padding:16px 20px;transition:box-shadow 0.2s,border-color 0.2s;cursor:pointer;background:var(--ifm-background-surface-color,var(--ifm-background-color))}
.cf-card:hover{box-shadow:0 4px 16px rgba(0,0,0,0.08);border-color:var(--ifm-color-primary)}

.cf-card-header{display:flex;align-items:center;gap:10px;flex-wrap:wrap}
.cf-num{width:28px;height:28px;border-radius:50%;display:flex;align-items:center;justify-content:center;font-size:0.8rem;font-weight:800;color:#fff;flex-shrink:0}
.cf-num-int{background:#3b82f6}
.cf-num-qi{background:#8b5cf6}
.cf-num-ges{background:#d946ef}
.cf-title{font-size:1rem;font-weight:700;color:var(--ifm-font-color-base)}
.cf-actor{font-size:0.7rem;font-weight:700;padding:2px 8px;border-radius:12px;margin-left:auto}
.cf-actor-int{background:rgba(59,130,246,0.12);color:#2563eb}
.cf-actor-qi{background:rgba(139,92,246,0.12);color:#7c3aed}
.cf-actor-ges{background:rgba(217,70,239,0.12);color:#c026d3}
.cf-subtitle{font-size:0.82rem;color:var(--ifm-color-emphasis-700);margin-top:4px;margin-left:38px}

.cf-tracks{display:flex;flex-wrap:wrap;gap:8px;margin-top:12px;margin-left:38px}
.cf-track{display:inline-flex;align-items:center;gap:5px;padding:3px 10px;border-radius:6px;font-size:0.75rem;font-family:var(--ifm-font-family-monospace);border:1px solid}
.cf-track-lote{background:rgba(34,197,94,0.1);color:#16a34a;border-color:rgba(34,197,94,0.25)}
.cf-track-ativo{background:rgba(59,130,246,0.1);color:#2563eb;border-color:rgba(59,130,246,0.25)}
.cf-track-wh{background:rgba(245,158,11,0.1);color:#b45309;border-color:rgba(245,158,11,0.25)}
.cf-track-err{background:rgba(239,68,68,0.1);color:#dc2626;border-color:rgba(239,68,68,0.25)}
.cf-track-label{font-family:var(--ifm-font-family-base);font-weight:700;font-size:0.7rem;text-transform:uppercase;letter-spacing:0.03em}
.cf-new{font-weight:700}
.cf-unchanged{opacity:0.5}

.cf-details{max-height:0;overflow:hidden;opacity:0;transition:max-height 0.35s ease,opacity 0.25s ease,margin 0.3s ease;margin-left:38px}
.cf-card:hover .cf-details{max-height:300px;opacity:1;margin-top:14px;padding-top:12px;border-top:1px solid var(--ifm-color-emphasis-200)}

.cf-endpoint{font-family:var(--ifm-font-family-monospace);font-size:0.82rem;padding:8px 12px;border-radius:6px;background:var(--ifm-color-emphasis-100);margin-bottom:8px;display:flex;align-items:center;gap:8px;flex-wrap:wrap}
.cf-method{font-weight:800;padding:2px 6px;border-radius:4px;font-size:0.72rem}
.cf-method-post{background:#f97316;color:#fff}
.cf-method-put{background:#3b82f6;color:#fff}
.cf-method-get{background:#22c55e;color:#fff}
.cf-desc{font-size:0.82rem;color:var(--ifm-color-emphasis-700);margin-bottom:8px}
.cf-link{font-size:0.82rem;font-weight:600;color:var(--ifm-color-primary);text-decoration:none}
.cf-link:hover{text-decoration:underline}

.cf-branch{margin-top:12px;margin-left:38px;display:flex;gap:12px;flex-wrap:wrap}
.cf-branch-path{flex:1;min-width:200px;border-radius:8px;padding:10px 14px;border:1.5px dashed}
.cf-branch-ok{border-color:rgba(34,197,94,0.4);background:rgba(34,197,94,0.05)}
.cf-branch-err{border-color:rgba(239,68,68,0.4);background:rgba(239,68,68,0.05)}
.cf-branch-label{font-size:0.78rem;font-weight:700;margin-bottom:4px}
.cf-branch-label-ok{color:#16a34a}
.cf-branch-label-err{color:#dc2626}

html[data-theme='dark'] .cf-track-lote{background:rgba(34,197,94,0.15);color:#4ade80;border-color:rgba(34,197,94,0.3)}
html[data-theme='dark'] .cf-track-ativo{background:rgba(59,130,246,0.15);color:#60a5fa;border-color:rgba(59,130,246,0.3)}
html[data-theme='dark'] .cf-track-wh{background:rgba(245,158,11,0.15);color:#fbbf24;border-color:rgba(245,158,11,0.3)}
html[data-theme='dark'] .cf-track-err{background:rgba(239,68,68,0.15);color:#f87171;border-color:rgba(239,68,68,0.3)}
html[data-theme='dark'] .cf-branch-ok{background:rgba(34,197,94,0.08)}
html[data-theme='dark'] .cf-branch-err{background:rgba(239,68,68,0.08)}
html[data-theme='dark'] .cf-actor-int{background:rgba(59,130,246,0.2);color:#60a5fa}
html[data-theme='dark'] .cf-actor-qi{background:rgba(139,92,246,0.2);color:#a78bfa}
html[data-theme='dark'] .cf-actor-ges{background:rgba(217,70,239,0.2);color:#e879f9}
`}

## Legenda

Agente Integrador
QI Tech (automático)
Gestor do Fundo
Status do Lote
Status do Ativo
Webhook

## Fluxograma

1
Criação do Lote
Agente Integrador
Cria um lote de cessão com um identificador único ( external_id ).
Lote: pending_assets_insertion
POST /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment
O lote é criado em status pending_assets_insertion , pronto para receber ativos.
Ver documentação completa →

2
Inserção dos Ativos
Agente Integrador
Insere os ativos no lote (CCB, duplicata, contrato descontado ou contrato parcelado). Repita para cada ativo.
Lote: pending_assets_insertion
Ativo: pending_eligibility
Webhook: asset_creation
POST /trade_receivables/.../assignment/{assignment_external_id}/asset
Cada ativo é criado com status pending_eligibility . Você receberá um webhook trade_receivables.asset_creation confirmando a inserção.
CCB →
Duplicata →
Contrato Descontado →
Contrato Parcelado →

3
Envio de Documentos
Agente Integrador
Envia os documentos exigidos para cada ativo (PDF em Base64). Duplicatas mercantis não exigem documentos.
Lote: pending_assets_insertion
Ativo: pending_eligibility
POST /trade_receivables/.../asset/{asset_external_id}/document
Envie os documentos após receber o webhook pending_documentation para o ativo (etapa 5a).
Ver documentação completa →

4
Encerrar Inserção
Agente Integrador
Sinaliza que todos os ativos foram inseridos no lote. A análise de elegibilidade será iniciada automaticamente.
Lote: completed_assets_insertion
Ativo: pending_eligibility
PUT /trade_receivables/.../assignment/{assignment_external_id}
Envie {"assignment_status": "completed_assets_insertion"} . Não é necessário aguardar os webhooks de elegibilidade individual dos ativos.
Ver documentação completa →

5a
Elegibilidade dos Ativos
QI Tech
A QI Tech analisa cada ativo individualmente. Você recebe um webhook por ativo com o resultado.
Lote: completed_assets_insertion
Ativo: pre_approved / denied
Webhook: asset_status_change
Ativo aprovado
pre_approved
O ativo foi pré-aprovado na elegibilidade.
Ativo reprovado
denied
O ativo não segue adiante no fluxo.
Webhook trade_receivables.asset_status_change — enviado para cada ativo com o resultado da elegibilidade.
Ver documentação de webhooks do ativo →

5b
Elegibilidade do Lote
QI Tech
Quando todos os ativos forem analisados, a QI Tech avalia a elegibilidade do lote como um todo.
Lote: pending_manager_approval / denied

Webhook: assignment_status_change
Lote elegível
pending_manager_approval
O lote aguarda a aprovação do gestor do fundo (passo 6).
Lote reprovado
denied
O lote causa desenquadramento do fundo. Fluxo encerrado.
Webhook trade_receivables.assignment_status_change — informa se o lote foi aprovado ou reprovado na elegibilidade.
Ver documentação de webhooks do lote →

6
Aprovação do Gestor
Gestor do Fundo
O gestor do fundo analisa e aprova ou reprova o lote (via API ou pelo Portal do Gestor). Se aprovado, o Termo de Cessão é gerado automaticamente.
Lote: pending_assignment_term_signature
Webhook: assignment_status_change
PUT /trade_receivables/.../assignment/{assignment_external_id}
Endpoint disponível somente para gestores. Envie {"assignment_status": "approved"} ou "denied" . Após aprovação, você recebe o webhook com status pending_assignment_term_signature .
Ver documentação completa →

7
Assinatura do Termo de Cessão
QI Tech
O Termo de Cessão é gerado e encaminhado para assinatura. Todas as partes relacionadas precisam assinar o termo para que o fluxo prossiga. O integrador pode consultar o documento a qualquer momento.
Lote: pending_payment
Webhook: assignment_status_change
GET /trade_receivables/.../assignment/{assignment_external_id}/assignment_term_link
Consulte o Termo de Cessão (original e assinado). Após todas as partes assinarem, você recebe o webhook com status pending_payment .
Ver documentação completa →

8
Pagamento ao Cedente
QI Tech
O pagamento é realizado automaticamente ao cedente na conta configurada durante a homologação.
Lote: pending_assets_wallet_inclusion
Webhook: assignment_status_change
O valor total é a soma dos total_purchase_value de todos os ativos não descartados. Após o pagamento, você recebe o webhook com status pending_assets_wallet_inclusion .

9
Encarteiramento
QI Tech
Os ativos são incluídos na carteira do fundo. A cessão está concluída.
Lote: completed
Ativo: completed
Webhook: assignment_status_change
Você recebe o webhook final com status completed . A partir desse momento, os ativos se encontram na carteira do fundo.
Ver documentação de webhooks →

---

## Resumo de webhooks

A tabela abaixo consolida todos os webhooks que o integrador recebe ao longo do fluxo, na ordem cronológica:

| # | Tipo do webhook | Status | Momento no fluxo | Ação esperada |
|---|---|---|---|---|
| 1 | `asset_creation` | `pending_eligibility` | Após inserção de cada ativo (passo 2) | Nenhuma — confirmação de recebimento. |
| 2 | `asset_status_change` | `pre_approved` | Ativo aprovado na elegibilidade (passo 5a) | Nenhuma — ativo pré-aprovado. |
| 3 | `asset_status_change` | `denied` | Ativo reprovado na elegibilidade (passo 5a) | Nenhuma — ativo não segue adiante. |
| 4 | `assignment_status_change` | `pending_manager_approval` | Lote aprovado na elegibilidade (passo 5b) | Aguardar [aprovação do gestor](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao). |
| 5 | `assignment_status_change` | `denied` | Lote reprovado na elegibilidade (passo 5b) | Nenhuma — fluxo encerrado. |
| 6 | `assignment_status_change` | `pending_assignment_term_signature` | Gestor aprovou o lote (passo 6) | Opcional: [consultar Termo de Cessão](/documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao). |
| 7 | `assignment_status_change` | `pending_payment` | Termo assinado por todas as partes (passo 7) | Nenhuma — pagamento em processamento. |
| 8 | `assignment_status_change` | `pending_assets_wallet_inclusion` | Pagamento realizado (passo 8) | Nenhuma — encarteiramento em processamento. |
| 9 | `assignment_status_change` | `completed` | Ativos encarteirados (passo 9) | Cessão concluída com sucesso. |
| — | `assignment_status_change` | `discarded` | Qualquer momento (reprovação/erro) | Nenhuma — lote descartado. |

:::info Prefixo dos webhooks
Todos os tipos de webhook possuem o prefixo `trade_receivables.`. Por exemplo: `trade_receivables.asset_creation` e `trade_receivables.assignment_status_change`. Para detalhes sobre a estrutura completa dos webhooks, consulte [Webhooks do Ativo](/documentation/iaas/negociacao_recebiveis/asset/webhooks) e [Webhooks do Lote](/documentation/iaas/negociacao_recebiveis/assignment/webhooks).
:::

---

# Cessão de Direitos Creditórios

URL: /documentation/iaas/negociacao_recebiveis/inicio

Esta seção documenta as APIs que viabilizam o processo de cessão de Direitos Creditórios para Fundos de Investimento administrados pela QI CTVM. O fluxo abrange desde a criação do lote de cessão até o encarteiramento dos ativos na carteira do fundo.

:::tip Manual completo
Para um entendimento aprofundado das regras de negócio e do produto, consulte o [Manual de Cessão de Direitos Creditórios](/documentation/iaas/negociacao_recebiveis/manual_api). Recomendamos a leitura em conjunto com as rotas aqui disponibilizadas.
:::

:::info Pré-requisitos
- Para ter acesso a esses serviços, entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) para liberação dos ambientes de Homologação (Sandbox) e Produção.
- Você precisará da `fund_class_key` (chave do fundo) e da `assignment_configuration_key` (chave da configuração de cessão), obtidas na [Homologação de Cedente](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato).
- Para consultar as configurações de cessão disponíveis, utilize o endpoint de [Listagem de Configurações de Cessão](/documentation/iaas/negociacao_recebiveis/listagem).
:::

## Como enviar a cessão

Existem dois caminhos, com o mesmo resultado final. Escolha um por lote — não é possível misturar os dois no mesmo lote.

| Caminho | Como funciona | Onde |
|---|---|---|
| **Pela API, ativo a ativo** | Criação do lote, uma requisição por ativo e encerramento da inserção. É o fluxo detalhado nesta seção | API de integração |
| **Por arquivo** | Um único arquivo com todos os ativos do lote: **CNAB 444** para duplicatas, contratos descontados e CT-e, ou **CSV** para CCB, honorários advocatícios e contratos parcelados | Portal do gestor/consultor |

:::tip Cessão de duplicatas por arquivo
Para duplicatas o formato é o **CNAB 444**; o CSV é aceito para operações de crédito (CCB), honorários advocatícios e contratos parcelados. Veja [Cessão por Arquivo](/documentation/iaas/negociacao_recebiveis/arquivo/inicio), o [Layout CNAB 444 — Cessão](/documentation/iaas/negociacao_recebiveis/arquivo/cnab444) e o [Layout CSV — Contratos Parcelados](/documentation/iaas/negociacao_recebiveis/arquivo/csv_contrato_parcelado), com exemplos prontos para download.
:::

## Fluxo de cessão

O diagrama abaixo mostra o caminho principal, as bifurcações e o status resultante de cada etapa. Passe o mouse em um nó para ver o endpoint e clique para abrir a documentação.

<FlowDiagram
  columns={3}
  nodes={[
    { id: 'criacao', row: 1, col: 2, actor: 'you', num: 1,
      title: 'Criação do Lote',
      status: 'pending_assets_insertion',
      desc: 'Contêiner de todos os ativos que serão cedidos ao fundo, identificado por um external_id único.',
      endpoint: { method: 'POST', path: '/trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment' },
      href: '/documentation/iaas/negociacao_recebiveis/assignment/criacao' },

    { id: 'ativos', row: 2, col: 2, actor: 'you', num: 2,
      title: 'Inserção dos Ativos',
      status: 'ativo: pending_eligibility',
      desc: 'Uma requisição por ativo, com as informações de operação, parcelas e dados do sacado.',
      endpoint: { method: 'POST', path: '.../assignment/{assignment_external_id}/asset' },
      href: '/documentation/iaas/negociacao_recebiveis/asset/criacao_co' },

    { id: 'documentos', row: 3, col: 2, actor: 'you', num: 3,
      title: 'Envio dos Documentos',
      desc: 'O ativo só prossegue na esteira depois que todos os documentos exigidos pelo produto são enviados.',
      endpoint: { method: 'POST', path: '.../asset/{asset_external_id}/document' },
      href: '/documentation/iaas/negociacao_recebiveis/asset/documents' },

    { id: 'fechamento', row: 4, col: 2, actor: 'you', num: 4,
      title: 'Encerramento da Inserção',
      status: 'completed_assets_insertion',
      desc: 'Sinaliza que todos os ativos foram inseridos e libera o lote para a análise de elegibilidade.',
      endpoint: { method: 'PUT', path: '.../assignment/{assignment_external_id}' },
      href: '/documentation/iaas/negociacao_recebiveis/assignment/fechamento' },

    { id: 'elegibilidade', row: 5, col: 2, actor: 'qitech',
      title: 'Elegibilidade dos ativos e do lote',
      desc: 'Cada ativo é analisado individualmente e, em seguida, o lote como um todo. Ativos reprovados não seguem no lote.',
      href: '/documentation/iaas/negociacao_recebiveis/asset/webhooks' },

    { id: 'reprovado', row: 6, col: 1, actor: 'qitech', tone: 'end',
      title: 'Reprovado',
      status: 'denied',
      desc: 'O ativo ou o lote não passou na elegibilidade, ou o gestor reprovou o lote. Fluxo encerrado.' },

    { id: 'aprovacao', row: 6, col: 2, actor: 'manager', tag: 'Condicional', num: 5,
      title: 'Aprovação do consultor e/ou gestor',
      status: 'pending_manager_approval',
      desc: 'Etapa manual apenas se a configuração de cessão exigir. Caso contrário a aprovação é automática e nenhuma ação é necessária.',
      endpoint: { method: 'PUT', path: '.../assignment/{assignment_external_id}' },
      href: '/documentation/iaas/negociacao_recebiveis/assignment/aprovacao' },

    { id: 'termo', row: 7, col: 2, actor: 'qitech',
      title: 'Termo de Cessão gerado e assinado',
      status: 'pending_assignment_term_signature',
      desc: 'Com o lote aprovado, o Termo de Cessão é gerado e assinado pelas partes.',
      href: '/documentation/iaas/negociacao_recebiveis/assignment/webhooks' },

    { id: 'pagamento', row: 8, col: 2, actor: 'qitech',
      title: 'Pagamento ao cedente',
      status: 'pending_payment',
      desc: 'O valor da cessão é repassado ao cedente.',
      href: '/documentation/iaas/negociacao_recebiveis/assignment/webhooks' },

    { id: 'encarteirado', row: 9, col: 2, actor: 'qitech', tone: 'ok',
      title: 'Ativos encarteirados no fundo',
      status: 'completed',
      desc: 'Os ativos entram na carteira do fundo e o ciclo do lote se encerra.',
      href: '/documentation/iaas/negociacao_recebiveis/assignment/webhooks' },
  ]}
  edges={[
    { from: 'criacao', to: 'ativos' },
    { from: 'ativos', to: 'documentos' },
    { from: 'documentos', to: 'fechamento' },
    { from: 'fechamento', to: 'elegibilidade' },
    { from: 'elegibilidade', to: 'reprovado', label: 'denied', tone: 'end' },
    { from: 'elegibilidade', to: 'aprovacao', label: 'pre_approved', tone: 'ok' },
    { from: 'elegibilidade', to: 'termo', label: 'automática', via: 'right', dashed: true },
    { from: 'aprovacao', to: 'reprovado', tone: 'end' },
    { from: 'aprovacao', to: 'termo', label: 'aprovou', tone: 'ok' },
    { from: 'termo', to: 'pagamento', label: 'webhook' },
    { from: 'pagamento', to: 'encarteirado', label: 'webhook' },
  ]}
/>

:::tip Fluxo completo
Para todas as transições de status, os payloads dos webhooks e os caminhos de exceção, consulte o [Fluxo de cessão](/documentation/iaas/negociacao_recebiveis/fluxo_cessao).
:::

## Passo a passo

### 1. Criação do Lote

Crie um lote de cessão informando um identificador único (`external_id`). O lote será o contêiner para todos os ativos que serão cedidos ao fundo.

**[Acessar documentação da criação do lote](/documentation/iaas/negociacao_recebiveis/assignment/criacao)**

### 2. Inserção dos Ativos

Adicione os ativos (CCBs, duplicatas, contratos parcelados, etc.) ao lote criado. Cada ativo deve ser inserido individualmente com suas informações de operação, parcelas e dados do sacado.

**[Acessar documentação da inserção de ativos](/documentation/iaas/negociacao_recebiveis/asset/criacao_co)**

### 3. Envio dos Documentos

Para cada ativo inserido, envie os documentos exigidos pelo produto (contrato, nota fiscal, etc.). O ativo só prossegue na esteira após todos os documentos exigidos serem enviados.

**[Acessar documentação do envio de documentos](/documentation/iaas/negociacao_recebiveis/asset/documents)**

### 4. Encerramento da Inserção

Sinalize que todos os ativos foram inseridos no lote. O sistema aguardará a análise individual de cada ativo antes de prosseguir com a elegibilidade do lote como um todo.

**[Acessar documentação do encerramento](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)**

### 5. Aprovação do Gestor

Após a elegibilidade do lote ser aprovada, o lote segue para aprovação. A depender da configuração de cessão, essa etapa é **manual** — o consultor e/ou o gestor do fundo analisam e aprovam ou reprovam o lote, e o lote fica em `pending_consultant_approval` / `pending_manager_approval` até a decisão — ou **automática**, sem nenhuma ação do integrador. Se aprovado, o Termo de Cessão será gerado automaticamente.

**[Acessar documentação da aprovação](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao)**

### 6. Assinatura, Pagamento e Encarteiramento

Os passos finais são automatizados: o Termo de Cessão é assinado pelas partes, o pagamento é realizado ao cedente e os ativos são encarteirados na carteira do fundo. Acompanhe o progresso através dos [webhooks do lote](/documentation/iaas/negociacao_recebiveis/assignment/webhooks).

## Lotes de substituição

O fluxo de substituição segue as mesmas etapas do fluxo de cessão, com um passo adicional: antes de inserir os ativos que serão comprados, é necessário inserir os ativos que serão **recomprados** pelo cedente.

1. Criação do lote
2. **Inserção dos ativos de recompra** — [Acessar documentação](/documentation/iaas/negociacao_recebiveis/asset/criacao_repurchased_asset)
3. Inserção dos ativos que serão comprados
4. Encerramento da inserção

---

# Listagem de Configurações de Cessão

URL: /documentation/iaas/negociacao_recebiveis/listagem

Endpoint de consulta paginada que retorna as configurações de cessão vinculadas a uma determinada classe de fundo. Cada configuração representa a relação entre um fundo cessionário e um cedente, incluindo regras de registro, tipo de ativo aceito e aprovação.

## Request

ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configurations
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID). |

### Query params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `assignment_contract_key` | string | opcional | Filtra por chave do contrato que originou a configuração (UUID). |
| `asset_type` | string | opcional | Filtra por tipo de ativo aceito na configuração (ex: `ccb`, `duplicata_mercantil`, `duplicata_servicos`). |
| `assignor_document_number` | string | opcional | Filtra por CPF/CNPJ do cedente. Deve ser enviado **com pontuação** (ex: `12.345.678/0001-90` ou `123.456.789-00`). |
| `page` | integer | opcional | Número da página (começa em 0). Padrão: `0`. |
| `limit` | integer | opcional | Quantidade de registros por página. Padrão: `10`. |

```python title="Exemplo de chamada"
GET /trade_receivables/fund_class/{fund_class_key}/assignment_configurations?asset_type=ccb&assignor_document_number=98.765.432/0001-10&page=0&limit=10
```

## Response

STATUS 200

```json title="Response Body"
{
  "data": [
    {
      "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
      "assignment_configuration_name": "Config CCB Fundo Alpha",
      "assignment_contract_key": "k1l2m3n4-o5p6-7890-abcd-ef1234567890",
      "registry_type": "internal_registry",
      "asset_type": "ccb",
      "fund_class": {
        "fund_class_key": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "name": "Fundo Alpha FIDC",
        "document_number": "12.345.678/0001-90",
        "accounting_date": "2024-04-01",
        "manager": {
          "manager_key": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
          "document_number": "11.222.333/0001-44",
          "manager_name": "Gestora Exemplo S.A."
        }
      },
      "assignor": {
        "assignor_key": "c1d2e3f4-a5b6-7890-abcd-ef1234567890",
        "document_number": "98.765.432/0001-10",
        "name": "Cedente Exemplo Ltda"
      },
      "consultant_decision_type": "manual_approval",
      "consultant": {
        "consultant_key": "g1h2i3j4-k5l6-7890-abcd-ef1234567890",
        "document_number": "55.666.777/0001-88",
        "name": "Consultoria Exemplo Ltda"
      }
    }
  ],
  "limit": 10,
  "page": 0,
  "is_last_page": true
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Lista de objetos de configuração de cessão. Veja tabela abaixo. |
| `page` | integer | Número da página atual. |
| `limit` | integer | Quantidade de registros por página. |
| `is_last_page` | boolean | Indica se esta é a última página de resultados. |

#### Atributos de cada configuração (objetos dentro de `data`)

| Campo | Tipo | Descrição |
|---|---|---|
| `assignment_configuration_key` | string | Identificador único da configuração de cessão (UUID). |
| `assignment_configuration_name` | string | Nome da configuração de cessão. |
| `assignment_contract_key` | string | Chave do contrato de cessão que originou esta configuração (UUID). |
| `registry_type` | string | Tipo de registro dos ativos. Valores possíveis: `internal_registry`, `external_registry`. |
| `asset_type` | string | Tipo de ativo aceito nesta configuração. Valores possíveis: `ccb`, `duplicata_mercantil`, `duplicata_servico`. |
| `consultant_decision_type` | string | Tipo de decisão do consultor sobre a elegibilidade. Valores possíveis: `automatic_approval`, `manual_approval`. |
| `fund_class` | object | Dados do fundo cessionário. Consulte os [atributos de `fund_class`](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao#atributos-de-fund_class) na página de Recuperação. |
| `assignor` | object | Dados do cedente. Consulte os [atributos de `assignor`](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao#atributos-de-assignor) na página de Recuperação. |
| `consultant` | object | Dados do consultor vinculado à configuração. Consulte os [atributos de `consultant`](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao#atributos-de-consultant) na página de Recuperação. |
| `required_documents` | array | Tipos de documento exigidos **antes** da cessão, enviados pelo [endpoint de documentos](/documentation/iaas/negociacao_recebiveis/asset/documents) enquanto o ativo está em `pending_documentation`. Lista vazia quando o produto não exige nenhum. |
| `after_assignment_required_documents` | array | Tipos de documento exigidos **depois** da cessão, enviados pelo mesmo endpoint enquanto o ativo está em `pending_after_assignment_documentation`. Lista vazia quando o produto não exige nenhum. |

---

# Manual de Cessão de Direitos Creditórios

URL: /documentation/iaas/negociacao_recebiveis/manual_api

Esse manual descreve o passo a passo envolvido na Cessão de Direitos Creditórios aos Fundos administrados pela QI CTVM. Além disso, é explicados as regras de negócio do produto e quais os principais pontos de atenção que o parceiro integrador deve ter para se ter uma integração mais rápida e eficiente.

## Pré Requisitos

1. Um Contrato de Cessão ter sido constituído e o Produto respectivo ter sido ativado (Vide APIs de **[Homologação de Cedente](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato)**);

2. Somente o Gestor do Fundo, o Cedente parte do Contrato e Originadores vinculados que podem acessar esse serviço.

3. Ter armazenado a chave única de identificação do Fundo Cessionário ( fund_class_key ), e a chave única de identificação da Configuração de Cessão ( assignment_configuration_key ).

```python
BASE_URL = "/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}"
```

:::info
A _**BASE_URL**_ será o caminho utilizado em todos os endpoints desta API.
:::

## Fluxo de Estados

A esteira de Cessão possui duas entidades principais onde as suas máquinas de estados possuem relações. De um lado temos o Lote, denominado assignment e de outro temos os Ativos, que chamamos de asset . Para o primeiro temos o seguinte fluxo:

![Fluxo de estados do Lote (assignment)](/img/diagrams/iaas-negociacao-recebiveis-manual-api-1.svg)

Para o Ativo, temos o seguinte:

![Fluxo de estados do Ativo (asset)](/img/diagrams/iaas-negociacao-recebiveis-manual-api-2.svg)

## Resumo da Integração

Em suma, para chegarmos no Encarteiramento dos Ativos, temos o seguinte passo a passo:

1. Criação do Lote;
2. Inserção dos Ativos;
3. Encerrar inserção de Ativos;
4. Webhook de Elegibilidade dos Ativos;
6. Envio da Documentação ;
7. Webhook de Elegiblidade do Lote;
8. Aprovação do Gestor;
9. Assinatura do Termo de Cessão;
10. Pagamento da Cessão;
11. Encarteiramento dos Ativos;

## 1 - Criação do Lote;

Para a **[criação do Lote](/documentation/iaas/negociacao_recebiveis/assignment/criacao)** é exigido apenas um identificador único, gerado no sistema do parceiro integrador. Esse será o identificador utilizado tanto nas devoluções de Webhooks quanto nas rotas para as outras funcionalidades, que serão explicadas abaixo.

É de suma importância que esse identificador seja único, e o sistema da QI CTVM não permitirá que o parceiro mande duas vezes o mesmo Lote.

## 2 - Inserção dos Ativos;

A inserção de Ativos é o processo mais delicado de toda a integração. Nessa seção iremos explicar quais as regras de negócio envolvidas na criação dos Ativos, sejam aquelas que independem do tipo, ou aquelas que são específicas para um determinado tipo.

É muito importante para o entendimento dessa API, entender o conceito do Valor do Ativo e do Valor de Compra do Ativo. Para isso vamos utilizar a seguinte notação:

**[A]** como Valor de Compra do Ativo, fornecido no raiz do objeto, e significa o quanto o Fundo deve pagar por esse Ativo.

**[B]** como a soma total do Ágios da operação. Pode ser obtido através da soma de todos os total_values dos premiums fornecidos.

**[C]** como a soma total do Deságios da operação. Pode ser obtido através da soma de todos os total_values das deductions fornecidas.

**[D]** como o Valor do Ativo, que pode ser inferido através da seguinte fórmula.

:::tip Relação
[D] = [A] - [B] + [C]
:::

### 2.1 - Regras Independentes de Tipo de Ativo

#### 2.1.1 - Compatibilidade de Tipo de Ativo com Configuração de Cessão;

Toda Configuração de Cessão é única por tipo de ativo. Nunca será possível colocar num mesmo lote CCBs e e Duplicatas por exemplo. O produto ativado que gerou a assignment_configuration_key contém um tipo de ativo especifico, e esse será o único tipo aceito em uma dada Configuração.
Caso isso seja violado retornaremos o seguinte erro:

Response Body
STATUS 400

```json title='Response Body'
{
    "code": "TRC000025"
}
```

#### 2.1.2 - Inserção em Lotes Finalizados;

Caso tente-se inserir um ativo em lotes que já foram fechados, o parceiro integrador receberá o seguinte erro:

Response Body
STATUS 400

```json title='Response Body'
{
    "code": "TRC000022"
}
```

#### 2.1.3 - Validação de Código Postal;

O código postal do objeto de endereço do tomador da operação deve ser válido. Portanto caso algum inexistente seja fornecido, a requisição não será aceita e devolverá o seguinte erro:

Response Body
STATUS 404

```json title='Response Body'
{
    "code": "TRC000070"
}
```

#### 2.1.4 - Unicidade de External ID;

Um mesmo ativo não pode ser cedido 2 vezes pelo parceiro. Portanto caso esse ativo já exista em nossa base e não tenha sido descartado, o seguinte erro será levantado:

Response Body
STATUS 409

```json title='Response Body'
{
    "code": "TRC000054"
}
```

### 2.2 - Regras para Operações de Crédito

As Operações de Crédito são aquele ativos que derivam de um compromisso firmado por um Sacado, que toma dinheiro a uma determinada taxa, e honra um compromisso de pagamento de acordo com um determinado fluxo. Portanto esses ativos sempre possuem um principal em aberto, e uma taxa de juros que aumenta esse valor. A estrutura de dados exigida na Criação de uma Operação de Crédito encontra **[nesta página](/documentation/iaas/negociacao_recebiveis/asset/criacao_co)**.

#### 2.2.1 - Divergência Valor do Ativo vs Principal em Aberto;

Para uma Operação de Crédito é necessário que o Valor do Ativo seja sempre maior ou igual ao Principal em Aberto (Campo principal_value do Objeto de Operação de Crédito). O erro relacionado a essa regra de negócio é:

Response Body
STATUS 409

```json title='Response Body'
{
    "code": "TRC000054"
}
```

#### 2.2.2 - Divergência Valor de Emissão vs Principal em Aberto;

O valor de Emissão do Contrato deve ser sempre maior ou igual ao principal em Aberto. O erro relacionado a essa regra de negócio é:

Response Body
STATUS 409

```json title='Response Body'
{
    "code": "TRC000054"
}
```

#### 2.2.3 - Parcelas Sequenciais;

Todas as parcelas de uma operação de crédito devem ser ordenadas em ordem crescente de data de vencimento ( maturity_date ) e com os números ( installment_number ) sequenciais. Portanto se o fluxo começa com a parcela número 1, a próxima deve ser a 2, a seguinte a 3, e assim por diante.

Os erros relacionados a essas regras são respectivamente:

Response Body
STATUS 409

```json title='Response Body'
{
    "code": "TRC000054"
}
```

Response Body
STATUS 409

```json title='Response Body'
{
    "code": "TRC000054"
}
```

#### 2.2.4 - Objetos pré e pós fixados;

De acordo com o tipo de juros ( interest_rate_type ) de uma operação, é preciso fornecer os objetos de pré e/ou pós fixados. Caso o tipo de juros seja pré fixado, é necessário fornecer **apenas** o objeto de pré fixado, enquanto na pós fixada, o objeto de pós fixado é **obrigatório** e o de pré fixado é **opcional**.

<!-- #### 2.2.5 - Fluxo de Pagamentos de Operações Pré Fixadas;
DEVEM EXISTIR APENAS O VALOR DE FACE
VP TEM QUE BATER VALOR DO ATIVO
#### 2.2.5 - Fluxo de Pagamentos de Operações Pós Fixadas;
DEVEM EXISTIR SEMPRE O VALOR DE PRINCIPAL;
TAMBÉM DEVE EXISTIR O VALOR DE FACE PRA VENCIDAS;
PRINCIPAL TOTAL == PRINCIAPL EM ABERTA -->

## 3 - Encerrar inserção de Ativos;

Após todos os ativos do Lote terem sido criados, o parceiro pode comandar o **[encerramento da Inserção de Ativos](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)**. Esse processo é importante para que o sistema da QI CTVM saiba que a partir desse momento, quando todos os ativos tiverem sido devidamente analisados pela Elegibilidade, e com toda a documentação fornecida, pode-se analisar a Elegibilidade do Lote como um todo.

:::info
Não é necessário esperar o Webhook de todos os Ativos para realizar essa ação. No momento em que não se desejar mais inserir ativos, pode-se executar esse comando.
:::

## 4 - Webhook de Elegibilidade dos Ativos;

De acordo com o que os Ativos forem sendo analisados pelas regras de Elegibilidade do Fundo, o sistema devolve os **[Webhooks](/documentation/iaas/negociacao_recebiveis/asset/webhooks)**, 1 a 1. Esses Webhooks serão identificados com o identificador único do ativo, fornecido pelo parceiro no momento de criação.

Apenas duas possibilidades podem incorrer dessa análise, a **aprovação** dos ativos, ou a **reprovação**. Caso aconteça o primeiro, o Ativo irá seguir a sua esteira, ficando sujeito a inserção de documentos, caso contrário, ele irá para o Estado de descartado, e não irá seguir para os próximos passos.

## 5 - Envio da Documentação;

Com a aprovação de um determinado ativo na Elegibilidade, o parceiro pode seguir com a **[inserção dos documentos](/documentation/iaas/negociacao_recebiveis/asset/documents)** exigidos pelo produto. O envio deve ocorrer com uma requisição para cada documento necessário. O conteúdo será transmitido através de um Base64 do binário, portanto viabilizando que isso seja feito através de JSON, como todo o restante das APIs do nosso sistema.

Note que para realizar essa requisição é exigido, além do binário do arquivo, o tipo de documento desse arquivo. O Ativo só seguirá a esteira quando todos os documento exigidos forem enviados. Quando isso acontecer, este irá seguir para o estado de Pré Aprovado ( pre_approved ).

:::warning Aviso
Os documentos exigidos dependem do tipo de Produto e do Regulamento do Fundo. Isso pode ser obtido recuperando o Produto do Contrato de Cessão, que foi ativado para obtenção da assignment_configuration_key desse respectivo lote.
::: 

:::info
Não é necessário ter comandado o Encerramento da Inserção de Ativos. Caso queira vincular a lógica do Envio de Documentos ao Recebimento do Webhook, é totalmente possível e recomendado.
:::

## 6 - Webhook de Elegiblidade do Lote;

Assim que um determinado Lote que ja teve a inserção de ativos encerrada, e todos os seus Ativos tiverem ou descartado ou pré-aprovados, ele irá seguir para uma análise de Elegibilidade do Lote todo. Mesmo que todos os Ativos ali tenha sido aprovados, pode ser que o Lote como um todo cause algum desenquadramento do Fundo. Por isso é necessário um segundo passo na execução da Elegibilidade.

De forma similar ao Ativo, podemos ter duas opções de resultado decorrido da Elegibilidade, a aprovação ou a reprovação. O resultado será informado através de um **[Webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks)**, mas dessa vez identificado com o external_id do Lote.

Caso o Lote seja reprovado, ele será descartado, e o processo finaliza-se. Caso contrário, ele seguirá para uma etapa de análise e aprovação do Gestor.

## 7 - Aprovação do Gestor;

A aprovação do Gestor deve ser feita através de uma **[requisição especifica](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao)**, ou através do nosso **[Portal](https://portal-do-gestor.fundos.qitech.com.br/)**. Caso o Lote seja negado, ele será descartado e o processo finaliza-se. Caso contrário, o sistema providencia a geração do Termo de Cessão e o envia para assinatura, levando o Lote para o Estado pending_assignment_term_signature , e assim ficará ate que todas as partes relacionadas assinem o Documento.

## 8 - Assinatura do Termo de Cessão;

Uma vez assinado, enviamos um **[Webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks)** avisando que o Termo foi assinado e deve prosseguir para o pagamento, ficando, portanto, em pending_payment

## 9 - Pagamento da Cessão;

Nesse momento, o sistema paga o Cedente, o montante total da Cessão, que é a soma de todos os total_purchase_value dos ativos não descartados, na conta que foi informada no momento de ativação do Produto. Uma vez que esse pagamento for confirmado, enviamos um **[Webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks)**, e os ativos começam a serem encarteirados.

## 10 - Encarteiramento dos Ativos;

Por fim, assim que todos os ativos forem devidamente encarteirados, o Lote se tornará completed , e a partir desse momento o parceiro integrador tem a total certeza de que todos aqueles ativos já se encontram devidamente dentro do estoque do Fundo.

---

# Listagem de Solicitações de Amortização

URL: /documentation/iaas/passivo/amortizacao/listagem

Endpoint de consulta paginada que retorna as solicitações de amortização de uma determinada classe de fundo. A resposta inclui, para cada solicitação, os dados financeiros calculados, o histórico de status, as amortizações por investidor e os dados da série de emissão vinculada.

:::info Filtros de retorno
Por padrão, todos os sub-objetos (`issuance_serie`, `investor_amortizations` e `status_events`) são retornados. Utilize os query params `dto_filters_*` para omitir campos e reduzir o tamanho da resposta.
:::

## Request

ENDPOINT /quota/fund_class/{fund_class_key}/amortization_requests
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única da classe de fundo (UUID). |

### Query params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `page` | integer | opcional | Número da página (começa em 0). Padrão: `0`. |
| `limit` | integer | opcional | Quantidade de registros por página. Padrão: `20`. Máximo: `100`. |
| `dto_filters_issuance_serie` | boolean | opcional | Quando `true`, omite o objeto `issuance_serie` de cada item. Padrão: `false`. |
| `dto_filters_investor_amortizations` | boolean | opcional | Quando `true`, omite o array `investor_amortizations` de cada item. Padrão: `false`. |
| `dto_filters_status_events` | boolean | opcional | Quando `true`, omite o array `status_events` de cada item. Padrão: `false`. |

```python title="Exemplo de chamada"
GET /quota/fund_class/{fund_class_key}/amortization_requests?page=0&limit=20
```

## Response

STATUS 200

```json title="Response Body"
{
  "data": [
    {
      "amortization_request_key": "3571e292-3a83-4011-904d-20ee963022ef",
      "type": "scheduled_amortization",
      "regime_type": "issuance_serie_principal_percentage",
      "quotation_date": "2026-06-05",
      "principal_percentage": 0.5,
      "financial_application_yield_percentage": 0.12,
      "gross_value": 10000.0,
      "result_quota_value": 1.05,
      "amortization_value": 5000.0,
      "net_value": 4750.0,
      "quota_percentage": 0.5,
      "status": "done",
      "status_events": [
        {
          "status": "created",
          "event_datetime": "2026-06-01T10:00:00.000Z"
        },
        {
          "status": "done",
          "event_datetime": "2026-06-05T14:30:00.000Z"
        }
      ],
      "investor_amortizations": [
        {
          "investor_amortization_key": "f1e2d3c4-b5a6-7890-fedc-ba9876543210",
          "investor": {
            "investor_key": "aaaa1111-bbbb-2222-cccc-dddd33334444",
            "name": "Investidor Exemplo S.A.",
            "person_type": "legal",
            "document_number": "12.345.678/0001-99",
            "distributor": {
              "distributor_key": "dddd4444-eeee-5555-ffff-aaaa66667777",
              "name": "Distribuidora Exemplo",
              "document_number": "98.765.432/0001-11",
              "account_data": {
                "bank": "341",
                "agency": "1234",
                "account": "56789-0"
              }
            }
          },
          "status": "done",
          "net_value": 4750.0,
          "ir_value": 200.0,
          "iof_value": 50.0,
          "ir_compensation": 0.0,
          "iof_compensation": 0.0,
          "total_value": 5000.0,
          "payment_method": "regular",
          "payment_date": "2026-06-06",
          "status_events": [
            {
              "status": "created",
              "event_datetime": "2026-06-01T10:00:00.000Z"
            },
            {
              "status": "done",
              "event_datetime": "2026-06-06T09:00:00.000Z"
            }
          ],
          "amortizations": [
            {
              "financial_application_key": "fa111111-2222-3333-4444-555566667777",
              "amortization_key": "am888888-9999-aaaa-bbbb-ccccddddeeee",
              "status": "settled",
              "principal_reduction": 2500.0,
              "acquisition_cost_reduction": 0.0,
              "yield_value": 300.0,
              "total_value": 2800.0,
              "ir_value": 100.0,
              "iof_value": 25.0,
              "taxable_yield_value": 300.0
            }
          ],
          "payments": [
            {
              "payment_key": "pp000000-1111-2222-3333-444455556666",
              "origin_key": "f1e2d3c4-b5a6-7890-fedc-ba9876543210",
              "total_value": 4750.0,
              "target_account": {
                "bank": "341",
                "agency": "1234",
                "account": "56789-0"
              },
              "payment_type": "amortization_payment.investor",
              "payment_date": "2026-06-06",
              "status": "paid",
              "status_events": [
                {
                  "status": "paid",
                  "event_datetime": "2026-06-06T09:15:00.000Z"
                }
              ]
            }
          ]
        }
      ],
      "issuance_serie": {
        "issuance_serie_key": "is111111-2222-3333-4444-555566667777",
        "name": "Série A - Cota Sênior",
        "serie": 1,
        "original_quota_value": 1.0,
        "current_quota_value": 1.05,
        "current_number_of_quotas": 1000000.0,
        "current_net_worth": 1050000.0,
        "current_principal_value": 1000000.0,
        "performance_fee_current_value": 0.0,
        "remuneration_type": "cdi_plus",
        "minimum_share_capital": 1000.0,
        "status": "active",
        "internal_code": "SR-001",
        "processing_method": "pro_rata",
        "operation_period_configuration": {
          "subscription_days": [1, 2, 3, 4, 5],
          "redemption_days": [1, 2, 3, 4, 5]
        },
        "sub_class": {
          "sub_class_key": "sc222222-3333-4444-5555-666677778888",
          "name": "Classe Sênior",
          "subordination_level": 1,
          "fund_class": {
            "fund_class_key": "fc333333-4444-5555-6666-777788889999",
            "name": "Fundo de Investimento em Direitos Creditórios Exemplo",
            "short_name": "FIDC Exemplo",
            "document_number": "11.222.333/0001-44",
            "accounting_date": "2026-06-09",
            "sub_type": "exclusive",
            "tax_classification": "long_term",
            "condominum_type": "closed",
            "investment_category": "credit_rights",
            "prevent_payment": false,
            "manager": {
              "manager_key": "mg444444-5555-6666-7777-888899990000",
              "name": "Gestora Exemplo DTVM",
              "document_number": "55.666.777/0001-88"
            }
          }
        }
      }
    }
  ],
  "limit": 20,
  "page": 0,
  "is_last_page": true
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Lista de solicitações de amortização. Veja tabela abaixo. |
| `page` | integer | Número da página atual. |
| `limit` | integer | Quantidade de registros por página. |
| `is_last_page` | boolean | Indica se esta é a última página de resultados. |

#### Atributos de cada solicitação (objetos dentro de `data`)

| Campo | Tipo | Descrição |
|---|---|---|
| `amortization_request_key` | string | Identificador único da solicitação (UUID). |
| `type` | string | Tipo da amortização. Consulte os [enumeradores de tipo](#enumeradores-de-type) abaixo. |
| `regime_type` | string | Regime de cálculo da amortização. Consulte os [enumeradores de regime](#enumeradores-de-regime_type) abaixo. |
| `quotation_date` | string | Data de cotação no formato `YYYY-MM-DD`. |
| `principal_percentage` | number | Percentual do principal a ser amortizado. Presente conforme o `regime_type`. |
| `financial_application_yield_percentage` | number | Percentual de rendimento da aplicação financeira. Presente conforme o `regime_type`. |
| `gross_value` | number | Valor bruto total da amortização em reais. |
| `result_quota_value` | number | Valor da cota resultante após a amortização. |
| `amortization_value` | number | Valor total a ser amortizado em reais. |
| `net_value` | number | Valor líquido total após impostos em reais. |
| `quota_percentage` | number | Percentual de cotas resgatadas. Presente conforme o `regime_type`. |
| `status` | string | Status atual da solicitação. Consulte os [enumeradores de status](#enumeradores-de-status) abaixo. |
| `status_events` | array | Histórico de transições de status. Omitido se `dto_filters_status_events=true`. Veja tabela abaixo. |
| `investor_amortizations` | array | Lista de amortizações individuais por investidor. Omitido se `dto_filters_investor_amortizations=true`. Veja tabela abaixo. |
| `issuance_serie` | object | Dados da série de emissão vinculada. Omitido se `dto_filters_issuance_serie=true`. Veja tabela abaixo. |

#### Atributos de `status_events`

| Campo | Tipo | Descrição |
|---|---|---|
| `status` | string | Status do evento. |
| `event_datetime` | string | Data e hora do evento no formato ISO 8601 (ex: `2026-06-01T10:00:00.000Z`). |

#### Atributos de `investor_amortizations`

| Campo | Tipo | Descrição |
|---|---|---|
| `investor_amortization_key` | string | Identificador único da amortização do investidor (UUID). |
| `investor` | object | Dados do investidor. Veja tabela abaixo. |
| `status` | string | Status da amortização do investidor. Consulte os [enumeradores de status do investidor](#enumeradores-de-status-do-investor_amortization) abaixo. |
| `net_value` | number | Valor líquido a pagar ao investidor em reais. |
| `ir_value` | number | Valor de IR retido em reais. |
| `iof_value` | number | Valor de IOF retido em reais. |
| `ir_compensation` | number | Compensação de IR em reais. |
| `iof_compensation` | number | Compensação de IOF em reais. |
| `total_value` | number | Valor total bruto em reais. Presente após o cálculo. |
| `payment_method` | string | Método de pagamento. Consulte os [enumeradores de método de pagamento](#enumeradores-de-payment_method) abaixo. |
| `payment_date` | string | Data prevista do pagamento no formato `YYYY-MM-DD`. |
| `status_events` | array | Histórico de transições de status do investidor. Mesma estrutura de `status_events` da solicitação. |
| `amortizations` | array | Detalhamento por aplicação financeira. Veja tabela abaixo. |
| `payments` | array | Lista de pagamentos gerados. Veja tabela abaixo. |

#### Atributos de `investor`

| Campo | Tipo | Descrição |
|---|---|---|
| `investor_key` | string | Chave única do investidor (UUID). |
| `name` | string | Nome do investidor. |
| `person_type` | string | Tipo de pessoa (`natural` ou `legal`). |
| `document_number` | string | CPF ou CNPJ do investidor. Presente quando disponível. |
| `external_id` | string | Identificador externo do investidor. Presente quando informado. |
| `external_distribution_key` | string | Chave de distribuição externa. Presente quando informada. |
| `short_name` | string | Nome abreviado. Presente quando informado. |
| `sub_type` | string | Subtipo do investidor. Presente quando informado. |
| `distributor` | object | Dados da distribuidora vinculada. Veja tabela abaixo. |

#### Atributos de `distributor`

| Campo | Tipo | Descrição |
|---|---|---|
| `distributor_key` | string | Chave única da distribuidora (UUID). |
| `name` | string | Nome da distribuidora. |
| `document_number` | string | CNPJ da distribuidora. |
| `account_data` | object | Dados bancários da distribuidora. |

#### Atributos de `amortizations` {#amortizations}

| Campo | Tipo | Descrição |
|---|---|---|
| `financial_application_key` | string | Chave da aplicação financeira (UUID). |
| `amortization_key` | string | Chave única da amortização (UUID). |
| `status` | string | Status da amortização. |
| `principal_reduction` | number | Redução de principal em reais. |
| `acquisition_cost_reduction` | number | Redução de custo de aquisição em reais. |
| `yield_value` | number | Valor de rendimento em reais. Presente quando calculado. |
| `total_value` | number | Valor total em reais. Presente quando calculado. |
| `ir_value` | number | Valor de IR em reais. Presente quando calculado. |
| `iof_value` | number | Valor de IOF em reais. Presente quando calculado. |
| `taxable_yield_value` | number | Valor de rendimento tributável em reais. Presente quando calculado. |

#### Atributos de `payments`

| Campo | Tipo | Descrição |
|---|---|---|
| `payment_key` | string | Chave única do pagamento (UUID). |
| `origin_key` | string | Chave da origem do pagamento (UUID). |
| `total_value` | number | Valor total do pagamento em reais. |
| `target_account` | object | Dados da conta de destino. |
| `description` | string | Descrição do pagamento. Presente quando informada. |
| `payment_type` | string | Tipo do pagamento. Consulte os [enumeradores de tipo de pagamento](#enumeradores-de-payment_type) abaixo. |
| `payment_date` | string | Data do pagamento no formato `YYYY-MM-DD`. |
| `status` | string | Status do pagamento. Consulte os [enumeradores de status do pagamento](#enumeradores-de-status-do-payment) abaixo. |
| `deleted_at` | string | Data e hora de exclusão no formato ISO 8601. Presente apenas quando o pagamento foi cancelado. |
| `status_events` | array | Histórico de transições de status do pagamento. Mesma estrutura de `status_events` da solicitação. |

#### Atributos de `issuance_serie`

| Campo | Tipo | Descrição |
|---|---|---|
| `issuance_serie_key` | string | Chave única da série de emissão (UUID). |
| `name` | string | Nome da série de emissão. |
| `serie` | integer | Número da série. |
| `original_quota_value` | number | Valor original da cota em reais. |
| `current_quota_value` | number | Valor atual da cota em reais (calculado como `current_net_worth / current_number_of_quotas`). |
| `current_number_of_quotas` | number | Quantidade atual de cotas em circulação. |
| `current_net_worth` | number | Patrimônio líquido atual em reais. |
| `current_principal_value` | number | Valor de principal atual em reais. |
| `performance_fee_current_value` | number | Valor atual de taxa de performance em reais. |
| `remuneration_type` | string | Tipo de remuneração da série. |
| `minimum_share_capital` | number | Capital mínimo em reais. |
| `status` | string | Status da série de emissão. |
| `internal_code` | string | Código interno da série. |
| `processing_method` | string | Método de processamento (ex: `pro_rata`). |
| `operation_period_configuration` | object | Configuração de períodos operacionais da série. |
| `pre_fixed` | number | Taxa pré-fixada. Presente quando aplicável. |
| `post_fixed` | object | Dados do indexador pós-fixado. Presente quando aplicável. |
| `interest_rate_type` | string | Tipo de taxa de juros. Presente quando aplicável. |
| `isin_code` | string | Código ISIN da série. Presente quando informado. |
| `external_id` | string | Identificador externo. Presente quando informado. |
| `specific_interest_rate_data` | object | Dados específicos de taxa de juros. Presente quando aplicável. |
| `fixed_principal_value` | number | Valor de principal fixo. Presente quando aplicável. |
| `sub_class` | object | Dados da subclasse vinculada. Veja tabela abaixo. |

#### Atributos de `sub_class`

| Campo | Tipo | Descrição |
|---|---|---|
| `sub_class_key` | string | Chave única da subclasse (UUID). |
| `name` | string | Nome da subclasse. |
| `subordination_level` | integer | Nível de subordinação da subclasse. |
| `fund_class` | object | Dados da classe de fundo. Veja tabela abaixo. |

#### Atributos de `fund_class`

| Campo | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única da classe de fundo (UUID). |
| `name` | string | Nome do fundo. |
| `short_name` | string | Nome abreviado do fundo. |
| `document_number` | string | CNPJ do fundo. |
| `accounting_date` | string | Data contábil vigente no formato `YYYY-MM-DD`. |
| `sub_type` | string | Subtipo do fundo. |
| `tax_classification` | string | Classificação tributária do fundo. |
| `condominum_type` | string | Tipo de condomínio do fundo. |
| `investment_category` | string | Categoria de investimento. |
| `prevent_payment` | boolean | Indica se pagamentos estão bloqueados para o fundo. |
| `manager` | object | Dados do gestor do fundo. |
| `administrator` | object | Dados do administrador. Presente quando informado. |
| `integralization_account_key` | string | Chave da conta de integralização (UUID). Presente quando informada. |

## Enumeradores de `type`

| Valor | Descrição |
|---|---|
| `scheduled_amortization` | Amortização programada/agendada |
| `extraordinary_amortization` | Amortização extraordinária |

## Enumeradores de `regime_type`

| Valor | Descrição |
|---|---|
| `cash_availability` | Baseado na disponibilidade de caixa |
| `issuance_serie_principal_percentage` | Percentual do principal da série de emissão |
| `quota_percentage` | Percentual de cotas |
| `financial_application_principal_percentage` | Percentual do principal da aplicação financeira |
| `net_value` | Valor líquido fixo |
| `gross_value` | Valor bruto fixo |
| `financial_application_yield_percentage` | Percentual de rendimento da aplicação financeira |

## Enumeradores de `status`

| Status | Descrição |
|---|---|
| `created` | Solicitação criada |
| `waiting_quotation_date` | Aguardando data de cotação |
| `pending_inputs` | Aguardando dados de entrada |
| `processing_calculation` | Cálculo em processamento |
| `processing_investor_amortizations` | Processando amortizações dos investidores |
| `pending_manual_approval` | Aguardando aprovação manual |
| `processing_approval` | Aprovação em processamento |
| `processing_issuance_serie_impacts` | Processando impactos na série de emissão |
| `reprocessed` | Reprocessada |
| `reproved` | Reprovada |
| `done` | Concluída |

## Enumeradores de status do `investor_amortization`

| Status | Descrição |
|---|---|
| `created` | Amortização do investidor criada |
| `pending_quote` | Aguardando cotação |
| `processing_approval` | Aprovação em processamento |
| `pending_manual_approval` | Aguardando aprovação manual |
| `done` | Concluída |
| `reproved` | Reprovada |

## Enumeradores de `payment_method`

| Valor | Descrição |
|---|---|
| `regular` | Pagamento padrão (TED/PIX) |
| `b3` | Pagamento via B3 |

## Enumeradores de `payment_type`

| Valor | Descrição |
|---|---|
| `amortization_payment.investor` | Pagamento de amortização ao investidor |
| `amortization_payment.ir` | Recolhimento de IR da amortização |
| `amortization_payment.iof` | Recolhimento de IOF da amortização |
| `amortization_payment.collateral` | Pagamento de garantia da amortização |
| `redemption.investor` | Pagamento de resgate ao investidor |
| `redemption.ir` | Recolhimento de IR do resgate |
| `redemption.iof` | Recolhimento de IOF do resgate |
| `redemption.integralization_iof` | Recolhimento de IOF de integralização do resgate |
| `redemption.tax_anticipation` | Antecipação de tributos do resgate |

## Enumeradores de status do `payment`

| Status | Descrição |
|---|---|
| `created` | Pagamento criado |
| `pending_payment` | Aguardando pagamento |
| `pending_manual_approval` | Aguardando aprovação manual |
| `pending_confirmation` | Aguardando confirmação |
| `pending_accounting_date` | Aguardando data contábil |
| `paid` | Pago |
| `canceled` | Cancelado |

---

# Consulta paginada de Aplicação Financeira

URL: /documentation/iaas/passivo/aplicacao_financeira/busca_paginada_aplicacoes_financeiras

---

### Requests

Requisição por cotista: este endpoint retornará todas as aplicações financeiras de um cotista
ENDPOINT /quota/investor/INVESTOR_KEY/financial_applications
MÉTODO GET
STATUS 200
Requisição por fundo: este endpoint retornará todas as aplicações financeiras de um fundo
ENDPOINT /quota/fund_class/FUND_CLASS_KEY/financial_applications
MÉTODO GET
STATUS 200

### Query Params

| Parâmetro        | Descrição                                                                            |
|------------------|--------------------------------------------------------------------------------------|
| `quotation_date` | Data de cotização das aplicações                                                     |
| `status`         | Lista de **[Financial Application Status](#financial_application_status)** desejados |
| `application_from_datetime` | Retorna apenas as aplicações com data/hora de aplicação maior ou igual ao valor informado. |
| `application_to_datetime` | Retorna apenas as aplicações com data/hora de aplicação menor ou igual ao valor informado. |
| `issuance_serie_key` | Filtra as aplicações por série de emissão                                        |
| `types`          | Lista de tipos de aplicação desejados (ex.: primary_market, secondary_market)        |
| `fund_class_document_number` | Filtra por CNPJ da classe de fundo _(somente na consulta por cotista)_   |
| `manager_key`    | Filtra pelo gestor _(somente na consulta por cotista)_                                |
| `investor_name`  | Filtra pelo nome do investidor _(somente na consulta por fundo)_                      |
| `investor_document_number` | Filtra pelo CPF/CNPJ do investidor _(somente na consulta por fundo)_       |

### Responses

Caso 01: Consulta bem-sucedida

```json
{
    "data": [
        {
        "external_id": "",
        "financial_application_key": "UUID",
        "share_capital": 0.00,
        "investor_position": {
            "investor": {
                "investor_key": "UUID",
                "document_number": "999.999.999-99" | "99.999.999/9999-99",
                "name": "",
                "person_type": "natural_person" | "legal_person",
                "account_data": {
                    "owner": {
                        "name": "",
                        "document_number": "99.999.999/9999-99"
                    },
                    "account_digit": "0",
                    "account_branch": "0000",
                    "account_number": "00000",
                    "financial_institution_code": "000",
                    "financial_institution_ispb": "00000000"
                },
                "distributor": {
                    "distributor_key": "UUID",
                    "document_number": "99.999.999/9999-99",
                    "name": "",
                    "account_data": {
                        "owner": {
                            "name": "",
                            "document_number": "99.999.999/9999-99"
                        },
                        "account_digit": "0",
                        "account_branch": "0000",
                        "account_number": "00000",
                        "financial_institution_code": "000",
                        "financial_institution_ispb": "00000000"
                    },
                }
            },
            "total_net_worth": 0.00,
            "total_number_of_quotas": 0.00000000,
            "issuance_serie": {},
            "investor_position_key":"UUID"
        },
        "original_principal_value": 0.00000000,
        "current_principal_value": 0.00000000,
        "original_number_of_units": 0.00000000,
        "current_number_of_units": 0.00000000,
        "quotation_date": "yyyy-mm-dd",
        "application_datetime": "YYYY-MM-DDTHH:MM:SSZ",
        "status": "pending_payment" | "pending_quote" | "quoted" | "settled" | "redeemed" | "canceled",
        "status_events": [
            {
                "event_datetime": "yyyy-mm-dd HH:MM:SS:ms",
                "status": "pending_payment" | "pending_quote" | "quoted" | "settled" | "redeemed" | "canceled",
            }
        ],
        "capital_returns": [
            {
                "capital_return_key": "UUID",
                "origin_key": "UUID",
                "net_value": 0.00,
                "iof_value": 0.00,
                "ir_value": 0.00,
                "payment_date": "yyyy-mm-dd",
                "capital_return_date": "yyyy-mm-dd",
                "status": "",
                "capital_return_type": "",
                "number_of_units": "",
            }
        ],
        }
    ],
    "limit": 50,
    "page": 0,
    "is_last_page": true
}
```

### Page
| Campo         | Tipo   | Descrição                                                                    |
|---------------|--------|------------------------------------------------------------------------------|
| `data`        | array  | Lista de objetos de **[Financial Application](#financial_application)**      |
| `limit`       | int    | Limite de objetos recuperados por página                                     |
| `page`        | int    | Número da página recuperada                                                  |
| `is_last_page`| boolean| Informação que indica se a página recuperada é a última                      |

### Financial Application {#financial_application}
| Campo                         | Tipo     | Descrição                                                                       | Caracteres |
|-------------------------------|----------|---------------------------------------------------------------------------------|------------|
| `external_id`                 | string   | Identificador externo                                                           | até 100    |
| `financial_application_key`   | string   | Chave única de identificação da aplicação financeira                            | 36         |
| `share_capital`               | float    | Valor do aporte                                                                 | -          |             
| `investor_position`           | JSON     | Objeto de **[Investor Position](#investor_position)**                           | -          |
| `original_principal_value`    | float    | Valor original de principal por cota                                            | -          |
| `current_principal_value`     | float    | Valor atual de principal por cota                                               | -          |
| `original_number_of_units`    | float    | Quantidade original de cotas                                                    | -          |
| `current_number_of_units`     | float    | Quantidade atual de cotas                                                       | -          |
| `quotation_date`              | string   | Data da cotização                                                               | -          |
| `application_datetime`        | string   | Data da criação da aplicação financeira                                         | -          |
| `status`                      | string   | Enumerador de **[Financial Application Status](#financial_application_status)** | -          |
| `status_events`               | array    | Lista de objetos de **[Status Event](#status_event)**                           | -          |
| `capital_returns`             | array    | Lista de objetos de **[Capital Return](#capital_return)**                       | -          |

### Financial Application Status {#financial_application_status}
| Enumerador               | Descrição                                       |
|--------------------------|-------------------------------------------------|
| `pending_payment`        | Pendente pagamento                              |
| `pending_quote`          | Pendente cotização                              |
| `quoted`                 | Cotizado                                        |
| `settled`                | Totalmente amortizado                           |
| `redeemed`               | Totalmente resgatado                            |
| `canceled`               | cancelado                                       |

### Investor Position {#investor_position}
| Campo                    | Tipo   | Descrição                                             |
|--------------------------|--------|-------------------------------------------------------|
| `investor`               | JSON   | Objeto de **[Investor](#investor)**                   |
| `total_net_worth`        | float  | Patrimônio Líquido da posição do investidor           |
| `total_number_of_quotas` | float  | Número de cotas da posição do investidor              |
| `issuance_serie`         | JSON   | Objeto de **[Issuance Serie](#issuance_serie)**       |
| `investor_position_key`  | JSON   | Chave única de identificação da posição do investidor |

### Status Event {#status_event}
| Campo            | Tipo     | Descrição                                                      |
|------------------|----------|----------------------------------------------------------------|
| `status`         | string   | Status do evento                                               |
| `event_datetime` | string   | Data e hora do evento                                          |

### Investor
| Campo                    | Tipo     | Descrição                                         | Caracteres |
|--------------------------|----------|---------------------------------------------------|------------|
| `name`                   | string   | Nome do investidor                                | até 255    |
| `investor_key`           | string   | Chave única de identificação do investidor        | 36         |
| `document_number`        | string   | CPF/CNPJ do investidor                            | 14 ou 18   |
| `person_type`            | string   | Pessoa Física / Pessoa Jurídica / Classe de Fundo | até 50     |
| `distributor`            | JSON     | Objeto de **[Distributor](#distributor)**         |     -      |             
| `account_data`           | JSON     | Objeto de **[Account Data](#account_data)**       |     -      |

### Distributor
| Campo                    | Tipo     | Descrição                                         | Caracteres |
|--------------------------|----------|---------------------------------------------------|------------|
| `name`                   | string   | Nome do distribuidor                              | até 255    |
| `distributor_key`        | string   | Chave única de identificação do distribuidor      |     -      |             
| `document_number`        | string   | CPF/CNPJ do distribuidor                          | 14 ou 18   |
| `account_data`           | JSON     | Objeto de **[Account Data](#account_data)**       |     -      |

### Account Data {#account_data}
| Campo                        | Tipo     | Descrição                                                                   |
|------------------------------|----------|-----------------------------------------------------------------------------|
| `account_digit`              | string   | Dígito da conta bancária                                                    |
| `account_branch`             | string   | N° da agência da conta bancária                                             |             
| `account_number`             | string   | N° da conta bancária                                                        |
| `financial_institution_code` | string   | Código da instituição financeira                                            |
| `financial_institution_ispb` | string   | Identificador no Sistema de Pagamento Brasileiro da instituição financeira  |

### Issuance Serie {#issuance_serie}
| Campo                         | Tipo     | Descrição                                         | Caracteres |
|-------------------------------|----------|---------------------------------------------------|------------|
| `name`                        | string   | Nome da série de emissão                          | até 255    |
| `issuance_serie_key`          | string   | Chave única de identificação da série de emissão  | 36         |
| `cetip_code`                  | string   | Código da série de emissão como ativo na CETIP    | 10         |             
| `start_date`                  | string   | Data de início da série de emissão                | 10         |
| `maturity_date`               | string   | Data de vencimento da série de emissão            | 10         |
| `original_quota_value`        | float    | Valor de cota original                            | -          |
| `remuneration_type`           | string   | Curva de rendimento / Residual                    | até 50     |
| `investment_category`         | string   | FIDC / Multimercado                               | até 50     |
| `condominum_type`             | string   | Aberto / Fechado                                  | até 50     |
| `tax_classification`          | string   | Curto prazo / Longo prazo                         | até 50     |
| `investment_restriction_type` | string   | Sem restrição / Qualificado / Profissional        | até 50     |
| `minimum_share_capital`       | float    | Valor mínimo para aplicação                       | -          |
| `accounting_date`             | string   | Data contábil da série de emissão                 | 10         |
| `sub_class`                   | JSON     | Objeto de **[Sub Class](#sub_class)**             | -          |

### Sub Class {#sub_class}
| Campo                         | Tipo     | Descrição                                         | Caracteres |
|-------------------------------|----------|---------------------------------------------------|------------|
| `name`                        | string   | Nome da sub classe                                | até 255    |
| `sub_class_key`               | string   | Chave única de identificação da sub classe        | 36         |
| `subordination_level`         | int      | Nível de subordinação da sub classe               | -          |             
| `fund_class`                  | JSON     | Objeto de **[Fund Class](#fund_class)**           | -          |

### Fund Class {#fund_class}
| Campo                         | Tipo     | Descrição                                         | Caracteres |
|-------------------------------|----------|---------------------------------------------------|------------|
| `name`                        | string   | Nome da classe de fundo                           | até 255    |
| `fund_class_key`              | string   | Chave única de identificação da classe de fundo   | 36         |
| `document_number`             | string   | CNPJ da classe de fundo                           | -          |             

### Capital Return {#capital_return}
| Campo                     | Tipo     | Descrição                                                      |
|---------------------------|----------|----------------------------------------------------------------|
| `capital_return_key`      | string   | Chave única de identificação do retorno de capital             |                       
| `origin_key`              | string   | Chave única de identificação da origem do retorno de capital   |                               
| `net_value`               | float    | Valor líquido do retorno de capital                            |       
| `iof_value`               | float    | Valor de IOF do retorno de capital                             |   
| `ir_value`                | float    | Valor de IR do retorno de capital                              |   
| `payment_date`            | string   | Data de pagamento do retorno de capital                        |   
| `capital_return_date`     | string   | Data de criação do retorno de capital                          |           
| `status`                  | string   | Enviando para o Administrador / Pendente Pagamento / Pago      |                           
| `capital_return_type`     | string   | Amortização / Pedido de Resgate / Come-cotas                   |               
| `number_of_units`         | float    | N° de quotas do retorno de capital                             |

---

# Consulta paginada de Fechamento das Aplicações Financeiras

URL: /documentation/iaas/passivo/aplicacao_financeira/busca_paginada_fechamento_das_aplicacoes_financeiras

---

### Requests

Requisição por classe de fundo
ENDPOINT /quota/fund_class/FUND_CLASS_KEY/financial_application_closings
MÉTODO GET
STATUS 200

#### Query Params

| Parâmetro          | Descrição                                                                            |
|--------------------|--------------------------------------------------------------------------------------|
| `accounting_date`  | Data contábil específica de fechamento (formato `yyyy-mm-dd`)                        |
| `from_date`        | Data de início do período (formato `yyyy-mm-dd`)                                     |
| `to_date`          | Data de fim do período (formato `yyyy-mm-dd`)                                        |
| `limit`            | Limite de objetos recuperados por página (mínimo `0`, máximo `75`, padrão `75`)      |
| `page`             | Número da página recuperada (mínimo `0`, padrão `0`)                                 |

:::warning Atenção
É obrigatório enviar `accounting_date` **ou** a combinação de `from_date` e `to_date`. Caso nenhum desses parâmetros seja enviado, o recurso retornará erro de parâmetros obrigatórios ausentes.
:::

Requisição por investidor e aplicação financeira
ENDPOINT /quota/investor/INVESTOR_KEY/financial_application/FINANCIAL_APPLICATION_KEY/financial_application_closings
MÉTODO GET
STATUS 200

#### Query Params

| Parâmetro                            | Descrição                                                                            |
|--------------------------------------|--------------------------------------------------------------------------------------|
| `last_financial_application_closing` | Booleano. Quando `true`, retorna apenas o último fechamento da aplicação. Padrão: `false`. |
| `limit`                              | Limite de objetos recuperados por página (mínimo `0`, máximo `500`, padrão `50`)     |
| `page`                               | Número da página recuperada (mínimo `0`, padrão `0`)                                 |

### Responses

Caso 01: Consulta bem-sucedida

```json
{
    "data": [
        {
            "financial_application": {
                "financial_application_key": "UUID",
                "share_capital": 0.00,
                "status": "pending_payment" | "pending_quote" | "quoted" | "settled" | "redeemed" | "canceled",
                "investor": {
                    "investor_key": "UUID",
                    "name": "",
                    "person_type": "natural_person" | "legal_person",
                    "document_number": "999.999.999-99" | "99.999.999/9999-99",
                    "distributor": {
                        "distributor_key": "UUID",
                        "name": "",
                        "document_number": "99.999.999/9999-99",
                        "account_data": {}
                    }
                },
                "issuance_serie": {},
                "financial_application_type": "regular",
                "payment_method": "regular" | "cetip" | "b3",
                "quotation_date": "yyyy-mm-dd",
                "current_principal_value": 0.00000000,
                "current_number_of_quotas": 0.00000000,
                "original_number_of_quotas": 0.00000000,
                "original_number_of_quotas_str": "0.00000000",
                "acquisition_cost": 0.00,
                "external_id": "",
                "redemptions": [],
                "amortizations": [],
                "status_events": [],
                "reserved_taxable_yields": []
            },
            "total_value": 0.00,
            "number_of_quotas": 0.00000000,
            "principal_value": 0.00,
            "acquisition_cost": 0.00,
            "yield_value": 0.00,
            "ir_value": 0.00,
            "iof_value": 0.00,
            "taxable_yield_value": 0.00,
            "accounting_date": "yyyy-mm-dd"
        }
    ],
    "limit": 75,
    "page": 0,
    "is_last_page": true
}
```

:::caution **Atenção**
Os campos abaixo do objeto `financial_application` são **condicionais** — só são retornados quando o dado existe no recurso:

- `redemptions[]`, `amortizations[]`, `status_events[]`, `reserved_taxable_yields[]`: listas omitidas quando vazias.
- `original_number_of_quotas` (e o sibling `original_number_of_quotas_str`), `current_principal_value`, `acquisition_cost`, `current_number_of_quotas`, `quotation_date`: preenchidos após o processamento de cotização da aplicação.
- `payment_method`, `financial_application_type`, `external_id`: opcionais por aplicação — retornados quando informados na criação ou em atualização posterior.

O envelope (`data`, `limit`, `page`, `is_last_page`) e os campos do objeto **[Financial Application Closing](#financial-application-closing)** estão sempre presentes na resposta.
:::

### Page
| Campo         | Tipo   | Descrição                                                                               |
|---------------|--------|-----------------------------------------------------------------------------------------|
| `data`        | array  | Lista de objetos de **[Financial Application Closing](#financial-application-closing)** |
| `limit`       | int    | Limite de objetos recuperados por página                                                |
| `page`        | int    | Número da página recuperada                                                             |
| `is_last_page`| boolean| Informação que indica se a página recuperada é a última                                 |

### Financial Application Closing
| Campo                   | Tipo     | Descrição                                                     |
|-------------------------|----------|---------------------------------------------------------------|
| `financial_application` | JSON     | Objeto de **[Financial Application](#financial-application)** |
| `total_value`           | float    | Valor total de fechamento da aplicação                        |
| `number_of_quotas`      | float    | Número de cotas referente ao fechamento                       |
| `principal_value`       | float    | Valor principal referente ao fechamento                       |
| `acquisition_cost`      | float    | Custo de aquisição das cotas relacionadas ao fechamento       |
| `yield_value`           | float    | Valor do rendimento bruto                                     |
| `ir_value`              | float    | Valor de IR                                                   |
| `iof_value`             | float    | Valor de IOF                                                  |
| `taxable_yield_value`   | float    | Valor do rendimento tributável                                |
| `accounting_date`       | string   | Data contábil referente ao fechamento da aplicação            |

### Financial Application
| Campo                              | Tipo     | Descrição                                                                       |
|------------------------------------|----------|---------------------------------------------------------------------------------|
| `financial_application_key`        | string   | Chave única de identificação da aplicação financeira                            |
| `share_capital`                    | float    | Valor do aporte                                                                 |
| `status`                           | string   | Enumerador de **[Financial Application Status](#financial-application-status)** |
| `investor`                         | JSON     | Objeto de **[Investor](#investor)**                                             |
| `issuance_serie`                   | JSON     | Objeto de **[Issuance Serie](#issuance-serie)**                                 |
| `redemptions`                      | array    | Lista de objetos de **Redemption** *(condicional)*               |
| `amortizations`                    | array    | Lista de objetos de **[Amortization](/documentation/iaas/passivo/amortizacao/listagem#amortizations)** *(condicional)*           |
| `status_events`                    | array    | Lista de objetos de **[Status Event](#status_event)** *(condicional)*           |
| `reserved_taxable_yields`          | array    | Lista de objetos de **Reserved Taxable Yield** *(condicional)* |
| `financial_application_type`       | string   | Tipo da aplicação financeira *(condicional)*                                    |
| `original_number_of_quotas`        | float    | Quantidade original de cotas *(condicional)*                                    |
| `original_number_of_quotas_str`    | string   | Versão string com precisão da quantidade original de cotas *(condicional)*      |
| `current_principal_value`          | float    | Valor atual de principal por cota *(condicional)*                               |
| `acquisition_cost`                 | float    | Custo de aquisição das cotas da aplicação *(condicional)*                       |
| `current_number_of_quotas`         | float    | Quantidade atual de cotas *(condicional)*                                       |
| `payment_method`                   | string   | Método de pagamento (`regular`, `cetip`, `b3`) *(condicional)*                  |
| `quotation_date`                   | string   | Data de cotização *(condicional)*                                               |
| `external_id`                      | string   | Identificador externo *(condicional)*                                           |

### Financial Application Status
| Enumerador        | Descrição                  |
|-------------------|----------------------------|
| `pending_payment` | Pendente pagamento         |
| `pending_quote`   | Pendente cotização         |
| `quoted`          | Cotizado                   |
| `settled`         | Totalmente amortizado      |
| `redeemed`        | Totalmente resgatado       |
| `canceled`        | Cancelado                  |

### Status Event {#status_event}
| Campo            | Tipo     | Descrição                                                      |
|------------------|----------|----------------------------------------------------------------|
| `status`         | string   | Status do evento                                               |
| `event_datetime` | string   | Data e hora do evento                                          |

### Investor
| Campo                       | Tipo     | Descrição                                            |
|-----------------------------|----------|------------------------------------------------------|
| `investor_key`              | string   | Chave única de identificação do investidor           |
| `name`                      | string   | Nome do investidor                                   |
| `person_type`               | string   | `natural_person` / `legal_person` / `fund_class`     |
| `distributor`               | JSON     | Objeto de **[Distributor](#distributor)**            |
| `document_number`           | string   | CPF/CNPJ do investidor *(condicional)*               |
| `external_id`               | string   | Identificador externo do investidor *(condicional)*  |
| `external_distribution_key` | string   | Chave externa de distribuição *(condicional)*        |

### Distributor
| Campo                    | Tipo     | Descrição                                         |
|--------------------------|----------|---------------------------------------------------|
| `distributor_key`        | string   | Chave única de identificação do distribuidor      |
| `name`                   | string   | Nome do distribuidor                              |
| `document_number`        | string   | CNPJ do distribuidor                              |
| `account_data`           | JSON     | Objeto com dados bancários do distribuidor        |

### Issuance Serie
| Campo                            | Tipo     | Descrição                                                                                    |
|----------------------------------|----------|----------------------------------------------------------------------------------------------|
| `issuance_serie_key`             | string   | Chave única de identificação da série de emissão                                             |
| `name`                           | string   | Nome da série de emissão                                                                     |
| `serie`                          | string   | Identificador da série                                                                       |
| `internal_code`                  | string   | Código interno da série                                                                      |
| `status`                         | string   | Enumerador de status da série de emissão                                                     |
| `original_quota_value`           | float    | Valor de cota original                                                                       |
| `current_quota_value`            | float    | Valor de cota atual (calculado a partir de `current_net_worth` / `current_number_of_quotas`) |
| `current_number_of_quotas`       | float    | Quantidade atual de cotas em circulação                                                      |
| `current_net_worth`              | float    | Patrimônio líquido atual                                                                     |
| `current_principal_value`        | float    | Valor de principal atual                                                                     |
| `performance_fee_current_value`  | float    | Taxa de performance atual                                                                    |
| `minimum_share_capital`          | float    | Valor mínimo para aplicação                                                                  |
| `remuneration_type`              | string   | Tipo de remuneração (enumerador)                                                             |
| `interest_rate_type`             | string   | Tipo de taxa de juros (enumerador)                                                           |
| `processing_method`              | string   | Método de processamento da série (enumerador)                                                |
| `operation_period_configuration` | JSON     | Configuração do período de operação                                                          |
| `sub_class`                      | JSON     | Objeto de **[Sub Class](#sub-class)**                                                        |
| `pre_fixed`                      | JSON     | Configuração pré-fixada *(condicional)*                                                      |
| `post_fixed`                     | JSON     | Configuração pós-fixada *(condicional)*                                                      |
| `isin_code`                      | string   | Código ISIN *(condicional)*                                                                  |
| `external_id`                    | string   | Identificador externo da série de emissão *(condicional)*                                    |
| `specific_interest_rate_data`    | JSON     | Dados específicos da taxa de juros *(condicional)*                                           |

### Sub Class
| Campo                  | Tipo     | Descrição                                         |
|------------------------|----------|---------------------------------------------------|
| `sub_class_key`        | string   | Chave única de identificação da sub classe        |
| `name`                 | string   | Nome da sub classe                                |
| `subordination_level`  | int      | Nível de subordinação da sub classe               |
| `fund_class`           | JSON     | Objeto de **[Fund Class](#fund-class)**           |

### Fund Class
| Campo                          | Tipo     | Descrição                                         |
|--------------------------------|----------|---------------------------------------------------|
| `fund_class_key`               | string   | Chave única de identificação da classe de fundo   |
| `name`                         | string   | Nome da classe de fundo                           |
| `short_name`                   | string   | Nome curto da classe de fundo                     |
| `document_number`              | string   | CNPJ da classe de fundo                           |
| `accounting_date`              | string   | Data contábil da classe de fundo                  |
| `sub_type`                     | string   | Subtipo da classe de fundo (enumerador)           |
| `tax_classification_id`        | string   | Classificação tributária (enumerador)             |
| `condominum_type_id`           | string   | Tipo de condomínio (enumerador)                   |
| `investment_category_id`       | string   | Categoria de investimento (enumerador)            |
| `prevent_payment`              | boolean  | Flag de prevenção de pagamento                    |
| `integralization_account_key`  | string   | Chave da conta de integralização                  |
| `manager`                      | JSON     | Objeto de **[Manager](#manager)**                 |

### Manager
| Campo               | Tipo     | Descrição                                   |
|---------------------|----------|---------------------------------------------|
| `manager_key`       | string   | Chave única de identificação do gestor      |
| `manager_name`      | string   | Nome do gestor                              |
| `document_number`   | string   | CNPJ do gestor                              |

---

# Consultar Aplicação Financeira por chave

URL: /documentation/iaas/passivo/aplicacao_financeira/buscar_aplicacao_financeira_por_chave

---

### Request

ENDPOINT /quota/investor/INVESTOR_KEY/financial_application/FINANCIAL_APPLICATION_KEY
MÉTODO GET
STATUS 200

### Responses
 

Caso 01: Consulta bem-sucedida

```json
{
    "external_id": "",
    "financial_application_key": "UUID",
    "share_capital": 0.00,
    "investor_position": {
        "investor": {
            "investor_key": "UUID",
            "document_number": "999.999.999-99" | "99.999.999/9999-99",
            "name": "",
            "person_type": "natural_person" | "legal_person",
            "account_data": {
                "owner": {
                    "name": "",
                    "document_number": "99.999.999/9999-99"
                },"issuance_serie": {},
                "account_digit": "0",
                "account_branch": "0000",
                "account_number": "00000",
                "financial_institution_code": "000",
                "financial_institution_ispb": "00000000"
            },
            "distributor": {
                "distributor_key": "UUID",
                "document_number": "99.999.999/9999-99",
                "name": "",
                "account_data": {
                    "owner": {
                        "name": "",
                        "document_number": "99.999.999/9999-99"
                    },
                    "account_digit": "0",
                    "account_branch": "0000",
                    "account_number": "00000",
                    "financial_institution_code": "000",
                    "financial_institution_ispb": "00000000"
                },
            }
        },
        "total_net_worth": 0.00,
        "total_number_of_quotas": 0.00000000,
        "investor_position_key": "UUID",
        "issuance_serie":{
            "name":"1",
            "cetip_code":"0000000SN1",
            "start_date":"YYYY-MM-DD",
            "maturity_date":"YYYY-MM-DD",
            "original_quota_value":0.00000000000000,
            "remuneration_type":"yield_curve",
            "interest_rate_type":"post_fixed",
            "pre_fixed":{
               "calendar_base":"workdays / calendar_360 / calendar_365",
               "monthly_rate":0.00000000000000
            },
            "post_fixed":{
               "calendar_base":"workdays / calendar_360 / calendar_365",
               "indexer":"di / ipca",
               "rate":1,
               "lag":{
                  "reference":"daily / monthly",
                  "amount":1
               }
            },
            "investment_category":"fidc / multi_market",
            "condominum_type":"open_ended / close_ended",
            "tax_classification":"short_term / long_term",
            "investment_restriction_type":"just_professional",
            "issuance_serie_key":"UUID",
            "minimum_share_capital":0.0,
            "accounting_date":"YYYY-MM-DD",
            "sub_class":{
               "name":"COTA SÊNIOR",
               "sub_class_key":"UUID",
               "subordination_level":1,
               "fund_class":{
                  "name":"SAMPLE FUND CLASS NAME",
                  "fund_class_key":"UUID",
                  "document_number":"00.000.000/0000-00"
               }
            }
        }
    },
    "original_principal_value": 0.00000000,
    "current_principal_value": 0.00000000,
    "original_number_of_units": 0.00000000,
    "current_number_of_units": 0.00000000,
    "quotation_date": "yyyy-mm-dd",
    "status": "pending_payment" | "pending_quote" | "quoted" | "settled" | "redeemed" | "canceled",
    "status_events": [
        {
            "event_datetime": "yyyy-mm-dd HH:MM:SS:ms",
            "status": "pending_payment" | "pending_quote" | "quoted" | "settled" | "redeemed" | "canceled",
        }
    ],
    "capital_returns": [
        {
            "capital_return_key": "UUID",
            "origin_key": "UUID",
            "net_value": 0.00,
            "iof_value": 0.00,
            "ir_value": 0.00,
            "payment_date": "yyyy-mm-dd",
            "capital_return_date": "yyyy-mm-dd",
            "status": "",
            "capital_return_type": "",
            "number_of_units": "",
        }
    ],
}
```

### Financial Application
| Campo                         | Tipo     | Descrição                                                                       | Caracteres |
|-------------------------------|----------|---------------------------------------------------------------------------------|------------|
| `external_id`                 | string   | Identificador externo                                                           | até 100    |
| `financial_application_key`   | string   | Chave única de identificação da aplicação financeira                            | 36         |
| `share_capital`               | float    | Valor do aporte                                                                 | -          |             
| `investor_position`           | JSON     | Objeto de **[Investor Position](#investor_position)**                           | -          |
| `original_principal_value`    | float    | Valor original de principal por cota                                            | -          |
| `current_principal_value`     | float    | Valor atual de principal por cota                                               | -          |
| `original_number_of_units`    | float    | Quantidade original de cotas                                                    | -          |
| `current_number_of_units`     | float    | Quantidade atual de cotas                                                       | -          |
| `quotation_date`              | string   | Data da cotização                                                               | -          |
| `status`                      | string   | Enumerador de **[Financial Application Status](#financial_application_status)** | -          |
| `status_events`               | array    | Lista de objetos de **[Status Event](#status_event)**                           | -          |
| `capital_returns`             | array    | Lista de objetos de **[Capital Return](#capital_return)**                       | -          |

### Financial Application Status {#financial_application_status}
| Enumerador               | Descrição                                       |
|--------------------------|-------------------------------------------------|
| `pending_payment`        | Pendente pagamento                              |
| `pending_quote`          | Pendente cotização                              |
| `quoted`                 | Cotizado                                        |
| `settled`                | Totalmente amortizado                           |
| `redeemed`               | Totalmente resgatado                            |
| `canceled`               | cancelado                                       |

### Investor Position {#investor_position}
| Campo                    | Tipo   | Descrição                                             |
|--------------------------|--------|-------------------------------------------------------|
| `investor`               | JSON   | Objeto de **[Investor](#investor)**                   |
| `total_net_worth`        | float  | Patrimônio Líquido da posição do investidor           |
| `total_number_of_quotas` | float  | Número de cotas da posição do investidor              |
| `issuance_serie`         | JSON   | Objeto de **[Issuance Serie](#issuance_serie)**       |
| `investor_position_key`  | JSON   | Chave única de identificação da posição do investidor |

### Status Event {#status_event}
| Campo            | Tipo     | Descrição                                                      |
|------------------|----------|----------------------------------------------------------------|
| `status`         | string   | Status do evento                                               |
| `event_datetime` | string   | Data e hora do evento                                          |

### Investor
| Campo                    | Tipo     | Descrição                                         | Caracteres |
|--------------------------|----------|---------------------------------------------------|------------|
| `name`                   | string   | Nome do investidor                                | até 255    |
| `investor_key`           | string   | Chave única de identificação do investidor        | 36         |
| `document_number`        | string   | CPF/CNPJ do investidor                            | 14 ou 18   |
| `person_type`            | string   | Pessoa Física / Pessoa Jurídica / Classe de Fundo | até 50     |
| `distributor`            | JSON     | Objeto de **[Distributor](#distributor)**         |     -      |             
| `account_data`           | JSON     | Objeto de **[Account Data](#account_data)**       |     -      |

### Distributor
| Campo                    | Tipo     | Descrição                                         | Caracteres |
|--------------------------|----------|---------------------------------------------------|------------|
| `name`                   | string   | Nome do distribuidor                              | até 255    |
| `distributor_key`        | string   | Chave única de identificação do distribuidor      |     -      |             
| `document_number`        | string   | CPF/CNPJ do distribuidor                          | 14 ou 18   |
| `account_data`           | JSON     | Objeto de **[Account Data](#account_data)**       |     -      |

### Account Data {#account_data}
| Campo                        | Tipo     | Descrição                                                                   |
|------------------------------|----------|-----------------------------------------------------------------------------|
| `account_digit`              | string   | Dígito da conta bancária                                                    |
| `account_branch`             | string   | N° da agência da conta bancária                                             |             
| `account_number`             | string   | N° da conta bancária                                                        |
| `financial_institution_code` | string   | Código da instituição financeira                                            |
| `financial_institution_ispb` | string   | Identificador no Sistema de Pagamento Brasileiro da instituição financeira  |

### Issuance Serie {#issuance_serie}
| Campo                         | Tipo     | Descrição                                         | Caracteres |
|-------------------------------|----------|---------------------------------------------------|------------|
| `name`                        | string   | Nome da série de emissão                          | até 255    |
| `issuance_serie_key`          | string   | Chave única de identificação da série de emissão  | 36         |
| `cetip_code`                  | string   | Código da série de emissão como ativo na CETIP    | 10         |             
| `start_date`                  | string   | Data de início da série de emissão                | 10         |
| `maturity_date`               | string   | Data de vencimento da série de emissão            | 10         |
| `original_quota_value`        | float    | Valor de cota original                            | -          |
| `remuneration_type`           | string   | Curva de rendimento / Residual                    | até 50     |
| `investment_category`         | string   | FIDC / Multimercado                               | até 50     |
| `condominum_type`             | string   | Aberto / Fechado                                  | até 50     |
| `tax_classification`          | string   | Curto prazo / Longo prazo                         | até 50     |
| `investment_restriction_type` | string   | Sem restrição / Qualificado / Profissional        | até 50     |
| `minimum_share_capital`       | float    | Valor mínimo para aplicação                       | -          |
| `accounting_date`             | string   | Data contábil da série de emissão                 | 10         |
| `sub_class`                   | JSON     | Objeto de **[Sub Class](#sub_class)**             | -          |

### Sub Class {#sub_class}
| Campo                         | Tipo     | Descrição                                         | Caracteres |
|-------------------------------|----------|---------------------------------------------------|------------|
| `name`                        | string   | Nome da sub classe                                | até 255    |
| `sub_class_key`               | string   | Chave única de identificação da sub classe        | 36         |
| `subordination_level`         | int      | Nível de subordinação da sub classe               | -          |             
| `fund_class`                  | JSON     | Objeto de **[Fund Class](#fund_class)**           | -          |

### Fund Class {#fund_class}
| Campo                         | Tipo     | Descrição                                         | Caracteres |
|-------------------------------|----------|---------------------------------------------------|------------|
| `name`                        | string   | Nome da classe de fundo                           | até 255    |
| `fund_class_key`              | string   | Chave única de identificação da classe de fundo   | 36         |
| `document_number`             | string   | CNPJ da classe de fundo                           | -          |             

### Capital Return {#capital_return}
| Campo                     | Tipo     | Descrição                                                      |
|---------------------------|----------|----------------------------------------------------------------|
| `capital_return_key`      | string   | Chave única de identificação do retorno de capital             |                       
| `origin_key`              | string   | Chave única de identificação da origem do retorno de capital   |                               
| `net_value`               | float    | Valor líquido do retorno de capital                            |       
| `iof_value`               | float    | Valor de IOF do retorno de capital                             |   
| `ir_value`                | float    | Valor de IR do retorno de capital                              |   
| `payment_date`            | string   | Data de pagamento do retorno de capital                        |   
| `capital_return_date`     | string   | Data de criação do retorno de capital                          |           
| `status`                  | string   | Enviando para o Administrador / Pendente Pagamento / Pago      |                           
| `capital_return_type`     | string   | Amortização / Pedido de Resgate / Come-cotas                   |               
| `number_of_units`         | float    | N° de quotas do retorno de capital                             |

---

# Criar Aplicação Financeira

URL: /documentation/iaas/passivo/aplicacao_financeira/criar_aplicacao_financeira

---

### Request

ENDPOINT /quota/investor/INVESTOR_KEY/financial_application
MÉTODO POST
STATUS 201

```json title='Request Body'
{
    "issuance_serie_key": "UUID",
    "share_capital": 0.00,
    "payment_method": "b3 / regular",
    "central_depositary": "unregistered / cetip",
    "quotation_date": "yyyy-mm-dd"
}
```

:::note **Campos Obrigatórios**.
- issuance_serie_key 
- share_capital
:::

:::caution **Atenção**
**payment_method** e **central_depositary** são campos opcionais, de modo que caso não sejam enviado seram considerados a opção marcada de default.

- Isso será depreciado em próximas versões, tornando-se obrigatório o envio dos campos
- Com **central_depositary** `cetip`, o **payment_method** pode ser `regular` ou `b3`. Com `unregistered`, apenas `regular` (`b3` não é permitido).
:::
### Body params
| Campo                             | Tipo     | Descrição                                                                                                                |
|-----------------------------------|----------|--------------------------------------------------------------------------------------------------------------------------|
| `issuance_serie_key`              | string   | Chave única de identificação da Série de emissão                                                                         |
| `share_capital`                   | float    | Valor da aplicação financeira                                                                                            |
| `payment_method`                  | string   | Método de Pagamento. Valores esperados:<br />• regular: Pix ou TED **(default)**<br />• b3: Via B3                               |
| `central_depositary`              | string   | Tipo de depositárias. Valores esperados:<br />• unregistered: Sem registradora<br />• cetip: Registado na Cetip **(default)**         |
| `quotation_date`                  | string   | Data de cotização da aplicação, no formato yyyy-mm-dd (opcional)                                                         |

### Response
```json title='Response Body'
{
    "financial_application_key": "UUID"
}
```

---

# Aprovação manual de bloqueio de cotas

URL: /documentation/iaas/passivo/bloqueio_de_cotas/aprovar_bloqueio_pendente_aprovacao

---

### Introdução
Este recurso tem como objetivo detalhar o fluxo de aprovação manual de um bloqueio.

:::warning Atenção
O Bloqueio de cotas somente irá para pendente aprovação manual caso o valor do bloqueio ultrapasse o valor total do patrimônio em até **3.8%**

:::

### Aprovação

ENDPOINT quota_lock/investor/INVESTOR_KEY/quota_lock/QUOTA_LOCk_KEY/pending_manual_approval/approve
MÉTODO PUT
STATUS 204

### Reprovação

ENDPOINT quota_lock/investor/INVESTOR_KEY/quota_lock/QUOTA_LOCk_KEY/pending_manual_approval/reprove
MÉTODO PUT
STATUS 204

---

# Consultar bloqueio de cotas

URL: /documentation/iaas/passivo/bloqueio_de_cotas/consulta_de_bloqueio_de_cotas

---

### Introdução
Este recurso tem como objetivo detalhar as informações de uma solicitação de **bloqueio de cotas** de um **investidor**.

### Request

ENDPOINT /quota_lock/investor/INVESTOR_KEY/quota_lock/QUOTA_LOCK_KEY
MÉTODO GET
STATUS 200

### Response
```json
{
  "quota_lock_key": "UUID",
  "status": "pending_documents",
  "original_locked_quotas": 0.0,
  "current_locked_quotas": 0.0,
  "original_locked_value": 0.0,
  "current_locked_value": 0.0,
  "type": "collateral",
  "collateral": {
    "recipient": {
      "name": "Sample Recipient Name",
      "document_number": "000.000.000-00",
      "person_type": "natural_person",
      "natural_person": {
        "birthdate": "YYYY-MM-DD",
        "mother_name": "Sample Recipient Mother Name"
      }
    },
    "borrower": {
      "name": "Sample Borrower Name",
      "document_number": "000.000.000-00",
      "person_type": "natural_person",
      "natural_person": {
        "birthdate": "YYYY-MM-DD",
        "mother_name": "Sample Borrower Mother Name"
      }
    },
    "assets": [
      {
        "asset_key": "UUID",
        "asset_type": "cce",
        "credit_operation": {
          "contract_number": "1000000001",
          "principal_value": 0.0,
          "interest_rate_type": "post_fixed",
          "pre_fixed": {
            "monthly_rate": 0.0,
            "calendar_base": "calendar_360"
          },
          "post_fixed": {
            "calendar_base": "workdays",
            "indexer": "di",
            "rate": 1,
            "lag": {
              "reference": "daily",
              "amount": 1
            }
          }
        },
        "documents": [
          {
            "document_key": "UUID",
            "document_type": "asset_document"
          }
        ]
      }
    ],
    "issuance_series": [
      {
        "issuance_serie_key": "UUID",
        "number_of_quotas": 0.0,
        "financial_value": 0.0
      },
      {
        "issuance_serie_key": "UUID",
        "number_of_quotas": 0.0,
        "financial_value": 0.0
      }
    ],
    "documents": [
      {
        "document_key": "UUID",
        "document_type": "collateral_contract"
      }
    ]
  },
  "investor_positions_locks": [
    {
      "investor_position_lock_key": "UUID",
      "investor_position_key": "UUID",
      "original_locked_quotas": 0.0,
      "current_locked_quotas": 0.0,
      "original_locked_value": 0.0,
      "current_locked_value": 0.0
    }
  ]
}
```

### Quota Lock
| Campo                       | Tipo   | Descrição                                                              | Caracteres |
|-----------------------------|------- |------------------------------------------------------------------------|------------|
| `quota_lock_key`            | string | Identificador único do bloqueio de cotas                               | 36         |
| `status`                    | string | Enumerador de tipo de bloqueio de cotas                                | até 255    |
| `type`                      | string | Enumerador de tipo de bloqueio de cotas                                | até 255    |
| `original_locked_quotas`    | float  | Quantidade original de cotas bloqueadas                                | -          |
| `current_locked_quotas`     | float  | Quantidade atual de cotas bloqueadas                                   | -          |
| `original_locked_value`     | float  | Valor original do bloqueio                                             | -          |
| `current_locked_value`      | float  | Valor atual do bloqueio                                                | -          |
| `collateral`                | JSON   | Objeto de **[Garantia](#collateral)**                                   | -          |
| `investor_positions_locks`  | Array  | Lista de objetos de **[Bloqueio de posição do investidor](#locked-investor-positions)**  | -          |

### Quota Lock Status
| Enumerador               | Descrição             |
|--------------------------|-----------------------|
| `pending_documents`      | Pendente documentos   |
| `pending_approval`       | Pendente aprovação    |
| `denied`                 | Negado                |
| `approved`               | Aprovado              |

### Quota Lock Type
| Enumerador               | Descrição             |
|--------------------------|-----------------------|
| `collateral`             | Garantia              |

### Collateral
| Campo                       | Tipo   | Descrição                                                             | Caracteres |
|-----------------------------|------- |-----------------------------------------------------------------------|------------|
| `recipient`                 | JSON   | Objeto de **[Beneficiário](#recipient)**                              | -          |
| `borrower`                  | JSON   | Objeto de **[Tomador](#borrower)**                                    | -          |
| `assets`                    | Array  | Lista de objetos de **[Ativo](#asset)**                               | -          |
| `issuance_series`           | Array  | Lista de objetos de **[Série de emissão](#issuance_serie)**           | -          |
| `documents`                 | Array  | Lista de objetos de **[Documento da garantia](#document)** | -          |

### Issuance Serie {#issuance_serie}
| Campo                             | Tipo     | Descrição                                             | Caracteres   |
|-----------------------------------|----------|-------------------------------------------------------|--------------|
| `issuance_serie_key`              | string   | Chave da série de emissão                             |     36       |
| `number_of_quotas`                | float    | Número de cotas bloqueadas                            |     -        |
| `financial_value`                 | float    | Valor financeiro bloqueado                            |     -        |

### Recipient
| Campo                       | Tipo   | Descrição                                           | Caracteres |
|-----------------------------|------- |-----------------------------------------------------|------------|
| `name`                      | string | Nome do beneficiário                                | até 255    |
| `document_number`           | string | CPF / CNPJ do beneficiário                          | 14 ou 18   |
| `person_type`               | string | Enumerador de pessoa física ou jurídica             | até 255    |
| `natural_person`            | JSON   | Objeto de **[Pessoa Física](#natural_person)**      | -          |
| `legal_person`              | JSON   | Objeto de **[Pessoa Jurídica](#legal_person)**      | -          |

### Borrower
| Campo                       | Tipo   | Descrição                                           | Caracteres |
|-----------------------------|------- |-----------------------------------------------------|------------|
| `name`                      | string | Nome do tomador                                     | até 255    |
| `document_number`           | string | CPF / CNPJ do tomador                               | 14 ou 18   |
| `person_type`               | string | Enumerador de pessoa física ou jurídica             | até 255    |
| `natural_person`            | JSON   | Objeto de **[Pessoa Física](#natural_person)**      | -          |
| `legal_person`              | JSON   | Objeto de **[Pessoa Jurídica](#legal_person)**      | -          |

### Person Type
| Enumerador               | Descrição             |
|--------------------------|-----------------------|
| `natural_person`         | Pessoa física         |
| `legal_person`           | Pessoa jurídica       |

### Natural Person {#natural_person}
| Campo                       | Tipo   | Descrição                                           | Caracteres |
|-----------------------------|------- |-----------------------------------------------------|------------|
| `birthdate`                 | string | Data de nascimento                                  | 10         |
| `mother_name`               | string | Nome da mãe                                         | até 255    |

### Legal Person {#legal_person}
| Campo            | Tipo     | Descrição                                                | Caracteres   |
|------------------|----------|----------------------------------------------------------|--------------|
| `activity_code`  | string   | Classificação Nacional das Atividades Econômicas (CNAE)  |     10       |
| `representatives`| array    | Lista de objetos de **[Representative](#representative)**|      -       |

### Representative
| Campo                             | Tipo     | Descrição                                      | Caracteres   |
|-----------------------------------|----------|------------------------------------------------|--------------|
| `name`                            | string   | Nome do representante                          |   até 255    |
| `document_number`                 | string   | CPF do representante                           |     14       |

### Asset
| Campo                             | Tipo     | Descrição                                                     | Caracteres   |
|-----------------------------------|----------|---------------------------------------------------------------|--------------|
| `asset_key`                       | string   | Identificador único do ativo                                  |   até 255    |
| `asset_type`                      | string   | Enumerador de tipo de ativo                                   |   até 255    |
| `status`                          | string   | Enumerador de status de ativo                                 |   até 255    |
| `credit_operation`                | JSON     | Objeto de **[Operação de Crédito](#credit_operation)**        |     -        |
| `documents`                       | Array    | Lista de objetos de **[Documento do ativo](#document)** |     -        |

### Asset Status
| Enumerador               | Descrição             |
|--------------------------|-----------------------|
| `pending_approval`       | Pendente aprovação    |
| `done`                   | concluído             |

### Document
| Campo                             | Tipo     | Descrição                                                     | Caracteres   |
|-----------------------------------|----------|---------------------------------------------------------------|--------------|
| `document_key`                    | string   | Identificador único do ativo                                  |   até 255    |
| `document_type`                   | string   | Enumerador de tipo de ativo                                   |   até 255    |

### Asset Type
| Enumerador               | Descrição |
|--------------------------|-----------|
| `ccb`                    | CCB       |
| `cce`                    | CCE       |

### Credit Operation {#credit_operation}
| Campo                             | Tipo     | Descrição                                             | Caracteres   |
|-----------------------------------|----------|-------------------------------------------------------|--------------|
| `contract_number`                 | string   | N° do contrato                                        |   até 255    |
| `principal_value`                 | string   | Valor de principal da operação                        |     -        |
| `interest_rate_type`              | string   | Enumerador de pós-fixada / pré-fixada                 |   até 255    |
| `pre_fixed`                       | JSON     | Objeto de **[Pré-fixada](#pre_fixed)**                |     -        |
| `post_fixed`                      | JSON     | Objeto de **[Pós-fixada](#pos_fixed)**                |     -        |

### Interest Rate Type
| Enumerador               | Descrição             |
|--------------------------|-----------------------|
| `pre_fixed`              | Pré-fixada            |
| `post_fixed`             | Pós-fixada            |

### Pre fixed {#pre_fixed}
| Campo                         | Tipo     | Descrição                                                    | Caracteres |
|-------------------------------|----------|--------------------------------------------------------------|------------|
| `calendar_base`               | string   | Enumerador de Dias úteis / calendário 360 / calendário 365   | até 255    |
| `monthly_rate`                | float    | Taxa mensal                                                  | -          |

### Post fixed {#pos_fixed}
| Campo                         | Tipo     | Descrição                                                       | Caracteres |
|-------------------------------|----------|-----------------------------------------------------------------|------------|
| `calendar_base`               | string   | Enumerador de Dias úteis / calendário 360 / calendário 365      | até 255    |
| `indexer`                     | string   | Enumerador de DI / IPCA                                         | até 255    |
| `rate`                        | float    | Taxa                                                            | -          |
| `lag`                         | JSON     | Objeto de **[Lag](#lag)**                                       | -          |

### calendar_base
| Enumerador               | Descrição             |
|--------------------------|-----------------------|
| `workdays`               | Dias úteis            |
| `calendar_360`           | Calendário 360 dias   |
| `calendar_365`           | Calendário 365 dias   |

### Indexer
| Enumerador               | Descrição             |
|--------------------------|-----------------------|
| `di`                     | DI                    |
| `ipca`                   | IPCA                  |

### Lag
| Campo                         | Tipo     | Descrição                                         | Caracteres |
|-------------------------------|----------|---------------------------------------------------|------------|
| `reference`                   | string   | Enumerador de  Diário / Mensal                    | até 255    |
| `amount`                      | integer  | Quantidade de lag                                 | -          |

### Reference
| Enumerador               | Descrição             |
|--------------------------|-----------------------|
| `daily`                  | Diário                |
| `monthly`                | Mensal                |

### Locked Investor Positions
| Campo                           | Tipo   | Descrição                                                             | Caracteres |
|---------------------------------|------- |-----------------------------------------------------------------------|------------|
| `investor_position_lock_key`    | string | Identificador único do bloqueio da posição do investor                | 36         |
| `investor_position_key`         | string | Identificador único da posição do investidor                          | 36         |
| `original_locked_quotas`        | float  | Quantidade original de cotas bloqueadas                               | -          |
| `current_locked_quotas`         | float  | Quantidade atual de cotas bloqueadas                                  | -          |
| `original_locked_value`         | float  | Valor original do bloqueio                                            | -          |
| `current_locked_value`          | float  | Valor atual do bloqueio                                               | -          |

---

# Consultar bloqueio de cotas de um investidor

URL: /documentation/iaas/passivo/bloqueio_de_cotas/consulta_de_bloqueio_de_cotas_de_um_investidor

---

### Introdução
Este recurso tem como objetivo detalhar as informações de todas as solicitação de **bloqueio de cotas** de um **investidor**.

### Request

ENDPOINT /quota_lock/investor/INVESTOR_KEY/quota_locks
MÉTODO GET
STATUS 200

### Response
```json
{
  "data": [
    {
      "quota_lock_key": "UUID",
      "status": "pending_documents",
      "original_locked_quotas": 0.0,
      "current_locked_quotas": 0.0,
      "original_locked_value": 0.0,
      "current_locked_value": 0.0,
      "type": "collateral",
      "collateral": {
        "recipient": {
          "name": "Sample Recipient Name",
          "document_number": "000.000.000-00",
          "person_type": "natural_person",
          "natural_person": {
            "birthdate": "YYYY-MM-DD",
            "mother_name": "Sample Recipient Mother Name"
          }
        },
        "borrower": {
          "name": "Sample Borrower Name",
          "document_number": "000.000.000-00",
          "person_type": "natural_person",
          "natural_person": {
            "birthdate": "YYYY-MM-DD",
            "mother_name": "Sample Borrower Mother Name"
          }
        },
        "assets": [
          {
            "asset_key": "UUID",
            "asset_type": "cce",
            "credit_operation": {
              "contract_number": "1000000001",
              "principal_value": 0.0,
              "interest_rate_type": "post_fixed",
              "pre_fixed": {
                "monthly_rate": 0.0,
                "calendar_base": "calendar_360"
              },
              "post_fixed": {
                "calendar_base": "workdays",
                "indexer": "di",
                "rate": 1,
                "lag": {
                  "reference": "daily",
                  "amount": 1
                }
              }
            },
            "documents": [
              {
                "document_key": "UUID",
                "document_type": "asset_document"
              }
            ]
          }
        ],
        "issuance_series": [
          {
            "issuance_serie_key": "UUID",
            "number_of_quotas": 0.0,
            "financial_value": 0.0
          },
          {
            "issuance_serie_key": "UUID",
            "number_of_quotas": 0.0,
            "financial_value": 0.0
          }
        ],
        "documents": [
          {
            "document_key": "UUID",
            "document_type": "collateral_contract"
          }
        ]
      },
      "investor_positions_locks": [
        {
          "investor_position_lock_key": "UUID",
          "investor_position_key": "UUID",
          "original_locked_quotas": 0.0,
          "current_locked_quotas": 0.0,
          "original_locked_value": 0.0,
          "current_locked_value": 0.0
        }
      ]
    },
    {
      "quota_lock_key":"04eeaabc-cb40-484a-b730-85ed5aed7bbf",
      "status":"approved",
      "type":"lawsuit",
      "original_locked_value":"50000.00",
      "current_locked_value":"50000.00",
      "lawsuit":{
          "protocol":"20250037746822",
          "lock_date":"2024-01-15",
          "unlock_date":"2024-01-16",
          "process_number":"13289520258250000",
          "document_number":"236.682.501-38",
          "requested_amount":50000.0
      }
    }
  ],
  "page": 0,
  "is_last_page": true
}
```

### Quota Lock
| Campo                       | Tipo   | Descrição                                                              | Caracteres |
|-----------------------------|------- |------------------------------------------------------------------------|------------|
| `quota_lock_key`            | string | Identificador único do bloqueio de cotas                               | 36         |
| `status`                    | string | Enumerador de tipo de bloqueio de cotas                                | até 255    |
| `type`                      | string | Enumerador de tipo de bloqueio de cotas                                | até 255    |
| `original_locked_quotas`    | float  | Quantidade original de cotas bloqueadas                                | -          |
| `current_locked_quotas`     | float  | Quantidade atual de cotas bloqueadas                                   | -          |
| `original_locked_value`     | float  | Valor original do bloqueio                                             | -          |
| `current_locked_value`      | float  | Valor atual do bloqueio                                                | -          |
| `collateral`                | JSON   | Objeto de **[Garantia](#collateral)**                                   | -          |
| `investor_positions_locks`  | Array  | Lista de objetos de **[Bloqueio de posição do investidor](#locked-investor-positions)**  | -          |

### Quota Lock Status
| Enumerador               | Descrição             |
|--------------------------|-----------------------|
| `pending_documents`      | Pendente documentos   |
| `pending_approval`       | Pendente aprovação    |
| `denied`                 | Negado                |
| `approved`               | Aprovado              |

### Quota Lock Type
| Enumerador               | Descrição             |
|--------------------------|-----------------------|
| `collateral`             | Garantia              |

### Collateral
| Campo                       | Tipo   | Descrição                                                             | Caracteres |
|-----------------------------|------- |-----------------------------------------------------------------------|------------|
| `recipient`                 | JSON   | Objeto de **[Beneficiário](#recipient)**                              | -          |
| `borrower`                  | JSON   | Objeto de **[Tomador](#borrower)**                                    | -          |
| `assets`                    | Array  | Lista de objetos de **[Ativo](#asset)**                               | -          |
| `issuance_series`           | Array  | Lista de objetos de **[Série de emissão](#issuance_serie)**           | -          |
| `documents`                 | Array  | Lista de objetos de **[Documento da garantia](#document)** | -          |

### Issuance Serie {#issuance_serie}
| Campo                             | Tipo     | Descrição                                             | Caracteres   |
|-----------------------------------|----------|-------------------------------------------------------|--------------|
| `issuance_serie_key`              | string   | Chave da série de emissão                             |     36       |
| `number_of_quotas`                | float    | Número de cotas bloqueadas                            |     -        |
| `financial_value`                 | float    | Valor financeiro bloqueado                            |     -        |

### Recipient
| Campo                       | Tipo   | Descrição                                           | Caracteres |
|-----------------------------|------- |-----------------------------------------------------|------------|
| `name`                      | string | Nome do beneficiário                                | até 255    |
| `document_number`           | string | CPF / CNPJ do beneficiário                          | 14 ou 18   |
| `person_type`               | string | Enumerador de pessoa física ou jurídica             | até 255    |
| `natural_person`            | JSON   | Objeto de **[Pessoa Física](#natural_person)**      | -          |
| `legal_person`              | JSON   | Objeto de **[Pessoa Jurídica](#legal_person)**      | -          |

### Borrower
| Campo                       | Tipo   | Descrição                                           | Caracteres |
|-----------------------------|------- |-----------------------------------------------------|------------|
| `name`                      | string | Nome do tomador                                     | até 255    |
| `document_number`           | string | CPF / CNPJ do tomador                               | 14 ou 18   |
| `person_type`               | string | Enumerador de pessoa física ou jurídica             | até 255    |
| `natural_person`            | JSON   | Objeto de **[Pessoa Física](#natural_person)**      | -          |
| `legal_person`              | JSON   | Objeto de **[Pessoa Jurídica](#legal_person)**      | -          |

### Person Type
| Enumerador               | Descrição             |
|--------------------------|-----------------------|
| `natural_person`         | Pessoa física         |
| `legal_person`           | Pessoa jurídica       |

### Natural Person {#natural_person}
| Campo                       | Tipo   | Descrição                                           | Caracteres |
|-----------------------------|------- |-----------------------------------------------------|------------|
| `birthdate`                 | string | Data de nascimento                                  | 10         |
| `mother_name`               | string | Nome da mãe                                         | até 255    |

### Legal Person {#legal_person}
| Campo            | Tipo     | Descrição                                                | Caracteres   |
|------------------|----------|----------------------------------------------------------|--------------|
| `activity_code`  | string   | Classificação Nacional das Atividades Econômicas (CNAE)  |     10       |
| `representatives`| array    | Lista de objetos de **[Representative](#representative)**|      -       |

### Representative
| Campo                             | Tipo     | Descrição                                      | Caracteres   |
|-----------------------------------|----------|------------------------------------------------|--------------|
| `name`                            | string   | Nome do representante                          |   até 255    |
| `document_number`                 | string   | CPF do representante                           |     14       |

### Asset
| Campo                             | Tipo     | Descrição                                                     | Caracteres   |
|-----------------------------------|----------|---------------------------------------------------------------|--------------|
| `asset_key`                       | string   | Identificador único do ativo                                  |   até 255    |
| `asset_type`                      | string   | Enumerador de tipo de ativo                                   |   até 255    |
| `status`                          | string   | Enumerador de status de ativo                                 |   até 255    |
| `credit_operation`                | JSON     | Objeto de **[Operação de Crédito](#credit_operation)**        |     -        |
| `documents`                       | Array    | Lista de objetos de **[Documento do ativo](#document)** |     -        |

### Asset Status
| Enumerador               | Descrição             |
|--------------------------|-----------------------|
| `pending_approval`       | Pendente aprovação    |
| `done`                   | concluído             |

### Document
| Campo                             | Tipo     | Descrição                                                     | Caracteres   |
|-----------------------------------|----------|---------------------------------------------------------------|--------------|
| `document_key`                    | string   | Identificador único do ativo                                  |   até 255    |
| `document_type`                   | string   | Enumerador de tipo de ativo                                   |   até 255    |

### Asset Type
| Enumerador               | Descrição |
|--------------------------|-----------|
| `ccb`                    | CCB       |
| `cce`                    | CCE       |

### Credit Operation {#credit_operation}
| Campo                             | Tipo     | Descrição                                             | Caracteres   |
|-----------------------------------|----------|-------------------------------------------------------|--------------|
| `contract_number`                 | string   | N° do contrato                                        |   até 255    |
| `principal_value`                 | string   | Valor de principal da operação                        |     -        |
| `interest_rate_type`              | string   | Enumerador de pós-fixada / pré-fixada                 |   até 255    |
| `pre_fixed`                       | JSON     | Objeto de **[Pré-fixada](#pre_fixed)**                |     -        |
| `post_fixed`                      | JSON     | Objeto de **[Pós-fixada](#pos_fixed)**                |     -        |

### Interest Rate Type
| Enumerador               | Descrição             |
|--------------------------|-----------------------|
| `pre_fixed`              | Pré-fixada            |
| `post_fixed`             | Pós-fixada            |

### Pre fixed {#pre_fixed}
| Campo                         | Tipo     | Descrição                                                    | Caracteres |
|-------------------------------|----------|--------------------------------------------------------------|------------|
| `calendar_base`               | string   | Enumerador de Dias úteis / calendário 360 / calendário 365   | até 255    |
| `monthly_rate`                | float    | Taxa mensal                                                  | -          |

### Post fixed {#pos_fixed}
| Campo                         | Tipo     | Descrição                                                       | Caracteres |
|-------------------------------|----------|-----------------------------------------------------------------|------------|
| `calendar_base`               | string   | Enumerador de Dias úteis / calendário 360 / calendário 365      | até 255    |
| `indexer`                     | string   | Enumerador de DI / IPCA                                         | até 255    |
| `rate`                        | float    | Taxa                                                            | -          |
| `lag`                         | JSON     | Objeto de **[Lag](#lag)**                                       | -          |

### calendar_base
| Enumerador               | Descrição             |
|--------------------------|-----------------------|
| `workdays`               | Dias úteis            |
| `calendar_360`           | Calendário 360 dias   |
| `calendar_365`           | Calendário 365 dias   |

### Indexer
| Enumerador               | Descrição             |
|--------------------------|-----------------------|
| `di`                     | DI                    |
| `ipca`                   | IPCA                  |

### Lag
| Campo                         | Tipo     | Descrição                                         | Caracteres |
|-------------------------------|----------|---------------------------------------------------|------------|
| `reference`                   | string   | Enumerador de  Diário / Mensal                    | até 255    |
| `amount`                      | integer  | Quantidade de lag                                 | -          |

### Reference
| Enumerador               | Descrição             |
|--------------------------|-----------------------|
| `daily`                  | Diário                |
| `monthly`                | Mensal                |

### Locked Investor Positions
| Campo                           | Tipo   | Descrição                                                             | Caracteres |
|---------------------------------|------- |-----------------------------------------------------------------------|------------|
| `investor_position_lock_key`    | string | Identificador único do bloqueio da posição do investor                | 36         |
| `investor_position_key`         | string | Identificador único da posição do investidor                          | 36         |
| `original_locked_quotas`        | float  | Quantidade original de cotas bloqueadas                               | -          |
| `current_locked_quotas`         | float  | Quantidade atual de cotas bloqueadas                                  | -          |
| `original_locked_value`         | float  | Valor original do bloqueio                                            | -          |
| `current_locked_value`          | float  | Valor atual do bloqueio                                               | -          |

---

# Enviar Documento da Garantia

URL: /documentation/iaas/passivo/bloqueio_de_cotas/enviar_documento_da_garantia

---
### Introdução
Este recurso tem como objetivo nos enviar o **documento** relacionado a formalização da **garantia** ao qual se está solicitando o **bloqueio de cotas**

### Input / Output:
Como ***input*** deve ser enviado o **tipo do documento** e o **base 64** do documento. Segue abaixo exemplo.

Como ***output*** será entregue uma ***collateral_document_key***. A ***collateral_document_key*** é utilizada para identificar o **documento da garantia** enviado.

### Request

ENDPOINT /quota_lock/investor/INVESTOR_KEY/quota_lock/QUOTA_LOCK_KEY/collateral/COLLATERAL_KEY/document
MÉTODO POST
STATUS 201

### Request body
```json title='Request Body'
{
  "document_type": "collateral_contract",
  "document_b64" : "B64"
}
```

### Collateral Document
| Campo            | Tipo   | Descrição                                                  | Caracteres | Obrigatório |
|------------------|--------|------------------------------------------------------------|------------|-------------|
| `document_type`  | string | Enumerador de tipo de documento da garantia               | até 255    |     Sim     |
| `document_b64`   | string | Conteúdo do documento codificado em base64                 | -          |     Sim     |

### Document Type
| Enumerador             | Descrição              |
|------------------------|------------------------|
| `collateral_contract`  | Contrato de garantia   |
| `rental_contract`      | Contrato de aluguel    |

### Response
```json title='Response Body'
{
    "collateral_document_key": "UUID"
}
```

---

# Enviar Documento do Ativo

URL: /documentation/iaas/passivo/bloqueio_de_cotas/enviar_documento_do_ativo

---
### Introdução
Este recurso tem como objetivo nos enviar o **documento** do **ativo** que é objeto da **garantia** ao qual se está solicitando o **bloqueio de cotas**

### Input / Output:
Como ***input*** deve ser enviado o **tipo do documento** e o **base 64** do documento. Segue abaixo exemplo.

Como ***output*** será entregue uma ***asset_document_key***. A ***asset_document_key*** é utilizada para identificar o **documento do ativo** enviado.

### Request

ENDPOINT /quota_lock/investor/INVESTOR_KEY/quota_lock/QUOTA_LOCK_KEY/collateral/COLLATERAL_KEY/asset/ASSET_KEY/document
MÉTODO POST
STATUS 201

### Request body
```json title='Request Body'
{
  "document_type": "asset_document",
  "document_b64" : "B64"
}
```

### Response
```json title='Response Body'
{
    "asset_document_key": "UUID"
}
```

---

# Execução de garantia

URL: /documentation/iaas/passivo/bloqueio_de_cotas/execucao_de_garantia

---

### Introdução

Este recurso tem como objetivo **executar uma garantia** constituída sobre as cotas de um **investidor**, convertendo o bloqueio em pagamento ao **credor**.

Diferente dos demais eventos de bloqueio, a execução de garantia gera um **pedido de resgate** na classe do fundo e o valor apurado é pago **nominalmente ao credor** cadastrado na garantia — não ao investidor. A posição do investidor é reduzida na proporção das cotas resgatadas.

### Pré-requisitos

Antes de solicitar a execução, confirme que:

| Requisito | Detalhe |
|-----------|---------|
| Bloqueio aprovado | O bloqueio de cotas deve estar no status `approved`. |
| Bloqueio do tipo garantia | Apenas bloqueios com o objeto `collateral` são executáveis. Bloqueios de penhora judicial não são. |
| Credor identificado | `collateral.recipient` deve conter `name` e `document_number`. |
| Conta bancária do credor | `collateral.recipient.bank_account` deve conter `account_number`, `account_branch`, `account_digit` e `financial_institution_ispb`. |

O cadastro do credor e da conta bancária é feito no momento da [solicitação de bloqueio de cotas](./solicitar_bloqueio_de_cotas.md). Uma execução solicitada sobre uma garantia com cadastro incompleto **não é registrada**.

:::warning Atenção
A conta bancária informada em `collateral.recipient.bank_account` é a **conta do credor** e é o destino do pagamento da execução. Não confundir com `collateral.bank_account_key`, que identifica uma conta **do investidor** e não participa da execução.
:::

### Request

ENDPOINT /quota_lock/investor/INVESTOR_KEY/quota_lock/QUOTA_LOCK_KEY/investor_position_lock/INVESTOR_POSITION_LOCK_KEY/event
MÉTODO POST
STATUS 201

Execução de garantia

```json
{
    "type": "collateral_execution",
    "net_value": 1000.00
}
```

### Collateral Execution Event

| Campo        | Tipo   | Descrição                                                              | Caracteres | Obrigatório |
|--------------|--------|------------------------------------------------------------------------|------------|-------------|
| `type`       | string | Enumerador do tipo de evento. Para execução de garantia: `collateral_execution` | até 255    |     Sim     |
| `net_value`  | float  | Valor líquido a ser executado e pago ao credor                          | -          |     Sim     |

O valor informado em `net_value` não pode exceder o valor financeiro bloqueado no momento da solicitação.

### Response

Execução registrada

```json
{
    "investor_position_lock_event_key": "UUID"
}
```

| Campo                              | Tipo   | Descrição                                             | Caracteres |
|------------------------------------|--------|-------------------------------------------------------|------------|
| `investor_position_lock_event_key` | string | Identificador do evento de execução criado            | 36         |

### O que acontece após a solicitação

1. O evento de execução é registrado com o status `pending_processing`. Os valores bloqueados **permanecem integralmente bloqueados** neste momento.
2. Um pedido de resgate do tipo `net_value_redemption` é aberto automaticamente na classe do fundo, no valor informado.
3. O pedido de resgate é cotizado no ciclo normal da classe. O pagamento é emitido para a conta do credor, **líquido de IR e IOF**.
4. Com a cotização concluída, a quantidade de cotas efetivamente resgatada é abatida do bloqueio e o evento passa para `done`.

Caso o pedido de resgate seja cancelado antes da cotização, o evento de execução passa para `canceled` e os valores bloqueados são **preservados integralmente** — não há baixa parcial.

### Event Status

| Enumerador            | Descrição                                                                     |
|-----------------------|-------------------------------------------------------------------------------|
| `pending_processing`  | Execução registrada, aguardando a cotização do pedido de resgate              |
| `done`                | Execução concluída, cotas abatidas do bloqueio                                |
| `canceled`            | Execução cancelada, valores bloqueados preservados                            |

### Acompanhamento

O status da execução é consultado pelo endpoint de [consulta de bloqueio de cotas](./consulta_de_bloqueio_de_cotas.md), no objeto `investor_position_locks[].events[]`.

Evento na consulta de bloqueio

```json
{
    "investor_position_locks": [
        {
            "investor_position_lock_key": "UUID",
            "current_locked_quotas": 100.00000000000000,
            "events": [
                {
                    "quota_lock_event_key": "UUID",
                    "type": "collateral_execution",
                    "status": "pending_processing"
                }
            ]
        }
    ]
}
```

:::note
Na resposta da consulta, o identificador do evento é retornado no campo `quota_lock_event_key`. Ele corresponde ao `investor_position_lock_event_key` devolvido na criação.
:::

Concluída a execução, o mesmo evento passa a apresentar `status: "done"` e o campo `new_locked_quotas` com a quantidade de cotas remanescente no bloqueio.

Não há webhook dedicado a eventos de execução de garantia. Os webhooks disponíveis para bloqueio de cotas estão descritos em [Webhooks de bloqueio de cota](./webhooks_de_bloqueio_de_cota.md).

### Erros

| Status | Código      | Descrição                                                                     |
|--------|-------------|---------------------------------------------------------------------------------|
| 400    | `QLK000044` | O `net_value` informado é nulo, zero ou negativo                                |
| 400    | `QLK000042` | O `net_value` informado excede o valor bloqueado                                |
| 400    | `QLK000036` | O agente selecionado não é o solicitante do bloqueio                            |
| 404    | `QLK000022` | Bloqueio de cotas não encontrado                                                |
| 404    | `QLK000037` | Posição bloqueada não encontrada                                                |

---

# Reduzir bloqueio de cotas

URL: /documentation/iaas/passivo/bloqueio_de_cotas/reduzir_bloqueio_de_cotas

---

### Introdução
Este recurso tem como objetivo reduzir o valor de **bloqueio de cotas** de um **investidor**.

### Request

ENDPOINT /quota_lock/investor/INVESTOR_KEY/quota_lock/QUOTA_LOCK_KEY/investor_position_lock/INVESTOR_POSITION_LOCK_KEY/event
MÉTODO POST
STATUS 201

Redução de valor bloqueado

```json
{
    "type": "decrease_locked_value",
    "new_locked_value": 0.00
}
```

Redução de quantidade de cotas bloqueadas

```json
{
    "type": "decrease_locked_quotas",
    "new_locked_quotas": 0.00
}
```

Execução de garantia

```json
{
    "type": "collateral_execution",
    "net_value": 0.00
}
```

### Locked Investor Position Event
| Campo                       | Tipo   | Descrição                                                 | Caracteres | Obrigatório |
|-----------------------------|------- |-----------------------------------------------------------|------------|-------------|
| `type`                      | string | Enumerador de tipo de evento                              | até 255    |     Sim     |
| `new_locked_value`          | float  | Novo valor financeiro bloqueado                           | -          |     Não     |
| `new_locked_quotas`         | float  | Nova quantidade de cotas bloqueadas                       | -          |     Não     |
| `net_value`                 | float  | Valor líquido apurado na execução de garantia             | -          |     Não     |

Obrigatoriamente um — e apenas um — entre `new_locked_value`, `new_locked_quotas` e `net_value` deve ser enviado.

### Event Type
| Enumerador                | Descrição                                        |
|---------------------------|--------------------------------------------------|
| `decrease_locked_quotas`  | Diminuir quantidade de cotas bloqueadas          |
| `decrease_locked_value`   | Diminuir valor financeiro bloqueado              |
| `collateral_execution`    | Execução de garantia                             |

O evento `collateral_execution` tem fluxo, pré-requisitos e acompanhamento próprios, descritos em [Execução de garantia](./execucao_de_garantia.md).

---

# Solicitar bloqueio de cotas

URL: /documentation/iaas/passivo/bloqueio_de_cotas/solicitar_bloqueio_de_cotas

---

### Introdução
Este recurso tem como objetivo criar uma solicitação de **bloqueio de cotas** de um **investidor**.

### Input / Output:
Deve ser enviado o **tipo de bloqueio** e a informação específica do tipo de bloqueio.

Como ***output*** será entregue a ***quota_lock_key*** que representa o **bloqueio de cota**.

### Request

ENDPOINT /quota_lock/investor/INVESTOR_KEY/quota_lock
MÉTODO POST
STATUS 201

Bloqueio de cotas por garantia - CCE - pessoa física

```json
{
    "type": "collateral",
    "collateral": {
        "recipient": {
            "name": "Sample Recipient Name",
            "document_number": "000.000.000-00",
            "person_type": "natural_person",
            "natural_person": {
               "birthdate": "YYYY-MM-DD",
               "mother_name": "Sample Recipient Mother Name",
            }
        },
        "borrower": {
            "name": "Sample Borrower Name",
            "document_number": "000.000.000-00",
            "person_type": "natural_person",
            "natural_person": {
               "birthdate": "YYYY-MM-DD",
               "mother_name": "Sample Borrower Mother Name",
            }
        },
        "assets": [
            {
                "asset_type": "cce",
                "credit_operation": {
                    "contract_number": "1000000001",
                    "principal_value": 0.0,
                    "interest_rate_type": "post_fixed",
                    "pre_fixed": {
                        "monthly_rate": 0.0,
                        "calendar_base": "calendar_360",
                    },
                    "post_fixed": {
                        "calendar_base": "workdays",
                        "indexer": "di",
                        "rate": 1,
                        "lag": {
                           "reference": "daily",
                           "amount": 1
                        },
                    },
                },
            },
        ],
        "issuance_series": [
            {
                "issuance_serie_key": "UUID",
                "number_of_quotas": 0.00,
                "financial_value": 0.00,
            },
            {
                "issuance_serie_key": "UUID",
                "number_of_quotas": 0.00,
                "financial_value": 0.00,
            },
        ],
        "bank_account_key": "UUID"
    },
}
```

Bloqueio de cotas por garantia - CCE - pessoa jurídica

```json
{
    "type": "collateral",
    "collateral": {
        "recipient": {
            "name": "Sample Recipient Name",
            "document_number": "000.000.000-00",
            "person_type": "legal_person",
            "legal_person": {
                "activity_code": "00.00-0-00",
                "representatives": [
                    {
                        "name": "Sample Recipient Representative Name",
                        "document_number": "000.000.000-00",
                    }
                ],
            }
        },
        "borrower": {
            "name": "Sample Borrower Name",
            "document_number": "000.000.000-00",
            "person_type": "legal_person",
            "legal_person": {
                "activity_code": "00.00-0-00",
                "representatives": [
                    {
                        "name": "Sample Borrower Representative Name",
                        "document_number": "000.000.000-00",
                    }
                ],
            }
        },
        "assets": [
            {
                "asset_type": "cce",
                "credit_operation": {
                    "contract_number": "1000000001",
                    "principal_value": 0.0,
                    "interest_rate_type": "post_fixed",
                    "pre_fixed": {
                        "monthly_rate": 0.0,
                        "calendar_base": "calendar_360",
                    },
                    "post_fixed": {
                        "calendar_base": "workdays",
                        "indexer": "di",
                        "rate": 1,
                        "lag": {
                           "reference": "daily",
                           "amount": 1
                        },
                    },
                },
            },
        ],
        "issuance_series": [
            {
                "issuance_serie_key": "UUID",
                "number_of_quotas": 0.00,
                "financial_value": 0.00,
            },
            {
                "issuance_serie_key": "UUID",
                "number_of_quotas": 0.00,
                "financial_value": 0.00,
            },
        ],
        "bank_account_key": "UUID"
    },
}
```

Bloqueio de cotas por garantia - contrato de aluguel - pessoa física

```json
{
    "type": "collateral",
    "collateral": {
        "recipient": {
            "name": "Sample Recipient Name",
            "document_number": "000.000.000-00",
            "person_type": "natural_person",
            "natural_person": {
               "birthdate": "YYYY-MM-DD",
               "mother_name": "Sample Recipient Mother Name",
            }
        },
        "borrower": {
            "name": "Sample Borrower Name",
            "document_number": "000.000.000-00",
            "person_type": "natural_person",
            "natural_person": {
               "birthdate": "YYYY-MM-DD",
               "mother_name": "Sample Borrower Mother Name",
            }
        },
        "assets": [
            {
                "asset_type": "rental_contract",
                "rental_contract": {
                    "monthly_value": 0.0,
                    "property_address": {
                        "street": "Sample Street",
                        "number": "123",
                        "neighborhood": "Sample Neighborhood",
                        "city": "Sample City",
                        "uf": "SP",
                        "complement": "Sample Complement",
                        "postal_code": "00000-000",
                        "country": "BRA"
                    },
                    "start_date": "YYYY-MM-DD",
                    "end_date": "YYYY-MM-DD",
                    "readjustment_index": 0.0
                }
            }
        ],
        "issuance_series": [
            {
                "issuance_serie_key": "UUID",
                "number_of_quotas": 0.00,
                "financial_value": 0.00,
            }
        ],
        "bank_account_key": "UUID"
    },
}
```

Bloqueio de cotas por garantia - contrato de aluguel - pessoa jurídica

```json
{
    "type": "collateral",
    "collateral": {
        "recipient": {
            "name": "Sample Recipient Name",
            "document_number": "00.000.000/0000-00",
            "person_type": "legal_person",
            "legal_person": {
                "activity_code": "00.00-0-00",
                "representatives": [
                    {
                        "name": "Sample Recipient Representative Name",
                        "document_number": "000.000.000-00",
                    }
                ],
            }
        },
        "borrower": {
            "name": "Sample Borrower Name",
            "document_number": "00.000.000/0000-00",
            "person_type": "legal_person",
            "legal_person": {
                "activity_code": "00.00-0-00",
                "representatives": [
                    {
                        "name": "Sample Borrower Representative Name",
                        "document_number": "000.000.000-00",
                    }
                ],
            }
        },
        "assets": [
            {
                "asset_type": "rental_contract",
                "rental_contract": {
                    "monthly_value": 0.0,
                    "property_address": {
                        "street": "Sample Street",
                        "number": "123",
                        "neighborhood": "Sample Neighborhood",
                        "city": "Sample City",
                        "uf": "SP",
                        "complement": "Sample Complement",
                        "postal_code": "00000-000",
                        "country": "BRA"
                    },
                    "start_date": "YYYY-MM-DD",
                    "end_date": "YYYY-MM-DD",
                    "readjustment_index": 0.0
                }
            }
        ],
        "issuance_series": [
            {
                "issuance_serie_key": "UUID",
                "financial_application_keys": [
                    "UUID",
                    "UUID"
                ]
            }
        ],
        "bank_account_key": "UUID"
    },
}
```

### Quota Lock
| Campo                       | Tipo   | Descrição                                                        | Caracteres |
|-----------------------------|------- |------------------------------------------------------------------|------------|
| `type`                      | string | Enumerador de tipo de bloqueio de cotas                          | até 255    |
| `collateral`                | string | Objeto de **[Garantia](#collateral)**                            | -          |

### Quota Lock Type
| Enumerador               | Descrição             |
|--------------------------|-----------------------|
| `collateral`             | Garantia              |

### Collateral
| Campo                       | Tipo   | Descrição                                                        | Caracteres | Obrigatório |
|-----------------------------|------- |------------------------------------------------------------------|------------|-------------|
| `recipient`                 | JSON   | Objeto de **[Beneficiário](#recipient)**                         | -          |     Sim     |
| `borrower`                  | JSON   | Objeto de **[Tomador](#borrower)**                               | -          |     Sim     |
| `assets`                    | Array  | Lista de objetos de **[Ativo](#asset)**                          | -          |     Sim     |
| `issuance_series`           | Array  | Lista de objetos de **[Série de emissão](#issuance_serie)**      | -          |     Sim     |
| `bank_account_key`          | string | UUID da conta bancária associada à garantia                      | -          |     Não     |

### Recipient
| Campo                       | Tipo   | Descrição                                           | Caracteres | Obrigatório |
|-----------------------------|------- |-----------------------------------------------------|------------|-------------|
| `name`                      | string | Nome do beneficiário                                | até 255    |     Sim     |
| `document_number`           | string | CPF / CNPJ do beneficiário                          | 14 ou 18   |     Sim     |
| `person_type`               | string | Enumerador de pessoa física ou jurídica             | até 255    |     Sim     |
| `natural_person`            | JSON   | Objeto de **[Pessoa Física](#natural_person)**      | -          |     Não     |
| `legal_person`              | JSON   | Objeto de **[Pessoa Jurídica](#legal_person)**      | -          |     Não     |

### Borrower
| Campo                       | Tipo   | Descrição                                           | Caracteres | Obrigatório |
|-----------------------------|------- |-----------------------------------------------------|------------|------------ |
| `name`                      | string | Nome do tomador                                     | até 255    |     Sim     |
| `document_number`           | string | CPF / CNPJ do tomador                               | 14 ou 18   |     Sim     |
| `person_type`               | string | Enumerador de pessoa física ou jurídica             | até 255    |     Sim     |
| `natural_person`            | JSON   | Objeto de **[Pessoa Física](#natural_person)**      | -          |     Não     |
| `legal_person`              | JSON   | Objeto de **[Pessoa Jurídica](#legal_person)**      | -          |     Não     |

### Person Type
| Enumerador               | Descrição             |
|--------------------------|-----------------------|
| `natural_person`         | Pessoa física         |
| `legal_person`           | Pessoa jurídica       |

### Natural Person {#natural_person}
| Campo                       | Tipo   | Descrição                                           | Caracteres | Obrigatório |
|-----------------------------|------- |-----------------------------------------------------|------------|-------------|
| `birthdate`                 | string | Data de nascimento                                  | 10         |     Sim     |
| `mother_name`               | string | Nome da mãe                                         | até 255    |     Sim     |

### Legal Person {#legal_person}
| Campo            | Tipo     | Descrição                                                | Caracteres   | Obrigatório |
|------------------|----------|----------------------------------------------------------|--------------|-------------|
| `activity_code`  | string   | Classificação Nacional das Atividades Econômicas (CNAE)  |     10       |    Sim      |         
| `representatives`| array    | Lista de objetos de **[Representative](#representative)**|      -       |    Sim      |

### Representative
| Campo                             | Tipo     | Descrição                                      | Caracteres   | Obrigatório |
|-----------------------------------|----------|------------------------------------------------|--------------|-------------|
| `name`                            | string   | Nome do representante                          |   até 255    |    Sim      |
| `document_number`                 | string   | CPF do representante                           |     14       |    Sim      |

### Asset
| Campo                             | Tipo     | Descrição                                              | Caracteres   | Obrigatório |
|-----------------------------------|----------|--------------------------------------------------------|--------------|-------------|
| `asset_type`                      | string   | Enumerador de tipo de ativo                            |   até 255    |    Sim      |
| `credit_operation`                | JSON     | Objeto de **[Operação de Crédito](#credit_operation)** |     -        |    Não      |
| `rental_contract`                 | JSON     | Objeto de **[Contrato de Aluguel](#rental_contract)**  |     -        |    Não      |

### Asset Type
| Enumerador               | Descrição             |
|--------------------------|-----------------------|
| `ccb`                    | CCB                   |
| `cce`                    | CCE                   |
| `rental_contract`        | Contrato de aluguel   |

### Credit Operation {#credit_operation}
| Campo                             | Tipo     | Descrição                                             | Caracteres   | Obrigatório |
|-----------------------------------|----------|-------------------------------------------------------|--------------|-------------|
| `contract_number`                 | string   | N° do contrato                                        |   até 255    |    Sim      |
| `principal_value`                 | string   | Valor de principal da operação                        |     -        |    Sim      |
| `interest_rate_type`              | string   | Enumerador de Pós-fixada / pré-fixada                 |   até 255    |    Sim      |
| `pre_fixed`                       | JSON     | Objeto de **[Pré-fixada](#pre_fixed)**                |     -        |    Não      |
| `post_fixed`                      | JSON     | Objeto de **[Pós-fixada](#pos_fixed)**                |     -        |    Não      |

### Interest Rate Type
| Enumerador               | Descrição             |
|--------------------------|-----------------------|
| `pre_fixed`              | Pré-fixada            |
| `post_fixed`             | Pós-fixada            |

### Pre fixed {#pre_fixed}
| Campo                         | Tipo     | Descrição                                                    | Caracteres |
|-------------------------------|----------|--------------------------------------------------------------|------------|
| `calendar_base`               | string   | Enumerador de Dias úteis / calendário 360 / calendário 365   | até 255    |
| `monthly_rate`                | float    | Taxa mensal                                                  | -          |

### Post fixed {#pos_fixed}
| Campo                         | Tipo     | Descrição                                                       | Caracteres |
|-------------------------------|----------|-----------------------------------------------------------------|------------|
| `calendar_base`               | string   | Enumerador de Dias úteis / calendário 360 / calendário 365      | até 255    |
| `indexer`                     | string   | Enumerador de DI / IPCA                                                       | até 255    |
| `rate`                        | float    | Taxa                                                            | -          |
| `lag`                         | JSON     | Objeto de **[Lag](#lag)**                                       | -          |

### calendar_base
| Enumerador               | Descrição             |
|--------------------------|-----------------------|
| `workdays`               | Dias úteis            |
| `calendar_360`           | Calendário 360 dias   |
| `calendar_365`           | Calendário 365 dias   |

### Indexer
| Enumerador               | Descrição             |
|--------------------------|-----------------------|
| `di`                     | DI                    |
| `ipca`                   | IPCA                  |

### Lag
| Campo                         | Tipo     | Descrição                                         | Caracteres |
|-------------------------------|----------|---------------------------------------------------|------------|
| `reference`                   | string   | Enumerador de  Diário / Mensal                    | até 255    |
| `amount`                      | integer  | Quantidade de lag                                 | -          |

### Reference
| Enumerador               | Descrição             |
|--------------------------|-----------------------|
| `daily`                  | Diário                |
| `monthly`                | Mensal                |

### Rental Contract {#rental_contract}
| Campo                | Tipo     | Descrição                                             | Caracteres   | Obrigatório |
|----------------------|----------|-------------------------------------------------------|--------------|-------------|
| `monthly_value`      | float    | Valor mensal do aluguel                               |     -        |    Sim      |
| `property_address`   | JSON     | Objeto de **[Endereço](#address)** do imóvel          |     -        |    Sim      |
| `start_date`         | string   | Data de início do contrato (YYYY-MM-DD)               |     10       |    Sim      |
| `end_date`           | string   | Data de término do contrato (YYYY-MM-DD)              |     10       |    Sim      |
| `readjustment_index` | float    | Índice de reajuste do contrato                        |     -        |    Não      |

### Address
| Campo          | Tipo     | Descrição                                        | Caracteres   | Obrigatório |
|----------------|----------|--------------------------------------------------|--------------|-------------|
| `street`       | string   | Logradouro                                       |   até 255    |    Não      |
| `number`       | string   | Número                                           |     -        |    Não      |
| `neighborhood` | string   | Bairro                                           |   até 255    |    Não      |
| `city`         | string   | Cidade                                           |   até 255    |    Não      |
| `uf`           | string   | Unidade federativa (sigla de 2 letras)           |      2       |    Não      |
| `complement`   | string   | Complemento                                      |   até 255    |    Não      |
| `postal_code`  | string   | CEP no formato `00000-000`                       |      9       |    Não      |
| `country`      | string   | Código do país (3 letras)                        |      3       |    Não      |

### Issuance Serie {#issuance_serie}
| Campo                             | Tipo     | Descrição                                             | Caracteres   | Obrigatório |
|-----------------------------------|----------|-------------------------------------------------------|--------------|-------------|
| `issuance_serie_key`              | string   | Chave da série de emissão                             |     36       |    Sim      |
| `number_of_quotas`                | float    | Número de cotas a serem bloqueadas                    |     -        |    Não      |
| `financial_value`                 | float    | Valor financeiro a ser bloqueador                     |     -        |    Não      |

### Responses
```json title='Response Body'
{
    "quota_lock_key": "UUID"
}
```

---

# Webhook de bloqueio de cotas

URL: /documentation/iaas/passivo/bloqueio_de_cotas/webhooks_de_bloqueio_de_cota

---

### Introdução
Abaixo estão os detalhes sobre os webhooks enviados durante o processo de **bloqueio de cotas**.

Bloqueio aprovado

```json
{
  "webhook_type": "quota_lock.quota_lock_status_change",
  "webhook_datetime": "2024-12-05T00:00:00Z",
  "data": {
    "status": "approved",
    "quota_lock_key": "UUID"
  }
}
```

Bloqueio reprovado
    
```json
{
  "webhook_type": "quota_lock.quota_lock_status_change",
  "webhook_datetime": "2024-12-05T00:00:00Z",
  "data": {
    "status": "denied",
    "quota_lock_key": "UUID"
  }
}
```

---

# Consulta paginada de investidores por classe de fundo

URL: /documentation/iaas/passivo/consultas/consulta_investidores_classe_fundo

Retorna **investidores que possuem aplicação financeira** vinculada à classe de fundo informada (via séries de emissão e subclasses), de forma paginada. Permite filtrar por documento, nome e **data contábil** do fundo.

## Request

ENDPOINT /quota/fund_class/{fund_class_key}/investors
MÉTODO GET

### Query params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `page` | integer | opcional | Número da página (começa em `0`).|
| `limit` | integer | opcional | Registros por página. Padrão: `20`. Máximo: `500`. |
| `document_number` | string | opcional | Filtra pelo documento do investidor com pontuação. |
| `reference_date` | string (data) | opcional | Restringe a registros em que a **data contábil da classe de fundo** (`accounting_date`) é igual à data informada (formato aceito pelo servidor para parâmetros de data, tipicamente `YYYY-MM-DD`). |

```python title="Exemplo de chamada"
GET /quota/fund_class/{fund_class_key}/investors?page=0&limit=25&reference_date=2024-04-01
```

## Response

STATUS 200

```json title="Response Body"
{
  "data": [
    {
      "distributor": {
        "distributor_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "document_number": "12.345.678/0001-90",
        "name": "Distribuidora Exemplo S.A.",
        "account_data": {
          "owner": {
            "name": "Distribuidora Exemplo S.A.",
            "document_number": "12.345.678/0001-90"
          },
          "account_digit": "1",
          "account_branch": "0001",
          "account_number": "12345",
          "financial_institution_code": "341",
          "financial_institution_ispb": "60746948"
        }
      },
      "investor_key": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "Maria Cotista Silva",
      "person_type": "natural_person",
      "document_number": "123.456.789-00",
      "external_id": "ext-inv-001",
      "external_distribution_key": null
    },
    {
      "distributor": {
        "distributor_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "document_number": "12.345.678/0001-90",
        "name": "Distribuidora Exemplo S.A.",
        "account_data": {
          "owner": {
            "name": "Distribuidora Exemplo S.A.",
            "document_number": "12.345.678/0001-90"
          },
          "account_digit": "1",
          "account_branch": "0001",
          "account_number": "12345",
          "financial_institution_code": "341",
          "financial_institution_ispb": "60746948"
        }
      },
      "investor_key": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "name": "Investimentos PJ Ltda",
      "person_type": "legal_person",
      "document_number": "98.765.432/0001-10",
      "external_id": null,
      "external_distribution_key": "dist-key-7721"
    }
  ],
  "limit": 20,
  "page": 0,
  "is_last_page": true
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Lista de investidores. |
| `page` | integer | Página atual. |
| `limit` | integer | Tamanho da página. |
| `is_last_page` | boolean | Indica fim da paginação. |

#### Campos de cada investidor em `data`

| Campo | Tipo | Descrição |
|---|---|---|
| `investor_key` | string | Identificador único do investidor (UUID). |
| `name` | string | Nome. |
| `person_type` | string | Tipo de pessoa (enumerador, ex.: `natural_person`, `legal_person`). |
| `document_number` | string | Documento, quando houver. |
| `distributor` | object | Dados da distribuidora (`distributor_key`, `document_number`, `name`, `account_data`). |
| `external_id` | string | Opcional — identificador externo. |
| `external_distribution_key` | string | Opcional — chave de distribuição externa. |

## Possíveis erros

STATUS 404

**Classe de fundo não encontrada**

```json
{
  "title": " Fund Class not Found",
  "description": "Fund Class with key {fund_class_key} was not found.",
  "translation": "A classe com chave {fund_class_key} não foi encontrado.",
  "code": "QTA000002"
}
```

---

# Consulta paginada de posições de cotistas por classe de fundo

URL: /documentation/iaas/passivo/consultas/consulta_posicoes_cotistas_classe_fundo

Endpoint de consulta paginada que retorna as **posições por investidor e série de emissão** em uma classe de fundo: cotistas com saldo de cotas na aplicação financeira, com valor de cota obtido do fechamento mais recente da série. Utilize `document_number` para filtrar um cotista específico.

## Request

ENDPOINT /quota/fund_class/{fund_class_key}/investor_positions
MÉTODO GET

### Query params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `page` | integer | opcional | Número da página (começa em `0`). Padrão: `0`. |
| `limit` | integer | opcional | Quantidade de registros por página. Padrão: `20`. Máximo: `100`. |
| `document_number` | string | opcional | Filtra pelo documento do investidor (com pontuação). |

```python title="Exemplo de chamada"
GET /quota/fund_class/{fund_class_key}/investor_positions?page=0&limit=20&document_number=123.456.789-00
```

## Response

STATUS 200

```json title="Response Body"
{
  "data": [
    {
      "investor": {
        "distributor": {
          "distributor_key": "3571e292-3a83-4011-904d-20ee963022ef",
          "document_number": "12.345.678/0001-90",
          "name": "Distribuidora Exemplo S.A.",
          "account_data": {
            "owner": {
              "name": "Distribuidora Exemplo S.A.",
              "document_number": "12.345.678/0001-90"
            },
            "account_digit": "1",
            "account_branch": "0001",
            "account_number": "12345",
            "financial_institution_code": "341",
            "financial_institution_ispb": "60746948"
          }
        },
        "investor_key": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "name": "Maria Cotista Silva",
        "person_type": "natural_person",
        "document_number": "123.456.789-00",
        "external_id": "ext-inv-001",
        "external_distribution_key": null
      },
      "issuance_serie": {
        "issuance_serie_key": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "original_quota_value": 1.0,
        "current_number_of_quotas": 500000.0,
        "current_net_worth": 525000.75,
        "current_principal_value": 500000.0,
        "performance_fee_current_value": 0.0,
        "remuneration_type": "yield_curve",
        "minimum_share_capital": 1000.0,
        "interest_rate_type": "post_fixed",
        "name": "Série Única",
        "serie": 1,
        "sub_class": {
          "name": "Cota Sênior",
          "sub_class_key": "d4e5f6a7-b8c9-0123-def0-234567890123",
          "subordination_level": 1,
          "fund_class": {
            "name": "Fundo Exemplo FIDC",
            "short_name": "FEX",
            "document_number": "12.345.678/0001-90",
            "fund_class_key": "e5f6a7b8-c9d0-1234-ef01-345678901234",
            "accounting_date": "2024-06-01",
            "sub_type": "fidc",
            "tax_classification_id": "long_term",
            "condominum_type_id": "open_ended",
            "investment_category_id": "fidc",
            "prevent_payment": false,
            "integralization_account_key": null,
            "manager": {
              "manager_key": "f6a7b8c9-d0e1-2345-f012-456789012345",
              "document_number": "98.765.432/0001-10",
              "manager_name": "Gestora Exemplo S.A."
            }
          }
        },
        "status": "active",
        "internal_code": "INT-FEX-01",
        "processing_method": "standard",
        "operation_period_configuration": {
          "subscription": {},
          "redemption": {}
        },
        "current_quota_value": 1.0500015,
        "post_fixed": {
          "calendar_base": "calendar_252",
          "indexer": "cdi",
          "rate": 1.0,
          "lag": {
            "reference": "daily",
            "amount": 1
          }
        },
        "isin_code": "BRSTREXTFID6",
        "external_id": null,
        "specific_interest_rate_data": null
      },
      "number_of_quotas": 10000.0,
      "quota_value": 1.05234567
    }
  ],
  "limit": 20,
  "page": 0,
  "is_last_page": true
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Lista de posições. Cada item agrega **investidor**, **série de emissão**, **quantidade de cotas** e **valor de cota** (`quota_value` quando existir fechamento). |
| `page` | integer | Página atual. |
| `limit` | integer | Tamanho da página solicitado. |
| `is_last_page` | boolean | Indica se não há mais registros após esta página. |

#### Objeto em `data`

| Campo | Tipo | Descrição |
|---|---|---|
| `investor` | object | Dados do cotista e da distribuidora . |
| `issuance_serie` | object | Série de emissão da posição, incluindo `sub_class` e `fund_class` aninhados. |
| `number_of_quotas` | number | Soma das cotas da aplicação financeira para aquele investidor e série. |
| `quota_value` | number | Valor de cota do fechamento mais recente da série; omitido se não houver fechamento disponível. |

Campos opcionais ou nulos em `issuance_serie` (como `pre_fixed`, `external_id`, `integralization_account_key`) podem variar conforme o cadastro da série.

Para mais contexto sobre séries, consulte [Consulta paginada de séries de emissão](/documentation/iaas/cotas_de_fundo/consulta_paginada_series_de_emissao).

## Possíveis erros

STATUS 404

**Classe de fundo não encontrada**

```json
{
  "title": " Fund Class not Found",
  "description": "Fund Class with key {fund_class_key} was not found.",
  "translation": "A classe com chave {fund_class_key} não foi encontrado.",
  "code": "QTA000002"
}
```

STATUS 404

**Gestor não encontrado**

```json
{
  "title": "Manager not Found",
  "description": "Manager with Key {manager_key} was not found",
  "translation": "O gestor com chave {manager_key} nao foi encontrado",
  "code": "QTA00053"
}
```

---

# Consulta paginada do Mapa de Evolução de Cotas

URL: /documentation/iaas/passivo/consultas/consultar_mapa_de_evolucao_de_cotas

### Request

ENDPOINT /composition/fund_class/FUND-CLASS-KEY/issuance_serie/ISSUANCE-SERIE-KEY/quota_evolution_map
MÉTODO GET
STATUS 200

### Params

| Parâmetro            | Tipo   | Obrigatório | Descrição                 |
| -------------------- | ------ | ----------- | ------------------------- |
| `fund_class_key`     | `UUID` | Sim         | Chave do fundo            |
| `issuance_serie_key` | `UUID` | Sim         | Chave da série de emissão |

### Query Params

| Parâmetro        | Tipo         | Obrigatório | Descrição                                        |
| ---------------- | ------------ | ----------- | ------------------------------------------------ |
| `reference_date` | `YYYY-MM-DD` | Condicional | Data única de referência para consulta           |
| `start_date`     | `YYYY-MM-DD` | Condicional | Data inicial do intervalo                        |
| `end_date`       | `YYYY-MM-DD` | Condicional | Data final do intervalo                          |
| `limit`          | `int`        | Não         | Quantidade de registros por página (default: 10) |
| `page`           | `int`        | Não         | Página atual (default: 0)                        |

:::warning Atenção  
É obrigatório passar um dos filtros de data, reference_date trás o mec de uma data especifica, o conjunto de start_date e end_date vai trazer o mec em um range de datas. Caso nenhum dos dois filtros seja enviado, você receberá um erro: CMP000018
:::

Caso 01: Retorno com uma data

```json
{
  "data": [
    {
      "gross_net_worth": 10867777.38,
      "net_net_worth": 10867777.38,
      "gross_quota_value": 1.855893979904,
      "net_quota_value": 1.855893979904,
      "number_of_quotas": 5855818.003441199,
      "composition_date": "2025-05-04",
      "applied_value": 0.0,
      "applied_quotas": 0.0,
      "redeemed_value": 0.0,
      "redeemed_quotas": 0.0,
      "amortized_value": 0.0,
      "tax_anticipated_value": 0.0,
      "tax_anticipated_quotas": 0.0,
      "daily_rentability": 0.0006,
      "monthly_rentability": 0.0072,
      "yearly_rentability": 0.0898
    },
  ],
  "is_last_page": true,
  "page": 0,
  "limit": 10
}
```

###   Quota Evolution Map

| Campo                    | Tipo   | Descrição                                                       |
| ------------------------ | ------ | --------------------------------------------------------------- |
| `gross_net_worth`        | number | Patrimônio bruto no dia da composição                           |
| `net_net_worth`          | number | Patrimônio líquido no dia da composição                         |
| `gross_quota_value`      | number | Valor bruto da cota                                             |
| `net_quota_value`        | number | Valor líquido da cota                                           |
| `number_of_quotas`       | number | Quantidade total de cotas no dia                                |
| `composition_date`       | string | Data da composição (formato: `YYYY-MM-DD`)                      |
| `applied_value`          | number | Valor aplicado no dia                                           |
| `applied_quotas`         | number | Quantidade de cotas aplicadas no dia                            |
| `redeemed_value`         | number | Valor resgatado no dia                                          |
| `redeemed_quotas`        | number | Quantidade de cotas resgatadas no dia                           |
| `amortized_value`        | number | Valor amortizado no dia                                         |
| `tax_anticipated_value`  | number | Valor de imposto antecipado no dia                              |
| `tax_anticipated_quotas` | number | Quantidade de cotas com imposto antecipado no dia               |
| `daily_rentability`      | number | Rentabilidade diária (formato decimal, ex: `0.0007` para 0.07%) |
| `monthly_rentability`    | number | Rentabilidade mensal (formato decimal, ex: `0.0060` para 0.60%) |
| `yearly_rentability`     | number | Rentabilidade anual (formato decimal, ex: `0.096` para 9.6%)    |

---

# Consulta paginada de Séries de Emissão

URL: /documentation/iaas/passivo/consultas/consultar_todas_series_de_emissao

### Request

ENDPOINT /quota/issuance_series
MÉTODO GET
STATUS 200

### Query Params

| Parâmetro                     | Descrição                                                                 |
|-------------------------------|---------------------------------------------------------------------------|
| `issuance_serie_key`          | Chave única de identificação da série de emissão                          |
| `fund_class_document_number`  | CNPJ do fundo relacionado à série de emissão                              |

:::warning Atenção  
Durante o processo de integração será exigido um meio de autenticação da hash enviada.  
:::

Caso 01: Retorno com uma série de emissão

```json
{
  "data": [
    {
      "name": "Sample Issuance Serie Name",
      "investment_category": "fidc",
      "condominum_type": "open_ended",
      "tax_classification": "long_term",
      "investment_restriction_type": "professional",
      "remuneration_type": "residual",
      "issuance_serie_key": "UUID",
      "minimum_share_capital": 0.0,
      "accounting_date": "YYYY-MM-DD",
      "start_date": "YYYY-MM-DD",
      "original_quota_value": 1.0,
      "serie": 1,
      "maturity_date": "YYYY-MM-DD",
      "sub_class": {
        "name": "Sample Sub Class Name",
        "sub_class_key": "UUID",
        "subordination_level": 0,
        "fund_class": {
          "name": "Sample Fund Name",
          "fund_class_key": "UUID",
          "document_number": "00.000.000/0000-00",
          "administrator": {
            "name": "Sample Administrator Name",
            "administrator_key": "UUID",
            "document_number": "00.000.000/0000-00"
          }
        }
      }
    }
  ],
  "limit": 50,
  "page": 0,
  "is_last_page": true
}
```

### Issuance Serie

| Campo                          | Tipo   | Descrição                                                                 |
|-------------------------------|--------|---------------------------------------------------------------------------|
| `name`                        | string | Nome da série de emissão                                                  |
| `investment_category`         | string | Categoria de investimento (ex: fidc)                                      |
| `condominium_type`            | string | Tipo de condomínio (`open_ended` ou `closed_ended`)                       |
| `tax_classification`          | string | Classificação fiscal (ex: `long_term`)                                    |
| `investment_restriction_type` | string | Tipo de restrição ao investimento (ex: `professional`)                    |
| `remuneration_type`           | string | Tipo de remuneração (ex: `residual`)                                      |
| `issuance_serie_key`          | string | Chave única de identificação da série                                     |
| `minimum_share_capital`       | number | Capital mínimo da série                                                   |
| `accounting_date`             | string | Data contábil da série                                                    |
| `start_date`                  | string | Data de início da série                                                   |
| `original_quota_value`        | number | Valor original da cota                                                    |
| `serie`                       | number | Número da série                                                           |
| `maturity_date`               | string | Data de vencimento da série                                               |
| `sub_class`                   | JSON   | Objeto de **[Sub Class](#sub-class)** com informações da subclasse        |

### Sub Class

| Campo              | Tipo   | Descrição                                                          |
|--------------------|--------|---------------------------------------------------------------------|
| `name`             | string | Nome da subclasse                                                  |
| `sub_class_key`    | string | Chave única da subclasse                                           |
| `subordination_level` | number | Nível de subordinação                                           |
| `fund_class`       | JSON   | Objeto de **[Fund Class](#fund-class)** com informações do fundo   |

### Fund Class

| Campo             | Tipo   | Descrição                                                                             |
|-------------------|--------|---------------------------------------------------------------------------------------|
| `fund_class_key`  | string | Chave única de identificação do fundo                                                |
| `document_number` | string | CNPJ do fundo                                                                         |
| `name`            | string | Nome do fundo                                                                         |
| `administrator`   | JSON   | Objeto de **[Administrator](#administrator)** com informações do administrador        |

### Administrator

| Campo               | Tipo   | Descrição                                      |
|---------------------|--------|------------------------------------------------|
| `administrator_key` | string | Chave única de identificação do administrador  |
| `name`              | string | Nome do administrador                          |
| `document_number`   | string | CNPJ do administrador                          |

---

# Consulta paginada de Fundos

URL: /documentation/iaas/passivo/consultas/consultar_todos_fundos

---
:::warning Atenção
Este recurso está disponível apenas para integrações que exercem o papel de  **Distribuidor**.
:::

### Request

ENDPOINT /quota/fund_classes
MÉTODO GET
STATUS 200

### Query Params

| Parâmetro                    | Descrição                                                                            |
|------------------------------|--------------------------------------------------------------------------------------|
| `document_number`            | Documento do fundo                                                                   |
| `fund_class_key`             | Chave única de identificação do fundo                                                |

:::warning Atenção
Durante o processo de integração será exigido um meio de autenticação da hash enviada.
:::
Caso 01: Retorno com apenas um fundo

```json
{
    "data": [
      {
         "name":"SAMPLE FUND CLASS NAME",
         "fund_class_key":"UUID",
         "document_number":"00.000.000/0000-00",
         "administrator":{
            "name":"SAMPLE ADMINISTRATOR NAME",
            "administrator_key":"UUID",
            "document_number":"00.000.000/0000-00"
         }
      }
    ],
    "limit": 50,
    "page": 0,
    "is_last_page": true
}
```

### Fund Class

| Campo             | Tipo   | Descrição                                                                             |
| ----------------- | ------ | ------------------------------------------------------------------------------------- |
| `fund_class_key`  | string | Chave única de identificação do fundo                                                 |
| `document_number` | string | CNPJ do fundo                                                                         |
| `name`            | string | Nome do fundo                                                                         |
| `administrator`   | JSON   | Objeto de **[Administrator](#administrator)** com informações do administrador        |

### Administrator
| Campo               | Tipo   | Descrição                                      |
| ------------------- | ------ | ---------------------------------------------- |
| `administrator_key` | string | Chave única de identificação do administrador  |
| `name`              | string | Nome do administrador                          |
| `document_number`   | string | CNPJ do administrador                          |

---

# Enviar Boletim de Subscrição Assinado

URL: /documentation/iaas/passivo/controle_de_oferta/enviar_boletim_de_subscricao_assinado

---
### Introdução
Este recurso tem como objetivo nos enviar a comprovação de assinatura do **boletim de subscrição** de um **investidor** a uma **oferta de cotas** de um fundo.

:::warning Atenção
Este recurso está disponível apenas para integrações que exercem o papel de  **Distribuidor**.
:::

### Input / Output:
Como ***input*** deve ser enviada as informações relacionadas a subscrição,  UUID da **oferta de cotas** do fundo que o investidor subscreveu e, **tipo de assinatura** e dependendo da assinatura o conteúdo necessário para validação. Segue abaixo exemplo.

Como ***output*** será entregue uma ***subscription_note_key***. A ***subscription_note_key*** é utilizada para identificar o **boletim de subscrição**.

### Request

ENDPOINT /quota_offering_control/investor/INVESTOR_KEY/signed_subscription_note
MÉTODO POST
STATUS 201

### Request body
```json title='Request Body'
{
  "number_of_quotas": 0.0,
  "original_subscription_note_value": 0.0,
  "start_date": "YYYY-MM-DD",
  "maturity_date": "YYYY-MM-DD",
  "quota_offering_key": "UUID",
  "transaction_type": "ted | b3",
  "signature_method": "opt_in",
  "opt_in_hash" : "OPT_IN_HASH"
}
```
:::warning Atenção
Durante o processo de integração será exigido um meio de autenticação da hash enviada.
:::

### Response
```json title='Response Body'
{
    "subscription_note_key": "UUID"
}
```

---

# Recuperando Informações sobre Boletim de Subscrição

URL: /documentation/iaas/passivo/controle_de_oferta/informacoes_boletins_de_subscricao

---

### Request

ENDPOINT /quota_offering_control/investor/INVESTOR_KEY/subscription_notes
MÉTODO GET

:::warning Atenção
O endpoint acima está disponível apenas para integrações que exercem o papel de  **Distribuidor**.
:::

ENDPOINT /quota_offering_control/fund_class/FUND_CLASS_KEY/subscription_notes
MÉTODO GET

:::warning Atenção
O endpoint acima está disponível apenas para integrações que exercem o papel de  **Gestor**.
:::
   ### Responses

STATUS 200

Caso 01: Investidor com um Boletim de Subscrição

```json
{
   "data":[
      {
         "subscription_note_key":"UUID",
         "quota_offering":{
            "quota_offering_key":"UUID",
            "status":"active / closed",
            "original_quota_offering_value":0.00,
            "issued_number_of_quotas":0.00000000,
            "remaining_quota_offering_value":0.00,
            "start_date":"YYYY-MM-DD",
            "issuance_serie":{
               "name":"1",
               "issuance_serie_key":"UUID",
               "sub_class":{
                  "name":"SÊNIOR",
                  "sub_class_key":"UUID",
                  "subordination_level":1,
                  "fund_class":{
                     "fund_class_key":"UUID",
                     "name":"SAMPLE FUND CLASS NAME",
                     "document_number":"00.000.000/0000-00",
                     "short_name":"SAMPLE FUND CLASS SHORT NAME"
                  }
               },
               "classification":"general / qualified / professional",
               "market_type":"primary / secondary"
            },
            "type":"public / private",
            "data":{
               "type":"public / private",
               "cvm_registration":{
                  "date":"YYYY-MM-DD",
                  "number":"AAA/BBB/CCC/DDD/EEE/YYYY/000"
               },
               "lead_coordinator":{
                  "name":"SAMPLE LEAD COORDINATOR NAME",
                  "address":{
                     "uf":"SP",
                     "city":"São Paulo",
                     "number":"0000",
                     "street":"Sample street name",
                     "complement":"Sample complement"
                  },
                  "document_number":"00.000.000/0000-00"
               },
               "original_quota_offering_value":0.00
            }
         },
         "investor":{
            "distributor":{
               "distributor_key":"UUID",
               "document_number":"00.000.000/0000-00",
               "name":"Sample Distributor Name"
            },
            "investor_key":"UUID",
            "document_number":"00.000.000/0000-00",
            "name":"SAMPLE INVESTOR NAME",
            "person_type":"natural_person / legal_person"
         },
         "status":"send_to_generate_document / pending_document / pending_signature / canceled / active / sold_off",
         "transaction_type":"b3 / ted",
         "original_subscription_note_value":0.00,
         "issued_number_of_quotas":0.00000000,
         "remaining_subscription_note_value":0.00,
         "start_date":"YYYY-MM-DD",
         "financial_application_events":[
            {
               "financial_application_event_key":"UUID",
               "financial_application_key":"UUID",
               "type":"consume_value",
               "share_capital":0.00,
               "event_datetime":"YYYY-MM-DD HH:MM:SS"
            },
            {
               "financial_application_event_key":"UUID",
               "financial_application_key":"UUID",
               "type":"update_quotas",
               "number_of_quotas":0.00,
               "event_datetime":"YYYY-MM-DD HH:MM:SS"
            },
                        {
               "financial_application_event_key":"UUID",
               "financial_application_key":"UUID",
               "type":"cancel",
               "event_datetime":"YYYY-MM-DD HH:MM:SS"
            }
         ]
      }
   ],
   "limit":50,
   "page":0,
   "is_last_page":true
}
```

Caso 02: Investidor sem Boletim de Subscrição
```json
{
   "data":[],
   "limit":50,
   "page":0,
   "is_last_page":true
}
```

### Response Fields

| Campo         | Tipo   | Descrição                                                      |
|---------------|--------|----------------------------------------------------------------|
| `data`        | array  | Lista de objetos de **[Subscription Note](#subscription-note)**|
| `limit`       | int    | Limite de objetos recuperados por página                       |
| `page`        | int    | Número da página recuperada                                    |
| `is_last_page`| boolean| Informação que indica se a página recuperada é a última        |

### Observação

TIPO * significa que o campo pode ser nulo,
como no exemplo abaixo:
| Tipo     |
|----------|
| string * |

### Subscription Note
| Campo                     | Tipo     | Descrição                                                                                             |
|---------------------------|----------|-------------------------------------------------------------------------------------------------------|
| `subscription_note_key`   | string   | Chave única de identificação do boletim de subscrição                                                 |        
| `quota_offering`          | JSON     | Objeto de **[Quota Offering](#quota-offering)**                                                       |
| `investor`                | JSON     | Objeto de **[Investor](#investor)**                                                                   |
| `status`                  | string   | Enviar para gerar documento / Pendente documento / Pendente assinatura / Cancelado / Ativo / Esgotado |
| `transaction_type`        | string   | B3 / TED                                                                                              |
| `original_subscription_note_value`   | float    | Valor original do boletim de subscrição                                                    |       
| `issued_number_of_quotas` | float    | Quantidade de cotas emitidas                                                                          |   
| `remaining_subscription_note_value`  | float    | Valor restante do boletim de subscrição                                                    |   
| `start_date`              | string   | Data inicial do boletim de subscrição                                                                 |
| `financial_application_events`| array    | Lista de objetos de **[Financial Application Event](#financial-application-event)**               |
| `maturity_date`            | string* | Data de vencimento                                                                                    |       
| `original_number_of_quotas`| string* | Número do cotas emitidas                                                                              |

### Quota Offering
| Campo                             | Tipo     | Descrição                                                                               |
|-----------------------------------|----------|-----------------------------------------------------------------------------------------|
| `quota_offering_key`              | string   | Chave única de identificação da oferta                                                  |
| `status`                          | string   | Ativa / Fechada                                                                         |
| `original_quota_offering_value`   | float    | Valor original da oferta                                                                |
| `issued_number_of_quotas`         | float    | Quantidade de cotas subscritas                                                          |
| `remaining_quota_offering_value`  | float    | Valor restante da oferta                                                                |       
| `start_date`                      | string   | Data inicial da oferta                                                                  |
| `issuance_serie`                  | string   | Objeto de **[Issuance Serie](#issuance-serie)**             |
| `type`                            | string   | Tipo da oferta pública/privada                                                          |
| `cvm_registration`                | JSON    *| Dados do registro CVM                                                                   |
| `lead_coordinator`                | JSON    *| Dados do coordenador líder                                                              |
| `maturity_date`                   | string  *| Data de vencimento                                                                      |       
| `original_number_of_quotas`       | string  *| Número do cotas emitidas                                                                |

cvm_registration
```json
{
   "date":"YYYY-MM-DD",
   "number":"AAA/BBB/CCC/DDD/EEE/YYYY/000"
}
```
lead_coordinator
```json
{
   "name":"SAMPLE LEAD COORDINATOR NAME",
   "address":{
      "uf":"SP",
      "city":"São Paulo",
      "number":"0000",
      "street":"Sample street name",
      "complement":"Sample complement"
   },
   "document_number":"00.000.000/0000-00"
}
```

### Financial Application Event
| Campo                             | Tipo     | Descrição                                                                               |
|-----------------------------------|----------|-----------------------------------------------------------------------------------------|
| `financial_application_key`       | string   | Chave única de identificação da aplicação financeira                                    |
| `financial_application_event_key` | string   | Chave única de identificação do evento da aplicação financeira                          |
| `type`                            | string   | Consumir valor / Atualizar cotas / Cancelar                                             |
| `event_datetime`                  | string   | Data e hora do evento                                                                   |
| `share_capital`                   | float   *| Valor do aporte da aplicação financeira *SOMENTE APARECE QUANDO FOR 'consume_value'     |
| `number_of_quotas`                | float   *| Número de cotas da aplicação financeira *SOMENTE APARECE QUANDO FOR 'update_quotas'     |       

### Issuance Serie
| Campo                         | Tipo     | Descrição                                         |
|-------------------------------|----------|---------------------------------------------------|
| `name`                        | string   | Nome da série de emissão                          |
| `issuance_serie_key`          | string   | Chave única de identificação da série de emissão  |
| `sub_class`                   | JSON     | Objeto de **[Sub Class](#sub-class)**             |
| `classification`              | string   | Profissional / Qualificado / Geral                |
| `market_type`                 | string   | Primário / Secundário                             |
| `serie`                       | integer  | Curva de rendimento / Residual                    |

### Sub Class 
| Campo                         | Tipo     | Descrição                                         |
|-------------------------------|----------|---------------------------------------------------|
| `name`                        | string   | Nome da sub classe                                |
| `sub_class_key`               | string   | Chave única de identificação da sub classe        |
| `subordination_level`         | int      | Nível de subordinação da sub classe               |             
| `fund_class`                  | JSON     | Objeto de **[Fund Class](#fund-class)**           |

### Fund Class 
| Campo                         | Tipo     | Descrição                                         |
|-------------------------------|----------|---------------------------------------------------|
| `name`                        | string   | Nome da classe de fundo                           |
| `fund_class_key`              | string   | Chave única de identificação da classe de fundo   |
| `document_number`             | string   | CNPJ da classe de fundo                           | 
| `short_name`                  | string   | Nome reduzido da classe de fundo                  |

### Investor
| Campo                    | Tipo     | Descrição                                         |
|--------------------------|----------|---------------------------------------------------|
| `name`                   | string   | Nome do investidor                                |
| `investor_key`           | string   | Chave única de identificação do investidor        |
| `document_number`        | string   | CPF/CNPJ do investidor                            |
| `person_type`            | string   | Pessoa Física / Pessoa Jurídica / Classe de Fundo |
| `distributor`            | JSON     | Objeto de **[Distributor](#distributor)**         |             

### Distributor
| Campo                    | Tipo     | Descrição                                         |
|--------------------------|----------|---------------------------------------------------|
| `name`                   | string   | Nome do distribuidor                              |
| `distributor_key`        | string   | Chave única de identificação do distribuidor      |             
| `document_number`        | string   | CPF/CNPJ do distribuidor                          |

---

# Recuperando Informações sobre as Ofertas

URL: /documentation/iaas/passivo/controle_de_oferta/informacoes_das_ofertas

---

### Request

ENDPOINT /quota_offering_control/fund_class/FUND_CLASS_KEY/quota_offerings
MÉTODO GET

:::warning Atenção
Este recurso está disponível apenas para integrações que exercem o papel de  **Gestor**.
:::

   ### Responses

STATUS 200

   ### Query Params

| Parâmetro                    | Descrição                                                                            |
|------------------------------|--------------------------------------------------------------------------------------|
| `sub_class_key`              | Chave única de identificação da sub classe                                           |
| `issuance_serie_key`         | Chave única de identificação da série de emissão                                     |

Caso 01: Fundo com uma Oferta

```json
{
   "data":[{
      "quota_offering":{
         "quota_offering_key":"UUID",
         "status":"active / closed",
         "original_quota_offering_value":0.00,
         "issued_number_of_quotas":0.00000000,
         "remaining_quota_offering_value":0.00,
         "start_date":"YYYY-MM-DD",
         "issuance_serie":{
            "name":"1",
            "issuance_serie_key":"UUID",
            "sub_class":{
               "name":"SÊNIOR",
               "sub_class_key":"UUID",
               "subordination_level":1,
               "fund_class":{
                  "fund_class_key":"UUID",
                  "name":"SAMPLE FUND CLASS NAME",
                  "document_number":"00.000.000/0000-00",
                  "short_name":"SAMPLE FUND CLASS SHORT NAME"
               }
            },
            "classification":"general / qualified / professional",
            "market_type":"primary / secondary"
         },
         "type":"public / private",
         "data":{
            "type":"public / private",
            "cvm_registration":{
               "date":"YYYY-MM-DD",
               "number":"AAA/BBB/CCC/DDD/EEE/YYYY/000"
            },
            "lead_coordinator":{
               "name":"SAMPLE LEAD COORDINATOR NAME",
               "address":{
                  "uf":"SP",
                  "city":"São Paulo",
                  "number":"0000",
                  "street":"Sample street name",
                  "complement":"Sample complement"
               },
               "document_number":"00.000.000/0000-00"
            },
            "original_quota_offering_value":0.00
         }
      }
   }
   ],
   "limit":50,
   "page":0,
   "is_last_page":true
}
```

Caso 02: Fundo sem uma Oferta
```json
{
   "data":[],
   "limit":50,
   "page":0,
   "is_last_page":true
}
```

### Response Fields

| Campo         | Tipo   | Descrição                                                      |
|---------------|--------|----------------------------------------------------------------|
| `data`        | array  | Lista de objetos de **[Quota Offering](#quota-offering)**|
| `limit`       | int    | Limite de objetos recuperados por página                       |
| `page`        | int    | Número da página recuperada                                    |
| `is_last_page`| boolean| Informação que indica se a página recuperada é a última        |

### Observação

TIPO * significa que o campo pode ser nulo,
como no exemplo abaixo:
| Tipo     |
|----------|
| string * |

### Quota Offering
| Campo                             | Tipo     | Descrição                                                                               |
|-----------------------------------|----------|-----------------------------------------------------------------------------------------|
| `quota_offering_key`              | string   | Chave única de identificação da oferta                                                  |
| `status`                          | string   | Ativa / Fechada                                                                         |
| `original_quota_offering_value`   | float    | Valor original da oferta                                                                |
| `issued_number_of_quotas`         | float    | Quantidade de cotas subscritas                                                          |
| `remaining_quota_offering_value`  | float    | Valor restante da oferta                                                                |       
| `start_date`                      | string   | Data inicial da oferta                                                                  |
| `issuance_serie`                  | string   | Objeto de **[Issuance Serie](#issuance-serie)**             |
| `type`                            | string   | Tipo da oferta pública/privada                                                          |
| `cvm_registration`                | JSON    *| Dados do registro CVM                                                                   |
| `lead_coordinator`                | JSON    *| Dados do coordenador líder                                                              |
| `maturity_date`                   | string  *| Data de vencimento                                                                      |       
| `original_number_of_quotas`       | string  *| Número do cotas emitidas                                                                |

cvm_registration
```json
{
   "date":"YYYY-MM-DD",
   "number":"AAA/BBB/CCC/DDD/EEE/YYYY/000"
}
```
lead_coordinator
```json
{
   "name":"SAMPLE LEAD COORDINATOR NAME",
   "address":{
      "uf":"SP",
      "city":"São Paulo",
      "number":"0000",
      "street":"Sample street name",
      "complement":"Sample complement"
   },
   "document_number":"00.000.000/0000-00"
}
```

### Issuance Serie
| Campo                         | Tipo     | Descrição                                         |
|-------------------------------|----------|---------------------------------------------------|
| `name`                        | string   | Nome da série de emissão                          |
| `issuance_serie_key`          | string   | Chave única de identificação da série de emissão  |
| `sub_class`                   | JSON     | Objeto de **[Sub Class](#sub-class)**             |
| `classification`              | string   | Profissional / Qualificado / Geral                |
| `market_type`                 | string   | Primário / Secundário                             |
| `serie`                       | integer  | Curva de rendimento / Residual                    |

### Sub Class 
| Campo                         | Tipo     | Descrição                                         |
|-------------------------------|----------|---------------------------------------------------|
| `name`                        | string   | Nome da sub classe                                |
| `sub_class_key`               | string   | Chave única de identificação da sub classe        |
| `subordination_level`         | int      | Nível de subordinação da sub classe               |             
| `fund_class`                  | JSON     | Objeto de **[Fund Class](#fund-class)**           |

### Fund Class 
| Campo                         | Tipo     | Descrição                                         |
|-------------------------------|----------|---------------------------------------------------|
| `name`                        | string   | Nome da classe de fundo                           |
| `fund_class_key`              | string   | Chave única de identificação da classe de fundo   |
| `document_number`             | string   | CNPJ da classe de fundo                           | 
| `short_name`                  | string   | Nome reduzido da classe de fundo                  |

---

# Solicitar Boletim de Subscrição

URL: /documentation/iaas/passivo/controle_de_oferta/solicitar_boletim_de_subscricao

---
### Introdução
Este recurso tem como objetivo criar uma solicitação de **boletim de subscrição** de um **investidor** a uma **oferta de cotas** de um fundo. A partir desta solicitação, o documento do boletim é gerado de acordo com o tipo de geração configurado na oferta.

### Input / Output:
Como ***input*** deve ser enviado o UUID da **oferta de cotas** em que o investidor está subscrevendo, o **valor do boletim**, o **tipo de transação** e, opcionalmente, o método de assinatura e o grupo de signatários. Segue abaixo exemplo.

Como ***output*** será entregue o objeto completo do **boletim de subscrição** criado, incluindo a ***subscription_note_key***. A ***subscription_note_key*** é utilizada para identificar o **boletim de subscrição**.

### Request

ENDPOINT /quota_offering_control/investor/INVESTOR_KEY/subscription_note
MÉTODO POST
STATUS 201

### Path Params

| Parâmetro         | Descrição             |
|-------------------|-----------------------|
| `INVESTOR_KEY`    | UUID do investidor    |

### Request body
```json title='Request Body'
{
  "original_subscription_note_value": 50000.00,
  "quota_offering_key": "UUID",
  "transaction_type": "ted",
  "signature_method": "certifiqi",
  "signer_group_key": "UUID"
}
```

### Subscription Note
| Campo                              | Tipo   | Descrição                                                                                                                                        | Obrigatório |
|------------------------------------|--------|--------------------------------------------------------------------------------------------------------------------------------------------------|-------------|
| `original_subscription_note_value` | number | Valor do boletim de subscrição. Mínimo 0. Não pode exceder o valor restante da oferta                                                             |     Sim     |
| `quota_offering_key`               | string | UUID (36 caracteres) da oferta de cotas. A oferta deve existir e estar com status `active`                                                        |     Sim     |
| `transaction_type`                 | string | `ted` ou `b3`. Para `b3`, a classe de fundo precisa ter conta B3 cadastrada                                                                       |     Sim     |
| `signature_method`                 | string | Enumerador do método de assinatura. Se omitido, o serviço define pelo tipo de pessoa: `natural_person` → `qi_sign`, `legal_person` → `certifiqi`  |     Não     |
| `signer_group_key`                 | string | UUID (36 caracteres) do grupo de signatários. Se omitido, usa o grupo de signatários default do investidor                                        |     Não     |

### Signature Method

| Enumerador    | Descrição                                                    |
|---------------|--------------------------------------------------------------|
| `certifiqi`   | Assinatura via CertifiQi (Certificado Digital)               |
| `qi_sign`     | Assinatura via QI Sign (Assinatura Eletrônica)               |

### Response
```json title='Response Body'
{
  "subscription_note_key": "UUID",
  "status": "created",
  "original_number_of_quotas": 500,
  "original_subscription_note_value": 50000.00,
  "issued_number_of_quotas": 0,
  "remaining_subscription_note_value": 50000.00,
  "start_date": "YYYY-MM-DD",
  "transaction_type": "ted",
  "signature_method": "certifiqi",
  "investor": {
    "distributor": {
      "distributor_key": "UUID",
      "document_number": "00.000.000/0000-00",
      "name": "SAMPLE DISTRIBUTOR NAME"
    },
    "investor_key": "UUID",
    "name": "SAMPLE INVESTOR NAME",
    "person_type": "natural_person / legal_person",
    "document_number": "00.000.000/0000-00"
  },
  "quota_offering": {
    "quota_offering_key": "UUID",
    "status": "active",
    "original_quota_offering_value": 10000000.00,
    "issued_number_of_quotas": 25000.00,
    "remaining_quota_offering_value": 7500000.00,
    "start_date": "YYYY-MM-DD",
    "issuance_serie": {
      "name": "1",
      "issuance_serie_key": "UUID",
      "external_id": "SERIE-001",
      "sub_class": {
        "name": "SÊNIOR",
        "sub_class_key": "UUID",
        "subordination_level": 1,
        "fund_class": {
          "fund_class_key": "UUID",
          "document_number": "00.000.000/0000-00",
          "name": "SAMPLE FUND CLASS NAME",
          "short_name": "SAMPLE FUND CLASS SHORT NAME",
          "manager": {
            "name": "SAMPLE MANAGER NAME",
            "manager_key": "UUID",
            "document_number": "00.000.000/0000-00"
          },
          "administrator": {
            "name": "SAMPLE ADMINISTRATOR NAME",
            "administrator_key": "UUID",
            "document_number": "00.000.000/0000-00",
            "data": {}
          },
          "b3_account": "123456"
        }
      },
      "classification": "general / qualified / professional",
      "market_type": "primary / secondary",
      "serie": 1,
      "issuance_serie_configuration": {}
    },
    "type": "public / private",
    "subscription_note_template_key": "UUID",
    "subscription_note_generation_type": "internal / external",
    "regulatory_type": "exclusive_fund",
    "maturity_date": "YYYY-MM-DD",
    "status_events": [
      {
        "status": "created",
        "event_datetime": "YYYY-MM-DD HH:MM:SS"
      },
      {
        "status": "active",
        "event_datetime": "YYYY-MM-DD HH:MM:SS"
      }
    ]
  },
  "financial_application_events": [],
  "status_events": [
    {
      "status": "created",
      "event_datetime": "YYYY-MM-DD HH:MM:SS",
      "selected_agent": "distributor"
    }
  ]
}
```

A descrição detalhada dos objetos **[Quota Offering](/documentation/iaas/passivo/controle_de_oferta/informacoes_boletins_de_subscricao#quota-offering)**, **[Investor](/documentation/iaas/passivo/controle_de_oferta/informacoes_boletins_de_subscricao#investor)** e **[Financial Application Event](/documentation/iaas/passivo/controle_de_oferta/informacoes_boletins_de_subscricao#financial-application-event)** pode ser consultada na página **[Informações sobre Boletim de Subscrição](/documentation/iaas/passivo/controle_de_oferta/informacoes_boletins_de_subscricao)**.

---

# Recuperando Cotas Públicas

URL: /documentation/iaas/passivo/fundos/cotas_publicas

---

### Request

ENDPOINT /public_dash/mark_to_market/fund_quota/mark_to_markets
METHOD GET
STATUS 200

### Query Params

| Parâmetro                   |  Tipo    | Descrição                                                                             |
|-----------------------------|----------|---------------------------------------------------------------------------------------|
| `internal_codes`            |  list    | Lista de códigos internos da série de emissão para filtro exato dos registros.        |
| `from_reference_date`       |  string  | Data de início do período a ser consultado (YYYY-MM-DD)                               |
| `to_reference_date`         |  string  | Data do fim do período a ser consultado (YYYY-MM-DD)                                  |
| `internal_code`             |  string  | Código único da série de emissão a ser consultada                                     |
| `fund_class_document_number`|  string  | CNPJ (com pontuação) do fundo a ser consultado                                        |
| `limit`                     |  int     | Limite de objetos recuperados por página                                              |
| `page`                      |  int     | Número da página recuperada                                                           |

:::warning Atenção
O valor de cota se encontra a nível de **série de emissão (issuance_serie)** e portanto o uso do parâmetro **fund_class_document_number** implica no retorno de todas as séries.
Recomenda-se o uso desse filtro apenas para o mapeamento de identificadores únicos das séries de emissão (**internal_code** e **issuance_serie_key**).
:::

### Response
```json title='Response Body'
{
   "data": [
      {
         "issuance_serie_key": "1de4125b-48c7-40ca-b97b-0b65fb356468",
         "internal_code": "INTERNAL-CODE-2",
         "fund_class_document_number": "12.345.678/0001-95",
         "fund_class_name": "FUNDO DE INVESTIMENTO DE TESTES",
         "marks_to_market": [
            {
               "reference_date": "2025-09-05",
               "before_amortization_unit_price": 1000,
               "unit_price": 1000
            }
         ]
      },
      {
         "issuance_serie_key": "71f7ee44-388d-4916-b068-647e82fd67c8",
         "internal_code": "INTERNAL-CODE-1",
         "fund_class_document_number": "12.345.678/0001-95",
         "fund_class_name": "FUNDO DE INVESTIMENTO DE TESTES",
         "marks_to_market": [
            {
               "reference_date": "2025-09-04",
               "before_amortization_unit_price": 1000,
               "unit_price": 1000
            }
         ]
      }
   ],
   "limit": 5,
   "page": 0,
   "is_last_page": true
}
```

### Issuance Serie

| Campo                             | Tipo   | Descrição                                                    |
|-----------------------------------|--------|--------------------------------------------------------------|
| `issuance_serie_key`              | string | Chave que identifica a série de emissão                      |
| `internal_code`                   | string | Código que identifica a série de emissão internamente        |
| `fund_class_document_number`      | string | CNPJ do fundo de investimento consultado                     |
| `fund_class_name`                 | string | Nome do fundo de investimento consultado                     |
| `marks_to_market`                 | array  | Lista de objetos de **[Marks To Market](#marks-to-market)**                                  |

### Marks To Market

| Campo                             | Tipo   | Descrição                                                    |
|-----------------------------------|--------|--------------------------------------------------------------|
| `reference_date`                  | string | Data do valor de cota da série de emissão (YYYY-MM-DD)       |
| `before_amortization_unit_price`  | float  | O valor da cota da série de emissão antes de uma amortização |
| `unit_price`                      | float  | O valor da cota da série de emissão após o fechamento        |

---

# Introdução

URL: /documentation/iaas/passivo/inicio

Bem-vindo à documentação de integração para operações relacionadas ao **Passivo**. Nesta seção, apresentamos todas as ferramentas e recursos necessários para interagir com os serviços oferecidos, desde o cadastro de investidores até a execução de operações financeiras.

## Visão Geral

A API de Passivo oferece um conjunto de funcionalidades para facilitar a gestão e execução de operações financeiras para fundos de investimento. Com ela, é possível realizar o cadastro de investidores, aplicações financeiras, pedidos de resgate, bloqueio de cotas e outras operações essenciais para o gerenciamento de ativos.

Os serviços são disponibilizados por meio de endpoints que permitem a comunicação segura e eficiente entre as aplicações dos clientes e a plataforma.

### Acesso aos Serviços

Para obter acesso aos serviços, é necessário realizar as liberações necessárias em nossos ambientes de Homologação (Sandbox) e Produção. Entre em contato com o time de integração pelo e-mail [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) para solicitar as credenciais de acesso e receber orientações sobre o processo de ativação.

## Recursos Disponíveis

### Cadastro do Investidor

- **Criar investidor / análise do investidor**: Permite o cadastro de um investidor e a análise cadastral inicial. Descrito em: [5.9.2.1 Criar investidor](/documentation/iaas/investidor/cadastro/criar_investidor)
- **Buscar informações do investidor**: Consulta informações cadastrais de um investidor. Descrito em: [5.9.2.2 Buscar informações do investidor](/documentation/iaas/investidor/cadastro/busca_informacoes_do_investidor)
- **Buscar informações de uma análise cadastral do investidor**: Permite consultar o status da análise cadastral de um investidor. Descrito em: [5.9.2.3 Buscar análise cadastral](/documentation/iaas/investidor/cadastro/busca_informacoes_de_uma_analise_cadastral_do_investidor)
- **Enviar dados cadastrais**: Envia dados cadastrais complementares para análise. Descrito em: [5.9.2.4 Enviar dados cadastrais](/documentation/iaas/investidor/cadastro/enviar_dados_cadastrais)

### Aplicação Financeira

- **Criar Aplicação Financeira**: Permite criar uma aplicação financeira em uma série de emissão. Descrito em: [5.9.5.1 Criar Aplicação Financeira](/documentation/iaas/passivo/aplicacao_financeira/criar_aplicacao_financeira)
- **Consultar Aplicação Financeira**: Permite consultar aplicações financeiras por chave ou através de busca paginada. Descrito em: [5.9.5.2 Consulta por chave](/documentation/iaas/passivo/aplicacao_financeira/buscar_aplicacao_financeira_por_chave) e [5.9.5.3 Consulta paginada](/documentation/iaas/passivo/aplicacao_financeira/busca_paginada_aplicacoes_financeiras)

### Pedido de Resgate

- **Criar Pedido de Resgate**: Permite criar um pedido de resgate para um investidor. Descrito em: [5.9.6.1 Criar Pedido de Resgate](/documentation/iaas/passivo/pedido_de_resgate/criar_pedido_de_resgate)
- **Consultar Pedido de Resgate**: Consulta pedidos de resgate por chave ou através de busca paginada. Descrito em: [5.9.6.2 Consulta por chave](/documentation/iaas/passivo/pedido_de_resgate/buscar_pedido_de_resgate_por_chave), [5.9.6.3 Consulta paginada por investidor](/documentation/iaas/passivo/pedido_de_resgate/consulta_pedidos_resgate_investidor) e [5.9.6.4 Consulta paginada por classe de fundo](/documentation/iaas/passivo/pedido_de_resgate/consulta_pedidos_resgate_classe_fundo)

### Bloqueio de Cotas

- **Solicitar Bloqueio de Cotas**: Permite solicitar o bloqueio de cotas para garantia. Descrito em: [5.9.8.1 Solicitar Bloqueio de Cotas](/documentation/iaas/passivo/bloqueio_de_cotas/solicitar_bloqueio_de_cotas)
- **Consultar Bloqueios de Cotas**: Consulta bloqueios de cotas por investidor ou de forma paginada. Descrito em: [5.9.8.2 Consultar bloqueios de cotas](/documentation/iaas/passivo/bloqueio_de_cotas/consulta_de_bloqueio_de_cotas)

## Conclusão

Essa documentação serve como guia completo para integração e utilização dos serviços de Passivo. Em caso de dúvidas, entre em contato com nossa equipe de suporte pelo e-mail [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br).

---

# Consulta paginada de negociações em mercado secundário

URL: /documentation/iaas/passivo/mercado_secundario/consulta_negociacoes_mercado_secundario

Endpoint de consulta paginada que retorna as **negociações de cotas em mercado secundário** de uma classe de fundo. Cada registro representa a transferência de uma quantidade de cotas de um cotista vendedor para um cotista comprador, com o valor de cota praticado na negociação e a tributação retida do vendedor.

Cada negociação relaciona três aplicações financeiras:

| Papel | Descrição |
|---|---|
| `sold_financial_application` | Aplicação do **vendedor**, da qual as cotas saíram. É por ela que os filtros de classe de fundo, série, investidor e depositária central são aplicados. |
| `new_financial_application` | Aplicação criada para o **comprador**, com `financial_application_type` igual a `secondary_market`. |
| `original_financial_application` | Aplicação que **originou a posição** no mercado primário. Em revendas sucessivas, a mesma aplicação original é propagada para todas as negociações da cadeia, permitindo rastrear a entrada original das cotas. |

## Request

ENDPOINT /quota/fund_class/{fund_class_key}/secondary_market_trades
MÉTODO GET

### Query params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `page` | integer | opcional | Número da página (começa em `0`). Padrão: `0`. |
| `limit` | integer | opcional | Quantidade de registros por página. Padrão: `50`. Máximo: `500`. |
| `issuance_serie_key` | string | opcional | Filtra pelas negociações da série de emissão informada. |
| `investor_key` | string | opcional | Filtra pelas negociações em que o investidor informado é o **vendedor**. |
| `sold_financial_application_key` | string | opcional | Filtra pela aplicação financeira de origem das cotas negociadas. |
| `central_depositary` | string | opcional | Filtra pela depositária central da aplicação de origem. Valores: `cetip` (cotas depositadas na B3) ou `unregistered` (cotas não depositadas). |

Os registros são retornados em ordem cronológica de criação da negociação.

```python title="Exemplo de chamada"
GET /quota/fund_class/{fund_class_key}/secondary_market_trades?page=0&limit=50&issuance_serie_key=c3d4e5f6-a7b8-9012-cdef-123456789012&central_depositary=cetip
```

## Response

STATUS 200

```json title="Response Body"
{
  "data": [
    {
      "secondary_market_trade_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "original_financial_application": {
        "financial_application_key": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "share_capital": 500000.0,
        "status": "quoted",
        "redemption_keys": [
          {
            "redemption_key": "c3d4e5f6-a7b8-9012-cdef-123456789012"
          }
        ],
        "financial_application_type": "primary_market",
        "original_number_of_quotas": 500000.0,
        "current_principal_value": 490000.0,
        "acquisition_cost": 500000.0,
        "current_number_of_quotas": 490000.0,
        "quotation_date": "2026-03-02",
        "payment_method": "b3",
        "investor_key": "d4e5f6a7-b8c9-0123-def0-234567890123",
        "issuance_serie_key": "e5f6a7b8-c9d0-1234-ef01-345678901234",
        "external_id": "ext-fa-001"
      },
      "sold_financial_application": {
        "financial_application_key": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "share_capital": 500000.0,
        "status": "quoted",
        "redemption_keys": [
          {
            "redemption_key": "c3d4e5f6-a7b8-9012-cdef-123456789012"
          }
        ],
        "financial_application_type": "primary_market",
        "original_number_of_quotas": 500000.0,
        "current_principal_value": 490000.0,
        "acquisition_cost": 500000.0,
        "current_number_of_quotas": 490000.0,
        "quotation_date": "2026-03-02",
        "payment_method": "b3",
        "investor_key": "d4e5f6a7-b8c9-0123-def0-234567890123",
        "issuance_serie_key": "e5f6a7b8-c9d0-1234-ef01-345678901234",
        "external_id": "ext-fa-001"
      },
      "new_financial_application": {
        "financial_application_key": "f6a7b8c9-d0e1-2345-f012-456789012345",
        "share_capital": 10523.45,
        "status": "quoted",
        "redemption_keys": [],
        "financial_application_type": "secondary_market",
        "original_number_of_quotas": 10000.0,
        "current_principal_value": 1.05234567,
        "acquisition_cost": 1.05234567,
        "current_number_of_quotas": 10000.0,
        "quotation_date": "2026-03-02",
        "payment_method": "b3",
        "investor_key": "a7b8c9d0-e1f2-3456-0123-567890123456",
        "issuance_serie_key": "e5f6a7b8-c9d0-1234-ef01-345678901234"
      },
      "trade_quota_value": 1.05234567,
      "number_of_quotas": 10000.0,
      "event_datetime": "2026-07-31 00:00:00",
      "taxable_yield_value": 523.45,
      "ir_value": 78.52,
      "iof_value": 0.0
    }
  ],
  "limit": 50,
  "page": 0,
  "is_last_page": true
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Lista de negociações da classe de fundo. |
| `page` | integer | Página atual. |
| `limit` | integer | Tamanho da página solicitado. |
| `is_last_page` | boolean | Indica se não há mais registros após esta página. |

#### Objeto em `data`

| Campo | Tipo | Descrição |
|---|---|---|
| `secondary_market_trade_key` | string | Chave única da negociação. |
| `original_financial_application` | object | Aplicação financeira que originou a posição no mercado primário. |
| `sold_financial_application` | object | Aplicação financeira do vendedor, de onde saíram as cotas. |
| `new_financial_application` | object | Aplicação financeira criada para o comprador. |
| `trade_quota_value` | number | Valor de cota praticado na negociação. |
| `number_of_quotas` | number | Quantidade de cotas negociadas. |
| `event_datetime` | string | Data e hora do evento de negociação. |
| `taxable_yield_value` | number | Rendimento tributável apurado para o vendedor na negociação. Omitido quando não apurado. |
| `ir_value` | number | Imposto de renda retido do vendedor. Omitido quando não apurado. |
| `iof_value` | number | IOF retido do vendedor. Omitido quando não apurado. |

#### Objeto de aplicação financeira

| Campo | Tipo | Descrição |
|---|---|---|
| `financial_application_key` | string | Chave única da aplicação financeira. |
| `share_capital` | number | Valor aportado na aplicação. |
| `status` | string | Situação da aplicação, por exemplo `quoted`, `settled`, `redeemed`. |
| `redemption_keys` | array | Chaves dos resgates associados à aplicação. Na aplicação do vendedor inclui o resgate gerado pela negociação. |
| `financial_application_type` | string | `primary_market` ou `secondary_market`. |
| `original_number_of_quotas` | number | Quantidade de cotas na criação da aplicação. |
| `current_number_of_quotas` | number | Quantidade de cotas atual. |
| `current_principal_value` | number | Valor principal atual. |
| `acquisition_cost` | number | Custo de aquisição. |
| `quotation_date` | string | Data de cotização. |
| `payment_method` | string | Forma de liquidação, por exemplo `b3` ou `regular`. |
| `investor_key` | string | Chave do investidor titular da aplicação. |
| `issuance_serie_key` | string | Chave da série de emissão da aplicação. |
| `external_id` | string | Identificador externo, quando informado no cadastro da aplicação. |

Campos opcionais são omitidos da resposta quando não houver valor.

Para consultar as aplicações financeiras em detalhe, consulte [Consulta paginada de aplicações financeiras](/documentation/iaas/passivo/aplicacao_financeira/busca_paginada_aplicacoes_financeiras).

## Possíveis erros

STATUS 404

**Classe de fundo não encontrada**

```json
{
  "title": " Fund Class not Found",
  "description": "Fund Class with key {fund_class_key} was not found.",
  "translation": "A classe com chave {fund_class_key} não foi encontrado.",
  "code": "QTA000002"
}
```

STATUS 400

**Classe de fundo não pertence ao gestor autenticado**

A consulta só retorna negociações de classes de fundo cujo gestor é o titular da integração utilizada na chamada.

```json
{
  "title": "Invalid selected agent",
  "description": "Invalid selected agent",
  "translation": "Selected agent invalido",
  "code": "QIT000004"
}
```

---

# Consultar Pedido de Resgate por chave

URL: /documentation/iaas/passivo/pedido_de_resgate/buscar_pedido_de_resgate_por_chave

---

### Request

ENDPOINT /quota/investor/INVESTOR_KEY/redemption_request/REDEMPTION_REQUEST_KEY
MÉTODO GET
STATUS 200

### Responses

Caso 01: Consulta bem-sucedida

```json
{
    "redemption_request_key": "UUID",
    "redemption_request_type": "gross_redemption_value" | "number_of_quotas" | "remaining_application_value",
    "status": "pending_quote" | "processing_quote" | "canceled" | "quoted",
    "quotation_date": "yyyy-mm-dd",
    "payment_date":"yyyy-mm-dd",
    "request_datetime":"yyyy-mm-dd HH:MM:SS:MS",
    "processed_value": 0.00,
    "investor_position": {
        "investor": {
            "investor_key": "UUID",
            "document_number": "999.999.999-99" | "99.999.999/9999-99",
            "name": "",
            "person_type": "natural_person" | "legal_person",
            "account_data": {
                "owner": {
                    "name": "",
                    "document_number": "99.999.999/9999-99"
                },
                "account_digit": "0",
                "account_branch": "0000",
                "account_number": "00000",
                "financial_institution_code": "000",
                "financial_institution_ispb": "00000000"
            },
            "distributor": {
                "distributor_key": "UUID",
                "document_number": "99.999.999/9999-99",
                "name": "",
                "account_data": {
                    "owner": {
                        "name": "",
                        "document_number": "99.999.999/9999-99"
                    },
                    "account_digit": "0",
                    "account_branch": "0000",
                    "account_number": "00000",
                    "financial_institution_code": "000",
                    "financial_institution_ispb": "00000000"
                },
            }
        },
        "total_net_worth": 0.00,
        "total_number_of_quotas": 0.00000000,
        "investor_position_key":"UUID",
        "issuance_serie":{
            "name":"1",
            "cetip_code":"0000000SN1",
            "start_date":"YYYY-MM-DD",
            "maturity_date":"YYYY-MM-DD",
            "original_quota_value":0.00000000000000,
            "remuneration_type":"yield_curve",
            "interest_rate_type":"post_fixed",
            "pre_fixed":{
               "calendar_base":"workdays / calendar_360 / calendar_365",
               "monthly_rate":0.00000000000000
            },
            "post_fixed":{
               "calendar_base":"workdays / calendar_360 / calendar_365",
               "indexer":"di / ipca",
               "rate":1,
               "lag":{
                  "reference":"daily / monthly",
                  "amount":1
               }
            },
            "investment_category":"fidc / multi_market",
            "condominum_type":"open_ended / close_ended",
            "tax_classification":"short_term / long_term",
            "investment_restriction_type":"just_professional",
            "issuance_serie_key":"UUID",
            "minimum_share_capital":0.0,
            "accounting_date":"YYYY-MM-DD",
            "sub_class":{
               "name":"COTA SÊNIOR",
               "sub_class_key":"UUID",
               "subordination_level":1,
               "fund_class":{
                  "name":"SAMPLE FUND CLASS NAME",
                  "fund_class_key":"UUID",
                  "document_number":"00.000.000/0000-00"
               }
            }
        }
    },
    "status_events": [
        {
            "event_datetime": "yyyy-mm-dd HH:MM:SS:ms",
            "status": "pending_quote" | "processing_quote" | "canceled" | "quoted",
        }
    ],
}
```

### Redemption Request
| Campo                         | Tipo     | Descrição                                                                       | Caracteres |
|-------------------------------|----------|---------------------------------------------------------------------------------|------------|
| `redemption_request_key`      | string   | Chave única de identificação do pedido de resgate                               | 36         |
| `redemption_request_type`     | string   | Enumerador de **[Redemption Request Type](#redemption_request_type)**           | -          |             
| `status`                      | string   | Enumerador de **[Redemption Request Status](#redemption_request_status)**       | -          |
| `quotation_date`              | string   | Data da cotização                                                               | -          |
| `payment_date`                | string   | Data do pagamento                                                               | -          |
| `request_datetime`            | string   | Data da criação do pedido do resgate                                            | -          |
| `processed_value`             | float    | Valor processado do resgate                                                     | -          |
| `investor_position`           | JSON     | Objeto de **[Investor Position](#investor_position)**                           | -          |
| `status_events`               | array    | Lista de objetos de **[Status Event](#status_event)**                           | -          |

### Redemption Request Type {#redemption_request_type}
| Enumerador                     | Descrição                                       |
|--------------------------------|-------------------------------------------------|
| `gross_redemption_value`       | Resgate por valor bruto                         |
| `number_of_quotas`             | Resgate por número de cotas                     |
| `remaining_application_value`  | Resgate por valor restate                       |

### Redemption Request Status {#redemption_request_status}
| Enumerador               | Descrição                                       |
|--------------------------|-------------------------------------------------|
| `pending_quote`          | Pendente pagamento                              |
| `processing_quote`       | Pendente cotização                              |
| `quoted`                 | Cotizado                                        |
| `canceled`               | Totalmente amortizado                           |

### Investor Position {#investor_position}
| Campo                    | Tipo   | Descrição                                             |
|--------------------------|--------|-------------------------------------------------------|
| `investor`               | JSON   | Objeto de **[Investor](#investor)**                   |
| `total_net_worth`        | float  | Patrimônio Líquido da posição do investidor           |
| `total_number_of_quotas` | float  | Número de cotas da posição do investidor              |
| `issuance_serie`         | JSON   | Objeto de **[Issuance Serie](#issuance_serie)**       |
| `investor_position_key`  | JSON   | Chave única de identificação da posição do investidor |

### Status Event {#status_event}
| Campo            | Tipo     | Descrição                                                      |
|------------------|----------|----------------------------------------------------------------|
| `status`         | string   | Status do evento                                               |
| `event_datetime` | string   | Data e hora do evento                                          |

### Investor
| Campo                    | Tipo     | Descrição                                         | Caracteres |
|--------------------------|----------|---------------------------------------------------|------------|
| `name`                   | string   | Nome do investidor                                | até 255    |
| `investor_key`           | string   | Chave única de identificação do investidor        | 36         |
| `document_number`        | string   | CPF/CNPJ do investidor                            | 14 ou 18   |
| `person_type`            | string   | Pessoa Física / Pessoa Jurídica / Classe de Fundo | até 50     |
| `distributor`            | JSON     | Objeto de **[Distributor](#distributor)**         |     -      |             
| `account_data`           | JSON     | Objeto de **[Account Data](#account_data)**       |     -      |

### Distributor
| Campo                    | Tipo     | Descrição                                         | Caracteres |
|--------------------------|----------|---------------------------------------------------|------------|
| `name`                   | string   | Nome do distribuidor                              | até 255    |
| `distributor_key`        | string   | Chave única de identificação do distribuidor      |     -      |             
| `document_number`        | string   | CPF/CNPJ do distribuidor                          | 14 ou 18   |
| `account_data`           | JSON     | Objeto de **[Account Data](#account_data)**       |     -      |

### Account Data {#account_data}
| Campo                        | Tipo     | Descrição                                                                   |
|------------------------------|----------|-----------------------------------------------------------------------------|
| `account_digit`              | string   | Dígito da conta bancária                                                    |
| `account_branch`             | string   | N° da agência da conta bancária                                             |             
| `account_number`             | string   | N° da conta bancária                                                        |
| `financial_institution_code` | string   | Código da instituição financeira                                            |
| `financial_institution_ispb` | string   | Identificador no Sistema de Pagamento Brasileiro da instituição financeira  |

### Issuance Serie {#issuance_serie}
| Campo                         | Tipo     | Descrição                                         | Caracteres |
|-------------------------------|----------|---------------------------------------------------|------------|
| `name`                        | string   | Nome da série de emissão                          | até 255    |
| `issuance_serie_key`          | string   | Chave única de identificação da série de emissão  | 36         |
| `cetip_code`                  | string   | Código da série de emissão como ativo na CETIP    | 10         |             
| `start_date`                  | string   | Data de início da série de emissão                | 10         |
| `maturity_date`               | string   | Data de vencimento da série de emissão            | 10         |
| `original_quota_value`        | float    | Valor de cota original                            | -          |
| `remuneration_type`           | string   | Curva de rendimento / Residual                    | até 50     |
| `investment_category`         | string   | FIDC / Multimercado                               | até 50     |
| `condominum_type`             | string   | Aberto / Fechado                                  | até 50     |
| `tax_classification`          | string   | Curto prazo / Longo prazo                         | até 50     |
| `investment_restriction_type` | string   | Sem restrição / Qualificado / Profissional        | até 50     |
| `minimum_share_capital`       | float    | Valor mínimo para aplicação                       | -          |
| `accounting_date`             | string   | Data contábil da série de emissão                 | 10         |
| `sub_class`                   | JSON     | Objeto de **[Sub Class](#sub_class)**             | -          |

### Sub Class {#sub_class}
| Campo                         | Tipo     | Descrição                                         | Caracteres |
|-------------------------------|----------|---------------------------------------------------|------------|
| `name`                        | string   | Nome da sub classe                                | até 255    |
| `sub_class_key`               | string   | Chave única de identificação da sub classe        | 36         |
| `subordination_level`         | int      | Nível de subordinação da sub classe               | -          |             
| `fund_class`                  | JSON     | Objeto de **[Fund Class](#fund_class)**           | -          |

### Fund Class {#fund_class}
| Campo                         | Tipo     | Descrição                                         | Caracteres |
|-------------------------------|----------|---------------------------------------------------|------------|
| `name`                        | string   | Nome da classe de fundo                           | até 255    |
| `fund_class_key`              | string   | Chave única de identificação da classe de fundo   | 36         |
| `document_number`             | string   | CNPJ da classe de fundo                           | -          |

---

# Consulta paginada de pedidos de resgate por classe de fundo

URL: /documentation/iaas/passivo/pedido_de_resgate/consulta_pedidos_resgate_classe_fundo

Lista **pedidos de resgate** vinculados a uma **classe de fundo** (`fund_class_key`), com paginação. Permite filtrar por **status**, **data de cotização** e **documento do investidor**.

## Request

ENDPOINT /quota/fund_class/{fund_class_key}/redemption_requests
MÉTODO GET

### Query params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `page` | integer | opcional | Número da página (começa em `0`). Padrão: `0`. |
| `limit` | integer | opcional | Registros por página. Padrão: `20`. Máximo: `500`. |
| `quotation_date` | string | opcional | Filtra pela data de cotização (`YYYY-MM-DD`). |
| `investor_document_number` | string | opcional | Filtra pelo documento do investidor (com pontuação). |
| `request_from_datetime` | string (date-time) | opcional | Retorna apenas os pedidos com data/hora de solicitação maior ou igual ao valor informado. Formato ISO 8601 com Z (`YYYY-MM-DDTHH:MM:SSZ`). |
| `request_to_datetime` | string (date-time) | opcional | Retorna apenas os pedidos com data/hora de solicitação menor ou igual ao valor informado. Formato ISO 8601 com Z (`YYYY-MM-DDTHH:MM:SSZ`). |

```python title="Exemplo de chamada"
GET /quota/fund_class/{fund_class_key}/redemption_requests?page=0&limit=50&investor_document_number=12.345.678/0001-90
```

## Response

STATUS 200

```json title="Response Body"
{
  "data": [
    {
      "redemption_request_key": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "quotation_date": "2024-06-15",
      "payment_date": "2024-06-18",
      "redemption_request_type": "number_of_quotas",
      "request_datetime": "2024-06-10T14:00:00.000000Z",
      "status": "quoted",
      "redemption_request_data": {
        "number_of_quotas": 500.0
      },
      "processed_value": 5250.5,
      "ir_value": 0.0,
      "iof_value": 0.0,
      "issuance_serie": {
        "issuance_serie_key": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "original_quota_value": 1.0,
        "current_number_of_quotas": 499500.0,
        "current_net_worth": 524475.25,
        "current_principal_value": 499500.0,
        "performance_fee_current_value": 0.0,
        "remuneration_type": "yield_curve",
        "minimum_share_capital": 1000.0,
        "interest_rate_type": "post_fixed",
        "name": "Série Única",
        "serie": 1,
        "sub_class": {
          "name": "Cota Sênior",
          "sub_class_key": "d4e5f6a7-b8c9-0123-def0-234567890123",
          "subordination_level": 1,
          "fund_class": {
            "name": "Fundo Exemplo FIDC",
            "short_name": "FEX",
            "document_number": "12.345.678/0001-90",
            "fund_class_key": "e5f6a7b8-c9d0-1234-ef01-345678901234",
            "accounting_date": "2024-06-01",
            "sub_type": "fidc",
            "tax_classification_id": "long_term",
            "condominum_type_id": "open_ended",
            "investment_category_id": "fidc",
            "prevent_payment": false,
            "integralization_account_key": null,
            "manager": {
              "manager_key": "f6a7b8c9-d0e1-2345-f012-456789012345",
              "document_number": "98.765.432/0001-10",
              "manager_name": "Gestora Exemplo S.A."
            }
          }
        },
        "status": "active",
        "internal_code": "INT-FEX-01",
        "processing_method": "standard",
        "operation_period_configuration": {},
        "current_quota_value": 1.05000055,
        "post_fixed": {
          "calendar_base": "calendar_252",
          "indexer": "cdi",
          "rate": 1.0,
          "lag": {
            "reference": "daily",
            "amount": 1
          }
        },
        "isin_code": "BRSTREXTFID6",
        "external_id": null,
        "specific_interest_rate_data": null
      },
      "investor": {
        "distributor": {
          "distributor_key": "3571e292-3a83-4011-904d-20ee963022ef",
          "document_number": "12.345.678/0001-90",
          "name": "Distribuidora Exemplo S.A.",
          "account_data": {
            "owner": {
              "name": "Distribuidora Exemplo S.A.",
              "document_number": "12.345.678/0001-90"
            },
            "account_digit": "1",
            "account_branch": "0001",
            "account_number": "12345",
            "financial_institution_code": "341",
            "financial_institution_ispb": "60746948"
          }
        },
        "investor_key": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "name": "Maria Cotista Silva",
        "person_type": "natural_person",
        "document_number": "123.456.789-00",
        "external_id": "ext-inv-001",
        "external_distribution_key": null
      },
      "status_events": [
        {
          "status": "pending_quote",
          "event_datetime": "2024-06-10T14:00:01.000000Z"
        },
        {
          "status": "quoted",
          "event_datetime": "2024-06-15T18:30:00.000000Z"
        }
      ]
    }
  ],
  "limit": 20,
  "page": 0,
  "is_last_page": true
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Pedidos de resgate. |
| `page` | integer | Página atual. |
| `limit` | integer | Tamanho da página. |
| `is_last_page` | boolean | Última página da consulta. |

#### Campos principais de cada pedido em `data`

| Campo | Tipo | Descrição |
|---|---|---|
| `redemption_request_key` | string | Identificador único do pedido (UUID). |
| `redemption_request_type` | string | Tipo do pedido — veja [Tipos de pedido](#tipos-de-pedido-de-resgate). |
| `status` | string | Status atual — veja [Status do pedido](#status-do-pedido-de-resgate). |
| `quotation_date` | string | Data de cotização (`YYYY-MM-DD`). |
| `payment_date` | string | Data prevista/realizada de pagamento (`YYYY-MM-DD`). |
| `request_datetime` | string | Momento da solicitação (ISO 8601 com sufixo Z quando aplicável). |
| `processed_value` | number | Valor processado (quando aplicável). |
| `ir_value` / `iof_value` | number | Retenções quando aplicáveis. |
| `redemption_request_data` | object | Payload específico do tipo de resgate (valores solicitados, cotas, etc.). |
| `issuance_serie` | object | Série de emissão vinculada. |
| `investor` | object | Dados do investidor e distribuidora. |
| `status_events` | array | Histórico de mudanças de status. |

## Tipos de pedido de resgate

| Valor | Descrição |
|---|---|
| `gross_redemption_value` | Resgate por valor bruto. |
| `number_of_quotas` | Resgate por quantidade de cotas. |
| `remaining_application_value` | Resgate do valor remanescente da aplicação. |
| `net_value_redemption` | Resgate por valor líquido. |

## Status do pedido de resgate

| Status | Descrição resumida |
|---|---|
| `created` | Criado. |
| `pending_manager_approval` | Aguardando aprovação do gestor. |
| `pending_quote` | Aguardando cotização. |
| `processing_quotation` | Cotização em processamento. |
| `pending_quotation_date_input` | Aguardando informação de data de cotização. |
| `quoted` | Cotizado. |
| `canceled` | Cancelado. |
| `reprocessed` | Reprocessado. |

## Objetos da resposta

### Issuance Serie (`issuance_serie`)
| Campo | Tipo | Descrição |
|---|---|---|
| `issuance_serie_key` | string | Chave única de identificação da série de emissão |
| `name` | string | Nome da série de emissão |
| `serie` | int | Número da série |
| `original_quota_value` | float | Valor da cota original |
| `current_quota_value` | float | Valor atual da cota |
| `current_number_of_quotas` | float | Quantidade atual de cotas |
| `current_net_worth` | float | Patrimônio líquido atual |
| `current_principal_value` | float | Valor de principal atual |
| `performance_fee_current_value` | float | Valor atual de taxa de performance |
| `minimum_share_capital` | float | Valor mínimo para aplicação |
| `remuneration_type` | string | Tipo de remuneração (ex.: `yield_curve`) |
| `interest_rate_type` | string | Tipo de taxa (`post_fixed` / `pre_fixed`) |
| `post_fixed` / `pre_fixed` | object | Dados de remuneração (`calendar_base`, `indexer`, `rate`, `lag`) |
| `status` | string | Status da série de emissão (ex.: `active`) |
| `internal_code` | string | Código interno da série |
| `isin_code` | string | Código ISIN |
| `processing_method` | string | Método de processamento |
| `operation_period_configuration` | object | Configuração de períodos de operação |
| `external_id` | string | Identificador externo |
| `sub_class` | object | Objeto **Sub Class** |

### Sub Class (`sub_class`)
| Campo | Tipo | Descrição |
|---|---|---|
| `name` | string | Nome da subclasse |
| `sub_class_key` | string | Chave única de identificação da subclasse |
| `subordination_level` | int | Nível de subordinação da subclasse |
| `fund_class` | object | Objeto **Fund Class** |

### Fund Class (`fund_class`)
| Campo | Tipo | Descrição |
|---|---|---|
| `name` | string | Nome da classe de fundo |
| `short_name` | string | Nome curto da classe de fundo |
| `fund_class_key` | string | Chave única de identificação da classe de fundo |
| `document_number` | string | CNPJ da classe de fundo |
| `accounting_date` | string | Data contábil da classe de fundo |
| `sub_type` | string | Subtipo (ex.: `fidc`) |
| `tax_classification_id` | string | Classificação tributária (ex.: `long_term`) |
| `condominum_type_id` | string | Tipo de condomínio (ex.: `open_ended`) |
| `investment_category_id` | string | Categoria de investimento (ex.: `fidc`) |
| `prevent_payment` | boolean | Indica se os pagamentos estão bloqueados |
| `integralization_account_key` | string | Chave da conta de integralização |
| `manager` | object | Objeto **Manager** |

### Manager (`manager`)
| Campo | Tipo | Descrição |
|---|---|---|
| `manager_key` | string | Chave única de identificação do gestor |
| `document_number` | string | CNPJ do gestor |
| `manager_name` | string | Nome do gestor |

### Investor (`investor`)
| Campo | Tipo | Descrição |
|---|---|---|
| `investor_key` | string | Chave única de identificação do investidor |
| `name` | string | Nome do investidor |
| `document_number` | string | CPF/CNPJ do investidor |
| `person_type` | string | Tipo de pessoa (`natural_person` / `legal_person`) |
| `external_id` | string | Identificador externo do investidor |
| `external_distribution_key` | string | Chave de distribuição externa |
| `distributor` | object | Objeto **Distributor** |

### Distributor (`distributor`)
| Campo | Tipo | Descrição |
|---|---|---|
| `distributor_key` | string | Chave única de identificação do distribuidor |
| `name` | string | Nome do distribuidor |
| `document_number` | string | CNPJ do distribuidor |
| `account_data` | object | Objeto **Account Data** |

### Account Data (`account_data`)
| Campo | Tipo | Descrição |
|---|---|---|
| `owner` | object | Titular da conta (`name`, `document_number`) |
| `account_digit` | string | Dígito da conta bancária |
| `account_branch` | string | N° da agência da conta bancária |
| `account_number` | string | N° da conta bancária |
| `financial_institution_code` | string | Código da instituição financeira |
| `financial_institution_ispb` | string | Identificador no Sistema de Pagamento Brasileiro (ISPB) da instituição financeira |

## Possíveis erros

STATUS 404

**Classe de fundo não encontrada**

```json
{
  "title": " Fund Class not Found",
  "description": "Fund Class with key {fund_class_key} was not found.",
  "translation": "A classe com chave {fund_class_key} não foi encontrado.",
  "code": "QTA000002"
}
```

---

# Consulta paginada de pedidos de resgate por investidor

URL: /documentation/iaas/passivo/pedido_de_resgate/consulta_pedidos_resgate_investidor

Retorna os **pedidos de resgate** de um investidor identificado por `investor_key`, com paginação e filtros opcionais por **status** e **data de cotização**. A lista é ordenada por fundo, subclasse, série e data de cotização (mais recente primeiro).

## Request

ENDPOINT /quota/investor/{investor_key}/redemption_requests
MÉTODO GET

### Query params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `page` | integer | opcional | Número da página (começa em `0`) |
| `limit` | integer | opcional | Registros por página. Padrão: `20`. Máximo: `500`. |
| `status` | array de strings | opcional | Um ou mais valores de status do pedido (veja [Status do pedido de resgate](#status-do-pedido-de-resgate)). Repita o parâmetro ou use o formato aceito pela plataforma para listas. |
| `quotation_date` | string | opcional | Filtra pela data de cotização no formato `YYYY-MM-DD`. |
| `fund_class_document_number` | string | opcional | Filtra pelo documento (CNPJ) da classe de fundo. |
| `request_from_datetime` | string (date-time) | opcional | Retorna apenas os pedidos com data/hora de solicitação maior ou igual ao valor informado. Formato ISO 8601 com Z (`YYYY-MM-DDTHH:MM:SSZ`). |
| `request_to_datetime` | string (date-time) | opcional | Retorna apenas os pedidos com data/hora de solicitação menor ou igual ao valor informado. Formato ISO 8601 com Z (`YYYY-MM-DDTHH:MM:SSZ`). |

```python title="Exemplo de chamada"
GET /quota/investor/{investor_key}/redemption_requests?page=0&limit=20&status=quoted&quotation_date=2024-06-15
```

## Response

STATUS 200

```json title="Response Body"
{
  "data": [
    {
      "redemption_request_key": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "quotation_date": "2024-06-15",
      "payment_date": "2024-06-18",
      "redemption_request_type": "number_of_quotas",
      "request_datetime": "2024-06-10T14:00:00.000000Z",
      "status": "quoted",
      "redemption_request_data": {
        "number_of_quotas": 500.0
      },
      "processed_value": 5250.5,
      "ir_value": 0.0,
      "iof_value": 0.0,
      "issuance_serie": {
        "issuance_serie_key": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "original_quota_value": 1.0,
        "current_number_of_quotas": 499500.0,
        "current_net_worth": 524475.25,
        "current_principal_value": 499500.0,
        "performance_fee_current_value": 0.0,
        "remuneration_type": "yield_curve",
        "minimum_share_capital": 1000.0,
        "interest_rate_type": "post_fixed",
        "name": "Série Única",
        "serie": 1,
        "sub_class": {
          "name": "Cota Sênior",
          "sub_class_key": "d4e5f6a7-b8c9-0123-def0-234567890123",
          "subordination_level": 1,
          "fund_class": {
            "name": "Fundo Exemplo FIDC",
            "short_name": "FEX",
            "document_number": "12.345.678/0001-90",
            "fund_class_key": "e5f6a7b8-c9d0-1234-ef01-345678901234",
            "accounting_date": "2024-06-01",
            "sub_type": "fidc",
            "tax_classification_id": "long_term",
            "condominum_type_id": "open_ended",
            "investment_category_id": "fidc",
            "prevent_payment": false,
            "integralization_account_key": null,
            "manager": {
              "manager_key": "f6a7b8c9-d0e1-2345-f012-456789012345",
              "document_number": "98.765.432/0001-10",
              "manager_name": "Gestora Exemplo S.A."
            }
          }
        },
        "status": "active",
        "internal_code": "INT-FEX-01",
        "processing_method": "standard",
        "operation_period_configuration": {},
        "current_quota_value": 1.05000055,
        "post_fixed": {
          "calendar_base": "calendar_252",
          "indexer": "cdi",
          "rate": 1.0,
          "lag": {
            "reference": "daily",
            "amount": 1
          }
        },
        "isin_code": "BRSTREXTFID6",
        "external_id": null,
        "specific_interest_rate_data": null
      },
      "investor": {
        "distributor": {
          "distributor_key": "3571e292-3a83-4011-904d-20ee963022ef",
          "document_number": "12.345.678/0001-90",
          "name": "Distribuidora Exemplo S.A.",
          "account_data": {
            "owner": {
              "name": "Distribuidora Exemplo S.A.",
              "document_number": "12.345.678/0001-90"
            },
            "account_digit": "1",
            "account_branch": "0001",
            "account_number": "12345",
            "financial_institution_code": "341",
            "financial_institution_ispb": "60746948"
          }
        },
        "investor_key": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "name": "Maria Cotista Silva",
        "person_type": "natural_person",
        "document_number": "123.456.789-00",
        "external_id": "ext-inv-001",
        "external_distribution_key": null
      },
      "status_events": [
        {
          "status": "pending_quote",
          "event_datetime": "2024-06-10T14:00:01.000000Z"
        },
        {
          "status": "quoted",
          "event_datetime": "2024-06-15T18:30:00.000000Z"
        }
      ]
    }
  ],
  "limit": 20,
  "page": 0,
  "is_last_page": true
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Pedidos de resgate. |
| `page` | integer | Página atual. |
| `limit` | integer | Tamanho da página. |
| `is_last_page` | boolean | Última página da consulta. |

#### Campos principais de cada pedido em `data`

| Campo | Tipo | Descrição |
|---|---|---|
| `redemption_request_key` | string | Identificador único do pedido (UUID). |
| `redemption_request_type` | string | Tipo do pedido — veja [Tipos de pedido](#tipos-de-pedido-de-resgate). |
| `status` | string | Status atual — veja [Status do pedido](#status-do-pedido-de-resgate). |
| `quotation_date` | string | Data de cotização (`YYYY-MM-DD`). |
| `payment_date` | string | Data prevista/realizada de pagamento (`YYYY-MM-DD`). |
| `request_datetime` | string | Momento da solicitação (ISO 8601 com sufixo Z quando aplicável). |
| `processed_value` | number | Valor processado (quando aplicável). |
| `ir_value` / `iof_value` | number | Retenções quando aplicáveis. |
| `redemption_request_data` | object | Payload específico do tipo de resgate (valores solicitados, cotas, etc.). |
| `issuance_serie` | object | Série de emissão vinculada. |
| `investor` | object | Dados do investidor e distribuidora. |
| `status_events` | array | Histórico de mudanças de status. |
| `cancellation_data` | object | Presente quando o pedido foi cancelado (omitido quando `null`). |

## Tipos de pedido de resgate

| Valor | Descrição |
|---|---|
| `gross_redemption_value` | Resgate por valor bruto. |
| `number_of_quotas` | Resgate por quantidade de cotas. |
| `remaining_application_value` | Resgate do valor remanescente da aplicação. |
| `net_value_redemption` | Resgate por valor líquido. |

## Status do pedido de resgate

| Status | Descrição resumida |
|---|---|
| `created` | Criado. |
| `pending_manager_approval` | Aguardando aprovação do gestor. |
| `pending_quote` | Aguardando cotização. |
| `processing_quotation` | Cotização em processamento. |
| `pending_quotation_date_input` | Aguardando informação de data de cotização. |
| `quoted` | Cotizado. |
| `canceled` | Cancelado. |
| `reprocessed` | Reprocessado. |

## Objetos da resposta

### Issuance Serie (`issuance_serie`)
| Campo | Tipo | Descrição |
|---|---|---|
| `issuance_serie_key` | string | Chave única de identificação da série de emissão |
| `name` | string | Nome da série de emissão |
| `serie` | int | Número da série |
| `original_quota_value` | float | Valor da cota original |
| `current_quota_value` | float | Valor atual da cota |
| `current_number_of_quotas` | float | Quantidade atual de cotas |
| `current_net_worth` | float | Patrimônio líquido atual |
| `current_principal_value` | float | Valor de principal atual |
| `performance_fee_current_value` | float | Valor atual de taxa de performance |
| `minimum_share_capital` | float | Valor mínimo para aplicação |
| `remuneration_type` | string | Tipo de remuneração (ex.: `yield_curve`) |
| `interest_rate_type` | string | Tipo de taxa (`post_fixed` / `pre_fixed`) |
| `post_fixed` / `pre_fixed` | object | Dados de remuneração (`calendar_base`, `indexer`, `rate`, `lag`) |
| `status` | string | Status da série de emissão (ex.: `active`) |
| `internal_code` | string | Código interno da série |
| `isin_code` | string | Código ISIN |
| `processing_method` | string | Método de processamento |
| `operation_period_configuration` | object | Configuração de períodos de operação |
| `external_id` | string | Identificador externo |
| `sub_class` | object | Objeto **Sub Class** |

### Sub Class (`sub_class`)
| Campo | Tipo | Descrição |
|---|---|---|
| `name` | string | Nome da subclasse |
| `sub_class_key` | string | Chave única de identificação da subclasse |
| `subordination_level` | int | Nível de subordinação da subclasse |
| `fund_class` | object | Objeto **Fund Class** |

### Fund Class (`fund_class`)
| Campo | Tipo | Descrição |
|---|---|---|
| `name` | string | Nome da classe de fundo |
| `short_name` | string | Nome curto da classe de fundo |
| `fund_class_key` | string | Chave única de identificação da classe de fundo |
| `document_number` | string | CNPJ da classe de fundo |
| `accounting_date` | string | Data contábil da classe de fundo |
| `sub_type` | string | Subtipo (ex.: `fidc`) |
| `tax_classification_id` | string | Classificação tributária (ex.: `long_term`) |
| `condominum_type_id` | string | Tipo de condomínio (ex.: `open_ended`) |
| `investment_category_id` | string | Categoria de investimento (ex.: `fidc`) |
| `prevent_payment` | boolean | Indica se os pagamentos estão bloqueados |
| `integralization_account_key` | string | Chave da conta de integralização |
| `manager` | object | Objeto **Manager** |

### Manager (`manager`)
| Campo | Tipo | Descrição |
|---|---|---|
| `manager_key` | string | Chave única de identificação do gestor |
| `document_number` | string | CNPJ do gestor |
| `manager_name` | string | Nome do gestor |

### Investor (`investor`)
| Campo | Tipo | Descrição |
|---|---|---|
| `investor_key` | string | Chave única de identificação do investidor |
| `name` | string | Nome do investidor |
| `document_number` | string | CPF/CNPJ do investidor |
| `person_type` | string | Tipo de pessoa (`natural_person` / `legal_person`) |
| `external_id` | string | Identificador externo do investidor |
| `external_distribution_key` | string | Chave de distribuição externa |
| `distributor` | object | Objeto **Distributor** |

### Distributor (`distributor`)
| Campo | Tipo | Descrição |
|---|---|---|
| `distributor_key` | string | Chave única de identificação do distribuidor |
| `name` | string | Nome do distribuidor |
| `document_number` | string | CNPJ do distribuidor |
| `account_data` | object | Objeto **Account Data** |

### Account Data (`account_data`)
| Campo | Tipo | Descrição |
|---|---|---|
| `owner` | object | Titular da conta (`name`, `document_number`) |
| `account_digit` | string | Dígito da conta bancária |
| `account_branch` | string | N° da agência da conta bancária |
| `account_number` | string | N° da conta bancária |
| `financial_institution_code` | string | Código da instituição financeira |
| `financial_institution_ispb` | string | Identificador no Sistema de Pagamento Brasileiro (ISPB) da instituição financeira |

## Possíveis erros

STATUS 404

**Status informado inválido**

Algum valor em `status` não corresponde a um enumerador válido de `RedemptionRequestStatus`.

```json
{
  "title": "Not found enumerator",
  "description": "invalid_status is not a valid type of RedemptionRequestStatus",
  "translation": "invalid_status não é um tipo válido de RedemptionRequestStatus",
  "code": "QTA000004"
}
```

---

# Criar Pedido de Resgate

URL: /documentation/iaas/passivo/pedido_de_resgate/criar_pedido_de_resgate

---

### Request

ENDPOINT /quota/investor/INVESTOR_KEY/redemption_request
MÉTODO POST
STATUS 201

```json title='Request Body'
{
    "issuance_serie_key": "UUID",
    "redemption_request_type": "gross_redemption_value" | "number_of_quotas" | "remaining_application_value" | "net_value_redemption",
    "payment_method": "regular / b3",
    "gross_redemption_value":0.00,
    "net_value": 0.00,
    "remaining_application_value":0.00,
    "number_of_quotas":0.00000000,
    "disbursement_account_key": "UUID",
    "quotation_date": "yyyy-mm-dd",
    "reference_date": "yyyy-mm-dd"
}
```

:::::warning
- O campo redemption_request_type define se os campos gross_redemption_value , remaining_application_value e number_of_quotas devem ser passados ou não.

- Caso gross_redemption_value , o campo gross_redemption_value é obrigatório.
- Caso remaining_application_value , o campo remaining_application_value é obrigatório.
- Caso number_of_quotas , o campo number_of_quotas é obrigatório.
- Caso net_value_redenotuib , o campo net_value é obrigatório.

- O campo disbursement_account_key deve ser utilizada para a liquidação do resgate em uma conta específica do investidor. Caso não seja informada uma conta específica, a conta principal do investidor será utilizada
:::::

### Body params
| Campo                             | Tipo     | Descrição                                                                               | Obrigatório
|-----------------------------------|----------|-----------------------------------------------------------------------------------------|-----|
| `issuance_serie_key`              | string   | Chave única de identificação da Série de emissão                                        | Sim
| `redemption_request_type`         | string   | Enumerador de **[Tipos de Pedido de Resgate](#tipos_de_pedido_de_resgate)**             | Sim
| `gross_redemption_value`          | float    | Valor bruto do resgate, sem descontar IR e IOF                                          | Não
| `net_value`                       | float    | Valor Líquido do resgate, já disconsiderando IR e IOF                                     | Não
| `remaining_application_value`     | float    | Valor restante da aplicação                                                             | Não
| `number_of_quotas`                | float    | Valor da aplicação financeira                                                           | Não
| `disbursement_account_key`                | string   | Chave única de identificação da conta bancária do investidor                            | Não |
| `quotation_date`                | string   | Data de cotização do resgate                        | Não |
| `payment_method`                | string   | Método de pagamento do resgate. Valores esperados:<br />• regular **(default)**<br />• b3: Via B3 | Não |
| `reference_date`                | string   | Data de referência do resgate, no formato yyyy-mm-dd                                    | Não |

### Tipos de Pedido de Resgate {#tipos_de_pedido_de_resgate}
| Enumerador                      | Descrição                                       |
|---------------------------------|-------------------------------------------------|
| `gross_redemption_value`        | Resgate por valor bruto                         |
| `number_of_quotas`              | Resgate por número de cotas                     |
| `remaining_application_value`   | Resgate por posição remanescente                |]
| `net_value_redemption`          | Resgate por valor líquido             |

### Response
```json title='Response Body'
{
    "redemption_request_key": "UUID"
}
```

---

# Enviar Termo de Adesão Assinado

URL: /documentation/iaas/passivo/termo_de_adesao/enviar_termo_de_adesao_assinado

---
### Introdução
Este recurso tem como objetivo nos enviar a comprovação de assinatura do **termo de adesão** de um **investidor** a uma **série de emissão** de um fundo.

:::warning Atenção
Este recurso está disponível apenas para integrações que exercem o papel de  **Distribuidor**.
:::

### Input / Output:
Como ***input*** deve ser enviado o UUID da **série de emissão** do fundo que o investidor aderiu e **tipo de assinatura** e dependendo da assinatura o conteúdo necessário para validação. Segue abaixo exemplo.

Como ***output*** será entregue uma ***investor_adhesion_key***. A ***investor_adhesion_key*** é utilizada para identificar a **adesão do investidor**.

### Request

ENDPOINT /investor_adhesion/investor/INVESTOR_KEY/signed_investor_adhesion
MÉTODO POST
STATUS 201

### Request body
```json title='Request Body'
{
  "issuance_serie_key": "UUID",
  "signature_method": "opt_in",
  "opt_in_hash" : "OPT_IN_HASH"
}
```
:::warning Atenção
Durante o processo de integração será exigido um meio de autenticação da hash enviada.
:::

### Response
```json title='Response Body'
{
    "investor_adhesion_key": "UUID"
}
```

---

# Solicitar Termo de Adesão

URL: /documentation/iaas/passivo/termo_de_adesao/solicitar_termo_de_adesao

---

### Introdução
Este recurso tem como objetivo criar uma solicitação de **termo de adesão** de um **investidor** a uma **série de emissão** de um fundo. A partir desta solicitação, são gerados os documentos necessários para a formalização da adesão, de acordo com as configurações da série de emissão.

:::warning Atenção
Este recurso está disponível apenas para integrações que exercem o papel de **Gestor** do fundo.
:::

### Input / Output:
Como ***input*** deve ser enviado o UUID da **série de emissão** em que o investidor está aderindo e, opcionalmente, o **método de assinatura** que será utilizado para os documentos gerados.

Como ***output*** será entregue uma ***investor_adhesion_key***. A ***investor_adhesion_key*** é utilizada para identificar a **adesão do investidor**.

### Request

ENDPOINT /investor_adhesion/investor/INVESTOR_KEY/investor_adhesion
MÉTODO POST
STATUS 201

### Request body
```json title='Request Body'
{
  "issuance_serie_key": "UUID",
  "signature_method": "qi_sign"
}
```

### Investor Adhesion
| Campo                | Tipo   | Descrição                                                              | Caracteres | Obrigatório |
|----------------------|--------|------------------------------------------------------------------------|------------|-------------|
| `issuance_serie_key` | string | Chave da série de emissão a qual o investidor está aderindo            | 36         |     Sim     |
| `signature_method`   | string | Enumerador do método de assinatura a ser utilizado nos documentos      | até 255    |     Não     |

### Signature Method
| Enumerador    | Descrição                                                    |
|---------------|--------------------------------------------------------------|
| `certifiqi`   | Assinatura via CertifiQi (Certificado Digital)               |
| `qi_sign`     | Assinatura via QI Sign (Assinatura Eletrônica)               |

### Response
```json title='Response Body'
{
    "investor_adhesion_key": "UUID"
}
```

:::info Fluxo da adesão
Após solicitar uma nova adesão, podemos seguir dois caminhos:

- **Investidor NÃO tinha uma adesão ativa**: a adesão é criada no status `pending_documents` e permanece assim até que todos os documentos exigidos sejam gerados e assinados.
- **Investidor já tinha uma adesão ativa**: a requisição é rejeitada.
:::

---

# Razão Contábil

URL: /documentation/iaas/relatorios_dtvm/accounting_ledger

## Visão Geral

O relatório `accounting_ledger` apresenta o razão contábil do fundo em um intervalo de datas. Para cada conta do plano de contas com movimentações no período, o relatório exibe uma linha de saldo inicial, todos os lançamentos individuais com data, contrapartida, valor e descrição, e uma linha de saldo final com totais de débito e crédito. Auditores, administradores e analistas utilizam este relatório para rastrear a origem de cada lançamento contábil e verificar a evolução dos saldos conta a conta.

## O que você precisa informar

| Variável | Obrigatória | Descrição |
|----------|-------------|-----------|
| `fund_class_key` | sim | Identificador da classe de fundo sobre a qual o relatório é gerado. |
| `start_date` | sim | Data de início do período, no formato `AAAA-MM-DD`. |
| `end_date` | sim | Data de fim do período, no formato `AAAA-MM-DD`. Precisa ser **posterior** à data de início. |

:::warning É preciso haver contabilidade fechada nas duas datas
O relatório só é gerado se existir fechamento contábil na data de início **e** na data de fim. Sem isso a solicitação é recusada com a mensagem "Não existe contabil na data ...".
:::

:::warning As duas datas têm de estar no mesmo exercício contábil
Além de existir fechamento nas duas datas, elas precisam pertencer ao **mesmo exercício** (mesmo *ledger*). Um período que atravessa o encerramento de exercício faz a geração falhar.
:::

## Estrutura do Arquivo

| Atributo | Valor |
|----------|-------|
| Formato | XLSX |
| Nomenclatura | `{nome_resumido_fundo}_accounting_ledger_{YYYY-MM-DD}.xlsx` |

## Conteúdo da Planilha

### Cabeçalho do Fundo

Apresentado nas primeiras linhas da planilha:

| Campo | Descrição |
|-------|-----------|
| Fundo | Nome completo da classe de fundo. |
| CNPJ | CNPJ da classe de fundo. |

:::warning O sinal do saldo aqui é diferente do Relatório de Balanço
Neste relatório o saldo é o valor cru do fechamento (crédito positivo, débito negativo). No [Relatório de Balanço](/documentation/iaas/relatorios_dtvm/balance_report) o mesmo saldo é normalizado pela natureza da conta. A mesma conta pode, portanto, aparecer como `-45000.00` aqui e `45000.00` lá — são a mesma posição, em convenções de sinal diferentes.
:::

### Lançamentos por Conta

Para cada conta com movimentações no período, o relatório exibe:

1. **Linha de saldo inicial** (em negrito) — saldo da conta na Data de Início.
2. **Linhas de lançamento** — um registro por movimento contábil.
3. **Linha de saldo final** (em negrito) — saldo da conta na Data Final com totais de débito e crédito.

| Coluna | Tipo | Formato / Exemplo | Descrição |
|--------|------|-------------------|-----------|
| `Data` | data | `2026-07-15` | Data contábil do lançamento. Nas linhas de saldo inicial e final, exibe a Data de Início e a Data Final respectivamente. |
| `Conta` | string | `"1.2.1.10.00.001.001-9"` | Número da conta no plano de contas, com dígito verificador. |
| `Nome da Conta` | string | `"Direitos Creditórios sem Coobrigação"` | Nome descritivo da conta contábil. |
| `Tipo do Lançamento` | string (enum) | `"A"` | Tipo do lançamento: `"A"` para automático; `"M"` para manual; `"I"` para linha de saldo inicial; `"F"` para linha de saldo final. |
| `ContraPartida` | string | `"7.9.1.20.00.001.001-1"` | Número da conta de contrapartida do lançamento. Vazio nas linhas de saldo inicial e final. |
| `Débito` | número | `1500.00` | Valor do lançamento a débito (em reais). Zero quando o lançamento é a crédito. |
| `Crédito` | número | `0.00` | Valor do lançamento a crédito (em reais). Zero quando o lançamento é a débito. |
| `Saldo` | número | `-196500.00` | Saldo acumulado da conta após o lançamento (em reais). Crédito soma e débito subtrai, **sem normalização pela natureza da conta** — por isso uma conta de ativo com saldo devedor aparece negativa aqui. |
| `Descrição` | string | `"ACRUO DE ATIVOS - CCBs"` | Descrição do evento contábil associado ao lançamento. |

---

# Composição de Carteira de Ativos

URL: /documentation/iaas/relatorios_dtvm/assets_wallet_composition

## Visão Geral

O relatório `assets_wallet_composition` apresenta a posição completa de todos os ativos que compõem o estoque do fundo em uma determinada data de referência. Ele é gerado uma vez ao dia e consolida três categorias de ativos:

- **operações de crédito** (ex: CCB) — uma linha por **parcela** da operação;
- **direitos creditórios descontados** (ex: duplicatas, CT-e, contratos descontados) — uma linha por título;
- **títulos privados** (ex: debêntures, notas comerciais) — uma linha por parcela do título.

Gestores e analistas utilizam este relatório para acompanhar o estoque, avaliar provisões para devedores duvidosos e monitorar a evolução da carteira.

:::info Uma linha por parcela
Para operações de crédito parceladas, a mesma operação aparece em várias linhas — uma por parcela — repetindo os dados cadastrais (`external_id`, `contract_number`, `purchase_value`) e variando `installment_number`, `face_value`, `maturity_date` e `installment_purchase_value`.
:::

:::tip Também em PDF
Este relatório está descrito em linguagem de negócio no [Manual de Relatórios QI Tech](./manual_relatorios_qi_tech.pdf) — revisão 2, julho de 2026. O manual cobre quatro relatórios: este, a [Composição de Ativos da Cessão](/documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition), a [Aquisição Consolidada](/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_acquisition_assets) e a [Conciliação Consolidada de Direitos Creditórios](/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_conciliation_assets).

Nesta seção do manual os nomes das colunas aparecem em maiúsculas. No arquivo entregue eles vêm sempre em **minúsculas**, conforme a tabela de colunas abaixo.
:::

## O que você precisa informar

| Variável | Obrigatória | Descrição |
|----------|-------------|-----------|
| `fund_class_key` | sim | Identificador da classe de fundo sobre a qual o relatório é gerado. |
| `reference_date` | sim | Data de referência, no formato `AAAA-MM-DD`. |

:::info Fundos de cota de abertura
Para os fundos que operam com relatório de cota de abertura, a posição entregue é a do **dia anterior** à data de referência informada.
:::

## Estrutura do Arquivo

| Atributo | Valor |
|----------|-------|
| Formato | CSV |
| Encoding | UTF-8 |
| Delimitador | `,` (vírgula) |
| Cabeçalho | Sim (primeira linha) |
| Nomenclatura | `{nome_resumido_fundo}_assets_wallet_composition_{AAAA-MM-DD}.csv` |

Os nomes das colunas são gerados em **minúsculas**. Datas são escritas no formato `AAAA-MM-DD` e valores decimais usam ponto como separador, com até 8 casas decimais.

## Colunas

| Coluna | Tipo | Formato / Exemplo | Descrição |
|--------|------|-------------------|-----------|
| `fund_name` | string | `"FUNDO EXEMPLO FIDC RESPONSABILIDADE LIMITADA"` | Nome da classe de fundo. |
| `fund_document` | string | `"12.345.678/0001-99"` | CNPJ da classe de fundo. |
| `report_date` | data | `2026-07-30` | Data em que o relatório foi gerado. Nas linhas de títulos privados, esta coluna traz a data de referência da carteira. |
| `originator_name` | string | `"ORIGINADOR EXEMPLO S.A."` | Nome da empresa originadora da operação. Para títulos privados, o valor é `-`. |
| `originator_document` | string | `"11.222.333/0001-44"` | CNPJ do originador. Para títulos privados, o valor é `-`. |
| `assignor_name` | string | `"CEDENTE EXEMPLO S.A."` | Nome do cedente da operação. Para títulos privados, o valor é `-`. |
| `assignor_document` | string | `"22.333.444/0001-55"` | CNPJ do cedente. Para títulos privados, o valor é `-`. |
| `borrower_name` | string | `"MARIA APARECIDA DE SOUZA"` | Nome do devedor. Para direitos creditórios descontados, é o sacado; para títulos privados, é o emissor. |
| `borrower_document` | string | `"123.456.789-00"` | CPF ou CNPJ do devedor / sacado / emissor. |
| `external_id` | string | `"10a20b30-0001-4bbb-9222-000000000201"` | Identificador externo do ativo, conforme informado na criação. |
| `contract_number` | string | `"0900112233/EXA"` | Número do contrato ou número do pedido (`order_number`) associado à operação. |
| `asset_type` | string (enum) | `"ccb"` | Tipo do ativo. Exemplos: `ccb`, `duplicata_mercantil`, `duplicata_servicos`, `cte`, `discounted_contract`, `debenture`. |
| `face_value` | número | `1678.90` | Valor de face da parcela (ou do título) na data de referência, em reais. |
| `present_value` | número | `1663.48` | Valor presente da parcela (ou do título) na data de referência, em reais. |
| `purchase_value` | texto numérico | `4690.80` | Valor pelo qual o **ativo** foi adquirido pelo fundo, em reais. Repetido em todas as parcelas da mesma operação. |
| `bad_provision_value` | número | `0.0` | Valor da provisão para devedores duvidosos (PDD) constituída sobre o ativo, em reais. |
| `bad_provision_range` | string | `"AA"` | Faixa de classificação de risco da PDD — as usuais são `AA`, `A`, `B`, `C`, `D`, `E`, `F`, `G` e `H`, e ativos baixados podem trazer `WO`. Quando não há classificação, o relatório traz `AA`. |
| `fund_date` | data | `2026-07-29` | Data de referência da carteira. |
| `maturity_date` | data | `2026-08-28` | Data de vencimento da parcela (ou do título). |
| `business_maturity_date` | data | `2026-08-28` | Data de vencimento ajustada para dia útil. |
| `issue_date` | texto de data | `2026-07-28` | Data de emissão do contrato. Para direitos creditórios descontados, corresponde à data de aquisição. |
| `purchase_date` | texto de data | `2026-07-29` | Data de aquisição do ativo pelo fundo. |
| `total_duration` | inteiro | `30` | Prazo total em dias corridos, da aquisição até o vencimento. |
| `present_duration` | inteiro | `30` | Prazo remanescente em dias corridos, da data de referência até o vencimento. Fica negativo quando o ativo está vencido. |
| `asset_maturity_status` | string (enum) | `"on_time"` | Situação do vencimento: `OVERDUE` quando vencido, `on_time` quando dentro do prazo. |
| `assignment_rate_of_return` | número | `0.0312` | Taxa interna de retorno (TIR) da cessão. Vazio para títulos privados. |
| `purchase_rate_of_return` | texto numérico | `0.031874210` | TIR corrente da operação no momento da aquisição. Para títulos privados, o valor é `-`. |
| `has_assignor_coobligation` | string | `"False"` | Indica coobrigação do cedente: `True` ou `False`. Para títulos privados, o valor é `-`. |
| `installment_number` | inteiro | `1` | Número da parcela. Para direitos creditórios descontados, é sempre `1`. |
| `bad_debt_type` | string | `"default"` | Tipo de classificação da PDD aplicada ao ativo. |
| `nominal_rate` | número | `0.0231` | Taxa nominal mensal pré-fixada da operação. Vazio para direitos creditórios descontados e títulos privados. |
| `operation_type` | string | `"ccb"` | Tipo da operação registrado no cadastro do ativo. Vazio para títulos privados. |
| `installment_purchase_value` | texto numérico | `1598.74210000` | Valor pago pelo fundo pela **parcela** específica, em reais. Vazio para direitos creditórios descontados e títulos privados. |

:::note Coluna adicional
Quando a entrega é configurada com a opção `benefit_number`, o relatório traz uma coluna extra `benefit_type` ao final, com o tipo de benefício associado à garantia da operação.
:::

---

# Composição de Ativos da Cessão

URL: /documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition

## Visão Geral

O relatório `assignment_assets_wallet_composition` detalha os ativos de **uma cessão específica**, no mesmo formato do relatório de [Composição de Carteira de Ativos](/documentation/iaas/relatorios_dtvm/assets_wallet_composition). É o relatório usado para conferir o que entrou na carteira imediatamente após uma aquisição, antes de o ativo passar a compor as posições diárias.

- **operações de crédito** — uma linha por **parcela**;
- **direitos creditórios descontados** — uma linha por **ativo**.

:::tip Também em PDF
Este relatório está descrito em linguagem de negócio no [Manual de Relatórios QI Tech](./manual_relatorios_qi_tech.pdf) — revisão 2, julho de 2026. O manual cobre quatro relatórios: este, a [Composição de Carteira de Ativos](/documentation/iaas/relatorios_dtvm/assets_wallet_composition), a [Aquisição Consolidada](/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_acquisition_assets) e a [Conciliação Consolidada de Direitos Creditórios](/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_conciliation_assets).

Nesta seção do manual os nomes das colunas aparecem em maiúsculas. No arquivo entregue eles vêm sempre em **minúsculas**, conforme a tabela de colunas abaixo.
:::

## O que você precisa informar

| Variável | Obrigatória | Descrição |
|----------|-------------|-----------|
| `external_id` | sempre | O "seu número" da cessão a consultar. |
| `asset_type` | sempre | Define qual consulta é executada. Operações de crédito: `ccb`, `structured_ccb`, `cce`, `structured_cce`, `structured_cci`, `structured_nce`. Direitos creditórios descontados: `duplicata_mercantil`, `duplicata_servicos`, `discounted_contract`, `legal_fees`, `cte`. Um tipo fora dessas listas faz o relatório falhar. |
| `fund_class_key` | só para direitos creditórios descontados | Classe de fundo sobre a qual o relatório é gerado. Para operações de crédito o filtro é feito apenas pela cessão, e o fundo informado é ignorado. |

## Estrutura do Arquivo

| Atributo | Valor |
|----------|-------|
| Formato | CSV |
| Encoding | UTF-8 |
| Delimitador | `,` (vírgula) |
| Cabeçalho | Sim (primeira linha) |
| Nomenclatura | `{nome_resumido_fundo}_assignment_assets_wallet_composition_{AAAA-MM-DD}_{external_id}.csv` |

:::note O nome do arquivo termina com o identificador da cessão
Diferente dos relatórios diários, este acrescenta o `external_id` da cessão ao final do nome. Como o `external_id` é obrigatório, o sufixo está sempre presente.
:::

## O que o relatório traz

- Todos os ativos da cessão informada, **exceto** os descartados (`discarded`) e os reprovados (`denied`).
- As últimas colunas variam conforme o tipo de ativo — veja `asset_external_id` / `invoice_number` e `monthly_rate` na tabela abaixo.
- Campos sem valor vêm vazios no arquivo.

## Colunas

| Coluna | Tipo | Formato / Exemplo | Descrição |
|--------|------|-------------------|-----------|
| `fund_name` | string | `"FUNDO EXEMPLO FIDC RESPONSABILIDADE LIMITADA"` | Nome da classe de fundo. |
| `fund_document` | string | `"12.345.678/0001-99"` | CNPJ da classe de fundo. |
| `fund_date` | data | `2026-07-29` | Data contábil corrente do fundo. |
| `originator_name` | string | `"ORIGINADOR EXEMPLO S.A."` | Nome do originador. |
| `originator_document` | string | `"11.222.333/0001-44"` | CNPJ do originador. |
| `name` | string | `"CEDENTE EXEMPLO S.A."` | Nome do **cedente**. Atenção ao cabeçalho genérico: apesar de `name`, o conteúdo é o cedente, não o fundo nem o devedor. |
| `document_number` | string | `"22.333.444/0001-55"` | CNPJ do **cedente**. Mesma observação da coluna anterior. |
| `borrower_name` | string | `"MARIA APARECIDA DE SOUZA"` | Nome do devedor ou do sacado. |
| `borrower_document` | string | `"123.456.789-00"` | CPF ou CNPJ do devedor/sacado. |
| `external_id` | string | `"10a20b30-0001-4bbb-9222-000000000201-1"` | Identificador externo da **parcela** (operação de crédito) ou do **ativo** (direito creditório descontado). |
| `contract_number` | string | `"0900112233/EXA"` | Número do contrato ou do pedido. |
| `asset_type` | string (enum) | `"ccb"` | Tipo do ativo. |
| `face_value` | número | `1678.90` | Valor de face/nominal (em reais). |
| `present_value` | número | `1598.74210000` | Valor presente. Nesta visão, igual ao valor de compra. |
| `purchase_value` | número | `1598.74210000` | Valor de aquisição (em reais). |
| `bad_provision_value` | número | `0` | Provisão para devedores duvidosos. **Fixo em `0`** nesta visão. |
| `bad_provision_range` | string | `"AA"` | Faixa de PDD. **Fixo em `AA`** (melhor faixa) nesta visão. |
| `report_date` | data | `2026-07-30` | Data de geração do relatório. |
| `maturity_date` | data | `2026-08-28` | Vencimento da parcela ou do ativo. |
| `business_maturity_date` | data | `2026-08-28` | Vencimento ajustado. Nesta visão, repete o `maturity_date`. |
| `issue_date` | data | `2026-07-29` | Data de emissão. Nesta visão, traz a **data da cessão**. |
| `purchase_date` | data | `2026-07-29` | Data de aquisição. Nesta visão, traz a **data da cessão**. |
| `total_duration` | número | `30` | Prazo total, em dias. |
| `present_duration` | número | `30` | Prazo atual, em dias. |
| `asset_maturity_status` | string (enum) | `"on_time"` | `OVERDUE` quando a data da cessão é posterior ao vencimento; `on_time` nos demais casos. |
| `assignment_irr` | número | `0.0312` | Taxa de cessão. |
| `purchase_irr` | número | `0.03187421` | Taxa de compra do recebível. |
| `has_assignor_coobligation` | string | `"False"` | Coobrigação do cedente, como texto `"True"` ou `"False"`. |
| `asset_external_id` **ou** `invoice_number` | string | `"10a20b30-0001-4bbb-9222-000000000201"` | Operação de crédito: identificador externo do ativo (`asset_external_id`). Direito creditório descontado: chave de acesso da NF-e (`invoice_number`). |
| `monthly_rate` | string | `"0.0231"` | Taxa mensal pré-fixada. **Só existe no arquivo de operações de crédito** — no de direitos creditórios descontados a coluna não é emitida. |

## Colunas opcionais

Podem ser solicitadas na geração do relatório e são acrescentadas **ao final** do arquivo, nesta ordem. Valem apenas para **operações de crédito**.

| Coluna | Descrição |
|--------|-----------|
| `installment_number` | Número da parcela. |
| `disbursement_value` | Valor desembolsado no contrato. |
| `cet` | Custo Efetivo Total do contrato. |
| `issue_value` | Valor de emissão do contrato. |
| `interest_rate_type` | Tipo da taxa de juros da operação. |
| `borrower_birthdate` | Data de nascimento do devedor (pessoa natural). |
| `benefit_type` | Tipo de benefício da primeira garantia da operação. |

:::note Como pedir as colunas opcionais
A habilitação é feita pela QI CTVM na configuração da entrega, por relatório. Se você precisar de alguma dessas colunas, informe ao time de integração quais deseja.
:::

---

# Lastros da Cessão

URL: /documentation/iaas/relatorios_dtvm/assignment_documents

## Visão Geral

O relatório `assignment_documents` lista os **documentos comprobatórios** dos ativos de uma cessão específica, com um link de download para cada arquivo. É o relatório usado para arquivar o lastro da operação: uma linha por documento, com a chave do ativo a que ele pertence.

Ele é o complemento da [Composição de Ativos da Cessão](/documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition): aquele traz os valores e características dos ativos cedidos, este traz os arquivos que os comprovam.

## O que você precisa informar

| Variável | Obrigatória | Descrição |
|----------|-------------|-----------|
| `fund_class_key` | sim | Identificador da classe de fundo da cessão. |
| `external_id` | sim | O "seu número" da cessão a consultar. |

Este relatório **não recebe data de referência** — ele sempre reflete os documentos existentes no momento da geração.

## Estrutura do Arquivo

| Atributo | Valor |
|----------|-------|
| Formato | CSV |
| Encoding | UTF-8 |
| Delimitador | `,` (vírgula) |
| Cabeçalho | Sim (primeira linha) |
| Nomenclatura | `{nome_resumido_fundo}_assignment_documents_{external_id}_{AAAA-MM-DD}.csv` |

:::warning A nomenclatura deste relatório é diferente
Duas diferenças em relação aos outros relatórios:

1. o identificador da cessão vem **antes** da data, e não no fim do nome — compare com o `assignment_assets_wallet_composition`, que acrescenta o `external_id` no final;
2. a data no nome é a **data de geração do arquivo** (fuso de Brasília), não uma data de referência informada por você. Gerar o mesmo relatório em dois dias diferentes produz dois nomes diferentes para o mesmo conteúdo.
:::

## Colunas

| Coluna | Tipo | Formato / Exemplo | Descrição |
|--------|------|-------------------|-----------|
| `assignment_external_id` | string | `"CESSAO-2026-07-29-001"` | Identificador externo da cessão. Igual em todas as linhas do arquivo. |
| `asset_key` | string | `"1a2b3c40-0001-4aaa-9111-000000000101"` | Chave interna do ativo gerada pela QI Tech (UUID). Repete-se quando o ativo tem mais de um documento. |
| `asset_external_id` | string | `"10a20b30-0001-4bbb-9222-000000000201"` | Identificador externo do ativo. |
| `document_key` | string | `"50e60f70-0001-4fff-9666-000000000601"` | Chave interna do documento gerada pela QI Tech (UUID). |
| `document_type` | string (enum) | `"ccb"`, `"duplicata_mercantil"`, `"duplicata_servicos"`, `"discounted_contract"`, `"cte"`, `"invoice"` | Tipo do documento. Acompanha o tipo do ativo, exceto `invoice`, que é a nota fiscal do recebível. |
| `document_url` | string | `"https://...s3.amazonaws.com/...?X-Amz-Signature=..."` | Link de download direto do arquivo. Veja o aviso sobre validade abaixo. |

:::danger Os links expiram em 5 dias
`document_url` é uma URL pré-assinada, gerada no momento em que o relatório é produzido e válida por **5 dias (432.000 segundos)**. Depois disso o link retorna erro e é preciso gerar o relatório novamente para obter links novos.

Não armazene as URLs como referência permanente do documento. Se você precisa guardar o lastro, **baixe os arquivos** dentro da janela de validade e use `document_key` como identificador estável do documento.
:::

:::tip Testando a captura dos arquivos
Para exercitar o download em sandbox com links reais — e com documentos de exemplo de cada `document_type` — siga o roteiro em [Testando a Captura de Lastro](/documentation/iaas/relatorios_dtvm/testar_captura_lastro).
:::

## O que o relatório traz

- Os documentos de todos os ativos da cessão informada, **exceto** os dos ativos descartados (`discarded`) e reprovados (`denied`).
- **Uma linha por documento.** Um ativo com contrato e nota fiscal aparece em duas linhas, com o mesmo `asset_key` e `document_type` diferentes.
- Ativos sem documento anexado não aparecem no arquivo.

:::tip Cruzando com a composição da cessão
`asset_external_id` e `asset_key` são as chaves de junção com a [Composição de Ativos da Cessão](/documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition). Cruzando os dois arquivos você confere se todo ativo cedido tem o lastro correspondente — um ativo presente na composição e ausente aqui é um ativo sem documento anexado.
:::

---

# Relatório de Balanço

URL: /documentation/iaas/relatorios_dtvm/balance_report

## Visão Geral

O relatório `balance_report` apresenta o balanço contábil consolidado do fundo entre duas datas de referência. Ele exibe, para cada conta do plano de contas, o saldo inicial (Data de Início), os movimentos de débito e crédito ocorridos no período e o saldo final (Data Final). O relatório organiza as contas em uma estrutura hierárquica (grupos e subgrupos) e inclui totalizadores para ativo, passivo, patrimônio líquido, receitas, despesas e compensações. Administradores e analistas utilizam este relatório para verificar a consistência contábil e auditar a evolução do balanço do fundo.

## O que você precisa informar

| Variável | Obrigatória | Descrição |
|----------|-------------|-----------|
| `fund_class_key` | sim | Identificador da classe de fundo sobre a qual o relatório é gerado. |
| `start_date` | sim | Data de início do período, no formato `AAAA-MM-DD`. |
| `end_date` | sim | Data de fim do período, no formato `AAAA-MM-DD`. Precisa ser **posterior** à data de início. |

:::warning É preciso haver contabilidade fechada nas duas datas
O relatório só é gerado se existir fechamento contábil na data de início **e** na data de fim. Sem isso a solicitação é recusada com a mensagem "Não existe contabil na data ...".
:::

:::warning As duas datas têm de estar no mesmo exercício contábil
Além de existir fechamento nas duas datas, elas precisam pertencer ao **mesmo exercício** (mesmo *ledger*). Um período que atravessa o encerramento de exercício faz a geração falhar.
:::

## Estrutura do Arquivo

| Atributo | Valor |
|----------|-------|
| Formato | XLSX |
| Nomenclatura | `{nome_resumido_fundo}_balance_report_{YYYY-MM-DD}.xlsx` |

## Conteúdo da Planilha

### Cabeçalho do Fundo

Apresentado nas primeiras linhas da planilha:

| Campo | Descrição |
|-------|-----------|
| Nome do Fundo | Nome completo da classe de fundo. |
| CNPJ do Fundo | CNPJ da classe de fundo. |
| Data de Início | Data de início do período no formato `YYYY-MM-DD`. |
| Data Final | Data de fim do período no formato `YYYY-MM-DD`. |
| Total do Ativo | Soma do saldo final das contas de ativo. |
| Total do Passivo | Soma do saldo final das contas de passivo. |
| Total de PL | Saldo final das contas de patrimônio líquido. |
| Total de Receitas | Saldo final das contas de receita. |
| Total de Despesas | Saldo final das contas de despesa. |
| Total de Compensação Ativa | Saldo final das contas de compensação ativa (grupo 3). |
| Total de Compensação Passiva | Saldo final das contas de compensação passiva (grupo 9). |
| PL por Contas Patrimoniais | `Total do Ativo - Total do Passivo` |
| PL por Contas de Resultado | `Total de PL + Total de Receitas + Total de Despesas` |
| Bate Compensação | `Total de Compensação Ativa - Total de Compensação Passiva` |

:::note Os totais são fórmulas do Excel
As células do cabeçalho não são valores fixos: elas referenciam as linhas de total da tabela de contas (por exemplo, `Total do Ativo` é `=G20`). Ao abrir o arquivo, o Excel recalcula tudo — e, se você editar a tabela, os totais acompanham.
:::

### Tabela de Contas

Linhas organizadas hierarquicamente por número de conta, sem formatação especial — apenas a linha de cabeçalho da tabela vem em negrito:

| Coluna | Tipo | Formato / Exemplo | Descrição |
|--------|------|-------------------|-----------|
| `Número da Conta` | string | `"1.1.2.80.00.010.001-8"` | Número da conta no plano de contas, com dígito verificador. As linhas de grupo trazem o número do nível correspondente — por exemplo `1-7` (ATIVO) e `1.1-6` (DISPONIBILIDADES). |
| `Nome da Conta` | string | `"Conta Caixa - Banco Exemplo"` | Nome descritivo da conta contábil. |
| `Tipo da Conta` | string (enum) | `"A"` | Tipo da linha: `"A"` para conta analítica; `"S"` para conta sintética (agrupadora, exibida em negrito). |
| `Saldo em Término de {Data de Início}` | número | `40000.00` | Saldo da conta na Data de Início, em reais. Negativo indica saldo de natureza contrária à conta. |
| `Movimentos de Débito` | número | `5000.00` | Soma dos lançamentos a débito no período (em reais). O sinal segue a natureza da conta: positivo nas contas devedoras, negativo nas credoras. |
| `Movimentos de Crédito` | número | `0.00` | Soma dos lançamentos a crédito no período (em reais). Sinal invertido em relação à coluna de débito: negativo nas contas devedoras, positivo nas credoras. |
| `Saldo em Término de {Data Final}` | número | `45000.00` | Saldo da conta na Data Final, em reais. |

---

# Demonstrativo de Caixa

URL: /documentation/iaas/relatorios_dtvm/cash_account_demonstrative

## Visão Geral

O relatório `cash_account_demonstrative` é um extrato diário das movimentações e saldos das contas bancárias do fundo ao fim do dia. Ele é gerado uma vez por dia, após o encerramento do ciclo financeiro, e apresenta os saldos de abertura (D-1) e encerramento (D0) de cada conta, além de todas as transações ocorridas ao longo do dia. Gestores e administradores utilizam este relatório para conferir a posição de caixa e conciliar as movimentações financeiras do fundo.

O relatório pode ser gerado em modo de fundo único ou em modo multi-fundo. No modo multi-fundo, cada classe de fundo é apresentada em uma aba separada dentro da mesma planilha.

## O que você precisa informar

| Variável | Obrigatória | Descrição |
|----------|-------------|-----------|
| `fund_class_key` | sim | Identificador da classe de fundo sobre a qual o relatório é gerado. |
| `reference_date` | sim | Data de referência, no formato `AAAA-MM-DD`. |

## Estrutura do Arquivo

| Atributo | Valor |
|----------|-------|
| Formato | XLSX |
| Aba | `Demonstrativo de Caixa` (no modo multi-fundo, uma aba por fundo, nomeada com o nome do fundo) |
| Nomenclatura | `{nome_resumido_fundo}_cash_account_demonstrative_{AAAA-MM-DD}.xlsx` |

:::tip Versão para conciliação automatizada
Este relatório é uma planilha formatada para leitura. Para conciliar as movimentações de forma automatizada — com identificador de transação, tipo, status de conciliação e saldos antes e depois de cada lançamento — utilize o relatório [Movimentações de Caixa](/documentation/iaas/relatorios_dtvm/cash_account_demonstrative_movements), em CSV.
:::

## Conteúdo da Planilha

Cada aba da planilha (uma por fundo) contém as seguintes seções:

### Cabeçalho do Fundo

Apresentado no topo da aba, com as informações de identificação da classe de fundo:

| Campo | Descrição |
|-------|-----------|
| Data de referência | Data de referência do relatório no formato `YYYY-MM-DD`. |
| Nome da classe de fundo | Nome completo da classe de fundo. |
| CNPJ da classe de fundo | CNPJ da classe de fundo. |
| Nome da gestora | Nome da gestora responsável pelo fundo. |
| CNPJ da gestora | CNPJ da gestora responsável pelo fundo. |

### Extrato por Conta Bancária

Abaixo do cabeçalho, sob o título **Extrato**, é exibida uma tabela por conta bancária do fundo, com as seguintes colunas:

| Coluna | Tipo | Formato / Exemplo | Descrição |
|--------|------|-------------------|-----------|
| `Data de referência` | data | `2026-07-29` | Data de referência do relatório. |
| `Banco` | string | `"999 - BANCO EXEMPLO S.A."` | Código COMPE e nome da instituição financeira, no formato `{código} - {nome}`. |
| `Agência/Conta` | string | `"0001/4417206-9"` | Número da agência e da conta, no formato `{agência}/{conta}-{dígito}`. |
| `Descrição` | string | `"Liquidação de parcelas"` | Descrição da movimentação conforme o grupo de conciliação da transação. |
| `Valor (R$)` | número | `2417.86` | Valor da movimentação em reais. Valores negativos indicam saída de caixa. |

Cada tabela de conta exibe ainda três linhas de resumo, em negrito e com fundo cinza. Nessas linhas, o rótulo (`Saldo D-1`, `Total`, `Saldo D0`) ocupa a primeira coluna, no lugar da data de referência:

| Linha | Posição | Descrição |
|-------|---------|-----------|
| **Saldo D-1** | primeira linha da tabela | Saldo da conta ao início do dia (encerramento do dia anterior). |
| **Total** | após as movimentações | Soma de todas as movimentações do dia para a conta. |
| **Saldo D0** | última linha da tabela | Saldo da conta ao encerramento do dia de referência. |

---

# Movimentações de Caixa

URL: /documentation/iaas/relatorios_dtvm/cash_account_demonstrative_movements

## Visão Geral

O relatório `cash_account_demonstrative_movements` lista, transação a transação, todas as movimentações das contas bancárias do fundo na data de referência. É a versão tabular do [Demonstrativo de Caixa](/documentation/iaas/relatorios_dtvm/cash_account_demonstrative): enquanto o demonstrativo é uma planilha formatada para leitura, este arquivo é um CSV pensado para conciliação automatizada, com o identificador de cada transação, o tipo, o status de conciliação e os saldos antes e depois do lançamento.

:::info Janela do dia
São consideradas as transações registradas entre 03:00 (UTC) da data de referência e 03:00 (UTC) do dia seguinte — ou seja, o dia inteiro no horário de Brasília. As linhas vêm ordenadas por data e hora da transação.
:::

## O que você precisa informar

| Variável | Obrigatória | Descrição |
|----------|-------------|-----------|
| `fund_class_key` | sim | Identificador da classe de fundo sobre a qual o relatório é gerado. |
| `reference_date` | sim | Data de referência, no formato `AAAA-MM-DD`. |

## Estrutura do Arquivo

| Atributo | Valor |
|----------|-------|
| Formato | CSV |
| Encoding | UTF-8 |
| Delimitador | `,` (vírgula) |
| Cabeçalho | Sim (primeira linha) |
| Nomenclatura | `{nome_resumido_fundo}_cash_account_demonstrative_movements_{AAAA-MM-DD}.csv` |

:::warning Valores em centavos
As colunas `amount`, `previous_balance` e `post_balance` são números **inteiros em centavos** — `241786` significa R$ 2.417,86. Diferente dos demais relatórios, que trazem valores em reais.
:::

## Colunas

| Coluna | Tipo | Formato / Exemplo | Descrição |
|--------|------|-------------------|-----------|
| `fund_class_name` | string | `"FUNDO EXEMPLO FIDC RESPONSABILIDADE LIMITADA"` | Nome da classe de fundo. |
| `fund_class_document_number` | string | `"12.345.678/0001-99"` | CNPJ da classe de fundo. |
| `account_number` | string | `"4417206"` | Número da conta bancária, sem o dígito. |
| `account_digit` | string | `"9"` | Dígito verificador da conta. |
| `account_branch` | string | `"0001"` | Agência da conta. |
| `if_name` | string | `"BANCO EXEMPLO S.A."` | Nome da instituição financeira. |
| `if_code` | string | `"999"` | Código COMPE da instituição financeira. |
| `if_ispb` | string | `"99999999"` | ISPB da instituição financeira. |
| `transaction_key` | string | `"30c40d50-0001-4ddd-9444-000000000401"` | Identificador único da transação na QI CTVM (UUID). |
| `external_key` | string | `"40d50e60-0001-4eee-9555-000000000501"` | Identificador da transação na instituição financeira de origem. |
| `transaction_description` | string | `"Liquidação de parcelas de CCB"` | Descrição da transação conforme informada pela instituição financeira. |
| `transaction_type` | string (enum) | `"incoming_pix"` | Tipo da transação. Ver [tabela de tipos](#tipos-de-transação). |
| `transaction_status` | string (enum) | `"reconciled"` | Status de conciliação: `created`, `pending_conciliation` ou `reconciled`. |
| `amount` | inteiro (centavos) | `241786` | Valor da transação. Negativo indica saída de caixa. |
| `previous_balance` | inteiro (centavos) | `52811947` | Saldo da conta antes da transação. |
| `post_balance` | inteiro (centavos) | `53053733` | Saldo da conta após a transação. |
| `transaction_datetime` | data | `2026-07-29` | Data e hora da transação. **No arquivo, o campo é exportado apenas com a data**, no formato `AAAA-MM-DD`. |
| `accounting_date` | data | `2026-07-29` | Data contábil atribuída à transação. |
| `conciliation_description` | string | `"Liquidação de parcelas"` | Descrição do grupo de conciliação ao qual a transação foi associada. Vazio enquanto a transação não é conciliada. |

## Tipos de transação

| Valor | Descrição |
|-------|-----------|
| `incoming_pix` | Pix recebido. |
| `outgoing_pix` | Pix enviado. |
| `incoming_wire_transfer` | TED recebida. |
| `outgoing_wire_transfer` | TED enviada. |
| `outgoing_bank_slip_payment` | Pagamento de boleto. |
| `incoming_bank_slip_payment_reversal` | Estorno de pagamento de boleto. |
| `outgoing_bankslip_registration` | Custo de registro de boleto. |
| `outgoing_bankslip_payment` | Custo de pagamento de boleto. |
| `outgoing_bankslip_due_date_extension` | Custo de prorrogação de vencimento de boleto. |
| `outgoing_bankslip_permanence` | Custo de permanência de boleto. |
| `outgoing_bankslip_rebate` | Custo de abatimento de boleto. |
| `outgoing_bankslip_write_off` | Custo de baixa de boleto. |

---

# Aquisição Consolidada de Direitos Creditórios

URL: /documentation/iaas/relatorios_dtvm/consolidated_credit_rights_acquisition_assets

## Visão Geral

O relatório `consolidated_credit_rights_acquisition_assets` lista os direitos creditórios adquiridos pelo fundo na data de referência, com os valores de compra, o spread e as características da operação. Em um único arquivo, ele reúne as duas naturezas de ativo:

- **operações de crédito** (ex: CCB) — uma linha por **parcela** adquirida;
- **direitos creditórios descontados** (ex: duplicatas) — uma linha por **ativo**, já que não têm parcelas.

Este relatório substitui os antigos `credit_rights_acquisition_assets`, `credit_rights_acquisition_installments` e `discounted_credit_rights_acquisition_assets`, que deixaram de ser entregues.

:::tip Também em PDF
Este relatório está descrito em linguagem de negócio no [Manual de Relatórios QI Tech](./manual_relatorios_qi_tech.pdf) — revisão 2, julho de 2026. O manual cobre quatro relatórios: este, a [Composição de Ativos da Cessão](/documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition), a [Composição de Carteira de Ativos](/documentation/iaas/relatorios_dtvm/assets_wallet_composition) e a [Conciliação Consolidada de Direitos Creditórios](/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_conciliation_assets).
:::

## O que você precisa informar

| Variável | Obrigatória | Descrição |
|----------|-------------|-----------|
| `fund_class_key` | sim | Identificador da classe de fundo sobre a qual o relatório é gerado. |
| `reference_date` | sim | Data de referência, no formato `AAAA-MM-DD`. |

## Estrutura do Arquivo

| Atributo | Valor |
|----------|-------|
| Formato | CSV |
| Encoding | UTF-8 |
| Delimitador | `,` (vírgula) |
| Cabeçalho | Sim (primeira linha) |
| Nomenclatura | `{nome_resumido_fundo}_consolidated_credit_rights_acquisition_assets_{YYYY-MM-DD}.csv` |

## O que o relatório traz

- Os ativos comprados na data de referência (`purchase_date` igual à data informada).
- Ativos inativos são excluídos.
- Campos sem valor vêm **vazios** no arquivo.

:::info Fundos de cota de abertura
Para os fundos que operam com relatório de cota de abertura, o ramo de direitos creditórios descontados usa o **dia útil imediatamente anterior** à data de referência, enquanto o ramo de operações de crédito usa a própria data. As duas naturezas convivem no mesmo arquivo com datas de referência diferentes.
:::

## Colunas

| Coluna | Tipo | Formato / Exemplo | Descrição |
|--------|------|-------------------|-----------|
| `reference_date` | data | `2026-07-29` | Data de compra do ativo. |
| `fund_class_name` | string | `"FUNDO EXEMPLO FIDC RESPONSABILIDADE LIMITADA"` | Nome da classe de fundo. |
| `fund_class_document_number` | string | `"12.345.678/0001-99"` | CNPJ da classe de fundo. |
| `originator_name` | string | `"ORIGINADOR EXEMPLO S.A."` | Nome da empresa originadora do ativo. |
| `originator_document_number` | string | `"11.222.333/0001-44"` | CNPJ do originador. |
| `assignor_name` | string | `"CEDENTE EXEMPLO S.A."` | Nome do cedente. |
| `assignor_document_number` | string | `"22.333.444/0001-55"` | CNPJ do cedente. |
| `borrower_name` | string | `"MARIA APARECIDA DE SOUZA"` | Nome do devedor (tomador do crédito) ou do sacado. |
| `borrower_document_number` | string | `"123.456.789-00"` | CPF ou CNPJ do devedor/sacado. |
| `asset_type` | string (enum) | `"ccb"`, `"duplicata_mercantil"`, `"duplicata_servicos"` | Tipo do ativo. Determina qual dos dois ramos originou a linha. |
| `has_assignor_coobligation` | booleano | `False` | Indica se há coobrigação do cedente. |
| `asset_key` | string | `"1a2b3c40-0001-4aaa-9111-000000000101"` | Chave interna do ativo gerada pela QI Tech (UUID). |
| `contract_number` | string | `"0900112233/EXA"` | Número do contrato (operação de crédito) ou do pedido (direito creditório descontado). Para direito creditório descontado sem número de pedido, cai no número do contrato. |
| `external_id` | string | `"10a20b30-0001-4bbb-9222-000000000201"` | Identificador externo do ativo. |
| `installment_number` | número | `1` | Número da parcela. Para direito creditório descontado, sempre `1`. |
| `issue_date` | data | `2026-07-28` | Data de emissão do contrato. Para direito creditório descontado, vem `-`. |
| `purchase_date` | data | `2026-07-29` | Data de compra do ativo pelo fundo. |
| `installment_maturity_date` | data | `2026-08-28` | Data de vencimento da parcela. Para direito creditório descontado, é o vencimento do próprio ativo. |
| `total_purchase_value` | número | `4712.35` | Valor total pago pelo ativo, incluindo encargos (em reais). Repete-se em todas as parcelas do mesmo ativo. |
| `asset_purchase_value` | número | `4690.8` | Valor do ativo sem encargos e sem spread (em reais). |
| `installment_purchase_value` | número | `1598.7421` | Valor de compra da parcela (em reais). Para direito creditório descontado, é igual ao `total_purchase_value`. |
| `principal_value` | número | `1480.12` | Valor de principal da parcela (em reais). Para direito creditório descontado, vem **vazio**. |
| `face_value` | número | `1678.9` | Valor de face da parcela ou do ativo (em reais). |
| `index` | string (enum) | `"pre_fixed"` | Indexador / tipo de taxa de juros. Para direito creditório descontado, sempre `pre_fixed`. |
| `index_calendar_base` | string (enum) | `"calendar_365"`, `"calendar_360"`, `"workdays"` | Base de calendário usada na apropriação de juros. Para direito creditório descontado, sempre `workdays`. |
| `monthly_rate` | string | `"0.0231"` | Taxa mensal pré-fixada do contrato. Para direito creditório descontado, traz a **taxa de compra do recebível (TIR)**, e não uma taxa mensal — no exemplo, `0.19842300000000`. |
| `calendar_base` | string (enum) | `"calendar_365"` | Base de calendário do pré-fixado. Para direito creditório descontado, sempre `workdays`. |
| `iof_value` | string | `"52.40"` | Valor de IOF do contrato. Para direito creditório descontado, vem `-`. |
| `maturity_date` | data | `2026-10-28` | Data de vencimento final do ativo. |
| `total_purchase_spread` | número | `21.55` | Spread de aquisição (`total_purchase_value − asset_purchase_value`), em reais. **Nunca negativo**: quando a diferença é menor que zero, o campo vem `0`. |

:::note Como cruzar as linhas de um mesmo ativo
As parcelas de uma operação de crédito repetem `asset_key`, `external_id` e `contract_number`, e variam apenas em `installment_number`, `installment_maturity_date`, `installment_purchase_value`, `principal_value` e `face_value`. Os valores de nível de ativo (`total_purchase_value`, `asset_purchase_value`, `total_purchase_spread`) se repetem em todas as parcelas — **não devem ser somados** por linha.
:::

---

# Conciliação Consolidada de Direitos Creditórios

URL: /documentation/iaas/relatorios_dtvm/consolidated_credit_rights_conciliation_assets

## Visão Geral

O relatório `consolidated_credit_rights_conciliation_assets` lista os eventos de pagamento dos direitos creditórios registrados em uma data contábil, mostrando o efeito de cada pagamento sobre o valor do ativo: valor antes, valor depois, redução e resultado contábil apurado. Em um único arquivo, ele reúne as duas naturezas de ativo:

- **operações de crédito** (ex: CCB);
- **direitos creditórios descontados** (ex: duplicatas).

Este relatório substitui os antigos `credit_rights_conciliation_assets`, `credit_rights_conciliation_installments` e `discounted_credit_rights_conciliation_assets`, que deixaram de ser entregues.

:::tip Também em PDF
Este relatório está descrito em linguagem de negócio no [Manual de Relatórios QI Tech](./manual_relatorios_qi_tech.pdf) — revisão 2, julho de 2026. O manual cobre quatro relatórios: este, a [Composição de Ativos da Cessão](/documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition), a [Composição de Carteira de Ativos](/documentation/iaas/relatorios_dtvm/assets_wallet_composition) e a [Aquisição Consolidada de Direitos Creditórios](/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_acquisition_assets).
:::

## O que você precisa informar

| Variável | Obrigatória | Descrição |
|----------|-------------|-----------|
| `fund_class_key` | sim | Identificador da classe de fundo sobre a qual o relatório é gerado. |
| `reference_date` | sim | Data de referência, no formato `AAAA-MM-DD`. |

## Estrutura do Arquivo

| Atributo | Valor |
|----------|-------|
| Formato | CSV |
| Encoding | UTF-8 |
| Delimitador | `,` (vírgula) |
| Cabeçalho | Sim (primeira linha) |
| Nomenclatura | `{nome_resumido_fundo}_consolidated_credit_rights_conciliation_assets_{YYYY-MM-DD}.csv` |

## O que o relatório traz

- Os eventos de pagamento cuja data contábil é a data de referência.
- Considera os ativos nas situações **ativo**, **vendido**, **liquidado** e **baixado**.
- Cada linha é **um evento de pagamento** — um mesmo ativo pode aparecer em várias linhas no mesmo dia.

:::info Campos sem valor vêm como `-`
Diferente dos outros relatórios em CSV, este preenche os campos nulos com `-` em vez de deixá-los vazios.
:::

:::info Fundos de cota de abertura
Para os fundos que operam com relatório de cota de abertura, o ramo de direitos creditórios descontados usa o **dia anterior** à data de referência, enquanto o ramo de operações de crédito usa a própria data.
:::

## Colunas

| Coluna | Tipo | Formato / Exemplo | Descrição |
|--------|------|-------------------|-----------|
| `reference_date` | data | `2026-07-29` | Data contábil do evento de pagamento. |
| `fund_class_name` | string | `"FUNDO EXEMPLO FIDC RESPONSABILIDADE LIMITADA"` | Nome da classe de fundo. |
| `fund_class_document_number` | string | `"12.345.678/0001-99"` | CNPJ da classe de fundo. |
| `originator_name` | string | `"ORIGINADOR EXEMPLO S.A."` | Nome da empresa originadora do ativo. |
| `originator_document_number` | string | `"11.222.333/0001-44"` | CNPJ do originador. |
| `assignor_name` | string | `"CEDENTE EXEMPLO S.A."` | Nome do cedente. |
| `assignor_document_number` | string | `"22.333.444/0001-55"` | CNPJ do cedente. |
| `borrower_name` | string | `"MARIA APARECIDA DE SOUZA"` | Nome do devedor (tomador do crédito) ou do sacado. |
| `borrower_document_number` | string | `"123.456.789-00"` | CPF ou CNPJ do devedor/sacado. |
| `asset_type` | string (enum) | `"ccb"`, `"duplicata_mercantil"`, `"duplicata_servicos"` | Tipo do ativo. Determina qual dos dois ramos originou a linha. |
| `asset_key` | string | `"1a2b3c40-0003-4aaa-9111-000000000103"` | Chave interna do ativo gerada pela QI Tech (UUID). |
| `external_id` | string | `"10a20b30-0003-4bbb-9222-000000000203"` | Identificador externo do ativo. |
| `contract_number` | string | `"0900098765/EXC"` | Número do contrato (operação de crédito) ou do pedido (direito creditório descontado). Para direito creditório descontado sem número de pedido, cai no número do contrato. |
| `maturity_date` | data | `2027-01-11` | Data de vencimento final do ativo. |
| `total_purchase_value` | número | `5324.8` | Valor total pago pelo fundo na aquisição do ativo (em reais). |
| `purchase_date` | data | `2026-01-12` | Data de aquisição do ativo pelo fundo. |
| `internal_rate_of_return` | número | `0.0231` | Taxa interna de retorno do ativo. Operação de crédito: taxa corrente. Direito creditório descontado: taxa de compra do recebível. |
| `payment_date` | data | `2026-07-29` | Data contábil do pagamento. Traz sempre o mesmo valor de `reference_date`. |
| `payment_amount` | número | `512.68` | Valor pago no evento (em reais). |
| `payment_key` | string | `"20b30c40-0001-4ccc-9333-000000000301"` | Chave interna do evento de pagamento gerada pela QI Tech (UUID). |
| `payment_type` | string (enum) | `"installment_settlement"`, `"installment_amortization"`, `"asset_settlement"`, `"asset_amortization"`, `"fine_payment"`, `"gloss"`, ... | Tipo do pagamento. |
| `payment_event_type` | string (enum) | `"settlement"`, `"substitution"`, `"repurchase"`, `"unperformed"` | Natureza do evento que originou o pagamento: liquidação, substituição, recompra ou inadimplemento. Eventos anteriores à criação deste campo vêm como `-`. |
| `old_asset_current_value` | número | `5361.42` | Valor contábil do ativo imediatamente **antes** do evento (em reais). |
| `new_asset_current_value` | número | `4890.33` | Valor contábil do ativo imediatamente **depois** do evento (em reais). |
| `asset_reduction_value` | número | `471.09` | Redução do valor contábil do ativo (`old − new`), em reais. |
| `result_value` | número | `41.59` | Resultado contábil apurado no evento (em reais). |
| `written_off_accounting_result_value` | número inteiro | `0` | Resultado contábil de baixa (*write-off*) associado ao evento, **em centavos** — este é o único campo monetário do arquivo que não é convertido para reais. Para direito creditório descontado, sempre `0`. |
| `installment_number` | string | `"1"` | Número da parcela liquidada. Para direito creditório descontado, é o sufixo do número do pedido quando ele existe (`8977-3` → `3`); caso contrário, `-`. |

:::tip Conferindo o resultado do dia
A soma de `result_value` é o resultado contábil reconhecido pelos direitos creditórios na data, e deve fechar com as contas de receita correspondentes no [Relatório de Balanço](/documentation/iaas/relatorios_dtvm/balance_report) e na [Razão Contábil](/documentation/iaas/relatorios_dtvm/accounting_ledger). A soma de `asset_reduction_value` é a variação do estoque explicada por pagamentos no dia.
:::

---

# Relatórios DTVM

URL: /documentation/iaas/relatorios_dtvm/

Os relatórios DTVM fornecem uma visão detalhada das operações e posições financeiras dos fundos de investimento administrados pela QI CTVM. Eles são destinados a gestores e analistas que precisam acompanhar a composição da carteira, as aquisições e liquidações de ativos, e a movimentação de caixa do fundo em cada data de referência.

## Exemplos de relatórios

Baixe exemplos de todos os relatórios disponíveis: [example_reports.zip](./example_reports.zip)

O pacote contém um arquivo de cada relatório, gerado pelo mesmo código que produz os arquivos em produção, com dados fictícios. Os exemplos são consistentes entre si: descrevem o mesmo fundo (`FUNDO EXEMPLO FIDC RESPONSABILIDADE LIMITADA`), na mesma data de referência (`2026-07-29`), e fecham entre si — o patrimônio líquido, o saldo de caixa e a posição por classe de ativo são os mesmos em todos os arquivos que trazem esses números.

## Nomenclatura dos arquivos

Todos os arquivos seguem o padrão `{nome_resumido_fundo}_{modelo}_{data_de_referência}.{extensão}`, onde:

- **nome resumido do fundo** é derivado do nome curto cadastrado para a classe de fundo, em minúsculas, sem acentos e com espaços convertidos em `_` (nos exemplos, `example_name`);
- **modelo** é o nome do relatório, conforme a coluna "Modelo" da tabela abaixo;
- **data de referência** está no formato `AAAA-MM-DD`.

O prefixo vem do cadastro da classe, não da configuração da entrega, e não muda depois. Se você precisa de um prefixo diferente, fale com o time de integração.

Há três exceções ao padrão: o `wallet_composition_by_composition` é entregue como `wallet_composition` (sem o sufixo do modelo); o `assignment_assets_wallet_composition` acrescenta o identificador da cessão ao final do nome; e o `assignment_documents` coloca o identificador da cessão **antes** da data, que nele é a data de geração do arquivo.

:::info Relatórios de período
`quota_mec`, `balance_report` e `accounting_ledger` são gerados a partir de um intervalo (`start_date` / `end_date`), e não de uma única data. Nesses casos, a data no nome do arquivo é a data de referência da entrega.
:::

## Convenções dos arquivos CSV

Valem para todos os relatórios em CSV:

| Atributo | Padrão |
|----------|--------|
| Encoding | UTF-8, **sem BOM** |
| Delimitador | `,` (vírgula) |
| Separador decimal | `.` (ponto) |
| Fim de linha | `CRLF` (`\r\n`) |
| Cabeçalho | sempre presente, na primeira linha, com os nomes das colunas em minúsculas |

:::note Delimitador e separador decimal são configuráveis
Se o seu processo exigir `;` como delimitador ou `,` como separador decimal, a QI CTVM pode configurar isso por fundo na entrega. Sem configuração específica, valem os padrões da tabela acima. A exceção é o `quota_mec` em CSV, que usa `;` por definição do relatório.
:::

## Como os relatórios são entregues

A entrega é organizada em **rotinas**, configuradas por fundo. Cada rotina define três coisas: **quais** relatórios entram, com **qual periodicidade**, e para **qual destino**.

| Elemento | Opções |
|----------|--------|
| Periodicidade | diária · semanal (primeiro dia útil da semana) · mensal (último dia útil do mês) |
| Destino | SFTP · e-mail |

Um mesmo fundo pode ter mais de uma rotina — por exemplo, uma diária em SFTP e uma mensal por e-mail. Para incluir ou remover um relatório, mudar a periodicidade ou o destino, entre em contato com o time de integração.

### Quando a rotina é disparada

O gatilho é o **fechamento do dia daquele fundo**, e não um horário fixo. O fechamento acontece somente em dia útil, e dispara os relatórios em três momentos distintos:

| Momento | Contém |
|---------|--------|
| Pré-cota | Relatórios apurados antes do cálculo da cota do dia. |
| Fechamento | Relatórios da posição consolidada do dia, com a cota de fechamento. |
| Abertura | Relatórios apurados sobre a cota de abertura. |

Cada relatório é entregue no momento previsto na configuração da rotina do fundo — é por isso que os arquivos de um mesmo dia não chegam todos juntos. Uma rotina semanal ou mensal só materializa arquivos na data em que a periodicidade dela cai; nos outros dias o fechamento roda e ela não produz nada.

### Relatórios fora da rotina

Dois relatórios não seguem a periodicidade da rotina, porque não são do dia do fundo e sim de uma operação: a [Composição de Ativos da Cessão](/documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition) e os [Lastros da Cessão](/documentation/iaas/relatorios_dtvm/assignment_documents). Os dois são gerados quando a cessão entra na etapa de aprovação, desde que estejam habilitados na configuração de cessão, e são gravados na mesma pasta de SFTP do fundo.

Eles **não** emitem o [Webhook de Entrega](/documentation/iaas/relatorios_dtvm/webhook_de_entrega) — o acompanhamento é pelo [webhook de status do lote de cessão](/documentation/iaas/negociacao_recebiveis/assignment/webhooks).

### Entrega via SFTP

Cada arquivo é gravado na pasta configurada para o fundo, com exatamente o nome descrito acima. Para instruções de conexão, credenciais e exemplos de código para download, consulte a [documentação de integração SFTP](/documentation/iaas/integracao_sftp/inicio).

:::tip Você pode ser avisado a cada entrega concluída
Em vez de varrer a pasta em intervalos fixos, configure o [Webhook de Entrega](/documentation/iaas/relatorios_dtvm/webhook_de_entrega): ao fim de cada entrega, a QI CTVM notifica a sua aplicação com a lista de arquivos gravados e o status de cada relatório.
:::

## Relatórios disponíveis

| Relatório | Descrição | Modelo | Formato do arquivo |
|-----------|-----------|--------|-------------------|
| [Composição de Carteira de Ativos](/documentation/iaas/relatorios_dtvm/assets_wallet_composition) | Posição completa de todos os ativos que compõem o estoque do fundo em uma data de referência, ativo a ativo. | `assets_wallet_composition` | CSV |
| [Composição de Ativos da Cessão](/documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition) | Ativos de uma cessão específica, no mesmo formato da composição de carteira. Gerado por cessão, fora da rotina diária. | `assignment_assets_wallet_composition` | CSV |
| [Lastros da Cessão](/documentation/iaas/relatorios_dtvm/assignment_documents) | Documentos comprobatórios dos ativos de uma cessão, com link de download por arquivo. Gerado por cessão, fora da rotina diária. | `assignment_documents` | CSV |
| [Composição da Carteira](/documentation/iaas/relatorios_dtvm/wallet_composition) | Carteira consolidada do fundo ao fim do dia, por classe de ativo, com séries de emissão, valores a pagar e a receber, caixa, rentabilidade e resultado. | `wallet_composition_by_composition` | XLSX |
| [Aquisição Consolidada de Direitos Creditórios](/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_acquisition_assets) | Direitos creditórios adquiridos em um dia — operações de crédito por parcela e direitos creditórios descontados por ativo, no mesmo arquivo. | `consolidated_credit_rights_acquisition_assets` | CSV |
| [Conciliação Consolidada de Direitos Creditórios](/documentation/iaas/relatorios_dtvm/consolidated_credit_rights_conciliation_assets) | Eventos de pagamento dos direitos creditórios em uma data contábil, com o efeito de cada pagamento sobre o valor do ativo. | `consolidated_credit_rights_conciliation_assets` | CSV |
| [Demonstrativo de Caixa](/documentation/iaas/relatorios_dtvm/cash_account_demonstrative) | Extrato diário das movimentações e saldos das contas bancárias do fundo. | `cash_account_demonstrative` | XLSX |
| [Movimentações de Caixa](/documentation/iaas/relatorios_dtvm/cash_account_demonstrative_movements) | Mesma movimentação do demonstrativo de caixa em formato tabular, transação a transação, para conciliação automatizada. | `cash_account_demonstrative_movements` | CSV |
| [Cotas MEC](/documentation/iaas/relatorios_dtvm/quota_mec) | Evolução diária de cotas, patrimônio e rentabilidade das séries de emissão. | `quota_mec` | XLSX ou CSV |
| [Relatório de Balanço](/documentation/iaas/relatorios_dtvm/balance_report) | Balanço contábil consolidado do fundo com saldos e movimentações por conta. | `balance_report` | XLSX |
| [Razão Contábil](/documentation/iaas/relatorios_dtvm/accounting_ledger) | Razão contábil detalhado com todos os lançamentos por conta no período. | `accounting_ledger` | XLSX |
| [XML ANBIMA (tipos 5 e 401)](/documentation/iaas/relatorios_dtvm/xml_anbima) | Arquivos de posição no padrão ANBIMA, gerados a partir da composição da carteira. | `xml_5_by_composition` `xml_401_by_composition` | XML |

---

# Cotas MEC

URL: /documentation/iaas/relatorios_dtvm/quota_mec

## Visão Geral

O relatório `quota_mec` apresenta a evolução diária das cotas e do patrimônio do fundo em um intervalo de datas, calculada com base nos fechamentos de série de emissão. Cada linha representa um dia útil de uma série de emissão, contendo valores de patrimônio bruto e líquido, cota de fechamento, movimentações de aplicação e resgate, come-cotas e rentabilidade acumulada diária, mensal e anual. Gestores e administradores utilizam este relatório para acompanhar a performance do fundo e enviar informações regulatórias ao MEC (Método de Envio de Cota).

O relatório pode ser gerado nos formatos XLSX (uma aba por classe de fundo) ou CSV. O CSV só é aceito quando o pedido cobre **uma única classe de fundo**.

## O que você precisa informar

| Variável | Obrigatória | Descrição |
|----------|-------------|-----------|
| `fund_class_key` | sim | Identificador da classe de fundo sobre a qual o relatório é gerado. |
| `start_date` | sim | Data de início do período, no formato `AAAA-MM-DD`. |
| `end_date` | sim | Data de fim do período, no formato `AAAA-MM-DD`. Não pode ser anterior à data de início. |
| `include_secondary_market` | não | Booleano. Quando omitido, vale `true`. |
| `file_format` | não | `xlsx` (padrão) ou `csv`. Qualquer outro valor é recusado. |
| `issuance_serie_key` | não | Restringe o arquivo a uma única série de emissão. |

:::warning É preciso haver cota no período
O relatório só é gerado se ao menos uma série de emissão da classe tiver valor de cota (de abertura ou de fechamento) dentro do intervalo. Sem isso a solicitação é recusada.
:::

## Estrutura do Arquivo

| Atributo | Valor |
|----------|-------|
| Formato | XLSX ou CSV |
| Encoding | UTF-8 |
| Delimitador (CSV) | `;` (ponto e vírgula) |
| Nomenclatura | `{nome_resumido_fundo}_quota_mec_{AAAA-MM-DD}.xlsx` (ou `.csv`) |

No XLSX, cada classe de fundo ocupa uma aba, nomeada com o nome do fundo (limitado a 31 caracteres pelo Excel), o cabeçalho vem em português e as linhas em ordem cronológica crescente. Datas são apresentadas no formato `DD/MM/AAAA`.

:::info Variação no formato CSV
O CSV é gerado apenas para uma classe de fundo por arquivo e difere do XLSX em dois pontos: o cabeçalho vem com os **nomes técnicos em inglês** (`fund_class_name`, `fund_class_document_number`, `sub_class_name`, `issuance_serie_name`, `accounting_date`, `gross_net_worth`, `gross_quota_value`, `performance_fee_current_value`, `net_net_worth`, `net_quota_value`, `final_net_worth`, `final_quota_value`, `total_net_worth`, `issued_quotas`, `total_daily_applications`, `redeemed_quotas`, `total_daily_redemptions`, `tax_anticipated_quotas`, `total_daily_tax_anticipations`, `total_daily_amortizations`, `daily_rentability`, `monthly_rentability`, `yearly_rentability`), na mesma ordem da tabela abaixo; e as linhas vêm em ordem **cronológica decrescente**, da data mais recente para a mais antiga.
:::

## Colunas

| Coluna | Tipo | Formato / Exemplo | Descrição |
|--------|------|-------------------|-----------|
| `Nome do Fundo` | string | `"FUNDO EXEMPLO FIDC RESPONSABILIDADE LIMITADA"` | Nome da classe de fundo. |
| `CNPJ do Fundo` | string | `"12.345.678/0001-99"` | CNPJ da classe de fundo. |
| `Sub Classe` | string | `"SUBORDINADA"` | Nome da subclasse do fundo. |
| `Série de Emissão` | string | `"PRIMEIRA"` | Nome da série de emissão. |
| `Data de Referência` | data | `29/07/2026` | Data contábil de referência (apenas dias úteis). |
| `Patrimônio Bruto` | número | `10500000.00` | Patrimônio líquido bruto antes da provisão de taxa de performance (em reais). |
| `Cota Bruta` | número | `1.050000` | Valor da cota bruta antes da taxa de performance. |
| `Taxa de Performance` | número | `5000.00` | Valor corrente da taxa de performance provisionada (em reais). |
| `PL Pré Movimentação` | número | `10495000.00` | Patrimônio líquido antes das movimentações do dia (em reais). |
| `Cota Pré Movimentação` | número | `1.049500` | Valor da cota antes das movimentações do dia. |
| `PL de Fechamento` | número | `10495000.00` | Patrimônio líquido de fechamento antes das amortizações (em reais). |
| `Cota de Fechamento` | número | `1.049500` | Valor da cota de fechamento antes das amortizações. |
| `PL Pós Movimentações` | número | `10490000.00` | Patrimônio líquido total após todas as movimentações do dia (em reais). |
| `Cotas Integralizadas` | número | `1000.00000` | Quantidade de cotas emitidas (aplicadas) no dia. |
| `Total Aplicado` | número | `1049500.00` | Valor total aplicado no dia (em reais). |
| `Cotas Resgatadas` | número | `500.00000` | Quantidade de cotas resgatadas no dia. |
| `Total Resgatado` | número | `524750.00` | Valor total resgatado no dia (em reais). |
| `Come-cotas` | número | `200.00000` | Quantidade de cotas consumidas pela antecipação de IR (come-cotas). |
| `Total de Come-cotas` | número | `200.00` | Valor total do come-cotas do dia (em reais). |
| `Total Amortizado` | número | `0.00` | Valor total amortizado no dia (em reais). |
| `Rentabilidade Diária` | número | `0.000420` | Rentabilidade do dia, calculada como `(cota_pré_movimentação / cota_fechamento_anterior) - 1`. |
| `Rentabilidade Mensal` | número | `0.005200` | Rentabilidade acumulada no mês corrente (base composta). Reinicia no início de cada mês. |
| `Rentabilidade Anual` | número | `0.063000` | Rentabilidade acumulada no ano corrente (base composta). Reinicia no início de cada ano. |

---

# Testando a Captura de Lastro

URL: /documentation/iaas/relatorios_dtvm/testar_captura_lastro

Esta página é um roteiro para quem está construindo a leitura automatizada dos [Lastros da Cessão](/documentation/iaas/relatorios_dtvm/assignment_documents) e precisa de um `document_url` que funcione de verdade para testar antes de ir a produção.

A ideia é simples: em sandbox, você roda uma cessão de ponta a ponta usando os PDFs de exemplo que disponibilizamos abaixo. O `assignment_documents` é gerado pelo mesmo código que gera o relatório em produção, com links pré-assinados legítimos — nada é montado à mão.

:::info Por que não entregamos um arquivo pronto com links
`document_url` é uma URL pré-assinada de S3, gerada no momento em que o relatório é produzido e válida por 5 dias. Um arquivo estático com links reais expiraria antes de chegar até você. Rodando o roteiro, você gera links novos sempre que precisar.
:::

## O que você precisa ter em sandbox

Este teste usa o fluxo normal de cessão, então ele pressupõe o mesmo setup de qualquer integração:

| Item | Como obter |
|------|------------|
| Classe de fundo (`fund_class_key`) | Fornecida pelo time de integração. |
| Configuração de cessão (`assignment_configuration_key`) | Fornecida pelo time de integração. Ela define o tipo de ativo da cessão e quais documentos são exigidos. |
| `assignment_documents` na rotina de relatórios da configuração | Peça ao time de integração para incluir o relatório na configuração de cessão. Sem isso o arquivo não é gerado. |
| Destino de entrega (SFTP) | Configurado junto com a rotina de relatórios. Veja a [integração SFTP](/documentation/iaas/integracao_sftp/inicio). |

:::warning Não há atalho para o setup
Não existe caminho que produza um `document_url` real sem uma cessão real em sandbox — o relatório é uma consulta aos documentos efetivamente anexados aos ativos daquela cessão. Se o seu objetivo é apenas conferir a estrutura das colunas, use o [pacote de exemplos](/documentation/iaas/relatorios_dtvm/) da introdução, que traz o CSV com URL de exemplo no formato correto.
:::

## Arquivos de exemplo

Um documento por `document_type`, com dados fictícios, texto extraível (não são imagem) e a estrutura típica de cada tipo:

[📦 Baixar todos (lastros_exemplo.zip)](/downloads/lastros_exemplo.zip)

| Arquivo | `document_type` | O que é |
|---------|-----------------|---------|
| [ccb_exemplo_01.pdf](/downloads/lastros_exemplo/ccb_exemplo_01.pdf) | `ccb` | CCB emitida pela QI SCD, 3 parcelas, 22 páginas com cadeia de endossos |
| [ccb_exemplo_02.pdf](/downloads/lastros_exemplo/ccb_exemplo_02.pdf) | `ccb` | CCB emitida pela QI SCD, 2 parcelas, 22 páginas com cadeia de endossos |
| [duplicata_mercantil_exemplo.pdf](/downloads/lastros_exemplo/duplicata_mercantil_exemplo.pdf) | `duplicata_mercantil` | Duplicata mercantil com chave de acesso da NF-e |
| [invoice_exemplo.pdf](/downloads/lastros_exemplo/invoice_exemplo.pdf) | `invoice` | DANFE da NF-e referenciada pela duplicata |
| [duplicata_servicos_exemplo.pdf](/downloads/lastros_exemplo/duplicata_servicos_exemplo.pdf) | `duplicata_servicos` | Duplicata de prestação de serviços, referenciando NFS-e |
| [cte_exemplo.pdf](/downloads/lastros_exemplo/cte_exemplo.pdf) | `cte` | DACTE |
| [discounted_contract_exemplo.pdf](/downloads/lastros_exemplo/discounted_contract_exemplo.pdf) | `discounted_contract` | Contrato de prestação de serviços com cláusula de cessão |

:::danger Estes arquivos são fictícios
Nenhum deles tem validade jurídica ou fiscal, nenhum foi transmitido à SEFAZ e nenhum contém dados de pessoas ou empresas reais. Servem exclusivamente para teste de leitura.
:::

Os dois PDFs de `ccb` são consistentes com o `example_reports.zip` publicado na [introdução aos relatórios](/documentation/iaas/relatorios_dtvm/): mesmos números de contrato (`0900112233/EXA` e `0900112247/EXB`), mesmos valores de parcela, mesmos vencimentos e mesma taxa mensal que aparecem no `assignment_assets_wallet_composition` de exemplo.

:::tip As CCBs de exemplo seguem o layout real de emissão da QI Tech
Os dois PDFs de `ccb` são a estrutura de verdade de uma CCB emitida pela **QI Sociedade de Crédito Direto S.A.** — os Quadros I a XI na ordem em que aparecem no documento real, com o texto integral das condições gerais e especiais, a página de assinatura eletrônica do emitente e a **cadeia de endossos** até o fundo. É o documento que o seu leitor vai encontrar em produção quando o originador emite pela QI Tech, com os dados trocados por fictícios.

Três partes que costumam ser as mais úteis para validação de lastro:

- **Quadro V, item 5** — a tabela com as datas possíveis de liberação. Cada linha tem seu próprio Valor Total, IOF, Valor Líquido e CET; a linha que vale é a da data em que os recursos foram efetivamente liberados. Um leitor que assuma uma linha só extrai o valor errado.
- **Quadro V, item 13** — o demonstrativo do CET, que reconcilia com a **primeira** linha da tabela do item 5.
- **Endossos (últimas páginas)** — a cadeia `QI SCD → cedente → fundo`, cada elo com sua própria página de assinatura digital (hash, data, signatários). É por aí que se comprova a titularidade do título pelo fundo.

O `document_type` do relatório continua sendo a fonte de verdade sobre o tipo — não tente inferir da estrutura interna.
:::

:::warning Duas duplicações do template foram preservadas de propósito
O template de produção repete palavras em dois pontos, e os exemplos reproduzem isso:

- item 1.1 do Quadro V — `2,3100% % a.m. (dois inteiros e três mil e cem décimos de milésimo por cento por cento)`, com `%` e `por cento` duplicados;
- item 2 do Quadro V — `2. Prazo: 91 dias dias corridos.`

Não é erro destes arquivos. Mantivemos como está para o seu leitor encontrar em sandbox exatamente o texto que vai encontrar em produção — se você normalizar o texto antes de casar o padrão, esses dois campos são os que mais provavelmente quebram. Quando o template for corrigido, os exemplos são regerados.
:::

:::note CPF e CNPJ destes PDFs têm dígito verificador válido
Os documentos de exemplo do restante da documentação usam CPF e CNPJ de fachada, com dígito verificador **inválido** — `123.456.789-00`, `12.345.678/0001-99` e afins. Isso não incomoda quem só lê um payload de exemplo, mas reprovaria em qualquer validação de lastro que confira DV.

Nestes PDFs os dígitos verificadores foram corrigidos, preservando os 12 primeiros dígitos: `123.456.789-09`, `12.345.678/0001-95`, `22.333.444/0001-81`. As chaves de acesso de NF-e e CT-e também têm DV correto e embutem o CNPJ do emitente já corrigido.

Consequência: o `borrower_document` do `assignment_assets_wallet_composition` de exemplo difere do CPF impresso no PDF nos dois últimos dígitos. Se você está testando o cruzamento entre os dois arquivos, use `asset_external_id`, `asset_key`, número de contrato, valores e vencimentos — não o documento do sacado.
:::

## Roteiro

### 1. Crie a cessão

ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment
MÉTODO POST

O `external_id` que você informar aqui é o mesmo que vai aparecer na coluna `assignment_external_id` do relatório e no nome do arquivo. Detalhes em [Criação da Cessão](/documentation/iaas/negociacao_recebiveis/assignment/criacao).

### 2. Insira o ativo

ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/asset
MÉTODO POST

O payload depende do tipo de ativo da sua configuração de cessão — veja [Criação de Ativos](/documentation/iaas/negociacao_recebiveis/asset/criacao_co) para operação de crédito, ou as páginas de [duplicata](/documentation/iaas/negociacao_recebiveis/asset/criacao_duplicata), [CT-e](/documentation/iaas/negociacao_recebiveis/asset/criacao_cte) e [contrato descontado](/documentation/iaas/negociacao_recebiveis/asset/criacao_discounted_contract).

Guarde o `external_id` do ativo: ele é a chave de junção com os outros relatórios.

### 3. Anexe o documento de exemplo

Converta o PDF escolhido para Base64:

```bash
base64 -w 0 ccb_exemplo_01.pdf > ccb_exemplo_01.b64
```

ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/asset/{asset_external_id}/document
MÉTODO POST

```json title="Request Body"
{
    "document_type": "ccb",
    "document_b64": "JVBERi0xLjcKJfCflqQKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwo..."
}
```

Os tipos aceitos em `document_type` são os que a **sua** configuração de cessão exige, não a lista completa de tipos existentes. Detalhes e erros possíveis em [Inserção de Documentos do Ativo](/documentation/iaas/negociacao_recebiveis/asset/documents).

:::note Duplicatas mercantis podem não passar por aqui
Para ativos do tipo `duplicata_mercantil`, a plataforma pode gerar a documentação automaticamente a partir dos dados da nota fiscal — nesse caso não há upload a fazer, e o lastro aparece no relatório sem você anexar nada.

Isso **depende da configuração de cessão**: em algumas configurações a geração automática não acontece e o documento é esperado por upload. Confirme com o time de integração qual dos dois casos se aplica à sua antes de montar o teste. Independente disso, os PDFs de `duplicata_mercantil` e `invoice` deste pacote servem como referência de estrutura para o seu leitor.
:::

### 4. Encerre a inserção

ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}
MÉTODO PUT

```json title="Request Body"
{
    "assignment_status": "completed_assets_insertion"
}
```

A partir daqui a cessão segue para a elegibilidade e para a aprovação — veja [Encerramento da inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento) e [Aprovação da cessão](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao).

### 5. Receba o arquivo

O `assignment_documents` é gerado quando a cessão passa pela etapa de aprovação e gravado na pasta de SFTP configurada para o fundo, com o nome:

```
{nome_resumido_fundo}_assignment_documents_{external_id}_{AAAA-MM-DD}.csv
```

É o CSV com os links — os PDFs em si não são transferidos para o SFTP. Instruções de conexão e exemplos de download em [Integração SFTP](/documentation/iaas/integracao_sftp/inicio).

:::danger O arquivo espera na pasta, os links não
Este é o ponto de atenção mais importante da entrega por SFTP. A validade de 5 dias dos links começa a contar na **geração** do relatório, não na hora em que você busca o arquivo. O CSV continua na pasta indefinidamente, mas um arquivo coletado no sexto dia traz links que já não funcionam.

Colete o arquivo assim que ele chegar, ou trate o erro de link expirado como sinal de que o relatório precisa ser gerado novamente — e não como falha do seu leitor.
:::

:::warning Este relatório não emite o Webhook de Entrega
O [Webhook de Entrega](/documentation/iaas/relatorios_dtvm/webhook_de_entrega) cobre as rotinas de relatório do fundo, e não as entregas geradas por cessão. Para o `assignment_documents` não há aviso de arquivo disponível.

O sinal mais próximo é o [webhook de status do lote de cessão](/documentation/iaas/negociacao_recebiveis/assignment/webhooks). Em fluxos com aprovação manual, a passagem para `pending_consultant_approval` ou `pending_manager_approval` marca a entrada na etapa de aprovação, que é quando o relatório é gerado — use esse evento para agendar a coleta. Em fluxos com aprovação automática esses dois status não ocorrem, e o sinal utilizável é o status seguinte do lote no seu fluxo. Em ambos os casos o arquivo aparece na pasta em seguida, não no mesmo instante do webhook.
:::

## O que validar no seu leitor

Três comportamentos do `document_url` que costumam quebrar implementações e que você consegue exercitar com o arquivo que acabou de receber:

**Os links expiram em 5 dias.** São URLs pré-assinadas com `X-Amz-Expires=432000`, contados do momento da geração do relatório. Passado o prazo o link retorna erro e é preciso gerar o relatório novamente. O identificador estável do documento é o `document_key` — nunca a URL. Se você precisa arquivar o lastro, baixe os arquivos dentro da janela.

**O arquivo chega sem nome útil e sem extensão.** O download vem com os headers:

```http
Content-Disposition: attachment; filename="file"
Content-Type: binary/octet-stream
```

Ou seja: o arquivo se chama `file`, sem extensão, e o content-type não identifica o formato. Não infira o tipo pelo nome nem pelo content-type — use a coluna `document_type` do CSV. O conteúdo é sempre PDF.

**Um ativo pode ocupar mais de uma linha.** Quando o ativo tem mais de um documento, ele aparece repetido, com o mesmo `asset_key` e `document_type` diferente. Ativos sem documento anexado não aparecem, e ativos descartados (`discarded`) ou reprovados (`denied`) são excluídos do arquivo.

:::caution `document_url` não é sempre uma URL
Se a assinatura do link falhar no momento em que o relatório é gerado, a coluna vem preenchida com uma **mensagem de erro em texto**, não com uma URL — e o CSV é entregue normalmente, com as outras colunas íntegras.

Trate `document_url` como campo não confiável: valide que o valor começa com `https://` antes de tentar baixar. Uma linha nessa condição significa que aquele documento precisa ser obtido em uma nova geração do relatório, não que o arquivo não exista. Um leitor que assuma "toda linha tem URL válida" quebra no primeiro caso desses.
:::

## Cruzando com a composição da cessão

Para validação de lastro, o cruzamento mais útil é entre este relatório e a [Composição de Ativos da Cessão](/documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition), pelas colunas `asset_external_id` e `asset_key`. Ativo que aparece na composição e não aparece no lastro é ativo sem documento anexado.

## Um limite deste teste

**Não existe um layout QI Tech DTVM por tipo de documento.** Os arquivos de lastro são os documentos originais do cedente ou do originador — a CCB emitida pelo originador, o DANFE gerado pelo ERP dele, o DACTE da transportadora. A DTVM armazena e valida esses arquivos, não os gera, e é por isso que a validação de cada tipo é configurada por template do nosso lado.

:::note "QI Tech" não é o mesmo que "QI Tech DTVM"
A distinção importa aqui. A QI Tech **emite** crédito por outras frentes — BaaS e LaaS — e essas emissões têm, sim, um layout próprio de CCB, que é o das CCBs de exemplo desta página. O que não existe é um layout definido pela **DTVM** para o lastro que ela recebe: quando o originador é a própria QI Tech, o documento segue o padrão daquela emissão; quando é outro originador, segue o padrão dele.

Ou seja: a CCB de exemplo é *um* layout de lastro possível — o mais provável, se o seu originador emite pela QI Tech — e não *o* layout que a DTVM exige.
:::

Consequência prática: o que você pode tratar como contrato estável é o CSV — colunas, tipos e semântica. O interior do PDF varia por originador. Se o seu fundo compra de mais de um originador, ou se o originador não emite pela QI Tech, teste também contra um arquivo real dele antes de fechar a implementação. Os outros cinco exemplos (duplicata, invoice, CT-e, contrato) reproduzem a estrutura típica de cada tipo, mas não vêm de um emissor específico — são referência de campos, não de layout.

---

# Composição da Carteira

URL: /documentation/iaas/relatorios_dtvm/wallet_composition

## Visão Geral

O relatório `wallet_composition_by_composition` é a foto consolidada da carteira do fundo ao fim do dia. Ele reúne, em uma única planilha, o patrimônio e a cota de cada série de emissão, a posição por classe de ativo (títulos públicos, emissões, operações de crédito, direitos creditórios descontados, cotas de fundo, swaps e imóveis), os valores a pagar e a receber, os saldos de caixa e a rentabilidade das séries — sempre com o percentual que cada linha representa do patrimônio líquido.

É o relatório usado por gestores e administradores para conferir o fechamento do dia: o somatório das seções de ativos, menos os valores a pagar e mais os valores a receber, reconcilia com o patrimônio líquido informado no cabeçalho.

:::info Base do relatório
O relatório é gerado a partir de uma **composição** de carteira já fechada — confirmada ou aguardando confirmação. Por padrão é usada a composição de cota de fechamento (`final_quota`); mediante configuração, também pode ser gerado sobre a composição de cota de abertura (`opening_quota`) ou pré-cota (`pre_quota`).
:::

## O que você precisa informar

| Variável | Obrigatória | Descrição |
|----------|-------------|-----------|
| `fund_class_key` | sim | Identificador da classe de fundo sobre a qual o relatório é gerado. |
| `reference_date` | sim, se não informar `composition_key` | Data de referência, no formato `AAAA-MM-DD`. |
| `composition_key` | alternativa à data | Identificador de uma composição específica. |
| `composition_type` | não | `final_quota` (padrão), `opening_quota` ou `pre_quota`. Qualquer outro valor é recusado. |

:::warning É preciso existir composição na data
Se não houver composição do tipo pedido na data de referência, a solicitação é recusada com a mensagem "Não existe composition para esta 'reference_date'".
:::

## Estrutura do Arquivo

| Atributo | Valor |
|----------|-------|
| Formato | XLSX |
| Abas | `Sheet` (composição) e `P&L` (receitas e despesas do dia) |
| Nomenclatura | `{nome_resumido_fundo}_wallet_composition_{AAAA-MM-DD}.xlsx` |

:::note Nome do arquivo
O modelo a ser solicitado é `wallet_composition_by_composition`, mas o arquivo entregue é nomeado `wallet_composition`, sem o sufixo.
:::

Cada seção é apresentada com um título em negrito, uma linha de cabeçalho e, ao final, linhas de total por tipo de ativo e um total geral da seção — essas linhas de total aparecem em negrito e com fundo cinza. **Seções sem posição na data não são impressas**: um fundo que não tem imóveis, por exemplo, não terá a seção `IMÓVEIS`.

:::tip Como conferir o fechamento
Somando a coluna `% do PL` dos totais gerais de todas as seções — ativos, mais valores a receber, menos valores a pagar, mais caixa — o resultado é 100% do patrimônio líquido do cabeçalho.

Uma diferença pequena pode aparecer quando o fundo tem **emissões com ágio ainda não diferido**: na seção `EMISSÕES` o `Valor D0 (R$)` é apurado pelo valor contábil do papel, enquanto nas demais classes ele considera o valor justo. O ágio a diferir, nesse caso, fica fora da soma das seções, mas está dentro do patrimônio líquido.
:::

## Aba `Sheet`

### Cabeçalho do fundo

| Campo | Descrição |
|-------|-----------|
| Data de referência | Data da composição, no formato `AAAA-MM-DD`. |
| Nome da classe de fundo | Nome completo da classe de fundo. |
| CNPJ da classe de fundo | CNPJ da classe de fundo. |
| Nome da gestora | Nome da gestora do fundo. |
| CNPJ da gestora | CNPJ da gestora do fundo. |
| Patrimônio bruto (R$) | Soma do patrimônio bruto de todas as séries de emissão. |
| Patrimônio líquido (R$) | Soma do patrimônio líquido de todas as séries de emissão. É o denominador da coluna `% do PL` em todas as seções. |
| Número de cotas | Soma das cotas de todas as séries de emissão. |

### `SÉRIES DE EMISSÃO`

| Coluna | Descrição |
|--------|-----------|
| Nome | Nome da série de emissão. |
| Patrimônio bruto (R$) | Patrimônio bruto da série, antes da provisão de taxa de performance. |
| Cota bruta (R$) | Valor da cota bruta da série. |
| Patrimônio líquido (R$) | Patrimônio líquido da série. |
| Cota líquida (R$) | Valor da cota líquida da série. |
| Número de cotas | Quantidade de cotas da série. |

### `TÍTULOS PÚBLICOS`

Uma linha por título público em estoque (LFT, LTN, NTN-B e suas versões compromissadas).

| Coluna | Descrição |
|--------|-----------|
| Data de referência | Data da composição. |
| Identificador / Código SELIC | Código SELIC do título. |
| Tipo do ativo | `LFT`, `LTN`, `NTN-B`, `LFT COMPROMISSADA`, etc. |
| Emissor | `Tesouro Nacional`. |
| Tipo de amortização | `No vencimento` ou `Juros semestrais`. |
| Data de emissão / Data de compra / Data de vencimento | Datas do título e da aquisição. |
| Unidades compradas / Unidades atuais | Quantidade de títulos adquirida e em estoque. |
| PU de compra (R$) / PU D0 (R$) | Preço unitário de aquisição e preço unitário na data de referência. |
| Valor de compra (R$) / Valor D0 (R$) | Valor financeiro de aquisição e valor na data de referência. |
| % de Tesouros | Participação do título no total de títulos públicos. |
| % do PL | Participação do título no patrimônio líquido do fundo. |

### `EMISSÕES`

Uma linha por título privado ofertado (debênture, CRI, CRA, CDB, letra financeira). Notas comerciais são apresentadas em seção própria, com colunas equivalentes, em ordem própria.

| Coluna | Descrição |
|--------|-----------|
| Data de referência | Data da composição. |
| Identificador | Código externo do papel. |
| Tipo do ativo | `DEBENTURE`, `CRI`, `CRA`, `CDB`, `Letra Financeira`, `NOTA COMERCIAL`. |
| Código ISIN / Código B3 | Códigos de identificação do papel. |
| Emissor | Nome do emissor. |
| Data de emissão / Data de compra / Data de vencimento | Datas do papel e da aquisição. |
| Unidades compradas / Unidades atuais | Quantidade adquirida e em estoque. |
| PU de compra (R$) / PU do ativo (R$) / PU D0 (R$) | Preço unitário de aquisição, preço unitário contábil e preço unitário líquido de PDD. |
| Valor de compra (R$) / Valor do ativo (R$) / Valor D0 (R$) | Valor de aquisição, valor contábil e valor líquido de PDD. |
| PDD (R$) / PDD (%) | Provisão para devedores duvidosos, em reais (negativa) e em percentual. |
| Valor vencido (R$) / Valor não vencido (R$) | Parcela vencida e não vencida do valor contábil. |
| % de Emissões | Participação do papel no total de emissões. |
| % do PL | Participação do papel no patrimônio líquido do fundo. |

### `OPERAÇÕES DE CRÉDITO`

Operações de crédito (CCB, CCE, NCE e suas versões estruturadas). Para os tipos consolidados — `CCB`, `CCE`, `NCE` — a carteira é apresentada em **uma única linha por tipo**, identificada como `CCB CONSOLIDADO`, e não operação a operação; o detalhamento ativo a ativo está no relatório [Composição de Carteira de Ativos](/documentation/iaas/relatorios_dtvm/assets_wallet_composition).

| Coluna | Descrição |
|--------|-----------|
| Data de referência | Data da composição. |
| Identificador | Número do contrato da operação ou `{TIPO} CONSOLIDADO` nas linhas consolidadas. |
| Tipo do ativo | `CCB`, `CCB ESTRUTURADA`, `CCE`, `NCE ESTRUTURADA`, etc. |
| Código IF | Código do papel na B3, quando registrado. |
| Data de emissão / Data de compra / Data de vencimento | Datas do contrato e da aquisição. Vazias nas linhas consolidadas. |
| Unidades atuais | Quantidade de operações em estoque. |
| PU de compra (R$) / PU em acruo (R$) / PU D0 (R$) | Preços unitários. Vazios nas linhas consolidadas. |
| Valor D0 (R$) | Valor da posição líquido de PDD. |
| PDD (R$) / PDD (%) | Provisão para devedores duvidosos. |
| Valor do ativo (R$) | Valor contábil da posição. |
| Valor vencido (R$) / Valor em acruo (R$) | Parcela vencida e parcela em acruo do valor contábil. |
| Ágio restante (R$) | Ágio ainda não diferido (valor justo menos valor contábil). |
| Juros pós-vencimento (R$) / Juros de mora (R$) / Multa por atraso (R$) | Encargos por atraso. **Estas três colunas só aparecem quando há algum encargo de atraso na carteira de CCB.** |
| % de Operações de Crédito | Participação da linha no total de operações de crédito. |
| % do PL | Participação da linha no patrimônio líquido do fundo. |

### `DC DESCONTADOS`

Direitos creditórios descontados (duplicatas mercantis e de serviços, CT-e, contratos descontados). Sempre apresentados de forma consolidada, uma linha por tipo.

| Coluna | Descrição |
|--------|-----------|
| Data de referência | Data da composição. |
| Identificador | `{TIPO} CONSOLIDADO`. |
| Tipo do ativo | `DUPLICATA MERCANTIL`, `DUPLICATA SERVIÇOS`, `CTE`, `CONTRATO`. |
| Valor D0 (R$) | Valor da posição líquido de PDD. |
| Valor do ativo (R$) | Valor contábil da posição. |
| Valor vencido (R$) / Valor em acruo (R$) | Parcela vencida e parcela em acruo do valor contábil. |
| PDD (R$) | Provisão para devedores duvidosos (negativa). |
| % de Direitos Creditórios Descontados | Participação da linha no total de direitos creditórios descontados. |
| % do PL | Participação da linha no patrimônio líquido do fundo. |

### `COTAS DE FUNDOS`

| Coluna | Descrição |
|--------|-----------|
| Data de referência | Data da composição. |
| Tipo do ativo | `FIDC`, `RENDA FIXA`, `MULTIMERCADO`, `FIA`, `FIP`, `FII`. |
| Nome do Fundo / Documento do Fundo | Nome e CNPJ do fundo investido. |
| Senioridade | `SÊNIOR`, `MEZANINO` ou `SUBORDINADA`. |
| Código Interno | Código interno da classe investida. |
| Data de compra | Sempre vazia nesta seção. |
| Valor de compra (R$) / Unidades compradas / PU de compra (R$) | Dados da aquisição. |
| Unidades atuais / Valor D0 (R$) / PU D0 (R$) | Posição na data de referência. |
| % de Cotas | Participação da linha no total de cotas de fundos. |
| % do PL | Participação da linha no patrimônio líquido do fundo. |

### `SWAP` e `IMÓVEIS`

Apresentadas apenas para fundos que possuem esses ativos. `SWAP` traz contraparte, valores nominais e valores atualizados de ativo e passivo; `IMÓVEIS` traz número de matrícula, valor e data de avaliação e a próxima avaliação prevista.

### `VALORES A PAGAR`

| Coluna | Descrição |
|--------|-----------|
| Data de referência | Data da composição. |
| Tipo de a pagar | Descrição da despesa (ex: `TAXA DE ADMINISTRAÇÃO`). |
| Total provisionado | Valor total provisionado da despesa. |
| Valor reconhecido | Valor já reconhecido no resultado, apresentado como negativo. |
| Valor restante | Diferença entre o total provisionado e o valor reconhecido. |
| Inicio da provisão / Fim da provisão / Data do pagamento | Datas da provisão e do pagamento previsto. |
| % do PL | Participação do valor reconhecido no patrimônio líquido (negativa). |

### `VALORES A RECEBER`

Mesma estrutura da seção anterior, com as colunas `Total a diferir`, `Valor diferido`, `Valor restante`, `Inicio do diferimento` e `Fim do diferimento`.

### `CONTAS CAIXA`

| Coluna | Descrição |
|--------|-----------|
| Data de referência | Data da composição. |
| Nome da conta | Instituição financeira e identificação contábil da conta. |
| Dados da conta | Agência e conta no formato `Ag.: {agência} \| Cc.: {conta}-{dígito}`. |
| Entrada a conciliar / Saída a conciliar | Valores creditados ou debitados ainda não conciliados. |
| Saldo | Saldo da conta na data de referência. |
| % do PL | Participação do saldo no patrimônio líquido do fundo. |

### `RENTABILIDADE`

Um bloco por série de emissão, com uma linha por janela de apuração.

| Coluna | Descrição |
|--------|-----------|
| Tipo | `Diária`, `Mensal`, `Anual` ou `D-N` (janela de N dias corridos). |
| Data de Referência | Data inicial da janela de apuração. |
| Cota de Referência | Valor da cota na data inicial da janela. |
| Cota Benchmark | Valor da cota do benchmark (DI) na data inicial da janela. |
| Cota Atual | Valor da cota líquida na data da composição. |
| Rendimento Total | Rentabilidade da cota na janela, em percentual. |
| Rendimento (%CDI) | Rentabilidade como percentual do CDI. `-` quando não há benchmark na janela. |
| Rendimento (CDI+) | Rentabilidade expressa como CDI mais spread anualizado (252 dias úteis). `-` quando o resultado é negativo ou não há benchmark. |

## Aba `P&L`

Compara os saldos das contas de resultado (grupos contábeis `07` — receitas — e `08` — despesas) entre o dia útil anterior e a data de referência.

### `RESUMIDO`

| Coluna | Descrição |
|--------|-----------|
| Data de Referência | Data da composição. |
| Tipo | `Receitas`, `Despesas` ou `Resultado`. A classificação usa o **sinal do saldo final** de cada conta, não o grupo do plano de contas: uma conta de receita com saldo negativo entra em `Despesas`. |
| Valor (R$) | Variação do dia. `Resultado` é a soma de receitas e despesas. |

### `DETALHES`

| Coluna | Descrição |
|--------|-----------|
| Nome da Conta | Nome da conta contábil de resultado. |
| Data Inicial / Valor Inicial (R$) | Dia útil anterior e saldo da conta nessa data. |
| Data Final / Valor Final (R$) | Data de referência e saldo da conta nessa data. |
| Resultado (R$) | Variação do saldo no dia. |
| Variação (%) | Variação percentual em relação ao saldo inicial. |

Somente contas com variação no dia aparecem na seção.

---

# Webhook de Entrega

URL: /documentation/iaas/relatorios_dtvm/webhook_de_entrega

## Visão Geral

Sempre que uma entrega de relatórios é concluída, a QI CTVM pode notificar a sua aplicação por webhook. A notificação diz **qual entrega terminou, para qual destino, e quais arquivos ela levou** — com o status de cada relatório. É o sinal para você disparar a coleta no SFTP em vez de varrer a pasta em intervalos fixos.

O webhook é **opcional** e configurado por rotina de entrega. Sem configuração, nenhuma notificação é enviada.

:::info Como habilitar
Informe ao time de integração a URL que vai receber as notificações. Devolvemos uma *Signature Key* para você validar a assinatura, e vinculamos a configuração à rotina de entrega do fundo. A habilitação é por rotina — um fundo com duas rotinas configura as duas.
:::

## Quando é enviado

Uma notificação por **destino concluído**, no momento em que aquele destino termina de ser processado.

Um destino só é processado depois que **todos** os relatórios da entrega chegam a um estado final — `generated` ou `failed`. Só então os arquivos são transferidos e a notificação sai. Ou seja: quando o webhook chega, a pasta já tem os arquivos.

| Situação | Status do destino | Webhook |
|----------|-------------------|---------|
| Todos os relatórios gerados | `delivered` | enviado |
| Parte dos relatórios falhou | `delivered` | enviado — os que falharam aparecem em `reports`, mas **não têm arquivo** na pasta |
| Todos os relatórios falharam | `failed` | enviado — nenhum arquivo é transferido |

:::warning É um webhook por destino, não por arquivo
Uma rotina que entrega oito relatórios em uma pasta SFTP gera **uma** notificação, com oito entradas em `reports`. Não há uma notificação por arquivo.

Se a mesma entrega tem dois destinos — por exemplo uma pasta SFTP e um e-mail — são **duas** notificações, uma por destino, e as duas trazem a mesma lista de `reports`.
:::

:::info Cada destino é notificado uma única vez
A notificação de um destino é registrada quando é enviada e não se repete. Um reprocessamento do envio não gera notificação nova. Para reenviar uma notificação já emitida, veja [Recebimento de Webhooks](/documentation/iaas/introducao/autenticacao_webhooks).
:::

## Tipos de webhook

| `webhook_type` | Quando |
|----------------|--------|
| `report.recurring_delivery_destination_completed` | Entrega originada de uma **rotina** — o caso da entrega diária de relatórios do fundo. |
| `report.delivery_destination_completed` | Entrega **avulsa**, criada fora da rotina. |

A diferença de payload está em `data`: o tipo de rotina acrescenta `recurring_delivery_key` e `description`.

## Estrutura do webhook

```json title="Webhook Body — rotina, destino SFTP"
{
    "webhook_type": "report.recurring_delivery_destination_completed",
    "webhook_datetime": "2026-07-30T09:12:44Z",
    "data": {
        "solicitation_time": "2026-07-30T09:05:00Z",
        "delivery_key": "3f1c9b7e-0a44-4c21-9f18-6b2d5e7a1c33",
        "recurring_delivery_key": "b8d2a6f4-77c1-4e90-8a3b-1d5f9c0e2a77",
        "description": "Relatórios diários — FUNDO EXEMPLO FIDC",
        "destination": {
            "destination_key": "c4e7a1b9-2d63-4f85-90ab-7c1e3f5d8b02",
            "destination_type": "sftp",
            "folder_path": "/fundos/fundo_exemplo",
            "status": "delivered"
        },
        "reports": [
            {
                "report_type": "consolidated_credit_rights_acquisition_assets",
                "file_name": "example_name_consolidated_credit_rights_acquisition_assets_2026-07-29.csv",
                "fund_class_key": "5dac941c-c779-4049-a4ee-7cee583b6860",
                "reference_date": "2026-07-29",
                "status": "generated"
            },
            {
                "report_type": "cash_account_demonstrative",
                "file_name": "example_name_cash_account_demonstrative_2026-07-29.xlsx",
                "fund_class_key": "5dac941c-c779-4049-a4ee-7cee583b6860",
                "reference_date": "2026-07-29",
                "status": "generated"
            }
        ]
    }
}
```

### Atributos de `data`

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `solicitation_time` | string | Data e hora em que a entrega foi solicitada, em ISO 8601 (UTC). |
| `delivery_key` | string | Identificador da entrega (UUID). Único por execução da rotina. |
| `recurring_delivery_key` | string | Identificador da rotina. **Presente apenas** em `report.recurring_delivery_destination_completed` — é estável entre execuções e serve para identificar de qual rotina veio a entrega. |
| `description` | string | Descrição cadastrada na rotina. **Presente apenas** em `report.recurring_delivery_destination_completed`. |
| `destination` | object | Destino concluído. Veja **[Atributos de `destination`](#atributos-de-destination)**. |
| `reports` | array | Relatórios da entrega. Veja **[Atributos de `reports`](#atributos-de-reports)**. |

### Atributos de `destination`

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `destination_key` | string | Identificador do destino (UUID). É a chave desta notificação: um `destination_key` é notificado uma única vez. |
| `destination_type` | string (enum) | `sftp` ou `email`. |
| `status` | string (enum) | `delivered` ou `failed`. Veja a tabela de [quando é enviado](#quando-é-enviado). |
| `folder_path` | string | Pasta de destino no SFTP. **Presente apenas** quando `destination_type` é `sftp`. |
| `recipients` | array | Destinatários do e-mail. **Presente apenas** quando `destination_type` é `email`. |
| `title` | string | Assunto do e-mail. **Presente apenas** quando `destination_type` é `email`. |

Os arquivos são gravados em `folder_path` com exatamente o `file_name` de cada relatório — o caminho completo é `{folder_path}/{file_name}`.

### Atributos de `reports`

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `report_type` | string (enum) | Modelo do relatório, conforme a coluna "Modelo" da [lista de relatórios disponíveis](/documentation/iaas/relatorios_dtvm/). |
| `file_name` | string | Nome do arquivo entregue, já com o prefixo do fundo e a data. |
| `fund_class_key` | string | Classe de fundo do relatório. |
| `reference_date` | string | Data de referência, em `AAAA-MM-DD`. **Pode vir nulo** nos relatórios gerados por intervalo (`quota_mec`, `balance_report`, `accounting_ledger`), que são parametrizados por `start_date` e `end_date` em vez de uma data única — trate o campo como opcional e use `file_name` para identificar o arquivo. |
| `status` | string (enum) | `generated` ou `failed`. |

:::danger Confira o `status` de cada relatório
Um webhook recebido **não** significa que todos os arquivos estão na pasta. Relatórios com `status: "failed"` aparecem na lista e não têm arquivo correspondente.

Um leitor que itere `reports` e tente baixar tudo vai falhar no primeiro relatório com erro. Filtre por `status == "generated"` antes de montar a lista de arquivos a coletar, e trate a presença de `failed` como alerta operacional — não como ausência de entrega.
:::

## Autenticação e reenvio

A validação da assinatura, a lista de IPs de origem, a política de tentativas e o reenvio são iguais aos dos demais webhooks da QI CTVM — veja **[Recebimento de Webhooks](/documentation/iaas/introducao/autenticacao_webhooks)**.

## Onde não há webhook

Duas entregas de relatório **não** emitem esta notificação:

- **Relatórios de cessão** — o [Lastros da Cessão](/documentation/iaas/relatorios_dtvm/assignment_documents) e a [Composição de Ativos da Cessão](/documentation/iaas/relatorios_dtvm/assignment_assets_wallet_composition) são gerados na etapa de aprovação da cessão, e não na rotina do fundo. Para esses dois, o acompanhamento é pelo [webhook de status do lote de cessão](/documentation/iaas/negociacao_recebiveis/assignment/webhooks) e pela coleta na pasta.
- **Download sob demanda da carteira** — a rota de [Baixar a Carteira](/documentation/iaas/composicao_carteira/baixar_carteira) é síncrona e devolve o arquivo na própria resposta, em base64. Não passa por entrega, destino, nem webhook.

:::caution Atenção ao lastro da cessão
O `assignment_documents` é justamente o relatório em que o aviso de chegada faria mais diferença, porque os links de download dentro dele expiram em 5 dias contados da **geração**. Como ele não emite webhook, a orientação de coleta continua sendo a do roteiro de [Testando a Captura de Lastro](/documentation/iaas/relatorios_dtvm/testar_captura_lastro).
:::

---

# XML ANBIMA (tipos 5 e 401)

URL: /documentation/iaas/relatorios_dtvm/xml_anbima

## Visão Geral

A QI CTVM gera os arquivos de posição de carteira no padrão ANBIMA a partir da composição de carteira do fundo. São dois modelos, entregues como arquivos independentes:

| Modelo | Padrão | Descrição |
|--------|--------|-----------|
| `xml_5_by_composition` | Arquivo de Posição ANBIMA 5.0 (ISO 20022, `semt.003.001.04`) | Posição da carteira em estrutura ISO 20022, com identificação de administrador, gestor e custodiante, posição por ativo, valores a pagar e a receber. |
| `xml_401_by_composition` | Arquivo de Posição ANBIMA 4.01 | Posição da carteira no layout 4.01, com cabeçalho do fundo e blocos por classe de ativo. |

:::info Qual é o "XML da ANBIMA"
Quando se fala do XML da ANBIMA no dia a dia, o arquivo em questão é o **`xml_5_by_composition`** — a versão 5.0 do arquivo de posição. O `xml_401_by_composition` é a versão anterior do mesmo padrão, ainda exigida por alguns consumidores.
:::

## O que você precisa informar

| Variável | Obrigatória | Descrição |
|----------|-------------|-----------|
| `fund_class_key` | sim | Identificador da classe de fundo sobre a qual o arquivo é gerado. |
| `reference_date` | sim | Data de referência da posição, no formato `AAAA-MM-DD`. |
| `type_fund_code_anbima` | não | Código do tipo de fundo na tabela da ANBIMA. Quando omitido, é derivado do cadastro do fundo. Um código fora da lista de válidos faz a geração falhar. |
| `issuance_serie_key` | não (só XML 401) | Restringe o arquivo a uma única série de emissão. Sem ele, todas as séries da classe entram no arquivo. |

## Estrutura do Arquivo

| Atributo | Valor |
|----------|-------|
| Formato | XML |
| Encoding | UTF-8 |
| Nomenclatura | `{nome_resumido_fundo}_xml_5_by_composition_{AAAA-MM-DD}.xml` e `{nome_resumido_fundo}_xml_401_by_composition_{AAAA-MM-DD}.xml` |

Ambos os arquivos são gerados a partir de uma **composição de carteira** já fechada na data de referência — confirmada ou aguardando confirmação. Antes de montar o arquivo, o serviço reconcilia a posição: a soma dos ativos, mais os valores a receber, menos os valores a pagar, tem que fechar com o patrimônio líquido informado pelas séries de emissão. Quando não fecha, o arquivo não é gerado.

## Como receber

Há duas formas, que podem ser usadas em conjunto:

1. **Na rotina de entrega do fundo**, junto com os demais relatórios — veja [como os relatórios são entregues](/documentation/iaas/relatorios_dtvm/). Basta solicitar ao time de integração a inclusão dos modelos `xml_5_by_composition` e/ou `xml_401_by_composition` na configuração da entrega.
2. **Sob demanda, pela API**, com a rota de download de relatório da composição:

ENDPOINT /composition/fund_class/{fund_class_key}/report
MÉTODO POST

```json title="Request Body"
{
    "composition_type": "final_quota",
    "report_type": "xml_5_by_composition",
    "reference_date": "2026-07-29"
}
```

A resposta devolve o arquivo em base64, no campo `document_b64`. A carteira precisa estar no status **confirmed** para o download ser possível. Detalhes em [Carteira - Baixar a Carteira](/documentation/iaas/composicao_carteira/baixar_carteira).

## Conteúdo do arquivo tipo 5

O arquivo tem o elemento raiz `PosicaoAtivosCarteira` e é dividido em duas partes:

- **`AppHdr`** — cabeçalho da mensagem: administrador remetente (nome e CNPJ), fundo destinatário, identificador da mensagem, versão do layout (`semt.003.001.04`), serviço (`Arquivo de Posicao 5.0`) e data/hora de geração.
- **`Document / SctiesBalAcctgRpt`** — corpo da posição:

| Elemento | Conteúdo |
|----------|----------|
| `Pgntn` | Paginação do arquivo. |
| `StmtGnlDtls` | Dados gerais do extrato: data da composição, frequência e tipo de atualização. |
| `AcctOwnr` | CNPJ do administrador (titular da conta). |
| `AcctSvcr` | CNPJ da gestora. |
| `SfkpgAcct` | CNPJ e nome do custodiante. |
| `BalForAcct` | Classe de fundo e séries de emissão, com ISIN, quantidade de cotas, valor da cota, valor total dos ativos, e o detalhamento de valores a pagar (`PAYA`) e a receber (`RECE`). |
| `SubAcctDtls` | Uma entrada por ativo da carteira: títulos públicos, títulos privados, debêntures, cotas de fundo, direitos creditórios, swaps, imóveis e contas caixa. |
| `AcctBaseCcyTtlAmts` | Patrimônio líquido total do fundo. |

Os valores a pagar são classificados com os códigos ISO correspondentes à natureza da despesa — `ADMF` (taxa de administração), `MANF` (gestão), `PERF` (performance), `CETI` (CETIP), `REGF` (CVM), `ANBI` (ANBIMA), `AUDT` (auditoria), `SELC` (SELIC), `CUST` (custódia), `LEGA` (serviços) — ou `OTHR` para os demais.

## Conteúdo do arquivo tipo 401

O arquivo tem o elemento raiz `arquivoposicao_4_01`, com um elemento `fundo` que reúne:

| Bloco | Conteúdo |
|-------|----------|
| `header` | ISIN, CNPJ e nome do fundo, data da posição, administrador, gestor e custodiante, valor e quantidade de cotas, patrimônio líquido, valor dos ativos, valores a receber e a pagar, tipo de fundo ANBIMA. |
| `titpublico` | Um bloco por título público, com código SELIC, datas, quantidades, PUs, indexador e valor financeiro. |
| `titprivado` | Um bloco por título privado que não seja debênture. |
| `debenture` | Um bloco por debênture. |
| `swap` | Um bloco por contrato de swap, com valores de ativo e passivo. |
| `cotas` | Um bloco por cota de fundo investida, com ISIN, CNPJ do fundo, quantidade e PU. |
| `caixa` | Saldo das contas caixa. |
| `despesas` | Taxas de administração e performance do fundo. |
| `outrasdespesas` | Demais despesas provisionadas. |
| `provisao` | Provisões constituídas, com data e valor. |
| `fidc` | Valor financeiro total dos direitos creditórios da carteira. |

Blocos sem posição na data não são incluídos no arquivo.

---

# Criação de um ativo a ser recomprado/vendido

URL: /documentation/iaas/venda_ativos/asset/criacao_recompra

---

### Request

ENDPOINT /trade_resolve/fund_class/FUND_CLASS_KEY/assignment/EXTERNAL_ID/asset
MÉTODO POST

```json title='Request Body'
{
	"external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
        "sale_value": 1234.56
}
```

:::info 
O external_id informado na payload deve corresponder ao external_id de um ativo que está presente na carteira do fundo.
:::

#### Body Params

| Campo | Tipo | Descrição | Caracteres |
|-|-|-|-|
| `external_id` * | string | Chave única de identificação do ativo a ser recomprado/vendido informada pelo parceiro. | Até 50 |
| `sale_value` *| float | Valor pelo qual o ativo será baixado | 2 casas decimais |

### Response

STATUS 201

```json title='Response Body'
{
    "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "status": "pending_assets_insertion",
}
```

---

# Aprovação do Gestor

URL: /documentation/iaas/venda_ativos/assignment/aprovacao_recompra

:::info Aos Gestores
É importante mencionar que essa rota está disponível somente para Gestores. Caso ele não seja integrado, pode-se realizar esta ação via Portal.
:::

### Request

ENDPOINT /trade_resolve/fund_class/FUND_CLASS_KEY/assignment/EXTERNAL_ID
MÉTODO PUT

```json title='Request Body'
{
	"assignment_status": "approved"
}
```

#### Enumeradores Assignment Status
| Enumerador   | Descrição     |
|--------------|---------------|
| **approved**   | Para aprovar o Lote |
| **reproved**  | Para reprovar o Lote  |

### Response

STATUS 201

```json title='Response Body'
{
    "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "status": "approved",
}
```

---

# Criação de um lote de recompra

URL: /documentation/iaas/venda_ativos/assignment/criacao_recompra

---

### Request

ENDPOINT /trade_resolve/fund_class/FUND_CLASS_KEY/assignment
MÉTODO POST

```json title='Request Body'
{
    "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
    "assignment_date": "2024-04-01",
    "assignment_configuration_key": "d9308a2b-21fa-4724-9bbe-59ae65287b10",
    "source_account":{
        "document_number": "95.031.521/0001-12"
    }
}
```

#### Body Params

| Campo | Tipo | Descrição | Caracteres |
|-|-|-|-|
| `external_id` * | string | Chave única de identificação deste lote no sistema do parceiro integrador. | Até 50 |
| `assignment_date` *| string | Data da recompra | YYYY-MM-DD |
| `assignment_configuration_key` *| string | Chave única fornecida pela CTVM | 36 |
| `source_account` *| objeto | Objeto da conta que irá realizar o pagamento ao fundo | - |

### Objeto de source account

| Campo | Tipo | Descrição | Caracteres |
|-|-|-|-|
| `document_number` * | string | Número do documento da conta que irá realizar o pagamento ao fundo. | Até 18 |

### Response

STATUS 201

```json title='Response Body'
{
    "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "status": "pending_assets_insertion",
}
```

---

# Encerrar Inserção de Ativos

URL: /documentation/iaas/venda_ativos/assignment/fechamento_recompra

### Request

ENDPOINT /trade_resolve/fund_class/FUND_CLASS_KEY/assignment/EXTERNAL_ID
MÉTODO PUT

```json title='Request Body'
{
	"assignment_status": "completed_assets_insertion"
}
```

### Response

STATUS 201

```json title='Response Body'
{
    "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "status": "completed_assets_insertion",
}
```

---

# Recompra e Venda de Ativos

URL: /documentation/iaas/venda_ativos/inicio

Esta seção documenta as APIs que viabilizam a **venda e a recompra de direitos creditórios** já encarteirados nos fundos administrados pela QI CTVM. O fluxo abrange desde a criação do lote até a baixa dos ativos da carteira do fundo.

:::tip Contexto
Este serviço apenas **baixa os ativos da carteira** do fundo. Ele não envia dados para outras administradoras.

Existem dois conceitos fundamentais: o **lote** (`assignment`) e o **ativo** (`asset`). Um lote é composto por um ou mais ativos, e cada ativo inserido precisa já estar na carteira do fundo.
:::

:::info Pré-requisitos
- Para ter acesso a esses serviços, entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) para liberação dos ambientes de Homologação (Sandbox) e Produção.
- Você precisará da `fund_class_key` (chave do fundo), que compõe a URL base de todos os endpoints desta API, e da `assignment_configuration_key` (chave da configuração), informada na criação do lote:

```
/trade_resolve/fund_class/{fund_class_key}
```
:::

## Fluxo de venda/recompra

O diagrama abaixo mostra o caminho principal, as bifurcações e o status resultante de cada etapa. Passe o mouse em um nó para ver o endpoint e clique para abrir a documentação.

<FlowDiagram
  columns={3}
  nodes={[
    { id: 'criacao', row: 1, col: 2, actor: 'you', num: 1,
      title: 'Criação do Lote',
      status: 'pending_assets_insertion',
      desc: 'Informe um external_id único, a data da operação e a conta que fará o pagamento ao fundo.',
      endpoint: { method: 'POST', path: '/trade_resolve/fund_class/{fund_class_key}/assignment' },
      href: '/documentation/iaas/venda_ativos/assignment/criacao_recompra' },

    { id: 'ativos', row: 2, col: 2, actor: 'you', num: 2,
      title: 'Inserção dos Ativos',
      status: 'ativo: pending_wallet_sale',
      desc: 'Uma requisição por ativo, identificado pelo mesmo external_id com que foi encarteirado. O ativo precisa estar ativo na carteira.',
      endpoint: { method: 'POST', path: '.../assignment/{external_id}/asset' },
      href: '/documentation/iaas/venda_ativos/asset/criacao_recompra' },

    { id: 'validacao', row: 2, col: 3, actor: 'you', tag: 'Condicional',
      title: 'Confirmação do preço',
      status: 'ativo: pending_validation',
      desc: 'Quando o preço de venda diverge mais de 5% do valor justo contábil, o ativo fica retido e exige confirmação explícita. Endpoint ainda não documentado — alinhe com integracao.dtvm@qitech.com.br.' },

    { id: 'encerramento', row: 3, col: 2, actor: 'you', num: 3,
      title: 'Encerramento do Lote',
      desc: 'É necessário ter ao menos um ativo não descartado. Você pode enviar number_of_assets e total_value para a API conferir os totais.',
      endpoint: { method: 'PUT', path: '.../assignment/{external_id}' },
      href: '/documentation/iaas/venda_ativos/assignment/fechamento_recompra' },

    { id: 'descartado', row: 4, col: 1, actor: 'you', tone: 'end',
      title: 'Lote descartado',
      status: 'discarded',
      desc: 'O descarte está disponível até o encerramento. Depois que o termo entra em circulação, o lote não pode mais ser descartado.' },

    { id: 'termo', row: 4, col: 2, actor: 'qitech',
      title: 'Termo de Recompra',
      status: 'pending_signed_term_submission',
      desc: 'Termo interno: a QI Tech gera o documento e coleta as assinaturas. Termo externo: o integrador envia o termo já assinado.' },

    { id: 'credito', row: 5, col: 2, actor: 'qitech',
      title: 'Aguardando o crédito no fundo',
      status: 'pending_payment',
      desc: 'Com o termo assinado, a QI Tech registra a expectativa de pagamento na conta do fundo.' },

    { id: 'baixa', row: 6, col: 2, actor: 'qitech', tone: 'ok',
      title: 'Ativos baixados da carteira',
      status: 'completed',
      desc: 'Confirmado o crédito, os ativos são baixados um a um. Quando todos concluem, o lote é encerrado.' },
  ]}
  edges={[
    { from: 'criacao', to: 'ativos' },
    { from: 'ativos', to: 'validacao', label: 'diverge > 5%', dashed: true },
    { from: 'validacao', to: 'encerramento', label: 'confirmado', dashed: true },
    { from: 'ativos', to: 'encerramento' },
    { from: 'encerramento', to: 'descartado', label: 'discarded', tone: 'end' },
    { from: 'encerramento', to: 'termo', label: 'encerrado', tone: 'ok' },
    { from: 'termo', to: 'credito', label: 'assinado' },
    { from: 'credito', to: 'baixa', label: 'pago' },
  ]}
/>

## Passo a passo

### 1. Criação do Lote

Crie o lote informando um identificador único (`external_id`), a data da operação e a conta que fará o pagamento ao fundo. O lote nasce em `pending_assets_insertion` e é o contêiner de todos os ativos que serão baixados.

**[Acessar documentação da criação do lote](/documentation/iaas/venda_ativos/assignment/criacao_recompra)**

### 2. Inserção dos Ativos

Insira um ativo por requisição, identificando-o pelo mesmo `external_id` com que ele foi encarteirado. O ativo precisa estar **ativo** na carteira do fundo no momento da inserção.

**[Acessar documentação da inserção de ativos](/documentation/iaas/venda_ativos/asset/criacao_recompra)**

:::caution Divergência de preço acima de 5%
Se o preço de venda informado divergir em **mais de 5%** do valor justo contábil do ativo, o ativo não segue automaticamente: ele fica em `pending_validation` e exige uma confirmação explícita do integrador antes de entrar na baixa. Divergências de até 5% seguem direto para `pending_wallet_sale`.

O endpoint de confirmação ainda não está documentado nesta seção — se o seu fluxo pode gerar divergências acima de 5%, alinhe o procedimento com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br).
:::

### 3. Encerramento do Lote

Após inserir todos os ativos, encerre o lote. É necessário ter ao menos um ativo não descartado. Opcionalmente, você pode enviar `number_of_assets` e `total_value` para que a API confira a quantidade e o valor total consolidados antes de aceitar o encerramento.

O descarte do lote está disponível **até esta etapa**: depois que o termo entra em circulação, o lote não pode mais ser descartado.

**[Acessar documentação do encerramento](/documentation/iaas/venda_ativos/assignment/fechamento_recompra)**

### 4. Termo de Recompra

O responsável pela emissão do Termo de Recompra depende da configuração do lote:

- **Termo interno** — a QI Tech gera o termo e coleta as assinaturas das partes. Nenhuma ação do integrador é necessária.
- **Termo externo** — o lote passa para `pending_signed_term_submission` e o integrador precisa enviar o termo já assinado para que o fluxo prossiga.

Em ambos os casos, com o termo assinado o lote passa a `pending_payment`, aguardando o crédito na conta do fundo.

### 5. Pagamento e Baixa dos Ativos

As etapas finais são automatizadas: a QI Tech confirma o crédito na conta do fundo, os ativos são baixados da carteira e, quando todos os ativos são concluídos, o lote é encerrado em `completed`.

---

# Recuperando Informações da Conta

URL: /documentation/iaas/visibildade_de_caixa/get_accounts

---

### Request

ENDPOINT /cash_account/fund_class/FUND_CLASS_KEY/accounts
MÉTODO GET
### Response

STATUS 200

```json title='Response Body'
{
    {
   "data":[
      {
         "account_key":"fdbe66e9-4b1d-4254-8473-523b8d3587be",
         "account_type":"checking_account",
         "financial_institution":{
            "ispb":"32402502",
            "code":"329",
            "name":"QI Sociedade de Crédito Direto"
         },
         "account_status":"open",
         "account_number":"999999",
         "account_digit":"9",
         "account_branch":"0001",
         "accounting_identification":1,
         "balance":0,
         "owner":{
            "name":"FUNDO DE INVESTIMENTO EM DIREITOS CREDITORIOS",
            "document_number":"16.958.441/0001-30"
         },
         "owner_document_number":"16.958.441/0001-30"
      },
      {
         "account_key":"e40dd24e-4341-4736-a868-f3e767dd6c31",
         "account_type":"checking_account",
         "financial_institution":{
            "ispb":"32402502",
            "code":"329",
            "name":"QI Sociedade de Crédito Direto"
         },
         "account_status":"open",
         "account_number":"77777",
         "account_digit":"7",
         "account_branch":"0001",
         "accounting_identification":2,
         "balance":0,
         "owner":{
            "name":"FUNDO DE INVESTIMENTO EM DIREITOS CREDITORIOS",
            "document_number":"16.958.441/0001-30"
         },
         "owner_document_number":"16.958.441/0001-30"
      }
   ],
   "limit":10,
   "page":0,
   "is_last_page":true
}
}
```

### Response Fields

| Campo         | Tipo   | Descrição                                              |
|---------------|--------|--------------------------------------------------------|
| `data`        | array  | Lista de objetos de **[Account](#account)**            |
| `limit`       | int    | Limite de objetos recuperados por página               |
| `page`        | int    | Número da página recuperada                            |
| `is_last_page`| boolean| Informação que indica se a página recuperada é a última|

### Account
| Campo                       | Tipo   | Descrição                                      | Caracteres |
|-----------------------------|--------|------------------------------------------------|------------|
| `account_key`               | string | Chave única identificadora da conta no sistema | 36         |
| `account_type`              | string | Tipo de conta                                  | Até 50     |
| `financial_institution`     | JSON   | Objeto de instituição financeira               | -          |
| `account_status`            | string | Status da conta                                | Até 50     |
| `account_number`            | string | Número da conta                                | Até 50     |
| `account_digit`             | string | Digito da conta                                | 1          |
| `account_branch`            | string | Agência da conta                               | Até 50     |
| `accounting_identification` | int    | Identificador ordinal da conta                 | -          |
| `balance`                   | int    | Saldo da conta no momento                      | -          |
| `owner`                     | JSON   | Objeto de proprietário                         | -          |
| `owner_document_number`     | string | Documento do proprietário                      | 14 ou 18   |

:::caution **Atenção**

O saldo é disponibilizado concatenando reais e centavos ex.: 1234 = R$ 12,34
:::
### Finacial institution
| Campo  | Tipo   | Descrição                                        | Caracteres |
|--------|--------|--------------------------------------------------|------------|
| `ispb` | string | Identificador de Sistema de Pagamentos Brasileiro| 8          |
| `code` | string | Código da instituição financeira                 | 3          |
| `name` | string | Nome da instituição financeira                   | Até 255    |

### Owner
| Campo             | Tipo   | Descrição                 | Caracteres |
|-------------------|--------|---------------------------|------------|
| `name`            | string | Nome do proprietário      | até 255    |
| `document_number` | string | Documento do proprietário | 14 ou 18   |

---

# Recuperando Transações de uma Conta

URL: /documentation/iaas/visibildade_de_caixa/get_transaction_reversals

---

### Request

ENDPOINT /cash_account/account/ACCOUNT_KEY/transactions
MÉTODO GET

### Response

STATUS 200

```json title='Response Body'
{
    "data": [
        {
            "transaction_key": "ed585534-8c05-431d-b829-0dc7883b24ba",
            "transaction_type": "outgoing_wire_transfer",
            "transaction_status": "pending_conciliation",
            "transaction_description": "Descrição do pagamento",
            "amount": -70000,
            "transaction_datetime": "2025-01-01T14:00:00Z",
            "account_balance": 500000,
            "transaction_data": {
               "counter_part_account": {
                  "owner": {
                        "name": "Nome da Contraparte",
                        "document_number": "***.805.49*-**"
                  },
                  "account_digit": "8",
                  "account_branch": "1",
                  "account_number": "1234567",
                  "financial_institution": {
                        "code": "329",
                        "ispb": "32402502"
                  }
               },
            },
            "account": {
                "account_key": "9c1d0c18-01ea-4c32-a878-1c6391f9aa44",
                "account_type": "checking_account",
                "financial_institution": {
                    "ispb": "32402502",
                    "code": "329",
                    "name": "QI Sociedade de Crédito Direto"
                },
                "account_status": "open",
                "account_number": "3289018",
                "account_digit": "7",
                "account_branch": "0001",
                "accounting_identification": 1,
                "balance": 500000,
                "owner": {
                    "name": "FUNDO TESTE",
                    "document_number": "93.625.214/0001-34"
                },
                "owner_document_number": "93.625.214/0001-34",
                "account_configuration": {
                    "pix": true,
                    "wire_transfer": true
                },
                "billings": []
            }
        },
        {
            "transaction_key": "16c9c463-266e-4e73-b87d-efc32aa6727a",
            "transaction_type": "incoming_wire_transfer",
            "transaction_status": "reconciled",
            "transaction_description": "Descrição",
            "amount": 300000,
            "transaction_datetime": "2025-06-04T13:00:00Z",
            "account_balance": 570000,
            "transaction_data": {
               "counter_part_account": {
                  "owner": {
                     "name": "FUNDO TESTE",
                     "document_number": "93.625.214/0001-34"
                  },
                  "account_digit": "8",
                  "account_branch": "73",
                  "account_number": "567567",
                  "financial_institution": {
                     "code": "341",
                     "ispb": "60701190",
                  }
               },
            },
            "account": {
                "account_key": "9c1d0c18-01ea-4c32-a878-1c6391f9aa44",
                "account_type": "checking_account",
                "financial_institution": {
                    "ispb": "32402502",
                    "code": "329",
                    "name": "QI Sociedade de Crédito Direto"
                },
                "account_status": "open",
                "account_number": "3289018",
                "account_digit": "7",
                "account_branch": "0001",
                "accounting_identification": 1,
                "balance": 500000,
                "owner": {
                    "name": "FUNDO TESTE",
                    "document_number": "93.625.214/0001-34"
                },
                "owner_document_number": "93.625.214/0001-34",
                "account_configuration": {
                    "pix": true,
                    "wire_transfer": true
                },
                "billings": []
            },
            "conciliation_group": {
                "description": "TRANSFERÊNCIA: CONTA COBRANÇA -> CONTA PRINCIPAL",
                "conciliation_group_key": "1ac2921c-6c81-481b-8472-6c4126bba4bf",
                "conciliation_group_datetime": "2025-01-01T13:28:58Z"
            }
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true
}
```

### Query Params

| Campo         | Tipo   | Descrição                  |
|---------------|--------|----------------------------|
| `status`      | string | Status da transação        |
| `start_date`  | string | Data inicial de consulta   |
| `end_date`    | string | Data final de consulta     |
| `page`        | string | Número da página recuperada|

### Response Fields

| Campo         | Tipo   | Descrição                                              |
|---------------|--------|--------------------------------------------------------|
| `data`        | array  | Lista de objetos de **[Transaction](#transaction)**    |
| `limit`       | int    | Limite de objetos recuperados por página               |
| `page`        | int    | Número da página recuperada                            |
| `is_last_page`| boolean| Informação que indica se a página recuperada é a última|

### Transaction
| Campo                       | Tipo   | Descrição                                         | Caracteres |
|-----------------------------|--------|---------------------------------------------------|------------|
| `transaction_key`           | string | Chave única identificadora da transação           | 36         |
| `transaction_type`          | string | Tipo de transação                                 | Até 50     |
| `transaction_status`        | string | status da transação                               | Até 50     |
| `transaction_description`   | string | Descrição da transação fornecida pelo banco       | Até 255    |
| `amount`                    | bigint | Valor da transação vezes 100 (ex: R$1,00 == 100)  | -          |
| `transaction_datetime`      | string | Data e hora da transação                          | ISO 8601   |
| `account_balance`           | bigint | Saldo da conta após a transação                   | -          |
| `transaction_data`          | JSON   | Objeto com informações adicionais da transação    | -          |
| `account`                   | JSON   | Objeto da conta contendo a transação              | -          |

### Account
| Campo                       | Tipo   | Descrição                           | Caracteres |
|-----------------------------|--------|-------------------------------------|------------|
| `account_key`               | string | Chave única identificadora da conta | 36         |
| `account_type`              | string | Tipo de conta                       | Até 50     |
| `financial_institution`     | JSON   | Objeto de instituição financeira    | -          |
| `account_status`            | string | Status da conta                     | Até 50     |
| `account_number`            | string | Número da conta                     | Até 50     |
| `account_digit`             | string | Digito da conta                     | 1          |
| `account_branch`            | string | Agência da conta                    | Até 50     |
| `accounting_identification` | int    | Identificador ordinal da conta      | -          |
| `balance`                   | int    | Saldo da conta no momento           | -          |
| `owner`                     | JSON   | Objeto de proprietário              | -          |
| `owner_document_number`     | string | Documento do proprietário           | 14 ou 18   |

:::caution **Atenção**

O saldo é disponibilizado concatenando reais e centavos ex.: 1234 = R$ 12,34
:::
### Finacial institution
| Campo  | Tipo   | Descrição                                         | Caracteres |
|--------|--------|---------------------------------------------------|------------|
| `ispb` | string | Identificador de Sistema de Pagamentos Brasileiro | 8          |
| `code` | string | Código da instituição financeira                  | 3          |
| `name` | string | Nome da instituição financeira                    | Até 255    |

### Owner
| Campo             | Tipo   | Descrição                 | Caracteres |
|-------------------|--------|---------------------------|------------|
| `name`            | string | Nome do proprietário      | até 255    |
| `document_number` | string | Documento do proprietário | 14 ou 18   |

### Conciliation Group
| Campo                         | Tipo   | Descrição                                | Caracteres |
|-------------------------------|--------|------------------------------------------|------------|
| `description`                 | string | Descrição da conciliação da transação    | Até 255    |
| `conciliation_group_key`      | string | Chave única identificadora da conciliação| 36         |
| `conciliation_group_datetime` | string | data e horário da conciliação            | ISO 8601   |

---

# Recuperando Transações de uma Conta

URL: /documentation/iaas/visibildade_de_caixa/get_transactions

---

### Request

ENDPOINT /cash_account/account/ACCOUNT_KEY/transactions
MÉTODO GET

### Response

STATUS 200

```json title='Response Body'
{
    "data": [
        {
            "transaction_key": "ed585534-8c05-431d-b829-0dc7883b24ba",
            "transaction_type": "outgoing_wire_transfer",
            "transaction_status": "pending_conciliation",
            "transaction_description": "Descrição do pagamento",
            "amount": -70000,
            "transaction_datetime": "2025-01-01T14:00:00Z",
            "account_balance": 500000,
            "transaction_data": {
               "counter_part_account": {
                  "owner": {
                        "name": "Nome da Contraparte",
                        "document_number": "***.805.49*-**"
                  },
                  "account_digit": "8",
                  "account_branch": "1",
                  "account_number": "1234567",
                  "financial_institution": {
                        "code": "329",
                        "ispb": "32402502"
                  }
               },
            },
            "account": {
                "account_key": "9c1d0c18-01ea-4c32-a878-1c6391f9aa44",
                "account_type": "checking_account",
                "financial_institution": {
                    "ispb": "32402502",
                    "code": "329",
                    "name": "QI Sociedade de Crédito Direto"
                },
                "account_status": "open",
                "account_number": "3289018",
                "account_digit": "7",
                "account_branch": "0001",
                "accounting_identification": 1,
                "balance": 500000,
                "owner": {
                    "name": "FUNDO TESTE",
                    "document_number": "93.625.214/0001-34"
                },
                "owner_document_number": "93.625.214/0001-34",
                "account_configuration": {
                    "pix": true,
                    "wire_transfer": true
                },
                "billings": []
            }
        },
        {
            "transaction_key": "16c9c463-266e-4e73-b87d-efc32aa6727a",
            "transaction_type": "incoming_wire_transfer",
            "transaction_status": "reconciled",
            "transaction_description": "Descrição",
            "amount": 300000,
            "transaction_datetime": "2025-06-04T13:00:00Z",
            "account_balance": 570000,
            "transaction_data": {
               "counter_part_account": {
                  "owner": {
                     "name": "FUNDO TESTE",
                     "document_number": "93.625.214/0001-34"
                  },
                  "account_digit": "8",
                  "account_branch": "73",
                  "account_number": "567567",
                  "financial_institution": {
                     "code": "341",
                     "ispb": "60701190",
                  }
               },
            },
            "account": {
                "account_key": "9c1d0c18-01ea-4c32-a878-1c6391f9aa44",
                "account_type": "checking_account",
                "financial_institution": {
                    "ispb": "32402502",
                    "code": "329",
                    "name": "QI Sociedade de Crédito Direto"
                },
                "account_status": "open",
                "account_number": "3289018",
                "account_digit": "7",
                "account_branch": "0001",
                "accounting_identification": 1,
                "balance": 500000,
                "owner": {
                    "name": "FUNDO TESTE",
                    "document_number": "93.625.214/0001-34"
                },
                "owner_document_number": "93.625.214/0001-34",
                "account_configuration": {
                    "pix": true,
                    "wire_transfer": true
                },
                "billings": []
            },
            "conciliation_group": {
                "description": "TRANSFERÊNCIA: CONTA COBRANÇA -> CONTA PRINCIPAL",
                "conciliation_group_key": "1ac2921c-6c81-481b-8472-6c4126bba4bf",
                "conciliation_group_datetime": "2025-01-01T13:28:58Z"
            }
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true
}
```

### Query Params

| Campo         | Tipo   | Descrição                  |
|---------------|--------|----------------------------|
| `status`      | string | Status da transação        |
| `start_date`  | string | Data inicial de consulta   |
| `end_date`    | string | Data final de consulta     |
| `page`        | string | Número da página recuperada|

### Response Fields

| Campo         | Tipo   | Descrição                                              |
|---------------|--------|--------------------------------------------------------|
| `data`        | array  | Lista de objetos de **[Transaction](#transaction)**    |
| `limit`       | int    | Limite de objetos recuperados por página               |
| `page`        | int    | Número da página recuperada                            |
| `is_last_page`| boolean| Informação que indica se a página recuperada é a última|

### Transaction
| Campo                       | Tipo   | Descrição                                         | Caracteres |
|-----------------------------|--------|---------------------------------------------------|------------|
| `transaction_key`           | string | Chave única identificadora da transação           | 36         |
| `transaction_type`          | string | Tipo de transação                                 | Até 50     |
| `transaction_status`        | string | status da transação                               | Até 50     |
| `transaction_description`   | string | Descrição da transação fornecida pelo banco       | Até 255    |
| `amount`                    | bigint | Valor da transação vezes 100 (ex: R$1,00 == 100)  | -          |
| `transaction_datetime`      | string | Data e hora da transação                          | ISO 8601   |
| `account_balance`           | bigint | Saldo da conta após a transação                   | -          |
| `transaction_data`          | JSON   | Objeto com informações adicionais da transação    | -          |
| `account`                   | JSON   | Objeto da conta contendo a transação              | -          |

### Account
| Campo                       | Tipo   | Descrição                           | Caracteres |
|-----------------------------|--------|-------------------------------------|------------|
| `account_key`               | string | Chave única identificadora da conta | 36         |
| `account_type`              | string | Tipo de conta                       | Até 50     |
| `financial_institution`     | JSON   | Objeto de instituição financeira    | -          |
| `account_status`            | string | Status da conta                     | Até 50     |
| `account_number`            | string | Número da conta                     | Até 50     |
| `account_digit`             | string | Digito da conta                     | 1          |
| `account_branch`            | string | Agência da conta                    | Até 50     |
| `accounting_identification` | int    | Identificador ordinal da conta      | -          |
| `balance`                   | int    | Saldo da conta no momento           | -          |
| `owner`                     | JSON   | Objeto de proprietário              | -          |
| `owner_document_number`     | string | Documento do proprietário           | 14 ou 18   |

:::caution **Atenção**

O saldo é disponibilizado concatenando reais e centavos ex.: 1234 = R$ 12,34
:::
### Finacial institution
| Campo  | Tipo   | Descrição                                         | Caracteres |
|--------|--------|---------------------------------------------------|------------|
| `ispb` | string | Identificador de Sistema de Pagamentos Brasileiro | 8          |
| `code` | string | Código da instituição financeira                  | 3          |
| `name` | string | Nome da instituição financeira                    | Até 255    |

### Owner
| Campo             | Tipo   | Descrição                 | Caracteres |
|-------------------|--------|---------------------------|------------|
| `name`            | string | Nome do proprietário      | até 255    |
| `document_number` | string | Documento do proprietário | 14 ou 18   |

### Conciliation Group
| Campo                         | Tipo   | Descrição                                | Caracteres |
|-------------------------------|--------|------------------------------------------|------------|
| `description`                 | string | Descrição da conciliação da transação    | Até 255    |
| `conciliation_group_key`      | string | Chave única identificadora da conciliação| 36         |
| `conciliation_group_datetime` | string | data e horário da conciliação            | ISO 8601   |

---

# Introdução

URL: /documentation/iaas/visibildade_de_caixa/inicio

A visibilidade das movimentações de caixa é extremamente importante para a gestão de um fundo de investimento. Nesta seção iremos explicar as ferramentas disponibilizadas para consultar as informações de contas.

Para ter acesso a esses serviços, entre em contato com o time [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br), para que seja feito as devidas liberações, tanto em ambiente de Homologação (Sandbox), quanto em ambiente produtivo.

### Informações de conta
Nessa ferramenta é possível resgatar uma lista de informações das contas de um fundo, conforme descrito em: [5.7.2.1 Recuperando Informações da Conta](/documentation/iaas/visibildade_de_caixa/get_accounts).

---

# Transferência entre contas do fundo

URL: /documentation/iaas/visibildade_de_caixa/post_internal_transfer

Esse recurso permite realizar uma transferência de valores entre duas contas pertencentes ao mesmo fundo, debitando a conta de origem e creditando a conta de destino.

---

### Request

ENDPOINT /transfer/fund_class/FUND_CLASS_KEY/internal_transfer
MÉTODO POST

```json title='Request Body'
{
    "amount": 15000,
    "description": "Internal transfer",
    "origin_key": "<UUID>",
    "origin_type": "manual_transfer",
    "source_account_key": "<UUID>",
    "target_account_key": "<UUID>",
    "transfer_type": "pix"
}
```

### Response

STATUS 201

```json title='Response Body'
{
    "internal_transfer_key": "<UUID>",
    "internal_transfer_status": "created"
}
```

### Path Params

| Campo            | Tipo   | Descrição                                      |
|------------------|--------|------------------------------------------------|
| `fund_class_key` | string | Chave única identificadora do fundo na QI CTVM |

### Body Params

| Campo                 | Tipo   | Descrição                                                                                                          |
|-----------------------|--------|------------------------------------------------------------------------------------------------------------------|
| `amount`             | int    | Valor a ser transferido, em centavos (ex.: `15000` = R$ 150,00)                                                  |
| `description`        | string | Descrição da transferência                                                                                       |
| `origin_key`         | string | Chave única de idempotência da transferência (UUID v4), gerada pelo integrador a cada solicitação               |
| `origin_type`        | string | Tipo de origem da transferência. Deve ser enviado como `manual_transfer`                                          |
| `source_account_key` | string | Chave única identificadora da conta a ser debitada (origem)                                                       |
| `target_account_key` | string | Chave única identificadora da conta a ser creditada (destino)                                                     |
| `transfer_type`      | string | Tipo de transferência. Aceita `pix` ou `wire_transfer`, limitado ao que a conta de origem suporta |

:::caution **Atenção**

Para receber o resultado da transferência, é necessário a configuração do webhook de confirmação da transferência.
:::

---

# Criando Pedido de Estorno

URL: /documentation/iaas/visibildade_de_caixa/post_transaction_reversal

---

### Request

ENDPOINT /transaction_reversal/fund_class/FUND_CLASS_KEY/transaction_reversal
MÉTODO POST

### Response

STATUS 201

```json title='Response Body'
{
    "amount": 125.25,
    "description": "Estorno - transferência indevida",
    "reversal_type": "pix",
    "reference_date": "2025-01-01",
    "source_account": {
        "owner": {
            "name": "Nome do Fundo",
            "document_number": "123.805.491-24"
        },
        "account_digit": "8",
        "account_branch": "0001",
        "account_number": "1234567",
        "financial_institution": {
            "ispb": "32402502",
            "code": "329",
            "name": "QI Sociedade de Crédito Direto"
        },
    },
    "transaction_key": "4208d7d1-9077-4d00-aa4a-a4368b954867"
}
```

### Path Params

| Campo           | Tipo   | Descrição                                      | 
|-----------------|--------|------------------------------------------------|
| `fund_class_key`| string | Chave única identificadora do fundo na QI CTVM |

### Body Params

| Campo                            | Tipo                    | Descrição                                                                  |
|----------------------------------|-------------------------|----------------------------------------------------------------------------|
| `amount`*                        | float                   | Valor a ser estornado                                                      |
| `description`*                   | string                  | Descrição do estorno realizado                                             |
| `reversal_type`*                 | string                  | Tipo de estorno a ser enviado                                              |
| `reference_date`*                | string                  | Data de referência para o processamento do estorno                         |
| `source_account_key`             | int                     | Chave única identificadora da conta de origem do estorno                   |
| `source_account`                 | **[Account](#account)** | Objeto de conta de origem do estorno                                       |
| `transaction_key`*               | string                  | Chave única identificadora da transferência a estornar no sistema de caixa |
| `reference_key`                  | string                  | Chave de referencia da transferência a estornar no banco de origem         |
| `conciliation_field`             | string                  | Campo para conciliação em múltiplas expectativas                           |
| `end_to_end_id`                  | string                  | Identificador do pix a estornar                                            |
| `external_key`                   | string                  | Chave única da transação a estornar no banco de origem                     |
| `bank_slip_settlement_group_key` | string                  | Chave única da liquidação de boleto a estornar no banco de origem          |

:::caution **Atenção**

O Campos `source_account_key` e `source_account` são campos identificadores da origem do valor a ser estornado. Devem ser enviados **1 campo de cada**, caso sejam enviados múltiplos, retornará erro 400.
:::

### Account
| Campo                       | Tipo                                              | Descrição                           | Caracteres |
|-----------------------------|---------------------------------------------------|-------------------------------------|------------|
| `account_number`            | string                                            | Número da conta                     | Até 50     |
| `account_digit`             | string                                            | Digito da conta                     | 1          |
| `account_branch`            | string                                            | Agência da conta                    | Até 4      |
| `financial_institution`     | **[Financial Institution](#financial_institution)** | Objeto de instituição financeira    | -          |
| `owner`                     | **[Owner](#owner)**                               | Objeto de proprietário              | -          |

### Financial institution {#financial_institution}
| Campo  | Tipo   | Descrição                                         | Caracteres |
|--------|--------|---------------------------------------------------|------------|
| `ispb` | string | Identificador de Sistema de Pagamentos Brasileiro | 8          |
| `code` | string | Código da instituição financeira                  | 3          |
| `name` | string | Nome da instituição financeira                    | Até 255    |

### Owner
| Campo             | Tipo   | Descrição                 | Caracteres |
|-------------------|--------|---------------------------|------------|
| `name`            | string | Nome do proprietário      | até 255    |
| `document_number` | string | Documento do proprietário | 14 ou 18   |

---

# Webhooks

URL: /documentation/iaas/visibildade_de_caixa/webhook_transaction_reversal

---
#### Liquidação concluida

STATUS Settled

```json title='Webhook Body'
{
    "data":{
        "transaction_reversal_key": "b6da1a84-5bb3-4d71-9912-cbbcfe7189c1", 
        "amount": 123.45,
        "status": "paid", 
        "description": "Valor de liquidação indevido",
        "reference_date": "2025-03-23",
        "fund_class_document_number": "12.345.678/0009-10",
        "fund_class_key": "0619574f-2815-419d-8208-630b0dc30487",
        "source_account": {
            "account_digit": "7",
            "account_branch": "0001",
            "account_number": "0099999",
            "owner": {
                "name": "FUNDO DE INVESTIMENTO",
                "document_number": "12.345.678/0009-10"
            },
            "financial_institution": {
                "code": "329",
                "ispb": "32402502",
                "name": "QI Sociedade de Crédito Direto"
            },
        },
        "target_account":{
            "owner": {
                "name": "Nome fictício",
                "document_number": "111.202.188-99"
            },
            "account_digit": "0",
            "account_branch": "0001",
            "account_number": "1029490",
            "target_pix_key": "1232221",
            "financial_institution": {
                "code": "033",
                "ispb": "90400888",
                "name": "BCO SANTANDER (BRASIL) S.A."
            }
        },
        "external_key":"40054daa-c3c5-49cd-add7-858b576c5887"
    },
    "webhook_type":"transaction_reversal.transaction_reversal_status_change",
    "webhook_datetime":"2025-03-23T15:08:30Z"
}
```

---

# Introdução a Documentação

URL: /documentation/introducao_api_reference

Essa documentação tem como objetivo descrever e guiar o desenvolvedor a utilizar nossa API Rest.

## Introdução

Somos a primeira instituição financeira a criar um modelo exclusivo de Bank-as-a-Service (BaaS) do Brasil. Nosso objetivo é ajudar qualquer Fintech/Gestora de Crédito ou empresa a ter acesso a serviços financeiros rápidos, ágeis e seguros, da maneira que quiser. Saiba mais em https://qitech.com.br.

## Ambientes (Hosts)

A QI Tech possui infraestruturas completamente separadas para os ambientes SANDBOX e PRODUÇÃO, sendo que o ambiente de sandbox apresenta valores monetários totalmente fictícios, somente o ambiente de Produção realiza transações financeiras validas.

O ambiente Sandbox foi criado para os desenvolvedores realizarem suas integrações, e quando estiverem prontos para entrada em produção, atualizarem apenas as variáveis Host e Access Token com os parâmetros do ambiente de Produção.

Alem da divisão por ambientes, ainda contamos com a segregação dos HOSTs relacionados a serviços financeiros, Serviços de analise e serviços da certificadora QI Tech conforme tabela abaixo:

| Serviço | Ambiente | Host |
|-|-|-|
| BaaS e LaaS | Produção | https://api-auth.qitech.app/ |
| BaaS e LaaS | Sandbox | https://api-auth.sandbox.qitech.app/ |
| CaaS | Produção | https://api.caas.qitech.app/ |
| CaaS | Sandbox | https://api.sandbox.caas.qitech.app/ |
| CertifiQI | Produção | https://api.certifiqi.com.br/ |
| CertifiQI | Sandbox | https://api.sandbox.certifiqi.com.br/ |
| Insurance | Produção | https://api.insurance.qitech.app/ |
| Insurance | Sandbox | https://api.sandbox.insurance.qitech.app/ |

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.
:::

Os ambientes estão sempre na mesma versão, portanto quando ocorre uma atualização em Produção, a mesma atualização ocorre no ambiente Sandbox.

## Primeiros Passos

Para começar a integrar com as APIs da QI Tech, siga os passos abaixo:

1. [Criação de Perfil de Acesso](/documentation/primeiros_passos/inicio)
2. [Troca de Chaves](/documentation/primeiros_passos/troca_de_chaves)
3. [Teste de Autenticação](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2)
4. [Configuração de Webhooks](/documentation/primeiros_passos/configurando_webhooks)

## Como essa documentação esta dividida?

Após realizar os primeiros passos presentes na unidade "Primeiros Passos" já é possível consumir os micro-serviços da QI Tech em ambiente de sandbox.

Essa documentação esta dividida por produtos, são eles:

- **Banking as a Service**
- **Lending as a Service**
- **Risk Solutions**
- **Investment as a Service**
- **Insurance as a Service**

## Mensagens de Erro

:::danger Atenção!
As mensagens de erro retornadas pela QI não devem ser mapeadas de forma restrita. Campos adicionais podem ser incluídos futuramente nas mensagens de erro das nossas APIs.
:::

---

# Bem Vindo à Seção de Manuais das API's da QI Tech

URL: /documentation/introducao_manuais

Esta seção é destinada à orientação dos diferentes casos de uso das APIs da QI Tech.

## Crédito Consignado

- **[INSS](/documentation/guides/INSS/intro)** — Crédito Novo, Refinanciamento e Portabilidade para beneficiários INSS
- **[SIAPE-SIGEPE](/documentation/siape/manual_siape)** — Crédito Novo para servidores públicos federais
- **[Consignado Privado](/documentation/manual_consignado_privado/manual_detalhamento_fluxo_ativo)** — Originação via Leilão ou Ativa, consultas, emissão e averbação
- **[Previdência Privada](/documentation/manual_previdencia_privada/manual_previdencia_privada_consulta)** — Consulta, Crédito Novo e Averbação para previdência privada
- **[Saque Aniversário FGTS](/documentation/manual_FGTS/manual_fgts)** — Originação e Consulta de Autorização

## Cartões

- **[Pré-pago](/documentation/manual_pre_pago/casos_uso)** — Casos de uso do QI Cartões Pré-pago
- **[Cartão Consignado INSS](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_emissao)** — Emissão, Acompanhamento, Webhooks, Documentos e Gestão de Endereço
- **[QI Fatura](/documentation/manual_qi_fatura/pix_parcelado)** — Experiência de cartão com PIX Parcelado

## Portabilidade

- **[Port Out](/documentation/manual_portabilidade/portabilidade_out)** — Portabilidade de crédito
- **[Evidências de Retenção](/documentation/manual_portabilidade/evidencias_de_retencao)** — Evidências para retenção de portabilidade

## Outros Produtos

- **[QI Sign](/documentation/manual_qi_sign/manual_qi_sign)** — Assinatura eletrônica
- **[BNPL E-commerce](/documentation/manual_bnpl_ecommerce/manual_bnpl_ecommerce)** — Buy Now Pay Later para e-commerce
- **[Negociação de Direitos Creditórios](/documentation/iaas/negociacao_recebiveis/manual_api)** — Negociação e cessão de recebíveis
- **[Crédito Clean](/documentation/manual_credito_clean/emissao/emissao)** — Crédito Clean

## Cessão

- **[Cessão](/documentation/manual_cessao/)** — Fluxo de cessão de direitos creditórios ao cessionário

## Conciliação

- **[Conciliação](/documentation/manual_conciliacao/)** — Conciliação de portabilidade, renegociação, refinanciamento e cancelamento

---

# Bem Vindo à Seção de Manuais das API's da QI Tech

URL: /documentation/introducao_operational_guides

Esta seção é destinada à orientação dos diferentes casos de uso das APIs da QI Tech.

---

# Consulta de instituições financeiras

URL: /documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras

## Request

ENDPOINT /financial_institution
MÉTODO GET

### QUERY PARAMS

| Campo | Descrição |
|---|---|
| `ispb_number` | Número ISPB da instituição financeira. |
| `name` | Nome da instituição financeira |
| `compe_number` | Número Compe da instituição financeira. |
| `min_str_start_date` | Data mínima de início da operação. |
| `max_str_start_date` | Data máxima de início da operação. |
| `page_number` | Página atual que está sendo consultada |
| `page_size` | Quantidade de resultados por página |

## Response

status: 200

Response Body: Consulta com paginação

```json
{
  "data": [
    {
      "compe_number": "001",
      "created_at": "2019-06-19T17:31:51",
      "is_active": true,
      "is_compe_participant": true,
      "ispb_number": "00000000",
      "name": "Banco do Brasil S.A.",
      "str_start_date": "2002-04-22"
    },
    {
      "compe_number": "070",
      "created_at": "2019-06-19T17:31:51",
      "is_active": true,
      "is_compe_participant": true,
      "ispb_number": "00000208",
      "name": "Banco de Brasília S.A.",
      "str_start_date": "2002-04-22"
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": 2,
    "rows_per_page": 2,
    "total_pages": 115,
    "total_rows": 230
  }
}

```

Response Body: Consulta sem paginação

```json
{
  "94968518": {
    "compe_number": "289",
    "is_active": true,
    "is_compe_participant": false,
    "ispb_number": "94968518",
    "name": "Decyseo Corretora de Câmbio Ltda.",
    "str_start_date": "2019-03-14"
  },
  "00000000": {
    "compe_number": "001",
    "is_active": true,
    "is_compe_participant": true,
    "ispb_number": "00000000",
    "name": "Banco do Brasil S.A.",
    "str_start_date": "2002-04-22"
  }
}

```

:::info

Os parâmetros da requisição são opcionais, caso nenhum seja especificado, todas as instituições serão retornadas na resposta da requisição (sem paginação).

:::

---

# Manual Consignado da Aeronáutica

URL: /documentation/manual_aeronautica/manual_consignado

---

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

:::info Funcionamento AERONÁUTICA
O sistema de consignações da Aeronáutica, via API, funciona 24 horas por dia, todos dias da semana, inclusive feriados.
:::

## 1. Autorização

Antes do envio de qualquer requisição de Consignado do Exército (Consulta, Emissão da dívida, etc), é necessário fazer o upload do consentimento do militar autorizando a QI a proceder com a consulta, averbação e manutenção em folha de pagamento. 
Para upload da autorização, seguir o passo a passo encontrado na sessão de [**Upload de Documentos**](../upload_de_documentos/)

O upload retornará uma chave única no campo de retorno "**document_key**" que deverá ser enviado no payload de requisição de Consulta de Margem Consignável em "**authorization_document_key**", confome melhor detalhado à seguir, no item  **[3. Consulta de Margem Consignável.](#3-consulta-de-margem-consignável)**

## 2. Simulação de Cenários de Sucesso nas Consultas de Saldos, Consulta de Lista de Contratos e Averbações em Sandbox

Para fins de teste, temos um conjunto de dados que podem ser utilizados para simular os casos de sucesso em sandbox, são eles:

| document_number | registration_code  |    token       | birthdate |
|-----------------|--------------------|----------------|-----------|
| 60221284630     |       18571        |    abc123      |1954-09-08 |
| 57343241400     |       72893        |    abc123      |1998-02-06 |
| 13212590696     |       15410        |    abc123      |1959-11-14 |

Essas informações devem ser enviadas no **payload da requisição** no momento da simulação e o resultado será enviado por meio do webhook de sucesso correspondente.

## 3. Consulta de Margem Consignável {#3-consulta-de-margem-consignavel}

Em posse dos dados de **CPF**, **Matrícula do militar** e a **Chave do Documento de Autorização**, o parceiro integrador pode realizar a **consulta assíncrona** da margem consignável do militar através do seguinte endpoint:

### Request

ENDPOINT /airforce_payroll/balance
MÉTODO POST

Request Body

```json
{
    "document_number": "45507529710",
    "registration_code": "146254221",
    "authorization_document_key": "f2bc2369-89ea-4a80-9f64-ba7b1566cd31",
}
```

:::info
 O CPF deve ser informados em formato de texto, com no máximo 11 caracteres, sem ".", sem "-" e alinhado com zeros à esquerda.
 A Matrícula também deve ser no formato de texto.
:::

#### Request Body Params

| Campo                        | Tipo   | Descrição                                 |
|------------------------------|--------|-------------------------------------------|
| `document_number`            | string | CPF do militar.                           |
| `registration_code`          | string    | Matrícula do militar.                     |
| `authorization_document_key` | uuid   | **document_key** do termo de autorização. |

### Sincronous Response

ENDPOINT /airforce_payroll/balance
STATUS 201

Response Body

```json
{
	"balance_key": "81da8afb-e1b2-4215-8093-c4b5feab8a9f",
	"status": "pending_search"
}
```

**Por ser assíncrono, os dados da consulta de margem do tomador serão retornados via webhook.**

#### Response Body Params

| Campo                        | Tipo   | Descrição                                                                                                              |
|------------------------------|--------|------------------------------------------------------------------------------------------------------------------------|
| `balance_key`                | string | Chave de identificação da consulta de Margem Consignável.                                                              |
| `status`                     | enum   | [Enumeradores de status de consulta de margem consignável abaixo.](#enumeradores-de-status-de-consulta-de-margem-consignável) |

#### Enumeradores de Status de Consulta de Margem Consignável {#enumeradores-de-status-de-consulta-de-margem-consignavel}

| Enumerador        | Descrição                                                                   |
|-------------------|-----------------------------------------------------------------------------|
| `pending_search`  | Consulta de margem consignável pendente de resposta do sistema do exército. |
| `processed`       | Consulta de margem consignável processada.                                  |

:::info
 O status ***'processed'*** refere-se apenas ao fato de que a requisição do saldo foi efetivamente eviada e processada, porém não diz respeito ao sucesso ou à falha da mesma, tal informação estará no payload enviado via **Webhook** explicado à seguir. 
:::

### Consulta com sucesso

O webhook de sucesso será retornado da seguinte forma: 

WEBHOOK_TYPE airforce_payroll.balance

Body

```json
{
	"webhook_type": "airforce_payroll.balance.status_change",
	"key": "81da8afb-e1b2-4215-8093-c4b5feab8a9f",
	"event_datetime": "2023-05-28T08:43:29Z",
	"status": "processed",
	"data": {
            "military_unit": "Aeronáutica Brasileira",
            "military_branch": "IAE",
            "category": "Ativo",
            "name": "João da Silva",
            "document_number": "12345678901",
            "registration_code": "ABC123",
            "balance": "15000.00",
            "birth_date": "1980-01-01",
            "grant_date": "2005-03-15",
            "allowed_installment_numbers": 24
     }
}
```

#### Response Body Params success
| Campo                              | Tipo    | Descrição                                                                        |
|------------------------------------|---------|----------------------------------------------------------------------------------|
| `webhook_type`                     | string  | Tipo do webhook.                                                                 |
| `key`                              | uuid    | Chave de referência do webhook. Neste caso, se trata da **balance_key**          |
| `event_datetime`                   | string  | Data e hora do envio do webhook.                                                 |
| `status`                           | string  | Status da consulta de margem consignável.                                        |
| `data`                             | json    | Campo que irá conter os dados referentes à consulta.                             |
| `data.military_unit`               | string  | Estabelecimento que o militar está cadastro no sistema eConsig.                  |
| `data.military_branch`             | string  | Orgão/organização militar que o militar está.                                    |
| `data.category`                    | string  | Categoria do militar.                                                            |
| `data.name`                        | string  | Nome do militar.                                                                 |
| `data.document_number`             | string  | CPF do militar.                                                                  |
| `data.registration_code`           | string  | Matrícula do militar.                                                            |
| `data.balance`                     | string  | Margem disponível para contratação de empréstimo consignado.                     |
| `data.birth_date`                  | string  | Data de nascimento do militar.                                                   |
| `data.grant_date`                  | string  | Data de admissão do militar.                                                     |
| `data.allowed_installment_numbers` | string  | Número limite de parcelas de um empréstimo consignado para o militar consultado. |

### Consulta com falha

O webhook de falha será retornado da seguinte forma: 

WEBHOOK_TYPE airforce_payroll.balance

Body

```json
{
    "webhook_type": "airforce_payroll.balance.status_change",
    "key": "81da8afb-e1b2-4215-8093-c4b5feab8a9f",
    "event_datetime": "2023-05-28T08:43:29Z",
    "status": "processed",
    "data": { 
            "title": "insufficient_permission",
            "description": "User Has insufficient permissions for this operation.",
            "translation": "Usuario nao possui permissoes suficientes para essa operacao.",
            "code": "ZP000329",
            "extra_fields": {} 
    }
}
```

Cada tipo de erro **mapeado** possui um título, código e descrição mais detalhada. Caso ainda não tenha sido mapeado retornaremos no mesmo formato porém com o título ***unknown_response***. Salvo os campos idênticos, a tabela abaixo descreve com detalhes os parâmetros retornados.

#### Response body params failure

| Campo                     | Tipo   | Descrição                                                                                                               |
|---------------------------|--------|-------------------------------------------------------------------------------------------------------------------------|
| `data.title`                     | string |Título referente ao erro ocorrido.                                                                                       |
| `data.description`               | string |Descrição detalhada em **inglês** do erro ocorrido.                                                                      |
| `data.translation`               | string |Tradução da decrição do erro ocorrido.                                                                                   |
| `data.code`                      | string |Código do erro recebido. **Os 3 últimos dígitos referem-se ao código de erro recebido pela Zetra.** (ex: ZP000***329***) |
| `data.extra_fields`              |  json  |Campo destinado à possíveis atributos extras.                                                                            |

 --- 

### Requisição de uma Consulta de Margem Consignável

Caso o parceiro queira saber sobre o andamento de alguma entidade Balance criada, ele pode realizar uma requisição da mesma:

:::danger Atenção!
Recomendamos fortemente que utilizem o Webhook como referência nas informações da Consulta de Margem Consignável do tomador. Feature passível de remoção no futuro.
:::

 #### Request

ENDPOINT /airforce_payroll/balance/[balance_key]
MÉTODO GET

#### Response

ENDPOINT /airforce_payroll/balance/[balance_key]
STATUS 200

Body

```json
{
	"status": "processed",
	"data": {
            "military_unit": "Aeronáutica Brasileira",
            "military_branch": "IAE",
            "category": "Ativo",
            "name": "João da Silva",
            "document_number": "12345678901",
            "registration_code": "ABC123",
            "balance": "15000.00",
            "birth_date": "1980-01-01",
            "grant_date": "2005-03-15",
            "allowed_installment_numbers": 24
     }
}
```

## 4. Consulta da Lista de Contratos

Em posse dos dados de **CPF**, **Matrícula do militar** e **Token** do possível tomador, o parceiro integrador pode realizar a consulta da lista de contratos do militar disponíveis para compra através do seguinte endpoint:

### Request

ENDPOINT /airforce_payroll/portability_contracts_report
MÉTODO POST

Request Body

```json
{
    "document_number": "45507529710",
    "registration_code": "146254221",
    "token": "abc1234"
}
```

:::info
 O CPF deve ser informados em formato de texto, com no máximo 11 caracteres, sem ".", sem "-" e alinhado com zeros à esquerda. A Matrícula também deve ser no formato de texto.
:::

#### Request Body Params

| Campo                        | Tipo   | Descrição                                 |
|------------------------------|--------|-------------------------------------------|
| `document_number`            | string | CPF do militar.                           |
| `registration_code`          | string | Matrícula do militar.                     |
| `token`                      | string | Senha do militar.                         |

### Sincronous Response

ENDPOINT /airforce_payroll/portability_contracts_report
STATUS 201

Response Body

```json
{
    "portability_contracts_report_key": "3e41a8afb-e1b2-4215-8093-c4b5feab529c" ,
    "status": "pending_search"
}
```

**Por ser assíncrono, os dados da consulta da lista de contratos do tomador serão retornados via webhook.**

#### Response Body Params

| Campo                              | Tipo   | Descrição                                                                                                              |
|------------------------------------|--------|------------------------------------------------------------------------------------------------------------------------|
| `portability_contracts_report_key` | string | Chave de identificação da consulta da lista de contratos.                                                              |
| `status`                           | enum   | [Enumeradores de status de consulta da lista de contratos.](#enumeradores-de-status-da-consulta-da-lista-de-contratos) |

#### Enumeradores de Status da Consulta da Lista de Contratos {#enumeradores-de-status-da-consulta-da-lista-de-contratos}

| Enumerador         | Descrição                                                                   |
|--------------------|-----------------------------------------------------------------------------|
| `pending_search`   | Consulta da lista de contratos pendente de resposta do sistema do exército. |
| `processed`        | Consulta da lista de contratos processada.                                  |

:::info
 O status ***'processed'*** refere-se apenas ao fato de que a requisição da consulta da lista de contratos foi efetivamente eviada e processada, porém não diz respeito ao sucesso ou à falha da mesma, tal informação estará no payload enviado via **Webhook** explicado à seguir. 
:::

### Webhook da Consulta de Lista de Contratos

O webhook de sucesso será retornado da seguinte forma: 

WEBHOOK_TYPE airforce_payroll.portability_contracts_report

Body

```json
{
    "webhook_type": "airforce_payroll.portability_contracts_report.status_change",
    "key": "3e41a8afb-e1b2-4215-8093-c4b5feab529c",
    "event_datetime": "2023-05-28T08:43:29Z",
    "status": "processed",
    "data": {
        "document_number": "45507529710",
        "contracts" : [
            {
                "econsig_id": "2361529",
                "consignatory": "BANCO XPTO", 
                "contract_date": "2022-01-03T15:01:57Z",
                "installment_amount": 10.0,
                "number_of_installments": 5,
                "number_of_paid_installments": 1,
                "contract_status":"in_progress"			
            },
            {
                "econsig_id": "2361529",
                "consignatory": "BANCO XPTO", 
                "contract_date": "2022-01-03T15:01:57Z",
                "installment_amount": 10.0,
                "number_of_installments": 5,
                "number_of_paid_installments": 1,
                "contract_status":"in_progress"			
            }
        ]
        
    }
}
```

#### Response Body Params
| Campo                                             | Tipo    | Descrição                                                                        |
|---------------------------------------------------|---------|----------------------------------------------------------------------------------|
| `webhook_type`                                    | string  | Tipo do webhook.                                                                 |
| `key`                                             | uuid    | Chave de referência do webhook. Neste caso, se trata da **balance_key**          |
| `event_datetime`                                  | string  | Data e hora do envio do webhook.                                                 |
| `status`                                          | string  | Status da consulta de margem consignável.                                        |
| `data`                                            | json    | Campo que irá conter os dados referentes à consulta.                             |
| `data.document_number`                            | string  | CPF do militar.                                                                  |
| `data.contracts`                                  | array   | Lista dos contratos e de suas respectivas informações.                           |
| `data.contracts.econsig_id`                       | string  | Identificador único do contrato no sistema da Zetra.                             |
| `data.contracts.consignatory`                     | string  | Consignatária do contrato.                                                       |
| `data.contracts.installment_amount`               | float   | Valor da parcela.                                                                |
| `data.contracts.number_of_installments`           | int     | Número total de parcelas do contrato.                                            |
| `data.contracts.number_of_paid_installments`      | int     | Número de parcelas pagas até a vigência atual.                                   |
| `data.contracts.contract_status`                  | string  | Situação do contrato.                                                            |

As possíveis Situações de Contrato estão mapeadas aqui.
| Situações do Contrato             | contract_status              | 
|-----------------------------------|------------------------------|
|"Aguard. Confirmação"              | `waiting_confirmation`       |
|"Suspensa Pelo Gestor."            | `suspend_by_manager`         |
|"Aguard. Liquidação"               | `waiting_closure`            |
|"Aguard. Liquidação Portabilidade" | `waiting_portability_closure`|
|"Aguard. Margem"                   | `waiting_balance`            |
|"Encerrado por Exclusão"           | `closed_by_exclusion`        |
|"Aguard. Deferimento"              | `waiting_approval`           |
|"Indeferida"                       | `rejected`                   |
|"Deferida"                         | `accepted`                   |
|"Em Andamento"                     | `in_progress`                |
|"Suspensa"                         | `suspended`                  |
|"Cancelada"                        | `canceled`                   |
|"Liquidada"                        | `settled`                    |
|"Concluído"                        | `completed`                  |

:::info
 Estas situações de contrato referem-se também às possíveis situações dos contratos internos.
:::

### Requisição de uma Consulta de Lista de Contratos

Caso o parceiro queira saber sobre o andamento de uma Consulta de Lista de Contratos, ele pode realizar uma requisição da mesma:

:::danger Atenção!
Recomendamos fortemente que utilizem o Webhook como referência nas informações da Lista de Contratos do tomador. Feature passível de remoção no futuro.
:::

#### Request

ENDPOINT /airforce_payroll/portability_contracts_report/[portability_contracts_report_key]
MÉTODO GET

#### Response

ENDPOINT /airforce_payroll/portability_contracts_report/[portability_contracts_report_key]
STATUS 200

Body

```json
{
    "status": "processed",
    "data": {
        "document_number": "45507529710",
        "contracts" : [
            {
                "econsig_id": "2361529",
                "consignatory": "BANCO XPTO", 
                "contract_date": "2022-01-03T15:01:57Z",
                "installment_amount": 10.0,
                "number_of_installments": 5,
                "number_of_paid_installments": 1,
                "contract_status":"in_progress"			
            },
            {
                "econsig_id": "2361529",
                "consignatory": "BANCO XPTO", 
                "contract_date": "2022-01-03T15:01:57Z",
                "installment_amount": 10.0,
                "number_of_installments": 5,
                "number_of_paid_installments": 1,
                "contract_status":"in_progress"			
            }
        ]
        
    }
}
```

## 5. Simulação da Operação de Crédito Pessoal

Primeiramente é preciso calcular o valor da operação de Crédtio Pessoal necessária para quitar a operação de crédito original.

O valor do saldo devedor da dívida original deve ser informado no campo _**disbursed_amount**_.

:::caution Aviso
A operação deve ser simulada com apenas 1 parcela, desembolso em **D0** e a parcela deve ter seu vencimento para **D+5 dias úteis**, contas a partir da data de desembolso (pagamento) da operação.
:::

### Request

ENDPOINT /debt_simulation
MÉTODO POST

```json title='Request Body'
{
	"borrower": {
		"person_type": "natural"
	},
	"financial": {
		"disbursed_amount": 80492.95,
		"monthly_interest_rate": 0.03,
		"credit_operation_type": "ccb",
		"disbursement_date": "2023-03-17",
		"issue_date": "2023-03-17",
		"fine_configuration": {
			"contract_fine_rate": 0,
			"interest_base": "workdays",
			"monthly_rate": 0
		},
		"interest_grace_period": 0,
		"interest_type": "pre_price_days",
		"number_of_installments": 1,
		"principal_grace_period": 0,
		"first_due_date_delay": 5
	}
}
```

---

## 6 .Simulação da Operação de Crédito Consignado da AERONÁUTICA 

Nesta simulação os campos informados terão seus valores atribuidos da seguinte forma:

_**installment_face_value**_ = Valor da margem consignável

_**disbursement_date**_ = **D+5 dias úteis** do momento da simulação

_**due_balance**_ = **total_amount** da 1ª parcela retornada na simulação da Operação de Crédito Pessoal

_**original_deadline**_ = Prazo total em dias da Operação de Crédito Pessoal (5 dias)

### Request

ENDPOINT /debt_simulation
MÉTODO POST

```json title='Request Body'
{
    "borrower": {
        "person_type": "natural"
    },
    "financial": {
        "first_due_date": "2023-06-10",
        "installment_face_value": 100.0,
        "disbursement_date": "2023-03-22",
        "number_of_installments": 96,
        "monthly_interest_rate": 0.0205,
        "interest_type": "pre_price_days",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0
    },
    "collaterals": [{
        "collateral_type": "airforce_payroll"
    }],
    "refinanced_credit_operations": [
        {
            "due_balance": 1250.20,
            "original_deadline": 120
        }
    ]
}
```

O campo _**data.final_disbursement_amount**_ retornado na simulação será o valor do troco pago ao cliente.

---

### Consulta do valor de parcela da operação de Crédito Pessoal

#### Request

ENDPOINT /debt?key=[DEBT-KEY]&eval_present_value=True&calculate_delay=True&calculate_spread=False
MÉTODO GET

:::info Informação
A DEBT-KEY é a chave retornada na resposta da criação da operação (resposta do /debt)
:::

---

## 7. Criação da conta de titularidade do devedor

Antes da digitação das propostas é necessário abrir uma conta para o devedor na QI Tech.

A conta será utilizada para receber o desembolso da Operação de Crédito Pessoal, realizar os pagamentos do saldo devedor da dívida original em outro banco (via Boleto, TED ou Pix).

### Request

ENDPOINT /account
MÉTODO POST

```json title='Request Body'
{
	"is_operation_account": true,
	"account_owner": {
		"address": {
			"city": "São Paulo",
			"complement": "s/c",
			"neighborhood": "Pinheiros",
			"number": "215",
			"postal_code": "12345012",
			"state": "SP",
			"street": "Gilberto Sabino"
		},
		"birth_date": "1961-01-30",
		"document_identification": "261a8fbc-d998-4dd7-8515-ddebb212ae27",
		"is_pep": false,
		"mother_name": "Nome da Mãe do Devedor",
		"nationality": "brasileiro",
		"email": "email@email.com",
		"individual_document_number": "12345678911",
		"name": "Nome do Devedor",
		"phone": {
			"area_code": "11",
			"country_code": "055",
			"number": "900000000"
		},
		"person_type": "natural"
	}
}
```

| Parâmetro                                                    | Descrição                                          |
|--------------------------------------------------------------|----------------------------------------------------|
| **account_owner**                                            | Dados do devedor                                   |
| **is_operation_account**                                     | Indicativo de que a conta é uma conta de operação. |

### Response

ENDPOINT /account
MÉTODO POST

```json title='Response Body'
{
	"data": {
		"account_info": {
			"account_branch": "0001",
			"account_digit": "3",
			"account_number": "1234567",
			"financial_institution_code": "329"
		},
		"account_owner": {
			"document_number": "12345678911",
			"name": "Nome do Devedor"
		}
	},
	"event_datetime": "2023-03-21 12:30:24",
	"key": "8ff1e73f-e87b-4641-99a6-3267030c6034",
	"status": "account_pending_operation",
	"webhook_type": "account"
}
```

:::info
Os dados de conta retornados no /account deverão ser utilizados como conta de desembolso da Operação de Crédito Pessoal
:::

### Erro 5xx ou Timeout 

O fluxo não deve prosseguir enquanto a conta não estiver abertua com sucesso. 
Para os casos de falha, deve ser checado se a conta de fato não foi aberta para o cliente, antes de uma possível retentativa de abertura.

É possível checar se a conta foi aberta para o cliente, listando as conta abertas para um determinado CPF.

#### Request

ENDPOINT /account
MÉTODO POST
PARAMETER owner_document_number, requester_key

| Parâmetro                 | Descrição                          |
|---------------------------|------------------------------------|
| **owner_document_number** | CPF do devedor                     |
| **requester_key**         | É uma chave interna da integração. |

#### Response
STATUS 200

```json title='Response Body'
{
	"data": [{
		...
		"account_branch": "0001",
		...
		"account_digit": "2",
		...
		"account_key": "f600a6a9-0845-454f-b25c-a6d108ea582e",
		"account_name": "Default",
		"account_number": "1467576",
		"account_status": {
			"created_at": "2019-10-11T18:58:31",
			"enumerator": "opened",
			"translation_path": "account.AccountStatus.opened"
		},
		...
		"owner_document_number": "09080702000105",
		"owner_name": "Nome do Devedor",
		...
	}],
	"pagination": {
		"current_page": 1,
		"next_page": null,
		"rows_per_page": 100,
		"total_pages": 1,
		"total_rows": 1
	}
}
```

:::info Informação
No payload de resposta acima, estão listados apenas os campos relevantes para leitura.
:::

---

## 8. Emissão das Operações

- **Operação de Crédito Pessoal**: Deve ser emitida com desembolso em D0 e com apenas uma parcela com vencimento para **D+5 dias úteis** do desembolso.

:::danger Atenção
Para emissão da Operação de Crédito Pessoal o objeto "_**financial**_", deve ser enviado com exatamente as mesmas informações enviadas na sua simulação.
:::

:::info Informação
A Operação de Crédito Pessoal, só pode desembolsar em **dias úteis** e nos seguintes horários, à depender do meio de pagamento do saldo devedor da dívida original:
- **TED**: desembolso entre **6:30 e 17:15**
- **Boleto**: desembolso entre **7:00 e 22:00**
- **Pix**: qualquer horário (mas é recomendado o desembolso em horário comercial, pois caso uma operação seja desembolsada de madrugada, por exemplo, a entrada do Pix pode ser rejeitada por suspeitas de fraude)
:::

### Emissão da Operação de Crédito Pessoal

Para emitir a Operação de Crédito Pessoal, é necessário enviar a informação dos Boletos/TEDs/Pix que precisam ser pagos após o desembolso da operação. 

:::caution Atenção
O parceiro deve gerar uma chave interna de identificação da operação e enviá-la na requisição de emissão de dívida no campo "_**requester_identifier_key**_"
:::

#### Exemplos Resquests

ENDPOINT /debt
MÉTODO POST

**Boleto**

```json title='Request Body'
{
    "borrower": {
        "name": "Nome do Devedor",
        "email": "email@email.com",
        "phone": {
            "number": "900000000",
            "area_code": "11",
            "country_code": "055"
        },
        "address": {
            "city": "São Paulo",
            "state": "SP",
            "number": "215",
            "street": "Gilberto Sabino",
            "complement": "s/c",
            "postal_code": "12345012",
            "neighborhood": "Pinheiros"
        },
        "role_type": "issuer",
        "birth_date": "1969-05-01",
        "mother_name": "Nome da Mãe do Devedor",
        "person_type": "natural",
        "individual_document_number": "12345678911",
        "gender": "male",
        "nationality": "brasileiro",
        "is_pep": false,
        "marital_status": "married"
    },
    "financial": {
        "disbursed_amount": 80492.95,
        "annual_interest_rate": 0.20983,
        "credit_operation_type": "ccb",
        "disbursement_date": "2023-03-17",
        "issue_date": "2023-03-17",
        "fine_configuration": {
            "contract_fine_rate": 0,
            "interest_base": "workdays",
            "monthly_rate": 0
        },
        "interest_grace_period": 0,
        "interest_type": "pre_price_days",
        "number_of_installments": 1,
        "principal_grace_period": 0,
        "first_due_date_delay": 5
    },
    "simplified": true,
    "additional_data": {
        "debt_payment": [{
            "bank_slip": [{
                "digitable_line": "10495419967200010004900031456924592920008049295",
                "amount": "80492,95",
                "beneficiary": "CAIXA ECONÔMICA FEDERAL",
                "due_date": "2023-03-17"
            }],
            "funds_transfer": [],
            "pix": [],
            "financial_institution_code_number": "623"
        }],
        "issuer_account": {
            "account_digit": "0",
            "account_branch": "1234",
            "account_number": "123456",
            "financial_institution_code_number": "104"
        },
        "total_af_amount": 86186.52
    },
    "requester_identifier_key": "7ac52492-61c0-4dd6-a414-b0bf940fb7ca",
    "disbursement_bank_account": {
        "bank_code": "329",
        "account_digit": "3",
        "branch_number": "0001",
        "account_number": "1234567"
    },
    "after_disbursement_actions": [{
        "action_data": {
            "digitable_line": "10495419967200010004900031456924592920008049295"
        },
        "action_type": "bankslip_payment"
    }],
    "modality": {
        "code": "0203"
    }
}
```

**TED**

```json title='Request Body'
{
    "borrower": {
        "name": "Nome do Devedor",
        "email": "email@email.com",
        "phone": {
            "number": "900000000",
            "area_code": "11",
            "country_code": "055"
        },
        "address": {
            "city": "São Paulo",
            "state": "SP",
            "number": "215",
            "street": "Gilberto Sabino",
            "complement": "s/c",
            "postal_code": "12345012",
            "neighborhood": "Pinheiros"
        },
        "role_type": "issuer",
        "birth_date": "1969-05-01",
        "mother_name": "Nome da Mãe do Devedor",
        "person_type": "natural",
        "individual_document_number": "12345678911",
        "gender": "male",
        "nationality": "brasileiro",
        "is_pep": false,
        "marital_status": "married"
    },
    "financial": {
        "disbursed_amount": 80492.95,
        "annual_interest_rate": 0.20983,
        "credit_operation_type": "ccb",
        "disbursement_date": "2023-03-17",
        "issue_date": "2023-03-17",
        "fine_configuration": {
            "contract_fine_rate": 0,
            "interest_base": "workdays",
            "monthly_rate": 0
        },
        "interest_grace_period": 0,
        "interest_type": "pre_price_days",
        "number_of_installments": 1,
        "principal_grace_period": 0,
        "first_due_date_delay": 5
    },
    "simplified": true,
    "additional_data": {
        "debt_payment": [{
            "bank_slip": [],
            "funds_transfer": [{
                "amount": "4736,07",
                "account_digit": "0",
                "account_branch": "0897",
                "account_number": "20001",
                "financial_institution_code_number": "341"
            }],
            "pix": [],
            "financial_institution_code_number": "341"
        }],
        "issuer_account": {
            "account_digit": "0",
            "account_branch": "0491",
            "account_number": "100021100",
            "financial_institution_code_number": "104"
        },
        "total_af_amount": 86186.52
    },
    "requester_identifier_key": "7ac52492-61c0-4dd6-a414-b0bf940fb7ca",
    "disbursement_bank_account": {
        "bank_code": "329",
        "account_digit": "3",
        "branch_number": "0001",
        "account_number": "1234567"
    },
    "after_disbursement_actions": [{
        "action_data": {
            "destination": {
                "name": "Nome Credor Original",
                "account_digit": "0",
                "account_branch": "0897",
                "account_number": "20001",
                "document_number": "87163234000138",
                "financial_institution_code_number": "341"
            },
            "transaction_amount": 4736.07
        },
        "action_type": "funds_transfer"
    }],
    "modality": {
        "code": "0203"
    }
}
```

**Chave Pix**

```json title='Request Body'
{
    "borrower": {
        "name": "Nome do Devedor",
        "email": "email@email.com",
        "phone": {
            "number": "900000000",
            "area_code": "11",
            "country_code": "055"
        },
        "address": {
            "city": "São Paulo",
            "state": "SP",
            "number": "215",
            "street": "Gilberto Sabino",
            "complement": "s/c",
            "postal_code": "12345012",
            "neighborhood": "Pinheiros"
        },
        "role_type": "issuer",
        "birth_date": "1969-05-01",
        "mother_name": "Nome da Mãe do Devedor",
        "person_type": "natural",
        "individual_document_number": "12345678911",
        "gender": "male",
        "nationality": "brasileiro",
        "is_pep": false,
        "marital_status": "married"
    },
    "financial": {
        "disbursed_amount": 80492.95,
        "annual_interest_rate": 0.20983,
        "credit_operation_type": "ccb",
        "disbursement_date": "2023-03-17",
        "issue_date": "2023-03-17",
        "fine_configuration": {
            "contract_fine_rate": 0,
            "interest_base": "workdays",
            "monthly_rate": 0
        },
        "interest_grace_period": 0,
        "interest_type": "pre_price_days",
        "number_of_installments": 1,
        "principal_grace_period": 0,
        "first_due_date_delay": 5
    },
    "simplified": true,
    "additional_data": {
        "debt_payment": [{
            "bank_slip": [],
            "funds_transfer": [],
            "pix": [{
                "amount": "4736,07",
                "account_digit": "0",
                "account_branch": "0897",
                "account_number": "20001",
                "financial_institution_code_number": "341",
                "ispb": "60701190"
            }],
            "financial_institution_code_number": "341"
        }],
        "issuer_account": {
            "account_digit": "0",
            "account_branch": "0491",
            "account_number": "100021100",
            "financial_institution_code_number": "104"
        },
        "total_af_amount": 86186.52
    },
    "requester_identifier_key": "7ac52492-61c0-4dd6-a414-b0bf940fb7ca",
    "disbursement_bank_account": {
        "bank_code": "329",
        "account_digit": "3",
        "branch_number": "0001",
        "account_number": "1234567"
    },
    "after_disbursement_actions": [{
        "action_data": {
            "pix_transfer_type": "key",
            "pix_key": "cahvepix@credororiginal.com.br",
            "transaction_amount": 4736.07
        },
        "action_type": "pix"
    }],
    "modality": {
        "code": "0203"
    }
}
```

**Pix Manual**

```json title='Request Body'
{
    "borrower": {
        "name": "Nome do Devedor",
        "email": "email@email.com",
        "phone": {
            "number": "900000000",
            "area_code": "11",
            "country_code": "055"
        },
        "address": {
            "city": "São Paulo",
            "state": "SP",
            "number": "215",
            "street": "Gilberto Sabino",
            "complement": "s/c",
            "postal_code": "12345012",
            "neighborhood": "Pinheiros"
        },
        "role_type": "issuer",
        "birth_date": "1969-05-01",
        "mother_name": "Nome da Mãe do Devedor",
        "person_type": "natural",
        "individual_document_number": "12345678911",
        "gender": "male",
        "nationality": "brasileiro",
        "is_pep": false,
        "marital_status": "married"
    },
    "financial": {
        "disbursed_amount": 80492.95,
        "annual_interest_rate": 0.20983,
        "credit_operation_type": "ccb",
        "disbursement_date": "2023-03-17",
        "issue_date": "2023-03-17",
        "fine_configuration": {
            "contract_fine_rate": 0,
            "interest_base": "workdays",
            "monthly_rate": 0
        },
        "interest_grace_period": 0,
        "interest_type": "pre_price_days",
        "number_of_installments": 1,
        "principal_grace_period": 0,
        "first_due_date_delay": 5
    },
    "simplified": true,
    "additional_data": {
        "debt_payment": [{
            "bank_slip": [],
            "funds_transfer": [],
            "pix": [{
                "amount": "4736,07",
                "account_digit": "0",
                "account_branch": "0897",
                "account_number": "20001",
                "financial_institution_code_number": "341",
                "ispb": "60701190"
            }],
            "financial_institution_code_number": "341"
        }],
        "issuer_account": {
            "account_digit": "0",
            "account_branch": "0491",
            "account_number": "100021100",
            "financial_institution_code_number": "104"
        },
        "total_af_amount": 86186.52
    },
    "requester_identifier_key": "7ac52492-61c0-4dd6-a414-b0bf940fb7ca",
    "disbursement_bank_account": {
        "bank_code": "329",
        "account_digit": "3",
        "branch_number": "0001",
        "account_number": "1234567"
    },
    "after_disbursement_actions": [{
        "action_data": {
            "pix_transfer_type": "manual",
            "target_account": {
                "name": "Nome Credor Original",
                "account_digit": "0",
                "account_branch": "0897",
                "account_number": "20001",
                "document_number": "87163234000138",
                "financial_institution_code_number": "341"
            },
            "transaction_amount": 4736.07
        },
        "action_type": "pix"
    }],
    "modality": {
        "code": "0203"
    }
}
```
  

**QrCode Pix**

```json title='Request Body'
{
    "borrower": {
        "name": "Nome do Devedor",
        "email": "email@email.com",
        "phone": {
            "number": "900000000",
            "area_code": "11",
            "country_code": "055"
        },
        "address": {
            "city": "São Paulo",
            "state": "SP",
            "number": "215",
            "street": "Gilberto Sabino",
            "complement": "s/c",
            "postal_code": "12345012",
            "neighborhood": "Pinheiros"
        },
        "role_type": "issuer",
        "birth_date": "1969-05-01",
        "mother_name": "Nome da Mãe do Devedor",
        "person_type": "natural",
        "individual_document_number": "12345678911",
        "gender": "male",
        "nationality": "brasileiro",
        "is_pep": false,
        "marital_status": "married"
    },
    "financial": {
        "disbursed_amount": 80492.95,
        "annual_interest_rate": 0.20983,
        "credit_operation_type": "ccb",
        "disbursement_date": "2023-03-17",
        "issue_date": "2023-03-17",
        "fine_configuration": {
            "contract_fine_rate": 0,
            "interest_base": "workdays",
            "monthly_rate": 0
        },
        "interest_grace_period": 0,
        "interest_type": "pre_price_days",
        "number_of_installments": 1,
        "principal_grace_period": 0,
        "first_due_date_delay": 5
    },
    "simplified": true,
    "additional_data": {
        "debt_payment": [{
            "bank_slip": [],
            "funds_transfer": [],
            "pix": [{
                "amount": "4736,07",
                "account_digit": "0",
                "account_branch": "0897",
                "account_number": "20001",
                "financial_institution_code_number": "341",
                "ispb": "60701190"
            }],
            "financial_institution_code_number": "341"
        }],
        "issuer_account": {
            "account_digit": "0",
            "account_branch": "0491",
            "account_number": "100021100",
            "financial_institution_code_number": "104"
        },
        "total_af_amount": 86186.52
    },
    "requester_identifier_key": "7ac52492-61c0-4dd6-a414-b0bf940fb7ca",
    "disbursement_bank_account": {
        "bank_code": "329",
        "account_digit": "3",
        "branch_number": "0001",
        "account_number": "1234567"
    },
    "after_disbursement_actions": [{
        "action_data": {
            "pix_transfer_type": "qr_code",
            "qr_code": "00020126870014br.gov.bcb.pix2565qrcode.qitech.app/bacen/cobv/4ec760c4-b950-4afd-af10-92c1bb7804015204000053039865802BR5925SECURITIZADORA DE CREDITO6009SAO PAULO61080540700362070503***63042FA4"
        },
        "action_type": "pix"
    }],
    "modality": {
        "code": "0203"
    }
}
```
    

#### Enumeradores Marital Status
| Enumerador   | Descrição     |
|--------------|---------------|
| **single**   | Solteiro(a)   |
| **married**  | Casado(a)     |
| **widower**  | Viúvo(a)      |
| **divorced** | Divorciado(a) |

#### Erro 5xx ou Timeout

Caso seja retornado algum 5xx ou Timeout na requisição, afim de certificar que a operação de fato não foi criada na QI, é recomendado que o parceiro realize uma consulta da operação que teve retorno 5xx ou timeout.

ENDPOINT /debt?requester_identifier_key=34427233-925d-416d-93eb-c7f5084e8359
MÉTODO GET

Caso o retorno do GET seja um 200, o parceiro não deve retentar a criação da operação e seguir o fluxo da operação.
Caso seja retornado um 404 - Not Found, o parceiro deve retentar a criação da operação.

STATUS 200

```json title='Response Body'
{
    "data": {
        "additional_iof": 307.166388,
        "annual_cet": "60,4731%",
        "assignment_amount": 80833.26,
        "base_iof": 33.141637696905995,
        "borrower": {
            "document_number": "12345678911",
            "name": "Nome do Devedor"
        },
        "cet": "4,0200%",
        "collaterals": [],
        "contract": {
            "external_contract_key": "351eada5-a626-404c-a3a3-f91c123270ce",
            "number": "0000000001/NDD",
            "signature_information": [{
                "signature_url": "https://sign.qitech.com.br/s/hNrwjda",
                "signer_document_number": "12345678911",
                "signer_email": "email@email.com",
                "signer_external_key": "56d105f3-a7f6-4442-95e9-71f44d2ae5fc",
                "signer_name": "Nome do Devedor",
                "signer_role": "issuer"
            }],
            "urls": [
                "https://storage.googleapis.com/live-doc-api/documents/45e5b9c0-0f56-40a8-aace-d206f72c164d/QISCD-NOME_DO_DEVEDOR-CCB-0001212121-20230317194512.pdf"
            ]
        },
        "contract_fee_amount": 0,
        "contract_fees": [],
        "external_contract_fee_amount": 0,
        "external_contract_fees": [],
        "installments": [{
            "accrual_reference_date": null,
            "additional_costs": [],
            "advanced_paid_amount": 0,
            "bank_slip_key": null,
            "business_due_date": "2023-03-22",
            "calendar_days": 5,
            "digitable_line": null,
            "due_date": "2023-03-22",
            "due_interest": 0,
            "due_principal": 80833.26,
            "fine_amount": null,
            "has_interest": true,
            "installment_history": [],
            "installment_key": "75460851-2e82-4e3d-a805-b3e55b6b31d4",
            "installment_number": 1,
            "installment_payment": [],
            "installment_status": "created",
            "installment_type": "principal",
            "original_due_principal": 80833.26,
            "original_pre_fixed_amount": 183.5073246195304,
            "original_principal_amortization_amount": 80833.26267538047,
            "original_total_amount": 81016.77,
            "paid_amount": 0,
            "paid_at": null,
            "post_fixed_amount": 0,
            "pre_fixed_amount": 183.5073246195304,
            "principal_amortization_amount": 80833.26267538047,
            "qr_code_key": null,
            "qr_code_url": null,
            "renegotiation_proposal_key": null,
            "tax_amount": 33.141637696905995,
            "total_accrual_amount": null,
            "total_amount": 81016.77,
            "total_paid_amount": 0,
            "workdays": 3
        }],
        "iof_charge_method": "financed",
        "issue_amount": 80833.26,
        "net_external_contract_fee_amount": 0,
        "number_of_installments": 1,
        "prefixed_interest_rate": {
            "annual_rate": 0.20983,
            "created_at": "2023-03-17T19:45:11",
            "daily_rate": 0.00075616,
            "interest_base": "workdays",
            "monthly_rate": 0.01599997
        },
        "requester_identifier_key": "34427233-925d-416d-93eb-c7f5084e8359",
        "total_iof": 340.31,
        "total_pre_fixed_amount": 183.5073246195304
    },
    "event_datetime": "2023-03-17 19:45:19",
    "key": "052fe83c-37f6-4339-a831-127b50566745",
    "status": "waiting_signature",
    "webhook_type": "debt"
}
```

:::info Informação
O campo "key" da resposta de criação da operação é a **DEBT-KEY**, que é a chave única da operação dentro da QI.
:::

#### Assinatura

#### Autorizar desembolso

Após assinatura da operação, é necessário autorizar a operação para desembolso.

ENDPOINT /debt/ [DEBT-KEY] /allow_disbursement
MÉTODO POST

```json title='Request Body'
{
    "allow_disbursement": true
}
```

#### Desembolso

Após ser assinada e autorizada para desembolso, a operação seguirá automaticamente para esteira de desembolso.

Após o desembolso ser processado o parceiro receberá o seguinte webhook:

#### Sucesso no desembolso

WEBHOOK_TYPE debt
STATUS Disbursed

```json title='Webhook Body'
{
    "key": "052fe83c-37f6-4339-a831-127b50566745",
    "data": {
        "installments": [{
            "due_date": "2023-03-22",
            "total_amount": 81016.77,
            "installment_key": "75460851-2e82-4e3d-a805-b3e55b6b31d4",
            "pre_fixed_amount": 183.5073246195304,
            "principal_amortization_amount": 80833.26267538047
        }],
        "ted_receipt_list": []
    },
    "status": "disbursed",
    "webhook_type": "debt",
    "event_datetime": "2023-03-17 13:20:40"
}
```

#### Ações pós-desembolso

Após o desembolso da Operação de Crédito Pessoal na conta do devedor criada na QI, serão executados os pagamentos de boleto/TED/Pix referente à quitação do saldo devedor da dívida original do devedor (ações pós-desembolso)

#### Sucesso

WEBHOOK_TYPE after_disbursement_action_update
STATUS Success

**Boleto**

```json title='Webhook Body'
{
    "key": "3bce3113-3644-4491-b87a-fe6551edff70",
    "data": {
        "status": "done",
        "action_key": "d25097e2-09f1-47fc-8b7f-d1988b1a7669",
        "error_data": null,
        "action_data": {
            "digitable_line": "10495419967200010004900031456924592920008049295"
        },
        "action_type": "bankslip_payment",
        "execution_data": {
            "bank_slip": {
                "payer": {
                    "name": "Nome do Devedor",
                    "document_number": "12345678911",
                    "document_number_formatted": "123.456.789-11"
                },
                "beneficiary": {
                    "name": "CAIXA ECONÔMICA FEDERAL",
                    "document_number": "00360305000104",
                    "document_number_formatted": "00.360.305/0001-04"
                },
                "payment_key": "500a496e-4cca-4b12-9dc8-254932ebbcac",
                "payment_date": "2023-03-08",
                "digitable_line": "10495419967200010004900031456924592920008049295",
                "expiration_date": "2023-03-10",
                "payment_date_formatted": "08/03/2023",
                "expiration_date_formatted": "10/03/2023",
                "financial_institution_name": "CAIXA ECONÔMICA FEDERAL",
                "financial_institution_compe_number": "104"
            },
            "origin_key": "dfac205a-bdef-4820-8608-2dc81d9e10d4",
            "transacted_at": "2023-03-08 16:07:58",
            "source_account": {
                "owner_name": "Nome do Devedor",
                "account_digit": "3",
                "account_branch": "0001",
                "account_number": "1234567",
                "owner_document_number": "12345678911",
                "financial_institution_name": "QI SCD S.A.",
                "owner_document_number_formatted": "123.456.789-11",
                "financial_institution_compe_number": 329
            },
            "source_subtype": "bank_slip_payment",
            "transaction_key": "86a4320d-a69d-4c14-8300-9a6f22d35fcb",
            "transacted_at_br": "2023-03-08 13:07:58",
            "pdf_encoded_string": "\<BASE 64 DO PDF DO COMPROVANTE\>",
            "transaction_amount": 3864.95,
            "transacted_at_formatted": "08/03/2023, 16:07:58",
            "transacted_at_br_formatted": "08/03/2023, 13:07:58",
            "transaction_amount_formatted": "R$ 3.864,95",
            "source_subtype_translation_ptbr": "Pagamento de Boleto"
        }
    },
    "webhook_type": "after_disbursement_action_update",
    "event_datetime": "2023-03-08 16:08:02"
}
```

**TED**

```json title='Webhook Body'
{
    "key": "1f13c154-4164-412d-b3f3-00b7af7b18ee",
    "data": {
        "status": "done",
        "action_key": "a7a2c87d-b882-4680-ae58-9a5292d26788",
        "error_data": null,
        "action_data": {
            "destination": {
                "name": "Nome Credor Original",
                "account_digit": "0",
                "account_branch": "0897",
                "account_number": "20001",
                "document_number": "87163234000138",
                "financial_institution_code_number": "341"
            },
            "transaction_amount": 520
        },
        "action_type": "funds_transfer",
        "execution_data": {
            "origin_key": "f786dc97-faaa-40d8-9818-c8dc184bf131",
            "transacted_at": "2023-03-23 16:48:27",
            "source_account": {
                "owner_name": "Nome do Devedor",
                "account_digit": "3",
                "account_branch": "0001",
                "account_number": "1234567",
                "owner_document_number": "12345678911",
                "financial_institution_name": "QI SCD S.A.",
                "owner_document_number_formatted": "123.456.789-11",
                "financial_institution_compe_number": 329
            },
            "source_subtype": "withdrawal",
            "target_account": {	
                "owner_name": "Nome Credor Original",
                "account_type": "checking_account",
                "account_digit": "0",
                "account_branch": "0897",
                "account_number": "20001",
                "account_type_str": "Conta Corrente",
                "owner_document_number": "87163234000138",
                "financial_institution_name": "ITAÚ UNIBANCO S.A.",
                "owner_document_number_formatted": "87.163.234/0001-38",
                "financial_institution_compe_number": "341"
            },
            "transaction_key": "b8993075-9ede-4073-be2d-6130b052f888",
            "transacted_at_br": "2023-03-23 13:48:27",
            "pdf_encoded_string": "\<BASE 64 DO PDF DO COMPROVANTE\>",
            "transaction_amount": 520.0,
            "transacted_at_formatted": "23/03/2023, 16:48:27",
            "transacted_at_br_formatted": "23/03/2023, 13:48:27",
            "transaction_amount_formatted": "R$ 520,00",
            "source_subtype_translation_ptbr": "Transferência"
        }
    },
    "webhook_type": "after_disbursement_action_update",
    "event_datetime": "2023-03-23 16:48:31"
}
```

  

#### Erro na ação pós-desembolso

Em caso de erro no pagamento da ação pós-desembolso, o parceiro será notificado através do seguinte webhook:

WEBHOOK_TYPE after_disbursement_action_update
STATUS Error

**Boleto**

```json title='Webhook Body'
{
    "key": "e358e7e3-17b8-4aab-9da1-92f6b78dea00",
    "data": {
        "status": "error",
        "action_key": "e2495e5a-df32-4826-b6f0-419014d3c35a",
        "error_data": {
            "error_code": "QIT000007",
            "description": "Account blocked balance cannot be negative."
        },
        "action_data": {
            "digitable_line": "10495419967200010004900031456924592920008049295"
        },
        "action_type": "bankslip_payment",
        "execution_data": null
    },
    "webhook_type": "after_disbursement_action_update",
    "event_datetime": "2023-03-22 12:06:38"
}
```

**TED**

```json title='Webhook Body'
{
    "key": "e358e7e3-17b8-4aab-9da1-92f6b78dea00",
    "data": {
        "status": "error",
        "action_key": "e2495e5a-df32-4826-b6f0-419014d3c35a",
        "error_data": {
            "error_code": "QIT000007",
            "description": "Account blocked balance cannot be negative."
        },
        "action_data": {
            "destination": {
                "name": "Nome Credor Original",
                "account_digit": "0",
                "account_branch": "0897",
                "account_number": "20001",
                "document_number": "87163234000138",
                "financial_institution_code_number": "341"
            },
            "transaction_amount": 1000
        },
        "action_type": "funds_transfer",
        "execution_data": null
    },
    "webhook_type": "after_disbursement_action_update",
    "event_datetime": "2023-03-22 12:06:38"
}
```

#### Estorno da TED da ação pós-desembolso

Caso a TED realizada na ação pós-desembolso seja devolvida pela instituição financeira destinatária, o parceiro será notificado através do seguinte webhook:

WEBHOOK_TYPE after_disbursement_action_update
STATUS Refused

```json title='Webhook Body'
{
    "key": "f4b5c36a-2aa1-4865-9678-e5a6fa585845",
    "data": {
        "status": "refused",
        "action_key": "cf3b8809-36dc-4574-8763-3600e413cf5c",
        "error_data": {
            "code": "agencia_conta_invalida",
            "description": "Agência ou Conta Destinatária do Crédito Inválida"
        },
        "action_data": {
            "destination": {
                "name": "SILVANA RAMOS DOS SANTOS",
                "account_digit": "1",
                "account_branch": "0150",
                "account_number": "301771620",
                "document_number": "30874011884",
                "financial_institution_code_number": "237"
            },
            "transaction_amount": 3200
        },
        "action_type": "funds_transfer",
        "action_amount": 3200.0
    },
    "webhook_type": "after_disbursement_action_update",
    "event_datetime": "2023-03-23 14:46:39"
}
```

#### Retentar ação pós-desembolso com falha

Caso ocorra um erro/estorno no pagamento da ação pós-desembolso, ela pode ser retentada através do seguinte endpoint [/baas/action/**[ACTION-KEY]**](/documentation/emissao_de_divida/reprocessar_acao_pos_desembolso)

### Emissão da Operação de Crédito Consignado da Aeronáutica

A Operação de Crédito Consignado do Exército deve quitar a Operação de Crédito Pessoal e liberar (caso exista) o troco para o cliente

#### Request

ENDPOINT /debt
MÉTODO POST

**Digitação Portabilidade(s)**

```json title='Request Body'
{
    "borrower": {
        "name": "Nome do Devedor",
        "email": "email@email.com",
        "phone": {
            "number": "900000000",
            "area_code": "11",
            "country_code": "055"
        },
        "address": {
            "city": "São Paulo",
            "state": "SP",
            "number": "215",
            "street": "Gilberto Sabino",
            "complement": "s/c",
            "postal_code": "12345012",
            "neighborhood": "Pinheiros"
        },
        "role_type": "issuer",
        "birth_date": "1969-05-01",
        "mother_name": "Nome da Mãe do Devedor",
        "person_type": "natural",
        "individual_document_number": "12345678911",
        "gender": "male",
        "nationality": "brasileiro",
        "is_pep": false,
        "marital_status": "married"
    },
    "financial": {
        "first_due_date": "2023-05-07",
        "installment_face_value": 100.0,
        "disbursement_date": "2023-03-22",
        "limit_days_to_disburse": 3,
        "number_of_installments": 72,
        "monthly_interest_rate": 0.017,
        "interest_type": "pre_price_days",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0
    },
    "simplified": true,
    "collaterals": [{
        "percentage": 1,
        "collateral_data": {
            "reservation_type": "portability",
            "portability_data":{
                "token":"hw342y1h24",
                "origin_econsig_ids": [
                    "2016587",
                    "2016588",
                    "2016589",
                ]
            },
            "registration_code": "12345678",
            "reservation_method": "creation"
        },
        "collateral_type": "airforce_payroll" 
    }],
    "requester_identifier_key": "7e000c2d-d381-470e-b233-416097504866",
    "disbursement_bank_account": {
        "bank_code": "341",
        "account_digit": "3",
        "branch_number": "1234",
        "account_number": "1234567"
    },
    "purchaser_document_number": "32402502000135",
    "modality": {
        "code": "0202"
    },
    "refinanced_credit_operations": [
        {
            "operation_key": "d2fd3f63-3d11-42a8-ab5c-9a84b5c58b6c"
        }
    ]
}
```

**Digitação Margem Livre**

```json title='Request Body'
{
    "borrower": {
        "name": "Nome do Devedor",
        "email": "email@email.com",
        "phone": {
            "number": "900000000",
            "area_code": "11",
            "country_code": "055"
        },
        "address": {
            "city": "São Paulo",
            "state": "SP",
            "number": "215",
            "street": "Gilberto Sabino",
            "complement": "s/c",
            "postal_code": "12345012",
            "neighborhood": "Pinheiros"
        },
        "role_type": "issuer",
        "birth_date": "1969-05-01",
        "mother_name": "Nome da Mãe do Devedor",
        "person_type": "natural",
        "individual_document_number": "12345678911",
        "gender": "male",
        "nationality": "brasileiro",
        "is_pep": false,
        "marital_status": "married"
    },
    "financial": {
        "first_due_date": "2023-05-07",
        "installment_face_value": 100.0,
        "disbursement_date": "2023-03-22",
        "limit_days_to_disburse": 3,
        "number_of_installments": 72,
        "monthly_interest_rate": 0.017,
        "interest_type": "pre_price_days",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0
    },
    "simplified": true,
    "collaterals": [{
        "percentage": 1,
        "collateral_data": {
            "reservation_type": "new_credit",
            "registration_code": "123456789",
            "reservation_method": "creation"
        },
        "collateral_type": "airforce_payroll"
    }],
    "requester_identifier_key": "7e000c2d-d381-470e-b233-416097504866",
    "disbursement_bank_account": {
        "bank_code": "341",
        "account_digit": "3",
        "branch_number": "1234",
        "account_number": "1234567"
    },
    "purchaser_document_number": "32402502000135",
    "modality": {
        "code": "0202"
    },
    "refinanced_credit_operations": [
        {
            "operation_key": "d2fd3f63-3d11-42a8-ab5c-9a84b5c58b6c"
        }
    ]
}
```

**Digitação Refinanciamento**

```json title='Request Body'
{
    "borrower": {
        "name": "Nome do Devedor",
        "email": "email@email.com",
        "phone": {
            "number": "900000000",
            "area_code": "11",
            "country_code": "055"
        },
        "address": {
            "city": "São Paulo",
            "state": "SP",
            "number": "215",
            "street": "Gilberto Sabino",
            "complement": "s/c",
            "postal_code": "12345012",
            "neighborhood": "Pinheiros"
        },
        "role_type": "issuer",
        "birth_date": "1969-05-01",
        "mother_name": "Nome da Mãe do Devedor",
        "person_type": "natural",
        "individual_document_number": "12345678911",
        "gender": "male",
        "nationality": "brasileiro",
        "is_pep": false,
        "marital_status": "married"
    },
    "financial": {
        "first_due_date": "2023-05-07",
        "installment_face_value": 100.0,
        "disbursement_date": "2023-03-22",
        "limit_days_to_disburse": 3,
        "number_of_installments": 72,
        "monthly_interest_rate": 0.017,
        "interest_type": "pre_price_days",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0
    },
    "simplified": true,
    "collaterals": [{
        "percentage": 1,
        "collateral_data": {
            "reservation_type": "refinancing",
            "registration_code": "123456789",
            "reservation_method": "issuing"
        },
        "collateral_type": "airforce_payroll"
    }],
    "requester_identifier_key": "7e000c2d-d381-470e-b233-416097504866",
    "disbursement_bank_account": {
        "bank_code": "341",
        "account_digit": "3",
        "branch_number": "1234",
        "account_number": "1234567"
    },
    "purchaser_document_number": "32402502000135",
    "modality": {
        "code": "0202"
    },
    "refinanced_credit_operations": [
        {
            "operation_key": "d2fd3f63-3d11-42a8-ab5c-9a84b5c58b6c"
        }
    ]
}
```

### Detalhamento de campos no objeto collateral_data
| Campo             	| Descrição             						| Valores  												|
|-----------------------|-----------------------------------------------|-------------------------------------------------------|
| reservation_type		| Tipo da reserva								| [Enumeradores](#reservation_type_enumerator)			|
| registration_code		| Matrícula do militar							| 123456789               								|
| reservation_method	| Determina quando deve-se iniciar a tentativa de averbação do consignado, seja no momento da criação da operação de crédito ou no momento da emissão da mesma.	| [Enumeradores](#reservation_method_enumerator)		|
| portability_data  	| Dados de portabilidade						| [Objeto de Portabilidade](#portability_data_object)	|

### Tabela de tipos de reserva {#reservation_type_enumerator}
| Enumerador  | Descrição 		|
|-------------|-----------------|
| new_credit  | Crédito Novo 	|
| portability | Portabilidade 	|
| refinancing | Refinanciamento |

### Tabela de metodos de criação de reserva {#reservation_method_enumerator}

:::caution Atenção
Campo muito importante, pois ele determina diretamente quando o pedido de intensão de reserva na Zetra será feito.
:::

| Enumerator 	| Descrição                                     																		|
|---------------|-----------------------------------------------------------------------------------------------------------------------|
| creation		| A tentativa de averbação começará quando a operação de crédito for criada.											|
| issuing		| A tentativa de averbação começará quando a operação de crédito for emitida, ou seja, após a formalização da mesma.	|

### Detalhamento de campos no objeto portability_data {#portability_data_object}
| Campo             	| Descrição             									| Valores  						|
|-----------------------|-----------------------------------------------------------|-------------------------------|
| token             	| Senha fornecida pelo militar								| 1234abcd  					|
| origin_econsig_id		| Código identificador de contrato da Zetra					| 1234567						|
| origin_econsig_ids	| Lista de códigos identificadores de contratos da Zetra	| [1234567, 1234568, 1234569]	|

#### Response

STATUS 200

```json title='Response Body'
{
    "data": {
        "borrower": {
            "document_number": "12345678911",
            "name": "Nome do Devedor",
            "related_party_key": "1fe936e7-0917-4c3d-9206-87958254fa1d"
        },
        "collaterals": [{
            "absolute_amount": null,
            "collateral_constituted": false,
            "collateral_data": {
                "reservation_type": "new_credit",
                "registration_code": "123456789"
            },
            "collateral_key": "c6006572-d66a-45f6-862d-4ecb5b9b5d2d",
            "collateral_type": "airforce_payroll",
            "created_at": "2023-03-17T20:56:09.200482",
            "external_key": "1c736cd8-a4c7-43d4-8abd-c00ed0cd6450",
            "percentage": 1,
            "updated_at": "2023-03-17T20:56:09.200474"
        }],
        "contract": {
            "number": "0000000003/NDD",
            "signature_information": [{
                "signature_url": null,
                "signer_document_number": "12345678911",
                "signer_email": "email@email.com",
                "signer_external_key": null,
                "signer_name": "Nome do Devedor",
                "signer_role": "issuer"
            }],
            "urls": [
                "https://storage.googleapis.com/live-doc-api/documents/ae66d0cd-1054-4ff5-b1d6-e03aaaa2ff1b/QISCD-NOME_DO_DEVEDOR-CCB-0000000002-20230317183044.pdf"
            ]
        },
        "disbursement_options": [{
                "additional_iof": 24.220242,
                "annual_cet": "26.1457%",
                "assignment_amount": 3205.12,
                "base_iof": 176.6603785598479778,
                "cet": "1,9544%",
                "contract_fee_amount": 17.68,
                "contract_fees": [{
                    "amount": 17.68,
                    "amount_type": "absolute",
                    "fee_amount": 17.68,
                    "fee_type": "spread_cip_cost"
                }],
                "disbursement_date": "2023-03-22",
                "external_contract_fee_amount": 0,
                "external_contract_fees": [],
                "first_due_date": "2023-05-07",
                "installments": [{
                        "additional_costs": [],
                        "business_due_date": "2022-05-08",
                        "calendar_days": 34,
                        "due_date": "2023-05-07",
                        "due_interest": 0,
                        "due_principal": 3187.44,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "installment_status": null,
                        "installment_type": null,
                        "post_fixed_amount": 0,
                        "pre_fixed_amount": 64.20069301315790,
                        "principal_amortization_amount": 35.79930698684210,
                        "tax_amount": 0.10014353287723266,
                        "total_amount": 100,
                        "workdays": 23
                    }, 
                    ... 
                    x 96
                ],
                "issue_amount": 3187.44,
                "net_external_contract_fee_amount": 0,
                "total_iof": 100.44,
                "total_pre_fixed_amount": 3225.1656904289435
            },
            ...
            x 15
        ],
        "iof_charge_method": "financed",
        "requester_identifier_key": "f7fa079e-e02f-469f-a9ba-7a550f8f665f"
    },
    "event_datetime": "2023-03-17 13:54:58",
    "key": "23c89acf-b11b-4988-b738-a0f5ba238c33",
    "status": "waiting_signature",
    "webhook_type": "debt"
}
```

#### Averbação

Após a criação da Operação de Crédito Consignado do EXÉRCITO, a QI iniciará o processo de averbação da operação.

O processo de tentativa de averbação inicia no momento da criação da operação, e será retentado até a última data de opção de desembolso da operação.

A após a conclusão da averbação da margem consignável do exército, a QI notificará o parceiro através do seguinte webhook:

WEBHOOK_TYPE credit_operation.collateral
STATUS Success

```json title='Webhook Body'
{
    "key": "23c89acf-b11b-4988-b738-a0f5ba238c33",
    "data": {
        "collateral_type": "airforce_payroll",
        "collateral_constituted": true
    },
    "event_time": "2022-10-31 15:23:46",
    "webhook_type": "credit_operation.collateral"
}
```
Caso o token informado não seja válido, enviaremos o seguinte webhook. Esse webhook também será enviado caso o token informado já tenha sido utilizado e seja necessário um novo.

WEBHOOK_TYPE credit_operation.collateral
STATUS Pending Valid Token

```json title='Webhook Body'
{
    "key": "23c89acf-b11b-4988-b738-a0f5ba238c33",
    "data": {
        "collateral_type": "airforce_payroll",
        "collateral_data": {
            "reservation_status": "pending_valid_token",
            "cancel_reason": "invalid_token",
        },
        "collateral_constituted": false,
    },
    "event_time": "2022-10-31 15:23:46",
    "webhook_type": "credit_operation.collateral"
}
```

#### Resposta que ocasionam cancelamento automático

Dependendo da resposta da Zetra, a operação será cancelada automaticamente.
Quando isso ocorrer enviaremos um webhook no formato abaixo, o motivo do cancelamento é informado no campo "cancel_reason"

WEBHOOK_TYPE credit_operation.collateral
STATUS Canceled

```json title='Webhook Body'
{
    "data": {
        "cancel_reason": "Contrato de origem não encontrato.",
        "cancel_reason_enumerator": "airforce_payroll_portability_not_found"
    },
    "event_datetime": "2023-10-10 15:45:21",
    "key": "\<UUID \>",
    "status": "canceled",
    "webhook_type": "debt"

}
```
#### Tabela de enumeradores
| Enumerador                    				| Descrição                             | Código da Zetra  |
|-----------------------------------------------|---------------------------------------|------------------|
| airforce_payroll_military_not_found			| Militar não encontrado. 				| 293              |
| airforce_payroll_portability_not_found		| Contrato de origem não encontrato.	| 294              |
| airforce_payroll_consignable_margin_exceeded	| Margem disponível excedida.			| 359              |

#### Expiração da Portabilidade

Após 10 dias, a Zetra cancela os pedidos de portabilidades que estão aguardando confirmação.

Desta forma, para reiniciar o fluxo de portabilidade, faz-se necessário um novo token válido. Caso exista um novo token válido, a proposta retorna para o passo de intenção de portabilidade (status da reserva: pending_reservation). No entanto, caso não exista um token válido, geralmente porque o token enviado já foi utilizado na intenção de portabilidade anterior, a proposta é atualizada para o status de pending_valid_token, aguardando o envio de um novo token. Com o envio de um novo token válido, a proposta segue normalmente o fluxo de intenção de portabilidade e confirmação.

Para informar a situação será enviado o seguinte webhook:

WEBHOOK_TYPE credit_operation.collateral
STATUS Pending Reservation/Pending Valid Token

```json title='Webhook Body'
{
    "key": "23c89acf-b11b-4988-b738-a0f5ba238c33",
    "data": {
        "collateral_type": "airforce_payroll",
        "collateral_data": {
            "reservation_status": "pending_reservation" ou "pending_valid_token",
            "cancel_reason": "expired_portability",
        },
    },
    "event_time": "2022-10-31 15:23:46",
    "webhook_type": "credit_operation.collateral"
}
```

## 9. Envio de novo Token de Portabilidade

O token de portabilidade é de uso único, portanto, é necessário que um novo token seja enviado quando o anterior for utilizado ou no caso de token inválido.

A forma de envio é uma chamada simples:

### Request

ENDPOINT /debt/[DEBT-KEY]/collateral
MÉTODO PATCH

Request Body

```json
    {
        "portability_data": {
            "token": "12345678"
        }
    }
```

### Casos de sucesso

ENDPOINT /debt/[DEBT-KEY]/collateral
STATUS 204

Response Body - No content

### Caso de erro
:::info
Somente o token deverá ser enviado nessa requisição, caso contrário o processo retornará um erro
:::
#### Response

ENDPOINT /debt/[DEBT-KEY]/collateral
STATUS 400

Response Body

```json
    {
        "title": "Bad Request",
        "description": "Additional properties are not allowed (<campo extra> was unexpected)",
        "translation": "Schema Inválido",
        "code": "QIT000001"
    }
```

## 10. Cancelamento e Desaverbação:
Para realizar o cancelamento definitivo de uma operação, com a desaverbação da margem consignável, deve ser utilizado o seguinte endpoint:

:::caution Atenção
Vale ressaltar que o processo de desaverbação é assíncrono, ou seja, o cancelamento da operação de crédito, NÃO signifca necessáriamente que a desaverbação foi concluída. Para consultar o status da desaverbação vide [Recuperar resposta da última request](#recuperar-ultima-request)".
:::

:::caution Atenção
O cancelamento definitivo também pode ocorrer de forma automática, isso acontece quando uma operação está no status "canceled" por mais de 7 dias.
:::
### Request

ENDPOINT /debt/[DEBT-KEY]/cancel_permanently
MÉTODO POST

#### Cancelamento da operação com sucesso:

Após a conclusão do cancelamento da operação, o parceiro receberá o seguinte webhook:

WEBHOOK_TYPE debt
STATUS Canceled Permanently

Body

```json
{
	"key": "\<DEBT-KEY\>",
	"data": {},
	"status": "canceled_permanently",
	"webhook_type": "debt",
	"event_datetime": "2022-11-01 03:46:31"
}
```

#### Desaverbação com sucesso 

Após a conclusão da desaverbação, o parceiro receberá o seguinte webhook:

incluímos esse webhook de confirmação que a reserva foi desaverbada. Só existe em exército por enquanto. Como ainda não temos o last_response pro get /collateral, esse webhook seria importante pro cliente saber se foi desaverbada.
Se achar que pode gerar confusão, a gte remove. 
Seria a mesma ideia de webhook do pending_consent etc.  -->

WEBHOOK_TYPE debt
STATUS Canceled Permanently

Body

```json
{
	"key": "\<DEBT-KEY\>",
	"data": {
        "collateral_data": {
            "reservation_status": "deleted"
        },
        "collateral_type": "airforce_payroll",
        "collateral_constituted": false
    },
    "event_datetime": "2022-11-01 03:46:31",
	"webhook_type": "credit_operation.collateral",
	"event_datetime": "2022-11-01 03:46:31"
}
```

## 11. Recuperar resposta da última Request {#recuperar-ultima-request}

O ***last_response*** é uma forma de mapear, de forma simples e objetiva, a resposta da comunicação entre a QI e a Zetra, possibilitando saber quando essa requisição foi feita e qual o retorno obtido (através de um enumerador).

Cada enumerador tem uma descrição detalhada. Podemos conferir abaixo, com mais detalhes, como serão apresentados os dados do last response.

### Casos de sucesso

#### Request
ENDPOINT /debt/[DEBT-KEY]/collateral
MÉTODO GET

#### Response
ENDPOINT /debt/[DEBT-KEY]/collateral
STATUS 200
Response Body

```json
  {
    "collateral_constituted": true,
    "collateral_type": "airforce_payroll",
    "updated_at": "2023-05-24 19:13:02",
    "collateral_data": {
      "status": "reserved",
      "last_response": {
        "success": [
          {
            "enumerator": "succesfully_reserved"
          }
        ]
      },
      "last_response_event_datetime": "2023-05-22T19:13:02Z"
    }
  }
```

Response Body Portability or Refin

```json
{
    "collateral_constituted": true,
    "collateral_type": "airforce_payroll",
    "collateral_data": {
        "status": "reserved",
        "last_response": {
            "success": [
                {
                    "enumerator": "successfully_reserved"
                }
            ]
        },
        "last_response_event_datetime": "2023-08-09T19:25:09Z",
        "portability_data": {
            "origin_econsig_id": "2016587",
            "token": "123456"
        }       
    }
}
```

#### Tabela de enumeradores
| Enumerador                        | Descrição                        | Detalhes                                                           | Status da reserva    |
|-----------------------------------|----------------------------------|--------------------------------------------------------------------| ---------------------|
| successfully_accepted             | Reservation request accepted     | O pedido de averbação foi aceito e está aguardando confirmação     | pending_confirmation |
| successfully_reserved             | Reservation made successfully    | A reserva foi averbada com sucesso                                 | reserved             |
| successfully_deleted              | Reservation successfully deleted | A reserva foi desaverbada com sucesso                              | deleted              |

### Casos de erro

#### Request
ENDPOINT /debt/[DEBT-KEY]/collateral
MÉTODO GET

#### Response
ENDPOINT /debt/[DEBT-KEY]/collateral
STATUS 200
Response Body

```json
  {
    "collateral_constituted": false,
    "collateral_type": "airforce_payroll",
    "updated_at": "2023-05-24 19:13:02",
    "collateral_data": {
      "status": "pending_reservation",
      "last_response": {
        "errors": [
          {
            "enumerator": "invalid_portability_token"
          }
        ]
      },
      "last_response_event_datetime": "2023-05-22T19:13:02Z"
    }
  }
```

#### Tabela de enumeradores
| Enumerador                  | Descrição                                 | Ação QI | Código correspondente da Zetra  |
|-----------------------------|-------------------------------------------|---------|---------------------------------|
| waiting_confirmation        | Waiting Confirmation on Portability       | retry   |                                 |
| communication_error         | Communication Error with Zetra            | retry   | 241                             |
| consignable_margin_excceded | Exceeded consignable margin               | retry   | 359                             |

## 12. Informe de Saldo Devedor

O informe de saldo devedor acontece no 5º dia útil após o dia da solicitação, e todos os contratos informados são enviados pelo webhook com as seguintes informações:

WEBHOOK_TYPE airforce_payroll.due_balance.status_change
STATUS processed

Response Body

```json
{
	"webhook_type": "airforce_payroll.due_balance.status_change",
	"status": "processed",
	"event_datetime": "2024-03-12T19:23:12Z",
	"data":{
			"contract_number": "0000086715/TA",
			"payment_amount": 284.28,
			"balance_limit_date": "2024-03-12"
	}
}
```

---

# Homologation Roadmap - BNPL

URL: /documentation/manual_bnpl_ecommerce/manual_bnpl

## Summary
This document guides clients through integrating Buy Now Pay Later (BNPL) with the QI Tech platform. It outlines the essential steps and provides answers to common questions.

## 1. Document Inquiry
The document inquiry can be performed using the following request:

### Request Body Upload

ENDPOINT /document/[document_key]/url
METHOD GET

Testar no Playground

### Path Params

| Field          | Description                              |
|--------------- |------------------------------------------|
| `document_key` | Unique document key                      |

:::caution Attention
The document URL will be generated with an expiration period of 10 minutes.
:::

Response Body

```json
{
    "document_key": "8a1e62f3-7add-4240-a51d-e0f1a2f421fa",
    "document_url": "expirable_url",
    "signed_document_url": "expirable_url",
    "expiration_datetime": "2024-05-01T01:00:00.000Z"
}
```

## 2. Document upload
To receive the document_key for the debt issuance documents, you must upload them using the following request:

### Request Body Upload

ENDPOINT /upload
METHOD POST

Testar no Playground

Response Body

```json
{
  "document_key": "cfbc8469-89ea-4a80-9f64-ba7b1566c68b",
  "document_md5": "cd451103fa512frc98ce684d3896698c"
}
```

:::caution Atenção
Remember to save the **document_key**, as this key is required to query the document.
:::

### API call example

Example for uploading an image from a URL.

**Python**

```python

import jwt
import hashlib
import requests
from requests_toolbelt.multipart.encoder import MultipartEncoder
import json
from datetime import datetime

BASE_URL = "https://api-auth.sandbox.qitech.app"
API_KEY = "4c268c0a-53ff-429b-92b6-47ef98a6d89a" # This key is an example; please use your own key.
CLIENT_PRIVATE_KEY = ''''
-----BEGIN EC PRIVATE KEY-----
MIHbAgEBBEHh1hIeOPE5XNNhn6bxRAmVswsPZ0wZCmzVvP8Tl/LZK9ofVmRVGzll
srU1uezJEyHKYdOHrE2p52xUj+pHzjJvb6AHBgUrgQQAI6GBiQOBhgAEAAofUz1J
hBSOyGHLsnV9Sz0DSWmhl7U+ljqbfa8PKVFWSV3w16I1v2zME5/UzUhHn1gWsjnv
7/ekcLLAQbvqMPNXAfjIhFXLAPzqbB9iCuVua1v0Vgy52rBemOWrJka/Ws2bnKR8
h1N1OxOYeYr6C2jqMygBLktKMAs+282CEiEb4bIv
-----END EC PRIVATE KEY----- 
''' # This key is an example; please use your own key.

def get_document(url):
    try:
        response = requests.get(url)
        return response.content
    except Exception as error:
        print("Error fetching document:", error)
        raise

def upload_document(array_buffer):
    endpointeger= "/upload"
    method = "POST"
    timestamp = datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
    md5_hash = hashlib.md5(array_buffer).hexdigest()

    jwt_header = {
        "typ": "JWT",
        "alg": "ES512",
    }

    jwt_body = {
        "payload_md5": md5_hash,
        "timestamp": timestamp,
        "method": method,
        "uri": endpoint,
    }

    encoded_header_token = jwt.encode(jwt_body, CLIENT_PRIVATE_KEY, algorithm="ES512", headers=jwt_header)

    signed_header = {
        "Authorization": encoded_header_token,
        "API-CLIENT-KEY": API_KEY,
        "Content-Type": "multipart/form-data",
    }

    url = f"{BASE_URL}{endpoint}"
    multipart_data = MultipartEncoder(
        fields={'file': ('image.jpeg', array_buffer, 'image/jpeg')}
    )
    signed_header['Content-Type'] = multipart_data.content_type

    try:
        response = requests.post(url, headers=signed_header, data=multipart_data)
        response_data = response.json()
        document_key = response_data.get('document_key')
        print(f'Response data is: {response_data} and document_key is: {document_key}')
        return document_key
    except Exception as error:
        print('Error:', error)
        raise

def main():
    file_url = "{FILE_URL}"

    document_buffer = get_document(file_url)

    document_key = upload_document(document_buffer)

    print("document_key is", document_key)

if __name__ == "__main__":
    main()

```
  

**Node.js**

```js
const jwt = require('jsonwebtoken')
const crypto = require('crypto')
const axios = require('axios')
const FormData = require('form-data')
const fs = require('fs')
const fetch = require('node-fetch')

async function getDocument(url) {
  try {
    const response = await axios.get(url, { responseType: 'arraybuffer' })
    return response.data
  } catch (error) {
    console.error('Error fetching document:', error)
    throw error
  }
}

async function uploadDocument(arrayBuffer) {
  const endpointeger= '/upload'
  const method = 'POST'
  const timestamp = new Date().toISOString()
  const md5_hash = crypto.createHash('md5').update(arrayBuffer).digest('hex')
  const client_private_key = `-----BEGIN EC PRIVATE KEY-----
    MIHbAgEBBEHh1hIeOPE5XNNhn6bxRAmVswsPZ0wZCmzVvP8Tl/LZK9ofVmRVGzll
    srU1uezJEyHKYdOHrE2p52xUj+pHzjJvb6AHBgUrgQQAI6GBiQOBhgAEAAofUz1J
    hBSOyGHLsnV9Sz0DSWmhl7U+ljqbfa8PKVFWSV3w16I1v2zME5/UzUhHn1gWsjnv
    7/ekcLLAQbvqMPNXAfjIhFXLAPzqbB9iCuVua1v0Vgy52rBemOWrJka/Ws2bnKR8
    h1N1OxOYeYr6C2jqMygBLktKMAs+282CEiEb4bIv
    -----END EC PRIVATE KEY-----`; // This key is an example; please use your own key.
  const api_key = '4c268c0a-53ff-429b-92b6-47ef98a6d89a' // This key is an example; please use your own key.

  try {
    const jwt_header = {
      typ: 'JWT',
      alg: 'ES512',
    }

    const jwt_body = {
      payload_md5: md5_hash,
      timestamp: timestamp,
      method: method,
      uri: endpoint,
    }

    const encoded_header_token = jwt.sign(jwt_body, client_private_key, {
      algorithm: 'ES512',
      header: jwt_header,
    })

    const signed_header = {
      AUTHORIZATION: encoded_header_token,
      'API-CLIENT-KEY': api_key,
      'Content-Type': 'multipart/form-data',
    }

    const url = `${base_url}${endpoint}`
    const formData = new FormData()
    formData.append('file', Buffer.from(arrayBuffer), {
      filename: 'image.jpeg',
    })

    fetch(url, {
      method: 'POST',
      headers: signed_header,
      body: formData,
    })
      .then(data => {
        console.log('Response data is: ' + data)

        return data.document_key
      })
      .catch(error => {
        console.log('Error: ' + error)
      })
  } catch (error) {
    console.error('Error:', error)
  }
}

async function main() {
  const fileUrl = '<URL_LINK_TO_DOCUMENT_IMAGE>'
  const documentBuffer = await getDocument(fileUrl)
  const documentKey = await uploadDocument(documentBuffer)

  console.log('Document key is: ' + documentKey)
}

main()
```

- OBS: The example above uses the library [node-fetch](https://www.npmjs.com/package/node-fetch) to make the call, but you can use the library of your choice. The important thing is that the call must be made using the POST method, with the `Content-Type` header set to `multipart/form-data` and the body must be a FormData object with the key `file` and the value as the file binary to be sent.

:::warning Aviso
The 'Axios' library has a bug that causes FormData to be sent empty. The issue can be seen on the [GitHub repository](https://github.com/axios/axios/issues/5986). If this problem has not yet been resolved at the time of your integration, we suggest using the 'node-fetch' library to make this call.
:::

  

## 3. Debt Simulation

### Request Debt Simulation

At QI Tech, we provide our clients with the ability to simulate the values of a credit operation before it is actually issued. The simulation follows the same pattern as the debt issuance request, but it is not necessary to provide the debtor’s registration and disbursement account details. The following endpoint is a simplified version of /debt_simulation, but much more optimized. It is used to calculate only one disbursement option.

ENDPOINT /v2/credit_operation/simulation
METHOD POST

Testar no Playground

Request Body

```json
{
    "credit_operation_type": "ccb",
    "disbursed_issue_amount": 2800,
    "disbursement_date": "2025-09-24",
    "first_due_date": "2025-10-24",
    "force_installments_on_workdays": true,
    "interest_type": "pre_price_days",
    "issuer_person_type": "natural",
    "monthly_interest_rate": 0.04488,
    "number_of_installments": 12,
    "principal_amortization_month_period": 1
}
```

### Request Body Details

| Field  | Type   | Description | Max. Char. |
|---|--- |---|---|
| **credit_operation_type***                 | string    |   Type of credit agreement      |  **[Credit Operation Type Enumerator](#credit-operation-type-enumerator)**           |
| **disbursed_issue_amount***                | float   | The value actually released to the borrower      | 15,2           |
| **disbursement_date***                     | string    | The specific date the loan funds are made available      | 10            |
| **first_due_date***                        | string    | Due date of the first installment      | 10             |
| **force_installments_on_workdays***        | boolean | If true, ensures all installment due dates are moved to the next business day  |       5       |
| **interest_type***                         | string    |  Amortization method      | **[Interest Type Enumerator ](#interest-type-enumerator)**           |
| **issuer_person_type***                    | string    | Defines whether the issuer is an individual (natural person) or a legal entity (corporation/business)     | **[Person Type Enumerator](#person-type-enumerator)**           |
| **monthly_interest_rate***                 | float   |The percentage charged on a principal balance over a one-month period    | 10,6           |
| **number_of_installments***                | integer    | Number of installments      | 3            |
| **principal_amortization_month_period***   | integer    | Period, in months, between installments      | 1            |

### Response Debt Simulation

STATUS 200

Response Body

```json
    {
        "disbursement_date": "2025-09-24",
        "issue_amount": 2821.32,
        "interest_type": "pre_price_days",
        "assignment_amount": 2829.78,
        "base_iof": 10.6,
        "total_iof": 21.32,
        "additional_iof": 10.72,
        "cet": 5.09,
        "annual_cet": 81.39,
        "first_due_date": "2025-10-24",
        "disbursed_amount": 2800,
        "prefixed_interest_rate": {
            "annual_rate": 0.6935459998,
            "daily_rate": 0.0014644728,
            "interest_base": "calendar_days",
            "monthly_rate": 0.04488
        },
        "tax_configuration": {
            "base_rate": 8.2e-05,
            "additional_rate": 0.0038
        },
        "fees": [
            {
                "amount": 0.3,
                "fee_amount": 8.46,
                "amount_type": "percentage",
                "fee_type": "spread",
                "type": "internal"
            }
        ],
        "installments": [
            {
                "due_date": "2025-10-24",
                "amount": 1507.4,
                "due_principal": 2821.32,
                "due_interest": 0,
                "has_interest": true,
                "period": 1,
                "period_workdays": 1.1,
                "calendar_days": 30,
                "workdays": 22,
                "installment_number": 1,
                "period_to_disbursement": 1,
                "prefixed_amount": 126.62083829,
                "period_workdays_to_disbursement": 1.1,
                "calendar_days_to_disbursement": 30,
                "workdays_to_disbursement": 22,
                "tax_amount": 3.39671674,
                "principal_amortization_amount": 1380.77916171
            },
            {
                "due_date": "2025-11-24",
                "amount": 1507.4,
                "due_principal": 1440.54083829,
                "due_interest": 0,
                "has_interest": true,
                "period": 1,
                "period_workdays": 1,
                "calendar_days": 31,
                "workdays": 20,
                "installment_number": 2,
                "period_to_disbursement": 2,
                "prefixed_amount": 66.85916171,
                "period_workdays_to_disbursement": 2.1,
                "calendar_days_to_disbursement": 61,
                "workdays_to_disbursement": 42,
                "tax_amount": 7.20558527,
                "principal_amortization_amount": 1440.54083829
            }
        ]
    }
```

### Response Body Details
| Field                                   | Type   | Description                                                                                                                     |
|-----------------------------------------|--------|-------------------------------------------------------------------------------------------------------------------------------|
| **annual_cet**                          | float  | Total effective cost expressed as a decimal per year                                                                                | -            |
| **assignment_amount**                   | float  | Acquisition value of the credit operation                                                                                     | -            |
| **cet**                                 | float  | Total effective cost expressed as a decimal per month                                                                                | -            |
| **fees**                                | object | **[Object Fees](#object-fees)** - List of QI Tech fees charged on the operation                            | -            |
| **disbursed_amount**                    | float  | Amount disbursed in the credit operation                                                                                     | -            |
| **disbursement_date**                   | string   | Disbursement date of the operation                                                                                                | -            |
| **installments**                        | array   | **[Object Installments](#object-installments)** - Installments of the operation                                                        | -            |
| **interest_type**                       | string   | **[Enumerator Interest Type](#enumerator-interest-type)** - Amortization method and interest calculation method                 | -            |
| **additional_iof**                      | float  |A fixed-rate tax applied to the transaction principal, independent of the duration of the credit operation                                                                               | -            |
| **base_iof**                            | float  |  The taxable amount or principal value used as the basis for calculating the Tax on Financial Operations  | -            |
| **total_iof**                           | float  | The total amount of Tax on Financial Operations applied to the transaction   | -            |
| **issue_amount**                        | float  | Issue/nominal value of the credit operation                                                                               | -            |
| **tax_configuration**                   | object | **[Object Tax Configuration](#object-tax-configuration)** - Rate iof values                                             | -            |
| **first_due_date**                      | string   | Due date of the first installment                                                                                        | -            |
| **prefixed_interest_rate**              | object | **[Object Interest Rate](#object-interest-rate)** - Nominal interest rate                              | -            |

## 4. Debt issuance for natural persons

This endpoint issues the debt and processes the contract signature via opt-in. Disbursement occurs automatically immediately after issuance. Pre-registration is not required; simply provide the borrower's details during the debt request.

### Request

ENDPOINT /signed_debt
METHOD POST

Testar no Playground

Request Body

```json
{
    "additional_data": {
        "contract": {
            "contract_number": "TIK11267101100",
            "signed": true,
            "signatures": [
                {
                    "signer": {
                        "name": "Alan Mathison Turing",
                        "phone": {
                            "number": "912345678",
                            "area_code": "11",
                            "country_code": "055"
                        },
                        "email": "alan.turing@email.com",
                        "document_number": "96969879003"
                    },
                    "signature": {
                        "ip_address": "168.211.22.84",
                        "timestamp": "27-10-2025 11:07:15",
                        "signature_file": {
                            "file_url": "http://qitech.com.br/signature.pdf",
                            "file_type": "pdf"
                        },
                        "geolocation": {
                            "long": "-46.63611",
                            "lat": "-23.5475"
                        },
                        "fingerprint_device": null
                    }
                }
            ]
        }
    },
    "financial": {
        "number_of_installments": 2,
        "credit_operation_type": "ccb",
        "interest_type": "pre_price_days",
        "monthly_interest_rate": 0.07,
        "disbursed_amount": 200,
        "fine_configuration": {
            "contract_fine_rate": 0.02,
            "monthly_rate": 0.15,
            "interest_base": "calendar_days"
        },
        "interest_grace_period": 0,
        "disbursement_date": "2026-02-06",
        "first_due_date": "2026-03-06",
        "principal_grace_period": 0
    },
    "disbursement_bank_accounts": [
        {
            "account_digit": "5",
            "document_number": "32402502000135",
            "bank_code": "329",
            "account_number": "00002",
            "percentage_receivable": 100,
            "branch_number": "0001",
            "name": "Accout Name"
        }
    ],
    "requester_identifier_key":"6b558426-6b6c-4c9e-bfb3-5734fe45a651",
    "purchaser_document_number": "32402502000135",
    "borrower": {
        "email": "alan.turing@email.com",
        "document_identification": "494598fd-c226-4332-a500-591ae3884673",
        "document_identification_back": "494598fd-c226-4332-a500-591ae3884673",
        "birth_date": "1990-11-20",
        "person_type": "natural",
        "is_pep":false,
        "profession": "Public server",
        "individual_document_number": "96969879003",
        "address": {
            "city": "São Paulo",
            "neighborhood": "CENTRO",
            "street": "Avenida Feliz",
            "complement": "AP 801",
            "postal_code": "49026100",
            "state": "SP",
            "number": "1000"
        },
        "phone": {
            "country_code": "055",
            "number": "912345678",
            "area_code": "11"
        },
        "mother_name": "MARIA TURING",
        "document_identification_number": "96969879003",
        "name": "Alan Mathison Turing"
    }
}
```

### Request Body Details

| Field  | Type   | Description | Max. Char. |
|---|--- |---|---|
| **borrower** *                  | object | Borrower Object - The debtor of the credit operation         | **[Borrower Object](#borrower-object)** |
| **disbursement_bank_account** * | object |  Technical details of the bank account where the operation funds will be deposited.                                                                                 | **[Disbursement Bank Account Object](#disbursement-bank-account-object)**          |
| **financial** *                 | object | Contains all financial details and calculation parameters for the operation. | **[ Financial Object](#financial-object)**            |
| **purchaser_document_number** * | string | Assignee's Tax ID – The buyer of the credit operation (FIDC/Receivables Investment Fund).   | 14           |
| **additional_data** * | object | Assignee's Tax ID – The buyer of the credit operation (FIDC/Receivables Investment Fund).   | **[ Additional Data Object](#additional-data-object)**          |

### Borrower Object 

|Field|Type|Description|Max. Char.|
|---|--- |---|---|
|name *|string|Full name of the borrower|100|
|email|string|Borrower's electronic mail address|254|
|phone|object| Borrower's contact telephone details| **[Phone Object](#phone-object)**|
|is_pep *|boolean|Politically Exposed Person (PEP) indicator|5|
|address *|object| Borrower's residential address details| **[Address Object](#address-object)** |
|role_type *|enum|The role of the person in the operation. Default: issuer|-|
|birth_date *|date|Borrower's date of birth (Format: "YYYY-MM-DD")|10|
|mother_name *|string|Borrower's mother's full name|100|
|nationality|string|Borrower's nationality|50|
|person_type *|string|Person classification|7|
|individual_document_number *|string|Borrower's Tax ID (CPF) - numbers only|11|
|document_identification *|string|DOCUMENT_KEY of the uploaded identification document (RG or CNH)|36|
|document_identification_back|string|DOCUMENT_KEY of the uploaded back side of the identification document|36|

### Address Object

|Field|Type|Description|Max. Char.|
|---|--- |---|---|
|city *|string|City name of the address|100|
|state *|string|State abbreviation (two uppercase characters)|2|
|number *|string|Street number|10|
|street *|string|Street name|100|
|complement *|string|Address complement (free text)|100|
|postal_code *|string|Postal code (CEP) - numbers only|8|
|neighborhood *|string|Neighborhood or district name|100|

### Phone Object 

|Field|Type|Description|Max. Char.|
|---|--- |---|---|
|number *|string|Subscriber's phone number|9|
|area_code *|string|Two-digit regional area code (e.g., "11")|2|
|country_code *|string|International dialing code (e.g., "055")|3|

### Disbursement Bank Account Object
|Field|Type|Description|Max. Char.|
|---|--- |---|---|
|name|string|Account holder's full name|50|
|document_number|string|Account holder's Tax ID (CPF)|11|
|bank_code *|string|Financial institution's COMPE code|3|
|branch_number *|string|Branch number (do not include the branch check digit!)|4|
|account_number *|string|Account number (do not include the account check digit!)|10|
|account_digit *|string|Account check digit (use zero instead of letters)|1|
|account_type|enum|Account Type Enumerator - Type of the bank account| **[Account Type Object](#account-type-object)**|

### Additional Data Object 

|Field|Type|Description|Max. Char.|
|---|--- |---|---|
|contract_number *|string|The unique identifier or reference number of the contract|12|
|signed *|boolean|Indicates if the contract has been successfully signed|5|
|signatures *|array|List of digital signature evidence objects (Opt-in)|-|
|name *|string|Full name of the signer|255|
|document_number *|string|Signer's tax identification number (CPF)|11|
|email *|string|Electronic mail address of the signer|100|
|area_code *|string|Two-digit regional area code (e.g., "11")|2|
|number *|string|Subscriber's phone number|9|
|country_code *|string|International dialing code (e.g., "055")|3|
|ip_address *|string|The IP address used during the signature process|45|
|timestamp *|string|Date and time of the signature (DD-MM-YYYY HH:mm:ss)|19|
|file_url *|string|Direct link to the signed contract document (PDF)|2048|
|file_type *|string|Format of the signature file (e.g., "pdf")|4|
|long *|string|Geographic longitude coordinate of the signature location|20|
|lat *|string|Geographic latitude coordinate of the signature location|20|
|fingerprint_device|string|Unique digital identifier of the device used|-|

### Response

The response to this debt request will return the payment plan as well as a **DEBT-KEY**, which is the identifier of the debt in QI SCD.

STATUS 201

Response Body

```json
{
    "webhook_type": "debt",
    "key": "a6dbf441-31b0-44df-9bb8-593553de2c45",
    "status": "issued",
    "event_datetime": "2026-02-10 00:01:20",
    "data": {
        "borrower": {
            "name": "Alan Mathison Turing",
            "document_number": "96969879003",
            "related_party_key": "6995ff6e-27c2-47e9-b4bf-640934b56b23"
        },
        "contract": {
            "document_key": null,
            "number": "TIK11267101100",
            "urls": [],
            "signature_information": [
                {
                    "signer_name": "Alan Mathison Turing",
                    "signer_document_number": "96969879003",
                    "signer_role": "issuer",
                    "signer_email": "alan.turing@email.com",
                    "signer_external_key": null,
                    "signature_url": null
                }
            ]
        },
        "requester_identifier_key": "6b558426-6b6c-4c9e-bfb3-5734fe45a651",
        "iof_charge_method": "financed",
        "collaterals": [],
        "contract_fees": [
            {
                "fee_type": "spread",
                "fee_amount": 0.6
            }
        ],
        "external_contract_fees": [],
        "external_contract_fee_amount": 0,
        "net_external_contract_fee_amount": 0,
        "contract_fee_amount": 0.6,
        "issue_amount": 201.49,
        "assignment_amount": 202.09,
        "cet": "7,6600%",
        "annual_cet": "142,5744%",
        "number_of_installments": 2,
        "base_iof": 0.73,
        "additional_iof": 0.76,
        "total_iof": 1.49,
        "ipoc_code": "324025020203196969879003TIK11267101100",
        "prefixed_interest_rate": {
            "annual_rate": 1.252191589,
            "created_at": "2026-02-10T00:01:18",
            "daily_rate": 0.0022578334,
            "interest_base": "calendar_days",
            "monthly_rate": 0.07
        },
        "installments": [
            {
                "accrual_reference_date": null,
                "additional_costs": [],
                "advanced_paid_amount": 0,
                "bank_slip_key": null,
                "business_due_date": "2026-03-06",
                "calendar_days": 28,
                "digitable_line": null,
                "due_date": "2026-03-06",
                "due_interest": 0,
                "due_principal": 201.49,
                "fine_amount": null,
                "has_interest": true,
                "installment_history": [],
                "installment_key": "5c121fac-20f8-4481-b7b6-d0647a0ce524",
                "installment_number": 1,
                "installment_payment": [],
                "installment_status": "created",
                "installment_type": "principal",
                "original_due_principal": 201.49,
                "original_pre_fixed_amount": 13.13403553,
                "original_principal_amortization_amount": 97.92596447,
                "original_total_amount": 111.06,
                "paid_amount": 0,
                "paid_at": null,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 13.13403553,
                "principal_amortization_amount": 97.92596447,
                "qr_code_key": null,
                "qr_code_url": null,
                "renegotiation_proposal_key": null,
                "tax_amount": 0.22483801,
                "total_accrual_amount": null,
                "total_amount": 111.06,
                "total_paid_amount": 0,
                "workdays": 18
            },
            {
                "accrual_reference_date": null,
                "additional_costs": [],
                "advanced_paid_amount": 0,
                "bank_slip_key": null,
                "business_due_date": "2026-04-06",
                "calendar_days": 31,
                "digitable_line": null,
                "due_date": "2026-04-06",
                "due_interest": 0,
                "due_principal": 103.56403553,
                "fine_amount": null,
                "has_interest": true,
                "installment_history": [],
                "installment_key": "a8a21d7a-481e-43ba-b115-fd89253bcde9",
                "installment_number": 2,
                "installment_payment": [],
                "installment_status": "created",
                "installment_type": "principal",
                "original_due_principal": 103.56403553,
                "original_pre_fixed_amount": 7.49596447,
                "original_principal_amortization_amount": 103.56403553,
                "original_total_amount": 111.06,
                "paid_amount": 0,
                "paid_at": null,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 7.49596447,
                "principal_amortization_amount": 103.56403553,
                "qr_code_key": null,
                "qr_code_url": null,
                "renegotiation_proposal_key": null,
                "tax_amount": 0.5010428,
                "total_accrual_amount": null,
                "total_amount": 111.06,
                "total_paid_amount": 0,
                "workdays": 20
            }
        ],
        "total_pre_fixed_amount": 20.63
    }
}
```

## 5. Webhooks

After the successful response, you will receive a webhook with the signed CCB and a webhook indicating the disbursement's success or failure.

### Signature webhook

Response Body

```json
{
    "key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "status": "signature_finished",
    "webhook_type": "debt",
    "event_datetime": "2025-10-27 17:09:33",
    "signed_contract_url": "https://storage.googleapis.com/sandbox-doc-api/documents/c8b191cb-7b90-4e37-9280-397a597babc1/RAFAELAEBENJAMINFINANCEIRALTDA-ALAN_MATHISON_TURING-CCB-TIK11267101212-20251027170925_signed.pdf"
}

```

### Disbursement webhook

Response Body

```json
{
    "key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "data": {
      "installments": [
        {
          "due_date": "2025-11-27",
          "total_amount": 87.43,
          "installment_key": "e25fb146-0a61-4319-a722-d01b2213d0f9",
          "pre_fixed_amount": 29.26477451,
          "installment_number": 1,
          "principal_amortization_amount": 58.16522549
        },
        {
          "due_date": "2025-12-27",
          "total_amount": 87.43,
          "installment_key": "2557de2b-6df1-4a8a-b46a-59206ece157f",
          "pre_fixed_amount": 20.11446867,
          "installment_number": 2,
          "principal_amortization_amount": 67.31553133
        },
        {
          "due_date": "2026-01-27",
          "total_amount": 87.43,
          "installment_key": "cc503d1d-6387-4a1f-bd78-62b248d02ec8",
          "pre_fixed_amount": 11.07075682,
          "installment_number": 3,
          "principal_amortization_amount": 76.35924318
        }
      ],
      "ted_receipt_list": [],
      "requester_identifier_key": null
    },
    "status": "disbursed",
    "webhook_type": "debt",
    "event_datetime": "2025-10-27 17:10:21"
}

```

If the debt fails to disburse, or is returned, you will receive a cancellation webhook.

### Cancelation webhook

Response Body

```json
{
     "webhook_type": "debt",
     "key":"1ebd4a90-2721-4c39-a399-427fa16bca65",
     "event_datetime": "2025-10-27 16:38:59",
    "data": {
        "cancel_reason": "Operacao cancelada manualmente",
        "cancel_reason_enumerator": "manual"
    },
     "status":"canceled"
  }

```

****Cancelation reasons****

| cancel_reason_enumerator | Description |  
|---|---|  
|disbursing_error|Operation canceled due to an error during disbursement.  
|waiting_signature |Operation canceled due to missing signature. 
|pix_max_retry|Operation canceled because the receiving bank could not process the disbursement.  
|manual|Operation canceled manually.  
|agencia_conta_invalida|Invalid agency or recipient account number.  
|invalid_account|The destination account number is nonexistent or invalid.  
|invalid_document_number|The CPF/CNPJ of the destination account is incorrect.  
|unsupported_transaction|The destination account does not support this type of transaction.  
|invalid_ispb|The ISPB number is invalid or nonexistent.  
|rejected_payment|Payment order was rejected by the receiving bank.  
| refund_after_payee_request | Refund requested by the payee                                                |
| invalid_account            | The destination account number is nonexistent or invalid.                    |
| invalid_document_number    | The CPF/CNPJ of the destination account is incorrect.                        |
| rejected_payment           | Payment rejected by the receiving bank.                                      |
| blocked_account            | The destination account is blocked.                                          |
| unsupported_transaction    | The destination account does not support this type of transaction.           |
| amount_too_great           | Payment/refund amount exceeds the limit for the credited destination account. |
| invalid_ispb               | The ISPB number is invalid or nonexistent.                                   |
| receiver_error             | Transaction interrupted due to error on the receiver's PSP.                  |
| closed_account             | The destination account is closed.                                           |
| disbursing_hour_closed     | Disbursement occurred outside of the allowed time frame.                     |
| unregistered_pix_key       | The Pix key is not being used.                                               |
| manual                     | Operation manually canceled.                                                 |
| spi_timeout                | Timeout control in SPI.                                                     |

## 6. Cancellation

### Cancel debt before disbursement

### Request Body

ENDPOINT /debt/ DEBT-KEY /cancel
MÉTODO PATCH

Testar no Playground

### Path params

| Field  | Type   | Description | Max. Char. |
|---|---| ---| ---|
| `debt_key` * | string | Debt unique identifier key returned at the moment of the credit operation creation. | 32 |  

### Response Body

STATUS 200

Response Body

```json
{
  "data": [
    {
      "borrower": {
        "document_number": "68394265057",
        "name": "Xuxa Meneguel"
      },
      "contract_fee_amount": 5.56,
      "installments": [
        {
          "bank_slip_key": null,
          "calendar_days": 57,
          "due_date": "2020-09-30",
          "due_principal": -0.00217819,
          "fine_amount": null,
          "has_interest": true,
          "installment_key": "28eb5907-ed25-4a86-bb9d-b6dc944f13df",
          "installment_number": 1,
          "installment_status": "opened",
          "installment_type": "principal",
          "paid_amount": 0,
          "post_fixed_amount": 0,
          "pre_fixed_amount": 268.75782181,
          "principal_amortization_amount": 1111.9,
          "tax_amount": 0,
          "total_amount": 1380.66,
          "workdays": 40
        }
      ],
      "operation_key": "7986dcc7-4331-478f-af47-adfbdf7f4a36",
      "status": "opened"
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "rows_per_page": 100,
    "total_pages": 1,
    "total_rows": 55
  }
}

```

### Debt cancellation within seven days after disbursement

###  Request Body

ENDPOINT /debt/reversal
MÉTODO POST

Testar no Playground

Request Body

```json
{
    "contract_number": "0000049343/TW"
}

```

### Request Body Details
| Field  | Type   | Description | Max. Char. |
|-------------------|--------|--------------------------------|--------------|
| `contract_number` * | string | Contract Number of the CCB |              |

###  Response Body

STATUS 200

Response Body

```json
{
  "amount": "2026.93",
  "copy_paste_pix": "00020126930014br.gov.bcb.pix2571qrcode-h.dev.qitech.app/bacen/cobv/dece8d3e-32ce-439e-8204000053039865802BR5925Joao61080150400062070503***63046ECD",
  "expiration_date": "2022-09-28",
  "payer_document_number": "000000000008",
  "payer_name": "Teste",
  "reversal_key": "f98a1b7c-5e3c-4e6f-8887-c7fedfa0d5b5",
  "status": "waiting_payment"
}

```

## 7. Debt inquiry

You can query the debt later to retrieve information or track its current status:

ENDPOINT /v2/credit_operation/ CREDIT-OPERATION-KEY
METHOD GET

Testar no Playground

### Path params

| Field  | Type   | Description | Max. Char. |
|---|---|---|---|   
| `credit_operation_key` * | string |  Key of the credit operation | UUID |

### Response

STATUS 200

Response Body

```json
{
   "credit_operation_key":"31381158-e138-4aaa-99b7-f78356e71004",
   "issue_amount":201,
   "origin_key":"31381158-e138-4aaa-99b7-f78356e71004",
   "total_iof":1,
   "assigned_at":null,
   "disbursement_start_date":"2026-02-23",
   "disbursement_end_date":"2026-02-23",
   "issue_date":"2026-02-23",
   "requester_identifier_key":"12313asdjasdx998",
   "installments":[
      {
         "business_due_date":"2026-02-24",
         "due_date":"2026-02-24",
         "calendar_days":1,
         "due_interest":0,
         "due_principal":201,
         "fine_amount":0,
         "has_interest":true,
         "post_fixed_amount":0,
         "pre_fixed_amount":0.46,
         "principal_amortization_amount":103.45,
         "tax_amount":0.01,
         "total_amount":103.91,
         "workdays":1,
         "accrual_reference_date":null,
         "advanced_paid_amount":0,
         "bank_slip_key":null,
         "digitable_line":null,
         "installment_key":"cfd67eb8-cd1e-438b-8636-44cb94176515",
         "installment_status":"created",
         "installment_type":"principal",
         "original_due_principal":201,
         "original_pre_fixed_amount":0.46,
         "original_principal_amortization_amount":103.45,
         "paid_amount":0,
         "original_total_amount":103.91,
         "qr_code_key":null,
         "qr_code_url":null,
         "renegotiation_proposal_key":null,
         "total_accrual_amount":0,
         "total_paid_amount":0,
         "installment_number":1,
         "paid_at":null,
         "updated_at":null,
         "principal_amortization_payment_amount":0,
         "prefixed_interest_payment_amount":0
      },
      {
         "business_due_date":"2026-03-24",
         "due_date":"2026-03-24",
         "calendar_days":28,
         "due_interest":0,
         "due_principal":97.54761348,
         "fine_amount":0,
         "has_interest":true,
         "post_fixed_amount":0,
         "pre_fixed_amount":6.36,
         "principal_amortization_amount":97.55,
         "tax_amount":0.23,
         "total_amount":103.91,
         "workdays":20,
         "accrual_reference_date":null,
         "advanced_paid_amount":0,
         "bank_slip_key":null,
         "digitable_line":null,
         "installment_key":"445f1c2d-3967-4b23-9290-e19a0a5fb956",
         "installment_status":"created",
         "installment_type":"principal",
         "original_due_principal":97.55,
         "original_pre_fixed_amount":6.36,
         "original_principal_amortization_amount":97.55,
         "paid_amount":0,
         "original_total_amount":103.91,
         "qr_code_key":null,
         "qr_code_url":null,
         "renegotiation_proposal_key":null,
         "total_accrual_amount":0,
         "total_paid_amount":0,
         "installment_number":2,
         "paid_at":null,
         "updated_at":null,
         "principal_amortization_payment_amount":0,
         "prefixed_interest_payment_amount":0
      }
   ],
   "first_due_date":"2026-02-24",
   "requester_key":"3e69b448-9afb-4aef-9c0d-0a3059350d80",
   "original_total_iof":null,
   "contract_number":"TIK122710117",
   "credit_operation_status_enumerator":"issued",
   "operation_type_enumerator":"structured_operation",
   "disbursement_date":"2026-02-23",
   "issuer_name":"Alan Mathison Turing",
   "issuer_document_number":"46843213049",
   "external_contract_fees":[
      
   ],
   "cet":8.23,
   "annual_cet":158.43,
   "final_disbursement_amount":200,
   "number_of_installments":2,
   "disbursement_issue_amount":200,
   "prefixed_interest_rate":{
      "annual_rate":1.252191589,
      "daily_rate":0.0022578334,
      "interest_base":{
         "enumerator":"calendar_days",
         "year_days":360
      },
      "monthly_rate":0.07
   },
   "fine_configuration":{
      "contract_fine_rate":0.02,
      "fine_delay_rate":{
         "annual_rate":4.35025011,
         "daily_rate":0.0046696,
         "interest_base":{
            "enumerator":"calendar_days",
            "year_days":360
         },
         "monthly_rate":0.15
      }
   },
   "attached_documents":[
      {
         "document_key":"494598fd-c226-4332-a500-591ae3884673",
         "document_url":"https://storage.googleapis.com/sandbox-doc-api/documents/494598fd-c226-4332-a500-591ae3884673/3d684e68e7df4e557d0480d98e2692.jpg",
         "signature_url":null,
         "document_type":"document_identification",
         "signature_required":false,
         "signed":false
      },
      {
         "document_key":"494598fd-c226-4332-a500-591ae3884673",
         "document_url":"https://storage.googleapis.com/sandbox-doc-api/documents/494598fd-c226-4332-a500-591ae3884673/3d684e68e7df4e557d0480d98e2692.jpg",
         "signature_url":null,
         "document_type":"document_identification_back",
         "signature_required":false,
         "signed":false
      },
      {
         "document_key":"73584aa0-91d4-483b-a95c-1b0263c14126",
         "document_url":"https://storage.googleapis.com/sandbox-doc-api/documents/73584aa0-91d4-483b-a95c-1b0263c14126/CASTELLOBNPL-ALAN_MATHISON_TURING-CCB-TIK122710117-202602241151.pdf",
         "signature_url":"https://storage.googleapis.com/sandbox-doc-api/documents/73584aa0-91d4-483b-a95c-1b0263c14126/CASTELLOBNPL-ALAN_MATHISON_TURING-CCB-TIK122710117-202602241151_signed.pdf",
         "document_type":"ccb_pre_price_days",
         "signature_required":true,
         "signed":true
      }
   ],
   "related_parties":[
      {
         "related_party_key":"fe133e90-9ee6-401a-a5a4-7d415ecb04fd",
         "role_type":"issuer",
         "person_type":"natural",
         "name":"Alan Mathison Turing",
         "email":"weiwenqian.wayne@bytedance.com",
         "individual_document_number":"46843213049"
      }
   ],
   "base_iof":0.24,
   "additional_iof":0.76,
   "assignment_amount":201.6,
   "total_prefixed_amount":6.82
}
```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

You can also query the debt later to retrieve the log of events status:

ENDPOINT /v2/credit_operation/ CREDIT-OPERATION-KEY /events
METHOD GET

CREDIT-OPERATION-KEY /events">Testar no Playground

### Path params

| Field  | Type   | Description | Max. Char. |
|---|---|---|---|   
| `credit_operation_key` * | string | Key of the credit operation | UUID |

### Response

STATUS 200

Response Body

```json
{
  "data": [
    {
      "status": "waiting_signature",
      "reason": null,
      "cancel_reason": null,
      "event_date": "2026-03-13T17:19:59Z"
    },
    {
      "status": "issued",
      "reason": null,
      "cancel_reason": null,
      "event_date": "2026-03-13T17:19:59Z"
    },
    {
      "status": "waiting_disbursement",
      "reason": null,
      "cancel_reason": null,
      "event_date": "2026-03-13T17:19:59Z"
    },
    {
      "status": "opened",
      "reason": null,
      "cancel_reason": null,
      "event_date": "2026-03-13T17:19:59Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "rows_per_page": 10
  }
}
```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

## 8. Assignment Inquiry

###  Assignment Confirmation Webhook
This webhook is triggered to notify the client that the assignment process has been initiated. It provides the essential metadata required to track the assignment.

Response Body

```json
{
   "key":"b866dc02-73db-42a4-bc66-866d465cbb73",
   "webhook_type":"assignment.status_change",
   "event_datetime":"2026-03-09T19:47:00Z",
   "data":{
      "assignment_key":"550e8400-e29b-41d4-a716-446655440000",
      "term_of_assignment_url":"[https://api.sistema.com.br/terms/7742.pdf](https://api.sistema.com.br/terms/7742.pdf)",
      "number_of_items":1,
      "total_amount":100,
      "reference_date":"2026-03-01"
   }
}

```

|Field|Type|Description|Maximum lenght|
|---|---|---|---|
|assignment_key|string|Unique identifier for the assignment operation|36|
|term_of_assignment_url|string| URL to download the Term of Assignment (PDF)|2048|
|number_of_items|integer|Total number of credit operations (items) included in this assignment|5|
|total_amount|float|The sum of the present value of all items in the assignment|15,2|
|reference_date|string|The base date used for the assignment calculations (YYYY-MM-DD)|10|

To query a specific assignment, the client can perform a GET request on the endpoint using the assignment identifier key (assignment_key).

###  Request Body

ENDPOINT /v2/assignment/[assignment_key] METHOD GET

Testar no Playground

### Params

| Field            | Descrição                      |
| ---------------- | ------------------------------ |
| `assignment_key` | Assignment unique identifier key |

### Response

STATUS 200

Response Body

```json
{
"assignment_key": "77997168-5d61-430f-b5ae-08eb3d7b8c0e",
"creation_datetime": "2023-10-01T12:00:00",
"reference_date": "2023-10-01",
"total_amount": 120000,
"number_of_items": 5,
"term_of_assignment_url": "https://example.com/assignment.pdf",
"status": "settled",
"signable_term_url": "https://example.com/signable_term.pdf"
}
```

To query the contracts within an assignment, use a GET request on the endpoint with the same **assignment_key**.

### Request Body

ENDPOINT /v2/assignment/[ASSIGNMENT_KEY]/assignment_items?page=1&page_size=100 METHOD GET

Testar no Playground

### Path Params

| Field      | Type    | Description    | 
|-----------------|---------|----------------|
| `assignment_key` | string |Assignment unique identifier key |

### Query Params

| Field      | Type    | Description    | 
|-----------------|---------|----------------|
| `page` | string |Number of the page |
| `page_size` | string | Length of the page, limited by 100 |

The response is a paginated list containing information for each contract in the assignment (status 200):

### Response Body

STATUS 200

Response Body

```json
{
        "pagination": {
            "page": 1,
            "page_size": 10
        }
        "data": [
        {
                "assignment_date": date,
        "assignment_item_key": uuid,
        "contract_number": "TIK000012312",
        "control_number": "TIK000012312",
        "requester_identifier_key": uuid,  -> including this field
        "credit_operation_key": string,
        "disbursed_amount": 80.0,
        "disbursement_date": date,
        "endorsement_url": url,
        "issue_amount": 180.00,
        "issuer_document_number": string,
        "issuer_name": string,
        "number_of_installments": 10,
        "present_amount": 180.0,
        "contract_present_amount": 180.0,
        "purchaser_document_number": string,
        "status": "settled/canceled",
        "rejected_reasons": []
        "assignment_items": [
            {
                "installment_key": uuid,
                "present_amount": 100,
                "due_date": date,
                "your_number": "TIK000012312001"
            },
            {
                "installment_key": uuid,
                "present_amount": 80,
                "due_date": date,
                "your_number": "TIK000012312002"
            }
        ]
      }
    ]
}
```

Query the assigment batchs by the **assignment_date**.

### Request Body

ENDPOINT /v2/assignments?reference_date METHOD GET

Testar no Playground

### Query Params

| Field                             | Type    | Description                                                                      | 
|-----------------------------------|---------|--------------------------------------------------------------------------------|
| `reference_date` |string| Date of assignment attempt |

### Response Body

STATUS 200

Response Body

```json
{"data": [{
      "assignment_key": "439b1257-82ac-4741-a416-a4428a9a7327",
      "number_of_items": 10000,
      "reference_date": "2025-01-01",
      "signable_term_url": "https://example.com/endorsement.pdf",
      "status": "settled",
      "term_of_assignment_url": "signed_url",
      "total_amount": 100.00,
  },
  {
      "assignment_key": "439b1257-82ac-4741-a416-a4428a9a7327",
      "number_of_items": 10000,
      "reference_date": "2025-01-01",
      "signable_term_url": "https://example.com/endorsement.pdf",
      "status": "settled",
      "term_of_assignment_url": "signed_url",
      "total_amount": 100.00,
  },
  {
      "assignment_key": "439b1257-82ac-4741-a416-a4428a9a7327",
      "number_of_items": 10000,
      "reference_date": "2025-01-01",
      "signable_term_url": "https://example.com/endorsement.pdf",
      "status": "canceled",
      "term_of_assignment_url": "signed_url",
      "total_amount": 100.00,
  }
  ]}
```

## 9. Refund Flow

###  Refund
This webhook is triggered to notify the client that the assignment process has been initiated. It provides the essential metadata required to track the assignment.
About the amortization_type, defines the amortization strategy for the renegotiation proposal. Use full_settle to request a total refund (full settlement of the debt) or equal_amount to process partial refunds based on a specific payment value.

### Query Params

| Field                             | Type    | Description                                                                      | 
|-----------------------------------|---------|--------------------------------------------------------------------------------|
| debt_key | string | Unique identifier (UUID) of the debt or credit operation to be renegotiated. |
| payment_type | string | The type of payment for the renegotiation (e.g., internal). |
| amortization_type | string | Method of amortization. Possible values: full_settle or equal_amount. |
| reference_date | string | Reference date for calculating values and projections (format YYYY-MM-DD). |
| payment_amount | number | Total amount to be paid in the renegotiation proposal. |
| account_key | string | Unique identifier (UUID) of the account associated with the payment. |
| request_control_key | string | Idempotency key (UUID) used to prevent duplicate requests for the same operation. |

ENDPOINT /renegotiation/proposal
MÉTODO POST

Request Body

**Full Refund**

```json
{
  "debt_key": "c0e4a0a3-98aa-47b5-a1db-f2c63bf1fe16",
  "payment_type": "internal",
  "amortization_type": "full_settle",
  "reference_date": "2025-10-20",
  "payment_amount": 1000,
  "account_key": "eaf3ad19-a2a5-41be-a646-c910dc92429f",
  "request_control_key": "eaf3ad19-a2a5-41be-a646-c910dc92429f"
}
```

**Partial Refund**

 ```json
{
  "debt_key": "c0e4a0a3-98aa-47b5-a1db-f2c63bf1fe16",
  "payment_type": "internal",
  "amortization_type": "equal_amount",
  "reference_date": "2025-10-20",
  "payment_amount": 1000,
  "account_key": "eaf3ad19-a2a5-41be-a646-c910dc92429f",
  "request_control_key": "eaf3ad19-a2a5-41be-a646-c910dc92429f"
}
 ```

### Response Body

STATUS 200

Response Body

```json
{
  "contract_number": "0000281416/NDR",
  "discount_percentage": 0,
  "discount_amount": 0,
  "amortization_type": "full_settle",
  "payment_amount": 50,
  "requester_name": "Ali Pay",
  "requester_key": "a29eb3a6-f278-4b09-95df-f52b789ee120",
  "origin_key": "6f9743be-b58a-46c9-9460-478e718848b6",
  "issuer_name": "NOME DO REPRESENTANTE",
  "issuer_document_number": "31057466093",
  "affected_installments": [{
    "installment_key": "f73bc15a-0075-4c5d-bb0d-e364ec55ff5b",
    "due_date": "2025-11-20",
    "principal_amount": 0.08,
    "interest_amount": 5.19,
    "fine_amount": 0,
    "total_amount": 5.27,
    "present_amount": 5.27,
    "paid_amount": 5.94,
    "principal_amortization_payment_amount": null,
    "prefixed_interest_payment_amount": null
  }, {
    "installment_key": "3ddb34d5-f63b-4238-945f-e89661cb628d",
    "due_date": "2025-12-20",
    "principal_amount": 0.1,
    "interest_amount": 3.57,
    "fine_amount": 0,
    "total_amount": 3.68,
    "present_amount": 3.68,
    "paid_amount": 7.53,
    "principal_amortization_payment_amount": null,
    "prefixed_interest_payment_amount": null
  }, {
    "installment_key": "2e018153-51fa-4d04-b5df-8ff1570f8dc5",
    "due_date": "2026-01-20",
    "principal_amount": 0.11,
    "interest_amount": 3.07,
    "fine_amount": 0,
    "total_amount": 3.18,
    "present_amount": 3.18,
    "paid_amount": 8.03,
    "principal_amortization_payment_amount": null,
    "prefixed_interest_payment_amount": null
  }, {
    "installment_key": "4dc7d6f3-cd70-4425-84ad-e59348c9b1b0",
    "due_date": "2026-02-20",
    "principal_amount": 0.12,
    "interest_amount": 2.39,
    "fine_amount": 0,
    "total_amount": 2.51,
    "present_amount": 2.51,
    "paid_amount": 8.7,
    "principal_amortization_payment_amount": null,
    "prefixed_interest_payment_amount": null
  }, {
    "installment_key": "eda0e9c0-d7d7-4249-9087-b6dfe0f48941",
    "due_date": "2026-03-20",
    "principal_amount": 0.13,
    "interest_amount": 1.49,
    "fine_amount": 0,
    "total_amount": 1.63,
    "present_amount": 1.63,
    "paid_amount": 9.58,
    "principal_amortization_payment_amount": null,
    "prefixed_interest_payment_amount": null
  }, {
    "installment_key": "0ae280f4-8697-4956-ad36-7fd49a757334",
    "due_date": "2026-04-20",
    "principal_amount": 0.14,
    "interest_amount": 0.85,
    "fine_amount": 0,
    "total_amount": 1,
    "present_amount": 1,
    "paid_amount": 10.21,
    "principal_amortization_payment_amount": null,
    "prefixed_interest_payment_amount": null
  }],
  "remaining_installments": [],
  "proposal_key": "c01e5d06-fcde-40b4-a0c8-5930c54d222c",
  "proposal_status": "paid",
  "payment_type": "internal",
  "payment": {
    "digitable_line": null,
    "qr_code_url": null,
    "qr_code_key": null,
    "bank_slip_key": null,
    "paid_method_type": "internal",
    "source_account_key": "5d068423-6094-49e4-b15b-7740038295a8",
    "payment_data": {
      "target_account_key": "5d068423-6094-49e4-b15b-7740038295a8",
      "transaction_amount": 50
    }
  },
  "proposal_due_date": "2025-10-13",
  "reference_date": "2025-10-13",
  "devolution_amount": 0
}
```

## 10. Ordinary Repayment Flow

###  Standard Payment
For the ordinary installment repayment flow, please refer to the following link: [Renegociação em lote](/documentation/renegociacao/renegociacao_em_lote).

## 11. Technical Specifications and Enums

### Fees Object
| Field           | Type  | Description                                                                                           |
|-----------------|-------|-----------------------------------------------------------------------------------------------------|
| **amount**      | float | Fee amount (in percentage or absolute value, depending on the value provided in the amount_type field)| -            |
| **amount_type** | enum  | Fee value unit                   |  **[Amount Type Enumerator](#amount-type-enumerator)**             |
| **fee_amount**  | float | Absolute value of the fee charged in the operation                                                           | -            |
| **fee_type**    | string  | Type of fee charged in the operation                   | **[Fee Type Enumerator](#fee-type-enumerator)**          |
| **type**        | string  |  Source of the fee charged in the operation                         | **[Origin Type Enumerator](#origin-type-enumerator)**          |

### Installments Object
| Field                             | Type    | Description                                                                      | 
|-----------------------------------|---------|--------------------------------------------------------------------------------|
| **calendar_days**                 | integer    | Number of calendar days between installments                                | -            |
| **due_date**                      | string    | Installment due date in calendar days                                   | -            |
| **due_principal**                 | float   | Remaining principal on the installment due date before its payment | -            |
| **has_interest**                  | boolean | _true_ - If true, interest applies to the installment                           | -            |
| **installment_number**            | integer    | Installment number                                                              | -            |
| **prefixed_amount**               | float   | Fixed interest amount paid on the installment                                      | -            |
| **principal_amortization_amount** | float   | Principal amount paid on the installment                                           | -            |
| **tax_amount**                    | float   | Base IOF amount of installment                                                            | -            |
| **amount**                        | float   | Installment total value                                                         | -            |
| **due_interest**                  | float     | Remaining interest after the installment due date before its payment                                   | -            |
| **period**                        | float     | Installment period | -            |
| **period_workdays**               | float     | Installment period in business days | -            |
| **period_to_disbursement**        | float     | Period until disbursement | -            |
| **period_workdays_to_disbursement**| float     | Business days until disbursement | -            |
| **calendar_days_to_disbursement** | integer    | Calendar days to disbursement | -            |
| **workdays**                      | integer    | Business days between installments | -            |
| **workdays_to_disbursement**      | integer    | Business days until disbursement | -            |

### Interest Rate Object
| Field             | Description                                                                             | 
|-------------------|---------------------------------------------------------------------------------------|
| **annual_rate**   | Annual fixed/floating interest rate expressed as a decimal                                      | -            |
| **daily_rate**    | Daily fixed/floating interest rate expressed as a decimal                                      | -            |
| **interest_base** | **[Interest Base Enumerator](#interest-base-enumerator)** - Interest calculation basis  | -            |
| **monthly_rate**  | Monthly fixed/floating interest rate expressed as a decimal                                      | -            |

### Tax Configuration Object
| Field                 | Description                                                                             | 
|-----------------------|---------------------------------------------------------------------------------------|
| **base_rate**         | Base IOF rate value                                                                | -            |
| **additional_rate**   | Additional IOF rate value                                                           | -            |

### Enumeratores

### Person Type Enumerator
| Enumerator             | Description             |
|------------------------|-----------------------|
| **legal**              | Legal person       |
| **natural**            | Natural person          |

### Account Type Enumerator
| Enumerator             | Description             |
|------------------------|-----------------------|
| **checking_account**   | Checking account        |

### Amount Type Enumerator
| Enumerator             | Description             |
|------------------------|-----------------------|
| **absolute**           | Absolute value        |
| **percentage**         | Percentage value      |

###  Interest Type Enumerator
| Enumerator           | Description                                                                                                                                                                |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **pre_price_days**   | Price amortization method (equal installments) with daily fixed-rate interest calculation                                                                                     |
| **pre_price**        | Price amortization method (equal installments) with fixed-rate interest calculation over 30-day periods                                                                |

### Credit Operation Type Enumerator 
| Enumerator    | Description                      |
|---------------|--------------------------------|
| **ccb**       | Bank Credit Note    |

### Interest Base Enumerator 
| Enumerator            | Description                                                                 |
|-----------------------|---------------------------------------------------------------------------|
| **workdays**          | Interest calculation basis in business days, assuming a 252-day year    |
| **calendar_days**     | Interest calculation basis in calendar days, assuming a 360-day year |
| **calendar_days_365** | Interest calculation basis in calendar days, assuming a 365-day year |

###  Fee Type Enumerator
Each fee type must be previously enabled and configured by QI Tech

| Enumerator            | Description                                                                  |
|-----------------------|----------------------------------------------------------------------------|
| **spread**            | Premium included in the credit operation's acquisition value                  |
| **spread_ted_fee**    | Premium on the TED transfer fee |

### Origin Type Enumerator
Each fee type must be previously enabled and configured by QI Tech

| Enumerator            | Description                                                                  |
|-----------------------|----------------------------------------------------------------------------|
| **internal**          | Internal fee                                                   |
| **external**          | External fee                                                   |

---

# Homologation Roadmap - BNPL

URL: /documentation/manual_bnpl_ecommerce/

## Summary
This document guides clients through integrating Buy Now Pay Later (BNPL) with the QI Tech platform. It outlines the essential steps and provides answers to common questions.

## 1. Document Inquiry
The document inquiry can be performed using the following request:

### Request Body Upload

ENDPOINT /document/[document_key]/url
METHOD GET

Testar no Playground

### Path Params

| Field          | Description                              |
|--------------- |------------------------------------------|
| `document_key` | Unique document key                      |

:::caution Attention
The document URL will be generated with an expiration period of 10 minutes.
:::

Response Body

```json
{
	"document_key": "8a1e62f3-7add-4240-a51d-e0f1a2f421fa",
	"document_url": "expirable_url",
	"signed_document_url": "expirable_url",
	"expiration_datetime": "2024-05-01T01:00:00.000Z"
}
```

## 2. Document upload
To receive the document_key for the debt issuance documents, you must upload them using the following request:

### Request Body Upload

ENDPOINT /upload
METHOD POST

Testar no Playground

Response Body

```json
{
  "document_key": "cfbc8469-89ea-4a80-9f64-ba7b1566c68b",
  "document_md5": "cd451103fa512frc98ce684d3896698c"
}
```

:::caution Atenção
Remember to save the **document_key**, as this key is required to query the document.
:::

### API call example

Example for uploading an image from a URL.

**Python**

```python

import jwt
import hashlib
import requests
from requests_toolbelt.multipart.encoder import MultipartEncoder
import json
from datetime import datetime

BASE_URL = "https://api-auth.sandbox.qitech.app"
API_KEY = "4c268c0a-53ff-429b-92b6-47ef98a6d89a" # This key is an example; please use your own key.
CLIENT_PRIVATE_KEY = ''''
-----BEGIN EC PRIVATE KEY-----
MIHbAgEBBEHh1hIeOPE5XNNhn6bxRAmVswsPZ0wZCmzVvP8Tl/LZK9ofVmRVGzll
srU1uezJEyHKYdOHrE2p52xUj+pHzjJvb6AHBgUrgQQAI6GBiQOBhgAEAAofUz1J
hBSOyGHLsnV9Sz0DSWmhl7U+ljqbfa8PKVFWSV3w16I1v2zME5/UzUhHn1gWsjnv
7/ekcLLAQbvqMPNXAfjIhFXLAPzqbB9iCuVua1v0Vgy52rBemOWrJka/Ws2bnKR8
h1N1OxOYeYr6C2jqMygBLktKMAs+282CEiEb4bIv
-----END EC PRIVATE KEY----- 
''' # This key is an example; please use your own key.

def get_document(url):
    try:
        response = requests.get(url)
        return response.content
    except Exception as error:
        print("Error fetching document:", error)
        raise

def upload_document(array_buffer):
    endpointeger= "/upload"
    method = "POST"
    timestamp = datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
    md5_hash = hashlib.md5(array_buffer).hexdigest()

    jwt_header = {
        "typ": "JWT",
        "alg": "ES512",
    }

    jwt_body = {
        "payload_md5": md5_hash,
        "timestamp": timestamp,
        "method": method,
        "uri": endpoint,
    }

    encoded_header_token = jwt.encode(jwt_body, CLIENT_PRIVATE_KEY, algorithm="ES512", headers=jwt_header)

    signed_header = {
        "Authorization": encoded_header_token,
        "API-CLIENT-KEY": API_KEY,
        "Content-Type": "multipart/form-data",
    }

    url = f"{BASE_URL}{endpoint}"
    multipart_data = MultipartEncoder(
        fields={'file': ('image.jpeg', array_buffer, 'image/jpeg')}
    )
    signed_header['Content-Type'] = multipart_data.content_type

    try:
        response = requests.post(url, headers=signed_header, data=multipart_data)
        response_data = response.json()
        document_key = response_data.get('document_key')
        print(f'Response data is: {response_data} and document_key is: {document_key}')
        return document_key
    except Exception as error:
        print('Error:', error)
        raise

def main():
    file_url = "{FILE_URL}"

    document_buffer = get_document(file_url)

    document_key = upload_document(document_buffer)

    print("document_key is", document_key)

if __name__ == "__main__":
    main()

```
  

**Node.js**

```js
const jwt = require('jsonwebtoken')
const crypto = require('crypto')
const axios = require('axios')
const FormData = require('form-data')
const fs = require('fs')
const fetch = require('node-fetch')

async function getDocument(url) {
  try {
    const response = await axios.get(url, { responseType: 'arraybuffer' })
    return response.data
  } catch (error) {
    console.error('Error fetching document:', error)
    throw error
  }
}

async function uploadDocument(arrayBuffer) {
  const endpointeger= '/upload'
  const method = 'POST'
  const timestamp = new Date().toISOString()
  const md5_hash = crypto.createHash('md5').update(arrayBuffer).digest('hex')
  const client_private_key = `-----BEGIN EC PRIVATE KEY-----
    MIHbAgEBBEHh1hIeOPE5XNNhn6bxRAmVswsPZ0wZCmzVvP8Tl/LZK9ofVmRVGzll
    srU1uezJEyHKYdOHrE2p52xUj+pHzjJvb6AHBgUrgQQAI6GBiQOBhgAEAAofUz1J
    hBSOyGHLsnV9Sz0DSWmhl7U+ljqbfa8PKVFWSV3w16I1v2zME5/UzUhHn1gWsjnv
    7/ekcLLAQbvqMPNXAfjIhFXLAPzqbB9iCuVua1v0Vgy52rBemOWrJka/Ws2bnKR8
    h1N1OxOYeYr6C2jqMygBLktKMAs+282CEiEb4bIv
    -----END EC PRIVATE KEY-----`; // This key is an example; please use your own key.
  const api_key = '4c268c0a-53ff-429b-92b6-47ef98a6d89a' // This key is an example; please use your own key.

  try {
    const jwt_header = {
      typ: 'JWT',
      alg: 'ES512',
    }

    const jwt_body = {
      payload_md5: md5_hash,
      timestamp: timestamp,
      method: method,
      uri: endpoint,
    }

    const encoded_header_token = jwt.sign(jwt_body, client_private_key, {
      algorithm: 'ES512',
      header: jwt_header,
    })

    const signed_header = {
      AUTHORIZATION: encoded_header_token,
      'API-CLIENT-KEY': api_key,
      'Content-Type': 'multipart/form-data',
    }

    const url = `${base_url}${endpoint}`
    const formData = new FormData()
    formData.append('file', Buffer.from(arrayBuffer), {
      filename: 'image.jpeg',
    })

    fetch(url, {
      method: 'POST',
      headers: signed_header,
      body: formData,
    })
      .then(data => {
        console.log('Response data is: ' + data)

        return data.document_key
      })
      .catch(error => {
        console.log('Error: ' + error)
      })
  } catch (error) {
    console.error('Error:', error)
  }
}

async function main() {
  const fileUrl = '<URL_LINK_TO_DOCUMENT_IMAGE>'
  const documentBuffer = await getDocument(fileUrl)
  const documentKey = await uploadDocument(documentBuffer)

  console.log('Document key is: ' + documentKey)
}

main()
```

- OBS: The example above uses the library [node-fetch](https://www.npmjs.com/package/node-fetch) to make the call, but you can use the library of your choice. The important thing is that the call must be made using the POST method, with the `Content-Type` header set to `multipart/form-data` and the body must be a FormData object with the key `file` and the value as the file binary to be sent.

:::warning Aviso
The 'Axios' library has a bug that causes FormData to be sent empty. The issue can be seen on the [GitHub repository](https://github.com/axios/axios/issues/5986). If this problem has not yet been resolved at the time of your integration, we suggest using the 'node-fetch' library to make this call.
:::

  

## 3. Debt Simulation

### Request Debt Simulation

At QI Tech, we provide our clients with the ability to simulate the values of a credit operation before it is actually issued. The simulation follows the same pattern as the debt issuance request, but it is not necessary to provide the debtor’s registration and disbursement account details. The following endpoint is a simplified version of /debt_simulation, but much more optimized. It is used to calculate only one disbursement option.

ENDPOINT /v2/credit_operation/simulation
METHOD POST

Testar no Playground

Request Body

```json
{
    "credit_operation_type": "ccb",
    "disbursed_issue_amount": 2800,
    "disbursement_date": "2025-09-24",
    "first_due_date": "2025-10-24",
    "force_installments_on_workdays": true,
    "interest_type": "pre_price_days",
    "issuer_person_type": "natural",
    "monthly_interest_rate": 0.04488,
    "number_of_installments": 12,
    "principal_amortization_month_period": 1
}
```

### Request Body Details

| Field  | Type   | Description | Max. Char. |
|---|--- |---|---|
| **credit_operation_type***                 | string    |   Type of credit agreement      |  **[Credit Operation Type Enumerator](#credit-operation-type-enumerator)**           |
| **disbursed_issue_amount***                | float   | The value actually released to the borrower      | 15,2           |
| **disbursement_date***                     | string    | The specific date the loan funds are made available      | 10            |
| **first_due_date***                        | string    | Due date of the first installment      | 10             |
| **force_installments_on_workdays***        | boolean | If true, ensures all installment due dates are moved to the next business day  |       5       |
| **interest_type***                         | string    |  Amortization method      | **[Interest Type Enumerator ](#interest-type-enumerator)**           |
| **issuer_person_type***                    | string    | Defines whether the issuer is an individual (natural person) or a legal entity (corporation/business)     | **[Person Type Enumerator](#person-type-enumerator)**           |
| **monthly_interest_rate***                 | float   |The percentage charged on a principal balance over a one-month period    | 10,6           |
| **number_of_installments***                | integer    | Number of installments      | 3            |
| **principal_amortization_month_period***   | integer    | Period, in months, between installments      | 1            |

### Response Debt Simulation

STATUS 200

Response Body

```json
    {
        "disbursement_date": "2025-09-24",
        "issue_amount": 2821.32,
        "interest_type": "pre_price_days",
        "assignment_amount": 2829.78,
        "base_iof": 10.6,
        "total_iof": 21.32,
        "additional_iof": 10.72,
        "cet": 5.09,
        "annual_cet": 81.39,
        "first_due_date": "2025-10-24",
        "disbursed_amount": 2800,
        "prefixed_interest_rate": {
            "annual_rate": 0.6935459998,
            "daily_rate": 0.0014644728,
            "interest_base": "calendar_days",
            "monthly_rate": 0.04488
        },
        "tax_configuration": {
            "base_rate": 8.2e-05,
            "additional_rate": 0.0038
        },
        "fees": [
            {
                "amount": 0.3,
                "fee_amount": 8.46,
                "amount_type": "percentage",
                "fee_type": "spread",
                "type": "internal"
            }
        ],
        "installments": [
            {
                "due_date": "2025-10-24",
                "amount": 1507.4,
                "due_principal": 2821.32,
                "due_interest": 0,
                "has_interest": true,
                "period": 1,
                "period_workdays": 1.1,
                "calendar_days": 30,
                "workdays": 22,
                "installment_number": 1,
                "period_to_disbursement": 1,
                "prefixed_amount": 126.62083829,
                "period_workdays_to_disbursement": 1.1,
                "calendar_days_to_disbursement": 30,
                "workdays_to_disbursement": 22,
                "tax_amount": 3.39671674,
                "principal_amortization_amount": 1380.77916171
            },
            {
                "due_date": "2025-11-24",
                "amount": 1507.4,
                "due_principal": 1440.54083829,
                "due_interest": 0,
                "has_interest": true,
                "period": 1,
                "period_workdays": 1,
                "calendar_days": 31,
                "workdays": 20,
                "installment_number": 2,
                "period_to_disbursement": 2,
                "prefixed_amount": 66.85916171,
                "period_workdays_to_disbursement": 2.1,
                "calendar_days_to_disbursement": 61,
                "workdays_to_disbursement": 42,
                "tax_amount": 7.20558527,
                "principal_amortization_amount": 1440.54083829
            }
        ]
    }
```

### Response Body Details
| Field                                   | Type   | Description                                                                                                                     |
|-----------------------------------------|--------|-------------------------------------------------------------------------------------------------------------------------------|
| **annual_cet**                          | float  | Total effective cost expressed as a decimal per year                                                                                | -            |
| **assignment_amount**                   | float  | Acquisition value of the credit operation                                                                                     | -            |
| **cet**                                 | float  | Total effective cost expressed as a decimal per month                                                                                | -            |
| **fees**                                | object | **[Object Fees](#object-fees)** - List of QI Tech fees charged on the operation                            | -            |
| **disbursed_amount**                    | float  | Amount disbursed in the credit operation                                                                                     | -            |
| **disbursement_date**                   | string   | Disbursement date of the operation                                                                                                | -            |
| **installments**                        | array   | **[Object Installments](#object-installments)** - Installments of the operation                                                        | -            |
| **interest_type**                       | string   | **[Enumerator Interest Type](#enumerator-interest-type)** - Amortization method and interest calculation method                 | -            |
| **additional_iof**                      | float  |A fixed-rate tax applied to the transaction principal, independent of the duration of the credit operation                                                                               | -            |
| **base_iof**                            | float  |  The taxable amount or principal value used as the basis for calculating the Tax on Financial Operations  | -            |
| **total_iof**                           | float  | The total amount of Tax on Financial Operations applied to the transaction   | -            |
| **issue_amount**                        | float  | Issue/nominal value of the credit operation                                                                               | -            |
| **tax_configuration**                   | object | **[Object Tax Configuration](#object-tax-configuration)** - Rate iof values                                             | -            |
| **first_due_date**                      | string   | Due date of the first installment                                                                                        | -            |
| **prefixed_interest_rate**              | object | **[Object Interest Rate](#object-interest-rate)** - Nominal interest rate                              | -            |

## 4. Debt issuance for natural persons

This endpoint issues the debt and processes the contract signature via opt-in. Disbursement occurs automatically immediately after issuance. Pre-registration is not required; simply provide the borrower's details during the debt request.

### Request

ENDPOINT /signed_debt
METHOD POST

Testar no Playground

Request Body

```json
{
   "additional_data":{
      "contract":{
         "contract_number":"TIK11267101100",
         "signed":true,
         "signatures":[
            {
               "signer":{
                  "name":"Alan Mathison Turing",
                  "phone":{
                     "number":"912345678",
                     "area_code":"11",
                     "country_code":"055"
                  },
                  "email":"alan.turing@email.com",
                  "document_number":"96969879003"
               },
               "signature":{
                  "ip_address":"168.211.22.84",
                  "timestamp":"27-10-2025 11:07:15",
                  "signature_file":{
                     "file_url":"http://qitech.com.br/signature.pdf",
                     "file_type":"pdf"
                  },
                  "geolocation":{
                     "long":"-46.63611",
                     "lat":"-23.5475"
                  },
                  "fingerprint_device":{
                     "device":"Web",
                     "model":"iPhone 11",
                     "os_version":"iOS 15.2",
                     "browser":"Chrome",
                     "browser_version":"120.0.0.0",
                     "language":"pt-BR",
                     "timezone":"America/Sao_Paulo",
                     "gpu_renderer":"Apple GPU"
                  }
               }
            }
         ]
      }
   },
   "financial":{
      "number_of_installments":2,
      "credit_operation_type":"ccb",
      "interest_type":"pre_price_days",
      "monthly_interest_rate":0.07,
      "disbursed_amount":200,
      "fine_configuration":{
         "contract_fine_rate":0.02,
         "monthly_rate":0.15,
         "interest_base":"calendar_days"
      },
      "interest_grace_period":0,
      "disbursement_date":"2026-02-06",
      "first_due_date":"2026-03-06",
      "principal_grace_period":0
   },
   "disbursement_bank_accounts":[
      {
         "account_digit":"5",
         "document_number":"32402502000135",
         "bank_code":"329",
         "account_number":"00002",
         "percentage_receivable":100,
         "branch_number":"0001",
         "name":"Accout Name"
      }
   ],
   "requester_identifier_key":"6b558426-6b6c-4c9e-bfb3-5734fe45a651",
   "purchaser_document_number":"32402502000135",
   "borrower":{
      "email":"alan.turing@email.com",
      "document_identification":"494598fd-c226-4332-a500-591ae3884673",
      "document_identification_back":"494598fd-c226-4332-a500-591ae3884673",
      "birth_date":"1990-11-20",
      "person_type":"natural",
      "is_pep":false,
      "profession":"Public server",
      "individual_document_number":"96969879003",
      "address":{
         "city":"São Paulo",
         "neighborhood":"CENTRO",
         "street":"Avenida Feliz",
         "complement":"AP 801",
         "postal_code":"49026100",
         "state":"SP",
         "number":"1000"
      },
      "phone":{
         "country_code":"055",
         "number":"912345678",
         "area_code":"11"
      },
      "mother_name":"MARIA TURING",
      "document_identification_number":"96969879003",
      "name":"Alan Mathison Turing"
   }
}
```

### Request Body Details

| Field  | Type   | Description | Max. Char. |
|---|--- |---|---|
| **borrower** *                  | object | Borrower Object - The debtor of the credit operation         | **[Borrower Object](#borrower-object)** |
| **disbursement_bank_account** * | object |  Technical details of the bank account where the operation funds will be deposited.                                                                                 | **[Disbursement Bank Account Object](#disbursement-bank-account-object)**          |
| **financial** *                 | object | Contains all financial details and calculation parameters for the operation. | **[ Financial Object](#financial-object)**            |
| **purchaser_document_number** * | string | Assignee's Tax ID – The buyer of the credit operation (FIDC/Receivables Investment Fund).   | 14           |
| **additional_data** * | object | Assignee's Tax ID – The buyer of the credit operation (FIDC/Receivables Investment Fund).   | **[ Additional Data Object](#additional-data-object)**          |

### Borrower Object 

|Field|Type|Description|Max. Char.|
|---|--- |---|---|
|name *|string|Full name of the borrower|100|
|email|string|Borrower's electronic mail address|254|
|phone|object| Borrower's contact telephone details| **[Phone Object](#phone-object)**|
|is_pep *|boolean|Politically Exposed Person (PEP) indicator|5|
|address *|object| Borrower's residential address details| **[Address Object](#address-object)** |
|role_type *|enum|The role of the person in the operation. Default: issuer|-|
|birth_date *|date|Borrower's date of birth (Format: "YYYY-MM-DD")|10|
|mother_name *|string|Borrower's mother's full name|100|
|nationality|string|Borrower's nationality|50|
|person_type *|string|Person classification|7|
|individual_document_number *|string|Borrower's Tax ID (CPF) - numbers only|11|
|document_identification *|string|DOCUMENT_KEY of the uploaded identification document (RG or CNH)|36|
|document_identification_back|string|DOCUMENT_KEY of the uploaded back side of the identification document|36|

### Address Object

|Field|Type|Description|Max. Char.|
|---|--- |---|---|
|city *|string|City name of the address|100|
|state *|string|State abbreviation (two uppercase characters)|2|
|number *|string|Street number|10|
|street *|string|Street name|100|
|complement *|string|Address complement (free text)|100|
|postal_code *|string|Postal code (CEP) - numbers only|8|
|neighborhood *|string|Neighborhood or district name|100|

### Phone Object 

|Field|Type|Description|Max. Char.|
|---|--- |---|---|
|number *|string|Subscriber's phone number|9|
|area_code *|string|Two-digit regional area code (e.g., "11")|2|
|country_code *|string|International dialing code (e.g., "055")|3|

### Disbursement Bank Account Object
|Field|Type|Description|Max. Char.|
|---|--- |---|---|
|name|string|Account holder's full name|50|
|document_number|string|Account holder's Tax ID (CPF)|11|
|bank_code *|string|Financial institution's COMPE code|3|
|branch_number *|string|Branch number (do not include the branch check digit!)|4|
|account_number *|string|Account number (do not include the account check digit!)|10|
|account_digit *|string|Account check digit (use zero instead of letters)|1|
|account_type|enum|Account Type Enumerator - Type of the bank account| **[Account Type Object](#account-type-object)**|

### Additional Data Object 

|Field|Type|Description|Max. Char.|
|---|--- |---|---|
|contract_number *|string|The unique identifier or reference number of the contract|12|
|signed *|boolean|Indicates if the contract has been successfully signed|5|
|signatures *|array|List of digital signature evidence objects (Opt-in)|-|
|name *|string|Full name of the signer|255|
|document_number *|string|Signer's tax identification number (CPF)|11|
|email *|string|Electronic mail address of the signer|100|
|area_code *|string|Two-digit regional area code (e.g., "11")|2|
|number *|string|Subscriber's phone number|9|
|country_code *|string|International dialing code (e.g., "055")|3|
|ip_address *|string|The IP address used during the signature process|45|
|timestamp *|string|Date and time of the signature (DD-MM-YYYY HH:mm:ss)|19|
|file_url *|string|Direct link to the signed contract document (PDF)|2048|
|file_type *|string|Format of the signature file (e.g., "pdf")|4|
|long *|string|Geographic longitude coordinate of the signature location|20|
|lat *|string|Geographic latitude coordinate of the signature location|20|
|fingerprint_device|string|Unique digital identifier of the device used|-|

### Response

The response to this debt request will return the payment plan as well as a **DEBT-KEY**, which is the identifier of the debt in QI SCD.

STATUS 201

Response Body

```json
{
    "webhook_type": "debt",
    "key": "a6dbf441-31b0-44df-9bb8-593553de2c45",
    "status": "issued",
    "event_datetime": "2026-02-10 00:01:20",
    "data": {
        "borrower": {
            "name": "Alan Mathison Turing",
            "document_number": "96969879003",
            "related_party_key": "6995ff6e-27c2-47e9-b4bf-640934b56b23"
        },
        "contract": {
            "document_key": null,
            "number": "TIK11267101100",
            "urls": [],
            "signature_information": [
                {
                    "signer_name": "Alan Mathison Turing",
                    "signer_document_number": "96969879003",
                    "signer_role": "issuer",
                    "signer_email": "alan.turing@email.com",
                    "signer_external_key": null,
                    "signature_url": null
                }
            ]
        },
        "requester_identifier_key": "6b558426-6b6c-4c9e-bfb3-5734fe45a651",
        "iof_charge_method": "financed",
        "collaterals": [],
        "contract_fees": [
            {
                "fee_type": "spread",
                "fee_amount": 0.6
            }
        ],
        "external_contract_fees": [],
        "external_contract_fee_amount": 0,
        "net_external_contract_fee_amount": 0,
        "contract_fee_amount": 0.6,
        "issue_amount": 201.49,
        "assignment_amount": 202.09,
        "cet": "7,6600%",
        "annual_cet": "142,5744%",
        "number_of_installments": 2,
        "base_iof": 0.73,
        "additional_iof": 0.76,
        "total_iof": 1.49,
        "ipoc_code": "324025020203196969879003TIK11267101100",
        "prefixed_interest_rate": {
            "annual_rate": 1.252191589,
            "created_at": "2026-02-10T00:01:18",
            "daily_rate": 0.0022578334,
            "interest_base": "calendar_days",
            "monthly_rate": 0.07
        },
        "installments": [
            {
                "accrual_reference_date": null,
                "additional_costs": [],
                "advanced_paid_amount": 0,
                "bank_slip_key": null,
                "business_due_date": "2026-03-06",
                "calendar_days": 28,
                "digitable_line": null,
                "due_date": "2026-03-06",
                "due_interest": 0,
                "due_principal": 201.49,
                "fine_amount": null,
                "has_interest": true,
                "installment_history": [],
                "installment_key": "5c121fac-20f8-4481-b7b6-d0647a0ce524",
                "installment_number": 1,
                "installment_payment": [],
                "installment_status": "created",
                "installment_type": "principal",
                "original_due_principal": 201.49,
                "original_pre_fixed_amount": 13.13403553,
                "original_principal_amortization_amount": 97.92596447,
                "original_total_amount": 111.06,
                "paid_amount": 0,
                "paid_at": null,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 13.13403553,
                "principal_amortization_amount": 97.92596447,
                "qr_code_key": null,
                "qr_code_url": null,
                "renegotiation_proposal_key": null,
                "tax_amount": 0.22483801,
                "total_accrual_amount": null,
                "total_amount": 111.06,
                "total_paid_amount": 0,
                "workdays": 18
            },
            {
                "accrual_reference_date": null,
                "additional_costs": [],
                "advanced_paid_amount": 0,
                "bank_slip_key": null,
                "business_due_date": "2026-04-06",
                "calendar_days": 31,
                "digitable_line": null,
                "due_date": "2026-04-06",
                "due_interest": 0,
                "due_principal": 103.56403553,
                "fine_amount": null,
                "has_interest": true,
                "installment_history": [],
                "installment_key": "a8a21d7a-481e-43ba-b115-fd89253bcde9",
                "installment_number": 2,
                "installment_payment": [],
                "installment_status": "created",
                "installment_type": "principal",
                "original_due_principal": 103.56403553,
                "original_pre_fixed_amount": 7.49596447,
                "original_principal_amortization_amount": 103.56403553,
                "original_total_amount": 111.06,
                "paid_amount": 0,
                "paid_at": null,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 7.49596447,
                "principal_amortization_amount": 103.56403553,
                "qr_code_key": null,
                "qr_code_url": null,
                "renegotiation_proposal_key": null,
                "tax_amount": 0.5010428,
                "total_accrual_amount": null,
                "total_amount": 111.06,
                "total_paid_amount": 0,
                "workdays": 20
            }
        ],
        "total_pre_fixed_amount": 20.63
    }
}
```

## 5. Webhooks

After the successful response, you will receive webhooks for the CCB and for disbursement success or failure. How the CCB and signature are notified depends on whether generation is **synchronous** or **asynchronous**:

- **Synchronous CCB generation:** the Signature webhook (`signature_finished`) is sent during this flow, with the signed CCB URL.
- **Asynchronous CCB generation:** two debt webhooks may be sent instead: one with status `issued` (full debt data after issuance) and one with status `generated_document` (CCB URL and signed document). **If these asynchronous webhooks are triggered, the Signature finished (`signature_finished`) webhook is not sent.**

You will still receive a webhook indicating the disbursement’s success or failure (or cancellation), as described below.

### Signature webhook (synchronous)

In synchronous CCB mode generation, the Signature webhook is delivered in this flow.

Response Body

```json
{
    "key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "status": "signature_finished",
    "webhook_type": "debt",
    "event_datetime": "2025-10-27 17:09:33",
    "contract_document_key":"9f9ab7e4-3605-4f92-89ca-0d9c2a17fba4",
    "requester_identifier_key":"7349e218-0646-483b-b75b-3300f7212176",
    "signed_contract_url": "https://storage.googleapis.com/sandbox-doc-api/documents/c8b191cb-7b90-4e37-9280-397a597babc1/RAFAELAEBENJAMINFINANCEIRALTDA-ALAN_MATHISON_TURING-CCB-TIK11267101212-20251027170925_signed.pdf"
}

```

### Issued webhook (asynchronous)

When CCB generation runs asynchronously, this webhook notifies issuance with the full debt payload (`status`: `issued`). It replaces the synchronous Signature webhook in that flow; see the introduction at the top of this section.

Response Body

```json
{
    "key": "1e90d231-e569-49cb-9bf0-3409bb45a43a",
    "data": {
      "cet": "33,6800%",
      "base_iof": 0.19,
      "borrower": {
        "name": "teste",
        "document_number": "68752867005",
        "related_party_key": "186e58d3-1e82-400c-88b5-fd9c087f80bb"
      },
      "contract": {
        "urls": [],
        "number": "MSCT6YJ3MO51",
        "document_key": null,
        "signature_information": [
          {
            "signer_name": "teste",
            "signer_role": "issuer",
            "signer_email": "teste@gmail.com",
            "signature_url": null,
            "signer_external_key": null,
            "signer_document_number": "06160405390"
          }
        ]
      },
      "ipoc_code": "324025020203106160405390MSCT6YJ3MO51",
      "total_iof": 0.38,
      "annual_cet": "3.156,5450%",
      "collaterals": [],
      "installments": [
        {
          "paid_at": null,
          "due_date": "2026-05-27",
          "workdays": 31,
          "tax_amount": 0.1859022,
          "fine_amount": null,
          "paid_amount": 0.0,
          "qr_code_key": null,
          "qr_code_url": null,
          "due_interest": 0.0,
          "has_interest": true,
          "total_amount": 76.82,
          "bank_slip_key": null,
          "calendar_days": 45,
          "due_principal": 50.38,
          "digitable_line": null,
          "installment_key": "4a940fc6-45d8-43a4-9f62-1b8cf36bf5d9",
          "additional_costs": [],
          "installment_type": "principal",
          "pre_fixed_amount": 26.44,
          "business_due_date": "2026-05-27",
          "post_fixed_amount": 0,
          "total_paid_amount": 0.0,
          "installment_number": 1,
          "installment_status": "created",
          "installment_history": [],
          "installment_payment": [],
          "advanced_paid_amount": 0.0,
          "total_accrual_amount": null,
          "original_total_amount": 76.82,
          "accrual_reference_date": null,
          "original_due_principal": 50.38,
          "original_pre_fixed_amount": 26.44,
          "renegotiation_proposal_key": null,
          "principal_amortization_amount": 50.38,
          "original_principal_amortization_amount": 50.38
        }
      ],
      "issue_amount": 50.38,
      "contract_fees": [
        {
          "fee_type": "spread",
          "fee_amount": 0.19
        },
        {
          "fee_type": "spread_ted_fee",
          "fee_amount": 1.0
        }
      ],
      "additional_iof": 0.19,
      "assignment_amount": 51.57,
      "iof_charge_method": "financed",
      "contract_fee_amount": 1.19,
      "external_contract_fees": [],
      "number_of_installments": 1,
      "prefixed_interest_rate": {
        "created_at": "2026-04-12T21:37:53",
        "daily_rate": 0.009419836,
        "annual_rate": 29.6351274611,
        "monthly_rate": 0.33,
        "interest_base": "calendar_days_365"
      },
      "total_pre_fixed_amount": 26.44,
      "requester_identifier_key": "ccdbb93a-89cf-47bc-bd69-87671019d2ae",
      "external_contract_fee_amount": 0,
      "net_external_contract_fee_amount": 0
    },
    "status": "issued",
    "webhook_type": "debt",
    "event_datetime": "2026-04-12 21:37:53"
}
```

### Generated document webhook (asynchronous)

Sent asynchronously with the CCB document URL and the signed PDF. In the asynchronous flow, use this together with the Issued webhook; the Signature finished webhook is not sent. See the introduction at the top of this section.

Response Body

```json
{
    "key": "1e90d231-e569-49cb-9bf0-3409bb45a43a",
    "data": {
      "contract": {
        "urls": [
          "https://storage.googleapis.com/live-doc-api/documents/ddc85f4c-7079-44c5-b8cc-1fa630406551-signed.pdf"
        ]
      },
      "document_key": "ddc85f4c-7079-44c5-b8cc-1fa630406551",
      "signed_contract_url": "https://storage.googleapis.com/live-doc-api/documents/ddc85f4c-7079-44c5-b8cc-1fa630406551-signed.pdf"
    },
    "status": "generated_document",
    "webhook_type": "debt",
    "event_datetime": "2026-04-12 21:38:02"
}
```

### Disbursement webhook

Response Body

```json
{
    "key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "data": {
      "installments": [
        {
          "due_date": "2025-11-27",
          "total_amount": 87.43,
          "installment_key": "e25fb146-0a61-4319-a722-d01b2213d0f9",
          "pre_fixed_amount": 29.26477451,
          "installment_number": 1,
          "principal_amortization_amount": 58.16522549
        },
        {
          "due_date": "2025-12-27",
          "total_amount": 87.43,
          "installment_key": "2557de2b-6df1-4a8a-b46a-59206ece157f",
          "pre_fixed_amount": 20.11446867,
          "installment_number": 2,
          "principal_amortization_amount": 67.31553133
        },
        {
          "due_date": "2026-01-27",
          "total_amount": 87.43,
          "installment_key": "cc503d1d-6387-4a1f-bd78-62b248d02ec8",
          "pre_fixed_amount": 11.07075682,
          "installment_number": 3,
          "principal_amortization_amount": 76.35924318
        }
      ],
      "ted_receipt_list": [],
      "requester_identifier_key": "24b5deae-304e-4773-9b25-e42dbd450241",
    },
    "status": "disbursed",
    "webhook_type": "debt",
    "event_datetime": "2025-10-27 17:10:21"
}

```

If the debt fails to disburse, or is returned, you will receive a cancellation webhook.

### Cancelation webhook

Response Body

```json
{
     "webhook_type": "debt",
     "key":"1ebd4a90-2721-4c39-a399-427fa16bca65",
     "event_datetime": "2025-10-27 16:38:59",
    "data": {
        "cancel_reason": "Operacao cancelada manualmente",
        "cancel_reason_enumerator": "manual"
    },
     "status":"canceled"
  }

```

****Cancelation reasons****

| cancel_reason_enumerator | Description |  
|---|---|  
|disbursing_error|Operation canceled due to an error during disbursement.  
|waiting_signature |Operation canceled due to missing signature. 
|pix_max_retry|Operation canceled because the receiving bank could not process the disbursement.  
|manual|Operation canceled manually.  
|agencia_conta_invalida|Invalid agency or recipient account number.  
|invalid_account|The destination account number is nonexistent or invalid.  
|invalid_document_number|The CPF/CNPJ of the destination account is incorrect.  
|unsupported_transaction|The destination account does not support this type of transaction.  
|invalid_ispb|The ISPB number is invalid or nonexistent.  
|rejected_payment|Payment order was rejected by the receiving bank.  
| refund_after_payee_request | Refund requested by the payee                                                |
| invalid_account            | The destination account number is nonexistent or invalid.                    |
| invalid_document_number    | The CPF/CNPJ of the destination account is incorrect.                        |
| rejected_payment           | Payment rejected by the receiving bank.                                      |
| blocked_account            | The destination account is blocked.                                          |
| unsupported_transaction    | The destination account does not support this type of transaction.           |
| amount_too_great           | Payment/refund amount exceeds the limit for the credited destination account. |
| invalid_ispb               | The ISPB number is invalid or nonexistent.                                   |
| receiver_error             | Transaction interrupted due to error on the receiver's PSP.                  |
| closed_account             | The destination account is closed.                                           |
| disbursing_hour_closed     | Disbursement occurred outside of the allowed time frame.                     |
| unregistered_pix_key       | The Pix key is not being used.                                               |
| manual                     | Operation manually canceled.                                                 |
| spi_timeout                | Timeout control in SPI.                                                     |

## 6. Cancellation

### Cancel debt before disbursement

### Request Body

ENDPOINT /debt/ DEBT-KEY /cancel
MÉTODO PATCH

Testar no Playground

### Path params

| Field  | Type   | Description | Max. Char. |
|---|---| ---| ---|
| `debt_key` * | string | Debt unique identifier key returned at the moment of the credit operation creation. | 32 |  

### Response Body

STATUS 200

Response Body

```json
{
  "data": [
    {
      "borrower": {
        "document_number": "68394265057",
        "name": "Xuxa Meneguel"
      },
      "contract_fee_amount": 5.56,
      "installments": [
        {
          "bank_slip_key": null,
          "calendar_days": 57,
          "due_date": "2020-09-30",
          "due_principal": -0.00217819,
          "fine_amount": null,
          "has_interest": true,
          "installment_key": "28eb5907-ed25-4a86-bb9d-b6dc944f13df",
          "installment_number": 1,
          "installment_status": "opened",
          "installment_type": "principal",
          "paid_amount": 0,
          "post_fixed_amount": 0,
          "pre_fixed_amount": 268.75782181,
          "principal_amortization_amount": 1111.9,
          "tax_amount": 0,
          "total_amount": 1380.66,
          "workdays": 40
        }
      ],
      "operation_key": "7986dcc7-4331-478f-af47-adfbdf7f4a36",
      "status": "opened"
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "rows_per_page": 100,
    "total_pages": 1,
    "total_rows": 55
  }
}

```

### Debt cancellation within seven days after disbursement — Via Pix refund

Used when the partner requests the borrower to return the funds via Pix. The system generates a copy-paste Pix code for the borrower to complete the refund. Once payment is confirmed, the operation is automatically canceled.

:::info When to use
Use this endpoint when the reversal must be completed by the **borrower**, who will receive a Pix refund code to pay.
:::

###  Request Body

ENDPOINT /debt/CREDIT-OPERATION-KEY/reversal
MÉTODO POST

Testar no Playground

Request Body

```json
{}

```

---

### Debt cancellation within seven days after disbursement — Via QI internal account

Used when the refund is processed directly through **QI Tech's internal account**, without requiring any action from the borrower. Suitable for the `internal` method, where the amount is debited internally without generating a Pix.

:::info When to use
Use this endpoint when the reversal is operated by the **partner via QI Tech's internal account**, without involving the borrower in the refund process.
:::

###  Request Body

ENDPOINT /credit_operation/ CREDIT-OPERATION-KEY /reversal
MÉTODO PUT

:::info Required Header
Send the `SELECTED-AGENT` header with your `requester_key` value.
:::

### Path Params

| Field | Type | Description | Max. Char. |
|---|---|---|---|
| `credit_operation_key`* | string | Credit operation key (DEBT-KEY) | UUID |

Request Body (optional)

```json
{
    "cancel_reason": "reversed_manually"
}

```

### Body Params

| Field | Type | Description | Max. Char. |
|---|---|---|---|
| `cancel_reason` | string | Reason for the reversal. If not provided, the system will use the default. | - |

###  Response Body

STATUS 200

Response Body

```json
{
  "disbursed_issue_amount": 1500,
  "issue_amount": 2000,
  "assignment_amount": 1850,
  "assigned": true,
  "assigned_at": "2023-10-01T12:00:00",
  "purchaser_document_number": "12345678000199",
  "reversal_key": "a353c543-2ac7-437c-ac6a-eb4e8d6ce250"
}

```

## 7. Debt inquiry

You can query the debt later to retrieve information or track its current status:

ENDPOINT /v2/credit_operation/ CREDIT-OPERATION-KEY
METHOD GET

Testar no Playground

### Path params

| Field  | Type   | Description | Max. Char. |
|---|---|---|---|   
| `credit_operation_key` * | string |  Key of the credit operation | UUID |

### Response

STATUS 200

Response Body

```json
{
   "credit_operation_key":"31381158-e138-4aaa-99b7-f78356e71004",
   "issue_amount":201,
   "origin_key":"31381158-e138-4aaa-99b7-f78356e71004",
   "total_iof":1,
   "assigned_at":null,
   "disbursement_start_date":"2026-02-23",
   "disbursement_end_date":"2026-02-23",
   "issue_date":"2026-02-23",
   "requester_identifier_key":"12313asdjasdx998",
   "installments":[
      {
         "business_due_date":"2026-02-24",
         "due_date":"2026-02-24",
         "calendar_days":1,
         "due_interest":0,
         "due_principal":201,
         "fine_amount":0,
         "has_interest":true,
         "post_fixed_amount":0,
         "pre_fixed_amount":0.46,
         "principal_amortization_amount":103.45,
         "tax_amount":0.01,
         "total_amount":103.91,
         "workdays":1,
         "accrual_reference_date":null,
         "advanced_paid_amount":0,
         "bank_slip_key":null,
         "digitable_line":null,
         "installment_key":"cfd67eb8-cd1e-438b-8636-44cb94176515",
         "installment_status":"created",
         "installment_type":"principal",
         "original_due_principal":201,
         "original_pre_fixed_amount":0.46,
         "original_principal_amortization_amount":103.45,
         "paid_amount":0,
         "original_total_amount":103.91,
         "qr_code_key":null,
         "qr_code_url":null,
         "renegotiation_proposal_key":null,
         "total_accrual_amount":0,
         "total_paid_amount":0,
         "installment_number":1,
         "paid_at":null,
         "updated_at":null,
         "principal_amortization_payment_amount":0,
         "prefixed_interest_payment_amount":0
      },
      {
         "business_due_date":"2026-03-24",
         "due_date":"2026-03-24",
         "calendar_days":28,
         "due_interest":0,
         "due_principal":97.54761348,
         "fine_amount":0,
         "has_interest":true,
         "post_fixed_amount":0,
         "pre_fixed_amount":6.36,
         "principal_amortization_amount":97.55,
         "tax_amount":0.23,
         "total_amount":103.91,
         "workdays":20,
         "accrual_reference_date":null,
         "advanced_paid_amount":0,
         "bank_slip_key":null,
         "digitable_line":null,
         "installment_key":"445f1c2d-3967-4b23-9290-e19a0a5fb956",
         "installment_status":"created",
         "installment_type":"principal",
         "original_due_principal":97.55,
         "original_pre_fixed_amount":6.36,
         "original_principal_amortization_amount":97.55,
         "paid_amount":0,
         "original_total_amount":103.91,
         "qr_code_key":null,
         "qr_code_url":null,
         "renegotiation_proposal_key":null,
         "total_accrual_amount":0,
         "total_paid_amount":0,
         "installment_number":2,
         "paid_at":null,
         "updated_at":null,
         "principal_amortization_payment_amount":0,
         "prefixed_interest_payment_amount":0
      }
   ],
   "first_due_date":"2026-02-24",
   "requester_key":"3e69b448-9afb-4aef-9c0d-0a3059350d80",
   "original_total_iof":null,
   "contract_number":"TIK122710117",
   "credit_operation_status_enumerator":"issued",
   "operation_type_enumerator":"structured_operation",
   "disbursement_date":"2026-02-23",
   "issuer_name":"Alan Mathison Turing",
   "issuer_document_number":"46843213049",
   "external_contract_fees":[
      
   ],
   "cet":8.23,
   "annual_cet":158.43,
   "final_disbursement_amount":200,
   "number_of_installments":2,
   "disbursement_issue_amount":200,
   "prefixed_interest_rate":{
      "annual_rate":1.252191589,
      "daily_rate":0.0022578334,
      "interest_base":{
         "enumerator":"calendar_days",
         "year_days":360
      },
      "monthly_rate":0.07
   },
   "fine_configuration":{
      "contract_fine_rate":0.02,
      "fine_delay_rate":{
         "annual_rate":4.35025011,
         "daily_rate":0.0046696,
         "interest_base":{
            "enumerator":"calendar_days",
            "year_days":360
         },
         "monthly_rate":0.15
      }
   },
   "attached_documents":[
      {
         "document_key":"494598fd-c226-4332-a500-591ae3884673",
         "document_url":"https://storage.googleapis.com/sandbox-doc-api/documents/494598fd-c226-4332-a500-591ae3884673/3d684e68e7df4e557d0480d98e2692.jpg",
         "signature_url":null,
         "document_type":"document_identification",
         "signature_required":false,
         "signed":false
      },
      {
         "document_key":"494598fd-c226-4332-a500-591ae3884673",
         "document_url":"https://storage.googleapis.com/sandbox-doc-api/documents/494598fd-c226-4332-a500-591ae3884673/3d684e68e7df4e557d0480d98e2692.jpg",
         "signature_url":null,
         "document_type":"document_identification_back",
         "signature_required":false,
         "signed":false
      },
      {
         "document_key":"73584aa0-91d4-483b-a95c-1b0263c14126",
         "document_url":"https://storage.googleapis.com/sandbox-doc-api/documents/73584aa0-91d4-483b-a95c-1b0263c14126/CASTELLOBNPL-ALAN_MATHISON_TURING-CCB-TIK122710117-202602241151.pdf",
         "signature_url":"https://storage.googleapis.com/sandbox-doc-api/documents/73584aa0-91d4-483b-a95c-1b0263c14126/CASTELLOBNPL-ALAN_MATHISON_TURING-CCB-TIK122710117-202602241151_signed.pdf",
         "document_type":"ccb_pre_price_days",
         "signature_required":true,
         "signed":true
      }
   ],
   "related_parties":[
      {
         "related_party_key":"fe133e90-9ee6-401a-a5a4-7d415ecb04fd",
         "role_type":"issuer",
         "person_type":"natural",
         "name":"Alan Mathison Turing",
         "email":"weiwenqian.wayne@bytedance.com",
         "individual_document_number":"46843213049"
      }
   ],
   "base_iof":0.24,
   "additional_iof":0.76,
   "assignment_amount":201.6,
   "total_prefixed_amount":6.82
}
```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

You can also query the debt later to retrieve the log of events status:

ENDPOINT /v2/credit_operation/ CREDIT-OPERATION-KEY /events
METHOD GET

CREDIT-OPERATION-KEY /events">Testar no Playground

### Path params

| Field  | Type   | Description | Max. Char. |
|---|---|---|---|   
| `credit_operation_key` * | string | Key of the credit operation | UUID |

### Response

STATUS 200

Response Body

```json
{
  "data": [
    {
      "status": "waiting_signature",
      "reason": null,
      "cancel_reason": null,
      "event_date": "2026-03-13T17:19:59Z"
    },
    {
      "status": "issued",
      "reason": null,
      "cancel_reason": null,
      "event_date": "2026-03-13T17:19:59Z"
    },
    {
      "status": "waiting_disbursement",
      "reason": null,
      "cancel_reason": null,
      "event_date": "2026-03-13T17:19:59Z"
    },
    {
      "status": "opened",
      "reason": null,
      "cancel_reason": null,
      "event_date": "2026-03-13T17:19:59Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "rows_per_page": 10
  }
}
```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

## 8. Assignment Inquiry

###  Assignment Confirmation Webhook
This webhook is triggered to notify the client that the assignment process has been initiated. It provides the essential metadata required to track the assignment.

Response Body

```json
{
      "key":"19e34186-847b-4dd7-9fc2-d14e28bc2f10",
      "data":{
         "status":"settled",
         "total_amount":1917.04,
         "assignment_key":"19e34186-847b-4dd7-9fc2-d14e28bc2f10",
         "reference_date":"2026-04-10",
         "number_of_items":8,
         "term_of_assignment_url":null
      },
      "webhook_type":"assignment.status_change",  
      "event_datetime":"2026-04-10T22:37:52"
}

```

|Field|Type|Description|Maximum lenght|
|---|---|---|---|
|assignment_key|string|Unique identifier for the assignment operation|36|
|term_of_assignment_url|string| URL to download the Term of Assignment (PDF)|2048|
|number_of_items|integer|Total number of credit operations (items) included in this assignment|5|
|total_amount|float|The sum of the present value of all items in the assignment|15,2|
|reference_date|string|The base date used for the assignment calculations (YYYY-MM-DD)|10|

To query a specific assignment, the client can perform a GET request on the endpoint using the assignment identifier key (assignment_key).

###  Request Body

ENDPOINT /v2/assignment/[assignment_key] METHOD GET

Testar no Playground

### Params

| Field            | Descrição                      |
| ---------------- | ------------------------------ |
| `assignment_key` | Assignment unique identifier key |

### Response

STATUS 200

Response Body

```json
{
"assignment_key": "77997168-5d61-430f-b5ae-08eb3d7b8c0e",
"creation_datetime": "2023-10-01T12:00:00",
"reference_date": "2023-10-01",
"total_amount": 120000,
"number_of_items": 5,
"term_of_assignment_url": "https://example.com/assignment.pdf",
"status": "settled",
"signable_term_url": "https://example.com/signable_term.pdf"
}
```

To query the contracts within an assignment, use a GET request on the endpoint with the same **assignment_key**.

### Request Body

ENDPOINT /v2/assignment/[ASSIGNMENT_KEY]/assignment_items?page=1&page_size=100 METHOD GET

Testar no Playground

### Path Params

| Field      | Type    | Description    | 
|-----------------|---------|----------------|
| `assignment_key` | string |Assignment unique identifier key |

### Query Params

| Field      | Type    | Description    | 
|-----------------|---------|----------------|
| `page` | string |Number of the page |
| `page_size` | string | Length of the page, limited by 100 |

The response is a paginated list containing information for each contract in the assignment (status 200):

### Response Body

STATUS 200

Response Body

```json
{
		"pagination": {
			"page": 1,
			"page_size": 10
		}
		"data": [
		{
				"assignment_date": date,
        "assignment_item_key": uuid,
        "contract_number": "TIK000012312",
        "control_number": "TIK000012312",
        "requester_identifier_key": uuid,  -> including this field
        "credit_operation_key": string,
        "disbursed_amount": 80.0,
        "disbursement_date": date,
        "endorsement_url": url,
        "issue_amount": 180.00,
        "issuer_document_number": string,
        "issuer_name": string,
        "number_of_installments": 10,
        "present_amount": 180.0,
        "contract_present_amount": 180.0,
        "purchaser_document_number": string,
        "status": "settled/canceled",
        "rejected_reasons": []
        "assignment_items": [
	        {
		        "installment_key": uuid,
		        "present_amount": 100,
		        "due_date": date,
		        "your_number": "TIK000012312001"
	        },
	        {
		        "installment_key": uuid,
		        "present_amount": 80,
		        "due_date": date,
		        "your_number": "TIK000012312002"
	        }
        ]
      }
	]
}
```

Query the assigment batchs by the **assignment_date**.

### Request Body

ENDPOINT /v2/assignment/assignments?reference_date=2026-05-15 METHOD GET

Testar no Playground

### Query Params

| Field                             | Type    | Description                                                                      | 
|-----------------------------------|---------|--------------------------------------------------------------------------------|
| `reference_date` |string| Date of assignment attempt |

### Response Body

STATUS 200

Response Body

```json
{"data": [{
      "assignment_key": "439b1257-82ac-4741-a416-a4428a9a7327",
      "number_of_items": 10000,
      "reference_date": "2025-01-01",
      "signable_term_url": "https://example.com/endorsement.pdf",
      "status": "settled",
      "term_of_assignment_url": "signed_url",
      "total_amount": 100.00,
  },
  {
      "assignment_key": "439b1257-82ac-4741-a416-a4428a9a7327",
      "number_of_items": 10000,
      "reference_date": "2025-01-01",
      "signable_term_url": "https://example.com/endorsement.pdf",
      "status": "settled",
      "term_of_assignment_url": "signed_url",
      "total_amount": 100.00,
  },
  {
      "assignment_key": "439b1257-82ac-4741-a416-a4428a9a7327",
      "number_of_items": 10000,
      "reference_date": "2025-01-01",
      "signable_term_url": "https://example.com/endorsement.pdf",
      "status": "canceled",
      "term_of_assignment_url": "signed_url",
      "total_amount": 100.00,
  }
  ]}
```

## 9. Technical Specifications and Enums

### Fees Object
| Field           | Type  | Description                                                                                           |
|-----------------|-------|-----------------------------------------------------------------------------------------------------|
| **amount**      | float | Fee amount (in percentage or absolute value, depending on the value provided in the amount_type field)| -            |
| **amount_type** | enum  | Fee value unit                   |  **[Amount Type Enumerator](#amount-type-enumerator)**             |
| **fee_amount**  | float | Absolute value of the fee charged in the operation                                                           | -            |
| **fee_type**    | string  | Type of fee charged in the operation                   | **[Fee Type Enumerator](#fee-type-enumerator)**          |
| **type**        | string  |  Source of the fee charged in the operation                         | **[Origin Type Enumerator](#origin-type-enumerator)**          |

### Installments Object
| Field                             | Type    | Description                                                                      | 
|-----------------------------------|---------|--------------------------------------------------------------------------------|
| **calendar_days**                 | integer    | Number of calendar days between installments                                | -            |
| **due_date**                      | string    | Installment due date in calendar days                                   | -            |
| **due_principal**                 | float   | Remaining principal on the installment due date before its payment | -            |
| **has_interest**                  | boolean | _true_ - If true, interest applies to the installment                           | -            |
| **installment_number**            | integer    | Installment number                                                              | -            |
| **prefixed_amount**               | float   | Fixed interest amount paid on the installment                                      | -            |
| **principal_amortization_amount** | float   | Principal amount paid on the installment                                           | -            |
| **tax_amount**                    | float   | Base IOF amount of installment                                                            | -            |
| **amount**                        | float   | Installment total value                                                         | -            |
| **due_interest**                  | float     | Remaining interest after the installment due date before its payment                                   | -            |
| **period**                        | float     | Installment period | -            |
| **period_workdays**               | float     | Installment period in business days | -            |
| **period_to_disbursement**        | float     | Period until disbursement | -            |
| **period_workdays_to_disbursement**| float     | Business days until disbursement | -            |
| **calendar_days_to_disbursement** | integer    | Calendar days to disbursement | -            |
| **workdays**                      | integer    | Business days between installments | -            |
| **workdays_to_disbursement**      | integer    | Business days until disbursement | -            |

### Interest Rate Object
| Field             | Description                                                                             | 
|-------------------|---------------------------------------------------------------------------------------|
| **annual_rate**   | Annual fixed/floating interest rate expressed as a decimal                                      | -            |
| **daily_rate**    | Daily fixed/floating interest rate expressed as a decimal                                      | -            |
| **interest_base** | **[Interest Base Enumerator](#interest-base-enumerator)** - Interest calculation basis  | -            |
| **monthly_rate**  | Monthly fixed/floating interest rate expressed as a decimal                                      | -            |

### Tax Configuration Object
| Field                 | Description                                                                             | 
|-----------------------|---------------------------------------------------------------------------------------|
| **base_rate**         | Base IOF rate value                                                                | -            |
| **additional_rate**   | Additional IOF rate value                                                           | -            |

### Enumeratores

### Person Type Enumerator
| Enumerator             | Description             |
|------------------------|-----------------------|
| **legal**              | Legal person       |
| **natural**            | Natural person          |

### Account Type Enumerator
| Enumerator             | Description             |
|------------------------|-----------------------|
| **checking_account**   | Checking account        |

### Amount Type Enumerator
| Enumerator             | Description             |
|------------------------|-----------------------|
| **absolute**           | Absolute value        |
| **percentage**         | Percentage value      |

###  Interest Type Enumerator
| Enumerator           | Description                                                                                                                                                                |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **pre_price_days**   | Price amortization method (equal installments) with daily fixed-rate interest calculation                                                                                     |
| **pre_price**        | Price amortization method (equal installments) with fixed-rate interest calculation over 30-day periods                                                                |

### Credit Operation Type Enumerator 
| Enumerator    | Description                      |
|---------------|--------------------------------|
| **ccb**       | Bank Credit Note    |

### Interest Base Enumerator 
| Enumerator            | Description                                                                 |
|-----------------------|---------------------------------------------------------------------------|
| **workdays**          | Interest calculation basis in business days, assuming a 252-day year    |
| **calendar_days**     | Interest calculation basis in calendar days, assuming a 360-day year |
| **calendar_days_365** | Interest calculation basis in calendar days, assuming a 365-day year |

###  Fee Type Enumerator
Each fee type must be previously enabled and configured by QI Tech

| Enumerator            | Description                                                                  |
|-----------------------|----------------------------------------------------------------------------|
| **spread**            | Premium included in the credit operation's acquisition value                  |
| **spread_ted_fee**    | Premium on the TED transfer fee |

### Origin Type Enumerator
Each fee type must be previously enabled and configured by QI Tech

| Enumerator            | Description                                                                  |
|-----------------------|----------------------------------------------------------------------------|
| **internal**          | Internal fee                                                   |
| **external**          | External fee                                                   |

---

# Consulta - Emissão BNPL

URL: /documentation/manual_bnpl_full/emissao/consulta

# Consulta - Emissão BNPL


## Resumo

Você pode consultar a dívida a qualquer momento para obter informações ou acompanhar o status atual da operação.

## Consultar Operação de Crédito

Existem duas formas de consultar uma operação:
- Por `credit_operation_key` (DEBT-KEY)
- Por `requester_identifier_key` (chave identificadora enviada na emissão)

### Por Credit Operation Key

ENDPOINT /v2/credit_operation/ CREDIT-OPERATION-KEY
MÉTODO GET

Testar no Playground

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `credit_operation_key`* | string | Chave da operação de crédito (DEBT-KEY) | UUID |

### Por Requester Identifier Key

ENDPOINT /v2/credit_operation/requester_identifier_key/ REQUESTER-IDENTIFIER-KEY
MÉTODO GET

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `requester_identifier_key`* | string | Chave identificadora enviada na emissão | UUID |

### Response

STATUS 200

Response Body

```json
{
    "credit_operation_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c",
    "issue_amount": 1007.62,
    "origin_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c",
    "total_iof": 7.62,
    "assigned_at": null,
    "disbursement_start_date": "2026-04-07",
    "disbursement_end_date": "2026-04-07",
    "issue_date": "2026-04-07",
    "requester_identifier_key": "d1905ef5-19df-4183-bf0e-802b8229933c",
    "installments": [
        {
            "business_due_date": "2026-05-07",
            "due_date": "2026-05-07",
            "calendar_days": 30,
            "due_interest": 0,
            "due_principal": 1007.62,
            "fine_amount": 0,
            "has_interest": true,
            "post_fixed_amount": 0,
            "pre_fixed_amount": 52.4,
            "principal_amortization_amount": 491.49,
            "tax_amount": 1.21,
            "total_amount": 543.89,
            "workdays": 20,
            "accrual_reference_date": null,
            "advanced_paid_amount": 0,
            "bank_slip_key": null,
            "digitable_line": null,
            "installment_key": "1dea396f-beb1-4df3-9822-35800b4c095a",
            "installment_status": "opened",
            "installment_type": "principal",
            "original_due_principal": 1007.62,
            "original_pre_fixed_amount": 52.4,
            "original_principal_amortization_amount": 491.49,
            "paid_amount": 0,
            "original_total_amount": 543.89,
            "qr_code_key": null,
            "qr_code_url": null,
            "renegotiation_proposal_key": null,
            "total_accrual_amount": 0,
            "total_paid_amount": 0,
            "installment_number": 1,
            "paid_at": null,
            "updated_at": "2026-04-07T23:59:27",
            "principal_amortization_payment_amount": 0,
            "prefixed_interest_payment_amount": 0
        },
        {
            "business_due_date": "2026-06-08",
            "due_date": "2026-06-07",
            "calendar_days": 31,
            "due_interest": 0,
            "due_principal": 516.1296159,
            "fine_amount": 0,
            "has_interest": true,
            "post_fixed_amount": 0,
            "pre_fixed_amount": 27.76,
            "principal_amortization_amount": 516.13,
            "tax_amount": 2.58,
            "total_amount": 543.89,
            "workdays": 20,
            "accrual_reference_date": null,
            "advanced_paid_amount": 0,
            "bank_slip_key": null,
            "digitable_line": null,
            "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999",
            "installment_status": "opened",
            "installment_type": "principal",
            "original_due_principal": 516.13,
            "original_pre_fixed_amount": 27.76,
            "original_principal_amortization_amount": 516.13,
            "paid_amount": 0,
            "original_total_amount": 543.89,
            "qr_code_key": null,
            "qr_code_url": null,
            "renegotiation_proposal_key": null,
            "total_accrual_amount": 0,
            "total_paid_amount": 0,
            "installment_number": 2,
            "paid_at": null,
            "updated_at": "2026-04-07T23:59:27",
            "principal_amortization_payment_amount": 0,
            "prefixed_interest_payment_amount": 0
        }
    ],
    "first_due_date": "2026-05-07",
    "requester_key": "78287247-947d-4730-9bd1-7efb068175b6",
    "contract_number": "DWF1761222116",
    "credit_operation_status_enumerator": "opened",
    "operation_type_enumerator": "structured_operation",
    "disbursement_date": "2026-04-07",
    "issuer_name": "Dante Ferrarini",
    "issuer_document_number": "31057466093",
    "external_contract_fees": [
        {
            "amount_type": "absolute",
            "fee_amount": 0,
            "tax_amount": 0,
            "irrf_amount": 0,
            "amount": 0,
            "pis_amount": 0,
            "amount_released": 0,
            "fee_type": "tac",
            "cofins_amount": 0,
            "csll_amount": 0,
            "description": null,
            "net_fee_amount": 0,
            "rebate_account": null
        }
    ],
    "cet": 5.82,
    "annual_cet": 97.05,
    "final_disbursement_amount": 1000,
    "number_of_installments": 2,
    "disbursement_issue_amount": 1000,
    "prefixed_interest_rate": {
        "annual_rate": 0.8373372409,
        "daily_rate": 0.0016911989,
        "interest_base": {
            "enumerator": "calendar_days",
            "year_days": 360
        },
        "monthly_rate": 0.052
    },
    "fine_configuration": {
        "contract_fine_rate": 0.02,
        "fine_delay_rate": {
            "annual_rate": 0.12682503,
            "daily_rate": 0.00033173,
            "interest_base": {
                "enumerator": "calendar_days",
                "year_days": 360
            },
            "monthly_rate": 0.01
        }
    },
    "attached_documents": [
        {
            "document_key": "d6705fc4-80e0-4c8e-9aff-f3875024e6a4",
            "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/...",
            "signature_url": "https://storage.googleapis.com/sandbox-doc-api/documents/..._signed.pdf",
            "document_type": "ccb_pre_price_days",
            "signature_required": true,
            "signed": true
        }
    ],
    "related_parties": [
        {
            "related_party_key": "24fac77e-7782-4f72-b31a-daee288e34ed",
            "role_type": "issuer",
            "person_type": "natural",
            "name": "Dante Ferrarini",
            "email": "",
            "individual_document_number": "31057466093"
        }
    ],
    "base_iof": 3.79,
    "additional_iof": 3.83,
    "assignment_amount": 1010.64,
    "created_at": "2026-04-07T23:59:22Z",
    "total_prefixed_amount": 80.16
}
```

STATUS 400

Response Body

```json
{
    "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

---

## Consultar Eventos da Operação

Você também pode consultar o histórico de eventos (log de status) da operação:

ENDPOINT /v2/credit_operation/ CREDIT-OPERATION-KEY /events
MÉTODO GET

Testar no Playground

### Path Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `credit_operation_key`* | string | Chave da operação de crédito | UUID |

### Response

STATUS 200

Response Body

```json
{
    "data": [
        {
            "status": "waiting_signature",
            "reason": null,
            "cancel_reason": null,
            "event_date": "2026-03-13T17:19:59Z"
        },
        {
            "status": "issued",
            "reason": null,
            "cancel_reason": null,
            "event_date": "2026-03-13T17:19:59Z"
        },
        {
            "status": "waiting_disbursement",
            "reason": null,
            "cancel_reason": null,
            "event_date": "2026-03-13T17:19:59Z"
        },
        {
            "status": "opened",
            "reason": null,
            "cancel_reason": null,
            "event_date": "2026-03-13T17:19:59Z"
        }
    ],
    "pagination": {
        "current_page": 1,
        "next_page": null,
        "rows_per_page": 10
    }
}
```

### Enumeradores de Status da Operação

| Status | Descrição |
|---|---|
| `waiting_signature` | Aguardando assinatura do contrato |
| `issued` | Operação emitida |
| `waiting_disbursement` | Aguardando desembolso |
| `opened` | Operação aberta (desembolso realizado) |
| `canceled` | Operação cancelada |
| `settled` | Operação liquidada (todas as parcelas pagas) |

---

# Emissão BNPL

URL: /documentation/manual_bnpl_full/emissao/

# Emissão BNPL


## Resumo

Este endpoint realiza a emissão da dívida e processa a assinatura do contrato via opt-in. O desembolso ocorre automaticamente logo após a emissão. Não é necessário pré-cadastro; basta fornecer os dados do tomador durante a requisição de emissão.

## Request

ENDPOINT /signed_debt
MÉTODO POST

Testar no Playground

Request Body

```json
{
    "borrower": {
        "name": "Dante Ferrarini",
        "email": "",
        "phone": {
            "number": "185633631",
            "area_code": "15",
            "country_code": "086"
        },
        "is_pep": false,
        "address": {
            "city": "São Paulo",
            "state": "SP",
            "number": "",
            "street": "Rua Gilberto Sabino",
            "postal_code": "05425020",
            "neighborhood": "Pinheiros",
            "complement": ""
        },
        "role_type": "issuer",
        "birth_date": "1993-09-10",
        "person_type": "natural",
        "attached_documents_list": [
            {
                "selfie": "250e7e95-57c8-40bd-a0cd-0be8eb172916"
            }
        ],
        "individual_document_number": "31057466093"
    },
    "financial": {
        "interest_type": "pre_price_days",
        "disbursement_date": "2026-04-07",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "disbursed_amount": 1000,
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "number_of_installments": 2,
        "principal_grace_period": 0,
        "monthly_interest_rate": 0.052
    },
    "simplified": true,
    "additional_data": {
        "contract": {
            "contract_number": "DWF1761222116",
            "signatures": [
                {
                    "signer": {
                        "name": "Dante Ferrarini",
                        "email": "",
                        "phone": {
                            "number": "185633631",
                            "area_code": "15",
                            "country_code": "086"
                        },
                        "document_number": "31057466093"
                    },
                    "signature": {
                        "timestamp": "28-01-2026 06:36:35",
                        "ip_address": "192.168.1.1",
                        "signature_file": {
                            "file_url": "https://qitech.com.br/signature.pdf",
                            "file_type": "pdf"
                        }
                    }
                }
            ]
        }
    },
    "requester_identifier_key": "d1905ef5-19df-4183-bf0e-802b8229933c",
    "purchaser_document_number": "32402502000135",
    "disbursement_bank_accounts": [
        {
            "name": "company name",
            "ispb_number": "32402502",
            "account_digit": "5",
            "branch_number": "0001",
            "account_number": "7617846",
            "document_number": "32246162000281",
            "percentage_receivable": 100
        }
    ]
}
```

### Detalhes do Request Body

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| **borrower*** | object | Objeto do tomador - O devedor da operação de crédito | **[Objeto Borrower](#objeto-borrower)** |
| **financial*** | object | Contém todos os detalhes financeiros e parâmetros de cálculo da operação | **[Objeto Financial](#objeto-financial)** |
| **simplified** | boolean | Se verdadeiro, utiliza o fluxo simplificado de emissão | - |
| **additional_data*** | object | Dados adicionais do contrato, incluindo assinaturas | **[Objeto Additional Data](#objeto-additional-data)** |
| **requester_identifier_key** | string | Chave identificadora do solicitante | UUID |
| **purchaser_document_number*** | string | CNPJ do cessionário – O comprador da operação de crédito (FIDC) | 14 |
| **disbursement_bank_accounts*** | array | Dados técnicos da conta bancária onde os recursos serão depositados | **[Objeto Disbursement Bank Account](#objeto-disbursement-bank-account)** |

### Objeto Borrower

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| name* | string | Nome completo do tomador | 100 |
| email | string | Endereço de e-mail do tomador | 254 |
| phone | object | Dados de telefone do tomador | **[Objeto Phone](#objeto-phone)** |
| is_pep* | boolean | Indicador de Pessoa Politicamente Exposta | 5 |
| address* | object | Endereço residencial do tomador | **[Objeto Address](#objeto-address)** |
| role_type | string | Papel do tomador na operação (ex: "issuer") | 10 |
| birth_date* | date | Data de nascimento do tomador (Formato: "YYYY-MM-DD") | 10 |
| person_type* | string | Classificação da pessoa (natural ou legal) | 7 |
| attached_documents_list | array | Lista de documentos anexados (ex: selfie) | **[Objeto Attached Documents](#objeto-attached-documents)** |
| individual_document_number* | string | CPF do tomador - somente números | 11 |

### Objeto Attached Documents

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| selfie | string | DOCUMENT_KEY do documento de selfie enviado via upload | UUID |

### Objeto Address

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| city* | string | Nome da cidade | 100 |
| state* | string | Sigla do estado (duas letras maiúsculas) | 2 |
| number | string | Número do logradouro | 10 |
| street* | string | Nome do logradouro | 100 |
| complement | string | Complemento do endereço (texto livre) | 100 |
| postal_code* | string | CEP - somente números | 8 |
| neighborhood* | string | Nome do bairro | 100 |

### Objeto Phone

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| number* | string | Número do telefone | 9 |
| area_code* | string | Código de área (DDD) | 2 |
| country_code* | string | Código internacional (ex: "055") | 3 |

### Objeto Financial

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| interest_type* | string | Método de amortização | 20 |
| disbursement_date* | string | Data de desembolso | 10 |
| fine_configuration* | object | Configuração de multa e mora | **[Objeto Fine Configuration](#objeto-fine-configuration)** |
| disbursed_amount* | float | Valor a ser desembolsado | 15,2 |
| credit_operation_type* | string | Tipo da operação de crédito (ex: "ccb") | 10 |
| interest_grace_period | integer | Período de carência de juros (em meses) | 3 |
| number_of_installments* | integer | Número de parcelas | 3 |
| principal_grace_period | integer | Período de carência do principal (em meses) | 3 |
| monthly_interest_rate* | float | Taxa de juros mensal | 10,6 |

### Objeto Fine Configuration

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| monthly_rate* | float | Taxa de mora mensal | 10,6 |
| interest_base* | string | Base de cálculo da mora (ex: "calendar_days") | 20 |
| contract_fine_rate* | float | Taxa de multa contratual | 10,6 |

### Objeto Disbursement Bank Account

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| name | string | Nome completo do titular da conta | 50 |
| ispb_number | string | Código ISPB da instituição financeira | 8 |
| account_digit* | string | Dígito verificador da conta (usar zero no lugar de letras) | 1 |
| branch_number* | string | Número da agência (sem dígito verificador) | 4 |
| account_number* | string | Número da conta (sem dígito verificador) | 10 |
| document_number | string | CPF/CNPJ do titular da conta | 14 |
| percentage_receivable* | float | Percentual do desembolso para esta conta | 3 |

### Objeto Additional Data

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| contract* | object | Dados do contrato | **[Objeto Contract](#objeto-contract)** |

### Objeto Contract

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| contract_number* | string | Número identificador único do contrato | 20 |
| signatures* | array | Lista de objetos de evidência de assinatura digital (Opt-in) | **[Objeto Signature](#objeto-signature)** |

### Objeto Signature

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| signer* | object | Dados de identificação do assinante | **[Objeto Signer](#objeto-signer)** |
| signature* | object | Dados de evidência da assinatura digital | **[Objeto Signature Details](#objeto-signature-details)** |

### Objeto Signer

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| name* | string | Nome completo do assinante | 255 |
| document_number* | string | CPF do assinante | 11 |
| email | string | E-mail do assinante | 100 |
| phone | object | Dados de telefone do assinante | **[Objeto Phone](#objeto-phone)** |

### Objeto Signature Details

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| ip_address* | string | Endereço IP utilizado na assinatura | 45 |
| timestamp* | string | Data e hora da assinatura (ISO 8601: YYYY-MM-DDTHH:mm:ssZ) | 24 |
| signature_file* | object | Arquivo da assinatura digital | **[Objeto Signature File](#objeto-signature-file)** |

### Objeto Signature File

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| file_url* | string | Link direto para o documento do contrato assinado (PDF) | 2048 |
| file_type* | string | Formato do arquivo de assinatura (ex: "pdf") | 4 |

## Response

A resposta à requisição de emissão retornará o plano de pagamento e uma **DEBT-KEY**, que é o identificador da dívida na QI SCD.

STATUS 201

Response Body

```json
{
    "webhook_type": "debt",
    "key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c",
    "status": "issued",
    "event_datetime": "2026-04-07 23:59:28",
    "data": {
        "borrower": {
            "name": "Dante Ferrarini",
            "document_number": "31057466093",
            "related_party_key": "24fac77e-7782-4f72-b31a-daee288e34ed"
        },
        "contract": {
            "document_key": null,
            "number": "DWF1761222116",
            "urls": [],
            "signature_information": [
                {
                    "signer_name": "Dante Ferrarini",
                    "signer_document_number": "31057466093",
                    "signer_role": "issuer",
                    "signer_email": null,
                    "signer_external_key": null,
                    "signature_url": null
                }
            ]
        },
        "requester_identifier_key": "d1905ef5-19df-4183-bf0e-802b8229933c",
        "iof_charge_method": "financed",
        "collaterals": [],
        "contract_fees": [
            {
                "fee_type": "spread",
                "fee_amount": 3.02
            }
        ],
        "external_contract_fees": [
            {
                "fee_type": "tac",
                "fee_amount": 0,
                "tax_amount": 0,
                "net_fee_amount": 0
            }
        ],
        "external_contract_fee_amount": 0,
        "net_external_contract_fee_amount": 0,
        "contract_fee_amount": 3.02,
        "issue_amount": 1007.62,
        "assignment_amount": 1010.64,
        "cet": "5,8200%",
        "annual_cet": "97,0501%",
        "number_of_installments": 2,
        "base_iof": 3.79,
        "additional_iof": 3.83,
        "total_iof": 7.62,
        "ipoc_code": "324025020203131057466093DWF1761222116",
        "prefixed_interest_rate": {
            "annual_rate": 0.8373372409,
            "created_at": "2026-04-07T23:59:22",
            "daily_rate": 0.0016911989,
            "interest_base": "calendar_days",
            "monthly_rate": 0.052
        },
        "installments": [
            {
                "accrual_reference_date": null,
                "additional_costs": [],
                "advanced_paid_amount": 0,
                "bank_slip_key": null,
                "business_due_date": "2026-05-07",
                "calendar_days": 30,
                "digitable_line": null,
                "due_date": "2026-05-07",
                "due_interest": 0,
                "due_principal": 1007.62,
                "fine_amount": null,
                "has_interest": true,
                "installment_history": [],
                "installment_key": "1dea396f-beb1-4df3-9822-35800b4c095a",
                "installment_number": 1,
                "installment_payment": [],
                "installment_status": "created",
                "installment_type": "principal",
                "original_due_principal": 1007.62,
                "original_pre_fixed_amount": 52.3996159,
                "original_principal_amortization_amount": 491.4903841,
                "original_total_amount": 543.89,
                "paid_amount": 0,
                "paid_at": null,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 52.3996159,
                "principal_amortization_amount": 491.4903841,
                "qr_code_key": null,
                "qr_code_url": null,
                "renegotiation_proposal_key": null,
                "tax_amount": 1.20906634,
                "total_accrual_amount": null,
                "total_amount": 543.89,
                "total_paid_amount": 0,
                "workdays": 20
            },
            {
                "accrual_reference_date": null,
                "additional_costs": [],
                "advanced_paid_amount": 0,
                "bank_slip_key": null,
                "business_due_date": "2026-06-08",
                "calendar_days": 31,
                "digitable_line": null,
                "due_date": "2026-06-07",
                "due_interest": 0,
                "due_principal": 516.1296159,
                "fine_amount": null,
                "has_interest": true,
                "installment_history": [],
                "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999",
                "installment_number": 2,
                "installment_payment": [],
                "installment_status": "created",
                "installment_type": "principal",
                "original_due_principal": 516.1296159,
                "original_pre_fixed_amount": 27.7603841,
                "original_principal_amortization_amount": 516.1296159,
                "original_total_amount": 543.89,
                "paid_amount": 0,
                "paid_at": null,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 27.7603841,
                "principal_amortization_amount": 516.1296159,
                "qr_code_key": null,
                "qr_code_url": null,
                "renegotiation_proposal_key": null,
                "tax_amount": 2.58168034,
                "total_accrual_amount": null,
                "total_amount": 543.89,
                "total_paid_amount": 0,
                "workdays": 20
            }
        ],
        "total_pre_fixed_amount": 80.16
    }
}
```

:::caution Atenção
Lembre-se de salvar a **DEBT-KEY** retornada, pois ela será necessária para consultas, renegociações e estornos da operação.
:::

### Detalhes do Response Body

| Campo | Tipo | Descrição |
|---|---|---|
| **webhook_type** | string | Identificador do tipo de evento |
| **key** | string | DEBT-KEY — identificador único da dívida na QI SCD (UUID) |
| **status** | string | Status atual da dívida |
| **event_datetime** | string | Data e hora do evento (ISO 8601) |
| **data** | object | **[Objeto Data](#objeto-data)** — Dados da operação |

### Objeto Data

| Campo | Tipo | Descrição |
|---|---|---|
| **borrower** | object | **[Objeto Borrower Response](#objeto-borrower-response)** — Dados do tomador |
| **contract** | object | **[Objeto Contract Response](#objeto-contract-response)** — Dados do contrato |
| **requester_identifier_key** | string | Chave identificadora do solicitante (UUID) |
| **iof_charge_method** | string | Método de cobrança do IOF — sempre "financed" |
| **collaterals** | array | Lista de garantias da operação |
| **contract_fees** | array | **[Objeto Contract Fees](#objeto-contract-fees)** — Taxas QI Tech cobradas na operação |
| **external_contract_fees** | array | **[Objeto External Contract Fees](#objeto-external-contract-fees)** — Taxas externas cobradas na operação |
| **external_contract_fee_amount** | float | Valor total das taxas externas |
| **net_external_contract_fee_amount** | float | Valor líquido das taxas externas após impostos |
| **contract_fee_amount** | float | Valor total das taxas QI Tech |
| **issue_amount** | float | Valor nominal da operação de crédito |
| **assignment_amount** | float | Valor de cessão da operação de crédito |
| **cet** | string | Custo Efetivo Total mensal |
| **annual_cet** | string | Custo Efetivo Total anual |
| **number_of_installments** | integer | Número de parcelas |
| **base_iof** | float | Valor base do IOF |
| **additional_iof** | float | Valor adicional do IOF |
| **total_iof** | float | Valor total do IOF |
| **ipoc_code** | string | Código de registro de crédito brasileiro gerado pela QI Tech |
| **prefixed_interest_rate** | object | **[Objeto Interest Rate Response](#objeto-interest-rate-response)** — Taxa de juros nominal |
| **installments** | array | **[Objeto Installments Response](#objeto-installments-response)** — Parcelas da operação |
| **total_pre_fixed_amount** | float | Valor total dos juros pré-fixados de todas as parcelas |

### Objeto Borrower Response

| Campo | Tipo | Descrição |
|---|---|---|
| **name** | string | Nome completo do tomador |
| **document_number** | string | CPF do tomador |
| **related_party_key** | string | Identificador único do tomador na QI Tech (UUID) |

### Objeto Contract Response

| Campo | Tipo | Descrição |
|---|---|---|
| **document_key** | string | Chave do documento do contrato |
| **number** | string | Número do contrato |
| **urls** | array | Lista de URLs do documento do contrato |
| **signature_information** | array | **[Objeto Signature Information](#objeto-signature-information)** — Informações de assinatura |

### Objeto Signature Information

| Campo | Tipo | Descrição |
|---|---|---|
| **signer_name** | string | Nome completo do assinante |
| **signer_document_number** | string | CPF do assinante |
| **signer_role** | string | Papel do assinante na operação |
| **signer_email** | string | E-mail do assinante |
| **signer_external_key** | string | Chave externa do assinante |
| **signature_url** | string | URL do documento assinado |

### Objeto Contract Fees

| Campo | Tipo | Descrição |
|---|---|---|
| **fee_type** | string | Tipo da taxa |
| **fee_amount** | float | Valor da taxa |

### Objeto External Contract Fees

| Campo | Tipo | Descrição |
|---|---|---|
| **fee_type** | string | Tipo da taxa externa |
| **fee_amount** | float | Valor da taxa externa |
| **tax_amount** | float | Valor do imposto sobre a taxa |
| **net_fee_amount** | float | Valor líquido da taxa após impostos |

### Objeto Interest Rate Response

| Campo | Tipo | Descrição |
|---|---|---|
| **annual_rate** | float | Taxa de juros anual |
| **created_at** | string | Timestamp de criação da taxa (ISO 8601) |
| **daily_rate** | float | Taxa de juros diária |
| **interest_base** | string | Base de cálculo dos juros |
| **monthly_rate** | float | Taxa de juros mensal |

### Objeto Installments Response

| Campo | Tipo | Descrição |
|---|---|---|
| **accrual_reference_date** | string | Data de referência de cálculo da parcela |
| **additional_costs** | array | Lista de custos adicionais da parcela |
| **advanced_paid_amount** | float | Valor pago antecipadamente |
| **bank_slip_key** | string | Chave do boleto bancário |
| **business_due_date** | string | Data de vencimento ajustada para o próximo dia útil |
| **calendar_days** | integer | Dias corridos entre parcelas |
| **digitable_line** | string | Linha digitável do boleto |
| **due_date** | string | Data de vencimento da parcela |
| **due_interest** | float | Valor de juros remanescente na data de vencimento antes do pagamento |
| **due_principal** | float | Saldo devedor no momento da parcela |
| **fine_amount** | float | Valor de multa aplicado |
| **has_interest** | boolean | Indicador de incidência de juros na parcela |
| **installment_history** | array | Histórico de eventos da parcela |
| **installment_key** | string | Identificador único da parcela (UUID) |
| **installment_number** | integer | Número da parcela |
| **installment_payment** | array | Lista de pagamentos realizados na parcela |
| **installment_status** | string | Status atual da parcela |
| **installment_type** | string | Tipo da parcela — sempre "principal" |
| **original_due_principal** | float | Saldo devedor original no momento da emissão |
| **original_pre_fixed_amount** | float | Valor original dos juros pré-fixados na emissão |
| **original_principal_amortization_amount** | float | Valor original de amortização do principal na emissão |
| **original_total_amount** | float | Valor total original da parcela na emissão |
| **paid_amount** | float | Valor já pago na parcela |
| **paid_at** | string | Data do pagamento |
| **post_fixed_amount** | float | Valor dos juros pós-fixados — sempre 0 |
| **pre_fixed_amount** | float | Valor atual dos juros pré-fixados |
| **principal_amortization_amount** | float | Valor de amortização do principal |
| **qr_code_key** | string | Chave do QR Code PIX |
| **qr_code_url** | string | URL do QR Code PIX |
| **renegotiation_proposal_key** | string | Chave da proposta de renegociação, se aplicável |
| **tax_amount** | float | Valor do IOF na parcela |
| **total_accrual_amount** | float | Valor total de juros acumulados |
| **total_amount** | float | Valor total da parcela |
| **total_paid_amount** | float | Valor total pago na parcela até o momento |
| **workdays** | integer | Dias úteis entre parcelas |

---

# Simulação - Emissão BNPL

URL: /documentation/manual_bnpl_full/emissao/simulacao

# Simulação - Emissão BNPL


## Resumo

Na QI Tech, disponibilizamos aos nossos clientes a possibilidade de simular os valores de uma operação de crédito antes de sua emissão efetiva. A simulação segue o mesmo padrão da requisição de emissão de dívida, porém não é necessário fornecer os dados cadastrais do tomador e da conta de desembolso.

## Request

ENDPOINT /v2/credit_operation/simulation
MÉTODO POST

Testar no Playground

Request Body

```json
{
    "credit_operation_type": "ccb",
    "disbursed_issue_amount": 2800,
    "disbursement_date": "2025-09-24",
    "first_due_date": "2025-10-24",
    "force_installments_on_workdays": true,
    "interest_type": "pre_price_days",
    "issuer_person_type": "natural",
    "monthly_interest_rate": 0.04488,
    "number_of_installments": 2,
    "principal_amortization_month_period": 1
}
```


### Detalhes do Request Body

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| **credit_operation_type*** | string | Tipo de operação de crédito | **[Enumerador Credit Operation Type](#enumerador-credit-operation-type)** |
| **disbursed_issue_amount*** | float | Valor efetivamente liberado ao tomador | 15,2 |
| **disbursement_date*** | string | Data em que os recursos do empréstimo serão disponibilizados | 10 |
| **first_due_date*** | string | Data de vencimento da primeira parcela | 10 |
| **force_installments_on_workdays*** | boolean | Se verdadeiro, garante que todas as datas de vencimento das parcelas sejam movidas para o próximo dia útil | - |
| **interest_type*** | string | Método de amortização | **[Enumerador Interest Type](#enumerador-interest-type)** |
| **issuer_person_type*** | string | Define se o emissor é pessoa física ou jurídica | **[Enumerador Person Type](#enumerador-person-type)** |
| **monthly_interest_rate*** | float | Taxa de juros mensal aplicada sobre o saldo principal | 10,6 |
| **number_of_installments*** | integer | Número de parcelas | 3 |
| **principal_amortization_month_period*** | integer | Período, em meses, entre as parcelas | 1 |

### Enumerador Credit Operation Type

| Valor | Descrição |
|---|---|
| `ccb` | Cédula de Crédito Bancário |

### Enumerador Interest Type

| Valor | Descrição |
|---|---|
| `pre_price_days` | Juros pré-fixados com amortização Price por dias corridos |
| `pre_price` | Juros pré-fixados com amortização Price por meses |
| `pre_sac` | Juros pré-fixados com amortização SAC |

### Enumerador Person Type

| Valor | Descrição |
|---|---|
| `natural` | Pessoa física |
| `legal` | Pessoa jurídica |

## Response

STATUS 200

Response Body

```json
{
    "disbursement_date": "2025-09-24",
    "issue_amount": 2821.32,
    "interest_type": "pre_price_days",
    "assignment_amount": 2829.78,
    "base_iof": 10.6,
    "total_iof": 21.32,
    "additional_iof": 10.72,
    "cet": 5.09,
    "annual_cet": 81.39,
    "first_due_date": "2025-10-24",
    "disbursed_amount": 2800,
    "prefixed_interest_rate": {
        "annual_rate": 0.6935459998,
        "daily_rate": 0.0014644728,
        "interest_base": "calendar_days",
        "monthly_rate": 0.04488
    },
    "tax_configuration": {
        "base_rate": 8.2e-05,
        "additional_rate": 0.0038
    },
    "fees": [
        {
            "amount": 0.3,
            "fee_amount": 8.46,
            "amount_type": "percentage",
            "fee_type": "spread",
            "type": "internal"
        }
    ],
    "installments": [
        {
            "due_date": "2025-10-24",
            "amount": 1507.4,
            "due_principal": 2821.32,
            "due_interest": 0,
            "has_interest": true,
            "period": 1,
            "period_workdays": 1.1,
            "calendar_days": 30,
            "workdays": 22,
            "installment_number": 1,
            "period_to_disbursement": 1,
            "prefixed_amount": 126.62248868,
            "period_workdays_to_disbursement": 1.1,
            "calendar_days_to_disbursement": 30,
            "workdays_to_disbursement": 22,
            "tax_amount": 3.39671268,
            "principal_amortization_amount": 1380.77751132
        },
        {
            "due_date": "2025-11-24",
            "amount": 1507.4,
            "due_principal": 1440.54248868,
            "due_interest": 0,
            "has_interest": true,
            "period": 1,
            "period_workdays": 1,
            "calendar_days": 31,
            "workdays": 20,
            "installment_number": 2,
            "period_to_disbursement": 2,
            "prefixed_amount": 66.85751132,
            "period_workdays_to_disbursement": 2.1,
            "calendar_days_to_disbursement": 61,
            "workdays_to_disbursement": 42,
            "tax_amount": 7.20559353,
            "principal_amortization_amount": 1440.54248868
        }
    ]
}
```


### Detalhes do Response Body

| Campo | Tipo | Descrição |
|---|---|---|
| **annual_cet** | float | Custo Efetivo Total anualizado expresso em decimal |
| **assignment_amount** | float | Valor de cessão da operação de crédito |
| **cet** | float | Custo Efetivo Total mensal expresso em decimal |
| **fees** | array | **[Objeto Fees](#objeto-fees)** - Lista de taxas da QI Tech cobradas na operação |
| **disbursed_amount** | float | Valor desembolsado na operação de crédito |
| **disbursement_date** | string | Data de desembolso da operação |
| **installments** | array | **[Objeto Installments](#objeto-installments)** - Parcelas da operação |
| **interest_type** | string | Método de amortização e cálculo de juros |
| **additional_iof** | float | IOF adicional aplicado sobre o principal da transação |
| **base_iof** | float | Base de cálculo do IOF |
| **total_iof** | float | Valor total do IOF aplicado na transação |
| **issue_amount** | float | Valor nominal da operação de crédito |
| **tax_configuration** | object | **[Objeto Tax Configuration](#objeto-tax-configuration)** - Valores das taxas de IOF |
| **first_due_date** | string | Data de vencimento da primeira parcela |
| **prefixed_interest_rate** | object | **[Objeto Interest Rate](#objeto-interest-rate)** - Taxa de juros nominal |

### Objeto Fees

| Campo | Tipo | Descrição |
|---|---|---|
| **amount** | float | Valor ou percentual da taxa |
| **fee_amount** | float | Valor monetário da taxa |
| **amount_type** | string | Tipo do valor (percentage ou fixed) |
| **fee_type** | string | Tipo da taxa |
| **type** | string | Classificação da taxa (internal ou external) |

### Objeto Installments

| Campo | Tipo | Descrição |
|---|---|---|
| **due_date** | string | Data de vencimento da parcela |
| **amount** | float | Valor total da parcela |
| **due_principal** | float | Saldo devedor no momento da parcela |
| **due_interest** | float | Valor de juros remanescente na data de vencimento antes do pagamento |
| **has_interest** | boolean | Indicador de incidência de juros na parcela |
| **installment_number** | integer | Número da parcela |
| **prefixed_amount** | float | Valor dos juros pré-fixados pagos na parcela |
| **tax_amount** | float | Valor do IOF na parcela |
| **principal_amortization_amount** | float | Valor de amortização do principal |
| **period** | float | Período da parcela |
| **period_workdays** | float | Período da parcela em dias úteis |
| **period_to_disbursement** | float | Número de períodos acumulados desde o desembolso até a parcela |
| **period_workdays_to_disbursement** | float | Número de períodos em dias úteis acumulados desde o desembolso até a parcela |
| **calendar_days** | integer | Dias corridos entre parcelas |
| **calendar_days_to_disbursement** | integer | Dias corridos acumulados desde o desembolso até a parcela |
| **workdays** | integer | Dias úteis entre parcelas |
| **workdays_to_disbursement** | integer | Dias úteis acumulados desde o desembolso até a parcela |

### Objeto Tax Configuration

| Campo | Tipo | Descrição |
|---|---|---|
| **base_rate** | float | Taxa base do IOF |
| **additional_rate** | float | Taxa adicional do IOF |

### Objeto Interest Rate

| Campo | Tipo | Descrição |
|---|---|---|
| **annual_rate** | float | Taxa de juros anual |
| **daily_rate** | float | Taxa de juros diária |
| **interest_base** | string | Base de cálculo dos juros |
| **monthly_rate** | float | Taxa de juros mensal |

---

# Webhooks - Emissão BNPL

URL: /documentation/manual_bnpl_full/emissao/webhooks

## Resumo

Após a resposta de sucesso da emissão, você receberá webhooks notificando sobre os eventos do ciclo de vida da operação: assinatura do contrato, desembolso e, eventualmente, cancelamento.

:::danger Atenção!
Os webhooks não devem ser mapeados de forma estrita. Novos campos podem ser adicionados ao payload sem aviso prévio.
:::

## Webhook de Assinatura

Este webhook é enviado quando o contrato (CCB) é assinado com sucesso.

WEBHOOK_TYPE debt
STATUS signature_finished

Webhook Body

```json
{
    "key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "status": "signature_finished",
    "webhook_type": "debt",
    "event_datetime": "2025-10-27T17:09:33Z",
    "signed_contract_url": "https://storage.googleapis.com/sandbox-doc-api/documents/c8b191cb-7b90-4e37-9280-397a597babc1/CCB-TIK11267101212-20251027170925_signed.pdf"
}
```

### Campos do Webhook de Assinatura

| Campo | Tipo | Descrição |
|---|---|---|
| **key** | string | Chave única da dívida (DEBT-KEY) |
| **status** | string | Status do evento: `signature_finished` |
| **webhook_type** | string | Tipo do webhook: `debt` |
| **event_datetime** | string | Data e hora do evento |
| **signed_contract_url** | string | URL do contrato assinado (PDF) |

## Webhook de Desembolso

Este webhook confirma que o desembolso foi realizado com sucesso.

WEBHOOK_TYPE debt
STATUS disbursed

Webhook Body

```json
{
    "key": "132372de-fead-488f-9fae-b6c2986182be",
    "data": {
      "installments": [
        {
          "due_date": "2026-04-27",
          "total_amount": 89.48,
          "installment_key": "470c69cd-2a3e-4a17-9003-819e9d37a510",
          "pre_fixed_amount": 5.60437824,
          "installment_number": 1,
          "principal_amortization_amount": 83.87562176
        },
        {
          "due_date": "2026-05-26",
          "total_amount": 89.48,
          "installment_key": "c190c72d-2ea8-478c-b85b-041c0f402a0c",
          "pre_fixed_amount": 8.00493898,
          "installment_number": 2,
          "principal_amortization_amount": 81.47506102
        },
        {
          "due_date": "2026-06-26",
          "total_amount": 89.48,
          "installment_key": "07c40e11-400d-4675-8a57-b9bee9e4b21c",
          "pre_fixed_amount": 6.90959582,
          "installment_number": 3,
          "principal_amortization_amount": 82.57040418
        },
        {
          "due_date": "2026-07-27",
          "total_amount": 89.48,
          "installment_key": "43dfc3ec-99ed-4b86-9105-a126c69ca1ea",
          "pre_fixed_amount": 5.23461479,
          "installment_number": 4,
          "principal_amortization_amount": 84.24538521
        },
        {
          "due_date": "2026-08-26",
          "total_amount": 89.48,
          "installment_key": "104c9564-488c-44f4-ba50-5c1e87c145a7",
          "pre_fixed_amount": 3.4109145,
          "installment_number": 5,
          "principal_amortization_amount": 86.0690855
        },
        {
          "due_date": "2026-09-28",
          "total_amount": 89.48,
          "installment_key": "aa073681-d11c-4349-ad4a-64f68538447c",
          "pre_fixed_amount": 1.89555767,
          "installment_number": 6,
          "principal_amortization_amount": 87.58444233
        }
      ],
      "ted_receipt_list": [
        {
          "fee": 0,
          "url": "https://storage.googleapis.com/sandbox-doc-api/documents/491e-b208-ddf5addab58d/1043ce73-b366-491e-ddf5addab58d.pdf",
          "amount": 500.0,
          "origin": {
            "name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
            "type": "payment_account",
            "branch": "0001",
            "document": "32402502000135",
            "bank_code": "329",
            "account_key": "5d068423-6094-49e4-b15b-7740038295a8",
            "branch_digit": null,
            "account_digit": "5",
            "account_branch": "0001",
            "account_number": "00002",
            "financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A."
          },
          "timestamp": "2026-04-10T14:48:35",
          "description": "00360305 0001 12345-6 12345678000199 - NEXUS TECH SOLUTIONS",
          "destination": {
            "name": "NEXUS TECH SOLUTIONS",
            "type": "checking_account",
            "branch": "0001",
            "purpose": "Crédito PIX em Conta",
            "document": "12345678000199",
            "bank_ispb": "00360305",
            "branch_digit": null,
            "account_digit": "6",
            "account_number": "12345",
            "financial_institution_name": "BANCO HORIZONTE S.A."
          },
          "end_to_end_id": "E00360305202604151954bB7qwX9pzKL0",
          "transaction_key": "2fb21861-b43c-4bbc-85d8-ece2aaf6328e",
          "origin_transaction_key": "dbd8af8d-c372-4d1b-8d9a-24527286d80a"
        }
      ],
      "requester_identifier_key": "65caad48-976c-44ea-8e34-c8519241981d"
    },
    "status": "disbursed",
    "webhook_type": "debt",
    "event_datetime": "2026-04-10 14:48:35"
  }
```

### Campos do Webhook de Desembolso

| Campo | Tipo | Descrição |
|---|---|---|
| **key** | string | Chave única da dívida (DEBT-KEY) |
| **status** | string | Status do evento: `disbursed` |
| **webhook_type** | string | Tipo do webhook: `debt` |
| **event_datetime** | string | Data e hora do evento |
| **data.installments** | array | Lista de parcelas com suas chaves e valores |
| **data.ted_receipt_list** | array | Lista de comprovantes de TED (quando aplicável) |

## Webhook de Cancelamento

Se a dívida falhar no desembolso ou for devolvida, você receberá um webhook de cancelamento.

WEBHOOK_TYPE debt
STATUS canceled

Webhook Body

```json
{
    "webhook_type": "debt",
    "key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "event_datetime": "2025-10-27T16:38:59Z",
    "data": {
        "cancel_reason": "Operacao cancelada manualmente",
        "cancel_reason_enumerator": "manual"
    },
    "status": "canceled"
}
```

### Campos do Webhook de Cancelamento

| Campo | Tipo | Descrição |
|---|---|---|
| **key** | string | Chave única da dívida (DEBT-KEY) |
| **status** | string | Status do evento: `canceled` |
| **webhook_type** | string | Tipo do webhook: `debt` |
| **event_datetime** | string | Data e hora do evento |
| **data.cancel_reason** | string | Descrição textual do motivo do cancelamento |
| **data.cancel_reason_enumerator** | string | Enumerador do motivo do cancelamento |

### Enumeradores de Cancelamento

| Enumerador | Descrição |
|---|---|
| `disbursing_error` | Operação cancelada por erro durante o desembolso |
| `waiting_signature` | Operação cancelada por falta de assinatura |
| `pix_max_retry` | Operação cancelada porque o banco receptor não processou o desembolso |
| `manual` | Operação cancelada manualmente |
| `agencia_conta_invalida` | Agência ou número de conta do destinatário inválidos |
| `invalid_account` | Número da conta de destino inexistente ou inválido |
| `invalid_document_number` | CPF/CNPJ da conta de destino incorreto |
| `unsupported_transaction` | A conta de destino não suporta este tipo de transação |
| `invalid_ispb` | O número ISPB é inválido ou inexistente |
| `rejected_payment` | Ordem de pagamento rejeitada pelo banco receptor |
| `refund_after_payee_request` | Estorno solicitado pelo beneficiário |
| `blocked_account` | A conta de destino está bloqueada |
| `amount_too_great` | Valor excede o limite da conta de destino |
| `receiver_error` | Transação interrompida por erro no PSP do receptor |
| `closed_account` | A conta de destino está encerrada |
| `disbursing_hour_closed` | Desembolso fora do horário permitido |
| `unregistered_pix_key` | A chave Pix não está registrada |
| `spi_timeout` | Timeout no controle SPI |

---

# Estorno BNPL

URL: /documentation/manual_bnpl_full/estorno/

# Estorno BNPL


## Resumo

O estorno de uma operação BNPL permite reverter o desembolso realizado. Existem três cenários de cancelamento/estorno:

1. **Cancelamento antes do desembolso**: Cancela a operação antes que os recursos sejam transferidos
2. **Estorno após o desembolso — via Pix de devolução (até 7 dias)**: Gera um Pix copia-e-cola para que o tomador devolva os recursos
3. **Estorno após o desembolso — via conta interna QI**: A devolução é feita diretamente pela conta interna da QI Tech, sem ação do tomador

---

## 1. Cancelamento Antes do Desembolso

Cancela uma operação de crédito que ainda não foi desembolsada.

### Request

ENDPOINT /debt/ DEBT-KEY /cancel
MÉTODO PATCH

Testar no Playground

### Path Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `debt_key`* | string | Chave única da dívida retornada no momento da criação da operação de crédito | UUID |

### Response

STATUS 200

Response Body

```json
{}
```

:::caution Atenção
Este endpoint só pode ser utilizado para operações que ainda **não foram desembolsadas**. Para operações já desembolsadas, utilize o endpoint de estorno abaixo.
:::

---

## 2. Estorno Após o Desembolso — Via Pix de Devolução (Até 7 Dias)

Utilizado quando o parceiro deseja solicitar ao tomador que devolva os recursos via Pix. O sistema gera um Pix copia-e-cola para que o tomador realize a devolução. Assim que o pagamento é confirmado, a operação é cancelada automaticamente.

:::info Quando usar
Use este endpoint quando o estorno deve ser realizado pelo **próprio tomador**, que receberá um Pix de devolução para pagar.
:::

### Request

ENDPOINT /debt/reversal
MÉTODO POST

Testar no Playground

Request Body

```json
{
    "credit_operation_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c"
}
```


### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `credit_operation_key`* | string | Chave da operação de crédito (DEBT-KEY) | UUID |

### Response

STATUS 200

Response Body

```json
{
    "payer_name": "Dante Ferrarini",
    "payer_document_number": "31057466093",
    "amount": 1000,
    "expiration_date": "2026-04-28",
    "copy_paste_pix": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/fb1906ab2eff40109609855ac104f60e5204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***63046387",
    "reversal_key": "7a18fdb6-a3e7-4fc9-833e-0f6d8e98de3b",
    "status": "active",
    "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c",
    "qr_code_key": "fb1906ab-2eff-4010-9609-855ac104f60e"
}
```


### Detalhes do Response

| Campo | Tipo | Descrição |
|---|---|---|
| **payer_name** | string | Nome do tomador |
| **payer_document_number** | string | CPF/CNPJ do tomador |
| **amount** | float | Valor total a ser devolvido |
| **expiration_date** | string | Data de expiração do Pix de devolução |
| **copy_paste_pix** | string | Código Pix copia-e-cola para devolução dos recursos |
| **reversal_key** | string | Chave única do estorno (UUID) |
| **status** | string | Status do estorno: `active` |
| **debt_key** | string | Chave da dívida (DEBT-KEY) |
| **qr_code_key** | string | Chave do QR Code Pix (UUID) |

:::warning Importante
- O estorno só pode ser realizado dentro de **7 dias corridos** após o desembolso
- O `copy_paste_pix` gerado possui uma **data de expiração**. Após essa data, o Pix não poderá mais ser utilizado
- Após o pagamento do Pix pelo tomador, a operação será cancelada automaticamente e você receberá um webhook de cancelamento
:::

---

## 3. Estorno Após o Desembolso — Via Conta Interna QI

Utilizado quando a devolução dos recursos é realizada diretamente pela **conta interna da QI Tech**, sem necessidade de ação do tomador. Indicado para o método `internal`, onde o valor é debitado internamente sem geração de Pix.

:::info Quando usar
Use este endpoint quando o estorno é operado pelo **parceiro via conta interna da QI Tech**, sem envolver o tomador no processo de devolução.
:::

### Request

ENDPOINT /credit_operation/ CREDIT-OPERATION-KEY /reversal
MÉTODO PUT

:::info Header obrigatório
Envie o header `SELECTED-AGENT` com o valor do seu `requester_key`.
:::

### Path Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `credit_operation_key`* | string | Chave da operação de crédito (DEBT-KEY) | UUID |

Request Body (opcional)

```json
{
    "cancel_reason": "reversed_manually"
}
```


### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `cancel_reason` | string | Motivo do estorno. Se não informado, o sistema utilizará o padrão. | - |

---

# Estorno via Amortização — equal_amount e full_settle

URL: /documentation/manual_bnpl_full/estorno/estorno_amortizacao

## Resumo

Além dos fluxos de cancelamento antes do desembolso e estorno via Pix nos primeiros 7 dias (ver [Estorno BNPL](./estorno.md)), o BNPL Full oferece **duas modalidades de estorno por amortização**, que executam o retorno dos recursos debitando diretamente uma conta interna do parceiro:

- **`equal_amount`** — estorno **parcial**. Distribui o valor informado proporcionalmente entre as parcelas da operação, reduzindo o saldo devedor. A operação continua ativa, com as parcelas restantes em aberto.
- **`full_settle`** — estorno **total**. Quita integralmente a operação em uma única transação, calculando o valor presente de todas as parcelas na `reference_date`. Após a liquidação, a operação é marcada como `settled` e não há parcelas remanescentes.

Ambas as modalidades utilizam o endpoint `POST /renegotiation/proposal` com `payment_type: "internal"`, o que significa que o valor é movimentado diretamente da conta informada em `account_key`, sem geração de boleto ou Pix.

---

## Quando usar cada modalidade

### `equal_amount` — Estorno Parcial

Use quando o tomador deseja **reduzir** o saldo devedor sem encerrar a operação. O valor enviado em `payment_amount` é distribuído entre as parcelas, abatendo principal, juros e eventual multa. As parcelas que ainda não foram totalmente amortizadas continuam em `remaining_installments` para cobrança nos próximos vencimentos.

Casos típicos:

- Cliente pagou a mais e quer abater apenas parte da dívida.
- Retorno parcial de recursos acordado entre parceiro e tomador.
- Aplicação de créditos ou devoluções pontuais em operações ativas.

### `full_settle` — Estorno Total

Use quando o objetivo é **quitar** a operação por completo. O sistema calcula o valor presente de todas as parcelas abertas na `reference_date` (principal + juros acumulados + eventual multa) e distribui o `payment_amount` até zerar o saldo. A operação passa ao status `settled`.

Casos típicos:

- Estorno após o prazo de 7 dias do `POST /debt/reversal`.
- Quitação antecipada solicitada pelo tomador.
- Encerramento administrativo da operação com retorno integral dos recursos.

:::info Sequenciamento
É possível combinar as duas modalidades. Por exemplo: várias chamadas `equal_amount` para amortizações parciais, seguidas de um `full_settle` final para quitar o saldo remanescente.
:::

---

## Request

ENDPOINT /renegotiation/proposal
MÉTODO POST

Testar no Playground

Request Body

**equal_amount (parcial)**

```json
{
    "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c",
    "payment_type": "internal",
    "amortization_type": "equal_amount",
    "reference_date": "2026-04-13",
    "payment_amount": 50.00,
    "account_key": "5ae72355-1e47-4624-9915-ceb93d872194",
    "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db"
}
```

**full_settle (total)**

```json
{
    "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c",
    "payment_type": "internal",
    "amortization_type": "full_settle",
    "reference_date": "2026-04-13",
    "payment_amount": 1043.55,
    "account_key": "5ae72355-1e47-4624-9915-ceb93d872194",
    "request_control_key": "e5f6c3d4-e5f6-7890-abcd-ef1234567890"
}
```

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `debt_key`* | string | Chave única da operação de crédito a ser estornada | UUID |
| `payment_type`* | string | Deve ser `internal` para estorno via conta interna | 8 |
| `amortization_type`* | string | Modalidade do estorno | **[Enumeradores Amortization Type](#enumeradores-amortization-type)** |
| `reference_date`* | string | Data de referência para cálculo do valor presente (formato `YYYY-MM-DD`) | 10 |
| `payment_amount`* | float | Valor do estorno em reais (R$). Em `equal_amount`, é o valor parcial a ser abatido. Em `full_settle`, deve cobrir o saldo total na `reference_date` | 15,2 |
| `account_key`* | string | Chave da conta interna de onde o valor será debitado | UUID |
| `request_control_key`* | string | Chave de controle da requisição (idempotência) | UUID |

### Enumeradores Amortization Type

| Valor | Descrição |
|---|---|
| **`equal_amount`** | Estorno parcial. `payment_amount` é distribuído proporcionalmente entre as parcelas; a operação permanece ativa com as parcelas remanescentes em aberto. |
| **`full_settle`** | Estorno total. Quita integralmente a operação na `reference_date`. A operação passa a `settled` e não há parcelas remanescentes. |

---

## Response

STATUS 201

Response Body

```json
{
    "proposal_key": "bcc16a6d-ce21-4cd4-8d8c-d26f89ccc685",
    "contract_number": "DWF1761222116",
    "amortization_type": "equal_amount",
    "payment_amount": 50.00,
    "discount_percentage": 0,
    "discount_amount": 0,
    "requester_name": "Dante Ltda",
    "requester_key": "78287247-947d-4730-9bd1-7efb068175b6",
    "origin_key": null,
    "issuer_name": "Dante Ferrarini",
    "issuer_document_number": "31057466093",
    "affected_installments": [
        {
            "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88",
            "due_date": "2026-05-07",
            "principal_amount": 15.71,
            "interest_amount": 4.07,
            "fine_amount": 0,
            "total_amount": 19.78,
            "present_amount": 18.00,
            "paid_amount": 18.00,
            "principal_amortization_payment_amount": 18.00,
            "prefixed_interest_payment_amount": 0,
            "fine_payment_amount": 0
        }
    ],
    "remaining_installments": [
        {
            "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999",
            "due_date": "2026-06-07",
            "principal_amount": 15.71,
            "interest_amount": 4.07,
            "fine_amount": 0,
            "total_amount": 19.78
        }
    ],
    "proposal_status": "pending_payment",
    "payment_type": "internal",
    "payment": {
        "digitable_line": null,
        "qr_code_url": null,
        "qr_code_key": null,
        "bank_slip_key": null,
        "paid_method_type": "internal",
        "source_account_key": "5ae72355-1e47-4624-9915-ceb93d872194",
        "payment_data": {
            "target_account_key": "6108dd45-580d-48c4-b3bb-74c1e843be49",
            "transaction_amount": 50.00
        }
    },
    "proposal_due_date": "2026-04-13",
    "reference_date": "2026-04-13",
    "devolution_amount": 0,
    "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db"
}
```

### Detalhes do Response

| Campo | Tipo | Descrição |
|---|---|---|
| `proposal_key` | string | Chave única da proposta de estorno (UUID). Guarde para consultas e webhooks. |
| `amortization_type` | string | Modalidade utilizada (`equal_amount` ou `full_settle`). |
| `payment_amount` | float | Valor efetivamente aplicado no estorno. |
| `proposal_status` | string | Estado da proposta. Inicia em `pending_payment` e transiciona para `paid` após o débito interno. |
| `affected_installments` | array | Parcelas que receberam o valor do estorno. Para cada parcela, mostra a composição do `paid_amount` entre principal, juros e multa. |
| `remaining_installments` | array | Parcelas que permanecem em aberto após o estorno. Em `full_settle`, vem vazio. |
| `payment.payment_data.target_account_key` | string | Conta de destino do débito interno. |
| `payment.payment_data.transaction_amount` | float | Valor efetivamente movimentado da `account_key`. |
| `devolution_amount` | float | Valor de sobrepagamento devolvido ao fundo. Só é diferente de zero quando já existe um pagamento prévio na operação e o estorno somado a esse pagamento excede o saldo devedor — o excedente é retornado via este campo. |
| `request_control_key` | string | Eco da chave de idempotência enviada no request. |

---

## Regras e observações

:::caution Atenção

- **Estado da operação**: a operação deve estar ativa e desembolsada. Operações ainda não desembolsadas devem ser canceladas via `PATCH /debt/{debt_key}/cancel`.
- **`reference_date`**: determina o cálculo de juros e multa. Em `full_settle`, todo o saldo é trazido a valor presente nesta data. **Não pode ser anterior à data de desembolso da operação** — esse é o limite mínimo permitido.
- **Parcelas em atraso**: quando há parcelas vencidas, o `paid_amount` da parcela afetada é distribuído entre `principal_amortization_payment_amount`, `prefixed_interest_payment_amount` e `fine_payment_amount`. Verifique o detalhamento no array `affected_installments`.
- **Idempotência**: `request_control_key` é obrigatório. Use um UUID único por tentativa para evitar duplicações.
- **`full_settle` com valor insuficiente**: se `payment_amount` for menor que o saldo total calculado, o débito ainda é processado e distribuído proporcionalmente — verifique o status final da operação para confirmar a quitação.

:::

:::info Combinando modalidades

- Várias propostas `equal_amount` podem ser feitas em sequência, cada uma abatendo uma parte do saldo.
- Um `full_settle` pode ser feito após uma ou mais propostas `equal_amount` para encerrar o saldo remanescente.
- Cada proposta é independente e deve usar um `request_control_key` distinto.

:::

---

## Consultar status da proposta

Após criar a proposta, consulte seu status pelo `request_control_key` informado no request.

ENDPOINT /renegotiation/proposal/request_control_key/ REQUEST-CONTROL-KEY
MÉTODO GET

### Path Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `request_control_key`* | string | Chave de controle enviada na criação da proposta | UUID |

O response segue o mesmo formato do retorno do `POST`. O campo `proposal_status` indica o andamento:

| Status | Descrição |
|---|---|
| `pending_payment` | Proposta criada, aguardando o processamento do débito interno. |
| `paid` | Débito processado. Em `full_settle`, a operação já está em `settled`. |

---

## Webhook de Quitação

Quando um estorno resulta na quitação integral da operação — tipicamente em `full_settle`, mas também em casos de `equal_amount` cujo somatório zera o saldo devedor — o sistema envia um webhook do tipo `debt` com status `settled`.

WEBHOOK_TYPE debt
STATUS settled

Use este webhook para confirmar, de forma assíncrona, que a operação foi encerrada após o processamento do débito interno. O payload completo e os campos seguem o padrão descrito em [Webhooks - Estorno BNPL](./webhooks.md).

---

# Webhooks - Estorno BNPL

URL: /documentation/manual_bnpl_full/estorno/webhooks

## Resumo

Após a criação de um pedido de estorno, o sistema enviará webhooks para notificar sobre os eventos do processo de reversão.

:::danger Atenção!
Os webhooks não devem ser mapeados de forma estrita. Novos campos podem ser adicionados ao payload sem aviso prévio.
:::

## Webhook de Cancelamento por Estorno

Quando o tomador realiza o pagamento do Pix de devolução gerado pelo estorno, a operação de crédito é cancelada automaticamente e o seguinte webhook é enviado:

WEBHOOK_TYPE debt
STATUS canceled

Webhook Body

```json
{
    "webhook_type": "debt",
    "key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "event_datetime": "2025-10-27T16:38:59Z",
    "data": {
        "cancel_reason": "Operacao cancelada por estorno",
        "cancel_reason_enumerator": "refund_after_payee_request"
    },
    "status": "canceled"
}
```

### Campos do Webhook

| Campo | Tipo | Descrição |
|---|---|---|
| **webhook_type** | string | Tipo do webhook: `debt` |
| **key** | string | Chave única da dívida (DEBT-KEY) |
| **event_datetime** | string | Data e hora do evento |
| **status** | string | Status do evento: `canceled` |
| **data.cancel_reason** | string | Descrição textual do motivo do cancelamento |
| **data.cancel_reason_enumerator** | string | Enumerador do motivo do cancelamento |

### Enumeradores de Cancelamento Relacionados a Estorno

| Enumerador | Descrição |
|---|---|
| `refund_after_payee_request` | Estorno solicitado pelo beneficiário |
| `manual` | Operação cancelada manualmente |
| `disbursing_error` | Operação cancelada por erro durante o desembolso |

---

## Webhook de Liquidação de Estorno (Transaction Reversal)

Para estornos processados via o endpoint de `transaction_reversal`, o webhook de confirmação segue o formato abaixo:

WEBHOOK_TYPE transaction_reversal.transaction_reversal_status_change
STATUS paid

Webhook Body

```json
{
    "data": {
        "transaction_reversal_key": "b6da1a84-5bb3-4d71-9912-cbbcfe7189c1",
        "amount": 123.45,
        "status": "paid",
        "description": "Valor de liquidação indevido",
        "reference_date": "2025-03-23",
        "fund_class_document_number": "12.345.678/0009-10",
        "fund_class_key": "0619574f-2815-419d-8208-630b0dc30487",
        "source_account": {
            "account_digit": "7",
            "account_branch": "0001",
            "account_number": "0099999",
            "owner": {
                "name": "FUNDO DE INVESTIMENTO",
                "document_number": "12.345.678/0009-10"
            },
            "financial_institution": {
                "code": "329",
                "ispb": "32402502",
                "name": "QI Sociedade de Crédito Direto"
            }
        },
        "target_account": {
            "owner": {
                "name": "Nome fictício",
                "document_number": "111.202.188-99"
            },
            "account_digit": "0",
            "account_branch": "0001",
            "account_number": "1029490",
            "target_pix_key": "1232221",
            "financial_institution": {
                "code": "033",
                "ispb": "90400888",
                "name": "BCO SANTANDER (BRASIL) S.A."
            }
        },
        "external_key": "40054daa-c3c5-49cd-add7-858b576c5887"
    },
    "webhook_type": "transaction_reversal.transaction_reversal_status_change",
    "webhook_datetime": "2025-03-23T15:08:30Z"
}
```

### Campos do Webhook de Transaction Reversal

| Campo | Tipo | Descrição |
|---|---|---|
| **webhook_type** | string | Tipo do webhook: `transaction_reversal.transaction_reversal_status_change` |
| **webhook_datetime** | string | Data e hora do envio do webhook |
| **data.transaction_reversal_key** | string | Chave única do estorno |
| **data.amount** | float | Valor estornado |
| **data.status** | string | Status do estorno: `paid` |
| **data.description** | string | Descrição do estorno |
| **data.reference_date** | string | Data de referência do processamento |
| **data.fund_class_key** | string | Chave do fundo |
| **data.source_account** | object | Dados da conta de origem do estorno |
| **data.target_account** | object | Dados da conta de destino do estorno |
| **data.external_key** | string | Chave externa da transação estornada |

---

# Consulta de Valor Presente - Refinanciamento BNPL

URL: /documentation/manual_bnpl_full/refinanciamento/consulta_valor_presente

# Consulta de Valor Presente - Refinanciamento BNPL


## Resumo

Para descobrir o valor presente que será utilizado no refinanciamento de uma operação, é possível utilizar o endpoint de consulta de dívidas indicando os query params listados abaixo.

## Request

ENDPOINT /debt
MÉTODO GET

### Query Params

| Campo | Tipo | Descrição |
|---|---|---|
| `key`* | string | Chave da dívida (DEBT-KEY) retornada no momento da criação da operação de crédito |
| `eval_present_value`* | string | Indica que o valor atual de cada parcela deve ser calculado e mostrado (`true`) |
| `calculate_delay`* | string | Indica que, se a parcela estiver vencida, os juros de mora e multa devem ser calculados com o valor presente (`true`) |
| `calculate_spread`* | string | Indica se o valor de spread da operação deve ser adicionado ao valor presente. Para operações de refinanciamento deve ser `false` |

### Exemplo de URL

```
/debt?key=72760166-4ddf-41fb-8a8c-605f8f4fc35c&eval_present_value=true&calculate_delay=true&calculate_spread=false
```

### Response

STATUS 200

Response Body

```json
{
    "webhook_type": "debt",
    "operation_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c",
    "status": "opened",
    "data": {
        "credit_operation_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c",
        "contract_number": "DWF1761222116",
        "annual_cet": 97.05,
        "cet": 5.82,
        "disbursed_issue_amount": 1000,
        "disbursement_date": "2026-04-07",
        "issue_amount": 1007.62,
        "final_disbursement_amount": 1000,
        "number_of_installments": 2,
        "total_iof": 7.62,
        "base_iof": 3.79,
        "additional_iof": 3.83,
        "assignment_amount": 1007.63,
        "issuer_name": "Dante Ferrarini",
        "issuer_document_number": "31057466093",
        "prefixed_interest_rate": {
            "annual_rate": 0.8373372409,
            "daily_rate": 0.0016911989,
            "interest_base": {
                "enumerator": "calendar_days",
                "year_days": 360
            },
            "monthly_rate": 0.052
        },
        "installments": [
            {
                "installment_key": "1dea396f-beb1-4df3-9822-35800b4c095a",
                "installment_number": 1,
                "due_date": "2026-05-07",
                "business_due_date": "2026-05-07",
                "calendar_days": 30,
                "total_amount": 543.89,
                "due_principal": 1007.62,
                "pre_fixed_amount": 52.3996159,
                "principal_amortization_amount": 491.4903841,
                "tax_amount": 1.20906634,
                "installment_status": {
                    "enumerator": "opened"
                },
                "paid_amount": 0,
                "present_amount": 517.01,
                "workdays": 20
            },
            {
                "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999",
                "installment_number": 2,
                "due_date": "2026-06-07",
                "business_due_date": "2026-06-08",
                "calendar_days": 31,
                "total_amount": 543.89,
                "due_principal": 516.1296159,
                "pre_fixed_amount": 27.7603841,
                "principal_amortization_amount": 516.1296159,
                "tax_amount": 2.58168034,
                "installment_status": {
                    "enumerator": "opened"
                },
                "paid_amount": 0,
                "present_amount": 490.62,
                "workdays": 20
            }
        ]
    }
}
```


:::tip Valor para Refinanciamento
O valor total a ser utilizado como `disbursed_amount` na simulação/criação do refinanciamento é a soma dos `present_amount` de todas as parcelas. Neste exemplo: 517.01 + 490.62 = **1007.63**.
:::

:::caution Atenção
Para operações de refinanciamento, o campo `calculate_spread` deve ser sempre `false`, pois o valor de spread não deve ser considerado no cálculo do valor presente para quitação.
:::

---

# Criação - Refinanciamento BNPL

URL: /documentation/manual_bnpl_full/refinanciamento/criacao

# Criação - Refinanciamento BNPL


## Resumo

A criação de um refinanciamento utiliza o mesmo endpoint e payload da emissão (`/signed_debt`), com a adição do objeto `refinanced_credit_operations` contendo a lista de operações que serão quitadas. O somatório do valor presente dos contratos anteriores será retido e apenas o excedente será liberado na conta do tomador.

## Request

ENDPOINT /signed_debt
MÉTODO POST

Testar no Playground

Request Body

```json
{
    "borrower": {
        "name": "Dante Ferrarini",
        "email": "",
        "phone": {
            "number": "185633631",
            "area_code": "15",
            "country_code": "086"
        },
        "is_pep": false,
        "address": {
            "city": "São Paulo",
            "state": "SP",
            "number": "",
            "street": "Rua Gilberto Sabino",
            "postal_code": "05425020",
            "neighborhood": "Pinheiros",
            "complement": ""
        },
        "role_type": "issuer",
        "birth_date": "1993-09-10",
        "person_type": "natural",
        "attached_documents_list": [
            {
                "selfie": "250e7e95-57c8-40bd-a0cd-0be8eb172916"
            }
        ],
        "individual_document_number": "31057466093"
    },
    "financial": {
        "final_disbursement_amount": 0,
        "interest_type": "pre_price_days",
        "credit_operation_type": "ccb",
        "annual_interest_rate": 2.32,
        "disbursement_date": "2026-04-07",
        "interest_grace_period": 0,
        "principal_grace_period": 0,
        "number_of_installments": 3,
        "fine_configuration": {
            "contract_fine_rate": 0.02,
            "interest_base": "calendar_days",
            "monthly_rate": 0.01
        }
    },
    "simplified": true,
    "additional_data": {
        "contract": {
            "contract_number": "DWFR00000012",
            "signatures": [
                {
                    "signer": {
                        "name": "Dante Ferrarini",
                        "email": "",
                        "phone": {
                            "number": "185633631",
                            "area_code": "15",
                            "country_code": "086"
                        },
                        "document_number": "31057466093"
                    },
                    "signature": {
                        "timestamp": "2026-04-08T00:40:30Z",
                        "ip_address": "192.168.1.1",
                        "signature_file": {
                            "file_url": "https://qitech.com.br/signature.pdf",
                            "file_type": "pdf"
                        }
                    }
                }
            ]
        }
    },
    "refinanced_credit_operations": [
        {
            "operation_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c"
        }
    ],
    "requester_identifier_key": "d2107ef5-19df-4183-bf0e-802b8229933c",
    "purchaser_document_number": "32402502000135",
    "disbursement_bank_accounts": [
        {
            "name": "company name",
            "ispb_number": "32402502",
            "account_digit": "5",
            "branch_number": "0001",
            "account_number": "7617846",
            "document_number": "32246162000281",
            "percentage_receivable": 100
        }
    ]
}
```


:::caution Atenção
O payload é **idêntico** ao da emissão (`/signed_debt`), com a adição do campo **`refinanced_credit_operations`** contendo a lista de operações a serem quitadas.
:::

### Detalhes do Request Body

O payload contém todos os campos da [Emissão BNPL](../emissao/emissao), com a adição de:

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| **refinanced_credit_operations*** | array | Lista de operações a serem refinanciadas | **[Objeto Refinanced Credit Operations](#objeto-refinanced-credit-operations)** |

Todos os demais campos seguem a mesma especificação da emissão:
- **[Objeto Borrower](../emissao/emissao#objeto-borrower)**
- **[Objeto Additional Data](../emissao/emissao#objeto-additional-data)**
- **[Objeto Disbursement Bank Account](../emissao/emissao#objeto-disbursement-bank-account)**

:::info Diferença no Objeto Financial
No refinanciamento, o campo `financial` utiliza `annual_interest_rate` ao invés de `monthly_interest_rate`, e o `disbursed_amount` deve ser o valor presente total da operação a ser refinanciada (obtido na consulta de valor presente).
:::

### Objeto Refinanced Credit Operations

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `operation_key`* | string | Chave da operação a ser refinanciada (DEBT-KEY da operação original) | UUID |

## Response

A resposta segue o mesmo formato da emissão de dívida, retornando a **DEBT-KEY** do novo contrato.

STATUS 201

Response Body

```json
{
    "webhook_type": "debt",
    "key": "290f042f-eedd-4d9d-b621-3a81df0181b6",
    "status": "opened",
    "event_datetime": "2026-04-08 00:40:37",
    "data": {
        "borrower": {
            "name": "Dante Ferrarini",
            "document_number": "31057466093",
            "related_party_key": "3d62f3c6-1ae5-49f9-aa5d-21a08d95aad6"
        },
        "contract": {
            "document_key": null,
            "number": "DWFR00000012",
            "urls": [],
            "signature_information": [
                {
                    "signer_name": "Dante Ferrarini",
                    "signer_document_number": "31057466093",
                    "signer_role": "issuer",
                    "signer_email": null,
                    "signer_external_key": null,
                    "signature_url": null
                }
            ]
        },
        "requester_identifier_key": "d2107ef5-19df-4183-bf0e-802b8229933c",
        "iof_charge_method": "financed",
        "collaterals": [],
        "contract_fees": [
            {
                "fee_type": "spread",
                "fee_amount": 3.05
            },
            {
                "fee_type": "spread_refinancing",
                "fee_amount": 3.02
            }
        ],
        "external_contract_fees": [
            {
                "fee_type": "tac",
                "fee_amount": 0,
                "tax_amount": 0,
                "net_fee_amount": 0
            }
        ],
        "external_contract_fee_amount": 0,
        "net_external_contract_fee_amount": 0,
        "contract_fee_amount": 6.07,
        "issue_amount": 1016.72,
        "assignment_amount": 1022.79,
        "cet": "11,1900%",
        "annual_cet": "256,9982%",
        "number_of_installments": 3,
        "base_iof": 5.23,
        "additional_iof": 3.86,
        "total_iof": 9.09,
        "ipoc_code": "324025020203131057466093DWFR00000012",
        "prefixed_interest_rate": {
            "annual_rate": 2.32,
            "created_at": "2026-04-08T00:40:30",
            "daily_rate": 0.0033387969,
            "interest_base": "calendar_days",
            "monthly_rate": 0.1051676747
        },
        "installments": [
            {
                "accrual_reference_date": null,
                "additional_costs": [],
                "advanced_paid_amount": 0,
                "bank_slip_key": null,
                "business_due_date": "2026-05-07",
                "calendar_days": 30,
                "digitable_line": null,
                "due_date": "2026-05-07",
                "due_interest": 0,
                "due_principal": 1016.72,
                "fine_amount": null,
                "has_interest": true,
                "installment_history": [],
                "installment_key": "52810e9d-0815-4fd1-ab20-d8b37dcd936e",
                "installment_number": 1,
                "installment_payment": [],
                "installment_status": "created",
                "installment_type": "principal",
                "original_due_principal": 1016.72,
                "original_pre_fixed_amount": 106.92260459,
                "original_principal_amortization_amount": 306.50739541,
                "original_total_amount": 413.43,
                "paid_amount": 0,
                "paid_at": null,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 106.92260459,
                "principal_amortization_amount": 306.50739541,
                "qr_code_key": null,
                "qr_code_url": null,
                "renegotiation_proposal_key": null,
                "tax_amount": 0.75400819,
                "total_accrual_amount": null,
                "total_amount": 413.43,
                "total_paid_amount": 0,
                "workdays": 20
            },
            {
                "accrual_reference_date": null,
                "additional_costs": [],
                "advanced_paid_amount": 0,
                "bank_slip_key": null,
                "business_due_date": "2026-06-08",
                "calendar_days": 31,
                "digitable_line": null,
                "due_date": "2026-06-07",
                "due_interest": 0,
                "due_principal": 710.21260459,
                "fine_amount": null,
                "has_interest": true,
                "installment_history": [],
                "installment_key": "2bcfe19e-9847-4c8f-be80-17f646a897c4",
                "installment_number": 2,
                "installment_payment": [],
                "installment_status": "created",
                "installment_type": "principal",
                "original_due_principal": 710.21260459,
                "original_pre_fixed_amount": 77.30856978,
                "original_principal_amortization_amount": 336.12143022,
                "original_total_amount": 413.43,
                "paid_amount": 0,
                "paid_at": null,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 77.30856978,
                "principal_amortization_amount": 336.12143022,
                "qr_code_key": null,
                "qr_code_url": null,
                "renegotiation_proposal_key": null,
                "tax_amount": 1.68127939,
                "total_accrual_amount": null,
                "total_amount": 413.43,
                "total_paid_amount": 0,
                "workdays": 20
            },
            {
                "accrual_reference_date": null,
                "additional_costs": [],
                "advanced_paid_amount": 0,
                "bank_slip_key": null,
                "business_due_date": "2026-07-07",
                "calendar_days": 30,
                "digitable_line": null,
                "due_date": "2026-07-07",
                "due_interest": 0,
                "due_principal": 374.09117437,
                "fine_amount": null,
                "has_interest": true,
                "installment_history": [],
                "installment_key": "7cf785c9-b6cf-4e9b-9c09-61d917bc72b8",
                "installment_number": 3,
                "installment_payment": [],
                "installment_status": "created",
                "installment_type": "principal",
                "original_due_principal": 374.09117437,
                "original_pre_fixed_amount": 39.33882563,
                "original_principal_amortization_amount": 374.09117437,
                "original_total_amount": 413.43,
                "paid_amount": 0,
                "paid_at": null,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 39.33882563,
                "principal_amortization_amount": 374.09117437,
                "qr_code_key": null,
                "qr_code_url": null,
                "renegotiation_proposal_key": null,
                "tax_amount": 2.79146834,
                "total_accrual_amount": null,
                "total_amount": 413.43,
                "total_paid_amount": 0,
                "workdays": 22
            }
        ],
        "total_pre_fixed_amount": 223.57
    }
}
```

:::info Observação
- O valor presente das operações listadas em `refinanced_credit_operations` será automaticamente retido para quitação dos contratos anteriores
- Apenas o excedente (diferença entre o valor desembolsado e o valor retido) será liberado na conta do tomador
- Após a criação, os contratos refinanciados serão automaticamente liquidados
- Os webhooks de emissão (assinatura, desembolso, cancelamento) seguem o mesmo padrão descrito na seção de [Webhooks da Emissão](../emissao/webhooks)
:::

---

# Introdução - Refinanciamento BNPL

URL: /documentation/manual_bnpl_full/refinanciamento/introducao

## Resumo

Um refinanciamento consiste na geração de um novo contrato de crédito para a quitação de um anterior. O fluxo funciona da mesma forma que uma emissão de dívida simples, porém, quando informados os valores da operação, o somatório do valor presente dos contratos anteriores será retido e apenas o excedente, caso exista, será liberado na conta do tomador.

## Fluxo do Refinanciamento

1. **Consulta de valor presente**: Consultar o valor presente da operação original para saber o montante necessário para quitação
2. **Simulação**: Simular o refinanciamento com os dados da nova operação e a referência à operação original
3. **Criação**: Criar o refinanciamento informando a lista de operações a serem quitadas em `refinanced_credit_operations`

:::info Importante
O payload utilizado tanto na simulação quanto na criação de um refinanciamento é o mesmo de uma dívida simples, com a adição da lista de operações que serão quitadas em **`refinanced_credit_operations`**.
:::

---

# Simulação - Refinanciamento BNPL

URL: /documentation/manual_bnpl_full/refinanciamento/simulacao

# Simulação - Refinanciamento BNPL


## Resumo

Antes de criar um refinanciamento, é possível simular os valores da nova operação. A simulação utiliza o mesmo payload de uma simulação de dívida simples, com a adição do campo `refinanced_credit_operations`.

## Request

ENDPOINT /debt_simulation
MÉTODO POST

Request Body

```json
{
    "borrower": {
        "person_type": "natural"
    },
    "refinanced_credit_operations": [
        {
            "operation_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c"
        }
    ],
    "financial": {
        "disbursed_amount": 1007.63,
        "interest_type": "pre_price_days",
        "credit_operation_type": "ccb",
        "annual_interest_rate": 2.32,
        "disbursement_date": "2026-04-07",
        "interest_grace_period": 0,
        "principal_grace_period": 0,
        "number_of_installments": 3,
        "fine_configuration": {
            "contract_fine_rate": 0.02,
            "interest_base": "calendar_days",
            "monthly_rate": 0.01
        }
    }
}
```


### Body Params

| Campo | Tipo | Descrição |
|---|---|---|
| **borrower*** | object | Dados do tomador (mínimo: `person_type`) |
| **refinanced_credit_operations*** | array | Lista de operações a serem refinanciadas |
| **financial*** | object | Dados financeiros da nova operação |

### Objeto refinanced_credit_operations

| Campo | Tipo | Descrição |
|---|---|---|
| `operation_key`* | string | Chave da operação a ser refinanciada (DEBT-KEY) |

## Response

STATUS 200

Response Body

```json
{
    "type": "debt",
    "key": "daa5173d-ae44-44c5-87bc-f9115cfbcaa1",
    "status": "finished",
    "event_datetime": "2026-04-08 00:36:02",
    "data": {
        "interest_type": "pre_price_days",
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "interest_payment_month_period": 1,
        "principal_grace_period": 0,
        "principal_amortization_month_period": 1,
        "operation_type": "settlement_refinancing",
        "prefixed_interest_rate": {
            "interest_base": "calendar_days_365",
            "annual_rate": 2.32,
            "monthly_rate": 0.1051676747,
            "daily_rate": 0.0032929847
        },
        "issue_date": "2026-04-07",
        "number_of_installments": 3,
        "requester_key": "78287247-947d-4730-9bd1-7efb068175b6",
        "final_disbursement_amount": 0.01,
        "refinanced_credit_operations": [
            {
                "refinanced_credit_operation_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c",
                "refinanced_credit_operation_status": "pending_payment",
                "due_balance": 1007.62,
                "due_balance_reference_date": "2026-04-07",
                "original_deadline": 61
            }
        ],
        "total_pre_fixed_amount": 220.27,
        "iof_amount": 9.09,
        "cet": 0.1103,
        "annual_cet": 2.5111,
        "disbursement_date": "2026-04-07",
        "installments": [
            {
                "calendar_days": 30,
                "workdays": 20,
                "business_due_date": "2026-05-07",
                "due_date": "2026-05-07",
                "due_principal": 1016.72,
                "has_interest": true,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 105.38950323,
                "tax_amount": 0.75507362,
                "total_amount": 412.33,
                "principal_amortization_amount": 306.94049677,
                "installment_number": 1
            },
            {
                "calendar_days": 31,
                "workdays": 20,
                "business_due_date": "2026-06-08",
                "due_date": "2026-06-07",
                "due_principal": 709.77950323,
                "has_interest": true,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 76.15320432,
                "tax_amount": 1.68155633,
                "total_amount": 412.33,
                "principal_amortization_amount": 336.17679568,
                "installment_number": 2
            },
            {
                "calendar_days": 30,
                "workdays": 22,
                "business_due_date": "2026-07-07",
                "due_date": "2026-07-07",
                "due_principal": 373.60270755,
                "has_interest": true,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 38.72729245,
                "tax_amount": 2.7878234,
                "total_amount": 412.33,
                "principal_amortization_amount": 373.60270755,
                "installment_number": 3
            }
        ],
        "external_contract_fees": [
            {
                "fee_type": "tac",
                "amount_type": "absolute",
                "amount": 0,
                "fee_amount": 0,
                "tax_amount": 0,
                "net_fee_amount": 0
            }
        ],
        "contract_fee_amount": 3.05,
        "external_contract_fee_amount": 0,
        "net_external_contract_fee_amount": 0,
        "contract_fees": [
            {
                "fee_type": "spread",
                "amount_type": "percentage",
                "amount": 0.3,
                "fee_amount": 3.05
            }
        ],
        "issue_amount": 1016.72,
        "disbursed_issue_amount": 1007.63,
        "assignment_amount": 1019.77
    }
}
```

---

# Cenários - Renegociação em Lote BNPL

URL: /documentation/manual_bnpl_full/renegociacao/cenarios

## Resumo

Este documento apresenta os principais cenários de renegociação em lote para operações BNPL. Todos os cenários utilizam o `amortization_type: "present_amount"` e permitem aplicar descontos individuais por parcela através do campo `discount_amount` no objeto de cada installment.

:::info Lógica de Desconto por Parcela
É possível aplicar descontos diferentes em cada parcela individualmente. Basta adicionar o campo `discount_amount` (valor absoluto em reais) dentro do objeto da parcela desejada. Parcelas sem o campo `discount_amount` serão cobradas pelo valor presente integral.
:::

---

## Cenário 1: Empréstimo de 1 Parcela - Pagamento Padrão

O tomador possui um empréstimo BNPL de 1 parcela e deseja quitá-lo pelo valor presente.

### Exemplo de Payload

```json
{
    "payment_type": "pix",
    "amortization_type": "present_amount",
    "proposal_due_date": "2026-04-10",
    "discount_percentage": 0,
    "reference_date": "2026-04-10",
    "request_control_key": "3571e292-3a83-4011-904d-20ee963022ef",
    "operations": [
        {
            "debt_key": "bf1175f4-750d-42b9-b264-5e7cd8c1c189",
            "installments": [
                {
                    "installment_key": "0298c572-7b6b-4db0-88d6-4bf1622d3e2d"
                }
            ]
        }
    ]
}
```

---

## Cenário 2: Empréstimo de 1 Parcela - Pagamento Sem Juros (Interest Free)

O tomador possui um empréstimo BNPL de 1 parcela e negocia o pagamento sem juros. O desconto aplicado corresponde ao valor dos juros da parcela.

### Exemplo de Payload

```json
{
    "payment_type": "pix",
    "amortization_type": "present_amount",
    "proposal_due_date": "2026-04-10",
    "discount_percentage": 0,
    "reference_date": "2026-04-10",
    "request_control_key": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "operations": [
        {
            "debt_key": "bf1175f4-750d-42b9-b264-5e7cd8c1c189",
            "installments": [
                {
                    "installment_key": "0298c572-7b6b-4db0-88d6-4bf1622d3e2d",
                    "discount_amount": 54.19
                }
            ]
        }
    ]
}
```

:::info Observação
O valor do `discount_amount` (54.19) corresponde ao valor dos juros (`pre_fixed_amount`) da parcela. Dessa forma, o tomador paga apenas o valor do principal.
:::

---

## Cenário 3: Empréstimo de 1 Parcela - Pagamento Sem Juros e Sem IOF (Interest + IOF Free)

O tomador possui um empréstimo BNPL de 1 parcela e negocia o pagamento sem juros e sem IOF. O desconto aplicado corresponde à soma dos juros e do IOF da parcela.

### Exemplo de Payload

```json
{
    "payment_type": "pix",
    "amortization_type": "present_amount",
    "proposal_due_date": "2026-04-10",
    "discount_percentage": 0,
    "reference_date": "2026-04-10",
    "request_control_key": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "operations": [
        {
            "debt_key": "bf1175f4-750d-42b9-b264-5e7cd8c1c189",
            "installments": [
                {
                    "installment_key": "0298c572-7b6b-4db0-88d6-4bf1622d3e2d",
                    "discount_amount": 55.44
                }
            ]
        }
    ]
}
```

:::info Observação
O valor do `discount_amount` (55.44) corresponde à soma dos juros (`pre_fixed_amount`: 54.19) + IOF (`tax_amount`: 1.25) da parcela. Dessa forma, o tomador paga apenas o valor de amortização do principal.
:::

---

## Cenário 4: Empréstimo de Múltiplas Parcelas com Desconto Individual

O tomador possui um empréstimo BNPL com várias parcelas e negocia descontos diferentes para parcelas específicas. Parcelas sem o campo `discount_amount` são cobradas pelo valor presente integral.

### Exemplo de Payload

```json
{
    "payment_type": "pix",
    "amortization_type": "present_amount",
    "proposal_due_date": "2026-04-10",
    "discount_percentage": 0,
    "reference_date": "2026-04-10",
    "request_control_key": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "operations": [
        {
            "debt_key": "bf1175f4-750d-42b9-b264-5e7cd8c1c189",
            "installments": [
                {
                    "installment_key": "0298c572-7b6b-4db0-88d6-4bf1622d3e2d",
                    "discount_amount": 20
                },
                {
                    "installment_key": "5e267f58-0f55-4b12-9582-63e0e9e082a8"
                },
                {
                    "installment_key": "5be492bf-b637-4999-986d-ecf423cc5dd1"
                },
                {
                    "installment_key": "15abfbfd-8608-45e9-abbb-a04c021dcf7b",
                    "discount_amount": 10
                },
                {
                    "installment_key": "c8eb83b3-5b0d-4326-947c-79279cdce2d6"
                }
            ]
        }
    ]
}
```

:::info Observação
Neste exemplo:
- Parcela 1: desconto de R$ 20,00
- Parcela 2: sem desconto (valor presente integral)
- Parcela 3: sem desconto (valor presente integral)
- Parcela 4: desconto de R$ 10,00
- Parcela 5: sem desconto (valor presente integral)
:::

---

## Cenário 5: Pagamento de Parcelas em Atraso (Overdue)

O tomador possui parcelas vencidas e deseja quitá-las. As parcelas em atraso já incluem multa e juros de mora calculados automaticamente. É possível aplicar descontos individuais para reduzir o valor.

### Exemplo de Payload

```json
{
    "payment_type": "pix",
    "amortization_type": "present_amount",
    "proposal_due_date": "2026-04-10",
    "discount_percentage": 0,
    "reference_date": "2026-04-10",
    "request_control_key": "e5f6a7b8-c9d0-1234-efab-345678901234",
    "operations": [
        {
            "debt_key": "bf1175f4-750d-42b9-b264-5e7cd8c1c189",
            "installments": [
                {
                    "installment_key": "0298c572-7b6b-4db0-88d6-4bf1622d3e2d",
                    "discount_amount": 15
                },
                {
                    "installment_key": "5e267f58-0f55-4b12-9582-63e0e9e082a8",
                    "discount_amount": 15
                }
            ]
        }
    ]
}
```

:::caution Atenção
Para parcelas em atraso, o valor presente já inclui multa (`fine_amount`) e juros de mora calculados automaticamente com base na `fine_configuration` do contrato. O `discount_amount` é aplicado sobre esse valor total.
:::

---

## Cenário 6: Múltiplas Operações com Desconto Individual por Parcela

O tomador possui empréstimos BNPL em diferentes operações e deseja quitar parcelas de todas em um único pagamento, com descontos individuais.

### Exemplo de Payload

```json
{
    "payment_type": "pix",
    "amortization_type": "present_amount",
    "proposal_due_date": "2026-04-10",
    "discount_percentage": 0,
    "reference_date": "2026-04-10",
    "request_control_key": "f6a7b8c9-d0e1-2345-fabc-456789012345",
    "operations": [
        {
            "debt_key": "bf1175f4-750d-42b9-b264-5e7cd8c1c189",
            "installments": [
                {
                    "installment_key": "0298c572-7b6b-4db0-88d6-4bf1622d3e2d",
                    "discount_amount": 20
                },
                {
                    "installment_key": "5e267f58-0f55-4b12-9582-63e0e9e082a8"
                }
            ]
        },
        {
            "debt_key": "a2c3d4e5-860f-4b7a-9c1d-2e3f4a5b6c7d",
            "installments": [
                {
                    "installment_key": "7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e",
                    "discount_amount": 30
                }
            ]
        }
    ]
}
```

---

## Objeto Installments - Campo Discount

| Campo | Tipo | Descrição | Obrigatório |
|---|---|---|---|
| `installment_key`* | string | Chave da parcela a ser renegociada | Sim |
| `discount_amount` | float | Valor de desconto em reais (R$) aplicado individualmente na parcela | Não |

:::info Sobre o campo discount_amount
- O campo `discount_amount` é **opcional** e pode ser informado em qualquer parcela
- O valor é um **desconto absoluto em reais** (não percentual)
- Parcelas sem o campo `discount_amount` são cobradas pelo **valor presente integral**
- O desconto é aplicado sobre o valor presente da parcela na `reference_date`
:::

---

## Tabela Resumo dos Cenários

| Cenário | Descrição | Discount |
|---|---|---|
| 1 parcela - padrão | Pagamento pelo valor presente | Sem desconto |
| 1 parcela - interest free | Desconto = valor dos juros | `discount_amount` = `pre_fixed_amount` |
| 1 parcela - interest + IOF free | Desconto = juros + IOF | `discount_amount` = `pre_fixed_amount` + `tax_amount` |
| Múltiplas parcelas | Descontos individuais por parcela | `discount_amount` por parcela |
| Parcelas em atraso | Parcelas vencidas com multa/mora | `discount_amount` opcional |
| Múltiplas operações | Operações diferentes em um lote | `discount_amount` por parcela |

---

## Regras Importantes

:::caution Regras da Renegociação em Lote
- Todas as operações devem ser do **mesmo emitente** e mesma **chave de integração**
- Limite de **50 operações** por lote
- Um único meio de pagamento (boleto/Pix) é gerado para o valor total do lote
- Se uma parcela incluída no lote for paga por fora antes da confirmação, o lote é **rejeitado**
- Se o pagamento não for realizado até a `proposal_due_date`, o lote é **rejeitado**
- O `amortization_type` utilizado é sempre `present_amount`
- O campo `discount_amount` é aplicado **individualmente por parcela**
:::

---

# Consulta - Renegociação em Lote BNPL

URL: /documentation/manual_bnpl_full/renegociacao/consulta

# Consulta - Renegociação em Lote BNPL


## Resumo

É possível consultar o status e detalhes de uma proposta de renegociação em lote, utilizando a `batch_proposal_key` ou a `request_control_key`.

---

## Consultar por Batch Proposal Key

ENDPOINT /renegotiation/batch_proposal/ BATCH-PROPOSAL-KEY
MÉTODO GET

### Path Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `batch_proposal_key`* | string | Chave da proposta de renegociação em lote | UUID |

### Response

STATUS 200

Response Body

```json
{
    "batch_proposal_key": "ff5ad6dd-2087-4850-a3e8-b37634448b4e",
    "discount_percentage": 0,
    "discount_amount": 0,
    "amortization_type": "installment_payment",
    "payment_amount": 517.88,
    "requester_name": "Dante Ltda",
    "requester_key": "78287247-947d-4730-9bd1-7efb068175b6",
    "issuer_name": "Dante Ferrarini",
    "reference_date": "2026-04-08",
    "issuer_document_number": "31057466093",
    "batch_proposal_status": "pending_payment",
    "proposal_due_date": "2026-04-15",
    "payment_type": "pix",
    "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db",
    "origin_key": null,
    "operations": [
        {
            "requester_key": "78287247-947d-4730-9bd1-7efb068175b6",
            "contract_number": "DWF1761222116",
            "payment_amount": 517.88,
            "discount_amount": 0,
            "origin_key": null,
            "affected_installments": [
                {
                    "installment_key": "1dea396f-beb1-4df3-9822-35800b4c095a",
                    "due_date": "2026-05-07",
                    "principal_amount": 491.49,
                    "interest_amount": 52.4,
                    "fine_amount": 0,
                    "total_amount": 543.89,
                    "present_amount": 517.88,
                    "paid_amount": 517.88,
                    "principal_amortization_payment_amount": 491.49,
                    "prefixed_interest_payment_amount": 26.39,
                    "fine_payment_amount": 0,
                    "discount_amount": 0
                }
            ],
            "remaining_installments": [
                {
                    "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999",
                    "due_date": "2026-06-07",
                    "principal_amount": 516.13,
                    "interest_amount": 27.76,
                    "fine_amount": 0,
                    "total_amount": 543.89
                }
            ],
            "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c"
        }
    ],
    "payment": {
        "digitable_line": null,
        "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/acaeb341e1264cde99b93e247e12b3725204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***63043AD0",
        "qr_code_key": "acaeb341-e126-4cde-99b9-3e247e12b372",
        "bank_slip_key": null,
        "paid_method_type": "pix",
        "source_account_key": null,
        "payment_data": {
            "creditor_bank_account_key": "6108dd45-580d-48c4-b3bb-74c1e843be49",
            "batch_renegotiation_proposal_key": "ff5ad6dd-2087-4850-a3e8-b37634448b4e"
        }
    }
}
```


---

## Consultar por Request Control Key

ENDPOINT /renegotiation/batch_proposal/request_control_key/ REQUEST-CONTROL-KEY
MÉTODO GET

### Path Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `request_control_key`* | string | Chave de controle da requisição | UUID |

### Response

A resposta segue o mesmo formato da consulta por `batch_proposal_key`.

---

## Listar Renegociações em Lote

ENDPOINT /renegotiation/batch_proposal
MÉTODO GET

### Query Params

| Campo | Tipo | Descrição |
|---|---|---|
| `batch_proposal_status` | string | Filtrar por status da proposta em lote |
| `issuer_document_number` | string | Filtrar por CPF/CNPJ do emitente |
| `request_control_key` | string | Filtrar por chave de controle |

### Response

STATUS 200

Response Body

```json
{
    "data": [
        {
            "batch_proposal_key": "ff5ad6dd-2087-4850-a3e8-b37634448b4e",
            "discount_percentage": 0,
            "discount_amount": 0,
            "amortization_type": "installment_payment",
            "payment_amount": 517.88,
            "requester_name": "Dante Ltda",
            "requester_key": "78287247-947d-4730-9bd1-7efb068175b6",
            "issuer_name": "Dante Ferrarini",
            "reference_date": "2026-04-08",
            "issuer_document_number": "31057466093",
            "batch_proposal_status": "pending_payment",
            "proposal_due_date": "2026-04-15",
            "payment_type": "pix",
            "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db",
            "origin_key": null
        }
    ],
    "pagination": {
        "current_page": 1,
        "next_page": 2,
        "rows_per_page": 10,
        "total_pages": 150,
        "total_rows": 1495
    }
}
```


---

## Cancelar uma Renegociação em Lote

ENDPOINT /renegotiation/batch_proposal/ BATCH-PROPOSAL-KEY
MÉTODO DELETE

### Path Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `batch_proposal_key`* | string | Chave da proposta de renegociação em lote a ser cancelada | UUID |

### Response

STATUS 204

Response Body

```json
{}
```


:::caution Atenção
Somente propostas com status `pending_payment` podem ser canceladas.
:::

---

# Renegociação com IOF Spread e Desconto Somente Juros - BNPL

URL: /documentation/manual_bnpl_full/renegociacao/iof-spread-e-desconto-juros

## Resumo

Esta página documenta o fluxo de renegociação em lote para operações BNPL em que a operação de crédito foi criada com `iof_charge_method: "spread"`. Nesse modelo, o IOF **não** é financiado nas parcelas — ele é calculado normalmente, mas adicionado ao `assignment_amount` (valor de cessão), e não às prestações do tomador.

Além disso, é possível utilizar o campo `discount_validation: "only_interest_discount"` em cada operação do array `operations[]` para restringir os descontos aplicados somente à parcela de juros. Se o desconto exceder os juros e atingir o principal ou a multa, a API retornará o erro `InvalidDiscountAmountOnlyInterestDiscount`.

O fluxo utiliza os endpoints de lote: simulação (`POST /renegotiation/batch_proposal_simulation`) seguida da proposta (`POST /renegotiation/batch_proposal`). O campo `discount_validation` é definido **por operação** no array `operations[]`, e não no nível raiz do payload.

:::info Nota — iof_charge_method
O campo `iof_charge_method` é definido no momento da **criação da operação de crédito** (credit-operation-api), e não durante a renegociação. Quando `iof_charge_method: "spread"`:
- O IOF é calculado normalmente (IOF base + IOF adicional), mas **não** é deduzido das parcelas do tomador
- O IOF é adicionado ao `assignment_amount` — ou seja, o custo do IOF é refletido no valor de cessão
- As parcelas do tomador são "limpas" de IOF

Os três valores possíveis são:
- `"financed"` **(padrão)** — IOF é financiado nas parcelas (deduzido do valor creditado ao tomador)
- `"spread"` — IOF é adicionado ao valor de cessão (`assignment_amount`), não às parcelas
- `"free"` — Sem IOF (`total_iof = 0`)
:::

:::caution Atenção — discount_validation
Quando `discount_validation: "only_interest_discount"` é definido em uma operação, o sistema valida que o desconto aplicado em cada parcela **não** inclui amortização de principal (`discount_principal_amortization_amount`) nem multa (`discount_fine_amount`). Somente os juros (juros prefixados) podem ser descontados.

Se qualquer parcela tiver um desconto que atinja o principal ou a multa, a API retorna o erro `InvalidDiscountAmountOnlyInterestDiscount` e a requisição inteira falha.
:::

## Passo 1: Simulação em Lote

ENDPOINT /renegotiation/batch_proposal_simulation
MÉTODO POST

:::warning Atenção
Os campos `discount_amount` e `discount_percentage` **NÃO** podem ser enviados juntos no mesmo payload (nível raiz).
:::

Request Body

```json
{
    "amortization_type": "installment_payment",
    "reference_date": "2026-04-20",
    "discount_percentage": 0.0,
    "operations": [
        {
            "debt_key": "3571e292-3a83-4011-904d-20ee963022ef",
            "discount_validation": "only_interest_discount",
            "installments": [
                {
                    "installment_key": "f9e8d7c6-b5a4-3210-fedc-ba9876543210"
                }
            ]
        }
    ]
}
```

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `amortization_type`* | string | Tipo de amortização | **[Enumeradores Amortization Type](#enumeradores-amortization-type)** |
| `reference_date`* | string | Data de referência para cálculo do valor presente (precisa ser D+1) | 10 |
| `discount_percentage` | float | Percentual de desconto sobre o valor presente ((1 - percentual) × Valor Presente) | 10 |
| `discount_amount` | float | Valor de desconto aplicado sobre o valor presente | 10 |
| `operations`* | array | Lista de operações a serem renegociadas | **[Objeto Operations](#objeto-operations)** |

### Objeto Operations

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `debt_key`* | string | Chave única da operação de crédito (DEBT-KEY) | UUID |
| `discount_validation` | string | Regra de validação de desconto. Quando definido como `"only_interest_discount"`, o desconto aplicado não pode ultrapassar a parcela de juros. | **[Enumeradores Discount Validation](#enumeradores-discount-validation)** |
| `installments`* | array | Parcelas a serem renegociadas | **[Objeto Installments](#objeto-installments)** |

### Objeto Installments

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `installment_key`* | string | Chave da parcela a ser renegociada | UUID |
| `paid_amount` | float | Valor pago (ou alocado) na parcela, em reais (R$). Obrigatório quando `amortization_type` é **`present_amount`**. | 15,2 |
| `discount_amount` | float | Valor de desconto em reais (R$) na parcela. Obrigatório quando `amortization_type` é **`present_amount`** (use `0` se não houver desconto). Opcional nos demais tipos. | 15,2 |

### Enumeradores Discount Validation

| Campo | Descrição |
|---|---|
| `only_interest_discount` | Valida que o desconto aplicado em cada parcela não ultrapassa o valor de juros. Caso o desconto atinja o principal ou multa, a API retorna o erro `InvalidDiscountAmountOnlyInterestDiscount`. |

### Enumeradores Amortization Type

| Campo | Descrição |
|---|---|
| **installment_payment** | Renegociação para pagamento de parcelas específicas enviadas no payload. Requer `installment_key` de cada parcela. |
| **overdue_installment_payment** | Renegociação direcionada para pagamento de parcelas em atraso. Requer `installment_key` de cada parcela. |
| **present_amount** | Simulação com valor presente por parcela. Em cada `installments[]` é obrigatório `installment_key`, **`paid_amount`** e **`discount_amount`**. |

## Response

STATUS 200

Response Body

```json
{
    "batch_proposal_key": "7423c701-3578-4733-8f30-81ab60afdb6d",
    "discount_percentage": 0,
    "discount_amount": 0,
    "amortization_type": "installment_payment",
    "payment_amount": 517.88,
    "requester_name": "Empresa Exemplo Ltda",
    "requester_key": "78287247-947d-4730-9bd1-7efb068175b6",
    "issuer_name": "João da Silva",
    "reference_date": "2026-04-20",
    "issuer_document_number": "31057466093",
    "operations": [
        {
            "requester_key": "78287247-947d-4730-9bd1-7efb068175b6",
            "contract_number": "DWF1761222116",
            "payment_amount": 517.88,
            "discount_amount": 0,
            "origin_key": null,
            "affected_installments": [
                {
                    "installment_key": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
                    "due_date": "2026-05-07",
                    "principal_amount": 491.49,
                    "interest_amount": 52.40,
                    "fine_amount": 0,
                    "total_amount": 543.89,
                    "present_amount": 517.88,
                    "paid_amount": 517.88,
                    "principal_amortization_payment_amount": 491.49,
                    "prefixed_interest_payment_amount": 26.39,
                    "fine_payment_amount": 0,
                    "discount_amount": 0
                }
            ],
            "remaining_installments": [
                {
                    "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999",
                    "due_date": "2026-06-07",
                    "principal_amount": 516.13,
                    "interest_amount": 27.76,
                    "fine_amount": 0,
                    "total_amount": 543.89
                }
            ],
            "debt_key": "3571e292-3a83-4011-904d-20ee963022ef"
        }
    ]
}
```

## Passo 2: Proposta em Lote

ENDPOINT /renegotiation/batch_proposal
MÉTODO POST

:::warning Atenção
Os campos `discount_amount` e `discount_percentage` **NÃO** podem ser enviados juntos no mesmo payload (nível raiz).
:::

Request Body

```json
{
    "amortization_type": "installment_payment",
    "reference_date": "2026-04-20",
    "proposal_due_date": "2026-04-27",
    "payment_type": "pix",
    "discount_percentage": 0.0,
    "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db",
    "operations": [
        {
            "debt_key": "3571e292-3a83-4011-904d-20ee963022ef",
            "discount_validation": "only_interest_discount",
            "installments": [
                {
                    "installment_key": "f9e8d7c6-b5a4-3210-fedc-ba9876543210"
                }
            ]
        }
    ]
}
```

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `amortization_type`* | string | Tipo de amortização | **[Enumeradores Amortization Type](#enumeradores-amortization-type-1)** |
| `reference_date`* | string | Data de referência para cálculo do valor presente (D+1) | 10 |
| `proposal_due_date`* | string | Data de vencimento da proposta de renegociação | 10 |
| `payment_type`* | string | Tipo de pagamento | **[Enumeradores Payment Type](#enumeradores-payment-type)** |
| `request_control_key` | string | Chave de controle para rastreamento e identificação única (opcional) | UUID |
| `discount_percentage` | float | Percentual de desconto sobre o valor presente | 10 |
| `discount_amount` | float | Valor de desconto sobre o valor presente | 10 |
| `operations`* | array | Lista de operações a serem renegociadas | **[Objeto Operations](#objeto-operations-1)** |

### Objeto Operations

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `debt_key`* | string | Chave única da operação de crédito (DEBT-KEY) | UUID |
| `discount_validation` | string | Regra de validação de desconto. Quando definido como `"only_interest_discount"`, o desconto aplicado não pode ultrapassar a parcela de juros. | **[Enumeradores Discount Validation](#enumeradores-discount-validation-1)** |
| `installments`* | array | Parcelas a serem renegociadas | **[Objeto Installments](#objeto-installments-1)** |

### Objeto Installments

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `installment_key`* | string | Chave da parcela a ser renegociada | UUID |
| `paid_amount` | float | Valor pago (ou alocado) na parcela, em reais (R$). Obrigatório quando `amortization_type` é **`present_amount`**. | 15,2 |
| `discount_amount` | float | Valor de desconto em reais (R$) aplicado na parcela. Obrigatório quando `amortization_type` é **`present_amount`** (use `0` se não houver desconto). Para outros tipos de amortização, permanece opcional por parcela. | 15,2 |

### Enumeradores Discount Validation

| Campo | Descrição |
|---|---|
| `only_interest_discount` | Valida que o desconto aplicado em cada parcela não ultrapassa o valor de juros. Caso o desconto atinja o principal ou multa, a API retorna o erro `InvalidDiscountAmountOnlyInterestDiscount`. |

### Enumeradores Payment Type

| Campo | Descrição |
|---|---|
| `bank_slip` | Pagamento via boleto bancário (gera boleto e Pix) |
| `pix` | Pagamento via Pix (gera apenas Pix) |
| `manual` | Pagamento feito de forma manual (não gera forma de pagamento) |

### Enumeradores Amortization Type

| Campo | Descrição |
|---|---|
| **installment_payment** | Renegociação para pagamento de parcelas específicas. Requer `installment_key` de cada parcela. |
| **overdue_installment_payment** | Renegociação direcionada para pagamento de parcelas em atraso. Requer `installment_key` de cada parcela. |
| **present_amount** | Renegociação com composição por valor presente por parcela. Em cada item de `installments[]` é obrigatório informar `installment_key`, **`paid_amount`** e **`discount_amount`**. |

## Response

STATUS 201

Response Body

```json
{
    "batch_proposal_key": "ff5ad6dd-2087-4850-a3e8-b37634448b4e",
    "discount_percentage": 0,
    "discount_amount": 0,
    "amortization_type": "installment_payment",
    "payment_amount": 517.88,
    "requester_name": "Empresa Exemplo Ltda",
    "requester_key": "78287247-947d-4730-9bd1-7efb068175b6",
    "issuer_name": "João da Silva",
    "reference_date": "2026-04-20",
    "issuer_document_number": "31057466093",
    "batch_proposal_status": "pending_payment",
    "proposal_due_date": "2026-04-27",
    "payment_type": "pix",
    "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db",
    "origin_key": null,
    "operations": [
        {
            "requester_key": "78287247-947d-4730-9bd1-7efb068175b6",
            "contract_number": "DWF1761222116",
            "payment_amount": 517.88,
            "discount_amount": 0,
            "origin_key": null,
            "affected_installments": [
                {
                    "installment_key": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
                    "due_date": "2026-05-07",
                    "principal_amount": 491.49,
                    "interest_amount": 52.40,
                    "fine_amount": 0,
                    "total_amount": 543.89,
                    "present_amount": 517.88,
                    "paid_amount": 517.88,
                    "principal_amortization_payment_amount": 491.49,
                    "prefixed_interest_payment_amount": 26.39,
                    "fine_payment_amount": 0,
                    "discount_amount": 0
                }
            ],
            "remaining_installments": [
                {
                    "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999",
                    "due_date": "2026-06-07",
                    "principal_amount": 516.13,
                    "interest_amount": 27.76,
                    "fine_amount": 0,
                    "total_amount": 543.89
                }
            ],
            "debt_key": "3571e292-3a83-4011-904d-20ee963022ef"
        }
    ],
    "payment": {
        "digitable_line": null,
        "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/acaeb341e1264cde99b93e247e12b3725204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***63043AD0",
        "qr_code_key": "acaeb341-e126-4cde-99b9-3e247e12b372",
        "bank_slip_key": null,
        "paid_method_type": "pix",
        "source_account_key": null,
        "payment_data": {
            "creditor_bank_account_key": "6108dd45-580d-48c4-b3bb-74c1e843be49",
            "batch_renegotiation_proposal_key": "ff5ad6dd-2087-4850-a3e8-b37634448b4e"
        }
    }
}
```

:::info Importante
Salve a **batch_proposal_key** retornada na resposta. Ela será necessária para consultar o status da renegociação em lote e para receber os webhooks de pagamento.
:::

## Erro: Desconto Excede Juros

Quando `discount_validation: "only_interest_discount"` é definido em uma operação e o valor de desconto aplicado excede a parcela de juros, a API retorna o seguinte erro:

Resposta de Erro

```json
{
    "code": "InvalidDiscountAmountOnlyInterestDiscount",
    "message": "Discount amount must be only interest discount"
}
```

A validação é feita **por parcela** durante o processamento da amortização. Se qualquer parcela individual tiver um desconto cujo valor inclua amortização de principal (`discount_principal_amortization_amount > 0`) ou multa (`discount_fine_amount > 0`), a requisição inteira é rejeitada.

## Cessão (Assignment)

:::info Nota
Após a proposta ser paga, o passo de cessão (`POST /credit_operations/assign`) cria uma transferência formal da operação de crédito. Este é um endpoint separado da **credit-operation-api**.

Quando a operação de crédito possui `iof_charge_method: "spread"`, o `assignment_amount` calculado inclui o IOF que **não** foi financiado nas parcelas. Ou seja, o valor de cessão reflete o custo total incluindo o IOF separado.
:::

---

# Proposta de Renegociação em Lote - BNPL

URL: /documentation/manual_bnpl_full/renegociacao/proposta

# Proposta de Renegociação em Lote - BNPL


## Resumo

Após simular os valores, é possível criar uma proposta de renegociação em lote para múltiplas operações BNPL. A proposta gera um único meio de pagamento (boleto e/ou Pix) que cobre todas as operações incluídas no lote.

Para o tipo de amortização **`present_amount`**, cada parcela informada em `operations[].installments[]` deve incluir **`paid_amount`** (valor pago/alocado naquela parcela) e **`discount_amount`** (desconto em R$ aplicado na parcela), além de **`installment_key`**.

:::caution Atenção
A renegociação em lote só pode ser criada com operações de um mesmo emitente e mesma chave de integração. Há um limite de **50 operações** para cada renegociação em lote.
:::

## Request

ENDPOINT /renegotiation/batch_proposal
MÉTODO POST

:::warning Atenção
Os campos `discount_amount` e `discount_percentage` **NÃO** podem ser enviados juntos no mesmo payload (nível raiz).
:::

:::info Nota
Na raiz do body, `discount_amount` e `discount_percentage` são alternativas para desconto global sobre o valor presente. Já os campos **`paid_amount`** e **`discount_amount`** dentro de cada objeto em `operations[].installments[]` definem a composição por parcela quando `amortization_type` é **`present_amount`** (são obrigatórios nesse modo e não conflitam com a regra da raiz).
:::

Request Body

```json
{
    "amortization_type": "present_amount",
    "reference_date": "2026-04-08",
    "proposal_due_date": "2026-04-15",
    "discount_percentage": 0.0,
    "payment_type": "pix",
    "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db",
    "operations": [
        {
            "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
            "installments": [
                {
                    "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88",
                    "paid_amount": 500,
                    "discount_amount": 50
                }
            ]
        },
        {
            "debt_key": "2cbfb9b1-1fdb-5f8d-9967-b338e5eb83f9",
            "installments": [
                {
                    "installment_key": "2ef25ed8-7124-44f5-9e3d-1d1a7196166e",
                    "paid_amount": 150,
                    "discount_amount": 10
                }
            ]
        }
    ]
}
```


### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `amortization_type`* | string | Tipo de amortização | **[Enumeradores Amortization Type](#enumeradores-amortization-type)** |
| `reference_date`* | string | Data de referência para cálculo do valor presente (D+1) | 10 |
| `proposal_due_date`* | string | Data de vencimento da proposta de renegociação | 10 |
| `payment_type`* | string | Tipo de pagamento | **[Enumeradores Payment Type](#enumeradores-payment-type)** |
| `request_control_key` | string | Chave de controle para rastreamento e identificação única (opcional) | UUID |
| `discount_percentage` | float | Percentual de desconto sobre o valor presente | 10 |
| `discount_amount` | float | Valor de desconto sobre o valor presente | 10 |
| `operations`* | array | Lista de operações a serem renegociadas | **[Objeto Operations](#objeto-operations)** |

### Objeto Operations

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `debt_key`* | string | Chave única da operação de crédito (DEBT-KEY) | UUID |
| `installments`* | array | Parcelas a serem renegociadas | **[Objeto Installments](#objeto-installments)** |

### Objeto Installments

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `installment_key`* | string | Chave da parcela a ser renegociada | UUID |
| `paid_amount` | float | Valor pago (ou alocado) na parcela, em reais (R$). Obrigatório quando `amortization_type` é **`present_amount`**. | 15,2 |
| `discount_amount` | float | Valor de desconto em reais (R$) aplicado na parcela. Obrigatório quando `amortization_type` é **`present_amount`** (use `0` se não houver desconto). Para outros tipos de amortização, permanece opcional por parcela. | 15,2 |

### Enumeradores Payment Type

| Campo | Descrição |
|---|---|
| `bank_slip` | Pagamento via boleto bancário (gera boleto e Pix) |
| `pix` | Pagamento via Pix (gera apenas Pix) |
| `internal` | Pagamento via transferência interna (processamento automático) |
| `manual` | Pagamento feito de forma manual (não gera forma de pagamento) |

### Enumeradores Amortization Type

| Campo | Descrição |
|---|---|
| **present_amount** | Renegociação com composição por valor presente por parcela. Em cada item de `installments[]` é obrigatório informar `installment_key`, **`paid_amount`** e **`discount_amount`**. |
| **installment_payment** | Renegociação para pagamento de parcelas específicas. Requer `installment_key` de cada parcela. |
| **overdue_installment_payment** | Renegociação direcionada para pagamento de parcelas em atraso. Requer `installment_key` de cada parcela. |

## Response

STATUS 201

Response Body

```json
{
    "batch_proposal_key": "ff5ad6dd-2087-4850-a3e8-b37634448b4e",
    "discount_percentage": 0,
    "discount_amount": 0,
    "amortization_type": "present_amount",
    "payment_amount": 517.88,
    "requester_name": "Dante Ltda",
    "requester_key": "78287247-947d-4730-9bd1-7efb068175b6",
    "issuer_name": "Dante Ferrarini",
    "reference_date": "2026-04-08",
    "issuer_document_number": "31057466093",
    "batch_proposal_status": "pending_payment",
    "proposal_due_date": "2026-04-15",
    "payment_type": "pix",
    "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db",
    "origin_key": null,
    "operations": [
        {
            "requester_key": "78287247-947d-4730-9bd1-7efb068175b6",
            "contract_number": "DWF1761222116",
            "payment_amount": 517.88,
            "discount_amount": 0,
            "origin_key": null,
            "affected_installments": [
                {
                    "installment_key": "1dea396f-beb1-4df3-9822-35800b4c095a",
                    "due_date": "2026-05-07",
                    "principal_amount": 491.49,
                    "interest_amount": 52.4,
                    "fine_amount": 0,
                    "total_amount": 543.89,
                    "present_amount": 517.88,
                    "paid_amount": 517.88,
                    "principal_amortization_payment_amount": 491.49,
                    "prefixed_interest_payment_amount": 26.39,
                    "fine_payment_amount": 0,
                    "discount_amount": 0
                }
            ],
            "remaining_installments": [
                {
                    "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999",
                    "due_date": "2026-06-07",
                    "principal_amount": 516.13,
                    "interest_amount": 27.76,
                    "fine_amount": 0,
                    "total_amount": 543.89
                }
            ],
            "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c"
        }
    ],
    "payment": {
        "digitable_line": null,
        "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/acaeb341e1264cde99b93e247e12b3725204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***63043AD0",
        "qr_code_key": "acaeb341-e126-4cde-99b9-3e247e12b372",
        "bank_slip_key": null,
        "paid_method_type": "pix",
        "source_account_key": null,
        "payment_data": {
            "creditor_bank_account_key": "6108dd45-580d-48c4-b3bb-74c1e843be49",
            "batch_renegotiation_proposal_key": "ff5ad6dd-2087-4850-a3e8-b37634448b4e"
        }
    }
}
```


:::info Importante
Salve a **batch_proposal_key** retornada na resposta. Ela será necessária para consultar o status da renegociação em lote e para receber os webhooks de pagamento.
:::

---

# Simulação - Renegociação em Lote BNPL

URL: /documentation/manual_bnpl_full/renegociacao/simulacao

# Simulação - Renegociação em Lote BNPL


## Resumo

Antes de criar uma proposta de renegociação, é possível simular os valores da renegociação em lote para operações BNPL. A simulação permite visualizar as parcelas afetadas, valores de desconto e o montante final a ser pago para múltiplas operações simultaneamente.

Com **`amortization_type`** igual a **`present_amount`**, envie em cada parcela de `operations[].installments[]` os campos **`paid_amount`**, **`discount_amount`** e **`installment_key`**, como na proposta em lote.

:::caution Atenção
A renegociação em lote só pode ser criada com operações de um mesmo emitente e mesma chave de integração. Há um limite de **50 operações** para cada renegociação em lote.
:::

## Request

ENDPOINT /renegotiation/batch_proposal_simulation
MÉTODO POST

:::warning Atenção
Os campos `discount_amount` e `discount_percentage` **NÃO** podem ser enviados juntos no mesmo payload (nível raiz).
:::

:::info Nota
Na raiz, `discount_amount` e `discount_percentage` são alternativas para desconto global. Os campos **`paid_amount`** e **`discount_amount`** em `operations[].installments[]` são usados com **`present_amount`** por parcela e não substituem a regra da raiz.
:::

Request Body

```json
{
    "amortization_type": "present_amount",
    "reference_date": "2026-04-08",
    "discount_percentage": 0.0,
    "operations": [
        {
            "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
            "installments": [
                {
                    "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88",
                    "paid_amount": 500,
                    "discount_amount": 50
                }
            ]
        },
        {
            "debt_key": "2cbfb9b1-1fdb-5f8d-9967-b338e5eb83f9",
            "installments": [
                {
                    "installment_key": "2ef25ed8-7124-44f5-9e3d-1d1a7196166e",
                    "paid_amount": 150,
                    "discount_amount": 10
                }
            ]
        }
    ]
}
```


### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `amortization_type`* | string | Tipo de amortização | **[Enumeradores Amortization Type](#enumeradores-amortization-type)** |
| `reference_date`* | string | Data de referência para cálculo do valor presente (precisa ser D+1) | 10 |
| `discount_percentage` | float | Percentual de desconto sobre o valor presente ((1 - percentual) * Valor Presente) | 10 |
| `discount_amount` | float | Valor de desconto aplicado sobre o valor presente | 10 |
| `operations`* | array | Lista de operações a serem renegociadas | **[Objeto Operations](#objeto-operations)** |

### Objeto Operations

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `debt_key`* | string | Chave única da operação de crédito (DEBT-KEY) | UUID |
| `installments`* | array | Parcelas a serem renegociadas | **[Objeto Installments](#objeto-installments)** |

### Objeto Installments

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `installment_key`* | string | Chave da parcela a ser renegociada | UUID |
| `paid_amount` | float | Valor pago (ou alocado) na parcela, em reais (R$). Obrigatório quando `amortization_type` é **`present_amount`**. | 15,2 |
| `discount_amount` | float | Valor de desconto em reais (R$) na parcela. Obrigatório quando `amortization_type` é **`present_amount`** (use `0` se não houver desconto). Opcional nos demais tipos. | 15,2 |

### Enumeradores Amortization Type

| Campo | Descrição |
|---|---|
| **present_amount** | Simulação com valor presente por parcela. Em cada `installments[]` é obrigatório `installment_key`, **`paid_amount`** e **`discount_amount`**. |
| **installment_payment** | Renegociação para pagamento de parcelas específicas enviadas no payload. Requer `installment_key` de cada parcela. |
| **overdue_installment_payment** | Renegociação direcionada para pagamento de parcelas em atraso. Requer `installment_key` de cada parcela. |

## Response

STATUS 200

Response Body

```json
{
    "batch_proposal_key": "7423c701-3578-4733-8f30-81ab60afdb6d",
    "discount_percentage": 0,
    "discount_amount": 0,
    "amortization_type": "present_amount",
    "payment_amount": 517.88,
    "requester_name": "Dante Ltda",
    "requester_key": "78287247-947d-4730-9bd1-7efb068175b6",
    "issuer_name": "Dante Ferrarini",
    "reference_date": "2026-04-08",
    "issuer_document_number": "31057466093",
    "operations": [
        {
            "requester_key": "78287247-947d-4730-9bd1-7efb068175b6",
            "contract_number": "DWF1761222116",
            "payment_amount": 517.88,
            "discount_amount": 0,
            "origin_key": null,
            "affected_installments": [
                {
                    "installment_key": "1dea396f-beb1-4df3-9822-35800b4c095a",
                    "due_date": "2026-05-07",
                    "principal_amount": 491.4903841,
                    "interest_amount": 52.3996159,
                    "fine_amount": 0,
                    "total_amount": 543.89,
                    "present_amount": 517.88,
                    "paid_amount": 517.88,
                    "principal_amortization_payment_amount": 491.49,
                    "prefixed_interest_payment_amount": 26.39,
                    "fine_payment_amount": 0,
                    "discount_amount": 0
                }
            ],
            "remaining_installments": [
                {
                    "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999",
                    "due_date": "2026-06-07",
                    "principal_amount": 516.1296159,
                    "interest_amount": 27.7603841,
                    "fine_amount": 0,
                    "total_amount": 543.89
                }
            ],
            "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c"
        }
    ]
}
```


### Campos de Desconto

Desconto percentual

```json
{
    "discount_percentage": 0.5
}
```


Desconto absoluto

```json
{
    "discount_amount": 200
}
```

---

# Webhooks - Renegociação em Lote BNPL

URL: /documentation/manual_bnpl_full/renegociacao/webhooks

## Resumo

Após a criação de uma proposta de renegociação em lote, o sistema enviará webhooks para notificar sobre o pagamento ou rejeição da proposta.

:::danger Atenção!
Os webhooks não devem ser mapeados de forma estrita. Novos campos podem ser adicionados ao payload sem aviso prévio.
:::

## Webhook de Pagamento

Este webhook é enviado quando o pagamento da proposta de renegociação em lote é confirmado.

WEBHOOK_TYPE renegotiation.batch_proposal
STATUS paid

Webhook Body

```json
{
    "webhook_type": "renegotiation.batch_proposal",
    "key": "<BATCH-PROPOSAL-KEY>",
    "event_datetime": "<DATA E HORA DO ENVIO DO WEBHOOK>",
    "status": "paid",
    "data": {
        "paid_method_type": "<METODO DE PAGAMENTO>",
        "paid_in": {
            "code_number": "<CODIGO DO BANCO LIQUIDANTE>",
            "ispb": "<ISPB DO BANCO LIQUIDANTE>",
            "name": "<NOME DO BANCO LIQUIDANTE>"
        }
    }
}
```

### Campos do Webhook de Pagamento

| Campo | Tipo | Descrição |
|---|---|---|
| **webhook_type** | string | Tipo do webhook: `renegotiation.batch_proposal` |
| **key** | string | Chave da proposta de renegociação em lote (BATCH-PROPOSAL-KEY) |
| **event_datetime** | string | Data e hora do envio do webhook |
| **status** | string | Status do evento: `paid` |
| **data.paid_method_type** | string | Método de pagamento utilizado |
| **data.paid_in.code_number** | string | Código do banco liquidante |
| **data.paid_in.ispb** | string | ISPB do banco liquidante |
| **data.paid_in.name** | string | Nome do banco liquidante |

### Enumeradores paid_method_type

| Enumerador | Descrição |
|---|---|
| **bank_slip** | Pagamento realizado por boleto |
| **pix** | Pagamento realizado por Pix |

---

## Webhook de Rejeição

Uma renegociação em lote pode ser rejeitada pelo decurso de prazo do pagamento ou por um pagamento de parcela por fora da renegociação.

WEBHOOK_TYPE renegotiation.batch_proposal
STATUS rejected

Webhook Body

```json
{
    "webhook_type": "renegotiation.batch_proposal",
    "key": "<BATCH-PROPOSAL-KEY>",
    "event_datetime": "<DATA E HORA DO ENVIO DO WEBHOOK>",
    "status": "rejected",
    "data": {}
}
```

:::caution Atenção
Uma renegociação em lote pode ser rejeitada por:
- **Decurso de prazo**: o pagamento não foi realizado dentro da data de vencimento (`proposal_due_date`)
- **Pagamento externo**: uma parcela incluída na renegociação foi paga por fora antes da confirmação do pagamento do lote
:::

---

## Dados de Pagamento na Parcela

Quando uma parcela é paga através de uma renegociação em lote, os dados de pagamento são registrados na parcela:

Payment Data

```json
{
    "batch_renegotiation_proposal_key": "f9addba2-ec91-41bf-a150-c59eb1c3fbef",
    "paid_in": {
        "ispb": "18236120",
        "name": "NU PAGAMENTOS - IP",
        "code_number": 260
    },
    "resource_account_key": "ea44b9f2-ad00-4896-b8a3-b1a3da28a72f"
}
```

### Campos dos Dados de Pagamento

| Campo | Tipo | Descrição |
|---|---|---|
| **batch_renegotiation_proposal_key** | string | Chave da proposta de renegociação em lote que originou o pagamento |
| **paid_in.ispb** | string | ISPB do banco utilizado para o pagamento |
| **paid_in.name** | string | Nome do banco utilizado para o pagamento |
| **paid_in.code_number** | integer | Código do banco utilizado para o pagamento |
| **resource_account_key** | string | Chave da conta de recursos que recebeu o pagamento |

---

# Scripts de Integração - BNPL Full

URL: /documentation/manual_bnpl_full/scripts_integracao

## Resumo

Disponibilizamos scripts Python prontos para uso que demonstram o fluxo completo de integração BNPL Full com a API Sandbox da QI Tech. Cada script corresponde a uma chamada de API testada e validada.

**Todos os payloads e respostas exibidos nesta documentação refletem as respostas reais da API Sandbox, obtidas através destes scripts.**

## Download

Os scripts estão disponíveis no repositório do projeto:

📦 Baixar pacote Python completo

## Pre-requisitos

- Python 3.8+
- Dependencias: `requests`, `python-jose`, `python-dotenv`
- Arquivo `_local.env` com suas credenciais Sandbox:
  - `API_KEY` - Sua chave de API
  - `QI_PUBLIC_KEY` - Chave publica da QI Tech
  - `CLIENT_PRIVATE_KEY` - Sua chave privada EC (PEM)

## Scripts Disponiveis

### Emissao

| # | Script | Endpoint | Metodo | Descricao |
|---|--------|----------|--------|-----------|
| 01 | `01_issuance_simulation.py` | `/v2/credit_operation/simulation` | POST | Simular uma operacao de credito antes da emissao |
| 02 | `02_issuance_issuance.py` | `/signed_debt` | POST | Emitir a divida com assinatura de contrato via opt-in |
| 03 | `03_issuance_query.py` | `/v2/credit_operation/requester_identifier_key/{key}` | GET | Consultar a operacao emitida |

### Estorno

| # | Script | Endpoint | Metodo | Descricao |
|---|--------|----------|--------|-----------|
| 04 | `04_reversal_cancel_before_disbursement.py` | `/debt/{debt_key}/cancel` | PATCH | Cancelar operacao antes do desembolso |
| 05 | `05_reversal_cancel_after_disbursement.py` | `/debt/reversal` | POST | Estornar operacao apos desembolso (gera Pix de devolucao) |

### Renegociacao

| # | Script | Endpoint | Metodo | Descricao |
|---|--------|----------|--------|-----------|
| 06 | `06_renegotiation_simulation.py` | `/renegotiation/batch_proposal_simulation` | POST | Simular renegociacao em lote |
| 07 | `07_renegotiation_proposal.py` | `/renegotiation/batch_proposal` | POST | Criar proposta de renegociacao em lote |
| 08 | `08_renegotiation_query.py` | `/renegotiation/batch_proposal/{key}` | GET | Consultar proposta por chave |
| 09 | `09_renegotiation_list.py` | `/renegotiation/batch_proposal` | GET | Listar todas as propostas |
| 10 | `10_renegotiation_cancel.py` | `/renegotiation/batch_proposal/{key}` | DELETE | Cancelar proposta pendente |

### Refinanciamento

| # | Script | Endpoint | Metodo | Descricao |
|---|--------|----------|--------|-----------|
| 11 | `11_refinancing_present_value.py` | `/debt` | GET | Consultar valor presente para calculo de refinanciamento |
| 12 | `12_refinancing_simulation.py` | `/debt_simulation` | POST | Simular operacao de refinanciamento |
| 13 | `13_refinancing_issuance.py` | `/signed_debt` | POST | Criar refinanciamento (emite nova divida, liquida a anterior) |

## Como Usar

1. Baixe os scripts do repositorio
2. Crie um arquivo `_local.env` com suas credenciais Sandbox
3. Execute os scripts em ordem numerica
4. Atualize as chaves (`DEBT_KEY`, `BATCH_PROPOSAL_KEY`, etc.) entre os scripts conforme necessario

:::info Sobre os exemplos da documentacao
Cada script inclui a resposta real da API como bloco de comentario no final do arquivo. Esses exemplos sao a fonte de verdade para os payloads exibidos nas paginas desta documentacao.
:::

---

# Manual Cartão Consignado - Changelog

URL: /documentation/manual_cartao_beneficio/changelog

Mudanças de contrato do cartão consignado, para quem já integra. As **rotas de cliente não mudaram** em nenhum momento — apenas o corpo das requisições e alguns códigos de erro.

:::caution API em desenvolvimento
A API ainda está em fase de desenvolvimento, sendo assim, este manual está sujeito a alterações.
:::

## Suporte a múltiplas fontes de consignação

O cartão passou a atender mais de uma folha de pagamento. Para isso, o que antes era uma única string fundida virou dois campos independentes: a **fonte de consignação** na rota e o **produto** no payload. Ver [Visão Geral](/documentation/manual_cartao_beneficio/visao_geral#fontes-de-consignacao).

### `collateral.collateral_type` foi removido; `product_type` é obrigatório

O campo `collateral.collateral_type`, que combinava fonte e produto em uma string (`social_security_benefit_card`), **não é mais aceito** em nenhum corpo de requisição. Em seu lugar, informe `product_type` no primeiro nível.

**Antes**

```json
{
  "collateral": {
    "state": "MG",
    "benefit_number": "5556667777",
    "collateral_type": "social_security_benefit_card",
    "subcorban_document_number": "12123456000101",
    "assistance_type": "pension_by_death_rural_worker"
  }
}
```

**Agora**

```json
{
  "product_type": "benefit_card",
  "collateral": {
    "state": "MG",
    "benefit_number": "5556667777",
    "subcorban_document_number": "12123456000101",
    "assistance_type": "pension_by_death_rural_worker"
  }
}
```

Vale para a **criação** (`POST /payroll_card_reservation/{collateral_type}`) e para a **simulação** (`POST /payroll_card_reservation/{collateral_type}/simulation`). Na simulação, a seção `collateral` passou a ser opcional e o INSS não a envia.

As **respostas não mudaram**: o campo `payroll_card_type` continua devolvendo a string combinada, como antes.

### `GET /eligibility` exige `product_type`

A consulta de elegibilidade passou a exigir o parâmetro `product_type`, porque a faixa etária elegível é definida por tipo de cartão.

```
GET /payroll_card_reservation/social_security/eligibility?document_number=...&birth_date=...&product_type=benefit_card
```

## Limites passaram a ser validados por tipo de cartão

Tetos comerciais — número de parcelas, taxa de juros mensal, `withdrawal_ratio` e `limit_days_to_disburse` — deixaram de ser limites fixos do schema e passaram a ser configuração do seu tipo de cartão.

⚠️ **Mudança de código de erro.** Um valor acima do teto era recusado pela validação de schema, com `QIT000001`. Agora é recusado pela regra de negócio, com **`PCR000001`**. O status HTTP continua **400**, mas o `code` e a `description` mudaram — a nova mensagem informa o campo, o valor recebido e o máximo permitido. Se a sua integração trata códigos de erro individualmente, este é o ponto a ajustar.

## Novos códigos de erro

| Código | Status | Quando ocorre |
|---|---|---|
| `PCR000001` | 400 | Um valor da requisição excede o teto do tipo de cartão |
| `PCR000004` | 400 | A combinação de fonte de consignação (rota) e `product_type` (payload) não corresponde a um tipo de cartão contratado |
| `PCR000005` | 400 | A entrada financeira enviada não é aceita pelo tipo de cartão — `salary_amount` e `available_margin` são mutuamente exclusivos e cada tipo aceita um deles |

## Consulta por `request_control_key` removida da documentação

A rota `GET /payroll_card_reservation/{collateral_type}/request_control_key/{request_control_key}` estava documentada mas **nunca existiu** na API. A referência foi removida. Para localizar uma reserva, use a chave da reserva ou a [consulta por CPF do portador](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_acompanhamento).

O campo `request_control_key` continua existindo normalmente no corpo da criação e nas respostas.

---

# Manual Cartão Consignado - Acompanhamento

URL: /documentation/manual_cartao_beneficio/manual_cartao_beneficio_acompanhamento

:::info Navegação
- [Emissão](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_emissao) (anterior)
- [Webhooks](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_webhook) (próximo)
:::

:::caution API em desenvolvimento
A API ainda está em fase de desenvolvimento, sendo assim, este manual esta sujeito a alterações.
:::

---

## 1. Consulta da reserva do cartão consignado

Consulta os detalhes de uma reserva específica através de sua chave (`payroll_card_reservation_key`). Retorna um **único objeto** contendo os detalhes da reserva.

**GET**
/payroll_card_reservation/{collateral_type}/[PAYROLL-CARD-RESERVATION-KEY]

Testar no Playground

#### Query Params

**Query Params**

| Campo       | Tipo    | Descrição                                                                 |
|-------------|---------|---------------------------------------------------------------------------|
| retrieve_document_urls | bool  | Se as URLs de certos documentos devem ser retornadas. Definido como False como padrão. |

:::warning Parâmetro retrieve_document_urls

Ativar esse parâmetro pode causar latências na requisição. Utilizar apenas quando necessário. 

Atualmente, apenas o campo `benefit.policy_document_url` é impactado por esse parâmetro, mas outros campos de url (como `attached_documents.document_url` e `attached_documents.signature_url`) serão atualizados para depender desse parâmetro. 

Os campos impactados (tanto atualmente quanto no futuro) estão demarcados por (*).

:::

### Response

**Response Body**

```json
{
  "request_control_key": "550e8400-e29b-41d4-a716-446655440000",
  "payroll_card_reservation_key": "3571e292-3a83-4011-904d-20ee963022ef",
  "payroll_card_reservation_status": "pending_document_generation",
  "card_holder_document_number": "12345678901",
  "identifier_number": "1234567890",
  "total_limit_amount": 8000.00,
  "reservation_amount": 250.00,
  "reservation_contract_number": "PCR0123456789",
  "wallet_key": null,
  "payroll_card_type": "social_security_payroll_card",
  "signature_url": "https://sandbox.sign.qitech.com.br/s/teste",
  "signature_data": {
      "document_similarity_score": 1,
      "similarity_score": 0.75,
      "biometry_analysis_reference": "internal",
  },
  "withdrawal": {
    "withdrawal_key": "b2c3d4e5-f6g7-8901-bcde-f23456789012",
    "withdrawal_amount": 5600.00,
    "withdrawal_status": "waiting_signature",
    "contract_number": "PCR12345678",
    "disbursement_date": "2025-08-08",
    "withdrawal_data": {
      "disbursement_options": [
        {
          "disbursement_date": "2025-08-08",
          "cet": 0.0262,
          "annual_cet": 0.3643,
          "issue_amount": 5827.36,
          "prefixed_interest_rate": {
            "daily_rate": 0.0008104046,
            "interest_base": "calendar_days",
            "monthly_rate": 0.0246,
            "annual_rate": 0.3386043084
          },
          "installments": [
            {
              "total_amount": 152.5,
              "due_date": "2025-10-10",
              "installment_number": 1
            },
            {
              "total_amount": 152.5,
              "due_date": "2025-11-10",
              "installment_number": 2
            },
            {
              "total_amount": 152.5,
              "due_date": "2025-12-10",
              "installment_number": 3
            }
          ]
        }
      ]
    }
  },
  "payroll_card": {
    "payroll_card_key": "c3d4e5f6-g7h8-9012-cdef-345678901234",
    "payroll_card_status": "pending_issuance",
    "card_limit": 2400.00,
    "card_issuance_entry_amount": 17.28
  },
  "attached_documents": [
    {
      "document_key": "d4e5f6g7-h8i9-0123-defg-456789012345",
      "document_batch_key": "e5f6g7h8-i9j0-1234-efgh-567890123456",
      "document_type": "withdrawal_operation_term",
      "document_certifier": "qi_sign",
      "document_status": "pending_generation",
      "document_url": null,
      "signature_url": null,
    },
    {
      "document_key": "f6g7h8i9-j0k1-2345-fghi-678901234567",
      "document_batch_key": "e5f6g7h8-i9j0-1234-efgh-567890123456",
      "document_type": "payroll_card_term",
      "document_certifier": "qi_sign",
      "document_status": "pending_generation",
      "document_url": null,
      "signature_url": null,
    },
    {
      "document_key": "925c0a62-ef98-4891-909b-9955a87ccefb",
      "document_batch_key": "e5f6g7h8-i9j0-1234-efgh-567890123456",
      "document_type": "payroll_card_consent_term",
      "document_certifier": "qi_sign",
      "document_status": "pending_generation",
      "document_url": null,
      "signature_url": null,
    }
  ],
  "benefit": {
    "benefit_key": "0b80d313-2ade-4a28-be58-38b9219c2b8c",
    "card_insurance_key": "0151934c-b219-458f-98a3-8b0f85c70307",
    "status": "active",
    "due_date": "2036-02-18",
    "policy_document_key": "6363eb63-2e85-4786-bc03-8c1ddd8e2be2",
    "policy_document_url": "https://example.com/policy.pdf"
  }
}
```

**Response Body Details**

| Campo | Tipo | Descrição |
|---|---|---| 
| request_control_key | string | Chave de identificação da requisição | 
| payroll_card_reservation_key | string | Chave da reserva do cartão consignado | 
| payroll_card_reservation_status | string | Status da reserva do cartão consignado | 
| card_holder_document_number | string | CPF do portador do cartão | 
| identifier_number | string | Número identificador da operação | 
| reservation_amount | number | Valor da reserva do cartão consignado |
| reservation_contract_number | string | Número do contrato de averbação na Dataprev | 
| withdrawal | object | Dados do saque | 
| payroll_card | object | Dados do cartão consignado | 
| attached_documents | array | Lista de documentos anexados | 
| payroll_card_type | string | Tipo do cartão — a fonte de consignação e o produto combinados, por exemplo `social_security_benefit_card` ou `public_payroll_payroll_card` | 
| wallet_key | string | Chave única da wallet criada (UUID4) | 
| signature_url | string | URL de assinatura do contrato da reserva (Apenas presente no payload após geração do link de assiantura) | 
| signature_data | object | Dados biométricos coletados na assinatura (Apenas presente no payload após assinatura dos documentos) | 
| benefit | object | Dados do seguro/benefício associado ao cartão (Apenas presente no payload após emissão do cartão) | 

#### Payload withdrawal

| Campo | Tipo | Descrição | 
|---|---|---| 
| withdrawal_key | string | Chave única do saque | 
| contract_number | string | Número do contrato da CCB de saque | 
| withdrawal_amount | number | Valor de desembolso calculado para CCB de saque | 
| disbursement_date | date | Data de desembolso da operação | 
| withdrawal_status | string | Status do saque | 
| withdrawal_data | object | Dados detalhados do saque |

#### Payload withdrawal_data

| Campo | Tipo | Descrição |
|---|---|---| 
| prefixed_interest_rate | object | Taxa de juros prefixada | 
| disbursement_options | array | Opções de desembolso disponíveis | 

#### Payload prefixed_interest_rate

| Campo | Tipo | Descrição | 
|---|---|---| 
| daily_rate | number | Taxa diária | 
| interest_base | string | Base de cálculo dos juros | 
| monthly_rate | number | Taxa mensal | 
| annual_rate | number | Taxa anual | 

#### Payload disbursement_options

| Campo | Tipo | Descrição | 
|---|---|---| 
| disbursement_date | string | Data do desembolso | 
| cet | number | Custo Efetivo Total mensal | 
| annual_cet | number | Custo Efetivo Total anual | 
| total_iof | number | Valor total de IOF |  
| disbursed_issue_amount | number | Valor de desembolso |  
| issue_amount | number | Valor de emissão |  
| installments | array | Lista de parcelas | 

#### Payload installments

| Campo | Tipo | Descrição | 
|---|---|---| 
| total_amount | number | Valor total da parcela | 
| due_date | string | Data de vencimento | 
| installment_number | number | Número da parcela | 

#### Payload payroll_card

| Campo | Tipo | Descrição | 
|---|---|---| 
| payroll_card_key | string | Chave única do cartão consignado | 
| payroll_card_status | string | Status do cartão consignado | 
| card_limit | number | Limite total calculado para o cartão | 
| card_issuance_entry_amount | number | Valor da Taxa de emissão do cartão | 

#### Payload attached_documents

| Campo | Tipo | Descrição | 
|---|---|---| 
| document_key | string | Chave única do documento | 
| document_batch_key | string | Chave do lote de documentos | 
| document_type | string | Tipo do documento | 
| document_certifier | string | Certificadora do documento | 
| document_status | string | Status do documento | 
| document_url (*) | string | URL do documento | 
| signature_url (*) | string | URL da assinatura | 

---

#### Payload signature_data

| Campo | Tipo | Descrição | 
|---|---|---| 
| document_similarity_score | number | Nota de similiaridade biométrica entre o assinante e o documento enviado (0-1) |
| similarity_score | number | Nota de similiaridade biométrica entre o assinante e a referência encontrada na base de rostos (0-1) |
| biometry_analysis_reference | string | Base de origem do rosto utilizado para o calculo da nota de similaridade biométrica |

---

#### Payload benefit

| Campo | Tipo | Descrição | 
|---|---|---| 
| benefit_key | string | Chave única do benefício (UUID) | 
| status | string | Status da emissão do Seguro (`created`, `pending_emission`, `active`, `canceled` ou `inactive`)  |
| policy_document_key | string | Chave única do documento da apólice (UUID) |
| policy_document_url (*) | string | URL do documento de apólice do seguro |

---

## 2. Consulta de reservas do cartão consignado por CPF

Consulta as reservas ativas de um determinado CPF. Retorna uma **lista de objetos** dentro da propriedade `payroll_card_reservations`.

**GET**
/payroll_card_reservation/{collateral_type}/card_holder_document_number/[CARD-HOLDER-DOCUMENT-NUMBER]

Testar no Playground

### Response

**Response Body**

```json
{
   "payroll_card_reservations": [
      {
        "request_control_key": "d3bc353e-d612-4029-9d77-4dca9171c3b5",
        "payroll_card_reservation_key": "5fb9d810-be74-4d26-959d-c75d10834e93",
        "payroll_card_reservation_status": "card_issued",
        "card_holder_document_number": "12345678901",
        "identifier_number": "1234567890",
        "total_limit_amount": 8000.00,
        "reservation_amount": 250.00,
        "reservation_contract_number": "PCR0123456789",
        "wallet_key": "298e4d37-0f20-4aed-ad66-016f8487afba",
        "payroll_card_type": "social_security_payroll_card",
        "card_holder": {
          "email": "joao.teste@example.com",
          "phone": {
            "number": "352141677",
            "area_code": "11",
            "country_code": "055"
          },
          "address": {
            "city": "Belo Horizonte",
            "state": "MG",
            "number": "7889",
            "street": "Rua Santos",
            "complement": "Apto 243",
            "postal_code": "30112000",
            "neighborhood": "Centro"
          }
        },
        "attached_documents": [
          {
              "document_key": "910e8de5-16af-4bc5-8ee1-4a0652ca0cbf",
              "document_type": "withdrawal_operation_term",
              "document_certifier": "qi_sign",
              "document_status": "signed",
              "document_batch_key": "f28bf87a-11cd-4d89-89c0-19229a1b31a7",
              "document_url": "https://storage.googleapis.com/example_document.pdf",
              "signature_url": "https://storage.googleapis.com/example_document_signed.pdf",
          },
          {
              "document_key": "332017f4-a0d6-463a-8557-e925a9485251",
              "document_type": "payroll_card_term",
              "document_certifier": "qi_sign",
              "document_status": "signed",
              "document_batch_key": "f28bf87a-11cd-4d89-89c0-19229a1b31a7",
              "document_url": "https://storage.googleapis.com/example_document.pdf",
              "signature_url": "https://storage.googleapis.com/example_document_signed.pdf",
          },
          {
              "document_key": "b098074a-7cba-4b67-81e1-8d587185504b",
              "document_type": "payroll_card_consent_term",
              "document_certifier": "qi_sign",
              "document_status": "signed",
              "document_batch_key": "f28bf87a-11cd-4d89-89c0-19229a1b31a7",
              "document_url": "https://storage.googleapis.com/example_document.pdf",
              "signature_url": "https://storage.googleapis.com/example_document_signed.pdf",
          },
          {
              "document_key": "b1c3e915-6707-49f5-85a9-398ef997fdad",
              "document_type": "selfie",
              "document_certifier": "qi_sign",
              "document_status": "generated",
              "document_url": "https://storage.googleapis.com/selfie.jpeg"
          },
          {
              "document_key": "5769a335-a2ac-4913-a742-38b9d1e4abd2",
              "document_type": "document_identification",
              "document_certifier": "qi_sign",
              "document_status": "generated",
              "document_url": "https://storage.googleapis.com/cnh.jpeg"
          },
          {
              "document_key": "75577d34-4ebd-4488-aca8-b064e603c973",
              "document_type": "document_identification_back",
              "document_certifier": "qi_sign",
              "document_status": "generated",
              "document_url": "https://storage.googleapis.com/cnh_back.jpeg"
          },
          {
              "document_key": "2fc216c6-5d1c-4713-b70b-6e1f75f8bb17",
              "document_type": "payroll_card_confirmation_video",
              "document_certifier": "electronic_client_side",
              "document_status": "generated",
              "document_url": "https://storage.googleapis.com/video.mp4"
          }
        ],
      },
      {
        "request_control_key": "d3bc353e-d612-4029-9d77-4dca9171c3b5",
        "payroll_card_reservation_key": "5fb9d810-be74-4d26-959d-c75d10834e93",
        "payroll_card_reservation_status": "pending_withdrawal_disbursement",
        "card_holder_document_number": "12345678901",
        "identifier_number": "1234567890",
        "total_limit_amount": 8000.00,
        "reservation_amount": 250.00,
        "reservation_contract_number": "PCR0123456789",
        "wallet_key": "298e4d37-0f20-4aed-ad66-016f8487afba",
        "payroll_card_type": "social_security_payroll_card",
        "card_holder": {
          "email": "joao.teste@example.com",
          "phone": {
            "number": "352141677",
            "area_code": "11",
            "country_code": "055"
          },
          "address": {
            "city": "Belo Horizonte",
            "state": "MG",
            "number": "7889",
            "street": "Rua Santos",
            "complement": "Apto 243",
            "postal_code": "30112000",
            "neighborhood": "Centro"
          }
        },
        "attached_documents": [
          {
              "document_key": "910e8de5-16af-4bc5-8ee1-4a0652ca0cbf",
              "document_type": "withdrawal_operation_term",
              "document_certifier": "qi_sign",
              "document_status": "signed",
              "document_batch_key": "f28bf87a-11cd-4d89-89c0-19229a1b31a7",
              "document_url": "https://storage.googleapis.com/example_document.pdf",
              "signature_url": "https://storage.googleapis.com/example_document_signed.pdf",
          },
          {
              "document_key": "332017f4-a0d6-463a-8557-e925a9485251",
              "document_type": "payroll_card_term",
              "document_certifier": "qi_sign",
              "document_status": "signed",
              "document_batch_key": "f28bf87a-11cd-4d89-89c0-19229a1b31a7",
              "document_url": "https://storage.googleapis.com/example_document.pdf",
              "signature_url": "https://storage.googleapis.com/example_document_signed.pdf",
          },
          {
              "document_key": "87c23417-c342-4cc7-81b6-81185b6012ce",
              "document_type": "payroll_card_consent_term",
              "document_certifier": "qi_sign",
              "document_status": "signed",
              "document_batch_key": "f28bf87a-11cd-4d89-89c0-19229a1b31a7",
              "document_url": "https://storage.googleapis.com/example_document.pdf",
              "signature_url": "https://storage.googleapis.com/example_document_signed.pdf",
          },
          {
              "document_key": "b1c3e915-6707-49f5-85a9-398ef997fdad",
              "document_type": "selfie",
              "document_certifier": "qi_sign",
              "document_status": "generated",
              "document_url": "https://storage.googleapis.com/selfie.jpeg"
          },
          {
              "document_key": "5769a335-a2ac-4913-a742-38b9d1e4abd2",
              "document_type": "document_identification",
              "document_certifier": "qi_sign",
              "document_status": "generated",
              "document_url": "https://storage.googleapis.com/cnh.jpeg"
          },
          {
              "document_key": "75577d34-4ebd-4488-aca8-b064e603c973",
              "document_type": "document_identification_back",
              "document_certifier": "qi_sign",
              "document_status": "generated",
              "document_url": "https://storage.googleapis.com/cnh_back.jpeg"
          },
          {
              "document_key": "b574b555-e3c9-402a-a869-c4bc27751be8",
              "document_type": "payroll_card_confirmation_video",
              "document_certifier": "electronic_client_side",
              "document_status": "generated",
              "document_url": "https://storage.googleapis.com/video.mp4"
          }
        ],
      }
   ]
}
```

---

## 3. Máquinas de Status

### Payroll Card Reservation

A entidade **Payroll Card Reservation** possui os seguintes status e transições:

![Status e transições da entidade Payroll Card Reservation](/img/diagrams/manual-cartao-beneficio-manual-cartao-beneficio-acompanhamento-1.svg)

#### Descrição dos Status

| Status | Descrição |
|--------|-----------|
| `pending_document_generation` | Aguardando geração dos documentos para assinatura |
| `pending_onboarding` | Aguardando processo de onboarding e KYC |
| `pending_additional_documents_submission` | Onboarding aprovado. Aguardando envio do vídeo de confirmação |
| `pending_additional_documents_validation` | Aguardando validação do vídeo de confirmação |
| `pending_collateral_reservation` | Documentos adicionais aprovados. Aguardando reserva de margem na Dataprev |
| `pending_withdrawal_disbursement` | Margem averbada. Aguardando desembolso da operação de saque |
| `pending_card_issuance` | Aguardando criação da wallet e emissão do cartão |
| `card_issued` | Cartão criado e ativo |
| `canceled` | Operação cancelada |

### Withdrawal

A entidade **Withdrawal** possui os seguintes status e transições:

![Status e transições da entidade Withdrawal](/img/diagrams/manual-cartao-beneficio-manual-cartao-beneficio-acompanhamento-2.svg)

#### Descrição dos Status

| Status | Descrição |
|--------|-----------|
| `pending_signature` | Aguardando assinatura dos termos |
| `pending_disbursement` | Aguardando desembolso da operação de saque |
| `opened` | Desembolso realizado e operação ativa |
| `canceled` | Operação cancelada |

### Benefit

A entidade **Benefit** possui os seguintes status e transições:

![Status e transições da entidade Benefit](/img/diagrams/manual-cartao-beneficio-manual-cartao-beneficio-acompanhamento-3.svg)

#### Descrição dos Status

| Status | Descrição |
|--------|-----------|
| `created` | Seguro em procesasmento |
| `pending_emission` | Aguardando emissão do seguro |
| `active` | Seguro emitido e ativo |
| `canceled` | Seguro cancelado |
| `inactive` | Seguro expirado ou inativo |

---

## 4. Cancelamento da reserva

Permite o cancelamento da reserva do cartão consignado. 

:::warning Restrições
O cancelamento via API só é permitido **antes** do desembolso do saque (Status: `pending_withdrawal_disbursement` ou anterior). 
Caso o saque já tenha sido realizado ou o cartão já esteja emitido, o cancelamento deve ser tratado via suporte, pois envolve estorno financeiro.
:::

**PATCH**
/payroll_card_reservation/{collateral_type}/[PAYROLL-CARD-RESERVATION-KEY]/cancel

Testar no Playground

### Response

STATUS
**200** (OK)

A requisição foi processada com sucesso. Não há retorno de conteúdo (Body vazio).

```json
// Empty response body
```

---

# Documentos e Assinatura

URL: /documentation/manual_cartao_beneficio/manual_cartao_beneficio_documentos

:::info Navegação
- [Webhooks](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_webhook) (anterior)
- [Gestão de Endereço](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_endereco) (próximo)
:::

Esta seção detalha o fluxo de geração de documentos e o processo de assinatura eletrônica, seja via fluxo externo ou via Qi Sign.

:::info Obs
Caso o cliente esteja integrado no fluxo de assinatura do QISign, os itens dessa secção são opcionais.
:::

## 1. Webhook de Documentos

Após a criação da operação, os documentos (`payroll_card_term`, `withdrawal_operation_term` e `payroll_card_consent_term`) são gerados assincronamente. A API envia um webhook para cada documento notificando a mudança de status do documento.

:::caution Atenção
Caso o cliente não utilize o QISign, o cliente deve implementar o tratamento deste webhook para capturar as URLs dos documentos e direcionar o beneficiário para a assinatura através da certificadora externa escolhida.
:::

:::info Acompanhamento via Webhook
Para conferir a estrutura completa dos payloads, os cenários de eventos e implementar a captura das URLs, consulte a seção **[Webhook de Documentos (Geração e Validação)](./manual_cartao_beneficio_webhook.md#2-webhook-de-documentos-geração-e-validação)** no Manual de Webhooks.
:::

## 2. Assinatura externa de documentos

Este endpoint é utilizado quando a coleta da assinatura e biometria é feita pela interface do cliente (Client Side) ou parceiro externo. O cliente deve enviar os documentos assinados e os dados biométricos para validação.

:::caution Atenção
Esta etapa só deve ser chamada se o fluxo de assinatura **não** for o Qi Sign. Se estiver utilizando Qi Sign, a confirmação será automática.
:::

:::tip Antes de enviar
Realize o upload dos 5 documentos obrigatórios (selfie, frentes/verso do RG, contrato de cartão e contrato de saque) utilizando o endpoint de Upload de Documentos para obter as `document_key`s.
:::

### Request

**POST**
/payroll_card_reservation/{collateral_type}/{payroll_card_reservation_key}/signature

Testar no Playground

**Request Body**

```json
{
  "documents": [
    { "document_type": "selfie", "document_key": "2c8f2b3d-8c7a-4e3b-9f6a-1234567890ab" },
    { "document_type": "document_identification", "document_key": "b1a2c3d4-e5f6-7890-abcd-ef0123456789" },
    { "document_type": "document_identification_back", "document_key": "0a1b2c3d-4e5f-6789-0abc-def123456789" },
    { "document_type": "payroll_card_term", "document_key": "9f8e7d6c-5b4a-3210-fedc-ba9876543210" }, 
    { "document_type": "payroll_card_consent_term", "document_key": "d9b64eae-6e11-4b82-92f0-a0e1a3049eee" }, 
    { "document_type": "withdrawal_operation_term", "document_key": "a05c74eb-542a-4820-8954-eef92ebb383f" }
  ],
  "ip_address": "192.168.1.100",
  "signature_datetime": "2025-01-15T14:30:00Z",
  "similarity_score": 0.95,
  "biometry_analysis_reference": "serpro"
}
```

**Request Body Details**

| Campo | Tipo | Descrição | Obrigatório |
|---|---|---|---|
| documents | array | Lista dos 5 documentos exigidos | Sim |
| biometry_analysis_reference | string | Referência da análise biométrica | Sim |
| signature_datetime | string | Data e hora da assinatura (ISO 8601) | Sim |
| ip_address | string | Endereço IP de onde foi feita a assinatura | Sim |
| similarity_score | float | Score de similaridade biométrica | Sim |

#### Enumeradores _Biometry Analysis Reference_

| Enumerador    | Descrição                                                                                                                                                                                                                                                          |
|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| serpro    | Utilizado quando o similarity_score for retornado através de consulta realizada na base de documentos com foto do Detran (Serviço prestado através da Serpro)                                                                                                      |
| tse       | Utilizado quando o similarity_score for retornado através de consulta realizada na base de documentos com foto do TSE                                                                                                                                              |
| not_found | Deve ser informado quando a biometria facial não for localizada em nenhuma das bases governamentais anteriores (serpro ou tse). Neste caso o similarity_score deve ser null ou o grau de similaridade da selfie com o documento oficial com foto, retornado pelo parceiro. |

#### Item de documents

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| document_type | string | Tipo do documento | Enum: "selfie", "document_identification", "document_identification_back", "payroll_card_term", "payroll_card_consent_term", "withdrawal_operation_term" | Sim |
| document_key | string | Chave única do documento | UUID v4 | Sim |

**Observações sobre os tipos de documento:**
- `selfie`: Foto do beneficiário
- `document_identification`: Frente do documento de identificação
- `document_identification_back`: Verso do documento de identificação  
- `payroll_card_term`: Termos e condições do cartão **assinado** 
- `payroll_card_consent_term`: Termo de consentimento da contratação do cartão **assinado** 
- `withdrawal_operation_term`: Termo da operação de saque **assinado** 

:::danger QI Sign
A QI Tech oferece o serviço de assinatura que atende ao determinado pela IN 138. Com biometria facial e envio de documentos.

Para receber uma cotação consulte nosso time comercial:

comercial@qitech.com.br ou (11) 2339-4763
:::

### Response

STATUS
**200** (OK)

**Response Body**

```json
{
  "payroll_card_reservation_key": "d4e5f6g7-h8i9-0123-defg-456789012345",
  "payroll_card_reservation_status": "pending_onboarding",
  "attached_documents": [
    {
      "document_key": "0b6c9bb9-0bc1-4fd2-9aab-3ccf5c8bc69d",
      "document_type": "withdrawal_operation_term",
      "document_certifier": "electronic_client_side",
      "document_url": "https://storage.googleapis.com/live-doc-api/documents/withdrawal_operation_term.pdf",
      "document_status": "signed",
      "document_batch_key": "ccc42bc6-efbc-4e8f-a7da-fb6cb77e4146",
      "signature_url": "https://storage.googleapis.com/live-doc-api/documents/withdrawal_operation_term_signed.pdf",
    },
    {
      "document_key": "f974bb60-ff4c-4027-9d88-399470586691",
      "document_type": "payroll_card_term",
      "document_certifier": "electronic_client_side",
      "document_url": "https://storage.googleapis.com/live-doc-api/documents/payroll_card_term.pdf",
      "document_status": "signed",
      "document_batch_key": "ccc42bc6-efbc-4e8f-a7da-fb6cb77e4146",
      "signature_url": "https://storage.googleapis.com/live-doc-api/documents/payroll_card_term_signed.pdf",
    },
    {
      "document_key": "0133eda8-0e82-41d9-ae8d-7020f023b0f9",
      "document_type": "payroll_card_consent_term",
      "document_certifier": "electronic_client_side",
      "document_url": "https://storage.googleapis.com/live-doc-api/documents/payroll_card_consent_term.pdf",
      "document_status": "signed",
      "document_batch_key": "ccc42bc6-efbc-4e8f-a7da-fb6cb77e4146",
      "signature_url": "https://storage.googleapis.com/live-doc-api/documents/payroll_card_consent_term.pdf",
    },
    {
      "document_key": "2c8f2b3d-8c7a-4e3b-9f6a-1234567890ab",
      "document_type": "selfie",
      "document_certifier": "electronic_client_side",
      "document_url": "https://storage.googleapis.com/live-doc-api/documents/selfie.pdf",
      "document_status": "generated"
    },
    {
      "document_key": "b1a2c3d4-e5f6-7890-abcd-ef0123456789",
      "document_type": "document_identification",
      "document_certifier": "electronic_client_side",
      "document_url": "https://storage.googleapis.com/live-doc-api/documents/document_identification.pdf",
      "document_status": "generated"
    },
    {
      "document_key": "0a1b2c3d-4e5f-6789-0abc-def123456789",
      "document_type": "document_identification_back",
      "document_certifier": "electronic_client_side",
      "document_url": "https://storage.googleapis.com/live-doc-api/documents/document_identification_back.pdf",
      "document_status": "generated"
    }
  ]
}
```

**Response Body Details**

| Campo | Tipo | Descrição |
|---|---|---|
| payroll_card_reservation_key | string | Chave da reserva do cartão consignado |
| payroll_card_reservation_status | string | Status da reserva (pending_onboarding) |
| attached_documents | array | Lista de documentos e seus status |

:::info Informação
Após a confirmação da assinatura dos dois documentos, o status do cartão consignado será alterado para "pending_onboarding", indicando que a operação está aguardando o processo de onboarding do cartão.
:::

#### Erros comuns

**404 - Document Not Found**

```json
{
  "title": "Document Not Found",
  "description": "Document selfie not found",
  "translation": "Documento selfie não encontrado"
}
```

**Explicação:** Este erro ocorre quando a `document_key` informada no request não foi encontrada no sistema. Verifique se a `document_key` foi obtida corretamente através do endpoint de Upload de documentos

---

## 3. Confirmação de Assinatura

Independente do método de assinatura (Externa ou Qi Sign), quando o processo for concluído com sucesso, você receberá um webhook de mudança de status da reserva.

Consulte a seção **Webhooks de Alteração de Status** no [Manual do Fluxo Principal](./manual_cartao_beneficio_emissao.md) para ver o exemplo de payload com status `pending_onboarding`.

---

# Manual Cartão Consignado - Criação

URL: /documentation/manual_cartao_beneficio/manual_cartao_beneficio_emissao

:::info Navegação
- [Visão Geral](/documentation/manual_cartao_beneficio/visao_geral) (anterior)
- [Acompanhamento](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_acompanhamento) (próximo)
:::

:::caution API em desenvolvimento
A API ainda está em fase de desenvolvimento, sendo assim, este manual esta sujeito a alterações.
:::

---

:::info Consultas da fonte de consignação
Os dados do titular e a margem disponível vêm de consultas da própria [fonte de consignação](/documentation/manual_cartao_beneficio/visao_geral#fontes-de-consignacao), documentadas fora deste manual:

- **INSS** (`social_security`) — [lista de benefícios](/documentation/guides/INSS/inquiries/lista-de-beneficios) e [dados do benefício](/documentation/guides/INSS/inquiries/dados-do-beneficio)
- **Consignado Público** (`public_payroll`) — [consulta de margem](/documentation/guides/publico/consulta-de-margem)
:::

## 1. Consulta de elegibilidade do beneficiário

A consulta de elegibilidade permite verificar se um CPF está elegível para o cartão. Esta operação é síncrona e retorna imediatamente o resultado da verificação.

Em posse dos dados de **CPF** e **data de nascimento**, é possível consultar a elegibilidade do titular. Atualmente, a única validação realizada é a faixa etária, que é definida por tipo de cartão — ou seja, varia conforme a fonte de consignação e o produto informados.

### Request

**GET**
/payroll_card_reservation/{collateral_type}/eligibility

Testar no Playground

**Params**

| Campo             | Tipo   | Descrição                    | Obrigatório | Formatação |
|-------------------|--------|------------------------------|-------------|------------|
| document_number | string | Número de CPF do titular | Sim         | 11 dígitos numéricos |
| birth_date     | date   | Data de nascimento           | Sim         | YYYY-MM-DD |
| product_type   | string | Produto consultado           | Sim         | Enum: `payroll_card`, `benefit_card` |

:::info Consignado Público
Na fonte `public_payroll`, a faixa etária depende do órgão consultado, então os parâmetros `consignment_entity` e `agency` também são obrigatórios. Ver [Consignado Público](/documentation/guides/publico/visao_geral).
:::

### Response

STATUS
**200** (OK)

**Exemplos de Response**

**Elegível:**
```json
{
    "status": "eligible"
}
```

**Não elegível - Idade fora do intervalo:**
```json
{
    "status": "not_eligible",
    "error_description": "Age 72 is not within the eligible range (18-71 years)"
}
```

O intervalo citado na mensagem é o do tipo de cartão consultado, não um valor fixo da API.

**Response Body Details**

| Campo     | Tipo    | Descrição                                    |
|-----------|---------|----------------------------------------------|
| status | string | Status da elegibilidade (eligible/not_eligible) |
| error_description | string | Descrição do erro quando não elegível (opcional) |

---

## 2. Simulação de saque e limite do cartão

A simulação permite calcular o valor de saque disponível e o limite do cartão consignado baseado nos parâmetros financeiros informados. Esta operação é útil para apresentar ao beneficiário as condições antes da contratação.

### Request
**POST**
/payroll_card_reservation/{collateral_type}/simulation

Testar no Playground

**Request Body**

```json
{
  "product_type": "benefit_card",
  "financial": {
    "salary_amount": 5000.00,
    "number_of_installments": 96,
    "monthly_interest_rate": 0.0246
  },
  "withdrawal": {
    "disbursement_date": "2026-01-02",
    "limit_days_to_disburse": 1,
    "withdrawal_ratio": 0.7
  }
}
```

**Request Body Details**

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| product_type | string | Produto simulado | Enum: `payroll_card`, `benefit_card` | Sim |
| financial | object | Dados financeiros da operação | - | Sim |
| withdrawal | object | Dados do saque | - | Sim |
| collateral | object | Dados da consignação, quando a fonte precisa deles para precificar | - | Não |

#### Payload financial

Informe **exatamente um** entre `salary_amount` e `available_margin`. Qual dos dois o seu tipo de cartão aceita depende da fonte de consignação — ver [Colateral por fonte de consignação](#colateral-por-fonte-de-consignacao).

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| salary_amount | number | Valor do salário ou benefício do titular | Mínimo: 1 | Sim, se `available_margin` não for informado |
| available_margin | number | Margem consignável mensal disponível, já informada pelo solicitante | Mínimo: 1 | Sim, se `salary_amount` não for informado |
| number_of_installments | number  | Número de parcelas da CCB de saque | Mínimo: 1 | Sim |
| monthly_interest_rate | number  | Taxa de juros mensal da CCB de saque | Mínimo: 0.001 | Sim |

#### Payload withdrawal

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| disbursement_date | date  | Data do desembolso da CCB de saque | YYYY-MM-DD | Sim |
| limit_days_to_disburse | number  | Número de dias limite para desembolso da CCB de saque | Mínimo: 1 | Sim |
| withdrawal_ratio | number  | Parte do limite que será usado para o saque | Mínimo: 0.5 | Não |

:::caution Limites máximos são definidos por tipo de cartão
O número de parcelas, a taxa de juros, o `withdrawal_ratio` e o `limit_days_to_disburse` têm **tetos por tipo de cartão**, não limites fixos de schema. Um valor acima do teto é recusado com **400 `PCR000001`**, informando o valor recebido e o máximo permitido. Consulte a sua configuração contratada.
:::

### Response

STATUS
**201** (Created)

**Response Body**

```json
{
   "total_limit_amount": 8000,
   "reservation_amount": 250,
   "withdrawal": {
      "withdrawal_amount": 5600,
      "withdrawal_data": {
         "prefixed_interest_rate": {
            "interest_base": "calendar_days",
            "annual_rate": 0.3386043084,
            "monthly_rate": 0.0246,
            "daily_rate": 0.0008104046
         },
         "disbursement_options": [
            {
               "disbursement_date": "2026-01-02",
               "cet": 0.0261,
               "annual_cet": 0.3618,
               "total_iof": 193.55,
               "disbursed_issue_amount": 5600,
               "issue_amount": 5793.55,
               "installments": [
                  {
                     "total_amount": 160.51,
                     "due_date": "2026-02-10",
                     "business_due_date": "2026-02-11",
                     "installment_number": 1
                  },
                  {
                     "total_amount": 160.51,
                     "due_date": "2026-03-10",
                     "business_due_date": "2026-03-11",
                     "installment_number": 2
                  },
                  {
                     "total_amount": 160.51,
                     "due_date": "2026-04-10",
                     "business_due_date": "2026-04-13",
                     "installment_number": 3
                  },
                  ...
               ]
            }
         ]
      }
   },
   "payroll_card": {
      "card_limit": 2400
   }
}
```

**Response Body Details**

| Campo | Tipo | Descrição |
|---|---|---| 
| total_limit_amount | number | Valor total do limite disponível considerando saque e cartão | 
| reservation_amount | number | Valor da reserva do cartão consignado | 
| withdrawal | object | Dados do saque |
| withdrawal.withdrawal_amount | number | Valor de desembolso calculado para CCB de saque | 
| withdrawal.withdrawal_data | object | Dados detalhados do saque | 
| payroll_card | object | Dados do cartão consignado | 
| payroll_card.card_limit | number | Limite total calculado para o cartão | 

#### Payload withdrawal.withdrawal_data

| Campo | Tipo | Descrição | 
|---|---|---| 
| prefixed_interest_rate | object | Taxa de juros prefixada |
| disbursement_options | array | Opções de desembolso disponíveis | 

#### Payload prefixed_interest_rate

| Campo | Tipo | Descrição | 
|---|---|---| 
| daily_rate | number | Taxa diária | 
| interest_base | string | Base de cálculo dos juros | 
| monthly_rate | number | Taxa mensal | 
| annual_rate | number | Taxa anual | 

#### Payload disbursement_options

| Campo | Tipo | Descrição | 
|---|---|---| 
| disbursement_date | string | Data do desembolso | 
| cet | number | Custo Efetivo Total mensal | 
| annual_cet | number | Custo Efetivo Total anual | 
| total_iof | number | Valor total de IOF |  
| disbursed_issue_amount | number | Valor de desembolso |  
| issue_amount | number | Valor de emissão |  
| installments | array | Lista de parcelas | 

#### Payload installments

| Campo | Tipo | Descrição | 
|---|---|---| 
| total_amount | number | Valor total da parcela | 
| due_date | string | Data de vencimento | 
| installment_number | number | Número da parcela | 

---

## 3. Criação da operação de saque e geração do termo

A criação da operação de saque inicia o processo de contratação do cartão consignado. Esta operação cria a reserva do cartão, gera os documentos necessários e retorna as chaves para acompanhamento do processo.

**POST**
/payroll_card_reservation/{collateral_type}

Testar no Playground

### Request

**Request Body**

```json
{
  "request_control_key": "150e8400-e29b-41d4-a716-446655440000",
  "purchaser_document_number": "55566677000177",
  "product_type": "benefit_card",
  "card_holder": {
    "name": "Carlos Eduardo Lima",
    "email": "carlos.lima@email.com",
    "phone": {
      "number": "654321098",
      "area_code": "31",
      "country_code": "055"
    },
    "gender": "male",
    "address": {
      "city": "Belo Horizonte",
      "state": "MG",
      "number": "789",
      "street": "Rua das Palmeiras",
      "complement": "Casa 3",
      "postal_code": "30112000",
      "neighborhood": "Savassi"
    },
    "birth_date": "1990-09-18",
    "mother_name": "Fernanda Lima",
    "nationality": "Brasileiro",
    "document_number": "55566677788",
    "document_identification": {
      "document_identification_date": "2012-05-20",
      "document_identification_type": "rg",
      "document_identification_number": "555666777"
    }
  },
  "related_parties": [
    {
      "name": "Pedro Costa",
      "email": "pedro.costa@email.com",
      "phone": {
        "number": "765432109",
        "area_code": "21",
        "country_code": "055"
      },
      "address": {
        "city": "Rio de Janeiro",
        "state": "RJ",
        "number": "789",
        "street": "Rua Ipanema",
        "complement": "Apto 12",
        "postal_code": "22080001",
        "neighborhood": "Ipanema"
      },
      "role_type": "issuer_legal_representative",
      "person_type": "natural",
      "is_pep": false,
      "individual_document_number": "11122233344",
      "birth_date": "1980-12-05",
      "mother_name": "Lucia Costa",
      "document_identification": {
        "document_identification_date": "2017-01-14",
        "document_identification_type": "rg",
        "document_identification_number": "222333444"
      }
    }
  ],
  "withdrawal": {
    "disbursement_date": "2026-01-02",
    "limit_days_to_disburse": 1,
    "withdrawal_ratio": 0.7,
    "contract_number": "PCR12345678",
    "disbursement_bank_account": {
      "name": "Carlos Eduardo Lima",
      "bank_code": "104",
      "account_digit": "3",
      "branch_number": "5678",
      "account_number": "987654321",
      "document_number": "55566677788",
      "transfer_method": "pix",
      "account_type": "checking_account"
    }
  },
  "financial": {
    "salary_amount": 5000.00,
    "number_of_installments": 96,
    "monthly_interest_rate": 0.0246,
    "emission_installments": 1
  },
  "credit_agent": {
    "document_number": "44455566677",
    "name": "Agente de Crédito Lima"
  },
  "collateral": {
    "state": "MG",
    "benefit_number": "5556667777",
    "subcorban_document_number": "12123456000101",
    "assistance_type": "pension_by_death_rural_worker"
  }
}
```

**Request Body Details**

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| request_control_key | string | Chave de identificação da requisição | UUID v4 | Sim |
| purchaser_document_number | string | CNPJ do comprador | 14 dígitos numéricos | Sim |
| product_type | string | Produto contratado | Enum: `payroll_card`, `benefit_card` | Sim |
| card_holder | object | Dados do portador do cartão | - | Sim |
| withdrawal | object | Dados do saque | - | Sim |
| financial | object | Dados financeiros da operação | - | Sim |
| credit_agent | object | Dados do agente de crédito | - | Sim |
| related_parties | array | Lista de partes relacionadas | - | Não |
| collateral | object | Dados da consignação, no formato da fonte informada na rota — ver [Colateral por fonte de consignação](#colateral-por-fonte-de-consignacao) | - | Sim |

#### Payload card_holder

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| name | string | Nome completo do portador | Mínimo: 1 caractere válido | Sim |
| email | string | Email do portador | Formato de email válido | Sim |
| phone | object | Dados do telefone | - | Sim |
| gender | string | Gênero | Enum: "male", "female" | Sim |
| address | object | Endereço do portador e de entrega do cartão. | - | Sim |
| birth_date | date | Data de nascimento | YYYY-MM-DD | Sim |
| mother_name | string | Nome da mãe | Mínimo: 1 caractere válido | Sim |
| nationality | string | Nacionalidade | Mínimo: 1 caractere | Sim |
| document_number | string | CPF do portador | 11 dígitos numéricos | Sim |
| document_identification | object | Dados do documento de identificação | - | Sim |

#### Payload related_parties

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| name | string | Nome da parte relacionada | Mínimo: 1 caractere válido | Sim |
| email | string | Email da parte relacionada | Formato de email válido | Sim |
| phone | object | Dados do telefone | - | Sim |
| address | object | Endereço da parte relacionada | - | Sim |
| role_type | string | Tipo de papel | Enum: "issuer_legal_representative", "issuer_attorney" | Sim |
| person_type | string | Tipo de pessoa | Enum: "natural" | Sim |
| is_pep | boolean | Se é pessoa politicamente exposta | true/false | Sim |
| individual_document_number | string | CPF da parte relacionada | 11 dígitos numéricos | Sim |
| birth_date | date | Data de nascimento | YYYY-MM-DD | Sim |
| mother_name | string | Nome da mãe | Mínimo: 1 caractere válido | Sim |
| document_identification | object | Dados do documento de identificação | - | Sim |

#### Payload phone

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| number | string | Número do telefone | Apenas números | Sim |
| area_code | string | Código de área | Apenas números | Sim |
| country_code | string | Código do país | Apenas números | Sim |

#### Payload address

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| city | string | Cidade | Mínimo: 1 caractere | Sim |
| state | string | Estado | 2 caracteres | Sim |
| number | string | Número | Mínimo: 1 caractere | Sim |
| street | string | Rua | Mínimo: 1 caractere | Sim |
| complement | string | Complemento | Mínimo: 1 caractere | Não |
| postal_code | string | CEP | 8 dígitos numéricos | Sim |
| neighborhood | string | Bairro | Mínimo: 1 caractere | Sim |

#### Payload document_identification

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| document_identification_date | date | Data de emissão do documento | YYYY-MM-DD | Sim |
| document_identification_type | string | Tipo do documento | Enum: "rg", "passport", "other" | Sim |
| document_identification_number | string | Número do documento | Mínimo: 1 caractere | Sim |

#### Payload withdrawal

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| disbursement_date | date | Data do desembolso | YYYY-MM-DD | Sim |
| limit_days_to_disburse | number | Número de dias limite para desembolso | Mínimo: 1, Máximo: 10 | Sim |
| contract_number | string | Número do contrato | 3 letras maiúsculas + 8 números | Sim |
| disbursement_bank_account | object | Conta bancária para desembolso | - | Sim |

#### Payload disbursement_bank_account

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| name | string | Nome do titular da conta | Mínimo: 1 caractere válido | Sim |
| bank_code | string | Código do banco | 3 dígitos numéricos | Sim |
| account_digit | string | Dígito da conta | 1 dígito numérico | Sim |
| branch_number | string | Número da agência | Apenas números | Sim |
| account_number | string | Número da conta | Apenas números | Sim |
| document_number | string | CPF do titular | 11 dígitos numéricos | Sim |
| transfer_method | string | Método de transferência | Enum: "pix", "ted" | Sim |
| account_type | string | Tipo de conta | Enum: `checking_account`, `deposit_account`, `guaranteed_account`, `investment_account`, `payment_account`, `saving_account`, `salary_account` | Sim |

#### Payload financial

Informe **exatamente um** entre `salary_amount` e `available_margin`. Qual dos dois o seu tipo de cartão aceita depende da fonte de consignação; enviar o que não é aceito é recusado com **400 `PCR000005`**.

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| salary_amount | number | Valor do salário ou benefício do titular (valor total) | Mínimo: 1 | Sim, se `available_margin` não for informado |
| available_margin | number | Margem consignável mensal disponível, já apurada pelo solicitante | Mínimo: 1 | Sim, se `salary_amount` não for informado |
| number_of_installments | number | Número de parcelas das CCBs (saque e rotativo) | Mínimo: 1 | Sim |
| monthly_interest_rate | number | Taxa de juros mensal das CCBs (saque e rotativo) | Mínimo: 0.001 | Sim |
| emission_installments | number | Número de Parcelas da taxa de emissão do cartão (Conforme coletado com o beneficiário) | Mínimo: 1, Máximo: 3 | Sim |

:::caution Limites máximos são definidos por tipo de cartão
O número de parcelas, a taxa de juros, o `withdrawal_ratio` e o `limit_days_to_disburse` têm **tetos por tipo de cartão**, não limites fixos de schema. Um valor acima do teto é recusado com **400 `PCR000001`**.
:::

#### Payload credit_agent

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| document_number | string | CPF do agente de crédito | 11 ou 14 dígitos numéricos | Sim |
| name | string | Nome do agente de crédito | Mínimo: 1 caractere válido | Sim |

#### Payload collateral {#colateral-por-fonte-de-consignacao}

O formato do `collateral` é definido pela fonte de consignação informada na rota. Cada fonte tem o seu próprio conjunto de campos, todos obrigatórios.

**INSS**

Consignação de **aposentados e pensionistas do INSS**. Rota: `/payroll_card_reservation/social_security`. Esta fonte aceita apenas `salary_amount` como entrada financeira.

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| state | string | Estado | 2 caracteres | Sim |
| benefit_number | string | Número do benefício | Mínimo: 1 caractere | Sim |
| subcorban_document_number | string | Número do documento do correspondente bancário (ou filial de correspondente bancário) responsável pela operação | 14 dígitos numéricos | Sim |
| assistance_type | string | Tipo do benefício | Enum: [Tabela de benefícios](/documentation/guides/INSS/reference/enumeradores#benefit_type_enumerator) | Sim |

```json
{
  "state": "MG",
  "benefit_number": "5556667777",
  "subcorban_document_number": "12123456000101",
  "assistance_type": "pension_by_death_rural_worker"
}
```

Regras de elegibilidade e averbação do benefício: [INSS](/documentation/guides/INSS/intro).

**Consignado Público**

Consignação de **servidores públicos estaduais e municipais**. Rota: `/payroll_card_reservation/public_payroll`. Esta fonte aceita apenas `available_margin` como entrada financeira.

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| entity_level | string | Esfera do ente consignante | Enum: `municipal`, `state` | Sim |
| consignment_entity | string | Enumerador do ente consignante | Enum: [Entes consignantes](/documentation/guides/publico/entes#entes-disponiveis) | Sim |
| agency | string | Enumerador do órgão do titular | Mínimo: 1 caractere | Sim |
| registration_number | string | Matrícula do titular no órgão, exatamente como o órgão a emite | Mínimo: 1 caractere | Sim |

```json
{
  "entity_level": "state",
  "consignment_entity": "sp",
  "agency": "spprev",
  "registration_number": "1234567890123"
}
```

Regras de margem e averbação: [Consignado Público](/documentation/guides/publico/visao_geral).

### Response

STATUS
**201** (Created)

**Response Body**

```json
{
   "request_control_key": "150e8400-e29b-41d4-a716-446655440000",
   "payroll_card_type": "social_security_benefit_card",
   "payroll_card_reservation_key": "72d63aea-15b6-402c-a18b-d12cd4619c9d",
   "card_holder_document_number": "55566677788",
   "identifier_number": "5556667777",
   "total_limit_amount": 8000,
   "reservation_amount": 250,
   "withdrawal": {
      "withdrawal_key": "56cfe7b7-ed6e-4212-8744-c9fcff309ec0",
      "withdrawal_amount": 5600,
      "credit_operation_key": null,
      "withdrawal_status": "pending_signature",
      "contract_number": "PCR12345678",
      "withdrawal_data": {
         "prefixed_interest_rate": {
            "interest_base": "calendar_days",
            "annual_rate": 0.3386043084,
            "monthly_rate": 0.0246,
            "daily_rate": 0.0008104046
         },
         "disbursement_options": [
            {
               "disbursement_date": "2026-01-02",
               "cet": 0.0261,
               "annual_cet": 0.3618,
               "total_iof": 193.55,
               "disbursed_issue_amount": 5600,
               "issue_amount":  5793.55,
               "installments": [
                  {
                     "total_amount": 160.51,
                     "due_date": "2026-02-10",
                     "business_due_date": "2026-02-11",
                     "installment_number": 1
                  },
                  {
                     "total_amount": 160.51,
                     "due_date": "2026-03-10",
                     "business_due_date": "2026-03-11",
                     "installment_number": 2
                  },
                  {
                     "total_amount": 160.51,
                     "due_date": "2026-04-10",
                     "business_due_date": "2026-04-13",
                     "installment_number": 3
                  },
                  ...
               ]
            }
         ]
      },
      "wallet_entry_key": null
   },
   "payroll_card": {
      "payroll_card_key": "572650c7-67f6-4f73-8444-b9da72000057",
      "payroll_card_status": "pending_issuance",
      "card_key": null,
      "payment_instrument_key": null,
      "card_issuance_entry_key": null,
      "card_issuance_entry_amount": 17.28,
      "card_limit": 2400
   },
   "attached_documents": [
      {
         "document_key": "32f5e5e2-a15a-40af-9ddc-cddaba1966cf",
         "document_type": "withdrawal_operation_term",
         "document_certifier": "qi_sign",
         "document_status": "pending_generation",
         "document_url": null,
         "document_batch_key": "f4f2b64c-5608-44bb-a2df-bf62cf26cc76"
      },
      {
         "document_key": "7767e30e-417e-4dd7-b061-bba722451d10",
         "document_type": "payroll_card_term",
         "document_certifier": "qi_sign",
         "document_status": "pending_generation",
         "document_url": null,
         "document_batch_key": "f4f2b64c-5608-44bb-a2df-bf62cf26cc76"
      },
      {
         "document_key": "6c839b10-9558-4e6e-9f7d-d1e494cf6156",
         "document_type": "payroll_card_consent_term",
         "document_certifier": "qi_sign",
         "document_status": "pending_generation",
         "document_url": null,
         "document_batch_key": "f4f2b64c-5608-44bb-a2df-bf62cf26cc76"
      }
   ],
   "payroll_card_reservation_status": "pending_document_generation",
   "wallet_key": null,
   "reservation_contract_number": "PCR0000000822"
}
```

**Response Body Details**

| Campo | Tipo | Descrição |
|---|---|---| 
| request_control_key | string | Chave de identificação da requisição | 
| payroll_card_reservation_key | string | Chave da reserva do cartão consignado | 
| payroll_card_reservation_status | string | Status da reserva do cartão consignado | 
| card_holder_document_number | string | CPF do portador do cartão | 
| identifier_number | string | Número identificador da operação | 
| reservation_amount | number | Valor da reserva do cartão consignado |
| reservation_contract_number | string | Número do contrato de averbação na Dataprev | 
| withdrawal | object | Dados do saque | 
| payroll_card | object | Dados do cartão consignado | 
| attached_documents | array | Lista de documentos anexados | 
| payroll_card_type | string | Tipo do cartão — a fonte de consignação e o produto combinados, por exemplo `social_security_benefit_card` ou `public_payroll_payroll_card` | 
| wallet_key | string | Chave única da wallet criada (UUID4) | 

#### Payload withdrawal

| Campo | Tipo | Descrição | 
|---|---|---| 
| withdrawal_key | string | Chave única do saque | 
| contract_number | string | Número do contrato da CCB de saque | 
| withdrawal_amount | number | Valor de desembolso calculado para CCB de saque | 
| disbursement_date | date | Data de desembolso da operação | 
| withdrawal_status | string | Status do saque | 
| withdrawal_data | object | Dados detalhados do saque |

#### Payload withdrawal_data

| Campo | Tipo | Descrição |
|---|---|---| 
| prefixed_interest_rate | object | Taxa de juros prefixada | 
| disbursement_options | array | Opções de desembolso disponíveis | 

#### Payload prefixed_interest_rate

| Campo | Tipo | Descrição | 
|---|---|---| 
| daily_rate | number | Taxa diária | 
| interest_base | string | Base de cálculo dos juros | 
| monthly_rate | number | Taxa mensal | 
| annual_rate | number | Taxa anual | 

#### Payload disbursement_options

| Campo | Tipo | Descrição | 
|---|---|---| 
| disbursement_date | string | Data do desembolso | 
| cet | number | Custo Efetivo Total mensal | 
| annual_cet | number | Custo Efetivo Total anual | 
| total_iof | number | Valor total de IOF |  
| disbursed_issue_amount | number | Valor de desembolso |  
| issue_amount | number | Valor de emissão |  
| installments | array | Lista de parcelas | 

#### Payload installments

| Campo | Tipo | Descrição | 
|---|---|---| 
| total_amount | number | Valor total da parcela | 
| due_date | string | Data de vencimento | 
| installment_number | number | Número da parcela | 

#### Payload payroll_card

| Campo | Tipo | Descrição | 
|---|---|---| 
| payroll_card_key | string | Chave única do cartão consignado | 
| payroll_card_status | string | Status do cartão consignado | 
| card_limit | number | Limite total calculado para o cartão | 
| card_issuance_entry_amount | number | Valor da Taxa de emissão do cartão | 

#### Payload attached_documents

| Campo | Tipo | Descrição | 
|---|---|---| 
| document_key | string | Chave única do documento | 
| document_batch_key | string | Chave do lote de documentos | 
| document_type | string | Tipo do documento | 
| document_certifier | string | Certificadora do documento | 
| document_status | string | Status do documento | 
| document_url | string | URL do documento | 
| signature_url | string | URL da assinatura | 

---

---

## 4. Envio de documentos adicionais

Após a aprovação do onboarding, a reserva é atualizada para o status `pending_additional_documents_submission`. Para prosseguir com a reserva de margem e o desembolso da operação, é obrigatório o envio dos documentos adicionais (Para o produto de Cartão Consignado/Benefício de INSS, o **vídeo de confirmação da contratação**).

O processamento do upload é assíncrono. O upload bem sucedido aciona a transição automática da reserva para `pending_additional_documents_validation`, disparando os webhooks de [alteração de status](./manual_cartao_beneficio_webhook.md) e de [atualização de documentos](./manual_cartao_beneficio_documentos.md), e acionando a validação dos documentos.

:::info Reprovação e Re-envio de Documentos Adicionais
Caso os documentos adicionais sejam rejeitados na validação do sistema, a reserva retornará para o status `pending_additional_documents_submission` e será possível realizar o re-envio dos documentos adicionais por este mesmo endpoint. Não é possível realizar o re-envio dos documentos adicionais antes da aprovação/rejeição pela análise do sistema, e existe um limite de 5 análises por reserva e tipo de documento.
:::

:::warning Atenção: Gatilho de Desembolso
O envio e a subsequente aprovação pelo sistema dos documentos adicionais são tratados como autorização para o desembolso da operação de crédito. Após a validação bem sucedida dos dos arquivos, a operação seguirá automaticamente para a averbação e para a criação da operação de crédito e será efetuado o desembolso na conta do beneficiário, **sem etapas adicionais de aprovação**.
:::

### Request

**POST**
/payroll_card_reservation/{collateral_type}/[PAYROLL-CARD-RESERVATION-KEY]/additional_documents

Testar no Playground

**Params**

| Campo | Tipo | Descrição | Obrigatório |
|---|---|---|---|
| payroll_card_reservation_key | string | Chave única da reserva (UUID) | Sim |

**Request Body**

```json
{
  "documents": [
      {
        "document_type": "payroll_card_confirmation_video", 
        "document_url": "https://download.samplelib.com/mp4/sample-5s.mp4"
      }
  ]
}
```

**Request Body Details**

| Campo | Tipo | Descrição | Obrigatório |
|---|---|---|---|
| documents | array | Lista de documentos a serem anexados | Sim |

#### Payload documents

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| document_type | string | Tipo do documento | Enum: "payroll_card_confirmation_video" | Sim |
| document_url | string | URL pública para download do arquivo de vídeo | URL válida | Sim |

:::info **URL do Vídeo**
Garanta que a URL enviada é acessível por usuários externos, para conseguirmos efetuar o upload do arquivo para o banco de dados interno da QI.

- Formatos de arquivo suportados: .mp4
- Tamanho máximo do arquivo: 256MB
:::

### Response

STATUS
**200** (OK)

A requisição foi recebida com sucesso e o documento será processado assincronamente.

```json
{
   "attached_documents": [
      {
         "document_key": "2fc216c6-5d1c-4713-b70b-6e1f75f8bb17",
         "document_type": "payroll_card_confirmation_video",
         "document_certifier": "electronic_client_side",
         "document_status": "pending_generation",
         "document_url": ""
      }
   ],
}
```

---

## 5. Reapresentação de Pagamento do Saque

Caso o pagamento não seja processado devido a dados incorretos, é possível pode ajustar as informações da conta bancária para reapresentação através do seguinte endpoint:

**PATCH**
/payroll_card_reservation/{collateral_type}/[PAYROLL-CARD-RESERVATION-KEY]/disbursement_account

Testar no Playground

### Request

**Request Body**

```json
{
   "disbursement_bank_account": {
      "name": "Carlos Eduardo Lima",
      "bank_code": "001",
      "account_digit": "3",
      "branch_number": "5678",
      "account_number": "987654321",
      "document_number": "55566677788",
      "transfer_method": "pix",
      "account_type": "checking_account"
   }
}
```

**Request Body Details**

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| disbursement_bank_account | object | Conta bancária para desembolso | - | Sim |

#### Payload disbursement_bank_account

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| name | string | Nome do titular da conta | Mínimo: 1 caractere válido | Sim |
| bank_code | string | Código do banco | 3 dígitos numéricos | Sim |
| account_digit | string | Dígito da conta | 1 dígito numérico | Sim |
| branch_number | string | Número da agência | Apenas números | Sim |
| account_number | string | Número da conta | Apenas números | Sim |
| document_number | string | CPF do titular | 11 dígitos numéricos | Sim |
| transfer_method | string | Método de transferência | Enum: "pix", "ted" | Sim |
| account_type | string | Tipo de conta | Enum: `checking_account`, `deposit_account`, `guaranteed_account`, `investment_account`, `payment_account`, `saving_account`, `salary_account` | Sim |

### Response

STATUS
**200** (OK)

---

## 6. Anexos 

### Referências
:::info **Fura Fila**
A funcionalidade de [Fura Fila](/docs/guides/INSS/reservations/priority-request.md) (Averbação Síncrona) está disponível apra o Cartão INSS, utilizando a payroll_card_reservation_key como a \{deby_key\} da requisição.:
:::

### Ambiente de Homologação (Mocks)

Para facilitar os testes de integração em ambiente de **Sandbox**, o sistema simula diferentes comportamentos baseados no **primeiro dígito do CPF do titular** enviado no payload de criação.

Os cenários abaixo são **específicos da fonte de consignação**, porque simulam as respostas do órgão que averba a operação.

**INSS**

Os cenários simulam as respostas da Dataprev. O detalhamento por etapa — consulta de saldo, averbação e anuência — está em [Mocks (Sandbox) do INSS](/documentation/guides/INSS/mocks-sandbox).

| 1º Dígito do CPF | Cenário | Comportamento Interno | Resultado Final (Cliente) |
| :---: | --- | --- | --- |
| **1** | **Fluxo Ideal (Completo)** | **Sucesso** na Assinatura <br/> **Sucesso** no Onboarding <br/> **Sucesso** na Averbação (Dataprev) | **Cartão emitido** <br/> (Status: `card_issued`) |
| **2** | **Erro na Consulta Dataprev** | **Sucesso** na Assinatura <br/> **Sucesso** no Onboarding <br/> **Falha** na Consulta de Benefício | **Reserva cancelada** <br/> (Status: `canceled`) <br/> + **Envio de Webhook de status** <br/> (Status: `canceled`) |
| **3** | **Erro na Averbação Dataprev** | **Sucesso** na Assinatura <br/> **Sucesso** no Onboarding <br/> **Falha** na Averbação/Reserva de Margem | **Reserva cancelada** <br/> (Status: `canceled`) <br/> + **Envio de Webhook de status** <br/> (Status: `canceled`) |
| **4** | **Erro de Endereço** | **Sucesso** na Assinatura <br/> **Sucesso** no Onboarding (Endereço Divergente) <br/> **Sucesso** na Averbação (Dataprev) | **Cartão emitido** <br/> (Status: `card_issued`) <br/> + **Envio de Webhook de atualização de endereço** |
| **5** | **Onboarding Rejeitado** | **Sucesso** na Assinatura <br/> **Rejeição** no Onboarding/KYC | **Reserva cancelada** <br/> (Status: `canceled`) <br/> + **Envio de Webhook de status** <br/> (Status: `canceled`) |
| **6** | **Inelegível (Idade > 65)** | **Sucesso** na Assinatura <br/> **Sucesso** no Onboarding (Retorna idade superior a 65 anos) | **Reserva cancelada** <br/> (Status: `canceled`) <br/> + **Envio de Webhook de status** <br/> (Status: `canceled`) |
| **7** | **Inelegível (Idade < 18)** | **Sucesso** na Assinatura <br/> **Sucesso** no Onboarding (Retorna idade inferior a 18 anos) | **Reserva cancelada** <br/> (Status: `canceled`) <br/> + **Envio de Webhook de status** <br/> (Status: `canceled`) |
| **8** | **Teimosinha (Retentativa)** | **Sucesso** na Assinatura <br/> **Sucesso** no Onboarding <br/> **Falha Temporária** na Averbação (Dataprev) | **Aguardando liberação** <br/> (Status: `pending_reservation`) <br/> + **Envio de Webhook de Collateral** |

:::tip Dica
Para testar o **Fluxo ideal**, certifique-se de usar um CPF que comece com o dígito `1` (ex: `123.456.789-00`) e que seja válido (cálculo de dígitos verificadores correto).
:::

:::warning Aviso
Os mocks de sucesso estão configurados para simular benefícios de até R$10.000,00. Caso valores de benefício acima deste sejam usados, o sistema irá retornar erro de margem excedida na averbação, cancelando a reserva.
:::

**Consignado Público**

:::caution Em construção
Os cenários de sandbox do Consignado Público serão publicados junto com o produto. Ver [Consignado Público](/documentation/guides/publico/visao_geral).
:::

---

---

# Gestão de Endereço

URL: /documentation/manual_cartao_beneficio/manual_cartao_beneficio_endereco

:::info Navegação
- [Documentos e Assinatura](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_documentos) (anterior)
:::

Durante o processo de Onboarding e KYC, o endereço do beneficiário é validado tanto por nossos processos de análise quanto pelo próprio beneficiário. Além disso, problemas de endereço também podem ser identificados durante a tentativa de entrega do cartão. Em ambos os casos, o cliente será notificado via webhook para realizar a confirmação ou a correção dos dados junto ao beneficiário.

## 1. Webhook de problema no endereço

Este webhook é disparado quando é identificado um problema relacionado ao endereço do beneficiário. Existem dois cenários possíveis, identificados pelo campo `rejected_reason`:

- **`address_mismatch`**: Inconsistência detectada durante o processo de KYC entre o endereço enviado e o endereço em nossa base.
- **`delivery_failure`**: Falha na tentativa de entrega do cartão físico no endereço cadastrado.

:::caution Ação Necessária
Ao receber este webhook, o cliente deve contatar o beneficiário e solicitar a correção dos dados através do endpoint de **Atualização de Endereço**. 
Estes webhooks também são informados ao beneficiário final através do aplicativo. No entanto, o cliente deve acompanhar e tratar esses casos independentemente, garantindo que a correção do endereço seja realizada pelo cliente ou pelo beneficiário.
:::

:::danger Prazo para Falha de Entrega (`delivery_failure`)
Após o recebimento de um webhook de falha na entrega, o cliente tem um prazo de **10 dias** para atualizar o endereço do beneficiário. Caso o prazo não seja cumprido, o cartão físico será cancelado e será necessária uma nova emissão do cartão através do endpoint de [Reemissão de Cartão](#3-reemissão-de-cartão).
:::

WEBHOOK TYPE
laas.payroll_card_reservation.address

### 1.1 Exemplo: Inconsistência de endereço (KYC)

**Webhook Body — address_mismatch**

```json
{
    "key": "3571e292-3a83-4011-904d-20ee963022ef",
    "webhook_type": "laas.payroll_card_reservation.address",
    "status": "pending_card_issuance",
    "event_datetime": "2025-01-15T16:45:00Z",
    "data": {
        "address": {
          "city": "Belo Horizonte",
          "state": "MG",
          "postal_code": "30112000",
          "street": "Rua Inexistente",
          "number": "000",
          "neighborhood": "Savassi"
        }, 
        "rejected_reason": "address_mismatch",
        "rejection_details": {
            "cancel_reason_description": "Endereço não encontrado na base de validação",
            "cancel_reason_translation": "Endereço não encontrado na base de validação"
        }
    }
}
```

### 1.2 Exemplo: Falha na entrega do cartão

**Webhook Body — delivery_failure**

```json
{
    "key": "3571e292-3a83-4011-904d-20ee963022ef",
    "webhook_type": "laas.payroll_card_reservation.address",
    "status": "card_issued",
    "event_datetime": "2025-01-15T16:45:00Z",
    "data": {
        "address": {
          "city": "Belo Horizonte",
          "state": "MG",
          "postal_code": "30112000",
          "street": "Rua das Palmeiras",
          "number": "789",
          "neighborhood": "Savassi"
        }, 
        "rejected_reason": "delivery_failure",
        "rejection_details": {
            "cancel_reason_description": "Delivery Failure",
            "cancel_reason_translation": "Falha na entrega"
        }
    }
}
```

---

## 2. Atualização de Endereço

Endpoint utilizado para corrigir o endereço do beneficiário após o recebimento de um webhook de erro de validação.

:::info 
Caso o beneficiário confirme o endereço, não é necessário enviar uma requisição de atualização de endereço, e o endereço já cadastrado será utilizado para o envio do cartão.
:::

### Request

**PATCH**
/payroll_card_reservation/{collateral_type}/{payroll_card_reservation_key}/address

Testar no Playground

**Request Body**

```json
{
    "address": {
        "city": "Belo Horizonte",
        "state": "MG",
        "number": "789",
        "street": "Rua das Palmeiras",
        "complement": "Casa 3",
        "postal_code": "30112000",
        "neighborhood": "Savassi"
    }
}
```

**Params Details**

| Campo | Tipo | Descrição | Obrigatório |
|---|---|---|---|
| city | string | Cidade | Sim |
| state | string | Estado (UF) | Sim |
| number | string | Número | Sim |
| street | string | Logradouro | Sim |
| complement | string | Complemento | Não |
| postal_code | string | CEP (apenas números) | Sim |
| neighborhood | string | Bairro | Sim |

### Response

STATUS
**200** (OK)

A operação será automaticamente reprocessada no fluxo de KYC, potencialmente resultando em um novo webhook de erro caso seja detectada alguma inconsistência novamente.

---

## 3. Reemissão de Cartão

Endpoint utilizado para **cancelar o cartão físico atual e emitir um novo cartão** para uma reserva já finalizada (`card_issued`). Deve ser utilizado quando o cartão ainda está em produção ou entrega (ex.: endereço incorreto, falha de entrega, cartão extraviado antes da ativação).

:::info Preservação da operação
A reemissão **não cancela** a reserva, a operação de crédito nem a averbação na Dataprev.
:::

:::caution Cobrança da re-emissão
A taxa de produção e de entrega da re-emissão do cartão é cobrada do correspondente bancário automaticamente via sistema.
:::

:::caution Status elegíveis do cartão
A reemissão só é permitida enquanto o cartão estiver em produção ou entrega. São aceitos cartões nos seguintes status: `building`, `embossing` ou `canceled`. Cartões já ativos (`active`) não podem ser reemitidos por este endpoint.
:::

:::tip Atualização de endereço no mesmo fluxo
Opcionalmente, é possível enviar um novo endereço de entrega no corpo da requisição. Quando informado, o endereço do beneficiário na reserva é atualizado e o novo cartão é produzido/entregue neste endereço.
:::

### Request

**POST**
/payroll_card_reservation/{collateral_type}/{payroll_card_reservation_key}/reissue_card

Testar no Playground

**Request Body (opcional)**

```json
{
    "delivery_address": {
        "city": "Belo Horizonte",
        "state": "MG",
        "number": "789",
        "street": "Rua das Palmeiras",
        "complement": "Casa 3",
        "postal_code": "30112000",
        "neighborhood": "Savassi"
    }
}
```

O corpo da requisição é opcional. Caso não seja enviado, o novo cartão será emitido utilizando o endereço atualmente cadastrado na reserva.

**Request Body Details**

| Campo | Tipo | Descrição | Obrigatório |
|---|---|---|---|
| delivery_address | object | Novo endereço de entrega. Quando enviado, também atualiza o endereço cadastrado na reserva. | Não |

#### Payload delivery_address

| Campo | Tipo | Descrição | Formatação | Obrigatório |
|---|---|---|---|---|
| city | string | Cidade | Mínimo: 1 caractere | Sim |
| state | string | Estado (UF) | 2 caracteres | Sim |
| number | string | Número | Mínimo: 1 caractere | Sim |
| street | string | Logradouro | Mínimo: 1 caractere | Sim |
| complement | string | Complemento | Mínimo: 1 caractere | Não |
| postal_code | string | CEP (apenas números) | 8 dígitos numéricos | Sim |
| neighborhood | string | Bairro | Mínimo: 1 caractere | Sim |

### Response

STATUS
**200** (OK)

Retorna o DTO completo da reserva do cartão consignado, já com o novo `payroll_card` (nova `payroll_card_key`, `card_key` e `payment_instrument_key`). A estrutura do retorno é a mesma descrita na [criação da reserva](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_emissao#3-criação-da-operação-de-saque-e-geração-do-termo).

---

# Manual Cartão Consignado - Webhook

URL: /documentation/manual_cartao_beneficio/manual_cartao_beneficio_webhook

:::info Navegação
- [Acompanhamento](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_acompanhamento) (anterior)
- [Documentos e Assinatura](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_documentos) (próximo)
:::

:::caution API em desenvolvimento
A API ainda está em fase de desenvolvimento, sendo assim, este manual esta sujeito a alterações.
:::

---

## 1. Webhook de Alteração de Status (Global)

Para acompanhar a evolução do pedido (Assinatura concluída, Falha no Onboarding, Desembolso realizado ou Cartão Emitido), a API envia um webhook único notificando a mudança de status da reserva.

WEBHOOK TYPE
laas.payroll_card_reservation.status_change

### Estrutura Geral do Webhook

| Campo | Tipo | Descrição |
|---|---|---|
| key | string | Chave da reserva do cartão |
| status | string | Novo status da reserva |
| webhook_type | string | `laas.payroll_card_reservation.status_change` |
| event_datetime | string | Data e hora do evento |
| data | object | Objeto contendo dados relevantes para a mudança de estado |

### Cenários

#### A. Assinatura Concluída (Pending Onboarding)
Ocorre quando os documentos são assinados (via Qi Sign ou externamente). O status da reservation muda para `pending_onboarding` e o fluxo segue para onboarding. 

Retorna a lista dos attached documents da Reserva, além dos dados da análise facial do assinante .

**Exemplo de Payload**

```json
{
    "key": "3571e292-3a83-4011-904d-20ee963022ef",
    "status": "pending_onboarding",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T14:30:00Z",
    "data": {
        "attached_documents": [
            {
                "document_key":"332017f4-a0d6-463a-8557-e925a9485251",
                "document_type":"payroll_card_term",
                "document_certifier":"qi_sign",
                "document_status":"signed",
                "document_batch_key":"f28bf87a-11cd-4d89-89c0-19229a1b31a7",
                "document_url": "https://storage.googleapis.com/example_document.pdf",
                "signature_url": "https://storage.googleapis.com/example_document_signed.pdf",
            },
            {
                "document_key":"0f0651de-bf3f-45f8-891f-f81b9c24df10",
                "document_type":"payroll_card_consent_term",
                "document_certifier":"qi_sign",
                "document_status":"signed",
                "document_batch_key":"f28bf87a-11cd-4d89-89c0-19229a1b31a7",
                "document_url": "https://storage.googleapis.com/example_document.pdf",
                "signature_url": "https://storage.googleapis.com/example_document_signed.pdf",
            },
            {
                "document_key":"910e8de5-16af-4bc5-8ee1-4a0652ca0cbf",
                "document_type":"withdrawal_operation_term",
                "document_certifier":"qi_sign",
                "document_status":"signed",
                "document_batch_key":"f28bf87a-11cd-4d89-89c0-19229a1b31a7",
                "document_url": "https://storage.googleapis.com/example_document.pdf",
                "signature_url": "https://storage.googleapis.com/example_document_signed.pdf",
            },
            {
                "document_key":"b1c3e915-6707-49f5-85a9-398ef997fdad",
                "document_type":"selfie",
                "document_certifier":"qi_sign",
                "document_status":"generated",
                "document_url":"https://storage.googleapis.com/selfie.jpeg"
            },
            {
                "document_key":"5769a335-a2ac-4913-a742-38b9d1e4abd2",
                "document_type":"document_identification",
                "document_certifier":"qi_sign",
                "document_status":"generated",
                "document_url":"https://storage.googleapis.com/cnh.jpeg"
            },
            {
                "document_key":"75577d34-4ebd-4488-aca8-b064e603c973",
                "document_type":"document_identification_back",
                "document_certifier":"qi_sign",
                "document_status":"generated",
                "document_url":"https://storage.googleapis.com/cnh_back.jpeg"
            }
        ],
        "signature_data": {
            "document_similarity_score": 1,
            "similarity_score": 0.75,
            "biometry_analysis_reference": "internal",
        }
    }
}
```

**Response Body Details**

| Campo | Tipo | Descrição |
|---|---|---|
| attached_documents | array | Lista de documentos criados para a reserva |
| signature_data | object | Dados biométricos coletados na assinatura |

##### Payload signature_data

| Campo | Tipo | Descrição |
|---|---|---|
| document_similarity_score | number | Nota de similiaridade biométrica entre o assinante e o documento enviado (0-1) |
| similarity_score | number | Nota de similiaridade biométrica entre o assinante e a referência encontrada na base de rostos (0-1) |
| biometry_analysis_reference | string | Base de origem do rosto utilizado para o calculo da nota de similaridade biométrica |

#### B. Envio de Documentos Adicionais (Pending Additional Documents Submission)
Ocorre quando o onboarding é aprovado com sucesso **OU** quando a operação retorna da etapa de validação devido à rejeição do documento adicional (vídeo).

Este webhook indica que a operação está aguardando o envio (ou reenvio) do vídeo de confirmação via endpoint `/additional_documents`. Caso seja um reenvio por rejeição, o payload retornará o campo `rejection_reason`.

**Exemplo de Payload**

```json
{
    "key": "3571e292-3a83-4011-904d-20ee963022ef",
    "status": "pending_additional_documents_submission",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T16:00:00Z",
    "data": {
        "rejection_reason": "Vídeo sem áudio ou ilegível" // Presente apenas quando retornando do status pending_additional_documents_validation após a rejeição de um documento
    }
}
```

#### C. Validação de Documentos Adicionais (Pending Additional Documents Validation)
Ocorre após o envio com sucesso do vídeo de confirmação. O status muda para `pending_additional_documents_validation`, indicando que o vídeo/documento adicional entrou na fila para validação e análise.

**Exemplo de Payload**

```json
{
    "key": "3571e292-3a83-4011-904d-20ee963022ef",
    "status": "pending_additional_documents_validation",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T16:15:00Z",
    "data": {}
}
```

#### D. Documentos Adicionais Aprovados (Pending Collateral Reservation)
Ocorre após a etapa de validação analisar e aprovar o vídeo de confirmação. O status muda para `pending_collateral_reservation` (aguardando reserva de margem na Dataprev).

**Exemplo de Payload**

```json
{
    "key": "3571e292-3a83-4011-904d-20ee963022ef",
    "status": "pending_collateral_reservation",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T17:00:00Z",
    "data": {}
}
```

#### E. Margem Averbada (Pending Withdrawal Disbursement)
Ocorre quando a margem é reservada com sucesso na Dataprev e a operação de crédito é criada e está aguardando desembolso. O status muda para `pending_withdrawal_disbursement` (aguardando desembolso do saque).

**Exemplo de Payload**

```json
{
    "key": "3571e292-3a83-4011-904d-20ee963022ef",
    "status": "pending_withdrawal_disbursement",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T17:30:00Z",
    "data": {
        "credit_operation_key": "3571e292-3a83-4011-904d-20ee963022ef"
    }
}
```

#### F. Desembolso Realizado (Pending Card Issuance)
Ocorre quando o saque é efetivado. O status muda para `pending_card_issuance` (aguardando emissão do cartão) e o fluxo segue para a emissão do cartão.

Não retorna nenhuma informação adicional.

**Exemplo de Payload**

```json
{
    "key": "3571e292-3a83-4011-904d-20ee963022ef",
    "status": "pending_card_issuance",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T17:00:00Z",
    "data": {
        "wallet_key": "9a7b7982-8bf7-4a2c-942c-588166811623"
    }
}
```

#### G. Cartão Emitido (Card Issued)
Ocorre quando a wallet e o cartão são criados.

**Exemplo de Payload**

```json
{
    "key": "3571e292-3a83-4011-904d-20ee963022ef",
    "status": "card_issued",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T18:30:00Z",
    "data": {
        "card_key": "7c6b421e-7ae0-4419-b021-87bcc0be8748"
    }
}
```

---

#### H. Cancelamento (Canceled)
Ocorre quando a operação é cancelada por algum motivo (Rejeição nas validações de identidade ou crédito, erro na reserva da margem na Dataprev, etc).

Retorna o motivo do cancelamento e detalhes.

**Exemplo de Payload**

```json
{
    "key": "3571e292-3a83-4011-904d-20ee963022ef",
    "status": "canceled",
    "webhook_type": "laas.payroll_card_reservation.status_change",
    "event_datetime": "2025-01-15T16:45:00Z",
    "data": {
        "cancel_reason": "not_eligible", 
        "cancel_details": "Age 15 is not within the eligible range (18-79 years)"
    }
}
```

---

## 2. Webhook de Documentos (Geração e Validação)

Este webhook notifica alterações nos status individuais de cada documento anexado à operação. Isso inclui a geração de contratos, a etapa de coleta de assinaturas, e as respostas da etapa de validação de documentos adicionais (como o vídeo de confirmação).

WEBHOOK TYPE
laas.payroll_card_reservation.attached_document.status_change

### Estrutura Geral do Webhook

| Campo | Tipo | Descrição |
|---|---|---|
| key | string | Chave do documento |
| status | string | Novo status do documento (`generated`, `pending_signature`, `approved`, `rejected`) |
| webhook_type | string | `laas.payroll_card_reservation.attached_document.status_change` |
| event_datetime | string | Data e hora do evento |
| data | object | Objeto contendo dados relevantes para a mudança de status |

#### Detalhes do objeto `data`

| Campo | Tipo | Descrição |
| --- | --- | --- |
| payroll_card_reservation_key | string | Chave da reserva do cartão |
| document_key | string | Chave única do documento |
| document_type | string | Tipo do documento |
| document_url | string | Link para visualização do documento |
| signature_url | string | Link para o fluxo de assinatura. Apenas quando o `status` é `pending_signature`. |
| rejection_reason | string | Motivo da rejeição. Apenas quando o `status` é `rejected`. |

### Cenários

#### A. Documento Gerado (generated)
Ocorre quando os contratos de operação são gerados com sucesso e estão prontos para visualização.

**Exemplo de Payload**

```json
{
    "key": "332017f4-a0d6-463a-8557-e925a9485251",
    "status": "generated",
    "webhook_type": "laas.payroll_card_reservation.attached_document.status_change",
    "event_datetime": "2025-01-15T14:30:00Z",
    "data": {
        "payroll_card_reservation_key": "910e8de5-16af-4bc5-8ee1-4a0652ca0cbf",
        "document_key": "332017f4-a0d6-463a-8557-e925a9485251",
        "document_type": "payroll_card_term",
        "document_url": "https://storage.googleapis.com/example_document.pdf",
        "signature_url": null
    }
}
```

#### B. Assinatura Pendente (pending_signature)
Ocorre quando os contratos estão gerados e prontos para assinatura pelo beneficiário. Retorna a `signature_url`.

**Exemplo de Payload**

```json
{
    "key": "332017f4-a0d6-463a-8557-e925a9485251",
    "status": "pending_signature",
    "webhook_type": "laas.payroll_card_reservation.attached_document.status_change",
    "event_datetime": "2025-01-15T14:30:00Z",
    "data": {
        "payroll_card_reservation_key": "910e8de5-16af-4bc5-8ee1-4a0652ca0cbf",
        "document_key": "332017f4-a0d6-463a-8557-e925a9485251",
        "document_type": "payroll_card_term",
        "document_url": "https://storage.googleapis.com/example_document.pdf",
        "signature_url": "https://test.sign.qitech.com.br/s/SVomf6J"
    }
}
```

#### C. Documento Adicional Aprovado (approved)
Ocorre como resposta da validação de um documento adicional (como o vídeo de confirmação), indicando que ele foi validado e aceito pelo nosso time ou sistema de checagem.

**Exemplo de Payload**

```json
{
    "key": "2fc216c6-5d1c-4713-b70b-6e1f75f8bb17",
    "status": "approved",
    "webhook_type": "laas.payroll_card_reservation.attached_document.status_change",
    "event_datetime": "2025-01-15T16:45:00Z",
    "data": {
        "payroll_card_reservation_key": "910e8de5-16af-4bc5-8ee1-4a0652ca0cbf",
        "document_key": "2fc216c6-5d1c-4713-b70b-6e1f75f8bb17",
        "document_type": "payroll_card_confirmation_video",
        "document_url": "https://storage.googleapis.com/video.mp4",
        "signature_url": null
    }
}
```

#### D. Documento Adicional Rejeitado (rejected)
Ocorre como resposta negativa da validação de um documento adicional. Neste cenário, o arquivo foi recusado e o payload incluirá a propriedade `rejection_reason` informando o porquê.

**Exemplo de Payload**

```json
{
    "key": "2fc216c6-5d1c-4713-b70b-6e1f75f8bb17",
    "status": "rejected",
    "webhook_type": "laas.payroll_card_reservation.attached_document.status_change",
    "event_datetime": "2025-01-15T16:50:00Z",
    "data": {
        "payroll_card_reservation_key": "910e8de5-16af-4bc5-8ee1-4a0652ca0cbf",
        "document_key": "2fc216c6-5d1c-4713-b70b-6e1f75f8bb17",
        "document_type": "payroll_card_confirmation_video",
        "document_url": "https://storage.googleapis.com/video_bad.mp4",
        "signature_url": null,
        "rejection_reason": "Áudio inaudível e rosto do cliente não visível"
    }
}
```

---

## 3. Webhook de Retorno da Averbadora (Collateral)

Este webhook notifica sobre o andamento da reserva de margem junto ao órgão que averba a operação. Ele é emitido pela API da fonte de consignação, e não pela reserva do cartão — por isso o `webhook_type` e o conteúdo de `last_response` variam conforme a fonte.

É utilizado principalmente em cenários de **"Teimosinha"**, onde falhas temporárias (como margem presa ou valor de parcela excedido momentaneamente) não cancelam a reserva imediatamente. Nesses casos, a reserva permanece na fila de averbação até a última data de desembolso configurada.

**INSS**

A averbadora é a **Dataprev**.

WEBHOOK TYPE
social_security.collateral

### Estrutura Geral do Webhook

| Campo | Tipo | Descrição |
|---|---|---|
| key | string | Chave da **Reserva do Cartão** (`payroll_card_reservation_key`) |
| webhook_type | string | Sempre `social_security.collateral` |
| event_time | string | Data e hora do evento |
| data | object | Dados detalhados do retorno da Dataprev |
| data.collateral_constituted | boolean | Indica se a garantia foi constituída com sucesso (`true` ou `false`) |
| data.collateral_data.status | string | Status da reserva (ex: `pending_reservation`) |
| data.collateral_data.last_response | object | Contém a lista de erros retornada pela Dataprev (ex: `installment_limit_excceded`) |

**Exemplo de Payload - Falha Temporária**

```json
{
  "event_time": "2026-01-06 18:48:51",
  "key": "b670553f-28f4-4cf2-a3b5-e33c5ae86bb5",
  "webhook_type": "social_security.collateral",
  "data": {
    "collateral_data": {
      "last_response": {
        "errors": [
          {
            "enumerator": "installment_limit_excceded"
          }
        ]
      },
      "status": "pending_reservation",
      "last_response_event_datetime": "2026-01-06T18:48:51Z",
      "reservation_method": "social_security_payroll_card"
    },
    "collateral_type": "social_security_payroll_card",
    "collateral_constituted": false
  }
}
```

**Consignado Público**

:::caution Em construção
O `webhook_type` e o conteúdo de `last_response` do Consignado Público serão publicados junto com o produto. Ver [Consignado Público](/documentation/guides/publico/visao_geral).
:::

---

## 4. Webhook de Operação de Crédito (Desembolso e Status da CCB)

Este webhook notifica a mudança de status da **Operação de Crédito** (CCB) vinculada à reserva. Ele é disparado em dois momentos principais:
1.  **Sucesso (`opened`):** O valor foi transferido com sucesso para a conta do cliente.
2.  **Cancelamento (`canceled`):** Ocorreu um erro bancário no desembolso (ex: conta inválida, divergência de titularidade) e a operação foi cancelada.

WEBHOOK TYPE
laas.credit_operation.status_change

### Estrutura Geral do Webhook

| Campo | Tipo | Descrição |
|---|---|---|
| key | string | Chave da **Operação de Crédito** (`credit_operation_key`) |
| status | string | Novo status da operação: `opened` (Sucesso) ou `canceled` (Falha) |
| webhook_type | string | Sempre `laas.credit_operation.status_change` |
| event_datetime | string | Data e hora do evento |
| data | object | Objeto variável contendo detalhes do sucesso ou motivo do erro |

---

### Cenário A: Desembolso com Sucesso (`opened`)

Quando o status é `opened`, o objeto `data` contém os detalhes financeiros finais e o comprovante da transação.

| Campo (dentro de `data`) | Tipo | Descrição |
|---|---|---|
| installments | array | Lista de parcelas confirmadas com datas e valores finais |
| transaction_receipts | array | Lista de comprovantes de transferência bancária |
| requester_identifier_key | string | Identificador único do solicitante |

**Exemplo de Payload - Sucesso**

```json
{
    "key": "550e8400-e29b-41d4-a716-446655440000",
    "status": "opened",
    "webhook_type": "laas.credit_operation.status_change",
    "event_datetime": "2025-10-14 13:26:52",
    "data": {
      "installments": [
        {
          "due_date": "2025-12-28",
          "total_amount": 315.02,
          "installment_key": "123e4567-e89b-12d3-a456-426614174000",
          "pre_fixed_amount": 212.35873015,
          "installment_number": 1,
          "principal_amortization_amount": 102.66126985
        },
        {
          "due_date": "2026-01-28",
          "total_amount": 315.02,
          "installment_key": "123e4567-e89b-12d3-a456-426614174001",
          "pre_fixed_amount": 76.17371273,
          "installment_number": 2,
          "principal_amortization_amount": 238.84628727
        },
        {
          "due_date": "2026-02-28",
          "total_amount": 315.02,
          "installment_key": "123e4567-e89b-12d3-a456-426614174002",
          "pre_fixed_amount": 59.12264515,
          "installment_number": 3,
          "principal_amortization_amount": 255.89735485
        },
        {
          "due_date": "2026-03-28",
          "total_amount": 315.02,
          "installment_key": "123e4567-e89b-12d3-a456-426614174003",
          "pre_fixed_amount": 36.77641144,
          "installment_number": 4,
          "principal_amortization_amount": 278.24358856
        },
        {
          "due_date": "2026-04-28",
          "total_amount": 315.02,
          "installment_key": "123e4567-e89b-12d3-a456-426614174004",
          "pre_fixed_amount": 20.98850053,
          "installment_number": 5,
          "principal_amortization_amount": 294.03149947
        }
      ],
      "disbursement_type": "pix",
      "transaction_receipts": [
        {
          "fee": 0,
          "url": "https://bank-receipt-url.com/receipt.pdf",
          "amount": 1151.15,
          "origin": {
            "name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
            "type": "payment_account",
            "branch": "0001",
            "document": "32402502000135",
            "bank_code": "329",
            "account_key": "acc_origin_uuid",
            "branch_digit": null,
            "account_digit": "1",
            "account_branch": "0001",
            "account_number": "1234567",
            "financial_institution_name": "QI SCD S.A."
          },
          "timestamp": "2025-10-14T13:26:52",
          "description": "1234567 - Roberto Alves",
          "destination": {
            "name": "Roberto Alves",
            "type": "checking_account",
            "branch": "0001",
            "purpose": "Crédito PIX em Conta",
            "document": "12345678911",
            "bank_ispb": "12121212",
            "branch_digit": null,
            "account_digit": "2",
            "account_number": "123456",
            "financial_institution_name": "BANCO"
          },
          "end_to_end_id": "E32402502202510141326",
          "transaction_key": "tx_key_uuid",
          "origin_transaction_key": "origin_tx_key_uuid"
        }
      ],
      "requester_identifier_key": "req_id_key_uuid"
    }
}
```

---

### Cenário B: Falha no Desembolso (`canceled`)

Quando o status é `canceled`, o objeto `data` contém o motivo da recusa bancária (Pix ou TED devolvido).

| Campo (dentro de `data`) | Tipo | Descrição |
|---|---|---|
| cancel_reason | string | Motivo macro do cancelamento (ex: `pix_refusal`, `ted_refusal`) |
| cancel_reason_enumerator | string | Enumerador do motivo (ex: `pix_refusal`) |
| pix_refusal | object | Detalhes da recusa caso seja Pix (opcional) |
| ted_refusal | object | Detalhes da recusa caso seja TED (opcional) |
| [refusal].reason | string | Mensagem descritiva do erro bancário |
| [refusal].reason_enumerator | string | Código do erro bancário (ex: `invalid_account`) |

**Exemplo de Payload - Erro no Desembolso**

```json
{
    "key": "30e8917d-2b1f-4c79-baf5-cc18bb6e0277",
    "status": "canceled",
    "webhook_type": "laas.credit_operation.status_change",
    "event_datetime": "2026-01-06 20:57:04",
    "data": {
        "cancel_reason": "pix_refusal",
        "cancel_reason_enumerator": "pix_refusal",
        "pix_refusal": {
            "reason": "Número da conta de destino é inexistente ou inválido.",
            "reason_enumerator": "invalid_account",
            "cancel_reason_enumerator": "invalid_account"
        }
    }
}
```

:::info Reapresentação
O cancelamento da Operação de Crédito associada a uma reserva não necessariamente implica no cancelamento da reserva em sí. Em casos de erro de desembolso, a reserva permanece aberta e a operação de crédito permanece apta a reapresentação até a data de envio do cartão.

Para mais detalhes, ver tópico [5. Reapresentação de Pagamento do Saque](./manual_cartao_beneficio_emissao.md) em Criação da Reserva
:::

## 5. Webhook de Criação da Apólice de Seguro/Benefício

Este webhook notifica a emissão do seguro associado ao cartão, e retorna a URL da apólice do benefício. 
A emissão do seguro ocorre de forma assíncrona após a emissão do cartão, podendo demorar algumas horas para ser confirmada.

WEBHOOK TYPE
laas.payroll_card_reservation.benefit.emission

### Estrutura Geral do Webhook

| Campo | Tipo | Descrição |
|---|---|---|
| key | string | Chave da **Reserva do Cartão** (`payroll_card_reservation_key`) |
| status | string | `active` (Seguro ativo) |
| webhook_type | string | Sempre `laas.payroll_card_reservation.benefit.emission` |
| event_datetime | string | Data e hora do evento |
| data | object | Objeto variável contendo detalhes da apólice |
| data.benefit_key | string | Chave do Benefício/Seguro associado a uma reserva (`benefit.benefit_key`) |
| data.policy_url | string | URL do documento da apólice do seguro |

**Exemplo de Webhook**

```json
{
    "key": "550e8400-e29b-41d4-a716-446655440000",
    "status": "active",
    "webhook_type": "laas.payroll_card_reservation.benefit.emission",
    "event_datetime": "2025-10-14 13:26:52",
    "data": {
      "benefit_key": "29dbece4-9f57-40ae-b85c-8e04bf2c4cdf",
      "policy_url": "https://example.com/policy.pdf",
    }
}
```

---

# Manual Cartão Consignado - Visão Geral

URL: /documentation/manual_cartao_beneficio/visao_geral

O cartão consignado é um cartão de crédito cujo limite é garantido por uma **margem consignável** — uma parcela mensal descontada diretamente da folha de pagamento ou do benefício do titular. Na contratação, parte do limite é liberada como **saque em conta**, e o restante fica disponível como limite rotativo do cartão.

:::caution API em desenvolvimento
A API ainda está em fase de desenvolvimento, sendo assim, este manual está sujeito a alterações.
:::

## O que a QI Tech entrega

Uma única integração cobre a operação inteira: a simulação das condições, a emissão da CCB de saque, o onboarding e a assinatura digital dos termos, a averbação da margem junto ao órgão consignante, o desembolso e a emissão do cartão físico.

| Produto | `product_type` | O que é |
|---|---|---|
| Cartão Benefício | `benefit_card` | Cartão de benefício com limite consignado |
| Cartão Consignado | `payroll_card` | Cartão de crédito consignado |

## A jornada de uma contratação {#a-jornada}

Do primeiro contato até o cartão na mão do titular:

1. **Elegibilidade** — verifica se o CPF pode contratar. Síncrono. Ver [Emissão](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_emissao).
2. **Simulação** — calcula limite total, valor de saque e parcelas a partir da margem e das condições financeiras. Nada é criado ainda.
3. **Criação da reserva** — cria a operação, gera os termos e devolve a `payroll_card_reservation_key`, a chave que identifica a contratação daqui em diante.
4. **Onboarding e assinatura** — o titular passa por KYC, assina os termos e envia o vídeo de confirmação. Ver [Documentos e Assinatura](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_documentos).
5. **Averbação da margem** — a QI Tech reserva a margem junto ao órgão consignante. É a etapa que depende da fonte de consignação e a que pode falhar por margem insuficiente.
6. **Desembolso e emissão** — o saque é desembolsado na conta informada e o cartão é emitido e enviado. Ver [Gestão de Endereço](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_endereco).

Cada transição emite um webhook. A máquina de status completa está em [Acompanhamento](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_acompanhamento); as notificações, em [Webhooks](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_webhook).

## Fontes de consignação {#fontes-de-consignacao}

O mesmo produto atende mais de uma folha de pagamento. A **fonte de consignação** é o primeiro segmento da rota, e o **produto** é um campo do corpo da requisição:

```
POST /payroll_card_reservation/{collateral_type}
{
  "product_type": "benefit_card",
  "collateral": { ... no formato da fonte informada na rota ... }
}
```

| Fonte | Valor na rota | Quem atende | Regras do produto |
|---|---|---|---|
| INSS | `social_security` | Aposentados e pensionistas do INSS | [INSS](/documentation/guides/INSS/intro) |
| Consignado Público | `public_payroll` | Servidores públicos estaduais e municipais | [Consignado Público](/documentation/guides/publico/visao_geral) |

A combinação de fonte e produto resolve o **tipo de cartão** (`payroll_card_type`), que é o que a API devolve nas respostas e o que carrega a configuração comercial: tetos de parcelas e de taxa, faixa etária elegível e multiplicador de limite. Uma combinação não contratada é recusada com **400 `PCR000004`**.

Entre as fontes, variam apenas três coisas — o segmento da rota, a seção [`collateral`](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_emissao#colateral-por-fonte-de-consignacao) e a entrada financeira aceita (`salary_amount` ou `available_margin`). O restante da jornada é idêntico.

:::info Exemplos e Playground
Os exemplos executáveis deste manual usam `social_security` na rota, por ser a fonte disponível hoje.
:::

## Conteúdo desta seção

1. **[Emissão](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_emissao)** — elegibilidade, simulação, criação da operação e envio de documentos adicionais.
2. **[Acompanhamento](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_acompanhamento)** — consulta da reserva, consulta por CPF do titular e máquina de status.
3. **[Webhooks](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_webhook)** — notificações de mudança de status da reserva, do saque e do cartão.
4. **[Documentos e Assinatura](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_documentos)** — geração, assinatura e reenvio dos termos.
5. **[Gestão de Endereço](/documentation/manual_cartao_beneficio/manual_cartao_beneficio_endereco)** — atualização do endereço de entrega do cartão.
6. **[Changelog](/documentation/manual_cartao_beneficio/changelog)** — mudanças de contrato relevantes para quem já integra.

## Glossário

| Termo | Significado |
|---|---|
| **Margem consignável** | Valor mensal que pode ser comprometido com a operação, descontado direto da folha ou do benefício. É a base do limite do cartão. |
| **Averbação** | Reserva da margem junto ao órgão consignante, o que torna o desconto efetivo. |
| **Reserva** (`payroll_card_reservation`) | A entidade que acompanha a contratação, da criação até a emissão do cartão. |
| **Saque** (`withdrawal`) | A parte do limite liberada em conta na contratação, formalizada em uma CCB. |
| **Fonte de consignação** (`collateral_type`) | A folha que garante a operação — `social_security` (INSS) ou `public_payroll` (servidores públicos estaduais e municipais). É o primeiro segmento da rota. |
| **Produto** (`product_type`) | O cartão contratado — `benefit_card` ou `payroll_card`. É um campo do corpo da requisição. |
| **Tipo de cartão** (`payroll_card_type`) | A combinação de fonte e produto, por exemplo `social_security_benefit_card`. Carrega a configuração comercial e aparece nas respostas. |

---

# Manual CertifiQI

URL: /documentation/manual_certifiqi/dc37cf4f-adad-45c5-9251-9c957fb9ce8e

## Request

ENDPOINT /document
MÉTODO POST

Request Body

```json
{
        "file_name": "nome.pdf",
        "document_type": "ccb",
        "document_identifier": "jfkjkd",
        "endorsement_page": true,
        "endorser_name": "NOME ENDOSSANTE",
        "endorser_document_number": "CNPM ENDOSSANTE",
        "receiver_name": "NOME ENDOSSATÁRIO",
        "receiver_document_number": "CNPJ ENDOSSATÁRIO",
        "control_number": "123456789"
}
```

O método POST /document deve ser utilizado para enviar os documentos (PDF ou CNAB) e vincular a um grupo de documentos.

Deverão ser enviados os seguintes dados no form-data da request:

- file - documento no formato pdf.

:::caution **Retorno desta request**

O retorno desta request deverá ser enviado posteriormente na request POST /batch_group. Depois de enviado junto com o batch_group não há necessidade de salvar esta informação.

:::

## Response

STATUS 200

Response Body

```json
{
		"control_number": null,
		"document_key": "45e781b8-7275-48e6-8719-b4d232b2828a",
		"file_size": 281195,
		"name": "ml1258-00822_22_carlos_cesar_consolaro_20221222095624158505.pdf",
		"url": "https://storage.googleapis.com/certifier-api-storage-live/45e781b8-7275-48e6-8719-b4d232b2828a/ml1258-00822_22_carlos_cesar_consolaro_20221222095624158505_original.pdf"
}

```

## Definições

### Objeto Request Body
| Campo                           | Tipo   | Descrição                                                                                                                                                                                                        | Máx. Caract. | 
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **file_name** *                  | string | Nome do arquivo que será enviado.                                                                                                                                        | -            | 
| **document_type** * | string | Tipo do documento que será enviado.                                                                                 | -            |
| **document_identifier** *                 | string | Identificador do documento do sistema do parceiro. | -            |
| **endorsement_page** * | booleano | Indica se um endosso deve ser gerado para o documento.                                                                                                                                                           | -            |
| **endorser_name** * | string | nome do endossante.                                                                                                                                                           | -            |
| **endorser_document_number** * | string | Numero de documento do endossante.                                                                                                                                                           | -            |
| **receiver_name** * | string | Nome do recebedor.                                                                                                                                                           | -            |
| **receiver_document_number** * | string | Número de documento do recebedor.                                                                                                                                                           | -            |
| **control_number** | string | Campo opcional indicando o numero de controle da cessão, fornecido pela QI Tech quando a cessão é realizada pela pela mesma.                                                                                                                                                           | 36            |

## Request

ENDPOINT /batch_group
MÉTODO POST

Request Body

```json
{
    "client_key": "eb4d4f62-f209-47aa-bb99-24d4e056ae11",
    "name": "Endosso",
    "main_related_party": "MACACO LOCO LTDA",
    "batches": [{
        "documents": [
                {
		"control_number": null,
		"document_key": "45e781b8-7275-48e6-8719-b4d232b2828a",
		"file_size": 281195,
		"name": "ml1258-00822_22_macaco_loco_20221222095624158505.pdf",
		"url": "https://storage.googleapis.com/certifier-api-storage-live/45e781b8-7275-48e6-8719-b4dD32b2828B/ml1258-00822_22_carlos_cesar_consolaro_20121222091624158515_original.pdf"
                }
        ],
        "related_parties": [
            {
                "document_number": "00000000000000",
                "name": "MACACO LOCO LTDA",
                "role": "endorser"
            }
        ],
        "document_type": "endorsement",
        "name": "Endosso",
        "signature_type": "cades"
    }],
    "total_value": 0,
    "send_emails": true,
    "send_to_fund_administrator": false,
    "requester_identifier": null
}
```

O método POST /batch_group deve ser utilizado para enviar todos os documentos e os assinantes
do evento para assinatura. Os dados que devem ser enviados no body da request estão disponíveis em Criar 'batch group.

## Response

STATUS 200

Response Body

```json
{
	"batch_group_key": "6ab44a69-7089-4951-a27a-d58c4136ac11",
	"name": "Endosso",
	"main_related_party": "MACACO LOCO LTDA",
	"number_of_documents": 131,
	"total_value": 0.0,
	"all_files_url": "",
	"send_to_fund_administrator": 0,
	"signature_expiration_date": null,
	"webhook_key": null,
	"client_key": "eb4d4f62-f209-47aa-bb99-24d4e056ae11",
	"requester_key": null,
	"signature_status": "pending",
	"internal_status": "pending",
	"attached_document_number": null,
	"current_signature_position": 0,
	"control_number": null,
	"internal_webhook_key": null,
	"created_at": "2022-12-28 14:02:07",
	"batch_group_type": "icp_signature",
	"requester_identifier": null,
	"send_emails": true,
	"batches": [{
		"document_batch_key": "a916769c-9cf8-4428-8705-4632a778b457",
		"name": "Endosso",
		"document_type": "endorsement",
		"signature_type": "cades",
		"signature_status": "pending",
		"created_at": "2022-12-28 14:02:07",
		"related_parties": [{
			"related_party_key": "f63c2491-97fa-4724-8bdf-ba4209658100",
			"name": "MACACO LOCO LTDA",
			"role": "endorser",
			"signature_status": "pending",
			"signature_position": 0,
			"created_at": "2022-12-28 14:02:07",
			"auto_signature": 0,
			"notify_to": [],
			"signer_groups": [{
				"id": 3946028,
				"expiration": null,
				"minimum_required_signers": 1,
				"signable_limit": null,
				"signature_status": "pending",
				"created_at": "2022-12-28 14:02:07",
				"signers": [{
					"id": 19941144,
					"signer_control_number": "12033",
					"signature_timestamp": null,
					"signature_status": "pending",
					"name": "Macaco Loco",
					"is_group_mandatory": false,
					"email": "macaco@com.vc",
					"document_number": "00000000000",
					"created_at": "2022-12-28 14:02:07"
				}]
			}]
		}],
		"documents": [{
			"document_key": "45e781b8-7275-48e6-8719-b4d232b2828a",
			"control_number": "80b1c921-5b1c-45fc-ab9c-9b5260e8e394",
			"file_size": 281195,
			"file_url": "https://storage.googleapis.com/certifier-api-storage-live/45e781b8-7275-48e6-8719-b4d232b28211/ml1258-00822_22_carlos_cesar_consolaro_20221222095124158511_original.pdf",
			"name": "ml1258-00822_22_macaco_loco_20221222095624158511.pdf",
			"original_file_url": "https://storage.googleapis.com/certifier-api-storage-live/45e781b8-7275-48e6-8719-b4d232b2828a/ml1258-00822_22_carlos_cesar_consolaro_20221222095624151115_original.pdf",
			"status": "pending",
			"signed_file_url": null,
			"created_at": "2022-12-28 14:02:07",
			"signatures": []
		}]
	}],
	"watcher_clients": []
}

```

## Definições

### Objeto Request Body
| Campo                           | Tipo   | Descrição                                                                                                                                                                                                        | Máx. Caract. | 
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **client_key** *                  | string | uuid representando a chave do parceiro.                                                                                                                                         | -            | 
| **name** * | string | Nome dado ao grupo de documentos que será enviado.                                                                                 | -            |
| **main_related_party** *                 | string | Nome da principal parte relacionada para assinar o evento (porém é um campo livre). | -            |
| **batches** * | array of objects | Lista de diferentes tipos de documentos.                                                                                                                                                           | -            |
| **total_value** * | float | Valor total dos documentos do evento.                                                                                                                                                           | -            |
| **send_emails** * | boolean |Indica se os e-mails de assinatura devem ser enviados para este evento de assinatura.                                                                                                                                                           | -            |
| **send_to_fund_administrator** * | boolean | Indica se o evento deve ser enviado para o FROMTIS caso o administrador do fundo o utilize.                                                                                                                                                           | -            |
| **requester_identifier** * | string | Identificador do evento fornecido pelo parceiro.                                                                                                          

### BATCHES OBJECT  

| Campo                           | Tipo   | Descrição                                                                                                                                                                                                        | Máx. Caract. | 
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **related_parties** *                  | array of objects | Partes relacionadas que assinam este batch.                                                                                                                                        | -            | 
| **documents** * | array of objects | lista de documentos enviados no POST /document.                                                                                 | -            |
| **name** *                 | string | NNome do arquivo. | -            |
| **signature_type** * | string | Tipo de assinatura.                                                                                                                                                           | -            |
| **document_type** * | string | Tipo de documento.                                                                                                                                                          | -            |      

### RELATED PARTIES OBJECT  

| Campo                           | Tipo   | Descrição                                                                                                                                                                                                        | Máx. Caract. | 
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **role** *                  | string | Cargo.                                                                                                                                      | -            | 
| **name** * | string | Nome da Empresa.                                                                          | -            |
| **document_number** *                 | string | numero de documento do assinante. | -            |
 
## Request

ENDPOINT /batch_group/ BATCH_GROUP_KEY /send_to_signature
MÉTODO POST

### Path Params

| Campo | Descrição |
|---|---|
| **batch_group_key** * | Chave única de identificação do evento de assinatura. |

O método POST /batch_group/ BATCH_GROUP_KEY /send_to_signature" finaliza o grupo de documentos e envia o lote para assinatura.

---

# Cessão

URL: /documentation/manual_cessao/

Este manual descreve o fluxo de Cessão de Direitos Creditórios operado pela QI Tech, desde a originação do ativo até o repasse ao originador.

## Visão Geral

:::info
O fluxo descrito nesta página se refere ao caso de CCB (Cédula de Crédito Bancário).
:::

O Originador origina os ativos utilizando o balanço da QI Tech para realizar o desembolso. A partir daí, o fluxo segue três grandes blocos:

```mermaid
graph LR
    O[Originação do Ativo] --> D[Desembolso Pré-Cessão<br/>via balanço QI Tech]
    D --> P[Processo de Cessão]
    P --> R[Repasse e Conciliação]
```

:::info
Além do desembolso pré-cessão (via balanço da QI Tech), também existem opções de desembolso pós-cessão.
:::

## Cessão dos Direitos Creditórios

Na QI Tech, oferecemos um processo de cessão automatizado e personalizável, no qual adaptamos cada etapa para construir o fluxo ideal para cada parceiro.

O processo se divide em 4 etapas:

```mermaid
graph LR
    E1[1. Seleção e Precificação<br/>das Operações] --> E2[2. Registro na B3, Envio<br/>do Lote e Retorno do Cessionário]
    E2 --> E3[3. Termo de Cessão<br/>e Pagamento]
    E3 --> E4[4. Lastros e Rebate]
```

| # | Etapa | Resumo |
|---|---|---|
| 1 | [Seleção e Precificação das Operações](#etapa-1--seleção-e-precificação-das-operações) | A QI Tech seleciona as operações elegíveis até o horário de corte e direcionadas ao respectivo cessionário. Após a seleção, define-se o preço com base na Promessa de Endosso. |
| 2 | [Registro na B3, Envio do Lote e Retorno do Cessionário](#etapa-2--registro-na-b3-envio-do-lote-e-retorno-do-cessionário) | QI Tech registra os ativos na B3 (se acordado), envia os ativos ao cessionário, que retorna aprovando ou recusando. A QI segue o fluxo apenas com os ativos aprovados. |
| 3 | [Termo de Cessão e Pagamento](#etapa-3--termo-de-cessão-e-pagamento) | QI Tech envia o termo de cessão para assinatura (modelo e signatários definidos na Promessa de Endosso). Após assinatura, aguarda-se o pagamento na conta indicada, no valor exato da cessão. |
| 4 | [Lastros e Rebate](#etapa-4--lastros-e-rebate) | O endosso das CCBs é realizado durante o processo de cessão. Os lastros acordados podem ser enviados durante o processo de cessão ou após a liquidação. No próximo dia útil da cessão, a QI Tech repassa o valor de Rebate ao originador (se houver). |

## Etapa 1 — Seleção e Precificação das Operações

### 1.1 Seleção dos Ativos para Cessão

O cessionário indica o tamanho do lote desejado e os critérios de seleção das operações. Esses critérios são alinhados individualmente para cada fluxo/parceiro.

Por padrão, a QI Tech envia lotes de 2.500 ativos. Por exemplo, se houver 5.000 ativos na cessão, serão abertos 2 lotes.

### 1.2 Horário de Corte

O horário de corte é combinado em discussões comerciais com cada parceiro. Em geral, a QI Tech inicia o processo de cessão às 6h como referência. Operações originadas após o horário acordado não entram na cessão do dia.

### 1.3 Precificação

O cálculo acordado é registrado no Item 5 da Promessa de Endosso. Existem dois métodos possíveis de precificação:

#### Método 1 — Papel + Spread

$$
\text{Preço de Aquisição} = \sum_{n=1}^{n} \left[ nPMT \times \left( \frac{VF_n}{(1+t)^{P_n}} \right) \right] + Spread
$$

| Variável | Significado |
|---|---|
| Spread | = FQI + FO |
| FQI | Fee de Bancarização + RCO |
| FO | Fee do Originador |
| n | Período da parcela analisada |
| nPMT | Quantidade de parcelas em aberto |
| Pn | Diferença de dias entre a data de vencimento da parcela "n" (inclusive) e a data da cessão (exclusive), dividida pela "base" |
| VFn | Valor da parcela "n" no seu respectivo vencimento |
| t | Taxa da CCB, expressa ao ano |
| Base | 365 (trezentos e sessenta e cinco) dias |

#### Método 2 — Taxa Fixa

$$
\text{Preço de Aquisição} = \sum_{n=1}^{n} \left[ \frac{\text{Valor da Parcela}}{(1 + \text{Taxa de Endosso})^{d/base}} \right]
$$

- **Valor da Parcela**: valor de face, nas respectivas datas de vencimento, de cada parcela vincenda da CCB contratada pelo Devedor, incluindo tarifas, tributos e demais encargos aplicáveis.
- **Taxa de Endosso**: taxa anual de deságio acordada entre as Partes no momento da cessão, que seja suficiente para que o Preço de Aquisição seja igual ou maior ao "Preço Base de Venda".

## Etapa 2 — Registro na B3, Envio do Lote e Retorno do Cessionário

### 2.a Registro na B3

Se acordado na Promessa de Endosso, a QI Tech realiza o registro dos ativos na B3. Quando o registro for acordado, é preciso definir se ele é feito pela própria QI Tech ou por uma registradora, conforme combinado comercialmente. Quando aplicável, é necessário informar a conta de custódia do cessionário na B3.

### 2.b Envio do Lote

A QI Tech envia o arquivo do lote de cessão para o cessionário por Bucket, SFTP ou, caso combinado em negociação com o time comercial, via API. O arquivo pode estar nos formatos CNAB, CSV ou JSON — o formato pode ser alinhado entre as partes, mas a QI Tech também pode fornecer modelos padrão.

**Arquivos no Bucket ou SFTP:**

1. O parceiro fornece as credenciais de acesso ao Bucket ou SFTP.
2. A QI Tech deposita o arquivo escolhido (CNAB 444, 400, 800, CSV ou JSON).
3. O parceiro deposita o retorno no mesmo diretório. O arquivo de retorno também pode ser JSON, CNAB ou CSV.

**Outros métodos de envio:**

Caso opte por outros métodos (ex.: envio via portal), há custo de setup e prazo maior de integração.

### 2.c Retorno do Lote

Após o envio do lote, a QI Tech aguarda o retorno de aprovação de todos os contratos. O cessionário deve enviar um arquivo CSV contendo:

| Coluna | Nome | Preenchimento |
|---|---|---|
| A | Número de Contrato | Contrato no formato da CCB ou control number |
| B | Aprovação | "Aprovado" ou "Reprovado" |
| C | Motivo | Motivo para os casos reprovados |

:::info
Para outros tipos de arquivo de retorno, é necessário alinhar o interesse previamente com o time de suporte.
:::

## Etapa 3 — Termo de Cessão e Pagamento

### 3.a Termo de Cessão

A QI Tech envia o termo de cessão para assinatura. O modelo do termo e os signatários são definidos na Promessa de Endosso.

### 3.b Pagamento

- Se o fluxo for via B3: a QI Tech monta a CCCB e faz o lançamento da venda na B3.
- Se o fluxo não for via B3: o pagamento é feito via câmara registradora, e o cessionário envia o valor para a conta informada (Agência / Conta).

:::caution Conteúdo pendente
Os dados de Agência e Conta variam por convênio/cessionário e precisam ser preenchidos conforme o caso de uso específico antes da publicação final.
:::

## Etapa 4 — Lastros e Rebate

O endosso das CCBs é realizado durante o processo de cessão. Os lastros acordados na Promessa de Endosso podem ser enviados durante o processo de cessão ou após a liquidação da operação.

No próximo dia útil da cessão, a QI Tech repassa o valor de Rebate ao originador (se houver).

## Contatos de Suporte

| Time | Contato |
|---|---|
| Tesouraria | suporte.cessao@qitech.com.br / suporte.conciliacao@qitech.com.br |

---

# Conciliação

URL: /documentation/manual_conciliacao/

Este manual descreve o processo de conciliação de CCBs já cedidas ao cessionário (fundo), utilizado sempre que um evento altera a posição de uma operação cedida.

## Tipos de Conciliação

Existem conciliações para os seguintes eventos:

- Portabilidade
- Renegociação
- Refinanciamento
- Cancelamento

## Fluxo de Conciliação

Nesses casos, a QI Tech:

1. Envia um arquivo de baixa para o SFTP/Bucket combinado com o cessionário, com o nome de arquivo acordado entre as partes.
2. Envia uma transferência atrelada ao evento para a conta do fundo vinculado à operação.

## Contatos de Suporte

| Time | Contato |
|---|---|
| Tesouraria | suporte.cessao@qitech.com.br / suporte.conciliacao@qitech.com.br |

---

# Manual Consignado Privado - Averbação de Novos Empréstimos: Consulta de Reservas

URL: /documentation/manual_consignado_privado/averbacao_novos_emprestimos/consultas

Há duas formas de consultar reservas: por operação específica (`external_key`), útil para acompanhar uma única contratação e recuperar seus comprovantes de averbação/desaverbação; ou em lote (paginada), útil para monitorar várias operações de uma vez sem precisar conhecer a `external_key` de cada uma.

## Consulta por operação (external_key) {#consulta-por-operacao-external_key}

Para consultar os dados da averbação de uma operação específica — e, com ela, os **comprovantes de protocolo de averbação ou desaverbação** — pode-se utilizar o endpoint:

:::warning Comprovantes de averbação e desaverbação
É possível recuperar os comprovantes de averbação, desaverbação e suspensão através do objeto `protocols` da resposta deste endpoint. Os possíveis enumeradores para `protocol_type` estão disponíveis na tabela [Tipos de protocolo](/documentation/manual_consignado_privado/manual_averbação_desembolso#protocol_type).
:::

**GET**
/private_payroll/reservation/external_key/ [DEBT-KEY]

Testar no Playground

### Response

STATUS
**200** OK

**Response Body**

```json
{
    "data": [
        {
            "reservation_key": "310754e1-cef2-4b19-ba04-7b1c0b575276",
            "document_number": "04142652117",
            "registration_number": "SECAIXADEA00000000000000006258",
            "employer_name": null,
            "admission_date": null,
            "employer_document_number": "04311093000126",
            "external_key": "1d900fed-5ed2-4149-8702-f8dab595b590",
            "contract_number": "179799466",
            "inclusion_date": "2025-09-30",
            "disbursement_date": "2025-02-06",
            "contract_data": {
                "iof": 227.64,
                "periods": [
                    {
                        "amount": 338.22,
                        "due_date": "2025-04-20"
                    },
                    {
                        "amount": 338.22,
                        "due_date": "2025-05-20"
                    },
                    {
                        "amount": 338.22,
                        "due_date": "2025-06-20"
                    },
                    {
                        "amount": 338.22,
                        "due_date": "2025-07-20"
                    },
                    {
                        "amount": 338.22,
                        "due_date": "2025-08-20"
                    }
                ],
                "total_amount": 6680.9,
                "annual_cet_rate": 0.7176,
                "contract_number": "179799466",
                "disbursed_amount": 6090.9,
                "monthly_cet_rate": 0.0461,
                "disbursement_date": "2025-02-06",
                "annual_interest_rate": 0.6163544955,
                "disbursement_end_date": "2025-02-06",
                "monthly_interest_rate": 0.0408
            },
            "reservation_type": "rollover",
            "reservation_status": "reserved",
            "protocols": {
                "reservation": {
                    "receipt_url": "[URL]",
                    "receipt_data": {
                        "contract_number": "XXX0123456789",
                        "protocol_number": "21134056260",
                        "reservation_competence": "2026-03",
                        "installment_value": 468.6,
                        "protocol_type": "reservation",
                        "number_of_installments": 12,
                        "operation_datetime": "30/01/2026 20:21:22"
                    },
                    "protocol_key": "d32342f-369a-4e12-8634-4dfb494d3038"
                },
                "documents_inclusion": {
                    "receipt_data": {
                        "contract_number": "XXX0123456789",
                        "operation_datetime": "30/01/2026 20:21:29",
                        "number_of_installments": 12,
                        "protocol_number": "21134054053",
                        "installment_value": 468.6,
                        "protocol_type": "documents_inclusion"
                    },
                    "receipt_url": "[URL]",
                    "protocol_key": "ae018749-7982-4547-92aa-12455e8bafe7"
                }
            },
        }
    ],
    "pagination": {
        "current_page": 1,
        "next_page": 2,
        "rows_per_page": 1
    }
}
```

## Consulta em lote (paginada)

:::info Novidade
Endpoint novo de consulta paginada de reservas, útil para monitorar em lote o andamento de averbações — sem precisar conhecer previamente a `external_key` de cada operação.
:::

Diferente da consulta por operação acima, este endpoint não recebe nenhuma `external_key` — ele **lista e filtra reservas em lote**, entre todas as operações do solicitante.

**GET**
/private_payroll/reservation

Testar no Playground

A consulta é sempre restrita às reservas do próprio solicitante autenticado — não é necessário (nem possível) informar o `requester_key` como filtro. Para acompanhar novas contratações, filtre por `reservation_type=new_credit`.

### Query Params

| Campo | Descrição | Tipo | Obrigatório | Valores |
|---|---|---|---|---|
| `document_number` | CPF do trabalhador, para filtrar as reservas de um único tomador | Texto | Não | — |
| `reservation_type` | Filtra pelo método de averbação da reserva | Texto | Não | `new_credit`, `refinancing`, `portability`, `transferred` |
| `reservation_status` | Filtra pelo status atual da reserva | Texto | Não | Ver [Enumeradores](/documentation/manual_consignado_privado/averbacao_novos_emprestimos/enumeradores#reservation_status) |
| `page_number` | Número da página, começando em 1 | Número | Não (padrão `1`) | Mínimo `1` |
| `page_rows` | Quantidade de registros por página | Número | Não (padrão `25`) | Entre `1` e `100` |

### Response sucesso

STATUS
**200**

**Response Body**

```json
{
    "data": [
        {
            "reservation_key": "<Reservation Key>",
            "requester_key": "123e4567-e89b-12d3-a456-426614174000",
            "document_number": "12345678901",
            "registration_number": "99999999999-A",
            "employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
            "admission_date": "2025-04-02",
            "employer_document_number": "12345678901234",
            "external_key": "123e4567-e89b-12d3-a456-426614174000",
            "contract_number": "2024001234",
            "inclusion_date": "2025-04-02",
            "disbursement_date": "2025-04-05",
            "expiration_date": null,
            "contract_data": {
                "amount": 5000.00,
                "installments": 12,
                "interest_rate": 0.018
            },
            "reservation_data": {
                "installment_value": 500.00,
                "margin_value": 450.00
            },
            "reservation_type": "new_credit",
            "reservation_status": "reserved",
            "reservation_documents_submission_status": "sent",
            "protocols": {},
            "next_check_datetime": null,
            "next_billing_execution_datetime": null,
            "balance_inquiry_data": {},
            "periods": [],
            "warranty_type": null
        }
    ],
    "pagination": {
        "current_page": 1,
        "next_page": 2,
        "rows_per_page": 25
    }
}
```

Cada item de `data` tem o mesmo formato retornado pelos endpoints de autorização (ver [Autorização e Averbação](/documentation/manual_consignado_privado/averbacao_novos_emprestimos/tecnico#1-autorizacao)). Já `pagination.next_page` vem `null` quando a página atual é a última (ou seja, quando a quantidade de itens retornados em `data` é menor que `page_rows`); caso contrário, traz o número da próxima página a ser consultada.

### Response falha

Quando nenhuma reserva atende aos filtros informados, o endpoint retorna:

STATUS
**404**

**Response Body**

```json
{
    "title": "Reservation not found",
    "code": "PRP000035",
    "description": "The reservation was not found",
    "translation": "A reserva não foi encontrada"
}
```

---

# Manual Consignado Privado - Averbação de Novos Empréstimos: Enumeradores

URL: /documentation/manual_consignado_privado/averbacao_novos_emprestimos/enumeradores

:::info Motivos de falha na averbação
Os motivos retornados pela DATAPREV em uma averbação sem sucesso (e a lógica de retentativa vs. cancelamento) estão em [Erros de Averbação](/documentation/manual_consignado_privado/averbacao_novos_emprestimos/erros#motivos-de-falha-na-averbacao), não nesta página.
:::

## Status da reserva {#reservation_status}

| Enumerador | Descrição |
|---|---|
| **pending_requester_authorization** | Averbação criada, aguardando autorização do parceiro |
| **pending_reservation** | Averbação criada, na fila para tentativa junto à DATAPREV |
| **authorized** | Averbação autorizada pelo parceiro, seguirá para a fila de averbação |
| **reserved** | Averbação concluída com sucesso — margem reservada na folha do empregador |
| **canceled** | Averbação cancelada — não haverá novas tentativas |

## Método de averbação da reserva {#reservation_type}

| Enumerador | Descrição |
|---|---|
| **new_credit** | Averbação de uma nova contratação |
| **refinancing** | Averbação de uma operação de refinanciamento |
| **portability** | Averbação de uma operação de portabilidade |
| **transferred** | Averbação de um revínculo (reaverbação em um novo vínculo empregatício) — ver [Movimentação de Vínculos](/documentation/manual_consignado_privado/vinculos_empregaticios/visao_geral) |

---

# Manual Consignado Privado - Averbação de Novos Empréstimos: Erros de Averbação

URL: /documentation/manual_consignado_privado/averbacao_novos_emprestimos/erros

:::info Regras de negócio
Esta página detalha os possíveis erros retornados pela DATAPREV em uma tentativa de averbação, os webhooks que os notificam, e a lógica de retentativa automática ("teimosinha") vs. cancelamento. Para o fluxo de sucesso, veja [Autorização e Averbação](/documentation/manual_consignado_privado/averbacao_novos_emprestimos/tecnico).
:::

## Como uma falha de averbação é notificada

Caso haja uma falha na averbação, o parceiro recebe o seguinte webhook, com os motivos da falha estruturados em uma lista — útil quando há mais de uma crítica retornada pela DATAPREV na mesma tentativa:

Dependendo do erro de averbação, a QI manterá a proposta em **"teimosinha"**, fazendo novas tentativas de averbação até que a operação seja aceita, cancelada manualmente, ou até esgotar as opções de desembolso. A tabela completa de motivos, e se cada um é retentado ou cancela a operação, está em [Motivos de falha na averbação](#motivos-de-falha-na-averbacao).

### Webhook dedicado de falha na averbação {#reservation-failure-webhook}

:::info Disparado também no revínculo
É disparado tanto para falhas de averbação de um contrato novo quanto para falhas de reaverbação por revínculo (ver [Movimentação de Vínculos — Averbação por Revínculo](/documentation/manual_consignado_privado/vinculos_empregaticios/revinculo)).
:::

webhook_type
laas.private_payroll.reservation_failure

**Webhook Body**

```json
{
    "webhook_type": "laas.private_payroll.reservation_failure",
    "key": "<External Key>",
    "status": "pending_reservation",
    "event_datetime": "2025-10-10T19:45:39Z",
    "data": {
        "reservation_key": "<Reservation Key>",
        "reservation_status": "pending_reservation",
        "reservation_type": "new_credit",
        "reasons": [
            {
                "enumerator": "monthly_interest_rate_exceeds_active_proposal",
                "description": "There is an active proposal in the borrower's CTPS app sent by QI with a rate lower than the registration attempt",
                "translation": "Há uma proposta ativa no app da CTPS do tomador enviada pela QI com taxa inferior à da tentativa de averbação"
            }
        ]
    }
}
```

#### Detalhamento de campos

| Campo | Descrição | Valores |
|---|---|---|
| `reservation_key` | Chave da reserva (entidade `reservation`) | UUID |
| `reservation_status` | Status atual da reserva após a falha | `pending_reservation`, `canceled` |
| `reservation_type` | Método de averbação que originou a tentativa | `new_credit`, `refinancing`, `portability`, `transferred` |
| `reasons` | Lista de motivos da falha retornados pela DATAPREV na tentativa — pode conter mais de um item | Ver [Motivos de falha na averbação](#motivos-de-falha-na-averbacao) |
| `reasons[].enumerator` | Código do motivo | Ver [Motivos de falha na averbação](#motivos-de-falha-na-averbacao) |
| `reasons[].description` | Descrição do motivo, em inglês | Texto |
| `reasons[].translation` | Descrição do motivo, em português | Texto |

## "Teimosinha" vs. cancelamento

Cada motivo de falha devolvido pela DATAPREV leva a QI a uma de duas ações:

- **Teimosinha (retentativa automática)** — para críticas transitórias, que podem deixar de existir sem nenhuma ação do parceiro ou do trabalhador (ex.: a margem consignável se libera na próxima competência, ou a proposta concorrente do app CTPS expira). A operação permanece em `pending_reservation` e a QI tenta novamente, até aceitar ou esgotar as opções de desembolso.
- **Cancelamento da operação** — para críticas terminais, que dependem de uma ação fora do controle da QI (o trabalhador desbloquear o vínculo pelo app CTPS, por exemplo) ou que já esgotam por definição o espaço de novas tentativas (limite de contratos por vínculo). A operação vai para `canceled` e não há novas tentativas.

## Motivos de falha na averbação {#motivos-de-falha-na-averbacao}

| Enumerador | Descrição | Ação QI |
|---|---|---|
| **monthly_interest_rate_exceeds_active_proposal** | Há uma proposta ativa no app da CTPS do tomador enviada pela QI com taxa inferior à da tentativa de averbação | Teimosinha |
| **margin_exceeded** | Margem consignável excedida | Teimosinha |
| **competency_change** | Processamento e atualização das informações do Crédito do Trabalhador para virada de competência (crítica transitória) | Teimosinha |
| **allowed_number_of_contracts_exceeded** | Quantidade máxima de contratos excedida | Cancelamento da operação |
| **employment_relationship_blocked** | Vínculo bloqueado pelo tomador (é possível desbloquear pelo app da CTPS) | Cancelamento da operação |

:::info Outros motivos
A DATAPREV pode retornar outras críticas de validação de campos (valores obrigatórios, formato de contrato, taxa de juros, quantidade de parcelas, etc.), listadas na íntegra nos manuais de comunicação da DATAPREV referenciados por este produto. Elas seguem a mesma lógica geral descrita acima.
:::

---

# Manual Consignado Privado - Averbação de Novos Empréstimos: Autorização e Averbação

URL: /documentation/manual_consignado_privado/averbacao_novos_emprestimos/tecnico

:::info Regras de negócio
Esta página cobre os endpoints e o webhook de sucesso da averbação de uma nova contratação. Para entender **por que** a garantia funciona dessa forma, veja [Regras de Negócio](/documentation/manual_consignado_privado/averbacao_novos_emprestimos/visao_geral). Para o que fazer quando a averbação falha, veja [Erros de Averbação](/documentation/manual_consignado_privado/averbacao_novos_emprestimos/erros).
:::

## 1. Autorização {#1-autorizacao}

Após a formalização de uma nova contratação de consignado privado, é criada a entidade `reservation`, utilizada para acompanhar as tentativas de averbação do contrato na DATAPREV e a gestão da garantia após a averbação.

No fluxo ativo, o ambiente pode ser configurado para que a averbação seja criada em um status pendente de autorização ou pode ser criada na fila de averbação — esta configuração deve ser alinhada com o time de operações. No fluxo de leilão, a averbação sempre é criada pendente de autorização.

Quando a averbação é criada com o status `pending_requester_authorization`, é enviado o webhook:

webhook_type
laas.private_payroll.reservation_status_change
reservation_status
pending_requester_authorization

**Webhook Body**

```json
{
    "webhook_type": "laas.private_payroll.reservation_status_change",
    "data": {
        "reservation_status": "pending_requester_authorization"
    },
    "key": "<Debt Key>",
    "event_datetime": "2025-04-09T20:00:20Z",
    "status": "pending_requester_authorization"
}
```

Para autorizar a averbação, deve ser enviada a seguinte requisição, identificando a operação pela `external_key` (o UUID da operação de crédito, o mesmo que `debt_key`/`credit_operation_key`):

:::info Autorizando um revínculo?
Este endpoint identifica a operação pela `external_key` da contratação original. Para autorizar um **revínculo** (reaverbação em um novo vínculo empregatício), a autorização é feita por `reservation_key` em um endpoint próprio — ver [Movimentação de Vínculos — Averbação por Revínculo](/documentation/manual_consignado_privado/vinculos_empregaticios/revinculo#2-atualizacao-da-margem).
:::

#### Request

**PATCH**
/private_payroll/reservation/external_key/ EXTERNAL-KEY /authorize
Testar no Playground

#### Response sucesso

STATUS
**200**

**Response Body**

```json
{
    "reservation_key": "<Debt Key>",
    "document_number": "12345678901",
    "registration_number": "99999999999-A",
    "employer_document_number": "12345678901234",
    "external_key": "abc123def456",
    "contract_number": "2024001234",
    "inclusion_date": "2024-03-18",
    "disbursement_date": "2024-03-20",
    "contract_data": {
        "amount": 5000.00,
        "installments": 12,
        "interest_rate": 0.018
    },
    "reservation_data": {
        "installment_value": 500.00,
        "margin_value": 450.00
    },
    "reservation_status": "authorized"
}
```

#### Response falha

STATUS
**400**

**Response Body**

**Operação não encontrada**

    ```json
    {
        "title" : "Reservation not found",
        "code" : "PRP000035",
        "description" : "The reservation was not found",
        "translation" : "A reserva não foi encontrada",
    }
    ```

**Averbação ainda não está pronta para autorização**

    ```json
    {
        "title" : "Reservation is not ready for authorization",
        "code" : "PRP000111",
        "description" : "The reservation is not ready for authorization",
        "translation" : "A reserva não está pronta para autorização"
    }
    ```

**Averbação já está autorizada**

    ```json
    {
        "title" : "Reservation is not pending requester authorization",
        "code" : "PRP000057",
        "description" : "The reservation is not pending requester authorization",
        "translation" : "A reserva não está pendente de autorização do requerente",
    }
    ```

## 2. Averbação {#2-averbacao}

### Sucesso na averbação

Em caso de sucesso na averbação o parceiro receberá o seguinte webhook:

webhook_type
credit_operation.collateral

collateral_constituted
True

**Webhook Body**

```json
{
  "webhook": {
    "key": "<UUID>",
    "data": {
      "collateral_data": {},
      "collateral_type": "private_payroll",
      "collateral_constituted": true
    },
    "event_time": "2025-07-10 02:15:01",
    "webhook_type": "credit_operation.collateral"
  }
}
```

:::info Averbação sem sucesso na primeira tentativa?
Se a averbação falhar, o parceiro recebe um webhook diferente do de sucesso acima — ver [Erros de Averbação](/documentation/manual_consignado_privado/averbacao_novos_emprestimos/erros).
:::

---

# Manual Consignado Privado - Averbação de Novos Empréstimos: Regras de Negócio

URL: /documentation/manual_consignado_privado/averbacao_novos_emprestimos/visao_geral

Este manual documenta a **colateralização da dívida** de um consignado privado no momento da contratação: a reserva de margem na folha de pagamento do empregador (averbação), realizada junto à DATAPREV, e o ciclo de vida dessa tentativa — da criação da garantia até a confirmação de sucesso ou o esgotamento das retentativas em caso de falha.

:::info Vínculo terminou depois de averbado?
Este manual cobre a averbação de um contrato **novo**. Para o que acontece quando o vínculo empregatício do trabalhador termina e a dívida precisa ser transferida para o novo emprego, veja [Movimentação de Vínculos](/documentation/manual_consignado_privado/vinculos_empregaticios/visao_geral).
:::

## Quando usar

Use esta referência para desenhar a esteira de **emissão** de um consignado privado, entendendo:

- Como e quando a garantia (`reservation`) é efetivamente constituída após a contratação.
- O que fazer quando o parceiro precisa autorizar a averbação manualmente.
- Como interpretar e reagir aos motivos de falha retornados pela DATAPREV — assunto do foco desta seção, detalhado em [Erros de Averbação](/documentation/manual_consignado_privado/averbacao_novos_emprestimos/erros).

## A entidade reservation

Após a formalização de uma nova contratação de consignado privado, é criada a entidade `reservation`, responsável por:

- Acompanhar as tentativas de averbação do contrato junto à DATAPREV (o registro do desconto na folha de pagamento do empregador).
- Gerir a garantia após a averbação ser aceita — é a partir da averbação bem-sucedida que a garantia passa a estar de fato constituída (`collateral_constituted: true`), e não antes. Até esse momento, o que existe é apenas uma **tentativa** registrada, não uma garantia real.

### Máquina de estados de um contrato novo

![Máquina de estados de um contrato novo](/img/diagrams/manual-consignado-privado-manual-vinculos-empregaticios-1.svg)

## Autorização pendente ou fila de averbação

No **fluxo ativo**, o ambiente pode ser configurado para que a averbação seja criada em um status pendente de autorização (`pending_requester_authorization`) ou diretamente na fila de averbação (`pending_reservation`) — esta configuração deve ser alinhada com o time de operações. No **fluxo de leilão**, a averbação é sempre criada pendente de autorização.

O endpoint de autorização (identificando a operação pela `external_key`) e os detalhes de request/response estão em [Autorização e Averbação](/documentation/manual_consignado_privado/averbacao_novos_emprestimos/tecnico#1-autorizacao).

:::info Autorizando um revínculo?
A autorização de um **revínculo** (reaverbação em um novo vínculo empregatício) usa um endpoint próprio, identificado pela `reservation_key` — ver [Movimentação de Vínculos — Averbação por Revínculo](/documentation/manual_consignado_privado/vinculos_empregaticios/revinculo).
:::

## Consulta de averbação e comprovantes

Além dos webhooks, é possível consultar a qualquer momento os dados de uma averbação específica pela `external_key` da operação — inclusive os **comprovantes de averbação e desaverbação da dívida**, disponíveis no objeto `protocols` da resposta. Também existe uma consulta paginada, para acompanhar várias reservas de uma vez sem precisar conhecer a `external_key` de cada uma. Ambas estão documentadas em [Consulta de Reservas](/documentation/manual_consignado_privado/averbacao_novos_emprestimos/consultas).

## Averbação: sucesso, falha e "teimosinha"

Uma tentativa de averbação pode ter sucesso ou falhar de acordo com a crítica devolvida pela DATAPREV. Esse retorno determina o que a QI Tech faz a seguir:

- **Falha transitória** (ex.: margem consignável momentaneamente insuficiente, ou taxa em conflito com uma proposta ativa do trabalhador no app CTPS) — a QI mantém a operação em **retentativa automática** ("teimosinha"), tentando novamente a averbação até que ela seja aceita ou até que as opções de desembolso se esgotem.
- **Falha terminal** (ex.: quantidade máxima de contratos por vínculo excedida, ou vínculo bloqueado pelo próprio trabalhador) — a operação é cancelada, pois não há expectativa de que uma nova tentativa tenha resultado diferente sem uma ação externa (o trabalhador desbloquear o vínculo, por exemplo).

A lista completa de motivos de falha, o webhook dedicado que os notifica de forma estruturada, e a classificação de cada motivo entre retentável e terminal estão detalhados em **[Erros de Averbação](/documentation/manual_consignado_privado/averbacao_novos_emprestimos/erros)** — o foco principal desta seção do manual.

## Conteúdo desta seção

1. **[Autorização e Averbação](/documentation/manual_consignado_privado/averbacao_novos_emprestimos/tecnico)** — página técnica: endpoint de autorização por `external_key` e webhook de sucesso na averbação.
2. **[Erros de Averbação](/documentation/manual_consignado_privado/averbacao_novos_emprestimos/erros)** — foco nos possíveis erros: o webhook dedicado de falha, a lógica de retentativa ("teimosinha") vs. cancelamento, e a tabela de motivos retornados pela DATAPREV.
3. **[Consulta de Reservas](/documentation/manual_consignado_privado/averbacao_novos_emprestimos/consultas)** — consulta por operação (com os comprovantes de averbação/desaverbação em `protocols`) e consulta paginada de reservas por filtros (documento, tipo e status).
4. **[Enumeradores](/documentation/manual_consignado_privado/averbacao_novos_emprestimos/enumeradores)** — status e método de averbação da reserva.

## Glossário

| Termo | Significado |
|---|---|
| **`reservation`** | Entidade que acompanha as tentativas de averbação de um contrato na DATAPREV e a gestão da garantia (margem reservada) após a averbação. |
| **Averbação** | Reserva da margem consignável na folha de pagamento do empregador, garantindo o desconto das parcelas. |
| **Desaverbação** | Liberação da margem previamente reservada. |
| **"Teimosinha"** | Retentativa automática de averbação feita pela QI Tech quando a tentativa falha por um motivo não terminal. |
| **`private_payroll`** | `collateral_type` da garantia de folha de pagamento de funcionários de empresas privadas. |

---

# Manual Consignado Privado - Formalização Externa

URL: /documentation/manual_consignado_privado/manual_assinatura_externa

:::info Navegação
- [Emissão e Formalização](/documentation/manual_consignado_privado/manual_credito_novo) (anterior)
- [Averbação e Desembolso](/documentation/manual_consignado_privado/manual_averbacao_desembolso) (próximo)
:::

:::caution API em desenvolvimento 
A API ainda está em fase de desenvolvimento, sendo assim, este manual esta sujeito a alterações.
:::

Nesta seção, você encontrará as orientações necessárias para utilizar as APIs de formalização de operações originadas no fluxo ativo sem o uso do QIsign, a solução de assinatura eletrônica da QI Tech. 

Este fluxo é destinado a clientes que optam por utilizar uma solução externa de assinatura eletrônica (como DocuSign, Clicksign, entre outras) para formalizar seus contratos.

## 1 - Envio de documentos

É obrigatório o envio dos dados complementares do contrato.

Os documentos devem ser enviados através do [endpoint de upload de documentos](../upload_de_documentos) e devem seguir a seguinte formatação:

| Validações     | Valores      |
|----------------|--------------|
| Formato        | JPEG         |
| Tamanho mínimo | 250 x 250 px |

Após o upload dos documentos, as chaves dos documentos enviados devem ser informadas no payload de criação da operação ou após, através do seguinte endpoint:

ENDPOINT /debt/ DEBT-KEY /related_party/ RELATED-PARTY-KEY /attached_document
MÉTODO POST

Testar no Playground

Request Body

```json
{
    "document_identification": "2893fc74-88fd-4cc9-a5c6-8a63d9d00f41",
    "document_identification_back": "e881ddf4-bc9a-48e0-9555-cac979f65431",
    "selfie": "ca37979e-6f11-4465-bf3b-69cd8307549c"
}
```

:::info Informação
A **related_party_key** é retornada na response da criação de dívida dentro do objeto **borrower**
:::

## 2 - Formalização da operação

Após o input dos documentos a operação pode seguir para formalização.

No caso de assinatura por parte do representante legal, no campo "**data.contract.signers[i]**" serão retornados os dados do representante legal, e o valor do objeto "**data.contract.signers[i].signer_role**" será "**issuer_legal_representative**".

**No payload de assinatura devem conter os campos obrigatórios relacionados aos documentos enviados no item 1. Os campos obrigatórios são os seguintes: _ip_address_ e _signature_datetime_.**

### Request

ENDPOINT /debt/ DEBT-KEY /signed
MÉTODO POST

Testar no Playground

#### **EXEMPLOS DE PAYLOAD**
Request Body - PDF Assinado

```json
{
    "path-pdf-signed": "https://storage.googleapis.com/sandbox-doc-api-private/documents/8b740ca1-405d-4507-a7b3-e7de01c4e008/BENJAMINERAPHAELA-NOME_DEVEDOR-CCB-LCM3307596554-20250721184150_signed.pdf",
    "type": "pdf-signature",
    "biometry_analysis_reference": "serpro",
    "similarity_score": "0.96",
    "ip_address": "192.168.0.0",
    "signature_datetime": "2025-07-22T14:30:12.729Z"
}
```

Request Body - Assinatura Por Evidências

```json
{
    "biometry_analysis_reference": "serpro",
    "signature_datetime": "2025-07-21T10:38:23.382748Z",
    "similarity_score": 0.98,
    "ip_address": "179.104.42.245",
    "type": "data-signature",
    "signatures": [
        {
            "authenticity": {
                "timestamp": "2025-07-21 10:38:23",
                "ip_address": "179.104.42.245",
                "session_id": "ddb1d063-4fdf-4330-af9c-3316e9142ff3"
            },
            "signer": {
                "name": "Nome devedor",
                "email": "naotem@gmail.com",
                "phone": {
                    "country_code": "055",
                    "area_code": "84",
                    "number": "999538380"
                },
                "document_number": "11200770870"
            },
            "authentication_type": "opt-in"
        }
    ]
}
```

:::caution Atenção
O payload de envio da assinatura varia de acordo com o processo de formalização do parceiro e deve ser alinhado com o time de integração da QI Tech.
:::

#### Enumeradores _Biometry Analysis Reference_
| Enumerador    | Descrição                                                                                                                                                                                                                                                          |
|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **serpro**    | Utilizado quando o similarity_score for retornado através de consulta realizada na base de documentos com foto do Detran (Serviço prestado através da Serpro)                                                                                                      |
| **tse**       | Utilizado quando o similarity_score for retornado através de consulta realizada na base de documentos com foto do TSE                                                                                                                                              |
| **not_found** | Deve ser informado quando a biometria facial não for localizada em nenhuma das bases governamentais anteriores (serpro ou tse). Neste caso o similarity_score deve ser null ou o grau de similaridade da selfie com o documento oficial com foto, retornado pelo parceiro. |

---

# Manual Consignado Privado - Acompanhamento da Operação de crédito

URL: /documentation/manual_consignado_privado/manual_assinatura_leilao

## 1. Formalização

Após vencer o leilão interno, o parceiro deve aguardar o recebimento do webhook de formalização, indicando que o tomador finalizou o fluxo de assinatura do QI Sign.

```json
{
    "key": "<credit_operation_key>",
    "status": "signed",
    "signers": [
        {
            "id": "3271efd3-89ba-43aa-b032-af9a459e6096",
            "images": {
                "face_image_url": "https://qisign-face-images-bucket-sandbox.s3.amazonaws.com/fad7f924-d210-4ec4-9565-a57662a0a65a.jpeg",
                "document_back_url": "https://qisign-personal-documents-bucket-sandbox.s3.amazonaws.com/8c7b68ba-07ad-4188-82ae-679833b2843b.jpeg",
                "document_front_url": "https://qisign-personal-documents-bucket-sandbox.s3.amazonaws.com/f63cd291-5668-4926-be5d-9290aeda3f6e.jpeg",
                "document_back_template": "cnh_back",
                "document_front_template": "cnh_front"
            },
            "biometry": {
                "face_validation": {
                    "score": 80,
                    "provider": "qitech",
                    "available": true
                },
                "fraud_base_flag": false
            },
            "document": {
                "template": "cnh_front",
                "face_match_score": 100
            },
            "liveness": {
                "result": "live"
            },
            "signed_at": "2025-04-09T19:59:39Z",
            "ip_address": "182.224.219.198",
            "signer_data": {
                "name": "Nome Trabalhador",
                "email": "exemplo@qitech.com.br",
                "phone": {
                    "number": "829549234",
                    "area_code": "11",
                    "international_dial_code": "55"
                },
                "address": {
                    "uf": "SP",
                    "city": "Sao Paulo",
                    "number": "123",
                    "street": "Rua tal do sal",
                    "complement": "Ap 23",
                    "postal_code": "00000-000",
                    "neighborhood": "Pinheiros"
                },
                "pix_key": "pix03@pix03.com",
                "birthdate": "1996-03-13",
                "document_number": "504.856.400-66",
                "document_submission_method": "email",
                "authentication_submission_method": "sms"
            }
        }
    ],
    "webhook_type": "laas.credit_operation.status_change",
    "event_datetime": "2025-04-09 20:00:19",
    "signed_contract_url": "https://storage.googleapis.com/sandbox-doc-api/documents/9b55450e-fca5-44f2-9118-5851ed4bd92e/RESTAURANTEBEBBER-TRABALHADOR_SICQ-CCB-0000195364-2230409195718_signed.pdf"
}
```

Em casos de falha na assinatura, o parceiro irá receber um webhook neste modelo.

```json
{
  "key": "e8e28023-fa00-4d12-a410-ede4157957ea",
  "data": {
    "cancel_reason": "Validação facial não alcançou a pontuação mínima permitida",
    "cancel_reason_enumerator": "face_validation_score"
  },
  "status": "canceled",
  "webhook_type": "laas.credit_operation.status_change",
  "event_datetime": "2025-11-28 17:35:07"
}
```

## 2. Confirmação da proposta

Um segundo webhook é enviado informando que a operação está aguardando a chamada de autorização de averbação.

WEBHOOK TYPE
laas.private_payroll.reservation_status_change

**Webhook Body**

```json
{
    "webhook_type": "laas.private_payroll.reservation_status_change",
    "data": {
        "reservation_status": "pending_requester_authorization",
        "reservation_type": "new_credit"
    },
    "key": "<credit_operation_key>",
    "event_datetime": "2025-04-09T20:00:20Z",
    "status": "pending_requester_authorization"
}
```

Neste momento o parceiro pode tomar a decisão de seguir com o desembolso da opreração ou cancelar a proposta:

### Autorizar Averbação

Para seguir com a averbação, deve ser realizada a chamada:

#### Request

**PATCH**
/private_payroll/reservation/external_key/ EXTERNAL-KEY /authorize

Testar no Playground

#### Response

STATUS
**202** (OK)

**Response Body**

```json
{
    "reservation_key": "<credit_operation_key>",
    "document_number": "12345678901",
    "registration_number": "99999999999-A", 
    "employer_document_number": "12345678901234",
    "external_key": "abc123def456",
    "contract_number": "2024001234",
    "inclusion_date": "2024-03-18",
    "disbursement_date": "2024-03-20",
    "contract_data": {
        "amount": 5000.00,
        "installments": 12,
        "interest_rate": 0.018
    },
    "reservation_data": {
        "installment_value": 500.00,
        "margin_value": 450.00
    },
    "reservation_status": "authorized"
}
```

### Cancelar operação
Para não prosseguir com a averbação, é necessário cancelar a operação.

Se a operação foi originada via leilão, isto pode ser feito através do endpoint de cancelamento permanente, da mesma forma que é feito no item [6 - Desaverbação](#desaverbacao).

Se a operação foi originada no fluxo ativo, o cancelamento deverá ser feito através do endpoint de que consta [neste manual](./manual_averbacao_desembolso.md).

:::info Importante
O campo `external_key` é o UUID da operação de crédito, o mesmo que `debt_key` e `credit_operation_key`.
:::

## 3 - Averbação

### Sucesso na averbação

Em caso de sucesso na averbação o parceiro receberá o seguinte webhook:

WEBHOOK TYPE
laas.private_payroll.reservation_status_change

STATUS
reserved

**Webhook Body**

```json
{
    "webhook_type": "laas.private_payroll.reservation_status_change",
    "data": {
        "reservation_status": "reserved",
        "reservation_type": "new_credit",
        "warranty" : {
            "severance_pay_rate":null,
            "severance_fine":5522.06,
            "fgts_balance":10000
        }
    },
    "key": "<credit_operation_key>",
    "event_datetime": "2025-04-09T20:00:20Z",
    "status": "reserved"
}
```

### Falha na averbação

Caso haja uma falha na averbação, será enviado um webhook com a crítica da DATAPREV. Dependendo do erro de averbação, a QI manterá a proposta em "teimosinha" fazendo novas tentativas de averbação até que a operação seja cancelada manualmente ou por esgotar as opções de desembolso. O webhook e a tabela completa de motivos de falha estão documentados em [Averbação de Novos Empréstimos — Erros de Averbação](/documentation/manual_consignado_privado/averbacao_novos_emprestimos/erros).

## 4 - Desembolso

Após o sucesso na averbação, a operação seguirá automaticamente para o desembolso.

### Sucesso no desembolso

WEBHOOK TYPE
laas.credit_operation.status_change

STATUS
opened

**Webhook Body**

```
{
  "webhook": {
    "key": "b0e263d0-3f78-4d40-835d-225321cbc0db",
    "data": {
      "installments": [
        {
          "due_date": "2026-04-28",
          "total_amount": 2723.11,
          "installment_key": "05d3f492-bb09-4b2f-9d6a-a2d8890fcfe8",
          "pre_fixed_amount": 2723.11,
          "installment_number": 1,
          "principal_amortization_amount": 0.0
        },
        {
          "due_date": "2026-05-28",
          "total_amount": 2723.11,
          "installment_key": "2c90a77e-2aac-4b18-a092-6435615cc99b",
          "pre_fixed_amount": 1974.82423911,
          "installment_number": 2,
          "principal_amortization_amount": 748.28576089
        },
        {
          "due_date": "2026-06-28",
          "total_amount": 2723.11,
          "installment_key": "746b1034-c4cf-4388-8a80-9dcea92550c5",
          "pre_fixed_amount": 1362.47207785,
          "installment_number": 3,
          "principal_amortization_amount": 1360.63792215
        },
        {
          "due_date": "2026-07-28",
          "total_amount": 2723.11,
          "installment_key": "caffce5c-0b8b-419c-bb66-3419ad9d8cf0",
          "pre_fixed_amount": 1223.14316953,
          "installment_number": 4,
          "principal_amortization_amount": 1499.96683047
        },
        {
          "due_date": "2026-08-28",
          "total_amount": 2723.11,
          "installment_key": "63bf5117-7d44-4a7c-9ac8-a061f769b477",
          "pre_fixed_amount": 1158.2555271,
          "installment_number": 5,
          "principal_amortization_amount": 1564.8544729
        },
        {
          "due_date": "2026-09-28",
          "total_amount": 2723.11,
          "installment_key": "0c99c88e-b510-432d-ad8b-661a1bb2da1d",
          "pre_fixed_amount": 1046.54167269,
          "installment_number": 6,
          "principal_amortization_amount": 1676.56832731
        },
        {
          "due_date": "2026-10-28",
          "total_amount": 2723.11,
          "installment_key": "64240d5f-6413-4119-b527-636080a81fb2",
          "pre_fixed_amount": 895.94579894,
          "installment_number": 7,
          "principal_amortization_amount": 1827.16420106
        },
        {
          "due_date": "2026-11-28",
          "total_amount": 2723.11,
          "installment_key": "0e73e4f3-71f9-429d-8e9c-5ef41702db83",
          "pre_fixed_amount": 796.41268475,
          "installment_number": 8,
          "principal_amortization_amount": 1926.69731525
        },
        {
          "due_date": "2026-12-28",
          "total_amount": 2723.11,
          "installment_key": "1410ad56-890f-49b3-85e5-b8eb95b54910",
          "pre_fixed_amount": 636.89650888,
          "installment_number": 9,
          "principal_amortization_amount": 2086.21349112
        },
        {
          "due_date": "2027-01-28",
          "total_amount": 2723.11,
          "installment_key": "08364a82-e805-4446-91ec-df982815a676",
          "pre_fixed_amount": 509.93381955,
          "installment_number": 10,
          "principal_amortization_amount": 2213.17618045
        },
        {
          "due_date": "2027-02-28",
          "total_amount": 2723.11,
          "installment_key": "fdad3297-a729-4603-8d42-ed30604d93a3",
          "pre_fixed_amount": 351.93673682,
          "installment_number": 11,
          "principal_amortization_amount": 2371.17326318
        },
        {
          "due_date": "2027-03-28",
          "total_amount": 2723.11,
          "installment_key": "a3d78a2e-01e9-4c04-8cea-3106a52e5b54",
          "pre_fixed_amount": 164.42776478,
          "installment_number": 12,
          "principal_amortization_amount": 2558.68223522
        }
      ],
      "disbursement_type": "pix",
      "transaction_receipts": [
        {
          "fee": 0,
          "url": {url},
          "amount": 19316.77,
          "origin": {
            "name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
            "type": "payment_account",
            "branch": "0001",
            "document": "32402502000135",
            "bank_code": "329",
            "account_key": "18bd2ed6-bca7-4cc8-806c-a45a8d9ae804",
            "branch_digit": null,
            "account_digit": "7",
            "account_branch": "0001",
            "account_number": "8022858",
            "financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A."
          },
          "timestamp": "2026-02-18T14:23:25",
          "description": "60701190 5807 20467-1 24182533410 - Mock Person Name",
          "destination": {
            "name": "Mock Person Name",
            "type": "checking_account",
            "branch": "5807",
            "purpose": "Crédito PIX em Conta",
            "document": "12345678909",
            "bank_ispb": "60701190",
            "branch_digit": null,
            "account_digit": "1",
            "account_number": "20467",
            "financial_institution_name": "ITAÚ UNIBANCO S.A."
          },
          "end_to_end_id": "E324025022026021814222AHLHi3btjz",
          "transaction_key": "000531c1-ecb7-47f8-947f-51e467bd58b7",
          "origin_transaction_key": "4600743f-13e3-47d2-a8c1-2a71c097409a"
        }
      ],
      "requester_identifier_key": "b0e263d0-3f78-4d40-835d-225321cbc0db"
    },
    "status": "opened",
    "webhook_type": "laas.credit_operation.status_change",
    "event_datetime": "2026-02-18 14:23:24"
  }
}
```

### Falha no desembolso

WEBHOOK TYPE
laas.credit_operation.status_change

STATUS
canceled

**Webhook Body**

```
{
    "key": "<UUID>",
    "data": {
      "cancel_reason": "A conta de destino encontra-se bloqueada.",
      "cancel_reason_enumerator": "blocked_account"
    },
    "status": "canceled",
    "webhook_type": "laas.credit_operation.status_change",
    "event_datetime": "2025-10-12 09:54:46"
}
```

:::danger FALHA NO DESEMBOLSO
Caso haja uma falha no desembolso, é crítico que haja uma atuação na proposta, pois a margem não é desaverbada automaticamente.

É necessário que o parceiro tome a decisão de entrar em contato com o tomador para pedir uma atualização dos dados bancários assim sendo possível [reapresentar a o pagamento da dívida](#reapresentacao), ou que o parceiro realize a chamada de [cancelamento permanente](#desaverbacao) da dívida para desaverbar a margem consignável.
:::

## 5 - Reapresentação da pagamento {#reapresentacao}

Para retentar o desembolso da dívida, deve ser realizada a chamada a seguir atualizando tanto a data de desembolso quanto os dados bancários (caso a retentativa seja na mesma conta bancária, pode ser enviado somente o parâmetro de data de desembolso).

Os possíveis payloads de conta de desembolso constam no página de [exemplos de payload de desembolso](/documentation/emissao_de_divida/emissao/exemplo_payloads_desembolso).
Para essa API, foi alterado o nome do payload de disbursement_bank_accounts para disbursement_account. 

Para reapresentar uma dívida deve-se realizar uma requisição utilizando a auction_proposal_key.
ENDPOINT - `/private_payroll_auction/auction_proposal/{auction_proposal_key}/change_disbursement_date`
MÉTODO - `PATCH`

Testar no Playground

```json
{
    "disbursement_date": "2025-12-12",
    "disbursement_account": {
        "document_number": "31233261000185",
        "name": "Jorge Augusto Salgado Salhani",
        "pix_key": "2f205c99-3161-4120-badd-854039d12de6",
        "pix_transfer_type": "key"
    }
}
```

## 6 - Desavebação {#desaverbacao}

Para cancelar permanentemente a operação e desaverbar a margem, deve ser realizada a chamada:

#### Request

ENDPOINT - `/private_payroll_auction/auction_proposal/{auction_proposal_key}/cancel`
MÉTODO - `PATCH`

Testar no Playground

#### Response

STATUS - 202 (Accepted)

Response Body: Proposta cancelada

```json
{
  "auction_proposal_key": "814e7ed3-4080-4cae-a853-8e12812817ea",
  "status": "cancelled"
}
```

:::danger Rotinas Automáticas de Cancelamento permanente
Existem duas rotinas automáticas de cancelamento permanente acionadas pela QI Tech:

1. Esgotamento das opções de desembolso.

Todas as operações que não forem desembolsadas até a data final de desembolso serão caceladas permanentemente no dia seguinte á data final.
Operações originadas via leilão possuem 10 opções de desembolso desde a data do envio da proposta.

2. Operação averbada e não desembolsada depois de 5 dias.

Caso uma operação fique averbada e não desembolsada por 5 dias corridos, ocorrerá o cancelamento permantente.

Webhooks de cancelamento permanente

**Esgotamento das opções de desembolso**

```json
{
    "key": "d7ba5332-3675-12a6-9e07-8afd25ffcfd0",
    "data": {
      "cancel_reason": "Operação não desembolsada já passou da última data de desembolso",
      "cancel_reason_enumerator": "expired_disbursement_date"
    },
    "status": "canceled_permanently",
    "webhook_type": "laas.credit_operation.status_change",
    "event_datetime": "2026-02-12 00:53:16"
}
```
  
**Operação averbada e não desembolsada depois de 5 dias**

```json
{
    "key": "d7ba5332-3675-12a6-9e07-8afd25ffcfd0",
    "data": {
      "cancel_reason": "Operação excedeu o prazo máximo em averbação sem desembolso",
      "cancel_reason_enumerator": "exceeded_max_days_reserved_not_disbursed"
    },
    "status": "canceled_permanently",
    "webhook_type": "laas.credit_operation.status_change",
    "event_datetime": "2026-02-12 00:53:16"
}
```

:::

Em caso de sucesso na alteração será retornado status 200.

STATUS - 200
Caso haja algum erro no formato do payload enviado para a alteração será retornado um erro de schema invalido

STATUS - 400

:::info Consulta de averbação
A consulta dos dados da averbação e dos comprovantes de protocolo de averbação/desaverbação por `external_key` foi movida para [Averbação de Novos Empréstimos — Consulta de Reservas](/documentation/manual_consignado_privado/averbacao_novos_emprestimos/consultas).
:::

## Anexos

### Detalhamento reapresentação de desembolso

|         Campo         |  Tipo   | Descrição| 
|-----------------------|---------|----------|
| `disbursement_date` | string  | Nova data de desembolso no formato YYYY-MM-DD, não obrigatória| 
| `disbursement_account`              | dict  | dados da conta de desembolso, não obrigatório|

### Motivo de falha na averbação {#fail_reservation_reason}

| Enumerador                                                            | Descrição                                                                                                     | Ação QI                                                                         
|------------------------------------------                             |-------------------------------------------------------                                                        |----------
| **monthly_interest_rate_exceeds_active_proposal**                     | Há uma proposta ativa no app da CTPS do tomador enviada pela QI com taxa inferior à da tentativa de averbação | Teimosinha
| **margin_exceeded**                                                   | Margem consignável excedida                                                                                   | Teimosinha
| **allowed_number_of_contracts_exceeded**                              | Quantidade máxima de contratos excedida                                                                       | Cancelamento da operação
| **employment_relationship_blocked**                                   | Vínculo bloqueado pelo tomador (é possível desbloquear pelo app da CTPS)                                      | Cancelamento da operação
| **warranty_exceeded**                                                 | Coberturas disponíveis excedidas                                                                              | Teimosinha
| **invalid_cover_amount**                                              | Valor da cobertura não corresponde ao percentual do valor de emissão esperado                                 | Teimosinha

### Tipos de protocolo {#protocol_type}

| Enumerador                                                            | Descrição                                             
|------------------------------------------                             |-------------------------------------------------------
| **reservation**                                                       | Averbação 
| **documents_inclusion**                                               | Envio de documentos  (processo de enviar os documentos de formalização para DATAPREV)
| **suspension**                                                        | Suspensão                                                                      
| **deletion**                                                          | Exclusão

---

# Manual Consignado Privado - Averbação e Desembolso

URL: /documentation/manual_consignado_privado/manual_averbacao_desembolso

:::info Navegação
- [Formalização Externa](/documentation/manual_consignado_privado/manual_assinatura_externa) (anterior)
:::

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeados de forma estrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

## 1. Confirmação da proposta

No fluxo ativo, é possível configurar o ambiente para que a operação siga para as etapas de averbação e desembolso logo após a finalização da formalização da dívida pelo tomador, caso contrário, será enviado um webhook informando que a operação está aguardando uma chamada de autorização para dar continuidade ao fluxo (esta configuração deve ser alinhada com o time de operações).

### Averbação pendente de autorização

WEBHOOK TYPE
laas.private_payroll.reservation_status_change

**Webhook Body**

```json
{
    "webhook_type": "laas.private_payroll.reservation_status_change",
    "data": {
        "reservation_status": "pending_requester_authorization",
        "reservation_type": "new_credit"
    },
    "key": "<Debt Key>",
    "event_datetime": "2025-04-09T20:00:20Z",
    "status": "pending_requester_authorization"
}
```

Neste momento o parceiro pode tomar a decisão de seguir com o desembolso da opreração ou cancelar a proposta:

### Autorizar Averbação

Para seguir com a averbação, deve ser realizada a chamada:

#### Request

**PATCH**
/private_payroll/reservation/external_key/ EXTERNAL-KEY /authorize

Testar no Playground

#### Response

STATUS
**200** (OK)

**Response Body**

```json
{
    "reservation_key": "<Debt Key>",
    "document_number": "12345678901",
    "registration_number": "99999999999-A", 
    "employer_document_number": "12345678901234",
    "external_key": "abc123def456",
    "contract_number": "2024001234",
    "inclusion_date": "2024-03-18",
    "disbursement_date": "2024-03-20",
    "contract_data": {
        "amount": 5000.00,
        "installments": 12,
        "interest_rate": 0.018
    },
    "reservation_data": {
        "installment_value": 500.00,
        "margin_value": 450.00
    },
    "reservation_status": "authorized"
}
```

### Cancelar operação
Para não prosseguir com a averbação, é necessário cancelar a operação.

Se a operação foi originada no fluxo ativo, isto pode ser feito através do endpoint de cancelamento permanente, da mesma forma que é feito no item [5 - Desaverbação](#desaverbação).

Se a operação foi originada via leilão, o cancelamento deverá ser feito através do endpoint de cancelamento da proposta, conforme documentação do Leilão.

:::info Importante
O campo `external_key` é o UUID da operação de crédito, o mesmo que `debt_key` e `credit_operation_key`.
:::

## 2 - Averbação

### Sucesso na averbação

Em caso de sucesso na averbação o parceiro receberá o seguinte webhook:

WEBHOOK TYPE
laas.private_payroll.reservation_status_change

STATUS
reserved

**Webhook Body**

```json
{
    "webhook_type": "laas.private_payroll.reservation_status_change",
    "data": {
        "reservation_status": "reserved",
        "reservation_type": "new_credit",
        "warranty" : {
            "severance_pay_rate":null,
            "severance_fine":5522.06,
            "fgts_balance":10000
        },
    },
    "key": "<credit_operation_key>",
    "event_datetime": "2025-04-09T20:00:20Z",
    "status": "reserved"
}
```

### Falha na averbação

Caso haja uma falha na averbação, será enviado um webhook com a crítica da DATAPREV. Dependendo do erro de averbação, a QI manterá a proposta em "teimosinha" fazendo novas tentativas de averbação até que a operação seja cancelada manualmente ou por esgotar as opções de desembolso. O webhook e a tabela completa de motivos de falha estão documentados em [Averbação de Novos Empréstimos — Erros de Averbação](/documentation/manual_consignado_privado/averbacao_novos_emprestimos/erros).

## 3 - Desembolso

Após o sucesso na averbação, a operação seguirá automaticamente para o desembolso.

### Sucesso no desembolso

WEBHOOK TYPE
debt

STATUS
disbursed

**Webhook Body**

```
 {
    "key": "8351238-1272-46b2-292b-7161a05c5161",
    "data": {
      "installments": [
        {
          "due_date": "2026-04-28",
          "total_amount": 180.75,
          "installment_key": "6286548-015a-4f26-8fb5-0d23f34554e",
          "pre_fixed_amount": 180.75,
          "installment_number": 1,
          "principal_amortization_amount": 0.0
        },
        {
          "due_date": "2026-05-28",
          "total_amount": 180.75,
          "installment_key": "b3e719e6-24fc-4ddf-a8b8-ee9012342ba6",
          "pre_fixed_amount": 180.75,
          "installment_number": 2,
          "principal_amortization_amount": 0.0
        },
        {
          "due_date": "2026-06-28",
          "total_amount": 180.75,
          "installment_key": "3652fb45-4304-4f8e-84ff-1234307042cc",
          "pre_fixed_amount": 180.75,
          "installment_number": 3,
          "principal_amortization_amount": 0.0
        },
        {
          "due_date": "2026-07-28",
          "total_amount": 180.75,
          "installment_key": "7e2d4334-b963-4a77-1234-4e4fcb1986f8",
          "pre_fixed_amount": 180.75,
          "installment_number": 4,
          "principal_amortization_amount": 0.0
        },
        {
          "due_date": "2026-08-28",
          "total_amount": 180.75,
          "installment_key": "a1ab6f5b-321b-41a0-a608-0eb54a261014",
          "pre_fixed_amount": 180.75,
          "installment_number": 5,
          "principal_amortization_amount": 0.0
        },
        {
          "due_date": "2026-09-28",
          "total_amount": 180.75,
          "installment_key": "7d423192-10d4-45c6-8353-7c3be28ee368",
          "pre_fixed_amount": 180.75,
          "installment_number": 6,
          "principal_amortization_amount": 0.0
        }
      ],
      "ted_receipt_list": [
        {
          "fee": 0,
          "url": "[URL]",
          "amount": 2444.15,
          "origin": {
            "name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
            "type": "payment_account",
            "branch": "0001",
            "document": "32402502000135",
            "bank_code": "329",
            "account_key": "65463575-3456-4345-9787-146868523667",
            "branch_digit": null,
            "account_digit": "1",
            "account_branch": "0001",
            "account_number": "0000025",
            "financial_institution_name": "QI SCD S.A."
          },
          "timestamp": "2026-01-29T20:03:44",
          "description": "12431420 0134 71234489-3 99999999999 - Lucas Blau Mattos",
          "destination": {
            "name": "Lucas Blau Mattos",
            "type": "checking_account",
            "branch": "0001",
            "purpose": "Crédito PIX em Conta",
            "document": "99999999999",
            "bank_ispb": "18236120",
            "branch_digit": null,
            "account_digit": "3",
            "account_number": "71234489",
            "financial_institution_name": "NU PAGAMENTOS - IP"
          },
          "end_to_end_id": "E32402502202601291954msTASDFEGS",
          "transaction_key": "e89dc7af-165d-4534-b345-11345625d2c6",
          "origin_transaction_key": "3415085f-1254-2153-a254-b1254215279e"
        }
      ],
      "requester_identifier_key": "1235cd2f-6345-4025-a334-a1435269fe11"
    },
    "status": "disbursed",
    "webhook_type": "debt",
    "event_datetime": "2026-01-29 20:03:45"
  }
```

### Falha no desembolso

#### TED
Em caso de falha no desembolso via TED

WEBHOOK TYPE
debt

STATUS
canceled

**Webhook Body**

```json
 {
     "key": "<Debt Key>",
     "status": "canceled",
     "webhook_type": "debt",
     "event_datetime": "2025-03-18 16:41:28",
     "data": {
         "ted_refusal": {
             "transaction_key": "16faabfc-3876-437d-a4f6-aae17a1d68c9",
             "description": "341 0000 000000-7 12345678900 - NOME DO EMPREGADO",
             "origin": {
                 "account_key": "a1d2dea5-fa90-4676-a125-da355fdc3ed0",
                 "account_number": "00086",
                 "bank_code": "329",
                 "name": "ACCOUNT TRANSITORY",
                 "type": "payment_account",
                 "document": "32402502000135",
                 "branch_digit": null,
                 "account_digit": "8",
                 "branch": "0001"
             },
             "fee": 0,
             "reason_enumerator": "agencia_conta_invalida",
             "timestamp": "2022-11-07T14:36:05",
             "amount": 483.6,
             "reason": "Agência ou Conta Destinatária do Crédito Inválida",
             "destination": {
                 "branch": "0000",
                 "account_number": "000000",
                 "name": "NOME DO EMPREGADO",
                 "purpose": "Crédito em Conta",
                 "type": "checking_account",
                 "branch_digit": null,
                 "document": "12345678900",
                 "bank_code": "341",
                 "account_digit": "7"
             }
         },
         "cancel_reason": "ted_refusal"
     }
 }
```

#### PIX
Em caso de falha no desembolso via PIX

WEBHOOK TYPE
debt

STATUS
canceled

**Webhook Body**

```json
{
    "key": "<Debt Key>",
    "status": "canceled",
    "webhook_type": "debt",
    "event_datetime": "2025-03-18 16:41:28",
    "data": {
        "cancel_reason": "pix_refusal",
        "pix_refusal": {
            "reason_enumerator": "invalid_document_number",
            "reason": "CPF/CNPJ do usuário recebedor não é compatível com o titular da conta de destino."
        }
    }
}
```

:::danger FALHA NO DESEMBOLSO
Caso haja uma falha no desembolso, é crítico que haja uma atuação na proposta, pois a margem não é desaverbada automaticamente.

É necessário que o parceiro tome a decisão de entrar em contato com o tomador para pedir uma atualização dos dados bancários assim sendo possível [reapresentar a o pagamento da dívida](#reapresentacao), ou que o parceiro realize a chamada de [cancelamento permanente](#desaverbacao) da dívida para desaverbar a margem consignável.
:::

## 4 - Reapresentação de pagamento{#reapresentacao}

Para retentar o desembolso da dívida, deve ser realizada a chamada a seguir atualizando tanto a data de desembolso quanto os dados bancários (caso a retentativa seja na mesma conta bancária, pode ser enviado somente o parâmetro de data de desembolso).

Os possíveis payloads de conta de desembolso constam no página de [exemplos de payload de desembolso](/documentation/emissao_de_divida/emissao/exemplo_payloads_desembolso).

#### Request

**POST**
/debt/ DEBT-KEY /change_disbursement_date

Testar no Playground

### Request

**Request Body**

```json
{
    "disbursement_date": "2025-03-19",
    "disbursement_bank_accounts": [
        {
            "branch_number": "1232",
            "account_digit": "4",
            "account_number": "412412412",
            "account_type": "checking_account",
            "document_number": "<CPF DO TRABALHADOR>",
            "bank_code": 184,
            "ispb_number": "17298092",
            "name": "<NOME DO TRABALHADOR>",
            "percentage_receivable": 100
        }
    ]
}
```

 
### Response

STATUS
**200** OK

**Response Body**

```json
{
    "disbursement_date": "2025-03-19",
    "disbursement_accounts": [
        {
            "account_branch": "1232",
            "account_digit": "4",
            "account_number": "412412412",
            "account_type": "checking_account",
            "amount_receivable": null,
            "created_at": "2022-05-24T14:51:46",
            "digitable_line": null,
            "disbursement_type": "ted",
            "document_number": "37197645832",
            "financial_institutions": {
                "code_number": 184,
                "ispb": 17298092,
                "name": "BCO ITAÚ BBA S.A."
            },
            "financial_institutions_code_number": 184,
            "is_pix_disbursement": false,
            "ispb": "17298092",
            "name": "Márcio e Catarina Gráfica Ltda",
            "percentage_receivable": 50.0,
            "pix_key": null,
            "pix_transfer_key": null,
            "pix_type": null,
            "qr_code_key": null,
            "retry_counter": 0,
            "retry_vector": null,
            "transaction_key": null,
            "webhook_key": null
        }
    ]
}
```

## 5 - Desaverbação {#desaverbacao}

A desaverbação de um contrato é realizada através da rota de cancelamento permanente. Essa rota coloca um status final
no contrato, o qual não é passível de retentativa e dispara a desaverbação da margem averbada.

Para realizar o cancelamento definitivo, deve ser utilizado o seguinte endpoint:

### Request

**POST**
/debt/ DEBT-KEY /cancel_permanently

Testar no Playground

### Webhooks

WEBHOOK TYPE
debt

STATUS
canceled_permanently

**Webhook Body**

```json
{
    "key": "<Debt Key>",
    "status": "canceled_permanently",
    "webhook_type": "debt",
    "event_datetime": "2025-03-18 16:41:28",
    "data": {}
}
```

:::danger Rotinas Automáticas de Cancelamento permanente
Existem duas rotinas automáticas de cancelamento permanente acionadas pela QI Tech:

1. Esgotamento das opções de desembolso.

Todas as operações que não forem desembolsadas até a data final de desembolso serão caceladas permanentemente no dia seguinte á data final.

2. Operação averbada e não desembolsada depois de 5 dias.

Caso uma operação fique averbada e não desembolsada por 5 dias corridos, ocorrerá o cancelamento permantente.

Webhooks de cancelamento permanente

**Esgotamento das opções de desembolso**

```json
{
    "key": "d7ba5332-3675-12a6-9e07-8afd25ffcfd0",
    "data": {
      "cancel_reason": "Operação não desembolsada já passou da última data de desembolso",
      "cancel_reason_enumerator": "expired_disbursement_date"
    },
    "status": "canceled_permanently",
    "webhook_type": "debt",
    "event_datetime": "2026-02-12 00:53:16"
}
```
  
**Operação averbada e não desembolsada depois de 5 dias**

```json
{
    "key": "d7ba5332-3675-12a6-9e07-8afd25ffcfd0",
    "data": {
      "cancel_reason": "Operação excedeu o prazo máximo em averbação sem desembolso",
      "cancel_reason_enumerator": "exceeded_max_days_reserved_not_disbursed"
    },
    "status": "canceled_permanently",
    "webhook_type": "debt",
    "event_datetime": "2026-02-12 00:53:16"
}
```

:::

:::info Consulta de averbação
A consulta dos dados da averbação e dos comprovantes de protocolo de averbação/desaverbação por `external_key` foi movida para [Averbação de Novos Empréstimos — Consulta de Reservas](/documentation/manual_consignado_privado/averbacao_novos_emprestimos/consultas).
:::

## Anexos
---

### Motivo de falha na averbação {#fail_reservation_reason}

| Enumerador                                                            | Descrição                                                                                                     | Ação QI                                                                         
|------------------------------------------                             |-------------------------------------------------------                                                        |----------
| **monthly_interest_rate_exceeds_active_proposal**                     | Há uma proposta ativa no app da CTPS do tomador enviada pela QI com taxa inferior à da tentativa de averbação | Teimosinha
| **margin_exceeded**                                                   | Margem consignável excedida                                                                                   | Teimosinha
| **allowed_number_of_contracts_exceeded**                              | Quantidade máxima de contratos excedida                                                                       | Cancelamento da operação
| **employment_relationship_blocked**                                   | Vínculo bloqueado pelo tomador (é possível desbloquear pelo app da CTPS)                                                                       | Cancelamento da operação

### Tipos de protocolo {#protocol_type}

| Enumerador                                                            | Descrição                                             
|------------------------------------------                             |-------------------------------------------------------
| **reservation**                                                       | Averbação 
| **documents_inclusion**                                               | Envio de documentos  (processo de enviar os documentos de formalização para DATAPREV)
| **suspension**                                                        | Suspensão                                                                      
| **deletion**                                                          | Exclusão

---

# Manual Consignado Privado - Configuração dos Filtros de Recebimento de Propostas de Leilão

URL: /documentation/manual_consignado_privado/manual_configuracao_filtros

## Introdução

O Fluxo de emissão das operações via leilão se inicia no momento em que um tomador solicita um empréstimo no app da CTPS digital, a QI Tech consulta todas as solicitações realizadas periodicamente e, para cada pedido, abre um leilão interno de propostas de empréstimo notificando os parceiros via webhook.
Neste manual estão os endpoints necessários para configurar os filtros de solicitação que possibilitam controlar o público alvo da operação.

## Modificando regras de filtragem

ENDPOINT - `/private_payroll_auction/requester_configuration/custom_data`
MÉTODO - `PATCH`

Testar no Playground

Nessa requisição existem dois tipos de campos passiveis de serem alterados; O status do cliente e os filtros do cliente. Em relação ao status do cliente, pode ser alterado entre [ativo e inativo](#status_do_cliente), sinalizando se o cliente deseja ou não receber novas solicitações de leilão. 

```json
{
    "status": "active"
}
```

O campo [custom_data](#custom_data_params) contêm os filtros de fato. Nele devem ser enviados todos os campos de filtragem como no exemplo abaixo:
```json

```

:::warning 
cada campo deve ter obrigatoriamente as chaves min e max, com exceção do received_daily_proposals, days_since_employmente e alert_preferences.
*OBS: Todos os campos de custom data devem ser enivados, mesmo que não seja necessário mudar todos os valores. Além disso, o envio de todas as chaves min/max é obrigatório, sendo passado 'null' caso não seja necessário utilizar esse filtro*.
:::

### Exemplo de [Body](#custom_data_payload)

```json
{
  "custom_data": {
        "disbursed_issue_amount": {"min": null, "max": null},
        "number_of_installments": {"min": 12, "max": 24},
        "consigned_credit_balance": {"min": null, "max": null},
        "days_since_employment": {"min": null},
        "age": {"min": null, "max": 60},
        "received_daily_proposals": {"max": null},
        "alert_preferences": {
          "default": "acknowledge",
          "leave": "acknowledge",
          "termination": "ignore"
        },
        "allowed_employer_document_types": [
          "cpf",
          "cnpj"
        ],
       "allowed_political_exposures": [
         "not_exposed",
         "level_1",
         "level_2"
       ]
      }
}
```

### Response

STATUS - 201 (Accepted)

Response Body: Configuração Atualizada

```json
{
    "status": "active",
    "custom_data": {
        "disbursed_issue_amount": {"min": 1000, "max": null},
        "number_of_installments": {"min": 12, "max": 24},
        "consigned_credit_balance": {"min": 200, "max": null},
        "days_since_employment": {"min": null},
        "age": {"min": null, "max": 60},
        "received_daily_proposals": {"max": 1000},
    }
}
```

## Adicionando CNPJs de filtragem

Para clientes que desejam receber solicitações apenas de funcionários de CNPJs específicos, existe a opção de adicionar esses CNPJs em lote:
ENDPOINT - `/private_payroll_auction/requester_configuration/related_employer`
MÉTODO - `POST`

Testar no Playground

:::caution Atenção!
A DATAPREV somente opera com a raíz dos CNPJs, portanto para a filtragem a partir do documento do empregador devem ser enviados **apenas os 8 primeiros dígitos do CNPJ**.
:::

### [Body](#employer_payload)
```json
{
  "employer_document_numbers": [
    "01234567",
    "12345678"
  ]
}
```

**A [lista](#employer_payload) pode conter no máximo 100 CNPJs.**

### Response

STATUS - 201
Response Body: CNPJs adicionados

```json
{
  "employer_document_numbers": [
    "01234567",
    "12345678"
  ]
}
```
:::info Observação
Apenas os CNPJs efetivamente adicionados serão retornados. No caso em que um CNPJ já tenha sido cadastrado, não será retornado na lista da resposta. Caso nenhum CNPJ seja adicionado será retornada uma lista vazia.
:::

## Removendo CNPJs de filtragem

ENDPOINT - `/private_payroll_auction/requester_configuration/remove_related_employers`
MÉTODO - `POST`

Testar no Playground

### [Body](#employer_payload)
```json
{
  "employer_document_numbers": [
    "01234567",
    "12345678"
  ]
}
```
**Os CNPJs devem ser enviado apenas com os 8 primeiros dígitos e a lista pode conter no máximo 100 CNPJs.**

### Response

STATUS - 200
Response Body: CNPJ removidos

```json
{
    "employer_document_numbers": ["01234567", "12345678"]
}
```

## Buscando CNPJs de filtragem

Para consultar os CNPJs cadastrados como filtros para um solicitante, utilize o endpoint abaixo com suporte a paginação.

### Endpoint

ENDPOINT - `/private_payroll_auction/requester_configuration/related_employers`
MÉTODO - `GET`

Testar no Playground

### Query Params

| Campo         | Tipo | Descrição                          | Padrão |
|---------------|------|------------------------------------|--------|
| `page_number` | int  | Número da página atual             | 1      |
| `page_rows`   | int  | Quantidade de registros por página | 100    |

### Exemplo de Resposta - 200

```json
{
  "data": [
    {
      "employer_document_number": "01234567"
    },
    {
      "employer_document_number": "12345678"
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": 2,
    "rows_per_page": 2,
    "total_pages": 3,
    "total_rows": 6
  }
}
```

## Anexos

### Detalhamento do Payload de Alteração de Regras de Filtragem {#custom_data_payload}

| Campo         | Tipo      | Descrição                             | Obrigatório   |
|---------------|--------   |---------------------------------------|------------   |
| `status`      | string    | novo status do cliente                | Não           |
| `custom_data` | dict      | Novos filtros para o cliente          | Não           |

### Status do Cliente {#status_do_cliente}

| Status        | Descrição                                                                 |
|----------     | ------------------------------------------------------------------------- |
| active        | Cliente deseja receber novas solicitação de proposta no leilão            |
| inactive      | Cliente **Nâo** deseja receber novas solicitações de proposta             |

### Parâmetros do Custom Data {#custom_data_params}

| Campo                       | Tipo  | Descrição                                                               | Obrigatório |
|---------------------------- |-------|-----------------------------------------------------------------------  |--------------|
| `disbursed_issue_amount`    | dict  | Valor do contrato emitido (mínimo e máximo)                             | Sim          |
| `number_of_installments`    | dict  | Número de parcelas (mínimo e máximo)                                    | Sim          |
| `consigned_credit_balance`  | dict  | Saldo de crédito consignado (mínimo e máximo)                           | Sim          |
| `days_since_employment`     | dict  | Dias desde o início do vínculo empregatício (mínimo)                    | Sim          |
| `age`                       | dict  | Idade do proponente (mínimo e máximo)                                   | Sim          |
| `received_daily_proposals`  | dict  | Número de propostas recebidas por dia (máximo)                          | Sim          |
| `alert_preferences`         | dict  | Filtro de pedidos de empréstimo com algum alerta, para detalhamento consulte [Parâmetros alert_preferences](#alert_preferences)| Sim          |

### Parâmetros alert_preferences {#alert_preferences} 

| Campo                       | Tipo    | Descrição                                                                         | Obrigatório  | Enumeradores                                     |
|---------------------------- |-------  |-----------------------------------------------------------------------            |--------------|-------------                                     |
| `default`                   | string  | Comportamento padrão, caso os comportamentos específicos não estejam configurados | Sim          | ignore para não receber, acknowledge para receber|
| `termination`               | string  | Filtro de leads com alerta de desligamento                                        | Não          | ignore para não receber, acknowledge para receber|
| `leave`                     | string  | Filtro de leads com alerta de afastamento                                         | Não          | ignore para não receber, acknowledge para receber|

### Detalhamento do Payload de Adição e Remoção de CNPJs de Filtragem {#employer_payload}

| Campo         | Tipo   | Descrição                              | Obrigatório |
|---------------|--------|----------------------------------------|------------ |
| `employer_document_number` | array de strings  | Lista de raízes de CNPJ (com 8 dígitos cada). Deve conter entre 1 e 100 itens  | Sim         |

---

# Manual Consignado Privado - Consulta de Escriturações

URL: /documentation/manual_consignado_privado/manual_consultas_conciliacao

A escrituração é o processo obrigatório que o setor de Recursos Humanos (RH) ou Departamento Pessoal (DP) da empresa realiza para registrar no sistema governamental (via eSocial) o desconto da parcela de um empréstimo consignado ativo do colaborador em sua folha de pagamento, em essência, a escrituração é a formalização contábil e fiscal do desconto. Após o pagamento do valor formalizado, o valor é direcionado para a Caixa Econômica Federal, que encaminha para a instituição financeira credora.

A escrituração do desconto referente à folha de pagamento da competência deve ser realizada até o dia 15 de cada mês.

## 1 - Consulta de escriturações

**GET**
/private_payroll_conciliation/registers

Testar no Playground

### Query Parameters

| Parâmetro       | Tipo    | Obrigatório | Descrição                                 | Valor Padrão |
|-----------------|---------|-------------|-------------------------------------------|--------------|
| start_date      | date    | Sim         | Data mínima da escrituração (YYYY-mm-dd)  |              |
| end_date        | date    | Sim         | Data máxima da escrituração (YYYY-mm-dd)  |              |
| page_number     | integer | Não         | Número da página a ser retornada          | 1            |
| page_rows       | integer | Não         | Quantidade de registros por página        | 100          |

:::info
A paginação é baseada em um, portanto a primeira página é a página 1.
:::

### Response

STATUS
**200** OK

```json
{
    "data": [
        {
            "register_key": "123e4567-e89b-12d3-a456-426614174000",
            "contract_number": "1234567890",
            "credit_operation_key": "123e4567-e89b-12d3-a456-426614174000",
            "amount": 2405.76,
            "reference_month": "2024-07",
            "external_reference_month": "2024-06",
            "document_number": "29883927061",
            "employer_document_number": "12345678",
            "registration_number": "11841",
            "registered_at": "2025-08-06T03:49:52Z",
            "register_type":"regular_pay"
        }
    ],
    "pagination": {
        "current_page": 1,
        "next_page": 2,
        "rows_per_page": 100,
    }
}
```
:::warning Atributos da escrituração
Os atributos 'contract_number', 'employer_document_number' e 'registration_number' não coincidem necessariamente com os dados da operação de crédito, pois são referentes aos dados digitados pelo RH do empregador, para associar a escrituração com a operação de crédito deve ser utilizada a chave "credit_operation_key".
:::

### Response Body

A resposta paginada é composta por um array de escriturações (*data*) e um objeto de paginação (*pagination*).

#### Lista de atributos

Descrição dos itens do array *data*:

| Parâmetro                  | Tipo    | Descrição                              |
|----------------------------|---------|----------------------------------------|
| register_key               | string  | Identificacor da escrituração                      |
| contract_number            | string  | Número do contrato escriturado pelo empregador     |
| amount                     | decimal | Valor total da escrituração                        |
| reference_month            | string  | Mês de vencimento no qual a escrituração se refere |
| external_reference_month   | string  | Mês de competência informada pela DATAPREV         |
| registered_at              | string  | Data de escrituração                               |
| document_number            | string  | CPF do cliente                                     |
| employer_document_number   | string  | CNPJ ou CPF do empregador                          |
| registration_number        | string  | Matrícula do funcionário                           |
| credit_operation_key       | string  | Identificador da Operação de crédito               |
| register_type              | string  | Tipo de escrituração, consulte os possíveis enumeradores na tabela [Tipos de escrituração](#register_type)|
| credit_operation_key       | string  | Identificador da Operação de crédito               |

#### Dados de paginação

Dados contidos no objeto *pagination*:

| Parâmetro     | Tipo    | Obrigatório | Descrição                          |
|---------------|---------|-------------|------------------------------------|
| current_page  | integer | Sim         | Página atual                       |
| next_page     | integer | Sim         | Próxima página                     |
| rows_per_page | integer | Sim         | Quantidade de registros por página |

### Tipos de escrituração {#register_type}
ENUMERADOR
register_type
| Enumerador                    | Descrição                         | 
|-------------------------      |-----------------------------------|
|regular_pay                    |Desconto ordinário                 |
|severance_pay                  |Desconto de verba rescisória       |

---

# Manual Consignado Privado - Consultas do Trabalhador

URL: /documentation/manual_consignado_privado/manual_consultas_trabalhador

:::info Navegação
- [Fluxo de Emissão](/documentation/manual_consignado_privado/manual_detalhamento_fluxo_ativo) (anterior)
- [Emissão e Formalização](/documentation/manual_consignado_privado/manual_credito_novo) (próximo)
:::

No início do fluxo ativo de emissão de uma dívida de consignado privado, é necessário realizar duas consultas principais relacionadas ao trabalhador:

1. Consulta de vínculos empregatícios: realizada informando apenas o CPF do trabalhador. Essa operação retorna a lista de vínculos ativos do trabalhador, juntamente com a elegibilidade de cada um para operações de crédito.

2. Consulta de dados do trabalhador: realizada com base em um vínculo específico, informando o número de documento do empregador e o número de matrícula obtidos na consulta de vínculos. Essa operação retorna informações adicionais detalhadas sobre o vínculo selecionado, incluindo dados pessoais, margem consignável, histórico do vínculo e eventuais alertas.

:::caution Atenção
Para realizar qualquer uma dessas consultas, é obrigatório enviar um [Termo de autorização](#authorization_term).
Esse termo deve ser criado a partir da coleta de evidências de que o tomador forneceu um aceite expresso (opt-in) autorizando a execução das consultas.
As evidências — como timestamp, endereço IP e identificador de sessão — devem ser incluídas na requisição para garantir a rastreabilidade e conformidade regulatória do processo.
:::

Essas consultas, juntamente com o [Termo de autorização](#authorization_term), são etapas fundamentais para validar a elegibilidade do trabalhador e obter os dados necessários antes da formalização da operação de crédito.

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeados de forma estrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

## 1 - Consulta dos vínculos empregatícios do trabalhador:
A consulta de vínculos empregatícios é uma operação assíncrona. Ao enviar a requisição, a QI Tech processará a consulta em background e retornará o resultado através de um webhook quando finalizada.

O webhook será enviado para a URL configurada no seu ambiente.

**POST**
/private_payroll/employment_relationships_inquiry

Testar no Playground

### Request

**Caso 1:** O trabalhador é o assinante do [Termo de autorização](#authorization_term).
**Request Body**

```json
{
    "document_number": "12345678909",
    "authorization_term": {
        "signature": {
            "signer": {
                "name": "Nome do tomador",
                "email": "email_do_tomador@email.com",
                "phone": {
                    "number": "999999999",
                    "area_code": "11",
                    "country_code": "55"
                },
                "document_number": "12345678909"
            },
            "authentication_type": "opt_in",
            "authenticity": {
                "timestamp": "2025-03-24T12:19:08Z",
                "ip_address": "255.255.255.255",
                "fingerprint": {},
                "session_id": "0b73fdb9-1b3b-4f09-9cf2-b775a1ce58d2"
            }
        }
    }
}
```

**Caso 2:** O representante legal é o assinante do [Termo de autorização](#authorization_term).
**Request Body**

```json
{
    "document_number": "12345678909",
    "authorization_term": {
      "legal_representative_document_number": "32165498709",
        "signature": {
            "signer": {
                "name": "Nome do tomador",
                "email": "email_do_tomador@email.com",
                "phone": {
                    "number": "999999999",
                    "area_code": "11",
                    "country_code": "55"
                },
                "document_number": "12345678909"
            },
            "authentication_type": "opt_in",
            "authenticity": {
                "timestamp": "2025-03-24T12:19:08Z",
                "ip_address": "255.255.255.255",
                "fingerprint": {},
                "session_id": "0b73fdb9-1b3b-4f09-9cf2-b775a1ce58d2"
            }
        }
    }
}
```

:::caution Atenção
Nos casos em que houver representante legal, é necessário preencher o campo **"legal_representative_document_number"**
com o CPF do representante legal, e os dados do objeto **"signer"** devem ser preenchidos com os dados do mesmo.
:::

### Response

STATUS
**202** Accepted

**Response Body**

```json
{
    "employment_relationships_inquiry_key": "<UUID>",
    "employment_relationships_inquiry_status": "pending_inquiry"
}
```

:::info
Os possíveis valores para o enumerador **employment_relationships_inquiry_status** estão listados
na seção [Status das consultas de vínculos empregatícios](#status-das-consultas).
:::

### Webhooks

WEBHOOK TYPE
laas.private_payroll.employment_relationships_inquiry_status_change

Retorno da consulta dos vínculos empregatícios:

STATUS
completed

**Webhook Body**

```json
{
    "key": "<Employment Relationships Inquiry Key>",
    "status": "completed",
    "webhook_type": "laas.private_payroll.employment_relationships_inquiry_status_change",
    "event_datetime": "2025-03-24T15:28:31Z",
    "data": {
        "authorization_term": {
            "status": "authorized",
            "authorization_term_key": "<UUID>",
            "signed_at": "2025-03-24T12:19:08Z",
            "expiration_date": "2025-04-24"
        },
        "employment_relationships": [
            {
                "eligible": true,
                "document_number": "47812365409",
                "registration_number": "99999999999-A", 
                "employer_document_type": "cpf",
                "employer_document_number": "34848037034"
            },
            {
                "eligible": false,
                "document_number": "47812365409",
                "registration_number": "11111111111-B",
                "employer_document_type": "cnpj",
                "employer_document_number": "33296860000173"
            }
        ]
    }
}
```

STATUS
failed

**Webhook Body**

```json
{
    "key": "<Employment Relationships Inquiry Key>",
    "status": "failed",
    "webhook_type": "laas.private_payroll.employment_relationships_inquiry_status_change",
    "event_datetime": "2025-03-24T15:28:31Z",
    "data": {
        "enumerator": "ineligible_worker_cpf",
        "description": "CPF not found in database or worker CPF ineligible",
        "translation": "CPF não encontrado na base ou CPF do trabalhador inelegível"
    }
}
```

:::warning Aviso
Para simular uma falha em ambiente de sandbox, realize uma consulta com um CPF iniciado com o dígito 2.
:::
---

## 2 - Consulta de dados do trabalhador: {#consulta-de-dados}
A consulta de dados do trabalhador é uma operação assíncrona. Ao enviar a requisição, a QI Tech irá processar a consulta em background e retornará o resultado através de um webhook quando finalizada.

O webhook será enviado para a URL configurada no seu ambiente.

Existem dois cenários possíveis para realizar a consulta:

1. Utilizando um [Termo de autorização](#authorization_term) previamente enviado na consulta de vínculos empregatícios
2. Enviando um novo [Termo de autorização](#authorization_term) junto com a consulta

Em ambos os casos, é necessário informar o número de matrícula do trabalhador obtido na consulta de vínculos empregatícios.

**POST**
/private_payroll/balance_inquiry

Testar no Playground

### Request

**Caso 1:** Consulta de dados do trabalhador com o [Termo de autorização](#authorization_term) previamente enviado.
**Request Body**

```json
{
    "document_number": "<CPF FUNCIONÁRIO>",
    "registration_number": "<NÚMERO DE MATRÍCULA>",
    "employer_document_number": "<CNPJ EMPREGADOR>"
}
```

**Caso 2:** Consulta de dados do trabalhador com envio do [Termo de autorização](#authorization_term).
**Request Body**

```json
{
    "document_number": "<CPF FUNCIONÁRIO>",
    "registration_number": "<NÚMERO DE MATRÍCULA>",
    "employer_document_number": "<CNPJ EMPREGADOR>",
    "authorization_term": {
        "legal_representative_document_number": "<CPF DO REPRESENTANTE LEGAL>", // Caso aplicável
        "signature": {
            "signer": {
                "name": "<NOME DO ASSINANTE>",
                "email": "<EMAIL DO ASSINANTE>",
                "phone": {
                    "number": "<NUMERO DO ASSINANTE>",
                    "area_code": "<DDD DO ASSINANTE>",
                    "country_code": "55"
                },
                "document_number": "<CPF DO ASSINANTE>"
            },
            "authentication_type": "opt_in",
            "authenticity": {
                "timestamp": "<DATA E HORA DA ASSINATURA>",
                "ip_address": "<IP DO ASSINANTE>",
                "fingerprint": {},
                "session_id": "<ID DA SESSÃO DO ASSINANTE>"
            }
        }
    }
}
```

:::caution Atenção
Nos casos em que houver representante legal, é necessário preencher o campo **"legal_representative_document_number"**
com o CPF do representante legal, e os dados do objeto **"signer"** devem ser preenchidos com os dados do mesmo.
:::

### Response

STATUS
**202** (Accepted)

**Response Body**

```json
{
    "balance_inquiry_key": "<Balance Inquiry Key>",
    "balance_inquiry_status": "pending_inquiry"
}
```

:::info
Os possíveis valores para o enumerador **balance_inquiry_status** estão listados
na seção [Status das consultas de dados do trabalhador](#status-das-consultas).
:::

### Webhooks

WEBHOOK TYPE
laas.private_payroll.balance_inquiry_status_change

Retorno da consulta de dados do trabalhador:

STATUS
completed

**Webhook Body**

```json
{
    "key": "<Balance Inquiry Key>",
    "status": "completed",
    "webhook_type": "laas.private_payroll.balance_inquiry_status_change",
    "event_datetime": "2024-02-21T14:30:25Z",
    "data": {
        "document_number": "99999999999",
        "registration_number": "99999999999-A",
        "employer_document_number": "99999999999962",
        "name": "JOÃO SILVA",
        "gender": "male",
        "birth_date": "1985-07-20",
        "worker_category_code": 101,
        "eligible": true,
        "available_margin_amount": 5000.00,
        "base_margin_amount": 4500.00,
        "total_due_amount": 8207.54,
        "admission_date": "2020-03-15",
        "termination_date": null,
        "termination_reason_code": null,
        "political_exposition": "not_exposed",
        "suspended_loans_count": 2,
        "block_type": "no_block",
        "blocked_at": null,
        "employer_name": "EMPRESA XYZ LTDA",
        "mother_name": "MARIA DA SILVA",
        "nationality": {
            "code": 76,
            "description": "BRASIL"
        },
        "occupation": {
            "code": 724325,
            "description": "SOLDADOR ELETRICO"
        },
        "economic_activity": {
            "code": 2833000,
            "description": "FABRICACAO DE MAQUINAS E EQUIPAMENTOS PARA A AGRICULTURA E PECUARIA, PECAS E ACESSORIOS, EXCETO PARA IRRIGACAO"
        },
        "ineligibility_reason": "not_informed",
        "employer_activity_start_date": "2010-05-12",
        "legacy_loans": [],
        "alerts": [
            {
                "alert_type": "leave",
                "reference_date": "2025-02-11",
                "event_id": 123456,
                "leave_reason_code": 3,
                "leave_start_date": "2025-02-11",
                "leave_end_date": "2025-03-11"
            },
            {
                "alert_type": "termination",
                "reference_date": "2025-02-11", 
                "event_id": 789012,
                "termination_reason_code": 1,
                "termination_date": "2025-02-11",
                "notice_period_start_date": "2025-01-11",
                "notice_period_end_date": "2025-02-11"
            }
        ],
        "warranty":{
            "severance_pay_rate":0.15
        }
    }
}
```

STATUS
failed

**Webhook Body**

```json
{
    "key": "<Balance Inquiry Key>",
    "status": "failed",
    "webhook_type": "laas.private_payroll.balance_inquiry_status_change",
    "event_datetime": "2024-02-21T14:30:25Z",
    "data": {
      "authorization_term": {
        "status": "authorized",
        "signed_at": "2025-08-10T17:42:05Z",
        "expiration_date": "2025-09-09",
        "authorization_term_key": "4444cc5b-9c60-473f-8fe4-6c43b855be6d"
      }
    }
}
```

:::warning Aviso
Para simular uma falha em ambiente de sandbox, realize uma consulta com um CPF iniciado com o dígito 2.
:::

## 3 - Consulta de garantias FGTS

Para emissão de crédito com garantias em multa e saldo do FGTS, é necessário realizar uma consulta adicional para verificar a disponibilidade destas garantias.

:::warning Verbas rescisórias
Neste endpoint serão retornados somente os valores de multa rescisória e saldo FGTS disponíveis, o percentual de verbas rescisórias é retornado no endpoint de [consulta de dados do vínculo](#consulta-de-dados).
:::

:::danger Autorização no app da CTPS
Além do termo de autorização o tomador deve entrar no app da CTPS e autorizar a instituição financeira QI SCD a consultar o seu saldo no FGTS.
:::

**POST**
/private_payroll/warranty_inquiry

### Request

**Caso 1:** O trabalhador é o assinante do [Termo de autorização](#authorization_term).
**Request Body**

```json
{
    "document_number": "<CPF FUNCIONÁRIO>",
    "registration_number": "<NÚMERO DE MATRÍCULA>",
    "employer_document_number": "<CNPJ EMPREGADOR>",
    "authorization_term": {
        "signature": {
            "signer": {
                "name": "<NOME DO ASSINANTE>",
                "email": "<EMAIL DO ASSINANTE>",
                "phone": {
                    "number": "<NUMERO DO ASSINANTE>",
                    "area_code": "<DDD DO ASSINANTE>",
                    "country_code": "55"
                },
                "document_number": "<CPF DO ASSINANTE>"
            },
            "authentication_type": "opt_in",
            "authenticity": {
                "timestamp": "<DATA E HORA DA ASSINATURA>",
                "ip_address": "<IP DO ASSINANTE>",
                "fingerprint": {},
                "session_id": "<ID DA SESSÃO DO ASSINANTE>"
            }
        }
    }
}
```

**Caso 2:** O representante legal é o assinante do [Termo de autorização](#authorization_term).
**Request Body**

```json
{
    "document_number": "<CPF FUNCIONÁRIO>",
    "registration_number": "<NÚMERO DE MATRÍCULA>",
    "employer_document_number": "<CNPJ EMPREGADOR>",
    "authorization_term": {
        "legal_representative_document_number": "<CPF DO REPRESENTANTE LEGAL>", // Caso aplicável
        "signature": {
            "signer": {
                "name": "<NOME DO ASSINANTE>",
                "email": "<EMAIL DO ASSINANTE>",
                "phone": {
                    "number": "<NUMERO DO ASSINANTE>",
                    "area_code": "<DDD DO ASSINANTE>",
                    "country_code": "55"
                },
                "document_number": "<CPF DO ASSINANTE>"
            },
            "authentication_type": "opt_in",
            "authenticity": {
                "timestamp": "<DATA E HORA DA ASSINATURA>",
                "ip_address": "<IP DO ASSINANTE>",
                "fingerprint": {},
                "session_id": "<ID DA SESSÃO DO ASSINANTE>"
            }
        }
    }
}
```

:::caution Atenção
Nos casos em que houver representante legal, é necessário preencher o campo **"legal_representative_document_number"**
com o CPF do representante legal, e os dados do objeto **"signer"** devem ser preenchidos com os dados do mesmo.
:::

### Response

STATUS
**202** Accepted

**Response Body**

```json
{
    "warranty_inquiry_key": "<UUID>",
    "warranty_inquiry_status": "pending_inquiry"
}
```

:::info
Os possíveis valores para o enumerador **warranty_inquiry_status** estão listados
na seção [Status das consultas de vínculos empregatícios](#status-das-consultas).
:::

### Webhooks

WEBHOOK TYPE
laas.private_payroll.warranty_inquiry_status_change

Retorno da consulta de garantias FGTS:

STATUS
completed

**Webhook Body**

```json
{
    "key": "<Warranty Inquiry Key>",
    "status": "completed",
    "webhook_type": "laas.private_payroll.warranty_inquiry_status_change",
    "event_datetime": "2025-03-24T15:28:31Z",
    "data": {
        "severance_fine":1000,
        "fgts_balance":2000
    }
}
```

STATUS
failed

**Webhook Body**

```json
{
    "key": "<Warranty Inquiry Key>",
    "status": "failed",
    "webhook_type": "laas.private_payroll.warranty_inquiry_status_change",
    "event_datetime": "2025-03-24T15:28:31Z",
    "data": {
        "enumerator": "ineligible_worker_cpf",
        "description": "CPF not found in database or worker CPF ineligible",
        "translation": "CPF não encontrado na base ou CPF do trabalhador inelegível"
    }
}
```

## 4 - Consulta da Proposta Ativa no Leilão da CTPS

Caso a QI Tech já tenha uma proposta de leilão ativa na CTPS para o tomador, a DATAPREV não permite que seja averbada uma nova proposta no fluxo ativo com taxa superior à que foi ofertada no leilão vigente.

A fim de trazer visibilidade sobre essa taxa vigente antes de uma nova simulação/emissão, é possível realizar uma consulta no vínculo empregatício do trabalhador para verificar se já existe uma proposta ativa na CTPS.

:::warning Pré-requisito
Este endpoint só pode ser consultado se você tiver uma [consulta de dados do trabalhador](#consulta-de-dados) com status `completed` para o mesmo `document_number`, `registration_number` e `employer_document_number`, realizada **nos últimos 7 dias**.

Caso não exista essa consulta ou ela esteja vencida, refaça a [consulta de dados do trabalhador](#consulta-de-dados) antes de tentar novamente.
:::

**GET**
/private_payroll_auction/auction_proposal/active

### Request

Todos os parâmetros são enviados via query string.

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `document_number` | string | Sim | CPF do trabalhador, retornado na consulta de dados. |
| `employer_document_number` | string | Sim | Documento do empregador, retornado na consulta de dados. Aceita CPF (empregador pessoa física), CNPJ completo (numérico ou alfanumérico) ou apenas a raiz de 8 caracteres do CNPJ. |
| `registration_number` | string | Sim | Número de registro do vínculo, retornado na consulta de dados. |
| `employer_document_type` | string (`cpf` ou `cnpj`) | Não | Tipo do documento informado em `employer_document_number`. Quando omitido, é inferido automaticamente a partir do formato do valor enviado. |

### Response

STATUS
**200** (OK)

**Response Body**

```json
{
    "document_number": "12345678900",
    "employer_document_number": "12345678000199",
    "registration_number": "1234567",
    "standard_proposal": {
        "monthly_interest_rate": 0.0135,
        "expiration_datetime": "2026-09-20T00:00:00Z"
    },
    "warranted_proposal": null
}
```

| Campo | Tipo | Descrição |
|---|---|---|
| `standard_proposal` | objeto, opcional | Proposta ativa **sem garantia**. Retorna `null` quando não houver proposta ativa deste tipo. Ver [Objeto standard_proposal / warranted_proposal](#objeto-proposta-ativa-leilao-ctps). |
| `warranted_proposal` | objeto, opcional | Proposta ativa **com garantia** (FGTS/multa rescisória). Retorna `null` quando não houver proposta ativa deste tipo. Ver [Objeto standard_proposal / warranted_proposal](#objeto-proposta-ativa-leilao-ctps). |

#### Objeto `standard_proposal` / `warranted_proposal` {#objeto-proposta-ativa-leilao-ctps}

| Campo | Tipo | Descrição |
|---|---|---|
| `monthly_interest_rate` | número | Taxa de juros mensal vigente da proposta ativa, no intervalo de 0 a 1 (ex.: `0.0135` = 1,35%). Uma nova proposta só será aceita pela DATAPREV se possuir taxa menor que esta. |
| `expiration_datetime` | string (data/hora, ISO-8601 UTC) | Data e horário em que a proposta ativa expira. |

:::info
`standard_proposal` e `warranted_proposal` são independentes entre si: é possível existir proposta ativa de apenas um dos dois tipos, dos dois, ou nenhum deles.
:::

STATUS
**404** (Not Found)

Retornado quando não existe nenhuma proposta ativa (vencedora e não expirada) para a combinação de `document_number`, `employer_document_number` e `registration_number` informada — ou seja, não há taxa vigente limitando uma nova averbação no momento.

**Response Body**

```json
{
    "code": "PPA000037",
    "title": "Active Auction Proposal not Found",
    "description": "No active auction proposal sent to Dataprev was found for 'document_number' 12345678900, 'employer_document_number' 12345678000199 and 'registration_number' 1234567.",
    "translation": "Nenhuma proposta ativa enviada ao Dataprev foi encontrada para o 'document_number' 12345678900, 'employer_document_number' 12345678000199 e 'registration_number' 1234567."
}
```

STATUS
**412** (Precondition Failed)

Retornado quando o pré-requisito de [consulta de dados do trabalhador](#consulta-de-dados) recente não é atendido. Há dois cenários possíveis:

**Nenhuma consulta encontrada**

Nenhuma consulta de dados do trabalhador com status `completed` foi encontrada para a combinação de `document_number`, `employer_document_number` e `registration_number` informada (considerando apenas as consultas do seu próprio `SELECTED-AGENT`).

**Response Body**

```json
{
    "code": "PPA000038",
    "title": "Missing Margin Inquiry",
    "description": "No completed margin inquiry was found for 'document_number' 12345678900, 'employer_document_number' 12345678000199 and 'registration_number' 1234567.",
    "translation": "Nenhuma consulta de margem concluída foi encontrada para o 'document_number' 12345678900, 'employer_document_number' 12345678000199 e 'registration_number' 1234567."
}
```

**Consulta expirada**

A consulta de dados do trabalhador mais recente encontrada foi concluída há mais de 7 dias.

**Response Body**

```json
{
    "code": "PPA000039",
    "title": "Stale Margin Inquiry",
    "description": "The latest margin inquiry for 'document_number' 12345678900 was made at 2026-08-10T10:00:00Z, older than the 7-day freshness window.",
    "translation": "A consulta de margem mais recente para o 'document_number' 12345678900 foi feita em 2026-08-10T10:00:00Z, fora da janela de validade de 7 dias."
}
```

STATUS
**502** (Bad Gateway)

Retornado quando não foi possível verificar a existência de uma consulta de dados do trabalhador recente por uma falha na comunicação interna da QI Tech. Nesse caso, recomenda-se tentar novamente a requisição.

**Response Body**

```json
{
    "code": "PPA000040",
    "title": "Margin Inquiry Lookup Error",
    "description": "Could not check the margin inquiry of 'document_number' 12345678900 with the private payroll service.",
    "translation": "Não foi possível verificar a consulta de margem do 'document_number' 12345678900 junto ao serviço de consignado privado."
}
```

## Anexos
---
### Detalhamento do objeto authorization_term {#authorization_term}
| Campo                   | Obrigatoriedade | Descrição                          | 
|-------------------------|-----------------|------------------------------------|
|Name                     |Obrigatório      |Nome do tomador                     |
|Email                    |Opcional         |Email do tomador                    |
|Phone                    |Opcional         |Telefone do tomador                 |
|Document_number          |Obrigatório      |CPF do tomador                      |
|Authentication_type      |Obrigatório      |Obrigatoriamente "opt-in"           |
|Timestamp                |Obrigatório      |Timestamp do aceite do tomador, obrigatoriamente no formato:  2025-08-04T23:45:30Z|
|Ip_address               |Obrigatório      |IP da sessão do usuário, seja em IPv4 (ex: 192.168.0.1) ou IPv6 (ex: 2001:0db8:85a3:0000:0000:8a2e:0370:7334)|
|Fingerprint              |Obrigatório      |Objeto onde podem ser enviadas evidências adicionais que contribuam com a robustez do aceite e que auxiliem na rastreabilidade, apesar de obrigatório, pode ser enviado um objeto nulo|
|Session_id               |Obrigatório      |Chave identificadora interna da sessão do usuário, tamanho mínimo 10 e máximo 50|

**Exemplos de campos do objeto fingerprint**
```json
{
  "fingerprint_id": "4c188fc4-2cb4-48cc-9236-7df953570638",
  "lat": "-15.82891",
  "long": "-48.12751",
  "name": "ALBERTO PEREIRA",
  "device": "Web",
  "browser": "Chrome",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/037.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/037.36",
  "browser_version": "120.0.0.0"
}
```
### Detalhamento do webhook de consulta de dados
| Campo                         | Descrição                          | 
|-------------------------      |------------------------------------|
|document_number                |Documento do tomador                 |
|registration_number            |Número de registro do vínculo empregatício                    |
|employer_document_number       |Número de documento do empregador (no caso de CNPJ somente os 8 primeiros dígitos)|
|name                           |Nome do tomador                      |
|gender                         |Gênero do tomador           |
|birth_date                     |Data de nascimento do tomador|
|worker_category_code           |[Categoria do trabalhador](https://www.gov.br/esocial/pt-br/documentacao-tecnica/manuais/leiautes-esocial-v-1-1-beta/tabelas.html#01) em conformidade com o site do eSocial|
|eligible                       |Eligibilidade do vínculo para emissão de crédito consignado|
|available_margin_amount        |Margem consignável|
|base_margin_amount             |Salário|
|total_due_amount               |Saldo devedor do tomador|
|admission_date                 |Data de admissão|
|termination_date               |Data de desligamento|
|termination_reason_code        |[Motivo do desligamento](https://www.gov.br/esocial/pt-br/documentacao-tecnica/leiautes-esocial-versao-1-3-nt-03-2025/tabelas.html#19) em conformidade com o site do eSocial|
|political_exposition           |Nível de exposição política do tomador, consulte os possíveis enumeradores na tabela [Exposição política](#exposição-política)|
|employer_name                  |Nome do empregador|
|mother_name                    |Nome da mãe do tomador|
|nationality.description        |Nacionalidade do tomador|
|nationality.code               |Código da nacionalidade to tomador segundo o padrão numérico da parte 1 da norma ISO 3166|
|occupation.description         |Ocupação do tomador segundo a Clasificação Brasileira de Ocupações (CBO)|
|occupation.code                |Código segundo a CBO 2002|
|economic_activity.description  |Atividade econômica do empregador segundo a Classificação Nacional de Atividades Econômicas (CNAE)|
|economic_activity.code         |Código segundo a CNAE Subclasses 2.3|
|ineligibility_reason           |Motivo da inelegibilidade do vínculo|
|employer_activity_start_date   |Data de início da atividade do empregador|
|legacy_loans                   |Lista de empréstimos ativos informados pelas IFs, para detalhamento dos campos consulte a tabela [Detalhamento do objeto legacy_loans](#legacy_loans)|
|alerts                         |Lista com histórico de afastamentos e avisos de desligamento do vínculo, para detalhamento dos campos consulte a tabela [Detalhamento do objeto alerts](#alerts)|
|suspended_loans_count          |Quantidade de empréstimos suspensos|
|block_type                     |Tipo de bloqueio do Vínculo empregatício, consulte os possíveis enumeradores na tabela [Bloqueio de Salário](#block)|
|blocked_at                     |Data de bloqueio do Vínculo empregatício|
|warranty                       |Garantias disponíveis|
|severance_pay_rate             |Percentual de verbas rescisórias disponível para garantia|

### Detalhamento do webhook de consulta de saldo FGTS
| Campo                         | Descrição                          | 
|-------------------------      |------------------------------------|
|severance_fine                 |Valor de multa rescisória disponível para garantia                 |
|fgts_balance                   |Valor de saldo do fgts disponível para garantia                    |

### Exposição política {#exposicao-politica}

ENUMERADOR
political_exposition

| Enumerador    | Descrição                                                                 |
| ------------- | ------------------------------------------------------------------------- |
| not_exposed   | Pessoa não exposta politicamente                                          |
| level_1       | Pessoa exposta politicamente nível 1                                      |
| level_2       | Pessoa exposta politicamente nível 2                                      |
| not_informed  | Não há informação sobre a exposição política                              |

### Detalhamento do objeto alerts {#alerts}
| Campo                         | Descrição                          | 
|-------------------------      |------------------------------------|
|alert_type                     |Tipo de alerta, consulte os possíveis enumeradores na tabela [Tipos de alerta](#alert_type)|
|reference_date                 |Data de referência do evento|
|event_id                       |Identificador do evento|
|leave_reason_code              |[Motivo do afastamento](https://www.gov.br/esocial/pt-br/documentacao-tecnica/leiautes-esocial-versao-1-3-nt-03-2025/tabelas.html#18) em conformidade com o site do eSocial|
|leave_start_date               |Data de início do afastamento|
|leave_end_date                 |Data de término do afastamento|
|termination_reason_code        |[Motivo do desligamento](https://www.gov.br/esocial/pt-br/documentacao-tecnica/leiautes-esocial-versao-1-3-nt-03-2025/tabelas.html#19) em conformidade com o site do eSocial|
|termination_date               |Data de desligamento do vínculo|
|notice_period_start_date       |Data de início do período de aviso prévio|
|notice_period_end_date         |Data de término do período de aviso prévio|

### Tipos de alerta {#alert_type}
ENUMERADOR
alert_type
| Enumerador                    | Descrição                         | 
|-------------------------      |-----------------------------------|
|leave                          |Afastamento                        |
|termination                    |Aviso prévio de desligamento       |

### Detalhamento do objeto legacy_loans {#legacy_loans}
| Campo                         | Descrição                          | 
|-------------------------      |------------------------------------|
|loan_amount                    |Valor desembolsado|
|monthly_cet                    |CET mensal|
|monthly_rate                   |Taxa mensal|
|contract_type                  |Tipo de contrato, consulte os possíveis enumeradores na tabela [Tipos de contrato legado](#contract_type)|
|contract_number                |Número de contrato|
|contract_end_date              |Data de término do contrato|
|paid_installments              |Quantidade de parcelas pagas|
|total_installments             |Quantidade total de parcelas|
|installment_amount             |Valor de parcela|
|contract_start_date            |Data de início do contrato|
|outstanding_balance            |Saldo devedor|
|last_update_timestamp          |Data da última atualização|
|financial_institution_code     |Código da IF que informou o empréstimo|

### Tipos de contrato legado{#contract_type}
ENUMERADOR
contract_type
| Enumerador                    | Descrição                         | 
|-------------------------      |-----------------------------------|
|unsecured_non_consigned_loan   |Empréstimo não consignado sem garantia|
|loan_with_payroll_deductions   |Empréstimo com descontos em folha de pagamento|

### Status das consultas de vínculos empregatícios e de dados do trabalhador {#status-das-consultas}

ENUMERADOR
employment_relationships_inquiry_status

ENUMERADOR
balance_inquiry_status

ENUMERADOR
warranty_inquiry_status

| Status                | Descrição                                                                     |
| --------------------- | ----------------------------------------------------------------------------- |
| pending_authorization | Os dados de autorização foram enviados e estão pendentes de processamento.    |
| pending_inquiry       | A consulta está autorizada e pendente de ser processada.                      |
| completed             | A consulta foi concluída com sucesso.                                         |
| failed                | A consulta falhou.                                                            |

### Bloqueio de Vínculo empregatício {#block}

ENUMERADOR
block_type

| Enumerador            | Descrição                                                                 |
| -------------         | ------------------------------------------------------------------------- |
| no_block              | Vínculo empregatício não bloqueado                                          |
| blocked_by_the_worker | Vínculo empregatício pelo colaborador                                      |

---

# Manual Consignado Privado - Contratos Legados

URL: /documentation/manual_consignado_privado/manual_contratos_legados

:::caution API em desenvolvimento 
A API ainda está em fase de desenvolvimento, sendo assim, este manual esta sujeito a alterações.
:::

A renegociação de um contrato legado é feita a partir da criação de uma nova dívida, com os dados do contrato legado informados no campo *collateral_data*.

Para verificar os contratos legados que foram incluídos no sistema, deve-se realizar uma consulta aos empréstimos legados.
Em caso de não encontrar, favor entrar em contato com o suporte para solicitar a inclusão.

Devido à regra de negócio do Consignado Privado, atualmente o trabalhador pode ter apenas um contrato ativo. 
Portanto, caso o trabalhador possua mais de um contrato legado, somente um deles poderá ser renegociado.
Da mesma forma, caso o trabalhador possua um contrato ativo, não será possível criar uma renegociação para o mesmo.

O fluxo de criação da dívida e de assinatura é o mesmo utilizado para a criação de um crédito novo. A diferença está na averbação da dívida, que é feita automaticamente pelo sistema após a assinatura do contrato, não necessitando de aprovação manual e não sendo necessária a consulta ao SCR.

## 1 - Consulta de empréstimos legados

**GET**
/private_payroll/legacy_contracts

Testar no Playground

### Query Parameters

| Parâmetro       | Tipo    | Obrigatório | Descrição                          | Valor Padrão |
|-----------------|---------|-------------|------------------------------------|--------------|
| page            | integer | Não         | Número da página a ser retornada   | 1            |
| page_size       | integer | Não         | Quantidade de registros por página | 100          |
| document_number | string  | Não         | CPF do cliente sem pontuação       | N/A          |

:::info
A paginação é baseada em um, portanto a primeira página é a página 1.
:::

### Response

STATUS
**200** OK

```json
{
    "data": [
        {
            "legacy_contract_key": "123e4567-e89b-12d3-a456-426614174000",
            "document_number": "29883927061",
            "contract_number": "1234567890",
            "legacy_contract_data": {
                "cet": 0.0637,
                "due_balance": 1935,
                "total_amount": 2405.76,
                "contract_type": "consigned_loan",
                "interest_rate": 0.0409,
                "period_amount": 129.33,
                "contract_end_date": "2026-10-05",
                "number_of_periods": 36,
                "contract_start_date": "2023-10-06",
                "registration_number": "11841",
                "number_of_paid_periods": 17,
                "employer_document_number": "43028211000145"
            }, 
            "status": "active"
        }
    ],
    "pagination": {
        "current_page": 1,
        "next_page": 2,
        "rows_per_page": 100,
        "total_pages": 1,
        "total_rows": 1
    }
}
```

### Response Body

A resposta paginada é composta por um array de contratos (*data*) e um objeto de paginação (*pagination*).

#### Lista de contratos

Descrição dos itens do array *data*:

| Parâmetro            | Tipo    | Obrigatório | Descrição                              |
|----------------------|---------|-------------|----------------------------------------|
| legacy_contract_key  | string  | Sim         | Identificador único do contrato legado |
| document_number      | string  | Sim         | CPF do cliente                         |
| contract_number      | string  | Sim         | Número do contrato                     |
| legacy_contract_data | object  | Sim         | Dados do contrato legado               |
| status               | string  | Sim         | Status do contrato                     |

#### Dados do contrato legado

Dados contidos no objeto *legacy_contract_data*:

| Parâmetro                | Tipo    | Obrigatório | Descrição                   |
|--------------------------|---------|-------------|-----------------------------|
| cet                      | decimal | Sim         | Custo Efetivo Total         |
| due_balance              | decimal | Sim         | Saldo devedor               |
| total_amount             | decimal | Sim         | Valor total do contrato     |
| contract_type            | string  | Sim         | Tipo do contrato            |
| interest_rate            | decimal | Sim         | Taxa de juros               |
| period_amount            | decimal | Sim         | Valor da parcela            |
| contract_end_date        | string  | Sim         | Data de término do contrato |
| number_of_periods        | integer | Sim         | Número total de parcelas    |
| contract_start_date      | string  | Sim         | Data de início do contrato  |
| registration_number      | string  | Sim         | Matrícula do funcionário    |
| number_of_paid_periods   | integer | Sim         | Número de parcelas pagas    |
| employer_document_number | string  | Sim         | CNPJ do empregador          |

#### Dados de paginação

Dados contidos no objeto *pagination*:

| Parâmetro     | Tipo    | Obrigatório | Descrição                          |
|---------------|---------|-------------|------------------------------------|
| current_page  | integer | Sim         | Página atual                       |
| next_page     | integer | Sim         | Próxima página                     |
| rows_per_page | integer | Sim         | Quantidade de registros por página |
| total_pages   | integer | Sim         | Total de páginas                   |
| total_rows    | integer | Sim         | Total de registros                 |

## 2 - Exclusão de Contrato Legado

A exclusão de um contrato legado é realizada pelo seguinte endpoint:

**DELETE**
/private_payroll/legacy_contract/ contract_number

Testar no Playground

Onde o path parameter "contract_number" deve ser o contrato a ser excluído, em formato de string.

### Response

Em caso de sucesso será retornada a resposta:

STATUS
**200** OK

Enquanto no caso em que o contrato legado apontado não exista será retornado um erro de NotFound, com código de erro "PRP000079".

STATUS
**404** NOT FOUND

## 3 - Criação da renegociação

A renegociação de um contrato legado é realizada através da criação de uma dívida similar à criação de um crédito novo, com a diferença de que os dados do contrato legado deverão ser informados no campo *collateral_data* como exemplificado abaixo:

**POST**
/debt

Testar no Playground

```json
{
    "simplified": true,
    "requester_identifier_key": "05a9c4cc-39d5-48fe-ab47-8f1b37d8bffb",
    "purchaser_document_number": "30620610000159",
    "borrower": {
        "role_type": "issuer",
        "person_type": "natural",
        "name": "EXEMPLO",
        "email": "exemplo@exemplo.com",
        "individual_document_number": "48674911013",
        "birth_date": "1991-01-01",
        "mother_name": "MÃE DO EXEMPLO",
        "phone": {
            "country_code": "55",
            "area_code": "11",
            "number": "999999999"
        },
        "address": {
            "street": "RUA EXEMPLO",
            "number": "123",
            "complement": "APTO 123",
            "neighborhood": "BAIRRO EXEMPLO",
            "postal_code": "12345678",
            "city": "SÃO PAULO",
            "state": "SP"
        },
    },
    "disbursement_bank_accounts": [
        {
            "name": "EXEMPLO",
            "document_number": "48674911013",
            "pix_transfer_type": "key",
            "pix_key": "pix03@pix03.com",
            "amount_receivable": 2000
        },
        {
            "name": "Cel-lep Ensino De Idiomas S.a.",
            "document_number": "10772420000140",
            "digitable_line": "32990001039000210987502864982109595090000063958",
            "amount_receivable": 639.58
        }
    ],
    "financial": {
        "credit_operation_type": "ccb",
        "interest_type": "pre_price_days",
        "interest_grace_period": 0,
        "principal_grace_period": 0,
        "limit_days_to_disburse": 1,
        "number_of_installments": 12,
        "installment_face_value": 250,
        "disbursement_date": "2025-05-12",
        "disbursed_amount": 2639.58,
        "first_due_date": "2025-07-28",
        "fine_configuration": {
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02,
            "monthly_rate": 0.01
        },
    },
    "collaterals": [
        {
            "percentage": 1,
            "collateral_type": "private_payroll",
            "collateral_data": {
                "registration_number": "g7D1IFvUmq2s7zE9UVsV0HQwfcbHj",
                "employer_document_number": "60518978000171",
                "operation_category": "legacy_contract_refinancing",
                "legacy_contract_numbers": ["0000001523EMP"],
            }
        }
    ]
}
```

:::info
Caso tenha um representante legal, deverá ser informado no campo *related_parties* como exemplificado no exemplo de crédito novo.

```json
{
    "related_parties": [
        {
            "role_type": "issuer_legal_representative",
            "person_type": "natural",
            "name": "REPRESENTANTE EXEMPLO",
            "email": "representante.exemplo@exemplo.com",
            "individual_document_number": "79795844067",
            "birth_date": "1970-04-20",
            "mother_name": "MÃE DO REPRESENTANTE",
            "phone": {
                "country_code": "55",
                "area_code": "11",
                "number": "999999999"
            },
            "address": {
                "street": "RUA EXEMPLO",
                "number": "123",
                "complement": "APTO 123",
                "neighborhood": "BAIRRO EXEMPLO",
                "postal_code": "12345678",
                "city": "SÃO PAULO",
                "state": "SP"
            }
        }
    ]
}
```
:::

### Response

STATUS
**201** Created

```json title="Response Body"
{
    "webhook_type": "debt",
    "key": "<Debt Key>",
    "status": "waiting_signature",
    "event_datetime": "2025-05-06 10:00:00",
    "data": {
        "borrower": {
            "name": "Nome devedor",
            "document_number": "58307769019",
            "related_party_key": "28b7fc16-6d1f-467d-9667-62a8c13daea6"
        },
        "contract": {
            "number": "0000644710/NDV",
            "urls": [
                "https://storage.googleapis.com/sandbox-doc-api/documents/a2e9c83a-3666-4def-8b27-e96fabb8705c/NOME_DEVEDOR-CCB-TST0000644710-20241107231916.pdf"
            ],
            "signature_information": [
                {
                    "signer_name": "Nome devedor",
                    "signer_document_number": "14471835092",
                    "signer_role": "issuer",
                    "signer_email": null,
                    "signer_external_key": null,
                    "signature_url": null
                }
            ]
        },
        "requester_identifier_key": "05a9c4cc-39d5-48fe-ab47-8f1b37d8bffb",
        "iof_charge_method": "financed",
        "collaterals": [
            {
                "absolute_amount": null,
                "collateral_constituted": false,
                "collateral_data": {
                    "operation_category": "legacy_contract_refinancing",
                    "legacy_contract_number": "1234567890"
                },
                "collateral_key": "26c7f4f4-51f3-41fa-b880-9691211136aa",
                "collateral_type": "private_payroll",
                "created_at": "2024-11-07T23:19:16.413448",
                "external_key": null,
                "percentage": 1,
                "updated_at": "2024-11-07T23:19:16.413441"
            }
        ],
        "disbursement_options": [
            {
                "disbursement_date": "2024-11-07",
                "contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 4.55
                    },
                    {
                        "fee_type": "ted_fee",
                        "fee_amount": 1.5
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0
                    }
                ],
                "contract_fee_amount": 6.05,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "assignment_amount": 914.3,
                "issue_amount": 909.75,
                "cet": "2,0100%",
                "annual_cet": "27,0481%",
                "base_iof": 16.259002146803677,
                "additional_iof": 3.45705,
                "total_iof": 19.72,
                "total_pre_fixed_amount": 108.6508885851,
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-01-21",
                        "calendar_days": 74,
                        "due_date": "2025-01-21",
                        "due_interest": 0.0,
                        "due_principal": 909.75,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 37.1789024864,
                        "principal_amortization_amount": 64.6610975136,
                        "tax_amount": 0.3923635397125248,
                        "total_amount": 101.84,
                        "workdays": 49.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-02-21",
                        "calendar_days": 31,
                        "due_date": "2025-02-21",
                        "due_interest": 0.0,
                        "due_principal": 845.0889024864,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 2,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 14.2997636051,
                        "principal_amortization_amount": 87.5402363949,
                        "tax_amount": 0.753721435360089,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-03-21",
                        "calendar_days": 28,
                        "due_date": "2025-03-21",
                        "due_interest": 0.0,
                        "due_principal": 757.5486660915,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 3,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 11.5685715131,
                        "principal_amortization_amount": 90.2714284869,
                        "tax_amount": 0.9845001990781314,
                        "total_amount": 101.84,
                        "workdays": 18.0,
                        "installment_status": null,
                        "installment_type": null
                    }
                ],
                "first_due_date": "2025-01-21",
                "prefixed_interest_rate": {
                    "monthly_rate": 0.0166,
                    "daily_rate": 0.00054142,
                    "annual_rate": 0.21843191,
                    "interest_base": "calendar_days_365"
                }
            }
        ]
    }
} 
```

---

# Manual Consignado Privado - Crédito Novo

URL: /documentation/manual_consignado_privado/manual_credito_novo

:::info Navegação
- [Consultas do Trabalhador](/documentation/manual_consignado_privado/manual_consultas_trabalhador) (anterior)
- [Formalização Externa](/documentation/manual_consignado_privado/manual_assinatura_externa) (próximo)
:::

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeados de forma estrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

## 1 - Simulação da dívida:
CRÉDITO NOVO

### Request

**POST**
/debt_simulation

Testar no Playground

**Valor de parcela**

```json title='Request Body'
{
    "borrower": {
        "person_type": "natural"
    },
    "financial": {
        "first_due_date": "2024-12-07",
        "installment_face_value": 100,
        "disbursement_date": "2024-11-05",
        "limit_days_to_disburse": 3,
        "number_of_installments": 4,
        "monthly_interest_rate": 0.018,
        "interest_type": "pre_price_days",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0
    },
    "collaterals": [
        {
            "collateral_type": "private_payroll"
        }
    ]
}
```

**Valor desembolsado**

```json title='Request Body'
{
    "borrower": {
        "person_type": "natural"
    },
    "financial": {
        "first_due_date": "2024-12-07",
        "disbursed_amount": 1000,
        "disbursement_date": "2024-11-05",
        "limit_days_to_disburse": 3,
        "number_of_installments": 4,
        "monthly_interest_rate": 0.018,
        "interest_type": "pre_price_days",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0
    },
    "collaterals": [
        {
            "collateral_type": "private_payroll"
        }
    ]
}
```

**Simulação com garantia**

```json title='Request Body'
{
    "borrower": {
        "person_type": "natural",
        "individual_document_number": "14471835092"
    },
    "financial": {
        "first_due_date": "2024-12-07",
        "disbursed_amount": 1000,
        "disbursement_date": "2024-11-05",
        "limit_days_to_disburse": 3,
        "number_of_installments": 4,
        "monthly_interest_rate": 0.018,
        "interest_type": "pre_price_days",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0
    },
    "collaterals": [
        {
            "collateral_type": "private_payroll",
            "collateral_data": {
                "employer_document_number": "07940839000159",
                "registration_number": "99999999999-A",
                "warranted" :  true
            }
        }
    ]
}
```

:::info
Na request acima existem 3 simulações sendo realizadas. A primeira está fixando o valor de parcela ao cliente
(varia o valor desembolsado) e a segunda está fixando o valor desembolsado (varia o valor de parcela).

A terceira está adicionando as informações do vínculo empregatício para que seja retornada na resposta a composição da cobertura para o fluxo de pagamento considerando as garantias disponíveis retornadas nas últimas consultas deste vínculo.
::: 

### Response

STATUS
**200** (OK)

**Response Body**

**Simulação sem garantia**

```json
{
    "type": "debt",
    "key": "<Debt Key>",
    "status": "finished",
    "event_datetime": "2024-11-05 16:50:00",
    "data": {
        "interest_type": "pre_price_days",
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "interest_payment_month_period": 1,
        "principal_grace_period": 0,
        "principal_amortization_month_period": 1,
        "operation_type": "structured_operation",
        "post_fixed_interest_base": "workdays",
        "post_fixed_interest_rate": null,
        "prefixed_interest_rate": {
            "interest_base": "calendar_days_365",
            "annual_rate": 0.23872053,
            "monthly_rate": 0.018,
            "daily_rate": 0.00058669
        },
        "issue_date": "2024-11-05",
        "number_of_installments": 4,
        "requester_key": "e5eb6a0a-e003-4cbd-b702-5a25bf71af0a",
        "final_disbursement_amount": 0.0,
        "disbursement_options": [
            {
                "iof_amount": 3.93,
                "total_pre_fixed_amount": 17.8715883143,
                "cet": 0.0257,
                "annual_cet": 0.355163,
                "contract_fees": [
                    {
                        "fee_type": "tac",
                        "amount_type": "percentage",
                        "amount": 0.6,
                        "fee_amount": 2.29
                    },
                    {
                        "fee_type": "ted_fee",
                        "amount_type": "absolute",
                        "amount": 1.0,
                        "fee_amount": 1.0
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "insurance_premium",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "tac",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    }
                ],
                "contract_fee_amount": 2.29,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "disbursement_date": "2024-11-05",
                "first_due_date": "2024-12-21",
                "installments": [
                    {
                        "calendar_days": 34,
                        "workdays": 23.0,
                        "business_due_date": "2024-12-21",
                        "due_date": "2024-12-21",
                        "due_principal": 382.13,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 7.6967422515,
                        "tax_amount": 0.257341482602818,
                        "total_amount": 100,
                        "principal_amortization_amount": 92.3032577485,
                        "installment_number": 1
                    },
                    {
                        "calendar_days": 29,
                        "workdays": 19.0,
                        "business_due_date": "2025-01-21",
                        "due_date": "2025-01-21",
                        "due_principal": 289.8267422515,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 4.9718040699,
                        "tax_amount": 0.4909156601748966,
                        "total_amount": 100,
                        "principal_amortization_amount": 95.0281959301,
                        "installment_number": 2
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 23.0,
                        "business_due_date": "2025-02-21",
                        "due_date": "2025-02-21",
                        "due_principal": 194.7985463214,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.5742034136,
                        "tax_amount": 0.7432500400879712,
                        "total_amount": 100,
                        "principal_amortization_amount": 96.4257965864,
                        "installment_number": 3
                    },
                    {
                        "calendar_days": 28,
                        "workdays": 18.0,
                        "business_due_date": "2025-03-21",
                        "due_date": "2025-03-21",
                        "due_principal": 98.372749735,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.6288385793,
                        "tax_amount": 0.9841050988526828,
                        "total_amount": 100,
                        "principal_amortization_amount": 98.3711614207,
                        "installment_number": 4
                    }
                ],
                "issue_amount": 382.13,
                "disbursed_issue_amount": 374.91,
                "assignment_amount": 382.13,
                "final_disbursement_amount": 374.91,
                "prefixed_interest_rate": {
                    "interest_base": "calendar_days_365",
                    "annual_rate": 0.23872053,
                    "monthly_rate": 0.018,
                    "daily_rate": 0.00058669
                }
            },
            {
                "iof_amount": 4.77,
                "total_pre_fixed_amount": 24.2597288075,
                "cet": 0.0243,
                "annual_cet": 0.334037,
                "contract_fees": [
                    {
                        "fee_type": "tac",
                        "amount_type": "percentage",
                        "amount": 0.6,
                        "fee_amount": 2.25
                    },
                    {
                        "fee_type": "ted_fee",
                        "amount_type": "absolute",
                        "amount": 1.0,
                        "fee_amount": 1.0
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "insurance_premium",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "tac",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    }
                ],
                "contract_fee_amount": 2.25,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "disbursement_date": "2024-11-06",
                "first_due_date": "2025-01-21",
                "installments": [
                    {
                        "calendar_days": 62,
                        "workdays": 41.0,
                        "business_due_date": "2025-01-21",
                        "due_date": "2025-01-21",
                        "due_principal": 375.74,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 13.9149280115,
                        "tax_amount": 0.437656505989534,
                        "total_amount": 100,
                        "principal_amortization_amount": 86.0850719885,
                        "installment_number": 1
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 23.0,
                        "business_due_date": "2025-02-21",
                        "due_date": "2025-02-21",
                        "due_principal": 289.6549280115,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 5.3146959395,
                        "tax_amount": 0.722070128765373,
                        "total_amount": 100,
                        "principal_amortization_amount": 94.6853040605,
                        "installment_number": 2
                    },
                    {
                        "calendar_days": 28,
                        "workdays": 18.0,
                        "business_due_date": "2025-03-21",
                        "due_date": "2025-03-21",
                        "due_principal": 194.969623951,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.2283291407,
                        "tax_amount": 0.9601685182659746,
                        "total_amount": 100,
                        "principal_amortization_amount": 96.7716708593,
                        "installment_number": 3
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 21.0,
                        "business_due_date": "2025-04-07",
                        "due_date": "2025-04-07",
                        "due_principal": 98.1979530917,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.8017757158,
                        "tax_amount": 1.2239426674782687,
                        "total_amount": 100,
                        "principal_amortization_amount": 98.1982242842,
                        "installment_number": 4
                    }
                ],
                "issue_amount": 375.74,
                "disbursed_issue_amount": 367.72,
                "assignment_amount": 375.74,
                "final_disbursement_amount": 367.72,
                "prefixed_interest_rate": {
                    "interest_base": "calendar_days_365",
                    "annual_rate": 0.23872053,
                    "monthly_rate": 0.018,
                    "daily_rate": 0.00058669
                }
            },
            {
                "iof_amount": 4.74,
                "total_pre_fixed_amount": 24.0392857898,
                "cet": 0.0243,
                "annual_cet": 0.334673,
                "contract_fees": [
                    {
                        "fee_type": "tac",
                        "amount_type": "percentage",
                        "amount": 0.6,
                        "fee_amount": 2.26
                    },
                    {
                        "fee_type": "ted_fee",
                        "amount_type": "absolute",
                        "amount": 1.0,
                        "fee_amount": 1.0
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "insurance_premium",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "tac",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    }
                ],
                "contract_fee_amount": 2.26,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "disbursement_date": "2024-11-07",
                "first_due_date": "2025-01-21",
                "installments": [
                    {
                        "calendar_days": 61,
                        "workdays": 40.0,
                        "business_due_date": "2025-01-21",
                        "due_date": "2025-01-21",
                        "due_principal": 375.96,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 13.6944849939,
                        "tax_amount": 0.4317001860605122,
                        "total_amount": 100,
                        "principal_amortization_amount": 86.3055150061,
                        "installment_number": 1
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 23.0,
                        "business_due_date": "2025-02-21",
                        "due_date": "2025-02-21",
                        "due_principal": 289.6544849939,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 5.3146959395,
                        "tax_amount": 0.714305933832412,
                        "total_amount": 100,
                        "principal_amortization_amount": 94.6853040605,
                        "installment_number": 2
                    },
                    {
                        "calendar_days": 28,
                        "workdays": 18.0,
                        "business_due_date": "2025-03-21",
                        "due_date": "2025-03-21",
                        "due_principal": 194.9691809334,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.2283291407,
                        "tax_amount": 0.952233241255512,
                        "total_amount": 100,
                        "principal_amortization_amount": 96.7716708593,
                        "installment_number": 3
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 21.0,
                        "business_due_date": "2025-04-07",
                        "due_date": "2025-04-07",
                        "due_principal": 98.1975100741,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.8017757157,
                        "tax_amount": 1.2158904130882027,
                        "total_amount": 100,
                        "principal_amortization_amount": 98.1982242843,
                        "installment_number": 4
                    }
                ],
                "issue_amount": 375.96,
                "disbursed_issue_amount": 367.96,
                "assignment_amount": 375.96,
                "final_disbursement_amount": 367.96,
                "prefixed_interest_rate": {
                    "interest_base": "calendar_days_365",
                    "annual_rate": 0.23872053,
                    "monthly_rate": 0.018,
                    "daily_rate": 0.00058669
                }
            },
            {
                "iof_amount": 4.71,
                "total_pre_fixed_amount": 23.8187134405,
                "cet": 0.0244,
                "annual_cet": 0.335196,
                "contract_fees": [
                    {
                        "fee_type": "tac",
                        "amount_type": "percentage",
                        "amount": 0.6,
                        "fee_amount": 2.26
                    },
                    {
                        "fee_type": "ted_fee",
                        "amount_type": "absolute",
                        "amount": 1.0,
                        "fee_amount": 1.0
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "insurance_premium",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "tac",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    }
                ],
                "contract_fee_amount": 2.26,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "disbursement_date": "2024-11-08",
                "first_due_date": "2025-01-21",
                "installments": [
                    {
                        "calendar_days": 60,
                        "workdays": 39.0,
                        "business_due_date": "2025-01-21",
                        "due_date": "2025-01-21",
                        "due_principal": 376.18,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 13.4739126445,
                        "tax_amount": 0.42570834978906,
                        "total_amount": 100,
                        "principal_amortization_amount": 86.5260873555,
                        "installment_number": 1
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 23.0,
                        "business_due_date": "2025-02-21",
                        "due_date": "2025-02-21",
                        "due_principal": 289.6539126445,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 5.3146959395,
                        "tax_amount": 0.706541738899451,
                        "total_amount": 100,
                        "principal_amortization_amount": 94.6853040605,
                        "installment_number": 2
                    },
                    {
                        "calendar_days": 28,
                        "workdays": 18.0,
                        "business_due_date": "2025-03-21",
                        "due_date": "2025-03-21",
                        "due_principal": 194.968608584,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.2283291407,
                        "tax_amount": 0.9442979642450494,
                        "total_amount": 100,
                        "principal_amortization_amount": 96.7716708593,
                        "installment_number": 3
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 21.0,
                        "business_due_date": "2025-04-21",
                        "due_date": "2025-04-21",
                        "due_principal": 98.1969377247,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.8017757158,
                        "tax_amount": 1.20783815869566,
                        "total_amount": 100,
                        "principal_amortization_amount": 98.1982242842,
                        "installment_number": 4
                    }
                ],
                "issue_amount": 376.18,
                "disbursed_issue_amount": 368.21,
                "assignment_amount": 376.18,
                "final_disbursement_amount": 368.21,
                "prefixed_interest_rate": {
                    "interest_base": "calendar_days_365",
                    "annual_rate": 0.23872053,
                    "monthly_rate": 0.018,
                    "daily_rate": 0.00058669
                }
            }
        ]
    }
}
```

**Simulação com garantia**

```json
{
    "type": "debt",
    "key": "<Debt Key>",
    "status": "finished",
    "event_datetime": "2024-11-05 16:50:00",
    "data": {
        "collaterals": [
            {
                "percentage": 1,
                "collateral_type": "private_payroll",
                "collateral_data": {
                    "employer_document_number": "07940839000159",
                    "registration_number": "99999999999-A",
                    "warranty":{
                        "severance_pay_rate":0.15,
                        "severance_fine":1000,
                        "fgts_balance":2000
                    }
                }
            }
        ],
        "interest_type": "pre_price_days",
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "interest_payment_month_period": 1,
        "principal_grace_period": 0,
        "principal_amortization_month_period": 1,
        "operation_type": "structured_operation",
        "post_fixed_interest_base": "workdays",
        "post_fixed_interest_rate": null,
        "prefixed_interest_rate": {
            "interest_base": "calendar_days_365",
            "annual_rate": 0.23872053,
            "monthly_rate": 0.018,
            "daily_rate": 0.00058669
        },
        "issue_date": "2024-11-05",
        "number_of_installments": 4,
        "requester_key": "e5eb6a0a-e003-4cbd-b702-5a25bf71af0a",
        "final_disbursement_amount": 0.0,
        "disbursement_options": [
            {
                "iof_amount": 3.93,
                "total_pre_fixed_amount": 17.8715883143,
                "cet": 0.0257,
                "annual_cet": 0.355163,
                "contract_fees": [
                    {
                        "fee_type": "tac",
                        "amount_type": "percentage",
                        "amount": 0.6,
                        "fee_amount": 2.29
                    },
                    {
                        "fee_type": "ted_fee",
                        "amount_type": "absolute",
                        "amount": 1.0,
                        "fee_amount": 1.0
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "insurance_premium",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "tac",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    }
                ],
                "contract_fee_amount": 2.29,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "disbursement_date": "2024-11-05",
                "first_due_date": "2024-12-21",
                "installments": [
                    {
                        "calendar_days": 34,
                        "workdays": 23.0,
                        "business_due_date": "2024-12-21",
                        "due_date": "2024-12-21",
                        "due_principal": 382.13,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 7.6967422515,
                        "tax_amount": 0.257341482602818,
                        "total_amount": 100,
                        "principal_amortization_amount": 92.3032577485,
                        "installment_number": 1
                    },
                    {
                        "calendar_days": 29,
                        "workdays": 19.0,
                        "business_due_date": "2025-01-21",
                        "due_date": "2025-01-21",
                        "due_principal": 289.8267422515,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 4.9718040699,
                        "tax_amount": 0.4909156601748966,
                        "total_amount": 100,
                        "principal_amortization_amount": 95.0281959301,
                        "installment_number": 2
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 23.0,
                        "business_due_date": "2025-02-21",
                        "due_date": "2025-02-21",
                        "due_principal": 194.7985463214,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.5742034136,
                        "tax_amount": 0.7432500400879712,
                        "total_amount": 100,
                        "principal_amortization_amount": 96.4257965864,
                        "installment_number": 3
                    },
                    {
                        "calendar_days": 28,
                        "workdays": 18.0,
                        "business_due_date": "2025-03-21",
                        "due_date": "2025-03-21",
                        "due_principal": 98.372749735,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.6288385793,
                        "tax_amount": 0.9841050988526828,
                        "total_amount": 100,
                        "principal_amortization_amount": 98.3711614207,
                        "installment_number": 4
                    }
                ],
                "issue_amount": 382.13,
                "disbursed_issue_amount": 374.91,
                "assignment_amount": 382.13,
                "final_disbursement_amount": 374.91,
                "prefixed_interest_rate": {
                    "interest_base": "calendar_days_365",
                    "annual_rate": 0.23872053,
                    "monthly_rate": 0.018,
                    "daily_rate": 0.00058669
                }
            },
            {
                "iof_amount": 4.77,
                "total_pre_fixed_amount": 24.2597288075,
                "cet": 0.0243,
                "annual_cet": 0.334037,
                "contract_fees": [
                    {
                        "fee_type": "tac",
                        "amount_type": "percentage",
                        "amount": 0.6,
                        "fee_amount": 2.25
                    },
                    {
                        "fee_type": "ted_fee",
                        "amount_type": "absolute",
                        "amount": 1.0,
                        "fee_amount": 1.0
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "insurance_premium",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "tac",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    }
                ],
                "contract_fee_amount": 2.25,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "disbursement_date": "2024-11-06",
                "first_due_date": "2025-01-21",
                "installments": [
                    {
                        "calendar_days": 62,
                        "workdays": 41.0,
                        "business_due_date": "2025-01-21",
                        "due_date": "2025-01-21",
                        "due_principal": 375.74,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 13.9149280115,
                        "tax_amount": 0.437656505989534,
                        "total_amount": 100,
                        "principal_amortization_amount": 86.0850719885,
                        "installment_number": 1
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 23.0,
                        "business_due_date": "2025-02-21",
                        "due_date": "2025-02-21",
                        "due_principal": 289.6549280115,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 5.3146959395,
                        "tax_amount": 0.722070128765373,
                        "total_amount": 100,
                        "principal_amortization_amount": 94.6853040605,
                        "installment_number": 2
                    },
                    {
                        "calendar_days": 28,
                        "workdays": 18.0,
                        "business_due_date": "2025-03-21",
                        "due_date": "2025-03-21",
                        "due_principal": 194.969623951,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.2283291407,
                        "tax_amount": 0.9601685182659746,
                        "total_amount": 100,
                        "principal_amortization_amount": 96.7716708593,
                        "installment_number": 3
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 21.0,
                        "business_due_date": "2025-04-07",
                        "due_date": "2025-04-07",
                        "due_principal": 98.1979530917,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.8017757158,
                        "tax_amount": 1.2239426674782687,
                        "total_amount": 100,
                        "principal_amortization_amount": 98.1982242842,
                        "installment_number": 4
                    }
                ],
                "issue_amount": 375.74,
                "disbursed_issue_amount": 367.72,
                "assignment_amount": 375.74,
                "final_disbursement_amount": 367.72,
                "prefixed_interest_rate": {
                    "interest_base": "calendar_days_365",
                    "annual_rate": 0.23872053,
                    "monthly_rate": 0.018,
                    "daily_rate": 0.00058669
                }
            },
            {
                "iof_amount": 4.74,
                "total_pre_fixed_amount": 24.0392857898,
                "cet": 0.0243,
                "annual_cet": 0.334673,
                "contract_fees": [
                    {
                        "fee_type": "tac",
                        "amount_type": "percentage",
                        "amount": 0.6,
                        "fee_amount": 2.26
                    },
                    {
                        "fee_type": "ted_fee",
                        "amount_type": "absolute",
                        "amount": 1.0,
                        "fee_amount": 1.0
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "insurance_premium",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "tac",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    }
                ],
                "contract_fee_amount": 2.26,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "disbursement_date": "2024-11-07",
                "first_due_date": "2025-01-21",
                "installments": [
                    {
                        "calendar_days": 61,
                        "workdays": 40.0,
                        "business_due_date": "2025-01-21",
                        "due_date": "2025-01-21",
                        "due_principal": 375.96,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 13.6944849939,
                        "tax_amount": 0.4317001860605122,
                        "total_amount": 100,
                        "principal_amortization_amount": 86.3055150061,
                        "installment_number": 1
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 23.0,
                        "business_due_date": "2025-02-21",
                        "due_date": "2025-02-21",
                        "due_principal": 289.6544849939,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 5.3146959395,
                        "tax_amount": 0.714305933832412,
                        "total_amount": 100,
                        "principal_amortization_amount": 94.6853040605,
                        "installment_number": 2
                    },
                    {
                        "calendar_days": 28,
                        "workdays": 18.0,
                        "business_due_date": "2025-03-21",
                        "due_date": "2025-03-21",
                        "due_principal": 194.9691809334,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.2283291407,
                        "tax_amount": 0.952233241255512,
                        "total_amount": 100,
                        "principal_amortization_amount": 96.7716708593,
                        "installment_number": 3
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 21.0,
                        "business_due_date": "2025-04-07",
                        "due_date": "2025-04-07",
                        "due_principal": 98.1975100741,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.8017757157,
                        "tax_amount": 1.2158904130882027,
                        "total_amount": 100,
                        "principal_amortization_amount": 98.1982242843,
                        "installment_number": 4
                    }
                ],
                "issue_amount": 375.96,
                "disbursed_issue_amount": 367.96,
                "assignment_amount": 375.96,
                "final_disbursement_amount": 367.96,
                "prefixed_interest_rate": {
                    "interest_base": "calendar_days_365",
                    "annual_rate": 0.23872053,
                    "monthly_rate": 0.018,
                    "daily_rate": 0.00058669
                }
            },
            {
                "iof_amount": 4.71,
                "total_pre_fixed_amount": 23.8187134405,
                "cet": 0.0244,
                "annual_cet": 0.335196,
                "contract_fees": [
                    {
                        "fee_type": "tac",
                        "amount_type": "percentage",
                        "amount": 0.6,
                        "fee_amount": 2.26
                    },
                    {
                        "fee_type": "ted_fee",
                        "amount_type": "absolute",
                        "amount": 1.0,
                        "fee_amount": 1.0
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "insurance_premium",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "tac",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    }
                ],
                "contract_fee_amount": 2.26,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "disbursement_date": "2024-11-08",
                "first_due_date": "2025-01-21",
                "installments": [
                    {
                        "calendar_days": 60,
                        "workdays": 39.0,
                        "business_due_date": "2025-01-21",
                        "due_date": "2025-01-21",
                        "due_principal": 376.18,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 13.4739126445,
                        "tax_amount": 0.42570834978906,
                        "total_amount": 100,
                        "principal_amortization_amount": 86.5260873555,
                        "installment_number": 1
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 23.0,
                        "business_due_date": "2025-02-21",
                        "due_date": "2025-02-21",
                        "due_principal": 289.6539126445,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 5.3146959395,
                        "tax_amount": 0.706541738899451,
                        "total_amount": 100,
                        "principal_amortization_amount": 94.6853040605,
                        "installment_number": 2
                    },
                    {
                        "calendar_days": 28,
                        "workdays": 18.0,
                        "business_due_date": "2025-03-21",
                        "due_date": "2025-03-21",
                        "due_principal": 194.968608584,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.2283291407,
                        "tax_amount": 0.9442979642450494,
                        "total_amount": 100,
                        "principal_amortization_amount": 96.7716708593,
                        "installment_number": 3
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 21.0,
                        "business_due_date": "2025-04-21",
                        "due_date": "2025-04-21",
                        "due_principal": 98.1969377247,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.8017757158,
                        "tax_amount": 1.20783815869566,
                        "total_amount": 100,
                        "principal_amortization_amount": 98.1982242842,
                        "installment_number": 4
                    }
                ],
                "issue_amount": 376.18,
                "disbursed_issue_amount": 368.21,
                "assignment_amount": 376.18,
                "final_disbursement_amount": 368.21,
                "prefixed_interest_rate": {
                    "interest_base": "calendar_days_365",
                    "annual_rate": 0.23872053,
                    "monthly_rate": 0.018,
                    "daily_rate": 0.00058669
                }
            }
        ]
    }
}
```

---

## 2 - Emissão da operação:
O campo "registration_number", localizado dentro do objeto "collateral_data", refere-se ao número de matrícula de um vínculo empregatício. O mesmo é retornado na consulta de vínculos empregatícios.

CRÉDITO NOVO

### Request

**POST**
/debt

Testar no Playground

**Sem representante legal**

```json title='Request Body'
{
    "borrower": {
        "name": "Nome devedor",
        "email":"email.devedor@gmail.com",
        "phone": {
            "number": "999538380",
            "area_code": "84",
            "country_code": "055"
        },
        "gender": "female",
        "political_exposition": "not_exposed",
        "address": {
            "city": "Natal",
            "state": "RN",
            "number": "1984",
            "street": "Rua",
            "complement": "complemento",
            "postal_code": "59065720",
            "neighborhood": "bairro"
        },
        "role_type": "issuer",
        "birth_date": "1959-07-08",
        "mother_name": "NOME DA MAE",
        "nationality": "Brasileiro",
        "person_type": "natural",
        "marital_status": "single",
        "attached_documents_list": [],
        "individual_document_number": "14471835092",
        "document_identification_date": "2015-10-02",
        "document_identification_type": "rg",
        "document_identification_number": "003709888"
    },
    "financial": {
        "interest_type": "pre_price_days",
        "first_due_date": "2023-09-21",
        "disbursement_date": "2024-11-07",
        "fine_configuration": {
            "monthly_rate": 0.0166,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "monthly_interest_rate": 0.0166,
        "installment_face_value": 101.84,
        "limit_days_to_disburse": 7,
        "number_of_installments": 10,
        "principal_grace_period": 0,
        "rebates": [ // Opcional
            {
                "amount": 20,
                "rebate_bank_account": {
                    "name": "Teste Ltda",
                    "document_number": "18533555000164",
                    "account_digit": "0",
                    "account_number": "4290001",
                    "branch_number": "0001",
                    "bank_code": "329"
                },
                "amount_type": "percentage",
                "fee_type": "spread"
            }
        ]
    },
    "simplified": true,
    "collaterals": [
        {
            "percentage": 1,
            "collateral_type": "private_payroll",
            "collateral_data": {
                "employer_document_number": "07940839000159",
                "registration_number": "99999999999-A"
            }
        }
    ],
    "additional_data": {
        "contract": {
            "contract_number": "TST0000644799"
        }
    },
    "purchaser_document_number": "32402502000135",
    "disbursement_bank_accounts": [
        {
            "name": "NOME DEVEDOR",
            "bank_code": "001",
            "account_digit": "0",
            "branch_number": "2874",
            "account_number": "000057555",
            "document_number": "14471835092",
            "transfer_method": "pix",
            "percentage_receivable": 100
        }
    ]
}
```

**Com representante legal**

```json title='Request Body'
{
    "borrower": {
        "name": "Nome devedor",
        "phone": {
            "number": "999538380",
            "area_code": "84",
            "country_code": "055"
        },
        "gender": "female",
        "political_exposition": "not_exposed",
        "address": {
            "city": "Natal",
            "state": "RN",
            "number": "1984",
            "street": "Rua",
            "complement": "complemento",
            "postal_code": "59065720",
            "neighborhood": "bairro"
        },
        "role_type": "issuer",
        "birth_date": "1959-07-08",
        "mother_name": "NOME DA MAE",
        "nationality": "Brasileiro",
        "person_type": "natural",
        "marital_status": "single",
        "attached_documents_list": [],
        "individual_document_number": "14471835092",
        "document_identification_date": "2015-10-02",
        "document_identification_type": "rg",
        "document_identification_number": "003709888"
    },
    "related_parties": [
        {
            "role_type": "issuer_legal_representative",
            "person_type": "natural",
            "name": "REPRESENTANTE EXEMPLO",
            "email": "representante.exemplo@exemplo.com",
            "individual_document_number": "79795844067",
            "birth_date": "1970-04-20",
            "mother_name": "MÃE DO REPRESENTANTE",
            "phone": {
                "country_code": "55",
                "area_code": "11",
                "number": "999999999"
            },
            "address": {
                "street": "RUA EXEMPLO",
                "number": "123",
                "complement": "APTO 123",
                "neighborhood": "BAIRRO EXEMPLO",
                "postal_code": "12345678",
                "city": "SÃO PAULO",
                "state": "SP"
            }
        }
    ],
    "financial": {
        "interest_type": "pre_price_days",
        "first_due_date": "2024-09-21",
        "disbursement_date": "2024-11-07",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "monthly_interest_rate": 0.0166,
        "installment_face_value": 1000,
        "limit_days_to_disburse": 7,
        "number_of_installments": 84,
        "principal_grace_period": 0,
        "rebates": [ // Opcional
            {
                "amount": 20,
                "rebate_bank_account": {
                    "name": "Teste Ltda",
                    "document_number": "18533555000164",
                    "account_digit": "0",
                    "account_number": "4290001",
                    "branch_number": "0001",
                    "bank_code": "329"
                },
                "amount_type": "percentage",
                "fee_type": "spread"
            }
        ]
    },
    "simplified": true,
    "collaterals": [
        {
            "percentage": 1,
            "collateral_type": "private_payroll",
            "collateral_data": {
                "employer_document_number": "07940839000159",
                "registration_number": "99999999999-A"
            }
        }
    ],
    "additional_data": {
        "contract": {
            "contract_number": "TST0000644715"
        }
    },
    "purchaser_document_number": "32402502000135",
    "disbursement_bank_accounts": [
        {
            "name": "NOME DEVEDOR",
            "bank_code": "001",
            "account_digit": "0",
            "branch_number": "2874",
            "account_number": "000057555",
            "document_number": "14471835092",
            "transfer_method": "pix",
            "percentage_receivable": 100
        }
    ]
}
```

**Com garantia**

```json title='Request Body'
{
    "borrower": {
        "name": "Nome devedor",
        "email":"email.devedor@gmail.com",
        "phone": {
            "number": "999538380",
            "area_code": "84",
            "country_code": "055"
        },
        "gender": "female",
        "political_exposition": "not_exposed",
        "address": {
            "city": "Natal",
            "state": "RN",
            "number": "1984",
            "street": "Rua",
            "complement": "complemento",
            "postal_code": "59065720",
            "neighborhood": "bairro"
        },
        "role_type": "issuer",
        "birth_date": "1959-07-08",
        "mother_name": "NOME DA MAE",
        "nationality": "Brasileiro",
        "person_type": "natural",
        "marital_status": "single",
        "attached_documents_list": [],
        "individual_document_number": "14471835092",
        "document_identification_date": "2015-10-02",
        "document_identification_type": "rg",
        "document_identification_number": "003709888"
    },
    "financial": {
        "interest_type": "pre_price_days",
        "first_due_date": "2023-09-21",
        "disbursement_date": "2024-11-07",
        "fine_configuration": {
            "monthly_rate": 0.0166,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "monthly_interest_rate": 0.0166,
        "installment_face_value": 101.84,
        "limit_days_to_disburse": 7,
        "number_of_installments": 10,
        "principal_grace_period": 0,
        "rebates": [ // Opcional
            {
                "amount": 20,
                "rebate_bank_account": {
                    "name": "Teste Ltda",
                    "document_number": "18533555000164",
                    "account_digit": "0",
                    "account_number": "4290001",
                    "branch_number": "0001",
                    "bank_code": "329"
                },
                "amount_type": "percentage",
                "fee_type": "spread"
            }
        ]
    },
    "simplified": true,
    "collaterals": [
        {
            "percentage": 1,
            "collateral_type": "private_payroll",
            "collateral_data": {
                "employer_document_number": "07940839000159",
                "registration_number": "99999999999-A",
                "warranted": true
            }
        }
    ],
    "additional_data": {
        "contract": {
            "contract_number": "TST0000644799"
        }
    },
    "purchaser_document_number": "32402502000135",
    "disbursement_bank_accounts": [
        {
            "name": "NOME DEVEDOR",
            "bank_code": "001",
            "account_digit": "0",
            "branch_number": "2874",
            "account_number": "000057555",
            "document_number": "14471835092",
            "transfer_method": "pix",
            "percentage_receivable": 100
        }
    ]
}
```

### Response

STATUS
**201** (Created)

**Response Body**

```json title="Response Body"
{
    "webhook_type": "debt",
    "key": "<Debt Key>",
    "status": "waiting_signature",
    "event_datetime": "2024-11-07 23:19:22",
    "data": {
        "borrower": {
            "name": "Nome devedor",
            "document_number": "14471835092",
            "related_party_key": "28b7fc16-6d1f-467d-9667-62a8c13daea6"
        },
        "contract": {
            "number": "TST0000644710",
            "urls": [
                "https://storage.googleapis.com/sandbox-doc-api/documents/a2e9c83a-3666-4def-8b27-e96fabb8705c/NOME_DEVEDOR-CCB-TST0000644710-20241107231916.pdf"
            ],
            "signature_information": [
                {
                    "signer_name": "Nome devedor",
                    "signer_document_number": "14471835092",
                    "signer_role": "issuer",
                    "signer_email": null,
                    "signer_external_key": null,
                    "signature_url": null
                }
            ]
        },
        "requester_identifier_key": "eb859ebe-3a41-49bf-a6c3-d6902039ec00",
        "iof_charge_method": "financed",
        "collaterals": [
            {
                "absolute_amount": null,
                "collateral_constituted": false,
                "collateral_data": {
                    "registration_number": "99999999999-A",
                    "employer_document_number": "07940839000159"
                },
                "collateral_key": "26c7f4f4-51f3-41fa-b880-9691211136aa",
                "collateral_type": "private_payroll",
                "created_at": "2024-11-07T23:19:16.413448",
                "external_key": null,
                "percentage": 1,
                "updated_at": "2024-11-07T23:19:16.413441"
            }
        ],
        "disbursement_options": [
            {
                "disbursement_date": "2024-11-07",
                "contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 4.55
                    },
                    {
                        "fee_type": "ted_fee",
                        "fee_amount": 1.5
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0
                    }
                ],
                "contract_fee_amount": 6.05,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "assignment_amount": 914.3,
                "issue_amount": 909.75,
                "cet": "2,0100%",
                "annual_cet": "27,0481%",
                "base_iof": 16.259002146803677,
                "additional_iof": 3.45705,
                "total_iof": 19.72,
                "total_pre_fixed_amount": 108.6508885851,
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-01-21",
                        "calendar_days": 74,
                        "due_date": "2025-01-21",
                        "due_interest": 0.0,
                        "due_principal": 909.75,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 37.1789024864,
                        "principal_amortization_amount": 64.6610975136,
                        "tax_amount": 0.3923635397125248,
                        "total_amount": 101.84,
                        "workdays": 49.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-02-21",
                        "calendar_days": 31,
                        "due_date": "2025-02-21",
                        "due_interest": 0.0,
                        "due_principal": 845.0889024864,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 2,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 14.2997636051,
                        "principal_amortization_amount": 87.5402363949,
                        "tax_amount": 0.753721435360089,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-03-21",
                        "calendar_days": 28,
                        "due_date": "2025-03-21",
                        "due_interest": 0.0,
                        "due_principal": 757.5486660915,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 3,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 11.5685715131,
                        "principal_amortization_amount": 90.2714284869,
                        "tax_amount": 0.9845001990781314,
                        "total_amount": 101.84,
                        "workdays": 18.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-04-21",
                        "calendar_days": 33,
                        "due_date": "2025-04-21",
                        "due_interest": 0.0,
                        "due_principal": 667.2772376046,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 4,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 12.025984633,
                        "principal_amortization_amount": 89.814015367,
                        "tax_amount": 1.222548377175604,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-05-21",
                        "calendar_days": 28,
                        "due_date": "2025-05-21",
                        "due_interest": 0.0,
                        "due_principal": 577.4632222376,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 5,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.8184725787,
                        "principal_amortization_amount": 93.0215274213,
                        "tax_amount": 1.4797864582180404,
                        "total_amount": 101.84,
                        "workdays": 19.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-06-21",
                        "calendar_days": 31,
                        "due_date": "2025-06-21",
                        "due_interest": 0.0,
                        "due_principal": 484.4416948163,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 6,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.1972396908,
                        "principal_amortization_amount": 93.6427603092,
                        "tax_amount": 1.72770892770474,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-07-21",
                        "calendar_days": 31,
                        "due_date": "2025-07-21",
                        "due_interest": 0.0,
                        "due_principal": 390.7989345071,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 7,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 6.6127072945,
                        "principal_amortization_amount": 95.2272927055,
                        "tax_amount": 1.999011328473856,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-08-21",
                        "calendar_days": 30,
                        "due_date": "2025-08-21",
                        "due_interest": 0.0,
                        "due_principal": 295.5716418016,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 8,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 4.8387153664,
                        "principal_amortization_amount": 97.0012846336,
                        "tax_amount": 2.274874127227187,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-09-21",
                        "calendar_days": 33,
                        "due_date": "2025-09-21",
                        "due_interest": 0.0,
                        "due_principal": 198.570357168,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 9,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.5787172455,
                        "principal_amortization_amount": 98.2612827545,
                        "tax_amount": 2.570318634292211,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-10-21",
                        "calendar_days": 28,
                        "due_date": "2025-10-21",
                        "due_interest": 0.0,
                        "due_principal": 100.3090744135,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 10,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.5318141716,
                        "principal_amortization_amount": 100.3081858284,
                        "tax_amount": 2.8541691195612935,
                        "total_amount": 101.84,
                        "workdays": 20.0,
                        "installment_status": null,
                        "installment_type": null
                    }
                ],
                "first_due_date": "2025-01-21",
                "prefixed_interest_rate": {
                    "monthly_rate": 0.0166,
                    "daily_rate": 0.00054142,
                    "annual_rate": 0.21843191,
                    "interest_base": "calendar_days_365"
                }
            },
            {
                "disbursement_date": "2024-11-08",
                "contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 4.55
                    },
                    {
                        "fee_type": "ted_fee",
                        "fee_amount": 1.5
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0
                    }
                ],
                "contract_fee_amount": 6.05,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "assignment_amount": 914.79,
                "issue_amount": 910.24,
                "cet": "2,0200%",
                "annual_cet": "27,0539%",
                "base_iof": 16.187351160427028,
                "additional_iof": 3.458912,
                "total_iof": 19.65,
                "total_pre_fixed_amount": 108.1583324947,
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-01-21",
                        "calendar_days": 73,
                        "due_date": "2025-01-21",
                        "due_interest": 0.0,
                        "due_principal": 910.24,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 36.6863463961,
                        "principal_amortization_amount": 65.1536536039,
                        "tax_amount": 0.3900097704729454,
                        "total_amount": 101.84,
                        "workdays": 48.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-02-21",
                        "calendar_days": 31,
                        "due_date": "2025-02-21",
                        "due_interest": 0.0,
                        "due_principal": 845.0863463961,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 2,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 14.2997636051,
                        "principal_amortization_amount": 87.5402363949,
                        "tax_amount": 0.7465431359757072,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-03-21",
                        "calendar_days": 28,
                        "due_date": "2025-03-21",
                        "due_interest": 0.0,
                        "due_principal": 757.5461100012,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 3,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 11.5685715131,
                        "principal_amortization_amount": 90.2714284869,
                        "tax_amount": 0.9770979419422056,
                        "total_amount": 101.84,
                        "workdays": 18.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-04-21",
                        "calendar_days": 33,
                        "due_date": "2025-04-21",
                        "due_interest": 0.0,
                        "due_principal": 667.2746815143,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 4,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 12.025984633,
                        "principal_amortization_amount": 89.814015367,
                        "tax_amount": 1.21518362791551,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-05-21",
                        "calendar_days": 28,
                        "due_date": "2025-05-21",
                        "due_interest": 0.0,
                        "due_principal": 577.4606661473,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 5,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.8184725787,
                        "principal_amortization_amount": 93.0215274213,
                        "tax_amount": 1.4721586929694939,
                        "total_amount": 101.84,
                        "workdays": 19.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-06-21",
                        "calendar_days": 31,
                        "due_date": "2025-06-21",
                        "due_interest": 0.0,
                        "due_principal": 484.439138726,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 6,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.1972396908,
                        "principal_amortization_amount": 93.6427603092,
                        "tax_amount": 1.7200302213593857,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-07-21",
                        "calendar_days": 31,
                        "due_date": "2025-07-21",
                        "due_interest": 0.0,
                        "due_principal": 390.7963784168,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 7,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 6.6127072945,
                        "principal_amortization_amount": 95.2272927055,
                        "tax_amount": 1.991202690472005,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-08-21",
                        "calendar_days": 30,
                        "due_date": "2025-08-21",
                        "due_interest": 0.0,
                        "due_principal": 295.5690857113,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 8,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 4.8387153664,
                        "principal_amortization_amount": 97.0012846336,
                        "tax_amount": 2.266920021887232,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-09-21",
                        "calendar_days": 33,
                        "due_date": "2025-09-21",
                        "due_interest": 0.0,
                        "due_principal": 198.5678010777,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 9,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.5787172455,
                        "principal_amortization_amount": 98.2612827545,
                        "tax_amount": 2.562261209106342,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-10-21",
                        "calendar_days": 28,
                        "due_date": "2025-10-21",
                        "due_interest": 0.0,
                        "due_principal": 100.3065183232,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 10,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.5318141715,
                        "principal_amortization_amount": 100.3081858285,
                        "tax_amount": 2.845943848326202,
                        "total_amount": 101.84,
                        "workdays": 20.0,
                        "installment_status": null,
                        "installment_type": null
                    }
                ],
                "first_due_date": "2025-01-21",
                "prefixed_interest_rate": {
                    "monthly_rate": 0.0166,
                    "daily_rate": 0.00054142,
                    "annual_rate": 0.21843191,
                    "interest_base": "calendar_days_365"
                }
            },
            {
                "disbursement_date": "2024-11-09",
                "contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 4.55
                    },
                    {
                        "fee_type": "ted_fee",
                        "fee_amount": 1.5
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0
                    }
                ],
                "contract_fee_amount": 6.05,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "assignment_amount": 915.28,
                "issue_amount": 910.73,
                "cet": "2,0200%",
                "annual_cet": "27,0599%",
                "base_iof": 16.115620969325082,
                "additional_iof": 3.460774,
                "total_iof": 19.58,
                "total_pre_fixed_amount": 107.6655097248,
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-01-21",
                        "calendar_days": 72,
                        "due_date": "2025-01-21",
                        "due_interest": 0.0,
                        "due_principal": 910.73,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 36.1935236262,
                        "principal_amortization_amount": 65.6464763738,
                        "tax_amount": 0.3875767965109152,
                        "total_amount": 101.84,
                        "workdays": 48.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-02-21",
                        "calendar_days": 31,
                        "due_date": "2025-02-21",
                        "due_interest": 0.0,
                        "due_principal": 845.0835236262,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 2,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 14.2997636051,
                        "principal_amortization_amount": 87.5402363949,
                        "tax_amount": 0.7393648365913253,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-03-21",
                        "calendar_days": 28,
                        "due_date": "2025-03-21",
                        "due_interest": 0.0,
                        "due_principal": 757.5432872313,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 3,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 11.5685715131,
                        "principal_amortization_amount": 90.2714284869,
                        "tax_amount": 0.9696956848062798,
                        "total_amount": 101.84,
                        "workdays": 18.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-04-21",
                        "calendar_days": 33,
                        "due_date": "2025-04-21",
                        "due_interest": 0.0,
                        "due_principal": 667.2718587444,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 4,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 12.025984633,
                        "principal_amortization_amount": 89.814015367,
                        "tax_amount": 1.207818878655416,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-05-21",
                        "calendar_days": 28,
                        "due_date": "2025-05-21",
                        "due_interest": 0.0,
                        "due_principal": 577.4578433774,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 5,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.8184725787,
                        "principal_amortization_amount": 93.0215274213,
                        "tax_amount": 1.4645309277209473,
                        "total_amount": 101.84,
                        "workdays": 19.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-06-21",
                        "calendar_days": 31,
                        "due_date": "2025-06-21",
                        "due_interest": 0.0,
                        "due_principal": 484.4363159561,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 6,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.1972396908,
                        "principal_amortization_amount": 93.6427603092,
                        "tax_amount": 1.7123515150140312,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-07-21",
                        "calendar_days": 31,
                        "due_date": "2025-07-21",
                        "due_interest": 0.0,
                        "due_principal": 390.7935556469,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 7,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 6.6127072945,
                        "principal_amortization_amount": 95.2272927055,
                        "tax_amount": 1.983394052470154,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-08-21",
                        "calendar_days": 30,
                        "due_date": "2025-08-21",
                        "due_interest": 0.0,
                        "due_principal": 295.5662629414,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 8,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 4.8387153664,
                        "principal_amortization_amount": 97.0012846336,
                        "tax_amount": 2.2589659165472766,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-09-21",
                        "calendar_days": 33,
                        "due_date": "2025-09-21",
                        "due_interest": 0.0,
                        "due_principal": 198.5649783078,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 9,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.5787172455,
                        "principal_amortization_amount": 98.2612827545,
                        "tax_amount": 2.554203783920473,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-10-21",
                        "calendar_days": 28,
                        "due_date": "2025-10-21",
                        "due_interest": 0.0,
                        "due_principal": 100.3036955533,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 10,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.5318141715,
                        "principal_amortization_amount": 100.3081858285,
                        "tax_amount": 2.837718577088265,
                        "total_amount": 101.84,
                        "workdays": 20.0,
                        "installment_status": null,
                        "installment_type": null
                    }
                ],
                "first_due_date": "2025-01-21",
                "prefixed_interest_rate": {
                    "monthly_rate": 0.0166,
                    "daily_rate": 0.00054142,
                    "annual_rate": 0.21843191,
                    "interest_base": "calendar_days_365"
                }
            },
            {
                "disbursement_date": "2024-11-10",
                "contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 4.56
                    },
                    {
                        "fee_type": "ted_fee",
                        "fee_amount": 1.5
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0
                    }
                ],
                "contract_fee_amount": 6.06,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "assignment_amount": 915.79,
                "issue_amount": 911.23,
                "cet": "2,0200%",
                "annual_cet": "27,0635%",
                "base_iof": 16.0438115087348,
                "additional_iof": 3.462674,
                "total_iof": 19.51,
                "total_pre_fixed_amount": 107.1724201311,
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-01-21",
                        "calendar_days": 71,
                        "due_date": "2025-01-21",
                        "due_interest": 0.0,
                        "due_principal": 911.23,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 35.7004340324,
                        "principal_amortization_amount": 66.1395659676,
                        "tax_amount": 0.3850645530633672,
                        "total_amount": 101.84,
                        "workdays": 48.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-02-21",
                        "calendar_days": 31,
                        "due_date": "2025-02-21",
                        "due_interest": 0.0,
                        "due_principal": 845.0904340324,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 2,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 14.2997636051,
                        "principal_amortization_amount": 87.5402363949,
                        "tax_amount": 0.7321865372069436,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-03-21",
                        "calendar_days": 28,
                        "due_date": "2025-03-21",
                        "due_interest": 0.0,
                        "due_principal": 757.5501976375,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 3,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 11.5685715131,
                        "principal_amortization_amount": 90.2714284869,
                        "tax_amount": 0.962293427670354,
                        "total_amount": 101.84,
                        "workdays": 18.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-04-21",
                        "calendar_days": 33,
                        "due_date": "2025-04-21",
                        "due_interest": 0.0,
                        "due_principal": 667.2787691506,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 4,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 12.025984633,
                        "principal_amortization_amount": 89.814015367,
                        "tax_amount": 1.200454129395322,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-05-21",
                        "calendar_days": 28,
                        "due_date": "2025-05-21",
                        "due_interest": 0.0,
                        "due_principal": 577.4647537836,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 5,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.8184725787,
                        "principal_amortization_amount": 93.0215274213,
                        "tax_amount": 1.4569031624724007,
                        "total_amount": 101.84,
                        "workdays": 19.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-06-21",
                        "calendar_days": 31,
                        "due_date": "2025-06-21",
                        "due_interest": 0.0,
                        "due_principal": 484.4432263623,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 6,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.1972396908,
                        "principal_amortization_amount": 93.6427603092,
                        "tax_amount": 1.7046728086686769,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-07-21",
                        "calendar_days": 31,
                        "due_date": "2025-07-21",
                        "due_interest": 0.0,
                        "due_principal": 390.8004660531,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 7,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 6.6127072945,
                        "principal_amortization_amount": 95.2272927055,
                        "tax_amount": 1.975585414468303,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-08-21",
                        "calendar_days": 30,
                        "due_date": "2025-08-21",
                        "due_interest": 0.0,
                        "due_principal": 295.5731733476,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 8,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 4.8387153664,
                        "principal_amortization_amount": 97.0012846336,
                        "tax_amount": 2.2510118112073214,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-09-21",
                        "calendar_days": 33,
                        "due_date": "2025-09-21",
                        "due_interest": 0.0,
                        "due_principal": 198.571888714,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 9,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.5787172455,
                        "principal_amortization_amount": 98.2612827545,
                        "tax_amount": 2.546146358734604,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-10-21",
                        "calendar_days": 28,
                        "due_date": "2025-10-21",
                        "due_interest": 0.0,
                        "due_principal": 100.3106059595,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 10,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.5318141716,
                        "principal_amortization_amount": 100.3081858284,
                        "tax_amount": 2.829493305847507,
                        "total_amount": 101.84,
                        "workdays": 20.0,
                        "installment_status": null,
                        "installment_type": null
                    }
                ],
                "first_due_date": "2025-01-21",
                "prefixed_interest_rate": {
                    "monthly_rate": 0.0166,
                    "daily_rate": 0.00054142,
                    "annual_rate": 0.21843191,
                    "interest_base": "calendar_days_365"
                }
            },
            {
                "disbursement_date": "2024-11-11",
                "contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 4.56
                    },
                    {
                        "fee_type": "ted_fee",
                        "fee_amount": 1.5
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0
                    }
                ],
                "contract_fee_amount": 6.06,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "assignment_amount": 916.28,
                "issue_amount": 911.72,
                "cet": "2,0200%",
                "annual_cet": "27,0698%",
                "base_iof": 15.971922713858204,
                "additional_iof": 3.464536,
                "total_iof": 19.44,
                "total_pre_fixed_amount": 106.6790635687,
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-01-21",
                        "calendar_days": 70,
                        "due_date": "2025-01-21",
                        "due_interest": 0.0,
                        "due_principal": 911.72,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 35.2070774702,
                        "principal_amortization_amount": 66.6329225298,
                        "tax_amount": 0.382472975321052,
                        "total_amount": 101.84,
                        "workdays": 47.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-02-21",
                        "calendar_days": 31,
                        "due_date": "2025-02-21",
                        "due_interest": 0.0,
                        "due_principal": 845.0870774702,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 2,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 14.2997636051,
                        "principal_amortization_amount": 87.5402363949,
                        "tax_amount": 0.7250082378225619,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-03-21",
                        "calendar_days": 28,
                        "due_date": "2025-03-21",
                        "due_interest": 0.0,
                        "due_principal": 757.5468410753,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 3,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 11.5685715131,
                        "principal_amortization_amount": 90.2714284869,
                        "tax_amount": 0.9548911705344282,
                        "total_amount": 101.84,
                        "workdays": 18.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-04-21",
                        "calendar_days": 33,
                        "due_date": "2025-04-21",
                        "due_interest": 0.0,
                        "due_principal": 667.2754125884,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 4,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 12.025984633,
                        "principal_amortization_amount": 89.814015367,
                        "tax_amount": 1.193089380135228,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-05-21",
                        "calendar_days": 28,
                        "due_date": "2025-05-21",
                        "due_interest": 0.0,
                        "due_principal": 577.4613972214,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 5,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.8184725787,
                        "principal_amortization_amount": 93.0215274213,
                        "tax_amount": 1.449275397223854,
                        "total_amount": 101.84,
                        "workdays": 19.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-06-21",
                        "calendar_days": 31,
                        "due_date": "2025-06-21",
                        "due_interest": 0.0,
                        "due_principal": 484.4398698001,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 6,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.1972396908,
                        "principal_amortization_amount": 93.6427603092,
                        "tax_amount": 1.6969941023233224,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-07-21",
                        "calendar_days": 31,
                        "due_date": "2025-07-21",
                        "due_interest": 0.0,
                        "due_principal": 390.7971094909,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 7,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 6.6127072945,
                        "principal_amortization_amount": 95.2272927055,
                        "tax_amount": 1.967776776466452,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-08-21",
                        "calendar_days": 30,
                        "due_date": "2025-08-21",
                        "due_interest": 0.0,
                        "due_principal": 295.5698167854,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 8,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 4.8387153664,
                        "principal_amortization_amount": 97.0012846336,
                        "tax_amount": 2.243057705867366,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-09-21",
                        "calendar_days": 33,
                        "due_date": "2025-09-21",
                        "due_interest": 0.0,
                        "due_principal": 198.5685321518,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 9,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.5787172455,
                        "principal_amortization_amount": 98.2612827545,
                        "tax_amount": 2.538088933548735,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-10-21",
                        "calendar_days": 28,
                        "due_date": "2025-10-21",
                        "due_interest": 0.0,
                        "due_principal": 100.3072493973,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 10,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.5318141714,
                        "principal_amortization_amount": 100.3081858286,
                        "tax_amount": 2.8212680346152035,
                        "total_amount": 101.84,
                        "workdays": 20.0,
                        "installment_status": null,
                        "installment_type": null
                    }
                ],
                "first_due_date": "2025-01-21",
                "prefixed_interest_rate": {
                    "monthly_rate": 0.0166,
                    "daily_rate": 0.00054142,
                    "annual_rate": 0.21843191,
                    "interest_base": "calendar_days_365"
                }
            },
            {
                "disbursement_date": "2024-11-12",
                "contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 4.56
                    },
                    {
                        "fee_type": "ted_fee",
                        "fee_amount": 1.5
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0
                    }
                ],
                "contract_fee_amount": 6.06,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "assignment_amount": 916.77,
                "issue_amount": 912.21,
                "cet": "2,0200%",
                "annual_cet": "27,0762%",
                "base_iof": 15.899954519820076,
                "additional_iof": 3.466398,
                "total_iof": 19.37,
                "total_pre_fixed_amount": 106.1854398936,
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-01-21",
                        "calendar_days": 69,
                        "due_date": "2025-01-21",
                        "due_interest": 0.0,
                        "due_principal": 912.21,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 34.7134537949,
                        "principal_amortization_amount": 67.1265462051,
                        "tax_amount": 0.3798019984284558,
                        "total_amount": 101.84,
                        "workdays": 46.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-02-21",
                        "calendar_days": 31,
                        "due_date": "2025-02-21",
                        "due_interest": 0.0,
                        "due_principal": 845.0834537949,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 2,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 14.2997636051,
                        "principal_amortization_amount": 87.5402363949,
                        "tax_amount": 0.71782993843818,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-03-21",
                        "calendar_days": 28,
                        "due_date": "2025-03-21",
                        "due_interest": 0.0,
                        "due_principal": 757.5432174,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 3,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 11.5685715131,
                        "principal_amortization_amount": 90.2714284869,
                        "tax_amount": 0.9474889133985024,
                        "total_amount": 101.84,
                        "workdays": 18.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-04-21",
                        "calendar_days": 33,
                        "due_date": "2025-04-21",
                        "due_interest": 0.0,
                        "due_principal": 667.2717889131,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 4,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 12.025984633,
                        "principal_amortization_amount": 89.814015367,
                        "tax_amount": 1.185724630875134,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-05-21",
                        "calendar_days": 28,
                        "due_date": "2025-05-21",
                        "due_interest": 0.0,
                        "due_principal": 577.4577735461,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 5,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.8184725787,
                        "principal_amortization_amount": 93.0215274213,
                        "tax_amount": 1.4416476319753073,
                        "total_amount": 101.84,
                        "workdays": 19.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-06-21",
                        "calendar_days": 31,
                        "due_date": "2025-06-21",
                        "due_interest": 0.0,
                        "due_principal": 484.4362461248,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 6,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.1972396908,
                        "principal_amortization_amount": 93.6427603092,
                        "tax_amount": 1.689315395977968,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-07-21",
                        "calendar_days": 31,
                        "due_date": "2025-07-21",
                        "due_interest": 0.0,
                        "due_principal": 390.7934858156,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 7,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 6.6127072945,
                        "principal_amortization_amount": 95.2272927055,
                        "tax_amount": 1.959968138464601,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-08-21",
                        "calendar_days": 30,
                        "due_date": "2025-08-21",
                        "due_interest": 0.0,
                        "due_principal": 295.5661931101,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 8,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 4.8387153664,
                        "principal_amortization_amount": 97.0012846336,
                        "tax_amount": 2.2351036005274114,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-09-21",
                        "calendar_days": 33,
                        "due_date": "2025-09-21",
                        "due_interest": 0.0,
                        "due_principal": 198.5649084765,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 9,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.5787172455,
                        "principal_amortization_amount": 98.2612827545,
                        "tax_amount": 2.530031508362866,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-10-21",
                        "calendar_days": 28,
                        "due_date": "2025-10-21",
                        "due_interest": 0.0,
                        "due_principal": 100.303625722,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 10,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.5318141716,
                        "principal_amortization_amount": 100.3081858284,
                        "tax_amount": 2.8130427633716497,
                        "total_amount": 101.84,
                        "workdays": 20.0,
                        "installment_status": null,
                        "installment_type": null
                    }
                ],
                "first_due_date": "2025-01-21",
                "prefixed_interest_rate": {
                    "monthly_rate": 0.0166,
                    "daily_rate": 0.00054142,
                    "annual_rate": 0.21843191,
                    "interest_base": "calendar_days_365"
                }
            },
            {
                "disbursement_date": "2024-11-13",
                "contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 4.56
                    },
                    {
                        "fee_type": "ted_fee",
                        "fee_amount": 1.5
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0
                    }
                ],
                "contract_fee_amount": 6.06,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "assignment_amount": 917.27,
                "issue_amount": 912.71,
                "cet": "2,0200%",
                "annual_cet": "27,0802%",
                "base_iof": 15.827906861727051,
                "additional_iof": 3.468298,
                "total_iof": 19.3,
                "total_pre_fixed_amount": 105.691548961,
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-01-21",
                        "calendar_days": 68,
                        "due_date": "2025-01-21",
                        "due_interest": 0.0,
                        "due_principal": 912.71,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 34.2195628621,
                        "principal_amortization_amount": 67.6204371379,
                        "tax_amount": 0.3770515574809304,
                        "total_amount": 101.84,
                        "workdays": 45.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-02-21",
                        "calendar_days": 31,
                        "due_date": "2025-02-21",
                        "due_interest": 0.0,
                        "due_principal": 845.0895628621,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 2,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 14.2997636051,
                        "principal_amortization_amount": 87.5402363949,
                        "tax_amount": 0.7106516390537982,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-03-21",
                        "calendar_days": 28,
                        "due_date": "2025-03-21",
                        "due_interest": 0.0,
                        "due_principal": 757.5493264672,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 3,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 11.5685715131,
                        "principal_amortization_amount": 90.2714284869,
                        "tax_amount": 0.9400866562625766,
                        "total_amount": 101.84,
                        "workdays": 18.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-04-21",
                        "calendar_days": 33,
                        "due_date": "2025-04-21",
                        "due_interest": 0.0,
                        "due_principal": 667.2778979803,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 4,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 12.025984633,
                        "principal_amortization_amount": 89.814015367,
                        "tax_amount": 1.17835988161504,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-05-21",
                        "calendar_days": 28,
                        "due_date": "2025-05-21",
                        "due_interest": 0.0,
                        "due_principal": 577.4638826133,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 5,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.8184725787,
                        "principal_amortization_amount": 93.0215274213,
                        "tax_amount": 1.4340198667267607,
                        "total_amount": 101.84,
                        "workdays": 19.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-06-21",
                        "calendar_days": 31,
                        "due_date": "2025-06-21",
                        "due_interest": 0.0,
                        "due_principal": 484.442355192,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 6,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.1972396908,
                        "principal_amortization_amount": 93.6427603092,
                        "tax_amount": 1.6816366896326136,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-07-21",
                        "calendar_days": 31,
                        "due_date": "2025-07-21",
                        "due_interest": 0.0,
                        "due_principal": 390.7995948828,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 7,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 6.6127072945,
                        "principal_amortization_amount": 95.2272927055,
                        "tax_amount": 1.95215950046275,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-08-21",
                        "calendar_days": 30,
                        "due_date": "2025-08-21",
                        "due_interest": 0.0,
                        "due_principal": 295.5723021773,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 8,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 4.8387153664,
                        "principal_amortization_amount": 97.0012846336,
                        "tax_amount": 2.227149495187456,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-09-21",
                        "calendar_days": 33,
                        "due_date": "2025-09-21",
                        "due_interest": 0.0,
                        "due_principal": 198.5710175437,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 9,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.5787172455,
                        "principal_amortization_amount": 98.2612827545,
                        "tax_amount": 2.521974083176997,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-10-21",
                        "calendar_days": 28,
                        "due_date": "2025-10-21",
                        "due_interest": 0.0,
                        "due_principal": 100.3097347892,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 10,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.5318141718,
                        "principal_amortization_amount": 100.3081858282,
                        "tax_amount": 2.8048174921281284,
                        "total_amount": 101.84,
                        "workdays": 20.0,
                        "installment_status": null,
                        "installment_type": null
                    }
                ],
                "first_due_date": "2025-01-21",
                "prefixed_interest_rate": {
                    "monthly_rate": 0.0166,
                    "daily_rate": 0.00054142,
                    "annual_rate": 0.21843191,
                    "interest_base": "calendar_days_365"
                }
            },
            {
                "disbursement_date": "2024-11-14",
                "contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 4.57
                    },
                    {
                        "fee_type": "ted_fee",
                        "fee_amount": 1.5
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0
                    }
                ],
                "contract_fee_amount": 6.07,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "assignment_amount": 917.77,
                "issue_amount": 913.2,
                "cet": "2,0200%",
                "annual_cet": "27,0870%",
                "base_iof": 15.755779674642707,
                "additional_iof": 3.47016,
                "total_iof": 19.23,
                "total_pre_fixed_amount": 105.1973906257,
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-01-21",
                        "calendar_days": 67,
                        "due_date": "2025-01-21",
                        "due_interest": 0.0,
                        "due_principal": 913.2,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 33.7254045271,
                        "principal_amortization_amount": 68.1145954729,
                        "tax_amount": 0.3742215875281126,
                        "total_amount": 101.84,
                        "workdays": 44.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-02-21",
                        "calendar_days": 31,
                        "due_date": "2025-02-21",
                        "due_interest": 0.0,
                        "due_principal": 845.0854045271,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 2,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 14.2997636051,
                        "principal_amortization_amount": 87.5402363949,
                        "tax_amount": 0.7034733396694164,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-03-21",
                        "calendar_days": 28,
                        "due_date": "2025-03-21",
                        "due_interest": 0.0,
                        "due_principal": 757.5451681322,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 3,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 11.5685715131,
                        "principal_amortization_amount": 90.2714284869,
                        "tax_amount": 0.9326843991266508,
                        "total_amount": 101.84,
                        "workdays": 18.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-04-21",
                        "calendar_days": 33,
                        "due_date": "2025-04-21",
                        "due_interest": 0.0,
                        "due_principal": 667.2737396453,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 4,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 12.025984633,
                        "principal_amortization_amount": 89.814015367,
                        "tax_amount": 1.170995132354946,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-05-21",
                        "calendar_days": 28,
                        "due_date": "2025-05-21",
                        "due_interest": 0.0,
                        "due_principal": 577.4597242783,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 5,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.8184725787,
                        "principal_amortization_amount": 93.0215274213,
                        "tax_amount": 1.4263921014782142,
                        "total_amount": 101.84,
                        "workdays": 19.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-06-21",
                        "calendar_days": 31,
                        "due_date": "2025-06-21",
                        "due_interest": 0.0,
                        "due_principal": 484.438196857,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 6,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.1972396908,
                        "principal_amortization_amount": 93.6427603092,
                        "tax_amount": 1.6739579832872593,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-07-21",
                        "calendar_days": 31,
                        "due_date": "2025-07-21",
                        "due_interest": 0.0,
                        "due_principal": 390.7954365478,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 7,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 6.6127072945,
                        "principal_amortization_amount": 95.2272927055,
                        "tax_amount": 1.944350862460899,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-08-21",
                        "calendar_days": 30,
                        "due_date": "2025-08-21",
                        "due_interest": 0.0,
                        "due_principal": 295.5681438423,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 8,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 4.8387153664,
                        "principal_amortization_amount": 97.0012846336,
                        "tax_amount": 2.219195389847501,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-09-21",
                        "calendar_days": 33,
                        "due_date": "2025-09-21",
                        "due_interest": 0.0,
                        "due_principal": 198.5668592087,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 9,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.5787172455,
                        "principal_amortization_amount": 98.2612827545,
                        "tax_amount": 2.513916657991128,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-10-21",
                        "calendar_days": 28,
                        "due_date": "2025-10-21",
                        "due_interest": 0.0,
                        "due_principal": 100.3055764542,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 10,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.5318141715,
                        "principal_amortization_amount": 100.3081858285,
                        "tax_amount": 2.79659222089858,
                        "total_amount": 101.84,
                        "workdays": 20.0,
                        "installment_status": null,
                        "installment_type": null
                    }
                ],
                "first_due_date": "2025-01-21",
                "prefixed_interest_rate": {
                    "monthly_rate": 0.0166,
                    "daily_rate": 0.00054142,
                    "annual_rate": 0.21843191,
                    "interest_base": "calendar_days_365"
                }
            }
        ]
    }
} 
```

### Objeto Installments

| Campo | Descrição |
|-------|-----------|
| additional_costs | Custos adicionais |
| business_due_date | Data de vencimento em dia útil |
| calendar_days | Dias corridos |
| due_date | Data de vencimento |
| due_interest | Juros do vencimento |
| due_principal | Principal do vencimento |
| fine_amount | Multa do vencimento |
| has_interest | Indica se o vencimento possui juros |
| installment_number | Número da parcela |
| installment_status | Status da parcela |
| installment_type | Tipo de parcela |
| post_fixed_amount | Valor da parcela após juros |
| pre_fixed_amount | Valor da parcela antes de juros |
| principal_amortization_amount | Valor da amortização do principal da parcela |
| tax_amount | Valor dos juros da parcela |
| total_amount | Valor total da parcela |
| workdays | Dias úteis |

### Objeto Prefixed Interest Rate

| Campo | Descrição |
|-------|-----------|
| monthly_rate | Taxa mensal |
| daily_rate | Taxa diária |
| annual_rate | Taxa anual |
| interest_base | Base de cálculo da taxa de juros |

### Webhooks

Caso a operação não seja assinada ou averbada até a última opção de data de desembolso o parceiro receberá um webhook
informando a respeito do cancelamento da operação:

WEBHOOK TYPE
debt

STATUS
Canceled

**Webhook Body**

```json title="Webhook Body"
{
    "key": "<Debt Key>",
    "status": "canceled",
    "webhook_type": "debt",
    "event_datetime": "2025-03-18 13:46:31",
    "data": {
        "cancel_reason": "<CANCEL_REASON>",
        "cancel_reason_enumerator": "<CANCEL_REASON_ENUMERATOR>"
    }
}
```

### Objeto Data

| Campo | Descrição |
|-------|-----------|
| cancel_reason | Motivo do cancelamento |
| cancel_reason_enumerator | Enumerador do motivo do cancelamento |

## 3 - Coleta de documentos e formalização da operação
É obrigatório o envio dos dados complementares do contrato para a formalização da operação.

Recomendamos fortemente que a coleta e assinatura dos documentos da operação sejam realizadas por meio do **QI Sign**, nossa plataforma proprietária de assinatura eletrônica com tecnologia de antifraude embarcada.

Por ter sido desenvolvida internamente e estar totalmente integrada aos nossos sistemas, o uso do QI Sign garante:

- **Automação completa do fluxo de formalização**: a operação segue automaticamente para a próxima etapa após a assinatura.
- **Upload automático de documentos**: todos os arquivos assinados são enviados diretamente para o sistema de crédito, sem necessidade de intervenção manual.
- **Segurança e rastreabilidade**: o processo é seguro, auditável e em conformidade com os requisitos regulatórios.

Essa abordagem reduz erros operacionais, acelera a liberação do crédito e melhora significativamente a experiência do cliente.

### Por que usar o QI Sign?

- **Assinatura remota por celular**, com reconhecimento facial em conformidade com a regulação.
- **Integração via API RESTful**, facilitando automação de fluxos de assinatura.
- **Segurança jurídica**, com diferentes níveis de comprovação de identidade.
- **Soluções escaláveis** e sob demanda para corporações que precisam digitalizar seus processos.

:::info QI Sign
O **QI Sign** é a plataforma de assinatura eletrônica da QI Tech, desenvolvida internamente para atender às exigências regulatórias do mercado de crédito.  
Com suporte a **biometria facial** e **envio automático de documentos**, garante segurança, agilidade e rastreabilidade durante a formalização.

Para mais informações ou para solicitar uma proposta, entre em contato com nosso time comercial:  
📧 **comercial@qitech.com.br**  
📞 **(11) 2339-4763**
:::
### Formalização Externa
Caso a formalização das operações não seja realizada através do QI Sign, o procedimento de formalização deve ser consultado no [manual de formalização externa.](./manual_assinatura_externa.md)

## Webhooks

Após a assinatura do contrato, o parceiro receberá um webhook informando a respeito da assinatura do contrato. Com o seguinte body:

```json
{
    "key": "<Debt Key>",
    "status": "signed",
    "signers": [
        {
            "id": "3271efd3-89ba-43aa-b032-af9a459e6096",
            "images": {
                "face_image_url": "https://qisign-face-images-bucket-sandbox.s3.amazonaws.com/fad7f924-d210-4ec4-9565-a57662a0a65a.jpeg",
                "document_back_url": "https://qisign-personal-documents-bucket-sandbox.s3.amazonaws.com/8c7b68ba-07ad-4188-82ae-679833b2843b.jpeg",
                "document_front_url": "https://qisign-personal-documents-bucket-sandbox.s3.amazonaws.com/f63cd291-5668-4926-be5d-9290aeda3f6e.jpeg",
                "document_back_template": "cnh_back",
                "document_front_template": "cnh_front"
            },
            "biometry": {
                "face_validation": {
                    "score": 80,
                    "provider": "qitech",
                    "available": true
                },
                "fraud_base_flag": false
            },
            "document": {
                "template": "cnh_front",
                "face_match_score": 100
            },
            "liveness": {
                "result": "live"
            },
            "signed_at": "2025-04-09T19:59:39Z",
            "ip_address": "182.224.219.198",
            "signer_data": {
                "name": "Nome Trabalhador",
                "email": "exemplo@qitech.com.br",
                "phone": {
                    "number": "829549234",
                    "area_code": "11",
                    "international_dial_code": "55"
                },
                "address": {
                    "uf": "SP",
                    "city": "Sao Paulo",
                    "number": "123",
                    "street": "Rua tal do sal",
                    "complement": "Ap 23",
                    "postal_code": "00000-000",
                    "neighborhood": "Pinheiros"
                },
                "pix_key": "pix03@pix03.com",
                "birthdate": "1996-03-13",
                "document_number": "504.856.400-66",
                "document_submission_method": "email",
                "authentication_submission_method": "sms"
            }
        }
    ],
    "webhook_type": "laas.credit_operation.status_change",
    "event_datetime": "2025-04-09 20:00:19",
    "signed_contract_url": "https://storage.googleapis.com/sandbox-doc-api/documents/9b55450e-fca5-44f2-9118-5851ed4bd92e/RESTAURANTEBEBBER-TRABALHADOR_SICQ-CCB-0000195364-2230409195718_signed.pdf"
}
```

### Objeto Signers

| Campo | Descrição |
|-------|-----------|
| id | ID do signatário |
| images | Imagens do signatário |

### Objeto Images

| Campo | Descrição |
|-------|-----------|
| face_image_url | URL da imagem da face do signatário |
| document_back_url | URL da imagem do verso do documento do signatário |
| document_front_url | URL da imagem do documento do signatário |
| document_back_template | Template do verso do documento do signatário |
| document_front_template | Template do documento do signatário |

### Objeto Biometry

| Campo | Descrição |
|-------|-----------|
| face_validation | Validação da rosto do signatário (true ou false) |
| face_validation.score | Pontuação da rosto do signatário (0 a 100) |
| face_validation.available | Disponibilidade da validação da rosto do signatário (true ou false) |
| face_validation.provider | Provedor da validação da rosto do signatário (qitech ou external) |
| fraud_base_flag | Flag de fraude base (true ou false) |

### Objeto Document

| Campo | Descrição |
|-------|-----------|
| template | Template do documento (cnh_front, cnh_back, rg_front, rg_back) |
| face_match_score | Pontuação da rosto do signatário (0 a 100) |

### Objeto Liveness

| Campo | Descrição |
|-------|-----------|
| result | Resultado da liveness (live ou spoof) |

### Objeto Signer Data

| Campo | Descrição |
|-------|-----------|
| name | Nome do signatário |
| email | Email do signatário |
| phone | Telefone do signatário |

### Objeto Address

| Campo | Descrição |
|-------|-----------|
| uf | Unidade Federativa |
| city | Cidade |
| number | Número |
| street | Rua |
| complement | Complemento |
| postal_code | CEP |
| neighborhood | Bairro |

### Objeto Warranty
| Campo | Descrição |
|-------|-----------|
| severance_pay_rate          |float  |Percentual de verbas rescisórias disponíveis para garantia|
| severance_fine              |float  |Valor de multa rescisória disponível para garantia|
| fgts_balance                |float  |Valor de saldo do fgts disponível para garantia|

## Enumeradores

### Status da reserva {#status-da-reserva}

ENUMERADOR
reservation_status

| Status                        | Descrição                                                                 |
| ----------------------------- | ------------------------------------------------------------------------- |
| pending_auction               | A reserva foi criada e está esperando o início do leilão (receber uma solicitação de proposta).                                |
| pending_reservation           | A reserva foi criada e está pendente de averbação.                                      |
| pending_documents_submission  | A reserva já foi averbada e está pendente de envio de documentos. |
| reserved                      | A reserva foi averbada com sucesso. Fluxo de averbação concluído. |
| canceled                      | Em caso de envio de documentos inválidos, a reserva é cancelada. |
| pending_suspension            | A reserva está averbada e foi solicitada a suspensão. |
| suspended                     | A reserva foi suspensa com sucesso. |
| settled                       | A reserva foi liquidada com sucesso. |
| pending_deletion              | A reserva está averbada e foi solicitada a exclusão. |
| deleted                       | A reserva foi excluída com sucesso. |

---

# Manual Consignado Privado - Fluxo Ativo de Emissão

URL: /documentation/manual_consignado_privado/manual_detalhamento_fluxo_ativo

:::info Próximo passo
- [Consultas do Trabalhador](/documentation/manual_consignado_privado/manual_consultas_trabalhador)
:::

## Etapas do fluxo

### 1. Consultas do trabalhador
Realizar as [consultas do trabalhador](./manual_consultas_trabalhador.md) a fim de verificar a elegibilidade dos vínculos para emissão de crédito consignado e a margem consignável disponível além de outras informações.

### 2. Emissão e formalização da operação

Realizar as chamadas de simulação e criação da operação de crédito e orientar o tomador quanto ao fluxo de assinatura da CCB.

### 3. Averbação

Acompanhar o retorno da DATAPREV a respeito das tentativas de averbação.

### 4. Desembolso

Acompanhar o desembolso da operação e tratar eventuais falhas de desembolso.

---

# Manual Consignado Privado - Fluxo de Emissão Via Leilão

URL: /documentation/manual_consignado_privado/manual_detalhamento_fluxo_leilao

## Etapas do fluxo

### 1. Configuração dos filtros de pedido de empréstimo
Realizar a configuração dos filtros de recebimento de pedidos de empréstimo, a fim de selecionar o público alvo que se deseja atacar.

### 2. Recebimento dos webhooks de pedido de empréstimo e envio de proposta

Receber os webhooks filtrados de pedidos de empréstimo, simular as condições desejadas do crédito e envio da proposta para o leilão interno.

### 3. Acompanhamento do status da proposta de leilão interno e da assinatura da operação de crédito

Aguardar os webhooks de atualização do leilão interno e de assinatura da operação.

### 4. Autorização da averbação e acompanhamento do desembolso

Autorizar a averbação e tratar as possíveis falhas de averbação e desembolso.

---

# Manual Consignado Privado - Leilão Interno

URL: /documentation/manual_consignado_privado/manual_leilao_interno

## 1. Início de Leilão

Após as configurações dos filtros de pedidos de empréstimo, o parceiro irá começar a receber webhooks notificando estas solicitações. 

WEBHOOK_TYPE laas.private_payroll_auction.new_issuer_proposal_request

Webhook Body: Nova solicitação de empréstimo

**Solicitação sem garantia**

```json
{
    "status": "ongoing",
    "event_datetime": "2025-03-20T14:47:43Z",
    "key": "88b0203d-31ad-48c6-a795-b6d45ab4898a",
    "webhook_type": "laas.private_payroll_auction.new_issuer_proposal_request",
    "data": {
        "issuer_proposal_request_key": "88b0203d-31ad-48c6-a795-b6d45ab4898a",
        "status": "ongoing",
        "expiration_datetime": "2025-03-21T11:47:12Z",
        "inclusion_limit_datetime": "2025-03-20T11:49:43Z",
        "issuer_proposal_request_data": {
            "issuer_registration_number": "TESTE123",
            "birth_date": "1973-03-14",
            "disbursed_issue_amount": 2100,
            "admission_date": "2020-03-10",
            "consigned_credit_balance": 10000,
            "eligible": true,
            "employer_document_type": "cnpj",
            "document_number": "00737823780",
            "employer_document_number": "29113956000181",
            "number_of_installments": 10,
            "political_exposition": "not_exposed",
            "name": "VALENTINA SANTOS",
            "alerts": [
                {
                    "alert_type": "leave",
                    "description": "Afastamento",
                    "reference_date": "2025-02-11",
                    "event_id": "123456",
                    "leave_reason_code": 3,
                    "leave_start_date": "2025-02-11",
                    "leave_end_date": "2025-03-11"
                },
                {
                    "alert_type": "termination",
                    "description": "Desligamento",
                    "reference_date": "2025-02-11", 
                    "event_id": "789012",
                    "termination_reason_code": 1,
                    "termination_date": "2025-02-11",
                    "notice_period_start_date": "2025-01-11",
                    "notice_period_end_date": "2025-02-11"
                }
            ],
            "issuer_proposal_request_type" : "standard",
            "warranty" : null
        }
    }
}
```

**Solicitação com garantia**

```json
{
    "status": "ongoing",
    "event_datetime": "2025-03-20T14:47:43Z",
    "key": "88b0203d-31ad-48c6-a795-b6d45ab4898a",
    "webhook_type": "laas.private_payroll_auction.new_issuer_proposal_request",
    "data": {
        "issuer_proposal_request_key": "88b0203d-31ad-48c6-a795-b6d45ab4898a",
        "status": "ongoing",
        "expiration_datetime": "2025-03-21T11:47:12Z",
        "inclusion_limit_datetime": "2025-03-20T11:49:43Z",
        "issuer_proposal_request_data": {
            "issuer_registration_number": "TESTE123",
            "birth_date": "1973-03-14",
            "disbursed_issue_amount": 2100,
            "admission_date": "2020-03-10",
            "consigned_credit_balance": 10000,
            "eligible": true,
            "employer_document_type": "cnpj",
            "document_number": "00737823780",
            "employer_document_number": "29113956000181",
            "number_of_installments": 10,
            "political_exposition": "not_exposed",
            "name": "VALENTINA SANTOS",
            "alerts": [
                {
                    "alert_type": "leave",
                    "description": "Afastamento",
                    "reference_date": "2025-02-11",
                    "event_id": "123456",
                    "leave_reason_code": 3,
                    "leave_start_date": "2025-02-11",
                    "leave_end_date": "2025-03-11"
                },
                {
                    "alert_type": "termination",
                    "description": "Desligamento",
                    "reference_date": "2025-02-11", 
                    "event_id": "789012",
                    "termination_reason_code": 1,
                    "termination_date": "2025-02-11",
                    "notice_period_start_date": "2025-01-11",
                    "notice_period_end_date": "2025-02-11"
                }
            ],
            "issuer_proposal_request_type" : "warranted",
            "warranty" : {
                "severance_pay_rate":0.15,
                "severance_fine":20000,
                "fgts_balance":10000
            }
        }
    }
}
```

Cada pedido de empréstimo passa por duas etapas, o leilão interno e o leilão no app da CTPS. O leilão interno se inicia assim que o webhook é recebido e se encerra no timestamp indicado no campo *inclusion_limit_datetime*, durante este período as propostas de todos os parceiros são recebidas e ranqueadas com base na taxa, assim que o leilão interno se encerra a proposta com as melhores condições é enviada à CTPS do tomador onde as propostas de todas as IFs são apresentadas.
Caso nenhuma proposta seja enviada até o fim do leilão interno, a primeira proposta enviada depois do *inclusion_limit_datetime* ganhará automaticamente e será enviada à CTPS.

## 2. Proposta de Crédito  

### Request

POST - `/private_payroll_auction/issuer_proposal_request/{issuer_proposal_request_key}/auction_proposals`

Testar no Playground

Request Body: Incluindo AuctionProposal(s) no leilão

**Proposta sem garantia**

```json
{
    "standard_proposal":{
        "request_control_key" : "111e7ed3-4080-4cae-a853-8e12812817ea",
        "disbursed_issue_amount": 15000,
        "monthly_interest_rate": 0.045,
        "number_of_installments": 48,
        "purchaser_document_number": "01272247000120",
        "days_to_expiration": 10,
        "rebates": [
            {
                "fee_type": "spread",
                "amount_type": "percentage",
                "amount": 4.17
            }
        ]
    }
}
```

**Proposta com garantia**

```json
{
    "standard_proposal":{
        "request_control_key" : "111e7ed3-4080-4cae-a853-8e12812817ea",
        "disbursed_issue_amount": 15000,
        "monthly_interest_rate": 0.045,
        "number_of_installments": 48,
        "purchaser_document_number": "01272247000120",
        "days_to_expiration": 10,
        "rebates": [
            {
                "fee_type": "spread",
                "amount_type": "percentage",
                "amount": 4.17
            }
        ]
    },
    "warranted_proposal":{
        "request_control_key" : "4593d8a6-91a1-4195-ba78-b1a864bac247",
        "disbursed_issue_amount": 15000,
        "monthly_interest_rate": 0.04,
        "number_of_installments": 48,
        "purchaser_document_number": "01272247000120",
        "days_to_expiration": 10,
        "rebates": [
            {
                "fee_type": "spread",
                "amount_type": "percentage",
                "amount": 4.17
            }
        ]
    }
}
```

### Response

STATUS - 200 (Accepted)

Response Body: AuctionProposal(s) incluída(s) com sucesso no leilão

**Resultado proposta sem garantia**

```json
{
    "standard_proposal":{
        "auction_proposal_key": "814e7ed3-4080-4cae-a853-8e12812817ea",
        "issuer_proposal_request_key" : "100e7ed3-4080-4cae-a853-8e12812817ea",
        "request_control_key" : "111e7ed3-4080-4cae-a853-8e12812817ea",
        "status": "bid",
        "proposal_score" : 0.4,
        "inclusion_date" : "2025-03-18T14:52:07.123456",
        "rank_position" : null,
        "proposal_data": {
                "simulation": {
                    "total_iof": 523.3,
                    "annual_cet": 0.735,
                    "monthly_cet": 0.047,
                    "issue_amount": 15523.3,
                    "annual_interest_rate": 0.6958814328,
                    "monthly_interest_rate": 0.045,
                    "disbursed_issue_amount": 15000,
                    "installment_face_value": 851.33,
                    "number_of_installments" : 48
                },
                "monthly_interest_rate": 0.045,
                "disbursed_issue_amount": 15000,
                "installment_face_value": null,
                "number_of_installments": 48
        },
    }
}
```

**Resultado proposta com garantia**

```json
{
    "standard_proposal":{
        "auction_proposal_key": "814e7ed3-4080-4cae-a853-8e12812817ea",
        "issuer_proposal_request_key" : "100e7ed3-4080-4cae-a853-8e12812817ea",
        "request_control_key" : "111e7ed3-4080-4cae-a853-8e12812817ea",
        "status": "bid",
        "proposal_score" : 0.4,
        "inclusion_date" : "2025-03-18T14:52:07.123456",
        "rank_position" : null,
        "proposal_data": {
                "simulation": {
                    "total_iof": 523.3,
                    "annual_cet": 0.735,
                    "monthly_cet": 0.047,
                    "issue_amount": 15523.3,
                    "annual_interest_rate": 0.6958814328,
                    "monthly_interest_rate": 0.045,
                    "disbursed_issue_amount": 15000,
                    "installment_face_value": 851.33,
                    "number_of_installments" : 48
                },
                "monthly_interest_rate": 0.045,
                "disbursed_issue_amount": 15000,
                "installment_face_value": null,
                "number_of_installments": 48
        },
    },
    "warranted_proposal":{
        "auction_proposal_key": "1fedc1ba-bff5-4149-831a-cfd1f556da63",
        "issuer_proposal_request_key" : "100e7ed3-4080-4cae-a853-8e12812817ea",
        "request_control_key" : "4593d8a6-91a1-4195-ba78-b1a864bac247",
        "status": "bid",
        "proposal_score" : 0.4,
        "inclusion_date" : "2025-03-18T14:52:07.123456",
        "rank_position" : null,
        "proposal_data": {
            "simulation": {
                "total_iof": 522.06,
                "annual_cet": 0.6364,
                "monthly_cet": 0.0419,
                "issue_amount": 15522.06,
                "annual_interest_rate": 0.6010322186,
                "monthly_interest_rate": 0.04,
                "disbursed_issue_amount": 15000,
                "installment_face_value": 778.76,
                "number_of_installments" : 48
            },
            "monthly_interest_rate": 0.04,
            "disbursed_issue_amount": 15000,
            "installment_face_value": null,
            "number_of_installments": 48
        }
    }
}
```

STATUS - 400 (Rejected)

Response Body: Bad Request

**Margem consignável excedida**

    ```json
    {
    "title": "Bad Request",
    "description": "Calculated installment face value is greater than consigned credit balance",
    "translation": "Schema Invalido",
    "extra_fields": {},
    "code": "QIT000001"
    }
    ```
**Garantias disponíveis excedidas**

    ```json
    {
    "title": "Warranty cap exceeded",
    "description": "One or more warranty values exceed the allowed caps",
    "translation": "Um ou mais valores de garantia excedem os limites permitidos",
    "extra_fields": {},
    "code": "PPA000034"
    }
    ```

## 3. Encerramento do Leilão

Quando o leilão interno se encerra, um webhook é enviado atualizando o parceiro se o mesmo venceu ou perdeu o leilão, no caso de vitória, a operação de crédito é criada e o link de formalização do QI Sign é enviado ao app da CTPS do tomador, a partir deste momento o acompanhamento da operação deve ser realizado através da chave *credit_operation_key*.

:::danger Leilão com garantia!
Ao entrar no leilão de um pedido de empréstimo com garantia, são geradas duas propostas e o leilão interno é segregado em dois, um para as propostas com garantia e um para as propostas sem garantia, então dois webhooks são enviados informando a vitória ou derrota em cada um dos leilões.
:::

WEBHOOK_TYPE laas.private_payroll_auction.end_of_auction

Webhook Body: Resultado do leilão interno

**Resultado proposta sem garantia**

```json
{
    "key": "814e7ed3-4080-4cae-a853-8e12812817ea", // esta chave é igual à auction_proposal_key
    "data": {
        "auction_proposal_key": "814e7ed3-4080-4cae-a853-8e12812817ea",
        "status": "won",
        "type": "auction",
        "rank_position": 1,
        "signature_url": "https://sandbox.sign.qitech.com.br/r/3D1s523",
        "credit_operation_key": "9e06ca79-3610-4794-8312-9663e0343f6b",
        "issuer_proposal_request_key": "262d0584-9827-4652-9b27-6a46c9832f38",
        "proposal_number": "QITECH_6853045512774",
        "contract_number": "0340932936/VHD",
        "auction_proposal_type":"standard"
    },
    "status": "won",
    "event_datetime": "2025-03-20T14:48:43Z",
    "webhook_type": "laas.private_payroll_auction.end_of_auction"
}
```

**Resultado proposta com garantia**

```json
{
    "key": "1fedc1ba-bff5-4149-831a-cfd1f556da63", // esta chave é igual à auction_proposal_key
    "data": {
        "auction_proposal_key": "1fedc1ba-bff5-4149-831a-cfd1f556da63",
        "status": "won",
        "type": "auction",
        "rank_position": 1,
        "signature_url": "https://sandbox.sign.qitech.com.br/r/3D1s523",
        "credit_operation_key": "9e06ca79-3610-4794-8312-9663e0343f6b",
        "issuer_proposal_request_key": "262d0584-9827-4652-9b27-6a46c9832f38",
        "proposal_number": "QITECH_6853045512774",
        "contract_number": "0340932936/VHD",
        "auction_proposal_type":"warranted",
        "warranty" : {
            "severance_pay_rate":null,
            "severance_fine":5522.06,
            "fgts_balance":10000
        }
    },
    "status": "won",
    "event_datetime": "2025-03-20T14:48:43Z",
    "webhook_type": "laas.private_payroll_auction.end_of_auction"
}
```

A chave da operação de crédito será enviada com valor null para as propostas perdedoras.

:::info Atenção
O link de assinatura não será enviado no ambiente de produção, apenas em sandbox para que seja possível simular a assinatura do tomador.
:::

## Anexos

### Definição do Objeto IssuerProposalRequest

| Nome            | Tipo   | Descrição                                                                          |
| --------------- | ------ | ---------------------------------------------------------------------------------- |
| issuer_proposal_request_key | string  | Identificador único da **Solicitação de Proposta** |
| issuer_proposal_request_data| object  | Objeto que descreve os dados da **Solicitação de Proposta** |
| status                      | string  | Status da **Solicitação de Proposta** (`ongoing`, `finished`, `expired`)|

### Definição do Objeto IssuerProposalRequestData

| Nome            | Tipo   | Descrição                                                                          |
| --------------- | ------ | ---------------------------------------------------------------------------------- |
| name                        |string | Nome completo do Tomador |
| document_number             |string | CPF do Tomador |
| birth_date                  |string | Data de nascimento do Tomador no formato `YYYY-MM-DD` |
| disbursed_amount            |float  | Valor de desembolso solicitado pelo tomador |
| number_of_installments      |integer| Número de parcelas solicitados pelo tomador |
| consigned_credit_balance    |float  | Margem consignável disponível de saldo do tomador |
| admission_date              |string | Data de admissão do trabalhador no cargo atual no formato `YYYY-MM-DD` |
| issuer_registration_code    |string | Matricula eSocial do empregado|
| employer_document_number    |string | CNPJ do empregador |
| eligible                    |boolean| True se elegivel, False se não elegivel|
| employer_document_type      |string | CNPJ ou CPF|
| alerts                      |objeto |Lista com histórico de afastamentos e avisos de desligamento do vínculo, para detalhamento dos campos consulte a tabela [Detalhamento do objeto alerts](#alerts)|
| type                        |string |Tipo de solicitação, para detalhamento dos campos consulte a tabela [Tipos de solicitação de empréstimo](#request_type)|
| severance_pay_rate          |float  |Percentual de verbas rescisórias disponíveis para garantia|
| severance_fine              |float  |Valor de multa rescisória disponível para garantia|
| fgts_balance                |float  |Valor de saldo do fgts disponível para garantia|

### Detalhamento do objeto alerts {#alerts}
| Campo                         | Descrição                          | 
|-------------------------      |------------------------------------|
|alert_type                     |Tipo de alerta, consulte os possíveis enumeradores na tabela [Tipos de alerta](#alert_type)|
|reference_date                 |Data de referência do evento|
|event_id                       |Identificador do evento|
|leave_reason_code              |[Motivo do afastamento](https://www.gov.br/esocial/pt-br/documentacao-tecnica/leiautes-esocial-versao-1-3-nt-03-2025/tabelas.html#18) em conformidade com o site do eSocial|
|leave_start_date               |Data de início do afastamento|
|leave_end_date                 |Data de término do afastamento|
|termination_reason_code        |[Motivo do desligamento](https://www.gov.br/esocial/pt-br/documentacao-tecnica/leiautes-esocial-versao-1-3-nt-03-2025/tabelas.html#19) em conformidade com o site do eSocial|
|termination_date               |Data de desligamento do vínculo|
|notice_period_start_date       |Data de início do período de aviso prévio|
|notice_period_end_date         |Data de término do período de aviso prévio|

### Tipos de alerta {#alert_type}
ENUMERADOR
alert_type
| Enumerador                    | Descrição                         | 
|-------------------------      |-----------------------------------|
|leave                          |Afastamento                        |
|termination                    |Aviso prévio de desligamento       |

### Tipos de solicitação de empréstimo {#request_type}
ENUMERADOR
type
| Enumerador                    | Descrição                         | 
|-------------------------      |-----------------------------------|
|warranted                      |Solicitação com garantia           |
|standard                       |Solicitação sem garantia           |

### Detalhamento dos Status da solicitação de proposta

| Status  | Descrição                                                                 |
| ------- | ------------------------------------------------------------------------- |
| ongoing | **Solicitação de Proposta** em andamento, o leilão continua ativo.  |
| finished| **Solicitação de Proposta** finalizada, o leilão foi encerrado e uma **Proposta** enviada foi aceita e incluída. |
| expired | **Solicitação de Proposta** expirada, o leilão foi encerrado sem a inclusão de nenhuma **Proposta** em tempo hábil.  |

### Detalhamento da Requisição de Proposta de Leilão

| Campo         | Tipo    | Descrição                                                                                                       | Obrigatório |
|---------------|---------|-----------------------------------------------------------------------------------------------------------------|-------------|
| `issuer_proposal_request_key` | string  | Chave única de identificação da **IssuerProposalRequest** incluída no formato uuid v4.                          | Sim         |
| `auction_proposal_key` | string  | Chave única de identificação da **AuctionProposal** incluída no formato uuid v4.                                | Sim         |
| `disbursed_issue_amount`| float   | Valor de desembolso pretendido pela **Proposta**.                                                               | Sim         |
| `purchaser_document_number` | integer | CNPJ do comprador da dívida | Sim         
| `monthly_interest_rate` | float   | Taxa de juros mensal da **Proposta** no intervalo de 0 a 1 (0% a 100%, respectivamente).                        | Não         |
| `installment_face_value`| float   | Valor da parcela pretendida pela **Proposta**.                                                                  | Não         |
| `number_of_installments`| integer | Número de parcelas da proposta.                                                                                 | Sim         |
| `days_to_expiration`| integer | Número de dias até que a proposta expire. Caso a chave não seja incluida, a validade da proposta será de 7 dias | Não         |
| `rebates` | list    | Lista de rebates da operação de crédito. Utiliza o mesmo padrão da emissão ativa (/debt)                        | Não         |

### Detalhamento do webhook de finalização de leilão

| Campo         | Tipo    | Descrição                                                                                                       |
|---------------|---------|-----------------------------------------------------------------------------------------------------------------|
| `auction_proposal_key` | string  | Chave única de identificação da **AuctionProposal** incluída no formato uuid v4.                       |
| `status` | string  | Indicador de vitória ou derrota no leilão interno.                                                                    |
| `type` | string  | Enumerador de tipo de proposta de leilão (demais tipos foram deprecados o valor sempre será "auction").                 |
| `rank_position`| integer   | Posição da proposta no leilão interno.                                                                       |
| `signature_url` | string | Link de formalização da dívida, enviado somente em ambiente de sandbox para fins de homologação.                |
| `credit_operation_key` | string   | Identificador único da operação de crédito, caso a proposta não tenha vencido o leilão, é retornado vazio.              |
| `issuer_proposal_request_key`| string   | Identificador único do pedido de empréstimo.                                                        |
| `proposal_number`| string | Número da proposta QI Tech no app da CTPS.                                                                       |
| `contract_number`| string | Número de contrato da CCB |

### Detalhamento do webhook de finalização de leilão

| Campo         | Tipo    | Descrição                                                                                                       |
|---------------|---------|-----------------------------------------------------------------------------------------------------------------|
| `auction_proposal_key` | string  | Chave única de identificação da **AuctionProposal** incluída no formato uuid v4.                       |
| `status` | string  | Indicador de vitória ou derrota no leilão interno.                                                                    |
| `type` | string  | Enumerador de tipo de proposta de leilão (demais tipos foram deprecados o valor sempre será "auction").                 |
| `rank_position`| integer   | Posição da proposta no leilão interno.                                                                       |
| `signature_url` | string | Link de formalização da dívida, enviado somente em ambiente de sandbox para fins de homologação.                |
| `credit_operation_key` | string   | Identificador único da operação de crédito, caso a proposta não tenha vencido o leilão, é retornado vazio.              |
| `issuer_proposal_request_key`| string   | Identificador único do pedido de empréstimo.                                                        |
| `proposal_number`| string | Número da proposta QI Tech no app da CTPS.                                                                       |
| `contract_number`| string | Número de contrato da CCB |

---

# Manual Consignado Privado - Refinanciamento

URL: /documentation/manual_consignado_privado/manual_refinanciamento

:::info 
Este manual é dedicado a documentar o refinanciamento de operações originadas na QI Tech já no crédito do trabalhador, ou de operações legado tombadas para o crédito do trabalhador.
:::

:::danger Opções de desembolso
Como no crédito novo, as operações de refinanciamento terão suas opções de desembolso limitadas à uma mesma competência, além disso, uma vez averbada a operação de refinanciamento deverá desembolsar na mesma data, caso contrário será cancelada permanentemente e precisará ser reformalizada.
:::

:::warning Data de liquidação
Para garantir o direito de arrependimento do tomador, as operações refinanciadas somente serão liquidadas 7 dias úteis após a data de desembolso da dívida. 
:::

:::danger Rotinas Automáticas de Cancelamento permanente
Existem duas rotinas automáticas de cancelamento permanente acionadas pela QI Tech:

1. Esgotamento das opções de desembolso.

Todas as operações que não forem desembolsadas até a data final de desembolso serão caceladas permanentemente no dia seguinte á data final.

2. Operação averbada e não desembolsada no mesmo dia.

Operações de refinanciamento devem ser desembolsadas na mesma data da averbação, caso contrário serão canceladas permanentemente.

Webhooks de cancelamento permanente

**Esgotamento das opções de desembolso**

```json
{
    "key": "d7ba5332-3675-12a6-9e07-8afd25ffcfd0",
    "data": {
      "cancel_reason": "Operação não desembolsada já passou da última data de desembolso",
      "cancel_reason_enumerator": "expired_disbursement_date"
    },
    "status": "canceled_permanently",
    "webhook_type": "laas.credit_operation.status_change",
    "event_datetime": "2026-02-12 00:53:16"
}
```
  
**Operação averbada e não desembolsada no mesmo dia**

```json
{
    "key": "d7ba5332-3675-12a6-9e07-8afd25ffcfd0",
    "data": {
      "cancel_reason": "Operação excedeu o prazo máximo em averbação sem desembolso",
      "cancel_reason_enumerator": "exceeded_max_days_reserved_not_disbursed"
    },
    "status": "canceled_permanently",
    "webhook_type": "laas.credit_operation.status_change",
    "event_datetime": "2026-02-12 00:53:16"
}
```

:::

Para simular e emitir dívidas de refinanciamento, deve-se adicionar ao payload as chaves das dívidas que serão refinanciadas no seguinte formato:

REFINANCIAMENTO

```json 
  "refinanced_credit_operations": [
    {
      "operation_key": "c63f3a4c-0cde-4be7-8bb2-00ffc564cddb"
    }
  ]
```

## 1 - Simulação da dívida:

### Request

**POST**
/debt_simulation

Testar no Playground

```json title='Request Body'
{
    "borrower": {
        "person_type": "natural"
    },
    "financial": {
        "first_due_date": "2024-12-07",
        "installment_face_value": 100,
        "disbursement_date": "2024-11-05",
        "limit_days_to_disburse": 3,
        "number_of_installments": 4,
        "monthly_interest_rate": 0.018,
        "interest_type": "pre_price_days",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0
    },
    "collaterals": [
        {
            "collateral_type": "private_payroll"
        }
    ],
    "refinanced_credit_operations": [
        {
        "operation_key": "c63f3a4c-0cde-4be7-8bb2-00ffc564cddb"
        }
    ]
}
```

### Response

STATUS
**200** (OK)

**Response Body**

```json
{
    "type": "debt",
    "key": "<Debt Key>",
    "status": "finished",
    "event_datetime": "2024-11-05 16:50:00",
    "data": {
        "interest_type": "pre_price_days",
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "interest_payment_month_period": 1,
        "principal_grace_period": 0,
        "principal_amortization_month_period": 1,
        "operation_type": "refinancing",
        "post_fixed_interest_base": "workdays",
        "post_fixed_interest_rate": null,
        "prefixed_interest_rate": {
            "interest_base": "calendar_days_365",
            "annual_rate": 0.23872053,
            "monthly_rate": 0.018,
            "daily_rate": 0.00058669
        },
        "issue_date": "2024-11-05",
        "number_of_installments": 4,
        "requester_key": "e5eb6a0a-e003-4cbd-b702-5a25bf71af0a",
        "final_disbursement_amount": 0.0,
        "disbursement_options": [
            {
                "iof_amount": 3.93,
                "total_pre_fixed_amount": 17.8715883143,
                "cet": 0.0257,
                "annual_cet": 0.355163,
                "contract_fees": [
                    {
                        "fee_type": "tac",
                        "amount_type": "percentage",
                        "amount": 0.6,
                        "fee_amount": 2.29
                    },
                    {
                        "fee_type": "ted_fee",
                        "amount_type": "absolute",
                        "amount": 1.0,
                        "fee_amount": 1.0
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "insurance_premium",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "tac",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    }
                ],
                "contract_fee_amount": 2.29,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "disbursement_date": "2024-11-05",
                "first_due_date": "2024-12-21",
                "installments": [
                    {
                        "calendar_days": 34,
                        "workdays": 23.0,
                        "business_due_date": "2024-12-21",
                        "due_date": "2024-12-21",
                        "due_principal": 382.13,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 7.6967422515,
                        "tax_amount": 0.257341482602818,
                        "total_amount": 100,
                        "principal_amortization_amount": 92.3032577485,
                        "installment_number": 1
                    },
                    {
                        "calendar_days": 29,
                        "workdays": 19.0,
                        "business_due_date": "2025-01-21",
                        "due_date": "2025-01-21",
                        "due_principal": 289.8267422515,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 4.9718040699,
                        "tax_amount": 0.4909156601748966,
                        "total_amount": 100,
                        "principal_amortization_amount": 95.0281959301,
                        "installment_number": 2
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 23.0,
                        "business_due_date": "2025-02-21",
                        "due_date": "2025-02-21",
                        "due_principal": 194.7985463214,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.5742034136,
                        "tax_amount": 0.7432500400879712,
                        "total_amount": 100,
                        "principal_amortization_amount": 96.4257965864,
                        "installment_number": 3
                    },
                    {
                        "calendar_days": 28,
                        "workdays": 18.0,
                        "business_due_date": "2025-03-21",
                        "due_date": "2025-03-21",
                        "due_principal": 98.372749735,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.6288385793,
                        "tax_amount": 0.9841050988526828,
                        "total_amount": 100,
                        "principal_amortization_amount": 98.3711614207,
                        "installment_number": 4
                    }
                ],
                "issue_amount": 382.13,
                "disbursed_issue_amount": 374.91,
                "assignment_amount": 382.13,
                "final_disbursement_amount": 374.91,
                "prefixed_interest_rate": {
                    "interest_base": "calendar_days_365",
                    "annual_rate": 0.23872053,
                    "monthly_rate": 0.018,
                    "daily_rate": 0.00058669
                }
            },
            {
                "iof_amount": 4.77,
                "total_pre_fixed_amount": 24.2597288075,
                "cet": 0.0243,
                "annual_cet": 0.334037,
                "contract_fees": [
                    {
                        "fee_type": "tac",
                        "amount_type": "percentage",
                        "amount": 0.6,
                        "fee_amount": 2.25
                    },
                    {
                        "fee_type": "ted_fee",
                        "amount_type": "absolute",
                        "amount": 1.0,
                        "fee_amount": 1.0
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "insurance_premium",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "tac",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    }
                ],
                "contract_fee_amount": 2.25,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "disbursement_date": "2024-11-06",
                "first_due_date": "2025-01-21",
                "installments": [
                    {
                        "calendar_days": 62,
                        "workdays": 41.0,
                        "business_due_date": "2025-01-21",
                        "due_date": "2025-01-21",
                        "due_principal": 375.74,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 13.9149280115,
                        "tax_amount": 0.437656505989534,
                        "total_amount": 100,
                        "principal_amortization_amount": 86.0850719885,
                        "installment_number": 1
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 23.0,
                        "business_due_date": "2025-02-21",
                        "due_date": "2025-02-21",
                        "due_principal": 289.6549280115,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 5.3146959395,
                        "tax_amount": 0.722070128765373,
                        "total_amount": 100,
                        "principal_amortization_amount": 94.6853040605,
                        "installment_number": 2
                    },
                    {
                        "calendar_days": 28,
                        "workdays": 18.0,
                        "business_due_date": "2025-03-21",
                        "due_date": "2025-03-21",
                        "due_principal": 194.969623951,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.2283291407,
                        "tax_amount": 0.9601685182659746,
                        "total_amount": 100,
                        "principal_amortization_amount": 96.7716708593,
                        "installment_number": 3
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 21.0,
                        "business_due_date": "2025-04-07",
                        "due_date": "2025-04-07",
                        "due_principal": 98.1979530917,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.8017757158,
                        "tax_amount": 1.2239426674782687,
                        "total_amount": 100,
                        "principal_amortization_amount": 98.1982242842,
                        "installment_number": 4
                    }
                ],
                "issue_amount": 375.74,
                "disbursed_issue_amount": 367.72,
                "assignment_amount": 375.74,
                "final_disbursement_amount": 367.72,
                "prefixed_interest_rate": {
                    "interest_base": "calendar_days_365",
                    "annual_rate": 0.23872053,
                    "monthly_rate": 0.018,
                    "daily_rate": 0.00058669
                }
            },
            {
                "iof_amount": 4.74,
                "total_pre_fixed_amount": 24.0392857898,
                "cet": 0.0243,
                "annual_cet": 0.334673,
                "contract_fees": [
                    {
                        "fee_type": "tac",
                        "amount_type": "percentage",
                        "amount": 0.6,
                        "fee_amount": 2.26
                    },
                    {
                        "fee_type": "ted_fee",
                        "amount_type": "absolute",
                        "amount": 1.0,
                        "fee_amount": 1.0
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "insurance_premium",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "tac",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    }
                ],
                "contract_fee_amount": 2.26,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "disbursement_date": "2024-11-07",
                "first_due_date": "2025-01-21",
                "installments": [
                    {
                        "calendar_days": 61,
                        "workdays": 40.0,
                        "business_due_date": "2025-01-21",
                        "due_date": "2025-01-21",
                        "due_principal": 375.96,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 13.6944849939,
                        "tax_amount": 0.4317001860605122,
                        "total_amount": 100,
                        "principal_amortization_amount": 86.3055150061,
                        "installment_number": 1
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 23.0,
                        "business_due_date": "2025-02-21",
                        "due_date": "2025-02-21",
                        "due_principal": 289.6544849939,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 5.3146959395,
                        "tax_amount": 0.714305933832412,
                        "total_amount": 100,
                        "principal_amortization_amount": 94.6853040605,
                        "installment_number": 2
                    },
                    {
                        "calendar_days": 28,
                        "workdays": 18.0,
                        "business_due_date": "2025-03-21",
                        "due_date": "2025-03-21",
                        "due_principal": 194.9691809334,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.2283291407,
                        "tax_amount": 0.952233241255512,
                        "total_amount": 100,
                        "principal_amortization_amount": 96.7716708593,
                        "installment_number": 3
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 21.0,
                        "business_due_date": "2025-04-07",
                        "due_date": "2025-04-07",
                        "due_principal": 98.1975100741,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.8017757157,
                        "tax_amount": 1.2158904130882027,
                        "total_amount": 100,
                        "principal_amortization_amount": 98.1982242843,
                        "installment_number": 4
                    }
                ],
                "issue_amount": 375.96,
                "disbursed_issue_amount": 367.96,
                "assignment_amount": 375.96,
                "final_disbursement_amount": 367.96,
                "prefixed_interest_rate": {
                    "interest_base": "calendar_days_365",
                    "annual_rate": 0.23872053,
                    "monthly_rate": 0.018,
                    "daily_rate": 0.00058669
                }
            },
            {
                "iof_amount": 4.71,
                "total_pre_fixed_amount": 23.8187134405,
                "cet": 0.0244,
                "annual_cet": 0.335196,
                "contract_fees": [
                    {
                        "fee_type": "tac",
                        "amount_type": "percentage",
                        "amount": 0.6,
                        "fee_amount": 2.26
                    },
                    {
                        "fee_type": "ted_fee",
                        "amount_type": "absolute",
                        "amount": 1.0,
                        "fee_amount": 1.0
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "insurance_premium",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "tac",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    }
                ],
                "contract_fee_amount": 2.26,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "disbursement_date": "2024-11-08",
                "first_due_date": "2025-01-21",
                "installments": [
                    {
                        "calendar_days": 60,
                        "workdays": 39.0,
                        "business_due_date": "2025-01-21",
                        "due_date": "2025-01-21",
                        "due_principal": 376.18,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 13.4739126445,
                        "tax_amount": 0.42570834978906,
                        "total_amount": 100,
                        "principal_amortization_amount": 86.5260873555,
                        "installment_number": 1
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 23.0,
                        "business_due_date": "2025-02-21",
                        "due_date": "2025-02-21",
                        "due_principal": 289.6539126445,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 5.3146959395,
                        "tax_amount": 0.706541738899451,
                        "total_amount": 100,
                        "principal_amortization_amount": 94.6853040605,
                        "installment_number": 2
                    },
                    {
                        "calendar_days": 28,
                        "workdays": 18.0,
                        "business_due_date": "2025-03-21",
                        "due_date": "2025-03-21",
                        "due_principal": 194.968608584,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.2283291407,
                        "tax_amount": 0.9442979642450494,
                        "total_amount": 100,
                        "principal_amortization_amount": 96.7716708593,
                        "installment_number": 3
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 21.0,
                        "business_due_date": "2025-04-21",
                        "due_date": "2025-04-21",
                        "due_principal": 98.1969377247,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.8017757158,
                        "tax_amount": 1.20783815869566,
                        "total_amount": 100,
                        "principal_amortization_amount": 98.1982242842,
                        "installment_number": 4
                    }
                ],
                "issue_amount": 376.18,
                "disbursed_issue_amount": 368.21,
                "assignment_amount": 376.18,
                "final_disbursement_amount": 368.21,
                "prefixed_interest_rate": {
                    "interest_base": "calendar_days_365",
                    "annual_rate": 0.23872053,
                    "monthly_rate": 0.018,
                    "daily_rate": 0.00058669
                },
                "refinanced_credit_operations": [
                    {
                        "due_balance": 833.55,
                        "due_balance_reference_date": "2025-07-16",
                        "original_deadline": 275,
                        "refinanced_credit_operation_key": "dd65582d-ea63-44ab-8ee8-438b2d7246c7",
                        "refinanced_credit_operation_status": "pending_payment"
                    }
                ]
            }
        ]
    }
}
```

---

## 2 - Emissão da operação:

REFINANCIAMENTO

### Request

**POST**
/debt

Testar no Playground

```json title='Request Body'
{
    "borrower": {
        "name": "Nome devedor",
        "email":"email.devedor@gmail.com",
        "phone": {
            "number": "999538380",
            "area_code": "84",
            "country_code": "055"
        },
        "gender": "female",
        "political_exposition": "not_exposed",
        "address": {
            "city": "Natal",
            "state": "RN",
            "number": "1984",
            "street": "Rua",
            "complement": "complemento",
            "postal_code": "59065720",
            "neighborhood": "bairro"
        },
        "role_type": "issuer",
        "birth_date": "1959-07-08",
        "mother_name": "NOME DA MAE",
        "nationality": "Brasileiro",
        "person_type": "natural",
        "marital_status": "single",
        "attached_documents_list": [],
        "individual_document_number": "14471835092",
        "document_identification_date": "2015-10-02",
        "document_identification_type": "rg",
        "document_identification_number": "003709888"
    },
    "financial": {
        "interest_type": "pre_price_days",
        "first_due_date": "2023-09-21",
        "disbursement_date": "2024-11-07",
        "fine_configuration": {
            "monthly_rate": 0.0166,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "monthly_interest_rate": 0.0166,
        "installment_face_value": 101.84,
        "limit_days_to_disburse": 7,
        "number_of_installments": 10,
        "principal_grace_period": 0,
        "rebates": [ // Opcional
            {
                "amount": 20,
                "rebate_bank_account": {
                    "name": "Teste Ltda",
                    "document_number": "18533555000164",
                    "account_digit": "0",
                    "account_number": "4290001",
                    "branch_number": "0001",
                    "bank_code": "329"
                },
                "amount_type": "percentage",
                "fee_type": "spread"
            }
        ]
    },
    "simplified": true,
    "collaterals": [
        {
            "percentage": 1,
            "collateral_type": "private_payroll",
            "collateral_data": {
                "employer_document_number": "07940839000159",
                "registration_number": "99999999999-A"
            }
        }
    ],
    "additional_data": {
        "contract": {
            "contract_number": "TST0000644799"
        }
    },
    "purchaser_document_number": "32402502000135",
    "disbursement_bank_accounts": [
        {
            "name": "NOME DEVEDOR",
            "bank_code": "001",
            "account_digit": "0",
            "branch_number": "2874",
            "account_number": "000057555",
            "document_number": "14471835092",
            "transfer_method": "pix",
            "percentage_receivable": 100
        }
    ],
    "refinanced_credit_operations": [
        {
        "operation_key": "dd65582d-ea63-44ab-8ee8-438b2d7246c7"
        }
    ]
}
```

### Response

STATUS
**201** (Created)

**Response Body**

```json title="Response Body"
{
    "webhook_type": "debt",
    "key": "<Debt Key>",
    "status": "waiting_signature",
    "event_datetime": "2024-11-07 23:19:22",
    "data": {
        "borrower": {
            "name": "Nome devedor",
            "document_number": "14471835092",
            "related_party_key": "28b7fc16-6d1f-467d-9667-62a8c13daea6"
        },
        "contract": {
            "number": "TST0000644710",
            "urls": [
                "https://storage.googleapis.com/sandbox-doc-api/documents/a2e9c83a-3666-4def-8b27-e96fabb8705c/NOME_DEVEDOR-CCB-TST0000644710-20241107231916.pdf"
            ],
            "signature_information": [
                {
                    "signer_name": "Nome devedor",
                    "signer_document_number": "14471835092",
                    "signer_role": "issuer",
                    "signer_email": null,
                    "signer_external_key": null,
                    "signature_url": null
                }
            ]
        },
        "requester_identifier_key": "eb859ebe-3a41-49bf-a6c3-d6902039ec00",
        "iof_charge_method": "financed",
        "collaterals": [
            {
                "absolute_amount": null,
                "collateral_constituted": false,
                "collateral_data": {
                    "registration_number": "99999999999-A",
                    "employer_document_number": "07940839000159"
                },
                "collateral_key": "26c7f4f4-51f3-41fa-b880-9691211136aa",
                "collateral_type": "private_payroll",
                "created_at": "2024-11-07T23:19:16.413448",
                "external_key": null,
                "percentage": 1,
                "updated_at": "2024-11-07T23:19:16.413441"
            }
        ],
        "disbursement_options": [
            {
                "disbursement_date": "2024-11-07",
                "contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 4.55
                    },
                    {
                        "fee_type": "ted_fee",
                        "fee_amount": 1.5
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0
                    }
                ],
                "contract_fee_amount": 6.05,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "assignment_amount": 914.3,
                "issue_amount": 909.75,
                "cet": "2,0100%",
                "annual_cet": "27,0481%",
                "base_iof": 16.259002146803677,
                "additional_iof": 3.45705,
                "total_iof": 19.72,
                "total_pre_fixed_amount": 108.6508885851,
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-01-21",
                        "calendar_days": 74,
                        "due_date": "2025-01-21",
                        "due_interest": 0.0,
                        "due_principal": 909.75,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 37.1789024864,
                        "principal_amortization_amount": 64.6610975136,
                        "tax_amount": 0.3923635397125248,
                        "total_amount": 101.84,
                        "workdays": 49.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-02-21",
                        "calendar_days": 31,
                        "due_date": "2025-02-21",
                        "due_interest": 0.0,
                        "due_principal": 845.0889024864,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 2,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 14.2997636051,
                        "principal_amortization_amount": 87.5402363949,
                        "tax_amount": 0.753721435360089,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-03-21",
                        "calendar_days": 28,
                        "due_date": "2025-03-21",
                        "due_interest": 0.0,
                        "due_principal": 757.5486660915,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 3,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 11.5685715131,
                        "principal_amortization_amount": 90.2714284869,
                        "tax_amount": 0.9845001990781314,
                        "total_amount": 101.84,
                        "workdays": 18.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-04-21",
                        "calendar_days": 33,
                        "due_date": "2025-04-21",
                        "due_interest": 0.0,
                        "due_principal": 667.2772376046,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 4,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 12.025984633,
                        "principal_amortization_amount": 89.814015367,
                        "tax_amount": 1.222548377175604,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-05-21",
                        "calendar_days": 28,
                        "due_date": "2025-05-21",
                        "due_interest": 0.0,
                        "due_principal": 577.4632222376,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 5,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.8184725787,
                        "principal_amortization_amount": 93.0215274213,
                        "tax_amount": 1.4797864582180404,
                        "total_amount": 101.84,
                        "workdays": 19.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-06-21",
                        "calendar_days": 31,
                        "due_date": "2025-06-21",
                        "due_interest": 0.0,
                        "due_principal": 484.4416948163,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 6,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.1972396908,
                        "principal_amortization_amount": 93.6427603092,
                        "tax_amount": 1.72770892770474,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-07-21",
                        "calendar_days": 31,
                        "due_date": "2025-07-21",
                        "due_interest": 0.0,
                        "due_principal": 390.7989345071,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 7,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 6.6127072945,
                        "principal_amortization_amount": 95.2272927055,
                        "tax_amount": 1.999011328473856,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-08-21",
                        "calendar_days": 30,
                        "due_date": "2025-08-21",
                        "due_interest": 0.0,
                        "due_principal": 295.5716418016,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 8,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 4.8387153664,
                        "principal_amortization_amount": 97.0012846336,
                        "tax_amount": 2.274874127227187,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-09-21",
                        "calendar_days": 33,
                        "due_date": "2025-09-21",
                        "due_interest": 0.0,
                        "due_principal": 198.570357168,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 9,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.5787172455,
                        "principal_amortization_amount": 98.2612827545,
                        "tax_amount": 2.570318634292211,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-10-21",
                        "calendar_days": 28,
                        "due_date": "2025-10-21",
                        "due_interest": 0.0,
                        "due_principal": 100.3090744135,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 10,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.5318141716,
                        "principal_amortization_amount": 100.3081858284,
                        "tax_amount": 2.8541691195612935,
                        "total_amount": 101.84,
                        "workdays": 20.0,
                        "installment_status": null,
                        "installment_type": null
                    }
                ],
                "first_due_date": "2025-01-21",
                "prefixed_interest_rate": {
                    "monthly_rate": 0.0166,
                    "daily_rate": 0.00054142,
                    "annual_rate": 0.21843191,
                    "interest_base": "calendar_days_365"
                }
            },
            {
                "disbursement_date": "2024-11-08",
                "contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 4.55
                    },
                    {
                        "fee_type": "ted_fee",
                        "fee_amount": 1.5
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0
                    }
                ],
                "contract_fee_amount": 6.05,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "assignment_amount": 914.79,
                "issue_amount": 910.24,
                "cet": "2,0200%",
                "annual_cet": "27,0539%",
                "base_iof": 16.187351160427028,
                "additional_iof": 3.458912,
                "total_iof": 19.65,
                "total_pre_fixed_amount": 108.1583324947,
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-01-21",
                        "calendar_days": 73,
                        "due_date": "2025-01-21",
                        "due_interest": 0.0,
                        "due_principal": 910.24,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 36.6863463961,
                        "principal_amortization_amount": 65.1536536039,
                        "tax_amount": 0.3900097704729454,
                        "total_amount": 101.84,
                        "workdays": 48.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-02-21",
                        "calendar_days": 31,
                        "due_date": "2025-02-21",
                        "due_interest": 0.0,
                        "due_principal": 845.0863463961,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 2,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 14.2997636051,
                        "principal_amortization_amount": 87.5402363949,
                        "tax_amount": 0.7465431359757072,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-03-21",
                        "calendar_days": 28,
                        "due_date": "2025-03-21",
                        "due_interest": 0.0,
                        "due_principal": 757.5461100012,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 3,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 11.5685715131,
                        "principal_amortization_amount": 90.2714284869,
                        "tax_amount": 0.9770979419422056,
                        "total_amount": 101.84,
                        "workdays": 18.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-04-21",
                        "calendar_days": 33,
                        "due_date": "2025-04-21",
                        "due_interest": 0.0,
                        "due_principal": 667.2746815143,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 4,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 12.025984633,
                        "principal_amortization_amount": 89.814015367,
                        "tax_amount": 1.21518362791551,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-05-21",
                        "calendar_days": 28,
                        "due_date": "2025-05-21",
                        "due_interest": 0.0,
                        "due_principal": 577.4606661473,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 5,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.8184725787,
                        "principal_amortization_amount": 93.0215274213,
                        "tax_amount": 1.4721586929694939,
                        "total_amount": 101.84,
                        "workdays": 19.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-06-21",
                        "calendar_days": 31,
                        "due_date": "2025-06-21",
                        "due_interest": 0.0,
                        "due_principal": 484.439138726,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 6,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.1972396908,
                        "principal_amortization_amount": 93.6427603092,
                        "tax_amount": 1.7200302213593857,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-07-21",
                        "calendar_days": 31,
                        "due_date": "2025-07-21",
                        "due_interest": 0.0,
                        "due_principal": 390.7963784168,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 7,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 6.6127072945,
                        "principal_amortization_amount": 95.2272927055,
                        "tax_amount": 1.991202690472005,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-08-21",
                        "calendar_days": 30,
                        "due_date": "2025-08-21",
                        "due_interest": 0.0,
                        "due_principal": 295.5690857113,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 8,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 4.8387153664,
                        "principal_amortization_amount": 97.0012846336,
                        "tax_amount": 2.266920021887232,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-09-21",
                        "calendar_days": 33,
                        "due_date": "2025-09-21",
                        "due_interest": 0.0,
                        "due_principal": 198.5678010777,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 9,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.5787172455,
                        "principal_amortization_amount": 98.2612827545,
                        "tax_amount": 2.562261209106342,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-10-21",
                        "calendar_days": 28,
                        "due_date": "2025-10-21",
                        "due_interest": 0.0,
                        "due_principal": 100.3065183232,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 10,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.5318141715,
                        "principal_amortization_amount": 100.3081858285,
                        "tax_amount": 2.845943848326202,
                        "total_amount": 101.84,
                        "workdays": 20.0,
                        "installment_status": null,
                        "installment_type": null
                    }
                ],
                "first_due_date": "2025-01-21",
                "prefixed_interest_rate": {
                    "monthly_rate": 0.0166,
                    "daily_rate": 0.00054142,
                    "annual_rate": 0.21843191,
                    "interest_base": "calendar_days_365"
                }
            },
            {
                "disbursement_date": "2024-11-09",
                "contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 4.55
                    },
                    {
                        "fee_type": "ted_fee",
                        "fee_amount": 1.5
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0
                    }
                ],
                "contract_fee_amount": 6.05,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "assignment_amount": 915.28,
                "issue_amount": 910.73,
                "cet": "2,0200%",
                "annual_cet": "27,0599%",
                "base_iof": 16.115620969325082,
                "additional_iof": 3.460774,
                "total_iof": 19.58,
                "total_pre_fixed_amount": 107.6655097248,
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-01-21",
                        "calendar_days": 72,
                        "due_date": "2025-01-21",
                        "due_interest": 0.0,
                        "due_principal": 910.73,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 36.1935236262,
                        "principal_amortization_amount": 65.6464763738,
                        "tax_amount": 0.3875767965109152,
                        "total_amount": 101.84,
                        "workdays": 48.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-02-21",
                        "calendar_days": 31,
                        "due_date": "2025-02-21",
                        "due_interest": 0.0,
                        "due_principal": 845.0835236262,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 2,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 14.2997636051,
                        "principal_amortization_amount": 87.5402363949,
                        "tax_amount": 0.7393648365913253,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-03-21",
                        "calendar_days": 28,
                        "due_date": "2025-03-21",
                        "due_interest": 0.0,
                        "due_principal": 757.5432872313,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 3,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 11.5685715131,
                        "principal_amortization_amount": 90.2714284869,
                        "tax_amount": 0.9696956848062798,
                        "total_amount": 101.84,
                        "workdays": 18.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-04-21",
                        "calendar_days": 33,
                        "due_date": "2025-04-21",
                        "due_interest": 0.0,
                        "due_principal": 667.2718587444,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 4,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 12.025984633,
                        "principal_amortization_amount": 89.814015367,
                        "tax_amount": 1.207818878655416,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-05-21",
                        "calendar_days": 28,
                        "due_date": "2025-05-21",
                        "due_interest": 0.0,
                        "due_principal": 577.4578433774,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 5,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.8184725787,
                        "principal_amortization_amount": 93.0215274213,
                        "tax_amount": 1.4645309277209473,
                        "total_amount": 101.84,
                        "workdays": 19.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-06-21",
                        "calendar_days": 31,
                        "due_date": "2025-06-21",
                        "due_interest": 0.0,
                        "due_principal": 484.4363159561,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 6,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.1972396908,
                        "principal_amortization_amount": 93.6427603092,
                        "tax_amount": 1.7123515150140312,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-07-21",
                        "calendar_days": 31,
                        "due_date": "2025-07-21",
                        "due_interest": 0.0,
                        "due_principal": 390.7935556469,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 7,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 6.6127072945,
                        "principal_amortization_amount": 95.2272927055,
                        "tax_amount": 1.983394052470154,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-08-21",
                        "calendar_days": 30,
                        "due_date": "2025-08-21",
                        "due_interest": 0.0,
                        "due_principal": 295.5662629414,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 8,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 4.8387153664,
                        "principal_amortization_amount": 97.0012846336,
                        "tax_amount": 2.2589659165472766,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-09-21",
                        "calendar_days": 33,
                        "due_date": "2025-09-21",
                        "due_interest": 0.0,
                        "due_principal": 198.5649783078,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 9,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.5787172455,
                        "principal_amortization_amount": 98.2612827545,
                        "tax_amount": 2.554203783920473,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-10-21",
                        "calendar_days": 28,
                        "due_date": "2025-10-21",
                        "due_interest": 0.0,
                        "due_principal": 100.3036955533,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 10,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.5318141715,
                        "principal_amortization_amount": 100.3081858285,
                        "tax_amount": 2.837718577088265,
                        "total_amount": 101.84,
                        "workdays": 20.0,
                        "installment_status": null,
                        "installment_type": null
                    }
                ],
                "first_due_date": "2025-01-21",
                "prefixed_interest_rate": {
                    "monthly_rate": 0.0166,
                    "daily_rate": 0.00054142,
                    "annual_rate": 0.21843191,
                    "interest_base": "calendar_days_365"
                }
            },
            {
                "disbursement_date": "2024-11-10",
                "contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 4.56
                    },
                    {
                        "fee_type": "ted_fee",
                        "fee_amount": 1.5
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0
                    }
                ],
                "contract_fee_amount": 6.06,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "assignment_amount": 915.79,
                "issue_amount": 911.23,
                "cet": "2,0200%",
                "annual_cet": "27,0635%",
                "base_iof": 16.0438115087348,
                "additional_iof": 3.462674,
                "total_iof": 19.51,
                "total_pre_fixed_amount": 107.1724201311,
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-01-21",
                        "calendar_days": 71,
                        "due_date": "2025-01-21",
                        "due_interest": 0.0,
                        "due_principal": 911.23,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 35.7004340324,
                        "principal_amortization_amount": 66.1395659676,
                        "tax_amount": 0.3850645530633672,
                        "total_amount": 101.84,
                        "workdays": 48.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-02-21",
                        "calendar_days": 31,
                        "due_date": "2025-02-21",
                        "due_interest": 0.0,
                        "due_principal": 845.0904340324,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 2,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 14.2997636051,
                        "principal_amortization_amount": 87.5402363949,
                        "tax_amount": 0.7321865372069436,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-03-21",
                        "calendar_days": 28,
                        "due_date": "2025-03-21",
                        "due_interest": 0.0,
                        "due_principal": 757.5501976375,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 3,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 11.5685715131,
                        "principal_amortization_amount": 90.2714284869,
                        "tax_amount": 0.962293427670354,
                        "total_amount": 101.84,
                        "workdays": 18.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-04-21",
                        "calendar_days": 33,
                        "due_date": "2025-04-21",
                        "due_interest": 0.0,
                        "due_principal": 667.2787691506,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 4,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 12.025984633,
                        "principal_amortization_amount": 89.814015367,
                        "tax_amount": 1.200454129395322,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-05-21",
                        "calendar_days": 28,
                        "due_date": "2025-05-21",
                        "due_interest": 0.0,
                        "due_principal": 577.4647537836,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 5,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.8184725787,
                        "principal_amortization_amount": 93.0215274213,
                        "tax_amount": 1.4569031624724007,
                        "total_amount": 101.84,
                        "workdays": 19.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-06-21",
                        "calendar_days": 31,
                        "due_date": "2025-06-21",
                        "due_interest": 0.0,
                        "due_principal": 484.4432263623,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 6,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.1972396908,
                        "principal_amortization_amount": 93.6427603092,
                        "tax_amount": 1.7046728086686769,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-07-21",
                        "calendar_days": 31,
                        "due_date": "2025-07-21",
                        "due_interest": 0.0,
                        "due_principal": 390.8004660531,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 7,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 6.6127072945,
                        "principal_amortization_amount": 95.2272927055,
                        "tax_amount": 1.975585414468303,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-08-21",
                        "calendar_days": 30,
                        "due_date": "2025-08-21",
                        "due_interest": 0.0,
                        "due_principal": 295.5731733476,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 8,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 4.8387153664,
                        "principal_amortization_amount": 97.0012846336,
                        "tax_amount": 2.2510118112073214,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-09-21",
                        "calendar_days": 33,
                        "due_date": "2025-09-21",
                        "due_interest": 0.0,
                        "due_principal": 198.571888714,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 9,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.5787172455,
                        "principal_amortization_amount": 98.2612827545,
                        "tax_amount": 2.546146358734604,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-10-21",
                        "calendar_days": 28,
                        "due_date": "2025-10-21",
                        "due_interest": 0.0,
                        "due_principal": 100.3106059595,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 10,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.5318141716,
                        "principal_amortization_amount": 100.3081858284,
                        "tax_amount": 2.829493305847507,
                        "total_amount": 101.84,
                        "workdays": 20.0,
                        "installment_status": null,
                        "installment_type": null
                    }
                ],
                "first_due_date": "2025-01-21",
                "prefixed_interest_rate": {
                    "monthly_rate": 0.0166,
                    "daily_rate": 0.00054142,
                    "annual_rate": 0.21843191,
                    "interest_base": "calendar_days_365"
                }
            },
            {
                "disbursement_date": "2024-11-11",
                "contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 4.56
                    },
                    {
                        "fee_type": "ted_fee",
                        "fee_amount": 1.5
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0
                    }
                ],
                "contract_fee_amount": 6.06,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "assignment_amount": 916.28,
                "issue_amount": 911.72,
                "cet": "2,0200%",
                "annual_cet": "27,0698%",
                "base_iof": 15.971922713858204,
                "additional_iof": 3.464536,
                "total_iof": 19.44,
                "total_pre_fixed_amount": 106.6790635687,
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-01-21",
                        "calendar_days": 70,
                        "due_date": "2025-01-21",
                        "due_interest": 0.0,
                        "due_principal": 911.72,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 35.2070774702,
                        "principal_amortization_amount": 66.6329225298,
                        "tax_amount": 0.382472975321052,
                        "total_amount": 101.84,
                        "workdays": 47.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-02-21",
                        "calendar_days": 31,
                        "due_date": "2025-02-21",
                        "due_interest": 0.0,
                        "due_principal": 845.0870774702,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 2,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 14.2997636051,
                        "principal_amortization_amount": 87.5402363949,
                        "tax_amount": 0.7250082378225619,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-03-21",
                        "calendar_days": 28,
                        "due_date": "2025-03-21",
                        "due_interest": 0.0,
                        "due_principal": 757.5468410753,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 3,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 11.5685715131,
                        "principal_amortization_amount": 90.2714284869,
                        "tax_amount": 0.9548911705344282,
                        "total_amount": 101.84,
                        "workdays": 18.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-04-21",
                        "calendar_days": 33,
                        "due_date": "2025-04-21",
                        "due_interest": 0.0,
                        "due_principal": 667.2754125884,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 4,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 12.025984633,
                        "principal_amortization_amount": 89.814015367,
                        "tax_amount": 1.193089380135228,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-05-21",
                        "calendar_days": 28,
                        "due_date": "2025-05-21",
                        "due_interest": 0.0,
                        "due_principal": 577.4613972214,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 5,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.8184725787,
                        "principal_amortization_amount": 93.0215274213,
                        "tax_amount": 1.449275397223854,
                        "total_amount": 101.84,
                        "workdays": 19.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-06-21",
                        "calendar_days": 31,
                        "due_date": "2025-06-21",
                        "due_interest": 0.0,
                        "due_principal": 484.4398698001,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 6,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.1972396908,
                        "principal_amortization_amount": 93.6427603092,
                        "tax_amount": 1.6969941023233224,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-07-21",
                        "calendar_days": 31,
                        "due_date": "2025-07-21",
                        "due_interest": 0.0,
                        "due_principal": 390.7971094909,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 7,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 6.6127072945,
                        "principal_amortization_amount": 95.2272927055,
                        "tax_amount": 1.967776776466452,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-08-21",
                        "calendar_days": 30,
                        "due_date": "2025-08-21",
                        "due_interest": 0.0,
                        "due_principal": 295.5698167854,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 8,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 4.8387153664,
                        "principal_amortization_amount": 97.0012846336,
                        "tax_amount": 2.243057705867366,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-09-21",
                        "calendar_days": 33,
                        "due_date": "2025-09-21",
                        "due_interest": 0.0,
                        "due_principal": 198.5685321518,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 9,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.5787172455,
                        "principal_amortization_amount": 98.2612827545,
                        "tax_amount": 2.538088933548735,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-10-21",
                        "calendar_days": 28,
                        "due_date": "2025-10-21",
                        "due_interest": 0.0,
                        "due_principal": 100.3072493973,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 10,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.5318141714,
                        "principal_amortization_amount": 100.3081858286,
                        "tax_amount": 2.8212680346152035,
                        "total_amount": 101.84,
                        "workdays": 20.0,
                        "installment_status": null,
                        "installment_type": null
                    }
                ],
                "first_due_date": "2025-01-21",
                "prefixed_interest_rate": {
                    "monthly_rate": 0.0166,
                    "daily_rate": 0.00054142,
                    "annual_rate": 0.21843191,
                    "interest_base": "calendar_days_365"
                }
            },
            {
                "disbursement_date": "2024-11-12",
                "contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 4.56
                    },
                    {
                        "fee_type": "ted_fee",
                        "fee_amount": 1.5
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0
                    }
                ],
                "contract_fee_amount": 6.06,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "assignment_amount": 916.77,
                "issue_amount": 912.21,
                "cet": "2,0200%",
                "annual_cet": "27,0762%",
                "base_iof": 15.899954519820076,
                "additional_iof": 3.466398,
                "total_iof": 19.37,
                "total_pre_fixed_amount": 106.1854398936,
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-01-21",
                        "calendar_days": 69,
                        "due_date": "2025-01-21",
                        "due_interest": 0.0,
                        "due_principal": 912.21,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 34.7134537949,
                        "principal_amortization_amount": 67.1265462051,
                        "tax_amount": 0.3798019984284558,
                        "total_amount": 101.84,
                        "workdays": 46.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-02-21",
                        "calendar_days": 31,
                        "due_date": "2025-02-21",
                        "due_interest": 0.0,
                        "due_principal": 845.0834537949,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 2,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 14.2997636051,
                        "principal_amortization_amount": 87.5402363949,
                        "tax_amount": 0.71782993843818,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-03-21",
                        "calendar_days": 28,
                        "due_date": "2025-03-21",
                        "due_interest": 0.0,
                        "due_principal": 757.5432174,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 3,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 11.5685715131,
                        "principal_amortization_amount": 90.2714284869,
                        "tax_amount": 0.9474889133985024,
                        "total_amount": 101.84,
                        "workdays": 18.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-04-21",
                        "calendar_days": 33,
                        "due_date": "2025-04-21",
                        "due_interest": 0.0,
                        "due_principal": 667.2717889131,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 4,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 12.025984633,
                        "principal_amortization_amount": 89.814015367,
                        "tax_amount": 1.185724630875134,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-05-21",
                        "calendar_days": 28,
                        "due_date": "2025-05-21",
                        "due_interest": 0.0,
                        "due_principal": 577.4577735461,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 5,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.8184725787,
                        "principal_amortization_amount": 93.0215274213,
                        "tax_amount": 1.4416476319753073,
                        "total_amount": 101.84,
                        "workdays": 19.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-06-21",
                        "calendar_days": 31,
                        "due_date": "2025-06-21",
                        "due_interest": 0.0,
                        "due_principal": 484.4362461248,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 6,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.1972396908,
                        "principal_amortization_amount": 93.6427603092,
                        "tax_amount": 1.689315395977968,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-07-21",
                        "calendar_days": 31,
                        "due_date": "2025-07-21",
                        "due_interest": 0.0,
                        "due_principal": 390.7934858156,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 7,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 6.6127072945,
                        "principal_amortization_amount": 95.2272927055,
                        "tax_amount": 1.959968138464601,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-08-21",
                        "calendar_days": 30,
                        "due_date": "2025-08-21",
                        "due_interest": 0.0,
                        "due_principal": 295.5661931101,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 8,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 4.8387153664,
                        "principal_amortization_amount": 97.0012846336,
                        "tax_amount": 2.2351036005274114,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-09-21",
                        "calendar_days": 33,
                        "due_date": "2025-09-21",
                        "due_interest": 0.0,
                        "due_principal": 198.5649084765,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 9,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.5787172455,
                        "principal_amortization_amount": 98.2612827545,
                        "tax_amount": 2.530031508362866,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-10-21",
                        "calendar_days": 28,
                        "due_date": "2025-10-21",
                        "due_interest": 0.0,
                        "due_principal": 100.303625722,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 10,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.5318141716,
                        "principal_amortization_amount": 100.3081858284,
                        "tax_amount": 2.8130427633716497,
                        "total_amount": 101.84,
                        "workdays": 20.0,
                        "installment_status": null,
                        "installment_type": null
                    }
                ],
                "first_due_date": "2025-01-21",
                "prefixed_interest_rate": {
                    "monthly_rate": 0.0166,
                    "daily_rate": 0.00054142,
                    "annual_rate": 0.21843191,
                    "interest_base": "calendar_days_365"
                }
            },
            {
                "disbursement_date": "2024-11-13",
                "contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 4.56
                    },
                    {
                        "fee_type": "ted_fee",
                        "fee_amount": 1.5
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0
                    }
                ],
                "contract_fee_amount": 6.06,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "assignment_amount": 917.27,
                "issue_amount": 912.71,
                "cet": "2,0200%",
                "annual_cet": "27,0802%",
                "base_iof": 15.827906861727051,
                "additional_iof": 3.468298,
                "total_iof": 19.3,
                "total_pre_fixed_amount": 105.691548961,
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-01-21",
                        "calendar_days": 68,
                        "due_date": "2025-01-21",
                        "due_interest": 0.0,
                        "due_principal": 912.71,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 34.2195628621,
                        "principal_amortization_amount": 67.6204371379,
                        "tax_amount": 0.3770515574809304,
                        "total_amount": 101.84,
                        "workdays": 45.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-02-21",
                        "calendar_days": 31,
                        "due_date": "2025-02-21",
                        "due_interest": 0.0,
                        "due_principal": 845.0895628621,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 2,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 14.2997636051,
                        "principal_amortization_amount": 87.5402363949,
                        "tax_amount": 0.7106516390537982,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-03-21",
                        "calendar_days": 28,
                        "due_date": "2025-03-21",
                        "due_interest": 0.0,
                        "due_principal": 757.5493264672,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 3,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 11.5685715131,
                        "principal_amortization_amount": 90.2714284869,
                        "tax_amount": 0.9400866562625766,
                        "total_amount": 101.84,
                        "workdays": 18.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-04-21",
                        "calendar_days": 33,
                        "due_date": "2025-04-21",
                        "due_interest": 0.0,
                        "due_principal": 667.2778979803,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 4,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 12.025984633,
                        "principal_amortization_amount": 89.814015367,
                        "tax_amount": 1.17835988161504,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-05-21",
                        "calendar_days": 28,
                        "due_date": "2025-05-21",
                        "due_interest": 0.0,
                        "due_principal": 577.4638826133,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 5,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.8184725787,
                        "principal_amortization_amount": 93.0215274213,
                        "tax_amount": 1.4340198667267607,
                        "total_amount": 101.84,
                        "workdays": 19.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-06-21",
                        "calendar_days": 31,
                        "due_date": "2025-06-21",
                        "due_interest": 0.0,
                        "due_principal": 484.442355192,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 6,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.1972396908,
                        "principal_amortization_amount": 93.6427603092,
                        "tax_amount": 1.6816366896326136,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-07-21",
                        "calendar_days": 31,
                        "due_date": "2025-07-21",
                        "due_interest": 0.0,
                        "due_principal": 390.7995948828,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 7,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 6.6127072945,
                        "principal_amortization_amount": 95.2272927055,
                        "tax_amount": 1.95215950046275,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-08-21",
                        "calendar_days": 30,
                        "due_date": "2025-08-21",
                        "due_interest": 0.0,
                        "due_principal": 295.5723021773,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 8,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 4.8387153664,
                        "principal_amortization_amount": 97.0012846336,
                        "tax_amount": 2.227149495187456,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-09-21",
                        "calendar_days": 33,
                        "due_date": "2025-09-21",
                        "due_interest": 0.0,
                        "due_principal": 198.5710175437,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 9,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.5787172455,
                        "principal_amortization_amount": 98.2612827545,
                        "tax_amount": 2.521974083176997,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-10-21",
                        "calendar_days": 28,
                        "due_date": "2025-10-21",
                        "due_interest": 0.0,
                        "due_principal": 100.3097347892,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 10,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.5318141718,
                        "principal_amortization_amount": 100.3081858282,
                        "tax_amount": 2.8048174921281284,
                        "total_amount": 101.84,
                        "workdays": 20.0,
                        "installment_status": null,
                        "installment_type": null
                    }
                ],
                "first_due_date": "2025-01-21",
                "prefixed_interest_rate": {
                    "monthly_rate": 0.0166,
                    "daily_rate": 0.00054142,
                    "annual_rate": 0.21843191,
                    "interest_base": "calendar_days_365"
                }
            },
            {
                "disbursement_date": "2024-11-14",
                "contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 4.57
                    },
                    {
                        "fee_type": "ted_fee",
                        "fee_amount": 1.5
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0
                    }
                ],
                "contract_fee_amount": 6.07,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "assignment_amount": 917.77,
                "issue_amount": 913.2,
                "cet": "2,0200%",
                "annual_cet": "27,0870%",
                "base_iof": 15.755779674642707,
                "additional_iof": 3.47016,
                "total_iof": 19.23,
                "total_pre_fixed_amount": 105.1973906257,
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-01-21",
                        "calendar_days": 67,
                        "due_date": "2025-01-21",
                        "due_interest": 0.0,
                        "due_principal": 913.2,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 33.7254045271,
                        "principal_amortization_amount": 68.1145954729,
                        "tax_amount": 0.3742215875281126,
                        "total_amount": 101.84,
                        "workdays": 44.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-02-21",
                        "calendar_days": 31,
                        "due_date": "2025-02-21",
                        "due_interest": 0.0,
                        "due_principal": 845.0854045271,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 2,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 14.2997636051,
                        "principal_amortization_amount": 87.5402363949,
                        "tax_amount": 0.7034733396694164,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-03-21",
                        "calendar_days": 28,
                        "due_date": "2025-03-21",
                        "due_interest": 0.0,
                        "due_principal": 757.5451681322,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 3,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 11.5685715131,
                        "principal_amortization_amount": 90.2714284869,
                        "tax_amount": 0.9326843991266508,
                        "total_amount": 101.84,
                        "workdays": 18.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-04-21",
                        "calendar_days": 33,
                        "due_date": "2025-04-21",
                        "due_interest": 0.0,
                        "due_principal": 667.2737396453,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 4,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 12.025984633,
                        "principal_amortization_amount": 89.814015367,
                        "tax_amount": 1.170995132354946,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-05-21",
                        "calendar_days": 28,
                        "due_date": "2025-05-21",
                        "due_interest": 0.0,
                        "due_principal": 577.4597242783,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 5,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.8184725787,
                        "principal_amortization_amount": 93.0215274213,
                        "tax_amount": 1.4263921014782142,
                        "total_amount": 101.84,
                        "workdays": 19.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-06-21",
                        "calendar_days": 31,
                        "due_date": "2025-06-21",
                        "due_interest": 0.0,
                        "due_principal": 484.438196857,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 6,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.1972396908,
                        "principal_amortization_amount": 93.6427603092,
                        "tax_amount": 1.6739579832872593,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-07-21",
                        "calendar_days": 31,
                        "due_date": "2025-07-21",
                        "due_interest": 0.0,
                        "due_principal": 390.7954365478,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 7,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 6.6127072945,
                        "principal_amortization_amount": 95.2272927055,
                        "tax_amount": 1.944350862460899,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-08-21",
                        "calendar_days": 30,
                        "due_date": "2025-08-21",
                        "due_interest": 0.0,
                        "due_principal": 295.5681438423,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 8,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 4.8387153664,
                        "principal_amortization_amount": 97.0012846336,
                        "tax_amount": 2.219195389847501,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-09-21",
                        "calendar_days": 33,
                        "due_date": "2025-09-21",
                        "due_interest": 0.0,
                        "due_principal": 198.5668592087,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 9,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.5787172455,
                        "principal_amortization_amount": 98.2612827545,
                        "tax_amount": 2.513916657991128,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-10-21",
                        "calendar_days": 28,
                        "due_date": "2025-10-21",
                        "due_interest": 0.0,
                        "due_principal": 100.3055764542,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 10,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.5318141715,
                        "principal_amortization_amount": 100.3081858285,
                        "tax_amount": 2.79659222089858,
                        "total_amount": 101.84,
                        "workdays": 20.0,
                        "installment_status": null,
                        "installment_type": null
                    }
                ],
                "first_due_date": "2025-01-21",
                "prefixed_interest_rate": {
                    "monthly_rate": 0.0166,
                    "daily_rate": 0.00054142,
                    "annual_rate": 0.21843191,
                    "interest_base": "calendar_days_365"
                }
            }
        ]
    }
} 
```

## Anexo
### Campos relevantes

| Campo                                             | Descrição                                                                                                                                                                                                        |
|---------------------------------                  |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **issue_amount**                                  | Valor de emissão                                                                                                                            |
| **disbursed_issue_amount**                        | Valor total desembolsado (troco + quitações)                                                                                |
| **final_disbursement_amount**                     | Valor do troco                                                                            |
| **refinanced_credit_operations.due_balance**      | Saldo devedor da dívida refinanciada |

---

# Seguro

URL: /documentation/manual_consignado_privado/manual_seguro

**Este manual passa pelas etapas do fluxo de emissão de crédito consignado privado atrelado à contratação de seguro.**

## 1. Simulação e emissão da dívida

Para simular e emitir uma dívida atrelada à emissão de um seguro, deve-se adicionar um objeto à lista de rebates dentro do objeto finantial.

:::warning Seleção do Produto
O enumerador _description_ é utilizado para definir o tipo de produto de seguro que será emitido, isto interfere diretamente no valor do prêmio e nas coberturas. Consulte a equipe de operações para saber quais enumeradores devem ser utilizados na sua integração.
:::

```json title='Objeto Rebate'
{
  "rebates": [
    {
      "fee_type": "insurance_premium_qi",
      "description": "insurance_premium_description"
    }
  ]
}
```

### Exemplo de payload de simulação

POST /debt

request_body

```json
{
    "borrower": {
        "person_type": "natural"
    },
    "financial": {
        "first_due_date": "2024-12-07",
        "installment_face_value": 100,
        "disbursement_date": "2024-11-05",
        "limit_days_to_disburse": 3,
        "number_of_installments": 4,
        "monthly_interest_rate": 0.018,
        "interest_type": "pre_price_days",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0,
        "rebates": [
          {
            "fee_type": "insurance_premium_qi",
            "description": "insurance_premium_description"
          }
        ]
    }
}
```

### Exemplo payload de emissão

POST /debt_simulation

request_body

```json
{
    "borrower": {
        "name": "Nome devedor",
        "email":"email.devedor@gmail.com",
        "phone": {
            "number": "999538380",
            "area_code": "84",
            "country_code": "055"
        },
        "gender": "female",
        "political_exposition": "not_exposed",
        "address": {
            "city": "Natal",
            "state": "RN",
            "number": "1984",
            "street": "Rua",
            "complement": "complemento",
            "postal_code": "59065720",
            "neighborhood": "bairro"
        },
        "role_type": "issuer",
        "birth_date": "1959-07-08",
        "mother_name": "NOME DA MAE",
        "nationality": "Brasileiro",
        "person_type": "natural",
        "marital_status": "single",
        "attached_documents_list": [],
        "individual_document_number": "14471835092",
        "document_identification_date": "2015-10-02",
        "document_identification_type": "rg",
        "document_identification_number": "003709888"
    },
    "financial": {
        "interest_type": "pre_price_days",
        "first_due_date": "2023-09-21",
        "disbursement_date": "2024-11-07",
        "fine_configuration": {
            "monthly_rate": 0.0166,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "monthly_interest_rate": 0.0166,
        "installment_face_value": 101.84,
        "limit_days_to_disburse": 7,
        "number_of_installments": 10,
        "principal_grace_period": 0,
        "rebates": [ // Opcional
          {
            "fee_type": "insurance_premium_qi",
            "description": "insurance_premium_description"
          }
        ]
    },
    "simplified": true,
    "collaterals": [
        {
            "percentage": 1,
            "collateral_type": "private_payroll",
            "collateral_data": {
                "employer_document_number": "07940839000159",
                "registration_number": "99999999999-A"
            }
        }
    ],
    "additional_data": {
        "contract": {
            "contract_number": "TST0000644799"
        }
    },
    "purchaser_document_number": "32402502000135",
    "disbursement_bank_accounts": [
        {
            "name": "NOME DEVEDOR",
            "bank_code": "001",
            "account_digit": "0",
            "branch_number": "2874",
            "account_number": "000057555",
            "document_number": "14471835092",
            "transfer_method": "pix",
            "percentage_receivable": 100
        }
    ]
}
```

## 2. Formalização

Durante o fluxo de formalização da dívida no QI Sign, serão apresentadas algumas telas para garantir a ciência e o consentimento do tomador em relação à contratação do seguro. 

:::warning OPT-OUT
É possível que o tomador decida abandonar a contratação do seguro e seguir somente com a contratação do crédito, neste caso o valor que seria destinado ao prêmio do seguro também será desembolsado na conta do tomador.
:::

Junto ao webhook de formalização do crédito, será enviado um evento informando se o seguro foi aceito ou rejeitado no fluxo de formalização.

WEBHOOK_TYPE insurance_premium.status_change

Webhook Body

**Operação formalizada com seguro**

```json
{
  "data": {
    "credit_operation_key": "5ae2c008-44c1-4435-bbfa-094a4b11d962"
  },
  "event_datetime": "2023-03-03 22:39:39",
  "key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
  "status": "accepted",
  "webhook_type": "insurance_premium.status_change"
}
```

**Operação formalizada sem seguro**

```json
{
  "data": {
    "credit_operation_key": "5ae2c008-44c1-4435-bbfa-094a4b11d962",
    "rejection_reason": "insurance_rejected" 
  },
  "event_datetime": "2023-03-03 22:39:39",
  "key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
  "status": "rejected",
  "webhook_type": "insurance_premium.status_change"
}
```

## 3. Emissão do seguro

Após o sucesso no desembolso, será realizada a transferência do valor do prêmio e a emissão do seguro, para acompanhamento do status do seguro deve-se monitorar o seguinte webhook.

WEBHOOK_TYPE insurance_premium.status_change

Webhook Body

**Seguro emitido**

```json
{
  "data": {
    "credit_operation_key": "5ae2c008-44c1-4435-bbfa-094a4b11d962",
    "insurance_policy_document_key": "9990ce22-aeac-4728-82da-d1f22c33873f",
    "insurance_date": "2024-09-11",
    "term_start_date": "2024-09-11",
    "term_end_date": "2025-09-11",
    "insurance_amount": 1600,
    "operation_amount": 6400,
    "covers": [
      {
        "cover_amount": 200,
        "cover_type": "permanent_disability",
        "cover_prize_amount": 572.82
      },
      {
        "cover_amount": 100,
        "cover_type": "accidental_death",
        "cover_prize_amount": 572.82
      },
      {
        "capitalcover_amount_segurado": 300,
        "cover_type": "unemployment",
        "cover_prize_amount": 572.82
      }
    ],
    "policy_number": "1098200000008",
    "prize_number": "3907",
    "insurance_premium_net_amount": 1145.63,
    "iof_amount": 4.37
  },
  "event_datetime": "2023-03-03 22:39:39",
  "key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
  "status": "active",
  "webhook_type": "insurance_premium.status_change"
}
```

**Seguro cancelado**

```json
{
    "key": "dc575950-dcce-48e1-99a6-5fb0ada63d86",
    "data": {
        "cancel_reason": "reversed_operation",
        "credit_operation_key": "2fbd6613-3228-5gdg-9377-93db394bf2d4"
    },
    "status": "canceled",
    "webhook_type": "insurance_premium.status_change",
    "event_datetime": "2023-03-03 22:39:39"
}
```

:::info Cancelamento do seguro
Para verificar os possíveis motivos de cancelamento do seguro, consulte a tabela [Motivo de cancelamento](#cancel-insurance).
:::
:::danger Envio obrigatório do bilhete ao tomador
É obrigatório que o pdf do bilhete seja enviado ao tomador após a emissão do seguro, o documento pode ser consultado através da **[consulta de documentos](../upload_de_documentos/consulta_documents)** utilizando a *insurance_policy_document_key* informada no webhook de emissão do seguro.
:::
:::info Testes em Sandbox
Para testar o cancelamento do seguro pode-se utilizar o seguinte endpoint:

POST /mock/insurance_premium/ [INSURANCE-PREMIUM-KEY] /cancel

:::
### Consulta de seguro

Para ativamente consultar as informações de um seguro pode-se utilizar o seguinte endpoint.

GET /debt/ [DEBT-KEY] /insurance_premium/ [INSURANCE-PREMIUM-KEY]

STATUS 200

Response Body

```json
{
  "insurance_premium_key": "e4fe84e3-cc71-481b-87ea-8a07f7d69079",
  "status": "active",
  "credit_operation_key": "5ae2c008-44c1-4435-bbfa-094a4b11d962",
  "disbursement_key": "bd0ea133-ff47-4a21-a3e6-24186e5e2fc1",
  "contract_number": "4069550961/QIT",
  "requester_key": "1040ce22-aeac-4728-82da-d1f22c33873f",
  "insurance_policy_document_key": "9990ce22-aeac-4728-82da-d1f22c33873f",
  "insurance_date": "2024-09-11",
  "term_start_date": "2024-09-11",
  "term_end_date": "2025-09-11",
  "insurance_amount": 1600,
  "operation_amount": 6400,
  "customer": {
    "customer_key": "cd587fa8-3abd-4023-99ab-957df60933a5",
    "document_number": "08556878350",
    "name": "Wilker Oliveiraço",
    "birth_date": "1998-03-21",
    "gender": "male",
    "email": "urich.oliveira@yopmail.com",
    "phone": {
      "country_code": "55",
      "area_code": "11",
      "number": "966931427"
    },
    "address": {
      "postal_code": "56821686",
      "state": "CE",
      "city": "Ceará",
      "neighborhood": "Marmiteiros",
      "street": "Conjunto João Gabriel da Mata",
      "number": "95",
      "complement": ""
    }
  },
  "covers": [
    {
      "cover_amount": 300,
      "cover_type": "permanent_disability",
      "cover_prize_amount": 572.82
    },
    {
      "cover_amount": 300,
      "cover_type": "accidental_death",
      "cover_prize_amount": 572.82
    },
    {
      "cover_amount": 300,
      "cover_type": "unemployment",
      "cover_prize_amount": 572.82
    }
  ],
  "policy_number": "1098200000008",
  "prize_number": "3907",
  "insurance_premium_net_amount": 1145.63,
  "iof_amount": 4.37
}
```

## Anexos
---

### Motivo de rejeição {#rejection_reason}

| Enumerador                                | Descrição                                             |
|------------------------------------------ |-------------------------------------------------------|
| **insurance_rejected**                    | seguro rejeitado                                      |

### Motivo de cancelamento {#cancel-insurance}

| Enumerador                                | Descrição                                              |
|------------------------------------------ |-------------------------------------------------------|
| reversed_operation                        | Operação revertida e seguro cancelados|
| cover_limit_amount_exceeded               | Somente o seguro foi cancelado. Algum limite de cobertura foi ultrapassado e não foi possível a emissão do seguro|
| insurance_premium_cancel                  | Somente o seguro foi cancelado. Cancelamento do tomador direto com a seguradora|

---

# Manual Consignado Privado - Tombamento do Legado

URL: /documentation/manual_consignado_privado/manual_tombamento_legado

:::caution API em desenvolvimento 
A API ainda está em fase de desenvolvimento, sendo assim, este manual esta sujeito a alterações.
:::

## 1 - Pré requisitos

Para tombar um contrato para o novo modelo do empréstimo consignado, é necessário que este tenha sido informado previamente e esteja no status "active", caso ainda haja algum contrato legado que não foi informado ou que não esteja no status correto, favor informar o time de operações com urgência, no [manual de contratos legados](./manual_contratos_legados) está a documentação para consultar os contratos informados.

Além disso, por determinação da DATAPREV, é necessário que o tomador ainda esteja empregado no mesmo vínculo do contrato informado. É possível consultar os vínculos ativos do tomador sem enviar um termo de autorização utilizando a chamada abaixo (será validado se existe um contrato legado ativo para o mesmo CPF):

## 2 - Consulta de vínculos empregatícios para tombamento:
A consulta de vínculos empregatícios é uma operação assíncrona. Ao enviar a requisição, a QI Tech processará a consulta em background e retornará o resultado através de um webhook quando finalizada.
O webhook será enviado para a URL configurada no seu ambiente.

Para consultar os vínculos ativos de um tomador que possui um contrato legado ativo, deverá ser feita uma consulta de vínculos utilizando o mesmo endpoint do fluxo de emissão adicionando um campo extra na raiz do payload da requisição.

**POST**
/private_payroll/employment_relationships_inquiry

Testar no Playground

### Request

**Request Body**

```json
{
    "document_number" : "<CPF FUNCIONÁRIO>",
    "inquiry_type" : "legacy"
}
```

### Response

STATUS
**202** Accepted

**Response Body**

```json
{
    "employment_relationships_inquiry_key": "<UUID>",
    "employment_relationships_inquiry_status": "pending_inquiry"
}
```

### Webhooks

WEBHOOK TYPE
laas.private_payroll.employment_relationships_inquiry_status_change

Retorno da consulta dos vínculos empregatícios:

STATUS
completed

**Webhook Body**

```json
{
    "key": "<Employment Relationships Inquiry Key>",
    "status": "completed",
    "webhook_type": "laas.private_payroll.employment_relationships_inquiry_status_change",
    "event_datetime": "2025-03-24T15:28:31Z",
    "data": {
        "inquiry_type": "legacy",
        "employment_relationships": [
            {
                "eligible": true,
                "document_number": "47812365409",
                "registration_number": "99999999999-A", 
                "employer_document_type": "cnpj",
                "employer_document_number": "12345678000173"
            },
            {
                "eligible": true,
                "document_number": "47812365409",
                "registration_number": "11111111111-B",
                "employer_document_type": "cnpj",
                "employer_document_number": "43211234000189"
            }
        ]
    }
}
```

STATUS
failed

**Webhook Body**

```json
{
    "key": "<Employment Relationships Inquiry Key>",
    "status": "failure",
    "webhook_type": "laas.private_payroll.employment_relationships_inquiry_status_change",
    "event_datetime": "2025-03-24T15:28:31Z"
}
```

## 3 - Chamada de tombamento do contrato legado:

:::warning Atenção!
Os campos de nome do tomador, documento do empregador e número de registro do vínculo devem ser preenchidos com os dados retornados na consulta de vínculos, caso contrário, a DATAPREV retornará erro na averbação.
:::
:::warning Atenção!
Caso tenha sido cobrada uma tarifa de cadastro (TAC) na operação original, o valor desta tarifa será calculado pela diferença entre o valor de emissão e a somatória do valor desembolsado com o valor de iof.
:::
TOMBAMENTO

### Request

**POST**
/credit_operation/external

Testar no Playground

**Contrato legado emitido externamente**

```json title='Request Body'
{
    "requester_identifier_key": "d6a931e8-1655-479e-97a8-df8b426f49a0",
    "borrower": {
        "name": "Nome devedor",
        "role_type": "issuer",
        "person_type": "natural",
        "individual_document_number": "14471835092",
    },
    "collaterals": [
        {
            "percentage": 1,
            "collateral_type": "private_payroll",
            "collateral_data": {
                "legacy_contract_number": "109230148",
                "operation_category": "legacy_contract_rollover",
                "employer_document_number": "07940839000159",
                "registration_number": "99999999999-A",
            },
        }
    ],
    "control_number": "CTRL-2025-0001",
    "purchaser_document_number": "32402502000135",
    "disbursement_bank_account": {
        "name": "NOME DEVEDOR",
        "bank_code": "001",
        "account_digit": "0",
        "branch_number": "2874",
        "account_number": "000057555",
        "document_number": "14471835092",
        "transfer_method": "pix",
        "percentage_receivable": 100,
    },
    "financial": {
        "interest_type": "pre_price_days",
        "disbursement_date": "2024-11-07",
        "fine_configuration": {
            "monthly_rate": 0.0186,
            "interest_base": "calendar_days_365",
            "contract_fine_rate": 0,
        },
        "monthly_interest_rate": 0.04,
        "credit_operation_type": "ccb",
        "principal_grace_period": 0,
        "interest_grace_period": 0,
        "total_iof": 50,
        "amount": 700,
        "disbursed_amount": 500,
        "monthly_cet": 0.015,
        "annual_cet": 31.81,
        "installment_face_value": 82.57,
        "installments" : [
            {
                "due_date":"2025-04-07",
                "control_number": "CTRL-2025-1001",
                "status": "paid"
            },
            {
                "due_date":"2025-05-07",
                "control_number": "CTRL-2025-1002",
                "status": "paid"
            },
            {
                "due_date":"2025-06-07",
                "control_number": "CTRL-2025-1003",
                "status": "opened"
            },
            {
                "due_date":"2025-08-07",
                "due_balance": 11.20,
                "control_number": "CTRL-2025-1004",
                "status": "paid_partial"  
            },
            {
                "due_date":"2025-09-07",
                "control_number": "CTRL-2025-1005",
                "status": "opened"
            },
            {
                "due_date":"2025-10-07",
                "control_number": "CTRL-2025-1006",
                "status": "opened"
            },
            {
                "due_date":"2025-11-07",
                "due_balance": 70.09,
                "control_number": "CTRL-2025-1007",
                "status": "paid_partial"
            }
        ]
    },
}
```

:::warning Atenção!
Todas as parcelas devem ser informadas, mesmo que já tenham sido pagas. Os status das parcelas devem ser informados conforme a descrição abaixo.
:::

#### Descrição dos Status

| Status | Descrição |
|--------|-----------|
| `opened` | Parcela em aberto |
| `paid_partial` | Parcela parcialmente paga |
| `paid` | Parcela totalmente paga |
| `overdue` | Parcela vencida e não paga |

### Response

STATUS
**201** Created

**Response Body**

```json
{
    "issue_date": "2024-11-07",
    "issuer_name": "Nome Devedor",
    "disbursement_start_date": "2024-11-07",
    "credit_operation_status_enumerator": "opened",
    "original_total_iof": null,
    "origin_key": "<UUID>",
    "contract_number": "LEG0123456789",
    "first_due_date": "2025-04-07",
    "disbursement_end_date": "2024-11-07",
    "requester_identifier_key": "<KEY>",
    "credit_operation_key": "<UUID>",
    "operation_type_enumerator": "external_operation",
    "issue_amount": 700,
    "requester_key": "<UUID>",
    "disbursement_date": "2024-11-07",
    "total_iof": 50,
    "external_contract_fees": [
        {
        "tax_amount": 50,
        "cofins_amount": 0,
        "fee_type": {
            "enumerator": "tac"
        },
        "fee_amount": 150,
        "csll_amount": 0,
        "amount_released": 135,
        "irrf_amount": 0,
        "billing_type": {
            "enumerator": "rebate"
        },
        "amount": 150,
        "amount_type": {
            "enumerator": "absolute"
        },
        "pis_amount": 0,
        "rebate_account": null,
        "description": null,
        "created_at": "2024-11-07T01:51:41",
        "net_fee_amount": 135
        }
    ],
    "installments": [
        {
            "principal_amortization_amount": 23.2268766,
            "qr_code_url": null,
            "installment_type": "principal",
            "due_interest": 0,
            "paid_amount": 82.57,
            "original_total_amount": 82.57,
            "tax_amount": 0.12951306,
            "due_principal": 10,
            "bank_slip_key": null,
            "total_accrual_amount": null,
            "total_amount": 82.57,
            "calendar_days": 145,
            "installment_key": "f9d8ecae-a314-460a-987c-3a48afc283ef",
            "has_interest": true,
            "due_date": "2025-04-07",
            "original_principal_amortization_amount": 23.2268766,
            "pre_fixed_amount": 82.57,
            "digitable_line": null,
            "accrual_reference_date": null,
            "qr_code_key": null,
            "advanced_paid_amount": 0,
            "post_fixed_amount": 0,
            "original_pre_fixed_amount": 82.57,
            "original_due_principal": 635,
            "business_due_date": "2025-04-22",
            "workdays": 145,
            "installment_status": "paid",
            "total_paid_amount": 82.57,
            "renegotiation_proposal_key": null,
            "fine_amount": null
        },
        {
            "principal_amortization_amount": 23.2268766,
            "qr_code_url": null,
            "installment_type": "principal",
            "due_interest": 0,
            "paid_amount": 82.57,
            "original_total_amount": 82.57,
            "tax_amount": 0.12951306,
            "due_principal": 10,
            "bank_slip_key": null,
            "total_accrual_amount": null,
            "total_amount": 82.57,
            "calendar_days": 145,
            "installment_key": "f9d8ecae-a314-460a-987c-3a48afc283ef",
            "has_interest": true,
            "due_date": "2025-05-07",
            "original_principal_amortization_amount": 23.2268766,
            "pre_fixed_amount": 82.57,
            "digitable_line": null,
            "accrual_reference_date": null,
            "qr_code_key": null,
            "advanced_paid_amount": 0,
            "post_fixed_amount": 0,
            "original_pre_fixed_amount": 82.57,
            "original_due_principal": 635,
            "business_due_date": "2025-04-22",
            "workdays": 145,
            "installment_status": "paid",
            "total_paid_amount": 82.57,
            "renegotiation_proposal_key": null,
            "fine_amount": null
        },
        ...
    ]
}
```

---

# Manual Consignado Privado - Portabilidade: Consultas Prévias

URL: /documentation/manual_consignado_privado/portabilidade/consultas

:::danger Consulta obrigatória antes da proposta
Antes de digitar uma proposta de portabilidade, é **obrigatório** realizar uma **consulta de dados válida do trabalhador**. Sem uma consulta de dados concluída com sucesso, o pedido de averbação da portabilidade (e do refinanciamento) **não é criado**. Sempre faça a consulta antes de digitar a proposta.
:::

São duas consultas, ambas assinadas com o **Termo de Autorização**:

1. **Consulta dos vínculos empregatícios** — `POST /private_payroll/employment_relationships_inquiry`
2. **Consulta de dados do trabalhador (saldo e margem consignável)** — `POST /private_payroll/balance_inquiry`

:::info Estas consultas são documentadas em detalhe
As duas consultas, o Termo de Autorização e os enumeradores de status (`employment_relationships_inquiry_status`, `balance_inquiry_status`) estão detalhados em **[Consultas do Trabalhador](/documentation/manual_consignado_privado/manual_consultas_trabalhador)**. Esta página mostra como elas se encaixam na jornada de portabilidade.

A consulta de dados do trabalhador valida a elegibilidade, a margem consignável e os dados da conta de pagamento antes da digitação da proposta.
:::

## Onde a consulta entra no fluxo

```
1.  POST /private_payroll/employment_relationships_inquiry   (vínculos + Termo de Autorização)
2.  POST /private_payroll/balance_inquiry                    (margem consignável + Termo de Autorização)
3.  POST /v2/credit_transfer/proposal                        (digitação da proposta de portabilidade)
```

A **consulta de dados do trabalhador (passo 2) deve ter sido concluída com sucesso antes do passo 3**. A proposta de portabilidade só deve ser digitada após a consulta retornar com sucesso — é ela que valida a margem consignável e habilita a averbação da operação.

---

# Manual Consignado Privado - Portabilidade: Consultas e Operações Pós-Proposta

URL: /documentation/manual_consignado_privado/portabilidade/consultas_pos_proposta

## Consulta de Lista de Participantes do CTC

ENDPOINT /v2/credit_transfer/participants
MÉTODO GET

Testar no Playground

**Resposta**

**response.json**

```json
[
    {
        "name": "<NOME DO BANCO>",
        "bank_code": "<CÓDIGO DO BANCO>",
        "ispb": "<BASE DO CNPJ DO BANCO>"
    }
]
```

## Recuperar resposta da última request

O last response é uma forma de mapear, de forma simples e objetiva, a resposta da comunicação entre a QI e o empregador, possibilitando saber quando essa requisição foi feita e qual o retorno obtido (através de um enumerador). Os enumeradores estão divididos em duas formas: "errors" e "success".

Cada enumerador tem uma descrição detalhada e o código de referência. Podemos conferir abaixo, com mais detalhes, como serão apresentados os dados do last response.

### Casos de sucesso

#### Requisição
ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /CREDIT-OPERATION-TYPE/collateral
MÉTODO GET

#### Path Params credit-operation-type
| Enumerador               					| Descrição                  		|
|-------------------------------------------|--------------------------------|
| refinancing_credit_operation  			| Operação de refinanciamento    |
| portability_credit_operation     			| Operação de portabilidade      |

#### Resposta

Response Body

```json
{
    "collateral_data": {
        "employer_document_number": "<CNPJ DO EMPREGADOR>",
        "registration_number": "<MATRÍCULA DO TRABALHADOR>",
        "last_response": {
            "success": [
                {
                    "enumerator": "succesfully_included",
                    "reservation_method": "portability"
                }
            ]
        },
        "last_response_event_datetime": "2023-05-22T19:13:02Z",
        "status": "reserved"
    },
    "collateral_constituted": true,
    "collateral_type": "private_payroll"
}
```

### Detalhamento de campos no retorno da request
| Campo                     | Descrição                           | Valores                          |
|---------------------------|-------------------------------------|----------------------------------|
| enumerator                | Retorno mapeado do código de resposta  | [Consultas do Trabalhador](/documentation/manual_consignado_privado/manual_consultas_trabalhador)|
| reservation_method        | Método de averbação da reserva      | portability, new_credit, refinancing|

### Casos de erro

#### Requisição
ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /CREDIT-OPERATION-TYPE/collateral
MÉTODO GET

#### Resposta

Response Body

```json
{
    "collateral_constituted": false,
    "collateral_type": "type",
    "updated_at": "2023-05-24 19:13:02",
    "collateral_data": {
        "employer_document_number": "<CNPJ DO EMPREGADOR>",
        "registration_number": "<MATRÍCULA DO TRABALHADOR>",
        "status": "pending_reservation",
        "last_response": {
            "errors": [
                {
                    "enumerator": "consignable_margin_exceeded",
                    "reservation_method": "portability"
                },
                {
                    "enumerator": "consignable_margin_exceeded",
                    "reservation_method": "new_credit"
                }
            ]
        },
        "last_response_event_datetime": "2023-05-22T19:13:02Z"
    }
}
```

### Detalhamento de campos no webhook de falha
| Campo                     | Descrição                           | Valores                          |
|---------------------------|-------------------------------------|----------------------------------|
| enumerator                | Retorno mapeado do código de resposta  | [Consultas do Trabalhador](/documentation/manual_consignado_privado/manual_consultas_trabalhador) |
| reservation_method        | Método de averbação da reserva      | portability, new_credit, refinancing|

## Webhook de resposta da última tentativa de averbação

Caso a operação não tenha sucesso na averbação na folha do empregador, a mesma ficará em retentativa e será enviado o seguinte webhook, detalhando o motivo da não averbação, o horário desta tentativa e o método de averbação utilizado. Trata-se da reserva de margem (averbação) na folha de pagamento de funcionários de empresas privadas.

**Operação de portabilidade**

WEBHOOK_TYPE credit_transfer.proposal.collateral

```json
{
    "webhook_type": "credit_transfer.proposal.collateral",
    "proposal_key": "<PROPOSAL-KEY>",
    "event_datetime": "2022-11-24T15:42:12",
    "data": {
        "credit_operation_type": "portability",
        "credit_operation_key": "<CREDIT-OPERATION-KEY>",
        "collateral_type": "private_payroll",
        "collateral_constituted": false,
        "collateral_data": {
            "status": "pending_reservation",
            "last_response": {
                "errors": [
                    {
                        "enumerator": "consignable_margin_exceeded"
                    }
                ]
            },
            "last_response_event_datetime": "2023-05-22T19:13:02Z",
            "reservation_method": "new_credit"
        }
    }
}
```

**Operação de refinanciamento**

:::info Mesmo webhook da averbação de portabilidade
A averbação do Refinanciamento (Troco) usa o **mesmo** `webhook_type` `credit_transfer.proposal.collateral` usado para a averbação da Portabilidade — a diferença está apenas no campo `data.credit_operation_type`, que aqui vem como `"refinancing"`.
:::

WEBHOOK_TYPE credit_transfer.proposal.collateral

```json
{
    "webhook_type": "credit_transfer.proposal.collateral",
    "proposal_key": "<PROPOSAL-KEY>",
    "event_datetime": "2022-11-24T15:42:12",
    "data": {
        "credit_operation_type": "refinancing",
        "credit_operation_key": "<CREDIT-OPERATION-KEY>",
        "collateral_type": "private_payroll",
        "collateral_constituted": false,
        "collateral_data": {
            "status": "pending_reservation",
            "last_response": {
                "errors": [
                    {
                        "enumerator": "consignable_margin_exceeded"
                    }
                ]
            },
            "last_response_event_datetime": "2023-05-22T19:13:02Z",
            "reservation_method": "refinancing"
        }
    }
}
```

### Detalhamento de campos no webhook de falha
| Campo                     | Descrição                           | Valores                          |
|---------------------------|-------------------------------------|----------------------------------|
| enumerator                | Retorno mapeado do código de resposta  | [Consultas do Trabalhador](/documentation/manual_consignado_privado/manual_consultas_trabalhador) |
| reservation_method        | Método de averbação da reserva      | portability, new_credit, refinancing|

## Dados do contrato de origem

Não existe um endpoint separado para "consultar" os dados do contrato de origem (banco credor original) depois da digitação — esses dados chegam automaticamente ao parceiro no webhook de **[`accepted`](/documentation/manual_consignado_privado/portabilidade/maquina_de_status#accepted)**, dentro de `data.original_contract`, assim que a instituição credora original informa o saldo devedor real (`final_due_balance`). O objeto traz, entre outros campos, o número e o ISPB do contrato de origem, a taxa e o CET do contrato original, o número de parcelas e a data da última parcela.

:::info Consulta prévia (antes da proposta)
A elegibilidade do trabalhador para a portabilidade — vínculo empregatício, contratos existentes na folha do empregador — é apurada nas **[Consultas Prévias](/documentation/manual_consignado_privado/portabilidade/consultas)**, obrigatórias antes da digitação da proposta.
:::

## Diminuir o valor das parcelas

Este endpoint permite a redução do valor das parcelas de um contrato de portabilidade de crédito. Esta funcionalidade é especialmente útil em casos onde a margem consignável é excedida devido ao banco de origem desaverbar uma quantia menor do que a esperada.

ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /portability_credit_operation
MÉTODO PUT

**Requisição**

**request.json**

```json
{
    "installment_face_value": 382.18
}
```

**Resposta sucesso - HTTP 200**

**response.json**

```json
{
    "credit_operation_key": "7aa77bca-c724-4c1a-bfae-9b1b7bd81ab2",
    "contract_number": "0000000007/WO",
    "document_key": "045a8f35-6170-4112-8d83-29a753d0c78e",
    "document_url": "http://teste.com",
    "signed_url": "signed_url_test",
    "credit_operation_status": "waiting_signature",
    "fine_configuration": {
        "contract_fine_rate": 0.02,
        "interest_base": "calendar_days",
        "monthly_rate": 0.01
    },
    "disbursement_accounts": [
        {
            "account_digit": "3",
            "account_branch": "0001",
            "account_number": "94134",
            "ispb": "32402502",
            "name": "Wilker Teste",
            "document_number": "37197645832"
        }
    ],
    "disbursement_options": [
        {
            "prefixed_interest_rate": {
                "annual_rate": 3.0,
                "daily_rate": 0.00385824,
                "interest_base": "calendar_days",
                "monthly_rate": 0.12246205
            },
            "total_iof": 7.03,
            "external_contract_fee_amount": 0.0,
            "external_contract_fees": [],
            "contract_fee_amount": 0.0,
            "number_of_installments": 3,
            "contract_fees": [],
            "disbursed_issue_amount": 1000.0,
            "issue_amount": 1007.03,
            "disbursement_date": "2022-08-24",
            "cet": 12.6,
            "annual_cet": 315.3944,
            "installments": [
                {
                    "business_due_date": "2022-08-30",
                    "calendar_days": 5,
                    "due_date": "2022-08-29",
                    "due_principal": 1007.03,
                    "installment_number": 1,
                    "pre_fixed_amount": 84.43554587915118,
                    "principal_amortization_amount": 297.73445412084885,
                    "total_amount": 382.17,
                    "workdays": 3
                },
                {
                    "business_due_date": "2022-09-30",
                    "calendar_days": 31,
                    "due_date": "2022-09-29",
                    "due_principal": 709.2955458791512,
                    "installment_number": 2,
                    "pre_fixed_amount": 47.97894031795043,
                    "principal_amortization_amount": 334.19105968204957,
                    "total_amount": 382.17,
                    "workdays": 22
                },
                {
                    "business_due_date": "2022-11-01",
                    "calendar_days": 32,
                    "due_date": "2022-10-31",
                    "due_principal": 375.1044861971016,
                    "installment_number": 3,
                    "pre_fixed_amount": 7.055513802898396,
                    "principal_amortization_amount": 375.1044861971016,
                    "total_amount": 382.16,
                    "workdays": 21
                }
            ],
            "final_disbursement_amount": 997.87
        }
    ],
    "final_disbursement_amount": 997.87,
    "collateral_is_constituted": false
}
```

## Incluir Fee na operação de portabilidade rebatido pela QI ao parceiro

Para inclusão do fee, é necessário que a operação esteja averbada, desembolsada e que não esteja cedida.

ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /portability_credit_operation/rebate
MÉTODO POST

**Requisição**

**request.json**

```json
{
    "amount": 20,
    "rebate_bank_account": {
        "name": "Teste Ltda",
        "document_number": "18533555000164",
        "account_digit": "0",
        "account_number": "4290001",
        "branch_number": "0001",
        "bank_code": "329"
    },
    "amount_type": "percentage",
    "fee_type": "spread"
}
```

**Resposta**

**response.json**

```json
{}
```

## Recibo do pagamento de portabilidade (STR00047)

Após o pagamento da portabilidade, é possível gerar o recibo da transação.

ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /receipt_str0047
MÉTODO POST

**Requisição**

**request.json**

```json
{}
```

**Resposta**

**response.json**

```json
{
    "proposal_key": "CHAVE DA PROPOSTA",
    "receipt_url": "URL DO RECIBO",
    "receipt_document_key": "CHAVE DO RECIBO"
}
```

---

# Manual Consignado Privado - Portabilidade: Enumeradores

URL: /documentation/manual_consignado_privado/portabilidade/enumeradores

## Mapeamento de enumeradores

Esta página reúne os enumeradores utilizados ao longo do fluxo de Portabilidade de Consignado Privado: `retention_reason`, `proposal_status`, `credit_operation_status` e `politically_exposed`.

Os enumeradores relacionados à situação do trabalhador, à margem consignável e a bloqueios na folha de pagamento são apurados nas consultas prévias à proposta e estão detalhados no [Manual de Consultas do Trabalhador](/documentation/manual_consignado_privado/manual_consultas_trabalhador), que documenta `employment_relationships_inquiry_status` e `balance_inquiry_status`.

### Enumeradores Retention Reason {#retention_reason_enumerator}
| Enumerador                               | Descrição                                              |
|------------------------------------------|--------------------------------------------------------|
| **issuer_retention**                     | Retenção do Cliente                                    |
| **different_from_original**              | Condições da proposta divergentes do contrato original |
| **issuer_lawsuit**                       | Cliente com ação judicial                              |
| **insurance_in_progress**                | Indenização de seguro em andamento                     |
| **collateral_in_execution**              | Garantia em Execução                                   |
| **contract_not_found**                   | Contrato não encontrado                                |
| **invalid_contract_type**                | Tipo de contrato inválido                              |
| **portability_in_progress**              | Portabilidade em andamento                             |
| **assigned_contract**                    | Contrato cedido                                        |
| **issuer_document_number_invalid**       | CPF não é do contrato                                  |
| **unrelated_issuer_document_number**     | CPF informado não é o do titular                       |
| **assigned_without_co_obligation**       | Contrato cedido sem coobrigação                        |
| **fgts_in_use**                          | FGTS AMORTIZAR em uso                                  |
| **fgts_funding**                         | FGTS funding                                           |
| **portability_not_requested**            | O cliente não solicitou a portabilidade                |
| **wrong_original_financial_institution** | IF Credora Original Incorreta                          |

### Enumeradores proposal_status {#proposal_status_enumerator}

Os estados da Proposta de Portabilidade refletem as etapas do processo de portabilidade de crédito dentro do CTC (Central de Transferência de Crédito) da Núclea, desde a digitação até a liquidação.

| Enumerador                        | Descrição                                                                                                       |
|-----------------------------------|-----------------------------------------------------------------------------------------------------------------|
| pending_submission                | Proposta criada e aguardando envio                                                                              |
| pending_response                  | Proposta digitada, recebida com sucesso pela QI e enviada para o CTC                                       |
| pending_acceptance                | Proposta enviada/aceita pelo CTC, aguardando resposta de saldo devedor pela instituição credora original  |
| accepted                          | Instituição credora original retornou o saldo devedor e não reteve o crédito                                     |
| retained                          | Crédito retido pela instituição credora original                                                                |
| settlement_sent                   | Liquidação enviada à instituição credora original                                                               |
| pending_settlement_confirmation   | Aguardando confirmação da liquidação                                                                            |
| paid                              | Proposta liquidada/paga                                                                                          |
| rejected                          | Digitação da proposta rejeitada pelo CTC                                                                   |
| canceled                          | Proposta cancelada                                                                                              |

### Enumeradores credit_operation_status {#credit_operation_status_enumerator}
| Enumerador               					| Descrição                  	 		|
|-------------------------------------------|---------------------------------------|
| waiting_signature  						| Operação aguardando assinatura 		|
| signed     								| Operação assinada			     		|
| issued  									| Operação emitida			     		|
| disbursed									| Operação desembolsada		     		|
| settled     								| Operação liquidada	         		|
| canceled     								| Operação cancelada		     		|
| canceled_permanently  					| Operação cancelada permanentemente    |

### Tabela de tipos de politicamente exposto {#politically_exposed_enumerator}

| Enumerador | Descrição                                           |
|------------|-----------------------------------------------------|
| 0          | Pessoa Não Exposta Politicamente                    |
| 1          | Pessoa Exposta Politicamente - Nível 1              |

---

## Situação do trabalhador, margem e bloqueios

A elegibilidade do trabalhador, a margem consignável e eventuais bloqueios da folha de pagamento são apurados nas consultas prévias à digitação da proposta. Os enumeradores correspondentes estão detalhados no [Manual de Consultas do Trabalhador](/documentation/manual_consignado_privado/manual_consultas_trabalhador).

### Retorno da averbação

A averbação da operação ocorre junto ao empregador/folha de pagamento de funcionários de empresas privadas. As críticas associadas decorrem da consulta de vínculo empregatício e de saldo do trabalhador.

### Situação e status do vínculo empregatício

Refletem a situação do vínculo empregatício do trabalhador junto ao empregador/folha de pagamento de funcionários de empresas privadas. Consulte os enumeradores de status de consulta no [Manual de Consultas do Trabalhador](/documentation/manual_consignado_privado/manual_consultas_trabalhador).

### Bloqueios do vínculo empregatício

Bloqueios são tratados no contexto do vínculo empregatício do trabalhador. Consulte o detalhamento no [Manual de Consultas do Trabalhador](/documentation/manual_consignado_privado/manual_consultas_trabalhador) e no [Manual de Vínculos Empregatícios](/documentation/manual_consignado_privado/vinculos_empregaticios/visao_geral).

---

# Manual Consignado Privado - Portabilidade: Formalização

URL: /documentation/manual_consignado_privado/portabilidade/formalizacao

A formalização — coleta de documentos e assinatura dos contratos gerados na digitação da proposta — é realizada **integralmente pelo QI Sign**.

:::info Formalização via QI Sign
A QI Tech coleta os documentos do tomador e captura a assinatura no fluxo do QI Sign. O parceiro **não envia documentos** — nem no payload da proposta, nem por qualquer outro endpoint — e **não submete evidências de assinatura**.
:::

O andamento da assinatura de cada operação (portabilidade e refinanciamento) é refletido no `credit_operation_status` (`waiting_signature → issued → ...`) e pode ser acompanhado em [Acompanhamento da Operação](/documentation/manual_consignado_privado/portabilidade/maquina_de_status).

---

# Manual Consignado Privado - Portabilidade: Acompanhamento da Operação

URL: /documentation/manual_consignado_privado/portabilidade/maquina_de_status

## Status da Proposta de Portabilidade

Os estados da Proposta de Portabilidade refletem as etapas envolvidas no processo de portabilidade de crédito dentro do CTC (Central de Transferência de Crédito) da Núclea.
Segue abaixo a descrição do fluxo e do significado de cada status envolvido em uma Proposta de Portabilidade, desde sua digitação até sua liquidação.

### pending_response

Status da proposta após realização da digitação. Neste status a proposta foi recebida com sucesso pela QI e enviada para o CTC.

#### rejected

Caso a digitação da proposta seja rejeitada pelo CTC, será enviado um webhook com o motivo da rejeição:

**Webhook**

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS rejected

**webhook.json**

```json
{
    "webhook_type": "credit_transfer.proposal",
    "proposal_key": "<PROPOSAL-KEY>",
    "proposal_status": "rejected",
    "event_datetime": "2022-11-24T15:42:12",
    "data": {
        "error": {
            "code": "ECTC0023",
            "reason": "Contrato com portabilidade em andamento"
        }
    }
}
```

#### rejected reasons

Caso a digitação da proposta seja rejeitada pelo CTC, será enviado um webhook com o motivo da rejeição:

| reason                             | description                                                                                                                   | external_code |
|------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|---------------|
| portability_in_progress            | Contrato com portabilidade em andamento                                                                                       | ECTC0023      |
| portability_finished               | Portabilidade já finalizada para o contrato informado                                                                         | ECTC0028      |
| portability_in_expiration_progress | Portabilidade não permitida. Contrato com portabilidade em situação de "Decurso de prazo" por não efetivação da portabilidade | ECTC0085      |
| unexpected_error                   | Erro inesperado                                                                                                               | ECTC9999      |
| portability_payment_rejected       | Pagamento de portabilidade rejeitado.                                                                                         |               |
| divergent_due_balance              | Saldo devedor final deve ser menor que saldo devedor devolvido pela Núclea.                                                      |               |

### pending_acceptance

Status da Proposta após envio/aceite pelo CTC. A Proposta, neste momento, está aguardando resposta de saldo devedor pelo banco credor original. Neste momento é enviado um webhook com o número da Portabilidade no CTC:

**Webhook**

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS pending_acceptance

**webhook.json**

```json
{
    "webhook_type": "credit_transfer.proposal",
    "proposal_key": "<PROPOSAL-KEY>",
    "proposal_status": "pending_acceptance",
    "event_datetime": "2022-11-24T15:42:12",
    "data": {
        "portability_number": "202211230000246536429",
        "inclusion_date": "2022-11-24",
        "due_balance_expected_return_date": "2022-12-01"
    }
}
```

:::info
O **“portability_number“** é o Número da Portabilidade dentro do CTC, e é o número utilizado pela instituição proponente e instituição credora original para localizar a Proposta de Portabilidade.
:::

Assim que o banco credor original responder à solicitação de portabilidade, será enviado um webhook com a resposta do valor do saldo devedor no caso da não retenção, e com a informação de “retido”, no caso da retenção:

#### accepted

Status da Proposta quando o banco credor original retorna o saldo devedor e não retem o crédito. Será enviado um webhook com a informação do saldo devedor.
O banco credor original tem até 5 d.u. após a recepção da Proposta de Portabilidade, para envio da resposta com a informação do saldo devedor da operação.

**Webhook**

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS accepted

**webhook.json**

```json
{
    "webhook_type": "credit_transfer.proposal",
    "proposal_key": "<PROPOSAL-KEY>",
    "proposal_status": "accepted",
    "event_datetime": "2022-11-24T15:42:12",
    "data": {
        "final_due_balance": 1000,
        "portability_number": "202211230000246536429",
        "original_contract": {
            "origin_contract_number": "5584745",
            "origin_ispb_number": "60746948",
            "origin_document_number": "90406718261",
            "origin_operation_type": "0202",
            "installment_face_value": 1000,
            "total_iof": 1,
            "first_due_date": "2021-05-31",
            "last_due_date": "2022-05-31",
            "interest": 1,
            "cet": 1,
            "installment_number": 12,
            "amortization": 1,
            "final_due_balance": 1000,
            "final_due_date": "2021-08-31",
            "contract_date": "2021-04-31"
        }
    }
}
```

Com a informação do saldo devedor retornado pela instituição credora original, o parceiro tomará a decisão se seguir ou não com a Portabilidade.

:::info
Horário limite para envio do saldo devedor pela instituição credora original é às 10:00.
:::

:::info Saldo devedor real diferente do estimado na proposta
O `final_due_balance` informado pela instituição credora original é validado contra o saldo devedor estimado enviado na proposta (`origin_contract.last_due_balance`): se o saldo real superar o estimado em mais de **15%**, a proposta é automaticamente rejeitada com o motivo `divergent_due_balance` (ver [rejected reasons](#rejected-reasons)). Dentro dessa tolerância, a proposta segue para `accepted` normalmente — mas as condições financeiras só são recalculadas com base no saldo real no momento do aceite (`PATCH .../accepted_by_requester` abaixo), não antes.
:::

Após o recebimento do saldo devedor, caso o Parceiro decida seguir com a Proposta Portabilidade, ele deve realizar a seguinte chamada:

ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY
MÉTODO PATCH

Testar no Playground

**Requisição**

**request.json**

```json
{
    "status": "accepted_by_requester"
}
```

:::caution Atenção
Para propostas que envolvam troco após o refinanciamento, o troco recalculado de acordo com as novas condições do contrato (após o retorno do saldo devedor) também precisa respeitar o piso mínimo — que é **escalonado pelo número de parcelas em aberto do contrato de origem** (5% para menos de 56 parcelas, 3% para 56 a 71, 2% para 72 ou mais; ver [Simulação](/documentation/manual_consignado_privado/portabilidade/simulacao)) em relação à diferença entre a soma de todas as parcelas do refinanciamento e a soma de todas as parcelas da portabilidade. Caso contrário, a requisição receberá o seguinte erro:

STATUS 400

**Response Body**

```json
{
    "code": "CT000118",
    "title": "Bad Request",
    "description": "The final disbursement amount is less than 5% of the sum of refinancing installment minus the sum of portability installment. The minimum final disbursement amount allowed is 500.00. Calculated final disbursement amount: 400.00.",
    "translation": "O valor do troco é menor que 5% da soma do valor das parcelas do refinanciamento menos o valor soma das parcelas da portabilidade. O valor mínimo do troco permitido é de 500.00. Valor calculado do troco: 400.00."
}
```
:::

:::info Recálculo das condições com base no saldo devedor real
Essa chamada (`accepted_by_requester`) recalcula a simulação da Portabilidade — e do Refinanciamento/Troco, se houver — usando o saldo devedor **real** (`final_due_balance`), e retorna as condições recalculadas na própria resposta (além dos webhooks de status). Duas garantias protegem o tomador nesse recálculo:
- O valor da nova parcela não pode ultrapassar o valor da parcela do contrato de origem.
- O valor do Troco recalculado não pode ser reduzido em mais de **10%** em relação ao Troco calculado na digitação/simulação original.
:::

O Parceiro pode adicionar dados de novo valor de parcela ou nova taxa nessa chamada, caso queira alterá-los:

ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY
MÉTODO PATCH

**Requisição**

**request.json**

```json
{
    "status": "accepted_by_requester",
    "financial": {
        "installment_face_value": 100
    }
}
```

ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY
MÉTODO PATCH

**Requisição**

**request.json**

```json
{
    "status": "accepted_by_requester",
    "financial": {
        "monthly_interest_rate": 0.01
    }
}
```

:::info Campos adicionais opcionais
Além dos campos `status` e `financial`, o endpoint de aceite da proposta também aceita os seguintes campos opcionais:
- **`borrower.document_identification_type`** (string ou null): Tipo do documento de identificação
- **`borrower.document_identification_number`** (string, máx. 16 caracteres): Número do documento de identificação
- **`borrower.gender`** (string ou null): Gênero do tomador. Valores aceitos: `"male"`, `"female"` ou `null`
:::

:::danger Atenção!
Caso o valor da parcela seja maior que valor total disponível (valor da parcela do contrato de origem + margem consignável total disponível),
será retornado o seguinte erro:
```json
{
    "code": "SSC000059",
    "title": "Reservation amount greater than available total balance",
    "description": "The installment face value: 54.4 is greater than the available total balance (origin installment face value + available total balance):30.4. Available total balance: -20.0.",
    "translation": "O valor da parcela: 54.4 é maior que o valor total disponível (valor da parcela do contrato de origem + margem total disponível) : 30.4. Margem total diponível: -20.0."
}
```
Ao receber esta crítica, é possível que uma nova chamada seja feita, alterando o valor da parcela para que ela se ajuste ao valor total disponível.

Se o ajuste no valor da parcela não for feito até o horário limite para aceite do saldo devedor, será necessária uma nova digitação de proposta.
:::

Caso o Parceiro decida por não prosseguir com a Proposta de Portabilidade, ele deve, **obrigatoriamente** realizar a seguinte chamada para informar a desistência da Portabilidade:

ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY
MÉTODO DELETE

Testar no Playground

Após o envio do cancelamento da Proposta de Portabilidade ao CTC, será enviado um webhook de Proposta Cancelada:

**Webhook**

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS canceled

**webhook.json**

```json
{
    "webhook_type": "credit_transfer.proposal",
    "proposal_status": "canceled",
    "proposal_key": "<PROPOSAL-KEY>",
    "event_datetime": "2022-11-24T15:42:12"
}
```

:::info
O comando de pagamento do saldo devedor (envio da liquidação) deve ser enviado até às 16:00.
Não é possível retomar uma Proposta com status “canceled”. Caso a Proposta esteja com este status, será necessária a realização de uma nova digitação.
:::

#### retained

Status da Proposta quando o banco credor original retem o crédito, será enviado o webhook com a informação de retenção. O banco credor original do crédito tem até 5 d.u. após a recepção da Proposta de Portabilidade, para envio da resposta de retenção do crédito — o mesmo prazo aplicável ao envio do saldo devedor (ver [`accepted`](#accepted)).

**Webhook**

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS retained

**webhook.json**

```json
{
    "webhook_type": "credit_transfer.proposal",
    "proposal_key": "<PROPOSAL-KEY>",
    "proposal_status": "retained",
    "event_datetime": "2022-11-24T15:42:12",
    "data": {
        "retained_reason": {
            "reason": "issuer_retention",
            "description": "Retenção do Cliente"
        }
    }
}
```

### Detalhamento de campos no webhook de proposal
| Campo                     | Descrição                           | Valores                          |
|---------------------------|-------------------------------------|----------------------------------|
| reason                    | lista dos motivos de retenção de uma Proposta  | [Enumeradores](/documentation/manual_consignado_privado/portabilidade/enumeradores#retention_reason_enumerator) |

### accepted_by_requester

Após aprovada pelo parceiro, a Proposta segue o fluxo interno da QI para liquidação.

### settlement_sent

Após conclusão do fluxo interno da QI para liquidação da Proposta de Portabilidade o recurso para pagamento do saldo devedor é enviado ao credor original disparando o seguinte webhook para o Parceiro:

**Webhook**

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS settlement_sent

**webhook.json**

```json
{
    "webhook_type": "credit_transfer.proposal",
    "proposal_key": "<PROPOSAL KEY>",
    "proposal_status": "settlement_sent",
    "event_datetime": "2022-11-24T15:42:12",
    "data": {
        "receipt": {
            "amount": 1000,
            "timestamp": "2022-09-14 11:55:31",
            "description": "237 0001 1000093 1000093-3 59588111000103 - BCO BRADESCO S.A.",
            "ted_receipt_document_key": "a34e84a2-1628-4f23-8c11-2b2f4656ced1",
            "ted_receipt_url": "https://qitech.com.br/",
            "transaction_key": "ed3e84a2-1628-4f23-8c11-2b2f4656cedf",
            "origin": {
                "account_key": "ed3e84a2-1628-4f23-8c11-2b2f4656cedf",
                "bank_code": "329",
                "branch": "0001",
                "branch_digit": null,
                "account_number": "1000361",
                "account_digit": "3",
                "type": "checking_account",
                "name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
                "document": "32402502000135"
            },
            "destination": {
                "bank_code": "237",
                "branch": "0001",
                "branch_digit": null,
                "account_number": "1000093",
                "account_digit": "3",
                "type": "checking_account",
                "name": "BCO BRADESCO S.A.",
                "document": "59588111000103",
                "purpose": "Saída Liquidação de Portabilidade"
            }
        }
    }
}
```

Neste momento será iniciada averbação da Operação de Portabilidade na folha do empregador. O processo de averbação acontecerá em paralelo aos itens seguintes (itens 7.5., 7.5.1. e 7.5.2.)

### pending_settlement_confirmation

Após a confirmação do envio dos recursos para pagamento do saldo devedor, é aguardada a confirmação da quitação do contrato por parte da Instituição Credora Original. Nesta etapa o Parceiro receberá o seguinte webhook:

**Webhook**

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS pending_settlement_confirmation

**webhook.json**

```json
{
    "webhook_type": "credit_transfer.proposal",
    "proposal_key": "<PROPOSAL-KEY>",
    "proposal_status": "pending_settlement_confirmation",
    "event_datetime": "2022-11-24T15:42:12"
}
```

:::info
A confirmação da quitação do contrato é encaminhada pela Instituição Credora Original ao CTC e posteriormente encaminhado pelo CTC à QI.

O SLA para confirmação da quitação da Portabilidade é de **2 d.u.** contados a partir do envio dos recursos para pagamento do saldo devedor do contrato original.
:::

#### paid

Assim que a QI receber do CTC a confirmação da quitação do Contrato Original, a Proposta constará como paga e a Portabilidade estará finalizada.

**Webhook**

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS paid

**webhook.json**

```json
{
    "webhook_type": "credit_transfer.proposal",
    "proposal_key": "<PROPOSAL-KEY>",
    "proposal_status": "paid",
    "event_datetime": "2022-11-24T15:42:12"
}
```

Nesta etapa, caso a averbação da Operação de Portabilidade já esteja concluída, a Operação de Refinanciamento (Troco), poderá ser iniciada (fluxo descrito no item 7).

A notificação sobre a averbação da Operação de Portabilidade será enviada através do seguinte webhook:

**Webhook**

- WEBHOOK_TYPE credit_transfer.proposal.collateral

**webhook.json**

```json
{
    "webhook_type": "credit_transfer.proposal.collateral",
    "proposal_key": "<PROPOSAL-KEY>",
    "event_datetime": "2022-11-24T15:42:12",
    "data": {
        "credit_operation_type": "portability",
        "credit_operation_key": "<CREDIT-OPERATION-KEY>",
        "collateral_type": "private_payroll",
        "collateral_constituted": true,
        "collateral_data": {
            "reservation_method": "portability"
        }
    }
}
```

data.collateral_data.reservation_method: [portability, new_credit ]

#### rejected

Caso o banco credor original rejeite a quitação do contrato, o recurso enviado para quitação do saldo devedor do contrato original será devolvido, e a proposta será finalizada. O parceiro receberá o webhook de **“rejected”**.

**Webhook**

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS rejected

**webhook.json**

```json
{
    "webhook_type": "credit_transfer.proposal",
    "proposal_key": "<PROPOSAL-KEY>",
    "proposal_status": "rejected",
    "event_datetime": "2022-11-24T15:42:12",
    "data": {
        "error": {
            "code": "QCTC0001",
            "reason": "Pagamento de portabilidade rejeitado."
        }
    }
}
```

Caso nesta etapa a Operação de Portabilidada já esteja averbada na folha do empregador, será realizada a desaverbação da margem.

:::info
Não é possível retomar uma Proposta com status “**rejected**”. É sempre necessário realizar uma nova digitação.
:::

---

## Status da Operação de Refinanciamento (Troco)

No momento em que a Operação de Portabilidade é paga, o Parceiro pode optar por seguir com a Operação de Refinanciamento (Troco) ou não.

#### Enumeradores credit_operation_status
| Enumerador               					| Descrição                  	 		|
|-------------------------------------------|---------------------------------------|
| waiting_signature  						| Operação aguardando assinatura 		|
| signed     								| Operação assinada			     		|
| issued  									| Operação emitida			     		|
| disbursed									| Operação desembolsada		     		|
| settled     								| Operação liquidada	         		|
| canceled     								| Operação cancelada		     		|
| canceled_permanently  					| Operação cancelada permanentemente    |

Para prosseguir com o Refinanciamento (Troco), o Parceiro deve realizar a seguinte chamada passando os campos 'Financial' e 'Disbursement Bank Accounts':

*Adicionalmente, pode-se passar o campo 'purchaser_document_number' para alterar o cessionário da operação.

ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /refinancing_credit_operation/acceptance
MÉTODO POST

Testar no Playground

**Requisição**

**request.json**

```json
{
    "financial": {
        "installment_face_value": 379.87,
        "monthly_interest_rate": 0.0166,
        "number_of_installments": 84,
        "limit_days_to_disburse": 7,
        "disbursement_date": "2024-07-02",
        "rebates": [
            {
                "rebate_bank_account": {
                    "bank_code": "329",
                    "account_digit": "9",
                    "document_number": "18533555000164",
                    "name": "Teste Ltda",
                    "account_number": "4290002",
                    "branch_number": "0001"
                },
                "amount_type": "percentage",
                "fee_type": "spread",
                "amount": 9.5
            },
            {
                "amount": 20,
                "rebate_bank_account": {
                    "name": "Teste Ltda",
                    "document_number": "18533555000164",
                    "account_digit": "0",
                    "account_number": "4290001",
                    "branch_number": "0001",
                    "bank_code": "329"
                },
                "amount_type": "percentage",
                "fee_type": "insurance_premium"
            }
        ]
    },
    "disbursement_bank_accounts": [
        {
            "document_number": "92093764000197",
            "branch_number": "0001",
            "name": "TESTE LTDA",
            "percentage_receivable": 100,
            "account_number": "120012",
            "account_digit": "3",
            "bank_code": "329"
        }
    ],
    "purchaser_document_number": "28534595027164"
}
```

**Resposta**

**response.json**

```json
{
    "credit_operation_key": "<CREDIT-OPERATION-KEY>",
    "contract_number": "00000002",
    "document_key": "<DOCUMENT-KEY da CCB de Refinanciamento>",
    "document_url": "<URL da CCB de Refinanciamento>",
    "credit_operation_status": "issued",
    "fine_configuration": {
        "contract_fine_rate": 0.02,
        "interest_base": "calendar_days",
        "monthly_rate": 0.01
    },
    "disbursement_options": [
        {
            "installments": [
                {
                    "additional_costs": [],
                    "bank_slip_key": null,
                    "business_due_date": "2021-08-09",
                    "calendar_days": 53,
                    "digitable_line": null,
                    "due_date": "2021-08-08",
                    "due_interest": 0,
                    "due_principal": 997.87,
                    "fine_amount": null,
                    "has_interest": true,
                    "installment_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036",
                    "installment_number": 1,
                    "installment_status": "created",
                    "installment_type": "principal",
                    "paid_amount": 0,
                    "paid_at": null,
                    "post_fixed_amount": 0,
                    "pre_fixed_amount": 54.84865004983954,
                    "principal_amortization_amount": 306.98134995016045,
                    "total_amount": 361.83,
                    "workdays": 37
                },
                {
                    "additional_costs": [],
                    "bank_slip_key": null,
                    "business_due_date": "2021-09-08",
                    "calendar_days": 31,
                    "digitable_line": null,
                    "due_date": "2021-09-08",
                    "due_interest": 0,
                    "due_principal": 690.8886500498395,
                    "fine_amount": null,
                    "has_interest": true,
                    "installment_key": "e8406cdb-844c-4e6d-9620-3635fab9d8d1",
                    "installment_number": 2,
                    "installment_status": "created",
                    "installment_type": "principal",
                    "paid_amount": 0,
                    "paid_at": null,
                    "post_fixed_amount": 0,
                    "pre_fixed_amount": 21.964874249804833,
                    "principal_amortization_amount": 339.86512575019515,
                    "tax_amount": 0,
                    "total_amount": 361.83,
                    "workdays": 22
                }
            ],
            "prefixed_interest_rate": {
                "annual_rate": 0.44556431,
                "daily_rate": 0.00564312,
                "monthly_rate": 0.0556431,
                "interest_base": "calendar_days_365"
            },
            "iof_amount": 50,
            "external_contract_fee_amount": 0,
            "external_contract_fees": [],
            "contract_fee_amount": 0,
            "contract_fees": [],
            "number_of_installments": 2,
            "disbursed_issue_amount": 997.87,
            "final_disbursement_amount": 100,
            "issue_amount": 1147.87,
            "disbursement_date": "2021-05-31",
            "cet": 1.212,
            "annual_cet": 32.122
        }
    ],
    "disbursement_bank_account": {
        "account_digit": "1",
        "account_number": "00001",
        "ispb": "00000000",
        "branch_number": "0001"
    }
}
```

Caso o Parceiro opte por não prosseguir com a Operação de Refinanciamento (Troco), ele deve realizar a seguinte chamada:

ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /refinancing_credit_operation
MÉTODO DELETE

### Averbação do Refinanciamento (Troco)

Assim que o Parceiro optar por prosseguir com a Operação de Refinanciamento, a rotina para averbação da margem consignável terá início. Assim que a averbação da margem consignável na folha do empregador for concluída o parceiro recebera o seguinte webhook:

**Webhook**

- WEBHOOK_TYPE credit_transfer.proposal.collateral

**webhook.json**

```json
{
    "webhook_type": "credit_transfer.proposal.collateral",
    "proposal_key": "<PROPOSAL-KEY>",
    "event_datetime": "2022-11-24T15:42:12",
    "data": {
        "credit_operation_type": "refinancing",
        "credit_operation_key": "<CREDIT-OPERATION-KEY>",
        "collateral_type": "private_payroll",
        "collateral_constituted": true
    }
}
```

### Desembolso do Refinanciamento (Troco)

Assim que a averbação da margem consignável na folha do empregador for concluída a operação estará pronta para desembolso.
No desembolso da Operação de Refinanciamento, a Operação de Portabilidade será quitada e caso exista valor desembolsado remanescente (**7.1.1. “disbursement_options.final_disbursement_amount”**), este valor será liberado para o cliente (Troco) na conta para desembolso da Operação (**“disbursement_bank_account“**).
A liberação do troco para o cliente pode ser realizada via PIX ou TED, em qualquer horário do dia (obedecendo horário comercial de 7:00 às 17:00 em dias úteis, no caso da TED).

Caso o desembolso do troco para o cliente seja bem sucedido, será enviado um webhook com os dados da comprovação do desembolso:

**Webhook**

- WEBHOOK_TYPE credit_transfer.proposal.credit_operation

**webhook.json**

```json
{
    "webhook_type": "credit_transfer.proposal.credit_operation",
    "proposal_key": "<PROPOSAL-KEY>",
    "event_datetime": "2022-11-24T15:42:12",
    "data": {
        "credit_operation_status": "disbursed",
        "credit_operation_type": "refinancing",
        "credit_operation_key": "<CREDIT-OPERATION-KEY>",
        "ted_receipt_list": [
            {
                "fee": 0,
                "url": "https://qitech.com.br/",
                "amount": 500,
                "origin": {
                    "name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
                    "type": "payment_account",
                    "branch": "0001",
                    "document": "32402502000135",
                    "bank_code": "329",
                    "account_key": "871059bd-4014-41ad-82b4-28275ff0e67b",
                    "branch_digit": null,
                    "account_digit": "5",
                    "account_branch": "0001",
                    "account_number": "00002"
                },
                "timestamp": "2022-09-28T13:00:47",
                "description": "DESCRIPTION",
                "destination": {
                    "name": "Elaine Isadora da Cruz",
                    "type": "checking_account",
                    "bank_code": "033",
                    "branch": "0001",
                    "purpose": "Crédito PIX em Conta",
                    "document_number": "90406718261",
                    "bank_ispb": "90400888",
                    "branch_digit": null,
                    "account_digit": "1",
                    "account_number": "00001"
                },
                "end_to_end_id": null,
                "transaction_key": "871059bd-4014-41ad-82b4-28275ff0e67b",
                "origin_transaction_key": null
            }
        ]
    }
}
```

Caso ocorra falha no desembolso, o parceiro receberá o seguinte webhook:

#### Falha no desembolso via PIX

**Webhook**

- WEBHOOK_TYPE credit_transfer.proposal.credit_operation

**webhook.json**

```json
{
    "webhook_type": "credit_transfer.proposal.credit_operation",
    "proposal_key": "60fbbfe2-eb52-4825-9ed5-f169a58b9999",
    "event_datetime": "2022-11-24T15:42:12",
    "data": {
        "credit_operation_status": "canceled",
        "credit_operation_type": "refinancing",
        "credit_operation_key": "1a1a44df-29b6-431c-89af-53657d906333",
        "pix_refusal": {
            "reason_enumerator": "invalid_document_number",
            "reason": "CPF/CNPJ do usuário recebedor não é compatível com o titular da conta de destino."
        },
        "cancel_reason": "pix_refusal"
    }
}
```

#### Falha no desembolso via TED

**Webhook**

- WEBHOOK_TYPE credit_transfer.proposal.credit_operation

**webhook.json**

```json
{
    "webhook": {
        "data": {
            "cancel_reason": "Agência ou Conta Destinatária do Crédito Inválida",
            "credit_operation_key": "1a1a44df-29b6-431c-89af-53657d906333",
            "credit_operation_type": "refinancing",
            "credit_operation_status": "canceled",
            "cancel_reason_enumerator": "agencia_conta_invalida"
        },
        "proposal_key": "60fbbfe2-eb52-4825-9ed5-f169a58b9999",
        "webhook_type": "credit_transfer.proposal.credit_operation",
        "event_datetime": "2023-12-22T10:15:25"
    }
}
```

No caso de falha no desembolso da Operação, o desembolso pode ser retentato alterando-se os dados bancários:

ENDPOINT /v2/credit_transfer/proposal/ PROPOSAL-KEY /refinancing_credit_operation
MÉTODO PATCH

Testar no Playground

**Requisição**

**request.json**

```json
{
    "disbursement_date": "2022-11-04",
    "disbursement_bank_account": {
        "account_branch": "1232",
        "account_digit": "4",
        "account_number": "412412412",
        "account_type": "checking_account",
        "document_number": "14950479032",
        "ispb": "17298092",
        "name": "Maria da Silva"
    }
}
```

---

# Manual Consignado Privado - Portabilidade: Mocks e Sandbox

URL: /documentation/manual_consignado_privado/portabilidade/mocks_sandbox

:::danger Aviso Importante!
Não utilize dados pessoais reais (CPF, CNPJ etc.) em ambiente sandbox.
:::

## Simulação de Cenários

### Portabilidade

#### 1. Solicitação do Saldo Devedor

Após a assinatura da operação de portabilidade, caso o cliente tenha configuração de envio manual, a proposta será 
criada com status "pending_submission" e somente após a chamada da rota a seguir, a solicitação do saldo devedor será feita. 
Caso a configuração seja de envio automático a proposta será criada com status "pending_response", ou seja, já está aguardando o retorno do saldo
e não é necessário chamar esta rota.

**Requisição**

ENDPOINT /v2/credit_transfer/proposal/PROPOSAL-KEY
MÉTODO PATCH

**request.json**

```json
{
    "status": "pending_response"
}
```

#### 2. Aprovação pelo CTC

A proposta deve estar em status "pending_response".

**Requisição**

ENDPOINT /mock/credit_transfer/ctc
MÉTODO POST

**request.json**

```json
{
    "proposal_key": "CHAVE DA PROPOSTA",
    "event_type": "proposal_creation_accepted"
}
```

#### 3. Rejeição pelo CTC

A proposta deve estar em status "pending_response".

**Requisição**

ENDPOINT /mock/credit_transfer/ctc
MÉTODO POST

**request.json**

```json
{
    "proposal_key": "CHAVE DA PROPOSTA",
    "event_type": "proposal_creation_refused"
}
```

#### 4. Envio de saldo devedor pelo banco de origem

A chamada de aprovação pelo CTC (**2**) deve ser enviada antes. A proposta deve estar em status "pending_acceptance". 
Após esta rota, receberá o webhook informando o saldo devedor atual da dívida e caso queira seguir com a operação deve chamar
a rota apresentada no fluxo de aceite da proposta.

**Requisição**

ENDPOINT /mock/credit_transfer/ctc
MÉTODO POST

**request.json**

```json
{
    "proposal_key": "CHAVE DA PROPOSTA",
    "event_type": "proposal_approval",
    "due_balance": 9000, // Opcional, se não informado será enviado o valor usado na criação da proposta
    "installment_face_value": 300, // Opcional, se não informado será enviado o valor usado na criação da proposta
    "installment_number": 40, // Opcional, se não informado será enviado o valor usado na criação da proposta
    "opened_installment_number": 35, // Opcional, se não informado será enviado igual ao installment_number
    "overdue_installment_number": 5 // Opcional, se não informado será enviado 0
}
```

#### 5. Retenção pelo banco de origem

A chamada de aprovação pelo CTC (**2**) deve ser enviada antes. A proposta deve estar em status "pending_acceptance"

**Requisição**

ENDPOINT /mock/credit_transfer/ctc
MÉTODO POST

**request.json**

```json
{
    "proposal_key": "CHAVE DA PROPOSTA",
    "event_type": "proposal_retention"
}
```

#### 6. Devolução do pagamento pelo banco de origem

Só pode ser enviado depois que a proposta for aceita e a operação de portabilidade desembolsada. Proposta deve estar em 
status "settlement_sent", "pending_settlement_confirmation" ou "paid".

**Requisição**

ENDPOINT /mock/credit_transfer/str
MÉTODO POST

**request.json**

```json
{
    "proposal_key": "CHAVE DA PROPOSTA",
    "event_type": "payment_rejected"
}
```

#### 7. Confirmação de pagamento pelo CTC

Proposta deve ter sido aceita e a operação de portabilidade desembolsada. Status deve ser "settlement_sent".

**Requisição**

ENDPOINT /mock/credit_transfer/ctc
MÉTODO POST

**request.json**

```json
{
    "proposal_key": "CHAVE DA PROPOSTA",
    "event_type": "settlement_confirmation"
}
```

#### 8. Confirmação de pagamento pelo banco de origem

Deve ser chamado após a confirmação de pagamento pelo CTC (**7**). Proposta deve estar em status 
"pending_settlement_confirmation".

**Requisição**

ENDPOINT /mock/credit_transfer/ctc
MÉTODO POST

**request.json**

```json
{
    "proposal_key": "CHAVE DA PROPOSTA",
    "event_type": "payment_confirmation"
}
```

#### 9. Averbação de garantia

Proposta deve estar em status "pending_settlement_confirmation" ou "paid", após **7** ou **8**.

**Requisição**

ENDPOINT /mock/credit_transfer/collateral
MÉTODO POST

**request.json**

```json
{
    "proposal_key": "CHAVE DA PROPOSTA",
    "credit_operation_type": "portability",
    "collateral_constituted": true
}
```

### Refinanciamento

#### 10. Averbação de garantia

Proposta deve estar em status "paid" ou "pending_settlement_confirmation" com garantia de portabilidade averbada e o 
refinanciamento deve ter sido aceito.

**Requisição**

ENDPOINT /mock/credit_transfer/collateral
MÉTODO POST

**request.json**

```json
{
    "proposal_key": "CHAVE DA PROPOSTA",
    "credit_operation_type": "refinancing",
    "collateral_constituted": true
}
```

#### 11. Falha na averbação de garantia

Proposta deve estar em status "paid" ou "pending_settlement_confirmation" com garantia de portabilidade averbada e o 
refinanciamento deve ter sido aceito.

**Requisição**

ENDPOINT /mock/credit_transfer/collateral
MÉTODO POST

**request.json**

```json
{
    "proposal_key": "CHAVE DA PROPOSTA",
    "credit_operation_type": "refinancing",
    "collateral_constituted": false
}
```

#### 12. Falha no desembolso

Operação de refinanciamento deve ter sido desembolsada.

**Requisição**

ENDPOINT /mock/credit_transfer/disbursement
MÉTODO POST

**request.json**

```json
{
    "proposal_key": "CHAVE DA PROPOSTA",
    "event_type": "disbursement_failed"
}
```

---

# Manual Consignado Privado - Portabilidade: Digitação da Proposta

URL: /documentation/manual_consignado_privado/portabilidade/proposta

A digitação da proposta cria a operação de **portabilidade** e, opcionalmente, a operação de **refinanciamento** (Troco) na mesma requisição, por meio do endpoint `POST /v2/credit_transfer/proposal`.

ENDPOINT /v2/credit_transfer/proposal
MÉTODO POST

Testar no Playground

:::caution Atenção
Para que os pedidos de averbação, tanto da portabilidade quanto do refinanciamento, sejam criados com sucesso, é preciso que uma **consulta de dados válida do trabalhador** tenha sido feita **previamente**. Siga os passos de [Consultas Prévias](/documentation/manual_consignado_privado/portabilidade/consultas).
:::

## Estrutura da requisição

A requisição é composta por alguns campos no nível raiz e pelos objetos da operação. A estrutura geral é a seguinte — cada objeto é detalhado nas seções abaixo:

```json title='Estrutura geral'
{
    "proposal_type": "private_company",
    "purchaser_document_number": "32402502000135",
    "borrower": ,
    "related_parties": [ /* representante legal, quando houver */ ],
    "collaterals": [ /* garantia: folha de pagamento */ ],
    "portability_credit_operation": ,
    "refinancing_credit_operation": ,
    "origin_contract": ,
    "additional_data": {}
}
```

| Campo (raiz) | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `proposal_type` | string | ✅ | `"private_company"` para Consignado Privado. |
| `purchaser_document_number` | string | ✅ | CNPJ do comprador da operação. |
| `additional_data` | object | — | Dados complementares da operação. |

:::info Portabilidade sem refinanciamento
Para uma **portabilidade pura**, sem liberação de Troco, omita o objeto `refinancing_credit_operation`, mantendo `portability_credit_operation` e `origin_contract`.
:::

### `borrower` — dados do tomador

Dados cadastrais do tomador do crédito. Ver objeto compartilhado [Borrower](/documentation/objetos_compartilhados/borrower). Os documentos do tomador **não são enviados na proposta** — a formalização é feita via QI Sign. Ver [Formalização](/documentation/manual_consignado_privado/portabilidade/formalizacao).

```json
{
    "person_type": "natural",
    "name": "Marilene da Silva",
    "mother_name": "Maria Mariane",
    "birth_date": "1990-05-06",
    "profession": "Desenvolvedora",
    "nationality": "Brasileira",
    "marital_status": "single",
    "is_pep": false,
    "individual_document_number": "20676928013",
    "document_identification_number": "381803326",  // obrigatório
    "document_identification_type": "rg",  // obrigatório — rg | cnh | cin
    "document_identification_date": "2019-01-28",
    "email": "marilene@email.com",
    "phone": {
        "country_code": "055",
        "area_code": "11",
        "number": "912828135"
    },
    "address": {
        "street": "Passagem Mariana",
        "state": "PA",
        "city": "Ananindeua",
        "neighborhood": "Águas Lindas",
        "number": "660",
        "postal_code": "67118003",
        "complement": "complemento"
    }
}
```

:::danger Documento de identificação obrigatório (a partir de 03/08/2026)
A Núclea passará a exigir o documento de identificação do tomador no registro da portabilidade a partir de **06/08/2026**. Por isso, a partir de **segunda-feira, 03/08/2026**, `borrower.document_identification_type` e `borrower.document_identification_number` passam a ser **obrigatórios** na digitação da proposta — propostas sem esses campos retornam erro.

Quando `document_identification_type` for `cin`, o `document_identification_number` **pode** ser igual ao `individual_document_number` (CPF), já que a CIN usa o número do CPF. Para os demais tipos (`rg`, `cnh`), enviar o CPF em `document_identification_number` retorna erro.
:::

| Campo (`borrower`) | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `person_type` | string | ✅ | `natural`. |
| `individual_document_number` | string | ✅ | CPF do tomador (11 dígitos, sem pontuação). |
| `document_identification_type` | string | ✅ | Tipo do documento de identificação. Valores: `rg`, `cnh`, `cin`. |
| `document_identification_number` | string (máx. 16) | ✅ | Número do documento informado em `document_identification_type`. Igual ao CPF **somente** quando o tipo for `cin`. |
| `document_identification_date` | string | — | Data de emissão do documento (`YYYY-MM-DD`). |

### `related_parties` — representante legal (opcional)

Envie esta lista **apenas** quando a operação tem representante legal. Cada item deve conter os dados cadastrais do representante e o campo `role_type` com o valor `issuer_legal_representative`.

```json
[
    {
        "name": "Nome Representante Legal",
        "email": "email@email.com.br",
        "birth_date": "2000-12-12",
        "is_pep": false,
        "mother_name": "maria",
        "phone": {
            "number": "991294043",
            "area_code": "11",
            "country_code": "055"
        },
        "address": {
            "street": "Avenida das Castanheiras",
            "state": "SP",
            "city": "Brasília",
            "neighborhood": "bairro",
            "number": "12",
            "postal_code": "71900100",
            "complement": ""
        },
        "role_type": "issuer_legal_representative",
        "person_type": "natural",
        "individual_document_number": "45102538004",
        "document_identification_type": "rg",
        "document_identification_number": "123456789"
    }
]
```

### `collaterals` — garantia (folha de pagamento)

A garantia é a folha de pagamento de funcionários de empresas privadas. O `collateral_data` carrega o CNPJ do empregador e a matrícula do trabalhador.

```json
[
    {
        "collateral_type": "private_payroll",
        "collateral_data": {
            "employer_document_number": "<CNPJ DO EMPREGADOR>",
            "registration_number": "<MATRÍCULA DO TRABALHADOR>"
        }
    }
]
```

### `portability_credit_operation` — operação portada

Operação que assume (porta) o contrato de origem. Informe sempre `number_of_installments` e **uma** entre `monthly_interest_rate` ou `installment_face_value`.

```json
{
    "financial": {
        "monthly_interest_rate": 0.0132,
        "number_of_installments": 10
    },
    "contract_number": "300523588PF"
}
```

### `refinancing_credit_operation` — Troco (opcional)

Operação que quita a portabilidade e libera o Troco na conta do trabalhador. Como o refinanciamento **não tem data de desembolso fixa**, a mudança na data de desembolso altera os valores da operação — por isso é necessário fixar **a taxa** (`monthly_interest_rate`) **ou** o **valor liberado** ao cliente (`disbursed_amount`).

A única diferença entre as duas formas está no objeto `financial`; `disbursement_bank_account` (conta de destino do Troco) e `contract_number` são iguais nos dois casos.

**Fixando a taxa**

```json
{
    "financial": {
        "monthly_interest_rate": 0.0132,
        "installment_face_value": 100,
        "number_of_installments": 10
    },
    "disbursement_bank_account": {
        "account_digit": "1",
        "account_number": "000059923",
        "ispb": "341",
        "bank_code": "341",
        "branch_number": "0155"
    },
    "contract_number": "200523588PK"
}
```

**Fixando o valor liberado**

```json
{
    "financial": {
        "disbursed_amount": 1000,
        "installment_face_value": 100,
        "number_of_installments": 10
    },
    "disbursement_bank_account": {
        "account_digit": "1",
        "account_number": "000059923",
        "ispb": "341",
        "bank_code": "341",
        "branch_number": "0155"
    },
    "contract_number": "200523588PK"
}
```

### `origin_contract` — contrato de origem

Identifica a dívida na instituição credora original.

```json
{
    "ispb": "60746948",
    "contract_number": "558472",
    "last_due_balance": 997.87
}
```

:::info ISPB do credor original
O `origin_contract.ispb` é o **ISPB** da instituição credora original (a base do CNPJ da instituição). A lista completa de ISPBs das instituições participantes da CTC pode ser obtida pelo endpoint de [consulta de participantes do CTC](/documentation/manual_consignado_privado/portabilidade/consultas_pos_proposta).
:::

### Campos das operações

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `collaterals[].collateral_type` | string | ✅ | `"private_payroll"`. |
| `collaterals[].collateral_data.employer_document_number` | string | ✅ | CNPJ do empregador. |
| `collaterals[].collateral_data.registration_number` | string | ✅ | Matrícula do trabalhador na folha do empregador. |
| `portability_credit_operation.financial.number_of_installments` | integer | ✅ | Número de parcelas. |
| `portability_credit_operation.financial.monthly_interest_rate` / `installment_face_value` | number | ✅ | Enviar **uma** das duas. |
| `portability_credit_operation.contract_number` | string | ✅ | Número do contrato de portabilidade gerado. |
| `refinancing_credit_operation.financial` | object | ⚠️ | Necessário quando há Troco. Fixar `monthly_interest_rate` (taxa) **ou** `disbursed_amount` (valor liberado). |
| `refinancing_credit_operation.disbursement_bank_account` | object | ⚠️ | Conta de destino do Troco. |
| `origin_contract.ispb` | string | ✅ | ISPB do credor original (base do CNPJ). |
| `origin_contract.contract_number` | string | ✅ | Número do contrato na instituição de origem. |
| `origin_contract.last_due_balance` | number | ✅ | Saldo devedor do contrato de origem. |

## Response

A criação da proposta retorna a `proposal_key` e, dentro de `borrower` e de cada item de `related_parties`, a `related_party_key` (identificador de cada parte na proposta).

**Response Body (resumido)**

```json
{
    "proposal_key": "<PROPOSAL-KEY>",
    "status": "pending_submission",
    "borrower": {
        "name": "Marilene da Silva",
        "individual_document_number": "20676928013",
        "role_type": "issuer",
        "related_party_key": "511d7186-3c17-4f35-8887-c4aefaf270be"
    },
    "collaterals": [
        {
            "collateral_type": "private_payroll",
            "collateral_data": {
                "employer_document_number": "<CNPJ DO EMPREGADOR>",
                "registration_number": "<MATRÍCULA DO TRABALHADOR>"
            }
        }
    ],
    "portability_credit_operation": {
        "contract_number": "300523588PF"
    },
    "refinancing_credit_operation": {
        "contract_number": "200523588PK"
    },
    "origin_contract": {
        "ispb": "60746948",
        "contract_number": "558472",
        "last_due_balance": 997.87
    }
}
```

:::info Recuperar dados de uma proposta
Em casos de timeout ou operação duplicada, é possível recuperar os dados de uma proposta enviando a `requester_control_key` no lugar da `proposal_key`. Ver [Consultas e Operações Pós-Proposta](/documentation/manual_consignado_privado/portabilidade/consultas_pos_proposta).
:::

## Correção de dados

Após a digitação, dados da proposta podem ser corrigidos antes do avanço do fluxo — para a operação de refinanciamento, para a portabilidade, ou para ambas. Dependendo do dado alterado, pode ser necessária uma **nova assinatura da CCB**. As transições e o endpoint de atualização (`PATCH /v2/credit_transfer/proposal/{PROPOSAL-KEY}`) estão detalhados em [Acompanhamento da Operação](/documentation/manual_consignado_privado/portabilidade/maquina_de_status).

---

# Manual Consignado Privado - Portabilidade: Simulação

URL: /documentation/manual_consignado_privado/portabilidade/simulacao

A simulação retorna as condições financeiras da operação — cronograma de parcelas, CET e o valor do Troco — **antes da digitação da proposta** e sem precisar coletar os dados cadastrais do cliente. Use-a para validar taxas, número de parcelas e o Troco com o trabalhador.

ENDPOINT /v2/credit_transfer/proposal_simulation
MÉTODO POST

Testar no Playground

:::caution Troco mínimo escalonado pelo número de parcelas em aberto
Em propostas com Troco, o valor do Troco precisa corresponder a um percentual mínimo da diferença entre a soma das parcelas do refinanciamento e a soma das parcelas da portabilidade. Esse percentual mínimo **diminui conforme o número de parcelas em aberto do contrato de origem** (`origin_contract`):

| Parcelas em aberto do contrato de origem | Troco mínimo |
|---|---|
| Menos de 56 | **5%** |
| De 56 a 71 | **3%** |
| 72 ou mais | **2%** |

Caso o Troco calculado fique abaixo do piso aplicável, a requisição retorna o erro **400**:

STATUS 400

**Response Body**

```json
{
    "code": "CT000118",
    "title": "Bad Request",
    "description": "The final disbursement amount is less than 5% of the sum of refinancing installment minus the sum of portability installment. The minimum final disbursement amount allowed is 500.00. Calculated final disbursement amount: 400.00.",
    "translation": "O valor do troco é menor que 5% da soma do valor das parcelas do refinanciamento menos o valor soma das parcelas da portabilidade. O valor mínimo do troco permitido é de 500.00. Valor calculado do troco: 400.00."
}
```
:::

## Portabilidade com Refinanciamento

Simula a portabilidade e o refinanciamento (Troco) na mesma requisição, retornando as condições das duas operações.

### Requisição

O corpo contém apenas os dados mínimos da simulação. Assim como na [Digitação da Proposta](/documentation/manual_consignado_privado/portabilidade/proposta), a diferença entre os dois modos está em como o refinanciamento é fixado — pela **taxa** (`monthly_interest_rate`) ou pelo **valor liberado** ao cliente (`disbursed_amount`):

**Fixando a taxa**

```json
{
    "borrower": {
        "person_type": "natural"
    },
    "collaterals": [
        {
            "collateral_type": "private_payroll"
        }
    ],
    "portability_credit_operation": {
        "financial": {
            "monthly_interest_rate": 0.0132,
            "number_of_installments": 10
        }
    },
    "refinancing_credit_operation": {
        "financial": {
            "days_to_accrual": 0,
            "monthly_interest_rate": 0.0132,
            "installment_face_value": 100,
            "number_of_installments": 10
        }
    },
    "origin_contract": {
        "last_due_balance": 997.87
    }
}
```

**Fixando o valor liberado**

```json
{
    "borrower": {
        "person_type": "natural"
    },
    "collaterals": [
        {
            "collateral_type": "private_payroll"
        }
    ],
    "portability_credit_operation": {
        "financial": {
            "installment_face_value": 100,
            "number_of_installments": 10
        }
    },
    "refinancing_credit_operation": {
        "financial": {
            "days_to_accrual": 0,
            "disbursed_amount": 1000,
            "installment_face_value": 100,
            "number_of_installments": 10
        }
    },
    "origin_contract": {
        "last_due_balance": 997.87
    }
}
```

### Resposta

A resposta retorna **6 campos** no nível raiz: três identificadores da proposta e três objetos com os detalhes do tomador e das operações.

```json title='Estrutura da resposta'
{
    "proposal_key": "...",                      /* chave única da proposta */
    "proposal_number": "...",                   /* número da proposta */
    "proposal_status": "pending_submission",    /* status atual da proposta */
    "borrower": ,
    "portability_credit_operation": ,
    "refinancing_credit_operation": 
}
```

| Campo | Tipo | Descrição |
|---|---|---|
| `proposal_key` | string | Chave única da proposta. |
| `proposal_number` | string | Número da proposta. |
| `proposal_status` | string | Status atual da proposta (ex.: `pending_submission`). |
| `borrower` | object | Dados do tomador, incluindo a `related_party_key` usada no envio de documentos. |
| `portability_credit_operation` | object | Condições da operação de portabilidade: `disbursement_options` com o cronograma de `installments`, as taxas (`cet`, `annual_cet`, `prefixed_interest_rate`) e o `issue_amount`. |
| `refinancing_credit_operation` | object | Condições do refinanciamento (Troco). O valor do Troco aparece em `final_disbursement_amount`. |

Exemplo completo da resposta:

**response.json**

```json
{
    "proposal_key": "28a925f6-570e-4724-9132-3bd42f267c4f",
    "proposal_number": "17032788499215403",
    "proposal_status": "pending_submission",
    "borrower": {
        "individual_document_number": "98765432100",
        "related_party_key": "fa55dca3-3147-45d2-bb8d-941f2d7191da",
        "role_type": "issuer"
    },
    "portability_credit_operation": {
        "credit_operation_key": "a66675e6-bdc2-4468-8420-2889d5cec0a8",
        "credit_operation_status": "waiting_signature",
        "disbursement_accounts": [],
        "disbursement_options": [
            {
                "annual_cet": 0.173044,
                "cet": 0.0134,
                "contract_fee_amount": 0.0,
                "contract_fees": [
                    {
                        "amount": 0.5,
                        "amount_type": "percentage",
                        "fee_amount": 0.0,
                        "fee_type": "tac"
                    }
                ],
                "disbursed_issue_amount": 997.87,
                "disbursement_date": "2023-12-22",
                "external_contract_fee_amount": 0.0,
                "external_contract_fees": [
                    {
                        "amount": 0.0,
                        "amount_released": 0,
                        "amount_type": "absolute",
                        "cofins_amount": 0,
                        "csll_amount": 0,
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "spread",
                        "irrf_amount": 0,
                        "net_fee_amount": 0.0,
                        "pis_amount": 0,
                        "tax_amount": 0.0
                    },
                    {
                        "amount": 0.0,
                        "amount_released": 0,
                        "amount_type": "absolute",
                        "cofins_amount": 0,
                        "csll_amount": 0,
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "tac",
                        "irrf_amount": 0,
                        "net_fee_amount": 0.0,
                        "pis_amount": 0,
                        "tax_amount": 0.0
                    },
                    {
                        "amount": 0.0,
                        "amount_released": 0,
                        "amount_type": "absolute",
                        "cofins_amount": 0,
                        "csll_amount": 0,
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "insurance_premium",
                        "irrf_amount": 0,
                        "net_fee_amount": 0.0,
                        "pis_amount": 0,
                        "tax_amount": 0.0
                    }
                ],
                "installments": [
                    {
                        "business_due_date": "2024-02-22",
                        "calendar_days": 62,
                        "due_date": "2024-02-22",
                        "due_principal": 997.87,
                        "installment_number": 1,
                        "pre_fixed_amount": 27.413791524708554,
                        "principal_amortization_amount": 81.34620847529145,
                        "total_amount": 108.76,
                        "workdays": 40
                    },
                    {
                        "business_due_date": "2024-03-22",
                        "calendar_days": 29,
                        "due_date": "2024-03-22",
                        "due_principal": 916.5237915247086,
                        "installment_number": 2,
                        "pre_fixed_amount": 11.692366920719124,
                        "principal_amortization_amount": 97.06763307928088,
                        "total_amount": 108.76,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2024-04-22",
                        "calendar_days": 31,
                        "due_date": "2024-04-22",
                        "due_principal": 819.4561584454277,
                        "installment_number": 3,
                        "pre_fixed_amount": 11.179911547915339,
                        "principal_amortization_amount": 97.58008845208467,
                        "total_amount": 108.76,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2024-05-22",
                        "calendar_days": 30,
                        "due_date": "2024-05-22",
                        "due_principal": 721.876069993343,
                        "installment_number": 4,
                        "pre_fixed_amount": 9.5288330736045,
                        "principal_amortization_amount": 99.2311669263955,
                        "total_amount": 108.76,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2024-06-24",
                        "calendar_days": 33,
                        "due_date": "2024-06-24",
                        "due_principal": 622.6449030669476,
                        "installment_number": 5,
                        "pre_fixed_amount": 9.046812945831448,
                        "principal_amortization_amount": 99.71318705416856,
                        "total_amount": 108.76,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2024-07-22",
                        "calendar_days": 28,
                        "due_date": "2024-07-22",
                        "due_principal": 522.9317160127789,
                        "installment_number": 6,
                        "pre_fixed_amount": 6.439743824282488,
                        "principal_amortization_amount": 102.32025617571752,
                        "total_amount": 108.76,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2024-08-22",
                        "calendar_days": 31,
                        "due_date": "2024-08-22",
                        "due_principal": 420.61145983706143,
                        "installment_number": 7,
                        "pre_fixed_amount": 5.738438681013405,
                        "principal_amortization_amount": 103.0215613189866,
                        "total_amount": 108.76,
                        "workdays": 23
                    },
                    {
                        "business_due_date": "2024-09-23",
                        "calendar_days": 32,
                        "due_date": "2024-09-23",
                        "due_principal": 317.58989851807485,
                        "installment_number": 8,
                        "pre_fixed_amount": 4.473657660291388,
                        "principal_amortization_amount": 104.28634233970861,
                        "total_amount": 108.76,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2024-10-22",
                        "calendar_days": 29,
                        "due_date": "2024-10-22",
                        "due_principal": 213.30355617836625,
                        "installment_number": 9,
                        "pre_fixed_amount": 2.721176981322744,
                        "principal_amortization_amount": 106.03882301867725,
                        "total_amount": 108.76,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2024-11-22",
                        "calendar_days": 31,
                        "due_date": "2024-11-22",
                        "due_principal": 107.26473315968899,
                        "installment_number": 10,
                        "pre_fixed_amount": 1.4934220715493307,
                        "principal_amortization_amount": 107.26657792845067,
                        "total_amount": 108.76,
                        "workdays": 22
                    }
                ],
                "issue_amount": 997.87,
                "number_of_installments": 10,
                "prefixed_interest_rate": {
                    "annual_rate": 0.17042118,
                    "daily_rate": 0.00043722,
                    "interest_base": "calendar_days",
                    "monthly_rate": 0.0132
                },
                "total_iof": 0.0
            }
        ],
        "final_disbursement_amount": 0.0
    },
    "refinancing_credit_operation": {
        "credit_operation_key": "aaf9abe0-2b8a-4688-8e09-413e1bd5285e",
        "credit_operation_status": "waiting_signature",
        "disbursement_accounts": [],
        "disbursement_options": [
            {
                "annual_cet": 0.172031,
                "cet": 0.0133,
                "contract_fee_amount": -0.4,
                "contract_fees": [
                    {
                        "amount": 0.5,
                        "amount_type": "percentage",
                        "fee_amount": -0.4,
                        "fee_type": "tac"
                    }
                ],
                "disbursed_issue_amount": 918.04,
                "disbursement_date": "2023-12-22",
                "external_contract_fee_amount": 0.0,
                "external_contract_fees": [
                    {
                        "amount": 0.0,
                        "amount_released": 0,
                        "amount_type": "absolute",
                        "cofins_amount": 0,
                        "csll_amount": 0,
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "spread",
                        "irrf_amount": 0,
                        "net_fee_amount": 0.0,
                        "pis_amount": 0,
                        "tax_amount": 0.0
                    },
                    {
                        "amount": 0.0,
                        "amount_released": 0,
                        "amount_type": "absolute",
                        "cofins_amount": 0,
                        "csll_amount": 0,
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "tac",
                        "irrf_amount": 0,
                        "net_fee_amount": 0.0,
                        "pis_amount": 0,
                        "tax_amount": 0.0
                    },
                    {
                        "amount": 0.0,
                        "amount_released": 0,
                        "amount_type": "absolute",
                        "cofins_amount": 0,
                        "csll_amount": 0,
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "insurance_premium",
                        "irrf_amount": 0,
                        "net_fee_amount": 0.0,
                        "pis_amount": 0,
                        "tax_amount": 0.0
                    }
                ],
                "installments": [
                    {
                        "business_due_date": "2024-02-22",
                        "calendar_days": 62,
                        "due_date": "2024-02-22",
                        "due_principal": 917.64,
                        "installment_number": 1,
                        "pre_fixed_amount": 25.2095730147,
                        "principal_amortization_amount": 74.7904269853,
                        "total_amount": 100.0,
                        "workdays": 40
                    },
                    {
                        "business_due_date": "2024-03-22",
                        "calendar_days": 29,
                        "due_date": "2024-03-22",
                        "due_principal": 842.8495730147,
                        "installment_number": 2,
                        "pre_fixed_amount": 10.7524369787,
                        "principal_amortization_amount": 89.2475630213,
                        "total_amount": 100.0,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2024-04-22",
                        "calendar_days": 31,
                        "due_date": "2024-04-22",
                        "due_principal": 753.6020099934,
                        "installment_number": 3,
                        "pre_fixed_amount": 10.2814172859,
                        "principal_amortization_amount": 89.7185827141,
                        "total_amount": 100.0,
                        "workdays": 20
                    },
                    {
                        "business_due_date": "2024-05-22",
                        "calendar_days": 30,
                        "due_date": "2024-05-22",
                        "due_principal": 663.8834272793,
                        "installment_number": 4,
                        "pre_fixed_amount": 8.7632941742,
                        "principal_amortization_amount": 91.2367058258,
                        "total_amount": 100.0,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2024-06-24",
                        "calendar_days": 31,
                        "due_date": "2024-06-22",
                        "due_principal": 572.6467214535,
                        "installment_number": 5,
                        "pre_fixed_amount": 7.8126464787,
                        "principal_amortization_amount": 92.1873535213,
                        "total_amount": 100.0,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2024-07-22",
                        "calendar_days": 30,
                        "due_date": "2024-07-22",
                        "due_principal": 480.4593679322,
                        "installment_number": 6,
                        "pre_fixed_amount": 6.3420966342,
                        "principal_amortization_amount": 93.6579033658,
                        "total_amount": 100.0,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2024-08-22",
                        "calendar_days": 31,
                        "due_date": "2024-08-22",
                        "due_principal": 386.8014645664,
                        "installment_number": 7,
                        "pre_fixed_amount": 5.2771618926,
                        "principal_amortization_amount": 94.7228381074,
                        "total_amount": 100.0,
                        "workdays": 23
                    },
                    {
                        "business_due_date": "2024-09-23",
                        "calendar_days": 31,
                        "due_date": "2024-09-22",
                        "due_principal": 292.078626459,
                        "installment_number": 8,
                        "pre_fixed_amount": 3.9848593609,
                        "principal_amortization_amount": 96.0151406391,
                        "total_amount": 100.0,
                        "workdays": 21
                    },
                    {
                        "business_due_date": "2024-10-22",
                        "calendar_days": 30,
                        "due_date": "2024-10-22",
                        "due_principal": 196.0634858199,
                        "installment_number": 9,
                        "pre_fixed_amount": 2.5880710578,
                        "principal_amortization_amount": 97.4119289422,
                        "total_amount": 100.0,
                        "workdays": 22
                    },
                    {
                        "business_due_date": "2024-11-22",
                        "calendar_days": 31,
                        "due_date": "2024-11-22",
                        "due_principal": 98.6515568777,
                        "installment_number": 10,
                        "pre_fixed_amount": 1.3459361963,
                        "principal_amortization_amount": 98.6540638037,
                        "total_amount": 100.0,
                        "workdays": 22
                    }
                ],
                "issue_amount": 917.64,
                "number_of_installments": 10,
                "prefixed_interest_rate": {
                    "annual_rate": 0.17042118,
                    "daily_rate": 0.00043722,
                    "interest_base": "calendar_days",
                    "monthly_rate": 0.0132
                },
                "total_iof": 0.0
            }
        ],
        "final_disbursement_amount": -79.83
    }
}
```

## Portabilidade pura

Para simular uma portabilidade sem liberação de Troco, envie apenas `portability_credit_operation` — sem o objeto `refinancing_credit_operation`.

**Requisição**

**request.json**

```json
{
    "borrower": {
        "person_type": "natural"
    },
    "collaterals": [
        {
            "collateral_type": "private_payroll"
        }
    ],
    "portability_credit_operation": {
        "financial": {
            "monthly_interest_rate": 0.0132,
            "installment_face_value": 100,
            "number_of_installments": 10
        }
    },
    "origin_contract": {
        "last_due_balance": 997.87
    }
}
```
 

**Resposta**

**response.json**

```json
{
    "portability_credit_operation": {
        "fine_configuration": {
            "contract_fine_rate": 0.02,
            "interest_base": "calendar_days",
            "monthly_rate": 0.01
        },
        "disbursement_options": [
            {
                "installments": [
                    {
                        "bank_slip_key": null,
                        "digitable_line": null,
                        "business_due_date": "2021-08-09",
                        "calendar_days": 53,
                        "due_date": "2021-08-08",
                        "due_principal": 997.87,
                        "installment_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036",
                        "installment_number": 1,
                        "pre_fixed_amount": 54.84865004983954,
                        "principal_amortization_amount": 306.98134995016045,
                        "total_amount": 361.83,
                        "workdays": 37
                    },
                    {
                        "bank_slip_key": null,
                        "digitable_line": null,
                        "business_due_date": "2021-09-08",
                        "calendar_days": 31,
                        "due_date": "2021-09-08",
                        "due_principal": 690.89,
                        "installment_key": "e8406cdb-844c-4e6d-9620-3635fab9d8d1",
                        "installment_number": 2,
                        "pre_fixed_amount": 21.964874249804833,
                        "principal_amortization_amount": 339.86512575019515,
                        "total_amount": 361.83,
                        "workdays": 22
                    }
                ],
                "prefixed_interest_rate": {
                    "annual_rate": 0.44556431,
                    "daily_rate": 0.00564312,
                    "monthly_rate": 0.0556431,
                    "interest_base": "calendar_days_365"
                },
                "iof_amount": 0,
                "external_contract_fee_amount": 0,
                "external_contract_fees": [],
                "contract_fee_amount": 0,
                "contract_fees": [],
                "number_of_installments": 2,
                "disbursed_issue_amount": 1000,
                "issue_amount": 1000,
                "disbursement_date": "2021-05-31",
                "cet": 1.212,
                "annual_cet": 32.122
            }
        ]
    }
}
```

---

# Manual Consignado Privado - Portabilidade + Refinanciamento

URL: /documentation/manual_consignado_privado/portabilidade/visao_geral

Este manual documenta o fluxo de **portabilidade de crédito consignado privado**: a compra de uma dívida consignada originada em outra instituição, com a opção de, ao final, liberar mais crédito ao trabalhador (o **Troco**) por meio de uma operação de refinanciamento.

A proposta de portabilidade é digitada no endpoint `POST /v2/credit_transfer/proposal` e processada junto à **CTC** (Central de Transferência de Crédito, operada pela Núclea). A garantia da operação é a folha de pagamento de funcionários de empresas privadas (`collateral_type: "private_payroll"`), averbada junto ao empregador.

Além do passo a passo de integração, esta página descreve o **fluxo de negócio** por trás da portabilidade — como funciona a comunicação com a instituição credora original através da CTC, os prazos e retornos possíveis, e o que fazer quando o saldo devedor real diverge do saldo estimado no início do fluxo. Use-a como referência para desenhar a esteira de emissão do seu produto.

## Quando usar

Use a portabilidade quando o trabalhador já possui um contrato de consignado privado em **outra instituição** e deseja transferir essa dívida para a sua operação. Dois cenários:

- **Portabilidade pura** — assume a dívida de origem nas novas condições, sem liberar caixa adicional.
- **Portabilidade + Refinanciamento (com Troco)** — assume a dívida de origem e, na mesma proposta, refinancia a operação liberando um valor adicional (Troco) ao trabalhador. A proposta de portabilidade e a de refinanciamento são geradas na **mesma requisição**.

## Composição da operação

Uma proposta de portabilidade é montada com até três blocos, além dos dados cadastrais do tomador:

| Bloco | Campo no payload | Papel |
|---|---|---|
| **Garantia** | `collaterals[].collateral_type: "private_payroll"` | Folha de pagamento de funcionários de empresas privadas (averbação junto ao empregador). `collateral_data` carrega `employer_document_number` e `registration_number`. |
| **Portabilidade** | `portability_credit_operation` | Operação que assume (porta) o contrato de origem. Informa `number_of_installments` e **uma** entre `monthly_interest_rate` ou `installment_face_value`. |
| **Refinanciamento (Troco)** | `refinancing_credit_operation` | Opcional. Quita a operação de portabilidade e libera o Troco na conta do trabalhador. Carrega `disbursement_bank_account`. |
| **Contrato de origem** | `origin_contract` | Identifica a dívida na instituição credora original: `ispb`, `contract_number`, `last_due_balance`. |

## Como funciona a portabilidade na CTC/Núclea

A portabilidade não é uma transação direta entre a QI Tech e o banco onde o trabalhador tem a dívida hoje — toda a comunicação passa por uma câmara centralizadora, e envolve prazos e decisões de terceiros que o parceiro precisa entender para desenhar sua esteira corretamente.

### Os papéis envolvidos

| Papel | Quem é |
|---|---|
| **Instituição Proponente** | A QI Tech, atuando em nome do parceiro — é quem está "comprando" a dívida do trabalhador. |
| **Instituição Credora Original** (o "banco atacado") | A instituição onde o contrato consignado hoje existe. Pode ser qualquer participante da CTC (bancos digitais que atuam fortemente em consignado privado, como o Nubank, são um exemplo comum, mas o fluxo é o mesmo para qualquer credora original). |
| **CTC (Central de Transferência de Crédito)** | Câmara centralizadora operada pela Núclea, regulamentada pela Resolução BCB nº 4.292/2013. Nenhuma comunicação ocorre diretamente entre Proponente e Credora Original — tudo passa pela CTC, que também atribui um Número Único de Portabilidade a cada solicitação. |
| **Empregador** | Mantém a folha de pagamento onde a margem consignável do trabalhador é averbada (reservada) e desaverbada (liberada) a cada operação. |

### 1. Simulação com base nos dados informados pelo próprio trabalhador

No início do fluxo, o parceiro **não tem acesso aos dados oficiais do contrato na instituição credora original** — só o próprio trabalhador pode informá-los. Por isso, tanto a [Simulação](/documentation/manual_consignado_privado/portabilidade/simulacao) quanto a [Digitação da Proposta](/documentation/manual_consignado_privado/portabilidade/proposta) são montadas com um **saldo devedor estimado** (`origin_contract.last_due_balance`) e os dados de identificação do contrato de origem (`ispb`, `contract_number`) fornecidos pelo trabalhador — não com o saldo contábil real, que só existe dentro da credora original.

É nessa simulação que as condições da operação de portabilidade — e, se houver, do Refinanciamento (Troco) — são calculadas e apresentadas ao trabalhador antes de qualquer envio à CTC.

### 2. O envio da solicitação ("ataque") à instituição credora original

A digitação da proposta (`POST /v2/credit_transfer/proposal`) só monta e registra a operação — o "ataque" à instituição credora original **só é enviado depois que o tomador assina a proposta** na [Formalização](/documentation/manual_consignado_privado/portabilidade/formalizacao). É esse envio, pós-assinatura, que a CTC repassa à instituição credora original identificada em `origin_contract`, e é ele que dá início à contagem dos prazos de resposta descritos a seguir. Ver os status `pending_response` / `pending_acceptance` em [Acompanhamento da Operação](/documentation/manual_consignado_privado/portabilidade/maquina_de_status).

### 3. Prazos de resposta da instituição credora original

Os prazos de resposta são definidos pela regulamentação da CTC/Núclea, não por configuração da QI Tech — a credora original tem **até 5 dias úteis**, após a recepção do ataque, tanto para decidir se retém o cliente (recusar a portabilidade) quanto para responder informando o saldo devedor — é o mesmo prazo para as duas decisões, não um sendo subconjunto do outro.

Dentro do dia em que a resposta é dada, há ainda dois horários-limite:

- A instituição credora original deve liberar/informar o saldo devedor **até às 10:00**.
- A QI Tech deve enviar o comando de pagamento (liquidação do saldo devedor) **até às 16:00** do mesmo dia.

Se a credora original não responder dentro do prazo de 5 dias úteis, a solicitação entra em **decurso de prazo** — isso **não cancela automaticamente** a portabilidade, ela continua válida e pode ser respondida a qualquer momento. Se o parceiro (ou o trabalhador) decidir desistir nesse meio tempo, é necessário cancelar explicitamente a proposta. Ver o detalhamento de status em [Acompanhamento da Operação](/documentation/manual_consignado_privado/portabilidade/maquina_de_status).

### 4. Os retornos possíveis da instituição credora original

| Retorno | O que significa |
|---|---|
| **Retenção** (`retained`) | A credora original decide manter o cliente e informa o motivo (ver [Enumeradores](/documentation/manual_consignado_privado/portabilidade/enumeradores#retention_reason_enumerator)). O contrato retido continua disponível para uma nova tentativa de portabilidade no futuro — inclusive pela própria QI Tech, com uma oferta diferente. |
| **Aceite com saldo devedor** (`accepted`) | A credora original não reteve o cliente e informa o saldo devedor contábil **real** do contrato (`final_due_balance`), junto com os dados completos do contrato original (taxa, CET, parcelas, datas). |

### 5. Quando o saldo devedor real diverge do saldo estimado

Este é o ponto mais importante para quem desenha uma esteira de portabilidade: a proposta é montada com uma **estimativa**, mas quem decide o valor real a ser pago é a instituição credora original — e os dois valores raramente coincidem exatamente.

- Se o saldo devedor real superar o estimado em **mais de 15%**, a proposta é **automaticamente rejeitada** pela QI Tech, com o motivo `divergent_due_balance` — evitando prosseguir com uma operação montada sobre uma premissa muito distante da realidade.
- Dentro dessa margem de 15%, a proposta segue para `accepted`, e cabe ao parceiro decidir se quer continuar. Essa decisão é formalizada pela chamada de aceite (`accepted_by_requester` — ver [Acompanhamento da Operação](/documentation/manual_consignado_privado/portabilidade/maquina_de_status)), que **recalcula as condições financeiras da operação (e do Troco, se houver) com base no saldo devedor real**, com duas garantias comerciais:
  - A parcela recalculada nunca pode ficar **maior** que a parcela do contrato de origem.
  - O Troco recalculado não pode **cair mais de 10%** em relação ao Troco originalmente calculado na simulação/digitação — preservando, dentro de uma margem, a oferta feita ao trabalhador no início do fluxo.

Se as novas condições não forem aceitáveis, o parceiro deve cancelar a proposta explicitamente; não é possível retomar uma proposta cancelada ou rejeitada — é sempre necessária uma nova digitação.

### 6. Pagamento do saldo devedor e averbação da margem: dois processos em paralelo

Uma vez aceita, a QI Tech envia o pagamento do saldo devedor à instituição credora original (liquidação) — e, **em paralelo**, inicia a averbação da nova operação de portabilidade na folha do empregador. São dois processos independentes, cada um com seu próprio acompanhamento (status da proposta vs. webhook de averbação): o envio do pagamento **não espera** a confirmação da averbação da margem. Ao desenhar sua esteira, não assuma que "pagamento enviado" já significa "margem garantida" — acompanhe os dois eventos separadamente em [Acompanhamento da Operação](/documentation/manual_consignado_privado/portabilidade/maquina_de_status).

### 7. A liberação da margem pelo banco atacado e a averbação da nova operação

Para que a averbação da nova operação seja aceita, o registro central de consignado privado precisa refletir que a margem do trabalhador — antes reservada pela instituição credora original — já está livre. Isso normalmente é consequência do próprio andamento da portabilidade (quitação do contrato original), mas pode não estar refletido no registro no exato momento em que a QI tenta averbar a nova operação.

Por isso, falhas transitórias na averbação (por exemplo, margem ainda aparecendo como comprometida, ou taxa da nova proposta em conflito com uma proposta ativa do trabalhador) não cancelam a operação de imediato: a QI tenta novamente de forma automática ("teimosinha") até que a averbação seja aceita ou até que um motivo terminal exija o cancelamento manual. Os motivos de falha e o comportamento de retentativa estão detalhados em [Averbação e Desembolso](/documentation/manual_consignado_privado/manual_averbacao_desembolso#fail_reservation_reason); o webhook de confirmação (sucesso ou falha) da averbação da portabilidade está documentado em [Acompanhamento da Operação](/documentation/manual_consignado_privado/portabilidade/maquina_de_status).

### 8. Da portabilidade paga ao início do Refinanciamento (Troco)

A operação de Refinanciamento (Troco), quando existe, só pode ser aceita **depois que a garantia da operação de Portabilidade estiver averbada** — a tentativa de prosseguir com o Troco antes disso é bloqueada. Ao desenhar a esteira, aguarde o webhook de averbação da Portabilidade antes de disparar a aceitação do Refinanciamento. Uma vez aceito, o Troco segue seu próprio ciclo de averbação e desembolso, detalhado em [Acompanhamento da Operação](/documentation/manual_consignado_privado/portabilidade/maquina_de_status).

## Fluxo (passo a passo)

1. **[Consultas prévias](/documentation/manual_consignado_privado/portabilidade/consultas)** — consulta dos vínculos empregatícios e dos dados do trabalhador (margem consignável), com o Termo de Autorização. **Pré-requisito obrigatório** para a averbação.
2. **[Simulação](/documentation/manual_consignado_privado/portabilidade/simulacao)** — simula as condições financeiras e o Troco, a partir do saldo devedor estimado informado pelo trabalhador, antes (ou em vez) de digitar a proposta.
3. **[Digitação da proposta](/documentation/manual_consignado_privado/portabilidade/proposta)** — `POST /v2/credit_transfer/proposal` com a garantia `private_payroll`, a operação de portabilidade e, opcionalmente, a de refinanciamento.
4. **[Formalização](/documentation/manual_consignado_privado/portabilidade/formalizacao)** — assinatura das operações via QI Sign. A QI Tech coleta os documentos e captura a assinatura; o parceiro não envia documentos. É **só após a assinatura** que o "ataque" é enviado à instituição credora original através da CTC.
5. **[Acompanhamento da Operação](/documentation/manual_consignado_privado/portabilidade/maquina_de_status)** — acompanhamento da proposta na CTC (`pending_response → pending_acceptance → accepted → accepted_by_requester → settlement_sent → paid`), incluindo o recálculo por divergência de saldo devedor e a averbação da margem, e da operação de refinanciamento/Troco (`issued → disbursed`).
6. **[Consultas e operações pós-proposta](/documentation/manual_consignado_privado/portabilidade/consultas_pos_proposta)** — lista de participantes da CTC, recuperação da última resposta de averbação, redução de parcelas, fee e recibo de pagamento.
7. **[Mocks e Sandbox](/documentation/manual_consignado_privado/portabilidade/mocks_sandbox)** — simulação de cenários (aprovação, rejeição, saldo) em ambiente de testes.

Referência transversal: **[Enumeradores](/documentation/manual_consignado_privado/portabilidade/enumeradores)**.

## Pré-requisito: consultas do trabalhador

Antes da digitação, é obrigatório realizar uma **consulta de dados válida** do trabalhador (consulta dos vínculos empregatícios + consulta de saldo/margem), assinada com o **Termo de Autorização**. Essas consultas estão documentadas em **[Consultas do Trabalhador](/documentation/manual_consignado_privado/manual_consultas_trabalhador)**; a página [Consultas prévias](/documentation/manual_consignado_privado/portabilidade/consultas) explica como elas se encaixam no fluxo de portabilidade.

## Glossário

| Termo | Significado |
|---|---|
| **CTC** | Central de Transferência de Crédito, operada pela Núclea — câmara que intermedia toda a comunicação da portabilidade entre a Instituição Proponente e a Instituição Credora Original. |
| **Instituição Proponente** | Quem propõe a portabilidade — a QI Tech, atuando em nome do parceiro. |
| **Instituição Credora Original / "banco atacado"** | Instituição onde o contrato consignado hoje existe. |
| **"Ataque"** | Termo de mercado para o envio da solicitação de portabilidade, pela CTC, à instituição credora original. |
| **Saldo devedor estimado** | Valor informado pelo trabalhador na proposta (`origin_contract.last_due_balance`), usado para simular e digitar a operação antes de qualquer confirmação da credora original. |
| **Saldo devedor real** | Valor contábil oficial do contrato de origem, informado pela credora original na resposta de aceite (`final_due_balance`). Pode divergir do saldo estimado — ver [seção 5](#5-quando-o-saldo-devedor-real-diverge-do-saldo-estimado). |
| **Retenção** | Decisão da credora original de não liberar o cliente para a portabilidade, com motivo obrigatório. |
| **Troco** | Valor adicional liberado ao trabalhador quando a portabilidade vem acompanhada de refinanciamento (`refinancing_credit_operation`). |
| **`origin_contract`** | Dados do contrato na instituição credora original (`ispb`, `contract_number`, `last_due_balance`). |
| **Averbação** | Reserva da margem consignável na folha de pagamento do empregador, garantindo o desconto das parcelas. |
| **"Teimosinha"** | Retentativa automática de averbação feita pela QI Tech quando a tentativa falha por um motivo não terminal (ex.: margem ainda não liberada pela credora original). |
| **`private_payroll`** | `collateral_type` da garantia de folha de pagamento de funcionários de empresas privadas; `collateral_data` = `employer_document_number` + `registration_number`. |
| **`proposal_type`** | Tipo da proposta; para Consignado Privado, `"private_company"`. |

---

# Manual Consignado Privado - Movimentação de Vínculos: Consulta de Reservas

URL: /documentation/manual_consignado_privado/vinculos_empregaticios/consultas

:::info Diferença em relação à consulta por external_key
Já existe uma consulta de reserva por operação específica, `GET /private_payroll/reservation/external_key/{external_key}`, documentada em [Averbação de Novos Empréstimos — Consulta de Reservas](/documentation/manual_consignado_privado/averbacao_novos_emprestimos/consultas#consulta-por-operacao-external_key). Aquele endpoint retorna o histórico de tentativas de **uma** operação de crédito. O endpoint desta página não recebe nenhuma `external_key` — ele **lista e filtra reservas em lote**, entre todas as operações do solicitante.
:::

## Consulta paginada de reservas

**GET**
/private_payroll/reservation

Testar no Playground

A consulta é sempre restrita às reservas do próprio solicitante autenticado — não é necessário (nem possível) informar o `requester_key` como filtro. Para acompanhar revínculos em andamento, filtre por `reservation_type=transferred`.

### Query Params

| Campo | Descrição | Tipo | Obrigatório | Valores |
|---|---|---|---|---|
| `document_number` | CPF do trabalhador, para filtrar as reservas de um único tomador | Texto | Não | — |
| `reservation_type` | Filtra pelo método de averbação da reserva — use `transferred` para localizar revínculos | Texto | Não | `new_credit`, `refinancing`, `portability`, `transferred` |
| `reservation_status` | Filtra pelo status atual da reserva | Texto | Não | Ver [Enumeradores](/documentation/manual_consignado_privado/vinculos_empregaticios/enumeradores#reservation_status) |
| `page_number` | Número da página, começando em 1 | Número | Não (padrão `1`) | Mínimo `1` |
| `page_rows` | Quantidade de registros por página | Número | Não (padrão `25`) | Entre `1` e `100` |

### Response sucesso

STATUS
**200**

**Response Body**

```json
{
    "data": [
        {
            "reservation_key": "<Reservation Key>",
            "requester_key": "123e4567-e89b-12d3-a456-426614174000",
            "document_number": "12345678901",
            "registration_number": "99999999999-A",
            "employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
            "admission_date": "2025-04-02",
            "employer_document_number": "12345678901234",
            "external_key": "123e4567-e89b-12d3-a456-426614174000",
            "contract_number": "2024001234",
            "inclusion_date": "2025-04-02",
            "disbursement_date": "2025-04-05",
            "expiration_date": null,
            "contract_data": {
                "amount": 5000.00,
                "installments": 12,
                "interest_rate": 0.018
            },
            "reservation_data": {
                "installment_value": 500.00,
                "margin_value": 450.00
            },
            "reservation_type": "transferred",
            "reservation_status": "reserved",
            "reservation_documents_submission_status": "sent",
            "protocols": {},
            "next_check_datetime": null,
            "next_billing_execution_datetime": null,
            "balance_inquiry_data": {},
            "periods": [],
            "warranty_type": null
        }
    ],
    "pagination": {
        "current_page": 1,
        "next_page": 2,
        "rows_per_page": 25
    }
}
```

Cada item de `data` tem o mesmo formato retornado pelo endpoint de [autorização do revínculo](/documentation/manual_consignado_privado/vinculos_empregaticios/revinculo#1-autorizacao). Já `pagination.next_page` vem `null` quando a página atual é a última (ou seja, quando a quantidade de itens retornados em `data` é menor que `page_rows`); caso contrário, traz o número da próxima página a ser consultada.

### Response falha

Quando nenhuma reserva atende aos filtros informados, o endpoint retorna:

STATUS
**404**

**Response Body**

```json
{
    "title": "Reservation not found",
    "code": "PRP000035",
    "description": "The reservation was not found",
    "translation": "A reserva não foi encontrada"
}
```

---

# Manual Consignado Privado - Movimentação de Vínculos: Enumeradores

URL: /documentation/manual_consignado_privado/vinculos_empregaticios/enumeradores

:::info Erros de averbação de um contrato novo
Os motivos de falha retornados pela DATAPREV na averbação de um **contrato novo** (quantidade máxima de contratos, vínculo bloqueado, etc.) estão em [Averbação de Novos Empréstimos — Erros de Averbação](/documentation/manual_consignado_privado/averbacao_novos_emprestimos/erros). Esta página cobre apenas os enumeradores específicos do fluxo de **movimentação de vínculos e revínculo**.
:::

## Status da reserva {#reservation_status}

| Enumerador | Descrição |
|---|---|
| **pending_requester_authorization** | Averbação criada, aguardando autorização do parceiro |
| **pending_reservation** | Averbação criada, na fila para tentativa junto à DATAPREV |
| **authorized** | Averbação autorizada pelo parceiro (por exemplo, um revínculo com margem parcial), seguirá para a fila de averbação |
| **reserved** | Averbação concluída com sucesso — margem reservada na folha do empregador |
| **transferred** | Averbação original marcada como transferida para um novo vínculo (revínculo) |
| **terminated** | Averbação encerrada por término do vínculo empregatício de origem |
| **canceled** | Averbação cancelada — não haverá novas tentativas |

## Método de averbação da reserva {#reservation_type}

| Enumerador | Descrição |
|---|---|
| **new_credit** | Averbação de uma nova contratação |
| **refinancing** | Averbação de uma operação de refinanciamento |
| **portability** | Averbação de uma operação de portabilidade |
| **transferred** | Averbação de um revínculo (reaverbação em um novo vínculo empregatício) |

## Motivo de falha na reaverbação {#fail_renewal_reason}

Motivos retornados pela DATAPREV em uma tentativa de reaverbação (revínculo) sem sucesso — presentes em `data.reason` (webhook `laas.private_payroll.reservation_status_change`) e em `data.reasons[].enumerator` (webhook [`laas.private_payroll.reservation_failure`](/documentation/manual_consignado_privado/averbacao_novos_emprestimos/erros#reservation-failure-webhook)).

| Enumerador | Descrição | Ação QI |
|---|---|---|
| **margin_exceeded** | Margem consignável do novo vínculo excedida | Retorna para `pending_requester_authorization` — nova consulta de dados e reavaliação são necessárias |
| **employment_relationship_not_ineligible_due_to_previous_termination** | Vínculo não está inelegível por empréstimo encerrado por término de vínculo anterior — não é possível fazer a reaverbação neste momento | Cancelamento da operação |

---

# Manual Consignado Privado - Movimentação de Vínculos: Webhooks de Movimentação

URL: /documentation/manual_consignado_privado/vinculos_empregaticios/movimentacao_de_vinculos

:::info Regras de negócio
Esta página cobre os webhooks de movimentação de vínculos. Para entender o ciclo de inelegibilidade que conecta o encerramento de um vínculo à liberação do novo, veja [Regras de Negócio — Por que a garantia precisa seguir o trabalhador](/documentation/manual_consignado_privado/vinculos_empregaticios/visao_geral#por-que-a-garantia-precisa-seguir-o-trabalhador).
:::

A DATAPREV fornece um serviço de atualização de vínculos empregatícios que é consultado diariamente pela QI Tech. Nesse serviço são informados os contratos que foram encerrados por término de vínculo e os novos vínculos empregatícios dos tomadores que possuem contratos ativos.

## Encerramento por término de vínculo {#encerramento-por-termino-de-vinculo}

A partir das atualizações de desligamento, são disparados webhooks informando a mudança de status das averbações para o status `terminated`:

webhook_type
laas.private_payroll.reservation_status_change
reservation_status
terminated
**Webhook Body**

```json
{
    "status": "terminated",
    "event_datetime": "2025-03-20T14:47:43Z",
    "key": "<Debt Key>",
    "webhook_type": "laas.private_payroll.reservation_status_change",
    "data": {
        "reservation_key": "<Reservation Key>",
            "document_number": "12345678901",
            "reservation_status": "terminated",
            "requester_key": "123e4567-e89b-12d3-a456-426614174000",
            "registration_number": "99999999999-A",
            "employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
            "employer_document_number": "12345678901234",
            "external_key": "123e4567-e89b-12d3-a456-426614174000",
            "contract_number": "2024001234",
            "inclusion_date": "2025-04-02",
            "disbursement_date": "2025-04-05",
            "reservation_type": "new_credit",
    }
}
```

## Novo vínculo empregatício {#novo-vinculo-empregaticio}

A partir das atualizações de novos vínculos, são disparados webhooks:

webhook_type
laas.private_payroll.new_employment_relationship
status
active
**Webhook Body**

```json
{
    "status": "active",
    "event_datetime": "2025-03-20T14:47:43Z",
    "key": "<Debt Key>",
    "webhook_type": "laas.private_payroll.new_employment_relationship",
    "data": {
        "document_number": "71742311016",
        "registration_number": "123456789ABCDEFR",
        "employer_document_number": "02302554000179",
        "status": "active",
        "employment_relationship_data": {
            "name": "LETYCIA AGUILAR DA SILVA",
            "eligible": true,
            "loan_count": 0,
            "employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
            "admission_date": "2025-04-02",
            "total_due_amount": 1642.16,
            "base_margin_amount": 911.67,
            "political_exposition": "not_exposed",
            "worker_category_code": 101,
            "employer_document_type": "CNPJ",
            "available_margin_amount": 319.08
        }
    }
}
```

:::info Elegibilidade do novo vínculo
Enquanto o contrato do vínculo anterior não for excluído ou reaverbado, o novo vínculo é informado pela DATAPREV como **inelegível** (`eligible: false`), mesmo estando ativo — ver o detalhamento do ciclo de motivos 4 e 8 em [Regras de Negócio](/documentation/manual_consignado_privado/vinculos_empregaticios/visao_geral#o-ciclo-de-inelegibilidade-motivo-4-motivo-8).
:::

É a partir deste webhook que o fluxo de [Averbação por Revínculo](/documentation/manual_consignado_privado/vinculos_empregaticios/revinculo) é iniciado.

---

# Manual Consignado Privado - Movimentação de Vínculos: Averbação por Revínculo

URL: /documentation/manual_consignado_privado/vinculos_empregaticios/revinculo

:::info Regras de negócio
Esta página cobre os endpoints e webhooks da reaverbação por revínculo. Para entender **por que** a autorização é obrigatória em determinados casos, e o que diferencia uma falha retentável de uma falha terminal, veja [Regras de Negócio — Reaverbação automática vs. autorização obrigatória](/documentation/manual_consignado_privado/vinculos_empregaticios/visao_geral#reaverbacao-automatica-vs-autorizacao-obrigatoria).
:::

## 1. Autorização {#1-autorizacao}

Semelhante ao fluxo de contratação de um novo empréstimo, é possível que a integração seja configurada para que todos os revínculos sejam criados pendente de autorização. Caso seja configurada para revincular automaticamente, ainda assim nos casos onde o novo vínculo é informado pela DATAPREV com margem parcial, as novas averbações serão criadas no status pendente de autorização.

Dependendo do status em que o revínculo foi criado, será enviado um webhook informando a criação da nova averbação e seu status (`pending_requester_authorization` ou `pending_reservation`):

webhook_type
laas.private_payroll.renewed_reservation

reservation_status
pending_requester_authorization/pending_reservation

**Webhook Body**

**Revínculo criado aguardando autorização**

    ```json
    {
        "status": "pending_requester_authorization",
        "event_datetime": "2025-03-20T14:47:43Z",
        "key": "<Debt Key>",
        "webhook_type": "laas.private_payroll.renewed_reservation",
        "data": {
                "reservation_key": "<Reservation Key>",
                "document_number": "12345678901",
                "reservation_status": "pending_requester_authorization",
                "requester_key": "123e4567-e89b-12d3-a456-426614174000",
                "registration_number": "99999999999-A",
                "employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
                "admission_date": "2025-04-02",
                "employer_document_number": "12345678901234",
                "external_key": "123e4567-e89b-12d3-a456-426614174000",
                "contract_number": "2024001234",
                "inclusion_date": "2025-04-02",
                "disbursement_date": "2025-04-05",
                "reservation_type": "transferred",
        }
    }
    ```
**Revínculo criado na fila para averbação**

    ```json
    {
        "status": "pending_reservation",
        "event_datetime": "2025-03-20T14:47:43Z",
        "key": "<Debt Key>",
        "webhook_type": "laas.private_payroll.renewed_reservation",
        "data": {
                "reservation_key": "<Reservation Key>",
                "document_number": "12345678901",
                "reservation_status": "pending_reservation",
                "requester_key": "123e4567-e89b-12d3-a456-426614174000",
                "registration_number": "99999999999-A",
                "employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
                "admission_date": "2025-04-02",
                "employer_document_number": "12345678901234",
                "external_key": "123e4567-e89b-12d3-a456-426614174000",
                "contract_number": "2024001234",
                "inclusion_date": "2025-04-02",
                "disbursement_date": "2025-04-05",
                "reservation_type": "transferred",
        }
    }
    ```

## 2. Autorização e atualização da margem {#2-atualizacao-da-margem}

Para os casos onde o novo vínculo não tem margem consignável suficiente para averbar a parcela cheia do contrato, é obrigatório que seja realizada a autorização da averbação. Diferente da averbação de um contrato novo — identificada pela `external_key` da operação de crédito, documentada em [Averbação de Novos Empréstimos — Autorização e Averbação](/documentation/manual_consignado_privado/averbacao_novos_emprestimos/tecnico#1-autorizacao) — a autorização do revínculo é feita pela **`reservation_key`**: o identificador da própria reserva criada para o revínculo, recebido no webhook `laas.private_payroll.renewed_reservation` acima.

### Request

**PATCH**
/private_payroll/reservation/ RESERVATION-KEY /authorize
Testar no Playground

### Response sucesso

STATUS
**200**

**Response Body**

```json
{
    "reservation_key": "<Reservation Key>",
    "document_number": "12345678901",
    "registration_number": "99999999999-A",
    "employer_document_number": "12345678901234",
    "external_key": "abc123def456",
    "contract_number": "2024001234",
    "inclusion_date": "2024-03-18",
    "disbursement_date": "2024-03-20",
    "contract_data": {
        "amount": 5000.00,
        "installments": 12,
        "interest_rate": 0.018
    },
    "reservation_data": {
        "installment_value": 500.00,
        "margin_value": 450.00
    },
    "reservation_status": "authorized"
}
```

### Response falha

STATUS
**400**

:::warning Reserva não encontrada ou não pertencente ao solicitante
Uma `reservation_key` inexistente **e** uma `reservation_key` que exista mas pertença a outro solicitante retornam o **mesmo** erro (`PRP000111`) — não há uma variante dedicada de "não encontrado".
:::

**Response Body**

**Reserva não encontrada ou não pertence ao solicitante**

    ```json
    {
        "title" : "Reservation is not ready for authorization",
        "code" : "PRP000111",
        "description" : "The reservation is not ready for authorization",
        "translation" : "A reserva não está pronta para autorização"
    }
    ```

**Averbação já está autorizada**

    ```json
    {
        "title" : "Reservation is not pending requester authorization",
        "code" : "PRP000057",
        "description" : "The reservation is not pending requester authorization",
        "translation" : "A reserva não está pendente de autorização do requerente",
    }
    ```

:::danger
Uma vez autorizado o revínculo com margem parcial, não é possível alterar o valor da averbação posteriormente. Os valores que não forem averbados deverão ser cobrados diretamente do tomador.
:::

É possível atualizar o valor da nova averbação através de uma [consulta de dados](/documentation/manual_consignado_privado/manual_consultas_trabalhador#consulta-de-dados) no novo vínculo antes de decidir a autorização; este mecanismo é importante pois é possível que a primeira margem do novo vínculo informada pela DATAPREV seja parcial dependendo do período de contribuição da primeira competência.

## 3. Revínculo {#3-revinculo}

### Sucesso

Quando a nova reserva é averbada com sucesso, são enviados dois webhooks informando a alteração de status da averbação original para `transferred` e a alteração de status da nova reserva para `reserved`.

webhook_type
laas.private_payroll.reservation_status_change

reservation_status
transferred

**Webhook Body**

```json
{
    "status": "transferred",
    "event_datetime": "2025-03-20T14:47:43Z",
    "key": "<Debt Key>",
    "webhook_type": "laas.private_payroll.reservation_status_change",
    "data": {
            "reservation_key": "<Reservation Key>",
            "document_number": "12345678901",
            "requester_key": "123e4567-e89b-12d3-a456-426614174000",
            "registration_number": "99999999999-A",
            "employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
            "employer_document_number": "12345678901234",
            "external_key": "123e4567-e89b-12d3-a456-426614174000",
            "contract_number": "2024001234",
            "inclusion_date": "2025-04-02",
            "disbursement_date": "2025-04-05",
            "reservation_type": "new_credit",
            "reservation_status": "transferred",
            "termination_date":null,
            "periods": [],
            "reason":null
    }
}
```

webhook_type
laas.private_payroll.reservation_status_change

reservation_status
reserved

**Webhook Body**

```json
{
    "status": "reserved",
    "event_datetime": "2025-03-20T14:47:43Z",
    "key": "<Debt Key>",
    "webhook_type": "laas.private_payroll.reservation_status_change",
    "data": {
            "reservation_key": "<Reservation Key>",
            "document_number": "12345678901",
            "reservation_status": "reserved",
            "requester_key": "123e4567-e89b-12d3-a456-426614174000",
            "registration_number": "99999999999-A",
            "employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
            "employer_document_number": "12345678901234",
            "external_key": "123e4567-e89b-12d3-a456-426614174000",
            "contract_number": "2024001234",
            "inclusion_date": "2025-04-02",
            "disbursement_date": "2025-04-05",
            "reservation_type": "transferred",
            "termination_date":null,
            "periods": [
                {
                "amount": 339.06,
                "due_date": "2026-08-28",
                "installment_key": "<Installment Key>",
                "installment_number": 1
                },
                {
                "amount": 339.06,
                "due_date": "2026-09-28",
                "installment_key": "<Installment Key>",
                "installment_number": 2
                },
                {
                "amount": 339.06,
                "due_date": "2026-10-28",
                "installment_key": "<Installment Key>",
                "installment_number": 3
                }
            ],
            "reason": null,
    }
}
```

### Falha

Diferente da averbação de crédito novo, caso haja uma falha no revínculo por margem excedida, a averbação irá retornar ao status de pendente de autorização. Nestes casos é possível que a margem consignável disponível para o revínculo tenha flutuado, sendo necessária uma nova [consulta de dados](/documentation/manual_consignado_privado/manual_consultas_trabalhador#consulta-de-dados) para reavaliar a reaverbação.

webhook_type
laas.private_payroll.reservation_status_change

reservation_status
pending_requester_authorization

**Webhook Body**

```json
{
    "status": "pending_requester_authorization",
    "event_datetime": "2025-03-20T14:47:43Z",
    "key": "<Debt Key>",
    "webhook_type": "laas.private_payroll.reservation_status_change",
    "data": {
        "reservation_key": "<Reservation Key>",
        "document_number": "12345678901",
        "reservation_status": "pending_requester_authorization",
        "requester_key": "123e4567-e89b-12d3-a456-426614174000",
        "registration_number": "99999999999-A",
        "employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
        "employer_document_number": "12345678901234",
        "external_key": "123e4567-e89b-12d3-a456-426614174000",
        "contract_number": "2024001234",
        "inclusion_date": "2025-04-02",
        "disbursement_date": "2025-04-05",
        "reservation_type": "transferred",
        "termination_date":null,
        "periods": [],
        "reason": {
            "enumerator": "margin_exceeded",
            "description": "Consignable margin exceeded",
            "translation": "Margem consignável excedida"
        }
    }
}
```

Caso haja uma falha na averbação porque o vínculo empregatício não está mais disponível para reaverbação, a nova averbação será cancelada e não haverá mais tentativas.

webhook_type
laas.private_payroll.reservation_status_change

reservation_status
canceled

**Webhook Body**

```json
{
    "status": "pending_requester_authorization",
    "event_datetime": "2025-03-20T14:47:43Z",
    "key": "<Debt Key>",
    "webhook_type": "laas.private_payroll.reservation_status_change",
    "data": {
        "reservation_key": "<Reservation Key>",
        "document_number": "12345678901",
        "reservation_status": "canceled",
        "requester_key": "123e4567-e89b-12d3-a456-426614174000",
        "registration_number": "99999999999-A",
        "employer_name": "VIPER SERVICOS DO NORDESTE LTDA",
        "employer_document_number": "12345678901234",
        "external_key": "123e4567-e89b-12d3-a456-426614174000",
        "contract_number": "2024001234",
        "inclusion_date": "2025-04-02",
        "disbursement_date": "2025-04-05",
        "reservation_type": "transferred",
        "termination_date":null,
        "periods": [],
        "reason": {
            "enumerator": "employment_relationship_not_ineligible_due_to_previous_termination",
            "description": "Employment relationship is not ineligible due to loan closed by previous relationship termination",
            "translation": "Vínculo não está inelegível por empréstimo encerrado por término de vínculo anterior"
        },
    }
}
```

:::info Webhook adicional com motivo da falha
Assim como na averbação de um contrato novo, essas falhas de reaverbação também disparam o webhook dedicado `laas.private_payroll.reservation_failure` — ver [detalhamento em Erros de Averbação](/documentation/manual_consignado_privado/averbacao_novos_emprestimos/erros#reservation-failure-webhook). Para o revínculo, `data.reservation_type` vem como `"transferred"`.
:::

---

# Manual Consignado Privado - Movimentação de Vínculos: Regras de Negócio

URL: /documentation/manual_consignado_privado/vinculos_empregaticios/visao_geral

Este manual documenta o que acontece com a garantia de um consignado privado quando o **vínculo empregatício do trabalhador termina**: como a DATAPREV comunica o encerramento e a chegada de um novo emprego, e todo o fluxo até a dívida ser **reaverbada (revínculo)** — ou seja, até a margem do contrato original ser transferida para a margem consignável do novo vínculo.

:::info Averbação de um contrato novo
Este manual **não** cobre a averbação inicial de uma contratação nova — isso está em [Averbação de Novos Empréstimos](/documentation/manual_consignado_privado/averbacao_novos_emprestimos/visao_geral). Aqui, o ponto de partida é sempre um contrato **já averbado** cujo vínculo de origem terminou.
:::

## Quando usar

Use esta referência para desenhar a esteira de **retenção de carteira**: o que a QI Tech faz automaticamente quando um trabalhador muda de emprego, e o que exige uma decisão do parceiro — autorizar um revínculo com margem parcial.

## Por que a garantia precisa "seguir" o trabalhador {#por-que-a-garantia-precisa-seguir-o-trabalhador}

A margem consignável está associada a um vínculo empregatício específico (um trabalhador em um empregador). Quando esse vínculo termina, a margem reservada para o contrato deixa de existir — mas a dívida do trabalhador com a instituição financeira, não. A DATAPREV fornece um serviço de atualização de vínculos, consultado diariamente pela QI Tech, que informa:

- Os contratos que foram **encerrados por término de vínculo**.
- Os **novos vínculos empregatícios** de trabalhadores que possuíam contratos ativos.

Essas duas informações são o que permite à QI Tech (e ao parceiro) identificar, monitorar e executar a reaverbação — ajustando os termos da dívida à nova margem consignável disponível, ao mesmo tempo em que preserva a sustentabilidade financeira da carteira.

## O ciclo de inelegibilidade (motivo 4 → motivo 8) {#o-ciclo-de-inelegibilidade-motivo-4-motivo-8}

O mecanismo que impede a dupla contagem de margem (a antiga e a nova) durante a transição é o de **inelegibilidade do vínculo**, controlado pela própria DATAPREV:

1. O vínculo do trabalhador com o empregador de origem é encerrado. O contrato ativo nesse vínculo passa para a situação **15 — "Encerrado por término de vínculo"**. Esse vínculo (de origem) fica **inelegível com motivo 4** (vínculo com data de desligamento).
2. Quando o novo vínculo é carregado na base da DATAPREV, ele nasce **inelegível com motivo 8** (vínculo com CPF que possui empréstimo encerrado por término de vínculo) — ou seja, mesmo sendo um vínculo novo e ativo, ele não pode receber novas averbações até que a pendência do contrato anterior seja resolvida.
3. Quando o contrato de origem é **excluído** (por liquidação ou outro motivo) ou **renegociado/reaverbado** no novo vínculo, o novo vínculo deixa de ser inelegível e volta a operar normalmente.

## Do novo vínculo até a reaverbação {#do-novo-vinculo-ate-a-reaverbacao}

Este é o fluxo completo, do momento em que a DATAPREV identifica o novo emprego até a dívida estar reaverbada (ou definitivamente cancelada):

1. **Encerramento do vínculo de origem** — a DATAPREV informa o término, o contrato original passa para `terminated` e o parceiro recebe o webhook correspondente. Ver [Movimentação de Vínculos](/documentation/manual_consignado_privado/vinculos_empregaticios/movimentacao_de_vinculos#encerramento-por-termino-de-vinculo).
2. **Identificação do novo vínculo** — a DATAPREV informa o novo emprego do trabalhador (ainda inelegível, motivo 8), e o parceiro recebe o webhook de novo vínculo. Ver [Movimentação de Vínculos](/documentation/manual_consignado_privado/vinculos_empregaticios/movimentacao_de_vinculos#novo-vinculo-empregaticio).
3. **Criação da nova reserva (revínculo)** — a QI cria a nova `reservation` já vinculada ao novo emprego, em um de dois estados, dependendo da configuração do ambiente e da margem disponível: pendente de autorização do parceiro, ou direto na fila de averbação. Ver [Averbação por Revínculo — Autorização](/documentation/manual_consignado_privado/vinculos_empregaticios/revinculo#1-autorizacao).
4. **Autorização, quando obrigatória** — se a margem consignável do novo vínculo não for suficiente para a parcela cheia do contrato original (margem parcial), a autorização do parceiro é **sempre obrigatória**, mesmo com a revinculação automática habilitada. Ver [Reaverbação automática vs. autorização obrigatória](#reaverbacao-automatica-vs-autorizacao-obrigatoria).
5. **Tentativa de averbação na DATAPREV** — assim como na averbação de um contrato novo, a tentativa pode ter sucesso ou falhar; uma falha por margem excedida é retentada automaticamente, uma falha por vínculo indisponível para reaverbação é terminal. Ver [O que acontece quando a reaverbação falha](#o-que-acontece-quando-a-reaverbacao-falha).
6. **Resultado** — em caso de sucesso, dois webhooks confirmam a transição: o contrato original passa a `transferred` e a nova reserva passa a `reserved`. Ver [Averbação por Revínculo — Sucesso](/documentation/manual_consignado_privado/vinculos_empregaticios/revinculo#3-revinculo).

## Reaverbação automática vs. autorização obrigatória {#reaverbacao-automatica-vs-autorizacao-obrigatoria}

Semelhante ao fluxo de contratação de um novo empréstimo, a integração pode ser configurada para que todos os revínculos sejam criados pendentes de autorização, ou para que a QI revincule automaticamente. Mesmo com a revinculação automática habilitada, há um caso em que a autorização do parceiro é **sempre obrigatória**: quando o novo vínculo é informado pela DATAPREV com **margem parcial** — ou seja, quando a margem consignável disponível no novo emprego não é suficiente para cobrir a parcela cheia do contrato original.

:::danger
Uma vez autorizado o revínculo com margem parcial, não é possível alterar o valor da averbação posteriormente. Os valores que não forem averbados deverão ser cobrados diretamente do tomador.
:::

Como a primeira margem do novo vínculo informada pela DATAPREV pode ser parcial simplesmente por causa do período de contribuição da primeira competência, é possível — e recomendado — reavaliar esse valor por meio de uma [consulta de dados](/documentation/manual_consignado_privado/manual_consultas_trabalhador#consulta-de-dados) no novo vínculo antes de decidir a autorização.

## O que acontece quando a reaverbação falha {#o-que-acontece-quando-a-reaverbacao-falha}

Diferente da averbação de crédito novo, uma falha no revínculo por **margem excedida** deixa a `reservation` em situação de teimosinha: ela retorna ao status `pending_requester_authorization`, pois a margem consignável do novo vínculo pode ter flutuado desde a última consulta — cabendo ao parceiro fazer uma nova [consulta de dados](/documentation/manual_consignado_privado/manual_consultas_trabalhador#consulta-de-dados) e reavaliar a reaverbação.

Já uma falha porque o vínculo empregatício **não está mais disponível para reaverbação** (por exemplo, o vínculo de origem já não está mais na situação que permite a transferência) é **terminal**: a nova averbação é cancelada e não há mais tentativas automáticas.

Os webhooks de autorização, sucesso e falha do revínculo estão documentados em **[Averbação por Revínculo](/documentation/manual_consignado_privado/vinculos_empregaticios/revinculo)**.

## Conteúdo desta seção

1. **[Movimentação de Vínculos](/documentation/manual_consignado_privado/vinculos_empregaticios/movimentacao_de_vinculos)** — webhooks de encerramento de contrato por término de vínculo e de identificação de novo vínculo empregatício.
2. **[Averbação por Revínculo](/documentation/manual_consignado_privado/vinculos_empregaticios/revinculo)** — autorização, atualização de margem, e webhooks de sucesso e falha da reaverbação no novo vínculo.
3. **[Consulta de Reservas](/documentation/manual_consignado_privado/vinculos_empregaticios/consultas)** — consulta paginada de reservas por filtros (documento, tipo e status), com foco em revínculos.
4. **[Enumeradores](/documentation/manual_consignado_privado/vinculos_empregaticios/enumeradores)** — status de reserva e motivos de falha específicos do revínculo.

## Glossário

| Termo | Significado |
|---|---|
| **`reservation`** | Entidade que acompanha as tentativas de averbação de um contrato na DATAPREV e a gestão da garantia (margem reservada) após a averbação. |
| **Revínculo / Reaverbação** | Transferência da averbação de um contrato encerrado por término de vínculo para o novo vínculo empregatício do trabalhador. |
| **Motivo 4** | Inelegibilidade da DATAPREV para o vínculo de origem, por já possuir data de desligamento. |
| **Motivo 8** | Inelegibilidade da DATAPREV para o novo vínculo, enquanto o contrato do vínculo anterior não é excluído ou reaverbado. |
| **Margem parcial** | Situação em que a margem consignável do novo vínculo é insuficiente para cobrir a parcela cheia do contrato original, exigindo autorização do parceiro. |
| **"Teimosinha"** | Retentativa automática de averbação feita pela QI Tech quando a tentativa falha por um motivo não terminal. |

---

# Manual de Consulta de Autorização FGTS

URL: /documentation/manual_consulta_de_autorizacao_FGTS/

:::info Veja também
- [Originação FGTS](/documentation/manual_FGTS/manual_fgts)
:::

## 1. Consulta de Autorização do Beneficiário

A consulta de autorização permite verificar se o beneficiário concedeu autorização para averbação e consulta de saldo no FGTS, vinculada a um CPF específico, para realizar operações junto à Caixa Econômica Federal.

### Características da Consulta

- **Requisição síncrona**: Retorna resultado imediatamente
- **Regra de negócio**: O sucesso da consulta ocorre apenas para o último parceiro com quem o beneficiário possui vínculo ativo
- **Exceção**: Caso o beneficiário não tenha realizado operações nos últimos 90 dias, a consulta retornará com dados para todos os parceiros

### Requisitos

Para realizar a consulta, é necessário o **CPF** do beneficiário.

### Endpoint

**GET**
`/fgts_issuer_auth_manager/issuer/{CPF}`

Testar no Playground

**Path Params**

| Campo           | Tipo   | Descrição                     | Obrigatório | Formatação           |
|-----------------|--------|-------------------------------|-------------|----------------------|
| document_number | string | Número do CPF do beneficiário | Sim         | 11 dígitos numéricos, sem pontuação |

### Resposta de Sucesso

STATUS
**200** (OK)

**Exemplos de Resposta**

**Autorizado:**
```json
{
    "authorization_limit_date": "2026-01-01",
    "last_checked_at": "2025-10-01",
    "status": "authorized"
}
```

**Não Autorizado:**
```json
{
    "authorization_limit_date": null,
    "last_checked_at": "2025-10-01",
    "status": "unauthorized"
}
```

### Resposta de Erro

STATUS
**404** (Not Found)

Retornado quando o CPF não foi encontrado na base.

## Referência de Status

| Status         | Descrição                           |
|----------------|-------------------------------------|
| `authorized`   | Beneficiário possui autorização     |
| `unauthorized` | Beneficiário não possui autorização |

## Campos de Resposta

| Campo                      | Tipo   | Descrição                                    |
|----------------------------|--------|----------------------------------------------|
| `authorization_limit_date` | string | Data limite da autorização (formato: YYYY-MM-DD) |
| `last_checked_at`          | string | Data da última atualização da autorização   |
| `status`                   | string | Status atual da autorização                  |

---

# Consulta - Emissão Crédito Clean

URL: /documentation/manual_credito_clean/emissao/consulta

## Resumo

Você pode consultar a dívida a qualquer momento para obter informações ou acompanhar o status atual da operação.

## Consultar Operação de Crédito

Existem duas formas de consultar uma operação:
- Por `credit_operation_key` (DEBT-KEY)
- Por `requester_identifier_key` (chave identificadora enviada na emissão)

### Por Credit Operation Key

ENDPOINT /v2/credit_operation/ CREDIT-OPERATION-KEY
MÉTODO GET

Testar no Playground

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `credit_operation_key`* | string | Chave da operação de crédito (DEBT-KEY) | UUID |

### Por Requester Identifier Key

ENDPOINT /v2/credit_operation/requester_identifier_key/ REQUESTER-IDENTIFIER-KEY
MÉTODO GET

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `requester_identifier_key`* | string | Chave identificadora enviada na emissão | UUID |

### Response

STATUS 200

Response Body

```json
{
    "credit_operation_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c",
    "issue_amount": 1007.62,
    "origin_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c",
    "total_iof": 7.62,
    "assigned_at": null,
    "disbursement_start_date": "2026-04-07",
    "disbursement_end_date": "2026-04-07",
    "issue_date": "2026-04-07",
    "requester_identifier_key": "d1905ef5-19df-4183-bf0e-802b8229933c",
    "installments": [
        {
            "business_due_date": "2026-05-07",
            "due_date": "2026-05-07",
            "calendar_days": 30,
            "due_interest": 0,
            "due_principal": 1007.62,
            "fine_amount": 0,
            "has_interest": true,
            "post_fixed_amount": 0,
            "pre_fixed_amount": 52.4,
            "principal_amortization_amount": 491.49,
            "tax_amount": 1.21,
            "total_amount": 543.89,
            "workdays": 20,
            "accrual_reference_date": null,
            "advanced_paid_amount": 0,
            "bank_slip_key": null,
            "digitable_line": null,
            "installment_key": "1dea396f-beb1-4df3-9822-35800b4c095a",
            "installment_status": "opened",
            "installment_type": "principal",
            "original_due_principal": 1007.62,
            "original_pre_fixed_amount": 52.4,
            "original_principal_amortization_amount": 491.49,
            "paid_amount": 0,
            "original_total_amount": 543.89,
            "qr_code_key": null,
            "qr_code_url": null,
            "renegotiation_proposal_key": null,
            "total_accrual_amount": 0,
            "total_paid_amount": 0,
            "installment_number": 1,
            "paid_at": null,
            "updated_at": "2026-04-07T23:59:27",
            "principal_amortization_payment_amount": 0,
            "prefixed_interest_payment_amount": 0
        },
        {
            "business_due_date": "2026-06-08",
            "due_date": "2026-06-07",
            "calendar_days": 31,
            "due_interest": 0,
            "due_principal": 516.1296159,
            "fine_amount": 0,
            "has_interest": true,
            "post_fixed_amount": 0,
            "pre_fixed_amount": 27.76,
            "principal_amortization_amount": 516.13,
            "tax_amount": 2.58,
            "total_amount": 543.89,
            "workdays": 20,
            "accrual_reference_date": null,
            "advanced_paid_amount": 0,
            "bank_slip_key": null,
            "digitable_line": null,
            "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999",
            "installment_status": "opened",
            "installment_type": "principal",
            "original_due_principal": 516.13,
            "original_pre_fixed_amount": 27.76,
            "original_principal_amortization_amount": 516.13,
            "paid_amount": 0,
            "original_total_amount": 543.89,
            "qr_code_key": null,
            "qr_code_url": null,
            "renegotiation_proposal_key": null,
            "total_accrual_amount": 0,
            "total_paid_amount": 0,
            "installment_number": 2,
            "paid_at": null,
            "updated_at": "2026-04-07T23:59:27",
            "principal_amortization_payment_amount": 0,
            "prefixed_interest_payment_amount": 0
        }
    ],
    "first_due_date": "2026-05-07",
    "requester_key": "78287247-947d-4730-9bd1-7efb068175b6",
    "contract_number": "DWF1761222116",
    "credit_operation_status_enumerator": "opened",
    "operation_type_enumerator": "structured_operation",
    "disbursement_date": "2026-04-07",
    "issuer_name": "Dante Ferrarini",
    "issuer_document_number": "31057466093",
    "external_contract_fees": [
        {
            "amount_type": "absolute",
            "fee_amount": 0,
            "tax_amount": 0,
            "irrf_amount": 0,
            "amount": 0,
            "pis_amount": 0,
            "amount_released": 0,
            "fee_type": "tac",
            "cofins_amount": 0,
            "csll_amount": 0,
            "description": null,
            "net_fee_amount": 0,
            "rebate_account": null
        }
    ],
    "cet": 5.82,
    "annual_cet": 97.05,
    "final_disbursement_amount": 1000,
    "number_of_installments": 2,
    "disbursement_issue_amount": 1000,
    "prefixed_interest_rate": {
        "annual_rate": 0.8373372409,
        "daily_rate": 0.0016911989,
        "interest_base": {
            "enumerator": "calendar_days",
            "year_days": 360
        },
        "monthly_rate": 0.052
    },
    "fine_configuration": {
        "contract_fine_rate": 0.02,
        "fine_delay_rate": {
            "annual_rate": 0.12682503,
            "daily_rate": 0.00033173,
            "interest_base": {
                "enumerator": "calendar_days",
                "year_days": 360
            },
            "monthly_rate": 0.01
        }
    },
    "attached_documents": [
        {
            "document_key": "d6705fc4-80e0-4c8e-9aff-f3875024e6a4",
            "document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/...",
            "signature_url": "https://storage.googleapis.com/sandbox-doc-api/documents/..._signed.pdf",
            "document_type": "ccb_pre_price_days",
            "signature_required": true,
            "signed": true
        }
    ],
    "related_parties": [
        {
            "related_party_key": "24fac77e-7782-4f72-b31a-daee288e34ed",
            "role_type": "issuer",
            "person_type": "natural",
            "name": "Dante Ferrarini",
            "email": "",
            "individual_document_number": "31057466093"
        }
    ],
    "base_iof": 3.79,
    "additional_iof": 3.83,
    "assignment_amount": 1010.64,
    "created_at": "2026-04-07T23:59:22Z",
    "total_prefixed_amount": 80.16
}
```

STATUS 400

Response Body

```json
{
    "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

---

## Consultar Eventos da Operação

Você também pode consultar o histórico de eventos (log de status) da operação:

ENDPOINT /v2/credit_operation/ CREDIT-OPERATION-KEY /events
MÉTODO GET

Testar no Playground

### Path Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `credit_operation_key`* | string | Chave da operação de crédito | UUID |

### Response

STATUS 200

Response Body

```json
{
    "data": [
        {
            "status": "waiting_signature",
            "reason": null,
            "cancel_reason": null,
            "event_date": "2026-03-13T17:19:59Z"
        },
        {
            "status": "issued",
            "reason": null,
            "cancel_reason": null,
            "event_date": "2026-03-13T17:19:59Z"
        },
        {
            "status": "waiting_disbursement",
            "reason": null,
            "cancel_reason": null,
            "event_date": "2026-03-13T17:19:59Z"
        },
        {
            "status": "opened",
            "reason": null,
            "cancel_reason": null,
            "event_date": "2026-03-13T17:19:59Z"
        }
    ],
    "pagination": {
        "current_page": 1,
        "next_page": null,
        "rows_per_page": 10
    }
}
```

### Enumeradores de Status da Operação

| Status | Descrição |
|---|---|
| `waiting_signature` | Aguardando assinatura do contrato |
| `issued` | Operação emitida |
| `waiting_disbursement` | Aguardando desembolso |
| `opened` | Operação aberta (desembolso realizado) |
| `canceled` | Operação cancelada |
| `settled` | Operação liquidada (todas as parcelas pagas) |

---

# Consulta de Cessão

URL: /documentation/manual_credito_clean/emissao/consulta_cessao

## Resumo

A cessão é o processo pelo qual as operações de crédito (itens) são transferidas para um cessionário. Você pode acompanhar e consultar as cessões a qualquer momento para obter informações ou verificar o status atual do processo.

## Webhook de Confirmação de Cessão

Este webhook é disparado para notificar o cliente de que o processo de cessão foi iniciado. Ele fornece os metadados essenciais necessários para acompanhar a cessão.

Response Body

```json
{
    "key": "19e34186-847b-4dd7-9fc2-d14e28bc2f10",
    "data": {
        "status": "settled",
        "total_amount": 1917.04,
        "assignment_key": "19e34186-847b-4dd7-9fc2-d14e28bc2f10",
        "reference_date": "2026-04-10",
        "number_of_items": 8,
        "term_of_assignment_url": null
    },
    "webhook_type": "assignment.status_change",
    "event_datetime": "2026-04-10T22:37:52"
}
```

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `assignment_key` | string | Identificador único da operação de cessão | 36 |
| `term_of_assignment_url` | string | URL para download do Termo de Cessão (PDF) | 2048 |
| `number_of_items` | integer | Número total de operações de crédito (itens) incluídas nesta cessão | 5 |
| `total_amount` | float | Soma do valor presente de todos os itens da cessão | 15,2 |
| `reference_date` | string | Data base utilizada para os cálculos da cessão (YYYY-MM-DD) | 10 |

---

## Consultar uma Cessão Específica

Para consultar uma cessão específica, o cliente pode realizar uma requisição GET no endpoint utilizando a chave identificadora da cessão (`assignment_key`).

ENDPOINT /v2/assignment/ ASSIGNMENT-KEY
MÉTODO GET

Testar no Playground

### Path Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `assignment_key`* | string | Chave identificadora única da cessão | UUID |

### Response

STATUS 200

Response Body

```json
{
    "assignment_key": "77997168-5d61-430f-b5ae-08eb3d7b8c0e",
    "creation_datetime": "2023-10-01T12:00:00",
    "reference_date": "2023-10-01",
    "total_amount": 120000,
    "number_of_items": 5,
    "term_of_assignment_url": "https://example.com/assignment.pdf",
    "status": "settled",
    "signable_term_url": "https://example.com/signable_term.pdf"
}
```

---

## Consultar os Itens (Contratos) de uma Cessão

Para consultar os contratos contidos em uma cessão, utilize uma requisição GET no endpoint com a mesma `assignment_key`.

ENDPOINT /v2/assignment/ ASSIGNMENT-KEY /assignment_items?page=1&page_size=100
MÉTODO GET

Testar no Playground

### Path Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `assignment_key`* | string | Chave identificadora única da cessão | UUID |

### Query Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `page` | string | Número da página | - |
| `page_size` | string | Tamanho da página, limitado a 100 | - |

### Response

A resposta é uma lista paginada contendo as informações de cada contrato da cessão (status 200):

STATUS 200

Response Body

```json
{
    "pagination": {
        "page": 1,
        "page_size": 10
    },
    "data": [
        {
            "assignment_date": "2026-04-10",
            "assignment_item_key": "uuid",
            "contract_number": "TIK000012312",
            "control_number": "TIK000012312",
            "requester_identifier_key": "uuid",
            "credit_operation_key": "string",
            "disbursed_amount": 80.0,
            "disbursement_date": "2026-04-10",
            "endorsement_url": "url",
            "issue_amount": 180.00,
            "issuer_document_number": "string",
            "issuer_name": "string",
            "number_of_installments": 10,
            "present_amount": 180.0,
            "contract_present_amount": 180.0,
            "purchaser_document_number": "string",
            "status": "settled",
            "rejected_reasons": [],
            "assignment_items": [
                {
                    "installment_key": "uuid",
                    "present_amount": 100,
                    "due_date": "2026-05-10",
                    "your_number": "TIK000012312001"
                },
                {
                    "installment_key": "uuid",
                    "present_amount": 80,
                    "due_date": "2026-06-10",
                    "your_number": "TIK000012312002"
                }
            ]
        }
    ]
}
```

---

## Consultar Lotes de Cessão por Data

Consulte os lotes de cessão pela data de referência (`reference_date`).

ENDPOINT /v2/assignment/assignments?reference_date=2026-05-15
MÉTODO GET

Testar no Playground

### Query Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `reference_date` | string | Data da tentativa de cessão (YYYY-MM-DD) | 10 |

### Response

STATUS 200

Response Body

```json
{
    "data": [
        {
            "assignment_key": "439b1257-82ac-4741-a416-a4428a9a7327",
            "number_of_items": 10000,
            "reference_date": "2025-01-01",
            "signable_term_url": "https://example.com/endorsement.pdf",
            "status": "settled",
            "term_of_assignment_url": "signed_url",
            "total_amount": 100.00
        },
        {
            "assignment_key": "439b1257-82ac-4741-a416-a4428a9a7327",
            "number_of_items": 10000,
            "reference_date": "2025-01-01",
            "signable_term_url": "https://example.com/endorsement.pdf",
            "status": "settled",
            "term_of_assignment_url": "signed_url",
            "total_amount": 100.00
        },
        {
            "assignment_key": "439b1257-82ac-4741-a416-a4428a9a7327",
            "number_of_items": 10000,
            "reference_date": "2025-01-01",
            "signable_term_url": "https://example.com/endorsement.pdf",
            "status": "canceled",
            "term_of_assignment_url": "signed_url",
            "total_amount": 100.00
        }
    ]
}
```

---

# Emissão Crédito Clean

URL: /documentation/manual_credito_clean/emissao/

## Resumo

O Crédito Clean oferece **dois fluxos de emissão**:

| Fluxo | Endpoints | Quando usar |
|---|---|---|
| **Emissão com Assinatura Imediata** | `POST /signed_debt` | A assinatura do tomador é coletada pelo parceiro e enviada junto com a emissão em uma única chamada via opt-in |
| **Emissão com Assinatura Posterior** | `POST /debt` → `POST /debt/{debt_key}/signed` | A dívida é criada primeiro e a assinatura é enviada em uma chamada separada |

---

# Emissão com Assinatura Posterior

URL: /documentation/manual_credito_clean/emissao/emissao_dois_passos

Neste fluxo, a dívida é criada em uma primeira chamada e a assinatura do tomador é enviada em uma chamada separada. O sistema gera o contrato e aguarda a assinatura antes de processar o desembolso.

---

## Passo 1 — Criação da Dívida (`POST /debt`)

### Request

ENDPOINT /debt
MÉTODO POST

Request Body

**disbursed_amount**

```json
{
    "borrower": {
        "name": "Dante Ferrarini",
        "email": "dante@email.com",
        "phone": {
            "number": "185633631",
            "area_code": "15",
            "country_code": "055"
        },
        "is_pep": false,
        "address": {
            "city": "São Paulo",
            "state": "SP",
            "number": "1000",
            "street": "Rua Gilberto Sabino",
            "complement": "",
            "postal_code": "05425020",
            "neighborhood": "Pinheiros"
        },
        "role_type": "issuer",
        "birth_date": "1993-09-10",
        "person_type": "natural",
        "individual_document_number": "31057466093"
    },
    "financial": {
        "interest_type": "pre_price_days",
        "disbursement_date": "2026-04-07",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "disbursed_amount": 1000,
        "monthly_interest_rate": 0.052,
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "number_of_installments": 2,
        "principal_grace_period": 0
    },
    "disbursement_bank_account": {
        "name": "Dante Ferrarini",
        "document_number": "31057466093",
        "bank_code": "329",
        "branch_number": "0001",
        "account_number": "7617846",
        "account_digit": "5",
        "account_type": "checking_account"
    },
    "purchaser_document_number": "32402502000135"
}
```

**installments**

```json
{
    "borrower": {
        "name": "Dante Ferrarini",
        "email": "dante@email.com",
        "phone": {
            "number": "185633631",
            "area_code": "15",
            "country_code": "055"
        },
        "is_pep": false,
        "address": {
            "city": "São Paulo",
            "state": "SP",
            "number": "1000",
            "street": "Rua Gilberto Sabino",
            "complement": "",
            "postal_code": "05425020",
            "neighborhood": "Pinheiros"
        },
        "role_type": "issuer",
        "birth_date": "1993-09-10",
        "person_type": "natural",
        "individual_document_number": "31057466093"
    },
    "financial": {
        "interest_type": "pre_price_days",
        "disbursement_date": "2026-04-07",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "monthly_interest_rate": 0.052,
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0,
        "desired_installments": [
            {
                "due_date": "2026-05-07",
                "total_amount": 543.89
            },
            {
                "due_date": "2026-06-07",
                "total_amount": 543.89
            }
        ]
    },
    "disbursement_bank_account": {
        "name": "Dante Ferrarini",
        "document_number": "31057466093",
        "bank_code": "329",
        "branch_number": "0001",
        "account_number": "7617846",
        "account_digit": "5",
        "account_type": "checking_account"
    },
    "purchaser_document_number": "32402502000135"
}
```

**due_dates**

```json
{
    "borrower": {
        "name": "Dante Ferrarini",
        "email": "dante@email.com",
        "phone": {
            "number": "185633631",
            "area_code": "15",
            "country_code": "055"
        },
        "is_pep": false,
        "address": {
            "city": "São Paulo",
            "state": "SP",
            "number": "1000",
            "street": "Rua Gilberto Sabino",
            "complement": "",
            "postal_code": "05425020",
            "neighborhood": "Pinheiros"
        },
        "role_type": "issuer",
        "birth_date": "1993-09-10",
        "person_type": "natural",
        "individual_document_number": "31057466093"
    },
    "financial": {
        "interest_type": "pre_price_days",
        "disbursement_date": "2026-04-07",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "disbursed_amount": 1000,
        "monthly_interest_rate": 0.052,
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0,
        "due_dates": [
            "2026-05-07",
            "2026-06-07"
        ]
    },
    "disbursement_bank_account": {
        "name": "Dante Ferrarini",
        "document_number": "31057466093",
        "bank_code": "329",
        "branch_number": "0001",
        "account_number": "7617846",
        "account_digit": "5",
        "account_type": "checking_account"
    },
    "purchaser_document_number": "32402502000135"
}
```

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| **borrower*** | object | Objeto do tomador | **[Objeto Borrower](#objeto-borrower)** |
| **financial*** | object | Detalhes financeiros da operação | **[Objeto Financial](#objeto-financial)** |
| **disbursement_bank_account*** | object | Dados da conta bancária do tomador para recebimento do desembolso | **[Objeto Disbursement Bank Account](#objeto-disbursement-bank-account)** |
| **purchaser_document_number*** | string | CNPJ do cessionário | 14 |

### Objeto Borrower

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| name* | string | Nome completo do tomador | 100 |
| email | string | Endereço de e-mail do tomador | 254 |
| phone | object | Dados de telefone do tomador | **[Objeto Phone](#objeto-phone)** |
| is_pep* | boolean | Indicador de Pessoa Politicamente Exposta | 5 |
| address* | object | Endereço residencial do tomador | **[Objeto Address](#objeto-address)** |
| role_type | string | Papel do tomador na operação (ex: "issuer") | 10 |
| birth_date* | date | Data de nascimento do tomador (Formato: "YYYY-MM-DD") | 10 |
| person_type* | string | Classificação da pessoa (natural ou legal) | 7 |
| individual_document_number* | string | CPF do tomador - somente números | 11 |

### Objeto Address

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| city* | string | Nome da cidade | 100 |
| state* | string | Sigla do estado (duas letras maiúsculas) | 2 |
| number | string | Número do logradouro | 10 |
| street* | string | Nome do logradouro | 100 |
| complement | string | Complemento do endereço (texto livre) | 100 |
| postal_code* | string | CEP - somente números | 8 |
| neighborhood* | string | Nome do bairro | 100 |

### Objeto Phone

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| number* | string | Número do telefone | 9 |
| area_code* | string | Código de área (DDD) | 2 |
| country_code* | string | Código internacional (ex: "055") | 3 |

### Objeto Financial

:::info Formas de definir o valor da operação
É possível definir o valor da operação de três formas mutuamente exclusivas:
- **`disbursed_amount` + `monthly_interest_rate` + `number_of_installments`**: informe o valor a ser desembolsado, a taxa de juros e o número de parcelas — o sistema calcula o valor de cada parcela.
- **`desired_installments`**: informe um array com a data e o valor total de cada parcela individualmente — o sistema calcula o valor de desembolso.
- **`disbursed_amount` + `due_dates`**: informe o valor de desembolso e um array com as datas de vencimento — o sistema calcula os valores das parcelas para a agenda irregular informada.
:::

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| interest_type* | string | Método de amortização | 20 |
| disbursement_date* | string | Data de desembolso | 10 |
| fine_configuration* | object | Configuração de multa e mora | **[Objeto Fine Configuration](#objeto-fine-configuration)** |
| monthly_interest_rate* | float | Taxa de juros mensal | 10,6 |
| disbursed_amount | float | Valor a ser desembolsado. Obrigatório se `desired_installments` não for informado | 15,2 |
| number_of_installments | integer | Número de parcelas. Obrigatório se `disbursed_amount` for informado sem `due_dates` | 3 |
| desired_installments | array | Array de parcelas com data e valor definidos individualmente. Obrigatório se `disbursed_amount` não for informado | **[Objeto Desired Installments](#objeto-desired-installments)** |
| due_dates | array | Lista de datas de vencimento (YYYY-MM-DD). Utilizado com `disbursed_amount` para agenda de parcelas irregular | - |
| credit_operation_type* | string | Tipo da operação de crédito (ex: "ccb") | 10 |
| interest_grace_period | integer | Período de carência de juros (em meses) | 3 |
| principal_grace_period | integer | Período de carência do principal (em meses) | 3 |

### Objeto Desired Installments

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| due_date* | string | Data de vencimento da parcela (YYYY-MM-DD) | 10 |
| total_amount* | float | Valor total da parcela | 15,2 |

### Objeto Fine Configuration

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| monthly_rate* | float | Taxa de mora mensal | 10,6 |
| interest_base* | string | Base de cálculo da mora (ex: "calendar_days") | 20 |
| contract_fine_rate* | float | Taxa de multa contratual | 10,6 |

### Objeto Disbursement Bank Account

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| name | string | Nome do titular da conta | 50 |
| document_number | string | CPF do titular da conta | 11 |
| bank_code* | string | Código COMPE da instituição financeira | 3 |
| branch_number* | string | Número da agência (sem dígito verificador) | 4 |
| account_number* | string | Número da conta (sem dígito verificador) | 10 |
| account_digit* | string | Dígito verificador da conta (usar zero no lugar de letras) | 1 |
| account_type | enum | Tipo da conta (`checking_account`, `saving_account`, `payment_account`, etc.) | - |

### Response

STATUS 200

A resposta retorna o plano de pagamento e a **DEBT-KEY**, com status `waiting_signature`. O desembolso não é realizado até que a assinatura seja enviada no Passo 2.

Response Body

```json
{
    "webhook_type": "debt",
    "key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
    "status": "waiting_signature",
    "event_datetime": "2026-04-07 22:46:10",
    "data": {
        "borrower": {
            "name": "Dante Ferrarini",
            "document_number": "31057466093",
            "related_party_key": "d5cbcada-42e7-4d5b-84fc-3c2dc8038411"
        },
        "contract": {
            "number": "0000192840/DWF",
            "urls": [
                "https://storage.googleapis.com/sandbox-doc-api/documents/b2d974f9-c710-42e3-8ea4-69cc31561c38/CCB-0000192840-20260407.pdf"
            ],
            "signers": [
                {
                    "signer_name": "Dante Ferrarini",
                    "signer_document_number": "31057466093",
                    "signer_role": "issuer",
                    "signer_email": "dante@email.com",
                    "signer_external_key": null,
                    "signature_url": null
                }
            ]
        },
        "installments": [...],
        "total_pre_fixed_amount": 80.16
    }
}
```

:::caution Atenção
Salve a **DEBT-KEY** retornada — ela é necessária para enviar a assinatura no Passo 2.
:::

---

## Passo 2 — Envio da Assinatura (`POST /debt/{DEBT-KEY}/signed`)

### Request

ENDPOINT /debt/ DEBT-KEY /signed
MÉTODO POST

Request Body

```json
{
    "type": "data_signature",
    "signatures": [
        {
            "signed_object": {
                "raw_text": "Lorem ipsum dolor sit amet, consectetur a...."
            },
            "authenticity": {
                "timestamp": "1970-01-01 00:00:01",
                "ip_address": "179.104.42.245",
                "session_id": "ddb1d063-4fdf-4330-af9c-3316e9142ff3"
            },
            "signer": {
                "name": "Dante Ferrarini",
                "email": "dante@email.com",
                "phone": {
                    "country_code": "055",
                    "area_code": "15",
                    "number": "185633631"
                },
                "document_number": "31057466093"
            },
            "authentication_type": "opt-in"
        }
    ]
}
```

### Path Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `debt_key`* | string | Chave da dívida retornada no Passo 1 | UUID |

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `type`* | string | Tipo de assinatura. Valor: `data_signature` | - |
| `signatures`* | array | Lista de objetos de comprovação de assinatura | **[Objeto signatures](#objeto-signatures)** |

### Objeto signatures

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `signed_object` | object | Documento que está sendo assinado | **[Objeto signed_object](#objeto-signed_object)** |
| `authenticity` | object | Dados de autenticação da assinatura | **[Objeto authenticity](#objeto-authenticity)** |
| `signer` | object | Dados do assinante | **[Objeto signer](#objeto-signer)** |
| `authentication_type`* | string | Tipo de assinatura. Valor: `opt-in` | - |

### Objeto signed_object

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `raw_text`* | string | Texto corrido com os dados do contrato que será assinado | - |

### Objeto authenticity

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `timestamp`* | string | Data e hora da assinatura | - |
| `ip_address`* | string | Endereço IP onde o aceite foi coletado | - |
| `session_id`* | string | ID de sessão do cliente no momento da assinatura — deve ser armazenado por no mínimo 5 anos | - |
| `geolocation` | object | Geolocalização opcional | - |

### Objeto signer

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `name`* | string | Nome do assinante | - |
| `email`* | string | E-mail do assinante | - |
| `phone` | object | Telefone do assinante | **[Objeto Phone](#objeto-phone)** |
| `document_number`* | string | CPF do assinante | - |

### Response

STATUS 200

Response Body

```json
{
    "data": {},
    "event_datetime": "2026-04-07 15:24:47",
    "key": "<DEBT-KEY>",
    "status": "signature_received",
    "webhook_type": "debt"
}
```

---

# Emissão com Assinatura Imediata (/signed_debt)

URL: /documentation/manual_credito_clean/emissao/emissao_signed_debt

Este endpoint realiza a emissão da dívida e processa a assinatura do contrato via opt-in em uma única chamada. O desembolso ocorre na data informada no campo `disbursement_date`, que pode ser diferente da data de emissão. Não é necessário pré-cadastro; basta fornecer os dados do tomador durante a requisição de emissão.

## Request

ENDPOINT /signed_debt
MÉTODO POST

Testar no Playground

Request Body

**disbursed_amount**

```json
{
    "borrower": {
        "name": "Dante Ferrarini",
        "email": "",
        "phone": {
            "number": "185633631",
            "area_code": "15",
            "country_code": "086"
        },
        "is_pep": false,
        "address": {
            "city": "São Paulo",
            "state": "SP",
            "number": "",
            "street": "Rua Gilberto Sabino",
            "postal_code": "05425020",
            "neighborhood": "Pinheiros",
            "complement": ""
        },
        "role_type": "issuer",
        "birth_date": "1993-09-10",
        "person_type": "natural",
        "attached_documents_list": [
            {
                "selfie": "250e7e95-57c8-40bd-a0cd-0be8eb172916"
            }
        ],
        "individual_document_number": "31057466093"
    },
    "financial": {
        "interest_type": "pre_price_days",
        "disbursement_date": "2026-04-07",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "disbursed_amount": 1000,
        "monthly_interest_rate": 0.052,
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "number_of_installments": 2,
        "principal_grace_period": 0
    },
    "simplified": true,
    "additional_data": {
        "contract": {
            "contract_number": "DWF1761222116",
            "signatures": [
                {
                    "signer": {
                        "name": "Dante Ferrarini",
                        "email": "",
                        "phone": {
                            "number": "185633631",
                            "area_code": "15",
                            "country_code": "086"
                        },
                        "document_number": "31057466093"
                    },
                    "signature": {
                        "timestamp": "28-01-2026 06:36:35",
                        "ip_address": "192.168.1.1",
                        "signature_file": {
                            "file_url": "https://qitech.com.br/signature.pdf",
                            "file_type": "pdf"
                        }
                    }
                }
            ]
        }
    },
    "requester_identifier_key": "d1905ef5-19df-4183-bf0e-802b8229933c",
    "purchaser_document_number": "32402502000135",
    "disbursement_bank_accounts": [
        {
            "name": "Dante Ferrarini",
            "ispb_number": "32402502",
            "account_digit": "5",
            "branch_number": "0001",
            "account_number": "7617846",
            "document_number": "31057466093",
            "percentage_receivable": 100
        }
    ]
}
```

**installments**

```json
{
    "borrower": {
        "name": "Dante Ferrarini",
        "email": "",
        "phone": {
            "number": "185633631",
            "area_code": "15",
            "country_code": "086"
        },
        "is_pep": false,
        "address": {
            "city": "São Paulo",
            "state": "SP",
            "number": "",
            "street": "Rua Gilberto Sabino",
            "postal_code": "05425020",
            "neighborhood": "Pinheiros",
            "complement": ""
        },
        "role_type": "issuer",
        "birth_date": "1993-09-10",
        "person_type": "natural",
        "attached_documents_list": [
            {
                "selfie": "250e7e95-57c8-40bd-a0cd-0be8eb172916"
            }
        ],
        "individual_document_number": "31057466093"
    },
    "financial": {
        "interest_type": "pre_price_days",
        "disbursement_date": "2026-04-07",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "monthly_interest_rate": 0.052,
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0,
        "desired_installments": [
            {
                "due_date": "2026-05-07",
                "total_amount": 543.89
            },
            {
                "due_date": "2026-06-07",
                "total_amount": 543.89
            }
        ]
    },
    "simplified": true,
    "additional_data": {
        "contract": {
            "contract_number": "DWF1761222116",
            "signatures": [
                {
                    "signer": {
                        "name": "Dante Ferrarini",
                        "email": "",
                        "phone": {
                            "number": "185633631",
                            "area_code": "15",
                            "country_code": "086"
                        },
                        "document_number": "31057466093"
                    },
                    "signature": {
                        "timestamp": "28-01-2026 06:36:35",
                        "ip_address": "192.168.1.1",
                        "signature_file": {
                            "file_url": "https://qitech.com.br/signature.pdf",
                            "file_type": "pdf"
                        }
                    }
                }
            ]
        }
    },
    "requester_identifier_key": "d1905ef5-19df-4183-bf0e-802b8229933c",
    "purchaser_document_number": "32402502000135",
    "disbursement_bank_accounts": [
        {
            "name": "Dante Ferrarini",
            "ispb_number": "32402502",
            "account_digit": "5",
            "branch_number": "0001",
            "account_number": "7617846",
            "document_number": "31057466093",
            "percentage_receivable": 100
        }
    ]
}
```

**due_dates**

```json
{
    "borrower": {
        "name": "Dante Ferrarini",
        "email": "",
        "phone": {
            "number": "185633631",
            "area_code": "15",
            "country_code": "086"
        },
        "is_pep": false,
        "address": {
            "city": "São Paulo",
            "state": "SP",
            "number": "",
            "street": "Rua Gilberto Sabino",
            "postal_code": "05425020",
            "neighborhood": "Pinheiros",
            "complement": ""
        },
        "role_type": "issuer",
        "birth_date": "1993-09-10",
        "person_type": "natural",
        "attached_documents_list": [
            {
                "selfie": "250e7e95-57c8-40bd-a0cd-0be8eb172916"
            }
        ],
        "individual_document_number": "31057466093"
    },
    "financial": {
        "interest_type": "pre_price_days",
        "disbursement_date": "2026-04-07",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "disbursed_amount": 1000,
        "monthly_interest_rate": 0.052,
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0,
        "due_dates": [
            "2026-05-07",
            "2026-06-07"
        ]
    },
    "simplified": true,
    "additional_data": {
        "contract": {
            "contract_number": "DWF1761222116",
            "signatures": [
                {
                    "signer": {
                        "name": "Dante Ferrarini",
                        "email": "",
                        "phone": {
                            "number": "185633631",
                            "area_code": "15",
                            "country_code": "086"
                        },
                        "document_number": "31057466093"
                    },
                    "signature": {
                        "timestamp": "28-01-2026 06:36:35",
                        "ip_address": "192.168.1.1",
                        "signature_file": {
                            "file_url": "https://qitech.com.br/signature.pdf",
                            "file_type": "pdf"
                        }
                    }
                }
            ]
        }
    },
    "requester_identifier_key": "d1905ef5-19df-4183-bf0e-802b8229933c",
    "purchaser_document_number": "32402502000135",
    "disbursement_bank_accounts": [
        {
            "name": "Dante Ferrarini",
            "ispb_number": "32402502",
            "account_digit": "5",
            "branch_number": "0001",
            "account_number": "7617846",
            "document_number": "31057466093",
            "percentage_receivable": 100
        }
    ]
}
```

### Detalhes do Request Body

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| **borrower*** | object | Objeto do tomador - O devedor da operação de crédito | **[Objeto Borrower](#objeto-borrower)** |
| **financial*** | object | Contém todos os detalhes financeiros e parâmetros de cálculo da operação | **[Objeto Financial](#objeto-financial)** |
| **simplified** | boolean | Se verdadeiro, utiliza o fluxo simplificado de emissão | - |
| **additional_data*** | object | Dados adicionais do contrato, incluindo assinaturas | **[Objeto Additional Data](#objeto-additional-data)** |
| **requester_identifier_key** | string | Chave identificadora do solicitante | UUID |
| **purchaser_document_number*** | string | CNPJ do cessionário – O comprador da operação de crédito (FIDC) | 14 |
| **disbursement_bank_accounts*** | array | Dados da conta bancária do tomador para recebimento do desembolso | **[Objeto Disbursement Bank Account](#objeto-disbursement-bank-account)** |

### Objeto Borrower

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| name* | string | Nome completo do tomador | 100 |
| email | string | Endereço de e-mail do tomador | 254 |
| phone | object | Dados de telefone do tomador | **[Objeto Phone](#objeto-phone)** |
| is_pep* | boolean | Indicador de Pessoa Politicamente Exposta | 5 |
| address* | object | Endereço residencial do tomador | **[Objeto Address](#objeto-address)** |
| role_type | string | Papel do tomador na operação (ex: "issuer") | 10 |
| birth_date* | date | Data de nascimento do tomador (Formato: "YYYY-MM-DD") | 10 |
| person_type* | string | Classificação da pessoa (natural ou legal) | 7 |
| attached_documents_list | array | Lista de documentos anexados (ex: selfie) | **[Objeto Attached Documents](#objeto-attached-documents)** |
| individual_document_number* | string | CPF do tomador - somente números | 11 |

### Objeto Attached Documents

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| selfie | string | DOCUMENT_KEY do documento de selfie enviado via upload | UUID |

### Objeto Address

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| city* | string | Nome da cidade | 100 |
| state* | string | Sigla do estado (duas letras maiúsculas) | 2 |
| number | string | Número do logradouro | 10 |
| street* | string | Nome do logradouro | 100 |
| complement | string | Complemento do endereço (texto livre) | 100 |
| postal_code* | string | CEP - somente números | 8 |
| neighborhood* | string | Nome do bairro | 100 |

### Objeto Phone

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| number* | string | Número do telefone | 9 |
| area_code* | string | Código de área (DDD) | 2 |
| country_code* | string | Código internacional (ex: "055") | 3 |

### Objeto Financial

:::info Formas de definir o valor da operação
É possível definir o valor da operação por meio das seguintes combinações mutuamente exclusivas (informe **uma e somente uma** das chaves de valor, junto com os demais campos obrigatórios):
- **`disbursed_amount` + `monthly_interest_rate` + `number_of_installments`**: informe o valor líquido a ser desembolsado, a taxa de juros e o número de parcelas — o sistema calcula o valor de cada parcela.
- **`amount` + `monthly_interest_rate` + `number_of_installments`**: informe o valor bruto (com IOF) da operação — o sistema calcula o desembolso líquido e o valor de cada parcela.
- **`final_disbursement_amount` + `monthly_interest_rate` + `number_of_installments`**: informe o valor final que deve chegar ao destinatário e o sistema infla o `issue_amount` para cobrir o IOF.
- **`installment_face_value` + `number_of_installments` + (`disbursed_amount` ou `amount`)**: informe o valor desejado por parcela; quando essa combinação é usada **sem** `monthly_interest_rate`, o sistema assume taxa zero.
- **`desired_installments`**: informe um array com a data e o valor total de cada parcela individualmente — o sistema calcula o valor de desembolso.
- **`disbursed_amount` + `due_dates`**: informe o valor de desembolso e um array com as datas de vencimento — o sistema calcula os valores das parcelas para a agenda irregular informada.
:::

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| interest_type* | string | Método de amortização | 20 |
| disbursement_date* | string | Data de desembolso | 10 |
| first_due_date | string | Data de vencimento da primeira parcela (YYYY-MM-DD) | 10 |
| limit_days_to_disburse | integer | Quantidade de dias após `disbursement_date` em que o desembolso ainda pode ocorrer | 3 |
| fine_configuration* | object | Configuração de multa e mora | **[Objeto Fine Configuration](#objeto-fine-configuration)** |
| monthly_interest_rate | float | Taxa de juros mensal. Opcional quando `installment_face_value` é utilizado | 10,6 |
| annual_interest_rate | float | Taxa de juros anual (alternativa a `monthly_interest_rate`) | 10,6 |
| daily_interest_rate | float | Taxa de juros diária (alternativa a `monthly_interest_rate`) | 10,6 |
| disbursed_amount | float | Valor líquido a ser desembolsado | 15,2 |
| amount | float | Valor bruto da operação (`issue_amount`) — inclui IOF | 15,2 |
| final_disbursement_amount | float | Valor final a chegar no destinatário — sistema infla o `issue_amount` para cobrir IOF | 15,2 |
| installment_face_value | float | Valor desejado de cada parcela | 15,2 |
| number_of_installments | integer | Número de parcelas | 3 |
| desired_installments | array | Array de parcelas com data e valor definidos individualmente | **[Objeto Desired Installments](#objeto-desired-installments)** |
| due_dates | array | Lista de datas de vencimento (YYYY-MM-DD). Utilizado com `disbursed_amount` para agenda de parcelas irregular | - |
| total_iof | float | Valor total do IOF — quando omitido, o sistema calcula automaticamente | 15,2 |
| credit_operation_type* | string | Tipo da operação de crédito (ex: "ccb") | 10 |
| interest_grace_period | integer | Período de carência de juros (em meses) | 3 |
| principal_grace_period | integer | Período de carência do principal (em meses) | 3 |

### Objeto Desired Installments

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| due_date* | string | Data de vencimento da parcela (YYYY-MM-DD) | 10 |
| total_amount* | float | Valor total da parcela | 15,2 |

### Objeto Fine Configuration

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| monthly_rate* | float | Taxa de mora mensal | 10,6 |
| interest_base* | string | Base de cálculo da mora (ex: "calendar_days") | 20 |
| contract_fine_rate* | float | Taxa de multa contratual | 10,6 |

### Objeto Disbursement Bank Account

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| name | string | Nome completo do titular da conta destino | 100 |
| document_number | string | CPF ou CNPJ do titular da conta destino | 11 ou 14 |
| transfer_method | string | Método de transferência. Valores: `pix`, `ted` (default: `pix`) | 3 |
| pix_transfer_type | string | Subtipo da transferência Pix. Valores: `manual`, `key`, `qrcode` | 6 |
| ispb_number | string | Código ISPB da instituição financeira | 8 |
| bank_code | string | Código COMPE da instituição financeira (alternativa a `ispb_number`) | 3 |
| branch_number | string | Número da agência (sem dígito verificador) | 4 |
| account_number | string | Número da conta (sem dígito verificador) | 19 |
| account_digit | string | Dígito verificador da conta (usar zero no lugar de letras) | 1 |
| account_type | string | Tipo da conta destino. Valores: `checking_account`, `saving_account`, `salary_account`, `payment_account`, `deposit_account`, `guaranteed_account`, `investment_account` | 20 |
| pix_key | string | Chave Pix do destinatário — obrigatório quando `pix_transfer_type` = `key` | - |
| qr_code_key | string | Chave UUID de um QR Code Pix já registrado — obrigatório quando `pix_transfer_type` = `qrcode` | 36 |
| qr_code_url | string | String EMV (copia-e-cola) do QR Code Pix — alternativa a `qr_code_key` | 250 |
| digitable_line | string | Linha digitável de boleto bancário — usado para desembolso por boleto | 47-48 |
| end_to_end_id | string | Identificador end-to-end do Pix (preenchido na resposta) | 32 |
| percentage_receivable | float | Percentual do desembolso destinado a esta conta. Obrigatório quando `amount_receivable` não é informado | 3 |
| amount_receivable | float | Valor fixo destinado a esta conta. Obrigatório quando `percentage_receivable` não é informado | 15,2 |

:::info Modos de desembolso suportados
A combinação de campos depende do `transfer_method` e do `pix_transfer_type`:
- **Conta interna QI Tech ou TED**: `bank_code`/`ispb_number` + `branch_number` + `account_number` + `account_digit` + `document_number` + `name` + `percentage_receivable`.
- **Pix manual**: `pix_transfer_type` = `manual` + dados de conta (igual ao TED).
- **Pix por chave**: `pix_transfer_type` = `key` + `pix_key`.
- **Pix por QR Code (registrado)**: `pix_transfer_type` = `qrcode` + `qr_code_key`.
- **Pix por QR Code (copia-e-cola)**: `qr_code_url` + `transfer_method` = `pix`.
- **Pagamento de boleto**: `digitable_line` + `amount_receivable`.
:::

### Objeto Additional Data

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| contract* | object | Dados do contrato | **[Objeto Contract](#objeto-contract)** |

### Objeto Contract

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| contract_number* | string | Número identificador único do contrato | 20 |
| signatures* | array | Lista de objetos de evidência de assinatura digital (Opt-in) | **[Objeto Signature](#objeto-signature)** |

### Objeto Signature

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| signer* | object | Dados de identificação do assinante | **[Objeto Signer](#objeto-signer)** |
| signature* | object | Dados de evidência da assinatura digital | **[Objeto Signature Details](#objeto-signature-details)** |

### Objeto Signer

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| name* | string | Nome completo do assinante | 255 |
| document_number* | string | CPF do assinante | 11 |
| email | string | E-mail do assinante | 100 |
| phone | object | Dados de telefone do assinante | **[Objeto Phone](#objeto-phone)** |

### Objeto Signature Details

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| ip_address* | string | Endereço IP utilizado na assinatura | 45 |
| timestamp* | string | Data e hora da assinatura (ISO 8601: YYYY-MM-DDTHH:mm:ssZ) | 24 |
| signature_file* | object | Arquivo da assinatura digital | **[Objeto Signature File](#objeto-signature-file)** |

### Objeto Signature File

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| file_url* | string | Link direto para o documento do contrato assinado (PDF) | 2048 |
| file_type* | string | Formato do arquivo de assinatura (ex: "pdf") | 4 |

## Response

A resposta à requisição de emissão retornará o plano de pagamento e uma **DEBT-KEY**, que é o identificador da dívida na QI SCD.

STATUS 201

Response Body

```json
{
    "webhook_type": "debt",
    "key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c",
    "status": "issued",
    "event_datetime": "2026-04-07 23:59:28",
    "data": {
        "borrower": {
            "name": "Dante Ferrarini",
            "document_number": "31057466093",
            "related_party_key": "24fac77e-7782-4f72-b31a-daee288e34ed"
        },
        "contract": {
            "document_key": null,
            "number": "DWF1761222116",
            "urls": [],
            "signature_information": [
                {
                    "signer_name": "Dante Ferrarini",
                    "signer_document_number": "31057466093",
                    "signer_role": "issuer",
                    "signer_email": null,
                    "signer_external_key": null,
                    "signature_url": null
                }
            ]
        },
        "requester_identifier_key": "d1905ef5-19df-4183-bf0e-802b8229933c",
        "iof_charge_method": "financed",
        "collaterals": [],
        "contract_fees": [
            {
                "fee_type": "spread",
                "fee_amount": 3.02
            }
        ],
        "external_contract_fees": [
            {
                "fee_type": "tac",
                "fee_amount": 0,
                "tax_amount": 0,
                "net_fee_amount": 0
            }
        ],
        "external_contract_fee_amount": 0,
        "net_external_contract_fee_amount": 0,
        "contract_fee_amount": 3.02,
        "issue_amount": 1007.62,
        "assignment_amount": 1010.64,
        "cet": "5,8200%",
        "annual_cet": "97,0501%",
        "number_of_installments": 2,
        "base_iof": 3.79,
        "additional_iof": 3.83,
        "total_iof": 7.62,
        "ipoc_code": "324025020203131057466093DWF1761222116",
        "prefixed_interest_rate": {
            "annual_rate": 0.8373372409,
            "created_at": "2026-04-07T23:59:22",
            "daily_rate": 0.0016911989,
            "interest_base": "calendar_days",
            "monthly_rate": 0.052
        },
        "installments": [
            {
                "accrual_reference_date": null,
                "additional_costs": [],
                "advanced_paid_amount": 0,
                "bank_slip_key": null,
                "business_due_date": "2026-05-07",
                "calendar_days": 30,
                "digitable_line": null,
                "due_date": "2026-05-07",
                "due_interest": 0,
                "due_principal": 1007.62,
                "fine_amount": null,
                "has_interest": true,
                "installment_history": [],
                "installment_key": "1dea396f-beb1-4df3-9822-35800b4c095a",
                "installment_number": 1,
                "installment_payment": [],
                "installment_status": "created",
                "installment_type": "principal",
                "original_due_principal": 1007.62,
                "original_pre_fixed_amount": 52.3996159,
                "original_principal_amortization_amount": 491.4903841,
                "original_total_amount": 543.89,
                "paid_amount": 0,
                "paid_at": null,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 52.3996159,
                "principal_amortization_amount": 491.4903841,
                "qr_code_key": null,
                "qr_code_url": null,
                "renegotiation_proposal_key": null,
                "tax_amount": 1.20906634,
                "total_accrual_amount": null,
                "total_amount": 543.89,
                "total_paid_amount": 0,
                "workdays": 20
            },
            {
                "accrual_reference_date": null,
                "additional_costs": [],
                "advanced_paid_amount": 0,
                "bank_slip_key": null,
                "business_due_date": "2026-06-08",
                "calendar_days": 31,
                "digitable_line": null,
                "due_date": "2026-06-07",
                "due_interest": 0,
                "due_principal": 516.1296159,
                "fine_amount": null,
                "has_interest": true,
                "installment_history": [],
                "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999",
                "installment_number": 2,
                "installment_payment": [],
                "installment_status": "created",
                "installment_type": "principal",
                "original_due_principal": 516.1296159,
                "original_pre_fixed_amount": 27.7603841,
                "original_principal_amortization_amount": 516.1296159,
                "original_total_amount": 543.89,
                "paid_amount": 0,
                "paid_at": null,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 27.7603841,
                "principal_amortization_amount": 516.1296159,
                "qr_code_key": null,
                "qr_code_url": null,
                "renegotiation_proposal_key": null,
                "tax_amount": 2.58168034,
                "total_accrual_amount": null,
                "total_amount": 543.89,
                "total_paid_amount": 0,
                "workdays": 20
            }
        ],
        "total_pre_fixed_amount": 80.16
    }
}
```

:::caution Atenção
Lembre-se de salvar a **DEBT-KEY** retornada, pois ela será necessária para consultas, renegociações e estornos da operação.
:::

### Detalhes do Response Body

| Campo | Tipo | Descrição |
|---|---|---|
| **webhook_type** | string | Identificador do tipo de evento |
| **key** | string | DEBT-KEY — identificador único da dívida na QI SCD (UUID) |
| **status** | string | Status atual da dívida |
| **event_datetime** | string | Data e hora do evento (ISO 8601) |
| **data** | object | **[Objeto Data](#objeto-data)** — Dados da operação |

### Objeto Data

| Campo | Tipo | Descrição |
|---|---|---|
| **borrower** | object | **[Objeto Borrower Response](#objeto-borrower-response)** — Dados do tomador |
| **contract** | object | **[Objeto Contract Response](#objeto-contract-response)** — Dados do contrato |
| **requester_identifier_key** | string | Chave identificadora do solicitante (UUID) |
| **iof_charge_method** | string | Método de cobrança do IOF — sempre "financed" |
| **collaterals** | array | Lista de garantias da operação |
| **contract_fees** | array | **[Objeto Contract Fees](#objeto-contract-fees)** — Taxas QI Tech cobradas na operação |
| **external_contract_fees** | array | **[Objeto External Contract Fees](#objeto-external-contract-fees)** — Taxas externas cobradas na operação |
| **external_contract_fee_amount** | float | Valor total das taxas externas |
| **net_external_contract_fee_amount** | float | Valor líquido das taxas externas após impostos |
| **contract_fee_amount** | float | Valor total das taxas QI Tech |
| **issue_amount** | float | Valor nominal da operação de crédito |
| **assignment_amount** | float | Valor de cessão da operação de crédito |
| **cet** | string | Custo Efetivo Total mensal |
| **annual_cet** | string | Custo Efetivo Total anual |
| **number_of_installments** | integer | Número de parcelas |
| **base_iof** | float | Valor base do IOF |
| **additional_iof** | float | Valor adicional do IOF |
| **total_iof** | float | Valor total do IOF |
| **ipoc_code** | string | Código de registro de crédito brasileiro gerado pela QI Tech |
| **prefixed_interest_rate** | object | **[Objeto Interest Rate Response](#objeto-interest-rate-response)** — Taxa de juros nominal |
| **installments** | array | **[Objeto Installments Response](#objeto-installments-response)** — Parcelas da operação |
| **disbursement_account** | array | **[Objeto Disbursement Account Response](#objeto-disbursement-account-response)** — Dados das contas de desembolso (PIX por chave ou QR Code) |
| **total_pre_fixed_amount** | float | Valor total dos juros pré-fixados de todas as parcelas |

### Objeto Disbursement Account Response

Retornado apenas quando o desembolso é via **chave PIX** (`pix_key`) ou **QR Code** (`qr_code_key` / `qr_code_url`). Em desembolsos por TED, manual, PIX manual ou boleto, o campo `disbursement_account` **não aparece** na resposta.

| Campo | Tipo | Descrição |
|---|---|---|
| **name** | string | Nome do titular da conta destino (sempre por extenso). |
| **document_number** | string | CPF ou CNPJ do titular da conta destino. **CPF (11 dígitos) vem mascarado** como `***XXXXXX**` quando a conta foi resolvida via QR Code; **CNPJ (14 dígitos) vem íntegro**. Em fluxo `pix_key` consultado no DICT, retorna sem máscara. |
| **pix_key** | string | Chave PIX do destinatário (input do cliente ou extraída do QR Code decodificado). |
| **qr_code_key** | string | UUID do QR Code PIX, quando o desembolso foi por QR registrado. |
| **qr_code_url** | string | EMV "copia-e-cola" do QR Code, quando o desembolso foi por QR copia-e-cola. |
| **account_branch** | string | Agência da conta destino (preenchida em fluxos `pix_key` consultado no DICT). |
| **account_number** | string | Número da conta destino. |
| **account_digit** | string | Dígito verificador da conta destino. |
| **account_type** | string | Tipo da conta destino. |
| **ispb** | string | Código ISPB da instituição financeira destino. |
| **percentage_receivable** | float | Percentual do desembolso destinado a esta conta. |
| **amount_receivable** | float | Valor fixo destinado a esta conta. |
| **end_to_end_id** | string | Identificador end-to-end do PIX, atribuído após o decode/consulta. |

:::info Comportamento condicional
O campo `disbursement_account` é **estritamente populado** com `name` e `document_number` quando o fluxo é por PIX (chave ou QR Code). Os demais campos seguem o tipo do desembolso: por exemplo, em `qr_code_url` os campos `account_branch`/`account_number`/`account_digit` vêm `null` porque o EMV dinâmico não os carrega.
:::

### Objeto Borrower Response

| Campo | Tipo | Descrição |
|---|---|---|
| **name** | string | Nome completo do tomador |
| **document_number** | string | CPF do tomador |
| **related_party_key** | string | Identificador único do tomador na QI Tech (UUID) |

### Objeto Contract Response

| Campo | Tipo | Descrição |
|---|---|---|
| **document_key** | string | Chave do documento do contrato |
| **number** | string | Número do contrato |
| **urls** | array | Lista de URLs do documento do contrato |
| **signature_information** | array | **[Objeto Signature Information](#objeto-signature-information)** — Informações de assinatura |

### Objeto Signature Information

| Campo | Tipo | Descrição |
|---|---|---|
| **signer_name** | string | Nome completo do assinante |
| **signer_document_number** | string | CPF do assinante |
| **signer_role** | string | Papel do assinante na operação |
| **signer_email** | string | E-mail do assinante |
| **signer_external_key** | string | Chave externa do assinante |
| **signature_url** | string | URL do documento assinado |

### Objeto Contract Fees

| Campo | Tipo | Descrição |
|---|---|---|
| **fee_type** | string | Tipo da taxa |
| **fee_amount** | float | Valor da taxa |

### Objeto External Contract Fees

| Campo | Tipo | Descrição |
|---|---|---|
| **fee_type** | string | Tipo da taxa externa |
| **fee_amount** | float | Valor da taxa externa |
| **tax_amount** | float | Valor do imposto sobre a taxa |
| **net_fee_amount** | float | Valor líquido da taxa após impostos |

### Objeto Interest Rate Response

| Campo | Tipo | Descrição |
|---|---|---|
| **annual_rate** | float | Taxa de juros anual |
| **created_at** | string | Timestamp de criação da taxa (ISO 8601) |
| **daily_rate** | float | Taxa de juros diária |
| **interest_base** | string | Base de cálculo dos juros |
| **monthly_rate** | float | Taxa de juros mensal |

### Objeto Installments Response

| Campo | Tipo | Descrição |
|---|---|---|
| **accrual_reference_date** | string | Data de referência de cálculo da parcela |
| **additional_costs** | array | Lista de custos adicionais da parcela |
| **advanced_paid_amount** | float | Valor pago antecipadamente |
| **bank_slip_key** | string | Chave do boleto bancário |
| **business_due_date** | string | Data de vencimento ajustada para o próximo dia útil |
| **calendar_days** | integer | Dias corridos entre parcelas |
| **digitable_line** | string | Linha digitável do boleto |
| **due_date** | string | Data de vencimento da parcela |
| **due_interest** | float | Valor de juros remanescente na data de vencimento antes do pagamento |
| **due_principal** | float | Saldo devedor no momento da parcela |
| **fine_amount** | float | Valor de multa aplicado |
| **has_interest** | boolean | Indicador de incidência de juros na parcela |
| **installment_history** | array | Histórico de eventos da parcela |
| **installment_key** | string | Identificador único da parcela (UUID) |
| **installment_number** | integer | Número da parcela |
| **installment_payment** | array | Lista de pagamentos realizados na parcela |
| **installment_status** | string | Status atual da parcela |
| **installment_type** | string | Tipo da parcela — sempre "principal" |
| **original_due_principal** | float | Saldo devedor original no momento da emissão |
| **original_pre_fixed_amount** | float | Valor original dos juros pré-fixados na emissão |
| **original_principal_amortization_amount** | float | Valor original de amortização do principal na emissão |
| **original_total_amount** | float | Valor total original da parcela na emissão |
| **paid_amount** | float | Valor já pago na parcela |
| **paid_at** | string | Data do pagamento |
| **post_fixed_amount** | float | Valor dos juros pós-fixados — sempre 0 |
| **pre_fixed_amount** | float | Valor atual dos juros pré-fixados |
| **principal_amortization_amount** | float | Valor de amortização do principal |
| **qr_code_key** | string | Chave do QR Code PIX |
| **qr_code_url** | string | URL do QR Code PIX |
| **renegotiation_proposal_key** | string | Chave da proposta de renegociação, se aplicável |
| **tax_amount** | float | Valor do IOF na parcela |
| **total_accrual_amount** | float | Valor total de juros acumulados |
| **total_amount** | float | Valor total da parcela |
| **total_paid_amount** | float | Valor total pago na parcela até o momento |
| **workdays** | integer | Dias úteis entre parcelas |

---

# Simulação - Emissão Crédito Clean

URL: /documentation/manual_credito_clean/emissao/simulacao

## Resumo

Na QI Tech, disponibilizamos aos nossos clientes a possibilidade de simular os valores de uma operação de crédito antes de sua emissão efetiva. A simulação segue o mesmo padrão da requisição de emissão de dívida, porém não é necessário fornecer os dados cadastrais do tomador e da conta de desembolso.

## Request

ENDPOINT /v2/credit_operation/simulation
MÉTODO POST

Testar no Playground

Request Body

**disbursed_issue_amount**

```json
{
    "credit_operation_type": "ccb",
    "disbursed_issue_amount": 2800,
    "disbursement_date": "2025-09-24",
    "first_due_date": "2025-10-24",
    "force_installments_on_workdays": true,
    "interest_type": "pre_price_days",
    "issuer_person_type": "natural",
    "monthly_interest_rate": 0.04488,
    "number_of_installments": 2,
    "principal_amortization_month_period": 1
}
```

**installments**

```json
{
    "credit_operation_type": "ccb",
    "disbursement_date": "2026-01-26",
    "interest_type": "pre_price_days",
    "issuer_person_type": "natural",
    "monthly_interest_rate": 0.04488,
    "installments": [
        {
            "due_date": "2026-02-26",
            "amount": 137.48
        },
        {
            "due_date": "2026-03-26",
            "amount": 180.56
        }
    ]
}
```

### Detalhes do Request Body

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| **credit_operation_type*** | string | Tipo de operação de crédito | **[Enumerador Credit Operation Type](#enumerador-credit-operation-type)** |
| **disbursed_issue_amount** | float | Valor efetivamente liberado ao tomador. Obrigatório no fluxo padrão | 15,2 |
| **disbursement_date*** | string | Data em que os recursos do empréstimo serão disponibilizados | 10 |
| **first_due_date** | string | Data de vencimento da primeira parcela. Obrigatório no fluxo padrão | 10 |
| **force_installments_on_workdays** | boolean | Se verdadeiro, move datas de vencimento para o próximo dia útil | - |
| **interest_type*** | string | Método de amortização | **[Enumerador Interest Type](#enumerador-interest-type)** |
| **issuer_person_type*** | string | Define se o emissor é pessoa física ou jurídica | **[Enumerador Person Type](#enumerador-person-type)** |
| **monthly_interest_rate*** | float | Taxa de juros mensal aplicada sobre o saldo principal | 10,6 |
| **number_of_installments** | integer | Número de parcelas. Obrigatório no fluxo padrão | 3 |
| **principal_amortization_month_period** | integer | Período, em meses, entre as parcelas. Obrigatório no fluxo padrão | 1 |
| **installments** | array | Lista de parcelas para simulação. Cada item deve conter `due_date` e `amount`. Utilizar em substituição a `number_of_installments` + `first_due_date` | **[Objeto Installments Request](#objeto-installments-request)** |

### Objeto Installments Request

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| **due_date*** | string | Data de vencimento da parcela (YYYY-MM-DD) | 10 |
| **amount*** | float | Valor total da parcela. O sistema calcula o `disbursed_issue_amount` correspondente | 15,2 |

### Enumerador Credit Operation Type

| Valor | Descrição |
|---|---|
| `ccb` | Cédula de Crédito Bancário |

### Enumerador Interest Type

| Valor | Descrição |
|---|---|
| `pre_price_days` | Juros pré-fixados com amortização Price por dias corridos |
| `pre_price` | Juros pré-fixados com amortização Price por meses |
| `pre_sac` | Juros pré-fixados com amortização SAC |

### Enumerador Person Type

| Valor | Descrição |
|---|---|
| `natural` | Pessoa física |
| `legal` | Pessoa jurídica |

## Response

STATUS 200

Response Body

```json
{
    "disbursement_date": "2025-09-24",
    "issue_amount": 2821.32,
    "interest_type": "pre_price_days",
    "assignment_amount": 2829.78,
    "base_iof": 10.6,
    "total_iof": 21.32,
    "additional_iof": 10.72,
    "cet": 5.09,
    "annual_cet": 81.39,
    "first_due_date": "2025-10-24",
    "disbursed_amount": 2800,
    "prefixed_interest_rate": {
        "annual_rate": 0.6935459998,
        "daily_rate": 0.0014644728,
        "interest_base": "calendar_days",
        "monthly_rate": 0.04488
    },
    "tax_configuration": {
        "base_rate": 8.2e-05,
        "additional_rate": 0.0038
    },
    "fees": [
        {
            "amount": 0.3,
            "fee_amount": 8.46,
            "amount_type": "percentage",
            "fee_type": "spread",
            "type": "internal"
        }
    ],
    "installments": [
        {
            "due_date": "2025-10-24",
            "amount": 1507.4,
            "due_principal": 2821.32,
            "due_interest": 0,
            "has_interest": true,
            "period": 1,
            "period_workdays": 1.1,
            "calendar_days": 30,
            "workdays": 22,
            "installment_number": 1,
            "period_to_disbursement": 1,
            "prefixed_amount": 126.62248868,
            "period_workdays_to_disbursement": 1.1,
            "calendar_days_to_disbursement": 30,
            "workdays_to_disbursement": 22,
            "tax_amount": 3.39671268,
            "principal_amortization_amount": 1380.77751132
        },
        {
            "due_date": "2025-11-24",
            "amount": 1507.4,
            "due_principal": 1440.54248868,
            "due_interest": 0,
            "has_interest": true,
            "period": 1,
            "period_workdays": 1,
            "calendar_days": 31,
            "workdays": 20,
            "installment_number": 2,
            "period_to_disbursement": 2,
            "prefixed_amount": 66.85751132,
            "period_workdays_to_disbursement": 2.1,
            "calendar_days_to_disbursement": 61,
            "workdays_to_disbursement": 42,
            "tax_amount": 7.20559353,
            "principal_amortization_amount": 1440.54248868
        }
    ]
}
```

### Detalhes do Response Body

| Campo | Tipo | Descrição |
|---|---|---|
| **annual_cet** | float | Custo Efetivo Total anualizado expresso em decimal |
| **assignment_amount** | float | Valor de cessão da operação de crédito |
| **cet** | float | Custo Efetivo Total mensal expresso em decimal |
| **fees** | array | **[Objeto Fees](#objeto-fees)** - Lista de taxas da QI Tech cobradas na operação |
| **disbursed_amount** | float | Valor desembolsado na operação de crédito |
| **disbursement_date** | string | Data de desembolso da operação |
| **installments** | array | **[Objeto Installments](#objeto-installments)** - Parcelas da operação |
| **interest_type** | string | Método de amortização e cálculo de juros |
| **additional_iof** | float | IOF adicional aplicado sobre o principal da transação |
| **base_iof** | float | Base de cálculo do IOF |
| **total_iof** | float | Valor total do IOF aplicado na transação |
| **issue_amount** | float | Valor nominal da operação de crédito |
| **tax_configuration** | object | **[Objeto Tax Configuration](#objeto-tax-configuration)** - Valores das taxas de IOF |
| **first_due_date** | string | Data de vencimento da primeira parcela |
| **prefixed_interest_rate** | object | **[Objeto Interest Rate](#objeto-interest-rate)** - Taxa de juros nominal |

### Objeto Fees

| Campo | Tipo | Descrição |
|---|---|---|
| **amount** | float | Valor ou percentual da taxa |
| **fee_amount** | float | Valor monetário da taxa |
| **amount_type** | string | Tipo do valor (percentage ou fixed) |
| **fee_type** | string | Tipo da taxa |
| **type** | string | Classificação da taxa (internal ou external) |

### Objeto Installments

| Campo | Tipo | Descrição |
|---|---|---|
| **due_date** | string | Data de vencimento da parcela |
| **amount** | float | Valor total da parcela |
| **due_principal** | float | Saldo devedor no momento da parcela |
| **due_interest** | float | Valor de juros remanescente na data de vencimento antes do pagamento |
| **has_interest** | boolean | Indicador de incidência de juros na parcela |
| **installment_number** | integer | Número da parcela |
| **prefixed_amount** | float | Valor dos juros pré-fixados pagos na parcela |
| **tax_amount** | float | Valor do IOF na parcela |
| **principal_amortization_amount** | float | Valor de amortização do principal |
| **period** | float | Período da parcela |
| **period_workdays** | float | Período da parcela em dias úteis |
| **period_to_disbursement** | float | Número de períodos acumulados desde o desembolso até a parcela |
| **period_workdays_to_disbursement** | float | Número de períodos em dias úteis acumulados desde o desembolso até a parcela |
| **calendar_days** | integer | Dias corridos entre parcelas |
| **calendar_days_to_disbursement** | integer | Dias corridos acumulados desde o desembolso até a parcela |
| **workdays** | integer | Dias úteis entre parcelas |
| **workdays_to_disbursement** | integer | Dias úteis acumulados desde o desembolso até a parcela |

### Objeto Tax Configuration

| Campo | Tipo | Descrição |
|---|---|---|
| **base_rate** | float | Taxa base do IOF |
| **additional_rate** | float | Taxa adicional do IOF |

### Objeto Interest Rate

| Campo | Tipo | Descrição |
|---|---|---|
| **annual_rate** | float | Taxa de juros anual |
| **daily_rate** | float | Taxa de juros diária |
| **interest_base** | string | Base de cálculo dos juros |
| **monthly_rate** | float | Taxa de juros mensal |

---

# Webhooks - Emissão Crédito Clean

URL: /documentation/manual_credito_clean/emissao/webhooks

## Resumo

Após a resposta de sucesso da emissão, você receberá webhooks notificando sobre os eventos do ciclo de vida da operação: assinatura do contrato, desembolso e, eventualmente, cancelamento.

:::danger Atenção!
Os webhooks não devem ser mapeados de forma estrita. Novos campos podem ser adicionados ao payload sem aviso prévio.
:::

## Webhook de Assinatura

Este webhook é enviado quando o contrato (CCB) é assinado com sucesso.

WEBHOOK_TYPE debt
STATUS signature_finished

Webhook Body

```json
{
    "key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "status": "signature_finished",
    "webhook_type": "debt",
    "event_datetime": "2025-10-27T17:09:33Z",
    "signed_contract_url": "https://storage.googleapis.com/sandbox-doc-api/documents/c8b191cb-7b90-4e37-9280-397a597babc1/CCB-TIK11267101212-20251027170925_signed.pdf"
}
```

### Campos do Webhook de Assinatura

| Campo | Tipo | Descrição |
|---|---|---|
| **key** | string | Chave única da dívida (DEBT-KEY) |
| **status** | string | Status do evento: `signature_finished` |
| **webhook_type** | string | Tipo do webhook: `debt` |
| **event_datetime** | string | Data e hora do evento |
| **signed_contract_url** | string | URL do contrato assinado (PDF) |

## Webhook de Desembolso

Este webhook confirma que o desembolso foi realizado com sucesso.

WEBHOOK_TYPE debt
STATUS disbursed

Webhook Body

```json
{
    "key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "data": {
        "installments": [
            {
                "due_date": "2025-11-27",
                "total_amount": 87.43,
                "installment_key": "e25fb146-0a61-4319-a722-d01b2213d0f9",
                "pre_fixed_amount": 29.26477451,
                "installment_number": 1,
                "principal_amortization_amount": 58.16522549
            },
            {
                "due_date": "2025-12-27",
                "total_amount": 87.43,
                "installment_key": "2557de2b-6df1-4a8a-b46a-59206ece157f",
                "pre_fixed_amount": 20.11446867,
                "installment_number": 2,
                "principal_amortization_amount": 67.31553133
            },
            {
                "due_date": "2026-01-27",
                "total_amount": 87.43,
                "installment_key": "cc503d1d-6387-4a1f-bd78-62b248d02ec8",
                "pre_fixed_amount": 11.07075682,
                "installment_number": 3,
                "principal_amortization_amount": 76.35924318
            }
        ],
        "ted_receipt_list": [],
        "requester_identifier_key": null
    },
    "status": "disbursed",
    "webhook_type": "debt",
    "event_datetime": "2025-10-27T17:10:21Z"
}
```

### Campos do Webhook de Desembolso

| Campo | Tipo | Descrição |
|---|---|---|
| **key** | string | Chave única da dívida (DEBT-KEY) |
| **status** | string | Status do evento: `disbursed` |
| **webhook_type** | string | Tipo do webhook: `debt` |
| **event_datetime** | string | Data e hora do evento |
| **data.installments** | array | Lista de parcelas com suas chaves e valores |
| **data.ted_receipt_list** | array | Lista de comprovantes de TED (quando aplicável) |

## Webhook de Cancelamento

Se a dívida falhar no desembolso ou for devolvida, você receberá um webhook de cancelamento.

WEBHOOK_TYPE debt
STATUS canceled

Webhook Body

```json
{
    "webhook_type": "debt",
    "key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "event_datetime": "2025-10-27T16:38:59Z",
    "data": {
        "cancel_reason": "Operacao cancelada manualmente",
        "cancel_reason_enumerator": "manual"
    },
    "status": "canceled"
}
```

### Campos do Webhook de Cancelamento

| Campo | Tipo | Descrição |
|---|---|---|
| **key** | string | Chave única da dívida (DEBT-KEY) |
| **status** | string | Status do evento: `canceled` |
| **webhook_type** | string | Tipo do webhook: `debt` |
| **event_datetime** | string | Data e hora do evento |
| **data.cancel_reason** | string | Descrição textual do motivo do cancelamento |
| **data.cancel_reason_enumerator** | string | Enumerador do motivo do cancelamento |

### Enumeradores de Cancelamento

| Enumerador | Descrição |
|---|---|
| `disbursing_error` | Operação cancelada por erro durante o desembolso |
| `waiting_signature` | Operação cancelada por falta de assinatura |
| `pix_max_retry` | Operação cancelada porque o banco receptor não processou o desembolso |
| `manual` | Operação cancelada manualmente |
| `agencia_conta_invalida` | Agência ou número de conta do destinatário inválidos |
| `invalid_account` | Número da conta de destino inexistente ou inválido |
| `invalid_document_number` | CPF/CNPJ da conta de destino incorreto |
| `unsupported_transaction` | A conta de destino não suporta este tipo de transação |
| `invalid_ispb` | O número ISPB é inválido ou inexistente |
| `rejected_payment` | Ordem de pagamento rejeitada pelo banco receptor |
| `refund_after_payee_request` | Estorno solicitado pelo beneficiário |
| `blocked_account` | A conta de destino está bloqueada |
| `amount_too_great` | Valor excede o limite da conta de destino |
| `receiver_error` | Transação interrompida por erro no PSP do receptor |
| `closed_account` | A conta de destino está encerrada |
| `disbursing_hour_closed` | Desembolso fora do horário permitido |
| `unregistered_pix_key` | A chave Pix não está registrada |
| `spi_timeout` | Timeout no controle SPI |

---

## Webhook de Quitação

Quando todas as parcelas são pagas e a operação é quitada integralmente, o sistema envia este webhook.

WEBHOOK_TYPE debt
STATUS settled

Webhook Body

```json
{
    "key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "data": {
        "settlement_amount": 3429.38
    },
    "status": "settled",
    "webhook_type": "debt",
    "event_datetime": "2025-10-27T07:03:49Z"
}
```

### Campos do Webhook de Quitação

| Campo | Tipo | Descrição |
|---|---|---|
| **key** | string | Chave única da dívida (DEBT-KEY) |
| **status** | string | Status do evento: `settled` |
| **webhook_type** | string | Tipo do webhook: `debt` |
| **event_datetime** | string | Data e hora do evento |
| **data.settlement_amount** | float | Valor total liquidado |

## Webhook de Confirmação de Cessão

Este webhook é enviado quando uma cessão de operações de crédito é processada. Ele notifica que o processo de cessão foi iniciado e fornece os metadados necessários para rastreamento.

WEBHOOK_TYPE assignment.status_change

Webhook Body

```json
{
    "key": "b866dc02-73db-42a4-bc66-866d465cbb73",
    "webhook_type": "assignment.status_change",
    "event_datetime": "2026-04-10T22:37:52Z",
    "data": {
        "assignment_key": "550e8400-e29b-41d4-a716-446655440000",
        "term_of_assignment_url": "https://example.com/terms/cessao.pdf",
        "number_of_items": 1,
        "total_amount": 1000,
        "reference_date": "2026-04-10"
    }
}
```

### Campos do Webhook de Confirmação de Cessão

| Campo | Tipo | Descrição |
|---|---|---|
| **key** | string | Chave única da cessão |
| **webhook_type** | string | Tipo do webhook: `assignment.status_change` |
| **event_datetime** | string | Data e hora do evento |
| **data.assignment_key** | string | Identificador único da cessão (UUID) |
| **data.term_of_assignment_url** | string | URL para download do Termo de Cessão (PDF) |
| **data.number_of_items** | integer | Total de operações de crédito incluídas na cessão |
| **data.total_amount** | float | Soma do valor presente de todos os itens da cessão |
| **data.reference_date** | string | Data base utilizada nos cálculos da cessão (YYYY-MM-DD) |

---

## Webhook de Cancelamento Permanente

Operações com status `canceled` são automaticamente canceladas de forma permanente após 7 dias. O cancelamento permanente também pode ser acionado manualmente via endpoint `/debt/{debt_key}/cancel_permanently`.

WEBHOOK_TYPE debt
STATUS canceled_permanently

Webhook Body

```json
{
    "key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "data": {},
    "status": "canceled_permanently",
    "webhook_type": "debt",
    "event_datetime": "2025-10-27T03:46:31Z"
}
```

### Campos do Webhook de Cancelamento Permanente

| Campo | Tipo | Descrição |
|---|---|---|
| **key** | string | Chave única da dívida (DEBT-KEY) |
| **status** | string | Status do evento: `canceled_permanently` |
| **webhook_type** | string | Tipo do webhook: `debt` |
| **event_datetime** | string | Data e hora do evento |

---

## Webhook de Atualização de Parcela

Enviado quando o status de uma parcela é atualizado (pagamento, vencimento, antecipação, etc.).

WEBHOOK_TYPE installment.status_change

:::info Documentação completa
Payload detalhado e todos os status possíveis estão em [Webhooks de Parcelas](/documentation/webhooks/parcelas).
:::

### Status de parcela

| Status | Descrição |
|---|---|
| `opened` | Parcela em aberto |
| `paid` | Parcela paga |
| `waiting_payment` | Aguardando pagamento |
| `paid_early` | Parcela paga antecipadamente |
| `paid_partial` | Parcela paga parcialmente |
| `overdue` | Parcela vencida |
| `paid_partial_overdue` | Parcela paga parcialmente após vencimento |
| `paid_overdue` | Parcela paga após vencimento |

---

# Estorno Crédito Clean

URL: /documentation/manual_credito_clean/estorno/

## Resumo

O estorno de uma operação Crédito Clean permite reverter o desembolso realizado. Existem três cenários de cancelamento/estorno:

1. **Cancelamento antes do desembolso**: Cancela a operação antes que os recursos sejam transferidos
2. **Estorno após o desembolso — via Pix de devolução (até 7 dias)**: Gera um Pix copia-e-cola para que o tomador devolva os recursos
3. **Estorno após o desembolso — via conta interna QI**: A devolução é feita diretamente pela conta interna da QI Tech, sem ação do tomador

---

## 1. Cancelamento Antes do Desembolso

Cancela uma operação de crédito que ainda não foi desembolsada.

### Request

ENDPOINT /debt/ DEBT-KEY /cancel
MÉTODO PATCH

Testar no Playground

### Path Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `debt_key`* | string | Chave única da dívida retornada no momento da criação da operação de crédito | UUID |

### Response

STATUS 200

Response Body

```json
{}
```

:::caution Atenção
Este endpoint só pode ser utilizado para operações que ainda **não foram desembolsadas**. Para operações já desembolsadas, utilize o endpoint de estorno abaixo.
:::

---

## 2. Estorno Após o Desembolso — Via Pix de Devolução (Até 7 Dias)

Utilizado quando o parceiro deseja solicitar ao tomador que devolva os recursos via Pix. O sistema gera um Pix copia-e-cola para que o tomador realize a devolução. Assim que o pagamento é confirmado, a operação é cancelada automaticamente.

:::info Quando usar
Use este endpoint quando o estorno deve ser realizado pelo **próprio tomador**, que receberá um Pix de devolução para pagar.
:::

### Request

ENDPOINT /debt/reversal
MÉTODO POST

Testar no Playground

Request Body

```json
{
    "credit_operation_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c"
}
```

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `credit_operation_key`* | string | Chave da operação de crédito (DEBT-KEY) | UUID |

### Response

STATUS 200

Response Body

```json
{
    "payer_name": "Dante Ferrarini",
    "payer_document_number": "31057466093",
    "amount": 1000,
    "expiration_date": "2026-04-28",
    "copy_paste_pix": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/fb1906ab2eff40109609855ac104f60e5204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***63046387",
    "reversal_key": "7a18fdb6-a3e7-4fc9-833e-0f6d8e98de3b",
    "status": "active",
    "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c",
    "qr_code_key": "fb1906ab-2eff-4010-9609-855ac104f60e"
}
```

### Detalhes do Response

| Campo | Tipo | Descrição |
|---|---|---|
| **payer_name** | string | Nome do tomador |
| **payer_document_number** | string | CPF/CNPJ do tomador |
| **amount** | float | Valor total a ser devolvido |
| **expiration_date** | string | Data de expiração do Pix de devolução |
| **copy_paste_pix** | string | Código Pix copia-e-cola para devolução dos recursos |
| **reversal_key** | string | Chave única do estorno (UUID) |
| **status** | string | Status do estorno: `active` |
| **debt_key** | string | Chave da dívida (DEBT-KEY) |
| **qr_code_key** | string | Chave do QR Code Pix (UUID) |

:::warning Importante
- O estorno só pode ser realizado dentro de **7 dias corridos** após o desembolso
- O `copy_paste_pix` gerado possui uma **data de expiração**. Após essa data, o Pix não poderá mais ser utilizado
- Após o pagamento do Pix pelo tomador, a operação será cancelada automaticamente e você receberá um webhook de cancelamento
:::

---

## 3. Estorno Após o Desembolso — Via Conta Interna QI

Utilizado quando a devolução dos recursos é realizada diretamente pela **conta interna da QI Tech**, sem necessidade de ação do tomador. Indicado para o método `internal`, onde o valor é debitado internamente sem geração de Pix.

:::info Quando usar
Use este endpoint quando o estorno é operado pelo **parceiro via conta interna da QI Tech**, sem envolver o tomador no processo de devolução.
:::

### Request

ENDPOINT /credit_operation/ CREDIT-OPERATION-KEY /reversal
MÉTODO PUT

:::info Header obrigatório
Envie o header `SELECTED-AGENT` com o valor do seu `requester_key`.
:::

### Path Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `credit_operation_key`* | string | Chave da operação de crédito (DEBT-KEY) | UUID |

Request Body (opcional)

```json
{
    "cancel_reason": "reversed_manually"
}
```

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `cancel_reason` | string | Motivo do estorno. Se não informado, o sistema utilizará o padrão. | - |

---

# Webhooks - Estorno Crédito Clean

URL: /documentation/manual_credito_clean/estorno/webhooks

## Resumo

Após a criação de um pedido de estorno, o sistema enviará webhooks para notificar sobre os eventos do processo de reversão.

:::danger Atenção!
Os webhooks não devem ser mapeados de forma estrita. Novos campos podem ser adicionados ao payload sem aviso prévio.
:::

## Webhook de Cancelamento por Estorno

Quando o tomador realiza o pagamento do Pix de devolução gerado pelo estorno, a operação de crédito é cancelada automaticamente e o seguinte webhook é enviado:

WEBHOOK_TYPE debt
STATUS canceled

Webhook Body

```json
{
    "webhook_type": "debt",
    "key": "1ebd4a90-2721-4c39-a399-427fa16bca65",
    "event_datetime": "2025-10-27T16:38:59Z",
    "data": {
        "cancel_reason": "Operacao cancelada por estorno",
        "cancel_reason_enumerator": "refund_after_payee_request"
    },
    "status": "canceled"
}
```

### Campos do Webhook

| Campo | Tipo | Descrição |
|---|---|---|
| **webhook_type** | string | Tipo do webhook: `debt` |
| **key** | string | Chave única da dívida (DEBT-KEY) |
| **event_datetime** | string | Data e hora do evento |
| **status** | string | Status do evento: `canceled` |
| **data.cancel_reason** | string | Descrição textual do motivo do cancelamento |
| **data.cancel_reason_enumerator** | string | Enumerador do motivo do cancelamento |

### Enumeradores de Cancelamento Relacionados a Estorno

| Enumerador | Descrição |
|---|---|
| `refund_after_payee_request` | Estorno solicitado pelo beneficiário |
| `manual` | Operação cancelada manualmente |
| `disbursing_error` | Operação cancelada por erro durante o desembolso |

---

## Webhook de Liquidação de Estorno (Transaction Reversal)

Para estornos processados via o endpoint de `transaction_reversal`, o webhook de confirmação segue o formato abaixo:

WEBHOOK_TYPE transaction_reversal.transaction_reversal_status_change
STATUS paid

Webhook Body

```json
{
    "data": {
        "transaction_reversal_key": "b6da1a84-5bb3-4d71-9912-cbbcfe7189c1",
        "amount": 123.45,
        "status": "paid",
        "description": "Valor de liquidação indevido",
        "reference_date": "2025-03-23",
        "fund_class_document_number": "12.345.678/0009-10",
        "fund_class_key": "0619574f-2815-419d-8208-630b0dc30487",
        "source_account": {
            "account_digit": "7",
            "account_branch": "0001",
            "account_number": "0099999",
            "owner": {
                "name": "FUNDO DE INVESTIMENTO",
                "document_number": "12.345.678/0009-10"
            },
            "financial_institution": {
                "code": "329",
                "ispb": "32402502",
                "name": "QI Sociedade de Crédito Direto"
            }
        },
        "target_account": {
            "owner": {
                "name": "Nome fictício",
                "document_number": "111.202.188-99"
            },
            "account_digit": "0",
            "account_branch": "0001",
            "account_number": "1029490",
            "target_pix_key": "1232221",
            "financial_institution": {
                "code": "033",
                "ispb": "90400888",
                "name": "BCO SANTANDER (BRASIL) S.A."
            }
        },
        "external_key": "40054daa-c3c5-49cd-add7-858b576c5887"
    },
    "webhook_type": "transaction_reversal.transaction_reversal_status_change",
    "webhook_datetime": "2025-03-23T15:08:30Z"
}
```

### Campos do Webhook de Transaction Reversal

| Campo | Tipo | Descrição |
|---|---|---|
| **webhook_type** | string | Tipo do webhook: `transaction_reversal.transaction_reversal_status_change` |
| **webhook_datetime** | string | Data e hora do envio do webhook |
| **data.transaction_reversal_key** | string | Chave única do estorno |
| **data.amount** | float | Valor estornado |
| **data.status** | string | Status do estorno: `paid` |
| **data.description** | string | Descrição do estorno |
| **data.reference_date** | string | Data de referência do processamento |
| **data.fund_class_key** | string | Chave do fundo |
| **data.source_account** | object | Dados da conta de origem do estorno |
| **data.target_account** | object | Dados da conta de destino do estorno |
| **data.external_key** | string | Chave externa da transação estornada |

---

## Webhook de Devolução de Indevido

Quando um valor indevido é identificado e a devolução é processada com sucesso, o sistema envia este webhook.

WEBHOOK_TYPE laas.devolution.refund_receipt
STATUS refunded

Webhook Body

```json
{
    "event_datetime": "2024-01-15T14:30:00.000Z",
    "key": "fb34e0ac-2c98-47e7-9040-406b8c3d80e7",
    "status": "refunded",
    "webhook_type": "laas.devolution.refund_receipt",
    "data": {
        "origin_key": "b41c63e4-6912-4217-9111-a47dd4da9588",
        "devolution_key": "336f0e15-e7b8-45a4-8986-5411434be76a",
        "devolution_amount": 150.75,
        "devolution_status": "refunded",
        "devolution_reason_description": "The payment arrived earlier than expected. The difference between the paid amount and the present value should be refund",
        "receipt_url": "https://storage.googleapis.com/receipts/devolution_receipt_12345.pdf",
        "document_key": "cd27a0c3-630d-4682-81b2-71b5b325bcde",
        "transacted_at": "2024-01-15T14:25:30.000Z",
        "devolution_origin_type": "social_security"
    }
}
```

### Campos do Webhook de Devolução

| Campo | Tipo | Descrição |
|---|---|---|
| **webhook_type** | string | Tipo do webhook: `laas.devolution.refund_receipt` |
| **key** | string | Chave única da devolução |
| **event_datetime** | string | Data e hora do evento |
| **status** | string | Status: `refunded` |
| **data.origin_key** | string | Chave de referência do recurso devolvido |
| **data.devolution_key** | string | Chave única da devolução |
| **data.devolution_amount** | float | Valor da devolução em reais |
| **data.devolution_status** | string | Status da devolução |
| **data.devolution_reason_description** | string | Descrição do motivo da devolução |
| **data.receipt_url** | string | URL do comprovante da devolução |
| **data.document_key** | string | Chave do documento relacionado |
| **data.transacted_at** | string | Data e hora da transação (ISO 8601 UTC) |
| **data.devolution_origin_type** | string | Origem da devolução |

---

# Notificações - Crédito Clean

URL: /documentation/manual_credito_clean/notificacoes

## Resumo

O sistema de notificações permite consultar e reenviar webhooks de eventos do ciclo de vida da operação. Utilize estes endpoints para diagnosticar falhas de entrega e disparar retentativas.

:::danger Atenção!
Os webhooks não devem ser mapeados de forma estrita. Novos campos podem ser adicionados ao payload sem aviso prévio.
:::

## Webhooks do Crédito Clean

Os webhooks gerados pelo Crédito Clean são distribuídos pelas páginas de cada fluxo:

| Webhook Type | Status | Documentação |
|---|---|---|
| `debt` | `signature_finished` | [Emissão — Webhooks](./emissao/webhooks) |
| `debt` | `disbursed` | [Emissão — Webhooks](./emissao/webhooks) |
| `debt` | `canceled` | [Emissão — Webhooks](./emissao/webhooks) |
| `debt` | `settled` | [Emissão — Webhooks](./emissao/webhooks) |
| `debt` | `canceled_permanently` | [Emissão — Webhooks](./emissao/webhooks) |
| `installment.status_change` | — | [Emissão — Webhooks](./emissao/webhooks) |
| `debt` | `canceled` (estorno) | [Estorno — Webhooks](./estorno/webhooks) |
| `transaction_reversal.transaction_reversal_status_change` | `paid` | [Estorno — Webhooks](./estorno/webhooks) |
| `laas.devolution.refund_receipt` | `refunded` | [Estorno — Webhooks](./estorno/webhooks) |
| `renegotiation.proposal` | `paid` | [Renegociação — Webhooks](./renegociacao/webhooks) |
| `renegotiation.batch_proposal` | `paid` | [Renegociação — Webhooks](./renegociacao/webhooks) |
| `renegotiation.batch_proposal` | `rejected` | [Renegociação — Webhooks](./renegociacao/webhooks) |

---

## Consultando Eventos para Reenvio

ENDPOINT /notification/events
MÉTODO GET

### Query Parameters

| Parâmetro | Tipo | Descrição |
|---|---|---|
| **event_type** | string | Tipo do evento (ex: `debt_disbursed`) |
| **callback_status** | string | Status do callback (ex: `failed`, `sent`) |
| **origin_key** | uuid | Chave única do recurso de origem |
| **start_datetime** | string | Data/hora inicial (formato `YYYY-MM-DDTHH:mm:ssZ`, UTC) |
| **end_datetime** | string | Data/hora final (formato `YYYY-MM-DDTHH:mm:ssZ`, UTC) |

:::caution Limite de janela
A janela entre `start_datetime` e `end_datetime` deve ser de no máximo **14 dias**.
:::

Response Body (200)

```json
{
    "data": [
        {
            "event_key": "<UUID>",
            "event_type": "debt_disbursed",
            "status": "processed",
            "origin_enumerator": "account",
            "origin_key": "<UUID>",
            "callbacks": [
                {
                    "callback_key": "<UUID>",
                    "callback_status": "failed"
                }
            ]
        }
    ],
    "pagination": {
        "current_page": 1,
        "rows_per_page": 25
    }
}
```

---

## Reenviando um Callback

ENDPOINT /notification/event/{`{event_key}`}/callback/{`{callback_key}`}/retry
MÉTODO PATCH

### Path Parameters

| Parâmetro | Tipo | Descrição |
|---|---|---|
| **event_key** | uuid | Chave do evento (obtida na listagem) |
| **callback_key** | uuid | Chave do callback (obtida na listagem) |

Retorna `204 No Content` em caso de sucesso.

:::info Documentação completa
Instruções detalhadas e exemplos de troubleshooting estão em [Reenvio de Notificações](/documentation/notificacoes/reenvio_de_notificacoes).
:::

---

# Consulta de Valor Presente - Refinanciamento Crédito Clean

URL: /documentation/manual_credito_clean/refinanciamento/consulta_valor_presente

## Resumo

Para descobrir o valor presente que será utilizado no refinanciamento de uma operação, é possível utilizar o endpoint de consulta de dívidas indicando os query params listados abaixo.

## Request

ENDPOINT /debt
MÉTODO GET

### Query Params

| Campo | Tipo | Descrição |
|---|---|---|
| `key`* | string | Chave da dívida (DEBT-KEY) retornada no momento da criação da operação de crédito |
| `eval_present_value`* | string | Indica que o valor atual de cada parcela deve ser calculado e mostrado (`true`) |
| `calculate_delay`* | string | Indica que, se a parcela estiver vencida, os juros de mora e multa devem ser calculados com o valor presente (`true`) |
| `calculate_spread`* | string | Indica se o valor de spread da operação deve ser adicionado ao valor presente. Para operações de refinanciamento deve ser `false` |

### Exemplo de URL

```
/debt?key=72760166-4ddf-41fb-8a8c-605f8f4fc35c&eval_present_value=true&calculate_delay=true&calculate_spread=false
```

### Response

STATUS 200

Response Body

```json
{
    "webhook_type": "debt",
    "operation_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c",
    "status": "opened",
    "data": {
        "credit_operation_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c",
        "contract_number": "DWF1761222116",
        "annual_cet": 97.05,
        "cet": 5.82,
        "disbursed_issue_amount": 1000,
        "disbursement_date": "2026-04-07",
        "issue_amount": 1007.62,
        "final_disbursement_amount": 1000,
        "number_of_installments": 2,
        "total_iof": 7.62,
        "base_iof": 3.79,
        "additional_iof": 3.83,
        "assignment_amount": 1007.63,
        "issuer_name": "Dante Ferrarini",
        "issuer_document_number": "31057466093",
        "prefixed_interest_rate": {
            "annual_rate": 0.8373372409,
            "daily_rate": 0.0016911989,
            "interest_base": {
                "enumerator": "calendar_days",
                "year_days": 360
            },
            "monthly_rate": 0.052
        },
        "installments": [
            {
                "installment_key": "1dea396f-beb1-4df3-9822-35800b4c095a",
                "installment_number": 1,
                "due_date": "2026-05-07",
                "business_due_date": "2026-05-07",
                "calendar_days": 30,
                "total_amount": 543.89,
                "due_principal": 1007.62,
                "pre_fixed_amount": 52.3996159,
                "principal_amortization_amount": 491.4903841,
                "tax_amount": 1.20906634,
                "installment_status": {
                    "enumerator": "opened"
                },
                "paid_amount": 0,
                "present_amount": 517.01,
                "workdays": 20
            },
            {
                "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999",
                "installment_number": 2,
                "due_date": "2026-06-07",
                "business_due_date": "2026-06-08",
                "calendar_days": 31,
                "total_amount": 543.89,
                "due_principal": 516.1296159,
                "pre_fixed_amount": 27.7603841,
                "principal_amortization_amount": 516.1296159,
                "tax_amount": 2.58168034,
                "installment_status": {
                    "enumerator": "opened"
                },
                "paid_amount": 0,
                "present_amount": 490.62,
                "workdays": 20
            }
        ]
    }
}
```

:::tip Valor para Refinanciamento
O valor total a ser utilizado como `disbursed_amount` na simulação/criação do refinanciamento é a soma dos `present_amount` de todas as parcelas. Neste exemplo: 517.01 + 490.62 = **1007.63**.
:::

:::caution Atenção
Para operações de refinanciamento, o campo `calculate_spread` deve ser sempre `false`, pois o valor de spread não deve ser considerado no cálculo do valor presente para quitação.
:::

---

# Criação - Refinanciamento Crédito Clean

URL: /documentation/manual_credito_clean/refinanciamento/criacao

## Resumo

A criação de um refinanciamento utiliza o mesmo endpoint e payload da emissão (`/signed_debt`), com a adição do objeto `refinanced_credit_operations` contendo a lista de operações que serão quitadas. O somatório do valor presente dos contratos anteriores será retido e apenas o excedente será liberado na conta do tomador.

## Request

ENDPOINT /signed_debt
MÉTODO POST

Testar no Playground

Request Body

```json
{
    "borrower": {
        "name": "Dante Ferrarini",
        "email": "",
        "phone": {
            "number": "185633631",
            "area_code": "15",
            "country_code": "086"
        },
        "is_pep": false,
        "address": {
            "city": "São Paulo",
            "state": "SP",
            "number": "",
            "street": "Rua Gilberto Sabino",
            "postal_code": "05425020",
            "neighborhood": "Pinheiros",
            "complement": ""
        },
        "role_type": "issuer",
        "birth_date": "1993-09-10",
        "person_type": "natural",
        "attached_documents_list": [
            {
                "selfie": "250e7e95-57c8-40bd-a0cd-0be8eb172916"
            }
        ],
        "individual_document_number": "31057466093"
    },
    "financial": {
        "disbursed_amount": 1007.63,
        "interest_type": "pre_price_days",
        "credit_operation_type": "ccb",
        "annual_interest_rate": 2.32,
        "disbursement_date": "2026-04-07",
        "interest_grace_period": 0,
        "principal_grace_period": 0,
        "number_of_installments": 3,
        "fine_configuration": {
            "contract_fine_rate": 0.02,
            "interest_base": "calendar_days",
            "monthly_rate": 0.01
        }
    },
    "simplified": true,
    "additional_data": {
        "contract": {
            "contract_number": "DWFR00000012",
            "signatures": [
                {
                    "signer": {
                        "name": "Dante Ferrarini",
                        "email": "",
                        "phone": {
                            "number": "185633631",
                            "area_code": "15",
                            "country_code": "086"
                        },
                        "document_number": "31057466093"
                    },
                    "signature": {
                        "timestamp": "2026-04-08T00:40:30Z",
                        "ip_address": "192.168.1.1",
                        "signature_file": {
                            "file_url": "https://qitech.com.br/signature.pdf",
                            "file_type": "pdf"
                        }
                    }
                }
            ]
        }
    },
    "refinanced_credit_operations": [
        {
            "operation_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c"
        }
    ],
    "requester_identifier_key": "d2107ef5-19df-4183-bf0e-802b8229933c",
    "purchaser_document_number": "32402502000135",
    "disbursement_bank_accounts": [
        {
            "name": "company name",
            "ispb_number": "32402502",
            "account_digit": "5",
            "branch_number": "0001",
            "account_number": "7617846",
            "document_number": "32246162000281",
            "percentage_receivable": 100
        }
    ]
}
```

:::caution Atenção
O payload é **idêntico** ao da emissão (`/signed_debt`), com a adição do campo **`refinanced_credit_operations`** contendo a lista de operações a serem quitadas.
:::

### Detalhes do Request Body

O payload contém todos os campos da [Emissão Crédito Clean](../emissao/emissao), com a adição de:

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| **refinanced_credit_operations*** | array | Lista de operações a serem refinanciadas | **[Objeto Refinanced Credit Operations](#objeto-refinanced-credit-operations)** |

Todos os demais campos seguem a mesma especificação da emissão:
- **[Objeto Borrower](../emissao/emissao#objeto-borrower)**
- **[Objeto Additional Data](../emissao/emissao#objeto-additional-data)**
- **[Objeto Disbursement Bank Account](../emissao/emissao#objeto-disbursement-bank-account)**

:::info Diferença no Objeto Financial
No refinanciamento, o campo `financial` utiliza `annual_interest_rate` ao invés de `monthly_interest_rate`, e o `disbursed_amount` deve ser o valor presente total da operação a ser refinanciada (obtido na consulta de valor presente).
:::

### Objeto Refinanced Credit Operations

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `operation_key`* | string | Chave da operação a ser refinanciada (DEBT-KEY da operação original) | UUID |

## Response

A resposta segue o mesmo formato da emissão de dívida, retornando a **DEBT-KEY** do novo contrato.

STATUS 201

Response Body

```json
{
    "webhook_type": "debt",
    "key": "290f042f-eedd-4d9d-b621-3a81df0181b6",
    "status": "opened",
    "event_datetime": "2026-04-08 00:40:37",
    "data": {
        "borrower": {
            "name": "Dante Ferrarini",
            "document_number": "31057466093",
            "related_party_key": "3d62f3c6-1ae5-49f9-aa5d-21a08d95aad6"
        },
        "contract": {
            "document_key": null,
            "number": "DWFR00000012",
            "urls": [],
            "signature_information": [
                {
                    "signer_name": "Dante Ferrarini",
                    "signer_document_number": "31057466093",
                    "signer_role": "issuer",
                    "signer_email": null,
                    "signer_external_key": null,
                    "signature_url": null
                }
            ]
        },
        "requester_identifier_key": "d2107ef5-19df-4183-bf0e-802b8229933c",
        "iof_charge_method": "financed",
        "collaterals": [],
        "contract_fees": [
            {
                "fee_type": "spread",
                "fee_amount": 3.05
            },
            {
                "fee_type": "spread_refinancing",
                "fee_amount": 3.02
            }
        ],
        "external_contract_fees": [
            {
                "fee_type": "tac",
                "fee_amount": 0,
                "tax_amount": 0,
                "net_fee_amount": 0
            }
        ],
        "external_contract_fee_amount": 0,
        "net_external_contract_fee_amount": 0,
        "contract_fee_amount": 6.07,
        "issue_amount": 1016.72,
        "assignment_amount": 1022.79,
        "cet": "11,1900%",
        "annual_cet": "256,9982%",
        "number_of_installments": 3,
        "base_iof": 5.23,
        "additional_iof": 3.86,
        "total_iof": 9.09,
        "ipoc_code": "324025020203131057466093DWFR00000012",
        "prefixed_interest_rate": {
            "annual_rate": 2.32,
            "created_at": "2026-04-08T00:40:30",
            "daily_rate": 0.0033387969,
            "interest_base": "calendar_days",
            "monthly_rate": 0.1051676747
        },
        "installments": [
            {
                "accrual_reference_date": null,
                "additional_costs": [],
                "advanced_paid_amount": 0,
                "bank_slip_key": null,
                "business_due_date": "2026-05-07",
                "calendar_days": 30,
                "digitable_line": null,
                "due_date": "2026-05-07",
                "due_interest": 0,
                "due_principal": 1016.72,
                "fine_amount": null,
                "has_interest": true,
                "installment_history": [],
                "installment_key": "52810e9d-0815-4fd1-ab20-d8b37dcd936e",
                "installment_number": 1,
                "installment_payment": [],
                "installment_status": "created",
                "installment_type": "principal",
                "original_due_principal": 1016.72,
                "original_pre_fixed_amount": 106.92260459,
                "original_principal_amortization_amount": 306.50739541,
                "original_total_amount": 413.43,
                "paid_amount": 0,
                "paid_at": null,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 106.92260459,
                "principal_amortization_amount": 306.50739541,
                "qr_code_key": null,
                "qr_code_url": null,
                "renegotiation_proposal_key": null,
                "tax_amount": 0.75400819,
                "total_accrual_amount": null,
                "total_amount": 413.43,
                "total_paid_amount": 0,
                "workdays": 20
            },
            {
                "accrual_reference_date": null,
                "additional_costs": [],
                "advanced_paid_amount": 0,
                "bank_slip_key": null,
                "business_due_date": "2026-06-08",
                "calendar_days": 31,
                "digitable_line": null,
                "due_date": "2026-06-07",
                "due_interest": 0,
                "due_principal": 710.21260459,
                "fine_amount": null,
                "has_interest": true,
                "installment_history": [],
                "installment_key": "2bcfe19e-9847-4c8f-be80-17f646a897c4",
                "installment_number": 2,
                "installment_payment": [],
                "installment_status": "created",
                "installment_type": "principal",
                "original_due_principal": 710.21260459,
                "original_pre_fixed_amount": 77.30856978,
                "original_principal_amortization_amount": 336.12143022,
                "original_total_amount": 413.43,
                "paid_amount": 0,
                "paid_at": null,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 77.30856978,
                "principal_amortization_amount": 336.12143022,
                "qr_code_key": null,
                "qr_code_url": null,
                "renegotiation_proposal_key": null,
                "tax_amount": 1.68127939,
                "total_accrual_amount": null,
                "total_amount": 413.43,
                "total_paid_amount": 0,
                "workdays": 20
            },
            {
                "accrual_reference_date": null,
                "additional_costs": [],
                "advanced_paid_amount": 0,
                "bank_slip_key": null,
                "business_due_date": "2026-07-07",
                "calendar_days": 30,
                "digitable_line": null,
                "due_date": "2026-07-07",
                "due_interest": 0,
                "due_principal": 374.09117437,
                "fine_amount": null,
                "has_interest": true,
                "installment_history": [],
                "installment_key": "7cf785c9-b6cf-4e9b-9c09-61d917bc72b8",
                "installment_number": 3,
                "installment_payment": [],
                "installment_status": "created",
                "installment_type": "principal",
                "original_due_principal": 374.09117437,
                "original_pre_fixed_amount": 39.33882563,
                "original_principal_amortization_amount": 374.09117437,
                "original_total_amount": 413.43,
                "paid_amount": 0,
                "paid_at": null,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 39.33882563,
                "principal_amortization_amount": 374.09117437,
                "qr_code_key": null,
                "qr_code_url": null,
                "renegotiation_proposal_key": null,
                "tax_amount": 2.79146834,
                "total_accrual_amount": null,
                "total_amount": 413.43,
                "total_paid_amount": 0,
                "workdays": 22
            }
        ],
        "total_pre_fixed_amount": 223.57
    }
}
```

:::info Observação
- O valor presente das operações listadas em `refinanced_credit_operations` será automaticamente retido para quitação dos contratos anteriores
- Apenas o excedente (diferença entre o valor desembolsado e o valor retido) será liberado na conta do tomador
- Após a criação, os contratos refinanciados serão automaticamente liquidados
- Os webhooks de emissão (assinatura, desembolso, cancelamento) seguem o mesmo padrão descrito na seção de [Webhooks da Emissão](../emissao/webhooks)
:::

---

# Introdução - Refinanciamento Crédito Clean

URL: /documentation/manual_credito_clean/refinanciamento/introducao

## Resumo

Um refinanciamento consiste na geração de um novo contrato de crédito para a quitação de um anterior. O fluxo funciona da mesma forma que uma emissão de dívida simples, porém, quando informados os valores da operação, o somatório do valor presente dos contratos anteriores será retido e apenas o excedente, caso exista, será liberado na conta do tomador.

## Fluxo do Refinanciamento

1. **Consulta de valor presente**: Consultar o valor presente da operação original para saber o montante necessário para quitação
2. **Simulação**: Simular o refinanciamento com os dados da nova operação e a referência à operação original
3. **Criação**: Criar o refinanciamento informando a lista de operações a serem quitadas em `refinanced_credit_operations`

:::info Importante
O payload utilizado tanto na simulação quanto na criação de um refinanciamento é o mesmo de uma dívida simples, com a adição da lista de operações que serão quitadas em **`refinanced_credit_operations`**.
:::

---

# Simulação - Refinanciamento Crédito Clean

URL: /documentation/manual_credito_clean/refinanciamento/simulacao

## Resumo

Antes de criar um refinanciamento, é possível simular os valores da nova operação. A simulação utiliza o mesmo payload de uma simulação de dívida simples, com a adição do campo `refinanced_credit_operations`.

## Request

ENDPOINT /debt_simulation
MÉTODO POST

Request Body

```json
{
    "borrower": {
        "person_type": "natural"
    },
    "refinanced_credit_operations": [
        {
            "operation_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c"
        }
    ],
    "financial": {
        "disbursed_amount": 1007.63,
        "interest_type": "pre_price_days",
        "credit_operation_type": "ccb",
        "annual_interest_rate": 2.32,
        "disbursement_date": "2026-04-07",
        "interest_grace_period": 0,
        "principal_grace_period": 0,
        "number_of_installments": 3,
        "fine_configuration": {
            "contract_fine_rate": 0.02,
            "interest_base": "calendar_days",
            "monthly_rate": 0.01
        }
    }
}
```

### Body Params

| Campo | Tipo | Descrição |
|---|---|---|
| **borrower*** | object | Dados do tomador (mínimo: `person_type`) |
| **refinanced_credit_operations*** | array | Lista de operações a serem refinanciadas |
| **financial*** | object | Dados financeiros da nova operação |

### Objeto refinanced_credit_operations

| Campo | Tipo | Descrição |
|---|---|---|
| `operation_key`* | string | Chave da operação a ser refinanciada (DEBT-KEY) |

## Response

STATUS 200

Response Body

```json
{
    "type": "debt",
    "key": "daa5173d-ae44-44c5-87bc-f9115cfbcaa1",
    "status": "finished",
    "event_datetime": "2026-04-08 00:36:02",
    "data": {
        "interest_type": "pre_price_days",
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "interest_payment_month_period": 1,
        "principal_grace_period": 0,
        "principal_amortization_month_period": 1,
        "operation_type": "settlement_refinancing",
        "prefixed_interest_rate": {
            "interest_base": "calendar_days_365",
            "annual_rate": 2.32,
            "monthly_rate": 0.1051676747,
            "daily_rate": 0.0032929847
        },
        "issue_date": "2026-04-07",
        "number_of_installments": 3,
        "requester_key": "78287247-947d-4730-9bd1-7efb068175b6",
        "final_disbursement_amount": 0.01,
        "refinanced_credit_operations": [
            {
                "refinanced_credit_operation_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c",
                "refinanced_credit_operation_status": "pending_payment",
                "due_balance": 1007.62,
                "due_balance_reference_date": "2026-04-07",
                "original_deadline": 61
            }
        ],
        "total_pre_fixed_amount": 220.27,
        "iof_amount": 9.09,
        "cet": 0.1103,
        "annual_cet": 2.5111,
        "disbursement_date": "2026-04-07",
        "installments": [
            {
                "calendar_days": 30,
                "workdays": 20,
                "business_due_date": "2026-05-07",
                "due_date": "2026-05-07",
                "due_principal": 1016.72,
                "has_interest": true,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 105.38950323,
                "tax_amount": 0.75507362,
                "total_amount": 412.33,
                "principal_amortization_amount": 306.94049677,
                "installment_number": 1
            },
            {
                "calendar_days": 31,
                "workdays": 20,
                "business_due_date": "2026-06-08",
                "due_date": "2026-06-07",
                "due_principal": 709.77950323,
                "has_interest": true,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 76.15320432,
                "tax_amount": 1.68155633,
                "total_amount": 412.33,
                "principal_amortization_amount": 336.17679568,
                "installment_number": 2
            },
            {
                "calendar_days": 30,
                "workdays": 22,
                "business_due_date": "2026-07-07",
                "due_date": "2026-07-07",
                "due_principal": 373.60270755,
                "has_interest": true,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 38.72729245,
                "tax_amount": 2.7878234,
                "total_amount": 412.33,
                "principal_amortization_amount": 373.60270755,
                "installment_number": 3
            }
        ],
        "external_contract_fees": [
            {
                "fee_type": "tac",
                "amount_type": "absolute",
                "amount": 0,
                "fee_amount": 0,
                "tax_amount": 0,
                "net_fee_amount": 0
            }
        ],
        "contract_fee_amount": 3.05,
        "external_contract_fee_amount": 0,
        "net_external_contract_fee_amount": 0,
        "contract_fees": [
            {
                "fee_type": "spread",
                "amount_type": "percentage",
                "amount": 0.3,
                "fee_amount": 3.05
            }
        ],
        "issue_amount": 1016.72,
        "disbursed_issue_amount": 1007.63,
        "assignment_amount": 1019.77
    }
}
```

---

# Cenários - Renegociação em Lote Crédito Clean

URL: /documentation/manual_credito_clean/renegociacao/cenarios

## Resumo

Este documento apresenta os principais cenários de renegociação em lote para operações Crédito Clean. Todos os cenários utilizam o `amortization_type: "present_amount"` e permitem aplicar descontos individuais por parcela através do campo `discount_amount` no objeto de cada installment.

:::info Lógica de Desconto por Parcela
É possível aplicar descontos diferentes em cada parcela individualmente. Basta adicionar o campo `discount_amount` (valor absoluto em reais) dentro do objeto da parcela desejada. Parcelas sem o campo `discount_amount` serão cobradas pelo valor presente integral.
:::

---

## Cenário 1: Empréstimo de 1 Parcela - Pagamento Padrão

O tomador possui um empréstimo Crédito Clean de 1 parcela e deseja quitá-lo pelo valor presente.

### Exemplo de Payload

```json
{
    "payment_type": "pix",
    "amortization_type": "present_amount",
    "proposal_due_date": "2026-04-10",
    "discount_percentage": 0,
    "reference_date": "2026-04-10",
    "request_control_key": "3571e292-3a83-4011-904d-20ee963022ef",
    "operations": [
        {
            "debt_key": "bf1175f4-750d-42b9-b264-5e7cd8c1c189",
            "installments": [
                {
                    "installment_key": "0298c572-7b6b-4db0-88d6-4bf1622d3e2d"
                }
            ]
        }
    ]
}
```

---

## Cenário 2: Empréstimo de 1 Parcela - Pagamento Sem Juros (Interest Free)

O tomador possui um empréstimo Crédito Clean de 1 parcela e negocia o pagamento sem juros. O desconto aplicado corresponde ao valor dos juros da parcela.

### Exemplo de Payload

```json
{
    "payment_type": "pix",
    "amortization_type": "present_amount",
    "proposal_due_date": "2026-04-10",
    "discount_percentage": 0,
    "reference_date": "2026-04-10",
    "request_control_key": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "operations": [
        {
            "debt_key": "bf1175f4-750d-42b9-b264-5e7cd8c1c189",
            "installments": [
                {
                    "installment_key": "0298c572-7b6b-4db0-88d6-4bf1622d3e2d",
                    "discount_amount": 54.19
                }
            ]
        }
    ]
}
```

:::info Observação
O valor do `discount_amount` (54.19) corresponde ao valor dos juros (`pre_fixed_amount`) da parcela. Dessa forma, o tomador paga apenas o valor do principal.
:::

---

## Cenário 3: Empréstimo de 1 Parcela - Pagamento Sem Juros e Sem IOF (Interest + IOF Free)

O tomador possui um empréstimo Crédito Clean de 1 parcela e negocia o pagamento sem juros e sem IOF. O desconto aplicado corresponde à soma dos juros e do IOF da parcela.

### Exemplo de Payload

```json
{
    "payment_type": "pix",
    "amortization_type": "present_amount",
    "proposal_due_date": "2026-04-10",
    "discount_percentage": 0,
    "reference_date": "2026-04-10",
    "request_control_key": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "operations": [
        {
            "debt_key": "bf1175f4-750d-42b9-b264-5e7cd8c1c189",
            "installments": [
                {
                    "installment_key": "0298c572-7b6b-4db0-88d6-4bf1622d3e2d",
                    "discount_amount": 55.44
                }
            ]
        }
    ]
}
```

:::info Observação
O valor do `discount_amount` (55.44) corresponde à soma dos juros (`pre_fixed_amount`: 54.19) + IOF (`tax_amount`: 1.25) da parcela. Dessa forma, o tomador paga apenas o valor de amortização do principal.
:::

---

## Cenário 4: Empréstimo de Múltiplas Parcelas com Desconto Individual

O tomador possui um empréstimo Crédito Clean com várias parcelas e negocia descontos diferentes para parcelas específicas. Parcelas sem o campo `discount_amount` são cobradas pelo valor presente integral.

### Exemplo de Payload

```json
{
    "payment_type": "pix",
    "amortization_type": "present_amount",
    "proposal_due_date": "2026-04-10",
    "discount_percentage": 0,
    "reference_date": "2026-04-10",
    "request_control_key": "d4e5f6a7-b8c9-0123-defa-234567890123",
    "operations": [
        {
            "debt_key": "bf1175f4-750d-42b9-b264-5e7cd8c1c189",
            "installments": [
                {
                    "installment_key": "0298c572-7b6b-4db0-88d6-4bf1622d3e2d",
                    "discount_amount": 20
                },
                {
                    "installment_key": "5e267f58-0f55-4b12-9582-63e0e9e082a8"
                },
                {
                    "installment_key": "5be492bf-b637-4999-986d-ecf423cc5dd1"
                },
                {
                    "installment_key": "15abfbfd-8608-45e9-abbb-a04c021dcf7b",
                    "discount_amount": 10
                },
                {
                    "installment_key": "c8eb83b3-5b0d-4326-947c-79279cdce2d6"
                }
            ]
        }
    ]
}
```

:::info Observação
Neste exemplo:
- Parcela 1: desconto de R$ 20,00
- Parcela 2: sem desconto (valor presente integral)
- Parcela 3: sem desconto (valor presente integral)
- Parcela 4: desconto de R$ 10,00
- Parcela 5: sem desconto (valor presente integral)
:::

---

## Cenário 5: Pagamento de Parcelas em Atraso (Overdue)

O tomador possui parcelas vencidas e deseja quitá-las. As parcelas em atraso já incluem multa e juros de mora calculados automaticamente. É possível aplicar descontos individuais para reduzir o valor.

### Exemplo de Payload

```json
{
    "payment_type": "pix",
    "amortization_type": "present_amount",
    "proposal_due_date": "2026-04-10",
    "discount_percentage": 0,
    "reference_date": "2026-04-10",
    "request_control_key": "e5f6a7b8-c9d0-1234-efab-345678901234",
    "operations": [
        {
            "debt_key": "bf1175f4-750d-42b9-b264-5e7cd8c1c189",
            "installments": [
                {
                    "installment_key": "0298c572-7b6b-4db0-88d6-4bf1622d3e2d",
                    "discount_amount": 15
                },
                {
                    "installment_key": "5e267f58-0f55-4b12-9582-63e0e9e082a8",
                    "discount_amount": 15
                }
            ]
        }
    ]
}
```

:::caution Atenção
Para parcelas em atraso, o valor presente já inclui multa (`fine_amount`) e juros de mora calculados automaticamente com base na `fine_configuration` do contrato. O `discount_amount` é aplicado sobre esse valor total.
:::

---

## Cenário 6: Múltiplas Operações com Desconto Individual por Parcela

O tomador possui empréstimos Crédito Clean em diferentes operações e deseja quitar parcelas de todas em um único pagamento, com descontos individuais.

### Exemplo de Payload

```json
{
    "payment_type": "pix",
    "amortization_type": "present_amount",
    "proposal_due_date": "2026-04-10",
    "discount_percentage": 0,
    "reference_date": "2026-04-10",
    "request_control_key": "f6a7b8c9-d0e1-2345-fabc-456789012345",
    "operations": [
        {
            "debt_key": "bf1175f4-750d-42b9-b264-5e7cd8c1c189",
            "installments": [
                {
                    "installment_key": "0298c572-7b6b-4db0-88d6-4bf1622d3e2d",
                    "discount_amount": 20
                },
                {
                    "installment_key": "5e267f58-0f55-4b12-9582-63e0e9e082a8"
                }
            ]
        },
        {
            "debt_key": "a2c3d4e5-860f-4b7a-9c1d-2e3f4a5b6c7d",
            "installments": [
                {
                    "installment_key": "7b8c9d0e-1f2a-3b4c-5d6e-7f8a9b0c1d2e",
                    "discount_amount": 30
                }
            ]
        }
    ]
}
```

---

## Objeto Installments - Campo Discount

| Campo | Tipo | Descrição | Obrigatório |
|---|---|---|---|
| `installment_key`* | string | Chave da parcela a ser renegociada | Sim |
| `discount_amount` | float | Valor de desconto em reais (R$) aplicado individualmente na parcela | Não |

:::info Sobre o campo discount_amount
- O campo `discount_amount` é **opcional** e pode ser informado em qualquer parcela
- O valor é um **desconto absoluto em reais** (não percentual)
- Parcelas sem o campo `discount_amount` são cobradas pelo **valor presente integral**
- O desconto é aplicado sobre o valor presente da parcela na `reference_date`
:::

---

## Tabela Resumo dos Cenários

| Cenário | Descrição | Discount |
|---|---|---|
| 1 parcela - padrão | Pagamento pelo valor presente | Sem desconto |
| 1 parcela - interest free | Desconto = valor dos juros | `discount_amount` = `pre_fixed_amount` |
| 1 parcela - interest + IOF free | Desconto = juros + IOF | `discount_amount` = `pre_fixed_amount` + `tax_amount` |
| Múltiplas parcelas | Descontos individuais por parcela | `discount_amount` por parcela |
| Parcelas em atraso | Parcelas vencidas com multa/mora | `discount_amount` opcional |
| Múltiplas operações | Operações diferentes em um lote | `discount_amount` por parcela |

---

## Regras Importantes

:::caution Regras da Renegociação em Lote
- Todas as operações devem ser do **mesmo emitente** e mesma **chave de integração**
- Limite de **50 operações** por lote
- Um único meio de pagamento (boleto/Pix) é gerado para o valor total do lote
- Se uma parcela incluída no lote for paga por fora antes da confirmação, o lote é **rejeitado**
- Se o pagamento não for realizado até a `proposal_due_date`, o lote é **rejeitado**
- O `amortization_type` utilizado é sempre `present_amount`
- O campo `discount_amount` é aplicado **individualmente por parcela**
:::

---

# Consulta - Renegociação em Lote Crédito Clean

URL: /documentation/manual_credito_clean/renegociacao/consulta

## Resumo

É possível consultar o status e detalhes de uma proposta de renegociação em lote, utilizando a `batch_proposal_key` ou a `request_control_key`.

---

## Consultar por Batch Proposal Key

ENDPOINT /renegotiation/batch_proposal/ BATCH-PROPOSAL-KEY
MÉTODO GET

### Path Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `batch_proposal_key`* | string | Chave da proposta de renegociação em lote | UUID |

### Response

STATUS 200

Response Body

```json
{
    "batch_proposal_key": "ff5ad6dd-2087-4850-a3e8-b37634448b4e",
    "discount_percentage": 0,
    "discount_amount": 0,
    "amortization_type": "installment_payment",
    "payment_amount": 517.88,
    "requester_name": "Dante Ltda",
    "requester_key": "78287247-947d-4730-9bd1-7efb068175b6",
    "issuer_name": "Dante Ferrarini",
    "reference_date": "2026-04-08",
    "issuer_document_number": "31057466093",
    "batch_proposal_status": "pending_payment",
    "proposal_due_date": "2026-04-15",
    "payment_type": "pix",
    "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db",
    "origin_key": null,
    "operations": [
        {
            "requester_key": "78287247-947d-4730-9bd1-7efb068175b6",
            "contract_number": "DWF1761222116",
            "payment_amount": 517.88,
            "discount_amount": 0,
            "origin_key": null,
            "affected_installments": [
                {
                    "installment_key": "1dea396f-beb1-4df3-9822-35800b4c095a",
                    "due_date": "2026-05-07",
                    "principal_amount": 491.49,
                    "interest_amount": 52.4,
                    "fine_amount": 0,
                    "total_amount": 543.89,
                    "present_amount": 517.88,
                    "paid_amount": 517.88,
                    "principal_amortization_payment_amount": 491.49,
                    "prefixed_interest_payment_amount": 26.39,
                    "fine_payment_amount": 0,
                    "discount_amount": 0
                }
            ],
            "remaining_installments": [
                {
                    "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999",
                    "due_date": "2026-06-07",
                    "principal_amount": 516.13,
                    "interest_amount": 27.76,
                    "fine_amount": 0,
                    "total_amount": 543.89
                }
            ],
            "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c"
        }
    ],
    "payment": {
        "digitable_line": null,
        "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/acaeb341e1264cde99b93e247e12b3725204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***63043AD0",
        "qr_code_key": "acaeb341-e126-4cde-99b9-3e247e12b372",
        "bank_slip_key": null,
        "paid_method_type": "pix",
        "source_account_key": null,
        "payment_data": {
            "creditor_bank_account_key": "6108dd45-580d-48c4-b3bb-74c1e843be49",
            "batch_renegotiation_proposal_key": "ff5ad6dd-2087-4850-a3e8-b37634448b4e"
        }
    }
}
```

---

## Consultar por Request Control Key

ENDPOINT /renegotiation/batch_proposal/request_control_key/ REQUEST-CONTROL-KEY
MÉTODO GET

### Path Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `request_control_key`* | string | Chave de controle da requisição | UUID |

### Response

A resposta segue o mesmo formato da consulta por `batch_proposal_key`.

---

## Listar Renegociações em Lote

ENDPOINT /renegotiation/batch_proposal
MÉTODO GET

### Query Params

| Campo | Tipo | Descrição |
|---|---|---|
| `batch_proposal_status` | string | Filtrar por status da proposta em lote |
| `issuer_document_number` | string | Filtrar por CPF/CNPJ do emitente |
| `request_control_key` | string | Filtrar por chave de controle |

### Response

STATUS 200

Response Body

```json
{
    "data": [
        {
            "batch_proposal_key": "ff5ad6dd-2087-4850-a3e8-b37634448b4e",
            "discount_percentage": 0,
            "discount_amount": 0,
            "amortization_type": "installment_payment",
            "payment_amount": 517.88,
            "requester_name": "Dante Ltda",
            "requester_key": "78287247-947d-4730-9bd1-7efb068175b6",
            "issuer_name": "Dante Ferrarini",
            "reference_date": "2026-04-08",
            "issuer_document_number": "31057466093",
            "batch_proposal_status": "pending_payment",
            "proposal_due_date": "2026-04-15",
            "payment_type": "pix",
            "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db",
            "origin_key": null
        }
    ],
    "pagination": {
        "current_page": 1,
        "next_page": 2,
        "rows_per_page": 10,
        "total_pages": 150,
        "total_rows": 1495
    }
}
```

---

## Cancelar uma Renegociação em Lote

ENDPOINT /renegotiation/batch_proposal/ BATCH-PROPOSAL-KEY
MÉTODO DELETE

### Path Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `batch_proposal_key`* | string | Chave da proposta de renegociação em lote a ser cancelada | UUID |

### Response

STATUS 204

Response Body

```json
{}
```

:::caution Atenção
Somente propostas com status `pending_payment` podem ser canceladas.
:::

---

# Proposta de Renegociação em Lote - Crédito Clean

URL: /documentation/manual_credito_clean/renegociacao/proposta

## Resumo

Após simular os valores, é possível criar uma proposta de renegociação em lote para múltiplas operações Crédito Clean. A proposta gera um único meio de pagamento (boleto e/ou Pix) que cobre todas as operações incluídas no lote.

Para o tipo de amortização **`present_amount`**, cada parcela informada em `operations[].installments[]` deve incluir **`paid_amount`** (valor pago/alocado naquela parcela) e **`discount_amount`** (desconto em R$ aplicado na parcela), além de **`installment_key`**.

:::caution Atenção
A renegociação em lote só pode ser criada com operações de um mesmo emitente e mesma chave de integração. Há um limite de **50 operações** para cada renegociação em lote.
:::

## Request

ENDPOINT /renegotiation/batch_proposal
MÉTODO POST

:::warning Atenção
Os campos `discount_amount` e `discount_percentage` **NÃO** podem ser enviados juntos no mesmo payload (nível raiz).
:::

:::info Nota
Na raiz do body, `discount_amount` e `discount_percentage` são alternativas para desconto global sobre o valor presente. Já os campos **`paid_amount`** e **`discount_amount`** dentro de cada objeto em `operations[].installments[]` definem a composição por parcela quando `amortization_type` é **`present_amount`** (são obrigatórios nesse modo e não conflitam com a regra da raiz).
:::

Request Body

```json
{
    "amortization_type": "present_amount",
    "reference_date": "2026-04-08",
    "proposal_due_date": "2026-04-15",
    "discount_percentage": 0.0,
    "payment_type": "pix",
    "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db",
    "operations": [
        {
            "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
            "installments": [
                {
                    "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88",
                    "paid_amount": 500,
                    "discount_amount": 50
                }
            ]
        },
        {
            "debt_key": "2cbfb9b1-1fdb-5f8d-9967-b338e5eb83f9",
            "installments": [
                {
                    "installment_key": "2ef25ed8-7124-44f5-9e3d-1d1a7196166e",
                    "paid_amount": 150,
                    "discount_amount": 10
                }
            ]
        }
    ]
}
```

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `amortization_type`* | string | Tipo de amortização | **[Enumeradores Amortization Type](#enumeradores-amortization-type)** |
| `reference_date`* | string | Data de referência para cálculo do valor presente (D+1) | 10 |
| `proposal_due_date`* | string | Data de vencimento da proposta de renegociação | 10 |
| `payment_type`* | string | Tipo de pagamento | **[Enumeradores Payment Type](#enumeradores-payment-type)** |
| `request_control_key` | string | Chave de controle para rastreamento e identificação única (opcional) | UUID |
| `discount_percentage` | float | Percentual de desconto sobre o valor presente | 10 |
| `discount_amount` | float | Valor de desconto sobre o valor presente | 10 |
| `operations`* | array | Lista de operações a serem renegociadas | **[Objeto Operations](#objeto-operations)** |

### Objeto Operations

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `debt_key`* | string | Chave única da operação de crédito (DEBT-KEY) | UUID |
| `installments`* | array | Parcelas a serem renegociadas | **[Objeto Installments](#objeto-installments)** |

### Objeto Installments

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `installment_key`* | string | Chave da parcela a ser renegociada | UUID |
| `paid_amount` | float | Valor pago (ou alocado) na parcela, em reais (R$). Obrigatório quando `amortization_type` é **`present_amount`**. | 15,2 |
| `discount_amount` | float | Valor de desconto em reais (R$) aplicado na parcela. Obrigatório quando `amortization_type` é **`present_amount`** (use `0` se não houver desconto). Para outros tipos de amortização, permanece opcional por parcela. | 15,2 |

### Enumeradores Payment Type

| Campo | Descrição |
|---|---|
| `bank_slip` | Pagamento via boleto bancário (gera boleto e Pix) |
| `pix` | Pagamento via Pix (gera apenas Pix) |
| `internal` | Pagamento via transferência interna (processamento automático) |
| `manual` | Pagamento feito de forma manual (não gera forma de pagamento) |

### Enumeradores Amortization Type

| Campo | Descrição |
|---|---|
| **present_amount** | Renegociação com composição por valor presente por parcela. Em cada item de `installments[]` é obrigatório informar `installment_key`, **`paid_amount`** e **`discount_amount`**. |
| **installment_payment** | Renegociação para pagamento de parcelas específicas. Requer `installment_key` de cada parcela. |
| **overdue_installment_payment** | Renegociação direcionada para pagamento de parcelas em atraso. Requer `installment_key` de cada parcela. |

## Response

STATUS 201

Response Body

```json
{
    "batch_proposal_key": "ff5ad6dd-2087-4850-a3e8-b37634448b4e",
    "discount_percentage": 0,
    "discount_amount": 0,
    "amortization_type": "present_amount",
    "payment_amount": 517.88,
    "requester_name": "Dante Ltda",
    "requester_key": "78287247-947d-4730-9bd1-7efb068175b6",
    "issuer_name": "Dante Ferrarini",
    "reference_date": "2026-04-08",
    "issuer_document_number": "31057466093",
    "batch_proposal_status": "pending_payment",
    "proposal_due_date": "2026-04-15",
    "payment_type": "pix",
    "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db",
    "origin_key": null,
    "operations": [
        {
            "requester_key": "78287247-947d-4730-9bd1-7efb068175b6",
            "contract_number": "DWF1761222116",
            "payment_amount": 517.88,
            "discount_amount": 0,
            "origin_key": null,
            "affected_installments": [
                {
                    "installment_key": "1dea396f-beb1-4df3-9822-35800b4c095a",
                    "due_date": "2026-05-07",
                    "principal_amount": 491.49,
                    "interest_amount": 52.4,
                    "fine_amount": 0,
                    "total_amount": 543.89,
                    "present_amount": 517.88,
                    "paid_amount": 517.88,
                    "principal_amortization_payment_amount": 491.49,
                    "prefixed_interest_payment_amount": 26.39,
                    "fine_payment_amount": 0,
                    "discount_amount": 0
                }
            ],
            "remaining_installments": [
                {
                    "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999",
                    "due_date": "2026-06-07",
                    "principal_amount": 516.13,
                    "interest_amount": 27.76,
                    "fine_amount": 0,
                    "total_amount": 543.89
                }
            ],
            "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c"
        }
    ],
    "payment": {
        "digitable_line": null,
        "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/acaeb341e1264cde99b93e247e12b3725204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***63043AD0",
        "qr_code_key": "acaeb341-e126-4cde-99b9-3e247e12b372",
        "bank_slip_key": null,
        "paid_method_type": "pix",
        "source_account_key": null,
        "payment_data": {
            "creditor_bank_account_key": "6108dd45-580d-48c4-b3bb-74c1e843be49",
            "batch_renegotiation_proposal_key": "ff5ad6dd-2087-4850-a3e8-b37634448b4e"
        }
    }
}
```

:::info Importante
Salve a **batch_proposal_key** retornada na resposta. Ela será necessária para consultar o status da renegociação em lote e para receber os webhooks de pagamento.
:::

---

# Simulação - Renegociação em Lote Crédito Clean

URL: /documentation/manual_credito_clean/renegociacao/simulacao

## Resumo

Antes de criar uma proposta de renegociação, é possível simular os valores da renegociação em lote para operações Crédito Clean. A simulação permite visualizar as parcelas afetadas, valores de desconto e o montante final a ser pago para múltiplas operações simultaneamente.

Com **`amortization_type`** igual a **`present_amount`**, envie em cada parcela de `operations[].installments[]` os campos **`paid_amount`**, **`discount_amount`** e **`installment_key`**, como na proposta em lote.

:::caution Atenção
A renegociação em lote só pode ser criada com operações de um mesmo emitente e mesma chave de integração. Há um limite de **50 operações** para cada renegociação em lote.
:::

## Request

ENDPOINT /renegotiation/batch_proposal_simulation
MÉTODO POST

:::warning Atenção
Os campos `discount_amount` e `discount_percentage` **NÃO** podem ser enviados juntos no mesmo payload (nível raiz).
:::

:::info Nota
Na raiz, `discount_amount` e `discount_percentage` são alternativas para desconto global. Os campos **`paid_amount`** e **`discount_amount`** em `operations[].installments[]` são usados com **`present_amount`** por parcela e não substituem a regra da raiz.
:::

Request Body

```json
{
    "amortization_type": "present_amount",
    "reference_date": "2026-04-08",
    "discount_percentage": 0.0,
    "operations": [
        {
            "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
            "installments": [
                {
                    "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88",
                    "paid_amount": 500,
                    "discount_amount": 50
                }
            ]
        },
        {
            "debt_key": "2cbfb9b1-1fdb-5f8d-9967-b338e5eb83f9",
            "installments": [
                {
                    "installment_key": "2ef25ed8-7124-44f5-9e3d-1d1a7196166e",
                    "paid_amount": 150,
                    "discount_amount": 10
                }
            ]
        }
    ]
}
```

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `amortization_type`* | string | Tipo de amortização | **[Enumeradores Amortization Type](#enumeradores-amortization-type)** |
| `reference_date`* | string | Data de referência para cálculo do valor presente (precisa ser D+1) | 10 |
| `discount_percentage` | float | Percentual de desconto sobre o valor presente ((1 - percentual) * Valor Presente) | 10 |
| `discount_amount` | float | Valor de desconto aplicado sobre o valor presente | 10 |
| `operations`* | array | Lista de operações a serem renegociadas | **[Objeto Operations](#objeto-operations)** |

### Objeto Operations

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `debt_key`* | string | Chave única da operação de crédito (DEBT-KEY) | UUID |
| `installments`* | array | Parcelas a serem renegociadas | **[Objeto Installments](#objeto-installments)** |

### Objeto Installments

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `installment_key`* | string | Chave da parcela a ser renegociada | UUID |
| `paid_amount` | float | Valor pago (ou alocado) na parcela, em reais (R$). Obrigatório quando `amortization_type` é **`present_amount`**. | 15,2 |
| `discount_amount` | float | Valor de desconto em reais (R$) na parcela. Obrigatório quando `amortization_type` é **`present_amount`** (use `0` se não houver desconto). Opcional nos demais tipos. | 15,2 |

### Enumeradores Amortization Type

| Campo | Descrição |
|---|---|
| **present_amount** | Simulação com valor presente por parcela. Em cada `installments[]` é obrigatório `installment_key`, **`paid_amount`** e **`discount_amount`**. |
| **installment_payment** | Renegociação para pagamento de parcelas específicas enviadas no payload. Requer `installment_key` de cada parcela. |
| **overdue_installment_payment** | Renegociação direcionada para pagamento de parcelas em atraso. Requer `installment_key` de cada parcela. |

## Response

STATUS 200

Response Body

```json
{
    "batch_proposal_key": "7423c701-3578-4733-8f30-81ab60afdb6d",
    "discount_percentage": 0,
    "discount_amount": 0,
    "amortization_type": "present_amount",
    "payment_amount": 517.88,
    "requester_name": "Dante Ltda",
    "requester_key": "78287247-947d-4730-9bd1-7efb068175b6",
    "issuer_name": "Dante Ferrarini",
    "reference_date": "2026-04-08",
    "issuer_document_number": "31057466093",
    "operations": [
        {
            "requester_key": "78287247-947d-4730-9bd1-7efb068175b6",
            "contract_number": "DWF1761222116",
            "payment_amount": 517.88,
            "discount_amount": 0,
            "origin_key": null,
            "affected_installments": [
                {
                    "installment_key": "1dea396f-beb1-4df3-9822-35800b4c095a",
                    "due_date": "2026-05-07",
                    "principal_amount": 491.4903841,
                    "interest_amount": 52.3996159,
                    "fine_amount": 0,
                    "total_amount": 543.89,
                    "present_amount": 517.88,
                    "paid_amount": 517.88,
                    "principal_amortization_payment_amount": 491.49,
                    "prefixed_interest_payment_amount": 26.39,
                    "fine_payment_amount": 0,
                    "discount_amount": 0
                }
            ],
            "remaining_installments": [
                {
                    "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999",
                    "due_date": "2026-06-07",
                    "principal_amount": 516.1296159,
                    "interest_amount": 27.7603841,
                    "fine_amount": 0,
                    "total_amount": 543.89
                }
            ],
            "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c"
        }
    ]
}
```

### Campos de Desconto

Desconto percentual

```json
{
    "discount_percentage": 0.5
}
```

Desconto absoluto

```json
{
    "discount_amount": 200
}
```

---

# Webhooks - Renegociação em Lote Crédito Clean

URL: /documentation/manual_credito_clean/renegociacao/webhooks

## Resumo

Após a criação de uma proposta de renegociação, o sistema enviará webhooks para notificar sobre o pagamento ou rejeição da proposta. Esta página cobre tanto as propostas individuais (`renegotiation.proposal`) quanto as propostas em lote (`renegotiation.batch_proposal`).

---

## Webhook de Pagamento — Proposta Individual

Enviado quando uma proposta de renegociação individual é paga.

WEBHOOK_TYPE renegotiation.proposal
STATUS paid

Webhook Body

```json
{
    "webhook_type": "renegotiation.proposal",
    "key": "<PROPOSAL-KEY>",
    "event_datetime": "<DATA E HORA DO ENVIO DO WEBHOOK>",
    "status": "paid",
    "data": {
        "paid_method_type": "<METODO DE PAGAMENTO>",
        "paid_in": {
            "code_number": "<CODIGO DO BANCO LIQUIDANTE>",
            "ispb": "<ISPB DO BANCO LIQUIDANTE>",
            "name": "<NOME DO BANCO LIQUIDANTE>"
        }
    }
}
```

### Campos do Webhook de Proposta Individual

| Campo | Tipo | Descrição |
|---|---|---|
| **webhook_type** | string | Tipo do webhook: `renegotiation.proposal` |
| **key** | string | Chave da proposta de renegociação (PROPOSAL-KEY) |
| **event_datetime** | string | Data e hora do envio do webhook |
| **status** | string | Status do evento: `paid` |
| **data.paid_method_type** | string | Método de pagamento utilizado |
| **data.paid_in.code_number** | string | Código do banco liquidante |
| **data.paid_in.ispb** | string | ISPB do banco liquidante |
| **data.paid_in.name** | string | Nome do banco liquidante |

### Enumeradores paid_method_type

| Enumerador | Descrição |
|---|---|
| **bank_slip** | Pagamento realizado por boleto |
| **pix** | Pagamento realizado por Pix |

---

## Webhooks — Proposta em Lote

Após a criação de uma proposta de renegociação em lote, o sistema enviará webhooks para notificar sobre o pagamento ou rejeição da proposta.

:::danger Atenção!
Os webhooks não devem ser mapeados de forma estrita. Novos campos podem ser adicionados ao payload sem aviso prévio.
:::

## Webhook de Pagamento

Este webhook é enviado quando o pagamento da proposta de renegociação em lote é confirmado.

WEBHOOK_TYPE renegotiation.batch_proposal
STATUS paid

Webhook Body

```json
{
    "webhook_type": "renegotiation.batch_proposal",
    "key": "<BATCH-PROPOSAL-KEY>",
    "event_datetime": "<DATA E HORA DO ENVIO DO WEBHOOK>",
    "status": "paid",
    "data": {
        "paid_method_type": "<METODO DE PAGAMENTO>",
        "paid_in": {
            "code_number": "<CODIGO DO BANCO LIQUIDANTE>",
            "ispb": "<ISPB DO BANCO LIQUIDANTE>",
            "name": "<NOME DO BANCO LIQUIDANTE>"
        }
    }
}
```

### Campos do Webhook de Pagamento

| Campo | Tipo | Descrição |
|---|---|---|
| **webhook_type** | string | Tipo do webhook: `renegotiation.batch_proposal` |
| **key** | string | Chave da proposta de renegociação em lote (BATCH-PROPOSAL-KEY) |
| **event_datetime** | string | Data e hora do envio do webhook |
| **status** | string | Status do evento: `paid` |
| **data.paid_method_type** | string | Método de pagamento utilizado |
| **data.paid_in.code_number** | string | Código do banco liquidante |
| **data.paid_in.ispb** | string | ISPB do banco liquidante |
| **data.paid_in.name** | string | Nome do banco liquidante |

### Enumeradores paid_method_type

| Enumerador | Descrição |
|---|---|
| **bank_slip** | Pagamento realizado por boleto |
| **pix** | Pagamento realizado por Pix |

---

## Webhook de Rejeição

Uma renegociação em lote pode ser rejeitada pelo decurso de prazo do pagamento ou por um pagamento de parcela por fora da renegociação.

WEBHOOK_TYPE renegotiation.batch_proposal
STATUS rejected

Webhook Body

```json
{
    "webhook_type": "renegotiation.batch_proposal",
    "key": "<BATCH-PROPOSAL-KEY>",
    "event_datetime": "<DATA E HORA DO ENVIO DO WEBHOOK>",
    "status": "rejected",
    "data": {}
}
```

:::caution Atenção
Uma renegociação em lote pode ser rejeitada por:
- **Decurso de prazo**: o pagamento não foi realizado dentro da data de vencimento (`proposal_due_date`)
- **Pagamento externo**: uma parcela incluída na renegociação foi paga por fora antes da confirmação do pagamento do lote
:::

---

## Dados de Pagamento na Parcela

Quando uma parcela é paga através de uma renegociação em lote, os dados de pagamento são registrados na parcela:

Payment Data

```json
{
    "batch_renegotiation_proposal_key": "f9addba2-ec91-41bf-a150-c59eb1c3fbef",
    "paid_in": {
        "ispb": "18236120",
        "name": "NU PAGAMENTOS - IP",
        "code_number": 260
    },
    "resource_account_key": "ea44b9f2-ad00-4896-b8a3-b1a3da28a72f"
}
```

### Campos dos Dados de Pagamento

| Campo | Tipo | Descrição |
|---|---|---|
| **batch_renegotiation_proposal_key** | string | Chave da proposta de renegociação em lote que originou o pagamento |
| **paid_in.ispb** | string | ISPB do banco utilizado para o pagamento |
| **paid_in.name** | string | Nome do banco utilizado para o pagamento |
| **paid_in.code_number** | integer | Código do banco utilizado para o pagamento |
| **resource_account_key** | string | Chave da conta de recursos que recebeu o pagamento |

---

# Scripts de Integração - Crédito Clean

URL: /documentation/manual_credito_clean/scripts_integracao

## Resumo

Disponibilizamos scripts Python prontos para uso que demonstram o fluxo completo de integração Crédito Clean com a API Sandbox da QI Tech. Cada script corresponde a uma chamada de API testada e validada.

**Todos os payloads e respostas exibidos nesta documentação refletem as respostas reais da API Sandbox, obtidas através destes scripts.**

## Download

Os scripts estão disponíveis no repositório do projeto:

📦 Baixar pacote Python completo

## Pre-requisitos

- Python 3.8+
- Dependencias: `requests`, `python-jose`, `python-dotenv`
- Arquivo `_local.env` com suas credenciais Sandbox:
  - `API_KEY` - Sua chave de API
  - `QI_PUBLIC_KEY` - Chave publica da QI Tech
  - `CLIENT_PRIVATE_KEY` - Sua chave privada EC (PEM)

## Scripts Disponiveis

### Emissao

| # | Script | Endpoint | Metodo | Descricao |
|---|--------|----------|--------|-----------|
| 01 | `01_issuance_simulation.py` | `/v2/credit_operation/simulation` | POST | Simular uma operacao de credito antes da emissao |
| 02 | `02_issuance_issuance.py` | `/signed_debt` | POST | Emitir a divida com assinatura de contrato via opt-in |
| 03 | `03_issuance_query.py` | `/v2/credit_operation/requester_identifier_key/{key}` | GET | Consultar a operacao emitida |

### Estorno

| # | Script | Endpoint | Metodo | Descricao |
|---|--------|----------|--------|-----------|
| 04 | `04_reversal_cancel_before_disbursement.py` | `/debt/{debt_key}/cancel` | PATCH | Cancelar operacao antes do desembolso |
| 05 | `05_reversal_cancel_after_disbursement.py` | `/debt/reversal` | POST | Estornar operacao apos desembolso (gera Pix de devolucao) |

### Renegociacao

| # | Script | Endpoint | Metodo | Descricao |
|---|--------|----------|--------|-----------|
| 06 | `06_renegotiation_simulation.py` | `/renegotiation/batch_proposal_simulation` | POST | Simular renegociacao em lote |
| 07 | `07_renegotiation_proposal.py` | `/renegotiation/batch_proposal` | POST | Criar proposta de renegociacao em lote |
| 08 | `08_renegotiation_query.py` | `/renegotiation/batch_proposal/{key}` | GET | Consultar proposta por chave |
| 09 | `09_renegotiation_list.py` | `/renegotiation/batch_proposal` | GET | Listar todas as propostas |
| 10 | `10_renegotiation_cancel.py` | `/renegotiation/batch_proposal/{key}` | DELETE | Cancelar proposta pendente |

### Refinanciamento

| # | Script | Endpoint | Metodo | Descricao |
|---|--------|----------|--------|-----------|
| 11 | `11_refinancing_present_value.py` | `/debt` | GET | Consultar valor presente para calculo de refinanciamento |
| 12 | `12_refinancing_simulation.py` | `/debt_simulation` | POST | Simular operacao de refinanciamento |
| 13 | `13_refinancing_issuance.py` | `/signed_debt` | POST | Criar refinanciamento (emite nova divida, liquida a anterior) |

## Como Usar

1. Baixe os scripts do repositorio
2. Crie um arquivo `_local.env` com suas credenciais Sandbox
3. Execute os scripts em ordem numerica
4. Atualize as chaves (`DEBT_KEY`, `BATCH_PROPOSAL_KEY`, etc.) entre os scripts conforme necessario

:::info Sobre os exemplos da documentacao
Cada script inclui a resposta real da API como bloco de comentario no final do arquivo. Esses exemplos sao a fonte de verdade para os payloads exibidos nas paginas desta documentacao.
:::

---

# Emissão de Dívida PJ com Assinatura Imediata

URL: /documentation/manual_emissao_pj_signed_debt/emissao_signed_debt_pj

Este endpoint realiza a emissão da dívida para uma **pessoa jurídica** e processa a assinatura do contrato via opt-in em uma única chamada. O desembolso ocorre na data informada no campo `disbursement_date`, que pode ser diferente da data de emissão.

Não é necessário realizar o cadastro prévio do tomador: basta fornecer os dados cadastrais da empresa e de seus representantes legais no momento da requisição de emissão.

:::info Pré-requisito — upload de documentos
Os documentos da empresa e dos representantes (estatuto/contrato social, documentos de identificação, etc.) devem ser enviados previamente via [upload de documentos](../upload_de_documentos/upload_de_documentos). Cada upload retorna uma `document_key` (UUID), que deve ser referenciada nos campos correspondentes do request.
:::

:::danger Atenção — Onboarding e Antifraude
A QI Tech oferece uma solução de Onboarding de novos clientes e Antifraude.

[Confira aqui a documentação das APIs deste serviço.](https://www.zaig.com.br/en/devcenter.html)

Para receber uma cotação, entre em contato com nosso time comercial: comercial@qitech.com.br ou (11) 3522-1301
:::

O formato de assinatura do header e do body desta requisição é descrito em detalhes [aqui](../primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2).

## Simulação de dívida

Antes de emitir, é possível **simular** os valores da operação de crédito. A simulação segue o mesmo padrão da emissão, porém **não exige** os dados cadastrais do tomador nem a conta de desembolso — basta informar `borrower.person_type` (`legal` para PJ) e o objeto `financial`. O exemplo abaixo simula com base no **valor desembolsado** (`disbursed_amount` + `number_of_installments`).

ENDPOINT /debt_simulation
MÉTODO POST

### Request

Request Body

```json
{
    "borrower": {
        "person_type": "legal"
    },
    "financial": {
        "interest_type": "pre_price_days",
        "disbursement_date": "2026-04-07",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "disbursed_amount": 10000,
        "monthly_interest_rate": 0.03,
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "number_of_installments": 2,
        "principal_grace_period": 0
    }
}
```

#### Campos do Request

| Campo | Tipo | Descrição |
|---|---|---|
| borrower.person_type* | enum | Natureza jurídica do tomador — usar `legal` para PJ |
| financial.interest_type* | enum | Método de amortização — **[Enumerador Interest Type](#enumerador-interest-type)** |
| financial.credit_operation_type* | enum | Tipo do contrato de crédito — **[Enumerador Credit Operation Type](#enumerador-credit-operation-type)** |
| financial.disbursed_amount* | float | Valor desembolsado da operação |
| financial.monthly_interest_rate* | float | Taxa de juros mensal pré-fixada (em decimal) |
| financial.number_of_installments* | int | Número de parcelas |
| financial.disbursement_date | date | Data do desembolso (YYYY-MM-DD) |
| financial.interest_grace_period | int | Carência de juros (em meses) |
| financial.principal_grace_period | int | Carência do principal (em meses) |
| financial.fine_configuration | object | Configuração de multa e mora — **[Objeto Fine Configuration](#objeto-fine-configuration)** |

### Response

Response Body

```json
{
    "type": "debt",
    "key": "bf84379c-d4cf-4f16-a63c-865c129e6fce",
    "status": "finished",
    "event_datetime": "2026-04-07 23:59:28",
    "data": {
        "interest_type": "pre_price_days",
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0,
        "prefixed_interest_rate": {
            "interest_base": "calendar_days",
            "annual_rate": 0.42576089,
            "monthly_rate": 0.03,
            "daily_rate": 0.00097227
        },
        "issue_date": "2026-04-07",
        "number_of_installments": 2,
        "final_disbursement_amount": 10000,
        "total_pre_fixed_amount": 453.94,
        "iof_amount": 51.07,
        "cet": 0.0335,
        "annual_cet": 0.4851,
        "disbursement_date": "2026-04-07",
        "issue_amount": 10076.2,
        "disbursed_issue_amount": 10000,
        "assignment_amount": 10106.4,
        "installments": [
            {
                "calendar_days": 30,
                "workdays": 20,
                "business_due_date": "2026-05-07",
                "due_date": "2026-05-07",
                "due_principal": 10076.2,
                "has_interest": true,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 52.4,
                "tax_amount": 12.49,
                "total_amount": 5226.97,
                "principal_amortization_amount": 5174.57,
                "installment_number": 1
            },
            {
                "calendar_days": 31,
                "workdays": 20,
                "business_due_date": "2026-06-08",
                "due_date": "2026-06-07",
                "due_principal": 4901.63,
                "has_interest": true,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 27.76,
                "tax_amount": 26.09,
                "total_amount": 5226.97,
                "principal_amortization_amount": 4901.63,
                "installment_number": 2
            }
        ]
    }
}
```

#### Campos do Response

A simulação não gera dívida nem retorna **DEBT-KEY**: o campo `key` é apenas o identificador da simulação e o `status` é `finished`. Os valores ficam dentro de `data`.

| Campo | Tipo | Descrição |
|---|---|---|
| disbursed_issue_amount | float | Valor desembolsado informado na simulação |
| final_disbursement_amount | float | Valor efetivamente desembolsado para o tomador |
| issue_amount | float | Valor de emissão/nominal da operação |
| assignment_amount | float | Valor de aquisição (cessão) da operação |
| cet | float | Custo Efetivo Total mensal (em decimal) |
| annual_cet | float | Custo Efetivo Total anual (em decimal) |
| iof_amount | float | Valor total do IOF |
| total_pre_fixed_amount | float | Total de juros pré-fixados da operação |
| prefixed_interest_rate | object | Taxa de juros nominal (anual, diária, mensal e base de cálculo) |
| installments | array | Parcelas simuladas (data, valor, amortização, juros e IOF de cada parcela) |

## Emissão de dívida

ENDPOINT /signed_debt
MÉTODO POST

Testar no Playground

### Request

#### Payload recomendado (PJ + PIX)

Este é o corpo recomendado para emitir uma dívida de pessoa jurídica com desembolso via PIX. Além dos dados cadastrais, ele inclui a **evidência de assinatura (opt-in)** em `additional_data.contract.signatures`, que é necessária para a emissão ser concluída com sucesso.

```json
{
    "borrower": {
        "person_type": "legal",
        "name": "RAZAO SOCIAL EMPRESA",
        "phone": { "country_code": "055", "area_code": "11", "number": "991112222" },
        "address": {
            "street": "Rua Gilberto Sabino",
            "number": "215",
            "neighborhood": "Pinheiros",
            "city": "São Paulo",
            "state": "SP",
            "postal_code": "05425020"
        },
        "company_document_number": "80282008000127",
        "company_statute": "2d9b7271-8dfd-43d5-9aee-d2814b98cb9e",
        "company_representatives": [
            {
                "person_type": "natural",
                "name": "NOME DO REPRESENTANTE",
                "phone": { "country_code": "055", "area_code": "11", "number": "990121234" },
                "address": {
                    "street": "Rua Gilberto Sabino",
                    "number": "215",
                    "neighborhood": "Pinheiros",
                    "city": "São Paulo",
                    "state": "SP",
                    "postal_code": "05425020"
                },
                "is_pep": false,
                "individual_document_number": "31057466093"
            }
        ]
    },
    "financial": {
        "disbursed_amount": 10000,
        "interest_type": "pre_price_days",
        "credit_operation_type": "ccb",
        "number_of_installments": 1,
        "interest_grace_period": 0,
        "principal_grace_period": 0,
        "monthly_interest_rate": 0.03,
        "disbursement_date": "2026-06-23",
        "first_due_date": "2026-07-23",
        "fine_configuration": {
            "contract_fine_rate": 0.02,
            "monthly_rate": 0.01,
            "interest_base": "calendar_days_365"
        }
    },
    "additional_data": {
        "contract": {
            "contract_number": "STN92924220",
            "signatures": [
                {
                    "signer": {
                        "name": "NOME DO REPRESENTANTE",
                        "email": "representante@test.com",
                        "document_number": "32402502000135",
                        "phone": { "country_code": "011", "area_code": "55", "number": "991112222" }
                    },
                    "signature": {
                        "ip_address": "192.168.1.1",
                        "signature_file": {
                            "file_type": "pdf",
                            "file_url": "https://qitech.com.br/signature.pdf"
                        }
                    }
                }
            ]
        }
    },
    "disbursement_bank_accounts": [
        {
            "pix_key": "2f205c99-3161-4120-badd-854039d12de6",
            "pix_transfer_type": "key"
        }
    ],
    "purchaser_document_number": "32402502000135",
    "requester_identifier_key": "3eb8d228-ed17-4352-a081-1d1f3a35334c",
    "simplified": true
}
```

:::info Observações importantes
- O bloco `additional_data.contract.signatures` (opt-in) é **necessário** para a emissão. Enviar `additional_data` vazio (`{}`) faz a emissão falhar.
- Envie `simplified: true` para utilizar o fluxo simplificado de emissão.
- `monthly_interest_rate` e `disbursement_bank_accounts` são obrigatórios: sem a taxa o cálculo pré-fixado não é possível, e sem a conta não há desembolso.
- `financial.first_due_date` define a data de vencimento da primeira parcela; junto com `disbursement_date`, determina a agenda de pagamento.
- `postal_code` deve ter **8 dígitos, sem traço**.
- `company_representatives[].address` é **obrigatório**.
- `interest_grace_period` e `principal_grace_period` são **obrigatórios** neste modo (use `0` quando não houver carência).
:::

O exemplo completo abaixo inclui também os campos cadastrais adicionais da empresa (`company_type`, `cnae_code`, `foundation_date`, `trading_name`) e dos representantes.

Request Body

**Valor líquido**

```json
{
    "borrower": {
        "name": "RAZAO SOCIAL EMPRESA",
        "email": "emailempresa@email.com",
        "phone": {
            "number": "991112222",
            "area_code": "11",
            "country_code": "055"
        },
        "is_pep": false,
        "address": {
            "city": "São Paulo",
            "state": "SP",
            "number": "215",
            "street": "Rua Gilberto Sabino",
            "complement": "3 andar",
            "postal_code": "05425020",
            "neighborhood": "Pinheiros"
        },
        "cnae_code": "6822-6/00",
        "role_type": "issuer",
        "person_type": "legal",
        "company_type": "ltda",
        "trading_name": "NOME FANTASIA DA EMPRESA",
        "foundation_date": "2019-07-05",
        "attached_documents_list": [],
        "company_document_number": "80282008000127",
        "company_statute": "aa28e598-55e2-40f1-8884-671772c541a1",
        "company_representatives": [
            {
                "name": "NOME DO REPRESENTANTE",
                "email": "nomedorepresentante@email.com",
                "phone": {
                    "number": "990121234",
                    "area_code": "11",
                    "country_code": "055"
                },
                "is_pep": false,
                "final_beneficiary": true,
                "address": {
                    "city": "São Paulo",
                    "state": "SP",
                    "number": "215",
                    "street": "Rua Gilberto Sabino",
                    "complement": "3 andar",
                    "postal_code": "05425020",
                    "neighborhood": "Pinheiros"
                },
                "role_type": "company_representative",
                "birth_date": "1993-09-10",
                "profession": "DIRETOR",
                "mother_name": "NOME DA MAE DO REPRESENTANTE",
                "nationality": "BRASILEIRO",
                "person_type": "natural",
                "marital_status": "single",
                "attached_documents_list": [],
                "individual_document_number": "31057466093",
                "document_identification_number": "20202020200"
            }
        ]
    },
    "financial": {
        "interest_type": "pre_price_days",
        "disbursement_date": "2026-04-07",
        "first_due_date": "2026-05-07",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "disbursed_amount": 10000,
        "monthly_interest_rate": 0.03,
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "number_of_installments": 2,
        "principal_grace_period": 0
    },
    "additional_data": {
        "contract": {
            "contract_number": "DWF1761222116",
            "signatures": [
                {
                    "signer": {
                        "name": "NOME DO REPRESENTANTE",
                        "email": "nomedorepresentante@email.com",
                        "phone": {
                            "number": "990121234",
                            "area_code": "11",
                            "country_code": "055"
                        },
                        "document_number": "31057466093"
                    },
                    "signature": {
                        "timestamp": "28-01-2026 06:36:35",
                        "ip_address": "192.168.1.1",
                        "signature_file": {
                            "file_url": "https://qitech.com.br/signature.pdf",
                            "file_type": "pdf"
                        }
                    }
                }
            ]
        }
    },
    "requester_identifier_key": "d1905ef5-19df-4183-bf0e-802b8229933c",
    "purchaser_document_number": "32402502000135",
    "disbursement_bank_accounts": [
        {
            "document_number": "31233261000185",
            "name": "Fornecedor",
            "pix_key": "2f205c99-3161-4120-badd-854039d12de6",
            "pix_transfer_type": "key"
        }
    ],
    "simplified": true
}
```

#### Detalhes do Request Body

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| **borrower*** | object | Objeto do tomador pessoa jurídica — a empresa devedora da operação de crédito | **[Objeto Borrower](#objeto-borrower)** |
| **financial*** | object | Contém todos os detalhes financeiros e parâmetros de cálculo da operação | **[Objeto Financial](#objeto-financial)** |
| **additional_data*** ⚠ | object | Dados adicionais do contrato. Deve conter `contract.signatures` (opt-in) para a emissão ser concluída — enviar vazio (`{}`) faz a emissão falhar | **[Objeto Additional Data](#objeto-additional-data)** |
| **disbursement_bank_accounts** ⚠ | array | Dados de desembolso via PIX. Não exigido pelo schema, mas **operacionalmente obrigatório** (sem ele não há desembolso) | **[Objeto Disbursement Bank Account](#objeto-disbursement-bank-account)** |
| **simplified** | boolean | Utiliza o fluxo simplificado de emissão. Envie `true` | - |
| **purchaser_document_number** | string | CNPJ do cessionário — o comprador da operação de crédito (FIDC) | 14 |
| **requester_identifier_key** | string | Chave identificadora única do solicitante | UUID |

:::note Legenda
**\*** campo obrigatório no schema · **⚠** exigido na prática para concluir a emissão · sem marcação: opcional.
:::

#### Objeto Borrower

O `borrower` representa a pessoa jurídica tomadora. Por isso o campo `person_type` deve conter **sempre** o valor `legal`.

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| name* | string | Razão social da empresa | 100 |
| trading_name* | string | Nome fantasia da empresa | 100 |
| email | string | E-mail institucional da empresa | 254 |
| phone* | object | Telefone da empresa | **[Objeto Phone](#objeto-phone)** |
| is_pep | boolean | Indicador de Pessoa Politicamente Exposta | - |
| address* | object | Endereço da empresa | **[Objeto Address](#objeto-address)** |
| role_type | string | Papel do tomador na operação — default: `issuer` | - |
| person_type* | string | Classificação da pessoa — deve ser sempre `legal` | 5 |
| company_type* | enum | Tipo da empresa | **[Enumerador Company Type](#enumerador-company-type)** |
| company_document_number* | string | CNPJ da empresa — somente números | 14 |
| cnae_code* | string | Classificação Nacional de Atividades Econômicas | - |
| foundation_date* | date | Data de abertura da empresa (Formato: "YYYY-MM-DD") | 10 |
| company_statute* | string | `document_key` do PDF do contrato social/estatuto da empresa (enviado previamente) | UUID |
| directors_election_minute | string | `document_key` do PDF da ata de eleição (recomendado para `company_type` igual a `sa`; não é forçado pelo schema) | UUID |
| attached_documents_list | array | Lista de documentos anexados da empresa | - |
| company_representatives* | array | Lista de representantes legais da empresa | **[Objeto Company Representatives](#objeto-company-representatives)** |

#### Objeto Company Representatives

Lista dos representantes legais da empresa. O representante que assina o contrato deve também constar no array `signatures` em [Objeto Contract](#objeto-contract).

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| person_type* | string | Identificador do tipo de pessoa — deve ser `natural` | 7 |
| name* | string | Nome completo do representante | 100 |
| birth_date* | date | Data de nascimento (Formato: "YYYY-MM-DD") | 10 |
| is_pep* | boolean | Declaração se o representante é PEP | - |
| individual_document_number* | string | CPF do representante — somente números | 11 |
| phone* | object | Telefone do representante | **[Objeto Phone](#objeto-phone)** |
| address* | object | Endereço do representante | **[Objeto Address](#objeto-address)** |
| mother_name | string | Nome da mãe do representante | 100 |
| profession | string | Profissão do representante | 64 |
| nationality | string | Nacionalidade do representante | 50 |
| marital_status | string | Estado civil do representante | - |
| property_system | string | Regime de bens (recomendado para `marital_status` igual a `married`; não é forçado pelo schema) | **[Enumerador Property System](#enumerador-property-system)** |
| wedding_certificate | string | `document_key` do PDF da certidão de casamento (`null` se solteiro) | UUID |
| spouse | object | Dados do cônjuge (`null` se solteiro; não é forçado pelo schema) | **[Objeto Spouse](#objeto-spouse)** |
| final_beneficiary | boolean | Declaração se o representante é beneficiário final da empresa | - |
| document_identification | string | `document_key` do PDF do documento de identificação com foto (RG ou CNH) | UUID |
| document_identification_back | string | `document_key` do PDF do verso do documento de identificação | UUID |
| document_identification_type | string | Tipo do documento de identificação enviado | - |
| document_identification_number | string | Número do documento de identificação enviado | 16 |
| email | string | E-mail do representante | 254 |
| role_type | string | Papel na operação — default: `company_representative` | - |
| proof_of_residence | string | `document_key` do PDF do comprovante de endereço (enviado previamente) | UUID |

#### Objeto Spouse

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| person_type* | string | Identificador do tipo de pessoa — deve ser `natural` | 7 |
| name* | string | Nome completo do cônjuge | 100 |
| mother_name* | string | Nome da mãe do cônjuge | 100 |
| birth_date* | date | Data de nascimento (Formato: "YYYY-MM-DD") | 10 |
| profession* | string | Profissão do cônjuge | 64 |
| is_pep* | boolean | Declaração se o cônjuge é PEP | - |
| individual_document_number* | string | CPF do cônjuge — somente números | 11 |
| document_identification_number* | string | Número do documento de identificação do cônjuge | 16 |
| email* | string | E-mail do cônjuge | 254 |
| phone* | object | Telefone do cônjuge | **[Objeto Phone](#objeto-phone)** |
| address | object | Endereço do cônjuge | **[Objeto Address](#objeto-address)** |

#### Objeto Address

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| city* | string | Nome da cidade | 100 |
| state* | string | Sigla do estado (duas letras maiúsculas) | 2 |
| number* | string | Número do logradouro | 10 |
| street* | string | Nome do logradouro | 100 |
| complement | string | Complemento do endereço (texto livre) | 100 |
| postal_code* | string | CEP — somente números | 8 |
| neighborhood* | string | Nome do bairro | 100 |

#### Objeto Phone

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| number* | string | Número do telefone | 10 |
| area_code* | string | Código de área (DDD) | 2 |
| country_code* | string | Código internacional (ex: "055") | 3 |

#### Objeto Financial

Nesta modalidade, o valor da operação é definido pelo **valor líquido** a ser desembolsado (`disbursed_amount`), em conjunto com a taxa de juros (`monthly_interest_rate`) e o número de parcelas (`number_of_installments`). A partir desses dados, o sistema calcula o valor de cada parcela.

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| interest_type* | string | Método de amortização | **[Enumerador Interest Type](#enumerador-interest-type)** |
| fine_configuration* | object | Configuração de multa e mora | **[Objeto Fine Configuration](#objeto-fine-configuration)** |
| disbursed_amount* | float | Valor líquido a ser desembolsado | 15,2 |
| credit_operation_type* | string | Tipo da operação de crédito | **[Enumerador Credit Operation Type](#enumerador-credit-operation-type)** |
| number_of_installments* | integer | Número de parcelas | 3 |
| interest_grace_period* | integer | Período de carência de juros (em meses) — use `0` quando não houver | 3 |
| principal_grace_period* | integer | Período de carência do principal (em meses) — use `0` quando não houver | 3 |
| monthly_interest_rate ⚠ | float | Taxa de juros mensal (em decimal). Não exigida pelo schema, mas **necessária** para o cálculo pré-fixado (`interest_type` `pre_*`) | 10,6 |
| disbursement_date | string | Data de desembolso (YYYY-MM-DD). Se omitida, assume a data de emissão | 10 |
| first_due_date | string | Data de vencimento da primeira parcela (YYYY-MM-DD) | 10 |

#### Objeto Fine Configuration

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| monthly_rate* | float | Taxa de mora mensal (alternativamente, informe `daily_rate` ou `annual_rate`) | 10,6 |
| interest_base* | string | Base de cálculo da mora | **[Enumerador Interest Base](#enumerador-interest-base)** |
| contract_fine_rate* | float | Taxa de multa contratual | 10,6 |

#### Objeto Disbursement Bank Account

O desembolso desta operação é realizado via **chave PIX**. Informe os dados do recebedor do desembolso no array `disbursement_bank_accounts`.

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| pix_key* | string | Chave PIX para a qual o desembolso será realizado | - |
| pix_transfer_type* | string | Tipo de transferência PIX — utilizar `key` para transferência via chave | - |
| document_number | string | CPF/CNPJ do titular da chave PIX. Obrigatório apenas quando há **mais de uma conta** de desembolso | 14 |
| name | string | Nome do titular da chave PIX. Obrigatório apenas quando há **mais de uma conta** de desembolso | 50 |
| percentage_receivable | float | Percentual do desembolso para esta conta. Obrigatório com **múltiplas contas** (a soma deve ser 100) | 3 |

#### Objeto Additional Data

A chave `additional_data` é obrigatória e deve conter o bloco `contract` com a evidência de assinatura (opt-in) em `signatures`. Enviar `additional_data` vazio (`{}`) faz a emissão **falhar**.

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| contract* | object | Dados do contrato | **[Objeto Contract](#objeto-contract)** |

#### Objeto Contract

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| contract_number* | string | Número identificador único do contrato | 20 |
| signatures* | array | Lista de objetos de evidência de assinatura digital (Opt-in) dos representantes legais | **[Objeto Signature](#objeto-signature)** |

#### Objeto Signature

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| signer* | object | Dados de identificação do assinante (representante legal) | **[Objeto Signer](#objeto-signer)** |
| signature* | object | Dados de evidência da assinatura digital | **[Objeto Signature Details](#objeto-signature-details)** |

#### Objeto Signer

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| name* | string | Nome completo do assinante | 255 |
| document_number* | string | CPF do assinante | 11 |
| email | string | E-mail do assinante | 100 |
| phone | object | Telefone do assinante | **[Objeto Phone](#objeto-phone)** |

#### Objeto Signature Details

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| ip_address* | string | Endereço IP utilizado na assinatura | 45 |
| timestamp* | string | Data e hora da assinatura | 24 |
| signature_file* | object | Arquivo da assinatura digital | **[Objeto Signature File](#objeto-signature-file)** |

#### Objeto Signature File

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| file_url* | string | Link direto para o documento do contrato assinado (PDF) | 2048 |
| file_type* | string | Formato do arquivo de assinatura (ex: "pdf") | 4 |

### Response

A resposta à requisição de emissão retornará o plano de pagamento e uma **DEBT-KEY**, que é o identificador da dívida na QI SCD.

STATUS 201

Response Body

```json
{
    "webhook_type": "debt",
    "key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c",
    "status": "issued",
    "event_datetime": "2026-04-07 23:59:28",
    "data": {
        "borrower": {
            "name": "RAZAO SOCIAL EMPRESA",
            "document_number": "80282008000127",
            "related_party_key": "24fac77e-7782-4f72-b31a-daee288e34ed"
        },
        "contract": {
            "document_key": null,
            "number": "DWF1761222116",
            "urls": [],
            "signature_information": [
                {
                    "signer_name": "NOME DO REPRESENTANTE",
                    "signer_document_number": "31057466093",
                    "signer_role": "issuer",
                    "signer_email": null,
                    "signer_external_key": null,
                    "signature_url": null
                }
            ]
        },
        "requester_identifier_key": "d1905ef5-19df-4183-bf0e-802b8229933c",
        "iof_charge_method": "financed",
        "collaterals": [],
        "contract_fees": [
            {
                "fee_type": "spread",
                "fee_amount": 30.2
            }
        ],
        "external_contract_fees": [
            {
                "fee_type": "tac",
                "fee_amount": 0,
                "tax_amount": 0,
                "net_fee_amount": 0
            }
        ],
        "external_contract_fee_amount": 0,
        "net_external_contract_fee_amount": 0,
        "contract_fee_amount": 30.2,
        "issue_amount": 10076.2,
        "assignment_amount": 10106.4,
        "cet": "3,3500%",
        "annual_cet": "48,5100%",
        "number_of_installments": 2,
        "base_iof": 12.49,
        "additional_iof": 38.58,
        "total_iof": 51.07,
        "ipoc_code": "324025020203180282008000127DWF1761222116",
        "prefixed_interest_rate": {
            "annual_rate": 0.42576089,
            "created_at": "2026-04-07T23:59:22",
            "daily_rate": 0.00097227,
            "interest_base": "calendar_days",
            "monthly_rate": 0.03
        },
        "installments": [
            {
                "accrual_reference_date": null,
                "additional_costs": [],
                "advanced_paid_amount": 0,
                "bank_slip_key": null,
                "business_due_date": "2026-05-07",
                "calendar_days": 30,
                "digitable_line": null,
                "due_date": "2026-05-07",
                "due_interest": 0,
                "due_principal": 10076.2,
                "fine_amount": null,
                "has_interest": true,
                "installment_history": [],
                "installment_key": "1dea396f-beb1-4df3-9822-35800b4c095a",
                "installment_number": 1,
                "installment_payment": [],
                "installment_status": "created",
                "installment_type": "principal",
                "paid_amount": 0,
                "paid_at": null,
                "post_fixed_amount": 0,
                "qr_code_key": null,
                "qr_code_url": null,
                "renegotiation_proposal_key": null,
                "total_amount": 5226.97,
                "total_paid_amount": 0,
                "workdays": 20
            },
            {
                "accrual_reference_date": null,
                "additional_costs": [],
                "advanced_paid_amount": 0,
                "bank_slip_key": null,
                "business_due_date": "2026-06-08",
                "calendar_days": 31,
                "digitable_line": null,
                "due_date": "2026-06-07",
                "due_interest": 0,
                "fine_amount": null,
                "has_interest": true,
                "installment_history": [],
                "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999",
                "installment_number": 2,
                "installment_payment": [],
                "installment_status": "created",
                "installment_type": "principal",
                "paid_amount": 0,
                "paid_at": null,
                "post_fixed_amount": 0,
                "qr_code_key": null,
                "qr_code_url": null,
                "renegotiation_proposal_key": null,
                "total_amount": 5226.97,
                "total_paid_amount": 0,
                "workdays": 20
            }
        ],
        "total_pre_fixed_amount": 453.94
    }
}
```

:::caution Atenção
Lembre-se de salvar a **DEBT-KEY** retornada, pois ela será necessária para consultas, renegociações e estornos da operação.
:::

#### Detalhes do Response Body

| Campo | Tipo | Descrição |
|---|---|---|
| **webhook_type** | string | Identificador do tipo de evento |
| **key** | string | DEBT-KEY — identificador único da dívida na QI SCD (UUID) |
| **status** | string | Status atual da dívida — veja os [status de uma dívida](../emissao_de_divida/status_de_uma_divida) |
| **event_datetime** | string | Data e hora do evento |
| **data** | object | **[Objeto Data](#objeto-data)** — Dados da operação |

#### Objeto Data

| Campo | Tipo | Descrição |
|---|---|---|
| **borrower** | object | Dados do tomador (razão social, CNPJ e `related_party_key`) |
| **contract** | object | Dados do contrato, incluindo informações de assinatura |
| **requester_identifier_key** | string | Chave identificadora do solicitante (UUID) |
| **iof_charge_method** | string | Método de cobrança do IOF — sempre "financed" |
| **collaterals** | array | Lista de garantias da operação |
| **contract_fees** | array | Taxas QI Tech cobradas na operação |
| **external_contract_fees** | array | Taxas externas cobradas na operação |
| **contract_fee_amount** | float | Valor total das taxas QI Tech |
| **issue_amount** | float | Valor nominal da operação de crédito |
| **assignment_amount** | float | Valor de cessão da operação de crédito |
| **cet** | string | Custo Efetivo Total mensal |
| **annual_cet** | string | Custo Efetivo Total anual |
| **number_of_installments** | integer | Número de parcelas |
| **base_iof** | float | Valor base do IOF |
| **additional_iof** | float | Valor adicional do IOF |
| **total_iof** | float | Valor total do IOF |
| **ipoc_code** | string | Código de registro de crédito brasileiro gerado pela QI Tech |
| **prefixed_interest_rate** | object | Taxa de juros nominal (anual, diária, mensal e base de cálculo) |
| **installments** | array | Parcelas da operação |
| **total_pre_fixed_amount** | float | Valor total dos juros pré-fixados de todas as parcelas |

## Webhooks

Durante o ciclo de vida da operação, a QI Tech envia webhooks para a URL configurada. Abaixo estão os eventos relevantes para este fluxo.

:::info Informação
O timeout para resposta dos nossos webhooks é de 5 segundos.
:::

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeados de forma restrita. Campos adicionais podem ser incluídos aos payloads retornados.
:::

### Webhook de documento gerado

Enviado quando o contrato da operação é gerado. Traz a `document_key` e as URLs do documento (incluindo a versão assinada).

Response Body

```json
{
    "key": "cc91aac2-8d15-4349-b155-7c23080c61e8",
    "data": {
      "contract": {
        "urls": [
          "https://storage.googleapis.com/live-doc-api/documents/50711223-dfe2-4ed6-9c41-42d68638cfff.pdf"
        ]
      },
      "document_key": "50711223-dfe2-4ed6-9c41-42d68638cfff",
      "signed_contract_url": "https://storage.googleapis.com/live-doc-api/documents/_signed.pdf"
    },
    "status": "generated_document",
    "webhook_type": "debt",
    "event_datetime": "2026-03-24 08:27:11"
}
```

### Webhook de desembolso

Enviado quando o desembolso da operação é realizado (`status: disbursed`). Traz a agenda de parcelas e os comprovantes de transferência (`ted_receipt_list`).

Response Body

```json
{
    "key": "bb81d525s-aa4b-4ddf-81d6-aa4b41fd04nb",
    "data": {
        "installments": [
        {
            "due_date": "2025-11-24",
            "total_amount": 8304.16,
            "installment_key": "7ec2f4d-b21e-4bd5-ahs6-60e998267249",
            "pre_fixed_amount": 2475.77421509,
            "installment_number": 1,
            "principal_amortization_amount": 5828.23857532
        },
        {
            "due_date": "2025-12-22",
            "total_amount": 8304.16,
            "installment_key": "54g37d78-a9a9-bf82-9f8e-fd3ba123797a",
            "pre_fixed_amount": 2001.06342502,
            "installment_number": 2,
            "principal_amortization_amount": 6303.43346322
        }
        ],
        "ted_receipt_list": [
        {
            "fee": 0,
            "url": "https://storage.storage.com/sandbox-doc-api/documents/f9as9329-22bd-4dbg-91a2-f2sdgeth4h04/fheth459-bhrf-4hrt-9hra-fdsfsgehth42.pdf",
            "amount": 123456.0,
            "origin": {
            "name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
            "type": "payment_account",
            "branch": "0001",
            "document": "32402502000777",
            "bank_code": "329",
            "account_key": "5d068423-7774-49e4-b15b-7741238df5a8",
            "branch_digit": null,
            "account_digit": "5",
            "account_branch": "0001",
            "account_number": "00002",
            "financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A."
            },
            "timestamp": "2025-10-26T17:00:51",
            "description": "60701190 8615 22110-2 96969879003 - Fornecedor",
            "destination": {
            "name": "Fornecedor",
            "type": "checking_account",
            "branch": "8612",
            "purpose": "Crédito PIX em Conta",
            "document": "31233261000185",
            "bank_ispb": "60111190",
            "branch_digit": null,
            "account_digit": "2",
            "account_number": "44110",
            "financial_institution_name": "BANCO S.A."
            },
            "end_to_end_id": "E32402402200510221300gNgeefVNtVr",
            "transaction_key": "25044504-1902-412a-a445-23b813bee6c1",
            "origin_transaction_key": "542224ea-b5ea-49ff-b7b7-673b81af387b"
        }
        ],
        "requester_identifier_key": null
    },
    "status": "disbursed",
    "webhook_type": "debt",
    "event_datetime": "2025-10-26 17:00:52"
}
```

### Webhook de cancelamento

Enviado quando a operação é cancelada (`status: canceled`). O campo `cancel_reason_enumerator` indica o motivo.

Response Body

```json
{
    "webhook_type": "debt",
    "key": "27a099df-4688-43cb-87fa-515b1cf343a5",
    "event_datetime": "2022-09-27 07:03:49",
    "data": {
        "cancel_reason": "Operacao cancelada manualmente",
        "cancel_reason_enumerator": "manual"
    },
    "status": "canceled"
}
```

#### Motivos de cancelamento

| cancel_reason_enumerator | Descrição |
|---|---|
| disbursing_error | Operação cancelada por erro no momento do desembolso. |
| waiting_signature | Operação cancelada por falta de assinatura. |
| is_portability | A operação foi cancelada pois é uma portabilidade que não foi concluída. |
| not_collateral_constituted | A operação foi cancelada pois as garantias não foram constituídas. |
| entry_not_paid | A operação foi cancelada pois a entrada não foi paga. |
| not_assigned | Operação cancelada porque o processo de cessão não foi realizado. |
| pix_max_retry | Operação cancelada pois o banco recebedor não conseguiu receber o desembolso. |
| lack_of_resource | Operação cancelada por falta de recurso. |
| manual | Operação cancelada manualmente. |
| kyc_not_accepted | Operação cancelada pois não foi aprovada no compliance. |
| not_collateral_fgts | Operação cancelada por erro com FGTS. |
| agencia_conta_invalida | Agência ou conta destinatária do crédito inválida. |
| invalid_account | Número da conta de destino é inexistente ou inválido. |
| invalid_document_number | CPF/CNPJ da conta de destino está incorreto. |
| unsupported_transaction | A conta de destino não suporta este tipo de transação. |
| bank_slip_payment | Operação cancelada por erro no pagamento do boleto. |
| bank_slip_paid | Operação cancelada pois o boleto já está pago. |
| bank_slip_written_off | Operação cancelada pois o boleto já está baixado. |
| invalid_ispb | Número ISPB é inválido ou inexistente. |
| rejected_payment | Ordem de pagamento foi rejeitada pelo banco recebedor. |
| disbursed_amount_refunded | Operação cancelada devido à devolução do valor de desembolso. |

# Enumeradores

### Enumerador _Company Type_
| Enumerador | Descrição |
|---|---|
| **ltda** | Sociedade Limitada |
| **sa** | Sociedade Anônima |
| **micro_enterprise** | Microempresa |
| **freelancer** | Profissional autônomo |

### Enumerador _Property System_
| Enumerador | Descrição |
|---|---|
| **total_communion_of_goods** | Comunhão total de bens |
| **partial_communion_of_goods** | Comunhão parcial de bens |
| **final_participation_of_acquisitions** | Participação final nos aquestos |
| **compulsory_separation_of_goods** | Separação obrigatória de bens |

### Enumerador _Interest Type_
| Enumerador | Descrição |
|---|---|
| **pre_price_days** | Amortização Price (parcelas iguais) com juros pré-fixado ao dia |
| **pre_price** | Amortização Price (parcelas iguais) com juros pré-fixado em períodos fixos (30 dias) |
| **pre_sac** | Amortização SAC (amortização constante) com juros pré-fixado ao dia |
| **post_sac** | Amortização SAC com juros pré-fixado + indexador pós-fixado (cdi, ipca ou igpm) ao dia |
| **post_price** | Amortização Price com juros pré-fixado + indexador pós-fixado em períodos fixos (30 dias) |
| **post_price_days** | Amortização Price com juros pré-fixado + indexador pós-fixado ao dia |

### Enumerador _Credit Operation Type_
| Enumerador | Descrição |
|---|---|
| **ccb** | Cédula de Crédito Bancário |
| **cce** | Cédula de Crédito à Exportação |
| **cci** | Cédula de Crédito Imobiliário |
| **nce** | Nota de Crédito à Exportação |
| **ncom** | Nota Comercial |

### Enumerador _Interest Base_
| Enumerador | Descrição |
|---|---|
| **workdays** | Cálculo de juros em dias úteis considerando um ano de 252 dias |
| **calendar_days** | Cálculo de juros em dias corridos considerando um ano de 360 dias |
| **calendar_days_365** | Cálculo de juros em dias corridos considerando um ano de 365 dias |

## Decodificação de QR Code

### Request

ENDPOINT pix/decode_qrcode_payload
MÉTODO POST

Testar no Playground

Request Body

```json
{
   "qr_code_type": "dynamic_instant",
   "qr_code_payload": "00020101021226850014br.gov.bcb.pix2563qrcodepix.bb.com.br/pix/v2/d373e385-dfe7-49f6-b9ec-14ba60a9b8285204000053039865802BR5925TESTE62070503***63047B7D",
   "pix_key": "teste.cobrancapix@gmail.com.br",
   "receiver_conciliation_id": "fgnb4NTt7pOUBGfrcporERwVVqr0f8PWRfK",
   "amount": "9367.61",
   "status": "ATIVA"
}

```
### Response Body

| Campo | Tipo | Descrição | Disponível |
|-----------------------------|--------|-------------------------------------------------------------------------|--------------------|
| `qr_code_type` | string | Tipo do QR Code: static, dynamic_instant ou dynamic_term. | Todos |
| `qr_code_payload` | string | Payload EMV original recebido na requisição. | Todos |
| `pix_key` | string | Chave Pix do recebedor extraída do payload do QR Code. | Todos |
| `transfer_amount` | string | Valor da transferência, quando especificado no QR Code. | `static` |
| `additional_data` | string | Dados adicionais contidos no QR Code estático. | `static` |
| `receiver_conciliation_id` | string | Identificador de conciliação do recebedor (txid). | `dynamic_*` |
| `amount` | string | Valor original da cobrança. | `dynamic_*` |
| `status` | string | Status da cobrança dinâmica. | `dynamic_*` |

###  :::info Status
Para QR Codes dinâmicos, o status do QR Code é retornado de acordo com a tabela de enumeração abaixo.

### Erros

Response Body: QR Code estático
QR Code com formato inválido

```json
{
"data": "{\"title\": \"Invalid Qr Code Format\", \"description\": \"The Qr Code format is invalid, please enter a valid Qr Code\", \"translation\": \"O formato do Qr Code é inválido, por favor insira um Qr Code válido\", \"extra_fields\": {}, \"code\": \"PXT000070\"}"
}

```

Tipo de QR Code não identificado no payload

```json
{
 "data": "{\"title\": \"Invalid Qr Code Type\", \"description\": \"The Qr Code payload given did not provide a propper Qr Code type\", \"translation\": \"O payload de QR Code fornecido não contêm um tipo de Qr Code Válido\", \"extra_fields\": {}, \"code\": \"PXT000071\"}"
}
```

Response Body

```json
{
"data": "{\"title\": \"Error in Qr Code Payload Request\", \"description\": \"An error occurred while requesting the qr code payload to the registry institution\", \"translation\": \"Um erro ocorreu durante a requisição do payload do qr code para a instituição de registro\", \"extra_fields\": {}, \"code\": \"PXT000069\"}"
}
```

# Análise de Risco

:::caution Versão preliminar
Esta é a primeira versão da documentação do Análise de Risco e pode sofrer pequenas alterações. Recomendamos acompanhar esta página para futuras atualizações.
:::

O endpoint de **Análise de Risco** permite realizar uma análise de crédito completa para o tomador, combinando onboarding, análise de crédito e consulta de dados do trabalhador do consignado privado em uma única requisição.

A operação é **assíncrona**: ao enviar a requisição, a API retorna uma resposta síncrona com o status `pending_inquiry`. O resultado final da análise é entregue via **webhook** quando o processamento é concluído.

:::info Fluxo
1. O cliente envia um `POST` para `/lending_analysis` com os dados do tomador e as consultas desejadas.
2. A API retorna uma resposta síncrona com a `lending_analysis_key` e status `pending_inquiry`.
3. Ao finalizar o processamento, a API envia um webhook com o resultado completo da análise.
:::

:::info Endpoints disponíveis
Além do `POST /lending_analysis` descrito abaixo, a API expõe duas consultas auxiliares:

- [Consulta de elegibilidade](#consulta-de-elegibilidade) — `GET /lending_analysis` para verificar se o tomador já tem análise ativa antes de criar uma nova.
- [Consulta de status da análise](#consulta-de-status-da-análise) — `GET /lending_analysis/{lending_analysis_key}` para acompanhar o estado da análise via polling, como alternativa ao webhook.
:::

---

## Request

ENDPOINT /lending_analysis
MÉTODO POST

Request Body

```json
{
    "request_identifier_key": "12345678901",
    "document_number": "46276658812",
    "lending_analysis_type": "private_payroll",
    "purchaser_document_number": "12345678000199",
    "private_payroll": {
        "employer_document_number": "12345678000199",
        "registration_number": "12345678901"
    },
    "authorization_term": {
        "legal_representative_document_number": "98765432100",
        "signature": {
            "signer": {
                "document_number": "46276658812",
                "name": "João da Silva",
                "email": "joao.silva@email.com",
                "phone": {
                    "number": "912345678",
                    "area_code": "11",
                    "country_code": "55"
                }
            },
            "authentication_type": "opt_in",
            "authenticity": {
                "timestamp": "2026-03-12T10:00:00Z",
                "ip_address": "192.168.1.100",
                "fingerprint": {},
                "session_id": "3571e292-3a83-4011-904d-20ee963022ef"
            }
        }
    },
    "analysis_data": {
        "name": "João da Silva"
    }
}
```

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `request_identifier_key` | string | Chave idempotente da requisição. Deve ser única por análise. | - |
| `document_number` | string | CPF do tomador (apenas dígitos). | 11 |
| `lending_analysis_type` | string | Tipo da análise de crédito. | **[Enumeradores Análise de Risco Type](#enumeradores-lending-analysis-type)** |
| `purchaser_document_number` | string | CNPJ do comprador/cessionário. (opcional) | 14 |
| `private_payroll` | object | Dados do consignado privado do tomador. | **[Private Payroll Object](#private-payroll-object)** |
| `authorization_term` | object | Termo de autorização do tomador. | **[Authorization Term Object](#authorization-term-object)** |
| `analysis_data` | object | Dados adicionais do tomador para a análise. | **[Analysis Data Object](#analysis-data-object)** |

### Private Payroll Object

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `employer_document_number` | string | CNPJ do empregador. | 14 |
| `registration_number` | string | Número de matrícula do trabalhador. | - |

### Authorization Term Object

:::caution Atenção
Nos casos em que houver representante legal, é necessário preencher o campo `legal_representative_document_number` com o CPF do representante legal, e os dados do objeto `signer` devem ser preenchidos com os dados do representante.
:::

> Para mais informações sobre o objeto `authorization_term`, consulte a documentação oficial:
> [Consultas do Trabalhador - Consulta de Dados do Trabalhador](https://docs.qitech.com.br/documentation/manual_consignado_privado/manual_consultas_trabalhador)

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `legal_representative_document_number` | string | CPF do representante legal (obrigatório apenas quando houver representante legal). | 11 |
| `signature.signer.document_number` | string | CPF do assinante. | 11 |
| `signature.signer.name` | string | Nome do assinante. | - |
| `signature.signer.email` | string | Email do assinante. (opcional) | - |
| `signature.signer.phone.number` | string | Número de telefone do assinante. (opcional) | - |
| `signature.signer.phone.area_code` | string | DDD do assinante. (opcional) | 2 |
| `signature.signer.phone.country_code` | string | Código do país (ex: `"55"`). (opcional) | 3 |
| `signature.authentication_type` | string | Tipo de autenticação. Deve ser `"opt_in"`. | - |
| `signature.authenticity.timestamp` | string | Data e hora do aceite (formato ISO 8601: `2026-03-12T10:00:00Z`). | - |
| `signature.authenticity.ip_address` | string | IP da sessão do usuário (IPv4 ou IPv6). | - |
| `signature.authenticity.fingerprint` | object | Evidências adicionais de rastreabilidade (pode ser objeto vazio `{}`). | - |
| `signature.authenticity.session_id` | string | Identificador da sessão do usuário (min. 10, máx. 50 caracteres). | 50 |

### Analysis Data Object

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `name` | string | Nome do tomador. (opcional) | - |

---

## Response

STATUS 202

Response Body

```json
{
    "analysis_status": "pending_inquiry",
    "lending_analysis_key": "06666318-c9e9-416b-ae2f-460355a3d8e8"
}
```

| Campo | Tipo | Descrição |
|---|---|---|
| `analysis_status` | string | Status atual da análise. Retorna `pending_inquiry` na resposta síncrona. |
| `lending_analysis_key` | string | Chave UUID da análise, utilizada para correlacionar com o webhook. |

---

STATUS 400

Response Body

```json
{
    "title": "Bad Request",
    "description": "Invalid or missing required fields in the request body. Check 'document_number', 'lending_analysis_type', 'private_payroll', and 'authorization_term'.",
    "translation": "Campos obrigatórios ausentes ou inválidos no corpo da requisição. Verifique 'document_number', 'lending_analysis_type', 'private_payroll' e 'authorization_term'.",
    "extra_fields": {},
    "code": "LAS000001"
}
```

---

STATUS 409

Retornado quando o campo `request_identifier_key` já foi utilizado em uma requisição anterior.

Response Body

```json
{
    "title": "Conflict",
    "description": "A lending analysis with the provided 'request_identifier_key' already exists. Each analysis must use a unique identifier.",
    "translation": "Já existe uma análise de crédito com o 'request_identifier_key' informado. Cada análise deve utilizar um identificador único.",
    "extra_fields": {
        "existing_lending_analysis_key": "06666318-c9e9-416b-ae2f-460355a3d8e8"
    },
    "code": "LAS000002"
}
```

---

## Consulta de elegibilidade

Verifica se o tomador possui uma análise ativa (não expirada) para um determinado produto. Se não houver, indica que uma nova análise pode ser criada com `POST /lending_analysis`.

ENDPOINT /lending_analysis
MÉTODO GET

### Query Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `document_number` | string | CPF do tomador (apenas dígitos). | 11 |
| `product_name` | string | Nome do produto. Atualmente o único valor aceito é `private_payroll`. | - |
| `purchaser_document_number` | string | CNPJ do comprador/cessionário. (opcional) | 14 |

### Exemplo de chamada

```
GET /lending_analysis?document_number=46276658812&product_name=private_payroll
```

---

### Response — Tomador com análise ativa

STATUS 200

Response Body

```json
{
    "lending_analysis_key": "06666318-c9e9-416b-ae2f-460355a3d8e8",
    "analysis_status": "approved",
    "expires_at": "2026-03-17T10:00:00Z"
}
```

| Campo | Tipo | Descrição |
|---|---|---|
| `lending_analysis_key` | string | Chave UUID da análise ativa do tomador. |
| `analysis_status` | string | Status atual da análise. Veja **[Status da análise](#status-da-análise)**. |
| `expires_at` | string | Data e hora (ISO 8601) em que a análise expira. Após essa data, o tomador volta a ser elegível para uma nova análise. |

---

### Response — Tomador sem análise ativa

STATUS 404

Retornado quando não existe análise ativa para o tomador na combinação informada. O cliente pode prosseguir com `POST /lending_analysis` para iniciar uma nova análise (desde que exista uma `AnalysisConfiguration` ativa para o mesmo `requester_key`, produto e `purchaser_document_number`).

Response Body

```json
{
    "code": "LAS000009",
    "title": "No active lending analysis found",
    "description": "No active lending analysis found for product_name=<X>, purchaser_document_number=<Y>. The borrower has no active analysis for the given product.",
    "translation": "Nenhuma analise de credito ativa encontrada para product_name=<X>, purchaser_document_number=<Y>. O tomador nao possui analise ativa para o produto informado."
}
```

Disparado quando não existe nenhuma `Analysis` para a tupla (`requester_key`, `product_name`, `document_number`, `purchaser_document_number`) que esteja em status diferente de `failed` e ainda dentro do prazo de validade (`expires_at` no futuro).

---

## Consulta de status da análise

Retorna o estado completo de uma análise específica, incluindo o histórico de transições de status, etapas individuais executadas e dados das consultas realizadas (`inquiries`). Útil quando o cliente prefere fazer polling em vez de aguardar exclusivamente o webhook de conclusão.

ENDPOINT /lending_analysis/{lending_analysis_key}
MÉTODO GET

### Path Params

| Campo | Tipo | Descrição |
|---|---|---|
| `lending_analysis_key` | string | UUID da análise, retornado pelo `POST /lending_analysis` na criação. |

### Exemplo de chamada

```
GET /lending_analysis/06666318-c9e9-416b-ae2f-460355a3d8e8
```

---

### Response

STATUS 200

Response Body

```json
{
    "lending_analysis_key": "06666318-c9e9-416b-ae2f-460355a3d8e8",
    "analysis_status": "approved",
    "expires_at": "2026-03-17T10:00:00Z",
    "request_identifier_key": "12345678901",
    "document_number": "46276658812",
    "additional_data": {
        "private_payroll": {
            "employer_document_number": "12345678000199",
            "registration_number": "12345678901"
        },
        "analysis_data": {
            "name": "João da Silva"
        }
    },
    "status_events": [
        {
            "status": "pending_inquiry",
            "created_at": "2026-03-12T10:00:00Z"
        },
        {
            "status": "approved",
            "created_at": "2026-03-12T10:05:00Z"
        }
    ],
    "inquiries": [
        {
            "inquiry_key": "0a1b2c3d-e5f6-7890-abcd-ef1234567890",
            "inquiry_type": "private_payroll",
            "inquiry_status": "success",
            "inquiry_data": {}
        }
    ],
    "steps": [
        {
            "analysis_step_key": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
            "order": 1,
            "step_type": "onboarding_natural_person",
            "step_status": "approved"
        },
        {
            "analysis_step_key": "a9b8c7d6-e5f4-3210-abcd-ef1234567890",
            "order": 2,
            "step_type": "credit_analysis_natural_person",
            "step_status": "approved"
        }
    ]
}
```

#### Campos principais

| Campo | Tipo | Descrição |
|---|---|---|
| `lending_analysis_key` | string | UUID da análise. |
| `analysis_status` | string | Status atual da análise. Veja **[Status da análise](#status-da-análise)**. |
| `expires_at` | string | Data e hora de expiração da análise (ISO 8601). |
| `request_identifier_key` | string | Chave idempotente informada na requisição original. |
| `document_number` | string | CPF do tomador. |
| `additional_data` | object | Dados originais enviados em `POST /lending_analysis` (`private_payroll`, `authorization_term`, `analysis_data`). |
| `status_events` | array | Histórico de transições de status. **[Status Events Object](#status-events-object)** |
| `inquiries` | array | Consultas realizadas durante a análise. **[Inquiries Object (consulta)](#inquiries-object-consulta)** |
| `steps` | array | Etapas individuais executadas. **[Steps Object](#steps-object)** |

#### Status Events Object

Cada item registra uma transição de status com seu carimbo de tempo, em ordem cronológica.

| Campo | Tipo | Descrição |
|---|---|---|
| `status` | string | Status assumido pela análise. Veja **[Status da análise](#status-da-análise)**. |
| `created_at` | string | Data e hora da transição (ISO 8601). |

#### Inquiries Object (consulta)

| Campo | Tipo | Descrição |
|---|---|---|
| `inquiry_key` | string | UUID da consulta. |
| `inquiry_type` | string | Tipo da consulta. Atualmente o único valor é `private_payroll`. |
| `inquiry_status` | string | Status da consulta: `pending`, `success` ou `failed`. |
| `inquiry_data` | object | Dados retornados pela consulta. Para `private_payroll`, segue o mesmo formato exibido no webhook — consulte **[Dados de inquiry (`inquiry_data`)](#dados-de-inquiry-inquiry_data)**. |
| `failure_reason` | string | Motivo da falha quando `inquiry_status` é `failed`. (opcional) |

#### Steps Object

Cada etapa representa uma análise individual executada (onboarding, análise de crédito) durante o processamento.

| Campo | Tipo | Descrição |
|---|---|---|
| `analysis_step_key` | string | UUID da etapa. |
| `order` | integer | Ordem de execução da etapa (1, 2, ...). |
| `step_type` | string | Tipo da etapa: `onboarding_natural_person` ou `credit_analysis_natural_person`. |
| `step_status` | string | Status atual da etapa: `created`, `pending`, `approved`, `reproved` ou `failed`. |

---

STATUS 404

Retornado quando a `lending_analysis_key` informada não corresponde a nenhuma análise existente.

Response Body

```json
{
    "title": "Not Found",
    "description": "Lending analysis with the provided key was not found.",
    "translation": "Não foi encontrada uma análise de crédito com a chave informada.",
    "extra_fields": {},
    "code": "LAS000005"
}
```

---

## Webhooks

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeados de forma estrita.
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

**Webhook type:** `laas.lending_analysis.status_change`

O webhook é enviado para a URL configurada no ambiente do cliente quando a análise é concluída.

## Webhook de análise concluída

Response Body

```json
{
    "key": "06666318-c9e9-416b-ae2f-460355a3d8e8",
    "status": "completed",
    "webhook_type": "laas.lending_analysis.status_change",
    "event_datetime": "2026-03-12T10:05:00Z",
    "data": {
        "request_identifier_key": "12345678901",
        "analysis_status": "reproved",
        "analysis_steps": [
            {
                "analysis_step_type": "onboarding_natural_person",
                "analysis_step_status": "approved",
                "reason": "Passou nas validações",
                "output_data": {}
            },
            {
                "analysis_step_type": "credit_analysis_natural_person",
                "analysis_step_status": "reproved",
                "reason": "Score do Serasa menor que 500",
                "output_data": {
                    "analysis_score": 100,
                    "credit_model_score": 100,
                    "maximum_monthly_interest_rate": 0.00,
                    "minimum_monthly_interest_rate": 0.00,
                    "maximum_installments_number": 10,
                    "minimum_installments_number": 1,
                    "maximum_disbursed_issue_amount": 4500.00,
                    "minimum_disbursed_issue_amount": 0.00
                }
            }
        ],
        "inquiries": [
            {
                "inquiry_type": "private_payroll",
                "inquiry_data": {
                    "document_number": "99999999999",
                    "registration_number": "99999999999-A",
                    "employer_document_number": "99999999999962",
                    "name": "JOÃO SILVA",
                    "gender": "male",
                    "birth_date": "1985-07-20",
                    "worker_category_code": 101,
                    "eligible": true,
                    "available_margin_amount": 5000.00,
                    "base_margin_amount": 4500.00,
                    "total_due_amount": 8207.54,
                    "admission_date": "2020-03-15",
                    "termination_date": null,
                    "termination_reason_code": null,
                    "political_exposition": "not_exposed",
                    "employer_name": "EMPRESA XYZ LTDA",
                    "mother_name": "MARIA DA SILVA",
                    "nationality": {
                        "code": 76,
                        "description": "BRASIL"
                    },
                    "occupation": {
                        "code": 724325,
                        "description": "SOLDADOR ELETRICO"
                    },
                    "economic_activity": {
                        "code": 2833000,
                        "description": "FABRICACAO DE MAQUINAS E EQUIPAMENTOS PARA A AGRICULTURA E PECUARIA"
                    },
                    "ineligibility_reason": "not_informed",
                    "employer_activity_start_date": "2010-05-12",
                    "legacy_loans": [],
                    "alerts": [
                        {
                            "alert_type": "leave",
                            "reference_date": "2025-02-11",
                            "event_id": 123456,
                            "leave_reason_code": 3,
                            "leave_start_date": "2025-02-11",
                            "leave_end_date": "2025-03-11"
                        },
                        {
                            "alert_type": "termination",
                            "reference_date": "2025-02-11",
                            "event_id": 789012,
                            "termination_reason_code": 1,
                            "termination_date": "2025-02-11",
                            "notice_period_start_date": "2025-01-11",
                            "notice_period_end_date": "2025-02-11"
                        }
                    ]
                }
            }
        ]
    }
}
```

### Descrição dos campos do webhook

| Campo | Tipo | Descrição |
|---|---|---|
| `key` | string | `lending_analysis_key` retornada na resposta síncrona. |
| `status` | string | Status do webhook. |
| `webhook_type` | string | Tipo do webhook. |
| `event_datetime` | string | Data e hora do evento (ISO 8601). |
| `data.request_identifier_key` | string | Chave idempotente informada na requisição original. |
| `data.analysis_status` | string | Status final da análise. **[Status da análise](#status-da-análise)** |
| `data.analysis_steps` | array | Lista de etapas da análise realizadas. **[Analysis Steps Object](#analysis-steps-object)** |
| `data.inquiries` | array | Dados retornados das consultas realizadas. Consulte a seção **[Dados de inquiry (inquiry_data)](#dados-de-inquiry-inquiry_data)**. |

### Analysis Steps Object

| Campo | Tipo | Descrição |
|---|---|---|
| `analysis_step_type` | string | Tipo da etapa. **[Tipos de análise individual](#tipos-de-análise-individual)** |
| `analysis_step_status` | string | Status da etapa individual (`approved` ou `reproved`). |
| `reason` | string | Razão da aprovação ou reprovação, definida em regra pelo cliente. |
| `output_data` | object | Dados de saída específicos da etapa. |

### `output_data` para `credit_analysis`

:::info Importante
Todos os campos do `output_data` são configuráveis nas regras de análise. Caso a regra não esteja configurada para retornar um determinado campo, ele será retornado vazio ou não estará presente no payload.
:::

| Campo | Tipo | Descrição |
|---|---|---|
| `analysis_score` | number | Score da análise de crédito. |
| `credit_model_score` | number | Score do modelo de crédito. |
| `maximum_monthly_interest_rate` | number | Taxa de juros mensal máxima. |
| `minimum_monthly_interest_rate` | number | Taxa de juros mensal mínima. |
| `maximum_installments_number` | number | Número máximo de parcelas. |
| `minimum_installments_number` | number | Número mínimo de parcelas. |
| `maximum_disbursed_issue_amount` | number | Valor máximo de desembolso. |
| `minimum_disbursed_issue_amount` | number | Valor mínimo de desembolso. |

### Dados de inquiry (`inquiry_data`)

O array `inquiries` no webhook contém os dados retornados das consultas realizadas durante a análise. Cada item possui os campos `inquiry_type` (tipo da consulta) e `inquiry_data` (dados retornados).

Para o tipo `private_payroll`, o objeto `inquiry_data` segue o mesmo padrão de resposta da **Consulta de dados do trabalhador** do consignado privado, incluindo dados pessoais, margem consignável, histórico do vínculo, empréstimos ativos e alertas.

A documentação completa dos campos, enumeradores e exemplos de resposta do `inquiry_data` está disponível em:

> **[Consultas do Trabalhador — 2. Consulta de dados do trabalhador](/documentation/manual_consignado_privado/manual_consultas_trabalhador#consulta-de-dados)**

---

## Enumeradores

### Enumeradores Lending Analysis Type

| Campo | Descrição |
|---|---|
| `private_payroll` | Análise de crédito consignado privado |

### Status da análise

> `analysis_status` (POST 202, GET de elegibilidade, GET de status e webhook `data.analysis_status`)

| Status | Descrição |
|---|---|
| `pending_inquiry` | A análise foi criada e aguarda a consulta inicial (estado inicial). |
| `pending_analysis` | A consulta inicial foi concluída e as etapas de análise (onboarding, análise de crédito) estão em execução. |
| `approved` | A análise foi aprovada (terminal). |
| `reproved` | A análise foi reprovada (terminal). |
| `failed` | A análise falhou por erro técnico ou indisponibilidade de provedor externo (terminal). |

> O webhook `data.analysis_status` é emitido apenas com valores terminais (`approved`, `reproved`, `failed`).

### Status do webhook

> `status` (campo raiz do webhook)

| Status | Descrição |
|---|---|
| `completed` | O processamento foi concluído |
| `failed` | O processamento falhou |

### Tipos de análise individual

> `analysis_step_type` (dentro do array `analysis_steps`)

| Enumerador | Descrição |
|---|---|
| `onboarding_natural_person` | Análise de onboarding/cadastro do tomador. |
| `credit_analysis_natural_person` | Análise de crédito do tomador. |

### Status da análise individual

> `analysis_step_status` (dentro do array `analysis_steps`)

| Status | Descrição |
|---|---|
| `approved` | Análise individual aprovada. |
| `reproved` | Análise individual reprovada. |
| `failed` | Análise individual falhou por erro técnico ou indisponibilidade de provedor externo. |

---

## Sandbox — Casos de teste

:::danger Aviso Importante!
Não utilize dados pessoais reais (CPF, CNPJ, etc.) em ambientes de sandbox.
:::

No ambiente de sandbox, o resultado da análise é determinado pelo valor do campo `analysis_data.name` no body da requisição. Utilize os nomes abaixo para simular diferentes cenários:

| Nome (`analysis_data.name`) | Resultado do onboarding | Resultado da credit_analysis | Status final (`analysis_status`) |
|---|---|---|---|
| `Ana Santos` | `approved` | `approved` | `approved` |
| `Carlos Oliveira` | `approved` | `reproved` | `reproved` |
| `Mariana Costa` | `reproved` | — | `reproved` |
| `Pedro Almeida` | `approved` | — | `approved` |
| `Fernanda Lima` | `reproved` | — | `reproved` |

:::info Como funciona
- **Onboarding approved + Credit analysis approved** (`Ana Santos`): a análise completa é aprovada. O webhook retorna `analysis_status: "approved"` com ambas as etapas aprovadas.
- **Onboarding approved + Credit analysis reproved** (`Carlos Oliveira`): o onboarding é aprovado mas a análise de crédito reprova. O webhook retorna `analysis_status: "reproved"`.
- **Onboarding reproved** (`Mariana Costa`, `Fernanda Lima`): o onboarding reprova e a análise de crédito não é executada. O webhook retorna `analysis_status: "reproved"` com apenas a etapa de onboarding.
- **Only onboarding approved** (`Pedro Almeida`): apenas o onboarding é executado e aprovado, sem análise de crédito. O webhook retorna `analysis_status: "approved"` com apenas a etapa de onboarding.
:::

Webhook — Sandbox com nome "Ana Santos"

```json
{
    "key": "3571e292-3a83-4011-904d-20ee963022ef",
    "status": "completed",
    "webhook_type": "laas.lending_analysis.status_change",
    "event_datetime": "2026-03-12T10:05:00Z",
    "data": {
        "request_identifier_key": "sandbox-test-001",
        "analysis_status": "approved",
        "analysis_steps": [
            {
                "analysis_step_type": "onboarding_natural_person",
                "analysis_step_status": "approved",
                "reason": "Passou nas validações",
                "output_data": {}
            },
            {
                "analysis_step_type": "credit_analysis_natural_person",
                "analysis_step_status": "approved",
                "reason": "Score acima do mínimo",
                "output_data": {
                    "analysis_score": 750,
                    "credit_model_score": 720,
                    "maximum_monthly_interest_rate": 0.0449,
                    "minimum_monthly_interest_rate": 0.0199,
                    "maximum_installments_number": 24,
                    "minimum_installments_number": 3,
                    "maximum_disbursed_issue_amount": 15000.00,
                    "minimum_disbursed_issue_amount": 500.00
                }
            }
        ],
        "inquiries": [
            {
                "inquiry_type": "private_payroll",
                "inquiry_data": {
                    "document_number": "99999999999",
                    "registration_number": "99999999999-A",
                    "employer_document_number": "99999999999962",
                    "name": "ANA SANTOS",
                    "gender": "female",
                    "birth_date": "1990-05-15",
                    "worker_category_code": 101,
                    "eligible": true,
                    "available_margin_amount": 8000.00,
                    "base_margin_amount": 6500.00,
                    "total_due_amount": 3200.00,
                    "admission_date": "2018-09-01",
                    "termination_date": null,
                    "termination_reason_code": null,
                    "political_exposition": "not_exposed",
                    "employer_name": "EMPRESA XYZ LTDA",
                    "mother_name": "LUCIA SANTOS",
                    "nationality": {
                        "code": 76,
                        "description": "BRASIL"
                    },
                    "occupation": {
                        "code": 411010,
                        "description": "AUXILIAR DE ESCRITORIO"
                    },
                    "economic_activity": {
                        "code": 6499999,
                        "description": "OUTRAS ATIVIDADES DE SERVICOS FINANCEIROS"
                    },
                    "ineligibility_reason": "not_informed",
                    "employer_activity_start_date": "2005-01-10",
                    "legacy_loans": [],
                    "alerts": []
                }
            }
        ]
    }
}
```

Webhook — Sandbox com nome "Carlos Oliveira" (credit_analysis reproved)

```json
{
    "key": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "status": "completed",
    "webhook_type": "laas.lending_analysis.status_change",
    "event_datetime": "2026-03-12T10:05:00Z",
    "data": {
        "request_identifier_key": "sandbox-test-002",
        "analysis_status": "reproved",
        "analysis_steps": [
            {
                "analysis_step_type": "onboarding_natural_person",
                "analysis_step_status": "approved",
                "reason": "Passou nas validações",
                "output_data": {}
            },
            {
                "analysis_step_type": "credit_analysis_natural_person",
                "analysis_step_status": "reproved",
                "reason": "Score do Serasa menor que 500",
                "output_data": {
                    "analysis_score": 100,
                    "credit_model_score": 100,
                    "maximum_monthly_interest_rate": 0.00,
                    "minimum_monthly_interest_rate": 0.00,
                    "maximum_installments_number": 10,
                    "minimum_installments_number": 1,
                    "maximum_disbursed_issue_amount": 4500.00,
                    "minimum_disbursed_issue_amount": 0.00
                }
            }
        ],
        "inquiries": [
            {
                "inquiry_type": "private_payroll",
                "inquiry_data": {
                    "document_number": "99999999999",
                    "registration_number": "99999999999-A",
                    "employer_document_number": "99999999999962",
                    "name": "CARLOS OLIVEIRA",
                    "gender": "male",
                    "birth_date": "1988-11-22",
                    "worker_category_code": 101,
                    "eligible": true,
                    "available_margin_amount": 3500.00,
                    "base_margin_amount": 3000.00,
                    "total_due_amount": 12500.00,
                    "admission_date": "2019-06-10",
                    "termination_date": null,
                    "termination_reason_code": null,
                    "political_exposition": "not_exposed",
                    "employer_name": "EMPRESA XYZ LTDA",
                    "mother_name": "ROSA OLIVEIRA",
                    "nationality": {
                        "code": 76,
                        "description": "BRASIL"
                    },
                    "occupation": {
                        "code": 724325,
                        "description": "SOLDADOR ELETRICO"
                    },
                    "economic_activity": {
                        "code": 2833000,
                        "description": "FABRICACAO DE MAQUINAS E EQUIPAMENTOS PARA A AGRICULTURA E PECUARIA"
                    },
                    "ineligibility_reason": "not_informed",
                    "employer_activity_start_date": "2010-05-12",
                    "legacy_loans": [],
                    "alerts": []
                }
            }
        ]
    }
}
```

Webhook — Sandbox com nome "Mariana Costa" (onboarding reproved)

```json
{
    "key": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "status": "completed",
    "webhook_type": "laas.lending_analysis.status_change",
    "event_datetime": "2026-03-12T10:05:00Z",
    "data": {
        "request_identifier_key": "sandbox-test-003",
        "analysis_status": "reproved",
        "analysis_steps": [
            {
                "analysis_step_type": "onboarding_natural_person",
                "analysis_step_status": "reproved",
                "reason": "Documentação inválida",
                "output_data": {}
            }
        ],
        "inquiries": [
            {
                "inquiry_type": "private_payroll",
                "inquiry_data": {
                    "document_number": "99999999999",
                    "registration_number": "99999999999-A",
                    "employer_document_number": "99999999999962",
                    "name": "MARIANA COSTA",
                    "gender": "female",
                    "birth_date": "1992-03-08",
                    "worker_category_code": 101,
                    "eligible": true,
                    "available_margin_amount": 6000.00,
                    "base_margin_amount": 5000.00,
                    "total_due_amount": 2100.00,
                    "admission_date": "2021-01-15",
                    "termination_date": null,
                    "termination_reason_code": null,
                    "political_exposition": "not_exposed",
                    "employer_name": "EMPRESA XYZ LTDA",
                    "mother_name": "PAULA COSTA",
                    "nationality": {
                        "code": 76,
                        "description": "BRASIL"
                    },
                    "occupation": {
                        "code": 252305,
                        "description": "ANALISTA DE SISTEMAS"
                    },
                    "economic_activity": {
                        "code": 6201500,
                        "description": "DESENVOLVIMENTO DE PROGRAMAS DE COMPUTADOR SOB ENCOMENDA"
                    },
                    "ineligibility_reason": "not_informed",
                    "employer_activity_start_date": "2015-08-20",
                    "legacy_loans": [],
                    "alerts": []
                }
            }
        ]
    }
}
```

---

## Referências

- [Consultas do Trabalhador — Consignado Privado](https://docs.qitech.com.br/documentation/manual_consignado_privado/manual_consultas_trabalhador) — Documentação completa sobre consulta de vínculos e consulta de dados do trabalhador, incluindo detalhamento do `authorization_term`.

---

# Assinatura em Lote

URL: /documentation/manual_exercito/assinatura-em-lote

Agrupa **várias operações do consignado militar** em **um único envelope** de assinatura do QI Sign. Você abre o lote, cria as operações referenciando o `document_batch_key`, confere (opcionalmente limpa) e dispara o envio para assinatura.

Fluxo recomendado para [compra de dívida](./04-portabilidade-refin.md) — onde N duplas `debt_purchase` + `refinancing` + 1 refin/refin consolidador podem ser assinadas num único envelope (militar assina uma vez só).

:::caution Regras do lote
**Mesma titularidade:** todas as operações do lote devem ser do **CPF** (ou do **mesmo representante legal**) do militar. Incluir CPF "A" e CPF "B" no mesmo lote gera **erro síncrono** no `POST /debt`.

**Tipos permitidos:** o lote do Exército aceita apenas `POST /debt` com `collateral_type: military_payroll`.
:::

## 1. Abrir o lote

ENDPOINT /document/document_batch
MÉTODO POST

**Request Body**

```json
{
  "type": "military_payroll_external_batch",
  "certifier_type": "qi_sign",
  "batch_name": "Lote EB compra-divida - 5ed20003-0610-46d2-88cc-a5d0de640696",
  "request_control_key": "5ed20003-0610-46d2-88cc-a5d0de640696"
}
```

### Campos chave

| Campo | Tipo | Descrição |
|---|---|---|
| `type` | string | Fixo: **`military_payroll_external_batch`** |
| `certifier_type` | string | Fixo: **`qi_sign`** |
| `batch_name` | string | Nome identificador do lote (**máximo 100 caracteres**) |
| `request_control_key` | string (UUIDv4) | **Idempotência** — não reutilize entre lotes |

**Response Body**

```json
{
  "document_batch_key": "17f35e19-a039-468f-aaa7-84aa8edec3dc"
}
```

Guarde o `document_batch_key` retornado — ele é referenciado em todas as próximas chamadas.

## 2. Incluir operações no lote

Ao criar cada operação militar, envie **`document_batch_key` na raiz** do payload do `POST /debt` (mesmo nível dos demais campos principais).

ENDPOINT /debt
MÉTODO POST

```json
{
  "document_batch_key": "17f35e19-a039-468f-aaa7-84aa8edec3dc",
  "borrower": { "...": "demais campos do borrower" },
  "financial": { "...": "demais campos financeiros" },
  "operation_type": "refinancing",
  "collaterals": [
    {
      "collateral_type": "military_payroll",
      "collateral_data": {
        "reservation_type": "refinancing",
        "registration_code": "146254221",
        "token": "12345678"
      }
    }
  ],
  "modality": { "code": "0202" },
  "refinanced_credit_operations": [
    { "...": "operation_key + contrato externo (ver Portabilidade + Refin)" }
  ]
}
```

O restante do body segue o contrato do `POST /debt`. Consulte os roteiros da [Margem Livre](./03-margem-livre.md) ou [Portabilidade + Refinanciamento](./04-portabilidade-refin.md) conforme a modalidade.

:::tip Compra de dívida cabe num lote só
Pra [compra de dívida](./04-portabilidade-refin.md) (`debt_purchase` + `refinancing` port-enrustido), todas as duplas Op A + Op B + o refin/refin consolidador podem entrar no mesmo lote.
:::

## 3. Consultar documentos do lote

Recomendado **antes de fechar o lote** para conferir os documentos agrupados.

ENDPOINT /document/document_batch/DOCUMENT_BATCH_KEY
MÉTODO GET

**Response Body**

```json
{
  "document_batch_key": "1eee4ec2-05f5-45ef-aa64-38bb3d9de02f",
  "documents": [
    {
      "document_key": "5cca1dad-28fe-4f19-8bbb-0edd6f042384",
      "document_type": "ccb_pre_price_days"
    },
    {
      "document_key": "c109d589-ae18-4f4f-ad31-2879bf714c71",
      "document_type": "ccb_pre_price_days"
    }
  ]
}
```

## 4. Limpar documentos do lote (opcional)

Remove **todos os documentos** vinculados ao lote — útil pra reagrupar do zero se identificar inconsistência antes do envio.

ENDPOINT /document/document_batch/DOCUMENT_BATCH_KEY/documents
MÉTODO DELETE

Body vazio. Response: HTTP 200.

## 5. Enviar para assinatura

Fecha o lote e dispara os documentos pro QI Sign. **Antes desse PUT, os documentos não vão pro militar.** É o gatilho final.

ENDPOINT /document/document_batch/DOCUMENT_BATCH_KEY/send_to_signature
MÉTODO PUT

Body: `{}`. Response: HTTP 200.

## Erros comuns

| HTTP | Código | Endpoint | Quando ocorre |
|---|---|---|---|
| 404 | `DOC000007` | `GET /document/document_batch/DOCUMENT_BATCH_KEY` | `document_batch_key` inexistente |
| 409 | `DOC000103` | `POST /document/document_batch` | `request_control_key` duplicado (idempotência violada) |

**Exemplo — DOC000103 (idempotência)**

```json
{
  "code": "DOC000103",
  "title": "Bad Request",
  "description": "request_control_key already exists",
  "translation": "Chave de controle da request já existe.",
  "http_status": 409
}
```

:::info Conflito de titularidade
Validação de **mesmo CPF/representante** no lote retorna erro no `POST /debt` (não no endpoint do lote). O corpo de erro segue o catálogo do `/debt`.
:::

---

# Cancelamento, Desaverbação e Reversal

URL: /documentation/manual_exercito/cancelamento

Cancelar uma operação militar tem dois eixos independentes:
1. **Cancelamento da CCB** — estado da operação no LaaS, e eventual estorno do dinheiro desembolsado.
2. **Desaverbação no Zetra** — liberação da margem em folha de pagamento.

Os dois acontecem de forma assíncrona e nem sempre simultâneos. Cancelar a operação NÃO libera a margem instantaneamente; pagar de volta o dinheiro desembolsado também é um passo separado.

## 1. Pré-desembolso — Cancelamento Imediato

Antes do desembolso (operação em `waiting_signature`, `signature_finished` ou `waiting_disbursement`):

```http
PATCH /debt/{DEBT_KEY}/cancel
```

Sem body. Resposta imediata: operação vai pra `canceled`. Não há reversal financeiro (dinheiro nem saiu).

Webhook: `debt` com `status: canceled` + `cancel_reason_enumerator` indicando o motivo (`manual`, `waiting_signature`, `not_collateral_constituted`, etc.).

A QI dispara em seguida a desaverbação no Zetra (ver seção 4).

## 2. Pós-desembolso — Janela de Desistência (7 dias úteis)

**A janela legal de desistência é de 7 dias úteis** após o desembolso. Dentro dela:

```http
PATCH /debt/{DEBT_KEY}/cancel
```

A response **NÃO é instantânea como o pré-desembolso** — retorna um **PIX QR Code** que o borrower deve pagar pra devolver o dinheiro desembolsado. O parceiro repassa o QR pro cliente.

| Campo na response | Significado |
|---|---|
| `cancel_qr_code.qr_code_url` / `digitable_line` | PIX copia-e-cola ou QR pra pagamento |
| `cancel_qr_code.amount` | Valor a devolver (igual ao desembolsado) |
| `cancel_qr_code.expiration` | Prazo pro pagamento (15 dias úteis após desembolso) |

Quando o borrower paga o PIX:
1. QI confirma o pagamento.
2. Dispara o **reversal financeiro automático** — desfaz o desembolso, devolve pro fundo.
3. Webhook `reversal` chega:
   ```json
   {
     "webhook_type": "reversal",
     "credit_operation_key": "<uuid>",
     "contract_number": "<...>",
     "reversal": {
       "status": "pending_fund",
       "amount": 2026.93,
       "amount_to_send": 2026.93,
       "is_total": true,
       "is_operation_canceled": true,
       "reversal_key": "<uuid>",
       "date": "2026-09-06"
     }
   }
   ```
4. QI dispara a desaverbação no Zetra.
5. Operação vai pra `canceled`.

> [!warning] Prazo de pagamento do QR
> O QR tem validade de **15 dias úteis após o desembolso** (não após emissão do QR). Se o borrower não pagar dentro desse prazo, o cancelamento expira e a operação volta a ser ativa — vira inadimplência normal (cobrança de parcelas segue o curso).

Restrições pós-desembolso:
- Operação precisa estar em status `open` (sem parcelas pagas).
- Pagamento parcial de qualquer parcela bloqueia o cancelamento.
- Não há cancelamento parcial — só total.

## 3. Cancelamento Permanente

```http
PATCH /debt/{DEBT_KEY}/cancel/permanent
```

Marca como `canceled_permanently` — não há volta. Útil pra:
- Cliente desistiu e não vai pagar o QR (vira inadimplência → permanent depois)
- Operação que ficou pendente além do prazo (auto-cancel já faz isso em 7 dias, mas pode forçar)

Sem reversal automático — usar apenas se o dinheiro já foi resolvido por fora ou nunca saiu.

## 4. Desaverbação no Zetra

Independente do cancelamento financeiro, a desaverbação é processada pelo Zetra de forma assíncrona:

![Fluxo de cancelamento Exército](/img/diagrams/exercito-cancelamento.svg)

| Status no `credit_operation.collateral` | Significado |
|---|---|
| `waiting_confirmation` | Zetra ainda processando a desaverbação |
| `successfully_deleted` | Margem liberada |
| `communication_error` | Zetra indisponível (cod 241) — QI retenta automaticamente |

> [!warning]
> **Não considere a margem liberada até `successfully_deleted` chegar.** Emitir nova operação no mesmo militar antes da desaverbação confirmada retorna `consignable_margin_exceeded`.

Pra consultar o estado:

```http
GET /debt/{DEBT_KEY}/collateral
```

Retorna `last_response` + `reservation_status` atual.

## 5. Auto-cancelamento (7 dias)

Operações em status `canceled` (não-permanente) por mais de **7 dias** são automaticamente convertidas em `canceled_permanently` pelo sistema. Aplica-se a:
- Operação cuja averbação foi recusada (`consent_refused`)
- Operação cuja averbação expirou (`consent_expired`)
- Operação pendente de assinatura além do prazo
- Operação com cancelamento solicitado mas QR não pago dentro de 15 dias úteis

Não precisa fazer nada — o sistema cancela e desaverba sozinho.

## Resumo dos Endpoints

| Endpoint | Quando usar | Reversal automático? |
|---|---|---|
| `PATCH /debt/{KEY}/cancel` (pré-desembolso) | Antes do desembolso | Não aplica (dinheiro não saiu) |
| `PATCH /debt/{KEY}/cancel` (pós-desembolso) | Dentro de 7 dias úteis após desembolso | Sim — após borrower pagar o PIX QR retornado |
| `PATCH /debt/{KEY}/cancel/permanent` | Cancelamento definitivo (sem volta) | Não — uso administrativo |

## Cancel reasons no webhook `debt` (`status: canceled`)

Os principais `cancel_reason_enumerator` que aparecem:

| Enumerador | Significado |
|---|---|
| `manual` | Cancelado via API ou portal |
| `waiting_signature` | Não assinou no prazo |
| `not_collateral_constituted` | Averbação falhou |
| `is_portability` | Portabilidade falhou |
| `pix_max_retry` | Muitas falhas no desembolso PIX |
| `lack_of_resource` | Sem recurso pra desembolsar |
| `kyc_not_accepted` | KYC reprovado |

→ [Lista completa de enumeradores em Mapa de Status](./08-mapa-de-status.md)

---

# Consulta de Margem Consignável

URL: /documentation/manual_exercito/consulta-margem

Endpoint que consulta a margem disponível do militar no Zetra (eConsig). É o **primeiro passo operacional** depois do upload da autorização — sem o `balance_key` desse passo, não dá pra simular nem emitir.

## Pré-requisitos

1. **Upload do consentimento** feito (`POST /upload` → `document_key`). → [Upload de Documentos](../upload_de_documentos/)
2. **Token Zetra** do militar em mãos (senha do sistema militar).

## Endpoint

```http
POST /military_payroll/balance
```

| Campo | Tipo | Descrição |
|---|---|---|
| `document_number` | string | CPF do militar — 11 dígitos, sem `.` e sem `-`, zero-padded |
| `registration_code` | string | Matrícula do militar |
| `authorization_document_key` | uuid | `document_key` retornado no upload |
| `token` | string | Token de autenticação Zetra (senha) |

Resposta síncrona:

```json
{
  "balance_key": "81da8afb-e1b2-4215-8093-c4b5feab8a9f",
  "status": "pending_search"
}
```

## Webhook de resultado

Tipo: `military_payroll.balance.status_change`

Campos no payload de **sucesso**:
- `balance` — margem disponível (Decimal)
- `allowed_installment_numbers` — array de prazos válidos (ex: `[24, 36, 48]`)
- `military_unit` — unidade do militar
- `military_branch` — força (string longa, dezenas de valores possíveis: `AMAN`, `Sistema de Retribuição do Exterior`, etc.)
- `category` — `ATIVO`, `INATIVO`, `PENSIONISTA`
- `name`, `document_number`, `registration_code`, `birth_date`, `grant_date`

## Enumeradores de falha

| Enumerador | Zetra code | Significado | Ação |
|---|---|---|---|
| `invalid_registration_code` | 210 | Matrícula inválida ou inexistente | Verificar matrícula |
| `military_not_found` | 293 | Militar não encontrado pelo CPF+matrícula | Verificar dados |
| `military_blocked` | 352 | Militar com bloqueio em folha | Não há ação imediata |
| `communication_error` | 241 | Zetra indisponível | QI retenta automaticamente |

## Sandbox

A sandbox militar **conecta na Zetra real de homologação** (`central_homologa.econsig.com.br`) — não há whitelist local de CPFs no `military-payroll-api`. Os dados de teste (CPFs, matrículas, tokens) são fornecidos pela Zetra.

Solicite ao time de Integrações QI Tech a lista de servidores fictícios disponíveis. CPFs fora dessa lista retornam `military_not_found` (Zetra 293) ou `invalid_registration_code` (Zetra 210).

→ [Mocks (Sandbox) — detalhes completos](./09-mocks-sandbox.md)

## Próximo passo

Após o webhook `succeeded` com `balance` retornado, escolha a modalidade:

- [Margem Livre](./03-margem-livre.md) — crédito novo com margem disponível
- [Portabilidade + Refinanciamento](./04-portabilidade-refin.md) — refin de operação QI ou compra de dívida externa

---

# Conta Interna para Desembolso

URL: /documentation/manual_exercito/conta-interna-desembolso

Em **compra de dívida**, **portabilidade** e **refinanciamento** do consignado militar (Exército), o desembolso da operação **não vai direto para a conta externa do tomador**: ele cai numa conta interna **em nome do tomador** (aberta pelo parceiro via `POST /account`). É a partir dessa conta que a QI executa as ações pós-desembolso — **quitação do contrato externo**, **repasse de troco**, **conciliação**.

:::tip Por que conta interna?
Concentrar o desembolso numa conta operacional dá controle do fluxo: a QI consegue orquestrar quitação externa + averbação + repasse de troco sem depender de SLA de banco terceiro no meio do processo.
:::

## Quando usar conta interna vs externa

| Cenário | `disbursement_bank_account` |
|---|---|
| [Margem Livre](./03-margem-livre.md) (crédito novo direto) | Conta **externa** do tomador |
| [Refinanciamento puro](./04-portabilidade-refin.md) (renegocia CO QI ativa) | Conta **interna** em nome do tomador |
| [Portabilidade](./04-portabilidade-refin.md) (com ou sem troco) | Conta **interna** em nome do tomador |
| [Compra de dívida](./04-portabilidade-refin.md) (`debt_purchase` + `refinancing` port-enrustido) | Conta **interna** em nome do tomador **nas duas operações da dupla** |
| Refin/refin consolidador (opcional, fecha várias port/refins) | Conta **interna** em nome do tomador |

## 1. Abrir a conta interna em nome do tomador

ENDPOINT /account
MÉTODO POST

A conta é aberta pelo **parceiro** (autenticado com seus `client_integration_key`), com o `owner_document_number` apontando para o **CPF do militar tomador**. Reutilize a conta existente — uma por tomador (não abrir nova a cada operação).

**Request Body**

```json
{
  "owner_document_number": "<CPF DO MILITAR>",
  "owner_person_key": "<PERSON_KEY DO MILITAR>",
  "requester_key": "<REQUESTER_KEY DO PARCEIRO>",
  "webhook_enabled": true
}
```

:::info Pré-requisito
O militar precisa estar **onboarded** previamente (ter `person_key`) — o parceiro envia esse `person_key` no `owner_person_key`. Caso contrário, o `/account` falha com `ACC000xxx` por validation.
:::

**Response Body**

```json
{
  "account_key": "1167955-...",
  "account_branch": "0001",
  "account_number": "1167955",
  "account_digit": "1",
  "owner_document_number": "<CPF DO MILITAR>",
  "owner_name": "<NOME DO MILITAR>",
  "bank_code": "329",
  "account_status": "active",
  "webhook_enabled": true
}
```

:::tip Idempotência por tomador
Se já existe conta ativa para esse `owner_document_number` no parceiro, evite chamar `POST /account` de novo — consulte `GET /accounts?owner_document_number= ` antes e reaproveite o `account_key` retornado.
:::

## 2. Usar a conta no `/debt`

Use os dados retornados em `disbursement_bank_account` no payload do `POST /debt`. **A mesma conta vai nas DUAS operações da dupla `debt_purchase` + `refinancing`** (e no `refinancing` consolidador, se houver).

```json
{
  "disbursement_bank_account": {
    "name": "<NOME DO MILITAR>",
    "bank_code": "329",
    "account_type": "checking_account",
    "account_branch": "0001",
    "account_number": "1167955",
    "account_digit": "1",
    "document_number": "<CPF DO MILITAR>",
    "transfer_method": "ted"
  }
}
```

| Campo | Valor (conta interna QI Tech) |
|---|---|
| `bank_code` | `"329"` (QI Tech S.A. — SCD) |
| `account_branch` | `"0001"` |
| `account_number` / `account_digit` | retornados no `POST /account` |
| `document_number` | **CPF do militar** (mesmo do `owner_document_number`) |
| `transfer_method` | `"ted"` (recomendado para `payment_type_id: 10`) |

Exemplo completo: ver [Portabilidade + Refinanciamento — Compra de dívida](./04-portabilidade-refin.md).

## 3. Ações pós-desembolso

A QI dispara as ações abaixo automaticamente conforme os webhooks confirmam cada etapa.

### 3.1 Conferir saldo

ENDPOINT /account/ACCOUNT_KEY/balance
MÉTODO GET

### 3.2 Quitação do contrato externo (port)

Disparada pela QI ao receber `credit_operation.collateral` (`reservation_status: deleted`) na operação antiga: saldo da conta interna é enviado ao banco origem via **PIX** ou **TED** para liquidar o contrato externo.

### 3.3 Repasse de troco pro tomador (se houver)

Se `final_disbursement_amount > 0` na simulação, o saldo residual é transferido da conta interna para a **conta externa do militar** (informada no onboarding ou no payload da operação).

### 3.4 Conciliação

ENDPOINT /account/ACCOUNT_KEY/statement
MÉTODO GET

Query params `from_date` e `to_date` no formato `YYYY-MM-DD`.

### 3.5 Webhooks relevantes

| Webhook | Quando dispara |
|---|---|
| `account.balance_change` | Crédito recebido na conta interna (desembolso da CO) |
| `pix_transfer.status_change` | Quitação externa OU repasse de troco confirmados |
| `ted.status_change` | Quitação externa OU repasse via TED confirmados |

## Referências

- [Conta de pagamento — fluxo completo](/documentation/contas/abertura_de_conta/fluxo_de_abertura_de_conta) — referência do `POST /account` em detalhes
- [Portabilidade + Refinanciamento](./04-portabilidade-refin.md) — usa essa conta em compra de dívida (`debt_purchase` + `refinancing`)
- [Webhooks](./07-webhooks.md) — eventos assíncronos da operação

---

# Modelos de Formalização

URL: /documentation/manual_exercito/formalizacao

A QI Tech suporta **5 modelos** de formalização da operação militar — escolha conforme a infraestrutura do parceiro (se já tem signature provider, se quer usar QI Sign, se vai usar biometria). Adicionalmente, pra agrupar várias operações num único envelope (recomendado em [compra de dívida](./04-portabilidade-refin.md)), use [Assinatura em Lote](./11-assinatura-em-lote.md).

:::tip Várias operações no mesmo envelope
Em compra de dívida com N duplas `debt_purchase` + `refinancing` (+ refin/refin consolidador), use [Assinatura em Lote](./11-assinatura-em-lote.md) (`POST /document/document_batch` com `type: military_payroll_external_batch`) — o militar assina tudo de uma vez só.
:::

## Modelos disponíveis

| Modelo | Quando usar |
|---|---|
| **QI Sign automático** (default) | Não precisa configurar nada — QI envia link de assinatura por email/SMS pro borrower |
| **QI Sign em lote** | Várias operações num único envelope; ver [Assinatura em Lote](./11-assinatura-em-lote.md) |
| **PDF assinado externamente** | Parceiro tem signature provider próprio; faz upload do PDF assinado |
| **Data-signature: opt-in** | Borrower clica "concordo" em um portal do parceiro; parceiro envia evidência |
| **Data-signature: zip** | Parceiro envia zip com evidências (logs, IPs, timestamps) |
| **Data-signature: selfie** | Biometria via CaaS (face match + liveness) |

## QI Sign Automático

Não requer chamada adicional após `/debt`. QI envia URL de assinatura pro borrower (email/SMS). Quando o borrower assina, webhook `debt` fires com `status: signature_finished` e a esteira segue.

Pré-requisito: o RequesterConfiguration tem `default_signature_method` apontando pra QI Sign.

## PDF assinado externamente

```http
POST /debt/{DEBT_KEY}/signed
```

```json
{
  "signed_document_key": "<uuid retornado pelo upload do PDF assinado>"
}
```

Pré-requisito: fazer upload do PDF assinado via `POST /upload` antes de chamar `/signed`.

## Data-signature: opt-in

```json
{
  "data_signature": {
    "type": "opt_in",
    "evidence": {
      "ip_address": "200.123.45.67",
      "user_agent": "Mozilla/5.0 ...",
      "timestamp": "2026-05-17T14:30:00Z"
    }
  }
}
```

## Data-signature: zip

Parceiro empacota evidências em `.zip` e envia via upload. O `signed_document_key` aponta pro zip.

## Data-signature: selfie

Requer integração com CaaS (face recognition + liveness). O `signed_document_key` aponta pra um `image_key` retornado pelo CaaS.

## Webhook após formalização

`debt` com `status: signature_finished` → indica que QI aceitou a formalização. Em seguida, a averbação é confirmada (se `reservation_method: issuing`) e o desembolso entra na fila.

## Próximo passo

Após o `signature_finished`, a operação segue automaticamente: averbação confirmada (se `issuing`) → desembolso PIX/TED → webhook `debt` (`disbursed`).

Para acompanhar via webhooks: [Webhooks](./07-webhooks.md). Para cancelar a qualquer momento: [Cancelamento](./06-cancelamento.md).

---

# Consignado do Exército — Introdução

URL: /documentation/manual_exercito/introducao

API para originação de **CCB consignado** para militares do Exército Brasileiro (ativos, inativos e pensionistas). A reserva de margem é feita via **Zetra (eConsig)** e o ciclo todo — consulta de margem, emissão, averbação, desembolso e cancelamento — passa por essa plataforma.

| Item | Valor |
|---|---|
| Autoridade pagadora | Exército Brasileiro / **Zetra (eConsig)** |
| Tipo de garantia (`collateral_type`) | `military_payroll` |
| Modelo de reserva | Averbação (assíncrona, consentida via documento de autorização) |
| Funcionamento | **24h por dia, todos os dias, inclusive feriados** |
| Modalidades suportadas | [Margem Livre (Crédito Novo)](./03-margem-livre.md) e [Portabilidade + Refinanciamento](./04-portabilidade-refin.md) |
| Token | **Obrigatório** na consulta de margem (senha do sistema militar) |
| Instrumento | CCB (via `POST /debt`) |

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeados de forma restrita.
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

## Fluxo End-to-End

Em **margem livre** o desembolso vai direto pra conta externa do militar. Em **refinanciamento, portabilidade e compra de dívida** o desembolso vai pra uma **conta interna em nome do militar** (aberta pelo parceiro via `POST /account`) — daí a QI quita o contrato externo, repassa o troco e faz a conciliação. Ver [Conta Interna para Desembolso](./10-conta-interna-desembolso.md).

![Fluxo end-to-end Exército](/img/diagrams/exercito-introducao.svg)

## Modalidades

A operação se divide em quatro modalidades, escolhidas no `operation_type` e `collateral_data`:

| Modalidade | `operation_type` / `reservation_type` | Quando usar | Doc |
|---|---|---|---|
| **Margem Livre** (Crédito Novo) | `operation_type: structured_operation` / `reservation_type: new_credit` | Militar com margem disponível; sem dívida externa nem refin de operação ativa | [→ Margem Livre](./03-margem-livre.md) |
| **Refinanciamento** | `operation_type: refinancing` / `reservation_type: refinancing` + `operation_key` | Renegociar operação QI ativa (prazo/taxa), eventualmente liberando troco | [→ Port + Refin](./04-portabilidade-refin.md) |
| **Portabilidade** (com ou sem troco) | `operation_type: refinancing` / `reservation_type: refinancing` + `original_contract_number` | Trazer dívida de outro banco; pode incluir troco | [→ Port + Refin](./04-portabilidade-refin.md) |
| **Compra de dívida** (port enrustida) | `operation_type: debt_purchase` + `operation_type: refinancing` (dupla) | Trazer N dívidas externas; QI emite uma dupla `debt_purchase` + `refinancing` por contrato externo, com desembolso em [conta interna em nome do militar](./10-conta-interna-desembolso.md) | [→ Port + Refin](./04-portabilidade-refin.md) |

## Pré-requisitos

Antes de qualquer requisição (Consulta, Emissão, etc):
1. Upload do consentimento do militar via `POST /upload` → retorna `document_key`. Ver [Upload de Documentos](../upload_de_documentos/).
2. Conhecer o **token** (senha do sistema militar Zetra) do borrower — é obrigatório no payload de `POST /military_payroll/balance`.

## Referência por área

- [Consulta de Margem](./02-consulta-margem.md) — endpoint `/military_payroll/balance` + token Zetra
- [Margem Livre](./03-margem-livre.md) — Simulação + Emissão para `new_credit`
- [Portabilidade + Refinanciamento](./04-portabilidade-refin.md) — Simulação + Emissão para `refinancing` + payloads de compra de dívida (`debt_purchase` + `refinancing` port-enrustido)
- [Formalização](./05-formalizacao.md) — 5 modelos: QI Sign, PDF, opt-in, zip, selfie
- [Conta Interna para Desembolso](./10-conta-interna-desembolso.md) — POST `/account` em nome do militar + uso em compra de dívida + ações pós-desembolso
- [Assinatura em Lote](./11-assinatura-em-lote.md) — agrupar várias operações num único envelope QI Sign (`POST /document/document_batch`)
- [Cancelamento, Desaverbação e Reversal](./06-cancelamento.md) — pré + pós-desembolso + reversal automático
- [Webhooks](./07-webhooks.md) — todos os eventos assíncronos + payloads
- [Mapa de Status](./08-mapa-de-status.md) — enumeradores consolidados
- [Mocks (Sandbox)](./09-mocks-sandbox.md) — dados de teste e cenários end-to-end

---

# Mapa de Status

URL: /documentation/manual_exercito/mapa-de-status

Referência consolidada de todos os enumeradores que podem aparecer nas respostas síncronas e webhooks do produto consignado militar.

## Consulta de Margem (`military_payroll.balance.status_change`)

| Status | Significado |
|---|---|
| `pending_search` | Resposta síncrona — consulta enfileirada no Zetra |
| `succeeded` | Webhook — margem retornada com sucesso |
| `failed` | Webhook — falha (ver `failure_reason`) |

### Failure reasons

| Enumerador | Zetra code | Significado |
|---|---|---|
| `invalid_registration_code` | 210 | Matrícula inválida |
| `military_not_found` | 293 | CPF/matrícula sem registro |
| `military_blocked` | 352 | Militar com bloqueio em folha |
| `communication_error` | 241 | Zetra indisponível |
| `invalid_document_number` | — | CPF malformado |

## Averbação / Desaverbação (`credit_operation.collateral`)

| Enumerador | `reservation_status` | Significado |
|---|---|---|
| `successfully_accepted` | `pending_confirmation` | Zetra aceitou a requisição, aguardando confirmação |
| `successfully_reserved` | `reserved` | Margem reservada com sucesso |
| `successfully_deleted` | `deleted` | Margem desaverbada com sucesso |
| `waiting_confirmation` | — | Aguardando Zetra |
| `communication_error` | — | Erro de comunicação (cod 241) |
| `consignable_margin_exceeded` | — | Margem insuficiente (cod 359) |
| `consent_refused` | — | Militar recusou o consentimento |
| `consent_expired` | — | Janela de consentimento expirou |
| `expired_portability` | — | Janela de port expirou |
| `origin_contract_not_found` | — | Contrato origem (port/refin) não existe |
| `waiting_for_origin_contract_closure` | — | Aguardando quitação externa |

## Operação (`debt`)

| Status | Significado |
|---|---|
| `waiting_signature` | Aguardando assinatura |
| `signature_finished` | Assinatura concluída |
| `waiting_disbursement` | Aguardando desembolso |
| `disbursed` | Desembolsado |
| `canceled` | Cancelada (não-permanente, ainda recuperável) |
| `canceled_permanently` | Cancelada definitivamente |
| `settled` | Liquidada (todas as parcelas pagas) |

### Cancel reasons (`cancel_reason_enumerator`)

| Enumerador | Significado |
|---|---|
| `manual` | Cancelado via API ou portal |
| `waiting_signature` | Não assinou no prazo |
| `not_collateral_constituted` | Averbação falhou |
| `is_portability` | Portabilidade falhou |
| `pix_max_retry` | Muitas falhas no desembolso PIX |
| `lack_of_resource` | Sem recurso pra desembolsar |
| `kyc_not_accepted` | KYC reprovado |
| `agencia_conta_invalida` | Erro em dados bancários |
| `invalid_account` | Conta inválida |
| `rejected_payment` | Pagamento recusado pelo banco destino |
| `disbursing_error` | Erro genérico no desembolso |
| `entry_not_paid` | Entrada não paga (refin com troco negativo) |
| `bank_slip_paid` | Boleto já foi pago |
| `unsupported_transaction` | Tipo de conta não suporta a transação |

## Reversal (cancelamento pós-desembolso)

| Status | Significado |
|---|---|
| `pending_fund` | Reversal iniciado, aguardando devolução pro fundo |
| `completed` | Reversal completo |
| `failed` | Reversal falhou (raro — investigação manual) |

## Parcelas (`installment.status_change`)

| Status | Significado |
|---|---|
| `opened` | Aberta, ainda não venceu |
| `waiting_payment` | Aberta, na data de vencimento |
| `paid` | Paga em dia |
| `paid_early` | Paga antes do vencimento |
| `paid_partial` | Paga parcialmente |
| `paid_overdue` | Paga após o vencimento |
| `paid_partial_overdue` | Paga parcialmente após o vencimento |
| `overdue` | Em atraso |
| `canceled` | Cancelada |

## Recuperar último estado

Pra consultar o estado atual de uma operação a qualquer momento:

```http
GET /debt/{DEBT_KEY}/collateral
```

Retorna `last_response` (último enumerador) + `reservation_status` + timestamp da última atualização.

---

# Margem Livre (Crédito Novo)

URL: /documentation/manual_exercito/margem-livre

Esteira de **originação direta** quando o militar tem margem consignável disponível e não está trazendo dívida externa nem refinanciando operação ativa. Cobre simulação e emissão para `reservation_type: new_credit`.

Para refinanciar uma operação QI ativa ou trazer dívida de outro banco, ver [Portabilidade + Refinanciamento](./04-portabilidade-refin.md).

## Pré-requisitos

- `balance_key` recebido na [Consulta de Margem](./02-consulta-margem.md), com webhook `military_payroll.balance.status_change` em `status: succeeded`.
- `balance` retornado > parcela desejada × prazo.
- `token` Zetra do militar disponível.

## 1. Simulação

Antes de emitir, simule as condições para validar margem, prazo e cronograma.

### Request

ENDPOINT /debt_simulation
MÉTODO POST

**Request Body**

```json
{
  "borrower": {
    "person_type": "natural",
    "individual_document_number": "45507529710"
  },
  "financial": {
    "first_due_date": "2026-07-01",
    "installment_face_value": 500.00,
    "disbursement_date": "2026-06-01",
    "number_of_installments": 24,
    "monthly_interest_rate": 0.0205,
    "interest_type": "pre_price_days",
    "credit_operation_type": "ccb",
    "interest_grace_period": 0,
    "principal_grace_period": 0,
    "fine_configuration": {
      "monthly_rate": 0.01,
      "interest_base": "calendar_days",
      "contract_fine_rate": 0.02
    }
  },
  "collaterals": [
    {
      "collateral_type": "military_payroll",
      "percentage": 1,
      "collateral_data": {
        "reservation_type": "new_credit",
        "registration_code": "146254221"
      }
    }
  ]
}
```

#### Campos chave

| Campo | Descrição |
|---|---|
| `collaterals[].collateral_type` | **`military_payroll`** (obrigatório) |
| `collaterals[].collateral_data.reservation_type` | **`new_credit`** — sempre pra margem livre |
| `collaterals[].collateral_data.registration_code` | Matrícula do militar |
| `financial.installment_face_value` | Parcela — ≤ `balance` retornado na consulta de margem |
| `financial.number_of_installments` | Prazo — ∈ `allowed_installment_numbers` |
| `financial.monthly_interest_rate` | Taxa mensal (ex: `0.0205` = 2,05% a.m.) |

`modality.code` **NÃO** é obrigatório em margem livre — só em refinanciamento.

### Response

Síncrona — retorna o cronograma completo (`disbursement_options[]` com parcelas, IOF, CET).

## 2. Emissão

Cria a CCB e dispara a esteira de averbação → formalização → desembolso.

### Request

ENDPOINT /debt
MÉTODO POST

**Request Body**

```json
{
  "borrower": {
    "name": "JOÃO DA SILVA",
    "email": "joao@email.com",
    "phone": { "number": "900000000", "area_code": "11", "country_code": "+55" },
    "address": {
      "city": "São Paulo", "state": "SP", "number": "215",
      "street": "Gilberto Sabino", "complement": "",
      "postal_code": "12345012", "neighborhood": "Pinheiros"
    },
    "role_type": "issuer",
    "birth_date": "1985-03-12",
    "mother_name": "MARIA DA SILVA",
    "person_type": "natural",
    "individual_document_number": "45507529710",
    "gender": "male",
    "nationality": "brasileiro",
    "is_pep": false,
    "marital_status": "single"
  },
  "financial": {
    "first_due_date": "2026-07-01",
    "installment_face_value": 500.00,
    "disbursement_date": "2026-06-01",
    "number_of_installments": 24,
    "monthly_interest_rate": 0.0205,
    "interest_type": "pre_price_days",
    "credit_operation_type": "ccb",
    "interest_grace_period": 0,
    "principal_grace_period": 0,
    "fine_configuration": {
      "monthly_rate": 0.01,
      "interest_base": "calendar_days",
      "contract_fine_rate": 0.02
    }
  },
  "simplified": true,
  "collaterals": [
    {
      "collateral_type": "military_payroll",
      "percentage": 1,
      "collateral_data": {
        "reservation_type": "new_credit",
        "reservation_method": "creation",
        "registration_code": "146254221",
        "token": "12345678"
      }
    }
  ],
  "disbursement_bank_account": {
    "name": "JOÃO DA SILVA",
    "bank_code": "104",
    "account_type": "checking_account",
    "account_digit": "1",
    "branch_number": "3880",
    "account_number": "000736703806",
    "document_number": "45507529710",
    "transfer_method": "pix"
  },
  "purchaser_document_number": "32402502000135"
}
```

#### `reservation_method` — quando a averbação dispara

**creation (averbação imediata)**

Averbação no Zetra dispara **junto com a criação do `/debt`**. Feedback rápido de margem antes da assinatura — ideal pra fluxos onde o operador quer saber logo se a margem reserva.

**issuing (averbação após formalização)**

Averbação só dispara **após a formalização** (`POST /debt/{KEY}/signed`). Usado quando a assinatura é coletada offline ou em fluxos onde o contrato chega já assinado.

#### Webhooks pós `/debt`

| Webhook | Status | Quando |
|---|---|---|
| `debt` | `waiting_signature` | Operação criada, aguardando assinatura |
| `credit_operation.collateral` | `successfully_accepted` → `successfully_reserved` | Averbação aceita pelo Zetra |
| `debt` | `disbursed` | Desembolso PIX/TED enviado |

→ Próximo passo: [Formalização](./05-formalizacao.md)

## Falhas comuns

| Webhook / Erro | Enumerador | Significado | Ação |
|---|---|---|---|
| Simulação | `INSUFFICIENT_MARGIN` | parcela × prazo > balance | Reduzir parcela ou prazo |
| Simulação | `INVALID_INSTALLMENT_NUMBER` | prazo fora de `allowed_installment_numbers` | Usar um dos prazos permitidos |
| `credit_operation.collateral` | `consignable_margin_exceeded` | margem insuficiente no momento da averbação (Zetra 359) | Reduzir parcela ou aguardar liberação |
| `credit_operation.collateral` | `military_blocked` | Militar com bloqueio em folha (Zetra 352) | Militar precisa resolver com Zetra |
| `credit_operation.collateral` | `communication_error` | Zetra indisponível (cod 241) | QI **retenta automaticamente** |

→ [Lista completa de enumeradores](./08-mapa-de-status.md)

## Sandbox

A sandbox militar **conecta na Zetra real de homologação** — não há whitelist local. Os exemplos de CPF/matrícula/token nesta página (`45507529710`, `146254221`, etc.) são apenas placeholders ilustrativos. Solicite ao time de Integrações QI Tech os dados reais cadastrados em `central_homologa.econsig.com.br`.

→ [Mocks (Sandbox)](./09-mocks-sandbox.md)

---

# Mocks (Sandbox)

URL: /documentation/manual_exercito/mocks-sandbox

:::caution Sandbox militar usa Zetra real de homologação
Ao contrário do SIAPE, o `military-payroll-api` em sandbox **NÃO usa mocks locais**. Em sandbox a integração aponta para o endpoint Host-a-Host de homologação da Zetra (eConsig):

- Sandbox: `https://www.econsig.com.br/central_homologa/services/HostaHostService-v8_0?wsdl`
- Produção: `https://api.econsig.com.br/central/services/HostaHostService`

Os dados de teste (CPFs, matrículas, tokens) são fornecidos **pela própria Zetra** via planilha de homologação oficial. **Suporte Zetra:** suporte@econsig.com.br.
:::

## Convênio QI Sociedade — Exército Brasileiro

| Item | Valor |
|---|---|
| **Cliente** | `QI_SOCIEDADE` |
| **Convênio** | `QI_SOCIEDADE-EB` |
| **Usuário API** | `qi_sociedade_xml` |
| **Senha API** | `qi12345` |
| **Código Serviço** | `001` |
| **Descrição Serviço** | `EMPRÉSTIMO` |
| **Código Verba** | `ZQD` |

## Servidores de Teste

Servidores fictícios cadastrados na Zetra homologação. Todos com **senha do servidor** = `abc123`.

### Cenário: Margem Negativa

Servidor sem margem disponível — toda tentativa de reserva retorna falha.

| # | Matrícula | CPF | Data Nascimento |
|---|---|---|---|
| 1 | `132722899` | `279.315.128-98` | 1983-04-01 |
| 2 | `143320397` | `213.628.178-05` | 1978-02-17 |

### Cenário: Margem Limite R$ 500,00

Margem reduzida — útil para testar limites e validação `INSUFFICIENT_MARGIN`.

| # | Matrícula | CPF | Data Nascimento |
|---|---|---|---|
| 3 | `346578694` | `432.108.069-00` | 1997-04-21 |
| 4 | `982435311` | `432.108.069-00` | 1993-03-20 |

> [!info]
> Matrículas 3 e 4 compartilham o mesmo CPF — útil para testar cenário "mesmo militar, múltiplas matrículas/órgãos".

### Cenário: Margem Limite R$ 10.000,00

Margem confortável — usar para testar fluxos completos de margem livre, refinanciamento e portabilidade.

| # | Matrícula | CPF | Data Nascimento |
|---|---|---|---|
| 5 | `346578694` | `540.770.447-15` | 1997-04-21 |
| 6 | `961683333` | `734.119.817-68` | 1963-04-09 |

### Cenário: BLOQUEADO

Servidor com bloqueio em folha — Zetra retorna `military_blocked` (código 352).

| # | Matrícula | CPF | Data Nascimento |
|---|---|---|---|
| 7 | `234674321` | `045.672.387-02` | 1975-01-01 |
| 8 | `342542124` | `472.635.472-87` | 1964-03-06 |

## Como mapear nos payloads QI

Quando construir o payload de `POST /military_payroll/balance`:

```json
{
  "document_number": "27931512898",
  "registration_code": "132722899",
  "authorization_document_key": "<document_key do POST /upload>",
  "token": "abc123"
}
```

- `document_number` — CPF sem máscara (remova `.` e `-` da tabela acima).
- `registration_code` — matrícula direto da tabela.
- `token` — senha do servidor (`abc123` para todos os testes).
- `authorization_document_key` — upload de qualquer PDF/PNG; em sandbox a Zetra não valida o conteúdo do termo.

## Webhook esperado por cenário

| Cenário | Webhook `military_payroll.balance.status_change` |
|---|---|
| Margem Negativa (1, 2) | `status: failed`, `failure_reason: invalid_balance` ou `consignable_margin_exceeded` |
| Margem Limite R$ 500 (3, 4) | `status: succeeded`, `balance: 500.00`, `allowed_installment_numbers: [...]` |
| Margem Limite R$ 10.000 (5, 6) | `status: succeeded`, `balance: 10000.00`, `allowed_installment_numbers: [...]` |
| BLOQUEADO (7, 8) | `status: failed`, `failure_reason: military_blocked` (Zetra 352) |
| CPF/matrícula fora da tabela | `status: failed`, `failure_reason: military_not_found` (Zetra 293) ou `invalid_registration_code` (Zetra 210) |

## Fluxo end-to-end recomendado

Para validar margem livre, use **teste 5** ou **teste 6** (margem alta):

1. `POST /upload` com PDF qualquer → `document_key`.
2. `POST /military_payroll/balance` com `27931512898` (margem negativa, pra testar failure) ou `54077044715` (margem 10k).
3. Aguardar webhook `military_payroll.balance.status_change`.
4. Em caso de sucesso, `POST /debt_simulation` com `installment_face_value` ≤ `balance` retornado.
5. `POST /debt` com `reservation_method: creation` (margem livre) ou `refinancing` (port/refin).
6. Aguardar webhook `credit_operation.collateral` (`successfully_accepted` → `successfully_reserved`).
7. `POST /debt/{KEY}/signed` com QI Sign ou data-signature opt-in.
8. Aguardar webhook `debt` (`disbursed`).
9. (opcional cancelamento) `PATCH /debt/{KEY}/cancel` dentro de 7 dias úteis → recebe PIX QR → simular pagamento → webhook `reversal`.

Para testar **portabilidade** com contrato externo, combine teste 5 ou 6 com um `original_contract_number` fictício (Zetra homologação aceita strings arbitrárias nesse campo durante port em sandbox).

## Códigos Zetra observados em sandbox

| Código | Mensagem | Mapeamento na QI |
|---|---|---|
| `000` | Operação realizada com sucesso | `succeeded` |
| `210` | Matrícula inválida | `invalid_registration_code` |
| `241` | Erro de comunicação | `communication_error` (QI retenta automaticamente) |
| `293` | Militar não encontrado | `military_not_found` |
| `352` | Militar bloqueado em folha | `military_blocked` |
| `359` | Margem consignável excedida | `consignable_margin_exceeded` |
| `360` | Margem disponível verificada | retorno de `consultarMargem` |

## Operação 24/7 em sandbox

A Zetra em homologação opera **24h/dia, todos os dias** — sem janela operacional restrita (mesmo comportamento da produção).

## Reset de reservas

Reservas Zetra em homologação **persistem indefinidamente** salvo cancelamento explícito. Limpe seu ambiente cancelando as reservas que não forem necessárias (`PATCH /debt/{KEY}/cancel`).

## Não há mocks locais ativos

O arquivo `src/connectors/zetra_mocker.py` no repo `military-payroll-api` existe mas **não é invocado** no fluxo de runtime — `EconsigConnector` chama diretamente o `ECONSIG_SERVICE_ADDRESS` configurado por ambiente. Se algum dia for necessário introduzir mocks locais (ex: Zetra fora do ar bloqueando QA), o `ZetraMocker` está disponível para ser ativado, mas hoje **toda integração de teste passa pela Zetra real de homologação**.

---

# Portabilidade + Refinanciamento

URL: /documentation/manual_exercito/portabilidade-refin

Fluxo de **compra de dívida de consignado militar** (Exército) via assinatura em lote. A QI Tech emite uma CCB de quitação (`debt_purchase`) que paga o banco vendedor, uma CCB de portabilidade (`portability`) que porta o contrato, e um `refinancing` consolidador **sempre obrigatório** que carrega seguro e troco. Tudo assinado uma única vez via QI Sign.

:::info Contas por operação
Cada operação do fluxo exige uma conta de desembolso distinta:

- **`debt_purchase`** → **conta interna QI** em nome do tomador. O desembolso cai nessa conta e quita a dívida origem no banco vendedor via `after_disbursement_actions` (boleto/PIX).
- **`refinancing`** → **conta externa do tomador**. O troco do refinanciamento é desembolsado nessa conta.

O parceiro abre a conta interna via `POST /account` antes da emissão. Ver [Conta Interna para Desembolso](./10-conta-interna-desembolso.md).
:::

## Cenários

O `refinancing` consolidador é **sempre obrigatório** no batch militar — é ele quem carrega seguro e troco.

| Cenário | Composição | Quando usar |
|---|---|---|
| **α** | 1× `debt_purchase` + 1× `portability` + 1× `refinancing` | Porta **uma** dívida externa |
| **β** | N× `debt_purchase` + N× `portability` + 1× `refinancing` | Porta **N dívidas** externas num único envelope |
| **γ** | α ou β + `financial.rebates` no `refinancing` | Qualquer composição acima com prêmio de seguro — gera `insurance_premium_term` automaticamente |

:::caution Regra do seguro e do troco
Seguro (`financial.rebates` com `fee_type: "insurance_premium_qi"`) e troco só podem ser enviados no `refinancing` consolidador (Passo 6).

- **`debt_purchase`** — `rebates` proibido (CCB de quitação não carrega seguro).
- **`portability`** — `rebates` proibido **e** `final_disbursement_amount` deve ser `0`.
:::

## Sequência de chamadas

```
0.  POST /debt_simulation  (opcional — condições do refinanciamento consolidado)

1.  POST /upload   (documentos do tomador)
    └─ (opcional) POST /upload  (documento de identificação do tomador)

2.  POST /account  (conta interna QI p/ debt_purchase)

3.  POST /document/document_batch      → criar envelope de assinatura
    └─ (opcional) personal_document com as chaves do documento de identificação

4.  POST /debt  (debt_purchase)        → desembolso em conta interna QI

5.  POST /debt  (portability)          → sem troco, sem seguro

6.  POST /debt  (refinancing)          → seguro + troco em conta externa

7.  PUT  /document/document_batch/{key}/send_to_signature
```

:::caution Ordem obrigatória de inserção no batch
`debt_purchase` deve ser inserido **antes** da `portability` que o referencia, e a `portability` **antes** do `refinancing` consolidador. Inverter a ordem dispara:

- **`DOC000110`** (HTTP 422) — `portability` cujo `refinanced_credit_operations[].operation_key` não casa com nenhum `debt_purchase` já inserido no batch.
- **`DOC000112`** (HTTP 422) — `refinancing` cujo `refinanced_credit_operations[].operation_key` não casa com nenhuma `portability` já inserida no batch.
:::

---

## 0. Simulação (opcional)

Antes de abrir o lote é possível simular as condições da operação consolidada — parcela, prazo, IOF, CET e troco — sem criar nada. A simulação é **uma só**, feita sobre o `refinancing` consolidador: as dívidas portadas entram como itens de `refinanced_credit_operations`. Não se simula `debt_purchase` nem `portability` separadamente.

ENDPOINT /debt_simulation
MÉTODO POST

:::info Como a dívida portada entra na simulação
Cada item de `refinanced_credit_operations` pode ser informado de duas formas:

- **Dívida externa** (ainda não existe na QI Tech) — informe `due_balance` com o saldo devedor do contrato no banco vendedor. Opcionalmente envie também `monthly_interest_rate` e `disbursement_date` da operação de origem: com esses dois campos a QI Tech **corrige o saldo** até a data de desembolso da nova operação; sem eles, o `due_balance` é usado exatamente como enviado.
- **Operação QI ativa** (refinanciamento puro) — informe `credit_operation_key`. O saldo devedor é calculado pela QI Tech.
:::

**Request Body**

**Dívida externa (port + refin)**

```json
{
  "borrower": {
    "person_type": "natural",
    "individual_document_number": "45507529710"
  },
  "financial": {
    "first_due_date": "2026-07-01",
    "installment_face_value": 500.00,
    "disbursement_date": "2026-06-01",
    "number_of_installments": 24,
    "monthly_interest_rate": 0.0185,
    "interest_type": "pre_price_days",
    "credit_operation_type": "ccb",
    "interest_grace_period": 0,
    "principal_grace_period": 0,
    "fine_configuration": {
      "monthly_rate": 0.01,
      "interest_base": "calendar_days",
      "contract_fine_rate": 0.02
    }
  },
  "collaterals": [
    {
      "collateral_type": "military_payroll",
      "percentage": 1,
      "collateral_data": {
        "reservation_type": "refinancing",
        "registration_code": "146254221"
      }
    }
  ],
  "refinanced_credit_operations": [
    {
      "due_balance": 8500.00,
      "monthly_interest_rate": 0.0225,
      "disbursement_date": "2024-03-15",
      "original_deadline": 60
    }
  ]
}
```

**Operação QI ativa (refin puro)**

```json
{
  "borrower": {
    "person_type": "natural",
    "individual_document_number": "45507529710"
  },
  "financial": {
    "first_due_date": "2026-07-01",
    "installment_face_value": 500.00,
    "disbursement_date": "2026-06-01",
    "number_of_installments": 24,
    "monthly_interest_rate": 0.0185,
    "interest_type": "pre_price_days",
    "credit_operation_type": "ccb",
    "interest_grace_period": 0,
    "principal_grace_period": 0,
    "fine_configuration": {
      "monthly_rate": 0.01,
      "interest_base": "calendar_days",
      "contract_fine_rate": 0.02
    }
  },
  "collaterals": [
    {
      "collateral_type": "military_payroll",
      "percentage": 1,
      "collateral_data": {
        "reservation_type": "refinancing",
        "registration_code": "146254221"
      }
    }
  ],
  "refinanced_credit_operations": [
    { "credit_operation_key": "<key da operação QI a refinanciar>" }
  ]
}
```

**Simulando pelo troco desejado**

```json
{
  "borrower": {
    "person_type": "natural",
    "individual_document_number": "45507529710"
  },
  "financial": {
    "first_due_date": "2026-07-01",
    "final_disbursement_amount": 2000.00,
    "disbursement_date": "2026-06-01",
    "number_of_installments": 24,
    "monthly_interest_rate": 0.0185,
    "interest_type": "pre_price_days",
    "credit_operation_type": "ccb",
    "interest_grace_period": 0,
    "principal_grace_period": 0,
    "fine_configuration": {
      "monthly_rate": 0.01,
      "interest_base": "calendar_days",
      "contract_fine_rate": 0.02
    }
  },
  "collaterals": [
    {
      "collateral_type": "military_payroll",
      "percentage": 1,
      "collateral_data": {
        "reservation_type": "refinancing",
        "registration_code": "146254221"
      }
    }
  ],
  "refinanced_credit_operations": [
    {
      "due_balance": 8500.00,
      "monthly_interest_rate": 0.0225,
      "disbursement_date": "2024-03-15"
    }
  ]
}
```

### Campos chave

| Campo | Descrição |
|---|---|
| `collaterals[].collateral_type` | **`military_payroll`** (obrigatório) |
| `collaterals[].collateral_data.reservation_type` | **`refinancing`** — a simulação representa o consolidador, mesmo quando há portabilidade de dívida externa |
| `collaterals[].collateral_data.registration_code` | Matrícula do militar no Zetra |
| `refinanced_credit_operations[].due_balance` | Saldo devedor da dívida portada. Obrigatório quando a dívida é **externa** (não existe `credit_operation_key`) |
| `refinanced_credit_operations[].monthly_interest_rate` | Taxa mensal do contrato de origem — usada, junto com `disbursement_date`, para corrigir o `due_balance` até o desembolso da nova operação |
| `refinanced_credit_operations[].disbursement_date` | Data de desembolso do contrato de origem |
| `refinanced_credit_operations[].original_deadline` | Prazo original do contrato de origem (informativo) |
| `refinanced_credit_operations[].credit_operation_key` | Chave da operação QI a refinanciar — alternativa ao `due_balance` |
| `financial.installment_face_value` | Parcela desejada — ≤ `balance` retornado na [Consulta de Margem](./02-consulta-margem.md) |
| `financial.final_disbursement_amount` | Troco desejado. Alternativa ao `installment_face_value`: o valor financiado vira `soma dos due_balance + troco` |
| `financial.number_of_installments` | Prazo — ∈ `allowed_installment_numbers` |

:::tip Cenário β (N dívidas portadas)
Para simular a portabilidade de **N** dívidas externas num único envelope, envie **N itens** em `refinanced_credit_operations`, cada um com seu `due_balance`. A simulação devolve as condições do consolidador que quita todas elas.
:::

:::note Diferenças em relação à emissão
- `modality.code` **não** é necessário na simulação — só na emissão (`POST /debt`) da `portability` e do `refinancing`.
- Não é preciso enviar `document_batch_key`, `disbursement_bank_account`, `purchaser_document_number` nem os dados cadastrais completos do tomador: na simulação o `borrower` se resume a `person_type` + `individual_document_number`.
- `portability_data` (com `origin_econsig_id` e `token`) também não entra na simulação — é exigido só na emissão da `portability`.
:::

### Response

Síncrona — retorna `disbursement_options[]` com cronograma de parcelas, IOF, CET e, quando há refinanciamento, o `due_balance` corrigido de cada dívida portada.

---

## 1. Upload dos documentos

Antes de abrir a conta e o lote, faça o **upload dos documentos** exigidos na operação via `POST /upload`. Cada chamada retorna um `document_key`, identificador do documento referenciado nas etapas seguintes.

ENDPOINT /upload
MÉTODO POST

→ Autenticação, headers, FormData e exemplos de código (Python / Node.js) em [Upload de Documentos](../upload_de_documentos/upload_de_documentos.md) .

:::caution Atenção
Salve o `document_key` retornado — ele é necessário para a consulta e o uso futuro do documento.
:::

### (Opcional) Documento de identificação do tomador {#documento-de-identificacao-do-tomador}

Se o seu fluxo já coleta o documento de identificação do tomador (registro militar, RG, CNH etc.), suba os arquivos **neste mesmo passo** e informe as chaves na abertura do lote (Passo 3). A etapa de captura do documento chega **pré-atendida** na jornada de assinatura e o tomador não precisa fotografar o documento novamente.

Suba **um arquivo por lado** do documento, ou **um arquivo único** no caso de documento digital. Não é preciso classificar o arquivo no upload: é o **campo** em que você informa a chave, no Passo 3, que declara qual lado ela representa.

| Campo do `personal_document` | Arquivo esperado |
|---|---|
| `document_identification_front_key` | Frente do documento de identificação |
| `document_identification_back_key` | Verso do documento de identificação |
| `document_identification_full_key` | Documento digital completo, em arquivo único |

Tipos aceitos e os modos de envio de cada um:

| `type` | Documento | Frente e verso | Arquivo único |
|---|---|---|---|
| `military_registry` | Registro militar | ✔ | — |
| `rg` | Registro Geral (RG) | ✔ | — |
| `cnh` | Carteira Nacional de Habilitação | ✔ | ✔ |
| `cin` | Carteira de Identidade Nacional | — | ✔ |

O conjunto efetivamente aceito também depende da jornada de assinatura configurada para o seu requester — um `type` fora dessa configuração retorna **`DOC000130`**.

:::caution Atenção
Esses arquivos ficam vinculados ao lote, mas **não são assinados**: não entram no envelope como documentos assináveis e não participam do `send_to_signature`.
:::

---

## 2. Abrir a conta interna em nome do tomador

Em **compra de dívida**, **portabilidade** e **refinanciamento** do consignado militar (Exército), o desembolso da operação **não vai direto para a conta externa do tomador**: ele cai numa conta interna **em nome do tomador** (aberta pelo parceiro via `POST /account`). É a partir dessa conta que a QI executa as ações pós-desembolso — **quitação do contrato externo**, **repasse de troco**, **conciliação**.

ENDPOINT /account
MÉTODO POST

A conta é aberta pelo **parceiro** (autenticado com seus `client_integration_key`), com `account_owner.individual_document_number` apontando para o **CPF do militar tomador**. Reutilize a conta existente — uma por tomador (não abra uma nova a cada operação).

O campo `account_owner.document_identification` recebe o `document_key` retornado no **Passo 1** (upload do documento de identificação do tomador).

**Request Body**

```json
{
  "account_owner": {
    "person_type": "natural",
    "name": "JOÃO DA SILVA",
    "email": "joao@email.com",
    "individual_document_number": "<CPF DO MILITAR>",
    "mother_name": "MARIA DA SILVA",
    "birth_date": "1985-03-12",
    "is_pep": false,
    "document_identification": "<document_key DO PASSO 1>",
    "phone": {
      "country_code": "055",
      "area_code": "11",
      "number": "900000000"
    },
    "address": {
      "street": "Eixo Monumental",
      "state": "DF",
      "city": "Brasília",
      "neighborhood": "Asa Sul",
      "number": "215",
      "postal_code": "70000000"
    }
  }
}
```

### Campos chave

| Campo | Tipo | Descrição |
|---|---|---|
| `account_owner.person_type` | string | Fixo: **`natural`** (pessoa física) |
| `account_owner.individual_document_number` | string | **CPF do militar tomador** |
| `account_owner.document_identification` | string (UUID) | `document_key` do documento enviado no **Passo 1** |
| `account_owner.is_pep` | boolean | Indica se o tomador é pessoa politicamente exposta |

**Response Body**

```json
{
  "account_key": "1167955-...",
  "account_branch": "0001",
  "account_number": "1167955",
  "account_digit": "1",
  "owner_document_number": "<CPF DO MILITAR>",
  "owner_name": "<NOME DO MILITAR>",
  "bank_code": "329",
  "account_status": "active"
}
```

:::tip Idempotência por tomador
Se já existe conta ativa para esse `owner_document_number` no parceiro, evite chamar `POST /account` de novo — consulte `GET /accounts?owner_document_number= ` antes e reaproveite o `account_key` retornado.
:::

---

## 3. Abrir o lote

ENDPOINT /document/document_batch
MÉTODO POST

**Request Body**

```json
{
  "type": "military_payroll_external_batch",
  "certifier_type": "qi_sign",
  "batch_name": "Lote EB portabilidade - <UUID_UNICO>",
  "request_control_key": "<UUID_UNICO_2>"
}
```

### Campos chave

| Campo | Tipo | Descrição |
|---|---|---|
| `type` | string | Fixo: **`military_payroll_external_batch`** |
| `certifier_type` | string | Fixo: **`qi_sign`** |
| `batch_name` | string | Nome identificador do lote — **único** (não reutilize entre lotes) e **máximo 100 caracteres** |
| `request_control_key` | string (UUIDv4) | **Idempotência** — não reutilize entre lotes |
| `personal_document` | object | (Opcional) Chaves do [documento de identificação do tomador](#documento-de-identificacao-do-tomador) subido no Passo 1 |

### (Opcional) Enviar o documento de identificação pré-coletado {#enviar-documento-de-identificacao}

Informe as `document_key` do Passo 1 no objeto `personal_document`, na **raiz** do payload de abertura do lote:

**Request Body com documento pré-coletado**

```json
{
  "type": "military_payroll_external_batch",
  "certifier_type": "qi_sign",
  "batch_name": "Lote EB portabilidade - <UUID_UNICO>",
  "request_control_key": "<UUID_UNICO_2>",
  "personal_document": {
    "type": "military_registry",
    "document_identification_front_key": "3b28a1a6-51c0-4f0e-9b64-2c98d6a3f1e0",
    "document_identification_back_key": "9d47c2b1-8f3a-4e5d-a1c2-7b6e5d4f3a2b"
  }
}
```

| Campo | Tipo | Descrição |
|---|---|---|
| `personal_document.type` | string | Tipo do documento: `military_registry`, `rg`, `cnh` ou `cin` |
| `personal_document.document_identification_front_key` | string (UUIDv4) | Chave da **frente** — obrigatório junto com `..._back_key` |
| `personal_document.document_identification_back_key` | string (UUIDv4) | Chave do **verso** — obrigatório junto com `..._front_key` |
| `personal_document.document_identification_full_key` | string (UUIDv4) | Chave do **arquivo único** (documento digital) — não combinar com frente e verso |

:::caution Regras
- Envie **frente + verso** **ou** o **arquivo único** — nunca os dois modos juntos. Combinação inválida retorna **`DOC000128`**.
- Os arquivos devem pertencer ao seu requester e já ter o upload concluído — chave inexistente ou de outro requester retorna **`DOC000004`**; arquivo ausente retorna **`DOC000049`**.
- Cada arquivo só pode ser usado em **um lote**; reaproveitar uma chave já vinculada retorna **`DOC000137`**.
- O envio ocorre **apenas na abertura do lote** — não é possível adicionar ou trocar o documento depois. Se algum arquivo for rejeitado, nenhum lote é criado.
- A requisição precisa identificar o titular dos arquivos: envie o header `SELECTED-AGENT`. Sem ele, a abertura retorna **`QIT000004`**.
:::

**Response Body**

```json
{
  "document_batch_key": "17f35e19-a039-468f-aaa7-84aa8edec3dc"
}
```

Guarde o `document_batch_key` retornado — ele é referenciado em todas as chamadas seguintes.

→ Para consultar, limpar documentos ou conferir o batch antes do envio, ver [Assinatura em Lote](./11-assinatura-em-lote.md).

---

## 4. Emitir `debt_purchase`

CCB de **quitação da dívida original**. A QI Tech vai pagar o banco vendedor.

ENDPOINT /debt
MÉTODO POST

:::info Particularidades do `debt_purchase`
- `document_batch_key` incluído na **raiz** do payload (mesmo nível de `borrower`, `financial`).
- `disbursement_bank_account` aponta para a **conta interna QI** do tomador (criada no Passo 2).
- `collaterals` vazio — o `debt_purchase` é a operação-ponte que carrega o saldo externo; **não** leva colateral.
- `after_disbursement_actions` na raiz define a quitação automática da dívida origem após o desembolso (boleto ou PIX do banco vendedor).
:::

**Request Body**

```json
{
  "borrower": {
    "name": "JOÃO DA SILVA",
    "email": "joao@email.com",
    "phone": { "number": "900000000", "area_code": "11", "country_code": "055" },
    "is_pep": false,
    "address": {
      "city": "Brasília",
      "state": "DF",
      "number": "215",
      "street": "Eixo Monumental",
      "complement": "",
      "postal_code": "70000000",
      "neighborhood": "Asa Sul"
    },
    "role_type": "issuer",
    "birth_date": "1985-03-12",
    "mother_name": "MARIA DA SILVA",
    "nationality": "Brasileiro",
    "person_type": "natural",
    "marital_status": "single",
    "individual_document_number": "45507529710",
    "gender": "male",
    "document_identification_type": "rg",
    "document_identification_number": "1234567",
    "document_identification_date": "2015-01-01"
  },
  "financial": {
    "first_due_date": "2026-07-01",
    "installment_face_value": 100,
    "disbursement_date": "2026-06-01",
    "limit_days_to_disburse": 5,
    "number_of_installments": 20,
    "monthly_interest_rate": 0.0185,
    "interest_type": "pre_price_days",
    "fine_configuration": {
      "monthly_rate": 0.01,
      "interest_base": "calendar_days",
      "contract_fine_rate": 0.02
    },
    "credit_operation_type": "ccb",
    "interest_grace_period": 0,
    "principal_grace_period": 0
  },
  "simplified": true,
  "collaterals": [],
  "requester_identifier_key": "<UUIDv4 gerado por request>",
  "disbursement_bank_account": {
    "bank_code": "329",
    "account_digit": "1",
    "branch_number": "0001",
    "account_number": "1167955",
    "document_number": "45507529710",
    "name": "JOÃO DA SILVA"
  },
  "purchaser_document_number": "<CNPJ do comprador>",
  "document_batch_key": "<document_batch_key DO PASSO 3>",
  "after_disbursement_actions": [
    {
      "action_type": "bankslip_payment",
      "action_data": {
        "qr_code": null,
        "destination": null,
        "digitable_line": "03399199530490000005237385601010297590005474921",
        "pix_transfer_type": null,
        "transaction_amount": 0
      }
    }
  ]
}
```

### Campos que devem ser alterados

| Campo | Obrigatório alterar? | Observação |
|---|---|---|
| `document_batch_key` | ✅ Sim | Valor retornado no Passo 3 |
| `borrower.*` | ✅ Sim | Dados reais do tomador |
| `financial.first_due_date` / `disbursement_date` | ✅ Sim | Conforme calendário da operação |
| `financial.installment_face_value` / `number_of_installments` / `monthly_interest_rate` | ✅ Sim | Conforme condições comerciais |
| `purchaser_document_number` | ✅ Sim | CNPJ do comprador (via variável de ambiente) |
| `requester_identifier_key` | ✅ Sim | UUIDv4 único por requisição |
| `disbursement_bank_account` | ✅ Sim | **Conta interna QI em nome do tomador** (Passo 2). O `account_branch` da resposta do `POST /account` vai no campo `branch_number` |
| `after_disbursement_actions` | ✅ Sim | Quitação da dívida origem. `action_type`: `bankslip_payment` (boleto) ou PIX. Preencha `digitable_line` (boleto) ou `qr_code` (PIX) do banco vendedor |

**Response Body**

```json
{
  "proposal_id": "<id interno>",
  "status": 200,
  "key": "<key da operação debt_purchase>",
  "data": {
    "credit_operation_key": "<mesmo valor de key>",
    "status": "waiting_signature"
  }
}
```

**Guarde a `key` retornada** — ela é passada em `refinanced_credit_operations[].operation_key` da `portability` correspondente.

---

## 5. Emitir `portability`

CCB de **portabilidade da dívida**. Cada portabilidade referencia **exatamente um** `debt_purchase` via `refinanced_credit_operations`. **Não carrega seguro nem troco** — ambos vão no `refinancing` consolidador.

ENDPOINT /debt
MÉTODO POST

:::info Particularidades da `portability`
- `collaterals[0].collateral_type` é **`military_payroll`** com `reservation_type: "portability"`.
- `collaterals[0].collateral_data.portability_data` é **obrigatório** — contém o `origin_econsig_id` (contrato de origem no Zetra) e o `token` do militar.
- `refinanced_credit_operations` carrega a `key` do `debt_purchase` correspondente.
- `modality.code` **`"0202"`** é obrigatório em portabilidade/refinanciamento do Exército.
:::

:::caution Portabilidade sem seguro e sem troco
Em batch militar, a `portability` **não pode** carregar `financial.rebates` (seguro). O seguro é enviado exclusivamente no `refinancing` consolidador. A QI Tech rejeita o `POST /debt` que violar essa regra.
:::

**Request Body**

```json
{
  "borrower": { "...": "mesmo borrower do Passo 4" },
  "financial": {
    "first_due_date": "2026-07-01",
    "disbursement_date": "2026-06-01",
    "limit_days_to_disburse": 5,
    "number_of_installments": 20,
    "monthly_interest_rate": 0.0185,
    "interest_type": "pre_price_days",
    "final_disbursement_amount": 0,
    "fine_configuration": {
      "monthly_rate": 0.01,
      "interest_base": "calendar_days",
      "contract_fine_rate": 0.02
    },
    "credit_operation_type": "ccb",
    "interest_grace_period": 0,
    "principal_grace_period": 0
  },
  "simplified": true,
  "collaterals": [
    {
      "percentage": 1,
      "collateral_type": "military_payroll",
      "collateral_data": {
        "reservation_type": "portability",
        "reservation_method": "issuing",
        "registration_code": "146254221",
        "token": "12345678",
        "portability_data": {
          "origin_econsig_id": "2016587",
          "token": "12345678"
        }
      }
    }
  ],
  "modality": { "code": "0202" },
  "requester_identifier_key": "<UUIDv4>",
  "disbursement_bank_account": { "...": "mesma conta interna do Passo 4" },
  "purchaser_document_number": "<CNPJ do comprador>",
  "document_batch_key": "<document_batch_key DO PASSO 3>",
  "refinanced_credit_operations": [
    { "operation_key": "<key DO PASSO 4>" }
  ]
}
```

### Campos que devem ser alterados

| Campo | Obrigatório alterar? | Observação |
|---|---|---|
| `document_batch_key` | ✅ Sim | Valor retornado no Passo 3 |
| `refinanced_credit_operations[0].operation_key` | ✅ Sim | `key` do `debt_purchase` referenciado (Passo 4) |
| `collaterals[0].collateral_data.registration_code` | ✅ Sim | Matrícula do militar no Zetra |
| `collaterals[0].collateral_data.token` | ✅ Sim | Token Zetra do militar |
| `collaterals[0].collateral_data.portability_data.origin_econsig_id` | ✅ Sim | ID do contrato de origem no Zetra (e-consignado da instituição vendedora) |
| `collaterals[0].collateral_data.portability_data.token` | ✅ Sim | Token Zetra do militar |
| `modality.code` | 🚫 Fixo | Sempre `"0202"` em portabilidade/refinanciamento do Exército |
| `financial.installment_face_value` | 🚫 Não enviar | Valor da parcela (auto calculado) |
| `financial.rebates` | 🚫 Proibido | Seguro não é aceito em portabilidade — só no `refinancing` |

**Response Body**

```json
{
  "proposal_id": "<id interno>",
  "status": 200,
  "key": "<key da operação portability>",
  "data": {
    "credit_operation_key": "<mesmo valor de key>",
    "status": "waiting_signature"
  }
}
```

**Guarde a `key` desta portabilidade** — usada em `refinanced_credit_operations` do `refinancing` consolidador (Passo 6).

### Erros possíveis na criação

| Código | HTTP | Quando |
|---|---|---|
| `DOC000110` | 422 | `refinanced_credit_operations[].operation_key` não casa com nenhum `credit_operation_key` de `debt_purchase` já inserido no batch |
| `DOC000114` | 422 | `refinanced_credit_operations[].operation_key` já está em outra portabilidade do mesmo batch (duplicidade) |
| `COP000515` | 400 | `final_disbursement_amount` ≠ `0` — portabilidade não carrega troco |
| `COP000516` | 400 | `financial.rebates` presente — portabilidade não aceita seguro |
| `INVALID_MODALITY_CODE` | 400 | portabilidade sem `modality.code: "0202"` |

---

## 6. Emitir `refinancing` consolidador

CCB **mãe** que consolida as portabilidades num único instrumento. **Sempre obrigatória** no batch militar — tanto no cenário α (1 portabilidade) quanto no β (N portabilidades). É a única operação do fluxo que carrega **seguro** e **troco**.

ENDPOINT /debt
MÉTODO POST

:::info Particularidades do `refinancing` consolidador
- `collaterals[0].collateral_type` é **`military_payroll`** com `reservation_type: "refinancing"`.
- `refinanced_credit_operations` lista as `key` de **todas** as portabilidades do batch.
- `disbursement_bank_account` aponta para a **conta externa do tomador** — destino do troco.
- `modality.code` **`"0202"`** é obrigatório.
- `financial.rebates` é **opcional** — único lugar do fluxo que aceita seguro.
- `after_disbursement_actions` só é enviado **quando há seguro** — liquida o prêmio após o desembolso.
:::

:::caution `after_disbursement_actions` exige seguro
`after_disbursement_actions` só pode ser enviado no `refinancing` **quando a operação tem seguro** (`financial.rebates` presente). Enviar `after_disbursement_actions` sem `rebates` faz a QI Tech rejeitar o `POST /debt`.
:::

**Request Body**

**Sem seguro**

```json
{
  "borrower": { "...": "mesmo borrower" },
  "financial": {
    "first_due_date": "2026-07-01",
    "installment_face_value": 1000,
    "disbursement_date": "2026-06-01",
    "limit_days_to_disburse": 5,
    "number_of_installments": 20,
    "monthly_interest_rate": 0.0185,
    "interest_type": "pre_price_days",
    "fine_configuration": {
      "monthly_rate": 0.01,
      "interest_base": "calendar_days",
      "contract_fine_rate": 0.02
    },
    "credit_operation_type": "ccb",
    "interest_grace_period": 0,
    "principal_grace_period": 0
  },
  "simplified": true,
  "collaterals": [
    {
      "percentage": 1,
      "collateral_type": "military_payroll",
      "collateral_data": {
        "reservation_type": "refinancing",
        "reservation_method": "issuing",
        "registration_code": "146254221",
        "token": "12345678"
      }
    }
  ],
  "modality": { "code": "0202" },
  "requester_identifier_key": "<UUIDv4>",
  "disbursement_bank_account": { "...": "conta externa do tomador" },
  "purchaser_document_number": "<CNPJ do comprador>",
  "document_batch_key": "<document_batch_key DO PASSO 3>",
  "refinanced_credit_operations": [
    { "operation_key": "<key da portabilidade 1>" },
    { "operation_key": "<key da portabilidade 2>" }
  ]
}
```

**Com seguro + troco (Cenário γ)**

```json
{
  "borrower": { "...": "mesmo borrower" },
  "financial": {
    "first_due_date": "2026-07-01",
    "installment_face_value": 1500,
    "disbursement_date": "2026-06-01",
    "limit_days_to_disburse": 5,
    "number_of_installments": 20,
    "monthly_interest_rate": 0.0185,
    "interest_type": "pre_price_days",
    "fine_configuration": {
      "monthly_rate": 0.01,
      "interest_base": "calendar_days",
      "contract_fine_rate": 0.02
    },
    "credit_operation_type": "ccb",
    "interest_grace_period": 0,
    "principal_grace_period": 0,
    "rebates": [
      {
        "fee_type": "insurance_premium_qi",
        "description": "credit_insurance_blindado"
      }
    ]
  },
  "simplified": true,
  "collaterals": [
    {
      "percentage": 1,
      "collateral_type": "military_payroll",
      "collateral_data": {
        "reservation_type": "refinancing",
        "reservation_method": "issuing",
        "registration_code": "146254221",
        "token": "12345678"
      }
    }
  ],
  "modality": { "code": "0202" },
  "requester_identifier_key": "<UUIDv4>",
  "disbursement_bank_account": { "...": "conta externa do tomador" },
  "purchaser_document_number": "<CNPJ do comprador>",
  "document_batch_key": "<document_batch_key DO PASSO 3>",
  "refinanced_credit_operations": [
    { "operation_key": "<key da portabilidade 1>" },
    { "operation_key": "<key da portabilidade 2>" }
  ],
  "after_disbursement_actions": [
    {
      "action_type": "bankslip_payment",
      "action_data": {
        "qr_code": null,
        "destination": null,
        "digitable_line": "03399199530490000005237385601010297590005474921",
        "pix_transfer_type": null,
        "transaction_amount": 0
      }
    }
  ]
}
```

### Campos que devem ser alterados

| Campo | Obrigatório alterar? | Observação |
|---|---|---|
| `document_batch_key` | ✅ Sim | Valor retornado no Passo 3 |
| `refinanced_credit_operations` | ✅ Sim | **Todas** as `key` das portabilidades emitidas no Passo 5 |
| `collaterals[0].collateral_data.registration_code` | ✅ Sim | Matrícula do militar no Zetra |
| `collaterals[0].collateral_data.token` | ✅ Sim | Token Zetra do militar |
| `reservation_method` | ✅ Sim | Sempre `"issuing"` para o consolidador |
| `modality.code` | 🚫 Fixo | Sempre `"0202"` |
| `disbursement_bank_account` | ✅ Sim | **Conta externa do tomador** — destino do troco |
| `financial.rebates` | ⚠️ Opcional | Único lugar do fluxo que aceita seguro. Incluir `[{ "fee_type": "insurance_premium_qi", ... }]` apenas se a operação tem seguro |
| `financial.final_disbursement_amount` | 🚫 Não enviar | Valor final do desembolso (troco) calculado automaticamente baseado no valor da parcela |
| `after_disbursement_actions` | ⚠️ Só com seguro | Liquida o prêmio do seguro após desembolso. **Só envie quando `rebates` está presente** — caso contrário a QI Tech rejeita o `POST /debt` |

### Erros possíveis na criação

| Código | HTTP | Quando |
|---|---|---|
| `DOC000109` | 422 | Batch já contém outro `refinancing` — só 1 por batch |
| `DOC000112` | 422 | `refinanced_credit_operations[].operation_key` não casa com nenhum `credit_operation_key` de portabilidade no batch |
| `COP000517` | 400 | `refinancing` **com** seguro (`rebates`) sem nenhuma `after_disbursement_actions` — seguro exige ao menos uma ação pós-desembolso |
| `COP000518` | 400 | `refinancing` **sem** seguro carregando `after_disbursement_actions` — só permitido quando há `rebates` |
| `INVALID_MODALITY_CODE` | 400 | refinanciamento sem `modality.code: "0202"` |

---

## 7. Enviar para assinatura

Fecha o lote e dispara os documentos para o QI Sign. **Antes desse PUT, nada é enviado ao militar.**

ENDPOINT /document/document_batch/DOCUMENT_BATCH_KEY/send_to_signature
MÉTODO PUT

Body: `{}`. Response: **HTTP 200**.

### Erros possíveis no envio

| Código | HTTP | Quando |
|---|---|---|
| `DOC000108` | 422 | Batch contém mais de 1 `insurance_premium_term` |
| `DOC000109` | 422 | Batch contém mais de 1 `refinancing` |
| `DOC000110` | 422 | `portability` cujo `refinanced_op` não casa com nenhum `debt_purchase` no batch |
| `DOC000111` | 422 | Batch **sem** `refinancing` consolidador |
| `DOC000114` | 422 | `debt_purchase` referenciado por 0 ou mais de 1 portabilidade |

:::tip Conferir antes de enviar
Use `GET /document/document_batch/DOCUMENT_BATCH_KEY` para listar os documentos agrupados e confirmar a composição antes do `send_to_signature`. Ver [Assinatura em Lote](./11-assinatura-em-lote.md).
:::

→ Próximo passo: [Formalização](./05-formalizacao.md)

---

## Mapa consolidado de erros

| Código | HTTP | Ponto de disparo | Quando |
|---|---|---|---|
| `DOC000108` | 422 | criação + envio | Mais de 1 `insurance_premium_term` no batch |
| `DOC000109` | 422 | criação + envio | Mais de 1 `refinancing` no batch |
| `DOC000110` | 422 | criação + envio | `portability` com `refinanced_op` sem `debt_purchase` casado no batch |
| `DOC000111` | 422 | envio | Batch sem `refinancing` consolidador |
| `DOC000112` | 422 | criação | `refinancing` com `refinanced_op` sem portabilidade casada no batch |
| `DOC000114` | 422 | criação + envio | `debt_purchase` referenciado por ≠ 1 portabilidade (0 órfão ou ≥ 2 duplicado) |
| `COP000515` | 400 | criação (`portability`) | `final_disbursement_amount` ≠ `0` na portabilidade |
| `COP000516` | 400 | criação (`portability`) | `financial.rebates` enviado na portabilidade |
| `COP000517` | 400 | criação (`refinancing`) | `refinancing` com seguro sem nenhuma `after_disbursement_actions` |
| `COP000518` | 400 | criação (`refinancing`) | `refinancing` sem seguro carregando `after_disbursement_actions` |
| `INVALID_MODALITY_CODE` | 400 | criação (`portability`/`refinancing`) | operação sem `modality.code: "0202"` |
| `DOC000128` | 400 | abertura do lote | `type` do `personal_document` não suporta o modo enviado (frente e verso × arquivo único) |
| `DOC000129` | 400 | abertura do lote | Jornada configurada para o requester não coleta documento de identificação |
| `DOC000130` | 400 | abertura do lote | `type` do `personal_document` fora dos tipos aceitos pela configuração do requester |
| `DOC000137` | 400 | abertura do lote | `document_key` do documento de identificação já vinculada a outro lote |
| `DOC000004` | 404 | abertura do lote | `document_key` do documento de identificação não encontrada (inclui arquivo de outro requester) |
| `DOC000049` | 400 | abertura do lote | Documento de identificação sem arquivo — upload não concluído |
| `QIT000004` | 403 | abertura do lote | `personal_document` enviado sem o header `SELECTED-AGENT` |

:::info Notas sobre erros recorrentes
- `DOC000110` dispara em **dois momentos**: na criação da portabilidade (validação imediata) e no envio (cobertura defensiva).
- `DOC000114` dispara em **dois momentos**: na criação da segunda portabilidade duplicada e no envio (cobre o `debt_purchase` órfão, i.e. `count = 0`).
- `DOC000111` dispara **apenas no envio** — não há validação na criação.
- Batches que **não** são `military_payroll_external_batch` não disparam nenhuma das validações acima.
:::

---

## Glossário

| Termo | Significado |
|---|---|
| **CCB** | Cédula de Crédito Bancário — instrumento de dívida emitido pelo banco |
| **Zetra** | Sistema de gestão do e-consignado militar (Exército) — onde a reserva de margem é averbada |
| **matrícula militar** | `registration_code` — identificador do militar no Zetra |
| **token** | Token Zetra do militar — autoriza a operação de consignado (6 a 8 caracteres) |
| **portability_data** | Dados do contrato de origem no Zetra (`origin_econsig_id`, `token`) da instituição vendedora |
| **origin_econsig_id** | ID do e-consignado de origem no Zetra — o contrato externo que está sendo portado |
| **modality.code** | Código de modalidade do consignado militar — **`"0202"`** para portabilidade/refinanciamento |
| **credit_operation_key** | Chave única da operação retornada por `POST /debt` — também chamada `key` |
| **insurance_premium_term** | Documento extra gerado automaticamente no batch quando uma `portability` ou `refinancing` carrega `financial.rebates` com `fee_type: "insurance_premium_qi"`. **Nunca** originado de `debt_purchase` |
| **QI Sign** | Provedor de assinatura digital QI Tech (configurado via `certifier_type: "qi_sign"`) |

---

# Recálculo e Retentativa de Averbação

URL: /documentation/manual_exercito/recalculo

Fluxo de **recálculo da compra de dívida** do consignado militar. Quando o Exército recusa a averbação — margem insuficiente, prazo acima do permitido, consignação indeferida — a operação já assinada **não precisa ser cancelada**: o parceiro recalcula as condições a partir de um novo valor de parcela e reenvia a averbação, na mesma CCB e no mesmo lote.

O recálculo também é o passo que **dimensiona o `refinancing` consolidador** depois que as portabilidades do lote são averbadas — nesse caso não há recusa nenhuma envolvida, apenas o ajuste do valor final da operação mãe.

São duas rotas, usadas em conjunto:

ENDPOINT /v2/credit_operation/ CREDIT_OPERATION_KEY /recalculate
MÉTODO PATCH

ENDPOINT /debt/ CREDIT_OPERATION_KEY /reservation/retry
MÉTODO PATCH

:::info Divisão de responsabilidade entre as duas rotas
- `recalculate` reescreve as condições financeiras da CCB **e** propaga essas condições para a averbação. Não é necessária nenhuma chamada adicional para atualizar a reserva — mas o `reservation_status` **não muda**.
- `reservation/retry` é o que devolve uma averbação recusada (`pending_requester_action`) para a fila de envio (`pending_reservation`), de onde a QI Tech a reenvia ao Exército.

Uma averbação recusada só volta a ser tentada com o `reservation/retry`. Um recálculo feito antes do envio da averbação (caso do consolidador em `created` / `pending_reservation`) **não** exige retry — a averbação segue o fluxo normal já com as condições novas.
:::

## Quando usar

| Situação | O que fazer |
|---|---|
| Webhook `credit_operation.collateral` com `reservation_status: pending_requester_action` na portabilidade | Recalcular a portabilidade com parcela que caiba na margem informada e retentar |
| Todas as portabilidades do lote averbadas (`reserved`) | Recalcular o `refinancing` consolidador para o valor definitivo |
| Webhook `credit_operation.collateral` com `reservation_status: pending_requester_action` no consolidador | Recalcular o consolidador e retentar |
| Averbação parada por token inválido (`pending_valid_token`) | Não é recálculo — atualizar o token do militar |
| Falha de comunicação com o Exército | Nada a fazer — a QI Tech retenta automaticamente |
| Garantia já constituída (`reserved`) | Nada a fazer — o recálculo é recusado com `COP000556` |
| Condições novas fora do que a operação suporta | Cancelar e reemitir o lote (ver [Cancelamento](./06-cancelamento.md)) |

## Por que a averbação para

Recusas que **nenhuma retentativa automática resolve** deixam a averbação parada em `pending_requester_action`, aguardando condições novas do parceiro, em vez de cancelar a operação. O aviso chega pelo webhook `credit_operation.collateral` (ver [Webhooks](./07-webhooks.md)):

```json
{
  "webhook_type": "credit_operation.collateral",
  "key": "8916175e-18df-4845-a238-643f52b77be4",
  "data": {
    "collateral_type": "military_payroll",
    "collateral_constituted": false,
    "operation_type": "portability_for_refinancing",
    "collateral_data": {
      "reservation_status": "pending_requester_action",
      "cancel_reason": "consignable_margin_exceeded"
    }
  },
  "event_datetime": "2026-09-08 14:30:00"
}
```

### Recusas na inclusão da consignação

| `cancel_reason` | Código Zetra | Significado |
|---|---|---|
| `consignable_margin_exceeded` | 359 | Margem consignável excedida |
| `period_quantity_exceeded` | 347 | Quantidade de parcelas acima do permitido |
| `military_payroll_period_quantity_exceeded` | 471 | Quantidade de parcelas acima do permitido na verba |
| `military_blocked` | 352 | Militar com bloqueio em folha |
| `military_not_found` | 293 | Militar não localizado com CPF/matrícula informados |
| `portability_not_found` | 294 | Contrato de origem não localizado para portabilidade |

### Recusas na confirmação da averbação

| `cancel_reason` | Situação no Exército | Significado |
|---|---|---|
| `rejected` | `Indeferida` | Averbação indeferida |
| `suspended` | `Suspensa` | Consignação suspensa |
| `suspend_by_manager` | `Suspensa Pelo Gestor` | Consignação suspensa pelo gestor |
| `closed_by_exclusion` | `Encerrado por Exclusão` | Consignação encerrada por exclusão |

:::caution Nem toda parada é recálculo
`pending_valid_token` (token do militar inválido ou ausente) e falhas de comunicação **não** entram nesse fluxo: a primeira se resolve com a atualização do token, a segunda é retentada automaticamente pela QI Tech.
:::

## Ciclo completo do lote

O lote é recalculado em duas rodadas, com a resposta do Exército no meio: primeiro as **portabilidades**, depois o **refinanciamento consolidador**.

```
1.  PATCH /v2/credit_operation/{portability}/recalculate     nova parcela da portabilidade
        ↓
2.  PATCH /debt/{portability}/reservation/retry              204 — volta para pending_reservation
        ↓
3.  [ Exército responde a averbação reenviada ]
        ├── reserved                 → repita 1 e 2 nas demais portabilidades, depois siga para 4
        └── pending_requester_action → volta ao passo 1 com parcela menor
        ↓
4.  PATCH /v2/credit_operation/{refinancing}/recalculate     parcela definitiva do consolidador
        ↓
5.  PATCH /debt/{refinancing}/reservation/retry              204 (só se o consolidador estiver parado)
        ↓
6.  [ Exército averba o consolidador ]                       → operação segue para desembolso
```

:::caution Ordem obrigatória
As portabilidades são recalculadas e averbadas **antes** do consolidador. O recálculo do `refinancing` é recusado com **`MPR000037`** enquanto qualquer portabilidade do lote não estiver em `reserved` — é o valor averbado das portabilidades que dimensiona o consolidador.

Num lote do cenário β (N portabilidades), **todas** passam pelos passos 1 a 3 antes do passo 4.
:::

---

## 1. Recalcular a portabilidade

Recalcula as condições financeiras da portabilidade a partir do novo valor de parcela. O **valor líquido é travado**: a portabilidade tem de quitar exatamente o saldo devedor do contrato de origem, então quem cede é a **taxa** — parcela menor ⇒ taxa menor, parcela maior ⇒ taxa maior.

ENDPOINT /v2/credit_operation/ CREDIT_OPERATION_KEY /recalculate
MÉTODO PATCH

### Path Params

credit_operation_key
string (UUID)
obrigatório
Chave da portabilidade — a `key` retornada pelo `POST /debt` do Passo 5 de [Portabilidade + Refinanciamento](./04-portabilidade-refin.md).

### Body Params

installment_amount
number
obrigatório
Novo valor total da parcela, maior que `0` e com **no máximo 2 casas decimais**. É o valor que **toda** parcela do fluxo vai passar a ter.

```json
{
  "installment_amount": 95.00
}
```

:::caution `installment_amount` é o único campo aceito
Qualquer outra condição (`monthly_interest_rate`, `number_of_installments`, `final_disbursement_amount`) é recusada com **`COP000557`**. Campo desconhecido, corpo vazio, valor não numérico ou `installmentAmount` em camelCase são recusados com **`QIT000001`**; três casas decimais, com **`COP000564`**.
:::

### Pré-condições

Só é recalculável a operação que:

| Condição | Erro quando não atendida |
|---|---|
| Tem garantia `military_payroll` | `COP000553` |
| Tem tipo de reserva `portability` ou `refinancing` na garantia | `COP000554` / `COP000568` |
| Está **assinada e emitida** (status `issued`) | `COP000555` |
| Ainda **não teve a garantia constituída** | `COP000556` |
| Tem contrato de origem com saldo devedor | `COP000566` |
| Tem opção de desembolso em ou após hoje | `COP000559` |
| Não tem parcela com valor pago | `COP000561` |
| Não tem entrada emitida | `COP000562` |
| Tem a averbação parada em `pending_requester_action` | `MPR000009` |

:::info A averbação só existe depois da assinatura
A averbação é solicitada depois do `signature_finished`, não no `POST /debt`. Antes disso o recálculo responde **`MPR000017`** (não há averbação para a operação). Com a averbação já solicitada mas ainda em `pending_reservation` ou `pending_confirmation`, responde **`MPR000009`**, e a descrição do erro traz o **status atual** — é assim que se confere em que ponto a averbação está, além do webhook `credit_operation.collateral` e do `GET /debt/{DEBT_KEY}/collateral`.
:::

### Response

STATUS 200

Devolve a operação recalculada inteira, com as parcelas reescritas. Campos relevantes:

**Response Body**

```json
{
  "credit_operation_key": "8916175e-18df-4845-a238-643f52b77be4",
  "credit_operation_status": "issued",
  "operation_type": "portability_for_refinancing",
  "collateral_type": "military_payroll",
  "collateral_constituted": false,
  "disbursement_date": "2026-09-16",
  "number_of_installments": 20,
  "issue_amount": 1686.84,
  "disbursed_issue_amount": 1680.84,
  "final_disbursement_amount": 0,
  "base_iof": 5.98,
  "additional_iof": 0.02,
  "total_iof": 6.00,
  "annual_cet": 0.1495,
  "interest_type": "pre_price_days",
  "prefixed_interest_rate": {
    "interest_base": "calendar_days",
    "daily_rate": 0.00035739,
    "monthly_rate": 0.01079689,
    "annual_rate": 0.13756
  },
  "installments": [
    {
      "installment_key": "1b6a2c58-0f37-4f21-9c2e-2a7f0c1d4e55",
      "installment_number": 1,
      "due_date": "2026-10-16",
      "total_amount": 95.00,
      "principal_amortization_amount": 76.79,
      "pre_fixed_amount": 18.21,
      "installment_status": "opened"
    },
    { "...": "parcelas 2 a 20" }
  ],
  "disbursement_options": [
    { "...": "mesma estrutura, uma entrada por data de desembolso disponível" }
  ]
}
```

:::info Opções de desembolso
Havendo várias opções de desembolso, o recálculo reescreve **todas** as que ainda estão dentro da janela (data em ou após hoje) e aplica na operação a que corresponde à `disbursement_date` vigente. Opções com data passada são preservadas como estão. Leia sempre a opção cuja `disbursement_date` é a da operação.
:::

### O que muda e o que fica travado

| Campo | Comportamento na portabilidade |
|---|---|
| `installments[].total_amount` | **Todas** as parcelas passam a valer exatamente o `installment_amount` enviado |
| `disbursed_issue_amount` | **Travado** — igual ao saldo devedor do contrato de origem |
| `issue_amount` | Recalculado — igual ao valor líquido somado ao IOF |
| `prefixed_interest_rate.*` | Recalculada. Parcela menor ⇒ taxa menor; `daily` < `monthly` < `annual` |
| `number_of_installments` | **Travado** |
| `installments[].due_date` / `installment_key` | **Preservados** — as parcelas são reescritas, não recriadas |
| `final_disbursement_amount` | **`0`** na portabilidade (sem troco) |
| `additional_iof` | Cobrado somente sobre dinheiro novo (`issue_amount` menos o saldo devedor portado) |
| Σ `principal_amortization_amount` | Igual ao `issue_amount` |
| Componentes da parcela | `principal_amortization_amount` + `pre_fixed_amount` = `total_amount` |

:::tip Como conferir a resposta
Em `interest_type: pre_price_days`, o valor presente das parcelas descontado pela `daily_rate` por **dias corridos** reconstitui o `issue_amount`:

`Σ total_amount / (1 + daily_rate) ^ (due_date − disbursement_date) == issue_amount`
:::

### Recálculo é tudo-ou-nada

Se o resultado do cálculo violar qualquer uma das travas da tabela acima, a resposta é **`COP000560`**, com o nome da invariante violada, o valor esperado e o obtido na descrição. Se a averbação recusar as condições novas (por exemplo, `MPR000036`), a resposta é o próprio erro da averbação.

Nos dois casos **nada é gravado**: a operação continua com as condições da emissão e a averbação, com as condições anteriores. Basta corrigir o `installment_amount` e chamar de novo.

---

## 2. Retentar a averbação da portabilidade

Devolve a averbação de `pending_requester_action` para `pending_reservation`, já com as condições gravadas pelo recálculo. A QI Tech a reenvia ao Exército na varredura seguinte.

ENDPOINT /debt/ CREDIT_OPERATION_KEY /reservation/retry
MÉTODO PATCH

### Body Params

A rota **não aceita nenhum campo**. Qualquer propriedade enviada é recusada com `QIT000001` — inclusive token, que tem rota própria.

```json
{}
```

:::caution O corpo vazio é `{}`, não ausente
A rota não tem campo obrigatório, mas a requisição **sem corpo** é recusada com `GDF000028`. Envie `{}` — e calcule a assinatura sobre a string `{}`, não sobre a string vazia.
:::

### Response

STATUS 204

**204 sem corpo** é o sucesso: a averbação voltou para `pending_reservation`. A rota apenas reposiciona a averbação na fila — o resultado do reenvio chega por webhook.

### Erros possíveis

| HTTP | Código | Quando |
|---|---|---|
| 400 | `QIT000001` | Corpo com qualquer campo |
| 403 | `QIT000003` | Requisitante da chamada não identificado |
| 404 | `GDF000028` | Requisição sem corpo — envie `{}` |
| 404 | `MPR000017` | Não há averbação para essa operação, ou ela pertence a outro requisitante |
| 409 | `MPR000009` | Averbação fora de `pending_requester_action` — o retry só vale para a averbação parada aguardando o requisitante |

---

## 3. Averbado com sucesso, ou novo recálculo

O resultado do reenvio chega pelo webhook `credit_operation.collateral`:

| `reservation_status` | `collateral_constituted` | O que fazer |
|---|---|---|
| `reserved` | `true` | **Averbado.** Portabilidade fechada — repita nas demais portabilidades e siga para o passo 4 |
| `pending_confirmation` | `false` | Exército aceitou a inclusão, aguardando confirmação da averbação — espere o próximo evento |
| `pending_requester_action` | `false` | **Recusado de novo.** Repita os passos 1 e 2 com parcela menor (ver `cancel_reason`) |
| `pending_valid_token` | `false` | Token do militar inválido — atualizar o token; não é caso de recálculo |

O ciclo recálculo → retry pode ser repetido quantas vezes a margem exigir. Cada iteração parte do estado atual da operação: o valor líquido continua travado no saldo devedor do contrato de origem, só a taxa acompanha a parcela.

:::caution Um recálculo por ciclo de averbação
Faça **um** `recalculate`, então o `reservation/retry`, e espere a resposta do Exército antes de recalcular de novo. Recalcular duas vezes seguidas, sem o retry no meio, sobrescreve as condições que ainda não foram enviadas.
:::

:::tip Consulta de status
Além do webhook, o estado atual da averbação pode ser lido em `GET /debt/{DEBT_KEY}/collateral` (`last_response` + `reservation_status`). Respeite um intervalo de **no mínimo 25 segundos** entre consultas — a atualização do estado é assíncrona e leituras mais frequentes não refletem mudança.
:::

---

## 4. Recalcular o refinanciamento consolidador

Com todas as portabilidades do lote averbadas, recalcule o `refinancing` consolidador — a CCB mãe que carrega **seguro e troco**. Mesma rota, mesmo corpo, com duas diferenças de comportamento.

ENDPOINT /v2/credit_operation/ CREDIT_OPERATION_KEY /recalculate
MÉTODO PATCH

```json
{
  "installment_amount": 9500.00
}
```

Use a `key` do `refinancing` retornada no Passo 6 de [Portabilidade + Refinanciamento](./04-portabilidade-refin.md).

### Diferenças em relação à portabilidade

| Comportamento | Portabilidade | Refinanciamento consolidador |
|---|---|---|
| Taxa (`prefixed_interest_rate`) | Recalculada, acompanha a parcela | **Preservada** — a da emissão |
| `issue_amount` / `disbursed_issue_amount` | Líquido travado no saldo devedor | **Acompanham a parcela** — parcela menor ⇒ emissão menor |
| `final_disbursement_amount` | Sempre `0` | **≠ 0** — é o troco, recalculado junto com a parcela |
| IOF | Só sobre dinheiro novo | Idem — sobre o `issue_amount` líquido do saldo portado |
| Averbação exigida em `pending_requester_action` | Sim | **Não** — aceita também `created` e `pending_reservation` |
| Portabilidades do lote averbadas | Não se aplica | **Obrigatório** — todas em `reserved` (`MPR000037`) |

:::info Por que o consolidador aceita recálculo sem recusa
O valor do consolidador só fica conhecido depois que as portabilidades de origem são averbadas. Por isso o recálculo do `refinancing` é aceito nos estados `created`, `pending_reservation` e `pending_requester_action` — nos dois primeiros é o ajuste normal do lote, sem retry: a averbação é enviada já com as condições novas.
:::

**Response Body**

```json
{
  "credit_operation_key": "50b950be-e7ec-484c-8c59-e7a1bbae020b",
  "credit_operation_status": "issued",
  "operation_type": "refinancing",
  "collateral_type": "military_payroll",
  "collateral_constituted": false,
  "disbursement_date": "2026-09-16",
  "number_of_installments": 20,
  "issue_amount": 157000.00,
  "disbursed_issue_amount": 155000.00,
  "final_disbursement_amount": 55000.00,
  "base_iof": 1783.40,
  "additional_iof": 216.60,
  "total_iof": 2000.00,
  "prefixed_interest_rate": {
    "interest_base": "calendar_days",
    "daily_rate": 0.00056214,
    "monthly_rate": 0.01700000,
    "annual_rate": 0.22421
  },
  "installments": [
    {
      "installment_key": "7c3d9e11-52a8-4b0e-9f41-b0a6d2c9e733",
      "installment_number": 1,
      "due_date": "2026-10-16",
      "total_amount": 9500.00,
      "principal_amortization_amount": 6832.14,
      "pre_fixed_amount": 2667.86,
      "installment_status": "opened"
    },
    { "...": "parcelas 2 a 20" }
  ]
}
```

### Limite de redução do valor líquido

O valor líquido do consolidador **não pode cair mais de 15%** em relação ao valor da emissão original. Parcela que produza um líquido abaixo desse piso é recusada com **`MPR000036`**, e a descrição do erro traz o valor original, o novo e o mínimo permitido. Aumento não tem teto.

Reduções maiores que 15% exigem cancelamento e reemissão do lote (ver [Cancelamento](./06-cancelamento.md)).

As demais pré-condições, travas de resposta e códigos de erro são os do passo 1.

---

## 5. Retentar a averbação do refinanciamento

Necessário **apenas** se a averbação do consolidador estiver parada em `pending_requester_action`. Nos estados `created` e `pending_reservation` a averbação segue sozinha com as condições novas.

ENDPOINT /debt/ CREDIT_OPERATION_KEY /reservation/retry
MÉTODO PATCH

Corpo `{}` · Resposta **204**. Comportamento e erros idênticos ao passo 2.

---

## 6. Refinanciamento averbado

Webhook `credit_operation.collateral` com `reservation_status: reserved` e `collateral_constituted: true` no consolidador fecha o ciclo: com a garantia constituída, a operação segue para o desembolso normal (`waiting_disbursement` → `disbursed`), conforme [Mapa de Status](./08-mapa-de-status.md).

A partir daí a operação **não é mais recalculável** — `recalculate` passa a responder `COP000556` (garantia já constituída).

---

## Erros possíveis no recálculo

| HTTP | Código | Quando |
|---|---|---|
| 400 | `QIT000001` | Corpo fora do schema — vazio, campo desconhecido, tipo errado |
| 403 | `QIT000403` | Requisitante da chamada não identificado |
| 403 | `QIT000005` | Requisitante não é dono da operação |
| 404 | `COP000027` | `credit_operation_key` não encontrada |
| 400 | `COP000553` | Tipo de garantia não recalculável |
| 400 | `COP000554` | Operação sem tipo de reserva na garantia |
| 400 | `COP000568` | Tipo de reserva sem recálculo disponível (ex.: `new_credit`, margem livre) |
| 400 | `COP000555` | Status ≠ `issued` — a operação ainda não foi assinada e emitida |
| 400 | `COP000556` | Garantia já constituída — a averbação passou, não há o que recalcular |
| 400 | `COP000557` | Condição não aceita — só `installment_amount` |
| 400 | `COP000558` | `installment_amount` ausente |
| 400 | `COP000559` | Nenhuma opção de desembolso em ou após hoje |
| 400 | `COP000560` | O resultado do cálculo violou uma trava da operação — nada é gravado |
| 400 | `COP000561` | Existe parcela com valor pago |
| 400 | `COP000562` | Operação com entrada emitida |
| 400 | `COP000564` | Condição com mais de 2 casas decimais |
| 400 | `COP000566` | Sem contrato portado/refinanciado com saldo devedor |
| 400 | `COP000567` | Operação sem taxa pré-fixada de referência |
| 400 | `COP000339` | Parcela insuficiente para o valor da operação — resultaria em troco negativo |
| 400 | `MPR000036` | Valor líquido abaixo de 85% do valor da emissão original |
| 404 | `MPR000017` | Não há averbação para essa operação |
| 409 | `MPR000009` | Averbação em status que não permite recálculo — a descrição traz o status atual |
| 409 | `MPR000037` | Consolidador com portabilidade do lote fora de `reserved` |

---

## Simulação em Sandbox

Os cenários de recusa são selecionados pelos **dois últimos dígitos do CPF** do tomador (são os dígitos verificadores — escolha uma base de 9 dígitos cujos verificadores resultem no sufixo desejado):

| Sufixo do CPF | Cenário | Onde para |
|---|---|---|
| `40` | Inclusão recusada com código 359 (margem consignável excedida) | `pending_requester_action` com `cancel_reason: consignable_margin_exceeded` |
| `41` | Averbação indeferida na confirmação (`Indeferida`) | `pending_requester_action` com `cancel_reason: rejected` |

Roteiro de teste:

1. Emita e assine o lote com um CPF de cenário (ver [Portabilidade + Refinanciamento](./04-portabilidade-refin.md) e [Formalização](./05-formalizacao.md)).
2. Aguarde o webhook `credit_operation.collateral` com `reservation_status: pending_requester_action`.
3. `PATCH /v2/credit_operation/{portability}/recalculate` com a parcela nova → `200`.
4. `PATCH /debt/{portability}/reservation/retry` → `204`.

:::caution O cenário de recusa não "cura" em sandbox
O CPF de cenário recusa **toda** tentativa de inclusão ou averbação. Para exercitar o caminho completo até `reserved`, use no reenvio um tomador sem sufixo de cenário. Ver [Mocks (Sandbox)](./09-mocks-sandbox.md) para os demais dados de teste.
:::

---

## Resumo do ciclo

| Passo | Chamada | Sucesso | Próximo gatilho |
|---|---|---|---|
| 1 | `PATCH /v2/credit_operation/{portability}/recalculate` | 200 com parcelas reescritas | — |
| 2 | `PATCH /debt/{portability}/reservation/retry` | 204 | Webhook `credit_operation.collateral` |
| 3 | — | `reserved` → passo 4 | Recusa → volta ao passo 1 |
| 4 | `PATCH /v2/credit_operation/{refinancing}/recalculate` | 200 (troco ≠ 0) | — |
| 5 | `PATCH /debt/{refinancing}/reservation/retry` | 204 (só se parado) | Webhook `credit_operation.collateral` |
| 6 | — | `reserved` + `collateral_constituted: true` | Desembolso |

---

## Glossário

| Termo | Significado |
|---|---|
| **`installment_amount`** | Novo valor total da parcela enviado ao recálculo — único campo aceito |
| **`pending_requester_action`** | Averbação recusada por motivo que exige condições novas do parceiro. Único estado em que o recálculo da portabilidade é aceito, e único em que o retry funciona |
| **`pending_reservation`** | Averbação aguardando envio ao Exército — onde o `reservation/retry` a coloca |
| **`pending_confirmation`** | Inclusão aceita, aguardando a confirmação da averbação |
| **`pending_valid_token`** | Averbação parada por token do militar inválido — resolve-se pela atualização do token, não por recálculo |
| **`reserved`** | Margem averbada, garantia constituída — a operação deixa de ser recalculável |
| **valor líquido** | `disbursed_issue_amount` — travado no saldo devedor portado na portabilidade; acompanha a parcela no consolidador |
| **troco** | `final_disbursement_amount` — só existe no `refinancing` consolidador; na portabilidade é sempre `0` |

---

# Webhooks

URL: /documentation/manual_exercito/webhooks

Eventos assíncronos emitidos pela QI Tech durante o ciclo de vida da operação consignada militar. Todos seguem o protocolo unificado de [Webhooks QI](/documentation/webhooks/notificacoes_baas_e_laas) — 5 segundos pra resposta HTTP 200 com `encoded_body` assinado, 3 retries de 5 minutos em caso de falha.

:::danger Atenção!
Os webhooks da QI Tech **não devem ser mapeados de forma restrita**. Campos adicionais podem ser incluídos aos payloads a qualquer momento. Use desserialização permissiva.
:::

## Webhooks específicos do produto militar

| Webhook | Quando dispara | Origem |
|---|---|---|
| `military_payroll.balance.status_change` | Resultado da consulta de margem (`succeeded` ou `failed`) | military-payroll-api |
| `military_payroll.due_balance.status_change` | Saldo devedor (usado em refin/port) | military-payroll-api |
| `military_payroll.portability_contracts_report.status_change` | Relatório de contratos pra portabilidade | military-payroll-api |
| `credit_operation.collateral` | Averbação ou desaverbação no Zetra | credit-operation-api |

## Webhooks comuns LaaS

| Webhook | Status | Quando dispara |
|---|---|---|
| `debt` | `waiting_signature` | Operação criada, aguardando assinatura |
| `debt` | `signature_finished` | Assinatura concluída |
| `debt` | `disbursed` | Desembolso PIX/TED enviado |
| `debt` | `canceled` | Operação cancelada (ver `cancel_reason_enumerator`) |
| `debt` | `canceled_permanently` | Cancelamento definitivo |
| `debt` | `settled` | Operação liquidada (parcelas pagas) |
| `reversal` | `pending_fund` | Borrower pagou PIX QR de cancelamento — reversal iniciado |
| `credit_transfer.received_portability` | — | Portabilidade externa recebida (banco origem aceitou) |
| `credit_transfer_status_change` | — | Atualização do credit-transfer |
| `installment.status_change` | `paid` / `overdue` / etc | Mudança de status de parcela individual |
| `laas.devolution.refund_receipt` | `refunded` | Devolução de overpayment via PIX |

## Estrutura padrão do payload

Todos os webhooks LaaS seguem essa forma básica:

```json
{
  "key": "<UUID da operação>",
  "data": ,
  "status": "<status>",
  "webhook_type": "<tipo>",
  "event_datetime": "2026-06-01 14:30:00"
}
```

## Exemplos

### `military_payroll.balance.status_change` (sucesso)

```json
{
  "webhook_type": "military_payroll.balance.status_change",
  "key": "81da8afb-e1b2-4215-8093-c4b5feab8a9f",
  "status": "succeeded",
  "data": {
    "balance": 3500.00,
    "allowed_installment_numbers": [24, 36, 48, 60],
    "military_unit": "AMAN",
    "military_branch": "Sistema de Retribuição do Exterior",
    "category": "ATIVO",
    "name": "JOÃO DA SILVA",
    "document_number": "45507529710",
    "registration_code": "146254221",
    "birth_date": "1985-03-12",
    "grant_date": "2010-05-15"
  },
  "event_datetime": "2026-06-01 14:30:00"
}
```

### `credit_operation.collateral` (averbação reservada)

```json
{
  "webhook_type": "credit_operation.collateral",
  "key": "27a099df-4688-43cb-87fa-515b1cf343a5",
  "status": "success",
  "data": {
    "collateral_constituted": true,
    "enumerator": "successfully_reserved",
    "reservation_status": "reserved"
  },
  "event_datetime": "2026-06-01 15:00:00"
}
```

### `debt` (cancelado)

```json
{
  "webhook_type": "debt",
  "key": "27a099df-4688-43cb-87fa-515b1cf343a5",
  "status": "canceled",
  "data": {
    "cancel_reason": "Operação cancelada manualmente",
    "cancel_reason_enumerator": "manual"
  },
  "event_datetime": "2026-06-01 16:00:00"
}
```

### `reversal` (cancelamento pós-desembolso)

```json
{
  "webhook_type": "reversal",
  "credit_operation_key": "2893b8bd-8f4e-4e45-9325-fc7003beb869",
  "contract_number": "0000049333/TW",
  "reversal": {
    "status": "pending_fund",
    "amount": 2026.93,
    "amount_to_send": 2026.93,
    "is_total": true,
    "is_operation_canceled": true,
    "reversal_key": "eb0bbd1d-111d-4a61-bb65-c1f66a005ea2",
    "date": "2026-09-06"
  }
}
```

## Cancel reasons (`cancel_reason_enumerator`)

| Enumerador | Significado |
|---|---|
| `manual` | Cancelado via API ou portal |
| `waiting_signature` | Não assinou no prazo |
| `not_collateral_constituted` | Averbação falhou (consent_refused, consent_expired, etc.) |
| `is_portability` | Portabilidade falhou |
| `pix_max_retry` | Muitas falhas no desembolso PIX |
| `lack_of_resource` | Sem recurso pra desembolsar |
| `kyc_not_accepted` | KYC reprovado |
| `agencia_conta_invalida` | Erro em dados bancários do desembolso |
| `invalid_account` | Conta inválida |
| `rejected_payment` | Pagamento recusado pelo banco destino |

→ Lista completa em [Mapa de Status](./08-mapa-de-status.md)

## Reenvio Manual

Webhooks podem ser consultados e reenviados via portal seguindo [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).

---

# Manual Saque Aniversário - FGTS

URL: /documentation/manual_FGTS/

:::info Veja também
- [Consulta de Autorização FGTS](/documentation/manual_consulta_de_autorizacao_FGTS/manual_consulta_de_autorizacao_FGTS)
:::

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita.
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

Este manual descreve o passo a passo envolvido na consulta, simulação, emissão,  desembolso e demais ações de uma operação de Adiantamento do Saque Aniversário FGTS (Crédito pessoal com cessão do Saque Aniversário FGTS).

## Pré-requisitos
1 - Tomador deve ser optante pelo saque aniversario FGTS;

2 - Tomador deve autorizar a QI a consultar seu saldo de FGTS no aplicativo da CEF (Caixa Econômica Federal);

 

## 1 - Consultar saldo disponível
**1.1.** Realização da consulta de saldo:

        **Request**

ENDPOINT /baas/v2/fgts/available_balance
MÉTODO POST

Request Body

```json
{
	"document_number": "06568225037"
}

```

| Campo | Tipo | Obrigatório | Descrição |
|-|-|-|-|
| `document_number` | string(11) | Sim | CPF do tomador |

Testar no Playground

Em caso de sucesso na consulta do saldo disponível, é retornado principalmente o número de contratos ativos e se o beneficiário tem saldo disponível em seu FGTS.

        **Response**

ENDPOINT /baas/v2/fgts/available_balance
MÉTODO POST

Response Body

```json
{
	"available_balance_key": "7521981f-0b06-43d2-9a75-d3a1f215fbbf",
	"document_number": "06568225037",
	"status": "pending",
	"status_events": [{
		"event_datetime": "2022-12-26T13:36:16",
		"status": "pending"
	}]
}

```

| Campo | Tipo | Descrição |
|-|-|-|
| `available_balance_key` | string (UUID) | Chave única da consulta de saldo |
| `document_number` | string(11) | CPF do tomador |
| `status` | string | Status da consulta (`pending`, `success`, `failed`) |
| `status_events[]` | array | Histórico de eventos de status |
| `status_events[].event_datetime` | string (datetime) | Data/hora do evento |
| `status_events[].status` | string | Status do evento |

 

**1.1.1.** No caso de sucesso na consulta de saldo na CEF, o parceiro receberá o seguinte webhook:

        **Webhooks**

WEBHOOK_TYPE available_balance
STATUS Success

Body

```json
{
	"webhook_type": "available_balance",
	"event_datetime": "2022-12-26T13:36:16",
	"key": "7521981f-0b06-43d2-9a75-d3a1f215fbbf",
	"status": "success",
	"data": {
		"reference_date": "2022-07-28",
		"periods": [{
				"due_date": "2022-08-01",
				"amount": 500.1
			},
			{
				"due_date": "2023-08-01",
				"amount": 400.2
			}
		]
	}
}
```

| Campo | Tipo | Descrição |
|-|-|-|
| `webhook_type` | string | Tipo do webhook (`available_balance`) |
| `event_datetime` | string (datetime) | Data/hora do evento |
| `key` | string (UUID) | Chave da consulta de saldo |
| `status` | string | Status (`success`) |
| `data.reference_date` | string (date) | Data de referência do saldo |
| `data.periods[]` | array | Períodos de saque disponíveis |
| `data.periods[].due_date` | string (date) | Data de vencimento do saque |
| `data.periods[].amount` | number | Valor disponível para saque no período |

**1.1.2.** No caso de falha na consulta de saldo na CEF, o parceiro receberá o seguinte webhook:

WEBHOOK_TYPE available_balance
STATUS Failed

Body

```json
{
	"webhook_type": "available_balance",
	"event_datetime": "2022-12-26T13:36:16",
	"key": "7521981f-0b06-43d2-9a75-d3a1f215fbbf",
	"status": "failed",
	"data": {
		"error_description": "Client does not have membership for anniversary withdraw on current date",
		"error_enumerator": "inexistent_anniversary_membership"
	}
}
```

| Campo | Tipo | Descrição |
|-|-|-|
| `webhook_type` | string | Tipo do webhook (`available_balance`) |
| `event_datetime` | string (datetime) | Data/hora do evento |
| `key` | string (UUID) | Chave da consulta de saldo |
| `status` | string | Status (`failed`) |
| `data.error_description` | string | Descrição do erro |
| `data.error_enumerator` | string | Enumerador do erro |

**1.1.3.** No caso de falha na consulta de saldo na CEF por data da operação não permitida, o parceiro receberá um webhook com uma informação adicional no campo "data":

WEBHOOK_TYPE available_balance
STATUS Failed

Body

```json
{
	"webhook_type": "available_balance",
	"event_datetime": "2022-12-26T13:36:16",
	"key": "7521981f-0b06-43d2-9a75-d3a1f215fbbf",
	"status": "failed",
	"data": {
		"error_description": "Not permitted action on current date",
		"error_enumerator": "on_locked_date_range",
		"error_data": {
			"operation_not_allowed_until_date": "2023-01-03"
		}
	}
}
```

| Campo | Tipo | Descrição |
|-|-|-|
| `webhook_type` | string | Tipo do webhook (`available_balance`) |
| `event_datetime` | string (datetime) | Data/hora do evento |
| `key` | string (UUID) | Chave da consulta de saldo |
| `status` | string | Status (`failed`) |
| `data.error_description` | string | Descrição do erro |
| `data.error_enumerator` | string | Enumerador do erro |
| `data.error_data.operation_not_allowed_until_date` | string (date) | Data a partir da qual a operação será permitida |

Os possíveis enumeradores de falha na consulta de saldo são listados na seção **2**.

**1.2.** Consultar resultado de uma consulta de saldo específica:

É possível consultar o resultado de uma consulta de saldo já realizada utilizando a chave retornada na criação (`available_balance_key`).

        **Request**

ENDPOINT /baas/v2/fgts/available_balance/{available_balance_key}
MÉTODO GET

        **Response**

STATUS 200

Response Body

```json
{
	"available_balance_key": "7521981f-0b06-43d2-9a75-d3a1f215fbbf",
	"document_number": "06568225037",
	"status": "success",
	"reference_date": "2022-07-28",
	"number_of_active_contracts": 0,
	"has_unavailable_balance": false,
	"periods": [
		{
			"due_date": "2022-08-01",
			"amount": 500.1
		},
		{
			"due_date": "2023-08-01",
			"amount": 400.2
		}
	],
	"has_succeeded": true,
	"error_message": null
}
```

| Campo | Tipo | Descrição |
|-|-|-|
| `available_balance_key` | string (UUID) | Chave única da consulta de saldo |
| `document_number` | string(11) | CPF do tomador |
| `status` | string | Status da consulta (`success`, `pending`, `failed`) |
| `reference_date` | string (date) | Data de referência do saldo |
| `number_of_active_contracts` | integer | Número de contratos ativos de FGTS |
| `has_unavailable_balance` | boolean | Indica se há saldo indisponível |
| `periods[]` | array | Períodos de saque disponíveis |
| `periods[].due_date` | string (date) | Data de vencimento do saque |
| `periods[].amount` | number | Valor disponível para saque |
| `has_succeeded` | boolean | Indica se a consulta foi bem-sucedida |
| `error_message` | string/null | Mensagem de erro, se houver |

Testar no Playground

**1.3.** Cancelar uma consulta de saldo pendente:

Caso deseje cancelar uma consulta de saldo que ainda esteja com status `pending`, utilize o endpoint abaixo.

        **Request**

ENDPOINT /baas/v2/fgts/available_balance/{available_balance_key}
MÉTODO DELETE

        **Response**

STATUS 204 No Content

O endpoint retorna status 204 sem corpo na resposta.

Testar no Playground

## 2 - Simulando cenários de sucesso e insucesso na consulta de saldo em Sandbox:

**2.1.** Para CPFs iniciados com os números 0, 1, 2, 3, 4, 5, 6 e 7, retornarão uma resposta assíncrona de sucesso através do Webhook (**1.1.1.**).

**2.2.** Para CPF’s iniciandos com o número 8, a consulta de saldo retornará uma resposta assíncrona de sucesso (**1.1.1.**) com períodos zerados que podem ser usados para teste.

**2.3.** Simulando casos de falha na consulta de saldo disponível:

Todas as consultas realizadas para CPFs incitados com 9, retornarão uma resposta assíncrona de erro através do webhook (**1.1.2. ou 1.1.3.**) com um dos erros listados abaixo.

Temos um mock de casos de insucesso para serem testados, eles usam uma lógica aplicada aos primeiros números do documento do tomador em sandbox.

| Início do CPF  |  error_enumerator                                                 | 	error_description     |    
|----------------|-------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------| 
| 90             | ongoing_operation	                                             | There's an ongoing operation                                                                                                     |
| 91	         | unauthorized_institution	                                         | Institution isn't authorized by the client                                                                                       |
| 92, 920        | inexistent_anniversary_membership                            	 | 	Client does not have membership for anniversary withdraw on current date                                                        |
| 93	         | on_locked_date_range                                              | 	Not permitted action on current date                                                                                            |
| 94             |anniversary_membership_egress                                      | Client moving away from anniversary membership. It need to be canceled before requesting a reserve                               |
| 95, 950	     | processing_pending_changes	                                     | Changes on profile info happened on client's FGTS account                                                                        |
| 96, 97, 98, 99 | caixa_error	                                                     | Request wasn't able to process due to an error on CEF                                                                            |
 

## 3 - Acompanhamento e ações em relação a consulta de saldo

A resposta da consulta deve desencadear uma ação por parte do correspondente, de forma a orientar o cliente assertivamente e evitar o acúmulo de requsições perdidas em nossas filas.

| Enumerador                        | error_description | Descrição   |  Ação da QI  | Ação do Cliente |
|-----------------------------------|--------------------- |-------------|-----------| -----------|
|ongoing_operation                  | There's an ongoing operation   | Existe uma operação em andamento na Caixa em relação à esse CPF que implica na alteração do saldo do cliente. Isso impede que valores exatos de parcelas sejam disponibilizados| Envio webhook com o correspondente enumerador e descrição   | Recomenda-se aguardar e fazer uma nova tentativa |
|unauthorized_institution			| Institution isn't authorized by the client  | Instituição não autorizada pelo cliente | Envio webhook com o correspondente enumerador e descrição |  Orientar o cliente a realizar a autorização da "**QI SOCIEDADE DE CREDITO S.A**" para operar o Adiantamento do Saque Aniversário FGTS |
|inexistent_anniversary_membership	| Client does not have membership for anniversary withdraw on current date           |  Trabalhador não possui adesão ao saque aniversário na data vigente | Envio webhook com o correspondente enumerador e descrição |  Necessário orientar o cliente a aderir a modalidade de Saque Aniversário no aplicativo do FGTS|
|on_locked_date_range				| Not permitted action on current date     | A Operação não é permitida na data atual |  Envio webhook com o correspondente enumerador e descrição| A operação é permitida no segundo dia útil do próximo mês. Fazer a devida comunicação com o cliente, visto que ele não conseguirá fazer a operação no momento em nenhuma outra instituição financeira |
|anniversary_membership_egress		|  Client moving away from anniversary membership. It need to be canceled before requesting a reserve | Trabalhador com solicitação de retorno para saque rescisão, que deve ser cancelada pelo mesmo para possibilitar a solicitação de garantia. |  Envio webhook com o correspondente enumerador e descrição | Orientar cliente que ele solicitou o egresso da modalidade de Saque Aniversário, isso  impede que ele faça o adiantamento de seus saques
|processing_pending_changes			| Changes on profile info happened on client's FGTS account | Operação não permitida por pendência no processo de pagamento de Saque Aniversário| Envio webhook com o correspondente enumerador e descrição |  Orientar cliente a aguardar a regularização |
|caixa_error						|  Request wasn't able to process due to an error on CEF | A requisição não foi completada devido a um erro retornado pela Caixa | Envio webhook com o correspondente enumerador e descrição | Recomenda-se aguardar e fazer uma nova tentativa |

:::info
No ambiente produtivo, a consulta de saldo possui uma rotina de retentativas que depende do erro retornado pela CEF no momento da consulta. 
Alguns erros são passíveis de retentativa, já os erros listados acima, são erros definitivos, que não retornam a consulta assíncrona para a fila de retentativa.
:::

## 4 - Simulação do valor máximo
Em posse dos valores disponíveis para saque em cada período (ano), retornados na consulta de saldo (**1.**), é possível realizar a simulação de uma operação de adiantamento do Saque Aniversário FGTS.

A forma de simulação demonstrada nessa seção, mostra qual é o valor máximo que pode ser contratado pelo tomador adiantando 100% dos valores das parcelas disponíveis.

        **Request**

ENDPOINT /baas/fgts_simulation
MÉTODO POST

Request Body

```json
{
        "borrower": {
            "person_type": "natural",
			"individual_document_number": "46338864879"
        },
        "financial": {
            "desired_installments": [{
                    "total_amount": 5448.42,
                    "due_date": "2023-10-01"
                },
                {
                    "total_amount": 2811.86,
                    "due_date": "2024-10-01"
                }
            ],
            "interest_type": "pre_price_days",
            "disbursement_date": "2023-06-30",
            "fine_configuration": {
                "monthly_rate": 0,
                "interest_base": "calendar_days",
                "contract_fine_rate": 0
            },
            "annual_interest_rate": 0.274223,
            "credit_operation_type": "ccb",
            "interest_grace_period": 0,
            "number_of_installments": 2,
            "principal_grace_period": 0
        }
}
```

| Campo | Tipo | Obrigatório | Descrição |
|-|-|-|-|
| `borrower` | object | Sim | Dados do tomador |
| `borrower.person_type` | string | Sim | Tipo de pessoa (`natural`) |
| `borrower.individual_document_number` | string(11) | Sim | CPF do tomador |
| `financial` | object | Sim | Dados financeiros da operação |
| `financial.desired_installments[]` | array | Sim | Parcelas desejadas (valores da consulta de saldo) |
| `financial.desired_installments[].total_amount` | number | Sim | Valor total da parcela |
| `financial.desired_installments[].due_date` | string (date) | Sim | Data de vencimento da parcela |
| `financial.interest_type` | string | Sim | Tipo de juros (`pre_price_days`) |
| `financial.disbursement_date` | string (date) | Sim | Data de desembolso |
| `financial.fine_configuration` | object | Sim | Configuração de multa |
| `financial.annual_interest_rate` | number | Sim | Taxa de juros anual |
| `financial.credit_operation_type` | string | Sim | Tipo de operação de crédito (`ccb`) |
| `financial.interest_grace_period` | integer | Sim | Período de carência de juros |
| `financial.number_of_installments` | integer | Sim | Número de parcelas |
| `financial.principal_grace_period` | integer | Sim | Período de carência do principal |

        **Response**

MÉTODO POST
ENDPOINT /baas/fgts_simulation

Response Body

```json
{
    "data": {
        "annual_cet": 0.3339086001603759,
        "assignment_amount": 7195.39,
        "cet": 0.0243,
        "contract_fee_amount": 43.17,
        "contract_fees": [
            {
                "amount": 0.6,
                "amount_type": "percentage",
                "fee_amount": 43.17,
                "fee_type": "tac"
            }
        ],
        "credit_operation_type": "ccb",
        "disbursed_issue_amount": 7020.82,
        "disbursement_date": "2023-06-30",
        "disbursement_options": [
            {
                "annual_cet": 0.3339086001603759,
                "assignment_amount": 7195.39,
                "cet": 0.0243,
                "contract_fee_amount": 43.17,
                "contract_fees": [
                    {
                        "amount": 0.6,
                        "amount_type": "percentage",
                        "fee_amount": 43.17,
                        "fee_type": "tac"
                    }
                ],
                "disbursed_issue_amount": 7020.82,
                "disbursement_date": "2023-06-30",
                "external_contract_fee_amount": 0.0,
                "external_contract_fees": [
                    {
                        "amount": 0.0,
                        "amount_released": 0,
                        "amount_type": "absolute",
                        "cofins_amount": 0,
                        "csll_amount": 0,
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "tac",
                        "irrf_amount": 0,
                        "net_fee_amount": 0.0,
                        "pis_amount": 0,
                        "tax_amount": 0.0
                    },
                    {
                        "amount": 0.0,
                        "amount_released": 0,
                        "amount_type": "absolute",
                        "cofins_amount": 0,
                        "csll_amount": 0,
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "spread",
                        "irrf_amount": 0,
                        "net_fee_amount": 0.0,
                        "pis_amount": 0,
                        "tax_amount": 0.0
                    }
                ],
                "first_due_date": "2023-10-01",
                "installments": [
                    {
                        "business_due_date": "2023-10-02",
                        "calendar_days": 93,
                        "due_date": "2023-10-01",
                        "due_principal": 7195.39,
                        "has_interest": true,
                        "installment_number": 1,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 458.290020805,
                        "principal_amortization_amount": 4990.129979195,
                        "tax_amount": 38.05473122134107,
                        "total_amount": 5448.42,
                        "workdays": 64.0
                    },
                    {
                        "business_due_date": "2024-10-01",
                        "calendar_days": 366,
                        "due_date": "2024-10-01",
                        "due_principal": 2205.260020805,
                        "has_interest": true,
                        "installment_number": 2,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 606.5994412243,
                        "principal_amortization_amount": 2205.2605587757,
                        "tax_amount": 66.0034485241567,
                        "total_amount": 2811.86,
                        "workdays": 252.0
                    }
                ],
                "iof_amount": 131.4,
                "issue_amount": 7195.39,
                "net_external_contract_fee_amount": 0.0,
                "prefixed_interest_rate": {
                    "annual_rate": 0.274223,
                    "daily_rate": 0.00066416,
                    "interest_base": "calendar_days_365",
                    "monthly_rate": 0.02040001
                },
                "total_pre_fixed_amount": 1064.8894620293
            }
        ],
        "external_contract_fee_amount": 0.0,
        "external_contract_fees": [
            {
                "amount": 0.0,
                "amount_released": 0,
                "amount_type": "absolute",
                "cofins_amount": 0,
                "csll_amount": 0,
                "description": null,
                "fee_amount": 0.0,
                "fee_type": "tac",
                "irrf_amount": 0,
                "net_fee_amount": 0.0,
                "pis_amount": 0,
                "tax_amount": 0.0
            },
            {
                "amount": 0.0,
                "amount_released": 0,
                "amount_type": "absolute",
                "cofins_amount": 0,
                "csll_amount": 0,
                "description": null,
                "fee_amount": 0.0,
                "fee_type": "spread",
                "irrf_amount": 0,
                "net_fee_amount": 0.0,
                "pis_amount": 0,
                "tax_amount": 0.0
            }
        ],
        "final_disbursement_amount": 7020.82,
        "installments": [
            {
                "business_due_date": "2023-10-02",
                "calendar_days": 93,
                "due_date": "2023-10-01",
                "due_principal": 7195.39,
                "has_interest": true,
                "installment_number": 1,
                "post_fixed_amount": null,
                "pre_fixed_amount": 458.290020805,
                "principal_amortization_amount": 4990.129979195,
                "tax_amount": 38.05473122134107,
                "total_amount": 5448.42,
                "workdays": 64.0
            },
            {
                "business_due_date": "2024-10-01",
                "calendar_days": 366,
                "due_date": "2024-10-01",
                "due_principal": 2205.260020805,
                "has_interest": true,
                "installment_number": 2,
                "post_fixed_amount": null,
                "pre_fixed_amount": 606.5994412243,
                "principal_amortization_amount": 2205.2605587757,
                "tax_amount": 66.0034485241567,
                "total_amount": 2811.86,
                "workdays": 252.0
            }
        ],
        "interest_grace_period": 0,
        "interest_payment_month_period": 1,
        "interest_type": "pre_price_days",
        "iof_amount": 131.4,
        "issue_amount": 7195.39,
        "issue_date": "2023-06-30",
        "net_external_contract_fee_amount": 0.0,
        "number_of_installments": 2,
        "operation_type": "structured_operation",
        "post_fixed_interest_base": "workdays",
        "post_fixed_interest_rate": null,
        "prefixed_interest_rate": {
            "annual_rate": 0.274223,
            "daily_rate": 0.00066416,
            "interest_base": "calendar_days_365",
            "monthly_rate": 0.02040001
        },
        "principal_amortization_month_period": 1,
        "principal_grace_period": 0,
        "requester_key": "a5c043d3-dec3-4f8d-aa14-01dc9ba85783",
        "total_pre_fixed_amount": 1064.8894620293
    },
    "event_datetime": "2023-06-28 14:07:47",
    "key": "9e532b37-e301-4646-80b7-afd8a3d60f51",
    "status": "finished",
    "type": "debt"
}

```

Testar no Playground

## 5 - Simulação do valor desejado
A forma de simulação demonstrada nessa seção, mostra qual é o valor das parcelas do Saque Aniversário o tomador precisa adiantar para desembolsar um determinado valor.

        **Request**

ENDPOINT /baas/fgts_simulation_guess
MÉTODO POST

Request Body

```json
{
	"borrower": {
		"person_type": "natural",
		"individual_document_number": "46338864879"
	},
	"target_disbursed_amount": 4000,
	"financial": {
		"desired_installments": [{
			"total_amount": 5448.42,
			"due_date": "2023-10-01"
		}],
		"interest_type": "pre_price_days",
		"disbursement_date": "2023-06-30",
		"fine_configuration": {
			"monthly_rate": 0,
			"interest_base": "calendar_days",
			"contract_fine_rate": 0
		},
		"annual_interest_rate": 0.27422288066567435,
		"credit_operation_type": "ccb",
		"interest_grace_period": 0,
		"number_of_installments": 1,
		“principal_grace_period”: 0
	}
}

```

| Campo | Tipo | Obrigatório | Descrição |
|-|-|-|-|
| `borrower` | object | Sim | Dados do tomador |
| `borrower.person_type` | string | Sim | Tipo de pessoa (`natural`) |
| `borrower.individual_document_number` | string(11) | Sim | CPF do tomador |
| `target_disbursed_amount` | number | Sim | Valor desejado de desembolso |
| `financial` | object | Sim | Dados financeiros da operação |
| `financial.desired_installments[]` | array | Sim | Parcelas (valores máximos da consulta de saldo) |
| `financial.desired_installments[].total_amount` | number | Sim | Valor total da parcela |
| `financial.desired_installments[].due_date` | string (date) | Sim | Data de vencimento da parcela |
| `financial.interest_type` | string | Sim | Tipo de juros (`pre_price_days`) |
| `financial.disbursement_date` | string (date) | Sim | Data de desembolso |
| `financial.fine_configuration` | object | Sim | Configuração de multa |
| `financial.annual_interest_rate` | number | Sim | Taxa de juros anual |
| `financial.credit_operation_type` | string | Sim | Tipo de operação de crédito (`ccb`) |
| `financial.interest_grace_period` | integer | Sim | Período de carência de juros |
| `financial.number_of_installments` | integer | Sim | Número de parcelas |
| `financial.principal_grace_period` | integer | Sim | Período de carência do principal |

:::info
Os valores de parcela informados na lista de parcelas no objeto “***financial.desired_installments***” devem ser os valores retornados na consulta. Esses valores serão utilizados como valores máximos das parcelas na simulação.
:::

        **Response**

MÉTODO POST
ENDPOINT /baas/fgts_simulation_guess

Response Body

```json
{
    "data": {
        "annual_cet": 0.3655007620895273,
        "assignment_amount": 4070.94,
        "cet": 0.0263,
        "contract_fee_amount": 24.43,
        "contract_fees": [
            {
                "amount": 0.6,
                "amount_type": "percentage",
                "fee_amount": 24.43,
                "fee_type": "tac"
            }
        ],
        "credit_operation_type": "ccb",
        "disbursed_issue_amount": 4000.0,
        "disbursement_date": "2023-06-30",
        "disbursement_options": [
            {
                "annual_cet": 0.3655007620895273,
                "assignment_amount": 4070.94,
                "cet": 0.0263,
                "contract_fee_amount": 24.43,
                "contract_fees": [
                    {
                        "amount": 0.6,
                        "amount_type": "percentage",
                        "fee_amount": 24.43,
                        "fee_type": "tac"
                    }
                ],
                "disbursed_issue_amount": 4000.0,
                "disbursement_date": "2023-06-30",
                "external_contract_fee_amount": 0.0,
                "external_contract_fees": [
                    {
                        "amount": 0.0,
                        "amount_released": 0,
                        "amount_type": "absolute",
                        "cofins_amount": 0,
                        "csll_amount": 0,
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "tac",
                        "irrf_amount": 0,
                        "net_fee_amount": 0.0,
                        "pis_amount": 0,
                        "tax_amount": 0.0
                    },
                    {
                        "amount": 0.0,
                        "amount_released": 0,
                        "amount_type": "absolute",
                        "cofins_amount": 0,
                        "csll_amount": 0,
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "spread",
                        "irrf_amount": 0,
                        "net_fee_amount": 0.0,
                        "pis_amount": 0,
                        "tax_amount": 0.0
                    }
                ],
                "first_due_date": "2023-10-01",
                "installments": [
                    {
                        "business_due_date": "2023-10-02",
                        "calendar_days": 93,
                        "due_date": "2023-10-01",
                        "due_principal": 4070.94,
                        "has_interest": true,
                        "installment_number": 1,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 259.2870755335,
                        "principal_amortization_amount": 4070.9429244665,
                        "tax_amount": 31.045010741981528,
                        "total_amount": 4330.23,
                        "workdays": 64.0
                    }
                ],
                "iof_amount": 46.51,
                "issue_amount": 4070.94,
                "net_external_contract_fee_amount": 0.0,
                "prefixed_interest_rate": {
                    "annual_rate": 0.27422288,
                    "daily_rate": 0.00066416,
                    "interest_base": "calendar_days_365",
                    "monthly_rate": 0.0204
                },
                "total_pre_fixed_amount": 259.2870755335
            }
        ],
        "external_contract_fee_amount": 0.0,
        "external_contract_fees": [
            {
                "amount": 0.0,
                "amount_released": 0,
                "amount_type": "absolute",
                "cofins_amount": 0,
                "csll_amount": 0,
                "description": null,
                "fee_amount": 0.0,
                "fee_type": "tac",
                "irrf_amount": 0,
                "net_fee_amount": 0.0,
                "pis_amount": 0,
                "tax_amount": 0.0
            },
            {
                "amount": 0.0,
                "amount_released": 0,
                "amount_type": "absolute",
                "cofins_amount": 0,
                "csll_amount": 0,
                "description": null,
                "fee_amount": 0.0,
                "fee_type": "spread",
                "irrf_amount": 0,
                "net_fee_amount": 0.0,
                "pis_amount": 0,
                "tax_amount": 0.0
            }
        ],
        "final_disbursement_amount": 4000.0,
        "installments": [
            {
                "business_due_date": "2023-10-02",
                "calendar_days": 93,
                "due_date": "2023-10-01",
                "due_principal": 4070.94,
                "has_interest": true,
                "installment_number": 1,
                "post_fixed_amount": null,
                "pre_fixed_amount": 259.2870755335,
                "principal_amortization_amount": 4070.9429244665,
                "tax_amount": 31.045010741981528,
                "total_amount": 4330.23,
                "workdays": 64.0
            }
        ],
        "interest_grace_period": 0,
        "interest_payment_month_period": 1,
        "interest_type": "pre_price_days",
        "iof_amount": 46.51,
        "issue_amount": 4070.94,
        "issue_date": "2023-06-30",
        "net_external_contract_fee_amount": 0.0,
        "number_of_installments": 1,
        "operation_type": "structured_operation",
        "post_fixed_interest_base": "workdays",
        "post_fixed_interest_rate": null,
        "prefixed_interest_rate": {
            "annual_rate": 0.27422288,
            "daily_rate": 0.00066416,
            "interest_base": "calendar_days_365",
            "monthly_rate": 0.0204
        },
        "principal_amortization_month_period": 1,
        "principal_grace_period": 0,
        "requester_key": "a5c043d3-dec3-4f8d-aa14-01dc9ba85783",
        "total_pre_fixed_amount": 259.2870755335
    },
    "event_datetime": "2023-06-28 14:11:15",
    "key": "aa0d581b-4332-40e1-adad-0c7724dc880a",
    "status": "finished",
    "type": "debt"
}
```

Testar no Playground

## 6 - Criação da Operação
Para realizar a criação de uma operação do Saque Aniversário FGTS, é necessário informar 4 objetos na requisição:

- borrower: tomador da dívida (**[Objeto Borrower](#objeto-borrower)**)

- collaterals: informações das parcelas de pagamento (objeto Collateral FGTS)

- financial: dados do fluxo financeiro da operação (Objeto Financeiro FGTS). É o mesmo objeto informado na simulação.

- disbursement_bank_account: informações bancárias para o desembolso (Objeto Conta Bancária)

O PDF do contrato da operação do Saque Aniversário FGTS será gerado pela QI neste momento e será retornado na resposta da requisição.

:::caution Atenção 
Para os valores de parcelas informados na lista de parcelas do objeto “***financial.desired_installments***” utilizamos o campo "***total_amount***", para os valores de parcelas no objeto “***collaterals.collateral_data.periods***” utilizamos o campo "***amount***".
:::

        **Request**

ENDPOINT /baas/debt_fgts
MÉTODO POST

Request Body

```json
	{
    "borrower": {
        "person_type": "natural",
        "name": "PATRICIA APARECIDA DO NASCIMENTO PEREIRA DA SILVA",
        "mother_name": "HELENA DO NASCIMENTO PEREIRA DA SILVA",
        "birth_date": "1997-10-28",
        "profession": "Outros",
        "nationality": "brasileira",
        "marital_status": "married",
        "is_pep": false,
        "individual_document_number": "46338864879",
        "document_identification_number": "46338864879",
        "document_identification_type": "rg",
        "document_identification_date": "2023-12-29",
        "document_identification": "494598fd-c226-4332-a500-591ae3884673",
        "document_identification_back": "494598fd-c226-4332-a500-591ae3884673",
        "email": "naotem@gmail.com",
        "phone": {
            "country_code": "055",
            "area_code": "11",
            "number": "989073010"
        },
        "address": {
            "street": "Rua José Castrioto",
            "state": "SP",
            "city": "São José dos Campos",
            "neighborhood": "Parque Nova Esperança",
            "number": "147",
            "postal_code": "12226160",
            "complement": "CASA"
        }
    },
    "additional_data": null,
    "collaterals": [
        {
            "collateral_type": "fgts_balance",
            "collateral_data": {
                "periods": [
                    {
                        "due_date": "2024-05-02",
                        "amount": 1758.2
                    }
                ]
            },
            "percentage": 1
        }
    ],
    "financial": {
        "desired_installments": [
            {
                "due_date": "2024-05-02",
                "total_amount": 1758.2
            }
        ],
        "interest_type": "pre_price_days",
        "disbursement_start_date": "2024-01-17",
        "disbursement_end_date": "2024-01-22",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "contract_fine_rate": 0.01,
            "interest_base": "calendar_days"
        },
        "monthly_interest_rate": 0.018,
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "number_of_installments": 11,
        "principal_grace_period": 0,
        "issue_date": "2024-01-17"
    },
    "disbursement_bank_account": {
        "ispb_number": "18236120",
        "branch_number": "1",
        "account_number": "87823171",
        "account_digit": "0",
        "document_number": "46338864879",
        "name": "PATRICIA APARECIDA DO NASCIMENTO PEREIRA DA SILVA",
        "percentage_receivable": 1
    }
}
```

| Campo | Tipo | Obrigatório | Descrição |
|-|-|-|-|
| `borrower` | object | Sim | Dados completos do tomador |
| `borrower.person_type` | string | Sim | Tipo de pessoa (`natural`) |
| `borrower.name` | string | Sim | Nome completo |
| `borrower.mother_name` | string | Sim | Nome da mãe |
| `borrower.birth_date` | string (date) | Sim | Data de nascimento |
| `borrower.individual_document_number` | string(11) | Sim | CPF |
| `borrower.document_identification_number` | string | Sim | Número do documento de identificação |
| `borrower.document_identification_type` | string | Sim | Tipo do documento (`rg`, `cnh`, etc.) |
| `borrower.document_identification_date` | string (date) | Sim | Data de emissão do documento |
| `borrower.document_identification` | string (UUID) | Sim | Chave do documento (frente) |
| `borrower.document_identification_back` | string (UUID) | Não | Chave do documento (verso) |
| `borrower.email` | string | Sim | E-mail do tomador |
| `borrower.phone` | object | Sim | Telefone do tomador |
| `borrower.address` | object | Sim | Endereço do tomador |
| `collaterals[]` | array | Não | Dados das garantias FGTS |
| `collaterals[].collateral_type` | string | Sim | Tipo de garantia (`fgts_balance`) |
| `collaterals[].collateral_data.periods[]` | array | Sim | Períodos de saque |
| `collaterals[].percentage` | number | Sim | Percentual da garantia |
| `financial` | object | Sim | Dados financeiros (mesmo objeto da simulação) |
| `financial.desired_installments[]` | array | Sim | Parcelas desejadas |
| `financial.disbursement_start_date` | string (date) | Sim | Data inicial de desembolso |
| `financial.disbursement_end_date` | string (date) | Sim | Data final de desembolso |
| `financial.monthly_interest_rate` | number | Sim | Taxa de juros mensal |
| `financial.issue_date` | string (date) | Sim | Data de emissão |
| `disbursement_bank_account` | object | Sim | Conta bancária para desembolso |
| `disbursement_bank_account.ispb_number` | string | Sim | ISPB do banco |
| `disbursement_bank_account.branch_number` | string | Sim | Número da agência |
| `disbursement_bank_account.account_number` | string | Sim | Número da conta |
| `disbursement_bank_account.account_digit` | string | Sim | Dígito da conta |
| `disbursement_bank_account.document_number` | string | Sim | CPF do titular da conta |
| `disbursement_bank_account.name` | string | Sim | Nome do titular da conta |

        **Response**

MÉTODO POST
ENDPOINT /baas/debt_fgts

Response Body

```json
{
    "data": {
        "borrower": {
            "document_number": "46338864879",
            "name": "PATRICIA APARECIDA DO NASCIMENTO PEREIRA DA SILVA",
            "related_party_key": "824e4338-5b22-4e78-84db-94a23c56bf49"
        },
        "collaterals": [
            {
                "absolute_amount": null,
                "collateral_constituted": false,
                "collateral_data": {
                    "document_number": "46338864879",
                    "error_message": "None",
                    "periods": [
                        {
                            "amount": 1758.2,
                            "due_date": "2024-05-02"
                        }
                    ],
                    "protocol_number": null,
                    "reservation_request_closure_status": null,
                    "reservation_request_closure_status_translation": null,
                    "reservation_request_key": "1b6ce462-3a28-4601-bd27-ce8ce6b50781",
                    "reservation_request_status": "pending",
                    "reservation_request_status_translation": "Em Teimosinha"
                },
                "collateral_key": "01f511ee-3409-44f8-adb9-31fbeab87b27",
                "collateral_type": "fgts_balance",
                "created_at": "2024-01-17T14:59:35.434402",
                "external_key": "1b6ce462-3a28-4601-bd27-ce8ce6b50781",
                "percentage": 1,
                "updated_at": "2024-01-17T14:59:35.434387"
            }
        ],
        "contract": {
            "number": "0000083262/PAD",
            "signers": [
                {
                    "signature_url": null,
                    "signer_document_number": "46338864879",
                    "signer_email": "naotem@gmail.com",
                    "signer_external_key": null,
                    "signer_name": "PATRICIA APARECIDA DO NASCIMENTO PEREIRA DA SILVA",
                    "signer_role": "issuer"
                }
            ],
            "urls": [
                "https://storage.googleapis.com/sandbox-doc-api/documents/cb10aaac-a6da-4742-b86f-60726d9f6ce7/TESTEINSSS.A.-PATRICIA_APARECIDA_DO_NASCIMENTO_PEREIRA_DA_SILVA-CCB-0000083262-20240117145936.pdf"
            ]
        },
        "disbursement_options": [
            {
                "additional_iof": 6.278436,
                "annual_cet": "31,6323%",
                "assignment_amount": 1652.22,
                "base_iof": 14.361093768373301,
                "cet": "2,3200%",
                "contract_fee_amount": 8.26,
                "contract_fees": [
                    {
                        "fee_amount": 8.26,
                        "fee_type": "tac"
                    }
                ],
                "disbursed_issue_amount": 1623.32,
                "disbursement_date": "2024-01-17",
                "external_contract_fee_amount": 0.0,
                "external_contract_fees": [
                    {
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "spread",
                        "net_fee_amount": 0.0,
                        "rebate_bank_account": null,
                        "tax_amount": 0.0
                    },
                    {
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "tac",
                        "net_fee_amount": 0.0,
                        "rebate_bank_account": null,
                        "tax_amount": 0.0
                    },
                    {
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "insurance_premium",
                        "net_fee_amount": 0.0,
                        "rebate_bank_account": null,
                        "tax_amount": 0.0
                    }
                ],
                "first_due_date": "2024-05-02",
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2024-05-02",
                        "calendar_days": 106,
                        "due_date": "2024-05-02",
                        "due_interest": 0.0,
                        "due_principal": 1652.22,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "installment_status": null,
                        "installment_type": null,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 105.9802843565,
                        "principal_amortization_amount": 1652.2197156435,
                        "tax_amount": 14.361093768373301,
                        "total_amount": 1758.2,
                        "workdays": 72.0
                    }
                ],
                "issue_amount": 1652.22,
                "net_external_contract_fee_amount": 0.0,
                "number_of_installments": null,
                "pre_fixed_interest_rate": {
                    "annual_rate": 0.23872053,
                    "daily_rate": 0.00058669,
                    "interest_base": "calendar_days_365",
                    "monthly_rate": 0.018
                },
                "total_iof": 20.64,
                "total_pre_fixed_amount": 105.9802843565
            },
            {
                "additional_iof": 6.282122,
                "annual_cet": "31,6725%",
                "assignment_amount": 1653.19,
                "base_iof": 14.233957774255675,
                "cet": "2,3200%",
                "contract_fee_amount": 8.27,
                "contract_fees": [
                    {
                        "fee_amount": 8.27,
                        "fee_type": "tac"
                    }
                ],
                "disbursed_issue_amount": 1624.4,
                "disbursement_date": "2024-01-18",
                "external_contract_fee_amount": 0.0,
                "external_contract_fees": [
                    {
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "spread",
                        "net_fee_amount": 0.0,
                        "rebate_bank_account": null,
                        "tax_amount": 0.0
                    },
                    {
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "tac",
                        "net_fee_amount": 0.0,
                        "rebate_bank_account": null,
                        "tax_amount": 0.0
                    },
                    {
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "insurance_premium",
                        "net_fee_amount": 0.0,
                        "rebate_bank_account": null,
                        "tax_amount": 0.0
                    }
                ],
                "first_due_date": "2024-05-02",
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2024-05-02",
                        "calendar_days": 105,
                        "due_date": "2024-05-02",
                        "due_interest": 0.0,
                        "due_principal": 1653.19,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "installment_status": null,
                        "installment_type": null,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 105.0109437566,
                        "principal_amortization_amount": 1653.1890562434,
                        "tax_amount": 14.233957774255675,
                        "total_amount": 1758.2,
                        "workdays": 71.0
                    }
                ],
                "issue_amount": 1653.19,
                "net_external_contract_fee_amount": 0.0,
                "number_of_installments": null,
                "pre_fixed_interest_rate": {
                    "annual_rate": 0.23872053,
                    "daily_rate": 0.00058669,
                    "interest_base": "calendar_days_365",
                    "monthly_rate": 0.018
                },
                "total_iof": 20.52,
                "total_pre_fixed_amount": 105.0109437566
            },
            {
                "additional_iof": 6.285808,
                "annual_cet": "31,7080%",
                "assignment_amount": 1654.16,
                "base_iof": 14.10666765817373,
                "cet": "2,3200%",
                "contract_fee_amount": 8.27,
                "contract_fees": [
                    {
                        "fee_amount": 8.27,
                        "fee_type": "tac"
                    }
                ],
                "disbursed_issue_amount": 1625.5,
                "disbursement_date": "2024-01-19",
                "external_contract_fee_amount": 0.0,
                "external_contract_fees": [
                    {
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "spread",
                        "net_fee_amount": 0.0,
                        "rebate_bank_account": null,
                        "tax_amount": 0.0
                    },
                    {
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "tac",
                        "net_fee_amount": 0.0,
                        "rebate_bank_account": null,
                        "tax_amount": 0.0
                    },
                    {
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "insurance_premium",
                        "net_fee_amount": 0.0,
                        "rebate_bank_account": null,
                        "tax_amount": 0.0
                    }
                ],
                "first_due_date": "2024-05-02",
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2024-05-02",
                        "calendar_days": 104,
                        "due_date": "2024-05-02",
                        "due_interest": 0.0,
                        "due_principal": 1654.16,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "installment_status": null,
                        "installment_type": null,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 104.0410344543,
                        "principal_amortization_amount": 1654.1589655457,
                        "tax_amount": 14.10666765817373,
                        "total_amount": 1758.2,
                        "workdays": 70.0
                    }
                ],
                "issue_amount": 1654.16,
                "net_external_contract_fee_amount": 0.0,
                "number_of_installments": null,
                "pre_fixed_interest_rate": {
                    "annual_rate": 0.23872053,
                    "daily_rate": 0.00058669,
                    "interest_base": "calendar_days_365",
                    "monthly_rate": 0.018
                },
                "total_iof": 20.39,
                "total_pre_fixed_amount": 104.0410344543
            },
            {
                "additional_iof": 6.289494,
                "annual_cet": "31,7502%",
                "assignment_amount": 1655.13,
                "base_iof": 13.979223283044265,
                "cet": "2,3200%",
                "contract_fee_amount": 8.28,
                "contract_fees": [
                    {
                        "fee_amount": 8.28,
                        "fee_type": "tac"
                    }
                ],
                "disbursed_issue_amount": 1626.58,
                "disbursement_date": "2024-01-20",
                "external_contract_fee_amount": 0.0,
                "external_contract_fees": [
                    {
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "spread",
                        "net_fee_amount": 0.0,
                        "rebate_bank_account": null,
                        "tax_amount": 0.0
                    },
                    {
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "tac",
                        "net_fee_amount": 0.0,
                        "rebate_bank_account": null,
                        "tax_amount": 0.0
                    },
                    {
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "insurance_premium",
                        "net_fee_amount": 0.0,
                        "rebate_bank_account": null,
                        "tax_amount": 0.0
                    }
                ],
                "first_due_date": "2024-05-02",
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2024-05-02",
                        "calendar_days": 103,
                        "due_date": "2024-05-02",
                        "due_interest": 0.0,
                        "due_principal": 1655.13,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "installment_status": null,
                        "installment_type": null,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 103.070556116,
                        "principal_amortization_amount": 1655.129443884,
                        "tax_amount": 13.979223283044265,
                        "total_amount": 1758.2,
                        "workdays": 70.0
                    }
                ],
                "issue_amount": 1655.13,
                "net_external_contract_fee_amount": 0.0,
                "number_of_installments": null,
                "pre_fixed_interest_rate": {
                    "annual_rate": 0.23872053,
                    "daily_rate": 0.00058669,
                    "interest_base": "calendar_days_365",
                    "monthly_rate": 0.018
                },
                "total_iof": 20.27,
                "total_pre_fixed_amount": 103.070556116
            },
            {
                "additional_iof": 6.29318,
                "annual_cet": "31,7877%",
                "assignment_amount": 1656.1,
                "base_iof": 13.851624511675489,
                "cet": "2,3300%",
                "contract_fee_amount": 8.28,
                "contract_fees": [
                    {
                        "fee_amount": 8.28,
                        "fee_type": "tac"
                    }
                ],
                "disbursed_issue_amount": 1627.68,
                "disbursement_date": "2024-01-21",
                "external_contract_fee_amount": 0.0,
                "external_contract_fees": [
                    {
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "spread",
                        "net_fee_amount": 0.0,
                        "rebate_bank_account": null,
                        "tax_amount": 0.0
                    },
                    {
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "tac",
                        "net_fee_amount": 0.0,
                        "rebate_bank_account": null,
                        "tax_amount": 0.0
                    },
                    {
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "insurance_premium",
                        "net_fee_amount": 0.0,
                        "rebate_bank_account": null,
                        "tax_amount": 0.0
                    }
                ],
                "first_due_date": "2024-05-02",
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2024-05-02",
                        "calendar_days": 102,
                        "due_date": "2024-05-02",
                        "due_interest": 0.0,
                        "due_principal": 1656.1,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "installment_status": null,
                        "installment_type": null,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 102.099508408,
                        "principal_amortization_amount": 1656.100491592,
                        "tax_amount": 13.851624511675489,
                        "total_amount": 1758.2,
                        "workdays": 70.0
                    }
                ],
                "issue_amount": 1656.1,
                "net_external_contract_fee_amount": 0.0,
                "number_of_installments": null,
                "pre_fixed_interest_rate": {
                    "annual_rate": 0.23872053,
                    "daily_rate": 0.00058669,
                    "interest_base": "calendar_days_365",
                    "monthly_rate": 0.018
                },
                "total_iof": 20.14,
                "total_pre_fixed_amount": 102.099508408
            },
            {
                "additional_iof": 6.296866,
                "annual_cet": "31,8319%",
                "assignment_amount": 1657.07,
                "base_iof": 13.723871206771127,
                "cet": "2,3300%",
                "contract_fee_amount": 8.29,
                "contract_fees": [
                    {
                        "fee_amount": 8.29,
                        "fee_type": "tac"
                    }
                ],
                "disbursed_issue_amount": 1628.76,
                "disbursement_date": "2024-01-22",
                "external_contract_fee_amount": 0.0,
                "external_contract_fees": [
                    {
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "spread",
                        "net_fee_amount": 0.0,
                        "rebate_bank_account": null,
                        "tax_amount": 0.0
                    },
                    {
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "tac",
                        "net_fee_amount": 0.0,
                        "rebate_bank_account": null,
                        "tax_amount": 0.0
                    },
                    {
                        "description": null,
                        "fee_amount": 0.0,
                        "fee_type": "insurance_premium",
                        "net_fee_amount": 0.0,
                        "rebate_bank_account": null,
                        "tax_amount": 0.0
                    }
                ],
                "first_due_date": "2024-05-02",
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2024-05-02",
                        "calendar_days": 101,
                        "due_date": "2024-05-02",
                        "due_interest": 0.0,
                        "due_principal": 1657.07,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "installment_status": null,
                        "installment_type": null,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 101.127890996,
                        "principal_amortization_amount": 1657.072109004,
                        "tax_amount": 13.723871206771127,
                        "total_amount": 1758.2,
                        "workdays": 69.0
                    }
                ],
                "issue_amount": 1657.07,
                "net_external_contract_fee_amount": 0.0,
                "number_of_installments": null,
                "pre_fixed_interest_rate": {
                    "annual_rate": 0.23872053,
                    "daily_rate": 0.00058669,
                    "interest_base": "calendar_days_365",
                    "monthly_rate": 0.018
                },
                "total_iof": 20.02,
                "total_pre_fixed_amount": 101.127890996
            }
        ],
        "entry": null,
        "iof_charge_method": "financed",
        "prefixed_interest_rate": {
            "annual_rate": 0.23872053,
            "created_at": "2024-01-17T14:59:35",
            "daily_rate": 0.00058669,
            "interest_base": "calendar_days_365",
            "monthly_rate": 0.018
        },
        "requester_identifier_key": "2fedb18e-207b-4bb5-954a-0e6e19bb6e50"
    },
    "event_datetime": "2024-01-17 14:59:40",
    "key": "2fedb18e-207b-4bb5-954a-0e6e19bb6e50",
    "status": "waiting_signature",
    "webhook_type": "debt"
}

```
 

Testar no Playground

## 7 - Formalização da operação
Por padrão a QI Tech realiza a coleta de assinaturas através da QI Sign e o contrato é enviado para os assinantes no momento da emissão, porém ainda existe a possibilidade de o parceiro realizar a coleta de assinaturas de forma independente e enviar o documento assinado ou as evidencias de assinatura para a QI Tech para seguir com a operação.

**Tipos de assinatura aceitos**

**QI Sign**

A assinatura através da QI Sign ocorre de forma automática na plataforma QI Tech, uma vez que a operação é criada o documento é disparado pela QI Sign para coleta de assinaturas, após assinado a operação automaticamente muda de status aguardando o desembolso.

**pdf-signature**

Esse tipo indica que o PDF emitido através da "/debt" será assinado e link com o PDF assinado será enviado através da API 4.1 como forma de autenticação.

        **Request**

ENDPOINT /debt/{debt_key}/signed
MÉTODO POST

Request Body

```json
{
    "type": "pdf-signature",
    "path-pdf-signed": "https://www.google.com/"
}
```

| Campo | Tipo | Obrigatório | Descrição |
|-|-|-|-|
| `type` | string | Sim | Tipo de assinatura (`pdf-signature`) |
| `path-pdf-signed` | string (URL) | Sim | URL do PDF assinado |

        **Response**

MÉTODO POST
ENDPOINT /debt/{debt_key}/signed

Response Body

```json
{
  "data": {},
  "event_datetime": "2023-01-17 17:17:28",
  "key": "4630cd58-ab00-49b3-b8cb-cb0f4a5af7a4",
  "status": "signature_received",
  "webhook_type": "debt"
}
```

| Campo | Tipo | Descrição |
|-|-|-|
| `data` | object | Dados adicionais (vazio para assinatura) |
| `event_datetime` | string (datetime) | Data/hora do evento |
| `key` | string (UUID) | Chave da operação |
| `status` | string | Status (`signature_received`) |
| `webhook_type` | string | Tipo do webhook (`debt`) |

**data-signature**

Esse tipo indica que o PDF emitido através da "/debt" será assinado através de um hash anexado em sua ultima pagina.

A autenticação através de dados pode ter 3 tipos:

- **Opt-in**

A assinatura através de opt-in significa que o cliente vai dar o aceite do contrato através do front.

Para que essa assinatura seja valida, alguns dados devem ser enviados obrigatoriamente.

        **Request**

ENDPOINT /debt/{debt_key}/signed
MÉTODO POST

Request Body

```json
{
	"type": "data-signature",
	"signatures": [{
		"signed_object": {
			"document_key": "095bd363-a5be-4561-955d-f199bf664972",
            "document_md5": "06d19d6664f20a73158d277d41c8c7d3",
			"raw_text": "Lorem ipsum dolor sit amet, consectetur a...."
		},
		"authenticity": {
			"timestamp": "1970-01-01 00:00:01",
			"ip_address": "179.104.42.245",
			"session_id": "ddb1d063-4fdf-4430-af9c-3316e9142ff3",
            "fingerprint": {
				"lat": -7.205088,
				"long": -48.2414106,
				"name": "SM-A015M",
				"model": "SM-A015M",
				"calendar": "AM",
				"regionCode": "BR",
				"systemName": "Android",
				"orientation": "Portrait",
				"currencyCode": "BRL",
				"languageCode": "pt",
				"systemVersion": "11",
				"userinterface": "Android",
				"localizedModel": "SM-A015M",
				"decimalSeparator": ",",
				"usesMetricSystem": "true",
				"preferredLanguages": "pt-BR,en-BR",
				"supportsMultiTasking": "true"
			}
		},
		"signer": {
			"name": "VITOR",
			"email": "vitor.castello@qitech.com.br",
			"phone": {
				"country_code": "055",
				"area_code": "11",
				"number": "999999999"
			},
			"document_number": "645236363652"
		},
		"authentication_type": "opt_in"
	}]
}
```

| Campo | Tipo | Obrigatório | Descrição |
|-|-|-|-|
| `type` | string | Sim | Tipo de assinatura (`data-signature`) |
| `signatures[]` | array | Sim | Lista de assinaturas |
| `signatures[].signed_object.document_key` | string (UUID) | Sim | Chave do documento |
| `signatures[].signed_object.document_md5` | string | Sim | Hash MD5 do documento |
| `signatures[].signed_object.raw_text` | string | Sim | Texto do contrato |
| `signatures[].authenticity.timestamp` | string (datetime) | Sim | Timestamp da assinatura |
| `signatures[].authenticity.ip_address` | string | Sim | Endereço IP do assinante |
| `signatures[].authenticity.session_id` | string (UUID) | Não | ID da sessão |
| `signatures[].authenticity.fingerprint` | object | Não | Dados do dispositivo |
| `signatures[].signer.name` | string | Sim | Nome do assinante |
| `signatures[].signer.email` | string | Sim | E-mail do assinante |
| `signatures[].signer.phone` | object | Sim | Telefone do assinante |
| `signatures[].signer.document_number` | string | Sim | CPF do assinante |
| `signatures[].authentication_type` | string | Sim | Tipo de autenticação (`opt_in`) |

- **Zip**

A assinatura através de zip contempla o envio de um arquivo de comprovação, como uma ligação gravada.

        **Request**

ENDPOINT /debt/{debt_key}/signed
MÉTODO POST

Request Body

```json
{
    "type": "data-signature",
    "signatures": [
        {
            "signed_object": {
                "raw_text": "Lorem ipsum dolor sit amet, consectetur a....",
                "document_key": "79003de0-2590-455d-9b73-426b8ca284eb",
                "document_md5": "7521bd5621d97af26b2c1721fc4023a8"
            },
            "authenticity": {
                "timestamp": "1970-01-01 00:00:01",
                "document_key": "79003de0-2590-455d-9b73-426b8ca284eb",
                "document_md5": "7521bd5621d97af26b2c1721fc4023a8"
            },
            "signer": {
                "name": "IVANILDO DE SENA LIMA",
                "email": "ivanlima2604@gmail.com",
                "phone": {
                    "country_code": "055",
                    "area_code": "11",
                    "number": "999999999"
                },
                "document_number": "61766976204"
            },
            "authentication_type": "zip"
        }
    ]
}
```

| Campo | Tipo | Obrigatório | Descrição |
|-|-|-|-|
| `type` | string | Sim | Tipo de assinatura (`data-signature`) |
| `signatures[].signed_object.raw_text` | string | Sim | Texto do contrato |
| `signatures[].signed_object.document_key` | string (UUID) | Sim | Chave do documento |
| `signatures[].signed_object.document_md5` | string | Sim | Hash MD5 do documento |
| `signatures[].authenticity.timestamp` | string (datetime) | Sim | Timestamp da assinatura |
| `signatures[].authenticity.document_key` | string (UUID) | Sim | Chave do documento de comprovação (zip) |
| `signatures[].authenticity.document_md5` | string | Sim | Hash MD5 do documento de comprovação |
| `signatures[].signer.name` | string | Sim | Nome do assinante |
| `signatures[].signer.email` | string | Sim | E-mail do assinante |
| `signatures[].signer.phone` | object | Sim | Telefone do assinante |
| `signatures[].signer.document_number` | string | Sim | CPF do assinante |
| `signatures[].authentication_type` | string | Sim | Tipo de autenticação (`zip`) |

- **Selfie**

A autenticação através de selfie é disponibilizada para os parceiros que utilizam os serviços de CaaS QI Tech, onde a autenticação através de selfie é validada e um id de comprovação é gerado.

        **Request**

ENDPOINT /debt/{debt_key}/signed
MÉTODO POST

Request Body

```json
{
    "type": "data-signature",
    "signatures": [
        {
            "signed_object": {
                "raw_text": "Lorem ipsum dolor sit amet, consectetur a...."
            },
            "authenticity": {
                "timestamp": "1970-01-01 00:00:01",
                "facial_recognition_key": "79003de0-2590-455d-9b73-426b8ca284eb"
            },
            "signer": {
                "name": "IVANILDO DE SENA LIMA",
                "email": "ivanlima2604@gmail.com",
                "phone": {
                    "country_code": "055",
                    "area_code": "11",
                    "number": "999999999"
                },
                "document_number": "61766976204"
            },
            "authentication_type": "selfie"
        }
    ]
}
```

| Campo | Tipo | Obrigatório | Descrição |
|-|-|-|-|
| `type` | string | Sim | Tipo de assinatura (`data-signature`) |
| `signatures[].signed_object.raw_text` | string | Sim | Texto do contrato |
| `signatures[].authenticity.timestamp` | string (datetime) | Sim | Timestamp da assinatura |
| `signatures[].authenticity.facial_recognition_key` | string (UUID) | Sim | Chave de reconhecimento facial (CaaS) |
| `signatures[].signer.name` | string | Sim | Nome do assinante |
| `signatures[].signer.email` | string | Sim | E-mail do assinante |
| `signatures[].signer.phone` | object | Sim | Telefone do assinante |
| `signatures[].signer.document_number` | string | Sim | CPF do assinante |
| `signatures[].authentication_type` | string | Sim | Tipo de autenticação (`selfie`) |

        **Response**
MÉTODO POST
ENDPOINT /debt/{debt_key}/signed

Response Body

```json
{
  "data": {},
  "event_datetime": "2023-01-17 17:17:28",
  "key": "4630cd58-ab00-49b3-b8cb-cb0f4a5af7a4",
  "status": "signature_received",
  "webhook_type": "debt"
}
```

:::info
O Response é o mesmo para todas as operações realizadas através do endpoint /debt/\{debt_key\}/signed.
:::

Testar no Playground

## 8 - Máquina de estados e webhooks
Após a criação de uma dívida dentro do nosso sistema, são possíveis os seguintes status:

| Status | Tradução  |  
| -- | -- | 
| waiting_signature | Aguardando assinatura |
| signature_finished | Assinatura finalizada |  
| disbursed | Operação desembolsada (paga) |  
| canceled | Operação cancelada |  
| cancel_permanently | Operação cancelada permanentemente |  

**8.1. signature_finished:** Informa que a operação está assinada e fornece o url com o documento assinado.

        **Webhook**

WEBHOOK_TYPE debt
STATUS signature_finished

Body

```json
{
	"data": {
		"borrower": {
			"document_number": "46338864879",
			"name": "PATRICIA APARECIDA DO NASCIMENTO PEREIRA DA SILVA",
			"related_party_key": "9878573b-4ccf-4f72-be82-5ba70d25d5a7"
		},
		"collaterals": [{
			"absolute_amount": null,
			"collateral_constituted": false,
			"collateral_data": {
				"document_number": "46338864879",
				"error_message": "None",
				"periods": [{
						"amount": 222.21,
						"due_date": "2024-01-01"
					},
					{
						"amount": 382.14,
						"due_date": "2025-01-01"
					},
					{
						"amount": 311.43,
						"due_date": "2026-01-01"
					},
					{
						"amount": 342.38,
						"due_date": "2027-01-01"
					},
					{
						"amount": 194.29,
						"due_date": "2028-01-01"
					},
					{
						"amount": 97.15,
						"due_date": "2029-01-01"
					},
					{
						"amount": 48.57,
						"due_date": "2030-01-01"
					},
					{
						"amount": 24.29,
						"due_date": "2031-01-01"
					},
					{
						"amount": 12.14,
						"due_date": "2032-01-01"
					},
					{
						"amount": 6.07,
						"due_date": "2033-01-01"
					}
				],
				"protocol_number": null,
				"reservation_request_closure_status": null,
				"reservation_request_closure_status_translation": null,
				"reservation_request_key": "e2edaa95-69b8-47d3-8ca7-5e48fd3440c5",
				"reservation_request_status": "pending",
				"reservation_request_status_translation": "Em Teimosinha"
			},
			"collateral_key": "e9cf1551-5b95-4edf-827f-29bd4d4f0b2f",
			"collateral_type": "fgts_balance",
			"created_at": "2023-05-26T14:55:25.335308",
			"external_key": "977075c1-d529-4cc2-931c-188cab4aa761",
			"percentage": 1,
			"updated_at": "2023-05-26T14:55:25.335291"
		}],
		"contract": {
			"number": "0000064547/PAD",
			"signers": [{
				"signature_url": null,
				"signer_document_number": "46338864879",
				"signer_email": "naotem@gmail.com",
				"signer_external_key": null,
				"signer_name": "PATRICIA APARECIDA DO NASCIMENTO PEREIRA DA SILVA",
				"signer_role": "issuer"
			}],
			"urls": [
				"https://storage.googleapis.com/sandbox-doc-api/documents/8a370979-727b-4865-a03a-27f8d6208f57/SYNGENTASANDBOX-PATRICIA_APARECIDA_DO_NASCIMENTO_PEREIRA_DA_SILVA-CCB-0000070572-20230526145531.pdf"
			]
		},
		"disbursement_options": [{
				"additional_iof": 3.282668,
				"annual_cet": "29,8407%",
				"assignment_amount": 872.5,
				"base_iof": 24.828504537437023,
				"cet": "2,2000%",
				"contract_fee_amount": 8.64,
				"contract_fees": [{
					"fee_amount": 8.64,
					"fee_type": "tac"
				}],
				"disbursed_issue_amount": 827.11,
				"disbursement_date": "2023-05-26",
				"external_contract_fee_amount": 8.64,
				"external_contract_fees": [{
						"description": null,
						"fee_amount": 8.64,
						"fee_type": "spread",
						"net_fee_amount": 7.84,
						"rebate_bank_account": null,
						"tax_amount": 0.8
					},
					{
						"description": null,
						"fee_amount": 0,
						"fee_type": "tac",
						"net_fee_amount": 0,
						"rebate_bank_account": null,
						"tax_amount": 0
					}
				],
				"first_due_date": "2024-01-01",
				"installments": [{
						"additional_costs": [],
						"business_due_date": "2024-01-02",
						"calendar_days": 220,
						"due_date": "2024-01-01",
						"due_interest": 0,
						"due_principal": 863.86,
						"fine_amount": null,
						"has_interest": true,
						"installment_number": 1,
						"installment_status": null,
						"installment_type": null,
						"post_fixed_amount": null,
						"pre_fixed_amount": 135.8606707299,
						"principal_amortization_amount": 86.3493292701,
						"tax_amount": 1.557741900032604,
						"total_amount": 222.21,
						"workdays": 149
					},
 					...
				],
				"issue_amount": 863.86,
				"net_external_contract_fee_amount": 7.84,
				"number_of_installments": null,
				"pre_fixed_interest_rate": {
					"annual_rate": 0.274223,
					"daily_rate": 0.00066416,
					"interest_base": "calendar_days_365",
					"monthly_rate": 0.02040001
				},
				"total_iof": 28.11,
				"total_pre_fixed_amount": 776.8144015216
			},
			...
		],
		"entry": null,
		"iof_charge_method": "financed",
		"prefixed_interest_rate": {
			"annual_rate": 0.274223,
			"created_at": "2023-05-26T14:55:31",
			"daily_rate": 0.00066416,
			"interest_base": "calendar_days_365",
			"monthly_rate": 0.02040001
		},
		"requester_identifier_key": "e99ed7c8-ecb3-441d-9130-45feb0ad9c36"
	},
	"event_datetime": "2023-05-26 14:55:38",
	"key": "e99ed7c8-ecb3-441d-9130-45feb0ad9c36",
	"status": "waiting_signature",
	"webhook_type": "debt"
}
```

 

**8.2. signature_finished (simplificado):** Webhook simplificado informando que a operação está assinada.

        **Webhook**

WEBHOOK_TYPE debt
STATUS Signature_finished

Body

```json
{
     "webhook_type": "debt",
     "key":"57f8e1ce-1080-4d0d-a195-89709b961561",
     "event_datetime": "2022-09-29 20:00:54",
     "status":"signature_finished",
  }

```

 

**8.3. disbursed:** Indica que o recurso foi enviado para a conta do cliente. 
Além de dispor dos dados de transferência do pagamento e um comprovante em pdf do desembolso realizado.

        **Webhook**

WEBHOOK_TYPE debt
STATUS disbursed

Body

```json
{
    "webhook": {
        "key": "4475d350-a63f-4d93-8e76-40386ce942b0",
        "data": {
            "installments": [
                {
                    "due_date": "2024-08-01",
                    "total_amount": 1264.12,
                    "installment_key": "526ca3da-d669-4db5-a16c-67a687c4a755",
                    "pre_fixed_amount": 141.15866647,
                    "principal_amortization_amount": 1122.96133353
                }
            ],
            "ted_receipt_list": [
                {
                    "fee": 0,
                    "url": "https://storage.googleapis.com/sandbox-doc-api/documents/099e04d7-3fe5-41ba-bef3-4165d0a09a99/099e04d7-3fe5-41ba-bef3-4165d0a09a99.pdf",
                    "amount": 1100,
                    "origin": {
                        "name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
                        "type": "payment_account",
                        "branch": "0001",
                        "document": "32402502000135",
                        "bank_code": "329",
                        "account_key": "5d068423-6094-49e4-b15b-7740038295a8",
                        "branch_digit": null,
                        "account_digit": "5",
                        "account_branch": "0001",
                        "account_number": "00002",
                        "financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A."
                    },
                    "timestamp": "2024-01-11T13:28:45",
                    "description": "00360305 0465 100071066-1 24182533410 - Mock Person Name",
                    "destination": {
                        "name": "Mock Person Name",
                        "type": "checking_account",
                        "branch": "0465",
                        "purpose": "Crédito PIX em Conta",
                        "document": "24182533410",
                        "bank_ispb": "00360305",
                        "branch_digit": null,
                        "account_digit": "1",
                        "account_number": "100071066",
                        "financial_institution_name": "CAIXA ECONOMICA FEDERAL"
                    },
                    "end_to_end_id": "E32402502202401111328RqgXuWz64uU",
                    "transaction_key": "cffe9c42-fec0-49fc-b9f6-7a5b431f8374",
                    "origin_transaction_key": "e8ef9c9f-b813-418a-b19c-8fab0dfcb67e"
                }
            ],
            "requester_identifier_key": null
        },
        "status": "disbursed",
        "webhook_type": "debt",
        "event_datetime": "2024-01-11 13:28:46"
    }
}
```
 

**8.4. canceled:** Indica o cancelamento da operação. Isso pode ser causado por dados bancários incorretos na tentativa de pagamento, falta de assinatura, limite da data de desembolso excedido ou alguma questão em relação à averbação do saldo.

:::warning Atenção
O cancelamento da operação não indica que a operação será desaverbada na Caixa. Para que seja disparado a solicitação de desaverbação do saldo do cliente deve-se obrigatoriamente cancelar permanentemente a operação.
:::

Nessa lista de enumeradores, você encontra todos os possíveis motivos de cancelamento de uma operação, por erro na averbação.

        **Webhook**

WEBHOOK_TYPE debt
STATUS canceled

Body

```json
{
	"key": "6613ebf5-b41d-4257-b2f9-89ce261c5041",
	"data": {
		"cancel_reason": "Available Balance is not sufficient for given periods amount",
		"cancel_reason_enumerator": "fgts_insufficient_balance"
	},
	"status": "canceled",
	"webhook_type": "debt",
	"event_datetime": "2022-12-22 21:27:41"
}

```

| Campo | Tipo | Descrição |
|-|-|-|
| `key` | string (UUID) | Chave da operação |
| `data.cancel_reason` | string | Descrição do motivo do cancelamento |
| `data.cancel_reason_enumerator` | string | Enumerador do cancelamento |
| `status` | string | Status (`canceled`) |
| `webhook_type` | string | Tipo do webhook (`debt`) |
| `event_datetime` | string (datetime) | Data/hora do evento |

 
**8.5. Colateral constituído:**

        **Webhook**

WEBHOOK_TYPE credit_operation.collateral
STATUS NA

Body

```json
{
	"key": "767b4ca4-0afc-4e28-a7d7-645bef1873c2",
	"data": {
		"collateral_type": "fgts",
		"collateral_constituted": true
	},
	"event_time": "2022-12-09 19:02:32",
	"webhook_type": "credit_operation.collateral"
}
```

| Campo | Tipo | Descrição |
|-|-|-|
| `key` | string (UUID) | Chave da operação |
| `data.collateral_type` | string | Tipo de garantia (`fgts`) |
| `data.collateral_constituted` | boolean | Indica se a garantia foi constituída |
| `event_time` | string (datetime) | Data/hora do evento |
| `webhook_type` | string | Tipo do webhook (`credit_operation.collateral`) |

 
## 9 - Simulando cenários de sucesso e insucesso na averbação em Sandbox:
**9.1.** O cenário ideal é simulado para os CPFs iniciados com 0, 1, 2 ou 3.

|Início do CPF	| Ação	|
|---|---|
|0, 1, 2 ou 3| Operação segue com sucesso até o desembolso  |

**9.2.** Simulando casos de falha na averbação:

Todas as averbações com CPFs que começam com 9 terão erros. Alguns tratáveis, outros que disparam retentativa e outros inesperados.

Todas as averbações com CPFs que começam com 8 terão erros por falta de saldo.

:::caution 
Alguns erros na averbação, mesmo disparando um webhook de cancelamento, são passíveis de rententativa de averbação. Então, é necessário  
:::
 
### Enumeradores webhook de cancelamento por erro na averbação   
|cancel_reason_enumerator	|cancel_reason|  Descrição| Ação QI | 
| -- | -- |   -- | -- | 
|fgts_invalid_given_period	| Given periods date does not match with CEF system |  Uma ou mais datas de previsão do saque informadas não conferem com as datas previstas no sistema da Caixa ou os valores enviados para as parcelas são maiores do que o disponível | Operação é cancelada e não retentamos averbação | 
|fgts_unauthorized_institution	| Institution isn't authorized by the client  | Instituição não autorizada pelo cliente | Operação é cancelada e retentamos a averbação 
|fgts_processing_pending_changes | 	Changes on profile info happened on client's FGTS account |  Operação não permitida por mudanças nas informações do perfil na conta do FGTS do cliente | Operação é cancelada e não retentamos averbação | 
|fgts_on_locked_date_range |	Not permitted action on current date  | A Operação não é permitida na data atual | Operação é cancelada e retentamos a averbação na data pemitida  |
|fgts_insufficient_balance |	Available Balance is not sufficient for given periods amount | Trabalhador não possui saldo disponível para a Operação Fiduciária  |  Operação é cancelada e não retentamos averbação | 
|fgts_inexistent_anniversary_membership | 	Client does not have membership for anniversary withdraw on current date |  Trabalhador não possui adesão ao saque aniversário na data vigente |  Operação é cancelada e não retentamos averbação | 
|fgts_period_rejected |	Reservation period not accepted |  Protocolo recusado pela CEF |  Operação é cancelada e não retentamos averbação
|fgts_deletion_request | Deletion request was before the reservation was completed |  A solicitação de desaverbação foi realizada antes da conclusão da reserva |   Operação é cancelada e não retentamos averbação | 
|fgts_protocol_removed | Protocol was removed |  Protocolo removido na CEF  |  Operação é cancelada e não retentamos averbação |
|fgts_insufficient_balance_available |	The indicated value is not available for contracting | O valor indicado não está disponível para a contratação  | Operação é cancelada e não retentamos averbação
|fgts_insufficient_balance_for_guarantee |	Available balance is not sufficient for the required guarantee |   O saldo disponível não é suficiente para a garantia requerida   | Operação é cancelada e não retentamos averbação
|fgts_fgts_accounts_not_found |	The informed worker does not have FGTS accounts |  O Trabalhador informado não possui contas de FGTS | Operação é cancelada e não retentamos averbação

## 10 - Reapresentação de Operações
Existem casos onde a data de desembolso selecionada para a operação pode passar com pendências no contrato, o que faz com que o mesmo seja cancelado.

Para que seja possível reiniciar o processo de um contrato já cancelado, é necessário recalcular a operação. Temos duas formas para o envio: alterar a data de desembolso ou alterar os dados da conta bancária de desembolso.

### 10.1 - Mudança da data de desembolso:

        **Request**

ENDPOINT /debt/{debt_key}/disbursement_option
MÉTODO PATCH

Request Body

```json
{
    "disbursement_date": "2023-06-30",
    "status": "active"
}
```

| Campo | Tipo | Obrigatório | Descrição |
|-|-|-|-|
| `disbursement_date` | string (date) | Sim | Nova data de desembolso |
| `status` | string | Sim | Status desejado (`active`) |

STATUS 200

**Response Body**

```json
{
	"data": {
		"additional_iof": 17.770586,
		"annual_cet": 31.682,
		"assignment_amount": 4676.97,
		"base_iof": 127.71954759,
		"borrower": {
			"document_number": "88229032939",
			"name": "Teste",
			"related_party_key": "13d210c8-d39a-40f9-bd16-b6ab81d35fa8"
		},
		"cet": 2.32,
		"collaterals": [],
		"contract": {
			"number": "0000051370/TG",
			"urls": [
				"https://storage.googleapis.com/dev-doc-api/documents/a715175f-8d29-4929-9576-4b692d1e9610/BEATRIZCOUTODECARVALHO-TESTE-CCB-0000051370-20230707151409.pdf"
			]
		},
		"contract_fee_amount": 0.5,
		"contract_fees": [{
			"fee_amount": 0.5,
			"fee_type": "spread"
		}],
		"disbursed_issue_amount": 4530.98,
		"entry": null,
		"external_contract_fee_amount": 0.0,
		"external_contract_fees": [{
			"description": null,
			"fee_amount": 0.0,
			"fee_type": "spread",
			"net_fee_amount": 0.0,
			"rebate_bank_account": null,
			"tax_amount": 0.0
		}],
		"installments": [{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2023-08-29",
				"calendar_days": 50,
				"digitable_line": null,
				"due_date": "2023-08-28",
				"due_interest": 0.0,
				"due_principal": 4676.47,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "29c6e226-b710-4e3b-a5d6-62119b9d9547",
				"installment_number": 1,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 4676.47,
				"original_pre_fixed_amount": 164.86042852,
				"original_principal_amortization_amount": 25.13957148,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 164.86042852,
				"principal_amortization_amount": 25.13957148,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 0.10307224,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 36
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2023-09-29",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2023-09-28",
				"due_interest": 0.0,
				"due_principal": 4651.33042852,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "322d7973-4d2a-41a6-ad1b-2fef59c551b7",
				"installment_number": 2,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 4651.33042852,
				"original_pre_fixed_amount": 100.99385125,
				"original_principal_amortization_amount": 89.00614875,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 100.99385125,
				"principal_amortization_amount": 89.00614875,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 0.59117884,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 22
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2023-10-31",
				"calendar_days": 30,
				"digitable_line": null,
				"due_date": "2023-10-28",
				"due_interest": 0.0,
				"due_principal": 4562.32427977,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "a2d43778-0342-48f7-a0d2-c385773fa545",
				"installment_number": 3,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 4562.32427977,
				"original_pre_fixed_amount": 95.83242026,
				"original_principal_amortization_amount": 94.16757974,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 95.83242026,
				"principal_amortization_amount": 94.16757974,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 0.85711331,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 20
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2023-11-29",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2023-11-28",
				"due_interest": 0.0,
				"due_principal": 4468.15670003,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "9126aa9a-6bb0-44c6-8ea4-61fd68fcd936",
				"installment_number": 4,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 4468.15670003,
				"original_pre_fixed_amount": 97.01661904,
				"original_principal_amortization_amount": 92.98338096,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 97.01661904,
				"principal_amortization_amount": 92.98338096,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 1.08269849,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 20
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2023-12-29",
				"calendar_days": 30,
				"digitable_line": null,
				"due_date": "2023-12-28",
				"due_interest": 0.0,
				"due_principal": 4375.17331907,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "f0b363f9-0aca-4154-b14a-2c7933374abc",
				"installment_number": 5,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 4375.17331907,
				"original_pre_fixed_amount": 91.90128137,
				"original_principal_amortization_amount": 98.09871863,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 91.90128137,
				"principal_amortization_amount": 98.09871863,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 1.38358433,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 21
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2024-01-30",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2024-01-28",
				"due_interest": 0.0,
				"due_principal": 4277.07460043,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "c7c41dee-28a3-4b37-b2de-256fa0c9a0a9",
				"installment_number": 6,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 4277.07460043,
				"original_pre_fixed_amount": 92.86767319,
				"original_principal_amortization_amount": 97.13232681,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 92.86767319,
				"principal_amortization_amount": 97.13232681,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 1.61686471,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 20
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2024-02-29",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2024-02-28",
				"due_interest": 0.0,
				"due_principal": 4179.94227362,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "ee5d7b27-5160-49d3-9eb0-ec5a2f20e50d",
				"installment_number": 7,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 4179.94227362,
				"original_pre_fixed_amount": 90.75864903,
				"original_principal_amortization_amount": 99.24135097,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 90.75864903,
				"principal_amortization_amount": 99.24135097,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 1.90424304,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 21
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2024-04-01",
				"calendar_days": 29,
				"digitable_line": null,
				"due_date": "2024-03-28",
				"due_interest": 0.0,
				"due_principal": 4080.70092265,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "a9ec8c98-0061-4956-8af8-93d5742f6c1f",
				"installment_number": 8,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 4080.70092265,
				"original_pre_fixed_amount": 82.82984224,
				"original_principal_amortization_amount": 107.17015776,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 82.82984224,
				"principal_amortization_amount": 107.17015776,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 2.31123162,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 21
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2024-04-30",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2024-04-28",
				"due_interest": 0.0,
				"due_principal": 3973.53076489,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "bfd2ceab-74d4-4ff4-b099-c6ab986b7acb",
				"installment_number": 9,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 3973.53076489,
				"original_pre_fixed_amount": 86.2768573,
				"original_principal_amortization_amount": 103.7231427,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 86.2768573,
				"principal_amortization_amount": 103.7231427,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 2.50055752,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 20
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2024-05-29",
				"calendar_days": 30,
				"digitable_line": null,
				"due_date": "2024-05-28",
				"due_interest": 0.0,
				"due_principal": 3869.80762219,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "eb41f47f-ffcd-4d4d-8834-600cfe95b2a4",
				"installment_number": 10,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 3869.80762219,
				"original_pre_fixed_amount": 81.2859859,
				"original_principal_amortization_amount": 108.7140141,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 81.2859859,
				"principal_amortization_amount": 108.7140141,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 2.88831393,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 21
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2024-07-01",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2024-06-28",
				"due_interest": 0.0,
				"due_principal": 3761.09360809,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "13183e83-70cf-4990-a3cc-c979e43015b9",
				"installment_number": 11,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 3761.09360809,
				"original_pre_fixed_amount": 81.6642313,
				"original_principal_amortization_amount": 108.3357687,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 81.6642313,
				"principal_amortization_amount": 108.3357687,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 3.15365423,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 22
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2024-07-30",
				"calendar_days": 30,
				"digitable_line": null,
				"due_date": "2024-07-28",
				"due_interest": 0.0,
				"due_principal": 3652.75783939,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "a2ed3748-8567-4cab-a1ff-0cf6b2698d15",
				"installment_number": 12,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 3652.75783939,
				"original_pre_fixed_amount": 76.72681698,
				"original_principal_amortization_amount": 113.27318302,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 76.72681698,
				"principal_amortization_amount": 113.27318302,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 3.39026637,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 20
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2024-08-29",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2024-08-28",
				"due_interest": 0.0,
				"due_principal": 3539.48465638,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "1e009f23-2044-40ba-8249-a9077a2391b9",
				"installment_number": 13,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 3539.48465638,
				"original_pre_fixed_amount": 76.85245907,
				"original_principal_amortization_amount": 113.14754093,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 76.85245907,
				"principal_amortization_amount": 113.14754093,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 3.3865059,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 23
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2024-10-01",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2024-09-28",
				"due_interest": 0.0,
				"due_principal": 3426.33711545,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "e475d886-a596-4541-bcae-4986bf7c3609",
				"installment_number": 14,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 3426.33711545,
				"original_pre_fixed_amount": 74.39569823,
				"original_principal_amortization_amount": 115.60430177,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 74.39569823,
				"principal_amortization_amount": 115.60430177,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 3.46003675,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 22
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2024-10-29",
				"calendar_days": 30,
				"digitable_line": null,
				"due_date": "2024-10-28",
				"due_interest": 0.0,
				"due_principal": 3310.73281367,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "5584643d-4e65-4e99-9483-b3c1b051fd63",
				"installment_number": 15,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 3310.73281367,
				"original_pre_fixed_amount": 69.54252108,
				"original_principal_amortization_amount": 120.45747892,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 69.54252108,
				"principal_amortization_amount": 120.45747892,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 3.60529234,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 21
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2024-11-29",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2024-11-28",
				"due_interest": 0.0,
				"due_principal": 3190.27533475,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "23a0002c-49bf-4c22-a506-d89ae4372249",
				"installment_number": 16,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 3190.27533475,
				"original_pre_fixed_amount": 69.27011321,
				"original_principal_amortization_amount": 120.72988679,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 69.27011321,
				"principal_amortization_amount": 120.72988679,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 3.61344551,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 22
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2024-12-31",
				"calendar_days": 30,
				"digitable_line": null,
				"due_date": "2024-12-28",
				"due_interest": 0.0,
				"due_principal": 3069.54544796,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "5efbf6d0-84bc-4041-8a33-e9ab1bf82969",
				"installment_number": 17,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 3069.54544796,
				"original_pre_fixed_amount": 64.47633798,
				"original_principal_amortization_amount": 125.52366202,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 64.47633798,
				"principal_amortization_amount": 125.52366202,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 3.7569232,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 20
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2025-01-29",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2025-01-28",
				"due_interest": 0.0,
				"due_principal": 2944.02178595,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "e9bb5d68-8c93-43a4-b240-d68b0d1d6d08",
				"installment_number": 18,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 2944.02178595,
				"original_pre_fixed_amount": 63.9232354,
				"original_principal_amortization_amount": 126.0767646,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 63.9232354,
				"principal_amortization_amount": 126.0767646,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 3.77347756,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 21
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2025-03-05",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2025-02-28",
				"due_interest": 0.0,
				"due_principal": 2817.94502134,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "d6c34059-ba9b-4345-b937-35293f34a3dd",
				"installment_number": 19,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 2817.94502134,
				"original_pre_fixed_amount": 61.18574366,
				"original_principal_amortization_amount": 128.81425634,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 61.18574366,
				"principal_amortization_amount": 128.81425634,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 3.85541069,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 23
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2025-03-31",
				"calendar_days": 28,
				"digitable_line": null,
				"due_date": "2025-03-28",
				"due_interest": 0.0,
				"due_principal": 2689.130765,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "63fa4169-f1a9-43f0-a059-70e2df35ac7e",
				"installment_number": 20,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 2689.130765,
				"original_pre_fixed_amount": 52.68330953,
				"original_principal_amortization_amount": 137.31669047,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 52.68330953,
				"principal_amortization_amount": 137.31669047,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 4.10988855,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 18
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2025-04-29",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2025-04-28",
				"due_interest": 0.0,
				"due_principal": 2551.81407453,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "859ee4fa-f781-419b-8888-731b0f8fc01b",
				"installment_number": 21,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 2551.81407453,
				"original_pre_fixed_amount": 55.40726995,
				"original_principal_amortization_amount": 134.59273005,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 55.40726995,
				"principal_amortization_amount": 134.59273005,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 4.02836041,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 19
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2025-05-29",
				"calendar_days": 30,
				"digitable_line": null,
				"due_date": "2025-05-28",
				"due_interest": 0.0,
				"due_principal": 2417.22134448,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "d6e25388-d54d-42ca-8b46-ac70fa7aeb23",
				"installment_number": 22,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 2417.22134448,
				"original_pre_fixed_amount": 50.7741553,
				"original_principal_amortization_amount": 139.2258447,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 50.7741553,
				"principal_amortization_amount": 139.2258447,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 4.16702953,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 21
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2025-07-01",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2025-06-28",
				"due_interest": 0.0,
				"due_principal": 2277.99549978,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "d92f0e38-fa48-48c2-a79e-e8316fe5c870",
				"installment_number": 23,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 2277.99549978,
				"original_pre_fixed_amount": 49.46187558,
				"original_principal_amortization_amount": 140.53812442,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 49.46187558,
				"principal_amortization_amount": 140.53812442,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 4.20630606,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 21
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2025-07-29",
				"calendar_days": 30,
				"digitable_line": null,
				"due_date": "2025-07-28",
				"due_interest": 0.0,
				"due_principal": 2137.45737535,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "04aa2658-8fbe-4147-8a14-03c7bba13577",
				"installment_number": 24,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 2137.45737535,
				"original_pre_fixed_amount": 44.89766385,
				"original_principal_amortization_amount": 145.10233615,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 44.89766385,
				"principal_amortization_amount": 145.10233615,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 4.34291292,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 21
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2025-08-29",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2025-08-28",
				"due_interest": 0.0,
				"due_principal": 1992.35503921,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "af5b3343-7d91-46cf-a908-bf24e4e79907",
				"installment_number": 25,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 1992.35503921,
				"original_pre_fixed_amount": 43.25979382,
				"original_principal_amortization_amount": 146.74020618,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 43.25979382,
				"principal_amortization_amount": 146.74020618,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 4.39193437,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 23
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2025-09-30",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2025-09-28",
				"due_interest": 0.0,
				"due_principal": 1845.61483303,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "1e7981d6-4274-49f1-ab6e-a98d97485e78",
				"installment_number": 26,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 1845.61483303,
				"original_pre_fixed_amount": 40.07363891,
				"original_principal_amortization_amount": 149.92636109,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 40.07363891,
				"principal_amortization_amount": 149.92636109,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 4.48729599,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 21
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2025-10-29",
				"calendar_days": 30,
				"digitable_line": null,
				"due_date": "2025-10-28",
				"due_interest": 0.0,
				"due_principal": 1695.68847194,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "a07e171b-e2a6-49b4-9d6d-8124fff9d736",
				"installment_number": 27,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 1695.68847194,
				"original_pre_fixed_amount": 35.61823023,
				"original_principal_amortization_amount": 154.38176977,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 35.61823023,
				"principal_amortization_amount": 154.38176977,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 4.62064637,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 22
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2025-12-01",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2025-11-28",
				"due_interest": 0.0,
				"due_principal": 1541.30670217,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "0cd84cc5-0dd0-4318-99f9-178843d3d5b5",
				"installment_number": 28,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 1541.30670217,
				"original_pre_fixed_amount": 33.46622796,
				"original_principal_amortization_amount": 156.53377204,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 33.46622796,
				"principal_amortization_amount": 156.53377204,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 4.6850558,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 23
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2025-12-30",
				"calendar_days": 30,
				"digitable_line": null,
				"due_date": "2025-12-28",
				"due_interest": 0.0,
				"due_principal": 1384.77293013,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "24dc3c8b-ac3a-496e-8646-a1e66051090b",
				"installment_number": 29,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 1384.77293013,
				"original_pre_fixed_amount": 29.08739451,
				"original_principal_amortization_amount": 160.91260549,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 29.08739451,
				"principal_amortization_amount": 160.91260549,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 4.81611428,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 19
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2026-01-29",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2026-01-28",
				"due_interest": 0.0,
				"due_principal": 1223.86032464,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "bba128ee-b195-4a65-9caf-3ebe452d9d10",
				"installment_number": 30,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 1223.86032464,
				"original_pre_fixed_amount": 26.57354762,
				"original_principal_amortization_amount": 163.42645238,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 26.57354762,
				"principal_amortization_amount": 163.42645238,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 4.89135372,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 22
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2026-03-03",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2026-02-28",
				"due_interest": 0.0,
				"due_principal": 1060.43387227,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "35a03898-607a-4194-804c-bfd375c3ea45",
				"installment_number": 31,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 1060.43387227,
				"original_pre_fixed_amount": 23.02508598,
				"original_principal_amortization_amount": 166.97491402,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 23.02508598,
				"principal_amortization_amount": 166.97491402,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 4.99755918,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 20
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2026-03-31",
				"calendar_days": 28,
				"digitable_line": null,
				"due_date": "2026-03-28",
				"due_interest": 0.0,
				"due_principal": 893.45895824,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "0a8a83db-835d-46bc-8e24-c542c44d6e68",
				"installment_number": 32,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 893.45895824,
				"original_pre_fixed_amount": 17.50393379,
				"original_principal_amortization_amount": 172.49606621,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 17.50393379,
				"principal_amortization_amount": 172.49606621,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 5.16280726,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 20
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2026-04-29",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2026-04-28",
				"due_interest": 0.0,
				"due_principal": 720.96289203,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "07e3155c-30b5-4d13-8a31-0af4c7d5c9c5",
				"installment_number": 33,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 720.96289203,
				"original_pre_fixed_amount": 15.65418772,
				"original_principal_amortization_amount": 174.34581228,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 15.65418772,
				"principal_amortization_amount": 174.34581228,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 5.21817016,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 20
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2026-05-29",
				"calendar_days": 30,
				"digitable_line": null,
				"due_date": "2026-05-28",
				"due_interest": 0.0,
				"due_principal": 546.61707975,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "d1badc80-d7a2-4428-abf6-4877ac9f4497",
				"installment_number": 34,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 546.61707975,
				"original_pre_fixed_amount": 11.48178326,
				"original_principal_amortization_amount": 178.51821674,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 11.48178326,
				"principal_amortization_amount": 178.51821674,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 5.34305023,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 21
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2026-06-30",
				"calendar_days": 31,
				"digitable_line": null,
				"due_date": "2026-06-28",
				"due_interest": 0.0,
				"due_principal": 368.098863,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "4b466830-c432-4478-a1b9-bff6562834ee",
				"installment_number": 35,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 368.098863,
				"original_pre_fixed_amount": 7.99248758,
				"original_principal_amortization_amount": 182.00751242,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 7.99248758,
				"principal_amortization_amount": 182.00751242,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 5.44748485,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 20
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0.0,
				"bank_slip_key": null,
				"business_due_date": "2026-07-29",
				"calendar_days": 30,
				"digitable_line": null,
				"due_date": "2026-07-28",
				"due_interest": 0.0,
				"due_principal": 186.09135058,
				"fine_amount": null,
				"has_interest": true,
				"installment_history": [],
				"installment_key": "0e8843ff-1339-40ab-a0b5-c450eca68e44",
				"installment_number": 36,
				"installment_payment": [],
				"installment_status": "created",
				"installment_type": "principal",
				"original_due_principal": 186.09135058,
				"original_pre_fixed_amount": 3.90887682,
				"original_principal_amortization_amount": 186.09112318,
				"original_total_amount": 190.0,
				"paid_amount": 0.0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 3.90887682,
				"principal_amortization_amount": 186.09112318,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 5.56970732,
				"total_accrual_amount": null,
				"total_amount": 190.0,
				"total_paid_amount": 0.0,
				"workdays": 22
			}
		],
		"iof_charge_method": "financed",
		"issue_amount": 4676.47,
		"net_external_contract_fee_amount": 0.0,
		"number_of_installments": 36,
		"prefixed_interest_rate": {
			"annual_rate": 0.28777498,
			"created_at": "2023-07-07T18:13:42",
			"daily_rate": 0.00069316,
			"interest_base": "calendar_days_365",
			"monthly_rate": 0.0213
		},
		"requester_identifier_key": "7d174b91-e411-4375-b788-9ced9b941cd0",
		"total_iof": 145.49,
		"total_pre_fixed_amount": 2163.53022742
	},
	"event_datetime": "2023-07-07 19:04:20",
	"key": "7d174b91-e411-4375-b788-9ced9b941cd0",
	"status": "waiting_signature",
	"webhook_type": "debt"
}
```

Testar no Playground

### 10.2 - Mudança dos dados bancários:

        **Request**

ENDPOINT /debt/{debt_key}/disbursement_bank_accounts
MÉTODO PUT

**Request Body**

```json
{
	"disbursement_bank_accounts": [{
		"bank_code": "329",
		"branch_number": "001",
		"account_number": "6947216",
		"account_digit": "4",
		"account_type": "checking_account",
		"document_number": "946321801",
		"name": "Pedro Felipe Henrique Alves",
		"percentage_receivable": 100
	}]
}
```

| Campo | Tipo | Obrigatório | Descrição |
|-|-|-|-|
| `disbursement_bank_accounts[]` | array | Sim | Lista de contas bancárias |
| `disbursement_bank_accounts[].bank_code` | string | Sim | Código do banco |
| `disbursement_bank_accounts[].branch_number` | string | Sim | Número da agência |
| `disbursement_bank_accounts[].account_number` | string | Sim | Número da conta |
| `disbursement_bank_accounts[].account_digit` | string | Sim | Dígito da conta |
| `disbursement_bank_accounts[].account_type` | string | Sim | Tipo de conta (`checking_account`, `savings_account`) |
| `disbursement_bank_accounts[].document_number` | string | Sim | CPF do titular |
| `disbursement_bank_accounts[].name` | string | Sim | Nome do titular |
| `disbursement_bank_accounts[].percentage_receivable` | number | Sim | Percentual recebido (100) |

        **Response**

STATUS 200

**Response Body**

```json
{}
```

Testar no Playground

:::info 
**Quando uma operação é cancelada e pode ser reapresentada:**

- Caso a data de desembolso enviada seja ultrapassada ainda com pendências nas assinaturas do contrato;

- Caso a averbação não seja concluída até a data de desembolso;

- Caso exista algum problema com os dados bancários para o pagamento da operação;
:::

## 11 - Cancelamento da operação
**Permite a Instituição Fiduciária realizar, junto ao Agente Operador do FGTS, o cancelamento de uma reserva de valores de saque aniversário do Trabalhador utilizados como garantia para uma operação fiduciária**

**ATENÇÃO: A operação só poderá ser desaverbada se ela já tiver sido cancelada.**

        **Request**

ENDPOINT /debt/[debt_key]/cancel_permanently
MÉTODO POST
PARAMETERS debt_key

        **Payload**

|Key | Value | Description|
|--|--|--|
|debt_key| 95ba572e-b8d2-43db-94b9-8c4a0405e3bc |Debt key da operação que esta sendo cancelada.|

        **Response**

STATUS 200
ENDPOINT /debt/{debt_key}/cancel_permanently
MÉTODO POST

Request Body

```json
{
	"data": {
		"additional_iof": 0.956498,
		"annual_cet": 41.5826,
		"assignment_amount": 251.71,
		"base_iof": 5.38721386,
		"borrower": {
			"document_number": "0000000000",
			"name": "Andre Luis Souto de Souza"
		},
		"cet": 2.94,
		"collaterals": [{
			"collateral_constituted": false,
			"collateral_data": {
				"document_number": "00000000000",
				"error_message": "None",
				"periods": [{
						"amount": 116.48,
						"due_date": "2023-04-01"
					},
					{
						"amount": 81.53,
						"due_date": "2024-04-01"
					},
					{
						"amount": 57.07,
						"due_date": "2025-04-01"
					},
					{
						"amount": 39.95,
						"due_date": "2026-04-01"
					},
					{
						"amount": 37.29,
						"due_date": "2027-04-01"
					},
					{
						"amount": 27.96,
						"due_date": "2028-04-01"
					},
					{
						"amount": 13.99,
						"due_date": "2029-04-01"
					},
					{
						"amount": 6.99,
						"due_date": "2030-04-01"
					},
					{
						"amount": 3.49,
						"due_date": "2031-04-01"
					},
					{
						"amount": 3.6,
						"due_date": "2032-04-01"
					}
				],
				"protocol_number": null,
				"reservation_request_closure_status": null,
				"reservation_request_closure_status_translation": null,
				"reservation_request_key": "11e904ad-1e7c-46c7-9e15-16d3650670bd",
				"reservation_request_status": "pending",
				"reservation_request_status_translation": "Em Teimosinha"
			},
			"collateral_key": "7686f240-329b-4ef5-8956-914c05cbd445",
			"collateral_type": "fgts_balance",
			"created_at": "2022-12-19T15:52:32",
			"external_key": "11e904ad-1e7c-46c7-9e15-16d3650670bd",
			"percentage": 1,
			"updated_at": "2022-12-20T21:09:27.573223"
		}],
		"contract": {
			"number": "0003296996/ALS-R",
			"urls": [
				"https://storage.googleapis.com/live-doc-api/documents/0e2d7181-799c-4134-af18-2a9ffb14da57/HUBCREDFINTECHLTDA-ANDRE_LUIS_SOUTO_DE_SOUZA-CCB-0003296996-20221219155233.pdf"
			]
		},
		"contract_fee_amount": 2.46,
		"contract_fees": [{
				"fee_amount": 1.26,
				"fee_type": "tac"
			},
			{
				"fee_amount": 1.2,
				"fee_type": "ted_fee"
			}
		],
		"disbursed_issue_amount": 211.45,
		"entry": null,
		"external_contract_fee_amount": 31.46,
		"external_contract_fees": [{
				"description": null,
				"fee_amount": 15.1,
				"fee_type": "tac",
				"net_fee_amount": 12.95,
				"rebate_bank_account": {
					"account_branch": "1",
					"account_digit": "5",
					"account_number": "1000398",
					"created_at": "2022-12-19T15:52:32",
					"document_number": "000000000000",
					"financial_institutions": {
						"code_number": 329,
						"is_active": true,
						"is_pix_participant": true,
						"ispb": 32402502,
						"name": "QI SCD S.A."
					},
					"financial_institutions_code_number": 329,
					"name": "QI SOCIEDADE DE CREDITO DIRETO SA"
				},
				"tax_amount": 2.15
			},
			{
				"description": null,
				"fee_amount": 16.36,
				"fee_type": "tac",
				"net_fee_amount": 14.03,
				"rebate_bank_account": {
					"account_branch": "1",
					"account_digit": "1",
					"account_number": "1000418",
					"created_at": "2022-12-19T15:52:32",
					"document_number": "000000000000",
					"financial_institutions": {
						"code_number": 329,
						"is_active": true,
						"is_pix_participant": true,
						"ispb": 32402502,
						"name": "QI SCD S.A."
					},
					"financial_institutions_code_number": 329,
					"name": "QI SOCIEDADE DE CREDITO DIRETO SA"
				},
				"tax_amount": 2.33
			},
			{
				"description": null,
				"fee_amount": 0,
				"fee_type": "spread",
				"net_fee_amount": 0,
				"rebate_bank_account": null,
				"tax_amount": 0
			}
		],
		"installments": [{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0,
				"bank_slip_key": null,
				"business_due_date": "2023-04-03",
				"calendar_days": 103,
				"digitable_line": null,
				"due_date": "2023-04-01",
				"due_interest": 0,
				"due_principal": 251.71,
				"fine_amount": null,
				"has_interest": true,
				"installment_key": "9badede6-9db0-45d9-9797-9b1459eb4a38",
				"installment_number": 1,
				"installment_payment": [],
				"installment_status": "canceled",
				"installment_type": "principal",
				"original_due_principal": 251.71,
				"original_pre_fixed_amount": 16.57,
				"original_principal_amortization_amount": 99.91,
				"original_total_amount": 116.48,
				"paid_amount": 0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 16.57,
				"principal_amortization_amount": 99.91,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 0.84383986,
				"total_accrual_amount": null,
				"total_amount": 116.48,
				"total_paid_amount": 0,
				"workdays": 72
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0,
				"bank_slip_key": null,
				"business_due_date": "2024-04-01",
				"calendar_days": 366,
				"digitable_line": null,
				"due_date": "2024-04-01",
				"due_interest": 0,
				"due_principal": 151.8,
				"fine_amount": null,
				"has_interest": true,
				"installment_key": "c3c86b8b-5af8-47de-a77a-ef8622955219",
				"installment_number": 2,
				"installment_payment": [],
				"installment_status": "canceled",
				"installment_type": "principal",
				"original_due_principal": 151.8,
				"original_pre_fixed_amount": 38.58,
				"original_principal_amortization_amount": 42.95,
				"original_total_amount": 81.53,
				"paid_amount": 0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 38.58,
				"principal_amortization_amount": 42.95,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 1.2854935,
				"total_accrual_amount": null,
				"total_amount": 81.53,
				"total_paid_amount": 0,
				"workdays": 248
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0,
				"bank_slip_key": null,
				"business_due_date": "2025-04-01",
				"calendar_days": 365,
				"digitable_line": null,
				"due_date": "2025-04-01",
				"due_interest": 0,
				"due_principal": 108.85,
				"fine_amount": null,
				"has_interest": true,
				"installment_key": "5c3aa86f-bb17-4e60-85d0-64cfc8082332",
				"installment_number": 3,
				"installment_payment": [],
				"installment_status": "canceled",
				"installment_type": "principal",
				"original_due_principal": 108.85,
				"original_pre_fixed_amount": 27.58,
				"original_principal_amortization_amount": 29.49,
				"original_total_amount": 57.07,
				"paid_amount": 0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 27.58,
				"principal_amortization_amount": 29.49,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 0.8826357,
				"total_accrual_amount": null,
				"total_amount": 57.07,
				"total_paid_amount": 0,
				"workdays": 254
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0,
				"bank_slip_key": null,
				"business_due_date": "2026-04-01",
				"calendar_days": 365,
				"digitable_line": null,
				"due_date": "2026-04-01",
				"due_interest": 0,
				"due_principal": 79.36,
				"fine_amount": null,
				"has_interest": true,
				"installment_key": "e3e01865-bd87-4934-bce4-52fcae82c30e",
				"installment_number": 4,
				"installment_payment": [],
				"installment_status": "canceled",
				"installment_type": "principal",
				"original_due_principal": 79.36,
				"original_pre_fixed_amount": 20.11,
				"original_principal_amortization_amount": 19.84,
				"original_total_amount": 39.95,
				"paid_amount": 0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 20.11,
				"principal_amortization_amount": 19.84,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 0.5938112,
				"total_accrual_amount": null,
				"total_amount": 39.95,
				"total_paid_amount": 0,
				"workdays": 253
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0,
				"bank_slip_key": null,
				"business_due_date": "2027-04-01",
				"calendar_days": 365,
				"digitable_line": null,
				"due_date": "2027-04-01",
				"due_interest": 0,
				"due_principal": 59.52,
				"fine_amount": null,
				"has_interest": true,
				"installment_key": "a0f2a23f-0766-4912-a0de-7b84c1df1c9e",
				"installment_number": 5,
				"installment_payment": [],
				"installment_status": "canceled",
				"installment_type": "principal",
				"original_due_principal": 59.52,
				"original_pre_fixed_amount": 15.08,
				"original_principal_amortization_amount": 22.21,
				"original_total_amount": 37.29,
				"paid_amount": 0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 15.08,
				"principal_amortization_amount": 22.21,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 0.6647453,
				"total_accrual_amount": null,
				"total_amount": 37.29,
				"total_paid_amount": 0,
				"workdays": 249
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0,
				"bank_slip_key": null,
				"business_due_date": "2028-04-03",
				"calendar_days": 366,
				"digitable_line": null,
				"due_date": "2028-04-01",
				"due_interest": 0,
				"due_principal": 37.31,
				"fine_amount": null,
				"has_interest": true,
				"installment_key": "a0916b23-c193-4a61-8850-1fbae73440d5",
				"installment_number": 6,
				"installment_payment": [],
				"installment_status": "canceled",
				"installment_type": "principal",
				"original_due_principal": 37.31,
				"original_pre_fixed_amount": 9.48,
				"original_principal_amortization_amount": 18.48,
				"original_total_amount": 27.96,
				"paid_amount": 0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 9.48,
				"principal_amortization_amount": 18.48,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 0.5531064,
				"total_accrual_amount": null,
				"total_amount": 27.96,
				"total_paid_amount": 0,
				"workdays": 253
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0,
				"bank_slip_key": null,
				"business_due_date": "2029-04-02",
				"calendar_days": 365,
				"digitable_line": null,
				"due_date": "2029-04-01",
				"due_interest": 0,
				"due_principal": 18.83,
				"fine_amount": null,
				"has_interest": true,
				"installment_key": "aeda565d-e743-408d-bbff-32374eadd02d",
				"installment_number": 7,
				"installment_payment": [],
				"installment_status": "canceled",
				"installment_type": "principal",
				"original_due_principal": 18.83,
				"original_pre_fixed_amount": 4.77,
				"original_principal_amortization_amount": 9.22,
				"original_total_amount": 13.99,
				"paid_amount": 0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 4.77,
				"principal_amortization_amount": 9.22,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 0.2759546,
				"total_accrual_amount": null,
				"total_amount": 13.99,
				"total_paid_amount": 0,
				"workdays": 247
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0,
				"bank_slip_key": null,
				"business_due_date": "2030-04-01",
				"calendar_days": 365,
				"digitable_line": null,
				"due_date": "2030-04-01",
				"due_interest": 0,
				"due_principal": 9.61,
				"fine_amount": null,
				"has_interest": true,
				"installment_key": "8a8dcf1a-40fb-4526-b7ab-ae133c12b388",
				"installment_number": 8,
				"installment_payment": [],
				"installment_status": "canceled",
				"installment_type": "principal",
				"original_due_principal": 9.61,
				"original_pre_fixed_amount": 2.44,
				"original_principal_amortization_amount": 4.55,
				"original_total_amount": 6.99,
				"paid_amount": 0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 2.44,
				"principal_amortization_amount": 4.55,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 0.1361815,
				"total_accrual_amount": null,
				"total_amount": 6.99,
				"total_paid_amount": 0,
				"workdays": 251
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0,
				"bank_slip_key": null,
				"business_due_date": "2031-04-01",
				"calendar_days": 365,
				"digitable_line": null,
				"due_date": "2031-04-01",
				"due_interest": 0,
				"due_principal": 5.06,
				"fine_amount": null,
				"has_interest": true,
				"installment_key": "10c9b5d0-0401-4e7c-b58e-635de70434c7",
				"installment_number": 9,
				"installment_payment": [],
				"installment_status": "canceled",
				"installment_type": "principal",
				"original_due_principal": 5.06,
				"original_pre_fixed_amount": 1.28,
				"original_principal_amortization_amount": 2.21,
				"original_total_amount": 3.49,
				"paid_amount": 0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 1.28,
				"principal_amortization_amount": 2.21,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 0.0661453,
				"total_accrual_amount": null,
				"total_amount": 3.49,
				"total_paid_amount": 0,
				"workdays": 253
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0,
				"bank_slip_key": null,
				"business_due_date": "2032-04-01",
				"calendar_days": 366,
				"digitable_line": null,
				"due_date": "2032-04-01",
				"due_interest": 0,
				"due_principal": 2.85,
				"fine_amount": null,
				"has_interest": true,
				"installment_key": "663f8109-cca3-469a-855a-4f0294fb77ba",
				"installment_number": 10,
				"installment_payment": [],
				"installment_status": "canceled",
				"installment_type": "principal",
				"original_due_principal": 2.85,
				"original_pre_fixed_amount": 0.75,
				"original_principal_amortization_amount": 2.85,
				"original_total_amount": 3.6,
				"paid_amount": 0,
				"paid_at": null,
				"post_fixed_amount": null,
				"pre_fixed_amount": 0.75,
				"principal_amortization_amount": 2.85,
				"qr_code_key": null,
				"qr_code_url": null,
				"renegotiation_proposal_key": null,
				"tax_amount": 0.0853005,
				"total_accrual_amount": null,
				"total_amount": 3.6,
				"total_paid_amount": 0,
				"workdays": 253
			}
		],
		"iof_charge_method": "financed",
		"issue_amount": 251.71,
		"net_external_contract_fee_amount": 26.98,
		"number_of_installments": 10,
		"prefixed_interest_rate": {
			"annual_rate": 0.25340149,
			"created_at": "2022-12-19T15:52:32",
			"daily_rate": 0.00061899,
			"interest_base": "calendar_days_365",
			"monthly_rate": 0.019
		},
		"requester_identifier_key": "93a47fc5-5969-42ff-bdbb-3c9e8ec58d35",
		"total_iof": 6.34,
		"total_pre_fixed_amount": 136.64
	},
	"event_datetime": "2022-12-20 21:09:28",
	"key": "93a47fc5-5969-42ff-bdbb-3c9e8ec58d35",
	"status": "canceled_permanently",
	"webhook_type": "debt"
}
```

Quando todas as reversões são executadas com sucesso, uma rotina é executada uma vez por dia, coletando o valor adequado e enviando para o fundo.

        **Response**

STATUS 400
ENDPOINT /debt/{debt_key}/cancel_permanently
MÉTODO POST

Request Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Operation with status \{status\} cannot be cancelled.\", \"translation\": \"Essa operação com \{status\} não permite cancelamento.\", \"extra_fields\": {}, \"code\": \"COP000245\"}"
}
 ```

Testar no Playground

## 12 - Acompanhamento e mapeamento dos status das reservas
O objeto "last_response" traz os dados da última tentativa de reserva ou liberação (averbação ou desaverbação) realizada pela QI na Caixa.

O campo "last_response.success.enumerator" será retornado caso a reserva/liberação (averbação/desaverbação) tenha sido finalizada com sucesso.

O campo "last_response.errors.enumerator" traz a mensagem de erro retornada pela Caixa na última tentativa de reserva/liberação (averbação/desaverbação).

O campo "last_response_event_datetime" traz a data e horário da última tentativa de reserva/liberação (averbação/desaverbação)

Testar no Playground

### 12.1 - Casos de sucesso

#### Request

ENDPOINT /debt/{debt_key}/collateral
MÉTODO GET

        **Response**

Response Body

```json
{
  "collateral_constituted": true,
  "collateral_type": "fgts_balance",
  "updated_at": "2023-05-24 19:13:02",
  "collateral_data": {
    "periods": [
      {
        "amount": 77.86,
        "due_date": "2023-12-01"
      },
      {
        "amount": 54.51,
        "due_date": "2024-12-01"
      },
      {
        "amount": 38.83,
        "due_date": "2025-12-01"
      },
      {
        "amount": 35.34,
        "due_date": "2026-12-01"
      }
    ],
    "document_number": "73422975004",
    "status": "waiting_protocol_activation",
    "last_response": {
      "success": [
        {
          "enumerator": "protocol_created"
        }
      ]
    },
    "last_response_event_datetime": "2023-05-22T19:13:02Z"
  }
}
```

| Enumerador | Descrição   | Ação da QI   | Ação do cliente 
|------------------------------|------------------------------|  ------------------------------|  ------------------------------| 
| `protocol_created` | Protocolo criado com sucesso | Início da etapa de ativação de protocolo | Aguardar a ativação de protocolo
| `successfully_reserved` | Protocolo ativado com sucesso. Saldo está reservado  |Envio do webhook de colateral constituído | Aguardar o cumprimento de todos os requsitos de desembolso e o pagamento da operação de crédito

### 12.2 - Casos de erro

        **Request**

ENDPOINT /debt/{debt_key}/collateral
MÉTODO GET

        **Response**

Response Body

```json
{
  "collateral_constituted": false,
  "collateral_type": "fgts_balance",
  "updated_at": "2023-05-24 19:13:02",
  "collateral_data": {
    "periods": [
      {
        "amount": 77.86,
        "due_date": "2023-12-01"
      },
      {
        "amount": 54.51,
        "due_date": "2024-12-01"
      },
      {
        "amount": 38.83,
        "due_date": "2025-12-01"
      },
      {
        "amount": 35.34,
        "due_date": "2026-12-01"
      }
    ],
    "document_number": "73422975004",
    "status": "pending_protocol",
    "last_response": {
      "errors": [
        {
          "enumerator": "on_locked_date_range"
        }
      ]
    },
    "last_response_event_datetime": "2023-05-22T19:13:02Z"
  }
}
```

| Enumerador                           | Descrição<br/>   |  Ação da QI  | Ação do Cliente |
|--------------------------------------|-----------------------------------------------------------------------------|-------------|-----------|
| `unauthorized_institution`           | Instituição não autorizada pelo cliente                                           | Cancelamento da operação, porém continuamos rententando a averbação | Orientar o cliente a realizar a autorização da "**QI SOCIEDADE DE CREDITO S.A**" para operar o Adiantamento do Saque Aniversário FGTS |
| `inexistent_anniversary_membership ` | Trabalhador não possui adesão ao saque aniversário na data vigente   | Cancelamento da operação, saldo do cliente não é averbado (retirada da nossa fila de retentativas)| Necessário orientar o cliente a aderir a modalidade de Saque Aniversário no aplicativo do FGTS | 
| `on_locked_date_range `              | A Operação não é permitida na data atual | Retentativa de averbação apenas na data em que a operação passa a ser permitida | A operação é permitida no segundo dia útil do próximo mês. Como a operação fica travada até esse período, recomenda-se o envio cancelamento permanente e a devida comunicação com o cliente, visto que ele não conseguirá fazer a operação no momento em nenhuma outra instituição financeira |
| `insufficient_balance `              | Trabalhador não possui saldo disponível para a Operação Fiduciária  | Cancelamento da operação, saldo do cliente não é averbado (retirada da nossa fila de retentativas) | Recomenda-se reduzir valor da operação ou cancelar a operação, caso o saldo seja zerado.|
| `processing_pending_changes `        | Operação não permitida por pendência no processo de pagamento de Saque Aniversário | Cancelamento da operação, saldo do cliente não é averbado (retirada da nossa fila de retentativas)| Orientar cliente a aguardar a regularização |
| `invalid_given_period `              | Uma ou mais datas de previsão do saque informadas não conferem com as datas previstas no sistema da Caixa ou os valores enviados para as parcelas são maiores do que o disponível   | Recomenda-se reduzir valor da operação ou cancelar caso saldo seja zerado Cancelamento da operação, saldo do cliente não é averbado (retirada da nossa fila de retentativas) | Necessário a digitação de uma nova operação |
| `operation_in_process`               | Reserva pendente de protocolo | Retentativa de averbação do saldo do cliente  | A Caixa tem uma rotina que destrava essas reservas a cada um ou dois dias. Sendo assim, é necessário orientar o cliente que a reserva está presa na Caixa e será liberada em breve |
| `not_found_operation`                | Status só é retornado para reservas em processo de desaverbação   | Encaminhamos a reserva para nossa fila de deleção para garantir que não existe saldo do cliente bloqueado conosco, então mudamos o status da reserva para cancelado | Necessário a digitação de uma nova operação |
| `anniversary_membership_egress `     | Trabalhador com solicitação de retorno para saque rescisão |  Cancelamento da operação, saldo do cliente não é averbado (retirada da nossa fila de retentativas) | Orientar cliente que ele solicitou o egresso da modalidade de Saque Aniversário, isso  impede que ele faça o adiantamento de seus saques
| `protocol_removed`                   | Protocolo removido na CEF   | Cancelamento da operação, saldo do cliente não é averbado (retirada da nossa fila de retentativas) | Necessário a digitação de uma nova operação |
| `protocol_rejected`                  | Protocolo recusado pela CEF  | Cancelamento da operação, saldo do cliente não é averbado (retirada da nossa fila de retentativas)|  Necessário a digitação de uma nova operação
| `protocol_in_process`                | Protocolo está em processamento na CEF     | Retentativa de averbação do saldo do cliente |  A Caixa tem uma rotina que destrava essas reservas a cada um ou dois dias. Sendo assim, é necessário orientar o cliente que a reserva está presa na Caixa e será liberada em breve
| `timeout`                            | A CEF retornou erro de timeout     | Retentativa de averbação do saldo do cliente | Necessário acompanhar os próximos retornos da Caixa e aguardar a averbação do saldo do cliente. Esse erro é normal quando temos períodos de instabilidade na Caixa 
| `unexpected_error`                   | A CEF retornou erro inesperado     | Retentativa de averbação do saldo do cliente | Necessário acompanhar os próximos retornos da Caixa e aguardar a averbação do saldo do cliente.
| `period_rejected`                    | Período da reserva recusado pela CEF    | Cancelamento da operação, saldo do cliente não é averbado (retirada da nossa fila de retentativas)| Necessário a digitação de uma nova operação para que sejam enviados períodos atualizados
| `deletion_request`                   | A solicitação de desaverbação foi realizada antes da conclusão da reserva   | Cancelamento da operação, saldo do cliente não é averbado (retirada da nossa fila de retentativas) |  Necessário a digitação de uma nova operação para que seja feito uma nova tentativa de averbação  |  
| `rate_limit_exceeded`                | Número máximo de requisições por segundo na CEF foi excedido   | Retentativa de averbação do saldo do cliente  | Acompanhar os próximos retornos da Caixa e aguardar a averbação do saldo do cliente 
| `misformatted_error `                | A CEF retornou um erro mal formatado   |  Retentativa de averbação do saldo do cliente |  Acompanhar os próximos retornos da Caixa e aguardar a averbação do saldo do cliente    |
| `unlisted_error     `                | A CEF retornou um erro que não está listado  |   Retentativa de averbação do saldo do cliente | Acompanhar os próximos retornos da Caixa e aguardar a averbação do saldo do cliente 
| `registration_changes_or_debit_transactions     `                | Foram feitas alterações cadastrais ou movimentações de débito na conta do FGTS, impossibilitando o processo de contratação.  |   Retentativa de averbação do saldo do cliente | Necessário a reapresentação da operação, após a regularização das pendências, se ainda houver opções de desembolso
| `fgts_accounts_not_found     `                | O trabalhador informado não tem contas do FGTS  |   Cancelamento da operação, saldo do cliente não é averbado (retirada da nossa fila de retentativas) |Necessário a digitação de uma nova operação para que seja feito uma nova tentativa de averbação, assim que o processo de pagamento pendente for resolvido
| `inexistent_anniversary_membership_on_period`                | A CEF retornou um erro que não está listado  |   Retentativa de averbação do saldo do cliente | Acompanhar os próximos retornos da Caixa e aguardar a averbação do saldo do cliente 
| `insufficient_balance_available`                | O valor indicado não está disponível para contratação |   Cancelamento da operação, saldo do cliente não é averbado (retirada da nossa fila de retentativas)| Recomenda-se reduzir o valor da operação para fazer uma nova tentativa, se houver saldo disponível. Ou cancelar a operação, redigitando a operação para conseguir um saldo atualizado.
| `insufficient_balance_for_guarantee`                | O saldo disponível não é suficiente para a garantia requerida |   Cancelamento da operação, saldo do cliente não é averbado (retirada da nossa fila de retentativas) | Recomenda-se reduzir o valor da operação para fazer uma nova tentativa, se houver saldo disponível. Ou cancelar a operação, redigitando a operação para conseguir um saldo atualizado.

---

# Manual de Garantia Veicular

URL: /documentation/manual_garantia_veicular/

:::caution API em desenvolvimento
A API ainda está em fase de desenvolvimento, sendo assim, este manual está sujeito a alterações.
:::

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeados de forma estrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
É possível consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

Este manual descreve o fluxo completo de uma operação de crédito com garantia veicular (gravame). O registro de gravame no SNG/B3, o registro do contrato no DETRAN/Registradora, o envio de imagem e o cancelamento são realizados internamente pela QI Tech. O processo é acompanhado via endpoints de consulta (GET) e webhooks.

## Pré-requisitos

1. Possuir credenciais de acesso à API QI Tech (veja [Primeiros Passos](/documentation/primeiros_passos/inicio));
2. Ter concluído a homologação em ambiente sandbox;
3. Veículo deve possuir informações válidas de chassi, RENAVAM (quando já emplacado) e UF de licenciamento.

## Visão Geral do Fluxo

![Visão geral do fluxo de garantia veicular](/img/diagrams/manual-garantia-veicular-manual-garantia-veicular.svg)

1. **Simular** — Envie `POST /debt_simulation` com `collateral_type: "vehicle"` (ver [Simulação e Emissão](/documentation/garantia_veicular/simulacao_e_emissao));
2. **Criar a operação** — Envie `POST /debt` incluindo os dados do veículo no objeto `collaterals` (ver [Simulação e Emissão](/documentation/garantia_veicular/simulacao_e_emissao));
3. **QI Tech registra o gravame** — Após a assinatura do contrato, a QI Tech envia automaticamente a inclusão de gravame ao SNG/B3. Webhooks enviados: `pending_reservation_confirmation` → `reserved`;
4. **Desembolso** — Após a confirmação do gravame (`reserved`), a QI Tech realiza o desembolso (transferência de recursos) para a conta informada;
5. **QI Tech registra o contrato** — A QI Tech envia automaticamente o registro de contrato ao DETRAN/Registradora. Webhooks enviados: `pending_registration_confirmation` → `registered`;
6. **QI Tech envia a imagem do contrato** — A QI Tech realiza o envio da imagem ao DETRAN/Registradora;
7. **Acompanhar o progresso** — Consulte a reserva (gravame) e registro (contrato) a qualquer momento via endpoints GET (ver [Consultas](/documentation/garantia_veicular/consultas));
8. **Receber notificações** — Os webhooks de gravame usam o tipo `laas.vehicle_collateral.reservation.status_change` (SNG/B3) e os de contrato usam `laas.vehicle_collateral.contract.status_change` (DETRAN) (ver [Webhooks](/documentation/garantia_veicular/webhooks)).

:::info URLs Base
**Homologação:** Fornecida pela QI Tech durante o onboarding.  
**Produção:** Fornecida pela QI Tech após homologação.
:::

:::info Códigos HTTP
200 = Sucesso · 201 = Criado · 400 = Falha na validação (ver body) · 401 = Não autorizado · 403 = Requisição indevida · 404 = Não encontrado · 500 = Erro interno
:::

---

# Manual Leilão de propostas Meu INSS

URL: /documentation/manual_leilao_meu_inss/

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita.
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

## Introdução

### Bem-vindo à API de Leilão de Propostas do Meu INSS. 

O **Leilão de Propostas do Meu INSS** é um serviço que permite a consulta de *Solicitações de Propostas*, criadas pelos beneficiários, e a inclusão de *Propostas*, por parte dos consignatários,  para assim oferecer oportunidades de Crédito ao aposentado/pensionista. 

A API permite a criação, atualização, consulta e cancelamento de propostas dentro do Leilão. ***Que vença a melhor proposta!!!***

### Problemas?

Caso tenha algum problema entre em contato com o nosso suporte (suporte@qitech.com.br) e nós responderemos o mais rápido possível.

### Ambientes

Possuímos dois ambientes para os nossos clientes. As URLs base das APIs são:

- Produção - `https://api-auth.qitech.app/`
- Sandbox - `https://api-auth.sandbox.qitech.app/`

## Somente HTTPS

Por questão de segurança, toda a comunicação com as APIs da QI Tech deve ser realizada utilizando a comunicação HTTPS. Para evitar que, por desatenção ou outro motivo, sejam feitas chamadas HTTP, este servidor somente disponibiliza a porta 443 com comunicação TLS 1.2. Chamadas realizadas utilizando outros protocolos serão automaticamente negadas.

## ProposalRequest: Solicitação de Proposta de Crédito

A `ProposalRequest` é o objeto que representa a **Solicitação de Proposta de Crédito** realizada pelo beneficiário. Para que um pensionista ou aposentado possa fazer uma solicitação, é necessário que ele tenha saldo disponível, esteja apto, além de possuir o benefício ativo e desbloqueado.

Quando a QI Tech receber uma nova **Solicitação de Proposta de Crédito**, enviaremos um Webhook para o endpoint configurado. 

Segue abaixo um exemplo do payload enviado:

```json
{
    "expiration_datetime": "2024-09-22T10:22:10Z",
    "status": "ongoing",
    "inclusion_limit_datetime": "2024-09-02T14:22:15Z",
    "proposal_request_key": "24e9625a-e264-4d33-8b59-a5238001b12f",
    "proposal_request_data": {
        "consigned_credit": {
            "balance": 432
        }
    }
}
```

:::warning Atenção
Esses são os dados iniciais da solicitação de proposta. Para visualizar **TODAS AS INFORMAÇÕES** dos beneficiários é necessário criar uma **Proposta** aceitando a respectiva **ProposalRequest**. Os demais dados consistem no **CPF**, **Nome**, **Data de nascimento**, **número de benefício**, **tipo de benefício**, entre outros...
:::

## Definição do Objeto ProposalRequest

Todas as trocas de informação de uma ProposalRequest utilizam a seguinte definição para este objeto. Em alguns casos, para facilitar a implementação e diminuir o fluxo de dados entre as partes, algumas informações poderão ser omitidas.

| Nome            | Tipo   | Descrição                                                                          |
| --------------- | ------ | ---------------------------------------------------------------------------------- |
| proposal_request_key        | string  | Identificador único da **Solicitação de Proposta** |
| proposal_request_data       | object  | Objeto que descreve os dados da **Solicitação de Proposta** |
| status                      | string  | Status da **Solicitação de Proposta** (`ongoing`, `finished`, `expired`)|
| expiration_datetime         | string  | Data de expiração da **Solicitação de Proposta** no formato `YYYY-MM-DDTHH:MM:SSZ` |
| inclusion_limit_datetime    | string  | Data limite para inclusão de **Propostas** no leilão no formato `YYYY-MM-DDTHH:MM:SSZ` |

### Definição do Objeto ProposalRequestData

| Nome            | Tipo   | Descrição                                                                          |
| --------------- | ------ | ---------------------------------------------------------------------------------- |
| name                        |string | Nome completo do Beneficiário |
| state                       |string | Estado do Beneficiário |
| document_number             |string | CPF do Beneficário |
| birth_date                  |string | Data de nascimento do Beneficiário no formato `DDMMYYYY` |
| benefit_number              |integer| Número do benefício do Aposentado/Pensionista |
| benefit_status              |string | Enumerador que descreve a situação do benefício |
| assistance_type             |string | Enumerador do **Tipo** do benefício |
| benefit_situation           |string | Enumerador que descreve a situação do benefício |
| max_total_balance           |float  | Valor comprometido possível para a respectiva espécie do benefício |
| used_total_balance          |float  | Valor total comprometido em averbações de empréstimos, reservado para portabilidade, refinanciamento, alterações, RMC e RCC |
| requested_disbursed_amount  |float  | Valor de desembolso solicitado pelo beneficiário |
| number_of_installments      |integer| Número de parcelas solicitados pelo beneficiário |
| has_legal_representative    |boolean| Indica se o beneficiário possui representante legal |
| has_power_of_attorney       |boolean| Indica se o beneficiário possui procurador |
| has_entity_representation   |boolean| Indica se o beneficiário possui entidade de representação |
| consigned_credit.balance    |float  | Valor disponível de saldo do beneficiário |

### Detalhamento dos Status da solicitação de proposta

O status da **Solicitação de Proposta** pode ser:

| Status  | Descrição                                                                 |
| ------- | ------------------------------------------------------------------------- |
| ongoing | **Solicitação de Proposta** em andamento, o leilão continua ativo.  |
| finished| **Solicitação de Proposta** finalizada, o leilão foi encerrado e uma **Proposta** enviada foi aceita e incluída. |
| expired | **Solicitação de Proposta** expirada, o leilão foi encerrado sem a inclusão de nenhuma **Proposta** em tempo hábil.  |

## Consultando uma Solicitação de Proposta após o envio do Webhook

Caso queira, ainda é possível consultar novamente a **Solicitação de Proposta** feita pelo beneficiário (mesmo após o envio do **Webhook automático**). Realize uma chamada via **API** utilizando o ***ID*** da **Solicitação de Proposta** enviado via Webhook automático.

:::warning Atenção
A Consulta completa dos dados do beneficiário também só será permitida caso o Parceiro Aceite a **Solicitação de Proposta** e Crie uma **Proposta**.
:::

ENDPOINT - `/social_security_auction/proposal_request/{proposal_request_key}`
MÉTODO - `GET`

### Path Params

| Campo         | Tipo   | Descrição                              | Caracteres | Obrigatório |
|---------------|--------|----------------------------------------|------------| ----------- |
| `proposal_request_key` | uuidv4 | Chave única de identificação da **ProposalRequest** utilizada no formato uuid v4. | 36         | Sim         |

### Response - Consulta Parcial

STATUS - 200

Response Body: Consulta parcial da PropostaRequest

```json
{
    "proposal_request_data": {
        "consigned_credit": {
            "balance": 750.00
        }
    },
    "proposal_request_key": "94340718-e90b-4641-b34b-7966297e49c4",
    "status": "ongoing",
    "inclusion_limit_datetime": "YYYY-MM-DDTHH:MM:SSZ",
    "expiration_datetime": "YYYY-MM-DDTHH:MM:SSZ"
}
```

Response Body: Consulta completa da PropostaRequest

```json
{
    "proposal_request_data": {
        "name": "João Silva",
        "state": "SP",
        "birth_date": "14031992",
        "benefit_number": 8784006178,
        "benefit_status": "elegible",
        "assistance_type": "retirement_by_age",
        "document_number": 71881324451,
        "consigned_credit": {
            "balance": 750.00
        },
        "benefit_situation": "active",
        "max_total_balance": 1800.00,
        "used_total_balance": 1400.00,
        "has_power_of_attorney": false,
        "number_of_installments": 48,
        "has_legal_representative": false,
        "has_entity_representation": false,
        "requested_disbursed_amount": 15000.00,
        "social_benefit_max_balance": 1800.00,
        "social_benefit_used_balance": 1400.00,
        "dataprev_proposal_request_id": 41
    },
    "proposal_request_key": "94340718-e90b-4641-b34b-7966297e49c4",
    "status": "ongoing",
    "inclusion_limit_datetime": "YYYY-MM-DDTHH:MM:SSZ",
    "expiration_datetime": "YYYY-MM-DDTHH:MM:SSZ"
}
```

*OBS: O detalhamento dos campos do `Response Body` estão descritos na definição do Objeto ProposalRequest acima.*

## Proposal: Proposta de Crédito ao Beneficiário

A `Proposal` é o objeto que representa a **Proposta de Crédito** realizada pelo consignatário ao beneficiário. Para a QI Tech incluir uma nova **Proposta** para o aposentado/pensionista, dada uma determinada **Solicitação de Proposta**, será realizado um Leilão onde a melhor Oferta de Crédito será levada adiante. 

:::warning Atenção
Será aceito somente uma única **Proposta** por **Solicitação de Proposta** - possibilidando apenas a alteração da mesma, conforme interesse do parceiro.
:::

## Definição do Objeto Proposal

Todas as trocas de informação de uma **Proposal** utilizam a seguinte definição para este objeto. Em alguns casos, para facilitar a implementação e diminuir o fluxo de dados entre as partes, algumas informações poderão ser omitidas.

| Nome                        | Tipo    | Descrição                                                                          |
| --------------------------- | ------- | ---------------------------------------------------------------------------------- |
| proposal_request_key        | string  | Identificador único da **Solicitação de Proposta**. |
| request_control_key         | string  | Chave única de identificação da **Proposal** incluída no formato uuid v4. |
| proposal_data               | object  | Objeto que descreve os dados da **Proposta** enviados pelo paceiro. |
| status                      | string  | Status da **Proposta** (`created`, `bid`, `lost`, `won`, `cancelled`).|
| cet                         | float   | Valor do CET calculado para a proposta **incluída** no Leilão (calculado posteriormente).|
| updated_at                  | string  | Data da inclusão ou atualização da **Proposta** no formato `YYYY-MM-DDTHH:MM:SSZ`.|
| rank_position               | integer | Posição atual da **Proposta** no ranking do Leilão para sua respectiva **Solicitação de Proposta** equivalente.|

*OBS: O conteúdo do objeto `proposal_data` é composto por informações enviadas pelo Participante em requisição descrita posteriormente.*

### Detalhamento dos Status da solicitação de proposta

O status da **Proposta** pode ser:

| Status   | Descrição                                                                 |
|----------| ------------------------------------------------------------------------- |
| created  | **Proposta** foi criada, porém não foi incluída no Leilão da sua respectiva **Solicitação de Proposta** em andamento.  |
| bid      | **Proposta** foi incluída no leilão com suas condições - ainda passível de alterações. |
| lost     | **Proposta** perdeu o Leilão daquela **Solicitação de Proposta**. O Leilão foi encerrado sem a inclusão desta **Proposta**.  |
| won      | **Proposta** ganhou o Leilão daquela **Solicitação de Proposta**. O Leilão foi encerrado com a inclusão desta **Proposta**.  |
| cancelled| **Proposta** cancelada pelo participante.  |

## Aceitando uma Solicitação de Proposta e Criando uma Proposta

Para aceitar a **Solicitação de Proposta** criada pelo beneficiário e conseguir consultar os seus dados completos, realize uma chamada via **API** com o ***ID*** recebido da **Solicitação de Proposta** via Webhook automático ou consulta posterior, conforme o exemplo abaixo:

ENDPOINT - `/social_security_auction/proposal_request/{proposal_request_key}/proposal`
MÉTODO - `POST`

### Path Params

| Campo         | Tipo   | Descrição                              | Caracteres | Obrigatório |
|---------------|--------|----------------------------------------|------------| ----------- |
| `proposal_request_key` | uuidv4 | Chave única de identificação da **ProposalRequest** utilizada no formato uuid v4. | 36         | Sim         |

### Response

STATUS - 201 (Created)

Response Body: Proposta criada

```json
{"request_control_key": "814e7ed3-4080-4cae-a853-8e12812817ea"}
```

### Response Body Params 

| Campo         | Tipo   | Descrição                              | Caracteres | Obrigatório |
|---------------|--------|----------------------------------------|------------| ----------- |
| `request_control_key` | uuidv4 | Chave única de identificação da **Proposal** incluída no formato uuid v4. | 36         | Sim         |

## Incluindo uma Proposta no leilão

Para efetivamente **incluir** ou **atualizar** sua proposta no **Leilão de Crédito**, realize uma chamada via **API** com os dados pertinentes da **Proposta** conforme o exemplo abaixo:

ENDPOINT - `/social_security_auction/proposal_request/{proposal_request_key}/proposal/{request_control_key}`
MÉTODO - `PATCH`

Request Body: Incluindo uma Proposal no leilão

```json
{
    "disbursed_issue_amount": 15000,
    "monthly_interest_rate": 0.04252764,
    "installment_face_value": 400.00,
    "number_of_installments": 48,
    "contacts": [
        {
            "contact_type": "email",
            "contact": "exemplo@qitech.com.br"
        },
        {
            "contact_type": "phone",
            "contact": "5511999999999"
        }
    ],
    "expiration_datetime": "YYYY-MM-DDTHH:MM:SSZ"
}
```

:::warning Atenção
Para os campos **monthly_interest_rate** e **installment_face_value** APENAS 1 destes 2 campos devem ser informados na requisição. O outro não precisa estar incluído dentro do Payload enviado, caso esteja, deve-se colocar valor nulo.
:::

### Body Params

| Campo         | Tipo   | Descrição                              | Obrigatório |
|---------------|--------|----------------------------------------|------------|
| `disbursed_issue_amount`| float  | Valor de desembolso pretendido pela **Proposta**.                                                           | Sim         |
| `monthly_interest_rate` | float  | Taxa de juros mensal da **Proposta** no intervalo de 0 a 1 (0% a 100%, respectivamente).                    | Não         |
| `installment_face_value`| float  | Valor da parcela pretendida pela **Proposta**.                                                              | Não         |
| `number_of_installments`| integer| Número de parcelas da proposta.                                                                             | Sim         |
| `contacts`              | array  | Lista de contatos da **Proposta** que será enviado ao beneficiário                                          | Sim         |
| `contacts.contact_type` | string | Tipo de canal de contato registrado na **Proposta**. Os possíveis valores são `email`, `phone` e `website`. | Sim         |
| `contacts.contact`      | string | Contato do parceiro, que será enviado para o beneficiário.                                                  | Sim         |
| `expiration_datetime`   | string | Data de expiração da **Proposta** enviada ao beneficiário, no formato `YYYY-MM-DDTHH:MM:SSZ`                | Sim         |

### Response

STATUS - 202 (Accepted)

Response Body: Proposta criada

```json
{
  "request_control_key": "814e7ed3-4080-4cae-a853-8e12812817ea",
  "status": "bid",
  "rank_position": 2
}
```

### Response Body Params

|         Campo         |  Tipo   | Descrição| 
|-----------------------|---------|----------|
| `request_control_key` | string  | Chave única de identificação da **Proposal** incluída no formato uuid v4. | 
| `status`              | string  | Status da **proposta** |
| `rank_position`       | integer | Posição da proposta no Ranking do Leilão para a sua respectiva **Solicitação de Proposta** |

## Cancelando a Proposta

Caso queira excluir uma Proposta criada ou incluída no Leilão, basta realizar uma chamada via **API**, com os dados pertinentes da **Proposta**:

:::danger Atenção!
Só é possível Criar/Incluir UMA **Proposta** por **Solicitação de Proposta**. Dado ao caráter dinâmico do Leilão, caso cancele sua **Proposta** não é possível voltar atrás e/ou incluir uma nova para esta mesma **Solicitação de Proposta**.
:::

ENDPOINT - `/social_security_auction/proposal_request/{proposal_request_key}/proposal/{request_control_key}/cancel`
MÉTODO - `PUT`

| Campo         | Tipo   | Descrição                              | Caracteres | Obrigatório |
|---------------|--------|----------------------------------------|------------| ----------- |
| `proposal_request_key` | uuidv4 | Chave única de identificação da **ProposalRequest** utilizada no formato uuid v4. | 36         | Sim         |
| `request_control_key`  | uuidv4 | Chave única de identificação da **Proposal** incluída no formato uuid v4.         | 36         | Sim         |

### Response

STATUS - 202 (Accepted)

Response Body: Proposta cancelada

```json
{
  "request_control_key": "814e7ed3-4080-4cae-a853-8e12812817ea",
  "status": "cancelled"
}
```

### Response Body Params

|         Campo         |  Tipo   | Descrição| 
|-----------------------|---------|----------|
| `request_control_key` | string  | Chave única de identificação da **Proposal** incluída no formato uuid v4. | 
| `status`              | string  | Status da **proposta** |

## Consultando a Proposta

Caso queira consultar a sua **Proposta**, basta apenas realizar uma chamada via **API** utilizando o ***ID*** retornado na hora da criação da Proposta:

ENDPOINT - `/social_security_auction/proposal/{request_control_key}`
MÉTODO - `GET`

### Path Params

| Campo         | Tipo   | Descrição                              | Caracteres | Obrigatório |
|---------------|--------|----------------------------------------|------------| ----------- |
| `request_control_key`  | uuidv4 | Chave única de identificação da **Proposal** incluída no formato uuid v4. | 36         | Sim         |

### Response

STATUS - 200

Response Body: Consulta da Proposta Incluída no Leilão

```json
{
    "proposal_request_key": "94340718-e90b-4641-b34b-7966297e49c4",
    "status": "bid",
    "request_control_key": "814e7ed3-4080-4cae-a853-8e12812817ea",
    "proposal_data": {
        "contacts": [
            {
                "contact": "exemplo@qitech.com.br",
                "contact_type": "email"
            },
            {
                "contact": "5511999999999",
                "contact_type": "phone"
            }
        ],
        "simulation": {
            "cet": 0.0019,
            "annual_cet": 0.023647,
            "iof_amount": 462.04,
            "issue_amount": 15539.74,
            "disbursed_issue_amount": 15000,
            "prefixed_interest_rate": {
                "daily_rate": 0.00001417,
                "annual_rate": 0.00511527,
                "monthly_rate": 0.00042528,
                "interest_base": "calendar_days"
            },
            "installments_face_value": 327.04
        },
        "expiration_datetime": "YYYY-MM-DDTHH:MM:SSZ",
        "monthly_interest_rate": 0.04252764,
        "disbursed_issue_amount": 15000,
        "number_of_installments": 48
    },
    "cet": 0.0019,
    "updated_at": "YYYY-MM-DDTHH:MM:SSZ",
    "rank_position": 1
}
```

Response Body: Consulta da Proposta Criada e não incluida no Leilão

```json
{
    "proposal_request_key": "94340718-e90b-4641-b34b-7966297e49c4",
    "status": "created",
    "request_control_key": "01a7a1bf-b75b-4526-bbc3-a27e85e14325"
}
```

*OBS: O detalhamento dos campos devolvidos no `Response Body` estão descritos na definição do Objeto Proposal acima.*

## Status HTTP

A API de assinatura utilizam a seguinte padronização nos status HTTP de retorno, de acordo com o RFC 7231 :

| Status HTTP | Significado           | Descrição                                                                                                                                                                       |
| ----------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400         | Bad Request           | A requisição enviada possui algum erro de formatação. Na maioria dos casos, retornamos no corpo da mensagem uma explicação de onde está o erro.                                 |
| 401         | Unauthorized          | Houve algum problema na autenticação, verifique se a API Key está correta e no header correto, de acordo com a seção <a href='#autenticacao'>Autenticação</a>.                  |
| 403         | Forbidden             | O endpoint acessado é de uso interno e não está disponível para esta API Key.                                                                                                   |
| 404         | Not Found             | O dado requisitado não foi encontrado usando a chave utilizada. Este status também é retornado quando um endpoint inválido é requisitado.                                       |
| 405         | Method Not Allowed    | O método HTTP utilizado não se aplica ao endpoint utilizado.                                                                                                                    |
| 406         | Not Acceptable        | Os dados enviados no corpo da requisição são inválidos. Em geral, isso significa que os dados enviados não são um JSON válido.                                                  |
| 409         | Conflict              | O id da requisição corresponde a um id já processado anteriormente. Este status é retornado no caso de requisições duplicadas enviadas ao servidor.                             |
| 500         | Internal Server Error | Tivemos um problema para processar esta requisição, ao encontrarmos esse erro nossos especialistas são automaticamente notificados e iniciam a análise e solução imediatamente. |
| 503         | Service Unavailable   | Você se deparou com uma indisponibilidade, planejada ou não, de infraestrutura dos nossos servidores.                                                                           |

---

# Portabilidade Out - Evidências de rentenção

URL: /documentation/manual_portabilidade/evidencias_de_retencao

# Evidências de Retenção

:::info Objetivo
Para efetivar a retenção de um contrato atacado por portabilidade, é **obrigatório** o envio de evidências que comprovem:
1. A realização do contato com o tomador;
2. O aceite explícito do tomador em relação à retenção.
:::

## 1. Coleta das Evidências

As evidências podem ser coletadas via mensagem (WhatsApp, Chat), e-mail ou ligação gravada. Independentemente do canal, a interação deve seguir estritamente os roteiros (scripts) de atendimento listados abaixo para cada motivo de retenção.

### 1.1 Caso haja refinanciamento

Utilize este roteiro quando a retenção for realizada mediante uma oferta de refinanciamento do contrato atual.

```text title="Script - Retenção com Refinanciamento"

Sr. (a) XXXXX, com final de CPF XXX-XX, conforme sua aprovação, na data de hoje XX/XX/XXXX,
estamos cancelando a sua solicitação(ões) de portabilidade de número(s) final(is) XXXX, efetuada pelo Banco XX, 
referente ao(s) contratos finais XXXX  mediante a oferta de refinanciamento.
O Sr.(a) confirma? 

SIM / OK / CONFIRMO
```

### 1.2 Caso NÃO haja refinanciamento
Utilize este roteiro quando a retenção for realizada mantendo as condições originais, sem refinanciamento.

```text title="Script - Retenção sem Refinanciamento"

Sr. (a) XXXXX, com final de CPF XXX-XX, conforme sua aprovação, na data de hoje XX/XX/XXXX,
estamos cancelando a sua solicitação(ões) de portabilidade de número(s) final(is) XXXX, efetuada pelo Banco XX, 
referente ao(s) contratos finais XXXX  mantendo-o junto ao [NOME DA IF].
O Sr.(a) confirma? 

SIM / OK / CONFIRMO
```

### 1.3 Quando o cliente NÃO SOLICITOU a portabilidade
Utilize este roteiro quando o cliente informa que não reconhece a solicitação de portabilidade.

```text title="Script - Ataque indevido"

Sr. (a) XXXXX, com final de CPF XXX-XX, conforme sua aprovação, na data de hoje XX/XX/XXXX, 
estamos cancelando a sua solicitação(ões) de portabilidade de número(s) final(is) XXXX, 
efetuada pelo Banco XX  sem o seu consentimento, referente ao(s) contratos finais XXXX  mantendo-o junto ao [NOME DA IF]. 
O Sr.(a) confirma? 

SIM / OK / CONFIRMO
```

---

# Portabilidade Out

URL: /documentation/manual_portabilidade/portabilidade_out

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

## 1. Notificação de recebimento de portabilidade out

Assim que uma solicitação de portabilidade for recepcionada pela QI SCD via CTC (Central de Transferência de Crédito), o parceiro será notificado através do seguinte webhook:

WEBHOOK_TYPE credit_transfer.received_portability
STATUS Received

Webhook Body

```json
{
    "webhook_type": "credit_transfer.received_portability",
    "received_portability_status": "received", 
    "key": "673d2872-c6c9-4075-b9ab-4525bcbe4aa1",
    "event_datetime": "2022-07-24T18:29:45",  
    "data": {
        "annual_interest_rate": "20.27",
        "annual_effective_interest_rate": "20.27",
        "number_of_installments": "6",
        "installment_face_value": "201.71",
        "phone_number": "(05)541997558",
        "address": {
            "street": "Rua Longe de Casa",
            "city": "Rio de Janeiro",
            "state": "RJ",
            "number": "112",
            "postal_code": "38300569"
        },
        "due_balance": "1000",
        "due_balance_date": "2022-07-29",
        "issuer_name": "A Random Name",
        "issuer_document_number": "37197645832",
        "reference_date": "2022-08-01",
        "contract_number": "0000049045/UO",
        "origin_credit_operation_key": "7daef1ad-5497-4ec3-92f4-26f8d63bcd80",
        "retention_limit_date": "2022-08-03", 
        "due_balance_limit_date": "2022-08-08", 
        "portability_number": "202207150000001642808",
        "corban_document_number": "08289470514408",
        "source_ispb_number": "0"
    }
}
```

Confira a descrição dos campos na tabela [Detalhamento do webhook received_portability](#received_portability)

## 2. Resposta ao ataque de portabilidade

### 2.1. Retenção de contrato

:::warning Reenvio de Webhooks
Para realizar a retenção do cliente, o parceiro deve realizar o **[upload](../upload_de_documentos)** das **[evidências de retenção](./evidencias_de_retencao)** e anexá-las à operação até às 18:00 horas do 4° dia útil após o recebimento do evento de ataque (_**credit_transfer.received_portability**_).
:::

ENDPOINT /credit_transfer/received_portability/ [received_portability_key]
MÉTODO PATCH

Testar no Playground

```json title='Request Body
{
  "received_portability_status": "retained",
  "retention_reason": "issuer_retention",
  "document_type": "received_portability_retention_proof",
  "documents": [
    {
      "file_type": "jpeg",
      "document_key": "3d6fbbbf-55e9-4275-8050-b83b33fdefa6",
      "retention_type": "whatsapp"
    }
  ]
}
```
:::danger Atenção
**NÃO serão aceitos arquivos COMPRIMIDOS.**
:::

Consulte o descritivo dos campos da requisição na tabela [Detalhamento do objeto authorization_term](#authorization_term).

### 2.2 Aprovação de portabilidade out

Caso o cliente não seja retido o parceiro deve informar sobre a não retenção até as 10:00 do 4o. dia útil após o recebimento da notificação de ataque de portabilidade (_**credit_transfer.received_portability**_).

:::danger Atenção
**Caso a solicitação de portabilidade não seja respondida em até 4 dias úteis, a QI Tech retornará o saldo devedor da operação ao proponente (solicitante da portabilidade).**
:::

ENDPOINT /credit_transfer/received_portability/ [received_portability_key]
MÉTODO PATCH

Testar no Playground

```json title='Request Body'
{
	"received_portability_status": "accepted_by_creditor"
}
```

## 3. Consultando solicitações de portabilidade out

### 3.1. Consulta de solicitação de portabilidade

Para verificar os possíveis status da 

ENDPOINT /credit_transfer/received_portability/ [received_portability_key]
MÉTODO GET

Testar no Playground

Response Body

```json
{
	"received_portability_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036",
	"received_portability_status": "accepted",
	"annual_interest_rate": "20.27",
	"annual_effective_interest_rate": "20.27",
	"number_of_installments": "6",
	"installment_face_value": "201.71",
	"phone_number": "(05)541997558",
	"address": {
		"street": "Rua Longe de Casa",
		"city": "Rio de Janeiro",
		"state": "RJ",
		"number": "112",
		"postal_code": "38300569"
	},
	"due_balance": 1000,
	"due_balance_date": "2022-07-29",
	"issuer_name": "A Random Name",
	"issuer_document_number": "37197645832",
	"reference_date": "2022-08-01",
	"contract_number": "0000049045/UO",
	"origin_credit_operation_key": "key",
	"retention_limit_date": "2022-08-03",
	"due_balance_limit_date": "2022-08-08",
	"portability_number": "202207150000001642808",
	"retention_reason": null,
	"canceled_reason": null,
  "corban_document_number": "08289470514408",
  "attached_documents": [
    ],
  "financial_institution_code_number": "001",
  "financial_institution_name": "Banco do Brasil",
  "ispb": "00000000",
  "requester_key": "8511012c-3a3c-4f4d-9f23-dbe437211a8e",
  "requester_name": "Corban LTDA",
  "response_date": null,
  "settlement_date": null,
  "settlement_due_balance": null
}
```

### 3.2. Listar solicitação de portabilidade

ENDPOINT /credit_transfer/received_portability
MÉTODO GET
PARÂMETROS settlement_date, max_portability_date, due_balance_limit_date, received_portability_status, portability_number, contract_number, credit_operation_key

Testar no Playground

Response Body

```json
{
	"data": [{
		"received_portability_key": "e3bedf31-1e87-4ba4-a36c-d52f7f5c9036",
		"received_portability_status": "accepted",
		"annual_interest_rate": 1,
		"annual_effective_interest_rate": 1,
		"number_of_installments": 6,
		"installment_face_value": 201.71,
		"phone_number": "(05)541997558",
		"address": {
			"street": "Rua Longe de Casa",
			"city": "Rio de Janeiro",
			"state": "RJ",
			"number": "112",
			"postal_code": "38300569"
		},
		"due_balance": 1000,
		"due_balance_date": "2022-07-29",
		"issuer_name": "A Random Name",
		"issuer_document_number": "37197645832",
		"reference_date": "2022-08-01",
		"contract_number": "0000049045/UO",
		"origin_credit_operation_key": "key",
		"retention_limit_date": "2022-08-03",
		"due_balance_limit_date": "2022-08-08",
		"portability_number": "202207150000001642808",
		"retention_reason": null,
		"canceled_reason": null
	}],
	"pagination": {
		"next_page": null,
		"current_page": 1,
		"total_rows": 0,
		"rows_per_page": 1,
		"total_pages": 0
	}
}
```

## 4. Webhooks

A seguir estão os possíveis webhooks recebidos durante o fluxo, a [máquina de estados](#state-machine) pode ser consultada para verificar as possíveis alterações de status (o status de canceled_by_proponent pode ser alcançado a partir de qualquer status não final)

### 4.1. Aguardando pagamento do saldo devedor

WEBHOOK_TYPE credit_transfer.received_portability
STATUS waiting_settlement

```json title='Webhook Body'
{
  "webhook_type": "credit_transfer.received_portability",

  "received_portability_key": "673d2872-c6c9-4075-b9ab-4525bcbe4aa1",
  "received_portability_status": "waiting_settlement",
  "event_datetime": "2022-07-24T18:29:45",
  "data": {
    "settlement_due_balance": 120.00,
    "settlement_date": "2022-08-02"
  }
}
```

### 4.2. Proposta cancelada pelo proponente

WEBHOOK_TYPE credit_transfer.received_portability
STATUS canceled_by_proponent

```json title='Webhook Body'
{
  "webhook_type": "credit_transfer.received_portability",
  "received_portability_key": "673d2872-c6c9-4075-b9ab-4525bcbe4aa1",
  "received_portability_status": "canceled_by_proponent",
  "event_datetime": "2022-07-24T18:29:45",
  "data": {}
}
```

### 4.3. Portabilidade liquidada

WEBHOOK_TYPE credit_transfer.received_portability
STATUS settled

```json title='Webhook Body'
{
  "webhook_type": "credit_transfer.received_portability",
  "received_portability_key": "673d2872-c6c9-4075-b9ab-4525bcbe4aa1",
  "received_portability_status": "settled",
  "event_datetime": "2022-07-24T18:29:45Z",
  "data": {}
}
```

### 4.4. Portabilidade não liquidada

Caso o proponente não realiza o pagamento do saldo devedor retornado na resposta da portabilidade out (ataque de portabilidade), a proposta será cancelada por falta de pagamento dentro do prazo.

WEBHOOK_TYPE credit_transfer.received_portability
STATUS canceled_by_creditor

```json title='Webhook Body'
{
  "webhook_type": "credit_transfer.received_portability",
  "received_portability_key": "673d2872-c6c9-4075-b9ab-4525bcbe4aa1",
  "received_portability_status": "canceled_by_creditor",
  "event_datetime": "2022-07-24T18:29:45",
  "data": {
   "canceled_reason": {
    "enumerator": "not_paid",
    "description": "Decurso de prazo por STR não paga dentro do prazo"
   }
  }
}
```
## 5. Mocks para validação em sandbox

:::info Ambiente Sandbox
Utilize estes endpoints para simular o fluxo de portabilidade out no sandbox sem depender de eventos reais do CTC/STR.
:::

:::danger Aviso Importante!
Não utilize dados pessoais reais (CPF, CNPJ, etc.) em ambientes sandbox.
:::

### 5.1. Simular portabilidade recebida

Ao chamar este endpoint, você receberá o webhook `credit_transfer.received_portability` (descrito na [seção 1](#1-notificação-de-recebimento-de-portabilidade-out)) com os dados calculados a partir da operação de crédito informada.

ENDPOINT /mock/credit_transfer/received_portability
MÉTODO POST

#### Atributos

credit_operation_key
string (UUID)
obrigatório
Chave da operação de crédito a ser portada.

reference_date
string
obrigatório
Data de referência para a portabilidade (formato `YYYY-MM-DD`).

ispb_number
string
obrigatório
Número ISPB da instituição de origem (máx. 8 caracteres).

origin_contract_type
string
opcional
Tipo do contrato de origem. Valores permitidos: `payroll`, `public_agency`. Padrão: `payroll`.

proposal_type
string
opcional
Tipo da proposta. Valores permitidos: `inss`. Padrão: `inss`.

```json title='Request Body'
{
  "credit_operation_key": "3571e292-3a83-4011-904d-20ee963022ef",
  "reference_date": "2026-04-13",
  "ispb_number": "00000000",
  "origin_contract_type": "payroll",
  "proposal_type": "inss"
}
```

```json title='Response — 202 Accepted'
{}
```

### 5.2. Simular liquidação STR

Após aprovar a portabilidade ([seção 2.2](#22-aprovação-de-portabilidade-out)) e receber o webhook `waiting_settlement` ([seção 4.1](#41-aguardando-pagamento-do-saldo-devedor)), utilize este endpoint para simular a liquidação ou rejeição do pagamento via STR. O webhook correspondente (`settled` ou `canceled_by_creditor`) será disparado conforme o `event_type` escolhido.

ENDPOINT /mock/credit_transfer/str
MÉTODO POST

#### Atributos

proposal_key
string (UUID)
obrigatório
Chave da proposta (retornada no webhook `waiting_settlement`).

event_type
string
obrigatório
Tipo do evento. Valores permitidos: `settlement`, `payment_rejected`.

source_branch
string
opcional
Código da agência de origem. Padrão: `"0001"`.

target_branch
string
opcional
Código da agência de destino. Padrão: `"0001"`.

provider_ispb
string
opcional
Número ISPB do provedor. Padrão: `"99999999"`.

```json title='Request Body (settlement)'
{
  "proposal_key": "9ff557c3-b640-4862-b2c1-ef6f7d9a6a61",
  "event_type": "settlement",
  "source_branch": "0001",
  "target_branch": "0001",
  "provider_ispb": "99999999"
}
```

```json title='Response — 202 Accepted'
{}
```

## Anexos
---

### Detalhamento do webhook received_portability {#received_portability}
| Campo                         | Descrição                          | 
|-------------------------      |------------------------------------|
|key                            |Chave do ataque (received_portability_key)                 |
|webhook_type                   |Tipo de evento                                             |
|received_portability_status    |Status do ataque                                           |
|event_datetime                 |Data do evento                                             |
|annual_interest_rate           |Taxa informada no ataque                                   |
|annual_effective_interest_rate |CET informado no ataque                                    |
|number_of_installments         |Quantidade de parcelas informadas no ataque                |
|installment_face_value         |Valor de parcela informado no ataque                       |
|phone_number                   |Número de telefone informado no ataque                     |
|address                        |Endereço informado no ataque                               |
|due_balance                    |Saldo devedor informado no ataque|
|due_balance_date               |Data de referência do saldo devedor informado no ataque|
|issuer_name                    |Nome do tomador informado no ataque|
|issuer_document_number         |Número de documento do tomador informado no ataque|
|reference_date                 |informado no ataque|
|contract_number                |Número de contrato informado no ataque|
|origin_credit_operation_key    |Chave da operação de crédito (DEBT_KEY/CREDIT_OPERATION_KEY)|
|retention_limit_date           |Data limite para retenção|
|due_balance_limit_date         |Data limite para informar o saldo devedor|
|portability_number             |Número da portabilidade (NU)|
|corban_document_number         |informado no ataque|
|source_ispb_number             |informado no ataque|

### Detalhamento do objeto authorization_term {#authorization_term}
| Campo                       | Obrigatoriedade                     | Descrição                          | 
|-------------------------    |-----------------                    |------------------------------------|
|received_portability_status  |Obrigatório                          |Liberação ou não do saldo           |
|retention_reason             |Obrigatório no caso de retenção      |Motivo da rentenção, consulte os possíveis enumeradores na tabela [Motivo de retenção](#retention_reason)|
|document_type                |Obrigatório no caso de retenção      |Necessariamente "received_portability_retention_proof"|
|documents                    |Obrigatório no caso de retenção      |Evidências de retenção|
|file_type                    |Obrigatório no caso de retenção      |Tipo de documento, consulte os possíveis enumeradores na tabela [Tipo de documento](document_type)|
|document_key                 |Obrigatório no caso de retenção      |Chave do documento retornada após feito o [upload](../upload_de_documentos)|
|retention_type               |Obrigatório no caso de retenção      |Tipo de evidência de retenção, consulte os possíveis enumeradores na tabela [Tipos de retenção](#retention_type)|

### Motivo de retenção {#retention_reason}

| Enumerador                               | Descrição                                              |
|------------------------------------------|--------------------------------------------------------|
| **issuer_retention**                     | Retenção do Cliente                                    |
| **portability_not_requested**            | O cliente não solicitou a portabilidade                |

### Tipo de documento {#document_type}

|enumerador  |
|------------|
| **pdf**    |
| **jpeg**   |
| **jpg**    |
| **png**    |
| **mp3**    |
| **wav**    |

:::note
Para evidências de retenção (`retention_type`), apenas os formatos **jpg**, **jpeg**, **png** e **pdf** são aceitos.
:::

### Tipos de retenção {#retention_type}

|enumerador      |
|----------------|
| **sms**        |
| **whatsapp**   |

### Status do ataque {#received_portability_status}

| Enumerador                   | Descrição                                                |
|------------------------------|----------------------------------------------------------|
| **received**                 | Recebido                                                 |
| **waiting_validation**       | Aguardando validação do Documento comprovante da Retenção|
| **canceled_by_proponent**    | Cancelado pelo Proponente                                |
| **canceled_by_creditor**     | Cancelado pelo Credor Original                           |
| **retained**                 | Retido                                                   | 
| **waiting_settlement**       | Portabilidade aprovada esperando liquidação              | 
| **settled**                  | Liquidado                                                |

### Máquina de estados do ataque {#state-machine}

![Máquina de estados do ataque de portabilidade](/img/diagrams/manual-portabilidade-portabilidade-out.svg)

---

# QI Cartões - Pré-pago

URL: /documentation/manual_pre_pago/casos_uso

## Casos de Uso

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

---

Para facilitar o entendimento, o cliente de BaaS que irá emitir e fornece o serviço de cartões para seus clientes será tratado como "Cliente". O cliente final portador do cartão emitido será tratado com "Portador".

## 1. Autorização e confirmação completa de uma transação

Este é o caminho mais comum para as transações de cartão, o Portador passa seu cartão para uma transação de valor financeiro X e a adquirente captura exatamente este valor do emissor do cartão. O processo inicia com o Portador utilizando seu cartão em um POS. A autorização será recebida pela QI e uma autorização será solicitada ao cliente conforme descrito na [Requisição de Autorização](/documentation/cards/autorizacao/). O cliente então, faz suas validações e opta por responder a requisção informando um parecer *autorization_request_response* = authorized.

O [Objeto Autorização](/documentation/cards/search/buscar_autorizacao) pode ser detalhado [nesta](/documentation/cards/search/buscar_autorizacao) referência.

A QI irá responder a autorização para a rede de cartões e o Portador irá ter seu saldo em conta descontado do valor da transação.

Neste momento, será enviado um webhook referenciando a autorização que acaba de ser aprovada.

Webhook de autorização autorizada

```json
{
	"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"data": {
		"merchant_currency_code": "BRL",
		"merchant_amount": 25,
		"billing_currency_code": "BRL",
		"billing_amount": 25,
		"processing_datetime": "2023-07-24T12:00:00.000Z",
		"authorization_event_type": "authorization",
		"authorization": {Objeto da Autorização}
	},
	"webhook_type": "prepaid_card.authorization_event",
	"event_datetime": "2023-07-24T12:00:00.000Z"
}
```

A adquirente, após ter uma transação autorizada, realiza a captura deste valor. Essa captura é processada pela QI e um webhook de atualização de estado da autorização é enviado passando essa transação para o estado *completed*. O valor capturado pode ser consultado na variável *captured_amount* do objeto `Authorization`.

Webhook de autorização confirmada

```json
{
	"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"data": {
		"merchant_currency_code": "BRL",
		"merchant_amount": 25,
		"billing_currency_code": "BRL",
		"billing_amount": 25,
		"processing_datetime": "2023-07-24T12:00:00.000Z",
		"authorization_event_type": "capture",
		"authorization": {Objeto da Autorização}
	},
	"webhook_type": "prepaid_card.authorization_event",
	"event_datetime": "2023-07-24T12:00:00.000Z"
}
```

## 2. Autorização e confirmação a menor de uma transação

Neste caso, a adquirente captura um valor menor do que o valor estipulado na autorização. O processo inicia com o Portador utilizando seu cartão em um POS. A autorização será recebida pela QI e uma autorização será solicitada ao cliente conforme descrito na [Requisição de Autorização](/documentation/cards/autorizacao/). O cliente então, faz suas validações e opta por responder a requisição informando um parecer *autorization_request_response* = authorized.

A QI irá responder a autorização para a rede de cartões e o Portador irá ter seu saldo em conta descontado do valor da transação.

Neste momento, será enviado um webhook referenciando a autorização que acaba de ser aprovada.

Webhook de autorização autorizada

```json
{
	"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"data": {
		"merchant_currency_code": "BRL",
		"merchant_amount": 25,
		"billing_currency_code": "BRL",
		"billing_amount": 25,
		"processing_datetime": "2023-07-24T12:00:00.000Z",
		"authorization_event_type": "authorization",
		"authorization": {Objeto da Autorização}
	},
	"webhook_type": "prepaid_card.authorization_event",
	"event_datetime": "2023-07-24T12:00:00.000Z"
}
```

A adquirente, após ter uma transação autorizada, realiza a captura deste valor. Essa captura é processada pela QI e um webhook de atualização de estado da autorização é enviado passando essa autorização para o estado *completed*. O valor capturado pode ser consultado na variável *captured_amount* do objeto `Authorization`. 

Webhook de autorização confirmada a menor

```json
{
	"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"data": {
		"merchant_currency_code": "BRL",
		"merchant_amount": 23,
		"billing_currency_code": "BRL",
		"billing_amount": 23,
		"processing_datetime": "2023-07-24T12:00:00.000Z",
		"authorization_event_type": "capture",
		"authorization": {Objeto da Autorização}
	},
	"webhook_type": "prepaid_card.authorization_event",
	"event_datetime": "2023-07-24T12:00:00.000Z"
}
```

Caso a autorização expire sem ter seu valor total capturado, o excedente será creditado em conta para o Portador no valor da diferença pendente.

## 3. Autorização e confirmação a maior de uma transação

Neste caso, a adquirente captura um valor maior do que o valor estipulado na autorização. O processo inicia com o Portador utilizando seu cartão em um POS. A autorização será recebida pela QI e uma autorização será solicitada ao cliente conforme descrito na [Requisição de Autorização](/documentation/cards/autorizacao/). O cliente então, faz suas validações e opta por responder a requisção informando um parecer *autorization_request_response* = authorized.

A QI irá responder a autorização para a rede de cartões e o Portador irá ter seu saldo em conta descontado do valor da transação.

Neste momento, será enviado um webhook referenciando a transação que acaba de ser autorizada.

Webhook de autorização autorizada

```json
{
	"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"data": {
		"merchant_currency_code": "BRL",
		"merchant_amount": 25,
		"billing_currency_code": "BRL",
		"billing_amount": 25,
		"processing_datetime": "2023-07-24T12:00:00.000Z",
		"authorization_event_type": "authorization",
		"authorization": {Objeto da Autorização}
	},
	"webhook_type": "prepaid_card.authorization_event",
	"event_datetime": "2023-07-24T12:00:00.000Z"
}
```

A adquirente, após ter uma transação autorizada, realiza a captura deste valor. Essa captura é processada pela QI e um webhook de atualização de estado da autorização é enviado passando essa autorização para o estado *completed*. O valor capturado pode ser consultado na variável *captured_amount* do objeto `Authorization`. Neste caso de uso, o valor capturado será maior do que o valor original autorizado.

Webhook de autorização confirmada a maior

```json
{
	"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"data": {
		"merchant_currency_code": "BRL",
		"merchant_amount": 27,
		"billing_currency_code": "BRL",
		"billing_amount": 27,
		"processing_datetime": "2023-07-24T12:00:00.000Z",
		"authorization_event_type": "capture",
		"authorization": {Objeto da Autorização}
	},
	"webhook_type": "prepaid_card.authorization_event",
	"event_datetime": "2023-07-24T12:00:00.000Z"
}
```

Esta situação produzirá um débito em conta para o Portador no valor da diferença a maior, neste exemplo seria debitado R$ 2,00 na QI Conta do Portador. Caso não seja possível realizar esse débito em nenhuma instância a QI irá tratar particularmente esses casos junto ao cliente (Cliente de BaaS utilizando serviço de cartões da QI).

### Cancelamento parcial

Ainda nesta situação de confirmação a maior, a adquirente pode decidir corrigir o eventual engano enviano o reembolso total `refund` ou parcial `partial_refund` que serão representados na forma de eventos de autorização. Abaixo um exemplo de reembolso parcial dos R$2,00 cobrados indevidamente.

Webhook de autorização com reembolso parcial

```json
{
	"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"data": {
		"merchant_currency_code": "BRL",
		"merchant_amount": 2,
		"billing_currency_code": "BRL",
		"billing_amount": 2,
		"processing_datetime": "2023-07-24T12:00:00.000Z",
		"authorization_event_type": "partial_refund",
		"authorization": {Objeto da Autorização}
	},
	"webhook_type": "prepaid_card.authorization_event",
	"event_datetime": "2023-07-24T12:00:00.000Z"
}
```

## 4. Autorização e cancelamento de uma transação

Neste caso, a transação é autorizada mas por algum motivo o vendedor decide cancelar essa transação no POS antes que ela seja capturada. O processo inicia com o Portador utilizando seu cartão em um POS. A autorização será recebida pela QI e uma autorização será solicitada ao cliente conforme descrito na [Requisição de Autorização](/documentation/cards/autorizacao/). O cliente então, faz suas validações e opta por responder a requisção informando um parecer *approve* = true.

A QI irá responder a autorização para a rede de cartões e o Portador irá ter seu saldo em conta descontado do valor da transação.

Neste momento, será enviado um webhook referenciando a transação que acaba de ser autorizada

Webhook de transação autorizada

```json
{
	"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"data": {
		"merchant_currency_code": "BRL",
		"merchant_amount": 25,
		"billing_currency_code": "BRL",
		"billing_amount": 25,
		"processing_datetime": "2023-07-24T12:00:00.000Z",
		"authorization_event_type": "authorization",
		"authorization": {Objeto da Autorização}
	},
	"webhook_type": "prepaid_card.authorization_event",
	"event_datetime": "2023-07-24T12:00:00.000Z"
}
```

A vendedor, após ter uma transação autorizada, decide cancelar essa transação por algum motivo, um erro de digitação por exemplo. Esse mensagem de cancelamento é processada pela QI e um webhook de atualização de estado da transação é enviado passando essa transação para o estado de estornada *reversed*. Nesta situação, o valor total da autorização foi cancelado.

Webhook de autorização estornada

```json
{
	"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"data": {
		"merchant_currency_code": "BRL",
		"merchant_amount": 27,
		"billing_currency_code": "BRL",
		"billing_amount": 27,
		"processing_datetime": "2023-07-24T12:00:00.000Z",
		"authorization_event_type": "authorization_reversal",
		"authorization": {Objeto da Autorização}
	},
	"webhook_type": "prepaid_card.authorization_event",
	"event_datetime": "2023-07-24T12:00:00.000Z"
}
```

Nesta situação um crédito no valor total cancelado é feito na Qi Conta do Portador.

### Autorização expirada

Pode ocorrer que uma autorização seja aprovada, mas não seja capturada dentro dos prazos estipulados pela bandeira do cartão. Nesta situação, será enviado um webhook de autorização expirada e o um crédito no valor não capturado será feito na Qi Conta do portador.

Webhook de autorização expirada

```json
{
	"key": "cccbd9e9-863f-44b5-aa05-f6afa555bb74",
	"data": {
		"merchant_currency_code": "BRL",
		"merchant_amount": 25,
		"billing_currency_code": "BRL",
		"billing_amount": 25,
		"processing_datetime": "2023-07-24T12:00:00.000Z",
		"authorization_event_type": "authorization_expiration",
		"authorization": {Objeto da Autorização}
	},
	"webhook_type": "prepaid_card.authorization_event",
	"event_datetime": "2023-07-24T12:00:00.000Z"
}
```

---

# Manual Previdência Privada - Averbação e Desembolso

URL: /documentation/manual_previdencia_privada/manual_previdencia_privada_averbacao_desembolso

:::info Navegação
- [Crédito Novo](/documentation/manual_previdencia_privada/manual_previdencia_privada_credito_novo) (anterior)
:::

:::caution API em desenvolvimento
A API ainda está em fase de desenvolvimento, sendo assim, este manual está sujeito a alterações.
:::

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeados de forma estrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

## 1 - Averbação

### Webhooks

Em caso de sucesso na averbação o parceiro receberá o seguinte webhook:

WEBHOOK TYPE
credit_operation.collateral

STATUS
Opened

**Webhook Body**

```json
{
  "webhook": {
    "key": "<Debt Key>",
    "data": {
      "collateral_data": "collateral_data": {
            "total_gross_amount_lock": 1500,
            "investment_funds": [
                {
                    "susep_process_number": "111111111111",
                    "certificate": "12345678",   
                    "name": "QI Fund Alpha",
                    "document_number": "32402502000135",
                    "class": "",
                    "subclass": "",
                    "lock_gross_amount": 500,
                },
                {
                    "susep_process_number": "222222222222",
                    "certificate": "87654321",
                    "name": "QI Fund Beta",
                    "document_number": "32402502000135",
                    "class": "",
                    "subclass": "",
                    "lock_gross_amount": 500,
                },
                {
                    "susep_process_number": "333333333333",
                    "certificate": "56781234",  
                    "name": "QI Fund Gama",
                    "document_number": "32402502000135",
                    "class": "",
                    "subclass": "",
                    "lock_gross_amount": 500,
                }
            ]
        },
      "collateral_type": "private_pension",
      "collateral_constituted": true
    },
    "event_time": "2025-07-10 02:15:01",
    "webhook_type": "credit_operation.collateral"
  }
}
```

### Falha na averbação
Se uma reserva falhar, será enviado um webhook no seguinte formato para informar o ocorrido:

WEBHOOK TYPE
private_pension_failed_reservation

STATUS
Failed

**Webhook Body**

```json title="Webhook Body"
{
    "key": "<Debt Key>",
    "status": "failed",
    "webhook_type": "private_pension_failed_reservation",
    "event_datetime": "2025-10-26 16:41:28",
    "data": {
        "enumerator": "Fail enumerator.",
        "description": "Descrição da falha.",
    }
}
```

## 2 - Desaverbação

A desaverbação de um contrato é realizada através da rota de cancelamento permanente. Essa rota coloca um status final
no contrato, o qual não é passível de retentativa e dispara a desaverbação da margem averbada.

Para realizar o cancelamento definitivo, deve ser utilizado o seguinte endpoint:

**POST**
/debt/ DEBT-KEY /cancel_permanently

Testar no Playground

### Webhooks

WEBHOOK TYPE
debt

STATUS
canceled_permanently

**Webhook Body**

```json
{
    "key": "<Debt Key>",
    "status": "canceled_permanently",
    "webhook_type": "debt",
    "event_datetime": "2025-03-18 16:41:28",
    "data": {}
}
```

## 3 - Falha no desembolso

### TED
Em caso de falha no desembolso via TED

WEBHOOK TYPE
debt

STATUS
canceled

**Webhook Body**

```json
 {
     "key": "<Debt Key>",
     "status": "canceled",
     "webhook_type": "debt",
     "event_datetime": "2025-03-18 16:41:28",
     "data": {
         "ted_refusal": {
             "transaction_key": "16faabfc-3876-437d-a4f6-aae17a1d68c9",
             "description": "341 0000 000000-7 12345678900 - NOME DO EMPREGADO",
             "origin": {
                 "account_key": "a1d2dea5-fa90-4676-a125-da355fdc3ed0",
                 "account_number": "00086",
                 "bank_code": "329",
                 "name": "ACCOUNT TRANSITORY",
                 "type": "payment_account",
                 "document": "32402502000135",
                 "branch_digit": null,
                 "account_digit": "8",
                 "branch": "0001"
             },
             "fee": 0,
             "reason_enumerator": "agencia_conta_invalida",
             "timestamp": "2022-11-07T14:36:05",
             "amount": 483.6,
             "reason": "Agência ou Conta Destinatária do Crédito Inválida",
             "destination": {
                 "branch": "0000",
                 "account_number": "000000",
                 "name": "NOME DO EMPREGADO",
                 "purpose": "Crédito em Conta",
                 "type": "checking_account",
                 "branch_digit": null,
                 "document": "12345678900",
                 "bank_code": "341",
                 "account_digit": "7"
             }
         },
         "cancel_reason": "ted_refusal"
     }
 }
```

### PIX
Em caso de falha no desembolso via PIX

WEBHOOK TYPE
debt

STATUS
canceled

**Webhook Body**

```json
{
    "key": "<Debt Key>",
    "status": "canceled",
    "webhook_type": "debt",
    "event_datetime": "2025-03-18 16:41:28",
    "data": {
        "cancel_reason": "pix_refusal",
        "pix_refusal": {
            "reason_enumerator": "invalid_document_number",
            "reason": "CPF/CNPJ do usuário recebedor não é compatível com o titular da conta de destino."
        }
    }
}
```

## 4 - Reapresentação de Pagamento
Altera a data de desembolso sem afetar os valores financeiros da operação.

**POST**
/debt/ DEBT-KEY /change_disbursement_date

Testar no Playground

### Request

**Request Body**

```json
{
    "disbursement_date": "2025-03-19",
    "disbursement_bank_accounts": [
        {
            "branch_number": "1232",
            "account_digit": "4",
            "account_number": "412412412",
            "account_type": "checking_account",
            "document_number": "<CPF DO TRABALHADOR>",
            "bank_code": 184,
            "ispb_number": "17298092",
            "name": "<NOME DO TRABALHADOR>",
            "percentage_receivable": 100
        }
    ]
}
```

 
### Response

STATUS
**200** OK

**Response Body**

```json
{
    "disbursement_date": "2025-03-19",
    "disbursement_accounts": [
        {
            "account_branch": "1232",
            "account_digit": "4",
            "account_number": "412412412",
            "account_type": "checking_account",
            "amount_receivable": null,
            "created_at": "2022-05-24T14:51:46",
            "digitable_line": null,
            "disbursement_type": "ted",
            "document_number": "37197645832",
            "financial_institutions": {
                "code_number": 184,
                "ispb": 17298092,
                "name": "BCO ITAÚ BBA S.A."
            },
            "financial_institutions_code_number": 184,
            "is_pix_disbursement": false,
            "ispb": "17298092",
            "name": "Márcio e Catarina Gráfica Ltda",
            "percentage_receivable": 50.0,
            "pix_key": null,
            "pix_transfer_key": null,
            "pix_type": null,
            "qr_code_key": null,
            "retry_counter": 0,
            "retry_vector": null,
            "transaction_key": null,
            "webhook_key": null
        }
    ]
}
```

---

# Manual Previdência Privada - Consulta

URL: /documentation/manual_previdencia_privada/manual_previdencia_privada_consulta

:::info Próximo passo
- [Crédito Novo](/documentation/manual_previdencia_privada/manual_previdencia_privada_credito_novo)
:::

:::caution API em desenvolvimento 
A API ainda está em fase de desenvolvimento, sendo assim, este manual está sujeito a alterações.
:::

---

## 1. Consulta de garantias

A consulta de garantias permite verificar as informações referentes aos produtos de previdência. Esta operação é assíncrona, o pedido de consulta é enviado para uma de nossas filas e processado posteriormente. A requisição retorna de imediato o identificador único referente ao pedido de consulta e seu status de processamento.

### Request

**POST**
/private_pension/inquiry

Testar no Playground

**Payload**

```json
{
    "document_number": "\<CPF DO ASSINANTE\>",
    "operating_entity": "\<CNPJ ENTIDADE OPERADORA\>",
    "investment_funds": [
        {
            "susep_process_number": "",
            "certificate": "",   
            "name": "",
            "document_number": "",
            "class": "",
            "subclass": "",
        },
        {
            "susep_process_number": "",
            "certificate": "",
            "name": "",
            "document_number": "",
            "class": "",
            "subclass": "",
        },
        {
            "susep_process_number": "",
            "certificate": "",  
            "name": "",
            "document_number": "",
            "class": "",
            "subclass": "",
        },
    ],
    "authorization_term": {
        "signature": {
            "signer": {
                "name": "\<NOME DO ASSINANTE\>",
                "birth_date": "\<DATA DE NASCIMENTO DO ASSINANTE\>",
                "address": {
                    "street": "",
                    "neighborhood": "",
                    "city": "",
                    "state": "",
                    "postal_code": "",
                },
                "email": "\<EMAIL ASSINANTE\>",
                "phone": {
                    "number": "\<NUMERO ASSINANTE\>",
                    "area_code": "\<DDD ASSINANTE\>",
                    "country_code": "55"
                },
            }
        },
        "authentication_type": "opt_in",
        "authenticity": {
            "timestamp": "\<DATA E HORA DA ASSINATURA\>",
            "ip_address": "\<IP DO ASSINANTE\>",
            "city": "\<CIDADE DA ASSINATURA\>",
            "session_id": "\<ID DA SESSÃO DO ASSINANTE\>",
        },
    }
}
```

**Body Details**

| Campo              | Tipo   | Descrição                        |
|--------------------|--------|----------------------------------|
| document_number    | string | CPF do tomador                   |
| operating_entity   | string | Enumerador da entidade operadora |
| investment_funds   | objeto | Dados de fundos de investimento  |
| authorization_term | objeto | Dados de autorização             |

#### Objeto investment_funds

| Campo                 | Tipo   | Descrição                             |
|-----------------------|--------|---------------------------------------|
| susep_process_number  | string | Número do processo SUSEP              |
| certificate           | string | Certificado do produto de previdência |
| name                  | string | Nome do fundo                         |
| document_number       | string | CNPJ do fundo                         |
| class                 | string | Classe do fundo                       |
| subclass              | string | Subclasse do fundo                    |

#### Objeto authorization_term

| Campo               | Tipo   | Descrição                        |
|---------------------|--------|----------------------------------|
| signature           | objeto | Dados de assinatura              |
| authentication_type | string | Tipo de autenticação (opt_in)    |
| authenticity        | objeto | Dados de autenticidade           |

#### Objeto signature

| Campo              | Tipo   | Descrição                        |
|--------------------|--------|----------------------------------|
| signer             | objeto | Dados do assinante               |

#### Objeto signer

| Campo              | Tipo   | Descrição                        |
|--------------------|--------|----------------------------------|
| name               | string | Nome do assinante                |
| birth_date         | string | Data de nascimento do assinante  |
| address            | objeto | Endereço do assinante            |
| email              | objeto | Endereço de email do assinante   |
| phone              | objeto | Telefone do assinate             |

#### Objeto address

| Campo              | Tipo   | Descrição                        |
|--------------------|--------|----------------------------------|
| street             | string | Logradouro                       |
| neighborhood       | string | Bairro                           |
| city               | string | Cidade                           |
| state              | string | Estado                           |
| postal_code        | string | CEP                              |

#### Objeto phone

| Campo              | Tipo   | Descrição                        |
|--------------------|--------|----------------------------------|
| number             | string | Número de telefone               |
| area_code          | string | DDD                              |
| country_code       | string | Código de telefone do país       |

#### Objeto authenticity

| Campo              | Tipo   | Descrição                        |
|--------------------|--------|----------------------------------|
| timestamp          | string | Timestamp do aceite do tomador   |
| ip_address         | string | IP da sessão do usuário          |
| city               | string | Cidade de assinatura             |
| session_id         | string | Chave identificadora interna da sessão do usuário |

### Response

STATUS
**201** (CREATED)

**Payload**

```json
{
    "inquiry_key": "69aac130-35cb-4bdd-80e9-ba01d18002bd",
    "inquiry_status": "pending_inquiry"
}
```

**Response Body Details**

| Campo                     | Tipo    | Descrição                                                           |
|---------------------------|---------|---------------------------------------------------------------------|
| inquiry_key       | string  | Identificador única para a consulta da garantia                     |
| inquiry_status    | string  | Status da requisição de consulta (pending_inquiry/success/rejected) |

---

## 2. Consulta do processamento de garantias

**GET**
/private_pension/inquiry/[inquiry_key]

Testar no Playground

### Response

**Response Body**

```json
{
    "inquiry_key": "69aac130-35cb-4bdd-80e9-ba01d18002bd",
    "inquiry_status": "pending_inquiry"
}
```

---

## 3. Webhook de consulta de garantias

Após o processamento do pedido de consulta, o cliente receberá um webhook com as informações das garantias.

:::caution Atenção
O cliente deve implementar o tratamento deste webhook para capturar as informações do pedido de consulta das garantias.
:::

WEBHOOK TYPE
laas.private_pension.inquiry.status_change

STATUS
sucess

**Webhook Body**

```json
{
  "key": "69aac130-35cb-4bdd-80e9-ba01d18002bd",
  "status": "success",
  "webhook_type": "laas.private_pension.inquiry.status_change",
  "event_datetime": "2025-10-08T01:00:00Z",
  "data": [
        {
            "contract_id": "851cf2e4-524b-48d7-a133-fd10bb0a7313",
            "product": "PGBL",
            "operation_type": "PREVIDENCIA",
            "operating_entity": {
                "document_number": "42283770000139",
                "operating_entity_name": "Icatu seguros",
                "street": "Avenida Ibirapuera",
                "neighborhood": "Moema",
                "city": "São Paulo",
                "state": "SP",
                "postal_code": "04028002",
                "authenticity": {
                    "timestamp": "\<DATA E HORA DA ASSINATURA DA ENTIDADE OPERADORA\>",
                    "city": "\<CIDADE DA ASSINATURA DA ENTIDADE OPERADORA\>",
                    "session_id": "\<ID DA SESSÃO DA ENTIDADE OPERADORA\>"
                }
            },
            "guarantor": {
                "contract_code": "48334488-ecf1-4b84-a352-b3eb57dca066",
                "person_type": "natural_person",
                "document_number": "75020251038",
                "name": "Nome garantidor",
                "social_name": "Nome social garantidor",
                "second_document_number": "126979364",
                "birth_date": "1983-12-01",
                "street": "Rua Maria Carolina",
                "neighborhood": "Jardim Paulistano",
                "city": "São Paulo",
                "state": "SP",
                "postal_code": "01445000",
                "phone": "11911111111",
                "email": "exemplo@gmail.com",
                "movement_type": "supply",
                "consent_term_code": "6bb8b263-c5ed-4406-bfd2-44f314038784",
                "consent_file_url": null,
                "consent_file_hash": null,
                "legal_representatives": [],
            },
            "plan_type": "PGBL",
            "initial_grace": true,
            "accumulation_period_end_date": "2050-01-01",
            "tax_regime": "indefinite",
            "remaining_grace_period": 15,
            "load_percentage": 99.50,
            "investment_funds": [
                {
                    "susep_process_number": "111111111111111111111111",
                    "certificate": "12345678QI",
                    "name": "Fundo QI Tech",
                    "document_number": "32402502000135",
                    "class": "Renda Fixa",
                    "subclass": "Crédito Privado",
                    "inquiry_id": "fcfb01b5-5c08-4cdb-9915-aaf16d457803",
                    "response_within_deadline": null,
                    "inquiry_processing_status": "inquiry_nuclea_register",
                    "inquiry_status": "pending",
                    "rejection_reason": null,
                    "rejection_reason_description": null,
                    "remuneration_criteria": null,
                    "available_gross_amount": 500,
                    "elegible_gross_amount": 250,
                    "lock_gross_amount": 200
                }
            ]
        },
        {
            "contract_id": "733cf2e4-908b-48d7-a222-fd10bb0a1323",
            "product": "VGBL",
            "operation_type": "PREVIDENCIA",
            "operating_entity": {
                "document_number": "42283770000139",
                "operating_entity_name": "Icatu seguros",
                "street": "Avenida Ibirapuera",
                "neighborhood": "Moema",
                "city": "São Paulo",
                "state": "SP",
                "postal_code": "04028002",
                "authenticity": {
                    "timestamp": "\<DATA E HORA DA ASSINATURA DA ENTIDADE OPERADORA\>",
                    "city": "\<CIDADE DA ASSINATURA DA ENTIDADE OPERADORA\>",
                    "session_id": "\<ID DA SESSÃO DA ENTIDADE OPERADORA\>"
                }
            },
            "guarantor": {
                "contract_code": "48334488-ecf1-4b84-a352-b3eb57dca066",
                "person_type": "natural_person",
                "document_number": "75020251038",
                "name": "Nome garantidor",
                "social_name": "Nome social garantidor",
                "second_document_number": "126979364",
                "birth_date": "1983-12-01",
                "street": "Rua Maria Carolina",
                "neighborhood": "Jardim Paulistano",
                "city": "São Paulo",
                "state": "SP",
                "postal_code": "01445000",
                "phone": "11911111111",
                "email": "exemplo@gmail.com",
                "movement_type": "supply",
                "consent_term_code": "6bb8b263-c5ed-4406-bfd2-44f314038784",
                "consent_file_url": null,
                "consent_file_hash": null,
                "legal_representatives": [],
            },
            "plan_type": "VGBL",
            "initial_grace": true,
            "accumulation_period_end_date": "2050-01-01",
            "tax_regime": "indefinite",
            "remaining_grace_period": 15,
            "load_percentage": 99.50,
            "investment_funds": [
                {
                    "susep_process_number": "222222222222222222222222",
                    "certificate": "87654321QI",
                    "name": "Fundo QI Tech",
                    "document_number": "32402502000135",
                    "class": "Renda Fixa",
                    "subclass": "Crédito Privado",
                    "inquiry_id": "fcfb01b5-5c08-4cdb-9915-aaf16d457803",
                    "response_within_deadline": null,
                    "inquiry_processing_status": "inquiry_nuclea_register",
                    "inquiry_status": "pending",
                    "rejection_reason": null,
                    "rejection_reason_description": null,
                    "remuneration_criteria": null,
                    "available_gross_amount": 500,
                    "elegible_gross_amount": 250,
                    "lock_gross_amount": 200
                }
            ]
        },
        {
            "contract_id": "733cf2e4-908b-48d7-a222-fd10bb0a1323",
            "product": "PGBL",
            "operation_type": "PREVIDENCIA",
            "operating_entity": {
                "document_number": "42283770000139",
                "operating_entity_name": "Icatu seguros",
                "street": "Avenida Ibirapuera",
                "neighborhood": "Moema",
                "city": "São Paulo",
                "state": "SP",
                "postal_code": "04028002",
                "authenticity": {
                    "timestamp": "\<DATA E HORA DA ASSINATURA DA ENTIDADE OPERADORA\>",
                    "city": "\<CIDADE DA ASSINATURA DA ENTIDADE OPERADORA\>",
                    "session_id": "\<ID DA SESSÃO DA ENTIDADE OPERADORA\>"
                }
            },
            "guarantor": {
                "contract_code": "94039572-ecf1-4h84-h929-q3eb51gea231",
                "person_type": "natural_person",
                "document_number": "75020251038",
                "name": "Nome garantidor",
                "social_name": "Nome social garantidor",
                "second_document_number": "126979364",
                "birth_date": "1983-12-01",
                "street": "Rua Maria Carolina",
                "neighborhood": "Jardim Paulistano",
                "city": "São Paulo",
                "state": "SP",
                "postal_code": "01445000",
                "phone": "11911111111",
                "email": "exemplo@gmail.com",
                "movement_type": "supply",
                "consent_term_code": "6bb8b263-c5ed-4406-bfd2-44f314038784",
                "consent_file_url": null,
                "consent_file_hash": null,
                "legal_representatives": [],
            },
            "plan_type": "PGBL",
            "initial_grace": true,
            "accumulation_period_end_date": "2050-01-01",
            "tax_regime": "indefinite",
            "remaining_grace_period": 15,
            "load_percentage": 99.50,
            "investment_funds": [
                {
                    "susep_process_number": "333333333333333333333333",
                    "certificate": "56781234QI",
                    "name": "Fundo QI Tech",
                    "document_number": "32402502000135",
                    "class": "Renda Fixa",
                    "subclass": "Crédito Privado",
                    "inquiry_id": "fcfb01b5-5c08-4cdb-9915-aaf16d457803",
                    "response_within_deadline": null,
                    "inquiry_processing_status": "inquiry_nuclea_register",
                    "inquiry_status": "pending",
                    "rejection_reason": null,
                    "rejection_reason_description": null,
                    "remuneration_criteria": null,
                    "available_gross_amount": 500,
                    "elegible_gross_amount": 250,
                    "lock_gross_amount": 200
                }
            ]
        }
    ]
}
```

**Webhook Body Details**

| Campo               | Tipo   | Descrição                            |
|---------------------|--------|--------------------------------------|
| key | string | Chave do pedido de consulta          |
| status              | string | Status do documento (success)        |
| webhook_type        | string | Tipo do webhook                      |
| event_datetime      | string | Data e hora do evento                |
| data                | array  | Lista de garantias                   |

#### Objeto data

| Campo                         | Tipo   | Descrição                        |
|-------------------------------|--------|----------------------------------|
| contract_id                   | string | Código do anexo IV modelo de termo acessório ao instrumento contratual de garantia           |
| product                       | string | Denominação do produto na entidade operadora  |
| operation_type                | string | Tipo do produto (previdencia)    |
| operating_entity              | objeto | Dados da entidade operadora      |
| guarantor                     | objeto | Dados do garantidor              |
| plan_type                     | objeto | Tipo do plano de previdência     |
| initial_grace                 | bool   | Existência de período de carência inicial |
| accumulation_period_end_date  | objeto | Data final do período de acumulação |
| tax_regime                    | enum   | Regime tributário                |
| remaining_grace_period        | int    | Prazo remanescente do período de carência (em dias)           |
| load_percentage               | number | Percentual de carregamento       |
| investment_funds              | objeto | Dados de fundo de investimento   |

#### Objeto operating_entity

| Campo                 | Tipo   | Descrição                        |
|-----------------------|--------|----------------------------------|
| document_number       | string | Cnpj da entidade operadora       |
| operating_entity_name | string | Nome da entidade operadora       |
| street                | string | Logradouro                       |
| neighborhood          | string | Bairro                           |
| city                  | string | Cidade                           |
| state                 | string | Estado                           |
| postal_code           | string | CEP                              |
| authenticity          | object | Dados de autenticidade           |

#### Objeto authenticity

| Campo              | Tipo   | Descrição                                 |
|--------------------|--------|-------------------------------------------|
| timestamp          | string | Timestamp do aceite da entidade operadora |
| city               | string | Cidade de assinatura                      |
| session_id         | string | Chave identificadora interna da sessão    |

#### Objeto guarantor

| Campo                  | Tipo   | Descrição                                 |
|------------------------|--------|-------------------------------------------|
| contract_code          | string | Código contratual                         |
| person_type            | enum   | Tipo de pessoa (PF, PJ)                   |
| document_number        | string | Cpf/cnpj do garantidor                    |
| name                   | string | Nome do garantidor                        |
| social_name            | string | Nome social do garantidor                 |
| second_document_number | string | Rg do garantidor                          |
| birth_date             | string | Data de nascimento do garantidor          |
| street                 | string | Logradouro                                |
| neighborhood           | string | Bairro                                    |
| city                   | string | Cidade                                    |
| state                  | string | Estado                                    |
| postal_code            | string | CEP                                       |
| phone                  | string | Número de telefone do garantidor          |
| email                  | string | Endereço de email do garantidor           |
| movement_type          | enum   | Tipo de operação realizada                |
| consent_term_code      | string | Código do termo de consentimento          |
| consent_file_url       | object | Dados da url do arquivo de consentimento  |
| consent_file_hash      | string | Hash do arquivo de consentimento          |
| legal_representatives  | object | Representantes legais                     |

#### Objeto investment_funds

| Campo                         | Tipo   | Descrição                                      |
|-------------------------------|--------|------------------------------------------------|
| susep_process_number          | string | Número do processo SUSEP                       |
| certificate                   | string | Certificado do produto de previdência          |
| name                          | string | Nome do fundo                                  |
| document_number               | string | CNPJ do fundo                                  |
| class                         | string | Classe do fundo                                |
| subclass                      | string | Subclasse do fundo                             |
| inquiry_id                    | string | Identificador da garantia                      |
| response_within_deadline      | bool   | Resposta realizada dentro do prazo             |
| inquiry_processing_status     | enum   | Status do processamento do pedido de consulta  |
| inquiry_status                | enum   | Status do pedido                               |
| rejection_reason              | enum   | Motivo de recusa da consulta                   |
| rejection_reason_description  | string | Descrição do motivo de recusa da consulta      |
| remuneration_criteria         | string | Critério de remuneração                        |
| available_gross_amount        | number | Valor bruto disponível                         |
| elegible_gross_amount         | number | Valor bruto elegível                           |
| lock_gross_amount             | number | Valor bruto para bloquear                      |

#### Objeto consent_file_url

| Campo              | Tipo   | Descrição                                 |
|--------------------|--------|-------------------------------------------|
| url                | string | Url do arquivo de consentimento           |
| duration           | string | Duração de validade de acesso da url      |

#### Objeto legal_representatives

| Campo              | Tipo   | Descrição                                 |
|--------------------|--------|-------------------------------------------|
| person_type        | enum   | Tipo de pessoa                            |
| document_number    | string | Cpf/cnpj do representante legal           |
| name               | string | Nome do representante legal               |
| social_name        | string | Nome social do representante legal        |

#### Enumerador tax_regime

| Enumerador                | Descrição                     |
|---------------------------|-------------------------------|
| indefinite                | Regime tributário indefinido  |
| progressive               | Regime tributário progressivo |
| regressive                | Regime tributário regressivo  |

#### Enumerador person_type

| Enumerador                | Descrição                    |
|---------------------------|------------------------------|
| natural_person            | Pessoa Física                |
| legal_person              | Pessoa Jurídica              |

#### Enumerador movement_type

| Enumerador                | Descrição                          |
|---------------------------|------------------------------------|
| supply                    | Consentimento para a trava         |
| renegotiate               | Consentimento para a repactuação   |

#### Enumerador inquiry_processing_status

| Enumerador                        | Descrição                                 |
|-----------------------------------|-------------------------------------------|
| inquiry_nuclea_register           | Pedido cadastrado pela Núclea             |
| inquiry_sent_operating_entity     | Pedido recebido pela entidade operadora   |
| inquiry_returned_operating_entity | Pedido retornado pela entidade operadora  |

#### Enumerador inquiry_status

| Enumerador                | Descrição                          |
|---------------------------|------------------------------------|
| success                   | Sucesso no pedido de consulta      |
| failed                    | Falha no pedido de consulta        |
| pending                   | Pedido de consulta pendente        |

#### Enumerador rejection_reason

| Enumerador                    | Descrição                          |
|-------------------------------|------------------------------------|
| invalid_signature             | Assinatura inválida                |
| invalid_client_information    | Informações do cliente inválidas   |
| invalid_plan_information      | Informações do plano inválidas     |
| incomplete_information        | Informações incompletas            |
| others                        | Outros motivos de rejeição         |

WEBHOOK TYPE
laas.private_pension.inquiry.status_change

STATUS
failed

**Webhook Body**

```json
{
  "key": "69aac130-35cb-4bdd-80e9-ba01d18002bd",
  "status": "failed",
  "webhook_type": "laas.private_pension.inquiry.status_change",
  "event_datetime": "2025-10-08T01:00:00Z",
  "data": [
        {
            "contract_id": "851cf2e4-524b-48d7-a133-fd10bb0a7313",
            "product": "PGBL",
            "operation_type": "PREVIDENCIA",
            "operating_entity": {
                "document_number": "42283770000139",
                "operating_entity_name": "Icatu seguros",
                "street": "Avenida Ibirapuera",
                "neighborhood": "Moema",
                "city": "São Paulo",
                "state": "SP",
                "postal_code": "04028002",
                "authenticity": {
                    "timestamp": "\<DATA E HORA DA ASSINATURA DA ENTIDADE OPERADORA\>",
                    "city": "\<CIDADE DA ASSINATURA DA ENTIDADE OPERADORA\>",
                    "session_id": "\<ID DA SESSÃO DA ENTIDADE OPERADORA\>"
                }
            },
            "guarantor": {
                "contract_code": "48334488-ecf1-4b84-a352-b3eb57dca066",
                "person_type": "natural_person",
                "document_number": "75020251038",
                "name": "Nome garantidor",
                "social_name": "Nome social garantidor",
                "second_document_number": "126979364",
                "birth_date": "1983-12-01",
                "street": "Rua Maria Carolina",
                "neighborhood": "Jardim Paulistano",
                "city": "São Paulo",
                "state": "SP",
                "postal_code": "01445000",
                "phone": "11911111111",
                "email": "exemplo@gmail.com",
                "movement_type": "supply",
                "consent_term_code": "6bb8b263-c5ed-4406-bfd2-44f314038784",
                "consent_file_url": null,
                "consent_file_hash": null,
                "legal_representatives": [],
            },
            "plan_type": "PGBL",
            "initial_grace": true,
            "accumulation_period_end_date": "2050-01-01",
            "tax_regime": "indefinite",
            "remaining_grace_period": 15,
            "load_percentage": 99.50,
            "investment_funds": [
                {
                    "susep_process_number": "111111111111111111111111",
                    "certificate": "12345678QI",
                    "name": "Fundo QI Tech",
                    "document_number": "32402502000135",
                    "class": "Renda Fixa",
                    "subclass": "Crédito Privado",
                    "inquiry_id": "fcfb01b5-5c08-4cdb-9915-aaf16d457803",
                    "response_within_deadline": null,
                    "inquiry_processing_status": "inquiry_nuclea_register",
                    "inquiry_status": "failed",
                    "rejection_reason": "invalid_plan_information",
                    "rejection_reason_description": null,
                    "remuneration_criteria": null,
                    "available_gross_amount": null,
                    "elegible_gross_amount": null,
                    "lock_gross_amount": null
                }
            ]
        },
        {
            "contract_id": "733cf2e4-908b-48d7-a222-fd10bb0a1323",
            "product": "VGBL",
            "operation_type": "PREVIDENCIA",
            "operating_entity": {
                "document_number": "42283770000139",
                "operating_entity_name": "Icatu seguros",
                "street": "Avenida Ibirapuera",
                "neighborhood": "Moema",
                "city": "São Paulo",
                "state": "SP",
                "postal_code": "04028002",
                "authenticity": {
                    "timestamp": "\<DATA E HORA DA ASSINATURA DA ENTIDADE OPERADORA\>",
                    "city": "\<CIDADE DA ASSINATURA DA ENTIDADE OPERADORA\>",
                    "session_id": "\<ID DA SESSÃO DA ENTIDADE OPERADORA\>"
                }
            },
            "guarantor": {
                "contract_code": "48334488-ecf1-4b84-a352-b3eb57dca066",
                "person_type": "natural_person",
                "document_number": "75020251038",
                "name": "Nome garantidor",
                "social_name": "Nome social garantidor",
                "second_document_number": "126979364",
                "birth_date": "1983-12-01",
                "street": "Rua Maria Carolina",
                "neighborhood": "Jardim Paulistano",
                "city": "São Paulo",
                "state": "SP",
                "postal_code": "01445000",
                "phone": "11911111111",
                "email": "exemplo@gmail.com",
                "movement_type": "supply",
                "consent_term_code": "6bb8b263-c5ed-4406-bfd2-44f314038784",
                "consent_file_url": null,
                "consent_file_hash": null,
                "legal_representatives": [],
            },
            "plan_type": "VGBL",
            "initial_grace": true,
            "accumulation_period_end_date": "2050-01-01",
            "tax_regime": "indefinite",
            "remaining_grace_period": 15,
            "load_percentage": 99.50,
            "investment_funds": [
                {
                    "susep_process_number": "222222222222222222222222",
                    "certificate": "87654321QI",
                    "name": "Fundo QI Tech",
                    "document_number": "32402502000135",
                    "class": "Renda Fixa",
                    "subclass": "Crédito Privado",
                    "inquiry_id": "fcfb01b5-5c08-4cdb-9915-aaf16d457803",
                    "response_within_deadline": null,
                    "inquiry_processing_status": "inquiry_nuclea_register",
                    "inquiry_status": "failed",
                    "rejection_reason": "others",
                    "rejection_reason_description": "O numero do processo susep nao se refere a esse produto",
                    "remuneration_criteria": null,
                    "available_gross_amount": 500,
                    "elegible_gross_amount": 250,
                    "lock_gross_amount": 200
                }
            ]
        },
        {
            "contract_id": "733cf2e4-908b-48d7-a222-fd10bb0a1323",
            "product": "PGBL",
            "operation_type": "PREVIDENCIA",
            "operating_entity": {
                "document_number": "42283770000139",
                "operating_entity_name": "Icatu seguros",
                "street": "Avenida Ibirapuera",
                "neighborhood": "Moema",
                "city": "São Paulo",
                "state": "SP",
                "postal_code": "04028002",
                "authenticity": {
                    "timestamp": "\<DATA E HORA DA ASSINATURA DA ENTIDADE OPERADORA\>",
                    "city": "\<CIDADE DA ASSINATURA DA ENTIDADE OPERADORA\>",
                    "session_id": "\<ID DA SESSÃO DA ENTIDADE OPERADORA\>"
                }
            },
            "guarantor": {
                "contract_code": "94039572-ecf1-4h84-h929-q3eb51gea231",
                "person_type": "natural_person",
                "document_number": "75020251038",
                "name": "Nome garantidor",
                "social_name": "Nome social garantidor",
                "second_document_number": "126979364",
                "birth_date": "1983-12-01",
                "street": "Rua Maria Carolina",
                "neighborhood": "Jardim Paulistano",
                "city": "São Paulo",
                "state": "SP",
                "postal_code": "01445000",
                "phone": "11911111111",
                "email": "exemplo@gmail.com",
                "movement_type": "supply",
                "consent_term_code": "6bb8b263-c5ed-4406-bfd2-44f314038784",
                "consent_file_url": null,
                "consent_file_hash": null,
                "legal_representatives": [],
            },
            "plan_type": "PGBL",
            "initial_grace": true,
            "accumulation_period_end_date": "2050-01-01",
            "tax_regime": "indefinite",
            "remaining_grace_period": 15,
            "load_percentage": 99.50,
            "investment_funds": [
                {
                    "susep_process_number": "333333333333333333333333",
                    "certificate": "56781234QI",
                    "name": "Fundo QI Tech",
                    "document_number": "32402502000135",
                    "class": "Renda Fixa",
                    "subclass": "Crédito Privado",
                    "inquiry_id": "fcfb01b5-5c08-4cdb-9915-aaf16d457803",
                    "response_within_deadline": null,
                    "inquiry_processing_status": "inquiry_nuclea_register",
                    "inquiry_status": "success",
                    "rejection_reason": null,
                    "rejection_reason_description": null,
                    "remuneration_criteria": null,
                    "available_gross_amount": 500,
                    "elegible_gross_amount": 250,
                    "lock_gross_amount": 200
                }
            ]
        }
    ]
}
```

---

---

# Manual Previdência Privada - Crédito Novo

URL: /documentation/manual_previdencia_privada/manual_previdencia_privada_credito_novo

:::info Navegação
- [Consulta](/documentation/manual_previdencia_privada/manual_previdencia_privada_consulta) (anterior)
- [Averbação e Desembolso](/documentation/manual_previdencia_privada/manual_previdencia_privada_averbacao_desembolso) (próximo)
:::

:::caution API em desenvolvimento
A API ainda está em fase de desenvolvimento, sendo assim, este manual está sujeito a alterações.
:::

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeados de forma estrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

## 1 - Simulação da dívida:
CRÉDITO NOVO

### Request

**POST**
/debt_simulation

Testar no Playground

**Valor de parcela**

```json title='Request Body'
{
    "borrower": {
        "person_type": "natural"
    },
    "financial": {
        "first_due_date": "2024-12-07",
        "installment_face_value": 100,
        "disbursement_date": "2024-11-05",
        "limit_days_to_disburse": 3,
        "number_of_installments": 4,
        "monthly_interest_rate": 0.018,
        "interest_type": "pre_price_days",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0
    },
    "collaterals": [
        {
            "collateral_type": "private_pension"
        }
    ]
}
```

**Valor desembolsado**

```json title='Request Body'
{
    "borrower": {
        "person_type": "natural"
    },
    "financial": {
        "first_due_date": "2024-12-07",
        "disbursed_amount": 1000,
        "disbursement_date": "2024-11-05",
        "limit_days_to_disburse": 3,
        "number_of_installments": 4,
        "monthly_interest_rate": 0.018,
        "interest_type": "pre_price_days",
        "fine_configuration": {
            "monthly_rate": 0.01,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0.02
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "principal_grace_period": 0
    },
    "collaterals": [
        {
            "collateral_type": "private_pension"
        }
    ]
}
```

:::info
Na request acima existem 2 simulações sendo realizadas. A primeira está fixando o valor de parcela ao cliente
(varia o valor desembolsado) e a segunda está fixando o valor desembolsado (varia o valor de parcela).
::: 

### Response

STATUS
**200** (OK)

**Response Body**

```json
{
    "type": "debt",
    "key": "<Debt Key>",
    "status": "finished",
    "event_datetime": "2024-11-05 16:50:00",
    "data": {
        "interest_type": "pre_price_days",
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "interest_payment_month_period": 1,
        "principal_grace_period": 0,
        "principal_amortization_month_period": 1,
        "operation_type": "structured_operation",
        "post_fixed_interest_base": "workdays",
        "post_fixed_interest_rate": null,
        "prefixed_interest_rate": {
            "interest_base": "calendar_days_365",
            "annual_rate": 0.23872053,
            "monthly_rate": 0.018,
            "daily_rate": 0.00058669
        },
        "issue_date": "2024-11-05",
        "number_of_installments": 4,
        "requester_key": "e5eb6a0a-e003-4cbd-b702-5a25bf71af0a",
        "final_disbursement_amount": 0.0,
        "disbursement_options": [
            {
                "iof_amount": 3.93,
                "total_pre_fixed_amount": 17.8715883143,
                "cet": 0.0257,
                "annual_cet": 0.355163,
                "contract_fees": [
                    {
                        "fee_type": "tac",
                        "amount_type": "percentage",
                        "amount": 0.6,
                        "fee_amount": 2.29
                    },
                    {
                        "fee_type": "ted_fee",
                        "amount_type": "absolute",
                        "amount": 1.0,
                        "fee_amount": 1.0
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "insurance_premium",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "tac",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    }
                ],
                "contract_fee_amount": 2.29,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "disbursement_date": "2024-11-05",
                "first_due_date": "2024-12-21",
                "installments": [
                    {
                        "calendar_days": 34,
                        "workdays": 23.0,
                        "business_due_date": "2024-12-21",
                        "due_date": "2024-12-21",
                        "due_principal": 382.13,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 7.6967422515,
                        "tax_amount": 0.257341482602818,
                        "total_amount": 100,
                        "principal_amortization_amount": 92.3032577485,
                        "installment_number": 1
                    },
                    {
                        "calendar_days": 29,
                        "workdays": 19.0,
                        "business_due_date": "2025-01-21",
                        "due_date": "2025-01-21",
                        "due_principal": 289.8267422515,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 4.9718040699,
                        "tax_amount": 0.4909156601748966,
                        "total_amount": 100,
                        "principal_amortization_amount": 95.0281959301,
                        "installment_number": 2
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 23.0,
                        "business_due_date": "2025-02-21",
                        "due_date": "2025-02-21",
                        "due_principal": 194.7985463214,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.5742034136,
                        "tax_amount": 0.7432500400879712,
                        "total_amount": 100,
                        "principal_amortization_amount": 96.4257965864,
                        "installment_number": 3
                    },
                    {
                        "calendar_days": 28,
                        "workdays": 18.0,
                        "business_due_date": "2025-03-21",
                        "due_date": "2025-03-21",
                        "due_principal": 98.372749735,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.6288385793,
                        "tax_amount": 0.9841050988526828,
                        "total_amount": 100,
                        "principal_amortization_amount": 98.3711614207,
                        "installment_number": 4
                    }
                ],
                "issue_amount": 382.13,
                "disbursed_issue_amount": 374.91,
                "assignment_amount": 382.13,
                "final_disbursement_amount": 374.91,
                "prefixed_interest_rate": {
                    "interest_base": "calendar_days_365",
                    "annual_rate": 0.23872053,
                    "monthly_rate": 0.018,
                    "daily_rate": 0.00058669
                }
            },
            {
                "iof_amount": 4.77,
                "total_pre_fixed_amount": 24.2597288075,
                "cet": 0.0243,
                "annual_cet": 0.334037,
                "contract_fees": [
                    {
                        "fee_type": "tac",
                        "amount_type": "percentage",
                        "amount": 0.6,
                        "fee_amount": 2.25
                    },
                    {
                        "fee_type": "ted_fee",
                        "amount_type": "absolute",
                        "amount": 1.0,
                        "fee_amount": 1.0
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "insurance_premium",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "tac",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    }
                ],
                "contract_fee_amount": 2.25,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "disbursement_date": "2024-11-06",
                "first_due_date": "2025-01-21",
                "installments": [
                    {
                        "calendar_days": 62,
                        "workdays": 41.0,
                        "business_due_date": "2025-01-21",
                        "due_date": "2025-01-21",
                        "due_principal": 375.74,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 13.9149280115,
                        "tax_amount": 0.437656505989534,
                        "total_amount": 100,
                        "principal_amortization_amount": 86.0850719885,
                        "installment_number": 1
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 23.0,
                        "business_due_date": "2025-02-21",
                        "due_date": "2025-02-21",
                        "due_principal": 289.6549280115,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 5.3146959395,
                        "tax_amount": 0.722070128765373,
                        "total_amount": 100,
                        "principal_amortization_amount": 94.6853040605,
                        "installment_number": 2
                    },
                    {
                        "calendar_days": 28,
                        "workdays": 18.0,
                        "business_due_date": "2025-03-21",
                        "due_date": "2025-03-21",
                        "due_principal": 194.969623951,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.2283291407,
                        "tax_amount": 0.9601685182659746,
                        "total_amount": 100,
                        "principal_amortization_amount": 96.7716708593,
                        "installment_number": 3
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 21.0,
                        "business_due_date": "2025-04-07",
                        "due_date": "2025-04-07",
                        "due_principal": 98.1979530917,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.8017757158,
                        "tax_amount": 1.2239426674782687,
                        "total_amount": 100,
                        "principal_amortization_amount": 98.1982242842,
                        "installment_number": 4
                    }
                ],
                "issue_amount": 375.74,
                "disbursed_issue_amount": 367.72,
                "assignment_amount": 375.74,
                "final_disbursement_amount": 367.72,
                "prefixed_interest_rate": {
                    "interest_base": "calendar_days_365",
                    "annual_rate": 0.23872053,
                    "monthly_rate": 0.018,
                    "daily_rate": 0.00058669
                }
            },
            {
                "iof_amount": 4.74,
                "total_pre_fixed_amount": 24.0392857898,
                "cet": 0.0243,
                "annual_cet": 0.334673,
                "contract_fees": [
                    {
                        "fee_type": "tac",
                        "amount_type": "percentage",
                        "amount": 0.6,
                        "fee_amount": 2.26
                    },
                    {
                        "fee_type": "ted_fee",
                        "amount_type": "absolute",
                        "amount": 1.0,
                        "fee_amount": 1.0
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "insurance_premium",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "tac",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    }
                ],
                "contract_fee_amount": 2.26,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "disbursement_date": "2024-11-07",
                "first_due_date": "2025-01-21",
                "installments": [
                    {
                        "calendar_days": 61,
                        "workdays": 40.0,
                        "business_due_date": "2025-01-21",
                        "due_date": "2025-01-21",
                        "due_principal": 375.96,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 13.6944849939,
                        "tax_amount": 0.4317001860605122,
                        "total_amount": 100,
                        "principal_amortization_amount": 86.3055150061,
                        "installment_number": 1
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 23.0,
                        "business_due_date": "2025-02-21",
                        "due_date": "2025-02-21",
                        "due_principal": 289.6544849939,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 5.3146959395,
                        "tax_amount": 0.714305933832412,
                        "total_amount": 100,
                        "principal_amortization_amount": 94.6853040605,
                        "installment_number": 2
                    },
                    {
                        "calendar_days": 28,
                        "workdays": 18.0,
                        "business_due_date": "2025-03-21",
                        "due_date": "2025-03-21",
                        "due_principal": 194.9691809334,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.2283291407,
                        "tax_amount": 0.952233241255512,
                        "total_amount": 100,
                        "principal_amortization_amount": 96.7716708593,
                        "installment_number": 3
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 21.0,
                        "business_due_date": "2025-04-07",
                        "due_date": "2025-04-07",
                        "due_principal": 98.1975100741,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.8017757157,
                        "tax_amount": 1.2158904130882027,
                        "total_amount": 100,
                        "principal_amortization_amount": 98.1982242843,
                        "installment_number": 4
                    }
                ],
                "issue_amount": 375.96,
                "disbursed_issue_amount": 367.96,
                "assignment_amount": 375.96,
                "final_disbursement_amount": 367.96,
                "prefixed_interest_rate": {
                    "interest_base": "calendar_days_365",
                    "annual_rate": 0.23872053,
                    "monthly_rate": 0.018,
                    "daily_rate": 0.00058669
                }
            },
            {
                "iof_amount": 4.71,
                "total_pre_fixed_amount": 23.8187134405,
                "cet": 0.0244,
                "annual_cet": 0.335196,
                "contract_fees": [
                    {
                        "fee_type": "tac",
                        "amount_type": "percentage",
                        "amount": 0.6,
                        "fee_amount": 2.26
                    },
                    {
                        "fee_type": "ted_fee",
                        "amount_type": "absolute",
                        "amount": 1.0,
                        "fee_amount": 1.0
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "insurance_premium",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    },
                    {
                        "fee_type": "tac",
                        "amount_type": "absolute",
                        "amount": 0.0,
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0,
                        "csll_amount": 0,
                        "irrf_amount": 0,
                        "pis_amount": 0,
                        "cofins_amount": 0,
                        "amount_released": 0,
                        "description": null
                    }
                ],
                "contract_fee_amount": 2.26,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "disbursement_date": "2024-11-08",
                "first_due_date": "2025-01-21",
                "installments": [
                    {
                        "calendar_days": 60,
                        "workdays": 39.0,
                        "business_due_date": "2025-01-21",
                        "due_date": "2025-01-21",
                        "due_principal": 376.18,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 13.4739126445,
                        "tax_amount": 0.42570834978906,
                        "total_amount": 100,
                        "principal_amortization_amount": 86.5260873555,
                        "installment_number": 1
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 23.0,
                        "business_due_date": "2025-02-21",
                        "due_date": "2025-02-21",
                        "due_principal": 289.6539126445,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 5.3146959395,
                        "tax_amount": 0.706541738899451,
                        "total_amount": 100,
                        "principal_amortization_amount": 94.6853040605,
                        "installment_number": 2
                    },
                    {
                        "calendar_days": 28,
                        "workdays": 18.0,
                        "business_due_date": "2025-03-21",
                        "due_date": "2025-03-21",
                        "due_principal": 194.968608584,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.2283291407,
                        "tax_amount": 0.9442979642450494,
                        "total_amount": 100,
                        "principal_amortization_amount": 96.7716708593,
                        "installment_number": 3
                    },
                    {
                        "calendar_days": 31,
                        "workdays": 21.0,
                        "business_due_date": "2025-04-21",
                        "due_date": "2025-04-21",
                        "due_principal": 98.1969377247,
                        "has_interest": true,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.8017757158,
                        "tax_amount": 1.20783815869566,
                        "total_amount": 100,
                        "principal_amortization_amount": 98.1982242842,
                        "installment_number": 4
                    }
                ],
                "issue_amount": 376.18,
                "disbursed_issue_amount": 368.21,
                "assignment_amount": 376.18,
                "final_disbursement_amount": 368.21,
                "prefixed_interest_rate": {
                    "interest_base": "calendar_days_365",
                    "annual_rate": 0.23872053,
                    "monthly_rate": 0.018,
                    "daily_rate": 0.00058669
                }
            }
        ]
    }
}
```

---

## 2 - Emissão da operação:

CRÉDITO NOVO

### Request

**POST**
/debt

Testar no Playground

**Sem representante legal**

```json title='Request Body'
{
    "borrower": {
        "name": "Nome devedor",
        "email":"email.devedor@gmail.com",
        "phone": {
            "number": "999538380",
            "area_code": "84",
            "country_code": "055"
        },
        "is_pep": false,
        "address": {
            "city": "Natal",
            "state": "RN",
            "number": "1984",
            "street": "Rua",
            "postal_code": "59065720",
            "neighborhood": "bairro"
        },
        "birth_date": "1959-07-08",
        "person_type": "natural",
        "individual_document_number": "14471835092",
        "marital_status": "single",
        "profession": "",
        "document_identification": "494598fd-c226-4332-a500-591ae3884673",
        "document_identification_back": "a194d9a3-6790-449b-a429-f450cf904777",
        "proof_of_residence": "ec838feb-642b-4c58-81d8-f113b607da08",
    },
    "financial": {
        "interest_type": "pre_price_days",
        "first_due_date": "2023-09-21",
        "disbursement_start_date": "2024-11-07",
        "disbursement_end_date": "2024-11-07",
        "fine_configuration": {
            "monthly_rate": 0.0166,
            "interest_base": "calendar_days",
            "contract_fine_rate": 0
        },
        "credit_operation_type": "ccb",
        "interest_grace_period": 0,
        "annual_interest_rate": 0.0166,
        "disbursed_amount": 1234.56,
        "issue_date": "2024-11-07",
        "number_of_installments": 10,
        "principal_grace_period": 0,
        "rebates": [ // Opcional
            {
                "amount": 20,
                "rebate_bank_account": {
                    "name": "Teste Ltda",
                    "document_number": "18533555000164",
                    "account_digit": "0",
                    "account_number": "4290001",
                    "branch_number": "0001",
                    "bank_code": "329"
                },
                "amount_type": "percentage",
                "fee_type": "spread"
            }
        ]
    },
    "simplified": true,
    "collaterals": [
        {
            "percentage": 1,
            "collateral_type": "private_pension",
            "collateral_data": {
                "total_gross_amount_lock": 1500,
                "investment_funds": [
                    {
                        "susep_process": "111111111111111",
                        "certificate": "1234567",
                        "product_denomination": "PREVIDENCIA EMPRESARIAL",
                        "operating_entity_document_number": "40591162000166",
                        "plan_type": "",
                        "initial_grace": false,   
                        "remaining_grace_period": 0,   
                        "accumulation_period_end_date": "2050-01-01",   
                        "tax_regime": "progressive",   
                        "load_percentage": 0.0,   
                        "name": "QI Fund Alpha",
                        "document_number": "32402502000135",
                        "class": "",
                        "subclass": "",
                        "lock_gross_amount": 500,
                    },
                    {
                        "susep_process": "222222222222222",
                        "certificate": "8765432",
                        "product_denomination": "PREVIDENCIA EMPRESARIAL",
                        "operating_entity_document_number": "40591162000166",
                        "plan_type": "",
                        "initial_grace": false,   
                        "remaining_grace_period": 0,   
                        "accumulation_period_end_date": "2050-01-01",   
                        "tax_regime": "progressive",   
                        "load_percentage": 0.0,   
                        "name": "QI Fund Beta",
                        "document_number": "32402502000135",
                        "class": "",
                        "subclass": "",
                        "lock_gross_amount": 500,
                    },
                    {
                        "susep_process": "333333333333333",
                        "certificate": "5678123",
                        "product_denomination": "PREVIDENCIA EMPRESARIAL",
                        "operating_entity_document_number": "40591162000166",
                        "plan_type": "",
                        "initial_grace": false,   
                        "remaining_grace_period": 0,   
                        "accumulation_period_end_date": "2050-01-01",   
                        "tax_regime": "progressive",   
                        "load_percentage": 0.0,   
                        "name": "QI Fund Gama",
                        "document_number": "32402502000135",
                        "class": "",
                        "subclass": "",
                        "lock_gross_amount": 500,
                    }
                ]
            }
        }
    ],
    "purchaser_document_number": "32402502000135",
    "disbursement_bank_accounts": [
        {
            "name": "NOME DEVEDOR",
            "bank_code": "001",
            "account_digit": "0",
            "branch_number": "2874",
            "account_number": "000057555",
            "document_number": "14471835092",
            "transfer_method": "pix",
            "percentage_receivable": 100
        }
    ]
}
```

### Response

STATUS
**201** (Created)

**Response Body**

```json title="Response Body"
{
    "webhook_type": "debt",
    "key": "<Debt Key>",
    "status": "waiting_signature",
    "event_datetime": "2024-11-07 23:19:22",
    "data": {
        "borrower": {
            "name": "Nome devedor",
            "document_number": "14471835092",
            "related_party_key": "28b7fc16-6d1f-467d-9667-62a8c13daea6"
        },
        "contract": {
            "number": "TST0000644710",
            "urls": [
                "https://storage.googleapis.com/sandbox-doc-api/documents/a2e9c83a-3666-4def-8b27-e96fabb8705c/NOME_DEVEDOR-CCB-TST0000644710-20241107231916.pdf"
            ],
            "signature_information": [
                {
                    "signer_name": "Nome devedor",
                    "signer_document_number": "14471835092",
                    "signer_role": "issuer",
                    "signer_email": null,
                    "signer_external_key": null,
                    "signature_url": null
                }
            ]
        },
        "requester_identifier_key": "eb859ebe-3a41-49bf-a6c3-d6902039ec00",
        "iof_charge_method": "financed",
        "collaterals": [
            {
                "absolute_amount": null,
                "collateral_constituted": false,
                "collateral_data": {
                    "total_gross_amount_lock": 1500,
                    "reservation_method": "issuing",
                    "investment_funds": [
                        {
                            "susep_process": "111111111111111",
                            "certificate": "1234567",
                            "plan_type": "", // opcional
                            "initial_grace": false,   
                            "grace_days": 0,   
                            "accumulation_period_end_date": "2050-01-01",   
                            "tax_regime": "progressive",   
                            "load_percentage": 0.0,   
                            "name": "QI Fund Alpha",
                            "document_number": "32402502000135",
                            "class": "", // opcional
                            "subclass": "", // opcional
                            "lock_gross_amount": 500,
                            "product_denomination": "PREVIDENCIA EMPRESARIAL",
                            "operating_entity_document_number": "40591162000166",
                            "remaining_grace_period": 15,
                        },
                        {
                            "susep_process": "222222222222222",
                            "certificate": "8765432",
                            "plan_type": "",
                            "initial_grace": false,   
                            "grace_days": 0,   
                            "accumulation_period_end_date": "2050-01-01",   
                            "tax_regime": "progressive",   
                            "load_percentage": 0.0,   
                            "name": "QI Fund Beta",
                            "document_number": "32402502000135",
                            "class": "",
                            "subclass": "",
                            "lock_gross_amount": 500,
                            "product_denomination": "PREVIDENCIA EMPRESARIAL",
                            "operating_entity_document_number": "40591162000166",
                            "remaining_grace_period": 15,
                        },
                        {
                            "susep_process": "333333333333333",
                            "certificate": "5678123",
                            "plan_type": "",
                            "initial_grace": false,   
                            "grace_days": 0,   
                            "accumulation_period_end_date": "2050-01-01",   
                            "tax_regime": "progressive",   
                            "load_percentage": 0.0,   
                            "name": "QI Fund Gama",
                            "document_number": "32402502000135",
                            "class": "",
                            "subclass": "",
                            "lock_gross_amount": 500,
                            "product_denomination": "PREVIDENCIA EMPRESARIAL",
                            "operating_entity_document_number": "40591162000166",
                            "remaining_grace_period": 15,
                        }
                    ]
                },
                "collateral_key": "26c7f4f4-51f3-41fa-b880-9691211136aa",
                "collateral_type": "private_pension",
                "created_at": "2024-11-07T23:19:16.413448",
                "external_key": null,
                "percentage": 1,
                "updated_at": "2024-11-07T23:19:16.413441"
            }
        ],
        "disbursement_options": [
            {
                "disbursement_date": "2024-11-07",
                "contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 4.55
                    },
                    {
                        "fee_type": "ted_fee",
                        "fee_amount": 1.5
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0
                    }
                ],
                "contract_fee_amount": 6.05,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "assignment_amount": 914.3,
                "issue_amount": 909.75,
                "cet": "2,0100%",
                "annual_cet": "27,0481%",
                "base_iof": 16.259002146803677,
                "additional_iof": 3.45705,
                "total_iof": 19.72,
                "total_pre_fixed_amount": 108.6508885851,
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-01-21",
                        "calendar_days": 74,
                        "due_date": "2025-01-21",
                        "due_interest": 0.0,
                        "due_principal": 909.75,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 37.1789024864,
                        "principal_amortization_amount": 64.6610975136,
                        "tax_amount": 0.3923635397125248,
                        "total_amount": 101.84,
                        "workdays": 49.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-02-21",
                        "calendar_days": 31,
                        "due_date": "2025-02-21",
                        "due_interest": 0.0,
                        "due_principal": 845.0889024864,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 2,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 14.2997636051,
                        "principal_amortization_amount": 87.5402363949,
                        "tax_amount": 0.753721435360089,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-03-21",
                        "calendar_days": 28,
                        "due_date": "2025-03-21",
                        "due_interest": 0.0,
                        "due_principal": 757.5486660915,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 3,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 11.5685715131,
                        "principal_amortization_amount": 90.2714284869,
                        "tax_amount": 0.9845001990781314,
                        "total_amount": 101.84,
                        "workdays": 18.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-04-21",
                        "calendar_days": 33,
                        "due_date": "2025-04-21",
                        "due_interest": 0.0,
                        "due_principal": 667.2772376046,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 4,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 12.025984633,
                        "principal_amortization_amount": 89.814015367,
                        "tax_amount": 1.222548377175604,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-05-21",
                        "calendar_days": 28,
                        "due_date": "2025-05-21",
                        "due_interest": 0.0,
                        "due_principal": 577.4632222376,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 5,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.8184725787,
                        "principal_amortization_amount": 93.0215274213,
                        "tax_amount": 1.4797864582180404,
                        "total_amount": 101.84,
                        "workdays": 19.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-06-21",
                        "calendar_days": 31,
                        "due_date": "2025-06-21",
                        "due_interest": 0.0,
                        "due_principal": 484.4416948163,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 6,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.1972396908,
                        "principal_amortization_amount": 93.6427603092,
                        "tax_amount": 1.72770892770474,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-07-21",
                        "calendar_days": 31,
                        "due_date": "2025-07-21",
                        "due_interest": 0.0,
                        "due_principal": 390.7989345071,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 7,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 6.6127072945,
                        "principal_amortization_amount": 95.2272927055,
                        "tax_amount": 1.999011328473856,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-08-21",
                        "calendar_days": 30,
                        "due_date": "2025-08-21",
                        "due_interest": 0.0,
                        "due_principal": 295.5716418016,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 8,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 4.8387153664,
                        "principal_amortization_amount": 97.0012846336,
                        "tax_amount": 2.274874127227187,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-09-21",
                        "calendar_days": 33,
                        "due_date": "2025-09-21",
                        "due_interest": 0.0,
                        "due_principal": 198.570357168,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 9,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.5787172455,
                        "principal_amortization_amount": 98.2612827545,
                        "tax_amount": 2.570318634292211,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-10-21",
                        "calendar_days": 28,
                        "due_date": "2025-10-21",
                        "due_interest": 0.0,
                        "due_principal": 100.3090744135,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 10,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.5318141716,
                        "principal_amortization_amount": 100.3081858284,
                        "tax_amount": 2.8541691195612935,
                        "total_amount": 101.84,
                        "workdays": 20.0,
                        "installment_status": null,
                        "installment_type": null
                    }
                ],
                "first_due_date": "2025-01-21",
                "prefixed_interest_rate": {
                    "monthly_rate": 0.0166,
                    "daily_rate": 0.00054142,
                    "annual_rate": 0.21843191,
                    "interest_base": "calendar_days_365"
                }
            },
            {
                "disbursement_date": "2024-11-08",
                "contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 4.55
                    },
                    {
                        "fee_type": "ted_fee",
                        "fee_amount": 1.5
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0
                    }
                ],
                "contract_fee_amount": 6.05,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "assignment_amount": 914.79,
                "issue_amount": 910.24,
                "cet": "2,0200%",
                "annual_cet": "27,0539%",
                "base_iof": 16.187351160427028,
                "additional_iof": 3.458912,
                "total_iof": 19.65,
                "total_pre_fixed_amount": 108.1583324947,
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-01-21",
                        "calendar_days": 73,
                        "due_date": "2025-01-21",
                        "due_interest": 0.0,
                        "due_principal": 910.24,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 36.6863463961,
                        "principal_amortization_amount": 65.1536536039,
                        "tax_amount": 0.3900097704729454,
                        "total_amount": 101.84,
                        "workdays": 48.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-02-21",
                        "calendar_days": 31,
                        "due_date": "2025-02-21",
                        "due_interest": 0.0,
                        "due_principal": 845.0863463961,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 2,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 14.2997636051,
                        "principal_amortization_amount": 87.5402363949,
                        "tax_amount": 0.7465431359757072,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-03-21",
                        "calendar_days": 28,
                        "due_date": "2025-03-21",
                        "due_interest": 0.0,
                        "due_principal": 757.5461100012,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 3,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 11.5685715131,
                        "principal_amortization_amount": 90.2714284869,
                        "tax_amount": 0.9770979419422056,
                        "total_amount": 101.84,
                        "workdays": 18.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-04-21",
                        "calendar_days": 33,
                        "due_date": "2025-04-21",
                        "due_interest": 0.0,
                        "due_principal": 667.2746815143,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 4,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 12.025984633,
                        "principal_amortization_amount": 89.814015367,
                        "tax_amount": 1.21518362791551,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-05-21",
                        "calendar_days": 28,
                        "due_date": "2025-05-21",
                        "due_interest": 0.0,
                        "due_principal": 577.4606661473,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 5,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.8184725787,
                        "principal_amortization_amount": 93.0215274213,
                        "tax_amount": 1.4721586929694939,
                        "total_amount": 101.84,
                        "workdays": 19.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-06-21",
                        "calendar_days": 31,
                        "due_date": "2025-06-21",
                        "due_interest": 0.0,
                        "due_principal": 484.439138726,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 6,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.1972396908,
                        "principal_amortization_amount": 93.6427603092,
                        "tax_amount": 1.7200302213593857,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-07-21",
                        "calendar_days": 31,
                        "due_date": "2025-07-21",
                        "due_interest": 0.0,
                        "due_principal": 390.7963784168,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 7,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 6.6127072945,
                        "principal_amortization_amount": 95.2272927055,
                        "tax_amount": 1.991202690472005,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-08-21",
                        "calendar_days": 30,
                        "due_date": "2025-08-21",
                        "due_interest": 0.0,
                        "due_principal": 295.5690857113,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 8,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 4.8387153664,
                        "principal_amortization_amount": 97.0012846336,
                        "tax_amount": 2.266920021887232,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-09-21",
                        "calendar_days": 33,
                        "due_date": "2025-09-21",
                        "due_interest": 0.0,
                        "due_principal": 198.5678010777,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 9,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.5787172455,
                        "principal_amortization_amount": 98.2612827545,
                        "tax_amount": 2.562261209106342,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-10-21",
                        "calendar_days": 28,
                        "due_date": "2025-10-21",
                        "due_interest": 0.0,
                        "due_principal": 100.3065183232,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 10,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.5318141715,
                        "principal_amortization_amount": 100.3081858285,
                        "tax_amount": 2.845943848326202,
                        "total_amount": 101.84,
                        "workdays": 20.0,
                        "installment_status": null,
                        "installment_type": null
                    }
                ],
                "first_due_date": "2025-01-21",
                "prefixed_interest_rate": {
                    "monthly_rate": 0.0166,
                    "daily_rate": 0.00054142,
                    "annual_rate": 0.21843191,
                    "interest_base": "calendar_days_365"
                }
            },
            {
                "disbursement_date": "2024-11-09",
                "contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 4.55
                    },
                    {
                        "fee_type": "ted_fee",
                        "fee_amount": 1.5
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0
                    }
                ],
                "contract_fee_amount": 6.05,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "assignment_amount": 915.28,
                "issue_amount": 910.73,
                "cet": "2,0200%",
                "annual_cet": "27,0599%",
                "base_iof": 16.115620969325082,
                "additional_iof": 3.460774,
                "total_iof": 19.58,
                "total_pre_fixed_amount": 107.6655097248,
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-01-21",
                        "calendar_days": 72,
                        "due_date": "2025-01-21",
                        "due_interest": 0.0,
                        "due_principal": 910.73,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 36.1935236262,
                        "principal_amortization_amount": 65.6464763738,
                        "tax_amount": 0.3875767965109152,
                        "total_amount": 101.84,
                        "workdays": 48.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-02-21",
                        "calendar_days": 31,
                        "due_date": "2025-02-21",
                        "due_interest": 0.0,
                        "due_principal": 845.0835236262,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 2,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 14.2997636051,
                        "principal_amortization_amount": 87.5402363949,
                        "tax_amount": 0.7393648365913253,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-03-21",
                        "calendar_days": 28,
                        "due_date": "2025-03-21",
                        "due_interest": 0.0,
                        "due_principal": 757.5432872313,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 3,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 11.5685715131,
                        "principal_amortization_amount": 90.2714284869,
                        "tax_amount": 0.9696956848062798,
                        "total_amount": 101.84,
                        "workdays": 18.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-04-21",
                        "calendar_days": 33,
                        "due_date": "2025-04-21",
                        "due_interest": 0.0,
                        "due_principal": 667.2718587444,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 4,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 12.025984633,
                        "principal_amortization_amount": 89.814015367,
                        "tax_amount": 1.207818878655416,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-05-21",
                        "calendar_days": 28,
                        "due_date": "2025-05-21",
                        "due_interest": 0.0,
                        "due_principal": 577.4578433774,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 5,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.8184725787,
                        "principal_amortization_amount": 93.0215274213,
                        "tax_amount": 1.4645309277209473,
                        "total_amount": 101.84,
                        "workdays": 19.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-06-21",
                        "calendar_days": 31,
                        "due_date": "2025-06-21",
                        "due_interest": 0.0,
                        "due_principal": 484.4363159561,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 6,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.1972396908,
                        "principal_amortization_amount": 93.6427603092,
                        "tax_amount": 1.7123515150140312,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-07-21",
                        "calendar_days": 31,
                        "due_date": "2025-07-21",
                        "due_interest": 0.0,
                        "due_principal": 390.7935556469,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 7,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 6.6127072945,
                        "principal_amortization_amount": 95.2272927055,
                        "tax_amount": 1.983394052470154,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-08-21",
                        "calendar_days": 30,
                        "due_date": "2025-08-21",
                        "due_interest": 0.0,
                        "due_principal": 295.5662629414,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 8,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 4.8387153664,
                        "principal_amortization_amount": 97.0012846336,
                        "tax_amount": 2.2589659165472766,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-09-21",
                        "calendar_days": 33,
                        "due_date": "2025-09-21",
                        "due_interest": 0.0,
                        "due_principal": 198.5649783078,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 9,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.5787172455,
                        "principal_amortization_amount": 98.2612827545,
                        "tax_amount": 2.554203783920473,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-10-21",
                        "calendar_days": 28,
                        "due_date": "2025-10-21",
                        "due_interest": 0.0,
                        "due_principal": 100.3036955533,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 10,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.5318141715,
                        "principal_amortization_amount": 100.3081858285,
                        "tax_amount": 2.837718577088265,
                        "total_amount": 101.84,
                        "workdays": 20.0,
                        "installment_status": null,
                        "installment_type": null
                    }
                ],
                "first_due_date": "2025-01-21",
                "prefixed_interest_rate": {
                    "monthly_rate": 0.0166,
                    "daily_rate": 0.00054142,
                    "annual_rate": 0.21843191,
                    "interest_base": "calendar_days_365"
                }
            },
            {
                "disbursement_date": "2024-11-10",
                "contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 4.56
                    },
                    {
                        "fee_type": "ted_fee",
                        "fee_amount": 1.5
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0
                    }
                ],
                "contract_fee_amount": 6.06,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "assignment_amount": 915.79,
                "issue_amount": 911.23,
                "cet": "2,0200%",
                "annual_cet": "27,0635%",
                "base_iof": 16.0438115087348,
                "additional_iof": 3.462674,
                "total_iof": 19.51,
                "total_pre_fixed_amount": 107.1724201311,
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-01-21",
                        "calendar_days": 71,
                        "due_date": "2025-01-21",
                        "due_interest": 0.0,
                        "due_principal": 911.23,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 35.7004340324,
                        "principal_amortization_amount": 66.1395659676,
                        "tax_amount": 0.3850645530633672,
                        "total_amount": 101.84,
                        "workdays": 48.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-02-21",
                        "calendar_days": 31,
                        "due_date": "2025-02-21",
                        "due_interest": 0.0,
                        "due_principal": 845.0904340324,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 2,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 14.2997636051,
                        "principal_amortization_amount": 87.5402363949,
                        "tax_amount": 0.7321865372069436,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-03-21",
                        "calendar_days": 28,
                        "due_date": "2025-03-21",
                        "due_interest": 0.0,
                        "due_principal": 757.5501976375,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 3,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 11.5685715131,
                        "principal_amortization_amount": 90.2714284869,
                        "tax_amount": 0.962293427670354,
                        "total_amount": 101.84,
                        "workdays": 18.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-04-21",
                        "calendar_days": 33,
                        "due_date": "2025-04-21",
                        "due_interest": 0.0,
                        "due_principal": 667.2787691506,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 4,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 12.025984633,
                        "principal_amortization_amount": 89.814015367,
                        "tax_amount": 1.200454129395322,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-05-21",
                        "calendar_days": 28,
                        "due_date": "2025-05-21",
                        "due_interest": 0.0,
                        "due_principal": 577.4647537836,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 5,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.8184725787,
                        "principal_amortization_amount": 93.0215274213,
                        "tax_amount": 1.4569031624724007,
                        "total_amount": 101.84,
                        "workdays": 19.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-06-21",
                        "calendar_days": 31,
                        "due_date": "2025-06-21",
                        "due_interest": 0.0,
                        "due_principal": 484.4432263623,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 6,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.1972396908,
                        "principal_amortization_amount": 93.6427603092,
                        "tax_amount": 1.7046728086686769,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-07-21",
                        "calendar_days": 31,
                        "due_date": "2025-07-21",
                        "due_interest": 0.0,
                        "due_principal": 390.8004660531,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 7,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 6.6127072945,
                        "principal_amortization_amount": 95.2272927055,
                        "tax_amount": 1.975585414468303,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-08-21",
                        "calendar_days": 30,
                        "due_date": "2025-08-21",
                        "due_interest": 0.0,
                        "due_principal": 295.5731733476,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 8,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 4.8387153664,
                        "principal_amortization_amount": 97.0012846336,
                        "tax_amount": 2.2510118112073214,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-09-21",
                        "calendar_days": 33,
                        "due_date": "2025-09-21",
                        "due_interest": 0.0,
                        "due_principal": 198.571888714,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 9,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.5787172455,
                        "principal_amortization_amount": 98.2612827545,
                        "tax_amount": 2.546146358734604,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-10-21",
                        "calendar_days": 28,
                        "due_date": "2025-10-21",
                        "due_interest": 0.0,
                        "due_principal": 100.3106059595,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 10,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.5318141716,
                        "principal_amortization_amount": 100.3081858284,
                        "tax_amount": 2.829493305847507,
                        "total_amount": 101.84,
                        "workdays": 20.0,
                        "installment_status": null,
                        "installment_type": null
                    }
                ],
                "first_due_date": "2025-01-21",
                "prefixed_interest_rate": {
                    "monthly_rate": 0.0166,
                    "daily_rate": 0.00054142,
                    "annual_rate": 0.21843191,
                    "interest_base": "calendar_days_365"
                }
            },
            {
                "disbursement_date": "2024-11-11",
                "contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 4.56
                    },
                    {
                        "fee_type": "ted_fee",
                        "fee_amount": 1.5
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0
                    }
                ],
                "contract_fee_amount": 6.06,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "assignment_amount": 916.28,
                "issue_amount": 911.72,
                "cet": "2,0200%",
                "annual_cet": "27,0698%",
                "base_iof": 15.971922713858204,
                "additional_iof": 3.464536,
                "total_iof": 19.44,
                "total_pre_fixed_amount": 106.6790635687,
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-01-21",
                        "calendar_days": 70,
                        "due_date": "2025-01-21",
                        "due_interest": 0.0,
                        "due_principal": 911.72,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 35.2070774702,
                        "principal_amortization_amount": 66.6329225298,
                        "tax_amount": 0.382472975321052,
                        "total_amount": 101.84,
                        "workdays": 47.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-02-21",
                        "calendar_days": 31,
                        "due_date": "2025-02-21",
                        "due_interest": 0.0,
                        "due_principal": 845.0870774702,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 2,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 14.2997636051,
                        "principal_amortization_amount": 87.5402363949,
                        "tax_amount": 0.7250082378225619,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-03-21",
                        "calendar_days": 28,
                        "due_date": "2025-03-21",
                        "due_interest": 0.0,
                        "due_principal": 757.5468410753,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 3,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 11.5685715131,
                        "principal_amortization_amount": 90.2714284869,
                        "tax_amount": 0.9548911705344282,
                        "total_amount": 101.84,
                        "workdays": 18.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-04-21",
                        "calendar_days": 33,
                        "due_date": "2025-04-21",
                        "due_interest": 0.0,
                        "due_principal": 667.2754125884,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 4,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 12.025984633,
                        "principal_amortization_amount": 89.814015367,
                        "tax_amount": 1.193089380135228,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-05-21",
                        "calendar_days": 28,
                        "due_date": "2025-05-21",
                        "due_interest": 0.0,
                        "due_principal": 577.4613972214,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 5,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.8184725787,
                        "principal_amortization_amount": 93.0215274213,
                        "tax_amount": 1.449275397223854,
                        "total_amount": 101.84,
                        "workdays": 19.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-06-21",
                        "calendar_days": 31,
                        "due_date": "2025-06-21",
                        "due_interest": 0.0,
                        "due_principal": 484.4398698001,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 6,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.1972396908,
                        "principal_amortization_amount": 93.6427603092,
                        "tax_amount": 1.6969941023233224,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-07-21",
                        "calendar_days": 31,
                        "due_date": "2025-07-21",
                        "due_interest": 0.0,
                        "due_principal": 390.7971094909,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 7,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 6.6127072945,
                        "principal_amortization_amount": 95.2272927055,
                        "tax_amount": 1.967776776466452,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-08-21",
                        "calendar_days": 30,
                        "due_date": "2025-08-21",
                        "due_interest": 0.0,
                        "due_principal": 295.5698167854,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 8,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 4.8387153664,
                        "principal_amortization_amount": 97.0012846336,
                        "tax_amount": 2.243057705867366,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-09-21",
                        "calendar_days": 33,
                        "due_date": "2025-09-21",
                        "due_interest": 0.0,
                        "due_principal": 198.5685321518,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 9,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.5787172455,
                        "principal_amortization_amount": 98.2612827545,
                        "tax_amount": 2.538088933548735,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-10-21",
                        "calendar_days": 28,
                        "due_date": "2025-10-21",
                        "due_interest": 0.0,
                        "due_principal": 100.3072493973,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 10,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.5318141714,
                        "principal_amortization_amount": 100.3081858286,
                        "tax_amount": 2.8212680346152035,
                        "total_amount": 101.84,
                        "workdays": 20.0,
                        "installment_status": null,
                        "installment_type": null
                    }
                ],
                "first_due_date": "2025-01-21",
                "prefixed_interest_rate": {
                    "monthly_rate": 0.0166,
                    "daily_rate": 0.00054142,
                    "annual_rate": 0.21843191,
                    "interest_base": "calendar_days_365"
                }
            },
            {
                "disbursement_date": "2024-11-12",
                "contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 4.56
                    },
                    {
                        "fee_type": "ted_fee",
                        "fee_amount": 1.5
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0
                    }
                ],
                "contract_fee_amount": 6.06,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "assignment_amount": 916.77,
                "issue_amount": 912.21,
                "cet": "2,0200%",
                "annual_cet": "27,0762%",
                "base_iof": 15.899954519820076,
                "additional_iof": 3.466398,
                "total_iof": 19.37,
                "total_pre_fixed_amount": 106.1854398936,
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-01-21",
                        "calendar_days": 69,
                        "due_date": "2025-01-21",
                        "due_interest": 0.0,
                        "due_principal": 912.21,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 34.7134537949,
                        "principal_amortization_amount": 67.1265462051,
                        "tax_amount": 0.3798019984284558,
                        "total_amount": 101.84,
                        "workdays": 46.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-02-21",
                        "calendar_days": 31,
                        "due_date": "2025-02-21",
                        "due_interest": 0.0,
                        "due_principal": 845.0834537949,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 2,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 14.2997636051,
                        "principal_amortization_amount": 87.5402363949,
                        "tax_amount": 0.71782993843818,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-03-21",
                        "calendar_days": 28,
                        "due_date": "2025-03-21",
                        "due_interest": 0.0,
                        "due_principal": 757.5432174,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 3,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 11.5685715131,
                        "principal_amortization_amount": 90.2714284869,
                        "tax_amount": 0.9474889133985024,
                        "total_amount": 101.84,
                        "workdays": 18.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-04-21",
                        "calendar_days": 33,
                        "due_date": "2025-04-21",
                        "due_interest": 0.0,
                        "due_principal": 667.2717889131,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 4,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 12.025984633,
                        "principal_amortization_amount": 89.814015367,
                        "tax_amount": 1.185724630875134,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-05-21",
                        "calendar_days": 28,
                        "due_date": "2025-05-21",
                        "due_interest": 0.0,
                        "due_principal": 577.4577735461,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 5,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.8184725787,
                        "principal_amortization_amount": 93.0215274213,
                        "tax_amount": 1.4416476319753073,
                        "total_amount": 101.84,
                        "workdays": 19.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-06-21",
                        "calendar_days": 31,
                        "due_date": "2025-06-21",
                        "due_interest": 0.0,
                        "due_principal": 484.4362461248,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 6,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.1972396908,
                        "principal_amortization_amount": 93.6427603092,
                        "tax_amount": 1.689315395977968,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-07-21",
                        "calendar_days": 31,
                        "due_date": "2025-07-21",
                        "due_interest": 0.0,
                        "due_principal": 390.7934858156,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 7,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 6.6127072945,
                        "principal_amortization_amount": 95.2272927055,
                        "tax_amount": 1.959968138464601,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-08-21",
                        "calendar_days": 30,
                        "due_date": "2025-08-21",
                        "due_interest": 0.0,
                        "due_principal": 295.5661931101,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 8,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 4.8387153664,
                        "principal_amortization_amount": 97.0012846336,
                        "tax_amount": 2.2351036005274114,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-09-21",
                        "calendar_days": 33,
                        "due_date": "2025-09-21",
                        "due_interest": 0.0,
                        "due_principal": 198.5649084765,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 9,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.5787172455,
                        "principal_amortization_amount": 98.2612827545,
                        "tax_amount": 2.530031508362866,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-10-21",
                        "calendar_days": 28,
                        "due_date": "2025-10-21",
                        "due_interest": 0.0,
                        "due_principal": 100.303625722,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 10,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.5318141716,
                        "principal_amortization_amount": 100.3081858284,
                        "tax_amount": 2.8130427633716497,
                        "total_amount": 101.84,
                        "workdays": 20.0,
                        "installment_status": null,
                        "installment_type": null
                    }
                ],
                "first_due_date": "2025-01-21",
                "prefixed_interest_rate": {
                    "monthly_rate": 0.0166,
                    "daily_rate": 0.00054142,
                    "annual_rate": 0.21843191,
                    "interest_base": "calendar_days_365"
                }
            },
            {
                "disbursement_date": "2024-11-13",
                "contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 4.56
                    },
                    {
                        "fee_type": "ted_fee",
                        "fee_amount": 1.5
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0
                    }
                ],
                "contract_fee_amount": 6.06,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "assignment_amount": 917.27,
                "issue_amount": 912.71,
                "cet": "2,0200%",
                "annual_cet": "27,0802%",
                "base_iof": 15.827906861727051,
                "additional_iof": 3.468298,
                "total_iof": 19.3,
                "total_pre_fixed_amount": 105.691548961,
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-01-21",
                        "calendar_days": 68,
                        "due_date": "2025-01-21",
                        "due_interest": 0.0,
                        "due_principal": 912.71,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 34.2195628621,
                        "principal_amortization_amount": 67.6204371379,
                        "tax_amount": 0.3770515574809304,
                        "total_amount": 101.84,
                        "workdays": 45.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-02-21",
                        "calendar_days": 31,
                        "due_date": "2025-02-21",
                        "due_interest": 0.0,
                        "due_principal": 845.0895628621,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 2,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 14.2997636051,
                        "principal_amortization_amount": 87.5402363949,
                        "tax_amount": 0.7106516390537982,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-03-21",
                        "calendar_days": 28,
                        "due_date": "2025-03-21",
                        "due_interest": 0.0,
                        "due_principal": 757.5493264672,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 3,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 11.5685715131,
                        "principal_amortization_amount": 90.2714284869,
                        "tax_amount": 0.9400866562625766,
                        "total_amount": 101.84,
                        "workdays": 18.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-04-21",
                        "calendar_days": 33,
                        "due_date": "2025-04-21",
                        "due_interest": 0.0,
                        "due_principal": 667.2778979803,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 4,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 12.025984633,
                        "principal_amortization_amount": 89.814015367,
                        "tax_amount": 1.17835988161504,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-05-21",
                        "calendar_days": 28,
                        "due_date": "2025-05-21",
                        "due_interest": 0.0,
                        "due_principal": 577.4638826133,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 5,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.8184725787,
                        "principal_amortization_amount": 93.0215274213,
                        "tax_amount": 1.4340198667267607,
                        "total_amount": 101.84,
                        "workdays": 19.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-06-21",
                        "calendar_days": 31,
                        "due_date": "2025-06-21",
                        "due_interest": 0.0,
                        "due_principal": 484.442355192,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 6,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.1972396908,
                        "principal_amortization_amount": 93.6427603092,
                        "tax_amount": 1.6816366896326136,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-07-21",
                        "calendar_days": 31,
                        "due_date": "2025-07-21",
                        "due_interest": 0.0,
                        "due_principal": 390.7995948828,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 7,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 6.6127072945,
                        "principal_amortization_amount": 95.2272927055,
                        "tax_amount": 1.95215950046275,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-08-21",
                        "calendar_days": 30,
                        "due_date": "2025-08-21",
                        "due_interest": 0.0,
                        "due_principal": 295.5723021773,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 8,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 4.8387153664,
                        "principal_amortization_amount": 97.0012846336,
                        "tax_amount": 2.227149495187456,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-09-21",
                        "calendar_days": 33,
                        "due_date": "2025-09-21",
                        "due_interest": 0.0,
                        "due_principal": 198.5710175437,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 9,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.5787172455,
                        "principal_amortization_amount": 98.2612827545,
                        "tax_amount": 2.521974083176997,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-10-21",
                        "calendar_days": 28,
                        "due_date": "2025-10-21",
                        "due_interest": 0.0,
                        "due_principal": 100.3097347892,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 10,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.5318141718,
                        "principal_amortization_amount": 100.3081858282,
                        "tax_amount": 2.8048174921281284,
                        "total_amount": 101.84,
                        "workdays": 20.0,
                        "installment_status": null,
                        "installment_type": null
                    }
                ],
                "first_due_date": "2025-01-21",
                "prefixed_interest_rate": {
                    "monthly_rate": 0.0166,
                    "daily_rate": 0.00054142,
                    "annual_rate": 0.21843191,
                    "interest_base": "calendar_days_365"
                }
            },
            {
                "disbursement_date": "2024-11-14",
                "contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 4.57
                    },
                    {
                        "fee_type": "ted_fee",
                        "fee_amount": 1.5
                    }
                ],
                "external_contract_fees": [
                    {
                        "fee_type": "spread",
                        "fee_amount": 0.0,
                        "tax_amount": 0.0,
                        "net_fee_amount": 0.0
                    }
                ],
                "contract_fee_amount": 6.07,
                "external_contract_fee_amount": 0.0,
                "net_external_contract_fee_amount": 0.0,
                "assignment_amount": 917.77,
                "issue_amount": 913.2,
                "cet": "2,0200%",
                "annual_cet": "27,0870%",
                "base_iof": 15.755779674642707,
                "additional_iof": 3.47016,
                "total_iof": 19.23,
                "total_pre_fixed_amount": 105.1973906257,
                "installments": [
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-01-21",
                        "calendar_days": 67,
                        "due_date": "2025-01-21",
                        "due_interest": 0.0,
                        "due_principal": 913.2,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 1,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 33.7254045271,
                        "principal_amortization_amount": 68.1145954729,
                        "tax_amount": 0.3742215875281126,
                        "total_amount": 101.84,
                        "workdays": 44.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-02-21",
                        "calendar_days": 31,
                        "due_date": "2025-02-21",
                        "due_interest": 0.0,
                        "due_principal": 845.0854045271,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 2,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 14.2997636051,
                        "principal_amortization_amount": 87.5402363949,
                        "tax_amount": 0.7034733396694164,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-03-21",
                        "calendar_days": 28,
                        "due_date": "2025-03-21",
                        "due_interest": 0.0,
                        "due_principal": 757.5451681322,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 3,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 11.5685715131,
                        "principal_amortization_amount": 90.2714284869,
                        "tax_amount": 0.9326843991266508,
                        "total_amount": 101.84,
                        "workdays": 18.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-04-21",
                        "calendar_days": 33,
                        "due_date": "2025-04-21",
                        "due_interest": 0.0,
                        "due_principal": 667.2737396453,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 4,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 12.025984633,
                        "principal_amortization_amount": 89.814015367,
                        "tax_amount": 1.170995132354946,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-05-21",
                        "calendar_days": 28,
                        "due_date": "2025-05-21",
                        "due_interest": 0.0,
                        "due_principal": 577.4597242783,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 5,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.8184725787,
                        "principal_amortization_amount": 93.0215274213,
                        "tax_amount": 1.4263921014782142,
                        "total_amount": 101.84,
                        "workdays": 19.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-06-21",
                        "calendar_days": 31,
                        "due_date": "2025-06-21",
                        "due_interest": 0.0,
                        "due_principal": 484.438196857,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 6,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 8.1972396908,
                        "principal_amortization_amount": 93.6427603092,
                        "tax_amount": 1.6739579832872593,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-07-21",
                        "calendar_days": 31,
                        "due_date": "2025-07-21",
                        "due_interest": 0.0,
                        "due_principal": 390.7954365478,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 7,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 6.6127072945,
                        "principal_amortization_amount": 95.2272927055,
                        "tax_amount": 1.944350862460899,
                        "total_amount": 101.84,
                        "workdays": 21.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-08-21",
                        "calendar_days": 30,
                        "due_date": "2025-08-21",
                        "due_interest": 0.0,
                        "due_principal": 295.5681438423,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 8,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 4.8387153664,
                        "principal_amortization_amount": 97.0012846336,
                        "tax_amount": 2.219195389847501,
                        "total_amount": 101.84,
                        "workdays": 22.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-09-21",
                        "calendar_days": 33,
                        "due_date": "2025-09-21",
                        "due_interest": 0.0,
                        "due_principal": 198.5668592087,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 9,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 3.5787172455,
                        "principal_amortization_amount": 98.2612827545,
                        "tax_amount": 2.513916657991128,
                        "total_amount": 101.84,
                        "workdays": 23.0,
                        "installment_status": null,
                        "installment_type": null
                    },
                    {
                        "additional_costs": [],
                        "business_due_date": "2025-10-21",
                        "calendar_days": 28,
                        "due_date": "2025-10-21",
                        "due_interest": 0.0,
                        "due_principal": 100.3055764542,
                        "fine_amount": null,
                        "has_interest": true,
                        "installment_number": 10,
                        "post_fixed_amount": null,
                        "pre_fixed_amount": 1.5318141715,
                        "principal_amortization_amount": 100.3081858285,
                        "tax_amount": 2.79659222089858,
                        "total_amount": 101.84,
                        "workdays": 20.0,
                        "installment_status": null,
                        "installment_type": null
                    }
                ],
                "first_due_date": "2025-01-21",
                "prefixed_interest_rate": {
                    "monthly_rate": 0.0166,
                    "daily_rate": 0.00054142,
                    "annual_rate": 0.21843191,
                    "interest_base": "calendar_days_365"
                }
            }
        ]
    }
} 
```

### Objeto Installments

| Campo | Descrição |
|-------|-----------|
| additional_costs | Custos adicionais |
| business_due_date | Data de vencimento em dia útil |
| calendar_days | Dias corridos |
| due_date | Data de vencimento |
| due_interest | Juros do vencimento |
| due_principal | Principal do vencimento |
| fine_amount | Multa do vencimento |
| has_interest | Indica se o vencimento possui juros |
| installment_number | Número da parcela |
| installment_status | Status da parcela |
| installment_type | Tipo de parcela |
| post_fixed_amount | Valor da parcela após juros |
| pre_fixed_amount | Valor da parcela antes de juros |
| principal_amortization_amount | Valor da amortização do principal da parcela |
| tax_amount | Valor dos juros da parcela |
| total_amount | Valor total da parcela |
| workdays | Dias úteis |

### Objeto Prefixed Interest Rate

| Campo | Descrição |
|-------|-----------|
| monthly_rate | Taxa mensal |
| daily_rate | Taxa diária |
| annual_rate | Taxa anual |
| interest_base | Base de cálculo da taxa de juros |

### Webhooks

Caso a operação não seja assinada ou averbada até a última opção de data de desembolso o parceiro receberá um webhook
informando a respeito do cancelamento da operação:

WEBHOOK TYPE
debt

STATUS
Canceled

**Webhook Body**

```json title="Webhook Body"
{
    "key": "<Debt Key>",
    "status": "canceled",
    "webhook_type": "debt",
    "event_datetime": "2025-03-18 13:46:31",
    "data": {
        "cancel_reason": "<CANCEL_REASON>",
        "cancel_reason_enumerator": "<CANCEL_REASON_ENUMERATOR>"
    }
}
```

### Objeto Data

| Campo | Descrição |
|-------|-----------|
| cancel_reason | Motivo do cancelamento |
| cancel_reason_enumerator | Enumerador do motivo do cancelamento |

## Webhooks

Após a assinatura do contrato, o parceiro receberá um webhook informando a respeito da assinatura do contrato. Com o seguinte body:

```json
{
    "key": "<Debt Key>",
    "status": "signed",
    "signers": [
        {
            "id": "3271efd3-89ba-43aa-b032-af9a459e6096",
            "images": {
                "face_image_url": "https://qisign-face-images-bucket-sandbox.s3.amazonaws.com/fad7f924-d210-4ec4-9565-a57662a0a65a.jpeg",
                "document_back_url": "https://qisign-personal-documents-bucket-sandbox.s3.amazonaws.com/8c7b68ba-07ad-4188-82ae-679833b2843b.jpeg",
                "document_front_url": "https://qisign-personal-documents-bucket-sandbox.s3.amazonaws.com/f63cd291-5668-4926-be5d-9290aeda3f6e.jpeg",
                "document_back_template": "cnh_back",
                "document_front_template": "cnh_front"
            },
            "biometry": {
                "face_validation": {
                    "score": 80,
                    "provider": "qitech",
                    "available": true
                },
                "fraud_base_flag": false
            },
            "document": {
                "template": "cnh_front",
                "face_match_score": 100
            },
            "liveness": {
                "result": "live"
            },
            "signed_at": "2025-04-09T19:59:39Z",
            "ip_address": "182.224.219.198",
            "signer_data": {
                "name": "Nome Trabalhador",
                "email": "exemplo@qitech.com.br",
                "phone": {
                    "number": "829549234",
                    "area_code": "11",
                    "international_dial_code": "55"
                },
                "address": {
                    "uf": "SP",
                    "city": "Sao Paulo",
                    "number": "123",
                    "street": "Rua tal do sal",
                    "complement": "Ap 23",
                    "postal_code": "00000-000",
                    "neighborhood": "Pinheiros"
                },
                "pix_key": "pix03@pix03.com",
                "birthdate": "1996-03-13",
                "document_number": "504.856.400-66",
                "document_submission_method": "email",
                "authentication_submission_method": "sms"
            }
        }
    ],
    "webhook_type": "laas.credit_operation.status_change",
    "event_datetime": "2025-04-09 20:00:19",
    "signed_contract_url": "https://storage.googleapis.com/sandbox-doc-api/documents/9b55450e-fca5-44f2-9118-5851ed4bd92e/CCB-0000195364-2230409195718_signed.pdf"
}
```

### Objeto Signers

| Campo | Descrição |
|-------|-----------|
| id | ID do signatário |
| images | Imagens do signatário |

### Objeto Images

| Campo | Descrição |
|-------|-----------|
| face_image_url | URL da imagem da face do signatário |
| document_back_url | URL da imagem do verso do documento do signatário |
| document_front_url | URL da imagem do documento do signatário |
| document_back_template | Template do verso do documento do signatário |
| document_front_template | Template do documento do signatário |

### Objeto Biometry

| Campo | Descrição |
|-------|-----------|
| face_validation | Validação da rosto do signatário (true ou false) |
| face_validation.score | Pontuação da rosto do signatário (0 a 100) |
| face_validation.available | Disponibilidade da validação da rosto do signatário (true ou false) |
| face_validation.provider | Provedor da validação da rosto do signatário (qitech ou external) |
| fraud_base_flag | Flag de fraude base (true ou false) |

### Objeto Document

| Campo | Descrição |
|-------|-----------|
| template | Template do documento (cnh_front, cnh_back, rg_front, rg_back) |
| face_match_score | Pontuação da rosto do signatário (0 a 100) |

### Objeto Liveness

| Campo | Descrição |
|-------|-----------|
| result | Resultado da liveness (live ou spoof) |

### Objeto Signer Data

| Campo | Descrição |
|-------|-----------|
| name | Nome do signatário |
| email | Email do signatário |
| phone | Telefone do signatário |

### Objeto Address

| Campo | Descrição |
|-------|-----------|
| uf | Unidade Federativa |
| city | Cidade |
| number | Número |
| street | Rua |
| complement | Complemento |
| postal_code | CEP |
| neighborhood | Bairro |

## Enumeradores

### Status da reserva {#status-da-reserva}

ENUMERADOR
reservation_status

| Status                        | Descrição                                                                 |
| ----------------------------- | ------------------------------------------------------------------------- |
| pending_reservation           | A reserva foi criada e está pendente de averbação.                                      |
| pending_documents_submission  | A reserva já foi averbada e está pendente de envio de documentos. |
| reserved                      | A reserva foi averbada com sucesso. Fluxo de averbação concluído. |
| canceled                      | Em caso de envio de documentos inválidos, a reserva é cancelada. |
| settled                       | A reserva foi liquidada com sucesso. |
| pending_deletion              | A reserva está averbada e foi solicitada a exclusão. |
| deleted                       | A reserva foi excluída com sucesso. |

---

# QI FATURA

URL: /documentation/manual_qi_fatura/pix_parcelado

## Experiência de cartão com PIX Parcelado

---

:::caution API em desenvolvimento 
A API ainda está em fase final de desenvolvimento, sendo assim, este manual esta sujeito a alterações.
:::

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

## 1. Criar uma Carteira Digital

Para ser possível o lançamento de itens na fatura (entradas de pix lastreadas em ccb) é necessário, primeiramente, a criação de uma carteira digital por cliente.

### Request

ENDPOINT /card_invoice/wallet
MÉTODO POST

Testar no Playground

Request Body

```json
{
    "owner": {
        "person_type": "natural",
        "name": "\<NOME TITULAR DA CARTEIRA\>",
        "document_number": "\<CPF TITULAR DA CARTEIRA\>",
        "address": {
            "street": "\<RUA TITULAR DA CARTEIRA\>",
            "state": "\<ESTADO TITULAR DA CARTEIRA\>",
            "city": "\<CIDADE TITULAR DA CARTEIRA\>",
            "neighborhood": "\<BAIRRO TITULAR DA CARTEIRA\>",
            "number": "\<No. TITULAR DA CARTEIRA\>",
            "postal_code": "\<CEP TITULAR DA CARTEIRA\>",
            "complement": "\<COMPLEMENTO TITULAR DA CARTEIRA\>"
        },
        "phone": {
            "number": "\<CELULAR TITULAR DA CARTEIRA\>",
            "area_code": "\<DDD TITULAR DA CARTEIRA\>",
            "country_code": "55",
            },
        "email": "\<EMAIL TITULAR DA CARTEIRA\>",
        "document_identification_number":"\<NÚMERO DO DOCUMENTO DE IDENTIFICAÇÃO DO TITULAR DA CARTEIRA\>",
        "document_identification":"\<CHAVE DO DOCUMENTO DE IDENTICAÇÃO DO TITULAR\>",
        "document_identification_back":"\<CHAVE DO VERSO DO DOCUMENTO DE IDENTICAÇÃO DO TITULAR\>",
        "selfie":"\<CHAVE DA SELFIE DO TITULAR\>",
        "document_identification_type": "\<TIPO DO DOCUMENTO DE IDENTIFICAÇÃO DO TITULAR\>"

    },
    "invoice_configuration":{
        "closing_day": "\<DATA DE FECHAMENTO DA FATURA\>", 
        "due_day": "\<DATA DE VENCIMENTO DA FATURA\>", 
        "grace_months": "\<DIFERENÇA, EM MESES, ENTRE closing_day e due_day\>", 
        "issuing_and_due_day_difference": "\<DIAS ANTES DO VENCIMENTO QUE A FATURA DEVE SER EMITIDA\>", 
        "invoice_payment_type": "bankslip", 
        "delay_fine_percentage": "\<CONFIGURAÇÃO DE ATRASO - VALOR DA MORA\>", 
        "delay_monthly_interest_rate": "\<CONFIGURAÇÃO DE ATRASO -VALOR DOS JUROS POR DIA\>"
    },
    "invoice_authorization": {
        "signature": {
            "signer": {
                "name": "\<NOME ASSINANTE\>",
                "email": "\<EMAIL ASSINANTE\>",
                "phone": {
                    "number": "\<CELULAR ASSINANTE\>",
                    "area_code": "\<DDD ASSINANTE\>",
                    "country_code": "55",
                },
                "document_number": "CPF ASSINANTE"
                },
            "authentication_type": "opt_in",
            "authenticity": {
                "timestamp": "\<DATA E HORA DA ASSINATURA\>",
                "ip_address": "\<IP DO ASSINANTE\>",
                "fingerprint": {},
                "third_party_additional_data": {},
                "session_id": "\<ID DA SESSÃO DO ASSINANTE\>"
                },
            "signed_object": {
                "document_key": "\<CHAVE DO DOCUMENTO NA QI\>"
                }
            }
        },
    "limit": "\<VALOR DO LIMITE DA WALLET\>",
    "default_monthly_interest_rate": "\<TAXA DE JUROS MENSAL, DEFAULT DA CARTEIRA, CONSIDERADA PARA CADA ENTRADA (PIX)\>"
  }
```

### Request body details
#### Payload wallet

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---|---|
| `owner` | object  | Objeto Dono da carteira |**[Objeto owner](#objeto-owner)**  |
| `invoice_configuration` | object  | Objeto Configurações da Fatura para cada Carteira |**[Objeto invoicer_configuration](#objeto-invoicer_configuration)**  |
| `invoice_authorization` | object  | Objeto Autorização |**[Objeto invoice_authorization](#objeto-invoice_authorization)**  |
| `limit` | number  | Limite da carteira | |
| `default_monthly_interest_rate` | number  | Taxa de juros default da carteira. | |

#### Objeto owner

| Campo | Tipo | Descrição | Caracteres |
|---| ---| ---| ---| 
| `person_type` | string | Identificador de que o objeto enviado é uma pessoa física ou jurídica.|  |
| `name` | string |  Razão social em caso de operações PJ ou Nome da pessoa em caso de operações PF. | 100 |
| `document_number` | string | CPF da pessoa (apenas números). Limitado a 11 caracteres. |  |
| `address` | string | Endereço do cliente. | **[Objeto adress](#objeto-address)** |  |
| `phone` | string | Objeto com dados do telefone | **[Objeto phone](#objeto-phone)**|
| `email` | string |  Email do cliente. |  |

#### Objeto address 

| Campo | Descrição | Exemplo |  Máx. Caracteres | 
|---|---|---|---| 
| `street` | string | Rua do endereço  | 100 |
| `state` | string | Estado do endereço (com dois caracteres maiúsculos) | 2 |
| `city` | string | Cidade do endereço | 100 |
| `neighborhood` | string |Bairro do endereço | 100 |
| `number` | string | Número da rua | 10 |
| `postal_code` | string |CEP do endereço (http://www.buscacep.correios.com.br/sistemas/buscacep/) (apenas números) |  8 |
| `complement` | string |Complemento do endereço (texto livre) | 100 |

#### Objeto phone 

| Campo | Descrição | Exemplo |  Máx. Caracteres | 
| --- | --- | --- | --- | 
|`country_code` | string | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3 | 
| `area_code` | string | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2 |
| `number` | string |Número de telefone (apenas números) |  10 |

#### Objeto invoice_configuration

| Campo | Descrição | Exemplo |  Máx. Caracteres | 
| --- | --- | --- | --- | 
| `closing_day` | number |  Dia de fechamento da fatura (data de corte para registro de entradas me uma fatura).| |
| `due_day` | number |  Dia de vencimento da fatura. Opções: 1,5,10 | |
| `grace_months` | number |  Diferença de meses entre a data de fechamento e vencimento.| |
| `delay_fine_percentage` | number |  Valor da mora, em caso de atraso no pagamento da fatura.| |
| `delay_monthly_interest_rate` | number |  Valor do juros, por mês, em caso de atraso no pagamento da fatura.| |
| `issuing_and_due_day_difference` | number | Número de dia entre a emissão da fatura e vencimento, para fins de cálculo da data de emissão da fatura| |
| `invoice_payment_type` | string |  Meio de pagamento da fatura. Opções: 'bankslip'| |

:::info CONFIGURAÇÕES DA INVOICE 
Na configuração da invoice (invoice_configuration), os dados fixos, como "delay_fine_percentage", "grace_months", "delay_monthly_interest_rate",  "invoice_payment_type", "issuing_and_due_day_difference", podem estar diretamente configurado no setup inicial do parceiro na API, simplificando o payload de criação da wallet. As informações configuradas no setup inicial do parceiro na API serão fixas para todos os clientes. 
:::

:::caution 
O número de dias entre a data de vencimento da fatura “invoice_configuration.due_day“ e a data fechamento “invoice_configuration.closing_day“, precisa ser maior ou igual a 8 dias e menor ou igual a 10 dias.
:::

### Response

ENDPOINT /card_invoice/wallet
MÉTODO POST
HTTP STATUS 201

Response Body

```json
{
    "wallet_key": "0f4581d6-f4a4-4430-b94e-5db700e4baed",
    "status": "active"
}
```

### Response body details

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---|---|
| `wallet_key` | string  |  Identificador único da carteira (uuid) | |
| `status` | string  |  Status da carteira | |

## 1.1. Consultar carteiras existentes: 

#### QUERY PARAMETERS

| Enumerador                   | Descrição                                                   |
|------------------------------|-------------------------------------------------------------|
| **owner_document_number**    |  CPF do titular da carteira                                 |
| **page**                     |  Número da página da consulta                               |
| **page_size**                |  Tamanho da página requisitada na consulta                  |

### Request

ENDPOINT /card_invoice/wallets
MÉTODO GET

Testar no Playground

### Response

ENDPOINT /card_invoice/wallets
MÉTODO GET
HTTP STATUS 200

Response Body

```json
{
    "page": 1,
    "last_page": true,
    "data": [
        {
            "wallet_key": "0f4581d6-f4a4-4430-b94e-5db700e4baed",
            "owner": {
                "person_type": "natural",
                "name": "Nome Sobrenome",
                "document_number": "12345678911",
                "address": {
                    "street": "RUA DEZENOVE",
                    "state": "SP",
                    "city": "JARDINÓPOLIS",
                    "neighborhood": "JARDINS DO IMPÉRIO",
                    "number": "19",
                    "postal_code": "13348719",
                    "complement": ""
                },
                "phone": {
                            "number": "912345678",
                            "area_code": "21",
                            "country_code": "55"
                        },
                "email": "teste@teste.com.br"
            },
            "collaterals": [],
            "cards": [
                {"card_key":"067cba94-4d57-4a75-9766-7e5b95c87367"}
            ],
            "invoice_authorization": {
                "signature": {
                    "signer": {
                        "name": "Nome Sobrenome",
                        "document_number": "12345678911",
                        "email": "teste@teste.com.br",
                        "phone": {
                            "number": "912345678",
                            "area_code": "21",
                            "country_code": "55"
                        }
                    },
                    "authentication_type": "opt_in",
                    "authenticity": {
                        "timestamp": "2022-11-18T11:17:46",
                        "ip_address": "104.101.21.0",
                        "fingerprint": {
                            "browser": "Mozila"
                        },
                        "third_party_additional_data": {},
                        "session_id": "8df91773-c537-4662-b08b-025f03bf79dc"
                    },
                    "signed_object": {
                        "document_key": "27A0BA3D-A89D-4218-AB06-BC39B94CE23C"
                    }
                }
            },
            "interest_base": "calendar_days_365",
            "default_monthly_interest_rate": 0.035,
            "invoice_configuration": {
                "due_day": 10,
                "closing_day": 1,
                "grace_months": 1,
                "invoice_payment_type": "bankslip",
                "delay_fine_percentage": 0,
                "delay_monthly_interest_rate": 0,
                "issuing_and_due_day_difference": 9
            },
            "status": "active",
            "limit": 800,
            "current_limit": 800
}
    ]
}
```

## 1.2. Consultar carteira específica:
### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]
MÉTODO GET

Testar no Playground

### Response

ENDPOINT /card_invoice/wallet/[WALLET-KEY]
MÉTODO GET
HTTP STATUS 200

Response Body

```json
        {
            "wallet_key": "0f4581d6-f4a4-4430-b94e-5db700e4baed",
            "owner": {
                "person_type": "natural",
                "name": "Nome Sobrenome",
                "document_number": "12345678911",
                "address": {
                    "street": "RUA DEZENOVE",
                    "state": "SP",
                    "city": "JARDINÓPOLIS",
                    "neighborhood": "JARDINS DO IMPÉRIO",
                    "number": "19",
                    "postal_code": "13348719",
                    "complement": ""
                },
                "phone": {
                            "number": "912345678",
                            "area_code": "21",
                            "country_code": "55"
                        },
                "email": "teste@teste.com.br"
            },
            "collaterals": [],
            "cards": [
                {"card_key":"067cba94-4d57-4a75-9766-7e5b95c87367"}
            ],
            "invoice_authorization": {
                "signature": {
                    "signer": {
                        "name": "Nome Sobrenome",
                        "document_number": "12345678911",
                        "email": "teste@teste.com.br",
                        "phone": {
                            "number": "912345678",
                            "area_code": "21",
                            "country_code": "55"
                        }
                    },
                    "authentication_type": "opt_in",
                    "authenticity": {
                        "timestamp": "2022-11-18T11:17:46",
                        "ip_address": "104.101.21.0",
                        "fingerprint": {
                            "browser": "Mozila"
                        },
                        "third_party_additional_data": {},
                        "session_id": "8df91773-c537-4662-b08b-025f03bf79dc"
                    },
                    "signed_object": {
                        "document_key": "27A0BA3D-A89D-4218-AB06-BC39B94CE23C"
                    }
                }
            },
            "interest_base": "calendar_days_365",
            "default_monthly_interest_rate": 0.035,
            "invoice_configuration": {
                "due_day": 10,
                "closing_day": 1,
                "grace_months": 1,
                "invoice_payment_type": "bankslip",
                "delay_fine_percentage": 0,
                "delay_monthly_interest_rate": 0,
                "issuing_and_due_day_difference": 9
            },
            "status": "active",
            "limit": 800,
            "current_limit": 800
}
```

## 1.3. Alterar Limite de uma carteira:

### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]
MÉTODO PATCH

Testar no Playground

Request Body

```json
{
    "limit": 123
}
```

### Response

ENDPOINT /card_invoice/wallet/[WALLET-KEY]
MÉTODO PATCH
HTTP STATUS 200

Response Body

```json
        {
            "wallet_key": "0f4581d6-f4a4-4430-b94e-5db700e4baed",
            "owner": {
                "person_type": "natural",
                "name": "Nome Sobrenome",
                "document_number": "12345678911",
                "address": {
                    "street": "RUA DEZENOVE",
                    "state": "SP",
                    "city": "JARDINÓPOLIS",
                    "neighborhood": "JARDINS DO IMPÉRIO",
                    "number": "19",
                    "postal_code": "13348719",
                    "complement": ""
                },
                "phone": {
                            "number": "912345678",
                            "area_code": "21",
                            "country_code": "55"
                        },
                "email": "teste@teste.com.br"
            },
            "collaterals": [],
            "invoice_authorization": {
                "signature": {
                    "signer": {
                        "name": "Nome Sobrenome",
                        "document_number": "12345678911",
                        "email": "teste@teste.com.br",
                        "phone": {
                            "number": "912345678",
                            "area_code": "21",
                            "country_code": "55"
                        }
                    },
                    "authentication_type": "opt_in",
                    "authenticity": {
                        "timestamp": "2022-11-18T11:17:46",
                        "ip_address": "104.101.21.0",
                        "fingerprint": {
                            "browser": "Mozila"
                        },
                        "third_party_additional_data": {},
                        "session_id": "8df91773-c537-4662-b08b-025f03bf79dc"
                    },
                    "signed_object": {
                        "document_key": "27A0BA3D-A89D-4218-AB06-BC39B94CE23C"
                    }
                }
            },
            "interest_base": "calendar_days_365",
            "default_monthly_interest_rate": 0.035,
            "invoice_configuration": {
                "due_day": 10,
                "closing_day": 1,
                "grace_months": 1,
                "invoice_payment_type": "bankslip",
                "delay_fine_percentage": 0,
                "delay_monthly_interest_rate": 0,
                "issuing_and_due_day_difference": 9
            },
            "status": "active",
            "limit": 123,
            "current_limit": 1000
}
```

## 2. Adicionar Cartões a uma carteira digital existente:
Após a criação da carteira digital para o cliente, é necessário criar um cartão, vinculado à esta carteira

### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card
MÉTODO POST

Testar no Playground

Request Body

```json
{
    "settlement_method": "credit_operation"
}
```

### Request body details
#### Payload card

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---|---|
| `settlement_method` | string  |  Tipo de lastro. Ou seja, como as transações serão lastreadas. Opções: "credit_operation" | |

### Response

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card
MÉTODO POST
HTTP STATUS 201

Response Body

```json
{
    "card_key": "dabd10b6-80a8-4c9c-8a8e-e25a56668525"
}
```

### Response body details

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---|---|
| `card_key` | string  |  Identificador único do cartão (uuid)  | |

## 3. Simular operação:

Simular as transações (PIX).
### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry/simulation
MÉTODO POST

Testar no Playground

Request Body

```json
{
  "amount": 200,
  "number_of_installments": 4,
  "monthly_interest_rate": 0.035
}
```

:::note ATENÇÃO
Não é necessário informar o campo "monthly_interest_rate", quando não informado, a transação assumirá o default da carteira.
:::

### Response

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry/simulation
MÉTODO POST
HTTP STATUS 201

Response Body

```json
{
    "amount": 200,
    "final_amount": 221.16,
    "number_of_installments": 4,
    "monthly_interest_rate": 0.035,
    "cet": 0.03,
    "annual_cet": 0.5040,
    "total_iof": 100.44,
    "items": [
        {
            "amount": 55.29,
            "used_limit":50,
            "installment_number": 1,
            "invoice": {
                "due_date": "2023-09-10"
            }
        },
        {
            "amount": 55.29,
            "used_limit":50,
            "installment_number": 2,
            "invoice": {
                "due_date": "2023-10-10"
            }
        },
        {
            "amount": 55.29,
            "used_limit":50,
            "installment_number": 3,
            "invoice": {
                "due_date": "2023-11-10"
            }
        },
        {
            "amount": 55.29,
            "used_limit":50,
            "installment_number": 4,
            "invoice": {
                "due_date": "2023-12-10"
            }
        }
    ]
}
```

## 4. Incluir transações em um cartão:

Incluir as transações (PIX). É nesta etapa que é gerada a ccb, em que é verificado se há limite disponível para realizar a transação. A liquidação da transação é processada de forma síncrona.

### Request

:::note ATENÇÃO
Não é necessário informar o campo "monthly_interest_rate", quando não informado, a transação assumirá o default da carteira.
:::

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry
MÉTODO POST

Testar no Playground

Request Body

```json
{
  "disbursement": {
    "method": "pix",
    "data": {
      "pix_key": "\<CHAVE PIX\>",
      "end_to_end_id": "\<CHAVE END TO END DO PIX\>"
    }
  },
  "description": "Compra Padaria do João",
  "amount": 200,
  "request_control_key": "275619e6-23d1-485e-81ca-5552aa235761",
  "number_of_installments": 4,
  "monthly_interest_rate": 0.027,
  "authorization": {
    "document_number": "01975273702",
    "signature": {
      "signed_object": {
        "document_key": "6254c56e-c980-4b38-ad99-ac5ec7535d68"
      },
      "authenticity": {
        "ip_address": "192.168.0.0",
        "third_party_additional_data": {
          "hash": "23A2581A8D524035FEB2950D28727CF5 | 192.168.0.0 | 23/02/2023 17:38:45"
        },
        "timestamp": "2023-02-23T17:38:45.610458300"
      },
      "authentication_type": "opt_in",
      "signer": {
        "document_number": "01975273702",
        "phone": {
          "number": "986243444",
          "country_code": "55",
          "area_code": "21"
        },
        "name": "Master Tester",
        "email": "mail@mail.com"
      }
    }
  }
}
```

Desembolsar com Chave Pix
```json
{
    "disbursement": {
    "method": "pix",
    "data": {
      "pix_key": "\<CHAVE PIX\>",
      "end_to_end_id": "\<CHAVE END TO END DO PIX\>"
    }
  }
}
```

Desembolsar com Pix QR Code
```json
{
    "disbursement": {
    "method": "pix_qrcode",
    "data": {
      "qr_code_url": "\<URL DO PIX\>",
      "end_to_end_id": "\<CHAVE END TO END DO PIX QR CODE\>"
    }
  }
}
```

Desembolsar com Pix Manual
```json
{
    "disbursement": {
    "method": "pix_manual",
    "data": {
        "ispb": "\<BASE DO CNPJ DO BANCO\>",
        "branch_number": "\<AGÊNCIA DA CONTA DE DESEMBOLSO\>",
        "account_number": "\<NÚMERO DA CONTA SEM O DÍGITO\>",
        "account_digit": "\<DIGITO DA CONTA DE DESEMBOLSO\>",
        "document_number": "\<CPF/ CNPJ DO TITULAR DA CONTA\>",
        "name": "\<NOME DO TITULAR DA CONTA\>"
    }
  }
}
```

### Response

Em caso de sucesso no desembolso da transação:

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry
MÉTODO POST
HTTP STATUS 201

Response Body

```json
{
    "card_entry_key": "ad8e073a-2159-479b-b141-cd5d8ceb8567",
    "status": "active",
    "signed_url":"https://storage.googleapis.com/live-doc-api/documents/XXXXXXXXXXXXXXX.pdf"
}
```

:::caution ATENÇÃO
Por instabilidade do Bacen ou do banco de destino da transação, pode ocorrer atraso na transação do contrato, dessa forma o mesmo assumirá o status "pending_activation", e será atualizado quando a transação for realizada com sucesso ou o contrato for cancelado. Dessa forma, o fluxo migrará de síncrono para assíncrono devendo esperar o [webhook](#92-alteração-de-status-da-transação) de sucesso ou falha da transação .
:::

## 4.1 Consultar uma transação (card entry) específica:
### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry/[CARD-ENTRY-KEY]
MÉTODO GET

Testar no Playground

### Response

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry/[CARD-ENTRY-KEY]
MÉTODO GET
HTTP STATUS 200

Response Transação Pix Manual

```json
{
    "transaction_key": "75b800f3-12ba-41b3-a7d5-cbb3ae2199f2",
    "end_to_end_id": "E324025022023082120064RNfdmEDTxV", 
    "transacted_at": "2023-08-21T20:07:46",
    "amount": 2242.8,
    "number_of_installments": 2,
    "monthly_interest_rate": 0.027,
    "final_amount":2250,
    "cet": 0.03,
    "annual_cet": 0.5040,
    "total_iof": 100.44,
    "description":"Compra Padaria do João",
    "disbursement": {
        "method": "pix_manual",
        "data": {
            "ispb": 32402502,
            "branch_number": 1,
            "account_number": 15570,
            "account_digit": 1,
            "document_number": "12345678911",
            "name": "XXXXX XXXX XXXX"
        }
    },
    "card_entry_datetime": "2023-06-07T10:29:49Z",
    "signed_url":"https://storage.googleapis.com/live-doc-api/documents/XXXXXXXXXXXXXXX.pdf",
    "items": [
        {
            "item_key":"37ebad25-7eef-4a46-b497-ce46c2c04f68",
            "amount": 1125,
            "used_limit":1121.4,
            "status":"active",
            "installment_number": 1,
            "invoice": {
                "invoice_key": "b32e7eae-eaab-4402-9126-9fcf42741c24",
                "due_date": "2023-07-10",
                "status": "opened"
                },
        },
        {
            "item_key":"60e4801f-75ce-411e-aaf0-99b951c05308",
            "amount": 1125,
            "used_limit":1121.4,
            "installment_number": 2,
            "status":"active",
            "invoice": {
                "invoice_key": "2af90944-1377-447c-aa70-0efd24c17d6f",
                "due_date": "2023-08-10",
                "status": "opened"
                },
        }
	], 
    "status": "active"
}
```

Response Transação Pix Key

```json
{
    "transaction_key": "75b800f3-12ba-41b3-a7d5-cbb3ae2199f2",
    "end_to_end_id": "E324025022023082120064RNfdmEDTxV", 
    "transacted_at": "2023-08-21T20:07:46",
    "amount": 2242.8,
    "final_amount":2250,
    "number_of_installments": 2,
    "monthly_interest_rate": 0.027,
    "cet": 0.03,
    "annual_cet": 0.5040,
    "total_iof": 100.44,
    "description":"Compra Padaria do João",
    "disbursement": {
 		"data": {
 			"end_to_end_id": "E3240250220210928212926341670923",
 			"pix_key": "+5516983068432"
 		},
 		"method": "pix"
    },
    "card_entry_datetime": "2023-06-07T10:29:49Z",
    "signed_url":"https://storage.googleapis.com/live-doc-api/documents/XXXXXXXXXXXXXXX.pdf",
    "items": [
        {
            "item_key":"37ebad25-7eef-4a46-b497-ce46c2c04f68",
            "amount": 1125,
            "used_limit":1121.4,
            "installment_number": 1,
            "status":"active",
            "invoice": {
                "invoice_key": "b32e7eae-eaab-4402-9126-9fcf42741c24",
                "due_date": "2023-07-10",
                "status": "opened"
                },
        },
        {
            "item_key":"60e4801f-75ce-411e-aaf0-99b951c05308",
            "amount": 1125,
            "used_limit":1121.4,
            "status":"active",
            "installment_number": 2,
            "invoice": {
                "invoice_key": "2af90944-1377-447c-aa70-0efd24c17d6f",
                "due_date": "2023-08-10",
                "status": "opened"
                },
        }
	], 
    "status": "active"
}
```

Response Transação Pix QR Code

```json
{
    "transaction_key": "75b800f3-12ba-41b3-a7d5-cbb3ae2199f2",
    "end_to_end_id": "E324025022023082120064RNfdmEDTxV", 
    "transacted_at": "2023-08-21T20:07:46",
    "amount": 2242.8,
    "final_amount":2250,
    "number_of_installments": 2,
    "monthly_interest_rate": 0.027,
    "cet": 0.03,
    "annual_cet": 0.5040,
    "total_iof": 100.44,
    "description":"Compra Padaria do João",
    "disbursement": {
 		"method": "pix_qrcode",
        "data": {
            "qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/a1908d67-bcc8-40cd-a63d-6b6fb510b35c5204000053039865802BR5925QI SOCIEDADE DE CREDITO D6009Sao Paulo61080145200062070503***63042184",
            "end_to_end_id": "E3240250220220822211350711639780"
        }
    },
    "card_entry_datetime": "2023-06-07T10:29:49Z",
    "signed_url":"https://storage.googleapis.com/live-doc-api/documents/XXXXXXXXXXXXXXX.pdf",
    "items": [
        {
            "item_key":"37ebad25-7eef-4a46-b497-ce46c2c04f68",
            "amount": 1125,
            "used_limit":1121.4,
            "installment_number": 1,
            "status":"active",
            "invoice": {
                "invoice_key": "b32e7eae-eaab-4402-9126-9fcf42741c24",
                "due_date": "2023-07-10",
                "status": "opened"
                },
        },
        {
            "item_key":"60e4801f-75ce-411e-aaf0-99b951c05308",
            "amount": 1125,
            "used_limit":1121.4,
            "installment_number": 2,
            "status":"active",
            "invoice": {
                "invoice_key": "2af90944-1377-447c-aa70-0efd24c17d6f",
                "due_date": "2023-08-10",
                "status": "opened"
                },
        }
	], 
    "status": "active"
}
```

#### Enumeradores Card Entry status

| Enumerador                   | Descrição                                            |
|------------------------------|------------------------------------------------------|
| **active**                   | Contrato ativo e desembolsado                        |
| **pending_activation**       | Contrato aguardando desembolso                       |
| **canceled**                 | Contrato cancelado                                   |
| **paid**                     | Contrato liquidado                                   |

## 4.2 Gerar comprovante da transação:
### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry/[CARD-ENTRY-KEY]/receipt
MÉTODO GET

Testar no Playground

### Response

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry/[CARD-ENTRY-KEY]/receipt
MÉTODO GET
HTTP STATUS 200

Response Body

```json
    {
        "base64_receipt": ""
    }
```

## 5. Listar faturas de uma carteira digital:

### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoices
MÉTODO GET
<div className='badge
badge--primary'>PARAMETERS page, page_size

Testar no Playground

### Response

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoices
MÉTODO GET
HTTP STATUS 200
Limite de itens retornados por página: 100
Response Body

```json
{
    "wallet_key": "9798d733-7f68-4929-8877-a00bfda9735e",
    "invoice_closing_day": 2,
    "invoice_due_day": 10,
    "page": "1",
	"last_page": "False",
    "invoices": [
        {
            "invoice_key": "b32e7eae-eaab-4402-9126-9fcf42741c24",
            "due_date": "2023-04-10",
            "closing_date": "2023-04-02",
            "status": "opened",
            "number_of_items": 2
        },
        {
            "invoice_key": "2af90944-1377-447c-aa70-0efd24c17d6f",
            "due_date": "2023-05-10",
            "closing_date": "2023-05-02",
            "status": "opened",
            "number_of_items": 12
        },
        {
            "invoice_key": "26e18c39-8f67-4399-9a42-8d18bc175da2",
            "due_date": "2023-04-10",
            "closing_date": "2023-04-02",
            "status": "opened",
            "number_of_items": 1
        },
        {
            "invoice_key": "6991f8e6-7b1d-4496-a08f-8a9eef263f07",
            "due_date": "2023-06-10",
            "closing_date": "2023-06-02",
            "status": "opened",
            "number_of_items": 12
        }
    ]
    
}
```

## 6. Listar transações de uma fatura:
### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]
MÉTODO GET

Testar no Playground

### Response

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]
MÉTODO GET
HTTP STATUS 200

Response Body

```json
{
    "due_date": "2023-06-10",
    "closing_date": "2023-06-02",
    "status": "closed",
    "amount": 12345.67,
    "paid_amount": 0,
    "delay_interest_total_amount": 0,
    "delay_fine_total_amount": 0,
    "number_of_items": 1,
    "invoice_payments": [
        {
            "invoice_payment_key": "63a7c7a2-9e13-48cf-aea2-3b494125d14b",
            "invoice_payment_type": "bankslip",
            "charge_type": "ordinary",
            "data": {
                "digitable_line": "32990001039000000000104620768103992260000004183",
                "qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/881979cb-1c15-4dea-a05e-316caae22f5e5204000053039865802BR5925LOTEAMENTO RESIDENCIAL PO6014PORTO NACIONAL61087750000062070503***630414B8"
            },
            "expiration": "2023-07-10",
            "status": "opened",
            "total_amount": 0,
            "paid_amount": 0,
            "chargeback_amount": 50
        }
    ],
    "items": [
        {
            "item_key": "37ebad25-7eef-4a46-b497-ce46c2c04f68",
            "amount": 12345.67,
            "used_limit": 12300,
            "status": "active",
            "card_entry": {
                "card_entry_key": "ad8e073a-2159-479b-b141-cd5d8ceb8567",
                "card_entry_datetime": "2022-11-13T10:29:49",
                "description": "Compra Padaria do João",
                "final_amount": 12345.67,
                "number_of_installments": 2,
                "card": {
                    "card_key": "d41bd53e-eedc-4d62-97dd-26bbaefadb20"
                }
            },
            "installment_number": 1
        }
    ]
}
```

#### Enumeradores Item status

| Enumerador                   | Descrição                                                                                   |
|------------------------------|---------------------------------------------------------------------------------------------|
| **pending_activation**       | Item aguardando ativação, o valor do item compôe o valor da fatura                          |
| **active**                   | Item ativo, o valor do item compôe o valor da fatura                                        |
| **canceled**                 | Item cancelado, o valor do item é removido do valor da fatura                               |
| **paid**                     | Item pago na fatura do mês, o valor do item compôe o valor da fatura                        |
| **paid_early**               | Item pago adiantado, o valor do item não compôe mais o valor da fatura                      |
| **reversed**                 | Item cancelado após fechamento da fatura, o valor do item gerará um estorno                   |

## 7. Geração de boletos:

A geração do boleto ordinário acontecerá automaticamente no dia de fechamento da fatura e poderá ser resgatado através do get de pagamento da fatura. O query parameter "shorten_url" é uma flag para solicitar a URL do boleto encurtada.

:::caution ATENÇÃO
O boleto pode ser pago em até 30 dias após o vencimento da fatura.
:::

:::danger ATENÇÃO
O encurtamento de URL é limitado a 60 requisições por minuto.
:::

### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]/invoice_payment/[INVOICE-PAYMENT-KEY]
MÉTODO GET
<div className='badge
badge--primary'>PARAMETER shorten_url

Testar no Playground

### Response

#### Parameter shorten_url=False

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]/invoice_payment/[INVOICE-PAYMENT-KEY]?shorten_url=False
MÉTODO GET
HTTP STATUS 200

Response Body

```json
    {
        "invoice_payment_key": "63a7c7a2-9e13-48cf-aea2-3b494125d14b",
        "invoice_payment_type": "bankslip",
        "charge_type": "ordinary",
        "data": {
            "bank_slip_key": "dc4a27db-2fe1-474d-aa02-88d6fffb8d0d",
            "digitable_line": 32990001039000000000104620768103992260000004183,
            "qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/881979cb-1c15-4dea-a05e-316caae22f5e5204000053039865802BR5925LOTEAMENTO RESIDENCIAL PO6014PORTO NACIONAL61087750000062070503***630414B8",
            "bank_slip_url": "\<URL BOLETO EM PDF\>"
        },
        "expiration": "2023-07-10",
        "status": "issued",
        "total_amount": 0,
        "paid_amount": 0,
        "chargeback_amount": 50,
    }
```

#### Parameter shorten_url=True

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]/invoice_payment/[INVOICE-PAYMENT-KEY]?shorten_url=True
MÉTODO GET
HTTP STATUS 200

Response Body

```json
    {
        "invoice_payment_key": "63a7c7a2-9e13-48cf-aea2-3b494125d14b",
        "invoice_payment_type": "bankslip",
        "charge_type": "ordinary",
        "data": {
            "bank_slip_key": "dc4a27db-2fe1-474d-aa02-88d6fffb8d0d",
            "digitable_line": 32990001039000000000104620768103992260000004183,
            "qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/881979cb-1c15-4dea-a05e-316caae22f5e5204000053039865802BR5925LOTEAMENTO RESIDENCIAL PO6014PORTO NACIONAL61087750000062070503***630414B8",
            "bank_slip_url": "\<URL BOLETO EM PDF\>",
            "short_bank_slip_url": "\<URL BOLETO EM PDF ENCURTADA\>"
        },
        "expiration": "2023-07-10",
        "status": "issued",
        "total_amount": 0,
        "paid_amount": 0
    }
```

## 7.1 Geração de boleto extraordinário de adiantamento:

### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]/invoice_payment
MÉTODO POST

Testar no Playground

Request Body

```json
{
    "invoice_payment_type": "bankslip",
    "charge_type": "early",
    "expiration": "2023-08-15",
    "invoice_items": [
	    "key_1",
	    "key_2"
    ]
}
```

:::note ATENÇÃO
Condição: "expiration" deve ser dois dias úteis menor que a data de fechamento da fatura para garantir que o pagamento não irá interferir
em tal rotina.
:::

### Response

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]/invoice_payment
MÉTODO POST
HTTP STATUS 200

Response Body

```json
     {
        "invoice_payment_key": "63a7c7a2-9e13-48cf-aea2-3b494125d14b",
        "invoice_payment_type": "bankslip",
        "charge_type": "early",
        "data": {
            "digitable_line": 32990001039000000000104620768103992260000004183,
            "qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/881979cb-1c15-4dea-a05e-316caae22f5e5204000053039865802BR5925LOTEAMENTO RESIDENCIAL PO6014PORTO NACIONAL61087750000062070503***630414B8",
        },
        "expiration": "2023-08-15",
        "status": "issued",
        "total_amount": 200,
        "paid_amount": 0
 }
```

## 7.2 Simulação de boleto extraordinário de atraso:

:::caution ATENÇÃO
A simulação só pode ser solicitada após o termino do prazo de pagamento do boleto ordinário.
:::

### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]/invoice_payment/simulation
MÉTODO POST

Testar no Playground

Request Body

```json
    {
        "invoice_payment_type": "bankslip",
        "charge_type": "delay",
        "expiration": "2023-08-15"
    }
```

### Request com desconto

Request Body

```json
    {
        "invoice_payment_type": "bankslip",
        "charge_type": "delay",
        "expiration": "2023-08-15",
        "discount_amount": 50
    }
```

### Response

Response Body

```json
    {
        "invoice_payment_type": "bankslip",
        "charge_type": "delay",
        "total_amount": 150,
        "discount_amount": 50
    }
```

## 7.3 Geração de boleto extraordinário de atraso:

:::caution ATENÇÃO
O boleto de atraso só pode ser gerado após o termino do prazo de pagamento do boleto ordinário.
:::

### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]/invoice_payment
MÉTODO POST

Testar no Playground

Request Body

```json
    {
        "invoice_payment_type": "bankslip",
        "charge_type": "delay",
        "expiration": "2023-08-15"
    }
```

### Request com desconto

Request Body

```json
    {
        "invoice_payment_type": "bankslip",
        "charge_type": "delay",
        "expiration": "2023-08-15",
        "discount_amount": 50
    }
```

### Response

Response Body

```json
    {
        "invoice_payment_key": "63a7c7a2-9e13-48cf-aea2-3b494125d14b",
        "invoice_payment_type": "bankslip",
        "charge_type": "delay",
        "data": {
            "digitable_line": 32990001039000000000104620768103992260000004183,
            "qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/881979cb-1c15-4dea-a05e-316caae22f5e5204000053039865802BR5925LOTEAMENTO RESIDENCIAL PO6014PORTO NACIONAL61087750000062070503***630414B8",
        },
        "expiration": "2023-07-10",
        "status": "issued",
        "total_amount": 0,
        "paid_amount": 0,
        "discount_amount": 50
    }
```

## 7.4 Cancelamento de boleto de pagamento de fatura

### Request

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]/invoice_payment/[INVOICE-PAYMENT-KEY]
MÉTODO DELETE

Testar no Playground

### Response

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/invoice/[INVOICE-KEY]/invoice_payment/[INVOICE-PAYMENT-KEY]
MÉTODO DELETE
HTTP STATUS 204

Response Body

```json
    {}
```

## 8. Estornos:

## 8.1. Consultar estornos:

### Request

ENDPOINT
        /card_invoice/wallet/[WALLET-KEY]/chargebacks
MÉTODO
        GET

Testar no Playground

#### PATH PARAMETERS

| Enumerador                   | Descrição                                                   |
|------------------------------|-------------------------------------------------------------|
| **status**                   | Status do estorno('active'/'used'/'pending_payment')        |

### Response

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/chargebacks
MÉTODO GET
HTTP STATUS 200

Response Body

```json
    {
        "page": 1,
        "last_page": true,
        "data": [
            {
                "charge_back_key": "key",
                "amount": 100,
                "used_amount": 0,
                "status": "active",
                "reference_card_entry_key": "key",
                "reference_item_key": "key"
            }
        ]
    }

```

## 9. Webhooks:

## 9.1. Alteração de status de fatura:
### Webhook

WEBHOOK_TYPE card_invoice.invoice.status_change
STATUS opened

Webhook Body

```json
{
	"webhook_type": "card_invoice.invoice.status_change",
	"key": "\<INVOICE-KEY\>",
	"event_datetime": "\<DATA E HORA DO ENVIO DO WEBHOOK\>",
	"status": "opened",
    "data": {
        "wallet_key":"\<CHAVE DA CARTEIRA\>",
        "due_date": "2023-07-10",
        "closing_date": "2023-07-02"
    }
}
```

:::note ATENÇÃO
O conteúdo do campo "data" mantém o mesmo padrão para todos os status
:::

#### Enumeradores Invoice status

| Enumerador                   | Descrição                                            |
|------------------------------|------------------------------------------------------|
| **opened**                   | Fatura aberta                                        |
| **closed**                   | Fatura fechada                                       |
| **paid**                     | Fatura paga dentro da data de vencimento             |
| **paid_overdue**             | Fatura paga em atraso                                |

## 9.2. Alteração de status da transação:
### Webhook

WEBHOOK_TYPE card_invoice.card_entry.status_change
STATUS active

Webhook Body

```json
{
	"webhook_type": "card_invoice.card_entry.status_change",
	"key": "\<CARD-ENTRY-KEY\>",
	"event_datetime": "\<DATA E HORA DO ENVIO DO WEBHOOK\>",
	"status": "active",
    "data": {
        "wallet_key":"\<CHAVE DA CARTEIRA\>"
    }
}
```

#### Enumeradores Card Entry status

| Enumerador                   | Descrição                                            |
|------------------------------|------------------------------------------------------|
| **active**                   | Contrato ativo e desembolsado                        |
| **canceled**                 | Contrato cancelado                                   |

:::caution ATENÇÃO
O envio deste webhook só ocorrerá quando a transação estiver no status de "pending_activation"
:::

## 9.3. Criação do boleto após fechamento da fatura:
### Webhook

WEBHOOK_TYPE card_invoice.invoice_payment.status_change
STATUS issued

Webhook Body

```json
{
	"webhook_type": "card_invoice.invoice_payment.status_change",
	"key": "\<INVOICE-PAYMENT-KEY\>",
	"event_datetime": "\<DATA E HORA DO ENVIO DO WEBHOOK\>",
	"status": "issued",
    "data": {
        "charge_type": "ordinary",
        "wallet_key":"\<CHAVE DA CARTEIRA\>",
        "invoice_key":"\<CHAVE DA FATURA\>",
        "digitable_line":"\<LINHA DIGITAVEL DO BOLETO\>",
        "qr_code_url":"\<URL DO QR CODE DO BOLETO\>"
    }
}
```

#### Enumeradores Charge type

| Enumerador                   | Descrição                                            |
|------------------------------|------------------------------------------------------|
| **ordinary**                 | Pagamento ordinário                                  |
| **early**                    | Pagamento extraordinário de adiantamento             |
| **delay**                    | Pagamento extraordinário de atraso                   |

## 9.4. Alteração de status do pagamento da fatura:
### Webhook

WEBHOOK_TYPE card_invoice.invoice_payment.status_change
STATUS paid

Webhook Body

```json
{
	"webhook_type": "card_invoice.invoice_payment.status_change",
	"key": "\<INVOICE-PAYMENT-KEY\>",
	"event_datetime": "\<DATA E HORA DO ENVIO DO WEBHOOK\>",
	"status": "paid",
    "data": {
        "wallet_key":"\<CHAVE DA CARTEIRA\>",
        "charge_type": "ordinary",
        "invoice_key":"\<CHAVE DA FATURA\>",
        "paid_amount": 150.0
    }
}
```

#### Enumeradores Invoice Payment status

| Enumerador                   | Descrição                                            |
|------------------------------|------------------------------------------------------|
| **issued**                   | Emissão do boleto para pagamento da fatura           |
| **paid**                     | Boleto pago                                          |
| **canceled**                 | Pagamento do boleto cancelado                        |

## 9.5. Alteração de status do estorno:

### Webhook

WEBHOOK_TYPE card_invoice.chargeback.status_change
STATUS active

Webhook Body

```json
{
	"webhook_type": "card_invoice.chargeback.status_change",
	"key": "\<CHARGEBACK-KEY\>",
	"event_datetime": "\<DATA E HORA DO ENVIO DO WEBHOOK\>",
	"status": "active",
    "data": {
        "wallet_key":"\<CHAVE DA CARTEIRA\>",
        "chargeback_amount":150.00,
        "reference_card_entry_key":"\<CHAVE DA TRANSAÇÃO DE REFERÊNCIA DO ESTORNO\>",
        "reference_item_key" :"\<CHAVE DO ITEM DE REFERÊNCIA DO ESTORNO\>"
    }
}
```

#### Enumeradores status estorno

| Enumerador                   | Descrição                                                   |
|------------------------------|-------------------------------------------------------------|
| **active**                   | Estorno ativo para ser utilizado em um pagamento de fatura  |
| **used**                     | Estorno ja utilizado no pagamento de uma fatura             |
| **pending_payment**          | Estorno aguardando pagamento para ser ativado               |

:::caution Status 'pending_payment' 
O status pending_payment representa o estorno de um item que pertence a uma fatura fechada que ainda não foi paga, o valor do estorno só pode ser utilizado após o pagamento da fatura.
:::

## 9.6.1 Rejeição de renegociação de transação:
### Webhook

WEBHOOK_TYPE card_invoice.renegotiation.status_change
STATUS rejected

Webhook Body

```json
{
    "webhook_type": "card_invoice.renegotiation.status_change",
    "key": "\\<RENEGOTIATION-KEY\\>",
    "event_datetime": "\\<DATA E HORA DO ENVIO DO WEBHOOK\\>",
    "status": "rejected",
    "data": {
        "wallet_key": "\\<CHAVE DA CARTEIRA\\>"
    }
}

```

## 9.6.2 Pagamento de renegociação de transação:
### Webhook

WEBHOOK_TYPE card_invoice.renegotiation.status_change
STATUS paid

Webhook Body

```json
{
    "webhook_type": "card_invoice.renegotiation.status_change",
    "key": "\\<RENEGOTIATION-KEY\\>",
    "event_datetime": "\\<DATA E HORA DO ENVIO DO WEBHOOK\\>",
    "status": "paid",
    "data": {
        "wallet_key": "\\<CHAVE DA CARTEIRA\\>",
        "paid_method_type": "<METODO DE PAGAMENTO>",
        "paid_in": {
            "code_number": "<CODIGO DO BANCO LIQUIDANTE>", 
            "ispb": "<ISPB DO BANCO LIQUIDANTE>", 
            "name": "<NOME DO BANCO LIQUIDANTE>"
        }
    }
}
```

#### Enumeradores status renegociação

| Enumerador                   | Descrição                                                                                                          |
|------------------------------|--------------------------------------------------------------------------------------------------------------------|
| **pending_payment**          | Renegociação de adiantamento de pagamento aguardando pagamento                                                     |
| **paid**                     | Renegociação de adiantamento de pagamento paga                                                                     |
| **canceled**                 | Renegociação de adiantamento de pagamento cancelada                                                                |
| **rejected**                 | Renegociação de adiantamento de pagamento rejeitada por pagamento de parcela por fora da renegociação ou decurso de prazo              |

## 10. Cancelamento de compra em até 7 dias:

## 10.1. Solicitação de cancelamento de compra:

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry/[CARD-ENTRY-KEY]/reversal
MÉTODO POST

Testar no Playground

### Request

Request Body

```json
{}
```

### Response

Response Body

```json
    {
      "amount": "2026.93",
      "copy_paste_pix": "00020126930014br.gov.bcb.pix2571qrcode-h.dev.qitech.app/bacen/cobv/dece8d3e-32ce-439e-8204000053039865802BR5925Joao61080150400062070503***63046ECD",
      "expiration_date": "2022-09-28"
    }
```

## 10.2. Consulta de cancelamento de compra ativo:

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/card/[CARD-KEY]/card_entry/[CARD-ENTRY-KEY]/reversal
MÉTODO GET

Testar no Playground

### Response

Response Body

```json
    {
      "amount": "2026.93",
      "copy_paste_pix": "00020126930014br.gov.bcb.pix2571qrcode-h.dev.qitech.app/bacen/cobv/dece8d3e-32ce-439e-8204000053039865802BR5925Joao61080150400062070503***63046ECD",
      "expiration_date": "2022-09-28"
    }
```

## 11. Renegociação de compras:

## 11.1. Simular renegociação de compras:

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/renegotiation/simulation
MÉTODO POST

Testar no Playground

### Request

Request Body

```json
{
    "reference_date": "2024-07-20",
    "card_entries": [
        {
            "card_entry_key": "817dced9-3216-410b-a51c-645019ab320b",
            "items": [
                {
                    "item_key": "04318ab7-7b3c-4558-ad7b-4e9e2d9e0e6e"
                }
            ]
        },
        {
            "card_entry_key": "3a3d8bbb-be30-41b0-b5be-8d358dc059ea"
        }
    ]
}
```

### Request body details

| Campo | Tipo | Descrição | Caracteres |
|---| ---| ---| ---| 
| `reference_date` | string | Data de referencia da renegociação.|  |

### Response

Response Body

```json
    {
    "renegotiation_payment_amount": 350,
    "reference_date": "2022-07-20",
    "discount_percentage": 0,
    "discount_amount": 0,
    "card_entries": [
        {
            "card_entry_key": "817dced9-3216-410b-a51c-645019ab320b",
            "payment_amount": 125,
            "discount_amount": 0,
            "affected_items": [
                {
                    "item_key": "04318ab7-7b3c-4558-ad7b-4e9e2d9e0e6e",
                    "due_date": "2022-07-15",
                    "principal_amount": 100,
                    "interest_amount": 20,
                    "fine_amount": 5,
                    "total_amount": 125,
                    "present_amount": 100
                }
            ]
        },
        {
            "card_entry_key": "3a3d8bbb-be30-41b0-b5be-8d358dc059ea",
            "payment_amount": 225,
            "discount_amount": 0,
            "affected_items": [
                {
                    "item_key": "1249249c-95b5-45aa-81f1-967abf5e6eef",
                    "due_date": "2022-07-15",
                    "principal_amount": 100,
                    "interest_amount": 20,
                    "fine_amount": 5,
                    "total_amount": 125,
                    "present_amount": 100
                },
                {
                    "item_key": "c66dad81-ecb4-4afa-8713-a85ee8e721ec",
                    "due_date": "2022-08-15",
                    "principal_amount": 100,
                    "interest_amount": 20,
                    "fine_amount": 5,
                    "total_amount": 100,
                    "present_amount": 120
                }
            ]
        }
    ]
}
```

## 11.2. Criar uma renegociação de compras:

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/renegotiation
MÉTODO POST

Testar no Playground

:::caution Objeto 'items' 
Quando não informado o objeto "items", será considerado que todos os itens disponíveis da transação sejam incluídos na renegociação, ou seja, itens com status diferente de "active" serão ignorados. 

Além disso, caso a carteira ja possua uma renegociação aguardando pagamento, ela deve ser cancelada para que seja possível gerar uma nova renegociação.
:::

### Request

Request Body

```json
{
    "reference_date": "2024-07-20",
    "proposal_due_date": "2024-07-27",
    "card_entries": [
        {
            "card_entry_key": "817dced9-3216-410b-a51c-645019ab320b",
            "items": [
                {
                    "item_key": "04318ab7-7b3c-4558-ad7b-4e9e2d9e0e6e"
                }
            ]
        },
        {
            "card_entry_key": "3a3d8bbb-be30-41b0-b5be-8d358dc059ea"
        }
    ]
}
```

### Campos de desconto

Adicionar um destes campos na requisição permite definir um valor de desconto percentual ou absoluto na criação ou simulação da proposta de renegociação.

Desconto percentual

```json
{
  "discount_percentage": 0.5
}
```

Desconto absoluto

```json
{
  "discount_amount": 200
}
```

### Request body details

| Campo | Tipo | Descrição | Caracteres |
|---| ---| ---| ---| 
| `reference_date` | string | Data de referencia da renegociação.|  |
| `proposal_due_date` | string | Data do vencimento da proposal da renegociação.|  |

### Response

Response Body

```json
{
    "renegotiation_key": "2af29916-582b-4ce7-8440-352a0d9543f7",
    "renegotiation_payment_amount": 350,
    "reference_date": "2022-07-20",
    "renegotiation_status": "pending_payment",
    "proposal_due_date": "2022-07-27",
    "discount_percentage": 0,
    "discount_amount": 0,
    "payment": {
        "digitable_line": "",
        "qr_code_url": "",
        "qr_code_key": "",
        "bank_slip_key": "",
        "paid_method_type": null
    },
    "card_entries": [
        {
            "card_entry_key": "817dced9-3216-410b-a51c-645019ab320b",
            "payment_amount": 125,
            "discount_amount": 0,
            "affected_items": [
                {
                    "item_key": "04318ab7-7b3c-4558-ad7b-4e9e2d9e0e6e",
                    "due_date": "2022-07-15",
                    "principal_amount": 100,
                    "interest_amount": 20,
                    "fine_amount": 5,
                    "total_amount": 125,
                    "present_amount": 100
                }
            ]
        },
        {
            "card_entry_key": "3a3d8bbb-be30-41b0-b5be-8d358dc059ea",
            "payment_amount": 225,
            "discount_amount": 0,
            "affected_items": [
                {
                    "item_key": "1249249c-95b5-45aa-81f1-967abf5e6eef",
                    "due_date": "2022-07-15",
                    "principal_amount": 100,
                    "interest_amount": 20,
                    "fine_amount": 5,
                    "total_amount": 125,
                    "present_amount": 100
                },
                {
                    "item_key": "c66dad81-ecb4-4afa-8713-a85ee8e721ec",
                    "due_date": "2022-08-15",
                    "principal_amount": 100,
                    "interest_amount": 20,
                    "fine_amount": 5,
                    "total_amount": 100,
                    "present_amount": 120
                }
            ]
        }
    ]
}
```

### Response body details

| Campo | Tipo | Descrição | Caracteres |
|---| ---| ---| ---| 
| `reference_date` | string | Data de referencia da renegociação.|  |
| `proposal_due_date` | string | Data do vencimento da proposal da renegociação.|  |
| `renegotiation_key` | string | Identificador único da renegociação(uuid).|  |
| `renegotiation_payment_amount` | number | Valor total da renegociação.|  |
| `discount_percentage` | number | Valor do desconto percentual a ser aplicado na renegociação.|  |
| `discount_amount` | number | Valor de desconto absoluto a ser aplicado na renegociação.|  |
| `payment` | object | Objeto que contém as informações para pagamento da renegociação.|  |
| `card_entries` | list | Lista de transações e suas respectivas parcelas a serem renegociadas.|  |

## 11.3. Consultar uma renegociação de compras existente:

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/renegotiation/[RENEGOTIATION-KEY]
MÉTODO GET

Testar no Playground

#### QUERY PARAMETERS

| Enumerador                   | Descrição                                                        |
|------------------------------|------------------------------------------------------------------|
| **shorten_url**              |  Parâmetro utilizado para solicitar uma url de boleto encurtada  |

### Response

Response Body

```json
{
    "renegotiation_key": "2af29916-582b-4ce7-8440-352a0d9543f7",
    "renegotiation_payment_amount": 350,
    "reference_date": "2022-07-20",
    "renegotiation_status": "pending_payment",
    "proposal_due_date": "2022-07-27",
    "discount_percentage": 0,
    "discount_amount": 0,
    "payment": {
        "digitable_line": "",
        "qr_code_url": "",
        "qr_code_key": "",
        "bank_slip_key": "",
        "paid_method_type": null,
        "bank_slip_url": "\<URL BOLETO EM PDF\>",
        "short_bank_slip_url": "\<URL BOLETO EM PDF ENCURTADA\>"
    },
    "card_entries": [
        {
            "card_entry_key": "817dced9-3216-410b-a51c-645019ab320b",
            "payment_amount": 125,
            "discount_amount": 0,
            "affected_items": [
                {
                    "item_key": "04318ab7-7b3c-4558-ad7b-4e9e2d9e0e6e",
                    "due_date": "2022-07-15",
                    "principal_amount": 100,
                    "interest_amount": 20,
                    "fine_amount": 5,
                    "total_amount": 125,
                    "present_amount": 100
                }
            ]
        },
        {
            "card_entry_key": "3a3d8bbb-be30-41b0-b5be-8d358dc059ea",
            "payment_amount": 225,
            "discount_amount": 0,
            "affected_items": [
                {
                    "item_key": "1249249c-95b5-45aa-81f1-967abf5e6eef",
                    "due_date": "2022-07-15",
                    "principal_amount": 100,
                    "interest_amount": 20,
                    "fine_amount": 5,
                    "total_amount": 125,
                    "present_amount": 100
                },
                {
                    "item_key": "c66dad81-ecb4-4afa-8713-a85ee8e721ec",
                    "due_date": "2022-08-15",
                    "principal_amount": 100,
                    "interest_amount": 20,
                    "fine_amount": 5,
                    "total_amount": 100,
                    "present_amount": 120
                }
            ]
        }
    ]
}
```

## 11.4. Cancelamento manual de uma de renegociação:

ENDPOINT /card_invoice/wallet/[WALLET-KEY]/renegotiation/[RENEGOTIATION-KEY]
MÉTODO DELETE

Testar no Playground

### Response

Response Body

```json
{
    "renegotiation_key": "2af29916-582b-4ce7-8440-352a0d9543f7",
    "renegotiation_status": "canceled"
}

```

## 12. Simulação de cenários:

## 12.1. Fechamento de fatura:

:::info DUE_DATE
O campo due date é um campo opcional, quando não informado a fatura mantém a data de vencimento já definida. a data de fechamento não pode ser informada no futuro e a data de vencimento não pode ser definida antes da data de fechamento.
:::

ENDPOINT /mock/card_invoice/invoice/[INVOICE-KEY]/close
MÉTODO PATCH

### Request

Request Body

```json
{
    "closing_date":"2024-10-08",
    "due_date":"2024-10-20"
}
```

### Response

Response Body

```json
{}

```

---

# Manual QI Sign

URL: /documentation/manual_qi_sign/

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita.
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

## Introdução

Bem vindo à API de Assinaturas da QiTech! Esta API dá acesso ao serviço de assinatura eletrônica de documentos!

### Problemas?

Caso tenha algum problema entre em contato com o nosso suporte (suporte@qitech.com.br) e nós responderemos o mais rápido possível.

### Ambientes

Possuímos dois ambientes para os nossos clientes. As URLs base das APIs são:

- Produção - `https://api.sign.qitech.com.br/`
- Sandbox - `https://api.sandbox.sign.qitech.com.br/`

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.  
:::

## Somente HTTPS

Por questão de segurança, toda a comunicação com as APIs da QI Tech deve ser realizada utilizando a comunicação HTTPS. Para evitar que, por desatenção ou outro motivo, sejam feitas chamadas HTTP, este servidor somente disponibiliza a porta 443 com comunicação TLS 1.2. Chamadas realizadas utilizando outros protocolos serão automaticamente negadas.

## Autenticação

> Para autenticar uma chamada, utilize o código seguinte:

```shell
# No shell, você somente precisa adicionar o header adequado em cada requisição
curl "api_endpoint_here"
  -H "Authorization: EXAMPLE_API_KEY"
```

> Substitua a API key 'EXAMPLE_API_KEY' com a sua chave adquirida com o nosso suporte.

Utilizamos uma API Key para permitir acesso a nossa API. Ela provavelmente já foi enviada por e-mail para você. Caso você ainda não tenha recebido a sua chave, envie um e-mail para suporte@qitech.com.br .

Nossa API espera receber a API Key em todas as requisições ao nosso servidor em um header como o abaixo:

`Authorization: EXAMPLE_API_KEY`

Você deve substituir EXAMPLE_API_KEY com a API Key recebida do suporte.

Envelopes são os objetos que contêm os documentos a serem assinados eletronicamente. Eles são criados a partir de um ou mais arquivos e podem ser enviados para assinatura por e-mail, SMS ou WhatsApp. Para criar um envelope, você deve enviar um arquivo ou um conjunto de arquivos para a API. O envelope será criado e você receberá um identificador único para ele.

## Criando um Envelope

Para criar um Envelope, realize uma chamada `POST` para o endpoint `/sign/envelope` com os dados do(s) assinante(s).

```bash
curl -X POST \
  https://api.sign.qitech.com.br/sign/envelope \
  -H 'Content-Type: application/json' \
  -H "Authorization: EXAMPLE_API_KEY" \
  -d '{
    "id": "814e7ed3-4080-4cae-a853-8e12812817ea",
    "subject": "CCB QiTech",
    "expiration_date": "2023-09-20",
    "signers": [
      {
        "id": "1",
        "name": "John Sample",
        "email": "johnsample@test.com",
        "birthdate": "1992-09-15",
        "document_number": "111.111.111-11",
        "phone": {
              "international_dial_code": "55",
              "area_code": "11",
              "number": "988878722"
          },
        "document_submission_method": "email",
        "authentication_submission_method": "sms"
      }
    ]
  }'

```

## Definição do Objeto Envelope

Todas as trocas de informação de um envelope utilizam a seguinte definição para este objeto. Em alguns casos, para facilitar a implementação e diminuir o fluxo de dados entre as partes, algumas informações poderão ser omitidas.

| Nome            | Tipo   | Descrição                                                                          |
| --------------- | ------ | ---------------------------------------------------------------------------------- |
| id              | string | Identificador único do envelope. <br /> **É essencial que este número seja único** |
| subject         | string | Título do envelope. Aparece no assunto do email.                                   |
| expiration_date | string | Data de expiração do envelope no formato `YYYY-MM-DD`.                             |
| signers         | list   | Lista de objetos do tipo Signer que descreve os assinantes do envelope.            |

### Definição do Objeto Signer

|               Nome               |  tipo  | descrição                                                                                                          |
| :------------------------------: | :----: | ------------------------------------------------------------------------------------------------------------------ |
|                id                | string | Identificador da transação do assinante. <br /> **É essencial que este número seja único por envelope**            |
|              email               | string | Endereço de e-mail do assinante.                                                                                   |
|               name               | string | Nome completo do assinante.                                                                                        |
|            birthdate             | string | Data de nascimento do assinante no formato `YYYY-MM-DD`.                                                           |
|         document_number          | string | Número do documento do assinante.                                                                                  |
|              phone               | object | Objeto que descreve o telefone do assinante.                                                                       |
|  phone.international_dial_code   | string | Código do país do telefone do assinante.                                                                           |
|         phone.area_code          | string | Código de área do telefone do assinante.                                                                           |
|           phone.number           | string | Número do telefone do assinante.                                                                                   |
|    document_submission_method    |  enum  | Método de envio dos documentos para assinatura. <br /> Métodos disponíveis: **_email, sms e whatsapp _**           |
| authentication_submission_method |  enum  | Método de envio do token de autenticação para assinatura. <br /> Métodos disponíveis: **_email, sms e whatsapp _** |

- Campo email e phone podem ser enviados juntos ou separados, mas ao menos um deles deve ser enviado.
- Todos os campos são obrigatórios.

### Resposta da criação do envelope

Após o sucesso na criação do envelope, a resposta será um JSON contendo o id e status do envelope, conforme o exemplo ao lado:

> Resposta exemplo

```json
{
  "id": "814e7ed3-4080-4cae-a853-8e12812817ea",
  "status": "created"
}
```

## Adicionando documentos de identificação ao assinante

Para adicionar documentos de identificação ao assinante, realize uma chamada `POST` para o endpoint `/sign/envelope/\{envelope_id\}/signer/\{signer_id\}/personal_document` para cada documento a ser adicionado. O arquivo deve ser enviado no corpo da requisição seguindo o seguinte formato:

```json
{
  "document_b64": "Q5YACgAAAABDlgAbAAAAAEOWAC0AAAAAQ5YAPwAAAABDlgdN...",
  "template": "cnh_front",
  "file_type": "jpeg"
}
```

### Templates disponíveis

Para cada tipo de documento de identificação, é necessário informar o template correspondente. Os templates disponíveis são:

| Template  | Descrição                                                                |
| --------- | ------------------------------------------------------------------------ |
| cnh_front | Carteira Nacional de Habilitação brasileira frente (Lado da foto).       |
| cnh_back  | Carteira Nacional de Habilitação brasileira frente (Lado da assinatura). |
| rg_front  | Carteira de Identidade brasileira frente (Lado da foto).                 |
| rg_back   | Carteira de Identidade brasileira verso (Lado dos dados).                |

### Descrição dos Atributos de Envio

| Atributo     | Descrição                                                                                          |
| ------------ | -------------------------------------------------------------------------------------------------- |
| document_b64 | Documento de identificação codificado em base64.                                                   |
| template     | Declara o template que deve ser aplicado para análise da imagem.                                   |
| file_type    | Identifica o formato do arquivo enviado, `jpeg`. Caso não seja enviado, o valor `jpeg` é assumido. |

- O tamanho máximo do documento de identificação deve ser de 10 MB
- Todos os campos são obrigatórios exceto o `file_type`.

### Resposta da adição de documentos de identificação

Após o sucesso na adição de documentos de identificação, a resposta será um JSON contendo o `created_at` conforme o exemplo ao lado:

> Resposta exemplo

```json
{
  "created_at": "2023-01-01T00:00:00.000Z"
}
```

### Coleta do documento de identificação

Caso não seja enviado um documento de identificação do assinante, o mesmo será solicitado para realizar a coleta no momento da assinatura.

## Adicionando documentos ao envelope

Para adicionar documentos para assinatura a um envelope, realize uma chamada `POST` para o endpoint `/sign/envelope/\{envelope_id\}/document` para cada documento a ser adicionado. O arquivo deve ser enviado no corpo da requisição seguindo o seguinte formato:

```json
{
  "id": "3dfc5526-ee47-4b63-ad97-ddaf5b1c9110",
  "document_b64": "Q5YACgAAAABDlgAbAAAAAEOWAC0AAAAAQ5YAPwAAAABDlgdN...",
  "name": "Laudo de vistoria de entrada",
  "document_type": "pdf"
}
```

- O tamanho máximo do documento deve ser de 10 MB

### Definição do Objeto Document

|     nome      |  tipo  | descrição                                                                                                                                                                                          |
| :-----------: | :----: | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|      id       | string | Identificador do documento. <br /> **É essencial que este número seja único dentro do envelope** <br /> **Opcional** Caso não seja informado, geraremos uma GUID no padrão UUID4 de 36 caracteres. |
| document_b64  | string | Documento codificado em base64.                                                                                                                                                                    |
|     name      | string | Nome do documento.                                                                                                                                                                                 |
| document_type |  enum  | Tipo do documento. <br /> Tipo disponível: **_pdf_**                                                                                                                                               |

### Resposta da adição de documentos ao envelope

Após o sucesso na adição de documentos ao envelope, a resposta será um JSON contendo o identificador do documento e a data de criação, conforme o exemplo abaixo:

> Resposta exemplo

```json
{
  "id": "3dfc5526-ee47-4b63-ad97-ddaf5b1c9110",
  "created_at": "2023-01-01T00:00:00.000Z"
}
```

## Enviando o envelope para assinatura

Para enviar o envelope para assinatura, realize uma chamada `PATCH` para o endpoint `/sign/envelope/\{envelope_id\}`

```bash

  curl -X PATCH \
    https://api.sign.qitech.com.br/sign/envelope/\{envelope_id\} \
    -H "Authorization: EXAMPLE_API_KEY" \
    -d '{
      "status": "submitted"
    }'

```

### Resposta do envio do envelope para assinatura

Após o sucesso no envio do envelope para assinatura, a resposta será um JSON contendo o status do envelope, conforme o exemplo abaixo:

> Resposta exemplo

```json
{
  "status": "submitted"
}
```

Após o envio do envelope para assinatura, os assinantes receberão um e-mail ou uma mensagem com o link para assinar os documentos.

Ao acessar o link o assinante deverá preencher o CPF, assinar o documento e realizar o fluxo de validação facial e/ou documental a depender do fluxo do parceiro. Após a assinatura, o assinante será redirecionado para a página de sucesso.

## Consultando os dados do envelope

Para verificar os dados do envelope, como status e assinantes, realize uma chamada GET para o endpoint `/sign/envelope/\{envelope_id\}`

```bash

  curl -X GET \
    https://api.sign.qitech.com.br/sign/envelope/\{envelope_id\} \
    -H "Authorization: EXAMPLE_API_KEY"

```

Caso a requisição seja bem sucedida, a resposta será um JSON contendo o status do envelope e informações sobre os assinantes, conforme a exemplo abaixo:

> Resposta exemplo

```json
{
  "id": "814e7ed3-4080-4cae-a853-8e12812817ea",
  "subject": "Laudo de vistoria de entrada",
  "expiration_date": "2023-09-20T02:59:59Z",
  "status": "completed",
  "signers": [
    {
      "id": "1",
      "name": "John Sample",
      "email": "johnsample@test.com",
      "birthdate": "1992-09-15",
      "document_number": "111.111.111-11",
      "phone": {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "988878722"
      },
      "document_submission_method": "email",
      "authentication_submission_method": "email",
      "status": "signed",
      "signed_at": "2023-03-21T15:30:00.000Z",
      "signature_url": "https://sign.qitech.com.br/s/s2S33dD",
      "documents": [
        {
          "id": "8d3c3f1a-1a1a-1a1a-1a1a-1a1a1a1a1a1a",
          "name": "Laudo de vistoria de entrada",
          "document_type": "pdf"
        }
      ]
    }
  ]
}
```

- O status do envelope pode ser `created`, `submitted`, `completed`, `canceled` ou `expired`.

| enumeradores | descrição                                                            |
| :----------: | -------------------------------------------------------------------- |
|   created    | Envelope criado                                                      |
|  submitted   | Envelope enviado para assinatura                                     |
|  completed   | Quando todas as assinaturas do envelope foram concluídas com sucesso |
|   canceled   | Envelope cancelado por solicitação do parceiro                       |
|   expired    | Envelope expirado por tempo de assinatura                            |

|      nome       |   tipo   | descrição                                                                 |
| :-------------: | :------: | ------------------------------------------------------------------------- |
|       id        |  string  | Identificador único do envelope.                                          |
|     status      |  string  | Status do envelope.                                                       |
| expiration_date |  string  | Data de expiração do envelope.                                            |
|     signers     |  Signer  | Lista de objetos do tipo Signer que descreve os assinantes do envelope.   |
|    documents    | Document | Lista de objetos do tipo Document que descreve os documentos do envelope. |

## Webhook

Ao final da assinatura por todos os assinantes e geração do dossiê, será disparada uma chamada por meio de Webhook.
Para tanto, é necessário, por meio da equipe do suporte (suporte@qitech.com.br), configurar um endereço do endpoint por onde vamos notificar as atualizações e também uma _signature_key_ que será utilizada para assinar a requisição.

O cliente pode, apesar de não recomendável, também utilizar a técnica de [polling]( ). Neste caso, basta não configurar o endpoint de webhook e utilizar os endpoints de recuperação de cadastro para proceder com o polling.

## Assinatura

> Exemplo de cálculo de assinatura em Python

```python
    hmac_obj = hmac.new(signature_key.encode('utf-8'), (endpoint + method + payload).encode('utf-8'), hashlib.sha1)
    return hmac_obj.hexdigest()
```

Para garantir que a requisição recebida no endpoint do webhook parte dos nossos servidores, uma assinatura HMAC é enviada no Header Signature, semelhante ao processo de autenticação.

Após realizar o cálculo do valor esperado da assinatura do lado do servidor, é necessário comparar a assinatura calculada com a enviada. Caso as assinaturas sejam compatíveis, isso significa que a requisição partiu dos nossos servidores e que é confiável.

Exemplo de chamada webhook:

```json
{
  "id": "479f8e5a-75e1-4a33-9d75-e0083e3c8e9c",
  "status": "completed",
  "webhook_type": "envelope_completed",
  "signers": [
    {
      "id": "c15392dd-7859-4eae-a2b6-bf0f760a6d9b",
      "biometry": {
        "face_validation_available": true,
        "fraud_base_flag": false,
        "face_validation_score": 90
      },
      "liveness": {
        "result": "live"
      },
      "document": {
        "face_match_score": 85
      }
    }
  ]
}
```

|                   nome                    |  tipo   | descrição                                                                        |
| :---------------------------------------: | :-----: | -------------------------------------------------------------------------------- |
|                    id                     | string  | Identificador único do envelope.                                                 |
|                  status                   | string  | Status do envelope.                                                              |
|                 signer.id                 | string  | Identificador único do assinante.                                                |
| signer.biometry.face_validation_available | boolean | Indica se o rosto foi encontrado e validado.                                     |
|      signer.biometry.fraud_base_flag      | boolean | Indica se o rosto do assinante foi encontrado na base de fraude.                 |
|   signer.biometry.face_validation_score   | integer | Indica o score da validação facial.                                              |
|          signer.liveness.result           | string  | Indica o resultado da validação de liveness. Valores possíveis `live` ou `spoof` |
|     signer.document.face_match_score      | integer | Indica o score da validação de face match.                                       |

## Baixando os dossiês assinados

Caso todos os assinantes tenham assinado todos os documentos do envelope, o status do envelope será `completed` e um dossiê para cada documento, com as assinaturas e dados dos assinantes estará disponível para download. Para isso, realize uma chamada `GET` para o endpoint `/sign/envelope/\{envelope_id\}/report`

```bash
  curl -X GET \
    https://api.sign.qitech.com.br/sign/envelope/\{envelope_id\}/report \
    -H "Authorization: EXAMPLE_API_KEY"

```

Caso a requisição seja bem sucedida, a resposta será um JSON contendo o id e status do envelope, além de uma lista com id do documento e a url do dossiê gerado, conforme o exemplo abaixo:

> Resposta exemplo

```json
{
  "id": "479f8e5a-75e1-4a33-9d75-e0083e3c8e9c",
  "status": "available",
  "documents_reports": [
    {
      "id": "a50ef632-842e-4622-8075-684b8c83a99e",
      "url": "https://qisign-dossiers.com/06abda52-5bd1-46a1-8fa2-f616ba44b395.pdf"
    }
  ]
}
```

- O link do relatório para cada documento terá validade de 24 horas.
- O status dos relatórios para o envelope pode ser `available` ou `unavailable`.
- A propriedade `documents_reports` contem a lista dos documentos do envelope, identificados pelo id do documento e o link do seu relatório.

## Baixando o dossiê por documento assinado

Caso todos os assinantes tenham assinado todos os documentos do envelope, o status do envelope será `completed` e um dossiê para cada documento assinado, com as assinaturas e dados dos assinantes estará disponível para download. Para isso, realize uma chamada `GET` para o endpoint `/sign/envelope/\{envelope_id\}/document/{document_id}/report`

```bash
  curl -X GET \
    https://api.sign.qitech.com.br/sign/envelope/\{envelope_id\}/document/{document_id}/report \
    -H "Authorization: EXAMPLE_API_KEY"

```

Caso a requisição seja bem sucedida, a resposta será um JSON contendo id, status, url e o base64 do dossiê do documento, conforme o exemplo abaixo:

> Resposta exemplo

```json
{
  "id": "5b930d3d-3713-4c42-85d5-f8e9e44e30ce",
  "status": "available",
  "document_report_url": "https://qisign-dossiers.com/7bcf5868-784a-4356-85fb-dd72fd53cd4a.pdf",
  "document_report": "vAsXDdsaGUsdIMIGxhIG1GU=..."
}
```

- O link para o relatório do documento terá validade de 24 horas.
- O status para o relatório do documento pode ser `available` ou `unavailable`.
- A propriedade `document_report` é o relatório do documento em PDF codificado em base64.

## Baixando as fotos do rosto dos assinantes

É possível recuperar as imagens do rosto dos assinantes. Para isso basta realizar um chamada `GET` para o endpoint `/sign/envelope/\{envelope_id\}/signer/\{signer_id\}/face`

```bash
  curl -X GET \
    https://api.sign.qitech.com.br/sign/envelope/\{envelope_id\}/signer/\{signer_id\}/face \
    -H "Authorization: EXAMPLE_API_KEY"

```

Caso a requisição seja bem sucedida, a resposta será um JSON contendo a imagem codificada em base64, conforme o exemplo abaixo:

> Resposta exemplo

```json
{
  "face_image_url": "https://qisign-face-image.com/4fd09dab-6f3e-4ff5-bfed-6f7debfcde71.jpeg"
}
```

## Cancelando um envelope

Para cancelar um envelope, realize uma chamada `PATCH` para o endpoint `/sign/envelope/\{envelope_id\}`

```bash

  curl -X PATCH \
    https://api.sign.qitech.com.br/sign/envelope/\{envelope_id\} \
    -H "Authorization: EXAMPLE_API_KEY" \
    -d '{
      "status": "canceled"
    }'

```

Caso a requisição seja bem sucedida, a resposta será um JSON contendo o status do envelope, conforme o exemplo abaixo:

> Resposta exemplo

```json
{
  "status": "canceled"
}
```

## Baixando as fotos do documento dos assinantes

É possível recuperar as imagens do documento dos assinantes. Para isso basta realizar um chamada `GET` para o endpoint `/sign/envelope/\{envelope_id\}/signer/\{signer_id\}/personal_document`

```bash
  curl -X GET \
    https://api.sign.qitech.com.br/sign/envelope/\{envelope_id\}/signer/\{signer_id\}/personal_document \
    -H "Authorization: EXAMPLE_API_KEY"

```

Caso a requisição seja bem sucedida, a resposta será um JSON contendo a imagem codificada em base64, conforme o exemplo abaixo:

> Resposta exemplo

```json
{
  "document_front_url": "https://qisign-personal-documents.com/bee17d70-b029-41e2-b76b-86f64a8f9213.jpeg",
  "document_back_url": "https://qisign-personal-documents.com/faf38378-daa2-47b2-9d87-0bbc1f7c744c.jpeg"
}
```

## Consultando o status de um assinante

Para verificar o status de um assinante, realize uma chamada GET para o endpoint /sign/envelope/\{envelope_id\}/signer/\{signer_id\}

```bash

  curl -X GET \
    https://api.sign.qitech.com.br/sign/envelope/\{envelope_id\}/signer/\{signer_id\} \
    -H "Authorization: EXAMPLE_API_KEY"

```

Caso a requisição seja bem sucedida, a resposta será um JSON contendo o status do assinante, conforme a exemplo abaixo:

> Resposta exemplo

```json
{
  "name": "John Sample",
  "email": "johnsample@test.com",
  "status": "signed",
  "signed_at": "2023-03-21T15:30:00.000Z"
}
```

|   nome    |  tipo  | descrição                                                               |
| :-------: | :----: | ----------------------------------------------------------------------- |
|   name    | string | Nome do assinante.                                                      |
|   email   | string | E-mail do assinante.                                                    |
|  status   | string | Status da assinatura assinante.                                         |
| signed_at | string | Data e hora da última assinatura no formato `YYYY-MM-DDTHH:MM:SS.000Z`. |

## Status HTTP

A API de assinatura utilizam a seguinte padronização nos status HTTP de retorno, de acordo com o RFC 7231 :

| Status HTTP | Significado           | Descrição                                                                                                                                                                       |
| ----------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400         | Bad Request           | A requisição enviada possui algum erro de formatação. Na maioria dos casos, retornamos no corpo da mensagem uma explicação de onde está o erro.                                 |
| 401         | Unauthorized          | Houve algum problema na autenticação, verifique se a API Key está correta e no header correto, de acordo com a seção <a href='#autenticacao'>Autenticação</a>.                  |
| 403         | Forbidden             | O endpoint acessado é de uso interno e não está disponível para esta API Key.                                                                                                   |
| 404         | Not Found             | O dado requisitado não foi encontrado usando a chave utilizada. Este status também é retornado quando um endpoint inválido é requisitado.                                       |
| 405         | Method Not Allowed    | O método HTTP utilizado não se aplica ao endpoint utilizado.                                                                                                                    |
| 406         | Not Acceptable        | Os dados enviados no corpo da requisição são inválidos. Em geral, isso significa que os dados enviados não são um JSON válido.                                                  |
| 409         | Conflict              | O id da requisição corresponde a um id já processado anteriormente. Este status é retornado no caso de requisições duplicadas enviadas ao servidor.                             |
| 500         | Internal Server Error | Tivemos um problema para processar esta requisição, ao encontrarmos esse erro nossos especialistas são automaticamente notificados e iniciam a análise e solução imediatamente. |
| 503         | Service Unavailable   | Você se deparou com uma indisponibilidade, planejada ou não, de infraestrutura dos nossos servidores.                                                                           |

---

# Aprovar transferência

URL: /documentation/movimentacao_de_contas/aprovar_transferencia

## Request

ENDPOINT /wire_transfer_approval
MÉTODO POST

**Request Body**

```json
{
    "operation_key_list": ["0e241203-8c6b-4e0a-ac42-e0d2a2fc2d37"],
    "feedback": true
}

```

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `operation_key_list` *|  array of strings | Lista de chaves entregues na criação das tranferências (parâmetro key da resposta). | uuid | |
| `feedback` * |  boolean | Booleano de aprovação ou rejeição das transferências: "true" ou "false". | true/false |

---

# Comprovante de transferência

URL: /documentation/movimentacao_de_contas/comprovante_de_transferencia

## Request

ENDPOINT /transaction_receipt/ TRANSACTION_KEY
MÉTODO GET

:::info

A resposta desta requisição irá trazer os dados referentes á aquela transação consultada e caso o parâmetro PDF seja verdadeiro o campo "pdf_encoded_string" estará disponível com a string do PDF encodada em base-64.
:::

### Request Path Params

| Campo               | Tipo    | Descrição                         | Caracteres |
|---------------------|---------|-----------------------------------|------------|
| `transaction_key` * | uuidv4 | Chave única de identificação da transação. | 36         |

### Request Query String Params

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---|------------| 
| `pdf` * | boolean | Booleano que define se a resposta deverá gerar um PDF ou não. | - |

## Response

### Success Response

STATUS 200

**Response Body: Comprovantes de pagamento de boleto bancário**

```json
{
    "bank_slip": {
        "beneficiary": {
            "document_number": "03782617037",
            "document_number_formatted": "037.826.170-37",
            "name": "Beatriz Couto de Carvalho"
        },
        "digitable_line": "32992269485000000000554007797902798030027500000",
        "expiration_date": "2024-08-09",
        "expiration_date_formatted": "09/08/2024",
        "financial_institution_compe_number": "329",
        "financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
        "payer": {
            "document_number": "32402502000135",
            "document_number_formatted": "32.402.502/0001-35",
            "name": "QI SCD S.A."
        },
        "payment_date": "2024-08-06",
        "payment_date_formatted": "06/08/2024",
        "payment_key": "ca944fbb-7f0f-42d7-b775-1014f5804155",
        "tax_collection_info": null
    },
    "origin_key": "ca944fbb-7f0f-42d7-b775-1014f5804155",
    "pdf_encoded_string": "JVBERi0xLjcKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvUGFnZXMKL0NvdW50IDEKL0tpZHMgWyA0IDAgUiBdCj4+CmVuZG9iagoyIDAgb2JqCjw8Ci9Qcm9kdWNlciAoUHlQREYyKQo+PgplbmRvYmoKMyAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMSAwIFIKPj4KZW5kb2JqCjQgMCBvYmoKPDwKL1R5cGUgL1BhZ2UKL01lZGlhQm94IFsgMCAwIDU5NS4yNzU1OTEgODQxLjg4OTc2NCBdCi9Db250ZW50cyA1IDAgUgovUmVzb3VyY2VzIDw8Ci9FeHRHU3RhdGUgPDwKL2ExLjAgPDwKL2NhIDEKPj4KL2ExIDw8Ci9jYSAxCj4+Ci9hMC43IDw8Ci9jYSAwLjcKPj4KL0VHUzYgNiAwIFIKPj4KL0ZvbnQgPDwKL1ZDQVRXUyA3IDAgUgovT0NITlVQIDEyIDAgUgo+PgovWE9iamVjdCA8PAovSW00IDE3IDAgUgovVHI1IDE5IDAgUgo+PgovUHJvY1NldCBbIC9UZXh0IC9JbWFnZUkgL0ltYWdlQiAvSW1hZ2VDIC9QREYgXQo+PgovVHJpbUJveCBbIDAgMCA1OTUuMjc1NTkxIDg0MS44ODk3NjQgXQovQmxlZWRCb3ggWyAwIDAgNTk1LjI3NTU5MSA4NDEuODg5NzY0IF0KL0Fubm90cyBbIF0KL1BhcmVudCAxIDAgUgo+PgplbmRvYmoKNSAwIG9iago8PAovTGVuZ3RoIDI2MDQwCj4+CnN0cmVhbQpxCjEgMCAwIC0xIDAgODQxLjg4OTc2NCBjbQpxCjAuNzUgMCAwIDAuNzUgMCAwIGNtCnEKcQpxCnEKcQpxCjAgMCBtCjc5My43MDA3ODcgMCBsCjc5My43MDA3ODcgMCA3OTMuNzAwNzg3IDAgNzkzLjcwMDc4NyAwIGMKNzkzLjcwMDc4NyAxNDYuNDY4NzUgbAo3OTMuNzAwNzg3IDE1MS45Njg3NSA3ODkuMjAwNzg3IDE1Ni40Njg3NSA3ODMuNzAwNzg3IDE1Ni40Njg3NSBjCjEwIDE1Ni40Njg3NSBsCjQuNSAxNTYuNDY4NzUgMCAxNTEuOTY4NzUgMCAxNDYuNDY4NzUgYwowIDAgbAowIDAgMCAwIDAgMCBjClcKbgpxCjAuMDk4MDM5IDAuMTQxMTc2IDAuNDk0MTE4IHJnCi9hMS4wIGdzCjAgMCA3OTMuNzAwNzg3IDE1Ni40Njg3NSByZQpXCm4KMCAwIDc5My43MDA3ODcgMTU2LjQ2ODc1IHJlCmYKUQpRCnEKNzkzLjcwMDc4NyAwIG0KMCAwIGwKMCA1IGwKNzkzLjcwMDc4NyA1IGwKVyoKbgoxIDAuMjUwOTggMC41MDE5NjEgcmcKL2ExLjAgZ3MKMCA1IG0KNzkzLjcwMDc4NyA1IGwKNzkzLjcwMDc4NyA1IDc5My43MDA3ODcgNSA3OTMuNzAwNzg3IDUgYwo3OTMuNzAwNzg3IDE0Ni40Njg3NSBsCjc5My43MDA3ODcgMTUxLjk2ODc1IDc4OS4yMDA3ODcgMTU2LjQ2ODc1IDc4My43MDA3ODcgMTU2LjQ2ODc1IGMKMTAgMTU2LjQ2ODc1IGwKNC41IDE1Ni40Njg3NSAwIDE1MS45Njg3NSAwIDE0Ni40Njg3NSBjCjAgNSBsCjAgNSAwIDUgMCA1IGMKMCAwIG0KNzkzLjcwMDc4NyAwIGwKNzkzLjcwMDc4NyAwIDc5My43MDA3ODcgMCA3OTMuNzAwNzg3IDAgYwo3OTMuNzAwNzg3IDE0Ni40Njg3NSBsCjc5My43MDA3ODcgMTUxLjk2ODc1IDc4OS4yMDA3ODcgMTU2LjQ2ODc1IDc4My43MDA3ODcgMTU2LjQ2ODc1IGMKMTAgMTU2LjQ2ODc1IGwKNC41IDE1Ni40Njg3NSAwIDE1MS45Njg3NSAwIDE0Ni40Njg3NSBjCjAgMCBsCjAgMCAwIDAgMCAwIGMKZioKUQpRCnEKcQowIDAgMCByZwovYTEuMCBncwpCVApFVAoxIDEgMSByZwpCVAoxIDAgMCAtMSAyNTIuNjQ4MjQ1IDgxLjQ4MTQ0NSBUbQovVkNBVFdTIDE4IFRmClsgPDAwMjYwMDUyMDA1MDAwNTMwMDU1MDA1MjAwNTkwMDQ0MDA1MTAwNTcwMDQ4MDAwMzAwNDcwMDQ4MDAwMzAwNTMwMDQ0MDA0YTAwNDQwMDUwMDA0ODAwNTEwMDU3MDA1Mj4gXSBUSgoxIDAgMCAtMSAzNjIuMjY4MzYyIDEwNS44NjUyMzQgVG0KL09DSE5VUCAxMiBUZgpbIDwwMDEzMDAxOTAwMTIwMDEzMDAxYjAwMTIwMDE1MDAxMzAwMTUwMDE3PiBdIFRKCkVUClEKUQpxCnEKMzU4LjM1MDM5NCAyNSA3NyAyMiByZQpXCm4KcQovYTEgZ3MKMSAwIDAgMSAzNTguMzUwMzk0IDI1IGNtCnEKcQoxIDAgMCAxIDAgMCBjbQoxIDAgMCAxIDAgMCBjbQpxCjAgMCBtCjMuNTYzNzIgNi4yNTAwMSBtCjMuODgyODcgNi4yNTA4OSA0LjE5NDYxIDYuMzUyNDMgNC40NTk1NSA2LjU0MTgyIGMKNC43MjQ0OSA2LjczMTIgNC45MzA3NCA2Ljk5OTkyIDUuMDUyMjMgNy4zMTQwMSBjCjUuMTczNzMgNy42MjgxMSA1LjIwNTAyIDcuOTczNDkgNS4xNDIxNSA4LjMwNjUxIGMKNS4wNzkyOCA4LjYzOTUzIDQuOTI1MDcgOC45NDUyMyA0LjY5OTAxIDkuMTg1MDEgYwo0LjQ3Mjk2IDkuNDI0NzggNC4xODUxOSA5LjU4Nzg1IDMuODcyMDggOS42NTM2MSBjCjMuNTU4OTcgOS43MTkzOCAzLjIzNDU4IDkuNjg0ODkgMi45Mzk4OCA5LjU1NDQ5IGMKMi42NDUxOSA5LjQyNDEgMi4zOTM0MiA5LjIwMzY2IDIuMjE2NCA4LjkyMTAzIGMKMi4wMzkzNyA4LjYzODQgMS45NDUwNCA4LjMwNjI2IDEuOTQ1MzEgNy45NjY1OSBjCjEuOTQ1MzEgNy43NDA2NiAxLjk4NzIxIDcuNTE2OTYgMi4wNjg2MSA3LjMwODMxIGMKMi4xNTAwMSA3LjA5OTY2IDIuMjY5MzEgNi45MTAxNiAyLjQxOTY3IDYuNzUwNjkgYwoyLjU3MDAzIDYuNTkxMjEgMi43NDg0OCA2LjQ2NDg5IDIuOTQ0OCA2LjM3ODk3IGMKMy4xNDExMyA2LjI5MzA2IDMuMzUxNDUgNi4yNDkyMyAzLjU2MzcyIDYuMjUwMDEgYwpoCjE2LjkgMTQuOTMxMSBtCjE0Ljk5MzYgMTMuMjI0OSAxMy4xNzM0IDEwLjYwNzkgMTEuNTc0NCAxMi40Mjk2IGMKMTAuMzY5MyAxMy44MDQgMTEuNjAzNyAxNC44NTcxIDEyLjI0MSAxNS41MDczIGMKMTMuOTAxMiAxNy4yMzcyIDE2LjA3NjIgMTkuNTY4NCAxNy44NjAyIDIxLjE0NTggYwoxOC40NTU4IDIxLjY3MTYgMTguNzcwMyAyMS44MDYzIDE5LjIwNTkgMjEuOTEgYwoyMC41MjM3IDIyLjIxOTYgMjEuMjY2OCAyMS4wMjE0IDIxLjAxNDkgMTkuODM2NSBjCjIwLjc3ODQgMTguNzAzNSAxOS41ODcyIDE3LjU4MDggMTkuMzMzOSAxNy40NDE2IGMKMjAuMjU3OSAxNi4wNzUgMjAuODUxOSAxNC40ODc2IDIxLjA2MzYgMTIuODE5MSBjCjIxLjM2MzggMTAuNjA3NSAyMS4wMDQxIDguMzUxNCAyMC4wMzUzIDYuMzY4OTkgYwoxOC42NDM3IDMuNTU0OTIgMTYuMTM4OCAxLjc1MjQ0IDE0LjIxOTggMS4xMzc3OSBjCjEzLjE4MTcgMC44MDQ1NDYgMTIuMjI0MyAwLjkyMzAzMyAxMS43NTEyIDEuMjg1OSBjCjExLjE4NDggMS43MTM5MyAxMC44OTk1IDIuNzMyOTIgMTEuMzY1NyAzLjU1Nzg5IGMKMTEuNDQ1OSAzLjcwNTE5IDExLjU1MzQgMy44MzM2MyAxMS42ODE2IDMuOTM1NDYgYwoxMS44MDk4IDQuMDM3MjkgMTEuOTU2MSA0LjExMDM4IDEyLjExMTYgNC4xNTAzMiBjCjEyLjc4MjMgNC4zMjA2NSAxNC4wOTE4IDQuNjgyMDMgMTUuMjE0OCA1LjYzMTQxIGMKMTYuNDU1OCA2LjY0NzEyIDE3LjMyNDEgOC4wOTI2IDE3LjY2OTYgOS43MTc3MiBjCjE4LjA1NSAxMS40NjM5IDE3LjcyOCAxMy42MTQ1IDE2LjkwMTQgMTQuOTMxMSBjCjIuMzMzMTcgMTEuODMwOCBtCjEuMzg5NjggMTIuMjQ5OSAxLjI0NDk2IDEzLjE0NDUgMS40MzY5OSAxNC4wODIgYwoxLjc0NTkyIDE1LjU5MTIgMi45NTI0MyAxNy42OTI5IDMuODgyIDE4LjY5MTEgYwo1LjI3MzU4IDIwLjE3MjIgNi45NDM0OCAyMS4yNzg2IDguOTA3IDIxLjcyMTQgYwoxMC41MTE1IDIyLjA4MjggMTIuMjcwNSAyMi4wOTE3IDEzLjIzMDYgMjEuNzUyNiBjCjE0LjYyMjIgMjEuMjYwOCAxNC44NjAyIDE4LjQ2OSAxMi41NTQzIDE4LjQyOSBjCjEyLjE4MjggMTguNDI5IDExLjc2NjcgMTguNDU1NyAxMS4zMjU2IDE4LjQ3NDkgYwoxMC40MzM2IDE4LjUxMDYgOS41NDM4NiAxOC4zNTc2IDguNzA3ODMgMTguMDI0OCBjCjcuODcxNzkgMTcuNjkyIDcuMTA2MDkgMTcuMTg2MSA2LjQ1NTAzIDE2LjUzNjIgYwo1LjkxNCAxNi4wMTQgNS40NzEwNSAxNS4zODczIDUuMTQ5NzMgMTQuNjg5MyBjCjQuOTQ2MjEgMTQuMjQ5NCA0Ljc2NTUgMTMuNzk4IDQuNjA4NDEgMTMuMzM3IGMKNC41MjYzIDEzLjA3MzQgNC41Mzg4MyAxMi44MTg2IDQuMzgwMTkgMTIuNTQwMiBjCjQuMTcyNDMgMTIuMTg0IDMuODUzMDIgMTEuOTE3NCAzLjQ3ODQzIDExLjc4NzUgYwozLjEwMzg0IDExLjY1NzcgMi42OTgxOCAxMS42NzMgMi4zMzMxNyAxMS44MzA4IGMKaAowLjMwOTgwNCAwLjggMC45Mjk0MTIgcmcKL2ExLjAgZ3MKMSB3CjAgSgowIGoKNCBNCmYqClEKcQowIDAgbQo4Ljk4NDczIDcuMDM3MTEgbQo5LjQ4MjY4IDcuMDM2ODIgOS45Njk1MiA3LjE5MzcxIDEwLjM4MzcgNy40ODc5MyBjCjEwLjc5NzggNy43ODIxNiAxMS4xMjA3IDguMjAwNSAxMS4zMTE1IDguNjkwMDUgYwoxMS41MDIyIDkuMTc5NiAxMS41NTIzIDkuNzE4MzYgMTEuNDU1MyAxMC4yMzgyIGMKMTEuMzU4MyAxMC43NTggMTEuMTE4NyAxMS4yMzU2IDEwLjc2NjcgMTEuNjEwNCBjCjEwLjQxNDcgMTEuOTg1MyA5Ljk2NjExIDEyLjI0MDYgOS40Nzc3NSAxMi4zNDQxIGMKOC45ODkzOSAxMi40NDc2IDguNDgzMTYgMTIuMzk0NiA4LjAyMzA5IDEyLjE5MTkgYwo3LjU2MzAxIDExLjk4OTEgNy4xNjk3NyAxMS42NDU3IDYuODkzMSAxMS4yMDUxIGMKNi42MTY0MyAxMC43NjQ0IDYuNDY4NzUgMTAuMjQ2NCA2LjQ2ODc1IDkuNzE2MzkgYwo2LjQ2ODc1IDkuMDA2MDYgNi43MzM3OCA4LjMyNDggNy4yMDU1OCA3LjgyMjM4IGMKNy42NzczOCA3LjMxOTk2IDguMzE3MzIgNy4wMzc1IDguOTg0NzMgNy4wMzcxMSBjCmgKNi41MTA5NiAwIG0KNi44OTkwMyAwIDcuMjc4MzkgMC4xMjI0NzkgNy42MDEwNiAwLjM1MTk0OCBjCjcuOTIzNzMgMC41ODE0MTYgOC4xNzUyMiAwLjkwNzU2OCA4LjMyMzczIDEuMjg5MTYgYwo4LjQ3MjI0IDEuNjcwNzUgOC41MTEwOSAyLjA5MDY1IDguNDM1MzkgMi40OTU3NCBjCjguMzU5NjggMi45MDA4NCA4LjE3MjggMy4yNzI5NSA3Ljg5ODM5IDMuNTY1IGMKNy42MjM5OCAzLjg1NzA2IDcuMjc0MzcgNC4wNTU5NiA2Ljg5Mzc1IDQuMTM2NTQgYwo2LjUxMzEzIDQuMjE3MTEgNi4xMTg2MiA0LjE3NTc2IDUuNzYwMDggNC4wMTc3IGMKNS40MDE1NSAzLjg1OTY0IDUuMDk1MTEgMy41OTE5NyA0Ljg3OTUxIDMuMjQ4NTQgYwo0LjY2MzkxIDIuOTA1MTIgNC41NDg4MyAyLjUwMTM2IDQuNTQ4ODMgMi4wODgzMyBjCjQuNTQ4ODMgMS41MzQ0NyA0Ljc1NTU1IDEuMDAzMyA1LjEyMzUyIDAuNjExNjU3IGMKNS40OTE0OSAwLjIyMDAxOSA1Ljk5MDU3IDAgNi41MTA5NiAwIGMKaAoxLjIyNTk4IDIuMzM4OSBtCjEuNDcwNTIgMi4zMzcxNCAxLjcxMDA0IDIuNDEyNzMgMS45MTQxNSAyLjU1NjA3IGMKMi4xMTgyNiAyLjY5OTQyIDIuMjc3NzYgMi45MDQwNiAyLjM3MjQzIDMuMTQ0MDMgYwoyLjQ2NzA5IDMuMzg0MDEgMi40OTI2NSAzLjY0ODUxIDIuNDQ1ODYgMy45MDM5NyBjCjIuMzk5MDYgNC4xNTk0MyAyLjI4MjAzIDQuMzk0MzQgMi4xMDk2IDQuNTc4OSBjCjEuOTM3MTggNC43NjM0NiAxLjcxNzEzIDQuODg5MzUgMS40NzczNyA0Ljk0MDYgYwoxLjIzNzYyIDQuOTkxODQgMC45ODg5NjUgNC45NjYxNCAwLjc2Mjk1NyA0Ljg2Njc0IGMKMC41MzY5NSA0Ljc2NzM1IDAuMzQzNzc1IDQuNTk4NzUgMC4yMDc5MzkgNC4zODIzMiBjCjAuMDcyMTA0IDQuMTY1OSAtMC4wMDAyNjkgMy45MTE0MSAwLjAwMDAwMSAzLjY1MTE0IGMKMC4wMDAwMDEgMy4zMDMxMSAwLjEyOTg5OSAyLjk2OTM0IDAuMzYxMTIxIDIuNzIzMjUgYwowLjU5MjM0MiAyLjQ3NzE1IDAuOTA1OTQ1IDIuMzM4OSAxLjIzMjk0IDIuMzM4OSBjCjAuMzA5ODA0IDAuOCAwLjkyOTQxMiByZwovYTEuMCBncwoxIHcKMCBKCjAgago0IE0KZioKUQpxCjAgMCBtCjYxLjg4ODkgMTQuMTA4NCBtCjYxLjQyOSAxNC4xMTc3IDYwLjk2OTcgMTQuMDY4IDYwLjUyMSAxMy45NjAzIGMKNjAuMTk3MiAxMy44ODU5IDU5Ljg5NjIgMTMuNzI2IDU5LjY0NTcgMTMuNDk1MiBjCjU5LjQxOTIgMTMuMjY3OCA1OS4yNTggMTIuOTc2NiA1OS4xODA5IDEyLjY1NTQgYwo1OS4wODA2IDEyLjIzOSA1OS4wMzM3IDExLjgxIDU5LjA0MTggMTEuMzgwMiBjCjU5LjA0MTggOC44ODYwOCBsCjU5LjAzNDUgOC40NTgyNSA1OS4wODEzIDguMDMxMzMgNTkuMTgwOSA3LjYxNjc5IGMKNTkuMjU3IDcuMjkzOTYgNTkuNDE4MyA3LjAwMTAzIDU5LjY0NTcgNi43NzI1NyBjCjU5Ljg5NjIgNi41NDE4MSA2MC4xOTcyIDYuMzgxODcgNjAuNTIxIDYuMzA3NTEgYwo2MC45Njk3IDYuMTk5NzQgNjEuNDI5IDYuMTUwMDEgNjEuODg4OSA2LjE1OTQgYwo2Ny4wNjU2IDYuMTU5NCBsCjY3LjA2NTYgNy42ODY0IGwKNjEuOTY1NSA3LjY4NjQgbAo2MS43NTQyIDcuNjgxNDYgNjEuNTQzMSA3LjcwMjgzIDYxLjMzNjUgNy43NTAwOCBjCjYxLjE5MDkgNy43ODIyNiA2MS4wNTY2IDcuODU2NTcgNjAuOTQ4MiA3Ljk2NDg0IGMKNjAuODQ3OCA4LjA3NjQ2IDYwLjc3OTIgOC4yMTYxOCA2MC43NTA2IDguMzY3NyBjCjYwLjcxMTIgOC41NjgzMSA2MC42OTMgOC43NzI5OSA2MC42OTY0IDguOTc3OSBjCjYwLjY5NjQgMTEuMzA3NyBsCjYwLjY5MjUgMTEuNTE1IDYwLjcxMDcgMTEuNzIyMiA2MC43NTA2IDExLjkyNTMgYwo2MC43ODAyIDEyLjA3NDMgNjAuODQ4NyAxMi4yMTEzIDYwLjk0ODIgMTIuMzIwNyBjCjYxLjA1NzUgMTIuNDMwMSA2MS4xOTQzIDEyLjUwMzIgNjEuMzQyIDEyLjUzMSBjCjYxLjU1MTEgMTIuNTczNSA2MS43NjM4IDEyLjU5MjggNjEuOTc2NiAxMi41ODg4IGMKNjcuMDY1NiAxMi41ODg4IGwKNjcuMDY1NiAxNC4xMDI1IGwKNjEuODg4OSAxNC4xMDg0IGwKaAo1Mi44MTcyIDE0LjEwODQgbQo1Mi4zNTczIDE0LjExNzcgNTEuODk4IDE0LjA2OCA1MS40NDkzIDEzLjk2MDMgYwo1MS4xMjU1IDEzLjg4NTkgNTAuODI0NCAxMy43MjYgNTAuNTc0IDEzLjQ5NTIgYwo1MC4zNDc1IDEzLjI2NzggNTAuMTg2MyAxMi45NzY2IDUwLjEwOTIgMTIuNjU1NCBjCjUwLjAwODggMTIuMjM5IDQ5Ljk2MiAxMS44MSA0OS45NyAxMS4zODAyIGMKNDkuOTcgOC44ODYwOCBsCjQ5Ljk2MjggOC40NTgyNSA1MC4wMDk2IDguMDMxMzMgNTAuMTA5MiA3LjYxNjc5IGMKNTAuMTg1MyA3LjI5Mzk2IDUwLjM0NjYgNy4wMDEwMyA1MC41NzQgNi43NzI1NyBjCjUwLjgyNDQgNi41NDE4MSA1MS4xMjU1IDYuMzgxODcgNTEuNDQ5MyA2LjMwNzUxIGMKNTEuODk4IDYuMTk5NzQgNTIuMzU3MyA2LjE1MDAxIDUyLjgxNzIgNi4xNTk0IGMKNTQuNjU1NSA2LjE1OTQgbAo1NC42NTU1IDcuNjYyNyBsCjUyLjgxNzIgNy42NjI3IGwKNTIuNjE4OCA3LjY1NzYxIDUyLjQyMDYgNy42NzkwMSA1Mi4yMjcyIDcuNzI2MzkgYwo1Mi4wOTAzIDcuNzU5ODIgNTEuOTYzOCA3LjgzMDIxIDUxLjg1OTggNy45MzA3OCBjCjUxLjc2NDYgOC4wMzI0NCA1MS42OTk3IDguMTYxNzcgNTEuNjczMyA4LjMwMjUzIGMKNTEuNjM4NyA4LjQ5NDc4IDUxLjYyMzMgOC42OTAzOCA1MS42Mjc0IDguODg2MDggYwo1MS42Mjc0IDkuNDIyMjMgbAo1Ny45ODU1IDkuNDIyMjMgbAo1Ny45ODU1IDEwLjgzMjIgbAo1MS42Mjc0IDEwLjgzMjIgbAo1MS42Mjc0IDExLjM5MDYgbAo1MS42MjQxIDExLjU4OTMgNTEuNjQwNCAxMS43ODc5IDUxLjY3NjEgMTEuOTgzIGMKNTEuNzAxOCAxMi4xMjMyIDUxLjc2NDUgMTIuMjUyNyA1MS44NTcgMTIuMzU2MyBjCjUxLjk1OTIgMTIuNDU3MiA1Mi4wODY5IDEyLjUyNDEgNTIuMjI0NCAxMi41NDg4IGMKNTIuNDIwOSAxMi41ODY4IDUyLjYyMDMgMTIuNjA0MiA1Mi44MiAxMi42MDA2IGMKNTguMDI4NyAxMi42MDA2IGwKNTguMDI4NyAxNC4xMDI1IGwKNTIuODE3MiAxNC4xMDg0IGwKaAo0NC4zNTkyIDE0LjEwODQgbQo0NC4zNTkyIDcuNjkyMzIgbAo0MS4yMjk1IDcuNjkyMzIgbAo0MS4yMjk1IDYuMTY1MzIgbAo0OS4xNjE1IDYuMTY1MzIgbAo0OS4xNjE1IDcuNjkyMzIgbAo0Ni4wMzMzIDcuNjkyMzIgbAo0Ni4wMzMzIDE0LjEwODQgbAo0NC4zNTkyIDE0LjEwODQgbApoCjM0LjMzOTggNi4xNjUzMiBtCjM2LjAwOTcgNi4xNjUzMiBsCjM2LjAwOTcgMTQuMTA4NCBsCjM0LjMzOTggMTQuMTA4NCBsCjM0LjMzOTggNi4xNjUzMiBsCmgKMzEuNDMgOC45NzkzOSBtCjMxLjQzNCA4Ljc3MjA5IDMxLjQxMzQgOC41NjUwOCAzMS4zNjg4IDguMzYzMjUgYwozMS4zMzYzIDguMjE0MDQgMzEuMjY2NiA4LjA3NjkxIDMxLjE2NyA3Ljk2NjMyIGMKMzEuMDU5MiA3Ljg1ODM1IDMwLjkyNDQgNy43ODU4MyAzMC43Nzg3IDcuNzU3NDkgYwozMC41Nzg1IDcuNzE1NCAzMC4zNzQ3IDcuNjk2MDMgMzAuMTcwNiA3LjY5OTczIGMKMjcuNDg0OSA3LjY5OTczIGwKMjcuMjcwMiA3LjY5NTA5IDI3LjA1NTYgNy43MTQ0NSAyNi44NDQ3IDcuNzU3NDkgYwoyNi42OTkxIDcuNzg1ODMgMjYuNTY0MyA3Ljg1ODM1IDI2LjQ1NjUgNy45NjYzMiBjCjI2LjM1NzkgOC4wNzYyMSAyNi4yOTEyIDguMjE0MDMgMjYuMjY0NSA4LjM2MzI1IGMKMjYuMjI4OSA4LjU2NjM4IDI2LjIxMjUgOC43NzI3OSAyNi4yMTU3IDguOTc5MzkgYwoyNi4yMTU3IDExLjAwNyBsCjI2LjIxMjggMTEuMjY3OCAyNi4yMjU0IDExLjUyODQgMjYuMjUzMyAxMS43ODc1IGMKMjYuMjY4NyAxMS45NTk4IDI2LjMyNzQgMTIuMTI0NSAyNi40MjMxIDEyLjI2NDQgYwoyNi41MjE2IDEyLjM4NzcgMjYuNjU2NSAxMi40NzE4IDI2LjgwNTggMTIuNTAyOSBjCjI3LjAyOTEgMTIuNTUxOCAyNy4yNTY5IDEyLjU3MzYgMjcuNDg0OSAxMi41NjgxIGMKMzAuMTc2MiAxMi41NjgxIGwKMzAuMzggMTIuNTcxNSAzMC41ODM3IDEyLjU1MzYgMzAuNzg0MyAxMi41MTQ3IGMKMzAuOTI4NSAxMi40OTQxIDMxLjA2MyAxMi40MjU4IDMxLjE2ODggMTIuMzE5NSBjCjMxLjI3NDcgMTIuMjEzMiAzMS4zNDY1IDEyLjA3NDMgMzEuMzc0MyAxMS45MjIzIGMKMzEuNDE5MSAxMS43MTQ1IDMxLjQzOTcgMTEuNTAxNiAzMS40MzU2IDExLjI4ODQgYwozMS40MyA4Ljk3OTM5IGwKaAozMS42MTA5IDE1LjI1NDcgbQozMC41MzggMTQuMDMxNCBsCjI3LjQxMzkgMTQuMDMxNCBsCjI2Ljk1MSAxNC4wNDA3IDI2LjQ4ODYgMTMuOTk2IDI2LjAzNDggMTMuODk4MSBjCjI1LjcxMjEgMTMuODMyMyAyNS40MTA3IDEzLjY3OTMgMjUuMTU5NSAxMy40NTM3IGMKMjQuOTMzMyAxMy4yMzE0IDI0Ljc3MiAxMi45NDQ1IDI0LjY5NDggMTIuNjI3MyBjCjI0LjU5NDMgMTIuMjEyOSAyNC41NDc0IDExLjc4NTkgMjQuNTU1NiAxMS4zNTggYwoyNC41NTU2IDguODg2MDggbAoyNC41NDgzIDguNDU4MjUgMjQuNTk1MSA4LjAzMTMzIDI0LjY5NDggNy42MTY3OSBjCjI0Ljc3MDkgNy4yOTM5NiAyNC45MzIxIDcuMDAxMDMgMjUuMTU5NSA2Ljc3MjU3IGMKMjUuNDEgNi41NDE4MSAyNS43MTEgNi4zODE4NyAyNi4wMzQ4IDYuMzA3NTEgYwoyNi40ODczIDYuMTk5NDEgMjYuOTUwMyA2LjE0OTY4IDI3LjQxMzkgNi4xNTk0IGMKMzAuMjQ4NiA2LjE1OTQgbAozMC43MTE3IDYuMTQ5NjcgMzEuMTc0MyA2LjE5OTQgMzEuNjI2MiA2LjMwNzUxIGMKMzEuOTUwMSA2LjM4MTU3IDMyLjI1MTIgNi41NDE1NCAzMi41MDE1IDYuNzcyNTcgYwozMi43Mjk0IDcuMDAwODkgMzIuODkxMSA3LjI5MzgyIDMyLjk2NzcgNy42MTY3OSBjCjMzLjA2NjYgOC4wMzE0NyAzMy4xMTM0IDguNDU4MjkgMzMuMTA2OSA4Ljg4NjA4IGMKMzMuMTA2OSAxMS4zNDQ3IGwKMzMuMTIwMyAxMS44Mjc5IDMzLjA1NzMgMTIuMzEgMzIuOTIwNCAxMi43NzEgYwozMi44MDIyIDEzLjEzMjQgMzIuNTY1NSAxMy40MzYzIDMyLjI1MzggMTMuNjI3IGMKMzMuNjU2NSAxNS4yNTQ3IGwKMzEuNjEwOSAxNS4yNTQ3IGwKaAo3NS4zNDc1IDEyLjE1OTggbQo3NS4zNDc1IDEwLjk2MDEgbAo2OS44NzU4IDEwLjk2MDEgbAo2OS44NzU4IDE0LjEyODEgbAo2OC4yMTI5IDE0LjEyODEgbAo2OC4yMTI5IDYuMTgzNTkgbAo2OS44NzU4IDYuMTgzNTkgbAo2OS44NzU4IDkuNDIyNzMgbAo3NS4zNDc1IDkuNDIyNzMgbAo3NS4zNDc1IDYuMTgzNTkgbAo3Ni45OTkzIDYuMTgzNTkgbAo3Ni45OTkzIDEyLjE1OTggbAo3NS4zNDc1IDEyLjE1OTggbApoCjc2Ljk5OTggMTIuNjg4NSBtCjc1LjM1MzUgMTIuNjg4NSBsCjc1LjM1MzUgMTQuMTUxOCBsCjc2Ljk5OTggMTQuMTUxOCBsCjc2Ljk5OTggMTIuNjg4NSBsCmgKMC4zMDk4MDQgMC44IDAuOTI5NDEyIHJnCi9hMS4wIGdzCjEgdwowIEoKMCBqCjQgTQpmClEKMSB3CjAgSgowIGoKNCBNCm4KUQpRClEKUQpRCnEKcQozNzQuODUwMzk0IDEzMy42OTUzMTIgNDQgNDQgcmUKVwpuCnEKL2ExIGdzCjEgMCAwIDEgMzc0Ljg1MDM5NCAxMzMuNjk1MzEyIGNtCnEKcQoxIDAgMCAxIDAgMCBjbQoxIDAgMCAxIDAgMCBjbQpxCjQzLjIgMjEuNiBtCjQzLjIgMzMuNzg2NDk1IDMzLjc4NjQ5NSA0My4yIDIxLjYgNDMuMiBjCjkuNDEzNTA1IDQzLjIgMCAzMy43ODY0OTUgMCAyMS42IGMKMCA5LjQxMzUwNSA5LjQxMzUwNSAwIDIxLjYgMCBjCjMzLjc4NjQ5NSAwIDQzLjIgOS40MTM1MDUgNDMuMiAyMS42IGMKaAoxIDAuMjUwOTggMC41MDE5NjEgcmcKL2ExLjAgZ3MKMSB3CjAgSgowIGoKNCBNCmYKUQpxCjAgMCBtCjIyLjY5NSAyMC41ODUgbQoyMC41MDUgMjAuNTg1IGwKMTkuMjYwODI4IDIwLjU4NzIxNyAxOC4yNDk1MTEgMTkuNTgyMTYyIDE4LjI0NCAxOC4zMzggYwoxOC4yNTAwNiAxNy4wOTQyMjkgMTkuMjYxMjE2IDE2LjA4OTc4MSAyMC41MDUgMTYuMDkyIGMKMjQuODg0IDE2LjA5MiBsCjI1LjQ0OCAxNi4wOTIgMjUuOTA1IDE1LjYzNyAyNS45MDUgMTUuMDc3IGMKMjUuOTA1IDE0LjUxNyAyNS40NDggMTQuMDYyIDI0Ljg4NCAxNC4wNjIgYwoyMi42MjIgMTQuMDYyIGwKMjIuNjIyIDExLjgxNSBsCjIyLjYyMiAxMS4yNTUgMjIuMTY0IDEwLjggMjEuNiAxMC44IGMKMjEuMDM2IDEwLjggMjAuNTc4IDExLjI1NCAyMC41NzggMTEuODE1IGMKMjAuNTc4IDE0LjA2MiBsCjIwLjUwNiAxNC4wNjIgbAoxOC4xMzEgMTQuMDYyIDE2LjIgMTUuOTggMTYuMiAxOC4zMzggYwoxNi4yIDIwLjY5NiAxOC4xMzEgMjIuNjE1IDIwLjUwNiAyMi42MTUgYwoyMi42OTUgMjIuNjE1IGwKMjMuOTM5MTcyIDIyLjYxMjc4MyAyNC45NTA0ODkgMjMuNjE3ODM4IDI0Ljk1NiAyNC44NjIgYwoyNC45NDk5NCAyNi4xMDU3NzEgMjMuOTM4Nzg0IDI3LjExMDIxOSAyMi42OTUgMjcuMTA4IGMKMTguMzE3IDI3LjEwOCBsCjE3Ljc1MiAyNy4xMDggMTcuMjk1IDI3LjU2MyAxNy4yOTUgMjguMTIzIGMKMTcuMjk1IDI4LjY4MyAxNy43NTIgMjkuMTM4IDE4LjMxNiAyOS4xMzggYwoyMC41NzggMjkuMTM4IGwKMjAuNTc4IDMxLjM4NSBsCjIwLjU3OCAzMS45NDUgMjEuMDM2IDMyLjQgMjEuNiAzMi40IGMKMjIuMTY0IDMyLjQgMjIuNjIyIDMxLjk0NiAyMi42MjIgMzEuMzg1IGMKMjIuNjIyIDI5LjEzOCBsCjIyLjY5NSAyOS4xMzggbAoyNS4wNjkgMjkuMTM4IDI3IDI3LjIyIDI3IDI0Ljg2MiBjCjI3IDIyLjUwNCAyNS4wNjkgMjAuNTg1IDIyLjY5NSAyMC41ODUgYwpoCjEgMSAxIHJnCi9hMS4wIGdzCjEgdwowIEoKMCBqCjQgTQpmClEKMSB3CjAgSgowIGoKNCBNCm4KUQpRClEKUQpRCnEKcQowLjQxMTc2NSAwLjQ0NzA1OSAwLjQ5MDE5NiByZwovYTEuMCBncwpCVAoxIDAgMCAtMSAzMjIuNTM4ODcgMjE0LjYyMzA0NyBUbQovT0NITlVQIDEyIFRmClsgPDAwMzM+IDYzIDwwMDI0PiAxNyA8MDAyYTAwMjQwMDMwMDAyODAwMzEwMDM3MDAzMjAwMDMwMDI3MDAyODAwMDMwMDI1PiAxNyA8MDAzMjAwMmYwMDI4MDAzNzAwMzI+IF0gVEoKRVQKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCkJUCjEgMCAwIC0xIDI2Ni42MDgyMDYgMjYxLjU0Njg3NSBUbQovVkNBVFdTIDMyIFRmClsgPDAwMzUwMDA3MDAwMzAwMTUwMDFhMDAxNzAwMTEwMDFiMDAxMzAwMTMwMDBmMDAxMzAwMTM+IF0gVEoKRVQKUQpRCnEKcQowIDI3Mi40Njg3NSA3OTMuNzAwNzg3IDgyNCByZQpXCm4KcQowLjk0OTAyIDAuOTU2ODYzIDAuOTg4MjM1IHJnCi9hMS4wIGdzCjAgMjcyLjQ2ODc1IDc5My43MDA3ODcgODI0IHJlClcKbgowIDI3Mi40Njg3NSA3OTMuNzAwNzg3IDgyNCByZQpmClEKUQpRCnEKcQowIDI3Mi40Njg3NSA3OTMuNzAwNzg3IDIyOCByZQpXCm4KcQoxIDEgMSByZwovYTEuMCBncwowIDI3Mi40Njg3NSA3OTMuNzAwNzg3IDIyOCByZQpXCm4KMCAyNzIuNDY4NzUgNzkzLjcwMDc4NyAyMjggcmUKZgpRClEKcQo3OTMuNzAwNzg3IDUwMC40Njg3NSBtCjAgNTAwLjQ2ODc1IGwKMCA0OTkuNDY4NzUgbAo3OTMuNzAwNzg3IDQ5OS40Njg3NSBsClcqCm4KMC4wOTgwMzkgMC4xNDExNzYgMC40OTQxMTggcmcKL2ExLjAgZ3MKMCAyNzIuNDY4NzUgNzkzLjcwMDc4NyAyMjcgcmUKMCAyNzIuNDY4NzUgNzkzLjcwMDc4NyAyMjggcmUKZioKUQpRCnEKcQpxCnEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTEuMCBncwpCVAoxIDAgMCAtMSA3NS41OTA1NTEgMzgzLjAwNzgxMiBUbQovVkNBVFdTIDE2IFRmClsgPDAwMTYwMDE1MDAxYzAwMWMwMDE1MDAxNTAwMTkwMDFjMDAxNzAwMWIwMDE4MDAxMzAwMTMwMDEzMDAxMzAwMTMwMDEzMDAxMzAwMTMwMDEzMDAxODAwMTgwMDE3MDAxMzAwMTMwMDFhMDAxYTAwMWMwMDFhMDAxYzAwMTMwMDE1MDAxYTAwMWMwMDFiMDAxMzAwMTYwMDEzMDAxMzAwMTUwMDFhMDAxODAwMTMwMDEzMDAxMzAwMTMwMDEzPiBdIFRKCkVUClEKUQpRClEKcQpxCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2ExLjAgZ3MKQlQKMSAwIDAgLTEgNzUuNTkwNTUxIDQ1OS4wMDc4MTIgVG0KL1ZDQVRXUyAxNiBUZgpbIDwwMDE2MDAxNTAwMWMwMDAzMDAxMDAwMDMwMDM0MDAyYzAwMDMwMDM2MDAzMjAwMjYwMDJjMDAyODAwMjcwMDI0MDAyNzAwMjgwMDAzMDAyNzAwMjgwMDAzMDAyNjAwMzUwMDhiMDAyNzAwMmMwMDM3MDAzMjAwMDMwMDI3MDAyYzAwMzUwMDI4MDAzNzAwMzIwMDAzMDAzNjAwMTEwMDI0PiAtMTggPDAwMTE+IF0gVEoKRVQKUQpRClEKUQpRClEKcQpxCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2ExLjAgZ3MKQlQKMSAwIDAgLTEgMTA5LjU5MDU1MSAzNDkuNjIzMDQ3IFRtCi9PQ0hOVVAgMTIgVGYKWyA8MDAyZjAwNGMwMDUxMDA0YjAwNDQwMDAzMDAyNzAwNGMwMDRhMDA0YzAwNTcwMGEzMDA1OTAwNDgwMDRmPiBdIFRKCkVUClEKUQpRClEKcQpxCjc1LjU5MDU1MSAzMzIuNDY4NzUgMjQgMjQgcmUKVwpuCnEKL2ExIGdzCjEgMCAwIDEgNzUuNTkwNTUxIDMzMi40Njg3NSBjbQpxCnEKMSAwIDAgMSAwIDAgY20KMSAwIDAgMSAwIDAgY20KcQoyNCAxMiBtCjI0IDE4Ljc3MDI3NSAxOC43NzAyNzUgMjQgMTIgMjQgYwo1LjIyOTcyNSAyNCAwIDE4Ljc3MDI3NSAwIDEyIGMKMCA1LjIyOTcyNSA1LjIyOTcyNSAwIDEyIDAgYwoxOC43NzAyNzUgMCAyNCA1LjIyOTcyNSAyNCAxMiBjCmgKMC44NjI3NDUgMC44NzA1ODggMC45NzY0NzEgcmcKL2ExLjAgZ3MKMSB3CjAgSgowIGoKNCBNCmYKUQpxCjAgMCBtCjUuNyA3LjUgbQo0LjggNy41IGwKNC44IDE2LjUgbAo1LjcgMTYuNSBsCjUuNyA3LjUgbApoCjE5LjIgNy41IG0KMTguMyA3LjUgbAoxOC4zIDE2LjUgbAoxOS4yIDE2LjUgbAoxOS4yIDcuNSBsCmgKNy45NSA3LjUgbQo3LjA1IDcuNSBsCjcuMDUgMTQuNyBsCjcuOTUgMTQuNyBsCjcuOTUgNy41IGwKaAo5Ljc1MiA3LjUgbQo4Ljg1MiA3LjUgbAo4Ljg1MiAxNC43IGwKOS43NTIgMTQuNyBsCjkuNzUyIDcuNSBsCmgKMTMuMzUxIDcuNSBtCjEyLjQ1MSA3LjUgbAoxMi40NTEgMTYuNSBsCjEzLjM1MSAxNi41IGwKMTMuMzUxIDcuNSBsCmgKMTUuMTUgNy41IG0KMTQuMjUgNy41IGwKMTQuMjUgMTQuNyBsCjE1LjE1IDE0LjcgbAoxNS4xNSA3LjUgbApoCjcuOTUgMTUuNiBtCjcuMDUgMTUuNiBsCjcuMDUgMTYuNSBsCjcuOTUgMTYuNSBsCjcuOTUgMTUuNiBsCmgKOS43NTIgMTUuNiBtCjguODUyIDE1LjYgbAo4Ljg1MiAxNi41IGwKOS43NTIgMTYuNSBsCjkuNzUyIDE1LjYgbApoCjExLjU1IDcuNSBtCjEwLjY1IDcuNSBsCjEwLjY1IDE0LjcgbAoxMS41NSAxNC43IGwKMTEuNTUgNy41IGwKaAoxMS41NSAxNS42IG0KMTAuNjUgMTUuNiBsCjEwLjY1IDE2LjUgbAoxMS41NSAxNi41IGwKMTEuNTUgMTUuNiBsCmgKMTUuMTUgMTUuNiBtCjE0LjI1IDE1LjYgbAoxNC4yNSAxNi41IGwKMTUuMTUgMTYuNSBsCjE1LjE1IDE1LjYgbApoCjE2Ljk1IDcuNSBtCjE2LjA1IDcuNSBsCjE2LjA1IDE0LjcgbAoxNi45NSAxNC43IGwKMTYuOTUgNy41IGwKaAoxNi45NSAxNS42IG0KMTYuMDUgMTUuNiBsCjE2LjA1IDE2LjUgbAoxNi45NSAxNi41IGwKMTYuOTUgMTUuNiBsCmgKMC4wOTgwMzkgMC4xNDExNzYgMC40OTQxMTggcmcKL2ExLjAgZ3MKMSB3CjAgSgowIGoKNCBNCmYKUQoxIHcKMCBKCjAgago0IE0KbgpRClEKUQpRClEKcQpxCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2ExLjAgZ3MKQlQKMSAwIDAgLTEgMTA5LjU5MDU1MSA0MjUuNjIzMDQ3IFRtCi9PQ0hOVVAgMTIgVGYKWyA8MDAyNTAwNDQwMDUxMDA0NjAwNTIwMDAzMDA0NzAwNDgwMDU2MDA1NzAwNGMwMDUxMDA0NDAwNTcwMGEzMDA1NTAwNGMwMDUyPiBdIFRKCkVUClEKUQpRClEKcQpxCjc1LjU5MDU1MSA0MDguNDY4NzUgMjQgMjQgcmUKVwpuCnEKL2ExIGdzCjEgMCAwIDEgNzUuNTkwNTUxIDQwOC40Njg3NSBjbQpxCnEKMSAwIDAgMSAwIDAgY20KMSAwIDAgMSAwIDAgY20KcQoyNCAxMiBtCjI0IDE4Ljc3MDI3NSAxOC43NzAyNzUgMjQgMTIgMjQgYwo1LjIyOTcyNSAyNCAwIDE4Ljc3MDI3NSAwIDEyIGMKMCA1LjIyOTcyNSA1LjIyOTcyNSAwIDEyIDAgYwoxOC43NzAyNzUgMCAyNCA1LjIyOTcyNSAyNCAxMiBjCmgKMC44NjI3NDUgMC44NzA1ODggMC45NzY0NzEgcmcKL2ExLjAgZ3MKMSB3CjAgSgowIGoKNCBNCmYKUQpxCjAgMCBtCjE4LjEyOSAxMC4yMiBtCjE4LjU4MSAxMC4yMiAxOC45NDkgOS44NTIgMTguOTQ5IDkuNCBjCjE4Ljk0OSA4LjMzNyBsCjE4Ljk0OTkyOCA4LjAwMTkzMiAxOC43NDYxNzQgNy43MDAyNjUgMTguNDM1IDcuNTc2IGMKMTIuMjgyIDUuMDYgbAoxMi4wODU4MzUgNC45ODAzODcgMTEuODY2NDI1IDQuOTgwMDI4IDExLjY3IDUuMDU5IGMKNS41MTQgNy41NzYgbAo1LjIwMjgyNiA3LjcwMDI2NSA0Ljk5OTA3MiA4LjAwMTkzMiA1IDguMzM3IGMKNSA5LjQgbAo1IDkuODUyIDUuMzY4IDEwLjIyIDUuODIgMTAuMjIgYwo2LjMxMyAxMC4yMiBsCjYuMzEzIDE2LjQwMiBsCjUuODIgMTYuNDAyIGwKNS4zNjY5NjQgMTYuNDAyIDQuOTk5NTUyIDE2Ljc2ODk2NSA0Ljk5OSAxNy4yMjIgYwo0Ljk5OSAxOC4xNzkgbAo0Ljk5OSAxOC42MzIgNS4zNjcgMTkgNS44MTkgMTkgYwoxOC4xMyAxOSBsCjE4LjU4MiAxOSAxOC45NSAxOC42MzIgMTguOTUgMTguMTggYwoxOC45NSAxNy4yMjIgbAoxOC45NDk0NDkgMTYuNzY5MzU1IDE4LjU4MjY0NSAxNi40MDI1NTEgMTguMTMgMTYuNDAyIGMKMTcuNjM3IDE2LjQwMiBsCjE3LjYzNyAxMC4yMiBsCjE4LjEzIDEwLjIyIGwKaAoxOC4xMjkgMTcuMjIyIG0KMTguMTI5IDE4LjIwMiAxOC4xMzEgMTguMTc5IDE4LjEyOSAxOC4xNzkgYwo1LjgyIDE4LjE3OSBsCjUuODIgMTcuMjIyIGwKMTguMTI4IDE3LjIyMiBsCmgKNy4xMzMgMTYuNDAyIG0KNy4xMzMgMTAuMjIgbAo4LjA2MyAxMC4yMiBsCjguMDYzIDE2LjQwMiBsCjcuMTMzIDE2LjQwMiBsCmgKOC44ODQgMTYuNDAyIG0KOC44ODQgMTAuMjIgbAoxMC42ODkgMTAuMjIgbAoxMC42ODkgMTYuNDAyIGwKOC44ODQgMTYuNDAyIGwKaAoxMS41MSAxNi40MDIgbQoxMS41MSAxMC4yMiBsCjEyLjQ0IDEwLjIyIGwKMTIuNDQgMTYuNDAyIGwKMTEuNTEgMTYuNDAyIGwKaAoxMy4yNiAxNi40MDIgbQoxMy4yNiAxMC4yMiBsCjE1LjA2NSAxMC4yMiBsCjE1LjA2NSAxNi40MDIgbAoxMy4yNiAxNi40MDIgbApoCjE1Ljg4NiAxNi40MDIgbQoxNS44ODYgMTAuMjIgbAoxNi44MTYgMTAuMjIgbAoxNi44MTYgMTYuNDAyIGwKMTUuODg2IDE2LjQwMiBsCmgKNS44MiA5LjQgbQo1LjgyIDguMjU1IDUuODE4IDguMzM4IDUuODIyIDguMzM2IGMKMTEuOTc0IDUuODIxIGwKMTguMTI0IDguMzM2IGwKMTguMTI5IDguMzM4IDE4LjEyOCA4LjI1OCAxOC4xMjggOS40IGMKNS44MiA5LjQgbApoCjAuMDk4MDM5IDAuMTQxMTc2IDAuNDk0MTE4IHJnCi9hMS4wIGdzCjEgdwowIEoKMCBqCjQgTQpmClEKMSB3CjAgSgowIGoKNCBNCm4KUQpRClEKUQpRCnEKcQpxCnEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTAuNyBncwpCVAoxIDAgMCAtMSA3NS41OTA1NTEgNTg2LjYyMzA0NyBUbQovVkNBVFdTIDEyIFRmClsgPDAwMzEwMDUyMDA1MDAwNDgwMDAzMDA0NzAwNTIwMDAzMDAzMz4gMjYgPDAwNDQwMDRhMDA0NDAwNDcwMDUyMDA1NT4gXSBUSgpFVApRClEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTEuMCBncwpCVAoxIDAgMCAtMSAzOTYuODUwMzk0IDU4OC4xMjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDM0MDAyYzAwMDMwMDM2MDAyNjAwMjcwMDAzMDAzNjAwMTEwMDI0PiAtMTggPDAwMTE+IF0gVEoKRVQKUQpRClEKUQpxCnEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTAuNyBncwpCVAoxIDAgMCAtMSA3NS41OTA1NTEgNjI1LjYyMzA0NyBUbQovVkNBVFdTIDEyIFRmClsgPDAwMjYwMDMzMDAyOTAwMTIwMDI2MDAzMTAwMzMwMDJkPiBdIFRKCkVUClEKUQpxCnEKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCi9hMS4wIGdzCkJUCjEgMCAwIC0xIDM5Ni44NTAzOTQgNjI3LjEyMzA0NyBUbQovVkNBVFdTIDEyIFRmClsgPDAwMTYwMDE1MDAxMTAwMTcwMDEzMDAxNTAwMTEwMDE4MDAxMzAwMTUwMDEyMDAxMzAwMTMwMDEzMDAxNDAwMTAwMDE2MDAxOD4gXSBUSgpFVApRClEKUQpRCnEKcQpxCnEKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCi9hMC43IGdzCkJUCjEgMCAwIC0xIDc1LjU5MDU1MSA2NjQuNjIzMDQ3IFRtCi9WQ0FUV1MgMTIgVGYKWyA8MDAyNDAwNGEwMGFjMDA1MTAwNDYwMDRjMDA0ND4gXSBUSgpFVApRClEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTEuMCBncwpCVAoxIDAgMCAtMSAzOTYuODUwMzk0IDY2Ni4xMjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDEzMDAxMzAwMTMwMDE0PiBdIFRKCkVUClEKUQpRClEKcQpxCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2EwLjcgZ3MKQlQKMSAwIDAgLTEgNzUuNTkwNTUxIDcwMy42MjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDI2MDA1MjAwNTEwMDU3MDA0ND4gXSBUSgpFVApRClEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTEuMCBncwpCVAoxIDAgMCAtMSAzOTYuODUwMzk0IDcwNS4xMjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDEzMDAxMzAwMTMwMDEzMDAxYTAwMTAwMDE3PiBdIFRKCkVUClEKUQpRClEKcQpxCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2EwLjcgZ3MKQlQKMSAwIDAgLTEgNzUuNTkwNTUxIDc0Mi42MjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDJjMDA1MTAwNTYwMDU3MDA0YzAwNTcwMDU4MDA0YzAwYTkwMGE1MDA1MjAwMDMwMDI5MDA0YzAwNTEwMDQ0MDA1MTAwNDYwMDQ4MDA0YzAwNTUwMDQ0PiBdIFRKCkVUClEKUQpxCnEKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCi9hMS4wIGdzCkJUCjEgMCAwIC0xIDM5Ni44NTAzOTQgNzQ0LjEyMzA0NyBUbQovVkNBVFdTIDEyIFRmClsgPDAwMzQwMDJjMDAwMzAwMzYwMDMyMDAyNjAwMmMwMDI4MDAyNzAwMjQwMDI3MDAyODAwMDMwMDI3MDAyODAwMDMwMDI2MDAzNTAwOGIwMDI3MDAyYzAwMzcwMDMyMDAwMzAwMjcwMDJjMDAzNTAwMjgwMDM3MDAzMjAwMDMwMDM2MDAxMTAwMjQ+IC0xOCA8MDAxMT4gXSBUSgpFVApRClEKUQpRCnEKcQpxCnEKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCi9hMC43IGdzCkJUCjEgMCAwIC0xIDc1LjU5MDU1MSA3ODEuNjIzMDQ3IFRtCi9WQ0FUV1MgMTIgVGYKWyA8MDAzOT4gNTQgPDAwNDQwMDRmMDA1MjAwNTU+IF0gVEoKRVQKUQpRCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2ExLjAgZ3MKQlQKMSAwIDAgLTEgMzk2Ljg1MDM5NCA3ODMuMTIzMDQ3IFRtCi9WQ0FUV1MgMTIgVGYKWyA8MDAzNTAwMDcwMDAzMDAxNTAwMWEwMDE3MDAxMTAwMWIwMDEzMDAxMzAwMGYwMDEzMDAxMz4gXSBUSgpFVApRClEKUQpRCnEKcQpxCnEKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCi9hMC43IGdzCkJUCjEgMCAwIC0xIDc1LjU5MDU1MSA4ODQuNjIzMDQ3IFRtCi9WQ0FUV1MgMTIgVGYKWyA8MDAzMTAwNTIwMDUwMDA0ODAwMDMwMDQ3MDA1MjAwMDMwMDI1MDA0ODAwNTEwMDQ4MTNhZTAwNDYwMDRjMDBhMzAwNTUwMDRjMDA1Mj4gXSBUSgpFVApRClEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTEuMCBncwpCVAoxIDAgMCAtMSAzOTYuODUwMzk0IDg4Ni4xMjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDI1MDA0ODAwNDQwMDU3MDA1NTAwNGMwMDVkMDAwMzAwMjYwMDUyMDA1ODAwNTcwMDUyMDAwMzAwNDcwMDQ4MDAwMzAwMjYwMDQ0MDA1NTAwNTkwMDQ0MDA0ZjAwNGIwMDUyPiBdIFRKCkVUClEKUQpRClEKcQpxCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2EwLjcgZ3MKQlQKMSAwIDAgLTEgNzUuNTkwNTUxIDkyMy42MjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDI2MDAzMzAwMjkwMDEyMDAyNjAwMzEwMDMzMDAyZD4gXSBUSgpFVApRClEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTEuMCBncwpCVAoxIDAgMCAtMSAzOTYuODUwMzk0IDkyNS4xMjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDEzMDAxNjAwMWEwMDExMDAxYjAwMTUwMDE5MDAxMTAwMTQwMDFhMDAxMzAwMTAwMDE2MDAxYT4gXSBUSgpFVApRClEKUQpRCnEKcQpxCnEKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCi9hMC43IGdzCkJUCjEgMCAwIC0xIDc1LjU5MDU1MSA5NjIuNjIzMDQ3IFRtCi9WQ0FUV1MgMTIgVGYKWyA8MDAzMTAwNTIwMDUwMDA0ODAwMDMwMDQ3MDA1MjAwMDMwMDM2MDA0NDAwNDYwMDQ0MDA0NzAwNTIwMDU1MDAwMzAwMjQ+IDM1IDwwMDU5MDA0NDAwNGYwMDRjMDA1NjAwNTcwMDQ0PiBdIFRKCkVUClEKUQpxCnEKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCi9hMS4wIGdzCkJUCjEgMCAwIC0xIDM5Ni44NTAzOTQgOTY0LjEyMzA0NyBUbQovVkNBVFdTIDEyIFRmClsgPDAwMTA+IF0gVEoKRVQKUQpRClEKUQpxCnEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTAuNyBncwpCVAoxIDAgMCAtMSA3NS41OTA1NTEgMTAwMS42MjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDI2MDAzMTAwMzMwMDJkPiBdIFRKCkVUClEKUQpxCnEKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCi9hMS4wIGdzCkJUCjEgMCAwIC0xIDM5Ni44NTAzOTQgMTAwMy4xMjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDEwPiBdIFRKCkVUClEKUQpRClEKcQpxCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2EwLjcgZ3MKQlQKMSAwIDAgLTEgNzUuNTkwNTUxIDEwNDAuNjIzMDQ3IFRtCi9WQ0FUV1MgMTIgVGYKWyA8MDAyNzAwNDQwMDU3MDA0NDAwMDMwMDQ3MDA0ODAwMDMwMDM5PiA1NCA8MDA0ODAwNTEwMDQ2MDA0YzAwNTAwMDQ4MDA1MTAwNTcwMDUyPiBdIFRKCkVUClEKUQpxCnEKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCi9hMS4wIGdzCkJUCjEgMCAwIC0xIDM5Ni44NTAzOTQgMTA0Mi4xMjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDEzMDAxYzAwMTIwMDEzMDAxYjAwMTIwMDE1MDAxMzAwMTUwMDE3PiBdIFRKCkVUClEKUQpRClEKcQpxCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2EwLjcgZ3MKQlQKMSAwIDAgLTEgNzUuNTkwNTUxIDEwNzkuNjIzMDQ3IFRtCi9WQ0FUV1MgMTIgVGYKWyA8MDAyNzAwNDQwMDU3MDA0NDAwMDMwMDQ3MDA1MjAwMDMwMDMzPiAyNiA8MDA0NDAwNGEwMDQ0MDA1MDAwNDgwMDUxMDA1NzAwNTI+IF0gVEoKRVQKUQpRCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2ExLjAgZ3MKQlQKMSAwIDAgLTEgMzk2Ljg1MDM5NCAxMDgxLjEyMzA0NyBUbQovVkNBVFdTIDEyIFRmClsgPDAwMTMwMDE5MDAxMjAwMTMwMDFiMDAxMjAwMTUwMDEzMDAxNTAwMTc+IF0gVEoKRVQKUQpRClEKUQpRClEKcQpxCjAgMTAyNS41MTk2ODUgNzkzLjcwMDc4NyA5NyByZQpXCm4KcQowLjk0OTAyIDAuOTU2ODYzIDAuOTg4MjM1IHJnCi9hMS4wIGdzCjAgMTAyNS41MTk2ODUgNzkzLjcwMDc4NyA5NyByZQpXCm4KMCAxMDI1LjUxOTY4NSA3OTMuNzAwNzg3IDk3IHJlCmYKUQpRCnEKNzkzLjcwMDc4NyAxMDI1LjUxOTY4NSBtCjAgMTAyNS41MTk2ODUgbAowIDEwMjYuNTE5Njg1IGwKNzkzLjcwMDc4NyAxMDI2LjUxOTY4NSBsClcqCm4KMCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjUuOTkwMTk1IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMTEuOTgwMzg5IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMTcuOTcwNTg0IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMjMuOTYwNzc4IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMjkuOTUwOTczIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMzUuOTQxMTY4IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNDEuOTMxMzYyIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNDcuOTIxNTU3IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNTMuOTExNzUyIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNTkuOTAxOTQ2IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNjUuODkyMTQxIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNzEuODgyMzM1IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNzcuODcyNTMgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo4My44NjI3MjUgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo4OS44NTI5MTkgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo5NS44NDMxMTQgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoxMDEuODMzMzA5IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMTA3LjgyMzUwMyAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjExMy44MTM2OTggMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoxMTkuODAzODkyIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMTI1Ljc5NDA4NyAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjEzMS43ODQyODIgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoxMzcuNzc0NDc2IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMTQzLjc2NDY3MSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjE0OS43NTQ4NjYgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoxNTUuNzQ1MDYgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoxNjEuNzM1MjU1IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMTY3LjcyNTQ0OSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjE3My43MTU2NDQgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoxNzkuNzA1ODM5IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMTg1LjY5NjAzMyAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjE5MS42ODYyMjggMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoxOTcuNjc2NDIzIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMjAzLjY2NjYxNyAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjIwOS42NTY4MTIgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoyMTUuNjQ3MDA2IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMjIxLjYzNzIwMSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjIyNy42MjczOTYgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoyMzMuNjE3NTkgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoyMzkuNjA3Nzg1IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMjQ1LjU5Nzk3OSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjI1MS41ODgxNzQgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoyNTcuNTc4MzY5IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMjYzLjU2ODU2MyAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjI2OS41NTg3NTggMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoyNzUuNTQ4OTUzIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMjgxLjUzOTE0NyAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjI4Ny41MjkzNDIgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoyOTMuNTE5NTM2IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMjk5LjUwOTczMSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjMwNS40OTk5MjYgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQozMTEuNDkwMTIgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQozMTcuNDgwMzE1IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMzIzLjQ3MDUxIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMzI5LjQ2MDcwNCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjMzNS40NTA4OTkgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQozNDEuNDQxMDkzIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMzQ3LjQzMTI4OCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjM1My40MjE0ODMgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQozNTkuNDExNjc3IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMzY1LjQwMTg3MiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjM3MS4zOTIwNjcgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQozNzcuMzgyMjYxIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMzgzLjM3MjQ1NiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjM4OS4zNjI2NSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjM5NS4zNTI4NDUgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo0MDEuMzQzMDQgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo0MDcuMzMzMjM0IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNDEzLjMyMzQyOSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjQxOS4zMTM2MjQgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo0MjUuMzAzODE4IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNDMxLjI5NDAxMyAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjQzNy4yODQyMDcgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo0NDMuMjc0NDAyIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNDQ5LjI2NDU5NyAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjQ1NS4yNTQ3OTEgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo0NjEuMjQ0OTg2IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNDY3LjIzNTE4MSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjQ3My4yMjUzNzUgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo0NzkuMjE1NTcgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo0ODUuMjA1NzY0IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNDkxLjE5NTk1OSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjQ5Ny4xODYxNTQgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo1MDMuMTc2MzQ4IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNTA5LjE2NjU0MyAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjUxNS4xNTY3MzcgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo1MjEuMTQ2OTMyIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNTI3LjEzNzEyNyAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjUzMy4xMjczMjEgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo1MzkuMTE3NTE2IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNTQ1LjEwNzcxMSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjU1MS4wOTc5MDUgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo1NTcuMDg4MSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjU2My4wNzgyOTQgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo1NjkuMDY4NDg5IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNTc1LjA1ODY4NCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjU4MS4wNDg4NzggMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo1ODcuMDM5MDczIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNTkzLjAyOTI2OCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjU5OS4wMTk0NjIgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo2MDUuMDA5NjU3IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNjEwLjk5OTg1MSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjYxNi45OTAwNDYgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo2MjIuOTgwMjQxIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNjI4Ljk3MDQzNSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjYzNC45NjA2MyAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjY0MC45NTA4MjUgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo2NDYuOTQxMDE5IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNjUyLjkzMTIxNCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjY1OC45MjE0MDggMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo2NjQuOTExNjAzIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNjcwLjkwMTc5OCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjY3Ni44OTE5OTIgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo2ODIuODgyMTg3IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNjg4Ljg3MjM4MiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjY5NC44NjI1NzYgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo3MDAuODUyNzcxIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNzA2Ljg0Mjk2NSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjcxMi44MzMxNiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjcxOC44MjMzNTUgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo3MjQuODEzNTQ5IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNzMwLjgwMzc0NCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjczNi43OTM5MzggMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo3NDIuNzg0MTMzIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNzQ4Ljc3NDMyOCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjc1NC43NjQ1MjIgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo3NjAuNzU0NzE3IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNzY2Ljc0NDkxMiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjc3Mi43MzUxMDYgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo3NzguNzI1MzAxIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNzg0LjcxNTQ5NSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjc5MC43MDU2OSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlClcqCm4KMC4wOTgwMzkgMC4xNDExNzYgMC40OTQxMTggcmcKL2ExLjAgZ3MKMCAxMDI2LjUxOTY4NSA3OTMuNzAwNzg3IDk2IHJlCjAgMTAyNS41MTk2ODUgNzkzLjcwMDc4NyA5NyByZQpmKgpRClEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTAuNyBncwpCVAoxIDAgMCAtMSAzMjUuNzUyNzM3IDEwNTcuNjczOTgyIFRtCi9PQ0hOVVAgMTIgVGYKWyA8MDAyNjAwYjUwMDQ3MDA0YzAwNGEwMDUyMDAwMzAwNDcwMDQ4MDAwMzAwNDQwMDU4MDA1NzAwNDgwMDUxMDA1NzAwNGMwMDQ2MDA0NDAwYTkwMGE1MDA1MjAwMDM+IF0gVEoKRVQKL2ExLjAgZ3MKQlQKMSAwIDAgLTEgMjY3LjI2NDQ1NiAxMDcxLjY3Mzk4MiBUbQovT0NITlVQIDEyIFRmClsgPDAwMWMwMDE3MDAxMzAwNDYwMDE3MDAxYjAwMWEwMDQ2MDAxMDAwNDcwMDFjMDAxNzAwMTcwMDEwMDAxNzAwMWEwMDE2MDA0NzAwMTAwMDQ1MDA0NTAwNDcwMDE2MDAxMDAwMTMwMDFiMDAxYTAwMTQwMDQ3MDAxYzAwMTUwMDQ0MDAxODAwMTUwMDE1MDAxOD4gXSBUSgpFVAovYTAuNyBncwpCVAoxIDAgMCAtMSAyOTAuNjI4NzE0IDEwOTUuNjczOTgyIFRtCi9PQ0hOVVAgMTIgVGYKWyA8MDAzNDAwNGMwMDAzMDAzNjAwNTIwMDQ2MDA0YzAwNDgwMDQ3MDA0NDAwNDcwMDQ4MDAwMzAwNDcwMDQ4MDAwMzAwMjYwMDU1PiAyMSA8MDA0ODAwNDcwMDRjMDA1NzAwNTIwMDAzMDAyNzAwNGMwMDU1PiAyMSA8MDA0ODAwNTcwMDUyMDAwMzAwMzYwMDExMDAyND4gMTcgPDAwMTE+IF0gVEoKMSAwIDAgLTEgMzE5LjQzMzQwMiAxMTA5LjY3Mzk4MiBUbQpbIDwwMDI2MDAzMTAwMzMwMDJkMDAwMzAwMTYwMDE1MDAxMTAwMTcwMDEzMDAxNTAwMTEwMDE4MDAxMzAwMTUwMDEyMDAxMzAwMTMwMDEzMDAxNDAwMTAwMDE4MDAxYz4gXSBUSgpFVApRClEKcQpxCnEKcQo3NS41OTA1NTEgNTIyLjQ2ODc1IDcwIDkgcmUKVwpuCnEKMSAwLjkwNTg4MiAwLjkzNzI1NSByZwovYTEuMCBncwo3NS41OTA1NTEgNTIyLjQ2ODc1IDcwIDkgcmUKVwpuCjc1LjU5MDU1MSA1MjIuNDY4NzUgNzAgOSByZQpmClEKUQpRCjAuMDk4MDM5IDAuMTQxMTc2IDAuNDk0MTE4IHJnCi9hMS4wIGdzCkJUCjEgMCAwIC0xIDc1LjU5MDU1MSA1MjcuMDA3ODEyIFRtCi9WQ0FUV1MgMTYgVGYKWyA8MDAzMz4gMjYgPDAwNDQwMDRhMDA0NDAwNDcwMDUyPiBdIFRKCjEgMCAwIC0xIDc1LjU5MDU1MSA1NDkuMDA3ODEyIFRtClsgPDAwNTU+IF0gVEoKRVQKUQpRCnEKcQpxCnEKNzUuNTkwNTUxIDgyMC40Njg3NSAxMDAgOSByZQpXCm4KcQoxIDAuOTA1ODgyIDAuOTM3MjU1IHJnCi9hMS4wIGdzCjc1LjU5MDU1MSA4MjAuNDY4NzUgMTAwIDkgcmUKVwpuCjc1LjU5MDU1MSA4MjAuNDY4NzUgMTAwIDkgcmUKZgpRClEKUQowLjA5ODAzOSAwLjE0MTE3NiAwLjQ5NDExOCByZwovYTEuMCBncwpCVAoxIDAgMCAtMSA3NS41OTA1NTEgODI1LjAwNzgxMiBUbQovVkNBVFdTIDE2IFRmClsgPDAwMjUwMDQ4MDA1MTAwNDgxM2FlMDA0NjAwNGMwMGEzMDA1NTAwNGM+IF0gVEoKMSAwIDAgLTEgNzUuNTkwNTUxIDg0Ny4wMDc4MTIgVG0KWyA8MDA1Mj4gXSBUSgpFVApRClEKUQpRClEKUQpRClEKcQowIDAgNTk1LjMwMzkzNzAwNzg3NCA4NDEuODg5NzYzNzc5NTI4IHJlClcKbgowLjEgdwpxCjEwIC0wLjExIDU3NS4zIDgxNCByZQpXKgpuCnEKL0VHUzYgZ3MKL1RyNSBEbwpRClEKUQoKZW5kc3RyZWFtCmVuZG9iago2IDAgb2JqCjw8Ci9DQSAwLjMKL2NhIDAuMwo+PgplbmRvYmoKNyAwIG9iago8PAovVHlwZSAvRm9udAovU3VidHlwZSAvVHlwZTAKL0Jhc2VGb250IC9WQ0FUV1MrRGVqYVZ1LVNhbnMtQm9sZAovVG9Vbmljb2RlIDggMCBSCi9FbmNvZGluZyAvSWRlbnRpdHktSAovRGVzY2VuZGFudEZvbnRzIFsgOSAwIFIgXQo+PgplbmRvYmoKOCAwIG9iago8PAovRmlsdGVyIC9GbGF0ZURlY29kZQovTGVuZ3RoIDQ3Ngo+PgpzdHJlYW0KeNpdlMuK20AQRff6il5OFoPUL8kDxhAmGy/yIE4+oN0qeQSxJGR54b+P1KdxIAIbLvfW41apVL4fvxyHflHlj3mMJ1lU1w/tLLfxPkdRZ7n0Q6GNavu4ZJT+4zVMRbkGnx63Ra7HoRuL/V6VP1fytswP9fK5Hc/yqSi/z63M/XBRL7/fTys+3afpj1xlWFRVHA6qlW5N9DVM38JVVJnCXo/tyvfL43WN+af49ZhEmYQ1zcSxldsUosxhuEixr9bnoPbd+hwKGdr/eF8Tdu7iR5g3ualXeVU5e9iQNwnVHagCtSCbUFOBPMiA3kB1Qs4Rp+E0SEANSodyB+cTqqhgqOBQ1lkZQE1Cluqe6hVKg1LDWThNnCVOo7RZSWeGzvQZbgeiF0svVYcywjEzy8x0BL2BmIRlEhp/Fn+aeRrmaZmSZ0qGLI4slgqeCpatOLZiyOnIaXDkcGTI6ci5w1HMOVF6lBbvDu8Wtx63Bg8ue6C6ydVbuABHPUu9gAeBc3io8eDganrxcE1+63DU4ChQXdhYYJuSJwHn83vGVmq2YlC6be/aBoGrnzUDHiW/lfhocq9Mqt6lo8nXsZ3PduXP24z3eV7PMn0K0j1ul9gP8vxaTOO0RW2/vxSkCw0KZW5kc3RyZWFtCmVuZG9iago5IDAgb2JqCjw8Ci9UeXBlIC9Gb250Ci9TdWJ0eXBlIC9DSURGb250VHlwZTIKL0Jhc2VGb250IC9WQ0FUV1MrRGVqYVZ1LVNhbnMtQm9sZAovQ0lEU3lzdGVtSW5mbyA8PAovUmVnaXN0cnkgKEFkb2JlKQovT3JkZXJpbmcgKElkZW50aXR5KQovU3VwcGxlbWVudCAwCj4+Ci9DSURUb0dJRE1hcCAvSWRlbnRpdHkKL1cgWyAzIFsgMzQ4IF0gNyBbIDY5NiBdIDE1IFsgMzgwIDQxNSAzODAgMzY1IDY5NiA2OTYgNjk2IDY5NiA2OTYgNjk2IDY5NiA2OTYgNjk2IDY5NiBdIDM2IFsgNzc0IDc2MiA3MzQgODMwIDY4MyA2ODMgXSA0NCBbIDM3MiAzNzIgXSA0OSBbIDgzNyA4NTAgNzMzIDg1MCA3NzAgNzIwIDY4MiBdIDU3IFsgNzc0IF0gNjggWyA2NzUgXSA3MCBbIDU5MyA3MTYgNjc4IF0gNzQgWyA3MTYgNzEyIDM0MyBdIDc5IFsgMzQzIDEwNDIgNzEyIDY4NyA3MTYgXSA4NSBbIDQ5MyA1OTUgNDc4IDcxMiA2NTIgXSA5MyBbIDU4MiBdIDEzOSBbIDY4MyBdIDE2MyBbIDY3NSBdIDE2NSBbIDY3NSBdIDE2OSBbIDU5MyBdIDE3MiBbIDY3OCBdIDUwMzggWyA3NDEgXSBdCi9Gb250RGVzY3JpcHRvciAxMCAwIFIKPj4KZW5kb2JqCjEwIDAgb2JqCjw8Ci9UeXBlIC9Gb250RGVzY3JpcHRvcgovRm9udE5hbWUgL1ZDQVRXUytEZWphVnUtU2Fucy1Cb2xkCi9Gb250RmFtaWx5IChEZWphVnVcMDQwU2FucykKL0ZsYWdzIDQKL0ZvbnRCQm94IFsgMCAtMjM1IDEwNDIgOTI4IF0KL0l0YWxpY0FuZ2xlIDAKL0FzY2VudCA5MjgKL0Rlc2NlbnQgLTIzNQovQ2FwSGVpZ2h0IDkyOAovU3RlbVYgODAKL1N0ZW1IIDgwCi9Gb250RmlsZTIgMTEgMCBSCj4+CmVuZG9iagoxMSAwIG9iago8PAovTGVuZ3RoMSAzOTQxNgovRmlsdGVyIC9GbGF0ZURlY29kZQovTGVuZ3RoIDQ0NjAKPj4Kc3RyZWFtCnja7Vx7VFXV1p9zvyB8cXgjphwODxEVBBHtqYikpmSm5gOVhxwEOYACKiqS2hBfpQ7zgZUhkU8yJO7Nz8hrZN3MvOY16qqp1xhezdDMYabAWXxz7XMOobf7cHyjP/rG+v3ae6+911xrzTXnXHOv3ZADCACd4AWQYUx8/LjR61IqtwGUTqSn3Z6KGxbvu9t3H93n0/3SZ54Lj5wVXJkHgLx+QqolOdcvQh4A8HwE3R9JT87LBScilI6i+47pWYVmnxk+JL/cB8DgNjMteUbAoCE/Ud03dAyYSQ86rusaSP150H3gTEv+/IHz/brRfRXA+BeyclKTzy7+ugv1fwugb4AleX6uty8UUv1AkvfPTrak9e44ZA7A5t70jOXm5OW3noXJNH5vXg98btK0A+4r1neb3uWxn6CHM3CcubathF+/vdXkbLWweKcap1kk6wwS2EDtnCzsYQDnCVYLlWv0ntrBvYo/8XaFSLLbMDrurZfoHpWNUi2oAGqUWkpddrdd5a/BLLmRSAdnWdYUSVJIXh7crvEY87AZpLt/M2oezAO3OlmwwaYTh3IczG3DHL1XK3U9lMG/gewCFnks5ND1pNSoy6fQcZmOcjpW0pFIxzY6iu33RXRk/rs+tX7govlCrXoBzFoFXefZjjYdm6BWamp96Z421VCr0TzUc7arFkptPoINagG4OPqE/xKqGSbqdjkEE9WDpL/Fdq+Xq6FSOgSVbbpQ2XkC7OHP1WJdXq+Tb0Kl8hFkyqfAj+rK1Bjo0X4MZRckwm8MBdBy3732f+2zvR9+Czhs77i26X7ol3uHPwQEBAQEBAR+y30ElPxG/VYI6woICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICPw+oV6HMGEFAQEBAYHfJ/ivweq/EivT4WH/3VcPUKCKrj3Bn0rOdA6EQRAPI2EcTIBkSIMMyIW5sACOwkVogMtwtRlbWwF0yd4wBEZAgi6ZCumQBXPul2xt+Jesc9Dn7ft/o/YB8Ox9TCF9F8MaqIV6RHwCp+LLeBwvSmFSxn0skQ5JjbKvHCWP1DlRnm3nKvmgfEHxUOKV5cpW4ju/yqvKVdVbHa4uJNaql9QmTs1Zi9UytS3aUeJ3TiFOI53ynVbauf2BWWXnyf/Icw/I74g/2eiMOjsJCgr+7tjjAZggKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCj4/5oLBAUFBQUFf5dcqf8L9zJ2StU0DzBBL+gHgCY5ODjE4OXlbQgJDo7uPyAmJsqT7jz5U28vL08PzUk2aJqnh5e7YcCA6P7Bsl85Fl3Nyfu+0PjD0Z8asHzGp2n0nz87fuvn8qfGJ9x4/vkx7BT2UfuGovbokwrGaL1qdr979KHLDc4BfqxXuMouaj3ff+/Ax53lWFSVYdGPDmX72VWMjY0bSgqBhZ2TBuEyUAHcjQbZ5H4SZ/5cPwOXsRNsNRaQRA7WSg3SBf7v9UnCmCPlW9dIF9g53vokgN7aXkdt2RZqWsTroDVWalTreR1GoUnqfN764zm1/q4FJEhpbVDD1RvQAbyp1jXYFKAZXL2iIgegKxj9waCf5X0ZixZlZi5amIlL2GF2hp1mh3EwhmAwDpYa0efSJXaFXbpyBX3YS8yCGzAP83EDs9DYlwFUhcZ20fVSDUGknMF4A8exN3EKZuO45kZ0kT8ejtrw5mh2m1qUAygXSCMf0ocLo25+0suJHBHlr3DXSAnS+uaPJOOI+JcKJn+1YClbgB0xdPFn6McuoR9ejF0cl/HC6FE4PKxP46kFp/ZzK6xsbVCuU7896YY7WDEG6BFAc+X9m6LthfYDyQc3v84q2cG8y7Oz6tNL39z55tby9S+vWjz10LQ5f89CExpXyUEhH248fzkoCEMHxGSmmjPuTJk6YVqvUOzq7/+nw8t2ko0TyQZRZAMJOtHYaJSNhiiDidvBIN1kk3HHYKysr2evWDOVLda18r6Wsew7dgNdcSTXext5SKLWD9s868l1A08PuFd90vq0/IF1bu9JEWjACPYHdqb47sIFZ5PXbN++5rnaLLWeXbrcsRP74dZNdr1fJIbHx68smLsirA9pVUwjmNTrFAOBNGAAD3pbr2gI1numISP1IW0BEeklXUojmNPScO70XWMqD7vGbp1yCX3ZJ+wOO8c+xAIcll4nXVxmh3ScNfYJ+1Ntv37s1ukb7AKuxAycgzv9db+Qv6/T/DQ+P080onGlkmY9yFZKIdZ+av3pZkU5yFdwEWnppkeqCcLv1TOIL+FAoy02bL71D6RF7e7xi3mko1n5+Vmz5sxhi1aswq5kpC7YdfWKLa9SMJ8npb9+9WZq4uSUlMmJqdJrc7OzCwqycwqKQ/cUf/DJx4eK94T2+mDd+YaG8+s+wPGTkpImTZqeRJbLJJ06k+V8uOVibN6I0TRTAET3d1grIBgdOpDCxxN3ja08bIjbOvkSu4yD0AkDcTBbxQ5mHMbiNDOZ1Gw2okcYWSsyEjuc+RED2Fy2hb3MJvWQri9btvTFF5cuW8b/bodWlBZCdnPiJR5UqFNW4q07prMiKRSPSaGsyLoLSz9HV3ZDrW8Kk4KksdyWtRSRK6mtMxiAO8G+BAzujoJ9hVC82daB25Rp06bUf5tfkF/wrTR80Qr2DfvKukSKxRj0NssbxiSMfpYdsealpCYns0LJN7Dupb99qdbXnrCUkofNZKVE8pwvQBAZxxFE3np0SZ4ebtxqamLmP4rYajYKa7Cg6B+Zs77I+0tj41/yvpg1NmYgbsc0NOP2gTHs2Ig4dufKZXYnbgS3As1EG6TPhOcvg93dSGp7e7l5ekhOGs1CenxV490716w/4SYch6PnZZjNGfNZFTFTqW6ZffXC+StoSs5PY3d27mY/p+Un87iknpWL1HMH27pzsFbpYp0jpVtLpYrms7SqzrGrdOyxZWHe5hi1eah9m7YWrNghby2xS0uP2/Iyl66l5FrMvUR1rS8xs15nG53sZdLnxmVOsuMJj81fSJK1lCca0bR8qb039bZjbOQDI+9zn9QDLWys9SLboNa3gAJNYQq06H/5RX7RzG253+4Jt+j+kuxI/HSWzVV1dVX76+r240zcwui1wkpZOpYqp1lL4/esBZXvG1FBbzaDbWSb2Ax8DTNxFr5m840eZS7gznXikaTQPIxtbqqVivFh7EcvuAbGinFJfe6CBblqvfXq91Zrk3KITbfMmJGla8rqdU27gB/1aWpTj/xLMc8197JrvrY7W8vMWIrppMTGrz/DPmw9a6iqO1RDU/DDLZjFlaNprG9hrySyKk2hadxotc3CHk+gx1O3X9aFr+RYCJRdvN2NtHcwSRcKMzIKy1mxNIpehO5r1z1TNPgkM/8xZvY0+cnJ6eaJbAm7baVg+OSrVw71cStewiZiXu5Y7qkNtB760GxCeMQG2xODt7f9pRRIWV2xGSgkxJbYIhXl2MKrM1e9OKmg4u5f2Vl26mX27dq12GHR4uVTVmz8+wn0x84LUVF3sCMxA0eNeWyojzHy89qffxwQjcNGjR6XED+quzHir9UXbgTx8SlfqJl65miLUhc1iRlYMXPlEdqcoFTb5fQMo2dm5MnFBZfhGlyNy6xfs2i1vrlaSaBwlWAivVs/VhZSi6D2mTk6yGCM5ulQn0XUPW9XqTx39pRn01ZhBts8vGbJvtOUjwNOLX8575PxeVfyMRw74Z1RI+NGr7eElliX7DBPPVb+8YFu45/p2xcN3R7+gevHR42mUX3b25HnEkO7LKNEj9jwzKadOzeN2zx43NvP0+rZgxMwfOJe5XH2TWTEO6+//k5kP3a2Rw9KZZ7EmB78jc3zOu0WXfUo4AbSp8G7jIr0ktvlc3kH32mNrC44wW6jy4n8d8vzCgvz5hQWyrXSxLuN5amJOAJl4oipLUd3lZXt4ofNYqoL6e7BIxo9jV73Ke4Pqs1aqkvL+51eWzP7WlEx+ecL9g4+jQHojI+zdfOSZi51laLMixcPjWONEf0wGr3RDR9hdRvMRQXZfB4sXu2sFNIsetpyr/5ioil4Rxtt7ybHFkJu9zqVd9B8jrNb2PF4QfVImt9eVptxJHVazZSqisacRfPzchctOpSSiEObmnFIYuqOFgO7yRr8jeg9IHprhaxVbNr6RsXGTRXcR5UUa25kST07G6MNFNQ2T+lxxzcWXqob29LJ1XN439wX2FY0P/vH7Lqj0h7rhBws3ZDd1RTydqn1tOZh3ZUy9TrPBdSjxHuU28dvJZp5W7ZVSWou0zzYN/ax7ZK6nC6jedxt5HV7AJxqyP48XnUtPHV1HCFqNPRv09JTr1cOxr2f++FntKvG+ARzjsS2DB6bnku3M2P3pudXyztmWq43WCdIwzt16zpv1q43rGek4Qdn7X7delpJqpielOuwBY35q7bw/A+2eHW9wxbUHzeFLYZCqD97/m7nwHb5W/pwXlHRvIJFiwpoAQ9j77MLtN35H3xKXrh3+/a9/EBgn7JG4qc4ED2IA7mV2QR1GvWtr4CgNgV5j7Sc3dsNJrlxTUfWFJxAF3b7REFNRd7ChXm0CsqtNZoLqcreY1bie1PlmN1vvLFbXwA2a8iNNIKBbu43g7fcGD41fNVG3vOwd4vcevWUw708979lbVGSDmSnySq1p72XkkLt78uiyj9t7W1ZVPehd95X082pTyc/ie6HaKvalHOtaNbF/IzMEZYnfzh8qyX1DCWFGxERUdFhfTs8ZCrb+26NyYSu/fs/MigivJNz9/K3qiu7c91pzcoV6jb+XtOzg4GMEWWgUaNpXx9lkKJwNlv7ROIBdvzL/dXV6jZW1wosKCGmFfZ/iWcR8AneSxn5T1OSeP5yp5l78NeYt03rtpQTXIYzpc4Gr6coInj8PvsHS90xrJEqc6ewa31L5vmZgitLpdDmsnIeEwg9KMZ8qc9fcnYP2jh5oxems6fYPCWppUnWmstIkr5KlHiSfMi+76YB0Vggn7RWSwktXlKC9ZiS1GTd2gpNkpl/tliU63K5Zta/Io30FVlCH1trj2hmtoLXaixHOka7CrKIUf98JtVDQtpcIE1+JGZhcYS5P0Y+Z3xkSFifJzLDp0/p1GmLa5e+PbuOfay11bbfcprlFsxzlauTdxeFNoL0XH+3aGZ6Hsefw1ygz4G254Mcz6Vtjucsh78V6Hm8Lr8ADjjkVRe9n+G6/Ao4DdwLJTSvQpqXZvs6DnEyYclNhOo//7maT+7iRZKpUP3kRG0QcOeH0KrlweZp0mPK2+6x6Ch9zpIUo2jhvoHBq9OnBo4IfdwrqEtgT14eqo4LkpQeTzzqvOIVv+5hXVwHD6KSD89otOFTY/U85Wv75pU99QEcO0gKKR6/8mn+rhz5ydOPSIxtZrPY5qqqz7/iyQ4Dv4+JS2guk5Na6EBIeO8d6shKHmtNUG87PMaiyGMNR9Tb7I7tL+WdYDL/q3+FIgAj9P9LwssIXnRnK0vgjPH2sgz+mGAvK+3KKvhgtr2sQXdcDkMhB3KhEOZABqTDTMinb4yekAqhdI2ECGIUlVJIwh9iSSYf8uiYA2mQDBboTU9HQDbJ96XSEMgi+sPYtr7y9Ls0uqZRm7l0nkGSLv/FqAPaRh1HI82lsTKpTTZJcz2Sqc2DjRhHpUxqNwEKSCKVZJP13tL0Fsn6jPypl2w655JMCvWbQXL+1D6HRk/W6+7v5zm9lzzSKIfkZ/yLWv+2+gm6VnnUV44+UiTpFgUx97RztOrT1sr2qw+E1r9RFPw6yPsg0cqR9XVCOFOSs1a/XttW0nblNR3bWriTNP8lCSci0n69G50DyQdIfu1D536kGcIgIpKGcXSOp/WIMBJG0fkZ0hRhPEyi81QiwmoiwptEhLeICLuJ/O1RCei+z30f/wWL/wUNxoTECmVuZHN0cmVhbQplbmRvYmoKMTIgMCBvYmoKPDwKL1R5cGUgL0ZvbnQKL1N1YnR5cGUgL1R5cGUwCi9CYXNlRm9udCAvT0NITlVQK0RlamFWdS1TYW5zCi9Ub1VuaWNvZGUgMTMgMCBSCi9FbmNvZGluZyAvSWRlbnRpdHktSAovRGVzY2VuZGFudEZvbnRzIFsgMTQgMCBSIF0KPj4KZW5kb2JqCjEzIDAgb2JqCjw8Ci9GaWx0ZXIgL0ZsYXRlRGVjb2RlCi9MZW5ndGggNDQ3Cj4+CnN0cmVhbQp42l2Ty4rjMBBF9/4KLXsWjS1ZkjsQDEP3Jot5MJn5AD/KaUPHNo6zyN+PrCN6YAJJOFSVbt2SKn89vZ2mcVP5z3XuzrKpYZz6VW7zfe1EtXIZp0wb1Y/dlij+dtdmyfJQfH7cNrmepmHOjkeV/wrB27Y+1NPXfm7lS5b/WHtZx+minv68ngOf78vyIVeZNlVkda16GcJB35rle3MVlcey51Mf4uP2eA41/zJ+PxZRJrKmmW7u5bY0nazNdJHsWIRPrY5D+NSZTP1/cXugrB2692bd03UZ0ouiLOpIB8hDJpIZoJbYC+QgA1WQjVRypuNMYyNZDTVQRWYB9cReIEdMQwKh4JICnVk6K9AzSY9MS6ahT0ufwUqkLlL428kfIjn0PHoWtx63Fg8eDxYPHg8OvQq9hl6ETMc8K+Zp8efxZ+nFp148VFKHP48/i4JHwZFZpUz8VckfMUusJTakTNQr1Bs6Ezw0ZAqZmrmUzEXjtiRTc2OGG9PoldRZTvHpTTCzkklo1Mt0t8QcsZJTXFLnHgz3EIQUI9+fc3q3+8Pe9+9za7r7uoaFiUsaN2XfkXGSzz1e5mWv2r9/AZtk9d4KZW5kc3RyZWFtCmVuZG9iagoxNCAwIG9iago8PAovVHlwZSAvRm9udAovU3VidHlwZSAvQ0lERm9udFR5cGUyCi9CYXNlRm9udCAvT0NITlVQK0RlamFWdS1TYW5zCi9DSURTeXN0ZW1JbmZvIDw8Ci9SZWdpc3RyeSAoQWRvYmUpCi9PcmRlcmluZyAoSWRlbnRpdHkpCi9TdXBwbGVtZW50IDAKPj4KL0NJRFRvR0lETWFwIC9JZGVudGl0eQovVyBbIDMgWyAzMTggXSAxNiBbIDM2MSAzMTggMzM3IDYzNiA2MzYgNjM2IDYzNiA2MzYgNjM2IDYzNiA2MzYgNjM2IDYzNiBdIDM2IFsgNjg0IDY4NiA2OTggNzcwIDYzMiBdIDQyIFsgNzc1IF0gNDUgWyAyOTUgXSA0NyBbIDU1NyA4NjMgNzQ4IDc4NyA2MDMgNzg3IF0gNTQgWyA2MzUgNjExIF0gNjggWyA2MTMgNjM1IDU1MCA2MzUgNjE1IF0gNzQgWyA2MzUgNjM0IDI3OCBdIDc5IFsgMjc4IF0gODEgWyA2MzQgNjEyIF0gODUgWyA0MTEgNTIxIDM5MiA2MzQgNTkyIF0gMTYzIFsgNjEzIF0gMTY1IFsgNjEzIF0gMTY5IFsgNTUwIF0gMTgxIFsgNjEyIF0gXQovRm9udERlc2NyaXB0b3IgMTUgMCBSCj4+CmVuZG9iagoxNSAwIG9iago8PAovVHlwZSAvRm9udERlc2NyaXB0b3IKL0ZvbnROYW1lIC9PQ0hOVVArRGVqYVZ1LVNhbnMKL0ZvbnRGYW1pbHkgKERlamFWdVwwNDBTYW5zKQovRmxhZ3MgNAovRm9udEJCb3ggWyAwIC0yMzUgODYzIDkyOCBdCi9JdGFsaWNBbmdsZSAwCi9Bc2NlbnQgOTI4Ci9EZXNjZW50IC0yMzUKL0NhcEhlaWdodCA5MjgKL1N0ZW1WIDgwCi9TdGVtSCA4MAovRm9udEZpbGUyIDE2IDAgUgo+PgplbmRvYmoKMTYgMCBvYmoKPDwKL0xlbmd0aDEgOTI0NAovRmlsdGVyIC9GbGF0ZURlY29kZQovTGVuZ3RoIDM4MzMKPj4Kc3RyZWFtCnja7ToJVFRHtve+DVyiNLLERIWmWUxwCy2gxi1GDRp0XNAk6CDN0uKCoO0OGRQTwUMMrhgJgkFQBpEzosNHx/A1LoCoMTH8xIVvlK+QiVsS8zVAV/9brxsEk5lJ5vwz559/qEvVq+XW3erWrerHAwSAbrAGRAgfPz5k0qaIomwAjw+ot9drY8eNl4Pl4dQ+TO34Sa+EBHUapX8HQOdJ7f/+3fSBfvOa4hgAxlB7ZmSsIV45r1C7K82BorkGUzzYEYDHe9TuOnfhKuOZ7wLMAI59iemimGhDlMe5V2gI7lAOiKGOZ7zsiD9y+p4xsUtXPrra6zS1jwN0TlwYF2lYenLldSLVACCPjjWsjBcKYCmNBxG++yJDbLTP3RHlVCX58Yv4ONNSy1UIJf4L+ThwXYWwsr72lSFzug//EdzsOW+4cjc7hT9vPmy0t2SwmYqbYqSmPQhgTTTPLpb1BlDqLRmWRsVNpdQmCTm8h8pBZMcxlNuPC9RGqRtuApnk1ss7iWQf61P8EoyCI6F0UUTRXhIEifDFtpOnGMdFwWiS/gfFiTlhpl0s1lll4kk6D8ZWNmnwm5NQB1E076pQQpK5QgrlG5QzKGdRjqKcTTmdcgHlNMpr/x49eRU4yG9DlZwBJuUFenaDKt6v6MHUynO2JUOVfRlUKfWE00zPYDBJl6xPlY4TpEh1lsbfqo9UDwk096hkhMX0XCzdgcU2eotlRzgqDIUTrXLY6rxfumXF40mcSG1fiBN1EEhjxdIxGAH/4iQBmp5q6+D/eOK2b/ts7Tc+se2vonPrt+F3pI7UkTpSR+pIHelfdT+BUvVma72tOtnuvE40wH87eNB9VaJRdxgK4+A1mAhTIQSiYR4shDhYDjegDurhB4tFvZf3h1dUnGCYDgaYSziLYMkTHEvd34BPrPD0bfyfTM9AT/CBN4h3NlyBR+iDRlyFx5G1B+E5YaqwVvijcILgMQexG0EfcbgYIqaK+8UGsUHykob8TYiXdkvnpGZ5AEGsnC5/pEIxwadyEwflOWWGslzJVIr/aThmg9r/dWgg+MEGll8Gu84d0AEd8P8IAinGRuF1IUlYx+N9D62zNkp43nxLWJdHI1cBsBgYHwnUO+uuXrrEmPqGwjJGKJFreD/qUSfYF5ofF8o1P8XSyZBiqZPS5QfQBVxp1EPQODjq/Rw1DoKPH2gcQOfBSyEta9cu+tu1qwk7sUdNTewRdpKnsPPsHOXzRFSPg1G/m5nYepbCTLiRIvZq3Ei8b9AZFUq8O5NMWo3s76XXkNAMJ7KdGH0WJzbnFUqmoLKgxppCws4g7IkkTS8AL0LzD4DAgAD/wd46D8XOPyBA7yc5Oyl2CuAG4URzMPHRGybtWz/n0srVX7zZgE7jZvVkDwsLC1fg5mGxOyasyBjz6rmX/Bo+mZ0f35t9S/SzSFsT0e9Lurq4ODtJWg9vH38XF72fykXnb6u0ZSeO2ryHXWQNYRXzQypjyyuO5BeXbs/e88H08iWmqrduY9f3RS+3U5tqv/fyOvmSX0b6O9v3rog3JXh6H3Z3/6wkcT8/naNIrzyygkCnGyBqRb2GFkij02j9RYUJyPxZTU2VOUz2aq4TzzfrC9huDD/J1y6bJI6imb2tq63hUoGzE7QXnOStFXuad/d7s18jerIv2P2wkzGhxxccOHv2wNSPQuSaQrale3d276/fsR/d3atfGlSalVXq6U3ypBP9DHX9Pfn6K85ONpro7E10BbGFoc6de4LWz0XIS83JSaWMnYI/DK681P3lkgU3UGYPbjIzu4dT8PngD8WXj+Z+9Je/fJR7VFhV5unNvmf33/g9u//tbfZX1TciML8P166A7BJD2imqdqhDbYF43HzzEjKzXq6Z2bhW9iWvTSMZ01QZdTCwvZRe3t7+g0lCF+4X6orqPDypp4fTE9MIaZvy8zdt2pvP8pM3W/7zOtu8dsse9ujRI/YoL2jzuuStW5PXbRZOZ6akZH64PiVzpnvJmkMXLx5aU+LucSb9ckPD5fQzaFianLyUMllsLUmTQtI8yy0WqK6BYw9FoZ3iPxj0Vit5eGMLdxL1RnDW62SnYSULv2ZN6HATRdSwg+xWcBaOtNnSjayEz6DjzNnY/dvb6KLupBw2q4+wo8WS3I8cAOQY1Y86q37Et7OoFXXCMXZP8GIJt4Shn6ea56TWyN3MPcXiRl9MYmvJglVk5zs0zx40dM8D1Git4rVWvLRtTajFrTh2z65de9gx9N22efM21kWQ6hvXJG7PZw+azA1Clbk2Je29dwUjGxm3ZHH83uMHN+Q6uVd/UHmFr6rJUif7kIV6UoN7kc1zAgKdyUwtbiT7GOuTLcAeoANCcr1x/t132AG2Gtfj9PV35YiaOWGsgn3FLrOKsDmXgoIwB+diDOa8RrqTNvKfbNqQLjabe2mtTxL+IfqjG7vBqtkYmleCGSyGTWEGeWDTCnwWB2A/dN3LdrA17A8sg+Tl1kkjel1se8yWq8Q/mZ8TKsxDhcfNI/kWGl9oriu06cf9kfakF+1grUaRWtSSXNsqLJ1kpYLjMnZ7N8tlyzANw7agXVx8cxq7x+5iD3RcUFCDm/eak6bPwJ0Yi4twZ9D4L+eEswvsM/Y5u+BF6lkymBG32qTTaxwUW5SqOnu+btKo9Yvkmsat7PuHhRmf2DSZT7iyist1OCt82TyHcCi8WscVNxrvyjUl/6EIRJtOo6vC/vg2JmH/0yypmiWdkmua7cXHjb6yWzP9fmi8YZsr06aETupcDZFXJzoIGafYA/N8mtPkJt1o9JVuNLlxX+VWuvzkZOEm0atnio/VPGop+lxjZhSvXUNklms4DFeyVHaGnWYpuEoOZmXsFrvNyjAIn8PnMSiPzWLZfFtgHoUQCiJg9QZpo+oNPVRvaHVoibsyBVncyjZmZm5kQ7CyibNpYmflgeZPt6Ss37K37mrtTXMBl5Y9tknbu720PVDn0+q2vBTayTwKOz+s1eocrCLjy1yFz34ueeOnrPa+IGA+Grjcqh7N7H1uV34C5xJnH9tuUUOGq+vPjycfHx7sPCnYSUGmc3PyD63Yu/rml6yW1c+/vybhzpIDx1IyE26eRdcf512R804HBqxZHhnt1tP3cunlrwcNvDhufOofFiW6Pdv/+P4z/+XNPauRLPcNWc6Ofjxyn6fjSJHum+9Vm++RuzfWUPAlyySQfP2lBIo4Xm1jr3+gRufPw54agLVtT00Xofx60dq4nUfKykYdSy2qNjehsG9HeGlIdHnoDw8EvTEhwnT58AvB5rWFRsOJ3I+POyalDRhQ6OPTzPkdJX55ihOtBN0CsCWGEkvktPnVhHj60OmpF2/t27JlH8/m94cdTDhnsZxLODjsyBFhYHV9fTVlYVqUgR1jjwmOGaIKiCjZe7GlTqwnfXq2tbfeFp08bNFJrJ+8a8qhM2cOTdk1eVL+783sP2iHKDNyJf8iX9+68+frfH0LPT1xJHZDRxym43ITXSmUWDioctP+sJrHeqNywTYHkphbVjbsYGK1xVKdeNBcQQoUFJASYqkQ9tOdgigDjkV7grEG5mxTpIV+EsntBM9zybUurUK727zVTtXGTkpqLul6/t/mV0REXlzAHrIKfKH5JtqVCfmpmUe6CWGh5RWDBxe/2A+HYGcKQq+y2lM7DhdnqzzYTCmUeHRRb0htbO/qILTxxbaKufrrxdz87dvy87dtzy9jrNFQNHVq9rQ/Hx5aknihuflCYsnQMmFE5bVrlRXXrn3LbrJvevc51O/Fj/99VmQEbRYRJRwWEalGJzripCiyoLqPdRore6ro1VuPixRVlpi4vejIkTGHlp04I+SZZwvZOdnleeYUxcmcHR11n2twguauUvh7EDs1Bur4RetEGSUpvGm34vQN8XmCo2LQqOL0051WCUj/n0ng/A8kkMKLuQDWVVqmWtC1/U2l3X3atK1o//atRUVbH6Aju/fgO3YfNeL1+qqq+obKim+yWCW7w+7Swg2l9XHCIVbJxIlEl5943k+J5SpOdJvQL2vfkSPDjr7bY0Av8bCjprrcXEJCGSNlmWbHkc9X0OxfiDF8Bz8dYzhRMW1yQeiGDRHbRp3Kf/RV6MmFxjOG5Pei94/e/8HXF4yHpVHFffuGhIyeoO324s4NWaU6Xbm//1tTX5/i1d1ze3J2UR/iGkgL8r2cbbUmDzBkC1oNihi0N/QaXIEJ7N3XTR9/XJObkiJns0/Szbs3TM7M+VwIT8eRfDWLyZpvqutBW7cHOYLVmq2byxuL+YocKCt79eCyE5X4KR4V9poNOTnleUJC0+4iY+QDsYAkGUHrmiSFq/dMPfJb04iTGIZhJ9nsRim8OUQsatrNL1Qm6Z44TTG2/lJKq2BHdypGlkpjOrZM4P+nJG20v2A4ISQwYOXyAW/4ekwc+PJw3/4j5w16a1bXrus03QcN6PPGCLBYrJFUMTp6w1gABwWWT3vSG9jSK2SrvYvZMh6lqHc89drBakgHtZ/7l0pjmpWGifttqdxbnKgEqpHBxxoFdFbXcLWGCb3VWs1DXbTPeHsKbwvGWd6jvdq15NBApx4TpqVs7aVtqajv4+wglL9VlOjcx0Hqe0ZeR3DBQba6APY43lYX2/RLbeoyPIuTbXUFnNAIr0IcxMMqWALzYC7EwFK6mfaFSHiBnn4wiEBPtQjCcIcxhLMUTJSXQDQYIBb6Ue8EWET4A6j2CiwkcCebtNAyqa1oekbTnOVURhFm51/BNaCVawhxWk685tOcRYTN5TDQnN/GcSzV5tO8mbCMMCIJ16BSi1ZnGFSN3InKIirjCSeC6M4jPHeaH0fcDerY03Smq1RMJFEcwQLq5VxNhBunUvIj3nragW1ntcyxfddg+Yp/k/HLnyPwry7I28SWLxyupMSlt/1GQ33yka6tM+gyp7595ucf0m+jvlS+SIDQnwDpl9tgKukXPZVjIYhK/qYZ4XcECFPJdggz4C0q9xAg5BMg/JEA4c8EqPLrDF9DA0yB4V3BrlZlnEx7O5zupjW2N+LhT70ht7X5tzFqfcY/fgWN3Yju8l/xrjrUiqvasaXehka7/tA27SVP6sIQgCZu2+GtU/uSlp1bvngB+B8Cb4reCmVuZHN0cmVhbQplbmRvYmoKMTcgMCBvYmoKPDwKL1R5cGUgL1hPYmplY3QKL1N1YnR5cGUgL0ltYWdlCi9XaWR0aCA1OTUKL0hlaWdodCA4NDIKL0JpdHNQZXJDb21wb25lbnQgOAovRmlsdGVyIC9GbGF0ZURlY29kZQovQ29sb3JTcGFjZSAvRGV2aWNlUkdCCi9TTWFzayAxOCAwIFIKL0xlbmd0aCAxNDc5Cj4+CnN0cmVhbQp4nO3BMQEAAADCoPVPbQwfoAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD4GPBEAAEKZW5kc3RyZWFtCmVuZG9iagoxOCAwIG9iago8PAovVHlwZSAvWE9iamVjdAovU3VidHlwZSAvSW1hZ2UKL1dpZHRoIDU5NQovSGVpZ2h0IDg0MgovQml0c1BlckNvbXBvbmVudCA4Ci9GaWx0ZXIgL0ZsYXRlRGVjb2RlCi9Db2xvclNwYWNlIC9EZXZpY2VHcmF5Ci9EZWNvZGUgWyAxIDAgXQovTGVuZ3RoIDE5Mjc1Cj4+CnN0cmVhbQp4nO2d/2GjPA/HGYENygbNBmGDZIN0A24DugHvBjwbMAIjMAIjMELeWLZBsmVI79rm1/fzx10CBtxYSLIs2+czAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADwz0xD17ZdP926HuA56Ktd5ig++lvXBjw8bZkJivbWNQKPxjixL0MgUCRU/Y1qBh6Li7vUVB+7Isu65WDjpOj91LRtU+3d18+b1RI8AGPf1h/HIl+0UDuf+7RaqZ78gakt6NDHDSoK7p7JKaWI2pcgicobeZkVKsgUWDBKyfw/KdKUZW/vp9YVJIkqxvD6kWTqzy/WGNw5xsRN/sPC7uIuDSMrN+oSdZHFnTnT/UJVwWPwdpGHwXwwkvG2P9VtV2umrEhI1EWmzKl8+tFagjvk82O3G5XjB69i+lkptZdDh6CYOZb1+q0H4XKBJ2Yau4un1NgvRgntprjQ6XK8kYeMiBRBsWLNCa+hpp6ccWib6rhzztHBHjSik5VxYSMOVXC9kRB5qDdXj6kHTjnU1FNilVIZBgJ29myV6T2zVlE/mXfZZ07rkYJaF1fw2PRqFGDWNy7yHUW6+0XqZt4ilVSkPSnDFAsheEzai1Lyn8dQlN4Opvvmx+g6d7gJbjEqjlMZRgUUUxhf0f7d3wDuiVF4OE5m3t5PVRBTMgxe1LrghDkWHDqFAmJU2X6tJlXskYFH5CR69sZctSJxgEO2ybjR+SBPxFaOXKOaH2jWXSk97gDulLFvm9Qp0jqt/7pb93eMOJH1CwKWymWRyx7JWIjmkYE7pdR8agspqaWpI3MloTB5G8uUclkX2rlNkdI8MnA/9Mcin5XESfOpCeePzyWr9Xa3YXIjHDLkqVwWCQhE6sERVoRkIPtPKWaV1OLCbDg8LkxO8akjO65cNoUuuxa8SlcZ3JKLpzTGB/kr39qIwKCWynjJbt1F9mHyo7mIhTy1y/LAZe+2JCYyleBGJNwfriRcPClOAjBO1o7Hi7ShOYbXNDYZZXHPtMtMkYF934xLKcM64IeZxlHp31e6n8T79bMyCq6mYHlv1Ik/Ma23+2ybbNLc/FjtskMo6vl6b5LkW/lDwA8xNsfCmq8yMHMJ94f36+dsyyCNoKBL52wnA5cvpRazNhrzjEuIclkk6qd1LURyP6TPg2+lLzPOx8jOJSKEwh6aFif/R8geuVjjku1keFtv18WcDjl3z5RYZxNKkDG/K+kr7brNBd9JIFDkGk/z2YT7I/r15Nccpf8z5y+JbCchXzFMdER4SrksEvWN9JVi9Sz4Tj6dGOWH0+m0z51bNPrTCbdX2EPya0Kf2ikp6RYH2XQ+bcqf5+aUQhPOPVP6CEbUZQ+PsuzGs06TxYoO/B0Xn3v1/IcVodqX6k+BTOnuj+jXW7/G+tRzeMopKRkwsvIVpU3580J0WMhT6a3Fok5qKpESRb4Z5l39M8znboZEGZKovBWXFUKmFD/mHNhD59eM3P/xSkqGGM3RPI8MrT8vw+SnWdq0OGYWiXoTmt4Zms6gz3QA1xOsNrFrtUJk9faTPDhRW/r3XXd/RL/e+zWUnWJtDzVibT6JqGgfSZO54u3kTsvupTWlJuSpxTEVUS8TMmVv1Cp/P7ievohaTlnBhFr4FF9tZMr3nhKxzpwpidmvWXzqz0UtmGP+qpFXiNKmumFabhqEyUkujYxo43NlLOpuDugUlBzocB3/DeB6pj9eAbwznztO6y6Ut5+uL/J5WYFE1JmHAxa/xvs/Y7E0olAnJEoml7MfzzFh99K7Z9GI3lkXdWezxeHpM4NE/TPjzspTPfgDjVVawTS5Nkt5GCzjMjEeK+xhNqssGvL9OP9hsmEq0/uSumfmicLkFJ66XK1cpqYeWJm6CJUrPPVVDonaxKxcUn18fNTdkCigvKtusQkpQIVu0ySJ4VYRDmAtfiSZytidhToR8hXDzSlBpjmnd2SQRXVRH49eP5fHpU8ZrrwBiGU5pYVCBLo9pKOOU3B0LLPAzPXZNQFlzY85B/awXFSWdYX5NaIbl/DMPHF0nbpxRRlflsosaMUvROzH9BNfmV30SxGxUH2mFD115P7I71o5iebHnAMlwQXF2Z5FAkQ3rlp/ptK9rP1f2sjjCVFflpTyGurQp5/32px0kYp6zdSpqtK36OevRaQSVHT3R4SbhF9jh3yX1hbduMQoNK9hExyr/MsjDydE3Vausl2S/L1qp/TTXh33y7qe93jxqE6F9lsXqbfXdcpnOYh84QQ7VfKEkpB+zSCUlOzGBWGCELV7Wdo/M7wsV0Wd1XDtJDjb9/swymPKqoGmzZK/dM8b23zZX/HghPvDlUTg17TimxDdxCg0uzJWYs4920rCA19Ff7/Je+UOUrlqWcxZHxZPRAciKsUYneMkPN7itejVGXUyuc8bqlGY0xnrnm0m4YEvkni/beSm81/HNSXl1NRgP6uBHYVG9824koj8mp5/Ed04Ll8xCZ/bumfBZb0IvIOvk3q/bbLa5L616mu+UC4q51qR8iN4AcIervo1ohsXhwkECZ97WH9TwN+Rer/J9tXui9ZlCguXy8fqiucOupQKe7jq1wjhU0ehL32N3n5KRde7S59kuqKy4Csk3++SqSnTtv3KTZbhuKt9KXYJR0jkql8junFc5nn0trqu/uA7Ud9vAzlIjf287qqcuYnSMkZUFD/mHEhkwoVXShr5+ogWw58LbETXwbeStmmsH5fwRRYWE5XQPjG6MRJBy1UjKrpxbabjCvTxGkHgx1DDgESzWL5NkSoXy5Kve8ozulUTQysJF94iunF9LE0meut9KfCbpH0f6sP39PErInXIruvyVaosF9wOJ1x4B6/UOEtS/n7QFi4Dv4ceBiTeZpuo+z0MJlKs97f54GiGXC+etG5EheV0i+EnFy4Dv0dy6J3PtE11wmdYl4qmlPSJci2bdpwr6qyQOnNVlBf/DdwXaaNWza7M5igFb/vTipoqmBjVWSR7fzIpu6ui3EEp3SnpZjMmbE+fdL9noc+CMdxEJ7LlUmS3YGmXs9NHFjynzLDvzwOyi3SFp51FSoiMwqLP/Dd1gi4N1O7nr7ab9jHYb9OnsYRyoRbEkx6SdLMtIrXqH53DdPPklMljYNdcNKk4fny46abB1Ijm/VStPBbcJyISJKgXnVKtduPaQFRI/UQyZe2aeFRXZJLT9MXagztExKsFzJz1sSvNKMJbkOcdTCDpd1kcrxhPXKD2ySeAR0JPwjOUTKmUoZvD+AyU1NnPFiiWiIFbGyjexWx0+5nne5i4ZyGZZDtyzURfdNM3hP00Q+MUT/lR13VV5qt2bdxaCAY8FMkkW/KQJv+NZEQzkJSsFyswP0uKgamUr0Ke6SHqQlpEslzlGJbqzOVqyCCYTbmshwCenUQSHimpbvluFzwJJrC7lTfkwZn+9O7k6e3QTN9TW/AA6El4ZLiK6IgRqskfcatNyLXJJNPQ9z0mCLwYehLeLoskbfI9/rKqzWqYzucuhl+p5l0x3roC942WhDeVWjdOW2wiq6bfqOQ98Vnk2Hx2FSUJz652FweRzmMdCNULRicpnjLcuhZ3TZSE58KSiYVN20Pu+3D7l/S5T7FLACQ8CW8c2srpoXD5VsbUd22nrmH4LHQXV3HST9mc5OY3a/N40Fsnlwx/ybCkWTi9sx9NLzgxTG77KNVvVeoxeYt9bnUdvGfF7+aQLR5AlcUOpsXNxcEC+qvsAnnav0acO9rNIVs8ADtEqS2gb/1M7BS6zpxgQguX9dOt6/MbTHJW8oI97ZIDm+g6Pwd1ezXSl6amJcNfa27AFMlSbhdOt6cHd7APrzM67WMRPQBmZiUV7+ZwXqaahlsr2/zVzTlo4MmYhq5t235YLWQcyA99NwfD7FvJAqSksBDMa9F/lrMpO64s/LsxNdEoIur2iUwwl2SPiTsvRLhXaZ6MhqwuNORmENZh384qqa1l1sHzMAYCRVqm0cuuLjTkp6IF4anPzGYbpmeAgOeicy73+6m5+FL1obBf9ZGV1YWG5iVHSUZ9eGreaCs9AwQ8FZ/W1LE4bbT9LWN9oSGfnmFTWZvlAXSv5AwQ8DDQkMnHrrhQVstMLoGVqCDwb/dh1GRqY7U+o4j25zPfWpkCC635lJwBAu6fKR4yuVC2cUk7w7mPbnAKXWyPOT4lHzynZyxbK58W3ZSvXgvumtjftrasC8rZVPlRuQO52NHOptdsC2kj5H42/qKkNpdZB/fCNMXHRJbE29vyNRjSPWWJqV9ucY8+Omw87y5dmXyWOBpCLiampNLLMIM74mOXaxlKpuHF8ptDu3fWb2LFRuZFh5CLHd96I165y8QeJtmOKanNrQXAHWCHcfvouNbwbm2OMiiW7IPpa4S4MAG77aUP8HGs3DceXa+8ueXXVmdw13SRlFiihifaXDpIoy6PHqPqjtE9MhuvNGlTbCvevTstoutlJiVemQECfh/TdG2bysaqgkbzJBrP9u17XmolUESL+IUPNkKcH6O0KX8bEV234am9uCGS8G6GtSdL02kRgFkPRGqqy/QdIwfrM7Orm5U65Io7PWYqPt4ko+skwqO4FrHO29AXSqvF0SMKFuxLRU0lG4/6YY37YkRmWKlGpfg+QRJemDYVRNfHXChLc8XK88B3MrrNgQb7TVcFUVK3sSR1r6ipKdl45dLmm9FsdUCP9KbL5RzjvyO4Zy+CWEjC+3n4jmVEZ4/P9oSarm3cZtz/BZfXpKA0NZWnGo/14zZdG1XX7ZSnMcztJ/Z9CK8VB8D3McY7lmXMJpnXuRZpuI0pG0YlS2o/TU2lGy+frZm5br9WSVXXXZGEN6ZOIgnvBzlFwmSVUmtPK6qARs0Cycmtminjlko3fDXrpk2RUn2fa5LwUic3rgXXMI2jOoWmFqJEO5bxuTba69yFNoVkonL/BwYq3Xj9fJu/E6mrkvASIAnvH+k/3VpS+THKLGm9p6TvWKbm1JahmDReI8RqKt3wZM0G82k7f0kTqeuS8HQ2rgXrtKVQREE294ZrrL7OTdggB++3xGpqpfHesmvzlwatwHVJeOkbIjD1lyiRJREC2Ij6dZpERA2Sz98jNbXS8OWsR/JsvU+vBkyvTMJT2bgWrPDH+9uH0+m0t+ZPbvSi2ZQF9XUOtcqQiW0g5Aqh6cY7zSJ12PCWK1XjRC6dYP1dyVevBUns+orZvhndASWbez3qp9ukQAxbJhGRmko3/CJSxpKu7VRaZFrvbbvm6XcFsc6/ZEfy0/NDoz02iTJD+hba6xyqLiMb/iHRCHC68Q6zSG1kIvS6WJaqoIma6w+2z87TDwQpyOpFm3RQ0sCSWLIR9dMkog3clIJrsiK4X7rhF19KT18RVVQ87UTN/eYjq+/KgIW3/waKD9Tx8ZNQUxtRv4MiEaW8ZBQSFqqptMjmy63Z6ExMlzgpwwTLkNLHUnP9weAvoYQO7dWfCr4y9UbUT5EISiIYl++myavla6CmkvEhsnaD+1JKaxxUV49DUJjALlwmhpT29jQi5N/OZ5aYc3IeevbliohhJY6Q0uBCWEklEqipZHyo5Z4/qSndQz8GEiwqwiRpxj28q5rElEHwl4ROTYKNqF8oEXbXGSGqu8B5lg9OxofKLNxQ+aJz4mIfCfOdyLx525/UwuDfibpeCfTA0egzgo1E2FAlJXmX1G5iJbApC4KZtXhyKj5EAtEu38tIVKmUkdfspNZ8YpIkZuGAn+Fq7zRnSoalTQ32CEncvGCvsywDv74XeuwieI0QllR8aBeI2kTCk4vQvtvVXdlmwtfcKKUXW1PyduQJDyTChAn6Pkqb6uxZrgocwa4zFQnQGNxhkRa9Ip+BkvIylRUfvfvuNuJK78ENpfSrbAwHMw6aS7J0lt7CE6ETXWaql1z780ZShvCh/0mxs9T+2l1ZLispNOG14Dao470qp1gcjDkZ3GmrO1ymcKW0sS6RyywpzQKTbYx111BEt9kPYSFwI1bThazTNCwlnRRoPq6RuGqONRuVJMOOvZAjN7ugYE8/RVI4Hqlwq9TLT2/3AtUrZcBtqHWTwV2e1h6irmHax5URQ8oSFjFJkshwylPL1JTRSBW7wLtIrV7xsTm8W/muVlZ/Bb9PHPXu+ASYbFEjS5hAJYiuk1LiMfkyVFtEvtx/jmxRd9LvVYpB24cjNnxt6KY4QdlIwguj66E7ZURkUh/v1BTFUsNZOKmtzcD9khhI8S6TUWJ7e3w9sSiOru9M+YGfVnTctKgpJcgNF+kRiYfWRh4W5NkD6+loUXRdulOhp+RhakqKU354yb1Kn4CNobuRKZdd9rUkvIZZzeSCckxN2ciW7QwiOvm4kDmbkqd7pqW+nITH3akipeIWNVVXGDJ5CspVQeE5Tl9OwqMMJjt0nFaGk5kaOF1bW/AAGC2RniJwYnKScodY0VYeGmZ3aiPbCjwT1NEaU2e5vboiCa8OjpE7ZfLX49A4eF7KqM+3ICYkJOIAvGx0n6Nzpw6XXuT4b/UED8PaFIGCGzMlCc9uaj7RZzUtc6LRwO+pKHgYjJrSk88/pVM9dw6DTc0HOrsRXQcvBMUktYxII1Hc4zZhglombhIdnZ1MvP0XqntzxltX4AEgJzrWUyRRFTtQZjqNPf3kMaVFNbe3rsoDQIknRSuODSRAIj8lTMKjVJWnD3SHq29jc9qrsOl1TKj6YxarLpeE5/Pnpt+t4+8zVGGejwXr4l2DT9ksq7quq9K9kvtJFOpk/tzT02hW/qKa21tX7DFQlizLm1tX6sbwzLHkwukgTSuFKg/2en1SKCPaUHdTeM7EdrP3F1PN30t38lL1dnrykdxoSwCy+q0spE+wBl9j6i+8wDsZZUNbgl6vOTTdpH7g3hnFIjRnZ9NUoRpZqfU8VvCCsEWlgo6/S3R3OdHjReQaN5uaL+RQZtjbGBA0mi09pTCFwhwbgqtsKJctN7ORxwpegnEZzZYGLSin2jS7Semyl9LGVGzwtNgUmx0pIm19MppwH1yTsGmkqOYkVzUFDDwvQYqNm2TIRGltUamUTTOiNuefqilg4PmYrFLKI200mrPGou23R7OrhE2zUzAm+wUpYM+NUUqd+aAOvZkhk8Gc3cV+t0bSpvVMTW1MsAYPzjybopOiFKTYXNlLS6+rVTJvKo+d+GnosADxkzDPphicUjqc6jxWSRuzDT1pm9ZnixwxlacsjwQehKltPlrl+DziNi3juMrKecGiRMmnZMnxu3wRSnP/P/FgYHPFnwFujRnHHekThQE6pYg5PslDyvTAayehKjaN3dQJZaW7bdUV9we3gtuTjo6QTyxWTHco0UllAvTGuiHibspD3E2L5WPQBzBpU6N6HbgpanJJY8/RCi7KLLAy1l5Kv+3ajBTFZjr6pZ83JyyEK0KC+6KRK92F9mSX6TKlLbqQxaN3eWwfNdJT6tmUflJ5Tz9h4zGZLkqp9V/qSJjs1u6jPe1SAqKZhcqIm9ZvuzIjZWXRkCzj012RhHefiKGNJf/N2JNoyMT7xGG/TYtOLjZqJrU42hV3Yzftl4+TXgr8JlM0ribUiZGvIj1kMvvEf+RxbcRNUUmxfaTBQHloddEQJlJIwrstfBvFXCZyi6GNjaEzWi6GHCqx95B62S6LlgipZ4s28sHAUCOlKzEtvhSS8G6FPo4rErlz9rpvDJ2R/rCpSw0/rl2muOxGIss6SpuKNFKyEgOzdkjC+1WmyX86hO62g2mZXcbCQFy+YqxPbGWq5yeUy5SEgk6vS6SRkjatzRafHEl4v8d4UUqV/yIXS8jfD/u9/djM5UUYSMhXjNUStCqjCHkqlynDL2ESno1OdmP4lF0osfyvObjPSML7PU78t7YOtch4GylSMG9jJUdz02FGwukP6hjy8JRymZJQMDlR2loEJGXTaNlsfwJJeL/GKNwTdVyNtEztv4kw0Ea2QJlZn5gkla0do1ymDb8YiWy3FwFJJeGRJI/uC5LwvpXx0n1rEudOwj3RO+R1UupWwoz+5q2/Awt5KpdpCQUbZpXfTbFplNY5H19JWABfZ4j845ne2hb/VX+XJ+sTLTdb12oLi09Mkju3r3ZZnqnpCW367h7FZhr+cCUVdwl8oGTYfsCrMymHyBsatdKlFan5HJevBd6nEkMbK2FGA/OJ6UE+5KldpiQUbJhVXon4PfgUQryoPBfjKrzT324/4JWZTHSyjo/noX/s8SMqvT+gd8hLXoSrrI2hM+YTkxnywQjtMmX4ZcOselSb9ql1CUplamCz/YBXpk+oo7cs8I89/hdu/YGdaiJ3XNCE1HH5ImzalDvP7agNT/2XuOyfk/Dk3aYj/RJDcH+Fl197awM7Thu7qi6CGW0HQkrK/Pq1P6K6L1KplFydePkK0qbceTl6ky/6UFGGy/DLzIZZnQlt5vRJj8rFHzIPOFrWpgaChdL+XGN43L+hobAZCfgQHSa1Q/4pLhVSZ55YHqO0KX8+57VhOlSIpUWJRW6Y1RlmMy+eUuV+hcDxtjZe3SAcpElIzpLXJIdvbeBGdJi0DnkvxVQMbSTMSeVO74T+WEKeijLsFZVkyk8rfy+rxEcbjAbuR1lohFL6C0yrVEIxOExbHun3bvhhUlKyw6R0yJs8EyZJqJM6E4TmJAiTU2nj0ikjblr8Qu8sRASVIIHqty8D2xgV09eKnjGC4lICOln80mKiwyQ75MaMGIESiZliaGPDnIRhgMrdTLFyWvyizK5OwhOCXffbF4FrMC0wTYqashogGL4lEavPssNE8mWigHKKQhPdzEHyNZ1TRGGAY0bCpEUnFZUU2sdLd5IWw69ksX6WJZqrkK4O+Co5eSOKmnI9L/rp51jNp/8iOkx5bETEVV9PwjuImuzM1Z/aZeZMLw85+xjNwgndeKw7/UMMViVoasppADJ1LjxFffrGfBJBxjddpLii4vcX8qVXSfrc1vz+yeK+nOKyG4kslFk410QWwDfQONFQ1NTOKaJ6aZDTrChEkPEwt5tf/nJo7bH/wpsRivwylDDAOCub4DIlftGpwp2/nZIPBN/KwTWToqZmDXDydsM0tlMKIshoCpShq01iMEflRTdOyFeMecokDw1e6wSXKfGLUYgSZnX+OoVXO7GaWnpepWmcT66k4qhAFd2aZMqXEd24IEwQooUBfActuExx2SerlMzUQHhKN2CcmyRWU0vPyw7fNkxJySCj1r13ZXxmp+jGhWGCgDJTwgBubCS4TMYvXG0Qnbwl7dJKkZpiPS/ry+xY+4nulxbENpSLCIpuXBQmkCg+99nHJoPLRHwM3AOm9Xr7MVJTvOc1+zKdP2u++M+pqEC1yIDoxkVhAokSJvd1jZSh6Q2k7wR+nx0TjFBNiZ6Xiwzu57PC4eHyxWAGUdwsDhOkLosqi1DAnTNyKSE1NbCzoudlfZlxPrnLNpPwSA797fnNlDABVcD5QGL0hp9/35+axF8C7oROeCfGTvH0KCkogRITDo+QrwVu4CKtNs3FlqnmtsBGdB3cM5XoW1GPrl/OBj2vSmgiEWTUHWo67MuIm5F8RYvhi5Xw/u4P+gG6phpvXYcHYie0hQ1Zyq8tK11yB0cEGZUg9tn1EzvtZmWm4wqYWZ1/9fd8H1Pz4ZbEKrHUxheYAn83UFNhz2sa2RcRZFSC2GcRGb0iCc9EJ/voHjfiP+NXZuV4pmBwf+PaPBB9KAlSTaV6XoQIMipB7PP0kXEpisLtnq2p5rfAD+oU/fgnw7JlX6AWlm0aukqoqVTPy5bOkkl4dPqTfKTloLhZe+ebmptX6zQPhmOljesxLs0w8ZWiM66m1nteeRYk4bmL7N3cWz7OxcXNxjsfx93RmILLf9DmMoIE9IPFXk3vTq/3vEyvbfBfjHzF607z2QGTUUo/8Uf8BG9ukvFFW+Xo732BXnGShZoygjKmrjZ2ofNf3pTbBBuaPxJv+dtoP01bRaeureum63+0Pg9DwwXAzS4YuJraZSt5TcbfaPyXQyBO+XvVpy58AKYry/XVopZLbNvg5CCc8sQ7fat5TVESHt3tlTLe2jJ4kT7GW1fp1hi7NoUHeWxqNa9JRAUak/F2X4GAn2YMBcrwuX3dM5PIB2BqajWvyXhih5+p2SNAk18zs+1t2/V9c3IWkKKjL0siksnU1Gpe0/T0Smk0o9mTfu7T9kCa5XRvjf9LhxxEly04btXURl7Ts0MyUqunSKLCNYFsHOuVZcr8AKNyvJ/VVCKv6VUgCVmWRWa0Cdmh0YfXfQnTsfFyVlPPnYY7jX3fT8nTbqCvVs4UKW1Eg5d/lBMvQdpR6g+3Ty75aaZmHjT66PQinQuxTdGZU9q+nViH+eUQocoXo5cBgOJ/WiFjxfaamiLPoNXvTPPTopUDX4Tdy75O058onlT0cbGdmSytqalyrSO8eKIvx2SSS25diZvQO4uXX36A+rRPBSknEhye6+wgH2tM3t4I3PGbqwxuj0mxGfVT/1l5mscgp7ZQZaonx6CP1ZQJAO/Tj1auAI8PWR89c85KVDXxY7UmU5U1YGWkpsq0J0XkL2v5nhkrI6NyhlbIijwnO5laHjWSc9aUTr5q98Qca/A02A6d1vFKRJRIplpxyJu3UE2ZIYXV+O/qMBa4Q/rmoyyKXVmtrK/pXO4+OvGZ0l5NuEB173VNqKb4FGqVjZmtbvrilC4BfpPR7qHg+Oj1UqbV1fgQhb0b9Zoh+G6c8I4+BWpqdZKHQUz0YM+We0CHzwM3IQ4o6UlvJA6al9yuKxBOOauzQE2tTkUjsixK2R+KsObdddUAP8p/s4bK3/xHueeLw4jDVCtqqtjorDHyRfikmtLmLEo0kQoE6u29v64a4Cf5tK2xbygPeepd1puSSJmbdIApVlPxdMMkAxMcqaa2M34UkZr8q3DHkxefjOHiZpRleazjvdI9VqJ4QGlU40m20T9sJEGqKX2evUqTBUs41PNTdVdJPj4S3BdKyb8HpM9dtmohkqhwB1jrovRBUedZx2oqlXSoYIrOD5NqKs/W41Kb/jv4YcZj6LlqEwAp04TvSuMuLhSVcHBtHqmpXXZ1T6sQqkioKfOlWbnUDAtW1z0F/AR+WoAUqjEsVqgSRQpkP8RlScoiNZXHTk6CQWoaoaaayKDGVe2uewz4fuzyLsbnpvTKyc+1zDtZ7lOVM0PdhEfG2bMO1ZTiNydoMxky52qKT0tT6LZ8LfBPmFDxsHJ6RwJUT+yYSwz4TxQssuu3PW9nwxSqqetF6hRIjVBTRr7S6SvmLNZ6+TlWJ5e6bdF2Y3DUduQ6duQLIUohDoGaul6kjKhP/ABXU6tZdjTTYby2ruDLrE4utb240xQdp8g33xS+/IKS4gtvB2oqv7a1jW2zsSc+jCLUlLI1PZUvoKT+mamrPz7KY9X0ysnVUXl620/aGQo2L+qFAoXTtfXhnrVUU0bYhmvuYfyhMlrbSKoprbNgLTl/GcBXmT7L5RfP47kmq6HmIv2yG+22WMzNwX9OxxWjVFNXz+CoMpVZTdUJmbK+4VWPACqTiFEawpDSWqh51es4ZkG3vbq2UkYcuvmbUFNXR893oSy9HU67LIhNxV1QG3m9uqYgYhnGZQS5AebQpF9erDXwsj/p2UpJu1oVtrdVKZ4o1FS/IuCcyf8xfG0j0elzXdXPkV/1ScdOVzwAXH7Pj2P0Tv6xP/u+MqtTTUN7shImB03ekppoWFNSUr0kB1KWDYznhxpx4KZWqCkuXysY6dlFo7slV1PT0aqvDzddeeo+7J9fbd8enF0/ZpDHPqxS6tkhG1LK+aEyJQ2keg7pR05M4spIEka5Yi1TYn2g+4SaqrJ04HsqPnyeqB76CPKmav/ooiznxLpw5Q2Q4lO0GkE6KpwXMJFfmw/LkVPSZpUb1qxc2jXWUpH/3PgzdXhbrqbWIkrtYhVjEZ4P18vXcRdWIkw2fnXGoW1TpwrRagYSMqXPQ101ZiPrLLWejikYXy/v5NRNLJcNa8e3Hbc35aJP2XrZPTub6GQWy/PMFUqJaLJMt+fylD/08qQ/gWm3xJojJ/rJKnZkTEiU68ddscPD5kQTcmjsxyqSy25er3YMnmFu20brZfsKkdev/pX0jozzk/damTKqx9ie9jn1CKuVNWBeFbIl6lqTo20WLhlFlly7hHyM1n9LJg9txppY/CGWy4lvX8zdpz4yRpae1075Kxv2FyZjFpGaAmNbfZRlqQe6rS35TzljlRTvR62GlMi4zI/MEqNz2+HLxfz0qZtYeHCTW0Rnj953XG+WqkwJe22KdOqTios+0s+8JG5XF/c7x/OVOvk6LzglxRt1lzJnc/nWP3URDMlXRCreHV7QMHt0mP/EZfVt0enTVj+0M2/mcZT006ZptcavxXgK396ikyUGJ2xjeKm5shCSsRFSOmVX7PDwFZFSnJjweR17XLRxlohNuZ1hlneqt2MAcz91dRAJeNTcSRno9iHj0EWySkeELE0THdIPI39mcl+MQhuUQkmLOMNEqlktXCyP08VBjvT5zn9eftSXHqH7ZZYI7ZeGf16CS2cn/FFdqDfbN2YCCgt0j7yUl7qgI0dKSi5wZpRGu1IFfv6QKsvlTmNgYkQy0SUKtkzfJTqYMiHhXMcvGJt50z/96ttfJY+aSsmddIsq8aAkjZ2QeRTxZRcdFKGhLFvPO6pZw+qRaPe4fuUmXFLojol4ksj4TAzdhOmd40kK1X6tIi/FpB18iywNSVSYO2mdK+45UXPQUR64KW3L8tDQZkipY+YnaUaqDftyyMIkFT1q9smNYpEQduHe0Q3bQ+Hs34Gth//afBS5+utFL+of88Od4oIUomGvPikiq9GWTrYPF7BY9tfWLjE3OGiF+g3BlIqlkdVa+C9jSirpoI2ZohOnoW/X3P6XY5dwL06BpSGhqLQ71FIj1VSOlsRdblA4UeoyOaF7v1o3cwv3Mdl/IsXTJm/RBtJR6jJFEjVXhtdSctLPXC7YVe2UrMVrEQ98WepAgopUm7qAee+/OdfWdrL75RjpQu4sf0mkWBBceXrKP4qzqWy1/sjyNqC09DLC14ld3vF4+wy9VVmhDhq8HvHAlyXo9KwGunfcxfAeEK0I55ysuWEnJhlfEql0z24M3TbOZ1RtF6NslyNTU0iJ+vrC231d74VWfmkS/WU+3GooEpI3l13iyl4RtXNDMXnMF8n4UkhpJQlPKkkBBVODarsYZX5s+nEcu8ZFlJhEcbm/HnNfzOU0pPwG2eBdFgcvGSVTU8vYiR3xmoT1YR3JKal4HNxKroyYkdumTiexSx2Ej4hHAC7w3c3Gv1sdpVnR4y9FUldwFUHexUoGP3W7Jvdl0SfkYpQ2aG2PiI7kl0JKKZ/PPT1ajeXspwWMyo2LQKC+JaB0yrDOIZHU8sLSFButn7Pzu+WnJX1w5EaTe76nNWN6DtYuqVcKkzqM+nF29KjRLjj3LEiZn3q1zPWcPvpp/Ny04y8D824EOyYlizFLUAVS07rrdq7ZZqPJO5Lths8i5Djl8813DaZqdfbRdeIKs6RwfTqd6rW1Fq5lVnrNv9/rGYjD5BZuaTY7Z7zB+djJ5H7tViuorFkY3lN6c+kqNE5yPzrjcw+Nm2eiLsH5/XiRqn/lafdPYjxLKJ5k7NrDI5Fi7MT12eeCoiMZjW8ICqGXNvqHY+gekYs0rtX5+xjb/dvb+81zxs3csebGdSBScT0+drJqdQzpsZNgwwIhGf2asSDFM85fVds7sc+Rz62tgveM2EX13dyxu/DmwjC5h0cXrhIp7xYFYyed/DuFZBhxFmkM8o7imfkiYbQOiplpcBCXtPtFnvLnzwqYfwXBrWtlSIkLjwp9SaTCsZNGdP5FR5K8KTXeFe/7uzMaLZjKGb6TU1dXF5+7+g6f+87hE1o5460rdo7C5Od5PjeTjC4qEyCikuYvm9jJhpc0t+3nb12my5QYIbQclN/vhaPVb9FvYWePTbeu2Jl7N24OJBf/aSmzOVtu77+kx07OUciSuv9Rx8yGlGpxrIoE6m1/Wv/TngG3/VARWrQd+xXcfIv7wdQrtsmWwZXJN1SqkYyD/1JmK2vhhsPUNqRU9uyQ24W6Ftct86CWyZzPTLD9UPTz03jGvf4KkQr1TcckwzRys3KPkuuelbETZXEmK1NZUZklTi7vpFsMOHpce4+v4w/QW6WUfLsd1UaL3JSdrPqsBHh0wQhCOoJku2eD/7Y2dqIMU/t9pwXKkN1TQ0ppNJ92yq+hbEAUvZr3hBuYj5QAjy6QzPTJW3xm3H1f7R8KR94y1ZGCFOtNPzGzp0S05pDohtgNiDTVvBl9viVGhdoXRCIko1xTU9Q/a+evq2Mn6jD1KOKU++efGGCUUtAT8jahskrptOEvKq/m/ZBSoSK6QIHuLnGHP5mIBKyPnZifcYoPD2112O8v7+TKxrAPzzSYf9XBo8zbBDGelWazE35LYu/GIiXDqKnEssnhuMp63kJqmPr5MUqJPkSyxBfz3AwrOxKv5l2QVKFCMuw29qNSLN4myhTVShKpYernZ47X+T52/mZ+uuMoSgXjWdt3u0OuS8KLFqbzUO6k1F+7NUXUPf8mhWPfaYfNz9KbD6dZKSkqaSPlYuauX82UCp1/Agv5jdHwvo1AduKY+WvDci/EW6aHjJR4nTbSlV1n0Vajf7fmmiQ8/z1Y/Lff0bFWXHffYbifh8IAfXw8HDg46yrpSouWyiC5C65JwiN8oLumQPelj5ZblyC8uH07/HM+9yMwNNWH4knTq6fk7Chda60ns7vOooU206VNHbev/AWuScKzRGluhtddUrnU1ZH1BWK3U+taKyrpSovmbWYwGHgfsaprkvAcyip47c9X8E4hFaMEgFv3y0zBca1rrfRkFPuoQYEpZTDw+vr/INck4c2MNfsr8n3389W7W/pMcySX5YjD1be1rrWikq4MTE2KwcjuZcu1OAnPkoou+EB388xrdF9cxWZYL+Jdy/D46Js3FAxjnCZ5SOnJqKHnaezDQzKD5L7yNJKREOUneBlSDiajNGZPU1OmiY/mn2D1D6VrrQy/iOZgnlL4lB1J0uZg4G1ImeB7DtD+AOOl6WZtfcVQW25mvmuvI4kOtbicAa10rZWEAjIOIkPBMgZPufvA1Kgcb+9Hk/4GYiR226PpSeg0NWWkqbeDw//x44rm04Zfct1LGoJidx39o5/g1pX4VS72ZIyPZszQbw+1NaRzNDVl9QeNiorfVelaawkFb5E0UdpUWOErUxZuw0kJVz41pm3r+DDX1ttDbQcrgIqacmEAvmgboWk+xV9dkvB4hkLEXSfhPfMS3eOYSIlUrFrJfZ2UgzmTWzWmqCkfI6YAFQt5al3rRKxzV0fbjYZcm7IAvo+psbvoZXnZjOKM6afv4wuEw7vVNxm8WMZqag4DUJhhCXlqmk+IseVKi6bZTPCTuKlbHjGtK2HVhD3ccjBbL0mxmlpixCRTS8hT0Xx/H+u8NmUBfA+jFCgD2+smEcQVbbnVRzcez0CfIjXFbk8DWPM9Fc2nuHXXWrQXi/H8JmPfhof8/kn5++l02lvzx72aXG0NYQ+3htqKWWxiNcV8bqPs5vCUovkUlbTdM7AoNhN8C8rL+mnlqe7d98GOdi8JJ7tMSxETbamkooRl9+5zpKZYmNwu2uZkStF8mlun2EeNu451PjTxq/9pBWpih6whnGXqoLaGyF5Sh9oWOqbEIjXFw+Q85KloPk0lXWnR9FDINA7blwJiaPU13qKXtQmsnEX0vhIjeNweqnkY8qm9/xKqKXF7Ck9ZpaVoPiHGDsU+akibuUwNRGRhnWXT1kPCEoWvPkWtlW3djUzlvf2c6Kdze5jKw2BF52d0gfjJMHlPCnI865pPceuutGhkM93KTc5dtD7j9qX3yVB/ND94+8n80+7ypWlO3NFlhK/+UdNRhjL7mNzHRD9d2MM8W+mjT9IFKqTWC24/q01N8ylu3VbPwDFmCbYvvSem5qO0s92bn1vmoSkL20CiachyKeYqePVJJ4zabVnKUaKfLkZimY8d00k1Zyo67yUQh8m90dU0n+LWbfQMPJMiTTQaOG1eeke4BYL7MymN6oeeMr+4omla+6P9F5YOXv3ymvZI9NOFPeQ+dkQVnCyEYolub4qblGJF8wkxtij2kZaT08YHHaujgXeNN9mf/efaD/5vLO+yaJrevYdDsri/5IruUqZatZa3ZcKFt5TBUwI1FZkfU/4i6UpfTnHrlpck8JSCSuzcyi5bo4H3DL0+c/L5v7mBXXXc/dHPZLOfwn9H7zpEfpJ49a80Gno/XdjDOm7rhfDPp4Vs6/Tt3TaqiuYTYuwKG/kM17hUXpVnSGar7V9fWXXR/9O90j4PMwWiafwPG8qUKFRepz13arExuzIJr/dyIKY8LWrK3L6Xt6YX0ZRr5a00ty4UJc+w/Yc9Gif3JrbvWX4Y/vFmZarJyqU9RNMY0aFuXxAhEK++UFlpEv30jF0d+tgco8HKeP3DeuX2o5eTKjiebSfh3ddchW/l9PbeXVl07Jr6QjckS/TivWaYH9E/kDcNyZd3dHmtWKFxRQ44iX46V3gJF54odS0y/zna7QcnU+FrxMXYcXC3e4mFbq+j92u4mlYRiyhwSr1Zjajt3WfRNFZ0SE8JJ4w7PfziNRJWrcyuS8LLMwF5yQWrq+rRuS7rFUl49dMqpb8kyFRKzkhOqKkm1TRWvpyjyy7g4jE7ORtocezz1Ul4vTdItus+ztXwf45+extZuyIJDwimo2IRylErqqspo/V791k0jZMv6+g2ywUde/XXfGpOwqrV2VVJeKYmx6jrztSUFiY/e5kKDp4untJwRZVflsGZvH3V9hca5xYUnVJWV1PmBv6gaBovX1amlhty8bjW8Glx7PPVSXh6FJSpqcTtrdUer6jfizGZRWd6/dx/5GXwxJLJLfeijM6pamrgQiGaZpYvO/Vk4IUyVuaqkfhcbVuhFRMu/DnZrWRqKlFiMtHJ+LEvT0emTD01kPRUkzxq9X00kqKrKXP3av7Gm2aRL6rBEp5iTo/WJVcx1wxqhfb+SzJqmpLbZvlz9NubCl5TuedmSS6ZsZHOXilMJknZ/bUj3TXEFyhq6iSMimiaRb4aIVO77Prdbjy67RIilXDh0w4bC6Hrtwfnblcoqn+XpdRUkSljcAYyVdGCS6qa2gmTIZqGyRcpPh/y5E5PmXSAJCxEz2i4FCV87BUnq57/nNOlM9hfUY2XQ1X9k3W4FTVFgZdGvROZKmVIL1JTkzQqJ35HLl/k6Lq6cfGosusyJFr1rTjwx2k+9jSe7ZszaDed8vzt0F/x9FdgVPMiVNVvNMtRaxDK3E/14MlajtHhSE318h48jCnlq1yElEt+MiYfMGr1GaV9Zo7cvFfhAXMyr4JHdjiq6jetTNHMPjjRZol0SgPJWxUfD9VULZ0Q4bYI+WJTT1ou+XlSU5og7LIMWanI/0n+vcbQNkEa7m5jjxxgGTLl9z0nwiumLUgZhGqqCI2YgAeXGaFWKaXy6LMgCY/l7xfezgrJr3WvjThlcgvwQPY+M+kkHbKYnBTuW3sGq5DC1yJHTPXP2Hc0VlODbto81B1q4+OBmsqlXhRRbiFf52W1HWGJ6Dl6ItYoRKYM/ubpTxaon1MkT2+H0+UPTf+RYCZLyJQSXumt9YnVlOgtKVS6JpRqaghvYurlP4ejKD018xBIfp1F0u4oxPVWIv1aCVNDSk8Y7tqLkhnLwzju13izP10UjVTCK407FKkp0VtS6DO9T37iaqoJVRkLY8a5Aa2TAlGIwhDawrqhXXPZJsXx44P2mw8l6ty9H05ILvlLSvc6DsHxUywmpdMIkZrapZSDg4IPU3x85GrqEFZC3FWKznmeeiIl327KFf4pVqKEmvTjkTOvuyvA9+O9hvDlFn0sS+79mVBNCeujkRqk4GqqCPsDIqwYSy3FJnYHqX5axYzbGexBh1TuDPDCuwL8AEZ0dspvHg89DPORMFgYWqWIMraiBFNT5uNBnKyy9fxbEoo8k33N1onI/Mf0drubOMQxtnsrT+9Vv1p58EVIdJwV4ceDPtZZODuF1BmbIpUcx1jUVBcZWhHAr7IoTDE5L0hKfudM2u5Y13V1zFft2nhhteLgL7BhcpIp4R+FfSzh7ARqalOkDimRWtRUFVk2EcBvQtE5LzsF7+XRKACQ5fVq7cD34kSHD5xZIjnhzk4hZCTynUPKSF48s5oqo9CqCGOqA0ROpsLOpLdoHrYIHvgFfJicrAj3a0M5Gbk+aEVL7hKukijQq2dmNRVpm0QSnsAFA+Lj1btXUPtmWqsZ+AFyKzp24KxZjodi0ApvRqgpxdERpIIIBqemeuUWeaYl4QmsNz5qNx76/pmX4L5nfAc/3KYidKlPQsQarjXCHmCIsVqpHF6nphpFj4nQQ65LpbnuGafiPjSz6xzkdYeqZyfaVIzbrWkhw0nxrcXJmmqh1azzX1KhrRoZb3fHEia3A2ejOx70saYsXjhpVlPlquWjmHa/djY3ErpP1+yM/NtHwohOtXycg4JBH6vLZDRdqKkmW8t++1Rd6xkjnMdMSakSAfxkaOspGW9dgX+Ch8kpPOXyuoM+VhVqiT/s/EpaiXPS2nQFJttti3WQCOA3h1M9rP4hT8CyqNR466r8CwO3aDRwZj3toI9Vup7VJLYgbN3ZRrr2guO6kpozSabweJ/d8YZO38qcjDzT37pK/4IMkxvJcfpG9LHIA2c7yDvmC3fCted8ctFTsWoq7hJOLxADaIM1gT3trSv2TwgNwZayEH2sXvmz+Z9OLrgmUyRRG2sVkJqq/u2veFDi0aOMFpXqb12xf0KGyZe8btHHqoO/2iyAdMyC2FScHTqR1kslhM+lisvdhn/9Ox6SKvhNnyPvb5cJ19hm0f6nTXRyyyn5xFmZU26FbtezO0+fdK/k3JnXwHqfF6qmj05SX/npVroLu+c+5Cn68GTkwhdIxKasi34RKje7aexsptLLJkxOfDFPz7GThdTh8IcnGqFrrWrhfXjjSu2jK4OpLz7Z5HJxsfReqh+r+J3DbRpDZpDqw+GPTpy/aTPyzHHfDWt02aiDHyT0uC5y2P9Qre+fRhepbNl85Pys85cV3WtlislLYjiE1FTDDozz0uiG/DUEajRxujE6bDss3vscx6GvXSIXL2x+wem3avpbaLp37tu676k/3MheMBLTN4f929vbpffSa1c8IWTh4jgJxZBHecylnDKZ2kxffES0VKQ5r3ukryLCLsoZWat/tn53z479UgzdpvWkxpf1259zOFxTQZMzYD19i90tT529vVc/Wbn7Z3IeUnQiU1W77cTMA6LPORyupiK57ltLXw5P+XdfgR3HLcvyWHVjoowfWIjOJ2ya/WV7902Eap4GXffavO6aPhea0D0zUzSOa6zVMjuQY1wp43cfwxNlwqYZN2LOgk0bgEdGhMkXulmdX7yCPJXo+1RM/kOX6ShL3Nh5/XkWZw8kbVrN1NRaEvXjktK9c17n9IgbCH6Zi1ISE3JUlGCBUVJ2t6LgRJ3qupAAVvazTARxx4a2+es/4y5I6t5H3kDw6/BeinW5TUzJjONOZnDlZK1gHmaF9SQemppa69TMnUF6kvtIg4HO3I7f80fdiP4pde+XiSbkjPL8aNehCjMNG+sxKWqqy1LLMA7M8pnHhms4Klb0sRgvr+Pp1pX4JfpL01X6qe0JOeOR9NQoDpZWuSlqSrNp7PaN/bjTLWx7zV9zv0y3rsDvsdLBumZCjh2pmvih3Kn4WE0xm6Y962P5KLBpU+NVfw74VS5O7hQdTI4DrK2KzSABqIMb2j5MrKYU6+lolmrMCQtPvEHoc9CHbW9ZMUZCgaV6wTSqwEc1m9lIxWpqp1nP+VnFcoP9U+RyPh2m5z0tX8lEKXMLsyw18i96KelecCCqh1lsYjWVHnToF5tonnRQC4HbEuZTlJmuptIj/0KBpXvB5sZsNLhYvkVqqkpYTyFSK6YY3JQw68u5ulNYbqf73f4S/zltIEkael5u7z5HaiqRuHgWIvWcSXgPxDR2k3oi8KdNm+WamloZ+RcKLN1by/mTWv4lVFNpm9YzOUqbYvDzkHNcq6cCV5gCkLmipqrkHTZWxRZ3OPgvJ35NqKbSNo31+J4zCe9+CSccs5GMoGBwwng8kzbIthGYav2XXZaKYLPemi0mq8fUVNqmnZhYlmlTDL4bM6VQNn9qO5poCk9utMCkqKnQ52IIBZY2kAOzVJN8bKimkjatYPbyOZPw7pRT3Px1wm2upSs1WMdYUVMrgak588KQNpAUFB/t5y5wwAM1lbJpwsVPJiyAb8e0ftj8a7tm9ctXN5arqKnQQjKEAhPyJWHyUAVGK1BTKZt2yoKp/8+XhHc7xupjp+W1GcpMaf6EmsplB+3g1IOiAfKkNyxCWysGkolUGdyMBpYXNZWwafSuzMfTCQvgamg5pdF+zLLVcGDki+hqagiapXDCoagpNcfA3ppLcBg6ZSwiNblCy1JjGTdpKZtmyi25fJEp9kt46U8HjFH88B0dI8dEX+zMlRuCw43W1kFQcZxVTNyo6VGSa1bFNixSQ+GlMEWdqSndpv2RrxH9BFTroW0+2CIKo/54IJMVFxp79o2s2xBf1mZc9BiFIhMH4cKwACRJxsSLBjFRjlBgXL4ErMdXZzq+KqpNI4ni4SrzpKOycFkfXgksVeJnr+zpHX1RUrr9T9yEJ0RciBWelq8sAHkKFUV6lCROwotr5Z7v9Fcp/yTaYtQ80KsppXs57KK/d6f/QG/dGUyjku0TvckyL+iU6TJFSupDbX4jP604MgbvvWkkdkqIxkass/FfhHyFpfb2o627T1G3x3inb7Zpnv6k/LUH8fPYRRReK+1fZ2rKnH6RY5CQ6A1YYo03r8SWKd0WIzcfevPHaioID4kAZKim0qMkV66KnWd8ofhd9Bbx2FS+yPOlT1IV7m8dxQXVrOKa7iXmIl2F3cPcI7aWMs1dpJMVm/kicZgEcez15i+ywNEIwkNCwkI1tRLrFBIs5Cuq2Vz3uAhXU0ZdRnMVqkle0EEpxYRbBfNluVaa0GBa6HA0F/HwFE3yrlLXtlmQmFRKqZESFqqp0BgtCAlOGEgauXbHE7axWqonbRrxqosCfg071z3fV3Vd7e0Pt8hH5E8E1xqpYesYWz4z63Akrg3VVKDMjIRN4glc4JJ+91VJeKSOB/s5z5K7gLvqhX2Tfa2UBxGkUnL/Y7lVyxb5SDchFTfXhtts0dc6fW2gpnqpUCZFwtjpXZbsn3MJ1jWkkXV/s6RXtnT6ZrNOncFXWXDr3zllsg8z7jLeartsdY0O+6rLddPnMbBU80s1ZRquXU4GEmbD8Ev9kn63lGBVu5JE+b812Xdc1FT3NOtO/yqkZ0Z+hOzY/IavNKHBNSOZJ3cbapJ27Vqppg5Sl9XhRVJNVdlqEt4QVIwxlhkX/HQc/vS2P3X6I8AV1PHLanzY/eS+mCZs0pd7H7ddFMCspNLNL9RUHs9kGNxnGuTYCTXVpJSLkoQ3sJO9XcV9ifQX6+oX/DWlYpw6tvDrSrjaMDcjxURNeGpRUunm75maMgruwM6RuuvC3Vnm23TZahJeE1XMDCk1PqZUDP689QLBD7CLDISkTTehoZ4VUeVaflFSK83PBLmNXSkNX8chS0Y1hASb6nyEi+Efp7lwl+XvdfrvAn/Peo9uc6Iac3KPptH+MCW10vxMTZ2yaCZDQJ4zWZnS2kVIv3Ifsej2NKX/KPBPpL1Uy4aBMIpobz/a8FTBRHCl+Rc1tZNlWHhxHuQQIXQjX5N6TyHBbShP9aheBL4dFizWyWQTGo/Z+DmD+8qacd4ypPeF080/q6kpk8bRXBKNvJZMTb1JrUbJN/VcF5GERyqOxnEx+PaL9EIGFKxl9LmKs2fS2bMi/mO32WIeedD8HK+mzPOb5bBuZ3lsyvUxbcabq48TJC7Bo1FxiCndBKNagnW8BKbto8zHRQxyZpOcalhulhhGM3g1VWdR+p3SSSwz4XsVRVCbiU69rf8l4JcgDZCnJiUkdsbM3lp3eicUUSARpywd1HJqqoxdqS5RyZ4+1lp1Rjo1wL7dB3ZwNP9IDGKJJozTpgL3vo4i4VXisU5N5dFMBrUDuqgp4Xcj4+0+WQbcd8e6G4KzLbVcco23MLpecbOVHEczkJoyglUvx/TR3jNXU/QJGW93Titck1zujcnCBBpRdH1in03zJ4NapKaaTLhS68FR20WEUnoExvZduCZfTcJL3nf1WiMlRpin5VDa+RpaKKUHY+qbA5OrZW9MNU1kYT26vnqtG3vZs0O7DLOVnoyhq/e5davmY3nCY7asR9fXh3tKelK1HFgJt4NHxrpWtf9qNMeQLp1lK8vArWsdq6a65cBgupNX1xM8DpTYOc/y3RgFXFVEGwl85ao8gidC7FC7kYRXZivLwK3kYBoGDJm8DDXrx12bhKexkoMJXgueJ3J1Ep7CSg4meDFY7//6JLyY4YW24QIz46mOD7LevB4mmLcNWo+uj/9aO/BwTCctI0RoJt4tm9hMg4GObETXwetRanbtxK3ZG43vsow3R0dnN6Lr4PWgeGPgDFEq3ei/lZlOY08juQQEUEJUObIjfS6kTEnCo+SS4bdrCh4FEpmiGd3XnrQSWyZhScJDxhu4DpeDV5rlgI7WXeILb7QvkvE2XvzFW9fhaXAb3i+IlbmmG9Xql6EZhP2ta/E0jMJf4hl4rwO9VqtTGsGXGNsDmbz8vepvXZefxkTWxvDgaF+n/ver89Roy1Q/IeqM1c45lDeoD3h41AwwmnIKNQVW+SwLbTMSfdLE7mL0e6gpsMopiIZ4tAwwu9xHCTUFLHb9lnC+dB1G2BxaPk5Hmgtq6uWhpYn4Sndly87aue7hZiR6BliV+SUaoKZekcn+p664wbSS68RFCYJaPo6RpfMZaurV8ItKuYzARhMptmiwCzVlf8L7mINTdGhv/oeaegmCnWJneei8ENnR7L49UZE5o3DyxcOljuKJYr332FuoqedG27A0m+XB+ES5HM0mWzj7SeZKurqRt91Fqshc19GnAmrq+bBKaTQf31TL9nYYbMEszopvuQQZ0elIc/WiUDxRrJxVH9TUE0Fbu89KqTeHdlyU4hSbPPaJqOvm1RSFyWknLxnyjGes5stFUFMPT+wpEa05d8pW8/60wTqaKe0O2onS5HKJ8FQUmOrZAaiph2UySsmvQhxTmzIbE+DVlT3LxfK5MDn1DItpKRLNWG24JYSaelTsLJwpFCWxffXGBHh1sI4Nt/iJ0tZpn+YiUWDqwNVdAzX1mNDC+6P1h8hT2hvHKdiXc2MCfJ0pyzUwqzaHySnDcJHNyK8v+He+vTG4P6aL8BhPqQlPfLpGPsxrFCujuUOoTiTq5Hl2cJkobawhC08Ffr15zH75Wq8/FdwEv5sD2SXSEb0s4JUUQ1nPY2NZvD5TprVyycy86NA+2YtMBX59K102UlNt+rHgN4nGcY2+sPuQjqJgm0VLKWijuYE6CZ+mqZMDc7CWMLncfznw60+ByENN3QOjVUoRBzpZZGFGgNKt0tbzUHN6F8wTwopkTP2Vi+jYrqV7ZODXF4HgQk3dA20sTUZC3k90dpDusaqk1NFcNUywEA/W0baAs67jYXKaqe/G/6RfPy6XOIOdQ03dnkFIEkUn+W4OjXSP9diPIiBqmGBhF93mT8aFsOZOEkm9tb/Srzf9ymMbbjEKNXVjyN68pXcsq0RTq0pKW/ZTDRMshIN1vZExdoEUHZvlOZ1Dv75SNSzU1K1RrJagzFjaSaEqgXg0Vw8TjH3nPs3RdWuwrJJhTlsQ1yLZMaIk/fpdJE1v7znU1M1RrJaAuvFuVKTVdYAwUxauTthgoL/Y2NNdYLBO03J52CWcQ57m/7lm86XMYKPTd3sUqyWhLpcd6NCVlKaSSCb6OG1qsqe7LCQX9w3jWnb/5U/5AhixLUKDjU7f7VGsVgC1v0naTSgpddnPSGYsoz07RCeCpOA80J02PPUp/HqbrxACNXVzFKulFTGNl1BSauQyTsIzfYB2tGcnYbCMogw6gFFcy4U8+QtQRlfRraGmbo3qSAeQKzOklJS67Odutmg8Q2HGtPucSsXdNcchkgvKyMtK9gIoTzVATd0azWqF2JGZXfL1D83U2UrhUd+w1CC1EEUzRV6KEteag7Ify0VaxaGmbo063hYVKmxrJgruQjP11SS8KgtESMlumOdqHdJFCKipG6NZrRhrdlIvf2ymvpqEF7pTqjmuhVyXWaKrSmpKPQN+B8VqKZCKSOWrKH2vIFgZEkbXKVLB3Cktu8GvkZwv9Z6iIoYeC93eFsVqmaD2GBwiNfXfWeUbkvAoUnGcvybMsXX6J/+AlS1ywA3hVoulTTWyVG8VxKDe4juS8AJ3KlN1kM3Io0psWFZwQ8iR7qK0qUqWKp0fM2q3+I4kPBsgH/zXxDgR9RM686l7/tW3H5YmUzmIQjT4UaRszbck4Ul3apdwsYdoNSpwd8RJeBTU7kQho6RaMn7RcioGxUx9PQmPZNvbsu1xInC3LONt6c0cnLPdSH9n4TuS8FyHzl2zEdcC9wxZrY0dZk6ugcmH7uPzZaySvpiEZyDn2+VmjcnAO7h/9M4VZ5wd8zLLlJ0lr0vCs91Jd0zVQoNJVVmvCngEtpLwFiXlelxyhNewloQ3Tw10fUZ7GjGAZybVuZpZlJQbmTmGJRJJeHk402BRiF2Wv9ffUHlwj2x2rk5cYKiDGK54+IUkPK8Qp3+tNrhftjpXIxOEsxu8/S8uspGE9/Z+SM3CAc/GVhLeKTh/zKKRGW34ZUeSFE8NBM/PRtJAoKR8EuYoCuWxi99CKb0sG0l4oZJyQydyZMaopOEH6gYekvWkgUhJnV1aghiZOb2fquEH6gYeE8VqLcRK6rzMmQFAJU4asOtOd2d1iTJDZUYDf6Fq4DGZk/CCdaeb87KOIgBfgCZIKTt0VEklBcAqiSQ8E1kYmvUUBQA0wiQ8mmqO6CT4e1wSXo4hE/BNjBgyAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAK7i/zCa56YKZW5kc3RyZWFtCmVuZG9iagoxOSAwIG9iago8PAovVHlwZSAvWE9iamVjdAovU3VidHlwZSAvRm9ybQovQkJveCBbIDEwLjEgLTAuMDYxIDU4NS4yNSA4MTMuODQgXQovUmVzb3VyY2VzIDIwIDAgUgovR3JvdXAgPDwKL1MgL1RyYW5zcGFyZW5jeQovQ1MgL0RldmljZVJHQgovSyB0cnVlCj4+Ci9GaWx0ZXIgL0ZsYXRlRGVjb2RlCi9MZW5ndGggNDcKPj4Kc3RyZWFtCnicK1QwNTfVM1QwAEILQ2M9C1MFQwMQX8/A2FIhOZdL3zPXRMElXyGQCwC9AgjkCmVuZHN0cmVhbQplbmRvYmoKMjAgMCBvYmoKPDwKL0ZvbnQgMjEgMCBSCi9YT2JqZWN0IDw8Ci9JbTQgMTcgMCBSCi9UcjUgMTkgMCBSCj4+Ci9FeHRHU3RhdGUgPDwKL0VHUzYgNiAwIFIKPj4KL1Byb2NTZXQgWyAvUERGIC9UZXh0IC9JbWFnZUMgL0ltYWdlSSAvSW1hZ2VCIF0KPj4KZW5kb2JqCjIxIDAgb2JqCjw8Cj4+CmVuZG9iagp4cmVmCjAgMjIKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDE1IDAwMDAwIG4gCjAwMDAwMDAwNzQgMDAwMDAgbiAKMDAwMDAwMDExNCAwMDAwMCBuIAowMDAwMDAwMTYzIDAwMDAwIG4gCjAwMDAwMDA1ODUgMDAwMDAgbiAKMDAwMDAyNjY3OCAwMDAwMCBuIAowMDAwMDI2NzE1IDAwMDAwIG4gCjAwMDAwMjY4NjUgMDAwMDAgbiAKMDAwMDAyNzQxMyAwMDAwMCBuIAowMDAwMDI3OTk0IDAwMDAwIG4gCjAwMDAwMjgyMzUgMDAwMDAgbiAKMDAwMDAzMjc4NCAwMDAwMCBuIAowMDAwMDMyOTMyIDAwMDAwIG4gCjAwMDAwMzM0NTIgMDAwMDAgbiAKMDAwMDAzMzk3NyAwMDAwMCBuIAowMDAwMDM0MjEyIDAwMDAwIG4gCjAwMDAwMzgxMzMgMDAwMDAgbiAKMDAwMDAzOTc5NyAwMDAwMCBuIAowMDAwMDU5MjYxIDAwMDAwIG4gCjAwMDAwNTk1MTcgMDAwMDAgbiAKMDAwMDA1OTY2OCAwMDAwMCBuIAp0cmFpbGVyCjw8Ci9TaXplIDIyCi9Sb290IDMgMCBSCi9JbmZvIDIgMCBSCj4+CnN0YXJ0eHJlZgo1OTY5MAolJUVPRgo=",
    "source_account": {
        "account_branch": "0001",
        "account_digit": "4",
        "account_number": "00007",
        "financial_institution_compe_number": 329,
        "financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
        "owner_document_number": "32402502000135",
        "owner_document_number_formatted": "32.402.502/0001-35",
        "owner_name": "QI SCD S.A."
    },
    "source_subtype": "bank_slip_payment",
    "source_subtype_translation_ptbr": "Pagamento de Boleto",
    "transacted_at": "2024-08-07 00:36:03",
    "transacted_at_br": "2024-08-06 21:36:03",
    "transacted_at_br_formatted": "06/08/2024, 21:36:03",
    "transacted_at_formatted": "07/08/2024, 00:36:03",
    "transaction_amount": 274800.0,
    "transaction_amount_formatted": "R$ 274.800,00",
    "transaction_key": "940c487c-d944-473d-bbd3-0871d92a5225"
}
```

**Response Body: Comprovantes de pagamento de fatura de recolhimento**

```json
{
    "bank_slip": {
        "beneficiary": {
            "document_number": null,
            "name": "CPFL CIA PAULISTA FO"
        },
        "digitable_line": "836100000014389700403378033892445033101190122156",
        "expiration_date": null,
        "financial_institution_compe_number": null,
        "financial_institution_name": null,
        "payer": {
            "document_number": "03782617037",
            "document_number_formatted": "037.826.170-37",
            "name": "Beatriz Couto de Carvalho"
        },
        "payment_date": "2024-06-20",
        "payment_date_formatted": "20/06/2024",
        "payment_key": "c5a5aade-aba8-42aa-8dc4-566dfb6493d2",
        "tax_collection_info": null
    },
    "origin_key": "c5a5aade-aba8-42aa-8dc4-566dfb6493d2",
    "pdf_encoded_string": "JVBERi0xLjcKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvUGFnZXMKL0NvdW50IDEKL0tpZHMgWyA0IDAgUiBdCj4+CmVuZG9iagoyIDAgb2JqCjw8Ci9Qcm9kdWNlciAoUHlQREYyKQo+PgplbmRvYmoKMyAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMSAwIFIKPj4KZW5kb2JqCjQgMCBvYmoKPDwKL1R5cGUgL1BhZ2UKL01lZGlhQm94IFsgMCAwIDU5NS4yNzU1OTEgODQxLjg4OTc2NCBdCi9Db250ZW50cyA1IDAgUgovUmVzb3VyY2VzIDw8Ci9FeHRHU3RhdGUgPDwKL2ExLjAgPDwKL2NhIDEKPj4KL2ExIDw8Ci9jYSAxCj4+Ci9hMC43IDw8Ci9jYSAwLjcKPj4KL0VHUzYgNiAwIFIKPj4KL0ZvbnQgPDwKL1ZDQVRXUyA3IDAgUgovT0NITlVQIDEyIDAgUgo+PgovWE9iamVjdCA8PAovSW00IDE3IDAgUgovVHI1IDE5IDAgUgo+PgovUHJvY1NldCBbIC9JbWFnZUIgL1BERiAvSW1hZ2VJIC9UZXh0IC9JbWFnZUMgXQo+PgovVHJpbUJveCBbIDAgMCA1OTUuMjc1NTkxIDg0MS44ODk3NjQgXQovQmxlZWRCb3ggWyAwIDAgNTk1LjI3NTU5MSA4NDEuODg5NzY0IF0KL0Fubm90cyBbIF0KL1BhcmVudCAxIDAgUgo+PgplbmRvYmoKNSAwIG9iago8PAovTGVuZ3RoIDI1NjU1Cj4+CnN0cmVhbQpxCjEgMCAwIC0xIDAgODQxLjg4OTc2NCBjbQpxCjAuNzUgMCAwIDAuNzUgMCAwIGNtCnEKcQpxCnEKcQpxCjAgMCBtCjc5My43MDA3ODcgMCBsCjc5My43MDA3ODcgMCA3OTMuNzAwNzg3IDAgNzkzLjcwMDc4NyAwIGMKNzkzLjcwMDc4NyAxNDYuNDY4NzUgbAo3OTMuNzAwNzg3IDE1MS45Njg3NSA3ODkuMjAwNzg3IDE1Ni40Njg3NSA3ODMuNzAwNzg3IDE1Ni40Njg3NSBjCjEwIDE1Ni40Njg3NSBsCjQuNSAxNTYuNDY4NzUgMCAxNTEuOTY4NzUgMCAxNDYuNDY4NzUgYwowIDAgbAowIDAgMCAwIDAgMCBjClcKbgpxCjAuMDk4MDM5IDAuMTQxMTc2IDAuNDk0MTE4IHJnCi9hMS4wIGdzCjAgMCA3OTMuNzAwNzg3IDE1Ni40Njg3NSByZQpXCm4KMCAwIDc5My43MDA3ODcgMTU2LjQ2ODc1IHJlCmYKUQpRCnEKNzkzLjcwMDc4NyAwIG0KMCAwIGwKMCA1IGwKNzkzLjcwMDc4NyA1IGwKVyoKbgoxIDAuMjUwOTggMC41MDE5NjEgcmcKL2ExLjAgZ3MKMCA1IG0KNzkzLjcwMDc4NyA1IGwKNzkzLjcwMDc4NyA1IDc5My43MDA3ODcgNSA3OTMuNzAwNzg3IDUgYwo3OTMuNzAwNzg3IDE0Ni40Njg3NSBsCjc5My43MDA3ODcgMTUxLjk2ODc1IDc4OS4yMDA3ODcgMTU2LjQ2ODc1IDc4My43MDA3ODcgMTU2LjQ2ODc1IGMKMTAgMTU2LjQ2ODc1IGwKNC41IDE1Ni40Njg3NSAwIDE1MS45Njg3NSAwIDE0Ni40Njg3NSBjCjAgNSBsCjAgNSAwIDUgMCA1IGMKMCAwIG0KNzkzLjcwMDc4NyAwIGwKNzkzLjcwMDc4NyAwIDc5My43MDA3ODcgMCA3OTMuNzAwNzg3IDAgYwo3OTMuNzAwNzg3IDE0Ni40Njg3NSBsCjc5My43MDA3ODcgMTUxLjk2ODc1IDc4OS4yMDA3ODcgMTU2LjQ2ODc1IDc4My43MDA3ODcgMTU2LjQ2ODc1IGMKMTAgMTU2LjQ2ODc1IGwKNC41IDE1Ni40Njg3NSAwIDE1MS45Njg3NSAwIDE0Ni40Njg3NSBjCjAgMCBsCjAgMCAwIDAgMCAwIGMKZioKUQpRCnEKcQowIDAgMCByZwovYTEuMCBncwpCVApFVAoxIDEgMSByZwpCVAoxIDAgMCAtMSAyNTIuNjQ4MjQ1IDgxLjQ4MTQ0NSBUbQovVkNBVFdTIDE4IFRmClsgPDAwMjYwMDUyMDA1MDAwNTMwMDU1MDA1MjAwNTkwMDQ0MDA1MTAwNTcwMDQ4MDAwMzAwNDcwMDQ4MDAwMzAwNTMwMDQ0MDA0YTAwNDQwMDUwMDA0ODAwNTEwMDU3MDA1Mj4gXSBUSgoxIDAgMCAtMSAzNjIuMjY4MzYyIDEwNS44NjUyMzQgVG0KL09DSE5VUCAxMiBUZgpbIDwwMDE1MDAxMzAwMTIwMDEzMDAxOTAwMTIwMDE1MDAxMzAwMTUwMDE3PiBdIFRKCkVUClEKUQpxCnEKMzU4LjM1MDM5NCAyNSA3NyAyMiByZQpXCm4KcQovYTEgZ3MKMSAwIDAgMSAzNTguMzUwMzk0IDI1IGNtCnEKcQoxIDAgMCAxIDAgMCBjbQoxIDAgMCAxIDAgMCBjbQpxCjAgMCBtCjMuNTYzNzIgNi4yNTAwMSBtCjMuODgyODcgNi4yNTA4OSA0LjE5NDYxIDYuMzUyNDMgNC40NTk1NSA2LjU0MTgyIGMKNC43MjQ0OSA2LjczMTIgNC45MzA3NCA2Ljk5OTkyIDUuMDUyMjMgNy4zMTQwMSBjCjUuMTczNzMgNy42MjgxMSA1LjIwNTAyIDcuOTczNDkgNS4xNDIxNSA4LjMwNjUxIGMKNS4wNzkyOCA4LjYzOTUzIDQuOTI1MDcgOC45NDUyMyA0LjY5OTAxIDkuMTg1MDEgYwo0LjQ3Mjk2IDkuNDI0NzggNC4xODUxOSA5LjU4Nzg1IDMuODcyMDggOS42NTM2MSBjCjMuNTU4OTcgOS43MTkzOCAzLjIzNDU4IDkuNjg0ODkgMi45Mzk4OCA5LjU1NDQ5IGMKMi42NDUxOSA5LjQyNDEgMi4zOTM0MiA5LjIwMzY2IDIuMjE2NCA4LjkyMTAzIGMKMi4wMzkzNyA4LjYzODQgMS45NDUwNCA4LjMwNjI2IDEuOTQ1MzEgNy45NjY1OSBjCjEuOTQ1MzEgNy43NDA2NiAxLjk4NzIxIDcuNTE2OTYgMi4wNjg2MSA3LjMwODMxIGMKMi4xNTAwMSA3LjA5OTY2IDIuMjY5MzEgNi45MTAxNiAyLjQxOTY3IDYuNzUwNjkgYwoyLjU3MDAzIDYuNTkxMjEgMi43NDg0OCA2LjQ2NDg5IDIuOTQ0OCA2LjM3ODk3IGMKMy4xNDExMyA2LjI5MzA2IDMuMzUxNDUgNi4yNDkyMyAzLjU2MzcyIDYuMjUwMDEgYwpoCjE2LjkgMTQuOTMxMSBtCjE0Ljk5MzYgMTMuMjI0OSAxMy4xNzM0IDEwLjYwNzkgMTEuNTc0NCAxMi40Mjk2IGMKMTAuMzY5MyAxMy44MDQgMTEuNjAzNyAxNC44NTcxIDEyLjI0MSAxNS41MDczIGMKMTMuOTAxMiAxNy4yMzcyIDE2LjA3NjIgMTkuNTY4NCAxNy44NjAyIDIxLjE0NTggYwoxOC40NTU4IDIxLjY3MTYgMTguNzcwMyAyMS44MDYzIDE5LjIwNTkgMjEuOTEgYwoyMC41MjM3IDIyLjIxOTYgMjEuMjY2OCAyMS4wMjE0IDIxLjAxNDkgMTkuODM2NSBjCjIwLjc3ODQgMTguNzAzNSAxOS41ODcyIDE3LjU4MDggMTkuMzMzOSAxNy40NDE2IGMKMjAuMjU3OSAxNi4wNzUgMjAuODUxOSAxNC40ODc2IDIxLjA2MzYgMTIuODE5MSBjCjIxLjM2MzggMTAuNjA3NSAyMS4wMDQxIDguMzUxNCAyMC4wMzUzIDYuMzY4OTkgYwoxOC42NDM3IDMuNTU0OTIgMTYuMTM4OCAxLjc1MjQ0IDE0LjIxOTggMS4xMzc3OSBjCjEzLjE4MTcgMC44MDQ1NDYgMTIuMjI0MyAwLjkyMzAzMyAxMS43NTEyIDEuMjg1OSBjCjExLjE4NDggMS43MTM5MyAxMC44OTk1IDIuNzMyOTIgMTEuMzY1NyAzLjU1Nzg5IGMKMTEuNDQ1OSAzLjcwNTE5IDExLjU1MzQgMy44MzM2MyAxMS42ODE2IDMuOTM1NDYgYwoxMS44MDk4IDQuMDM3MjkgMTEuOTU2MSA0LjExMDM4IDEyLjExMTYgNC4xNTAzMiBjCjEyLjc4MjMgNC4zMjA2NSAxNC4wOTE4IDQuNjgyMDMgMTUuMjE0OCA1LjYzMTQxIGMKMTYuNDU1OCA2LjY0NzEyIDE3LjMyNDEgOC4wOTI2IDE3LjY2OTYgOS43MTc3MiBjCjE4LjA1NSAxMS40NjM5IDE3LjcyOCAxMy42MTQ1IDE2LjkwMTQgMTQuOTMxMSBjCjIuMzMzMTcgMTEuODMwOCBtCjEuMzg5NjggMTIuMjQ5OSAxLjI0NDk2IDEzLjE0NDUgMS40MzY5OSAxNC4wODIgYwoxLjc0NTkyIDE1LjU5MTIgMi45NTI0MyAxNy42OTI5IDMuODgyIDE4LjY5MTEgYwo1LjI3MzU4IDIwLjE3MjIgNi45NDM0OCAyMS4yNzg2IDguOTA3IDIxLjcyMTQgYwoxMC41MTE1IDIyLjA4MjggMTIuMjcwNSAyMi4wOTE3IDEzLjIzMDYgMjEuNzUyNiBjCjE0LjYyMjIgMjEuMjYwOCAxNC44NjAyIDE4LjQ2OSAxMi41NTQzIDE4LjQyOSBjCjEyLjE4MjggMTguNDI5IDExLjc2NjcgMTguNDU1NyAxMS4zMjU2IDE4LjQ3NDkgYwoxMC40MzM2IDE4LjUxMDYgOS41NDM4NiAxOC4zNTc2IDguNzA3ODMgMTguMDI0OCBjCjcuODcxNzkgMTcuNjkyIDcuMTA2MDkgMTcuMTg2MSA2LjQ1NTAzIDE2LjUzNjIgYwo1LjkxNCAxNi4wMTQgNS40NzEwNSAxNS4zODczIDUuMTQ5NzMgMTQuNjg5MyBjCjQuOTQ2MjEgMTQuMjQ5NCA0Ljc2NTUgMTMuNzk4IDQuNjA4NDEgMTMuMzM3IGMKNC41MjYzIDEzLjA3MzQgNC41Mzg4MyAxMi44MTg2IDQuMzgwMTkgMTIuNTQwMiBjCjQuMTcyNDMgMTIuMTg0IDMuODUzMDIgMTEuOTE3NCAzLjQ3ODQzIDExLjc4NzUgYwozLjEwMzg0IDExLjY1NzcgMi42OTgxOCAxMS42NzMgMi4zMzMxNyAxMS44MzA4IGMKaAowLjMwOTgwNCAwLjggMC45Mjk0MTIgcmcKL2ExLjAgZ3MKMSB3CjAgSgowIGoKNCBNCmYqClEKcQowIDAgbQo4Ljk4NDczIDcuMDM3MTEgbQo5LjQ4MjY4IDcuMDM2ODIgOS45Njk1MiA3LjE5MzcxIDEwLjM4MzcgNy40ODc5MyBjCjEwLjc5NzggNy43ODIxNiAxMS4xMjA3IDguMjAwNSAxMS4zMTE1IDguNjkwMDUgYwoxMS41MDIyIDkuMTc5NiAxMS41NTIzIDkuNzE4MzYgMTEuNDU1MyAxMC4yMzgyIGMKMTEuMzU4MyAxMC43NTggMTEuMTE4NyAxMS4yMzU2IDEwLjc2NjcgMTEuNjEwNCBjCjEwLjQxNDcgMTEuOTg1MyA5Ljk2NjExIDEyLjI0MDYgOS40Nzc3NSAxMi4zNDQxIGMKOC45ODkzOSAxMi40NDc2IDguNDgzMTYgMTIuMzk0NiA4LjAyMzA5IDEyLjE5MTkgYwo3LjU2MzAxIDExLjk4OTEgNy4xNjk3NyAxMS42NDU3IDYuODkzMSAxMS4yMDUxIGMKNi42MTY0MyAxMC43NjQ0IDYuNDY4NzUgMTAuMjQ2NCA2LjQ2ODc1IDkuNzE2MzkgYwo2LjQ2ODc1IDkuMDA2MDYgNi43MzM3OCA4LjMyNDggNy4yMDU1OCA3LjgyMjM4IGMKNy42NzczOCA3LjMxOTk2IDguMzE3MzIgNy4wMzc1IDguOTg0NzMgNy4wMzcxMSBjCmgKNi41MTA5NiAwIG0KNi44OTkwMyAwIDcuMjc4MzkgMC4xMjI0NzkgNy42MDEwNiAwLjM1MTk0OCBjCjcuOTIzNzMgMC41ODE0MTYgOC4xNzUyMiAwLjkwNzU2OCA4LjMyMzczIDEuMjg5MTYgYwo4LjQ3MjI0IDEuNjcwNzUgOC41MTEwOSAyLjA5MDY1IDguNDM1MzkgMi40OTU3NCBjCjguMzU5NjggMi45MDA4NCA4LjE3MjggMy4yNzI5NSA3Ljg5ODM5IDMuNTY1IGMKNy42MjM5OCAzLjg1NzA2IDcuMjc0MzcgNC4wNTU5NiA2Ljg5Mzc1IDQuMTM2NTQgYwo2LjUxMzEzIDQuMjE3MTEgNi4xMTg2MiA0LjE3NTc2IDUuNzYwMDggNC4wMTc3IGMKNS40MDE1NSAzLjg1OTY0IDUuMDk1MTEgMy41OTE5NyA0Ljg3OTUxIDMuMjQ4NTQgYwo0LjY2MzkxIDIuOTA1MTIgNC41NDg4MyAyLjUwMTM2IDQuNTQ4ODMgMi4wODgzMyBjCjQuNTQ4ODMgMS41MzQ0NyA0Ljc1NTU1IDEuMDAzMyA1LjEyMzUyIDAuNjExNjU3IGMKNS40OTE0OSAwLjIyMDAxOSA1Ljk5MDU3IDAgNi41MTA5NiAwIGMKaAoxLjIyNTk4IDIuMzM4OSBtCjEuNDcwNTIgMi4zMzcxNCAxLjcxMDA0IDIuNDEyNzMgMS45MTQxNSAyLjU1NjA3IGMKMi4xMTgyNiAyLjY5OTQyIDIuMjc3NzYgMi45MDQwNiAyLjM3MjQzIDMuMTQ0MDMgYwoyLjQ2NzA5IDMuMzg0MDEgMi40OTI2NSAzLjY0ODUxIDIuNDQ1ODYgMy45MDM5NyBjCjIuMzk5MDYgNC4xNTk0MyAyLjI4MjAzIDQuMzk0MzQgMi4xMDk2IDQuNTc4OSBjCjEuOTM3MTggNC43NjM0NiAxLjcxNzEzIDQuODg5MzUgMS40NzczNyA0Ljk0MDYgYwoxLjIzNzYyIDQuOTkxODQgMC45ODg5NjUgNC45NjYxNCAwLjc2Mjk1NyA0Ljg2Njc0IGMKMC41MzY5NSA0Ljc2NzM1IDAuMzQzNzc1IDQuNTk4NzUgMC4yMDc5MzkgNC4zODIzMiBjCjAuMDcyMTA0IDQuMTY1OSAtMC4wMDAyNjkgMy45MTE0MSAwLjAwMDAwMSAzLjY1MTE0IGMKMC4wMDAwMDEgMy4zMDMxMSAwLjEyOTg5OSAyLjk2OTM0IDAuMzYxMTIxIDIuNzIzMjUgYwowLjU5MjM0MiAyLjQ3NzE1IDAuOTA1OTQ1IDIuMzM4OSAxLjIzMjk0IDIuMzM4OSBjCjAuMzA5ODA0IDAuOCAwLjkyOTQxMiByZwovYTEuMCBncwoxIHcKMCBKCjAgago0IE0KZioKUQpxCjAgMCBtCjYxLjg4ODkgMTQuMTA4NCBtCjYxLjQyOSAxNC4xMTc3IDYwLjk2OTcgMTQuMDY4IDYwLjUyMSAxMy45NjAzIGMKNjAuMTk3MiAxMy44ODU5IDU5Ljg5NjIgMTMuNzI2IDU5LjY0NTcgMTMuNDk1MiBjCjU5LjQxOTIgMTMuMjY3OCA1OS4yNTggMTIuOTc2NiA1OS4xODA5IDEyLjY1NTQgYwo1OS4wODA2IDEyLjIzOSA1OS4wMzM3IDExLjgxIDU5LjA0MTggMTEuMzgwMiBjCjU5LjA0MTggOC44ODYwOCBsCjU5LjAzNDUgOC40NTgyNSA1OS4wODEzIDguMDMxMzMgNTkuMTgwOSA3LjYxNjc5IGMKNTkuMjU3IDcuMjkzOTYgNTkuNDE4MyA3LjAwMTAzIDU5LjY0NTcgNi43NzI1NyBjCjU5Ljg5NjIgNi41NDE4MSA2MC4xOTcyIDYuMzgxODcgNjAuNTIxIDYuMzA3NTEgYwo2MC45Njk3IDYuMTk5NzQgNjEuNDI5IDYuMTUwMDEgNjEuODg4OSA2LjE1OTQgYwo2Ny4wNjU2IDYuMTU5NCBsCjY3LjA2NTYgNy42ODY0IGwKNjEuOTY1NSA3LjY4NjQgbAo2MS43NTQyIDcuNjgxNDYgNjEuNTQzMSA3LjcwMjgzIDYxLjMzNjUgNy43NTAwOCBjCjYxLjE5MDkgNy43ODIyNiA2MS4wNTY2IDcuODU2NTcgNjAuOTQ4MiA3Ljk2NDg0IGMKNjAuODQ3OCA4LjA3NjQ2IDYwLjc3OTIgOC4yMTYxOCA2MC43NTA2IDguMzY3NyBjCjYwLjcxMTIgOC41NjgzMSA2MC42OTMgOC43NzI5OSA2MC42OTY0IDguOTc3OSBjCjYwLjY5NjQgMTEuMzA3NyBsCjYwLjY5MjUgMTEuNTE1IDYwLjcxMDcgMTEuNzIyMiA2MC43NTA2IDExLjkyNTMgYwo2MC43ODAyIDEyLjA3NDMgNjAuODQ4NyAxMi4yMTEzIDYwLjk0ODIgMTIuMzIwNyBjCjYxLjA1NzUgMTIuNDMwMSA2MS4xOTQzIDEyLjUwMzIgNjEuMzQyIDEyLjUzMSBjCjYxLjU1MTEgMTIuNTczNSA2MS43NjM4IDEyLjU5MjggNjEuOTc2NiAxMi41ODg4IGMKNjcuMDY1NiAxMi41ODg4IGwKNjcuMDY1NiAxNC4xMDI1IGwKNjEuODg4OSAxNC4xMDg0IGwKaAo1Mi44MTcyIDE0LjEwODQgbQo1Mi4zNTczIDE0LjExNzcgNTEuODk4IDE0LjA2OCA1MS40NDkzIDEzLjk2MDMgYwo1MS4xMjU1IDEzLjg4NTkgNTAuODI0NCAxMy43MjYgNTAuNTc0IDEzLjQ5NTIgYwo1MC4zNDc1IDEzLjI2NzggNTAuMTg2MyAxMi45NzY2IDUwLjEwOTIgMTIuNjU1NCBjCjUwLjAwODggMTIuMjM5IDQ5Ljk2MiAxMS44MSA0OS45NyAxMS4zODAyIGMKNDkuOTcgOC44ODYwOCBsCjQ5Ljk2MjggOC40NTgyNSA1MC4wMDk2IDguMDMxMzMgNTAuMTA5MiA3LjYxNjc5IGMKNTAuMTg1MyA3LjI5Mzk2IDUwLjM0NjYgNy4wMDEwMyA1MC41NzQgNi43NzI1NyBjCjUwLjgyNDQgNi41NDE4MSA1MS4xMjU1IDYuMzgxODcgNTEuNDQ5MyA2LjMwNzUxIGMKNTEuODk4IDYuMTk5NzQgNTIuMzU3MyA2LjE1MDAxIDUyLjgxNzIgNi4xNTk0IGMKNTQuNjU1NSA2LjE1OTQgbAo1NC42NTU1IDcuNjYyNyBsCjUyLjgxNzIgNy42NjI3IGwKNTIuNjE4OCA3LjY1NzYxIDUyLjQyMDYgNy42NzkwMSA1Mi4yMjcyIDcuNzI2MzkgYwo1Mi4wOTAzIDcuNzU5ODIgNTEuOTYzOCA3LjgzMDIxIDUxLjg1OTggNy45MzA3OCBjCjUxLjc2NDYgOC4wMzI0NCA1MS42OTk3IDguMTYxNzcgNTEuNjczMyA4LjMwMjUzIGMKNTEuNjM4NyA4LjQ5NDc4IDUxLjYyMzMgOC42OTAzOCA1MS42Mjc0IDguODg2MDggYwo1MS42Mjc0IDkuNDIyMjMgbAo1Ny45ODU1IDkuNDIyMjMgbAo1Ny45ODU1IDEwLjgzMjIgbAo1MS42Mjc0IDEwLjgzMjIgbAo1MS42Mjc0IDExLjM5MDYgbAo1MS42MjQxIDExLjU4OTMgNTEuNjQwNCAxMS43ODc5IDUxLjY3NjEgMTEuOTgzIGMKNTEuNzAxOCAxMi4xMjMyIDUxLjc2NDUgMTIuMjUyNyA1MS44NTcgMTIuMzU2MyBjCjUxLjk1OTIgMTIuNDU3MiA1Mi4wODY5IDEyLjUyNDEgNTIuMjI0NCAxMi41NDg4IGMKNTIuNDIwOSAxMi41ODY4IDUyLjYyMDMgMTIuNjA0MiA1Mi44MiAxMi42MDA2IGMKNTguMDI4NyAxMi42MDA2IGwKNTguMDI4NyAxNC4xMDI1IGwKNTIuODE3MiAxNC4xMDg0IGwKaAo0NC4zNTkyIDE0LjEwODQgbQo0NC4zNTkyIDcuNjkyMzIgbAo0MS4yMjk1IDcuNjkyMzIgbAo0MS4yMjk1IDYuMTY1MzIgbAo0OS4xNjE1IDYuMTY1MzIgbAo0OS4xNjE1IDcuNjkyMzIgbAo0Ni4wMzMzIDcuNjkyMzIgbAo0Ni4wMzMzIDE0LjEwODQgbAo0NC4zNTkyIDE0LjEwODQgbApoCjM0LjMzOTggNi4xNjUzMiBtCjM2LjAwOTcgNi4xNjUzMiBsCjM2LjAwOTcgMTQuMTA4NCBsCjM0LjMzOTggMTQuMTA4NCBsCjM0LjMzOTggNi4xNjUzMiBsCmgKMzEuNDMgOC45NzkzOSBtCjMxLjQzNCA4Ljc3MjA5IDMxLjQxMzQgOC41NjUwOCAzMS4zNjg4IDguMzYzMjUgYwozMS4zMzYzIDguMjE0MDQgMzEuMjY2NiA4LjA3NjkxIDMxLjE2NyA3Ljk2NjMyIGMKMzEuMDU5MiA3Ljg1ODM1IDMwLjkyNDQgNy43ODU4MyAzMC43Nzg3IDcuNzU3NDkgYwozMC41Nzg1IDcuNzE1NCAzMC4zNzQ3IDcuNjk2MDMgMzAuMTcwNiA3LjY5OTczIGMKMjcuNDg0OSA3LjY5OTczIGwKMjcuMjcwMiA3LjY5NTA5IDI3LjA1NTYgNy43MTQ0NSAyNi44NDQ3IDcuNzU3NDkgYwoyNi42OTkxIDcuNzg1ODMgMjYuNTY0MyA3Ljg1ODM1IDI2LjQ1NjUgNy45NjYzMiBjCjI2LjM1NzkgOC4wNzYyMSAyNi4yOTEyIDguMjE0MDMgMjYuMjY0NSA4LjM2MzI1IGMKMjYuMjI4OSA4LjU2NjM4IDI2LjIxMjUgOC43NzI3OSAyNi4yMTU3IDguOTc5MzkgYwoyNi4yMTU3IDExLjAwNyBsCjI2LjIxMjggMTEuMjY3OCAyNi4yMjU0IDExLjUyODQgMjYuMjUzMyAxMS43ODc1IGMKMjYuMjY4NyAxMS45NTk4IDI2LjMyNzQgMTIuMTI0NSAyNi40MjMxIDEyLjI2NDQgYwoyNi41MjE2IDEyLjM4NzcgMjYuNjU2NSAxMi40NzE4IDI2LjgwNTggMTIuNTAyOSBjCjI3LjAyOTEgMTIuNTUxOCAyNy4yNTY5IDEyLjU3MzYgMjcuNDg0OSAxMi41NjgxIGMKMzAuMTc2MiAxMi41NjgxIGwKMzAuMzggMTIuNTcxNSAzMC41ODM3IDEyLjU1MzYgMzAuNzg0MyAxMi41MTQ3IGMKMzAuOTI4NSAxMi40OTQxIDMxLjA2MyAxMi40MjU4IDMxLjE2ODggMTIuMzE5NSBjCjMxLjI3NDcgMTIuMjEzMiAzMS4zNDY1IDEyLjA3NDMgMzEuMzc0MyAxMS45MjIzIGMKMzEuNDE5MSAxMS43MTQ1IDMxLjQzOTcgMTEuNTAxNiAzMS40MzU2IDExLjI4ODQgYwozMS40MyA4Ljk3OTM5IGwKaAozMS42MTA5IDE1LjI1NDcgbQozMC41MzggMTQuMDMxNCBsCjI3LjQxMzkgMTQuMDMxNCBsCjI2Ljk1MSAxNC4wNDA3IDI2LjQ4ODYgMTMuOTk2IDI2LjAzNDggMTMuODk4MSBjCjI1LjcxMjEgMTMuODMyMyAyNS40MTA3IDEzLjY3OTMgMjUuMTU5NSAxMy40NTM3IGMKMjQuOTMzMyAxMy4yMzE0IDI0Ljc3MiAxMi45NDQ1IDI0LjY5NDggMTIuNjI3MyBjCjI0LjU5NDMgMTIuMjEyOSAyNC41NDc0IDExLjc4NTkgMjQuNTU1NiAxMS4zNTggYwoyNC41NTU2IDguODg2MDggbAoyNC41NDgzIDguNDU4MjUgMjQuNTk1MSA4LjAzMTMzIDI0LjY5NDggNy42MTY3OSBjCjI0Ljc3MDkgNy4yOTM5NiAyNC45MzIxIDcuMDAxMDMgMjUuMTU5NSA2Ljc3MjU3IGMKMjUuNDEgNi41NDE4MSAyNS43MTEgNi4zODE4NyAyNi4wMzQ4IDYuMzA3NTEgYwoyNi40ODczIDYuMTk5NDEgMjYuOTUwMyA2LjE0OTY4IDI3LjQxMzkgNi4xNTk0IGMKMzAuMjQ4NiA2LjE1OTQgbAozMC43MTE3IDYuMTQ5NjcgMzEuMTc0MyA2LjE5OTQgMzEuNjI2MiA2LjMwNzUxIGMKMzEuOTUwMSA2LjM4MTU3IDMyLjI1MTIgNi41NDE1NCAzMi41MDE1IDYuNzcyNTcgYwozMi43Mjk0IDcuMDAwODkgMzIuODkxMSA3LjI5MzgyIDMyLjk2NzcgNy42MTY3OSBjCjMzLjA2NjYgOC4wMzE0NyAzMy4xMTM0IDguNDU4MjkgMzMuMTA2OSA4Ljg4NjA4IGMKMzMuMTA2OSAxMS4zNDQ3IGwKMzMuMTIwMyAxMS44Mjc5IDMzLjA1NzMgMTIuMzEgMzIuOTIwNCAxMi43NzEgYwozMi44MDIyIDEzLjEzMjQgMzIuNTY1NSAxMy40MzYzIDMyLjI1MzggMTMuNjI3IGMKMzMuNjU2NSAxNS4yNTQ3IGwKMzEuNjEwOSAxNS4yNTQ3IGwKaAo3NS4zNDc1IDEyLjE1OTggbQo3NS4zNDc1IDEwLjk2MDEgbAo2OS44NzU4IDEwLjk2MDEgbAo2OS44NzU4IDE0LjEyODEgbAo2OC4yMTI5IDE0LjEyODEgbAo2OC4yMTI5IDYuMTgzNTkgbAo2OS44NzU4IDYuMTgzNTkgbAo2OS44NzU4IDkuNDIyNzMgbAo3NS4zNDc1IDkuNDIyNzMgbAo3NS4zNDc1IDYuMTgzNTkgbAo3Ni45OTkzIDYuMTgzNTkgbAo3Ni45OTkzIDEyLjE1OTggbAo3NS4zNDc1IDEyLjE1OTggbApoCjc2Ljk5OTggMTIuNjg4NSBtCjc1LjM1MzUgMTIuNjg4NSBsCjc1LjM1MzUgMTQuMTUxOCBsCjc2Ljk5OTggMTQuMTUxOCBsCjc2Ljk5OTggMTIuNjg4NSBsCmgKMC4zMDk4MDQgMC44IDAuOTI5NDEyIHJnCi9hMS4wIGdzCjEgdwowIEoKMCBqCjQgTQpmClEKMSB3CjAgSgowIGoKNCBNCm4KUQpRClEKUQpRCnEKcQozNzQuODUwMzk0IDEzMy42OTUzMTIgNDQgNDQgcmUKVwpuCnEKL2ExIGdzCjEgMCAwIDEgMzc0Ljg1MDM5NCAxMzMuNjk1MzEyIGNtCnEKcQoxIDAgMCAxIDAgMCBjbQoxIDAgMCAxIDAgMCBjbQpxCjQzLjIgMjEuNiBtCjQzLjIgMzMuNzg2NDk1IDMzLjc4NjQ5NSA0My4yIDIxLjYgNDMuMiBjCjkuNDEzNTA1IDQzLjIgMCAzMy43ODY0OTUgMCAyMS42IGMKMCA5LjQxMzUwNSA5LjQxMzUwNSAwIDIxLjYgMCBjCjMzLjc4NjQ5NSAwIDQzLjIgOS40MTM1MDUgNDMuMiAyMS42IGMKaAoxIDAuMjUwOTggMC41MDE5NjEgcmcKL2ExLjAgZ3MKMSB3CjAgSgowIGoKNCBNCmYKUQpxCjAgMCBtCjIyLjY5NSAyMC41ODUgbQoyMC41MDUgMjAuNTg1IGwKMTkuMjYwODI4IDIwLjU4NzIxNyAxOC4yNDk1MTEgMTkuNTgyMTYyIDE4LjI0NCAxOC4zMzggYwoxOC4yNTAwNiAxNy4wOTQyMjkgMTkuMjYxMjE2IDE2LjA4OTc4MSAyMC41MDUgMTYuMDkyIGMKMjQuODg0IDE2LjA5MiBsCjI1LjQ0OCAxNi4wOTIgMjUuOTA1IDE1LjYzNyAyNS45MDUgMTUuMDc3IGMKMjUuOTA1IDE0LjUxNyAyNS40NDggMTQuMDYyIDI0Ljg4NCAxNC4wNjIgYwoyMi42MjIgMTQuMDYyIGwKMjIuNjIyIDExLjgxNSBsCjIyLjYyMiAxMS4yNTUgMjIuMTY0IDEwLjggMjEuNiAxMC44IGMKMjEuMDM2IDEwLjggMjAuNTc4IDExLjI1NCAyMC41NzggMTEuODE1IGMKMjAuNTc4IDE0LjA2MiBsCjIwLjUwNiAxNC4wNjIgbAoxOC4xMzEgMTQuMDYyIDE2LjIgMTUuOTggMTYuMiAxOC4zMzggYwoxNi4yIDIwLjY5NiAxOC4xMzEgMjIuNjE1IDIwLjUwNiAyMi42MTUgYwoyMi42OTUgMjIuNjE1IGwKMjMuOTM5MTcyIDIyLjYxMjc4MyAyNC45NTA0ODkgMjMuNjE3ODM4IDI0Ljk1NiAyNC44NjIgYwoyNC45NDk5NCAyNi4xMDU3NzEgMjMuOTM4Nzg0IDI3LjExMDIxOSAyMi42OTUgMjcuMTA4IGMKMTguMzE3IDI3LjEwOCBsCjE3Ljc1MiAyNy4xMDggMTcuMjk1IDI3LjU2MyAxNy4yOTUgMjguMTIzIGMKMTcuMjk1IDI4LjY4MyAxNy43NTIgMjkuMTM4IDE4LjMxNiAyOS4xMzggYwoyMC41NzggMjkuMTM4IGwKMjAuNTc4IDMxLjM4NSBsCjIwLjU3OCAzMS45NDUgMjEuMDM2IDMyLjQgMjEuNiAzMi40IGMKMjIuMTY0IDMyLjQgMjIuNjIyIDMxLjk0NiAyMi42MjIgMzEuMzg1IGMKMjIuNjIyIDI5LjEzOCBsCjIyLjY5NSAyOS4xMzggbAoyNS4wNjkgMjkuMTM4IDI3IDI3LjIyIDI3IDI0Ljg2MiBjCjI3IDIyLjUwNCAyNS4wNjkgMjAuNTg1IDIyLjY5NSAyMC41ODUgYwpoCjEgMSAxIHJnCi9hMS4wIGdzCjEgdwowIEoKMCBqCjQgTQpmClEKMSB3CjAgSgowIGoKNCBNCm4KUQpRClEKUQpRCnEKcQowLjQxMTc2NSAwLjQ0NzA1OSAwLjQ5MDE5NiByZwovYTEuMCBncwpCVAoxIDAgMCAtMSAyNzguMDM2OTE3IDIxNC42MjMwNDcgVG0KL09DSE5VUCAxMiBUZgpbIDwwMDMzPiA2MyA8MDAyND4gMTcgPDAwMmEwMDI0MDAzMDAwMjgwMDMxMDAzNzAwMzIwMDAzMDAyNzAwMjgwMDAzMDAyNT4gMTcgPDAwMzIwMDJmMDAyODAwMzcwMDMyMDAwMzAwMjcwMDI4MDAwMzAwMjYwMDMyMDAzMTAwMzkwMDhjMDAzMTAwMmMwMDMyPiBdIFRKCkVUCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwpCVAoxIDAgMCAtMSAzMDYuMDg0NzY5IDI2MS41NDY4NzUgVG0KL1ZDQVRXUyAzMiBUZgpbIDwwMDM1MDAwNzAwMDMwMDE0MDAxNjAwMWIwMDBmMDAxYzAwMWE+IF0gVEoKRVQKUQpRCnEKcQowIDI3Mi40Njg3NSA3OTMuNzAwNzg3IDgxOCByZQpXCm4KcQowLjk0OTAyIDAuOTU2ODYzIDAuOTg4MjM1IHJnCi9hMS4wIGdzCjAgMjcyLjQ2ODc1IDc5My43MDA3ODcgODE4IHJlClcKbgowIDI3Mi40Njg3NSA3OTMuNzAwNzg3IDgxOCByZQpmClEKUQpRCnEKcQowIDI3Mi40Njg3NSA3OTMuNzAwNzg3IDIyOCByZQpXCm4KcQoxIDEgMSByZwovYTEuMCBncwowIDI3Mi40Njg3NSA3OTMuNzAwNzg3IDIyOCByZQpXCm4KMCAyNzIuNDY4NzUgNzkzLjcwMDc4NyAyMjggcmUKZgpRClEKcQo3OTMuNzAwNzg3IDUwMC40Njg3NSBtCjAgNTAwLjQ2ODc1IGwKMCA0OTkuNDY4NzUgbAo3OTMuNzAwNzg3IDQ5OS40Njg3NSBsClcqCm4KMC4wOTgwMzkgMC4xNDExNzYgMC40OTQxMTggcmcKL2ExLjAgZ3MKMCAyNzIuNDY4NzUgNzkzLjcwMDc4NyAyMjcgcmUKMCAyNzIuNDY4NzUgNzkzLjcwMDc4NyAyMjggcmUKZioKUQpRCnEKcQpxCnEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTEuMCBncwpCVAoxIDAgMCAtMSA3NS41OTA1NTEgMzgzLjAwNzgxMiBUbQovVkNBVFdTIDE2IFRmClsgPDAwMWIwMDE2MDAxOTAwMTQwMDEzMDAxMzAwMTMwMDEzMDAxMzAwMTMwMDE0MDAxNzAwMTYwMDFiMDAxYzAwMWEwMDEzMDAxMzAwMTcwMDEzMDAxNjAwMTYwMDFhMDAxYjAwMTMwMDE2MDAxNjAwMWIwMDFjMDAxNTAwMTcwMDE3MDAxODAwMTMwMDE2MDAxNjAwMTQwMDEzMDAxNDAwMTQwMDFjMDAxMzAwMTQwMDE1MDAxNTAwMTQwMDE4MDAxOT4gXSBUSgpFVApRClEKUQpRCnEKcQpxCnEKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCi9hMS4wIGdzCkJUCjEgMCAwIC0xIDc1LjU5MDU1MSA0NTkuMDA3ODEyIFRtCi9WQ0FUV1MgMTYgVGYKWyA8MDAzMTAwNTIwMDUxMDA0ODAwMDMwMDEwMDAwMzAwMzEwMDUyMDA1MTAwNDg+IF0gVEoKRVQKUQpRClEKUQpRClEKcQpxCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2ExLjAgZ3MKQlQKMSAwIDAgLTEgMTA5LjU5MDU1MSAzNDkuNjIzMDQ3IFRtCi9PQ0hOVVAgMTIgVGYKWyA8MDAyZjAwNGMwMDUxMDA0YjAwNDQwMDAzMDAyNzAwNGMwMDRhMDA0YzAwNTcwMGEzMDA1OTAwNDgwMDRmPiBdIFRKCkVUClEKUQpRClEKcQpxCjc1LjU5MDU1MSAzMzIuNDY4NzUgMjQgMjQgcmUKVwpuCnEKL2ExIGdzCjEgMCAwIDEgNzUuNTkwNTUxIDMzMi40Njg3NSBjbQpxCnEKMSAwIDAgMSAwIDAgY20KMSAwIDAgMSAwIDAgY20KcQoyNCAxMiBtCjI0IDE4Ljc3MDI3NSAxOC43NzAyNzUgMjQgMTIgMjQgYwo1LjIyOTcyNSAyNCAwIDE4Ljc3MDI3NSAwIDEyIGMKMCA1LjIyOTcyNSA1LjIyOTcyNSAwIDEyIDAgYwoxOC43NzAyNzUgMCAyNCA1LjIyOTcyNSAyNCAxMiBjCmgKMC44NjI3NDUgMC44NzA1ODggMC45NzY0NzEgcmcKL2ExLjAgZ3MKMSB3CjAgSgowIGoKNCBNCmYKUQpxCjAgMCBtCjUuNyA3LjUgbQo0LjggNy41IGwKNC44IDE2LjUgbAo1LjcgMTYuNSBsCjUuNyA3LjUgbApoCjE5LjIgNy41IG0KMTguMyA3LjUgbAoxOC4zIDE2LjUgbAoxOS4yIDE2LjUgbAoxOS4yIDcuNSBsCmgKNy45NSA3LjUgbQo3LjA1IDcuNSBsCjcuMDUgMTQuNyBsCjcuOTUgMTQuNyBsCjcuOTUgNy41IGwKaAo5Ljc1MiA3LjUgbQo4Ljg1MiA3LjUgbAo4Ljg1MiAxNC43IGwKOS43NTIgMTQuNyBsCjkuNzUyIDcuNSBsCmgKMTMuMzUxIDcuNSBtCjEyLjQ1MSA3LjUgbAoxMi40NTEgMTYuNSBsCjEzLjM1MSAxNi41IGwKMTMuMzUxIDcuNSBsCmgKMTUuMTUgNy41IG0KMTQuMjUgNy41IGwKMTQuMjUgMTQuNyBsCjE1LjE1IDE0LjcgbAoxNS4xNSA3LjUgbApoCjcuOTUgMTUuNiBtCjcuMDUgMTUuNiBsCjcuMDUgMTYuNSBsCjcuOTUgMTYuNSBsCjcuOTUgMTUuNiBsCmgKOS43NTIgMTUuNiBtCjguODUyIDE1LjYgbAo4Ljg1MiAxNi41IGwKOS43NTIgMTYuNSBsCjkuNzUyIDE1LjYgbApoCjExLjU1IDcuNSBtCjEwLjY1IDcuNSBsCjEwLjY1IDE0LjcgbAoxMS41NSAxNC43IGwKMTEuNTUgNy41IGwKaAoxMS41NSAxNS42IG0KMTAuNjUgMTUuNiBsCjEwLjY1IDE2LjUgbAoxMS41NSAxNi41IGwKMTEuNTUgMTUuNiBsCmgKMTUuMTUgMTUuNiBtCjE0LjI1IDE1LjYgbAoxNC4yNSAxNi41IGwKMTUuMTUgMTYuNSBsCjE1LjE1IDE1LjYgbApoCjE2Ljk1IDcuNSBtCjE2LjA1IDcuNSBsCjE2LjA1IDE0LjcgbAoxNi45NSAxNC43IGwKMTYuOTUgNy41IGwKaAoxNi45NSAxNS42IG0KMTYuMDUgMTUuNiBsCjE2LjA1IDE2LjUgbAoxNi45NSAxNi41IGwKMTYuOTUgMTUuNiBsCmgKMC4wOTgwMzkgMC4xNDExNzYgMC40OTQxMTggcmcKL2ExLjAgZ3MKMSB3CjAgSgowIGoKNCBNCmYKUQoxIHcKMCBKCjAgago0IE0KbgpRClEKUQpRClEKcQpxCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2ExLjAgZ3MKQlQKMSAwIDAgLTEgMTA5LjU5MDU1MSA0MjUuNjIzMDQ3IFRtCi9PQ0hOVVAgMTIgVGYKWyA8MDAyNTAwNDQwMDUxMDA0NjAwNTIwMDAzMDA0NzAwNDgwMDU2MDA1NzAwNGMwMDUxMDA0NDAwNTcwMGEzMDA1NTAwNGMwMDUyPiBdIFRKCkVUClEKUQpRClEKcQpxCjc1LjU5MDU1MSA0MDguNDY4NzUgMjQgMjQgcmUKVwpuCnEKL2ExIGdzCjEgMCAwIDEgNzUuNTkwNTUxIDQwOC40Njg3NSBjbQpxCnEKMSAwIDAgMSAwIDAgY20KMSAwIDAgMSAwIDAgY20KcQoyNCAxMiBtCjI0IDE4Ljc3MDI3NSAxOC43NzAyNzUgMjQgMTIgMjQgYwo1LjIyOTcyNSAyNCAwIDE4Ljc3MDI3NSAwIDEyIGMKMCA1LjIyOTcyNSA1LjIyOTcyNSAwIDEyIDAgYwoxOC43NzAyNzUgMCAyNCA1LjIyOTcyNSAyNCAxMiBjCmgKMC44NjI3NDUgMC44NzA1ODggMC45NzY0NzEgcmcKL2ExLjAgZ3MKMSB3CjAgSgowIGoKNCBNCmYKUQpxCjAgMCBtCjE4LjEyOSAxMC4yMiBtCjE4LjU4MSAxMC4yMiAxOC45NDkgOS44NTIgMTguOTQ5IDkuNCBjCjE4Ljk0OSA4LjMzNyBsCjE4Ljk0OTkyOCA4LjAwMTkzMiAxOC43NDYxNzQgNy43MDAyNjUgMTguNDM1IDcuNTc2IGMKMTIuMjgyIDUuMDYgbAoxMi4wODU4MzUgNC45ODAzODcgMTEuODY2NDI1IDQuOTgwMDI4IDExLjY3IDUuMDU5IGMKNS41MTQgNy41NzYgbAo1LjIwMjgyNiA3LjcwMDI2NSA0Ljk5OTA3MiA4LjAwMTkzMiA1IDguMzM3IGMKNSA5LjQgbAo1IDkuODUyIDUuMzY4IDEwLjIyIDUuODIgMTAuMjIgYwo2LjMxMyAxMC4yMiBsCjYuMzEzIDE2LjQwMiBsCjUuODIgMTYuNDAyIGwKNS4zNjY5NjQgMTYuNDAyIDQuOTk5NTUyIDE2Ljc2ODk2NSA0Ljk5OSAxNy4yMjIgYwo0Ljk5OSAxOC4xNzkgbAo0Ljk5OSAxOC42MzIgNS4zNjcgMTkgNS44MTkgMTkgYwoxOC4xMyAxOSBsCjE4LjU4MiAxOSAxOC45NSAxOC42MzIgMTguOTUgMTguMTggYwoxOC45NSAxNy4yMjIgbAoxOC45NDk0NDkgMTYuNzY5MzU1IDE4LjU4MjY0NSAxNi40MDI1NTEgMTguMTMgMTYuNDAyIGMKMTcuNjM3IDE2LjQwMiBsCjE3LjYzNyAxMC4yMiBsCjE4LjEzIDEwLjIyIGwKaAoxOC4xMjkgMTcuMjIyIG0KMTguMTI5IDE4LjIwMiAxOC4xMzEgMTguMTc5IDE4LjEyOSAxOC4xNzkgYwo1LjgyIDE4LjE3OSBsCjUuODIgMTcuMjIyIGwKMTguMTI4IDE3LjIyMiBsCmgKNy4xMzMgMTYuNDAyIG0KNy4xMzMgMTAuMjIgbAo4LjA2MyAxMC4yMiBsCjguMDYzIDE2LjQwMiBsCjcuMTMzIDE2LjQwMiBsCmgKOC44ODQgMTYuNDAyIG0KOC44ODQgMTAuMjIgbAoxMC42ODkgMTAuMjIgbAoxMC42ODkgMTYuNDAyIGwKOC44ODQgMTYuNDAyIGwKaAoxMS41MSAxNi40MDIgbQoxMS41MSAxMC4yMiBsCjEyLjQ0IDEwLjIyIGwKMTIuNDQgMTYuNDAyIGwKMTEuNTEgMTYuNDAyIGwKaAoxMy4yNiAxNi40MDIgbQoxMy4yNiAxMC4yMiBsCjE1LjA2NSAxMC4yMiBsCjE1LjA2NSAxNi40MDIgbAoxMy4yNiAxNi40MDIgbApoCjE1Ljg4NiAxNi40MDIgbQoxNS44ODYgMTAuMjIgbAoxNi44MTYgMTAuMjIgbAoxNi44MTYgMTYuNDAyIGwKMTUuODg2IDE2LjQwMiBsCmgKNS44MiA5LjQgbQo1LjgyIDguMjU1IDUuODE4IDguMzM4IDUuODIyIDguMzM2IGMKMTEuOTc0IDUuODIxIGwKMTguMTI0IDguMzM2IGwKMTguMTI5IDguMzM4IDE4LjEyOCA4LjI1OCAxOC4xMjggOS40IGMKNS44MiA5LjQgbApoCjAuMDk4MDM5IDAuMTQxMTc2IDAuNDk0MTE4IHJnCi9hMS4wIGdzCjEgdwowIEoKMCBqCjQgTQpmClEKMSB3CjAgSgowIGoKNCBNCm4KUQpRClEKUQpRCnEKcQpxCnEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTAuNyBncwpCVAoxIDAgMCAtMSA3NS41OTA1NTEgNTg2LjYyMzA0NyBUbQovVkNBVFdTIDEyIFRmClsgPDAwMzEwMDUyMDA1MDAwNDgwMDAzMDA0NzAwNTIwMDAzMDAzMz4gMjYgPDAwNDQwMDRhMDA0NDAwNDcwMDUyMDA1NT4gXSBUSgpFVApRClEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTEuMCBncwpCVAoxIDAgMCAtMSAzOTYuODUwMzk0IDU4OC4xMjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDI1MDA0ODAwNDQwMDU3MDA1NTAwNGMwMDVkMDAwMzAwMjYwMDUyMDA1ODAwNTcwMDUyMDAwMzAwNDcwMDQ4MDAwMzAwMjYwMDQ0MDA1NTAwNTkwMDQ0MDA0ZjAwNGIwMDUyPiBdIFRKCkVUClEKUQpRClEKcQpxCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2EwLjcgZ3MKQlQKMSAwIDAgLTEgNzUuNTkwNTUxIDYyNS42MjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDI2MDAzMzAwMjkwMDEyMDAyNjAwMzEwMDMzMDAyZD4gXSBUSgpFVApRClEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTEuMCBncwpCVAoxIDAgMCAtMSAzOTYuODUwMzk0IDYyNy4xMjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDEzMDAxNjAwMWEwMDExMDAxYjAwMTUwMDE5MDAxMTAwMTQwMDFhMDAxMzAwMTAwMDE2MDAxYT4gXSBUSgpFVApRClEKUQpRCnEKcQpxCnEKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCi9hMC43IGdzCkJUCjEgMCAwIC0xIDc1LjU5MDU1MSA2NjQuNjIzMDQ3IFRtCi9WQ0FUV1MgMTIgVGYKWyA8MDAyNDAwNGEwMGFjMDA1MTAwNDYwMDRjMDA0ND4gXSBUSgpFVApRClEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTEuMCBncwpCVAoxIDAgMCAtMSAzOTYuODUwMzk0IDY2Ni4xMjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDEzMDAxMzAwMTMwMDE0PiBdIFRKCkVUClEKUQpRClEKcQpxCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2EwLjcgZ3MKQlQKMSAwIDAgLTEgNzUuNTkwNTUxIDcwMy42MjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDI2MDA1MjAwNTEwMDU3MDA0ND4gXSBUSgpFVApRClEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTEuMCBncwpCVAoxIDAgMCAtMSAzOTYuODUwMzk0IDcwNS4xMjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDFhMDAxYTAwMWMwMDFhMDAxYzAwMTAwMDE1PiBdIFRKCkVUClEKUQpRClEKcQpxCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2EwLjcgZ3MKQlQKMSAwIDAgLTEgNzUuNTkwNTUxIDc0Mi42MjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDJjMDA1MTAwNTYwMDU3MDA0YzAwNTcwMDU4MDA0YzAwYTkwMGE1MDA1MjAwMDMwMDI5MDA0YzAwNTEwMDQ0MDA1MTAwNDYwMDQ4MDA0YzAwNTUwMDQ0PiBdIFRKCkVUClEKUQpxCnEKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCi9hMS4wIGdzCkJUCjEgMCAwIC0xIDM5Ni44NTAzOTQgNzQ0LjEyMzA0NyBUbQovVkNBVFdTIDEyIFRmClsgPDAwMzQwMDJjMDAwMzAwMzYwMDMyMDAyNjAwMmMwMDI4MDAyNzAwMjQwMDI3MDAyODAwMDMwMDI3MDAyODAwMDMwMDI2MDAzNTAwOGIwMDI3MDAyYzAwMzcwMDMyMDAwMzAwMjcwMDJjMDAzNTAwMjgwMDM3MDAzMjAwMDMwMDM2MDAxMTAwMjQ+IC0xOCA8MDAxMT4gXSBUSgpFVApRClEKUQpRCnEKcQpxCnEKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCi9hMC43IGdzCkJUCjEgMCAwIC0xIDc1LjU5MDU1MSA3ODEuNjIzMDQ3IFRtCi9WQ0FUV1MgMTIgVGYKWyA8MDAzOT4gNTQgPDAwNDQwMDRmMDA1MjAwNTU+IF0gVEoKRVQKUQpRCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2ExLjAgZ3MKQlQKMSAwIDAgLTEgMzk2Ljg1MDM5NCA3ODMuMTIzMDQ3IFRtCi9WQ0FUV1MgMTIgVGYKWyA8MDAzNTAwMDcwMDAzMDAxNDAwMTYwMDFiMDAwZjAwMWMwMDFhPiBdIFRKCkVUClEKUQpRClEKcQpxCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2EwLjcgZ3MKQlQKMSAwIDAgLTEgNzUuNTkwNTUxIDg4NC42MjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDMxMDA1MjAwNTAwMDQ4MDAwMzAwNDcwMDUyMDAwMzAwMjUwMDQ4MDA1MTAwNDgxM2FlMDA0NjAwNGMwMGEzMDA1NTAwNGMwMDUyPiBdIFRKCkVUClEKUQpxCnEKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCi9hMS4wIGdzCkJUCjEgMCAwIC0xIDM5Ni44NTAzOTQgODg2LjEyMzA0NyBUbQovVkNBVFdTIDEyIFRmClsgPDAwMjYwMDMzMDAyOTAwMmYwMDAzMDAyNjAwMmMwMDI0MDAwMzAwMzM+IDkxIDwwMDI0PiAzMCA8MDAzODAwMmYwMDJjMDAzNjAwMzc+IDc3IDwwMDI0MDAwMzAwMjkwMDMyPiBdIFRKCkVUClEKUQpRClEKcQpxCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2EwLjcgZ3MKQlQKMSAwIDAgLTEgNzUuNTkwNTUxIDkyMy42MjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDI2MDAzMzAwMjkwMDEyMDAyNjAwMzEwMDMzMDAyZD4gXSBUSgpFVApRClEKUQpRCnEKcQpxCnEKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCi9hMC43IGdzCkJUCjEgMCAwIC0xIDc1LjU5MDU1MSA5NTkuNjIzMDQ3IFRtCi9WQ0FUV1MgMTIgVGYKWyA8MDAzMTAwNTIwMDUwMDA0ODAwMDMwMDQ3MDA1MjAwMDMwMDM2MDA0NDAwNDYwMDQ0MDA0NzAwNTIwMDU1MDAwMzAwMjQ+IDM1IDwwMDU5MDA0NDAwNGYwMDRjMDA1NjAwNTcwMDQ0PiBdIFRKCkVUClEKUQpxCnEKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCi9hMS4wIGdzCkJUCjEgMCAwIC0xIDM5Ni44NTAzOTQgOTYxLjEyMzA0NyBUbQovVkNBVFdTIDEyIFRmClsgPDAwMTA+IF0gVEoKRVQKUQpRClEKUQpxCnEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTAuNyBncwpCVAoxIDAgMCAtMSA3NS41OTA1NTEgOTk4LjYyMzA0NyBUbQovVkNBVFdTIDEyIFRmClsgPDAwMjYwMDMxMDAzMzAwMmQ+IF0gVEoKRVQKUQpRCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2ExLjAgZ3MKQlQKMSAwIDAgLTEgMzk2Ljg1MDM5NCAxMDAwLjEyMzA0NyBUbQovVkNBVFdTIDEyIFRmClsgPDAwMTA+IF0gVEoKRVQKUQpRClEKUQpxCnEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTAuNyBncwpCVAoxIDAgMCAtMSA3NS41OTA1NTEgMTAzNy42MjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDI3MDA0NDAwNTcwMDQ0MDAwMzAwNDcwMDQ4MDAwMzAwMzk+IDU0IDwwMDQ4MDA1MTAwNDYwMDRjMDA1MDAwNDgwMDUxMDA1NzAwNTI+IF0gVEoKRVQKUQpRClEKUQpxCnEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTAuNyBncwpCVAoxIDAgMCAtMSA3NS41OTA1NTEgMTA3My42MjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDI3MDA0NDAwNTcwMDQ0MDAwMzAwNDcwMDUyMDAwMzAwMzM+IDI2IDwwMDQ0MDA0YTAwNDQwMDUwMDA0ODAwNTEwMDU3MDA1Mj4gXSBUSgpFVApRClEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTEuMCBncwpCVAoxIDAgMCAtMSAzOTYuODUwMzk0IDEwNzUuMTIzMDQ3IFRtCi9WQ0FUV1MgMTIgVGYKWyA8MDAxNTAwMTMwMDEyMDAxMzAwMTkwMDEyMDAxNTAwMTMwMDE1MDAxNz4gXSBUSgpFVApRClEKUQpRClEKUQpxCnEKMCAxMDI1LjUxOTY4NSA3OTMuNzAwNzg3IDk3IHJlClcKbgpxCjAuOTQ5MDIgMC45NTY4NjMgMC45ODgyMzUgcmcKL2ExLjAgZ3MKMCAxMDI1LjUxOTY4NSA3OTMuNzAwNzg3IDk3IHJlClcKbgowIDEwMjUuNTE5Njg1IDc5My43MDA3ODcgOTcgcmUKZgpRClEKcQo3OTMuNzAwNzg3IDEwMjUuNTE5Njg1IG0KMCAxMDI1LjUxOTY4NSBsCjAgMTAyNi41MTk2ODUgbAo3OTMuNzAwNzg3IDEwMjYuNTE5Njg1IGwKVyoKbgowIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNS45OTAxOTUgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoxMS45ODAzODkgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoxNy45NzA1ODQgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoyMy45NjA3NzggMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoyOS45NTA5NzMgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQozNS45NDExNjggMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo0MS45MzEzNjIgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo0Ny45MjE1NTcgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo1My45MTE3NTIgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo1OS45MDE5NDYgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo2NS44OTIxNDEgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo3MS44ODIzMzUgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo3Ny44NzI1MyAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjgzLjg2MjcyNSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjg5Ljg1MjkxOSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjk1Ljg0MzExNCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjEwMS44MzMzMDkgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoxMDcuODIzNTAzIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMTEzLjgxMzY5OCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjExOS44MDM4OTIgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoxMjUuNzk0MDg3IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMTMxLjc4NDI4MiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjEzNy43NzQ0NzYgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoxNDMuNzY0NjcxIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMTQ5Ljc1NDg2NiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjE1NS43NDUwNiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjE2MS43MzUyNTUgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoxNjcuNzI1NDQ5IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMTczLjcxNTY0NCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjE3OS43MDU4MzkgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoxODUuNjk2MDMzIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMTkxLjY4NjIyOCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjE5Ny42NzY0MjMgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoyMDMuNjY2NjE3IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMjA5LjY1NjgxMiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjIxNS42NDcwMDYgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoyMjEuNjM3MjAxIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMjI3LjYyNzM5NiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjIzMy42MTc1OSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjIzOS42MDc3ODUgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoyNDUuNTk3OTc5IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMjUxLjU4ODE3NCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjI1Ny41NzgzNjkgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoyNjMuNTY4NTYzIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMjY5LjU1ODc1OCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjI3NS41NDg5NTMgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoyODEuNTM5MTQ3IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMjg3LjUyOTM0MiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjI5My41MTk1MzYgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoyOTkuNTA5NzMxIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMzA1LjQ5OTkyNiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjMxMS40OTAxMiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjMxNy40ODAzMTUgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQozMjMuNDcwNTEgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQozMjkuNDYwNzA0IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMzM1LjQ1MDg5OSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjM0MS40NDEwOTMgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQozNDcuNDMxMjg4IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMzUzLjQyMTQ4MyAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjM1OS40MTE2NzcgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQozNjUuNDAxODcyIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMzcxLjM5MjA2NyAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjM3Ny4zODIyNjEgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQozODMuMzcyNDU2IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMzg5LjM2MjY1IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMzk1LjM1Mjg0NSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjQwMS4zNDMwNCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjQwNy4zMzMyMzQgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo0MTMuMzIzNDI5IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNDE5LjMxMzYyNCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjQyNS4zMDM4MTggMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo0MzEuMjk0MDEzIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNDM3LjI4NDIwNyAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjQ0My4yNzQ0MDIgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo0NDkuMjY0NTk3IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNDU1LjI1NDc5MSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjQ2MS4yNDQ5ODYgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo0NjcuMjM1MTgxIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNDczLjIyNTM3NSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjQ3OS4yMTU1NyAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjQ4NS4yMDU3NjQgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo0OTEuMTk1OTU5IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNDk3LjE4NjE1NCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjUwMy4xNzYzNDggMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo1MDkuMTY2NTQzIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNTE1LjE1NjczNyAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjUyMS4xNDY5MzIgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo1MjcuMTM3MTI3IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNTMzLjEyNzMyMSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjUzOS4xMTc1MTYgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo1NDUuMTA3NzExIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNTUxLjA5NzkwNSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjU1Ny4wODgxIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNTYzLjA3ODI5NCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjU2OS4wNjg0ODkgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo1NzUuMDU4Njg0IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNTgxLjA0ODg3OCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjU4Ny4wMzkwNzMgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo1OTMuMDI5MjY4IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNTk5LjAxOTQ2MiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjYwNS4wMDk2NTcgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo2MTAuOTk5ODUxIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNjE2Ljk5MDA0NiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjYyMi45ODAyNDEgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo2MjguOTcwNDM1IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNjM0Ljk2MDYzIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNjQwLjk1MDgyNSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjY0Ni45NDEwMTkgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo2NTIuOTMxMjE0IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNjU4LjkyMTQwOCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjY2NC45MTE2MDMgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo2NzAuOTAxNzk4IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNjc2Ljg5MTk5MiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjY4Mi44ODIxODcgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo2ODguODcyMzgyIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNjk0Ljg2MjU3NiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjcwMC44NTI3NzEgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo3MDYuODQyOTY1IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNzEyLjgzMzE2IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNzE4LjgyMzM1NSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjcyNC44MTM1NDkgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo3MzAuODAzNzQ0IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNzM2Ljc5MzkzOCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjc0Mi43ODQxMzMgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo3NDguNzc0MzI4IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNzU0Ljc2NDUyMiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjc2MC43NTQ3MTcgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo3NjYuNzQ0OTEyIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNzcyLjczNTEwNiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjc3OC43MjUzMDEgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo3ODQuNzE1NDk1IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNzkwLjcwNTY5IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKVyoKbgowLjA5ODAzOSAwLjE0MTE3NiAwLjQ5NDExOCByZwovYTEuMCBncwowIDEwMjYuNTE5Njg1IDc5My43MDA3ODcgOTYgcmUKMCAxMDI1LjUxOTY4NSA3OTMuNzAwNzg3IDk3IHJlCmYqClEKUQpxCnEKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCi9hMC43IGdzCkJUCjEgMCAwIC0xIDMyNS43NTI3MzcgMTA1Ny42NzM5ODIgVG0KL09DSE5VUCAxMiBUZgpbIDwwMDI2MDBiNTAwNDcwMDRjMDA0YTAwNTIwMDAzMDA0NzAwNDgwMDAzMDA0NDAwNTgwMDU3MDA0ODAwNTEwMDU3MDA0YzAwNDYwMDQ0MDBhOTAwYTUwMDUyMDAwMz4gXSBUSgpFVAovYTEuMCBncwpCVAoxIDAgMCAtMSAyNjkuNjAyMzQ3IDEwNzEuNjczOTgyIFRtCi9PQ0hOVVAgMTIgVGYKWyA8MDAxYjAwMWMwMDFiMDAxNTAwMTMwMDEzMDAxNTAwMTkwMDEwMDA0NTAwNDUwMDE2MDA0ODAwMTAwMDE3MDAxNzAwNDkwMDQ2MDAxMDAwMWIwMDE0MDAxNjAwMTMwMDEwMDA0NjAwNDgwMDQ0MDA0NDAwMTYwMDEzMDAxMzAwNDgwMDE0MDA0NzAwMWIwMDQ0PiBdIFRKCkVUCi9hMC43IGdzCkJUCjEgMCAwIC0xIDI5MC42Mjg3MTQgMTA5NS42NzM5ODIgVG0KL09DSE5VUCAxMiBUZgpbIDwwMDM0MDA0YzAwMDMwMDM2MDA1MjAwNDYwMDRjMDA0ODAwNDcwMDQ0MDA0NzAwNDgwMDAzMDA0NzAwNDgwMDAzMDAyNjAwNTU+IDIxIDwwMDQ4MDA0NzAwNGMwMDU3MDA1MjAwMDMwMDI3MDA0YzAwNTU+IDIxIDwwMDQ4MDA1NzAwNTIwMDAzMDAzNjAwMTEwMDI0PiAxNyA8MDAxMT4gXSBUSgoxIDAgMCAtMSAzMTkuNDMzNDAyIDExMDkuNjczOTgyIFRtClsgPDAwMjYwMDMxMDAzMzAwMmQwMDAzMDAxNjAwMTUwMDExMDAxNzAwMTMwMDE1MDAxMTAwMTgwMDEzMDAxNTAwMTIwMDEzMDAxMzAwMTMwMDE0MDAxMDAwMTgwMDFjPiBdIFRKCkVUClEKUQpxCnEKcQpxCjc1LjU5MDU1MSA1MjIuNDY4NzUgNzAgOSByZQpXCm4KcQoxIDAuOTA1ODgyIDAuOTM3MjU1IHJnCi9hMS4wIGdzCjc1LjU5MDU1MSA1MjIuNDY4NzUgNzAgOSByZQpXCm4KNzUuNTkwNTUxIDUyMi40Njg3NSA3MCA5IHJlCmYKUQpRClEKMC4wOTgwMzkgMC4xNDExNzYgMC40OTQxMTggcmcKL2ExLjAgZ3MKQlQKMSAwIDAgLTEgNzUuNTkwNTUxIDUyNy4wMDc4MTIgVG0KL1ZDQVRXUyAxNiBUZgpbIDwwMDMzPiAyNiA8MDA0NDAwNGEwMDQ0MDA0NzAwNTI+IF0gVEoKMSAwIDAgLTEgNzUuNTkwNTUxIDU0OS4wMDc4MTIgVG0KWyA8MDA1NT4gXSBUSgpFVApRClEKcQpxCnEKcQo3NS41OTA1NTEgODIwLjQ2ODc1IDEwMCA5IHJlClcKbgpxCjEgMC45MDU4ODIgMC45MzcyNTUgcmcKL2ExLjAgZ3MKNzUuNTkwNTUxIDgyMC40Njg3NSAxMDAgOSByZQpXCm4KNzUuNTkwNTUxIDgyMC40Njg3NSAxMDAgOSByZQpmClEKUQpRCjAuMDk4MDM5IDAuMTQxMTc2IDAuNDk0MTE4IHJnCi9hMS4wIGdzCkJUCjEgMCAwIC0xIDc1LjU5MDU1MSA4MjUuMDA3ODEyIFRtCi9WQ0FUV1MgMTYgVGYKWyA8MDAyNTAwNDgwMDUxMDA0ODEzYWUwMDQ2MDA0YzAwYTMwMDU1MDA0Yz4gXSBUSgoxIDAgMCAtMSA3NS41OTA1NTEgODQ3LjAwNzgxMiBUbQpbIDwwMDUyPiBdIFRKCkVUClEKUQpRClEKUQpRClEKUQpxCjAgMCA1OTUuMzAzOTM3MDA3ODc0IDg0MS44ODk3NjM3Nzk1MjggcmUKVwpuCjAuMSB3CnEKMTAgLTAuMTEgNTc1LjMgODE0IHJlClcqCm4KcQovRUdTNiBncwovVHI1IERvClEKUQpRCgplbmRzdHJlYW0KZW5kb2JqCjYgMCBvYmoKPDwKL0NBIDAuMwovY2EgMC4zCj4+CmVuZG9iago3IDAgb2JqCjw8Ci9UeXBlIC9Gb250Ci9TdWJ0eXBlIC9UeXBlMAovQmFzZUZvbnQgL1ZDQVRXUytEZWphVnUtU2Fucy1Cb2xkCi9Ub1VuaWNvZGUgOCAwIFIKL0VuY29kaW5nIC9JZGVudGl0eS1ICi9EZXNjZW5kYW50Rm9udHMgWyA5IDAgUiBdCj4+CmVuZG9iago4IDAgb2JqCjw8Ci9GaWx0ZXIgL0ZsYXRlRGVjb2RlCi9MZW5ndGggNDg0Cj4+CnN0cmVhbQp42l2UyYrbQBRF9/qKWnYWjVST7AYjCJ2NFxmIkw8oVz25BbEkZHnhv09JRzgQgw2XN9xBfirfj1+OfTer8sc0xJPMqu36NMltuE9R1FkuXV9oo1IX5w2tv/EaxqLMw6fHbZbrsW+H4nBQ5c9cvM3TQ718TsNZPhXl9ynJ1PUX9fL7/ZTx6T6Of+Qq/ayqomlUkjYv+hrGb+EqqlzHXo8p17v58Zpn/nX8eoyizIo1YuKQ5DaGKFPoL1Icqvxp1KHNn6aQPv1X93vGzm38CNPSburcXlXONgvyZkV1C6pACWRXtKtAHmRAb6B6Rc4xp6lpkIB2dDo699T8iioYDAyOznrrDKDdiizsHvaKTkOnht3CrvFn8afPoD1zLXORWqT2BoLPwqfxZ/Gn0WnRqWG3GzvKLMo0/iz+LEk4ktCka0jXstOz07DFscWhrEaZTyQYQDDsYHA4qnHkcFvj1uDBbR540oYnbdjp2KnRadBpyNORZ0CL0OlItyZdQ81tOqntqAXYhTwD/oSahcHDYJnzWw2dbtOJW4dbQ/KO5Pe4jbBbap6ahd0v3rUNgur6mWkgfUGBIUVHihbO/IdfDmq7nOW0ljfA827jfZryya6vifVWlyvtenm+ScZhXKaW718jUhDPCmVuZHN0cmVhbQplbmRvYmoKOSAwIG9iago8PAovVHlwZSAvRm9udAovU3VidHlwZSAvQ0lERm9udFR5cGUyCi9CYXNlRm9udCAvVkNBVFdTK0RlamFWdS1TYW5zLUJvbGQKL0NJRFN5c3RlbUluZm8gPDwKL1JlZ2lzdHJ5IChBZG9iZSkKL09yZGVyaW5nIChJZGVudGl0eSkKL1N1cHBsZW1lbnQgMAo+PgovQ0lEVG9HSURNYXAgL0lkZW50aXR5Ci9XIFsgMyBbIDM0OCBdIDcgWyA2OTYgXSAxNSBbIDM4MCA0MTUgMzgwIDM2NSA2OTYgNjk2IDY5NiA2OTYgNjk2IDY5NiA2OTYgNjk2IDY5NiA2OTYgXSAzNiBbIDc3NCA3NjIgNzM0IDgzMCA2ODMgNjgzIF0gNDQgWyAzNzIgMzcyIF0gNDcgWyA2MzcgXSA0OSBbIDgzNyA4NTAgNzMzIDg1MCA3NzAgNzIwIDY4MiA4MTIgNzc0IF0gNjggWyA2NzUgXSA3MCBbIDU5MyA3MTYgNjc4IF0gNzQgWyA3MTYgNzEyIDM0MyBdIDc5IFsgMzQzIDEwNDIgNzEyIDY4NyA3MTYgXSA4NSBbIDQ5MyA1OTUgNDc4IDcxMiA2NTIgXSA5MyBbIDU4MiBdIDEzOSBbIDY4MyBdIDE2MyBbIDY3NSBdIDE2NSBbIDY3NSBdIDE2OSBbIDU5MyBdIDE3MiBbIDY3OCBdIDUwMzggWyA3NDEgXSBdCi9Gb250RGVzY3JpcHRvciAxMCAwIFIKPj4KZW5kb2JqCjEwIDAgb2JqCjw8Ci9UeXBlIC9Gb250RGVzY3JpcHRvcgovRm9udE5hbWUgL1ZDQVRXUytEZWphVnUtU2Fucy1Cb2xkCi9Gb250RmFtaWx5IChEZWphVnVcMDQwU2FucykKL0ZsYWdzIDQKL0ZvbnRCQm94IFsgMCAtMjM1IDEwNDIgOTI4IF0KL0l0YWxpY0FuZ2xlIDAKL0FzY2VudCA5MjgKL0Rlc2NlbnQgLTIzNQovQ2FwSGVpZ2h0IDkyOAovU3RlbVYgODAKL1N0ZW1IIDgwCi9Gb250RmlsZTIgMTEgMCBSCj4+CmVuZG9iagoxMSAwIG9iago8PAovTGVuZ3RoMSAzOTUyMAovRmlsdGVyIC9GbGF0ZURlY29kZQovTGVuZ3RoIDQ1MjcKPj4Kc3RyZWFtCnja7Vx5WJXV1l/rnSCcOIziyPEwiIQgiGhlOSCpKZmpqaAyyGHyAApoKEhqT46lPo5YKRI5kilxb2bINTJvZmZeo66aeo3Pq5+hkY/XVDibb+33nEPo1x16vqc/+p79+/WOe+21115r7eHtkQMIAB3gJZBhXEzMhLFrkiq2ApQcobfdno4eEeNT4lNBz9/S8+Jnnw8NzwyoyAXAyfQ8KdmSmNPVV+4P8EIYPR9NTczNAScilFTRc/vUWQXmx1PM3wG80hnAMD8tJXFmr0HDGqiM6xuQRi/ar+niR/o86NkvzZL3YrRrt/X0vB9g4kuzspMTQ44FDSf9twH69rIkvpjj7QMFVD6Q5H2zEi0pj7YfOgdgE6/DcrJz81rOw1Rqfz0vB943afpBN6eRa2Z0euIf0NMZOM7d2LqUX7+7fb/FamExTlVOmSTrDBLYQPWcLKw7gPMkq4Xuq3RNbeC+n7/xdoVw8tsIOh4sl+gZlQ1SNagAaoRaQip72K7yN2CW3EiknbMsa4okKSQvD2lTeZx5xEyy3bcJNQ/mgVucLFhvs4lDOQnm1maOP2iVuhZK4V9AdgGLPB6y6XpaatDlk+i4SkcZHcvpiKdjKx3F9uciOjL+lU6tH7hoPlCtXgKzVk7Xebaj1cb7UC3db3lVt8/H9l6rhGqN+qFesF21IKrzMaxT80lXMb0jnfAfQjXDZN0vNTBZPUT2W2zP+n0lVEg1UNFqC907T4I9/L1arMvrZfItqFA+hgz5DHSlslI1Cnq2bUPZBfHwG0MBtDz0rP1fdbaNw28Bh+8d11bba35+dsRDQEBAQEBA4LfcR8DS30hvufCugICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDA7xPqTQgWXhAQEBAQ+H2C/xqs/iuxMh0e9t999QAF9tO1N/jSnTOd/WAQxMBoGAOTIBFSIB1yYC7Mh+NwGerhKlxvwpYWAF3yURgKo0gyliSTIRVmwZyHJVvq/ylrHez8zsO/Ufsr8NxDTCJ7F8IqqIY6RHwSp+FreBIvS8FS+kNcKtVIDbKPHCGP1jlZnk1cTHxdPiE3Kv7KC8omZa/yhVL/S1R7EJ9RC9V3iY2aj9ZX5xPaXG2r9rlm1axO3Z3inBY67XI6bGfdr+Z/2eis/lsafiW7E4PsjNQ5VFBQ8HfH538FFwsKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCv6/5j5BQUFBQcHfJQ/r/8K9lJ1RNc0DTNAH+gGgSQ4ICDR4eXkbAgMCIvsPiIqK8KQnT/7W28vL00Nzkg2a5unh5W4YMCCyf4DctQyLrmfnfl9g/OH4P+qxbOanKfSfLzt5+6eypyfGNr7wwjh2BkPUvkGoPf6UglFan6rd7x1/5Gq9c6+urE+oyi5rvT98/+AnHeVhqCojIh8fzg6w6zhsWPRwMggs7II0CJeACuBuNMgm99OY9lPdTFzCTrGVmE8S2Vgt1UuX+L/XJwljtpRnXSVdYhd47dMAem17GdVlm6lqES+DlmFSg1rHyzACTVLHi9YfL6h19ywgQVJLvRqqNkI78KZS1wBTL83g6hURPgBdwegLBv0s70svLMzIKFyQgYvYEXaOnWVHcAgGYgAOkRqw85Ur7Bq7cu0admavMguuw1zMw3XMQm1fBVAVattFt0s1+JNxBmMjTmBvYRxm4YSmBnSRPxmJ2simSHaHapQBKJfIos5kDxdG3f1klxMFIsJX4aGRYqW1TR9LxlExr+ZP/Xr+YjYf22PQws+wK7uCXfHysIXR6S+NHYMjg0Mazsw/c4B7YXlLvXKT9PamBx5gxdhLzwDqK9dvirTftG1IPrTpTVbBDuVenT2rLrXkrZ1vbSlb+9qKhdNqps/52yw0oXGF7B/40YaLV/39MWhAVEayOf1u3LRJ0/sEYRdf3z8dWbKTfBxPPoggH0jQgdpGo2w0RBhM3A8G6RabijuGYEVdHVtvzVA2W1fL+5rHs/9mjeiKo7ndWylCEtXubousJ7cNPD3gQfPJ6rPyYevcR6eEoQHD2B/YueJ7C+afT1y1ffuq56tnqXXsytX2HdgPt2+xm/3CMTQmZnn+3GXBIWRVMbVgUm9SDvhRg7140tu0oiFA10xNhutN2hIi3Eu6kkIwp6Tg3Bm7xlUccR22Je4K+rBj7C67wD7CfByRWitdXmKHdJI1hAT/qbpfP3b7bCO7hMsxHefgTl89LhTvm9Q/jffPE41oXK6kWA+x5VKgtZ9ad7ZJUQ7xEVxEVrrpmWqC0Aft9OdD2M9oyw1bbH39aFC7e/zsHun4rLy8WZlz5rDCZSuwCzmpE3ZZuWzz65TMF8nob16/lRw/NSlpanyy9MbcrKz8/Kzs/OKgPcWHj31SU7wnqM/hNRfr6y+uOYwTpyQkTJkyI4E8l0E2dSTPdeaei7JFI0rTTL0gsr/DW70C0GEDGXwyftf4iiOG6C1Tr7CrOAid0A+HsBXsUPoRLE4xk0vNZiN6BJO3wsOx3bkfsRebyzaz19iUntLNJUsWv/zy4iVL+N/t0IjSAslvTvyOJxXqlJUY644ZrEgKwhNSECuy7sKSz9GVNap194Mlf2k892U1ZeRyqusMBuBBsA8Bg7vjxj5CKN9s48Atbvr0uLrv8vLz8r+TRhYuY9+yr62LpGEYhd5med242LHPsaPW3KTkxERWIPn41b7616/UuupTlhKKsJm8FE+R8wHwJ+c4kshbzy7J08ONe02Nz/h7EVvJxmAV5hf9PSPzy9wvGhq+yP0yc3zUQNyOKWjG7QOj2IlR0ezutavsbvQo7gXqiTZI7wmfvwz2cCOZ7e3l5ukhOWnUC2nwioZ7d29Y/4EbcQKOnZduNqe/yPYTM5TK5tnXL128hqbEvBR2d+du9lNKXiLPS9KsXCbN7WzjzsFqpZN1jpRqLZHKm87TqLrArtOxxzYL8zonqM4jbeu01mDFDnnrUru0NNg2L3Ppappci3mUqKzlVWbWy2ytk79Met+4zGl2MvaJFxeQZDXNEw1oemVxW3tVR9ska7OxKbbVOvWOwzrkIsil9kk90cLGWy+zdWpdMyhwP1iBZv1vwyhymrl1dbDHyi2yvyQ7lgY6y+b9tbX7D9TWHsA03Mxo4WElLBVLlLOsueF71ozK9w2ooDebyTawjWwmvoEZmIlv2KKn56ELuHObeK4p1FNjayCrpWLsjv1oCaxnrBgX1eXMn5+j1lmvf2+13ldq2AzLzJmzdEtZnW5pJ+hKOk2t5lEG0KjglnvZLV/dg61mZizBVDJiwzefYQhby+r319ZUURe64macxY2jbqxtZuvj2X5NoW40tth6Yc840DOu288jx0dyDBWaf7zdjbS7MEmXCtLTC8pYsTSGlkr31WueLRpympn/GDV7uvzU1FTzZLaI3bFSuhz7en1NiFvxIjYZc3PG80itoxETQr0J5DkdYJ86vL3ty5YfzfuKzUGBgbapL1xRTiy4nrbi5Sn55ff+ws6zM6+x71avxnaFC1+JW7bhb6fQFzsuQEXdwY5GDRwz7onhnY3hn1f/9OOASBwxZuyE2JgxPYxhf6m81OjP26cZRc3Q55bWPHZRE5iBFTNXnsNNsUqlnlFk58ckZ9DlbLOtwWh3PeVfwfIVBZSxtewQ+5DVUnYt+mDbtg/k4uZF7GP2GQ7AwfbW9JlMXwGQT2IuuARX4UpcYv2GRVICVyqxNCwkmExr+CfKAqrh33YFiPQ3GCP5tKv7IuKBVVwqy5kd91zKCkxnm0ZWLdp3lub9XmdeeS332MTca3kYih3w7pjR0WPXWoKWWhftME87UfbJwW4Tn+3bFw3duv/A7eOtRlKrPm2jwecsQ5vZTIkcte7ZjTt3bpywaciEd16gUboHJ2Ho5L3KYPZteNi7b775bng/dr5nT5oyPYlRPfnOgK8ftCt11XOJu1nvBlcZEe4lt1k35B18Rze6Mv8Uu4Mup/LeK8stKMidU1AgV0uT7zWUJcfjKJSJo6Y1H99VWrqLHzaPqS5kuwcfF+hp9HrIcF9Qbd5SXZo/7PDGqtk3ioopyl+yd/EZ7IXOOJitmZeQtthVijAvXDg8mjWE9cNI9EY3fIzVrjMX5WfxfrAYtaNSQL3obZvj9QWQuuAdabStgY6titxm2ZZ3UH9OstvY/mR+5Wjq315WnX40eXpV3P7yhuzCF3NzCgtrkuJx+P0mHBqfvKPZwG6xel8jeg+I3FIua+Ubt2wr37CxnMeogjLWjTyprwLGSAMNDVuk9OzlGxgv1Y1t7uDqObJvzktsC5qf+2NW7XFpj3VSNpasy+piCnynxHpW87DuSpp2k88opFHiGuW2o6ACzbwu26IkNJVqHuxbe9t2SV1Ol9E87jXwsj0ATlXkf56vuhWeujmOFDUa+rda6amXK4eiP8z56DPavWNMrDlbYpuHjE/Noce0YXtT8yrlHWmWm/XWSdLIDt26zMvctc16Thp5KHP3m9azSkL5jIQchy+ozV/0hee/8cXrax2+IH3cFbYcCiR99lWgTQDbrALSR/OKiublFxbm0wAeQcP9Em2rPsCn5QV7t2/fyw8E9ilrIH6KA9GDOJB7mU1Sp5NufQT4txrINdJwdm/TmOTGLR1dlX8KXdidU/lV5bkLFuTSKCizVmkuZCp7n1mJ70+To3Zv27ZbHwA2b8gN1ALNUfiwG7zlhtBpoSs2cM0j3ity69NbDvXyPPC2tVlJOJiVIqtUn/Z4ShLVf2guVv7XJ4RtLtZj6J379Qxz8jOJT6F7DW2J72ffKMq8nJeeMcry1A9Hbjcnn6NJoTEsLCIyuG+7R0yle9+rMpnQtX//xwaFhXZw7lH2dmVFD247jVm5XN3KV0d9duBTbISBWo2k74cIgxSBs9nqJ+MPspNfHaisVLey2hZg/rFRLXDgKzyPgE9yLaUUP01J4POXO/Xcgy+G3l6Oydo+c5ZimtTR4PU0ZQTP3+f+YKk9gVVSRU4cu9F36byupoCKEimoqbSM5wRCT8oxH9L585zdkzZo3uiFqexpNk9JaL4va02lJElfP0oMST5i399Tg2jMl09bK6XYZi8p1npCSbhv3dIC9yUz/zyyKDflMs2sf60a6Wt1KX3UrT6qmdkyXqqxbOkE7U3II0b9M51MDwxsDYE09bGoBcVh5v4Y/rzxsaHBIU9mhM6I69Bhs2unvr27jH+ipcW2T3LKdAvgc5Wrk3cnhTac9F5fWzQzvY/m72Eu0GdH6/tBjvfSVsd7ls1XBXofo8vPh4MOedVF1zNSl18GZ4FHYSn1q4D6pdm+wgOdTLj0FkLln/9cyTt3+TLJlKtd5XhtEPDgB9Ko5cnmadJzytsescgIvc+SFKVooT5+AStTp/mNChrs5d/Jrze/H65O8JeUnk8+7rxsfdcewZ1chwyiu858RqONpTpMn6d8bN/WsqfegGOnSinF81c+y9fK0ceeeUxibBPLZJv27//8az7Zod/3UdGxTaVyQjMdCLHvv0uKrBSxllj1jiNiLIIiVn9UvcPu2v4i3wmm8l8XUCgDMEz/vzH8HsGLnmz3EjhjjP1eBl+Mtd8rbe5V6IxZ9nsNeuArMByyIQcKYA6kQyqkQR59y/SGZAiiaziEESPoLokkfGEYyeRBLh1zIAUSwQKP0ttRkEXyfeluKMwi+sL4Vl25+lMKXVOozlw6zyRJl/+g1QGtrU6gluZSWxlUJ4ukuR2JVOfXtRhNdxlUbxLkk0QyySbq2lL0Gol6j3xJSxadc0gmifSmk5wv1c+m1hP1sof1PK9rySWLskl+5j8p9W0tn6RblUu6svWWwsm2CIh6oJ6jVkhrLduvSxBa/kpZ8Mug6INEI0fWxwnh3NLs1fr1xtalrVde0r61hjtJ81+scCIi7fq70dmPYoAU1xA6hxIR+sEgOkcTkUbpSDrz37FAeJYsRZgIU+g8jYiwkojwFhHhbSLCbiJfPSoA3fe57+O/lPE/+OsfeAplbmRzdHJlYW0KZW5kb2JqCjEyIDAgb2JqCjw8Ci9UeXBlIC9Gb250Ci9TdWJ0eXBlIC9UeXBlMAovQmFzZUZvbnQgL09DSE5VUCtEZWphVnUtU2FucwovVG9Vbmljb2RlIDEzIDAgUgovRW5jb2RpbmcgL0lkZW50aXR5LUgKL0Rlc2NlbmRhbnRGb250cyBbIDE0IDAgUiBdCj4+CmVuZG9iagoxMyAwIG9iago8PAovRmlsdGVyIC9GbGF0ZURlY29kZQovTGVuZ3RoIDQ1NQo+PgpzdHJlYW0KeNpdk02LpDAQhu/+ihxnD4Mak9gDjbDMXPqwH2zv/oAYyx5hWsW2D/3vN+aRWVhB4aGqUu9bpvLX09tpHFaV/1ymcJZV9cPYLXKb7ksQ1cplGLNSq24I607pG65+zvJYfH7cVrmexn7KjkeV/4rB27o81NPXbmrlS5b/WDpZhvGinv68niOf7/P8IVcZV1VkTaM66eNB3/z83V9F5ans+dTF+LA+nmPNv4zfj1mUTlwiJkyd3GYfZPHjRbJjEZ9GHfv4NJmM3X9xqylr+/Duly29tDG9KCrdJKqgAtKJdA+9EHNQDZlEFXWWOm0SmRLyUE1mAXXEDpAlVkIC0cHuHdBi0FLQT+/9yDRkahwZHEXxiQLkoIozcWRxdAiJgicTMi+JDOQgi06HTtNCBwjvDu8G7w7vFp01Oj0ehEyLlhothrk45mLw4PBg8ODwYJmLYy6GDo4Olsx6z2QuNXNpoX6P0a+mn0eLoNqTKWSWuK1wWzKXirmU/FvNvzXUuf1moaXiFEMHt98lZlYxiQqyO1Fn9+5MXjP52Egx5BTDQ2XTxd9v+LYC26Z+7le4L0tcrbTOaae2bRpG+dz4eZq3qu39CyoR/ocKZW5kc3RyZWFtCmVuZG9iagoxNCAwIG9iago8PAovVHlwZSAvRm9udAovU3VidHlwZSAvQ0lERm9udFR5cGUyCi9CYXNlRm9udCAvT0NITlVQK0RlamFWdS1TYW5zCi9DSURTeXN0ZW1JbmZvIDw8Ci9SZWdpc3RyeSAoQWRvYmUpCi9PcmRlcmluZyAoSWRlbnRpdHkpCi9TdXBwbGVtZW50IDAKPj4KL0NJRFRvR0lETWFwIC9JZGVudGl0eQovVyBbIDMgWyAzMTggXSAxNiBbIDM2MSAzMTggMzM3IDYzNiA2MzYgNjM2IDYzNiA2MzYgNjM2IDYzNiBdIDI3IFsgNjM2IDYzNiBdIDM2IFsgNjg0IDY4NiA2OTggNzcwIDYzMiBdIDQyIFsgNzc1IF0gNDQgWyAyOTUgMjk1IF0gNDcgWyA1NTcgODYzIDc0OCA3ODcgNjAzIDc4NyBdIDU0IFsgNjM1IDYxMSBdIDU3IFsgNjg0IF0gNjggWyA2MTMgNjM1IDU1MCA2MzUgNjE1IDM1MiA2MzUgNjM0IDI3OCBdIDc5IFsgMjc4IF0gODEgWyA2MzQgNjEyIF0gODUgWyA0MTEgNTIxIDM5MiA2MzQgNTkyIF0gMTQwIFsgNjMyIF0gMTYzIFsgNjEzIF0gMTY1IFsgNjEzIF0gMTY5IFsgNTUwIF0gMTgxIFsgNjEyIF0gXQovRm9udERlc2NyaXB0b3IgMTUgMCBSCj4+CmVuZG9iagoxNSAwIG9iago8PAovVHlwZSAvRm9udERlc2NyaXB0b3IKL0ZvbnROYW1lIC9PQ0hOVVArRGVqYVZ1LVNhbnMKL0ZvbnRGYW1pbHkgKERlamFWdVwwNDBTYW5zKQovRmxhZ3MgNAovRm9udEJCb3ggWyAwIC0yMzUgODYzIDkyOCBdCi9JdGFsaWNBbmdsZSAwCi9Bc2NlbnQgOTI4Ci9EZXNjZW50IC0yMzUKL0NhcEhlaWdodCA5MjgKL1N0ZW1WIDgwCi9TdGVtSCA4MAovRm9udEZpbGUyIDE2IDAgUgo+PgplbmRvYmoKMTYgMCBvYmoKPDwKL0xlbmd0aDEgMzA0NTIKL0ZpbHRlciAvRmxhdGVEZWNvZGUKL0xlbmd0aCA0MDk1Cj4+CnN0cmVhbQp42u1dCVhUR7Y+dZdutygNDegYhbZZjLiFFhATNTEuaNBBRZOgQVug48aiLW6QoGhEP2IQF4wG0SAoD5Gn6PjQKE+jERHXGCZx4SXCU3RUdIwZDXRXz6nbDWKSeWPeMt8376vze++tqnvqbHXq3Ov3eW0gANAeloAIU4cPDx+9ZlpRDkBiNI6+OGLosOHydfmP2F+C/eTRr4eHtB5sWI59C/b/8vvxffxnNMZTADId+xOjYo0Jaos6DiAgDPuH3zOaE0CNgMS3sd/uvdmLTCExIzoCRE8G6NBqeowx2lMegvPhLh6B03GgTaT6A5TnhX2v6bHzFtpGdKnH/lEAw8ez46OMPuN6BCNrO4DeYbHGhQnufWEe3g9Bfs84Y2yM772BZQBmtJ98nRBvnme7ChGovz+7D8xXIbI0s2hC3ykdXv0RPFoBoyv3ctLYteZRg81ynk5UeahjsdsKBLATzlPH0i4AqjrLedtllYciqQUJ29iIuy/0xTgOwePZ+wL2idSerAEZQDbIm1BkV/tV/AZMgjOytFWJYitJECTkF1tODjMNi4bX0PofVFqqJZvVsaTWbhMj6SyYmtWkw28moRaicd5VoQQtc4c0PK7jkYVHNh7ReOTgkcF48ZqOx9L/Sp68CJzk96FCzgKz6iW8tocKNq4ygFnRNxkqhMm2LMX2RKhQ1SGPBa+hYJYu2a+KHC2kSbW2hiaZz+uPVAdJOPeQZII5eJ0j3YU5wkXow9qyMxwSguFYs++ONhuXbsCcpnFxFPb9IF7UQxDeK5YOw0D4B5MExPyzvv5/Q27Tevyf2Iyxb3ltHjc9je1zybnx2/g5ceLEiRMnTv+o9xM4wKPAiRMnTpw4ceLEiRMnTpw4ceLEiRMnTpw4ceLEiRMnTpw4ceLEiRMnTpw4cfpnJ8t55cK+GmJf8Ggd3wFpQYICvPqAJ7ZUeA6EYBgGI2AUjIVwmAgzYDbEw3w4DdehFurgB5sN2PdKvaA/vI58IyEUxiOfEfniYG5LPlvt38QXTfj510r/A3oBOoEvvIVW5MAVeEx8iQmxm9x5FoJaGCTECVlCMeIG4qHYCtFRDBTHiKlivlgj1kgekj9ixK8iRfpX6arcVh4ovytny2XyBQXVCKrqoWCkarkqX1Whqv5v444d6nbPgY6/CXpEbwcG/A0M4+Dg+H+EuRwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBz/5FgOBKLJd0KKsIz9e3gXnasuWuhsvSEsy8M7VwFIMVB2J8jgqr966RKlyq9a2IYIJXIVGycGohdaFVqfFMpVP8WCAGm2WilDfgBtwR3vdhM0Ts4Gf2eNk+DrDxon0HdjZyE9e8sW/LNlSyNpTR83NtLHpLUcRs/SM3icRaEG0o8YtlEzXUHTqJmsJovIYrIadV8HkCJQdxu0SaeRA7wNGjSaklF0E4k5TUZZ8golc0hpSENVIXJnIfcotOZFAG9kCwiEoMDAgH4++m4qdUBgoMFfctWq1Cogq4RjllDUYzCO3rliyqWFi79++xbRDpvUiT4qLCxcQDIHxG4cuSBryBtnXva/9cXk/IQu9A7Kz0ZvzSi/O/rq5uaqlXTdfHwD3NwM/ooWfYCj0VKdODhzO71Ab0WWzww/FVtWfjC/+MCGnO2fjC+ba6545yZp97Ho7XFiTfVDb+/jL/tnZSzfsGNBgjnJy2e/p+fFkuRd7OuFaPQrD6MgwAuomehEgwYXSKPX6AJEFRUIDaBVVRXWSNnbUiuetRgK6DYy9Thbuxy0OBpndrGvtoZZBa5aeNZwtLda7GTd1vPtng3Ei35N70cenx5xdNbu06d3j/0sXK4qpGs7dKD1f/oz/dHTs/Llvgeysw94+aA9GSg/S1l/L7b+KletQyZx9UG5gtikUO/JMkHn7ybkrdy6dSUepHXop6GnLnV4pWTWdSLTBzXUSutJGOkc+qn4yqHczz7//LPcQ8KiUi8f+pDef+tdev/OTfonJTemkfyu7IuOdNSermjXQ59n9Xv7+AT0Q91ubMWVtdJ388IRF+1Tp4X0Nfn5a9bsyKf5qZm2//iOZi5du50+fvyYPs4LyVyWum5d6rJM4cvNaWmbP12RtnmiZ8mSfRcu7FtS4tntZMblW7cuZ5wkxnmpqfPwwFgsRWvS0JqOLBZBSnSdXVQq3AMB/cBg97+bD2nSjqZeD81+EyMwoGT297SRONUQkWjoXnojNJsMckTJA/0nLxDniZNJhzs3iZuyR7bSSV2FjU0xYhniBCBPVzKkjZIhbKOKOlEvHKb1gjdNuiEEf7XSOmVlldze2kksbvAjKXQpRrACM+suzmsFGvDEmRqd3bzmhreuZQh1ZB0Zun3Llu30MPFbn5m5nrYVpLqGJckb8umDRustocJanZb+0YeCiQ6KnzsnYcfRvatytZ6Vn5y6wrLRbKuVfTFCnbDD8sORE4FBrhimpgSRfU11qTagD4gTgdQ608x7y+luupisIONX3JOnVU2JpOX0W3qZlkdOuRQSQraS98h0snUE+o7eyHsc3qAvjph76+xXNP4RCSAe9DqtpENwXgnJotNpGDXKfRoXkI6kN+lJ3HfQjXQJ/YBmob0sOukor61j9ziOCnGP9XdCuTVYeGIZxDbH8EJrbaHDP5aPuNu8cW/qNCqpyS3JvaXD0nF6QHBOpDe30VyaSNJJ5Fqijk+wpNN6eo+4EOdZBVUkc4c1ZfwEsonEkjiyKWT4N1Om0nP0Iv2KnvMGu3Vknb0uuxg0+orTp+WqBj8ctGVRk3KnrXLHSeWoTBWnz9aOHrwiDtnW0YePCrO+cPg4E3llhZd5d1r4xjIFebCk2u+rPPB+OxYDzCysOgTTQ19BepH3SQrp9SVNqaQpJ+QqSyvxSYOf7GEBCRquO+bKBpzbWpmrQfHKRCch6wR9YJ2Jcxo9pOsNftL1Rg+WxSx+l58+TViwDMpzxNceOOUs+l6jViJeu0YItV0jA8hCupKepF/SNLJIDqWl9Aa9SUtJCPkd6UxC8ugkmsM2DMnDsoGFA+x5Iq1W8sRFyZPmVJdYkmNhJevo6s2bV9P+5FQjU9NIT8t9rOfXpq1Yu6P2anWNtYBZS584rO3yrLUuRO/bnNDsLDxj82DS5lG1Tu9kN5m8wly4+EvLG87T6vuCQPKJkdmt+GGhH7O4sqduLmr2dewjpZi4u//ykeTry8qgF5ZBKcR8Zkr+vgU7Ftd8Q6tp3cz7S5Luzt19OG1zUs1p4v7jjCty3pdBgUvmR8V4dPK7fODy9337XBg2fOUHcckeHXsd3XXyP31YZjVg5G5j5NRYftluwEeQSrpvra+01uNGaKiSWf41VyMVAKtE+EcYZT15iVwmV76yluOqu0u3WaYKkISe9JKSsGp5t6zfAUEafQArnUoR17V8proJZd8VLY3fdLC0dPDhlUWV1kYi7Nw49UB4TFnEDw8Egylpmvny/pdCrUsLTcZjuUeOOqek9+5d6OtrYfoOob48lRbXDN8RSFMdRpWEyWYvLqjTF5+tBvHGzrVrd7LD+vGAvUlnbLYzSXsHHDwo9Kmsq6vEQxgXbaSH6RPEYWN0AQpFz+fYasU69KdTy5UxOCpcN0eFE+vGbAnbd/LkvrAtY0bnv2ulf8S9pJqQKwUU+fnVnj1b6+dX6OVFBpH2xJkM0DO7Ua4UgSqcFLtxJ9nDY3/fciMtHmpibmnpgL3JlTZbZfJeazk6UFCATogHhMif7hZEG8lQ0gox1EhdHY40yU9Bu7XQmVmuc2s22tOR12rFG7WUYilpd/bfZpZPi7owiz6i5eQlSw1Rlwr5KzcfbC9ERpSV9+tX3KMn6U/aYCF7g1af2Li/OIfFBp/QwhP0ge05VxYZV3sGYXFiqyw82RM1mvShFw/u2VN8RKXdFDY9KsPSR7yYMeZz5S1oDp0oRaCNbZX3rxZr5+4ktMj6loFxDzCIufkb1ufnr9+QX0ppg7Fo7NiccX/YH1ySfM5iOZdcElwqDDx17dqp8mvX7tAaertL1309exz590lR03BbikQiA6ZFKXUQH7NStMN6NNquHhsG5Z3KTYouTU7eUHTw4JB9icdOCnnWyULO1pyyPGuaSmvNiYm+zzw4hnMXqdhXqGp7zWavccdKkaSpjdtU2tuo5ymPwoF3Vdqf7jZbgP7/wgLXv2OBNLWYGWBf5UQlgu7Pvi0987ZuXl+0a8O6oqJ1D4gzrX/wZ3qfaMTv6ioq6m6dKr+dTU/Ru/QeLnwwrq+W9LdbJo5Cueyp6/Mzs9zFUR4je2bvPHhwwKEPXXq/KO531lSWWUvQKFOULOPseNwz5Tj7V6oZqwA/r2ZMqJg+piBi1app6wefyH/8bcTx2aaTxtSPYna9tuuT78+Z9kuDi7t3Dw9/baSufY9Nq7IP6PVlAQHvjH0zzLuD14bUnKKuqDUIF+ShnGOPJktEjAWuBlYclpAasoAk0Q/fNB85UpWblibn0C8yrNtWjdm89SthagYZxFazGKP5trIeuPVdMBHs0WzenD6kmK3I7tLSN/YmHjtFzpNDwg6rcevWsjwhqXFbkSnqgViAlgzEdU2RprJq6aIUS/3A4ySSRB6nkxukqZZwsahxG3upM0v14jiVqfnvYenl9NAmlYmuxHt6miiwX85Db3S/EjghPChw4fzeb/l1G9XnlVf9eg2a0fedSe3aLdN06Nu761sDwWazv+uoY5192O5yUrv7SDkkEceVCq0y4fhQHFfB/HHQPBrUNCrkKKNzaCKrfjg6nMmAxexXCtk4yztFxji7DDPL5wNyF3GUKkipOL726qK3p4y7vfwY7FG0BLvpXvDxEt4XTJN8XvN+pidHBGldRo5LW/eirqkBxHJeqre9LD9hESUGF72vWm/NPXwpfceOdPkJ/UtJCftuWg0R7GtwCd9NSF/l+3DWJuBG+jraArQiwx1tscW41KItQ0cyxtFWgZaY4A2IhwRYBHNhBrwH02Eevld3hyh4Ca/+0BdhwNY05PCEIcgzD8x4zIUYMEIs9MTRkRCH/L2x9TrMRnhi1JpkmZVeDF5jcM58PEcjZ5vn0BrYrDUcNc1HXTNxThxyMzuMOOe3aRyKrZk4byIkIkcU8hoVaTHKDKPikSdKicNzAvJMQ7kzkM8T58ejdqNy7+dyxitSzGhRPGIWjjKtZuSNVyT5o24D7t2Ws5rmOH6j0/Yt+33RXyWB/YIo5iPjVL7Av5IWr/yOZtPvjSpXdqdd8wxn5BaVd5pOeO6Mz1+Cf7/rjuceCIIr1kt5tvXDcyBaRiAYQdDCUDz/HkFgLEaQwAR4B88fIQhsRxDIRxD4FwSBPyCIorsNfA+3IAxebQfqasWIVNybU/GdqspuFGu3pKY++81XpT3h7/+3AaQ9yp3/HP+/QISdV4lpU7uFjGfGI1r05z5tC/0BGlmcX22e2h29bGMXwk5/BVazwokKZW5kc3RyZWFtCmVuZG9iagoxNyAwIG9iago8PAovVHlwZSAvWE9iamVjdAovU3VidHlwZSAvSW1hZ2UKL1dpZHRoIDU5NQovSGVpZ2h0IDg0MgovQml0c1BlckNvbXBvbmVudCA4Ci9GaWx0ZXIgL0ZsYXRlRGVjb2RlCi9Db2xvclNwYWNlIC9EZXZpY2VSR0IKL1NNYXNrIDE4IDAgUgovTGVuZ3RoIDE0NzkKPj4Kc3RyZWFtCnic7cExAQAAAMKg9U9tDB+gAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAPgY8EQAAQplbmRzdHJlYW0KZW5kb2JqCjE4IDAgb2JqCjw8Ci9UeXBlIC9YT2JqZWN0Ci9TdWJ0eXBlIC9JbWFnZQovV2lkdGggNTk1Ci9IZWlnaHQgODQyCi9CaXRzUGVyQ29tcG9uZW50IDgKL0ZpbHRlciAvRmxhdGVEZWNvZGUKL0NvbG9yU3BhY2UgL0RldmljZUdyYXkKL0RlY29kZSBbIDEgMCBdCi9MZW5ndGggMTkyNzUKPj4Kc3RyZWFtCnic7Z3/YaM8D8cZgQ3KBs0GYYNkg3QDbgO6Ae8GPBswAiMwAiMwQt5YtkGyZUjv2ubX9/PHXQIG3FhIsizb5zMAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAPDPTEPXtl0/3boe4Dnoq13mKD76W9cGPDxtmQmK9tY1Ao/GOLEvQyBQJFT9jWoGHouLu9RUH7siy7rlYOOk6P3UtG1T7d3Xz5vVEjwAY9/WH8ciX7RQO5/7tFqpnvyBqS3o0McNKgrunskppYjalyCJyht5mRUqyBRYMErJ/D8p0pRlb++n1hUkiSrG8PqRZOrPL9YY3DnGxE3+w8Lu4i4NIys36hJ1kcWdOdP9QlXBY/B2kYfBfDCS8bY/1W1Xa6asSEjURabMqXz60VqCO+TzY7cbleMHr2L6WSm1l0OHoJg5lvX6rQfhcoEnZhq7i6fU2C9GCe2muNDpcryRh4yIFEGxYs0Jr6GmnpxxaJvquHPO0cEeNKKTlXFhIw5VcL2REHmoN1ePqQdOOdTUU2KVUhkGAnb2bJXpPbNWUT+Zd9lnTuuRgloXV/DY9GoUYNY3LvIdRbr7Repm3iKVVKQ9KcMUCyF4TNqLUvKfx1CU3g6m++bH6Dp3uAluMSqOUxlGBRRTGF/R/t3fAO6JUXg4Tmbe3k9VEFMyDF7UuuCEORYcOoUCYlTZfq0mVeyRgUfkJHr2xly1InGAQ7bJuNH5IE/EVo5co5ofaNZdKT3uAO6UsW+b1CnSOq3/ulv3d4w4kfULApbKZZHLHslYiOaRgTul1HxqCymppakjcyWhMHkby5RyWRfauU2R0jwycD/0xyKflcRJ86kJ54/PJav1drdhciMcMuSpXBYJCETqwRFWhGQg+08pZpXU4sJsODwuTE7xqSM7rlw2hS67FrxKVxnckounNMYH+Svf2ojAoJbKeMlu3UX2YfKjuYiFPLXL8sBl77YkJjKV4EYk3B+uJFw8KU4CME7WjseLtKE5htc0Nhllcc+0y0yRgX3fjEspwzrgh5nGUenfV7qfxPv1szIKrqZgeW/UiT8xrbf7bJts0tz8WO2yQyjq+XpvkuRb+UPADzE2x8KarzIwcwn3h/fr52zLII2goEvnbCcDly+lFrM2GvOMS4hyWSTqp3UtRHI/pM+Db6UvM87HyM4lIoTCHpoWJ/9HyB65WOOS7WR4W2/XxZwOOXfPlFhnE0qQMb8r6Svtus0F30kgUOQaT/PZhPsj+vXk1xyl/zPnL4lsJyFfMUx0RHhKuSwS9Y30lWL1LPhOPp0Y5YfT6bTPnVs0+tMJt1fYQ/JrQp/aKSnpFgfZdD5typ/n5pRCE849U/oIRtRlD4+y7MazTpPFig78HRefe/X8hxWh2pfqT4FM6e6P6Ndbv8b61HN4yikpGTCy8hWlTfnzQnRYyFPprcWiTmoqkRJFvhnmXf0zzOduhkQZkqi8FZcVQqYUP+Yc2EPn14zc//FKSoYYzdE8jwytPy/D5KdZ2rQ4ZhaJehOa3hmazqDPdADXE6w2sWu1QmT19pM8OFFb+vddd39Ev977NZSdYm0PNWJtPomoaB9Jk7ni7eROy+6lNaUm5KnFMRVRLxMyZW/UKn8/uJ6+iFpOWcGEWvgUX21kyveeErHOnCmJ2a9ZfOrPRS2YY/6qkVeI0qa6YVpuGoTJSS6NjGjjc2Us6m4O6BSUHOhwHf8N4HqmP14BvDOfO07rLpS3n64v8nlZgUTUmYcDFr/G+z9jsTSiUCckSiaXsx/PMWH30rtn0YjeWRd1Z7PF4ekzg0T9M+POylM9+AONVVrBNLk2S3kYLOMyMR4r7GE2qywa8v04/2GyYSrT+5K6Z+aJwuQUnrpcrVymph5YmboIlSs89VUOidrErFxSfXx81N2QKKC8q26xCSlAhW7TJInhVhEOYC1+JJnK2J2FOhHyFcPNKUGmOad3ZJBFdVEfj14/l8elTxmuvAGIZTmlhUIEuj2ko45TcHQss8DM9dk1AWXNjzkH9rBcVJZ1hfk1ohuX8Mw8cXSdunFFGV+WyixoxS9E7Mf0E1+ZXfRLEbFQfaYUPXXk/sjvWjmJ5secAyXBBcXZnkUCRDeuWn+m0r2s/V/ayOMJUV+WlPIa6tCnn/fanHSRinrN1Kmq0rfo569FpBJUdPdHhJuEX2OHfJfWFt24xCg0r2ETHKv8yyMPJ0TdVq6yXZL8vWqn9NNeHffLup73ePGoToX2Wxept9d1ymc5iHzhBDtV8oSSkH7NIJSU7MYFYYIQtXtZ2j8zvCxXRZ3VcO0kONv3+zDKY8qqgabNkr90zxvbfNlf8eCE+8OVRODXtOKbEN3EKDS7MlZizj3bSsIDX0V/v8l75Q5SuWpZzFkfFk9EByIqxRid4yQ83uK16NUZdTK5zxuqUZjTGeuebSbhgS+SeL9t5KbzX8c1JeXU1GA/q4EdhUb3zbiSiPyann8R3TguXzEJn9u6Z8FlvQi8g6+Ter9tstrkvrXqa75QLirnWpHyI3gBwh6u+jWiGxeHCQQJn3tYf1PA35F6v8n21e6L1mUKC5fLx+qK5w66lAp7uOrXCOFTR6EvfY3efkpF17tLn2S6orLgKyTf75KpKdO2/cpNluG4q30pdglHSOSqXyO6cVzmefS2uq7+4DtR328DOUiN/bzuqpy5idIyRlQUP+YcSGTChVdKGvn6iBbDnwtsRNfBt5K2aawfl/BFFhYTldA+MboxEkHLVSMqunFtpuMK9PEaQeDHUMOARLNYvk2RKhfLkq97yjO6VRNDKwkX3iK6cX0sTSZ6630p8JukfR/qw/f08Ssidciu6/JVqiwX3A4nXHgHr9Q4S1L+ftAWLgO/hx4GJN5mm6j7PQwmUqz3t/ngaIZcL560bkSF5XSL4ScXLgO/R3Lonc+0TXXCZ1iXiqaU9IlyLZt2nCvqrJA6c1WUF/8N3Bdpo1bNrszmKAVv+9OKmiqYGNVZJHt/Mim7q6LcQSndKelmMyZsT590v2ehz4Ix3EQnsuVSZLdgaZez00cWPKfMsO/PA7KLdIWnnUVKiIzCos/8N3WCLg3U7uevtpv2Mdhv06exhHKhFsSTHpJ0sy0iteofncN08+SUyWNg11w0qTh+fLjppsHUiOb9VK08FtwnIhIkqBedUq1249pAVEj9RDJl7Zp4VFdkktP0xdqDO0TEqwXMnPWxK80owluQ5x1MIOl3WRyvGE9coPbJJ4BHQk/CM5RMqZShm8P4DJTU2c8WKJaIgVsbKN7FbHT7med7mLhnIZlkO3LNRF900zeE/TRD4xRP+VHXdVXmq3Zt3FoIBjwUySRb8pAm/41kRDOQlKwXKzA/S4qBqZSvQp7pIepCWkSyXOUYlurM5WrIIJhNuayHAJ6dRBIeKalu+W4XPAkmsLuVN+TBmf707uTp7dBM31Nb8ADoSXhkuIroiBGqyR9xq03Itckk09D3PSYIvBh6Et4uiyRt8j3+sqrNapjO5y6GX6nmXTHeugL3jZaEN5VaN05bbCKrpt+o5D3xWeTYfHYVJQnPrnYXB5HOYx0I1QtGJymeMty6FndNlITnwpKJhU3bQ+77cPuX9LlPsUsAJDwJbxzayumhcPlWxtR3baeuYfgsdBdXcdJP2Zzk5jdr83jQWyeXDH/JsKRZOL2zH00vODFMbvso1W9V6jF5i31udR28Z8Xv5pAtHkCVxQ6mxc3FwQL6q+wCedq/Rpw72s0hWzwAO0SpLaBv/UzsFLrOnGBCC5f1063r8xtMclbygj3tkgOb6Do/B3V7NdKXpqYlw19rbsAUyVJuF063pwd3sA+vMzrtYxE9AGZmJRXv5nBeppqGWyvb/NXNOWjgyZiGrm3bflgtZBzID303B8PsW8kCpKSwEMxr0X+Wsyk7riz8uzE10Sgi6vaJTDCXZI+JOy9EuFdpnoyGrC405GYQ1mHfziqprWXWwfMwBgJFWqbRy64uNOSnogXhqc/MZhumZ4CA56JzLvf7qbn4UvWhsF/1kZXVhYbmJUdJRn14at5oKz0DBDwVn9bUsThttP0tY32hIZ+eYVNZm+UBdK/kDBDwMNCQyceuuFBWy0wugZWoIPBv92HUZGpjtT6jiPbnM99amQILrfmUnAEC7p8pHjK5ULZxSTvDuY9ucApdbI85PiUfPKdnLFsrnxbdlK9eC+6a2N+2tqwLytlU+VG5A7nY0c6m12wLaSPkfjb+oqQ2l1kH98I0xcdElsTb2/I1GNI9ZYmpX25xjz46bDzvLl2ZfJY4GkIuJqak0sswgzviY5drGUqm4cXym0O7d9ZvYsVG5kWHkIsd33ojXrnLxB4m2Y4pqc2tBcAdYIdx++i41vBubY4yKJbsg+lrhLgwAbvtpQ/wcazcNx5dr7y55ddWZ3DXdJGUWKKGJ9pcOkijLo8eo+qO0T0yG680aVNsK969Oy2i62UmJV6ZAQJ+H9N0bZvKxqqCRvMkGs/27XteaiVQRIv4hQ82Qpwfo7QpfxsRXbfhqb24IZLwboa1J0vTaRGAWQ9EaqrL9B0jB+szs6ublTrkijs9Zio+3iSj6yTCo7gWsc7b0BdKq8XRIwoW7EtFTSUbj/phjftiRGZYqUal+D5BEl6YNhVE18dcKEtzxcrzwHcyus2BBvtNVwVRUrexJHWvqKkp2Xjl0uab0Wx1QI/0psvlHOO/I7hnL4JYSML7efiOZURnj8/2hJqubdxm3P8Fl9ekoDQ1lacaj/XjNl0bVdftlKcxzO0n9n0IrxUHwPcxxjuWZcwmmde5Fmm4jSkbRiVLaj9NTaUbL5+tmbluv1ZJVdddkYQ3pk4iCe8HOUXCZJVSa08rqoBGzQLJya2aKeOWSjd8NeumTZFSfZ9rkvBSJzeuBdcwjaM6haYWokQ7lvG5Ntrr3IU2hWSicv8HBirdeP18m78TqauS8BIgCe8f6T/dWlL5Mcosab2npO9YpubUlqGYNF4jxGoq3fBkzQbzaTt/SROp65LwdDauBeu0pVBEQTb3hmusvs5N2CAH77fEamql8d6ya/OXBq3AdUl46RsiMPWXKJElEQLYiPp1mkREDZLP3yM1tdLw5axH8my9T68GTK9MwlPZuBas8Mf724fT6bS35k9u9KLZlAX1dQ61ypCJbSDkCqHpxjvNInXY8JYrVeNELp1g/V3JV68FSez6itm+Gd0BJZt7Peqn26RADFsmEZGaSjf8IlLGkq7tVFpkWu9tu+bpdwWxzr9kR/LT80OjPTaJMkP6FtrrHKouIxv+IdEIcLrxDrNIbWQi9LpYlqqgiZrrD7bPztMPBCnI6kWbdFDSwJJYshH10ySiDdyUgmuyIrhfuuEXX0pPXxFVVDztRM395iOr78qAhbf/BooP1PHxk1BTG1G/gyIRpbxkFBIWqqm0yObLrdnoTEyXOCnDBMuQ0sdSc/3B4C+hhA7t1Z8KvjL1RtRPkQhKIhiX76bJq+VroKaS8SGydoP7UkprHFRXj0NQmMAuXCaGlPb2NCLk385nlphzch569uWKiGEljpDS4EJYSSUSqKlkfKjlnj+pKd1DPwYSLCrCJGnGPbyrmsSUQfCXhE5Ngo2oXygRdtcZIaq7wHmWD07Gh8os3FD5onPiYh8J853IvHnbn9TC4N+Jul4J9MDR6DOCjUTYUCUleZfUbmIlsCkLgpm1eHIqPkQC0S7fy0hUqZSR1+yk1nxikiRm4YCf4WrvNGdKhqVNDfYISdy8YK+zLAO/vhd67CJ4jRCWVHxoF4jaRMKTi9C+29Vd2WbC19wopRdbU/J25AkPJMKECfo+Spvq7FmuChzBrjMVCdAY3GGRFr0in4GS8jKVFR+9++424krvwQ2l9KtsDAczDppLsnSW3sIToRNdZqqXXPvzRlKG8KH/SbGz1P7aXVkuKyk04bXgNqjjvSqnWByMORncaas7XKZwpbSxLpHLLCnNApNtjHXXUES32Q9hIXAjVtOFrNM0LCWdFGg+rpG4ao41G5Ukw469kCM3u6BgTz9FUjgeqXCr1MtPb/cC1StlwG2odZPBXZ7WHqKuYdrHlRFDyhIWMUmSyHDKU8vUlNFIFbvAu0itXvGxObxb+a5WVn8Fv08c9e74BJhsUSNLmEAliK6TUuIx+TJUW0S+3H+ObFF30u9VikHbhyM2fG3opjhB2UjCC6ProTtlRGRSH+/UFMVSw1k4qa3NwP2SGEjxLpNRYnt7fD2xKI6u70z5gZ9WdNy0qCklyA0X6RGJh9ZGHhbk2QPr6WhRdF26U6Gn5GFqSopTfnjJvUqfgI2hu5Epl132tSS8hlnN5IJyTE3ZyJbtDCI6+biQOZuSp3umpb6chMfdqSKl4hY1VVcYMnkKylVB4TlOX07CowwmO3ScVoaTmRo4XVtb8AAYLZGeInBicpJyh1jRVh4aZndqI9sKPBPU0RpTZ7m9uiIJrw6OkTtl8tfj0Dh4Xsqoz7cgJiQk4gC8bHSfo3OnDpde5Phv9QQPw9oUgYIbMyUJz25qPtFnNS1zotHA76koeBiMmtKTzz+lUz13DoNNzQc6uxFdBy8ExSS1jEgjUdzjNmGCWiZuEh2dnUy8/Reqe3PGW1fgASAnOtZTJFEVO1BmOo09/eQxpUU1t7euygNAiSdFK44NJEAiPyVMwqNUlacPdIerb2Nz2quw6XVMqPpjFqsul4Tn8+em363j7zNUYZ6PBeviXYNP2Syruq6r0r2S+0kU6mT+3NPTaFb+oprbW1fsMVCWLMubW1fqxvDMseTC6SBNK4UqD/Z6fVIoI9pQd1N4zsR2s/cXU83fS3fyUvV2evKR3GhLALL6rSykT7AGX2PqL7zAOxllQ1uCXq85NN2kfuDeGcUiNGdn01ShGlmp9TxW8IKwRaWCjr9LdHc50eNF5Bo3m5ov5FBm2NsYEDSaLT2lMIXCHBuCq2woly03s5HHCl6CcRnNlgYtKKfaNLtJ6bKX0sZUbPC02BSbHSkibX0ymnAfXJOwaaSo5iRXNQUMPC9Bio2bZMhEaW1RqZRNM6I255+qKWDg+ZisUsojbTSas8ai7bdHs6uETbNTMCb7BSlgz41RSp35oA69mSGTwZzdxX63RtKm9UxNbUywBg/OPJuik6IUpNhc2UtLr6tVMm8qj534aeiwAPGTMM+mGJxSOpzqPFZJG7MNPWmb1meLHDGVpyyPBB6EqW0+WuX4POI2LeO4ysp5waJEyadkyfG7fBFKc/8/8WBgc8WfAW6NGccd6ROFATqliDk+yUPK9MBrJ6EqNo3d1Allpbtt1RX3B7eC25OOjpBPLFZMdyjRSWUC9Ma6IeJuykPcTYvlY9AHMGlTo3oduClqckljz9EKLsossDLWXkq/7dqMFMVmOvqlnzcnLIQrQoL7opEr3YX2ZJfpMqUtupDFo3d5bB810lPq2ZR+UnlPP2HjMZkuSqn1X+pImOzW7qM97VICopmFyoib1m+7MiNlZdGQLOPTXZGEd5+IoY0l/83Yk2jIxPvEYb9Ni04uNmomtTjaFXdjN+2Xj5NeCvwmUzSuJtSJka8iPWQy+8R/5HFtxE1RSbF9pMFAeWh10RAmUkjCuy18G8VcJnKLoY2NoTNaLoYcKrH3kHrZLouWCKlnizbywcBQI6UrMS2+FJLwboU+jisSuXP2um8MnZH+sKlLDT+uXaa47EYiyzpKm4o0UrISA7N2SML7VabJfzqE7raDaZldxsJAXL5irE9sZarnJ5TLlISCTq9LpJGSNq3NFp8cSXi/x3hRSpX/IhdLyN8P+7392MzlRRhIyFeM1RK0KqMIeSqXKcMvYRKejU52Y/iUXSix/K85uM9Iwvs9Tvy3tg61yHgbKVIwb2MlR3PTYUbC6Q/qGPLwlHKZklAwOVHaWgQkZdNo2Wx/Akl4v8Yo3BN1XI20TO2/iTDQRrZAmVmfmCSVrR2jXKYNvxiJbLcXAUkl4ZEkj+4LkvC+lfHSfWsS507CPdE75HVS6lbCjP7mrb8DC3kql2kJBRtmld9NsWmU1jkfX0lYAF9niPzjmd7aFv9Vf5cn6xMtN1vXaguLT0ySO7evdlmeqekJbfruHsVmGv5wJRV3CXygZNh+wKszKYfIGxq10qUVqfkcl68F3qcSQxsrYUYD84npQT7kqV2mJBRsmFVeifg9+BRCvKg8F+MqvNPfbj/glZlMdLKOj+ehf+zxIyq9P6B3yEtehKusjaEz5hOTGfLBCO0yZfhlw6x6VJv2qXUJSmVqYLP9gFemT6ijtyzwjz3+F279gZ1qIndc0ITUcfkibNqUO8/tqA1P/Ze47J+T8OTdpiP9EkNwf4WXX3trAztOG7uqLoIZbQdCSsr8+rU/orovUqmUXJ14+QrSptx5OXqTL/pQUYbL8MvMhlmdCW3m9EmPysUfMg84WtamBoKF0v5cY3jcv6GhsBkJ+BAdJrVD/ikuFVJnnlgeo7Qpfz7ntWE6VIilRYlFbpjVGWYzL55S5X6FwPG2Nl7dIBykSUjOktckh29t4EZ0mLQOeS/FVAxtJMxJ5U7vhP5YQp6KMuwVlWTKTyt/L6vERxuMBu5HWWiEUvoLTKtUQjE4TFse6fdu+GFSUrLDpHTImzwTJkmokzoThOYkCJNTaePSKSNuWvxC7yxEBJUggeq3LwPbGBXT14qeMYLiUgI6WfzSYqLDJDvkxowYgRKJmWJoY8OchGGAyt1MsXJa/KLMrk7CE4Jd99sXgWswLTBNipqyGiAYviURq8+yw0TyZaKAcopCE93MQfI1nVNEYYBjRsKkRScVlRTax0t3khbDr2SxfpYlmquQrg74Kjl5I4qacj0v+unnWM2n/yI6THlsRMRVX0/CO4ia7MzVn9pl5kwvDzn7GM3CCd14rDv9QwxWJWhqymkAMnUuPEV9+sZ8EkHGN12kuKLi9xfypVdJ+tzW/P7J4r6c4rIbiSyUWTjXRBbAN9A40VDU1M4ponppkNOsKESQ8TC3m1/+cmjtsf/CmxGK/DKUMMA4K5vgMiV+0anCnb+dkg8E38rBNZOipmYNcPJ2wzS2UwoiyGgKlKGrTWIwR+VFN07IV4x5yiQPDV7rBJcp8YtRiBJmdf46hVc7sZpael6laZxPrqTiqEAV3ZpkypcR3bggTBCihQF8By24THHZJ6uUzNRAeEo3YJybJFZTS8/LDt82TEnJIKPWvXdlfGan6MaFYYKAMlPCAG5sJLhMxi9cbRCdvCXt0kqRmmI9L+vL7Fj7ie6XFsQ2lIsIim5cFCaQKD732ccmg8tEfAzcA6b1evsxUlO85zX7Mp0/a774z6moQLXIgOjGRWECiRIm93WNlKHpDaTvBH6fHROMUE2JnpeLDO7ns8Lh4fLFYAZR3CwOE6QuiyqLUMCdM3IpITU1sLOi52V9mXE+ucs2k/BIDv3t+c2UMAFVwPlAYvSGn3/fn5rEXwLuhE54J8ZO8fQoKSiBEhMOj5CvBW7gIq02zcWWqea2wEZ0HdwzlehbUY+uX84GPa9KaCIRZNQdajrsy4ibkXxFi+GLlfD+7g/6AbqmGm9dhwdiJ7SFDVnKry0rXXIHRwQZlSD22fUTO+1mZabjCphZnX/193wfU/PhlsQqsdTGF5gCfzdQU2HPaxrZFxFkVILYZxEZvSIJz0Qn++geN+I/41dm5XimYHB/49o8EH0oCVJNpXpehAgyKkHs8/SRcSmKwu2eranmt8AP6hT9+CfDsmVfoBaWbRq6SqipVM/Lls6SSXh0+pN8pOWguFl755uam1frNA+GY6WN6zEuzTDxlaIzrqbWe155FiThuYvs3dxbPs7Fxc3GOx/H3dGYgst/0OYyggT0g8VeTe9Or/e8TK9t8F+MfMXrTvPZAZNRSj/xR/wEb26S8UVb5ejvfYFecZKFmjKCMqauNnah81/elNsEG5o/Em/522g/TVtFp66t66brf7Q+D0PDBcDNLhi4mtplK3lNxt9o/JdDIE75e9WnLnwApivL9dWilkts2+DkIJzyxDt9q3lNURIe3e2VMt7aMniRPsZbV+nWGLs2hQd5bGo1r0lEBRqT8XZfgYCfZgwFyvC5fd0zk8gHYGpqNa/JeGKHn6nZI0CTXzOz7W3b9X1zchaQoqMvSyKSydTUal7T9PRKaTSj2ZN+7tP2QJrldG+N/0uHHESXLThu1dRGXtOzQzJSq6dIosI1gWwc65VlyvwAo3K8n9VUIq/pVSAJWZZFZrQJ2aHRh9d9CdOx8XJWU8+dhjuNfd9PydNuoK9WzhQpbUSDl3+UEy9B2lHqD7dPLvlppmYeNPro9CKdC7FN0ZlT2r6dWIf55RChyhejlwGA4n9aIWPF9pqaIs+g1e9M89OilQNfhN3Lvk7TnyieVPRxsZ2ZLK2pqXKtI7x4oi/HZJJLbl2Jm9A7i5dffoD6tE8FKScSHJ7r7CAfa0ze3gjc8ZurDG6PSbEZ9VP/WXmaxyCntlBlqifHoI/VlAkA79OPVq4Ajw9ZHz1zzkpUNfFjtSZTlTVgZaSmyrQnReQva/meGSsjo3KGVsiKPCc7mVoeNZJz1pROvmr3xBxr8DTYDp3W8UpElEimWnHIm7dQTZkhhdX47+owFrhD+uajLIpdWa2sr+lc7j468ZnSXk24QHXvdU2opvgUapWNma1u+uKULgF+k9HuoeD46PVSptXV+BCFvRv1miH4bpzwjj4Famp1kodBTPRgz5Z7QIfPAzchDijpSW8kDpqX3K4rEE45q7NATa1ORSOyLErZH4qw5t111QA/yn+zhsrf/Ee554vDiMNUK2qq2OisMfJF+KSa0uYsSjSRCgTq7b2/rhrgJ/m0rbFvKA956l3Wm5JImZt0gClWU/F0wyQDExypprYzfhSRmvyrcMeTF5+M4eJmlGV5rOO90j1WonhAaVTjSbbRP2wkQaopfZ69SpMFSzjU81N1V0k+PhLcF0rJvwekz122aiGSqHAHWOui9EFR51nHaiqVdKhgis4Pk2oqz9bjUpv+O/hhxmPouWoTACnThO9K4y4uFJVwcG0eqalddnVPqxCqSKgp86VZudQMC1bXPQX8BH5agBSqMSxWqBJFCmQ/xGVJyiI1lcdOToJBahqhpprIoMZV7a57DPh+7PIuxuem9MrJz7XMO1nuU5UzQ92ER8bZsw7VlOI3J2gzGTLnaopPS1Potnwt8E+YUPGwcnpHAlRP7JhLDPhPFCyy67c9b2fDFKqp60XqFEiNUFNGvtLpK+Ys1nr5OVYnl7pt0XZjcNR25Dp25AshSiEOgZq6XqSMqE/8AFdTq1l2NNNhvLau4MusTi61vbjTFB2nyDffFL78gpLiC28Haiq/trWNbbOxJz6MItSUsjU9lS+gpP6Zqas/Pspj1fTKydVReXrbT9oZCjYv6oUChdO19eGetVRTRtiGa+5h/KEyWttIqimts2AtOX8ZwFeZPsvlF8/juSaroeYi/bIb7bZYzM3Bf07HFaNUU1fP4KgylVlN1QmZsr7hVY8AKpOIURrCkNJaqHnV6zhmQbe9urZSRhy6+ZtQU1dHz3ehLL0dTrssiE3FXVAbeb26piBiGcZlBLkB5tCkX16sNfCyP+nZSkm7WhW2t1UpnijUVL8i4JzJ/zF8bSPR6XNd1c+RX/VJx05XPABcfs+PY/RO/rE/+74yq1NNQ3uyEiYHTd6SmmhYU1JSvSQHUpYNjOeHGnHgplaoKS5fKxjp2UWjuyVXU9PRqq8PN1156j7sn19t3x6cXT9mkMc+rFLq2SEbUsr5oTIlDaR6DulHTkziykgSRrliLVNifaD7hJqqsnTgeyo+fJ6oHvoI8qZq/+iiLOfEunDlDZDiU7QaQToqnBcwkV+bD8uRU9JmlRvWrFzaNdZSkf/c+DN1eFuuptYiSu1iFWMRng/Xy9dxF1YiTDZ+dcahbVOnCtFqBhIypc9DXTVmI+sstZ6OKRhfL+/k1E0slw1rx7cdtzflok/Zetk9O5voZBbL88wVSolosky35/KUP/TypD+BabfEmiMn+skqdmRMSJTrx12xw8PmRBNyaOzHKpLLbl6vdgyeYW7bRutl+wqR16/+lfSOjPOT91qZMqrH2J72OfUIq5U1YF4VsiXqWpOjbRYuGUWWXLuEfIzWf0smD23Gmlj8IZbLiW9fzN2nPjJGlp7XTvkrG/YXJmMWkZoCY1t9lGWpB7qtLflPOWOVFO9HrYaUyLjMj8wSo3Pb4cvF/PSpm1h4cJNbRGeP3ndcb5aqTAl7bYp06pOKiz7Sz7wkblcX9zvH85U6+TovOCXFG3WXMmdz+dY/dREMyVdEKt4dXtAwe3SY/8Rl9W3R6dNWP7Qzb+ZxlPTTpmm1xq/FeArf3qKTJQYnbGN4qbmyEJKxEVI6ZVfs8PAVkVKcmPB5HXtctHGWiE25nWGWd6q3YwBzP3V1EAl41NxJGej2IePQRbJKR4QsTRMd0g8jf2ZyX4xCG5RCSYs4w0SqWS1cLI/TxUGO9PnOf15+1Jceoftllgjtl4Z/XoJLZyf8UV2oN9s3ZgIKC3SPvJSXuqAjR0pKLnBmlEa7UgV+/pAqy+VOY2BiRDLRJQq2TN8lOpgyIeFcxy8Ym3nTP/3q218lj5pKyZ10iyrxoCSNnZB5FPFlFx0UoaEsW887qlnD6pFo97h+5SZcUuiOiXiSyPhMDN2E6Z3jSQrVfq0iL8WkHXyLLA1JVJg7aZ0r7jlRc9BRHrgpbcvy0NBmSKlj5idpRqoN+3LIwiQVPWr2yY1ikRB24d7RDdtD4ezfga2H/9p8FLn660Uv6h/zw53ighSiYa8+KSKr0ZZOtg8XsFj219YuMTc4aIX6DcGUiqWR1Vr4L2NKKumgjZmiE6ehb9fc/pdjl3AvToGlIaGotDvUUiPVVI6WxF1uUDhR6jI5oXu/WjdzC/cx2X8ixdMmb9EG0lHqMkUSNVeG11Jy0s9cLthV7ZSsxWsRD3xZ6kCCilSbuoB5778519Z2svvlGOlC7ix/SaRYEFx5eso/irOpbLX+yPI2oLT0MsLXiV3e8Xj7DL1VWaEOGrwe8cCXJej0rAa6d9zF8B4QrQjnnKy5YScmGV8SqXTPbgzdNs5nVG0Xo2yXI1NTSIn6+sLbfV3vhVZ+aRL9ZT7caigSkjeXXeLKXhG1c0MxecwXyfhSSGklCU8qSQEFU4Nquxhlfmz6cRy7xkWUmERxub8ec1/M5TSk/AbZ4F0WBy8ZJVNTy9iJHfGahPVhHckpqXgc3EqujJiR26ZOJ7FLHYSPiEcALvDdzca/Wx2lWdHjL0VSV3AVQd7FSgY/dbsm92XRJ+RilDZobY+IjuSXQkopn889PVqN5eynBYzKjYtAoL4loHTKsM4hkdTywtIUG62fs/O75aclfXDkRpN7vqc1Y3oO1i6pVwqTOoz6cXb0qNEuOPcsSJmferXM9Zw++mn83LTjLwPzbgQ7JiWLMUtQBVLTuut2rtlmo8k7ku2GzyLkOOXzzXcNpmp19tF14gqzpHB9Op3qtbUWrmVWes2/3+sZiMPkFm5pNjtnvMH52Mnkfu1WK6isWRjeU3pz6So0TnI/OuNzD42bZ6Iuwfn9eJGqf+Vp909iPEsonmTs2sMjkWLsxPXZ54KiIxmNbwgKoZc2+odj6B6RizSu1fn7GNv929v7zXPGzdyx5sZ1IFJxPT52smp1DOmxk2DDAiEZ/ZqxIMUzzl9V2zuxz5HPra2C94zYRfXd3LG78ObCMLmHRxeuEinvFgVjJ538O4VkGHEWaQzyjuKZ+SJhtA6KmWlwEJe0+0We8ufPCph/BcGta2VIiQuPCn1JpMKxk0Z0/kVHkrwpNd4V7/u7MxotmMoZvpNTV1cXn7v6Dp/7zuETWjnjrSt2jsLk53k+N5OMLioTIKKS5i+b2MmGlzS37edvXabLlBghtByU3++Fo9Vv0W9hZ49Nt67YmXs3bg4kF/9pKbM5W27vv6THTs5RyJK6/1HHzIaUanGsigTqbX9a/9OeAbf9UBFatB37Fdx8i/vB1Cu2yZbBlck3VKqRjIP/UmYra+GGw9Q2pFT27JDbhboW1y3zoJbJnM9MsP1Q9PPTeMa9/gqRCvVNxyTDNHKzco+S656VsRNlcSYrU1lRmSVOLu+kWww4elx7j6/jD9BbpZR8ux3VRovclJ2s+qwEeHTBCEI6gmS7Z4P/tjZ2ogxT+32nBcqQ3VNDSmk0n3bKr6FsQBS9mveEG5iPlACPLpDM9MlbfGbcfV/tHwpH3jLVkYIU600/MbOnRLTmkOiG2A2INNW8GX2+JUaF2hdEIiSjXFNT1D9r56+rYyfqMPUo4pT7558YYJRS0BPyNqGySum04S8qr+b9kFKhIrpAge4ucYc/mYgErI+dmJ9xig8PbXXY7y/v5MrGsA/PNJh/1cGjzNsEMZ6VZrMTfkti78YiJcOoqcSyyeG4ynreQmqY+vkxSok+RLLEF/PcDCs7Eq/mXZBUoUIy7Db2o1Is3ibKFNVKEqlh6udnjtf5Pnb+Zn664yhKBeNZ23e7Q65LwosWpvNQ7qTUX7s1RdQ9/yaFY99ph83P0psPp1kpKSppI+Vi5q5fzZQKnX8CC/mN0fC+jUB24pj5a8NyL8RbpoeMlHidNtKVXWfRVqN/t+aaJDz/PVj8t9/RsVZcd99huJ+HwgB9fDwcODjrKulKi5bKILkLrknCI3ygu6ZA96WPlluXILy4fTv8cz73IzA01YfiSdOrp+TsKF1rrSezu86ihTbTpU0dt6/8Ba5JwrNEaW6G111SudTVkfUFYrdT61orKulKi+ZtZjAYeB+xqmuS8BzKKnjtz1fwTiEVowSAW/fLTMFxrWut9GQU+6hBgSllMPD6+v8g1yThzYw1+yvyfffz1btb+kxzJJfliMPVt7WutaKSrgxMTYrByO5ly7U4Cc+Sii74QHfzzGt0X1zFZlgv4l3L8PjomzcUDGOcJnlI6cmooedp7MNDMoPkvvI0kpEQ5Sd4GVIOJqM0Zk9TU6aJj+afYPUPpWutDL+I5mCeUviUHUnS5mDgbUiZ4HsO0P4A46XpZm19xVBbbma+a68jiQ61uJwBrXStlYQCMg4iQ8EyBk+5+8DUqBxv70eT/gZiJHbbo+lJ6DQ1ZaSpt4PD//HjiubThl9y3UsagmJ3Hf2jn+DWlfhVLvZkjI9mzNBvD7U1pHM0NWX1B42Kit9V6VprCQVvkTRR2lRY4StTFm7DSQlXPjWmbev4MNfW20NtByuAippyYQC+aBuhaT7FX12S8HiGQsRdJ+E98xLd45hIiVSsWsl9nZSDOZNbNaaoKR8jpgAVC3lqXetErHNXR9uNhlybsgC+j6mxu+hledmM4ozpp+/jC4TDu9U3GbxYxmpqDgNQmGEJeWqaT4ix5UqLptlM8JO4qVseMa0rYdWEPdxyMFsvSbGaWmLEJFNLyFPRfH8f67w2ZQF8D6MUKAPb6yYRxBVtudVHNx7PQJ8iNcVuTwNY8z0Vzae4dddatBeL8fwmY9+Gh/z+Sfn76XTaW/PHvZpcbQ1hD7eG2opZbGI1xXxuo+zm8JSi+RSVtN0zsCg2E3wLysv6aeWp7t33wY52Lwknu0xLERNtqaSihGX37nOkpliY3C7a5mRK0XyaW6fYR427jnU+NPGr/2kFamKHrCGcZeqgtobIXlKH2hY6psQiNcXD5DzkqWg+TSVdadH0UMg0DtuXAmJo9TXeope1CaycRfS+EiN43B6qeRjyqb3/EqopcXsKT1mlpWg+IcYOxT5qSJu5TA1EZGGdZdPWQ8ISha8+Ra2Vbd2NTOW9/Zzop3N7mMrDYEXnZ3SB+MkweU8Kcjzrmk9x6660aGQz3cpNzl20PuP2pffJUH80P3j7yfzT7vKlaU7c0WWEr/5R01GGMvuY3MdEP13Ywzxb6aNP0gUqpNYLbj+rTU3zKW7dVs/AMWYJti+9J6bmo7Sz3ZufW+ahKQvbQKJpyHIp5ip49UknjNptWcpRop8uRmKZjx3TSTVnKjrvJRCHyb3R1TSf4tZt9Aw8kyJNNBo4bV56R7gFgvszKY3qh54yv7iiaVr7o/0Xlg5e/fKa9kj004U95D52RBWcLIRiiW5vipuUYkXzCTG2KPaRlpPTxgcdq6OBd4032Z/959oP/m8s77Jomt69h0OyuL/kiu5Splq1lrdlwoW3lMFTAjUVmR9T/iLpSl9OceuWlyTwlIJK7NzKLlujgfcMvT5z8vm/uYFdddz90c9ks5/Cf0fvOkR+knj1rzQaej9d2MM6buuF8M+nhWzr9O3dNqqK5hNi7Aob+QzXuFRelWdIZqvtX19ZddH/073SPg8zBaJp/A8bypQoVF6nPXdqsTG7Mgmv93Igpjwtasrcvpe3phfRlGvlrTS3LhQlz7D9hz0aJ/cmtu9Zfhj+8WZlqsnKpT1E0xjRoW5fECEQr75QWWkS/fSMXR362Byjwcp4/cN65fajl5MqOJ5tJ+Hd11yFb+X09t5dWXTsmvpCNyRL9OK9Zpgf0T+QNw3Jl3d0ea1YoXFFDjiJfjpXeAkXnih1LTL/OdrtBydT4WvExdhxcLd7iYVur6P3a7iaVhGLKHBKvVmNqO3dZ9E0VnRITwknjDs9/OI1ElatzK5LwsszAXnJBaur6tG5LusVSXj10yqlvyTIVErOSE6oqSbVNFa+nKPLLuDiMTs5G2hx7PPVSXi9N0i26z7O1fB/jn57G1m7IgkPCKajYhHKUSuqqymj9Xv3WTSNky/r6DbLBR179dd8ak7CqtXZVUl4pibHqOvO1JQWJj97mQoOni6e0nBFlV+WwZm8fdX2FxrnFhSdUlZXU+YG/qBoGi9fVqaWG3LxuNbwaXHs89VJeHoUlKmpxO2t1R6vqN+LMZlFZ3r93H/kZfDEkskt96KMzqlqauBCIZpmli879WTghTJW5qqR+FxtW6EVEy78OdmtZGoqUWIy0cn4sS9PR6ZMPTWQ9FSTPGr1fTSSoqspc/dq/sabZpEvqsESnmJOj9YlVzHXDGqF9v5LMmqakttm+XP025sKXlO552ZJLpmxkc5eKUwmSdn9tSPdNcQXKGrqJIyKaJpFvhohU7vs+t1uPLrtEiKVcOHTDhsLoeu3B+duVyiqf5el1FSRKWNwBjJV0YJLqpraCZMhmobJFyk+H/LkTk+ZdIAkLETPaLgUJXzsFSernv+c06Uz2F9RjZdDVf2TdbgVNUWBl0a9E5kqZUgvUlOTNConfkcuX+Tourpx8aiy6zIkWvWtOPDHaT72NJ7tmzNoN53y/O3QX/H0V2BU8yJU1W80y1FrEMrcT/XgyVqO0eFITfXyHjyMKeWrXISUS34yJh8wavUZpX1mjty8V+EBczKvgkd2OKrqN61M0cw+ONFmiXRKA8lbFR8P1VQtnRDhtgj5YlNPWi75eVJTmiDssgxZqcj/Sf69xtA2QRrubmOPHGAZMuX3PSfCK6YtSBmEaqoIjZiAB5cZoVYppfLosyAJj+XvF97OCsmvda+NOGVyC/BA9j4z6SQdspicFO5bewarkMLXIkdM9c/YdzRWU4Nu2jzUHWrj44GayqVeFFFuIV/nZbUdYYnoOXoi1ihEpgz+5ulPFqifUyRPb4fT5Q9N/5FgJkvIlBJe6a31idWU6C0pVLomlGpqCG9i6uU/h6MoPTXzEEh+nUXS7ijE9VYi/VoJU0NKTxju2ouSGcvDOO7XeLM/XRSNVMIrjTsUqSnRW1LoM71PfuJqqglVGQtjxrkBrZMCUYjCENrCuqFdc9kmxfHjg/abDyXq3L0fTkgu+UtK9zoOwfFTLCal0wiRmtqllIODgg9TfHzkauoQVkLcVYrOeZ56IiXfbsoV/ilWooSa9OORM6+7K8D3472G8OUWfSxL7v2ZUE0J66ORGqTgaqoI+wMirBhLLcUmdgepflrFjNsZ7EGHVO4M8MK7AvwARnR2ym8eDz0M85EwWBhapYgytqIEU1Pm40GcrLL1/FsSijyTfc3Wicj8x/R2u5s4xDG2eytP71W/WnnwRUh0nBXhx4M+1lk4O4XUGZsilRzHWNRUFxlaEcCvsihMMTkvSEp+50za7ljXdXXMV+3aeGG14uAvsGFykinhH4V9LOHsBGpqU6QOKZFa1FQVWTYRwG9C0TkvOwXv5dEoAJDl9WrtwPfiRIcPnFkiOeHOTiFkJPKdQ8pIXjyzmiqj0KoIY6oDRE6mws6kt2getgge+AV8mJysCPdrQzkZuT5oRUvuEq6SKNCrZ2Y1FWmbRBKewAUD4uPVu1dQ+2Zaqxn4AXIrOnbgrFmOh2LQCm9GqCnF0RGkgggGp6Z65RZ5piXhCaw3Pmo3Hvr+mZfgvmd8Bz/cpiJ0qU9CxBquNcIeYIixWqkcXqemGkWPidBDrkulue4Zp+I+NLPrHOR1h6pnJ9pUjNutaSHDSfGtxcmaaqHVrPNfUqGtGhlvd8cSJrcDZ6M7HvSxpixeOGlWU+Wq5aOYdr92NjcSuk/X7Iz820fCiE61fJyDgkEfq8tkNF2oqSZby377VF3rGSOcx0xJqRIB/GRo6ykZb12Bf4KHySk85fK6gz5WFWqJP+z8SlqJc9LadAUm222LdZAI4DeHUz2s/iFPwLKo1HjrqvwLA7doNHBmPe2gj1W6ntUktiBs3dlGuvaC47qSmjNJpvB4n93xhk7fypyMPNPfukr/ggyTG8lx+kb0scgDZzvIO+YLd8K153xy0VOxairuEk4vEANogzWBPe2tK/ZPCA3BlrIQfaxe+bP5n04uuCZTJFEbaxWQmqr+7a94UOLRo4wWlepvXbF/QobJl7xu0ceqg7/aLIB0zILYVJwdOpHWSyWEz6WKy92Gf/07HpIq+E2fI+9vlwnX2GbR/qdNdHLLKfnEWZlTboVu17M7T590r+TcmdfAep8XqqaPTlJf+elWugu75z7kKfrwZOTCF0jEpqyLfhEqN7tp7Gym0ssmTE58MU/PsZOF1OHwhycaoWutauF9eONK7aMrg6kvPtnkcnGx9F6qH6v4ncNtGkNmkOrD4Y9OnL9pM/LMcd8Na3TZqIMfJPS4LnLY/1Ct759GF6ls2Xzk/KzzlxXda2WKyUtiOITUVMMOjPPS6Ib8NQRqNHG6MTpsOyze+xzHoa9dIhcvbH7B6bdq+ltounfu27rvqT/cyF4wEtM3h/3b29ul99JrVzwhZOHiOAnFkEd5zKWcMpnaTF98RLRUpDmve6SvIsIuyhlZq3+2fnfPjv1SDN2m9aTGl/Xbn3M4XFNBkzNgPX2L3S1Pnb29Vz9Zuftnch5SdCJTVbvtxMwDos85HK6mIrnuW0tfDk/5d1+BHccty/JYdWOijB9YiM4nbJr9ZXv3TYRqngZd99q87po+F5rQPTNTNI5rrNUyO5BjXCnjdx/DE2XCphk3Ys6CTRuAR0aEyRe6WZ1fvII8lej7VEz+Q5fpKEvc2Hn9eRZnDyRtWs3U1FoS9eOS0r1zXuf0iBsIfpmLUhITclSUYIFRUna3ouBEneq6kABW9rNMBHHHhrb56z/jLkjq3kfeQPDr8F6KdblNTMmM405mcOVkrWAeZoX1JB6amlrr1MydQXqS+0iDgc7cjt/zR92I/il175eJJuSM8vxo16EKMw0b6zEpaqrLUsswDszymceGazgqVvSxGC+v4+nWlfgl+kvTVfqp7Qk545H01CgOlla5KWpKs2ns9o39uNMtbHvNX3O/TLeuwO+x0sG6ZkKOHama+KHcqfhYTTGbpj3rY/kosGlT41V/DvhVLk7uFB1MjgOsrYrNIAGogxvaPkysphTr6WiWaswJC0+8Qehz0Idtb1kxRkKBpXrBNKrARzWb2UjFamqnWc/5WcVyg/1T5HI+HabnPS1fyUQpcwuzLDXyL3op6V5wIKqHWWxiNZUedOgXm2iedFALgdsS5lOUma6m0iP/QoGle8Hmxmw0uFi+RWqqSlhPIVIrphjclDDry7m6U1hup/vd/hL/OW0gSRp6Xm7vPkdqKpG4eBYi9ZxJeA/ENHaTeiLwp02b5ZqaWhn5Fwos3VvL+ZNa/iVUU2mb1jM5Spti8POQc1yrpwJXmAKQuaKmquQdNlbFFnc4+C8nfk2optI2jfX4njMJ734JJxyzkYygYHDCeDyTNsi2EZhq/Zddlopgs96aLSarx9RU2qadmFiWaVMMvhszpVA2f2o7mmgKT260wKSoqdDnYggFljaQA7NUk3xsqKaSNq1g9vI5k/DulFPc/HXCba6lKzVYx1hRUyuBqTnzwpA2kBQUH+3nLnDAAzWVsmnCxU8mLIBvx7R+2Pxru2b1y1c3lquoqdBCMoQCE/IlYfJQBUYrUFMpm3bKgqn/z5eEdzvG6mOn5bUZykxp/oSaymUH7eDUg6IB8qQ3LEJbKwaSiVQZ3IwGlhc1lbBp9K7Mx9MJC+BqaDml0X7MstVwYOSL6GpqCJqlcMKhqCk1x8DemktwGDplLCI1uULLUmMZN2kpm2bKLbl8kSn2S3jpTweMUfzwHR0jx0Rf7MyVG4LDjdbWQVBxnFVM3KjpUZJrVsU2LFJD4aUwRZ2pKd2m/ZGvEf0EVOuhbT7YIgqj/nggkxUXGnv2jazbEF/WZlz0GIUiEwfhwrAAJEnGxIsGMVGOUGBcvgSsx1dnOr4qqk0jieLhKvOko7JwWR9eCSxV4mev7OkdfVFSuv1P3IQnRFyIFZ6WrywAeQoVRXqUJE7Ci2vlnu/0Vyn/JNpi1DzQqymleznsor93p/9Ab90ZTKOS7RO9yTIv6JTpMkVK6kNtfiM/rTgyBu+9aSR2SojGRqyz8V+EfIWl9vajrbtPUbfHeKdvtmme/qT8tQfx89hFFF4r7V9nasqcfpFjkJDoDVhijTevxJYp3RYjNx9688dqKggPiQBkqKbSoyRXroqdZ3yh+F30FvHYVL7I86VPUhXubx3FBdWs4pruJeYiXYXdw9wjtpYyzV2kkxWb+SJxmARx7PXmL7LA0QjCQ0LCQjW1EusUEizkK6rZXPe4CFdTRl1GcxWqSV7QQSnFhFsF82W5VprQYFrocDQX8fAUTfKuUte2WZCYVEqpkRIWqqnQGC0ICU4YSBq5dscTtrFaqidtGvGqiwJ+DTvXPd9XdV3t7Q+3yEfkTwTXGqlh6xhbPjPrcCSuDdVUoMyMhE3iCVzgkn73VUl4pI4H+znPkruAu+qFfZN9rZQHEaRScv9juVXLFvlINyEVN9eG22zR1zp9baCmeqlQJkXC2OldluyfcwnWNaSRdX+zpFe2dPpms06dwVdZcOvfOWWyDzPuMt5qu2x1jQ77qst10+cxsFTzSzVlGq5dTgYSZsPwS/2SfreUYFW7kkT5vzXZd1zUVPc0607/KqRnRn6E7Nj8hq80ocE1I5kndxtqknbtWqmmDlKX1eFFUk1V2WoS3hBUjDGWGRf8dBz+9LY/dfojwBXU8ctqfNj95L6YJmzSl3sft10UwKyk0s0v1FQez2QY3Gca5NgJNdWklIuShDewk71dxX2J9Bfr6hf8NaVinDq28OtKuNowNyPFRE14alFS6ebvmZoyCu7AzpG668LdWebbdNlqEl4TVcwMKTU+plQM/rz1AsEPsIsMhKRNN6GhnhVR5Vp+UVIrzc8EuY1dKQ1fxyFLRjWEBJvqfISL4R+nuXCX5e91+u8Cf896j25zohpzco+m0f4wJbXS/ExNnbJoJkNAnjNZmdLaRUi/ch+x6PY0pf8o8E+kvVTLhoEwimhvP9rwVMFEcKX5FzW1k2VYeHEe5BAhdCNfk3pPIcFtKE/1qF4Evh0WLNbJZBMaj9n4OYP7yppx3jKk94XTzT+rqSmTxtFcEo28lkxNvUmtRsk39VwXkYRHKo7GcTH49ov0QgYUrGX0uYqzZ9LZsyL+Y7fZYh550Pwcr6bM85vlsG5neWzK9TFtxpurjxMkLsGjUXGIKd0Eo1qCdbwEpu2jzMdFDHJmk5xqWG6WGEYzeDVVZ1H6ndJJLDPhexVFUJuJTr2t/yXglyANkKcmJSR2xszeWnd6JxRRIBGnLB3UcmqqjF2pLlHJnj7WWnVGOjXAvt0HdnA0/0gMYokmjNOmAve+jiLhVeKxTk3l0UwGtQO6qCnhdyPj7T5ZBtx3x7obgrMttVxyjbcwul5xs5UcRzOQmjKCVS/H9NHeM1dT9AkZb3dOK1yTXO6NycIEGlF0fWKfTfMng1qkpppMuFLrwVHbRYRSegTG9l24Jl9Nwkved/VaIyVGmKflUNr5GloopQdj6psDk6tlb0w1TWRhPbq+eq0be9mzQ7sMs5WejKGr97l1q+ZjecJjtqxH19eHe0p6UrUcWAm3g0fGula1/2o0x5AunWUry8Ctax2rprrlwGC6k1fXEzwOlNg5z/LdGAVcVUQbCXzlqjyCJ0LsULuRhFdmK8vAreRgGgYMmbwMNevHXZuEp7GSgwleC54ncnUSnsJKDiZ4MVjv//okvJjhhbbhAjPjqY4Pst68HiaYtw1aj66P/1o78HBMJy0jRGgm3i2b2EyDgY5sRNfB61Fqdu3Erdkbje+yjDdHR2c3ouvg9aB4Y+AMUSrd6L+VmU5jTyO5BARQQlQ5siN9LqRMScKj5JLht2sKHgUSmaIZ3deetBJbJmFJwkPGG7gOl4NXmuWAjtZd4gtvtC+S8TZe/MVb1+FpcBveL4iVuaYb1eqXoRmE/a1r8TSMwl/iGXivA71Wq1MawZcY2wOZvPy96m9dl5/GRNbG8OBoX6f+96vz1GjLVD8h6ozVzjmUN6gPeHjUDDCacgo1BVb5LAttMxJ90sTuYvR7qCmwyimIhni0DDC73EcJNQUsdv2WcL50HUbYHFo+TkeaC2rq5aGlifhKd2XLztq57uFmJHoGWJX5JRqgpl6Ryf6nrrjBtJLrxEUJglo+jpGl8xlq6tXwi0q5jMBGEym2aLALNWV/wvuYg1N0aG/+h5p6CYKdYmd56LwQ2dHsvj1RkTmjcPLFw6WO4olivffYW6ip50bbsDSb5cH4RLkczSZbOPtJ5kq6upG33UWqyFzX0acCaur5sEppNB/fVMv2dhhswSzOim+5BBnR6Uhz9aJQPFGsnFUf1NQTQVu7z0qpN4d2XJTiFJs89omo6+bVFIXJaScvGfKMZ6zmy0VQUw9P7CkRrTl3ylbz/rTBOpop7Q7aidLkconwVBSY6tkBqKmHZTJKya9CHFObMhsT4NWVPcvF8rkwOfUMi2kpEs1YbbglhJp6VOwsnCkUJbF99cYEeHWwjg23+InS1mmf5iJRYOrA1V0DNfWY0ML7o/WHyFPaG8cp2JdzYwJ8nSnLNTCrNofJKcNwkc3Iry/4d769Mbg/povwGE+pCU98ukY+zGsUK6O5Q6hOJOrkeXZwmShtrCELTwV+vXnMfvlarz8V3AS/mwPZJdIRvSzglRRDWc9jY1m8PlOmtXLJzLzo0D7Zi0wFfn0rXTZSU236seA3icZxjb6w+5COomCbRUspaKO5gToJn6apkwNzsJYwudx/OfDrT4HIQ03dA6NVShEHOllkYUaA0q3S1vNQc3oXzBPCimRM/ZWL6NiupXtk4NcXgeBCTd0DbSxNRkLeT3R2kO6xqqTU0Vw1TLAQD9bRtoCzruNhcpqp78b/pF8/Lpc4g51DTd2eQUgSRSf5bg6NdI/12I8iIGqYYGEX3eZPxoWw5k4SSb21v9KvN/3KYxtuMQo1dWPI3ryldyyrRFOrSkpb9lMNEyyEg3W9kTF2gRQdm+U5nUO/vlI1LNTUrVGslqDMWNpJoSqBeDRXDxOMfec+zdF1a7CskmFOWxDXItkxoiT9+l0kTW/vOdTUzVGsloC68W5UpNV1gDBTFq5O2GCgv9jY011gsE7TcnnYJZxDnub/uWbzpcxgo9N3exSrJaEulx3o0JWUppJIJvo4bWqyp7ssJBf3DeNadv/lT/kCGLEtQoONTt/tUaxWALW/SdpNKCl12c9IZiyjPTtEJ4Kk4DzQnTY89Sn8epuvEAI1dXMUq6UVMY2XUFJq5DJOwjN9gHa0ZydhsIyiDDqAUVzLhTz5C1BGV9GtoaZujepIB5ArM6SUlLrs5262aDxDYca0+5xKxd01xyGSC8rIy0r2AihPNUBN3RrNaoXYkZld8vUPzdTZSuFR37DUILUQRTNFXooS15qDsh/LRVrFoaZujTreFhUqbGsmCu5CM/XVJLwqC0RIyW6Y52od0kUIqKkbo1mtGGt2Ui9/bKa+moQXulOqOa6FXJdZoqtKako9A34HxWopkIpI5asofa8gWBkSRtcpUsHcKS27wa+RnC/1nqIihh4L3d4WxWqZoPYYHCI19d9Z5RuS8ChScZy/Jsyxdfon/4CVLXLADeFWi6VNNbJUbxXEoN7iO5LwAncqU3WQzcijSmxYVnBDyJHuorSpSpYqnR8zarf4jiQ8GyAf/NfEOBH1EzrzqXv+1bcfliZTOYhCNPhRpGzNtyThSXdql3Cxh2g1KnB3xEl4FNTuRCGjpFoyftFyKgbFTH09CY9k29uy7XEicLcs423pzRycs91If2fhO5LwXIfOXbMR1wL3DFmtjR1mTq6ByYfu4/NlrJK+mIRnIOfb5WaNycA7uH/0zhVnnB3zMsuUnSWvS8Kz3Ul3TNVCg0lVWa8KeAS2kvAWJeV6XHKE17CWhDdPDXR9RnsaMYBnJtW5mlmUlBuZOYYlEkl4eTjTYFGIXZa/199QeXCPbHauTlxgqIMYrnj4hSQ8rxCnf602uF+2OlcjE4SzG7z9Ly6ykYT39n5IzcIBz8ZWEt4pOH/MopEZbfhlR5IUTw0Ez89G0kCgpHwS5igK5bGL30IpvSwbSXihknJDJ3Jkxqik4QfqBh6S9aSBSEmdXVqCGJk5vZ+q4QfqBh4TxWotxErqvMyZAUAlThqw6053Z3WJMkNlRgN/oWrgMZmT8IJ1p5vzso4iAF+AJkgpO3RUSSUFwCqJJDwTWRia9RQFADTCJDyaao7oJPh7XBJejiET8E2MGDIBAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAruL/MJrnpgplbmRzdHJlYW0KZW5kb2JqCjE5IDAgb2JqCjw8Ci9UeXBlIC9YT2JqZWN0Ci9TdWJ0eXBlIC9Gb3JtCi9CQm94IFsgMTAuMSAtMC4wNjEgNTg1LjI1IDgxMy44NCBdCi9SZXNvdXJjZXMgMjAgMCBSCi9Hcm91cCA8PAovUyAvVHJhbnNwYXJlbmN5Ci9DUyAvRGV2aWNlUkdCCi9LIHRydWUKPj4KL0ZpbHRlciAvRmxhdGVEZWNvZGUKL0xlbmd0aCA0Nwo+PgpzdHJlYW0KeJwrVDA1N9UzVDAAQgtDYz0LUwVDAxBfz8DYUiE5l0vfM9dEwSVfIZALAL0CCOQKZW5kc3RyZWFtCmVuZG9iagoyMCAwIG9iago8PAovRm9udCAyMSAwIFIKL1hPYmplY3QgPDwKL0ltNCAxNyAwIFIKL1RyNSAxOSAwIFIKPj4KL0V4dEdTdGF0ZSA8PAovRUdTNiA2IDAgUgo+PgovUHJvY1NldCBbIC9QREYgL1RleHQgL0ltYWdlQyAvSW1hZ2VJIC9JbWFnZUIgXQo+PgplbmRvYmoKMjEgMCBvYmoKPDwKPj4KZW5kb2JqCnhyZWYKMCAyMgowMDAwMDAwMDAwIDY1NTM1IGYgCjAwMDAwMDAwMTUgMDAwMDAgbiAKMDAwMDAwMDA3NCAwMDAwMCBuIAowMDAwMDAwMTE0IDAwMDAwIG4gCjAwMDAwMDAxNjMgMDAwMDAgbiAKMDAwMDAwMDU4NSAwMDAwMCBuIAowMDAwMDI2MjkzIDAwMDAwIG4gCjAwMDAwMjYzMzAgMDAwMDAgbiAKMDAwMDAyNjQ4MCAwMDAwMCBuIAowMDAwMDI3MDM2IDAwMDAwIG4gCjAwMDAwMjc2MjUgMDAwMDAgbiAKMDAwMDAyNzg2NiAwMDAwMCBuIAowMDAwMDMyNDgyIDAwMDAwIG4gCjAwMDAwMzI2MzAgMDAwMDAgbiAKMDAwMDAzMzE1OCAwMDAwMCBuIAowMDAwMDMzNzEwIDAwMDAwIG4gCjAwMDAwMzM5NDUgMDAwMDAgbiAKMDAwMDAzODEyOSAwMDAwMCBuIAowMDAwMDM5NzkzIDAwMDAwIG4gCjAwMDAwNTkyNTcgMDAwMDAgbiAKMDAwMDA1OTUxMyAwMDAwMCBuIAowMDAwMDU5NjY0IDAwMDAwIG4gCnRyYWlsZXIKPDwKL1NpemUgMjIKL1Jvb3QgMyAwIFIKL0luZm8gMiAwIFIKPj4Kc3RhcnR4cmVmCjU5Njg2CiUlRU9GCg==",
    "source_account": {
        "account_branch": "0001",
        "account_digit": "2",
        "account_number": "77979",
        "financial_institution_compe_number": 329,
        "financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
        "owner_document_number": "03782617037",
        "owner_document_number_formatted": "037.826.170-37",
        "owner_name": "Beatriz Couto de Carvalho"
    },
    "source_subtype": "bank_slip_covenant_payment",
    "source_subtype_translation_ptbr": "Pagamento de boleto de convênio",
    "transacted_at": "2024-06-20 19:58:21",
    "transacted_at_br": "2024-06-20 16:58:21",
    "transacted_at_br_formatted": "20/06/2024, 16:58:21",
    "transacted_at_formatted": "20/06/2024, 19:58:21",
    "transaction_amount": 138.97,
    "transaction_amount_formatted": "R$ 138,97",
    "transaction_key": "89820026-bb3e-44fc-8130-ceaa300e1d8a"
}
```

**Response Body: Comprovantes TED**

```json
{
    "origin_key": "6dcb9a84-f545-42ec-a5d0-7312436b4318",
    "pdf_encoded_string": "JVBERi0xLjcKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvUGFnZXMKL0NvdW50IDEKL0tpZHMgWyA0IDAgUiBdCj4+CmVuZG9iagoyIDAgb2JqCjw8Ci9Qcm9kdWNlciAoUHlQREYyKQo+PgplbmRvYmoKMyAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMSAwIFIKPj4KZW5kb2JqCjQgMCBvYmoKPDwKL1R5cGUgL1BhZ2UKL01lZGlhQm94IFsgMCAwIDU5NS4yNzU1OTEgODQxLjg4OTc2NCBdCi9Db250ZW50cyA1IDAgUgovUmVzb3VyY2VzIDw8Ci9FeHRHU3RhdGUgPDwKL2ExLjAgPDwKL2NhIDEKPj4KL2ExIDw8Ci9jYSAxCj4+Ci9hMC43IDw8Ci9jYSAwLjcKPj4KL0VHUzYgNiAwIFIKPj4KL0ZvbnQgPDwKL1ZDQVRXUyA3IDAgUgovT0NITlVQIDEyIDAgUgo+PgovWE9iamVjdCA8PAovSW00IDE3IDAgUgovVHI1IDE5IDAgUgo+PgovUHJvY1NldCBbIC9JbWFnZUIgL1BERiAvSW1hZ2VJIC9UZXh0IC9JbWFnZUMgXQo+PgovVHJpbUJveCBbIDAgMCA1OTUuMjc1NTkxIDg0MS44ODk3NjQgXQovQmxlZWRCb3ggWyAwIDAgNTk1LjI3NTU5MSA4NDEuODg5NzY0IF0KL0Fubm90cyBbIF0KL1BhcmVudCAxIDAgUgo+PgplbmRvYmoKNSAwIG9iago8PAovTGVuZ3RoIDIxNTAxCj4+CnN0cmVhbQpxCjEgMCAwIC0xIDAgODQxLjg4OTc2NCBjbQpxCjAuNzUgMCAwIDAuNzUgMCAwIGNtCnEKcQpxCnEKcQpxCjAgMCBtCjc5My43MDA3ODcgMCBsCjc5My43MDA3ODcgMCA3OTMuNzAwNzg3IDAgNzkzLjcwMDc4NyAwIGMKNzkzLjcwMDc4NyAxNDYuNDY4NzUgbAo3OTMuNzAwNzg3IDE1MS45Njg3NSA3ODkuMjAwNzg3IDE1Ni40Njg3NSA3ODMuNzAwNzg3IDE1Ni40Njg3NSBjCjEwIDE1Ni40Njg3NSBsCjQuNSAxNTYuNDY4NzUgMCAxNTEuOTY4NzUgMCAxNDYuNDY4NzUgYwowIDAgbAowIDAgMCAwIDAgMCBjClcKbgpxCjAuMDk4MDM5IDAuMTQxMTc2IDAuNDk0MTE4IHJnCi9hMS4wIGdzCjAgMCA3OTMuNzAwNzg3IDE1Ni40Njg3NSByZQpXCm4KMCAwIDc5My43MDA3ODcgMTU2LjQ2ODc1IHJlCmYKUQpRCnEKNzkzLjcwMDc4NyAwIG0KMCAwIGwKMCA1IGwKNzkzLjcwMDc4NyA1IGwKVyoKbgoxIDAuMjUwOTggMC41MDE5NjEgcmcKL2ExLjAgZ3MKMCA1IG0KNzkzLjcwMDc4NyA1IGwKNzkzLjcwMDc4NyA1IDc5My43MDA3ODcgNSA3OTMuNzAwNzg3IDUgYwo3OTMuNzAwNzg3IDE0Ni40Njg3NSBsCjc5My43MDA3ODcgMTUxLjk2ODc1IDc4OS4yMDA3ODcgMTU2LjQ2ODc1IDc4My43MDA3ODcgMTU2LjQ2ODc1IGMKMTAgMTU2LjQ2ODc1IGwKNC41IDE1Ni40Njg3NSAwIDE1MS45Njg3NSAwIDE0Ni40Njg3NSBjCjAgNSBsCjAgNSAwIDUgMCA1IGMKMCAwIG0KNzkzLjcwMDc4NyAwIGwKNzkzLjcwMDc4NyAwIDc5My43MDA3ODcgMCA3OTMuNzAwNzg3IDAgYwo3OTMuNzAwNzg3IDE0Ni40Njg3NSBsCjc5My43MDA3ODcgMTUxLjk2ODc1IDc4OS4yMDA3ODcgMTU2LjQ2ODc1IDc4My43MDA3ODcgMTU2LjQ2ODc1IGMKMTAgMTU2LjQ2ODc1IGwKNC41IDE1Ni40Njg3NSAwIDE1MS45Njg3NSAwIDE0Ni40Njg3NSBjCjAgMCBsCjAgMCAwIDAgMCAwIGMKZioKUQpRCnEKcQowIDAgMCByZwovYTEuMCBncwpCVApFVAoxIDEgMSByZwpCVAoxIDAgMCAtMSAyNTguOTYzMTg3IDgxLjQ4MTQ0NSBUbQovVkNBVFdTIDE4IFRmClsgPDAwMjYwMDUyMDA1MDAwNTMwMDU1MDA1MjAwNTkwMDQ0MDA1MTAwNTcwMDQ4MDAwMzAwNDcwMDQ4MDAwMzAwMzc+IDEwOSA8MDA1NTAwNDQwMDUxMDA1NjAwNDQwMGE5MDBhNTAwNTI+IF0gVEoKMSAwIDAgLTEgMzMxLjUwNjY0NCAxMDUuODY1MjM0IFRtCi9PQ0hOVVAgMTIgVGYKWyA8MDAxMzAwMWIwMDEyMDAxMzAwMWIwMDEyMDAxNTAwMTMwMDE1MDAxNzAwMGYwMDAzMDAxNDAwMTgwMDFkMDAxODAwMTgwMDFkMDAxNDAwMTk+IF0gVEoKRVQKUQpRCnEKcQozNTguMzUwMzk0IDI1IDc3IDIyIHJlClcKbgpxCi9hMSBncwoxIDAgMCAxIDM1OC4zNTAzOTQgMjUgY20KcQpxCjEgMCAwIDEgMCAwIGNtCjEgMCAwIDEgMCAwIGNtCnEKMCAwIG0KMy41NjM3MiA2LjI1MDAxIG0KMy44ODI4NyA2LjI1MDg5IDQuMTk0NjEgNi4zNTI0MyA0LjQ1OTU1IDYuNTQxODIgYwo0LjcyNDQ5IDYuNzMxMiA0LjkzMDc0IDYuOTk5OTIgNS4wNTIyMyA3LjMxNDAxIGMKNS4xNzM3MyA3LjYyODExIDUuMjA1MDIgNy45NzM0OSA1LjE0MjE1IDguMzA2NTEgYwo1LjA3OTI4IDguNjM5NTMgNC45MjUwNyA4Ljk0NTIzIDQuNjk5MDEgOS4xODUwMSBjCjQuNDcyOTYgOS40MjQ3OCA0LjE4NTE5IDkuNTg3ODUgMy44NzIwOCA5LjY1MzYxIGMKMy41NTg5NyA5LjcxOTM4IDMuMjM0NTggOS42ODQ4OSAyLjkzOTg4IDkuNTU0NDkgYwoyLjY0NTE5IDkuNDI0MSAyLjM5MzQyIDkuMjAzNjYgMi4yMTY0IDguOTIxMDMgYwoyLjAzOTM3IDguNjM4NCAxLjk0NTA0IDguMzA2MjYgMS45NDUzMSA3Ljk2NjU5IGMKMS45NDUzMSA3Ljc0MDY2IDEuOTg3MjEgNy41MTY5NiAyLjA2ODYxIDcuMzA4MzEgYwoyLjE1MDAxIDcuMDk5NjYgMi4yNjkzMSA2LjkxMDE2IDIuNDE5NjcgNi43NTA2OSBjCjIuNTcwMDMgNi41OTEyMSAyLjc0ODQ4IDYuNDY0ODkgMi45NDQ4IDYuMzc4OTcgYwozLjE0MTEzIDYuMjkzMDYgMy4zNTE0NSA2LjI0OTIzIDMuNTYzNzIgNi4yNTAwMSBjCmgKMTYuOSAxNC45MzExIG0KMTQuOTkzNiAxMy4yMjQ5IDEzLjE3MzQgMTAuNjA3OSAxMS41NzQ0IDEyLjQyOTYgYwoxMC4zNjkzIDEzLjgwNCAxMS42MDM3IDE0Ljg1NzEgMTIuMjQxIDE1LjUwNzMgYwoxMy45MDEyIDE3LjIzNzIgMTYuMDc2MiAxOS41Njg0IDE3Ljg2MDIgMjEuMTQ1OCBjCjE4LjQ1NTggMjEuNjcxNiAxOC43NzAzIDIxLjgwNjMgMTkuMjA1OSAyMS45MSBjCjIwLjUyMzcgMjIuMjE5NiAyMS4yNjY4IDIxLjAyMTQgMjEuMDE0OSAxOS44MzY1IGMKMjAuNzc4NCAxOC43MDM1IDE5LjU4NzIgMTcuNTgwOCAxOS4zMzM5IDE3LjQ0MTYgYwoyMC4yNTc5IDE2LjA3NSAyMC44NTE5IDE0LjQ4NzYgMjEuMDYzNiAxMi44MTkxIGMKMjEuMzYzOCAxMC42MDc1IDIxLjAwNDEgOC4zNTE0IDIwLjAzNTMgNi4zNjg5OSBjCjE4LjY0MzcgMy41NTQ5MiAxNi4xMzg4IDEuNzUyNDQgMTQuMjE5OCAxLjEzNzc5IGMKMTMuMTgxNyAwLjgwNDU0NiAxMi4yMjQzIDAuOTIzMDMzIDExLjc1MTIgMS4yODU5IGMKMTEuMTg0OCAxLjcxMzkzIDEwLjg5OTUgMi43MzI5MiAxMS4zNjU3IDMuNTU3ODkgYwoxMS40NDU5IDMuNzA1MTkgMTEuNTUzNCAzLjgzMzYzIDExLjY4MTYgMy45MzU0NiBjCjExLjgwOTggNC4wMzcyOSAxMS45NTYxIDQuMTEwMzggMTIuMTExNiA0LjE1MDMyIGMKMTIuNzgyMyA0LjMyMDY1IDE0LjA5MTggNC42ODIwMyAxNS4yMTQ4IDUuNjMxNDEgYwoxNi40NTU4IDYuNjQ3MTIgMTcuMzI0MSA4LjA5MjYgMTcuNjY5NiA5LjcxNzcyIGMKMTguMDU1IDExLjQ2MzkgMTcuNzI4IDEzLjYxNDUgMTYuOTAxNCAxNC45MzExIGMKMi4zMzMxNyAxMS44MzA4IG0KMS4zODk2OCAxMi4yNDk5IDEuMjQ0OTYgMTMuMTQ0NSAxLjQzNjk5IDE0LjA4MiBjCjEuNzQ1OTIgMTUuNTkxMiAyLjk1MjQzIDE3LjY5MjkgMy44ODIgMTguNjkxMSBjCjUuMjczNTggMjAuMTcyMiA2Ljk0MzQ4IDIxLjI3ODYgOC45MDcgMjEuNzIxNCBjCjEwLjUxMTUgMjIuMDgyOCAxMi4yNzA1IDIyLjA5MTcgMTMuMjMwNiAyMS43NTI2IGMKMTQuNjIyMiAyMS4yNjA4IDE0Ljg2MDIgMTguNDY5IDEyLjU1NDMgMTguNDI5IGMKMTIuMTgyOCAxOC40MjkgMTEuNzY2NyAxOC40NTU3IDExLjMyNTYgMTguNDc0OSBjCjEwLjQzMzYgMTguNTEwNiA5LjU0Mzg2IDE4LjM1NzYgOC43MDc4MyAxOC4wMjQ4IGMKNy44NzE3OSAxNy42OTIgNy4xMDYwOSAxNy4xODYxIDYuNDU1MDMgMTYuNTM2MiBjCjUuOTE0IDE2LjAxNCA1LjQ3MTA1IDE1LjM4NzMgNS4xNDk3MyAxNC42ODkzIGMKNC45NDYyMSAxNC4yNDk0IDQuNzY1NSAxMy43OTggNC42MDg0MSAxMy4zMzcgYwo0LjUyNjMgMTMuMDczNCA0LjUzODgzIDEyLjgxODYgNC4zODAxOSAxMi41NDAyIGMKNC4xNzI0MyAxMi4xODQgMy44NTMwMiAxMS45MTc0IDMuNDc4NDMgMTEuNzg3NSBjCjMuMTAzODQgMTEuNjU3NyAyLjY5ODE4IDExLjY3MyAyLjMzMzE3IDExLjgzMDggYwpoCjAuMzA5ODA0IDAuOCAwLjkyOTQxMiByZwovYTEuMCBncwoxIHcKMCBKCjAgago0IE0KZioKUQpxCjAgMCBtCjguOTg0NzMgNy4wMzcxMSBtCjkuNDgyNjggNy4wMzY4MiA5Ljk2OTUyIDcuMTkzNzEgMTAuMzgzNyA3LjQ4NzkzIGMKMTAuNzk3OCA3Ljc4MjE2IDExLjEyMDcgOC4yMDA1IDExLjMxMTUgOC42OTAwNSBjCjExLjUwMjIgOS4xNzk2IDExLjU1MjMgOS43MTgzNiAxMS40NTUzIDEwLjIzODIgYwoxMS4zNTgzIDEwLjc1OCAxMS4xMTg3IDExLjIzNTYgMTAuNzY2NyAxMS42MTA0IGMKMTAuNDE0NyAxMS45ODUzIDkuOTY2MTEgMTIuMjQwNiA5LjQ3Nzc1IDEyLjM0NDEgYwo4Ljk4OTM5IDEyLjQ0NzYgOC40ODMxNiAxMi4zOTQ2IDguMDIzMDkgMTIuMTkxOSBjCjcuNTYzMDEgMTEuOTg5MSA3LjE2OTc3IDExLjY0NTcgNi44OTMxIDExLjIwNTEgYwo2LjYxNjQzIDEwLjc2NDQgNi40Njg3NSAxMC4yNDY0IDYuNDY4NzUgOS43MTYzOSBjCjYuNDY4NzUgOS4wMDYwNiA2LjczMzc4IDguMzI0OCA3LjIwNTU4IDcuODIyMzggYwo3LjY3NzM4IDcuMzE5OTYgOC4zMTczMiA3LjAzNzUgOC45ODQ3MyA3LjAzNzExIGMKaAo2LjUxMDk2IDAgbQo2Ljg5OTAzIDAgNy4yNzgzOSAwLjEyMjQ3OSA3LjYwMTA2IDAuMzUxOTQ4IGMKNy45MjM3MyAwLjU4MTQxNiA4LjE3NTIyIDAuOTA3NTY4IDguMzIzNzMgMS4yODkxNiBjCjguNDcyMjQgMS42NzA3NSA4LjUxMTA5IDIuMDkwNjUgOC40MzUzOSAyLjQ5NTc0IGMKOC4zNTk2OCAyLjkwMDg0IDguMTcyOCAzLjI3Mjk1IDcuODk4MzkgMy41NjUgYwo3LjYyMzk4IDMuODU3MDYgNy4yNzQzNyA0LjA1NTk2IDYuODkzNzUgNC4xMzY1NCBjCjYuNTEzMTMgNC4yMTcxMSA2LjExODYyIDQuMTc1NzYgNS43NjAwOCA0LjAxNzcgYwo1LjQwMTU1IDMuODU5NjQgNS4wOTUxMSAzLjU5MTk3IDQuODc5NTEgMy4yNDg1NCBjCjQuNjYzOTEgMi45MDUxMiA0LjU0ODgzIDIuNTAxMzYgNC41NDg4MyAyLjA4ODMzIGMKNC41NDg4MyAxLjUzNDQ3IDQuNzU1NTUgMS4wMDMzIDUuMTIzNTIgMC42MTE2NTcgYwo1LjQ5MTQ5IDAuMjIwMDE5IDUuOTkwNTcgMCA2LjUxMDk2IDAgYwpoCjEuMjI1OTggMi4zMzg5IG0KMS40NzA1MiAyLjMzNzE0IDEuNzEwMDQgMi40MTI3MyAxLjkxNDE1IDIuNTU2MDcgYwoyLjExODI2IDIuNjk5NDIgMi4yNzc3NiAyLjkwNDA2IDIuMzcyNDMgMy4xNDQwMyBjCjIuNDY3MDkgMy4zODQwMSAyLjQ5MjY1IDMuNjQ4NTEgMi40NDU4NiAzLjkwMzk3IGMKMi4zOTkwNiA0LjE1OTQzIDIuMjgyMDMgNC4zOTQzNCAyLjEwOTYgNC41Nzg5IGMKMS45MzcxOCA0Ljc2MzQ2IDEuNzE3MTMgNC44ODkzNSAxLjQ3NzM3IDQuOTQwNiBjCjEuMjM3NjIgNC45OTE4NCAwLjk4ODk2NSA0Ljk2NjE0IDAuNzYyOTU3IDQuODY2NzQgYwowLjUzNjk1IDQuNzY3MzUgMC4zNDM3NzUgNC41OTg3NSAwLjIwNzkzOSA0LjM4MjMyIGMKMC4wNzIxMDQgNC4xNjU5IC0wLjAwMDI2OSAzLjkxMTQxIDAuMDAwMDAxIDMuNjUxMTQgYwowLjAwMDAwMSAzLjMwMzExIDAuMTI5ODk5IDIuOTY5MzQgMC4zNjExMjEgMi43MjMyNSBjCjAuNTkyMzQyIDIuNDc3MTUgMC45MDU5NDUgMi4zMzg5IDEuMjMyOTQgMi4zMzg5IGMKMC4zMDk4MDQgMC44IDAuOTI5NDEyIHJnCi9hMS4wIGdzCjEgdwowIEoKMCBqCjQgTQpmKgpRCnEKMCAwIG0KNjEuODg4OSAxNC4xMDg0IG0KNjEuNDI5IDE0LjExNzcgNjAuOTY5NyAxNC4wNjggNjAuNTIxIDEzLjk2MDMgYwo2MC4xOTcyIDEzLjg4NTkgNTkuODk2MiAxMy43MjYgNTkuNjQ1NyAxMy40OTUyIGMKNTkuNDE5MiAxMy4yNjc4IDU5LjI1OCAxMi45NzY2IDU5LjE4MDkgMTIuNjU1NCBjCjU5LjA4MDYgMTIuMjM5IDU5LjAzMzcgMTEuODEgNTkuMDQxOCAxMS4zODAyIGMKNTkuMDQxOCA4Ljg4NjA4IGwKNTkuMDM0NSA4LjQ1ODI1IDU5LjA4MTMgOC4wMzEzMyA1OS4xODA5IDcuNjE2NzkgYwo1OS4yNTcgNy4yOTM5NiA1OS40MTgzIDcuMDAxMDMgNTkuNjQ1NyA2Ljc3MjU3IGMKNTkuODk2MiA2LjU0MTgxIDYwLjE5NzIgNi4zODE4NyA2MC41MjEgNi4zMDc1MSBjCjYwLjk2OTcgNi4xOTk3NCA2MS40MjkgNi4xNTAwMSA2MS44ODg5IDYuMTU5NCBjCjY3LjA2NTYgNi4xNTk0IGwKNjcuMDY1NiA3LjY4NjQgbAo2MS45NjU1IDcuNjg2NCBsCjYxLjc1NDIgNy42ODE0NiA2MS41NDMxIDcuNzAyODMgNjEuMzM2NSA3Ljc1MDA4IGMKNjEuMTkwOSA3Ljc4MjI2IDYxLjA1NjYgNy44NTY1NyA2MC45NDgyIDcuOTY0ODQgYwo2MC44NDc4IDguMDc2NDYgNjAuNzc5MiA4LjIxNjE4IDYwLjc1MDYgOC4zNjc3IGMKNjAuNzExMiA4LjU2ODMxIDYwLjY5MyA4Ljc3Mjk5IDYwLjY5NjQgOC45Nzc5IGMKNjAuNjk2NCAxMS4zMDc3IGwKNjAuNjkyNSAxMS41MTUgNjAuNzEwNyAxMS43MjIyIDYwLjc1MDYgMTEuOTI1MyBjCjYwLjc4MDIgMTIuMDc0MyA2MC44NDg3IDEyLjIxMTMgNjAuOTQ4MiAxMi4zMjA3IGMKNjEuMDU3NSAxMi40MzAxIDYxLjE5NDMgMTIuNTAzMiA2MS4zNDIgMTIuNTMxIGMKNjEuNTUxMSAxMi41NzM1IDYxLjc2MzggMTIuNTkyOCA2MS45NzY2IDEyLjU4ODggYwo2Ny4wNjU2IDEyLjU4ODggbAo2Ny4wNjU2IDE0LjEwMjUgbAo2MS44ODg5IDE0LjEwODQgbApoCjUyLjgxNzIgMTQuMTA4NCBtCjUyLjM1NzMgMTQuMTE3NyA1MS44OTggMTQuMDY4IDUxLjQ0OTMgMTMuOTYwMyBjCjUxLjEyNTUgMTMuODg1OSA1MC44MjQ0IDEzLjcyNiA1MC41NzQgMTMuNDk1MiBjCjUwLjM0NzUgMTMuMjY3OCA1MC4xODYzIDEyLjk3NjYgNTAuMTA5MiAxMi42NTU0IGMKNTAuMDA4OCAxMi4yMzkgNDkuOTYyIDExLjgxIDQ5Ljk3IDExLjM4MDIgYwo0OS45NyA4Ljg4NjA4IGwKNDkuOTYyOCA4LjQ1ODI1IDUwLjAwOTYgOC4wMzEzMyA1MC4xMDkyIDcuNjE2NzkgYwo1MC4xODUzIDcuMjkzOTYgNTAuMzQ2NiA3LjAwMTAzIDUwLjU3NCA2Ljc3MjU3IGMKNTAuODI0NCA2LjU0MTgxIDUxLjEyNTUgNi4zODE4NyA1MS40NDkzIDYuMzA3NTEgYwo1MS44OTggNi4xOTk3NCA1Mi4zNTczIDYuMTUwMDEgNTIuODE3MiA2LjE1OTQgYwo1NC42NTU1IDYuMTU5NCBsCjU0LjY1NTUgNy42NjI3IGwKNTIuODE3MiA3LjY2MjcgbAo1Mi42MTg4IDcuNjU3NjEgNTIuNDIwNiA3LjY3OTAxIDUyLjIyNzIgNy43MjYzOSBjCjUyLjA5MDMgNy43NTk4MiA1MS45NjM4IDcuODMwMjEgNTEuODU5OCA3LjkzMDc4IGMKNTEuNzY0NiA4LjAzMjQ0IDUxLjY5OTcgOC4xNjE3NyA1MS42NzMzIDguMzAyNTMgYwo1MS42Mzg3IDguNDk0NzggNTEuNjIzMyA4LjY5MDM4IDUxLjYyNzQgOC44ODYwOCBjCjUxLjYyNzQgOS40MjIyMyBsCjU3Ljk4NTUgOS40MjIyMyBsCjU3Ljk4NTUgMTAuODMyMiBsCjUxLjYyNzQgMTAuODMyMiBsCjUxLjYyNzQgMTEuMzkwNiBsCjUxLjYyNDEgMTEuNTg5MyA1MS42NDA0IDExLjc4NzkgNTEuNjc2MSAxMS45ODMgYwo1MS43MDE4IDEyLjEyMzIgNTEuNzY0NSAxMi4yNTI3IDUxLjg1NyAxMi4zNTYzIGMKNTEuOTU5MiAxMi40NTcyIDUyLjA4NjkgMTIuNTI0MSA1Mi4yMjQ0IDEyLjU0ODggYwo1Mi40MjA5IDEyLjU4NjggNTIuNjIwMyAxMi42MDQyIDUyLjgyIDEyLjYwMDYgYwo1OC4wMjg3IDEyLjYwMDYgbAo1OC4wMjg3IDE0LjEwMjUgbAo1Mi44MTcyIDE0LjEwODQgbApoCjQ0LjM1OTIgMTQuMTA4NCBtCjQ0LjM1OTIgNy42OTIzMiBsCjQxLjIyOTUgNy42OTIzMiBsCjQxLjIyOTUgNi4xNjUzMiBsCjQ5LjE2MTUgNi4xNjUzMiBsCjQ5LjE2MTUgNy42OTIzMiBsCjQ2LjAzMzMgNy42OTIzMiBsCjQ2LjAzMzMgMTQuMTA4NCBsCjQ0LjM1OTIgMTQuMTA4NCBsCmgKMzQuMzM5OCA2LjE2NTMyIG0KMzYuMDA5NyA2LjE2NTMyIGwKMzYuMDA5NyAxNC4xMDg0IGwKMzQuMzM5OCAxNC4xMDg0IGwKMzQuMzM5OCA2LjE2NTMyIGwKaAozMS40MyA4Ljk3OTM5IG0KMzEuNDM0IDguNzcyMDkgMzEuNDEzNCA4LjU2NTA4IDMxLjM2ODggOC4zNjMyNSBjCjMxLjMzNjMgOC4yMTQwNCAzMS4yNjY2IDguMDc2OTEgMzEuMTY3IDcuOTY2MzIgYwozMS4wNTkyIDcuODU4MzUgMzAuOTI0NCA3Ljc4NTgzIDMwLjc3ODcgNy43NTc0OSBjCjMwLjU3ODUgNy43MTU0IDMwLjM3NDcgNy42OTYwMyAzMC4xNzA2IDcuNjk5NzMgYwoyNy40ODQ5IDcuNjk5NzMgbAoyNy4yNzAyIDcuNjk1MDkgMjcuMDU1NiA3LjcxNDQ1IDI2Ljg0NDcgNy43NTc0OSBjCjI2LjY5OTEgNy43ODU4MyAyNi41NjQzIDcuODU4MzUgMjYuNDU2NSA3Ljk2NjMyIGMKMjYuMzU3OSA4LjA3NjIxIDI2LjI5MTIgOC4yMTQwMyAyNi4yNjQ1IDguMzYzMjUgYwoyNi4yMjg5IDguNTY2MzggMjYuMjEyNSA4Ljc3Mjc5IDI2LjIxNTcgOC45NzkzOSBjCjI2LjIxNTcgMTEuMDA3IGwKMjYuMjEyOCAxMS4yNjc4IDI2LjIyNTQgMTEuNTI4NCAyNi4yNTMzIDExLjc4NzUgYwoyNi4yNjg3IDExLjk1OTggMjYuMzI3NCAxMi4xMjQ1IDI2LjQyMzEgMTIuMjY0NCBjCjI2LjUyMTYgMTIuMzg3NyAyNi42NTY1IDEyLjQ3MTggMjYuODA1OCAxMi41MDI5IGMKMjcuMDI5MSAxMi41NTE4IDI3LjI1NjkgMTIuNTczNiAyNy40ODQ5IDEyLjU2ODEgYwozMC4xNzYyIDEyLjU2ODEgbAozMC4zOCAxMi41NzE1IDMwLjU4MzcgMTIuNTUzNiAzMC43ODQzIDEyLjUxNDcgYwozMC45Mjg1IDEyLjQ5NDEgMzEuMDYzIDEyLjQyNTggMzEuMTY4OCAxMi4zMTk1IGMKMzEuMjc0NyAxMi4yMTMyIDMxLjM0NjUgMTIuMDc0MyAzMS4zNzQzIDExLjkyMjMgYwozMS40MTkxIDExLjcxNDUgMzEuNDM5NyAxMS41MDE2IDMxLjQzNTYgMTEuMjg4NCBjCjMxLjQzIDguOTc5MzkgbApoCjMxLjYxMDkgMTUuMjU0NyBtCjMwLjUzOCAxNC4wMzE0IGwKMjcuNDEzOSAxNC4wMzE0IGwKMjYuOTUxIDE0LjA0MDcgMjYuNDg4NiAxMy45OTYgMjYuMDM0OCAxMy44OTgxIGMKMjUuNzEyMSAxMy44MzIzIDI1LjQxMDcgMTMuNjc5MyAyNS4xNTk1IDEzLjQ1MzcgYwoyNC45MzMzIDEzLjIzMTQgMjQuNzcyIDEyLjk0NDUgMjQuNjk0OCAxMi42MjczIGMKMjQuNTk0MyAxMi4yMTI5IDI0LjU0NzQgMTEuNzg1OSAyNC41NTU2IDExLjM1OCBjCjI0LjU1NTYgOC44ODYwOCBsCjI0LjU0ODMgOC40NTgyNSAyNC41OTUxIDguMDMxMzMgMjQuNjk0OCA3LjYxNjc5IGMKMjQuNzcwOSA3LjI5Mzk2IDI0LjkzMjEgNy4wMDEwMyAyNS4xNTk1IDYuNzcyNTcgYwoyNS40MSA2LjU0MTgxIDI1LjcxMSA2LjM4MTg3IDI2LjAzNDggNi4zMDc1MSBjCjI2LjQ4NzMgNi4xOTk0MSAyNi45NTAzIDYuMTQ5NjggMjcuNDEzOSA2LjE1OTQgYwozMC4yNDg2IDYuMTU5NCBsCjMwLjcxMTcgNi4xNDk2NyAzMS4xNzQzIDYuMTk5NCAzMS42MjYyIDYuMzA3NTEgYwozMS45NTAxIDYuMzgxNTcgMzIuMjUxMiA2LjU0MTU0IDMyLjUwMTUgNi43NzI1NyBjCjMyLjcyOTQgNy4wMDA4OSAzMi44OTExIDcuMjkzODIgMzIuOTY3NyA3LjYxNjc5IGMKMzMuMDY2NiA4LjAzMTQ3IDMzLjExMzQgOC40NTgyOSAzMy4xMDY5IDguODg2MDggYwozMy4xMDY5IDExLjM0NDcgbAozMy4xMjAzIDExLjgyNzkgMzMuMDU3MyAxMi4zMSAzMi45MjA0IDEyLjc3MSBjCjMyLjgwMjIgMTMuMTMyNCAzMi41NjU1IDEzLjQzNjMgMzIuMjUzOCAxMy42MjcgYwozMy42NTY1IDE1LjI1NDcgbAozMS42MTA5IDE1LjI1NDcgbApoCjc1LjM0NzUgMTIuMTU5OCBtCjc1LjM0NzUgMTAuOTYwMSBsCjY5Ljg3NTggMTAuOTYwMSBsCjY5Ljg3NTggMTQuMTI4MSBsCjY4LjIxMjkgMTQuMTI4MSBsCjY4LjIxMjkgNi4xODM1OSBsCjY5Ljg3NTggNi4xODM1OSBsCjY5Ljg3NTggOS40MjI3MyBsCjc1LjM0NzUgOS40MjI3MyBsCjc1LjM0NzUgNi4xODM1OSBsCjc2Ljk5OTMgNi4xODM1OSBsCjc2Ljk5OTMgMTIuMTU5OCBsCjc1LjM0NzUgMTIuMTU5OCBsCmgKNzYuOTk5OCAxMi42ODg1IG0KNzUuMzUzNSAxMi42ODg1IGwKNzUuMzUzNSAxNC4xNTE4IGwKNzYuOTk5OCAxNC4xNTE4IGwKNzYuOTk5OCAxMi42ODg1IGwKaAowLjMwOTgwNCAwLjggMC45Mjk0MTIgcmcKL2ExLjAgZ3MKMSB3CjAgSgowIGoKNCBNCmYKUQoxIHcKMCBKCjAgago0IE0KbgpRClEKUQpRClEKcQpxCjM3NC44NTAzOTQgMTMzLjY5NTMxMiA0NCA0NCByZQpXCm4KcQovYTEgZ3MKMSAwIDAgMSAzNzQuODUwMzk0IDEzMy42OTUzMTIgY20KcQpxCjEgMCAwIDEgMCAwIGNtCjEgMCAwIDEgMCAwIGNtCnEKNDMuMiAyMS42IG0KNDMuMiAzMy43ODY0OTUgMzMuNzg2NDk1IDQzLjIgMjEuNiA0My4yIGMKOS40MTM1MDUgNDMuMiAwIDMzLjc4NjQ5NSAwIDIxLjYgYwowIDkuNDEzNTA1IDkuNDEzNTA1IDAgMjEuNiAwIGMKMzMuNzg2NDk1IDAgNDMuMiA5LjQxMzUwNSA0My4yIDIxLjYgYwpoCjEgMC4yNTA5OCAwLjUwMTk2MSByZwovYTEuMCBncwoxIHcKMCBKCjAgago0IE0KZgpRCnEKMCAwIG0KMjIuNjk1IDIwLjU4NSBtCjIwLjUwNSAyMC41ODUgbAoxOS4yNjA4MjggMjAuNTg3MjE3IDE4LjI0OTUxMSAxOS41ODIxNjIgMTguMjQ0IDE4LjMzOCBjCjE4LjI1MDA2IDE3LjA5NDIyOSAxOS4yNjEyMTYgMTYuMDg5NzgxIDIwLjUwNSAxNi4wOTIgYwoyNC44ODQgMTYuMDkyIGwKMjUuNDQ4IDE2LjA5MiAyNS45MDUgMTUuNjM3IDI1LjkwNSAxNS4wNzcgYwoyNS45MDUgMTQuNTE3IDI1LjQ0OCAxNC4wNjIgMjQuODg0IDE0LjA2MiBjCjIyLjYyMiAxNC4wNjIgbAoyMi42MjIgMTEuODE1IGwKMjIuNjIyIDExLjI1NSAyMi4xNjQgMTAuOCAyMS42IDEwLjggYwoyMS4wMzYgMTAuOCAyMC41NzggMTEuMjU0IDIwLjU3OCAxMS44MTUgYwoyMC41NzggMTQuMDYyIGwKMjAuNTA2IDE0LjA2MiBsCjE4LjEzMSAxNC4wNjIgMTYuMiAxNS45OCAxNi4yIDE4LjMzOCBjCjE2LjIgMjAuNjk2IDE4LjEzMSAyMi42MTUgMjAuNTA2IDIyLjYxNSBjCjIyLjY5NSAyMi42MTUgbAoyMy45MzkxNzIgMjIuNjEyNzgzIDI0Ljk1MDQ4OSAyMy42MTc4MzggMjQuOTU2IDI0Ljg2MiBjCjI0Ljk0OTk0IDI2LjEwNTc3MSAyMy45Mzg3ODQgMjcuMTEwMjE5IDIyLjY5NSAyNy4xMDggYwoxOC4zMTcgMjcuMTA4IGwKMTcuNzUyIDI3LjEwOCAxNy4yOTUgMjcuNTYzIDE3LjI5NSAyOC4xMjMgYwoxNy4yOTUgMjguNjgzIDE3Ljc1MiAyOS4xMzggMTguMzE2IDI5LjEzOCBjCjIwLjU3OCAyOS4xMzggbAoyMC41NzggMzEuMzg1IGwKMjAuNTc4IDMxLjk0NSAyMS4wMzYgMzIuNCAyMS42IDMyLjQgYwoyMi4xNjQgMzIuNCAyMi42MjIgMzEuOTQ2IDIyLjYyMiAzMS4zODUgYwoyMi42MjIgMjkuMTM4IGwKMjIuNjk1IDI5LjEzOCBsCjI1LjA2OSAyOS4xMzggMjcgMjcuMjIgMjcgMjQuODYyIGMKMjcgMjIuNTA0IDI1LjA2OSAyMC41ODUgMjIuNjk1IDIwLjU4NSBjCmgKMSAxIDEgcmcKL2ExLjAgZ3MKMSB3CjAgSgowIGoKNCBNCmYKUQoxIHcKMCBKCjAgago0IE0KbgpRClEKUQpRClEKcQpxCjAuNDExNzY1IDAuNDQ3MDU5IDAuNDkwMTk2IHJnCi9hMS4wIGdzCkJUCjEgMCAwIC0xIDM4NC43NzQyMjIgMjE0LjYyMzA0NyBUbQovT0NITlVQIDEyIFRmClsgPDAwMzcwMDI4MDAyNz4gXSBUSgpFVAowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKQlQKMSAwIDAgLTEgMzI4LjM1MDM5NCAyNjEuNTQ2ODc1IFRtCi9WQ0FUV1MgMzIgVGYKWyA8MDAzNTAwMDcwMDAzMDAxYjAwMGYwMDFiMDAxOT4gXSBUSgpFVApRClEKcQpxCjAgMjcyLjQ2ODc1IDc5My43MDA3ODcgNTU3IHJlClcKbgpxCjEgMSAxIHJnCi9hMS4wIGdzCjAgMjcyLjQ2ODc1IDc5My43MDA3ODcgNTU3IHJlClcKbgowIDI3Mi40Njg3NSA3OTMuNzAwNzg3IDU1NyByZQpmClEKUQpRCnEKcQpxCnEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTAuNyBncwpCVAoxIDAgMCAtMSA3NS41OTA1NTEgMzU4LjYyMzA0NyBUbQovVkNBVFdTIDEyIFRmClsgPDAwMzEwMDUyMDA1MDAwNDg+IF0gVEoKRVQKUQpRCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2ExLjAgZ3MKQlQKMSAwIDAgLTEgMzk2Ljg1MDM5NCAzNjAuMTIzMDQ3IFRtCi9WQ0FUV1MgMTIgVGYKWyA8MDAzNDAwMmMwMDAzMDAzNjAwMjYwMDI3MDAwMzAwMzYwMDExMDAyND4gLTE4IDwwMDExPiBdIFRKCkVUClEKUQpRClEKcQpxCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2EwLjcgZ3MKQlQKMSAwIDAgLTEgNzUuNTkwNTUxIDM5Ny42MjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDI2MDAzMzAwMjkwMDEyMDAyNjAwMzEwMDMzMDAyZD4gXSBUSgpFVApRClEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTEuMCBncwpCVAoxIDAgMCAtMSAzOTYuODUwMzk0IDM5OS4xMjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDE2MDAxNTAwMTEwMDE3MDAxMzAwMTUwMDExMDAxODAwMTMwMDE1MDAxMjAwMTMwMDEzMDAxMzAwMTQwMDEwMDAxNjAwMTg+IF0gVEoKRVQKUQpRClEKUQpxCnEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTAuNyBncwpCVAoxIDAgMCAtMSA3NS41OTA1NTEgNDM2LjYyMzA0NyBUbQovVkNBVFdTIDEyIFRmClsgPDAwMmMwMDUxMDA1NjAwNTcwMDRjMDA1NzAwNTgwMDRjMDBhOTAwYTUwMDUyMDAwMzAwMjkwMDRjMDA1MTAwNDQwMDUxMDA0NjAwNDgwMDRjMDA1NTAwNDQ+IF0gVEoKRVQKUQpRCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2ExLjAgZ3MKQlQKMSAwIDAgLTEgMzk2Ljg1MDM5NCA0MzguMTIzMDQ3IFRtCi9WQ0FUV1MgMTIgVGYKWyA8MDAzNDAwMmMwMDAzMDAzNjAwMzIwMDI2MDAyYzAwMjgwMDI3MDAyNDAwMjcwMDI4MDAwMzAwMjcwMDI4MDAwMzAwMjYwMDM1MDA4YjAwMjcwMDJjMDAzNzAwMzIwMDAzMDAyNzAwMmMwMDM1MDAyODAwMzcwMDMyMDAwMzAwMzYwMDExMDAyND4gLTE4IDwwMDExMDAwMzAwMGIwMDE2MDAxNTAwMWMwMDBjPiBdIFRKCkVUClEKUQpRClEKcQpxCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2EwLjcgZ3MKQlQKMSAwIDAgLTEgNzUuNTkwNTUxIDQ3NS42MjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDI0MDA0YTAwYWMwMDUxMDA0NjAwNGMwMDQ0PiBdIFRKCkVUClEKUQpxCnEKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCi9hMS4wIGdzCkJUCjEgMCAwIC0xIDM5Ni44NTAzOTQgNDc3LjEyMzA0NyBUbQovVkNBVFdTIDEyIFRmClsgPDAwMTMwMDEzMDAxMzAwMTQ+IF0gVEoKRVQKUQpRClEKUQpxCnEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTAuNyBncwpCVAoxIDAgMCAtMSA3NS41OTA1NTEgNTE0LjYyMzA0NyBUbQovVkNBVFdTIDEyIFRmClsgPDAwMjYwMDUyMDA1MTAwNTcwMDQ0PiBdIFRKCkVUClEKUQpxCnEKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCi9hMS4wIGdzCkJUCjEgMCAwIC0xIDM5Ni44NTAzOTQgNTE2LjEyMzA0NyBUbQovVkNBVFdTIDEyIFRmClsgPDAwMTMwMDEzMDAxMzAwMTMwMDE0MDAxMDAwMWE+IF0gVEoKRVQKUQpRClEKUQpxCnEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTAuNyBncwpCVAoxIDAgMCAtMSA3NS41OTA1NTEgNjE3LjYyMzA0NyBUbQovVkNBVFdTIDEyIFRmClsgPDAwMzEwMDUyMDA1MDAwNDgwMDAzMDA0NzAwNTIwMDAzMDAyNTAwNDgwMDUxMDA0ODEzYWUwMDQ2MDA0YzAwYTMwMDU1MDA0YzAwNTI+IF0gVEoKRVQKUQpRCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2ExLjAgZ3MKQlQKMSAwIDAgLTEgMzk2Ljg1MDM5NCA2MTkuMTIzMDQ3IFRtCi9WQ0FUV1MgMTIgVGYKWyA8MDAzNzAwNGMwMDU3MDA1ODAwNGYwMDQ0MDA1NTAwMDMwMDQ3MDA0NDAwMDMwMDI2MDA1MjAwNTEwMDU3MDA0ND4gXSBUSgpFVApRClEKUQpRCnEKcQpxCnEKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCi9hMC43IGdzCkJUCjEgMCAwIC0xIDc1LjU5MDU1MSA2NTYuNjIzMDQ3IFRtCi9WQ0FUV1MgMTIgVGYKWyA8MDAyNjAwMzMwMDI5MDAxMjAwMjYwMDMxMDAzMzAwMmQ+IF0gVEoKRVQKUQpRCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2ExLjAgZ3MKQlQKMSAwIDAgLTEgMzk2Ljg1MDM5NCA2NTguMTIzMDQ3IFRtCi9WQ0FUV1MgMTIgVGYKWyA8MDAxNTAwMTYwMDExMDAxODAwMWMwMDFjMDAxMTAwMWIwMDFiMDAxODAwMTIwMDEzMDAxMzAwMTMwMDE0MDAxMDAwMWMwMDE1PiBdIFRKCkVUClEKUQpRClEKcQpxCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2EwLjcgZ3MKQlQKMSAwIDAgLTEgNzUuNTkwNTUxIDY5NS42MjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDJjMDA1MTAwNTYwMDU3MDA0YzAwNTcwMDU4MDA0YzAwYTkwMGE1MDA1MjAwMDMwMDI5MDA0YzAwNTEwMDQ0MDA1MTAwNDYwMDQ4MDA0YzAwNTUwMDQ0PiBdIFRKCkVUClEKUQpxCnEKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCi9hMS4wIGdzCkJUCjEgMCAwIC0xIDM5Ni44NTAzOTQgNjk3LjEyMzA0NyBUbQovVkNBVFdTIDEyIFRmClsgPDAwMjUwMDI2MDAzMjAwMDMwMDI3MDAzMjAwMDMwMDI1MDAzNTAwMjQwMDM2MDAyYzAwMmYwMDAzMDAzNjAwMTEwMDI0PiAtMTggPDAwMTEwMDAzMDAwYjAwMTMwMDEzMDAxNDAwMGM+IF0gVEoKRVQKUQpRClEKUQpxCnEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTAuNyBncwpCVAoxIDAgMCAtMSA3NS41OTA1NTEgNzM0LjYyMzA0NyBUbQovVkNBVFdTIDEyIFRmClsgPDAwMjQwMDRhMDBhYzAwNTEwMDQ2MDA0YzAwNDQ+IF0gVEoKRVQKUQpRCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2ExLjAgZ3MKQlQKMSAwIDAgLTEgMzk2Ljg1MDM5NCA3MzYuMTIzMDQ3IFRtCi9WQ0FUV1MgMTIgVGYKWyA8MDAxMzAwMTMwMDEzMDAxND4gXSBUSgpFVApRClEKUQpRCnEKcQpxCnEKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCi9hMC43IGdzCkJUCjEgMCAwIC0xIDc1LjU5MDU1MSA3NzMuNjIzMDQ3IFRtCi9WQ0FUV1MgMTIgVGYKWyA8MDAyNjAwNTIwMDUxMDA1NzAwNDQ+IF0gVEoKRVQKUQpRCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2ExLjAgZ3MKQlQKMSAwIDAgLTEgMzk2Ljg1MDM5NCA3NzUuMTIzMDQ3IFRtCi9WQ0FUV1MgMTIgVGYKWyA8MDAxYzAwMTUwMDFhMDAxYzAwMTkwMDEwMDAxND4gXSBUSgpFVApRClEKUQpRCnEKcQpxCnEKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCi9hMC43IGdzCkJUCjEgMCAwIC0xIDc1LjU5MDU1MSA4MTIuNjIzMDQ3IFRtCi9WQ0FUV1MgMTIgVGYKWyA8MDAzNzAwNGMwMDUzMDA1MjAwMDMwMDQ3MDA0NDAwMDMwMDI2MDA1MjAwNTEwMDU3MDA0ND4gXSBUSgpFVApRClEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTEuMCBncwpCVAoxIDAgMCAtMSAzOTYuODUwMzk0IDgxNC4xMjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDI2MDA1MjAwNTEwMDU3MDA0NDAwMDMwMDI2MDA1MjAwNTUwMDU1MDA0ODAwNTEwMDU3MDA0OD4gXSBUSgpFVApRClEKUQpRClEKUQpxCnEKMCAxMDI1LjUxOTY4NSA3OTMuNzAwNzg3IDk3IHJlClcKbgpxCjAuOTQ5MDIgMC45NTY4NjMgMC45ODgyMzUgcmcKL2ExLjAgZ3MKMCAxMDI1LjUxOTY4NSA3OTMuNzAwNzg3IDk3IHJlClcKbgowIDEwMjUuNTE5Njg1IDc5My43MDA3ODcgOTcgcmUKZgpRClEKcQo3OTMuNzAwNzg3IDEwMjUuNTE5Njg1IG0KMCAxMDI1LjUxOTY4NSBsCjAgMTAyNi41MTk2ODUgbAo3OTMuNzAwNzg3IDEwMjYuNTE5Njg1IGwKVyoKbgowIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNS45OTAxOTUgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoxMS45ODAzODkgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoxNy45NzA1ODQgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoyMy45NjA3NzggMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoyOS45NTA5NzMgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQozNS45NDExNjggMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo0MS45MzEzNjIgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo0Ny45MjE1NTcgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo1My45MTE3NTIgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo1OS45MDE5NDYgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo2NS44OTIxNDEgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo3MS44ODIzMzUgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo3Ny44NzI1MyAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjgzLjg2MjcyNSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjg5Ljg1MjkxOSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjk1Ljg0MzExNCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjEwMS44MzMzMDkgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoxMDcuODIzNTAzIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMTEzLjgxMzY5OCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjExOS44MDM4OTIgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoxMjUuNzk0MDg3IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMTMxLjc4NDI4MiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjEzNy43NzQ0NzYgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoxNDMuNzY0NjcxIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMTQ5Ljc1NDg2NiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjE1NS43NDUwNiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjE2MS43MzUyNTUgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoxNjcuNzI1NDQ5IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMTczLjcxNTY0NCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjE3OS43MDU4MzkgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoxODUuNjk2MDMzIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMTkxLjY4NjIyOCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjE5Ny42NzY0MjMgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoyMDMuNjY2NjE3IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMjA5LjY1NjgxMiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjIxNS42NDcwMDYgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoyMjEuNjM3MjAxIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMjI3LjYyNzM5NiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjIzMy42MTc1OSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjIzOS42MDc3ODUgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoyNDUuNTk3OTc5IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMjUxLjU4ODE3NCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjI1Ny41NzgzNjkgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoyNjMuNTY4NTYzIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMjY5LjU1ODc1OCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjI3NS41NDg5NTMgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoyODEuNTM5MTQ3IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMjg3LjUyOTM0MiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjI5My41MTk1MzYgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoyOTkuNTA5NzMxIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMzA1LjQ5OTkyNiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjMxMS40OTAxMiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjMxNy40ODAzMTUgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQozMjMuNDcwNTEgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQozMjkuNDYwNzA0IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMzM1LjQ1MDg5OSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjM0MS40NDEwOTMgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQozNDcuNDMxMjg4IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMzUzLjQyMTQ4MyAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjM1OS40MTE2NzcgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQozNjUuNDAxODcyIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMzcxLjM5MjA2NyAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjM3Ny4zODIyNjEgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQozODMuMzcyNDU2IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMzg5LjM2MjY1IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMzk1LjM1Mjg0NSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjQwMS4zNDMwNCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjQwNy4zMzMyMzQgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo0MTMuMzIzNDI5IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNDE5LjMxMzYyNCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjQyNS4zMDM4MTggMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo0MzEuMjk0MDEzIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNDM3LjI4NDIwNyAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjQ0My4yNzQ0MDIgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo0NDkuMjY0NTk3IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNDU1LjI1NDc5MSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjQ2MS4yNDQ5ODYgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo0NjcuMjM1MTgxIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNDczLjIyNTM3NSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjQ3OS4yMTU1NyAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjQ4NS4yMDU3NjQgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo0OTEuMTk1OTU5IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNDk3LjE4NjE1NCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjUwMy4xNzYzNDggMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo1MDkuMTY2NTQzIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNTE1LjE1NjczNyAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjUyMS4xNDY5MzIgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo1MjcuMTM3MTI3IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNTMzLjEyNzMyMSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjUzOS4xMTc1MTYgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo1NDUuMTA3NzExIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNTUxLjA5NzkwNSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjU1Ny4wODgxIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNTYzLjA3ODI5NCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjU2OS4wNjg0ODkgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo1NzUuMDU4Njg0IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNTgxLjA0ODg3OCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjU4Ny4wMzkwNzMgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo1OTMuMDI5MjY4IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNTk5LjAxOTQ2MiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjYwNS4wMDk2NTcgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo2MTAuOTk5ODUxIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNjE2Ljk5MDA0NiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjYyMi45ODAyNDEgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo2MjguOTcwNDM1IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNjM0Ljk2MDYzIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNjQwLjk1MDgyNSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjY0Ni45NDEwMTkgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo2NTIuOTMxMjE0IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNjU4LjkyMTQwOCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjY2NC45MTE2MDMgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo2NzAuOTAxNzk4IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNjc2Ljg5MTk5MiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjY4Mi44ODIxODcgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo2ODguODcyMzgyIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNjk0Ljg2MjU3NiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjcwMC44NTI3NzEgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo3MDYuODQyOTY1IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNzEyLjgzMzE2IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNzE4LjgyMzM1NSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjcyNC44MTM1NDkgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo3MzAuODAzNzQ0IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNzM2Ljc5MzkzOCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjc0Mi43ODQxMzMgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo3NDguNzc0MzI4IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNzU0Ljc2NDUyMiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjc2MC43NTQ3MTcgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo3NjYuNzQ0OTEyIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNzcyLjczNTEwNiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjc3OC43MjUzMDEgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo3ODQuNzE1NDk1IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNzkwLjcwNTY5IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKVyoKbgowLjA5ODAzOSAwLjE0MTE3NiAwLjQ5NDExOCByZwovYTEuMCBncwowIDEwMjYuNTE5Njg1IDc5My43MDA3ODcgOTYgcmUKMCAxMDI1LjUxOTY4NSA3OTMuNzAwNzg3IDk3IHJlCmYqClEKUQpxCnEKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCi9hMC43IGdzCkJUCjEgMCAwIC0xIDMyNS43NTI3MzcgMTA1Ny42NzM5ODIgVG0KL09DSE5VUCAxMiBUZgpbIDwwMDI2MDBiNTAwNDcwMDRjMDA0YTAwNTIwMDAzMDA0NzAwNDgwMDAzMDA0NDAwNTgwMDU3MDA0ODAwNTEwMDU3MDA0YzAwNDYwMDQ0MDBhOTAwYTUwMDUyMDAwMz4gXSBUSgpFVAovYTEuMCBncwpCVAoxIDAgMCAtMSAyNjkuMDc3OTMzIDEwNzEuNjczOTgyIFRtCi9PQ0hOVVAgMTIgVGYKWyA8MDAxOTAwMTQwMDE5MDA0NTAwMWMwMDE4MDAxMzAwNDQwMDEwMDAxOTAwMTMwMDQ2MDAxNzAwMTAwMDE3MDAxNDAwMWIwMDEzMDAxMDAwNDUwMDQ2MDA0ODAwMTYwMDEwMDA0NTAwNDYwMDQ2MDA0NDAwNDcwMDE4MDAxNjAwMTYwMDQ2MDAxNjAwMTUwMDQ1PiBdIFRKCkVUCi9hMC43IGdzCkJUCjEgMCAwIC0xIDI5MC42Mjg3MTQgMTA5NS42NzM5ODIgVG0KL09DSE5VUCAxMiBUZgpbIDwwMDM0MDA0YzAwMDMwMDM2MDA1MjAwNDYwMDRjMDA0ODAwNDcwMDQ0MDA0NzAwNDgwMDAzMDA0NzAwNDgwMDAzMDAyNjAwNTU+IDIxIDwwMDQ4MDA0NzAwNGMwMDU3MDA1MjAwMDMwMDI3MDA0YzAwNTU+IDIxIDwwMDQ4MDA1NzAwNTIwMDAzMDAzNjAwMTEwMDI0PiAxNyA8MDAxMT4gXSBUSgoxIDAgMCAtMSAzMTkuNDMzNDAyIDExMDkuNjczOTgyIFRtClsgPDAwMjYwMDMxMDAzMzAwMmQwMDAzMDAxNjAwMTUwMDExMDAxNzAwMTMwMDE1MDAxMTAwMTgwMDEzMDAxNTAwMTIwMDEzMDAxMzAwMTMwMDE0MDAxMDAwMTgwMDFjPiBdIFRKCkVUClEKUQpxCnEKcQpxCjc1LjU5MDU1MSAyOTQuNDY4NzUgNjUgOSByZQpXCm4KcQoxIDAuOTA1ODgyIDAuOTM3MjU1IHJnCi9hMS4wIGdzCjc1LjU5MDU1MSAyOTQuNDY4NzUgNjUgOSByZQpXCm4KNzUuNTkwNTUxIDI5NC40Njg3NSA2NSA5IHJlCmYKUQpRClEKMC4wOTgwMzkgMC4xNDExNzYgMC40OTQxMTggcmcKL2ExLjAgZ3MKQlQKMSAwIDAgLTEgNzUuNTkwNTUxIDI5OS4wMDc4MTIgVG0KL1ZDQVRXUyAxNiBUZgpbIDwwMDMyMDA1NTAwNGMwMDRhMDA0OD4gXSBUSgoxIDAgMCAtMSA3NS41OTA1NTEgMzIxLjAwNzgxMiBUbQpbIDwwMDUwPiBdIFRKCkVUClEKUQpxCnEKcQpxCjc1LjU5MDU1MSA1NTMuNDY4NzUgNjUgOSByZQpXCm4KcQoxIDAuOTA1ODgyIDAuOTM3MjU1IHJnCi9hMS4wIGdzCjc1LjU5MDU1MSA1NTMuNDY4NzUgNjUgOSByZQpXCm4KNzUuNTkwNTUxIDU1My40Njg3NSA2NSA5IHJlCmYKUQpRClEKMC4wOTgwMzkgMC4xNDExNzYgMC40OTQxMTggcmcKL2ExLjAgZ3MKQlQKMSAwIDAgLTEgNzUuNTkwNTUxIDU1OC4wMDc4MTIgVG0KL1ZDQVRXUyAxNiBUZgpbIDwwMDI3MDA0ODAwNTYwMDU3MDA0YzAwNTE+IF0gVEoKMSAwIDAgLTEgNzUuNTkwNTUxIDU4MC4wMDc4MTIgVG0KWyA8MDA1Mj4gXSBUSgpFVApRClEKUQpRClEKUQpRClEKcQowIDAgNTk1LjMwMzkzNzAwNzg3NCA4NDEuODg5NzYzNzc5NTI4IHJlClcKbgowLjEgdwpxCjEwIC0wLjExIDU3NS4zIDgxNCByZQpXKgpuCnEKL0VHUzYgZ3MKL1RyNSBEbwpRClEKUQoKZW5kc3RyZWFtCmVuZG9iago2IDAgb2JqCjw8Ci9DQSAwLjMKL2NhIDAuMwo+PgplbmRvYmoKNyAwIG9iago8PAovVHlwZSAvRm9udAovU3VidHlwZSAvVHlwZTAKL0Jhc2VGb250IC9WQ0FUV1MrRGVqYVZ1LVNhbnMtQm9sZAovVG9Vbmljb2RlIDggMCBSCi9FbmNvZGluZyAvSWRlbnRpdHktSAovRGVzY2VuZGFudEZvbnRzIFsgOSAwIFIgXQo+PgplbmRvYmoKOCAwIG9iago8PAovRmlsdGVyIC9GbGF0ZURlY29kZQovTGVuZ3RoIDQ3NAo+PgpzdHJlYW0KeNpdlM2K20AQhO96ijluDos0f7IXjCBsLj7khzh5gLHU8gpiSYzlg98+o/mEAxFIUFR3V1c3rfL9+OU4Dosqf8SpPcmi+mHsotyme2xFneUyjIU2qhvaZUP5217DXJQp+fS4LXI9jv1UHA6q/JnI2xIf6uVzN53lU1F+j53EYbyol9/vp4RP93n+I1cZF1UVTaM66VOhr2H+Fq6iypz2euwSPyyP15TzL+LXYxZlMtY0006d3ObQSgzjRYpDlZ5GHfr0NIWM3X+8r0k79+1HiGu4qVN4VTnbrMibjOoeVIE6kM1oV4E8yIDeQHVGzpGn4TRIQDsiHZF7OJ9RhYJBwRFZE2lBHuTpekfXAXXZgehM4CzI02dFFUMVfc7I7uF6uBaOmhZHFg8ODxZ/Hn8pIXNvcHTmUTfouU2PKoYqhiqOKhbvHu8GdYe6ZiuGrZgOLsChZ9HTuLW41ajbTR0Fi4Jm8pbJa3qx9KLZu2HvDn81/jx5O/Ic6vU2a/p0W59EOiL3zLqlSgUyTF6jYDcOZEDJZlbYdgsnm3c4C2fw7lbv2gYhr352HvAveHRsu2bbBpSsrkezXcd6PuuVP2+zvceYzjL/CvI9rpc4jPL8W8zTvGat719+JgsqCmVuZHN0cmVhbQplbmRvYmoKOSAwIG9iago8PAovVHlwZSAvRm9udAovU3VidHlwZSAvQ0lERm9udFR5cGUyCi9CYXNlRm9udCAvVkNBVFdTK0RlamFWdS1TYW5zLUJvbGQKL0NJRFN5c3RlbUluZm8gPDwKL1JlZ2lzdHJ5IChBZG9iZSkKL09yZGVyaW5nIChJZGVudGl0eSkKL1N1cHBsZW1lbnQgMAo+PgovQ0lEVG9HSURNYXAgL0lkZW50aXR5Ci9XIFsgMyBbIDM0OCBdIDcgWyA2OTYgXSAxMSBbIDQ1NyA0NTcgXSAxNSBbIDM4MCA0MTUgMzgwIDM2NSA2OTYgNjk2IDY5NiA2OTYgNjk2IDY5NiA2OTYgNjk2IDY5NiA2OTYgXSAzNiBbIDc3NCA3NjIgNzM0IDgzMCA2ODMgNjgzIF0gNDQgWyAzNzIgMzcyIF0gNDcgWyA2MzcgXSA0OSBbIDgzNyA4NTAgNzMzIDg1MCA3NzAgNzIwIDY4MiBdIDY4IFsgNjc1IF0gNzAgWyA1OTMgNzE2IDY3OCBdIDc0IFsgNzE2IF0gNzYgWyAzNDMgXSA3OSBbIDM0MyAxMDQyIDcxMiA2ODcgNzE2IF0gODUgWyA0OTMgNTk1IDQ3OCA3MTIgNjUyIF0gMTM5IFsgNjgzIF0gMTYzIFsgNjc1IF0gMTY1IFsgNjc1IF0gMTY5IFsgNTkzIF0gMTcyIFsgNjc4IF0gNTAzOCBbIDc0MSBdIF0KL0ZvbnREZXNjcmlwdG9yIDEwIDAgUgo+PgplbmRvYmoKMTAgMCBvYmoKPDwKL1R5cGUgL0ZvbnREZXNjcmlwdG9yCi9Gb250TmFtZSAvVkNBVFdTK0RlamFWdS1TYW5zLUJvbGQKL0ZvbnRGYW1pbHkgKERlamFWdVwwNDBTYW5zKQovRmxhZ3MgNAovRm9udEJCb3ggWyAwIC0yMzUgMTA0MiA5MjggXQovSXRhbGljQW5nbGUgMAovQXNjZW50IDkyOAovRGVzY2VudCAtMjM1Ci9DYXBIZWlnaHQgOTI4Ci9TdGVtViA4MAovU3RlbUggODAKL0ZvbnRGaWxlMiAxMSAwIFIKPj4KZW5kb2JqCjExIDAgb2JqCjw8Ci9MZW5ndGgxIDM5NDA0Ci9GaWx0ZXIgL0ZsYXRlRGVjb2RlCi9MZW5ndGggNDQ5MQo+PgpzdHJlYW0KeNrtXAlUVUe2PedOEJx4jCJGeTwG0SgIImomo4hDFI1R4oDK+Jh8gAIqCqIxKw4Z1BgVTGKQEEdikNAd2xBbSbRjjG2MwUSN2oZl6zdoDCuO8Ip/6r4HQft3/5//V/5a6VV7W/feuvdU1alTp07VZfkuIAB0giUgw4SoqEnj1iRUbAYoGUV3u4+MHBHltcVrI+WTKL9i/LPBoRkBFTkAOIXyMYmW+Ozm3cYDAM+FUP6LlPicbHAgQsljlO+YMjvffGrZty8AvOgD4Nycmhyf5Dt45C169h2lgal0o+Oabn5Unxvl/VItuQsGxHTvRvlKgMlLZmclxpvTEnyp/maAfr6W+AXZnl6QT88HkbxPZrwl+ZGOT80F2Nid7rHsrJzclrMwjdrvzp8D75s0c+/ho5WDZnV57Cb0dASOM9c2L+fn72/CQ1YLi3KodsggWUeQwAYq52BhDwM4xlgtdF2t19QOrpX8jqczhJLdRlC6/7lEeVTWSzWgAqhhaglV2cN2lr8Bs+RCIh0cZVlTJEkheXlou8ITzCOSSHefJtTcmBtucrBgvU0nDuUYmNuaOXK/VupaKG2fl7dDJaXytrwTWOSJkEXnE1KDLp9A6TKlMkorKcVS2kypyJ4vpJQO/wJaf3DSvKBGvQBmrZzO822pTcd7UCPda3lF18/Ldl+rghqN+qGes521ICrzCaxT88AJfiVUM0zR7bIfpqj7SH+LLc+v9fb3Q0WbLnTtGAM71SqoUIt0ef2Z3AgVyieQLp8Eb3pWqkZAT/h/hgJoeSCv/V/rbD8OvwVabd96btN9/y/51vEQEBAQEBAQ+C33EbD8N6q3XFhXQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEDg9wn1OvQRVhAQEBAQ+H2Cfw1W/0qsTMnN/t1XN1BgL517gw9dOdHRD4JgMETBGBgLkyAekiEF0iAb5sERuAj1cBmuNmFLC4Au2wsegadgNMlGk2yiLjsb5t4v21L/L1jbyq7vPfil2l+FZ+zMhJd0vgk7qWeH4RZ2wUdxAW7EzyQHyVtKlt55gAelO3KA/KxskV/Q+Zq8i1hDrFNUpbcyS1mrnFAu/TOqPsRx6mJ1D7FRbdQcdLpr47X52rvaKeIthwEOzzksddjwv+a7dh7+b/nVr+R54lU7b3E6SoKCgr87uv0KDhcUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFPy3ZpagoKCgoODvkov1/+leyk6qmuYGJugN/QHQJAcEBBo8PDwNgQEB4QMGRkSEuVPOnd/19PBwd9McZIOmubt5uBoGDgwfECB7l2Hh1aycH/KNPx65WY9lSZ8l0z8fduzn22UjJ0ffeO65Cewk9lX7BaH26JMKRmi9q3d8cOShy/WOvt6sd7DKLmq9Pvpw76HO8jBUlRHhjw5ne9hVHDYscjgpBJWsUVY0F+hEGWOAFD7AJcKoSe5uLrLCvil5bV0xBi1ZUsQab+PHZ8/iwZvX2KPnzrEhVLKcNUp3bCVdB7qED5ACjR4u7m6SQ/kSAgYVr3uthDVex8PnzuGhazfZk2fPsuG3eZsWdk4ajMtApZJGg2xyPYGpt+uScBk7zl7CPJLIwhqpXrrAfytAEsYsKdf6snSBneOlTwDope3PqCwrpqKF/Bm0DJMa1Dr+DMPQJHU+b/3pnFp31wISJLTUq8HqDegAnvTUOcDkqxmcPcJCB6IzGH3AoB/l3WkFBenpBYvScSk7wM6w0+wADsVADMChUgN2vXSJXWGXrlzBruwVZsF1mIO5uI5ZqO3LAKpCbTvpeqkGf1LOYLyBk9g7OB0zcVJTAzrJh0ahNqopnN2iEmUAygXSqCu3PQmjPuSklwMNfpiPwt1BipbWNn0iGUdHvZI37dTC59lC7IhBiz9Hb3YJvfHisMWRaUvGjcVRffo2nFx4cg+3wsqWeuU61duLMtypFKOv7nXUV16/Kdx+0b4hed/Gt1gF25dzec7supSSd7a9s6ls7aurFs/YP3Pu32ajCY2rZP/Ag+vPX/b3x6CBEemJ5rQ702fEzOwdhN18fP58YNk2snEs2SCMbCDp/oRG2WgIM5i4HQxSI5uGW4diRV0de92arhRbV8u7myey/2A30BnHcL030whJVPph28i6c93A3Q3uV5+0Pi1/bJ33yNQQNGAI+wM7U3R30cKz8S9v2fLyszWz1Tp26XLHTuzHnxvZ9f6hGBwVtTJv3oo+fUmrImrBpF4nH/CjBn35RLPVioYAvWZqMlRv0uYQoR7SpWSCOTkZ583aPqHigPOwTdMvoRc7zO6wc+wg5uGIlFrp4jI7pGOsoW+fP9f0789+Pn2DXcCVmIZzcZuPPi403tepfxrvnzsa0bhSSbbuYyulQGt/te50k6Ls41GjkLR00T3VBMH36+nPw4af0eYbtrH18aNA4ur2i3mkI7Nzc2dnzJ3LClaswm5kpC7Y7aUVxW+QM58npb95ozExdlpCwrTYROnNeZmZeXmZWXlFQTuLPj58aH/RzqDeH685X19/fs3HOHlqXNzUqbPiyHLppFNnslxXbrkI22hEaJrJF8IHtFrLNwBbdSCFj8Vun1hxwBC5adoldhkHowP64VC2iu1LO4BFyWYyqdlsRLc+ZK3QUOxw5if0ZfNYMXuVTe0pXV+27PkXXnh+2TL+myGaUVog2c2BX3GnQp2yEmXdOosVSkF4VApihdbtWPIFOrMbat29PpK/NJHbsoY8ciWVdQQD8EGwTwGDa+uFfYaQv9nmgcv0mTOn132fm5eb9700qmAF+46dsi6VhmEEeprldROixz3DPrXmJCTGx7N8ycuv9pVvv1brao5bSmiEzWSlWBo5LwB/Mk6rE3nq3sWjKreaGpv+90L2EhuL1ZhX+Pf0jC9z/trQ8NecLzMmRgzCLZiMZtwyKIIdHR3J7ly5zO5EjuZWoJ5og/We8PhlsA83ktqetrirUS+kx1c13L1zzXoTN+AkHDc/zWxOW8AqielKVfOcqxfOX0FTfG4yu7NtB7udnBvP/ZJqVi5SzR1s866VNUoX61wpxVoilTedpVl1jl2ltNMWhXmZo1TmofZl2kqwolZ563K7tPS4LS5z6RoKrkV8lOhZyyvMrD+ztU72Mul94zIn2LHoxxYsIskaihMNaHrx+fb6qq1tk6xNx6boNu3UW63aIRdBLrVb6okWNtF6ka1T65pBgXt9FGjWf5dGI6eZ21YH+1jxVU1uXRroKJsra2sr99TW7sFULGa08LASloIlymnW3PADa0blhwZU0JMlsfVsA0vCNzEdM/BN2+jpfugErlwn7msK9dTYNpA1UhE+jP1pCaxnrAiX1mUvXJit1lmv/mC13lP2s1mWpKTZuqasTte0C3hTnaY29cgDaFZwzT3smq/uwVYzM5ZgCimx/pvPsS9by+ora/dXUxe8sRhnc+WoG2ub2euxrFJTqBs3Wmy9sHsc6B7X/ZeZ4yW1ThWKP56uRtrRmKQL+Wlp+WWsSBpLS6Xr6jXjC4eeYOY/RsyZKT85LcU8hS1lt6zkLodPvb6/r0vRUjYFc7In8pFaRzOmL/UmkPt0gD10eHraly0/ivuKzUCBgbbQF6ooRxddTV31wtS88rtfsbPs5Kvs+9WrsUPB4henr1j/t+Pog50XoaJuZZ9GDBo74bHhXY2hX9Tc/mlgOI4YO25SdNTYHsaQr6ou3PDn7VNEUdP12NLmx05qHDOwIubMfbgpWqniVp9Ca+ohZRHJ+7ePyOH+BmM4D4O6bmH3rapSWfac6c8kr8I0tnFU9dLdpykO+5588dWcw5NzruRiMHbCO2PHRI5bawlabl261TzjaNmhvd0nj+/XDw3dH/6Ra8dbDadWvdpbh8cQQ7voooSPXjd+w7ZtGyZtHDrpvedo1uzEGAyeskt5nH0XGvL+W2+9H9qfne3Zk0KYOzGiJ1+peTynnamzPra823o3eJVhoR5yuzgub+U7rDFVecfZLXQ6nvtBWU5+fs7c/Hy5Rppyt6EsMRZHo0wcPaP5yPbS0u082SymOpHubtxP0d3o8YDiPqDarKU6NX/U6c2X51wrLCKrf8nex6fRFx3xcbZmflzq885SmHnx4uGRrCGkP4ajJ7rgEFa7zlyYl8n7waLUzko+9aKXLebqCxJ1wTPcaFuTWrcOcrtlVN5K/TnGfsaOx/KqxlD/drGatE8TZ1ZPryxvyCpYkJNdULA/IRaH32vCp2ITtzYbWCOr9zGi58DwTeWyVr5h09vl6zeUc8+ooIOLxn/R2s6HKtDMNvGkxDWVam7sOz6av0jqcrqM5na3gT/bCeBQTdbi3sU3IR7uVM0v+0GjwTYcBvu+iEZ9X+RH2Qc/p70vRkWbsyRWPHRiSjZlU4ftSsmtkremWq7XW2OkUZ26d5ufsf1t6xlp1L6MHW9ZTytx5bPism36qC7Upr6eGMOpicCAB1pRXVhxJ2f3Uf2yl/D+PPPHzNoj0k5rTBa+sTazmynwvRK9voQZ1+0jHkj12WNoO3O3i6HSwfmFhfPzCgryKFqNYB+xC7Qp+ROOlBft2rJlF08I7DPWQPwMB6EbcRC3MotRZ1Ldur/6tynIa6TJ59quMcmFazqmOu84OrFbx/Oqy3MWLcohny2zVmtOpCr7kFmJH86QI3a8/fYO3V1t1pAbqAUDZR40g6fcEDwjeNV6XvOIDwpdeveSgz3c97xrbVbi9mYmyyqVpx2SkkDlH4hkyj9swG2RTB9Dz5xTs8yJT8c/ia77aUN5L+taYcbF3LT00ZYnfzzwc3PiGZrCN0JCwsL79OvwkKl01wfVJhM6DxgwZHBIcCfHHmXvVlX04LrTDJPL1c18bdHnsoGMEWagVsNp9x1mkMJwDlv9ROxeduzrPVVV6mZW2wLMPzqiBfZ8jWcR8AleSymNn6bE8WjjSj1340uJp03rtgARUIqpUmeDx0jyCO6/z/zBUnsUq6WK7OnsWr/l871NARUlUlBTaRn3CYSe5GNeVKe+50W+betJ2xtP9MAUNpLNV+Ka78laUym9LFiU63KZZtbf3Yz07racXnFWf6qZ2Qr+KqGxLOkordTUQ6P+okyqBAa2mVSaNiRiUVGIeQCGPmsc8lSfvk+kB8+a3qlTsXOXfr26TXyspcW2a3DIcAngkcLZwbOLQtsvuq9Hds1M9yP5fZgHtAlvuz+49b60ufU+y+Ixme5H6fIL+S/YbfKqk17PKF1+BZwGbtXl1K986pdmeycNdDDh8kaEqr/8pYp37uJF/i6tesux2mDggxlIs5A7j7tJ9xFP+wiEh+l9lqQIRQv28gt4KWWG3+igxz38u/j14tfD1Un+ktLziUcdV7zu3aNPF+ehg+mqK49QtM1Sh+lxx8v2pim76w207tvIRbg/yqf5SjXm8NNDJMY2sgy2sbLyi1M8eKHfDxGR0U2lclwzJYToD9+niqw0Yi3R6q3WEWNhNGL1n6q32B3+i3gHmMZ/5a/QHgxD9L+G8GsED8rZriVwxCj7tQw+GG2/Vtpdq9AVM+3XGvTAF2E4ZEE25MNcSIMUSIVc2tf3gkQIonMohBDD6CqBJHxgGMnkQg6luZAM8WCBR+juaMgk+X509RTMJvrAxLa6cvRcMp2Tqcw8OiaRpNP/oNWBba3y7xbMo7bSqUwmSXM94qnMr2sxkq7SqVwM5JFEIsnG67Ul6yXi9R75UC2ZdMwmmQSqN43kfKh8FrUerz97sJ5n9VpySKMskk/6J0992p7H6FrlUF1ZekuhpFsYRNxXrrVU37ZStq88EFq+JS/4r0GjDxLNG1mfJYQzy7NW6+drm5e3nfmTjm0luA/zL0c4EJHWmY507EIrAurfjUAa3b50DCYi9CctkfSMpGMUzUmEMUSEsUSE8aQ1wmSYSkf+vQaEd4gI7xIRdhD5ilAB6LrbdTdI/wme7KGpCmVuZHN0cmVhbQplbmRvYmoKMTIgMCBvYmoKPDwKL1R5cGUgL0ZvbnQKL1N1YnR5cGUgL1R5cGUwCi9CYXNlRm9udCAvT0NITlVQK0RlamFWdS1TYW5zCi9Ub1VuaWNvZGUgMTMgMCBSCi9FbmNvZGluZyAvSWRlbnRpdHktSAovRGVzY2VuZGFudEZvbnRzIFsgMTQgMCBSIF0KPj4KZW5kb2JqCjEzIDAgb2JqCjw8Ci9GaWx0ZXIgL0ZsYXRlRGVjb2RlCi9MZW5ndGggNDAyCj4+CnN0cmVhbQp42l2Ty4rbMBSG934KLaeLwbYsOTMQDGW6yaIXmvYBZOk4Y2hsoziLvH1lfWYKNSTw8Z/Lf6Sj8u305TSNqyp/xNmfZVXDOIUot/kevaheLuNU1FqF0a875X9/dUtRpuTz47bK9TQNc3E8qvJnEm9rfKinz2Hu5VNRfo9B4jhd1NPvt3Pi831Z/shVplVVRdepIEMq9NUt39xVVJnTnk8h6eP6eE45/yJ+PRZROnONGT8HuS3OS3TTRYpjlb5OHYf0dYVM4T/dVKT1g393cQuvmxReVU3VZeqhF0hn0gNk0TR0gEymaiDSQ9TUe01DZA29QBYKkINeoTZTQwdLB02eIU+jmV1roSZTj88BMkS2RBoPvUIOOmSyTNsyraFfSz/DDC0zWLQDmqXDgQ62JlLIw1mLF8d8Qj+HT9l9Qu1+uvhs8FlXnGeAqNmQ1+DM4qxBs2iWmoe9Js40zjR5Zs9DM2gN92e5P80dpcPaFmrfnG21thfwsbf+HmNa2fxM8q5uWzpO8vGSlnnZsrbfX0EI3FoKZW5kc3RyZWFtCmVuZG9iagoxNCAwIG9iago8PAovVHlwZSAvRm9udAovU3VidHlwZSAvQ0lERm9udFR5cGUyCi9CYXNlRm9udCAvT0NITlVQK0RlamFWdS1TYW5zCi9DSURTeXN0ZW1JbmZvIDw8Ci9SZWdpc3RyeSAoQWRvYmUpCi9PcmRlcmluZyAoSWRlbnRpdHkpCi9TdXBwbGVtZW50IDAKPj4KL0NJRFRvR0lETWFwIC9JZGVudGl0eQovVyBbIDMgWyAzMTggXSAxNSBbIDMxOCAzNjEgMzE4IDMzNyA2MzYgNjM2IDYzNiA2MzYgNjM2IDYzNiA2MzYgXSAyNyBbIDYzNiA2MzYgMzM3IF0gMzYgWyA2ODQgXSAzOCBbIDY5OCA3NzAgNjMyIF0gNDUgWyAyOTUgXSA0OSBbIDc0OCBdIDUxIFsgNjAzIDc4NyBdIDU0IFsgNjM1IDYxMSBdIDY4IFsgNjEzIDYzNSA1NTAgNjM1IDYxNSBdIDc0IFsgNjM1IF0gNzYgWyAyNzggXSA4MSBbIDYzNCA2MTIgXSA4NSBbIDQxMSBdIDg3IFsgMzkyIDYzNCBdIDE2NSBbIDYxMyBdIDE2OSBbIDU1MCBdIDE4MSBbIDYxMiBdIF0KL0ZvbnREZXNjcmlwdG9yIDE1IDAgUgo+PgplbmRvYmoKMTUgMCBvYmoKPDwKL1R5cGUgL0ZvbnREZXNjcmlwdG9yCi9Gb250TmFtZSAvT0NITlVQK0RlamFWdS1TYW5zCi9Gb250RmFtaWx5IChEZWphVnVcMDQwU2FucykKL0ZsYWdzIDQKL0ZvbnRCQm94IFsgMCAtMjM1IDc4NyA5MjggXQovSXRhbGljQW5nbGUgMAovQXNjZW50IDkyOAovRGVzY2VudCAtMjM1Ci9DYXBIZWlnaHQgOTI4Ci9TdGVtViA4MAovU3RlbUggODAKL0ZvbnRGaWxlMiAxNiAwIFIKPj4KZW5kb2JqCjE2IDAgb2JqCjw8Ci9MZW5ndGgxIDg2MDgKL0ZpbHRlciAvRmxhdGVEZWNvZGUKL0xlbmd0aCAzNDE3Cj4+CnN0cmVhbQp42u0aC1iUVfac/zEokjIwgFYKw8CQgS9GQMm0fEWELiqZYakjMOIDX+MbNl/l2OdnqCQWIZiCsoh8ieaCKWmWgGhZxBapmZKhpUJlacDc2XP/GQhs263db3e/3Y97uP9/H+ee1z3n3jv3BxAAusIqEGHa6NExYzZNL8gC8HGl1vsfGzlqtDxMDqd6ENVTxjwaE9F5mOF5qudR/cc/TOgXPLNpHgPARKpPjEsyzneKUaUDuAyh+pEZRvN8cCIAH4nqLjPmLDcljcv/EcBtEECXTxMTjPG+6x4TqO865dBEanC56CQSPT+q+yUmLVr23iavcqofA3BOmTMvznh9V/3XROoOgPxIknHZfCEPFlF/BOH7zDUmJQTceLgUoBfJjx/Pn2deZDsHsQDeX/J+4LoKU4qjHxVPTe025Afw7gQ8fXYjy8Lfl38AZ1s6myjXqExU7QQC2BONc0piPQFUUbZ0W6Nco1Bqk4Rs3kLP/mTH4ZTb9wtUR6krbgKZ5DbIrxLJXva3+AmYBDdC6aISxU6SIHBLiW0HR5tGxcMjJP33Kg3TYIZTEtbaZeJJOgOmVjYb4Hclws8SaiGe3ueEIpLMCyyUL1FOp5xJOZ5yFuVUjk/vDZRXE27Dr9GUl4Or8k4Hs6o3VMhdoeIXfJ+xpbcb02zHkaqgQhUFZqVNAxap1tYIvzNJdZBMYw9LJlhA7wXSdVjgoKe8hcFw/BcyuxH+FXs/T2IkHFbeOgijvkL4LyQJ0HxXXQf/I4nPQbu66Wfb/qbxV34ffkfqSB2pI3WkjtSR/lPnEziknGztp1WN48yroQ7+20BP51UJVPQMhXB4FEZBJIyFcRADCTADZsI8WAiLoRbq4HubTTmbB8Egwhuh4EXDBDAqeHMJb1ELnq3278I7HO4+mf/TyRV6Qm8IIymeoxPg1+iEYbiE4Cg2CS7t4AGCScIq4ZVWKHTASYJrop4gTlzyq1Aofi45S+HSHIK9BEdb4XPZWYHeBJHy3H8BUhyw/d8CeQ44+Cvwdgd0QAf8H8F1WmezbG54Ahi/0wgzeIg694aqnNXjWQE7ho/w+4l4vCisFNby/cFd66GNF+6zXhHW5lDPOeoupJGiMlJ3rqqKMeVGwzZcKJKreTsaUCd0yrfeyZerf0qifcZiq5VS5QboAl7U6yuoXd0MwW5qVyEgGNSuoPPlT2FD5vbt9Ld9exN2Zrebmtht7CxHszPsNOUzRNSAA9Gwg5nZOmZhZtyIy3EFbiTel2hPiyXeziSTVi2H+BvUJDTDSPYqJpzCyOacfMkcURzRWJ1P2OmEHUnS3A/gT2ghoRAWGhoyUK/zVTmFhIYagiUPjcpJBfiicLw5ivgYjGP2rJtatWzFx5OuombU5B7sVn5+/lLcHJ607fGl6cNHnB4QfPWdZ3Ln92TfEP1M0tZM9B8gXT09PTSS1lcfEOLpaQhWuOhCHIW27MRhm3exs+zqlLJZMeVJpWUluYWHtmbtemVC6UJzxdNfoctLor/3u5sufOfvf2JAcHrq81t3L51vTvbTH/Tx+bAoZS/fzeNJrxyyggD3EGfUigY1TZBap9aGiComIAth1dUV1imyf3OteKbZkMd24LQToHhDrRRPI3vaZ1vNpQIPDbQXnOS9IPaw7giaFNSIfuxjVj/lRGLssdn7Tp3aN+71GLk6n23p1o3d/Ppb9oOPT+WA/ocyMw/56UmeVKKfrsy/H59/lYfGQRM99ERXEFsY6ny4J2iDPYWc9dnZ6ylj56jXosqruj1UNPsSyqzhMrOymxiN90W9Jj50eOfrb731+s7DwvJiPz37jtU/9Syr/+Yr9rXiG9Mxtxc/4Wwg7hsU7jro156/v14fMpB4e/IZV+ZK5+tHLe6an5UWNmzKzd20aXcuy12z2fb5RbZ59ZZd7Pbt2+x2TsTmtWvS0tas3Sy8l2GxZLy2zpIx0ado1YGzZw+sKvLxPZlac/VqTepJNC5as2YRZbLFapLGQtJ057YIU6zr5q5SUQyEDASDXX9fPbZwJ1EvRWU+QRYIL5rzBWtC18sooprtZ1eiMnGow0repD/eg24Tn8Fu33yFnkqMZLPJvYRtLTbiHtJA2p+QdGQTJ3v0cgdpqKriMSzpGGG4AsiJig85Kz7EQ1nUijrhCLsp+LPkK8Lgj9Zbp66vlrtae4iFjYG4kq0mDzLbauUA0qoHjeJz6pjH0DAPUq1lUuUAU90aG7AGdEVYU2eadeN5to+twHU4Yd0NeXr11CmsjH3KaljZlKlVERGYjTMwEbMfI2kqSK43SK5OoCYOaoed/LX2txbTbmEIerNLrJINp3FFmM4SWTQzyv2almJ37ItB6LWbbWOr2HMsneQleuQT1eQTdo935ArxDeu9Qpl1sHCneSh36NH51lpaM2zpzIRpDnyD2lXliOKKU2dqxwxbN1eubkxj393KT3/HTls2EG5nTptkVdNDV4GuQvq7rME66125uslbutQYKF1q8ga7btJGRTd3RTf71Ptr+cIg6SiAMY1tzMjYyAZheRMiszWxU3I/6wdbLOu27K49d+GyNY+omNkduUbx8p7cx7ldDMrq6o66gNZJ4E9BDDjPrCieP8+JDUPnWxe0Olf2HrNQ0DyE4bjsQzmKFbMr7CtWjBF4L96HEY0fsAv1goC5aOSBxSazLNbMXuKrB1/ddxLnAMfcK07r5fXLpS8ggIebH4WbFGE+PTX3wNLdKy5/wi6wuln1q5KvL9x3xJKRfPkUev0w8zM5572w0FVL4hK8ewTWHKr5on+/s6NGr39ubop39z7H9p78Uk/M+A2zdI0sR94s8hmkpU4l1VtvVlpv0uQ1VsuB3L7JJF8fKZk82r9t9IeEqXUhPPCUJUDbdkX2FEovFqye92pJcfGwI+sLKq1NKOzZNu1QTEJp7PcNgsGUPN1cc7B3lHV1vsl4fOfRY24rN/Ttmx8Q0Mz5HSZ+OSoNzQTtMNgSxcQSOW2+7RHPAB584pU9W7bs4dn6Uvj+5NM22+nk/eElJUK/yrq6SsrC+HgjO8LuEBwxxucRUbL3AlutWEf69Ghrb4Mj1nwdsSbWjd0efeDkyQPR28eOyX3Wyv6CfVD15E4ppCAwsPbMmdrAwHw/PxyKXdENw3VcbqIrxRILV0Vu8lu7eey7tSe2WRLFncXF4ftTKm22ypT91jJSIC+PlBAPCVN+up4Xb8SR2IlgpJF5OBRpob+S5NbAfVxyrWer0D4Ob3VStHGSVjYXuZz586yy6XFnZ7NbrAx7N19Gp2Ihd31GSVdhSmxp2cCBhQ8G4SB0RnccwS68u+1gYZbCg02UYolHF2X3bWN7L1ehjS+2VcwrxCDuzN36cm7uy1tzixlrNBaMG5c1/s2Dg4tS3m9ufj+laHCx8HD5+fPlZefPf8Mus2s9ex0IevDo25PjplOwiChh+PS4fM79OPFcrtLY11daJ5T19XgxJWla0w6V5hrNHi3EUjxJqMS6Tm0XUcFUPE+KL05J2VpQUjL8wOLjJ4Uc6zNCVnZWaY7VIk0rTIivd9hxsaKjV/vdrN1pyvxywd6taQUFaQ3oxm42fMvqUS1erKuoqLtaXnYtk5Wz6+wGmXYwWVCDg+ySiZFEl6+w+rvE8hIjvR8PytxTUhJ++AX3vveLB93UlaXWIhLKFCfLNDqMDPCdnGXXiwcjSUXaU3SRHxnUuBST2QtPmI8erd5pschZ7J1U644Xx2ZkfyRMS8Wh3HqFpNckxTLk5u7kf3a9Wh1Rj4XcNvuKi0fsX3y8HD/Aw8JuqzE7uzRHSG7aUWCKaxDzaNMySzfF8SpT60l0Qxk7/KrKxNZTn44tFvg3JJJSyxcoTrbNAiXEhIUuW9L3qUDfyH4PDQnsM3Rm/6cnu7isVXfr37fXUw+DzWZfTVRhbnoYCeCqErLG89YFbDGPSWodTa1OsIJ/dePtfK5UJmofz7FhiZlH8CG5pxipClPiIMDu8zq7mb3sQWGw69s82FN7j95P+KNgmqx/xL9dTY4N07g/Pt6Sdr+2pUB6OUEsv82RaO/B/sr9Di8jeGJ/R1mATjjaURbbtEttyjJ0x7GOsgo0aIIRMA/mw3JYCDNhBiTCIvChCIuD3vQOhv4EBipNJwwfGE44i8BMeSEkgBGSIIhaH4e5hN+XSo/CHAIfskgLLbNSS6B3Ao1ZQs94wnT+DVxDW7nGEKclxGsWjZlL2FwOI435fRxHUmkWjZsIiwkjjnCNCrUEZYRR0chHudvyIckWE+85VIujWjzxTSIM3nc3nQkKFTNJNI9gNrVyrmblLm2uoktfsl9Yu1EtYxzfk22f8m/hf/tTMP/aTb4mtnxZ/swyL7Xtt3HlzXtcWke4ETa/9etGuwiSH/akpx8Bgp4sjNCHAGEAAZJkA+lJv5LoORIi6BlJgBBFgDCO7IjwJAHCUzCJnrkECH8iQHiTABXezvAFXIVoGOICThcUIdbQSjiNzkrVjlvJaXfdUjrq/P8TlPKT//jiD7sS3SW/4YYw1o6r2LSl3IZGu/bYNvWFP5eFQQBN3M5DWoc+QFo6t/zXAcBfAX235FEKZW5kc3RyZWFtCmVuZG9iagoxNyAwIG9iago8PAovVHlwZSAvWE9iamVjdAovU3VidHlwZSAvSW1hZ2UKL1dpZHRoIDU5NQovSGVpZ2h0IDg0MgovQml0c1BlckNvbXBvbmVudCA4Ci9GaWx0ZXIgL0ZsYXRlRGVjb2RlCi9Db2xvclNwYWNlIC9EZXZpY2VSR0IKL1NNYXNrIDE4IDAgUgovTGVuZ3RoIDE0NzkKPj4Kc3RyZWFtCnic7cExAQAAAMKg9U9tDB+gAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAPgY8EQAAQplbmRzdHJlYW0KZW5kb2JqCjE4IDAgb2JqCjw8Ci9UeXBlIC9YT2JqZWN0Ci9TdWJ0eXBlIC9JbWFnZQovV2lkdGggNTk1Ci9IZWlnaHQgODQyCi9CaXRzUGVyQ29tcG9uZW50IDgKL0ZpbHRlciAvRmxhdGVEZWNvZGUKL0NvbG9yU3BhY2UgL0RldmljZUdyYXkKL0RlY29kZSBbIDEgMCBdCi9MZW5ndGggMTkyNzUKPj4Kc3RyZWFtCnic7Z3/YaM8D8cZgQ3KBs0GYYNkg3QDbgO6Ae8GPBswAiMwAiMwQt5YtkGyZUjv2ubX9/PHXQIG3FhIsizb5zMAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAPDPTEPXtl0/3boe4Dnoq13mKD76W9cGPDxtmQmK9tY1Ao/GOLEvQyBQJFT9jWoGHouLu9RUH7siy7rlYOOk6P3UtG1T7d3Xz5vVEjwAY9/WH8ciX7RQO5/7tFqpnvyBqS3o0McNKgrunskppYjalyCJyht5mRUqyBRYMErJ/D8p0pRlb++n1hUkiSrG8PqRZOrPL9YY3DnGxE3+w8Lu4i4NIys36hJ1kcWdOdP9QlXBY/B2kYfBfDCS8bY/1W1Xa6asSEjURabMqXz60VqCO+TzY7cbleMHr2L6WSm1l0OHoJg5lvX6rQfhcoEnZhq7i6fU2C9GCe2muNDpcryRh4yIFEGxYs0Jr6GmnpxxaJvquHPO0cEeNKKTlXFhIw5VcL2REHmoN1ePqQdOOdTUU2KVUhkGAnb2bJXpPbNWUT+Zd9lnTuuRgloXV/DY9GoUYNY3LvIdRbr7Repm3iKVVKQ9KcMUCyF4TNqLUvKfx1CU3g6m++bH6Dp3uAluMSqOUxlGBRRTGF/R/t3fAO6JUXg4Tmbe3k9VEFMyDF7UuuCEORYcOoUCYlTZfq0mVeyRgUfkJHr2xly1InGAQ7bJuNH5IE/EVo5co5ofaNZdKT3uAO6UsW+b1CnSOq3/ulv3d4w4kfULApbKZZHLHslYiOaRgTul1HxqCymppakjcyWhMHkby5RyWRfauU2R0jwycD/0xyKflcRJ86kJ54/PJav1drdhciMcMuSpXBYJCETqwRFWhGQg+08pZpXU4sJsODwuTE7xqSM7rlw2hS67FrxKVxnckounNMYH+Svf2ojAoJbKeMlu3UX2YfKjuYiFPLXL8sBl77YkJjKV4EYk3B+uJFw8KU4CME7WjseLtKE5htc0Nhllcc+0y0yRgX3fjEspwzrgh5nGUenfV7qfxPv1szIKrqZgeW/UiT8xrbf7bJts0tz8WO2yQyjq+XpvkuRb+UPADzE2x8KarzIwcwn3h/fr52zLII2goEvnbCcDly+lFrM2GvOMS4hyWSTqp3UtRHI/pM+Db6UvM87HyM4lIoTCHpoWJ/9HyB65WOOS7WR4W2/XxZwOOXfPlFhnE0qQMb8r6Svtus0F30kgUOQaT/PZhPsj+vXk1xyl/zPnL4lsJyFfMUx0RHhKuSwS9Y30lWL1LPhOPp0Y5YfT6bTPnVs0+tMJt1fYQ/JrQp/aKSnpFgfZdD5typ/n5pRCE849U/oIRtRlD4+y7MazTpPFig78HRefe/X8hxWh2pfqT4FM6e6P6Ndbv8b61HN4yikpGTCy8hWlTfnzQnRYyFPprcWiTmoqkRJFvhnmXf0zzOduhkQZkqi8FZcVQqYUP+Yc2EPn14zc//FKSoYYzdE8jwytPy/D5KdZ2rQ4ZhaJehOa3hmazqDPdADXE6w2sWu1QmT19pM8OFFb+vddd39Ev977NZSdYm0PNWJtPomoaB9Jk7ni7eROy+6lNaUm5KnFMRVRLxMyZW/UKn8/uJ6+iFpOWcGEWvgUX21kyveeErHOnCmJ2a9ZfOrPRS2YY/6qkVeI0qa6YVpuGoTJSS6NjGjjc2Us6m4O6BSUHOhwHf8N4HqmP14BvDOfO07rLpS3n64v8nlZgUTUmYcDFr/G+z9jsTSiUCckSiaXsx/PMWH30rtn0YjeWRd1Z7PF4ekzg0T9M+POylM9+AONVVrBNLk2S3kYLOMyMR4r7GE2qywa8v04/2GyYSrT+5K6Z+aJwuQUnrpcrVymph5YmboIlSs89VUOidrErFxSfXx81N2QKKC8q26xCSlAhW7TJInhVhEOYC1+JJnK2J2FOhHyFcPNKUGmOad3ZJBFdVEfj14/l8elTxmuvAGIZTmlhUIEuj2ko45TcHQss8DM9dk1AWXNjzkH9rBcVJZ1hfk1ohuX8Mw8cXSdunFFGV+WyixoxS9E7Mf0E1+ZXfRLEbFQfaYUPXXk/sjvWjmJ5secAyXBBcXZnkUCRDeuWn+m0r2s/V/ayOMJUV+WlPIa6tCnn/fanHSRinrN1Kmq0rfo569FpBJUdPdHhJuEX2OHfJfWFt24xCg0r2ETHKv8yyMPJ0TdVq6yXZL8vWqn9NNeHffLup73ePGoToX2Wxept9d1ymc5iHzhBDtV8oSSkH7NIJSU7MYFYYIQtXtZ2j8zvCxXRZ3VcO0kONv3+zDKY8qqgabNkr90zxvbfNlf8eCE+8OVRODXtOKbEN3EKDS7MlZizj3bSsIDX0V/v8l75Q5SuWpZzFkfFk9EByIqxRid4yQ83uK16NUZdTK5zxuqUZjTGeuebSbhgS+SeL9t5KbzX8c1JeXU1GA/q4EdhUb3zbiSiPyann8R3TguXzEJn9u6Z8FlvQi8g6+Ter9tstrkvrXqa75QLirnWpHyI3gBwh6u+jWiGxeHCQQJn3tYf1PA35F6v8n21e6L1mUKC5fLx+qK5w66lAp7uOrXCOFTR6EvfY3efkpF17tLn2S6orLgKyTf75KpKdO2/cpNluG4q30pdglHSOSqXyO6cVzmefS2uq7+4DtR328DOUiN/bzuqpy5idIyRlQUP+YcSGTChVdKGvn6iBbDnwtsRNfBt5K2aawfl/BFFhYTldA+MboxEkHLVSMqunFtpuMK9PEaQeDHUMOARLNYvk2RKhfLkq97yjO6VRNDKwkX3iK6cX0sTSZ6630p8JukfR/qw/f08Ssidciu6/JVqiwX3A4nXHgHr9Q4S1L+ftAWLgO/hx4GJN5mm6j7PQwmUqz3t/ngaIZcL560bkSF5XSL4ScXLgO/R3Lonc+0TXXCZ1iXiqaU9IlyLZt2nCvqrJA6c1WUF/8N3Bdpo1bNrszmKAVv+9OKmiqYGNVZJHt/Mim7q6LcQSndKelmMyZsT590v2ehz4Ix3EQnsuVSZLdgaZez00cWPKfMsO/PA7KLdIWnnUVKiIzCos/8N3WCLg3U7uevtpv2Mdhv06exhHKhFsSTHpJ0sy0iteofncN08+SUyWNg11w0qTh+fLjppsHUiOb9VK08FtwnIhIkqBedUq1249pAVEj9RDJl7Zp4VFdkktP0xdqDO0TEqwXMnPWxK80owluQ5x1MIOl3WRyvGE9coPbJJ4BHQk/CM5RMqZShm8P4DJTU2c8WKJaIgVsbKN7FbHT7med7mLhnIZlkO3LNRF900zeE/TRD4xRP+VHXdVXmq3Zt3FoIBjwUySRb8pAm/41kRDOQlKwXKzA/S4qBqZSvQp7pIepCWkSyXOUYlurM5WrIIJhNuayHAJ6dRBIeKalu+W4XPAkmsLuVN+TBmf707uTp7dBM31Nb8ADoSXhkuIroiBGqyR9xq03Itckk09D3PSYIvBh6Et4uiyRt8j3+sqrNapjO5y6GX6nmXTHeugL3jZaEN5VaN05bbCKrpt+o5D3xWeTYfHYVJQnPrnYXB5HOYx0I1QtGJymeMty6FndNlITnwpKJhU3bQ+77cPuX9LlPsUsAJDwJbxzayumhcPlWxtR3baeuYfgsdBdXcdJP2Zzk5jdr83jQWyeXDH/JsKRZOL2zH00vODFMbvso1W9V6jF5i31udR28Z8Xv5pAtHkCVxQ6mxc3FwQL6q+wCedq/Rpw72s0hWzwAO0SpLaBv/UzsFLrOnGBCC5f1063r8xtMclbygj3tkgOb6Do/B3V7NdKXpqYlw19rbsAUyVJuF063pwd3sA+vMzrtYxE9AGZmJRXv5nBeppqGWyvb/NXNOWjgyZiGrm3bflgtZBzID303B8PsW8kCpKSwEMxr0X+Wsyk7riz8uzE10Sgi6vaJTDCXZI+JOy9EuFdpnoyGrC405GYQ1mHfziqprWXWwfMwBgJFWqbRy64uNOSnogXhqc/MZhumZ4CA56JzLvf7qbn4UvWhsF/1kZXVhYbmJUdJRn14at5oKz0DBDwVn9bUsThttP0tY32hIZ+eYVNZm+UBdK/kDBDwMNCQyceuuFBWy0wugZWoIPBv92HUZGpjtT6jiPbnM99amQILrfmUnAEC7p8pHjK5ULZxSTvDuY9ucApdbI85PiUfPKdnLFsrnxbdlK9eC+6a2N+2tqwLytlU+VG5A7nY0c6m12wLaSPkfjb+oqQ2l1kH98I0xcdElsTb2/I1GNI9ZYmpX25xjz46bDzvLl2ZfJY4GkIuJqak0sswgzviY5drGUqm4cXym0O7d9ZvYsVG5kWHkIsd33ojXrnLxB4m2Y4pqc2tBcAdYIdx++i41vBubY4yKJbsg+lrhLgwAbvtpQ/wcazcNx5dr7y55ddWZ3DXdJGUWKKGJ9pcOkijLo8eo+qO0T0yG680aVNsK969Oy2i62UmJV6ZAQJ+H9N0bZvKxqqCRvMkGs/27XteaiVQRIv4hQ82Qpwfo7QpfxsRXbfhqb24IZLwboa1J0vTaRGAWQ9EaqrL9B0jB+szs6ublTrkijs9Zio+3iSj6yTCo7gWsc7b0BdKq8XRIwoW7EtFTSUbj/phjftiRGZYqUal+D5BEl6YNhVE18dcKEtzxcrzwHcyus2BBvtNVwVRUrexJHWvqKkp2Xjl0uab0Wx1QI/0psvlHOO/I7hnL4JYSML7efiOZURnj8/2hJqubdxm3P8Fl9ekoDQ1lacaj/XjNl0bVdftlKcxzO0n9n0IrxUHwPcxxjuWZcwmmde5Fmm4jSkbRiVLaj9NTaUbL5+tmbluv1ZJVdddkYQ3pk4iCe8HOUXCZJVSa08rqoBGzQLJya2aKeOWSjd8NeumTZFSfZ9rkvBSJzeuBdcwjaM6haYWokQ7lvG5Ntrr3IU2hWSicv8HBirdeP18m78TqauS8BIgCe8f6T/dWlL5Mcosab2npO9YpubUlqGYNF4jxGoq3fBkzQbzaTt/SROp65LwdDauBeu0pVBEQTb3hmusvs5N2CAH77fEamql8d6ya/OXBq3AdUl46RsiMPWXKJElEQLYiPp1mkREDZLP3yM1tdLw5axH8my9T68GTK9MwlPZuBas8Mf724fT6bS35k9u9KLZlAX1dQ61ypCJbSDkCqHpxjvNInXY8JYrVeNELp1g/V3JV68FSez6itm+Gd0BJZt7Peqn26RADFsmEZGaSjf8IlLGkq7tVFpkWu9tu+bpdwWxzr9kR/LT80OjPTaJMkP6FtrrHKouIxv+IdEIcLrxDrNIbWQi9LpYlqqgiZrrD7bPztMPBCnI6kWbdFDSwJJYshH10ySiDdyUgmuyIrhfuuEXX0pPXxFVVDztRM395iOr78qAhbf/BooP1PHxk1BTG1G/gyIRpbxkFBIWqqm0yObLrdnoTEyXOCnDBMuQ0sdSc/3B4C+hhA7t1Z8KvjL1RtRPkQhKIhiX76bJq+VroKaS8SGydoP7UkprHFRXj0NQmMAuXCaGlPb2NCLk385nlphzch569uWKiGEljpDS4EJYSSUSqKlkfKjlnj+pKd1DPwYSLCrCJGnGPbyrmsSUQfCXhE5Ngo2oXygRdtcZIaq7wHmWD07Gh8os3FD5onPiYh8J853IvHnbn9TC4N+Jul4J9MDR6DOCjUTYUCUleZfUbmIlsCkLgpm1eHIqPkQC0S7fy0hUqZSR1+yk1nxikiRm4YCf4WrvNGdKhqVNDfYISdy8YK+zLAO/vhd67CJ4jRCWVHxoF4jaRMKTi9C+29Vd2WbC19wopRdbU/J25AkPJMKECfo+Spvq7FmuChzBrjMVCdAY3GGRFr0in4GS8jKVFR+9++424krvwQ2l9KtsDAczDppLsnSW3sIToRNdZqqXXPvzRlKG8KH/SbGz1P7aXVkuKyk04bXgNqjjvSqnWByMORncaas7XKZwpbSxLpHLLCnNApNtjHXXUES32Q9hIXAjVtOFrNM0LCWdFGg+rpG4ao41G5Ukw469kCM3u6BgTz9FUjgeqXCr1MtPb/cC1StlwG2odZPBXZ7WHqKuYdrHlRFDyhIWMUmSyHDKU8vUlNFIFbvAu0itXvGxObxb+a5WVn8Fv08c9e74BJhsUSNLmEAliK6TUuIx+TJUW0S+3H+ObFF30u9VikHbhyM2fG3opjhB2UjCC6ProTtlRGRSH+/UFMVSw1k4qa3NwP2SGEjxLpNRYnt7fD2xKI6u70z5gZ9WdNy0qCklyA0X6RGJh9ZGHhbk2QPr6WhRdF26U6Gn5GFqSopTfnjJvUqfgI2hu5Epl132tSS8hlnN5IJyTE3ZyJbtDCI6+biQOZuSp3umpb6chMfdqSKl4hY1VVcYMnkKylVB4TlOX07CowwmO3ScVoaTmRo4XVtb8AAYLZGeInBicpJyh1jRVh4aZndqI9sKPBPU0RpTZ7m9uiIJrw6OkTtl8tfj0Dh4Xsqoz7cgJiQk4gC8bHSfo3OnDpde5Phv9QQPw9oUgYIbMyUJz25qPtFnNS1zotHA76koeBiMmtKTzz+lUz13DoNNzQc6uxFdBy8ExSS1jEgjUdzjNmGCWiZuEh2dnUy8/Reqe3PGW1fgASAnOtZTJFEVO1BmOo09/eQxpUU1t7euygNAiSdFK44NJEAiPyVMwqNUlacPdIerb2Nz2quw6XVMqPpjFqsul4Tn8+em363j7zNUYZ6PBeviXYNP2Syruq6r0r2S+0kU6mT+3NPTaFb+oprbW1fsMVCWLMubW1fqxvDMseTC6SBNK4UqD/Z6fVIoI9pQd1N4zsR2s/cXU83fS3fyUvV2evKR3GhLALL6rSykT7AGX2PqL7zAOxllQ1uCXq85NN2kfuDeGcUiNGdn01ShGlmp9TxW8IKwRaWCjr9LdHc50eNF5Bo3m5ov5FBm2NsYEDSaLT2lMIXCHBuCq2woly03s5HHCl6CcRnNlgYtKKfaNLtJ6bKX0sZUbPC02BSbHSkibX0ymnAfXJOwaaSo5iRXNQUMPC9Bio2bZMhEaW1RqZRNM6I255+qKWDg+ZisUsojbTSas8ai7bdHs6uETbNTMCb7BSlgz41RSp35oA69mSGTwZzdxX63RtKm9UxNbUywBg/OPJuik6IUpNhc2UtLr6tVMm8qj534aeiwAPGTMM+mGJxSOpzqPFZJG7MNPWmb1meLHDGVpyyPBB6EqW0+WuX4POI2LeO4ysp5waJEyadkyfG7fBFKc/8/8WBgc8WfAW6NGccd6ROFATqliDk+yUPK9MBrJ6EqNo3d1Allpbtt1RX3B7eC25OOjpBPLFZMdyjRSWUC9Ma6IeJuykPcTYvlY9AHMGlTo3oduClqckljz9EKLsossDLWXkq/7dqMFMVmOvqlnzcnLIQrQoL7opEr3YX2ZJfpMqUtupDFo3d5bB810lPq2ZR+UnlPP2HjMZkuSqn1X+pImOzW7qM97VICopmFyoib1m+7MiNlZdGQLOPTXZGEd5+IoY0l/83Yk2jIxPvEYb9Ni04uNmomtTjaFXdjN+2Xj5NeCvwmUzSuJtSJka8iPWQy+8R/5HFtxE1RSbF9pMFAeWh10RAmUkjCuy18G8VcJnKLoY2NoTNaLoYcKrH3kHrZLouWCKlnizbywcBQI6UrMS2+FJLwboU+jisSuXP2um8MnZH+sKlLDT+uXaa47EYiyzpKm4o0UrISA7N2SML7VabJfzqE7raDaZldxsJAXL5irE9sZarnJ5TLlISCTq9LpJGSNq3NFp8cSXi/x3hRSpX/IhdLyN8P+7392MzlRRhIyFeM1RK0KqMIeSqXKcMvYRKejU52Y/iUXSix/K85uM9Iwvs9Tvy3tg61yHgbKVIwb2MlR3PTYUbC6Q/qGPLwlHKZklAwOVHaWgQkZdNo2Wx/Akl4v8Yo3BN1XI20TO2/iTDQRrZAmVmfmCSVrR2jXKYNvxiJbLcXAUkl4ZEkj+4LkvC+lfHSfWsS507CPdE75HVS6lbCjP7mrb8DC3kql2kJBRtmld9NsWmU1jkfX0lYAF9niPzjmd7aFv9Vf5cn6xMtN1vXaguLT0ySO7evdlmeqekJbfruHsVmGv5wJRV3CXygZNh+wKszKYfIGxq10qUVqfkcl68F3qcSQxsrYUYD84npQT7kqV2mJBRsmFVeifg9+BRCvKg8F+MqvNPfbj/glZlMdLKOj+ehf+zxIyq9P6B3yEtehKusjaEz5hOTGfLBCO0yZfhlw6x6VJv2qXUJSmVqYLP9gFemT6ijtyzwjz3+F279gZ1qIndc0ITUcfkibNqUO8/tqA1P/Ze47J+T8OTdpiP9EkNwf4WXX3trAztOG7uqLoIZbQdCSsr8+rU/orovUqmUXJ14+QrSptx5OXqTL/pQUYbL8MvMhlmdCW3m9EmPysUfMg84WtamBoKF0v5cY3jcv6GhsBkJ+BAdJrVD/ikuFVJnnlgeo7Qpfz7ntWE6VIilRYlFbpjVGWYzL55S5X6FwPG2Nl7dIBykSUjOktckh29t4EZ0mLQOeS/FVAxtJMxJ5U7vhP5YQp6KMuwVlWTKTyt/L6vERxuMBu5HWWiEUvoLTKtUQjE4TFse6fdu+GFSUrLDpHTImzwTJkmokzoThOYkCJNTaePSKSNuWvxC7yxEBJUggeq3LwPbGBXT14qeMYLiUgI6WfzSYqLDJDvkxowYgRKJmWJoY8OchGGAyt1MsXJa/KLMrk7CE4Jd99sXgWswLTBNipqyGiAYviURq8+yw0TyZaKAcopCE93MQfI1nVNEYYBjRsKkRScVlRTax0t3khbDr2SxfpYlmquQrg74Kjl5I4qacj0v+unnWM2n/yI6THlsRMRVX0/CO4ia7MzVn9pl5kwvDzn7GM3CCd14rDv9QwxWJWhqymkAMnUuPEV9+sZ8EkHGN12kuKLi9xfypVdJ+tzW/P7J4r6c4rIbiSyUWTjXRBbAN9A40VDU1M4ponppkNOsKESQ8TC3m1/+cmjtsf/CmxGK/DKUMMA4K5vgMiV+0anCnb+dkg8E38rBNZOipmYNcPJ2wzS2UwoiyGgKlKGrTWIwR+VFN07IV4x5yiQPDV7rBJcp8YtRiBJmdf46hVc7sZpael6laZxPrqTiqEAV3ZpkypcR3bggTBCihQF8By24THHZJ6uUzNRAeEo3YJybJFZTS8/LDt82TEnJIKPWvXdlfGan6MaFYYKAMlPCAG5sJLhMxi9cbRCdvCXt0kqRmmI9L+vL7Fj7ie6XFsQ2lIsIim5cFCaQKD732ccmg8tEfAzcA6b1evsxUlO85zX7Mp0/a774z6moQLXIgOjGRWECiRIm93WNlKHpDaTvBH6fHROMUE2JnpeLDO7ns8Lh4fLFYAZR3CwOE6QuiyqLUMCdM3IpITU1sLOi52V9mXE+ucs2k/BIDv3t+c2UMAFVwPlAYvSGn3/fn5rEXwLuhE54J8ZO8fQoKSiBEhMOj5CvBW7gIq02zcWWqea2wEZ0HdwzlehbUY+uX84GPa9KaCIRZNQdajrsy4ibkXxFi+GLlfD+7g/6AbqmGm9dhwdiJ7SFDVnKry0rXXIHRwQZlSD22fUTO+1mZabjCphZnX/193wfU/PhlsQqsdTGF5gCfzdQU2HPaxrZFxFkVILYZxEZvSIJz0Qn++geN+I/41dm5XimYHB/49o8EH0oCVJNpXpehAgyKkHs8/SRcSmKwu2eranmt8AP6hT9+CfDsmVfoBaWbRq6SqipVM/Lls6SSXh0+pN8pOWguFl755uam1frNA+GY6WN6zEuzTDxlaIzrqbWe155FiThuYvs3dxbPs7Fxc3GOx/H3dGYgst/0OYyggT0g8VeTe9Or/e8TK9t8F+MfMXrTvPZAZNRSj/xR/wEb26S8UVb5ejvfYFecZKFmjKCMqauNnah81/elNsEG5o/Em/522g/TVtFp66t66brf7Q+D0PDBcDNLhi4mtplK3lNxt9o/JdDIE75e9WnLnwApivL9dWilkts2+DkIJzyxDt9q3lNURIe3e2VMt7aMniRPsZbV+nWGLs2hQd5bGo1r0lEBRqT8XZfgYCfZgwFyvC5fd0zk8gHYGpqNa/JeGKHn6nZI0CTXzOz7W3b9X1zchaQoqMvSyKSydTUal7T9PRKaTSj2ZN+7tP2QJrldG+N/0uHHESXLThu1dRGXtOzQzJSq6dIosI1gWwc65VlyvwAo3K8n9VUIq/pVSAJWZZFZrQJ2aHRh9d9CdOx8XJWU8+dhjuNfd9PydNuoK9WzhQpbUSDl3+UEy9B2lHqD7dPLvlppmYeNPro9CKdC7FN0ZlT2r6dWIf55RChyhejlwGA4n9aIWPF9pqaIs+g1e9M89OilQNfhN3Lvk7TnyieVPRxsZ2ZLK2pqXKtI7x4oi/HZJJLbl2Jm9A7i5dffoD6tE8FKScSHJ7r7CAfa0ze3gjc8ZurDG6PSbEZ9VP/WXmaxyCntlBlqifHoI/VlAkA79OPVq4Ajw9ZHz1zzkpUNfFjtSZTlTVgZaSmyrQnReQva/meGSsjo3KGVsiKPCc7mVoeNZJz1pROvmr3xBxr8DTYDp3W8UpElEimWnHIm7dQTZkhhdX47+owFrhD+uajLIpdWa2sr+lc7j468ZnSXk24QHXvdU2opvgUapWNma1u+uKULgF+k9HuoeD46PVSptXV+BCFvRv1miH4bpzwjj4Famp1kodBTPRgz5Z7QIfPAzchDijpSW8kDpqX3K4rEE45q7NATa1ORSOyLErZH4qw5t111QA/yn+zhsrf/Ee554vDiMNUK2qq2OisMfJF+KSa0uYsSjSRCgTq7b2/rhrgJ/m0rbFvKA956l3Wm5JImZt0gClWU/F0wyQDExypprYzfhSRmvyrcMeTF5+M4eJmlGV5rOO90j1WonhAaVTjSbbRP2wkQaopfZ69SpMFSzjU81N1V0k+PhLcF0rJvwekz122aiGSqHAHWOui9EFR51nHaiqVdKhgis4Pk2oqz9bjUpv+O/hhxmPouWoTACnThO9K4y4uFJVwcG0eqalddnVPqxCqSKgp86VZudQMC1bXPQX8BH5agBSqMSxWqBJFCmQ/xGVJyiI1lcdOToJBahqhpprIoMZV7a57DPh+7PIuxuem9MrJz7XMO1nuU5UzQ92ER8bZsw7VlOI3J2gzGTLnaopPS1Potnwt8E+YUPGwcnpHAlRP7JhLDPhPFCyy67c9b2fDFKqp60XqFEiNUFNGvtLpK+Ys1nr5OVYnl7pt0XZjcNR25Dp25AshSiEOgZq6XqSMqE/8AFdTq1l2NNNhvLau4MusTi61vbjTFB2nyDffFL78gpLiC28Haiq/trWNbbOxJz6MItSUsjU9lS+gpP6Zqas/Pspj1fTKydVReXrbT9oZCjYv6oUChdO19eGetVRTRtiGa+5h/KEyWttIqimts2AtOX8ZwFeZPsvlF8/juSaroeYi/bIb7bZYzM3Bf07HFaNUU1fP4KgylVlN1QmZsr7hVY8AKpOIURrCkNJaqHnV6zhmQbe9urZSRhy6+ZtQU1dHz3ehLL0dTrssiE3FXVAbeb26piBiGcZlBLkB5tCkX16sNfCyP+nZSkm7WhW2t1UpnijUVL8i4JzJ/zF8bSPR6XNd1c+RX/VJx05XPABcfs+PY/RO/rE/+74yq1NNQ3uyEiYHTd6SmmhYU1JSvSQHUpYNjOeHGnHgplaoKS5fKxjp2UWjuyVXU9PRqq8PN1156j7sn19t3x6cXT9mkMc+rFLq2SEbUsr5oTIlDaR6DulHTkziykgSRrliLVNifaD7hJqqsnTgeyo+fJ6oHvoI8qZq/+iiLOfEunDlDZDiU7QaQToqnBcwkV+bD8uRU9JmlRvWrFzaNdZSkf/c+DN1eFuuptYiSu1iFWMRng/Xy9dxF1YiTDZ+dcahbVOnCtFqBhIypc9DXTVmI+sstZ6OKRhfL+/k1E0slw1rx7cdtzflok/Zetk9O5voZBbL88wVSolosky35/KUP/TypD+BabfEmiMn+skqdmRMSJTrx12xw8PmRBNyaOzHKpLLbl6vdgyeYW7bRutl+wqR16/+lfSOjPOT91qZMqrH2J72OfUIq5U1YF4VsiXqWpOjbRYuGUWWXLuEfIzWf0smD23Gmlj8IZbLiW9fzN2nPjJGlp7XTvkrG/YXJmMWkZoCY1t9lGWpB7qtLflPOWOVFO9HrYaUyLjMj8wSo3Pb4cvF/PSpm1h4cJNbRGeP3ndcb5aqTAl7bYp06pOKiz7Sz7wkblcX9zvH85U6+TovOCXFG3WXMmdz+dY/dREMyVdEKt4dXtAwe3SY/8Rl9W3R6dNWP7Qzb+ZxlPTTpmm1xq/FeArf3qKTJQYnbGN4qbmyEJKxEVI6ZVfs8PAVkVKcmPB5HXtctHGWiE25nWGWd6q3YwBzP3V1EAl41NxJGej2IePQRbJKR4QsTRMd0g8jf2ZyX4xCG5RCSYs4w0SqWS1cLI/TxUGO9PnOf15+1Jceoftllgjtl4Z/XoJLZyf8UV2oN9s3ZgIKC3SPvJSXuqAjR0pKLnBmlEa7UgV+/pAqy+VOY2BiRDLRJQq2TN8lOpgyIeFcxy8Ym3nTP/3q218lj5pKyZ10iyrxoCSNnZB5FPFlFx0UoaEsW887qlnD6pFo97h+5SZcUuiOiXiSyPhMDN2E6Z3jSQrVfq0iL8WkHXyLLA1JVJg7aZ0r7jlRc9BRHrgpbcvy0NBmSKlj5idpRqoN+3LIwiQVPWr2yY1ikRB24d7RDdtD4ezfga2H/9p8FLn660Uv6h/zw53ighSiYa8+KSKr0ZZOtg8XsFj219YuMTc4aIX6DcGUiqWR1Vr4L2NKKumgjZmiE6ehb9fc/pdjl3AvToGlIaGotDvUUiPVVI6WxF1uUDhR6jI5oXu/WjdzC/cx2X8ixdMmb9EG0lHqMkUSNVeG11Jy0s9cLthV7ZSsxWsRD3xZ6kCCilSbuoB5778519Z2svvlGOlC7ix/SaRYEFx5eso/irOpbLX+yPI2oLT0MsLXiV3e8Xj7DL1VWaEOGrwe8cCXJej0rAa6d9zF8B4QrQjnnKy5YScmGV8SqXTPbgzdNs5nVG0Xo2yXI1NTSIn6+sLbfV3vhVZ+aRL9ZT7caigSkjeXXeLKXhG1c0MxecwXyfhSSGklCU8qSQEFU4Nquxhlfmz6cRy7xkWUmERxub8ec1/M5TSk/AbZ4F0WBy8ZJVNTy9iJHfGahPVhHckpqXgc3EqujJiR26ZOJ7FLHYSPiEcALvDdzca/Wx2lWdHjL0VSV3AVQd7FSgY/dbsm92XRJ+RilDZobY+IjuSXQkopn889PVqN5eynBYzKjYtAoL4loHTKsM4hkdTywtIUG62fs/O75aclfXDkRpN7vqc1Y3oO1i6pVwqTOoz6cXb0qNEuOPcsSJmferXM9Zw++mn83LTjLwPzbgQ7JiWLMUtQBVLTuut2rtlmo8k7ku2GzyLkOOXzzXcNpmp19tF14gqzpHB9Op3qtbUWrmVWes2/3+sZiMPkFm5pNjtnvMH52Mnkfu1WK6isWRjeU3pz6So0TnI/OuNzD42bZ6Iuwfn9eJGqf+Vp909iPEsonmTs2sMjkWLsxPXZ54KiIxmNbwgKoZc2+odj6B6RizSu1fn7GNv929v7zXPGzdyx5sZ1IFJxPT52smp1DOmxk2DDAiEZ/ZqxIMUzzl9V2zuxz5HPra2C94zYRfXd3LG78ObCMLmHRxeuEinvFgVjJ538O4VkGHEWaQzyjuKZ+SJhtA6KmWlwEJe0+0We8ufPCph/BcGta2VIiQuPCn1JpMKxk0Z0/kVHkrwpNd4V7/u7MxotmMoZvpNTV1cXn7v6Dp/7zuETWjnjrSt2jsLk53k+N5OMLioTIKKS5i+b2MmGlzS37edvXabLlBghtByU3++Fo9Vv0W9hZ49Nt67YmXs3bg4kF/9pKbM5W27vv6THTs5RyJK6/1HHzIaUanGsigTqbX9a/9OeAbf9UBFatB37Fdx8i/vB1Cu2yZbBlck3VKqRjIP/UmYra+GGw9Q2pFT27JDbhboW1y3zoJbJnM9MsP1Q9PPTeMa9/gqRCvVNxyTDNHKzco+S656VsRNlcSYrU1lRmSVOLu+kWww4elx7j6/jD9BbpZR8ux3VRovclJ2s+qwEeHTBCEI6gmS7Z4P/tjZ2ogxT+32nBcqQ3VNDSmk0n3bKr6FsQBS9mveEG5iPlACPLpDM9MlbfGbcfV/tHwpH3jLVkYIU600/MbOnRLTmkOiG2A2INNW8GX2+JUaF2hdEIiSjXFNT1D9r56+rYyfqMPUo4pT7558YYJRS0BPyNqGySum04S8qr+b9kFKhIrpAge4ucYc/mYgErI+dmJ9xig8PbXXY7y/v5MrGsA/PNJh/1cGjzNsEMZ6VZrMTfkti78YiJcOoqcSyyeG4ynreQmqY+vkxSok+RLLEF/PcDCs7Eq/mXZBUoUIy7Db2o1Is3ibKFNVKEqlh6udnjtf5Pnb+Zn664yhKBeNZ23e7Q65LwosWpvNQ7qTUX7s1RdQ9/yaFY99ph83P0psPp1kpKSppI+Vi5q5fzZQKnX8CC/mN0fC+jUB24pj5a8NyL8RbpoeMlHidNtKVXWfRVqN/t+aaJDz/PVj8t9/RsVZcd99huJ+HwgB9fDwcODjrKulKi5bKILkLrknCI3ygu6ZA96WPlluXILy4fTv8cz73IzA01YfiSdOrp+TsKF1rrSezu86ihTbTpU0dt6/8Ba5JwrNEaW6G111SudTVkfUFYrdT61orKulKi+ZtZjAYeB+xqmuS8BzKKnjtz1fwTiEVowSAW/fLTMFxrWut9GQU+6hBgSllMPD6+v8g1yThzYw1+yvyfffz1btb+kxzJJfliMPVt7WutaKSrgxMTYrByO5ly7U4Cc+Sii74QHfzzGt0X1zFZlgv4l3L8PjomzcUDGOcJnlI6cmooedp7MNDMoPkvvI0kpEQ5Sd4GVIOJqM0Zk9TU6aJj+afYPUPpWutDL+I5mCeUviUHUnS5mDgbUiZ4HsO0P4A46XpZm19xVBbbma+a68jiQ61uJwBrXStlYQCMg4iQ8EyBk+5+8DUqBxv70eT/gZiJHbbo+lJ6DQ1ZaSpt4PD//HjiubThl9y3UsagmJ3Hf2jn+DWlfhVLvZkjI9mzNBvD7U1pHM0NWX1B42Kit9V6VprCQVvkTRR2lRY4StTFm7DSQlXPjWmbev4MNfW20NtByuAippyYQC+aBuhaT7FX12S8HiGQsRdJ+E98xLd45hIiVSsWsl9nZSDOZNbNaaoKR8jpgAVC3lqXetErHNXR9uNhlybsgC+j6mxu+hledmM4ozpp+/jC4TDu9U3GbxYxmpqDgNQmGEJeWqaT4ix5UqLptlM8JO4qVseMa0rYdWEPdxyMFsvSbGaWmLEJFNLyFPRfH8f67w2ZQF8D6MUKAPb6yYRxBVtudVHNx7PQJ8iNcVuTwNY8z0Vzae4dddatBeL8fwmY9+Gh/z+Sfn76XTaW/PHvZpcbQ1hD7eG2opZbGI1xXxuo+zm8JSi+RSVtN0zsCg2E3wLysv6aeWp7t33wY52Lwknu0xLERNtqaSihGX37nOkpliY3C7a5mRK0XyaW6fYR427jnU+NPGr/2kFamKHrCGcZeqgtobIXlKH2hY6psQiNcXD5DzkqWg+TSVdadH0UMg0DtuXAmJo9TXeope1CaycRfS+EiN43B6qeRjyqb3/EqopcXsKT1mlpWg+IcYOxT5qSJu5TA1EZGGdZdPWQ8ISha8+Ra2Vbd2NTOW9/Zzop3N7mMrDYEXnZ3SB+MkweU8Kcjzrmk9x6660aGQz3cpNzl20PuP2pffJUH80P3j7yfzT7vKlaU7c0WWEr/5R01GGMvuY3MdEP13Ywzxb6aNP0gUqpNYLbj+rTU3zKW7dVs/AMWYJti+9J6bmo7Sz3ZufW+ahKQvbQKJpyHIp5ip49UknjNptWcpRop8uRmKZjx3TSTVnKjrvJRCHyb3R1TSf4tZt9Aw8kyJNNBo4bV56R7gFgvszKY3qh54yv7iiaVr7o/0Xlg5e/fKa9kj004U95D52RBWcLIRiiW5vipuUYkXzCTG2KPaRlpPTxgcdq6OBd4032Z/959oP/m8s77Jomt69h0OyuL/kiu5Splq1lrdlwoW3lMFTAjUVmR9T/iLpSl9OceuWlyTwlIJK7NzKLlujgfcMvT5z8vm/uYFdddz90c9ks5/Cf0fvOkR+knj1rzQaej9d2MM6buuF8M+nhWzr9O3dNqqK5hNi7Aob+QzXuFRelWdIZqvtX19ZddH/073SPg8zBaJp/A8bypQoVF6nPXdqsTG7Mgmv93Igpjwtasrcvpe3phfRlGvlrTS3LhQlz7D9hz0aJ/cmtu9Zfhj+8WZlqsnKpT1E0xjRoW5fECEQr75QWWkS/fSMXR362Byjwcp4/cN65fajl5MqOJ5tJ+Hd11yFb+X09t5dWXTsmvpCNyRL9OK9Zpgf0T+QNw3Jl3d0ea1YoXFFDjiJfjpXeAkXnih1LTL/OdrtBydT4WvExdhxcLd7iYVur6P3a7iaVhGLKHBKvVmNqO3dZ9E0VnRITwknjDs9/OI1ElatzK5LwsszAXnJBaur6tG5LusVSXj10yqlvyTIVErOSE6oqSbVNFa+nKPLLuDiMTs5G2hx7PPVSXi9N0i26z7O1fB/jn57G1m7IgkPCKajYhHKUSuqqymj9Xv3WTSNky/r6DbLBR179dd8ak7CqtXZVUl4pibHqOvO1JQWJj97mQoOni6e0nBFlV+WwZm8fdX2FxrnFhSdUlZXU+YG/qBoGi9fVqaWG3LxuNbwaXHs89VJeHoUlKmpxO2t1R6vqN+LMZlFZ3r93H/kZfDEkskt96KMzqlqauBCIZpmli879WTghTJW5qqR+FxtW6EVEy78OdmtZGoqUWIy0cn4sS9PR6ZMPTWQ9FSTPGr1fTSSoqspc/dq/sabZpEvqsESnmJOj9YlVzHXDGqF9v5LMmqakttm+XP025sKXlO552ZJLpmxkc5eKUwmSdn9tSPdNcQXKGrqJIyKaJpFvhohU7vs+t1uPLrtEiKVcOHTDhsLoeu3B+duVyiqf5el1FSRKWNwBjJV0YJLqpraCZMhmobJFyk+H/LkTk+ZdIAkLETPaLgUJXzsFSernv+c06Uz2F9RjZdDVf2TdbgVNUWBl0a9E5kqZUgvUlOTNConfkcuX+Tourpx8aiy6zIkWvWtOPDHaT72NJ7tmzNoN53y/O3QX/H0V2BU8yJU1W80y1FrEMrcT/XgyVqO0eFITfXyHjyMKeWrXISUS34yJh8wavUZpX1mjty8V+EBczKvgkd2OKrqN61M0cw+ONFmiXRKA8lbFR8P1VQtnRDhtgj5YlNPWi75eVJTmiDssgxZqcj/Sf69xtA2QRrubmOPHGAZMuX3PSfCK6YtSBmEaqoIjZiAB5cZoVYppfLosyAJj+XvF97OCsmvda+NOGVyC/BA9j4z6SQdspicFO5bewarkMLXIkdM9c/YdzRWU4Nu2jzUHWrj44GayqVeFFFuIV/nZbUdYYnoOXoi1ihEpgz+5ulPFqifUyRPb4fT5Q9N/5FgJkvIlBJe6a31idWU6C0pVLomlGpqCG9i6uU/h6MoPTXzEEh+nUXS7ijE9VYi/VoJU0NKTxju2ouSGcvDOO7XeLM/XRSNVMIrjTsUqSnRW1LoM71PfuJqqglVGQtjxrkBrZMCUYjCENrCuqFdc9kmxfHjg/abDyXq3L0fTkgu+UtK9zoOwfFTLCal0wiRmtqllIODgg9TfHzkauoQVkLcVYrOeZ56IiXfbsoV/ilWooSa9OORM6+7K8D3472G8OUWfSxL7v2ZUE0J66ORGqTgaqoI+wMirBhLLcUmdgepflrFjNsZ7EGHVO4M8MK7AvwARnR2ym8eDz0M85EwWBhapYgytqIEU1Pm40GcrLL1/FsSijyTfc3Wicj8x/R2u5s4xDG2eytP71W/WnnwRUh0nBXhx4M+1lk4O4XUGZsilRzHWNRUFxlaEcCvsihMMTkvSEp+50za7ljXdXXMV+3aeGG14uAvsGFykinhH4V9LOHsBGpqU6QOKZFa1FQVWTYRwG9C0TkvOwXv5dEoAJDl9WrtwPfiRIcPnFkiOeHOTiFkJPKdQ8pIXjyzmiqj0KoIY6oDRE6mws6kt2getgge+AV8mJysCPdrQzkZuT5oRUvuEq6SKNCrZ2Y1FWmbRBKewAUD4uPVu1dQ+2Zaqxn4AXIrOnbgrFmOh2LQCm9GqCnF0RGkgggGp6Z65RZ5piXhCaw3Pmo3Hvr+mZfgvmd8Bz/cpiJ0qU9CxBquNcIeYIixWqkcXqemGkWPidBDrkulue4Zp+I+NLPrHOR1h6pnJ9pUjNutaSHDSfGtxcmaaqHVrPNfUqGtGhlvd8cSJrcDZ6M7HvSxpixeOGlWU+Wq5aOYdr92NjcSuk/X7Iz820fCiE61fJyDgkEfq8tkNF2oqSZby377VF3rGSOcx0xJqRIB/GRo6ykZb12Bf4KHySk85fK6gz5WFWqJP+z8SlqJc9LadAUm222LdZAI4DeHUz2s/iFPwLKo1HjrqvwLA7doNHBmPe2gj1W6ntUktiBs3dlGuvaC47qSmjNJpvB4n93xhk7fypyMPNPfukr/ggyTG8lx+kb0scgDZzvIO+YLd8K153xy0VOxairuEk4vEANogzWBPe2tK/ZPCA3BlrIQfaxe+bP5n04uuCZTJFEbaxWQmqr+7a94UOLRo4wWlepvXbF/QobJl7xu0ceqg7/aLIB0zILYVJwdOpHWSyWEz6WKy92Gf/07HpIq+E2fI+9vlwnX2GbR/qdNdHLLKfnEWZlTboVu17M7T590r+TcmdfAep8XqqaPTlJf+elWugu75z7kKfrwZOTCF0jEpqyLfhEqN7tp7Gym0ssmTE58MU/PsZOF1OHwhycaoWutauF9eONK7aMrg6kvPtnkcnGx9F6qH6v4ncNtGkNmkOrD4Y9OnL9pM/LMcd8Na3TZqIMfJPS4LnLY/1Ct759GF6ls2Xzk/KzzlxXda2WKyUtiOITUVMMOjPPS6Ib8NQRqNHG6MTpsOyze+xzHoa9dIhcvbH7B6bdq+ltounfu27rvqT/cyF4wEtM3h/3b29ul99JrVzwhZOHiOAnFkEd5zKWcMpnaTF98RLRUpDmve6SvIsIuyhlZq3+2fnfPjv1SDN2m9aTGl/Xbn3M4XFNBkzNgPX2L3S1Pnb29Vz9Zuftnch5SdCJTVbvtxMwDos85HK6mIrnuW0tfDk/5d1+BHccty/JYdWOijB9YiM4nbJr9ZXv3TYRqngZd99q87po+F5rQPTNTNI5rrNUyO5BjXCnjdx/DE2XCphk3Ys6CTRuAR0aEyRe6WZ1fvII8lej7VEz+Q5fpKEvc2Hn9eRZnDyRtWs3U1FoS9eOS0r1zXuf0iBsIfpmLUhITclSUYIFRUna3ouBEneq6kABW9rNMBHHHhrb56z/jLkjq3kfeQPDr8F6KdblNTMmM405mcOVkrWAeZoX1JB6amlrr1MydQXqS+0iDgc7cjt/zR92I/il175eJJuSM8vxo16EKMw0b6zEpaqrLUsswDszymceGazgqVvSxGC+v4+nWlfgl+kvTVfqp7Qk545H01CgOlla5KWpKs2ns9o39uNMtbHvNX3O/TLeuwO+x0sG6ZkKOHama+KHcqfhYTTGbpj3rY/kosGlT41V/DvhVLk7uFB1MjgOsrYrNIAGogxvaPkysphTr6WiWaswJC0+8Qehz0Idtb1kxRkKBpXrBNKrARzWb2UjFamqnWc/5WcVyg/1T5HI+HabnPS1fyUQpcwuzLDXyL3op6V5wIKqHWWxiNZUedOgXm2iedFALgdsS5lOUma6m0iP/QoGle8Hmxmw0uFi+RWqqSlhPIVIrphjclDDry7m6U1hup/vd/hL/OW0gSRp6Xm7vPkdqKpG4eBYi9ZxJeA/ENHaTeiLwp02b5ZqaWhn5Fwos3VvL+ZNa/iVUU2mb1jM5Spti8POQc1yrpwJXmAKQuaKmquQdNlbFFnc4+C8nfk2optI2jfX4njMJ734JJxyzkYygYHDCeDyTNsi2EZhq/Zddlopgs96aLSarx9RU2qadmFiWaVMMvhszpVA2f2o7mmgKT260wKSoqdDnYggFljaQA7NUk3xsqKaSNq1g9vI5k/DulFPc/HXCba6lKzVYx1hRUyuBqTnzwpA2kBQUH+3nLnDAAzWVsmnCxU8mLIBvx7R+2Pxru2b1y1c3lquoqdBCMoQCE/IlYfJQBUYrUFMpm3bKgqn/z5eEdzvG6mOn5bUZykxp/oSaymUH7eDUg6IB8qQ3LEJbKwaSiVQZ3IwGlhc1lbBp9K7Mx9MJC+BqaDml0X7MstVwYOSL6GpqCJqlcMKhqCk1x8DemktwGDplLCI1uULLUmMZN2kpm2bKLbl8kSn2S3jpTweMUfzwHR0jx0Rf7MyVG4LDjdbWQVBxnFVM3KjpUZJrVsU2LFJD4aUwRZ2pKd2m/ZGvEf0EVOuhbT7YIgqj/nggkxUXGnv2jazbEF/WZlz0GIUiEwfhwrAAJEnGxIsGMVGOUGBcvgSsx1dnOr4qqk0jieLhKvOko7JwWR9eCSxV4mev7OkdfVFSuv1P3IQnRFyIFZ6WrywAeQoVRXqUJE7Ci2vlnu/0Vyn/JNpi1DzQqymleznsor93p/9Ab90ZTKOS7RO9yTIv6JTpMkVK6kNtfiM/rTgyBu+9aSR2SojGRqyz8V+EfIWl9vajrbtPUbfHeKdvtmme/qT8tQfx89hFFF4r7V9nasqcfpFjkJDoDVhijTevxJYp3RYjNx9688dqKggPiQBkqKbSoyRXroqdZ3yh+F30FvHYVL7I86VPUhXubx3FBdWs4pruJeYiXYXdw9wjtpYyzV2kkxWb+SJxmARx7PXmL7LA0QjCQ0LCQjW1EusUEizkK6rZXPe4CFdTRl1GcxWqSV7QQSnFhFsF82W5VprQYFrocDQX8fAUTfKuUte2WZCYVEqpkRIWqqnQGC0ICU4YSBq5dscTtrFaqidtGvGqiwJ+DTvXPd9XdV3t7Q+3yEfkTwTXGqlh6xhbPjPrcCSuDdVUoMyMhE3iCVzgkn73VUl4pI4H+znPkruAu+qFfZN9rZQHEaRScv9juVXLFvlINyEVN9eG22zR1zp9baCmeqlQJkXC2OldluyfcwnWNaSRdX+zpFe2dPpms06dwVdZcOvfOWWyDzPuMt5qu2x1jQ77qst10+cxsFTzSzVlGq5dTgYSZsPwS/2SfreUYFW7kkT5vzXZd1zUVPc0607/KqRnRn6E7Nj8hq80ocE1I5kndxtqknbtWqmmDlKX1eFFUk1V2WoS3hBUjDGWGRf8dBz+9LY/dfojwBXU8ctqfNj95L6YJmzSl3sft10UwKyk0s0v1FQez2QY3Gca5NgJNdWklIuShDewk71dxX2J9Bfr6hf8NaVinDq28OtKuNowNyPFRE14alFS6ebvmZoyCu7AzpG668LdWebbdNlqEl4TVcwMKTU+plQM/rz1AsEPsIsMhKRNN6GhnhVR5Vp+UVIrzc8EuY1dKQ1fxyFLRjWEBJvqfISL4R+nuXCX5e91+u8Cf896j25zohpzco+m0f4wJbXS/ExNnbJoJkNAnjNZmdLaRUi/ch+x6PY0pf8o8E+kvVTLhoEwimhvP9rwVMFEcKX5FzW1k2VYeHEe5BAhdCNfk3pPIcFtKE/1qF4Evh0WLNbJZBMaj9n4OYP7yppx3jKk94XTzT+rqSmTxtFcEo28lkxNvUmtRsk39VwXkYRHKo7GcTH49ov0QgYUrGX0uYqzZ9LZsyL+Y7fZYh550Pwcr6bM85vlsG5neWzK9TFtxpurjxMkLsGjUXGIKd0Eo1qCdbwEpu2jzMdFDHJmk5xqWG6WGEYzeDVVZ1H6ndJJLDPhexVFUJuJTr2t/yXglyANkKcmJSR2xszeWnd6JxRRIBGnLB3UcmqqjF2pLlHJnj7WWnVGOjXAvt0HdnA0/0gMYokmjNOmAve+jiLhVeKxTk3l0UwGtQO6qCnhdyPj7T5ZBtx3x7obgrMttVxyjbcwul5xs5UcRzOQmjKCVS/H9NHeM1dT9AkZb3dOK1yTXO6NycIEGlF0fWKfTfMng1qkpppMuFLrwVHbRYRSegTG9l24Jl9Nwkved/VaIyVGmKflUNr5GloopQdj6psDk6tlb0w1TWRhPbq+eq0be9mzQ7sMs5WejKGr97l1q+ZjecJjtqxH19eHe0p6UrUcWAm3g0fGula1/2o0x5AunWUry8Ctax2rprrlwGC6k1fXEzwOlNg5z/LdGAVcVUQbCXzlqjyCJ0LsULuRhFdmK8vAreRgGgYMmbwMNevHXZuEp7GSgwleC54ncnUSnsJKDiZ4MVjv//okvJjhhbbhAjPjqY4Pst68HiaYtw1aj66P/1o78HBMJy0jRGgm3i2b2EyDgY5sRNfB61Fqdu3Erdkbje+yjDdHR2c3ouvg9aB4Y+AMUSrd6L+VmU5jTyO5BARQQlQ5siN9LqRMScKj5JLht2sKHgUSmaIZ3deetBJbJmFJwkPGG7gOl4NXmuWAjtZd4gtvtC+S8TZe/MVb1+FpcBveL4iVuaYb1eqXoRmE/a1r8TSMwl/iGXivA71Wq1MawZcY2wOZvPy96m9dl5/GRNbG8OBoX6f+96vz1GjLVD8h6ozVzjmUN6gPeHjUDDCacgo1BVb5LAttMxJ90sTuYvR7qCmwyimIhni0DDC73EcJNQUsdv2WcL50HUbYHFo+TkeaC2rq5aGlifhKd2XLztq57uFmJHoGWJX5JRqgpl6Ryf6nrrjBtJLrxEUJglo+jpGl8xlq6tXwi0q5jMBGEym2aLALNWV/wvuYg1N0aG/+h5p6CYKdYmd56LwQ2dHsvj1RkTmjcPLFw6WO4olivffYW6ip50bbsDSb5cH4RLkczSZbOPtJ5kq6upG33UWqyFzX0acCaur5sEppNB/fVMv2dhhswSzOim+5BBnR6Uhz9aJQPFGsnFUf1NQTQVu7z0qpN4d2XJTiFJs89omo6+bVFIXJaScvGfKMZ6zmy0VQUw9P7CkRrTl3ylbz/rTBOpop7Q7aidLkconwVBSY6tkBqKmHZTJKya9CHFObMhsT4NWVPcvF8rkwOfUMi2kpEs1YbbglhJp6VOwsnCkUJbF99cYEeHWwjg23+InS1mmf5iJRYOrA1V0DNfWY0ML7o/WHyFPaG8cp2JdzYwJ8nSnLNTCrNofJKcNwkc3Iry/4d769Mbg/povwGE+pCU98ukY+zGsUK6O5Q6hOJOrkeXZwmShtrCELTwV+vXnMfvlarz8V3AS/mwPZJdIRvSzglRRDWc9jY1m8PlOmtXLJzLzo0D7Zi0wFfn0rXTZSU236seA3icZxjb6w+5COomCbRUspaKO5gToJn6apkwNzsJYwudx/OfDrT4HIQ03dA6NVShEHOllkYUaA0q3S1vNQc3oXzBPCimRM/ZWL6NiupXtk4NcXgeBCTd0DbSxNRkLeT3R2kO6xqqTU0Vw1TLAQD9bRtoCzruNhcpqp78b/pF8/Lpc4g51DTd2eQUgSRSf5bg6NdI/12I8iIGqYYGEX3eZPxoWw5k4SSb21v9KvN/3KYxtuMQo1dWPI3ryldyyrRFOrSkpb9lMNEyyEg3W9kTF2gRQdm+U5nUO/vlI1LNTUrVGslqDMWNpJoSqBeDRXDxOMfec+zdF1a7CskmFOWxDXItkxoiT9+l0kTW/vOdTUzVGsloC68W5UpNV1gDBTFq5O2GCgv9jY011gsE7TcnnYJZxDnub/uWbzpcxgo9N3exSrJaEulx3o0JWUppJIJvo4bWqyp7ssJBf3DeNadv/lT/kCGLEtQoONTt/tUaxWALW/SdpNKCl12c9IZiyjPTtEJ4Kk4DzQnTY89Sn8epuvEAI1dXMUq6UVMY2XUFJq5DJOwjN9gHa0ZydhsIyiDDqAUVzLhTz5C1BGV9GtoaZujepIB5ArM6SUlLrs5262aDxDYca0+5xKxd01xyGSC8rIy0r2AihPNUBN3RrNaoXYkZld8vUPzdTZSuFR37DUILUQRTNFXooS15qDsh/LRVrFoaZujTreFhUqbGsmCu5CM/XVJLwqC0RIyW6Y52od0kUIqKkbo1mtGGt2Ui9/bKa+moQXulOqOa6FXJdZoqtKako9A34HxWopkIpI5asofa8gWBkSRtcpUsHcKS27wa+RnC/1nqIihh4L3d4WxWqZoPYYHCI19d9Z5RuS8ChScZy/Jsyxdfon/4CVLXLADeFWi6VNNbJUbxXEoN7iO5LwAncqU3WQzcijSmxYVnBDyJHuorSpSpYqnR8zarf4jiQ8GyAf/NfEOBH1EzrzqXv+1bcfliZTOYhCNPhRpGzNtyThSXdql3Cxh2g1KnB3xEl4FNTuRCGjpFoyftFyKgbFTH09CY9k29uy7XEicLcs423pzRycs91If2fhO5LwXIfOXbMR1wL3DFmtjR1mTq6ByYfu4/NlrJK+mIRnIOfb5WaNycA7uH/0zhVnnB3zMsuUnSWvS8Kz3Ul3TNVCg0lVWa8KeAS2kvAWJeV6XHKE17CWhDdPDXR9RnsaMYBnJtW5mlmUlBuZOYYlEkl4eTjTYFGIXZa/199QeXCPbHauTlxgqIMYrnj4hSQ8rxCnf602uF+2OlcjE4SzG7z9Ly6ykYT39n5IzcIBz8ZWEt4pOH/MopEZbfhlR5IUTw0Ez89G0kCgpHwS5igK5bGL30IpvSwbSXihknJDJ3Jkxqik4QfqBh6S9aSBSEmdXVqCGJk5vZ+q4QfqBh4TxWotxErqvMyZAUAlThqw6053Z3WJMkNlRgN/oWrgMZmT8IJ1p5vzso4iAF+AJkgpO3RUSSUFwCqJJDwTWRia9RQFADTCJDyaao7oJPh7XBJejiET8E2MGDIBAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAruL/MJrnpgplbmRzdHJlYW0KZW5kb2JqCjE5IDAgb2JqCjw8Ci9UeXBlIC9YT2JqZWN0Ci9TdWJ0eXBlIC9Gb3JtCi9CQm94IFsgMTAuMSAtMC4wNjEgNTg1LjI1IDgxMy44NCBdCi9SZXNvdXJjZXMgMjAgMCBSCi9Hcm91cCA8PAovUyAvVHJhbnNwYXJlbmN5Ci9DUyAvRGV2aWNlUkdCCi9LIHRydWUKPj4KL0ZpbHRlciAvRmxhdGVEZWNvZGUKL0xlbmd0aCA0Nwo+PgpzdHJlYW0KeJwrVDA1N9UzVDAAQgtDYz0LUwVDAxBfz8DYUiE5l0vfM9dEwSVfIZALAL0CCOQKZW5kc3RyZWFtCmVuZG9iagoyMCAwIG9iago8PAovRm9udCAyMSAwIFIKL1hPYmplY3QgPDwKL0ltNCAxNyAwIFIKL1RyNSAxOSAwIFIKPj4KL0V4dEdTdGF0ZSA8PAovRUdTNiA2IDAgUgo+PgovUHJvY1NldCBbIC9QREYgL1RleHQgL0ltYWdlQyAvSW1hZ2VJIC9JbWFnZUIgXQo+PgplbmRvYmoKMjEgMCBvYmoKPDwKPj4KZW5kb2JqCnhyZWYKMCAyMgowMDAwMDAwMDAwIDY1NTM1IGYgCjAwMDAwMDAwMTUgMDAwMDAgbiAKMDAwMDAwMDA3NCAwMDAwMCBuIAowMDAwMDAwMTE0IDAwMDAwIG4gCjAwMDAwMDAxNjMgMDAwMDAgbiAKMDAwMDAwMDU4NSAwMDAwMCBuIAowMDAwMDIyMTM5IDAwMDAwIG4gCjAwMDAwMjIxNzYgMDAwMDAgbiAKMDAwMDAyMjMyNiAwMDAwMCBuIAowMDAwMDIyODcyIDAwMDAwIG4gCjAwMDAwMjM0NjAgMDAwMDAgbiAKMDAwMDAyMzcwMSAwMDAwMCBuIAowMDAwMDI4MjgxIDAwMDAwIG4gCjAwMDAwMjg0MjkgMDAwMDAgbiAKMDAwMDAyODkwNCAwMDAwMCBuIAowMDAwMDI5NDA2IDAwMDAwIG4gCjAwMDAwMjk2NDEgMDAwMDAgbiAKMDAwMDAzMzE0NiAwMDAwMCBuIAowMDAwMDM0ODEwIDAwMDAwIG4gCjAwMDAwNTQyNzQgMDAwMDAgbiAKMDAwMDA1NDUzMCAwMDAwMCBuIAowMDAwMDU0NjgxIDAwMDAwIG4gCnRyYWlsZXIKPDwKL1NpemUgMjIKL1Jvb3QgMyAwIFIKL0luZm8gMiAwIFIKPj4Kc3RhcnR4cmVmCjU0NzAzCiUlRU9GCg==",
    "source_account": {
        "account_branch": "0001",
        "account_digit": "7",
        "account_number": "00001",
        "financial_institution_compe_number": 329,
        "financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
        "owner_document_number": "32402502000135",
        "owner_document_number_formatted": "32.402.502/0001-35",
        "owner_name": "QI SCD S.A."
    },
    "source_subtype": "outgoing_funds_transfer",
    "source_subtype_translation_ptbr": "TED",
    "target_account": {
        "account_branch": "0001",
        "account_digit": "1",
        "account_number": "92796",
        "account_type": "checking_account",
        "account_type_str": "Conta Corrente",
        "financial_institution_compe_number": "001",
        "financial_institution_name": "BCO DO BRASIL S.A.",
        "owner_document_number": "23599885000192",
        "owner_document_number_formatted": "23.599.885/0001-92",
        "owner_name": "Titular da Conta"
    },
    "transacted_at": "2024-08-08 18:55:16",
    "transacted_at_br": "2024-08-08 15:55:16",
    "transacted_at_br_formatted": "08/08/2024, 15:55:16",
    "transacted_at_formatted": "08/08/2024, 18:55:16",
    "transaction_amount": 8.86,
    "transaction_amount_formatted": "R$ 8,86",
    "transaction_key": "616b950a-60c4-4180-bce3-bccad533c32b"
}
```

**Response Body: Comprovantes PIX**

```json
{
    "chargeback_reason": null,
    "chargeback_unexpected_reason": null,
    "end_to_end_id": "E32402502202408262133XBCeENgoPHs",
    "origin_key": "ce7b934d-6651-4d42-8a83-9d8bebf517ff",
    "pdf_encoded_string": "JVBERi0xLjcKJeLjz9MKMSAwIG9iago8PAovVHlwZSAvUGFnZXMKL0NvdW50IDEKL0tpZHMgWyA0IDAgUiBdCj4+CmVuZG9iagoyIDAgb2JqCjw8Ci9Qcm9kdWNlciAoUHlQREYyKQo+PgplbmRvYmoKMyAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwovUGFnZXMgMSAwIFIKPj4KZW5kb2JqCjQgMCBvYmoKPDwKL1R5cGUgL1BhZ2UKL01lZGlhQm94IFsgMCAwIDU5NS4yNzU1OTEgODQxLjg4OTc2NCBdCi9Db250ZW50cyA1IDAgUgovUmVzb3VyY2VzIDw8Ci9FeHRHU3RhdGUgPDwKL2ExLjAgPDwKL2NhIDEKPj4KL2ExIDw8Ci9jYSAxCj4+Ci9hMC43IDw8Ci9jYSAwLjcKPj4KL0VHUzYgNiAwIFIKPj4KL0ZvbnQgPDwKL1ZDQVRXUyA3IDAgUgovT0NITlVQIDEyIDAgUgo+PgovWE9iamVjdCA8PAovSW00IDE3IDAgUgovVHI1IDE5IDAgUgo+PgovUHJvY1NldCBbIC9UZXh0IC9JbWFnZUkgL0ltYWdlQiAvSW1hZ2VDIC9QREYgXQo+PgovVHJpbUJveCBbIDAgMCA1OTUuMjc1NTkxIDg0MS44ODk3NjQgXQovQmxlZWRCb3ggWyAwIDAgNTk1LjI3NTU5MSA4NDEuODg5NzY0IF0KL0Fubm90cyBbIF0KL1BhcmVudCAxIDAgUgo+PgplbmRvYmoKNSAwIG9iago8PAovTGVuZ3RoIDIxMTIyCj4+CnN0cmVhbQpxCjEgMCAwIC0xIDAgODQxLjg4OTc2NCBjbQpxCjAuNzUgMCAwIDAuNzUgMCAwIGNtCnEKcQpxCnEKcQpxCjAgMCBtCjc5My43MDA3ODcgMCBsCjc5My43MDA3ODcgMCA3OTMuNzAwNzg3IDAgNzkzLjcwMDc4NyAwIGMKNzkzLjcwMDc4NyAxNDYuNDY4NzUgbAo3OTMuNzAwNzg3IDE1MS45Njg3NSA3ODkuMjAwNzg3IDE1Ni40Njg3NSA3ODMuNzAwNzg3IDE1Ni40Njg3NSBjCjEwIDE1Ni40Njg3NSBsCjQuNSAxNTYuNDY4NzUgMCAxNTEuOTY4NzUgMCAxNDYuNDY4NzUgYwowIDAgbAowIDAgMCAwIDAgMCBjClcKbgpxCjAuMDk4MDM5IDAuMTQxMTc2IDAuNDk0MTE4IHJnCi9hMS4wIGdzCjAgMCA3OTMuNzAwNzg3IDE1Ni40Njg3NSByZQpXCm4KMCAwIDc5My43MDA3ODcgMTU2LjQ2ODc1IHJlCmYKUQpRCnEKNzkzLjcwMDc4NyAwIG0KMCAwIGwKMCA1IGwKNzkzLjcwMDc4NyA1IGwKVyoKbgoxIDAuMjUwOTggMC41MDE5NjEgcmcKL2ExLjAgZ3MKMCA1IG0KNzkzLjcwMDc4NyA1IGwKNzkzLjcwMDc4NyA1IDc5My43MDA3ODcgNSA3OTMuNzAwNzg3IDUgYwo3OTMuNzAwNzg3IDE0Ni40Njg3NSBsCjc5My43MDA3ODcgMTUxLjk2ODc1IDc4OS4yMDA3ODcgMTU2LjQ2ODc1IDc4My43MDA3ODcgMTU2LjQ2ODc1IGMKMTAgMTU2LjQ2ODc1IGwKNC41IDE1Ni40Njg3NSAwIDE1MS45Njg3NSAwIDE0Ni40Njg3NSBjCjAgNSBsCjAgNSAwIDUgMCA1IGMKMCAwIG0KNzkzLjcwMDc4NyAwIGwKNzkzLjcwMDc4NyAwIDc5My43MDA3ODcgMCA3OTMuNzAwNzg3IDAgYwo3OTMuNzAwNzg3IDE0Ni40Njg3NSBsCjc5My43MDA3ODcgMTUxLjk2ODc1IDc4OS4yMDA3ODcgMTU2LjQ2ODc1IDc4My43MDA3ODcgMTU2LjQ2ODc1IGMKMTAgMTU2LjQ2ODc1IGwKNC41IDE1Ni40Njg3NSAwIDE1MS45Njg3NSAwIDE0Ni40Njg3NSBjCjAgMCBsCjAgMCAwIDAgMCAwIGMKZioKUQpRCnEKcQowIDAgMCByZwovYTEuMCBncwpCVApFVAoxIDEgMSByZwpCVAoxIDAgMCAtMSAyNTguOTYzMTg3IDgxLjQ4MTQ0NSBUbQovVkNBVFdTIDE4IFRmClsgPDAwMjYwMDUyMDA1MDAwNTMwMDU1MDA1MjAwNTkwMDQ0MDA1MTAwNTcwMDQ4MDAwMzAwNDcwMDQ4MDAwMzAwMzc+IDEwOSA8MDA1NTAwNDQwMDUxMDA1NjAwNDQwMGE5MDBhNTAwNTI+IF0gVEoKMSAwIDAgLTEgMzMxLjUwNjY0NCAxMDUuODY1MjM0IFRtCi9PQ0hOVVAgMTIgVGYKWyA8MDAxNTAwMTkwMDEyMDAxMzAwMWIwMDEyMDAxNTAwMTMwMDE1MDAxNzAwMGYwMDAzMDAxNDAwMWIwMDFkMDAxNjAwMTcwMDFkMDAxMzAwMTY+IF0gVEoKRVQKUQpRCnEKcQozNTguMzUwMzk0IDI1IDc3IDIyIHJlClcKbgpxCi9hMSBncwoxIDAgMCAxIDM1OC4zNTAzOTQgMjUgY20KcQpxCjEgMCAwIDEgMCAwIGNtCjEgMCAwIDEgMCAwIGNtCnEKMCAwIG0KMy41NjM3MiA2LjI1MDAxIG0KMy44ODI4NyA2LjI1MDg5IDQuMTk0NjEgNi4zNTI0MyA0LjQ1OTU1IDYuNTQxODIgYwo0LjcyNDQ5IDYuNzMxMiA0LjkzMDc0IDYuOTk5OTIgNS4wNTIyMyA3LjMxNDAxIGMKNS4xNzM3MyA3LjYyODExIDUuMjA1MDIgNy45NzM0OSA1LjE0MjE1IDguMzA2NTEgYwo1LjA3OTI4IDguNjM5NTMgNC45MjUwNyA4Ljk0NTIzIDQuNjk5MDEgOS4xODUwMSBjCjQuNDcyOTYgOS40MjQ3OCA0LjE4NTE5IDkuNTg3ODUgMy44NzIwOCA5LjY1MzYxIGMKMy41NTg5NyA5LjcxOTM4IDMuMjM0NTggOS42ODQ4OSAyLjkzOTg4IDkuNTU0NDkgYwoyLjY0NTE5IDkuNDI0MSAyLjM5MzQyIDkuMjAzNjYgMi4yMTY0IDguOTIxMDMgYwoyLjAzOTM3IDguNjM4NCAxLjk0NTA0IDguMzA2MjYgMS45NDUzMSA3Ljk2NjU5IGMKMS45NDUzMSA3Ljc0MDY2IDEuOTg3MjEgNy41MTY5NiAyLjA2ODYxIDcuMzA4MzEgYwoyLjE1MDAxIDcuMDk5NjYgMi4yNjkzMSA2LjkxMDE2IDIuNDE5NjcgNi43NTA2OSBjCjIuNTcwMDMgNi41OTEyMSAyLjc0ODQ4IDYuNDY0ODkgMi45NDQ4IDYuMzc4OTcgYwozLjE0MTEzIDYuMjkzMDYgMy4zNTE0NSA2LjI0OTIzIDMuNTYzNzIgNi4yNTAwMSBjCmgKMTYuOSAxNC45MzExIG0KMTQuOTkzNiAxMy4yMjQ5IDEzLjE3MzQgMTAuNjA3OSAxMS41NzQ0IDEyLjQyOTYgYwoxMC4zNjkzIDEzLjgwNCAxMS42MDM3IDE0Ljg1NzEgMTIuMjQxIDE1LjUwNzMgYwoxMy45MDEyIDE3LjIzNzIgMTYuMDc2MiAxOS41Njg0IDE3Ljg2MDIgMjEuMTQ1OCBjCjE4LjQ1NTggMjEuNjcxNiAxOC43NzAzIDIxLjgwNjMgMTkuMjA1OSAyMS45MSBjCjIwLjUyMzcgMjIuMjE5NiAyMS4yNjY4IDIxLjAyMTQgMjEuMDE0OSAxOS44MzY1IGMKMjAuNzc4NCAxOC43MDM1IDE5LjU4NzIgMTcuNTgwOCAxOS4zMzM5IDE3LjQ0MTYgYwoyMC4yNTc5IDE2LjA3NSAyMC44NTE5IDE0LjQ4NzYgMjEuMDYzNiAxMi44MTkxIGMKMjEuMzYzOCAxMC42MDc1IDIxLjAwNDEgOC4zNTE0IDIwLjAzNTMgNi4zNjg5OSBjCjE4LjY0MzcgMy41NTQ5MiAxNi4xMzg4IDEuNzUyNDQgMTQuMjE5OCAxLjEzNzc5IGMKMTMuMTgxNyAwLjgwNDU0NiAxMi4yMjQzIDAuOTIzMDMzIDExLjc1MTIgMS4yODU5IGMKMTEuMTg0OCAxLjcxMzkzIDEwLjg5OTUgMi43MzI5MiAxMS4zNjU3IDMuNTU3ODkgYwoxMS40NDU5IDMuNzA1MTkgMTEuNTUzNCAzLjgzMzYzIDExLjY4MTYgMy45MzU0NiBjCjExLjgwOTggNC4wMzcyOSAxMS45NTYxIDQuMTEwMzggMTIuMTExNiA0LjE1MDMyIGMKMTIuNzgyMyA0LjMyMDY1IDE0LjA5MTggNC42ODIwMyAxNS4yMTQ4IDUuNjMxNDEgYwoxNi40NTU4IDYuNjQ3MTIgMTcuMzI0MSA4LjA5MjYgMTcuNjY5NiA5LjcxNzcyIGMKMTguMDU1IDExLjQ2MzkgMTcuNzI4IDEzLjYxNDUgMTYuOTAxNCAxNC45MzExIGMKMi4zMzMxNyAxMS44MzA4IG0KMS4zODk2OCAxMi4yNDk5IDEuMjQ0OTYgMTMuMTQ0NSAxLjQzNjk5IDE0LjA4MiBjCjEuNzQ1OTIgMTUuNTkxMiAyLjk1MjQzIDE3LjY5MjkgMy44ODIgMTguNjkxMSBjCjUuMjczNTggMjAuMTcyMiA2Ljk0MzQ4IDIxLjI3ODYgOC45MDcgMjEuNzIxNCBjCjEwLjUxMTUgMjIuMDgyOCAxMi4yNzA1IDIyLjA5MTcgMTMuMjMwNiAyMS43NTI2IGMKMTQuNjIyMiAyMS4yNjA4IDE0Ljg2MDIgMTguNDY5IDEyLjU1NDMgMTguNDI5IGMKMTIuMTgyOCAxOC40MjkgMTEuNzY2NyAxOC40NTU3IDExLjMyNTYgMTguNDc0OSBjCjEwLjQzMzYgMTguNTEwNiA5LjU0Mzg2IDE4LjM1NzYgOC43MDc4MyAxOC4wMjQ4IGMKNy44NzE3OSAxNy42OTIgNy4xMDYwOSAxNy4xODYxIDYuNDU1MDMgMTYuNTM2MiBjCjUuOTE0IDE2LjAxNCA1LjQ3MTA1IDE1LjM4NzMgNS4xNDk3MyAxNC42ODkzIGMKNC45NDYyMSAxNC4yNDk0IDQuNzY1NSAxMy43OTggNC42MDg0MSAxMy4zMzcgYwo0LjUyNjMgMTMuMDczNCA0LjUzODgzIDEyLjgxODYgNC4zODAxOSAxMi41NDAyIGMKNC4xNzI0MyAxMi4xODQgMy44NTMwMiAxMS45MTc0IDMuNDc4NDMgMTEuNzg3NSBjCjMuMTAzODQgMTEuNjU3NyAyLjY5ODE4IDExLjY3MyAyLjMzMzE3IDExLjgzMDggYwpoCjAuMzA5ODA0IDAuOCAwLjkyOTQxMiByZwovYTEuMCBncwoxIHcKMCBKCjAgago0IE0KZioKUQpxCjAgMCBtCjguOTg0NzMgNy4wMzcxMSBtCjkuNDgyNjggNy4wMzY4MiA5Ljk2OTUyIDcuMTkzNzEgMTAuMzgzNyA3LjQ4NzkzIGMKMTAuNzk3OCA3Ljc4MjE2IDExLjEyMDcgOC4yMDA1IDExLjMxMTUgOC42OTAwNSBjCjExLjUwMjIgOS4xNzk2IDExLjU1MjMgOS43MTgzNiAxMS40NTUzIDEwLjIzODIgYwoxMS4zNTgzIDEwLjc1OCAxMS4xMTg3IDExLjIzNTYgMTAuNzY2NyAxMS42MTA0IGMKMTAuNDE0NyAxMS45ODUzIDkuOTY2MTEgMTIuMjQwNiA5LjQ3Nzc1IDEyLjM0NDEgYwo4Ljk4OTM5IDEyLjQ0NzYgOC40ODMxNiAxMi4zOTQ2IDguMDIzMDkgMTIuMTkxOSBjCjcuNTYzMDEgMTEuOTg5MSA3LjE2OTc3IDExLjY0NTcgNi44OTMxIDExLjIwNTEgYwo2LjYxNjQzIDEwLjc2NDQgNi40Njg3NSAxMC4yNDY0IDYuNDY4NzUgOS43MTYzOSBjCjYuNDY4NzUgOS4wMDYwNiA2LjczMzc4IDguMzI0OCA3LjIwNTU4IDcuODIyMzggYwo3LjY3NzM4IDcuMzE5OTYgOC4zMTczMiA3LjAzNzUgOC45ODQ3MyA3LjAzNzExIGMKaAo2LjUxMDk2IDAgbQo2Ljg5OTAzIDAgNy4yNzgzOSAwLjEyMjQ3OSA3LjYwMTA2IDAuMzUxOTQ4IGMKNy45MjM3MyAwLjU4MTQxNiA4LjE3NTIyIDAuOTA3NTY4IDguMzIzNzMgMS4yODkxNiBjCjguNDcyMjQgMS42NzA3NSA4LjUxMTA5IDIuMDkwNjUgOC40MzUzOSAyLjQ5NTc0IGMKOC4zNTk2OCAyLjkwMDg0IDguMTcyOCAzLjI3Mjk1IDcuODk4MzkgMy41NjUgYwo3LjYyMzk4IDMuODU3MDYgNy4yNzQzNyA0LjA1NTk2IDYuODkzNzUgNC4xMzY1NCBjCjYuNTEzMTMgNC4yMTcxMSA2LjExODYyIDQuMTc1NzYgNS43NjAwOCA0LjAxNzcgYwo1LjQwMTU1IDMuODU5NjQgNS4wOTUxMSAzLjU5MTk3IDQuODc5NTEgMy4yNDg1NCBjCjQuNjYzOTEgMi45MDUxMiA0LjU0ODgzIDIuNTAxMzYgNC41NDg4MyAyLjA4ODMzIGMKNC41NDg4MyAxLjUzNDQ3IDQuNzU1NTUgMS4wMDMzIDUuMTIzNTIgMC42MTE2NTcgYwo1LjQ5MTQ5IDAuMjIwMDE5IDUuOTkwNTcgMCA2LjUxMDk2IDAgYwpoCjEuMjI1OTggMi4zMzg5IG0KMS40NzA1MiAyLjMzNzE0IDEuNzEwMDQgMi40MTI3MyAxLjkxNDE1IDIuNTU2MDcgYwoyLjExODI2IDIuNjk5NDIgMi4yNzc3NiAyLjkwNDA2IDIuMzcyNDMgMy4xNDQwMyBjCjIuNDY3MDkgMy4zODQwMSAyLjQ5MjY1IDMuNjQ4NTEgMi40NDU4NiAzLjkwMzk3IGMKMi4zOTkwNiA0LjE1OTQzIDIuMjgyMDMgNC4zOTQzNCAyLjEwOTYgNC41Nzg5IGMKMS45MzcxOCA0Ljc2MzQ2IDEuNzE3MTMgNC44ODkzNSAxLjQ3NzM3IDQuOTQwNiBjCjEuMjM3NjIgNC45OTE4NCAwLjk4ODk2NSA0Ljk2NjE0IDAuNzYyOTU3IDQuODY2NzQgYwowLjUzNjk1IDQuNzY3MzUgMC4zNDM3NzUgNC41OTg3NSAwLjIwNzkzOSA0LjM4MjMyIGMKMC4wNzIxMDQgNC4xNjU5IC0wLjAwMDI2OSAzLjkxMTQxIDAuMDAwMDAxIDMuNjUxMTQgYwowLjAwMDAwMSAzLjMwMzExIDAuMTI5ODk5IDIuOTY5MzQgMC4zNjExMjEgMi43MjMyNSBjCjAuNTkyMzQyIDIuNDc3MTUgMC45MDU5NDUgMi4zMzg5IDEuMjMyOTQgMi4zMzg5IGMKMC4zMDk4MDQgMC44IDAuOTI5NDEyIHJnCi9hMS4wIGdzCjEgdwowIEoKMCBqCjQgTQpmKgpRCnEKMCAwIG0KNjEuODg4OSAxNC4xMDg0IG0KNjEuNDI5IDE0LjExNzcgNjAuOTY5NyAxNC4wNjggNjAuNTIxIDEzLjk2MDMgYwo2MC4xOTcyIDEzLjg4NTkgNTkuODk2MiAxMy43MjYgNTkuNjQ1NyAxMy40OTUyIGMKNTkuNDE5MiAxMy4yNjc4IDU5LjI1OCAxMi45NzY2IDU5LjE4MDkgMTIuNjU1NCBjCjU5LjA4MDYgMTIuMjM5IDU5LjAzMzcgMTEuODEgNTkuMDQxOCAxMS4zODAyIGMKNTkuMDQxOCA4Ljg4NjA4IGwKNTkuMDM0NSA4LjQ1ODI1IDU5LjA4MTMgOC4wMzEzMyA1OS4xODA5IDcuNjE2NzkgYwo1OS4yNTcgNy4yOTM5NiA1OS40MTgzIDcuMDAxMDMgNTkuNjQ1NyA2Ljc3MjU3IGMKNTkuODk2MiA2LjU0MTgxIDYwLjE5NzIgNi4zODE4NyA2MC41MjEgNi4zMDc1MSBjCjYwLjk2OTcgNi4xOTk3NCA2MS40MjkgNi4xNTAwMSA2MS44ODg5IDYuMTU5NCBjCjY3LjA2NTYgNi4xNTk0IGwKNjcuMDY1NiA3LjY4NjQgbAo2MS45NjU1IDcuNjg2NCBsCjYxLjc1NDIgNy42ODE0NiA2MS41NDMxIDcuNzAyODMgNjEuMzM2NSA3Ljc1MDA4IGMKNjEuMTkwOSA3Ljc4MjI2IDYxLjA1NjYgNy44NTY1NyA2MC45NDgyIDcuOTY0ODQgYwo2MC44NDc4IDguMDc2NDYgNjAuNzc5MiA4LjIxNjE4IDYwLjc1MDYgOC4zNjc3IGMKNjAuNzExMiA4LjU2ODMxIDYwLjY5MyA4Ljc3Mjk5IDYwLjY5NjQgOC45Nzc5IGMKNjAuNjk2NCAxMS4zMDc3IGwKNjAuNjkyNSAxMS41MTUgNjAuNzEwNyAxMS43MjIyIDYwLjc1MDYgMTEuOTI1MyBjCjYwLjc4MDIgMTIuMDc0MyA2MC44NDg3IDEyLjIxMTMgNjAuOTQ4MiAxMi4zMjA3IGMKNjEuMDU3NSAxMi40MzAxIDYxLjE5NDMgMTIuNTAzMiA2MS4zNDIgMTIuNTMxIGMKNjEuNTUxMSAxMi41NzM1IDYxLjc2MzggMTIuNTkyOCA2MS45NzY2IDEyLjU4ODggYwo2Ny4wNjU2IDEyLjU4ODggbAo2Ny4wNjU2IDE0LjEwMjUgbAo2MS44ODg5IDE0LjEwODQgbApoCjUyLjgxNzIgMTQuMTA4NCBtCjUyLjM1NzMgMTQuMTE3NyA1MS44OTggMTQuMDY4IDUxLjQ0OTMgMTMuOTYwMyBjCjUxLjEyNTUgMTMuODg1OSA1MC44MjQ0IDEzLjcyNiA1MC41NzQgMTMuNDk1MiBjCjUwLjM0NzUgMTMuMjY3OCA1MC4xODYzIDEyLjk3NjYgNTAuMTA5MiAxMi42NTU0IGMKNTAuMDA4OCAxMi4yMzkgNDkuOTYyIDExLjgxIDQ5Ljk3IDExLjM4MDIgYwo0OS45NyA4Ljg4NjA4IGwKNDkuOTYyOCA4LjQ1ODI1IDUwLjAwOTYgOC4wMzEzMyA1MC4xMDkyIDcuNjE2NzkgYwo1MC4xODUzIDcuMjkzOTYgNTAuMzQ2NiA3LjAwMTAzIDUwLjU3NCA2Ljc3MjU3IGMKNTAuODI0NCA2LjU0MTgxIDUxLjEyNTUgNi4zODE4NyA1MS40NDkzIDYuMzA3NTEgYwo1MS44OTggNi4xOTk3NCA1Mi4zNTczIDYuMTUwMDEgNTIuODE3MiA2LjE1OTQgYwo1NC42NTU1IDYuMTU5NCBsCjU0LjY1NTUgNy42NjI3IGwKNTIuODE3MiA3LjY2MjcgbAo1Mi42MTg4IDcuNjU3NjEgNTIuNDIwNiA3LjY3OTAxIDUyLjIyNzIgNy43MjYzOSBjCjUyLjA5MDMgNy43NTk4MiA1MS45NjM4IDcuODMwMjEgNTEuODU5OCA3LjkzMDc4IGMKNTEuNzY0NiA4LjAzMjQ0IDUxLjY5OTcgOC4xNjE3NyA1MS42NzMzIDguMzAyNTMgYwo1MS42Mzg3IDguNDk0NzggNTEuNjIzMyA4LjY5MDM4IDUxLjYyNzQgOC44ODYwOCBjCjUxLjYyNzQgOS40MjIyMyBsCjU3Ljk4NTUgOS40MjIyMyBsCjU3Ljk4NTUgMTAuODMyMiBsCjUxLjYyNzQgMTAuODMyMiBsCjUxLjYyNzQgMTEuMzkwNiBsCjUxLjYyNDEgMTEuNTg5MyA1MS42NDA0IDExLjc4NzkgNTEuNjc2MSAxMS45ODMgYwo1MS43MDE4IDEyLjEyMzIgNTEuNzY0NSAxMi4yNTI3IDUxLjg1NyAxMi4zNTYzIGMKNTEuOTU5MiAxMi40NTcyIDUyLjA4NjkgMTIuNTI0MSA1Mi4yMjQ0IDEyLjU0ODggYwo1Mi40MjA5IDEyLjU4NjggNTIuNjIwMyAxMi42MDQyIDUyLjgyIDEyLjYwMDYgYwo1OC4wMjg3IDEyLjYwMDYgbAo1OC4wMjg3IDE0LjEwMjUgbAo1Mi44MTcyIDE0LjEwODQgbApoCjQ0LjM1OTIgMTQuMTA4NCBtCjQ0LjM1OTIgNy42OTIzMiBsCjQxLjIyOTUgNy42OTIzMiBsCjQxLjIyOTUgNi4xNjUzMiBsCjQ5LjE2MTUgNi4xNjUzMiBsCjQ5LjE2MTUgNy42OTIzMiBsCjQ2LjAzMzMgNy42OTIzMiBsCjQ2LjAzMzMgMTQuMTA4NCBsCjQ0LjM1OTIgMTQuMTA4NCBsCmgKMzQuMzM5OCA2LjE2NTMyIG0KMzYuMDA5NyA2LjE2NTMyIGwKMzYuMDA5NyAxNC4xMDg0IGwKMzQuMzM5OCAxNC4xMDg0IGwKMzQuMzM5OCA2LjE2NTMyIGwKaAozMS40MyA4Ljk3OTM5IG0KMzEuNDM0IDguNzcyMDkgMzEuNDEzNCA4LjU2NTA4IDMxLjM2ODggOC4zNjMyNSBjCjMxLjMzNjMgOC4yMTQwNCAzMS4yNjY2IDguMDc2OTEgMzEuMTY3IDcuOTY2MzIgYwozMS4wNTkyIDcuODU4MzUgMzAuOTI0NCA3Ljc4NTgzIDMwLjc3ODcgNy43NTc0OSBjCjMwLjU3ODUgNy43MTU0IDMwLjM3NDcgNy42OTYwMyAzMC4xNzA2IDcuNjk5NzMgYwoyNy40ODQ5IDcuNjk5NzMgbAoyNy4yNzAyIDcuNjk1MDkgMjcuMDU1NiA3LjcxNDQ1IDI2Ljg0NDcgNy43NTc0OSBjCjI2LjY5OTEgNy43ODU4MyAyNi41NjQzIDcuODU4MzUgMjYuNDU2NSA3Ljk2NjMyIGMKMjYuMzU3OSA4LjA3NjIxIDI2LjI5MTIgOC4yMTQwMyAyNi4yNjQ1IDguMzYzMjUgYwoyNi4yMjg5IDguNTY2MzggMjYuMjEyNSA4Ljc3Mjc5IDI2LjIxNTcgOC45NzkzOSBjCjI2LjIxNTcgMTEuMDA3IGwKMjYuMjEyOCAxMS4yNjc4IDI2LjIyNTQgMTEuNTI4NCAyNi4yNTMzIDExLjc4NzUgYwoyNi4yNjg3IDExLjk1OTggMjYuMzI3NCAxMi4xMjQ1IDI2LjQyMzEgMTIuMjY0NCBjCjI2LjUyMTYgMTIuMzg3NyAyNi42NTY1IDEyLjQ3MTggMjYuODA1OCAxMi41MDI5IGMKMjcuMDI5MSAxMi41NTE4IDI3LjI1NjkgMTIuNTczNiAyNy40ODQ5IDEyLjU2ODEgYwozMC4xNzYyIDEyLjU2ODEgbAozMC4zOCAxMi41NzE1IDMwLjU4MzcgMTIuNTUzNiAzMC43ODQzIDEyLjUxNDcgYwozMC45Mjg1IDEyLjQ5NDEgMzEuMDYzIDEyLjQyNTggMzEuMTY4OCAxMi4zMTk1IGMKMzEuMjc0NyAxMi4yMTMyIDMxLjM0NjUgMTIuMDc0MyAzMS4zNzQzIDExLjkyMjMgYwozMS40MTkxIDExLjcxNDUgMzEuNDM5NyAxMS41MDE2IDMxLjQzNTYgMTEuMjg4NCBjCjMxLjQzIDguOTc5MzkgbApoCjMxLjYxMDkgMTUuMjU0NyBtCjMwLjUzOCAxNC4wMzE0IGwKMjcuNDEzOSAxNC4wMzE0IGwKMjYuOTUxIDE0LjA0MDcgMjYuNDg4NiAxMy45OTYgMjYuMDM0OCAxMy44OTgxIGMKMjUuNzEyMSAxMy44MzIzIDI1LjQxMDcgMTMuNjc5MyAyNS4xNTk1IDEzLjQ1MzcgYwoyNC45MzMzIDEzLjIzMTQgMjQuNzcyIDEyLjk0NDUgMjQuNjk0OCAxMi42MjczIGMKMjQuNTk0MyAxMi4yMTI5IDI0LjU0NzQgMTEuNzg1OSAyNC41NTU2IDExLjM1OCBjCjI0LjU1NTYgOC44ODYwOCBsCjI0LjU0ODMgOC40NTgyNSAyNC41OTUxIDguMDMxMzMgMjQuNjk0OCA3LjYxNjc5IGMKMjQuNzcwOSA3LjI5Mzk2IDI0LjkzMjEgNy4wMDEwMyAyNS4xNTk1IDYuNzcyNTcgYwoyNS40MSA2LjU0MTgxIDI1LjcxMSA2LjM4MTg3IDI2LjAzNDggNi4zMDc1MSBjCjI2LjQ4NzMgNi4xOTk0MSAyNi45NTAzIDYuMTQ5NjggMjcuNDEzOSA2LjE1OTQgYwozMC4yNDg2IDYuMTU5NCBsCjMwLjcxMTcgNi4xNDk2NyAzMS4xNzQzIDYuMTk5NCAzMS42MjYyIDYuMzA3NTEgYwozMS45NTAxIDYuMzgxNTcgMzIuMjUxMiA2LjU0MTU0IDMyLjUwMTUgNi43NzI1NyBjCjMyLjcyOTQgNy4wMDA4OSAzMi44OTExIDcuMjkzODIgMzIuOTY3NyA3LjYxNjc5IGMKMzMuMDY2NiA4LjAzMTQ3IDMzLjExMzQgOC40NTgyOSAzMy4xMDY5IDguODg2MDggYwozMy4xMDY5IDExLjM0NDcgbAozMy4xMjAzIDExLjgyNzkgMzMuMDU3MyAxMi4zMSAzMi45MjA0IDEyLjc3MSBjCjMyLjgwMjIgMTMuMTMyNCAzMi41NjU1IDEzLjQzNjMgMzIuMjUzOCAxMy42MjcgYwozMy42NTY1IDE1LjI1NDcgbAozMS42MTA5IDE1LjI1NDcgbApoCjc1LjM0NzUgMTIuMTU5OCBtCjc1LjM0NzUgMTAuOTYwMSBsCjY5Ljg3NTggMTAuOTYwMSBsCjY5Ljg3NTggMTQuMTI4MSBsCjY4LjIxMjkgMTQuMTI4MSBsCjY4LjIxMjkgNi4xODM1OSBsCjY5Ljg3NTggNi4xODM1OSBsCjY5Ljg3NTggOS40MjI3MyBsCjc1LjM0NzUgOS40MjI3MyBsCjc1LjM0NzUgNi4xODM1OSBsCjc2Ljk5OTMgNi4xODM1OSBsCjc2Ljk5OTMgMTIuMTU5OCBsCjc1LjM0NzUgMTIuMTU5OCBsCmgKNzYuOTk5OCAxMi42ODg1IG0KNzUuMzUzNSAxMi42ODg1IGwKNzUuMzUzNSAxNC4xNTE4IGwKNzYuOTk5OCAxNC4xNTE4IGwKNzYuOTk5OCAxMi42ODg1IGwKaAowLjMwOTgwNCAwLjggMC45Mjk0MTIgcmcKL2ExLjAgZ3MKMSB3CjAgSgowIGoKNCBNCmYKUQoxIHcKMCBKCjAgago0IE0KbgpRClEKUQpRClEKcQpxCjM3NC44NTAzOTQgMTMzLjY5NTMxMiA0NCA0NCByZQpXCm4KcQovYTEgZ3MKMSAwIDAgMSAzNzQuODUwMzk0IDEzMy42OTUzMTIgY20KcQpxCjEgMCAwIDEgMCAwIGNtCjEgMCAwIDEgMCAwIGNtCnEKNDMuMiAyMS42IG0KNDMuMiAzMy43ODY0OTUgMzMuNzg2NDk1IDQzLjIgMjEuNiA0My4yIGMKOS40MTM1MDUgNDMuMiAwIDMzLjc4NjQ5NSAwIDIxLjYgYwowIDkuNDEzNTA1IDkuNDEzNTA1IDAgMjEuNiAwIGMKMzMuNzg2NDk1IDAgNDMuMiA5LjQxMzUwNSA0My4yIDIxLjYgYwpoCjEgMC4yNTA5OCAwLjUwMTk2MSByZwovYTEuMCBncwoxIHcKMCBKCjAgago0IE0KZgpRCnEKMCAwIG0KMjIuNjk1IDIwLjU4NSBtCjIwLjUwNSAyMC41ODUgbAoxOS4yNjA4MjggMjAuNTg3MjE3IDE4LjI0OTUxMSAxOS41ODIxNjIgMTguMjQ0IDE4LjMzOCBjCjE4LjI1MDA2IDE3LjA5NDIyOSAxOS4yNjEyMTYgMTYuMDg5NzgxIDIwLjUwNSAxNi4wOTIgYwoyNC44ODQgMTYuMDkyIGwKMjUuNDQ4IDE2LjA5MiAyNS45MDUgMTUuNjM3IDI1LjkwNSAxNS4wNzcgYwoyNS45MDUgMTQuNTE3IDI1LjQ0OCAxNC4wNjIgMjQuODg0IDE0LjA2MiBjCjIyLjYyMiAxNC4wNjIgbAoyMi42MjIgMTEuODE1IGwKMjIuNjIyIDExLjI1NSAyMi4xNjQgMTAuOCAyMS42IDEwLjggYwoyMS4wMzYgMTAuOCAyMC41NzggMTEuMjU0IDIwLjU3OCAxMS44MTUgYwoyMC41NzggMTQuMDYyIGwKMjAuNTA2IDE0LjA2MiBsCjE4LjEzMSAxNC4wNjIgMTYuMiAxNS45OCAxNi4yIDE4LjMzOCBjCjE2LjIgMjAuNjk2IDE4LjEzMSAyMi42MTUgMjAuNTA2IDIyLjYxNSBjCjIyLjY5NSAyMi42MTUgbAoyMy45MzkxNzIgMjIuNjEyNzgzIDI0Ljk1MDQ4OSAyMy42MTc4MzggMjQuOTU2IDI0Ljg2MiBjCjI0Ljk0OTk0IDI2LjEwNTc3MSAyMy45Mzg3ODQgMjcuMTEwMjE5IDIyLjY5NSAyNy4xMDggYwoxOC4zMTcgMjcuMTA4IGwKMTcuNzUyIDI3LjEwOCAxNy4yOTUgMjcuNTYzIDE3LjI5NSAyOC4xMjMgYwoxNy4yOTUgMjguNjgzIDE3Ljc1MiAyOS4xMzggMTguMzE2IDI5LjEzOCBjCjIwLjU3OCAyOS4xMzggbAoyMC41NzggMzEuMzg1IGwKMjAuNTc4IDMxLjk0NSAyMS4wMzYgMzIuNCAyMS42IDMyLjQgYwoyMi4xNjQgMzIuNCAyMi42MjIgMzEuOTQ2IDIyLjYyMiAzMS4zODUgYwoyMi42MjIgMjkuMTM4IGwKMjIuNjk1IDI5LjEzOCBsCjI1LjA2OSAyOS4xMzggMjcgMjcuMjIgMjcgMjQuODYyIGMKMjcgMjIuNTA0IDI1LjA2OSAyMC41ODUgMjIuNjk1IDIwLjU4NSBjCmgKMSAxIDEgcmcKL2ExLjAgZ3MKMSB3CjAgSgowIGoKNCBNCmYKUQoxIHcKMCBKCjAgago0IE0KbgpRClEKUQpRClEKcQpxCjAuNDExNzY1IDAuNDQ3MDU5IDAuNDkwMTk2IHJnCi9hMS4wIGdzCkJUCjEgMCAwIC0xIDM1Ni43MTM2NzUgMjE0LjYyMzA0NyBUbQovT0NITlVQIDEyIFRmClsgPDAwMzY+IC0xOCA8MDAyNDAwOGYwMDI3PiAxNyA8MDAyNDAwMDMwMDI3MDAyODAwMDMwMDMzMDAyYzAwM2I+IF0gVEoKRVQKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCkJUCjEgMCAwIC0xIDMwNi4wODQ3NjkgMjYxLjU0Njg3NSBUbQovVkNBVFdTIDMyIFRmClsgPDAwMzUwMDA3MDAwMzAwMTYwMDE4MDAxYjAwMGYwMDFjMDAxNz4gXSBUSgpFVApRClEKcQpxCjAgMjcyLjQ2ODc1IDc5My43MDA3ODcgNTE4IHJlClcKbgpxCjEgMSAxIHJnCi9hMS4wIGdzCjAgMjcyLjQ2ODc1IDc5My43MDA3ODcgNTE4IHJlClcKbgowIDI3Mi40Njg3NSA3OTMuNzAwNzg3IDUxOCByZQpmClEKUQpRCnEKcQpxCnEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTAuNyBncwpCVAoxIDAgMCAtMSA3NS41OTA1NTEgMzU4LjYyMzA0NyBUbQovVkNBVFdTIDEyIFRmClsgPDAwMzEwMDUyMDA1MDAwNDg+IF0gVEoKRVQKUQpRCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2ExLjAgZ3MKQlQKMSAwIDAgLTEgMzk2Ljg1MDM5NCAzNjAuMTIzMDQ3IFRtCi9WQ0FUV1MgMTIgVGYKWyA8MDAzNDAwMmMwMDAzMDAzNjAwMzIwMDI2MDAyYzAwMjgwMDI3MDAyNDAwMjcwMDI4MDAwMzAwMjcwMDI4MDAwMzAwMjYwMDM1MDA4YjAwMjcwMDJjMDAzNzAwMzIwMDAzMDAyNzAwMmMwMDM1MDAyODAwMzcwMDMyMDAwMzAwMzYwMDExMDAyND4gLTE4IDwwMDExPiBdIFRKCkVUClEKUQpRClEKcQpxCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2EwLjcgZ3MKQlQKMSAwIDAgLTEgNzUuNTkwNTUxIDM5Ny42MjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDI2MDAzMzAwMjkwMDEyMDAyNjAwMzEwMDMzMDAyZD4gXSBUSgpFVApRClEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTEuMCBncwpCVAoxIDAgMCAtMSAzOTYuODUwMzk0IDM5OS4xMjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDE2MDAxNTAwMTEwMDE3MDAxMzAwMTUwMDExMDAxODAwMTMwMDE1MDAxMjAwMTMwMDEzMDAxMzAwMTQwMDEwMDAxNjAwMTg+IF0gVEoKRVQKUQpRClEKUQpxCnEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTAuNyBncwpCVAoxIDAgMCAtMSA3NS41OTA1NTEgNDM2LjYyMzA0NyBUbQovVkNBVFdTIDEyIFRmClsgPDAwMmMwMDUxMDA1NjAwNTcwMDRjMDA1NzAwNTgwMDRjMDBhOTAwYTUwMDUyMDAwMzAwMjkwMDRjMDA1MTAwNDQwMDUxMDA0NjAwNDgwMDRjMDA1NTAwNDQ+IF0gVEoKRVQKUQpRCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2ExLjAgZ3MKQlQKMSAwIDAgLTEgMzk2Ljg1MDM5NCA0MzguMTIzMDQ3IFRtCi9WQ0FUV1MgMTIgVGYKWyA8MDAzNDAwMmMwMDAzMDAzNjAwMzIwMDI2MDAyYzAwMjgwMDI3MDAyNDAwMjcwMDI4MDAwMzAwMjcwMDI4MDAwMzAwMjYwMDM1MDA4YjAwMjcwMDJjMDAzNzAwMzIwMDAzMDAyNzAwMmMwMDM1MDAyODAwMzcwMDMyMDAwMzAwMzYwMDExMDAyND4gLTE4IDwwMDExMDAwMzAwMGIwMDE2MDAxNTAwMWMwMDBjPiBdIFRKCkVUClEKUQpRClEKcQpxCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2EwLjcgZ3MKQlQKMSAwIDAgLTEgNzUuNTkwNTUxIDQ3NS42MjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDI0MDA0YTAwYWMwMDUxMDA0NjAwNGMwMDQ0PiBdIFRKCkVUClEKUQpxCnEKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCi9hMS4wIGdzCkJUCjEgMCAwIC0xIDM5Ni44NTAzOTQgNDc3LjEyMzA0NyBUbQovVkNBVFdTIDEyIFRmClsgPDAwMTMwMDEzMDAxMzAwMTQ+IF0gVEoKRVQKUQpRClEKUQpxCnEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTAuNyBncwpCVAoxIDAgMCAtMSA3NS41OTA1NTEgNTE0LjYyMzA0NyBUbQovVkNBVFdTIDEyIFRmClsgPDAwMjYwMDUyMDA1MTAwNTcwMDQ0PiBdIFRKCkVUClEKUQpxCnEKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCi9hMS4wIGdzCkJUCjEgMCAwIC0xIDM5Ni44NTAzOTQgNTE2LjEyMzA0NyBUbQovVkNBVFdTIDEyIFRmClsgPDAwMTQwMDEzMDAxMzAwMTMwMDEzMDAxYjAwMWEwMDEwMDAxNz4gXSBUSgpFVApRClEKUQpRCnEKcQpxCnEKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCi9hMC43IGdzCkJUCjEgMCAwIC0xIDc1LjU5MDU1MSA2MTcuNjIzMDQ3IFRtCi9WQ0FUV1MgMTIgVGYKWyA8MDAzMTAwNTIwMDUwMDA0ODAwMDMwMDQ3MDA1MjAwMDMwMDI1MDA0ODAwNTEwMDQ4MTNhZTAwNDYwMDRjMDBhMzAwNTUwMDRjMDA1Mj4gXSBUSgpFVApRClEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTEuMCBncwpCVAoxIDAgMCAtMSAzOTYuODUwMzk0IDYxOS4xMjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDEwPiBdIFRKCkVUClEKUQpRClEKcQpxCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2EwLjcgZ3MKQlQKMSAwIDAgLTEgNzUuNTkwNTUxIDY1Ni42MjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDI2MDAzMzAwMjkwMDEyMDAyNjAwMzEwMDMzMDAyZD4gXSBUSgpFVApRClEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTEuMCBncwpCVAoxIDAgMCAtMSAzOTYuODUwMzk0IDY1OC4xMjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDEwPiBdIFRKCkVUClEKUQpRClEKcQpxCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2EwLjcgZ3MKQlQKMSAwIDAgLTEgNzUuNTkwNTUxIDY5NS42MjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDJjMDA1MTAwNTYwMDU3MDA0YzAwNTcwMDU4MDA0YzAwYTkwMGE1MDA1MjAwMDMwMDI5MDA0YzAwNTEwMDQ0MDA1MTAwNDYwMDQ4MDA0YzAwNTUwMDQ0PiBdIFRKCkVUClEKUQpxCnEKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCi9hMS4wIGdzCkJUCjEgMCAwIC0xIDM5Ni44NTAzOTQgNjk3LjEyMzA0NyBUbQovVkNBVFdTIDEyIFRmClsgPDAwMTAwMDAzMDAwYjAwMTAwMDBjPiBdIFRKCkVUClEKUQpRClEKcQpxCnEKcQowLjIgMC4yNTQ5MDIgMC4zMTM3MjUgcmcKL2EwLjcgZ3MKQlQKMSAwIDAgLTEgNzUuNTkwNTUxIDczNC42MjMwNDcgVG0KL1ZDQVRXUyAxMiBUZgpbIDwwMDI0MDA0YTAwYWMwMDUxMDA0NjAwNGMwMDQ0PiBdIFRKCkVUClEKUQpxCnEKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCi9hMS4wIGdzCkJUCjEgMCAwIC0xIDM5Ni44NTAzOTQgNzM2LjEyMzA0NyBUbQovVkNBVFdTIDEyIFRmClsgPDAwMTA+IF0gVEoKRVQKUQpRClEKUQpxCnEKcQpxCjAuMiAwLjI1NDkwMiAwLjMxMzcyNSByZwovYTAuNyBncwpCVAoxIDAgMCAtMSA3NS41OTA1NTEgNzczLjYyMzA0NyBUbQovVkNBVFdTIDEyIFRmClsgPDAwMjYwMDUyMDA1MTAwNTcwMDQ0PiBdIFRKCkVUClEKUQpxCnEKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCi9hMS4wIGdzCkJUCjEgMCAwIC0xIDM5Ni44NTAzOTQgNzc1LjEyMzA0NyBUbQovVkNBVFdTIDEyIFRmClsgPDAwMzEwMDUyMDA1MTAwNDgwMDEwMDAzMTAwNTIwMDUxMDA0OD4gXSBUSgpFVApRClEKUQpRClEKUQpxCnEKMCAxMDI1LjUxOTY4NSA3OTMuNzAwNzg3IDk3IHJlClcKbgpxCjAuOTQ5MDIgMC45NTY4NjMgMC45ODgyMzUgcmcKL2ExLjAgZ3MKMCAxMDI1LjUxOTY4NSA3OTMuNzAwNzg3IDk3IHJlClcKbgowIDEwMjUuNTE5Njg1IDc5My43MDA3ODcgOTcgcmUKZgpRClEKcQo3OTMuNzAwNzg3IDEwMjUuNTE5Njg1IG0KMCAxMDI1LjUxOTY4NSBsCjAgMTAyNi41MTk2ODUgbAo3OTMuNzAwNzg3IDEwMjYuNTE5Njg1IGwKVyoKbgowIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNS45OTAxOTUgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoxMS45ODAzODkgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoxNy45NzA1ODQgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoyMy45NjA3NzggMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoyOS45NTA5NzMgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQozNS45NDExNjggMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo0MS45MzEzNjIgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo0Ny45MjE1NTcgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo1My45MTE3NTIgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo1OS45MDE5NDYgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo2NS44OTIxNDEgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo3MS44ODIzMzUgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo3Ny44NzI1MyAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjgzLjg2MjcyNSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjg5Ljg1MjkxOSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjk1Ljg0MzExNCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjEwMS44MzMzMDkgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoxMDcuODIzNTAzIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMTEzLjgxMzY5OCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjExOS44MDM4OTIgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoxMjUuNzk0MDg3IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMTMxLjc4NDI4MiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjEzNy43NzQ0NzYgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoxNDMuNzY0NjcxIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMTQ5Ljc1NDg2NiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjE1NS43NDUwNiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjE2MS43MzUyNTUgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoxNjcuNzI1NDQ5IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMTczLjcxNTY0NCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjE3OS43MDU4MzkgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoxODUuNjk2MDMzIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMTkxLjY4NjIyOCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjE5Ny42NzY0MjMgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoyMDMuNjY2NjE3IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMjA5LjY1NjgxMiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjIxNS42NDcwMDYgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoyMjEuNjM3MjAxIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMjI3LjYyNzM5NiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjIzMy42MTc1OSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjIzOS42MDc3ODUgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoyNDUuNTk3OTc5IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMjUxLjU4ODE3NCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjI1Ny41NzgzNjkgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoyNjMuNTY4NTYzIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMjY5LjU1ODc1OCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjI3NS41NDg5NTMgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoyODEuNTM5MTQ3IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMjg3LjUyOTM0MiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjI5My41MTk1MzYgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQoyOTkuNTA5NzMxIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMzA1LjQ5OTkyNiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjMxMS40OTAxMiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjMxNy40ODAzMTUgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQozMjMuNDcwNTEgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQozMjkuNDYwNzA0IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMzM1LjQ1MDg5OSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjM0MS40NDEwOTMgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQozNDcuNDMxMjg4IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMzUzLjQyMTQ4MyAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjM1OS40MTE2NzcgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQozNjUuNDAxODcyIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMzcxLjM5MjA2NyAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjM3Ny4zODIyNjEgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQozODMuMzcyNDU2IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMzg5LjM2MjY1IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKMzk1LjM1Mjg0NSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjQwMS4zNDMwNCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjQwNy4zMzMyMzQgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo0MTMuMzIzNDI5IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNDE5LjMxMzYyNCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjQyNS4zMDM4MTggMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo0MzEuMjk0MDEzIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNDM3LjI4NDIwNyAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjQ0My4yNzQ0MDIgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo0NDkuMjY0NTk3IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNDU1LjI1NDc5MSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjQ2MS4yNDQ5ODYgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo0NjcuMjM1MTgxIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNDczLjIyNTM3NSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjQ3OS4yMTU1NyAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjQ4NS4yMDU3NjQgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo0OTEuMTk1OTU5IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNDk3LjE4NjE1NCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjUwMy4xNzYzNDggMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo1MDkuMTY2NTQzIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNTE1LjE1NjczNyAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjUyMS4xNDY5MzIgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo1MjcuMTM3MTI3IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNTMzLjEyNzMyMSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjUzOS4xMTc1MTYgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo1NDUuMTA3NzExIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNTUxLjA5NzkwNSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjU1Ny4wODgxIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNTYzLjA3ODI5NCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjU2OS4wNjg0ODkgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo1NzUuMDU4Njg0IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNTgxLjA0ODg3OCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjU4Ny4wMzkwNzMgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo1OTMuMDI5MjY4IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNTk5LjAxOTQ2MiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjYwNS4wMDk2NTcgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo2MTAuOTk5ODUxIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNjE2Ljk5MDA0NiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjYyMi45ODAyNDEgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo2MjguOTcwNDM1IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNjM0Ljk2MDYzIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNjQwLjk1MDgyNSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjY0Ni45NDEwMTkgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo2NTIuOTMxMjE0IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNjU4LjkyMTQwOCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjY2NC45MTE2MDMgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo2NzAuOTAxNzk4IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNjc2Ljg5MTk5MiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjY4Mi44ODIxODcgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo2ODguODcyMzgyIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNjk0Ljg2MjU3NiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjcwMC44NTI3NzEgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo3MDYuODQyOTY1IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNzEyLjgzMzE2IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNzE4LjgyMzM1NSAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjcyNC44MTM1NDkgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo3MzAuODAzNzQ0IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNzM2Ljc5MzkzOCAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjc0Mi43ODQxMzMgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo3NDguNzc0MzI4IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNzU0Ljc2NDUyMiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjc2MC43NTQ3MTcgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo3NjYuNzQ0OTEyIDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNzcyLjczNTEwNiAxMDI1LjUxOTY4NSAyLjk5NTA5NyAxIHJlCjc3OC43MjUzMDEgMTAyNS41MTk2ODUgMi45OTUwOTcgMSByZQo3ODQuNzE1NDk1IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKNzkwLjcwNTY5IDEwMjUuNTE5Njg1IDIuOTk1MDk3IDEgcmUKVyoKbgowLjA5ODAzOSAwLjE0MTE3NiAwLjQ5NDExOCByZwovYTEuMCBncwowIDEwMjYuNTE5Njg1IDc5My43MDA3ODcgOTYgcmUKMCAxMDI1LjUxOTY4NSA3OTMuNzAwNzg3IDk3IHJlCmYqClEKUQpxCnEKMC4yIDAuMjU0OTAyIDAuMzEzNzI1IHJnCi9hMC43IGdzCkJUCjEgMCAwIC0xIDMyNS43NTI3MzcgMTA1Ny42NzM5ODIgVG0KL09DSE5VUCAxMiBUZgpbIDwwMDI2MDBiNTAwNDcwMDRjMDA0YTAwNTIwMDAzMDA0NzAwNDgwMDAzMDA0NDAwNTgwMDU3MDA0ODAwNTEwMDU3MDA0YzAwNDYwMDQ0MDBhOTAwYTUwMDUyMDAwMz4gXSBUSgpFVAovYTEuMCBncwpCVAoxIDAgMCAtMSAyNzMuMzExMzMxIDEwNzEuNjczOTgyIFRtCi9PQ0hOVVAgMTIgVGYKWyA8MDAxNzAwMTUwMDE4MDAxYjAwMTYwMDFhMDA0NTAwNDk+IDU0IDwwMDEwMDA0NTEzYjEwMDFhMDAxMDAwMTcwMDQ1MDA0ODAwMWIwMDEwMDA0NTAwNDcwMDQ4MDAxYzAwMTAwMDFhMDAxODAwNDgwMDE1MDA0NjAwNDUwMDEzMDA0NTAwNDgwMDQ0MDAxYTAwNDY+IF0gVEoKRVQKL2EwLjcgZ3MKQlQKMSAwIDAgLTEgMjkwLjYyODcxNCAxMDk1LjY3Mzk4MiBUbQovT0NITlVQIDEyIFRmClsgPDAwMzQwMDRjMDAwMzAwMzYwMDUyMDA0NjAwNGMwMDQ4MDA0NzAwNDQwMDQ3MDA0ODAwMDMwMDQ3MDA0ODAwMDMwMDI2MDA1NT4gMjEgPDAwNDgwMDQ3MDA0YzAwNTcwMDUyMDAwMzAwMjcwMDRjMDA1NT4gMjEgPDAwNDgwMDU3MDA1MjAwMDMwMDM2MDAxMTAwMjQ+IDE3IDwwMDExPiBdIFRKCjEgMCAwIC0xIDMxOS40MzM0MDIgMTEwOS42NzM5ODIgVG0KWyA8MDAyNjAwMzEwMDMzMDAyZDAwMDMwMDE2MDAxNTAwMTEwMDE3MDAxMzAwMTUwMDExMDAxODAwMTMwMDE1MDAxMjAwMTMwMDEzMDAxMzAwMTQwMDEwMDAxODAwMWM+IF0gVEoKRVQKUQpRCnEKcQpxCnEKNzUuNTkwNTUxIDI5NC40Njg3NSA2NSA5IHJlClcKbgpxCjEgMC45MDU4ODIgMC45MzcyNTUgcmcKL2ExLjAgZ3MKNzUuNTkwNTUxIDI5NC40Njg3NSA2NSA5IHJlClcKbgo3NS41OTA1NTEgMjk0LjQ2ODc1IDY1IDkgcmUKZgpRClEKUQowLjA5ODAzOSAwLjE0MTE3NiAwLjQ5NDExOCByZwovYTEuMCBncwpCVAoxIDAgMCAtMSA3NS41OTA1NTEgMjk5LjAwNzgxMiBUbQovVkNBVFdTIDE2IFRmClsgPDAwMzIwMDU1MDA0YzAwNGEwMDQ4PiBdIFRKCjEgMCAwIC0xIDc1LjU5MDU1MSAzMjEuMDA3ODEyIFRtClsgPDAwNTA+IF0gVEoKRVQKUQpRCnEKcQpxCnEKNzUuNTkwNTUxIDU1My40Njg3NSA2NSA5IHJlClcKbgpxCjEgMC45MDU4ODIgMC45MzcyNTUgcmcKL2ExLjAgZ3MKNzUuNTkwNTUxIDU1My40Njg3NSA2NSA5IHJlClcKbgo3NS41OTA1NTEgNTUzLjQ2ODc1IDY1IDkgcmUKZgpRClEKUQowLjA5ODAzOSAwLjE0MTE3NiAwLjQ5NDExOCByZwovYTEuMCBncwpCVAoxIDAgMCAtMSA3NS41OTA1NTEgNTU4LjAwNzgxMiBUbQovVkNBVFdTIDE2IFRmClsgPDAwMjcwMDQ4MDA1NjAwNTcwMDRjMDA1MT4gXSBUSgoxIDAgMCAtMSA3NS41OTA1NTEgNTgwLjAwNzgxMiBUbQpbIDwwMDUyPiBdIFRKCkVUClEKUQpRClEKUQpRClEKUQpxCjAgMCA1OTUuMzAzOTM3MDA3ODc0IDg0MS44ODk3NjM3Nzk1MjggcmUKVwpuCjAuMSB3CnEKMTAgLTAuMTEgNTc1LjMgODE0IHJlClcqCm4KcQovRUdTNiBncwovVHI1IERvClEKUQpRCgplbmRzdHJlYW0KZW5kb2JqCjYgMCBvYmoKPDwKL0NBIDAuMwovY2EgMC4zCj4+CmVuZG9iago3IDAgb2JqCjw8Ci9UeXBlIC9Gb250Ci9TdWJ0eXBlIC9UeXBlMAovQmFzZUZvbnQgL1ZDQVRXUytEZWphVnUtU2Fucy1Cb2xkCi9Ub1VuaWNvZGUgOCAwIFIKL0VuY29kaW5nIC9JZGVudGl0eS1ICi9EZXNjZW5kYW50Rm9udHMgWyA5IDAgUiBdCj4+CmVuZG9iago4IDAgb2JqCjw8Ci9GaWx0ZXIgL0ZsYXRlRGVjb2RlCi9MZW5ndGggNDYzCj4+CnN0cmVhbQp42l2UzYrbQBCE73qKOW4OizR/sheMIGwuPuSHOHkAeablFcSSkOWD3z6j+YQDMdhQVFdXdUvt8v345Tj0iyp/zGM4yaK6foiz3Mb7HESd5dIPhTYq9mHZUP4N13YqyiQ+PW6LXI9DNxaHgyp/JvK2zA/18jmOZ/lUlN/nKHM/XNTL7/dTwqf7NP2RqwyLqoqmUVG61OhrO31rr6LKLHs9xsT3y+M1af5V/HpMokzGmjBhjHKb2iBzO1ykOFTp06hDlz5NIUP8j/cW2bkLH+28lps6lVeVs82KvMmo7kAVKIJsRrsK5EEG9AaqM3IOnYbTIAHtqHRU7uF8RhUOBgdHZU2lBXmQJ/WO1C3usgORTOAsyJOzoouhi6aLpVKTxZJFn0F7dB26ABfg3kD0tFtOpnVMa9mEZxMGnUNncfdbTjbv2LwhiyOLwcHhYOjp6LknZ9iy4G42d/bp2adhS45npPEzm1+Ea+HYmWVnmi6WLhp3i7vmDTG8IY75arJ4Ztgxg2PammkrUpttu+gMuhQiV25PE062ZHAWzpDTrTm1bQVd/UzQklx0PoXtnV+PYr3d58WF+zynY8sHnq9sva9+kOd/wDROq2r9/gV31gJYCmVuZHN0cmVhbQplbmRvYmoKOSAwIG9iago8PAovVHlwZSAvRm9udAovU3VidHlwZSAvQ0lERm9udFR5cGUyCi9CYXNlRm9udCAvVkNBVFdTK0RlamFWdS1TYW5zLUJvbGQKL0NJRFN5c3RlbUluZm8gPDwKL1JlZ2lzdHJ5IChBZG9iZSkKL09yZGVyaW5nIChJZGVudGl0eSkKL1N1cHBsZW1lbnQgMAo+PgovQ0lEVG9HSURNYXAgL0lkZW50aXR5Ci9XIFsgMyBbIDM0OCBdIDcgWyA2OTYgXSAxMSBbIDQ1NyA0NTcgXSAxNSBbIDM4MCA0MTUgMzgwIDM2NSA2OTYgNjk2IDY5NiA2OTYgNjk2IDY5NiBdIDI2IFsgNjk2IDY5NiA2OTYgXSAzNiBbIDc3NCA3NjIgNzM0IDgzMCA2ODMgNjgzIF0gNDQgWyAzNzIgMzcyIF0gNDkgWyA4MzcgODUwIDczMyA4NTAgNzcwIDcyMCA2ODIgXSA2OCBbIDY3NSBdIDcwIFsgNTkzIDcxNiA2NzggXSA3NCBbIDcxNiBdIDc2IFsgMzQzIF0gODAgWyAxMDQyIDcxMiA2ODcgNzE2IF0gODUgWyA0OTMgNTk1IDQ3OCA3MTIgNjUyIF0gMTM5IFsgNjgzIF0gMTYzIFsgNjc1IF0gMTY1IFsgNjc1IF0gMTY5IFsgNTkzIF0gMTcyIFsgNjc4IF0gNTAzOCBbIDc0MSBdIF0KL0ZvbnREZXNjcmlwdG9yIDEwIDAgUgo+PgplbmRvYmoKMTAgMCBvYmoKPDwKL1R5cGUgL0ZvbnREZXNjcmlwdG9yCi9Gb250TmFtZSAvVkNBVFdTK0RlamFWdS1TYW5zLUJvbGQKL0ZvbnRGYW1pbHkgKERlamFWdVwwNDBTYW5zKQovRmxhZ3MgNAovRm9udEJCb3ggWyAwIC0yMzUgMTA0MiA5MjggXQovSXRhbGljQW5nbGUgMAovQXNjZW50IDkyOAovRGVzY2VudCAtMjM1Ci9DYXBIZWlnaHQgOTI4Ci9TdGVtViA4MAovU3RlbUggODAKL0ZvbnRGaWxlMiAxMSAwIFIKPj4KZW5kb2JqCjExIDAgb2JqCjw8Ci9MZW5ndGgxIDM5MjE2Ci9GaWx0ZXIgL0ZsYXRlRGVjb2RlCi9MZW5ndGggNDM3Ngo+PgpzdHJlYW0KeNrtXAtYVdW2HmO9IHzA5ilaymbzEE1AEFF7+EJ8pGSm5gOV5+a5AQVUVMRHNx9p6jEVrAyJzAcZEpUZeYzSk5nHOoYdNfUYn0evIZlfPmFP7phrbwg995x7u/frfl/3m//vXGvNtcacc8wxxxxzLj7XBgSATrAEZBgfHT1x3PqEim0AxWvo7sMjo0ZEe6/1XkL5nZRf+fSzIWEZARW5ADiF8pMTLfE5zduMbwI8F0r5L1Pic3PAgQjFVAY6pmQWmJuv+9wGeMEHwGVIanJ8ku/AUa/Rs+8o9U+lGx3Xd/Wj+twp75dqyZsf0Ng1nPKVAJOWZGYnxvd17dOH6m8GCPa1xM/P8fKGAno+gOR9suItyY92HDoHYHMc3WM52bl5LWdhGrUfx58D75s0c3/Lh+tXznJ+/Cb0cASOM9e2reDn729CpdXCoh2qHTJI1hEksIHKOVjYIwCOk60Wuq7Wa2oHt0p+x8sFwshuIyjd/1yiPCqbpBpQAdRwtYSq7G47y9+CWXIlkQ6OsqwpkqSQvDykXeHx5hFJpLtPE2ruzB23Oliw3qYTh3IczG3NHL1fK3UDlLbPyzuhklJ5W94JLPIEyKbz11KDLp9A6TKlMkqrKMVS2mavi+cLKaXDv4DWF5w0b6hRL4BZK6fzPFtq0/Ee1Ej3WtbeV6YKajTqh3rOdtaCqMynsFHNByf4lVDNMEW3y0GYoh4g/S22PL/W2z8IFe3lHSfDbrUKKtQiXV5/Jt+ACuVTSJdPQjd6VqpGQg/4P4YCaHkgr/1v62w/Dr8FWm3fem7T/eAv+dbxEBAQEBAQEPgt9xGw4jeqt1xYV0BAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBA4PcJtRF6CysICAgICPw+wX8NVv+VWJmSu/13X91Bgf107gU+dOVERz8IgggYCNEwBiZCPCRDCqRBDsyFo3AR6uEyXG3ClhYAXbYnPAqRMBRGQwzJJuqyFphzv2xL/b9gbSu7vP3gL9X+KjxjZxa8qPNV2E09OwK30Bkfw/m4BT8nficFSEkPcJn0oXRZdpeD5RE6n5Uz7fw3+T35jOKsDFWWKpv+Kb8iWtVgNZ5YRvzAzp80b22kNp9YrJ3S7jqYHAb8jznSztT/knm/kkuIa+ws1lkuKCj4u+P7v4KXBAUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUFBQUF/z/T0SAoKCgoKPi7pI/+P91L2UlV09zBBL2gLwCa5ICAQIOnp5chMCAgol//yMhwD8p58Ltenp4e7pqDbNA0D3dPN0P//hH9AuRuZVh4NTv3hwLjj0dv1mNZ0ufJ9M+HHf/5dtnISTHXn3tuPDuJfdTgINQeG6xgpNarete7Rx+6XO/o2431ClHZRa3nRx/sP9xZHoaqMiLiseFsH7uKw4ZFDSeFoJLdkBXNFTpRxhggRfRzjTRqkoe7q6ywb0v+sLEYg5YsKWI3buPHZ8/iJzevscfOnWODqGQ5uyHdsZV06+8a0U8KNHq6erhLDuVLCBhUvPEPJexGIx45dw4PX7vJBp89y4bf5m1a2DlpIC4HlUoaDbLJ7WtMvV2XhMvZCfYi5pNENtZI9dIF/q0ASRizpTzrGukCO8dLfw2gl7Y/o7KsmIoW8mfQMkxqUOv4MwxHk9T5vPWnc2rdXQtIkNBSr4ao16EDeNFTlwCTr2Zw8QwP648uYPQBg36U96YtWpSevmhhOi5lh9gZdpodwiEYiAE4RGrALpcusSvs0pUr2IWtZRbciLmYhxuZhdq+DKAq1LaTrpdq8CflDMbrOJG9gdMxCyc2NaCTfHgUaqOaItgtKlEGoFwgjbpw25Mw6kNOejnQ4If7KNwdpBhpQ9OnknF09Nr8aacWLGMLsCMGLf4Cu7FL2A0vDlsclbZk3Fgc1btPw8kFJ/dxK6xqqVcaqd6elOFOpRh9da+jvvL6TRH2i/YNyQe2vMYq2IHcy7Mz61JK3njrja1lG15avXjGwZlz/paJJjSulv0DP9l0/rK/Pwb1j0xPNKfdmT5j8sxeQdjVx+ePh5a/RTaOJRuEkw0k3Z/QKBsN4QYTt4NBusGm4Y4hWFFXx162pivF1nXy3uYJ7N/ZdXTBMVzvbTRCEpV+xDayHlw38HCH+9UnrU/LH1vnPjo1FA0Yyt5jZ4ruLlxwNn7N9u1rnq3JVOvYpcsdO7Eff77BGvuGYUh09Kr8uSt79+GWIYs3Ugsab8EDjWhcpSRbD7BVUqC1r1p3uklRDvB5W0iauOq+YoIQUs2XT0lb+/584voZbaNjs66PH01lN/dfFJSOZublZWbMmcMWrVyNXUlNZ+z64sriV8idzrNz7NtXbiTGTktImBabKL06NysrPz8rO78oaHfRx0cOHyzaHdTr4/Xn6+vPr/8YJ02Ni5s6dVYcWTSddOqsNpK3+AFE2uwRqWkmX4jo1+rAvgHYqgMpfDx254SKQ4aordMuscs4EB3QD4ew1exA2iEsSjabkykZ0b137z/WhIVhhzM/oS+by4rZS2xqD6lx+fJlzz+/bPly/tUO+bQWSHZz4Fd8WFGnrERbd8xihVIQHpOCWKF1J5Z8iS7sulp3r7fkL03gtqwhn1hFZR3BABQV7QqaDG6tF3YfpRG3eaLr9Jkzp9d9n5efl/+9NGrRSvYdO2VdKg3DSPQyyxvHx4x7hn1mzU1IjI9nBZK3X+3av36j1tWcsJTQCJvJSrE0ct4A/mQcm1nCKOAGkFF4XONWU2PT/17IXmRjsRrzC/+envFV7p8bGv6c+1XGhMgBuB2T0YzbB0SyY6Oj2J0rl9mdqNHcCtQTbaDeEx5BDPbhRlLbyxb5NOqF9MTqhrt3rllv4maciOPmpZnNafNZJTFdqWqeffXC+Stois9LZnfe2sVuJ+fFc8+nmpWLVHMHm+e3skZxts6RUqwlUnnTWfLrc+wqpd22OMjLHKMyD7Uv01aCFbXKW1fYpaUnbJGRS9dQeCvio0TPWtYys/7M1jrZy6T3jct8zY7HPD5/IUnW0ExtQNMLy+y1qbda20beMPI690o90MImWC+yjWpdMyhwr7cCzfp3XzQumrkt+tpHgq8acmvopaNsrqytrdxXW7sPU7GYUWBnJSwFS5TTrLnhB9aMyg8NqKAXS2Kb2GaWhK9iOmbgq7ax0b3MCdy4TtyTFOqHsW2YaqQifAT70hJTz1gRLq3LWbAgR62zXv3Bar2nHGSzLElJmbqmrE7X1Bm6UZ2mNvVofMnnueaeds3XdWfrmBlLMIWU2PTtF9iHbWD1lbUHq6kL3bAYM7ly1I0NzezlWFapKdSN6y22Xtj9CXR/eviXeeEttU4Eii5ebkbaMZikCwVpaQVlrEgaS0uR27r1TxcO+ZqZ34+cPVMePC3FPIUtZbes5AxHTr18sI9r0VI2BXNzJvCR2kjzoQ/1JpB7bIA9MHh52ZcFP4qris1AgYG2wBamKMcWXk1d/fzU/PK7f2Fn2cmX2Pfr1mGHRYtfmL5y099OoA92XoiKuoN9Fjlg7PjHh3cxhn1Zc/un/hE4Yuy4iTHRY7sbQ/9SdeG6P2+f4oWarkeONi91UuOYgRUxF+6hTTFKFbf6FFqzDisLSd6/fbyN8DcYI3iQ03ULv2/VkspyZk9/Jnk1prEto6qX7j1NUdb35Asv5R6ZlHslD0OwE94ZOyZq3AZL0Arr0h3mGcfKDu9/eNLTwcFoePiRH7l2vNUIatW7vXV4hDC0ix1KxOiNT29+663NE7cMmfj2czQnduNkDJmyR3mCfRcW+s5rr70T1ped7dGDApQHMbIHXwl5tKadn4s+trzbejd4leFhnnK7KC3v4DuYMVX5J9gtdDqR925ZbkFB7pyCArlGmnK3oSwxFkejTBw9o/noztLSnTzZLKY6ke7u3E/Rw+j5gOI+oNqspTo1f9Tp1TWzrxUWkdW/Yu/gU+iLjvgEWz8vLnWZixRuXrx4eBRrCO2LEeiFrjiI1W40F+Zn8X6waLWzUkC96GmLqPpyQ13wijDaVpzWpVlut0jKO6g/x9nP2PF4ftUY6t8eVpP2WeLM6umV5Q3Zi+bn5ixadDAhFoffa8KhsYk7mg3sBqv3MaJX/4it5bJWvnnr6+WbNpdzz6igg6vGvxht50MVaGZbeVLimko1d/YdH83dAA7VZBHuQeQhYZ4eJPrLnsposJncYN9b0MgeiPoo55MvaP+I0THmbIkVD5mQkkPZ1GF7UvKq5B2plsZ662RpVKeHu87L2Pm69Yw06kDGrtesp5W48llxOdQmaae6Upv6imCMoCYCAx5oRXVlxZ1cPEYF5yzhOj/zflbtUWm3dXI2vrIhq6sp8O0Svb6EGY32UQ2k+uxxsp1J28VJ6ZN5hYXz8hctyqeINIJ9xC7QtuJDHCkv3LN9+x6eENjnrIH4OQ5Ad+IAbkk2WZ1Jdes+6d+mIK+RJphbu8YkV67pmOr8E+jEbp3Iry7PXbgwl/yyzFqtOZGq7ANmJX4wQ47c9frru3SXtFlDbqAWDJR50AxeckPIjJDVm3jNI94tdO3VUw7x9Nj3prVZiduflSyrVJ72OEoClX8gWin/sIm1RSt9DL1yT80yJz4VPxjdDrI77F72tcKMi3lp6aMtg3889HNz4hmaptdDQ8Mjegd3eMhUuufdapMJXfr1GzQwNKSTY/eyN6squnPdaRbJ5eo2vn7o89VAxgg3UKsRtIMNN0jhOJutezJ2Pzv+zb6qKnUbq20B5h8T2QL7vsGzCPgkr6WUxk9T4nhEcaOeu/PlwsumdVsQCCjFVKmzwXMkeQT34Wfes9Qew2qpImc6uxa8Yl43U0BFiRTUVFrGfQKhB/mYN9Wp71qRb7x60AbFCz0xhY1k85S45nuy1lRKG26L0iiXaWb9/cdI7z8r6DVh3Weama3k23GNZUvHaDWmHhr1l01SJTCwzaTStEGRC4tCzf0w7FnjoKG9+zyZHjJreqdOxS7OwT27Tni8pcW2T3HIcA3g0cDFwctZoQ0U3dejt2am+1H8PswF2ka33R/Yel/a1nqfZfO4S/ejdfkF/Ctwm7zqpNczSpdfCaeBW3UF9auA+qXZ3usCHUy44gZC1Z/+VMU7d/Eifx9Vu8mx2kDggxlIs5A7j4dJ9xEv+whEhOt9lqRIRQvx9gt4MWWG3+igJzz9nf168uvh6kR/Senx5GOOK1/u1r23s8uQgXTVhUch2iipw/Qo5G17W5M99AZad17kItwf5dN8NRpz5KlBEmNbWAbbUln55SkeoNDvh8iomKZSOa6ZEkLMB+9QRVYasZYY9VbriLFwGrH6z9Rb7A7/qtwBpvEv5RXaZ2Go/hcFfo3gSTnbtQSOGG2/lsEHY+zXSrtrFbpglv1ag+74AgyHbMiBApgDaZACqZBHO/OekAhBdA6DUGI4XSWQhA8MI5k8yKU0B5IhHizwKN0dDVkkH0xXQyGT6AMT2urK1XPJdE6mMnPpmESSTv+NVvu3tcq//Z9LbaVTmSyS5nrEU5lf12IUXaVTucmQTxKJJBuv15asl4jXe+RDtWTRMYdkEqjeNJLzofLZ1Hq8/uzBep7Va8kljbJJPumfPPVpez5Z1yqX6srWWwoj3cIh8r5yraX6tJWy/VICoeWv5AX/OWj0QaJ5I+uzhHBmRfY6/Xxt24q2M3/Ssa0E92H+6wsORKR1piMdnemtEqErrQuo/wID0hjz9+W+pCWSnlF0jKY5iTCGiDCWiDCetEaYBFPpyH/zAOENIsKbRIRdRL4iVAC67XXbC9J/ABH+9soKZW5kc3RyZWFtCmVuZG9iagoxMiAwIG9iago8PAovVHlwZSAvRm9udAovU3VidHlwZSAvVHlwZTAKL0Jhc2VGb250IC9PQ0hOVVArRGVqYVZ1LVNhbnMKL1RvVW5pY29kZSAxMyAwIFIKL0VuY29kaW5nIC9JZGVudGl0eS1ICi9EZXNjZW5kYW50Rm9udHMgWyAxNCAwIFIgXQo+PgplbmRvYmoKMTMgMCBvYmoKPDwKL0ZpbHRlciAvRmxhdGVEZWNvZGUKL0xlbmd0aCA0MjkKPj4Kc3RyZWFtCnjaXZNNi9swEIbv/hU67h4W27IkZyEYyvaSQz9o2h8gS3Jq2NhGcQ7595X1mF2oIYGHmXfeGWlUvp2+nqZxFeXPOLtzWMUwTj6G23yPLog+XMapqKXwo1t3yv/uapeiTOLz47aG62ka5uJ4FOWvFLyt8SGevvi5D89F+SP6EMfpIp7+vJ0Tn+/L8h6uYVpFVXSd8GFIhb7Z5bu9BlFm2cvJp/i4Pl6S5jPj92MJQmauacbNPtwW60K00yUUxyp9nTgO6euKMPn/4koj6wf318YtvdYpvaoa2WV6hQwkM8kBaohVUA8doBZSmaoBnYPQyV2nyKwhD1nIQE2mBtKQRKfQHXBwnhjuCnd5gDRVcNe4p5Zy7JUYM2hmkPgp/HrOZYAUDgYHRRVDFWWhNpPmzAxnpujF0ItiBsMMmlhLTOPQ4qBrMgM6OjP0YrmjgJ+lz0CspmZDzZrOGjIVmYabVlQx+01X3NF2nnXT7+7mM87EzX5uzKH3Oajb7huEVtJ5AylIctvpwLbV3HdwW9LtLX28AHePMS1/fnB567d9H6fw8SaXedlU2+8ftPbr7wplbmRzdHJlYW0KZW5kb2JqCjE0IDAgb2JqCjw8Ci9UeXBlIC9Gb250Ci9TdWJ0eXBlIC9DSURGb250VHlwZTIKL0Jhc2VGb250IC9PQ0hOVVArRGVqYVZ1LVNhbnMKL0NJRFN5c3RlbUluZm8gPDwKL1JlZ2lzdHJ5IChBZG9iZSkKL09yZGVyaW5nIChJZGVudGl0eSkKL1N1cHBsZW1lbnQgMAo+PgovQ0lEVG9HSURNYXAgL0lkZW50aXR5Ci9XIFsgMyBbIDMxOCBdIDE1IFsgMzE4IDM2MSAzMTggMzM3IDYzNiA2MzYgNjM2IDYzNiA2MzYgNjM2IDYzNiA2MzYgNjM2IDYzNiAzMzcgXSAzNiBbIDY4NCBdIDM4IFsgNjk4IDc3MCA2MzIgXSA0NCBbIDI5NSAyOTUgXSA0OSBbIDc0OCBdIDUxIFsgNjAzIDc4NyBdIDU0IFsgNjM1IF0gNTkgWyA2ODUgXSA2OCBbIDYxMyA2MzUgNTUwIDYzNSA2MTUgMzUyIDYzNSBdIDc2IFsgMjc4IF0gODEgWyA2MzQgNjEyIF0gODUgWyA0MTEgXSA4NyBbIDM5MiA2MzQgXSAxNDMgWyAyOTUgXSAxNjUgWyA2MTMgXSAxNjkgWyA1NTAgXSAxODEgWyA2MTIgXSA1MDQxIFsgNjg5IF0gXQovRm9udERlc2NyaXB0b3IgMTUgMCBSCj4+CmVuZG9iagoxNSAwIG9iago8PAovVHlwZSAvRm9udERlc2NyaXB0b3IKL0ZvbnROYW1lIC9PQ0hOVVArRGVqYVZ1LVNhbnMKL0ZvbnRGYW1pbHkgKERlamFWdVwwNDBTYW5zKQovRmxhZ3MgNAovRm9udEJCb3ggWyAwIC0yMzUgNzg3IDkyOCBdCi9JdGFsaWNBbmdsZSAwCi9Bc2NlbnQgOTI4Ci9EZXNjZW50IC0yMzUKL0NhcEhlaWdodCA5MjgKL1N0ZW1WIDgwCi9TdGVtSCA4MAovRm9udEZpbGUyIDE2IDAgUgo+PgplbmRvYmoKMTYgMCBvYmoKPDwKL0xlbmd0aDEgMzg2OTIKL0ZpbHRlciAvRmxhdGVEZWNvZGUKL0xlbmd0aCAzODE0Cj4+CnN0cmVhbQp42u1cCVRUR7r+/7s0blEaGtAkSmOzaFAxtkDEqInbIEGfW9Sgo7ZAiwtuLW744paIOT6DSsTRKBoCyiPIEXQcMOpoNCIuiQ5hZnCZRBnFJC5Mxi1CV7+/bjekMTNvzJm3nJdX30fdW1X3r/qXqr+6PcfbgADQGpaDDJMHDx49dP2UgiyATf9Gvc//YuCgwe0mtXuN2nnUXjn01dHRzfuZ3wLI7ELtB/8yKqzHtPr8lgCYRO0x8cmWOc9+Kn0OMHYOtU9MtdjmgAcRNi2ndqupMxdbPzAVHQBYTe1nWiUlWhKM8dF76NktKhFJ1NHikN8Dmi+Q2oFJyfMXVR5+dim1jwK8Xjhzdrzl8YAH1QDjegJ0i0m2LJrj1xXm0/NokjfOsiQnhtzucwQgg+zHL+bMts13XII40j+ZPwfuqzSxpM/4mq8mtXn5Pvg3A46Lt7PS+P3afdhrt7ExapXHDGo2AwmcoHEeyaw9gC7WbnNUqVXaTG7w3sd7/AKhO8WxP5WmzyVqo9Ia14MKoJrVLTRlB+dd/gNYJS8SaamT5WaKJCkkL7/iNni4dVACvALGOtAZmAG3eiRjtdMmDuUcWBvVrIWfBJLPkqohge6XpGKyzA/SqFylkkllG5UEKllU0qnkUVlLZQXJ1v69OdXF4KndM8Gm6wzlamsob6JzApRLExyZTcbUO2WUCijXxYJN6zNA2o/mToU+/8gnpQZSaexBxQpz6T5XuQVzpQsQxuua/l5w7EfzepH8dedzDjkGDmp3E0TSs0L4X4ACaHuibfqv1kFrkf3fYjutQZO29YfYPtX46z9NXkBAQEBAQOB/6vsJHBBREBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQEBAQ+L8PdRWEiSgICAgICPxcYXf+oif/VVmZisH1O7EGUGAv3TuBkWrN6BoFr8IgiIFhMAJGwTiYCtNgNsyDFDgH1VADf60DhwP4L9p2IckBMIQkh2uSFpKcRZLz3SUd1f8JP3GybdGTv2n7T8AT2kNniCS734RC+AY9MBIX4Dt4Xmot+Tdhb+IMKUP6yMUS6TMXb0g35ObyYOKqRmb/iBeVFkqEYlV+pZQoD5WHavNGvqCO0ZhCzFQP/hM85eLXT837T08duNjq79BPUFDwZ8SBgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKCgoKC/w+4SFBQUFBQ8GfK1QCAkOXwwuPAQAWINPvIJu/aipwVI1kBO4qv8OcJ+KW0TFrF/8+8d4BPQIL0nP26tCqHnlyix4U0UtZGmi5VVDDGR4Cjv1SsVvJ+NKNJapZvf5SvVn6fDBKkOaqVdLUWWoIfPe0o6T29zD289J5SSA/Qe4KpI79Ka7dt305/27fXYXP2sK6OPcTm6nB2jp2lco4mNWNPNO9kNraapTEbrsPFuATXke6rAEoc6W5BNgXo1fAgs56MZhjDtmDiaYypz8lXbNEl0Y8r80k6k6RjyJrnAYJILDwCIiMiwnsGmzrqPMIjIsw9FB+DzkMH+I50rD6W9JgtQ3evnlSxaMkX426iYdD4duxefn7+QtwQlbx5yMLM/gPOvtjj5icTcue0Z9/S/NvIWxvN34l89fX1MSgBHYNDwn19zT00LaZwV8Vdndxvw4fsPLs5sWz66FPJR8pKcwsPbMr68Fejjsyzlb9xA1u9Kwf5n1h/5bugoOMv9shMf2vTroVzbKmBwfuNxgvFSz/ibzgkkF85FAUJniHNGCCb9bRAepM+IFzWMQlZOKusLLdPVIPqq+Vz9eY8thMnH3fuhmolgUa2d662nlsFPgZoajjZe0VuZ9/ZZVyXxxjIvmB3Jx5Pijs6Y8/p03tGfDBarcxnG9u0YXe++Qu7bzSeebH7gW3bDgQGkz3pNH+mtv6BfP11PgbXnOgTTPNKcoNCk5HvhIAevlLOmh071lDB5rHvx56qaNO7eMZVVFntNWZnd3A4Phf7vtz7YPYHH3/8QfZBaXFJYDD7jt0d+0t299sb7Bttb0zB3A7cuzyKSxJ5p9O8QxMG5MlH7dcqkNnNauWYxyvUUNq1a8nGtZqNJv5mpLuVQcHB4T3JQl++L7QVNXUMpB5vww+hkdauz81dv35XLstducHxpy/ZhhUbP2QPHz5kD3OiN6xamZGxctUG6dOtaWlb31+dtnWMsXj5vvPn9y0vNnY8mV5182ZV+km0zF+5cj4VitgKsiaNrGnLIxaprYGXt05HmRLeE8zOKHUMxgbtZOrV2G2vUZyiimd+xerQ8xrKqGdF7HrsNuzriqU/RQmfQa8xE7DNtzfQV8ukHWx8B2lzQyT5Pqol748rJoqJhzPH+Taqrajgma6YGEl4AqhJ2k5roe00nvBygGySDrE7UhBLvS71+t0a+6Q1lWprezu58HEoLmMraCVsjmo1hLxqR6P4yrtWOyLSh1xrWHo1xFqz0gGsFj0RVtZYp99+i+1hS3A1jlp9W51SOWkiK2N/ZFWsbOKkiuho3IFTMQl3/IKsKSe79pJdzUBPGvSuOAUFOO8BmHEPw9GfXWVnWH8aV4yZLIkNZxY1rG4htsVu2AX9drHNbDl7k2WSvTQf7YlK2hPOvHCVcnmv/VmpzN5LelTfl2/7wfn26nynPGY4z0Bvs95Ufvq0Wvk4lDodmcyqPWmpPfHUuU6B8tPnqof2Wz2LxDLYd/fyMz9xzqLSxoTmXCt5oaeLqRw9pcwTrNY+/YRaWeevXH0cqlyt8wen18o6zWtvzWvnpggK4AeLYqIDADPYuq1b17GX8FQdInPUsdNqmP3zjWmrN+6qvnTlmj2PZrGxR2qVtv/b893PI2bWTmdvNIU0Lg+/SnLIZWZH+fJlPlk/bHHvSoDJk33K0ijpemMULrqgxrISdp3dYCUYjc/icxj9+HN25a4kYS5aeGKy8SyL1bN3eX7yT4ds0hzi2hXadvbz+/HRGRLCEzGQElGJtp2dlLtv4a4l1/7ArrCa6XeXp96at+dQ2tbUa6fR7/60i2rOp5ERyxfEJ/q3C606UPVV97DzgwaveXPWUv+2XY9+dPLPwVxzH4p074ZVQdrFdDjQ34oqtGFKFTNKUMUmsDcuSj5qpb1SCrWb6x9Jqfa35fY87qlkd1cllXIgyP28CI/Um8J5qmqHRoD7Se8rHfmyYMXsLaUlJf0OrSk4Y69DaffmyQdGJx6J+2utZLamTrFV7e8ca1+Rb7Ucyz581GvZ2m7d8kNC6rm+g6QvR2cga+mTCxvynlQin5t/nJLOEJ6u8vXdGzfu5sX+blRR6lmH42xqUVRpqRR2pqbmDBVpZIKFHWKPiIcsCXk0KUVjrqNariF/2rmvg9mVnR1d2SnXDNs+fN/Jk/uGbx82NPeXdvZ77Iq617OV8ILQ0Opz56pDQ/MDA7EvtkYvjDJxu2leJY5UeGp20352hsf5LcAX3Q5RObukJKpo6RmH48zSInsZOZCXR07IB6SJ39/KS7DgQGxGHGhhPi5HGuZfRnYb4DlueYBvo9FG1y720LzxUJbVF7c695vpZVPiz89g91gZdq6/hh4lUu6araWtpYlxR8p69ix8oQu+hC3QGwewKyc27y/M4rGhTwTpEfnAM8yHR8aHnwWUW+FmvsrSo73xQzGMXSjdu7fwsM6wZXhSfHp9mHwhfdjH2mfzXDZGiSMbW2rfCtzWzs9Tctvj7oHxCzfL2bmb3svNfW9Tbgljjy0FI0Zkjfz1/l7FSz+rr/9saXGvEqnPqcuXT5Vdvvwtu8a+bt9hX5cXDv92fPwUSkIZFYyaEp/PtR8jnYt1BueJzk8mfqIfKyEok+t26gxfk4d09CsJZKF2hpj0ThM1SW3nKgklS5duKigt7b8v5dhJKcc+QcrakXUkx56mTC5MTLjrWocUzUe/pp+fTb7l2d4r+GhTRkFBRi16sTu1f2F3US9/WVNeXnPzVNnX29gpdovdpqXpRStgwJeclskxNC8/04OfMMtPjvEf0mXb7tLSqINve3d7Xt7vpT9zxF5MRlnjVZVGR1IAvlOznH7xRSOryHvKTr54elyIqezt12yHD1dmp6WpWeyTdPvOd4Zt3fE7aXI69uXRKyS/xmmRoTTxpv3r9KtxIwdjIY/NnpKSAUUpx07h53hQ2mW37NhxJEdKrdtZYI2vlfPoY9Km3JFH6qyN35DXlrGDW3RWtoaemViKRKvErQzgBx+f1u3gk0ZHRixa0G1saMeYsN4vh3btO637G+NbtVqlb9O9W4exffibqdlkqr/HDK9g6ALg6eFnksMwhfq1U0oXSf0DqV8nZY3k0nNZCs916h3MpWEJpIPWz9dQZ6X+kVwaFtj47j+gtpdjdJFafoU4c8nkDL+fM9nMzjjU9/INeCY4UPpXyTo++JWgJi01LtLgPWRkWsbzAQ0VZ16p+bQzA5/IK7fc4ovlwR/whprfkGjMQ8u1wr3xIcH4fZOka0i8LZ06JcXzBEQ7xZ7Vqg+csZdNLLL0z1vUB+wRf3PWA+L4W8EKfd5id+09YV5H8KWWsy5BMxzsqstu/YpbXYW2OMxV14EBrTAAZsMcWAzzYBpMhSSYD0bK/njoTPce0J1optoUkjBCf5KZDzYq8yARLJBMq2iEITCL5LtR7VWYSTTSqjTMZdNaiXRPpDEL6JpAki2eQmtEo9bRpGkB6ZpOY2aRNLfDQmN+msaBVJtO48ZACknEk6xFmy1RG2HRPDJq70gbybIU0j2TWvHUSiC9ya73p5+cZ5Q2i40smk2cQb1cq017K3uW5ks3il9kk1ENY2TnK9GOP9LK/m3QioJE+13W/jVMuJg2O127385Ka7zzJ60aR3iTNH97vA19Q0LasYF0DabYIq1VV7q+SESyqSddI4gIvYlIFsbQNZaIMIIiiPA6EWEsjKNrOhEhl4jw70SEXxPRu8i7SHtrndvQAr6CmzAcXm4FHlc0Y1bSaT2ZcqfSaRyvu6OhjUmu+uv/+AVybE3zLniKN83jnLJabBvqbnM06Y9za8/7oS69BFDH4/1y49BO5GUL5yT88h/wx8AkCmVuZHN0cmVhbQplbmRvYmoKMTcgMCBvYmoKPDwKL1R5cGUgL1hPYmplY3QKL1N1YnR5cGUgL0ltYWdlCi9XaWR0aCA1OTUKL0hlaWdodCA4NDIKL0JpdHNQZXJDb21wb25lbnQgOAovRmlsdGVyIC9GbGF0ZURlY29kZQovQ29sb3JTcGFjZSAvRGV2aWNlUkdCCi9TTWFzayAxOCAwIFIKL0xlbmd0aCAxNDc5Cj4+CnN0cmVhbQp4nO3BMQEAAADCoPVPbQwfoAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAD4GPBEAAEKZW5kc3RyZWFtCmVuZG9iagoxOCAwIG9iago8PAovVHlwZSAvWE9iamVjdAovU3VidHlwZSAvSW1hZ2UKL1dpZHRoIDU5NQovSGVpZ2h0IDg0MgovQml0c1BlckNvbXBvbmVudCA4Ci9GaWx0ZXIgL0ZsYXRlRGVjb2RlCi9Db2xvclNwYWNlIC9EZXZpY2VHcmF5Ci9EZWNvZGUgWyAxIDAgXQovTGVuZ3RoIDE5Mjc1Cj4+CnN0cmVhbQp4nO2d/2GjPA/HGYENygbNBmGDZIN0A24DugHvBjwbMAIjMAIjMELeWLZBsmVI79rm1/fzx10CBtxYSLIs2+czAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAADwz0xD17ZdP926HuA56Ktd5ig++lvXBjw8bZkJivbWNQKPxjixL0MgUCRU/Y1qBh6Li7vUVB+7Isu65WDjpOj91LRtU+3d18+b1RI8AGPf1h/HIl+0UDuf+7RaqZ78gakt6NDHDSoK7p7JKaWI2pcgicobeZkVKsgUWDBKyfw/KdKUZW/vp9YVJIkqxvD6kWTqzy/WGNw5xsRN/sPC7uIuDSMrN+oSdZHFnTnT/UJVwWPwdpGHwXwwkvG2P9VtV2umrEhI1EWmzKl8+tFagjvk82O3G5XjB69i+lkptZdDh6CYOZb1+q0H4XKBJ2Yau4un1NgvRgntprjQ6XK8kYeMiBRBsWLNCa+hpp6ccWib6rhzztHBHjSik5VxYSMOVXC9kRB5qDdXj6kHTjnU1FNilVIZBgJ29myV6T2zVlE/mXfZZ07rkYJaF1fw2PRqFGDWNy7yHUW6+0XqZt4ilVSkPSnDFAsheEzai1Lyn8dQlN4Opvvmx+g6d7gJbjEqjlMZRgUUUxhf0f7d3wDuiVF4OE5m3t5PVRBTMgxe1LrghDkWHDqFAmJU2X6tJlXskYFH5CR69sZctSJxgEO2ybjR+SBPxFaOXKOaH2jWXSk97gDulLFvm9Qp0jqt/7pb93eMOJH1CwKWymWRyx7JWIjmkYE7pdR8agspqaWpI3MloTB5G8uUclkX2rlNkdI8MnA/9Mcin5XESfOpCeePzyWr9Xa3YXIjHDLkqVwWCQhE6sERVoRkIPtPKWaV1OLCbDg8LkxO8akjO65cNoUuuxa8SlcZ3JKLpzTGB/kr39qIwKCWynjJbt1F9mHyo7mIhTy1y/LAZe+2JCYyleBGJNwfriRcPClOAjBO1o7Hi7ShOYbXNDYZZXHPtMtMkYF934xLKcM64IeZxlHp31e6n8T79bMyCq6mYHlv1Ik/Ma23+2ybbNLc/FjtskMo6vl6b5LkW/lDwA8xNsfCmq8yMHMJ94f36+dsyyCNoKBL52wnA5cvpRazNhrzjEuIclkk6qd1LURyP6TPg2+lLzPOx8jOJSKEwh6aFif/R8geuVjjku1keFtv18WcDjl3z5RYZxNKkDG/K+kr7brNBd9JIFDkGk/z2YT7I/r15Nccpf8z5y+JbCchXzFMdER4SrksEvWN9JVi9Sz4Tj6dGOWH0+m0z51bNPrTCbdX2EPya0Kf2ikp6RYH2XQ+bcqf5+aUQhPOPVP6CEbUZQ+PsuzGs06TxYoO/B0Xn3v1/IcVodqX6k+BTOnuj+jXW7/G+tRzeMopKRkwsvIVpU3580J0WMhT6a3Fok5qKpESRb4Z5l39M8znboZEGZKovBWXFUKmFD/mHNhD59eM3P/xSkqGGM3RPI8MrT8vw+SnWdq0OGYWiXoTmt4Zms6gz3QA1xOsNrFrtUJk9faTPDhRW/r3XXd/RL/e+zWUnWJtDzVibT6JqGgfSZO54u3kTsvupTWlJuSpxTEVUS8TMmVv1Cp/P7ievohaTlnBhFr4FF9tZMr3nhKxzpwpidmvWXzqz0UtmGP+qpFXiNKmumFabhqEyUkujYxo43NlLOpuDugUlBzocB3/DeB6pj9eAbwznztO6y6Ut5+uL/J5WYFE1JmHAxa/xvs/Y7E0olAnJEoml7MfzzFh99K7Z9GI3lkXdWezxeHpM4NE/TPjzspTPfgDjVVawTS5Nkt5GCzjMjEeK+xhNqssGvL9OP9hsmEq0/uSumfmicLkFJ66XK1cpqYeWJm6CJUrPPVVDonaxKxcUn18fNTdkCigvKtusQkpQIVu0ySJ4VYRDmAtfiSZytidhToR8hXDzSlBpjmnd2SQRXVRH49eP5fHpU8ZrrwBiGU5pYVCBLo9pKOOU3B0LLPAzPXZNQFlzY85B/awXFSWdYX5NaIbl/DMPHF0nbpxRRlflsosaMUvROzH9BNfmV30SxGxUH2mFD115P7I71o5iebHnAMlwQXF2Z5FAkQ3rlp/ptK9rP1f2sjjCVFflpTyGurQp5/32px0kYp6zdSpqtK36OevRaQSVHT3R4SbhF9jh3yX1hbduMQoNK9hExyr/MsjDydE3Vausl2S/L1qp/TTXh33y7qe93jxqE6F9lsXqbfXdcpnOYh84QQ7VfKEkpB+zSCUlOzGBWGCELV7Wdo/M7wsV0Wd1XDtJDjb9/swymPKqoGmzZK/dM8b23zZX/HghPvDlUTg17TimxDdxCg0uzJWYs4920rCA19Ff7/Je+UOUrlqWcxZHxZPRAciKsUYneMkPN7itejVGXUyuc8bqlGY0xnrnm0m4YEvkni/beSm81/HNSXl1NRgP6uBHYVG9824koj8mp5/Ed04Ll8xCZ/bumfBZb0IvIOvk3q/bbLa5L616mu+UC4q51qR8iN4AcIervo1ohsXhwkECZ97WH9TwN+Rer/J9tXui9ZlCguXy8fqiucOupQKe7jq1wjhU0ehL32N3n5KRde7S59kuqKy4Csk3++SqSnTtv3KTZbhuKt9KXYJR0jkql8junFc5nn0trqu/uA7Ud9vAzlIjf287qqcuYnSMkZUFD/mHEhkwoVXShr5+ogWw58LbETXwbeStmmsH5fwRRYWE5XQPjG6MRJBy1UjKrpxbabjCvTxGkHgx1DDgESzWL5NkSoXy5Kve8ozulUTQysJF94iunF9LE0meut9KfCbpH0f6sP39PErInXIruvyVaosF9wOJ1x4B6/UOEtS/n7QFi4Dv4ceBiTeZpuo+z0MJlKs97f54GiGXC+etG5EheV0i+EnFy4Dv0dy6J3PtE11wmdYl4qmlPSJci2bdpwr6qyQOnNVlBf/DdwXaaNWza7M5igFb/vTipoqmBjVWSR7fzIpu6ui3EEp3SnpZjMmbE+fdL9noc+CMdxEJ7LlUmS3YGmXs9NHFjynzLDvzwOyi3SFp51FSoiMwqLP/Dd1gi4N1O7nr7ab9jHYb9OnsYRyoRbEkx6SdLMtIrXqH53DdPPklMljYNdcNKk4fny46abB1Ijm/VStPBbcJyISJKgXnVKtduPaQFRI/UQyZe2aeFRXZJLT9MXagztExKsFzJz1sSvNKMJbkOcdTCDpd1kcrxhPXKD2ySeAR0JPwjOUTKmUoZvD+AyU1NnPFiiWiIFbGyjexWx0+5nne5i4ZyGZZDtyzURfdNM3hP00Q+MUT/lR13VV5qt2bdxaCAY8FMkkW/KQJv+NZEQzkJSsFyswP0uKgamUr0Ke6SHqQlpEslzlGJbqzOVqyCCYTbmshwCenUQSHimpbvluFzwJJrC7lTfkwZn+9O7k6e3QTN9TW/AA6El4ZLiK6IgRqskfcatNyLXJJNPQ9z0mCLwYehLeLoskbfI9/rKqzWqYzucuhl+p5l0x3roC942WhDeVWjdOW2wiq6bfqOQ98Vnk2Hx2FSUJz652FweRzmMdCNULRicpnjLcuhZ3TZSE58KSiYVN20Pu+3D7l/S5T7FLACQ8CW8c2srpoXD5VsbUd22nrmH4LHQXV3HST9mc5OY3a/N40Fsnlwx/ybCkWTi9sx9NLzgxTG77KNVvVeoxeYt9bnUdvGfF7+aQLR5AlcUOpsXNxcEC+qvsAnnav0acO9rNIVs8ADtEqS2gb/1M7BS6zpxgQguX9dOt6/MbTHJW8oI97ZIDm+g6Pwd1ezXSl6amJcNfa27AFMlSbhdOt6cHd7APrzM67WMRPQBmZiUV7+ZwXqaahlsr2/zVzTlo4MmYhq5t235YLWQcyA99NwfD7FvJAqSksBDMa9F/lrMpO64s/LsxNdEoIur2iUwwl2SPiTsvRLhXaZ6MhqwuNORmENZh384qqa1l1sHzMAYCRVqm0cuuLjTkp6IF4anPzGYbpmeAgOeicy73+6m5+FL1obBf9ZGV1YWG5iVHSUZ9eGreaCs9AwQ8FZ/W1LE4bbT9LWN9oSGfnmFTWZvlAXSv5AwQ8DDQkMnHrrhQVstMLoGVqCDwb/dh1GRqY7U+o4j25zPfWpkCC635lJwBAu6fKR4yuVC2cUk7w7mPbnAKXWyPOT4lHzynZyxbK58W3ZSvXgvumtjftrasC8rZVPlRuQO52NHOptdsC2kj5H42/qKkNpdZB/fCNMXHRJbE29vyNRjSPWWJqV9ucY8+Omw87y5dmXyWOBpCLiampNLLMIM74mOXaxlKpuHF8ptDu3fWb2LFRuZFh5CLHd96I165y8QeJtmOKanNrQXAHWCHcfvouNbwbm2OMiiW7IPpa4S4MAG77aUP8HGs3DceXa+8ueXXVmdw13SRlFiihifaXDpIoy6PHqPqjtE9MhuvNGlTbCvevTstoutlJiVemQECfh/TdG2bysaqgkbzJBrP9u17XmolUESL+IUPNkKcH6O0KX8bEV234am9uCGS8G6GtSdL02kRgFkPRGqqy/QdIwfrM7Orm5U65Io7PWYqPt4ko+skwqO4FrHO29AXSqvF0SMKFuxLRU0lG4/6YY37YkRmWKlGpfg+QRJemDYVRNfHXChLc8XK88B3MrrNgQb7TVcFUVK3sSR1r6ipKdl45dLmm9FsdUCP9KbL5RzjvyO4Zy+CWEjC+3n4jmVEZ4/P9oSarm3cZtz/BZfXpKA0NZWnGo/14zZdG1XX7ZSnMcztJ/Z9CK8VB8D3McY7lmXMJpnXuRZpuI0pG0YlS2o/TU2lGy+frZm5br9WSVXXXZGEN6ZOIgnvBzlFwmSVUmtPK6qARs0Cycmtminjlko3fDXrpk2RUn2fa5LwUic3rgXXMI2jOoWmFqJEO5bxuTba69yFNoVkonL/BwYq3Xj9fJu/E6mrkvASIAnvH+k/3VpS+THKLGm9p6TvWKbm1JahmDReI8RqKt3wZM0G82k7f0kTqeuS8HQ2rgXrtKVQREE294ZrrL7OTdggB++3xGpqpfHesmvzlwatwHVJeOkbIjD1lyiRJREC2Ij6dZpERA2Sz98jNbXS8OWsR/JsvU+vBkyvTMJT2bgWrPDH+9uH0+m0t+ZPbvSi2ZQF9XUOtcqQiW0g5Aqh6cY7zSJ12PCWK1XjRC6dYP1dyVevBUns+orZvhndASWbez3qp9ukQAxbJhGRmko3/CJSxpKu7VRaZFrvbbvm6XcFsc6/ZEfy0/NDoz02iTJD+hba6xyqLiMb/iHRCHC68Q6zSG1kIvS6WJaqoIma6w+2z87TDwQpyOpFm3RQ0sCSWLIR9dMkog3clIJrsiK4X7rhF19KT18RVVQ87UTN/eYjq+/KgIW3/waKD9Tx8ZNQUxtRv4MiEaW8ZBQSFqqptMjmy63Z6ExMlzgpwwTLkNLHUnP9weAvoYQO7dWfCr4y9UbUT5EISiIYl++myavla6CmkvEhsnaD+1JKaxxUV49DUJjALlwmhpT29jQi5N/OZ5aYc3IeevbliohhJY6Q0uBCWEklEqipZHyo5Z4/qSndQz8GEiwqwiRpxj28q5rElEHwl4ROTYKNqF8oEXbXGSGqu8B5lg9OxofKLNxQ+aJz4mIfCfOdyLx525/UwuDfibpeCfTA0egzgo1E2FAlJXmX1G5iJbApC4KZtXhyKj5EAtEu38tIVKmUkdfspNZ8YpIkZuGAn+Fq7zRnSoalTQ32CEncvGCvsywDv74XeuwieI0QllR8aBeI2kTCk4vQvtvVXdlmwtfcKKUXW1PyduQJDyTChAn6Pkqb6uxZrgocwa4zFQnQGNxhkRa9Ip+BkvIylRUfvfvuNuJK78ENpfSrbAwHMw6aS7J0lt7CE6ETXWaql1z780ZShvCh/0mxs9T+2l1ZLispNOG14Dao470qp1gcjDkZ3GmrO1ymcKW0sS6RyywpzQKTbYx111BEt9kPYSFwI1bThazTNCwlnRRoPq6RuGqONRuVJMOOvZAjN7ugYE8/RVI4Hqlwq9TLT2/3AtUrZcBtqHWTwV2e1h6irmHax5URQ8oSFjFJkshwylPL1JTRSBW7wLtIrV7xsTm8W/muVlZ/Bb9PHPXu+ASYbFEjS5hAJYiuk1LiMfkyVFtEvtx/jmxRd9LvVYpB24cjNnxt6KY4QdlIwguj66E7ZURkUh/v1BTFUsNZOKmtzcD9khhI8S6TUWJ7e3w9sSiOru9M+YGfVnTctKgpJcgNF+kRiYfWRh4W5NkD6+loUXRdulOhp+RhakqKU354yb1Kn4CNobuRKZdd9rUkvIZZzeSCckxN2ciW7QwiOvm4kDmbkqd7pqW+nITH3akipeIWNVVXGDJ5CspVQeE5Tl9OwqMMJjt0nFaGk5kaOF1bW/AAGC2RniJwYnKScodY0VYeGmZ3aiPbCjwT1NEaU2e5vboiCa8OjpE7ZfLX49A4eF7KqM+3ICYkJOIAvGx0n6Nzpw6XXuT4b/UED8PaFIGCGzMlCc9uaj7RZzUtc6LRwO+pKHgYjJrSk88/pVM9dw6DTc0HOrsRXQcvBMUktYxII1Hc4zZhglombhIdnZ1MvP0XqntzxltX4AEgJzrWUyRRFTtQZjqNPf3kMaVFNbe3rsoDQIknRSuODSRAIj8lTMKjVJWnD3SHq29jc9qrsOl1TKj6YxarLpeE5/Pnpt+t4+8zVGGejwXr4l2DT9ksq7quq9K9kvtJFOpk/tzT02hW/qKa21tX7DFQlizLm1tX6sbwzLHkwukgTSuFKg/2en1SKCPaUHdTeM7EdrP3F1PN30t38lL1dnrykdxoSwCy+q0spE+wBl9j6i+8wDsZZUNbgl6vOTTdpH7g3hnFIjRnZ9NUoRpZqfU8VvCCsEWlgo6/S3R3OdHjReQaN5uaL+RQZtjbGBA0mi09pTCFwhwbgqtsKJctN7ORxwpegnEZzZYGLSin2jS7Semyl9LGVGzwtNgUmx0pIm19MppwH1yTsGmkqOYkVzUFDDwvQYqNm2TIRGltUamUTTOiNuefqilg4PmYrFLKI200mrPGou23R7OrhE2zUzAm+wUpYM+NUUqd+aAOvZkhk8Gc3cV+t0bSpvVMTW1MsAYPzjybopOiFKTYXNlLS6+rVTJvKo+d+GnosADxkzDPphicUjqc6jxWSRuzDT1pm9ZnixwxlacsjwQehKltPlrl+DziNi3juMrKecGiRMmnZMnxu3wRSnP/P/FgYHPFnwFujRnHHekThQE6pYg5PslDyvTAayehKjaN3dQJZaW7bdUV9we3gtuTjo6QTyxWTHco0UllAvTGuiHibspD3E2L5WPQBzBpU6N6HbgpanJJY8/RCi7KLLAy1l5Kv+3ajBTFZjr6pZ83JyyEK0KC+6KRK92F9mSX6TKlLbqQxaN3eWwfNdJT6tmUflJ5Tz9h4zGZLkqp9V/qSJjs1u6jPe1SAqKZhcqIm9ZvuzIjZWXRkCzj012RhHefiKGNJf/N2JNoyMT7xGG/TYtOLjZqJrU42hV3Yzftl4+TXgr8JlM0ribUiZGvIj1kMvvEf+RxbcRNUUmxfaTBQHloddEQJlJIwrstfBvFXCZyi6GNjaEzWi6GHCqx95B62S6LlgipZ4s28sHAUCOlKzEtvhSS8G6FPo4rErlz9rpvDJ2R/rCpSw0/rl2muOxGIss6SpuKNFKyEgOzdkjC+1WmyX86hO62g2mZXcbCQFy+YqxPbGWq5yeUy5SEgk6vS6SRkjatzRafHEl4v8d4UUqV/yIXS8jfD/u9/djM5UUYSMhXjNUStCqjCHkqlynDL2ESno1OdmP4lF0osfyvObjPSML7PU78t7YOtch4GylSMG9jJUdz02FGwukP6hjy8JRymZJQMDlR2loEJGXTaNlsfwJJeL/GKNwTdVyNtEztv4kw0Ea2QJlZn5gkla0do1ymDb8YiWy3FwFJJeGRJI/uC5LwvpXx0n1rEudOwj3RO+R1UupWwoz+5q2/Awt5KpdpCQUbZpXfTbFplNY5H19JWABfZ4j845ne2hb/VX+XJ+sTLTdb12oLi09Mkju3r3ZZnqnpCW367h7FZhr+cCUVdwl8oGTYfsCrMymHyBsatdKlFan5HJevBd6nEkMbK2FGA/OJ6UE+5KldpiQUbJhVXon4PfgUQryoPBfjKrzT324/4JWZTHSyjo/noX/s8SMqvT+gd8hLXoSrrI2hM+YTkxnywQjtMmX4ZcOselSb9ql1CUplamCz/YBXpk+oo7cs8I89/hdu/YGdaiJ3XNCE1HH5ImzalDvP7agNT/2XuOyfk/Dk3aYj/RJDcH+Fl197awM7Thu7qi6CGW0HQkrK/Pq1P6K6L1KplFydePkK0qbceTl6ky/6UFGGy/DLzIZZnQlt5vRJj8rFHzIPOFrWpgaChdL+XGN43L+hobAZCfgQHSa1Q/4pLhVSZ55YHqO0KX8+57VhOlSIpUWJRW6Y1RlmMy+eUuV+hcDxtjZe3SAcpElIzpLXJIdvbeBGdJi0DnkvxVQMbSTMSeVO74T+WEKeijLsFZVkyk8rfy+rxEcbjAbuR1lohFL6C0yrVEIxOExbHun3bvhhUlKyw6R0yJs8EyZJqJM6E4TmJAiTU2nj0ikjblr8Qu8sRASVIIHqty8D2xgV09eKnjGC4lICOln80mKiwyQ75MaMGIESiZliaGPDnIRhgMrdTLFyWvyizK5OwhOCXffbF4FrMC0wTYqashogGL4lEavPssNE8mWigHKKQhPdzEHyNZ1TRGGAY0bCpEUnFZUU2sdLd5IWw69ksX6WJZqrkK4O+Co5eSOKmnI9L/rp51jNp/8iOkx5bETEVV9PwjuImuzM1Z/aZeZMLw85+xjNwgndeKw7/UMMViVoasppADJ1LjxFffrGfBJBxjddpLii4vcX8qVXSfrc1vz+yeK+nOKyG4kslFk410QWwDfQONFQ1NTOKaJ6aZDTrChEkPEwt5tf/nJo7bH/wpsRivwylDDAOCub4DIlftGpwp2/nZIPBN/KwTWToqZmDXDydsM0tlMKIshoCpShq01iMEflRTdOyFeMecokDw1e6wSXKfGLUYgSZnX+OoVXO7GaWnpepWmcT66k4qhAFd2aZMqXEd24IEwQooUBfActuExx2SerlMzUQHhKN2CcmyRWU0vPyw7fNkxJySCj1r13ZXxmp+jGhWGCgDJTwgBubCS4TMYvXG0Qnbwl7dJKkZpiPS/ry+xY+4nulxbENpSLCIpuXBQmkCg+99nHJoPLRHwM3AOm9Xr7MVJTvOc1+zKdP2u++M+pqEC1yIDoxkVhAokSJvd1jZSh6Q2k7wR+nx0TjFBNiZ6Xiwzu57PC4eHyxWAGUdwsDhOkLosqi1DAnTNyKSE1NbCzoudlfZlxPrnLNpPwSA797fnNlDABVcD5QGL0hp9/35+axF8C7oROeCfGTvH0KCkogRITDo+QrwVu4CKtNs3FlqnmtsBGdB3cM5XoW1GPrl/OBj2vSmgiEWTUHWo67MuIm5F8RYvhi5Xw/u4P+gG6phpvXYcHYie0hQ1Zyq8tK11yB0cEGZUg9tn1EzvtZmWm4wqYWZ1/9fd8H1Pz4ZbEKrHUxheYAn83UFNhz2sa2RcRZFSC2GcRGb0iCc9EJ/voHjfiP+NXZuV4pmBwf+PaPBB9KAlSTaV6XoQIMipB7PP0kXEpisLtnq2p5rfAD+oU/fgnw7JlX6AWlm0aukqoqVTPy5bOkkl4dPqTfKTloLhZe+ebmptX6zQPhmOljesxLs0w8ZWiM66m1nteeRYk4bmL7N3cWz7OxcXNxjsfx93RmILLf9DmMoIE9IPFXk3vTq/3vEyvbfBfjHzF607z2QGTUUo/8Uf8BG9ukvFFW+Xo732BXnGShZoygjKmrjZ2ofNf3pTbBBuaPxJv+dtoP01bRaeureum63+0Pg9DwwXAzS4YuJraZSt5TcbfaPyXQyBO+XvVpy58AKYry/XVopZLbNvg5CCc8sQ7fat5TVESHt3tlTLe2jJ4kT7GW1fp1hi7NoUHeWxqNa9JRAUak/F2X4GAn2YMBcrwuX3dM5PIB2BqajWvyXhih5+p2SNAk18zs+1t2/V9c3IWkKKjL0siksnU1Gpe0/T0Smk0o9mTfu7T9kCa5XRvjf9LhxxEly04btXURl7Ts0MyUqunSKLCNYFsHOuVZcr8AKNyvJ/VVCKv6VUgCVmWRWa0Cdmh0YfXfQnTsfFyVlPPnYY7jX3fT8nTbqCvVs4UKW1Eg5d/lBMvQdpR6g+3Ty75aaZmHjT66PQinQuxTdGZU9q+nViH+eUQocoXo5cBgOJ/WiFjxfaamiLPoNXvTPPTopUDX4Tdy75O058onlT0cbGdmSytqalyrSO8eKIvx2SSS25diZvQO4uXX36A+rRPBSknEhye6+wgH2tM3t4I3PGbqwxuj0mxGfVT/1l5mscgp7ZQZaonx6CP1ZQJAO/Tj1auAI8PWR89c85KVDXxY7UmU5U1YGWkpsq0J0XkL2v5nhkrI6NyhlbIijwnO5laHjWSc9aUTr5q98Qca/A02A6d1vFKRJRIplpxyJu3UE2ZIYXV+O/qMBa4Q/rmoyyKXVmtrK/pXO4+OvGZ0l5NuEB173VNqKb4FGqVjZmtbvrilC4BfpPR7qHg+Oj1UqbV1fgQhb0b9Zoh+G6c8I4+BWpqdZKHQUz0YM+We0CHzwM3IQ4o6UlvJA6al9yuKxBOOauzQE2tTkUjsixK2R+KsObdddUAP8p/s4bK3/xHueeLw4jDVCtqqtjorDHyRfikmtLmLEo0kQoE6u29v64a4Cf5tK2xbygPeepd1puSSJmbdIApVlPxdMMkAxMcqaa2M34UkZr8q3DHkxefjOHiZpRleazjvdI9VqJ4QGlU40m20T9sJEGqKX2evUqTBUs41PNTdVdJPj4S3BdKyb8HpM9dtmohkqhwB1jrovRBUedZx2oqlXSoYIrOD5NqKs/W41Kb/jv4YcZj6LlqEwAp04TvSuMuLhSVcHBtHqmpXXZ1T6sQqkioKfOlWbnUDAtW1z0F/AR+WoAUqjEsVqgSRQpkP8RlScoiNZXHTk6CQWoaoaaayKDGVe2uewz4fuzyLsbnpvTKyc+1zDtZ7lOVM0PdhEfG2bMO1ZTiNydoMxky52qKT0tT6LZ8LfBPmFDxsHJ6RwJUT+yYSwz4TxQssuu3PW9nwxSqqetF6hRIjVBTRr7S6SvmLNZ6+TlWJ5e6bdF2Y3DUduQ6duQLIUohDoGaul6kjKhP/ABXU6tZdjTTYby2ruDLrE4utb240xQdp8g33xS+/IKS4gtvB2oqv7a1jW2zsSc+jCLUlLI1PZUvoKT+mamrPz7KY9X0ysnVUXl620/aGQo2L+qFAoXTtfXhnrVUU0bYhmvuYfyhMlrbSKoprbNgLTl/GcBXmT7L5RfP47kmq6HmIv2yG+22WMzNwX9OxxWjVFNXz+CoMpVZTdUJmbK+4VWPACqTiFEawpDSWqh51es4ZkG3vbq2UkYcuvmbUFNXR893oSy9HU67LIhNxV1QG3m9uqYgYhnGZQS5AebQpF9erDXwsj/p2UpJu1oVtrdVKZ4o1FS/IuCcyf8xfG0j0elzXdXPkV/1ScdOVzwAXH7Pj2P0Tv6xP/u+MqtTTUN7shImB03ekppoWFNSUr0kB1KWDYznhxpx4KZWqCkuXysY6dlFo7slV1PT0aqvDzddeeo+7J9fbd8enF0/ZpDHPqxS6tkhG1LK+aEyJQ2keg7pR05M4spIEka5Yi1TYn2g+4SaqrJ04HsqPnyeqB76CPKmav/ooiznxLpw5Q2Q4lO0GkE6KpwXMJFfmw/LkVPSZpUb1qxc2jXWUpH/3PgzdXhbrqbWIkrtYhVjEZ4P18vXcRdWIkw2fnXGoW1TpwrRagYSMqXPQ101ZiPrLLWejikYXy/v5NRNLJcNa8e3Hbc35aJP2XrZPTub6GQWy/PMFUqJaLJMt+fylD/08qQ/gWm3xJojJ/rJKnZkTEiU68ddscPD5kQTcmjsxyqSy25er3YMnmFu20brZfsKkdev/pX0jozzk/damTKqx9ie9jn1CKuVNWBeFbIl6lqTo20WLhlFlly7hHyM1n9LJg9txppY/CGWy4lvX8zdpz4yRpae1075Kxv2FyZjFpGaAmNbfZRlqQe6rS35TzljlRTvR62GlMi4zI/MEqNz2+HLxfz0qZtYeHCTW0Rnj953XG+WqkwJe22KdOqTios+0s+8JG5XF/c7x/OVOvk6LzglxRt1lzJnc/nWP3URDMlXRCreHV7QMHt0mP/EZfVt0enTVj+0M2/mcZT006ZptcavxXgK396ikyUGJ2xjeKm5shCSsRFSOmVX7PDwFZFSnJjweR17XLRxlohNuZ1hlneqt2MAcz91dRAJeNTcSRno9iHj0EWySkeELE0THdIPI39mcl+MQhuUQkmLOMNEqlktXCyP08VBjvT5zn9eftSXHqH7ZZYI7ZeGf16CS2cn/FFdqDfbN2YCCgt0j7yUl7qgI0dKSi5wZpRGu1IFfv6QKsvlTmNgYkQy0SUKtkzfJTqYMiHhXMcvGJt50z/96ttfJY+aSsmddIsq8aAkjZ2QeRTxZRcdFKGhLFvPO6pZw+qRaPe4fuUmXFLojol4ksj4TAzdhOmd40kK1X6tIi/FpB18iywNSVSYO2mdK+45UXPQUR64KW3L8tDQZkipY+YnaUaqDftyyMIkFT1q9smNYpEQduHe0Q3bQ+Hs34Gth//afBS5+utFL+of88Od4oIUomGvPikiq9GWTrYPF7BY9tfWLjE3OGiF+g3BlIqlkdVa+C9jSirpoI2ZohOnoW/X3P6XY5dwL06BpSGhqLQ71FIj1VSOlsRdblA4UeoyOaF7v1o3cwv3Mdl/IsXTJm/RBtJR6jJFEjVXhtdSctLPXC7YVe2UrMVrEQ98WepAgopUm7qAee+/OdfWdrL75RjpQu4sf0mkWBBceXrKP4qzqWy1/sjyNqC09DLC14ld3vF4+wy9VVmhDhq8HvHAlyXo9KwGunfcxfAeEK0I55ysuWEnJhlfEql0z24M3TbOZ1RtF6NslyNTU0iJ+vrC231d74VWfmkS/WU+3GooEpI3l13iyl4RtXNDMXnMF8n4UkhpJQlPKkkBBVODarsYZX5s+nEcu8ZFlJhEcbm/HnNfzOU0pPwG2eBdFgcvGSVTU8vYiR3xmoT1YR3JKal4HNxKroyYkdumTiexSx2Ej4hHAC7w3c3Gv1sdpVnR4y9FUldwFUHexUoGP3W7Jvdl0SfkYpQ2aG2PiI7kl0JKKZ/PPT1ajeXspwWMyo2LQKC+JaB0yrDOIZHU8sLSFButn7Pzu+WnJX1w5EaTe76nNWN6DtYuqVcKkzqM+nF29KjRLjj3LEiZn3q1zPWcPvpp/Ny04y8D824EOyYlizFLUAVS07rrdq7ZZqPJO5Lths8i5Djl8813DaZqdfbRdeIKs6RwfTqd6rW1Fq5lVnrNv9/rGYjD5BZuaTY7Z7zB+djJ5H7tViuorFkY3lN6c+kqNE5yPzrjcw+Nm2eiLsH5/XiRqn/lafdPYjxLKJ5k7NrDI5Fi7MT12eeCoiMZjW8ICqGXNvqHY+gekYs0rtX5+xjb/dvb+81zxs3csebGdSBScT0+drJqdQzpsZNgwwIhGf2asSDFM85fVds7sc+Rz62tgveM2EX13dyxu/DmwjC5h0cXrhIp7xYFYyed/DuFZBhxFmkM8o7imfkiYbQOiplpcBCXtPtFnvLnzwqYfwXBrWtlSIkLjwp9SaTCsZNGdP5FR5K8KTXeFe/7uzMaLZjKGb6TU1dXF5+7+g6f+87hE1o5460rdo7C5Od5PjeTjC4qEyCikuYvm9jJhpc0t+3nb12my5QYIbQclN/vhaPVb9FvYWePTbeu2Jl7N24OJBf/aSmzOVtu77+kx07OUciSuv9Rx8yGlGpxrIoE6m1/Wv/TngG3/VARWrQd+xXcfIv7wdQrtsmWwZXJN1SqkYyD/1JmK2vhhsPUNqRU9uyQ24W6Ftct86CWyZzPTLD9UPTz03jGvf4KkQr1TcckwzRys3KPkuuelbETZXEmK1NZUZklTi7vpFsMOHpce4+v4w/QW6WUfLsd1UaL3JSdrPqsBHh0wQhCOoJku2eD/7Y2dqIMU/t9pwXKkN1TQ0ppNJ92yq+hbEAUvZr3hBuYj5QAjy6QzPTJW3xm3H1f7R8KR94y1ZGCFOtNPzGzp0S05pDohtgNiDTVvBl9viVGhdoXRCIko1xTU9Q/a+evq2Mn6jD1KOKU++efGGCUUtAT8jahskrptOEvKq/m/ZBSoSK6QIHuLnGHP5mIBKyPnZifcYoPD2112O8v7+TKxrAPzzSYf9XBo8zbBDGelWazE35LYu/GIiXDqKnEssnhuMp63kJqmPr5MUqJPkSyxBfz3AwrOxKv5l2QVKFCMuw29qNSLN4myhTVShKpYernZ47X+T52/mZ+uuMoSgXjWdt3u0OuS8KLFqbzUO6k1F+7NUXUPf8mhWPfaYfNz9KbD6dZKSkqaSPlYuauX82UCp1/Agv5jdHwvo1AduKY+WvDci/EW6aHjJR4nTbSlV1n0Vajf7fmmiQ8/z1Y/Lff0bFWXHffYbifh8IAfXw8HDg46yrpSouWyiC5C65JwiN8oLumQPelj5ZblyC8uH07/HM+9yMwNNWH4knTq6fk7Chda60ns7vOooU206VNHbev/AWuScKzRGluhtddUrnU1ZH1BWK3U+taKyrpSovmbWYwGHgfsaprkvAcyip47c9X8E4hFaMEgFv3y0zBca1rrfRkFPuoQYEpZTDw+vr/INck4c2MNfsr8n3389W7W/pMcySX5YjD1be1rrWikq4MTE2KwcjuZcu1OAnPkoou+EB388xrdF9cxWZYL+Jdy/D46Js3FAxjnCZ5SOnJqKHnaezDQzKD5L7yNJKREOUneBlSDiajNGZPU1OmiY/mn2D1D6VrrQy/iOZgnlL4lB1J0uZg4G1ImeB7DtD+AOOl6WZtfcVQW25mvmuvI4kOtbicAa10rZWEAjIOIkPBMgZPufvA1Kgcb+9Hk/4GYiR226PpSeg0NWWkqbeDw//x44rm04Zfct1LGoJidx39o5/g1pX4VS72ZIyPZszQbw+1NaRzNDVl9QeNiorfVelaawkFb5E0UdpUWOErUxZuw0kJVz41pm3r+DDX1ttDbQcrgIqacmEAvmgboWk+xV9dkvB4hkLEXSfhPfMS3eOYSIlUrFrJfZ2UgzmTWzWmqCkfI6YAFQt5al3rRKxzV0fbjYZcm7IAvo+psbvoZXnZjOKM6afv4wuEw7vVNxm8WMZqag4DUJhhCXlqmk+IseVKi6bZTPCTuKlbHjGtK2HVhD3ccjBbL0mxmlpixCRTS8hT0Xx/H+u8NmUBfA+jFCgD2+smEcQVbbnVRzcez0CfIjXFbk8DWPM9Fc2nuHXXWrQXi/H8JmPfhof8/kn5++l02lvzx72aXG0NYQ+3htqKWWxiNcV8bqPs5vCUovkUlbTdM7AoNhN8C8rL+mnlqe7d98GOdi8JJ7tMSxETbamkooRl9+5zpKZYmNwu2uZkStF8mlun2EeNu451PjTxq/9pBWpih6whnGXqoLaGyF5Sh9oWOqbEIjXFw+Q85KloPk0lXWnR9FDINA7blwJiaPU13qKXtQmsnEX0vhIjeNweqnkY8qm9/xKqKXF7Ck9ZpaVoPiHGDsU+akibuUwNRGRhnWXT1kPCEoWvPkWtlW3djUzlvf2c6Kdze5jKw2BF52d0gfjJMHlPCnI865pPceuutGhkM93KTc5dtD7j9qX3yVB/ND94+8n80+7ypWlO3NFlhK/+UdNRhjL7mNzHRD9d2MM8W+mjT9IFKqTWC24/q01N8ylu3VbPwDFmCbYvvSem5qO0s92bn1vmoSkL20CiachyKeYqePVJJ4zabVnKUaKfLkZimY8d00k1Zyo67yUQh8m90dU0n+LWbfQMPJMiTTQaOG1eeke4BYL7MymN6oeeMr+4omla+6P9F5YOXv3ymvZI9NOFPeQ+dkQVnCyEYolub4qblGJF8wkxtij2kZaT08YHHaujgXeNN9mf/efaD/5vLO+yaJrevYdDsri/5IruUqZatZa3ZcKFt5TBUwI1FZkfU/4i6UpfTnHrlpck8JSCSuzcyi5bo4H3DL0+c/L5v7mBXXXc/dHPZLOfwn9H7zpEfpJ49a80Gno/XdjDOm7rhfDPp4Vs6/Tt3TaqiuYTYuwKG/kM17hUXpVnSGar7V9fWXXR/9O90j4PMwWiafwPG8qUKFRepz13arExuzIJr/dyIKY8LWrK3L6Xt6YX0ZRr5a00ty4UJc+w/Yc9Gif3JrbvWX4Y/vFmZarJyqU9RNMY0aFuXxAhEK++UFlpEv30jF0d+tgco8HKeP3DeuX2o5eTKjiebSfh3ddchW/l9PbeXVl07Jr6QjckS/TivWaYH9E/kDcNyZd3dHmtWKFxRQ44iX46V3gJF54odS0y/zna7QcnU+FrxMXYcXC3e4mFbq+j92u4mlYRiyhwSr1Zjajt3WfRNFZ0SE8JJ4w7PfziNRJWrcyuS8LLMwF5yQWrq+rRuS7rFUl49dMqpb8kyFRKzkhOqKkm1TRWvpyjyy7g4jE7ORtocezz1Ul4vTdItus+ztXwf45+extZuyIJDwimo2IRylErqqspo/V791k0jZMv6+g2ywUde/XXfGpOwqrV2VVJeKYmx6jrztSUFiY/e5kKDp4untJwRZVflsGZvH3V9hca5xYUnVJWV1PmBv6gaBovX1amlhty8bjW8Glx7PPVSXh6FJSpqcTtrdUer6jfizGZRWd6/dx/5GXwxJLJLfeijM6pamrgQiGaZpYvO/Vk4IUyVuaqkfhcbVuhFRMu/DnZrWRqKlFiMtHJ+LEvT0emTD01kPRUkzxq9X00kqKrKXP3av7Gm2aRL6rBEp5iTo/WJVcx1wxqhfb+SzJqmpLbZvlz9NubCl5TuedmSS6ZsZHOXilMJknZ/bUj3TXEFyhq6iSMimiaRb4aIVO77Prdbjy67RIilXDh0w4bC6Hrtwfnblcoqn+XpdRUkSljcAYyVdGCS6qa2gmTIZqGyRcpPh/y5E5PmXSAJCxEz2i4FCV87BUnq57/nNOlM9hfUY2XQ1X9k3W4FTVFgZdGvROZKmVIL1JTkzQqJ35HLl/k6Lq6cfGosusyJFr1rTjwx2k+9jSe7ZszaDed8vzt0F/x9FdgVPMiVNVvNMtRaxDK3E/14MlajtHhSE318h48jCnlq1yElEt+MiYfMGr1GaV9Zo7cvFfhAXMyr4JHdjiq6jetTNHMPjjRZol0SgPJWxUfD9VULZ0Q4bYI+WJTT1ou+XlSU5og7LIMWanI/0n+vcbQNkEa7m5jjxxgGTLl9z0nwiumLUgZhGqqCI2YgAeXGaFWKaXy6LMgCY/l7xfezgrJr3WvjThlcgvwQPY+M+kkHbKYnBTuW3sGq5DC1yJHTPXP2Hc0VlODbto81B1q4+OBmsqlXhRRbiFf52W1HWGJ6Dl6ItYoRKYM/ubpTxaon1MkT2+H0+UPTf+RYCZLyJQSXumt9YnVlOgtKVS6JpRqaghvYurlP4ejKD018xBIfp1F0u4oxPVWIv1aCVNDSk8Y7tqLkhnLwzju13izP10UjVTCK407FKkp0VtS6DO9T37iaqoJVRkLY8a5Aa2TAlGIwhDawrqhXXPZJsXx44P2mw8l6ty9H05ILvlLSvc6DsHxUywmpdMIkZrapZSDg4IPU3x85GrqEFZC3FWKznmeeiIl327KFf4pVqKEmvTjkTOvuyvA9+O9hvDlFn0sS+79mVBNCeujkRqk4GqqCPsDIqwYSy3FJnYHqX5axYzbGexBh1TuDPDCuwL8AEZ0dspvHg89DPORMFgYWqWIMraiBFNT5uNBnKyy9fxbEoo8k33N1onI/Mf0drubOMQxtnsrT+9Vv1p58EVIdJwV4ceDPtZZODuF1BmbIpUcx1jUVBcZWhHAr7IoTDE5L0hKfudM2u5Y13V1zFft2nhhteLgL7BhcpIp4R+FfSzh7ARqalOkDimRWtRUFVk2EcBvQtE5LzsF7+XRKACQ5fVq7cD34kSHD5xZIjnhzk4hZCTynUPKSF48s5oqo9CqCGOqA0ROpsLOpLdoHrYIHvgFfJicrAj3a0M5Gbk+aEVL7hKukijQq2dmNRVpm0QSnsAFA+Lj1btXUPtmWqsZ+AFyKzp24KxZjodi0ApvRqgpxdERpIIIBqemeuUWeaYl4QmsNz5qNx76/pmX4L5nfAc/3KYidKlPQsQarjXCHmCIsVqpHF6nphpFj4nQQ65LpbnuGafiPjSz6xzkdYeqZyfaVIzbrWkhw0nxrcXJmmqh1azzX1KhrRoZb3fHEia3A2ejOx70saYsXjhpVlPlquWjmHa/djY3ErpP1+yM/NtHwohOtXycg4JBH6vLZDRdqKkmW8t++1Rd6xkjnMdMSakSAfxkaOspGW9dgX+Ch8kpPOXyuoM+VhVqiT/s/EpaiXPS2nQFJttti3WQCOA3h1M9rP4hT8CyqNR466r8CwO3aDRwZj3toI9Vup7VJLYgbN3ZRrr2guO6kpozSabweJ/d8YZO38qcjDzT37pK/4IMkxvJcfpG9LHIA2c7yDvmC3fCted8ctFTsWoq7hJOLxADaIM1gT3trSv2TwgNwZayEH2sXvmz+Z9OLrgmUyRRG2sVkJqq/u2veFDi0aOMFpXqb12xf0KGyZe8btHHqoO/2iyAdMyC2FScHTqR1kslhM+lisvdhn/9Ox6SKvhNnyPvb5cJ19hm0f6nTXRyyyn5xFmZU26FbtezO0+fdK/k3JnXwHqfF6qmj05SX/npVroLu+c+5Cn68GTkwhdIxKasi34RKje7aexsptLLJkxOfDFPz7GThdTh8IcnGqFrrWrhfXjjSu2jK4OpLz7Z5HJxsfReqh+r+J3DbRpDZpDqw+GPTpy/aTPyzHHfDWt02aiDHyT0uC5y2P9Qre+fRhepbNl85Pys85cV3WtlislLYjiE1FTDDozz0uiG/DUEajRxujE6bDss3vscx6GvXSIXL2x+wem3avpbaLp37tu676k/3MheMBLTN4f929vbpffSa1c8IWTh4jgJxZBHecylnDKZ2kxffES0VKQ5r3ukryLCLsoZWat/tn53z479UgzdpvWkxpf1259zOFxTQZMzYD19i90tT529vVc/Wbn7Z3IeUnQiU1W77cTMA6LPORyupiK57ltLXw5P+XdfgR3HLcvyWHVjoowfWIjOJ2ya/WV7902Eap4GXffavO6aPhea0D0zUzSOa6zVMjuQY1wp43cfwxNlwqYZN2LOgk0bgEdGhMkXulmdX7yCPJXo+1RM/kOX6ShL3Nh5/XkWZw8kbVrN1NRaEvXjktK9c17n9IgbCH6Zi1ISE3JUlGCBUVJ2t6LgRJ3qupAAVvazTARxx4a2+es/4y5I6t5H3kDw6/BeinW5TUzJjONOZnDlZK1gHmaF9SQemppa69TMnUF6kvtIg4HO3I7f80fdiP4pde+XiSbkjPL8aNehCjMNG+sxKWqqy1LLMA7M8pnHhms4Klb0sRgvr+Pp1pX4JfpL01X6qe0JOeOR9NQoDpZWuSlqSrNp7PaN/bjTLWx7zV9zv0y3rsDvsdLBumZCjh2pmvih3Kn4WE0xm6Y962P5KLBpU+NVfw74VS5O7hQdTI4DrK2KzSABqIMb2j5MrKYU6+lolmrMCQtPvEHoc9CHbW9ZMUZCgaV6wTSqwEc1m9lIxWpqp1nP+VnFcoP9U+RyPh2m5z0tX8lEKXMLsyw18i96KelecCCqh1lsYjWVHnToF5tonnRQC4HbEuZTlJmuptIj/0KBpXvB5sZsNLhYvkVqqkpYTyFSK6YY3JQw68u5ulNYbqf73f4S/zltIEkael5u7z5HaiqRuHgWIvWcSXgPxDR2k3oi8KdNm+WamloZ+RcKLN1by/mTWv4lVFNpm9YzOUqbYvDzkHNcq6cCV5gCkLmipqrkHTZWxRZ3OPgvJ35NqKbSNo31+J4zCe9+CSccs5GMoGBwwng8kzbIthGYav2XXZaKYLPemi0mq8fUVNqmnZhYlmlTDL4bM6VQNn9qO5poCk9utMCkqKnQ52IIBZY2kAOzVJN8bKimkjatYPbyOZPw7pRT3Px1wm2upSs1WMdYUVMrgak588KQNpAUFB/t5y5wwAM1lbJpwsVPJiyAb8e0ftj8a7tm9ctXN5arqKnQQjKEAhPyJWHyUAVGK1BTKZt2yoKp/8+XhHc7xupjp+W1GcpMaf6EmsplB+3g1IOiAfKkNyxCWysGkolUGdyMBpYXNZWwafSuzMfTCQvgamg5pdF+zLLVcGDki+hqagiapXDCoagpNcfA3ppLcBg6ZSwiNblCy1JjGTdpKZtmyi25fJEp9kt46U8HjFH88B0dI8dEX+zMlRuCw43W1kFQcZxVTNyo6VGSa1bFNixSQ+GlMEWdqSndpv2RrxH9BFTroW0+2CIKo/54IJMVFxp79o2s2xBf1mZc9BiFIhMH4cKwACRJxsSLBjFRjlBgXL4ErMdXZzq+KqpNI4ni4SrzpKOycFkfXgksVeJnr+zpHX1RUrr9T9yEJ0RciBWelq8sAHkKFUV6lCROwotr5Z7v9Fcp/yTaYtQ80KsppXs57KK/d6f/QG/dGUyjku0TvckyL+iU6TJFSupDbX4jP604MgbvvWkkdkqIxkass/FfhHyFpfb2o627T1G3x3inb7Zpnv6k/LUH8fPYRRReK+1fZ2rKnH6RY5CQ6A1YYo03r8SWKd0WIzcfevPHaioID4kAZKim0qMkV66KnWd8ofhd9Bbx2FS+yPOlT1IV7m8dxQXVrOKa7iXmIl2F3cPcI7aWMs1dpJMVm/kicZgEcez15i+ywNEIwkNCwkI1tRLrFBIs5Cuq2Vz3uAhXU0ZdRnMVqkle0EEpxYRbBfNluVaa0GBa6HA0F/HwFE3yrlLXtlmQmFRKqZESFqqp0BgtCAlOGEgauXbHE7axWqonbRrxqosCfg071z3fV3Vd7e0Pt8hH5E8E1xqpYesYWz4z63Akrg3VVKDMjIRN4glc4JJ+91VJeKSOB/s5z5K7gLvqhX2Tfa2UBxGkUnL/Y7lVyxb5SDchFTfXhtts0dc6fW2gpnqpUCZFwtjpXZbsn3MJ1jWkkXV/s6RXtnT6ZrNOncFXWXDr3zllsg8z7jLeartsdY0O+6rLddPnMbBU80s1ZRquXU4GEmbD8Ev9kn63lGBVu5JE+b812Xdc1FT3NOtO/yqkZ0Z+hOzY/IavNKHBNSOZJ3cbapJ27Vqppg5Sl9XhRVJNVdlqEt4QVIwxlhkX/HQc/vS2P3X6I8AV1PHLanzY/eS+mCZs0pd7H7ddFMCspNLNL9RUHs9kGNxnGuTYCTXVpJSLkoQ3sJO9XcV9ifQX6+oX/DWlYpw6tvDrSrjaMDcjxURNeGpRUunm75maMgruwM6RuuvC3Vnm23TZahJeE1XMDCk1PqZUDP689QLBD7CLDISkTTehoZ4VUeVaflFSK83PBLmNXSkNX8chS0Y1hASb6nyEi+Efp7lwl+XvdfrvAn/Peo9uc6Iac3KPptH+MCW10vxMTZ2yaCZDQJ4zWZnS2kVIv3Ifsej2NKX/KPBPpL1Uy4aBMIpobz/a8FTBRHCl+Rc1tZNlWHhxHuQQIXQjX5N6TyHBbShP9aheBL4dFizWyWQTGo/Z+DmD+8qacd4ypPeF080/q6kpk8bRXBKNvJZMTb1JrUbJN/VcF5GERyqOxnEx+PaL9EIGFKxl9LmKs2fS2bMi/mO32WIeedD8HK+mzPOb5bBuZ3lsyvUxbcabq48TJC7Bo1FxiCndBKNagnW8BKbto8zHRQxyZpOcalhulhhGM3g1VWdR+p3SSSwz4XsVRVCbiU69rf8l4JcgDZCnJiUkdsbM3lp3eicUUSARpywd1HJqqoxdqS5RyZ4+1lp1Rjo1wL7dB3ZwNP9IDGKJJozTpgL3vo4i4VXisU5N5dFMBrUDuqgp4Xcj4+0+WQbcd8e6G4KzLbVcco23MLpecbOVHEczkJoyglUvx/TR3jNXU/QJGW93Titck1zujcnCBBpRdH1in03zJ4NapKaaTLhS68FR20WEUnoExvZduCZfTcJL3nf1WiMlRpin5VDa+RpaKKUHY+qbA5OrZW9MNU1kYT26vnqtG3vZs0O7DLOVnoyhq/e5davmY3nCY7asR9fXh3tKelK1HFgJt4NHxrpWtf9qNMeQLp1lK8vArWsdq6a65cBgupNX1xM8DpTYOc/y3RgFXFVEGwl85ao8gidC7FC7kYRXZivLwK3kYBoGDJm8DDXrx12bhKexkoMJXgueJ3J1Ep7CSg4meDFY7//6JLyY4YW24QIz46mOD7LevB4mmLcNWo+uj/9aO/BwTCctI0RoJt4tm9hMg4GObETXwetRanbtxK3ZG43vsow3R0dnN6Lr4PWgeGPgDFEq3ei/lZlOY08juQQEUEJUObIjfS6kTEnCo+SS4bdrCh4FEpmiGd3XnrQSWyZhScJDxhu4DpeDV5rlgI7WXeILb7QvkvE2XvzFW9fhaXAb3i+IlbmmG9Xql6EZhP2ta/E0jMJf4hl4rwO9VqtTGsGXGNsDmbz8vepvXZefxkTWxvDgaF+n/ver89Roy1Q/IeqM1c45lDeoD3h41AwwmnIKNQVW+SwLbTMSfdLE7mL0e6gpsMopiIZ4tAwwu9xHCTUFLHb9lnC+dB1G2BxaPk5Hmgtq6uWhpYn4Sndly87aue7hZiR6BliV+SUaoKZekcn+p664wbSS68RFCYJaPo6RpfMZaurV8ItKuYzARhMptmiwCzVlf8L7mINTdGhv/oeaegmCnWJneei8ENnR7L49UZE5o3DyxcOljuKJYr332FuoqedG27A0m+XB+ES5HM0mWzj7SeZKurqRt91Fqshc19GnAmrq+bBKaTQf31TL9nYYbMEszopvuQQZ0elIc/WiUDxRrJxVH9TUE0Fbu89KqTeHdlyU4hSbPPaJqOvm1RSFyWknLxnyjGes5stFUFMPT+wpEa05d8pW8/60wTqaKe0O2onS5HKJ8FQUmOrZAaiph2UySsmvQhxTmzIbE+DVlT3LxfK5MDn1DItpKRLNWG24JYSaelTsLJwpFCWxffXGBHh1sI4Nt/iJ0tZpn+YiUWDqwNVdAzX1mNDC+6P1h8hT2hvHKdiXc2MCfJ0pyzUwqzaHySnDcJHNyK8v+He+vTG4P6aL8BhPqQlPfLpGPsxrFCujuUOoTiTq5Hl2cJkobawhC08Ffr15zH75Wq8/FdwEv5sD2SXSEb0s4JUUQ1nPY2NZvD5TprVyycy86NA+2YtMBX59K102UlNt+rHgN4nGcY2+sPuQjqJgm0VLKWijuYE6CZ+mqZMDc7CWMLncfznw60+ByENN3QOjVUoRBzpZZGFGgNKt0tbzUHN6F8wTwopkTP2Vi+jYrqV7ZODXF4HgQk3dA20sTUZC3k90dpDusaqk1NFcNUywEA/W0baAs67jYXKaqe/G/6RfPy6XOIOdQ03dnkFIEkUn+W4OjXSP9diPIiBqmGBhF93mT8aFsOZOEkm9tb/Srzf9ymMbbjEKNXVjyN68pXcsq0RTq0pKW/ZTDRMshIN1vZExdoEUHZvlOZ1Dv75SNSzU1K1RrJagzFjaSaEqgXg0Vw8TjH3nPs3RdWuwrJJhTlsQ1yLZMaIk/fpdJE1v7znU1M1RrJaAuvFuVKTVdYAwUxauTthgoL/Y2NNdYLBO03J52CWcQ57m/7lm86XMYKPTd3sUqyWhLpcd6NCVlKaSSCb6OG1qsqe7LCQX9w3jWnb/5U/5AhixLUKDjU7f7VGsVgC1v0naTSgpddnPSGYsoz07RCeCpOA80J02PPUp/HqbrxACNXVzFKulFTGNl1BSauQyTsIzfYB2tGcnYbCMogw6gFFcy4U8+QtQRlfRraGmbo3qSAeQKzOklJS67Odutmg8Q2HGtPucSsXdNcchkgvKyMtK9gIoTzVATd0azWqF2JGZXfL1D83U2UrhUd+w1CC1EEUzRV6KEteag7Ify0VaxaGmbo063hYVKmxrJgruQjP11SS8KgtESMlumOdqHdJFCKipG6NZrRhrdlIvf2ymvpqEF7pTqjmuhVyXWaKrSmpKPQN+B8VqKZCKSOWrKH2vIFgZEkbXKVLB3Cktu8GvkZwv9Z6iIoYeC93eFsVqmaD2GBwiNfXfWeUbkvAoUnGcvybMsXX6J/+AlS1ywA3hVoulTTWyVG8VxKDe4juS8AJ3KlN1kM3Io0psWFZwQ8iR7qK0qUqWKp0fM2q3+I4kPBsgH/zXxDgR9RM686l7/tW3H5YmUzmIQjT4UaRszbck4Ul3apdwsYdoNSpwd8RJeBTU7kQho6RaMn7RcioGxUx9PQmPZNvbsu1xInC3LONt6c0cnLPdSH9n4TuS8FyHzl2zEdcC9wxZrY0dZk6ugcmH7uPzZaySvpiEZyDn2+VmjcnAO7h/9M4VZ5wd8zLLlJ0lr0vCs91Jd0zVQoNJVVmvCngEtpLwFiXlelxyhNewloQ3Tw10fUZ7GjGAZybVuZpZlJQbmTmGJRJJeHk402BRiF2Wv9ffUHlwj2x2rk5cYKiDGK54+IUkPK8Qp3+tNrhftjpXIxOEsxu8/S8uspGE9/Z+SM3CAc/GVhLeKTh/zKKRGW34ZUeSFE8NBM/PRtJAoKR8EuYoCuWxi99CKb0sG0l4oZJyQydyZMaopOEH6gYekvWkgUhJnV1aghiZOb2fquEH6gYeE8VqLcRK6rzMmQFAJU4asOtOd2d1iTJDZUYDf6Fq4DGZk/CCdaeb87KOIgBfgCZIKTt0VEklBcAqiSQ8E1kYmvUUBQA0wiQ8mmqO6CT4e1wSXo4hE/BNjBgyAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAK7i/zCa56YKZW5kc3RyZWFtCmVuZG9iagoxOSAwIG9iago8PAovVHlwZSAvWE9iamVjdAovU3VidHlwZSAvRm9ybQovQkJveCBbIDEwLjEgLTAuMDYxIDU4NS4yNSA4MTMuODQgXQovUmVzb3VyY2VzIDIwIDAgUgovR3JvdXAgPDwKL1MgL1RyYW5zcGFyZW5jeQovQ1MgL0RldmljZVJHQgovSyB0cnVlCj4+Ci9GaWx0ZXIgL0ZsYXRlRGVjb2RlCi9MZW5ndGggNDcKPj4Kc3RyZWFtCnicK1QwNTfVM1QwAEILQ2M9C1MFQwMQX8/A2FIhOZdL3zPXRMElXyGQCwC9AgjkCmVuZHN0cmVhbQplbmRvYmoKMjAgMCBvYmoKPDwKL0ZvbnQgMjEgMCBSCi9YT2JqZWN0IDw8Ci9JbTQgMTcgMCBSCi9UcjUgMTkgMCBSCj4+Ci9FeHRHU3RhdGUgPDwKL0VHUzYgNiAwIFIKPj4KL1Byb2NTZXQgWyAvUERGIC9UZXh0IC9JbWFnZUMgL0ltYWdlSSAvSW1hZ2VCIF0KPj4KZW5kb2JqCjIxIDAgb2JqCjw8Cj4+CmVuZG9iagp4cmVmCjAgMjIKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDAwMDE1IDAwMDAwIG4gCjAwMDAwMDAwNzQgMDAwMDAgbiAKMDAwMDAwMDExNCAwMDAwMCBuIAowMDAwMDAwMTYzIDAwMDAwIG4gCjAwMDAwMDA1ODUgMDAwMDAgbiAKMDAwMDAyMTc2MCAwMDAwMCBuIAowMDAwMDIxNzk3IDAwMDAwIG4gCjAwMDAwMjE5NDcgMDAwMDAgbiAKMDAwMDAyMjQ4MiAwMDAwMCBuIAowMDAwMDIzMDU4IDAwMDAwIG4gCjAwMDAwMjMyOTkgMDAwMDAgbiAKMDAwMDAyNzc2NCAwMDAwMCBuIAowMDAwMDI3OTEyIDAwMDAwIG4gCjAwMDAwMjg0MTQgMDAwMDAgbiAKMDAwMDAyODk0NiAwMDAwMCBuIAowMDAwMDI5MTgxIDAwMDAwIG4gCjAwMDAwMzMwODQgMDAwMDAgbiAKMDAwMDAzNDc0OCAwMDAwMCBuIAowMDAwMDU0MjEyIDAwMDAwIG4gCjAwMDAwNTQ0NjggMDAwMDAgbiAKMDAwMDA1NDYxOSAwMDAwMCBuIAp0cmFpbGVyCjw8Ci9TaXplIDIyCi9Sb290IDMgMCBSCi9JbmZvIDIgMCBSCj4+CnN0YXJ0eHJlZgo1NDY0MQolJUVPRgo=",
    "pix_message": "",
    "pix_transfer_type": "manual",
    "receiver_conciliation_id": null,
    "source_account": {
        "account_branch": "0001",
        "account_digit": "4",
        "account_number": "1000087",
        "financial_institution_compe_number": 329,
        "financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
        "owner_document_number": "32402502000135",
        "owner_document_number_formatted": "32.402.502/0001-35",
        "owner_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A."
    },
    "source_subtype": "outgoing_pix_transfer",
    "source_subtype_translation_ptbr": "Saída de PIX",
    "transacted_at": "2024-08-26 21:34:03",
    "transacted_at_br": "2024-08-26 18:34:03",
    "transacted_at_br_formatted": "26/08/2024, 18:34:03",
    "transacted_at_formatted": "26/08/2024, 21:34:03",
    "transaction_amount": 358.94,
    "transaction_amount_formatted": "R$ 358,94",
    "transaction_key": "425837bf-bff7-4be8-bde9-75e2cb0bea7c",
    "translated_chargeback_reason": null
}
```

**Response Body: Comprovantes de Compra no Cartão**

```json
{
  "origin_key": "f17c219a-e11d-4b5c-b00a-8ee2135f581a",
  "pdf_encoded_string": "JVBERi0xLjUKJbXtrvsKNCAwIG9iago8PCAvTGVuZ3RoIDUgMCBSCiAgIC9GaWx0ZXIgL0ZsYXRlRGVjb2RlCj4+CnN0cmVhbQp4nN1YS28bNxC+76/goYdVEVFDcvgKDAOO3BYJ0LSuhfYQ97Bar+wtJG0iy0V+fof71sO2LDsoEBhacZbkNzPfDIcjCwb0NxT0cChYuoi+RBfsS2Qkl5pVTzSOa1RMWa7ZKmN/sWUzb9iiXmQU96p5NpPVIGVaWg7YTMxJ9lyIWo6YVsBtu7uVTNhZC96EbY3gONgWxHtudaMiqsU0bK+G8xq3kioTKoR6HPQEn4B78A6Q0UBq9OHbloPVDRslwG7uosCW9roki6iYlWQBl7Q2rIQwUELRtt6md5NIKOKuojqMrA2anebGCkdWTRbRaDaEITDBJrPoUzwuFp9XAynj4t9kuc4GQ2V9fB2+RczoCfFkINDGq2R5l1wptPRRxeDvyYfop0kvgkJKjtIw1KqMIaIkz10TRsHC3xPubSIpJpEj6g4CuK7pUhQT7OMZ3d+6YFq4MoLNm3n3Bg13VoRoVXta+XbLgANR5FMosx/73hlRLmx4EkJ3yf5UfB9jbRuXH0hcvVtxRbuDy7pysH4zb99Iqzdc7uTbLRv6KKJe06HYGrdBaeRdlA3iGnXfrYNI6jQVhcZBCFXkcA+ll1seNm8620oVrWWNdPssBFNV1gaiFncxat8OKVmyLliSWUVOKw+GCUUsGIM0rGqW2KpZbb3Csk7pqmhVAoaiBX67aFXToXT5SqPvK0Tk+wok2BG4kQQJbwZDNAGfnkK8Rf1WCxJ0jUnlsK1y5FWrIiSAsd44xyQ4oqJUt6Pnz4F1cTIvVh3Yvphv8iUplUo8GtItBUIbuceHP37o8eTVG4e7BVwB8HBDCEcJ2p2tEEFb3SjQXWvVYoNCh5u8CiUbfXXsvIguStBHM3bTCbqdRHU7qVBdUQqiaivo8W+r/CZbDCb/NFZLR/5Kdajd1XJhND5kvD/KeCUE93Rky+GD1p9nd+t8WdTmA0e6/lVA14YuydAIGAxHYzt3araV5NYQR347tPHHYpG1qA+ctGAwtF1BGNWwlPGGeNmXjRfvKVd8mewQX47PG4mel/xsIGzMmxQ63Js6ZKjc67vUx37Qr/iXfJocGwQ6amI/6nmR3i+y5bo4OhJWcu8NeNzBJp4QJF0McgQAgg7ws+3vU/NNnOgreNgTaouFp0YUfOWJhGMjQepwr45P8fslHbT1fd4r+m3N/nlgVZwvk2Wa5aukS99nBgtBcBXaaffUsSnSPLtOynupOTydQAvGZeN9pbS4ztdFt4qCkZdTWXhLC7uD1yFdUWr4q0E9/6Kz+H/x2bPh+yC1ThBhudvrS3x2Q4bJZZonx5YKpGveEmW7rUocTtVLisM3sruv4ZWNrymh315yP+q4WK6Pp1o7LsqWap+1Ug7Vi9h+dav74I+Ybp3CYVl7O7MUcq0xtKhIZdoAjcuLmXrtK2XUdX7TP/jhvJVtbxDO7td0a+Tp7j8HDqdFeMstNexkuSZXwElQYsfyaZpNg9mjy8/Jkp2csNFZur5P5pPs65qdzLLZDMCY8Dllp6fs3fm42i+q/SchxU4Dq7+ON4ETMZwmU00+TWE4hUQOnccZ6lmaAuABgeiIBMulQIfItAzxhZrI3YrWstmraC2ppdAs2K5ozcRWRWv2bvRn1Dl4iegoRbgIv6YoIa5DWD/+/qGnYk+X0fxAiP4DLOUwNwplbmRzdHJlYW0KZW5kb2JqCjUgMCBvYmoKICAgMTI0NwplbmRvYmoKMyAwIG9iago8PAogICAvRXh0R1N0YXRlIDw8CiAgICAgIC9hMCA8PCAvQ0EgMSAvY2EgMSA+PgogICA+PgogICAvWE9iamVjdCA8PCAveDggOCAwIFIgL3g5IDkgMCBSID4+CiAgIC9Gb250IDw8CiAgICAgIC9mLTAtMCA2IDAgUgogICAgICAvZi0xLTAgNyAwIFIKICAgICAgL2YtMC0xIDEwIDAgUgogICA+Pgo+PgplbmRvYmoKMiAwIG9iago8PCAvVHlwZSAvUGFnZSAlIDEKICAgL1BhcmVudCAxIDAgUgogICAvTWVkaWFCb3ggWyAwIDAgNTk1IDg0MSBdCiAgIC9Db250ZW50cyA0IDAgUgogICAvR3JvdXAgPDwKICAgICAgL1R5cGUgL0dyb3VwCiAgICAgIC9TIC9UcmFuc3BhcmVuY3kKICAgICAgL0kgdHJ1ZQogICAgICAvQ1MgL0RldmljZVJHQgogICA+PgogICAvUmVzb3VyY2VzIDMgMCBSCj4+CmVuZG9iago4IDAgb2JqCjw8IC9MZW5ndGggMTIgMCBSCiAgIC9GaWx0ZXIgL0ZsYXRlRGVjb2RlCiAgIC9UeXBlIC9YT2JqZWN0CiAgIC9TdWJ0eXBlIC9Gb3JtCiAgIC9CQm94IFsgMCAwIDI0IDIyIF0KICAgL1Jlc291cmNlcyAxMSAwIFIKPj4Kc3RyZWFtCnicbZVNjhQxDIX3OUWdIMSJHTvH4AioJWDRLID7S7znpKbVwKanvir72fFP5meRq1VrFtHxMGbM7tevb9enL+369rvIrMPX1euwdf24equtxcHnjVJlgo7tOzU+jmpLC7747K9PeEv6XrpeWqULA0jtsl4BNh5Lcei8g1aXl2H5iy+r4StjCCRdmIpMRSAwI+LPavMSqSGdNIOguggaej3ILfJjD8MpUC8PYpvzWnWNdIkxYbtqX06crV9RQ5UwzADpBa0VMIw62koxOkYVnwSNeEHDAR8HV7qnF4M0P4JRF3ItNAtjyLmEBj0NUO5Vvd3PD6oKDDbmSRTgmhCGjFaV1vepRSmlUwg9CMvGDacOj6xp6zc/D1NpNmOdYg6mh7FgF4LZdJEdA8l4FouqqKTnr3AUHSAyyk6bbFXdEWFlE9/Js7DPLBE1ZS0qy8Cvobd4w4JHbTqgOE+HWACMo7FQ3c4ja++aVok88AKsoTkGbVAoD43Tdc0u5cyM2qRnU3LWulh2js86Yp8E7uRp2eRpKBUwx7DV1SGKbYjTAtQHqJZDNXqQgmU9ZGj12LbgwhfTc6AhgUVrY2VrY+TayRkCi0m2yMOKpi1XZ8/ZhpLnWmveH1Eu9fTTbGJqchYfKO8SZXQ226tbAtc8oTBvN57KUMabnoesOqozcVxLeUwvIg4uObeU8p0DCy2xbCJjx9nAxsnaa/K4EcMHx2fWG7P2D8N8olzPrNTYYp7LGlhWBvKcVk/oSmk2m/1Aaj1bKhwO1Fi9fKDds31Y89LjYLDkuhV7bi1oDyOFJY1cpOQ11HN+VOJ6v7keuMvQo8F7kAP/A1cet3FTQ6Ewo41OZkyj5VmQwTbrnHN64wGXRg5TvkWB8pLbxjfdKochPubttCOmWjnwSg7/GWjD7HjSg7Jrv1f1wEeIxDgOynu0nFwTrsyWrdoIlXA6nIeX0OETJX3KncFbdv9J92v5XP4AkddargplbmRzdHJlYW0KZW5kb2JqCjEyIDAgb2JqCiAgIDczOAplbmRvYmoKMTEgMCBvYmoKPDwKICAgL0V4dEdTdGF0ZSA8PAogICAgICAvYTAgPDwgL0NBIDEgL2NhIDEgPj4KICAgPj4KPj4KZW5kb2JqCjkgMCBvYmoKPDwgL0xlbmd0aCAxNCAwIFIKICAgL0ZpbHRlciAvRmxhdGVEZWNvZGUKICAgL1R5cGUgL1hPYmplY3QKICAgL1N1YnR5cGUgL0Zvcm0KICAgL0JCb3ggWyAwIDAgMjQgMjIgXQogICAvUmVzb3VyY2VzIDEzIDAgUgo+PgpzdHJlYW0KeJxtlU2OFDEMhfc5RZ0gxIkdO8fgCKglYNEsgPtLvOekptXApqe+KvvZ8U/mZ5GrVWsW0fEwZszu169v16cv7fr2u8isw9fV67B1/bh6q63FweeNUmWCju07NT6OaksLvvjsr094S/peul5apQsDSO2yXgE2Hktx6LyDVpeXYfmLL6vhK2MIJF2YikxFIDAj4s9q8xKpIZ00g6C6CBp6Pcgt8mMPwylQLw9im/NadY10iTFhu2pfTpytX1FDlTDMAOkFrRUwjDraSjE6RhWfBI14QcMBHwdXuqcXgzQ/glEXci00C2PIuYQGPQ1Q7lW93c8PqgoMNuZJFOCaEIaMVpXW96lFKaVTCD0Iy8YNpw6PrGnrNz8PU2k2Y51iDqaHsWAXgtl0kR0DyXgWi6qopOevcBQdIDLKTptsVd0RYWUT38mzsM8sETVlLSrLwK+ht3jDgkdtOqA4T4dYAIyjsVDdziNr75pWiTzwAqyhOQZtUCgPjdN1zS7lzIzapGdTcta6WHaOzzpinwTu5GnZ5GkoFTDHsNXVIYptiNMC1AeolkM1epCCZT1kaPXYtuDCF9NzoCGBRWtjZWtj5NrJGQKLSbbIw4qmLVdnz9mGkudaa94fUS719NNsYmpyFh8o7xJldDbbq1sC1zyhMG83nspQxpueh6w6qjNxXEt5TC8iDi45t5TynQMLLbFsImPH2cDGydpr8rgRwwfHZ9Ybs/YPw3yiXM+s1NhinssaWFYG8pxWT+hKaTab/UBqPVsqHA7UWL18oN2zfVjz0uNgsOS6FXtuLWgPI4UljVyk5DXUc35U4nq/uR64y9CjwXuQA/8DVx63cVNDoTCjjU5mTKPlWZDBNuucc3rjAZdGDlO+RYHyktvGN90qhyE+5u20I6ZaOfBKDv8ZaMPseNKDsmu/V/XAR4jEOA7Ke7ScXBOuzJat2giVcDqch5fQ4RMlfcqdwVt2/0n3a/lc/gCR11quCmVuZHN0cmVhbQplbmRvYmoKMTQgMCBvYmoKICAgNzM4CmVuZG9iagoxMyAwIG9iago8PAogICAvRXh0R1N0YXRlIDw8CiAgICAgIC9hMCA8PCAvQ0EgMSAvY2EgMSA+PgogICA+Pgo+PgplbmRvYmoKMTUgMCBvYmoKPDwgL0xlbmd0aCAxNiAwIFIKICAgL0ZpbHRlciAvRmxhdGVEZWNvZGUKICAgL0xlbmd0aDEgMTIyOTYKPj4Kc3RyZWFtCnic1Xp7fBRV8m+dru6e90zPZCbPycwkk0kIARITQghEGVGQlxoBEVAwQIzIqoAICAHDY0lAUEBMUEQYFRAjYkQWE0REiTwEXJXgb1lxfRBF14isP1zdkJz86vQkiO7vd+9f93Pvnc6Znn6dU6dO1be+VR1gAGCGRYAQmHLfpBl/i4tMBwjmAEjjp8x5MAD3JBcChFYBMF424+77ZvaeMw0gg47hpbvvnVf2zLNJx+n3DoDUP069a1KpLWZ/H4Bufelcn6l0wrbZUEvHM+g4bep9Dz7kPJwirj9BxxfvnT5lEsgzPwfIXE7Hv9w36aEZcq06E6D7IjoOzHjgrhn9Df+gn90jAMpUkKCM18hlyhaS1gCJYat8CdRLzKhUSDJkNza1XAVaU0tTS06MM8UZSnGmlMnQNguT2r7iNQb7Lz8+oGYCg1kdZ5UM5QIkQJ9wou1Z+05ztZM9Czvl6ri1zlWJhgQb5Li1RK2tJVd02Hyx5WKLdv6f53N2O5L8SRKbwDy9WDAATg1ScvsUeOyXD2KVjLJzSzqAX2AagyXnyqZ9/0f+Mp/PKtmoyu+VyafunMgP87/w0/zwxDtPDhnCNrO72VS2+QaaogQzO87Ks+VysEAcDAvHqA0uaLDWu1bFm1yOW9DlGRRPIl3sFEk7nxMODkgoh3K1wlBhrDBVmCss5dYKW4W9wlGhVTjLXZGECwlOkjZV9bhj83L75PdOz8gVggZTxbc064kdL1Wv27Fj3QXm4ucv/IP/wJz42bmjR899c+Twtxv5Ed7Cv+eHWSGLYW4mVpTBXgBDMsmYCuPD6arLFO8ANdngsVYlB7A+aV+CZgCnw2hUi51GR7E33pg4OCj02NbW1uJ0FV4F2UVFzReLGltyna64wpxwTE5acdqMtDVpEdreSvssrSPNRBJfw/JyYz3OoLN3epCkv/JHnke/KGcOOrDklf0ND8xeva3hgbmPbmtoGFA3b/5LuGLBnJ++bL9D2vTsxv1b2qukTc89/dbz7VVyyc67Jy8AXc97+Rh5C81BAy9cE05KbAC7u0Ex1ttXsTdxX7LTZbkhTgajNDhZiJ4b1Xhz88XGFq2RtG4q8S3yRXyf+2Q2IXRZItKoFExNZ1FBdX2zWQ0N/V4tPw4dHcfLX5X6vvD44y+Itr19p2quLZ3E9/FfaNs3iX137Ny5Y9SgS8c4jORzQk7YrVpIoxassteb9hnMqhGMg11aGymQdElm0Nh0nPSas7s4ZnOMsEwyzN/oKQ6H+Yf22PgCSbJ3WUwvL+52OY/tb99F+iiboij6eFcDyBVyCahwKZyBTlmRJSeTFLFDSQWVOQHUgRLCW4qqoMQUGQxa0/A68+ixDdRBuO+44XXu0cPrPKNvFyc6DvQd1xgn1roltzBn+KixBk353qAZO5vy/bhUFn5siDRNKpcqpEppkbRW2iIZxUAmNMke8LBETJTTIZ1lYqYcMOZDPuuH/eQc42AYzIbiUHmwMkQNG8fAGDYOx8nFxjIoY/fgPfLdylS1xDgbHmTlWC7PVuary2AZW4Er5BVKpVoDNWy9tAGflJ9U1qvblRfUOuMB42fGDuM1E2BCTJ6J5bHg1QfZRDbxIL+jVS5pG407LkV0mykn3+xJa2KGEOwLZyT4LXEmO7wYpzbYnYFK/15vQ7DeuSrOCnEYbzMZLX40ugelk/0cbyITchYKdTQ2X2wjxz10XjvvLHQW0rKF789JzvHl+HMCOSk5qQMywslhX9gfDoRTwqnFycW+Yn9xoDilOLU4Y0bGsuQqX5W/KlCVsix1TUYk40KGr+vRroe6HijxlfhLAiUpM3wz/DMCM1IW+Rb5FwUWpcRPuAINrmYFzmA+YVdqen7vPnkp+brlGvJ1s5H2f7Zj8fSnGurrB+xbvuNY+yUmvbC+ZM/ou/aP/88LUl5Z+eRZp3dnjmhfXFs26e3n3jzgqljZq1dtRkZbp/3KpaSrGMLXBDQB2plaZXfWW/eZmWSEm4R+BruFbwnXyi4SnqXDwe4Sz589wor/O4cvrV+woHpHQ8PA12a/fUjaIlx88ybh4mTKd5X+QOMW0EL9qGyicfuGE+yK0YEvgpPtM1aZLUYTBQij5rKLcYsa6S9XX5KWKBYVFubsesXDxMgpnhSnO7Y/8wi9kILynGwuK+fLhs96881Tz1VVKZv4O6vbIytu2rD5I6lkNbsGLmN3Bc3ZDUkwI5xGNmyqNC5XPC8ypcHK3ohvcNVbV3mTPJLRY4ThkssxyKuDeaOOigLQmzWyC+3ieeHO4cwByTOSI8kfJF9IVgbAADZAGuAZkKT0MGQbs009zNNhOpsuTfdMTzJNmCniUYqPdHRFKCI8MuhQYJAr2nZZT7w+7fDkKR/8gV8kOM9s+5IZ6qWtyzc02KWJ4/cf7t17Z/cerC8zE85fxz9tXL9756auOY1X3TpOkka7cHKVvZ6tRx0hbyCsHJSsTyRXAFJLF0juiWIkCo3mdZqZpMsVy7piEUmHz9XX93t1wbEO6Di24NX2w4SO27cTQuIeaeK/WraXTmLXMyNt10/ini6IZB2tZF/fKqeIAQwL21WpGhbLLIxeCCtGram5rZkEIXlymI5Qb4IRwmQcBJwETM6CvuPCMWDyg8Y0yW/QTGHTDNNmk2kCioUPOlNU+Yf288fazyunaltPKVnCnqd3nMXDtLYZcC5cZLNKdssov48symAe5ff7BpotPj+hViVbIbsrPSviG5xyQ4jAoJvPbPEnGWBkktFuMLpTB3UTuN3U0kwrXFjYueoa/+m89tN5Yf06Utq/d8YVGvTvcam7IINsMnyf1+y1eK29aOF7WHpY+5v6m/tb+lstAQiwNKmbuZule0y2O9vTPbabr5s/M5CZkpZRaa60VForbS6B8JKkmlULWtGGdnSghgmYiEnolZNNGdmZAzLvzKzIXJS5JjOSeSEznqBwpk5wdKDwMx/zuFVyhox83cZo4bIpygjIyI3FlTdtH79ixeQnBjRu/fkv4w/eW3Zo0pJVd70UfunJz98v2y0P2Nmt2+jR4aEp9u5Prdi4Jxjcn58/7pbhxSFHWvWSTTt8JFxHB8zks/GcXO5KB1I3EYhCWK2f1zFXLaDzBgCnCv1GArh3u3sVWQxZYVOgV3aR1stfJE+4imy1iu5dTZxOcKcgcaeICyLWtYI7eR0+9HqSfsedmDBHV16ui8L2b0jRyo3PPEN/zzxziZn4z5cu8Z+ZSSnmJ/hxaicoQuSx3iwvwmfxSl7FZ7FH2Tw2nz0q7GQ72eVUsksVpoTjFaeEkh5MByoRWIwKMpmBatDajjdGw8HFll+Dox4Uh9fFCns16PZqAEOXvbrGSkzFRKVQGaLcjXVQpxpEvErxsCBL2Y4H2r88yXh7nnJqTOtiYbFCFugYKO0iWRB6ht2QyCQmJSLgQGkzeYsEDLMbdRP8NyEoBErG2vZfapVT/7pP9IWwknS7UtdtELLhunAo3gqRDDXi6xlxrfWtyng+J96a1t3rSfM6TKRpUrcjJSlHGLtAAz3aiaFadM1r5wlsr6SkIWFMaYLvuVWDMDY5mJpG5hVzBU5IK9ds3bpmzbatfOuStdDxt8/42sWPP89//vln/vOWIWuXLlm3bsnStdK7G6qqNjxdWbVhTGDXotc++OC1RbsCqYdWn/7mm9OrD7FJDy5Z8iA1XT81tFbDaE5e2ETRPDEJ471O4jVOYj0DtWedT9gi7rUyRCTQzBIze+M0VAnnBMcRq3S7IDyC7KBOdppaDhyIslsR0q5QqfI9q/Nqui+zcO6t8hhljGG+PF+Zk1SVYJBBTpAT5STF+yDMUWcnzkp60LsEKhOWJC5JWuLdDtuTnLTMIcKl/D5QcA27MkDLQlkqsBXS220jyAjzJt34QuWdJx+a3zT2G+YedHsCv1hbWzuXre133/qhc2sGXnf8qtxv3rlj64xk/p0+/00dLnYQOCiQELbiJliqoswSIF4lN2k6TqvV1pJTkOfBYMyFk1sWj+Q7+AEmzPIL0tt4siszhMOegRiRpYiy2AARk9GvehH8zCKYoUMwQyaYYUtjW0unXpp0vZAmdjvQIUsTClKcSn4oT0Rczobxp9hd77FhbVtq5VlD6oe0nqrV4+oFEvagHNTzPS+h/VJ5GyyVFIYyxBsplOs8WKichBVcIXjhJH04l4Ncf76U5N1C8kpgg8XhZGZDGyDaBgJaDBHqZrGJWc3gVY2y1a6dGV5nofW16UtrFUvbFKUHgms30ViuTpSWj9LyHhWL2t0C3WEIjIN7YC48AoZYlkW8NQv7sJvYzdabbWNYGZvN5uMyZqPFNLEUzBNSikiTjyqXGM/np04dbZ+ohNrO4om2vO08wkoOdq7RWbmUZE+GieGgnGhwVmrJiRGDO6KtsEmEKbZVhi2+OC8zU+wza6pPa9MhpMs2NTGBzrXQxFqQnVJs1pMZ8sSvz2u8UdPpRoyIfXoS43FDypVQLwzuU0xoj/QY26OVpfEm/sPEg1PHH/jDy++99/Itz46mKMkfdzj4+b//g/8UCBy7KmfPxo170tJ1+TWRs+t4+Ho4Q3aK5IFAURU7Gek6ZRkMBpLdvQKqjBIoCqO84n+TOuwqNoqYOBmwO94g36CMx4W4FMkXDJJRNqke5pYS5USlO61CupQpZyohNWDsC4TbUpFcpBSoQ2AQGyQNlYcqN6jjYIxaJt0j36PMhzlsjjRPnqfMVhcZn4T1aiatVwrTkwJpWPuhk+w0++tH7YeVU5fi5G9bs0j+t2mS84gfIaS+DuslZoTBshY195ywTVPCSrFSosxQLigqo/TCGXy7vl51/6tF2OVR0g1pj7iqF14N55uMBjSrTpRRccoyDlRl8KDsqTa5q22LLbKiotME3li7Yk5IkJ0D3GavVdazUwJZghenzieyi4STuQrFdiWqR7lE2Cf0NnB+DFNAYYqkokHPtdxSLJG5EIRYSErHDDXdkG5MNwV8fVgfaTAbLE1VZlMmNTdmubrc8KT6pMFPeiFSEBcTxF4sS1D1lIDAbiJ6UZPBR68tv+bE6beGrXzozHvsCIO2pe0r+OPV1Y9L+2LXPMynsoqaye0rlFMf/+XRvdLN7eerli5dJuJMLT8p30f6TIFuFGfeDN+aKpkt5gyW3k2yWMzJzOeVsjOzk6TMzOyBMU4t1ZyUKceppu4pihRXGatWKs5g4iOxKzTo/oiyQuppjDX7DJmJLgRTqmZCRvOyKWqOQHGT8Akl6h9WchhNILpD9xpFeEpRy8W4ora4oovNYjWbKctubslt1EOZi5QtkhXnZSz4vou1de1kEUeFdoQfxTl1slSQn+ehA+JVGU6dURnQaad9bJxTR3Zpdym756NpZR9O//ToX4+XTtg5atQrd5z9+OzHpQ/On/lFxeJyfpL1lHr23B2+lrEjaTtqnt9n/+4b2Z/0SvdeMr81uHvjiwcd5FQbbNPGjik5xW923j9+7NRobrKYcKSKYl08pMHYcNDgT2CVkBAxb5UjsCLWH9HWxq4KGbzelBgfpKZ6bUkhsiyCiC629LXgqNG8JLYx4Z3EA0kHvAeS3/E1+g21rn2ub11IeWWBjhmuGMH0Ib835EVLYqnprAtIaLJfjNg4/MhJR79d937OLzHtS4bMyV/lX43YyK5Zvnnzcmr++rR0ZmOuMXcwx3dfs1idaG3mt/uk9Xufe/aNN559bq/Alo00p1k0p26UbfUCT4y50uSvDMREPLaIaZ3qjQTWBdeqqzzPZ8Z6YwDdCd70gOZFt9+kZgoD+BUlTXoEJ2i8KBypk6c06/B4vnPBc1jYVOqb5J8UKE2RdeMnkvIbmMxi+b/i5eUAjQPWPs8/4N9MPDxt9JH79h9u2LpzT/Wm558ctf+BWUfHfc2sj2HI37jm0x9DoYNX5das/mP1trkzZpWnpe8OBD7cteAlMU+BE8TswATzwj6DU/A4J0X+gQYJ4RUjAYtB8sp9DF6QzbRobS1RakmhqvAK8xQGuctvEf6f00fqaxgi3WC4RyozLJIMKhOYmagOZkPV29hY9S52jzpPXcYeUavZBnWzRdOZpkji6Ct4lJKmmkZ+oX1aI+GgX/6iNUv+4pKfbGwW/0U5rXPEZBgZ7k6s2sGsNqud2WzWgQ6fVa12QXU8EXKbz5bksKIpISkPEzyar0tqEWS1Rp0i/g6+dPaU2pnV0ncMC2ZcLrmKbwkzzvB2hmfOMMY7BjDzxU9Tghp/l1cRN+/P+rGHPlRG8Hr+Ff+a17MhLJElsSGtf+af/iBJbCubxCazrfx2vom38cc6dc7W6dy51+vwisRIubIwGu1yvSuK8Sxsy+kE+dXKZkXVMf7oe+8pp1r1vFHkJM+RTjLg4c68UfJ1Jo7Sr4kjA8+z7ifiq51yNTwRWvtr3pialGDvaUhwp3bTzjSSkq7MG5v1grR2yPnbvFHrShwdmbTYe/yZ2Zk3Z+KE36dzvzXeaDonGLg8ZNbxO7e+Nnfb/C//g3/Kz037YVF5ywMv76vaUP7leyzup3v+qmx5t6DPojlT7vInZJ3ec/rznOwPBg1e/vD9C/zxPQ+8dKg5vSu21ZH+jOCEXmEPVJsWs2rNKGlmUBJsueA1yS49G3NG56Pzt10lMXr9pRM3QvrKAk1j3UWWz/z8C36MD2Sb2S5Ww6fyYj5Jyb40l8WT7D1Y3Da+ni/iD/ManXd8Ql87idsiOF8nsiho7eW4LGjiJ4Igkpxd/EQiNvtO+FpwMtBrn5QDMKcZzeCUiCuaDZQYqOKkyYlmo7hA7NFQLbijQnFbUBcGJsVs6eIuRc0iCl+RBFzeRUlMF6mhdQpY9aDsYA7JYXAYHTAW5sAMWAUmAzNSiDbJsSxBGsPGSsXWu9lU6SEiKQvwAXmu4SFjFVsuLbI+KT2FNXJclFyK7A1TMCjt4+elEC//Sir8aHn7nctPKfb2BNzZmsUq+GJdR+IdiMjpkqEwHAAliVVjUrXR9axzp6favta4yieB19lbzotPsER9tLmt8fK7EN4kUrqcEHHYFKcqd739kOOufC8iH+R7JNds/nWEP8dns5Vs4uPMMH1G20p+nn/PYpjrD9tPsbXb2itG3cqeYvex+9lTQwb/x50l/H3+If+Ivx/SY9evHMsAWcT/98uvwj7i/0YZBl/m/82UrIQtopZTbCoxzTApUboliDZRrvp6ueRSRHV/q9f+ySe3UH+WaE0LG6wOU0O8Z5WjPml9ArhcN8RbVWPiFZX/zprWod/UtK4s8l9R/M8QKQh+1VXnb3/s1+p/v4YGKbuzhCWNvKL2X7qdpGGi1iZqIJAAA8JJUMmWy/ZK23KzqCXF1YuXUi4bDHEPStTamrteSmn8oigd0cwdSVrSoqQ1SZEkhV3h7F0VwdTOl1N47qZnil87dOi14mduunHrhHb+MevJ1Fufk/N3ZGWdPXHibFZWbVoaTcjOXKxfUNf/TtLXWL2W64b+Ye+v1dxVZrbPXW+1mYxuy00SUV+PcOnC6Ho0514u6U73HBAl3RiKINGE/nI9MJ3tFCXdl+vrr3t19ttH2J/ZXmlb+6TNm/dvkcovRXaUTbmA24WtlrLPpAppqfDnPbBRkslNtTPH9Vd9eupSKiW1fyUt3SLkXU3y1uhxSHCdtBgVbJVWiMSqEW/sVi1iXZG61rsqZE01eRN8MV5M8etkh4y6OYqrbc2/hv2w+xgcYyekE3hCPqYcUynb2uWTJvz2jVpU3RJ2pU+XXwVKWzoZDTONeHoEsZ7+u/7wBVP4hS95Oz/PilnSiKexfxenkeYR7+E/8h9um8B/+O5r/ne9sESByRet5xCmykGdB2SGXWq1rFc9XzZSxoSdsT+3qTEKpdr5nF0OEez1tE4vax7F8e0zpOL2uvdEwjaktr1Ar7uJmrVa5kon/BN1t/6wUh+rjv8olasuypgLwg6VciG7zQDoUiHGrOfIMSIOmq/ILs0iJpJdRus85IxMlTxuV1wwXcrv7SqQyiuXLF0Wqal+Yr3q+ppfc+4c7//Vd+zQ55+xxhYabwuNN10fzx92GMR4BgYWlxxjBBqv6OKv/cbkxbo8bskQ7OPK7y1toS6rayLLli5VXS286LPPeb/vvmLvnjvH3onW5PkYebz+PrUbDAsHE6zJJldlTGyDAxvSg/UZ+0wNjjcTk9MTwGi9QXW5AoMy9ZpVtJTd2Bx1fH5K2EIheX/3Rd0j3X/n/XGa9GssvZp1lrld4sVbfh4+t7X6ia1bn6jeWs9566Qdt9yyaeSfdhfuWvB+W9v7C3YV1ktXHzlz5sjhM2e+41/yb5N9r/Xo/uZbt0+ZTJRFVAv7TZ5S+2/r5DRAkb5Oxt0eX2qSIesq6Lpntn6PRGupQv9ZUbvJJkX8QggTA+PCXkVjVuOLKqsiFav7zFKMAQwmxWhzWEa4BcHRX+hZoi/07Ppvscj665JGlx6pm3PbyL5yhULYnrCn2BPxCHpB+khm0QJ6MD9P1IalX+qm3Miy+YcNdXU731TdTxVPnbK6LRs/XH3TGy9FOYL8qM4RYqBfOJ74gaAJLs1slGTBEgY4BU3QXxK1CWKu10ubBMw7PH7PAM+dnlc8is4Xorw7lCIotyzyUbaOP7phw6O8LztySRDCS/w9Jbv9z49XVT6+7ewnn37Zvh1YRw0v0zmeBQaGYywSGKqVOlhsVYxqoeB71t/xveYo79KZqs77bGFbsa3Ettq22abzPk3tzAGOvnfi7I0DKu8nEriO/3ixtkbYImNBPluiWEaz9YftJtVs+09yJ9Ay0OTWzjTpJbfspjbSck7KvxfcM6TRBX0emtPrtqzUYdn9i7J6XnNPzrjbrdalTkdOL99tV9M671GScZhaAEkwJZwGLoPdIjOXwWGRXQcTDPJBj+V7r4PZweAZEzvXMMY4x6tdjPLuqGsVtTUViRf0l/9yQGTJIju+feyb4O04QGN4aQvrJWmWEX25FNRfzQlSKWJNXhTV2wpjU2zpadJCqez29HDoN0fK+AJ3zNCRVeu8KV0/dDtls+TzOFItI4y/KmySdsNrMl7PZE3/jw5ih53S2HVpZF0ambZOaUTNeuVhvvcptYwvj9r929TfAOpPJQyzyoro0SBLs1WDdqYlWvfOLfxtrwa9V4Mov3f2GhPMMATZnid+Wrl790rR9U8/QbR3Ub0CsIIs3UR7HzFJBDtUQAcbRenEQ+xh9rh0SDoTSA/kBPoFdqSkkocCBCDCRrISur6w83oMXS+8fP1//jAa4wzbwDayTbRFOrdDtB1hR3RJoh9f5/4qyNX3sdAT0snOnBAHHho/ARKhF7golvsh/jcjZOijCM6VTWgJEIS+nVdSqBVAKjHFNEJoIAv77z4G6A5Z5E1m6AN5dJypn/WSXozk7TL9VkhDJuhBK/L/6kfr3Duo5UDvf7ue/39aAJYP9UCcg1hvLWxk2+iojE7PpDMRaRcsg9l05iA7xlZIPencNrgAJ+nOKjiGtTKwYaT5Y3T/aUWCi2w07KY+CpmbFVKOAvJN8m55pFwvn5NPQIE8Sz4hl8izGAUpZYyyjVohviu5CJf9UM8+g1mwF7/FPNwnXy/b4TM8gbXwFY0iVvIYrIYtUE6yuNl0qJDKpZF05rByAjbQNp2unyArPUnS7WVL4RQ8ibI0BDaxUzSvY/BPWIqjpQoAzJPKSP7D1NcJen4DzCLkP8XMwKUsOkfS01iT9e9k7Kmc0rcL5GXlMBq2qPWqm7zzpK6xbewga1HXQQRO4h04Ez9hy+SgvF0eAqujGsASWE19bxDPqGVsHs1dbOWid2muXMJq4Vu5xDCZ+n5XzIjG3C2NpBmVwT5qc1WN5tSfLcMVJKm4mgwnDMPkbHqeejAspFkDTMd8mEa/ymEn7IKeWAOrqSd9vmqB8k96cqP8Bc15NXtU+iecwOvJS8rk86RrckjxRup1g6ro2WSPgFYnhYaW1oVvGRs4Mi6lZ4/fHQY0Q6AOiuts8wL1HR3FY+UkZVyd4q3DkLFODgW/+J8uftGzx/DisYG69kHXd/Y6qOR6OjdqLP0UR3Sazg+6Xr8mBq1TQvQ3tKQuMGVq4BHtkWC/R7S7+vXU3zGCNLH+69HPL7nTUfQT+I26DZ88be7Rtf/547YR9nGmM3QoLrKokZO+7uPJAHb+88ett9jHdZ7/9XM1WWiZUkP28BXMNByDvYqbrHEY7JX30bVzUK646DhIVtwCM+naTIn4kHy2o1XOgulyGczU74mDKmrbyW+A9iup1dB9m2j/BZ27QPtSapuUeaBJhfC2shqO0nEttcXUNiptcFQdAbOkO+i8G6rUTDhKz38i7lfz6Lx4huQS45E8O6Wzen+r5Q1wVMiFfqijtkXIJ47FXKQPIVs+Sf3c0VFD/hokZ9pDe7J7kefqn+upkb7YIlIu/ZaayU9G0+weollQgqNSuCRGDoZ7SaVyZ3sQwNRErQXATKhuJou0EIZb6Lx1CIBNNOrPdoF0nkON7nPsILhbRY2ih5PGiyG0c9MauekeD/UfW0qN7omjMePTqI0ASKB+Euh6YpjaXygQzKB2kUA+QO0Xcgm6J5meSyZZfGQDPrrmJ3n8NKafxgnQ84F6Cih0LoWeT+0m/mdUX/2raY5ZMJXimKjKPCWsRfZIsbSX66VFYaJw2OrGf4Xwl1z8uQb/acefOF7k+J8h/NGO/6jBCyH84ZFrlR84nq/B72uwpRW/a8W/c/y2H34zEM9x/DoXv2oepXxVg810Y/MoPPtltnK2Fb/Mxi84fs7xs1z8mxs/rcEzHD9x4V8X4uk38C8cP6bbP16Ip5puUE4txKYb8ORHScpJjh8l4YccP+D4Z47vczxRg8eP+ZTjHI/58L1cPMrx0DKncsiL78ZiI8eDHN/h+DbHAxzf4rif45sc93F8g+NeJzZUhpQGjvWvv6HUc3x9zwTl9Tfw9UXynj+FlD0Twh24Jyz/KYS7Ob5Wg7s4vsqxjuMrHHeW4st23PFSSNlRii/VupSXQljrwhdJ6BdbcTvHFzhu47jVhVs4Pv+cXXk+F5+z47OlGKFbIjW4meOmZ6zKJo7PWHHj0wnKxlJ8eoOmPJ2AGzR8yoxPclxfY1PWc6yxYTU9VF2DT6yzK090w3V2fLwV1655Q1nLcc3qCcqaN3DNInn1YyFl9QRcHZYfC+GjHFet7KWs4riyFz5C03zkWlyx3KKscONyC1bRiapSrCRNVYZwmRP/yHHpEqeylOMSJy7muIhjBcdwx8MLFyoPc1y4EBeUYvloj1Iewvkc53F8yI5zrTjHjLM5PtiKs1rxgVac2YozOE7neD/He1PwDxynOQcq00bhPRynLsS76aCM410cSzlO4TiZ46R+WNKKE604gePtHMdzHDfWrIxrxbFmvC02QbktF8dwvJVGvnUgjvbgKKYpo+JxpBtvGRaj3MKx2II3c7zpRk25ieONGo7gOJyuDOc4bKimDIvBock2ZaiGQ2x4A8fBNTioBq/neJ3UU7muFQe+gdcOxzDHARyvudqlXOPGq4scytUuLOpvU4rCHQ7sb8N+HAs59i1wK31bsaCPphS4sU++RemjYb4Fe/swz4a5V1mUXI5XWTAn26Lk2DDbgr16mpReGvY0YY9czOoeUrJKsXumS+kewkwXdssIKd2uxYwQpocsSroDQxZM4xjkmOrAFJpnigsDpehvRR9NwVeKyTb0kga9HJNaMXEgJtBBAsf4UowjTcVxjKWHYhPQw9HNMYaji25wcXTSXJ0DUVuIjlK0c7RZYxUbRyvdbY1FC0ezhiaORrrNyNHgRrUUZbookwV4kM4ip+ioKVJPZBoCR1bPSpc9yrL+f/jA/20B/pef5P8CaAoQZwplbmRzdHJlYW0KZW5kb2JqCjE2IDAgb2JqCiAgIDg4NjIKZW5kb2JqCjE3IDAgb2JqCjw8IC9MZW5ndGggMTggMCBSCiAgIC9GaWx0ZXIgL0ZsYXRlRGVjb2RlCj4+CnN0cmVhbQp4nF1Ty27bMBC86yt4TA+BZL6UAIKBIrn40Afq9gNkcukIiCWBlg/++3I4QQr0YHO0mhnNLsn25fB6mKdNtT/zEo6yqTTNMct1ueUg6iTnaW52WsUpbB9P9T9cxrVpi/h4v25yOcxpaYZBtb/Ky+uW7+rha1xO8qVRSrU/cpQ8zWf18OflyNLxtq7vcpF5U12z36soqdh9G9fv40VUW8WPh1jeT9v9scj+MX7fV1G6Pu8YKSxRrusYJI/zWZqh6/ZqSGnfyBz/e+c8JacU3sbcDNYUateVpRl8qrgsBUfiWHDfVVyWgjWxBvbEHvwd+TtgIRZwLDkWdce6A2bdo67pr+HvWHeo98zWI5v0FZelYNYFdUOtgdaQY8DR7EWjF/PE+hMw8xvk14GcgDrzG+Q3I/EIzDwGeQzzG+R37N3V3unj4ePo76o/tbpqn6l9BmZ+g/yWs7KYlWMGhwyWfAu+I99VPj1tnRu1GlpLra1azsFiDp4+Hj6e2TyyeXp6ePbsq0dfmvuuse+GPRr0aIktsNBT4Kk5W43ZatZ1/RYz+LpfnKdgnonfTfW80dPD03EfHfbRkl8WHOCPk4qjjDv3eUfCLedyPerFrPcCN2Ka5fPurssKVf39BcVs9IoKZW5kc3RyZWFtCmVuZG9iagoxOCAwIG9iagogICA0NzcKZW5kb2JqCjE5IDAgb2JqCjw8IC9UeXBlIC9Gb250RGVzY3JpcHRvcgogICAvRm9udE5hbWUgL09aQ1FLWCtEZWphVnVTYW5zCiAgIC9Gb250RmFtaWx5IChEZWphVnUgU2FucykKICAgL0ZsYWdzIDMyCiAgIC9Gb250QkJveCBbIC0xMDIwIC00NjIgMTc5MyAxMjMyIF0KICAgL0l0YWxpY0FuZ2xlIDAKICAgL0FzY2VudCA5MjgKICAgL0Rlc2NlbnQgLTIzNQogICAvQ2FwSGVpZ2h0IDEyMzIKICAgL1N0ZW1WIDgwCiAgIC9TdGVtSCA4MAogICAvRm9udEZpbGUyIDE1IDAgUgo+PgplbmRvYmoKNiAwIG9iago8PCAvVHlwZSAvRm9udAogICAvU3VidHlwZSAvVHJ1ZVR5cGUKICAgL0Jhc2VGb250IC9PWkNRS1grRGVqYVZ1U2FucwogICAvRmlyc3RDaGFyIDMyCiAgIC9MYXN0Q2hhciAyNDMKICAgL0ZvbnREZXNjcmlwdG9yIDE5IDAgUgogICAvRW5jb2RpbmcgL1dpbkFuc2lFbmNvZGluZwogICAvV2lkdGhzIFsgMzE3IDAgMCAwIDYzNiAwIDAgMCAzOTAgMzkwIDAgMCAzMTcgMzYwIDMxNyAzMzYgNjM2IDYzNiA2MzYgNjM2IDYzNiA2MzYgNjM2IDYzNiA2MzYgNjM2IDMzNiAwIDAgMCAwIDAgMCA2ODQgMCA2OTggNzcwIDAgNTc1IDc3NCAwIDI5NCAyOTQgMCAwIDAgNzQ4IDAgNjAzIDc4NyA2OTQgNjM0IDYxMCAwIDY4NCAwIDAgMCAwIDAgMCAwIDAgMCAwIDYxMiA2MzQgNTQ5IDYzNCA2MTUgMzUyIDYzNCAwIDI3NyAwIDAgMjc3IDk3NCA2MzMgNjExIDYzNCAwIDQxMSA1MjAgMzkyIDYzMyA1OTEgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgNjEyIDAgMCAwIDU0OSAwIDYxNSA2MTUgMCAwIDAgMCAwIDAgMCAwIDYxMSBdCiAgICAvVG9Vbmljb2RlIDE3IDAgUgo+PgplbmRvYmoKMjAgMCBvYmoKPDwgL0xlbmd0aCAyMSAwIFIKICAgL0ZpbHRlciAvRmxhdGVEZWNvZGUKICAgL0xlbmd0aDEgMjYxMgo+PgpzdHJlYW0KeJzVVGtUVNcV3vd+98wA8+DOMBBRUQhe34gOgi+SIsH6tigkQltTlHEkVoOK8VFKtLFoJDGYGsdnjFVrI1o7tUZRNG0qJk2RtgZx1SatNdGkttaY1Ggy2k32YLq6Vtdq/3b1nHvOPd+333ude0kjolhaSSCzfMniVHosZQSRtl4WBxfMmb9w6JK5RBBM++fMWx7cPd0aJ+ftsm5WzJ4ZcCW8mkNk5ArOqRDC9ZK9UvBiwb0q5i9eFldIGwVvFhwzr7J8pvgdLninYOf8mcsWGJW2hYIPCE5dsGj2glH2j+RonCFSFaRTkENGUO2R7OzUNc9p3CHbHS1GrdANymw+d20Imeeunbs2OMGT5rHSPGlBg+5WodvdKxyyuz/9eJGtH2mUKb4abD7qRePyEnqTPVbFONO6uHrEeJxppm+SZd7NbfY3y2bmytbcPITyPLEuzz6v3nUNddlk6+k94YjPzH3f7+fc637zut8/WEtMv9+WoqUlpnnSPdGVnp2VPTRnVJS3RwUCslRDuHyylslnj7H9WDh88OTBcHmf3tpnB0/afFsKK8rr72bibHTVT2nav6Vv34pyeWvZ1EgtMl+jBtqu7RUUlIYsFGanfohq6QlhTmkt2lo9Q7i9dIPaRHMNtaDBIG0CZQlLdEHpdFMrpsPiY4Tm00bYbQYZU4zDxjSj0fjAaKVhRpXRapQZVVoWdqlH1F5ZI3Ba99Kb1JMatYtURcdxFVk4YRQYbrqIVjTQFYliiP8Wqqc9VC25+LRKWqFX69OEeUO10laZlSJv1XZobZLdcW0VtdNmGPo42qG1S10tdItWoVhfIfcqSw9K/m+Ir1ax30pVBql2LY5YHyDc4c57NqtzT0GGau+cN2iFRC6mPbZGm8+eLlGiHdurndKu2TbQTmrD17EQb2u1RrrxsjGO6u91AGVUL763Rm1sQW251B6d1VHv+lKjTGugq0aZfZb4Ph2tSGIe1qdJRUE6IWupzZSaRmm1WCuZRqUp1GqfYGSKvXiw10jVRJXIprlyqqaDdIgyEKJ68dRZr22YuiWW241LUnO9tk6/Ra0ooH4UNK5Lr8lHFCI6arcpA7pGA1PNsG6ND4Tzppak/rI0LWPgv8FU054apsKwa3lqY0dHYYnRTZWGVfcwrJiwYaVf+k/CSxkDJxaWpIb/MabgC69jygqEKyqRYxQJLfyYgk5ZNGhYWfKMLwunllek1pl16SPrzNkjM+RTlor1Rxtjb556/BvxuZ9QzxiKjrYLcQP/+b59/u4kd2nsO9Hvn+5ZdO72+ZxC5Obb5yNT3aVf8P8autzQoFoV/XY7R0H0f3MvHoppAFWQU/4OJm2JejUS9SR5G436yryOO4yID59Z+NSP2yHccuMTxk3G3y187MZHIdyw8GHdaPUh43oIfwvhWgR/jeAvjKsj8ed8fMB4348rl4vUlRAui+LlIrz3bqZ6L4J3M3GJ8SfGRT/+6MMfQniH8bYXv6/BhSb8jnFe1M/XoP3cWNVeg3Nj0fZWN9XGeKsbzjJ+y/gN49eM1hDOtPRQZxgtPfArP95kvF7rUa93x+kkNDNOMX7BeI3xc8bPGK8yTjJOMJoYxz04ttpSxxiNR5tUI+PokRnqaBOOrjSOvGKpIzPyOnAkz3jFwmHGT0M4xPgJI8z4MeNgAD9y48B+Sx0IYH+DV+230ODFPkl6XwQvM37I2Mv4gRd7GLt3udVuP3a58f0AdorKzhBeYux40al2MF50Yvu2ZLU9gG1bTbUtGVtNbInDZsamkEttYoRc2ChGG0N4YYNbvdAXG9z4XgTPr29SzzPW189Q65uwfqVR/5yl6megPs94zsI6xrPPDFLPMp4ZhDops2401j7tUGt9eNqBNUKsCWC1dGq1hVoPvstY9ZRHrWI85cF3GCsZKxh5HU/W1KgnGTU1+HYA1cWJqtrCtxjLGcvcWOrEkjg8wVgcQVUEiyJYGMECRiXjcca8NHyTMdeTr+YW4TFGRQ3mCAgyZjMCjHLGLMbMkSiL4FEnZjC+xvgqo7QkTpVGUBKH6UnJarofjzAelsgP56M4EUWaqYq6YJoPUyckqKmMQge+wpgy2VRTGJNNTGJMFMlExoTxppqQgPEpLjXexDgXxjK+HMKYEAoYD+kZ6qEI8psweiLyGF9iPPiAVz3owwO58eoBL3JHuVRuXkc8RrkwkjGCMXyYTw2PYFiOqYb5kJPtUDkmsh0Y2gNZLviHOJSfMcSBwZkONdiFTAcGZcSqQSYyYjHQjwH9LTUggP79vKq/hX5e9O1jqb6j0cdCb8uhesfDcqAXI51xfzzSpM40L1ID6BlBDymhRwApLnSXDnZndIugaz6SBSQzugRwn3TqPkaSGCUlI5HhYyQwvKLgZXikVk8+zBrEB+BmuJxJysVwirYzCQ5GnIlYRoyoxTDsPtgCMERoyA1IhLBg+YuaSs+AZoIYWqMWqF2nDfh/GPS/TuC/jpTPAddlx60KZW5kc3RyZWFtCmVuZG9iagoyMSAwIG9iagogICAxODYyCmVuZG9iagoyMiAwIG9iago8PCAvTGVuZ3RoIDIzIDAgUgogICAvRmlsdGVyIC9GbGF0ZURlY29kZQo+PgpzdHJlYW0KeJxdkM9qwzAMxu9+Ch3bQ3HTcwiM7pLD/tBsD+DYcmZoZKM4h7z9ZDd0MIEN0vf9zGfpa//aU8igPznaATP4QI5xiStbhBGnQKq5gAs271297WyS0gIP25Jx7slH1bagbyIumTc4vLg44lEBgP5ghxxogsP3dXiMhjWlO85IGc6q68Chl+feTHo3M4Ku8Kl3ooe8nQT7c3xtCeFS++YRyUaHSzIW2dCEqj1LddB6qU4huX/6To3e/hiu7qa4R4GKe58XrnzyGcquzJKnbqIGKREC4XNZKaZC1fMLU0ZwxwplbmRzdHJlYW0KZW5kb2JqCjIzIDAgb2JqCiAgIDIyMwplbmRvYmoKMjQgMCBvYmoKPDwgL1R5cGUgL0ZvbnREZXNjcmlwdG9yCiAgIC9Gb250TmFtZSAvU1NDR0haK0RlamFWdVNhbnMKICAgL0ZvbnRGYW1pbHkgKERlamFWdSBTYW5zKQogICAvRmxhZ3MgNAogICAvRm9udEJCb3ggWyAtMTAyMCAtNDYyIDE3OTMgMTIzMiBdCiAgIC9JdGFsaWNBbmdsZSAwCiAgIC9Bc2NlbnQgOTI4CiAgIC9EZXNjZW50IC0yMzUKICAgL0NhcEhlaWdodCAxMjMyCiAgIC9TdGVtViA4MAogICAvU3RlbUggODAKICAgL0ZvbnRGaWxlMiAyMCAwIFIKPj4KZW5kb2JqCjI1IDAgb2JqCjw8IC9UeXBlIC9Gb250CiAgIC9TdWJ0eXBlIC9DSURGb250VHlwZTIKICAgL0Jhc2VGb250IC9TU0NHSForRGVqYVZ1U2FucwogICAvQ0lEU3lzdGVtSW5mbwogICA8PCAvUmVnaXN0cnkgKEFkb2JlKQogICAgICAvT3JkZXJpbmcgKElkZW50aXR5KQogICAgICAvU3VwcGxlbWVudCAwCiAgID4+CiAgIC9Gb250RGVzY3JpcHRvciAyNCAwIFIKICAgL1cgWzAgWyA2MDAgNjg4IF1dCj4+CmVuZG9iagoxMCAwIG9iago8PCAvVHlwZSAvRm9udAogICAvU3VidHlwZSAvVHlwZTAKICAgL0Jhc2VGb250IC9TU0NHSForRGVqYVZ1U2FucwogICAvRW5jb2RpbmcgL0lkZW50aXR5LUgKICAgL0Rlc2NlbmRhbnRGb250cyBbIDI1IDAgUl0KICAgL1RvVW5pY29kZSAyMiAwIFIKPj4KZW5kb2JqCjI2IDAgb2JqCjw8IC9MZW5ndGggMjcgMCBSCiAgIC9GaWx0ZXIgL0ZsYXRlRGVjb2RlCiAgIC9MZW5ndGgxIDc1MDAKPj4Kc3RyZWFtCnic3Vh7eFRFlq+651a/b/ftTj/S3Uk/0nQCAknIg5AESPNQHkGMwDBBiAQIzWuAaGCAhUgYx1FRRx00xgiGYAZRXjFkFcNjIkblKTAGHQV1WPExY8OwLiK2obLn3gR1/Hb223/2m/22K1W36lTVvafO43dOhVBCiIHUECCBOYtnVZ4t3HSeEIuOEOGOOb9cFhj+6iDsWytwPCVaOW/xdGHRZUIS9uKuHfN+sSo6aPLYbUqfEPOM+XNnVZj7HNQTYsf1ZPB8JJh3ax/E8UYc95m/eNnK1SMN83HcjuPyXyydM4uQPc2EOAI4rlg8a2WlpkwzEMe/xnGg8u65lWtmbfkcx02EaJ8nAonyWjHKmpBbLfHvJyJNxYUamvoy1bEHBZFkdHTGBhG5M9YZy0ywBq3hoDUYFUlXFXi7PuW1WvO1r+7W9MM9hJJo9ydsBrtM3KQw4jHJeuIESXY7d4G8S78R6jwJA01E098jd3VkKe+8cCUm8w75DastH/8yWzO8M70CLQubaShArDIJZjld1nQaShEcdlt21uA8NmPhZ9X8IT6BttLl1Z8tXHSq6u1Y7O2qU4sm5Q2hjXQujdLGIXn82LjR/NoXn/Nro8chXwIpRb7SxNXESFxkYCRB02gjjaajtrpE/UjLBBjpKEyUu2JdN1i6lPlyXkKRe0wC0DKaonHYnfjt3JxU6GFKbYXXVlRXr1i+Zs1yGqQ38338Y/4Rf5WOgdXbGxu3K5USfpjHsBymQ6gdy5AeGb2Icm9FXsJkQaSf12HTi1oS0GgTLWcDp0Jw1LcnKUFL7DaTTtKMtUu2sX6vlCynyl3FzZYppa+SZBIZMq1rqMKuIrRBJGPo0AtXhl6IZVnzsbjyM2nE4k/LTCtJq0yrSXssbXeatowOp9lZTgdqbzjFg4RSNFrsqx2FGHSo82Lb6H2Vrx3ldZTeMjG6VOB1kUnzKnE4f+T2ectaYOv8xZc+uT5VGCsleVYs2tZw/QNhbNuiFzZdf18sb5pZXklUWe/gU9mdeD6ZJKEVJLsaySmztZGd0h0119GPYE+yZ6QxYheJJMjJKPWsrCuq3C9cuHIhJl+4lNl6m6/cp1jB94wp8g6lpCb8SBWCjdfT6PjW5SepgV89uby1qWr16qqqVau2XG/VGJpml/FX+HUsr5RB3gsNDS9s27x5G8oefQpiyJuV5EWcVrNeoyXQbnzCfFS/R2vQSEQn2xRBJyiC1nW3D5nWEctCCSNrXR1W1UapYo4/FpoLYhllGeufVPi5eU+17aa+kOF0vPT7611i+d4lc4EpOvcTwtxiOdGQdyJpkCwyUUimAlMeIGjQ25LR5cICkI+ZhoFAmUi0cmdrA24UyjpcipZjWfmZxZNLtTK7qJV1vZVdnJZCI2tQ6oKMJSBkChFhqhAVaoTHhM1Cc29px3IKy5/VchmLmxGBSmAQHSSBJoFHTCV9aH/oJw4mOTQf8sVM3S3kFjoOxonlupWa++kDcD97QFNLaunT8LT4JKvXbIOX6avQp4yUJQT16ARBPzqfizrpPD6GrxDLu+Kg+W4zueF/4hsodwNa/abITXoNcfuN5I+uk5oG8ylr4Lj/WFJD6Ki1zkRCLkiU9JJxmB8keyGafazjCtqINT8/X1VEF/rnZ5euXsrvgYzIhIy0YYFhwaK0WwO3BssCZcElgSXBewL3BCvTHg48HNwU2BTcGdgZPBA4EHRk+TL9o3wR/2RfiX+Or9x/n6/Gv8H3mH+Lb7O/xdfsl8t+5O/DKBpgLiJRSmpuTp9g9g23QaUHRGFL5V3Tb5+7ni7gT41tXbfrfWqhKe/85rdVb/6s6otlNINK9NqE8aNvfXxxv/uvr9saLTu25Y29ST+7LT2dWpOS/6biANois6FMXCQ3kiiJhBrO2k45jsp7zFSQyBirJFlkBZZU/8gYqriHIoXM1nJ3jRv9gyJ76MJpPzVIZuN1kuwYm15Zo9jk7S8vOXREePH61KX0mceXeEJpO59W/XV22aUePPKiTzSxZ0kCWRzxmJnOAo1WukfXSAw6o17Qo6PKNvMUew8AFTfLU6YXN1uVxjZlOrqJWcGjoR1dQzs6bKqOOmJXhipgpABRYhEpSkDjJGCRLdYSoQRKHOVCOejRaqjCstXuLMQOytgasmZbhWx6F390+Iy9/ETnSy0t7Fl+qJvw8MS8bvJSJz1LCR3+PZ4bUHZ25H5UJEgcf6L647pO1mCi7yU22I6a6pK8DkHnkMhoQbIUJqEYr8Q6VLhUEP6CzK9cki8pESe5KFmRpSPoo0qAsX4fegKE9WicGbr2SRsfvuti9Vq+lp/iu2kxTaE6Oow/tqJ8/q9kITt6zz2jRvNY5iCaiw5gowX80IZo9fIlPbY/A3k1a+wqHg6JeH/AwzrzUfocqEgYQUwsTFa5zFIAJ/ZTMFSFpVqjwhxqGVQYDKnWClvpfF43vmX5SX6VGk4u27MFgbDq7lWrYL9Q+m1sy5wZdBwFLOPKuo4oSKiioaJ7A9rgQnYGI392xKwR2skjIh0CTjKE6eTO4mYD6tusapkpWlYjZAaymElbInqKfq+qMGhg5dyKspHZGf7hdxPFFvXdC9HnZ6OO0si5SEQyCWbjYJ/fxzRanZ6JhsF+vy9sMPr8iEDHaadoP+7oTGywig1hhIG+PoPR79WSyd5JZru2JOXWvgoOdMYuoAZVIOjJHL6+JH99yebqxUXzRQx+vY9pKS06I6VlkTv1er1BbzSajJLewkIek0fymBMtA3Tp+nRDujHdlC71C+TrCvWFhkJjgalAKtaPN4w3jjeNlVaYVkhtujZ9m6HN2GZqk8JmjVlr1pn1ZoNkzJOK+s3s12PGPQ5od/qp6HTYRTTmNKtqTaigDIwXuTmDleDqqnp3ZnRO8awimnCQX+PxpRerF51ftmDhuMVFf2u/0jXnA3EYv5yZmZ3bP92oD23evqc1FKJyTk5BfmaGpPNt+X3LDh/p7ialfKmYK662pRIHIbKWOAlmjgpdwVhNPtK1mF1qEVfaUA+6VmNRpl/bf5Bqi5ifaaKYnyl5UBbmQbtsZJdpo5IHDbTkwUBH/5/kQREjcbsSZHeGu8jNFHDsScRsuTnCj5MhiDYfOtT80qFDL9H5tI6jMfKn+Tz6tPg+74p9ybuo+GWMitTFK/iTvJZX0I10IV1EN/bkC9jY0D+U/LMfWuGHZI/4nMAoQqKsk7uGqhEYHSMzoi/Rl+sr9TV68Qfb20GjCsrxerH8u80aOz/X43P8FmYWV6HH9SXFkdQkCxDHcWenu8GW3Gg6pT8q7Qk12j4gpyDVRCRzxBEYqSnsdyPWKHHmQo8HookpJodueFP5Tb2ZaQrJzVE80JUbVATwg7bhx6niVnTHE/wKNZ1Y3jIe3XM737+gY86drdObm2JL16ysqlyz5uDsGXRU/Ds6YsacrV1W/hX/JBCkrsG59U2gaaqtb2h6srYJz7IfU4N89FEd6iw94iDt+kdou1MnOA2EDZTTiVMPPVqz9viGKquWEjdVUKOHmxANBkSX0+awC1qN2I8Kw9bHvr128frXtJZOobeuWBCNLljJm7EsFFu67vrrxx99QUOzls3l155/gX8zd9ksxZ8V+0K7w9w+L+JRfdZ8XOo0NFrFRhf6rEc7UiL2wr/P7a8oHprZOtO71quC2A1X+XuoRefIHbfhttrnn6+d8lRkys6f89P8RTqVZpRuR584l5W5e9Om3VmD+Fm/n+ZRB5Y8vxq7qIYvFY5hLwFjqMmglzQkQU9k0Nvlzs7jmA6jNDqPdx7PpAqWlR4g9u52PIkdS2SINW/INER9h12DIT6D3vDYNOGOgrzVazOjOTRrcrBgRP+BwxdmzJwuSXWyJb2vZ9JQRRZNzAszNPnER45E7C6rDHZJRwkkMXeiXTLomX0/TSJJ1EsYTYpYpDf8VioTnavGrasx+NWrVK+y5CuoOLQwq1pdas0kxc36XuQ9QPwqy34sPSxHpuiJnmJgBpPJJJnMJotJNllNNlOCyW5yWJwWlyXR4rZ49D4P8VCP4IEe0PNavLLX6rV5E7x2r8Pv9Lv8iX633+Px9XUYqZL5pKWmKQElmYZUwPL3iGQYzVYlJAh5oibD3Sf1oXllfcb1G+YMW/r0Vfqj2JSwIPqHF+oeeMLr62+RI/nYSyQ92QUQ5TZsIqIwEZ8+jIKAKcNa0k0n01l0Jb2H/k54UzgXSA1kBgoCO4IpiGR4TyWb6SRajvPVvfMJOJ///fw//lH8xjlajwjzLJbNveVNLIfpYZw3/re7/6c/xYb+q5/1+570D/dq1dakxF60W0JsvXRADxeIiD2GEsIbP94W/q/+5N6n5Z/FAF41smkUsfEv2B9GtpA4+JVbEIkiVXnuoFNIDOdn48p14n0Ic1G6WEQ8xfm14gl8hUCzyWxyF/bCYhPdj9HyU9y9jj7CxrI7lNXqh5R3XWWv08ssX8gnpeJicZjYIq4TW3DFcjEqriPN2OYLp8WN4mrxJOJjqcIZnaBUNbrV0/E0ROqFejqauulo4QR5TeW/CK20kB1jx8gZcoaW4ModZIVgoG/Rr/ACUUpbcNdVcpX6cZQr5NJL9HPkuI6chlJmIPXkUWrD0X5yAvn+lHxFqvAKESWPsjNCf4wWr5Pz5D2kE7KQCtgmw0B2Bstlso0sRMmcx+vnGY1dGxSjwjUSo/cKW4VrNEQFLDbqR2neCSfEcvEt8UGcRelQAbLBDyOxnaGsYGdoPXJxXhOlq3CdUlbjd2LC68JePONB8iGeC78uzBBWC/XkQ7qLtlHF1u+ju8Ry7WzRS+o19WIpuaTIhpwWTqA8SlR5PEQe0gwiV0UNuQwTaLm4TZEYCbPXMP8PasdrbHgLHa+9F09CII+sVn3xCCXstZ6Cq3SaZFIrpsGzyLsgVN+QG11FTgj5MJtsVMsGupdswOypiuArIPUVrYaJePkmAwJysxAeV9Ecub00cHhacOCAnwwDsjbQTEqapVWBvd3dJaWil01rZknNENY1i+HQ+X80eX7ggOKS0sBe2vfm0b2vvbl8NBInl2JXGSEZ6TePVueUrzazMP6NK28OzJkfWC+vDxWsl+cWDFRRVbhzrys0YexMy9CviV+nmus77xsCN57f3N21y3JCPxfXKpO0x3EQgBbzZHTh4Dd3f5tlOdFL/+GXiN4RZR9jXUtKdVPJi6yN7ICvyA6WR/wsSkpZC47fIV62mJQKRxCu2sgMtpwYxNfJQvEgzuMaDb5DOIh7cE7TRPYrdLRPDcJbU+93JmC9gAxV4kFKsMZQmxWEiFjZyh7w07Qit+W9tQuT2VJC9M1YEcn1uN5Qg7UTQX0zAmpfrJgrSTnK/03VUyXCRNKfrESsFRCxIooU2EUhiE9xxK+FGppKOAEaRtQG2ocGSQGG6z4kjqMQZtWAt7weWoq6TukDDajzfrIPWx+pwDZZnU3CvAgw4Puw9agUt9omqq1LbZ1q66B2xHdGHepI6QNNUPs2tbVQM6nGeYs6UvpAJWoiDyNNUmkSaSciNVEjmYY0ZQawrUGakRpIKtKUGcA2gjSFAlSv7tSprRYlorTKDk3LU+lsRALVqOdiaiuqq0A9kaBSqNqSSHc1dA8HzqHruwGsi8N3AyDO4dtrY9i31XBtDHwTh6scvuZwhcN/7IOvOPw7h8sc/uaDSxwuxgzsIoeYAWIR8cu/GtiXWfBXA/wlDl887mRfcPg8Dp/F4VMcfMrhAodPOPwbh/Mc/szhYw4fxeHDc4nswwo4lwhnN/vY2Qr44P0w+yAO74fhT6fD7E9xeO9dO3vPCe+ekdm7djgjQ+c7RtYZgHeM8Edc8cc4nMb3nw7DqSdM7FQITr5tZydT4e0TNva2HU7Y4DhOH0+GY3Y4emQfO8rhyOEydmQfHKkRD0e63wqzw2VwOCK+FYY3ObxRAR2PyayDw+tJcIjDaxza/1DA2uPwh51e9ocCOHjAww5mwYH9VnbAA/v3Wdh+K+xrM7F9Fmgzwav4sVc57OXwigNetsG/cmjlsIdDiwteckOzE3bje3bHYRc+dsVhJ67f6YUd+NhRDds5vJgKL3DYxuF5Dls5/N4ATRye22Jmz3HYYoYtEbERBdUYh824ZbMPGvDREIdn8fDPJsEmDhuf2cc2cnimvow9sw+eqRHrHw2z+jKoj4hPc6hD66jj8FQ61OLGWl+kG57ErU8G4AkTbEDShmL4HT5+x+FxlMPjTnhMhkfD8FsOj3B4mMNDHNZzeJDDA/eH2QMc7g/Dbzjcx+HXWXBvLfyKwzoONW5Ya4B7OFRzWMNhdRz+JQ6rOKz45Va2gsMvt8LyZV62PA7LvFAVh7ur4S4OlUsHsKUDYEkcFsfhF3FYxGEhhwUc5s8xsflZMI9DNAvmVhjYXA4VBqiIiHNmG9gcE8w2wKxyB5tVC+XUysodMNMAd3Io4xjZrGwGh+l3eNl0Dnfg6A4vTONQGoefc5iK40j3VA4/4zDFB5PtMOl2N5sUh9tx4nY3lNzmZiVxuG2ild3mholWuNUHE4rtbIIDisdbWbEdxo8zs/FWGGeGsXEYc4udjXHALXa4OQ6jR5nZaAuMMsPIEWE2Mg4j8J0jwhApsrAIh6LhZlZkgeFmGDZUYsOcMFSCwgoo4JBvhyEc8hJgcK6HDQ5Dbo6d5Xogt13MMUgsxw45NWJ2loll2yE7ImaZYFDmVjaIQya+P3MrZJggPQEGDihgA+MwwBFmAwqgfwXcVAH9OPR1QJrLytJ8kBqAsA/6hFAA/fv4IGSFFCKxlDgELRCMiAE7+A3g80FykpslhyHJksCS3JC0FzHjcdErgcddzDzV4MaPuoshkYPLCk78mjMODqQ5wmCvgAQr2DhYcWzlIFeAxSwzSwJY2kWzDOYaUcIZKQ6mLDDi0YxOMNaIBgkMEVHPQcdBy0HDDEzDgRmARUQxDlCBAd3KBI7oJTFqBSIB3Usr7nuE9v//8SP/bAb+F3/J5D8BQW8xlQplbmRzdHJlYW0KZW5kb2JqCjI3IDAgb2JqCiAgIDUyMzIKZW5kb2JqCjI4IDAgb2JqCjw8IC9MZW5ndGggMjkgMCBSCiAgIC9GaWx0ZXIgL0ZsYXRlRGVjb2RlCj4+CnN0cmVhbQp4nF2Sy26EMAxF9/kKL6eLEY/y0EgIqZpuWPSh0n4AkxgaqYQoMAv+vnY8mkpdgE/sa8vckJy7587ZDZL3sOgeNxitMwHX5Ro0wgUn61SWg7F6u53iW8+DVwk19/u64dy5cVFNA8kHFdct7HB4MssFHxQAJG/BYLBugsPXuZdUf/X+B2d0G6SqbcHgSONeBv86zAhJbD52hup224/U9qf43D1CHs+ZrKQXg6sfNIbBTaiaNG2hGcdWoTP/ankqLZdRfw9BNcUjSdOUgmqqMTIFYiNsiOs0MgXiXDhnroQr1meiz5hRGFlTiKbgfCn5kjiXmTnPrERTsaYULplr2a3m3bCOTIFY8sj5QnYu4s4nmXNiFn3F+kJmUmBDbl/O1vAd3j3X1xDI7njR0Wd22Dq8/wt+8dwVn18CZZ1jCmVuZHN0cmVhbQplbmRvYmoKMjkgMCBvYmoKICAgMzE2CmVuZG9iagozMCAwIG9iago8PCAvVHlwZSAvRm9udERlc2NyaXB0b3IKICAgL0ZvbnROYW1lIC9CTE5BUlErRGVqYVZ1U2Fucy1Cb2xkCiAgIC9Gb250RmFtaWx5IChEZWphVnUgU2FucykKICAgL0ZsYWdzIDMyCiAgIC9Gb250QkJveCBbIC0xMDY5IC00MTUgMTk3NSAxMTc0IF0KICAgL0l0YWxpY0FuZ2xlIDAKICAgL0FzY2VudCA5MjgKICAgL0Rlc2NlbnQgLTIzNQogICAvQ2FwSGVpZ2h0IDExNzQKICAgL1N0ZW1WIDgwCiAgIC9TdGVtSCA4MAogICAvRm9udEZpbGUyIDI2IDAgUgo+PgplbmRvYmoKNyAwIG9iago8PCAvVHlwZSAvRm9udAogICAvU3VidHlwZSAvVHJ1ZVR5cGUKICAgL0Jhc2VGb250IC9CTE5BUlErRGVqYVZ1U2Fucy1Cb2xkCiAgIC9GaXJzdENoYXIgMzIKICAgL0xhc3RDaGFyIDIzMQogICAvRm9udERlc2NyaXB0b3IgMzAgMCBSCiAgIC9FbmNvZGluZyAvV2luQW5zaUVuY29kaW5nCiAgIC9XaWR0aHMgWyAzNDggMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCA3MzMgODMwIDAgMCAwIDAgMCAwIDAgMCAwIDAgODUwIDAgMCAwIDAgNjgyIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDY3NCAwIDAgNzE1IDY3OCAwIDcxNSAwIDM0MiAwIDAgMCAxMDQxIDcxMSA2ODcgNzE1IDAgNDkzIDU5NSA0NzggMCA2NTEgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgMCAwIDAgNjc0IDAgMCAwIDU5MiBdCiAgICAvVG9Vbmljb2RlIDI4IDAgUgo+PgplbmRvYmoKMSAwIG9iago8PCAvVHlwZSAvUGFnZXMKICAgL0tpZHMgWyAyIDAgUiBdCiAgIC9Db3VudCAxCj4+CmVuZG9iagozMSAwIG9iago8PCAvUHJvZHVjZXIgKGNhaXJvIDEuMTYuMCAoaHR0cHM6Ly9jYWlyb2dyYXBoaWNzLm9yZykpCiAgIC9BdXRob3IgKCkKICAgL0tleXdvcmRzICgpCiAgIC9DcmVhdGlvbkRhdGUgKEQ6MjAyMDA4MTAxMjE5MDlaKQo+PgplbmRvYmoKMzIgMCBvYmoKPDwgL1R5cGUgL0NhdGFsb2cKICAgL1BhZ2VzIDEgMCBSCj4+CmVuZG9iagp4cmVmCjAgMzMKMDAwMDAwMDAwMCA2NTUzNSBmIAowMDAwMDI0MDE1IDAwMDAwIG4gCjAwMDAwMDE1NDggMDAwMDAgbiAKMDAwMDAwMTM2MiAwMDAwMCBuIAowMDAwMDAwMDE1IDAwMDAwIG4gCjAwMDAwMDEzMzkgMDAwMDAgbiAKMDAwMDAxMzU4NCAwMDAwMCBuIAowMDAwMDIzMzU1IDAwMDAwIG4gCjAwMDAwMDE3NjYgMDAwMDAgbiAKMDAwMDAwMjc1OCAwMDAwMCBuIAowMDAwMDE3MTQ3IDAwMDAwIG4gCjAwMDAwMDI2ODUgMDAwMDAgbiAKMDAwMDAwMjY2MiAwMDAwMCBuIAowMDAwMDAzNjc3IDAwMDAwIG4gCjAwMDAwMDM2NTQgMDAwMDAgbiAKMDAwMDAwMzc1MCAwMDAwMCBuIAowMDAwMDEyNzA5IDAwMDAwIG4gCjAwMDAwMTI3MzMgMDAwMDAgbiAKMDAwMDAxMzI4OSAwMDAwMCBuIAowMDAwMDEzMzEyIDAwMDAwIG4gCjAwMDAwMTQzMzQgMDAwMDAgbiAKMDAwMDAxNjI5MiAwMDAwMCBuIAowMDAwMDE2MzE2IDAwMDAwIG4gCjAwMDAwMTY2MTggMDAwMDAgbiAKMDAwMDAxNjY0MSAwMDAwMCBuIAowMDAwMDE2OTEyIDAwMDAwIG4gCjAwMDAwMTczMDggMDAwMDAgbiAKMDAwMDAyMjYzNiAwMDAwMCBuIAowMDAwMDIyNjYwIDAwMDAwIG4gCjAwMDAwMjMwNTUgMDAwMDAgbiAKMDAwMDAyMzA3OCAwMDAwMCBuIAowMDAwMDI0MDgwIDAwMDAwIG4gCjAwMDAwMjQyMjIgMDAwMDAgbiAKdHJhaWxlcgo8PCAvU2l6ZSAzMwogICAvUm9vdCAzMiAwIFIKICAgL0luZm8gMzEgMCBSCj4+CnN0YXJ0eHJlZgoyNDI3NQolJUVPRgo=",
  "source_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "00022",
    "financial_institution_compe_number": 329,
    "financial_institution_name": "QI Sociedade de Crédito Direto S.A",
    "owner_document_number": "32402502000135",
    "owner_document_number_formatted": "32.402.502/0001-35",
    "owner_name": "QI SCD S.A."
  },
  "source_subtype": "incoming_credit_card_settlement",
  "target_account": {
    "account_branch": "0001",
    "account_digit": "0",
    "account_number": "07834",
    "financial_institution_compe_number": 329,
    "financial_institution_name": "QI Sociedade de Crédito Direto S.A",
    "owner_document_number": "99195609000120",
    "owner_document_number_formatted": "99.195.609/0001-20",
    "owner_name": "Giba"
  },
  "transacted_at": "2020-08-07 14:45:51",
  "transacted_at_br": "2020-08-07 11:45:51",
  "transacted_at_br_formatted": "07/08/2020, 11:45:51",
  "transacted_at_formatted": "07/08/2020, 14:45:51",
  "transaction_amount": 93.84,
  "transaction_amount_formatted": "R$ 93,84",
  "transaction_key": "bcebffa1-bab5-45b0-b0a2-894f45fcc004"
}
```

### Error Response

STATUS 4XX

Response Body

```json
{
    "title": "Título",
    "description": "Description in english",
    "translation": "Descrição em português",
    "code": "Código"
}
```

---

# Consulta de Transações

URL: /documentation/movimentacao_de_contas/consulta_de_transacoes

## Request

ENDPOINT /account/ ACCOUNT_KEY /transaction
MÉTODO GET

### Request Path Params

| Campo           | Tipo   | Descrição                                |
|-----------------|--------|------------------------------------------|
| `account_key` * | string | Chave única de identificação da conta QI |

### Query Params

| Campo       | Tipo    | Descrição                                                                 |
|-------------|---------|---------------------------------------------------------------------------|
| `date_from` | string  | Data inicial. Formato "YYYY-MM-DD"                                        |
| `date_to`   | string  | Data final. Formato "YYYY-MM-DD"                                          |
| `order_by`  | string  | "asc" para ordem ascendente ou "desc" para descendente. "desc" por padrão |
| `page`      | integer | Número da página requisitada. 1 por padrão                                |
| `page_size` | integer | Tamanho da página requisitada na consulta. 4000 por padrão                |

## Response

### Success Response

STATUS 200

:::info Sobre o campo Transaction Details

Este campo é um objeto com informações específicas ao tipo de transação realizada (pagamento de boleto, TED ou Pix). 

:::

Response Body: Transações Pix

```json
{
    "data": [
        {
            "account_balance": 22403.11,
            "agent_person_key": null,
            "created_at": "2023-11-24 19:10:54",
            "description": "329 0001 000002-5 32.402.502/0001-35 QI SOCIEDADE DE CR\u00c9DITO DIRETO S.A.",
            "origin_key": "4983e0ad-2212-44f9-8ab9-c243f72f90a8",
            "source_subtype": {
                "enumerator": "internal_pix_transfer",
                "translation_ptbr": "Transfer\u00eancia de PIX"
            },
            "transacted_at": "2023-11-24 19:10:54",
            "transaction_amount": 1,
            "transaction_details": {
                "payer_account_branch": "0001",
                "payer_account_digit": "7",
                "payer_account_number": "5267641",
                "payer_document_number": "98765432100",
                "payer_ispb": "32402502",
                "payer_name": "Eduardo Spada",
                "receiver_account_branch": "0001",
                "receiver_account_digit": "5",
                "receiver_account_number": "000002",
                "receiver_conciliation_id": null,
                "receiver_document_number": "32402502000135",
                "receiver_ispb": "32402502",
                "receiver_name": "QI SCD S.A."
            },
            "transaction_key": "b71ea9a3-e012-4761-bea6-e65c6bfc228f"
        }
    ],
    "pagination": {
        "current_page": 1,
        "next_page": null,
        "rows_per_page": 30,
        "total_pages": "unavailable",
        "total_rows": null
    }
}
```

Response Body: Transações TED

```json
{
    "data": [
        {
            "account_balance": 22403.11,
            "agent_person_key": null,
            "created_at": "2023-11-24 19:10:54",
            "description": "329 0001 000002-5 32.402.502/0001-35 QI SOCIEDADE DE CR\u00c9DITO DIRETO S.A.",
            "origin_key": "4983e0ad-2212-44f9-8ab9-c243f72f90a8",
            "source_subtype": {
                "enumerator": "incoming_funds_transfer",
                "translation_ptbr": "Transferência de Entrada"
            },
            "transacted_at": "2023-11-24 19:10:54",
            "transaction_amount": 1,
            "transaction_details": {
                "receiver_account_number": "7212399",
                "payer_account_branch": "120",
                "payer_account_number": "84598",
                "receiver_name": "QI SCD S.A.",
                "receiver_account_branch": "2",
                "payer_document_number": "23846749289329",
                "payer_account_digit": "4",
                "payer_ispb": "61231190",
                "receiver_ispb": "32402502",
                "receiver_document_number": "02983510938761",
                "payer_name": "ASICS BRASIL DISTRIBUICAO E CO",
                "receiver_account_digit": "3"
            },
            "transaction_key": "b71ea9a3-e012-4761-bea6-e65c6bfc228f"
        }
    ],
    "pagination": {
        "current_page": 1,
        "next_page": null,
        "rows_per_page": 30,
        "total_pages": "unavailable",
        "total_rows": null
    }
}
```

Response Body: Transações de pagamento de boleto bancário

```json
{
    "data": [
        {
            "account_balance": 22403.11,
            "agent_person_key": null,
            "created_at": "2023-11-24 19:10:54",
            "description": "329 0001 000002-5 32.402.502/0001-35 QI SOCIEDADE DE CR\u00c9DITO DIRETO S.A.",
            "origin_key": "4983e0ad-2212-44f9-8ab9-c243f72f90a8",
            "source_subtype": {
                "enumerator": "bank_slip_payment",
                "translation_ptbr": "Pagamento de Boleto"
            },
            "transacted_at": "2023-11-24 19:10:54",
            "transaction_amount": 1,
            "transaction_details": {
                "beneficiary_legal_name": "COATIOSUERRA LTDA",
                "barcode": "34191954500001165778979877821520910001098000",
                "digitable_line": "34312123124532455091500010980001195450000116579",
                "beneficiary_document_number": "61148052000102"
            },
            "transaction_key": "b71ea9a3-e012-4761-bea6-e65c6bfc228f"
        }
    ],
    "pagination": {
        "current_page": 1,
        "next_page": null,
        "rows_per_page": 30,
        "total_pages": "unavailable",
        "total_rows": null
    }
}
```

Response Body: Transações de Liquidação de Cartão

```json
{
    "data": [
        {
            "account_balance": 22403.11,
            "agent_person_key": null,
            "created_at": "2023-11-24 19:10:54",
            "description": "Nome da Credenciadora 12345678000195 - Elo Débito - Liquidação",
            "origin_key": "4983e0ad-2212-44f9-8ab9-c243f72f90a8",
            "source_subtype": {
                "enumerator": "incoming_debit_card_settlement",
                "translation_ptbr": "Liquidação de cartão de débito"
            },
            "transacted_at": "2023-11-24 19:10:54",
            "transaction_amount": 1,
            "transaction_details": {
                "merchant_name": "Nome do Merchant",
                "merchant_document_number": "87654321000198",
                "acquirer_name": "Nome da Credenciadora",
                "acquirer_document_number": "12345678000195",
                "product_type": "ECD",
                "product_description": "Elo Débito"
            },
            "transaction_key": "b71ea9a3-e012-4761-bea6-e65c6bfc228f"
        }
    ],
    "pagination": {
        "current_page": 1,
        "next_page": null,
        "rows_per_page": 30,
        "total_pages": "unavailable",
        "total_rows": null
    }
}
```

Response Body: Transações de Compra no Cartão

```json
{
    "data": [
        {
            "account_balance": 20003.01,
            "agent_person_key": null,
            "created_at": "2023-11-24 19:10:54",
            "description": "Cartão físico | Nome do Estabelecimento | SAO PAULO - BR | U3UUUU",
            "origin_key": "c9f31beb-dafa-42c2-9a16-0854c523eabd",
            "source_subtype": {
                "enumerator": "card_purchase",
                "translation_ptbr": "Compra com Cartão"
            },
            "transacted_at": "2023-11-24 19:10:54",
            "transaction_amount": 17,
            "transaction_details": {
                "acquirer_code": "000000",
                "merchant_mcc": "0000",
                "merchant_name": "Nome do Estabelecimento",
                "authorization_code": "U3UUUU",
                "merchant_address": {
                    "postal_code": "00000123",
                    "city": "SAO PAULO",
                    "country": "BR"
                },
                "merchant_currency": "BRL",
                "merchant_amount": "17.00",
                "card_transaction_type": "purchase",
                "card_type": "plastic"
            },
            "transaction_key": "b71ea9a3-e012-4761-bea6-e65c6bfc228f"
        }
    ],
    "pagination": {
        "current_page": 1,
        "next_page": null,
        "rows_per_page": 30,
        "total_pages": "unavailable",
        "total_rows": null
    }
}
```

:::info Sobre o campo next_page
O campo `next_page` dentro do objeto `pagination`, indica a próxima página disponível para consulta. Caso não haja mais páginas disponíveis, o valor retornado será `null`.
:::

:::caution Atenção!
O campo `product_type` contido no objeto `transaction_details` das Transações de Liquidação de Cartão de Crédito, é um campo informado pelo Sistema de Liquidações de Cartão, e pode ser retornado com valor `null`. Para estes casos, o campo `product_description` deve ser lido para identificação do `product_type` da liquidação. 
:::

### Enumeradores product_type
| Enumerador | Descrição                                                 |
| --- |-----------------------------------------------------------|
|ACC| American Express Crédito                                  |
|BCC| Banescard Crédito                                         |
|BCD| Banescard Débito                                          |
|BVV| Ben Visa Vale Pré-pago                                    |
|CAC| Cielo Amex Crédito                                        |
|CBC| Cabal Crédito                                             |
|CBD| Cabal Débito                                              |
|CBP| Cabal Pré-pago                                            |
|CC3| Central de Cessões de Crédito                             |
|CDC| Cielo Diners Cartão de Crédito                            |
|CEC| Cielo Elo Cartão de Crédito                               |
|CED| Cielo Elo Cartão de Débito                                |
|CHC| Cielo Hipercard Crédito                                   |
|CMC| Cielo Mastercard Crédito                                  |
|CMD| Cielo Mastercard Débito                                   |
|COP| COPASA - Companhia de Saneamento de Minas Gerais          |
|CUP| Cup Crédito                                               |
|CZC| Credz Crédito                                             |
|DCC| Liquidações Transfronteiriças Diners Crédito              |
|ECB| Elo PAT - Cartão de Benefícios                            |
|ECC| Elo Crédito                                               |
|ECD| Elo Débito                                                |
|GCC| Goodcard Crédito                                          |
|GDC| Global Payments Diners Crédito                            |
|GMC| Global Payments MasterCard Crédito                        |
|GMD| Global Payments MasterCard Débito                         |
|GVC| Global Payments VISA Crédito                              |
|GVD| Global Payments VISA Débito                               |
|HCC| Hipercard Crédito                                         |
|HCD| Hiper Débito                                              |
|JCC| JCB Crédito                                               |
|MAC| Mais Cartão de Crédito                                    |
|MCA| MasterCard Cartão ATM                                     |
|MCC| Mastercard Crédito                                        |
|MCD| Maestro Débito                                            |
|MCP| Mastercard Pré-pago                                       |
|NBA| Neoenergia - Companhia de Eletricidade do Estado da Bahia |
|NBR| Neoenergia - Distribuição Brasília S.A                    |
|NEK| Neoenergia - Elektro Redes S/A                            |
|NPE| Neoenergia - Companhia Energética de Pernambuco           |
|NRN| Neoenergia - Companhia Energética do Rio Grande do Norte  |
|OCD| Ourocard Débito                                           |
|OT| Produto Liquidação Outras Transferências                  |
|PCA| Plataforma Centralizada de Arrecadação                    |
|SCC| Sorocred Crédito                                          |
|SCD| Sorocred Débito                                           |
|SLC| Serviço de Liquidação Centralizada                        |
|STC| SELTEC                                                    |
|TCB| Tecban                                                    |
|TED| Produto Liquidação TED                                    |
|VCA| Visa Cartão ATM                                           |
|VCC| Visa Crédito                                              |
|VCD| Visa Electron Débito                                      |
|VCP| Visa Pré-pago                                             |
|VDC| Verdecard Crédito                                         |
|VDP| Verdecard Pré-pago                                        |
|VIA| Visa Internacional Saque ATM                              |
|VIC| Visa Internacional Compra Crédito                         |
|VID| Visa Internacional Compra Débito                          |
||Alelo Pré-pago|
||Agiplan Crédito|
||Aura Crédito|
||Calcard Crédito|
||Credsystem Crédito|
||Redesplan Crédito|
||Sicred Crédito|
||Avista Crédito|
||Discover Crédito|
||Sicredi Débito|
||Hiper Crédito|
||Ticket Pré-pago|
||Sodexo Pré-pago|
||VR Pré-pago|
||Policard Pré-pago|
||Valecard Pré-pago|
||Greencard Pré-pago|
||Coopercard Pré-pago|
||Verocheque Pré-pago|
||Nutricash Pré-pago|
||Banricard Pré-pago|
||Socored Pré-pago|
||Cielo Arranjo Fechado Crédito|
||Cielo Arranjo Fechado Débito|

### Enumeradores de source_sub_types’s:

| Enum                                    | Descrição                                       |
|-----------------------------------------|-------------------------------------------------|
| operation_disbursement                  | Desembolso da Operação                          |
| protest_expense                         | Despesas de Protesto                            |
| automatic_integrated_payment            | Pagamento Automático Integrado                  |
| tax                                     | Impostos                                        |
| electronic_funds_fee                    | Tarifa de TED                                   |
| credit_operation_fee                    | Tarifa de Abertura de Crédito                   |
| internal_funds_transfer                 | Transferência Interna                           |
| incoming_funds_transfer                 | Transferência de Entrada                        |
| outgoing_funds_transfer                 | TED                                             |
| deposit                                 | Depósito                                        |
| withdrawal                              | Transferência                                   |
| withdrawal_reversal                     | Estorno de Transferência                        |
| trade_funds_transfer                    | Transferência de Pagamento de Cessão            |
| settlement_funds_transfer               | Transferência para Liquidação                   |
| bank_slip_fee                           | Tarifa de Boleto                                |
| bank_slip_settlement                    | Liquidação de Boleto                            |
| outgoing_funds_transfer_reversal        | Estorno de TED                                  |
| incoming_funds_transfer_refusal         | Transferência Negada                            |
| electronic_funds_fee_reversal           | Estorno de Tarifa de TED                        |
| monthly_account_fee_reversal            | Estorno de Tarifa de Manutenção de Conta        |
| bank_slip_fee_reversal                  | Estorno de Tarifa de Boleto                     |
| correspondent_bank_transfer             | Repasse de Correspondente Bancário              |
| credit_analysis_fee                     | Tarifa de Análise de Crédito                    |
| credit_operation_fee_reversal           | Estorno de Tarifa de Abertura de Crédito        |
| financial_investments_income            | Renda de Aplicação Financeira                   |
| bank_slip_settlement_reversal           | Estorno de Liquidação de Boleto                 |
| bank_slip_settlement_expense_reversal   | Estorno de Tarifa de liquidação de Boleto       |
| bank_slip_settlement_incoming_reversal  | Estorno de Recebimento de Liquidação de Boleto  |
| correspondent_bank_transfer_reversal    | Estrono de Repasse de Correspondente Bancário   |
| credit_analysis_fee_reversal            | Estorno de Tarifa de Análise de Crédito         |
| doc_expense_reversal                    | Estorno de Tarifa de DOC                        |
| incoming_doc_reversal                   | Estorno de Entrada de DOC                       |
| operation_disbursement_reversal         | Estorno de Desembolso da Operação               |
| operation_settling_reversal             | Estorno de Pagamento de Operação                |
| outgoing_doc_reversal                   | Estorno de Saída de DOC                         |
| rebate_reversal                         | Estorno de Rebate                               |
| settlement_funds_transfer_reversal      | Estorno de Transferência para Liquidação        |
| tax_reversal                            | Estorno de Impostos                             |
| trade_funds_transfer_reversal           | Estorno de Transferência de Pagamento de Cessão |
| bank_slip_permanency_fee                | Tarifa de Permanência do Título                 |
| bank_slip_cancel_protest_fee            | Tarifa de Permanência do Título                 |
| bank_slip_protest_fee                   | Tarifa de Pedido de Protesto                    |
| bank_slip_notary_office_fee             | Custas de Protesto                              |
| bank_slip_registration_fee              | Tarifa de Registro                              |
| bank_slip_extension_fee                 | Tarifa de Prorrogação                           |
| bank_slip_rebate_fee                    | Tarifa de Abatimento                            |
| bank_slip_discount_fee                  | Tarifa de Desconto                              |
| bank_slip_settlement_fee                | Tarifa de Liquidação                            |
| bank_slip_write_off_term_fee            | Tarifa de Baixa por Decurso de Prazo            |
| bank_slip_write_off_fee                 | Tarifa de Baixa                                 |
| bank_slip_cancel_protest_write_off_fee  | Tarifa de Sustação de Protesto com Baixa        |
| bank_slip_notary_office_settlement_fee  | Tarifa de Liquidação em Cartório                |
| rebate_tax_free                         | Repasse por Conta e Ordem                       |
| rebate_tax_free_reversal                | Estorno de Repasse por Conta e Ordem            |
| incoming_funds_transfer_reversal        | Estorno de Transferência Interna                |
| bank_slip_payment                       | Pagamento de Boleto                             |
| bank_slip_payment_reversal              | Estorno de Pagamento de Boleto                  |
| warranty_analysis_fee                   | Tarifa de Análise de Garantia                   |
| bank_slip_settlement_deposit            | Liquidação de Boleto                            |
| bank_slip_payment_withdrawal            | Pagamento de Boleto                             |
| account_setup_fee                       | Tarifa de Abertura de Conta                     |
| account_setup_fee_reversal              | Estorno de Tarifa de Abertura de Conta          |
| bank_slip_payment_withdrawal_reversal   | Estorno de Pagamento de Boleto                  |
| incoming_anticipation_of_receivable     | -                                               |
| incoming_credit_card_settlement         | Liquidação de cartão de crédito                 |
| incoming_debit_card_settlement          | Liquidação de cartão de débito                  |
| assignment_automatic_transfer           | Débito de Cessão Automática                     |
| assignment_automatic_transfer_reversal  | Estorno de Débito de Cessão Automática          |
| pix_fee                                 | Tarifa de PIX                                   |
| incoming_pix_transfer                   | Entrada de PIX                                  |
| outgoing_pix_transfer                   | Saída de PIX                                    |
| pix_fee_reversal                        | Estorno de Tarifa de PIX                        |
| incoming_pix_transfer_reversal          | Estorno de entrada de PIX                       |
| outgoing_pix_transfer_reversal          | Estorno de saída de PIX                         |
| pix_deposit                             | Depósito de PIX                                 |
| pix_withdrawal                          | Transferência de PIX                            |
| pix_withdrawal_reversal                 | Estorno de transferência de PIX                 |
| pix_chargeback_withdrawal               | Envio de devolução PIX                          |
| outgoing_pix_chargeback                 | Saída de PIX por devolução                      |
| incoming_pix_chargeback                 | Recebimento de devolução PIX                    |
| pix_chargeback_deposit                  | Entrada de PIX por devolução                    |
| pix_chargeback_withdrawal_reversal      | Estorno de envio de devolução PIX               |
| outgoing_pix_chargeback_reversal        | Estorno de saída de PIX por devolução           |
| incoming_pix_chargeback_reversal        | Estorno de recebimento de devolução PIX         |
| operation_pix_disbursement              | Desembolso PIX da Operação                      |
| operation_pix_disbursement_reversal     | Estorno de Desembolso PIX da Operação           |
| receivables_inquiry_fee                 | Tarifa de Consulta de Agenda de Recebíveis      |
| pix_deposit_reversal                    | Estorno de Depósito de PIX                      |
| internal_pix_transfer                   | Transferência de PIX                            |
| automatic_integrated_payment_reversal   | Estorno de Pagamento Automático Integrado       |
| operation_dibursement_reversal          | Estorno de Desembolso da Operação               |
| available_yield                         | Depósito de Investimento Liquido                |
| bank_slip_convenant_payment             | Pagamento de Boleto de Convênio                 |

### Enumeradores de prepaid_card_transaction_type:
| Enum                    | Descrição                                 |
|-------------------------|-------------------------------------------|
| purchase                | Compra no cartão                          |
| international_purchase  | Compra internacional no cartão            |
| withdrawal              | Saque em caixa eletrônico (ATM) no cartão |

### Enumeradores de card_type:
| Enum       | Descrição                                 |
|------------|-------------------------------------------|
| plastic    | Cartão físico                             |
| virtual    | Cartão virtual                            |

---

# Consulta de transações pendentes

URL: /documentation/movimentacao_de_contas/consulta_de_transacoes_pendentes

## Request

ENDPOINT /pending_movement
MÉTODO GET

## Response

STATUS 200

**Response Body**

```json
{
  "data": {
    "movement_request_list": [
      {
        "account_key": "003307e9-d4fd-487d-a07b-84ceab4ad4a9",
        "approval_feedback": null,
        "movement_amount": 1013,
        "movement_data": {
          "agent_person_key": "0bb61530-7f2e-4fe8-819d-8dcfde478a4c",
          "origin_key": "0cc9efd2-5d53-4ac7-8ab3-a2f65c0c5e3b",
          "origin_type": "movement_request",
          "source_account_key": "003307e9-d4fd-487d-a07b-84ceab4ad4a9",
          "source_subtype": "internal_funds_transfer",
          "target_account_key": "ec87ea6c-31f4-47f1-b16a-11fc39572cb5",
          "transaction_amount": 1013
        },
        "movement_date": "2020-08-04",
        "movement_info": null,
        "movement_request_key": "0cc9efd2-5d53-4ac7-8ab3-a2f65c0c5e3b",
        "movement_status": "submitted",
        "movement_type": "transaction",
        "requester_key": "ba99b7f1-3db6-4a63-a386-ba2c7f31e784"
      },
      {
        "account_key": "21af482f-b8ac-48dd-8f9a-ea23429d28be",
        "approval_feedback": null,
        "movement_amount": 10,
        "movement_data": {
          "digitable_line": "65590000020048550000321310771007283400000001000",
          "resource_account_key": "21af482f-b8ac-48dd-8f9a-ea23429d28be"
        },
        "movement_date": "2020-08-05",
        "movement_info": null,
        "movement_request_key": "09729b67-8853-4688-ae16-1b878b6629f8",
        "movement_status": "submitted",
        "movement_type": "bank_slip_payment",
        "requester_key": "ba99b7f1-3db6-4a63-a386-ba2c7f31e784"
      }
    ]
  },
  "status": "waiting_approval",
  "webhook_type": "pending_movement"
}
```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

---

# Consulta de extrato

URL: /documentation/movimentacao_de_contas/consulta_de_transferencias_realizadas

## Request

ENDPOINT /account_statement
MÉTODO GET
PARÂMETROS account_key, document_number, date_from, date_to, page, page_size

## QUERY PARAMS

| Campo | Tipo | Descrição | Máx. de caracteres | Exemplo |
|---|---| ---| ---| ---|
| `account_key` * | string |  Chave uuid da conta. | chave uuid ||
| `date_from` * | date |  Data de início do intervalo consultado. | 10 | 2023-10-10 |
| `date_to` * | date |  Data final do intervalo consultado. | 10 | 2023-10-10 |
| `page` | string |  Índice da página retornado | 2 | 1 |
| `page_size` | string |  Quantidade de transações a ser retornada (Máximo 4000) | 4 | 3999 |
| `order_by` | string |  Data final do intervalo consultado. | 3 | asc |

## Response

STATUS 200

Response Body

```json
{
  "data": {
    "account_info": {
      "account_block_reason": null,
      "account_branch": "0001",
      "account_credentials": [],
      "account_digit": "0",
      "account_key": "22189d43-4503-47c6-a05b-be29a534b2ac",
      "account_name": "Default",
      "account_number": "1467576",
      "account_status": "opened",
      "account_type": "checking",
      "automatic_transfers": [],
      "balance": 88637.41,
      "blocked_balance": 0,
      "destinations": [],
      "fee": 0.1,
      "internal_webhooks": [],
      "owner_document_number": "555555555",
      "owner_name": "Teste da Silva Testado",
      "owner_person_key": "f580d89d-217c-4244-ac88-5f4ec6861a5e",
      "permitted_person_keys": [
        "f580d89d-217c-4244-ac88-5f4ec6861a5e"
      ],
      "requester_key": "f580d89d-217c-4244-ac88-5f4ec6861a5e",
      "requester_name": "Teste da Silva Testado",
      "setup_fee": null,
      "transactional_limit": null,
      "webhook_enabled": true
    },
    "transaction_list": [
      {
        "account_balance": 88637.41,
        "description": "JORGE DA SILVA TESTE - 555555555",
        "source_subtype": "bank_slip_payment",
        "transacted_at": "2022-06-22 15:39:39",
        "transaction_amount": -1.5,
        "transaction_key": "D2Bb0f4e-cbb6-4f6a-8ea6-b66710d3dde8"
      },
      {
        "account_balance": 88638.91,
        "description": " 0001 52260-6 01.871.112/0001-80 ",
        "source_subtype": "pix_withdrawal_reversal",
        "transacted_at": "2022-06-20 19:28:16",
        "transaction_amount": 0.72,
        "transaction_key": "55c68b62-0288-4481-a6c2-44e9386e5d3f"
      }
    ]
  },
  "event_datetime": "2022-06-23 16:21:15",
  "key": "000fa133-2f45-4c39-ae76-c87cccb2c034",
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "rows_per_page": 10,
    "total_pages": "unavailable",
    "total_rows": null
  },
  "status": "success",
  "webhook_type": "account_statement"
}
```

:::info Dica de Paginação
O page_size é o indicador da quantidade de transações.

Se o número de transações retornadas é igual ao `page_size` informado, podem existir mais transações e a próxima página deve ser consultada.

Caso o número de itens contidos na lista "transaction_list" seja menor que o `page_size` ou igual zero, significa que não existem mais resultados e a página atual é a última da listagem.
:::

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

---

# Realizar transferência

URL: /documentation/movimentacao_de_contas/realizar_transferencia

## Request

ENDPOINT /wire_transfer
MÉTODO POST

Request Body

```json
{
    "source_account": {
        "account_branch": "0001",
        "account_number": "9477323",
        "account_digit": "0",
        "owner_document_number": "38299588000107"
    },
    "target_account": {
        "financial_institution_code": "341",
        "account_branch": "0001",
        "account_number": "92796",
        "account_digit": "1",
        "owner_document_number": "23599885000192",
        "owner_name": "Titular da Conta"
    },
    "transaction_amount": 8.86
}
```

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `source_account` * | object | Conta de origem. | **[Objeto source_account](#objeto-source_account)** | 
| `target_account` * |  object | Conta de destino. | **[Objeto target_account](#objeto-target_account)** | 
| `transaction_amount` * | double | Valor da transferência. | 10 |
| `schedule_date` * | date |  Data de agendamento da transação, se não especificado a transação será realizada no momento do envio ou assim que aprovada. | 10 |

### Objeto source_account

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `account_branch` * |  string | Agência. | 10 |
| `account_digit` * |  string | Dígito da conta | 10 |
| `account_number` * | string | Número da conta. | 10 |
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta. | 10 |
| `target_account_type` * |  string | Tipo da conta destino |  **[Enumeradores](#enumeradores-ted_account_type)** |

### Objeto target_account

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `account_branch` * | string | Agência. | 10 |
| `account_digit` * | string | Dígito da conta | 10 |
| `account_number` * | string | Número da conta. | 10 |
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta. | 10 |
| `owner_name` * | string | Nome do titular da conta. | 10 |

### Enumeradores target_account_type

| Enumerador | Tradução |
|---|---|
|  checking_account  | conta corrente |
|  deposit_account  |  conta depósito  |
|  guaranteed_account  |  conta de garantia  |
|  investment_account  |  conta de investimento |
|  payment_account  | conta de pagamento |
|  saving_account  | conta poupança  |

## Response

STATUS 200

Response Body

```json
{
  "data": {
    "source_account": {
      "account_branch": "0001",
      "account_digit": "3",
      "account_number": "24339",
      "owner_document_number": "32402502000135"
    },
    "target_account": {
      "account_branch": "0001",
      "account_digit": "6",
      "account_number": "78340",
      "financial_institution_code": "329",
      "owner_document_number": "32402502000135",
      "owner_name": "QI Tech"
    },
    "transaction_key": "7986dcc7-4331-478f-af47-adfbdf7f4a36",
    "transaction_amount": 1891268.97,
    "outgoing_ted_key": "bc90744e-4f9a-42b1-9410-d5fa3c183fa8",
  },
  "event_datetime": "2019-11-28 19:22:04",
  "key": "fa80723e-4f9a-42b1-9410-d5fa3c183fa8",
  "status": "success",
  "webhook_type": "wire_transfer"
}

```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

STATUS 400 - Fora do horário de TED

Response Body

```json
{
  	"data": "{ \"code\": \"TED000011\", \"title\": \"Bad Request\", \"http_status\": 400, \"description\": \"Wrong day/time for TED\", \"translation\": \"Dia/hora incorretos para a TED\", \"extra_fields\": { \"next_available_datetime\": \"2023-08-13T18:00:00.000Z\"} }",
	"code": "TED000011",
	"title": "Bad Request",
	"http_status": 400,
	"description": "Wrong day/time for TED",
	"translation": "Dia/hora incorretos para a TED",
	"extra_fields": {
		"next_available_datetime": "2023-08-13T18:00:00.000Z"
	}
}
```

---

# Simulação de cenários

URL: /documentation/movimentacao_de_contas/transacao

Passo a passo para simular a efetivação de ações feitas por agentes externos. Essa simulação visa efetivar transações
internas.

:::info Informação
Não há payload de retorno (response body) nessas requisições.
:::

## 1 - Simulação de transação interna

### Request

ENDPOINT /mock/account/transaction
MÉTODO POST

Request Body

```json
{
  "target_account_key": "c2aa26d5-d6fc-42cf-b9a0-e26f69d85c7d",
  "amount": 100
}
```

## 2 - Simulação de entrada de TED

### Request

ENDPOINT /mock/ted/incoming_ted
MÉTODO POST

Request Body

```json
{
  "target_account_key": "\<Chave unitária da conta de destino\>",
  "amount": "\<Valor da transação\>"
}
```

## 3 - Simulação de devolução de TED

        **Request**

ENDPOINT /mock/ted/ted_refusal
MÉTODO POST

Request Body

```json
{
  "transaction_key": "\<Chave unitária da transação\>"
}
```

Request Body

```json
{
  "ted_key": "\<Chave unitária da transferência TED\>"
}
```

### Objeto Request Body

Nessa tabela, está disponível o descritivo de todas as variáveis utilizadas pelas requisções acima detalhadas.

**ATENÇÃO: Cada requisição utiliza um conjunto específico de variáveis.**

| Campo                  | Tipo   | Descrição                           | Máx. Caract. | Exemplo                                | Observação              |
|------------------------|--------|-------------------------------------|--------------|----------------------------------------|-------------------------|
| **target_account_key** | string | Chave unitária da conta de destino  | 36           | "41112f46-0034-4007-85687-5e592173db2" |                         |
| **amount**             | number | Valor da transação                  | 6            | 1000                                   | Valor máximo de 100.000 |
| **transaction_key**    | string | Chave unitária da transação         | 36           | "e27ed4e1-53d8-4cc8-a00e-5b0008bf5526" |                         |
| **ted_key**            | string | Chave unitária da transferência TED | 36           | "3bb0e340-42f9-407f-a970-5a4f35f5403b" |                         |

---

# Webhooks

URL: /documentation/movimentacao_de_contas/webhook_movimentacoes

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

## Webhook de movimentações
Para toda e qualquer movimentação será enviado um webhook de “***account_transaction***“.

Cada transação possui um tipo de classificação (**Source Sub Type**). Essa classificação é utilizada para categorizar cada movimentação na conta. A lista de Source Sub Types pode ser visualizada abaixo.

### Crédito em Conta

Os créditos em conta resultarão em um webhook com “***data.amount***” positivo, “***data.origin***“ sendo a conta de origem dos recursos e a “***data.destination***“ sendo a conta de destino dos recursos:

WEBHOOK_TYPE account_transaction

Response Body: Pix

```json
{
    "key": "\<ACCOUNT-KEY\>",
	"data": {
		"amount": 1000000,
		"origin": {
			"name": "Treasury Account",
			"branch": "0001",
			"document": "32402502000135",
			"account_key": "5d068423-6094-49e4-b15b-7740038295a8",
			"account_digit": "5",
			"account_number": "00002"
		},
		"timestamp": "2022-09-02T21:36:33.446120",
		"description": "329 0001 00002-5 32.402.502/0001-35 - QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"destination": {
			"name": "Default",
			"branch": "0001",
			"document": "09080702000105",
			"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
			"account_digit": "2",
			"account_number": "2359934"
		},
		"reference_key": "983b4a28-7de6-4e71-97ef-60fb50c7b013",
		"reference_type": "movement_request",
		"account_balance": 1000000,
		"source_sub_type": "internal_funds_transfer",
		"transaction_key": "67a62397-2c32-4768-8485-ec9129a46654",
		"source_sub_type_str": "Transferência Interna",
		"transaction_details": {
			"payer_name": "0001",
			"receiver_name": "Default",
			"payer_account_digit": "5",
			"payer_account_branch": "",
			"payer_account_number": "1111111",
			"payer_document_number": "66681638999999",
			"receiver_account_digit": "6",
			"receiver_account_branch": "0000",
			"receiver_account_number": "34256449809",
			"receiver_conciliation_id": null,
			"receiver_document_number": "00809641658"
		}
	},
	"datetime": "2022-09-02T21:36:33.446120",
	"webhook_type": "account_transaction"
}
```

Response Body: Outras transações

```json
{
    "key": "\<ACCOUNT-KEY\>",
	"data": {
		"amount": 1000000,
		"origin": {
			"name": "Treasury Account",
			"branch": "0001",
			"document": "32402502000135",
			"account_key": "5d068423-6094-49e4-b15b-7740038295a8",
			"account_digit": "5",
			"account_number": "00002"
		},
		"timestamp": "2022-09-02T21:36:33.446120",
		"description": "329 0001 00002-5 32.402.502/0001-35 - QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"destination": {
			"name": "Default",
			"branch": "0001",
			"document": "09080702000105",
			"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
			"account_digit": "2",
			"account_number": "2359934"
		},
		"reference_key": "983b4a28-7de6-4e71-97ef-60fb50c7b013",
		"reference_type": "movement_request",
		"account_balance": 1000000,
		"source_sub_type": "internal_funds_transfer",
		"transaction_key": "67a62397-2c32-4768-8485-ec9129a46654",
		"source_sub_type_str": "Transferência Interna",
	},
	"datetime": "2022-09-02T21:36:33.446120",
	"webhook_type": "account_transaction"
}
```

## Débito em Conta
Os débitos em conta resultarão em um webhook com “***data.amount***” negativo, “***data.origin***“ sendo a conta destinatária dos recursos e a “***data.destination***“ sendo a conta de origem dos recursos:

WEBHOOK_TYPE account_transaction

Webhook Body

```json
{
	"key": "\<ACCOUNT-KEY\>",
	"data": {
		"amount": -45,
		"origin": {
			"name": "PIX",
			"branch": "0001",
			"document": "32402502000135",
			"account_key": "3d0e7d50-e898-49f3-b23b-05353c8a3c72",
			"account_digit": "3",
			"account_number": "00003"
		},
		"timestamp": "2022-09-02T23:00:05.326738",
		"description": "212 0001 1017372-2 ***.221.81*-** BANCO ORIGINAL S.A.",
		"destination": {
			"name": "Default",
			"branch": "0001",
			"document": "09080702000105",
			"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
			"account_digit": "2",
			"account_number": "2359934"
		},
		"reference_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
		"reference_type": "pix_outgoing",
		"account_balance": 999955,
		"source_sub_type": "pix_withdrawal",
		"transaction_key": "d2ba3817-26d7-4957-ab82-24f78d910a8a",
		"source_sub_type_str": "Transferência de PIX"
	},
	"datetime": "2022-09-02T23:00:05.326738",
	"webhook_type": "account_transaction"
}
```
 

**Lista de source_sub_types’s:**

| Enum                                    | Descrição                                       |
|-----------------------------------------|-------------------------------------------------|
| operation_disbursement                  | Desembolso da Operação                          |
| protest_expense                         | Despesas de Protesto                            |
| automatic_integrated_payment            | Pagamento Automático Integrado                  |
| tax                                     | Impostos                                        |
| electronic_funds_fee                    | Tarifa de TED                                   |
| credit_operation_fee                    | Tarifa de Abertura de Crédito                   |
| internal_funds_transfer                 | Transferência Interna                           |
| incoming_funds_transfer                 | Transferência de Entrada                        |
| outgoing_funds_transfer                 | TED                                             |
| deposit                                 | Depósito                                        |
| withdrawal                              | Transferência                                   |
| withdrawal_reversal                     | Estorno de Transferência                        |
| trade_funds_transfer                    | Transferência de Pagamento de Cessão            |
| settlement_funds_transfer               | Transferência para Liquidação                   |
| bank_slip_fee                           | Tarifa de Boleto                                |
| bank_slip_settlement                    | Liquidação de Boleto                            |
| outgoing_funds_transfer_reversal        | Estorno de TED                                  |
| incoming_funds_transfer_refusal         | Transferência Negada                            |
| electronic_funds_fee_reversal           | Estorno de Tarifa de TED                        |
| monthly_account_fee_reversal            | Estorno de Tarifa de Manutenção de Conta        |
| bank_slip_fee_reversal                  | Estorno de Tarifa de Boleto                     |
| correspondent_bank_transfer             | Repasse de Correspondente Bancário              |
| credit_analysis_fee                     | Tarifa de Análise de Crédito                    |
| credit_operation_fee_reversal           | Estorno de Tarifa de Abertura de Crédito        |
| financial_investments_income            | Renda de Aplicação Financeira                   |
| bank_slip_settlement_reversal           | Estorno de Liquidação de Boleto                 |
| bank_slip_settlement_expense_reversal   | Estorno de Tarifa de liquidação de Boleto       |
| bank_slip_settlement_incoming_reversal  | Estorno de Recebimento de Liquidação de Boleto  |
| correspondent_bank_transfer_reversal    | Estrono de Repasse de Correspondente Bancário   |
| credit_analysis_fee_reversal            | Estorno de Tarifa de Análise de Crédito         |
| doc_expense_reversal                    | Estorno de Tarifa de DOC                        |
| incoming_doc_reversal                   | Estorno de Entrada de DOC                       |
| operation_disbursement_reversal         | Estorno de Desembolso da Operação               |
| operation_settling_reversal             | Estorno de Pagamento de Operação                |
| outgoing_doc_reversal                   | Estorno de Saída de DOC                         |
| rebate_reversal                         | Estorno de Rebate                               |
| settlement_funds_transfer_reversal      | Estorno de Transferência para Liquidação        |
| tax_reversal                            | Estorno de Impostos                             |
| trade_funds_transfer_reversal           | Estorno de Transferência de Pagamento de Cessão |
| bank_slip_permanency_fee                | Tarifa de Permanência do Título                 |
| bank_slip_cancel_protest_fee            | Tarifa de Permanência do Título                 |
| bank_slip_protest_fee                   | Tarifa de Pedido de Protesto                    |
| bank_slip_notary_office_fee             | Custas de Protesto                              |
| bank_slip_registration_fee              | Tarifa de Registro                              |
| bank_slip_extension_fee                 | Tarifa de Prorrogação                           |
| bank_slip_rebate_fee                    | Tarifa de Abatimento                            |
| bank_slip_discount_fee                  | Tarifa de Desconto                              |
| bank_slip_settlement_fee                | Tarifa de Liquidação                            |
| bank_slip_write_off_term_fee            | Tarifa de Baixa por Decurso de Prazo            |
| bank_slip_write_off_fee                 | Tarifa de Baixa                                 |
| bank_slip_cancel_protest_write_off_fee  | Tarifa de Sustação de Protesto com Baixa        |
| bank_slip_notary_office_settlement_fee  | Tarifa de Liquidação em Cartório                |
| rebate_tax_free                         | Repasse por Conta e Ordem                       |
| rebate_tax_free_reversal                | Estorno de Repasse por Conta e Ordem            |
| incoming_funds_transfer_reversal        | Estorno de Transferência Interna                |
| bank_slip_payment                       | Pagamento de Boleto                             |
| bank_slip_payment_reversal              | Estorno de Pagamento de Boleto                  |
| warranty_analysis_fee                   | Tarifa de Análise de Garantia                   |
| bank_slip_settlement_deposit            | Liquidação de Boleto                            |
| bank_slip_payment_withdrawal            | Pagamento de Boleto                             |
| account_setup_fee                       | Tarifa de Abertura de Conta                     |
| account_setup_fee_reversal              | Estorno de Tarifa de Abertura de Conta          |
| bank_slip_payment_withdrawal_reversal   | Estorno de Pagamento de Boleto                  |
| incoming_anticipation_of_receivable     | -                                               |
| incoming_credit_card_settlement         | Liquidação de cartão de crédito                 |
| incoming_debit_card_settlement          | Liquidação de cartão de débito                  |
| assignment_automatic_transfer           | Débito de Cessão Automática                     |
| assignment_automatic_transfer_reversal  | Estorno de Débito de Cessão Automática          |
| pix_fee                                 | Tarifa de PIX                                   |
| incoming_pix_transfer                   | Entrada de PIX                                  |
| outgoing_pix_transfer                   | Saída de PIX                                    |
| pix_fee_reversal                        | Estorno de Tarifa de PIX                        |
| incoming_pix_transfer_reversal          | Estorno de entrada de PIX                       |
| outgoing_pix_transfer_reversal          | Estorno de saída de PIX                         |
| pix_deposit                             | Depósito de PIX                                 |
| pix_withdrawal                          | Transferência de PIX                            |
| pix_withdrawal_reversal                 | Estorno de transferência de PIX                 |
| pix_chargeback_withdrawal               | Envio de devolução PIX                          |
| outgoing_pix_chargeback                 | Saída de PIX por devolução                      |
| incoming_pix_chargeback                 | Recebimento de devolução PIX                    |
| pix_chargeback_deposit                  | Entrada de PIX por devolução                    |
| pix_chargeback_withdrawal_reversal      | Estorno de envio de devolução PIX               |
| outgoing_pix_chargeback_reversal        | Estorno de saída de PIX por devolução           |
| incoming_pix_chargeback_reversal        | Estorno de recebimento de devolução PIX         |
| operation_pix_disbursement              | Desembolso PIX da Operação                      |
| operation_pix_disbursement_reversal     | Estorno de Desembolso PIX da Operação           |
| receivables_inquiry_fee                 | Tarifa de Consulta de Agenda de Recebíveis      |
| pix_deposit_reversal                    | Estorno de Depósito de PIX                      |
| internal_pix_transfer                   | Transferência de PIX                            |
| automatic_integrated_payment_reversal   | Estorno de Pagamento Automático Integrado       |
| operation_dibursement_reversal          | Estorno de Desembolso da Operação               |
| available_yield                         | Depósito de Investimento Liquido                |
| bank_slip_convenant_payment             | Pagamento de Boleto de Convênio                 |

## Webhook de bloqueios

O webhook de bloqueios é enviado sempre que houver um bloqueio ou desbloqueio de um determinado valor em uma conta. O campo `origin_type` identifica o tipo de origem do bloqueio.

Para bloqueios, o valor em `blocked_balance` será positivo. Para desbloqueios, o valor será negativo, indicando a liberação do valor anteriormente bloqueado.

WEBHOOK_TYPE baas.account.block_event

Webhook Body: Sisbajud

```json
{
  "webhook_type": "baas.account.block_event",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
	"account_key": "ca2c934e-5970-4c15-bdef-87e1b5c204e3",
	"blocked_balance": 100,
    "origin_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "origin_type": "sisbajud",
	"block_details": {
        "block_order_protocol": "20250028399883",
        "block_order_sequence": "00005",
        "requester_judge": "JUIZ DE DIREITO",
        "defendant_document_number": "15717553064",
        "case_number": "07279467320148070007",
        "court_code": "44815",
        "requested_amount": 10000,
        "lawsuit_author_name": "Pamela Janssen de Araujo Clemente",
        "institution_document_number": null,
        "lawsuit_type": "labor",
        "protocol_datetime": "2025-02-19T10:00:00.000Z"
    }
  }
}
```

### Webhook Body Params

| Campo                	| Tipo          | Descrição                                         		| Máx. Caracteres					|
|-----------------------|---------------|-----------------------------------------------------------|-----------------------------------|
|webhook_type			| string		| Um enumerador que define o tipo de evento sendo reportado	| 23 								|
|blocked_balance		| string		| Data e hora do envio do webhook							| 20								|
|data					| string 		| Dados referentes à ordem judicial							| **[Objeto data](#objeto-data)**	|

#### Objeto data
| Campo                	| Tipo          | Descrição                                 				| Máx. Caracteres											|
|-----------------------|---------------|-----------------------------------------------------------|-----------------------------------------------------------|
| account_key			| string		| Chave única de identificação da conta QI					| 36 														|
| blocked_balance		| number		| Saldo bloqueado											| 15														|
| origin_key			| string 		| Chave única de identificação da origem da ordem judicial	| 36														|
| origin_type			| string		| Origem da ordem judicial									| **[Enumeradores origin_type](#enumeradores-origin_type)**	|
| block_details			| string		| Detalhes do bloqueio 										| **[Objeto block_details](#objeto-block_details)**			|

#### Objeto block_details
| Campo                			| Tipo      | Descrição 								| Máx. Caracteres 												|
|-------------------------------|-----------|-------------------------------------------|---------------------------------------------------------------|
| block_order_protocol       	| number 	| Número do protocolo de bloqueio judicial 	| 14															|
| block_order_sequence       	| number 	| Número de sequência do bloqueio 			| 5																|
| requester_judge            	| string 	| Magistrado    							| 115															|
| defendant_document_number  	| number 	| Número de documento do réu 				| 14															|
| case_number                	| number 	| Número do processo judicial              	| 30															|
| court_code                 	| string 	| Código do tribunal responsável pelo caso  | 5 															|
| requested_amount           	| number 	| Quantia solicitada para bloqueio          | 15															|
| lawsuit_author_name        	| string 	| Nome do autor da ação judicial           	| 115															|
| institution_document_number	| number 	| Número do documento da instituição 		| 14															|
| lawsuit_type               	| enumerator| Tipo de ação judicial  					| **[Enumeradores lawsuit_type](#enumeradores-lawsuit_type)**	|
| protocol_datetime          	| string	| Data e hora do protocolo de bloqueio      | 20 															|

#### Enumeradores lawsuit_type
| Enumerador	| Descrição					|
|---------------|---------------------------|
| civil			| Processo civil			|
| criminal		| Processo criminal			|
| labor			| Processo trabalhista		|
| tax			| Processo tributário		|
| food			| Processo alimentício		|

#### Enumeradores origin_type
| Enumerador    					| Tipo   | Descrição     					|
|-----------------------------------|--------|----------------------------------|
| `credit_operation` 				| string | Operação de crédito 				|
| `credit_operation_installment`	| string | Parcela de operação de crédito	|
| `wallet_trade` 					| string | Operação de carteira 			|
| `wallet_settlement` 				| string | Liquidação de carteira 			|
| `ted_incoming` 					| string | TED recebida 					|
| `ted_outgoing` 					| string | TED enviada 						|
| `bank_slip_expense` 				| string | Despesa de boleto 				|
| `bank_slip` 						| string | Boleto 							|
| `bank_slip_cnab` 					| string | Boleto CNAB 						|
| `future_transaction` 				| string | Transação futura 				|
| `internal_operation` 				| string | Operação interna 				|
| `lego` 							| string | Lego 							|
| `siloc` 							| string | SILOC 							|
| `bank_slip_payment` 				| string | Pagamento de boleto 				|
| `movement_request` 				| string | Solicitação de movimentação 		|
| `slc` 							| string | SLC 								|
| `julius` 							| string | Julius 							|
| `batch_disbursement` 				| string | Desembolso em lote 				|
| `card_transaction` 				| string | Transação de cartão 				|
| `credit_transfer` 				| string | Transferência de crédito 		|
| `pix_outgoing` 					| string | PIX enviado 						|
| `pix_incoming` 					| string | PIX recebido 					|
| `collateral` 						| string | Garantia 						|
| `celcoin` 						| string | Celcoin 							|
| `investment` 						| string | Investimento 					|
| `routing` 						| string | Roteamento 						|
| `c3` 								| string | C3 								|
| `billing` 						| string | Cobrança 						|
| `disbursement` 					| string | Desembolso 						|
| `rebate` 							| string | Rebate 							|
| `card_invoice`					| string | Fatura de cartão 				|
| `b3_operation`					| string | Operação B3 						|
| `bill_payment`					| string | Pagamento de conta 				|
| `med`					 			| string | MED 								|
| `peer_to_peer`					| string | Transferência entre pares 		|
| `settlement_notification`			| string | Notificação de liquidação 		|
| `reversal_notification`			| string | Notificação de estorno 			|
| `insurance_premium`				| string | Prêmio de seguro 				|
| `liquidation`					 	| string | Liquidação 						|
| `purchase`					 	| string | Compra 							|
| `lending_billing`					| string | Cobrança de empréstimo 			|
| `lending_rebate`					| string | Rebate de empréstimo 			|
| `sisbajud`					 	| string | SISBAJUD 						|

#### Enumeradores lawsuit_type
| Enumerador    | Tipo      | Descrição     		|
|---------------|-----------|-----------------------|
| `civil` 		| string 	| Processo Civil 		|
| `criminal` 	| string 	| Processo Criminal 	|
| `labor` 		| string 	| Processo Trabalhista 	|
| `tax` 		| string 	| Processo Tributário 	|
| `food` 		| string 	| Processo Alimentício	|

## Webhook de bloqueio de conta

O webhook de bloqueio de conta é enviado sempre que uma conta for bloqueada.

WEBHOOK_TYPE baas.account.status_change

Webhook Body

```json
{
  "webhook_type": "baas.account.status_change",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
	"account_key":"b91eb198-df87-456d-8ad2-0278f866c1f3",
	"account_status":"blocked",
	"block_reason":"judicially_suspended"
  }
}
```

**Lista de block_reason**:

| Valor | Descrição |
|-------|----------|
| `judicially_suspended` | Bloqueio determinado por ordem judicial |
| `pawn` | Bloqueio por penhor |
| `pending_fee` | Bloqueio por tarifa pendente |
| `missing_credit_operation_payment` | Bloqueio por falta de pagamento de operação de crédito |
| `pending_setup_payment`| Bloqueio por falta de pagamento de taxa de abertura de conta |
| `fraud` | Bloqueio por suspeita de fraude |

---

# Configuração de notificação

URL: /documentation/notificacoes/configuracao_de_notificacao

Aqui demostraremos como você poderá escolher quais tipos de eventos serão notificados e por quais meios a notificação ocorrerá.

:::warning Aviso
Caso não exista uma configuração de notificação para um evento, você não receberá notificações do mesmo.
::: 

## Criação de configuração de notificação

## Request

ENDPOINT /notification/notification_configuration
MÉTODO POST

Request Body

```json
{
    "callback": true,
    "email": true,
    "event_type": "account_transaction",
    "sms": true
}
```

## Response

STATUS 201

Response Body

```json
{"notification_configuration_key":  "69850ae3-28bc-4779-a871-e73e1e883413"}
```

## Listando configurações de notificação

## Request

ENDPOINT /notification/notification_configurations
MÉTODO GET

## Response

STATUS 200

Response Body

```json
{
  "data": [{
    "event_type": "account_request",
    "sms_template": "b35ed5fc-fdda-4618-84e6-b49876dabf23",
    "template_configuration_key": "480521cc-b0c9-4938-bd11-0000be11c66b"
  }],
  "pagination": {
        "current_page": 1,
        "next_page": null,
        "rows_per_page": 1
    }
}
```

## Atualização de configuração de notificação

## Request

ENDPOINT /notification/notification_configuration/ NOTIFICATION_CONFIGURATION_KEY
MÉTODO PUT

Request Body

```json
{
    "callback": true,
    "email": true,
    "event_type": "account_transaction",
    "sms": false
}
```

## Response

STATUS 200

Response Body

```json
{}
```

STATUS 4XX

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                    | Descrição (eng)<br/>`Description`               | Descrição (ptbr)<br/>`translation`                                   |
|-------------|----------------------|---------------------------------------|-------------------------------------------------|----------------------------------------------------------------------|
| 400         | PMB000026            | Invalid notification for event type   | Invalid notification method for event type      | Método de notificação inválido para tipo de evento                   |

---

# Configuração de template

URL: /documentation/notificacoes/configuracao_template

Esta configuração permite definir templates de SMS e e-mail para um evento.

## Criação de configuração de template

## Request

ENDPOINT /notification/template_configuration
MÉTODO POST

Request Body

```json
{
    "event_type": "bank_slip",
    "email_template_key": "e5c337db-dacc-4f1d-8a3e-919628640dd5"
}
``` 

## Response

STATUS 201

Response Body

```json
{"template_configuration_key": "e5c337db-dacc-4f1d-8a3e-919628640d51"}
```

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title` | Descrição (eng)<br/>`Description`                                       | Descrição (ptbr)<br/>`translation`                                 |
|-------------|----------------------|--------------------|-------------------------------------------------------------------------|--------------------------------------------------------------------|
| 400         | PMB000023            | Bad Request        | Already exists an template configuration to this person and event type  | Já existe um template configuration para essa pessoa e event type  |

## Listagem de configuração de template

## Request

ENDPOINT /notification/template_configurations
MÉTODO GET

## Response

STATUS 200

Response Body

```json
{
    "data": [
        {
            "event_type": "bank_slip",
            "sms_template": null,
            "template_configuration_key": "e5c337db-dacc-4f1d-8a3e-919628640d51",
            "email_template": "e5c337db-dacc-4f1d-8a3e-919628640dd5"
        },
        {
            "event_type": "account_transaction",
            "sms_template": null,
            "template_configuration_key": "e5c337db-dacc-4f1d-8a3e-919628640ds1",
            "email_template": "e5c337db-dacc-4f1d-8a3e-919628640dd5"
        }
    ],
    "pagination": {
        "current_page": 0,
        "next_page": null,
        "rows_per_page": 10
    }
}
```

## Atualização de configuração de template

## Request

ENDPOINT /notification/template_configuration/ TEMPLATE_CONFIGURATION_KEY
MÉTODO PUT

Request Body

```json
{
    "event_type": "bank_slip",
    "email_template_key": "e5c337db-dacc-4f1d-8a3e-919628640dd5"
}
``` 

## Response

STATUS 201

Response Body

```json
{}
```

STATUS 4XX

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title` | Descrição (eng)<br/>`Description`        | Descrição (ptbr)<br/>`translation`                     |
|-------------|----------------------|--------------------|------------------------------------------|--------------------------------------------------------|
| 400         | PMB000022            | Bad Request        | The event type (event type) is not valid | O tipo de evento (tipo de evento) enviado não é válido |
| 404         | PMB000024            | Not Found          | Template configuration not found         | Configuração de template não encontrada                |

---

# Gerenciamento de Notificações Personalizadas

URL: /documentation/notificacoes/introducao

Nossa plataforma oferece uma gama abrangente de opções de notificação, incluindo e-mails, mensagens SMS e webhooks, permitindo que os usuários escolham o canal que melhor se adapta às suas necessidades e preferências. Além disso, proporcionamos a capacidade de personalização por meio de templates para e-mails e SMS, garantindo que as notificações estejam alinhadas com a identidade e estilo de comunicação do usuário.

Um dos aspectos mais notáveis do nosso sistema é a capacidade de os usuários definirem quando desejam receber notificações para eventos específicos. Essa flexibilidade permite uma gestão mais eficiente do fluxo de informações, garantindo que os usuários recebam apenas as notificações mais relevantes no momento mais oportuno.

Nesta seção de documentação, detalharemos os diferentes aspectos do Gerenciamento de Notificações Personalizadas, desde a configuração inicial até a personalização avançada, proporcionando aos usuários uma compreensão abrangente de como aproveitar ao máximo essa funcionalidade essencial em nossa plataforma.

---

# Reenvio de Notificações

URL: /documentation/notificacoes/reenvio_de_notificacoes

Aqui demonstramos como realizar o reenvio de callbacks de webhooks no sistema. O reenvio pode ser realizado para qualquer callback, independentemente do seu status atual.

## Fluxo de notificações
1. É necessário primeiro fazer uma consulta dos eventos elegíveis para o reenvio utilizando o método listado no **[Request](#request)**   
2. Após a coleta de dados utilizando o método GET, para fazer o reenvio de wenhooks, você deve passar as chaves event_key e callback_key dentro da sua requisição PATCH, conforme apresentado no guia de **[Reenvio de callback](#reenviando-um-callback)**

## Listando eventos elegíveis para reenvio

## Request

ENDPOINT /notification/events
MÉTODO GET

### Query Parameters

| Parâmetro        | Tipo    | Descrição                                                        |
|------------------|---------|------------------------------------------------------------------|
| event_type       | string  | Tipo do evento (ex: "debt_disbursed")                          |
| callback_status  | string  | Status do callback (ex: "failed", "sent", etc.)              |
| origin_key       | uuid    | Chave única da origem do evento                                  |
| start_datetime   | string  | Data/hora inicial no formato "YYYY-MM-DDTHH:mm:ssZ" (Fuso Horário UTC)            |
| end_datetime     | string  | Data/hora final no formato "YYYY-MM-DDTHH:mm:ssZ" (Fuso Horário UTC)              |

> **Observação:**
> A janela de tempo entre `start_datetime` e `end_datetime` deve ser no máximo 14 dias. Caso contrário, será retornado um erro.

## Response

STATUS 200

Response Body

```json
{
  "data": [
    {
      "event_key": "<UUID>",
      "event_type": "debt_disbursed",
      "status": "processed",
      "origin_enumerator": "account",
      "origin_key": "<UUID>",
      "callbacks": [
        {
          "callback_key": "<UUID>",
          "callback_status": "failed"
        }
      ],
    }
  ],
  "pagination": {
    "current_page": 1,
    "rows_per_page": 25,
  }
}
```

### Response Parameters

| Parâmetro        | Tipo    | Descrição                                                        |
|------------------|---------|------------------------------------------------------------------|
| event_key       | uuid  |  Chave única do evento                         |
| event_type       | string  | Tipo do evento (ex: "debt_disbursed")                          |
| status       | string  | Status do evento (ex: "processed")                          |
| origin_enumerator       | string    |  API de origem do evento (ex: "lego")                                 |
| origin_key       | uuid    | Chave única do recurso da API de origem                                  |
| callbacks  | list  |  Lista de objetos Callback            |
| pagination       | object  | Objeto Pagination                        |

### Callback Object

| Parâmetro        | Tipo    | Descrição                                                        |
|------------------|---------|------------------------------------------------------------------|
| callback_key     | uuid    | Chave única do callback   |
| callback_status  | string  | Status do callback (ex: "failed", "sent", etc.)   |

### Pagination Object

| Parâmetro        | Tipo    | Descrição                                                        |
|------------------|---------|------------------------------------------------------------------|
| current_page     | integer | Número da página atual                                           |
| rows_per_page    | integer | Quantidade de registros por página                               |

STATUS 400

Response Body: Error

```json
{
  "code": "PMB000032",
  "title": "Bad Request",
  "description": "Selected timeframe should have a maximum of 14 days",
  "translation": "O intervalo de tempo selecionado deve ter no máximo 14 dias",
}
```

## Reenviando um callback

## Request

:::important Limite de tempo
A janela de tempo para busca de eventos é limitada a 14 dias.
:::

:::warning Observações
Verifique que está utilizando a event_key e a callback_key obtidas na request feita anteriormente.
:::

ENDPOINT `/notification/event/{event_key}/callback/{callback_key}/retry`
MÉTODO PATCH

### Path Parameters

| Parâmetro    | Tipo  | Descrição                                      |
|--------------|-------|------------------------------------------------|
| event_key    | uuid  | Chave única do evento (obtida na listagem)     |
| callback_key | uuid  | Chave única do callback (obtida na listagem)   |

**Exemplo de Uso**

```bash
curl -X PATCH "https://api-auth.sandbox.qitech.app/notification/event/123e4567-e89b-12d3-a456-426614174000/callback/987fcdeb-51a2-43d7-9012-345678901234/retry"
```

## Response

STATUS 204

Response Body

```json
{}
```

## Troubleshooting

Em caso de problemas com o reenvio de callbacks:

1. Verifique se o `event_key` e `callback_key` estão corretos.
2. Confirme se o callback existe.
3. Verifique se a janela de tempo está dentro do limite de 14 dias.
4. Em caso de erro persistente, entre em contato com o suporte técnico.

---

# Templates

URL: /documentation/notificacoes/template

Aqui veremos como criar templates do tipo e-mail e sms, esses templates permitirão personalizar as mensagens de texto e email enviados em cada tipo de evento.

Caso não seja configurado e a configuração esteja habilitada será enviado o template padrão da nossa plataforma.

Obs: onde você desejar inserir uma variável customizada basta adicionar no texto '[nome_da_variável]' 

## Criação de template SMS

## Request

ENDPOINT /notification/template
MÉTODO POST

Request Body

```json
{
    "template_type": "sms",
    "template": "Olá seu token e [name]"
}
```

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `template_type` *|  string | Tipo do template -> Valor default `sms` | - | |
| `template` * |  string | Texto do sms | 160 |

## Response

STATUS 201

Response Body

```json
{
    "template_key": "17f49953-29a1-439c-a6be-db37a32e2746"
}
```

## Criação de template E-mail

:::warning Aviso
O template de email se trata de um documento HTML compátivel com html para email.

O mesmo deve ser encodado em base64.
::: 

## Request

ENDPOINT /notification/template
MÉTODO POST

Request Body

```json
{
    "template_type": "email",
    "subject": "Título do email",
    "template": "PCFET0NUWVBFIGh0bWw+CjxodG1sIHhtbG5zOnY9InVybjpzY2hlbWFzLW1pY3Jvc29mdC1jb206dm1sIiB4bWxuczpvPSJ1cm46c2NoZW1hcy1taWNyb3NvZnQtY29tOm9mZmljZTpvZmZpY2UiIGxhbmc9ImVuIj4KICA8aGVhZD4KICAgIDx0aXRsZT48L3RpdGxlPgogICAgPG1ldGEgY2hhcnNldD0iVVRGLTgiPgogICAgPG1ldGEgbmFtZT0idmlld3BvcnQiIGNvbnRlbnQ9IndpZHRoPWRldmljZS13aWR0aCwgaW5pdGlhbC1zY2FsZT0xLjAiPgogICAgPCEtLVtpZiBtc29dPgoJCQkJPHhtbD4KCQkJCQk8bzpPZmZpY2VEb2N1bWVudFNldHRpbmdzPgoJCQkJCQk8bzpQaXhlbHNQZXJJbmNoPjk2PC9vOlBpeGVsc1BlckluY2g+CgkJCQkJCTxvOkFsbG93UE5HLz4KCQkJCQk8L286T2ZmaWNlRG9jdW1lbnRTZXR0aW5ncz4KCQkJCTwveG1sPgoJCQkJPCFbZW5kaWZdLS0+CiAgICA8IS0tW2lmICFtc29dPgoJCQkJPCEtLT4KICAgIDxsaW5rIGhyZWY9Imh0dHBzOi8vZm9udHMuZ29vZ2xlYXBpcy5jb20vY3NzP2ZhbWlseT1Nb250c2VycmF0IiByZWw9InN0eWxlc2hlZXQiIHR5cGU9InRleHQvY3NzIj4KICAgIDwhLS0KCQkJCQk8IVtlbmRpZl0tLT4KICAgIDxzdHlsZT4KICAgICAgKiB7CiAgICAgICAgYm94LXNpemluZzogYm9yZGVyLWJveDsKICAgICAgfQoKICAgICAgYm9keSB7CiAgICAgICAgbWFyZ2luOiAwOwogICAgICAgIHBhZGRpbmc6IDA7CiAgICAgIH0KCiAgICAgIGFbeC1hcHBsZS1kYXRhLWRldGVjdG9yc10gewogICAgICAgIGNvbG9yOiBpbmhlcml0ICFpbXBvcnRhbnQ7CiAgICAgICAgdGV4dC1kZWNvcmF0aW9uOiBpbmhlcml0ICFpbXBvcnRhbnQ7CiAgICAgIH0KCiAgICAgICNNZXNzYWdlVmlld0JvZHkgYSB7CiAgICAgICAgY29sb3I6IGluaGVyaXQ7CiAgICAgICAgdGV4dC1kZWNvcmF0aW9uOiBub25lOwogICAgICB9CgogICAgICBwIHsKICAgICAgICBsaW5lLWhlaWdodDogaW5oZXJpdAogICAgICB9CgogICAgICBAbWVkaWEgKG1heC13aWR0aDo2MjBweCkgewogICAgICAgIC5yb3ctY29udGVudCB7CiAgICAgICAgICB3aWR0aDogMTAwJSAhaW1wb3J0YW50OwogICAgICAgIH0KCiAgICAgICAgLnN0YWNrIC5jb2x1bW4gewogICAgICAgICAgd2lkdGg6IDEwMCU7CiAgICAgICAgICBkaXNwbGF5OiB3aXRoOwogICAgICAgIH0KICAgICAgfQogICAgPC9zdHlsZT4KICA8L2hlYWQ+CiAgPGJvZHkgc3R5bGU9ImJhY2tncm91bmQtY29sb3I6ICNmZmY7IG1hcmdpbjogMDsgcGFkZGluZzogMDsgLXdlYmtpdC10ZXh0LXNpemUtYWRqdXN0OiBub25lOyB0ZXh0LXNpemUtYWRqdXN0OiBub25lOyI+CiAgICA8dGFibGUgY2xhc3M9Im5sLWNvbnRhaW5lciIgd2lkdGg9IjEwMCUiIGJvcmRlcj0iMCIgY2VsbHBhZGRpbmc9IjAiIGNlbGxzcGFjaW5nPSIwIiByb2xlPSJwcmVzZW50YXRpb24iIHN0eWxlPSJtc28tdGFibGUtbHNwYWNlOiAwcHQ7IG1zby10YWJsZS1yc3BhY2U6IDBwdDsgYmFja2dyb3VuZC1jb2xvcjogI2ZmZjsiPgogICAgICA8dGJvZHk+CiAgICAgICAgPHRyPgogICAgICAgICAgPHRkPgogICAgICAgICAgICA8dGFibGUgY2xhc3M9InJvdyByb3ctMSIgYWxpZ249ImNlbnRlciIgd2lkdGg9IjEwMCUiIGJvcmRlcj0iMCIgY2VsbHBhZGRpbmc9IjAiIGNlbGxzcGFjaW5nPSIwIiByb2xlPSJwcmVzZW50YXRpb24iIHN0eWxlPSJtc28tdGFibGUtbHNwYWNlOiAwcHQ7IG1zby10YWJsZS1yc3BhY2U6IDBwdDsiPgogICAgICAgICAgICAgIDx0Ym9keT4KICAgICAgICAgICAgICAgIDx0cj4KICAgICAgICAgICAgICAgICAgPHRkPgogICAgICAgICAgICAgICAgICAgIDx0YWJsZSBjbGFzcz0icm93LWNvbnRlbnQgc3RhY2siIGFsaWduPSJjZW50ZXIiIGJvcmRlcj0iMCIgY2VsbHBhZGRpbmc9IjAiIGNlbGxzcGFjaW5nPSIwIiByb2xlPSJwcmVzZW50YXRpb24iIHN0eWxlPSJtc28tdGFibGUtbHNwYWNlOiAwcHQ7IG1zby10YWJsZS1yc3BhY2U6IDBwdDsgY29sb3I6ICMwMDAwMDA7IHdpZHRoOiA2MDBweDsiIHdpZHRoPSI2MDAiPgogICAgICAgICAgICAgICAgICAgICAgPHRib2R5PgogICAgICAgICAgICAgICAgICAgICAgICA8dHI+CiAgICAgICAgICAgICAgICAgICAgICAgICAgPHRkIGNsYXNzPSJjb2x1bW4iIHdpZHRoPSIxMDAlIiBzdHlsZT0ibXNvLXRhYmxlLWxzcGFjZTogMHB0OyBtc28tdGFibGUtcnNwYWNlOiAwcHQ7IGZvbnQtd2VpZ2h0OiA0MDA7IHRleHQtYWxpZ246IGxlZnQ7IHZlcnRpY2FsLWFsaWduOiB0b3A7IHBhZGRpbmctdG9wOiA1cHg7IHBhZGRpbmctYm90dG9tOiA1cHg7IGJvcmRlci10b3A6IDBweDsgYm9yZGVyLXJpZ2h0OiAwcHg7IGJvcmRlci1ib3R0b206IDBweDsgYm9yZGVyLWxlZnQ6IDBweDsiPgogICAgICAgICAgICAgICAgICAgICAgICAgICAgPHRhYmxlIGNsYXNzPSJpbWFnZV9ibG9jayIgd2lkdGg9IjEwMCUiIGJvcmRlcj0iMCIgY2VsbHBhZGRpbmc9IjIwIiBjZWxsc3BhY2luZz0iMCIgcm9sZT0icHJlc2VudGF0aW9uIiBzdHlsZT0ibXNvLXRhYmxlLWxzcGFjZTogMHB0OyBtc28tdGFibGUtcnNwYWNlOiAwcHQ7Ij4KICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgPHRyPgogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDx0ZD4KICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDxkaXYgYWxpZ249ImNlbnRlciIgc3R5bGU9ImxpbmUtaGVpZ2h0OjEwcHgiPgogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICA8aW1nIHNyYz0iaHR0cHM6Ly85bzM3Lm1qdC5sdS90cGxpbWcvOW8zNy9iLzF5ejdpL2hrM3NwLnBuZyIgc3R5bGU9ImRpc3BsYXk6IGJsb2NrOyBoZWlnaHQ6IGF1dG87IGJvcmRlcjogMDsgd2lkdGg6IDEyMHB4OyBtYXgtd2lkdGg6IDEwMCU7IiB3aWR0aD0iMTIwIiBhbHQ9InBsYWNlaG9sZGVyIGxvZ28iIHRpdGxlPSJwbGFjZWhvbGRlciBsb2dvIj4KICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDwvZGl2PgogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDwvdGQ+CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDwvdHI+CiAgICAgICAgICAgICAgICAgICAgICAgICAgICA8L3RhYmxlPgogICAgICAgICAgICAgICAgICAgICAgICAgIDwvdGQ+CiAgICAgICAgICAgICAgICAgICAgICAgIDwvdHI+CiAgICAgICAgICAgICAgICAgICAgICA8L3Rib2R5PgogICAgICAgICAgICAgICAgICAgIDwvdGFibGU+CiAgICAgICAgICAgICAgICAgIDwvdGQ+CiAgICAgICAgICAgICAgICA8L3RyPgogICAgICAgICAgICAgIDwvdGJvZHk+CiAgICAgICAgICAgIDwvdGFibGU+CiAgICAgICAgICAgIDx0YWJsZSBjbGFzcz0icm93IHJvdy0yIiBhbGlnbj0iY2VudGVyIiB3aWR0aD0iMTAwJSIgYm9yZGVyPSIwIiBjZWxscGFkZGluZz0iMCIgY2VsbHNwYWNpbmc9IjAiIHJvbGU9InByZXNlbnRhdGlvbiIgc3R5bGU9Im1zby10YWJsZS1sc3BhY2U6IDBwdDsgbXNvLXRhYmxlLXJzcGFjZTogMHB0OyI+CiAgICAgICAgICAgICAgPHRib2R5PgogICAgICAgICAgICAgICAgPHRyPgogICAgICAgICAgICAgICAgICA8dGQ+CiAgICAgICAgICAgICAgICAgICAgPHRhYmxlIGNsYXNzPSJyb3ctY29udGVudCBzdGFjayIgYWxpZ249ImNlbnRlciIgYm9yZGVyPSIwIiBjZWxscGFkZGluZz0iMCIgY2VsbHNwYWNpbmc9IjAiIHJvbGU9InByZXNlbnRhdGlvbiIgc3R5bGU9Im1zby10YWJsZS1sc3BhY2U6IDBwdDsgbXNvLXRhYmxlLXJzcGFjZTogMHB0OyBjb2xvcjogIzAwMDAwMDsgd2lkdGg6IDYwMHB4OyIgd2lkdGg9IjYwMCI+CiAgICAgICAgICAgICAgICAgICAgICA8dGJvZHk+CiAgICAgICAgICAgICAgICAgICAgICAgIDx0cj4KICAgICAgICAgICAgICAgICAgICAgICAgICA8dGQgY2xhc3M9ImNvbHVtbiIgd2lkdGg9IjEwMCUiIHN0eWxlPSJtc28tdGFibGUtbHNwYWNlOiAwcHQ7IG1zby10YWJsZS1yc3BhY2U6IDBwdDsgZm9udC13ZWlnaHQ6IDQwMDsgdGV4dC1hbGlnbjogbGVmdDsgdmVydGljYWwtYWxpZ246IHRvcDsgcGFkZGluZy10b3A6IDVweDsgcGFkZGluZy1ib3R0b206IDVweDsgYm9yZGVyLXRvcDogMHB4OyBib3JkZXItcmlnaHQ6IDBweDsgYm9yZGVyLWJvdHRvbTogMHB4OyBib3JkZXItbGVmdDogMHB4OyI+CiAgICAgICAgICAgICAgICAgICAgICAgICAgICA8dGFibGUgY2xhc3M9ImhlYWRpbmdfYmxvY2siIHdpZHRoPSIxMDAlIiBib3JkZXI9IjAiIGNlbGxwYWRkaW5nPSIwIiBjZWxsc3BhY2luZz0iMCIgcm9sZT0icHJlc2VudGF0aW9uIiBzdHlsZT0ibXNvLXRhYmxlLWxzcGFjZTogMHB0OyBtc28tdGFibGUtcnNwYWNlOiAwcHQ7Ij4KICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgPHRyPgogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDx0ZCBzdHlsZT0icGFkZGluZy1ib3R0b206MjBweDtwYWRkaW5nLWxlZnQ6MjBweDtwYWRkaW5nLXJpZ2h0OjIwcHg7cGFkZGluZy10b3A6NjBweDt0ZXh0LWFsaWduOmNlbnRlcjt3aWR0aDoxMDAlOyI+CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICA8aDEgc3R5bGU9Im1hcmdpbjogMDsgY29sb3I6ICMwMDAwMDA7IGRpcmVjdGlvbjogbHRyOyBmb250LWZhbWlseTogTW9udHNlcnJhdCwgVHJlYnVjaGV0IE1TLCBMdWNpZGEgR3JhbmRlLCBMdWNpZGEgU2FucyBVbmljb2RlLCBMdWNpZGEgU2FucywgVGFob21hLCBzYW5zLXNlcmlmOyBmb250LXNpemU6IDI1cHg7IGZvbnQtd2VpZ2h0OiBub3JtYWw7IGxldHRlci1zcGFjaW5nOiBub3JtYWw7IGxpbmUtaGVpZ2h0OiAxMjAlOyB0ZXh0LWFsaWduOiBjZW50ZXI7IG1hcmdpbi10b3A6IDA7IG1hcmdpbi1ib3R0b206IDA7Ij4KICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgPHN0cm9uZz5NQU5VVEVOw4fDg08gUFJPR1JBTUFEQTwvc3Ryb25nPgogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICA8YnI+CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICA8L2gxPgogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDwvdGQ+CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDwvdHI+CiAgICAgICAgICAgICAgICAgICAgICAgICAgICA8L3RhYmxlPgogICAgICAgICAgICAgICAgICAgICAgICAgICAgPHRhYmxlIGNsYXNzPSJ0ZXh0X2Jsb2NrIiB3aWR0aD0iMTAwJSIgYm9yZGVyPSIwIiBjZWxscGFkZGluZz0iMCIgY2VsbHNwYWNpbmc9IjAiIHJvbGU9InByZXNlbnRhdGlvbiIgc3R5bGU9Im1zby10YWJsZS1sc3BhY2U6IDBwdDsgbXNvLXRhYmxlLXJzcGFjZTogMHB0OyB3b3JkLWJyZWFrOiBicmVhay13b3JkOyI+CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDx0cj4KICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICA8dGQgc3R5bGU9InBhZGRpbmctYm90dG9tOjgwcHg7cGFkZGluZy1sZWZ0OjIwcHg7cGFkZGluZy1yaWdodDoyMHB4O3BhZGRpbmctdG9wOjYwcHg7Ij4KICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDxkaXYgc3R5bGU9ImZvbnQtZmFtaWx5OiBzYW5zLXNlcmlmIj4KICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgPGRpdiBzdHlsZT0iZm9udC1zaXplOiAxNnB4OyBtc28tbGluZS1oZWlnaHQtYWx0OiAxNi44cHg7IGNvbG9yOiAjMDAwMDAwOyBsaW5lLWhlaWdodDogMS4yOyBmb250LWZhbWlseTogTW9udHNlcnJhdCwgVHJlYnVjaGV0IE1TLCBMdWNpZGEgR3JhbmRlLCBMdWNpZGEgU2FucyBVbmljb2RlLCBMdWNpZGEgU2FucywgVGFob21hLCBzYW5zLXNlcmlmOyI+CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgPHAgc3R5bGU9Im1hcmdpbjogMDsgZm9udC1zaXplOiAxOHB4OyB0ZXh0LWFsaWduOiBsZWZ0OyI+CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICA8YnI+SW5mb3JtYW1vcyBxdWUgbm8gZGlhIDxiPjE4IGRlIGZldmVyZWlybyAoZG9taW5nbyk8L2I+LCBhIFFJIFRlY2ggcmVhbGl6YXLDoSB1bWEgbWFudXRlbsOnw6NvIGdlcmFsIGVtIHRvZG9zIG9zIHNldXMgc2lzdGVtYXMgZSBzZXJ2acOnb3MuIEVzdGEgbWFudXRlbsOnw6NvIHRlcsOhIHVtYSBkdXJhw6fDo28gZGUgdHLDqnMgaG9yYXMsIHRlbmRvIHNldSA8c3Ryb25nPmluw61jaW8gw6BzIDAyOjAwICgyQU0pPC9zdHJvbmc+IGUgc2V1IDxzdHJvbmc+dMOpcm1pbm8gw6BzIDA1OjAwICg1QU0pPC9zdHJvbmc+LgogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDwvcD4KICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICA8cCBzdHlsZT0ibWFyZ2luOiAwOyBmb250LXNpemU6IDE4cHg7IHRleHQtYWxpZ246IGxlZnQ7Ij4KICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDxicj4KICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICA8L3A+CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgPHA+IFNlcnZpw6dvcyA8c3Ryb25nPmluZGlzcG9uw612ZWlzPC9zdHJvbmc+IGR1cmFudGUgYSBtYW5udXRlbsOnw6NvOiA8L3A+CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgPC9wPgogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDx1bD4KICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIAogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgPGxpPlRvZG9zIHNlcnZpw6dvcyByZWxhY2lvbmFkb3MgYW8gUGl4W25hbWVdPC9saT4KICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDxsaT5QbGF0YWZvcm1hIDxzdHJvbmc+cWl0ZWNoLmFwcDwvc3Ryb25nPjwvbGk+CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICA8bGk+VG9kYXMgYXMgQVBJczwvbGk+CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICA8bGk+QVBQIFFpIENvbnRhPC9saT4KICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICA8L3VsPgogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDxwIHN0eWxlPSJtYXJnaW46IDA7IGZvbnQtc2l6ZTogMTZweDsgdGV4dC1hbGlnbjogbGVmdDsgbXNvLWxpbmUtaGVpZ2h0LWFsdDogMTYuOHB4OyI+Jm5ic3A7PC9wPgogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDxwIHN0eWxlPSJtYXJnaW46IDA7IGZvbnQtc2l6ZTogMTZweDsgdGV4dC1hbGlnbjogbGVmdDsiPkF0ZW5jaW9zYW1lbnRlLDwvcD4KICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgPC9kaXY+CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICA8L2Rpdj4KICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICA8L3RkPgogICAgICAgICAgICAgICAgICAgICAgICAgICAgICA8L3RyPgogICAgICAgICAgICAgICAgICAgICAgICAgICAgPC90YWJsZT4KICAgICAgICAgICAgICAgICAgICAgICAgICA8L3RkPgogICAgICAgICAgICAgICAgICAgICAgICA8L3RyPgogICAgICAgICAgICAgICAgICAgICAgPC90Ym9keT4KICAgICAgICAgICAgICAgICAgICA8L3RhYmxlPgogICAgICAgICAgICAgICAgICA8L3RkPgogICAgICAgICAgICAgICAgPC90cj4KICAgICAgICAgICAgICA8L3Rib2R5PgogICAgICAgICAgICA8L3RhYmxlPgogICAgICAgICAgICA8dGFibGUgY2xhc3M9InJvdyByb3ctMyIgYWxpZ249ImNlbnRlciIgd2lkdGg9IjEwMCUiIGJvcmRlcj0iMCIgY2VsbHBhZGRpbmc9IjAiIGNlbGxzcGFjaW5nPSIwIiByb2xlPSJwcmVzZW50YXRpb24iIHN0eWxlPSJtc28tdGFibGUtbHNwYWNlOiAwcHQ7IG1zby10YWJsZS1yc3BhY2U6IDBwdDsgYmFja2dyb3VuZC1jb2xvcjogI2ZmZjsiPgogICAgICAgICAgICAgIDx0Ym9keT4KICAgICAgICAgICAgICAgIDx0cj4KICAgICAgICAgICAgICAgICAgPHRkPgogICAgICAgICAgICAgICAgICAgIDx0YWJsZSBjbGFzcz0icm93LWNvbnRlbnQgc3RhY2siIGFsaWduPSJjZW50ZXIiIGJvcmRlcj0iMCIgY2VsbHBhZGRpbmc9IjAiIGNlbGxzcGFjaW5nPSIwIiByb2xlPSJwcmVzZW50YXRpb24iIHN0eWxlPSJtc28tdGFibGUtbHNwYWNlOiAwcHQ7IG1zby10YWJsZS1yc3BhY2U6IDBwdDsgY29sb3I6ICNmZmY7IHdpZHRoOiA2MDBweDsiIHdpZHRoPSI2MDAiPgogICAgICAgICAgICAgICAgICAgICAgPHRib2R5PgogICAgICAgICAgICAgICAgICAgICAgICA8dHI+CiAgICAgICAgICAgICAgICAgICAgICAgICAgPHRkIGNsYXNzPSJjb2x1bW4iIHdpZHRoPSIxMDAlIiBzdHlsZT0ibXNvLXRhYmxlLWxzcGFjZTogMHB0OyBtc28tdGFibGUtcnNwYWNlOiAwcHQ7IGZvbnQtd2VpZ2h0OiA0MDA7IHRleHQtYWxpZ246IGxlZnQ7IHZlcnRpY2FsLWFsaWduOiB0b3A7IHBhZGRpbmctbGVmdDogMjBweDsgcGFkZGluZy1yaWdodDogMjBweDsgcGFkZGluZy10b3A6IDBweDsgcGFkZGluZy1ib3R0b206IDEwcHg7IGJvcmRlci10b3A6IDBweDsgYm9yZGVyLXJpZ2h0OiAwcHg7IGJvcmRlci1ib3R0b206IDBweDsgYm9yZGVyLWxlZnQ6IDBweDsiPgogICAgICAgICAgICAgICAgICAgICAgICAgICAgPHRhYmxlIGNsYXNzPSJpbWFnZV9ibG9jayIgd2lkdGg9IjEwMCUiIGJvcmRlcj0iMCIgY2VsbHBhZGRpbmc9IjAiIGNlbGxzcGFjaW5nPSIwIiByb2xlPSJwcmVzZW50YXRpb24iIHN0eWxlPSJtc28tdGFibGUtbHNwYWNlOiAwcHQ7IG1zby10YWJsZS1yc3BhY2U6IDBwdDsiPgogICAgICAgICAgICAgICAgICAgICAgICAgICAgICA8dHI+CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgPHRkIHN0eWxlPSJ3aWR0aDoxMDAlO3BhZGRpbmctcmlnaHQ6MHB4O3BhZGRpbmctbGVmdDowcHg7Ij4KICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDxkaXYgYWxpZ249ImNlbnRlciIgc3R5bGU9ImxpbmUtaGVpZ2h0OjEwcHgiPgogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICA8aW1nIHNyYz0iaHR0cHM6Ly85bzM3Lm1qdC5sdS90cGxpbWcvOW8zNy9iLzF5ejdpL2hrM3NwLnBuZyIgc3R5bGU9ImRpc3BsYXk6IGJsb2NrOyBoZWlnaHQ6IGF1dG87IGJvcmRlcjogMDsgd2lkdGg6IDEyNnB4OyBtYXgtd2lkdGg6IDEwMCU7IiB3aWR0aD0iMTI2Ij4KICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDwvZGl2PgogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDwvdGQ+CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDwvdHI+CiAgICAgICAgICAgICAgICAgICAgICAgICAgICA8L3RhYmxlPgogICAgICAgICAgICAgICAgICAgICAgICAgIDwvdGQ+CiAgICAgICAgICAgICAgICAgICAgICAgIDwvdHI+CiAgICAgICAgICAgICAgICAgICAgICA8L3Rib2R5PgogICAgICAgICAgICAgICAgICAgIDwvdGFibGU+CiAgICAgICAgICAgICAgICAgIDwvdGQ+CiAgICAgICAgICAgICAgICA8L3RyPgogICAgICAgICAgICAgIDwvdGJvZHk+CiAgICAgICAgICAgIDwvdGFibGU+CiAgICAgICAgICAgIDx0YWJsZSBjbGFzcz0icm93IHJvdy00IiBhbGlnbj0iY2VudGVyIiB3aWR0aD0iMTAwJSIgYm9yZGVyPSIwIiBjZWxscGFkZGluZz0iMCIgY2VsbHNwYWNpbmc9IjAiIHJvbGU9InByZXNlbnRhdGlvbiIgc3R5bGU9Im1zby10YWJsZS1sc3BhY2U6IDBwdDsgbXNvLXRhYmxlLXJzcGFjZTogMHB0OyI+CiAgICAgICAgICAgICAgPHRib2R5PgogICAgICAgICAgICAgICAgPHRyPgogICAgICAgICAgICAgICAgICA8dGQ+CiAgICAgICAgICAgICAgICAgICAgPHRhYmxlIGNsYXNzPSJyb3ctY29udGVudCBzdGFjayIgYWxpZ249ImNlbnRlciIgYm9yZGVyPSIwIiBjZWxscGFkZGluZz0iMCIgY2VsbHNwYWNpbmc9IjAiIHJvbGU9InByZXNlbnRhdGlvbiIgc3R5bGU9Im1zby10YWJsZS1sc3BhY2U6IDBwdDsgbXNvLXRhYmxlLXJzcGFjZTogMHB0OyBjb2xvcjogI2ZmZjsgd2lkdGg6IDYwMHB4OyIgd2lkdGg9IjYwMCI+CiAgICAgICAgICAgICAgICAgICAgICA8dGJvZHk+CiAgICAgICAgICAgICAgICAgICAgICAgIDx0cj4KICAgICAgICAgICAgICAgICAgICAgICAgICA8dGQgY2xhc3M9ImNvbHVtbiIgd2lkdGg9IjEwMCUiIHN0eWxlPSJtc28tdGFibGUtbHNwYWNlOiAwcHQ7IG1zby10YWJsZS1yc3BhY2U6IDBwdDsgZm9udC13ZWlnaHQ6IDQwMDsgdGV4dC1hbGlnbjogbGVmdDsgdmVydGljYWwtYWxpZ246IHRvcDsgcGFkZGluZy10b3A6IDVweDsgcGFkZGluZy1ib3R0b206IDVweDsgYm9yZGVyLXRvcDogMHB4OyBib3JkZXItcmlnaHQ6IDBweDsgYm9yZGVyLWJvdHRvbTogMHB4OyBib3JkZXItbGVmdDogMHB4OyI+CiAgICAgICAgICAgICAgICAgICAgICAgICAgICA8dGFibGUgY2xhc3M9Imh0bWxfYmxvY2siIHdpZHRoPSIxMDAlIiBib3JkZXI9IjAiIGNlbGxwYWRkaW5nPSIwIiBjZWxsc3BhY2luZz0iMCIgcm9sZT0icHJlc2VudGF0aW9uIiBzdHlsZT0ibXNvLXRhYmxlLWxzcGFjZTogMHB0OyBtc28tdGFibGUtcnNwYWNlOiAwcHQ7Ij4KICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgPHRyPgogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDx0ZD4KICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDxkaXYgc3R5bGU9ImZvbnQtZmFtaWx5Ok1vbnRzZXJyYXQsIFRyZWJ1Y2hldCBNUywgTHVjaWRhIEdyYW5kZSwgTHVjaWRhIFNhbnMgVW5pY29kZSwgTHVjaWRhIFNhbnMsIFRhaG9tYSwgc2Fucy1zZXJpZjt0ZXh0LWFsaWduOmNlbnRlcjsiIGFsaWduPSJjZW50ZXIiPgogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICA8ZGl2IHN0eWxlPSJoZWlnaHQ6MzBweDsiPiZuYnNwOzwvZGl2PgogICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgPC9kaXY+CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgPC90ZD4KICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgPC90cj4KICAgICAgICAgICAgICAgICAgICAgICAgICAgIDwvdGFibGU+CiAgICAgICAgICAgICAgICAgICAgICAgICAgPC90ZD4KICAgICAgICAgICAgICAgICAgICAgICAgPC90cj4KICAgICAgICAgICAgICAgICAgICAgIDwvdGJvZHk+CiAgICAgICAgICAgICAgICAgICAgPC90YWJsZT4KICAgICAgICAgICAgICAgICAgPC90ZD4KICAgICAgICAgICAgICAgIDwvdHI+CiAgICAgICAgICAgICAgPC90Ym9keT4KICAgICAgICAgICAgPC90YWJsZT4KICAgICAgICAgIDwvdGQ+CiAgICAgICAgPC90cj4KICAgICAgPC90Ym9keT4KICAgIDwvdGFibGU+CiAgICA8IS0tIEVuZCAtLT4KICAgIDxkaXYgc3R5bGU9ImJhY2tncm91bmQ6I2ZmZmZmZjtiYWNrZ3JvdW5kLWNvbG9yOiNmZmZmZmY7bWFyZ2luOjBweCBhdXRvO21heC13aWR0aDo2MDBweDsiPgogICAgICA8dGFibGUgYWxpZ249ImNlbnRlciIgYm9yZGVyPSIwIiBjZWxscGFkZGluZz0iMCIgY2VsbHNwYWNpbmc9IjAiIHJvbGU9InByZXNlbnRhdGlvbiIgc3R5bGU9ImJhY2tncm91bmQ6I2ZmZmZmZjtiYWNrZ3JvdW5kLWNvbG9yOiNmZmZmZmY7d2lkdGg6MTAwJTsiPgogICAgICAgIDx0Ym9keT4KICAgICAgICAgIDx0cj4KICAgICAgICAgICAgPHRkIHN0eWxlPSJib3JkZXI6MHB4IHNvbGlkICNmZmZmZmY7ZGlyZWN0aW9uOmx0cjtmb250LXNpemU6MHB4O3BhZGRpbmc6MHB4IDMwcHggMjVweCAzMHB4O3BhZGRpbmctYm90dG9tOjI1cHg7cGFkZGluZy1sZWZ0OjMwcHg7cGFkZGluZy1yaWdodDozMHB4O3BhZGRpbmctdG9wOjBweDt0ZXh0LWFsaWduOmNlbnRlcjsiPgogICAgICAgICAgICAgIDwhLS1baWYgbXNvIHwgSUVdPgoJCQkJCQkJCQkJCQkJCQk8dGFibGUgcm9sZT0icHJlc2VudGF0aW9uIiBib3JkZXI9IjAiIGNlbGxwYWRkaW5nPSIwIiBjZWxsc3BhY2luZz0iMCI+CgkJCQkJCQkJCQkJCQkJCQk8dHI+CgkJCQkJCQkJCQkJCQkJCQkJPHRkIGNsYXNzPSIiIHN0eWxlPSJ2ZXJ0aWNhbC1hbGlnbjp0b3A7d2lkdGg6NTQwcHg7IiA+CgkJCQkJCQkJCQkJCQkJCQkJCTwhW2VuZGlmXS0tPgogICAgICAgICAgICAgIDxkaXYgY2xhc3M9Im1qLWNvbHVtbi1wZXItMTAwIG1qLW91dGxvb2stZ3JvdXAtZml4IiBzdHlsZT0iZm9udC1zaXplOjBweDt0ZXh0LWFsaWduOmxlZnQ7ZGlyZWN0aW9uOmx0cjtkaXNwbGF5OmlubGluZS1ibG9jazt2ZXJ0aWNhbC1hbGlnbjp0b3A7d2lkdGg6MTAwJTsiPgogICAgICAgICAgICAgICAgPHRhYmxlIGJvcmRlcj0iMCIgY2VsbHBhZGRpbmc9IjAiIGNlbGxzcGFjaW5nPSIwIiByb2xlPSJwcmVzZW50YXRpb24iIHN0eWxlPSJ2ZXJ0aWNhbC1hbGlnbjp0b3A7IiB3aWR0aD0iMTAwJSI+CiAgICAgICAgICAgICAgICAgIDx0cj4KICAgICAgICAgICAgICAgICAgICA8dGQgYWxpZ249ImxlZnQiIHN0eWxlPSJmb250LXNpemU6MHB4O3BhZGRpbmc6MTBweCAyNXB4O3BhZGRpbmctdG9wOjBweDtwYWRkaW5nLWJvdHRvbTowcHg7d29yZC1icmVhazpicmVhay13b3JkOyI+CiAgICAgICAgICAgICAgICAgICAgICA8ZGl2IHN0eWxlPSJmb250LWZhbWlseTpBcmlhbCwgc2Fucy1zZXJpZjtmb250LXNpemU6MTRweDtsZXR0ZXItc3BhY2luZzpub3JtYWw7bGluZS1oZWlnaHQ6MTt0ZXh0LWFsaWduOmxlZnQ7Y29sb3I6IzAwMDAwMDsiPgogICAgICAgICAgICAgICAgICAgICAgICA8cCBjbGFzcz0idGV4dC1idWlsZC1jb250ZW50IiBzdHlsZT0idGV4dC1hbGlnbjogY2VudGVyOyBtYXJnaW46IDEwcHggMDsgbWFyZ2luLXRvcDogMTBweDsiIGRhdGEtdGVzdGlkPSIyNFlfYk1SSW9JIj4KICAgICAgICAgICAgICAgICAgICAgICAgICA8c3BhbiBzdHlsZT0iY29sb3I6IzE5MjQ3RTtmb250LWZhbWlseTpSb2JvdG87Zm9udC1zaXplOjE0cHg7Ij48L3NwYW4+CiAgICAgICAgICAgICAgICAgICAgICAgIDwvcD4KICAgICAgICAgICAgICAgICAgICAgICAgPHAgY2xhc3M9InRleHQtYnVpbGQtY29udGVudCIgc3R5bGU9InRleHQtYWxpZ246IGNlbnRlcjsgbWFyZ2luOiAxMHB4IDA7IG1hcmdpbi1ib3R0b206IDEwcHg7IiBkYXRhLXRlc3RpZD0iMjRZX2JNUklvSSI+CiAgICAgICAgICAgICAgICAgICAgICAgICAgPHNwYW4gc3R5bGU9ImNvbG9yOiMxOTI0N0U7Zm9udC1mYW1pbHk6Um9ib3RvO2ZvbnQtc2l6ZToxNHB4OyI+CiAgICAgICAgICAgICAgICAgICAgICAgICAgICA8YSBocmVmPSJbW1VOU1VCX0xJTktfRU5dXSI+CiAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIDxiciAvPgogICAgICAgICAgICAgICAgICAgICAgICAgICAgICA8YnIgLz4KICAgICAgICAgICAgICAgICAgICAgICAgICAgIDwvYT4KICAgICAgICAgICAgICAgICAgICAgICAgICA8L3NwYW4+CiAgICAgICAgICAgICAgICAgICAgICAgIDwvcD4KICAgICAgICAgICAgICAgICAgICAgIDwvZGl2PgogICAgICAgICAgICAgICAgICAgIDwvdGQ+CiAgICAgICAgICAgICAgICAgIDwvdHI+CiAgICAgICAgICAgICAgICA8L3RhYmxlPgogICAgICAgICAgICAgIDwvZGl2PgogICAgICAgICAgICAgIDwhLS1baWYgbXNvIHwgSUVdPgoJCQkJCQkJCQkJCQkJCQkJCTwvdGQ+CgkJCQkJCQkJCQkJCQkJCQk8L3RyPgoJCQkJCQkJCQkJCQkJCQk8L3RhYmxlPgoJCQkJCQkJCQkJCQkJCQk8IVtlbmRpZl0tLT4KICAgICAgICAgICAgPC90ZD4KICAgICAgICAgIDwvdHI+CiAgICAgICAgPC90Ym9keT4KICAgICAgPC90YWJsZT4KICAgIDwvZGl2PgogICAgPCEtLVtpZiBtc28gfCBJRV0+CgkJCQkJCQkJCTwvdGQ+CgkJCQkJCQkJPC90cj4KCQkJCQkJCTwvdGFibGU+CgkJCQkJCQk8IVtlbmRpZl0tLT4KICA8L2JvZHk+CjwvaHRtbD4="
}
```

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `template_type` *|  string | Tipo do template -> Valor default `email` | - | |
| `template` * |  string | base64 do template | - |
| `subject` * |  string | Título do email | 80 |

## Response

STATUS 201

Response Body

```json
{
    "template_key": "17f49953-29a1-439c-a6be-db37a32e2746"
}
```

## Listando templates

## Request

ENDPOINT /notification/templates
MÉTODO GET

## Response

STATUS 200

Response Body

```json
{
  "data": [{
    "template_key": "b35ed5fc-fdda-4618-84e6-b49876dabf24",
    "template_type": "sms",
    "template_status": "480521cc-b0c9-4938-bd11-0000be11c66b",
    "template": "Seu código é [code]"
  }],
  "pagination": {
        "current_page": 1,
        "next_page": null,
        "rows_per_page": 1
    }
}
```

---

# Eventos

URL: /documentation/notificacoes/tipos_de_evento

Os Eventos disparam notificações, com a listagem de eventos você adiquire o conhecimento sobre quais tipos de notificação poderá receber e quais os meios de recebimento (webhook, e-mail e sms).

Os eventos posssuem os attributos allowed_sms, allowed_email e allowed_callback que indicam a possibilidade de envio de sms, e-mail ou callback respetivamente, além disso no caso de possibilidade de envio de email e sms podem conter o allowed_custom_vars que indicam as variáveis que podem ser substituidas no template utilizando o formato '[allowed_custom_var]' que será substituido pelo seu valor correspondente no envio.

## Consulta de eventos

## Request

ENDPOINT /notification/event_types
MÉTODO GET

### Query Params

| Campo       | Tipo   | Descrição                                    |
|-------------|--------|----------------------------------------------|
| `page`      | number | Página a ser recuperada, valor defaul 0      |
| `page_size` | number | Número de itens a ser recuperado, default 10 |

## Response

STATUS 200

Response Body: Lista de tipos de eventos

```json
{
    "data": [
        {
            "event_type": "incoming_ted",
            "allow_sms": false,
            "allow_email": true,
            "allow_callback": true,
            "allowed_custom_vars": ["total_amount", "target_account_number", "target_document_number"]
        },
        {
            "event_type": "outgoing_ted",
            "allow_sms": true,
            "allow_email": true,
            "allow_callback": false,
            "allowed_custom_vars": null
        }
    ],
    "pagination": {
        "current_page": 1,
        "next_page": 2,
        "rows_per_page": 2
    }
}

```

---

# Objeto Address

URL: /documentation/objetos_compartilhados/address

O objeto `address` é utilizado em diversas APIs para representar um endereço. A estrutura é padronizada em todos os endpoints.

## Estrutura

| Campo | Tipo | Obrigatório | Descrição |
|-|-|-|-|
| `street` | string | Sim | Logradouro. |
| `number` | string | Sim | Número do endereço. |
| `complement` | string | Não | Complemento. |
| `neighborhood` | string | Sim | Bairro. |
| `city` | string | Sim | Cidade. |
| `state` | string | Sim | UF (sigla de 2 caracteres). |
| `postal_code` | string | Sim | CEP (formato `XXXXXXXX`, sem hífen). |

## Exemplo

```json
{
  "street": "Rua Example",
  "number": "123",
  "complement": "Sala 1",
  "neighborhood": "Centro",
  "city": "São Paulo",
  "state": "SP",
  "postal_code": "01001000"
}
```

## Endpoints que utilizam este objeto

- [Abertura de conta PF (BaaS)](/documentation/baas/escrow/abrir_conta_pf)
- [Abertura de conta PJ (BaaS)](/documentation/baas/escrow/abrir_conta_pj)
- [Cadastro do investidor (IaaS)](/documentation/iaas/investidor/compartilhado/criar_investidor)
- [Emissão de dívida](/documentation/emissao_de_divida/simulacao_de_divida/simulacao_de_divida)

---

# Objeto Borrower

URL: /documentation/objetos_compartilhados/borrower

O objeto `borrower` representa o tomador de crédito em operações de dívida. É utilizado em diversos endpoints do Lending-as-a-Service.

## Estrutura — Pessoa Física (natural_person)

| Campo | Tipo | Obrigatório | Descrição |
|-|-|-|-|
| `person_type` | string | Sim | Tipo de pessoa. Valores: `natural` ou `legal`. |
| `name` | string | Sim | Nome completo do tomador. |
| `document_number` | string | Sim | CPF (11 dígitos, sem pontuação). |
| `mother_name` | string | Não | Nome da mãe. |
| `birth_date` | string | Não | Data de nascimento (formato `YYYY-MM-DD`). |
| `nationality` | string | Não | Nacionalidade. |
| `gender` | string | Não | Gênero. Valores: `male`, `female`. |
| `email` | string | Não | E-mail do tomador. |
| `phone` | object | Não | Objeto [phone](#phone). |
| `address` | object | Não | Objeto [address](/documentation/objetos_compartilhados/address). |

## Estrutura — Pessoa Jurídica (legal_person)

| Campo | Tipo | Obrigatório | Descrição |
|-|-|-|-|
| `person_type` | string | Sim | Valor: `legal`. |
| `company_name` | string | Sim | Razão social. |
| `trading_name` | string | Não | Nome fantasia. |
| `document_number` | string | Sim | CNPJ (14 dígitos, sem pontuação). |
| `foundation_date` | string | Não | Data de fundação (formato `YYYY-MM-DD`). |
| `email` | string | Não | E-mail corporativo. |
| `phone` | object | Não | Objeto [phone](#phone). |
| `address` | object | Não | Objeto [address](/documentation/objetos_compartilhados/address). |

## Phone

| Campo | Tipo | Obrigatório | Descrição |
|-|-|-|-|
| `country_code` | string | Sim | Código do país (ex: `"55"`). |
| `area_code` | string | Sim | DDD (ex: `"11"`). |
| `number` | string | Sim | Número do telefone. |

## Exemplo

```json
{
  "person_type": "natural",
  "name": "João da Silva",
  "document_number": "12345678901",
  "mother_name": "Maria da Silva",
  "birth_date": "1990-01-01",
  "phone": {
    "country_code": "55",
    "area_code": "11",
    "number": "999999999"
  },
  "address": {
    "street": "Rua Example",
    "number": "123",
    "neighborhood": "Centro",
    "city": "São Paulo",
    "state": "SP",
    "postal_code": "01001000"
  }
}
```

---

# Objeto Disbursement Account

URL: /documentation/objetos_compartilhados/disbursement_account

O objeto `disbursement_account` representa a conta bancária utilizada para desembolso de recursos em operações de crédito.

## Estrutura

| Campo | Tipo | Obrigatório | Descrição |
|-|-|-|-|
| `account_branch` | string | Sim | Agência bancária (sem dígito verificador). |
| `account_digit` | string | Sim | Dígito verificador da conta. |
| `account_number` | string | Sim | Número da conta (sem dígito). |
| `document_number` | string | Sim | CPF/CNPJ do titular da conta. |
| `financial_institution_code` | string | Sim | Código ISPB ou COMPE da instituição financeira. |
| `name` | string | Sim | Nome do titular da conta. |
| `account_type` | string | Sim | Tipo da conta. Valores: `checking_account`, `savings_account`, `payment_account`. |

## Exemplo

```json
{
  "account_branch": "0001",
  "account_digit": "2",
  "account_number": "12345",
  "document_number": "12345678901",
  "financial_institution_code": "329",
  "name": "João da Silva",
  "account_type": "checking_account"
}
```

## Endpoints que utilizam este objeto

- [Simulação de dívida](/documentation/emissao_de_divida/simulacao_de_divida/simulacao_de_divida)
- [Autorizar desembolso](/documentation/emissao_de_divida/autorizar_desembolso)
- [Consignado privado](/documentation/manual_consignado_privado/criacao_da_operacao)

---

# Objeto Financial Institution

URL: /documentation/objetos_compartilhados/financial_institution

O objeto `financial_institution` identifica uma instituição financeira participante de uma operação.

## Estrutura

| Campo | Tipo | Obrigatório | Descrição |
|-|-|-|-|
| `ispb_code` | string | Sim | Código ISPB (8 dígitos) da instituição financeira. |
| `compe_code` | string | Não | Código COMPE (3 dígitos) da instituição financeira. |
| `name` | string | Não | Nome da instituição financeira. |

## Exemplo

```json
{
  "ispb_code": "32402502",
  "compe_code": "329",
  "name": "QI Sociedade de Crédito Direto S.A."
}
```

## Referência

Para a lista completa de instituições financeiras e seus códigos, consulte a [Lista de Instituições Financeiras](/documentation/lista_de_instituicoes_financeiras).

---

# Manual Operacional de Boletos

URL: /documentation/operational_guide/boletos

## Tipos de cobrança

### Boletos bancários

São instrumentos de cobrança emitidos por uma instituição financeira a pedido de uma pessoa física ou jurídica que possua
uma conta bancária nesta instituição.

Esses instrumentos de cobrança são registrados pela instituição financeira na base centralizada de boletos do Brasil
([PCR - Nuclea](https://www.nuclea.com.br/plataforma-centralizada-de-recebiveis/)).

### Faturas de recolhimento e tributos

São instrumentos de cobrança utilizados para arrecadação/recebimento de tributos/taxas estaduais, municipais, federais e 
contas de concessionárias de serviços públicos como energia, água, telefonia e gás.

Cada convênio/órgão de arrecadação possuas suas próprias regras de horário/data de pagamento. Você pode conferir a lista de
convênios e horários através deste [link](https://storage.googleapis.com/live-doc-api/public_samples/active_covenants.xlsx).

:::caution Atenção!
A QI Tech só realiza o pagamento de faturas de recolhimento que possuem linha digitável ou código de barras.
:::

## Pagamento

Para realizar o pagamento de um boleto ou fatura de recolhimento, basta informar a conta de origem do pagamento, a linha digitável 
do boleto/fatura que será pago e a data em que o pagamento deve ser realizado.

Abaixo são listados os horários para pagamento de boletos bancários, faturas de recolhimento e tributos dentro da QI Tech.

| Valor do Boleto        | Horário        | Disponibilidade   |
|------------------------|----------------|-------------------|
| até R$ 249.999,99      | 06:00 às 22:00 | apenas dias úteis |
| acima de R$ 250.000,00 | 07:00 às 17:00 | apenas dias úteis |

:::caution Atenção!
Alguns tipos específicos de fatura de recolhimento e tributos, possuem horários diferentes da tabela acima, devido a 
particularidades relacionadas ao emissor/recebedor da cobrança. Para mais informações, confira nossa
tabela de horários para esses tipos de cobrança através deste [link](https://storage.googleapis.com/live-doc-api/public_samples/active_covenants.xlsx).
:::

### Limites de pagamento

O valor para pagamento de boletos bancários esta limitado ao saldo em conta do pagador.

### Liquidação financeira dos pagamentos

#### Boleto bancário

Quando um boleto bancário é pago em qualquer instituição financeira oferecedora desse meio de pagamento, o valor do boleto pago será recebido pelo
emissor da cobrança no próximo dia útil da data do pagamento (ex: um boleto pago na quinta-feira, será liquidado na sexta-feira. 
Um boleto pago em um sábado, será liquidado na segunda-feira).

Ou seja, caso um cliente da QI Tech tenha registrado um boleto em sua conta, ele só receberá o valor do boleto, um dia útil após seu pagamento (mesmo que esse pagamento
seja executado pela própria QI Tech).

#### Fatura de recolhimento e tributos

A liquidação de faturas do recolhimento e tributos, depende das regras e aspectos operacionais de cada órgão/agente que a emitiu.

---

# Criação de uma chave pix para um Alias

URL: /documentation/pix_indireto/chaves_pix/criacao_de_chaves

## Request

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_key
MÉTODO POST

**Request Body - Chave do tipo 'random_key'**

```json
{
  "request_control_key": "3d3d0083-ac71-46f0-8a90-c00a157a4893",
  "pix_key_type": "random_key"
}
```

**Request Body - Chave do tipo CPF**

```json
{
  "request_control_key": "3d3d0083-ac71-46f0-8a90-c00a157a4893",
  "pix_key_type": "cpf",
  "pix_key": "67824450007"
}
```

### Request Path Params

| Campo         | Tipo   | Descrição             | Caracteres |
|---------------|--------|-----------------------|------------|
| `account_key` | uuidv4 | Chave única da conta. | 36         |
| `alias_key`   | uuidv4 | Chave única do alias. | 36         |

### Request Body Params

| Campo                   | Tipo   | Descrição                                                                       | Max. Caracteres |
|-------------------------|--------|---------------------------------------------------------------------------------|-----------------|
| `request_control_key` * | string | UUID4 para fins de consulta sobre a requisição feita.                           | 36              |
| `pix_key_type` *        | string | Definição do tipo de chave que será criada. Valores possíveis: 'cpf', 'cnpj', 'email', 'phone_number', 'random_key'  | 10              |
| `pix_key`         | string | Valor da chave Pix a ser criado. Não deve ser enviado para casos de chave do tipo 'random_key'.  | 10              |

:::info Tipos de Chave Pix
A `pix_key` enviada na requisição pode ser um CPF, CNPJ, E-mail ou celular, seguindo as seguintes formatações:

**CPF**: Número inteiro com 11 dígitos.

**CNPJ**: Número inteiro com 14 dígitos.

**E-mail**: Texto contendo ao menos um “@”.

**Celular**: Texto contendo os seguintes valores: “+55” + “DDD do celular“ + “Número Inteiro do Celular com no mínimo 8
e no máximo 9 dígitos”. Ex: “+5511987654321“.

:::

## Response

STATUS 200

Response Body

```json

{
  "pix_key": "asra-4cd6-4c04-9651-1c0a2c30d7dd",
  "pix_key_status": "active",
  "created_at": "2021-12-06T21:16:11.001Z",
  "pix_key_type": "random_key"
}

```

### Response Body Params

| Campo                   | Tipo   | Descrição                                                                       | Max. Caracteres |
|-------------------------|--------|---------------------------------------------------------------------------------|-----------------|
| `pix_key`         | string | Valor da chave Pix criada. | 200              |
| `pix_key_status`         | string | Status de ativação da chave Pix. Pode ser "active","inactive" ou "pending" | 8              |
| `created_at`            | datetime Zulu | Data de criação da requisição. | 20 |

:::info Tipos de Chave Pix
A `pix_key` enviada na resposta da requisição pode ser um CPF, CNPJ, E-mail, celular ou chave aleatória, seguindo as seguintes formatações:

**CPF**: Número inteiro com 11 dígitos.

**CNPJ**: Número inteiro com 14 dígitos.

**E-mail**: Texto contendo ao menos um “@”.

**Celular**: Texto contendo os seguintes valores: “+55” + “DDD do celular“ + “Número Inteiro do Celular com no mínimo 8
e no máximo 9 dígitos”. Ex: “+5511987654321“.

**Chave aleatória**: UUIDV4.
:::

STATUS 4XX

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`    | Descrição (eng)<br/>`Description`                               | Descrição (ptbr)<br/>`translation`                           |
|-------------|----------------------|-----------------------|-----------------------------------------------------------------|--------------------------------------------------------------|
| 403         | PIX000080            | Not enough permission | The selected agent is not an Pix Indirect Participant           | O agente selecionado não é um Participante Indireto do Pix   |
| 404         | PIX000082            | Alias not found       | Alias \{alias_key\} not found                                     | Alias \{alias_key\} não encontrado                             |

---

# Deleção de chave Pix de um Alias

URL: /documentation/pix_indireto/chaves_pix/deletar_chaves

## Request

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_key/ PIX_KEY
MÉTODO DELETE

Request Body

```json

{}

```

### Path Params

| Campo         | Tipo   | Descrição                    | Caracteres |
|---------------|--------|------------------------------|------------|
| `account_key` | uuidv4 | Chave única da conta.        | 36         |
| `alias_key`   | uuidv4 | Chave única do alias.        | 36         |
| `pix_key`     | string | Chave PIX que será deletada. | 200        |

## Response

STATUS 200

Response Body

```json
{}
```

STATUS 4XX

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`    | Descrição (eng)<br/>`Description`                               | Descrição (ptbr)<br/>`translation`                           |
|-------------|----------------------|-----------------------|-----------------------------------------------------------------|--------------------------------------------------------------|
| 403         | PIX000080            | Not enough permission | The selected agent is not an Pix Indirect Participant           | O agente selecionado não é um Participante Indireto do Pix   |
| 404         | PIX000082            | Alias not found       | Alias \{alias_key\} not found                                     | Alias \{alias_key\} não encontrado                             |
| 400         | PIX000087            | Pix key type          | Only pix key type random_key is currently implemented for alias | Random_key é o único tipo atualmente implementado para alias |
| 404         | PIX000083            | Pix Key not found     | Pix Key \{pix_key\} not found for Alias \{alias_key\}               | Chave Pix \{pix_key\} não encontrada para o Alias \{alias_key\}  |

---

# Introdução a gestao de chaves PIX para um Alias

URL: /documentation/pix_indireto/chaves_pix/introducao_chaves_pix

Após o Participante Indireto ter realizado o cadastro de um Alias para sua conta aberta na QI Tech, este pode realizar o cadastro de uma chave PIX para este Alias o qual, na prática, representa o cliente do Participante Indireto.

Como o Participante Indireto já realizou o cadastro do Alias, basta indicar à  QI Tech, que se deseja abrir uma chave PIX para determinado Alias, o qual possui uma chave única que é fornecida quando o Participante Indireto registra um Alias.

:::info Informação

Tudo o descrito nesta seção de introdução também está, de forma detalhada como o Participante Indireto deve tratar via API, na seções seguintes.

:::

---

# Listagem de chaves Pix de um Alias

URL: /documentation/pix_indireto/chaves_pix/listar_chaves

## Request

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_key
MÉTODO GET

### Path Params

| Campo         | Tipo   | Descrição             | Caracteres |
|---------------|--------|-----------------------|------------|
| `account_key` | string | Chave única da conta. | 36         |
| `alias_key`   | string | Chave única do alias. | 36         |

:::info Tipos de Chave Pix
A “pix_key” é do tipo Chave Aleatória (UUID4), seguindo a seguinte formatação:

Chave Aleatória: UUID4.
:::

### Query Params

| Campo         | Tipo    | Descrição                               | Caracteres |
|---------------|---------|-----------------------------------------|------------|
| `page_number` | integer | Página atual que está sendo consultada. | -          |
| `page_size`   | integer | Quantidade de resultados por página.    | -          |

## Response

STATUS 200

Response Body: Chave Ativa

```json
{
  "data": [
    {
      "pix_key": "ecdb1790-667f-42ab-b319-fbc838a04672",
      "pix_key_type": "random_key",
      "pix_key_status": "active",
      "created_at": "2021-10-22T20:30:23.459Z"
    },
    {
      "pix_key": "f5eb52c1-5247-4de3-9982-f4f0ee9edad4",
      "pix_key_type": "random_key",
      "pix_key_status": "active",
      "created_at": "2021-12-06T21:16:12.123Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "rows_per_page": 10
  }
}
```

### Response Body Params

| Campo            | Tipo          | Descrição                                                                  | Max. Caracteres |
|------------------|---------------|----------------------------------------------------------------------------|-----------------|
| `pix_key`        | string        | Chave Pix.                                                                 | 77              |
| `pix_key_type`   | string        | Tipo da chave Pix. Pode ser "random_key"                                   | 10              |
| `pix_key_status` | string        | Status de ativação da chave Pix. Pode ser "active","inactive" ou "pending" | 8               |
| `created_at`     | datetime Zulu | Data de criação da requisição.                                             | 20              |

STATUS 4XX

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`       | Descrição (eng)<br/>`Description`                     | Descrição (ptbr)<br/>`translation`                             |
|-------------|----------------------|--------------------------|-------------------------------------------------------|----------------------------------------------------------------|
| 403         | PIX000080            | Not enough permission    | The selected agent is not an Pix Indirect Participant | O agente selecionado não é um Participante Indireto do Pix     |
| 404         | PIX000082            | Alias not found          | Alias \{alias_key\} not found                           | Alias \{alias_key\} não encontrado                               |
| 400         | PIX000088            | Page size too large      | Requested page size above limit of \{max_page_size\}    | Tamanho de página requerido acima do limite de \{max_page_size\} |
| 400         | PIX000089            | Invalid value for params | Page Size and Page Number must be integers            | age Size e Page Number devem ser números inteiros              |

---

# Cancelar Solicitação de Devolução

URL: /documentation/pix_indireto/devolucao/cancelar_devolucao

O Participante Indireto pode cancelar uma solicitação de devolução, caso seja necessário.

Apenas o Participante (Direto ou Indireto) o qual criou a solicitação de devolução pode cancelá-la.

Para o cancelamento, o status deve ser de OPEN

:::danger IMPORTANTE
O Banco Central do Brasil define que, dentro de um período de 1 dia do recebimento da Solicitação de Devolução pelo Participante Indireto, a Devolução precisa ser fechada .

Caso haja atraso por parte do Participante Indireto, a QI Tech irá fechar a Solicitação de Devolução, com o status de totally_accepted , a fim de que a instituição não seja penalizada pelo Banco Central do Brasil.
:::

## Request

ENDPOINT /pix/refund_request/ REFUND_REQUEST_KEY
MÉTODO PATCH

**Request Body**

```json
{
    "refund_request_status": "cancelled",
    "request_control_key": "e09aba97-0051-4c18-b645-1cb3c2581c34"
}

```

### Path Params
| Campo                  | Tipo   | Descrição                     | Caracteres |
| ---------------------- | ------ | ----------------------------- | ---------- |
| `refund_request_key` * | string | UUID4 da devolução já criada. | 36         |

### Body Params

| Campo                     | Tipo   | Descrição                                             | Caracteres |
| ------------------------- | ------ | ----------------------------------------------------- | ---------- |
| `refund_request_status` * | string | Status de atualização da devolução.                   | 36         |
| `request_control_key` *   | uuidv4 | UUID4 para fins de consulta sobre a requisição feita. | 36         |

## Response

STATUS 200

**Response Body**

```json
{
  "refund_request_key": "47633091-7d44-4d10-9d00-1f937104e537",
  "pix_transfer_key": "2bcbfd65-8660-4cb0-8ae4-4c4b327b32be",
  "end_to_end_id": "E73856642202407011350E8cnA3Ae7r3",
  "requested_amount": 10,
  "refund_request_status": "cancelled",
  "refund_request_type": "operational_flaw",
  "infraction_report_key": null,
  "refund_request_details": "Foi identificada uma fraude na transação.",
  "requesting_participant": "73856642",
  "contested_participant": "99999999",
  "analysis_result": null,
  "analysis_details": null,
  "reject_reason": null,
  "refund_transfer_key": null,
  "refunded_amount": 0.00,
  "refund_request_direction": "outgoing",
  "created_at": "2024-07-01T13:50:30Z"
}
```

### Body Params
| Campo                       | Tipo   | Descrição                                                                                 | Caracteres                                                                          |
| --------------------------- | ------ | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `pix_transfer_key`*         | string | Identificador único da transação PIX.                                                     | 36                                                                                  |
| `refund_request_key`*       | string | Identificador único da devolução.                                                         | 36                                                                                  |
| `infraction_report_key`*    | string | Identificador único da infração relacionada à devolução. Somente quando o tipo for FRAUDE | 36                                                                                  |
| `refund_request_type`       | enum   | Tipo de solicitação de devolução.                                                         | **[Enumeradores refund_request_type](#enumeradores-refund_request_type)**           |
| `requested_amount`*         | float  | Valor da devolução                                                                        | -                                                                                   |
| `refund_request_status`*    | enum   | Status .                                                                                  | **[Enumeradores refund_request_status](#enumeradores-refund_request_status)**       |
| `contested_participant`*    | string | ISPB do Participante Creditado (Contestado).                                              | 8                                                                                   |
| `requesting_participant`*   | string | ISPB do Participante Debitado (Requisitante, o qual está pedindo a devolução).            | 8                                                                                   |
| `refund_request_details`*   | string | Detalhes da devolução.                                                                    | -                                                                                   |
| `analysis_result`*          | enum   | Resultado da análise de fechamento da devolução.                                          | **[Enumeradores analysis_result](#enumeradores-analysis_result)**                   |
| `analysis_details`*         | string | Detalhes da análise de fechamento da devolução.                                           | -                                                                                   |
| `reject_reason`*            | string | Motivo da rejeição da devolução, caso seja fechada com REJECTED.                          | **[Enumeradores reject_reason](#enumeradores-reject_reason)**                       |
| `refund_transfer_key`*      | string | pix_transfer_key da transação de devolução, caso seja fechada com aceite.                 | -                                                                                   |
| `refunded_amount`*          | float  | Valor devolvido na transação de devolução.                                                | -                                                                                   |
| `refund_request_direction`* | string | Direção da solicitação de devolução.                                                      | **[Enumeradores refund_request_direction](#enumeradores-refund_request_direction)** |
| `created_at` *              | string | Data de criação da Solicitação de Devolução                                               | 24                                                                                  |

### Enumeradores refund_request_status
| Campo       | Descrição                                                                    |
| ----------- | ---------------------------------------------------------------------------- |
| `open`      | Solicitação de Devolução foi <strong>criada</strong> e está aberta no BACEN. |
| `cancelled` | Solicitação de Devolução está <strong>cancelada</strong> no BACEN            |
| `closed`    | Solicitação de Devolução está <strong>fechada</strong> no BACEN              |

### Enumeradores refund_request_type
| Campo              | Descrição                                              |
| ------------------ | ------------------------------------------------------ |
| `fraud`            | Solicitação de Devolução originada de uma fraude.      |
| `operational_flaw` | Solicitação de Devolução originada de um erro interno. |

### Enumeradores analysis_result
| Campo                | Descrição                                         |
| -------------------- | ------------------------------------------------- |
| `totally_accepted`   | Solicitação de Devolução foi totalmente aceita.   |
| `partially_accepted` | Solicitação de Devolução foi parcialmente aceita; |
| `rejected`           | Solicitação de Devolução foi rejeitada.           |

### Enumeradores reject_reason
| Campo             | Descrição                                                                  |
| ----------------- | -------------------------------------------------------------------------- |
| `no_balance`      | Conta não possui saldo para realizar a devolução.                          |
| `account_closure` | Conta se encontra fechada e, portanto, não é possível realizar a devolução |
| `other`           | Outro motivo                                                               |

### Enumeradores refund_request_direction
| Campo      | Descrição                                         |
| ---------- | ------------------------------------------------- |
| `outgoing` | Participante é originador do pedido de devolução. |
| `incoming` | Participante é o alvo do pedido de devolução      |

---

# Consultar Solicitação de Devolução

URL: /documentation/pix_indireto/devolucao/consultar_devolucao

Caso o Participante Indireto queira consultar as informações de uma Solicitação de Devolução, a rota abaixo o permite.

:::danger IMPORTANTE
O Banco Central do Brasil define que, dentro de um período de 1 dia do recebimento da Solicitação de Devolução pelo Participante Indireto, a Devolução precisa ser fechada .

Caso haja atraso por parte do Participante Indireto, a QI Tech irá fechar a Solicitação de Devolução, com o status de totally_accepted , a fim de que a instituição não seja penalizada pelo Banco Central do Brasil.
:::

## Request

ENDPOINT /pix/refund_request/ REFUND_REQUEST_KEY
MÉTODO GET

### Path Params
| Campo                | Tipo   | Descrição           | Caracteres |
| -------------------- | ------ | ------------------- | ---------- |
| `refund_request_key` | string | UUID4 da devolução. | 36         |

## Response

STATUS 200

**Response Body**

```json
{
  "refund_request_key": "47633091-7d44-4d10-9d00-1f937104e537",
  "pix_transfer_key": "2bcbfd65-8660-4cb0-8ae4-4c4b327b32be",
  "end_to_end_id": "E73856642202407011350E8cnA3Ae7r3",
  "requested_amount": 10,
  "refund_request_status": "closed",
  "refund_request_type": "operational_flaw",
  "infraction_report_key": null,
  "refund_request_details": "Foi identificada uma fraude na transação.",
  "requesting_participant": "73856642",
  "contested_participant": "99999999",
  "analysis_result": "rejected",
  "analysis_details": null,
  "reject_reason": "account_closure",
  "refund_transfer_key": null,
  "refunded_amount": 0.00,
  "refund_request_direction": "outgoing",
  "created_at": "2024-07-01T13:50:30Z",
  "refund_events": [
    {
      "event_type": "open",
      "event_details": "Solicitação de Devolução criada pelo participante indireto",
      "created_at": "2024-07-01T13:50:30Z"
    },
    {
      "event_type": "closed",
      "event_details": "Requisição de devolução fechado pela outra instituição financeira, com status REJEITADO",
      "created_at": "2024-07-01T14:02:55Z"
    }
  ]
}
```

### Body Params
| Campo                       | Tipo   | Descrição                                                                                 | Caracteres                                                                          |
| --------------------------- | ------ | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `pix_transfer_key`*         | string | Identificador único da transação PIX.                                                     | 36                                                                                  |
| `refund_request_key`*       | string | Identificador único da devolução.                                                         | 36                                                                                  |
| `infraction_report_key`*    | string | Identificador único da infração relacionada à devolução. Somente quando o tipo for FRAUDE | 36                                                                                  |
| `refund_request_type`       | enum   | Tipo de solicitação de devolução.                                                         | **[Enumeradores refund_request_type](#enumeradores-refund_request_type)**           |
| `requested_amount`*         | float  | Valor da devolução                                                                        | -                                                                                   |
| `refund_request_status`*    | enum   | Status .                                                                                  | **[Enumeradores refund_request_status](#enumeradores-refund_request_status)**       |
| `contested_participant`*    | string | ISPB do Participante Creditado (Contestado).                                              | 8                                                                                   |
| `requesting_participant`*   | string | ISPB do Participante Debitado (Requisitante, o qual está pedindo a devolução).            | 8                                                                                   |
| `refund_request_details`*   | string | Detalhes da devolução.                                                                    | -                                                                                   |
| `analysis_result`*          | enum   | Resultado da análise de fechamento da devolução.                                          | **[Enumeradores analysis_result](#enumeradores-analysis_result)**                   |
| `analysis_details`*         | string | Detalhes da análise de fechamento da devolução.                                           | -                                                                                   |
| `reject_reason`*            | string | Motivo da rejeição da devolução, caso seja fechada com REJECTED.                          | **[Enumeradores reject_reason](#enumeradores-reject_reason)**                       |
| `refund_transfer_key`*      | string | pix_transfer_key da transação de devolução, caso seja fechada com aceite.                 | -                                                                                   |
| `refunded_amount`*          | float  | Valor devolvido na transação de devolução.                                                | -                                                                                   |
| `refund_events`*            | object | Objeto eventos de pedido de devolução.                                                    | **[Objeto refund_events](#objetos-refund_events)**                                  |
| `refund_request_direction`* | string | Direção da solicitação de devolução.                                                      | **[Enumeradores refund_request_direction](#enumeradores-refund_request_direction)** |
| `created_at` *              | string | Data de criação da Solicitação de Devolução                                               | 24                                                                                  |

### Enumeradores refund_request_status
| Campo       | Descrição                                                                    |
| ----------- | ---------------------------------------------------------------------------- |
| `open`      | Solicitação de Devolução foi <strong>criada</strong> e está aberta no BACEN. |
| `cancelled` | Solicitação de Devolução está <strong>cancelada</strong> no BACEN            |
| `closed`    | Solicitação de Devolução está <strong>fechada</strong> no BACEN              |

### Enumeradores refund_request_type
| Campo              | Descrição                                              |
| ------------------ | ------------------------------------------------------ |
| `fraud`            | Solicitação de Devolução originada de uma fraude.      |
| `operational_flaw` | Solicitação de Devolução originada de um erro interno. |

### Enumeradores analysis_result
| Campo                | Descrição                                         |
| -------------------- | ------------------------------------------------- |
| `totally_accepted`   | Solicitação de Devolução foi totalmente aceita.   |
| `partially_accepted` | Solicitação de Devolução foi parcialmente aceita; |
| `rejected`           | Solicitação de Devolução foi rejeitada.           |

### Enumeradores reject_reason
| Campo             | Descrição                                                                  |
| ----------------- | -------------------------------------------------------------------------- |
| `no_balance`      | Conta não possui saldo para realizar a devolução.                          |
| `account_closure` | Conta se encontra fechada e, portanto, não é possível realizar a devolução |
| `other`           | Outro motivo                                                               |

### Enumeradores refund_request_direction
| Campo      | Descrição                                         |
| ---------- | ------------------------------------------------- |
| `outgoing` | Participante é originador do pedido de devolução. |
| `incoming` | Participante é o alvo do pedido de devolução      |

### Objetos refund_events
| Campo           | Descrição                                                                                                             |
| --------------- | --------------------------------------------------------------------------------------------------------------------- |
| `event_type`    | Tipo do evento de mudança da devolução. **[Enumeradores refund_request_status](#enumeradores-refund_request_status)** |
| `event_details` | Detalhes acerca do evento.                                                                                            |
| `created_at`    | Data de criação do evento.                                                                                            |

---

# Abrir Solicitação de Devolução

URL: /documentation/pix_indireto/devolucao/criar_devolucao

A Solicitação de Devolução é mais uma funcionalidade presente no MED, definido pelo BACEN.

O principal objetivo é facilitar a devolução de uma transação PIX feita. Tem-se que a Solicitação de Devolução pode ser gerada tanto por uma falha operacional quanto por uma infração . Neste último caso, há um Relato de Infração, para uma transação PIX, já fechado e aceito .

:::caution **Atenção**
A fim de se compreender o fluxo de Solicitação de Devolução, é necessário saber quais ENDPOINTS o Participante Indireto que criou a devolução pode utilizar.

Quando o Participante Indireto cria uma Solicitação de Devolução, este pode (se necessário) cancelar a solicitação caso tenha sido gerado de maneira indevida.

Quando o Participante Indireto recebe uma Solicitação de Devolução, esta deve respondê-lo informando o resultado da análise da solicitação.

Ambos os fluxos citados serão descritos nas seções seguintes.

Ressalta-se também que se o Participante Indireto abrir a Solicitação, então ele contesta outro Participante. No fluxo contrário, o Participante Indireto é o contestado .
:::

:::danger IMPORTANTE
O Banco Central do Brasil define que, dentro de um período de 1 dia do recebimento da Solicitação de Devolução pelo Participante Indireto, a Devolução precisa ser fechada .

Caso haja atraso por parte do Participante Indireto, a QI Tech irá fechar a Solicitação de Devolução, com o status de totally_accepted , a fim de que a instituição não seja penalizada pelo Banco Central do Brasil.
:::

## Request

ENDPOINT /pix/refund_request
MÉTODO POST

**Request Body**

```json
{
    "pix_transfer_key": "a39mn71j-1dc7-4df0-8472-233624706e08",
    "request_control_key":"df3ae07e-1dc7-4df0-8472-233624706e08",
    "amount": 200.00,
    "refund_request_details": "transação fraudada",
    "refund_request_type": "fraud"
}

```

### Body Params

| Campo                    | Tipo   | Descrição                                                                                  | Caracteres                                                                |
| ------------------------ | ------ | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| `pix_transfer_key` *     | string | Identificador único da transação PIX.                                                      | 36                                                                        |
| `request_control_key` *  | uuidv4 | UUID4 para fins de consulta sobre a requisição feita.                                      | 36                                                                        |
| `amount`                 | float  | Valor da devolução. Caso não seja fornecido, será utilizado o valor da transação original. | 19                                                                        |
| `refund_request_details` | string | Detalhes acerca da solicitação de devolução a ser criada                                   | \<\= 2000                                                                 |
| `refund_request_type` *  | enum   | Pode ser (fraud/operational_flaw)                                                          | **[Enumeradores refund_request_type](#enumeradores-refund_request_type)** |

## Response

STATUS
        200

**Response Body**

```json
{
  "refund_request_key": "47633091-7d44-4d10-9d00-1f937104e537",
  "pix_transfer_key": "2bcbfd65-8660-4cb0-8ae4-4c4b327b32be",
  "end_to_end_id": "E73856642202407011350E8cnA3Ae7r3",
  "requested_amount": 200.00,
  "refund_request_status": "open",
  "refund_request_type": "operational_flaw",
  "infraction_report_key": null,
  "refund_request_details": "Foi identificada uma fraude na transação.",
  "requesting_participant": "73856642",
  "contested_participant": "99999999",
  "analysis_result": null,
  "analysis_details": null,
  "reject_reason": null,
  "refund_transfer_key": null,
  "refunded_amount": 0.00,
  "refund_request_direction": "outgoing",
  "created_at": "2024-07-01T13:50:30Z"
}
```

:::info Informação
Caso o campo "refund_request_type" seja de "fraud", a QI Tech informará, na resposta, a infraction_report_key que já foi fechada e aceita.
:::

### Body Params
| Campo                       | Tipo   | Descrição                                                                                 | Caracteres                                                                          |
| --------------------------- | ------ | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `pix_transfer_key`*         | string | Identificador único da transação PIX.                                                     | 36                                                                                  |
| `refund_request_key`*       | string | Identificador único da devolução.                                                         | 36                                                                                  |
| `infraction_report_key`*    | string | Identificador único da infração relacionada à devolução. Somente quando o tipo for FRAUDE | 36                                                                                  |
| `refund_request_type`       | enum   | Tipo de solicitação de devolução.                                                         | **[Enumeradores refund_request_type](#enumeradores-refund_request_type)**           |
| `requested_amount`*         | float  | Valor da devolução                                                                        | -                                                                                   |
| `refund_request_status`*    | enum   | Status .                                                                                  | **[Enumeradores refund_request_status](#enumeradores-refund_request_status)**       |
| `contested_participant`*    | string | ISPB do Participante Creditado (Contestado).                                              | 8                                                                                   |
| `requesting_participant`*   | string | ISPB do Participante Debitado (Requisitante, o qual está pedindo a devolução).            | 8                                                                                   |
| `refund_request_details`*   | string | Detalhes da devolução.                                                                    | -                                                                                   |
| `analysis_result`*          | enum   | Resultado da análise de fechamento da devolução.                                          | **[Enumeradores analysis_result](#enumeradores-analysis_result)**                   |
| `analysis_details`*         | string | Detalhes da análise de fechamento da devolução.                                           | -                                                                                   |
| `reject_reason`*            | string | Motivo da rejeição da devolução, caso seja fechada com REJECTED.                          | **[Enumeradores reject_reason](#enumeradores-reject_reason)**                       |
| `refund_transfer_key`*      | string | pix_transfer_key da transação de devolução, caso seja fechada com aceite.                 | -                                                                                   |
| `refunded_amount`*          | float  | Valor devolvido na transação de devolução.                                                | -                                                                                   |
| `refund_request_direction`* | string | Direção da solicitação de devolução.                                                      | **[Enumeradores refund_request_direction](#enumeradores-refund_request_direction)** |
| `created_at` *              | string | Data de criação da Solicitação de Devolução                                               | 24                                                                                  |

### Enumeradores refund_request_status
| Campo       | Descrição                                                                    |
| ----------- | ---------------------------------------------------------------------------- |
| `open`      | Solicitação de Devolução foi <strong>criada</strong> e está aberta no BACEN. |
| `cancelled` | Solicitação de Devolução está <strong>cancelada</strong> no BACEN            |
| `closed`    | Solicitação de Devolução está <strong>fechada</strong> no BACEN              |

### Enumeradores refund_request_type
| Campo              | Descrição                                              |
| ------------------ | ------------------------------------------------------ |
| `fraud`            | Solicitação de Devolução originada de uma fraude.      |
| `operational_flaw` | Solicitação de Devolução originada de um erro interno. |

### Enumeradores analysis_result
| Campo                | Descrição                                         |
| -------------------- | ------------------------------------------------- |
| `totally_accepted`   | Solicitação de Devolução foi totalmente aceita.   |
| `partially_accepted` | Solicitação de Devolução foi parcialmente aceita; |
| `rejected`           | Solicitação de Devolução foi rejeitada.           |

### Enumeradores reject_reason
| Campo             | Descrição                                                                  |
| ----------------- | -------------------------------------------------------------------------- |
| `no_balance`      | Conta não possui saldo para realizar a devolução.                          |
| `account_closure` | Conta se encontra fechada e, portanto, não é possível realizar a devolução |
| `other`           | Outro motivo                                                               |

### Enumeradores refund_request_direction
| Campo      | Descrição                                         |
| ---------- | ------------------------------------------------- |
| `outgoing` | Participante é originador do pedido de devolução. |
| `incoming` | Participante é o alvo do pedido de devolução      |

---

# Fechar Solicitação de Devolução

URL: /documentation/pix_indireto/devolucao/fechar_devolucao

O Participante Indireto pode fechar uma solicitação de devolução, se este (Participante) estiver como Participante Contestado.

Para o fechamento, o status deve ser de OPEN .

:::danger IMPORTANTE
O Banco Central do Brasil define que, dentro de um período de 1 dia do recebimento da Solicitação de Devolução pelo Participante Indireto, a Devolução precisa ser fechada .

Caso haja atraso por parte do Participante Indireto, a QI Tech irá fechar a Solicitação de Devolução, com o status de totally_accepted , a fim de que a instituição não seja penalizada pelo Banco Central do Brasil.
:::

## Request

ENDPOINT /pix/refund_request/ REFUND_REQUEST_KEY
MÉTODO PATCH

**Request Body**

```json
{
    "request_control_key":"xpjae07e-1dc7-4df0-8472-233624706e08",
    "refund_request_status": "closed",
    "analysis_result": "totally_accepted",
    "analysis_details": "Valor bloqueado. Para mais informações, contatar central antifraude em 11 3000-45012, informando ID 0000.",
    "refund_transfer_key": "cdcf0d25-08a1-46e3-902a-6d7ca75e6c48"
}

```

### Path Params
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `refund_request_key` *| string | UUID4 da devolução já criada.| 36 |

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `request_control_key` * | uuidv4 | UUID4 para fins de consulta sobre a requisição feita. | 36 |
| `request_request_status` * | enum | status | **[Enumeradores refund_request_status](#enumeradores-refund_request_status)**  |
| `analysis_result` * | enum | Resultado da análise | **[Enumeradores analysis_result](#enumeradores-analysis_result)**  |
| `analysis_details` | string | Comentário sobre a análise | \<\= 2000 |
| `refund_transfer_key`  | string | UUID4 da transação de devolução enviada pela rota de "reversal". Deve ser utilizado quando o "analysis_result" é de aceite.| 36 |
| `reject_reason`  | enum | Razão da rejeição da devolução. Deve ser utilizado quando o campo 'analysis_result' é 'rejected'. | **[Enumeradores reject_reason](#enumeradores-reject_reason)**  |

## Response

STATUS 200

**Response Body - Recusa**

```json
{
  "refund_request_key": "2e42116f-4bdb-4f07-931f-c4dc7a78ed99",
  "pix_transfer_key": "d5856a5f-378f-43ed-818b-df33b9fae703",
  "end_to_end_id": "E60701190202406281828JCBxFsqssCf",
  "requested_amount": 10,
  "refund_request_status": "closed",
  "refund_request_type": "operational_flaw",
  "infraction_report_key": null,
  "refund_request_details": "Foi identificada uma fraude na transação.",
  "requesting_participant": "99999999",
  "contested_participant": "73856642",
  "analysis_result": "rejected",
  "analysis_details": "Conta sem saldo.",
  "reject_reason": "no_balance",
  "refund_transfer_key": null,
  "refunded_amount": 0.00,
  "refund_request_direction": "incoming",
  "created_at": "2024-07-01T15:46:18Z"
}
```

**Response Body - Aceite**

```json
{
  "refund_request_key": "2e42116f-4bdb-4f07-931f-c4dc7a78ed99",
  "pix_transfer_key": "d5856a5f-378f-43ed-818b-df33b9fae703",
  "end_to_end_id": "E60701190202406281828JCBxFsqssCf",
  "requested_amount": 10,
  "refund_request_status": "closed",
  "refund_request_type": "operational_flaw",
  "infraction_report_key": null,
  "refund_request_details": "Foi identificada uma fraude na transação.",
  "requesting_participant": "99999999",
  "contested_participant": "73856642",
  "analysis_result": "totally_accepted",
  "analysis_details": "Valor devolvido.",
  "reject_reason": null,
  "refund_transfer_key": "ab1189d8-5a87-4e5b-b49c-d05776bd8efe",
  "refunded_amount": 10.00,
  "refund_request_direction": "incoming",
  "created_at": "2024-07-01T15:46:18Z"
}
```

### Body Params
| Campo                       | Tipo   | Descrição                                                                                 | Caracteres                                                                          |
| --------------------------- | ------ | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `pix_transfer_key`*         | string | Identificador único da transação PIX.                                                     | 36                                                                                  |
| `refund_request_key`*       | string | Identificador único da devolução.                                                         | 36                                                                                  |
| `infraction_report_key`*    | string | Identificador único da infração relacionada à devolução. Somente quando o tipo for FRAUDE | 36                                                                                  |
| `refund_request_type`       | enum   | Tipo de solicitação de devolução.                                                         | **[Enumeradores refund_request_type](#enumeradores-refund_request_type)**           |
| `requested_amount`*         | float  | Valor da devolução                                                                        | -                                                                                   |
| `refund_request_status`*    | enum   | Status .                                                                                  | **[Enumeradores refund_request_status](#enumeradores-refund_request_status)**       |
| `contested_participant`*    | string | ISPB do Participante Creditado (Contestado).                                              | 8                                                                                   |
| `requesting_participant`*   | string | ISPB do Participante Debitado (Requisitante, o qual está pedindo a devolução).            | 8                                                                                   |
| `refund_request_details`*   | string | Detalhes da devolução.                                                                    | -                                                                                   |
| `analysis_result`*          | enum   | Resultado da análise de fechamento da devolução.                                          | **[Enumeradores analysis_result](#enumeradores-analysis_result)**                   |
| `analysis_details`*         | string | Detalhes da análise de fechamento da devolução.                                           | -                                                                                   |
| `reject_reason`*            | string | Motivo da rejeição da devolução, caso seja fechada com REJECTED.                          | **[Enumeradores reject_reason](#enumeradores-reject_reason)**                       |
| `refund_transfer_key`*      | string | pix_transfer_key da transação de devolução, caso seja fechada com aceite.                 | -                                                                                   |
| `refunded_amount`*          | float  | Valor devolvido na transação de devolução.                                                | -                                                                                   |
| `refund_request_direction`* | string | Direção da solicitação de devolução.                                                      | **[Enumeradores refund_request_direction](#enumeradores-refund_request_direction)** |
| `created_at` *              | string | Data de criação da Solicitação de Devolução                                               | 24                                                                                  |

### Enumeradores refund_request_status
| Campo       | Descrição                                                                    |
| ----------- | ---------------------------------------------------------------------------- |
| `open`      | Solicitação de Devolução foi <strong>criada</strong> e está aberta no BACEN. |
| `cancelled` | Solicitação de Devolução está <strong>cancelada</strong> no BACEN            |
| `closed`    | Solicitação de Devolução está <strong>fechada</strong> no BACEN              |

### Enumeradores refund_request_type
| Campo              | Descrição                                              |
| ------------------ | ------------------------------------------------------ |
| `fraud`            | Solicitação de Devolução originada de uma fraude.      |
| `operational_flaw` | Solicitação de Devolução originada de um erro interno. |

### Enumeradores analysis_result
| Campo                | Descrição                                         |
| -------------------- | ------------------------------------------------- |
| `totally_accepted`   | Solicitação de Devolução foi totalmente aceita.   |
| `partially_accepted` | Solicitação de Devolução foi parcialmente aceita; |
| `rejected`           | Solicitação de Devolução foi rejeitada.           |

### Enumeradores reject_reason
| Campo             | Descrição                                                                  |
| ----------------- | -------------------------------------------------------------------------- |
| `no_balance`      | Conta não possui saldo para realizar a devolução.                          |
| `account_closure` | Conta se encontra fechada e, portanto, não é possível realizar a devolução |
| `other`           | Outro motivo                                                               |

### Enumeradores refund_request_direction
| Campo      | Descrição                                         |
| ---------- | ------------------------------------------------- |
| `outgoing` | Participante é originador do pedido de devolução. |
| `incoming` | Participante é o alvo do pedido de devolução      |

---

# Listar Solicitações de Devolução

URL: /documentation/pix_indireto/devolucao/listar_solicitacoes

Caso o Participante Indireto solicite a listagem de Solicitações de Devolução, pode fazê-lo por meio da rota abaixo.

:::danger IMPORTANTE
O Banco Central do Brasil define que, dentro de um período de 1 dia do recebimento da Solicitação de Devolução pelo Participante Indireto, a Devolução precisa ser fechada .

Caso haja atraso por parte do Participante Indireto, a QI Tech irá fechar a Solicitação de Devolução, com o status de totally_accepted , a fim de que a instituição não seja penalizada pelo Banco Central do Brasil.
:::

## Request

ENDPOINT /pix/refund_requests
MÉTODO GET

### Query Params
| Campo                   | Tipo    | Descrição                               | Caracteres                                                                    |
| ----------------------- | ------- | --------------------------------------- | ----------------------------------------------------------------------------- |
| `refund_request_status` | enum    | Status do Relato de Infração.           | **[Enumeradores refund_request_status](#enumeradores-refund_request_status)** |
| `refund_request_type`   | enum    | Tipo do Relato de Infração.             | **[Enumeradores refund_request_type](#enumeradores-refund_request_type)**     |
| `initial_date`          | string  | Data inicial de busca.                  | **[Formato de data](#formato-de-data)**                                       |
| `final_date`            | string  | Data final de busca.                    | **[Formato de data](#formato-de-data)**                                       |
| `page_number`           | integer | Página atual que está sendo consultada. | -                                                                             |
| `page_size`             | integer | Quantidade de resultados por página.    | -                                                                             |

### Enumeradores refund_request_status
| Campo       | Tipo   | Descrição                                                                    | Caracteres |
| ----------- | ------ | ---------------------------------------------------------------------------- | ---------- |
| `open`      | string | Solicitação de Devolução foi <strong>criada</strong> e está aberto no BACEN. | 4          |
| `cancelled` | string | Solicitação de Devolução está <strong>cancelada</strong> no BACEN.           | 9          |
| `closed`    | string | Solicitação de Devolução está <strong>fechada</strong> no BACEN.             | 6          |

### Enumeradores refund_request_type
| Campo              | Tipo   | Descrição                                              | Caracteres |
| ------------------ | ------ | ------------------------------------------------------ | ---------- |
| `fraud`            | string | Solicitação de Devolução originada de uma fraude.      | 5          |
| `operational_flaw` | string | Solicitação de Devolução originada de um erro interno. | 16         |

### Formato de data

| Campo          | Tipo   | Descrição                                                                   | Caracteres |
| -------------- | ------ | --------------------------------------------------------------------------- | ---------- |
| `initial_date` | string | Data de inicio para a procura, em formato "%Y-%m-%d. Exemplo: "2023-10-09". | 10         |
| `final_date`   | string | Data final para a procura, em formato "%Y-%m-%d. Exemplo: "2023-10-11".     | 10         |

## Response

STATUS 200

**Response Body**

```json
{
  "data": [
    {
      "refund_request_key": "817c9331-fe1d-4178-aff2-8bed87ce3099",
      "pix_transfer_key": "029efb4e-ad3b-4ba5-a73c-c724f0d9c02b",
      "end_to_end_id": "E73856642202406282112pEBgwN7kkqD",
      "requested_amount": 10,
      "refund_request_status": "cancelled",
      "refund_request_type": "operational_flaw",
      "infraction_report_key": null,
      "refund_request_details": "Foi identificada uma fraude na transação.",
      "requesting_participant": "73856642",
      "contested_participant": "99999999",
      "analysis_result": null,
      "analysis_details": null,
      "reject_reason": null,
      "refund_transfer_key": null,
      "refunded_amount": 0.00,
      "refund_request_direction": "outgoing",
      "created_at": "2024-06-28T21:25:20Z",
      "refund_events": [
        {
          "event_type": "open",
          "event_details": "Solicitação de Devolução criada pelo participante indireto",
          "created_at": "2024-06-28T21:25:20Z"
        },
        {
          "event_type": "cancelled",
          "event_details": "Solicitação de Devolução cancelada pelo participante indireto",
          "created_at": "2024-06-28T21:27:19Z"
        }
      ]
    },
    {
      "refund_request_key": "5d174097-3d5c-41a2-a548-b24c41eecfb4",
      "pix_transfer_key": "d5856a5f-378f-43ed-818b-df33b9fae703",
      "end_to_end_id": "E60701190202406281828JCBxFsqssCf",
      "requested_amount": 10,
      "refund_request_status": "closed",
      "refund_request_type": "operational_flaw",
      "infraction_report_key": null,
      "refund_request_details": "Foi identificada uma fraude na transação.",
      "requesting_participant": "99999999",
      "contested_participant": "73856642",
      "analysis_result": "rejected",
      "analysis_details": null,
      "reject_reason": "no_balance",
      "refund_transfer_key": null,
      "refunded_amount": 0.00,
      "refund_request_direction": "incoming",
      "created_at": "2024-07-01T12:47:41Z",
      "refund_events": [
        {
          "event_type": "open",
          "event_details": "Solicitação de Devolução criada por outra instituição financeira",
          "created_at": "2024-07-01T12:47:41Z"
        }
      ]
    }
  ]
}
```

### Body Params
| Campo                       | Tipo   | Descrição                                                                                 | Caracteres                                                                         |
| --------------------------- | ------ | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `pix_transfer_key`*         | string | Identificador único da transação PIX.                                                     | 36                                                                                 |
| `refund_request_key`*       | string | Identificador único da devolução.                                                         | 36                                                                                 |
| `infraction_report_key`*    | string | Identificador único da infração relacionada à devolução. Somente quando o tipo for FRAUDE | 36                                                                                 |
| `refund_request_type`       | enum   | Tipo de solicitação de devolução.                                                         | **[Enumeradores refund_request_type](#enumeradores-refund_request_type)**           |
| `requested_amount`*         | float  | Valor da devolução                                                                        | -                                                                                  |
| `refund_request_status`*    | enum   | Status .                                                                                  | **[Enumeradores refund_request_status](#enumeradores-refund_request_status)**       |
| `contested_participant`*    | string | ISPB do Participante Creditado (Contestado).                                              | 8                                                                                  |
| `requesting_participant`*   | string | ISPB do Participante Debitado (Requisitante, o qual está pedindo a devolução).            | 8                                                                                  |
| `refund_request_details`*   | string | Detalhes da devolução.                                                                    | -                                                                                  |
| `analysis_result`*          | enum   | Resultado da análise de fechamento da devolução.                                          | **[Enumeradores analysis_result](#enumeradores-analysis_result)**                   |
| `analysis_details`*         | string | Detalhes da análise de fechamento da devolução.                                           | -                                                                                  |
| `reject_reason`*            | string | Motivo da rejeição da devolução, caso seja fechada com REJECTED.                          | **[Enumeradores reject_reason](#enumeradores-reject_reason)**                       |
| `refund_transfer_key`*      | string | pix_transfer_key da transação de devolução, caso seja fechada com aceite.                 | -                                                                                  |
| `refunded_amount`*          | float  | Valor devolvido na transação de devolução.                                                | -                                                                                  |
| `refund_events`*            | object | Objeto eventos de pedido de devolução.                                                    | **[Objeto refund_events](#objetos-refund_events)**                                 |
| `refund_request_direction`* | string | Direção da solicitação de devolução.                                                      | **[Enumeradores refund_request_direction](#enumeradores-refund_request_direction)** |
| `created_at` *              | string | Data de criação da Solicitação de Devolução                                               | 24                                                                                 |

### Enumeradores refund_request_status
| Campo       | Descrição                                                                    |
| ----------- | ---------------------------------------------------------------------------- |
| `open`      | Solicitação de Devolução foi <strong>criada</strong> e está aberta no BACEN. |
| `cancelled` | Solicitação de Devolução está <strong>cancelada</strong> no BACEN            |
| `closed`    | Solicitação de Devolução está <strong>fechada</strong> no BACEN              |

### Enumeradores refund_request_type
| Campo              | Descrição                                              |
| ------------------ | ------------------------------------------------------ |
| `fraud`            | Solicitação de Devolução originada de uma fraude.      |
| `operational_flaw` | Solicitação de Devolução originada de um erro interno. |

### Enumeradores analysis_result
| Campo                | Descrição                                         |
| -------------------- | ------------------------------------------------- |
| `totally_accepted`   | Solicitação de Devolução foi totalmente aceita.   |
| `partially_accepted` | Solicitação de Devolução foi parcialmente aceita; |
| `rejected`           | Solicitação de Devolução foi rejeitada.           |

### Enumeradores reject_reason
| Campo             | Descrição                                                                  |
| ----------------- | -------------------------------------------------------------------------- |
| `no_balance`      | Conta não possui saldo para realizar a devolução.                          |
| `account_closure` | Conta se encontra fechada e, portanto, não é possível realizar a devolução |
| `other`           | Outro motivo                                                               |

### Enumeradores refund_request_direction
| Campo      | Descrição                                         |
| ---------- | ------------------------------------------------- |
| `outgoing` | Participante é originador do pedido de devolução. |
| `incoming` | Participante é o alvo do pedido de devolução      |

### Objetos refund_events
| Campo           | Descrição                                                                                                             |
| --------------- | --------------------------------------------------------------------------------------------------------------------- |
| `event_type`    | Tipo do evento de mudança da devolução. **[Enumeradores refund_request_status](#enumeradores-refund_request_status)** |
| `event_details` | Detalhes acerca do evento.                                                                                            |
| `created_at`    | Data de criação do evento.                                                                                            |

---

# Introdução ao fluxo de Devolução

URL: /documentation/pix_indireto/devolucao/maquina_estados

## Introdução

O Banco Central do Brasil permite que, caso o Participante Indireto queira solicitar de volta para a conta um valor debitado em uma transação feita via PIX, este pode abrir uma Solicitação de Devolução.

:::info 

Ressalta-se que apenas o Participante debitado pode abrir uma Solicitação de Devolução. Formalmente, o Participante o qual abre uma Solicitação de Devolução é chamado de requesting_participant .

:::

| Enumerador | Tradução | Descrição|
|---|---|---|
|  open  | aberto | Após o processamento da <strong>criação</strong> da Solicitação de Devolução, o mesmo fica aberto no BACEN.  
|  cancelled  | cancelado | O cancelamento da Solicitação de Devolução foi processado pela QI Tech e está <strong>cancelado</strong> no BACEN.
|  closed  | fechado | O fechamento da Solicitação de Devolução foi processado pela QI Tech e está <strong>fechado</strong> no BACEN.

## Controle da Máquina de Estados

Mesmo o fluxo sendo síncrono , é necesário que se conheça os possíveis status os quais uma Solicitação de Devolução pode ter. Abaixo, está descrito o que o Participante Indireto pode esperar após abrir, cancelar, completar e receber uma Solicitação de Devolução.

### Participante Abre Solicitação de Devolução

O Participante Indireto pode solicitar a abertura de devolução de duas maneiras:

Por erro operacional (operational_flaw).
Por um relato de infração já fechado e aceito (refund_request)

Após a abertura, o status da devolução será de open

### Participante Cancela Solicitação de Devolução

Após o Participante ter aberto uma Solicitação de Devolução, é possível realizar o cancelamento desta, caso seja solicitado.

O Participante Indireto receberá uma resposta com o status de cancelled .

### Participante Recebe Solicitação de Devolução

Visto que outros Participantes podem abrir uma Solicitação de Devolução, é necessário que a outra ponta envolvida no fluxo possa saber recebê-lo, a fim de fechá-lo .

Diferentemente do Relato de Infração, o qual há um status intermediário de acknowledged , o Participante Indireto receberá, via webhook , uma requisição informando que há uma Solicitação de Devolução com o status open .

A diferença é de que, para esta requisição, o Participante Contestado é o Participante Indireto.

### Participante Fecha Solicitação de Devolução

Após a QI Tech, via webhook , informar o Participante Indireto de que há uma Solicitação de Devolução disponível, este pode fechar o relato.

Quando o Participante Indireto realizar este fluxo, enviará a requisição de fechamento para a QI Tech e receberá um status de closed

---

# Simulação de Cenários

URL: /documentation/pix_indireto/devolucao/simulacao_de_cenarios

Passo a passo para simular a efetivação de ações feitas por agentes externos. Essas simulações incluem recebimentos e atualizações de solicitações de devolução.

:::info Informação
Não há payload de retorno (response body) nessas requisições, somente response status de 201.
:::

## 1 - Simulação de recebimento de solicitação de devolução

Simula o recebimento de uma solicitação de devolução aberta por outra instituição.

:::info IMPORTANTE
É essencial possuir uma pix_transfer_key válida para mandar a request, não importando necessariamente as informações da outra parte da transferencia, visto que todas as informações do segundo participante serão substituidas no processo de mock.
:::

### Request

ENDPOINT /mock/pix/refund_request
MÉTODO POST

Request Body

:::info IMPORTANTE
Caso o tipo de devolução seja de FRAUD, é necessário haver um relato de infração fechado para a mesma pix_transfer_key.
:::

```json
{
    "pix_transfer_key": "d5856a5f-378f-43ed-818b-df33b9fae703",
    "refund_request_type": "fraud",
    "refund_request_details": "Foi identificada uma fraude na transação.",
    "refund_request_status": "open",
}
```

### Objeto Request Body

| Campo                      | Tipo   | Descrição                                                          | Máx. Caract.                                                              |
| -------------------------- | ------ | ------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| `pix_transfer_key` *      | string | Chave de identificação da transferência Pix no sistema QI (UUIDv4) | 36                                                                        |
| `refund_request_type` *   | enum   | Tipo de solicitação de devolução.                                  | **[Enumeradores refund_request_type](#enumeradores-refund_request_type)** |
| `refund_request_status` * | string | Status inicial da solicitação de devolução. "open"                 | 36                                                                        |
| `refund_request_details`  | string | Detalhes do relato da solicitação de devolução                     | 2000                                                                      |

### Enumeradores refund_request_type
| Campo              | Tipo   | Descrição                                              | Caracteres |
| ------------------ | ------ | ------------------------------------------------------ | ---------- |
| `fraud`            | string | Solicitação de Devolução originada de uma fraude.      | 5          |
| `operational_flaw` | string | Solicitação de Devolução originada de um erro interno. | 16         |

## 2 - Simulação de atualização de uma solicitação de devolução

Simula a atualização de status de uma solicitação de devolução aberta pelo participante indireto.

As opções de simulação para atualização de uma solicitação de devolução são:

1 - Cancelamento: Simula o cancelamento (cancel), feito por um participante "alvo", sobre uma solicitação de devolução aberta por ele mesmo previamente.

2 - Fechamento: Simula o fechamento (close), feito por um participante "alvo", sobre uma solicitação de devolução aberta pelo participante indireto. É importante que esse relato ja tenha sido reconhecido aberto.

### Request

ENDPOINT /mock/pix/refund_request
MÉTODO PATCH

Request Body - Cancelamento

:::info IMPORTANTE
A Solicitação de devolução identificada pela refund_request_key ja deve ter sido previamente criada na simulação de criação de solicitação de devolução.
:::

```json
{
    "refund_request_status": "cancelled",
    "refund_request_key": "c3e5664f-04bb-4625-9ef3-c8555d210c71"
}
```

Request Body - Fechamento com Aceite Total

:::info IMPORTANTE
A Solicitação de devolução identificada pela refund_request_key ja deve ter sido previamente criado pelo participante indireto.
:::
:::info IMPORTANTE
A refund transfer key deve ter sido préviamente criada pelo mock de recebimento de devolução com valor IGUAL à transação original.
:::

```json
{
    "refund_request_key": "42035bdd-0551-41c5-aaae-cb27d108160a",
    "refund_request_status": "closed",
    "analysis_result": "totally_accepted",
    "analysis_details": "Teste",
    "refund_transfer_key": "6f421127-892f-415f-8efc-4e20cf5d622d"
}
```

Request Body - Fechamento com Aceite Parcial

:::info IMPORTANTE
A Solicitação de devolução identificada pela refund_request_key ja deve ter sido previamente criado pelo participante indireto. Além disso, o valor devolvido não deve ser igual ou superior ao valor total da transação original.
:::
:::info IMPORTANTE
A refund transfer key deve ter sido préviamente criada pelo mock de recebimento de devolução com valor MENOR à transação original.
:::

```json
{
    "refund_request_key": "42035bdd-0551-41c5-aaae-cb27d108160a",
    "refund_request_status": "closed",
    "analysis_result": "partially_accepted",
    "analysis_details": "Teste",
    "refund_transfer_key": "6f421127-892f-415f-8efc-4e20cf5d622d"
}
```

Request Body - Fechamento com Recusa

:::info IMPORTANTE
A Solicitação de devolução identificada pela refund_request_key ja deve ter sido previamente criado pelo participante indireto.
:::

```json
{
    "refund_request_key": "47633091-7d44-4d10-9d00-1f937104e537",
    "refund_request_status": "closed",
    "analysis_result": "rejected",
    "analysis_details": "Teste",
    "reject_reason": "no_balance"
}
```

### Objeto Request Body

| Campo                      | Tipo   | Descrição                                                                                                                   | Máx. Caract. |
| -------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------- | ------------ |
| `refund_request_status` * | string | Status inicial da solicitação de devolução. "cancelled", "closed"                                                           | 36           |
| `refund_request_key` *    | string | Chave única da solicitação de devolução                                                                                     | 36           |
| `analysis_result` *       | string | Resultado da análise da solicitação de devolução. "totally_accepted" ou "partially_accepted", "rejected".                   | 36           |
| `analysis_details`        | string | Detalhes da análise da solicitação de devolução                                                                             | 2000         |
| `refund_transfer_key`      | float  | Identificador da transferência de devolução, obrigatório no caso de aceite                                                  | 20           |
| `reject_reason`            | string | Motivo da recusa de uma devolução (somente em analysis_result igual a rejected). "no_balance", "account_closure" ou "other" | 15           |

---

# Receber Solicitação de Devolução

URL: /documentation/pix_indireto/devolucao/webhooks_devolucao

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

Visto que um outro Participante pode abrir uma Solicitação de Devoluçao, tendo como alvo o Participante Indireto, é necessário que a QI Tech notifique o Participante Indireto acerca da Solicitação de Devolução aberta por outro Participante.

A QI Tech notificará o Participante Indireto via webhook .

:::danger IMPORTANTE
O Banco Central do Brasil define que, dentro de um período de 1 dia do recebimento da Solicitação de Devolução pelo Participante Indireto, a Devolução precisa ser fechada .

Caso haja atraso por parte do Participante Indireto, a QI Tech irá fechar a Solicitação de Devolução, com o status de totally_accepted , a fim de que a instituição não seja penalizada pelo Banco Central do Brasil.
:::

## Webhook recebimento de Devolução (Falha Operacional)
**Request Body**

```json
{
  "requesting_participant": "99999999",
  "requested_amount": 10,
  "refund_request_key": "2e42116f-4bdb-4f07-931f-c4dc7a78ed99",
  "infraction_report_key": null,
  "end_to_end_id": "E60701190202406281828JCBxFsqssCf",
  "contested_participant": "73856642",
  "refund_request_details": "Foi identificada uma fraude na transação.",
  "pix_transfer_key": "d5856a5f-378f-43ed-818b-df33b9fae703",
  "refund_request_type": "operational_flaw",
  "refund_request_status": "open",
  "refunded_amount": 0.00,
  "analysis_result": null,
  "analysis_details": null,
  "refund_transfer_key": null,
  "reject_reason": null,
  "refund_request_direction": "incoming",
  "created_at": "2024-07-01T15:46:18Z"
}
```

## Webhook recebimento de Devolução (Fraude)
**Request Body**

```json
{
  "requesting_participant": "99999999",
  "requested_amount": 10,
  "refund_request_key": "2e42116f-4bdb-4f07-931f-c4dc7a78ed99",
  "infraction_report_key": "9b36f112-ee56-4b26-9ba5-fde7b68b2d3b",
  "end_to_end_id": "E60701190202406281828JCBxFsqssCf",
  "contested_participant": "73856642",
  "refund_request_details": "Foi identificada uma fraude na transação.",
  "pix_transfer_key": "d5856a5f-378f-43ed-818b-df33b9fae703",
  "refund_request_type": "fraud",
  "refund_request_status": "open",
  "refunded_amount": 0.00,
  "analysis_result": null,
  "analysis_details": null,
  "refund_transfer_key": null,
  "reject_reason": null,
  "refund_request_direction": "incoming",
  "created_at": "2024-07-01T15:46:18Z"
}
```

---

# Consulta de uma entidade Alias

URL: /documentation/pix_indireto/gerenciamento_de_alias/consultar_alias

Consulta de uma entidade Alias, ja cadastrada para uma conta existente.

## Request

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY
MÉTODO GET

### Path Params

| Campo         | Tipo   | Descrição             | Caracteres |
|---------------|--------|-----------------------|------------|
| `account_key` | uuidv4 | Chave única da conta. | 36         |
| `alias_key`   | uuidv4 | Chave única do alias. | 36         |

## Response

STATUS 200

**Response Body**

```json
{
  "alias_key": "c446e513-131c-4741-bbc2-b7e6b6282899",
  "ispb": "12345678",
  "account_branch": "0001",
  "account_number": "4968688",
  "account_digit": "3",
  "account_type": "checking_account",
  "account_created_at": "2021-10-22T20:30:23.459Z",
  "owner_person_type": "legal",
  "owner_document_number": "89248771384257",
  "owner_name": " Vinicius De Oliveira",
  "owner_trading_name": "Pix Ltda",
  "created_at": "2021-10-22T20:30:23.459Z"
}
```

### Response Body Params

| Campo                   | Tipo       | Descrição                                          | Max. Caracteres                                         |
|-------------------------|------------|----------------------------------------------------|---------------------------------------------------------|
| `alias_key`             | string     | Chave única do alias                               | 36                                                      |
| `ispb`                  | string     | Ispb da instituição financeira vinculada ao Alias  | 36                                                      |
| `account_branch`        | string     | Agência, sem o dígito verificador                  | 4                                                       |
| `account_number`        | string     | Número de conta, sem o dígito verificador          | 20                                                      |
| `account_digit`         | string     | Dígito verificador da conta                        | 1                                                       |
| `account_type`          | enumerador | Tipo da conta                                      | **[Enumerador account_type](#enumerador-account_type)** |
| `account_created_at`    | string     | Data de criação da conta                           | 20                                                      |
| `owner_document_number` | string     | Numero de CPF ou CNPJ                              | 14                                                      |
| `owner_name`            | string     | Nome do dono da conta                              | 120                                                     |
| `owner_trading_name`    | string     | Nome fantasia do dono da conta (somente para CNPJ) | 100                                                     |
| `created_at`            | string     | Data de criação da requisição                      | 20                                                      |

### Enumerador account_type

| Enumerador           | Descrição           |
|----------------------|---------------------|
| **checking_account** | Conta Corrente      |
| **salary_account**   | Conta Salário       |
| **saving_account**   | Conta Poupança      |
| **payment_account**  | Conta de Pagamentos |

STATUS 404

Response Body: Not Found

```json

{
  "title": "Not Found", 
  "description": "Account not found for the given key \{account_key\}", 
  "translation": "A account_key \{account_key\} não foi encontrada",
  "extra_fields": {}, 
  "code": "ACC000006"
}
```

Response Body: Not found

```json

{
  "title": "Not found", 
  "description": "Alias \{alias_key\} not found", 
  "translation": "Alias \{alias_key\} n\u00e3o encontrado",
  "extra_fields": {}, 
  "code": "ACC000181"
}
```

---

# Consulta de Alias por Request Control Key

URL: /documentation/pix_indireto/gerenciamento_de_alias/consultar_request_control_key

Retorno da alias_key obtida na criação de um Alias, utilizando a request_control_key originalmente atribuida para ela no
corpo da requisição original.

## Request

ENDPOINT /account/ ACCOUNT_KEY /alias
MÉTODO GET

### Path Params

| Campo         | Tipo   | Descrição             | Caracteres |
|---------------|--------|-----------------------|------------|
| `account_key` | uuidv4 | Chave única da conta. | 36         |

### Query Params

| Campo                   | Tipo   | Descrição                                             | Caracteres |
|-------------------------|--------|-------------------------------------------------------|------------|
| `request_control_key` * | uuidv4 | UUID4 para fins de consulta sobre a requisição feita. | 36         |

## Response

STATUS 200

**Response Body**

```json
{
  "alias_key": "c446e513-131c-4741-bbc2-b7e6b6282899",
  "ispb": "12345678",
  "account_branch": "0001",
  "account_number": "4968688",
  "account_digit": "3",
  "account_type": "checking_account",
  "account_created_at": "2021-10-22T20:30:23.459Z",
  "owner_person_type": "legal",
  "owner_document_number": "89248771384257",
  "owner_name": " Vinicius De Oliveira",
  "owner_trading_name": "Pix Ltda",
  "created_at": "2021-10-22T20:30:23.459Z"
}
```

### Response Body Params

| Campo                   | Tipo       | Descrição                                          | Max. Caracteres                                         |
|-------------------------|------------|----------------------------------------------------|---------------------------------------------------------|
| `alias_key`             | string     | Chave única do alias                               | 36                                                      |
| `ispb`                  | string     | Ispb da instituição financeira vinculada ao Alias  | 36                                                      |
| `account_branch`        | string     | Agência, sem o dígito verificador                  | 4                                                       |
| `account_number`        | string     | Número de conta, sem o dígito verificador          | 20                                                      |
| `account_digit`         | string     | Dígito verificador da conta                        | 1                                                       |
| `account_type`          | enumerador | Tipo da conta                                      | **[Enumerador account_type](#enumerador-account_type)** |
| `account_created_at`    | string     | Data de criação da conta                           | 20                                                      |
| `owner_document_number` | string     | Numero de CPF ou CNPJ                              | 14                                                      |
| `owner_name`            | string     | Nome do dono da conta                              | 120                                                     |
| `owner_trading_name`    | string     | Nome fantasia do dono da conta (somente para CNPJ) | 100                                                     |
| `created_at`            | string     | Data de criação da requisição                      | 20                                                      |

### Enumerador account_type

| Enumerador           | Descrição           |
|----------------------|---------------------|
| **checking_account** | Conta Corrente      |
| **salary_account**   | Conta Salário       |
| **saving_account**   | Conta Poupança      |
| **payment_account**  | Conta de Pagamentos |

STATUS 404

Response Body: Not Found

```json
  {
  "title": "Not Found",
  "description": "Account not found for the given key \{account_key\}",
  "translation": "A account_key \{account_key\} não foi encontrada",
  "extra_fields": {},
  "code": "ACC000006"
}
```

STATUS 404

Response Body: Request Control Key Not found

```json
{
  "title": "Request Control Key Not found",
  "description": "The informed request_control_key \{request_control_key\} has no original registered entry associated",
  "translation": "A request_control_key informada \{request_control_key\} n\u00e3o possui entrada original associada",
  "extra_fields": {},
  "code": "ACC000186"
}
```

---

# Criação de uma entidade Alias

URL: /documentation/pix_indireto/gerenciamento_de_alias/criacao_de_alias

É o Fluxo responsável por criar entidades Alias, atreladas a uma conta jś existente.

## Request

ENDPOINT /account/ ACCOUNT_KEY /alias
MÉTODO POST

**Request Body**

```json
{
    "request_control_key":"5b4259a4-dc4a-489f-a050-3391e13d9850",
    "account_branch": "0001",
    "account_number": "4968698",
    "account_digit": "3",
    "account_type": "checking_account",
    "account_created_at": "2022-09-24T19:46:43.001Z",
    "owner_person_type": "legal",
    "owner_document_number": "89248771384257",
    "owner_name": "Vinicius De Oliveira",
    "owner_trading_name": "Pix Ltda"
}

```

### Path Params

| Campo         | Tipo   | Descrição             | Caracteres |
|---------------|--------|-----------------------|------------|
| `account_key` | uuidv4 | Chave única da conta. | 36         |

### Request Body Params

| Campo                     | Tipo       | Descrição                                                                        | Max. Caracteres                                         |
|---------------------------|------------|----------------------------------------------------------------------------------|---------------------------------------------------------|
| `request_control_key` *   | string     | Chave única de identificação da request utilizada pelo cliente no formato uuidv4 | 36                                                      |
| `account_branch` *        | string     | Agência, sem o dígito verificador                                                | 4                                                       |
| `account_number` *        | string     | Número de conta, sem o dígito verificador                                        | 20                                                      |
| `account_digit` *         | string     | Dígito verificador da conta                                                      | 1                                                       |
| `account_type`*           | enumerador | Tipo da conta                                                                    | **[Enumerador account_type](#enumerador-account_type)** |
| `account_created_at` *    | string     | Data de criação da conta. Ex: "2022-09-24T19:46:43.001Z"                         | 20                                                      |
| `owner_document_number` * | string     | Numero de CPF ou CNPJ                                                            | 11(CPF) ou 14(CNPJ)                                     |
| `owner_person_type` *     | string     | Tipo de dono da conta. Pode ser **legal** ou **natural**                         | 7                                                       |
| `owner_name` *            | string     | Nome do dono da conta                                                            | 120                                                     |
| `owner_trading_name`      | string     | Nome fantasia do dono da conta (opcional, e somente para CNPJ)                   | 100                                                     |

### Enumerador account_type

| Enumerador           | Descrição           |
|----------------------|---------------------|
| **checking_account** | Conta Corrente      |
| **salary_account**   | Conta Salário       |
| **saving_account**   | Conta Poupança      |
| **payment_account**  | Conta de Pagamentos |

## Response

STATUS 201 created

**Response Body**

```json
{
  "alias_key": "e04f496b-47be-4762-a6e2-8f2b05b46780",
  "created_at": "2022-09-24T19:46:43.001Z"
}
```

### Response Body Params

| Campo        | Tipo          | Descrição                        | Max. Caracteres |
|--------------|---------------|----------------------------------|-----------------|
| `alias_key`  | uuidv4        | Chave única do alias             | 36              |
| `created_at` | datetime Zulu | Data de realização da requisição | 20              |

STATUS 404

Response Body: Not Found

```json

  {
    "title": "Not Found", 
  "description": "Account not found for the given key \{account_key\}", 
  "translation": "A account_key \{account_key\} não foi encontrada",
  "extra_fields": {}, 
  "code": "ACC000006"
}
```

STATUS 400

Response Body: Repeted Request Control Key

```json

  {
  "title": "Repeated Request Control Key", 
  "description": "The request_control_key sent \{request_control_key\}, was already been used in other requisition", 
  "translation": "A request_control_key enviada \{request_control_key\}, já foi utilizada em outra requisição",
  "extra_fields": {}, 
  "code": "ACC000179"
}
```

Response Body: Invalid owner trading name

```json

  {
  "title": "Bad Request", 
  "description": "The owner_trading_name can only be sent by a legal person type", 
  "translation": "O owner_trading_name s\u00f3 pode ser utilizado por uma pessoa jur\u00eddica",
  "extra_fields": {}, 
  "code": "ACC000180"
}
```

---

# Deleção de uma entidade Alias

URL: /documentation/pix_indireto/gerenciamento_de_alias/deletar_alias

Deleção de uma entidade Alias, já cadastrada para uma conta account existente.
## Request

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY
MÉTODO DELETE

### Path Params

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `account_key` | uuidv4 | Chave única da conta. | 36 |
| `alias_key` | uuidv4 | Chave única do alias. | 36 |

## Response

STATUS 200

**Response Body**

```json
{}
```

STATUS 404

Response Body: Not Found

```json

  {
  "data": "{\"title\": \"Not Found\", \"description\": \"Account not found for the given key \{account_key\}\", \"translation\": \"A account_key \{account_key\} não foi encontrada\", \"extra_fields\": {}, \"code\": \"ACC000006\"}",
  "title": "Not Found", 
  "description": "Account not found for the given key \{account_key\}", 
  "translation": "A account_key \{account_key\} não foi encontrada",
  "extra_fields": {}, 
  "code": "ACC000006"
}
```

STATUS 404

Response Body: Not found

```json

  {
  "data": "{\"title\": \"Not found\", \"description\": \"Alias \{alias_key\} not found\", \"translation\": \"Alias \{alias_key\} n\u00e3o encontrado\", \"extra_fields\": {}, \"code\": \"ACC000181\"}",
  "title": "Not found", 
  "description": "Alias \{alias_key\} not found", 
  "translation": "Alias \{alias_key\} n\u00e3o encontrado",
  "extra_fields": {}, 
  "code": "ACC000181"
}
```

STATUS 400

Response Body: Alias Key Dont Match with Account Key

```json

  {
  "data": "{\"title\": \"Alias Key Dont Match with Account Key\", \"description\": \"The alias_key \{alias_key\} Dont Match with the account_key \{account_key\}\", \"translation\": \"AA alias_key \{alias_key\} não combina com a account_key \{account_key\}\", \"extra_fields\": {}, \"code\": \"ACC000181\"}",
  "title": "Alias Key Dont Match with Account Key", 
  "description": "The alias_key \{alias_key\} Dont Match with the account_key \{account_key\}", 
  "translation": "A alias_key \{alias_key\} não combina com a account_key \{account_key\}",
  "extra_fields": {}, 
  "code": "ACC000181"
}
```

---

# Introdução à entidade de Alias

URL: /documentation/pix_indireto/gerenciamento_de_alias/introducao_alias

A fim de manter e alinhar os dados em relação ao cadastro de chave PIX, conforme o Banco Central do Brasil requisita, o Participante Indireto deve registrar um Alias na QI Tech,

Todo Alias está, necessariamente, vinculado a uma conta a qual o Participante Indireto possui na QI Tech.

:::info Informação

Tudo o descrito nesta seção de introdução também está, de forma detalhada como o Participante Indireto deve tratar via API, na seções seguintes.

:::

## O que a entidade Alias representa?

A entidade Alias é uma 'máscara' dos dados da conta o qual o cliente do Participante Indireto possui cadastrado no próprio Participante Indireto. Ressalta-se que a QI Tech fará apenas as verificações de formatação em relação aos dados enviados pelo Participante Indireto a nós.

Por exemplo: validação de CPF, CNPJ, tamanho máximo de caracteres de um nome fantasia, etc.

Os dados os quais a QI Tech pede ao Participante Indireto enviar, em relação à conta de seu cliente, são apenas os necessários para o âmbito das funcionalidades do PIX.

## Alias na prática

Na prática, a entidade de Alias representa o cliente do Participante Indireto.

Um exemplo acerca da necessidade de criação de um Alias seria:
Participante Indireto possui uma conta, de account_key a520b977-d6b2-4f27-bef5-29760ebfd6a7 cadastrada na QI Tech,
Participante Indireto deseja vincular um cliente próprio a esta conta cadastrada na QI Tech,
Participante Indireto envia os dados do cliente (número da conta, agência, nome, nome fantasia, etc) para vincular a esta conta cadastrada na QI Tech,
QITech vincula o cliente do Participante Indireto à conta do Participante Indireto cadastrada.
Participante Indireto recebe uma chave única de identificaçã do Alias cadastrado.

Deste modo, o Participante Indireto pode solicitar a criação de uma chave PIX e a QI Tech conseguirá, efetivamente, comunicar-se com o Banco Central do Brasil com os dados necessários para o cadastro.

##### Representação de uso de Alias com relação de 1:N:
![Uso de Alias com relação de 1:N](/img/diagrams/pix-indireto-gerenciamento-de-alias-introducao-alias-1.svg)

##### Representação de uso de Alias com relação de 1:1:

![Uso de Alias com relação de 1:1](/img/diagrams/pix-indireto-gerenciamento-de-alias-introducao-alias-2.svg)

---

# Listagem de Alias

URL: /documentation/pix_indireto/gerenciamento_de_alias/listagem_de_alias

Listagem dos Alias de uma conta

## Request

ENDPOINT /account/ ACCOUNT_KEY /alias
MÉTODO GET

### Path Params

| Campo         | Tipo   | Descrição             | Caracteres |
|---------------|--------|-----------------------|------------|
| `account_key` | uuidv4 | Chave única da conta. | 36         |

### Query Params

| Campo         | Tipo    | Descrição                               | Max Value |
|---------------|---------|-----------------------------------------|-----------|
| `page_number` | integer | Página atual que está sendo consultada. | -         |
| `page_size`   | integer | Quantidade de resultados por página.    | 100       |

## Response

STATUS 200

**Response Body**

```json
{
  "data": [
    {
      "alias_key": "a446e513-131c-4741-bbc2-b7e6b6282899",
      "ispb": "12345678",
      "account_type": "checking_account",
      "account_branch": "0001",
      "account_number": "4968688",
      "account_digit": "3",
      "account_created_at": "2021-10-22T20:30:23.459Z",
      "owner_person_type": "legal",
      "owner_document_number": "89248771384257",
      "owner_name": " Vinicius De Oliveira",
      "owner_trading_name": "Pix Ltda",
      "created_at": "2021-10-22T20:30:23.459Z"
    },
    {
      "alias_key": "c246a573-131c-4741-bbc2-b7e6b6282424",
      "ispb": "12345678",
      "account_type": "checking_account",
      "account_branch": "0001",
      "account_number": "2987685",
      "account_digit": "1",
      "account_created_at": "2021-10-22T20:30:23.459Z",
      "owner_person_type": "legal",
      "owner_document_number": "23448771384689",
      "owner_name": " Roberto Moraes",
      "owner_trading_name": "Pix Ltda",
      "created_at": "2021-10-22T20:30:23.459Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "rows_per_page": 10
  }
}
```

### Response Body Params

| Campo                   | Tipo       | Descrição                                          | Max. Caracteres                                         |
|-------------------------|------------|----------------------------------------------------|---------------------------------------------------------|
| `alias_key`             | string     | Chave única do alias                               | 36                                                      |
| `ispb`                  | string     | Ispb da instituição financeira vinculada ao Alias  | 36                                                      |
| `account_branch`        | string     | Agência, sem o dígito verificador                  | 4                                                       |
| `account_number`        | string     | Número de conta, sem o dígito verificador          | 20                                                      |
| `account_digit`         | string     | Dígito verificador da conta                        | 1                                                       |
| `account_type`          | enumerador | Tipo da conta                                      | **[Enumerador account_type](#enumerador-account_type)** |
| `account_created_at`    | string     | Data de criação da conta                           | 20                                                      |
| `owner_document_number` | string     | Numero de CPF ou CNPJ                              | 14                                                      |
| `owner_name`            | string     | Nome do dono da conta                              | 120                                                     |
| `owner_trading_name`    | string     | Nome fantasia do dono da conta (somente para CNPJ) | 100                                                     |
| `created_at`            | string     | Data de criação da requisição                      | 20                                                      |

### Enumerador account_type

| Enumerador           | Descrição           |
|----------------------|---------------------|
| **checking_account** | Conta Corrente      |
| **salary_account**   | Conta Salário       |
| **saving_account**   | Conta Poupança      |
| **payment_account**  | Conta de Pagamentos |

STATUS 404

Response Body: Not Found

```json

  {
  "title": "Not Found", 
  "description": "Account not found for the given key \{account_key\}", 
  "translation": "A account_key \{account_key\} não foi encontrada",
  "extra_fields": {}, 
  "code": "ACC000006"
}
```

STATUS 400

Response Body: Wrong Pagination Query Parameter Set

```json
{
  "title": "Wrong Pagination Query Parameter Set",
  "description": "If page_number was informed, the page_size should also be informed",
  "translation": "Se o page_number foi informado, o page_size deve ser informado tambem",
  "extra_fields": {},
  "code": "ACC000183"
}
```

STATUS 400

Response Body: Wrong Pagination Query Parameter Format

```json
{
  "title": "Wrong Pagination Query Parameter Format",
  "description": "The page_number and page_formar should be formatad as an integer",
  "translation": "O page_number e o page_size devem ter formato de integer",
  "extra_fields": {},
  "code": "ACC000184"
}
```

---

# Introdução

URL: /documentation/pix_indireto/introducao

Na QI Tech, estamos orgulhosos de expandir nossos serviços através do serviço de PIX Indireto. Reconhecemos os desafios que algumas instituições podem enfrentar ao tentar se integrar ao PIX e, por isso, estamos comprometidos em tornar isso uma realidade fácil e acessível para todos.

Como participante direto do PIX, que opera com eficiência e segurança, implementamos uma solução de alta tecnologia que permite a bancos, instituições de pagamento e fintechs de todos os tamanhos se tornarem participantes indiretos, garantindo a todos os benefícios do PIX sem o peso dos custos operários e técnicos.

Nosso serviço de PIX Indireto proporciona uma integração simplificada e uma operação sem complicações, com custos reduzidos e compliance regulatório. Além disso, você não precisará se preocupar com os complexos processos técnicos; cuidaremos de tudo, permitindo que você se concentre no que é mais importante - seus clientes.

Com a QI Tech, você estará equipado para proporcionar aos seus clientes uma experiência de pagamento rápida, segura e disponível 24 horas por dia, 7 dias por semana. Nosso objetivo é facilitar sua transição para o PIX, permitindo que você ofereça o melhor serviço ao cliente.

Nas seções seguintes a esta introdução estão descritas as funcionalidades que um Participante Indireto pode executar, via API, no âmbito do PIX Indireto.

---

# Chaves PIX mockadas em ambiente de sandbox

URL: /documentation/pix_indireto/movimentacoes/chaves_pix_mockadas

## 104 - CAIXA ECONOMICA FEDERAL

| Chave Pix | Tipo | Nome do titular | Documento do titular | Número da conta | Agencia da conta | ISPB |
|---|---|---|---|---|---|---|
| +5568970000000 | phone_number | Vivo Test | 65322181032 | 21837-5 | 4458 | 360305 | 
| d6e2d611-6c68-4f84-9be5-962ad2f2bcb6 | random_key | Vivo Test | 61295118092 | 100091086-1 | 465 | 360305 | 
| 61295118092 | cpf | Vivo Test | 61295118092 | 1300005670-8 | 4289 | 360305 | 
| pix03@pix03.com | email | Vivo Test | 96969879003 | 363214578-8 | 8615 | 360305 | 
| +5568911106520 | phone_number | Vivo Test | 66702118805 | 100071086-1 | 465 | 360305 | 
| 5e6ce02a-e0da-4d56-73b8-84f118b4f371 | random_key | Vivo Test | 52720072800 | 100061086-1 | 465 | 360305 | 
| 52720072800 | cpf | Vivo Test | 52720072800 | 100071076-1 | 465 | 360305 | 
| pix10@pix10.com | email | Vivo Test | 24182533410 | 100071066-1 | 465 | 360305 | 
| pix33@pix33.com | email | Vivo Test | 56151446887 | 96764-6 | 919 | 360305 | 
| 88253032978 | cpf | Vivo Test | 88253032978 | 96764-6 | 919 | 360305 | 

## 341 - ITAÚ UNIBANCO S.A.

| Chave Pix | Tipo | Nome do titular | Documento do titular | Número da conta | Agencia da conta | ISPB |
|---|---|---|---|---|---|---|
| 22156083070 | cpf | Vivo Test | 22156083070 | 19413-2 | 8534 | 60701190 | 
| 96969879003 | cpf | Vivo Test | 96969879003 | 22110-1 | 8615 | 60701190 | 
| 5e6ce06a-e0da-4d56-93b8-84f118b4f371 | random_key | Vivo Test | 43135154025 | 57980-4 | 5067 | 60701190 | 
| pix11@pix11.com | email | Vivo Test | 66702118805 | 86091-8 | 3101 | 60701190 | 
| 24182533410 | cpf | Vivo Test | 24182533410 | 20467-1 | 5807 | 60701190 | 
| pix07@pix07.com | email | Vivo Test | 11646288874 | 33087-6 | 8872 | 60701190 | 

## 237 - BCO BRADESCO S.A.

| Chave Pix | Tipo | Nome do titular | Documento do titular | Número da conta       | Agencia da conta | ISPB |
|---|---|---|----------------------|-----------------------|---|---|
| 65322181032 | cpf | Vivo Test | 65322181032          | 1017372-2             | 1 | 60746948 | 
| b9380607-dac6-4e17-8ca7-eb761e3aa1dd | random_key | José Alves | 24080025327          | 0001000000000022279-9 | 1 | 08744817 | 
| b9380607-dac6-4e17-8ca7-eb761e3aa1dd | random_key | José Alves | 24080025327          | 0003000000000000288-9 | 1 | 08744817 | 
| b9380607-dac6-4e17-8ca7-eb761e3aa1dd | random_key | José Alves | 24080025327          | 0013000000000013609-9 | 1 | 08744817 | 
| b9380607-dac6-4e17-8ca7-eb761e3aa1dd | random_key | José Alves | 24080025327          | 1288000000884535174-9 | 1 | 08744817 | 
| b9380607-dac6-4e17-8ca7-eb761e3aa1dd | random_key | José Alves | 24080025327          | 3701000000593070593-9 | 1 | 08744817 | 
| pix01@pix01.com | email | Vivo Test | 65322181032          | 1017372-2             | 1 | 60746948 | 
| pix01@pix01.com | email | Vivo Test | 65322181032          | 1925255-8             | 3952 | 60746948 | 
| pix12@pix12.com | email | Vivo Test | 11085087824          | 1071659-4             | 427 | 60746948 | 
| 5e6ce08a-e0da-4d56-93b8-84f118b4f371 | random_key | Vivo Test | 66702118805          | 1751795-3             | 6162 | 60746948 | 
| +5568911137576 | phone_number | Vivo Test | 82104056080          | 1587784-7             | 1340 | 60746948 | 

## 33 - BCO SANTANDER (BRASIL) S.A.

| Chave Pix | Tipo | Nome do titular | Documento do titular | Número da conta | Agencia da conta | ISPB |
|---|---|---|---|---|---|---|
| 5e6ce05a-e0da-4d56-93b8-84f118b4f371 | random_key | Vivo Test | 42759960030 | 9206744-2 | 4187 | 90400888 | 
| 34175131205 | cpf | Vivo Test | 34175131205 | 9206744-2 | 4187 | 90400888 | 
| 5e6ce05a-e0da-4d56-53b8-74f118b4f371 | random_key | Vivo Test | 11646288874 | 9206744-2 | 4187 | 90400888 | 
| 82104056080 | cpf | Vivo Test | 82104056080 | 2850903-2 | 214 | 90400888 | 

## 77 - BANCO INTER
ISPB: 416968

| Chave Pix | Tipo | Nome do titular | Documento do titular | Número da conta | Agencia da conta | ISPB |
|---|---|---|---|---|---|---|
| 22156083070 | cpf | Vivo Test | 22156083070 | 4810813-8 | 1 | 416968 | 
| pix13@pix13.com | email | Vivo Test | 43135154025 | 4830813-8 | 1 | 416968 | 
| 66702118805 | cpf | Vivo Test | 66702118805 | 4820813-8 | 1 | 416968 | 
| 5e6ce05a-e0da-4d56-93b7-84f118b4f371 | random_key | Vivo Test | 24182533410 | 4850813-8 | 1 | 416968 | 
| +5568911168384 | phone_number | Vivo Test | 17413005255 | 4850813-8 | 1 | 416968 | 
| pix06@pix06.com | email | Vivo Test | 81035632691 | 4750813-8 | 1 | 416968 | 
| pix31@pix31.com | email | Vivo Test | 55125236780 | 1768538-4 | 2960 | 416968 | 

## 260 - NU PAGAMENTOS - IP

| Chave Pix | Tipo | Nome do titular | Documento do titular | Número da conta | Agencia da conta | ISPB |
|---|---|---|---|---|---|---|
| pix04@pix04.com | email | Vivo Test | 69017362073 | 81648459-8 | 1 | 18236120 | 
| pix09@pix09.com | email | Vivo Test | 34175131205 | 81538459-8 | 1 | 18236120 | 
| 5e6ce01a-e0da-4d56-93b8-44f118b4f371 | random_key | Vivo Test | 17413005255 | 81548459-8 | 1 | 18236120 | 
| +5568911186420 | phone_number | Vivo Test | 81035632691 | 81538459-8 | 1 | 18236120 | 
| pix32@pix32.com | email | Vivo Test | 56151446887 | 293201-6 | 2811 | 18236120 | 

## 336 - BCO C6 S.A.

| Chave Pix | Tipo | Nome do titular | Documento do titular | Número da conta | Agencia da conta | ISPB |
|---|---|---|---|---|---|---|
| dbbf965d-677c-49ff-b9da-5131da1505f3 | random_key | Vivo Test | 65322181032 | 1019902-6 | 1 | 31872495 | 
| 5e6ce07a-e0da-4d56-93b8-84f118b4f371 | random_key | Vivo Test | 11085087824 | 1018902-6 | 1 | 31872495 | 
| 11646288874 | cpf | Vivo Test | 11646288874 | 1017902-6 | 1 | 31872495 | 

## 403 - CORA SCD S.A.

| Chave Pix | Tipo | Nome do titular | Documento do titular | Número da conta | Agencia da conta | ISPB |
|---|---|---|---|---|---|---|
| 39284100000000 | cnpj | Parcela Mais | 39284100000000 | 1708315-8 | 1 | 37880206 | 

## 422 - BCO SAFRA S.A.

| Chave Pix | Tipo | Nome do titular | Documento do titular | Número da conta | Agencia da conta | ISPB |
|---|---|---|---|---|---|---|
| pix02@pix02.com | email | Vivo Test | 69017362073 | 364522-5 | 284 | 58160789 | 
| pix08@pix08.com | email | Vivo Test | 34175131205 | 264522-5 | 284 | 58160789 | 
| +5568911106070 | phone_number | Vivo Test | 11646288874 | 354522-5 | 284 | 58160789 | 
| 53465252110 | cpf | Vivo Test | 53465252110 | 364422-5 | 284 | 58160789 | 
| +5568911122488 | phone_number | Vivo Test | 10632271 | 1558321-5 | 907 | 58160789 | 

## 655 - BCO VOTORANTIM S.A.

| Chave Pix | Tipo | Nome do titular | Documento do titular | Número da conta | Agencia da conta | ISPB |
|---|---|---|---|---|---|---|
| 5301321099 | cpf | Vivo Test | 5301321099 | 622660113-8 | 1111 | 59588111 | 

## DOCK SOLUCOES EM MEIOS DE PAGAMENTO S A

| Chave Pix | Tipo | Nome do titular | Documento do titular | Número da conta | Agencia da conta | ISPB |
|---|---|---|---|---|---|---|
| +5568911165580 | phone_number | Vivo Test | 53465252110 | 622470112-8 | 1111 | 8744817 | 
| 17413005255 | cpf | Vivo Test | 17413005255 | 622450112-8 | 1111 | 8744817 | 
| 81035632691 | cpf | Vivo Test | 81035632691 | 622450113-8 | 1111 | 8744817 | 
| 5e6ce05a-e0da-4d56-93b8-64f118b4f371 | random_key | Vivo Test | 81035632691 | 622650113-8 | 1111 | 8744817 | 

## Empresas com CNPJ Alfanumérico

| Chave Pix | Tipo | Nome do titular | Documento do titular | Número da conta | Agencia da conta | ISPB | Participante |
|---|---|---|---|---|---|---|---|
| HSRMASY3000160 | cnpj | Empresa Alfa Mock 1 | HSRMASY3000160 | 1050001-2 | 1 | 416968 | BANCO INTER |
| 0ZSD0MBG000135 | cnpj | Empresa Alfa Mock 2 | 0ZSD0MBG000135 | 81550001-2 | 1 | 18236120 | NU PAGAMENTOS - IP |
| DDA9RHST000100 | cnpj | Empresa Alfa Mock 3 | DDA9RHST000100 | 1750001-9 | 1 | 37880206 | CORA SCD S.A. |

## COMPANHIA GLOBAL DE SOLUCOES E SERVICOS DE PAGAMENTOS S.A.

| Chave Pix | Tipo | Nome do titular | Documento do titular | Número da conta | Agencia da conta | ISPB |
|---|---|---|---|---|---|---|
| 96755229091 | cpf | Teste sem Compe | 96755229091 | 1444301-8 | 1 | 32024691 |

---

# Consulta de Dados de Chave Pix no Banco Central

URL: /documentation/pix_indireto/movimentacoes/consultar_chave_pix

## Request

ENDPOINT /pix_key/ PIX_KEY
MÉTODO GET

### Request Path Params

| Campo       | Tipo   | Descrição                      | Caracteres |
|-------------|--------|--------------------------------|------------|
| `pix_key` * | string | Chave PIX que será consultada. | 77         |

:::info Tipos de Chave Pix
A “pix_key” pode ser um CPF, CNPJ, E-mail, Celular ou uma Chave Aleatória (UUID), seguindo as seguintes formatações:

**CPF**: Número inteiro com 11 dígitos.

**CNPJ**: Número inteiro com 14 dígitos.

**E-mail**: Texto contendo ao menos um “@”.

**Celular**: Texto contendo os seguintes valores: “+55” + “DDD do celular“ + “Número Inteiro do Celular com no mínimo 8
e no máximo 9 dígitos”. Ex: “+5511987654321“.

**Chave Aleatória**: UUID4.
:::

### Request Query Params

| Campo         | Tipo   | Descrição             | Caracteres |
|---------------|--------|-----------------------|------------|
| `alias_key` * | uuidv4 | Chave única do alias. | 36         |

:::info Utilização de tokens de consulta
Para que o token de consulta de chave pix seja cobrado da pessoa correta, é obrigatório que o `alias_key` seja enviado.
:::

## Response

STATUS 200

Response Body: Chave Ativa

```json
{
  "account_branch": "0001",
  "account_created_at": "2023-09-06T22:03:34.000Z",
  "account_digit": "8",
  "account_number": "2897775",
  "account_type": "checking",
  "bank_code": null,
  "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
  "financial_institution": "BANCO INDIRETO PRUPRU",
  "ispb": "32402502",
  "owner_masked_document_number": "**.458.****/0001-**",
  "owner_name": "Empresa teste 01",
  "owner_person_type": "legal",
  "owner_trading_name": null,
  "pix_key": "0f723f66-b333-4187-be16-97fc37c86052"
}

```

| Campo                          | Tipo   | Descrição                                          | Max. Caracteres |
|--------------------------------|--------|----------------------------------------------------|-----------------|
| `pix_key`                      | string | Chave pix da consulta                              | 4               |
| `account_branch`               | string | Agência, sem o dígito verificador                  | 4               |
| `account_digit`                | string | Dígito verificador da conta                        | 1               |
| `account_number`               | string | Número de conta, sem o dígito verificador          | 20              |
| `account_type`                 | string | Definição do tipo de conta                         | 20              |
| `owner_person_type`            | string | Tipo de dono da contaPode ser "legal" ou "natural" | 7               |
| `owner_masked_document_number` | string | Numero de CPF ou CNPJ                              | 14              |
| `end_to_end_id`                | string | Chave unitária da transação PIX                    | 32              |
| `owner_name`                   | string | Nome do dono da conta                              | 120             |
| `owner_trading_name`           | string | Nome fantasia do dono da conta (somente para CNPJ) | 100             |
| `ispb`                         | string | ISPB do Participate detentor da chave              | 8               |
| `bank_code`                    | string | Código COMPE da instituição financeira             | 3               |
| `financial_institution`        | string | Nome da instituição financeira detentora da chave  | 100             |
| `account_created_at`           | string | Data de criação da conta                           | 20              |

STATUS 4XX

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`               | Descrição (eng)<br/>`Description`                                             | Descrição (ptbr)<br/>`translation`                                               |
|-------------|----------------------|----------------------------------|-------------------------------------------------------------------------------|----------------------------------------------------------------------------------|
| 400         | PIX000086            | Invalid Query Params Combination | Account_key and Alias_key are mutually exclusive query parameters. Choose one | Account_key e Alias_key são parâmetros mutualmente exclusivos. Escolha apenas um |
| 403         | PIX000080            | Not enough permission            | The selected agent is not an Pix Indirect Participant                         | O agente selecionado não é um Participante Indireto do Pix                       |
| 404         | PIX000082            | Alias not found                  | Alias \{alias_key\} not found                                                   | Alias \{alias_key\} não encontrado                                                 |
| 404         | PIX000017            | Pix Key is Unregistered          | Pix key \{pix_key\} is not currently used                                       | A chave pix \{pix_key\} não está sendo utilizada                                   |
| 400         | PIX000081            | Rate Limit Exceeded              | Rate Limit Exceeded                                                           | Limite de requisições excedido                                                   |

---

# Consultar Transação Pix

URL: /documentation/pix_indireto/movimentacoes/consultar_pix

## Request

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer/ PIX_TRANSFER_KEY / PIX_TRANSFER_DIRECTION
MÉTODO GET

### Request Path Params

| Campo                      | Tipo   | Descrição                                                                                        |
|----------------------------|--------|--------------------------------------------------------------------------------------------------|
| `pix_transfer_direction` * | string | Filtro para indicar se uma transação é de entrada ou saída. Valores: **incoming** e **outgoing** |
| `account_key` *            | string | Chave única de identificação da conta QI                                                         |
| `alias_key` *              | string | Chave única do Alias                                                                             |
| `pix_transfer_key` *       | string | Chave única de identificação da transferência Pix                                                |

:::caution Atenção
Será apenas permitida a visualização de uma transferência caso o requisitante tenha permissões no alias de saída da
transação. Caso o contrário um erro de não encontrado será retornado.
:::

## Response

STATUS 201

Response Body: Transferência Enviada (outgoing)

```json
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "pix_message": "Bom dia",
  "pix_transfer_type": "manual",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "alias_key": "c4332971-7cff-42eb-a117-7e6f0cd74db2",
  "updated_at": "2021-10-22T20:30:23.459Z",
  "created_at": "2021-10-22T20:30:23.459Z",
  "target_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "***02502000***",
    "owner_person_type": "legal",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502",
    "pix_key": null
  },
  "receiver_conciliation_id": null,
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "end_to_end_id": "E3240250220211022203051750897529",
  "pix_transfer_status": "sent",
  "transfer_amount": 126.97,
  "fee_amount": 0.0,
  "rejection_reason": null,
  "reversals": [
    {
      "end_to_end_id": "D35713491202309182058jlqdBkkHSWU",
      "transfer_amount": 0.01,
      "reversal_reason": "client_request",
      "pix_transfer_status": "received",
      "pix_transfer_key": "423866cd-0f3f-4cdd-904b-0d2e33273afd",
      "request_control_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0a",
      "created_at": "2021-10-23T20:30.459Z"
    }
  ]
}

```

Response Body: Transferência Rejeitada (outgoing)

```json
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "pix_message": "Bom dia",
  "pix_transfer_type": "manual",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "alias_key": "c4332971-7cff-42eb-a117-7e6f0cd74db2",
  "updated_at": "2021-10-22T20:30:23.459Z",
  "created_at": "2021-10-22T20:30:23.459Z",
  "target_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "***02502000***",
    "owner_person_type": "legal",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502",
    "pix_key": null
  },
  "receiver_conciliation_id": null,
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "end_to_end_id": "E3240250220211022203051750897529",
  "pix_transfer_status": "rejected",
  "transfer_amount": 126.97,
  "fee_amount": 0.0,
  "error_code": "PXT000132",
  "error_description": "Target account number is invalid.",
  "error_translation": "Número da conta de destino é inexistente ou inválido.",
  "reversals": []
}

```

Response Body: Devolução Enviada (outgoing)

```json
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "pix_message": "Bom dia",
  "pix_transfer_type": "reversal",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "alias_key": "c4332971-7cff-42eb-a117-7e6f0cd74db2",
  "updated_at": "2021-10-22T20:30:23.459Z",
  "created_at": "2021-10-22T20:30:23.459Z",
  "target_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "***02502000***",
    "owner_person_type": "legal",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502",
    "pix_key": null
  },
  "receiver_conciliation_id": null,
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "end_to_end_id": "E3240250220211022203051750897529",
  "pix_transfer_status": "sent",
  "transfer_amount": 126.97,
  "fee_amount": 0.0,
  "rejection_reason": null,
  "reversals": [],
  "original_incoming_pix_transfer": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3"
}

```

Response Body: Transferência Recebida (incoming)

```json
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "alias_key": "c4332971-7cff-42eb-a117-7e6f0cd74db2",
  "end_to_end_id": "E18236120202308111235s14fddf2801",
  "pix_transfer_status": "received",
  "receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
  "transfer_amount": 126.97,
  "fee_amount": 0.0,
  "source_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "***02502000***",
    "owner_person_type": "legal",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502"
  },
  "pix_transfer_type": "dynamic_qr_code",
  "reversals": []
}
```

Response Body: Devolução Recebida (incoming)

```json
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "alias_key": "c4332971-7cff-42eb-a117-7e6f0cd74db2",
  "end_to_end_id": "E18236120202308111235s14fddf2801",
  "pix_transfer_status": "received",
  "receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
  "transfer_amount": 126.97,
  "fee_amount": 0.0,
  "source_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "***02502000***",
    "owner_person_type": "legal",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502"
  },
  "pix_transfer_type": "reversal",
  "reversals": [],
  "original_outgoing_pix_transfer": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3"
}
```

Response Body: Transferência Rejeitada (incoming)

```json
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "alias_key": "c4332971-7cff-42eb-a117-7e6f0cd74db2",
  "end_to_end_id": "E18236120202308111235s14fddf2801",
  "pix_transfer_status": "rejected",
  "receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
  "transfer_amount": 126.97,
  "fee_amount": 0.0,
  "source_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "***02502000***",
    "owner_person_type": "legal",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502"
  },
  "pix_transfer_type": "dynamic_qr_code",
  "reversals": []
}
```

STATUS 4XX

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                          | Descrição (eng)<br/>`Description`                 | Descrição (ptbr)<br/>`translation`                                          |
|-------------|----------------------|---------------------------------------------|---------------------------------------------------|-----------------------------------------------------------------------------|
| 400         | PXT000075            | Pix Transfer Key or End To End Not Provided | No pix transfer key or end to end id provided.    | Não foram fornecidos uma pix transfer key ou end to end id.                 |
| 404         | PXT000023            | Outgoing PIX Transfer Not Found             | Pix transfer key \{pix_transfer_key\} was not found | Transferência PIX de saída com chave \{pix_transfer_key\} não foi encontrada. |
| 403         | PIT000001            | User is not allowed to do this transaction  | User is not allowed to do this transaction        | Usuário não tem autorização para fazer essa transação                       |

---

# Efetuar devolução de um Pix

URL: /documentation/pix_indireto/movimentacoes/devolucao_pix

A devolução de um Pix pode ser efetuada em até 90 dias a partir de seu recebimento.

## Request

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer/ PIX_TRANSFER_KEY /reversal
MÉTODO POST

### Request Path Params

| Campo              | Tipo   | Descrição                                                          | Caracteres |
|--------------------|--------|--------------------------------------------------------------------|------------|
| `account_key`      | string | Chave única da conta (UUIDv4)                                      | 36         |
| `alias_key`        | string | Chave única do alias (UUIDv4)                                      | 36         |
| `pix_transfer_key` | string | chave de identificação da transferência Pix no sistema QI (UUIDv4) | 36         |

Request Body

```json
{
  "request_control_key": "303393bf-8f2e-4ff0-b326-ee7ad612e8ca",
  "reversal_amount": 147.00,
  "reversal_reason": "client_request",
  "reversal_message": "Mensagem Pix da Devolução"
}
```

### Request Body

| Campo                  | Tipo   | Descrição                                 | Caracteres                                                    |
|------------------------|--------|-------------------------------------------|---------------------------------------------------------------|
| `request_control_key`* | string | Chave de unicidade da requisição (UUIDv4) | 36                                                            |
| `reversal_amount`*     | number | Valor da devolução                        | 11                                                            |
| `reversal_reason`*     | string | Motivo da devolução                       | **[Enumerador reversal_reason](#enumerador-reversal_reason)** |
| `reversal_message`     | string | Mensagem da devolução                     | 140                                                           |

### Enumerador reversal_reason

| Enumerador         | Descrição                                    |
|--------------------|----------------------------------------------|
| **client_request** | Caso tenha sido requerido pelo dono da conta |
| **reconciliation** | Para reconciliação devido a erro operacional |

## Response

### Response Body

| Campo                 | Tipo   | Descrição                                                                                   | Caracteres |
|-----------------------|--------|---------------------------------------------------------------------------------------------|------------|
| `reversal_status`     | string | Enumerador de status da transação de devolução. Pode ser 'pending', 'sent' e 'rejected'     | 36         |
| `transfer_amount`     | number | Valor da transferência de devolução                                                         | 11         |
| `pix_transfer_key`    | string | Chave da transação pix executada na devolução (UUIDv4)                                      | 36         |
| `end_to_end_id`       | string | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo) | 32         |
| `request_control_key` | string | Chave única de identificação da request utilizada pelo cliente (UUIDv4)                     | 36         |
| `created_at`          | string | Data e hora da devolução                                                                    | ---        |

STATUS 201 created

Response Body: Reversão Enviada

```json
{
  "reversal_status": "sent",
  "transfer_amount": 147.00,
  "pix_transfer_key": "cdcf0d25-08a1-46e3-902a-6d7ca75e6c48",
  "end_to_end_id": "E32402502202407112211Id9JbxoaiTf",
  "request_control_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
  "created_at": "2021-10-22T20:30:23.459Z"
}
```

STATUS 202

:::info Informação

Caso seja retornado uma `pix_transfer_status` no estado de **pending**, a solicitação de Pix não deve ser retentada.
Esta transferência será reprocessada. É necessário verificar o status da transferência por meio da consulta de
transferência pix.

:::

Response Body: Reversão Pendente

```json
{
  "reversal_status": "pending",
  "transfer_amount": 147.00,
  "pix_transfer_key": "cdcf0d25-08a1-46e3-902a-6d7ca75e6c48",
  "end_to_end_id": "E32402502202407112211Id9JbxoaiTf",
  "request_control_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
  "created_at": "2021-10-22T20:30:23.459Z"
}
```

STATUS 4XX

Response Body: Reversão Rejeitada

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {
    "pix_transfer_data": {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "end_to_end_id": "E32402502202407112211Id9JbxoaiTf",
      "pix_transfer_status": "rejected",
      "created_at": "2021-10-22T20:30:23.459Z"
    }
  }
}
```

STATUS 400

:::info Informação

Além dos erros discriminados abaixo, a devolução pix pode receber como erro os demais estabelecidos
em [Transação Pix](./transacao/transacao_pix_manual_sync)

:::

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                   | Descrição (eng)<br/>`Description`                                      | Descrição (ptbr)<br/>`translation`                                                        |
|-------------|----------------------|--------------------------------------|------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| 400         | QIT000001            | Bad Request                          | Schema Error                                                           | Erro de Schema                                                                            |
| 404         | PXT000018            | Reversal Original Transfer not Found | Reversal original pix transfer not found.                              | Transferência original da devolução não foi encontrada.                                   |
| 400         | PXT000017            | Reversal Too Great                   | Reversal transfers sum amount surpasses that of original pix transfer. | A soma das transferências de devolução ultrapassam o valor da transferência pix original. |
| 400         | PXT000015            | Reversal date expired                | Reversal original transaction is older than 90 days                    | A data de criação da transação original é mais antiga que 90 dias                         |
| 400         | PXT0000127           | Invalid Reversal Reason              | Reversal reason \{reversal_reason\} is not valid                       | Razão de reversão \{reversal_reason\} não é válida                                        |

---

# Introdução à movimentações no âmbito do PIX

URL: /documentation/pix_indireto/movimentacoes/introducao_movimentacoes

O cliente do Participante Indireto (Alias) pode solicitar diversas funcionalidades em relação à transações no âmbito do
PIX. Dentre elas, estão:

Transação PIX manual
Transação PIX por chave
Transação PIX QRCode
Devolução de um PIX

### Tipos de transferência Pix (pix_transfer_type)

| Enumerador          | Descrição                                                                                                                                                                                                                 |
|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **manual**          | Pix utilizando os dados da conta destino. Obrigatório enviar `target_account`                                                                                                                                             |
| **key**             | Pix utilizando uma chave pix. Obrigatório enviar `target_pix_key`. Recomendado enviar `end_to_end_id` da [consulta de chave](/documentation/pix_indireto/movimentacoes/consultar_chave_pix) pix caso tenha sido realizada |
| **static_qr_code**  | Pix utilizando um QR code estático. Obrigatório enviar o `end_to_end_id` retornado na [decodificação do QR code](/documentation/pix/decodificar_qr_code)                                                                  |
| **dynamic_qr_code** | Pix utilizando um QR code dinâmico. Obrigatório enviar o `end_to_end_id` retornado na [decodificação do QR code](/documentation/pix/decodificar_qr_code)                                                                  |
| **reversal**        | Devolução de um Pix                                                                                                                                                                                                       |

Dentre estas funcionalidades, há o tipo de 'sincronicidade' de transação que um Participante Indireto pode optar por
fazer, de acordo com suas necessidades.

:::info Informação

Tudo o descrito nesta seção de introdução também está, de forma detalhada como o Participante Indireto deve tratar via
API, na seções seguintes.

:::

## End to end ID

Toda transação pix possui um identificador único no banco central. End to End ID é o identificador fim-a-fim de uma
transferência pix. É utilizado para controle de rate-limiting no Banco Central.

![Fluxo End to End ID na consulta de chave Pix](/img/diagrams/pix-indireto-movimentacoes-introducao-movimentacoes.svg)

Cada cadastro de pessoa física ou jurídica possui um bucket para com o Banco Central. As requisições de consulta de
chave pix, consomem tokens desse bucket, que são recuperadas ao efetuar uma transação pix vinculada a uma consulta. O
vinculo entre uma consulta de chave pix e uma transação se dá por meio do End to End ID.

## Sincronicidade de uma movimentação

O Participante Indireto pode optar por realizar uma transação PIX de forma síncrona ou assíncrona. Em ambos os modos,
tem-se que a movimentação PIX será executada dentro do tempo estabelecido pelo Banco Central do Brasil.

:::info Informação

Nossa equipe configurará a o regime de sincronicidade a ser utilizado conforme acordado com o cliente.

:::

:::info Informação

Os endpoints, métodos, payloads e demais componentes da requisição são idênticos para o regime síncrono e assíncrono. A
diferença seria apenas que para o regime assíncrono, a resposta será sempre uma `pix_transfer` com status **pending**
caso tenha sido aprovada nas validações iniciais. Em seguida um webhook será enviado informando o status final da
transação (**sent** ou **rejected** ).

:::

## Retentativa de movimentações

Devido aos possíveis atrasos no sistema de mensageria no Banco Central do Brasil, em relação às movimentações PIX, a
QITech possui um mecanismo de retentativa das movimentações PIX, tanto para o modelo síncrono quanto assíncrono.

Caso este cenário aconteça, o Participante Indireto receberá um status HTTP 202, indicando que a transação foi enviada à
QITech e está pendente de confirmação por parte do Banco Central do Brasil. Assim que esta for retentada, o Participante
Indireto será informado, via webhook acerca da efetivação da transação.

---

# Simulação de cenários

URL: /documentation/pix_indireto/movimentacoes/simulacao

Passo a passo para simular a efetivação de ações feitas por agentes externos. Essas simulações inclúi transações de
entrada e devolução .

:::info Informação
Não há payload de retorno (response body) nessas requisições.
:::

## 1 - Simulação de entrada de PIX

### Request

ENDPOINT /mock/pix_transfer/incoming_pix_transfer
MÉTODO POST

Request Body

```json
{
  "target_account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "target_alias_key": "c4332971-7cff-42eb-a117-7e6f0cd74db2",
  "amount": 100.01
}

```

### Objeto Request Body

| Campo                   | Tipo   | Descrição                       | Máx. Caract. |
|-------------------------|--------|---------------------------------|--------------|
| **target_account_key*** | string | Chave única da conta de destino | 36           |
| **target_alias_key**    | string | Chave única do alias de destino | 36           |
| **amount***             | number | Valor da transação              | 6            |                        |

## 2 - Simulação de pagamento de PIX QR Code

### Request

ENDPOINT /mock/pix_transfer/incoming_pix_qrcode
MÉTODO POST

Request Body

```json
{
  "target_alias_key": "\<Chave única do alias de destino\>",
  "amount": "\<Valor da transação\>",
  "receiver_conciliation_id": "\<id do receiver conciliation do qr code\>"
}

```

### Objeto Request Body

| Campo                         | Tipo    | Descrição                                 | Máx. Caract. | Exemplo                                | Observação              |
|-------------------------------|---------|-------------------------------------------|--------------|----------------------------------------|-------------------------|
| **target_alias_key***         | string  | Chave única do alias de destino           | 36           | "41112f46-0034-4007-85687-5e592173db2" |                         |
| **amount***                   | decimal | Valor da transação                        | 6            | 1000.00                                | Valor máximo de 100.000 |                        |
| **receiver_conciliation_id*** | string  | id de conciliação do recebedor do qr code | 36           | 1000                                   |                         |                        |

## 3 - Simulação de devolução de PIX

Simula a devolução de uma transferência de saída Pix. Para isso o valor total das devoluções não deve exceder o valor da
transferência original. Para identificar a transação alvo, envie o `end_to_end_id` da transferência original.

### Request

ENDPOINT /mock/pix_transfer/reversal
MÉTODO POST

Request Body

```json
{
  "end_to_end_id": "E35713491202309182110sSCNh25ooX2",
  "amount": 100.00
}

```

### Objeto Request Body

| Campo              | Tipo   | Descrição                                   | Máx. Caract. |
|--------------------|--------|---------------------------------------------|--------------|
| **end_to_end_id*** | string | Chave unitária da transação a ser devolvida | 32           |
| **amount***        | number | Valor a ser devolvido                       | 6            |                     |

## 4 - Simulação de transação em estado pendente de confirmação

Transações pix podem entrar em status **pending_confirmation** quando ocorre alguma demora no retorno da resposta da
transação Pix pelo Banco Central. Para simular este cenário, realize uma transação com a chave
pix `"target_pix_key": "0476f803-0129-430a-a66c-d2f0d7cf4aaa"` ou, para transferências pix do tipo **manual**,
utilize `"owner_document_number": "35586870002"` como número de documento do proprietário da conta de destino.

Para que o status da transação seja atualizado, realize a requisição abaixo com `transaction_status` de **sent** para
aprovar a transação, ou **rejected** para reprová-la.

### Request

ENDPOINT /mock/pix_transfer/pending_confirmation
MÉTODO POST

Request Body

```json
{
  "end_to_end_id": "E32402502202308181802vSHbiqNCk9i",
  "transaction_status": "rejected",
  "status_reason_information": {
    "error_description": "description",
    "error_translation": "translation",
    "error_short_description": "short_description"
  },
  "error_code": "test_error"
}
```

### Body Parameters

| Campo                       | Tipo   | Descrição                                                             | Máx. Caract. |
|-----------------------------|--------|-----------------------------------------------------------------------|--------------|
| `end_to_end_id`*            | string | Chave unitária da transação PIX                                       | 36           |
| `transaction_status`*       | enum   | [Enumerador Transaction Status](#enumerador-transaction-status)       |
| `status_reason_information` | objeto | [Objeto Status Reason Information](#objeto-status-reason-information) |
| `error_code`                | string | Código de erro                                                        |

### Enumerador Transaction Status

| Enumerador   | Descrição |
|--------------|-----------|
| **sent**     | Concluído |
| **rejected** | Rejeitado |

### Objeto Status Reason Information

| Campo                     | Tipo   | Descrição                         | Máx. Caract. |
|---------------------------|--------|-----------------------------------|--------------|
| `error_description`       | string | Descrição do erro em inglês       | 100          |
| `error_translation`       | string | Descrição do erro em português    | 100          |
| `error_short_description` | string | Descrição curta do erro em inglês | 100          |

## 5 - Simulação de transação rejeitada

Transações pix podem entrar em status **rejected** quando ocorre algum retorno esperado de recusa da
transação Pix pelo Banco Central ou PSP recebedor. Para simular este cenário, realize uma transação com a chave
pix `"target_pix_key": "b9380607-dac6-4e17-8ca7-eb761e3aa1dc"` ou, para transferências pix do tipo **manual**,
utilize `"owner_document_number": "66972913039"` ou `"owner_document_number": "50305556000164"` como número de documento do proprietário da conta de destino.

---

# Efetuar Transferencia Assíncrona para Pix Manual

URL: /documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_manual

## Request Manual

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer
MÉTODO POST

Request Body

```json

{
    "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
    "pix_transfer_type": "manual",
    "target_account": {
      "account_branch": "0001",
      "account_digit": "1",
      "account_number": "2983779",
      "account_type": "checking_account",
      "ispb": "99999004",
      "owner_document_number": "36188081866",
      "owner_name": "USER PF LIMIT LEDGER",
      "owner_person_type": "natural"
    },
    "pix_message": "Bom dia", 
    "transaction_amount": 500.00,
    "schedule_date": "2021-08-04"
}

```

### Body Param

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `request_control_key` *| uuidv4 | UUID4 para fins de consulta sobre a requisição feita. | 36 |
| `pix_transfer_type` * | string | O Pix possui diferentes tipos de iniciação, o "manual" onde o usuário deve enviar os campos da conta de destino e conta de origem e o "key" onde o usuário deve enviar os campos da chave Pix do recebedor (conta de destino) e os dados da conta de origem. | 6 |
| `target_account` *| Object | Conta destino - Só deve ser enviada em transações do tipo "manual". | **[Objeto target_account](#objeto-target_account)** |
| `pix_message`  | string | Mensagem opcional que acompanhará o Pix | 140 |
| `transaction_amount` * | float | Valor da transação realizada | 20 |
| `schedule_date` | date | Data de agendamento da transação (caso não seja enviado a transferência é realizada no momento da aprovação). | 10 |

### Objeto target_account

| Campo | Tipo | Descrição | Caracteres |
|-------|------|-----------|------------|
| `account_branch` * | string | Agência.   | 4 |
| `account_digit` * | string | Dígito da conta  | 1 |
| `account_number` *  | string | Número da conta.  | 8 |
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta.| 14 |
| `owner_name` * | string | Nome do titular da conta. | 120 |
| `account_type` * | string | Tipo de conta, podendo ser `checking_account`, `deposit_account`, `guaranteed_account`, `investment_account`, `saving_account` | 20 |
| `owner_trading_name` | string | Nome fantasia para pessoa jurídica. Usado somente para CNPJ| 10 |
| `ispb` *| string | Código de oito dígitos que identifica os bancos no sistema de transferência de reserva do Banco Central. | 8 |

:::info HTTP Status 202 Accepted
No pix assíncrono, toda transação retorna **http status 202 Accepted**, a solicitação de Pix **não deve ser retentada**. Neste cenário, a transação será efetuada oportunamente e será atualizada por meio do [Webhook de Atualização de Transação](/documentation/pix_indireto/movimentacoes/webhook/webhook_transacao).
É possível ainda consultar o status da transação por meio do endpoint [/account/ACCOUNT_KEY/alias/ALIAS_KEY/pix_transfer/PIX_TRANSFER_KEY](/documentation/pix_indireto/movimentacoes/consultar_pix).
:::

## Response

STATUS 202 Accepted

Response Body: Transferência manual

```json
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "pix_transfer_status": "pending_confirmation",
  "created_at": "2021-10-22T20:30:23.459Z"
}

```

STATUS 400

Response Body

```json
{
  "data": {
    "title": "Bad Request",
    "description": "Invalid request body.",
    "translation": "Corpo da requisição inválido.",
    "extra_fields": {},
    "code": "LEG000069"
  }
}

```

---

# Efetuar Transferencia Assíncrona via Chave Pix

URL: /documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_normal

## Request Normal

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer
MÉTODO POST

Request Body

```json
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "pix_transfer_type": "key",
  "target_pix_key": "pix@qitech.com.br",
  "pix_message": "Bom dia", 
  "transaction_amount": 500.00,
  "end_to_end_id": "E3240250220211022203051750897529",
  "schedule_date": "2021-08-04"
}

```

### Request Path Params

| Campo               | Tipo   | Descrição             | Caracteres |
|---------------------|--------|-----------------------|------------|
| `account_key`       | uuidv4 | Chave única da conta. | 36         |
| `alias_key` | uuidv4 | Chave única do alias. | 36         |

### Body Param

|  Campo  | Tipo | Descrição | Max. Caracteres |
|---------|------|-----------|------------|
| `request_control_key` *| uuidv4 | UUID4 para fins de consulta sobre a requisição feita. | 36 |
| `pix_transfer_type` * | string | O Pix possui diferentes tipos de iniciação, o "manual" onde o usuário deve enviar os campos da conta de destino e conta de origem e o "key" onde o usuário deve enviar os campos da chave Pix do recebedor (conta de destino) e os dados da conta de origem. | 6 |
| `transfer_time` * | string | Informação de sincronicidade da trasação, utilizada para definir quando a transação será processada. Caso seja "synchronous", a transação sera efetuada imediatamente, porém respeitando-se um limite maximo de transações por minuto. Ja se for "asynchronous", a transação será processada em um  | 200 |
| `target_pix_key` * | string | Chave Pix que irá receber a transação. | 200 |
| `pix_message` *  | string | Mensagem opcional que acompanhará o Pix | 140 |
| `transaction_amount` * | float | Valor da transação realizada | 20 |
| `end_to_end_id` | string | chave de identificação única de uma transação ou consulta no Banco Central. Exemplo: E3240250220210615135810450327042 | 32 |
| `schedule_date` | date | Data de agendamento da transação (caso não seja enviado a transferência é realizada no momento da aprovação). | 10 |

:::info HTTP Status 202 Accepted
No pix assíncrono, toda transação retorna **http status 202 Accepted**, a solicitação de Pix **não deve ser retentada**. Neste cenário, a transação será efetuada oportunamente e será atualizada por meio do [Webhook de Atualização de Transação](/documentation/pix_indireto/movimentacoes/webhook/webhook_transacao).
É possível ainda consultar o status da transação por meio do endpoint [/account/ACCOUNT_KEY/alias/ALIAS_KEY/pix_transfer/PIX_TRANSFER_KEY](/documentation/pix_indireto/movimentacoes/consultar_pix).
:::
## Response

STATUS 202 Accepted

Response Body

```json
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "pix_transfer_status": "pending_confirmation",
  "created_at": "2021-10-22T20:30:23.459Z"
}

```

STATUS 400

Response Body: Invalid Request Body

```json
{
  "data": {
    "title": "Bad Request",
    "description": "Invalid request body.",
    "translation": "Corpo da requisição inválido.",
    "extra_fields": {},
    "code": "LEG000069"
  }
}

```

---

# Efetuar Transferencia Assíncrona para Pix Qr Code

URL: /documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_qr_code

## Request Qr Code 

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer
MÉTODO POST

Request Body

```json
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "pix_transfer_type": "qr_code",
  "target_pix_key": "pix@qitech.com.br",
  "pix_message": "Bom dia", 
  "transaction_amount": 500.00,
  "end_to_end_id": "E3240250220211022203051750897529",
  "schedule_date": "2021-08-04",
  "receiver_conciliation_id": "REC00000000000000000000009459463343"
}
```

### Body Param

|  Campo  | Tipo | Descrição | Max. Caracteres |
|---------|------|-----------|------------|
| `request_control_key` *| uuidv4 | UUID4 para fins de consulta sobre a requisição feita. | 36 |
| `pix_transfer_type` * | string | O Pix possui diferentes tipos de iniciação, o "manual" onde o usuário deve enviar os campos da conta de destino e conta de origem e o "key" onde o usuário deve enviar os campos da chave Pix do recebedor (conta de destino) e os dados da conta de origem. | 6 |
| `target_pix_key` * | string | Chave Pix que irá receber a transação. | 200 |
| `pix_message`  | string | Mensagem opcional que acompanhará o Pix | 140 |
| `transaction_amount` * | float | Valor da transação realizada | 20 |
| `end_to_end_id` | string | chave de identificação única de uma transação ou consulta no Banco Central. Exemplo: E3240250220210615135810450327042 | 32 |
| `schedule_date` | date | Data de agendamento da transação (caso não seja enviado a transferência é realizada no momento da aprovação). | 10 |
| `receiver_conciliation_id` * | string | Identicação de conciliação do recebedor. Gerada ao decodar um Qr Code  | 10 |

:::info HTTP Status 202 Accepted
No pix assíncrono, toda transação retorna **http status 202 Accepted**, a solicitação de Pix **não deve ser retentada**. Neste cenário, a transação será efetuada oportunamente e será atualizada por meio do [Webhook de Atualização de Transação](/documentation/pix_indireto/movimentacoes/webhook/webhook_transacao).
É possível ainda consultar o status da transação por meio do endpoint [/account/ACCOUNT_KEY/alias/ALIAS_KEY/pix_transfer/PIX_TRANSFER_KEY](/documentation/pix_indireto/movimentacoes/consultar_pix).
:::

## Response

STATUS 202 Accepted

Response Body

```json
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "pix_transfer_status": "pending_confirmation",
  "created_at": "2021-10-22T20:30:23.459Z"
}

```

STATUS 400

Response Body: Invalid Request Body

```json
{
  "data": {
    "title": "Bad Request",
    "description": "Invalid request body.",
    "translation": "Corpo da requisição inválido.",
    "extra_fields": {},
    "code": "LEG000069"
  }
}

```

STATUS 202

Response Body: Pending Transfer

```json
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "pix_transfer_status": "pending_confirmation",
  "created_at": "2021-10-22T20:30:23.459Z"
}
```

:::danger HTTP Status 202
Caso seja retornado **http status 202**, a solicitação de Pix **não deve ser retentada**. É preciso checar o status da solicitação de transferência Pix através de um GET na rota [/baas/pix/pix_transfer](/documentation/pix/pesquisar_por_transferencia_pix_de_saida).
:::

---

# Transação Pix por Chave Pix

URL: /documentation/pix_indireto/movimentacoes/transacao/transacao_pix_chave_sync

## Request Manual

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer
MÉTODO POST

Request Body

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_type": "key",
  "target_pix_key": "target_pix_key@email.com",
  "transaction_amount": 500.65,
  "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
  "pix_message": "Ola Mundo"
}

```

### Body Params

| Campo                   | Tipo       | Descrição                                                                                             | Caracteres |
|-------------------------|------------|-------------------------------------------------------------------------------------------------------|------------|
| `request_control_key` * | string     | Chave única de identificação da request utilizada pelo cliente no formato uuid v4                     | 36         | 
| `pix_transfer_type` *   | enumerador | Tipo do pix a ser realizado. Para o caso de transferência por chave deve ser **key**                  | "key"      |
| `target_pix_key` *      | string     | Chave pix da conta a ser enviada a transação                                                          | 100        |
| `transaction_amount` *  | number     | Valor da transferencia                                                                                | 10         |
| `end_to_end_id` *       | string     | Chave de idempotência de uma transação Pix - só deve ser enviado se o tipo de transferência for "key" | 32         |
| `pix_message`           | string     | Mensagem a ser enviada junto à transferência Pix                                                      | 140        |

:::info Aviso
Um `end_to_end_id` deve ser enviado referente
á [consulta de chave](/documentation/pix_indireto/movimentacoes/consultar_chave_pix).
:::

:::danger Aviso
O `end_to_end_id` da consulta deve ter sido feito em nome do alias que solicitará a movimentação!
:::

:::danger Aviso
Um `end_to_end_id` só pode ser utilizado para uma única transferência, não importando se tenha sido bem sucedida ou não.
:::

## Response

STATUS 201

Response Body: Transferência Enviada

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "alias_key": "68908c98-59cb-4fbf-9321-5d223ec78376",
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "pix_transfer_status": "sent",
  "created_at": "2021-10-22T20:30:23.459Z"
}
```

STATUS 202

:::info Informação

Caso seja retornado uma `pix_transfer_status` no estado de **pending**, a solicitação de Pix não deve ser retentada.
Esta transferência será reprocessada. É necessário verificar o status da transferência por meio da consulta de
transferência pix.

:::

Response Body: Transferência Pendente

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "alias_key": "68908c98-59cb-4fbf-9321-5d223ec78376",
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "pix_transfer_status": "pending",
  "created_at": "2021-10-22T20:30:23.459Z"
}
```

STATUS 4XX

Response Body: Transferência Rejeitada

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {
    "pix_transfer_data": {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "alias_key": "68908c98-59cb-4fbf-9321-5d223ec78376",
      "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "pix_transfer_status": "rejected",
      "created_at": "2021-10-22T20:30:23.459Z"
    }
  }
}
```

STATUS 4XX

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`Description`                                                                                       | Descrição (ptbr)<br/>`translation`                                                                                     |
|-------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400         | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Erro de Schema                                                                                                         |
| 406         | PXT000103            | request_control_key must be a valid uuid v4 string | request_control_key was not accepted for not being a valid uuid v4 string                                               | request_control_key não foi aceito por não ser uma palavra uuid v4 válida                                              |
| 400         | PXT000048            | Bad Request                                        | Emoji not allowed in pix message.                                                                                       | Emoji não é permitido na mensagem pix.                                                                                 |
| 400         | PXT000104            | Invalid Transaction Amount                         | Transaction amount of \{transaction_amount\} is not valid. It must be a positive value with at maximum 2 decimal places | O valor de transação \{transaction_amount\} não é válido. Deve ser um valor positivo com no máximo duas casas decimais |
| 404         | PXT000004            | Account not found                                  | Account not found for: \{account_datum\}                                                                                | Conta não encontrada para: \{account_datum\}                                                                           |
| 400         | PXT000003            | Account is Closed                                  | Account \{account_key\} is closed.                                                                                      | Conta \{account_key\} está fechada.                                                                                    |
| 422         | PXT000092            | Invalid Account Type                               | Pix is not yet implemented for non-checking or non-escrow account types                                                 | Transações Pix não estão implementadas para conta que não sejam escrow ou livres                                       |
| 403         | PIT000001            | User is not allowed to do this transaction         |                                                                                                                         | Usuário não tem autorização para fazer essa transação                                                                  |
| 400         | PXT000010            | Account is Blocked                                 | Account \{account_key\} is blocked.                                                                                     | Conta \{account_key\} está bloqueada.                                                                                  |
| 400         | PXT000003            | Account is Closed                                  | Account \{account_key\} is closed.                                                                                      | Conta \{account_key\} está fechada.                                                                                    |
| 400         | PIT000003            | Bad Request                                        | Insufficient account balance for transfer and fee amount.                                                               | Saldo de conta insuficiente para a transferência e a taxa.                                                             |
| 400         | PXT000118            | Requester is not Pix Participant                   | The requester sent an alias key but is not a indirect pix participant                                                   | O requisitante enviou uma alias key no entanto não é um participante do pix indireto                                   |
| 404         | PXT000120            | Alias sent not found                               | Alias key attached to this account not found                                                                            | Alias key vinculada à conta não encontrada                                                                             |
| 406         | PXT000105            | Invalid end_to_end_id                              | The end_to_end_id sent \{end_to_end_id\} is not valid.                                                                  | O end_to_end_id enviado \{end_to_end_id\} não é válido.                                                                |
| 400         | PXT000108            | Bad Request                                        | Billing account closed or blocked                                                                                       | Conta de cobrança encerrada ou bloqueada                                                                               |
| 400         | PXT000079            | Bad Request                                        | Insufficient billing account balance for fee.                                                                           | Saldo de conta de cobrança insuficiente para a taxa.                                                                   |
| 400         | PIT000004            | Bad Request                                        | Transaction amount is over limit.                                                                                       | O total da transferência é superior ao limite.                                                                         |
| 404         | PIX000056            | Not Found                                          | Pix key inquiry not found                                                                                               | Consulta de chave pix não encontrada                                                                                   |
| 404         | PXT000041            | Not Found                                          | Qr Code not found                                                                                                       | Qr Code não encontrado                                                                                                 |
| 400         | PXT000053            | Bad Request                                        | QrCode already paid                                                                                                     | Qr Code já Pago                                                                                                        |
| 400         | PXT000118            | Requester is not Pix Participant                   | The requester sent an alias key but is not a indirect pix participant                                                   | O requisitante enviou uma alias key no entanto não é um participante do pix indireto                                   |
| 404         | PXT000120            | Alias sent not found                               | Alias key attached to this account not found                                                                            | Alias key vinculada à conta não encontrada                                                                             |
| 400         | PXT000115            | Bad Request                                        | Insufficient account balance for transfer and fee amount.                                                               | Saldo de conta insuficiente para a transferência e a taxa                                                              |
| 400         | PXT000128            | Bad Request                                        | Pix key \{pix_key\} sent does match inquiry pix key. Verify if end_to_end_id sent is correct                            | Chave Pix \{pix_key\} enviada não condiz com consulta. Verifique se end_to_end_id enviado está correto                 |
| 400         | PXT000109            | Bad Request                                        | request_control_key \{request_control_key\} already in use                                                              | request_control_key \{request_control_key\} já utilizada                                                               |
| 400         | PXT000061            | Bad Request                                        | End to end id invalid. A pix transfer with the end to end id \{end_to_end\} has already been registered!                | End to end id inválido. Uma transação pix com o identificador único \{end_to_end\} já foi registrada!                  |
| 400         | PXT000129            | SPI Error message                                  | Message rejected by SPI-ICOM                                                                                            | Mensagem rejeitada pela SPI-ICOM                                                                                       |
| 408         | PXT000130            | SPI Timeout Control                                | SPI Timeout Control                                                                                                     | Controle de timeout no SPI                                                                                             |
| 400         | PXT000131            | Receiver Internal Error                            | Cancelled transaction due to receiver's internal error                                                                  | Transação interrompida devido a erro no PSP do Recebedor                                                               |
| 400         | PXT000132            | Invalid Target Account Number                      | Target account number is invalid                                                                                        | Número da conta de destino é inexistente ou inválido                                                                   |
| 400         | PXT000133            | Blocked Target Account                             | Target account is blocked.                                                                                              | A conta de destino encontra-se bloqueada.                                                                              |
| 400         | PXT000134            | Closed Target Account                              | Target account is closed.                                                                                               | A conta de destino encontra-se encerrada.                                                                              |
| 400         | PXT000135            | Unsupported Transaction                            | Unsupported transaction for given target account.                                                                       | A conta de destino não suporta este tipo de transação.                                                                 |
| 400         | PXT000136            | Invalid Participant                                | SPI participant is not PSP settler agent of payer nor receiver.                                                         | Participante direto do SPI não é liquidante do PSP do Pagador / Recebedor.                                             |
| 400         | PXT000137            | Zero Value Payment Order                           | Zero value payment order.                                                                                               | Ordem de pagamento com valor zero.                                                                                     |
| 400         | PXT000138            | Insufficient Funds                                 | Insufficient funds in PI account from payer.                                                                            | Saldo insuficiente na conta PI do pagador.                                                                             |
| 400         | PXT000139            | Return Value Too Great                             | Return value greater than corresponding payment order.                                                                  | Valor de devolução acima do valor de pagamento correspondente.                                                         |
| 400         | PXT000140            | Invalid Transactions Number                        | Invalid transactions number.                                                                                            | Quantidade de transações inválida.                                                                                     |
| 400         | PXT000141            | Unrelated Beneficiary Document Number              | Beneficiary document number is not that of target account owner.                                                        | CPF/CNPJ do usuário recebedor não é compatível com o titular da conta de destino.                                      |
| 400         | PXT000142            | Invalid Beneficiary Document Number                | Invalid beneficiary document number                                                                                     | CPF/CNPJ da conta de destino está incorreto.                                                                           |
| 400         | PXT000143            | Incorrect Message Element                          | Incorrect message element.                                                                                              | Elemento da mensagem incorreto.                                                                                        |
| 403         | PXT000144            | Rejected Payment Order                             | Beneficiary's PSP has rejected payment order.                                                                           | Ordem de pagamento foi rejeitada pelo banco recebedor.                                                                 |
| 403         | PXT000145            | Unauthorized Payer                                 | Signing participant is unauthorized to make a payment order for paying account.                                         | Participante que assinou a mensagem não é autorizado a realizar a operação na conta PI debitada.                       |
| 400         | PXT000146            | Invalid Datetime                                   | Invalid datetime for message delivery.                                                                                  | Data e Hora do envio da mensagem inválida.                                                                             |
| 400         | PXT000147            | Generic Error                                      | Error while processing payment (generic error).                                                                         | Erro no processamento do pagamento (erro genérico).                                                                    |
| 400         | PXT000148            | Bad Format Operation Identifier                    | Badly formatted operation's identifier.                                                                                 | Identificador da operação mal formatado.                                                                               |
| 400         | PXT000149            | Invalid Payer ISPB                                 | Invalid or non-existent payer's PSP ISPB number.                                                                        | Número ISPB do PSP do Pagador é inválido ou inexistente.                                                               |
| 400         | PXT000150            | Invalid Beneficiary ISPB                           | Invalid or non-existent beneficiary's PSP ISPB number.                                                                  | Número ISPB do banco recebedor é inválido ou inexistente.                                                              |
| 400         | PXT000151            | Incorrect Type                                     | Incorrect type for target account.                                                                                      | Tipo incorreto para a conta transacional especificada.                                                                 |
| 400         | PXT000152            | Repeated End-to-End ID Error                       | The end_to_end_id was already used                                                                                      | O end_to_end_id já foi utilizado                                                                                       |
| 400         | PXT000153            | Invalid Target Account Type                        | The target account type cannot receive PIX transactions                                                                 | O tipo de conta destino não pode receber transações PIX                                                                |
| 400         | PXT000154            | Invalid ISPB                                       | Invalid or non-existent ISPB number.                                                                                    | Número ISPB é inválido ou inexistente.                                                                                 |
| 400         | PXT000155            | Amount too Great                                   | Amount too great for credited account.                                                                                  | Valor de pagamento/devolução acima do permitido para a conta de destino creditada.                                     |
| 400         | PXT000156            | QR Code Rejected                                   | QR Code rejected by beneficiary's PSP.                                                                                  | QR Code rejeitado pelo PSP do usuário recebedor.                                                                       |
| 503         | PXT000157            | Bacen Service Unavailable Error                    | Could not send the message to ICOM after 3 retries                                                                      | Não pode enviar a mensagem para a ICOM depois de 3 tentativas                                                          |
| 400         | PXT000158            | Invalid Amount                                     | Paid amount diverges from expected amount of \{expected_amount\}                                                        | O valor do pagamento diverge do valor esperado de \{expected_amount\}                                                  |
| 400         | PXT000159            | QR code inactive                                   | QR code is not active at the time of payment                                                                            | QR code não está ativo no instante do pagamento                                                                        |

---

# Transação Pix Manual

URL: /documentation/pix_indireto/movimentacoes/transacao/transacao_pix_manual_sync

## Request Manual

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer
MÉTODO POST

Request Body

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_type": "manual",
  "target_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "32402502000135",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502"
  },
  "transaction_amount": 500.65,
  "pix_message": "Ola Mundo"
}

```

### Body Params

| Campo                   | Tipo       | Descrição                                                                            | Caracteres                                          |
|-------------------------|------------|--------------------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | string     | Chave única de identificação da request utilizada pelo cliente no formato uuid v4    | 36                                                  | 
| `pix_transfer_type` *   | enumerador | Tipo do pix a ser realizado. Para o caso de transferência manual deve ser **manual** | "manual"                                            |
| `target_account` *      | Object     | Conta destino - Só deve ser enviada em transações do tipo "manual"                   | **[Objeto target_account](#objeto-target_account)** | 10 |
| `transaction_amount` *  | number     | Valor da transferencia                                                               | 10                                                  |
| `pix_message`           | string     | Mensagem a ser enviada junto à transferência Pix                                     | 140                                                 |

:::warning Aviso
Um `end_to_end_id` só pode ser utilizado para uma única transferência, não importando se tenha sido bem sucedida ou não.
:::

### Objeto target_account

| Campo                     | Tipo       | Descrição                                                                                               | Caracteres                                              |
|---------------------------|------------|---------------------------------------------------------------------------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string     | Agência da conta                                                                                        | 6                                                       |
| `account_digit` *         | string     | Dígito da conta                                                                                         | 1                                                       |
| `account_number` *        | string     | Número da conta                                                                                         | 20                                                      |
| `owner_document_number` * | string     | CPF ou CNPJ (apenas números) do titular da conta                                                        | 14                                                      |
| `owner_name` *            | string     | Nome do titular da conta                                                                                | 150                                                     |
| `account_type`*           | enumerador | Tipo da conta                                                                                           | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string     | Código de oito dígitos que identifica os bancos no sistema de transferência de reserva do Banco Central | 8                                                       |

### Enumerador account_type

| Enumerador           | Descrição           |
|----------------------|---------------------|
| **checking_account** | Conta Corrente      |
| **salary_account**   | Conta Salário       |
| **saving_account**   | Conta Poupança      |
| **payment_account**  | Conta de Pagamentos |

## Response

STATUS 201

Response Body: Transferência Enviada

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "alias_key": "68908c98-59cb-4fbf-9321-5d223ec78376",
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "pix_transfer_status": "sent",
  "created_at": "2021-10-22T20:30:23.459Z"
}
```

STATUS 202

:::info Informação

Caso seja retornado uma `pix_transfer_status` no estado de **pending**, a solicitação de Pix não deve ser retentada.
Esta transferência será reprocessada. É necessário verificar o status da transferência por meio da consulta de
transferência pix.

:::

Response Body: Transferência Pendente

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "alias_key": "68908c98-59cb-4fbf-9321-5d223ec78376",
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "pix_transfer_status": "pending",
  "created_at": "2021-10-22T20:30:23.459Z"
}
```

STATUS 4XX

Response Body: Transferência Rejeitada

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {
    "pix_transfer_data": {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "alias_key": "68908c98-59cb-4fbf-9321-5d223ec78376",
      "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "pix_transfer_status": "rejected",
      "created_at": "2021-10-22T20:30:23.459Z"
    }
  }
}
```

STATUS 4XX

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`Description`                                                                                       | Descrição (ptbr)<br/>`translation`                                                                                     |
|-------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400         | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Erro de Schema                                                                                                         |
| 406         | PXT000103            | request_control_key must be a valid uuid v4 string | request_control_key was not accepted for not being a valid uuid v4 string                                               | request_control_key não foi aceito por não ser uma palavra uuid v4 válida                                              |
| 400         | PXT000048            | Bad Request                                        | Emoji not allowed in pix message.                                                                                       | Emoji não é permitido na mensagem pix.                                                                                 |
| 400         | PXT000104            | Invalid Transaction Amount                         | Transaction amount of \{transaction_amount\} is not valid. It must be a positive value with at maximum 2 decimal places | O valor de transação \{transaction_amount\} não é válido. Deve ser um valor positivo com no máximo duas casas decimais |
| 404         | PXT000004            | Account not found                                  | Account not found for: \{account_datum\}                                                                                | Conta não encontrada para: \{account_datum\}                                                                           |
| 400         | PXT000003            | Account is Closed                                  | Account \{account_key\} is closed.                                                                                      | Conta \{account_key\} está fechada.                                                                                    |
| 422         | PXT000092            | Invalid Account Type                               | Pix is not yet implemented for non-checking or non-escrow account types                                                 | Transações Pix não estão implementadas para conta que não sejam escrow ou livres                                       |
| 403         | PIT000001            | User is not allowed to do this transaction         |                                                                                                                         | Usuário não tem autorização para fazer essa transação                                                                  |
| 400         | PXT000010            | Account is Blocked                                 | Account \{account_key\} is blocked.                                                                                     | Conta \{account_key\} está bloqueada.                                                                                  |
| 400         | PXT000003            | Account is Closed                                  | Account \{account_key\} is closed.                                                                                      | Conta \{account_key\} está fechada.                                                                                    |
| 400         | PIT000003            | Bad Request                                        | Insufficient account balance for transfer and fee amount.                                                               | Saldo de conta insuficiente para a transferência e a taxa.                                                             |
| 400         | PXT000118            | Requester is not Pix Participant                   | The requester sent an alias key but is not a indirect pix participant                                                   | O requisitante enviou uma alias key no entanto não é um participante do pix indireto                                   |
| 404         | PXT000120            | Alias sent not found                               | Alias key attached to this account not found                                                                            | Alias key vinculada à conta não encontrada                                                                             |
| 406         | PXT000105            | Invalid end_to_end_id                              | The end_to_end_id sent \{end_to_end_id\} is not valid.                                                                  | O end_to_end_id enviado \{end_to_end_id\} não é válido.                                                                |
| 400         | PXT000108            | Bad Request                                        | Billing account closed or blocked                                                                                       | Conta de cobrança encerrada ou bloqueada                                                                               |
| 400         | PXT000079            | Bad Request                                        | Insufficient billing account balance for fee.                                                                           | Saldo de conta de cobrança insuficiente para a taxa.                                                                   |
| 400         | PIT000004            | Bad Request                                        | Transaction amount is over limit.                                                                                       | O total da transferência é superior ao limite.                                                                         |
| 404         | PIX000056            | Not Found                                          | Pix key inquiry not found                                                                                               | Consulta de chave pix não encontrada                                                                                   |
| 404         | PXT000041            | Not Found                                          | Qr Code not found                                                                                                       | Qr Code não encontrado                                                                                                 |
| 400         | PXT000053            | Bad Request                                        | QrCode already paid                                                                                                     | Qr Code já Pago                                                                                                        |
| 400         | PXT000118            | Requester is not Pix Participant                   | The requester sent an alias key but is not a indirect pix participant                                                   | O requisitante enviou uma alias key no entanto não é um participante do pix indireto                                   |
| 404         | PXT000120            | Alias sent not found                               | Alias key attached to this account not found                                                                            | Alias key vinculada à conta não encontrada                                                                             |
| 400         | PXT000115            | Bad Request                                        | Insufficient account balance for transfer and fee amount.                                                               | Saldo de conta insuficiente para a transferência e a taxa                                                              |
| 400         | PXT000128            | Bad Request                                        | Pix key \{pix_key\} sent does match inquiry pix key. Verify if end_to_end_id sent is correct                            | Chave Pix \{pix_key\} enviada não condiz com consulta. Verifique se end_to_end_id enviado está correto                 |
| 400         | PXT000109            | Bad Request                                        | request_control_key \{request_control_key\} already in use                                                              | request_control_key \{request_control_key\} já utilizada                                                               |
| 400         | PXT000061            | Bad Request                                        | End to end id invalid. A pix transfer with the end to end id \{end_to_end\} has already been registered!                | End to end id inválido. Uma transação pix com o identificador único \{end_to_end\} já foi registrada!                  |
| 400         | PXT000129            | SPI Error message                                  | Message rejected by SPI-ICOM                                                                                            | Mensagem rejeitada pela SPI-ICOM                                                                                       |
| 408         | PXT000130            | SPI Timeout Control                                | SPI Timeout Control                                                                                                     | Controle de timeout no SPI                                                                                             |
| 400         | PXT000131            | Receiver Internal Error                            | Cancelled transaction due to receiver's internal error                                                                  | Transação interrompida devido a erro no PSP do Recebedor                                                               |
| 400         | PXT000132            | Invalid Target Account Number                      | Target account number is invalid                                                                                        | Número da conta de destino é inexistente ou inválido                                                                   |
| 400         | PXT000133            | Blocked Target Account                             | Target account is blocked.                                                                                              | A conta de destino encontra-se bloqueada.                                                                              |
| 400         | PXT000134            | Closed Target Account                              | Target account is closed.                                                                                               | A conta de destino encontra-se encerrada.                                                                              |
| 400         | PXT000135            | Unsupported Transaction                            | Unsupported transaction for given target account.                                                                       | A conta de destino não suporta este tipo de transação.                                                                 |
| 400         | PXT000136            | Invalid Participant                                | SPI participant is not PSP settler agent of payer nor receiver.                                                         | Participante direto do SPI não é liquidante do PSP do Pagador / Recebedor.                                             |
| 400         | PXT000137            | Zero Value Payment Order                           | Zero value payment order.                                                                                               | Ordem de pagamento com valor zero.                                                                                     |
| 400         | PXT000138            | Insufficient Funds                                 | Insufficient funds in PI account from payer.                                                                            | Saldo insuficiente na conta PI do pagador.                                                                             |
| 400         | PXT000139            | Return Value Too Great                             | Return value greater than corresponding payment order.                                                                  | Valor de devolução acima do valor de pagamento correspondente.                                                         |
| 400         | PXT000140            | Invalid Transactions Number                        | Invalid transactions number.                                                                                            | Quantidade de transações inválida.                                                                                     |
| 400         | PXT000141            | Unrelated Beneficiary Document Number              | Beneficiary document number is not that of target account owner.                                                        | CPF/CNPJ do usuário recebedor não é compatível com o titular da conta de destino.                                      |
| 400         | PXT000142            | Invalid Beneficiary Document Number                | Invalid beneficiary document number                                                                                     | CPF/CNPJ da conta de destino está incorreto.                                                                           |
| 400         | PXT000143            | Incorrect Message Element                          | Incorrect message element.                                                                                              | Elemento da mensagem incorreto.                                                                                        |
| 403         | PXT000144            | Rejected Payment Order                             | Beneficiary's PSP has rejected payment order.                                                                           | Ordem de pagamento foi rejeitada pelo banco recebedor.                                                                 |
| 403         | PXT000145            | Unauthorized Payer                                 | Signing participant is unauthorized to make a payment order for paying account.                                         | Participante que assinou a mensagem não é autorizado a realizar a operação na conta PI debitada.                       |
| 400         | PXT000146            | Invalid Datetime                                   | Invalid datetime for message delivery.                                                                                  | Data e Hora do envio da mensagem inválida.                                                                             |
| 400         | PXT000147            | Generic Error                                      | Error while processing payment (generic error).                                                                         | Erro no processamento do pagamento (erro genérico).                                                                    |
| 400         | PXT000148            | Bad Format Operation Identifier                    | Badly formatted operation's identifier.                                                                                 | Identificador da operação mal formatado.                                                                               |
| 400         | PXT000149            | Invalid Payer ISPB                                 | Invalid or non-existent payer's PSP ISPB number.                                                                        | Número ISPB do PSP do Pagador é inválido ou inexistente.                                                               |
| 400         | PXT000150            | Invalid Beneficiary ISPB                           | Invalid or non-existent beneficiary's PSP ISPB number.                                                                  | Número ISPB do banco recebedor é inválido ou inexistente.                                                              |
| 400         | PXT000151            | Incorrect Type                                     | Incorrect type for target account.                                                                                      | Tipo incorreto para a conta transacional especificada.                                                                 |
| 400         | PXT000152            | Repeated End-to-End ID Error                       | The end_to_end_id was already used                                                                                      | O end_to_end_id já foi utilizado                                                                                       |
| 400         | PXT000153            | Invalid Target Account Type                        | The target account type cannot receive PIX transactions                                                                 | O tipo de conta destino não pode receber transações PIX                                                                |
| 400         | PXT000154            | Invalid ISPB                                       | Invalid or non-existent ISPB number.                                                                                    | Número ISPB é inválido ou inexistente.                                                                                 |
| 400         | PXT000155            | Amount too Great                                   | Amount too great for credited account.                                                                                  | Valor de pagamento/devolução acima do permitido para a conta de destino creditada.                                     |
| 400         | PXT000156            | QR Code Rejected                                   | QR Code rejected by beneficiary's PSP.                                                                                  | QR Code rejeitado pelo PSP do usuário recebedor.                                                                       |
| 503         | PXT000157            | Bacen Service Unavailable Error                    | Could not send the message to ICOM after 3 retries                                                                      | Não pode enviar a mensagem para a ICOM depois de 3 tentativas                                                          |
| 400         | PXT000158            | Invalid Amount                                     | Paid amount diverges from expected amount of \{expected_amount\}                                                        | O valor do pagamento diverge do valor esperado de \{expected_amount\}                                                  |
| 400         | PXT000159            | QR code inactive                                   | QR code is not active at the time of payment                                                                            | QR code não está ativo no instante do pagamento                                                                        |

---

# Transação Pix por QR Code

URL: /documentation/pix_indireto/movimentacoes/transacao/transacao_pix_qr_code_sync

## Request Manual

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /pix_transfer
MÉTODO POST

Request Body

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_type": "static_qr_code",
  "transaction_amount": 500.65,
  "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
  "receiver_conciliation_id": "REC00000000000000000000009459463343",
  "target_pix_key": "target_pix_key@email.com",
  "pix_message": "Ola Mundo"
}

```

### Body Params

| Campo                      | Tipo       | Descrição                                                                                                                | Caracteres                            |
|----------------------------|------------|--------------------------------------------------------------------------------------------------------------------------|---------------------------------------|
| `request_control_key` *    | string     | Chave única de identificação da request utilizada pelo cliente no formato uuid v4                                        | 36                                    | 
| `pix_transfer_type` *      | enumerador | Tipo do pix a ser realizado. Para o caso de transferência por QR code deve ser **static_qr_code** ou **dynamic_qr_code** | "static_qr_code" ou "dynamic_qr_code" |
| `target_pix_key` *         | string     | Chave pix da conta a ser enviada a transação                                                                             | 100                                   |
| `receiver_conciliation_id` | string     | Identicação de conciliação do recebedor                                                                                  | 35                                    |
| `transaction_amount` *     | number     | Valor da transferencia                                                                                                   | 10                                    |
| `end_to_end_id` *          | string     | Chave de idempotência de uma transação Pix - só deve ser enviado se o tipo de transferência for "key"                    | 32                                    |
| `pix_message`              | string     | Mensagem a ser enviada junto à transferência Pix                                                                         | 140                                   |

:::info Aviso
Um `end_to_end_id` deve ser enviado referente
á [decodificação do QR code](/documentation/pix/decodificar_qr_code).
:::

:::danger Aviso
O `end_to_end_id` da consulta deve ter sido feito em nome do alias que solicitará a movimentação!
:::

:::danger Aviso
Um `end_to_end_id` só pode ser utilizado para uma única transferência, não importando se tenha sido bem sucedida ou não.
:::

## Response

STATUS 201

Response Body: Transferência Enviada

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "alias_key": "68908c98-59cb-4fbf-9321-5d223ec78376",
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "pix_transfer_status": "sent",
  "created_at": "2021-10-22T20:30:23.459Z"
}
```

STATUS 202

:::info Informação

Caso seja retornado uma `pix_transfer_status` no estado de **pending**, a solicitação de Pix não deve ser retentada.
Esta transferência será reprocessada. É necessário verificar o status da transferência por meio da consulta de
transferência pix.

:::

Response Body: Transferência Pendente

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "alias_key": "68908c98-59cb-4fbf-9321-5d223ec78376",
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "pix_transfer_status": "pending",
  "created_at": "2021-10-22T20:30:23.459Z"
}
```

STATUS 4XX

Response Body: Transferência Rejeitada

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {
    "pix_transfer_data": {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "alias_key": "68908c98-59cb-4fbf-9321-5d223ec78376",
      "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "pix_transfer_status": "rejected",
      "created_at": "2021-10-22T20:30:23.459Z"
    }
  }
}
```

STATUS 4XX

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`Description`                                                                                       | Descrição (ptbr)<br/>`translation`                                                                                     |
|-------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400         | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Erro de Schema                                                                                                         |
| 406         | PXT000103            | request_control_key must be a valid uuid v4 string | request_control_key was not accepted for not being a valid uuid v4 string                                               | request_control_key não foi aceito por não ser uma palavra uuid v4 válida                                              |
| 400         | PXT000048            | Bad Request                                        | Emoji not allowed in pix message.                                                                                       | Emoji não é permitido na mensagem pix.                                                                                 |
| 400         | PXT000104            | Invalid Transaction Amount                         | Transaction amount of \{transaction_amount\} is not valid. It must be a positive value with at maximum 2 decimal places | O valor de transação \{transaction_amount\} não é válido. Deve ser um valor positivo com no máximo duas casas decimais |
| 404         | PXT000004            | Account not found                                  | Account not found for: \{account_datum\}                                                                                | Conta não encontrada para: \{account_datum\}                                                                           |
| 400         | PXT000003            | Account is Closed                                  | Account \{account_key\} is closed.                                                                                      | Conta \{account_key\} está fechada.                                                                                    |
| 422         | PXT000092            | Invalid Account Type                               | Pix is not yet implemented for non-checking or non-escrow account types                                                 | Transações Pix não estão implementadas para conta que não sejam escrow ou livres                                       |
| 403         | PIT000001            | User is not allowed to do this transaction         |                                                                                                                         | Usuário não tem autorização para fazer essa transação                                                                  |
| 400         | PXT000010            | Account is Blocked                                 | Account \{account_key\} is blocked.                                                                                     | Conta \{account_key\} está bloqueada.                                                                                  |
| 400         | PXT000003            | Account is Closed                                  | Account \{account_key\} is closed.                                                                                      | Conta \{account_key\} está fechada.                                                                                    |
| 400         | PIT000003            | Bad Request                                        | Insufficient account balance for transfer and fee amount.                                                               | Saldo de conta insuficiente para a transferência e a taxa.                                                             |
| 400         | PXT000118            | Requester is not Pix Participant                   | The requester sent an alias key but is not a indirect pix participant                                                   | O requisitante enviou uma alias key no entanto não é um participante do pix indireto                                   |
| 404         | PXT000120            | Alias sent not found                               | Alias key attached to this account not found                                                                            | Alias key vinculada à conta não encontrada                                                                             |
| 406         | PXT000105            | Invalid end_to_end_id                              | The end_to_end_id sent \{end_to_end_id\} is not valid.                                                                  | O end_to_end_id enviado \{end_to_end_id\} não é válido.                                                                |
| 400         | PXT000108            | Bad Request                                        | Billing account closed or blocked                                                                                       | Conta de cobrança encerrada ou bloqueada                                                                               |
| 400         | PXT000079            | Bad Request                                        | Insufficient billing account balance for fee.                                                                           | Saldo de conta de cobrança insuficiente para a taxa.                                                                   |
| 400         | PIT000004            | Bad Request                                        | Transaction amount is over limit.                                                                                       | O total da transferência é superior ao limite.                                                                         |
| 404         | PIX000056            | Not Found                                          | Pix key inquiry not found                                                                                               | Consulta de chave pix não encontrada                                                                                   |
| 404         | PXT000041            | Not Found                                          | Qr Code not found                                                                                                       | Qr Code não encontrado                                                                                                 |
| 400         | PXT000053            | Bad Request                                        | QrCode already paid                                                                                                     | Qr Code já Pago                                                                                                        |
| 400         | PXT000118            | Requester is not Pix Participant                   | The requester sent an alias key but is not a indirect pix participant                                                   | O requisitante enviou uma alias key no entanto não é um participante do pix indireto                                   |
| 404         | PXT000120            | Alias sent not found                               | Alias key attached to this account not found                                                                            | Alias key vinculada à conta não encontrada                                                                             |
| 400         | PXT000115            | Bad Request                                        | Insufficient account balance for transfer and fee amount.                                                               | Saldo de conta insuficiente para a transferência e a taxa                                                              |
| 400         | PXT000128            | Bad Request                                        | Pix key \{pix_key\} sent does match inquiry pix key. Verify if end_to_end_id sent is correct                            | Chave Pix \{pix_key\} enviada não condiz com consulta. Verifique se end_to_end_id enviado está correto                 |
| 400         | PXT000109            | Bad Request                                        | request_control_key \{request_control_key\} already in use                                                              | request_control_key \{request_control_key\} já utilizada                                                               |
| 400         | PXT000061            | Bad Request                                        | End to end id invalid. A pix transfer with the end to end id \{end_to_end\} has already been registered!                | End to end id inválido. Uma transação pix com o identificador único \{end_to_end\} já foi registrada!                  |
| 400         | PXT000129            | SPI Error message                                  | Message rejected by SPI-ICOM                                                                                            | Mensagem rejeitada pela SPI-ICOM                                                                                       |
| 408         | PXT000130            | SPI Timeout Control                                | SPI Timeout Control                                                                                                     | Controle de timeout no SPI                                                                                             |
| 400         | PXT000131            | Receiver Internal Error                            | Cancelled transaction due to receiver's internal error                                                                  | Transação interrompida devido a erro no PSP do Recebedor                                                               |
| 400         | PXT000132            | Invalid Target Account Number                      | Target account number is invalid                                                                                        | Número da conta de destino é inexistente ou inválido                                                                   |
| 400         | PXT000133            | Blocked Target Account                             | Target account is blocked.                                                                                              | A conta de destino encontra-se bloqueada.                                                                              |
| 400         | PXT000134            | Closed Target Account                              | Target account is closed.                                                                                               | A conta de destino encontra-se encerrada.                                                                              |
| 400         | PXT000135            | Unsupported Transaction                            | Unsupported transaction for given target account.                                                                       | A conta de destino não suporta este tipo de transação.                                                                 |
| 400         | PXT000136            | Invalid Participant                                | SPI participant is not PSP settler agent of payer nor receiver.                                                         | Participante direto do SPI não é liquidante do PSP do Pagador / Recebedor.                                             |
| 400         | PXT000137            | Zero Value Payment Order                           | Zero value payment order.                                                                                               | Ordem de pagamento com valor zero.                                                                                     |
| 400         | PXT000138            | Insufficient Funds                                 | Insufficient funds in PI account from payer.                                                                            | Saldo insuficiente na conta PI do pagador.                                                                             |
| 400         | PXT000139            | Return Value Too Great                             | Return value greater than corresponding payment order.                                                                  | Valor de devolução acima do valor de pagamento correspondente.                                                         |
| 400         | PXT000140            | Invalid Transactions Number                        | Invalid transactions number.                                                                                            | Quantidade de transações inválida.                                                                                     |
| 400         | PXT000141            | Unrelated Beneficiary Document Number              | Beneficiary document number is not that of target account owner.                                                        | CPF/CNPJ do usuário recebedor não é compatível com o titular da conta de destino.                                      |
| 400         | PXT000142            | Invalid Beneficiary Document Number                | Invalid beneficiary document number                                                                                     | CPF/CNPJ da conta de destino está incorreto.                                                                           |
| 400         | PXT000143            | Incorrect Message Element                          | Incorrect message element.                                                                                              | Elemento da mensagem incorreto.                                                                                        |
| 403         | PXT000144            | Rejected Payment Order                             | Beneficiary's PSP has rejected payment order.                                                                           | Ordem de pagamento foi rejeitada pelo banco recebedor.                                                                 |
| 403         | PXT000145            | Unauthorized Payer                                 | Signing participant is unauthorized to make a payment order for paying account.                                         | Participante que assinou a mensagem não é autorizado a realizar a operação na conta PI debitada.                       |
| 400         | PXT000146            | Invalid Datetime                                   | Invalid datetime for message delivery.                                                                                  | Data e Hora do envio da mensagem inválida.                                                                             |
| 400         | PXT000147            | Generic Error                                      | Error while processing payment (generic error).                                                                         | Erro no processamento do pagamento (erro genérico).                                                                    |
| 400         | PXT000148            | Bad Format Operation Identifier                    | Badly formatted operation's identifier.                                                                                 | Identificador da operação mal formatado.                                                                               |
| 400         | PXT000149            | Invalid Payer ISPB                                 | Invalid or non-existent payer's PSP ISPB number.                                                                        | Número ISPB do PSP do Pagador é inválido ou inexistente.                                                               |
| 400         | PXT000150            | Invalid Beneficiary ISPB                           | Invalid or non-existent beneficiary's PSP ISPB number.                                                                  | Número ISPB do banco recebedor é inválido ou inexistente.                                                              |
| 400         | PXT000151            | Incorrect Type                                     | Incorrect type for target account.                                                                                      | Tipo incorreto para a conta transacional especificada.                                                                 |
| 400         | PXT000152            | Repeated End-to-End ID Error                       | The end_to_end_id was already used                                                                                      | O end_to_end_id já foi utilizado                                                                                       |
| 400         | PXT000153            | Invalid Target Account Type                        | The target account type cannot receive PIX transactions                                                                 | O tipo de conta destino não pode receber transações PIX                                                                |
| 400         | PXT000154            | Invalid ISPB                                       | Invalid or non-existent ISPB number.                                                                                    | Número ISPB é inválido ou inexistente.                                                                                 |
| 400         | PXT000155            | Amount too Great                                   | Amount too great for credited account.                                                                                  | Valor de pagamento/devolução acima do permitido para a conta de destino creditada.                                     |
| 400         | PXT000156            | QR Code Rejected                                   | QR Code rejected by beneficiary's PSP.                                                                                  | QR Code rejeitado pelo PSP do usuário recebedor.                                                                       |
| 503         | PXT000157            | Bacen Service Unavailable Error                    | Could not send the message to ICOM after 3 retries                                                                      | Não pode enviar a mensagem para a ICOM depois de 3 tentativas                                                          |
| 400         | PXT000158            | Invalid Amount                                     | Paid amount diverges from expected amount of \{expected_amount\}                                                        | O valor do pagamento diverge do valor esperado de \{expected_amount\}                                                  |
| 400         | PXT000159            | QR code inactive                                   | QR code is not active at the time of payment                                                                            | QR code não está ativo no instante do pagamento                                                                        |

---

# Webhook para Devoluções de Pix

URL: /documentation/pix_indireto/movimentacoes/webhook/webhook_devolucao_outgoing_pix

Webhook que servirá para avisar sobre devoluções Pix que chegaram para um Alias.

## Webhook Request Body

**Request Body: Pix Recebido**

```json
{
  "webhook_type": "baas.pix_transfer.incoming_pix",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "end_to_end_id": "E18236120202308111235s14fddf2801",
    "pix_transfer_status": "received",
    "account_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
    "alias_key": "fc6862c4-2b20-4057-8063-b8809866e494",
    "receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
    "transfer_amount": 126.97,
    "fee_amount": 0.0,
    "source_account": {
      "account_branch": "0001",
      "account_digit": "3",
      "account_number": "12345678",
      "owner_document_number": "***02502000***",
      "owner_person_type": "legal",
      "owner_name": "Qi Tech",
      "account_type": "checking_account",
      "ispb": "32402502"
    },
    "pix_transfer_type": "reversal",
    "pix_message": "pix message received",
    "created_at": "2021-10-22T20:30:23.459Z",
    "reversals": [],
    "original_outgoing_pix_transfer": "b56862c4-2b20-4057-8063-b8809866e494"
  }
}
```

### Webhook Body Param

| Campo                            | Tipo       | Descrição                                                                                             | Max. Caracteres                                                   |
|----------------------------------|------------|-------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `webhook_type`                   | string     | Um enumerador que define o tipo de evento sendo reportado                                             | 23                                                                |
| `webhook_datetime`               | string     | Data e hora do envio do webhook                                                                       | 20                                                                |
| `pix_transfer_type`              | enumerador | Tipo do pix realizado                                                                                 | **[Enumerador pix_transfer_type](#enumerador-pix_transfer_type)** |
| `target_pix_key`                 | string     | Chave pix da conta a ser enviada a transação                                                          | 100                                                               |
| `source_account`                 | Object     | Conta destino - Só deve ser enviada em transações do tipo "manual"                                    | **[Objeto source_account](#objeto-source_account)**               |
| `transfer_amount`                | number     | Valor da transferencia                                                                                | 10                                                                |
| `receiver_conciliation_id`       | string     | Identicação de conciliação do recebedor                                                               | 35                                                                |
| `end_to_end_id`                  | string     | Chave de idempotência de uma transação Pix - só deve ser enviado se o tipo de transferência for "key" | 32                                                                |
| `pix_message`                    | string     | Mensagem a ser enviada junto à transferência Pix                                                      | 140                                                               |
| `fee_amount`                     | number     | Valor da transferencia                                                                                | 10                                                                |
| `pix_transfer_status`            | string     | Status da transação pix                                                                               | 10                                                                |
| `account_key`                    | string     | Chave única de identificação da conta QI                                                              | 36                                                                |
| `alias_key`                      | string     | Chave única do Alias                                                                                  | 36                                                                |
| `pix_transfer_key`               | string     | Chave única de identificação da transferência Pix                                                     | 36                                                                |
| `original_outgoing_pix_transfer` | string     | Chave única de identificação da transferência Pix de saída Original                                   | 36                                                                |

### Enumerador pix_transfer_type

| Enumerador          | Descrição                                |
|---------------------|------------------------------------------|
| **manual**          | Pix utilizando os dados da conta destino |
| **key**             | Pix utilizando uma chave pix             |
| **static_qr_code**  | Pix utilizando um QR code estático       |
| **dynamic_qr_code** | Pix utilizando um QR code dinâmico       |
| **reversal**        | Devolução Pix                            |

### Objeto source_account

| Campo                   | Tipo       | Descrição                                                                                               | Caracteres                                              |
|-------------------------|------------|---------------------------------------------------------------------------------------------------------|---------------------------------------------------------|
| `account_branch`        | string     | Agência da conta                                                                                        | 6                                                       |
| `account_digit`         | string     | Dígito da conta                                                                                         | 1                                                       |
| `account_number`        | string     | Número da conta                                                                                         | 20                                                      |
| `owner_document_number` | string     | CPF ou CNPJ (apenas números) do titular da conta                                                        | 14                                                      |
| `owner_name`            | string     | Nome do titular da conta                                                                                | 150                                                     |
| `account_type`          | enumerador | Tipo da conta                                                                                           | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb`                  | string     | Código de oito dígitos que identifica os bancos no sistema de transferência de reserva do Banco Central | 8                                                       |

### Enumerador account_type

| Enumerador           | Descrição           |
|----------------------|---------------------|
| **checking_account** | Conta Corrente      |
| **salary_account**   | Conta Salário       |
| **saving_account**   | Conta Poupança      |
| **payment_account**  | Conta de Pagamentos |

---

# Webhook para Pix de Entrada

URL: /documentation/pix_indireto/movimentacoes/webhook/webhook_incoming_pix

Webhook que servirá para avisar sobre transações Pix que chegaram para um Alias.

## Webhook Request Body

**Request Body: Pix Recebido**

```json
{
  "webhook_type": "baas.pix_transfer.incoming_pix",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "end_to_end_id": "E18236120202308111235s14fddf2801",
    "pix_transfer_status": "received",
    "account_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
    "alias_key": "fc6862c4-2b20-4057-8063-b8809866e494",
    "receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
    "transfer_amount": 126.97,
    "fee_amount": 0.0,
    "source_account": {
      "account_branch": "0001",
      "account_digit": "3",
      "account_number": "12345678",
      "owner_document_number": "***02502000***",
      "owner_person_type": "legal",
      "owner_name": "Qi Tech",
      "account_type": "checking_account",
      "ispb": "32402502"
    },
    "pix_transfer_type": "dynamic_qr_code",
    "pix_message": "pix message received",
    "created_at": "2021-10-22T20:30:23.459Z",
    "reversals": []
  }
}
```

### Webhook Body Param

| Campo                      | Tipo       | Descrição                                                                                             | Max. Caracteres                                                   |
|----------------------------|------------|-------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `webhook_type`             | string     | Um enumerador que define o tipo de evento sendo reportado                                             | 23                                                                |
| `webhook_datetime`         | string     | Data e hora do envio do webhook                                                                       | 20                                                                |
| `pix_transfer_type`        | enumerador | Tipo do pix realizado                                                                                 | **[Enumerador pix_transfer_type](#enumerador-pix_transfer_type)** |
| `target_pix_key`           | string     | Chave pix da conta a ser enviada a transação                                                          | 100                                                               |
| `source_account`           | Object     | Conta destino - Só deve ser enviada em transações do tipo "manual"                                    | **[Objeto source_account](#objeto-source_account)**               |
| `transfer_amount`          | number     | Valor da transferencia                                                                                | 10                                                                |
| `receiver_conciliation_id` | string     | Identicação de conciliação do recebedor                                                               | 35                                                                |
| `end_to_end_id`            | string     | Chave de idempotência de uma transação Pix - só deve ser enviado se o tipo de transferência for "key" | 32                                                                |
| `pix_message`              | string     | Mensagem a ser enviada junto à transferência Pix                                                      | 140                                                               |
| `fee_amount`               | number     | Valor da transferencia                                                                                | 10                                                                |
| `pix_transfer_status`      | string     | Status da transação pix                                                                               | 10                                                                |
| `account_key`              | string     | Chave única de identificação da conta QI                                                              | 36                                                                |
| `alias_key`                | string     | Chave única do Alias                                                                                  | 36                                                                |
| `pix_transfer_key`         | string     | Chave única de identificação da transferência Pix                                                     | 36                                                                |

### Enumerador pix_transfer_type

| Enumerador          | Descrição                                |
|---------------------|------------------------------------------|
| **manual**          | Pix utilizando os dados da conta destino |
| **key**             | Pix utilizando uma chave pix             |
| **static_qr_code**  | Pix utilizando um QR code estático       |
| **dynamic_qr_code** | Pix utilizando um QR code dinâmico       |
| **reversal**        | Devolução Pix                            |

### Objeto source_account

| Campo                     | Tipo       | Descrição                                                                                               | Caracteres                                              |
|---------------------------|------------|---------------------------------------------------------------------------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string     | Agência da conta                                                                                        | 6                                                       |
| `account_digit` *         | string     | Dígito da conta                                                                                         | 1                                                       |
| `account_number` *        | string     | Número da conta                                                                                         | 20                                                      |
| `owner_document_number` * | string     | CPF ou CNPJ (apenas números) do titular da conta                                                        | 14                                                      |
| `owner_name`              | string     | Nome do titular da conta                                                                                | 150                                                     |
| `account_type`*           | enumerador | Tipo da conta                                                                                           | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string     | Código de oito dígitos que identifica os bancos no sistema de transferência de reserva do Banco Central | 8                                                       |

### Enumerador account_type

| Enumerador           | Descrição           |
|----------------------|---------------------|
| **checking_account** | Conta Corrente      |
| **salary_account**   | Conta Salário       |
| **saving_account**   | Conta Poupança      |
| **payment_account**  | Conta de Pagamentos |

---

# Webhook para Transações Pendentes

URL: /documentation/pix_indireto/movimentacoes/webhook/webhook_transacao

Webhook que servirá para avisar sobre conclusão de transações que foram originalmente respondidas como pendentes (retornaram com http status 202).

## Webhook Request Body
**Request Body: Transação Enviada**

```json
{
  "webhook_type": "baas.pix_transfer.outgoing_pix",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "pix_transfer_status": "sent",
    "created_at": "2021-10-22T20:30:23.459Z"
  }
}
```

**Request Body: Transação Rejeitada**

```json
{
  "webhook_type": "baas.pix_transfer.outgoing_pix",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "pix_transfer_status": "rejected",
    "created_at": "2021-10-22T20:30:23.459Z",
    "error_code": "PXT000132",
    "error_description": "Target account number is invalid.",
    "error_translation": "Número da conta de destino é inexistente ou inválido.",
    "error_short_description": null
  }
}
```

### Webhook Body Param

|  Campo  | Tipo    | Descrição                                                 | Max. Caracteres |
|---------|---------|-----------------------------------------------------------|------------|
| `webhook_type` | string  | Um enumerador que define o tipo de evento sendo reportado | 23 |
| `webhook_datetime` | string  | Data e hora do envio do webhook                          | 20 |
| `request_control_key` | string  | UUID4 para fins de consulta sobre a requisição feita.     | 36 |
| `pix_transfer_key` | string  | Chave de identificação da transferência Pix no sistema QI | 36 |
| `pix_transfer_status` | string  | Status da transação.                                      | 200 |
| `created_at` | string  | Data e hora de criação da transação.                      | 20 |

---

# Cancelar um Pedido de Portabilidade

URL: /documentation/pix_indireto/portabilidade/cancelar_pedido_de_portabilidade

:::info
Cancelamentos de Pedido de Portabilidade podem ser realizados com as seguintes condições:

Status deve ser `waiting resolution`.

Se razão de cancelamento for `default`, prazo definido pelo campo `max_resolution_date` deve ter passado.
:::
A tabela abaixo define, a depender da razão, quem pode cancelar uma portabilidade.

| Razão             | Doador | Reivindicador |
| ----------------- | ------ | ------------- |
| `client_request`    | ✓      | ✓             |
| `account_closure`   | ✓      |               |
| `default` |        | ✓             |
| `fraud`             | ✓      | ✓             |

## Request

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /claim/ CLAIM_REQUEST_KEY
MÉTODO PATCH

**Request Body**

```json
{
    "request_control_key": "8a923886-afce-4116-ac1f-69bdffcf8da9",
    "claim_request_status": "cancelled",
    "cancellation_reason": "client_request",
}
```

| cancellation_reason | Descrição                                                                 |
| ------------------- |---------------------------------------------------------------------------|
| `client_request`    | O usuário reivindicador solicitou cancelamento do pedido de portabilidade |
| `account_closure`   | A conta foi encerrada durante o processo de portabilidade                 |
| `default` | O prazo de validação de posse da chave do usuário reivindicador expirou   |
| `fraud`             | Houve fraude na abertura do pedido de portabilidade                       |

## Response

STATUS 200

**Response Body**

```json
{
	"request_control_key": "95968498-5ad0-465a-9174-969d0bd1e84a",
	"claim_request_status": "cancelled",
    "created_at": "2024-05-25T12:13:25"
}
```

| Value                     | Description                                                                                                | type            |
| ------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------- |
| `claim_request_status`    | Status do pedido de portabilidade.                                                                         | string          |
| `created_at`              | Data de criação do pedido de portabilidade                                                                 | datetime string |
| `request_control_key`     | Identificador UUID4 único da request.                                                                      | uuid4 string    |

| claim_request_status | Descrição                                                                                |
| -------------------- | ---------------------------------------------------------------------------------------- |
| `waiting_resolution` | A notificação foi recebida pela contraparte                                              |
| `confirmed`          | O doador confirmou a reivindicação. Está aguardando o reivindicador encerrar o processo. |
| `cancelled`          | O doador ou reivindicador cancelou o pedido de portabilidade                             |
| `completed`          | Tanto o DICT quanto o reivindicador atualizaram suas bases com o novo vínculo            |

---

# Completa um Pedido de Portabilidade

URL: /documentation/pix_indireto/portabilidade/completar_pedido_de_portabilidade

:::info
Completa a operação de reivindicação. Como consequência, o vínculo com a chave é criado.

## Request

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /claim/ CLAIM_REQUEST_KEY
MÉTODO PATCH

**Request Body**

```json
{
    "request_control_key": "8a923886-afce-4116-ac1f-69bdffcf8da9",
    "claim_request_status": "completed",
}
```

## Response

STATUS 200

**Response Body**

```json
{
	"request_control_key": "95968498-5ad0-465a-9174-969d0bd1e84a",
	"claim_request_status": "completed",
    "created_at": "2024-05-25T12:13:25"
}
```

| Value                     | Description                                                                                                | type            |
| ------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------- |
| `claim_request_status`    | Status do pedido de portabilidade.                                                                         | string          |
| `created_at`              | Data de criação do pedido de portabilidade                                                                 | datetime string |
| `request_control_key`     | Identificador UUID4 único da request.                                                                      | uuid4 string    |

| claim_request_status | Descrição                                                                                |
| -------------------- | ---------------------------------------------------------------------------------------- |
| `waiting_resolution` | A notificação foi recebida pela contraparte                                              |
| `confirmed`          | O doador confirmou a reivindicação. Está aguardando o reivindicador encerrar o processo. |
| `cancelled`          | O doador ou reivindicador cancelou o pedido de portabilidade                             |
| `completed`          | Tanto o DICT quanto o reivindicador atualizaram suas bases com o novo vínculo            |

---

# Confirmar um Pedido de Portabilidade

URL: /documentation/pix_indireto/portabilidade/confirmar_pedido_de_portabilidade

Confirma a operação de reivindicação. Como consequência, vínculo da chave com participante doador é removido.

Status deve estar em `waiting_resolution`.

Para reivindicação de posse, caso razão seja `default`, o prazo de resolução (`max_resolution_date`) deve ter passado. Se a razão informada for `client_request`, o prazo de encerramento (`max_conclusion_date`) será adiantado para permitir o encerramento imediato pelo reivindicador.

As tabelas abaixo definem, a depender da razão e do tipo, quem pode confirmar.

| Ownership           | Doador | Reivindicador |
|---------------------|--------|---------------|
| `client_request`    | ✓      |               |
| `account_closure`   |        |               |
| `default` | ✓      |               |

| Portability         | Doador | Reivindicador |
|---------------------|--------|---------------|
| `client_request`    | ✓      |               |
| `account_closure`   | ✓      |               |
| `default` |        |               |

## Request

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /claim/ CLAIM_REQUEST_KEY
MÉTODO PATCH

**Request Body**

```json
{
    "request_control_key": "8a923886-afce-4116-ac1f-69bdffcf8da9",
    "claim_request_status": "confirmed",
    "confirmation_reason": "client_request",
}

```

## Response

STATUS 200

**Response Body**

```json
{
	"request_control_key": "95968498-5ad0-465a-9174-969d0bd1e84a",
	"claim_request_status": "confirmed",
    "created_at": "2024-05-25T12:13:25"
}
```

| Value                  | Description                                | type            |
| ---------------------- | ------------------------------------------ | --------------- |
| `claim_request_status` | Status do pedido de portabilidade.         | string          |
| `created_at`           | Data de criação do pedido de portabilidade | datetime string |
| `request_control_key`  | Identificador UUID4 único da request.      | uuid4 string    |

---

# Consultar Pedidos de Portabilidade

URL: /documentation/pix_indireto/portabilidade/consultar_pedido_de_portabilidade

Descrição

## Request

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /claim_request/ CLAIM_REQUEST_KEY
MÉTODO GET

## Response

STATUS 200

**Response Body**

```json
{
  {
    "request_control_key": "be0884bc-44a4-4907-8627-ef976e477aef",
    "claim_request_status": "pending",
    "claim_request_direction": "incoming",
    "claim_request_key": "fe3ab7c5-e907-4a66-b9c5-7ea156429f83",
    "pix_key": "12345678000190",
    "claim_request_type": "ownership",
    "pix_key_type": "cnpj",
    "cancellation_reason": null,
    "cancelled_by": "donor",
    "confirmation_reason": null,
    "created_at": "2024-05-25T12:13:25",
    "max_resolution_date": "2023-11-13T17:29:00",
    "claim_request_events": [
      {
       "event_type": "waiting_resolution",
       "event_details": "Relato de Infração recebido e em análise",
       "created_at": "2023-03-03T12:04:06.179Z"
      },
     {
       "event_type": "cancelled",
       "event_details": "Relato de Infração cancelado",
       "created_at": "2023-03-03T12:04:06.179Z"
     },
    ],
  }
} 
```

| Value                     | Description                                                                                                | type            |
| ------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------- |
| `cancellation_reason`     | Razão do cancelamento. "client_request", "account_closure", "fraud", "default", "reconciliation" | string          |
| `cancelled_by`            | Agente que cancelou o pedido de portabilidade. "donor", "claimer"                                          | string          |
| `claim_request_direction` | Indica se o pedido de portabilidade foi recebido ou enviado. "incoming" ou "outgoing"                      | string          |
| `claim_request_key`       | Chave única de identificação da claim                                                              | string          |
| `claim_request_status`    | Status do pedido de portabilidade.                                                                         | string          |
| `claim_request_type`      | Tipo de pedido de portabilidade. "ownership" ou "portability"                                              | string          |
| `confirmation_reason`     | Razão da confirmação. "client_request", "account_closure", "fraud", "default", "reconciliation"  | string          |
| `created_at`              | Data de criação do pedido de portabilidade                                                                 | datetime string |
| `max_conclusion_date`     | Data limite para encerrar o pedido de portabilidade. apenas para portabilidades do tipo "ownership"        | string          |
| `max_resolution_date`     | Data limite para a resolução do pedido de portabilidade                                                    | string          |
| `pix_key`                 | Chave pix do pedido de portabilidade                                                                       | string          |
| `pix_key_type`            | Tipo de chave pix do pedido de portabilidade                                                               | string          |
| `request_control_key`     | Identificador UUID4 único da request.                                                                      | uuid4 string    |
| `claim_request_events`    | Grupo de eventos relacionados ao pedido de portabilidade                                                   | uuid4 string    |

| claim_request_status | Descrição                                                                                |
| -------------------- | ---------------------------------------------------------------------------------------- |
| `waiting_resolution` | A notificação foi recebida pela contraparte                                              |
| `confirmed`          | O doador confirmou a reivindicação. Está aguardando o reivindicador encerrar o processo. |
| `cancelled`          | O doador ou reivindicador cancelou o pedido de portabilidade                             |
| `completed`          | Tanto o DICT quanto o reivindicador atualizaram suas bases com o novo vínculo            |

---

# Criação de um Pedido de Portabilidade

URL: /documentation/pix_indireto/portabilidade/criar_pedido_de_portabilidade

## Request

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /claim_request
MÉTODO POST

**Request Body**

```json
{
  "request_control_key": "4b61f25d-b8b5-49cb-a391-e4878091ac3f",
  "pix_key": "12345678000190",
  "claim_request_type": "ownership",
  "pix_key_type": "cnpj"
}
```

| Campo                   | Tipo   | Descrição                                                                                | Max. Caracteres |
| ----------------------- | ------ | ---------------------------------------------------------------------------------------- | --------------- |
| `request_control_key` * | string | UUID4 para fins de consulta sobre a requisição feita.                                    | 36              |
| `pix_key` *             | string | Chave pix referente ao pedido de portabilidade                                           | 36              |
| `claim_request_type` *          | string | Tipo de portabilidade. "ownership" para reivindicação e "portability" para portabilidade | 36              |
| `pix_key_type` *        | string | Definição do tipo de chave. Podendo ser "cpf", "cnpj", "email", "phone_number".          | 10              |

## Response

STATUS 201 created

**Response Body**

```json
{
    "request_control_key": "8a923886-afce-4116-ac1f-69bdffcf8da9",
    "claim_request_status": "pending",
    "claim_request_key": "fe3ab7c5-e907-4a66-b9c5-7ea156429f83",
    "max_conclusion_date": "2024-05-26T12:13:25",
    "created_at": "2024-05-25T12:13:25"
}
```

---

# Introdução a Pedidos de Portabilidade

URL: /documentation/pix_indireto/portabilidade/introducao_portabilidade

As reivindicações e portabilidades de chave são mecanismos especiais disponibilizados pelo banco central, para eventuais trocas de posse de chaves pix.

- Reivindicações são utilizadas nos casos que haja troca de posse de uma chave (**telefone** ou **email**) e o novo dono deseja criar um vínculo para sua conta, mas o dono anterior (antigo detentor do **telefone** ou **email**) já possui vínculo registrado no DICT com essa chave.
- Portabilidades são utilizadas em situações que o dono da chave deseja mudar a vinculação dela para outra conta sua, que está domiciliada em um participante diferente do atual.

Para cada tipo de recurso de mudança de posse, existem somente alguns tipos de chave habilitados, que são:

| Compatível   | Reivindicação | Portabilidade |
|--------------|---------------|---------------|
| cpf          | ✓             |               |
| cnpj         | ✓             |               |
| phone_number | ✓             | ✓             |
| email        | ✓             | ✓             |
| random_key   |               |               |

No âmbito do Pix indireto, os mecanismos de mudança de posse funcionarão com os mesmos preceitos, sendo disponibilizadas rotas especiais na infraestrutura QI Tech para que as contas habilitadas a usar o Pix indireto sejam capazes de realizar requisições e receber respostas dos fluxos apresentados acima.

### 1. Fluxo de Reivindicador 
:::info
Os fluxogramas abaixo representam os comportamentos pertinentes ao **fluxo de reivindicação** de chave pix
:::
##### 1.1. Participante Indireto QI Tech solicita abertura de pedido de portabilidade
![Participante Indireto QI Tech solicita abertura de pedido de portabilidade](/img/diagrams/pix-indireto-portabilidade-introducao-portabilidade-1.svg)
##### 1.2. Banco Doador confirma o recebimento de pedido de portabilidade
![Banco Doador confirma o recebimento de pedido de portabilidade](/img/diagrams/pix-indireto-portabilidade-introducao-portabilidade-2.svg)
##### 1.3. Participante Indireto QI Tech completa o pedido de portabilidade e vínculo de chave pix é criado
![Participante Indireto QI Tech completa o pedido e vínculo de chave pix é criado](/img/diagrams/pix-indireto-portabilidade-introducao-portabilidade-3.svg)
##### 1.4. Participante Indireto QI Tech completa o pedido de portabilidade e vínculo de chave pix é criado
:::warning Importante
Pedidos de Portabilidade com status **confirmed** só podem ser cancelados se forem do tipo **"fraud"**
:::
![Participante Indireto QI Tech cancela pedido de portabilidade](/img/diagrams/pix-indireto-portabilidade-introducao-portabilidade-4.svg)
### 2. Fluxo de Doador 
:::info
Os fluxogramas abaixo representam os comportamentos pertinentes ao **fluxo de doação** de chave pix
:::
#### 2.1. Banco Reivindicador abre um pedido de portabilidade
![Banco Reivindicador abre um pedido de portabilidade](/img/diagrams/pix-indireto-portabilidade-introducao-portabilidade-5.svg)

#### 2.2. Participante Indireto QI Tech confirma recebimento de pedido de portabilidade
![Participante Indireto QI Tech confirma recebimento de pedido de portabilidade](/img/diagrams/pix-indireto-portabilidade-introducao-portabilidade-6.svg)

#### 2.3. Banco Reivindicador completa um pedido de portabilidade
![Banco Reivindicador completa um pedido de portabilidade](/img/diagrams/pix-indireto-portabilidade-introducao-portabilidade-7.svg)

#### 2.4. Banco Reivindicador cancela um pedido de portabilidade
:::warning Importante
Pedidos de Portabilidade com status **confirmed** só podem ser cancelados se forem do tipo **"fraud"**
:::
![Banco Reivindicador cancela um pedido de portabilidade](/img/diagrams/pix-indireto-portabilidade-introducao-portabilidade-8.svg)

---

# Consultar Pedidos de Portabilidade de um Alias

URL: /documentation/pix_indireto/portabilidade/listar_pedidos_de_portabilidade_de_um_alias

Descrição

## Request

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /claim_requests
MÉTODO GET

## Response

STATUS 200

**Response Body**

```json
{
  "data": [
    {
        "cancellation_reason": null,
        "cancelled_by": null,
        "claim_request_flow_type": "donator",
        "claim_request_key": "be0884bc-44a4-4907-8627-ef976e477aef",
        "claim_request_status": "pending_confirmation",
        "claim_request_type": "portability",
        "confirmation_reason": null,
        "created_at": "2023-11-06T17:30:11",
        "donator_ispb": 32402502,
        "limit_conclusion_date": null,
        "limit_resolve_date": "2023-11-13T17:29:00",
        "max_conclusion_date": null,
        "max_resolution_date": "2023-11-13T17:29:00",
        "pix_key": "45574823098",
        "pix_key_claim_id": "205c72ab-c03e-43b7-a43d-2409e21fa5be",
        "pix_key_type": "cpf",
        "request_control_key": "be0884bc-44a4-4907-8627-ef976e477aef"
    },
    {
        "cancellation_reason": null,
        "cancelled_by": null,
        "claim_request_flow_type": "donator",
        "claim_request_key": "852d0192-68a7-4bad-bc22-0002f9c5cb1c",
        "claim_request_status": "concluded",
        "claim_request_type": "portability",
        "confirmation_reason": null,
        "created_at": "2023-11-05T17:30:11",
        "donator_ispb": 32402502,
        "limit_conclusion_date": null,
        "limit_resolve_date": "2023-11-12T17:29:00",
        "max_conclusion_date": null,
        "max_resolution_date": "2023-11-12T17:29:00",
        "pix_key": "93109309009",
        "pix_key_claim_id": "089db155-59cf-4a19-881b-22ca932a4612",
        "pix_key_type": "cpf",
        "request_control_key": "9a4336be-a729-4245-9b90-72bbeb04f13c"
    }
  ],
  "pagination": {
    "current_page": 1,
    "rows_per_page": 10
  }
} 
```

---

# Webhook Atualização de Portabilidade

URL: /documentation/pix_indireto/portabilidade/webhook/webhook_atualizacao_do_pedido_de_portabilidade

**Request Body: Atualização de Pedido de Portabilidade**

```json
{
  "webhook_type": "baas.pix_keys.claim_request",
  "webhook_datetime": "2024-05-27T12:13:24",
  "data": {
    "claim_request_status": "pending",
    "claim_request_direction": "incoming",
    "claim_request_key": "fe3ab7c5-e907-4a66-b9c5-7ea156429f83",
    "pix_key": "12345678000190",
    "claim_request_type": "ownership",
    "pix_key_type": "cnpj",
    "cancellation_reason": null,
    "cancelled_by": "donor",
    "confirmation_reason": null,
    "max_resolution_date": "2023-11-13T17:29:00",
    "updated_at": "2024-05-25T12:13:25",
  }
}
```

### Webhook Body Param

| Campo                    | Tipo     | Descrição                                                 | Caracteres |
| ------------------------ | -------- | --------------------------------------------------------- | ---------- |
| `claim_request_status` * | string   | Chave Pix que representa a conta de destino da transação. | -          |
| `claim_request_key` *    | string   | Chave UUID4 identificadora do QR Code.                    | -          |
| `updated_at` *           | datetime | Data hora de pagamento QR Code.                           | -          |

| claim_request_status | Descrição                                                                                |
| -------------------- | ---------------------------------------------------------------------------------------- |
| `waiting_resolution` | A notificação foi recebida pela contraparte                                              |
| `confirmed`          | O doador confirmou a reivindicação. Está aguardando o reivindicador encerrar o processo. |
| `cancelled`          | O doador ou reivindicador cancelou o pedido de portabilidade                             |
| `completed`          | Tanto o DICT quanto o reivindicador atualizaram suas bases com o novo vínculo            |

---

# Webhook Registro Externo de Portabilidade

URL: /documentation/pix_indireto/portabilidade/webhook/webhook_receber_registro_externo_de_portabilidade

**Request Body: Recebimento de Pedido de Portabilidade**

```json
{
  "webhook_type": "baas.pix_keys.claim_request",
  "webhook_datetime": "2024-05-27T12:13:24",
  "data": {
    "claim_request_status": "pending",
    "claim_request_direction": "incoming",
    "claim_request_key": "fe3ab7c5-e907-4a66-b9c5-7ea156429f83",
    "pix_key": "12345678000190",
    "claim_request_type": "ownership",
    "pix_key_type": "cnpj",
    "cancellation_reason": null,
    "cancelled_by": "donor",
    "confirmation_reason": null,
    "max_resolution_date": "2023-11-13T17:29:00",
    "created_at": "2024-05-25T12:13:25",
  }
}
```

### Webhook Body Param

| Campo                    | Tipo     | Descrição                                                 | Caracteres |
| ------------------------ | -------- | --------------------------------------------------------- | ---------- |
| `claim_request_status` * | string   | Chave Pix que representa a conta de destino da transação. | -          |
| `claim_request_key` *    | string   | Chave UUID4 identificadora do QR Code.                    | -          |
| `updated_at` *           | datetime | Data hora de pagamento QR Code.                           | -          |

| claim_request_status | Descrição | Valores    |
| -------------------- | --------- | ---------- |
| waiting_resolution   | Descrição | Caracteres |
| confirmed            | Descrição | Caracteres |
| cancelled            | Descrição | Caracteres |
| completed            | Descrição | Caracteres |

---

# Consultar um QR Code Pix

URL: /documentation/pix_indireto/qr_code/consultar_qr_code

É possível buscar um QR Code específico do Alias pela qr_code_key gerada na criação do mesmo. Esse endpoint retornará todas as informações do mesmo, como status, pagamento, eventos. 

## Request

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /qrcode/ QR_CODE_KEY
MÉTODO GET

## Response

STATUS 200 Ok

Response Body: Geral

```json
{
  "request_control_key": "037b46b1-0c67-4c0d-aac3-1e395dfdcb10",
  "pix_key": "3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
  "receiver_conciliation_id": "01GVGV9NXBCY287Z6CJ4S0ENW9",
  "qr_code_key": "d74bf12a-9243-4bfa-9b00-6b63755b6555",
  "qr_code_status": "active",
  "qr_code_type": "dynamic_instant",
  "amount": 22.34,
  "expiration_seconds": 864000,
  "expiration_date": null,
  "max_payment_days": null,
  "payer_name": "João da Silva",
  "payer_document_number": "00000000000000",
  "payer_person_type": "legal",
  "payer_request": "Payment for order XXXXXXXXXXXX",
  "rebate_amount": 1,
  "interest_amount": 2,
  "fine_amount": 3,
  "discounts": [],
  "additional_data": [
    {
      "key_name": "Juros e Multa",
      "value": "Juros 2 ao mes e multa de 1%"
    }
  ],
  "pix_transfer_key": null,
  "paid_amount": null,
  "base_64_payload": "<BASE64 DA URI DO PIX COPIA E COLA>",
  "qr_code_events": [
    {
      "request_control_key": "037b46b1-0c67-4c0d-aac3-1e395dfdcb10",
      "event_type": "registration",
      "created_at": "2023-03-03T12:04:06.179Z"
    },
    {
      "request_control_key": "cae915c8-1940-43ec-890b-ba1a3a66354c",
      "event_type": "payment",
      "created_at": "2023-03-03T12:04:06.179Z"
    }
  ],
  "created_at": "2023-03-03T12:04:06.179Z"
}
```

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `request_control_key` * | string | Identificador UUID4 único da request que originou o QR Code. | - |
| `pix_key` * | string | Chave Pix que representa a conta de destino da transação. | - |
| `receiver_conciliation_id` * | string | Identificador do QR Code para conciliação após o pagamento. | - |
| `qr_code_key` * | string | Chave UUID4 identificadora do QR Code. | - |
| `qr_code_status` * | string | Status do QR Code. | - |
| `qr_code_type` * | string | Tipo do QR Code. | "dynamic_term" ou "dynamic_instant" |
| `amount` * | float | Valor do QR Code antes do cálculo de descontos ou juros e multas. | - |
| `expiration_seconds`  | string | indica qual o tempo de validade do QR Code em segundos, padrão 1 dia. | - |
| `expiration_date` | date | Data de vencimento da cobrança (no formato "YYYY-MM-DD"). | - |
| `max_payment_days` | int32 | Dias máximos para pagamento da cobrança após vencimento. |  - |
| `payer_name` * | string | Nome do pagador. | - |
| `payer_document_number` * | string | CPF/ CNPJ do pagador. | - |
| `payer_request` * | string | Mensagem ao pagador. | - |
| `rebate_amount` | float | Valor absoluto de abatimento antes do pagamento. | - |
| `interest_amount` | float | Valor absoluto por dia de atraso após o vencimento, caso seja pago um dia após o vencimento o valor total será o valor ordinario + multa. |  - |
| `fine_amount` | float | Multa em valor absoluto após o vencimento. |  - |
| `discounts` | array of objects | Configurações de desconto. |  - |
| `additional_data` | array of objects | Informações que serão apresentadas para o pagador. | - |
| `pix_transfer_key` | string | Chave UUID4 identificadora da transação pix correspondente à liquidação do QR Code. | - |
| `paid_amount` | float | Valor do pagamento realizado, considerando multas, descontos e outros. | - |
| `base_64_payload` | string | URL do QR Code para pagamento, em base64. | - |
| `qr_code_events` | array of objects | Lista de mudanças de status pelas quais o QR Code passou. | - |
| `created_at` | datetime | Data e hora que o QR Code foi criado no sistema. | - |

### Objeto qr_code_status

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `active`  | string | QR Code se encontra ativo e disponível para pagamento. | - |
| `finished` | string | QR Code pago. | - |
| `written_off` | string | QR Code foi baixado pelo cliente. | - |
| `bank_written_off` | string | QR Code foi baixado automaticamente devido prazo expirado. | - |

### Objeto discount

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `discount_value` * | float |  Valor do desconto. | - |
| `discount_number` | int32 | Ordem que o desconto deve ser aplicado. | - |
| `discount_limit_date` | string | Data limite do desconto. | - |

### Objeto additional_data

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `key_name` * | string |  Nome do campo | - |
| `value` | string | Valor do campo | - |

### Objeto qr_code_events

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `request_control_key` * | string |  Identificador UUID4 único da request que originou o event. | - |
| `event_type` * | string |  Tipo de evento | "registration", "write_off", "payment" |
| `created_at` * | datetime | Data e hora que o evento foi criado. | - |

STATUS 400

Response Body

```json
{
    "title": "Bad Request",
    "description": "Invalid payload for QR Code creation.",
    "translation": "Payload inválido para a criação de QR Code.",
    "code": "QRI000003"
}

```

STATUS 404

Response Body: QR Code key não encontrada

```json
{
    "title": "Not found",
    "description": "No Pix QR Code found for qr_code_key {qr_code_key}.",
    "translation": "Não foi encontrado nenhum QR Code com a qr_code_key {qr_code_key}.",
    "code": "QRI000005"
}
```

---

# Criar QR Code Pix dinâmico com vencimento

URL: /documentation/pix_indireto/qr_code/Criar QR Code/criar_qr_code_dinamico_com_vencimento

O QR Code dinâmico com vencimento é utilizado para pagamentos onde o originador é conhecido e é desejado facilitar o pagamento, possibilitando adicionar prazos, descontos, multas, e juros. Este QR Code é utilizado normalmente em substituição ao boleto bancário. 

## Request

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /qrcode
MÉTODO POST

Request Body: Qr Code dinâmico com vencimento

```json
{
  "request_control_key": "8a923886-afce-4116-ac1f-69bdffcf8da9",
  "qr_code_type": "dynamic_term",
  "amount": 10.25,
  "receiver_conciliation_id": "01GVGV9NXBCY287Z6CJ4S0ENW9",
  "payer_document_number": "00000000000000",
  "payer_name": "Random",
  "payer_request": "Payment for order XXXXXXXXXX",
  "pix_key": "3d7d6a2b-f72f-44c7-bb20-79a94dff5954",
  "expiration_date": "2023-03-25",
  "max_payment_days": 128,
  "fine_amount": 3,
  "interest_amount": 2,
  "rebate_amount": 1,
  "discounts": [],
  "additional_data": [
    {
      "key_name": "merchant_name",
      "value": "Lojas Costa S.A."
    }
  ],
}
```

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `request_control_key` * | string | Identificador UUID4 único da request. | - |
| `qr_code_type` * | string | Tipo do QR Code dinâmico. | "dynamic_term" ou "dynamic_instant" |
| `amount` * | float | Valor do QR Code antes do cálculo de descontos ou juros e multas. | - |
| `receiver_conciliation_id` * | string | Identificador do QR Code para conciliação após o pagamento. | - |
| `payer_document_number` * | string | CPF/ CNPJ do pagador. | - |
| `payer_name` * | string | Nome do pagador. | - |
| `payer_request` * | string | Mensagem ao pagador. | - |
| `pix_key` * | string | Chave Pix que representa a conta de destino da transação. | - |
| `expiration_date` * | date | Data de vencimento da cobrança (no formato "YYYY-MM-DD"). | - |
| `max_payment_days` * | int32 | Dias máximo para pagamento da cobrança. |  - |
| `fine_amount` * | float | Multa em valor absoluto após o vencimento. |  - |
| `interest_amount` * | float | Valor absoluto por dia de atraso após o vencimento, caso seja pago um dia após o vencimento o valor total será o valor ordinario + multa. |  - |
| `rebate_amount` * | float | Valor absoluto de abatimento antes do pagamento. | - |
| `discounts` | array of objects | Configurações de desconto. |  - |
| `additional_data` | array of objects | Informações extras do QR Code utilizado para conciliações. | - |

### Objeto additional_data

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `key_name` * | string |  Nome do campo | - |
| `value` * | string | Valor do campo | - |

### Objeto discount

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `discount_value` * | float |  Valor do desconto. | - |
| `discount_number` | int32 | Ordem que o desconto deve ser aplicado. | - |
| `discount_limit_date` * | string | Data limite do desconto. | - |

## Response

STATUS 201 Created

Response Body: Criação Qr Code dinâmico com vencimento

```json
{
  "request_control_key": "037b46b1-0c67-4c0d-aac3-1e395dfdcb10",
  "qr_code_key": "d74bf12a-9243-4bfa-9b00-6b63755b6555",
  "qr_code_status": "active",
  "base_64_payload": "<BASE64 DA URI DO PIX COPIA E COLA>",
  "created_at": "2023-03-03T12:04:06.179Z",
}
```

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `request_control_key` * | string | Identificador UUID4 único da request. | - |
| `qr_code_key` * | string | Identificador do QR Code para futuras requisições. | - |
| `qr_code_status` * | string | Status do QR Code no sistema. | "active": default para criação. |
| `base_64_payload` * | string | URL do QR Code para pagamento, em base64. | - |
| `created_at` * | datetime | Data e hora que o QR Code foi criado no sistema. | - |

### Objeto qr_code_status

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `active`  | string | QR Code se encontra ativo e disponível para pagamento. | - |
| `finished` | string | QR Code pago. | - |
| `written_off` | string | QR Code foi baixado pelo cliente. | - |
| `bank_written_off` | string | QR Code foi baixado automaticamente devido prazo expirado. | - |

STATUS 400

Response Body

```json
{
    "title": "Bad Request",
    "description": "Invalid payload for QR Code creation.",
    "translation": "Payload inválido para a criação de QR Code.",
    "code": "QRI000003"
}

```

---

# Criar QR Code Pix dinâmico pagamento imediato

URL: /documentation/pix_indireto/qr_code/Criar QR Code/criar_qr_code_dinamico_imediato

O QR Code dinâmico imediato é utilizado para pagamentos que possuem um prazo de pagamento curto, normalmente providenciado em segundos, para operações rotineiras de cobrança para pagamento imediato.

## Request

Request Body: Qr Code dinâmico pagamento imediato

```json
{
  "request_control_key": "8a923886-afce-4116-ac1f-69bdffcf8da9",
  "qr_code_type": "dynamic_instant",
  "amount": 22.34,
  "receiver_conciliation_id": "01GVGV9NXBCY287Z6CJ4S0ENW9",
  "payer_document_number": "00000000000000",
  "payer_name": "Random",
  "payer_request": "Payment for order XXXXXXXXXX",
  "pix_key": "3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
  "expiration_seconds": 864000,
  "additional_data": [
    {
      "key_name": "identificacao_venda",
      "value": "Venda número 123 na plataforma"
    }
  ],
}
```

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `request_control_key` * | string | Identificador UUID4 único da request. | - |
| `qr_code_type` * | string | Tipo do QR Code dinâmico. | "dynamic_term" ou "dynamic_instant" |
| `amount` * | float | Valor do QR Code antes do cálculo de descontos ou juros e multas. | - |
| `receiver_conciliation_id` * | string | Identificador do QR Code para conciliação após o pagamento. | - |
| `payer_document_number` * | string | CPF/ CNPJ do pagador. | - |
| `payer_name` * | string | Nome do pagador. | - |
| `payer_request` * | string | Mensagem ao pagador. | - |
| `pix_key` * | string | Chave Pix que representa a conta de destino da transação. | - |
| `expiration_seconds`  | string | indica qual o tempo de validad e do QR Code em segundos, padrão 1 dia | - |
| `additional_data` | array of objects | Informações que serão apresentadas para o pagador. | - |

### Objeto additional_data

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `key_name` * | string |  Nome do campo | - |
| `value` | string | Valor do campo | - |

## Response

STATUS 201 Created

Response Body: Criação Qr Code dinâmico pagamento imediato

```json
{
  "request_control_key": "037b46b1-0c67-4c0d-aac3-1e395dfdcb10",
  "qr_code_key": "d74bf12a-9243-4bfa-9b00-6b63755b6555",
  "qr_code_status": "active",
  "base_64_payload": "<BASE64 DA URI DO PIX COPIA E COLA>",
  "created_at": "2023-03-03T12:04:06.179Z",
}
```

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `request_control_key` * | string | Identificador UUID4 único da request. | - |
| `qr_code_key` * | string | Identificador do QR Code para futuras requisições. | - |
| `qr_code_status` * | string | Status do QR Code no sistema. | "active": default para criação. |
| `base_64_payload` * | string | URL do QR Code para pagamento, em base64. | - |
| `created_at` * | datetime | Data e hora que o QR Code foi criado no sistema. | - |

### Objeto qr_code_status

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `active`  | string | QR Code se encontra ativo e disponível para pagamento. | - |
| `finished` | string | QR Code pago. | - |
| `written_off` | string | QR Code foi baixado pelo cliente. | - |
| `bank_written_off` | string | QR Code foi baixado automaticamente devido prazo expirado. | - |

STATUS 400

Response Body

```json
{
    "title": "Bad Request",
    "description": "Invalid payload for QR Code creation.",
    "translation": "Payload inválido para a criação de QR Code.",
    "code": "QRI000003"
}

```

---

# Criar QR Code Pix Estático

URL: /documentation/pix_indireto/qr_code/Criar QR Code/criar_qr_code_estatico

O QR Code estático é utilizado para pagamentos onde não se sabe a identidade do pagador, muito menos quando irá pagar e quantos pagadores terão. Basicamente, consiste em uma chave, e opcionalmente um valor, codificados, e pode ser pago multiplas vezes, por referenciar apenas a chave.

## Request

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /qrcode
MÉTODO POST

Request Body: Qr Code estático

```json
{
    "request_control_key": "8a923886-afce-4116-ac1f-69bdffcf8da9",
    "qr_code_type": "static",
    "pix_key": "joaosilva@gmail.com",
    "amount": 10.25,
}
```

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `request_control_key` * | string | Identificador UUID4 único da request. | - |
| `qr_code_type` * | string | Tipo do QR Code dinâmico. | "static" |
| `pix_key` * | string | Chave Pix que representa a conta de destino da transação. | - |
| `amount` | float | Valor do QR Code. | Se não passado, inserido a cargo do pagador. |

## Response

STATUS 201 Created

Response Body: Criação Qr Code estático

```json
{
  "request_control_key": "037b46b1-0c67-4c0d-aac3-1e395dfdcb10",
  "base_64_payload": "<BASE64 DA URI DO PIX COPIA E COLA>"
}
```

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `request_control_key` * | string | Identificador UUID4 único da request. | - |
| `base_64_payload` * | string | URL do QR Code para pagamento, em base64. | - |

STATUS 400

Response Body

```json
{
    "title": "Bad Request",
    "description": "Invalid payload for QR Code creation.",
    "translation": "Payload inválido para a criação de QR Code.",
    "code": "QRI000003"
}

```

---

# Listar QR Codes de um alias

URL: /documentation/pix_indireto/qr_code/decodificar_qr_code

Os QR Codes Pix, utilizados no formato imagem ou URL, seguem um padrão, e devem ser decodificados seguindo uma lógica para extrair as informações do pagamento a ser realizado. Tendo a URL do QR Code, é possível decodificar todas as informações que originaram o mesmo. A decodificação gera um `end_to_end_id`, que deverá ser utilizado no pagamento do QR Code, juntamente com o receiver_conciliation_id, para identificar o pagamento do QR Code.

## Request

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /qrcode/decode
MÉTODO POST

Request Body: Decode QR Code

```json
{
   "qr_code_payload": "00020126580014br.gov.bcb.pix0136a23bf0e9-5175-4829-bf89-e8fe6ac09aa1520400005303986540530.005802BR5914TywinLannister6008saopaulo62070503***6304D4FD",
}
```

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `qr_code_payload` | string | URL do QR Code para pagamento (pix copia e cola). | - |

## Response

STATUS 200 Ok

Response Body: QR Code estático

```json
{
  "end_to_end_id": "E32402502202303131806WTFZTGAOWiq",
  "qr_code_data": {
    "additional_data": null,
    "amount": null,
    "ispb_number": "90400888",
    "receiver_conciliation_id": "01GVGV9NXBCY287Z6CJ4S0ENW9",
    "target_account_branch": "2980",
    "target_account_digit": "5",
    "target_account_number": "0000000000022039741",
    "target_account_type": "checking_account",
    "target_bank_code": 33,
    "target_bank_name": "BCO SANTANDER (BRASIL) S.A.",
    "target_document_number": "00000000000000",
    "target_name": "JOSE RONALDO",
    "target_pix_key": "00000000000000"
  },
  "qr_code_key": "e54671f5-3eda-4180-8539-0ac6271fe185",
  "qr_code_payload": "00020126360032br.gov.bcb.pix0111234590280001665204000051234565802BR5925JOSE RONALDO BERNARDINO 26008BRASILIA62070503***63044293",
  "qr_code_type": "static"
}
```

STATUS 200 Ok

Response Body: QR Code dinâmico com vencimento

```json
{
  "request_control_key": "037b46b1-0c67-4c0d-aac3-1e395dfdcb10",
  "end_to_end_id": "E32402502202303101532yCipbxgUnUj",
  "qr_code_data": {
    "account_type": "payment_account",
    "additional_data": [],
    "amount": "55.59",
    "category_code": "0000",
    "max_payment_days": 16,
    "discount_amount": null,
    "expiration_date": "2023-03-27",
    "fee_amount": null,
    "fine_amount": null,
    "ispb_number": "20018183",
    "original_amount": "55.59",
    "payer_document_number": "00000000000",
    "payer_name": "Willian Rocha",
    "payer_request": null,
    "receiver_conciliation_id": "8b434df48c30482a81f7c936ae35cc87",
    "receiver_url": "invoice.starkbank.com/v2/cobv/8b434df48c30482a81f7c936ae351234",
    "reduction_amount": null,
    "qr_code_status": "active",
    "target_account_branch": "0001",
    "target_account_digit": "8",
    "target_account_number": "589575519784140",
    "target_bank_code": null,
    "target_bank_name": "Stark Bank S.A.",
    "target_document_number": "00000000000000",
    "target_name": "TESTE LTDA.",
    "target_pix_key": "e623e7b0-d00a-400e-aee6-79632430e817",
    "target_trading_name": null,
    "presented_at": "2023-03-10T15:32:15.87Z",
    "created_at": "2023-01-10T19:49:58.30Z",
  },
  "qr_code_key": "8c2c19bd-f260-4714-955c-956f3eaa30ca",
  "qr_code_payload": "00020101021226840014br.gov.bcb.pix2562invoice.starkbank.com/v2/cobv/8b434df48c30482a81f7c936ae35cc123456000053039865802BR5925Oncred Sociedade de Credi6015TESTE 62070503***6304D008",
  "qr_code_type": "dynamic_term"
}

```

STATUS 200 Ok

Response Body: QR Code dinâmico com vencimento

```json
{
  "request_control_key": "037b46b1-0c67-4c0d-aac3-1e395dfdcb10",
  "end_to_end_id": "E32402502202303141907qlBAF1evdJ2",
  "qr_code_data": {
    "account_type": "checking_account",
    "additional_data": [],
    "amount": "9367.61",
    "category_code": "0000",
    "expiration_seconds": 201574,
    "ispb_number": "00000000",
    "payer_document_number": "10003550206",
    "payer_name": "ISMAEL FATIMA AMARAL",
    "payer_request": "Liquidacao de Parcelas",
    "receiver_conciliation_id": "fgnb4NTt7pOUBGfrcporERwVVqr0f8PWRfK",
    "receiver_url": "qrcodepix.bb.com.br/pix/v2/d373e385-dfe7-49f6-b9ec-14ba60a90000",
    "qr_code_status": "active",
    "target_account_branch": "1253",
    "target_account_digit": "8",
    "target_account_number": "107260",
    "target_bank_code": 1,
    "target_bank_name": "BCO DO BRASIL S.A.",
    "target_document_number": "0000000000000",
    "target_name": "TESTE LTDA.",
    "target_pix_key": "teste.cobrancapix@gmail.com.br",
    "presented_at": "2023-03-14T19:07:48.729Z",
    "created_at": "2023-03-13T19:00:28.440Z",
  },
  "qr_code_key": "ffd7d60a-0f2d-4b29-9ae2-7f2b919fa65e",
  "qr_code_payload": "00020101021226850014br.gov.bcb.pix2563qrcodepix.bb.com.br/pix/v2/d373e385-dfe7-49f6-b9ec-14ba60a9b8285204001234567895802BR5925TESTE DE JANEIRO62070503***63047B7D",
  "qr_code_type": "dynamic_instant"
}
```

### Response Body

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `request_control_key` * | string | Identificador UUID4 único da request que originou o QR Code. | - |
| `end_to_end_id` * | string | Identificador único da transação Pix, de ponta a ponta. | - |
| `account_type` * | string | Tipo da conta de origem. | - |
| `amount` * | float | Valor do QR Code atualmente. | - |
| `category_code` * | string | Identificador do QR Code para conciliação após o pagamento. | - |// aaaaaaaaaaa
| `expiration_seconds`  | string | Indica qual o tempo de validade do QR Code em segundos, padrão 1 dia. | - |
| `ispb_number` * | string | Identificador do banco. | - |aaaaaaaaaaaa
| `payer_document_number` * | string | CPF/ CNPJ do pagador. | - |
| `payer_name` * | string | Nome do pagador. | - |
| `payer_request` * | string | Mensagem ao pagador. | - |
| `receiver_conciliation_id` * | string | Identificador do QR Code para conciliação após o pagamento. | - |
| `receiver_url` * | string | URL para consulta dos dados do QR Code dinâmico. | - |
| `qr_code_status` * | string | Status do QR Code. | - |
| `target_account_branch` * | string | Agência da conta de destino. | - |
| `target_account_digit` * | string | Digito verificador da conta de destino. | - |
| `target_account_number` * | string | Número da conta de destino. | - |
| `target_bank_code` * | string | Código do banco de destino. | - |
| `target_bank_name` * | string | Nome do banco de destino. | - |
| `target_document_number` * | string | CPF/ CNPJ do cobrador. | - |
| `target_name` * | string | Nome do cobrador. | - |
| `target_trading_name` * | string | Nome fantasia do cobrador - apenas para CNPJ. | - |
| `target_pix_key` * | string | Chave pix do cobrador. | - |
| `qr_code_key` * | string | Chave UUID4 identificadora do QR Code. | - |
| `qr_code_payload` * | string | URL copia e cola do QR Code. | - |
| `qr_code_type` * | string | Tipo do QR Code. | "static", "dynamic_term" ou "dynamic_instant" |
| `max_payment_days` | int32 | Dias máximos para pagamento da cobrança após vencimento. |  - |
| `expiration_date` | date | Data de vencimento da cobrança (no formato "YYYY-MM-DD"). | - |
| `fine_amount` | float | Multa em valor absoluto após o vencimento. |  - |
| `interest_amount` | float | Valor absoluto por dia de atraso após o vencimento, caso seja pago um dia após o vencimento o valor total será o valor ordinario + multa. |  - |
| `discount_amount` | float | Valor do desconto. |  - |
| `original_amount` | float | Valor original do QR Code. |  - |
| `additional_data` | array of objects | Informações que serão apresentadas para o pagador. | - |
| `presented_at` * | datetime | Data e hora que o QR Code foi decodificado. | - |
| `created_at` * | datetime | Data e hora que o QR Code foi criado no sistema. | - |
| `rebate_amount` | float | Valor absoluto de abatimento antes do pagamento. | - |

### Objeto qr_code_status

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `active`  | string | QR Code se encontra ativo e disponível para pagamento. | - |
| `finished` | string | QR Code pago. | - |
| `written_off` | string | QR Code foi baixado pelo cliente. | - |
| `bank_written_off` | string | QR Code foi baixado automaticamente devido prazo expirado. | - |

### Objeto additional_data

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `key_name` * | string |  Nome do campo | - |
| `value` | string | Valor do campo | - |

STATUS 400

Response Body: Impossível decodificar QR Code

```json
{
    "title": "Bad Request",
    "description": "Could not decode QR Code.",
    "translation": "Não foi possível decodificar o QR Code.",
    "code": "QRI000001"
}
```

STATUS 404

Response Body: QR Code não encontrado

```json
{
    "title": "Not found",
    "description": "Could not find the queried QR Code.",
    "translation": "Não possível encontrar o QR Code buscado.",
    "code": "QRI000002"
}
```

---

# Alterar um QR Code Pix

URL: /documentation/pix_indireto/qr_code/desativar_qr_code

Só é possível realizar a alteração de QR Code pix do tipo dinâmico. Ao realizar a mesma, identificada pela qr_code_key gerada na criação do QR Code, ele se torna inválido para posteriores pagamentos. Existem vários motivos para requisitar a alteração de um QR Code Pix, porém no sistema interno a inativação de um QR Code pode ser realizada por baixa requisitada pelo alias (write_off).

## Request

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /qrcode/ QR_CODE_KEY
MÉTODO PATCH

Request Body: Baixa de QR Code

```json
{
  "request_control_key": "76d4506d-31a4-48db-bc71-61068b138ffd",
  "qr_code_status": "written_off",
}
```

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `request_control_key` * | string | Identificador UUID4 único da request. | - |
| `qr_code_status` * | string | Status do QR Code | - |

### Objeto qr_code_status

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `active`  | string | QR Code se encontra ativo e disponível para pagamento. | - |
| `finished` | string | QR Code pago. | - |
| `written_off` | string | QR Code foi baixado pelo cliente. | - |
| `bank_written_off` | string | QR Code foi baixado automaticamente devido prazo expirado. | - |

## Response

STATUS 204 No content

Response Body

```json
{}
```

STATUS 404

Response Body

```json
{
    "title": "Not found",
    "description": "Could not find the queried QR Code.",
    "translation": "Não possível encontrar o QR Code buscado.",
    "code": "QRI000002"
}

```

---

# Introdução QR Code pix

URL: /documentation/pix_indireto/qr_code/introducao_qr_code

Qualquer cliente do Participante Indireto (Alias) pode realizar operações de criação, consulta e baixa de QR Codes pix.

- Criação: Pode-se gerar QR Codes do tipo estático ou dinâmico. No último, é possível gerar um dinâmico para pagamento instantâneo ou com vencimento de longo prazo. Os tipos serão explicados melhor no processo de criação.

- Consulta: Tendo um QR Code ou a URL do QR Code (pix copia e cola), é possível consultar suas informações para posterior pagamento realizado. A consulta é chamada de decodificação de QR Code, e gera um `end_to_end_id` para posterior pagamento.

- Baixa: A baixa de um QR Code o torna inválido para pagamento. As principais causas para baixa são: prazo expirado, cancelamento do QR Code pelo alias, ou pagamento.

## Tipos de QR Code
O tipo do QR Code é definido na criação, pelo campo qr_code_type

| Nome | Enumerador | Descrição |
|---|---|---|
| Estático | `static` | Contém chave pix de destino e pode conter valor. Pode ser pago a qualquer momento, desde que a chave steja ativa. Não possui prazo de validade. Reutilizável.|
| Dinâmico para Pagamento Instantaneo |  `dynamic_instant` | Cotém informações de pagamento, com pagador definido, valor e chave de conciliação. Prazo de pagamento em segundos. Uso único.|
| Dinâmico com Vencimento | `dynamic_term` | Cotém informações de pagamento, com pagador definido, valor e chave de conciliação. Prazo de pagamento em dias, informações de multa e juros. Uso único. |

## Pagamento de um QR Code

Após a decodificação de um QR Code e consulta da chave, é gerado um `end_to_end_id`, o qual é utilizado na ordem de pagamento para finalizar a transação. Além disso, no caso do QR Code Dinâmico, o campo `receiver_conciliation_id` é utilizado para identificar o QR Code específico sendo pago, utilizado pelo recebedor para dar continuidade na operação após pagamento.

Ao decodificar um QR Code, deve enviar uma ordem de pagamento pix com o `end_to_end_id` e `receiver_conciliation_id`, e o banco recebedor saberá dar prosseguimento. Seguindo a mesma linha, ao receber um pagamento pix do tipo `static_qr_code` ou `dynamic_qr_code`, será enviado um webhook, tratado também no final dessa seção de QR Code.

---

# Listar QR Codes de um alias

URL: /documentation/pix_indireto/qr_code/listar_alias_qr_codes

A busca de QR Codes é utilizado para gerenciar o status de QR Codes dinâmicos, averiguar pagamentos, baixas, etc.

## Request

ENDPOINT /account/ ACCOUNT_KEY /alias/ ALIAS_KEY /qrcodes
MÉTODO GET

### Path params

| Campo                      | Tipo    | Descrição                                                        | Caracteres |
|----------------------------|---------|------------------------------------------------------------------|------------|
| `page`                     | integer | Número da página pesquisada (default = 0)                        | -          |
| `page_size`                | integer | Quantidade de itens por página (default = 15)                    | -          |
| `qr_code_status`           | string  | Status dos qr codes buscados                                     | -          |
| `qr_code_type`             | string  | Tipo dos qr codes buscados                                       | -          |
| `request_control_key`      | string  | Request control key que originou o qr code                       | -          |

## Response

STATUS 200 Ok

Response Body: Geral

```json
{
   "data":[
      {
         "request_control_key":"037b46b1-0c67-4c0d-aac3-1e395dfdcb10",
         "pix_key":"3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
         "receiver_conciliation_id":"01GVGV9NXBCY287Z6CJ4S0ENW9",
         "qr_code_key":"d74bf12a-9243-4bfa-9b00-6b63755b6555",
         "qr_code_status":"active",
         "qr_code_type":"dynamic_instant",
         "amount":22.34,
         "expiration_seconds":864000,
         "expiration_date":null,
         "max_payment_days":null,
         "payer_name":"João da Silva",
         "payer_document_number":"00000000000000",
         "payer_request":"Payment for order XXXXXXXXXXXX",
         "rebate_amount":1,
         "interest_amount":2,
         "fine_amount":3,
         "discounts":[
            
         ],
         "additional_data":[
            {
               "key_name":"Juros e Multa",
               "value":"Juros 2 ao mes e multa de 1%"
            },
         ],
         "pix_transfer_key":null,
         "paid_amount":null,
         "base_64_payload":"<BASE64 DA URI DO PIX COPIA E COLA>",
         "qr_code_events":[
            {
               "request_control_key":"037b46b1-0c67-4c0d-aac3-1e395dfdcb10",
               "event_type":"registration",
               "created_at":"2023-03-03T12:04:06.179Z"
            },
            {
               "request_control_key":"cae915c8-1940-43ec-890b-ba1a3a66354c",
               "event_type":"payment",
               "created_at":"2023-03-03T12:04:06.179Z"
            },
         ],
         "created_at":"2023-03-03T12:04:06.179Z"
      },
   ],
   "pagination":{
      "current_page":1,
      "rows_per_page":30
   },
},
```

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `request_control_key` * | string | Identificador UUID4 único da request que originou o QR Code. | - |
| `pix_key` * | string | Chave Pix que representa a conta de destino da transação. | - |
| `receiver_conciliation_id` * | string | Identificador do QR Code para conciliação após o pagamento. | - |
| `qr_code_key` * | string | Chave UUID4 identificadora do QR Code. | - |
| `qr_code_status` * | string | Status do QR Code. | - |
| `qr_code_type` * | string | Tipo do QR Code. | "dynamic_term" ou "dynamic_instant" |
| `amount` * | float | Valor do QR Code antes do cálculo de descontos ou juros e multas. | - |
| `expiration_seconds`  | string | indica qual o tempo de validade do QR Code em segundos, padrão 1 dia. | - |
| `expiration_date` | date | Data de vencimento da cobrança (no formato "YYYY-MM-DD"). | - |
| `max_payment_days` | int32 | Dias máximos para pagamento da cobrança após vencimento. |  - |
| `payer_name` * | string | Nome do pagador. | - |
| `payer_document_number` * | string | CPF/ CNPJ do pagador. | - |
| `payer_request` * | string | Mensagem ao pagador. | - |
| `rebate_amount` | float | Valor absoluto de abatimento antes do pagamento. | - |
| `interest_amount` | float | Valor absoluto por dia de atraso após o vencimento, caso seja pago um dia após o vencimento o valor total será o valor ordinario + multa. |  - |
| `fine_amount` | float | Multa em valor absoluto após o vencimento. |  - |
| `discounts` | array of objects | Configurações de desconto. |  - |
| `additional_data` | array of objects | Informações que serão apresentadas para o pagador. | - |
| `pix_transfer_key` | string | Chave UUID4 identificadora da transação pix correspondente à liquidação do QR Code. | - |
| `paid_amount` | float | Valor do pagamento realizado, considerando multas, descontos e outros. | - |
| `base_64_payload` | string | URL do QR Code para pagamento, em base64. | - |
| `qr_code_events` | array of objects | Lista de mudanças de status pelas quais o QR Code passou. | - |
| `created_at` | datetime | Data e hora que o QR Code foi criado no sistema. | - |

### Objeto qr_code_status

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `active`  | string | QR Code se encontra ativo e disponível para pagamento. | - |
| `finished` | string | QR Code pago. | - |
| `written_off` | string | QR Code foi baixado pelo cliente. | - |
| `bank_written_off` | string | QR Code foi baixado automaticamente devido prazo expirado. | - |

### Objeto discount

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `discount_value` * | float |  Valor do desconto. | - |
| `discount_number` | int32 | Ordem que o desconto deve ser aplicado. | - |
| `discount_limit_date` | string | Data limite do desconto. | - |

### Objeto additional_data

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `key_name` * | string |  Nome do campo | - |
| `value` | string | Valor do campo | - |

### Objeto qr_code_events

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `request_control_key` * | string |  Identificador UUID4 único da request que originou o event. | - |
| `event_type` * | string |  Tipo de evento | "registration", "write_off", "payment" |
| `created_at` * | datetime | Data e hora que o evento foi criado. | - |

STATUS 404

Response Body

```json
{
    "title": "Not found",
    "description": "Could not find the queried QR Code.",
    "translation": "Não possível encontrar o QR Code buscado.",
    "code": "QRI000002"
}

```

---

# Webhook para Pix de Entrada de pagamento de QR Code

URL: /documentation/pix_indireto/qr_code/webhook_incoming_pix

Webhook que servirá para avisar sobre transações Pix que chegaram para um Alias de pagamento de um QR Code vinculado.

## Webhook Request Body

**Request Body: Pagamento QR Code Recebido**

```json
{
  "webhook_type": "baas.pix_qr_code.payment",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "qr_code_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "qr_code_type": "dynamic_instant",
    "receiver_conciliation_id": "faf1ef5b-e0a9-4430-8aa4-367b4825854c",
    "amount": 10.63,
    "updated_at": "2021-10-22T20:30:23.459Z"
  }
}
```

### Webhook Body Param

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `request_control_key` * | string | Identificador UUID4 único da request que originou o QR Code. | - |
| `pix_transfer_key` * | string | Chave Pix que representa a conta de destino da transação. | - |
| `qr_code_key` * | string | Chave UUID4 identificadora do QR Code. | - |
| `qr_code_type` * | string | Tipo do QR Code. | "static", "dynamic_term" ou "dynamic_instant" |
| `receiver_conciliation_id` * | string | Identificador do QR Code para conciliação após o pagamento. | - |
| `amount` * | string | Valor do pagamento. | - |
| `updated_at` * | datetime | Data hora de pagamento QR Code. | - |

---

# Cancelar Relato de Infração

URL: /documentation/pix_indireto/relato_de_infracao/cancelar_relato_infracao

Se um pedido de Relato de Infração foi gerado erroneamente e o Participante Indireto deseja cancelá-lo, é possível fazê-lo utilizando o endpoint citado abaixo.

:::danger IMPORTANTE
Ressalta-se que apenas o Participante o qual CRIOU o Relato de Infração pode cancelá-lo, e o cancelamento pode ser realizado mesmo que o status da infração seja de closed.
:::

:::info IMPORTANTE
Relatos de infração cancelados podem ser listados utilizando o endpoint [Listar Relatos de Infração](#listar-relatos-de-infração)
:::

## Request

ENDPOINT /pix/infraction_report/ INFRACTION_REPORT_KEY
MÉTODO PATCH

**Request Body**

```json
{
    "infraction_report_status": "cancelled",
    "request_control_key": "750cbfa0-f628-4944-a76c-9053bf1ebc87",
}
```

### Path Params
| Campo                   | Tipo   | Descrição                                                     | Caracteres |
| ----------------------- | ------ | ------------------------------------------------------------- | ---------- |
| `infraction_report_key` | string | UUID4 do Relato de Infração criado o qual se deseja cancelar. | 36         |

### Body Params

| Campo                        | Tipo   | Descrição                                                                          | Caracteres |
| ---------------------------- | ------ | ---------------------------------------------------------------------------------- | ---------- |
| `infraction_report_status` * | string | Status o qual se deseja atualizar o Relato de Infração.                            | 36         |
| `request_control_key` *      | string | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36         |

## Response

STATUS 200

**Response Body**

```json
{
   "infraction_report_key":"d7820e2f-1c23-4610-83d6-d9aad1845075",
   "pix_transfer_key":"cdcf0d25-08a1-46e3-902a-6d7ca75e6c48",
   "end_to_end_id":"E99999011202406251332F8n7dMUwOLE",
   "infraction_report_status":"cancelled",
   "infraction_report_situation":"scam",
   "infraction_report_type":"refund_request",
   "infraction_report_details":"usuario caiu em golpe…",
   "debited_participant":"99999010",
   "credited_participant":"99999011",
   "infraction_report_direction": "outgoing",
   "created_at": "2023-03-03T12:04:06.179Z",
   "updated_at": "2023-03-03T12:05:03.421Z"
}
```

### Body Params
| Campo                           | Tipo   | Descrição                                                                                     | Caracteres                                                                                |
| ------------------------------- | ------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `infraction_report_key` *       | string | Identificador único do relato de infração.                                                    | 36                                                                                        |
| `pix_transfer_key` *            | string | Identificador único da transação PIX.                                                         | 36                                                                                        |
| `end_to_end_id` *               | string | Identificador único da transação PIX no BACEN.                                                | 36                                                                                        |
| `infraction_report_status` *    | enum   | Status acerca do Relato de Infração                                                           | **[Enumeradores infraction_report_status](#enumeradores-infraction_report_status)**       |
| `infraction_report_situation` * | enum   | Situação em que ocorreu a infração.                                                           | **[Enumeradores infraction_report_situation](#enumeradores-infraction_report_situation)** |
| `infraction_report_type` *      | enum   | Tipo de Relato de Infração.                                                                   | **[Enumeradores infraction_report_type](#enumeradores-infraction_report_type)**           |
| `infraction_report_details`     | string | Detalhes acerca do Relato de Infração criado.                                                 | \<\= 2000                                                                                 |
| `credited_participant` *        | string | ISPB do Participante Creditado.                                                               | 8                                                                                         |
| `debited_participant` *         | string | ISPB do Participante Debitado.                                                                | 8                                                                                         |
| `infraction_report_direction` * | enum   | Enumerador acerca se o relato foi aberto pelo Participante Indireto ou por outro Participante | **[Enumeradores infraction_report_direction](#enumeradores-infraction_report_direction)** |
| `created_at` *                  | string | Data de criação do Relato de Infração                                                         | 24                                                                                        |
| `updated_at` *                  | string | Data de atualização do Relato de Infração                                                     | 24                                                                                        |

### Enumeradores infraction_report_status
| Campo          | Tipo   | Descrição                                                                     | Caracteres |
| -------------- | ------ | ----------------------------------------------------------------------------- | ---------- |
| `open`         | string | Relato de infração foi <strong>criado</strong> e está aberto no BACEN.        | -          |
| `acknowledged` | string | Relato de infração foi <strong>recebido</strong> pelo participante contestado | -          |
| `cancelled`    | string | Relato de infração está <strong>cancelado</strong> no BACEN                   | -          |
| `closed`       | string | Relato de infração está <strong>fechado</strong> no BACEN                     | -          |

### Enumeradores infraction_report_situation
| Campo               | Tipo   | Descrição                                               | Caracteres |
| ------------------- | ------ | ------------------------------------------------------- | ---------- |
| `scam`              | string | Causa de golpe ou estelionato.                          | -          |
| `account_takeover`  | string | Causa de transação não autorizada pela conta de origem. | -          |
| `coercion`          | string | Causa de crime de coerção.                              | -          |
| `fraudulent_access` | string | Causa de acesso fraudulento à conta de origem.          | -          |
| `other`             | string | Quaisquer causas não aplicáveis às listadas acima.      | -          |

### Enumeradores infraction_report_type
| Campo              | Tipo   | Descrição                                                              | Caracteres |
| ------------------ | ------ | ---------------------------------------------------------------------- | ---------- |
| `refund_request`   | string | Relato de infração será gerado a fim de se solicitar uma devolução.    | -          |
| `refund_cancelled` | string | Relato de infração será gerado pelo motivo de uma devolução cancelada. | -          |

### Enumeradores infraction_report_direction
| Campo      | Tipo   | Descrição                                                     | Caracteres |
| ---------- | ------ | ------------------------------------------------------------- | ---------- |
| `incoming` | string | Relato de infração com participante indireto como alvo.       | -          |
| `outgoing` | string | Relato de infração com participante indireto como originador. | -          |

---

# Consultar Relato de Infração

URL: /documentation/pix_indireto/relato_de_infracao/consultar_relato_infracao

O Participante Indireto pode consultar os dados acerca de um Relato de Infração, inclusive todas as alterações que ocorreram com o mesmo.

## Request

ENDPOINT /pix/infraction_report/ INFRACTION_REPORT_KEY
MÉTODO GET

### Path Params
| Campo                   | Tipo   | Descrição                    | Caracteres |
| ----------------------- | ------ | ---------------------------- | ---------- |
| `infraction_report_key` | string | UUID4 do Relato de Infração. | 36         |

## Response

STATUS 200

**Response Body**

```json
{
   "infraction_report_key":"d7820e2f-1c23-4610-83d6-d9aad1845075",
   "pix_transfer_key":"cdcf0d25-08a1-46e3-902a-6d7ca75e6c48",
   "end_to_end_id":"E99999010202406251332F8n7dMUwOLE",
   "infraction_report_status":"cancelled",
   "infraction_report_situation":"scam",
   "infraction_report_type":"refund_request",
   "report_details":"usuario caiu em golpe…",
   "debited_participant":"99999011",
   "credited_participant":"99999010",
   "infraction_report_direction": "incoming",
   "infraction_report_events": [
     {
       "event_type": "acknowledged",
       "event_details": "Relato de Infração recebido e em análise",
       "created_at": "2023-03-03T12:04:06.179Z"
     },
     {
       "event_type": "cancelled",
       "event_details": "Relato de Infração cancelado",
       "created_at": "2023-03-03T12:04:06.179Z"
     }
   ],
  "created_at": "2023-03-03T12:04:06.179Z",
  "updated_at": "2023-03-03T12:04:06.179Z"
}
```

### Body Params
| Campo                           | Tipo   | Descrição                                                                                     | Caracteres                                                                                |
| ------------------------------- | ------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `infraction_report_key` *       | string | Identificador único do relato de infração.                                                    | 36                                                                                        |
| `pix_transfer_key` *            | string | Identificador único da transação PIX.                                                         | 36                                                                                        |
| `end_to_end_id` *               | string | Identificador único da transação PIX no BACEN.                                                | 36                                                                                        |
| `infraction_report_status` *    | enum   | Status .                                                                                      | **[Enumeradores infraction_report_status](#enumeradores-infraction_report_status)**       |
| `infraction_report_situation` * | enum   | Situação em que ocorreu a infração.                                                           | **[Enumeradores infraction_report_situation](#enumeradores-infraction_report_situation)** |
| `infraction_report_type` *      | enum   | Tipo de Relato de Infração.                                                                   | **[Enumeradores infraction_report_type](#enumeradores-infraction_report_type)**           |
| `infraction_report_details`     | string | Detalhes acerca do Relato de Infração criado.                                                 | \<\= 2000                                                                                 |
| `credited_participant` *        | string | ISPB do Participante Creditado.                                                               | 8                                                                                         |
| `debited_participant` *         | string | ISPB do Participante Debitado.                                                                | 8                                                                                         |
| `infraction_report_direction` * | enum   | Enumerador acerca se o relato foi aberto pelo Participante Indireto ou por outro Participante | **[Enumeradores infraction_report_direction](#enumeradores-infraction_report_direction)** |
| `infraction_report_events`*     | object | Eventos relacionados ao Relato de Infração.                                                   | **[Objetos infraction_report_events](#objetos-infraction_report_events)**                 |
| `created_at` *                  | string | Horário de criação do Relato de Infração                                                      | 24                                                                                        |
| `updated_at`                    | string | Horário de atualização do Relato de Infração                                                  | 24                                                                                        |

### Enumeradores infraction_report_status

| Campo          | Tipo   | Descrição                                                                     | Caracteres |
| -------------- | ------ | ----------------------------------------------------------------------------- | ---------- |
| `open`         | string | Relato de infração foi <strong>criado</strong> e está aberto no BACEN.        | 4          |
| `acknowledged` | string | Relato de infração foi <strong>recebido</strong> pelo participante contestado | 12         |
| `cancelled`    | string | Relato de infração está <strong>cancelado</strong> no BACEN                   | 9          |
| `closed`       | string | Relato de infração está <strong>fechado</strong> no BACEN                     | 6          |

### Enumeradores infraction_report_situation
| Campo               | Tipo   | Descrição                                               | Caracteres |
| ------------------- | ------ | ------------------------------------------------------- | ---------- |
| `scam`              | string | Causa de golpe ou estelionato.                          | -          |
| `account_takeover`  | string | Causa de transação não autorizada pela conta de origem. | -          |
| `coercion`          | string | Causa de crime de coerção.                              | -          |
| `fraudulent_access` | string | Causa de acesso fraudulento à conta de origem.          | -          |
| `other`             | string | Quaisquer causas não aplicáveis às listadas acima.      | -          |

### Enumeradores infraction_report_type
| Campo              | Tipo   | Descrição                                                              | Caracteres |
| ------------------ | ------ | ---------------------------------------------------------------------- | ---------- |
| `refund_request`   | string | Relato de infração será gerado a fim de se solicitar uma devolução.    | -          |
| `refund_cancelled` | string | Relato de infração será gerado pelo motivo de uma devolução cancelada. | -          |

### Enumeradores infraction_report_direction
| Campo      | Tipo   | Descrição                                                     | Caracteres |
| ---------- | ------ | ------------------------------------------------------------- | ---------- |
| `incoming` | string | Relato de infração com participante indireto como alvo.       | -          |
| `outgoing` | string | Relato de infração com participante indireto como originador. | -          |

### Objetos infraction_report_events
| Campo           | Tipo   | Descrição                                | Caracteres                                                                          |
| --------------- | ------ | ---------------------------------------- | ----------------------------------------------------------------------------------- |
| `event_type`    | enum   | Mudança de status relacionada ao evento. | **[Enumeradores infraction_report_status](#enumeradores-infraction_report_status)** |
| `event_details` | string | Descrição do evento.                     | -                                                                                   |
| `created_at` *  | string | Horário de criação do evento             | 24                                                                                  |

---

# Abrir Relato de Infração

URL: /documentation/pix_indireto/relato_de_infracao/criar_relato_infracao

O Relato de Infração é um dos serviços o qual compoẽ o Mecanismo Especial de Devolução (MED) como definido pelo Banco Central do Brasil.

Quando há um indício de uma transação, pedido de devolução ou cancelamento de pedido de devolução fraudulentos, é possível criar um relato de infração a fim de se informar o BACEN e o outro Participante que há uma irregularidade em uma destas operações citadas. 

Tanto o Participante debitado quanto creditado podem criar um Relato de Infração.

:::caution **Atenção**

A fim de se compreender o fluxo de Relato de Infração, é necessário saber quais ENDPOINTS o Participante Indireto que criou o relato pode utilizar.

Quando o Participante Indireto abre um Relato de Infração, este pode (se necessário) cancelar o relato caso tenha sido gerado de maneira indevida.

Quando o Participante Indireto recebe um Relato de Infração, este deve fechá-lo informando o resultado da análise do relato.

Ambos os fluxos citados serão descritos nas seções seguintes.

:::

:::danger IMPORTANTE
O Banco Central do Brasil define que, dentro de um período de 7 dias do recebimento do Relato de Infração pelo Participante Indireto, o Relato precisa ser fechado .

Caso haja atraso por parte do Participante Indireto, a QI Tech irá fechar o Relato de Infração, com o status de agreed , a fim de que a instituição não seja penalizada pelo Banco Central do Brasil.
:::

:::info IMPORTANTE
Apenas o participante originador da transferência pode criar um relato de infração sobre a mesma
:::

## Request

ENDPOINT /pix/infraction_report
MÉTODO POST

**Request Body**

```json
{
    "pix_transfer_key": "c09fef15-ab30-469c-a1d4-4e9dd479943a",
    "request_control_key": "c09fef15-ab30-469c-a1d4-4e9dd479943a",
    "infraction_report_type": "refund_request",
    "infraction_report_details": "Foi identificado uma fraude na transação",
    "infraction_report_situation": "scam"
}
```

### Body Params

| Campo                         | Tipo   | Descrição                                             | Caracteres                                                                                |
| ----------------------------- | ------ | ----------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `request_control_key` *       | uuidv4 | UUID4 para fins de consulta sobre a requisição feita. | 36                                                                                        |
| `pix_transfer_key` *          | uuidv4 | Identificador único da transação PIX.                 | 36                                                                                        |
| `infraction_report_type` *    | enum   | Tipo de relato de infração a ser criado.              | **[Enumeradores infraction_report_type](#enumeradores-infraction_report_type)**                  |
| `infraction_report_details`   | string | Detalhes acerca do relato de infração a ser criado.   | 10                                                                                        |
| `infraction_report_situation` | string | Situação em que ocorreu a infração.                   | **[Enumeradores infraction_report_situation](#enumeradores-infraction_report_situation)** |

### Enumeradores infraction_report_type

| Campo              | Tipo   | Descrição                                                             | Caracteres |
| ------------------ | ------ | --------------------------------------------------------------------- | ---------- |
| `refund_cancelled` | string | Relato de infração será gerado pelo motivo de uma devolução cancelada | 16         |
| `refund_request`   | string | Relato de infração será gerado a fim de se solicitar uma devolução    | 14         |

### Enumeradores infraction_report_situation

| Campo               | Tipo   | Descrição                                               | Caracteres |
| ------------------- | ------ | ------------------------------------------------------- | ---------- |
| `scam`              | string | Causa de golpe ou estelionato.                          | -          |
| `account_takeover`  | string | Causa de transação não autorizada pela conta de origem. | -          |
| `coercion`          | string | Causa de crime de coerção.                              | -          |
| `fraudulent_access` | string | Causa de acesso fraudulento à conta de origem.          | -          |
| `other`             | string | Quaisquer causas não aplicáveis às listadas acima.      | -          |

## Response

STATUS 200

**Response Body**

```json
{
    "infraction_report_key":"d7820e2f-1c23-4610-83d6-d9aad1845075",
    "pix_transfer_key":"cdcf0d25-08a1-46e3-902a-6d7ca75e6c48",
    "end_to_end_id":"E99999010202406251332F8n7dMUwOLE",
    "infraction_report_status":"acknowledged",
    "infraction_report_situation":"scam",
    "infraction_report_type":"refund_request",
    "report_details":"usuario caiu em golpe…",
    "debited_participant":"99999011",
    "credited_participant":"99999010",
    "infraction_report_direction": "outgoing",
    "created_at": "2023-03-03T12:04:06.179Z",
    "updated_at": "2023-03-03T12:04:06.179Z"
}
```

### Body Params

| Campo                           | Tipo   | Descrição                                                                                     | Caracteres                                                                                |
| ------------------------------- | ------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `infraction_report_key` *       | string | Identificador único do relato de infração.                                                    | 36                                                                                        |
| `pix_transfer_key` *            | string | Identificador único da transação PIX.                                                         | 36                                                                                        |
| `end_to_end_id` *               | string | Identificador único da transação PIX no BACEN.                                                | 36                                                                                        |
| `infraction_report_status` *    | enum   | Status .                                                                                      | **[Enumeradores infraction_report_status](#enumeradores-infraction_report_status)**       |
| `infraction_report_situation` * | enum   | Situação em que ocorreu a infração.                                                           | **[Enumeradores infraction_report_situation](#enumeradores-infraction_report_situation)** |
| `infraction_report_type` *      | enum   | Tipo de Relato de Infração.                                                                   | **[Enumeradores infraction_report_type](#enumeradores-infraction_report_type)**           |
| `infraction_report_details`     | string | Detalhes acerca do Relato de Infração criado.                                                 | \<\= 2000                                                                                 |
| `credited_participant` *        | string | ISPB do Participante Creditado.                                                               | 8                                                                                         |
| `debited_participant` *         | string | ISPB do Participante Debitado.                                                                | 8                                                                                         |
| `infraction_report_direction` * | enum   | Enumerador acerca se o relato foi aberto pelo Participante Indireto ou por outro Participante | **[Enumeradores infraction_report_direction](#enumeradores-infraction_report_direction)** |
| `created_at` *                  | string | Horário de criação do Relato de Infração                                                      | 24                                                                                        |
| `updated_at`                    | string | Horário de atualização do Relato de Infração                                                  | 24                                                                                        |

### Enumeradores infraction_report_status

| Campo          | Tipo   | Descrição                                                                     | Caracteres |
| -------------- | ------ | ----------------------------------------------------------------------------- | ---------- |
| `open`         | string | Relato de infração foi <strong>criado</strong> e está aberto no BACEN.        | -          |
| `acknowledged` | string | Relato de infração foi <strong>recebido</strong> pelo participante contestado | -          |
| `cancelled`    | string | Relato de infração está <strong>cancelado</strong> no BACEN                   | -          |
| `closed`       | string | Relato de infração está <strong>fechado</strong> no BACEN                     | -          |

### Enumeradores infraction_report_direction
| Campo      | Tipo   | Descrição                                                     | Caracteres |
| ---------- | ------ | ------------------------------------------------------------- | ---------- |
| `incoming` | string | Relato de infração com participante indireto como alvo.       | -          |
| `outgoing` | string | Relato de infração com participante indireto como originador. | -          |

---

# Fechar Relato de Infração

URL: /documentation/pix_indireto/relato_de_infracao/fechar_relato_infracao

A QI Tech será responsável por realizar um pooling no Banco Central do Brasil a fim de se verificar se há Relato(s) de Infração criados por outros Participantes para o Participante Indireto, e enviará o webhook de recebimento já com o status acknowledged para o mesmo.

A fim de informar o Participante Indireto de que há um Relato de Infração a ser respondido pelo mesmo, a QI Tech irá fazer um webhook de recebimento no mesmo.

:::danger IMPORTANTE
Ressalta-se que apenas o Participante o qual RECEBEU o Relato de Infração pode fechá-lo.
:::

:::danger IMPORTANTE
O Banco Central do Brasil define que, dentro de um período de 7 dias do recebimento do Relato de Infração pelo Participante Indireto, o Relato precisa ser fechado .

Caso haja atraso por parte do Participante Indireto, a QI Tech irá fechar o Relato de Infração, com o status de agreed, 6 dias corridos após o envio do webhook de recebimento da infração, a fim de que a instituição não seja penalizada pelo Banco Central do Brasil.
:::

Para o fechamento do relato de infração, o status deve ser acknowledged .

## Request

ENDPOINT /pix/infraction_report/ INFRACTION_REPORT_KEY
MÉTODO PATCH

**Request Body - Aceite**

```json
{
    "infraction_report_status": "closed",
    "request_control_key": "feb59932-be7a-4584-9830-02ed8bc0aa77",
    "analysis_result": "agreed",
    "fraud_type": "application_fraud",
    "analysis_details": "Valor bloqueado. Para mais informações ligue para (11) 98871-1385.",
}
```

**Request Body - Recusa**

```json
{
    "infraction_report_status": "closed",
    "request_control_key": "feb59932-be7a-4584-9830-02ed8bc0aa77",
    "analysis_result": "disagreed",
    "analysis_details": "Valor bloqueado. Para mais informações ligue para (11) 98871-1385.",
}
```

### Path Params
| Campo                   | Tipo   | Descrição                                                   | Caracteres |
| ----------------------- | ------ | ----------------------------------------------------------- | ---------- |
| `infraction_report_key` | string | UUID4 do Relato de Infração criado o qual se deseja fechar. | 36         |

### Body Params

| Campo                        | Tipo   | Descrição                                                                                                    | Caracteres                                                                          |
| ---------------------------- | ------ | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| `analysis_result` *          | enum   | Resultado da análise.                                                                                        | **[Enumeradores analysis_result](#enumeradores-analysis_result)**                   |
| `request_control_key` *      | uuidv4 | UUID4 para fins de consulta sobre a requisição feita.                                                        | 36                                                                                  |
| `infraction_report_status` * | enum   | Status o qual se deseja 'setar' o relato de infração.                                                        | **[Enumeradores infraction_report_status](#enumeradores-infraction_report_status)** |
| `fraud_type`                 | enum   | Tipo de fraude constatada. Não pertencente à entidade infraction report, porém necessário para o fechamento. | **[Enumeradores fraud_type](#enumeradores-fraud_type)**                             |
| `analysis_details`           | string | Descrição acerca do resultado da análise                                                                     | 250                                                                                 |

### Enumeradores analysis_result

| Campo       | Tipo   | Descrição                                                                                                  | Caracteres |
| ----------- | ------ | ---------------------------------------------------------------------------------------------------------- | ---------- |
| `agreed`    | string | O Participante Indireto <strong>concorda</strong> com o Relato de Infração criado pelo outro Participante. | -          |
| `disagreed` | string | O Participante Indireto <strong>discorda</strong> com o Relato de Infração criado pelo outro Participante. | -          |

### Enumeradores infraction_report_status

| Campo          | Tipo   | Descrição                                                              | Caracteres |
| -------------- | ------ | ---------------------------------------------------------------------- | ---------- |
| `open`         | string | Relato de infração foi <strong>criado</strong> e está aberto no BACEN. | -          |
| `acknowledged` | string | Relato de infração foi <strong>recebido</strong> pelo participante     | -          |
| `cancelled`    | string | Relato de infração está <strong>cancelado</strong> no BACEN            | -          |
| `closed`       | string | Relato de infração está <strong>fechado</strong> no BACEN              | -          |

### Enumeradores fraud_type

| Campo               | Tipo   | Descrição                                                            | Caracteres |
| ------------------- | ------ | -------------------------------------------------------------------- | ---------- |
| `application_fraud` | string | Fraude por falsidade ideológica, com documentos de outra pessoa.     | -          |
| `mule_account`      | string | Fraude por conta laranja, aberta de forma legítma.                   | -          |
| `scammer_account`   | string | Fraude na qual a conta destino esta no nome do verdadeiro fraudador. | -          |
| `other`             | string | Fraude de outra naturaza, não enquadrada nos enumeradores acima.     | -          |

## Response

STATUS 200

**Response Body**

```json
{
   "infraction_report_key":"d7820e2f-1c23-4610-83d6-d9aad1845075",
   "pix_transfer_key":"cdcf0d25-08a1-46e3-902a-6d7ca75e6c48",
   "end_to_end_id":"E99999011202406251332F8n7dMUwOLE",
   "infraction_report_status":"cancelled",
   "infraction_report_situation":"scam",
   "infraction_report_type":"refund_request",
   "infraction_report_details":"usuario caiu em golpe…",
   "debited_participant":"99999010",
   "credited_participant":"99999011",
   "analysis_result": "agreed",
   "analysis_details": "Valor bloqueado. Para mais informações ligue para (11) 98871-1385.",
   "infraction_report_direction": "incoming",
   "created_at": "2023-03-03T12:04:06.179Z",
   "updated_at": "2023-03-03T12:05:03.421Z",
}
```

### Body Params
| Campo                           | Tipo   | Descrição                                                                                     | Caracteres                                                                                |
| ------------------------------- | ------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `infraction_report_key` *       | string | Identificador único do relato de infração.                                                    | 36                                                                                        |
| `pix_transfer_key` *            | string | Identificador único da transação PIX.                                                         | 36                                                                                        |
| `end_to_end_id` *               | string | Identificador único da transação PIX no BACEN.                                                | 36                                                                                        |
| `infraction_report_status` *    | enum   | Status acerca do Relato de Infração                                                           | **[Enumeradores infraction_report_status](#enumeradores-infraction_report_status)**       |
| `infraction_report_situation` * | enum   | Situação em que ocorreu a infração.                                                           | **[Enumeradores infraction_report_situation](#enumeradores-infraction_report_situation)** |
| `infraction_report_type` *      | enum   | Tipo de Relato de Infração.                                                                   | **[Enumeradores infraction_report_type](#enumeradores-infraction_report_type)**           |
| `infraction_report_details`     | string | Detalhes acerca do Relato de Infração criado.                                                 | \<\= 2000                                                                                 |
| `credited_participant` *        | string | ISPB do Participante Creditado.                                                               | 8                                                                                         |
| `debited_participant` *         | string | ISPB do Participante Debitado.                                                                | 8                                                                                         |
| `analysis_result` *             | string | Resultado da análise.                                                                         | **[Enumeradores analysis_result](#enumeradores-analysis_result)**                         |
| `analysis_details` *            | string | Descrição acerca do resultado da análise.                                                     | 250                                                                                       |
| `infraction_report_direction` * | enum   | Enumerador acerca se o relato foi aberto pelo Participante Indireto ou por outro Participante | **[Enumeradores infraction_report_direction](#enumeradores-infraction_report_direction)** |
| `created_at` *                  | string | Data de criação do Relato de Infração                                                         | 24                                                                                        |
| `updated_at` *                  | string | Data de atualização do Relato de Infração                                                     | 24                                                                                        |

### Enumeradores infraction_report_situation

| Campo               | Tipo   | Descrição                                               | Caracteres |
| ------------------- | ------ | ------------------------------------------------------- | ---------- |
| `scam`              | string | Causa de golpe ou estelionato.                          | -          |
| `account_takeover`  | string | Causa de transação não autorizada pela conta de origem. | -          |
| `coercion`          | string | Causa de crime de coerção.                              | -          |
| `fraudulent_access` | string | Causa de acesso fraudulento à conta de origem.          | -          |
| `other`             | string | Quaisquer causas não aplicáveis às listadas acima.      | -          |

### Enumeradores infraction_report_type

| Campo              | Tipo   | Descrição                                                              | Caracteres |
| ------------------ | ------ | ---------------------------------------------------------------------- | ---------- |
| `refund_request`   | string | Relato de infração será gerado a fim de se solicitar uma devolução.    | -          |
| `refund_cancelled` | string | Relato de infração será gerado pelo motivo de uma devolução cancelada. | -          |

### Enumeradores infraction_report_direction

| Campo      | Tipo   | Descrição                                                     | Caracteres |
| ---------- | ------ | ------------------------------------------------------------- | ---------- |
| `incoming` | string | Relato de infração com participante indireto como alvo.       | -          |
| `outgoing` | string | Relato de infração com participante indireto como originador. | -          |

---

# Listar Relatos de Infração

URL: /documentation/pix_indireto/relato_de_infracao/listar_relatos

Caso o Participante Indireto solicite a listagem de Relatos de Infração, pode fazê-lo por meio da rota abaixo.
## Request

ENDPOINT /pix/infraction_reports
MÉTODO GET

### Query Params
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `infraction_report_status` | enum | Status do Relato de Infração. | **[Enumeradores infraction_report_status](#enumeradores-infraction_report_status)** |
| `infraction_report_type` | enum | Tipo do Relato de Infração. | **[Enumeradores infraction_report_type](#enumeradores-infraction_report_type)** |
| `initial_date` | string | Data inicial de busca. | **[Formato de data](#formato-de-data)** |
| `final_date` | string | Data final de busca. | **[Formato de data](#formato-de-data)** |
| `page_number` | integer | Página atual que está sendo consultada. | - |
| `page_size` | integer | Quantidade de resultados por página. | - |

### Formato de data

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `initial_date` | string | Data de inicio para a procura, em formato "%Y-%m-%d. Exemplo: "2023-10-09".| 10 |
| `final_date` | string | Data final para a procura, em formato "%Y-%m-%d. Exemplo: "2023-10-11".| 10 |

## Response

STATUS 200

**Response Body**

```json
{
    "data": [
        {
            "infraction_report_key":"2b4b262d-fa31-4bb5-87f9-52ef1d243275",
            "pix_transfer_key":"16125a82-1842-4f29-a895-c80e14c70e44",
            "end_to_end_id":"E99999010202406251332F8n7dMUwOLE",
            "infraction_report_status":"cancelled",
            "infraction_report_situation":"scam",
            "infraction_report_type":"refund_request",
            "report_details":"usuario caiu em golpe…",
            "debited_participant":"99999011",
            "credited_participant":"99999010",
            "infraction_report_direction": "incoming",
            "infraction_report_events": [
                {
                "event_type": "acknowledged",
                "event_details": "Relato de Infração recebido e em análise",
                "created_at": "2023-03-03T12:04:06.179Z"
                },
                {
                "event_type": "cancelled",
                "event_details": "Relato de Infração cancelado",
                "created_at": "2023-03-03T12:04:06.179Z"
                }
            ],
            "created_at": "2023-03-03T12:04:06.179Z",
            "updated_at": "2023-03-03T12:04:06.179Z"
        },
        {
            "infraction_report_key":"facb89f7-49bb-41fd-8a4d-98792880a6f2",
            "pix_transfer_key":"a913cfb4-0c4a-4069-99f2-7ab34b6a4bf9",
            "end_to_end_id":"E99999010202406251332F8n7dMUwOLA",
            "infraction_report_status":"acknowledged",
            "infraction_report_situation":"scam",
            "infraction_report_type":"refund_request",
            "report_details":"usuario caiu em golpe de novo…",
            "debited_participant":"99999011",
            "credited_participant":"99999010",
            "infraction_report_direction": "incoming",
            "infraction_report_events": [
                {
                "event_type": "acknowledged",
                "event_details": "Relato de Infração recebido e em análise",
                "created_at": "2023-03-03T12:04:06.179Z"
                },
            ],
            "created_at": "2023-03-03T12:04:06.179Z",
            "updated_at": "2023-03-03T12:04:06.179Z"
        },
    ],
    "pagination": {
        "current_page": 1,
        "next_page": null,
        "rows_per_page": 10
    }
}
```

### Body Params
| Campo                           | Tipo   | Descrição                                                                                     | Caracteres                                                                                |
| ------------------------------- | ------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `infraction_report_key` *       | string | Identificador único do relato de infração.                                                    | 36                                                                                        |
| `pix_transfer_key` *            | string | Identificador único da transação PIX.                                                         | 36                                                                                        |
| `end_to_end_id` *               | string | Identificador único da transação PIX no BACEN.                                                | 36                                                                                        |
| `infraction_report_status` *    | enum   | Status .                                                                                      | **[Enumeradores infraction_report_status](#enumeradores-infraction_report_status)**       |
| `infraction_report_situation` * | enum   | Situação em que ocorreu a infração.                                                           | **[Enumeradores infraction_report_situation](#enumeradores-infraction_report_situation)** |
| `infraction_report_type` *      | enum   | Tipo de Relato de Infração.                                                                   | **[Enumeradores infraction_report_type](#enumeradores-infraction_report_type)**           |
| `infraction_report_details`     | string | Detalhes acerca do Relato de Infração criado.                                                 | \<\= 2000                                                                                 |
| `credited_participant` *        | string | ISPB do Participante Creditado.                                                               | 8                                                                                         |
| `debited_participant` *         | string | ISPB do Participante Debitado.                                                                | 8                                                                                         |
| `infraction_report_direction` * | enum   | Enumerador acerca se o relato foi aberto pelo Participante Indireto ou por outro Participante | **[Enumeradores infraction_report_direction](#enumeradores-infraction_report_direction)** |
| `infraction_report_events`*     | object | Eventos relacionados ao Relato de Infração.                                                   | **[Objetos infraction_report_events](#objetos-infraction_report_events)**                 |
| `created_at` *                  | string | Horário de criação do Relato de Infração                                                      | 24                                                                                        |
| `updated_at`                    | string | Horário de atualização do Relato de Infração                                                  | 24                                                                                        |

### Enumeradores infraction_report_status

| Campo          | Tipo   | Descrição                                                                     | Caracteres |
| -------------- | ------ | ----------------------------------------------------------------------------- | ---------- |
| `open`         | string | Relato de infração foi <strong>criado</strong> e está aberto no BACEN.        | 4          |
| `acknowledged` | string | Relato de infração foi <strong>recebido</strong> pelo participante contestado | 12         |
| `cancelled`    | string | Relato de infração está <strong>cancelado</strong> no BACEN                   | 9          |
| `closed`       | string | Relato de infração está <strong>fechado</strong> no BACEN                     | 6          |

### Enumeradores infraction_report_situation
| Campo               | Tipo   | Descrição                                               | Caracteres |
| ------------------- | ------ | ------------------------------------------------------- | ---------- |
| `scam`              | string | Causa de golpe ou estelionato.                          | -          |
| `account_takeover`  | string | Causa de transação não autorizada pela conta de origem. | -          |
| `coercion`          | string | Causa de crime de coerção.                              | -          |
| `fraudulent_access` | string | Causa de acesso fraudulento à conta de origem.          | -          |
| `other`             | string | Quaisquer causas não aplicáveis às listadas acima.      | -          |

### Enumeradores infraction_report_type
| Campo              | Tipo   | Descrição                                                              | Caracteres |
| ------------------ | ------ | ---------------------------------------------------------------------- | ---------- |
| `refund_request`   | string | Relato de infração será gerado a fim de se solicitar uma devolução.    | -          |
| `refund_cancelled` | string | Relato de infração será gerado pelo motivo de uma devolução cancelada. | -          |

### Enumeradores infraction_report_direction
| Campo      | Tipo   | Descrição                                                     | Caracteres |
| ---------- | ------ | ------------------------------------------------------------- | ---------- |
| `incoming` | string | Relato de infração com participante indireto como alvo.       | -          |
| `outgoing` | string | Relato de infração com participante indireto como originador. | -          |

### Objetos infraction_report_events
| Campo           | Tipo   | Descrição                                | Caracteres                                                                          |
| --------------- | ------ | ---------------------------------------- | ----------------------------------------------------------------------------------- |
| `event_type`    | enum   | Mudança de status relacionada ao evento. | **[Enumeradores infraction_report_status](#enumeradores-infraction_report_status)** |
| `event_details` | string | Descrição do evento.                     | -                                                                                   |
| `created_at` *  | string | Horário de criação do evento             | 24                                                                                  |

---

# Introdução ao fluxo de Relato de Infração

URL: /documentation/pix_indireto/relato_de_infracao/maquina_estados

## Introdução

O Banco Central do Brasil permite que, caso haja uma infração em uma transação PIX, podendo esta ser uma transação comum ou uma devolução, que o Participante Indireto possa informar o outro Participante envolvido no fluxo de que há uma irregularidade.

:::info 

Ressalta-se que, para uma transação PIX, somente o Participante creditado pode abrir um Relato de Infração.

:::

:::danger IMPORTANTE

O Banco Central do Brasil define que, dentro de um período de 7 dias do recebimento do Relato de Infração pelo Participante Indireto, o Relato precisa ser fechado .

Caso haja atraso por parte do Participante Indireto, a QI Tech irá fechar o Relato de Infração, com o status de agreed, 6 dias corridos após o envio do webhook de recebimento da infração, a fim de que a instituição não seja penalizada pelo Banco Central do Brasil.

:::

## Máquina de Estados Infraction_Report_Status

| Enumerador | Tradução | Descrição|
|---|---|---|
|  open  | aberto | Após o processamento da <strong>criação</strong> do Relato de Infração, o mesmo fica aberto no BACEN. 
|  acknowledged  | recebido | A QI Tech recebeu um Relato de Infração o qual possui o Participante Indireto como alvo, e irá encaminhá-lo (relato) via webhook. 
|  cancelled  | cancelado | O Participante que abriu o relato enviou o cancelamento e o mesmo está <strong>cancelado</strong> no BACEN.
|  closed  | fechado | O fechamento do Relato de Infração foi processado pela QI Tech e está <strong>fechado</strong> no BACEN.

## Controle da Máquina de Estados Infraction_Report_Status

Mesmo o fluxo sendo síncrono, é necessário que o Participante Indireto conheça os status os quais um Relato de Infração pode ter. Abaixo, está descrito o que o Participante pode esperar após abrir, cancelar, completar e receber um Relato de Infração.

### Participante Abre Relato de Infração

O Participante Indireto pode abrir um Relato de Infração no Banco Central. O único requisito, para a abertura do Relato, é de que uma transação tenha sido feita via PIX.

O Participante Indireto não pode abrir um segundo Relato de Infração para uma mesma transação, mesmo que o primeiro Relato já esteja fechado.

### Participante Cancela Relato de Infração

Após o Participante Indireto ter aberto um Relato de Infração, o Participante pode solicitar o cancelamento deste, se necessário, independente do status do mesmo.

### Participante Recebe Relato de Infração

No fluxo de incoming infraction, o recebimento (status acknowledged) é feito de maneira automática pela QI Tech, e será feito o envio do webhook ao Participante Indireto com a infração recebida.

No fluxo de outgoing, o recebimento de um relato pela contraparte não resulta em atualização de status interna, visto que essa ação não resulta numa alteração da entidade Infração.

O Participante Indireto receberá o Relato de Infração com o status de acknowledged

### Participante Fecha Relato de Infração

Após o Participante Indireto ter sido informado de que há um Relato de Infração com o status de acknowledged , este deve fechá-lo.

O Participante Indireto deverá informar, no fechamento, o resultado da análise feita, podendo rejeitar o Relato de Infração, ou aceitá-lo no prazo de 6 dias corridos à partir do webhook de recebimento do mesmo, apoś esse período, caso não haja resposta, o mesmo será aceito automaticamente pela QI Tech a fim de manter o compromisso com o BACEN e o SPI de tempos de resposta.

## Controle da Máquina de Estados Infraction_Report_Direction

| Enumerador | Tradução | Descrição|
|---|---|---|
|  incoming  | vindo | O Participante Indireto recebeu o Relato de Infração de um outro Participante. 
|  outgoing  | enviado | O Participante Indireto enviou o Relato de Infração a um outro Participante.

## Participande Indireto Recebe/Fecha Relato de Infração

Neste caso, o campo "infraction_report_direction" será de "incoming".

## Participande Indireto Envia/Cancela Relato de Infração

Neste caso, o campo "infraction_report_direction" será de "outgoing".

Ressalta-se que nenhum destes campos será enviado pelo Participante Indireto. Contém apenas na resposta da requisição.

---

# Simulação de Cenários

URL: /documentation/pix_indireto/relato_de_infracao/simulacao_de_cenarios

Passo a passo para simular a efetivação de ações feitas por agentes externos. Essas simulações incluem recebimentos e atualizações de relatos de infração .

:::info Informação
Não há payload de retorno (response body) nessas requisições, somente response status de 204. O conteúdo gerado pelo mock deve ser recebido via webhook. 
:::

## 1 - Simulação de recebimento de relato de infração

Simula o recebimento de um relato de infração aberto por outra instituição.

:::info IMPORTANTE
É essencial possuir uma pix_transfer_key válida para mandar a request, não importando necessariamente as informações da outra parte da transferencia, visto que todas as informações do segundo participante serão substituidas no processo de mock.
:::

### Request

ENDPOINT /mock/pix/infraction_report
MÉTODO POST

Request Body

```json
{
  "infraction_report_status": "acknowledged",
  "pix_transfer_key": "28290ff2-2ba7-4e85-9a5e-862c92259b33",
  "infraction_report_type": "refund_request",
  "infraction_report_situation": "scam",
  "infraction_report_details": "Transação com suspeita de fraude.",
}
```

### Objeto Request Body

| Campo                             | Tipo   | Descrição                                                    | Máx. Caract.                                                                              |
| --------------------------------- | ------ | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| **infraction_report_status\***    | string | Status de recebimento do relato de infração. "acknowledged". | **[Enumeradores infraction_report_status](#enumeradores-infraction_report_status)**       |
| **pix_transfer_key\***            | string | UUID4, chave única que identifica a transação relacionada.   | 36                                                                                        |
| **infraction_report_type\***      | string | Tipo de Relato de Infração                                   | **[Enumeradores infraction_report_type](#enumeradores-infraction_report_type)**           |
| **infraction_report_situation\*** | string | Situação em que ocorreu a infração                           | **[Enumeradores infraction_report_situation](#enumeradores-infraction_report_situation)** |
| **infraction_report_details\***   | string | Detalhes do relato de infração                               | 2000                                                                                      |

### Enumeradores infraction_report_status

| Campo          | Tipo   | Descrição                                                              | Caracteres |
| -------------- | ------ | ---------------------------------------------------------------------- | ---------- |
| `open`         | string | Relato de infração foi <strong>criado</strong> e está aberto no BACEN. | -          |
| `acknowledged` | string | Relato de infração foi <strong>recebido</strong> pelo participante     | -          |
| `cancelled`    | string | Relato de infração está <strong>cancelado</strong> no BACEN            | -          |
| `closed`       | string | Relato de infração está <strong>fechado</strong> no BACEN              | -          |

### Enumeradores infraction_report_type

| Campo              | Tipo   | Descrição                                                              | Caracteres |
| ------------------ | ------ | ---------------------------------------------------------------------- | ---------- |
| `refund_request`   | string | Relato de infração será gerado a fim de se solicitar uma devolução.    | -          |
| `refund_cancelled` | string | Relato de infração será gerado pelo motivo de uma devolução cancelada. | -          |

### Enumeradores infraction_report_situation

| Campo               | Tipo   | Descrição                                               | Caracteres |
| ------------------- | ------ | ------------------------------------------------------- | ---------- |
| `scam`              | string | Causa de golpe ou estelionato.                          | -          |
| `account_takeover`  | string | Causa de transação não autorizada pela conta de origem. | -          |
| `coercion`          | string | Causa de crime de coerção.                              | -          |
| `fraudulent_access` | string | Causa de acesso fraudulento à conta de origem.          | -          |
| `other`             | string | Quaisquer causas não aplicáveis às listadas acima.      | -          |

## 2 - Simulação de atualização de um relato de infração

Simula a atualização de status de um relato de infração aberto pelo participante indireto.

As opções de simulação para atualização de um relato de infração são:

1 - Cancelamento: Simula o cancelamento (cancel), feito pelo outro participante, sobre um relato de infração aberto por ele mesmo previamente.

2 - Fechamento: Simula o fechamento (close), feito pelo outro participante, sobre um relato de infração aberto pelo participante indireto.

### Request

ENDPOINT /mock/pix/infraction_report
MÉTODO PATCH

Request Body - Cancelamento

:::info IMPORTANTE
O Relato de infração identificado pela infraction_report_key ja deve ter sido previamente criado na simulação de recebimento de relato de infração.
:::

```json
{
  "infraction_report_status": "cancelled",
  "infraction_report_key": "28290ff2-2ba7-4e85-9a5e-862c92259b34"
}
```

Request Body - Fechamento

:::info IMPORTANTE
O Relato de infração identificado pela infraction_report_key ja deve ter sido previamente criado pelo participante indireto, e reconhecido na simulação de atualização de um relato de infração.
:::

```json
{
  "infraction_report_status": "closed",
  "infraction_report_key": "28290ff2-2ba7-4e85-9a5e-862c92259b34",
  "analysis_result": "agreed",
  "analysis_details": "Valor bloqueado. Para mais informações ligue para (99) 99999-9999."
}
```

### Objeto Request Body

| Campo                          | Tipo   | Descrição                                                            | Máx. Caract.                                                                        | Informações                      |
| ------------------------------ | ------ | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------- |
| **infraction_report_status\*** | string | Novo status do relato de infração. "cancelled", "closed"             | **[Enumeradores infraction_report_status](#enumeradores-infraction_report_status)** | ----                             |
| **infraction_report_key\***    | string | Chave única do relato de infração                                    | 36                                                                                  | ----                             |
| **analysis_result\***          | string | Resultado da análise do relato de infração. "agreed" ou "disagreed". | **[Enumeradores analysis_result](#enumeradores-analysis_result)**                   | Obrigatório para status "closed" |
| **analysis_details\***         | string | Detalhes da análise do relato de infração.                           | 2000                                                                                | Obrigatório para status "closed" |

### Enumeradores analysis_result

| Campo       | Tipo   | Descrição                                                                                                  | Caracteres |
| ----------- | ------ | ---------------------------------------------------------------------------------------------------------- | ---------- |
| `agreed`    | string | O Participante Indireto <strong>concorda</strong> com o Relato de Infração criado pelo outro Participante. | -          |
| `disagreed` | string | O Participante Indireto <strong>discorda</strong> com o Relato de Infração criado pelo outro Participante. | -          |

---

# Receber Relato de Infração

URL: /documentation/pix_indireto/relato_de_infracao/webhooks_relato_infracao

Visto que um outro Participante pode abrir um Relato de Infração, tendo como alvo o Participante Indireto, é necessário que a QI Tech notifique o Participante Indireto acerca do Relato aberto por outro Participante.

A QI Tech realizará o pooling periódico de novos relatos abertos aos Participantes Indiretos administrados, e notificará o correspondente via webhook , já com o status acknowledged.

:::danger IMPORTANTE
O Banco Central do Brasil define que, dentro de um período de 7 dias do recebimento do Relato de Infração pelo Participante Indireto, o Relato precisa ser fechado .

Caso haja atraso por parte do Participante Indireto, a QI Tech irá fechar o Relato de Infração, com o status de agreed, 6 dias corridos após o envio do webhook de recebimento da infração, a fim de que a instituição não seja penalizada pelo Banco Central do Brasil.
:::

O status do Relato de Infração sempre será de acknowledged , significando que a QI Tech recebeu o Relato e irá enviá-lo ao Participante Indireto.

:::info Informação

Tudo o descrito nesta seção de introdução também está, de forma detalhada como o Participante Indireto deve tratar via API, na seções relacionadas a Notificações de Infração.

:::

## Webhook recebimento de Relato de Infração
**Request Body**

```json
{
    "infraction_report_key":"d7820e2f-1c23-4610-83d6-d9aad1845075",
    "pix_transfer_key":"cdcf0d25-08a1-46e3-902a-6d7ca75e6c48",
    "end_to_end_id":"E99999010202406251332F8n7dMUwOLE",
    "infraction_report_status":"acknowledged",
    "infraction_report_situation":"scam",
    "infraction_report_type":"refund_request",
    "report_details":"usuario caiu em golpe…",
    "debited_participant":"99999011",
    "credited_participant":"99999010",
    "infraction_report_direction": "incoming",
    "created_at": "2023-03-03T12:04:06.179Z",
    "updated_at": "2023-03-03T12:04:06.179Z"
}
```

### Body Params

| Campo                           | Tipo   | Descrição                                                                                     | Caracteres                                                                                |
| ------------------------------- | ------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `infraction_report_key` *       | string | Identificador único do relato de infração.                                                    | 36                                                                                        |
| `pix_transfer_key` *            | string | Identificador único da transação PIX.                                                         | 36                                                                                        |
| `end_to_end_id` *               | string | Identificador único da transação PIX no BACEN.                                                | 36                                                                                        |
| `infraction_report_status` *    | enum   | Status .                                                                                      | **[Enumeradores infraction_report_status](#enumeradores-infraction_report_status)**       |
| `infraction_report_situation` * | enum   | Situação em que ocorreu a infração.                                                           | **[Enumeradores infraction_report_situation](#enumeradores-infraction_report_situation)** |
| `infraction_report_type` *      | enum   | Tipo de Relato de Infração.                                                                   | **[Enumeradores infraction_report_type](#enumeradores-infraction_report_type)**           |
| `infraction_report_details`     | string | Detalhes acerca do Relato de Infração criado.                                                 | \<\= 2000                                                                                 |
| `credited_participant` *        | string | ISPB do Participante Creditado.                                                               | 8                                                                                         |
| `debited_participant` *         | string | ISPB do Participante Debitado.                                                                | 8                                                                                         |
| `infraction_report_direction` * | enum   | Enumerador acerca se o relato foi aberto pelo Participante Indireto ou por outro Participante | **[Enumeradores infraction_report_direction](#enumeradores-infraction_report_direction)** |
| `created_at` *                  | string | Horário de criação do Relato de Infração                                                      | 24                                                                                        |
| `updated_at`                    | string | Horário de atualização do Relato de Infração                                                  | 24                                                                                        |

### Enumeradores infraction_report_status

| Campo          | Tipo   | Descrição                                                                     | Caracteres |
| -------------- | ------ | ----------------------------------------------------------------------------- | ---------- |
| `open`         | string | Relato de infração foi <strong>criado</strong> e está aberto no BACEN.        | -          |
| `acknowledged` | string | Relato de infração foi <strong>recebido</strong> pelo participante contestado | -          |
| `cancelled`    | string | Relato de infração está <strong>cancelado</strong> no BACEN                   | -          |
| `closed`       | string | Relato de infração está <strong>fechado</strong> no BACEN                     | -          |

### Enumeradores infraction_report_type

| Campo              | Tipo   | Descrição                                                             | Caracteres |
| ------------------ | ------ | --------------------------------------------------------------------- | ---------- |
| `refund_cancelled` | string | Relato de infração será gerado pelo motivo de uma devolução cancelada | 16         |
| `refund_request`   | string | Relato de infração será gerado a fim de se solicitar uma devolução    | 14         |

### Enumeradores infraction_report_situation

| Campo               | Tipo   | Descrição                                               | Caracteres |
| ------------------- | ------ | ------------------------------------------------------- | ---------- |
| `scam`              | string | Causa de golpe ou estelionato.                          | -          |
| `account_takeover`  | string | Causa de transação não autorizada pela conta de origem. | -          |
| `coercion`          | string | Causa de crime de coerção.                              | -          |
| `fraudulent_access` | string | Causa de acesso fraudulento à conta de origem.          | -          |
| `other`             | string | Quaisquer causas não aplicáveis às listadas acima.      | -          |

### Enumeradores infraction_report_direction
| Campo      | Tipo   | Descrição                                                     | Caracteres |
| ---------- | ------ | ------------------------------------------------------------- | ---------- |
| `incoming` | string | Relato de infração com participante indireto como alvo.       | -          |
| `outgoing` | string | Relato de infração com participante indireto como originador. | -          |

## Webhook recebimento de alteração de Relato de Infração
**Request Body**

```json
{
    "infraction_report_key":"d7820e2f-1c23-4610-83d6-d9aad1845075",
    "pix_transfer_key":"cdcf0d25-08a1-46e3-902a-6d7ca75e6c48",
    "end_to_end_id":"E99999010202406251332F8n7dMUwOLE",
    "infraction_report_status":"closed",
    "infraction_report_situation":"scam",
    "infraction_report_type":"refund_request",
    "report_details":"usuario caiu em golpe…",
    "debited_participant":"99999011",
    "credited_participant":"99999010",
    "analysis_result": "agreed",
    "analysis_details": "Valor bloqueado. Para mais informações ligue para (11) 98871-1385.",
    "infraction_report_direction": "outgoing",
    "created_at": "2023-03-03T12:04:06.179Z",
    "updated_at": "2023-03-03T12:04:06.179Z"
}
```

### Body Params

| Campo                           | Tipo   | Descrição                                                                                     | Caracteres                                                                                |
| ------------------------------- | ------ | --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `infraction_report_key` *       | string | Identificador único do relato de infração.                                                    | 36                                                                                        |
| `pix_transfer_key` *            | string | Identificador único da transação PIX.                                                         | 36                                                                                        |
| `end_to_end_id` *               | string | Identificador único da transação PIX no BACEN.                                                | 36                                                                                        |
| `infraction_report_status` *    | enum   | Status .                                                                                      | **[Enumeradores infraction_report_status](#enumeradores-infraction_report_status)**       |
| `infraction_report_situation` * | enum   | Situação em que ocorreu a infração.                                                           | **[Enumeradores infraction_report_situation](#enumeradores-infraction_report_situation)** |
| `infraction_report_type` *      | enum   | Tipo de Relato de Infração.                                                                   | **[Enumeradores infraction_report_type](#enumeradores-infraction_report_type)**           |
| `infraction_report_details`     | string | Detalhes acerca do Relato de Infração criado.                                                 | \<\= 2000                                                                                 |
| `credited_participant` *        | string | ISPB do Participante Creditado.                                                               | 8                                                                                         |
| `debited_participant` *         | string | ISPB do Participante Debitado.                                                                | 8                                                                                         |
| `analysis_result` *             | string | Resultado da análise.                                                                         | **[Enumeradores analysis_result](#enumeradores-analysis_result)**                         |
| `analysis_details` *            | string | Descrição acerca do resultado da análise.                                                     | 250                                                                                       |
| `infraction_report_direction` * | enum   | Enumerador acerca se o relato foi aberto pelo Participante Indireto ou por outro Participante | **[Enumeradores infraction_report_direction](#enumeradores-infraction_report_direction)** |
| `created_at` *                  | string | Horário de criação do Relato de Infração                                                      | 24                                                                                        |
| `updated_at`                    | string | Horário de atualização do Relato de Infração                                                  | 24                                                                                        |

### Enumeradores analysis_result

| Campo       | Tipo   | Descrição                                                                                                  | Caracteres |
| ----------- | ------ | ---------------------------------------------------------------------------------------------------------- | ---------- |
| `agreed`    | string | O Participante Indireto <strong>concorda</strong> com o Relato de Infração criado pelo outro Participante. | -          |
| `disagreed` | string | O Participante Indireto <strong>discorda</strong> com o Relato de Infração criado pelo outro Participante. | -          |

---

# Pix

URL: /documentation/pix_v2

## Realização de Transação Pix

### Request

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer
MÉTODO POST

### Path Params

| Campo         | Tipo   | Descrição                              | Caracteres |
|---------------|--------|----------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta. | 36         |

**Chave**

Request Body: Transferência por Chave Pix

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_type": "key",
  "target_pix_key": "target_pix_key@email.com",
  "transaction_amount": 500.65,
  "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
  "pix_message": "Ola Mundo"
}
```

### Body Params

| Campo                   | Tipo       | Descrição                                                                                                                                                                                                                                        | Caracteres |
|-------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `request_control_key` * | uuidv4     | Chave única de identificação da request utilizada pelo cliente no formato uuid v4.                                                                                                                                                               | 36         | 
| `pix_transfer_type` *   | enumerator | Tipo do pix a ser realizado. Para o caso de transferência por chave deve ser **key**.                                                                                                                                                            | "key"      |
| `target_pix_key` *      | string     | Chave pix da conta a ser enviada a transação.                                                                                                                                                                                                    | 100        |
| `transaction_amount` *  | number     | Valor da transferência.                                                                                                                                                                                                                          | 10         |
| `end_to_end_id` *       | string     | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na consulta de chave Pix. Só deve ser enviado se o `pix_transfer_type` for **key**, **static_qr_code** ou **dynamic_qr_code** | 32         |
| `pix_message`           | string     | Mensagem a ser enviada junto à transferência Pix.                                                                                                                                                                                                | 140        |

**Manual**
Request Body: Transferência Manual

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_type": "manual",
  "target_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "32402502000135",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502"
  },
  "transaction_amount": 500.65,
  "pix_message": "Ola Mundo"
}
```

### Body Params

| Campo                   | Tipo       | Descrição                                                                                         | Caracteres                                          |
|-------------------------|------------|---------------------------------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | uuidv4     | Chave única de identificação da request utilizada pelo cliente no formato uuid v4.                | 36                                                  | 
| `pix_transfer_type` *   | enumerator | Tipo de transferência Pix.                                                                        | **manual**                                          |
| `target_account` *      | Object     | Conta destino - Só deve ser enviada em transferências com `pix_transfer_type` do tipo **manual**. | **[Objeto target_account](#objeto-target_account)** | 10 |
| `transaction_amount` *  | number     | Valor da transferência.                                                                           | 10                                                  |
| `pix_message`           | string     | Mensagem a ser enviada junto à transferência Pix.                                                 | 140                                                 |

### Objeto target_account

| Campo                     | Tipo       | Descrição                                           | Caracteres                                              |
|---------------------------|------------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string     | Agência da conta.                                   | 6                                                       |
| `account_digit` *         | string     | Dígito da conta.                                    | 1                                                       |
| `account_number` *        | string     | Número da conta.                                    | 20                                                      |
| `owner_document_number` * | string     | CPF ou CNPJ (apenas números) do titular da conta.   | 14                                                      |
| `owner_name` *            | string     | Nome do titular da conta.                           | 150                                                     |
| `account_type`*           | enumerator | Tipo da conta.                                      | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string     | Base no CNPJ da instituição financeira (8 dígitos). | 8                                                       |

### Enumerador account_type

| Enumerador           | Descrição           |
|----------------------|---------------------|
| **checking_account** | Conta Corrente      |
| **salary_account**   | Conta Salário       |
| **saving_account**   | Conta Poupança      |
| **payment_account**  | Conta de Pagamentos |

**Qr Code**

Request Body: Transferência por Qr Code

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_type": "static_qr_code",
  "transaction_amount": 500.65,
  "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
  "receiver_conciliation_id": "REC00000000000000000000009459463343",
  "target_pix_key": "target_pix_key@email.com",
  "pix_message": "Ola Mundo"
}
```

### Body Params

| Campo                      | Tipo       | Descrição                                                                                                                                                                                                                                         | Caracteres                                |
|----------------------------|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------|
| `request_control_key` *    | uuidv4     | Chave única de identificação da request utilizada pelo cliente no formato uuid v4.                                                                                                                                                                | 36                                        | 
| `pix_transfer_type` *      | enumerator | Tipo de transferência Pix.                                                                                                                                                                                                                        | **static_qr_code** ou **dynamic_qr_code** |
| `target_pix_key` *         | string     | Chave pix da conta a ser enviada a transação.                                                                                                                                                                                                     | 100                                       |
| `receiver_conciliation_id` | string     | Identicação de conciliação do recebedor.                                                                                                                                                                                                          | 35                                        |
| `transaction_amount` *     | number     | Valor da transferência.                                                                                                                                                                                                                           | 10                                        |
| `end_to_end_id` *          | string     | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo). Esta chave é retornada na consulta de chave Pix. Só deve ser enviado se o `pix_transfer_type` for **key**, **static_qr_code** ou **static_qr_code**. | 32                                        |
| `pix_message`              | string     | Mensagem a ser enviada junto à transferência Pix.                                                                                                                                                                                                 | 140                                       |

:::info Aviso
O `end_to_end_id` é retornado ao [decodificar o QR Code Pix](/documentation/pix/decodificar_qr_code), utilizando a URI
do Pix Copia e Cola.
:::

:::danger Aviso
O `end_to_end_id` da consulta deve ter sido feito em nome da conta que solicitará a movimentação!
:::

:::danger Aviso
Um `end_to_end_id` só pode ser utilizado para uma única transferência, não importando, se a transferência tenha sido bem
sucedida ou não.
:::

### Response

STATUS 201

Response Body: Transferência Enviada

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "pix_transfer_status": "sent",
  "created_at": "2021-10-22T20:30:23.459Z"
}
```

STATUS 202

Response Body: Transferência Pendente

```json
{
  "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "pix_transfer_status": "pending",
  "created_at": "2021-10-22T20:30:23.459Z"
}
```

:::info Informação
Caso seja retornado **HTTP Status 202** com o campo `pix_transfer_status` com valor **pending**, a solicitação de Pix
não deve ser retentada.

Esta transferência será reprocessada. É necessário verificar o status da transferência por meio
da [Consulta de Transferência Pix](#consultar-transação-pix).
:::

STATUS 4xx

Response Body: Transferência Rejeitada

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {
    "pix_transfer_data": {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "pix_transfer_status": "rejected",
      "created_at": "2021-10-22T20:30:23.459Z"
    }
  }
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (ptbr)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Erro de Schema                                                                                                         |
| 406                      | PXT000103            | request_control_key must be a valid uuid v4 string | request_control_key was not accepted for not being a valid uuid v4 string                                               | request_control_key não foi aceito por não ser uma palavra uuid v4 válida                                              |
| 400                      | PXT000048            | Bad Request                                        | Emoji not allowed in pix message.                                                                                       | Emoji não é permitido na mensagem pix.                                                                                 |
| 400                      | PXT000104            | Invalid Transaction Amount                         | Transaction amount of \{transaction_amount\} is not valid. It must be a positive value with at maximum 2 decimal places | O valor de transação \{transaction_amount\} não é válido. Deve ser um valor positivo com no máximo duas casas decimais |
| 404                      | PXT000004            | Account not found                                  | Account not found for: \{account_datum\}                                                                                | Conta não encontrada para: \{account_datum\}                                                                           |
| 400                      | PXT000003            | Account is Closed                                  | Account \{account_key\} is closed.                                                                                      | Conta \{account_key\} está fechada.                                                                                    |
| 422                      | PXT000092            | Invalid Account Type                               | Pix is not yet implemented for non-checking or non-escrow account types                                                 | Transações Pix não estão implementadas para conta que não sejam escrow ou livres                                       |
| 403                      | PIT000001            | User is not allowed to do this transaction         |                                                                                                                         | Usuário não tem autorização para fazer essa transação                                                                  |
| 400                      | PXT000010            | Account is Blocked                                 | Account \{account_key\} is blocked.                                                                                     | Conta \{account_key\} está bloqueada.                                                                                  |
| 400                      | PXT000003            | Account is Closed                                  | Account \{account_key\} is closed.                                                                                      | Conta \{account_key\} está fechada.                                                                                    |
| 400                      | PIT000003            | Bad Request                                        | Insufficient account balance for transfer and fee amount.                                                               | Saldo de conta insuficiente para a transferência e a taxa.                                                             |
| 400                      | PXT000118            | Requester is not Pix Participant                   | The requester sent an alias key but is not a indirect pix participant                                                   | O requisitante enviou uma alias key no entanto não é um participante do pix indireto                                   |
| 404                      | PXT000120            | Alias sent not found                               | Alias key attached to this account not found                                                                            | Alias key vinculada à conta não encontrada                                                                             |
| 406                      | PXT000105            | Invalid end_to_end_id                              | The end_to_end_id sent \{end_to_end_id\} is not valid.                                                                  | O end_to_end_id enviado \{end_to_end_id\} não é válido.                                                                |
| 400                      | PXT000108            | Bad Request                                        | Billing account closed or blocked                                                                                       | Conta de cobrança encerrada ou bloqueada                                                                               |
| 400                      | PXT000079            | Bad Request                                        | Insufficient billing account balance for fee.                                                                           | Saldo de conta de cobrança insuficiente para a taxa.                                                                   |
| 400                      | PIT000004            | Bad Request                                        | Transaction amount is over limit.                                                                                       | O total da transferência é superior ao limite.                                                                         |
| 404                      | PIX000056            | Not Found                                          | Pix key inquiry not found                                                                                               | Consulta de chave pix não encontrada                                                                                   |
| 404                      | PXT000041            | Not Found                                          | Qr Code not found                                                                                                       | Qr Code não encontrado                                                                                                 |
| 400                      | PXT000053            | Bad Request                                        | QrCode already paid                                                                                                     | Qr Code já Pago                                                                                                        |
| 400                      | PXT000118            | Requester is not Pix Participant                   | The requester sent an alias key but is not a indirect pix participant                                                   | O requisitante enviou uma alias key no entanto não é um participante do pix indireto                                   |
| 404                      | PXT000120            | Alias sent not found                               | Alias key attached to this account not found                                                                            | Alias key vinculada à conta não encontrada                                                                             |
| 400                      | PXT000115            | Bad Request                                        | Insufficient account balance for transfer and fee amount.                                                               | Saldo de conta insuficiente para a transferência e a taxa                                                              |
| 400                      | PXT000128            | Bad Request                                        | Pix key \{pix_key\} sent does match inquiry pix key. Verify if end_to_end_id sent is correct                            | Chave Pix \{pix_key\} enviada não condiz com consulta. Verifique se end_to_end_id enviado está correto                 |
| 409                      | PXT000109            | Bad Request                                        | request_control_key \{request_control_key\} already in use                                                              | request_control_key \{request_control_key\} já utilizada                                                               |
| 400                      | PXT000061            | Bad Request                                        | End to end id invalid. A pix transfer with the end to end id \{end_to_end\} has already been registered!                | End to end id inválido. Uma transação pix com o identificador único \{end_to_end\} já foi registrada!                  |
| 400                      | PXT000129            | SPI Error message                                  | Message rejected by SPI-ICOM                                                                                            | Mensagem rejeitada pela SPI-ICOM                                                                                       |
| 408                      | PXT000130            | SPI Timeout Control                                | SPI Timeout Control                                                                                                     | Controle de timeout no SPI                                                                                             |
| 400                      | PXT000131            | Receiver Internal Error                            | Cancelled transaction due to receiver's internal error                                                                  | Transação interrompida devido a erro no PSP do Recebedor                                                               |
| 400                      | PXT000132            | Invalid Target Account Number                      | Target account number is invalid                                                                                        | Número da conta de destino é inexistente ou inválido                                                                   |
| 400                      | PXT000133            | Blocked Target Account                             | Target account is blocked.                                                                                              | A conta de destino encontra-se bloqueada.                                                                              |
| 400                      | PXT000134            | Closed Target Account                              | Target account is closed.                                                                                               | A conta de destino encontra-se encerrada.                                                                              |
| 400                      | PXT000135            | Unsupported Transaction                            | Unsupported transaction for given target account.                                                                       | A conta de destino não suporta este tipo de transação.                                                                 |
| 400                      | PXT000136            | Invalid Participant                                | SPI participant is not PSP settler agent of payer nor receiver.                                                         | Participante direto do SPI não é liquidante do PSP do Pagador / Recebedor.                                             |
| 400                      | PXT000137            | Zero Value Payment Order                           | Zero value payment order.                                                                                               | Ordem de pagamento com valor zero.                                                                                     |
| 400                      | PXT000138            | Insufficient Funds                                 | Insufficient funds in PI account from payer.                                                                            | Saldo insuficiente na conta PI do pagador.                                                                             |
| 400                      | PXT000139            | Return Value Too Great                             | Return value greater than corresponding payment order.                                                                  | Valor de devolução acima do valor de pagamento correspondente.                                                         |
| 400                      | PXT000140            | Invalid Transactions Number                        | Invalid transactions number.                                                                                            | Quantidade de transações inválida.                                                                                     |
| 400                      | PXT000141            | Unrelated Beneficiary Document Number              | Beneficiary document number is not that of target account owner.                                                        | CPF/CNPJ do usuário recebedor não é compatível com o titular da conta de destino.                                      |
| 400                      | PXT000142            | Invalid Beneficiary Document Number                | Invalid beneficiary document number                                                                                     | CPF/CNPJ da conta de destino está incorreto.                                                                           |
| 400                      | PXT000143            | Incorrect Message Element                          | Incorrect message element.                                                                                              | Elemento da mensagem incorreto.                                                                                        |
| 403                      | PXT000144            | Rejected Payment Order                             | Beneficiary's PSP has rejected payment order.                                                                           | Ordem de pagamento foi rejeitada pelo banco recebedor.                                                                 |
| 403                      | PXT000145            | Unauthorized Payer                                 | Signing participant is unauthorized to make a payment order for paying account.                                         | Participante que assinou a mensagem não é autorizado a realizar a operação na conta PI debitada.                       |
| 400                      | PXT000146            | Invalid Datetime                                   | Invalid datetime for message delivery.                                                                                  | Data e Hora do envio da mensagem inválida.                                                                             |
| 400                      | PXT000147            | Generic Error                                      | Error while processing payment (generic error).                                                                         | Erro no processamento do pagamento (erro genérico).                                                                    |
| 400                      | PXT000148            | Bad Format Operation Identifier                    | Badly formatted operation's identifier.                                                                                 | Identificador da operação mal formatado.                                                                               |
| 400                      | PXT000149            | Invalid Payer ISPB                                 | Invalid or non-existent payer's PSP ISPB number.                                                                        | Número ISPB do PSP do Pagador é inválido ou inexistente.                                                               |
| 400                      | PXT000150            | Invalid Beneficiary ISPB                           | Invalid or non-existent beneficiary's PSP ISPB number.                                                                  | Número ISPB do banco recebedor é inválido ou inexistente.                                                              |
| 400                      | PXT000151            | Incorrect Type                                     | Incorrect type for target account.                                                                                      | Tipo incorreto para a conta transacional especificada.                                                                 |
| 400                      | PXT000152            | Repeated End-to-End ID Error                       | The end_to_end_id was already used                                                                                      | O end_to_end_id já foi utilizado                                                                                       |
| 400                      | PXT000153            | Invalid Target Account Type                        | The target account type cannot receive PIX transactions                                                                 | O tipo de conta destino não pode receber transações PIX                                                                |
| 400                      | PXT000154            | Invalid ISPB                                       | Invalid or non-existent ISPB number.                                                                                    | Número ISPB é inválido ou inexistente.                                                                                 |
| 400                      | PXT000155            | Amount too Great                                   | Amount too great for credited account.                                                                                  | Valor de pagamento/devolução acima do permitido para a conta de destino creditada.                                     |
| 400                      | PXT000156            | QR Code Rejected                                   | QR Code rejected by beneficiary's PSP.                                                                                  | QR Code rejeitado pelo PSP do usuário recebedor.                                                                       |
| 503                      | PXT000157            | Bacen Service Unavailable Error                    | Could not send the message to ICOM after 3 retries                                                                      | Não pode enviar a mensagem para a ICOM depois de 3 tentativas                                                          |
| 400                      | PXT000158            | Invalid Amount                                     | Paid amount diverges from expected amount of \{expected_amount\}                                                        | O valor do pagamento diverge do valor esperado de \{expected_amount\}                                                  |
| 400                      | PXT000159            | QR code inactive                                   | QR code is not active at the time of payment                                                                            | QR code não está ativo no instante do pagamento                                                                        |

[//]: # (Break here for new page -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------)

## Consulta de Chave Pix no Banco Central

### Request

ENDPOINT /pix_key/ PIX_KEY ?account_key= ACCOUNT_KEY
MÉTODO GET

### Path Params

| Campo       | Tipo   | Descrição                      | Caracteres |
|-------------|--------|--------------------------------|------------|
| `pix_key` * | string | Chave Pix que será consultada. | 77         |

:::info Tipos de Chave Pix
A `pix_key` pode ser um CPF, CNPJ, E-mail, Celular ou uma Chave Aleatória (UUID), seguindo as seguintes formatações:

**CPF**: Número inteiro com 11 dígitos.

**CNPJ**: Número inteiro com 14 dígitos.

**E-mail**: Texto contendo ao menos um “@”.

**Celular**: Texto contendo os seguintes valores: “+55” + “DDD do celular“ + “Número Inteiro do Celular com no mínimo 8
e no máximo 9 dígitos”. Ex: “+5511987654321“.

**Chave Aleatória**: UUID4.
:::

### Query Params

| Campo           | Tipo   | Descrição                              | Caracteres |
|-----------------|--------|----------------------------------------|------------|
| `account_key` * | uuidv4 | Chave única de identificação da conta. | 36         |

:::info Utilização de tokens de consulta
Para que o token de consulta de chave pix seja cobrado da pessoa correta, é obrigatório que o `account_key` seja
enviado.
:::

### Response

STATUS 200

Response Body: Chave Ativa

```json
{
  "account_branch": "0001",
  "account_created_at": "2023-09-06T22:03:34.000Z",
  "account_digit": "8",
  "account_number": "2897775",
  "account_type": "checking",
  "bank_code": null,
  "end_to_end_id": "E73856642202309201429bZKfklNlbwu",
  "financial_institution": "BANCO INDIRETO PRUPRU",
  "ispb": "32402502",
  "owner_masked_document_number": "**.458.****/0001-**",
  "owner_name": "Empresa teste 01",
  "owner_person_type": "legal",
  "owner_trading_name": null,
  "pix_key": "0f723f66-b333-4187-be16-97fc37c86052"
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`      | Descrição (eng)<br/>`description`         | Descrição (ptbr)<br/>`translation`               |
|--------------------------|----------------------|-------------------------|-------------------------------------------|--------------------------------------------------|
| 404                      | PIX000017            | Pix Key is Unregistered | Pix key \{pix_key\} is not currently used | A chave pix \{pix_key\} não está sendo utilizada |
| 400                      | PIX000081            | Rate Limit Exceeded     | Rate Limit Exceeded                       | Limite de requisições excedido                   |

[//]: # (Break here for new page -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------)

## Efetuar devolução de um Pix

A devolução de um Pix pode ser efetuada em até 90 dias a partir de seu recebimento.

### Request

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer/ PIX_TRANSFER_KEY /reversal
MÉTODO POST

### Path Params

| Campo                | Tipo   | Descrição                                                        | Caracteres |
|----------------------|--------|------------------------------------------------------------------|------------|
| `account_key` *      | uuidv4 | Chave única de identificação da conta.                           | 36         |
| `pix_transfer_key` * | uuidv4 | Chave única de identificação da transferência Pix no sistema QI. | 36         |

Request Body

```json
{
  "request_control_key": "303393bf-8f2e-4ff0-b326-ee7ad612e8ca",
  "reversal_amount": 147,
  "reversal_reason": "client_request",
  "reversal_message": "Mensagem Pix da Devolução"
}
```

### Request Body

| Campo                   | Tipo   | Descrição                         | Caracteres                                                    |
|-------------------------|--------|-----------------------------------|---------------------------------------------------------------|
| `request_control_key` * | uuidv4 | Chave de unicidade da requisição. | 36                                                            |
| `reversal_amount` *     | number | Valor da devolução.               | 11                                                            |
| `reversal_reason` *     | string | Motivo da devolução.              | **[Enumerador reversal_reason](#enumerador-reversal_reason)** |
| `reversal_message`      | string | Mensagem da devolução.            | 140                                                           |

### Enumerador reversal_reason

| Enumerador         | Descrição                                     |
|--------------------|-----------------------------------------------|
| **client_request** | Caso tenha sido requerido pelo dono da conta. |
| **reconciliation** | Para reconciliação devido a erro operacional. |

### Response

STATUS 201

Response Body: Reversão Enviada

```json
{
  "reversal_status": "sent",
  "transfer_amount": 147,
  "pix_transfer_key": "cdcf0d25-08a1-46e3-902a-6d7ca75e6c48",
  "end_to_end_id": "E32402502202407112211Id9JbxoaiTf",
  "request_control_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
  "created_at": "2021-10-22T20:30:23.459Z"
}
```

STATUS 202

Response Body: Reversão Pendente

```json
{
  "reversal_status": "pending",
  "transfer_amount": 147,
  "pix_transfer_key": "cdcf0d25-08a1-46e3-902a-6d7ca75e6c48",
  "end_to_end_id": "E32402502202407112211Id9JbxoaiTf",
  "request_control_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
  "created_at": "2021-10-22T20:30:23.459Z"
}
```

:::info Informação
Caso seja retornado **HTTP Status 202** com o campo `pix_transfer_status` com valor **pending**, a solicitação de Pix
não deve ser retentada.

Esta transferência será reprocessada. É necessário verificar o status da transferência por meio
da [Consulta de Transferência Pix](#consultar-transação-pix).
:::

### Response Body

| Campo                 | Tipo       | Descrição                                                                                   | Caracteres                                                |
|-----------------------|------------|---------------------------------------------------------------------------------------------|-----------------------------------------------------------|
| `reversal_status`     | enumerator | Enumerador de status da transação de devolução.                                             | [Enumerador reversal_status](#enumerador-reversal_status) |
| `transfer_amount`     | number     | Valor da transferência de devolução.                                                        | 11                                                        |
| `pix_transfer_key`    | uuidv4     | Chave da transação pix executada na devolução.                                              | 36                                                        |
| `end_to_end_id`       | string     | Chave de idempotência de uma transação Pix dentro do SPI (Sistema de Pagamento Instantâneo) | 32                                                        |
| `request_control_key` | uuidv4     | Chave única de identificação da request utilizada pelo cliente.                             | 36                                                        |
| `created_at`          | string     | Data e hora da devolução.                                                                   | 10                                                        |

### Enumerador reversal_status

| Enumerador   | Descrição                                |
|--------------|------------------------------------------|
| **sent**     | Transferência Pix realizada com sucesso. |
| **pending**  | Transferência Pix pendente.              |
| **rejected** | Transferência Pix rejeitada.             |

STATUS 4xx

Response Body: Reversão Rejeitada

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {
    "pix_transfer_data": {
      "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
      "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "pix_transfer_status": "rejected",
      "created_at": "2021-10-22T20:30:23.459Z"
    }
  }
}
```

:::info Informação
Além dos erros anteriormente listados para transferências Pix, a devolução de um Pix também pode retornar os erros
listados abaixo.
:::

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                   | Descrição (eng)<br/>`description`                                      | Descrição (ptbr)<br/>`translation`                                                        |
|--------------------------|----------------------|--------------------------------------|------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                          | Schema Error                                                           | Erro de Schema                                                                            |
| 404                      | PXT000018            | Reversal Original Transfer not Found | Reversal original pix transfer not found.                              | Transferência original da devolução não foi encontrada.                                   |
| 400                      | PXT000017            | Reversal Too Great                   | Reversal transfers sum amount surpasses that of original pix transfer. | A soma das transferências de devolução ultrapassam o valor da transferência pix original. |
| 400                      | PXT000015            | Reversal date expired                | Reversal original transaction is older than 90 days                    | A data de criação da transação original é mais antiga que 90 dias                         |
| 400                      | PXT0000127           | Invalid Reversal Reason              | Reversal reason \{reversal_reason\} is not valid                       | Razão de reversão \{reversal_reason\} não é válida                                        |

[//]: # (Break here for new page -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------)

## Consultar Transação Pix por pix_transfer_key

### Request

ENDPOINT /account/ ACCOUNT_KEY /pix_transfer/ PIX_TRANSFER_KEY / PIX_TRANSFER_DIRECTION
MÉTODO GET

### Path Params

| Campo                      | Tipo       | Descrição                                             | Caracteres                                                                  |
|----------------------------|------------|-------------------------------------------------------|-----------------------------------------------------------------------------|
| `pix_transfer_direction` * | enumerator | Indicador do sentido da transação (entrada ou saída). | [Enumeradores pix_transfer_direction](#enumeradores-pix_transfer_direction) |
| `account_key` *            | uuidv4     | Chave única de identificação da conta QI.             | 36                                                                          |
| `pix_transfer_key` *       | uuidv4     | Chave única de identificação da transferência Pix.    | 36                                                                          |

### Enumeradores pix_transfer_direction

| Enumerador   | Descrição                                |
|--------------|------------------------------------------|
| **incoming** | Transferência Pix realizada com sucesso. |
| **outgoing** | Transferência Pix realizada com sucesso. |

### Response

STATUS 201

Response Body: Transferência Enviada (outgoing)

```json
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "pix_message": "Bom dia",
  "pix_transfer_type": "manual",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "updated_at": "2021-10-22T20:30:23.459Z",
  "created_at": "2021-10-22T20:30:23.459Z",
  "target_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "***02502000***",
    "owner_person_type": "legal",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502",
    "pix_key": null
  },
  "receiver_conciliation_id": null,
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "end_to_end_id": "E3240250220211022203051750897529",
  "pix_transfer_status": "sent",
  "transfer_amount": 126.97,
  "fee_amount": 0.0,
  "rejection_reason": null,
  "reversals": [
    {
      "end_to_end_id": "D35713491202309182058jlqdBkkHSWU",
      "transfer_amount": 0.01,
      "reversal_reason": "client_request",
      "pix_transfer_status": "received",
      "pix_transfer_key": "423866cd-0f3f-4cdd-904b-0d2e33273afd",
      "request_control_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0a",
      "created_at": "2021-10-23T20:30.459Z"
    }
  ]
}

```

Response Body: Transferência Rejeitada (outgoing)

```json
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "pix_message": "Bom dia",
  "pix_transfer_type": "manual",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "updated_at": "2021-10-22T20:30:23.459Z",
  "created_at": "2021-10-22T20:30:23.459Z",
  "target_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "***02502000***",
    "owner_person_type": "legal",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502",
    "pix_key": null
  },
  "receiver_conciliation_id": null,
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "end_to_end_id": "E3240250220211022203051750897529",
  "pix_transfer_status": "rejected",
  "transfer_amount": 126.97,
  "fee_amount": 0.0,
  "error_code": "PXT000132",
  "error_description": "Target account number is invalid.",
  "error_translation": "Número da conta de destino é inexistente ou inválido.",
  "reversals": []
}

```

Response Body: Devolução Enviada (outgoing)

```json
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "pix_message": "Bom dia",
  "pix_transfer_type": "reversal",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "updated_at": "2021-10-22T20:30:23.459Z",
  "created_at": "2021-10-22T20:30:23.459Z",
  "target_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "***02502000***",
    "owner_person_type": "legal",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502",
    "pix_key": null
  },
  "receiver_conciliation_id": null,
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "end_to_end_id": "E3240250220211022203051750897529",
  "pix_transfer_status": "sent",
  "transfer_amount": 126.97,
  "fee_amount": 0.0,
  "rejection_reason": null,
  "reversals": [],
  "original_incoming_pix_transfer": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3"
}

```

Response Body: Transferência Recebida (incoming)

```json
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "end_to_end_id": "E18236120202308111235s14fddf2801",
  "pix_transfer_status": "received",
  "receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
  "transfer_amount": 126.97,
  "fee_amount": 0.0,
  "source_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "***02502000***",
    "owner_person_type": "legal",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502"
  },
  "pix_transfer_type": "dynamic_qr_code",
  "reversals": []
}
```

Response Body: Devolução Recebida (incoming)

```json
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "end_to_end_id": "E18236120202308111235s14fddf2801",
  "pix_transfer_status": "received",
  "receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
  "transfer_amount": 126.97,
  "fee_amount": 0.0,
  "source_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "***02502000***",
    "owner_person_type": "legal",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502"
  },
  "pix_transfer_type": "reversal",
  "reversals": [],
  "original_outgoing_pix_transfer": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3"
}
```

Response Body: Transferência Rejeitada (incoming)

```json
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "end_to_end_id": "E18236120202308111235s14fddf2801",
  "pix_transfer_status": "rejected",
  "receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
  "transfer_amount": 126.97,
  "fee_amount": 0.0,
  "source_account": {
    "account_branch": "0001",
    "account_digit": "3",
    "account_number": "12345678",
    "owner_document_number": "***02502000***",
    "owner_person_type": "legal",
    "owner_name": "Qi Tech",
    "account_type": "checking_account",
    "ispb": "32402502"
  },
  "pix_transfer_type": "dynamic_qr_code",
  "reversals": []
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                          | Descrição (eng)<br/>`Description`                   | Descrição (ptbr)<br/>`translation`                                            |
|-------------|----------------------|---------------------------------------------|-----------------------------------------------------|-------------------------------------------------------------------------------|
| 400         | PXT000075            | Pix Transfer Key or End To End Not Provided | No pix transfer key or end to end id provided.      | Não foram fornecidos uma pix transfer key ou end to end id.                   |
| 404         | PXT000023            | Outgoing PIX Transfer Not Found             | Pix transfer key \{pix_transfer_key\} was not found | Transferência PIX de saída com chave \{pix_transfer_key\} não foi encontrada. |
| 403         | PIT000001            | User is not allowed to do this transaction  | User is not allowed to do this transaction          | Usuário não tem autorização para fazer essa transação                         |

[//]: # (Break here for new page -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------)

## Consultar Transações Pix

### Request

ENDPOINT /account/ ACCOUNT_KEY /pix_transfers
MÉTODO GET

### Path Params

| Campo           | Tipo   | Descrição                                | Caracteres |
|-----------------|--------|------------------------------------------|------------|
| `account_key` * | uuidv4 | Chave única de identificação da conta QI | 36         |

### Query Params

| Campo                    | Tipo       | Descrição                                                                                                  | Caracteres                                                                  |
|--------------------------|------------|------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| `pix_transfer_direction` | enumerator | Indicador do sentido da transação (entrada ou saída). Caso não seja enviado, **outgoing** será considerado | [Enumeradores pix_transfer_direction](#enumeradores-pix_transfer_direction) |
| `request_control_key`    | uuidv4     | Chave única de identificação da request utilizada pelo cliente.                                            | 36                                                                          |
| `end_to_end_id`          | string     | Chave de idempotência de uma transação Pix                                                                 | 32                                                                          |
| `transaction_key`        | uuidv4     | Chave de identificação da movimentação na conta                                                            | 36                                                                          |
| `date_from`              | string     | Data inicial. Formato "YYYY-MM-DD"                                                                         |                                                                             |
| `date_to`                | string     | Data final. Formato "YYYY-MM-DD"                                                                           |                                                                             |
| `page`                   | integer    | Número da página requisitada. 1 por padrão                                                                 |                                                                             |
| `page_size`              | integer    | Tamanho da página requisitada na consulta. 30 por padrão e valor máximo                                    | Valor máximo de 30                                                          |

### Enumeradores pix_transfer_direction

| Enumerador   | Descrição                    |
|--------------|------------------------------|
| **incoming** | Transferência Pix de entrada |
| **outgoing** | Transferência Pix de saída   |

### Response

STATUS 201

Response Body

```json
{
  "data": [
    {
      "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
      "pix_message": "Bom dia",
      "pix_transfer_type": "manual",
      "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
      "updated_at": "2021-10-22T20:30:23.459Z",
      "created_at": "2021-10-22T20:30:23.459Z",
      "target_account": {
        "account_branch": "0001",
        "account_digit": "3",
        "account_number": "12345678",
        "owner_document_number": "***02502000***",
        "owner_person_type": "legal",
        "owner_name": "Qi Tech",
        "account_type": "checking_account",
        "ispb": "32402502",
        "pix_key": null
      },
      "receiver_conciliation_id": null,
      "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "end_to_end_id": "E3240250220211022203051750897529",
      "pix_transfer_status": "sent",
      "transfer_amount": 126.97,
      "fee_amount": 0.0,
      "rejection_reason": null,
      "reversals": [
        {
          "end_to_end_id": "D35713491202309182058jlqdBkkHSWU",
          "transfer_amount": 0.01,
          "reversal_reason": "client_request",
          "pix_transfer_status": "received",
          "pix_transfer_key": "423866cd-0f3f-4cdd-904b-0d2e33273afd",
          "request_control_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0a",
          "created_at": "2021-10-23T20:30.459Z"
        }
      ]
    }
  ],
  "pagination": {
    "current_page": 1,
    "rows_per_page": 30
  }
}

```

[//]: # (Break here for new page -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------)

## Webhook para Transações Pendentes

Webhook que servirá para avisar sobre conclusão de transações que foram originalmente respondidas como pendentes (
retornaram com http status 202).

### Webhook Request Body

Request Body: Transação Enviada

```json
{
  "webhook_type": "baas.pix_transfer.outgoing_pix",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "pix_transfer_status": "sent",
    "created_at": "2021-10-22T20:30:23.459Z"
  }
}
```

Request Body: Transação Rejeitada

```json
{
  "webhook_type": "baas.pix_transfer.outgoing_pix",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "request_control_key": "b6804f32-101e-4702-8fbc-c2dbc4c2caec",
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "pix_transfer_status": "rejected",
    "created_at": "2021-10-22T20:30:23.459Z",
    "error_code": "PXT000132",
    "error_description": "Target account number is invalid.",
    "error_translation": "Número da conta de destino é inexistente ou inválido.",
    "error_short_description": null
  }
}
```

### Webhook Body Param

| Campo                 | Tipo   | Descrição                                                 | Max. Caracteres |
|-----------------------|--------|-----------------------------------------------------------|-----------------|
| `webhook_type`        | string | Um enumerador que define o tipo de evento sendo reportado | 23              |
| `webhook_datetime`    | string | Data e hora do envio do webhook                           | 20              |
| `request_control_key` | string | UUID4 para fins de consulta sobre a requisição feita.     | 36              |
| `pix_transfer_key`    | string | Chave de identificação da transferência Pix no sistema QI | 36              |
| `pix_transfer_status` | string | Status da transação.                                      | 200             |
| `created_at`          | string | Data e hora de criação da transação.                      | 20              |

[//]: # (Break here for new page -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------)

## Webhook para Pix de Entrada

Webhook que servirá para avisar sobre transações Pix que chegaram para uma conta.

### Webhook Request Body

Request Body: Pix Recebido

```json
{
  "webhook_type": "baas.pix_transfer.incoming_pix",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "end_to_end_id": "E18236120202308111235s14fddf2801",
    "pix_transfer_status": "received",
    "account_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
    "receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
    "transfer_amount": 126.97,
    "fee_amount": 0.0,
    "source_account": {
      "account_branch": "0001",
      "account_digit": "3",
      "account_number": "12345678",
      "owner_document_number": "***02502000***",
      "owner_person_type": "legal",
      "owner_name": "Qi Tech",
      "account_type": "checking_account",
      "ispb": "32402502"
    },
    "pix_transfer_type": "dynamic_qr_code",
    "pix_message": "pix message received",
    "created_at": "2021-10-22T20:30:23.459Z",
    "reversals": []
  }
}
```

### Webhook Body Param

| Campo                      | Tipo       | Descrição                                                                                             | Max. Caracteres                                                   |
|----------------------------|------------|-------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `webhook_type`             | string     | Um enumerador que define o tipo de evento sendo reportado                                             | 23                                                                |
| `webhook_datetime`         | string     | Data e hora do envio do webhook                                                                       | 20                                                                |
| `pix_transfer_type`        | enumerator | Tipo do pix realizado                                                                                 | **[Enumerador pix_transfer_type](#enumerador-pix_transfer_type)** |
| `target_pix_key`           | string     | Chave pix da conta a ser enviada a transação                                                          | 100                                                               |
| `source_account`           | Object     | Conta destino - Só deve ser enviada em transações do tipo "manual"                                    | **[Objeto source_account](#objeto-source_account)**               |
| `transfer_amount`          | number     | Valor da transferencia                                                                                | 10                                                                |
| `receiver_conciliation_id` | string     | Identicação de conciliação do recebedor                                                               | 35                                                                |
| `end_to_end_id`            | string     | Chave de idempotência de uma transação Pix - só deve ser enviado se o tipo de transferência for "key" | 32                                                                |
| `pix_message`              | string     | Mensagem a ser enviada junto à transferência Pix                                                      | 140                                                               |
| `fee_amount`               | number     | Valor da transferencia                                                                                | 10                                                                |
| `pix_transfer_status`      | string     | Status da transação pix                                                                               | 10                                                                |
| `account_key`              | string     | Chave única de identificação da conta QI                                                              | 36                                                                |
| `pix_transfer_key`         | string     | Chave única de identificação da transferência Pix                                                     | 36                                                                |

### Enumerador pix_transfer_type

| Enumerador          | Descrição                                |
|---------------------|------------------------------------------|
| **manual**          | Pix utilizando os dados da conta destino |
| **key**             | Pix utilizando uma chave pix             |
| **static_qr_code**  | Pix utilizando um QR code estático       |
| **dynamic_qr_code** | Pix utilizando um QR code dinâmico       |
| **reversal**        | Devolução Pix                            |

### Objeto source_account

| Campo                     | Tipo       | Descrição                                                                                               | Caracteres                                              |
|---------------------------|------------|---------------------------------------------------------------------------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string     | Agência da conta                                                                                        | 6                                                       |
| `account_digit` *         | string     | Dígito da conta                                                                                         | 1                                                       |
| `account_number` *        | string     | Número da conta                                                                                         | 20                                                      |
| `owner_document_number` * | string     | CPF ou CNPJ (apenas números) do titular da conta                                                        | 14                                                      |
| `owner_name`              | string     | Nome do titular da conta                                                                                | 150                                                     |
| `account_type`*           | enumerator | Tipo da conta                                                                                           | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string     | Código de oito dígitos que identifica os bancos no sistema de transferência de reserva do Banco Central | 8                                                       |

### Enumerador account_type

| Enumerador           | Descrição           |
|----------------------|---------------------|
| **checking_account** | Conta Corrente      |
| **salary_account**   | Conta Salário       |
| **saving_account**   | Conta Poupança      |
| **payment_account**  | Conta de Pagamentos |

[//]: # (Break here for new page -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------)

## Webhook para Devoluções de Pix

Webhook que servirá para avisar sobre devoluções Pix que chegaram para uma conta.

### Webhook Request Body

Request Body: Pix Recebido

```json
{
  "webhook_type": "baas.pix_transfer.incoming_pix",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "end_to_end_id": "E18236120202308111235s14fddf2801",
    "pix_transfer_status": "received",
    "account_key": "7c5a1425-73eb-420e-b4fb-0ce3386c7d0c",
    "receiver_conciliation_id": "745c28c780bc4822bbade86dd875d10b",
    "transfer_amount": 126.97,
    "fee_amount": 0.0,
    "source_account": {
      "account_branch": "0001",
      "account_digit": "3",
      "account_number": "12345678",
      "owner_document_number": "***02502000***",
      "owner_person_type": "legal",
      "owner_name": "Qi Tech",
      "account_type": "checking_account",
      "ispb": "32402502"
    },
    "pix_transfer_type": "reversal",
    "pix_message": "pix message received",
    "created_at": "2021-10-22T20:30:23.459Z",
    "reversals": [],
    "original_outgoing_pix_transfer": "b56862c4-2b20-4057-8063-b8809866e494"
  }
}
```

### Webhook Body Param

| Campo                            | Tipo       | Descrição                                                                                             | Max. Caracteres                                                   |
|----------------------------------|------------|-------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `webhook_type`                   | string     | Um enumerador que define o tipo de evento sendo reportado                                             | 23                                                                |
| `webhook_datetime`               | string     | Data e hora do envio do webhook                                                                       | 20                                                                |
| `pix_transfer_type`              | enumerator | Tipo do pix realizado                                                                                 | **[Enumerador pix_transfer_type](#enumerador-pix_transfer_type)** |
| `target_pix_key`                 | string     | Chave pix da conta a ser enviada a transação                                                          | 100                                                               |
| `source_account`                 | Object     | Conta destino - Só deve ser enviada em transações do tipo "manual"                                    | **[Objeto source_account](#objeto-source_account)**               |
| `transfer_amount`                | number     | Valor da transferencia                                                                                | 10                                                                |
| `receiver_conciliation_id`       | string     | Identicação de conciliação do recebedor                                                               | 35                                                                |
| `end_to_end_id`                  | string     | Chave de idempotência de uma transação Pix - só deve ser enviado se o tipo de transferência for "key" | 32                                                                |
| `pix_message`                    | string     | Mensagem a ser enviada junto à transferência Pix                                                      | 140                                                               |
| `fee_amount`                     | number     | Valor da transferencia                                                                                | 10                                                                |
| `pix_transfer_status`            | string     | Status da transação pix                                                                               | 10                                                                |
| `account_key`                    | string     | Chave única de identificação da conta QI                                                              | 36                                                                |
| `pix_transfer_key`               | string     | Chave única de identificação da transferência Pix                                                     | 36                                                                |
| `original_outgoing_pix_transfer` | string     | Chave única de identificação da transferência Pix de saída Original                                   | 36                                                                |

### Enumerador pix_transfer_type

| Enumerador          | Descrição                                |
|---------------------|------------------------------------------|
| **manual**          | Pix utilizando os dados da conta destino |
| **key**             | Pix utilizando uma chave pix             |
| **static_qr_code**  | Pix utilizando um QR code estático       |
| **dynamic_qr_code** | Pix utilizando um QR code dinâmico       |
| **reversal**        | Devolução Pix                            |

### Objeto source_account

| Campo                   | Tipo       | Descrição                                                                                               | Caracteres                                              |
|-------------------------|------------|---------------------------------------------------------------------------------------------------------|---------------------------------------------------------|
| `account_branch`        | string     | Agência da conta                                                                                        | 6                                                       |
| `account_digit`         | string     | Dígito da conta                                                                                         | 1                                                       |
| `account_number`        | string     | Número da conta                                                                                         | 20                                                      |
| `owner_document_number` | string     | CPF ou CNPJ (apenas números) do titular da conta                                                        | 14                                                      |
| `owner_name`            | string     | Nome do titular da conta                                                                                | 150                                                     |
| `account_type`          | enumerator | Tipo da conta                                                                                           | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb`                  | string     | Código de oito dígitos que identifica os bancos no sistema de transferência de reserva do Banco Central | 8                                                       |

### Enumerador account_type

| Enumerador           | Descrição           |
|----------------------|---------------------|
| **checking_account** | Conta Corrente      |
| **salary_account**   | Conta Salário       |
| **saving_account**   | Conta Poupança      |
| **payment_account**  | Conta de Pagamentos |

---

# Aprovar transferência

URL: /documentation/pix/2fa/aprovar_solicitacao_de_transferencia

## Request

ENDPOINT /baas/token_request
MÉTODO POST

Request Body

```json
{
    "token": "329329",
    "agent_document_number": "97564480000",
    "movement_payload": {
        "pix_transfer_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
        "approver_document_number": "97564480000"
    }
}

```

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `contact_type` * | string | Forma de envio do token de autenticação,  podendo ser via E-mail (“email”) ou SMS (“sms”)| 10 |
| `agent_document_number` * | Object | CPF do usuário que irá receber o token. | 11 | 
| `receiver_conciliation_id` | string | Identicação de conciliação do recebedor - Obrigatório para pagamento de QrCode . | 32 |
| `end_to_end_id` *| string | Chave de idempotência de uma transação Pix - | 32 |
| `movement_payload` *| Object | Payload contendo as informações da transferência | **[Objeto movement_payload](#objeto-movement_payload)** | - |

### Objeto movement_payload

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `pix_transfer_key` * | string | Chave única da transferência pix, retonada no endpoint de solicitação de transferência | 10 |
| `approver_document_number` * | Object | CPF do usuário que irá receber o token. | 11 | 

## Response

STATUS 201

Response Body
```json
{
    "pix_transaction": {
        "fee_amount": 0.0,
        "pix_message": null,
        "pix_transfer_type": "key",
        "end_to_end_id": "E32402502202404041622XydHD7dzD0s",
        "pix_transfer_key": "c7ad1951-96f7-4cd7-b15d-038512b26f4f",
        "transfer_amount": 45,
        "target_account": {
            "document_number": "***.698.79*-**",
            "financial_institution": "CAIXA ECONOMICA FEDERAL"
        },
        "source_account": {
            "account_digit": "0",
            "account_branch": "0001",
            "account_number": "9223675"
        },
        "pix_transfer_status": "sent",
        "transaction_key": "67d54c48-39a1-4c65-843c-ba9d876c3cff"
    },
    "operation_key": "08b9cc1a-3e24-4604-a080-e41ff782f19d",
    "transaction_key": "8ea90347-330d-4b3a-8ebb-2ac217ad6eb3",
    "status": "sent",
    "event_datetime": "2024-04-04 13:25:24",
    "authentication_code": "5dab74e796133f4039e437fb58b4a29b"
} 
```

---

# Solicitar devolução de um Pix

URL: /documentation/pix/2fa/solicitar_chargeback_pix

A devolução de um Pix pode ser solicitada em até 90 dias a partir de seu recebimento.

## Request

ENDPOINT /baas/pix_transfer
MÉTODO POST

:::info Informação
Após a solicitação da devolução é necessário realizar a [ solicitação do token de transferência Pix](../pix/2fa/aprovar_solicitacao_de_transferencia) 
:::

Request Body

```json
{
    "is_chargeback": true,
    "pix_transfer_key": "b91da9c7-72de-46dc-bb36-4b1407d1eb91",
    "chargeback_amount": 147,
    "chargeback_message": "Mensagem Pix da devolução"
}
```

## Response

STATUS 200

Response Body

```json
{
	"data": {
		"pix_transfer_key": "b3015cb5-862d-48aa-946d-c14afc8cdebb",
		"pix_transfer_status": "pending_approval",
		"pix_transfer_type": "chargeback",
		"target_account": {
			"document_number": "***02502000***",
			"financial_institution": "QI SOCIEDADE DE CRÉDITO DIRETO S.A."
		},
		"transfer_amount": 35
	},
	"event_datetime": "2023-03-21 11:52:11",
	"operation_key": "ec9b4741-7c7e-4429-9b10-3fc05045ebea",
	"status": "pending_approval"
}
```

STATUS 4xx

Response Body: Reversão Rejeitada

```json
{
    "title": "titulo",
    "description": "description in English",
    "translation": "descrição em portugues",
    "code": "codigo"
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                  | Descrição (eng)<br/>`description`                                      | Descrição (ptbr)<br/>`translation`                                                        |
|--------------------------|----------------------|-------------------------------------|------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                         | Schema Error                                                           | Erro de Schema                                                                            |
| 404                      | PXT000084            | Original Pix Transfer Was Not Found | Original Pix Transfer Was Not Found.                                   | A transação PIX original não foi encontrada.                                              |
| 400                      | PXT000017            | Reversal Too Great                  | Reversal transfers sum amount surpasses that of original pix transfer. | A soma das transferências de devolução ultrapassam o valor da transferência pix original. |
| 400                      | PXT000015            | Reversal date expired               | Reversal original transaction is older than 90 days                    | A data de criação da transação original é mais antiga que 90 dias                         |

---

# Solicitar Token de Aprovação da Transferência

URL: /documentation/pix/2fa/solicitar_token_de_aprovacao

## Request

ENDPOINT /baas/token_request
MÉTODO POST

Request Body

```json
{
    "contact_type": "sms",
    "agent_document_number": "97564480000",
    "movement_payload": {
        "pix_transfer_key": "cea836b5-b02e-4f94-b1e2-4d575671c33d",
        "approver_document_number": "97564480000"
    }
}

```

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `contact_type` * | string | Forma de envio do token de autenticação,  podendo ser via E-mail (“email”) ou SMS (“sms”)| 10 |
| `agent_document_number` * | string | CPF do usuário que irá receber o token. | 11 | 
| `movement_payload` | Object | Payload contendo as informações da transferência | **[Objeto movement_payload](#objeto-movement_payload)** | 

### Objeto movement_payload

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `pix_transfer_key` * | string | Chave única da transferência pix, retonada no endpoint de solicitação de transferência | 10 |
| `approver_document_number` * | string | CPF do usuário que irá receber o token. | 11 | 

### Response

STATUS 201

Response Body
```json
{} 
```

---

# Solicitar Transferência Pix

URL: /documentation/pix/2fa/solicitar_transferencia

## Request

ENDPOINT /baas/pix_transfer
MÉTODO POST

## Pix Manual - Transferência utilizando dados bancários

Request Body

```json

{
    "pix_transfer_type": "manual",
    "source_account": {
        "account_branch": "0001",
        "account_digit": "2",
        "account_number": "2359934",
        "owner_document_number": "09080702000105"
    },
    "target_account": {
          "account_branch": "0001",
          "account_digit": "3",
          "account_number": "12345678",
          "owner_document_number": "32402502000135",
          "owner_name": "Qi Tech",
          "account_type": "checking_account",
          "ispb": "32402502"
     },
    "transaction_amount": 45,
    "message": "Mensagem pix"
}

```

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `pix_transfer_type` * | string | O Pix possui diferentes tipos de iniciação, o "manual" onde o usuário deve enviar os campos da conta de destino e conta de origem e o "key" onde o usuário deve enviar os campos da chave Pix do recebedor (conta de destino) e os dados da conta de origem. | 10 |
| `source_account` * | Object | Conta de origem. | **[Objeto source_account](#objeto-source_account)** | 
| `target_account` | Object | Conta destino - Só deve ser enviada em transações do tipo "manual". | **[Objeto target_account](#objeto-target_account)** | 10 |
| `transaction_amount` * | string | Valor da transferencia. | 10 |

### Objeto source_account

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `account_branch` * | string | Número Agência. | 0 |
| `branch_digit` |string | Dígito da Agência.| 0 |
| `account_digit` * | string | Dígito da conta.| 0 |
| `account_number` * | string | Número da conta.| 0 | 
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta.| 0 |

### Objeto target_account

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `account_branch` * | string | Agência. | 10 |
| `account_digit` * | string | Dígito da conta | 10 |
| `account_number` * | string | Número da conta. | 10 |
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta. | 10 |
| `owner_name` * | string | Nome do titular da conta. | 10 |
| `account_type` * |string |  CPF ou CNPJ (apenas números) do titular da conta.| 10 |
| `ispb` | string |  Código de oito dígitos que identifica os bancos no sistema de transferência de reserva do Banco Central.| 10 |

### Response

STATUS 200

Response Body: Transferência manual

```json
{
    "data": {
        "fee_amount": 5.0,
        "pix_message": "",
        "pix_transfer_key": "fde0f4b4-8a8a-4ae2-a179-2398f434881a",
        "transfer_purpose": "transfer",
        "transaction_amount": 15.0,
        "end_to_end_id": "E324025022024040400378WsKzFgIuUg",
        "target_account": {
            "document_number": "***.698.79*-**",
            "financial_institution": "CAIXA ECONOMICA FEDERAL"
        },
        "source_account": {
            "account_number": "1314358",
            "account_digit": "0",
            "account_brach": "0001",
            "account_type": "checking",
            "owner_name": "Bem demais",
            "owner_document_number": "90477655000148"
        }
    },
    "operation_key": "06426df6-fe8e-4fe0-84b7-75d7199c3a34",
    "status": "pending_approval",
    "event_datetime": "2024-04-03 21:37:06"
}

``` 

## Transferência Pix utilizando Chave Pix

Request Body

```json

{
    "pix_transfer_type": "key",
    "source_account": {
        "account_branch": "0001",
        "account_digit": "2",
        "account_number": "2359934",
        "owner_document_number": "09080702000105"
    },
    "pix_key": "teste@pix.com",
    "transaction_amount": 45,
    "end_to_end_id": "E32402502202404040038Cs4oXRAOe98",
    "message": "olá, mundo!"
}

```

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `pix_transfer_type` * | string | Tipo de transferência Pix (key) | - |
| `source_account` * | Object | Conta de origem. | **[Objeto source_account](#objeto-source_account)** | 
| `pix_key` | Object | Chave pix | - |
| `transaction_amount` * | string | Valor da transferencia. | 10 |
| `end_to_end_id` | string | Chave de idempotência de uma transação Pix - é retornada na consulta de chave pix. | 32 |

 
### Objeto source_account

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `account_branch` * | string | Número Agência. | 0 |
| `branch_digit` |string | Dígito da Agência.| 0 |
| `account_digit` * | string | Dígito da conta.| 0 |
| `account_number` * | string | Número da conta.| 0 | 
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta.| 0 |

### Response

STATUS 200

Response Body: Transferência por chave Pix

```json
{
  "operation_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "status": "pending",
  "event_datetime": "2021-08-04 20:05:54",
  "pix_transaction": {
    "pix_message": "",
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "transaction_amount": 1891268.97,
    "source_account": {
      "account_branch": "0001",
      "account_digit": "3",
      "account_number": "24339",
      "owner_document_number": "32402502000135",
      "owner_name": "Qi Tech",
      "account_type": "checking"
    },
    "target_account": {
      "target_account": "78340-6",
      "financial_institution_code": "329",
      "owner_document_number": "32402502000135",
      "owner_name": "QI Tech",
      "target_account_type": "checking_account",
      "owner_person_type": "legal",
      "trading_name": "QITech"
    },
    "fee_amount": 0
  }
}

``` 

## Transferência Pix QRCode

Os dados utilizados para realizção de uma transação de pagamento de um QR Code Pix devem ser obtidos através da [decodificação do QR Code Pix](/documentation/pix/decodificar_qr_code), utilizando a URI do Pix Copia e Cola.
I - O campo “end_to_end_id” deve ser o mesmo valor retornado da decodificação do QR Code Dinâmico.
II - Informar no campo “transaction_amount“ o mesmo valor retornado no campo “qr_code_data.amount” da decodificação do QR Code Dinâmico;
III - Alterar o campo “pix_transfer_type” para o enumerador correspondente (**static_qr_code** ou **dynamic_qr_code** ), para solicitação do pagamento.
  IV - O campo “receiver_conciliation_id” deve ser o mesmo valor retornado da decodificação do QR Code Dinâmico.

Request Body

```json
{
    "pix_transfer_type": "dynamic_term",
    "source_account": {
        "account_branch": "0001",
        "account_digit": "2",
        "account_number": "2359934",
        "owner_document_number": "09080702000105"
    },
    "pix_key": "chave_pix_retornada",
    "receiver_conciliation_id": "27f6e293-7794-40a7-84e8-c5bf97ece57a",
    "end_to_end_id": "E32402502202304031417pknxDsRrUqM",
    "transaction_amount": 45
}

```

### Body Params

| Campo | Tipo | Descrição                                                                                              | Caracteres |
|---|---|--------------------------------------------------------------------------------------------------------| ---|
| `pix_transfer_type` * | string | Indicador do tipo de transferência (qrcode)                                                            | 10 |
| `source_account` * | Object | Conta de origem.                                                                                       | **[Objeto source_account](#objeto-source_account)** | 
| `pix_key` | Object | Chave pix                                                                                              | - |
| `transaction_amount` * | string | Valor da transferencia.                                                                                | 10 |
| `receiver_conciliation_id` | string | Identicação de conciliação do recebedor - Obtido através do decode do QrCode .                         | 32 |
| `end_to_end_id` | string | Chave de idempotência de uma transação Pix - é retornada na decodificação do QrCode.                   | 32 |
|`pix_transfer_key` | string | Chave de idempotência de uma transação Pix - só deve ser enviado se o tipo de transferência for "key". | 10 |

 
### Objeto source_account

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `account_branch` * | string | Número Agência. | 0 |
| `branch_digit` |string | Dígito da Agência.| 0 |
| `account_digit` * | string | Dígito da conta.| 0 |
| `account_number` * | string | Número da conta.| 0 | 
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta.| 0 |

### Response

STATUS 200

Response Body: Transferência por QrCode

```json
{
  "operation_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "status": "pending",
  "event_datetime": "2021-08-04 20:05:54",
  "pix_transaction": {
    "pix_message": "",
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "transaction_amount": 1891268.97,
    "source_account": {
      "account_branch": "0001",
      "account_digit": "3",
      "account_number": "24339",
      "owner_document_number": "32402502000135",
      "owner_name": "Qi Tech",
      "account_type": "checking"
    },
    "target_account": {
      "target_account": "78340-6",
      "financial_institution_code": "329",
      "owner_document_number": "32402502000135",
      "owner_name": "QI Tech",
      "target_account_type": "checking_account",
      "owner_person_type": "legal",
      "trading_name": "QITech"
    },
    "fee_amount": 0
  }
}

```

---

# Aprovar solicitação de transferência

URL: /documentation/pix/aprovar_solicitacao_de_transferencia

## Request

ENDPOINT /baas/pix_transfer_approval
MÉTODO POST

Request Body

```json
{
    "pix_transfer_key": "0e241203-8c6b-4e0a-ac42-e0d2a2fc2d37",
    "approver_document_number": "11111111111"
}

```

### Body params

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `pix_transfer_type` * | string | chave de identificação da transação, recebida no momento da solicitação de transferência. | chave uuid |
| `approver_document_number` * | string | CPF do usuário quem está autorizando a transferência. | string |

## Response

STATUS 200

Response Body: Aprovação de uma transferência manual

```json
{
  "operation_key": "ea2fc82c-ad32-4c08-a341-527b09883da3",
  "status": "pending",
  "event_datetime": "2021-08-04 20:05:54",
  "pix_transaction": {
    "pix_message": "",
    "pix_transfer_type": "manual",
    "created_at": "2021-10-22T20:30:50",
    "sent_at": "2021-10-22T20:30:53",
    "source_account_key": "a1d2dea5-fa90-4676-a125-da355fdc3ed0",
    "update_at": "2021-10-22T20:30:53",
    "fee_amount": 0,
    "receiver_conciliation_id": null,
    "transaction_key": "2e9f50cf-da59-4418-96a6-e7073a06f660",
    "target_account": {
      "target_account": "78340-6",
      "financial_institution_code": "329",
      "owner_document_number": "32402502000135",
      "owner_name": "QI Tech",
      "target_account_type": "checking_account",
      "owner_person_type": "legal",
      "trading_name": "QITech"
    },
    "source_account": {
      "account_branch": "0001",
      "account_digit": "9",
      "account_number": "09661"
    },
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "end_to_end_id": "E3240250220211022203051750897529",
    "pix_transfer_status": "sent",
    "transfer_amount": 1891268.97
  }
}

```

STATUS 200

Response Body: Aprovação de uma transferência por chave

```json
{
  "event_datetime": "2021-10-28 15:06:04",
  "operation_key": "ea2fc82c-ad32-4c08-a341-527b09883da3",
  "pix_transaction": {
    "end_to_end_id": "E3210272497339911957760452404275",
    "fee_amount": 0,
    "pix_message": null,
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "pix_transfer_status": "scheduled",
    "pix_transfer_type": "key",
    "schedule_date": "2021-10-28",
    "schedule_key": "9dee3e8f-2765-4b7a-8bb6-22557b0a4204",
    "source_account": {
      "account_branch": "0001",
      "account_digit": "9",
      "account_number": "09661"
    },
    "target_account": {
      "document_number": "***.221.81*-**",
      "financial_institution": "BANCO BRADESCO S.A.",
      "target_account": "1925255-8"
    },
    "transfer_amount": 1891268.97
  },
  "status": "sent"
}

```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

STATUS 422

Response Body

```json
{
  "data": "{\"title\": \"Pending Transfer\", \"description\": \"The transaction (<END TO END ID DO PIX>) could not be completed and is pending confirmation.\", \"translation\": \"Não foi possível concluir a transação (<END TO END ID DO PIX>) e ela está pendente de confirmação\", \"code\": \"PXT000072\"}"
}

```

:::danger HTTP Error 422
Caso seja retornado **http error 422**, a solicitação de Pix **não deve ser retentada**. É preciso checar o status da solicitação de transferência Pix através de um GET na rota [/baas/pix/pix_transfer](/documentation/pix/pesquisar_por_transferencia_pix_de_saida).
:::

---

# Consulta de Dados de Chave Pix no Banco Central

URL: /documentation/pix/baas_v2/consultar_chave_pix

## Request

ENDPOINT /pix_key/ PIX_KEY
MÉTODO GET

### Request Path Params

| Campo               | Tipo   | Descrição                      | Caracteres |
|---------------------|--------|--------------------------------|------------|
| `pix_key` * | string | Chave PIX que será consultada. | 77 |

:::info Tipos de Chave Pix
A “pix_key” pode ser um CPF, CNPJ, E-mail, Celular ou uma Chave Aleatória (UUID), seguindo as seguintes formatações:

**CPF**: Número inteiro com 11 dígitos.

**CNPJ**: Número inteiro com 14 dígitos.

**E-mail**: Texto contendo ao menos um “@”.

**Celular**: Texto contendo os seguintes valores: “+55” + “DDD do celular“ + “Número Inteiro do Celular com no mínimo 8 e no máximo 9 dígitos”. Ex: “+5511987654321“.

**Chave Aleatória**: UUID4.
:::

### Request Query Params

| Campo              | Tipo   | Descrição                                                                                                                                                                                            | Caracteres |
|--------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `account_key` *    | uuidv4 | Chave única do alias.                                                                                                                                                                                | 36         |
| `document_number`  | int    | CPF/CNPJ do titular da Chave Pix. Ao passar este parâmetro o campo `is_pix_key_owner` será retornado com um valor booleano identificando se o CPF/CNPJ informado é igual ao do titular da Chave Pix. | 14         |

:::info Utilização de tokens de consulta
Para que o token de consulta de chave pix seja cobrado da pessoa titular da conta, é obrigatório que o `account_key` seja enviado.
Caso não seja enviado o account_key, o token será cobrado do número de documento do parceiro. 
:::

## Response

STATUS 200

Response Body: Chave Ativa

```json
{
    "account_branch": "452",
    "account_created_at": "2021-10-22T20:30.459Z",
    "account_digit": "1",
    "account_number": "370158",
    "account_type": "checking_account",
    "bank_code": "237",
    "end_to_end_id": "E3240250220230404185631R0kjZnC6G",
    "financial_institution": "BCO BRADESCO S.A.",
    "is_pix_key_owner": false,
    "ispb": "60746948",
    "owner_masked_document_number": "***.141.857-**",
    "owner_name": "Teste teste",
    "owner_person_type": "legal",
    "owner_trading_name": "Teste LTDA.",
    "pix_key": "teste@gmail.com"
}
```

| Campo                          | Tipo    | Descrição                                                                                                                                                                                                                                                                                     | Max. Caracteres                                                   |
|--------------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------|
| `account_branch`               | string  | Agência da conta vinculada a Chave Pix, sem o dígito verificador.                                                                                                                                                                                                                             | 4                                                                 |
| `account_created_at`           | string  | Data de abertura da conta vinculada a Chave Pix, informada pela instituição custodiante da conta.                                                                                                                                                                                             | 21                                                                |
| `account_digit`                | string  | Dígito verificador da conta vinculada a Chave Pix.                                                                                                                                                                                                                                            | 1                                                                 |
| `account_number`               | string  | Número de conta vinculada a Chave Pix sem o dígito verificador.                                                                                                                                                                                                                               | 20                                                                |
| `account_type`                 | enum    | Definição do tipo de conta da Chave Pix.                                                                                                                                                                                                                                                      | [Enumeradores Account Type](#enumeradores-account_type)           |
| `bank_code`                    | string  | Código do banco registrador da Chave Pix. Pode ser retornado como nulo, para instituições que não possuem código de banco                                                                                                                                                                     | 3                                                                 |
| `end_to_end_id`                | string  | Indentificador único da consulta da chave Pix no Bacen. Deve ser enviado na transferência Pix para que o token consumido na consulta seja recuperado.                                                                                                                                         | 32                                                                |
| `financial_institution`        | string  | Nome da instituição financeira registradora da Chave Pix.                                                                                                                                                                                                                                     | 200                                                               |
| `is_pix_key_owner`             | boolean | Será retornado um valor boleano, caso o parâmetro `document_number` seja passado na request. Este campo informa se o CPF/CNPJ informado no parâmetro `document_number` é o mesmo do titular da Chave Pix. Será retornado um valor nulo caso o parâmetro `document_number` não seja informado. | -                                                                 |
| `ispb`                         | string  | ISPB do Participate detentor da Chave Pix.                                                                                                                                                                                                                                                    | 8                                                                 |
| `owner_masked_document_number` | string  | Número de CPF ou CNPJ do titular da Chave Pix.                                                                                                                                                                                                                                                | 14                                                                |
| `owner_name`                   | string  | Nome do titular da Chave Pix.                                                                                                                                                                                                                                                                 | 120                                                               |
| `owner_person_type`            | enum    | Natureza jurídica do titular da Chave Pix.                                                                                                                                                                                                                                                    | [Enumeradores Owner Person Type](#enumeradores-owner_person_type) |
| `owner_trading_name`           | string  | Nome fantasia do titular da Chave Pix (somente para `owner_person_type=legal`).                                                                                                                                                                                                               | 100                                                               |
| `pix_key`                      | string  | Chave Pix.                                                                                                                                                                                                                                                                                    | -                                                                 |

### Enumeradores account_type
| Enumerador       | Descrição          |
|------------------|--------------------|
| `payment` | Conta de pagamento |
| `checking` | Conta de corrente  |
| `savings` | Conta poupança     |
| `saving` | Conta poupança     |
| `salary` | Conta salário      |
| `saving_account` | Conta poupança     |
| `payment_account` | Conta de pagamento |
| `checking_account` | Conta de corrente  |
| `salary_account` | Conta salário      |
| `escrow` | Conta Vinculada    |

:::info
Diferentes enumeradores podem significar o mesmo tipo de conta devido a informação retornada por diferentes instituições.
:::

### Enumeradroes owner_person_type
| Enumerador | Descrição |
|------------|-----------|
| `natural`  | string    |
| `legal`    | string    |

STATUS 4XX

Response Body

```json
{
    "title": "titulo",
    "description": "description in English",
    "translation": "descrição em portugues",
    "code": "codigo"
}
```

|Código HTTP | Código QI<br/>`code` | Título<br/>`title` | Descrição (eng)<br/>`Description` | Descrição (ptbr)<br/>`translation` |
|------------|-------------------|----------------|------------------------------|-----------------------------|
| 404        | PIX000017         | Pix Key Not Found | Pix key \{pix_key\} not found. | A chave pix \{pix_key\} não foi encontrada. |
| 403        | PIX000080         | Not enough permission | The selected agent doesn't have permission to access this resource. | O agente selecionado não tem permissão para acessar este recurso. |
| 429        | PIX000081         | Rate Limit Exceeded | Rate Limit Exceeded | Limite de requisições excedido |
| 404        | PIX000082         | Alias not found | Alias \{alias_key\} not found | Alias \{alias_key\} não encontrado |
| 404        | PIX000083         | Pix Key not found | Pix Key \{pix_key\} not found for Alias \{alias_key\} | Chave Pix \{pix_key\} não encontrada para o Alias \{alias_key\} |
| 400        | PIX000084         | Only one query param allowed | Only one query param allowed | Somente um parâmetro de consulta é permitido |

---

# Baixar QR Code Pix dinâmico

URL: /documentation/pix/baixar_qr_code_dinamico

## Request

ENDPOINT /baas/qrcode/dynamic
MÉTODO POST

Request Body

```json
{
  "occurrence_type": "write_off",
  "qr_code_key": "461d29e6-d2ed-48f7-bc7b-c3143a1e43d2",
  "qr_code_type": "dynamic_term"
}

```

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `occurrence_type` * |  string |Tipo de ocorrencia. payment: Ocorrência do tipo pagamento, registration: Ocorrência do tipo registro, write_off: Ocorrência do tipo cancelamento pelo gerador, bank_written_off: Ocorrência do tipo cancelamento pelo banco. | - |
| `qr_code_type` * | string | Tipo do QR Code dinâmico | - |
| `qr_code_key` * | string | Chave do QR Code devolvida no momento da geração. | uuid |

## Response

STATUS 200

Response Body

```json
{
  "qr_code_type": "dynamic_instant",
  "amount": null,
  "expiration_seconds": null,
  "max_payment_days": 180,
  "receiver_conciliation_id": "461d29e6d2ed48f7bc7bc3143a1e43d2",
  "payer_name": null,
  "payer_document_number": null,
  "payer_person_type": "natural",
  "payer_request": null,
  "pix_message": null,
  "modality_alteration": false,
  "expiration_date": null,
  "rebate_amount": null,
  "interest_amount": null,
  "fine_amount": null,
  "paid_amount": null,
  "discounts": [],
  "additional_data": [],
  "origin": "system",
  "origin_key": null,
  "pix_key": "9de04466-0b02-4263-9c28-9cdc0fb638bb",
  "qr_code_key": "461d29e6-d2ed-48f7-bc7b-c3143a1e43d2",
  "occurrence_type": "write_off",
  "end_to_end_id": null,
  "source_account_branch": null,
  "source_account_financial_institution": null,
  "source_account_ispb": null,
  "source_account_number": null,
  "source_account_digit": null,
  "disable": null,
  "qr_code_occurrence_key": "32ec9e60-b630-45fa-a0c7-653fbb30a32a",
  "base_64": null,
  "image": null
}

```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

---

# Busca por solicitação de limite Pix

URL: /documentation/pix/busca_por_solicitacao_de_limite_pix

## Request

ENDPOINT /baas/pix/limits_request
MÉTODO GET

### Query String

| Campo       | Tipo   | Descrição                      |Caracteres|
|-------------|--------|--------------------------------|---------|
| `account_key` | string | chave de identificação da QIConta | 36
| `request_status` | string | status da solicitação de limite. Status válidos: **"pending_approval"**, **"approved"**, **"rejected"**, **"executed"**. Pode ser enviado em forma de lista, por exemplo: **"pending_approval,approved"**|
| `page`                     | integer | Número da página pesquisada                       | -          |
| `page_size`                | integer | Quantidade de itens por página                  | -          |

## Response

STATUS 200

Response Body

```json
{
   "pagination": {
      "current_page": 0,
      "next_page": 1,
      "rows_per_page": 15,
      "total_pages": 1,
      "total_rows": 4
   },
   "data": [
      {
         "account_key": "dc94d45c-11a1-46f1-b19a-a1af9884a3c5",
         "amount_limit": 2000,
         "created_at": "2023-05-29T11:50:03",
         "limit_type": "daily",
         "request_key": "155afa76-4e80-4a11-917a-34d48e39325c",
         "request_status": "pending_approval",
         "routine_key": null
      },
      {
         "account_key": "dc94d45c-11a1-46f1-b19a-a1af9884a3c5",
         "amount_limit": 1000,
         "created_at": "2023-05-29T11:50:03",
         "limit_type": "nightly",
         "request_key": "805a457d-307d-46c5-8dce-e98e309a3380",
         "request_status": "pending_approval",
         "routine_key": null
      },
      {
         "account_key": "dc94d45c-11a1-46f1-b19a-a1af9884a3c5",
         "amount_limit": 1500,
         "created_at": "2023-05-29T11:50:03",
         "limit_type": "self_daily",
         "request_key": "7cd413ab-fc78-41e6-ab27-206f69e2e294",
         "request_status": "pending_approval",
         "routine_key": null
      },
      {
         "account_key": "dc94d45c-11a1-46f1-b19a-a1af9884a3c5",
         "amount_limit": 500,
         "created_at": "2023-05-29T11:50:03",
         "limit_type": "self_nightly",
         "request_key": "febe9087-1eba-4169-a63e-29e546aaf874",
         "request_status": "pending_approval",
         "routine_key": null
      }
   ]
}
```

STATUS 403

Response Body: Usuário não possui credenciais

```json
{
    "title": "Unauthorized",
    "description": "User is not allowed to do this transaction",
    "translation": "Usuário não tem autorização para fazer essa transação",
    "code": "PIT000001"
}
```

---

# Busca por uso de limite Pix

URL: /documentation/pix/busca_por_uso_de_limite_pix

## Request

ENDPOINT /baas/pix/limits/ ACCOUNT_KEY /usage
MÉTODO GET

### Path Params

| Campo       | Tipo   | Descrição                      |Caracteres|
|-------------|--------|--------------------------------|---------|
| `account_key` | string | chave de identificação da QIConta | 36 |

## Response

STATUS 200

Response Body

```json
{
	"daily_amount_limit": "800012.67",
	"daily_amount_percentage": null,
	"daily_amount_used": "0",
	"nightly_amount_limit": "100000.00",
	"nightly_amount_percentage": null,
	"nightly_amount_used": "0",
	"self_daily_amount_limit": "500.03",
	"self_daily_amount_percentage": null,
	"self_daily_amount_used": "0",
	"self_nightly_amount_limit": "100000.00",
	"self_nightly_amount_percentage": null,
	"self_nightly_amount_used": "0"
}
```

STATUS 403

Response Body: Usuário não possui credenciais

```json
{
    "title": "Unauthorized",
    "description": "User is not allowed to do this transaction",
    "translation": "Usuário não tem autorização para fazer essa transação",
    "code": "PIT000001"
}
```

---

# Chaves PIX mockadas em ambiente de sandbox

URL: /documentation/pix/chaves_pix_mockadas

## 104 - CAIXA ECONOMICA FEDERAL

| Chave Pix                            | Tipo         | Nome do titular  | Documento do titular | Número da conta | Agencia da conta | ISPB   |
|--------------------------------------|--------------|------------------|----------------------|-----------------|------------------|--------|
| +5568970000000                       | phone_number | Mock Person Name | 65322181032          | 21837-5         | 4458             | 360305 | 
| d6e2d611-6c68-4f84-9be5-962ad2f2bcb6 | random_key   | Mock Person Name | 61295118092          | 100091086-1     | 465              | 360305 | 
| 61295118092                          | cpf          | Mock Person Name | 61295118092          | 1300005670-8    | 4289             | 360305 | 
| pix03@pix03.com                      | email        | Mock Person Name | 96969879003          | 363214578-8     | 8615             | 360305 | 
| +5568911106520                       | phone_number | Mock Person Name | 66702118805          | 100071086-1     | 465              | 360305 | 
| 5e6ce02a-e0da-4d56-73b8-84f118b4f371 | random_key   | Mock Person Name | 52720072800          | 100061086-1     | 465              | 360305 | 
| 52720072800                          | cpf          | Mock Person Name | 52720072800          | 100071076-1     | 465              | 360305 | 
| pix10@pix10.com                      | email        | Mock Person Name | 24182533410          | 100071066-1     | 465              | 360305 | 
| pix33@pix33.com                      | email        | Mock Person Name | 56151446887          | 96764-6         | 919              | 360305 | 
| 88253032978                          | cpf          | Mock Person Name | 88253032978          | 96764-6         | 919              | 360305 | 

## 341 - ITAÚ UNIBANCO S.A.

| Chave Pix                            | Tipo       | Nome do titular  | Documento do titular | Número da conta | Agencia da conta | ISPB     |
|--------------------------------------|------------|------------------|----------------------|-----------------|------------------|----------|
| 22156083070                          | cpf        | Mock Person Name | 22156083070          | 19413-2         | 8534             | 60701190 | 
| 96969879003                          | cpf        | Mock Person Name | 96969879003          | 22110-1         | 8615             | 60701190 | 
| 5e6ce06a-e0da-4d56-93b8-84f118b4f371 | random_key | Mock Person Name | 43135154025          | 57980-4         | 5067             | 60701190 | 
| pix11@pix11.com                      | email      | Mock Person Name | 66702118805          | 86091-8         | 3101             | 60701190 | 
| 24182533410                          | cpf        | Mock Person Name | 24182533410          | 20467-1         | 5807             | 60701190 | 
| pix07@pix07.com                      | email      | Mock Person Name | 11646288874          | 33087-6         | 8872             | 60701190 | 

## 237 - BCO BRADESCO S.A.

| Chave Pix                            | Tipo         | Nome do titular  | Documento do titular | Número da conta       | Agencia da conta | ISPB     |
|--------------------------------------|--------------|------------------|----------------------|-----------------------|------------------|----------|
| 65322181032                          | cpf          | Mock Person Name | 65322181032          | 1017372-2             | 1                | 60746948 | 
| b9380607-dac6-4e17-8ca7-eb761e3aa1dd | random_key   | José Alves       | 24080025327          | 0001000000000022279-9 | 1                | 08744817 | 
| b9380607-dac6-4e17-8ca7-eb761e3aa1dd | random_key   | José Alves       | 24080025327          | 0003000000000000288-9 | 1                | 08744817 | 
| b9380607-dac6-4e17-8ca7-eb761e3aa1dd | random_key   | José Alves       | 24080025327          | 0013000000000013609-9 | 1                | 08744817 | 
| b9380607-dac6-4e17-8ca7-eb761e3aa1dd | random_key   | José Alves       | 24080025327          | 1288000000884535174-9 | 1                | 08744817 | 
| b9380607-dac6-4e17-8ca7-eb761e3aa1dd | random_key   | José Alves       | 24080025327          | 3701000000593070593-9 | 1                | 08744817 | 
| pix01@pix01.com                      | email        | Mock Person Name | 65322181032          | 1017372-2             | 1                | 60746948 | 
| pix01@pix01.com                      | email        | Mock Person Name | 65322181032          | 1925255-8             | 3952             | 60746948 | 
| pix12@pix12.com                      | email        | Mock Person Name | 11085087824          | 1071659-4             | 427              | 60746948 | 
| 5e6ce08a-e0da-4d56-93b8-84f118b4f371 | random_key   | Mock Person Name | 66702118805          | 1751795-3             | 6162             | 60746948 | 
| +5568911137576                       | phone_number | Mock Person Name | 82104056080          | 1587784-7             | 1340             | 60746948 | 

## 33 - BCO SANTANDER (BRASIL) S.A.

| Chave Pix                            | Tipo       | Nome do titular  | Documento do titular | Número da conta | Agencia da conta | ISPB     |
|--------------------------------------|------------|------------------|----------------------|-----------------|------------------|----------|
| 5e6ce05a-e0da-4d56-93b8-84f118b4f371 | random_key | Mock Person Name | 42759960030          | 9206744-2       | 4187             | 90400888 | 
| 34175131205                          | cpf        | Mock Person Name | 34175131205          | 9206744-2       | 4187             | 90400888 | 
| 5e6ce05a-e0da-4d56-53b8-74f118b4f371 | random_key | Mock Person Name | 11646288874          | 9206744-2       | 4187             | 90400888 | 
| 82104056080                          | cpf        | Mock Person Name | 82104056080          | 2850903-2       | 214              | 90400888 | 

## 77 - BANCO INTER

ISPB: 416968

| Chave Pix                            | Tipo         | Nome do titular       | Documento do titular | Número da conta | Agencia da conta | ISPB   |
|--------------------------------------|--------------|-----------------------|----------------------|-----------------|------------------|--------|
| 22156083070                          | cpf          | Mock Person Name      | 22156083070          | 4810813-8       | 1                | 416968 | 
| pix13@pix13.com                      | email        | Mock Person Name      | 43135154025          | 4830813-8       | 1                | 416968 | 
| 66702118805                          | cpf          | Mock Person Name      | 66702118805          | 4820813-8       | 1                | 416968 | 
| 5e6ce05a-e0da-4d56-93b7-84f118b4f371 | random_key   | Mock Person Name      | 24182533410          | 4850813-8       | 1                | 416968 | 
| +5568911168384                       | phone_number | Mock Person Name      | 17413005255          | 4850813-8       | 1                | 416968 | 
| pix06@pix06.com                      | email        | Mock Person Name      | 81035632691          | 4750813-8       | 1                | 416968 | 
| pix31@pix31.com                      | email        | Mock Person Name      | 55125236780          | 1768538-4       | 2960             | 416968 |
| 8501216b-d676-4927-be65-060d3d4394fb | random_key   | Mocked Enterprise S.A | 40008675000100       | 1049122-2       | 1                | 416968 |
| pix_key@mockenterprise.com.br        | email        | Mocked Enterprise S.A | 40008675000100       | 1049122-2       | 1                | 416968 |
| 40008675000100                       | cnpj         | Mocked Enterprise S.A | 40008675000100       | 1049122-2       | 1                | 416968 |
| +5568956720123                       | phone_number | Mocked Enterprise S.A | 40008675000100       | 1049122-2       | 1                | 416968 |

## 260 - NU PAGAMENTOS - IP

| Chave Pix                            | Tipo         | Nome do titular  | Documento do titular | Número da conta | Agencia da conta | ISPB     |
|--------------------------------------|--------------|------------------|----------------------|-----------------|------------------|----------|
| pix04@pix04.com                      | email        | Mock Person Name | 69017362073          | 81648459-8      | 1                | 18236120 | 
| pix09@pix09.com                      | email        | Mock Person Name | 34175131205          | 81538459-8      | 1                | 18236120 | 
| 5e6ce01a-e0da-4d56-93b8-44f118b4f371 | random_key   | Mock Person Name | 17413005255          | 81548459-8      | 1                | 18236120 | 
| +5568911186420                       | phone_number | Mock Person Name | 81035632691          | 81538459-8      | 1                | 18236120 | 
| pix32@pix32.com                      | email        | Mock Person Name | 56151446887          | 293201-6        | 2811             | 18236120 | 

## 336 - BCO C6 S.A.

| Chave Pix                            | Tipo       | Nome do titular  | Documento do titular | Número da conta | Agencia da conta | ISPB     |
|--------------------------------------|------------|------------------|----------------------|-----------------|------------------|----------|
| dbbf965d-677c-49ff-b9da-5131da1505f3 | random_key | Mock Person Name | 65322181032          | 1019902-6       | 1                | 31872495 | 
| 5e6ce07a-e0da-4d56-93b8-84f118b4f371 | random_key | Mock Person Name | 11085087824          | 1018902-6       | 1                | 31872495 | 
| 11646288874                          | cpf        | Mock Person Name | 11646288874          | 1017902-6       | 1                | 31872495 | 

## 403 - CORA SCD S.A.

| Chave Pix      | Tipo | Nome do titular | Documento do titular | Número da conta | Agencia da conta | ISPB     |
|----------------|------|-----------------|----------------------|-----------------|------------------|----------|
| 39284100000000 | cnpj | Parcela Mais    | 39284100000000       | 1708315-8       | 1                | 37880206 | 

## 422 - BCO SAFRA S.A.

| Chave Pix       | Tipo         | Nome do titular  | Documento do titular | Número da conta | Agencia da conta | ISPB     |
|-----------------|--------------|------------------|----------------------|-----------------|------------------|----------|
| pix02@pix02.com | email        | Mock Person Name | 69017362073          | 364522-5        | 284              | 58160789 | 
| pix08@pix08.com | email        | Mock Person Name | 34175131205          | 264522-5        | 284              | 58160789 | 
| +5568911106070  | phone_number | Mock Person Name | 11646288874          | 354522-5        | 284              | 58160789 | 
| 53465252110     | cpf          | Mock Person Name | 53465252110          | 364422-5        | 284              | 58160789 | 
| +5568911122488  | phone_number | Mock Person Name | 10632271             | 1558321-5       | 907              | 58160789 | 

## 655 - BCO VOTORANTIM S.A.

| Chave Pix  | Tipo | Nome do titular  | Documento do titular | Número da conta | Agencia da conta | ISPB     |
|------------|------|------------------|----------------------|-----------------|------------------|----------|
| 5301321099 | cpf  | Mock Person Name | 5301321099           | 622660113-8     | 1111             | 59588111 | 

## DOCK SOLUCOES EM MEIOS DE PAGAMENTO S A

| Chave Pix                            | Tipo         | Nome do titular  | Documento do titular | Número da conta | Agencia da conta | ISPB    |
|--------------------------------------|--------------|------------------|----------------------|-----------------|------------------|---------|
| +5568911165580                       | phone_number | Mock Person Name | 53465252110          | 622470112-8     | 1111             | 8744817 | 
| 17413005255                          | cpf          | Mock Person Name | 17413005255          | 622450112-8     | 1111             | 8744817 | 
| 81035632691                          | cpf          | Mock Person Name | 81035632691          | 622450113-8     | 1111             | 8744817 | 
| 5e6ce05a-e0da-4d56-93b8-64f118b4f371 | random_key   | Mock Person Name | 81035632691          | 622650113-8     | 1111             | 8744817 | 

## COMPANHIA GLOBAL DE SOLUCOES E SERVICOS DE PAGAMENTOS S.A.

| Chave Pix   | Tipo | Nome do titular | Documento do titular | Número da conta | Agencia da conta | ISPB     |
|-------------|------|-----------------|----------------------|-----------------|------------------|----------|
| 96755229091 | cpf  | Teste sem Compe | 96755229091          | 1444301-8       | 1                | 32024691 | 

## Empresas com CNPJ Alfanumérico

| Chave Pix      | Tipo | Nome do titular     | Documento do titular | Número da conta | Agencia da conta | ISPB     | Participante         |
|----------------|------|---------------------|----------------------|-----------------|------------------|----------|----------------------|
| HSRMASY3000160 | cnpj | Empresa Alfa Mock 1 | HSRMASY3000160       | 1050001-2       | 1                | 416968   | BANCO INTER          |
| 0ZSD0MBG000135 | cnpj | Empresa Alfa Mock 2 | 0ZSD0MBG000135       | 81550001-2      | 1                | 18236120 | NU PAGAMENTOS - IP   |
| DDA9RHST000100 | cnpj | Empresa Alfa Mock 3 | DDA9RHST000100       | 1750001-9       | 1                | 37880206 | CORA SCD S.A.        |

---

# Comprovante de transação

URL: /documentation/pix/comprovante_de_transferencia

## Request

ENDPOINT /transaction_receipt/TRANSACTION_KEY
MÉTODO GET

:::info

A resposta desta requisição irá trazer os dados referentes á aquela transação consultada e caso o parâmetro PDF seja verdadeiro o campo "pdf_encoded_string" estará disponível com a string do PDF encodada em base-64.

:::

### Path params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `TRANSACTION_KEY` * | string |  Chave da transação consultada. | chave uuid |

### Query params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `pdf` | boolean | Booleano que define se a resposta deverá gerar um PDF ou não. | true/false |

STATUS 200

Response Body: Recibo de transação com chave

```json
{
  "is_schedule": true,
  "origin_key": "f7507645-534c-4790-a19c-b89763d42fe5",
  "schedule_date": "2021-11-06",
  "scheduled_for_br_formatted": "Agendado Para 06/11/2021",
  "source_account": {
    "account_branch": "0001",
    "account_digit": "9",
    "account_number": "09661",
    "financial_institution_compe_number": 329,
    "financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
    "owner_document_number": "45783565660"
  },
  "source_subtype": "pix_withdrawal",
  "source_subtype_translation_ptbr": "Transferência de PIX",
  "target_account": {
    "account_branch": "3952",
    "account_digit": "8",
    "account_number": "1925255",
    "account_type": "checking_account",
    "account_type_str": "Conta Corrente",
    "financial_institution_compe_number": 237,
    "financial_institution_name": "BANCO BRADESCO S.A.",
    "owner_document_number": "***.221.81*-**",
    "owner_name": "Vivo Test",
    "pix_key": "pix01@pix01.com",
    "pix_transfer_type": "key"
  },
  "transaction_amount": 12.2,
  "transaction_key": "53301505-342a-4bf4-b7de-845e5c79ed02"
}
```

## Response

STATUS 200

Response Body: Recibo de transação manual

```json
{
  "chargeback_returned_amount": null,
  "end_to_end_id": "E3210272497339911957760452404275",
  "is_chargeback": false,
  "pix_message": null,
  "pix_transfer_key": "2c4d15c4-2a03-4979-813e-0ead374686d8",
  "source_account_key": "e10a6f94-facc-4392-9eba-d0d0b278bc5d",
  "receiver_conciliation_id": "REC00000000000000000000009459463343",
  "pix_transfer_type": "transfer",
  "target_account": {
    "account_branch": "3952",
    "account_digit": "8",
    "account_number": "1925255",
    "financial_institution_compe_number": 237,
    "financial_institution_name": "BANCO BRADESCO S.A.",
    "is_internal": false,
    "ispb_number": "60746948",
    "owner_document_number": "***22181***",
    "owner_name": "Vivo Test",
    "target_pix_key": "pix01@pix01.com"
  },
  "transfer_amount": 1891268.97
}
```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

---

# Comprovante de transferência agendada

URL: /documentation/pix/comprovante_de_transferencia_agendada

## Request

ENDPOINT /schedule_receipt/SCHEDULE_KEY
MÉTODO GET

### Path params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `SCHEDULE_KEY` * | string | Chave da transação agendada. | chave uuid |

STATUS 200

Response Body: Recibo de transação com chave

```json
{
  "is_schedule": true,
  "origin_key": "f7507645-534c-4790-a19c-b89763d42fe5",
  "schedule_date": "2021-11-06",
  "scheduled_for_br_formatted": "Agendado Para 06/11/2021",
  "source_account": {
    "account_branch": "0001",
    "account_digit": "9",
    "account_number": "09661",
    "financial_institution_compe_number": 329,
    "financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
    "owner_document_number": "45783565660"
  },
  "source_subtype": "pix_withdrawal",
  "source_subtype_translation_ptbr": "Transferência de PIX",
  "target_account": {
    "account_branch": "3952",
    "account_digit": "8",
    "account_number": "1925255",
    "account_type": "checking_account",
    "account_type_str": "Conta Corrente",
    "financial_institution_compe_number": 237,
    "financial_institution_name": "BANCO BRADESCO S.A.",
    "owner_document_number": "***.221.81*-**",
    "owner_name": "Vivo Test",
    "pix_key": "pix01@pix01.com",
    "pix_transfer_type": "key"
  },
  "transaction_amount": 12.2,
  "transaction_key": "53301505-342a-4bf4-b7de-845e5c79ed02"
}
```

## Response

STATUS 200

Response Body: Recibo de transação manual

```json
{
  "chargeback_returned_amount": null,
  "end_to_end_id": "E3210272497339911957760452404275",
  "is_chargeback": false,
  "pix_message": null,
  "pix_transfer_key": "2c4d15c4-2a03-4979-813e-0ead374686d8",
  "source_account_key": "e10a6f94-facc-4392-9eba-d0d0b278bc5d",
  "receiver_conciliation_id": "REC00000000000000000000009459463343",
  "pix_transfer_type": "transfer",
  "target_account": {
    "account_branch": "3952",
    "account_digit": "8",
    "account_number": "1925255",
    "financial_institution_compe_number": 237,
    "financial_institution_name": "BANCO BRADESCO S.A.",
    "is_internal": false,
    "ispb_number": "60746948",
    "owner_document_number": "***22181***",
    "owner_name": "Vivo Test",
    "target_pix_key": "pix01@pix01.com"
  },
  "transfer_amount": 1891268.97
}
```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

---

# Consultar chaves Pix

URL: /documentation/pix/consultar_chave

## Request

ENDPOINT /baas/pix/keys/ PIX_KEY
MÉTODO GET

### Path params

| Campo       | Tipo   | Descrição                      |
|-------------|--------|--------------------------------|
| `pix_key` * | string | Chave PIX que será consultada. |

:::info Tipos de Chave Pix
A “pix_key” pode ser um CPF, CNPJ, E-mail, Celular ou uma Chave Aleatória (UUID), seguindo as seguintes formatações:

CPF: Número inteiro com 11 dígitos.

CNPJ: Número inteiro com 14 dígitos.

E-mail: Texto contendo ao menos um “@”.

Celular: Texto contendo os seguintes valores: “+55” + “DDD do celular“ + “Número Inteiro do Celular com no mínimo 8 e no máximo 9 dígitos”. Ex: “+5511987654321“.

Chave Aleatória: UUID.
:::

## Response

STATUS 200

Response Body: Chave Ativa

```json
{
  "account_branch": "452",
  "account_digit": "1",
  "account_number": "370158",
  "account_type": "checking_account",
  "bank_code": 237,
  "end_to_end_id": "E3240250220230404185631R0kjZnC6G",
  "exists": true,
  "financial_institution": "BCO BRADESCO S.A.",
  "ispb": "60746948",
  "masked_document_number": "***.141.85*-**",
  "name": "Teste teste",
  "pix_key": "teste@gmail.com",
  "valid": true
}

```

STATUS 200

Response Body: Chave Inativa

```json
{
  "exists": false,
  "pix_key": "teste@gmail.com"
}
```

STATUS 422
Response Body: Tempo limite de consulta de chave

```json
{
    "title": "Pix Key inquiry timeout",
    "description": "Pix key inquiry timeout. Please try again.",
    "translation": "Consulta de chave pix excedeu o tempo limite. Por favor tente novamente.",
    "code": "PIX000069"
}
```

STATUS 422

Response Body: Erro ao consultar chave pix

```json
{
    "title": "Unprocessable Entity",
    "description": "Error when querying pix key 12345678000190",
    "translation": "Erro ao consultar chave pix 12345678000190",
    "code": "PIX000077"
}
```

STATUS 429

Response Body: Limite de requisições atingido

```json
{
    "title": "Rate limit reached",
    "description": "Rate limit reached when checking key in Bacen",
    "translation": "Limite de requisições atingido ao consultar chave no Bacen",
    "code": "PIX000079"
}
```

---

# Consultar chaves Pix

URL: /documentation/pix/consultar_chave_v2

## Request

ENDPOINT /pix_key/ PIX_KEY ?authenticated_user_key= CPF/CNPJ
MÉTODO GET

### Request Path Params

| Campo               | Tipo   | Descrição                      | 
|---------------------|--------|--------------------------------|
| `pix_key` * | string | Chave PIX que será consultada. |

:::info Tipos de Chave Pix
A “pix_key” pode ser um CPF, CNPJ, E-mail, Celular ou uma Chave Aleatória (UUID), seguindo as seguintes formatações:

**CPF**: Número inteiro com 11 dígitos.

**CNPJ**: Número inteiro com 14 dígitos.

**E-mail**: Texto contendo ao menos um “@”.

**Celular**: Texto contendo os seguintes valores: “+55” + “DDD do celular“ + “Número Inteiro do Celular com no mínimo 8 e no máximo 9 dígitos”. Ex: “+5511987654321“.

**Chave Aleatória**: UUID4.
:::
### Request Query String Params

| Campo               | Tipo   | Descrição                      |
|---------------------|--------|--------------------------------|
| `authenticated_user_key` * | string | Documento do titular da conta  |

## Response

STATUS 200

Response Body: Chave Ativa

```json
{
  "account_branch": "452",
  "account_digit": "1",
  "account_number": "370158",
  "owner_person_type": "legal",
  "account_type": "checking_account",
  "account_created_at": "2021-10-22T20:30.459Z",
  "end_to_end_id": "E3240250220230404185631R0kjZnC6G",
  "financial_institution": "BCO BRADESCO S.A.",
  "ispb": "60746948",
  "owner_masked_document_number": "***.141.857-**",
  "owner_name": "Teste teste",
  "pix_key": "teste@gmail.com",
  "owner_trading_name": "Teste LTDA."
}

```

| Campo | Tipo | Descrição | Max. Caracteres |
|-------|------|-----------|-----------------|
| `account_branch` *| string | Agência, sem o dígito verificador. | 4 |
| `account_digit` *| string | Dígito verificador da conta. | 1 |
| `account_number` *| string | Número de conta, sem o dígito verificador. | 20 |
| `account_type` *| string | Definição do tipo de conta. | 20 |
| `owner_person_type` *| string | Tipo de dono da conta. Pode ser "legal" ou "natural" | 7 |
| `owner_masked_document_number`* | string | Numero de CPF ou CNPJ. | 14 |
| `owner_name` *| string | Nome do dono da conta. | 120 |
| `owner_trading_name` | string | Nome fantasia do dono da conta (somente para CNPJ). | 100 |
| `ispb` *| string | ISPB do Participate detentor da chave. | 8 |
| `financial_institution` *| string | Nome da instituição financeira detentora da chave. | 200 |
| `created_at` *| datetime Zulu | Data de criação da requisição. | 20 |

STATUS 404

Response Body: Chave Inativa

```json
{
  "title": "Pix Key Not Found",
  "description": "Pix key edd5d727-ddd6-4bbb-8463-2ff1bdb28c89 not found.", 
  "translation": "A chave pix edd5d727-ddd6-4bbb-8463-2ff1bdb28c89 não foi encontrada.",
  "code": "PIX000017"
}
```

STATUS 4XX

Response Body

```json
{
    "title": "titulo",
    "description": "description in English",
    "translation": "descrição em portugues",
    "code": "codigo"
}
```

|Código HTTP | Código QI<br/>`code` | Título<br/>`title` | Descrição (eng)<br/>`Description` | Descrição (ptbr)<br/>`translation` |
|------------|-------------------|----------------|------------------------------|-----------------------------|
| 403        | PIX000080         | Not enough permission | The selected agent doesn't have permission to access this resource. | O agente selecionado não tem permissão para acessar este recurso. |
| 429        | PIX000081         | Rate Limit Exceeded | Rate Limit Exceeded | Limite de requisições excedido |
| 404        | PIX000082         | Alias not found | Alias \{alias_key\} not found | Alias \{alias_key\} não encontrado |
| 404        | PIX000083         | Pix Key not found | Pix Key \{pix_key\} not found for Alias \{alias_key\} | Chave Pix \{pix_key\} não encontrada para o Alias \{alias_key\} |
| 400        | PIX000084         | Only one query param allowed | Only one query param allowed | Somente um parâmetro de consulta é permitido |

---

# Criar Chave Pix

URL: /documentation/pix/criar_chave

## Criar Chave Pix CPF, CNPJ ou Aleatória

### Request

- MÉTODO POST
- ENDPOINT /baas/pix/keys

Request Body

```json
{
    "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
    "pix_key_type": "random_key"
}
```

Request Body

```json
{
    "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
    "pix_key_type": "cnpj",
    "pix_key": "09080702000105"
}
```

Request Body

```json
{
    "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
    "pix_key_type": "cpf",
    "pix_key": "03882617038"
}
```

:::info Tipos de Chave Pix
A “pix_key” pode ser um CPF, CNPJ, E-mail, Celular ou uma Chave Aleatória (UUID), seguindo as seguintes formatações:

CPF: Número inteiro com 11 dígitos.

CNPJ: Número inteiro com 14 dígitos.

E-mail: Texto contendo ao menos um “@”.

Celular: Texto contendo os seguintes valores: “+55” + “DDD do celular“ + “Número Inteiro do Celular com no mínimo 8 e no máximo 9 dígitos”. Ex: “+5511987654321“.

Chave Aleatória: UUID.
:::

:::info Regra de CPF/CNPJ no Ambiente Sandbox
Para simular situações de aprovação e reprovação pode ser utilizado o primeiro digito do CPF/CNPJ do titular da chave pix a ser criada:

1, 2, 3, 4, 5 -> Reprovado automático
0, 6, 7, 8, 9 -> Aprovação automática
:::

### Response

- MÉTODO POST
- ENDPOINT /baas/pix/keys

Response Body

```json
{
	"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
	"created_at": "2022-09-02T18:20:52",
	"pix_key": {
		"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
		"created_at": "2022-09-02T18:20:51",
		"pix_key": "09080702000105",
		"pix_key_status": "pending_confirmation",
		"pix_key_type": "cnpj",
		"updated_at": "2022-09-02T18:20:51"
	},
	"pix_key_request_key": "d60abf67-ad9c-42ee-9089-d26c8fc855b9",
	"request_data": {
		"account_created_at": "2022-09-02T22:44:36",
		"account_digit": "2",
		"account_number": "2359934",
		"account_type": "checking",
		"branch_number": "0001",
		"key": "09080702000105",
		"owner_document_number": "09080702000105",
		"owner_name": "VOVO LUCIA CONVENIENCIA LTDA",
		"owner_person_type": "legal",
		"trading_name": "VOVO LUCIA"
	},
	"request_failure_reason": null,
	"request_status": "pending",
	"request_type": "inclusion",
	"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
	"updated_at": "2022-09-02T18:20:52"
}
```

STATUS 400

Response Body: Chave pix já existe.

  ```json
  {
    "title": "Bad Request",
    "description": "Pix key: \{pix_key\} already exists.",
    "translation": "A chave pix: \{pix_key\} já existe.",
    "code": "PIX000065"
  }
  ```

STATUS 404

Response Body: Conta não encontrada

    ```json
    {
        "title": "Account not found",
        "description": "Conta não encontrada para account_key: \{account_key\}",
        "translation": "Conta não encontrada para account_key: \{account_key\}",
        "code": "PIX000026"
    }
    ```

STATUS 400

Response Body: Pessoa não encontrada

    ```json
    {
        "title": "Person not found",
        "description": "Pessoa não encontrada para person_key: \{person_key\}",
        "translation": "Pessoa não encontrada para person_key: \{person_key\}",
        "code": "PIX000027"
    }
    ```

STATUS 400

Response Body: Chave Pix não Finalizada

    ```json
    {
        "title": "Pix Key Creation Non Finished",
        "description": "A chave pix \{pix_key\} já possui um pedido de criação não finalizado.",
        "translation": "A chave pix \{pix_key\} já possui um pedido de criação não finalizado.",
        "code": "PIX000074"
    }
    ```

STATUS 400

Response Body: Número Máximo de Chaves Pix em Uso

    ```json
    {
        "title": "Maximum Number of Pix Keys in Use",
        "description": "A conta \{account_key\} já atingiu o número máximo de chaves pix.",
        "translation": "A conta \{account_key\} já atingiu o número máximo de chaves pix.",
        "code": "PIX000014"
    }
    ```

STATUS 400

Response Body: Conta não Aberta

    ```json
    {
        "title": "Account is not Opened",
        "description": "A conta \{account_key\} não está aberta.",
        "translation": "A conta \{account_key\} não está aberta.",
        "code": "PIX000002"
    }
    ```

STATUS 403

Response Body: Permissão Inválida

    ```json
    {
        "title": "Invalid Permission",
        "description": "A pessoa \{person_key\} não possui credenciais de administrador para a conta \{account_key\}.",
        "translation": "A pessoa \{person_key\} não possui credenciais de administrador para a conta \{account_key\}.",
        "code": "PIX000054"
    }
    ```

STATUS 422

Response Body: Tentativa de Chave Pix CPF Inválida

    ```json
    {
        "title": "Attempted CPF Pix Key is Not that of Account Owner",
        "description": "A chave pix fornecida \{pix_key\} não corresponde ao CPF {document_number} do titular da conta.",
        "translation": "A chave pix fornecida \{pix_key\} não corresponde ao CPF {document_number} do titular da conta.",
        "code": "PIX000020"
    }
    ```

:::caution Atenção
No caso da Response de criação de uma Chave Pix **Aleatória**, o campo “***pix_key***“ retornará um valor nulo. Para recuperar o valor da chave aleatória gerada, é necessária realizar uma consulta à lista de chaves cadastradas em uma conta, ou através do webhook de ativação.
:::

:::caution Atenção
A criação de chaves é assíncrona, sendo assim, a chave apenas estará disponível para uso após o recebimento do [webhook de inclusão de chave pix.](#webhook-de-inclusao-de-chave-pix)
:::

## Criar Chave Pix E-mail e Celular

**Para criação da chave:** POST no endpoint “**/baas/pix/keys**“. Neste momento, será enviado um Token para o E-mail ou Celular informado no campo “***pix_key***“.

### Request

- MÉTODO POST
- ENDPOINT /baas/pix/keys

Request Body

```json
{
    "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
    "pix_key_type": "email",
    "pix_key": "vovo.lucia@gmail.com.br"
}
```

Request Body

```json
{
    "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
    "pix_key_type": "phone_number",
    "pix_key": "+5511987654321"
}

```

### Response

- MÉTODO POST
- ENDPOINT /baas/pix/keys

Response Body

```json
{
	"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
	"created_at": "2022-09-02T17:41:55",
	"pix_key": {
		"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
		"created_at": "2022-09-02T17:41:54",
		"pix_key": "pedro.pinho@qitech.com.br",
		"pix_key_status": "pending_confirmation",
		"pix_key_type": "email",
		"updated_at": "2022-09-02T17:41:54"
	},
	"pix_key_request_key": "f6209b7e-82da-44a8-9cfa-6ad0a689adb2",
	"request_data": {
		"account_created_at": "2022-09-02T22:44:36",
		"account_digit": "2",
		"account_number": "2359934",
		"account_type": "checking",
		"branch_number": "0001",
		"key": "pedro.pinho@qitech.com.br",
		"owner_document_number": "09080702000105",
		"owner_name": "VOVO LUCIA CONVENIENCIA LTDA",
		"owner_person_type": "legal",
		"trading_name": "VOVO LUCIA"
	},
	"request_failure_reason": null,
	"request_status": "pending_validation",
	"request_type": "inclusion",
	"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
	"updated_at": "2022-09-02T17:41:55"
}
```

STATUS 400

Response Body: Chave pix já existe.

  ```json
  {
    "title": "Bad Request",
    "description": "Pix key: \{pix_key\} already exists.",
    "translation": "A chave pix: \{pix_key\} já existe.",
    "code": "PIX000065"
  }
  ```

STATUS 404

Response Body: Conta não encontrada

    ```json
    {
        "title": "Account not found",
        "description": "Conta não encontrada para account_key: \{account_key\}",
        "translation": "Conta não encontrada para account_key: \{account_key\}",
        "code": "PIX000026"
    }
    ```

STATUS 400

Response Body: Pessoa não encontrada

    ```json
    {
        "title": "Person not found",
        "description": "Pessoa não encontrada para person_key: \{person_key\}",
        "translation": "Pessoa não encontrada para person_key: \{person_key\}",
        "code": "PIX000027"
    }
    ```

STATUS 400

Response Body: Chave Pix não Finalizada

    ```json
    {
        "title": "Pix Key Creation Non Finished",
        "description": "A chave pix \{pix_key\} já possui um pedido de criação não finalizado.",
        "translation": "A chave pix \{pix_key\} já possui um pedido de criação não finalizado.",
        "code": "PIX000074"
    }
    ```

STATUS 400

Response Body: Número Máximo de Chaves Pix em Uso

    ```json
    {
        "title": "Maximum Number of Pix Keys in Use",
        "description": "A conta \{account_key\} já atingiu o número máximo de chaves pix.",
        "translation": "A conta \{account_key\} já atingiu o número máximo de chaves pix.",
        "code": "PIX000014"
    }
    ```

STATUS 400

Response Body: Conta não Aberta

    ```json
    {
        "title": "Account is not Opened",
        "description": "A conta \{account_key\} não está aberta.",
        "translation": "A conta \{account_key\} não está aberta.",
        "code": "PIX000002"
    }
    ```

STATUS 403

Response Body: Permissão Inválida

    ```json
    {
        "title": "Invalid Permission",
        "description": "A pessoa \{person_key\} não possui credenciais de administrador para a conta \{account_key\}.",
        "translation": "A pessoa \{person_key\} não possui credenciais de administrador para a conta \{account_key\}.",
        "code": "PIX000054"
    }
    ```

STATUS 422

Response Body: Tentativa de Chave Pix CPF Inválida

    ```json
    {
        "title": "Attempted CPF Pix Key is Not that of Account Owner",
        "description": "A chave pix fornecida \{pix_key\} não corresponde ao CPF {document_number} do titular da conta.",
        "translation": "A chave pix fornecida \{pix_key\} não corresponde ao CPF {document_number} do titular da conta.",
        "code": "PIX000020"
    }
    ```

**IMPORTANTE:** O valor retornado no campo “pix_key_request_key“ deve ser utilizado na URL da requisição para aprovação da criação da Chave Pix.

## Aprovação de Chave Pix E-mail ou Celular

### Request

- MÉTODO PATCH
- ENDPOINT /baas/pix/keys/ PIX_KEY_REQUEST_KEY /twofa_validation

Request Body

```json
{
    "verification_code": "756816"
}
```

### Response

Response Body

```json
{
	"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
	"created_at": "2022-09-02T17:41:55",
	"pix_key": {
		"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
		"created_at": "2022-09-02T17:41:54",
		"pix_key": "pedro.pinho@qitech.com.br",
		"pix_key_status": "pending_confirmation",
		"pix_key_type": "email",
		"updated_at": "2022-09-02T17:41:54"
	},
	"pix_key_request_key": "f6209b7e-82da-44a8-9cfa-6ad0a689adb2",
	"request_data": {
		"account_created_at": "2022-09-02T22:44:36",
		"account_digit": "2",
		"account_number": "2359934",
		"account_type": "checking",
		"branch_number": "0001",
		"key": "pedro.pinho@qitech.com.br",
		"owner_document_number": "09080702000105",
		"owner_name": "VOVO LUCIA CONVENIENCIA LTDA",
		"owner_person_type": "legal",
		"trading_name": "VOVO LUCIA"
	},
	"request_failure_reason": null,
	"request_status": "pending",
	"request_type": "inclusion",
	"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
	"updated_at": "2022-09-02T17:41:55"
}
```

STATUS 404

Response Body: Solicitação de chave Pix não encontrada

    ```json
    {
      "title": "Pix Key Request not found",
      "description": "Pix Key Request not found for key: {pix_key_request_key}.",
      "translation": "Pix Key Request não encontrada para a chave: {pix_key_request_key}.",
      "code": "PIX000008"
    }
    ```

STATUS 403

Response Body: Erro do Validador de Permissão

    ```json
    {
        "title": "Permission Validator Error",
        "description": "Selected agent do not own this item.",
        "translation": "O agente selecionado não é dono do item.",
        "code": "QIT000005"
    }
    ```

STATUS 400

Response Body: Pedido de criação não possui validação

    ```json
    {
        "title": "Key request does not have validation",
        "description": "Key request does not have two steps validation",
        "translation": "Pedido de criação não possui validação de duas etapas",
        "code": "PIX000075"
    }
    ```

STATUS 400

Response Body: Pedido de criação não está pendente de validação

    ```json
    {
        "title": "Key Request Is Not Pending Validation",
        "description": "Key request {pix_key_request_key}, is not pending validation.",
        "translation": "Pedido de criação {pix_key_request_key}, não está pendente de validação.",
        "code": "PIX000076"
    }
    ```

STATUS 404

Response Body: Token Expirado

    ```json
    {
        "title": "Gone",
        "description": {
            "description": "Expired Code.",
            "translation": "Código de verificação expirado."
        },
        "translation": {},
        "extra_fields": {},
        "code": "2FA000410"
    }
    ```

STATUS 403

Response Body: Token Expirado

    ```json
    {
        "title": "Forbidden",
        "description": {
            "description": "Code already verified.",
            "translation": "Este código já foi utilizado."
        },
        "translation": {},
        "extra_fields": {},
        "code": "2FA000403"
    }
    ```

## Reenviar o token de aprovação

### Request

- MÉTODO PATCH
- ENDPOINT /baas/pix/keys/ PIX_KEY_REQUEST_KEY /resend_twofa

Request Body

```json
{}
```

### Response

Response Body

```json
{
	"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
	"created_at": "2022-09-02T17:41:55",
	"pix_key": {
		"account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
		"created_at": "2022-09-02T17:41:54",
		"pix_key": "pedro.pinho@qitech.com.br",
		"pix_key_status": "pending_confirmation",
		"pix_key_type": "email",
		"updated_at": "2022-09-02T17:41:54"
	},
	"pix_key_request_key": "f6209b7e-82da-44a8-9cfa-6ad0a689adb2",
	"request_data": {
		"account_created_at": "2022-09-02T22:44:36",
		"account_digit": "2",
		"account_number": "2359934",
		"account_type": "checking",
		"branch_number": "0001",
		"key": "pedro.pinho@qitech.com.br",
		"owner_document_number": "09080702000105",
		"owner_name": "VOVO LUCIA CONVENIENCIA LTDA",
		"owner_person_type": "legal",
		"trading_name": "VOVO LUCIA"
	},
	"request_failure_reason": null,
	"request_status": "pending_validation",
	"request_type": "inclusion",
	"requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
	"updated_at": "2022-09-02T17:41:55"
}
```

STATUS 404

Response Body: Solicitação de chave Pix não encontrada

    ```json
    {
      "title": "Pix Key Request not found",
      "description": "Pix Key Request not found for key: {pix_key_request_key}.",
      "translation": "Pix Key Request não encontrada para a chave: {pix_key_request_key}.",
      "code": "PIX000008"
    }
    ```

STATUS 403

Response Body: Erro do Validador de Permissão

    ```json
    {
        "title": "Permission Validator Error",
        "description": "Selected agent do not own this item.",
        "translation": "O agente selecionado não é dono do item.",
        "code": "QIT000005"
    }
    ```

STATUS 400

Response Body: Pedido de criação não possui validação

    ```json
    {
        "title": "Key request does not have validation",
        "description": "Key request does not have two steps validation",
        "translation": "Pedido de criação não possui validação de duas etapas",
        "code": "PIX000075"
    }
    ```

STATUS 400

Response Body: Pedido de criação não está pendente de validação

    ```json
    {
        "title": "Key Request Is Not Pending Validation",
        "description": "Key request {pix_key_request_key}, is not pending validation.",
        "translation": "Pedido de criação {pix_key_request_key}, não está pendente de validação.",
        "code": "PIX000076"
    }
    ```

### Webhook de Inclusão de Chave Pix

WEBHOOK_TYPE key_inclusion
STATUS approved

Webhook Body

```json
{
	"pix_key": "c232142c-ddbf-41d6-a54f-3b90c28b97dc",
	"account_key": "94945886-7a6f-43e6-a307-e36c959e4903",
	"webhook_type": "key_inclusion",
	"pix_key_status": "active",
	"pix_key_request_key": "e274eb13-40b3-4902-978e-8e5fa267af53",
	"pix_key_request_type": "inclusion",
	"pix_key_request_status": "approved"
}
```

WEBHOOK_TYPE key_inclusion
STATUS failed

Webhook Body

```json
{
	"pix_key": "03882617038",
	"account_key": "94945886-7a6f-43e6-a307-e36c959e4903",
	"webhook_type": "key_inclusion",
	"pix_key_status": "inactivated",
	"pix_key_request_key": "e274eb13-40b3-4902-978e-8e5fa267af53",
	"pix_key_request_type": "inclusion",
	"pix_key_request_status": "failed",
	"request_failure_reason": "DCT200016"
}
```

:::info Código de Motivo de Falha da Requisição
- DCT200012: Já existe vínculo para essa chave, mas ela é possuída por outra pessoa. Indica-se que seja feita uma reivindicação de posse.
- DCT200013: Já existe vínculo para essa chave com o mesmo dono, mas ela encontra-se associada a outro participante. Indica-se que seja feita uma reivindicação de portabilidade.
- DCT200014: Existe uma reivindicação com status diferente de concluída ou cancelada para a chave do vínculo. Enquanto estiver nessa situação, o vínculo não pode ser excluído.
- DCT200015: Falha na validação dos parâmetros informados no request.
- DCT200016: O titular da chave (CPF/CNPJ) possui situação cadastral irregular. A inclusão da chave PIX não é permitida até a regularização.
:::

---

# Criar QR Code Pix dinâmico

URL: /documentation/pix/criar_qr_code_dinamico

## Request

ENDPOINT /baas/qrcode/dynamic
MÉTODO POST

Request Body: Com vencimento

```json
{
  "account_key": "f0d363be-fc49-4cfc-a1f8-c8d4d4195095",
  "amount": 22.34,
  "occurrence_type": "registration",
  "payer_document_number": "00000000000000",
  "payer_name": "Random",
  "payer_person_type": "legal",
  "payer_request": "Payment for order XXXXXXXXXX",
  "pix_key": "3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
  "receiver_conciliation_id": "3d7d6a2bf72f44z7bb2079a94dff5645",
  "qr_code_type": "dynamic_term",
  "additional_data": [
    {
      "key_name": "Juros e Multa",
      "value": "Juros 2 ao mes e multa de 1%"
    }
  ],
  "fine_amount": 3,
  "interest_amount": 2,
  "expiration_date": "2023-03-25",
  "max_payment_days": 128,
  "rebate_amount": 1,
  "discounts": []
}

```

Request Body: Pagamento imediato

```json
{
  "account_key": "f0d363be-fc49-4cfc-a1f8-c8d4d4195095",
  "amount": 22.34,
  "expiration_seconds": 864000,
  "occurrence_type": "registration",
  "payer_document_number": "00000000000000",
  "payer_name": "Random",
  "payer_person_type": "legal",
  "payer_request": "Payment for order XXXXXXXXXX",
  "pix_key": "3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
  "receiver_conciliation_id": "3d7d6a2bf72f44z7bb2079a94dff5645",
  "qr_code_type": "dynamic_instant",
  "additional_data": [
    {
      "key_name": "Juros e Multa",
      "value": "Juros 2 ao mes e multa de 1%"
    }
  ],
  "fine_amount": 3,
  "interest_amount": 2,
  "max_payment_days": 128,
  "rebate_amount": 1,
  "discounts": []
}

```

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `amount` * | float | Valor do QR Code antes do cálculo de descontos ou juros e multas. | - |
| `occurrence_type` * |  string |Tipo de ocorrencia. payment: Ocorrência do tipo pagamento, registration: Ocorrência do tipo registro, write_off: Ocorrência do tipo cancelamento pelo gerador, bank_written_off: Ocorrência do tipo cancelamento pelo banco. | - |
| `qr_code_type` * | string | Tipo do QR Code dinâmico | - |
| `pix_key` * | string | Chave Pix que representa a conta de destino da transação. | - |
| `receiver_conciliation_id` * | string | Identificador único para conciliação  | 32 |
| `expiration_date` | date | Data de vencimento da cobrança (no formato "YYYY-MM-DD" | - |
| `expiration_seconds`  | string | indica qual o tempo de validad e do QR Code em segundos, padrão 1 dia. | - |
| `payer_name` * | string | Nome do pagador. | - |
| `payer_document_number` * | string | CPF do pagador. | - |
| `payer_person_type` * | string | Tipo de pessoa (natural = física ou legal = jurídica). | - |
| `payer_request` * | string | Mensagem ao pagador. | - |
| `additional_data` * | array of objects | Informações que serão apresentadas para o pagador. | - |
| `max_payment_days` * | int32 | Dias máximo para pagamento da cobrança. |  - |
| `rebate_amount` * | float | Valor absoluto de abatimento antes do pagamento. | - |
| `interest_amount` * | float | Valor absoluto por dia de atraso após o vencimento, caso seja pago um dia após o vencimento o valor total será o valor ordinario + multa. |  - |
| `fine_amount` * | float | Multa em valor absoluto após o vencimento. |  - |
| `discounts` * | array of objects | Configurações de desconto. |  - |

### Objeto additional_data

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `key_name` * | string |  Nome do campo | - |
| `value` | string | Valor do campo | - |

### Objeto discount

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `discount_value` * | float |  Valor do desconto. | - |
| `discount_number` | int32 | Ordem que o desconto deve ser aplicado. | - |
| `discount_limit_date` | string | Data limite do desconto. | - |

## Response

STATUS 200

Response Body: Com vencimento

```json
{
  "qr_code_type": "dynamic_instant",
  "amount": 22.34,
  "expiration_seconds": null,
  "max_payment_days": null,
  "receiver_conciliation_id": "01GVGV9NXBCY287Z6CJ4S0ENW9",
  "payer_name": "Random",
  "payer_document_number": "00000000000000",
  "payer_person_type": "legal",
  "payer_request": "Payment for order XXXXXXXXXXXX",
  "pix_message": null,
  "modality_alteration": false,
  "expiration_date": "2023-03-25",
  "rebate_amount": 1,
  "interest_amount": 2,
  "fine_amount": 3,
  "paid_amount": null,
  "discounts": [],
  "additional_data": [],
  "origin": "system",
  "origin_key": null,
  "pix_key": "3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
  "qr_code_key": "6fd14834-03e3-4777-b907-d2c43d4c2a1e",
  "occurrence_type": "registration",
  "end_to_end_id": null,
  "source_account_branch": null,
  "source_account_financial_institution": null,
  "source_account_ispb": null,
  "source_account_number": null,
  "source_account_digit": null,
  "disable": null,
  "qr_code_occurrence_key": "38c55754-2c26-4065-aa21-240c6b9a8ce7",
  "base_64": "\<BASE64 DA URI DO PIX COPIA E COLA\>",
  "image": "\<BASE64 DA IMAGEM\>"
}

```

STATUS 200

Response Body: Pagamento imediato

```json
{
  "qr_code_type": "dynamic_instant",
  "amount": 22.34,
  "expiration_seconds": 864000,
  "max_payment_days": null,
  "receiver_conciliation_id": "01GVGV9NXBCY287Z6CJ4S0ENW9",
  "payer_name": "Random",
  "payer_document_number": "00000000000000",
  "payer_person_type": "legal",
  "payer_request": "Payment for order XXXXXXXXXXXX",
  "pix_message": null,
  "modality_alteration": false,
  "expiration_date": null,
  "rebate_amount": 1,
  "interest_amount": 2,
  "fine_amount": 3,
  "paid_amount": null,
  "discounts": [],
  "additional_data": [],
  "origin": "system",
  "origin_key": null,
  "pix_key": "3d7d6a2b-f72f-44z7-bb20-79a94dff5645",
  "qr_code_key": "6fd14834-03e3-4777-b907-d2c43d4c2a1e",
  "occurrence_type": "registration",
  "end_to_end_id": null,
  "source_account_branch": null,
  "source_account_financial_institution": null,
  "source_account_ispb": null,
  "source_account_number": null,
  "source_account_digit": null,
  "disable": null,
  "qr_code_occurrence_key": "38c55754-2c26-4065-aa21-240c6b9a8ce7",
  "base_64": "\<BASE64 DA URI DO PIX COPIA E COLA\>",
  "image": "\<BASE64 DA IMAGEM\>"
}

```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

---

# Criar QR Code Estático

URL: /documentation/pix/criar_qr_code_estatico

## Request

ENDPOINT /baas/qrcode/static
MÉTODO POST

Request Body

```json
{
    "qr_code_format": "both",
    "pix_key": "3d7d6a2b-f72f-44c7-bb20-79a94dff5954",
    "receiver_name": "Tywin Lannister",
    "amount": 10.25
}

```

### Body params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `qrcode_format` | string | indica qual o tipo de retorno após a geração do QR Code (image, payload, both: padrão). | - |
| `pix_key` * | string |Chave Pix atrelada a conta de recebimento ao executar o pagamento com o QR Code. | 10 |
| `receiver_name` * | string | Nome do dono da conta. | - |
| `amount` | float | Valor do QR Code. Caso não seja enviado o pagador deverá inserir o total durante a transferência. | - |

## Response

STATUS 200

Response Body

```json
{
  "image": "\<BASE64 DA IMAGEM\>",
  "payload": "\<BASE64 DA URI DO PIX COPIA E COLA\>"
}

```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

---

# Decodificar QR Code Pix

URL: /documentation/pix/decodificar_qr_code

Decodifica um QR Code Pix retornando os dados contidos no payload. Não realiza consulta DICT na conta destino e não persiste o QR Code consultado — adequado para fluxos de pré-visualização (preview) antes da decisão de pagamento.

## Request

ENDPOINT /pix/decode_qrcode_payload
MÉTODO POST

Request Body

```json
{
   "qr_code_payload": "00020126580014br.gov.bcb.pix0136a23bf0e9-5175-4829-bf89-e8fe6ac09aa1520400005303986540530.005802BR5914TywinLannister6008saopaulo62070503***6304D4FD"
}
```

### Body Params

| Campo               | Tipo   | Descrição               | Caracteres |
|---------------------|--------|-------------------------|------------|
| `qr_code_payload` * | string | Pix Copia e Cola        | -          |

## Response

STATUS 200

Response Body: QR Code estático

```json
{
  "qr_code_type": "static",
  "qr_code_payload": "00020126580014br.gov.bcb.pix0136a23bf0e9-5175-4829-bf89-e8fe6ac09aa1520400005303986540530.005802BR5914TywinLannister6008saopaulo62070503***6304D4FD",
  "pix_key": "a23bf0e9-5175-4829-bf89-e8fe6ac09aa1",
  "transfer_amount": "30.00",
  "additional_data": null,
  "qr_code_data": {
    "target_pix_key": "a23bf0e9-5175-4829-bf89-e8fe6ac09aa1",
    "amount": "30.00",
    "receiver_conciliation_id": "***",
    "additional_data": [],
    "category_code": "0000",
    "city": "saopaulo",
    "postal_code": null,
    "reusable_qrcode": "no"
  }
}
```

STATUS 200

Response Body: QR Code dinâmico pagamento imediato

```json
{
  "qr_code_type": "dynamic_instant",
  "qr_code_payload": "00020101021226850014br.gov.bcb.pix2563qrcodepix.bb.com.br/pix/v2/d373e385-dfe7-49f6-b9ec-14ba60a9b8285204000053039865802BR5925TESTE62070503***63047B7D",
  "pix_key": "teste.cobrancapix@gmail.com.br",
  "receiver_conciliation_id": "fgnb4NTt7pOUBGfrcporERwVVqr0f8PWRfK",
  "amount": "9367.61",
  "status": "ATIVA",
  "qr_code_data": {
    "target_pix_key": "teste.cobrancapix@gmail.com.br",
    "receiver_conciliation_id": "fgnb4NTt7pOUBGfrcporERwVVqr0f8PWRfK",
    "amount": "9367.61",
    "can_change": "no",
    "expiration_seconds": 201574,
    "created_at": "2023-03-13T19:00:28.440Z",
    "presented_at": "2023-03-14T19:07:48.729Z",
    "question_to_payer": "Liquidacao de Parcelas",
    "status": "ATIVA",
    "revision": 0,
    "category_code": "0000",
    "city": "RIO DE JANEIRO",
    "postal_code": null,
    "reusable_qrcode": "no",
    "receiver_url": "qrcodepix.bb.com.br/pix/v2/d373e385-dfe7-49f6-b9ec-14ba60a90000",
    "additional_data": [],
    "payer_name": "ISMAEL FATIMA AMARAL",
    "payer_document_number": "10003550206",
    "payer_person_type": "natural",
    "target_name": "TESTE LTDA.",
    "target_trading_name": null,
    "address": "Rua Tapajos, 941",
    "state": "RJ"
  }
}
```

STATUS 200

Response Body: QR Code dinâmico com vencimento

```json
{
  "qr_code_type": "dynamic_term",
  "qr_code_payload": "00020101021226840014br.gov.bcb.pix2562invoice.starkbank.com/v2/cobv/8b434df48c30482a81f7c936ae35cc123456000053039865802BR5925Oncred Sociedade de Credi6015TESTE 62070503***6304D008",
  "pix_key": "e623e7b0-d00a-400e-aee6-79632430e817",
  "receiver_conciliation_id": "8b434df48c30482a81f7c936ae35cc87",
  "amount": "55.59",
  "status": "ATIVA",
  "qr_code_data": {
    "target_pix_key": "e623e7b0-d00a-400e-aee6-79632430e817",
    "receiver_conciliation_id": "8b434df48c30482a81f7c936ae35cc87",
    "original_amount": "55.59",
    "reduction_amount": null,
    "discount_amount": null,
    "fee_amount": null,
    "fine_amount": null,
    "amount": "55.59",
    "due_date": "2023-03-27",
    "days_after_due_accepted": 16,
    "created_at": "2023-01-10T19:49:58.30Z",
    "presented_at": "2023-03-10T15:32:15.87Z",
    "question_to_payer": null,
    "status": "ATIVA",
    "revision": 0,
    "category_code": "0000",
    "reusable_qrcode": "no",
    "receiver_url": "invoice.starkbank.com/v2/cobv/8b434df48c30482a81f7c936ae351234",
    "additional_data": [],
    "payer_name": "Willian Rocha",
    "payer_document_number": "00000000000",
    "payer_person_type": "natural",
    "target_name": "TESTE LTDA.",
    "target_trading_name": null,
    "address": "Rua Tapajos, 941",
    "state": "SP",
    "city": "Sao Caetano do Sul",
    "postal_code": "09551230"
  }
}
```

### Campos da resposta

| Campo                              | Tipo            | Descrição                                                                                  | Presente em       |
|------------------------------------|-----------------|--------------------------------------------------------------------------------------------|-------------------|
| `qr_code_type`                     | string          | Tipo do QR Code: `static`, `dynamic_instant` ou `dynamic_term`                             | Todos             |
| `qr_code_payload`                  | string          | Payload EMV original enviado na requisição                                                 | Todos             |
| `qr_code_data.target_pix_key`      | string          | Chave Pix do recebedor                                                                     | Todos             |
| `qr_code_data.amount`              | string/decimal  | Valor da cobrança. Em `dynamic_term` representa o valor final (após multa/juros/desconto)  | Todos             |
| `qr_code_data.receiver_conciliation_id` | string     | Identificador de conciliação do recebedor (txid)                                           | Todos             |
| `qr_code_data.additional_data`     | array           | Lista de informações adicionais `{name, value}`                                            | Todos             |
| `qr_code_data.category_code`       | string          | Código de categoria do estabelecimento (MCC)                                               | Todos             |
| `qr_code_data.city`                | string          | Cidade do recebedor                                                                        | Todos             |
| `qr_code_data.postal_code`         | string          | CEP do recebedor                                                                           | Todos             |
| `qr_code_data.reusable_qrcode`     | string          | `yes` se o QR Code pode ser pago múltiplas vezes, `no` caso contrário                      | Todos             |
| `qr_code_data.receiver_url`        | string          | URL do PSP do recebedor (campo `loc` do BR Code)                                           | `dynamic_*`       |
| `qr_code_data.status`              | string          | Status da cobrança (ver enumeradores abaixo)                                               | `dynamic_*`       |
| `qr_code_data.revision`            | integer         | Versão atual da cobrança                                                                   | `dynamic_*`       |
| `qr_code_data.created_at`          | string (ISO)    | Data de criação da cobrança no PSP do recebedor                                            | `dynamic_*`       |
| `qr_code_data.presented_at`        | string (ISO)    | Data de apresentação da cobrança ao pagador                                                | `dynamic_*`       |
| `qr_code_data.question_to_payer`   | string          | Mensagem do recebedor para o pagador (`solicitacaoPagador`)                                | `dynamic_*`       |
| `qr_code_data.payer_name`          | string          | Nome do pagador esperado, quando informado pelo recebedor                                  | `dynamic_*`       |
| `qr_code_data.payer_document_number` | string        | CPF/CNPJ do pagador esperado                                                               | `dynamic_*`       |
| `qr_code_data.payer_person_type`   | string          | `natural` ou `legal`                                                                       | `dynamic_*`       |
| `qr_code_data.target_name`         | string          | Nome do recebedor                                                                          | `dynamic_*`       |
| `qr_code_data.expiration_seconds`  | integer         | Tempo de validade da cobrança em segundos a partir de `created_at`                         | `dynamic_instant` |
| `qr_code_data.can_change`          | string          | `yes` se o pagador pode alterar o valor, `no` caso contrário                               | `dynamic_instant` |
| `qr_code_data.original_amount`     | string/decimal  | Valor original da cobrança antes de multa/juros/desconto                                   | `dynamic_term`    |
| `qr_code_data.due_date`            | string (date)   | Data de vencimento da cobrança                                                             | `dynamic_term`    |
| `qr_code_data.days_after_due_accepted` | integer     | Dias após o vencimento em que a cobrança ainda aceita pagamento                            | `dynamic_term`    |
| `qr_code_data.fine_amount`         | string/decimal  | Multa aplicada após o vencimento                                                           | `dynamic_term`    |
| `qr_code_data.fee_amount`          | string/decimal  | Juros aplicados após o vencimento                                                          | `dynamic_term`    |
| `qr_code_data.discount_amount`     | string/decimal  | Desconto concedido antes do vencimento                                                     | `dynamic_term`    |
| `qr_code_data.reduction_amount`    | string/decimal  | Abatimento aplicado à cobrança                                                             | `dynamic_term`    |
| `qr_code_data.target_trading_name` | string          | Nome fantasia do recebedor                                                                 | `dynamic_*`       |
| `qr_code_data.address`             | string          | Logradouro do recebedor                                                                    | `dynamic_*`       |
| `qr_code_data.state`               | string          | UF do recebedor                                                                            | `dynamic_*`       |

:::caution Campos deprecated na raiz da resposta
Os campos abaixo são retornados na raiz da resposta apenas por retrocompatibilidade e serão removidos em uma versão futura. Utilize os equivalentes dentro de `qr_code_data`.

| Campo                      | Equivalente                              | Presente em  |
|----------------------------|------------------------------------------|--------------|
| `pix_key`                  | `qr_code_data.target_pix_key`            | Todos        |
| `transfer_amount`          | `qr_code_data.amount`                    | `static`     |
| `additional_data`          | `qr_code_data.additional_data`           | `static`     |
| `amount`                   | `qr_code_data.amount`                    | `dynamic_*`  |
| `receiver_conciliation_id` | `qr_code_data.receiver_conciliation_id`  | `dynamic_*`  |
| `status`                   | `qr_code_data.status`                    | `dynamic_*`  |
:::

:::info QR Code estático
Por especificação do BR Code, QR Codes estáticos não contêm dados do pagador esperado, data de expiração, multa, juros, descontos nem abatimento. Esses campos só existem em QR Codes dinâmicos.
:::

:::info Status
Para o QR Code do tipo dinâmico, é retornado o status do QR Code conforme a tabela de enumeradores abaixo.
:::

#### Enumeradores Status QR Code dinâmico

| Enumerador                          | Descrição                                            |
|-------------------------------------|------------------------------------------------------|
| **ATIVA**                           | Cobrança disponível, sem pagamento realizado         |
| **CONCLUIDA**                       | Cobrança paga e finalizada                           |
| **REMOVIDA_PELO_USUARIO_RECEBEDOR** | Usuário recebedor solicitou a remoção da cobrança    |
| **REMOVIDA_PELO_PSP**               | Banco recebedor solicitou a remoção da cobrança      |

## Erros

STATUS 400

QR Code com formato inválido

```json
{
  "data": "{\"title\": \"Invalid Qr Code Format\", \"description\": \"The Qr Code format is invalid, please enter a valid Qr Code\", \"translation\": \"O formato do Qr Code é inválido, por favor insira um Qr Code válido\", \"extra_fields\": {}, \"code\": \"PXT000070\"}"
}

```

Tipo de QR Code não identificado no payload

```json
{
  "data": "{\"title\": \"Invalid Qr Code Type\", \"description\": \"The Qr Code payload given did not provide a propper Qr Code type\", \"translation\": \"O payload de QR Code fornecido não contêm um tipo de Qr Code Válido\", \"extra_fields\": {}, \"code\": \"PXT000071\"}"
}

```

Erro ao processar QR Code dinâmico

```json
{
  "data": "{\"title\": \"Error in Qr Code Payload Request\", \"description\": \"An error occurred while requesting the qr code payload to the registry institution\", \"translation\": \"Um erro ocorreu durante a requisição do payload do qr code para a instituição de registro\", \"extra_fields\": {}, \"code\": \"PXT000069\"}"
}

```

---

# Excluir chave Pix

URL: /documentation/pix/excluir_chave

## Request

ENDPOINT /baas/pix/keys/ PIX_KEY
MÉTODO DELETE

### Path params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `pix_key` * | string |  Chave PIX que será excluída. | chave uuid |  

## Response

STATUS 200

Response Body

```json
{
  "account_key": "9d3d0083-ac71-43f0-8a90-c00a157a4883",
  "created_at": "2021-12-06T21:16:11",
  "pix_key": {
    "account_key": "9d3d0083-ac71-43f0-8a90-c00a157a4883",
    "created_at": "2021-12-06T21:16:11",
    "pix_key": "b1afcafb-bd88-4958-b8ab-48c3a00044a0",
    "pix_key_status": "inactive",
    "pix_key_type": "random_key",
    "updated_at": "2021-12-06T21:16:22"
  },
  "pix_key_request_key": "ab816c64-bce9-42e9-be6f-9f690a1dccbc",
  "request_data": {},
  "request_failure_reason": null,
  "request_status": "approved",
  "request_type": "deletion",
  "requester_key": "62d1f47a-397d-4a46-bcf6-29e4a07d1375",
  "updated_at": "2021-12-06T21:16:22"
}

```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

---

# Introdução

URL: /documentation/pix/introducao

Pix é o pagamento instantâneo brasileiro. O meio de pagamento criado pelo Banco Central (BACEN) em que os recursos são transferidos entre contas em poucos segundos, a qualquer hora ou dia. É prático, rápido e seguro.

A QI Tech por ser uma instituição homologada junto ao Banco Central é integrante do Sistema de Pagamento Brasileiro (SPB), podendo oferecer mais essa facilidade aos seus clientes.

## Vantagens e potencial
Além de aumentar a velocidade em que pagamentos ou transferências são feitos e recebidos, o Pix tem o potencial de:

- Alavancar a competitividade e a eficiência do mercado;
- Baixar o custo, aumentar a segurança e aprimorar a experiência dos clientes;
- Incentivar a eletronização do mercado de pagamentos de varejo;
- Promover a inclusão financeira; e
- Preencher uma série de lacunas existentes na cesta de instrumentos de pagamentos disponíveis atualmente à população.

## Erros

### Exemplo de resposta de erro:

**Response Body**

```json
{
  "title": "SPI Timeout Control",
  "description": "SPI Timeout Control.",
  "translation": "Controle de timeout no SPI.",
  "extra_fields": {
    "description": "SPI Timeout Control.",
    "translation": "Controle de timeout no SPI.",
    "external_title": "SPI Timeout Control",
    "external_code": "PXP000007"
  },
  "code": "PXP000007"
}
```

### Tabela de erros:

| Code | Message | Status HTTP | Description | Translated description |
|---|---|---|---|---|
| QIT000403 | Forbidden | 403 | Participant has not rights to this operation. | Participante não tem poderes para essa operação. |
| QIT000400 | BadRequest | 400 | The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, size too large, invalid request message framing, or deceptive request routing). | O servidor não pode ou não processará a request devido a um erro do cliente (por exemplo, sintaxe de request malformada, tamanho muito grande, enquadramento de mensagem de request inválida ou roteamento de request enganoso). |
| PXP000046 | Gone | 410 | Expired QR code. |QR Code expirado. |
| PXP000046 | Gone | 410 | Expired QR code. | QR Code expirado. |
| QIT000404 | NotFound | 404 | The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible. | O resource solicitado não pôde ser encontrado, mas pode estar disponível no futuro. Requests subsequentes do cliente são permitidos. |
| QIT000500 | InternalServerError | 500 | An internal error has occurred and its being investigated. | Um erro interno aconteceu e está sendo investigado. |
| PXP000040 | ClaimKeyNotFound | 408 | Claim Key Not Found. | Chave a ser reivindicada não encontrada. |
| QIT000403 | Forbidden | AB03 | Participant has not rights to this operation. | Translated description |
| PXP000007 | AB03 | 408 | SPI Timeout Control. | Controle de timeout no SPI. |
| PXP000037 | AB09 | 502 | Cancelled transaction due to receiver's internal error. | Transação interrompida devido a erro no PSP do Recebedor. |
| PXP000037 | AB11 | 408 | Target PSP Timeout. | Timeout do participante emissor da ordem de pagamento. |
| PXP000009 | AC03 | 400 | Target account number is invalid. | Número da conta de destino é inexistente ou inválido. |
| PXP000010 | AC06 | 400 | Target account is blocked. | A conta de destino encontra-se bloqueada. |
| PXP000011 | AC07 | 400 | Target account is closed. | A conta de destino encontra-se encerrada. |
| PXP000032 | AC14 | 400 | Incorrect type for target account. | Tipo incorreto para a conta transacional especificada. | 
| PXP000012 | AG03 | 400 | Unsupported transaction for given target account. | A conta de destino não suporta este tipo de transação. |
| PXP000013 | AGNT | 400 | SPI participant is not PSP settler agent of payer nor receiver. | Participante direto do SPI não é liquidante do PSP do Pagador / Recebedor. |
| PXP000014 | AM01 | 400 | Zero value payment order. | Ordem de pagamento com valor zero. |
| PXP000015 | AM04 | 400 | Insufficient funds in PI account from payer. | Saldo insuficiente na conta PI do pagador. |
| PXP000016 | AM09 | 400 | Return value greater than corresponding payment order. | Valor de devolução acima do valor de pagamento correspondente. |
| PXP000017 | AM18 | 400 | Invalid transactions number. | Quantidade de transações inválida. |
| PXP000018 | BE01 | 400 | Beneficiary document number is not that of target account owner. | CPF/CNPJ do usuário recebedor não é compatível com o titular da conta de destino. |
| PXP000019 | CH11 | 400 | Invalid beneficiary document number. | CPF/CNPJ da conta de destino está incorreto. |
| PXP000020 | CH16 | 400 | Incorrect message element. | Elemento da mensagem incorreto. |
| PXP000021 | DS04 | 400 | Beneficiary's PSP has rejected payment order. | Ordem de pagamento foi rejeitada pelo banco recebedor. |
| PXP000022 | DS0G | 403 | Signing participant is unauthorized to make a payment order for paying account. | Participante que assinou a mensagem não é autorizado a realizar a operação na conta PI debitada. |
| PXP000023 | DT02 | 400 | Invalid datetime for message delivery. | Data e Hora do envio da mensagem inválida. |
| PXP000024 | ED05 | 400 | Error while processing payment (generic error). | Erro no processamento do pagamento (erro genérico). |
| PXP000025 | FF08 | 400 | Badly formatted operation's identifier. | Identificador da operação mal formatado. |
| PXP000026 | RC09 | 400 | Invalid or non-existent payer's PSP ISPB number. | Número ISPB do PSP do Pagador é inválido ou inexistente. |
| PXP000027 | RC10 | 400 | Invalid or non-existent beneficiary's PSP ISPB number. | Número ISPB do banco recebedor é inválido ou inexistente. |
| PXP000043 | DS27 | 400 | Invalid or non-existent ISPB number. | Número ISPB é inválido ou inexistente. |
| PXP000044 | AM02 | 400 | Amount too great for credited account. | Valor de pagamento/devolução acima do permitido para a conta de destino creditada. |
| PXP000028 | JDPISPI001 | 500 | Insufficient funds on JDPI managed PI account. | Saldo insuficiente na conta PI gerenciada pelo JDPI. |
| PXP000029 | JDPISPI002 | 500 | SPI has returned admi.002 message. N/A. | SPI retornou mensagem admi.002. Erro retornado na mensagem: N/A. |
| PXP000030 | JDPISPI003 | 500 | Insufficient funds on PSP sub-account. | Saldo insuficiente na subconta do PSP. |
| PXP000031 | JDPISPI004 | 500 | General failure during debt on JDPI managed PI account. | Falha geral ao realizar o débito em conta PI gerenciada pelo JDPI. |
| PXP000001 | JDPICHV001 | 404 | Pix key not found. | Chave Pix não encontrada. |
| PXP000002 | JDPICHV002 | 404 | Account has no pix keys linked. | Conta não possui nenhuma chave pix. |
| PXP000003 | JDPICHV003 | 404 | CPF/CNPJ has no pix keys linked. | CPF/CNPJ informada não possui nenhuma chave pix vinculada. |
| PXP000004 | JDPICHV004 | 400 | Pix key already linked on DICT. | Chave pix já está vinculada. |
| PXP000005 | JDPICHV005 | 400 | Pix key is linked to another person. Claim recommended. | Chave pix existe mas está possuída por outra pessoa. Reivindicação de posse recomendada. |
| PXP000006 | JDPICHV006 | 400 | Pix key is linked on another account of the same owner. Key alteration recommended. | Chave pix está vinculada a outra conta com o mesmo dono. Alteração de chave recomendada. |
| PXP000033 | JDPICHV007 | 400 | Missing new account or client name on pix key alteration request. | Nova conta ou nome do cliente faltando no pedido de alteração de chave pix. |
| PXP000034 | JDPICHV008 | 400 | Wrong field for trading name on natural person pix key alteration. | Campo para nome fantasia incorreto para alteração de chave pix pessoa física.recomendada. |
| PXP000035 | JDPICHV009 | 400 | Missing account type, account number, account created at, name or trading name on key alteration request. | Dados incompletos para alteração de chave pix. Faltando tipo de conta, número da conta, data de abertura, nome ou nome fantasia. |
| PXP000042 | JDPIRVN011 | 400 | Claim current status does not allow conclusion. | A situação da sua Reivindicação não permite a sua conclusão. |
| PXP000041 | JDPIRVN014 | 400 | Claim Key Not Found. | Chave a ser reivindicada não encontrada. |
| PXP000046 | EntryKeyInCustodyOfDifferentParticipant | 400 | There is already a link for this key with the same owner, but it is associated with another participant. It is indicated that a portability claim be made. | Já existe vínculo para essa chave com o mesmo dono, mas ela encontra-se associada a outro participante. Indica-se que seja feita uma reivindicação de portabilidade. |
| PXP000047 | RateLimited | 429 | Connection was refused by BACEN. Max requests per minute has been exceeded. | A requisição foi recusada pelo BACEN. A quantidade máxima de requisições por minuto foi excedida. |

---

# Listar chaves Pix de uma conta

URL: /documentation/pix/listar_chaves_pix

## Request

ENDPOINT /baas/pix/keys
MÉTODO GET

## Query Params

| Campo            | Tipo   | Descrição                                                                                                               | Caracteres |
|------------------|--------|-------------------------------------------------------------------------------------------------------------------------|------------|
| `account_key`*   | string | Chave uuid da conta.                                                                                                    | Chave uuid |
| `pix_key_status` | enum   | **[Enumerador Pix Key Status](#Pix-Key-Status)** Enumerador indicando o status das chaves pix que devem ser retornadas. | -          |

### Enumerador _Pix Key Status_

| Enumerador                             | Descrição                                                       |
|----------------------------------------|-----------------------------------------------------------------|
| **pending_confirmation**               | Pendente de confirmação                                         |
| **active**                             | Ativa                                                           |
| **inactivated**                        | Inativa                                                         |
| **pending_claim_request_confirmation** | Pendente de confirmação do pedido de portabilidade de chave Pix |

## Response

STATUS 200

Response Body

```json
[
  {
    "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
    "pix_key": "63927180432",
    "pix_key_status": "active",
    "pix_key_type": "cpf",
    "updated_at": "2022-09-02T20:00:36",
    "created_at": "2022-09-02T20:00:36"
  },
  {
    "account_key": "40cea00e-9d99-46f9-b55f-dbafa84553a9",
    "pix_key": "+5562985013819",
    "pix_key_status": "pending_confirmation",
    "pix_key_type": "phone_number",
    "updated_at": "2022-09-02T20:00:36",
    "created_at": "2022-09-02T20:00:36"
  },
  {
    "account_key": "0ebc3bfb-be25-4093-adf2-f0cdee6f5e69",
    "pix_key": "address@email.com",
    "pix_key_status": "pending_confirmation",
    "pix_key_type": "email",
    "updated_at": "2022-09-02T20:00:36",
    "created_at": "2022-09-02T20:00:36"
  }
]
```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

---

# MED 2.0 — Consultar Recuperações de Valores

URL: /documentation/pix/med/consultar_recuperacao_de_valores

Além dos webhooks de acompanhamento, você pode consultar as recuperações de valores abertas contra a sua conta: a listagem devolve todas as recuperações recebidas, e a consulta individual devolve o detalhe de uma recuperação a partir do seu `funds_recovery_id` — o mesmo identificador recebido no webhook.

## Listar recuperações de valores

ENDPOINT /pix/funds_recovery/incoming
MÉTODO GET

### Query params

| Campo                   | Tipo    | Descrição                                                                                              |
| ----------------------- | ------- | -------------------------------------------------------------------------------------------------------- |
| `funds_recovery_status` | string  | Filtra pelo status da recuperação: `awaiting_analysis`, `pending_approval`, `completed` ou `cancelled`. |
| `initial_date`          | string  | Filtra recuperações criadas a partir desta data. Formato `YYYY-MM-DD`.                                  |
| `final_date`            | string  | Filtra recuperações criadas até esta data. Formato `YYYY-MM-DD`.                                        |
| `page_number`           | integer | Página da listagem. Padrão: `1`.                                                                        |
| `page_size`             | integer | Itens por página. Padrão: `10`, máximo: `30`.                                                           |

### Response

STATUS 200

Response Body

```json
{
  "data": [
    {
      "funds_recovery_key": "9eb5f452-81fd-4f67-9f2a-49e14e53ef64",
      "funds_recovery_id": "b8d19bd4-51dc-4784-a2ad-52807c6dfc80",
      "infraction_report_id": "3541127e-cbc9-44f6-bb0e-3e346ddaefb4",
      "pix_transfer_key": "957ef961-1824-47e6-90fd-f8b4775a1e1c",
      "target_account_key": "6711e3cf-fdf4-41b4-88e8-0a31cb83b9f4",
      "target_person_key": "4f6ea994-e53a-4ef8-b2b0-89d14c4667bc",
      "end_to_end_id": "E12345678202607161648s188f18bJty",
      "funds_recovery_status": "awaiting_analysis",
      "situation_type": "scam",
      "report_details": "Transação acusada como fraudulenta pelo originador.",
      "infraction_amount": 150.50,
      "credited_participant": "32402502",
      "debited_participant": "12345678",
      "analysis_result": null,
      "analysis_details": null,
      "blocked_balance_status": "completelly_blocked",
      "tracking_graph": null,
      "funds_recovery_status_events": [
        {
          "old_status": null,
          "new_status": "awaiting_analysis",
          "created_at": "2026-07-16T16:48:43Z"
        }
      ],
      "updated_at": "2026-07-16T16:48:43Z",
      "created_at": "2026-07-16T16:48:43Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "rows_per_page": 10
  }
}
```

| Campo    | Tipo  | Descrição                                                                                                                            |
| -------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `data` * | array | Lista de recuperações de valores abertas contra a sua conta, da mais recente para a mais antiga. **[Objeto funds_recovery](./recebimento_recuperacao_de_valores.md#objeto-funds_recovery)** |
| `pagination` * | object | Dados de paginação: `current_page`, `next_page` (nulo na última página) e `rows_per_page`. |

## Consultar uma recuperação de valores

ENDPOINT /pix/funds_recovery/incoming/ FUNDS_RECOVERY_ID
MÉTODO GET

### Path params

| Campo                 | Tipo   | Descrição                                                                     | Caracteres |
| --------------------- | ------ | ------------------------------------------------------------------------------ | ---------- |
| `FUNDS_RECOVERY_ID` * | string | Identificador da recuperação de valores no Bacen (`funds_recovery_id`).       | 32         |

### Response

STATUS 200

A resposta é o **[objeto funds_recovery](./recebimento_recuperacao_de_valores.md#objeto-funds_recovery)**, incluindo o histórico de eventos de status (`funds_recovery_status_events`) e, quando a recuperação já foi respondida, o campo `client_awnser`.

---

# Mecanismo Especial de Devolução do PIX (MED)

URL: /documentation/pix/med/introducao

O Banco central desenvolveu um sistema de integração entre bancos com o objetivo de diminuir as ocorrências e a gravidade das fraudes cometidas envolvendo transações monetárias no escopo do PIX. O sistema consiste em duas entidades: o relato de infração e o pedido de devolução, sendo que para clientes internos da QI Tech, por questões de segurança, o gerenciamento das mesmas é realizado internamente, evitando possíveis fraudes.

O fluxo normalmente seguido é, ao identificar uma transação fraudulenta, o participante originador deve abrir um relato de infração, o qual o participante de destino deve apurar e, num período de 7 dias, responder acatando ou não o mesmo. Caso seja acatado, o participante originador novamente pode abrir um pedido de devolução relativo à infração, o qual deve ser acatado pelo participante recebedor.

---

# Recebimento de Pedidos de Devolução

URL: /documentation/pix/med/recebimento_pedidos_de_devolucao

Ao contrário de relatos de infração, os pedidos de devolução, desde que de acordo com algumas diretrizes, devem, sempre que possível, serem fechados com aceite, a não ser que a conta esteja fechada ou sem saldo. Dito isso, o cliente apenas receberá os webhooks de atualização de status do pedido de devolução, não sendo algo contestável, visto que as razões para se abrir um pedido de devolução pelo MED são ou devido a um relato de infração já aceito, ou outro participante abrindo vido a uma falha operacional.

## Webhook de um incoming refund request

Um incoming refund request é uma devolução aberta por outro banco, onde o dono da conta é o alvo da transação contestada.

## Webhook request body

Webhook: incoming refund request

```json
{
  "event_datetime": "2024-07-16T16:48:43Z",
  "key": "0dedf537-a75e-4945-be1d-5d278c623022",
  "data": {
    "refund_request_key": "9eb5f452-81fd-4f67-9f2a-49e14e53ef64",
    "infraction_report_key": "3541127e-cbc9-44f6-bb0e-3e346ddaefb4",
    "target_account_key": "6711e3cf-fdf4-41b4-88e8-0a31cb83b9f4",
    "refund_request_type": "fraud",
    "blocked_balance_status": "completelly_blocked",
    "pix_transfer_key": "957ef961-1824-47e6-90fd-f8b4775a1e1c",
    "end_to_end_id": "E12345678202404302308s188f18bJty",
    "requesting_participant": "18236120",
    "contested_participant": "32402502",
    "refund_request_details": null,
    "refund_payment_event": null,
    "requested_amount": 40,
    "refunded_amount": 0,
    "refund_request_status": "open",
    "analysis_result": null,
    "analysis_details": null,
    "reject_reason": null,
    "updated_at": "2024-07-16T19:48:43Z",
    "created_at": "2024-07-16T19:48:43Z"
  },
  "status": "open",
  "webhook_type": "incoming.internal_refund_request"
}

```

| Campo              | Tipo   | Descrição                                        | Caracteres                                                                    |
| ------------------ | ------ | ------------------------------------------------ | ----------------------------------------------------------------------------- |
| `event_datetime` * | string | Data e hora de criação da transação.             | 20                                                                            |
| `key` *            | string | Chave única de identificação do envio do evento. | 32                                                                            |
| `data` *           | string | Objeto incoming refund request data.             | **[Objeto incoming_refund_request](#objeto-incoming_refund_request)**         |
| `status` *         | string | Status da devolução.                             | **[Enumeradores refund_request_status](#enumeradores-refund_request_status)** |

### Enumeradores refund_request_status
| Enumerador  | Descrição                               |
| ----------- | --------------------------------------- |
| `open`      | Pedido recebido, e pendente de análise. |
| `closed`    | Análise concluída e pedido fechado.     |
| `cancelled` | Pedido cancelado pelo originados.       |

### Objeto incoming_refund_request
| Campo                      | Tipo   | Descrição                                                | Caracteres                                                                                      |
| -------------------------- | ------ | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `refund_request_key` *     | string | UUID4 identificador da devolução no Bacen.               | 32                                                                                              |
| `infraction_report_key`    | string | UUID4 identificador da infração relacionada no Bacen.    | 32                                                                                              |
| `target_account_key` *     | string | Account key da conta de destino da transação original.   | 32                                                                                              |
| `refund_request_type` *    | string | Tipo do pedido de devolução.                             | **[Enumeradores refund_request_type](#enumeradores-refund_request_type)**                       |
| `pix_transfer_key` *       | string | Pix transfer key da transação original.                  | 32                                                                                              |
| `end_to_end_id` *          | string | end_to_end_id da transação original.                     | 32                                                                                              |
| `requesting_participant` * | string | Participante que originou a transação.                   | 8                                                                                               |
| `contested_participant` *  | string | Participante que recebeu a transação.                    | 8                                                                                               |
| `refund_request_details`   | string | Detalhes da devolução, enviados pelo outro participante. | 2000                                                                                            |
| `refund_payment_event`     | string | Evento de realização da devolução.                       | **[Objeto refund_payment_event](#objeto-refund_payment_event)**                                 |
| `requested_amount` *       | float  | Valor requisitado na devolução.                          | 2000                                                                                            |
| `refunded_amount` *        | float  | Valor total devolvido.                                   | 2000                                                                                            |
| `refund_request_status` *  | string | Status da devolução.                                     | **[Enumeradores refund_request_status](#enumeradores-refund_request_status)**                   |
| `analysis_result`          | string | Resultado da análise. Decidido pela QI Tech.             | **[Enumeradores refund_request_analysis_result](#enumeradores-refund_request_analysis_result)** |
| `analysis_details`         | string | Justificativa do resultado da análise.                   | 200                                                                                             |
| `reject_reason`            | string | Motivo de rejeição do pedido.                            | **[Enumeradores refund_request_reject_reason](#enumeradores-refund_request_reject_reason)**     |
| `blocked_balance_status` * | string | Status do bloqueio de saldo da conta de destino.         | **[Enumeradores blocked_balance_status](#enumeradores-blocked_balance_status)**                 |
| `created_at` *             | string | Data e hora de alteração da transação.                   | 20                                                                                              |
| `updated_at` *             | string | Data e hora de criação da transação.                     | 20                                                                                              |

### Objeto refund_payment_event
| Campo                  | Tipo   | Descrição                                   | Caracteres |
| ---------------------- | ------ | ------------------------------------------- | ---------- |
| `refund_end_to_end_id` | string | end_to_end_id da transação de devolução.    | 32         |
| `refund_transfer_key`  | string | Pix transfer key da transação de devolução. | 32         |
| `refund_amount`        | string | Valor da transação de devolução.            |            |
| `created_at`           | string | Data e hora de criação da transação.        | 20         |

### Enumeradores refund_request_analysis_result
| Enumerador           | Descrição                                                                                                      |
| -------------------- | -------------------------------------------------------------------------------------------------------------- |
| `totally_accepted`   | Devolução realizada de todos os valores requisitados.                                                          |
| `partially_accepted` | Devolução parcial por falta de saldo. Monitorando conta para realizar posteriores devoluções.                  |
| `rejected`           | Devolução rejeitada e nenhum recurso foi devolvido. Se motivo for por falta de saldo, a conta será monitorada. |

### Enumeradores refund_request_type
| Enumerador         | Descrição                                                                                        |
| ------------------ | ------------------------------------------------------------------------------------------------ |
| `fraud`            | Aberta posterior ao aceite de um relato de infração.                                             |
| `operational_flaw` | Aberta sem um relato de infração, utilizada para corrigir falhas operacionais dos participantes. |
| `refund_cancelled` | Correção de uma devolução realizada erroneamente.                                                |

### Enumeradores blocked_balance_status
| Enumerador            | Descrição                                                                         |
| --------------------- | --------------------------------------------------------------------------------- |
| `no_balance`          | Conta do cliente sem saldo. Monitorando saldo pendente.                           |
| `completelly_blocked` | Recursos equivalentes à transação completamente bloqueados.                       |
| `partially_blocked`   | Recursos equivalentes à transação parcialmente bloqueados. Monitorando saldo.     |
| `settled`             | Infração aceita, e pagamento do pedido de devolução realizado.                    |
| `partially_settled`   | Infração aceita, e pagamento do pedido de devolução parcialmente realizado.       |
| `released`            | Recursos liberados, seja por cancelamento da infração ou fechamento em desacordo. |

### Enumeradores refund_request_reject_reason
| Enumerador        | Descrição                                                           |
| ----------------- | ------------------------------------------------------------------- |
| `no_balance`      | Conta do cliente sem saldo. Monitorando saldo pendente.             |
| `account_closure` | Relacionamento com cliente encerrado. Impossível realizar devolução |
| `other`           | Outro motivo, não aplicável nos listados acima.                     |

:::info
O monitoramento de saldo de uma conta com devolução parcial tem um limite de 90 dias após a transação original ocorrer.
:::

## Webhook de um outgoing refund request

### Um outgoing refund request é pedido de devolução aberto pela QI, tendo como alvo outro participante.

## Webhook request body

Webhook: outgoing refund request

```json
{
  "event_datetime": "2024-07-22T10:31:09Z",
  "key": "15d91f4b-a55c-41a6-9c46-2704253a1cf7",
  "data": {
    "refund_request_key": "5f98671e-9ec0-4ed7-95a9-061861243efc",
    "pix_transfer_key": "d04e0858-ea91-4dab-8089-a27d6cc68235",
    "source_account_key": "134ad635-ce80-4c8c-bca0-9dd3e8251317",
    "end_to_end_id": "E32402502202404302308s188f18bJty",
    "requested_amount": 78.5,
    "refund_request_status": "open",
    "infraction_report_key": "3b727ade-a736-473e-91a6-07b841253f55",
    "refund_request_type": "fraud",
    "refund_request_details": "Infraction aceita, favor realizar devolução de recursos.",
    "requesting_participant": "32402502",
    "contested_participant": "12345678",
    "analysis_result": null,
    "analysis_details": null,
    "reject_reason": null,
    "refund_payment_event": null,
    "updated_at": "2024-07-16T19:48:43Z",
    "created_at": "2024-07-16T19:48:43Z",
  },
  "status": "open",
  "webhook_type": "outgoing.internal_refund_request"
}
```

| Campo              | Tipo   | Descrição                                        | Caracteres                                                                    |
| ------------------ | ------ | ------------------------------------------------ | ----------------------------------------------------------------------------- |
| `event_datetime` * | string | Data e hora de criação da transação.             | 20                                                                            |
| `key` *            | enum   | Chave única de identificação do envio do evento. | 32                                                                            |
| `data` *           | string | Objeto outgoing infraction report data.          | **[Objeto outgoing_refund_request](#objeto-outgoing_refund_request)**         |
| `status` *         | string | Status da devolução.                             | **[Enumeradores refund_request_status](#enumeradores-refund_request_status)** |

### Objeto outgoing_refund_request
| Campo                      | Tipo   | Descrição                                                | Caracteres                                                                                      |
| -------------------------- | ------ | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `refund_request_key` *     | string | UUID4 identificador da devolução no Bacen.               | 32                                                                                              |
| `infraction_report_key`    | string | UUID4 identificador da infração relacionada no Bacen.    | 32                                                                                              |
| `source_account_key` *     | string | Account key da conta de origem da transação.             | 32                                                                                              |
| `refund_request_type` *    | string | Tipo do pedido de devolução.                             | **[Enumeradores refund_request_type](#enumeradores-refund_request_type)**                       |
| `pix_transfer_key` *       | string | Pix transfer key da transação original.                  | 32                                                                                              |
| `end_to_end_id` *          | string | end_to_end_id da transação original.                     | 32                                                                                              |
| `requesting_participant` * | string | Participante que originou a transação.                   | 8                                                                                               |
| `contested_participant` *  | string | Participante que recebeu a transação.                    | 8                                                                                               |
| `refund_request_details`   | string | Detalhes da devolução, enviados pelo outro participante. | 2000                                                                                            |
| `refund_payment_event`     | string | Evento de realização da devolução.                       | **[Objeto refund_payment_event](#objeto-refund_payment_event)**                                 |
| `requested_amount` *       | float  | Valor requisitado na devolução.                          | 2000                                                                                            |
| `refund_request_status` *  | string | Status da devolução.                                     | **[Enumeradores refund_request_status](#enumeradores-refund_request_status)**                   |
| `analysis_result`          | string | Resultado da análise. Decidido pela QI Tech.             | **[Enumeradores refund_request_analysis_result](#enumeradores-refund_request_analysis_result)** |
| `analysis_details`         | string | Justificativa do resultado da análise.                   | 200                                                                                             |
| `reject_reason`            | string | Motivo de rejeição do pedido.                            | **[Enumeradores refund_request_reject_reason](#enumeradores-refund_request_reject_reason)**     |
| `created_at` *             | string | Data e hora de alteração da transação.                   | 20                                                                                              |
| `updated_at` *             | string | Data e hora de criação da transação.                     | 20                                                                                              |

---

# MED 2.0 — Recebimento de Recuperação de Valores

URL: /documentation/pix/med/recebimento_recuperacao_de_valores

O MED 2.0 introduz a **recuperação de valores** (funds recovery), que unifica em um único fluxo o relato de infração e o pedido de devolução de uma transação PIX contestada. Ao receber uma recuperação de valores contra uma conta, a QI Tech automaticamente bloqueia de forma cautelar o recurso equivalente à transação contestada e envia uma notificação via webhook, dando a você a oportunidade de justificar a legitimidade da transação antes do fechamento.

O ciclo de vida de uma recuperação de valores recebida é:

1. **`awaiting_analysis`** — recuperação recebida e saldo bloqueado; aguardando a sua resposta, que deve ser enviada no prazo máximo de **5 dias**.
2. **`pending_approval`** — resposta enviada (justificativa + arquivo de evidências); em análise pela QI Tech.
3. **`completed`** — fechada pela QI Tech, acatando (`agreed`) ou recusando (`disagreed`) a recuperação.
4. **`cancelled`** — cancelada pelo participante originador.

Toda a comunicação de acompanhamento é realizada via webhooks.

## Webhook de uma incoming funds recovery

Uma incoming funds recovery é uma recuperação de valores aberta por outro participante, onde a sua conta é o alvo da transação contestada.

:::info Observação
Os webhooks de recuperação de valores são enviados com `webhook_type` **`incoming.internal_infraction_report`**. Para diferenciá-los dos relatos de infração, verifique a presença do campo `funds_recovery_key` no objeto `data`.
:::

Webhook: incoming funds recovery

```json
{
  "event_datetime": "2026-07-16T16:48:43Z",
  "key": "0dedf537-a75e-4945-be1d-5d278c623022",
  "data": {
    "funds_recovery_key": "9eb5f452-81fd-4f67-9f2a-49e14e53ef64",
    "funds_recovery_id": "b8d19bd4-51dc-4784-a2ad-52807c6dfc80",
    "infraction_report_id": "3541127e-cbc9-44f6-bb0e-3e346ddaefb4",
    "pix_transfer_key": "957ef961-1824-47e6-90fd-f8b4775a1e1c",
    "target_account_key": "6711e3cf-fdf4-41b4-88e8-0a31cb83b9f4",
    "target_person_key": "4f6ea994-e53a-4ef8-b2b0-89d14c4667bc",
    "end_to_end_id": "E12345678202607161648s188f18bJty",
    "funds_recovery_status": "awaiting_analysis",
    "situation_type": "scam",
    "report_details": "Transação acusada como fraudulenta pelo originador.",
    "infraction_amount": 150.50,
    "contact_email": "contato@participante.com.br",
    "contact_phone_number": "+5511999999999",
    "credited_participant": "32402502",
    "debited_participant": "12345678",
    "client_details": null,
    "analysis_result": null,
    "analysis_details": null,
    "blocked_balance_status": "completelly_blocked",
    "tracking_graph": null,
    "updated_at": "2026-07-16T16:48:43Z",
    "created_at": "2026-07-16T16:48:43Z"
  },
  "status": "awaiting_analysis",
  "webhook_type": "incoming.internal_infraction_report"
}
```

### Objeto funds_recovery

| Campo                     | Tipo   | Descrição                                                                 | Caracteres                                                                                  |
| ------------------------- | ------ | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `funds_recovery_key` *    | string | UUID4 identificador da recuperação de valores na QI Tech.                 | 32                                                                                          |
| `funds_recovery_id` *     | string | Identificador da recuperação de valores no Bacen. Usado nas consultas e na resposta. | 32                                                                                          |
| `infraction_report_id` *  | string | Identificador da infração que originou a recuperação no Bacen.            | 32                                                                                          |
| `pix_transfer_key` *      | string | Pix transfer key da transação original.                                   | 32                                                                                          |
| `target_account_key` *    | string | Account key da conta de destino da transação original.                    | 32                                                                                          |
| `target_person_key` *     | string | Person key do alvo da recuperação.                                        | 32                                                                                          |
| `end_to_end_id` *         | string | end_to_end_id da transação original.                                      | 32                                                                                          |
| `funds_recovery_status` * | string | Status da recuperação de valores.                                         | **[Enumeradores funds_recovery_status](#enumeradores-funds_recovery_status)**               |
| `situation_type` *        | string | Situação apontada pelo originador.                                        | **[Enumeradores situation_type](#enumeradores-situation_type)**                             |
| `report_details`          | string | Detalhes enviados pelo participante originador.                           | 2000                                                                                        |
| `infraction_amount`       | number | Valor contestado. Quando ausente, considera-se o valor total da transação. | -                                                                                           |
| `contact_email`           | string | E-mail de contato do participante originador.                             | 255                                                                                         |
| `contact_phone_number`    | string | Telefone de contato do participante originador.                           | 20                                                                                          |
| `credited_participant` *  | string | Participante que recebeu a transação.                                     | 8                                                                                           |
| `debited_participant` *   | string | Participante que originou a transação.                                    | 8                                                                                           |
| `client_awnser`           | string | Justificativa enviada na resposta. Presente após responder.             | 2000                                                                                        |
| `analysis_result`         | string | Resultado da análise. Decidido pela QI Tech.                              | **[Enumeradores analysis_result](#enumeradores-analysis_result)**                           |
| `analysis_details`        | string | Justificativa do resultado da análise.                                    | 2000                                                                                        |
| `blocked_balance_status` * | string | Status do bloqueio de saldo da conta de destino.                          | **[Enumeradores blocked_balance_status](#enumeradores-blocked_balance_status)**             |
| `tracking_graph`          | object | Grafo de rastreamento das movimentações dos recursos contestados, quando disponível. | -                                                                                           |
| `created_at` *            | string | Data e hora de criação.                                                   | 20                                                                                          |
| `updated_at` *            | string | Data e hora de alteração.                                                 | 20                                                                                          |

### Enumeradores funds_recovery_status

| Enumerador          | Descrição                                                                  |
| ------------------- | --------------------------------------------------------------------------- |
| `awaiting_analysis` | Recuperação recebida e saldo bloqueado, aguardando a sua resposta.  |
| `pending_approval`  | Justificativa enviada, aguardando análise interna da QI Tech.              |
| `completed`         | Fechada pela QI Tech após a análise.                                       |
| `cancelled`         | Cancelada pelo participante originador.                                    |

### Enumeradores situation_type

| Enumerador          | Descrição                                               |
| ------------------- | ------------------------------------------------------- |
| `scam`              | Causa de golpe ou estelionato.                          |
| `account_takeover`  | Causa de transação não autorizada pela conta de origem. |
| `coercion`          | Causa de crime de coerção.                              |
| `fraudulent_access` | Causa de acesso fraudulento à conta de origem.          |
| `other`             | Quaisquer causas não aplicáveis às listadas acima.      |

### Enumeradores analysis_result

| Enumerador  | Descrição                                                       |
| ----------- | ---------------------------------------------------------------- |
| `agreed`    | A QI Tech acata a recuperação de valores e os recursos bloqueados são devolvidos. |
| `disagreed` | A QI Tech recusa a recuperação de valores e os recursos bloqueados são liberados. |

### Enumeradores blocked_balance_status

| Enumerador            | Descrição                                                                      |
| --------------------- | ------------------------------------------------------------------------------- |
| `completelly_blocked` | Recursos equivalentes ao valor contestado completamente bloqueados.            |
| `partially_blocked`   | Recursos equivalentes ao valor contestado parcialmente bloqueados. Monitorando saldo. |
| `no_balance`          | Conta sem saldo. Monitorando saldo pendente.                        |
| `account_closed`      | Conta encerrada. Nenhum recurso bloqueado.                          |

---

# Recebimento de Relatos de Infração

URL: /documentation/pix/med/recebimento_relatos_de_infracao

Ao receber um relato de infração, a QI Tech automaticamente bloqueará o recurso da conta equivalente à transação contestada, e enviará notificações de acompanhamento sobre todo o ciclo da infração, inclusive dando chance do cliente justificar a transação, entretanto, vale ressaltar que a decisão final sobre acatar ou não uma infração partirá da QI Tech. Toda a comunicação relativa às infrações são realizadas via webhooks.

## Webhook de uma incoming infraction report

Uma incoming infraction report é uma infração aberta por outro banco, onde o dono da conta é o alvo da transação contestada.

## Webhook request body

Webhook: incoming infraction report

```json
{
  "event_datetime": "2024-07-22T10:31:09Z",
  "key": "15d91f4b-a55c-41a6-9c46-2704253a1cf7",
  "data": {
    "target_person_key": "4f6ea994-e53a-4ef8-b2b0-89d14c4667bc",
    "end_to_end_id": "E12345678202407171627342xlR8KpoD",
    "pix_transfer_key": "6cf241f8-328a-4813-90ab-2aef74d853ac",
    "target_account_key": "9d5b1a98-03ac-4202-91e8-29dbff3d1108",
    "infraction_report_status": "pending_client_awnser",
    "infraction_report_situation": "fraudulent_access",
    "analysis_result": null,
    "analysis_details": null,
    "infraction_report_type": "refund_request",
    "debited_participant": "12345678",
    "credited_participant": "32402502",
    "blocked_balance_status": "completelly_blocked",
    "infraction_report_key": "90b4e1bc-89bc-4df8-98a2-f912447b178f",
    "infraction_report_details": "Transação acusada como fraudulenta pelo originador.",
    "client_details": null,
    "created_at": "2024-07-22T13:31:09Z",
    "updated_at": "2024-07-22T13:31:09Z",
  },
  "status": "pending_client_awnser",
  "webhook_type": "incoming.internal_infraction_report"
}
```

| Campo              | Tipo   | Descrição                                        | Caracteres                                                                                            |
| ------------------ | ------ | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| `event_datetime` * | string | Data e hora de criação da transação.             | 20                                                                                                    |
| `key` *            | enum   | Chave única de identificação do envio do evento. | 32                                                                                                    |
| `data` *           | string | Objeto incoming infraction report data.          | **[Objeto incoming_infraction_report](#objeto-incoming_infraction_report)**                           |
| `status` *         | string | Status da infração.                              | **[Enumeradores incoming_infraction_report_status](#enumeradores-incoming_infraction_report_status)** |

### Objeto incoming_infraction_report
| Campo                           | Tipo   | Descrição                                                    | Caracteres                                                                                            |
| ------------------------------- | ------ | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| `target_person_key` *           | string | Person key do alvo da infração.                              | 32                                                                                                    |
| `end_to_end_id` *               | string | end_to_end_id da transação original.                         | 32                                                                                                    |
| `pix_transfer_key` *            | string | Pix transfer key da transação original.                      | 32                                                                                                    |
| `target_account_key` *          | string | Account key da conta de destino da transação original.       | 32                                                                                                    |
| `infraction_report_status` *    | string | Status da infração.                                          | **[Enumeradores incoming_infraction_report_status](#enumeradores-incoming_infraction_report_status)** |
| `infraction_report_situation` * | string | Situação da infração.                                        | **[Enumeradores infraction_report_situation](#enumeradores-infraction_report_situation)**             |
| `analysis_result`               | string | Resultado da análise. Decidido pela QI Tech.                 | **[Enumeradores infraction_report_analysis_result](#enumeradores-infraction_report_analysis_result)** |
| `analysis_details`              | string | Justificativa do resultado da análise.                       | 200                                                                                                   |
| `infraction_report_type` *      | string | Tipo do relato de infração.                                  | **[Enumeradores infraction_report_type](#enumeradores-infraction_report_type)**                       |
| `debited_participant` *         | string | Participante que originou a transação.                       | 8                                                                                                     |
| `credited_participant` *        | string | Participante que recebeu a transação.                        | 8                                                                                                     |
| `blocked_balance_status` *      | string | Status do bloqueio de saldo da conta de destino.             | **[Enumeradores blocked_balance_status](#enumeradores-blocked_balance_status)**                       |
| `infraction_report_key` *       | string | UUID4 identificador da transação no Bacen.                   | 32                                                                                                    |
| `infraction_report_details`     | string | Detalhes da infração, enviados pelo outro participante.      | 2000                                                                                                  |
| `client_details`                | string | Detalhes fornecidos pelo cliente sobre a transação original. | 2000                                                                                                  |
| `created_at` *                  | string | Data e hora de alteração da transação.                       | 20                                                                                                    |
| `updated_at` *                  | string | Data e hora de criação da transação.                         | 20                                                                                                    |

### Enumeradores incoming_infraction_report_status
| Enumerador              | Descrição                                                      |
| ----------------------- | -------------------------------------------------------------- |
| `pending_client_awnser` | Infração recebida, aguardando justificativa do cliente.        |
| `pending_approval`      | Justificativa enviada, aguardando aprovação interna.           |
| `automatically_closed`  | Fechado automaticamente devido a falta de resposta do cliente. |
| `manually_closed`       | Fechado pela QI Tech após análise da resposta do cliente.      |
| `cancelled`             | Cancelada pelo originador.                                     |

### Enumeradores infraction_report_situation
| Enumerador          | Descrição                                               |
| ------------------- | ------------------------------------------------------- |
| `scam`              | Causa de golpe ou estelionato.                          |
| `account_takeover`  | Causa de transação não autorizada pela conta de origem. |
| `coercion`          | Causa de crime de coerção.                              |
| `fraudulent_access` | Causa de acesso fraudulento à conta de origem.          |
| `other`             | Quaisquer causas não aplicáveis às listadas acima.      |

### Enumeradores infraction_report_analysis_result
| Enumerador  | Descrição                                                                                 |
| ----------- | ----------------------------------------------------------------------------------------- |
| `agreed`    | O Participante Indireto concorda com o Relato de Infração criado pelo outro Participante. |
| `disagreed` | O Participante Indireto discorda com o Relato de Infração criado pelo outro Participante. |

### Enumeradores infraction_report_type
| Enumerador         | Descrição                                                              |
| ------------------ | ---------------------------------------------------------------------- |
| `refund_cancelled` | Relato de infração será gerado pelo motivo de uma devolução cancelada. |
| `refund_request`   | Relato de infração será gerado a fim de se solicitar uma devolução.    |

### Enumeradores blocked_balance_status
| Enumerador            | Descrição                                                                         |
| --------------------- | --------------------------------------------------------------------------------- |
| `no_balance`          | Conta do cliente sem saldo. Monitorando saldo pendente.                           |
| `completelly_blocked` | Recursos equivalentes à transação completamente bloqueados.                       |
| `partially_blocked`   | Recursos equivalentes à transação parcialmente bloqueados. Monitorando saldo.     |
| `settled`             | Infração aceita, e pagamento do pedido de devolução realizado.                    |
| `partially_settled`   | Infração aceita, e pagamento do pedido de devolução parcialmente realizado.       |
| `released`            | Recursos liberados, seja por cancelamento da infração ou fechamento em desacordo. |

:::info
Uma infração será fechada automaticamente aceitando caso o cliente não responda à infração em 5 dias.
:::

## Webhook de uma outgoing infraction report

### Uma outgoing infraction report é uma infração aberta pela QI, tendo como alvo outro participante.

## Webhook request body

Webhook: outgoing infraction report

```json
{
  "event_datetime": "2024-07-22T10:31:09Z",
  "key": "15d91f4b-a55c-41a6-9c46-2704253a1cf7",
  "data": {
    "infraction_report_key": "4f6ea994-e53a-4ef8-b2b0-89d14c4667bc",
    "pix_transfer_key": "6cf241f8-328a-4813-90ab-2aef74d853ac",
    "source_account_key": "9d5b1a98-03ac-4202-91e8-29dbff3d1108",
    "end_to_end_id": "E32402502202407171627342xlR8KpoD",
    "infraction_report_status": "open",
    "infraction_report_situation": "account_takeover",
    "infraction_report_type": "refund_request",
    "infraction_report_details": "Transação fraudulenta.",
    "debited_participant": "32402502",
    "credited_participant": "12345678",
    "analysis_result": null,
    "analysis_details": null,
    "updated_at": "2024-07-22T13:31:09Z",
    "created_at": "2024-07-22T13:31:09Z",
},
  "status": "open",
  "webhook_type": "outgoing.internal_infraction_report"
}
```

| Campo              | Tipo   | Descrição                                        | Caracteres                                                                                   |
| ------------------ | ------ | ------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| `event_datetime` * | string | Data e hora de criação da transação.             | 20                                                                                           |
| `key` *            | enum   | Chave única de identificação do envio do evento. | 32                                                                                           |
| `data` *           | string | Objeto outgoing infraction report data.          | **[Objeto outgoing_infraction_report](#objeto-outgoing_infraction_report)**                  |
| `status` *         | string | Status da infração.                              | **[Enumeradores infraction_report_status](#enumeradores-outgoing_infraction_report_status)** |

### Objeto outgoing_infraction_report
| Campo                           | Tipo   | Descrição                                               | Caracteres                                                                                            |
| ------------------------------- | ------ | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `infraction_report_key` *       | string | UUID4 identificador da transação no Bacen.              | 32                                                                                                    |
| `end_to_end_id` *               | string | end_to_end_id da transação original.                    | 32                                                                                                    |
| `pix_transfer_key` *            | string | Pix transfer key da transação original.                 | 32                                                                                                    |
| `source_account_key` *          | string | Account key da conta de origem da transação original.   | 32                                                                                                    |
| `infraction_report_status` *    | string | Status da infração.                                     | **[Enumeradores outgoing_infraction_report_status](#enumeradores-outgoing_infraction_report_status)** |
| `infraction_report_situation` * | string | Situação da infração.                                   | **[Enumeradores infraction_report_situation](#enumeradores-infraction_report_situation)**             |
| `infraction_report_type` *      | string | Tipo do relato de infração.                             | **[Enumeradores infraction_report_type](#enumeradores-infraction_report_type)**                       |
| `infraction_report_details`     | string | Detalhes da infração, enviados pela QI Tech.            | 2000                                                                                                  |
| `debited_participant` *         | string | Participante que originou a transação.                  | 8                                                                                                     |
| `credited_participant` *        | string | Participante que recebeu a transação.                   | 8                                                                                                     |
| `analysis_result`               | string | Resultado da análise. Decidido pelo outro participante. | **[Enumeradores infraction_report_analysis_result](#enumeradores-infraction_report_analysis_result)** |
| `analysis_details`              | string | Justificativa do resultado da análise.                  | 200                                                                                                   |
| `created_at` *                  | string | Data e hora de alteração da transação.                  | 20                                                                                                    |
| `updated_at` *                  | string | Data e hora de criação da transação.                    | 20                                                                                                    |

### Enumeradores outgoing_infraction_report_status
| Enumerador  | Descrição                                        |
| ----------- | ------------------------------------------------ |
| `open`      | Infração aberta e enviada ao outro participante. |
| `closed`    | Infração respondida pelo outro participante.     |
| `cancelled` | Infração cancelada pela QI Tech.                 |

---

# MED 2.0 — Responder Recuperação de Valores

URL: /documentation/pix/med/responder_recuperacao_de_valores

Enquanto a recuperação de valores está com status `awaiting_analysis`, você pode respondê-la justificando a legitimidade da transação. A resposta é composta por uma **explicação em texto** e um **arquivo .zip de evidências** (nota fiscal, comprovantes, etc.), enviados como **`multipart/form-data`**.

Após a resposta, a recuperação passa para o status **`pending_approval`**, seguindo para a etapa de análise.

:::caution Aviso
O prazo máximo para responder a um MED é de **5 dias**.
:::

## Identificador da recuperação de valores

O identificador utilizado na rota é o campo **`funds_recovery_id`**, recebido no **[webhook de incoming funds recovery](./recebimento_recuperacao_de_valores.md#webhook-de-uma-incoming-funds-recovery)** no momento da abertura da recuperação.

O mesmo identificador também pode ser obtido pela **[listagem de recuperações de valores](./consultar_recuperacao_de_valores.md#listar-recuperações-de-valores)**.

## Request

ENDPOINT /pix/funds_recovery/incoming/ FUNDS_RECOVERY_ID
MÉTODO PATCH

### Path params

| Campo                 | Tipo   | Descrição                                                               | Caracteres |
| --------------------- | ------ | ------------------------------------------------------------------------ | ---------- |
| `FUNDS_RECOVERY_ID` * | string | Identificador da recuperação de valores no Bacen (`funds_recovery_id`). | 32         |

### Form data

| Campo             | Tipo   | Descrição                                                                              | Caracteres |
| ----------------- | ------ | --------------------------------------------------------------------------------------- | ---------- |
| `client_awnser` * | string | Sua interpretação acerca da transação apontada como fraudulenta.                | 2000       |
| `file` *          | file   | Arquivo **.zip** com as evidências que sustentam a justificativa. Tamanho máximo: **50MB**. | -          |

### Response

STATUS 200

Response Body

```json
{
  "funds_recovery_key": "9eb5f452-81fd-4f67-9f2a-49e14e53ef64",
  "funds_recovery_id": "b8d19bd4-51dc-4784-a2ad-52807c6dfc80",
  "infraction_report_id": "3541127e-cbc9-44f6-bb0e-3e346ddaefb4",
  "pix_transfer_key": "957ef961-1824-47e6-90fd-f8b4775a1e1c",
  "target_account_key": "6711e3cf-fdf4-41b4-88e8-0a31cb83b9f4",
  "target_person_key": "4f6ea994-e53a-4ef8-b2b0-89d14c4667bc",
  "end_to_end_id": "E12345678202607161648s188f18bJty",
  "funds_recovery_status": "pending_approval",
  "situation_type": "scam",
  "report_details": "Transação acusada como fraudulenta pelo originador.",
  "infraction_amount": 150.50,
  "credited_participant": "32402502",
  "debited_participant": "12345678",
  "client_awnser": "Transação legítima, conforme demonstrado na nota fiscal XXXXXXXXXX que confirma a venda do produto.",
  "analysis_result": null,
  "analysis_details": null,
  "blocked_balance_status": "completelly_blocked",
  "tracking_graph": null,
  "funds_recovery_status_events": [
    {
      "old_status": null,
      "new_status": "awaiting_analysis",
      "created_at": "2026-07-16T16:48:43Z"
    },
    {
      "old_status": "awaiting_analysis",
      "new_status": "pending_approval",
      "created_at": "2026-07-17T10:12:05Z"
    }
  ],
  "updated_at": "2026-07-17T10:12:05Z",
  "created_at": "2026-07-16T16:48:43Z"
}
```

A resposta é o **[objeto funds_recovery](./recebimento_recuperacao_de_valores.md#objeto-funds_recovery)** atualizado, com `funds_recovery_status` = `pending_approval` e a justificativa em `client_awnser`.

### Erros

| Código      | Status | Descrição                                                                          |
| ----------- | ------ | ----------------------------------------------------------------------------------- |
| `MED000042` | 400    | A recuperação de valores não está com status `awaiting_analysis`.                  |
| `MED000043` | 400    | O arquivo enviado não é um arquivo **.zip**.                                       |
| `MED000044` | 400    | O arquivo enviado excede o tamanho máximo de **50MB**.                             |
| `MED000039` | 404    | Recuperação de valores não encontrada para o `FUNDS_RECOVERY_ID` informado.        |

---

# Responder Relatos de Infração

URL: /documentation/pix/med/resposta_relatos_de_infracao

O Banco central estipula um limite de 7 dias para a análise de relatos de infração, com o objetivo de manter a qualidade do serviço e do mecanismo de devolução. A QI Tech reserva até 5 dias para que o cliente responda à infração recebida justificando a legitmidade ou não da transação, e 2 dias para a análise interna e apuração dos fatos. Vale ressaltar que a palavra final para o aceite ou não de um relato cabe exclusivamente à QI Tech.

:::caution Aviso
Após o decorrer dos 5 dias, a infração será automaticamente fechada aceitando, caso o cliente não responda.
:::

## Request

ENDPOINT /internal/pix/infraction_report/incoming/ INFRACTION_REPORT_KEY
MÉTODO PATCH

Request Body

```json
{
    "client_awnser": "Transação legítma, conforme demonstrado na nota fiscal XXXXXXXXXX que confirma a venda do produto.",
}

```

### Body params

| Campo             | Tipo   | Descrição                                                               | Caracteres |
| ----------------- | ------ | ----------------------------------------------------------------------- | ---------- |
| `client_awnser` * | string | Interpretação do cliente acerca da transação apontada como fraudulenta. | 2000       |

### Response

STATUS 200

Response Body

```json
{
    "target_person_key": "4f6ea994-e53a-4ef8-b2b0-89d14c4667bc",
    "end_to_end_id": "E12345678202407171627342xlR8KpoD",
    "pix_transfer_key": "6cf241f8-328a-4813-90ab-2aef74d853ac",
    "target_account_key": "9d5b1a98-03ac-4202-91e8-29dbff3d1108",
    "infraction_report_status": "pending_approval",
    "infraction_report_situation": "fraudulent_access",
    "analysis_result": null,
    "analysis_details": null,
    "infraction_report_type": "refund_request",
    "debited_participant": "12345678",
    "credited_participant": "32402502",
    "blocked_balance_status": "completelly_blocked",
    "infraction_report_key": "90b4e1bc-89bc-4df8-98a2-f912447b178f",
    "infraction_report_details": "Transação acusada como fraudulenta pelo originador.",
    "client_details": "Transação legítma, conforme demonstrado na nota fiscal XXXXXXXXXX que confirma a venda do produto.",
    "created_at": "2024-07-22T13:31:09Z",
    "updated_at": "2024-07-22T13:31:09Z",
}
```

| Campo                          | Tipo   | Descrição                                                    | Caracteres                                                                                            |
| ------------------------------ | ------ | ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| `target_person_key`*           | string | Person key do alvo da infração.                              | 32                                                                                                    |
| `end_to_end_id`*               | string | end_to_end_id da transação original.                         | 32                                                                                                    |
| `pix_transfer_key`*            | string | Pix transfer key da transação original.                      | 32                                                                                                    |
| `target_account_key`*          | string | Account key da conta de destino da transação original.       | 32                                                                                                    |
| `infraction_report_status`*    | string | Status da infração.                                          | **[Enumeradores incoming_infraction_report_status](#enumeradores-incoming_infraction_report_status)** |
| `infraction_report_situation`* | string | Situação da infração.                                        | **[Enumeradores infraction_report_situation](#enumeradores-infraction_report_situation)**             |
| `analysis_result`              | string | Resultado da análise. Decidido pela QI Tech.                 | **[Enumeradores infraction_report_analysis_result](#enumeradores-infraction_report_analysis_result)** |
| `analysis_details`             | string | Justificativa do resultado da análise.                       | 200                                                                                                   |
| `infraction_report_type`*      | string | Tipo do relato de infração.                                  | **[Enumeradores infraction_report_type](#enumeradores-infraction_report_type)**                       |
| `debited_participant`*         | string | Participante que originou a transação.                       | 8                                                                                                     |
| `credited_participant`*        | string | Participante que recebeu a transação.                        | 8                                                                                                     |
| `blocked_balance_status`*      | string | Status do bloqueio de saldo da conta de destino.             | **[Enumeradores blocked_balance_status](#enumeradores-blocked_balance_status)**                       |
| `infraction_report_key`*       | string | UUID4 identificador da transação no Bacen.                   | 32                                                                                                    |
| `infraction_report_details`    | string | Detalhes da infração, enviados pelo outro participante.      | 2000                                                                                                  |
| `client_details`*              | string | Detalhes fornecidos pelo cliente sobre a transação original. | 2000                                                                                                  |
| `created_at`*                  | string | Data e hora de alteração da transação.                       | 20                                                                                                    |
| `updated_at`*                  | string | Data e hora de criação da transação.                         | 20                                                                                                    |

### Enumeradores incoming_infraction_report_status
| Enumerador              | Descrição                                                      |
| ----------------------- | -------------------------------------------------------------- |
| `pending_client_awnser` | Infração recebida, aguardando justificativa do cliente.        |
| `pending_approval`      | Justificativa enviada, aguardando aprovação interna.           |
| `automatically_closed`  | Fechado automaticamente devido a falta de resposta do cliente. |
| `manually_closed`       | Fechado pela QI Tech após análise da resposta do cliente.      |
| `cancelled`             | Cancelada pelo originador.                                     |

### Enumeradores infraction_report_situation
| Enumerador          | Descrição                                               |
| ------------------- | ------------------------------------------------------- |
| `scam`              | Causa de golpe ou estelionato.                          |
| `account_takeover`  | Causa de transação não autorizada pela conta de origem. |
| `coercion`          | Causa de crime de coerção.                              |
| `fraudulent_access` | Causa de acesso fraudulento à conta de origem.          |
| `other`             | Quaisquer causas não aplicáveis às listadas acima.      |

### Enumeradores infraction_report_analysis_result
| Enumerador  | Descrição                                                                                 |
| ----------- | ----------------------------------------------------------------------------------------- |
| `agreed`    | O Participante Indireto concorda com o Relato de Infração criado pelo outro Participante. |
| `disagreed` | O Participante Indireto discorda com o Relato de Infração criado pelo outro Participante. |

### Enumeradores infraction_report_type
| Enumerador         | Descrição                                                              |
| ------------------ | ---------------------------------------------------------------------- |
| `refund_cancelled` | Relato de infração será gerado pelo motivo de uma devolução cancelada. |
| `refund_request`   | Relato de infração será gerado a fim de se solicitar uma devolução.    |

### Enumeradores blocked_balance_status
| Enumerador            | Descrição                                                                         |
| --------------------- | --------------------------------------------------------------------------------- |
| `no_balance`          | Conta do cliente sem saldo. Monitorando saldo pendente.                           |
| `completelly_blocked` | Recursos equivalentes à transação completamente bloqueados.                       |
| `partially_blocked`   | Recursos equivalentes à transação parcialmente bloqueados. Monitorando saldo.     |
| `settled`             | Infração aceita, e pagamento do pedido de devolução realizado.                    |
| `partially_settled`   | Infração aceita, e pagamento do pedido de devolução parcialmente realizado.       |
| `released`            | Recursos liberados, seja por cancelamento da infração ou fechamento em desacordo. |

---

# Pesquisar por QR Code Pix dinâmico próprio

URL: /documentation/pix/pesquisar_por_qr_code_dinamico

## Request

ENDPOINT /baas/qrcode/dynamic
MÉTODO GET

### Path params

| Campo                      | Tipo    | Descrição                                                        | Caracteres |
|----------------------------|---------|------------------------------------------------------------------|------------|
| `account_key`              | string  | chave de identificação da QIConta vinculada à chave pix (UUIDv4) | 36         |
| `pix_key`                  | string  | Chave PIX vinculado ao QRCode                                    | -          |
| `receiver_conciliation_id` | string  | Identicação de conciliação do recebedor                          | max_length = 35         |
| `page`                     | integer | Número da página pesquisada (default = 0)                        | -          |
| `page_size`                | integer | Quantidade de itens por página (default = 15)                    | -          |
| `first_result`             | boolean | Retornar apenas o primeiro resultado (default = desc)               | -          |
| `order_by`                 | string  | Determina a ordem de retorno dos resultados (default = desc)     | asc, desc  |

:::info
É obrigatório enviar `account_key` ou `pix_key`, sendo apenas um deles obrigatório.
::: 

:::caution Atenção
Para consultar apenas um QR Code específico, devem ser utilizados os parâmetros `receiver_conciliation_id` e `pix_key`.
:::

## Response

STATUS 200

Response Body

```json
{
	"pagination": {
		"current_page": 0,
		"next_page": 1,
		"rows_per_page": 15,
		"total_pages": 1,
		"total_rows": 4
	},
	"data": [
		{
			"additional_data": [],
			"amount": 1.0,
			"discounts": [],
			"qr_code_type": "dynamic_term",
			"end_to_end_id": null,
			"base_64": "MDAwMjAxMjY4OTAwMTRici5nb3YuYmNiLnBpeDI1NjdxcmNvZGUtaC5kZXYucWl0ZWNoLmFwcC9iYWNlbi9jb2J2LzQ1NWQ4ZmY1NGE0ZDQ2Mzg4YmVhN2I4MmFhMDZiNzdmNTIwNDAwMDA1MzAzOTg2NTgwMkJSNTkxOVBydVBydXVDb211bmljYWNvZXM2MDA4i2FvUGF1bG82MTA4MDU0MjUwMjA2MjA3MDUwMyoqKjYzMDQyNkNF",
			"expiration_date": "2023-03-30",
			"expiration_seconds": null,
			"max_payment_days": 180,
			"rebate_amount": 0.0,
			"interest_amount": 0.0,
			"fine_amount": 0.0,
			"paid_amount": null,
			"payer_request": null,
			"pix_message": null,
			"modality_alteration": false,
			"payer_name": "Random",
			"payer_document_number": "00000000000000",
			"payer_person_type": "natural",
			"pix_key": {
				"account_key": "ce0db38f-a2ba-446f-bb1a-51d0bf3f40fc",
				"is_activated": true,
				"pix_key": "63602991000100",
				"created_at": "2023-02-14T23:26:52"
			},
			"qr_code_key": "455d8ff5-4a4d-4638-8bea-7b82aa06b77f",
			"qr_code_status": {
				"enumerator": "active"
			},
			"receiver_conciliation_id": "01234567891293134978",
			"created_at": "2023-03-29T15:26:50"
		}
	]
}

```

STATUS 400

Response Body: Parâmetros Obrigatórios Faltantes

```json
{
    "title": "Bad Request",
    "description": "Must use pix key or account key to search for QR Codes",
    "translation": "Chave Pix ou Chave da Conta devem ser utilizados para realizar buscas por QR Codes",
    "code": "PQR000009"
}
```

STATUS 400

Response Body: Usuário não possui credenciais

```json
{
    "title": "Unauthorized",
    "description": "User is not allowed to do this transaction",
    "translation": "Usuário não tem autorização para fazer essa transação",
    "code": "PQR000004"
}
```

STATUS 400

Response Body: Usuário não é dono da conta

```json
{
    "title": "Unauthorized",
    "description": "Person is not account owner.",
    "translation": "A pessoa não é dona da conta.",
    "code": "PQR000005"
}
```

STATUS 404

Response Body: Chave Pix Não encontrada

```json
{
    "title": "Not Found",
    "description": "No active Pix key found with key \{pix_key\}",
    "translation": "Não foi encontrada pix key ativa com a chave \{pix_key\}",
    "code": "PQR000007"
}
```

### Enumeradores QR Code Status
| Enumerador         | Descrição                                                |
|--------------------|----------------------------------------------------------|
| `active`           | QR Code ativo                                            |
| `finished`         | QR Code pago                                             |
| `written_off`      | QR Code desativado por solicitação do recebedor/parceiro |
| `bank_written_off` | QR Code desativado pela QI                               |

---

# Pesquisar por transferência Pix de saída

URL: /documentation/pix/pesquisar_por_transferencia_pix_de_saida

## Request

ENDPOINT /baas/pix/pix_transfer
MÉTODO GET

### Path params

| Campo                      | Tipo    | Descrição                                                        | Caracteres |
|----------------------------|---------|------------------------------------------------------------------|------------|
| `end_to_end_id`            | string  | chave de identificação única de uma transação ou consulta no Banco Central. Exemplo: E3240250220210615135810450327042| 32         |
| `pix_transfer_key`         | string  | chave de identificação da transferência Pix no sistema QI (UUIDv4)  | 36         |

:::info
É obrigatório enviar `end_to_end_id` ou `pix_transfer_key`, sendo apenas um deles obrigatório.
::: 

:::caution Atenção
Será apenas permitida a visualização de uma transferência caso o requisitante tenha permissões na conta de saída da transação. Caso o contrário um erro será retornado.
:::

## Response

STATUS 200

Response Body

```json
{
	"billing_account_key": null,
	"created_at": "2021-03-12T20:39:06",
	"description": null,
	"end_to_end_id": "E3240250220210615135810450327042",
	"external_analysis": null,
	"fee_amount": 2.0,
	"initiator_document_number": null,
	"pix_message": null,
	"pix_transfer_key": "2c7e71f6-d2a3-4f2d-8243-9b28523e9c95",
	"pix_transfer_status": "rejected",
	"pix_transfer_type": "key",
	"receiver_conciliation_id": null,
	"sent_at": null,
	"source_account_key": "23a4a2c8-9d82-4ebe-a90d-44fe8d839ec0",
	"target_account": {
		"account_branch": "0001",
		"account_digit": "6",
		"account_number": "99031",
		"account_type": null,
		"financial_institution_compe_number": 341,
		"financial_institution_name": "ITAÚ UNIBANCO S.A.",
		"is_internal": false,
		"ispb_number": "60701190",
		"owner_document_number": "40569499801",
		"owner_name": "Nuno Reis",
		"target_pix_key": "rafaell@yopmail.com"
	},
	"transaction_key": "2ddc2843-5930-460f-9a3c-436f40ecc5f1",
	"transfer_amount": 10.0,
	"transfer_purpose": "transfer",
	"update_at": null
}

```

STATUS 400

Response Body: Parâmetros obrigatórios faltantes

```json
{
    "title": "Pix Transfer Key or End To End Not Provided",
    "description": "No pix transfer key or end to end id provided.",
    "translation": "Não foram fornecidos uma pix transfer key ou end to end id.",
    "code": "PXT000075"
}
```

STATUS 404

Response Body: Transferência Pix não encontrada por end_to_end_id

```json
{
    "title": "Outgoing PIX Transfer Not Found",
    "description": "Pix transfer end to end id \{end_to_end_id\} was not found",
    "translation": "Transferência PIX de saída com identificador único \{end_to_end_id\} não foi encontrada",
    "code": "PXT000073"
}
```

STATUS 404

Response Body: Transferência Pix não encontrada por pix_transfer_key

```json
{
    "title": "Outgoing PIX Transfer Not Found",
    "description": "Pix transfer key \{pix_transfer_key\} was not found",
    "translation": "Transferência PIX de saída com chave \{pix_transfer_key\} não foi encontrada.",
    "code": "PXT000023"
}
```

STATUS 403

Response Body: Usuário não possui credenciais

```json
{
    "title": "User is not allowed to do this transaction",
    "description": "User is not allowed to do this transaction",
    "translation": "Usuário não tem autorização para fazer essa transação",
    "code": "PIT000001"
}
```

### Enumeradores PixTransfer Status
| Enumerador         | Descrição                                                |
|--------------------|----------------------------------------------------------|
| `sent`           | Tranferência enviada                                            |
| `rejected`         | Tranferência rejeitada                             |
| `pending_confirmation`      | Tranferência pendente de confirmação|
| `pending_approval` | Tranferência pendente de aprovação                              |
| `error` | Tranferência com erro                              |

---

# Conclusão da portabilidade

URL: /documentation/pix/portabilidade/conclusao_de_portabilidade

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita.
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

Após a confirmação ou recusa da portabilidade, a QI dará continuidade ao processo de portabilidade da chave. O usuário deve receber autualizações da portabilidade no banco de destino em alguns minutos.

Assim que o pedido de portabilidade for concluído ou cancelado, a QI informará o solicitante sobre a conclusão da portabilidade através do seguinte webhook:

WEBHOOK_TYPE claim_request

Webhook Body

```json
{
  "account_key": "169010e3-6c1e-4521-9253-11cbbf36c59j",
  "pix_key": "12345678000190",
  "pix_key_type": "cnpj",
  "claim_request_type": "portability",
  "role": "claimant",
  "claim_request_key": "7f8b67d2-d8e4-4759-85eb-e4d0ac24708c",
  "claim_request_status": "concluded",
  "claimant_person_type": "natural",
  "claimant_document_number": "12345678000190",
  "claimant_account_branch": "0001",
  "claimant_account_number": "5050396",
  "claimant_account_digit": "1",
  "webhook_type": "claim_request"
}
```

#### Enumeradores claim_request_status

| Enumerador           | Tradução                |
|----------------------|-------------------------|
| **concluded**          | concluído               |
| **cancelled**            | cancelado               |
| **failed**               | falha                   |
| **pending_confirmation** | pendente de confirmação |

---

# Consulta de portabilidade por conta

URL: /documentation/pix/portabilidade/consulta_de_portabilidade_por_conta

## Request

ENDPOINT /baas/pix/key_claim_request/account/ ACCOUNT_KEY
MÉTODO GET

Request Body

### Path Params

| Campo         | Tipo   | Descrição                          | Caracteres |
|---------------|--------|------------------------------------|------------|
| `account_key` | string | chave de identificação da QIConta. | 36         |

### Query Params

| Campo          | Tipo    | Descrição                                                                                            | Caracteres                                     |
|----------------|---------|------------------------------------------------------------------------------------------------------|------------------------------------------------|
| `page_number`  | integer | Página atual que está sendo consultada.                                                              | -                                              |
| `page_size`    | integer | Quantidade de resultados por página.                                                                 | -                                              |
| `claim_status` | string  | Status da portabilidade. Caso não seja enviado, todas as portabiliades não concluidas serão listadas | **[Enumeradores](#enumeradores-pix_key_type)** |

#### Enumeradores pix_key_type

| Enumerador                     | Tradução                      |
|--------------------------------|-------------------------------|
| **pending**                    | pendente                      |
| **opened**                     | aberto                        |
| **pending_confirmation**       | confirmação pendente          |
| **confirmed**                  | confirmado                    |
| **cancelled**                  | cancelado                     |
| **concluded**                  | concluído                     |
| **failed**                     | falha                         |
| **pending_donator_validation** | validação de doador pendente  |
| **pending_claimer_validation** | validaçao de pedinte pendente |

## Response

STATUS 200

Response Body

```json
{
  "data": [
    {
        "account_key": "be0884bc-44a4-4907-8627-ef976e477aef",
        "cancellation_reason": null,
        "cancelled_by": null,
        "claim_flow_type": "donator",
        "claim_request_key": "be0884bc-44a4-4907-8627-ef976e477aef",
        "claim_status": "pending_confirmation",
        "claim_type": "portability",
        "claimant_account_branch": "9999",
        "claimant_account_number": "0",
        "claimant_document_number": "37059093800",
        "claimant_person_type": "natural",
        "confirmation_reason": null,
        "created_at": "2023-11-06T17:30:11",
        "donator_ispb": 32402502,
        "limit_conclusion_date": null,
        "limit_resolve_date": "2023-11-13T17:29:00",
        "max_conclusion_date": null,
        "max_resolution_date": "2023-11-13T17:29:00",
        "pix_key": "45574823098",
        "pix_key_claim_id": "205c72ab-c03e-43b7-a43d-2409e21fa5be",
        "pix_key_type": "cpf",
        "requester_key": "be0884bc-44a4-4907-8627-ef976e477aef"
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "rows_per_page": 10
  }
} 
```

STATUS 4XX

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`           | Descrição (eng)<br/>`Description`                                                 | Descrição (ptbr)<br/>`translation`                                                  |
|-------------|----------------------|------------------------------|-----------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|
| 400         | PIX000071            | Unknown Claim Request Status | Unknown claim_status \{claim_status\}.                                              | claim_status \{claim_status\} não reconhecido.                                        |
| 403         | PIX000054            | Invalid Permission           | Person \{person_key\} does not have administration roles for account \{account_key\}. | Pessoa \{person_key\} não tem credencial de administrador para a conta \{account_key\}. |

---

# Criando um pedido de portabilidade

URL: /documentation/pix/portabilidade/criando_um_pedido_de_portabilidade

:::caution **Atenção**
É necessário realizar validação de dois fatores caso o tipo da chave que a portabilidade está sendo solicitada seja
número de telefone ou e-mail, o token será enviado para o número ou e-mail solicitado. Caso a validação de dois fatores seja necessária o "claim_request_status" será "pending_claimer_validation".

A orientação para o envio do token está no item 2.5.3.5.2 Validação de dois fatores
:::

:::danger **Atenção!!**
A criação do pedido de portabilidade deve ser feita utilizando uma das chaves Pix mockadas para o ambiente de sandbox.
[Chaves Pix Mockadas](/documentation/pix/chaves_pix_mockadas)
:::

### Request

ENDPOINT /baas/pix/key_claim_request
MÉTODO POST

Request Body

```json
{
  "account_key": "169010e3-6c1e-4521-9253-11cbbf36c59j",
  "pix_key": "12345678000190",
  "pix_key_type": "cnpj"
}
```

#### Body Params

| Campo          | Tipo   | Descrição                               | Caracteres                                     |
|----------------|--------|-----------------------------------------|------------------------------------------------|
| `account_key`  | string | chave de identificação da QIConta.      | 36                                             |
| `pix_key`      | enum   | chave a ser solicitada a portabilidade. | -                                              |
| `pix_key_type` | enum   | tipo da chave pix da portabilidade.     | **[Enumeradores](#enumeradores-pix_key_type)** |

#### Enumeradores pix_key_type

| Enumerador       | Tradução           |
|------------------|--------------------|
| **random_key**   | aleatória          |
| **email**        | e-mail             |
| **phone_number** | número de telefone |
| **cpf**          | cpf                |
| **cnpj**         | cnpj               |

:::info Tipos de Chave Pix
A “pix_key” pode ser um CPF, CNPJ, E-mail, Celular ou uma Chave Aleatória (UUID), seguindo as seguintes formatações:

CPF: Número inteiro com 11 dígitos.

CNPJ: Número inteiro com 14 dígitos.

E-mail: Texto contendo ao menos um “@”.

Celular: Texto contendo os seguintes valores: “+55” + “DDD do celular“ + “Número Inteiro do Celular com no mínimo 8 e no
máximo 9 dígitos”. Ex: “+5511987654321“.

Chave Aleatória: UUID.
:::

### Response

STATUS 200

Response Body

```json
{
  "max_conclusion_date": "2023-05-26T12:13:25",
  "claim_request_status": "pending",
  "claimant": {
    "document_number": "12345678000190",
    "claimant_key": "6aaadfbc-76ba-45d2-bb21-138bcb2baa62",
    "account_opened_at": "2023-01-17T12:28:37",
    "account_branch": "0001",
    "account_type": "escrow",
    "account_number": "7336349",
    "person_type": "legal",
    "account_digit": "0"
  },
  "max_resolution_date": "2023-05-19T12:13:25",
  "claimant_bank_name": "QI SCD S.A.",
  "pix_key": {
    "pix_key_type": "cnpj",
    "pix_key_status": "pending_confirmation",
    "created_at": "2023-05-12T12:13:24",
    "updated_at": "2023-05-12T12:13:24",
    "account_key": "169010e3-6c1e-4521-9253-11cbbf36c59j",
    "pix_key": "12345678000190"
  },
  "donator_ispb": null,
  "external_key": null,
  "claim_request_key": "7f8b67d2-d8e4-4759-85eb-e4d0ac24708c",
  "claim_request_type": "portability",
  "client_role": "claimant",
  "confirmation_reason": null,
  "requester_key": "e151044c-44d0-48b3-9df1-0b9475077fe5",
  "claimant_bank_code": "329",
  "cancelled_by": null,
  "request_failure_reason": null,
  "donator": null,
  "account_key": "169010e3-6c1e-4521-9253-11cbbf36c59j"
}
```

STATUS 4XX

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                            | Descrição (eng)<br/>`Description`                                                                                                | Descrição (ptbr)<br/>`translation`                                                                                                 |
|-------------|----------------------|-----------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------|
| 400         | PIX000022            | Pix key already registered                    | Pix key already registered for the account.                                                                                      | Chave pix já cadastrada para a conta.                                                                                              |
| 400         | PIX000014            | Maximum Number of Pix Keys in Use             | Maximum number of pix keys for account \{account_key\} has reached                                                                 | A conta \{account_key\} já tem o número máximo de chaves pix.                                                                        |
| 400         | PIX000003            | Account is not Opened                         | Account \{account_key\} is not opened                                                                                              | Conta \{account_key\} não está aberta                                                                                                |
| 400         | PIX000053            | Invalid Portability Request                   | Portability within same Financial Institution should follow key alteration flow instead                                          | Não é possível realizar portabilidade dentro da própria instituição financeira. Proceder com o fluxo de alteração                  |
| 403         | PIX000054            | Invalid Permission                            | Person 5dbd5598-6b42-4d80-8e5e-1c616cf8b9ab does not have administration roles for account 169010e3-6c1e-4521-9253-11cbbf36c59j. | Pessoa 5dbd5598-6b42-4d80-8e5e-1c616cf8b9ab não tem credencial de administrador para a conta 169010e3-6c1e-4521-9253-11cbbf36c59j. |
| 404         | PIX000017            | Pix Key is Unregistered                       | Pix key 12345678000190 is not currently used.                                                                                    | A chave pix 12345678000190 não está sendo utilizada.                                                                               |
| 422         | PIX000077            | Error when querying pix key                   | Error when querying pix key 12345678000190                                                                                       | Erro ao consultar chave pix 12345678000190                                                                                         |
| 400         | PIX000028            | Key Type not allowed for portability or claim | Only cpf, cnpj, email and phone_number key_types can be portabilized or claim. Received key_type: random_key                     | Somente os key_types cpf, cnpj, email e phone_number podem ser portabilizados ou reivindicados. key_type recebido: random_key      |
| 400         | PIX000061            | Invalid Document                              | Invalid document sent 12345678000190.                                                                                            | Documento enviado é inválido 12345678000190.                                                                                       |
| 404         | PIX000026            | Account not found                             | Account not found for account_key: 6aaadfbc-76ba-45d2-bb21-138bcb2baa62                                                          | Conta não encontrada para account_key: 6aaadfbc-76ba-45d2-bb21-138bcb2baa62                                                        |
| 404         | PIX000027            | Person not found                              | Person not found for person_key: \{person_key\}                                                                                    | Pessoa não encontrada para person_key: \{person_key\}                                                                                |
| 422         | PIX000069            | Pix Key inquiry timeout                       | Pix key inquiry timeout. Please try again.                                                                                       | Consulta de chave pix excedeu o tempo limite. Por favor tente novamente.                                                           |
| 400         | PIX000072            | Pix Key Claim Non Finished                    | Pix key 12345678000190, already has a claim request non finished.                                                                | Chave pix 12345678000190, já possui um pedido de portabilidade não finalizado.                                                     |

---

# Deletando um pedido de portabilidade

URL: /documentation/pix/portabilidade/deletando_um_pedido_de_portabilidade

Caso o pedido de portabilidade esteja no status "pending_claimer_validation" é possível deletar a portabilidade.

### Request

ENDPOINT /baas/pix/key_claim_request/ CLAIM_REQUEST_KEY
MÉTODO DELETE

Request Body

```json
{}
```

### Response

STATUS 200

Response Body

```json
{
  "max_conclusion_date": "2023-05-26T12:13:25",
  "claim_request_status": "cancelled",
  "claimant": {
    "document_number": "12345678000190",
    "claimant_key": "6aaadfbc-76ba-45d2-bb21-138bcb2baa62",
    "account_opened_at": "2023-01-17T12:28:37",
    "account_branch": "0001",
    "account_type": "escrow",
    "account_number": "7336349",
    "person_type": "legal",
    "account_digit": "0"
  },
  "max_resolution_date": "2023-05-19T12:13:25",
  "claimant_bank_name": "QI SCD S.A.",
  "pix_key": {
    "pix_key_type": "email",
    "pix_key_status": "inactivated",
    "created_at": "2023-05-12T12:13:24",
    "updated_at": "2023-05-12T12:13:24",
    "account_key": "169010e3-6c1e-4521-9253-11cbbf36c59j",
    "pix_key": "example@gmail.com"
  },
  "donator_ispb": null,
  "external_key": null,
  "claim_request_key": "7f8b67d2-d8e4-4759-85eb-e4d0ac24708c",
  "claim_request_type": "portability",
  "client_role": "claimant",
  "confirmation_reason": null,
  "requester_key": "e151044c-44d0-48b3-9df1-0b9475077fe5",
  "claimant_bank_code": "329",
  "cancelled_by": null,
  "request_failure_reason": null,
  "donator": null,
  "account_key": "169010e3-6c1e-4521-9253-11cbbf36c59j"
}
```

STATUS 4XX

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                                        | Descrição (eng)<br/>`Description`                                                               | Descrição (ptbr)<br/>`translation`                                                                           |
|-------------|----------------------|-----------------------------------------------------------|-------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|
| 404         | PIX000031            | Claim Request not found                                   | Claim Request not found for key: 7f8b67d2-d8e4-4759-85eb-e4d0ac24708c.                          | Claim Request não encontrada para a chave: 7f8b67d2-d8e4-4759-85eb-e4d0ac24708c.                             |
| 403         | QIT000005            | Permission Validator Error.                               | Selected agent do not own this item.                                                            | O agente selecionado não é dono do item.                                                                     |
| 400         | PIX000047            | Claim request does not have validation.                   | Claim request does not have two steps validation.                                               | Pedido de reinvindicação não possui validação de duas etapas.                                                |
| 400         | PIX000047            | Claim Request Is Not Pending Validation From The Claimer. | Claim request 7f8b67d2-d8e4-4759-85eb-e4d0ac24708c, is not pending validation from the claimer. | Pedido de portabilidade 7f8b67d2-d8e4-4759-85eb-e4d0ac24708c, não está pendente de validação do solicitante. |

---

# Portabilidade

URL: /documentation/pix/portabilidade/recebendo_pedido_de_portabilidade

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita.
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

## Recebendo pedido de portabilidade

Após a criação do pedido de portabilidade em outro banco, a QI informará o solicitante sobre o pedido de portabilidade
em aberto através do seguinte webhook:

WEBHOOK_TYPE claim_request

Webhook Body

```json
{
  "account_key": "169010e3-6c1e-4521-9253-11cbbf36c59j",
  "pix_key": "12345678000190",
  "pix_key_type": "cnpj",
  "claim_request_type": "portability",
  "role": "donator",
  "claim_request_key": "7f8b67d2-d8e4-4759-85eb-e4d0ac24708c",
  "claim_request_status": "pending_confirmation",
  "claimant_person_type": "natural",
  "claimant_document_number": "12345678000190",
  "claimant_account_branch": "0001",
  "claimant_account_number": "5050396",
  "claimant_account_digit": "1",
  "webhook_type": "claim_request"
}
```

#### Enumeradores claim_request_status

| Enumerador           | Tradução                |
|----------------------|-------------------------|
| concluded            | concluído               |
| cancelled            | cancelado               |
| failed               | falha                   |
| pending_confirmation | pendente de confirmação |

---

# Reenviando a validação de dois fatores

URL: /documentation/pix/portabilidade/reenviando_a_2fa

Caso o pedido de portabilidade esteja no status "pending_claimer_validation" é possível reenviar o código da validação
de dois fatores.

### Request

ENDPOINT /baas/pix/key_claim_request/ CLAIM_REQUEST_KEY /resend_twofa
MÉTODO PATCH

Request Body

```json
{}
```

### Response

STATUS 205

Response Body

```json
{
  "max_conclusion_date": "2023-05-26T12:13:25",
  "claim_request_status": "pending_claimer_validation",
  "claimant": {
    "document_number": "12345678000190",
    "claimant_key": "6aaadfbc-76ba-45d2-bb21-138bcb2baa62",
    "account_opened_at": "2023-01-17T12:28:37",
    "account_branch": "0001",
    "account_type": "escrow",
    "account_number": "7336349",
    "person_type": "legal",
    "account_digit": "0"
  },
  "max_resolution_date": "2023-05-19T12:13:25",
  "claimant_bank_name": "QI SCD S.A.",
  "pix_key": {
    "pix_key_type": "email",
    "pix_key_status": "pending_confirmation",
    "created_at": "2023-05-12T12:13:24",
    "updated_at": "2023-05-12T12:13:24",
    "account_key": "169010e3-6c1e-4521-9253-11cbbf36c59j",
    "pix_key": "example@gmail.com"
  },
  "donator_ispb": null,
  "external_key": null,
  "claim_request_key": "7f8b67d2-d8e4-4759-85eb-e4d0ac24708c",
  "claim_request_type": "portability",
  "client_role": "claimant",
  "confirmation_reason": null,
  "requester_key": "e151044c-44d0-48b3-9df1-0b9475077fe5",
  "claimant_bank_code": "329",
  "cancelled_by": null,
  "request_failure_reason": null,
  "donator": null,
  "account_key": "169010e3-6c1e-4521-9253-11cbbf36c59j"
}

```

STATUS 4XX

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                                        | Descrição (eng)<br/>`Description`                                                               | Descrição (ptbr)<br/>`translation`                                                                           |
|-------------|----------------------|-----------------------------------------------------------|-------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|
| 404         | PIX000031            | Claim Request not found                                   | Claim Request not found for key: 7f8b67d2-d8e4-4759-85eb-e4d0ac24708c.                          | Claim Request não encontrada para a chave: 7f8b67d2-d8e4-4759-85eb-e4d0ac24708c.                             |
| 403         | QIT000005            | Permission Validator Error.                               | Selected agent do not own this item.                                                            | O agente selecionado não é dono do item.                                                                     |
| 400         | PIX000047            | Claim request does not have validation.                   | Claim request does not have two steps validation.                                               | Pedido de reinvindicação não possui validação de duas etapas.                                                |
| 400         | PIX000047            | Claim Request Is Not Pending Validation From The Claimer. | Claim request 7f8b67d2-d8e4-4759-85eb-e4d0ac24708c, is not pending validation from the claimer. | Pedido de portabilidade 7f8b67d2-d8e4-4759-85eb-e4d0ac24708c, não está pendente de validação do solicitante. |

---

# Portabilidade

URL: /documentation/pix/portabilidade/respondendo_pedido_de_portabilidade

### Request

ENDPOINT /baas/pix/key_claim_request/ CLAIM_REQUEST_KEY/
CLAIM_ACTION
MÉTODO PATCH

#### Path params

| Campo       | Tipo   | Descrição                      |
|-------------|--------|--------------------------------|
| `claim_request_key` | string | a chave do pedido de portabilidade. |
| `claim_action` | enum | **[Enumeradores](#enumeradores-claim_action)** |

#### Enumeradores claim_action

| Enumerador | Tradução | Descrição                      |
|---|---|---|
|  confirmed  | confirmado | use essa action para confirmar o pedido de portabilidade
|  cancelled  | cancelado | use essa action para cancelar o pedido de portabilidade
|  pending_donator_validation  | pending_donator_validation | use essa auction para receber a autenticaçã de dois fatores

:::caution **Atenção**
Antes de cancelar uma claim que o "claim_request_type" seja "ownership" é necessário realizar a action "pending_donator_validation" para receber a autenticação de dois fatores e realizar o envio no payload. A única "cancelation_reason" aceita para cancelamento de claims desse tipo são "ownership" e "fraud".
:::
:::caution **Atenção**
Após a action de cancelamento ser executada o processo de claim request chegou ao final e não existem hooks para serem recebidos.
:::

Request Body

```json title='Confirmação'
{
    "confirmation_reason": "client_request"
}
```
```json title='Cancelamento'
{
    "cancellation_reason": "client_request"
}
```
```json title='Cancelamento de ownership'
{
    "cancellation_reason": "fraud",
    "verification_code": "432371"
}
```
```json title='Pendente de validação do doador'
{}
```

#### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `confirmation_reason` | enum | **[Enumeradores](#enumeradores-confirmation_reason)**. | 14 |
| `cancellation_reason` | enum |  **[Enumeradores](#enumeradores-cancellation_reason)**. | 14 |
| `verification_code` | string | token recebido no número de telefone ou e-mail. | 6 |

#### Enumeradores confirmation_reason

| Enumerador | Tradução |
|---|---|
|  client_request  | pedido do clitente |

#### Enumeradores cancellation_reason

| Enumerador | Tradução |
|---|---|
|  **client_request**  | pedido do clitente |
|  **fraud**  | fraude |

:::caution **Atenção**
Ao cancelar um pedido de portabilidade do tipo "ownership" o "cancelation_reason" sempre deve ser "fraud".
:::

### Response

STATUS 200

Response Body

```json
{
    "max_conclusion_date": "2023-05-26T12:13:25",
    "claim_request_status": "confirmed",
    "claimant": {
        "document_number": "12345678000190",
        "claimant_key": "6aaadfbc-76ba-45d2-bb21-138bcb2baa62",
        "account_opened_at": "2023-01-17T12:28:37",
        "account_branch": "0001",
        "account_type": "checking",
        "account_number": "7336349",
        "person_type": "legal",
        "account_digit": "0"
    },
    "max_resolution_date": "2023-05-19T12:13:25",
    "claimant_bank_name": "QI SCD S.A.",
    "pix_key": {
        "pix_key_type": "cnpj",
        "pix_key_status": "active",
        "created_at": "2023-05-12T12:13:24",
        "updated_at": "2023-05-12T12:13:24",
        "account_key": "169010e3-6c1e-4521-9253-11cbbf36c59j",
        "pix_key": "12345678000190"
    },
    "donator_ispb": null,
    "external_key": null,
    "claim_request_key": "7f8b67d2-d8e4-4759-85eb-e4d0ac24708c",
    "claim_request_type": "portability",
    "client_role": "claimant",
    "confirmation_reason": null,
    "requester_key": "e151044c-44d0-48b3-9df1-0b9475077fe5",
    "claimant_bank_code": "329",
    "cancelled_by": null,
    "request_failure_reason": null,
    "donator": null,
    "account_key": "169010e3-6c1e-4521-9253-11cbbf36c59j"
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                            | Descrição (eng)<br/>`Description`                                                                                                | Descrição (ptbr)<br/>`translation`                                                                                                 |
|-------------|----------------------|-----------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------|
| 400         | PIX000043            | Claim request action not allowed on current status                    | confirmed Claim request action only allowed for pending_confirmation requests                                                                                      | Ação confirmed para claim request permitida somente para pedidos com status pending_confirmation.                                                                                              |
| 400         | PIX000036            | Claim request action not allowed for claimant             | Claim request action not allowed for claimant. Only donator can perform this action                                                                 | Ação sobre claim request não permitida para reivindicador. Somente o doador pode executar esta ação                                                                        |
| 400         | PIX000044            | Claim request confirm action without reason                         | confirmation_reason is required on action confirmed                                                                                              | confirmation_reason é obrigatório na ação confirmed                                                                                                |
| 400         | PIX000045            | Razão da confirmação não permitida                   | cancellation_reason: invalid not allowed for client_role: donator and claim_request_type: portability                                          | cancellation_reason: invalid não permitida para client_role: donator and claim_request_type: portability                  |
| 400         | PIX000039            | Claim request action not allowed on current status                            | Cancelled Claim request action only allowed for non concluded requests | Ação cancelled para claim request permitida somente para pedidos com status diferente de concluded |
| 400         | PIX000040            | Claim request cancel action without reason                       | cancellation_reason is required on action cancelled                                                                                    | cancellation_reason é obrigatório na ação cancelled                                                                               |
| 400        | PIX000042            | Razão do cancelamento não permitida                   | cancellation_reason: client_request not allowed for client_role: donator and claim_request_type: ownership                                                                                       | cancellation_reason: client_request não permitida para client_role: donator and claim_request_type: ownership                                                                                         |
| 400         | PIX000051            | Verification code required | 2FA verification code required.                     | Código de verificação 2FA necessário.     |
| 400 | PIX000100 | External Claim Already Cancelled | The external claim request has already been cancelled | O pedido de portabilidade externo já foi cancelado |
| 404         | PIX000034            | Claim Request not found                              | IClaim Request not found. claim_request_key: 7f8b67d2-d8e4-4759-85eb-e4d0ac24708c external_key: b8e25f24-4051-4b13-90a7-76be7b6e96d2.                                                                                            | Claim Request não encontrada. claim_request_key: 7f8b67d2-d8e4-4759-85eb-e4d0ac24708c external_key: b8e25f24-4051-4b13-90a7-76be7b6e96d2.                                                                                       |
| 401         | 2FA000401            | Unauthorized                             | Invalid verification combination.                                                          | CCódigo de verificação inválido.                                                        |
| 403         | 2FA000403            | Forbidden                              | Code already verified.                                                                                    | Este código já foi utilizado.                                                                                |
| 410         | 2FA000410            | Gone                       | Expired Code.                                                                                       | Código de verificação expirado.                                                           |

---

# Simular alteração de status de portabilidade

URL: /documentation/pix/portabilidade/simular_alteracao_de_status_de_portabilidade

### Request

ENDPOINT /mock/pix_keys/key_claim_simulation/ CLAIM_REQUEST_KEY
/receive_response/ CLAIM_ACTION
MÉTODO PATCH

#### Path params

| Campo               | Tipo   | Descrição                                                |
|---------------------|--------|----------------------------------------------------------|
| `claim_request_key` | uuidv4 | Chave única de identificação do pedido de portabilidade. |
| `claim_action`      | string | **[Enumeradores](#enumeradores-claim_action)**           |

#### Enumeradores claim_action

| Enumerador    | Tradução   | Descrição                                                                                                                                 |
|---------------|------------|-------------------------------------------------------------------------------------------------------------------------------------------|
| **failed**    | falhou     | O pedido de portabilidade falhou                                                                                                          |
| **confirmed** | confirmado | O pedido de portabilidade está confirmado, necessita de aprovação do banco doador para ser concluido ou de rejeição para ser cancelado    |
| **cancelled** | cancelado  | O pedido de portabilidade está cancelado, logo, para se realizar uma claim sobre está chave deve-se abrir um novo pedido de portabilidade |
| **concluded** | concluído  | O pedido de portabilidade está concluído                                                                                                  |

Request Body

```json
{}
```

### Response

STATUS 204

Response Body

```json
{}
```

STATUS 4XX

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                           | Descrição (eng)<br/>`Description`                                                         | Descrição (ptbr)<br/>`translation`                                                                  |
|-------------|----------------------|----------------------------------------------|-------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|
| 404         | PIX000034            | Claim Request not found                      | Claim Request not found. claim_request_key: claim_request_key external_key: external_key. | Claim Request não encontrada. claim_request_key: claim_request_key external_key: external_key.      |
| 400         | PIX000035            | Claim request action not allowed for donator | Claim request action not allowed for donator. Only claimant can perform this action       | Ação sobre claim request não permitida para doador. Somente o reinvidicador pode executar esta ação |

---

# Simular webhook de conclusão do pedido de portabilidade

URL: /documentation/pix/portabilidade/simular_webhook_de_conclusao

### Request

ENDPOINT /mock/pix_keys/key_claim_simulation/ CLAIM_REQUEST_KEY
/complete
MÉTODO PATCH

#### Path params

| Campo               | Tipo   | Descrição                           |
|---------------------|--------|-------------------------------------|
| `claim_request_key` | string | a chave do pedido de portabilidade. |

Request Body

```json
{}
```

### Response

STATUS 204

Response Body

```json
{}
```

STATUS 4XX

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                                  | Descrição (eng)<br/>`Description`                                                                                                         | Descrição (ptbr)<br/>`translation`                   |
|-------------|----------------------|-----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------|
| 404         | PIX000034            | Pedido de portabilidade não encontrado              | Claim Request não encontrada. claim_request_key: 7f8b67d2-d8e4-4759-85eb-e4d0ac24708c external_key: b8e25f24-4051-4b13-90a7-76be7b6e96d2. | Pedido de portabilidade não encontrado.              |
| 400         | PIX000046            | Ação de portabilidade não permitida no status atual | Ação concluded para pedido de reivindicação permitida somente para status confirmed                                                       | Ação de portabilidade não permitida no status atual. |
| 400         | PIX000036            | Ação não permitida para requerente                  | Ação sobre claim request não permitida para reivindicador. Somente o doador pode executar esta ação                                       | Ação não permitida para requerente.                  |

---

# Simular webhook de recebimento de um pedido de portabilidade

URL: /documentation/pix/portabilidade/simular_webhook_recebimento

### Request

ENDPOINT
      /mock/pix_keys/key_claim_simulation/receive
MÉTODO
      POST

Request Body

```json
{
  "pix_key": "12345678000190",
  "pix_key_type": "cnpj"
}
```

#### Body Params

| Campo          | Tipo | Descrição                                                    | Caracteres                                     |
|----------------|------|--------------------------------------------------------------|------------------------------------------------|
| `pix_key`      | enum | chave para simular o recebimento de pedido de portabilidade. | -                                              |
| `pix_key_type` | enum | tipo da chave pix da portabilidade.                          | **[Enumeradores](#enumeradores-pix_key_type)** |

#### Enumeradores pix_key_type

| Enumerador   | Tradução           |
|--------------|--------------------|
| **random_key**   | aleatória          |
| **email**        | e-mail             |
| **phone_number** | número de telefone |
| **cpf**          | cpf                |
| **cnpj**         | cnpj               |

:::info Tipos de Chave Pix
A chave pix enviada no payload deve estar ativa no ambiente de sandbox e em uma conta que você tenha criado.
:::

### Response

STATUS 201

Response Body

```json
{}
```

STATUS 4XX

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`         | Descrição (eng)<br/>`Description`                                       | Descrição (ptbr)<br/>`translation`                                             |
|-------------|----------------------|----------------------------|-------------------------------------------------------------------------|--------------------------------------------------------------------------------|
| 400         | PIX000072            | Pix Key Claim Non Finished | Pix key 12345678000190, already has a claim request non finished.       | Chave pix 12345678000190, já possui um pedido de portabilidade não finalizado. |
| 400         | PIX000026            | Account not found          | Account not found for account_key: 6aaadfbc-76ba-45d2-bb21-138bcb2baa62 | Conta não encontrada para account_key: 6aaadfbc-76ba-45d2-bb21-138bcb2baa62    |

---

# Validação de dois fatores

URL: /documentation/pix/portabilidade/validacao_de_dois_fatores

:::info Token em Sandbox
Para facilitar os testes no ambiente de sandbox, o token terá sempre o valor `329329`.

Este comportamento é exclusivo para o ambiente de sandbox.
:::

### Request

ENDPOINT /baas/pix/key_claim_request/ CLAIM_REQUEST_KEY /twofa_validation
MÉTODO PATCH

#### Path params

| Campo               | Tipo   | Descrição                           |
|---------------------|--------|-------------------------------------|
| `claim_request_key` | string | a chave do pedido de portabilidade. |

Request Body

```json
{
  "verification_code": "432371"
}
```

#### Body Params

| Campo               | Tipo   | Descrição                                       | Caracteres |
|---------------------|--------|-------------------------------------------------|------------|
| `verification_code` | string | token recebido no número de telefone ou e-mail. | 6          |

### Response

STATUS 200

Response Body

```json
{
  "max_conclusion_date": "2023-05-26T12:13:25",
  "claim_request_status": "pending",
  "claimant": {
    "document_number": "12345678000190",
    "claimant_key": "6aaadfbc-76ba-45d2-bb21-138bcb2baa62",
    "account_opened_at": "2023-01-17T12:28:37",
    "account_branch": "0001",
    "account_type": "escrow",
    "account_number": "7336349",
    "person_type": "legal",
    "account_digit": "0"
  },
  "max_resolution_date": "2023-05-19T12:13:25",
  "claimant_bank_name": "QI SCD S.A.",
  "pix_key": {
    "pix_key_type": "cnpj",
    "pix_key_status": "pending_confirmation",
    "created_at": "2023-05-12T12:13:24",
    "updated_at": "2023-05-12T12:13:24",
    "account_key": "169010e3-6c1e-4521-9253-11cbbf36c59j",
    "pix_key": "12345678000190"
  },
  "donator_ispb": null,
  "external_key": null,
  "claim_request_key": "7f8b67d2-d8e4-4759-85eb-e4d0ac24708c",
  "claim_request_type": "portability",
  "client_role": "claimant",
  "confirmation_reason": null,
  "requester_key": "e151044c-44d0-48b3-9df1-0b9475077fe5",
  "claimant_bank_code": "329",
  "cancelled_by": null,
  "request_failure_reason": null,
  "donator": null,
  "account_key": "169010e3-6c1e-4521-9253-11cbbf36c59j"
}

```

STATUS 4XX

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`Description`                                           | Descrição (ptbr)<br/>`translation`                                                  |
|-------------|----------------------|----------------------------------------------------|-----------------------------------------------------------------------------|-------------------------------------------------------------------------------------|
| 400         | PIX000047            | Claim request action not allowed on current status | Validate Claim request action only allowed for pending_validation requests. | Ação validate para claim request permitida somente para pedidos pending_validation. |
| 401         | 2FA000401            | Unauthorized                                       | Invalid verification combination.                                           | Código de verificação inválido.                                                     |
| 403         | 2FA000403            | Forbidden                                          | Code already verified.                                                      | Este código já foi utilizado.                                                       |
| 403         | QIT000005            | Permission Validator Error.                        | Selected agent do not own this item.                                        | O agente selecionado não é dono do item.                                            |
| 410         | 2FA000410            | Gone                                               | Expired Code.                                                               | Código de verificação expirado.                                                     |
| 404         | PIX000031            | Claim Request not found                            | Claim Request not found for key: 7f8b67d2-d8e4-4759-85eb-e4d0ac24708c.      | Claim Request não encontrada para a chave: 7f8b67d2-d8e4-4759-85eb-e4d0ac24708c.    |

---

# Simulação de cenários

URL: /documentation/pix/simulacao

Passo a passo para simular a efetivação de ações feitas por agentes externos. Essas simulações incluem: entrada, estorno
e portabilidade IN de chave PIX.

## 1 - Simulação de entrada de PIX

### Request

ENDPOINT /mock/pix_transfer/incoming_pix_transfer
MÉTODO POST

Request Body

```json
{
  "target_account_key": "\<Chave unitária da conta de destino\>",
  "amount": "\<Valor da transação\>"
}
```

### Body Parameters

| Campo                | Tipo   | Descrição                          | Máx. Caract. | Exemplo                                | Observação              |
|----------------------|--------|------------------------------------|--------------|----------------------------------------|-------------------------|
| `target_account_key` | string | Chave unitária da conta de destino | 36           | "41112f46-0034-4007-85687-5e592173db2" |                         |
| `amount`             | number | Valor da transação                 | 6            | 1000                                   | Valor máximo de 100.000 |

## Response

STATUS 201

Response Body

```json
{
  "end_to_end_id": "E60701190202601291553Zrxq8RRUwS1"
}
```

## 2 - Simulação de resultado da análise de entrada PIX

Para simular o cenário onde a entrada PIX entra em análise manual, é necessário simular uma entrada com valor superior a R$ 2.000.000,00 (dois milhões de reais). Nesse caso, o PIX ficará em status de análise manual e o cliente receberá os devidos webhooks.

:::caution Atenção
A regra de dois milhões é exclusiva para ambiente de sandbox e **não reflete os casos de produção**.
:::

Após receber o webhook de análise manual, é necessário utilizar esta rota de simulação para aprovar ou recusar a entrada do recurso. O cliente também receberá os devidos webhooks com o resultado da análise.

### Request

ENDPOINT /mock/pix_transfer/incoming_pix_analysis_result
MÉTODO POST

Request Body

```json
{
  "end_to_end_id": "E60701190202601291537yo1ZxpvVzJn",
  "analysis_status": "manually_reproved"
}
```

### Body Parameters

| Campo             | Tipo   | Descrição                                                   | Máx. Caract. | Exemplo                            | Observação |
|-------------------|--------|-------------------------------------------------------------|--------------|------------------------------------|-----------|
| `end_to_end_id`   | string | Chave unitária da transação PIX                             | 32           | "E60701190202601291537yo1ZxpvVzJn" |            |
| `analysis_status` | enum   | [Enumerador Analysis Status](#enumerador-analysis-status)   |              | "manually_reproved"                |            |

### Enumerador Analysis Status

| Enumerador            | Descrição             |
|-----------------------|-----------------------|
| **manually_approved** | Aprovado manualmente  |
| **manually_reproved** | Reprovado manualmente |

## 3 - Simulação de pagamento de PIX QR Code

### Request

ENDPOINT /mock/pix_transfer/incoming_pix_qrcode
MÉTODO POST

Request Body

```json
{
  "qr_code_key": "41112f46-0034-4007-85687-5e592173db2"
}
```

### Body Parameters

| Campo         | Tipo   | Descrição                                  | Máx. Caract. | Exemplo                                | Observação |
|---------------|--------|--------------------------------------------|--------------|----------------------------------------|------------|
| `qr_code_key` | string | Chave unitária de identificação do qr code | 36           | "41112f46-0034-4007-85687-5e592173db2" |            |

## 4 - Simulação de estorno de PIX

### Request

ENDPOINT /mock/pix_transfer/chargeback
MÉTODO POST

Request Body

```json
{
  "end_to_end_id": "\<Chave unitária da transação\>",
  "amount": "\<Valor da transação\>"
}
```

### Body Parameters

| Campo           | Tipo   | Descrição                       | Máx. Caract. | Exemplo                            | Observação              |
|-----------------|--------|---------------------------------|--------------|------------------------------------|-------------------------|
| `amount`        | number | Valor da transação              | 6            | 1000                               | Valor máximo de 100.000 |                        |
| `end_to_end_id` | string | Chave unitária da transação PIX | 32           | "E3240250220210723142712312751267" |                         |                         

## 5 - Simulação de webhook de portabilidade IN de chave PIX

### Request

ENDPOINT /mock/pix_keys/key_claim_request/webhook
MÉTODO POST

Request Body

```json
{
  "claim_request_key": "\<Chave unitária do requester\>",
  "claim_request_status": "\<Enumerador de status\>"
}
```

### Body Parameters

| Campo                  | Tipo   | Descrição                                                           | Máx. Caract. | Exemplo                                | Observação |
|------------------------|--------|---------------------------------------------------------------------|--------------|----------------------------------------|------------|
| `claim_request_key`    | string | Chave unitária do requester                                         | 36           | "ced00dc6-000a-0bd4-a111-85710a46ec05" |            |
| `claim_request_status` | enum   | [Enumerador Claim Request Status](#enumerador-claim-request-status) |              | "concluded"                            |            |

### Enumerador _Claim Request Status_

| Enumerador               | Descrição               |
|--------------------------|-------------------------|
| **concluded**            | Concluído               |
| **cancelled**            | Cancelado               |
| **failed**               | Falha                   |
| **pending_confirmation** | Pendente de confirmação |

## 6 - Simulação de transação em estado pendente de confirmação

Transações pix podem entrar em status **pending_confirmation** quando ocorre alguma demora no retorno da resposta da
transação Pix pelo Banco Central. Para simular este cenário, realize uma transação com a chave
pix `"target_pix_key": "0476f803-0129-430a-a66c-d2f0d7cf4aaa"` ou, para transferências pix do tipo **manual**,
utilize `"owner_document_number": "35586870002"` como número de documento do proprietário da conta de destino.

Para que o status da transação seja atualizado, realize a requisição abaixo com `transaction_status` de **sent** para
aprovar a transação, ou **rejected** para reprová-la.

### Request

ENDPOINT /mock/pix_transfer/pending_confirmation
MÉTODO POST

Request Body

```json
{
  "end_to_end_id": "E32402502202308181802vSHbiqNCk9i",
  "transaction_status": "rejected",
  "status_reason_information": {
    "error_description": "description",
    "error_translation": "translation",
    "error_short_description": "short_description"
  },
  "error_code": "test_error"
}
```

### Body Parameters

| Campo                       | Tipo   | Descrição                                                             | Máx. Caract. |
|-----------------------------|--------|-----------------------------------------------------------------------|--------------|
| `end_to_end_id`*            | string | Chave unitária da transação PIX                                       | 36           |
| `transaction_status`*       | enum   | [Enumerador Transaction Status](#enumerador-transaction-status)       |
| `status_reason_information` | objeto | [Objeto Status Reason Information](#objeto-status-reason-information) |
| `error_code`                | string | Código de erro                                                        |

### Enumerador Transaction Status

| Enumerador   | Descrição |
|--------------|-----------|
| **sent**     | Concluído |
| **rejected** | Rejeitado |

### Objeto Status Reason Information

| Campo                     | Tipo   | Descrição                         | Máx. Caract. |
|---------------------------|--------|-----------------------------------|--------------|
| `error_description`       | string | Descrição do erro em inglês       | 100          |
| `error_translation`       | string | Descrição do erro em português    | 100          |
| `error_short_description` | string | Descrição curta do erro em inglês | 100          |

## 7 - Simulação de transação rejeitada

Transações pix podem entrar em status **rejected** quando ocorre algum retorno esperado de recusa da
transação Pix pelo Banco Central ou PSP recebedor. Para simular este cenário, realize uma transação com a chave
pix `"target_pix_key": "b9380607-dac6-4e17-8ca7-eb761e3aa1dc"` ou, para transferências pix do tipo **manual**,
utilize `"owner_document_number": "66972913039"` ou `"owner_document_number": "50305556000164"` como número de documento
do proprietário da conta de destino.

## 8 - Recuperar Token enviado para Autenticação de Dois Fatores

Para transações pix individuais e em lote de parceiros integradores com configuração de autenticação de dois fatores,
um `token` é enviado ao aprovador de movimentação da conta. Por meio deste endpoint é possível recuperar o endpoint
enviado para fins de teste de integração.

ENDPOINT /mock/2fa/transaction_request/ TRANSACTION_REQUEST_KEY
MÉTODO GET

## Path Params

| Campo                     | Tipo  | Descrição                                                                                                                                                           | Caracteres |
|---------------------------|-------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------|
| `transaction_request_key` | uuid4 | Chave única de identificação transação. Para o caso de transação pix seria a `pix_transfer_key` e para o caso de transação pix em lote é a `pix_transfer_batch_key` | 36         |

Response Body

```json
{
  "token": "1a2b3c"
}
```

---

# Solicitar alteração de limite Pix

URL: /documentation/pix/solicitar_alteracao_de_limite_pix

## Request

ENDPOINT /baas/pix/limits/ ACCOUNT_KEY
MÉTODO POST

Request Body

```json
{
    "daily_amount_limit": 2000.00,
    "nightly_amount_limit": 1000.00,
    "self_daily_amount_limit": 1500.00,
    "self_nightly_amount_limit": 500.00
}
```

### Body Params

| Campo                       | Tipo  | Descrição                                                                          |
|-----------------------------|-------|------------------------------------------------------------------------------------|
| `daily_amount_limit`        | float | Limite durante o período diurno para transferências Pix de diferente titularidade  |
| `nightly_amount_limit`      | float | Limite durante o período noturno para transferências Pix de diferente titularidade |
| `self_daily_amount_limit`   | float | Limite durante o período diurno para transferências Pix de mesma titularidade      |
| `self_nightly_amount_limit` | float | Limite durante o período noturno para transferências Pix de mesma titularidade     | 

:::info Horário diurno
Para o período **diurno** são contabilizadas transferências realizadas entre **06:00** e **20:00**.
:::

:::danger Atenção
As Solicitações de aumento de limite Pix possuem um SLA de **48 horas** para aprovação.

Solicitações de redução do limite Pix são aprovação e executadas imediatamente. 

Caso o SLA de **48 horas** seja atingido sem aprovação, a solicitação é automaticamente rejeitada com o motivo `Tempo de avaliação expirado.` e um webhook de rejeição é enviado ao requisitante (ver [Webhook Request Rejected Body](#webhook-request-rejected-body)).
:::

## Response

STATUS 200

Response Body

```json
[
	{
		"account_digit": "5",
		"account_key": "467ce632-cc2c-412a-bc56-aa949bd8393d",
		"account_name": "Default",
		"account_number": "26709",
		"amount_limit": 2000.0,
		"event_type": "pix_limit_request",
		"limit_type": "daily",
		"owner_document_number": "63602991000100",
		"request_status": "pending_approval",
		"requester_document_number": "77669728833"
	},
	{
		"account_digit": "5",
		"account_key": "467ce632-cc2c-412a-bc56-aa949bd8393d",
		"account_name": "Default",
		"account_number": "26709",
		"amount_limit": 1000.0,
		"event_type": "pix_limit_request",
		"limit_type": "nightly",
		"owner_document_number": "63602991000100",
		"request_status": "pending_approval",
		"requester_document_number": "77669728833"
	},
	{
		"account_digit": "5",
		"account_key": "467ce632-cc2c-412a-bc56-aa949bd8393d",
		"account_name": "Default",
		"account_number": "26709",
		"amount_limit": 1500.0,
		"event_type": "pix_limit_request",
		"limit_type": "self_daily",
		"owner_document_number": "63602991000100",
		"request_status": "pending_approval",
		"requester_document_number": "53417895200"
	},
	{
		"account_digit": "5",
		"account_key": "467ce632-cc2c-412a-bc56-aa949bd8393d",
		"account_name": "Default",
		"account_number": "26709",
		"amount_limit": 500.0,
		"event_type": "pix_limit_request",
		"limit_type": "self_nightly",
		"owner_document_number": "63602991000100",
		"request_status": "pending_approval",
		"requester_document_number": "53417895200"
	}
]

```

STATUS 400

Response Body: Número enviado inválido

```json
{
	"title": "Bad Request",
	"description": "Invalid decimal amount, sent 1500.001",
	"translation": "Valor decimal inválido, enviado 1500.001",
	"code": "PXT000043",
	"additional_data": {}
}
```

STATUS 403

Response Body: Usuário não possui credenciais

```json
{
    "title": "Unauthorized",
    "description": "User is not allowed to do this transaction",
    "translation": "Usuário não tem autorização para fazer essa transação",
    "code": "PIT000001"
}
```

### Webhook Response

:::info Evento gerador de webhook
Webhooks são enviados ao requisitante da conta ao ser realizada a execução da solicitação de limite
:::

Webhook Request Accepted Body

```json
{
   "webhook_type": "baas.pix.limits.account_limit_config.updated",
   "webhook_datetime": "2023-08-05T19:54:01.514Z",
   "data": {
      "pix_transfer_limit_config": [
         {
            "period": "daily",
            "account_key": "467ce632-cc2c-412a-bc56-aa949bd8393d",
            "amount_limit": 800012.67,
            "self_amount_limit": 500.03
         },
         {
            "period": "nightly",
            "account_key": "467ce632-cc2c-412a-bc56-aa949bd8393d",
            "amount_limit": 100000.0,
            "self_amount_limit": 100000.0
         }
      ]
   }
}
```

Webhook Request Rejected Body

```json
{
   "webhook_type":"baas.pix.limits.account_limit_config.updated",
   "webhook_datetime": "2023-08-05T19:54:01.514Z",
   "data":{
     "message": "QI Tech informa que a solicitacao de limite PIX diário para terceiros da sua conta foi rejeitada. Motivo: limite reanalisado.",
     "account_key": "467ce632-cc2c-412a-bc56-aa949bd8393d",
     "request_status": "rejected",
     "limit_type": "daily"
   }
}
```

### Enumeradores limit_type
| Enumerador            | Descrição                                                                          |
|-----------------------|------------------------------------------------------------------------------------|
| `daily`               | Limite durante o período diurno para transferências Pix de diferente titularidade  |
| `nightly`             | Limite durante o período noturno para transferências Pix de diferente titularidade |
| `self_daily`          | Limite durante o período diurno para transferências Pix de mesma titularidade      |
| `self_nightly`        | Limite durante o período noturno para transferências Pix de mesma titularidade     |

---

# Solicitar devolução de um Pix

URL: /documentation/pix/solicitar_chargeback_pix

A devolução de um Pix pode ser solicitada em até 90 dias a partir de seu recebimento.

## Request

ENDPOINT /baas/pix_transfer
MÉTODO POST

:::info Informação
Após a solicitação da devolução é necessário realizar a [aprovação da solicitação de transferência Pix](../pix/aprovar_solicitacao_de_transferencia) 
:::

Request Body

```json
{
    "is_chargeback": true,
    "pix_transfer_key": "b91da9c7-72de-46dc-bb36-4b1407d1eb91",
    "chargeback_amount": 147,
    "chargeback_message": "Mensagem Pix da devolução"
}
```

## Response

STATUS 200

Response Body

```json
{
	"data": {
		"pix_transfer_key": "b3015cb5-862d-48aa-946d-c14afc8cdebb",
		"pix_transfer_status": "pending_approval",
		"pix_transfer_type": "chargeback",
		"target_account": {
			"document_number": "***02502000***",
			"financial_institution": "QI SOCIEDADE DE CRÉDITO DIRETO S.A."
		},
		"transfer_amount": 35
	},
	"event_datetime": "2023-03-21 11:52:11",
	"operation_key": "ec9b4741-7c7e-4429-9b10-3fc05045ebea",
	"status": "pending_approval"
}
```

STATUS 4xx

Response Body: Reversão Rejeitada

```json
{
    "title": "titulo",
    "description": "description in English",
    "translation": "descrição em portugues",
    "code": "codigo"
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                  | Descrição (eng)<br/>`description`                                      | Descrição (ptbr)<br/>`translation`                                                        |
|--------------------------|----------------------|-------------------------------------|------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                         | Schema Error                                                           | Erro de Schema                                                                            |
| 404                      | PXT000084            | Original Pix Transfer Was Not Found | Original Pix Transfer Was Not Found.                                   | A transação PIX original não foi encontrada.                                              |
| 400                      | PXT000017            | Reversal Too Great                  | Reversal transfers sum amount surpasses that of original pix transfer. | A soma das transferências de devolução ultrapassam o valor da transferência pix original. |
| 400                      | PXT000015            | Reversal date expired               | Reversal original transaction is older than 90 days                    | A data de criação da transação original é mais antiga que 90 dias                         |

---

# solicitar_transferencia

URL: /documentation/pix/solicitar_transferencia

## Request

ENDPOINT /baas/pix_transfer
MÉTODO POST

Request Body

```json
{
    "pix_transfer_type": "manual",
    "source_account": {
        "account_branch": "0001",
        "branch_digit": "1",
        "account_digit": "3",
        "account_number": "12345678",
        "owner_document_number": "32402502000135"
    },
    "target_account": {
        "account_branch": "0001",
        "account_digit": "3",
        "account_number": "12345678",
        "financial_institution_code": "329",
        "owner_document_number": "32402502000135",
        "owner_name": "Qi Tech",
        "account_type": "checking_account",
        "ispb": "32402502"
    },
    "transaction_amount": 500,
    "receiver_conciliation_id": "REC00000000000000000000009459463343",
    "is_chargeback": false,
    "requester_document_identification": "11111111111",
    "pix_transfer_key": "b5904f04-101e-4602-8fbc-c5dcc4c2caec",
    "chargeback_amount": 500,
    "chargeback_other_reason": "Valor excedente ao combinado"
}

```

### Body Params

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `pix_transfer_type` * | string | O Pix possui diferentes tipos de iniciação, o "manual" onde o usuário deve enviar os campos da conta de destino e conta de origem e o "key" onde o usuário deve enviar os campos da chave Pix do recebedor (conta de destino) e os dados da conta de origem. | 10 |
| `source_account` * | Object | Conta de origem. | **[Objeto source_account](#objeto-source_account)** | 
| `target_account` | Object | Conta destino - Só deve ser enviada em transações do tipo "manual". | **[Objeto target_account](#objeto-target_account)** | 10 |
| `transaction_amount` * | string | Valor da transferencia. | 10 |
| `receiver_conciliation_id` | string | Identicação de conciliação do recebedor. | 10 |
| `is_chargeback` | string | Flag de identificação de uma devolução de transação Pix (booleano True ou False). | 10 |
| `requester_document_identification` * | string | CPF do usuário quem está solicitando a transferência. | 10 |
| `pix_transfer_key` | string | Chave de idempotência de uma transação Pix - só deve ser enviado se o tipo de transferência for "key". | 10 |
| `chargeback_amount` | string | Valor da devolução - Este campo deve ser enviado apenas em caso de chargeback e exclui a obrigatoriedade do campo "transaction_amount". |  10 |
| `chargeback_other_reason` | string | Motivo de devolução ( Este campo deve ser enviado apenas em caso de chargeback). | 10 |
| `chargeback_message` | string | Campo para usuário inserir mensagem durante a devolução ( Este campo deve ser enviado apenas em caso de chargeback). | 10 |
 
### Objeto source_account

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `account_branch` * | string | Número Agência. | 0 |
| `branch_digit` |string | Dígito da Agência.| 0 |
| `account_digit` * | string | Dígito da conta.| 0 |
| `account_number` * | string | Número da conta.| 0 | 
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta.| 0 |

### Objeto target_account

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `account_branch` * | string | Agência. | 10 |
| `account_digit` * | string | Dígito da conta | 10 |
| `account_number` * | string | Número da conta. | 10 |
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta. | 10 |
| `owner_name` * | string | Nome do titular da conta. | 10 |
| `account_type` * |string |  CPF ou CNPJ (apenas números) do titular da conta.| 10 |
| `ispb` | string |  Código de oito dígitos que identifica os bancos no sistema de transferência de reserva do Banco Central.| 10 |

## Response

STATUS 200

Response Body: Transferência manual

```json
{
  "operation_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "status": "pending",
  "event_datetime": "2021-08-04 20:05:54",
  "pix_transaction": {
    "pix_message": "",
    "pix_transfer_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "transaction_amount": 1891268.97,
    "source_account": {
      "account_branch": "0001",
      "account_digit": "3",
      "account_number": "24339",
      "owner_document_number": "32402502000135",
      "owner_name": "Qi Tech",
      "account_type": "checking"
    },
    "target_account": {
      "target_account": "78340-6",
      "financial_institution_code": "329",
      "owner_document_number": "32402502000135",
      "owner_name": "QI Tech",
      "target_account_type": "checking_account",
      "owner_person_type": "legal",
      "trading_name": "QITech"
    },
    "fee_amount": 0
  }
}

```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

---

# Webhook por QR Code Pix dinâmico expirado

URL: /documentation/pix/webhook_por_qr_code_expirado

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

## Webhook

:::info Evento gerador de webhook
Webhooks são enviados ao detentor da chave pix vinculada ao QR Code Dinâmico. Este evento ocorre uma única vez após o vencimento do QR Code.
:::

Resquest Body

```json
{
   "event_type":"baas.pix_qr_code.occurrence.bank_write_off",
   "origin_key":"faf1ef5b-e0a9-4430-8aa4-367b4825854c",
   "data":{
      "pix_key":"c05b7c73-fb43-45c2-871d-8c890dbe5d85",
      "qr_code_key":"458b4a77-9cb2-4232-bae5-078150c4e93d",
      "qr_code_type":"dynamic_instant",
      "qr_code_status":"bank_written_off",
      "qr_code_occurrence_key":"faf1ef5b-e0a9-4430-8aa4-367b4825854c",
      "receiver_conciliation_id":"458b4a779cb24232bae5078150c4e93d"
   }
}
```

---

# Configurando Webhooks

URL: /documentation/primeiros_passos/configurando_webhooks

:::info Veja também
- [Validação de Webhooks](/documentation/primeiros_passos/teste_de_autenticacao/webhook_v2)
:::

Para configurar a URL de recepção das notificações faça login na plataforma QI Tech. Clique em "**Meu perfil**", localizado no menu lateral esquerdo, depois entre na aba Integração. Após isso, insira sua URL na divisão de "**Configurações de webhook**" da página e clique no botão “**SALVAR**”. Caso seja necessário configurar headers para as notificações enviadas é possível utilizar o campo seguinte conforme a imagem abaixo.

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeados de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

:::info Informação
O timeout para resposta dos nossos webhooks é de 10 segundos.
:::

---

# Configurar IP de Integração

URL: /documentation/primeiros_passos/configurar_ip_de_integracao

:::info Veja também
- [Configurando Webhooks](/documentation/primeiros_passos/configurando_webhooks)
- [Validação de Webhooks](/documentation/primeiros_passos/teste_de_autenticacao/webhook_v2)
:::

A QI Tech permite que você restrinja as chamadas à sua integração a uma lista de **endereços IP públicos** (ou ranges CIDR) previamente autorizados. Esse filtro é aplicado antes da validação de assinatura: requisições originadas de IPs fora da sua lista ativa serão recusadas com erro `403 Forbidden` (`GDF000029`).

## Como configurar

Faça login na plataforma QI Tech, clique em "**Meu perfil**" no menu lateral esquerdo e entre na aba **Integração**. Role até a seção "**Whitelist de IPs da API**" e adicione um IP por vez no campo "**IP / CIDR**", clicando em "**ADICIONAR IP**" a cada inclusão.

Formatos aceitos:

- Endereço IPv4 público (ex.: `189.10.20.30`)
- Range CIDR IPv4 com prefixo `/24` ou maior (ex.: `200.100.50.0/24`)
- Endereço IPv6 público
- Range CIDR IPv6 com prefixo `/48` ou maior

Endereços privados/reservados (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `127.0.0.0/8`, `169.254.0.0/16`) não são aceitos.

## Período de ativação (48 horas)

:::warning Atenção!
Por motivos de segurança, **todo IP cadastrado pelo painel fica em status `Pendente` por 48 horas** antes de se tornar ativo automaticamente. Durante esse período o IP é registrado mas **não autoriza requisições** — quem está na sua whitelist ativa atual continua valendo.

Você receberá um e-mail de confirmação no cadastro do IP e outro quando ele passar para o status `Ativo`.
:::

Após as 48 horas, o IP migra automaticamente para `Ativo` e passa a ser autorizado a chamar a API.

## Ativação emergencial

:::info Liberação imediata
Se você precisar liberar um IP **antes das 48 horas** (ex.: migração de servidor não planejada, incidente de produção), entre em contato com nosso suporte por meio dos canais oficiais e solicite a ativação manual informando:

- O `IP / CIDR` cadastrado
- A `client_integration_key` da sua integração
- O motivo da urgência

Nossa equipe de operações fará a promoção manual e o IP entrará em vigor imediatamente.
:::

## Erros comuns

| Código | Causa | Solução |
|---|---|---|
| `403` / `GDF000029` | Requisição partiu de um IP que não está em status `Ativo` na sua whitelist | Verifique na tela de Integração quais IPs estão ativos. Se o IP recém-cadastrado ainda está `Pendente`, aguarde as 48h ou solicite ativação manual. |
| Cadastro de IP rejeitado | IP/CIDR inválido, privado, ou range muito grande (prefixo menor que `/24` IPv4 ou `/48` IPv6) | Use somente endereços públicos e respeite os tamanhos mínimos de prefixo. |

---

# Introdução

URL: /documentation/primeiros_passos/inicio

Somos a primeira instituição financeira a criar um modelo exclusivo de Bank-as-a-Service (BaaS) do Brasil. Nosso objetivo é ajudar qualquer Fintech/Gestora de Crédito ou empresa a ter acesso a serviços financeiros rápidos, ágeis e seguros, da maneira que quiser. Saiba mais em https://qitech.com.br.

Essa documentação tem como objetivo descrever os diversos endpoints das nossas APIs.

Obs.: Em caso de dúvidas em qualquer etapa do processo, favor entrar em contato com [api@qitech.com.br](mailto:api@qitech.com.br) detalhando seu problema/dúvida que te auxiliaremos.

## Primeiros passos

Antes de iniciar as operações enviando requisições via API para consumo dos serviços QI Tech, é importante que um operador representante da empresa originadora realize os seguintes passos **em ambiente de sandbox**.

## Criação de Perfil de Acesso

1. Enviar solicitação de criação de acesso para o e-mail api@qitech.com.br informando os seguintes dados:
   1. CNPJ da empresa
   2. Nome completo do usuário Master
   3. CPF do usuário Master
   4. E-mail do usuário Master
   5. Telefone celular do usuário Master
2. Após a criação do acesso pelo time da QI Tech, o usuário Master receberá um e-mail com um link para acesso a plataforma da QI Tech em sandbox e uma senha provisória.
3. Ao realizar o primeiro acesso à plataforma o usuário Master deve redefinir a senha de acesso.

## Iniciando a jornada de integração

Existem várias combinações de endpoints que podem ser utilizadas de acordo com a necessidade do parceiro, porém os três primeiros passos são universais independente dos serviços utilizados:

Passo 1: Realizar a validação de Token através do portal QI Tech
Passo 2: [Realizar a troca de chaves e gerar credenciais de integração](/documentation/primeiros_passos/troca_de_chaves)
Passo 3: [Realizar o teste de autenticação](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2)
Passo 4: [Configurar a URL de recebimento de webhooks](/documentation/primeiros_passos/configurando_webhooks)

## Informações importantes

Para utilizar nossa API em produção é necessário que se entre com contato com [comercial@qitech.com.br](mailto:comercial@qitech.com.br) para contato comercial e configuração da integração.

---

# Endpoints de teste

URL: /documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste

:::info Veja também
- [Teste de autenticação](./teste_de_autenticacao_v2)
- [Exemplo completo de autenticação](./teste_de_autenticacao_completo)
- [Possíveis erros](./possiveis_erros)
:::

## Método GET

### Request

ENDPOINT /test/ API_KEY
MÉTODO GET

### Path Params

| Campo | Tipo | Descrição |
|-|-|-|
| `api_key` * | string | API_KEY do parceiro. |

<CodeSample endpoint="GET /test/{api_key}" samples={{
  curl: `curl -X GET \\
  'https://api-auth.sandbox.qitech.app/test/{api_key}' \\
  -H 'AUTHORIZATION: {encoded_header_token}' \\
  -H 'API-CLIENT-KEY: {api_key}'`,
  python: `import requests

url = f"{base_url}/test/{api_key}"
response = requests.get(url=url, headers=signed_header)
print(response.json())`,
  javascript: `const url = \`\${base_url}/test/\${api_key}\`;
const response = await fetch(url, {
  method: 'GET',
  headers: {
    'AUTHORIZATION': encoded_header_token,
    'API-CLIENT-KEY': api_key,
  },
});
const data = await response.json();
console.log(data);`,
  java: `OkHttpClient client = new OkHttpClient();
Request request = new Request.Builder()
    .url(requestUrl + "/" + api_key)
    .headers(Headers.of(headers))
    .get()
    .build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());`,
}} />

### Response

STATUS 200

Response Body

```json
{
  "test_key": "97ad0301-869c-4481-98b6-294b139e09ae",
  "success": "Congrats!"
}
```

## Método POST

### Request

ENDPOINT test/ API_KEY
MÉTODO POST

<CodeSample endpoint="POST /test/{api_key}" samples={{
  curl: `curl -X POST \\
  'https://api-auth.sandbox.qitech.app/test/{api_key}' \\
  -H 'AUTHORIZATION: {encoded_header_token}' \\
  -H 'API-CLIENT-KEY: {api_key}' \\
  -H 'Content-Type: application/json' \\
  -d '{"name": "QI Tech"}'`,
  python: `import requests

url = f"{base_url}/test/{api_key}"
body = {"name": "QI Tech"}
response = requests.post(url=url, headers=signed_header, json=body)
print(response.json())`,
  javascript: `const url = \`\${base_url}/test/\${api_key}\`;
const response = await fetch(url, {
  method: 'POST',
  headers: {
    'AUTHORIZATION': encoded_header_token,
    'API-CLIENT-KEY': api_key,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: 'QI Tech' }),
});
const data = await response.json();
console.log(data);`,
  java: `OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(
    mediaType, "{\\"name\\": \\"QI Tech\\"}");
Request request = new Request.Builder()
    .url(requestUrl + "/" + api_key)
    .headers(Headers.of(headers))
    .post(body)
    .build();
Response response = client.newCall(request).execute();
System.out.println(response.body().string());`,
}} />

Request Body

```json
{
  "name": "QI Tech"
}
```

### Path Params

| Campo | Tipo | Descrição |
|-|-|-|
| `api_key` * | string | API_KEY do parceiro. |

### Response

STATUS 201

Response Body

```json
{
  "name": "QI Tech",
  "success": "Congrats!"
}
```

---

# Possíveis erros

URL: /documentation/primeiros_passos/teste_de_autenticacao/possiveis_erros

:::info Veja também
- [Teste de autenticação](./teste_de_autenticacao_v2)
- [Exemplo completo de autenticação](./teste_de_autenticacao_completo)
- [Endpoints de teste](./endpoints_de_teste)
:::

## Erro no token

Caso a assinatura da string_to_sign esteja incorreta, um erro será apresentado relativo ao encoded_header_token :

STATUS 401

Response Body

```json
{
	"title": "QI Unauthenticated",
	"description": "Please provide valid credentials as part of the request. (Documentation: https://qitech.com.br/documentation) Details: Failed while decoding the authentication token",
	"translation": "Por favor forneça credenciais válidas como parte da request. (Documentação: https://qitech.com.br/documentation) Detalhes: Falha ao decodificar o token de autenticação",
	"code": "GDF000014"
}
```

## Erro no <strong>API_KEY</strong>

Caso a API_KEY não seja enviada no header o seguinte erro será apresentado:

STATUS 400

Response Body

```json
{
	"title": "Bad Request",
	"description": "No API Client Key received",
	"translation": "Nenhuma chave de API do cliente recebida",
	"code": "GDF000003"
}
```

## <strong>API_KEY</strong> incorreta

Caso a API_KEY enviada não corresponda a API_KEY apresentada no front QI Tech após o cadastro de chaves o seguinte retorno será apresentado:

STATUS 404

Response Body

```json
  {
  	"code": "GDF000018",
  	"title": "Not Found",
  	"description": "No ClientIntegration found for api_client_key: {api_client_key}.",
  	"translation": "Nenhuma ClientIntegration encontrada para api_client_key: {api_client_key}."
  }
```

## Endpoint não autorizado

Caso o endpoint ou método acessado não esteja autorizado o seguinte erro será retornado:

STATUS 401

Response Body

```json
{
	"title": "QI Unauthenticated",
	"description": "Please provide valid credentials as part of the request. (Documentation: https://qitech.com.br/documentation) Details: Endpoint or HTTP method not allowed for the given ClientIntegration (Action: POST /debt)",
	"translation": "Por favor forneça credenciais válidas como parte da request. (Documentação: https://qitech.com.br/documentation) Detalhes: Endpoint ou método HTTP não permitido para a ClientIntegration fornecida (Action: POST /debt)",
	"code": "GDF000014"
}
```

:::caution Atenção!

Para requisitar acesso ao endpoint que retornou o erro referido, é necessário solicitar a liberação ao time de suporte QI Tech.
:::

---

# Exemplo completo de teste de autenticação

URL: /documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_completo

:::info Veja também
- [Teste de autenticação passo a passo](./teste_de_autenticacao_v2)
- [Endpoints de teste](./endpoints_de_teste)
- [Possíveis erros](./possiveis_erros)
:::

### Visão Geral
Esta documentação detalha o processo de assinatura e encriptação de cabeçalhos para autenticação segura em requisições à nossa API. O processo garante que as requisições sejam confiáveis e seguras, prevenindo acessos não autorizados e garantindo a integridade dos dados.

:::caution Atenção!

O hash md5 de requisições dos métodos GET e DELETE deve ser gerado com o payload vazio
:::

**Python**

```python
#Aqui, importamos as bibliotecas necessárias ao longo do processo de autenticação.
from jose import jwt
import json
from datetime import datetime
from hashlib import md5
import requests

def get_auth_header(endpoint, method, CLIENT_PRIVATE_KEY, API_KEY, request_body=None):

    if request_body is None:
        request_body = {}

    #O objeto de data e hora informado deve estar em UTC e deve seguir o padrão da norma internacional ISO 8601 ("2023-06-26T19:48:32.759844Z")
    timestamp = datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S.%fZ")

    #Definimos o algoritmo de codificação JWT
    jwt_header = {
        "typ": "JWT",
        "alg": "ES512"
    }

    #Construir hash em MD5 para assinatura no cabeçalho (header) utilizando o payload
    json_body = json.dumps(request_body)
    md5_hash = md5(json_body.encode()).hexdigest()

    #Essas são as infromações necessárias para assinatura do cabeçalho
    jwt_body = {
        "payload_md5": md5_hash,
        "timestamp": timestamp,
        "method": method,
        "uri": endpoint
    }

    #Realizar criptografia do header
    encoded_header_token = jwt.encode(
        claims=jwt_body,
        key=CLIENT_PRIVATE_KEY,
        algorithm="ES512",
        headers=jwt_header
    )

    #Montar header assinado
    signed_header = {
        "AUTHORIZATION": encoded_header_token,
        "API-CLIENT-KEY": API_KEY
    }

    return signed_header

if __name__ == "__main__":

    #Utilizaremos as variáveis base_url, endpoint, method e request_body. Neste exemplo faremos um POST no endpoint "/test".
    #As chaves contidas neste exemplo são apenas para fins de demonstração. Por favor, utilize suas próprias chaves.
    CLIENT_PRIVATE_KEY = "SUA PRIVATE KEY AQUI"
    API_KEY = "SUA API KEY AQUI"

    BASE_URL = "https://api-auth.sandbox.qitech.app"
    METHOD = "POST" #GET ou POST
    REQUEST_BODY = {
        "name": "QI Tech"
    }

    #Para fazer um GET na /test, é necessário inserir a API key ao final, enquanto para fazer um POST no mesmo endpoint, não é necessário
    if METHOD == 'GET':
        ENDPOINT = f"/test/{API_KEY}"
        signed_header = get_auth_header(ENDPOINT, METHOD, CLIENT_PRIVATE_KEY, API_KEY)
        response = requests.get(f"{BASE_URL}{ENDPOINT}", headers=signed_header)
    else:
        ENDPOINT = f"/test/"
        signed_header = get_auth_header(ENDPOINT, METHOD, CLIENT_PRIVATE_KEY, API_KEY, REQUEST_BODY)
        response = requests.post(f"{BASE_URL}{ENDPOINT}", json=REQUEST_BODY, headers=signed_header)

    print(response.status_code)
    print(response.json())
```

**PHP**

```php
<?php
require __DIR__ . '/vendor/autoload.php';

//Aqui, importamos as bibliotecas necessárias ao longo do processo de autenticação.
use Jose\Component\Core\AlgorithmManager;
use Jose\Component\Signature\JWSTokenSupport;
use Jose\Component\Signature\Algorithm\ES512;
use Jose\Component\Signature\Serializer\CompactSerializer;
use Jose\Component\KeyManagement\JWKFactory;
use Jose\Component\Signature\JWSBuilder;

function get_auth_header($endpoint, $method, $privateKeyString, $api_key, $request_body = null) {

    if ($request_body === null) {
        $request_body = (object)[];
    }

    //O objeto de data e hora informado deve estar em UTC e deve seguir o padrão da norma internacional ISO 8601 ("2023-06-26T19:48:32.759844Z")
    $microtime_float = microtime(true);
    $datetime = new DateTimeImmutable('@' . floor($microtime_float), new DateTimeZone('UTC'));
    $timestamp = $datetime->format('Y-m-d\TH:i:s.') . sprintf('%06d', ($microtime_float - floor($microtime_float)) * 1000000) . 'Z';

    //Definimos o algoritmo de codificação JWT
    $header = [
        "typ" => "JWT",
        "alg" => "ES512"
    ];

    //Construir hash em MD5 para assinatura no cabeçalho (header) utilizando o payload
    $request_body_json = json_encode($request_body);
    $md5_hash = md5($request_body_json);

    //Essas são as infromações necessárias para assinatura do cabeçalho
    $payload = [
        "payload_md5" => $md5_hash,
        "timestamp" => $timestamp,
        "method" => $method,
        "uri" => $endpoint
    ];

    // Inicializar Algorithm Manager com ES512
    $algorithmManager = new AlgorithmManager([
        new ES512(),
    ]);

    // Inicializar JWS Builder
    $jwsBuilder = new JWSBuilder(
        $algorithmManager,
        new JWSTokenSupport()
    );

    $privateKey = JWKFactory::createFromKey($privateKeyString);

    //Realizar criptografia do header
    $jws = $jwsBuilder
        ->create()
        ->withPayload(json_encode($payload))
        ->addSignature($privateKey, $header)
        ->build();

    $serializer = new CompactSerializer();
    $jwt = $serializer->serialize($jws, 0);

    //Montar header assinado
    $headers = [
        'Authorization' => $jwt,
        'API-CLIENT-KEY' => $api_key,
    ];

    return $headers;
}

if (php_sapi_name() == 'cli' || (isset($_SERVER['REQUEST_METHOD']) && realpath($_SERVER['SCRIPT_FILENAME']) === __FILE__)) {
    
    //Utilizaremos as variáveis base_url, endpoint, method e request_body. Neste exemplo faremos um POST no endpoint "/test".
    $base_url = "https://api-auth.sandbox.qitech.app";
    $method = "POST"; // HTTP method: "GET" or "POST"

    $request_body = ["name" => "QI Tech"];

    //As chaves contidas neste exemplo são apenas para fins de demonstração. Por favor, utilize suas próprias chaves.
    $api_key = "SUA API KEY AQUI";
    $privateKeyString = "SUA PRIVATE KEY AQUI";

    $response = null;

    #Para fazer um GET na /test, é necessário inserir a API key ao final, enquanto para fazer um POST no mesmo endpoint, não é necessário
    if ($method == 'GET') {
        $endpoint = "/test/" . $api_key;
        $headers = get_auth_header($endpoint, $method, $privateKeyString, $api_key);
        $url = $base_url . $endpoint;
        $response = \WpOrg\Requests\Requests::get($url, $headers);
    } else {
        $endpoint = "/test";
        $headers = get_auth_header($endpoint, $method, $privateKeyString, $api_key, $request_body);
        $url = $base_url . $endpoint;
        $response = \WpOrg\Requests\Requests::post($url, $headers, json_encode($request_body));
    }

    if ($response) {
        echo "HTTP Status Code: " . $response->status_code . "\n";

        $json_response = json_decode($response->body, true);
        if (json_last_error() === JSON_ERROR_NONE) {
            echo "Response JSON:\n";
            print_r($json_response);
        } else {
            echo "Error decoding JSON. Raw Response Text:\n";
            echo $response->body . "\n";

    }
}
?>
```

**Node.js**

```js
//Aqui, importamos as bibliotecas necessárias ao longo do processo de autenticação.
const jwt = require('jsonwebtoken');
const crypto = require('crypto');
const axios = require('axios');

function getAuthHeader(endpoint, method, client_private_key, api_key, request_body = null) {
    if (request_body === null) {
        request_body = {};
    }

    //O objeto de data e hora informado deve estar em UTC e deve seguir o padrão da norma internacional ISO 8601 ("2023-06-26T19:48:32.759844Z")
    const now = new Date();
    const isoString = now.toISOString();
    const timestamp = isoString.slice(0, -1) + (now.getMilliseconds() * 1000).toString().padStart(6, '0').slice(0, 3) + 'Z';

    //Definimos o algoritmo de codificação JWT
    const jwt_header = {
        typ: 'JWT',
        alg: 'ES512'
    };

    //Construir hash em MD5 para assinatura no cabeçalho (header) utilizando o payload
    const str_body = JSON.stringify(request_body);
    const md5_hash = crypto.createHash('md5').update(str_body).digest('hex');

    //Essas são as infromações necessárias para assinatura do cabeçalho
    const jwt_body = {
        payload_md5: md5_hash,
        timestamp: timestamp,
        method: method,
        uri: endpoint
    };

    // Inicializar JWS Builder
    const encoded_header_token = jwt.sign(
        jwt_body,
        client_private_key,
        {
            algorithm: 'ES512',
            header: jwt_header
        }
    );

    //Realizar criptografia do header
    const signed_header = {
        'AUTHORIZATION': encoded_header_token,
        'API-CLIENT-KEY': api_key
    };

    return signed_header;
}
//Utilizaremos as variáveis BASE_URL, ENDPOINT, METHOD e REQUEST_BODY. Neste exemplo faremos um POST no endpoint "/test".
async function main() {
    const BASE_URL = "https://api-auth.sandbox.qitech.app";
    const METHOD = "POST"; //"POST" ou "GET"

    const REQUEST_BODY = {
        name: "QI Tech"
    };

    const API_KEY = "SUA API KEY AQUI";
    const CLIENT_PRIVATE_KEY = "SUA PRIVATE KEY AQUI";

    let ENDPOINT;
    let url;
    let signed_header;

    try {
    //Para fazer um GET na /test, é necessário inserir a API key ao final, enquanto para fazer um POST no mesmo endpoint, não é necessário
        if (METHOD === 'GET') {
            ENDPOINT = `/test/${API_KEY}`;
            url = `${BASE_URL}${ENDPOINT}`;
            signed_header = getAuthHeader(ENDPOINT, METHOD, CLIENT_PRIVATE_KEY, API_KEY);

            const response = await axios.get(url, { headers: signed_header });
            console.log("Status Code:", response.status);
            console.log("Response Body:", response.data);

        } else {
            ENDPOINT = "/test";
            url = `${BASE_URL}${ENDPOINT}`; // Corrected string interpolation
            signed_header = getAuthHeader(ENDPOINT, METHOD, CLIENT_PRIVATE_KEY, API_KEY, REQUEST_BODY);

            const response = await axios.post(url, REQUEST_BODY, { headers: signed_header });
            console.log("Status Code:", response.status);
            console.log("Response Body:", response.data);
        }
    } catch (error) {
        // More robust error handling for Axios
        if (error.response) {
            console.error("API Error - Status Code:", error.response.status);
            console.error("API Error - Response Data:", error.response.data);
            console.error("API Error - Headers:", error.response.headers);
        } else if (error.request) {
            console.error("Network Error: No response received from server.");
            console.error("Request:", error.request);
        } else {
            console.error("Error setting up request:", error.message);
        }
        console.error("Full Error Object:", error);
    }
}

main();
```

**Java**

```java
//Para Java precisaremos criar um arquivo com o nome de qitech-java-client
//Crie um arquivo chamado pom.xml e cole o final do código dentro dele
// Será necessário dentro do seu projeto criar algumas pastas - crie o seguinte path; src > main > java > com > qitech > api e insira seu arquivo java dentro com o nome de QItechApiClient.java
// Adicione sua private key no diretório raiz de seu projeto no mesmo nível que seu pom
// Para rodar o código abra o terminal ou comand prompt, navegue para a raiz de seu projeto e rode o seguinte código:
// mvn clean install exec:java

//Aqui, importamos as bibliotecas necessárias ao longo do processo de autenticação.
package com.qitech.api;

import com.google.gson.Gson;
import io.jsonwebtoken.JwtBuilder;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;
import org.bouncycastle.jce.provider.BouncyCastleProvider;

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.security.KeyFactory;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.security.PrivateKey;
import java.security.Security;
import java.security.spec.InvalidKeySpecException;
import java.security.spec.PKCS8EncodedKeySpec;
import java.text.SimpleDateFormat;
import java.util.Base64;
import java.util.Collections;
import java.util.Date;
import java.util.HashMap;
import java.util.Map;
import java.util.TimeZone;
import java.util.concurrent.TimeUnit;
import org.bouncycastle.jce.ECNamedCurveTable;
import org.bouncycastle.jce.spec.ECParameterSpec;
import org.bouncycastle.jce.spec.ECPrivateKeySpec;

public class QItechApiClient {

    public static Map<String, String> getAuthHeader(String endpoint, String method, PrivateKey privateKey, String apiKey, Map<String, Object> requestBody) throws NoSuchAlgorithmException {        
        //O objeto de data e hora informado deve estar em UTC e deve seguir o padrão da norma internacional ISO 8601 ("2023-06-26T19:48:32.759844Z")
        SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSSSSS'Z'");
        sdf.setTimeZone(TimeZone.getTimeZone("UTC"));
        String timestamp = sdf.format(new Date());

        //Construir hash em MD5 para assinatura no cabeçalho (header) utilizando o payload
        String jsonBody = jsonToString(requestBody);
        String md5Hash = md5Hash(jsonBody);

        //Essas são as infromações necessárias para assinatura do cabeçalho
        Map<String, Object> jwtBody = new HashMap<>();
        jwtBody.put("payload_md5", md5Hash);
        jwtBody.put("timestamp", timestamp);
        jwtBody.put("method", method);
        jwtBody.put("uri", endpoint);

        //Realizar criptografia do header
        JwtBuilder jwtBuilder = Jwts.builder()
                .setClaims(jwtBody)
                .signWith(privateKey, SignatureAlgorithm.ES512);
        String encodedHeaderToken = jwtBuilder.compact();

        //Montar header assinado
        Map<String, String> signedHeader = new HashMap<>();
        signedHeader.put("AUTHORIZATION", encodedHeaderToken);
        signedHeader.put("API-CLIENT-KEY", apiKey);

        return signedHeader;
    }

    public static void main(String[] args) {
        Security.addProvider(new BouncyCastleProvider());
        OkHttpClient client = null;

        try {

            //Utilizaremos as variáveis base_url, endpoint, method e request_body. Neste exemplo faremos um POST no endpoint "/test".
                //As chaves contidas neste exemplo são apenas para fins de demonstração. Por favor, utilize suas próprias chaves.
            final String BASE_URL = "https://api-auth.sandbox.qitech.app";
            final String PRIVATE_KEY_FILENAME = "private.key";

            final String API_CLIENT_KEY = "SUA API KEY AQUI";
            
            final String METHOD = "GET";  //GET ou POST
            final Map<String, Object> REQUEST_BODY = new HashMap<>();
            REQUEST_BODY.put("name", "QI Tech");

            
            String keyFromFile = readKeyFromFile(PRIVATE_KEY_FILENAME);
            PrivateKey privateKey = getPrivateKey(keyFromFile);

            String endpoint;
            Request request;

            //Para fazer um GET na /test, é necessário inserir a API key ao final, enquanto para fazer um POST no mesmo endpoint, não é necessário

            if ("GET".equalsIgnoreCase(METHOD)) {
                endpoint = "/test/" + API_CLIENT_KEY;

                Map<String, String> headers = getAuthHeader(endpoint, "GET", privateKey, API_CLIENT_KEY, Collections.emptyMap());

                request = new Request.Builder()
                        .url(BASE_URL + endpoint)
                        .headers(okhttp3.Headers.of(headers))
                        .get()
                        .build();

            } else {
                endpoint = "/test";

                Map<String, String> headers = getAuthHeader(endpoint, "POST", privateKey, API_CLIENT_KEY, REQUEST_BODY);

                RequestBody body = RequestBody.create(
                    jsonToString(REQUEST_BODY),
                    MediaType.parse("application/json; charset=utf-8")
                );

                request = new Request.Builder()
                        .url(BASE_URL + endpoint)
                        .headers(okhttp3.Headers.of(headers))
                        .post(body)
                        .build();
            }

            client = new OkHttpClient.Builder()
                    .connectTimeout(30, TimeUnit.SECONDS)
                    .readTimeout(30, TimeUnit.SECONDS)
                    .build();

            System.out.println("--- Sending " + METHOD + " Request ---");
            System.out.println("URL: " + BASE_URL + endpoint);

            try (Response response = client.newCall(request).execute()) {
                System.out.println("\n--- Received Response ---");
                System.out.println("Status Code: " + response.code());
                if (response.body() != null) {
                    System.out.println("Response Body: " + response.body().string());
                }
            }

        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            if (client != null) {
                client.dispatcher().executorService().shutdown();
                client.connectionPool().evictAll();
            }
        }
    }

    // --- Helper Methods ---
    
    private static String readKeyFromFile(String filename) throws IOException {
        String key = new String(Files.readAllBytes(Paths.get(filename)));
        return key.replace("-----BEGIN EC PRIVATE KEY-----", "")
                  .replace("-----END EC PRIVATE KEY-----", "")
                  .replace("-----BEGIN PRIVATE KEY-----", "")
                  .replace("-----END PRIVATE KEY-----", "")
                  .replaceAll("\\s", "");
    }

    private static String jsonToString(Map<String, Object> jsonMap) { return new Gson().toJson(jsonMap); }

    private static String md5Hash(String text) throws NoSuchAlgorithmException {
        MessageDigest md = MessageDigest.getInstance("MD5");
        byte[] array = md.digest(text.getBytes());
        StringBuilder sb = new StringBuilder();
        for (byte b : array) { sb.append(String.format("%02x", b)); }
        return sb.toString();
    }

    private static PrivateKey getPrivateKey(final String encodedPvKey) throws IOException {
        try {
            byte[] derBytes = Base64.getDecoder().decode(encodedPvKey);
            KeyFactory keyFactory = KeyFactory.getInstance("EC", BouncyCastleProvider.PROVIDER_NAME);
            try {
                return keyFactory.generatePrivate(new PKCS8EncodedKeySpec(derBytes));
            } catch (InvalidKeySpecException e) {
                org.bouncycastle.asn1.sec.ECPrivateKey sec1Key = org.bouncycastle.asn1.sec.ECPrivateKey.getInstance(derBytes);
                ECParameterSpec ecParameterSpec = ECNamedCurveTable.getParameterSpec("secp521r1");
                ECPrivateKeySpec privateKeySpec = new ECPrivateKeySpec(sec1Key.getKey(), ecParameterSpec);
                return keyFactory.generatePrivate(privateKeySpec);
            }
        } catch (Exception e) {
            throw new IOException("Failed to parse private key. Key is corrupted or not a valid EC key.", e);
        }
    }
}

////POM File

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.qitech.api</groupId>
    <artifactId>qitech-api-client</artifactId>
    <version>1.0.0</version>

    <properties>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <!-- HTTP Client -->
        <dependency>
            <groupId>com.squareup.okhttp3</groupId>
            <artifactId>okhttp</artifactId>
            <version>4.12.0</version>
        </dependency>

        <!-- JSON Web Token (JWT) Handling -->
        <dependency>
            <groupId>io.jsonwebtoken</groupId>
            <artifactId>jjwt-api</artifactId>
            <version>0.12.5</version>
        </dependency>
        <dependency>
            <groupId>io.jsonwebtoken</groupId>
            <artifactId>jjwt-impl</artifactId>
            <version>0.12.5</version>
            <scope>runtime</scope>
        </dependency>
        <dependency>
            <groupId>io.jsonwebtoken</groupId>
            <artifactId>jjwt-jackson</artifactId>
            <version>0.12.5</version>
            <scope>runtime</scope>
        </dependency>

        <!-- Cryptography Provider for ES512 -->
        <dependency>
            <groupId>org.bouncycastle</groupId>
            <artifactId>bcprov-jdk18on</artifactId>
            <version>1.78</version>
        </dependency>

        <!-- JSON Serialization -->
        <dependency>
            <groupId>com.google.code.gson</groupId>
            <artifactId>gson</artifactId>
            <version>2.10.1</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.13.0</version>
            </plugin>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>3.2.0</version>
                <configuration>
                    <mainClass>com.qitech.api.QItechApiClient</mainClass>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

```

**C#**

```c#
//Aqui, importamos as bibliotecas necessárias ao longo do processo de autenticação.
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Threading.Tasks;
using Jose;
using Newtonsoft.Json;

public static class QiTechAuthGenerator {
    public static string GetAuthorizationHeader(
        string endpoint,
        string method,
        string clientPrivateKey,
        object requestBody)
    {
        string privateKeyBase64 = clientPrivateKey 
            .Replace("-----BEGIN EC PRIVATE KEY-----", "")
            .Replace("-----END EC PRIVATE KEY-----", "")
            .Replace("\n", "")
            .Replace("\r", "");

        using var privateKey = ECDsa.Create();
        privateKey.ImportECPrivateKey(Convert.FromBase64String(privateKeyBase64), out _);

        string payloadToHash;

        if (method.ToUpper() == "GET") {
            payloadToHash = "{}";
        }
        else {
            payloadToHash = JsonConvert.SerializeObject(requestBody);
        }
        
        //Construir hash em MD5 para assinatura no cabeçalho (header) utilizando o payload
        var payloadMd5Hash = CalculateMd5Hash(payloadToHash);

        //Essas são as infromações necessárias para assinatura do cabeçalho
        var jwtBody = new Dictionary<string, object> {
            { "payload_md5", payloadMd5Hash },
            { "timestamp", timestamp },
            { "method", method },
            { "uri", endpoint }
        };

        //Definimos o algoritmo de codificação JWT
        var jwtHeader = new Dictionary<string, object> {
            { "typ", "JWT" },
            { "alg", "ES512" }
        };

        return JWT.Encode(jwtBody, privateKey, JwsAlgorithm.ES512, jwtHeader);
    }

    //Construir hash em MD5 para assinatura no cabeçalho (header) utilizando o payload
    private static string CalculateMd5Hash(string input) {
        using (var md5 = MD5.Create()) {
            byte[] inputBytes = Encoding.UTF8.GetBytes(input);
            byte[] hashBytes = md5.ComputeHash(inputBytes);

            var builder = new StringBuilder();
            foreach (var b in hashBytes) {
                builder.Append(b.ToString("x2"));
            }
            return builder.ToString();
        }
    }
}

public class QiTechApiClient {
    private readonly string _baseUrl;
    private readonly string _apiKey;
    private readonly string _clientPrivateKey;

    public QiTechApiClient(string baseUrl, string apiKey, string clientPrivateKey) {
        _baseUrl = baseUrl;
        _apiKey = apiKey;
        _clientPrivateKey = clientPrivateKey;
    }

    //Realizar criptografia do header
    public async Task<string> CallEndpointAsync(string endpoint, string method, object requestBody) {
        var signedHeader = QiTechAuthGenerator.GetAuthorizationHeader(
            endpoint,
            method,
            _clientPrivateKey,
            requestBody
        );

        var url = $"{_baseUrl}{endpoint}";

        //Montar header assinado
        using (var client = new HttpClient()) {
            client.DefaultRequestHeaders.Add("AUTHORIZATION", signedHeader);
            client.DefaultRequestHeaders.Add("API-CLIENT-KEY", _apiKey);

            HttpResponseMessage httpResponse;

            if (method.ToUpper() == "GET") {
                httpResponse = await client.GetAsync(url);
            }
            else {
                var jsonBody = JsonConvert.SerializeObject(requestBody);
                var content = new StringContent(jsonBody, Encoding.UTF8, "application/json");
                httpResponse = await client.PostAsync(url, content);
            }

            httpResponse.EnsureSuccessStatusCode();

            var responseContent = await httpResponse.Content.ReadAsStringAsync();

            return responseContent;
        }
    }
}

public class Program {
    public static async Task Main() {
        string response = "";
        
        //Utilizaremos as variáveis baseUrl, endpoint, method e requestBody. Neste exemplo faremos um POST no endpoint "/test".
        var baseUrl = "https://api-auth.sandbox.qitech.app";
        var method = "POST";
        var requestBody = new { name = "QI Tech" };
        
        //As chaves contidas neste exemplo são apenas para fins de demonstração. Por favor, utilize suas próprias chaves.
        var apiKey = "SUA API KEY AQUI";
        var clientPrivateKey = @"SUA PRIVATE KEY AQUI";

        try {
            var apiClient = new QiTechApiClient(baseUrl, apiKey, clientPrivateKey);

            //Para fazer um GET na /test, é necessário inserir a API key ao final, enquanto para fazer um POST no mesmo endpoint, não é necessário
            if (method.ToUpper() == "GET") {
                var endpoint = "/test/" + apiKey;
                response = await apiClient.CallEndpointAsync(endpoint, method, null);
            }
            else {
                var endpoint = "/test";
                response = await apiClient.CallEndpointAsync(endpoint, method, requestBody);
            }

            Console.WriteLine("\nAPI Response:");
            Console.WriteLine(response);
        }
        catch (HttpRequestException ex) {
            Console.WriteLine($"\nHTTP Error: {ex.Message}");
        }
        catch (Exception ex) {
            Console.WriteLine($"\nAn unexpected error occurred: {ex.Message}");
        }
    }
}
```

---

# Teste de autenticação

URL: /documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2

:::info Veja também
- [Exemplo completo de autenticação](./teste_de_autenticacao_completo)
- [Endpoints de teste](./endpoints_de_teste)
- [Possíveis erros](./possiveis_erros)
:::

## 1. Introdução e Configuração Inicial

### Visão Geral
Esta documentação detalha o processo de assinatura e encriptação de cabeçalhos para autenticação segura em requisições à nossa API. O processo garante que as requisições sejam confiáveis e seguras, prevenindo acessos não autorizados e garantindo a integridade dos dados.

### Importar Bibliotecas
Aqui, importamos as bibliotecas necessárias ao longo do processo de autenticação.

**Python**

```python
import json
import requests
from datetime import datetime, timezone
from hashlib import md5
from jose import jwt
```

**PHP**

```php
use Jose\Component\Core\AlgorithmManager;
use Jose\Component\Signature\JWSTokenSupport;
use Jose\Component\Signature\Algorithm\ES512;
use Jose\Component\Signature\Serializer\CompactSerializer;
use Jose\Component\Signature\JWSBuilder;
use Jose\Component\KeyManagement\JWKFactory;
```

**Node.js**

```js
const jose = require('jose');
const jwt = require('jsonwebtoken');
const crypto = require('crypto');
const axios = require('axios');
```

**Java**

```java
import io.jsonwebtoken.JwtBuilder;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

import java.io.IOException;
import java.io.StringReader;
import java.security.KeyPair;
import java.security.PrivateKey;
import java.util.Base64;
import java.util.Date;
import java.util.HashMap;
import java.util.Map;

import org.bouncycastle.openssl.PEMKeyPair;
import org.bouncycastle.openssl.PEMParser;
import org.bouncycastle.openssl.jcajce.JcaPEMKeyConverter;
```

**C#**

```c#
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using Jose;
using Newtonsoft.Json;
```

### Definir variáveis

Utilizaremos as variáveis _base_url_, _endpoint_, _method_ e _request_body_. Neste exemplo faremos um POST no endpoint "/test".

**Python**

```python
base_url = "https://api-auth.sandbox.qitech.app"
endpoint = "/test"
method = "POST"
request_body = {"name": "QI Tech"}
```
  

**PHP**

```php
$base_url = "https://api-auth.sandbox.qitech.app";
$endpoint = "/test";
$method = "POST";
$request_body = ["name" => "QI Tech"];
```
  

**Node.js**

```js
const base_url = 'https://api-auth.sandbox.qitech.app';
const endpoint = '/test';
const method = 'POST';
const request_body = { name: 'QI Tech' };
```
  

**Java**

```java
private static final String base_url = "https://api-auth.sandbox.qitech.app";
private static final String endpoint = "/test";
private static final String method = "POST";
private static final Map<String, Object> request_body = new HashMap<>();
static {
    request_body.put("name", "QI Tech");
}
```
  

**C#**

```c#
var base_url = "https://api-auth.sandbox.qitech.app";
var endpoint = "/test";
var method = "POST";
var request_body = new { name = "QI Tech" };

```
  

## 2. Preparação de Dados para Assinatura

### Inserir dados de criptografia

As chaves contidas neste exemplo são apenas para fins de demonstração. Por favor, utilize suas próprias chaves. 

**Python**

```python
api_key = "f19c6e62-bd82-4334-9839-020810550c44" 

client_private_key = '''-----BEGIN EC PRIVATE KEY-----
MIHbAgEBBEHh1hIeOPE5XNNhn6bxRAmVswsPZ0wZCmzVvP8Tl/LZK9ofVmRVGzll
srU1uezJEyHKYdOHrE2p52xUj+pHzjJvb6AHBgUrgQQAI6GBiQOBhgAEAAofUz1J
hBSOyGHLsnV9Sz0DSWmhl7U+ljqbfa8PKVFWSV3w16I1v2zME5/UzUhHn1gWsjnv
7/ekcLLAQbvqMPNXAfjIhFXLAPzqbB9iCuVua1v0Vgy52rBemOWrJka/Ws2bnKR8
h1N1OxOYeYr6C2jqMygBLktKMAs+282CEiEb4bIv
-----END EC PRIVATE KEY-----'''  
```
  

**PHP**

```php
$api_key = "f19c6e62-bd82-4334-9839-020810550c44"; 

$privateKeyString = "-----BEGIN EC PRIVATE KEY-----
MIHbAgEBBEHh1hIeOPE5XNNhn6bxRAmVswsPZ0wZCmzVvP8Tl/LZK9ofVmRVGzll
srU1uezJEyHKYdOHrE2p52xUj+pHzjJvb6AHBgUrgQQAI6GBiQOBhgAEAAofUz1J
hBSOyGHLsnV9Sz0DSWmhl7U+ljqbfa8PKVFWSV3w16I1v2zME5/UzUhHn1gWsjnv
7/ekcLLAQbvqMPNXAfjIhFXLAPzqbB9iCuVua1v0Vgy52rBemOWrJka/Ws2bnKR8
h1N1OxOYeYr6C2jqMygBLktKMAs+282CEiEb4bIv
-----END EC PRIVATE KEY-----"; 
```
  

**Node.js**

```js
const api_key = 'f19c6e62-bd82-4334-9839-020810550c44'; 

const client_private_key = `-----BEGIN EC PRIVATE KEY-----
MIHbAgEBBEHh1hIeOPE5XNNhn6bxRAmVswsPZ0wZCmzVvP8Tl/LZK9ofVmRVGzll
srU1uezJEyHKYdOHrE2p52xUj+pHzjJvb6AHBgUrgQQAI6GBiQOBhgAEAAofUz1J
hBSOyGHLsnV9Sz0DSWmhl7U+ljqbfa8PKVFWSV3w16I1v2zME5/UzUhHn1gWsjnv
7/ekcLLAQbvqMPNXAfjIhFXLAPzqbB9iCuVua1v0Vgy52rBemOWrJka/Ws2bnKR8
h1N1OxOYeYr6C2jqMygBLktKMAs+282CEiEb4bIv
-----END EC PRIVATE KEY-----`; 
```
  

**Java**

```java
private static final String clientPrivateKey = "MIHbAgEBBEHh1hIeOPE5XNNhn6bxRAmVswsPZ0wZCmzVvP8Tl/LZK9ofVmRVGzll
srU1uezJEyHKYdOHrE2p52xUj+pHzjJvb6AHBgUrgQQAI6GBiQOBhgAEAAofUz1J
hBSOyGHLsnV9Sz0DSWmhl7U+ljqbfa8PKVFWSV3w16I1v2zME5/UzUhHn1gWsjnv
7/ekcLLAQbvqMPNXAfjIhFXLAPzqbB9iCuVua1v0Vgy52rBemOWrJka/Ws2bnKR8
h1N1OxOYeYr6C2jqMygBLktKMAs+282CEiEb4bIv"; 
```
  

**C#**

```c#
var api_key = "f19c6e62-bd82-4334-9839-020810550c44"; 
var client_private_key = @"-----BEGIN EC PRIVATE KEY-----
MIHbAgEBBEHh1hIeOPE5XNNhn6bxRAmVswsPZ0wZCmzVvP8Tl/LZK9ofVmRVGzll
srU1uezJEyHKYdOHrE2p52xUj+pHzjJvb6AHBgUrgQQAI6GBiQOBhgAEAAofUz1J
hBSOyGHLsnV9Sz0DSWmhl7U+ljqbfa8PKVFWSV3w16I1v2zME5/UzUhHn1gWsjnv
7/ekcLLAQbvqMPNXAfjIhFXLAPzqbB9iCuVua1v0Vgy52rBemOWrJka/Ws2bnKR8
h1N1OxOYeYr6C2jqMygBLktKMAs+282CEiEb4bIv
-----END EC PRIVATE KEY-----"; 
```
  

### Formatar data
O objeto de data e hora informado deve estar em UTC e deve seguir o padrão da norma internacional ISO 8601 ("2023-06-26T19:48:32.759844Z")

**Python**

```python
timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
```
  

**PHP**

```php
$timestamp = gmdate('Y-m-d\TH:i:s.u\Z');
```
  

**Node.js**

```js
const timestamp = new Date().toISOString();
```
  

**Java**

```java
Date now = new Date();
SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSSSSS'Z'");
String formattedDate = sdf.format(now);
```
  

**C#**

```c#
var timestamp = datetime.now.ToString("yyyy-MM-ddTHH:mm:ss.fffZ");
```
  

### Definir cabeçalho JWT
Definimos o algoritmo de codificação JWT

**Python**

```python
jwt_header = {
    "typ": "JWT",
    "alg": "ES512"
}
```
  

**PHP**

```php
$header = [
    "typ" => "JWT",
    "alg" => "ES512"
];
```
  

**Node.js**

```js
const jwt_header = {
  typ: 'JWT',
  alg: 'ES512'
};
```
  

**Java**

```java
// Não é necessário
```
  

**C#**

```c#
var jwt_header = new Dictionary<string, object>
{ 
  { "typ", "JWT" },
  { "alg", "ES512" }
};
```
  

### Construir hash em MD5 para assinatura no cabeçalho JSON

Construir hash em MD5 para assinatura no cabeçalho (header) utilizando o payload

**Python**

```python
json_body = json.dumps(request_body)
md5_hash = md5(json_body.encode()).hexdigest()
```
  

**PHP**

```php
$request_body_json = json_encode($request_body);
$md5_hash = md5($request_body_json);
```
  

**Node.js**

```js
const str_body = JSON.stringify(request_body);
const md5_hash = crypto.createHash('md5').update(str_body).digest('hex');
```
  

**Java**

```java
String payloadMd5 = md5Hash(jsonToString(request_body));

...

private static String jsonToString(Map<String, Object> jsonMap) {
    return new com.google.gson.Gson().toJson(jsonMap);
}

...

private static String md5Hash(String text) {
    try {
        java.security.MessageDigest md = java.security.MessageDigest.getInstance("MD5");
        byte[] array = md.digest(text.getBytes());
        StringBuilder sb = new StringBuilder();
        for (byte b : array) {
            sb.append(String.format("%02x", b));
        }
        return sb.toString();
    } catch (java.security.NoSuchAlgorithmException e) {
        return null;
    }
}
```
  

**C#**

```c#
var json_body = JsonConvert.SerializeObject(request_body);
var md5_hash = CalculateMD5Hash(json_body);

.

static string CalculateMD5Hash(string input)
{
    using (MD5 md5 = MD5.Create())
    {
        byte[] inputBytes = Encoding.UTF8.GetBytes(input);
        byte[] hashBytes = md5.ComputeHash(inputBytes);

        StringBuilder builder = new StringBuilder();

        for (int i = 0; i < hashBytes.Length; i++)
        {
            builder.Append(hashBytes[i].ToString("x2"));
        }

        return builder.ToString();
    }
}
```
  

:::caution Atenção!

O hash md5 de requisições dos métodos GET e DELETE deve ser gerado com o payload vazio
:::

### Construir hash em MD5 para assinatura no cabeçalho Arquivo

Construir hash em MD5 para assinatura no cabeçalho (header) utilizando um arquivo

**Python**

```python
md5_instance = md5()
for chunk in iter(lambda: file.read(4096), b""):
    md5_instance.update(chunk)

file.seek(0)
md5_hash = md5_instance.hexdigest()
```

**PHP**

```php
$md5_instance = md5_file($file);
$md5_hash = hash_file('md5', $file);
```

**Node.js**

```js
const md5_instance = crypto.createHash('md5');
const readStream = fs.createReadStream(file);

readStream.on('data', (chunk) => {
  md5_instance.update(chunk);
});

readStream.on('end', () => {
  const md5_hash = md5_instance.digest('hex');
  file.seek(0);
```

**Java**

```java
MessageDigest md5_instance = MessageDigest.getInstance("MD5");
byte[] buffer = new byte[4096];
int bytesRead;

try (InputStream inputStream = new FileInputStream(file)) {
    while ((bytesRead = inputStream.read(buffer)) != -1) {
        md5_instance.update(buffer, 0, bytesRead);
    }
}

byte[] md5_hashBytes = md5_instance.digest();
StringBuilder md5_hashBuilder = new StringBuilder();

for (byte b : md5_hashBytes) {
    md5_hashBuilder.append(String.format("%02x", b));
}

String md5_hash = md5_hashBuilder.toString();
```

**C#**

```c#
using (var md5_instance = MD5.Create())
{
    using (var stream = File.OpenRead(file))
    {
        byte[] hash = md5_instance.ComputeHash(stream);
        string md5_hash = BitConverter.ToString(hash).Replace("-", "").ToLower();
        stream.Seek(0, SeekOrigin.Begin);
    }
}
```

### Definir o corpo do JWT
Essas são as infromações necessárias para assinatura do cabeçalho

**Python**

```python
jwt_body = {
    "payload_md5": md5_hash,
    "timestamp": timestamp,
    "method": method,
    "uri": endpoint
}
```
  

**PHP**

```php
$payload = [
    "payload_md5" => $md5_hash,
    "timestamp" => $timestamp,
    "method" => $method,
    "uri" => $endpoint
];
```
  

**Node.js**

```js
const jwt_body = {
  payload_md5: md5_hash,
  timestamp: timestamp,
  method: method,
  uri: endpoint
};
```
  

**Java**

```java
Map<String, Object> jwt_body = new HashMap<>();
jwt_body.put("payload_md5", payloadMd5);
jwt_body.put("timestamp", formattedDate);
jwt_body.put("method", method);
jwt_body.put("uri", endpoint);
```
  

**C#**

```c#
// Ajuste: Remover espaços e quebras de linha no meio da chave privada
client_private_key = client_private_key.Replace("-----BEGIN EC PRIVATE KEY-----", "")
                                       .Replace("-----END EC PRIVATE KEY-----", "")
                                       .Replace("\n", "")
                                       .Replace("\r", "");
// Converter a chave privada para ECDsa
using (ECDsa ecdsa = ECDsa.Create())
{
  ecdsa.ImportECPrivateKey(Convert.FromBase64String(client_private_key), out _);
  var jwt_body = new Dictionary<string, object>
    {
      { "payload_md5", md5_hash },
      { "timestamp", timestamp },
      { "method", method },
      { "uri", endpoint }
    };
```
  

### Realizar criptografia do header

**Python**

```python
encoded_header_token = jwt.encode(
    claims=jwt_body,
    key=client_private_key,
    algorithm="ES512",
    headers=jwt_header
)
```
  

**PHP**

```php
$jws = $jwsBuilder
    ->create()
    ->withPayload(json_encode($payload))
    ->addSignature($privateKey, $header)
    ->build();
$serializer = new CompactSerializer();
$jwt = $serializer->serialize($jws, 0);
```
  

**Node.js**

```js
const encoded_header_token = jwt.sign(
  jwt_body,
  client_private_key,
  {
    algorithm: 'ES512',
    header: jwt_header
  }
);
```
  

**Java**

```java
PrivateKey privateKey = getPrivateKey(clientPrivateKey);
JwtBuilder jwtBuilder = Jwts.builder().setClaims(jwt_body).signWith(privateKey, SignatureAlgorithm.ES512);
String encodedHeaderToken = jwtBuilder.compact();

...

public static PrivateKey getPrivateKey(final String encodedPvKey) {
    try {
        final String pvKey = new String(Base64.getDecoder().decode(encodedPvKey));
        PEMParser pemParser = new PEMParser(new StringReader(pvKey));
        PEMKeyPair pemKeyPair = (PEMKeyPair) pemParser.readObject();

        JcaPEMKeyConverter converter = new JcaPEMKeyConverter();
        KeyPair kp = converter.getKeyPair(pemKeyPair);
        pemParser.close();

        return kp.getPrivate();
    } catch (IOException e) {
        throw new RuntimeException("Couldn't load private key");
    }
}
```
  

**C#**

```c#
var encoded_header_token = JWT.Encode(jwt_body, ecdsa, JwsAlgorithm.ES512, jwt_header);
```
  

### Montar header assinado

**Python**

```python
signed_header = {
    "AUTHORIZATION": encoded_header_token,
    "API-CLIENT-KEY": api_key
}
```
  

**PHP**

```php
$headers = [
    'Authorization' => $jwt,
    'API-CLIENT-KEY' => $api_key,
];
```
  

**Node.js**

```js
const signed_header = {
  AUTHORIZATION: encoded_header_token,
  'API-CLIENT-KEY': api_key
};
```
  

**Java**

```java
Map<String, String> headers = new HashMap<>();
headers.put("AUTHORIZATION", encodedHeaderToken);
headers.put("API-CLIENT-KEY", api_key);
```
  

**C#**

```c#
using (var client = new HttpClient())
    client.DefaultRequestHeaders.Clear();
    client.DefaultRequestHeaders.Add("AUTHORIZATION", encoded_header_token);
    client.DefaultRequestHeaders.Add("API-CLIENT-KEY", api_key);
```
  

### Construir a URL da solicitação

**Python**

```python
url = f"{base_url}{endpoint}"
```
  

**PHP**

```php
$url = $base_url . $endpoint;
```
  

**Node.js**

```js
const url = `${base_url}${endpoint}`;
```
  

**Java**

```java
String requestUrl = base_url + endpoint;
```
  

**C#**

```c#
var url = $"{base_url}{endpoint}";
```
  

## 3. Realizar Requisição

**Python**

```python
post_test_response = requests.post(url=url, headers=signed_header, json=request_body)
```
  

**PHP**

```php
$response = \WpOrg\Requests\Requests::post($url, $headers, json_encode($request_body));
```
  

**Node.js**

```js
axios
  .post(url, request_body, { headers: signed_header })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error);
  });
```
  

**Java**

```java
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
okhttp3.RequestBody requestBody = RequestBody.create(mediaType, jsonToString(request_body));
Request request = new Request.Builder().url(requestUrl).headers(okhttp3.Headers.of(headers))
        .method(method, requestBody).build();
Response response = client.newCall(request).execute();

System.out.println(response.body().string());
```
  

**C#**

```c#
var content = new StringContent(json_body, Encoding.UTF8, "application/json");
var post_test_response = client.PostAsync(url, content).Result;
```

---

# Validação de Webhooks

URL: /documentation/primeiros_passos/teste_de_autenticacao/webhook_v2

:::info Veja também
- [Configurando Webhooks](/documentation/primeiros_passos/configurando_webhooks)
:::

## 1. Introdução e Preparação

### Visão Geral e Importância
Esta seção aborda como a QI Tech envia webhooks com headers assinados, destacando a importância de descriptografar e validar esses headers para garantir segurança nas comunicações.

### Formato das Requisições
As requisições de webhook serão enviadas para a [URL configurada para recebimento dos webhooks](/documentation/primeiros_passos/configurando_webhooks). Elas possuem um formato específico de headers e body, detalhado a seguir.

ENDPOINT URL configurada para recebimento dos webhooks
MÉTODO POST

Request Headers

```json
{
    "AUTHORIZATION": "eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkX21kNSI6IjRhNjAzZjBmMGU3ZGRkZTlkYTJhMGFkM2QzNDFmNzRiIiwidGltZXN0YW1wIjoiMjAyMy0wNi0zMFQxODo1MjoyNy44ODU3MzFaIiwibWV0aG9kIjoiUE9TVCIsInVyaSI6Ii90ZXN0In0.AcNiJqXDdVmlXSbPI6bH41n0KXz9JwVVMgo4Ivqsq5UZjM2WBOTWw3aAvIMAAhjK5OdrURD4cX3dbbnRgzxspUckANRt0hVHRKSkhROHBfZxuTXVfv8oYzwghwiO2MatPBsroC9Vxbh-DEVQJIBigtN9_D5bg8p2-mlVvoxou2I-EwZs",
    "API-CLIENT-KEY": "20d6a816-9d21-4e29-bbe5-2ffb3baacfe9"
}
```

Request Body

```json
{
    "body_sample": "Exemplo de webhook"
}
```

## 2. Configuração e Descriptografia

### Importar bibliotecas

Antes de começar a descriptografia e validação dos webhooks, é essencial importar as bibliotecas necessárias em sua linguagem de programação preferida. Estas bibliotecas facilitarão o trabalho com JWTs, criptografia e outros aspectos relacionados.

**Python**

```python
import json
from datetime import datetime, timedelta
from hashlib import md5
from jose import jwt
```

**PHP**

```php
use Jose\Component\Core\AlgorithmManager;
use Jose\Component\Signature\Algorithm\ES512;
use Jose\Component\Signature\JWSVerifier;
use Jose\Component\KeyManagement\JWKFactory;
use Jose\Component\Signature\Serializer\JWSSerializerManager;
use Jose\Component\Signature\Serializer\CompactSerializer;
```

**Node.js**

```js
const jwt = require('jsonwebtoken');
const crypto = require('crypto');
```

**Java**

```java
import io.jsonwebtoken.Claims;
import io.jsonwebtoken.Jwts;
import org.bouncycastle.jce.provider.BouncyCastleProvider;
import org.bouncycastle.util.io.pem.PemReader;
import java.io.IOException;
import java.io.Reader;
import java.io.StringReader;
import java.security.KeyFactory;
import java.security.NoSuchAlgorithmException;
import java.security.PublicKey;
import java.security.Security;
import java.security.spec.InvalidKeySpecException;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;
```

**C#**

```c#
using System;
using System.Collections.Generic;
using System.Security.Cryptography;
using System.Text;
using Newtonsoft.Json;
using Jose;
```

### Definir variáveis

Defina as variáveis necessárias para manipular os headers e o corpo do webhook. Isso inclui a chave pública fornecida pela QI Tech, utilizada para descriptografar e validar o webhook.

**Python**

```python
headers = {
    "AUTHORIZATION": "eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkX21kNSI6IjRhNjAzZjBmMGU3ZGRkZTlkYTJhMGFkM2QzNDFmNzRiIiwidGltZXN0YW1wIjoiMjAyMy0wNi0zMFQxODo1MjoyNy44ODU3MzFaIiwibWV0aG9kIjoiUE9TVCIsInVyaSI6Ii90ZXN0In0.AcNiJqXDdVmlXSbPI6bH41n0KXz9JwVVMgo4Ivqsq5UZjM2WBOTWw3aAvIMAAhjK5OdrURD4cX3dbbnRgzxspUckANRt0hVHRKSkhROHBfZxuTXVfv8oYzwghwiO2MatPBsroC9Vxbh-DEVQJIBigtN9_D5bg8p2-mlVvoxou2I-EwZs",
    "API-CLIENT-KEY": "20d6a816-9d21-4e29-bbe5-2ffb3baacfe9",
}
body = {"body_sample": "Exemplo de webhook"}
authorization = headers.get("AUTHORIZATION")
```

**PHP**

```php
$headers = [
    "AUTHORIZATION" => "eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkX21kNSI6IjRhNjAzZjBmMGU3ZGRkZTlkYTJhMGFkM2QzNDFmNzRiIiwidGltZXN0YW1wIjoiMjAyMy0wNi0zMFQxODo1MjoyNy44ODU3MzFaIiwibWV0aG9kIjoiUE9TVCIsInVyaSI6Ii90ZXN0In0.AcNiJqXDdVmlXSbPI6bH41n0KXz9JwVVMgo4Ivqsq5UZjM2WBOTWw3aAvIMAAhjK5OdrURD4cX3dbbnRgzxspUckANRt0hVHRKSkhROHBfZxuTXVfv8oYzwghwiO2MatPBsroC9Vxbh-DEVQJIBigtN9_D5bg8p2-mlVvoxou2I-EwZs",
    "API-CLIENT-KEY" => "20d6a816-9d21-4e29-bbe5-2ffb3baacfe9",
];
$body = ["body_sample" => "Exemplo de webhook"];
$authorization = $headers["AUTHORIZATION"];
```

**Node.js**

```js
const headers = {
  AUTHORIZATION: 'eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkX21kNSI6IjRhNjAzZjBmMGU3ZGRkZTlkYTJhMGFkM2QzNDFmNzRiIiwidGltZXN0YW1wIjoiMjAyMy0wNi0zMFQxODo1MjoyNy44ODU3MzFaIiwibWV0aG9kIjoiUE9TVCIsInVyaSI6Ii90ZXN0In0.AcNiJqXDdVmlXSbPI6bH41n0KXz9JwVVMgo4Ivqsq5UZjM2WBOTWw3aAvIMAAhjK5OdrURD4cX3dbbnRgzxspUckANRt0hVHRKSkhROHBfZxuTXVfv8oYzwghwiO2MatPBsroC9Vxbh-DEVQJIBigtN9_D5bg8p2-mlVvoxou2I-EwZs',
  'API-CLIENT-KEY': '20d6a816-9d21-4e29-bbe5-2ffb3baacfe9'
};
const body = { body_sample: 'Exemplo de webhook' };
```

**Java**

```java
String authorization = "eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkX21kNSI6IjRhNjAzZjBmMGU3ZGRkZTlkYTJhMGFkM2QzNDFmNzRiIiwidGltZXN0YW1wIjoiMjAyMy0wNi0zMFQxODo1MjoyNy44ODU3MzFaIiwibWV0aG9kIjoiUE9TVCIsInVyaSI6Ii90ZXN0In0.AcNiJqXDdVmlXSbPI6bH41n0KXz9JwVVMgo4Ivqsq5UZjM2WBOTWw3aAvIMAAhjK5OdrURD4cX3dbbnRgzxspUckANRt0hVHRKSkhROHBfZxuTXVfv8oYzwghwiO2MatPBsroC9Vxbh-DEVQJIBigtN9_D5bg8p2-mlVvoxou2I-EwZs";
```

**C#**

```c#
var headers = new Dictionary<string, string>()
{
    { "AUTHORIZATION", "eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkX21kNSI6IjRhNjAzZjBmMGU3ZGRkZTlkYTJhMGFkM2QzNDFmNzRiIiwidGltZXN0YW1wIjoiMjAyMy0wNi0zMFQxODo1MjoyNy44ODU3MzFaIiwibWV0aG9kIjoiUE9TVCIsInVyaSI6Ii90ZXN0In0.AcNiJqXDdVmlXSbPI6bH41n0KXz9JwVVMgo4Ivqsq5UZjM2WBOTWw3aAvIMAAhjK5OdrURD4cX3dbbnRgzxspUckANRt0hVHRKSkhROHBfZxuTXVfv8oYzwghwiO2MatPBsroC9Vxbh-DEVQJIBigtN9_D5bg8p2-mlVvoxou2I-EwZs" },
    { "API-CLIENT-KEY", "20d6a816-9d21-4e29-bbe5-2ffb3baacfe9" }
};

var body = new Dictionary<string, string>()
{
    { "body_sample", "Exemplo de webhook" }
};
```

### 2. Inserção de Dados de Criptografia e Realização da Descriptografia
Inserimos a chave pública fornecida pela QI Tech e realizamos a descriptografia do header do webhook. Essa chave é crucial para a descriptografia dos headers do webhook.

**Python**

```python
qi_public_key = """-----BEGIN PUBLIC KEY-----
{QI_PUBLIC_KEY}
-----END PUBLIC KEY-----"""
```

**PHP**

```php
$qiPublicKey = "-----BEGIN PUBLIC KEY-----
{QI_PUBLIC_KEY}
-----END PUBLIC KEY-----";
```

**Node.js**

```js
const qiPublicKey = `-----BEGIN PUBLIC KEY-----
{QI_PUBLIC_KEY}
-----END PUBLIC KEY-----`;
```

**Java**

```java
String publicKeyStr = "{QI_PUBLIC_KEY}";
```

**C#**

```c#
var authorization = headers["AUTHORIZATION"];

var qiPublicKey = @"-----BEGIN PUBLIC KEY-----
{QI_PUBLIC_KEY}
-----END PUBLIC KEY-----";
```

### Realizar descriptografia do header

O processo de descriptografia é essencial para verificar a autenticidade e integridade do webhook recebido.

**Python**

```python
try:
    decoded_header = jwt.decode(token=authorization, key=qi_public_key)
except:
    raise Exception("Decodification failed.")
```

**PHP**

```php
$algorithmManager = new AlgorithmManager([new ES512()]);
$jwsVerifier = new JWSVerifier($algorithmManager);
$publicKey = JWKFactory::createFromKey($qiPublicKey, null, ['use' => 'sig']);
$serializerManager = new JWSSerializerManager([new CompactSerializer]);
$jws = $serializerManager->unserialize($authorization);
$decodedHeader = json_decode($jws->getPayload(), true);
```

**Node.js**

```js
const decodedHeader = jwt.verify(authorization, qiPublicKey);
```

**Java**

```java
private static Claims validate(final String encodedBody, String publicKeyStr){
    try {
        Security.addProvider(new BouncyCastleProvider());

        final String pbKey = new String(Base64.getDecoder().decode(publicKeyStr));
        Reader rdr = new StringReader(pbKey);
        PemReader pemParser = new PemReader(rdr);

        X509EncodedKeySpec spec = new X509EncodedKeySpec(pemParser.readPemObject().getContent());
        KeyFactory kf = KeyFactory.getInstance("EC");

        PublicKey publicKey = kf.generatePublic(spec);
        return Jwts.parser().setSigningKey(publicKey).parseClaimsJws(encodedBody).getBody();
    }  catch (IOException | NoSuchAlgorithmException | InvalidKeySpecException e) {
        throw new IllegalStateException(e);
    }
}
```

**C#**

```c#
var key = ECDsa.Create();
key.ImportFromPem(qiPublicKey);
var decodedHeader = JWT.Decode<IDictionary<string, string>>(authorization, key);
```

## 3. Validação e Conclusão

### Realização de Validações

Após descriptografar o header, é importante realizar várias validações para garantir que o webhook é válido e seguro.

**Python**

```python
assert decoded_header.get("method") == "POST"
assert decoded_header.get("uri") == "/client_webhook_endpoint"
assert (
    decoded_header.get("payload_md5")
    == md5(json.dumps(body).encode()).hexdigest()
)
assert (
    (datetime.now() - timedelta(minutes=5))
    < datetime.strptime(decoded_header.get("timestamp"), "%Y-%m-%dT%H:%M:%S.%fZ")
    < (datetime.now() + timedelta(minutes=5))
)
```

**PHP**

```php
$method = $decodedHeader["method"];
$uri = $decodedHeader["uri"];
$payloadMd5 = $decodedHeader["payload_md5"];
$timestamp = $decodedHeader["timestamp"];

assert($method === "POST");
assert($uri === "/client_webhook_endpoint");
assert($payloadMd5 === md5(json_encode($body, JSON_UNESCAPED_SLASHES)));
assert(
    (new DateTime("now", new DateTimeZone("UTC")))->sub(new DateInterval("PT5M")) < DateTime::createFromFormat("Y-m-d\TH:i:s.u\Z", $timestamp) &&
    DateTime::createFromFormat("Y-m-d\TH:i:s.u\Z", $timestamp) < (new DateTime("now", new DateTimeZone("UTC")))->add(new DateInterval("PT5M"))
);
```

**Node.js**

```js
if (decodedHeader.method !== 'POST') {
    throw new Error('Invalid method');
  }
  
  if (decodedHeader.uri !== '/client_webhook_endpoint') {
    throw new Error('Invalid URI');
  }
  
  const payloadMd5 = crypto
    .createHash('md5')
    .update(JSON.stringify(body))
    .digest('hex');
    
  if (decodedHeader.payload_md5 !== payloadMd5) {
    throw new Error('Invalid payload MD5');
  }
  
  const timestamp = new Date(decodedHeader.timestamp);
  const currentDateTime = new Date();
  
  const fiveMinutesAgo = new Date(currentDateTime.getTime() - 5 * 60000);
  const fiveMinutesAhead = new Date(currentDateTime.getTime() + 5 * 60000);
  
  if (!(timestamp > fiveMinutesAgo && timestamp < fiveMinutesAhead)) {
    throw new Error('Invalid timestamp');
  }
```

**Java**

```java
Claims result = validate(authorization, publicKeyStr);
System.out.println(result);
System.out.println(result.get("method").equals("POST"));
System.out.println(result.get("uri").equals("/test"));
```

**C#**

```c#
var method = decodedHeader["method"];
var uri = decodedHeader["uri"];
var payloadMd5 = decodedHeader["payload_md5"];
var timestamp = DateTime.Parse(decodedHeader["timestamp"]);
timestamp = timestamp.ToUniversalTime();
var bodyJson = JsonConvert.SerializeObject(body, new JsonSerializerSettings
{
    NullValueHandling = NullValueHandling.Ignore,
    Formatting = Formatting.None
});

using (var md5Hash = MD5.Create())
{
    var calculatedMd5 = GetMd5Hash(md5Hash, bodyJson);
    if (payloadMd5 != calculatedMd5)
    {
        throw new Exception("Payload MD5 verification failed.");
    }
}

var currentTime = datetime.now;
var validTimeStart = currentTime.AddMinutes(-5);
var validTimeEnd = currentTime.AddMinutes(5);
if (timestamp < validTimeStart || timestamp > validTimeEnd)
{
    throw new Exception("Timestamp verification failed.");
}

...

static string GetMd5Hash(MD5 md5Hash, string input)
{
    byte[] data = md5Hash.ComputeHash(Encoding.UTF8.GetBytes(input));

    StringBuilder builder = new StringBuilder();
    for (int i = 0; i < data.Length; i++)
    {
        builder.Append(data[i].ToString("x2"));
    }

    return builder.ToString();
}
```

---

# Troca de chaves

URL: /documentation/primeiros_passos/troca_de_chaves

# Troca de chaves

---

# Consulta de valor presente de uma operação

URL: /documentation/refinanciamento/consulta_de_valor_presente_de_uma_operacao

Para descobrir o valor presente que será utilizado no refinanciamento de uma operação, é possível utilizar o endpoint de consulta de dívidas indicando 4 query params chave listados abaixo.

## Request

ENDPOINT /debt
MÉTODO GET

## Query Params
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `key` * | string | Chave da dívida devolvida no momento da criação da operação de crédito. | - |
| `eval_present_value` * | string | Indica que o valor atual de cada parcela deve ser calculado e mostrado. | - |
| `calculate_delay` * | string | Indica que, se a parcela estiver vencida, os juros de mora e multa devem ser calculados com o valor presente. | - |
| `calculate_spread` * | booleano | Indica se o valor de spread da operação deve ser adicionado ao valor presente (para operações de refinanciamento deve ser falso). | - |

## Response

STATUS 200

Response Body

```json
{
	"data": {
		"additional_iof": 11.547136,
		"after_disbursement_actions": [],
		"all_day_disbursement": true,
		"annual_cet": 41.0883,
		"assigned": false,
		"assigned_at": null,
		"assignment_amount": 3038.72,
		"attached_document_list": [{
			"created_at": "2022-10-19T11:53:01",
			"document_key": "5df59dca-b8d1-4dca-8358-8b4bd944f3dc",
			"document_type": {
				"enumerator": "document_identification",
				"translation_path": "co.DocumentType.document_identification"
			},
			"document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/5df59dca-b8d1-4dca-8358-8b4bd944f3dc/image_1666180300436.jpg",
			"related_party_key": null,
			"signature_required": false,
			"signature_url": null,
			"signed": false
		}],
		"balance_due": 3150.62,
		"base_iof": 27.17569413,
		"calculus_correction": null,
		"central_depository": null,
		"cet": 2.91,
		"cetip_assignments": [],
		"cetip_settlements": [],
		"collateral_constituted": true,
		"collateral_type": null,
		"collaterals": [],
		"contract_fee_amount": 0,
		"contract_fees": [],
		"contract_number": "TESTE118261",
		"created_at": "2022-10-19T11:53:00",
		"credit_operation_key": "438ceaa3-2906-4ee3-85f9-0dcacd5f2581",
		"credit_operation_status": {
			"enumerator": "opened",
			"translation_path": "co.CreditOperationStatus.opened",
			"translation_ptbr": "Desembolsada"
		},
		"credit_operation_type": {
			"enumerator": "ccb",
			"translation_path": "co.CreditOperationType.ccb"
		},
		"credit_rating": null,
		"creditor_bank_account_key": "5d068423-6094-49e4-b15b-7740038295a8",
		"custodian": {
			"enumerator": "qi_scd",
			"translation_path": "co.Custodian.qi_scd"
		},
		"decimal_annual_cet": 0.43241941956989105,
		"decimal_cet": 0.0304,
		"disburse_before_assign": true,
		"disbursed_at": "2022-10-19T11:54:47",
		"disbursed_issue_amount": 3000,
		"disbursement_account": [{
			"account_branch": "1234",
			"account_digit": "1",
			"account_number": "2345678601",
			"account_type": "checking_account",
			"amount_receivable": null,
			"created_at": "2022-10-19T11:53:01",
			"digitable_line": null,
			"disbursement_type": "pix",
			"document_number": "92147661180",
			"financial_institutions": {
				"code_number": 104,
				"is_active": true,
				"is_pix_participant": true,
				"ispb": 360305,
				"name": "CAIXA ECONOMICA FEDERAL"
			},
			"financial_institutions_code_number": 104,
			"is_pix_disbursement": true,
			"ispb": "00360305",
			"name": "104 CAIXA ECONOMICA FEDERAL",
			"percentage_receivable": 100,
			"pix_key": null,
			"pix_transfer_key": "da80477f-412e-40a5-81b0-c830b238081e",
			"pix_type": "manual",
			"qr_code_key": null,
			"retry_counter": 0,
			"retry_vector": null,
			"transaction_key": null,
			"webhook_key": null
		}],
		"disbursement_callback": {
			"installments": [{
				"bank_slip_key": "9d8c566a-c865-495e-8764-db8351e7ac41",
				"digitable_line": "32990001031000699925348000000207991730000055231",
				"due_date": "2022-11-18",
				"qr_code_key": "bdd41d56-8588-4468-9705-5233994cdc39",
				"qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/bdd41d56-8588-4468-9705-5233994cdc395204000053039865802BR5925QI SOCIEDADE DE CREDITO D6009Sao Paulo61080145200062070503***63044F44"
			}],
			"key": "438ceaa3-2906-4ee3-85f9-0dcacd5f2581",
			"origin_type": "lego-api",
			"status": "opened",
			"transaction_receipts": [{
				"amount": 3000,
				"description": "00360305 1234 2345678601-1 92147661180 - 104 CAIXA ECONOMICA FEDERAL",
				"destination": {
					"account_digit": "1",
					"account_number": "2345678601",
					"bank_ispb": "00360305",
					"branch": "1234",
					"branch_digit": null,
					"document": "92147661180",
					"name": "104 CAIXA ECONOMICA FEDERAL",
					"purpose": "Crédito PIX em Conta",
					"type": "checking_account"
				},
				"fee": 0,
				"origin": {
					"account_branch": "0001",
					"account_digit": "5",
					"account_key": "5d068423-6094-49e4-b15b-7740038295a8",
					"account_number": "00002",
					"bank_code": "329",
					"branch": "0001",
					"branch_digit": null,
					"document": "32402502000135",
					"name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
					"type": "payment_account"
				},
				"origin_transaction_key": null,
				"timestamp": "2022-10-19T11:55:03",
				"transaction_key": "da80477f-412e-40a5-81b0-c830b238081e"
			}]
		},
		"disbursement_confirmed_at": "2022-10-20T13:00:56",
		"disbursement_date": "2022-10-19",
		"disbursement_end_date": "2022-10-19",
		"disbursement_inelegibility_reason": null,
		"disbursement_inelegibility_reason_issued": null,
		"disbursement_options": [{
			"additional_iof": 11.547136,
			"annual_cet": 41.0883,
			"assignment_amount": 3038.72,
			"base_iof": 27.17569413,
			"calculus_correction": null,
			"cet": 2.91,
			"contract_fee_amount": 0,
			"contract_fees": [],
			"created_at": "2022-10-19T11:53:01",
			"disbursed_issue_amount": 3000,
			"disbursement_date": "2022-10-19",
			"external_contract_fee_amount": 0,
			"external_contract_fees": [],
			"first_due_date": "2022-11-18",
			"installments": [{
				"additional_costs": [],
				"business_due_date": "2022-11-21",
				"calendar_days": 30,
				"created_at": "2022-10-19T11:53:01",
				"due_date": "2022-11-18",
				"due_interest": 0,
				"due_principal": 3038.72,
				"fine_amount": null,
				"has_interest": true,
				"installment_number": 1,
				"post_fixed_amount": 0,
				"pre_fixed_amount": 75.66402982,
				"principal_amortization_amount": 476.64597018,
				"tax_amount": 1.17254909,
				"total_amount": 552.31,
				"workdays": 20
			}],
			"interest_subsidy_amount": 0,
			"issue_amount": 3038.72,
			"net_external_contract_fee_amount": 0,
			"prefixed_interest_rate": null,
			"share_quantity": 4,
			"total_iof": 38.72
		}],
		"disbursement_start_date": "2022-10-19",
		"document_certifier": {
			"enumerator": "electronic_client_side",
			"translation_path": "co.DocumentCertifier.electronic_client_side"
		},
		"early_settlement_configuration": {
			"created_at": "2022-10-19T11:53:00",
			"early_settlement_configuration_type": {
				"enumerator": "fixed_rate",
				"translation_path": "co.EarlySettlementConfigurationType.fixed_rate"
			},
			"effective_end_date": null,
			"fixed_interest_rate": 0
		},
		"endorsement": null,
		"entry": null,
		"events": [],
		"external_contract_fee_amount": 0,
		"external_contract_fees": [],
		"extra_fields": null,
		"facial_biometrics_enabled": false,
		"final_disbursement_amount": 3000,
		"financial_index": null,
		"fine_configuration": {
			"contract_fine_rate": 0.02,
			"created_at": "2022-10-19T11:53:00",
			"fine_delay_rate": {
				"annual_rate": 0.12682503,
				"created_at": "2022-10-19T11:53:00",
				"daily_rate": 0.00033173,
				"interest_base": {
					"enumerator": "calendar_days",
					"translation_path": "co.InterestBase.calendar_days",
					"year_days": 360
				},
				"monthly_rate": 0.01
			}
		},
		"first_due_date": "2022-11-18",
		"first_due_date_delay": null,
		"if_code": null,
		"installments": [{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0,
				"bank_slip_key": "9d8c566a-c865-495e-8764-db8351e7ac41",
				"business_due_date": "2022-11-21",
				"calendar_days": 30,
				"cetip_settlements": [],
				"created_at": "2022-10-19T11:53:00",
				"digitable_line": "32990001031000699925348000000207991730000055231",
				"due_date": "2022-11-18",
				"due_interest": 0,
				"due_principal": 3038.72,
				"events": [{
						"amount": null,
						"created_at": "2022-10-19T11:54:47",
						"event_date": "2022-10-19T11:54:47",
						"installment_event_type": {
							"enumerator": "open",
							"translation_path": "co.InstallmentEventType.open"
						},
						"installment_old_status": {
							"enumerator": "created",
							"translation_path": "co.InstallmentStatus.created"
						},
						"old_due_date": null
					},
					{
						"amount": null,
						"created_at": "2022-11-18T08:00:10",
						"event_date": "2022-11-18T08:00:10",
						"installment_event_type": {
							"enumerator": "maturity",
							"translation_path": "co.InstallmentEventType.maturity"
						},
						"installment_old_status": {
							"enumerator": "opened",
							"translation_path": "co.InstallmentStatus.opened"
						},
						"old_due_date": null
					},
					{
						"amount": 11.76,
						"created_at": "2022-11-22T08:00:14",
						"event_date": "2022-11-22T08:00:14",
						"installment_event_type": {
							"enumerator": "delay_fine",
							"translation_path": "co.InstallmentEventType.delay_fine"
						},
						"installment_old_status": {
							"enumerator": "waiting_payment",
							"translation_path": "co.InstallmentStatus.waiting_payment"
						},
						"old_due_date": null
					},
					{
						"amount": 11.94,
						"created_at": "2022-11-23T09:13:46",
						"event_date": "2022-11-23T09:13:46",
						"installment_event_type": {
							"enumerator": "delay_fine",
							"translation_path": "co.InstallmentEventType.delay_fine"
						},
						"installment_old_status": {
							"enumerator": "overdue",
							"translation_path": "co.InstallmentStatus.overdue"
						},
						"old_due_date": null
					},
					{
						"amount": 12.12,
						"created_at": "2022-11-24T09:15:55",
						"event_date": "2022-11-24T09:15:55",
						"installment_event_type": {
							"enumerator": "delay_fine",
							"translation_path": "co.InstallmentEventType.delay_fine"
						},
						"installment_old_status": {
							"enumerator": "overdue",
							"translation_path": "co.InstallmentStatus.overdue"
						},
						"old_due_date": null
					},
					{
						"amount": 12.3,
						"created_at": "2022-11-25T09:24:45",
						"event_date": "2022-11-25T09:24:44",
						"installment_event_type": {
							"enumerator": "delay_fine",
							"translation_path": "co.InstallmentEventType.delay_fine"
						},
						"installment_old_status": {
							"enumerator": "overdue",
							"translation_path": "co.InstallmentStatus.overdue"
						},
						"old_due_date": null
					},
					{
						"amount": 12.84,
						"created_at": "2022-11-28T09:37:41",
						"event_date": "2022-11-28T09:37:41",
						"installment_event_type": {
							"enumerator": "delay_fine",
							"translation_path": "co.InstallmentEventType.delay_fine"
						},
						"installment_old_status": {
							"enumerator": "overdue",
							"translation_path": "co.InstallmentStatus.overdue"
						},
						"old_due_date": null
					},
					{
						"amount": 13.02,
						"created_at": "2022-11-29T09:17:44",
						"event_date": "2022-11-29T09:17:44",
						"installment_event_type": {
							"enumerator": "delay_fine",
							"translation_path": "co.InstallmentEventType.delay_fine"
						},
						"installment_old_status": {
							"enumerator": "overdue",
							"translation_path": "co.InstallmentStatus.overdue"
						},
						"old_due_date": null
					}
				],
				"fine_amount": 13.02,
				"has_interest": true,
				"installment_key": "1d76836e-1fcc-4b67-8c01-64faa43de9c8",
				"installment_number": 1,
				"installment_payment": [],
				"installment_status": {
					"enumerator": "overdue",
					"translation_path": "co.InstallmentStatus.overdue"
				},
				"installment_type": {
					"enumerator": "principal",
					"translation_path": "co.InstallmentType.principal"
				},
				"original_due_principal": 3038.72,
				"original_pre_fixed_amount": 75.66402982,
				"original_principal_amortization_amount": 476.64597018,
				"original_total_amount": 552.31,
				"paid_amount": 0,
				"paid_at": null,
				"payment_type": {
					"enumerator": "bankslip",
					"translation_path": "co.PaymentType.bankslip"
				},
				"post_fixed_amount": 0,
				"pre_fixed_amount": 75.66402982,
				"principal_amortization_amount": 476.64597018,
				"qr_code_key": "bdd41d56-8588-4468-9705-5233994cdc39",
				"qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/bdd41d56-8588-4468-9705-5233994cdc395204000053039865802BR5925QI SOCIEDADE DE CREDITO D6009Sao Paulo61080145200062070503***63044F44",
				"renegotiation_proposal_key": null,
				"tax_amount": 1.17254909,
				"total_accrual_amount": null,
				"total_amount": 565.33,
				"total_paid_amount": 0,
				"updated_at": "2022-11-29T09:17:44",
				"workdays": 20,
				"present_amount": 1000.11
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0,
				"bank_slip_key": "527835e4-7b09-42f2-a7d0-befed3a326fd",
				"business_due_date": "2022-12-20",
				"calendar_days": 31,
				"cetip_settlements": [],
				"created_at": "2022-10-19T11:53:00",
				"digitable_line": "32990001031000699925349000000205492040000055231",
				"due_date": "2022-12-19",
				"due_interest": 0,
				"due_principal": 2562.07402982,
				"events": [{
					"amount": null,
					"created_at": "2022-10-19T11:54:47",
					"event_date": "2022-10-19T11:54:47",
					"installment_event_type": {
						"enumerator": "open",
						"translation_path": "co.InstallmentEventType.open"
					},
					"installment_old_status": {
						"enumerator": "created",
						"translation_path": "co.InstallmentStatus.created"
					},
					"old_due_date": null
				}],
				"fine_amount": null,
				"has_interest": true,
				"installment_key": "dde36938-8594-4507-a87d-cd2dd5309817",
				"installment_number": 2,
				"installment_payment": [],
				"installment_status": {
					"enumerator": "opened",
					"translation_path": "co.InstallmentStatus.opened"
				},
				"installment_type": {
					"enumerator": "principal",
					"translation_path": "co.InstallmentType.principal"
				},
				"original_due_principal": 2562.07402982,
				"original_pre_fixed_amount": 65.94922003,
				"original_principal_amortization_amount": 486.36077997,
				"original_total_amount": 552.31,
				"paid_amount": 0,
				"paid_at": null,
				"payment_type": {
					"enumerator": "bankslip",
					"translation_path": "co.PaymentType.bankslip"
				},
				"post_fixed_amount": 0,
				"pre_fixed_amount": 65.94922003,
				"principal_amortization_amount": 486.36077997,
				"qr_code_key": "9d2980e9-fa0c-4b21-a7c5-5ca266c9aba8",
				"qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/9d2980e9-fa0c-4b21-a7c5-5ca266c9aba85204000053039865802BR5925QI SOCIEDADE DE CREDITO D6009Sao Paulo61080145200062070503***6304FBC3",
				"renegotiation_proposal_key": null,
				"tax_amount": 2.43277662,
				"total_accrual_amount": null,
				"total_amount": 552.31,
				"total_paid_amount": 0,
				"updated_at": "2022-10-19T11:56:43",
				"workdays": 21,
				"present_amount": 1000.11
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0,
				"bank_slip_key": "d69c9ab6-01f1-40bb-9519-a06ee2230c22",
				"business_due_date": "2023-01-19",
				"calendar_days": 30,
				"cetip_settlements": [],
				"created_at": "2022-10-19T11:53:00",
				"digitable_line": "32990001031000699925350000000203192340000055231",
				"due_date": "2023-01-18",
				"due_interest": 0,
				"due_principal": 2075.71324985,
				"events": [{
					"amount": null,
					"created_at": "2022-10-19T11:54:47",
					"event_date": "2022-10-19T11:54:47",
					"installment_event_type": {
						"enumerator": "open",
						"translation_path": "co.InstallmentEventType.open"
					},
					"installment_old_status": {
						"enumerator": "created",
						"translation_path": "co.InstallmentStatus.created"
					},
					"old_due_date": null
				}],
				"fine_amount": null,
				"has_interest": true,
				"installment_key": "93273ee0-71bd-46a6-b5e2-39e03a365b16",
				"installment_number": 3,
				"installment_payment": [],
				"installment_status": {
					"enumerator": "opened",
					"translation_path": "co.InstallmentStatus.opened"
				},
				"installment_type": {
					"enumerator": "principal",
					"translation_path": "co.InstallmentType.principal"
				},
				"original_due_principal": 2075.71324985,
				"original_pre_fixed_amount": 51.68519286,
				"original_principal_amortization_amount": 500.62480714,
				"original_total_amount": 552.31,
				"paid_amount": 0,
				"paid_at": null,
				"payment_type": {
					"enumerator": "bankslip",
					"translation_path": "co.PaymentType.bankslip"
				},
				"post_fixed_amount": 0,
				"pre_fixed_amount": 51.68519286,
				"principal_amortization_amount": 500.62480714,
				"qr_code_key": "d79eb27b-7a1e-4d4c-94a1-f20045c4904e",
				"qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/d79eb27b-7a1e-4d4c-94a1-f20045c4904e5204000053039865802BR5925QI SOCIEDADE DE CREDITO D6009Sao Paulo61080145200062070503***6304E949",
				"renegotiation_proposal_key": null,
				"tax_amount": 3.73566231,
				"total_accrual_amount": null,
				"total_amount": 552.31,
				"total_paid_amount": 0,
				"updated_at": "2022-10-19T11:56:43",
				"workdays": 22,
				"present_amount": 1000.11
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0,
				"bank_slip_key": "5c62c50f-5326-4226-b154-a0cc6d2f62e7",
				"business_due_date": "2023-02-23",
				"calendar_days": 35,
				"cetip_settlements": [],
				"created_at": "2022-10-19T11:53:00",
				"digitable_line": "32990001031000699925351000000201192690000055231",
				"due_date": "2023-02-22",
				"due_interest": 0,
				"due_principal": 1575.08844271,
				"events": [{
					"amount": null,
					"created_at": "2022-10-19T11:54:47",
					"event_date": "2022-10-19T11:54:47",
					"installment_event_type": {
						"enumerator": "open",
						"translation_path": "co.InstallmentEventType.open"
					},
					"installment_old_status": {
						"enumerator": "created",
						"translation_path": "co.InstallmentStatus.created"
					},
					"old_due_date": null
				}],
				"fine_amount": null,
				"has_interest": true,
				"installment_key": "1f7b16fe-04b6-4f07-a807-eb3501e44e0d",
				"installment_number": 4,
				"installment_payment": [],
				"installment_status": {
					"enumerator": "opened",
					"translation_path": "co.InstallmentStatus.opened"
				},
				"installment_type": {
					"enumerator": "principal",
					"translation_path": "co.InstallmentType.principal"
				},
				"original_due_principal": 1575.08844271,
				"original_pre_fixed_amount": 45.8505547,
				"original_principal_amortization_amount": 506.4594453,
				"original_total_amount": 552.31,
				"paid_amount": 0,
				"paid_at": null,
				"payment_type": {
					"enumerator": "bankslip",
					"translation_path": "co.PaymentType.bankslip"
				},
				"post_fixed_amount": 0,
				"pre_fixed_amount": 45.8505547,
				"principal_amortization_amount": 506.4594453,
				"qr_code_key": "b55464c8-3764-4ee2-a814-ce22396aabe7",
				"qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/b55464c8-3764-4ee2-a814-ce22396aabe75204000053039865802BR5925QI SOCIEDADE DE CREDITO D6009Sao Paulo61080145200062070503***63044215",
				"renegotiation_proposal_key": null,
				"tax_amount": 5.23273899,
				"total_accrual_amount": null,
				"total_amount": 552.31,
				"total_paid_amount": 0,
				"updated_at": "2022-10-19T11:56:43",
				"workdays": 23,
				"present_amount": 1000.11
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0,
				"bank_slip_key": "256be15f-dcc6-4775-8298-c3efde5a1147",
				"business_due_date": "2023-03-21",
				"calendar_days": 26,
				"cetip_settlements": [],
				"created_at": "2022-10-19T11:53:00",
				"digitable_line": "32990001031000699925352000000209192950000055231",
				"due_date": "2023-03-20",
				"due_interest": 0,
				"due_principal": 1068.62899741,
				"events": [{
					"amount": null,
					"created_at": "2022-10-19T11:54:47",
					"event_date": "2022-10-19T11:54:47",
					"installment_event_type": {
						"enumerator": "open",
						"translation_path": "co.InstallmentEventType.open"
					},
					"installment_old_status": {
						"enumerator": "created",
						"translation_path": "co.InstallmentStatus.created"
					},
					"old_due_date": null
				}],
				"fine_amount": null,
				"has_interest": true,
				"installment_key": "3ed37dc1-61f8-44f1-af21-a55f0cf0795d",
				"installment_number": 5,
				"installment_payment": [],
				"installment_status": {
					"enumerator": "opened",
					"translation_path": "co.InstallmentStatus.opened"
				},
				"installment_type": {
					"enumerator": "principal",
					"translation_path": "co.InstallmentType.principal"
				},
				"original_due_principal": 1068.62899741,
				"original_pre_fixed_amount": 23.02305805,
				"original_principal_amortization_amount": 529.28694195,
				"original_total_amount": 552.31,
				"paid_amount": 0,
				"paid_at": null,
				"payment_type": {
					"enumerator": "bankslip",
					"translation_path": "co.PaymentType.bankslip"
				},
				"post_fixed_amount": 0,
				"pre_fixed_amount": 23.02305805,
				"principal_amortization_amount": 529.28694195,
				"qr_code_key": "64e05528-83fb-432a-8af7-491ca4eb7b90",
				"qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/64e05528-83fb-432a-8af7-491ca4eb7b905204000053039865802BR5925QI SOCIEDADE DE CREDITO D6009Sao Paulo61080145200062070503***630472F7",
				"renegotiation_proposal_key": null,
				"tax_amount": 6.59703244,
				"total_accrual_amount": null,
				"total_amount": 552.31,
				"total_paid_amount": 0,
				"updated_at": "2022-10-19T11:56:43",
				"workdays": 18,
				"present_amount": 1000.11
			},
			{
				"accrual_reference_date": null,
				"additional_costs": [],
				"advanced_paid_amount": 0,
				"bank_slip_key": "a8c2edaa-ed3d-4c5b-808e-b26947a5e79e",
				"business_due_date": "2023-04-19",
				"calendar_days": 29,
				"cetip_settlements": [],
				"created_at": "2022-10-19T11:53:01",
				"digitable_line": "32990001031000699925353000000207293240000055232",
				"due_date": "2023-04-18",
				"due_interest": 0,
				"due_principal": 539.34205545,
				"events": [{
					"amount": null,
					"created_at": "2022-10-19T11:54:47",
					"event_date": "2022-10-19T11:54:47",
					"installment_event_type": {
						"enumerator": "open",
						"translation_path": "co.InstallmentEventType.open"
					},
					"installment_old_status": {
						"enumerator": "created",
						"translation_path": "co.InstallmentStatus.created"
					},
					"old_due_date": null
				}],
				"fine_amount": null,
				"has_interest": true,
				"installment_key": "2b58b2be-89cd-4710-a6a5-81180938b501",
				"installment_number": 6,
				"installment_payment": [],
				"installment_status": {
					"enumerator": "opened",
					"translation_path": "co.InstallmentStatus.opened"
				},
				"installment_type": {
					"enumerator": "principal",
					"translation_path": "co.InstallmentType.principal"
				},
				"original_due_principal": 539.34205545,
				"original_pre_fixed_amount": 12.97660456,
				"original_principal_amortization_amount": 539.34339544,
				"original_total_amount": 552.32,
				"paid_amount": 0,
				"paid_at": null,
				"payment_type": {
					"enumerator": "bankslip",
					"translation_path": "co.PaymentType.bankslip"
				},
				"post_fixed_amount": 0,
				"pre_fixed_amount": 12.97660456,
				"principal_amortization_amount": 539.34339544,
				"qr_code_key": "dcc7d257-e6a1-4d0a-88f7-1acf662482b5",
				"qr_code_url": "00020126970014br.gov.bcb.pix2575qrcode-h.sandbox.qitech.app/bacen/cobv/dcc7d257-e6a1-4d0a-88f7-1acf662482b55204000053039865802BR5925QI SOCIEDADE DE CREDITO D6009Sao Paulo61080145200062070503***6304C9A1",
				"renegotiation_proposal_key": null,
				"tax_amount": 8.00493468,
				"total_accrual_amount": null,
				"total_amount": 552.32,
				"total_paid_amount": 0,
				"updated_at": "2022-10-19T11:56:43",
				"workdays": 20,
				"present_amount": 1000.11
			}
		],
		"interest_grace_period": 0,
		"interest_payment_month_period": 1,
		"interest_subsidy_amount": 0,
		"interest_subsidy_percentage": 0,
		"interest_type": {
			"enumerator": "pre_price_days",
			"translation_path": "co.InterestType.pre_price_days"
		},
		"iof_charge_method": "financed",
		"ipoc_code": "324025020203192147661180DiDi118261",
		"is_allowed_to_disburse": true,
		"is_portability": false,
		"is_refinancing": 0,
		"isin_number": null,
		"issue_amount": 3038.72,
		"issue_date": "2022-10-19",
		"issuer_document_number": "92147661180",
		"issuer_name": "Wxy  Wsx",
		"kyc": null,
		"modality": {
			"code": "0203",
			"description": "crédito pessoal - sem consignação em folha de pagam.",
			"enumerator": null,
			"visible": true
		},
		"net_external_contract_fee_amount": 0,
		"next_due_date": "2022-12-19",
		"number_of_installments": 6,
		"operation_extra_fields": null,
		"operation_type": {
			"enumerator": "structured_operation",
			"translation_path": "co.OperationType.structured_operation"
		},
		"origin_key": "438ceaa3-2906-4ee3-85f9-0dcacd5f2581",
		"origin_type": {
			"enumerator": "lego-api",
			"translation_path": "co.OriginType.lego-api"
		},
		"original_prefixed_interest_rate": {
			"annual_rate": 0.34331516,
			"created_at": "2022-10-19T11:53:00",
			"daily_rate": 0.00082017,
			"interest_base": {
				"enumerator": "calendar_days",
				"translation_path": "co.InterestBase.calendar_days",
				"year_days": 360
			},
			"monthly_rate": 0.0249
		},
		"original_total_iof": 38.72,
		"payment_and_settlement_agent": {
			"enumerator": "qi_scd",
			"translation_path": "co.PaymentAndSettlementAgent.qi_scd"
		},
		"payment_type": {
			"enumerator": "bankslip",
			"translation_path": "co.PaymentType.bankslip"
		},
		"payroll_data": null,
		"portability_amount": null,
		"portability_financial_institution_code_number": null,
		"portability_original_contract": null,
		"post_fixed_interest_base": {
			"enumerator": "workdays",
			"translation_path": "co.InterestBase.workdays",
			"year_days": 252
		},
		"post_fixed_interest_rate": null,
		"prefixed_interest_rate": {
			"annual_rate": 0.34331516,
			"created_at": "2022-10-19T11:53:00",
			"daily_rate": 0.00082017,
			"interest_base": {
				"enumerator": "calendar_days",
				"translation_path": "co.InterestBase.calendar_days",
				"year_days": 360
			},
			"monthly_rate": 0.0249
		},
		"principal_amortization_month_period": 1,
		"principal_grace_period": 0,
		"purchaser_document_number": "32402502000135",
		"rebate_account": null,
		"refinanced_credit_operations": [],
		"registration_institution": {
			"enumerator": "qi_scd",
			"translation_path": "co.RegistrationInstitution.qi_scd"
		},
		"related_party_list": [{
			"address": {
				"city": "Aguascalientes",
				"complement": null,
				"created_at": "2022-10-19T11:52:59",
				"neighborhood": "Aguascalientes",
				"number": "1",
				"postal_code": "20000000",
				"state": "SP",
				"street": "Zona Centro"
			},
			"attached_document_list": [{
				"created_at": "2022-10-19T11:53:01",
				"document_key": "5df59dca-b8d1-4dca-8358-8b4bd944f3dc",
				"document_type": {
					"enumerator": "document_identification",
					"translation_path": "co.DocumentType.document_identification"
				},
				"document_url": "https://storage.googleapis.com/sandbox-doc-api/documents/5df59dca-b8d1-4dca-8358-8b4bd944f3dc/image_1666180300436.jpg",
				"related_party_key": null,
				"signature_required": false,
				"signature_url": null,
				"signed": false
			}],
			"birth_date": "1997-10-19",
			"birth_place": null,
			"cnae_code": null,
			"company_document_number": null,
			"created_at": "2022-10-19T11:53:01",
			"document_identification_date": null,
			"document_identification_number": "",
			"document_identification_type": null,
			"email": "wxr@ff.com",
			"foundation_date": null,
			"gender": null,
			"income": 0.01,
			"individual_document_number": "92147661180",
			"is_pep": false,
			"marital_status": {
				"enumerator": "single",
				"translation_path": "co.MaritalStatus.single"
			},
			"mother_name": null,
			"name": "Wxy  Wsx",
			"nationality": "nationality",
			"person_type": "natural",
			"phone": {
				"area_code": "00",
				"country_code": "055",
				"created_at": "2022-10-19T11:53:00",
				"number": "016048311",
				"phone_key": "341d7c67-963c-49a5-b585-265425d71f52",
				"phone_type": null
			},
			"profession": null,
			"property_system": null,
			"related_party_key": "203b2ada-ff3e-44a6-a843-f244aa1afbc9",
			"revenue": null,
			"role_type": {
				"enumerator": "issuer",
				"translation_path": "co.RoleType.issuer"
			},
			"simples_nacional_participant": null,
			"spouse_document_number": null,
			"trading_name": null
		}],
		"requester_identifier_key": "89bb875a4a654ecfbad0c6ce0b3b5037",
		"requester_key": "75f2ab85-a5ce-40b9-9b1e-915175906d78",
		"requester_name": "DiDi Global (99Pay)",
		"resource_source_account": {
			"enumerator": "third_party",
			"translation_path": "co.ResourceSourceAccount.third_party"
		},
		"selfie_enabled": false,
		"settlement_bank_account_key": null,
		"share_quantity": 4,
		"signature_method": {
			"enumerator": "email"
		},
		"tax_configuration": {
			"created_at": "2019-03-15T13:09:32",
			"iof_additional_rate": 0.0038,
			"iof_rate": 0.000082
		},
		"tax_exempt_amount": null,
		"third_party_account_key": "5d068423-6094-49e4-b15b-7740038295a8",
		"total_iof": 38.72
	},
	"operation_key": "438ceaa3-2906-4ee3-85f9-0dcacd5f2581",
	"status": "opened",
	"webhook_type": "signed_debt"
}
```

:::caution Atenção!

Dentro do array de parcelas será retornado o valor presente calculado de cada parcela em **"present_amount"**, seu somatório será o valor presente considerado para o contrato no momento da solicitação do refinanciamento.
:::

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

---

# introducao

URL: /documentation/refinanciamento/introducao

Um refinanciamento consiste na geração de um novo contrato de crédito para a quitação de um anterior. Nesse sentido, seu fluxo funciona da mesma forma de uma emissão de dívidas simples, porém, quando informados os valores da operação, o somatório do valor presente dos contratos anteriores será retido e apenas o excedente, caso exista, será liberado na conta do tomador.

---

# Simulando um refinanciamento

URL: /documentation/refinanciamento/simulando_refinanciamento

## Request para uma Operação refinanciada não existente

ENDPOINT /debt_simulation
MÉTODO POST

Request Body

```json
{
  "complex_operation": true,
  "operation_batch": [
    {
      "borrower": {
        "person_type": "natural"
      },
     "refinanced_credit_operations": [
            {
                "original_deadline": 5,
                "monthly_interest_rate": "0.0133",
                "disbursement_date": "2024-06-30",
                "due_balance": 1050,
            }
    ],
      "financial": {
        "amount": 1900.83,
        "disbursement_amount": 800,
        "interest_type": "pre_price_days",
        "credit_operation_type": "ccb",
        "annual_interest_rate": 2.32,
        "disbursement_date": "2023-04-01",
        "interest_grace_period": 0,
        "principal_grace_period": 0,
        "number_of_installments": 2,
        "fine_configuration": {
          "contract_fine_rate": 0.02,
          "interest_base": "calendar_days",
          "monthly_rate": 0.01
        }
      }
    }
  ]
}
```
:::caution Atenção!

Os campos **"disbursement_date"** e **"monthly_interest_rate"** dentro do **"refinanced_credit_operations"** são obrigatórios apenas na necessidade de calcular o valor de quitação da operação refinanciada para as diversas opções de desembolso.
:::

## Request para uma Operação refinanciada já existente

ENDPOINT /debt_simulation
MÉTODO POST

Request Body

```json
{
  "complex_operation": true,
  "operation_batch": [
    {
      "borrower": {
        "person_type": "natural"
      },
     "refinanced_credit_operations": [
            {
                "operation_key": "a9630d51-f08f-4763-b269-c1947e97c260"
            }
    ],
      "financial": {
        "amount": 1900.83,
        "disbursement_amount": 800,
        "interest_type": "pre_price_days",
        "credit_operation_type": "ccb",
        "annual_interest_rate": 2.32,
        "disbursement_date": "2023-04-01",
        "interest_grace_period": 0,
        "principal_grace_period": 0,
        "number_of_installments": 2,
        "fine_configuration": {
          "contract_fine_rate": 0.02,
          "interest_base": "calendar_days",
          "monthly_rate": 0.01
        }
      }
    }
  ]
}

```

:::caution Atenção!

Os payloads ultilizados na simulação de um refinanciamento são os mesmos ultilizados na simulação de uma divida simples, com a adição da lista de operações que serão quitadas em **"refinanced_credit_operations"** com os seus dados para o cálculo da quitação.
:::

## Response

STATUS 200

Response Body

```json
[
    {
        "data": {
            "annual_cet": 0.6252134981759837,
            "assignment_amount": 1919.84,
            "cet": 0.0413,
            "contract_fee_amount": -179.13,
            "contract_fees": [
                {
                    "amount": 1.0,
                    "amount_type": "percentage",
                    "fee_amount": -179.13,
                    "fee_type": "tac"
                }
            ],
            "credit_operation_type": "ccb",
            "disbursed_issue_amount": 2079.96,
            "disbursement_date": "2023-04-01",
            "disbursement_options": [
                {
                    "annual_cet": 0.6252134981759837,
                    "assignment_amount": 1919.84,
                    "cet": 0.0413,
                    "contract_fee_amount": -179.13,
                    "contract_fees": [
                        {
                            "amount": 1.0,
                            "amount_type": "percentage",
                            "fee_amount": -179.13,
                            "fee_type": "tac"
                        }
                    ],
                    "disbursed_issue_amount": 2079.96,
                    "disbursement_date": "2023-04-01",
                    "external_contract_fee_amount": 19.01,
                    "external_contract_fees": [
                        {
                            "amount": 1.0,
                            "amount_released": 17.25,
                            "amount_type": "percentage",
                            "cofins_amount": 0,
                            "csll_amount": 0,
                            "description": null,
                            "fee_amount": 19.01,
                            "fee_type": "spread",
                            "irrf_amount": 0,
                            "net_fee_amount": 17.25,
                            "pis_amount": 0,
                            "tax_amount": 1.76
                        }
                    ],
                    "first_due_date": "2023-05-01",
                    "installments": [
                        {
                            "business_due_date": "2023-05-02",
                            "calendar_days": 30,
                            "due_date": "2023-05-01",
                            "due_principal": 1900.83,
                            "has_interest": true,
                            "installment_number": 1,
                            "post_fixed_amount": 0,
                            "pre_fixed_amount": 199.90606482231624,
                            "principal_amortization_amount": 904.6839351776838,
                            "tax_amount": 0.0,
                            "total_amount": 1104.59,
                            "workdays": 18.0
                        },
                        {
                            "business_due_date": "2023-06-01",
                            "calendar_days": 31,
                            "due_date": "2023-06-01",
                            "due_principal": 996.1460648223162,
                            "has_interest": true,
                            "installment_number": 2,
                            "post_fixed_amount": 0,
                            "pre_fixed_amount": 108.43818022618876,
                            "principal_amortization_amount": 996.1418197738112,
                            "tax_amount": 0.0,
                            "total_amount": 1104.58,
                            "workdays": 23.0
                        }
                    ],
                    "iof_amount": 0.0,
                    "issue_amount": 1900.83,
                    "net_external_contract_fee_amount": 17.25,
                    "prefixed_interest_rate": {
                        "annual_rate": 2.32,
                        "daily_rate": 0.0033388,
                        "interest_base": "calendar_days",
                        "monthly_rate": 0.10516767
                    },
                    "total_pre_fixed_amount": 308.344245048505
                }
            ],
            "external_contract_fee_amount": 19.01,
            "external_contract_fees": [
                {
                    "amount": 1.0,
                    "amount_released": 17.25,
                    "amount_type": "percentage",
                    "cofins_amount": 0,
                    "csll_amount": 0,
                    "description": null,
                    "fee_amount": 19.01,
                    "fee_type": "spread",
                    "irrf_amount": 0,
                    "net_fee_amount": 17.25,
                    "pis_amount": 0,
                    "tax_amount": 1.76
                }
            ],
            "final_disbursement_amount": -17733.89,
            "installments": [
                {
                    "business_due_date": "2023-05-02",
                    "calendar_days": 30,
                    "due_date": "2023-05-01",
                    "due_principal": 1900.83,
                    "has_interest": true,
                    "installment_number": 1,
                    "post_fixed_amount": 0,
                    "pre_fixed_amount": 199.90606482231624,
                    "principal_amortization_amount": 904.6839351776838,
                    "tax_amount": 0.0,
                    "total_amount": 1104.59,
                    "workdays": 18.0
                },
                {
                    "business_due_date": "2023-06-01",
                    "calendar_days": 31,
                    "due_date": "2023-06-01",
                    "due_principal": 996.1460648223162,
                    "has_interest": true,
                    "installment_number": 2,
                    "post_fixed_amount": 0,
                    "pre_fixed_amount": 108.43818022618876,
                    "principal_amortization_amount": 996.1418197738112,
                    "tax_amount": 0.0,
                    "total_amount": 1104.58,
                    "workdays": 23.0
                }
            ],
            "interest_grace_period": 0,
            "interest_payment_month_period": 1,
            "interest_type": "pre_price_days",
            "iof_amount": 0.0,
            "issue_amount": 1900.83,
            "issue_date": "2023-04-01",
            "net_external_contract_fee_amount": 17.25,
            "number_of_installments": 2,
            "operation_type": "refinancing",
            "post_fixed_interest_base": "workdays",
            "post_fixed_interest_rate": null,
            "prefixed_interest_rate": {
                "annual_rate": 2.32,
                "daily_rate": 0.0033388,
                "interest_base": "calendar_days",
                "monthly_rate": 0.10516767
            },
            "principal_amortization_month_period": 1,
            "principal_grace_period": 0,
            "refinanced_credit_operations": [
                {
                    "due_balance": 19813.85,
                    "due_balance_reference_date": "2023-03-29",
                    "original_deadline": 1084,
                    "refinanced_credit_operation_key": "a9630d51-f08f-4763-b269-c1947e97c260",
                    "refinanced_credit_operation_status": null
                }
            ],
            "requester_key": "ef48fbe4-267b-45c1-9049-75345c075486",
            "total_pre_fixed_amount": 308.344245048505
        },
        "event_datetime": "2023-03-29 19:19:28",
        "key": "0fc07785-7f74-45b0-a8ca-8ca48f8c17ed",
        "status": "finished",
        "type": "debt"
    }
]
```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

## Definições

### Request Body
| Campo                 | Tipo    | Descrição                                                                                                    | 
|-----------------------|---------|--------------------------------------------------------------------------------------------------------------|
| **complex_operation** | boolean | _true_ - indica que multiplas simulações podem ser realizadas na mesma request                               |
| **operation_batch**   | object  | Lista de solicitações de simulação - **[Objeto da Lista Operation Batch](#objeto-da-lista-operation_batch)** |

### Objeto da Lista Operation Batch
| Campo         | Tipo   | Descrição                                                                 | 
|---------------|--------|---------------------------------------------------------------------------|
| **borrower**  | object | **[Objeto Borrower](#objeto-borrower)** - Devedor da operação de crédito  |
| **financial** | object | **[Objeto Financial](#objeto-financial)** - Dados financeiros da operação |

### Objeto Borrower
| Campo           | Tipo   | Descrição                                                                                          |
|-----------------|--------|----------------------------------------------------------------------------------------------------|
| **person_type** | object | **[Enumerador Person Type](#enumerador-person_type)** - Natureza Jurídica do devedor da operação   |

### Objeto Financial
| Campo                      | Tipo   | Descrição                                                                                                     |
|----------------------------|--------|---------------------------------------------------------------------------------------------------------------|
| **amout**                  | float  | Valor de emissão/nominal da operação de crédito                                                               |
| **interest_type**          | object | **[Enumerador Interest Type](#enumerador-interest-type)** - Método de amortização e forma de cálculo de juros |
| **credit_operation_type**  | object | **[Enumerador Credit Operation Type](#enumerador-credit-operation-type)** - Tipo do contrato de crédito       |
| **annual_interest_rate**   | float  | Taxa de juros pré-fixada expressa em decimal ao ano                                                           |
| **disbursement_date**      | date   | Data do desembolso da operação                                                                                |
| **interest_grace_period**  | int    | Carência de juros (em meses)                                                                                  |
| **principal_grace_period** | int    | Período carência de principal                                                                                 |
| **number_of_installments** | int    | Número de parcelas da operação de crédito                                                                     |
| **fine_configuration**     | object | **[Objeto fine_configuration](#objeto-fine-configuration)** - Configuração de juros e multa por atraso        |
| **refinanced_credit_operations**     | array of objects | Lista de objetos contendo informações sobre as operações que serão refinanciadas         |

### Objeto Refinanced Credit Operations

#### Objeto no caso da operação refinanciada não existir
| Campo                     | Tipo   | Descrição                                                                 |
|---------------------------|--------|---------------------------------------------------------------------------|
| **due_balance**           | number | Valor necessário para a quitação da operação refinanciada.                |
| **original_deadline**     | int    | Prazo total em dias da Operação de Crédito refinanciada.                  |
| **monthly_interest_rate** | float  | Taxa de juros mensal da operação refinanciada.                            |
| **disbursement_date**     | date   | Data de desembolso da operação refinanciada.                              |

#### Objeto no caso da operação refinanciada já existir
| Campo                     | Tipo          | Descrição                                                   |
|---------------------------|---------------|-------------------------------------------------------------|
| **operation_key**         | string uuid   | Chave da operação que será refinanciada.                    |

### Objeto Fine Configuration
| Campo                  | Tipo  | Descrição                                                                            | 
|------------------------|-------|--------------------------------------------------------------------------------------|
| **contract_fine_rate** | float | Percentual de multa por atraso expresso em decimal                                   |
| **interest_base**      | enum  | **[Enumerador Interest Base](#enumerador-interest-base)** - Base de cálculo de juros |
| **monthly_rate**       | float | Percentual de juros de atraso ao mês expresso em decimal                             |

---

# Criar um refinanciamento

URL: /documentation/refinanciamento/solicitando_refinanciamento

## Request

ENDPOINT /debt
MÉTODO POST

Request Body

```json
{
    "borrower": {
        "address": {
            "city": "Bauru",
            "neighborhood": "Centro",
            "number": "343",
            "postal_code": "17057770",
            "state": "SP",
            "street": "Av Um"
        },
        "birth_date": "1998-03-21",
        "document_identification": "2f7bfc50-d7c0-4d4e-a5ce-d8bba2aeb348",
        "document_identification_number": "432202821",
        "email": "victor.moura@qitech.com.br",
        "individual_document_number": "37197645832",
        "name": "Urich Oliveira",
        "person_type": "natural",
        "phone": {
            "area_code": "14",
            "country_code": "055",
            "number": "936180265"
        }
    },
    "disbursement_bank_account": {
        "account_digit": "2",
        "account_number": "63755",
        "bank_code": "329",
        "branch_number": "0001"
    },
    "financial": {
        "disbursed_amount": 5000.0
        "monthly_interest_rate": 0.0175,
        "credit_operation_type": "ccb",
        "disbursement_date": "2022-04-25",
        "fine_configuration": {
            "contract_fine_rate": 0.02,
            "interest_base": "calendar_days",
            "monthly_rate": 0.01
        },
        "first_due_date": "2022-06-07",
        "interest_grace_period": 0,
        "interest_subsidy_percentage": 0,
        "interest_type": "pre_price_days",
        "issue_date": "2022-04-25",
        "number_of_installments": 84,
        "principal_grace_period": 0,
        "payment_type": "bankslip"
    },
    "simplified": true,
    "refinanced_credit_operations": [
            {
                "operation_key": "d897f8fa-30d0-4a25-b7e5-5daa61c7480d"
            },
            {
                "operation_key": "f8f0d7a9-4f0c-426c-ac50-33a09d4a0d78"
            }
    ],
  "purchaser_document_number": "32402502000135"
}

```

:::caution Atenção!

O payload ultilizado na emissão de um refinanciamento é o mesmo ultilizado na emissão de uma divida simples, com a adição da lista de operações que serão quitadas em **"refinanced_credit_operations"**.
:::

### Body Params

| Campo                           | Tipo   | Descrição                                                                                                                                                                                                        | Máx. Caract. | 
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **borrower** *                  | object | **[Objeto Borrower](#objeto-borrower)** - Devedor da operação de crédito.                                                                                                                                         | -            | 
| **disbursement_bank_account** * | object | **[Objeto Disbursement Bank Account](#objeto-disbursement_bank_accounts)** - Dados da conta bancária para desembolso da operação.                                                                                 | -            |
| **financial** *                 | object | **[Objeto Financial](#objeto-financial)** - Dados da conta bancária para desembolso da operaçãoIdentificador de que o objeto enviado é uma pessoa física. Deve conter SEMPRE o  valor "natural" para borrower PF. | -            |
| **purchaser_document_number** * | string | CNPJ do cessionário (comprador) da operação de crédito.                                                                                                                                                           | -            |
| **refinanced_credit_operations** * | array of objects | Lista de **[Objetos Refinanced Credit Operations](#objeto-refinanced_credit_operations)** contendo as operações refinanciadas.                                                                                                                                                           | -            |

## Definições

### Objeto Request Body
| Campo                           | Tipo   | Descrição                                                                                                                                                                                                        | Máx. Caract. | 
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **borrower** *                  | object | **[Objeto Borrower](#objeto-borrower)** - Devedor da operação de crédito                                                                                                                                         | -            | 
| **disbursement_bank_account** * | object | **[Objeto Disbursement Bank Account](#objeto-disbursement_bank_accounts)** - Dados da conta bancária para desembolso da operação                                                                                 | -            |
| **financial** *                 | object | **[Objeto Financial](#objeto-financial)** - Dados da conta bancária para desembolso da operaçãoIdentificador de que o objeto enviado é uma pessoa física. Deve conter SEMPRE o  valor "natural" para borrower PF | -            |
| **purchaser_document_number** * | string | CNPJ do cessionário (comprador) da operação de crédito                                                                                                                                                           | -            |

### Objeto Borrower
| Campo                            | Tipo    | Descrição                                                                             | Máx. Caract. | 
|----------------------------------|---------|---------------------------------------------------------------------------------------|--------------|
| **name** *                       | string  | Nome do devedor                                                                       | 100          |
| **email**                        | string  | Email do devedor                                                                      | 254          |
| **phone**                        | object  | **[Objeto Phone](#objeto-phone)** - Telefone de contato do devedor                    | -            | 
| **is_pep** *                     | boolean | Indicador de PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep)      | -            |
| **address** *                    | object  | **[Objeto Address](#objeto-address)** - Endereço do devedor                           | -            | 
| **role_type** *                  | enum    | default: _issuer_                                                                     | -            |
| **birth_date** *                 | date    | Data de nascimento do devedor (formato "AAAA-MM-DD")                                  | -            |
| **mother_name** *                | string  | Nome da mãe do devedor                                                                | 100          |
| **nationality**                  | string  | Nacionalidade do devedor                                                              | 50           |
| **person_type** *                | string  | Indicador de pessoa física - default: _natural_                                       | -            |
| **individual_document_number** * | string  | CPF do devedor (apenas números)                                                       | 11           |
| **document_identification**     * | string  | **DOCUMENT_KEY** do PDF do documento de identificação do devedor com foto (RG ou CNH) | -            |
| **document_identification_back** |string | DOCUMENT_KEY do PDF da parte de trás do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente). | 11 |
| **wedding_certificate** | string | DOCUMENT_KEY do PDF do certificado de casamento da pessoa (enviado previamente). No caso de marital_status ser "single", o valor deste campo deve ser NULL. | 11 |
| **proof_of_residence** * |string | DOCUMENT_KEY do PDF do comprovante de endereço do endereço enviado (enviado previamente). | 11 |

### Objeto Address
| Campo              | Tipo   | Descrição                                                                | Máx. Caract. | 
|--------------------|--------|--------------------------------------------------------------------------|--------------| 
| **city** *         | string | Cidade do endereço                                                       | 100          |
| **state** *        | string | Estado do endereço (com dois caracteres maiúsculos)                      | 2            |
| **number** *       | string | Número do endereço                                                       | 10           |
| **street** *       | string | Rua do endereço                                                          | 100          |
| **complement** *   | string | Complemento do endereço (texto livre)                                    | 100          |
| **postal_code** *  | string | CEP do endereço (http://www.buscacep.correios.com.br/sistemas/buscacep/) | 8            |
| **neighborhood** * | string | Bairro do endereço                                                       | 100          |

### Objeto Phone
| Campo              | Descrição | Exemplo                                               | Máx. Caract. | 
|--------------------|-----------|-------------------------------------------------------|--------------| 
| **number** *       | string    | Número de telefone                                    | 10           |
| **area_code** *    | string    | Código DDD do telefone (https://ddd.guiamais.com.br/) | 2            |
| **country_code** * | string    | Código DDI do telefone (https://ddi.guiamais.com.br/) | 3            |

### Objeto Disbursement Bank Account

Uma emissão de dívida deve conter as informações bancárias para desembolso, por padrão, uma conta de titularidade do devedor.

| Campo                 | Tipo   | Descrição                                                                                          | Máx. Caract. | 
|-----------------------|--------|----------------------------------------------------------------------------------------------------|--------------|
| name                  | string | Nome do titular da conta                                                                           | 50           |
| document_number       | string | CPF do titular da conta                                                                            | 11           |
| bank_code *           | string | Código COMPE da instituição financeira (https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf) | 3            |
| branch_number *       | string | Número da agência (não informar o dígito verificador da agência!)                                  | 4            |
| account_number *      | string | Número da conta (sem o dígito verificador da conta!)                                               | 10           |
| account_digit *       | string | Dígito verificador da conta (informar zero no lugar de letras)                                     | 1            |
| account_type          | enum   | [Enumerador Account Type](#enumerador-account-type) Tipo da conta                                  | 1            |

### Objeto Financial

O objeto financial descreve as informações financeiras da operação de crédito.

| Campo                      | Tipo   | Descrição                                                                                                     | Máx. Caract. |
|----------------------------|--------|---------------------------------------------------------------------------------------------------------------|--------------|
| **amout**                  | float  | Valor de emissão/nominal da operação de crédito                                                               | -            |
| **interest_type**          | object | **[Enumerador Interest Type](#enumerador-interest-type)** - Método de amortização e forma de cálculo de juros | -            |
| **credit_operation_type**  | object | **[Enumerador Credit Operation Type](#enumerador-credit-operation-type)** - Tipo do contrato de crédito       | -            |
| **annual_interest_rate**   | float  | Taxa de juros pré-fixada expressa em decimal ao ano                                                           | -            |
| **disbursement_date**      | date   | Data do desembolso da operação                                                                                | -            |
| **interest_grace_period**  | int    | Carência de juros (em meses)                                                                                  | -            |
| **principal_grace_period** | int    | Período carência de principal                                                                                 | -            |
| **number_of_installments** | int    | Número de parcelas da operação de crédito                                                                     | -            |
| **fine_configuration**     | object | **[Objeto Fine Configuration](#objeto-fine-configuration)** - Configuração de juros e multa por atraso        | -            |

### Objeto Fine Configuration

No Objeto Fine Configuration são informados os valor de multa e juros por atraso da operação de crédito. 

| Campo                  | Tipo  | Descrição                                                                            | Máx. Caract. |
|------------------------|-------|--------------------------------------------------------------------------------------|--------------|
| **contract_fine_rate** | float | Percentual de multa por atraso                                                       | -            |
| **interest_base**      | enum  | **[Enumerador Interest Base](#enumerador-interest-base)** - Base de cálculo de juros | -            |
| **monthly_rate**       | float | Percentual de juros de atraso ao mês                                                 | -            |

### Objeto Refinanced Credit Operations 

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `operation_key` | string | key da operação a ser refinanciada | chave uuid |

# Enumeradores

### Enumerador _Person Type_
| Enumerador             | Descrição             |
|------------------------|-----------------------|
| **legal**   | Pessoa juridica        |
| **natural**    | Pesso física    |

### Enumerador _Account Type_
| Enumerador             | Descrição             |
|------------------------|-----------------------|
| **checking_account**   | Conta corrente        |
| **deposit_account**    | Conta de depósito     |
| **guaranteed_account** | Conta de garantia     |
| **investment_account** | Conta de investimento |
| **payment_account**    | Conta de pagamento    |
| **saving_account**     | Conta poupança        |
| **salary_account**     | Conta salário         |

### Enumerador _Interest Type_
| Enumerador           | Descrição                                                                                                                                                                |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **pre_price_days**   | Método de amortização Price (parcelas iguais) com cálculo do juros pré-fixado ao dia                                                                                     |
| **pre_price**        | Método de amortização Price (parcelas iguais) com cálculo do juros pré-fixado em períodos fixos (30 dias)                                                                |
| **pre_sac**          | Método de amortização SAC (amortização constante) com cálculo do juros pré-fixado ao dia                                                                                 |
| **post_sac**         | Método de amortização SAC (amortização constante) com cálculo do juros baseado em uma taxa pré-fixada + indexador pós-fixado (cdi, ipca ou igpm) ao dia                  |
| **post_price**       | Método de amortização Price (parcelas iguais) com cálculo do juros baseado em uma taxa pré-fixada + indexador pós-fixado (cdi, ipca ou igpm) em períodos fixos (30 dias) |
| **post_price_days**  | Método de amortização Price (parcelas iguais) com cálculo do juros baseado em uma taxa pré-fixada + indexador pós-fixado (cdi, ipca ou igpm) ao dia                      |

### Enumerador _Credit Operation Type_
| Enumerador    | Descrição                      |
|---------------|--------------------------------|
| **ccb**       | Cédula de Crédito Bancário     |
| **cce**       | Cédula de Crédito à Exportação |
| **cci**       | Cédula de Crédito Imobiliário  |
| **nce**       | Nota de Crédito à Exportação   |

### Enumerador _Interest Base_
| Enumerador            | Descrição                                                                 |
|-----------------------|---------------------------------------------------------------------------|
| **workdays**          | Base de cálculo de juros em dias úteis considerando um ano de 252 dias    |
| **calendar_days**     | Base de cálculo de juros em dias corridos considerando um ano de 360 dias |
| **calendar_days_365** | Base de cálculo de juros em dias corridos considerando um ano de 365 dias |

### Enumerador _Fee Type_
Cada tipo de fee deve ser previamente habilitado e configurado pela QI Tech

| Enumerador            | Descrição                                                                  |
|-----------------------|----------------------------------------------------------------------------|
| **tac**               | Tarifa de abertura de cadastro                                             |
| **spread**            | Ágio cobrado no valor de aquisição da operação de crédito                  |
| **warranty_analysis** | Tarifa de análise de garantias                                             |
| **ted_fee**           | Tarifa de TED                                                              |
| **spread_ted_fee**    | Ágio da tarifa de TED cobrado no valor de aquisição da operação de crédito |

## Response

STATUS 200

Response Body

```json
{
  "data": {
    "additional_iof": 469.1328,
    "annual_cet": "283,3821%",
    "assignment_amount": 124690.56,
    "base_iof": 473.6829374063069,
    "borrower": {
      "document_number": "96969879003",
      "name": "Alan Mathison Turing"
    },
    "cet": "11,8500%",
    "collaterals": [],
    "contract": {
      "number": "0000067563/AMT",
      "signature_information": [
        {
          "signature_url": null,
          "signer_document_number": "15627918004",
          "signer_email": "alan.turing@email.com",
          "signer_external_key": null,
          "signer_name": "Alan Mathison Turing",
          "signer_role": "issuer"
        }
      ],
      "urls": [
        "https://storage.googleapis.com/sandbox-doc-api/documents/5af36fcd-8e4c-4421-ad45-7bcba899c0d3/SYNGENTASANDBOX-ALAN_MATHISON_TURING-CCB-0000067563-20230302234816.pdf"
      ]
    },
    "contract_fee_amount": 1234.56,
    "contract_fees": [
      {
        "fee_amount": 1234.56,
        "fee_type": "tac"
      }
    ],
    "external_contract_fee_amount": 1234.56,
    "external_contract_fees": [
      {
        "fee_amount": 1234.56,
        "fee_type": "spread",
        "net_fee_amount": 1120.36,
        "tax_amount": 114.2
      }
    ],
    "installments": [
      {
        "accrual_reference_date": null,
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": null,
        "business_due_date": "2023-04-03",
        "calendar_days": 31,
        "digitable_line": null,
        "due_date": "2023-04-02",
        "due_interest": 0,
        "due_principal": 123456,
        "fine_amount": null,
        "has_interest": true,
        "installment_history": [],
        "installment_key": "da264e95-2bbd-47de-876b-bfea7d25e266",
        "installment_number": 1,
        "installment_payment": [],
        "installment_status": "created",
        "installment_type": "principal",
        "original_due_principal": 123456,
        "original_pre_fixed_amount": 13245.468714162304,
        "original_principal_amortization_amount": 58473.151285837695,
        "original_total_amount": 71718.62,
        "paid_amount": 0,
        "paid_at": null,
        "post_fixed_amount": 0,
        "pre_fixed_amount": 13245.468714162304,
        "principal_amortization_amount": 58473.151285837695,
        "qr_code_key": null,
        "qr_code_url": null,
        "renegotiation_proposal_key": null,
        "tax_amount": 148.63875056859942,
        "total_accrual_amount": null,
        "total_amount": 71718.62,
        "total_paid_amount": 0,
        "workdays": 21
      },
      {
        "accrual_reference_date": null,
        "additional_costs": [],
        "advanced_paid_amount": 0,
        "bank_slip_key": null,
        "business_due_date": "2023-05-02",
        "calendar_days": 30,
        "digitable_line": null,
        "due_date": "2023-05-02",
        "due_interest": 0,
        "due_principal": 64982.848714162305,
        "fine_amount": null,
        "has_interest": true,
        "installment_history": [],
        "installment_key": "cac7064b-2310-45e1-a91f-5e8f39f0f0ea",
        "installment_number": 2,
        "installment_payment": [],
        "installment_status": "created",
        "installment_type": "principal",
        "original_due_principal": 64982.848714162305,
        "original_pre_fixed_amount": 6735.77577015044,
        "original_principal_amortization_amount": 64982.84422984956,
        "original_total_amount": 71718.62,
        "paid_amount": 0,
        "paid_at": null,
        "post_fixed_amount": 0,
        "pre_fixed_amount": 6735.77577015044,
        "principal_amortization_amount": 64982.84422984956,
        "qr_code_key": null,
        "qr_code_url": null,
        "renegotiation_proposal_key": null,
        "tax_amount": 325.0441868377075,
        "total_accrual_amount": null,
        "total_amount": 71718.62,
        "total_paid_amount": 0,
        "workdays": 19
      }
    ],
    "iof_charge_method": "financed",
    "issue_amount": 123456,
    "net_external_contract_fee_amount": 1120.36,
    "number_of_installments": 2,
    "prefixed_interest_rate": {
      "annual_rate": 2.32,
      "created_at": "2023-03-02T23:48:15",
      "daily_rate": 0.00329298,
      "interest_base": "calendar_days_365",
      "monthly_rate": 0.10516767
    },
    "requester_identifier_key": "1c2ca4dc-2a20-4dd4-bd5f-af143fadadf4",
    "total_iof": 942.82,
    "total_pre_fixed_amount": 19981.244484312745
  },
  "event_datetime": "2023-03-02 23:48:20",
  "key": "1c2ca4dc-2a20-4dd4-bd5f-af143fadadf4",
  "status": "waiting_signature",
  "webhook_type": "debt"
}
```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

---

# Atualizar regra de movimentação automática

URL: /documentation/regras_de_movimentacao/atualizar_regra_movimentacao

## Request

ENDPOINT /baas/automatic_transfer/transfer_configuration
MÉTODO PUT

:::danger Desativar transferência automática:
- Para desativar uma transferência automática basta enviar o parâmetro 'is_active' com valor false
:::

**REGRA DIVISÃO PERCENTUAL**

**Request Body**
    

```json
{
        "transfer_cronstring": "*/5 * * * *",
        "automatic_transfer_key": "967c40ea-ba35-4445-89b1-fa35bd0749a4",
        "rule_configuration": {
          "destinations": [
            {
              "account_digit": "9",
              "financial_institutions_code_number": "063",
              "document_number": "48504807000198",
              "account_number": "1232046",
              "percentage": 100,
              "name": "Mateus Fonseca",
              "account_branch": "0931",
              "is_pix_transfer": false
            }
          ],
          "remaining_balance": 0
        },
        "is_active": false,
        "rule": "split_percentage"
}
```

### Body Params

| Campo                           | Tipo   | Descrição                                                                                 | Caracteres                                                  |
|---------------------------------|--------|-------------------------------------------------------------------------------------------|-------------------------------------------------------------|
| `transfer_cronstring`*          | string | Frequência de transferência do dinheiro em CRON, padrão que permite expressar recorrência. | **[CRON Guru](https://crontab.guru/#0_9_*_*_*)**            |
| `rule`*                         | enum   | Regra a ser seguida. (split_equal ou split_percentage).                                    | **[Enumeradores](#enumeradores-rule)**                      
| `rule_configuration`*           | object | Objeto de configuração da regra escolhida.                                                 | **[Objeto rule_configuration](#objeto-rule_configuration)** |
| `account_key`*                  | uuid   | Key da conta origem das transferências.                                                    | -                                                           |
| `automatic_transfer_key`*       | uuid   | Key da configuração a ser alterada.                                                        | -                                                           |

### Obejto rule_configuration

| Campo          | Tipo | Descrição | Caracteres                                       |
|----------------|---| ---|--------------------------------------------------|
| `destinations` | object | Contas destino e outros dados. | **[Array of destination](#objeto-destinations)** |
| `remaining_balance` | float  | Valor de saldo que irá permanecer na conta.                                               | -                                                           |

### Objeto destinations

| Campo | Tipo    | Descrição                                                                                            | Caracteres |
|---|---------|------------------------------------------------------------------------------------------------------|------------|
| `account_branch`* | string  | Agência da conta destino.                                                                            | 3          |
| `account_number`* | string  | Número da conta destino.                                                                             | 3          |
| `account_digit`* | string  | Dígito da conta destino.                                                                             | 3          |
| `document_number`* | string  | Número do documento do dono da conta.                                                                | 3          |
| `name`* | string  | Nome da pessoa física ou razão social da pessoa jurídica.                                            | 3          |
| `financial_institutions_code_number`* | string  | Código COMPE da instituição financeira (https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf) | 3          |
| `financial_institutions_ispb`* | string  | Número ISPB da instituição financeira.                                                               | 8          |
| `is_pix_transfer`* | boolean | Define se a transferência será va pix.                                                               | -          |
| `percentage`* | float   | Porcentagem a ser destinada a essa conta.                                                            | -          |

### Enumeradores rule 

| Enumerador         | Tradução                                  |
|--------------------|-------------------------------------------|
| **split_percentage**   | [divisão percentual](./regras_de_movimentacao.md) |
| **split_equal**        | [divisão igual](./regras_de_movimentacao.md) |
| **single_beneficiary** | [beneficiário único](./regras_de_movimentacao.md) |

## Response

STATUS 200

**Response Body**

```json
{
  "automatic_transfer_key": "967c40ea-ba35-4445-89b1-fa35bd0749a4",
  "is_active": false,
  "rule": "split_percentage",
  "rule_configuration": {
    "destinations": [
      {
        "account_branch": "0931",
        "account_digit": "9",
        "account_number": "1232046",
        "document_number": "48504807000198",
        "financial_institutions_code_number": "063",
        "is_pix_transfer": false,
        "name": "Mateus Fonseca",
        "percentage": 100
      }
    ],
    "remaining_balance": 0
  },
  "transfer_cronstring": "*/5 * * * *"
}

```

**REGRA DIVISÃO IGUALITÁRIA**

**Request Body**
    

```json
{
        "transfer_cronstring": "*/5 * * * *",
        "automatic_transfer_key": "967c40ea-ba35-4445-89b1-fa35bd0749a4",
        "rule_configuration": {
          "destinations": [
            {
              "account_digit": "9",
              "financial_institutions_code_number": "063",
              "document_number": "48504807000198",
              "account_number": "1232046",
              "name": "Mateus Fonseca",
              "account_branch": "0931"
            }
          ],
          "remaining_balance": 0
        },
        "is_active": false,
        "rule": "split_equal"
}
```

### Body Params

| Campo | Tipo   | Descrição                                                                              | Caracteres                                                  |
|---|--------|----------------------------------------------------------------------------------------|-------------------------------------------------------------|
| `transfer_cronstring`* | string | Frequência de transferência do dinheiro em CRON, padrão que permite expressar recorrência. | **[CRON Guru](https://crontab.guru/#0_9_*_*_*)**            |
| `rule`* | enum   | Regra a ser seguida. (split_equal ou split_percentage).                                | **[Enumeradores](#enumeradores-rule)**                      
| `rule_configuration`*| object | Objeto de configuração da regra escolhida.                                             | **[Objeto rule_configuration](#objeto-rule_configuration)** |
| `account_key`*| uuid   | Key da conta origem das transferências.                                               | -                                                           |
| `automatic_transfer_key`*| uuid   | Key da configuração a ser alterada.                                                   | -                                                           |

### Obejto rule_configuration

| Campo          | Tipo | Descrição | Caracteres                                       |
|----------------|---| ---|--------------------------------------------------|
| `destinations` | object | Contas destino e outros dados. | **[Array of destination](#objeto-destinations)** |
| `remaining_balance` | float  | Valor de saldo que irá permanecer na conta.                                                | -                                                           |

### Objeto destinations

| Campo | Tipo   | Descrição | Caracteres |
|---|--------| ---|------------|
| `account_branch`* | string |  Agência da conta destino. | 3          |
| `account_number`* | string | Número da conta destino. | -          |
| `account_digit`* | string | Dígito da conta destino. | 3          |
| `document_number`* | string | Número do documento do dono da conta. | -          |
| `name`* | string | Nome da pessoa física ou razão social da pessoa jurídica. | 3          |
| `financial_institutions_code_number`* | string | Código COMPE da instituição financeira (https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf) | 3          |
| `financial_institutions_ispb`* | string | Número ISPB da instituição financeira. | 8          |

### Enumeradores rule 

| Enumerador         | Tradução                                  |
|--------------------|-------------------------------------------|
| **split_percentage**   | [divisão percentual](./regras_de_movimentacao.md) |
| **split_equal**        | [divisão igual](./regras_de_movimentacao.md) |
| **single_beneficiary** | [beneficiário único](./regras_de_movimentacao.md) |

## Response

STATUS 200

**Response Body**

```json
{
  "automatic_transfer_key": "967c40ea-ba35-4445-89b1-fa35bd0749a4",
  "is_active": false,
  "rule": "split_equal",
  "rule_configuration": {
    "destinations": [
      {
        "account_branch": "0931",
        "account_digit": "9",
        "account_number": "1232046",
        "document_number": "48504807000198",
        "financial_institutions_code_number": "063",
        "name": "Mateus Fonseca"
      }
    ],
    "remaining_balance": 0
  },
  "transfer_cronstring": "*/5 * * * *"
}

```

**REGRA BENEFICIÁRIO ÚNICO**

**Request Body**
    

```json
{
        "transfer_cronstring": "*/5 * * * *",
        "automatic_transfer_key": "967c40ea-ba35-4445-89b1-fa35bd0749a4",
        "rule_configuration": {
          "destination": 
            {
              "account_digit": "9",
              "financial_institutions_code_number": "063",
              "document_number": "48504807000198",
              "account_number": "1232046",
              "name": "Mateus Fonseca",
              "account_branch": "0931"
            },
          "remaining_balance": 0
        },
        "is_active": false,
        "rule": "single_beneficiary"
}
```

### Body Params

| Campo | Tipo   | Descrição                                                                                  | Caracteres                                                  |
|---|--------|--------------------------------------------------------------------------------------------|-------------------------------------------------------------|
| `transfer_cronstring`* | string | Frequência de transferência do dinheiro em CRON, padrão que permite expressar recorrência. | **[CRON Guru](https://crontab.guru/#0_9_*_*_*)**            |
| `rule`* | enum   | Regra a ser seguida. (split_equal ou split_percentage).                                    | **[Enumeradores](#enumeradores-rule)**                      
| `rule_configuration`*| object | Objeto de configuração da regra escolhida.                                                 | **[Objeto rule_configuration](#objeto-rule_configuration)** |
| `account_key`*| uuid   | Key da conta origem das transferências.                                                   | -                                                           |
| `automatic_transfer_key`*| uuid   | Key da configuração a ser alterada.                                                   | -                                                           |

### Obejto rule_configuration

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `destination` | object | Contas destino e outros dados. | **[destination](#objeto-destinations)**  |
| `remaining_balance` | float  | Valor de saldo que irá permanecer na conta.                                                | -                                                           |

### Objeto destination

| Campo | Tipo   | Descrição | Caracteres |
|---|--------| ---| ---|
| `account_branch`* | string |  Agência da conta destino. | 3 |
| `account_number`* | string | Número da conta destino. | 3 |
| `account_digit`* | string | Dígito da conta destino. | 3 |
| `document_number`* | string | Número do documento do dono da conta. | 3 |
| `name`* | string | Nome da pessoa física ou razão social da pessoa jurídica. | 3 |
| `financial_institutions_code_number`* | string | Código COMPE da instituição financeira (https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf) | 3 |
| `financial_institutions_ispb`* | string | Número ISPB da instituição financeira. | 8 |

### Enumeradores rule 

| Enumerador         | Tradução                                  |
|--------------------|-------------------------------------------|
| **split_percentage**   | [divisão percentual](./regras_de_movimentacao.md) |
| **split_equal**        | [divisão igual](./regras_de_movimentacao.md) |
| **single_beneficiary** | [beneficiário único](./regras_de_movimentacao.md) |

## Response

STATUS 200
**Response Body**

```json
{
  "automatic_transfer_key": "967c40ea-ba35-4445-89b1-fa35bd0749a4",
  "is_active": false,
  "rule": "single_beneficiary",
  "rule_configuration": {
    "destination": {
      "account_branch": "0931",
      "account_digit": "9",
      "account_number": "1232046",
      "document_number": "48504807000198",
      "financial_institutions_code_number": "063",
      "name": "Mateus Fonseca"
    },
    "remaining_balance": 0
  },
  "transfer_cronstring": "*/5 * * * *"
}

```

STATUS 400
**Response Body**

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

---

# Criar regra de movimentação automática

URL: /documentation/regras_de_movimentacao/criar_regra_de_movimentacao

## Request

ENDPOINT /baas/automatic_transfer/transfer_configuration
MÉTODO POST
**REGRA DIVISÃO PERCENTUAL**

**Request Body**
    

```json
{
        "transfer_cronstring": "*/5 * * * *",
        "account_key": "6203037b-4405-4602-b7ce-ff99806d9cb0",
        "rule_configuration": {
          "destinations": [
            {
              "account_digit": "9",
              "financial_institutions_code_number": "063",
              "document_number": "48504807000198",
              "account_number": "1232046",
              "percentage": 100,
              "name": "Mateus Fonseca",
              "account_branch": "0931",
              "is_pix_transfer": false
            }
          ],
          "remaining_balance": 0
        },
        "is_active": true,
        "rule": "split_percentage"
}
```

### Body Params

| Campo                | Tipo   | Descrição                                                                                 | Caracteres                                                  |
|----------------------|--------|-------------------------------------------------------------------------------------------|-------------------------------------------------------------|
| `transfer_cronstring`* | string | Frequência de transferência do dinheiro em CRON, padrão que permite expressar recorrência. | **[CRON Guru](https://crontab.guru/#0_9_*_*_*)**            |
| `rule`*              | enum   | Regra a ser seguida. (split_equal ou split_percentage).                                    | **[Enumeradores](#enumeradores-rule)**                      
| `rule_configuration`* | object | Objeto de configuração da regra escolhida.                                                 | **[Objeto rule_configuration](#objeto-rule_configuration)** |
| `account_key`*       | uuid   | Key da conta origem das transferências.                                                    | -                                                           |

### Obejto rule_configuration

| Campo          | Tipo | Descrição | Caracteres                                       |
|----------------|---| ---|--------------------------------------------------|
| `destinations` | object | Contas destino e outros dados. | **[Array of destination](#objeto-destinations)** |
| `remaining_balance` | float  | Valor de saldo que irá permanecer na conta.                                               | -                                                           |

### Objeto destinations

| Campo | Tipo    | Descrição                                                                                            | Caracteres |
|---|---------|------------------------------------------------------------------------------------------------------|------------|
| `account_branch`* | string  | Agência da conta destino.                                                                            | 3          |
| `account_number`* | string  | Número da conta destino.                                                                             | 3          |
| `account_digit`* | string  | Dígito da conta destino.                                                                             | 3          |
| `document_number`* | string  | Número do documento do dono da conta.                                                                | 3          |
| `name`* | string  | Nome da pessoa física ou razão social da pessoa jurídica.                                            | 3          |
| `financial_institutions_code_number`* | string  | Código COMPE da instituição financeira (https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf) | 3          |
| `financial_institutions_ispb`* | string  | Número ISPB da instituição financeira.                                                               | 8          |
| `is_pix_transfer`* | boolean | Define se a transferência será va pix.                                                               | -          |
| `percentage`* | float   | Porcentagem a ser destinada a essa conta.                                                            | -          |

### Enumeradores rule 

| Enumerador         | Tradução                                  |
|--------------------|-------------------------------------------|
| **split_percentage**   | [divisão percentual](./regras_de_movimentacao.md) |
| **split_equal**        | [divisão igual](./regras_de_movimentacao.md) |
| **single_beneficiary** | [beneficiário único](./regras_de_movimentacao.md) |

## Response

STATUS 200

**Response Body**

```json

{
  "account_key": "6203037b-4405-4602-b7ce-ff99806d9cb0",
  "automatic_transfer_key": "9284ef1d-3689-4bb0-8543-89fffab790a1",
  "rule": "split_percentage",
  "rule_configuration": {
    "destinations": [
      {
        "account_branch": "0931",
        "account_digit": "9",
        "account_number": "1232046",
        "document_number": "48504807000198",
        "financial_institutions_code_number": "063",
        "is_pix_transfer": false,
        "name": "Mateus Fonseca",
        "percentage": 100
      }
    ],
    "remaining_balance": 0
  },
  "status": "active",
  "transfer_cronstring": "*/5 * * * *"
}

```

**REGRA DIVISÃO IGUALITÁRIA**

**Request Body**
    

```json
{
        "transfer_cronstring": "*/5 * * * *",
        "account_key": "6203037b-4405-4602-b7ce-ff99806d9cb0",
         "rule_configuration": {
          "destinations": [
            {
              "account_digit": "9",
              "financial_institutions_code_number": "063",
              "document_number": "48504807000198",
              "account_number": "1232046",
              "name": "Mateus Fonseca",
              "account_branch": "0931"
            }
          ],
          "remaining_balance": 0
        },
        "is_active": true,
        "rule": "split_equal"
}
```

### Body Params

| Campo | Tipo   | Descrição                                                                                  | Caracteres                                                  |
|---|--------|--------------------------------------------------------------------------------------------|-------------------------------------------------------------|
| `transfer_cronstring`* | string | Frequência de transferência do dinheiro em CRON, padrão que permite expressar recorrência. | **[CRON Guru](https://crontab.guru/#0_9_*_*_*)**            |
| `rule`* | enum   | Regra a ser seguida. (split_equal ou split_percentage).                                    | **[Enumeradores](#enumeradores-rule)**                      
| `rule_configuration`*| object | Objeto de configuração da regra escolhida.                                                 | **[Objeto rule_configuration](#objeto-rule_configuration)** |
| `account_key`*| uuid   | Key da conta origem das transferências.                                                   | -                                                           |

### Obejto rule_configuration

| Campo          | Tipo | Descrição | Caracteres                                       |
|----------------|---| ---|--------------------------------------------------|
| `destinations` | object | Contas destino e outros dados. | **[Array of destination](#objeto-destinations)** |
| `remaining_balance` | float  | Valor de saldo que irá permanecer na conta.                                                | -                                                           |

### Objeto destinations

| Campo | Tipo   | Descrição | Caracteres |
|---|--------| ---|------------|
| `account_branch` * | string |  Agência da conta destino. | 3          |
| `account_number` * | string | Número da conta destino. | -          |
| `account_digit` * | string | Dígito da conta destino. | 3          |
| `document_number` * | string | Número do documento do dono da conta. | -          |
| `name` * | string | Nome da pessoa física ou razão social da pessoa jurídica. | 3          |
| `financial_institutions_code_number` * | string | Código COMPE da instituição financeira (https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf) | 3          |
| `financial_institutions_ispb` * | string | Número ISPB da instituição financeira. | 8          |

### Enumeradores rule 

| Enumerador         | Tradução                                  |
|--------------------|-------------------------------------------|
| **split_percentage**   | [divisão percentual](./regras_de_movimentacao.md) |
| **split_equal**        | [divisão igual](./regras_de_movimentacao.md) |
| **single_beneficiary** | [beneficiário único](./regras_de_movimentacao.md) |

## Response

STATUS 200

**Response Body**

```json
{
  "account_key": "6203037b-4405-4602-b7ce-ff99806d9cb0",
  "automatic_transfer_key": "d39fba5b-dec7-4773-9bba-120e9f61ffa0",
  "rule": "split_equal",
  "rule_configuration": {
    "destinations": [
      {
        "account_branch": "0931",
        "account_digit": "9",
        "account_number": "1232046",
        "document_number": "48504807000198",
        "financial_institutions_code_number": "063",
        "name": "Mateus Fonseca"
      }
    ],
    "remaining_balance": 0
  },
  "status": "active",
  "transfer_cronstring": "*/5 * * * *"
}

```

**REGRA BENEFICIÁRIO ÚNICO**

**Request Body**
    

```json
{
        "transfer_cronstring": "*/5 * * * *",
        "rule_configuration": {
          "destination": 
            {
              "account_digit": "9",
              "financial_institutions_code_number": "063",
              "document_number": "48504807000198",
              "account_number": "1232046",
              "name": "Mateus Fonseca",
              "account_branch": "0931"
            },
          "remaining_balance": 0
        },
        "is_active": false,
        "rule": "single_beneficiary"
}
```

### Body Params

| Campo | Tipo   | Descrição                                                                                  | Caracteres                                                  |
|---|--------|--------------------------------------------------------------------------------------------|-------------------------------------------------------------|
| `transfer_cronstring`* | string | Frequência de transferência do dinheiro em CRON, padrão que permite expressar recorrência. | **[CRON Guru](https://crontab.guru/#0_9_*_*_*)**            |
| `rule`* | enum   | Regra a ser seguida. (split_equal ou split_percentage).                                    | **[Enumeradores](#enumeradores-rule)**                      
| `rule_configuration`*| object | Objeto de configuração da regra escolhida.                                                 | **[Objeto rule_configuration](#objeto-rule_configuration)** |
| `account_key`*| uuid   | Key da conta origem das transferências.                                                   | -                                                           |

### Obejto rule_configuration

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `destination` | object | Contas destino e outros dados. | **[destination](#objeto-destinations)**  |
| `remaining_balance` | float  | Valor de saldo que irá permanecer na conta.                                                | -                                                           |

### Objeto destination

| Campo | Tipo   | Descrição | Caracteres |
|---|--------| ---| ---|
| `account_branch`* | string |  Agência da conta destino. | 3 |
| `account_number`* | string | Número da conta destino. | 3 |
| `account_digit`* | string | Dígito da conta destino. | 3 |
| `document_number`* | string | Número do documento do dono da conta. | 3 |
| `name`* | string | Nome da pessoa física ou razão social da pessoa jurídica. | 3 |
| `financial_institutions_code_number`* | string | Código COMPE da instituição financeira (https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf) | 3 |
| `financial_institutions_ispb`* | string | Número ISPB da instituição financeira. | 8 |

### Enumeradores rule 

| Enumerador         | Tradução                                  |
|--------------------|-------------------------------------------|
| **split_percentage**   | [divisão percentual](./regras_de_movimentacao.md) |
| **split_equal**        | [divisão igual](./regras_de_movimentacao.md) |
| **single_beneficiary** | [beneficiário único](./regras_de_movimentacao.md) |

## Response

STATUS 200

**Response Body**

```json
{
  "is_active": false,
  "rule": "single_beneficiary",
  "rule_configuration": {
    "destination": {
      "account_branch": "0931",
      "account_digit": "9",
      "account_number": "1232046",
      "document_number": "48504807000198",
      "financial_institutions_code_number": "063",
      "name": "Mateus Fonseca"
    },
    "remaining_balance": 0
  },
  "transfer_cronstring": "*/5 * * * *"
}

```

STATUS 400
**Response Body**

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

---

# Regras de movimentação

URL: /documentation/regras_de_movimentacao/

No momento da abertura de uma conta QI Tech, disponibilizamos aos nossos clientes a possibilidade de criar regras de movimentação para a conta. Estas regras visam facilitar operações repetivias, por exemplo, a transferência de todo ou parte do saldo da conta ao final do dia. Aqui iremos exemplificar as diferenças entre as principais regras presentes em nosso sistema: "split_equal", "split_percentage". Caso o cliente tenha uma regra que não se enquadre nestas duas ele pode solicitar ao nosso time durante sua integração a criação de uma regra em nosso sistema que atenda suas necessidades.

### REGRA DIVISÃO PERCENTUAL (SPLIT_PERCENTAGE)

A regra de divisão percentual divide o saldo disponível em conta percentualmente para as contas destino, na periocidade escolhida em "transfer_cronstring". A soma dos percentuais de cada conta destino pode ser menor ou igual a 100. Caso a soma das porcentagens seja menor que 100, a porcentagem faltante ficará como saldo na conta. Assim, o cliente pode escolher transferir, por exemplo, 80% do dinheiro entre contas e deixar sempre 20% de saldo.

### REGRA DIVISÃO IGUALITÁRIA (SPLIT_EQUAL)

A regra de divisão igualitária divide igualmente o saldo disponível em conta para as contas destino, na periocidade escolhida em "transfer_cronstring", deixando apenas o valor definido em "remaining_balance" como saldo. Caso o campo "remaining_balance" não seja preenchido, 100% do saldo da conta é transferido. Caso o saldo disponível em conta seja igual ou menor do que "remaining_balance", a transação não ocorre.

### REGRA BENEFICIÁRIO ÚNICO (SINGLE_BENEFICIARY)

A regra de divisão para beneficiário único permite a transferência para um único beneficiário, na periocidade escolhida em "transfer_cronstring".

---

# Cancelar uma renegociação

URL: /documentation/renegociacao/cancelar_uma_renegociacao

## Request

ENDPOINT /renegotiation/proposal/ PROPOSAL-KEY
MÉTODO DELETE

### Path Params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `proposal_key` * | string |  Chave da proposta de renegociação. | chave uuid |  

## Response

STATUS 200

Response Body

```json
{

}
```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

---

# Consultar uma renegociação

URL: /documentation/renegociacao/consultar_uma_renegociacao

## Consultar por Proposal Key

ENDPOINT /renegotiation/proposal/ PROPOSAL-KEY
MÉTODO GET

### Path params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|   
| `proposal_key` * | string |  Chave da proposta de renegociação. | Chave uuid |

### Response

STATUS 200

Response Body

```json
{
  "proposal_key": "bcc16a6d-ce21-4cd4-8d8c-d26f89ccc685",
  "request_control_key": null,
  "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
  "proposal_status": "pending_payment",
  "amortization_type": "installment_payment",
  "discount_percentage": 0.2,
  "payment_amount": 240,
  "requester_name": "Requester",
  "requester_key": "bcc16a6d-ce21-4cd4-8d8c-d26f89ccc685",
  "issuer_name": "issuer",
  "reference_date": "2022-07-20",
  "proposal_due_date": "2022-07-20",
  "issuer_document_number": "98765432100",
  "payment_type": "bank_slip",
  "payment": {
    "digitable_line": "",
    "qr_code_url": {},
    "qr_code_key": "",
    "bank_slip_key": "",
    "paid_method_type": null
  },
  "affected_installments": [
    {
      "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88",
      "due_date": "2022-05-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125,
      "present_amount": 100,
      "paid_amount": 80
    },
    {
      "installment_key": "6597a073-ea7a-4447-b250-f4d3f07b0b74",
      "due_date": "2022-06-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125,
      "present_amount": 100,
      "paid_amount": 80
    },
    {
      "installment_key": "3da60b56-17fb-4b32-a1e4-1f0c28d18900",
      "due_date": "2022-07-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125,
      "present_amount": 100,
      "paid_amount": 80
    }
  ],
  "remaining_installments": [
    {
      "installment_key": "3da60b56-17fb-4b32-a1e4-1f0c28d18903",
      "due_date": "2022-08-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125
    },
    {
      "installment_key": "3da60b56-17fb-4b32-a1e4-1f0c28d18904",
      "due_date": "2022-09-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125
    },
    {
      "installment_key": "3da60b56-17fb-4b32-a1e4-1f0c28d18905",
      "due_date": "2022-10-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125
    }
  ]
}
```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

## Consultar por Request Control Key

ENDPOINT /renegotiation/proposal/request_control_key/ REQUEST-CONTROL-KEY
MÉTODO GET

### Path params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|   
| `request_control_key` * | string |  Chave de controle da requisição para rastreamento e identificação única. | UUID |
 

 ## Response

STATUS 200

Response Body

```json
{
  "proposal_key": "bcc16a6d-ce21-4cd4-8d8c-d26f89ccc685",
  "request_control_key": "3571e292-3a83-4011-904d-20ee963022ef",
  "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
  "proposal_status": "pending_payment",
  "amortization_type": "installment_payment",
  "discount_percentage": 0.2,
  "payment_amount": 240,
  "requester_name": "Requester",
  "requester_key": "bcc16a6d-ce21-4cd4-8d8c-d26f89ccc685",
  "issuer_name": "issuer",
  "reference_date": "2022-07-20",
  "proposal_due_date": "2022-07-20",
  "issuer_document_number": "98765432100",
  "payment_type": "bank_slip",
  "payment": {
    "digitable_line": "",
    "qr_code_url": {},
    "qr_code_key": "",
    "bank_slip_key": "",
    "paid_method_type": null
  },
  "affected_installments": [
    {
      "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88",
      "due_date": "2022-05-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125,
      "present_amount": 100,
      "paid_amount": 80
    },
    {
      "installment_key": "6597a073-ea7a-4447-b250-f4d3f07b0b74",
      "due_date": "2022-06-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125,
      "present_amount": 100,
      "paid_amount": 80
    },
    {
      "installment_key": "3da60b56-17fb-4b32-a1e4-1f0c28d18900",
      "due_date": "2022-07-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125,
      "present_amount": 100,
      "paid_amount": 80
    }
  ],
  "remaining_installments": [
    {
      "installment_key": "3da60b56-17fb-4b32-a1e4-1f0c28d18903",
      "due_date": "2022-08-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125
    },
    {
      "installment_key": "3da60b56-17fb-4b32-a1e4-1f0c28d18904",
      "due_date": "2022-09-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125
    },
    {
      "installment_key": "3da60b56-17fb-4b32-a1e4-1f0c28d18905",
      "due_date": "2022-10-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125
    }
  ]
}
```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

---

# Criar uma renegociação

URL: /documentation/renegociacao/criacao_de_uma_renegociacao

ENDPOINT /renegotiation/proposal
MÉTODO POST

```json
{
  "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",  // chave da operação de crédito
  "amortization_type": "installment_payment",           // define quais parcelas e como o valor é calculado
  "reference_date": "2022-07-20",                       // base para cálculo do valor presente (D+1)
  "proposal_due_date": "2022-07-20",                    // vencimento do boleto / Pix gerado
  "payment_type": "bank_slip",                          // instrumento de cobrança
  "discount_percentage": 0.2,                           // 20% de desconto sobre o present_amount
  "installments": [
    { "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88" }, // parcela a quitar
    { "installment_key": "0ff87136-b084-44fb-8fc2-d2e3beed483b" }
  ]
}
```

O `amortization_type` define quais parcelas são quitadas e se o cálculo usa valor presente ou valor de face. O `payment_type` controla o instrumento gerado. Veja as seções abaixo para as variações de cada campo.

## `payment_type`

  {[
    {type:'bank_slip', desc:'Linha digitável + Pix QR code'},
    {type:'pix', desc:'Apenas Pix QR code'},
    {type:'manual', desc:'Sem instrumento — registro manual'},
    {type:'internal', desc:'Pagamento interno QI Tech'},
  ].map(({type,desc})=>(
{type}
{desc}
  ))}

## `amortization_type`

**installment_payment**

Quita **parcelas específicas** (por key) sobre o `present_amount` (valor descontado para hoje). Compatível com desconto.

- Exatamente **um** modo de desconto obrigatório: `discount_percentage`, `discount_amount` ou `paid_amount` por parcela
- Para cobrar o valor de face (`total_amount`) sem simular: use `first_installments` com `number_of_installments`

```json
{
  "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
  "payment_type": "bank_slip",
  "amortization_type": "installment_payment",
  "reference_date": "2022-07-20",
  "proposal_due_date": "2022-07-20",
  "discount_percentage": 0.2,
  "request_control_key": "3571e292-3a83-4011-904d-20ee963022ef",
  "installments": [
    { "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88" },
    { "installment_key": "0ff87136-b084-44fb-8fc2-d2e3beed483b" }
  ]
}
```

**overdue_installment_payment**

Idêntico ao `installment_payment`, mas **restrito a parcelas em atraso**. Compatível com desconto.

- Aceita apenas parcelas com status `overdue` ou `paid_partial_overdue` — qualquer outro status retorna erro
- Exatamente **um** modo de desconto obrigatório: `discount_percentage`, `discount_amount` ou `paid_amount` por parcela

```json
{
  "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
  "payment_type": "bank_slip",
  "amortization_type": "overdue_installment_payment",
  "reference_date": "2022-07-20",
  "proposal_due_date": "2022-07-20",
  "discount_percentage": 0.1,
  "request_control_key": "3571e292-3a83-4011-904d-20ee963022ef",
  "installments": [
    { "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88" }
  ]
}
```

**first_installments**

Quita as **primeiras parcelas em aberto** ao **valor de face** (`total_amount`). A co-api calcula os valores internamente — não é necessário simular antes. Não compatível com desconto.

- **`number_of_installments`** — quita exatamente N parcelas completas
- **`payment_amount`** — distribui o valor pelas primeiras parcelas; a última pode ser quitada parcialmente

```json
{
  "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
  "payment_type": "bank_slip",
  "amortization_type": "first_installments",
  "reference_date": "2022-07-20",
  "proposal_due_date": "2022-07-20",
  "request_control_key": "3571e292-3a83-4011-904d-20ee963022ef",
  "number_of_installments": 4
}
```

**last_installments**

Quita as **últimas parcelas em aberto** ao **valor de face**, distribuindo o `payment_amount` da última para a primeira. Não compatível com desconto.

- `include_matured_installment: true` inclui no cálculo a parcela vencida exatamente na `reference_date` (padrão: `false`)

```json
{
  "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
  "payment_type": "bank_slip",
  "amortization_type": "last_installments",
  "reference_date": "2022-07-20",
  "proposal_due_date": "2022-07-20",
  "request_control_key": "3571e292-3a83-4011-904d-20ee963022ef",
  "payment_amount": 900
}
```

**equal_amount**

Distribui o `payment_amount` **em partes iguais entre todas as parcelas em aberto**, independente do saldo devedor individual de cada uma. Não compatível com desconto.

:::caution
O abatimento uniforme ignora o peso de cada parcela — parcelas com juros acumulados diferentes recebem o mesmo valor, o que pode deixar saldo residual inesperado. Use apenas quando esse comportamento for intencional.
:::

```json
{
  "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
  "payment_type": "bank_slip",
  "amortization_type": "equal_amount",
  "reference_date": "2022-07-20",
  "proposal_due_date": "2022-07-20",
  "request_control_key": "3571e292-3a83-4011-904d-20ee963022ef",
  "payment_amount": 900
}
```

**full_settle**

Quitação total da operação. O `payment_amount` deve corresponder ao saldo devedor total — use a [simulação](/renegociacao/simulacao_de_uma_renegociacao) para obter o valor exato. Não compatível com desconto.

```json
{
  "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
  "payment_type": "bank_slip",
  "amortization_type": "full_settle",
  "reference_date": "2022-07-20",
  "proposal_due_date": "2022-07-20",
  "request_control_key": "3571e292-3a83-4011-904d-20ee963022ef",
  "payment_amount": 900
}
```

## Desconto

Aplicável apenas a `installment_payment` e `overdue_installment_payment`. Exatamente **um** dos três campos abaixo deve estar presente — são mutuamente exclusivos:

| Campo | Comportamento |
|---|---|
| `discount_percentage` | Percentual sobre o `present_amount`. Ex.: `0.2` = 20% de desconto. |
| `discount_amount` | Valor fixo distribuído proporcionalmente entre as parcelas pelo `present_amount`. |
| `paid_amount` (por parcela) | Valor exato por parcela, sobrepõe o `present_amount`. Use o `total_amount` da simulação para cobrar o valor de face. |

:::info Valor presente vs. valor de face
`installment_payment` cobra por padrão o `present_amount` — o valor da parcela descontado para hoje. Para cobrar o `total_amount` (valor de face, sem antecipação): simule primeiro e passe o `total_amount` retornado como `paid_amount` por parcela. Para cobrar ao valor de face sem simular, prefira `first_installments` com `number_of_installments`.
:::

## Parâmetros

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `debt_key` | UUID | sempre | Chave da operação de crédito. |
| `amortization_type` | string | sempre | Tipo de amortização. |
| `reference_date` | string | sempre | Data base para cálculo do valor presente (D+1). |
| `proposal_due_date` | string | sempre | Data de vencimento do boleto / Pix gerado. |
| `payment_type` | string | sempre | Instrumento de cobrança. |
| `installments` | array | `installment_payment`, `overdue_installment_payment` | Parcelas a quitar, identificadas por `installment_key`. |
| `number_of_installments` | int | `first_installments`¹ | Número exato de parcelas a quitar a partir da primeira em aberto. |
| `payment_amount` | float | `last_installments`, `equal_amount`, `full_settle`; opcional em `first_installments`¹ | Valor total a pagar. |
| `discount_percentage` | float | um dos três modos² | Percentual de desconto sobre o `present_amount`. |
| `discount_amount` | float | um dos três modos² | Valor fixo de desconto distribuído proporcionalmente. |
| `request_control_key` | UUID | não | Chave de idempotência — reenviar o mesmo valor retorna a proposta original sem criar duplicata. |
| `include_matured_installment` | bool | não | `last_installments` apenas: inclui parcela vencida na `reference_date`. Padrão: `false`. |

¹ `first_installments` exige exatamente um entre `number_of_installments` e `payment_amount`.  
² `discount_percentage`, `discount_amount` e `paid_amount` por parcela são mutuamente exclusivos — exatamente um é obrigatório para `installment_payment` e `overdue_installment_payment`.

### Installments object

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `installment_key` | UUID | sempre | Chave da parcela a quitar. |
| `paid_amount` | float | um dos três modos² | Valor exato a cobrar por esta parcela — substitui o `present_amount`. |

## Response

**201 — proposta criada**

```json
{
  "contract_number": "0001232093/ABC",
  "proposal_key": "bcc16a6d-ce21-4cd4-8d8c-d26f89ccc685",
  "request_control_key": "3571e292-3a83-4011-904d-20ee963022ef",
  "proposal_status": "pending_payment",
  "amortization_type": "installment_payment",
  "discount_percentage": 0.2,
  "payment_amount": 300,
  "reference_date": "2022-07-20",
  "proposal_due_date": "2022-07-20",
  "payment_type": "bank_slip",
  "payment": {
    "digitable_line": "32990001031000700298993000000203110340000004618",
    "qr_code_url": "mockurl.com.br",
    "qr_code_key": "f02c201d-314e-42be-968c-a48776d98fbf",
    "bank_slip_key": "931a989d-66e9-4631-abaa-b413610afb85",
    "paid_method_type": null
  },
  "affected_installments": [
    {
      "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88",
      "due_date": "2023-01-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125,
      "present_amount": 100,
      "paid_amount": 80
    }
  ],
  "remaining_installments": [
    {
      "installment_key": "03b4d86a-9dba-40fc-a4db-33e8772b7be8",
      "due_date": "2022-08-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125
    }
  ]
}
```

**`payment`**

| Campo | Descrição |
|---|---|
| `digitable_line` | Linha digitável do boleto. Vazio se `payment_type` não for `bank_slip`. |
| `qr_code_url` | URL do QR code Pix. Presente para `bank_slip` e `pix`. |
| `qr_code_key` | Chave do QR code Pix. |
| `bank_slip_key` | Chave do boleto gerado. |
| `paid_method_type` | Método pelo qual o pagamento foi confirmado. `null` enquanto `proposal_status` for `pending_payment`. |

**`affected_installments`** — parcelas incluídas nesta proposta

| Campo | Descrição |
|---|---|
| `total_amount` | Valor de face da parcela (principal + juros + multa). |
| `present_amount` | Valor descontado para a `reference_date` (base de cálculo do `installment_payment`). |
| `paid_amount` | Valor efetivamente cobrado nesta proposta após desconto aplicado. |

**`remaining_installments`** — parcelas não incluídas, para referência do saldo devedor restante.

**400 — requisição inválida**

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"code\": \"LEG000069\"}"
}
```

---

# Renegociação internal e external

URL: /documentation/renegociacao/criacao_renegociacao_internal

## Request 

ENDPOINT /renegotiation/proposal
MÉTODO POST

Request Body

**Usando valor de amortização**

```json
{
  "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
  "payment_type": "bank_slip",
  "amortization_type": "last_installments",
  "request_control_key": "e5f6c3d4-e5f6-7890-abcd-ef1234567890",
  "reference_date": "2022-07-20",
  "proposal_due_date":"2022-07-22",
  "payment_amount":500.00,
  "include_maturity_installment": true
}
```

**Usando método external e last_installments**

```json
{
  "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
  "payment_type": "external",
  "amortization_type": "last_installments",
  "request_control_key": "e5f6c3d4-e5f6-7890-abcd-ef1234567890",
  "reference_date": "2022-07-20",
  "transaction_key":"a1b2c3d4-7890-e5f6-abcd-ef17890a7890",
  "bank_slip_key":"a1b2c3d4-7890-e5f6-abcd-ef17890a7890",
  "include_maturity_installment": true
}
```

**Usando método external e first_installments**

```json
{
  "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
  "payment_type": "external",
  "amortization_type": "overdue_installments",
  "request_control_key": "e5f6c3d4-e5f6-7890-abcd-ef1234567890",
  "reference_date": "2022-07-20",
  "transaction_key":"a1b2c3d4-7890-e5f6-abcd-ef17890a7890",
  "bank_slip_key":"a1b2c3d4-7890-e5f6-abcd-ef17890a7890",
  "include_maturity_installment": true
}
```

**Usando método internal e installment_payment**

```json
{
  "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
  "payment_type": "internal",
  "amortization_type": "installment_payment",
  "request_control_key": "e5f6c3d4-e5f6-7890-abcd-ef1234567890",
  "reference_date": "2022-07-20",
  "account_key": "5ae72355-1e47-4624-9915-ceb93d872194",
  "installments": [
    {
      "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88"
    },
    {
      "installment_key": "0ff87136-b084-44fb-8fc2-d2e3beed483b"
    },
    {
      "installment_key": "e4101c6a-51b3-435f-a2b7-4a65a005cc15"
    }
  ]
}
```

**Usando método external e overdue_and_maturing_payment**

```json
{
  "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
  "payment_type": "external",
  "amortization_type": "overdue_and_maturing_payment",
  "request_control_key": "e5f6c3d4-e5f6-7890-abcd-ef1234567890",
  "reference_date": "2022-07-20",
  "transaction_key":"a1b2c3d4-7890-e5f6-abcd-ef17890a7890",
  "bank_slip_key":"a1b2c3d4-7890-e5f6-abcd-ef17890a7890"
}
```

**Usando método internal e overdue_and_maturing_payment**

```json
{
  "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
  "payment_type": "internal",
  "amortization_type": "overdue_and_maturing_payment",
  "request_control_key": "e5f6c3d4-e5f6-7890-abcd-ef1234567890",
  "reference_date": "2022-07-20",
  "account_key": "5ae72355-1e47-4624-9915-ceb93d872194",
  "payment_amount": 500.00
}
```

## Amortization_type last_installments

Este tipo de amortização pode ser utilizado com o payment_type bank_slip junto à um valor de saldo a ser amortizado, ou junto ao método external adicionando as informações da transação.

O método irá utilizar o saldo do pagamento para amortizar as parcelas na seguinte ordem:

#### 1. Parcelas vencidas
#### 2. Primeira parcela não vencida em aberto (caso seja enviada a flag include_maturity_installment)
#### 3. Últimas parcelas em aberto

Todas as parcelas serão calculadas na data de referência enviada no campo reference_date.

## Amortization_type overdue_and_maturing_payment

Este tipo de amortização pode ser utilizado tanto com o payment_type internal quanto com o payment_type external, informando um payment_amount (ou o valor da transação, no caso do método external) e a reference_date. Ele não requer o envio da lista de installments (como installment_payment) nem da flag include_maturity_installment (como last_installments) — a seleção das parcelas a amortizar é automática.

A partir das parcelas ainda em aberto da operação, o método seleciona automaticamente:

#### 1. Parcelas vencidas (due_date menor ou igual à reference_date)
#### 2. Parcelas que vencem no mesmo mês/ano da reference_date, mesmo que ainda não estejam vencidas

Caso não exista nenhuma parcela vencida nem nenhuma parcela a vencer no mês da reference_date, a requisição é recusada.

O valor informado é utilizado para quitar as parcelas em cascata, na seguinte ordem:

1. Parcelas vencidas, da mais antiga para a mais recente, calculadas pelo valor presente na reference_date **incluindo encargos de atraso** (juros e multa).
2. Parcelas a vencer no mês de referência, da mais próxima para a mais distante, calculadas pelo valor presente **descontado** da due_date até a reference_date (desconto por antecipação, sem encargos de atraso).

A alocação para de avançar assim que o valor informado se esgota. Caso uma parcela a vencer seja quitada apenas parcialmente, o valor pago é registrado como antecipação (advanced_paid_amount) na parcela, que mantém seu status original, ao invés de ser refletido em paid_amount.

Caso o valor informado seja maior do que o necessário para quitar todas as parcelas vencidas e todas as parcelas a vencer no mês de referência, o valor remanescente será enviado como devolução, da mesma forma que ocorre nos demais amortization_types baseados em saldo (last_installments e overdue_installments).

Este amortization_type está disponível apenas para operações de crédito com taxa de juros do tipo pre_sac, pre_price_days ou pre_price, e não pode ser utilizado em propostas de pré-desembolso — somente em operações de crédito já desembolsadas.

## payment_type external

Este método de pagamento deve sempre vir acompanhado do campo transaction_key e caso a transação seja referente à um pagamento de boleto, deve vir acompanhada da chave bank_slip_key.

Este método de pagamento deve vir acompanhado dos seguintes amortization_types:

#### 1. overdue_installments
#### 2. last_installments
#### 3. overdue_and_maturing_payment

Caso seja utilizado o método overdue_installments e o valor de amortização seja maior do que o valor de quitação das parcelas vencidas, o valor remanescente será enviado ao fundo como devolução.

Caso seja utilizado o método last_installments e o valor de amortização seja maior do que o valor de quitação de toda a operação, o valor remanescente será enviado ao fundo como devolução.

Caso seja utilizado o método overdue_and_maturing_payment e o valor de amortização seja maior do que o valor de quitação das parcelas vencidas e das parcelas a vencer no mês de referência, o valor remanescente será enviado ao fundo como devolução.

## payment_type internal

Este tipo de pagamento pode ser utilizado com qualquer tipo de amortização, ao invés de ser gerado um boleto ou um pix, o pagamento movimentará o valor financeiro da amortização (calculado ou informado, dependendo do tipo de amortização) da conta informada pelo parâmetro source_account_key. 

A movimentação enviará o financeiro para conta de conciliação das baixas de renegociação de titularidade QI, ou para conta de titularidade do credor da dívida. 

As configurações da conta de origem e destino da movimentação devem ser alinhadas com o time de operações.

### Body Params

| Campo | Tipo | Descrição                                                                                                                         | Caracteres                                                            |
|---    |---   |-----------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|  
| `debt_key`                        | string | Chave única da operação de crédito dentro da QI.                                                                                  | UUID                                                                  |
| `payment_type`                    | string | Tipo de pagamento.                                                                                                                | Enumeradores Payment Type           |
| `amortization_type`               | string | Tipo de amortização.                                                                                                              | Enumeradores Amortization Type |
| `reference_date`                  | string | Data referencia a qual valor presente será calculado da renegociação (precisa ser D+1).                                           | 10                                                                    |
| `proposal_due_date`               | string | Data referencia a qual valor presente será calculado da renegociação (precisa ser D+1).                                           | 10                                                                    |
| `request_control_key`             | string | Chave de controle da requisição para rastreamento e identificação única.                                                          | UUID                                                                  |
| `transaction_key`                 | string | Chave de controle da transação referente à liquidação na conta do fundo.                                                          | UUID                                                                  |
| `bank_slip_key`                   | string | Chave de controle da transação referente à liquidação na conta do fundo.                                                          | UUID                                                                  |
| `include_maturity_installment`    | boolean| Flag que indica se deve ser adicionada a primeira parcela não vencida no cálculo da amortização                                   | true ou false                                                         |

## Response

STATUS 201

Response Body

```json
{
  "contract_number": "0001232093/ABC",
  "proposal_key": "bcc16a6d-ce21-4cd4-8d8c-d26f89ccc685",
  "request_control_key": "3571e292-3a83-4011-904d-20ee963022ef",
  "proposal_status": "pending_payment",
  "amortization_type": "installment_payment",
  "discount_percentage": 0.2,
  "payment_amount": 300,
  "requester_name": "Requester",
  "requester_key": "bcc16a6d-ce21-4cd4-8d8c-d26f89ccc685",
  "issuer_name": "issuer",
  "reference_date": "2022-07-20",
  "proposal_due_date": "2022-07-20",
  "issuer_document_number": "98765432100",
  "payment_type": "bank_slip",
  "origin_key": "76912b4b-508a-4b10-9485-0e87f1316b35",
  "payment": {
    "digitable_line": "32990001031000700298993000000203110340000004618",
    "qr_code_url": "mockurl.com.br",
    "qr_code_key": "f02c201d-314e-42be-968c-a48776d98fbf",
    "bank_slip_key": "931a989d-66e9-4631-abaa-b413610afb85",
    "paid_method_type": "bank_slip"
  },
  "affected_installments": [
    {
      "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88",
      "due_date": "2023-01-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125,
      "present_amount": 100,
      "paid_amount": 80
    },
    {
      "installment_key": "0ff87136-b084-44fb-8fc2-d2e3beed483b",
      "due_date": "2022-12-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125,
      "present_amount": 100,
      "paid_amount": 80
    },
    {
      "installment_key": "e4101c6a-51b3-435f-a2b7-4a65a005cc15",
      "due_date": "2022-11-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125,
      "present_amount": 100,
      "paid_amount": 80
    }
  ],
  "remaining_installments": [
    {
      "installment_key": "03b4d86a-9dba-40fc-a4db-33e8772b7be8",
      "due_date": "2022-08-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125
    },
    {
      "installment_key": "c622efa6-8731-464b-a563-a7a26c19279d",
      "due_date": "2022-09-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125
    },
    {
      "installment_key": "3da60b56-17fb-4b32-a1e4-1f0c28d18905",
      "due_date": "2022-10-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125
    }
  ]
}
```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

---

# Listar renegociações

URL: /documentation/renegociacao/listar_renegociacoes

## Request

ENDPOINT /renegotiation/proposal
MÉTODO GET

### Query Params

Todos os parâmetros são opcionais e podem ser combinados livremente para filtrar a listagem.

| Campo | Tipo | Descrição |
|---|---|---|
| `proposal_status` | string (enumerador) | Filtra pelo status da proposta. Ver [Enumerador proposal_status](#enumerador-proposal_status). |
| `payment_type` | string (enumerador) | Filtra pelo tipo de pagamento da proposta. Ver [Enumerador payment_type](#enumerador-payment_type). |
| `amortization_type` | string (enumerador) | Filtra pelo tipo de amortização aplicado à proposta. Ver [Enumerador amortization_type](#enumerador-amortization_type). |
| `contract_number` | string | Número do contrato original que está sendo renegociado. |
| `issuer_document_number` | string | CPF ou CNPJ do tomador (devedor) do contrato original. |
| `issuer_name` | string | Nome do tomador do contrato original. |
| `requester_key` | string (UUID) | Chave do solicitante (parceiro) que criou a proposta. Quando não informado, é assumido automaticamente a partir do header `SELECTED-AGENT`. |
| `requester_name` | string | Nome do solicitante que criou a proposta. |
| `credit_operation_key` | string (UUID) | Chave da operação de crédito original que está sendo renegociada. |
| `payment_amount` | string (numérico) | Filtra pelo valor da parcela de pagamento da proposta. |
| `proposal_start_due_date` | string (data, `yyyy-MM-dd`) | Filtra propostas com data de vencimento (`proposal_due_date`) a partir desta data. |
| `proposal_end_due_date` | string (data, `yyyy-MM-dd`) | Filtra propostas com data de vencimento (`proposal_due_date`) até esta data. |
| `page` | string (numérico) | Número da página. Padrão: `1`. |
| `page_size` | string (numérico) | Quantidade de registros por página. Padrão: `10`. Valores acima de `50` são automaticamente limitados a `50`. |

 ## Response

STATUS 200

Response Body

```json
{
  "data": [
    {
      "proposal_key": "9f1c2e3a-7b6d-4a1e-8c2f-3d4e5f6a7b8c",
      "proposal_status": "pending_payment",
      "payment_type": "bank_slip",
      "amortization_type": "overdue_installment_payment",
      "contract_number": "0000049047/UO",
      "requester_key": "ba99b7f1-3db6-4a63-a386-ba2c7f31e784",
      "requester_name": "QI Sociedade de Crédito Direto",
      "issuer_name": "Urich Oliveira",
      "issuer_document_number": "37197645832",
      "origin_key": null,
      "payment_amount": 1210.26,
      "discount_amount": 0,
      "discount_percentage": 0,
      "devolution_amount": null,
      "proposal_due_date": "2026-08-15",
      "reference_date": "2026-08-01",
      "request_control_key": null,
      "payment": {
        "digitable_line": "34191790010104351004791020150008196610000121026",
        "qr_code_url": null,
        "qr_code_key": null,
        "bank_slip_key": "4b1c9e3d-2f5a-4c8b-9d6e-7f8a9b0c1d2e",
        "paid_method_type": null,
        "source_account_key": null,
        "payment_data": null
      },
      "affected_installments": [
        {
          "installment_key": "946a99c7-1f9d-429d-8ab9-bf2d0e6c6e48",
          "due_date": "2026-06-15",
          "principal_amount": 168.34,
          "interest_amount": 33.37,
          "fine_amount": 0,
          "total_amount": 201.71,
          "present_amount": 200.00,
          "paid_amount": 201.71,
          "principal_amortization_payment_amount": 168.34,
          "prefixed_interest_payment_amount": 33.37,
          "fine_payment_amount": 0,
          "discount_amount": 0
        }
      ],
      "remaining_installments": [
        {
          "installment_key": "b007376d-c0ce-4e83-a279-4981ab331ccf",
          "due_date": "2026-09-15",
          "principal_amount": 170.02,
          "interest_amount": 31.69,
          "fine_amount": null,
          "total_amount": 201.71
        },
        {
          "installment_key": "c1183e5c-0f8e-4b2a-8e4a-1a2b3c4d5e6f",
          "due_date": "2026-10-15",
          "principal_amount": 171.71,
          "interest_amount": 30.00,
          "fine_amount": null,
          "total_amount": 201.71
        }
      ]
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": 2,
    "rows_per_page": 30,
    "total_pages": 5,
    "total_rows": 140
  }
}
```

### Detalhamento dos campos de `data[]`

| Campo | Tipo | Descrição |
|---|---|---|
| `proposal_key` | string (UUID) | Chave única da proposta de renegociação. |
| `proposal_status` | string (enumerador) | Status atual da proposta. Ver [Enumerador proposal_status](#enumerador-proposal_status). |
| `payment_type` | string (enumerador) | Meio de pagamento configurado para a proposta. Ver [Enumerador payment_type](#enumerador-payment_type). |
| `amortization_type` | string (enumerador) | Tipo de amortização aplicado na simulação/criação da proposta. Ver [Enumerador amortization_type](#enumerador-amortization_type). |
| `contract_number` | string | Número do contrato original que está sendo renegociado. |
| `requester_key` | string (UUID) | Chave do solicitante (parceiro) que criou a proposta. |
| `requester_name` | string | Nome do solicitante que criou a proposta. |
| `issuer_name` | string | Nome do tomador (devedor) do contrato original. |
| `issuer_document_number` | string | CPF ou CNPJ do tomador. |
| `origin_key` | string, opcional | Chave de origem da proposta, quando aplicável. |
| `payment_amount` | número | Valor de cada parcela da proposta de renegociação. |
| `discount_amount` | número, opcional | Valor de desconto aplicado sobre o saldo devedor. |
| `discount_percentage` | número, opcional | Percentual de desconto aplicado sobre o saldo devedor. |
| `devolution_amount` | número, opcional | Valor a ser devolvido ao tomador, quando aplicável. |
| `proposal_due_date` | string (data) | Data de vencimento da proposta. |
| `reference_date` | string (data) | Data de referência utilizada no cálculo da proposta. |
| `request_control_key` | string, opcional | Chave de controle da requisição que originou a proposta, quando informada na criação. |
| `include_matured_installment` | booleano, opcional | Indica se parcelas vencidas foram incluídas na renegociação. Só aparece na resposta quando não for nulo. |
| `force_due_date` | booleano, opcional | Indica se a data de vencimento informada foi forçada, ignorando a data sugerida pelo cálculo. Só aparece na resposta quando não for nulo. |
| `issue_amount` | número, opcional | Valor de emissão, presente apenas para tipos de amortização que permitem desembolso (ex.: `equal_amount`, `present_amount`). Só aparece na resposta quando não for nulo. |
| `disbursement_issue_amount` | número, opcional | Valor de emissão a ser desembolsado ao tomador. Só aparece na resposta quando não for nulo. |
| `total_iof` | número, opcional | Valor total de IOF da operação, quando houver desembolso. Só aparece na resposta quando não for nulo. |
| `remaining_principal_disbursement_amount` | número, opcional | Saldo de principal a ser desembolsado nas parcelas remanescentes. Só aparece na resposta quando não for nulo. |
| `remaining_principal_iof_amount` | número, opcional | Saldo de IOF nas parcelas remanescentes. Só aparece na resposta quando não for nulo. |
| `payment` | objeto | Dados do meio de pagamento gerado para a proposta. Ver [Objeto payment](#objeto-payment). |
| `affected_installments` | lista de objetos, opcional | Parcelas do contrato original afetadas/liquidadas por esta proposta. Ver [Objeto affected_installments](#objeto-affected_installments). |
| `remaining_installments` | lista de objetos | Novas parcelas geradas pela renegociação, ainda a vencer. Ver [Objeto remaining_installments](#objeto-remaining_installments). |

#### Objeto `payment` {#objeto-payment}

| Campo | Tipo | Descrição |
|---|---|---|
| `digitable_line` | string, opcional | Linha digitável do boleto, quando `payment_type` for `bank_slip`. |
| `qr_code_url` | string, opcional | URL do QR Code Pix, quando `payment_type` for `pix`. |
| `qr_code_key` | string, opcional | Chave do QR Code Pix gerado. |
| `bank_slip_key` | string, opcional | Chave do boleto gerado. |
| `paid_method_type` | string (enumerador), opcional | Meio efetivamente utilizado no pagamento, preenchido somente após o pagamento ser realizado. Ver [Enumerador paid_method_type](#enumerador-paid_method_type). |
| `source_account_key` | string, opcional | Chave da conta de origem do pagamento, quando aplicável. |
| `payment_data` | objeto, opcional | Dados adicionais do pagamento, conforme o meio utilizado. |

#### Objeto `affected_installments[]` {#objeto-affected_installments}

Cada item representa uma parcela do contrato original consumida por esta proposta.

| Campo | Tipo | Descrição |
|---|---|---|
| `installment_key` | string (UUID) | Chave da parcela do contrato original. |
| `due_date` | string (data) | Data de vencimento original da parcela. |
| `principal_amount` | número | Valor de principal da parcela. |
| `interest_amount` | número | Valor de juros da parcela. |
| `fine_amount` | número, opcional | Valor de multa da parcela. |
| `total_amount` | número | Valor total da parcela (principal + juros + multa). |
| `present_amount` | número | Valor presente da parcela na data de referência da proposta. |
| `paid_amount` | número | Valor efetivamente considerado como pago/liquidado desta parcela pela proposta. |
| `principal_amortization_payment_amount` | número, opcional | Parcela do pagamento amortizada como principal. |
| `prefixed_interest_payment_amount` | número, opcional | Parcela do pagamento amortizada como juros pré-fixados. |
| `fine_payment_amount` | número, opcional | Parcela do pagamento amortizada como multa. |
| `discount_amount` | número, opcional | Valor de desconto aplicado a esta parcela. |
| `paid_principal_disbursement` | número, opcional | Valor de principal desembolsado referente a esta parcela. Só aparece na resposta quando não for nulo. |
| `paid_principal_iof` | número, opcional | Valor de IOF desembolsado referente a esta parcela. Só aparece na resposta quando não for nulo. |
| `discount_principal_disbursement` | número, opcional | Desconto aplicado sobre o principal desembolsado. Só aparece na resposta quando não for nulo. |
| `discount_principal_iof` | número, opcional | Desconto aplicado sobre o IOF desembolsado. Só aparece na resposta quando não for nulo. |
| `discount_fine_amount` | número, opcional | Desconto aplicado sobre a multa. Só aparece na resposta quando não for nulo. |
| `discount_prefixed_interest_amount` | número, opcional | Desconto aplicado sobre os juros pré-fixados. Só aparece na resposta quando não for nulo. |
| `discount_principal_amortization_amount` | número, opcional | Desconto aplicado sobre a amortização de principal. Só aparece na resposta quando não for nulo. |

#### Objeto `remaining_installments[]` {#objeto-remaining_installments}

Cada item representa uma nova parcela, ainda a vencer, gerada pela renegociação.

| Campo | Tipo | Descrição |
|---|---|---|
| `installment_key` | string (UUID) | Chave da nova parcela. |
| `due_date` | string (data) | Data de vencimento da nova parcela. |
| `principal_amount` | número | Valor de principal da parcela. |
| `interest_amount` | número | Valor de juros da parcela. |
| `fine_amount` | número, opcional | Valor de multa da parcela. |
| `total_amount` | número | Valor total da parcela (principal + juros + multa). |
| `principal_disbursement_amount` | número, opcional | Valor de principal a ser desembolsado referente a esta parcela, quando o tipo de amortização permitir desembolso. Só aparece na resposta quando não for nulo. |
| `principal_iof_amount` | número, opcional | Valor de IOF referente ao desembolso desta parcela. Só aparece na resposta quando não for nulo. |

### Enumeradores

#### Enumerador `proposal_status` {#enumerador-proposal_status}

| Valor | Descrição |
|---|---|
| `pending_payment` | Proposta criada, aguardando pagamento. |
| `processing_payment` | Pagamento identificado e em processamento. |
| `paid` | Proposta paga/liquidada com sucesso. |
| `canceled` | Proposta cancelada. |
| `rejected` | Proposta rejeitada. |
| `awaiting_disbursement` | Proposta paga e aguardando o desembolso do valor ao tomador. |
| `partially_settled` | Proposta parcialmente liquidada. |

#### Enumerador `payment_type` {#enumerador-payment_type}

| Valor | Descrição |
|---|---|
| `manual` | Pagamento controlado manualmente, sem geração de meio de pagamento pela QI Tech. |
| `bank_slip` | Pagamento via boleto bancário. |
| `pix` | Pagamento via Pix. |
| `internal` | Pagamento processado internamente, sem geração de boleto ou Pix. |

#### Enumerador `paid_method_type` {#enumerador-paid_method_type}

| Valor | Descrição |
|---|---|
| `bank_slip` | Pagamento identificado via boleto bancário. |
| `pix` | Pagamento identificado via Pix. |
| `integrated_payment` | Pagamento identificado via integração de pagamento (ex.: desconto em folha/conta). |
| `manual` | Pagamento registrado manualmente. |
| `internal` | Pagamento processado internamente. |

#### Enumerador `amortization_type` {#enumerador-amortization_type}

| Valor | Descrição |
|---|---|
| `installment_payment` | Pagamento de parcela(s) específica(s). |
| `first_installments` | Amortização das primeiras parcelas do contrato. |
| `last_installments` | Amortização das últimas parcelas do contrato. |
| `overdue_installment_payment` | Pagamento de parcela(s) em atraso. |
| `overdue_and_maturing_payment` | Pagamento de parcelas em atraso e a vencer. |
| `full_settle` | Liquidação total do contrato. |
| `equal_amount` | Renegociação com parcelas de valor igual, com possibilidade de desembolso. |
| `present_amount` | Renegociação a valor presente, com possibilidade de desembolso. |

:::info Paginação
`pagination.next_page` retorna `null` quando a página atual já é a última.
:::

STATUS 400

Response Body

```json
{
  "title": "Bad Request",
  "description": "1 validation error for GetParamsEntity\nproposal_status\n  value is not a valid enumeration member; permitted: 'pending_payment', 'processing_payment', 'paid', 'canceled', 'rejected', 'awaiting_disbursement', 'partially_settled' (type=type_error.enum; enum_values=[<ProposalStatusEnum.pending_payment: 'pending_payment'>, <ProposalStatusEnum.processing_payment: 'processing_payment'>, <ProposalStatusEnum.paid: 'paid'>, <ProposalStatusEnum.canceled: 'canceled'>, <ProposalStatusEnum.rejected: 'rejected'>, <ProposalStatusEnum.awaiting_disbursement: 'awaiting_disbursement'>, <ProposalStatusEnum.partially_settled: 'partially_settled'>])",
  "translation": "Payload Inválido",
  "code": "QIT000001"
}
```

---

# Pagamento de renegociação

URL: /documentation/renegociacao/pagamento_renegociacao

## Webhooks:

WEBHOOK_TYPE renegotiation.proposal
STATUS paid

#### Enumeradores paid_method_type

| Enumerador                   | Descrição                                     |
|------------------------------|-----------------------------------------------|
| **bank_slip**                | Pagamento por boleto                          |
| **pix**                      | Pagamento por pix                             |

#### Exemplo de webhook de pagamento da renegociação

Webhook Body

```json
{
	"webhook_type": "renegotiation.proposal",
	"key": "\<PROPOSAL-KEY\>",
	"event_datetime": "\<DATA E HORA DO ENVIO DO WEBHOOK\>",
	"status": "paid",
    "data": {
        "paid_method_type": "<METODO DE PAGAMENTO>",
        "paid_in": {
            "code_number": "<CODIGO DO BANCO LIQUIDANTE>", 
            "ispb": "<ISPB DO BANCO LIQUIDANTE>", 
            "name": "<NOME DO BANCO LIQUIDANTE>"
        }
    }
}
```

#### Payment data da installment paga através de renegociação

Webhook Body

```json
{
    "renegotiation_proposal_key": "806fa827-d1c4-4e5d-bf24-7b317fbbff15",
    "paid_in": {
        "ispb": "18236120",
        "name": "NU PAGAMENTOS - IP",
        "code_number": 260
    },
    "resource_account_key": "8517eb4e-ddce-457b-9e39-194213e53691"
}
```

---

# Renegociação em lote

URL: /documentation/renegociacao/renegociacao_em_lote

:::caution ATENÇÃO
A renegociação em lote só pode ser criada com operações de um mesmo emitente e mesma chave de integração. 
:::

:::caution ATENÇÃO
Há um limite de 50 operações para cada renegociação em lote.
:::

## 1. Simular uma renegociação em lote

### Request

ENDPOINT /renegotiation/batch_proposal_simulation
MÉTODO POST

Request Body

```json
{
    "amortization_type": "installment_payment",
    "reference_date": "2022-07-20",
    "discount_percentage": 0.0,
    "operations": [
      {
        "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
        "installments": [{
          "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88"
        }]
      },
      {
        "debt_key": "2cbfb9b1-1gdb-5g8d-9967-b338e5eb83g9",
        "installments": [{
          "installment_key": "2ef25ed8-7124-44f5-9e3d-1d1a7196166e"
        }]
      }
  ]
}
```

### Response

Response Body

```json
{
  "amortization_type": "installment_payment",
  "discount_percentage": 0.0,
  "discount_amount": 0.0,
  "payment_amount": 240,
  "requester_name": "Requester",
  "requester_key": "bcc16a6d-ce21-4cd4-8d8c-d26f89ccc685",
  "issuer_name": "issuer",
  "reference_date": "2022-07-20",
  "issuer_document_number": "98765432100",
  "operations": [
    {
      "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
      "payment_amount": 100,
      "discount_amount": 0,
      "affected_installments": [
        {
          "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88",
          "due_date": "2022-05-01",
          "principal_amount": 100,
          "interest_amount": 20,
          "fine_amount": 5,
          "total_amount": 125,
          "present_amount": 100,
          "paid_amount": 100
        }
      ],
      "remaining_installments": [
        {
          "installment_key": "7ac54a3e-fd11-46b2-b811-4c7d6d158fd5",
          "due_date": "2022-08-01",
          "principal_amount": 100,
          "interest_amount": 20,
          "fine_amount": 5,
          "total_amount": 125
        }
      ]
    },
     {
      "debt_key": "2cbfb9b1-1gdb-5g8d-9967-b338e5eb83g9",
      "payment_amount": 140,
      "discount_amount": 0,
      "affected_installments": [
        {
          "installment_key": "2ef25ed8-7124-44f5-9e3d-1d1a7196166e",
          "due_date": "2022-05-01",
          "principal_amount": 100,
          "interest_amount": 20,
          "fine_amount": 5,
          "total_amount": 200,
          "present_amount": 140,
          "paid_amount": 140
        }
      ],
      "remaining_installments": [
        {
          "installment_key": "3da60b56-17fb-4b32-a1e4-1f0c28d18907",
          "due_date": "2022-08-01",
          "principal_amount": 100,
          "interest_amount": 20,
          "fine_amount": 5,
          "total_amount": 125
        }
      ]
    }
  ]
}
```

### Campos de desconto

Adicionar um destes campos na requisição permite definir um valor de desconto percentual ou absoluto na criação ou simulação da proposta de renegociação.

Desconto percentual

```json
{
  "discount_percentage": 0.5
}
```

Desconto absoluto

```json
{
  "discount_amount": 200
}
```

## 2. Criar uma renegociação em lote

:::caution ATENÇÃO
O Campo 'request_control_key' é livre e opcional e possui a finalidade de garantir a unicidade das requisições.
:::

### Request

ENDPOINT /renegotiation/batch_proposal
MÉTODO POST

Request Body

```json
{
    "amortization_type": "installment_payment",
    "reference_date": "2022-07-20",
    "proposal_due_date": "2022-07-20",
    "discount_percentage": 0.0,
    "payment_type": "bank_slip",
    "request_control_key": "4f75374c-e02f-4459-bddc-b9a7a0c9b0f3",
    "operations": [
      {
        "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
        "installments": [{
          "installment_key": "767f6ce0-add7-4334-a843-0e82cd1e7360"
        }]
      },
      {
        "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
        "installments": [{
          "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e89"
        }]
      }
  ]
}
```

:::warning Atenção
 Os campos `discount_amount` e `discount_percentage` **NÃO** podem ser enviados juntos no mesmo payload.
:::

### Body Params

| Campo                 | Tipo | Descrição                                                                                                                         | Caracteres                                                            |
|-----------------------|---|-----------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|  
| `debt_key`            | string | Chave única da operação de crédito dentro da QI.                                                                                  | UUID                                                                  |
| `amortization_type`   | string | Tipo de amortização.                                                                                                              | **[Enumeradores Amortization Type](#enumeradores-amortization-type)** |
| `reference_date`      | string | Data referencia a qual valor presente será calculado da renegociação (precisa ser D+1).                                           | 10                                                                    |
| `proposal_due_date`   | string | Data de vencimento da proposta de renegociação.                                                                                   | 10                                                                    |
| `payment_type`        | string | Tipo de pagamento.                                                                                                                | **[Enumeradores Payment Type](#enumeradores-payment-type)**           |
| `discount_percentage` | float | Percentual de desconto que será calculado sobre o valor presente da renegociação ((1 - percentual de desconto) * Valor Presente). | 10                                                                    |
| `discount_amount`     | float | Valor de desconto que será aplicado sobre o valor presente da renegociação (Valor Presente - Valor Bruto Descontado).             | 10                                                                    |
| `installments`        | array of objects | Parcelas renegociadas.                                                                                                            | **[Installments Object](#installments-object)**                       |

### Enumeradores Amortization Type

| Campo                           | Descrição                                                                                |
|---------------------------------|------------------------------------------------------------------------------------------| 
| **installment_payment**         | Será criada uma renegociação para o pagamento de parcelas distintas enviadas no payload. <br/><br/> Para a utilização deste amortization type, é necessário passar a `installment_key` da parcela. |
| **overdue_installment_payment** | Será criada uma renegociação direcionado para o pagamento de parcelas em atraso.<br/><br/> Para a utilização deste amortization type, é necessário passar a `installment_key` da parcela.          |

### Enumeradores Payment Type

| Campo    | Descrição                                                     | 
|----------|---------------------------------------------------------------|
| bankslip | Pagamento via boleto bancário (gera pagamento boleto e o Pix) | 
| pix      | Pagamento via Pix (gera apenas Pix)     |
| manual   | Pagamento feito de forma manual (não gera forma de pagamento) | 

### Installments Object

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|
| `installment_key` | string | key da parcela a ser renegociada | chave uuid |

### Response

Response Body

```json
{
  "batch_proposal_key": "bcc16a6d-ce21-4cd4-8d8c-d26f89ccc685",
  "batch_proposal_status": "pending_payment",
  "amortization_type": "installment_payment",
  "discount_percentage": 0.0,
  "discount_amount": 0.0,
  "payment_amount": 240,
  "requester_name": "Requester",
  "requester_key": "0193d113-9abd-4a13-8edb-2d94c2fdb70b",
  "issuer_name": "issuer",
  "reference_date": "2022-07-20",
  "proposal_due_date": "2022-07-20",
  "issuer_document_number": "98765432100",
  "payment_type": "bank_slip",
  "request_control_key": "4f75374c-e02f-4459-bddc-b9a7a0c9b0f3",
  "payment": {
    "digitable_line": "",
    "qr_code_url": "",
    "qr_code_key": "",
    "bank_slip_key": "",
    "paid_method_type": null
  },
  "operations": [
    {
      "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
      "payment_amount": 100,
      "discount_amount": 0,
      "affected_installments": [
        {
          "installment_key": "767f6ce0-add7-4334-a843-0e82cd1e7360",
          "due_date": "2022-05-01",
          "principal_amount": 100,
          "interest_amount": 20,
          "fine_amount": 5,
          "total_amount": 125,
          "present_amount": 100,
          "paid_amount": 100
        }
      ],
      "remaining_installments": [
        {
          "installment_key": "6807c8ee-8deb-40da-9b39-653d64ee8db7",
          "due_date": "2022-08-01",
          "principal_amount": 100,
          "interest_amount": 20,
          "fine_amount": 5,
          "total_amount": 125
        }
      ]
    },
     {
      "debt_key": "2cbfb9b1-1gdb-5g8d-9967-b338e5eb83g9",
      "payment_amount": 140,
      "discount_amount": 0,
      "affected_installments": [
        {
          "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e89",
          "due_date": "2022-05-01",
          "principal_amount": 100,
          "interest_amount": 20,
          "fine_amount": 5,
          "total_amount": 200,
          "present_amount": 140,
          "paid_amount": 140
        }
      ],
      "remaining_installments": [
        {
          "installment_key": "3da60b56-17fb-4b32-a1e4-1f0c28d18907",
          "due_date": "2022-08-01",
          "principal_amount": 100,
          "interest_amount": 20,
          "fine_amount": 5,
          "total_amount": 125
        }
      ]
    }
  ]
}
```

## 3. Listar renegociações em lote

### Path params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---|   
| `batch_proposal_status` * | string |  Status proposta de renegociação em lote. | - |
| `issuer_document_number` * | string |  Número de documento do emitente | - |
| `request_control_key` * | string |  Chave de identificação do solicitante | - |
 

### Request

ENDPOINT /renegotiation/batch_proposal
MÉTODO GET

Response Body

```json
{
    "data": [
        {
            "batch_proposal_key": "7eba74fb-e893-40ac-91bb-9a9d8f8108d7",
            "request_control_key": "cb55f099-d7cf-4b0a-9ddb-8e3ac3fefe8e",
            "batch_proposal_status": "pending_payment",
            "amortization_type": "installment_payment",
            "discount_percentage": 0,
            "discount_amount": 0.0,
            "payment_amount": 240,
            "requester_name": "Requester",
            "requester_key": "bcc16a6d-ce21-4cd4-8d8c-d26f89ccc685",
            "issuer_name": "issuer",
            "reference_date": "2022-07-25",
            "proposal_due_date": "2022-07-25",
            "issuer_document_number": "98765432100",
            "payment_type": "bank_slip"
        },
        {
            "batch_proposal_key": "272d1b0f-c06d-47c0-943b-812609ff2e6f",
            "request_control_key": "2ef25ed8-7124-44f5-9e3d-1d1a7196166e",
            "batch_proposal_status": "pending_payment",
            "amortization_type": "installment_payment",
            "discount_percentage": 0,
            "discount_amount": 0.0,
            "payment_amount": 240,
            "requester_name": "Requester",
            "requester_key": "bcc16a6d-ce21-4cd4-8d8c-d26f89ccc685",
            "issuer_name": "issuer",
            "reference_date": "2022-07-20",
            "proposal_due_date": "2022-07-20",
            "issuer_document_number": "98765432100",
            "payment_type": "bank_slip"
        }
    ],
    "pagination": {
        "current_page": 1,
        "next_page": 2,
        "rows_per_page": 2,
        "total_pages": 5,
        "total_rows": 140
    }
}
```

## 4. Consultar uma renegociação em lote

### Request

ENDPOINT /renegotiation/batch_proposal/BATCH-PROPOSAL-KEY
MÉTODO GET

Response Body

```json
{
  "batch_proposal_key": "7ac54a3e-fd11-46b2-b811-4c7d6d158fd5",
  "request_control_key": "61905b8b-3ed2-46bc-8e9c-a5e99ceaea37",
  "batch_proposal_status": "pending_payment",
  "amortization_type": "installment_payment",
  "discount_percentage": 0.0,
  "discount_amount": 0.0,
  "payment_amount": 240,
  "requester_name": "Requester",
  "requester_key": "bcc16a6d-ce21-4cd4-8d8c-d26f89ccc685",
  "issuer_name": "issuer",
  "reference_date": "2022-07-20",
  "proposal_due_date": "2022-07-20",
  "issuer_document_number": "98765432100",
  "payment_type": "bank_slip",
  "payment": {
    "digitable_line": "",
    "qr_code_url": "",
    "qr_code_key": "",
    "bank_slip_key": "",
    "paid_method_type": null
  },
  "operations": [
    {
      "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
      "payment_amount": 100,
      "discount_amount": 0,
      "affected_installments": [
        {
          "installment_key": "3da60b56-17fb-4b32-a1e4-1f0c28d18903",
          "due_date": "2022-05-01",
          "principal_amount": 100,
          "interest_amount": 20,
          "fine_amount": 5,
          "total_amount": 125,
          "present_amount": 100,
          "paid_amount": 100
        }
      ],
      "remaining_installments": [
        {
          "installment_key": "34f81236-e24a-4788-88e0-86cd697c36b7",
          "due_date": "2022-08-01",
          "principal_amount": 100,
          "interest_amount": 20,
          "fine_amount": 5,
          "total_amount": 125
        }
      ]
    },
     {
      "debt_key": "2cbfb9b1-1gdb-5g8d-9967-b338e5eb83g9",
      "payment_amount": 140,
      "discount_amount": 0,
      "affected_installments": [
        {
          "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e89",
          "due_date": "2022-05-01",
          "principal_amount": 100,
          "interest_amount": 20,
          "fine_amount": 5,
          "total_amount": 200,
          "present_amount": 140,
          "paid_amount": 140
        }
      ],
      "remaining_installments": [
        {
          "installment_key": "44cad2ae-60e9-4eb8-bb2a-b37e9557873f",
          "due_date": "2022-08-01",
          "principal_amount": 100,
          "interest_amount": 20,
          "fine_amount": 5,
          "total_amount": 125
        }
      ]
    }
  ]
}
```

### Request

ENDPOINT /renegotiation/batch_proposal/request_control_key/REQUEST-CONTROL-KEY
MÉTODO GET

Response Body

```json
{
  "batch_proposal_key": "7ac54a3e-fd11-46b2-b811-4c7d6d158fd5",
  "request_control_key": "61905b8b-3ed2-46bc-8e9c-a5e99ceaea37",
  "batch_proposal_status": "pending_payment",
  "amortization_type": "installment_payment",
  "discount_percentage": 0.0,
  "discount_amount": 0.0,
  "payment_amount": 240,
  "requester_name": "Requester",
  "requester_key": "bcc16a6d-ce21-4cd4-8d8c-d26f89ccc685",
  "issuer_name": "issuer",
  "reference_date": "2022-07-20",
  "proposal_due_date": "2022-07-20",
  "issuer_document_number": "98765432100",
  "payment_type": "bank_slip",
  "payment": {
    "digitable_line": "",
    "qr_code_url": "",
    "qr_code_key": "",
    "bank_slip_key": "",
    "paid_method_type": null
  },
  "operations": [
    {
      "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
      "payment_amount": 100,
      "discount_amount": 0,
      "affected_installments": [
        {
          "installment_key": "3da60b56-17fb-4b32-a1e4-1f0c28d18903",
          "due_date": "2022-05-01",
          "principal_amount": 100,
          "interest_amount": 20,
          "fine_amount": 5,
          "total_amount": 125,
          "present_amount": 100,
          "paid_amount": 100
        }
      ],
      "remaining_installments": [
        {
          "installment_key": "34f81236-e24a-4788-88e0-86cd697c36b7",
          "due_date": "2022-08-01",
          "principal_amount": 100,
          "interest_amount": 20,
          "fine_amount": 5,
          "total_amount": 125
        }
      ]
    },
     {
      "debt_key": "2cbfb9b1-1gdb-5g8d-9967-b338e5eb83g9",
      "payment_amount": 140,
      "discount_amount": 0,
      "affected_installments": [
        {
          "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e89",
          "due_date": "2022-05-01",
          "principal_amount": 100,
          "interest_amount": 20,
          "fine_amount": 5,
          "total_amount": 200,
          "present_amount": 140,
          "paid_amount": 140
        }
      ],
      "remaining_installments": [
        {
          "installment_key": "44cad2ae-60e9-4eb8-bb2a-b37e9557873f",
          "due_date": "2022-08-01",
          "principal_amount": 100,
          "interest_amount": 20,
          "fine_amount": 5,
          "total_amount": 125
        }
      ]
    }
  ]
}
```

## 5. Cancelamento de uma renegociação em lote

ENDPOINT /renegotiation/batch_proposal/BATCH-PROPOSAL-KEY
MÉTODO DELETE

### Response

ENDPOINT /renegotiation/batch_proposal/BATCH-PROPOSAL-KEY
MÉTODO DELETE
HTTP STATUS 204

Response Body

```json
    {}
```

## 6. Webhooks

## 6.1. Webhook de pagamento de renegociação em lote

Webhook Body

```json
{
    "webhook_type": "renegotiation.batch_proposal",
    "key": "\<BATCH-PROPOSAL-KEY\>",
    "event_datetime": "\<DATA E HORA DO ENVIO DO WEBHOOK\>",
    "status": "paid",
    "data": {
        "paid_method_type": "<METODO DE PAGAMENTO>",
        "paid_in": {
            "code_number": "<CODIGO DO BANCO LIQUIDANTE>",
            "ispb": "<ISPB DO BANCO LIQUIDANTE>",
            "name": "<NOME DO BANCO LIQUIDANTE>"
        }
    }
}
```

## 6.2. Webhook de rejeição de renegociação em lote

:::caution ATENÇÃO
Uma renegociação em lote pode ser rejeitada pelo decurso de prazo do pagamento ou por um pagamento de parcela por fora da renegociação.
:::

Webhook Body

```json
{
    "webhook_type": "renegotiation.batch_proposal",
    "key": "\<BATCH-PROPOSAL-KEY\>",
    "event_datetime": "\<DATA E HORA DO ENVIO DO WEBHOOK\>",
    "status": "rejected",
    "data": {}
}
```

## 6.3. Exemplo de payment data da installment paga através de renegociação em lote

Webhook Body

```json
{
    "batch_renegotiation_proposal_key": "f9addba2-ec91-41bf-a150-c59eb1c3fbef",
    "paid_in": {
        "ispb": "18236120",
        "name": "NU PAGAMENTOS - IP",
        "code_number": 260
    },
    "resource_account_key": "ea44b9f2-ad00-4896-b8a3-b1a3da28a72f"
}
```

---

# Simulação com valor por parcela

URL: /documentation/renegociacao/simulacao_com_valor_por_parcela

## Request

ENDPOINT /renegotiation/simulation
MÉTODO POST

Request Body

```json
{
    "contract_number": "ABCD/1",
    "amortization_type": "installment_payment",
    "reference_date": "2022-07-20",
    "installments": [
        {
            "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88",
            "paid_amount": 150
        }
    ]
}

```

### Body params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---| 
| `contract_number` | string | Numero do contrato. | 10 |
| `amortization_type` | string | Tipo de amortização. | 10 |
| `reference_date` | date | Data de referencia da renegociação. | 10 |
| `installments` | array of objects | Parcelas renegociadas. | **[Installments Object](#installments-object)**  |
 
### Installments Object

| Campo | Descrição |
|---|---|
| `installment_key` * | string | key da parcela a ser renegociada | 10 |
| `paid_amount` * | float | Valor a ser pago da parcela renegociada. | 10 |

## Response

STATUS 200

Response Body

```json
{
  "contract_number": "ABCD/1",
  "discount_percentage": 0.2,
  "payment_amount": 240,
  "reference_date": "2022-07-20",
  "proposal_due_date": "2022-07-20",
  "requester_name": "Requester",
  "amortization_type": "installment_payment",
  "requester_key": "bcc16a6d-ce21-4cd4-8d8c-d26f89ccc685",
  "issuer_name": "issuer",
  "issuer_document_number": "98765432100",
  "affected_installments": [
    {
      "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88",
      "due_date": "2022-05-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125,
      "present_amount": 100,
      "paid_amount": 80
    },
    {
      "installment_key": "6597a073-ea7a-4447-b250-f4d3f07b0b74",
      "due_date": "2022-06-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125,
      "present_amount": 100,
      "paid_amount": 80
    },
    {
      "installment_key": "3da60b56-17fb-4b32-a1e4-1f0c28d18900",
      "due_date": "2022-07-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125,
      "present_amount": 100,
      "paid_amount": 80
    }
  ],
  "remaining_installments": [
    {
      "installment_key": "3da60b56-17fb-4b32-a1e4-1f0c28d18903",
      "due_date": "2022-08-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125
    },
    {
      "installment_key": "3da60b56-17fb-4b32-a1e4-1f0c28d18904",
      "due_date": "2022-09-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125
    },
    {
      "installment_key": "3da60b56-17fb-4b32-a1e4-1f0c28d18905",
      "due_date": "2022-10-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125
    }
  ]
}
```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

---

# Simulação de uma renegociação

URL: /documentation/renegociacao/simulacao_de_uma_renegociacao

## Request

ENDPOINT /renegotiation/simulation
MÉTODO POST

Request Body

 Exemplos de payloads utilizando amortization_types diferentes

**Usando chaves de parcelas**

```json
{
  "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
  "amortization_type": "installment_payment",
  "reference_date": "2022-07-20",
  "discount_amount": 100,
  "installments": [
    {
      "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88"
    },
    {
      "installment_key": "0ff87136-b084-44fb-8fc2-d2e3beed483b"
    },
    {
      "installment_key": "e4101c6a-51b3-435f-a2b7-4a65a005cc15"
    }
  ]
}
```

**Usando número de parcelas**

```json
{ 
  "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
  "amortization_type": "first_installments",
  "reference_date": "2022-07-20",
  "discount_percentage": 0.2,
  "discount_amount": 100,
  "number_of_installments": 4
}
```

**Usando valor de amortização**

```json
{
  "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
  "amortization_type": "first_installments",
  "reference_date": "2022-07-20",
  "payment_amount": 900
}
```

:::warning Atenção
Os campos `discount_amount`, `discount_percentage` e `paid_amount` (por parcela) são mutuamente exclusivos — envie exatamente um deles.
:::

:::info `total_amount` vs `present_amount` no response
O response retorna ambos por parcela: `present_amount` é o valor descontado para hoje (base do `installment_payment` sem `paid_amount`); `total_amount` é o valor de face. Para cobrar sem desconto de antecipação, use `total_amount` como `paid_amount` na criação da proposta.
:::

### Body Params 

| Campo | Tipo | Descrição                                                                                                                         | Caracteres                                                            |
|---|---|-----------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|  
| `debt_key`            | string | Chave única da operação de crédito dentro da QI.                                                                                  | UUID                                                                  |
| `amortization_type` | string | Tipo de amortização.                                                                                                              | **[Enumeradores Amortization Type](#enumeradores-amortization-type)** |
| `reference_date` | string | Data referencia a qual valor presente será calculado da renegociação (precisa ser D+1).                                           | 10                                                                    |
| `proposal_due_date` | string | Data de vencimento da proposta de renegociação.                                                                                   | 10                                                                    |
| `payment_type` | string | Tipo de pagamento.                                                                                                                | **[Enumeradores Payment Type](#enumeradores-payment-type)**           |
| `payment_amount` | float | Valor final renegociado na proposta.                                                                                              | -                                                                     |
| `number_of_installments` | int | Número de Parcelas renegociadas na proposta.                                                                                      | 10                                                                    |
| `discount_percentage` | float | Percentual de desconto que será calculado sobre o valor presente da renegociação ((1 - percentual de desconto) * Valor Presente). | 10                                                                    |
| `discount_amount` | float | Valor de desconto que será aplicado sobre o valor presente da renegociação (Valor Presente - Valor Bruto Descontado).             | 10                                                                    |
| `installments` | array of objects | Parcelas renegociadas.                                                                                                            | **[Installments Object](#installments-object)**                       |

### Installments array of objects

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---| 
| `installment_key` | string | key da parcela a ser renegociada | chave uuid |

### Enumeradores Amortization Type
 Campo                           | Descrição                                                                                                                                                                                                                                   |
|---------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 
| **installment_payment**         | Será criada uma renegociação para o pagamento de parcelas distintas enviadas no payload. <br/><br/> Para a utilização deste amortization type, é necessário passar a `installment_key` da parcela.                                                |
| **overdue_installment_payment** | Será criada uma renegociação direcionado para o pagamento de parcelas em atraso.<br/><br/> Para a utilização deste amortization type, é necessário passar a `installment_key` da parcela.                                                     |
| **first_installments**          | Será criada uma renegociação que pagará as primeiras parcelas, em status aberto. <br/><br/> Este amortization type pode ser utilizado passando tanto a quantidade de parcelas que deseja quitar (`number_of_installments`), quanto o valor que o tomador deseja pagar `payment_amount`). 

## Response

STATUS 201

Response Body

```json
{
  "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
  "discount_percentage": 0.2,
  "payment_amount": 240,
  "origin_key": "76912b4b-508a-4b10-9485-0e87f1316b35",
  "reference_date": "2022-07-20",
  "proposal_due_date": "2022-07-20",
  "requester_name": "Requester Name",
  "amortization_type": "installment_payment",
  "requester_key": "bcc16a6d-ce21-4cd4-8d8c-d26f89ccc685",
  "issuer_name": "issuer",
  "issuer_document_number": "98765432100",
  "affected_installments": [
    {
      "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88",
      "due_date": "2023-01-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125,
      "present_amount": 100,
      "paid_amount": 80
    },
    {
      "installment_key": "0ff87136-b084-44fb-8fc2-d2e3beed483b",
      "due_date": "2022-12-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125,
      "present_amount": 100,
      "paid_amount": 80
    },
    {
      "installment_key": "e4101c6a-51b3-435f-a2b7-4a65a005cc15",
      "due_date": "2022-11-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125,
      "present_amount": 100,
      "paid_amount": 80
    }
  ],
  "remaining_installments": [
    {
      "installment_key": "03b4d86a-9dba-40fc-a4db-33e8772b7be8",
      "due_date": "2022-08-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125
    },
    {
      "installment_key": "c622efa6-8731-464b-a563-a7a26c19279d",
      "due_date": "2022-09-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125
    },
    {
      "installment_key": "3da60b56-17fb-4b32-a1e4-1f0c28d18905",
      "due_date": "2022-10-01",
      "principal_amount": 100,
      "interest_amount": 20,
      "fine_amount": 5,
      "total_amount": 125
    }
  ]
}
```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

---

# Update de um pagamento manual

URL: /documentation/renegociacao/update_de_um_pagamento_manual

## Request

- ENDPOINT /renegotiation/proposal/proposal_key}/payment
- MÉTODO PATCH

Body.json

```json
{
   "paid_method_type": "bank_slip"
}

```

### Query params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---| 
| `proposal_status` |  Tipo |  Chave da proposta de renegociação. | 10 |

### Body params

| Campo | Tipo | Descrição | Caracteres |
|---|---|---|---| 
| `paid_method_type` | Tipo |  Meio de pagamento. | **[Enumeradores](#enumeradores-paid_method_type)**  |

### Enumeradores paid_method_type
| Campo |  Descrição | 
|---|---|
| banklisp | Pagamento via boleto bancário | 
| manual | Pagamento feito de forma manual | 
| pix | Pagamento via pix | 

## Response

STATUS 200

Response Body

```json
{

}
```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

---

# Roteiro de Homologação - Circuito de Compras

URL: /documentation/roteiros_de_homologacao/circuito_dd46f8d3-f078-41ba-a311-55be848f1c69

O roteiro de homologação descreve todos os recursos e funcionalidades que precisam
ser testados pelo parceiro integrador no ambiente de sandbox da QI Tech (ambiente de testes), 
antes da entrada em ambiente de produção do produto.

Este roteiro descreve todos os recursos e funcionalidades envolvidos no produto. 
:::info ATENÇÃO
As etapas sinalizadas com * são obrigatórias para a entrada em produção
:::

⚠️ **Todos os testes devem ser obrigatoriamente realizados no ambiente de Sandbox da QI Tech (ambiente de testes).
As movimentações realizadas em ambiente de Sandbox são movimentações financeiras fictícias, servindo apenas para teste de funcionalidade das APIs.**

## Cadastro e Autenticação API BaaS
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| CAB0001* | Cadastro no ambiente de Sandbox | Realizar o cadastro na plataforma da QI Tech no ambiente de Sandbox (sandbox.qitech.app) | [Link documentação](/documentation/primeiros_passos/inicio) 
| CAB0002* | Validação de token em Sandbox | Realizar a validação do QI Token em Sandbox | [Download Manual de Inclusão do Token](https://docs.qitech.com.br/assets/pdfs/QI%20Tech%20Manual%20Inclus%C3%A3o%20de%20Token.pdf) | CAB0001 |
| CAB0003* | Troca de chaves públicas | Realizar a troca de chaves públicas dentro da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Link Documentação](/documentation/primeiros_passos/troca_de_chaves) | CAB0001 e CAB0002 |
| CAB0004* | Teste de autenticação de chamadas | Finalizar teste de autenticação de chamadas | [Passo a Passo](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2) <br/><br/> [Link Documentação](/documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste) | CAB0003 |
| CAB0005* | Configuração de webhooks | Realizar a configuração da url para envio dos webhooks por parte da QI, através da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Link Documentação](/documentation/primeiros_passos/configurando_webhooks) | CAB0001 e CAB0002 |

## Movimentações
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
|---------|--|---|---|---|
| QIC0008* | Consulta de Transações | Realizar a consulta das transações de uma conta | [Consulta de Transações](/documentation/movimentacao_de_contas/consulta_de_transacoes) ||
| QIC0009 | Solicitação de comprovante de transferência | Solicitação de comprovante de transferência | [Solicitar comprovante de transferência](/documentation/movimentacao_de_contas/comprovante_de_transferencia) | PIX0002 |
| QIC0010* | Leitura de webhooks de transação | Recepcionar com sucesso todos os webhooks de transação | [Webhook account_transaction](/documentation/movimentacao_de_contas/webhook_movimentacoes) | CAB0005 e PIX0002 |
| QIC0011 | Consulta de lista de instituições financeiras | Consultar lista de instituições financeiras habiliatadas para recebimento de TED e Pix | [Consulta de Instituições Financeiras](/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras) ||

# TED

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| TED0001* | Transferência TED Out | Realizar transferência TED para outra instituição financeira | [Link Documentação](/documentation/baas/ted/realizar_transferencia) | CAB0002 ou CAB0003 |
| TED0002* | Simulação de estorno de uma TED Out | Simular o estorno de uma TED Out enviada a partira de uma QI Conta | Item 3: <br/>[Link Documentação](/documentation/movimentacao_de_contas/transacao#3---simula%C3%A7%C3%A3o-de-devolu%C3%A7%C3%A3o-de-ted) | TED0001 |
| TED0003* | Simulação de TED In | Simular a entrada de uma TED In em uma QI conta | Item 2: <br/>[Link Documentação](/documentation/movimentacao_de_contas/transacao#2---simula%C3%A7%C3%A3o-de-entrada-de-ted) | CAB0002 ou CAB0003 |
| TED0004* | Consulta de transações TED| Realizar a consulta de uma transação TED  | [Link Documentação](/documentation/movimentacao_de_contas/consulta_de_transacoes) | CAB0002 ou CAB0003 |
| TED000* | Leitura de webhooks de TED| Recepcionar com sucesso um webhook de TED | [Link Documentação](/documentation/baas/ted/webhooks) | CAB0002 ou CAB0003 |

---

# Boletos

## Gestão de Boletos

| Nº | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| BOL0002* | Registro de boleto de cobrança | Realizar o registro de um boleto de cobrança enviando uma ocorrência de registro | [Link Documentação](/documentation/boletos/emissao/emissao_via_json) | CAB0002 ou CAB0003, |
| BOL0003 | Consultar carteira de cobrança de boletos | Consultar as carteiras de cobrança disponíveis para registro de boletos | [Link Documentação](/documentation/boletos/consultar/consulta_de_carteira) | CAB0002 ou CAB0003 |
| BOL0004* | Instrução de boleto de cobrança | Comandar uma instrução para um boleto registrado | [Link Documentação](/documentation/boletos/enviar_instrucao_de_boleto) | BOL0002 |
| BOL0005 | Simulação de liquidação de boleto | Simular a liquidação de um boleto | [Link Documentação](/documentation/boletos/pagamento/liquidacao) | BOL0002 |
| BOL0006* | Leitura de webhooks de boletos | Recepcionar com sucesso todos os webhooks relacionados às alterações de status de um boleto | [Link Documentação](/documentation/webhooks/boletos) | BOL0004 |

## Pagamento de Boletos

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| BOL0009* | Consulta de linha digitável | Realizar a consulta de uma linha digitável de um boleto bancário ou boleto convênio. | [Link Documentação](/documentation/boletos/pagamento/consulta_linha_digitavel) |  |
| BOL0010* | Pagamento de um boleto | Realizar o pagamento de um boleto bancário ou de boleto de convênio | Item 7.5 <br/>[Link Documentação](/documentation/boletos/pagamento/realizar_pagamento) | CAB0002 ou CAB0003 |

---

## Pix

## Transferência Pix 
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
|---------|--|---|---|---|
| PIX0002* | Transferência Pix Out | Realizar uma transferência Pix a partir de uma QI Conta utilizando dados bancários (pix manual) ou chave Pix | [Realização de Transação Pix](/documentation/baas/pix/realizar_transferencia)||
| PIX0035 | Consulta de transferência pix | Recuperar os dados de uma transferência | [Consulta de transferência Pix](/documentation/baas/pix/consultar_transferencias) | PIX0002 |
| PIX0003* | Simulação de reembolso de Pix Out | Simular o reembolso de um Pix Out. | [Simulação reembolso Pix Out -> Item 2](/documentation/pix/simulacao)| PIX0002 |
| PIX0004* | Simulação de Pix In | Simular o crédito de um Pix In em uma QI Conta. | [Simulação Pix In -> Item 1](/documentation/pix/simulacao)||
| PIX0005* | Reembolso de Pix In | Realizar o reembolso de um Pix In a partir de uma QI Conta. | [Reembolso Pix In](/documentation/baas/pix/solicitar_devolucao)| PIX0004 |
| PIX0037* | Leitura de webhook de transação pendente | Recepcionar com sucesso um webhook de transação pendente | [Webhook de transação pendente](/documentation/baas/pix/webhooks/index.html#webhook-para-transa%C3%A7%C3%B5es-pendentes) | PIX0002 |
| PIX0038* | Leitura de webhook de Pix de In | Recepcionar com sucesso um webhook de transferência Pix de entrada | [Webhook Pix In](/documentation/baas/pix/webhooks/index.html#webhook-para-pix-de-entrada) | PIX0004 |
| PIX0039 | Leitura de webhook de Devolução Pix | Recepcionar com sucesso um webhook de devolução de um Pix | [Webhook Devolução Pix](/documentation/baas/pix/webhooks/index.html#webhook-para-devolu%C3%A7%C3%B5es-de-pix) | PIX0003 |

## Pagamento de QR Code Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0029* | Pagamento de QR Code Pix Estático | Realizar o pagamento de um QR Code Pix Estático | Item 4.1: [Link Documentação](/documentation/baas/pix/realizar_transferencia#transfer%C3%AAncia-por-qr-code-pix) | PIX0022 |
| PIX0030* | Pagamento de QR Code Pix Dinâmico | Realizar o pagamento de um QR Code Pix Dinâmico | Item 4.2: [Link Documentação](/documentation/baas/pix/realizar_transferencia#transfer%C3%AAncia-por-qr-code-pix) | PIX0022 |

---

# Roteiro de Homologação - BaaS Conta Digital

URL: /documentation/roteiros_de_homologacao/conta_digital

O roteiro de homolgoação descreve todos os recursos e funcionalidades que precisam
ser testados pelo parceiro integrador no ambiente de sandbox da QI Tech (ambiente de testes), 
antes da entrada em ambiente de produção do produto.

Este roteiro descreve todos os recursos e funcionalidades envolvidos no produto. 

⚠️ **Todos os testes devem ser obrigatoriamente realizados no ambiente de Sandbox da QI Tech (ambiente de testes).
As movimentações realizadas em ambiente de Sandbox são movimentações financeiras fictícias, servindo apenas para teste de funcionalidade das APIs.**

## Cadastro e Autenticação API BaaS
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| CAB0001* | Cadastro no ambiente de Sandbox | Realizar o cadastro na plataforma da QI Tech no ambiente de Sandbox (sandbox.qitech.app) | cs@qitech.com.br |
| CAB0002* | Validação de token em Sandbox | Realizar a validação do QI Token em Sandbox | [Link Documentação](https://docs.qitech.com.br/assets/pdfs/QI%20Tech%20Manual%20Inclus%C3%A3o%20de%20Token.pdf) | CAB0001 |
| CAB0003* | Troca de chaves públicas | Realizar a troca de chaves públicas dentro da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Link Documentação](/documentation/primeiros_passos/troca_de_chaves) | CAB0001 e CAB0002 |
| CAB0004* | Teste de autenticação de chamadas | Finalizar teste de autenticação de chamadas |[Link Documentação](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2) <br/><br/> [Link Documentação](/documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste) | CAB0003 |
| CAB0005* | Configuração de webhooks | Realizar a configuração da url para envio dos webhooks por parte da QI, através da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Link Documentação](/documentation/primeiros_passos/configurando_webhooks) | CAB0001 e CAB0002 |

## Antifraude

## Cadastro e Autenticação

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| ATF0002* | Obtenção de API-key de onboarding | Obter junto ao time de integração da QI Tech a chave de API para uso da API de /onboarding | suporte.caas@qitech.com.br |  
| ATF0003* | Obtenção de mobile-token de OCR | Obter junto ao time de integração da QI Tech o Mobile Token  para uso do SDK de OCR | suporte.caas@qitech.com.br |  
| ATF0004* | Obtenção de mobile-token de Face Recognition | Obter junto ao time de integração da QI Tech o Mobile Token  para uso do SDK de Face Recognition | suporte.caas@qitech.com.br |  
| ATF0005* | Obtenção de mobile-token de Device scan | Obter junto ao time de integração da QI Tech o Mobile Token  para uso do SDK de Device scan | suporte.caas@qitech.com.br |  

## SDK OCR

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| ATF0007* | Build do SDK | Definir o template e customizações para coleta dos documentos e buildar o SDK com sucesso dentro da sua aplicação (aplicação do cliente QI Tech) | Android: [Link Documentação](/documentation/caas/ocr/android/introduction) <br/> iOS:[ Link Documentação](/documentation/caas/ocr/ios/introduction) |  |
| ATF0008* | Envio de documentos | Realizar a coleta de documentos utilizando o SDK dentro da sua aplicação (aplicação cliente QI Tech) |  | ATF0003 e ATF0007 |
| ATF0009* | Armazenamento de ocr_key | Armazenar as chaves retornadas pelo SDK, identificando a natureza do documento coletado (ex: cnh_front, cnh_back, etc) | Android: [Link Documentação](/documentation/caas/ocr/android/collecting_response) <br/>iOS:[ Link Documentação](/documentation/caas/ocr/ios/collecting_response)| ATF0008 |

## SDK Face Recognition

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| ATF0011* | Build do SDK | Definir customizações e buildar o SDK com sucesso dentro da sua aplicação (aplicação do cliente QI Tech) |Android: [Link Documentação](/documentation/caas/face_recognition/android/introduction) <br/>iOS:[ Link Documentação](/documentation/caas/face_recognition/ios/introduction)  |  |
| ATF0012* | Fluxo de prova de vida | Realizar o fluxo de prova de vida utilizando o SDK dentro da sua aplicação (aplicação cliente QI Tech) | | ATF0004 e ATF0011* |
| ATF0013* | Armazenamento de chave de imagem | Armazenar a image_key retornada pelo SDK após finalização do fluxo de prova de vida | Android: [Link Documentação](/documentation/caas/face_recognition/android/collecting_response) iOS:[ Link Documentação](/documentation/caas/face_recognition/ios/collecting_response) | ATF0012 |

## SDK Device Scan

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| ATF0015* | Build do SDK | Definição das permissões a serem solicitadas ao usuário por sua aplicação (aplicação do cliente QI Tech) e buildar o SDK com sucesso dentro da sua aplicação (aplicação do cliente QI Tech) | Android: [Link Documentação](/documentation/caas/device_scan/android/introduction)<br/>iOS:[ Link Documentação](/documentation/caas/device_scan/ios/introduction)|  
| ATF0016* | Armazenamento da sessão do usuário | Realizar o armazenamento da sessão do usuário (sessionId) que terá o dispositivo escaneado | Android: [Link Documentação](/documentation/caas/device_scan/android/example)<br/>iOS:[ Link Documentação](/documentation/caas/device_scan/ios/example) | ATF0015 e ATF0017 |
| ATF0017* | Coleta de informações | Instanciar o SDK com o sessionId armazenado e chamar o método de coleta de informações dentro de sua aplicação (aplicação do cliente QI Tech) | Android: [Link Documentação](/documentation/caas/face_recognition/android/collecting_response)<br/>iOS:[ Link Documentação](/documentation/caas/face_recognition/ios/collecting_response) | ATF0005 e ATF0015 |

## Antifraude

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| ATF0019* | Antifraude PF | Realizar com sucesso o antifraude de uma cliente pessoa física | [Link Documentação](/documentation/caas/onboarding/natural_person) | ATF0002 |
| ATF0020* | Antifraude PJ | Realizar com sucesso o antifraude de uma cliente pessoa jurídica | [Link Documentação](/documentation/caas/onboarding/legal_person) | ATF0002 |
| ATF0021* | Leitura de webhooks de analises derivadas para fluxo assíncrono | Recepcionar com sucesso o webhook de análise derivada para o fluxo de resposta assíncrona |[Link Documentação](/documentation/caas/onboarding/webhook) | ATF0019 ou ATF0020 |

## Cadastro Plataforma

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| ATF0022* | Cadastro de usuário Master | Realizar o cadastro de um usuário Master na plataforma do CaaS, para resolução de solicitações derivadas para “Análise manual”  | suporte.caas@qitech.com.br | ATF0019 ou ATF0020 |

---

# **QI Conta**

## Abertura de Conta

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| QIC0002* | Reserva de conta PF | Solicitar a reserva de uma conta cujo titular seja uma pessoa física | [Link Documentação](/documentation/baas/account/reservar_conta_pf) | CAB0005 e CAB0006 |
| QIC0003* | Abertura de conta PF | Realizar a abertura de uma conta cujo titular seja uma pessoa física | [Link Documentação](/documentation/baas/account/abrir_conta_pf) | QIC0002 |
| QIC0004* | Reserva de conta PJ | Solicitar a reserva de uma conta cujo titular seja uma pessoa jurídica | [Link Documentação](/documentation/baas/account/reservar_conta_pj) | CAB0005 e CAB0006 |
| QIC0005* | Abertura de conta PJ | Realizar a abertura de uma conta cujo titular seja uma pessoa jurídica | [Link Documentação](/documentation/baas/account/abrir_conta_pj) | QIC0004 |
| QIC0006* | Leitura de webhooks de abertura de conta | Ler corretamente os webhooks de abertura de conta | Item 1.2. ou 1.3:<br/>[Link Documentação](/documentation/baas/account/webhooks) |  QIC0002 ou QIC0002  |
| QIC0007* | Listar contas | Listar contas abertas| [Link Documentação](/documentation/contas/consultar_conta) |  QIC0002 ou QIC0002  |
| QIC0008* | Consulta de dados de uma conta | Consultar dados como saldo, dados do titular, data de abertura, dentre outros | [Link Documentação](/documentation/contas/consultar_conta) |  QIC0002 ou QIC0002  |

## Movimentações

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| QIC0008* | Consulta de Extrato | Realizar a consulta do extrato de uma conta | [Link Documentação](/documentation/movimentacao_de_contas/consulta_de_transacoes) |  QIC0002 ou QIC0002  |
| QIC0009* | Solicitação de comprovante de transferência | Solicitar um comprovante de transferência | [Link Documentação](/documentation/movimentacao_de_contas/comprovante_de_transferencia)|  |
| QIC0010* | Leitura de webhooks de transação | Recepcionar com sucesso todos os webhooks de transação |  [Link Documentação](/documentation/movimentacao_de_contas/webhook_movimentacoes/index.html) |  QIC0002 ou QIC0002  |
| QIC0011* | Consulta de lista de instituições financeiras | Consultar lista de instituições financeiras habiliatadas para recebimento de TED e Pix |  [Link Documentação](/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras) |  QIC0002 ou QIC0002  |

---

# Upload de Documentos

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| UDD0001* | Upload de documento | Realizar o upload de um documento através da nossa API de documentos |  [Link Documentação](/documentation/upload_de_documentos/) |  |

---

# TED

| Código | Etapa | Descrição | Link                                                                                                        | Pré-requisito |
| --- | --- | --- |-------------------------------------------------------------------------------------------------------------| --- |
| TED0001* | Transferência TED Out | Realizar transferência TED  | [Link Documentação](/documentation/baas/ted/realizar_transferencia) | QIC0002 ou QIC0002 |
| TED0002* | Simulação de estorno de uma TED Out | Simular o estorno de uma TED Out enviada a partira de uma QI Conta | Item 3: <br/>[Link Documentação](/documentation/movimentacao_de_contas/transacao) |  |
| TED0003* | Simulação de TED In | Simular a entrada de uma TED In em uma QI conta | Item 2: <br/>[Link Documentação](/documentation/movimentacao_de_contas/transacao) | QIC0002 ou QIC0002 |
| TED0004* | Listar transações TED| Listar transações TED de entrada/saída  | [Link Documentação](/documentation/baas/ted/listar_teds)  | QIC0002 ou QIC0002 |
| TED0004* | Consulta de transação  TED| Realizar a consulta de uma transação TED  | [Link Documentação](/documentation/baas/ted/consultar_ted)           | QIC0002 ou QIC0002 |
| TED0006* | Leitura de webhooks de TED| Recepcionar com sucesso um webhook de TED | [Link Documentação](/documentation/baas/ted/webhooks/index.html)| QIC0002 ou QIC0002 |
---

# Transferência Interna

| Nº | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| TFI0001 | Transferência Interna com débito em conta | Comandar uma transferência a partir de uma QI Conta, tendo como destino da transferência, outra QI Conta | [Link Documentação](/documentation/baas/ted/realizar_transferencia) |  QIC0002 ou QIC0002  |
| TFI0002 | Simulação de transferência Interna com crédito em conta | Simular o recebimento de recursos na QI Conta alvo, tendo como origem, outra QI Conta | Item 1: <br/> [Link Documentação](/documentation/movimentacao_de_contas/transacao) |  QIC0002 ou QIC0002  |

---

# Boletos

## Gestão de Boletos

| Nº | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| Nº      | Etapa | Descrição | Link  | Pré-requisito |
|---|---|---|---|---|
| BOL0001 | Registro de boleto de um único boleto cobrança    | Realizar o registro de um boleto de cobrança | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao/index.html) | CAB0002 ou CAB0003   |
| BOL0002 | Registro de boleto de um único boleto de cobrança instantâneo | Realizar o registro de um boleto de cobrança | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) | CAB0002 ou CAB0003   |
| BOL0003 | Registro de boleto de boleto em lote  | Realizar o registro de boleto de cobrança em lote | [Link Documentação](/documentation/boletos/v2/emissao/emissao_em_lote) | CAB0002 ou CAB0003   |
| BOL0004 | Emissão de Boleto Único Padrão        | Emitir um boleto único padrão    | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao)  | CAB0002 ou CAB0003   |
| BOL0005 | Emissão de Boleto Único Instantâneo   | Emitir um boleto único instantân | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) | CAB0002 ou CAB0003   |
| BOL0006 | Emissão em Lote   | Emitir boletos em lote | [Link Documentação](/documentation/boletos/v2/emissao/emissao_em_lote)| CAB0002 ou CAB0003   |
| BOL0007 | Realizar abatimento no valor de um boleto | Realizar abatimento no valor de um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/abatimento/criar_abatimento) | BOL0001, BOL0002 ou BOL0003 |
| BOL0008 | Cancelar Abatimento     | Cancelar abatimento em um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/abatimento/cancelar_abatimento) | BOL0001, BOL0002 ou BOL0003  |
| BOL0009 | Estender vencimento de um boleto               | Enviar extensão de prazo de um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/extensao)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0010 | Incluir desconto em um boleto               | Incluir desconto em um boleto    | [Link Documentação](/documentation/boletos/v2/instrucoes/desconto)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0011 | Incluir juros em um boleto                   | Incluir juros em um boleto       | [Link Documentação](/documentation/boletos/v2/instrucoes/juros)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0012 | Incluir multa em um boleto                   | Incluir multa em um boleto       | [Link Documentação](/documentation/boletos/v2/instrucoes/multa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0013 | Realizar baixa de um boleto                   | Baixar um boleto                 | [Link Documentação](/documentation/boletos/v2/instrucoes/baixa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0014 | Consultar boletos por chave      | Consultar boletos por chave      | [Link Documentação](/documentation/boletos/v2/consulta/consulta_por_chave) | BOL0001, BOL0002 ou BOL0003   |
| BOL0015 | Listar Boletos          | Listar boletos     | [Link Documentação](/documentation/boletos/v2/consulta/listar_boletos) | BOL0001, BOL0002 ou BOL0003   |
| BOL0016 | Consulta de carteira de cobrança      | Consultar uma carteira de cobrança | [Link Documentação](/documentation/boletos/v2/carteira/listar_carteiras/index.html) | BOL0001, BOL0002 ou BOL0003   |
| BOL0017 | Webhooks de Boleto      | Realizar a leitura de webhook para boleto | [Link Documentação](/documentation/boletos/v2/webhooks/boleto) | BOL0001, BOL0002 ou BOL0003   |

## Pagamento de Boletos

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| BOL0009* | Consulta de linha digitável ou Código de Barras | Realizar a consulta de uma linha digitável de um boleto bancário | [Link Documentação](/documentation/baas/cobranca/consultar_boleto_bancario) |  |
| BOL0010* | Realizar pagamento de um boleto | Realizar o pagamento de um boleto bancário | [Link Documentação](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_boleto_bancario) |  QIC0002 ou QIC0002  |
| BOL0012* | Consulta de linha digitável ou Código de Barras de um boleto de convênio | Realizar a consulta de uma linha digitável de um  boleto convênio. | [Link Documentação](/documentation/baas/cobranca/consultar_fatura_de_recolhimento) |  |
| BOL0013* | Realizar pagamento de um boleto de convênio | Realizar o pagamento de um boleto convênio | [Link Documentação](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_fatura_de_recolhimento) |  QIC0002 ou QIC0002  |

---

## Pix

## Transferência Pix 
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
|---------|--|---|---|---|
| PIX0002* | Transferência Pix Out | Realizar uma transferência Pix a partir de uma QI Conta utilizando dados bancários (pix manual) ou chave Pix | [Link Documentação](/documentation/baas/pix/realizar_transferencia) | CAB0001 |
| PIX0035 | Consulta de transferência pix | Recuperar os dados de uma transferência | [Link Documentação](/documentation/baas/pix/consultar_transferencias) | PIX0002 |
| PIX0003* | Simulação de reembolso de Pix Out | Simular o reembolso de um Pix Out. | [Link Documentação - Item 2](/documentation/pix/simulacao)| PIX0002 |
| PIX0004* | Simulação de Pix In | Simular o crédito de um Pix In em uma QI Conta. | [Link Documentação -> Item 1](/documentation/pix/simulacao)||
| PIX0037* | Leitura de webhook de transação pendente | Recepcionar com sucesso um webhook de transação pendente | [Link Documentação][(/documentation/baas/pix/webhooks) | PIX0002 |
| PIX0038* | Leitura de webhook de Pix de In | Recepcionar com sucesso um webhook de transferência Pix de entrada | [Link Documentação](/documentation/baas/pix/webhooks#webhook-para-pix-de-entrada)| PIX0004 |
| PIX0039 | Leitura de webhook de Devolução Pix | Recepcionar com sucesso um webhook de devolução de um Pix | [Link Documentação](/documentation/baas/pix/webhooks#webhook-para-devolu%C3%A7%C3%B5es-de-pix) | PIX0003 |
| PIX0040 | Solicitar a devolução de um Pix recebido | Solicitar a devolução de um Pix recebido | [Link Documentação](/documentation/baas/pix/solicitar_devolucao) | PIX0003 |
| PIX0041 | Listar transferências Pix de uma conta | Listar transferências Pix de uma conta | [Link Documentação](/documentation/baas/pix/listar_transferencias) | PIX0003 |

## Gestão de Chave Pix

### Criação e Exclusão de Chave pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0008* | Criação de chave Pix | Realizar a criação de chave Pix do tipo cpf, cnpj, aleatória, e-mail e telefone | [Link Documentação](/documentation/pix/criar_chave) | 
|QIC0002 ou QIC0002  |](/documentation/baas/pix/consultar_chave_pix)
| PIX0009 | Exclusão de chave Pix | Realizar a exclusão de uma chave Pix | [Link Documentação](/documentation/pix/excluir_chave) | PIX0008 |
| PIX0010* | Listagem de chaves Pix de uma QI Conta | Listar chaves Pix vinculadas a uma QI Conta | [Link Documentação](/documentation/pix/listar_chaves_pix) | PIX0008 |

### Portabilidade de Chave Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0013* | Criação de Solicitação de Portabilidade In de uma Chave Pix | Criar um pedido de Portabilidade In de uma Chave Pix do tipo CPF, CNPJ, E-mail, Telefone e Aleatória | [Link Documentação](/documentation/pix/portabilidade#criando-um-pedido-de-portabilidade) |  QIC0002 ou QIC0002  |
| PIX0014* | Reenvio de 2fa de uma Solicitação de Portabilidade In de uma Chave Pix do tipo E-mail ou Telefone | Solicitar o reenvio do SMS (Chave Pix do tipo Telefone) ou E-mail (Chave Pix do tipo E-mail) de uma Solicitação de Portabilidade In de uma Chave Pix pendente (pending_claimer_validation) | [Link Documentação](/documentation/pix/portabilidade#reenviando-a-valida%C3%A7%C3%A3o-de-dois-fatores) | PIX0013 |
| PIX0015* | Exclusão de Solicitação de Portabilidade In de uma Chave Pix | Excluir uma Solicitação de Portabilidade In de uma Chave Pix pendente | [Link Documentação](/documentation/pix/portabilidade#deletando-um-pedido-de-portabilidade) | PIX0013 |
| PIX0016* | Leitura de webhook de conclusão de Solicitação de Portabilidade In de Chave Pix | Ler corretamente o webhook de conclusão de uma Solicitação de Portabilidade In de uma Chave Pix. Testando todos os possíveis status de conclusão (concluded, cancelled e failed) | Webhook: <br/> [Link Documentação](/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade) |PIX0013 |
| PIX0017* | Simulação de Solicitação de Portabilidade Out de uma Chave Pix | Simular a chegada de uma solicitação de Solicitação de Portabilidade Out de uma Chave Pix | Item 5:<br/> [Link Documentação](/documentation/pix/simulacao/index.html) | PIX0013 |
| PIX0018* | Aprovação e Reprovação de Solicitação de Portabilidade Out de uma Chave Pix | Realizar a aprovação de uma Solicitação de Portabilidade Out de uma Chave Pix | [Link Documentação](/documentation/pix/portabilidade#request-4) | PIX0017 |
| PIX0019* | Reenvio de 2fa de uma Solicitação de Portabilidade Out de uma Chave Pix | Solicitar reenvio de 2fa de uma Solicitação de Portabilidade Out de uma Chave Pix | Enum “pending_donator_validation”  <br/> [Link Documentação](/documentation/pix/portabilidade#request-4) | PIX0018 |
| PIX0020* | Leitura de webhook de conclusão de Solicitação de Portabilidade Out de Chave Pix | Ler corretamente o webhook de conclusão de uma Solicitação de Portabilidade Out de uma Chave Pix. Testando todos os possíveis status de conclusão (concluded, cancelled e failed) | [Link Documentação](D/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade-1) | PIX0018 |

## Gestão de QR Code Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0022* | Criação de QR Code Pix Estático | Gerar QR Code Estático | [Link Documentação](/documentation/pix/criar_qr_code_estatico) | PIX0008 |
| PIX0023 | Criação de QR Code Pix Dinâmico | Gerar QR Code Dinâmico com vencimento (dia de vencimento) e gerar QR Code Dinâmico Instantâneo (com segundos de expiração). | [Link Documentação](/documentation/pix/criar_qr_code_dinamico) | PIX0008 |
| PIX0024 | Exclusão de QR Code Pix Dinâmico | Excluir QR Code Pix | [Link Documentação](/documentation/pix/baixar_qr_code_dinamico) | PIX0023 |
| PIX0025 | Listar QR Codes Pix Dinâmicos | Listar QR Codes Pix Dinâmicos | [Link Documentação](/documentation/pix/pesquisar_por_qr_code_dinamico) | PIX0023 |
| PIX0026 | Leitura de webhook de expiração de QR Code Pix Dinâmico Instantâneo | Recepcionar com sucesso um webhook de expiração de QR Code Pix Dinâmico Instantâneo | [Link Documentação](/documentation/pix/webhook_por_qr_code_expirado) | PIX0023 |

## Pagamento de QR Code Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |

| PIX0029* | Pagamento de QR Code Pix Estático | Realizar o pagamento de um QR Code Pix Estático | [Link Documentação](/documentation/baas/pix/realizar_transferencia#transfer%C3%AAncia-por-qr-code-pix) | PIX0022 |
| PIX0030* | Pagamento de QR Code Pix Dinâmico | Realizar o pagamento de um QR Code Pix Dinâmico |  [Link Documentação](/documentation/baas/pix/realizar_transferencia#transfer%C3%AAncia-por-qr-code-pix) | PIX0022 |
| PIX0027* | Decodificação de QR Code Pix | Decodificar um QR Code Pix Estático, Dinâmico com vencimento e Dinâmico Instantâneo | [Link Documentação](/documentation/pix/decodificar_qr_code) | PIX0022 e PIX0023 |

## Gestão de Limite Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0032* | Solicitação de alteração de limite Pix | Realizar solicitação de alteração de limite Pix de uma QI Conte | [Link Documentação](/documentation/pix/solicitar_alteracao_de_limite_pix) |  QIC0002 ou QIC0002  |
| PIX0033 | Listagem de solicitações de alteração de limite Pix | Listar as solicitações de alteração de limite Pix para uma QI Conta | [Link Documentação](/documentation/pix/busca_por_solicitacao_de_limite_pix) | PIX0032 |
| PIX0034* | Consulta de limite Pix consumido | Consultar o limite Pix consumido para uma QI Conta | [Link Documentação](/documentation/pix/busca_por_uso_de_limite_pix) |  QIC0002 ou QIC0002  |

---

# Gestão de Tarifas
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GTF0001* | Solicitação de alteração de tarifas | Realizar a alteração de tarifas de uma conta| [Link Documentação](/documentation/contas/gestao_de_tarifas) |  QIC0002 ou QIC0002  |
| GTF0002* | Consulta de tarifas  | Consultar tarifas cadastradas em uma conta | [Link Documentação](/documentation/contas/consulta_de_tarifas) |  QIC0002 ou QIC0002  |

# Gestão de Cartoẽs

## Criação de Cartão
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GDC0001* | Criação de Cartão virtual  | Realizar a criação de um cartão virtual| [Link Documentação](/documentation/cards/create/gerar_cartao_virtual) |  QIC0002 ou QIC0002  |
| GDC0002* | Criação de Cartão físico  | Realizar a criação de um cartão físico| [Link Documentação](/documentation/cards/create/gerar_cartao_fisico) |  QIC0002 ou QIC0002  |

## Consulta de Cartões
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GDC0003* | Consulta cartão por chave  | Realizar a consulta de um cartão | [Link Documentação](/documentation/cards/search/buscar_cartao_by_key) | GDC0001 ou GDC0002 |
| GDC0004* | Listar cartões  | Realizar a listagem de cartões| [Link Documentação](/documentation/cards/search/listar_cartoes) | GDC0001 ou GDC0002 |
| GDC0005* | Buscar dados de um cartão | Buscar dados de um cartão| [Link Documentação](/documentation/cards/search/buscar_dados_pci) | GDC0001 ou GDC0002 |
| GDC0006* | Buscar Senha PCI | Buscar Senha PCI| [Link Documentação](/documentation/cards/search/buscar_senha) | GDC0001 ou GDC0002 |
| GDC0007* | Consultar dados da entrega | Consultar dados da entrega| [Link Documentação](/documentation/cards/search/buscar_entrega_by_key) | GDC0001 ou GDC0002 |

## Atualizar dados de um cartão
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GDC0008* | Atualizar status de um cartão  | Atualizar status de um cartão| [Link Documentação](/documentation/cards/status/update_status_cartao) | GDC0001 ou GDC0002 |
| GDC0009* | Ativar cartão físico  | Realizar a ativação de um cartão físico| [Link Documentação](/documentation/cards/status/ativar_cartao) | GDC0001 ou GDC0002 |
| GDC0010* | Alterar Senha   | Realizar a alteração de senha de um cartão | [Link Documentação](/documentation/cards/update/password_cartao) | GDC0001 ou GDC0002 |
| GDC0011* | Configurar contactless de um cartão  | Configurar contactless de um cartão  | [Link Documentação](/documentation/cards/update/contactless_cartao) | GDC0002 |

---

# Roteiro de Homologação - BaaS Conta Digital com Dupla Autenticação

URL: /documentation/roteiros_de_homologacao/conta_digital_2fa

O roteiro de homolgoação descreve todos os recursos e funcionalidades que precisam
ser testados pelo parceiro integrador no ambiente de sandbox da QI Tech (ambiente de testes), 
antes da entrada em ambiente de produção do produto.

Este roteiro descreve todos os recursos e funcionalidades envolvidos no produto. 

⚠️ **Todos os testes devem ser obrigatoriamente realizados no ambiente de Sandbox da QI Tech (ambiente de testes).
As movimentações realizadas em ambiente de Sandbox são movimentações financeiras fictícias, servindo apenas para teste de funcionalidade das APIs.**

## Cadastro e Autenticação API BaaS
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| CAB0001* | Cadastro no ambiente de Sandbox | Realizar o cadastro na plataforma da QI Tech no ambiente de Sandbox (sandbox.qitech.app) | cs@qitech.com.br |
| CAB0002* | Validação de token em Sandbox | Realizar a validação do QI Token em Sandbox | [Link Documentação](https://docs.qitech.com.br/assets/pdfs/QI%20Tech%20Manual%20Inclus%C3%A3o%20de%20Token.pdf) | CAB0001 |
| CAB0003* | Troca de chaves públicas | Realizar a troca de chaves públicas dentro da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Link Documentação](/documentation/primeiros_passos/troca_de_chaves) | CAB0001 e CAB0002 |
| CAB0004* | Teste de autenticação de chamadas | Finalizar teste de autenticação de chamadas |[Link Documentação](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2) <br/><br/> [Link Documentação](/documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste) | CAB0003 |
| CAB0005* | Configuração de webhooks | Realizar a configuração da url para envio dos webhooks por parte da QI, através da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Link Documentação](/documentation/primeiros_passos/configurando_webhooks) | CAB0001 e CAB0002 |

## Antifraude

## Cadastro e Autenticação

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| ATF0002* | Obtenção de API-key de onboarding | Obter junto ao time de integração da QI Tech a chave de API para uso da API de /onboarding | suporte.caas@qitech.com.br |  
| ATF0003* | Obtenção de mobile-token de OCR | Obter junto ao time de integração da QI Tech o Mobile Token  para uso do SDK de OCR | suporte.caas@qitech.com.br |  
| ATF0004* | Obtenção de mobile-token de Face Recognition | Obter junto ao time de integração da QI Tech o Mobile Token  para uso do SDK de Face Recognition | suporte.caas@qitech.com.br |  
| ATF0005* | Obtenção de mobile-token de Device scan | Obter junto ao time de integração da QI Tech o Mobile Token  para uso do SDK de Device scan | suporte.caas@qitech.com.br |  

## SDK OCR

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| ATF0007* | Build do SDK | Definir o template e customizações para coleta dos documentos e buildar o SDK com sucesso dentro da sua aplicação (aplicação do cliente QI Tech) | Android: [Link Documentação](/documentation/caas/ocr/android/introduction) <br/> iOS:[ Link Documentação](/documentation/caas/ocr/ios/introduction) |  |
| ATF0008* | Envio de documentos | Realizar a coleta de documentos utilizando o SDK dentro da sua aplicação (aplicação cliente QI Tech) |  | ATF0003 e ATF0007 |
| ATF0009* | Armazenamento de ocr_key | Armazenar as chaves retornadas pelo SDK, identificando a natureza do documento coletado (ex: cnh_front, cnh_back, etc) | Android: [Link Documentação](/documentation/caas/ocr/android/collecting_response) <br/>iOS:[ Link Documentação](/documentation/caas/ocr/ios/collecting_response)| ATF0008 |

## SDK Face Recognition

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| ATF0011* | Build do SDK | Definir customizações e buildar o SDK com sucesso dentro da sua aplicação (aplicação do cliente QI Tech) |Android: [Link Documentação](/documentation/caas/face_recognition/android/introduction) <br/>iOS:[ Link Documentação](/documentation/caas/face_recognition/ios/introduction)  |  |
| ATF0012* | Fluxo de prova de vida | Realizar o fluxo de prova de vida utilizando o SDK dentro da sua aplicação (aplicação cliente QI Tech) | | ATF0004 e ATF0011* |
| ATF0013* | Armazenamento de chave de imagem | Armazenar a image_key retornada pelo SDK após finalização do fluxo de prova de vida | Android: [Link Documentação](/documentation/caas/face_recognition/android/collecting_response) iOS:[ Link Documentação](/documentation/caas/face_recognition/ios/collecting_response) | ATF0012 |

## SDK Device Scan

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| ATF0015* | Build do SDK | Definição das permissões a serem solicitadas ao usuário por sua aplicação (aplicação do cliente QI Tech) e buildar o SDK com sucesso dentro da sua aplicação (aplicação do cliente QI Tech) | Android: [Link Documentação](/documentation/caas/device_scan/android/introduction)<br/>iOS:[ Link Documentação](/documentation/caas/device_scan/ios/introduction)|  
| ATF0016* | Armazenamento da sessão do usuário | Realizar o armazenamento da sessão do usuário (sessionId) que terá o dispositivo escaneado | Android: [Link Documentação](/documentation/caas/device_scan/android/example)<br/>iOS:[ Link Documentação](/documentation/caas/device_scan/ios/example) | ATF0015 e ATF0017 |
| ATF0017* | Coleta de informações | Instanciar o SDK com o sessionId armazenado e chamar o método de coleta de informações dentro de sua aplicação (aplicação do cliente QI Tech) | Android: [Link Documentação](/documentation/caas/face_recognition/android/collecting_response)<br/>iOS:[ Link Documentação](/documentation/caas/face_recognition/ios/collecting_response) | ATF0005 e ATF0015 |

## Antifraude

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| ATF0019* | Antifraude PF | Realizar com sucesso o antifraude de uma cliente pessoa física | [Link Documentação](/documentation/caas/onboarding/natural_person) | ATF0002 |
| ATF0020* | Antifraude PJ | Realizar com sucesso o antifraude de uma cliente pessoa jurídica | [Link Documentação](/documentation/caas/onboarding/legal_person) | ATF0002 |
| ATF0021* | Leitura de webhooks de analises derivadas para fluxo assíncrono | Recepcionar com sucesso o webhook de análise derivada para o fluxo de resposta assíncrona |[Link Documentação](/documentation/caas/onboarding/webhook) | ATF0019 ou ATF0020 |

## Cadastro Plataforma

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| ATF0022* | Cadastro de usuário Master | Realizar o cadastro de um usuário Master na plataforma do CaaS, para resolução de solicitações derivadas para “Análise manual”  | suporte.caas@qitech.com.br | ATF0019 ou ATF0020 |

---

# **QI Conta**

## Abertura de Conta

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| QIC0002* | Reserva de conta PF | Solicitar a reserva de uma conta cujo titular seja uma pessoa física | [Link Documentação](/documentation/baas/account/reservar_conta_pf) | CAB0005 e CAB0006 |
| QIC0003* | Abertura de conta PF | Realizar a abertura de uma conta cujo titular seja uma pessoa física | [Link Documentação](/documentation/baas/account/abrir_conta_pf) | QIC0002 |
| QIC0004* | Reserva de conta PJ | Solicitar a reserva de uma conta cujo titular seja uma pessoa jurídica | [Link Documentação](/documentation/baas/account/reservar_conta_pj) | CAB0005 e CAB0006 |
| QIC0005* | Abertura de conta PJ | Realizar a abertura de uma conta cujo titular seja uma pessoa jurídica | [Link Documentação](/documentation/baas/account/abrir_conta_pj) | QIC0004 |
| QIC0006* | Leitura de webhooks de abertura de conta | Ler corretamente os webhooks de abertura de conta | Item 1.2. ou 1.3:<br/>[Link Documentação](/documentation/baas/account/webhooks) |  QIC0004 ou QIC0005  |
| QIC0007* | Listar contas | Listar contas abertas| [Link Documentação](/documentation/contas/consultar_conta) |  QIC0004 ou QIC0005  |
| QIC0008* | Consulta de dados de uma conta | Consultar dados como saldo, dados do titular, data de abertura, dentre outros | [Link Documentação](/documentation/contas/consultar_conta) |  QIC0004 ou QIC0005  |

## Movimentações

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| QIC0008* | Consulta de Extrato | Realizar a consulta do extrato de uma conta | [Link Documentação](/documentation/movimentacao_de_contas/consulta_de_transacoes) |  QIC0004 ou QIC0005  |
| QIC0009* | Solicitação de comprovante de transferência | Solicitar um comprovante de transferência | [Link Documentação](/documentation/movimentacao_de_contas/comprovante_de_transferencia)|  |
| QIC0010* | Leitura de webhooks de transação | Recepcionar com sucesso todos os webhooks de transação |  [Link Documentação](/documentation/movimentacao_de_contas/webhook_movimentacoes/index.html) |  QIC0004 ou QIC0005  |
| QIC0011* | Consulta de lista de instituições financeiras | Consultar lista de instituições financeiras habiliatadas para recebimento de TED e Pix |  [Link Documentação](/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras) |  QIC0004 ou QIC0005  |

---

# Upload de Documentos

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| UDD0001* | Upload de documento | Realizar o upload de um documento através da nossa API de documentos |  [Link Documentação](/documentation/upload_de_documentos/) |  |

---

# TED

| Código | Etapa | Descrição | Link                                                                                                        | Pré-requisito |
| --- | --- | --- |-------------------------------------------------------------------------------------------------------------| --- |
| TED0001* | Transferência TED Out | Realizar transferência TED  | 1 . Criar a solicitação de transferência: [Link Documentação](/documentation/baas/ted/realizar_transferencia_2fa) <br/>   2 . Aprovar a transferência: [Link Documentação](/documentation/baas/ted/realizar_transferencia_2fa) <br/>           | QIC0004 ou QIC0005 |
| TED0006* | Solicitar reenvio de token| Reenviar token de aprovação da transferência TED | [Link Documentação](/documentation/baas/ted/2fa/solicitacao_de_reenvio_de_token) | TED0001 |
| TED0002* | Simulação de estorno de uma TED Out | Simular o estorno de uma TED Out enviada a partira de uma QI Conta | Item 3: <br/>[Link Documentação](/documentation/movimentacao_de_contas/transacao) |  |
| TED0003* | Simulação de TED In | Simular a entrada de uma TED In em uma QI conta | Item 2: <br/>[Link Documentação](/documentation/movimentacao_de_contas/transacao) | QIC0004 ou QIC0005 |
| TED0004* | Listar transações TED| Listar transações TED de entrada/saída  | [Link Documentação](/documentation/baas/ted/listar_teds)  | QIC0004 ou QIC0005 |
| TED0004* | Consulta de transação  TED| Realizar a consulta de uma transação TED  | [Link Documentação](/documentation/baas/ted/consultar_ted)           | QIC0004 ou QIC0005 |
| TED0006* | Leitura de webhooks de TED| Recepcionar com sucesso um webhook de TED | [Link Documentação](/documentation/baas/ted/webhooks/index.html)| QIC0004 ou QIC0005 |
---

# Transferência Interna

| Nº | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| TFI0001 | Transferência Interna com débito em conta | Comandar uma transferência a partir de uma QI Conta, tendo como destino da transferência, outra QI Conta |  1 . Criar a solicitação de transferência: [Link Documentação](/documentation/baas/ted/realizar_transferencia_2fa) <br/>   2 . Aprovar a transferência: [Link Documentação](/documentation/baas/ted/realizar_transferencia_2fa) <br/> |  QIC0004 ou QIC0005  |
| TFI0002 | Simulação de transferência Interna com crédito em conta | Simular o recebimento de recursos na QI Conta alvo, tendo como origem, outra QI Conta | Item 1: <br/> [Link Documentação](/documentation/movimentacao_de_contas/transacao) |  QIC0004 ou QIC0005  |

---

# Boletos

## Gestão de Boletos

| Nº | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| Nº      | Etapa | Descrição | Link  | Pré-requisito |
|---|---|---|---|---|
| BOL0001 | Registro de boleto de um único boleto cobrança    | Realizar o registro de um boleto de cobrança | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao/index.html) |QIC0004 ou QIC0005   |
| BOL0002 | Registro de boleto de um único boleto de cobrança instantâneo | Realizar o registro de um boleto de cobrança | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) |QIC0004 ou QIC0005   |
| BOL0003 | Registro de boleto de boleto em lote  | Realizar o registro de boleto de cobrança em lote | [Link Documentação](/documentation/boletos/v2/emissao/emissao_em_lote) |QIC0004 ou QIC0005   |
| BOL0004 | Emissão de Boleto Único Padrão        | Emitir um boleto único padrão    | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao)  |QIC0004 ou QIC0005   |
| BOL0005 | Emissão de Boleto Único Instantâneo   | Emitir um boleto único instantân | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) |QIC0004 ou QIC0005   |
| BOL0006 | Emissão em Lote   | Emitir boletos em lote | [Link Documentação](/documentation/boletos/v2/emissao/emissao_em_lote)|QIC0004 ou QIC0005   |
| BOL0007 | Realizar abatimento no valor de um boleto | Realizar abatimento no valor de um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/abatimento/criar_abatimento) | BOL0001, BOL0002 ou BOL0003 |
| BOL0008 | Cancelar Abatimento     | Cancelar abatimento em um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/abatimento/cancelar_abatimento) | BOL0001, BOL0002 ou BOL0003  |
| BOL0009 | Estender vencimento de um boleto               | Enviar extensão de prazo de um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/extensao)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0010 | Incluir desconto em um boleto               | Incluir desconto em um boleto    | [Link Documentação](/documentation/boletos/v2/instrucoes/desconto)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0011 | Incluir juros em um boleto                   | Incluir juros em um boleto       | [Link Documentação](/documentation/boletos/v2/instrucoes/juros)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0012 | Incluir multa em um boleto                   | Incluir multa em um boleto       | [Link Documentação](/documentation/boletos/v2/instrucoes/multa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0013 | Realizar baixa de um boleto                   | Baixar um boleto                 | [Link Documentação](/documentation/boletos/v2/instrucoes/baixa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0014 | Consultar boletos por chave      | Consultar boletos por chave      | [Link Documentação](/documentation/boletos/v2/consulta/consulta_por_chave) | BOL0001, BOL0002 ou BOL0003   |
| BOL0015 | Listar Boletos          | Listar boletos     | [Link Documentação](/documentation/boletos/v2/consulta/listar_boletos) | BOL0001, BOL0002 ou BOL0003   |
| BOL0016 | Consulta de carteira de cobrança      | Consultar uma carteira de cobrança | [Link Documentação](/documentation/boletos/v2/carteira/listar_carteiras/index.html) | BOL0001, BOL0002 ou BOL0003   |
| BOL0017 | Webhooks de Boleto      | Realizar a leitura de webhook para boleto | [Link Documentação](/documentation/boletos/v2/webhooks/boleto) | BOL0001, BOL0002 ou BOL0003   |

## Pagamento de Boletos

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| BOL0009* | Consulta de linha digitável ou Código de Barras | Realizar a consulta de uma linha digitável de um boleto bancário | [Link Documentação](/documentation/baas/cobranca/consultar_boleto_bancario) |  |
| BOL0010* | Solicitar Token para pagamento de um boleto | Solicitar o token o pagamento de um boleto bancário | [Link Documentação](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_boleto_bancario) |  QIC0004 ou QIC0005  |
| BOL0011* | Aprovar o pagamento de um boleto | Solicitar o token o pagamento de um boleto bancário  | [Link Documentação](/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_boleto_bancario) |  QIC0004 ou QIC0005  |
| BOL0012* | Consulta de linha digitável ou Código de Barras de um boleto de convênio | Realizar a consulta de uma linha digitável de um  boleto convênio. | [Link Documentação](/documentation/baas/cobranca/consultar_fatura_de_recolhimento) |  |
| BOL0013* | Solicitar Token para pagamento de um boleto de convênio | Solicitar o token o pagamento de um boleto convênio | [Link Documentação](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_fatura_de_recolhimento) |  QIC0004 ou QIC0005  |
| BOL0014* | Aprovar o pagamento de um boleto de convênio| Solicitar o token o pagamento de um boleto de convênio  | [Link Documentação](/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_fatura_de_recolhimento) |  QIC0004 ou QIC0005  |

---

## Pix

## Transferência Pix 
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
|---------|--|---|---|---|
| PIX0002* | Transferência Pix Out | Realizar uma transferência Pix a partir de uma QI Conta utilizando dados bancários (pix manual) ou chave Pix | [1. Solicitar transferência](/documentation/baas/pix/2fa_v2/solicitacao_de_transacao_pix_2fa) <br></br> [2. Aprovar transferência](/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa) | CAB0001 |
| PIX0035 | Consulta de transferência pix | Recuperar os dados de uma transferência | [Link Documentação](/documentation/baas/pix/consultar_transferencias) | PIX0002 |
| PIX0003* | Simulação de reembolso de Pix Out | Simular o reembolso de um Pix Out. | [Link Documentação - Item 2](/documentation/pix/simulacao)| PIX0002 |
| PIX0004* | Simulação de Pix In | Simular o crédito de um Pix In em uma QI Conta. | [Link Documentação -> Item 1](/documentation/pix/simulacao)||
| PIX0037* | Leitura de webhook de transação pendente | Recepcionar com sucesso um webhook de transação pendente | [Link Documentação][(/documentation/baas/pix/webhooks) | PIX0002 |
| PIX0038* | Leitura de webhook de Pix de In | Recepcionar com sucesso um webhook de transferência Pix de entrada | [Link Documentação](/documentation/baas/pix/webhooks#webhook-para-pix-de-entrada)| PIX0004 |
| PIX0039 | Leitura de webhook de Devolução Pix | Recepcionar com sucesso um webhook de devolução de um Pix | [Link Documentação](/documentation/baas/pix/webhooks#webhook-para-devolu%C3%A7%C3%B5es-de-pix) | PIX0003 |
| PIX0040 | Solicitar a devolução de um Pix recebido | Solicitar a devolução de um Pix recebido | [1. Solicitar devolução](/documentation/baas/pix/2fa_v2/solicitacao_de_devolucao_pix) <br></br> [2. Aprovar devolução](/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa) | PIX0003 |
| PIX0041 | Listar transferências Pix de uma conta | Listar transferências Pix de uma conta | [Link Documentação](/documentation/baas/pix/listar_transferencias) | PIX0003 |

## Gestão de Chave Pix

### Criação e Exclusão de Chave pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0008* | Criação de chave Pix | Realizar a criação de chave Pix do tipo cpf, cnpj, aleatória, e-mail e telefone | [Link Documentação](/documentation/pix/criar_chave) | 
|QIC0004 ou QIC0005  |](/documentation/baas/pix/consultar_chave_pix)
| PIX0009 | Exclusão de chave Pix | Realizar a exclusão de uma chave Pix | [Link Documentação](/documentation/pix/excluir_chave) | PIX0008 |
| PIX0010* | Listagem de chaves Pix de uma QI Conta | Listar chaves Pix vinculadas a uma QI Conta | [Link Documentação](/documentation/pix/listar_chaves_pix) | PIX0008 |

### Portabilidade de Chave Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0013* | Criação de Solicitação de Portabilidade In de uma Chave Pix | Criar um pedido de Portabilidade In de uma Chave Pix do tipo CPF, CNPJ, E-mail, Telefone e Aleatória | [Link Documentação](/documentation/pix/portabilidade#criando-um-pedido-de-portabilidade) |  QIC0004 ou QIC0005  |
| PIX0014* | Reenvio de 2fa de uma Solicitação de Portabilidade In de uma Chave Pix do tipo E-mail ou Telefone | Solicitar o reenvio do SMS (Chave Pix do tipo Telefone) ou E-mail (Chave Pix do tipo E-mail) de uma Solicitação de Portabilidade In de uma Chave Pix pendente (pending_claimer_validation) | [Link Documentação](/documentation/pix/portabilidade#reenviando-a-valida%C3%A7%C3%A3o-de-dois-fatores) | PIX0013 |
| PIX0015* | Exclusão de Solicitação de Portabilidade In de uma Chave Pix | Excluir uma Solicitação de Portabilidade In de uma Chave Pix pendente | [Link Documentação](/documentation/pix/portabilidade#deletando-um-pedido-de-portabilidade) | PIX0013 |
| PIX0016* | Leitura de webhook de conclusão de Solicitação de Portabilidade In de Chave Pix | Ler corretamente o webhook de conclusão de uma Solicitação de Portabilidade In de uma Chave Pix. Testando todos os possíveis status de conclusão (concluded, cancelled e failed) | Webhook: <br/> [Link Documentação](/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade) |PIX0013 |
| PIX0017* | Simulação de Solicitação de Portabilidade Out de uma Chave Pix | Simular a chegada de uma solicitação de Solicitação de Portabilidade Out de uma Chave Pix | Item 5:<br/> [Link Documentação](/documentation/pix/simulacao/index.html) | PIX0013 |
| PIX0018* | Aprovação e Reprovação de Solicitação de Portabilidade Out de uma Chave Pix | Realizar a aprovação de uma Solicitação de Portabilidade Out de uma Chave Pix | [Link Documentação](/documentation/pix/portabilidade#request-4) | PIX0017 |
| PIX0019* | Reenvio de 2fa de uma Solicitação de Portabilidade Out de uma Chave Pix | Solicitar reenvio de 2fa de uma Solicitação de Portabilidade Out de uma Chave Pix | Enum “pending_donator_validation”  <br/> [Link Documentação](/documentation/pix/portabilidade#request-4) | PIX0018 |
| PIX0020* | Leitura de webhook de conclusão de Solicitação de Portabilidade Out de Chave Pix | Ler corretamente o webhook de conclusão de uma Solicitação de Portabilidade Out de uma Chave Pix. Testando todos os possíveis status de conclusão (concluded, cancelled e failed) | [Link Documentação](D/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade-1) | PIX0018 |

## Gestão de QR Code Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0022* | Criação de QR Code Pix Estático | Gerar QR Code Estático | [Link Documentação](/documentation/pix/criar_qr_code_estatico) | PIX0008 |
| PIX0023 | Criação de QR Code Pix Dinâmico | Gerar QR Code Dinâmico com vencimento (dia de vencimento) e gerar QR Code Dinâmico Instantâneo (com segundos de expiração). | [Link Documentação](/documentation/pix/criar_qr_code_dinamico) | PIX0008 |
| PIX0024 | Exclusão de QR Code Pix Dinâmico | Excluir QR Code Pix | [Link Documentação](/documentation/pix/baixar_qr_code_dinamico) | PIX0023 |
| PIX0025 | Listar QR Codes Pix Dinâmicos | Listar QR Codes Pix Dinâmicos | [Link Documentação](/documentation/pix/pesquisar_por_qr_code_dinamico) | PIX0023 |
| PIX0026 | Leitura de webhook de expiração de QR Code Pix Dinâmico Instantâneo | Recepcionar com sucesso um webhook de expiração de QR Code Pix Dinâmico Instantâneo | [Link Documentação](/documentation/pix/webhook_por_qr_code_expirado) | PIX0023 |

## Pagamento de QR Code Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0029* | Pagamento de QR Code Pix Estático | Realizar o pagamento de um QR Code Pix Estático | [1. Solicitar transferência](/documentation/baas/pix/2fa_v2/solicitacao_de_transacao_pix_2fa) <br></br> [2. Aprovar transferência](/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa) | PIX0022 |
| PIX0030* | Pagamento de QR Code Pix Dinâmico | Realizar o pagamento de um QR Code Pix Dinâmico |  [1. Solicitar transferência](/documentation/baas/pix/2fa_v2/solicitacao_de_transacao_pix_2fa) <br></br> [2. Aprovar transferência](/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa) | PIX0022 |
| PIX0027* | Decodificação de QR Code Pix | Decodificar um QR Code Pix Estático, Dinâmico com vencimento e Dinâmico Instantâneo | [Link Documentação](/documentation/pix/decodificar_qr_code) | PIX0022 e PIX0023 |

## Gestão de Limite Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0032* | Solicitação de alteração de limite Pix | Realizar solicitação de alteração de limite Pix de uma QI Conte | [Link Documentação](/documentation/pix/solicitar_alteracao_de_limite_pix) |  QIC0004 ou QIC0005  |
| PIX0033 | Listagem de solicitações de alteração de limite Pix | Listar as solicitações de alteração de limite Pix para uma QI Conta | [Link Documentação](/documentation/pix/busca_por_solicitacao_de_limite_pix) | PIX0032 |
| PIX0034* | Consulta de limite Pix consumido | Consultar o limite Pix consumido para uma QI Conta | [Link Documentação](/documentation/pix/busca_por_uso_de_limite_pix) |  QIC0004 ou QIC0005  |

---

# Gestão de Tarifas
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GTF0001* | Solicitação de alteração de tarifas | Realizar a alteração de tarifas de uma conta| [Link Documentação](/documentation/contas/gestao_de_tarifas) |  QIC0004 ou QIC0005  |
| GTF0002* | Consulta de tarifas  | Consultar tarifas cadastradas em uma conta | [Link Documentação](/documentation/contas/consulta_de_tarifas) |  QIC0004 ou QIC0005  |

## Gestão de Usuários Administradores
| GUA0001* | Inclusão de usuário administrador | Realizar a criação e vinculo de um usuário administrador a uma QI Conta. | Intro: [Documentação](/documentation/gestao_de_usuarios/tfa_introducao)<br/>1. Criação: [Documentação](/documentation/gestao_de_usuarios/criacao_de_pessoa)<br/>2. Inclusão: [Documentação](/documentation/gestao_de_usuarios/inclusao_de_vinculo) |QIC0004 ou QIC0005 |
| GUA0002* | Alteração de dados de contato de um usuário administrador | Relizar a alteração dos dados para contato (E-mail e telefone) de um usuário administrador | [Link Documentação](/documentation/gestao_de_usuarios/alteracao_de_contato_de_vinculo) |  |
| GUA0003* | Exclusão de usuário administrador | Realizar a exclusão de vínculo entre um usuário administrador e uma QI Conta | [Link Documentação](/documentation/gestao_de_usuarios/exclusao_de_vinculo) |  |

# Gestão de Cartoẽs

## Criação de Cartão
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GDC0001* | Criação de Cartão virtual  | Realizar a criação de um cartão virtual| [Link Documentação](/documentation/cards/create/gerar_cartao_virtual) |  QIC0004 ou QIC0005  |
| GDC0002* | Criação de Cartão físico  | Realizar a criação de um cartão físico| [Link Documentação](/documentation/cards/create/gerar_cartao_fisico) |  QIC0004 ou QIC0005  |

## Consulta de Cartões
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GDC0003* | Consulta cartão por chave  | Realizar a consulta de um cartão | [Link Documentação](/documentation/cards/search/buscar_cartao_by_key) | GDC0001 ou GDC0002 |
| GDC0004* | Listar cartões  | Realizar a listagem de cartões| [Link Documentação](/documentation/cards/search/listar_cartoes) | GDC0001 ou GDC0002 |
| GDC0005* | Buscar dados de um cartão | Buscar dados de um cartão| [Link Documentação](/documentation/cards/search/buscar_dados_pci) | GDC0001 ou GDC0002 |
| GDC0006* | Buscar Senha PCI | Buscar Senha PCI| [Link Documentação](/documentation/cards/search/buscar_senha) | GDC0001 ou GDC0002 |
| GDC0007* | Consultar dados da entrega | Consultar dados da entrega| [Link Documentação](/documentation/cards/search/buscar_entrega_by_key) | GDC0001 ou GDC0002 |

## Atualizar dados de um cartão
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GDC0008* | Atualizar status de um cartão  | Atualizar status de um cartão| [Link Documentação](/documentation/cards/status/update_status_cartao) | GDC0001 ou GDC0002 |
| GDC0009* | Ativar cartão físico  | Realizar a ativação de um cartão físico| [Link Documentação](/documentation/cards/status/ativar_cartao) | GDC0001 ou GDC0002 |
| GDC0010* | Alterar Senha   | Realizar a alteração de senha de um cartão | [Link Documentação](/documentation/cards/update/password_cartao) | GDC0001 ou GDC0002 |
| GDC0011* | Configurar contactless de um cartão  | Configurar contactless de um cartão  | [Link Documentação](/documentation/cards/update/contactless_cartao) | GDC0002 |

---

# Roteiro de Homologação - BaaS Conta Digital com Dupla Autenticação

URL: /documentation/roteiros_de_homologacao/conta_digital_2fa_baas

O roteiro de homolgoação descreve todos os recursos e funcionalidades que precisam
ser testados pelo parceiro integrador no ambiente de sandbox da QI Tech (ambiente de testes), 
antes da entrada em ambiente de produção do produto.

Este roteiro descreve todos os recursos e funcionalidades envolvidos no produto. 

⚠️ **Todos os testes devem ser obrigatoriamente realizados no ambiente de Sandbox da QI Tech (ambiente de testes).
As movimentações realizadas em ambiente de Sandbox são movimentações financeiras fictícias, servindo apenas para teste de funcionalidade das APIs.**

## Cadastro e Autenticação API BaaS
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| CAB0001* | Cadastro no ambiente de Sandbox | Realizar o cadastro na plataforma da QI Tech no ambiente de Sandbox (sandbox.qitech.app) | cs@qitech.com.br |
| CAB0002* | Validação de token em Sandbox | Realizar a validação do QI Token em Sandbox | [Link Documentação](https://docs.qitech.com.br/assets/pdfs/QI%20Tech%20Manual%20Inclus%C3%A3o%20de%20Token.pdf) | CAB0001 |
| CAB0003* | Troca de chaves públicas | Realizar a troca de chaves públicas dentro da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Link Documentação](/documentation/primeiros_passos/troca_de_chaves) | CAB0001 e CAB0002 |
| CAB0004* | Teste de autenticação de chamadas | Finalizar teste de autenticação de chamadas |[Link Documentação](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2) <br/><br/> [Link Documentação](/documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste) | CAB0003 |
| CAB0005* | Configuração de webhooks | Realizar a configuração da url para envio dos webhooks por parte da QI, através da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Link Documentação](/documentation/primeiros_passos/configurando_webhooks) | CAB0001 e CAB0002 |

# **QI Conta**

## Abertura de Conta

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| QIC0002* | Reserva de conta PF | Solicitar a reserva de uma conta cujo titular seja uma pessoa física | [Link Documentação](/documentation/baas/account/reservar_conta_pf) | CAB0005 e CAB0006 |
| QIC0003* | Abertura de conta PF | Realizar a abertura de uma conta cujo titular seja uma pessoa física | [Link Documentação](/documentation/baas/account/abrir_conta_pf) | QIC0002 |
| QIC0004* | Reserva de conta PJ | Solicitar a reserva de uma conta cujo titular seja uma pessoa jurídica | [Link Documentação](/documentation/baas/account/reservar_conta_pj) | CAB0005 e CAB0006 |
| QIC0005* | Abertura de conta PJ | Realizar a abertura de uma conta cujo titular seja uma pessoa jurídica | [Link Documentação](/documentation/baas/account/abrir_conta_pj) | QIC0004 |
| QIC0006* | Leitura de webhooks de abertura de conta | Ler corretamente os webhooks de abertura de conta | Item 1.2. ou 1.3:<br/>[Link Documentação](/documentation/baas/account/webhooks) |  QIC0004 ou QIC0005  |
| QIC0007* | Listar contas | Listar contas abertas| [Link Documentação](/documentation/contas/consultar_conta) |  QIC0004 ou QIC0005  |
| QIC0008* | Consulta de dados de uma conta | Consultar dados como saldo, dados do titular, data de abertura, dentre outros | [Link Documentação](/documentation/contas/consultar_conta) |  QIC0004 ou QIC0005  |

## Movimentações

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| QIC0008* | Consulta de Extrato | Realizar a consulta do extrato de uma conta | [Link Documentação](/documentation/movimentacao_de_contas/consulta_de_transacoes) |  QIC0004 ou QIC0005  |
| QIC0009* | Solicitação de comprovante de transferência | Solicitar um comprovante de transferência | [Link Documentação](/documentation/movimentacao_de_contas/comprovante_de_transferencia)|  |
| QIC0010* | Leitura de webhooks de transação | Recepcionar com sucesso todos os webhooks de transação |  [Link Documentação](/documentation/movimentacao_de_contas/webhook_movimentacoes/index.html) |  QIC0004 ou QIC0005  |
| QIC0011* | Consulta de lista de instituições financeiras | Consultar lista de instituições financeiras habiliatadas para recebimento de TED e Pix |  [Link Documentação](/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras) |  QIC0004 ou QIC0005  |

---

# Upload de Documentos

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| UDD0001* | Upload de documento | Realizar o upload de um documento através da nossa API de documentos |  [Link Documentação](/documentation/upload_de_documentos/) |  |

---

# TED

| Código | Etapa | Descrição | Link                                                                                                        | Pré-requisito |
| --- | --- | --- |-------------------------------------------------------------------------------------------------------------| --- |
| TED0001* | Transferência TED Out | Realizar transferência TED  | 1 . Criar a solicitação de transferência: [Link Documentação](/documentation/baas/ted/realizar_transferencia_2fa) <br/>   2 . Aprovar a transferência: [Link Documentação](/documentation/baas/ted/realizar_transferencia_2fa) <br/>           | QIC0004 ou QIC0005 |
| TED0006* | Solicitar reenvio de token| Reenviar token de aprovação da transferência TED | [Link Documentação](/documentation/baas/ted/2fa/solicitacao_de_reenvio_de_token) | TED0001 |
| TED0002* | Simulação de estorno de uma TED Out | Simular o estorno de uma TED Out enviada a partira de uma QI Conta | Item 3: <br/>[Link Documentação](/documentation/movimentacao_de_contas/transacao) |  |
| TED0003* | Simulação de TED In | Simular a entrada de uma TED In em uma QI conta | Item 2: <br/>[Link Documentação](/documentation/movimentacao_de_contas/transacao) | QIC0004 ou QIC0005 |
| TED0004* | Listar transações TED| Listar transações TED de entrada/saída  | [Link Documentação](/documentation/baas/ted/listar_teds)  | QIC0004 ou QIC0005 |
| TED0004* | Consulta de transação  TED| Realizar a consulta de uma transação TED  | [Link Documentação](/documentation/baas/ted/consultar_ted)           | QIC0004 ou QIC0005 |
| TED0006* | Leitura de webhooks de TED| Recepcionar com sucesso um webhook de TED | [Link Documentação](/documentation/baas/ted/webhooks/index.html)| QIC0004 ou QIC0005 |
---

# Transferência Interna

| Nº | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| TFI0001 | Transferência Interna com débito em conta | Comandar uma transferência a partir de uma QI Conta, tendo como destino da transferência, outra QI Conta |  1 . Criar a solicitação de transferência: [Link Documentação](/documentation/baas/ted/realizar_transferencia_2fa) <br/>   2 . Aprovar a transferência: [Link Documentação](/documentation/baas/ted/realizar_transferencia_2fa) <br/> |  QIC0004 ou QIC0005  |
| TFI0002 | Simulação de transferência Interna com crédito em conta | Simular o recebimento de recursos na QI Conta alvo, tendo como origem, outra QI Conta | Item 1: <br/> [Link Documentação](/documentation/movimentacao_de_contas/transacao) |  QIC0004 ou QIC0005  |

---

# Boletos

## Gestão de Boletos

| Nº | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| Nº      | Etapa | Descrição | Link  | Pré-requisito |
|---|---|---|---|---|
| BOL0001 | Registro de boleto de um único boleto cobrança    | Realizar o registro de um boleto de cobrança | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao/index.html) |QIC0004 ou QIC0005   |
| BOL0002 | Registro de boleto de um único boleto de cobrança instantâneo | Realizar o registro de um boleto de cobrança | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) |QIC0004 ou QIC0005   |
| BOL0003 | Registro de boleto de boleto em lote  | Realizar o registro de boleto de cobrança em lote | [Link Documentação](/documentation/boletos/v2/emissao/emissao_em_lote) |QIC0004 ou QIC0005   |
| BOL0004 | Emissão de Boleto Único Padrão        | Emitir um boleto único padrão    | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao)  |QIC0004 ou QIC0005   |
| BOL0005 | Emissão de Boleto Único Instantâneo   | Emitir um boleto único instantân | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) |QIC0004 ou QIC0005   |
| BOL0006 | Emissão em Lote   | Emitir boletos em lote | [Link Documentação](/documentation/boletos/v2/emissao/emissao_em_lote)|QIC0004 ou QIC0005   |
| BOL0007 | Realizar abatimento no valor de um boleto | Realizar abatimento no valor de um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/abatimento/criar_abatimento) | BOL0001, BOL0002 ou BOL0003 |
| BOL0008 | Cancelar Abatimento     | Cancelar abatimento em um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/abatimento/cancelar_abatimento) | BOL0001, BOL0002 ou BOL0003  |
| BOL0009 | Estender vencimento de um boleto               | Enviar extensão de prazo de um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/extensao)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0010 | Incluir desconto em um boleto               | Incluir desconto em um boleto    | [Link Documentação](/documentation/boletos/v2/instrucoes/desconto)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0011 | Incluir juros em um boleto                   | Incluir juros em um boleto       | [Link Documentação](/documentation/boletos/v2/instrucoes/juros)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0012 | Incluir multa em um boleto                   | Incluir multa em um boleto       | [Link Documentação](/documentation/boletos/v2/instrucoes/multa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0013 | Realizar baixa de um boleto                   | Baixar um boleto                 | [Link Documentação](/documentation/boletos/v2/instrucoes/baixa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0014 | Consultar boletos por chave      | Consultar boletos por chave      | [Link Documentação](/documentation/boletos/v2/consulta/consulta_por_chave) | BOL0001, BOL0002 ou BOL0003   |
| BOL0015 | Listar Boletos          | Listar boletos     | [Link Documentação](/documentation/boletos/v2/consulta/listar_boletos) | BOL0001, BOL0002 ou BOL0003   |
| BOL0016 | Consulta de carteira de cobrança      | Consultar uma carteira de cobrança | [Link Documentação](/documentation/boletos/v2/carteira/listar_carteiras/index.html) | BOL0001, BOL0002 ou BOL0003   |
| BOL0017 | Webhooks de Boleto      | Realizar a leitura de webhook para boleto | [Link Documentação](/documentation/boletos/v2/webhooks/boleto) | BOL0001, BOL0002 ou BOL0003   |

## Pagamento de Boletos

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| BOL0009* | Consulta de linha digitável ou Código de Barras | Realizar a consulta de uma linha digitável de um boleto bancário | [Link Documentação](/documentation/baas/cobranca/consultar_boleto_bancario) |  |
| BOL0010* | Solicitar Token para pagamento de um boleto | Solicitar o token o pagamento de um boleto bancário | [Link Documentação](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_boleto_bancario) |  QIC0004 ou QIC0005  |
| BOL0011* | Aprovar o pagamento de um boleto | Solicitar o token o pagamento de um boleto bancário  | [Link Documentação](/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_boleto_bancario) |  QIC0004 ou QIC0005  |
| BOL0012* | Consulta de linha digitável ou Código de Barras de um boleto de convênio | Realizar a consulta de uma linha digitável de um  boleto convênio. | [Link Documentação](/documentation/baas/cobranca/consultar_fatura_de_recolhimento) |  |
| BOL0013* | Solicitar Token para pagamento de um boleto de convênio | Solicitar o token o pagamento de um boleto convênio | [Link Documentação](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_fatura_de_recolhimento) |  QIC0004 ou QIC0005  |
| BOL0014* | Aprovar o pagamento de um boleto de convênio| Solicitar o token o pagamento de um boleto de convênio  | [Link Documentação](/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_fatura_de_recolhimento) |  QIC0004 ou QIC0005  |

---

## Pix

## Transferência Pix 
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
|---------|--|---|---|---|
| PIX0002* | Transferência Pix Out | Realizar uma transferência Pix a partir de uma QI Conta utilizando dados bancários (pix manual) ou chave Pix | [1. Solicitar transferência](/documentation/baas/pix/2fa_v2/solicitacao_de_transacao_pix_2fa) <br></br> [2. Aprovar transferência](/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa) | CAB0001 |
| PIX0035 | Consulta de transferência pix | Recuperar os dados de uma transferência | [Link Documentação](/documentation/baas/pix/consultar_transferencias) | PIX0002 |
| PIX0003* | Simulação de reembolso de Pix Out | Simular o reembolso de um Pix Out. | [Link Documentação - Item 2](/documentation/pix/simulacao)| PIX0002 |
| PIX0004* | Simulação de Pix In | Simular o crédito de um Pix In em uma QI Conta. | [Link Documentação -> Item 1](/documentation/pix/simulacao)||
| PIX0037* | Leitura de webhook de transação pendente | Recepcionar com sucesso um webhook de transação pendente | [Link Documentação][(/documentation/baas/pix/webhooks) | PIX0002 |
| PIX0038* | Leitura de webhook de Pix de In | Recepcionar com sucesso um webhook de transferência Pix de entrada | [Link Documentação](/documentation/baas/pix/webhooks#webhook-para-pix-de-entrada)| PIX0004 |
| PIX0039 | Leitura de webhook de Devolução Pix | Recepcionar com sucesso um webhook de devolução de um Pix | [Link Documentação](/documentation/baas/pix/webhooks#webhook-para-devolu%C3%A7%C3%B5es-de-pix) | PIX0003 |
| PIX0040 | Solicitar a devolução de um Pix recebido | Solicitar a devolução de um Pix recebido | [1. Solicitar devolução](/documentation/baas/pix/2fa_v2/solicitacao_de_devolucao_pix) <br></br> [2. Aprovar devolução](/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa) | PIX0003 |
| PIX0041 | Listar transferências Pix de uma conta | Listar transferências Pix de uma conta | [Link Documentação](/documentation/baas/pix/listar_transferencias) | PIX0003 |

## Gestão de Chave Pix

### Criação e Exclusão de Chave pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0008* | Criação de chave Pix | Realizar a criação de chave Pix do tipo cpf, cnpj, aleatória, e-mail e telefone | [Link Documentação](/documentation/pix/criar_chave) | 
|QIC0004 ou QIC0005  |](/documentation/baas/pix/consultar_chave_pix)
| PIX0009 | Exclusão de chave Pix | Realizar a exclusão de uma chave Pix | [Link Documentação](/documentation/pix/excluir_chave) | PIX0008 |
| PIX0010* | Listagem de chaves Pix de uma QI Conta | Listar chaves Pix vinculadas a uma QI Conta | [Link Documentação](/documentation/pix/listar_chaves_pix) | PIX0008 |

### Portabilidade de Chave Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0013* | Criação de Solicitação de Portabilidade In de uma Chave Pix | Criar um pedido de Portabilidade In de uma Chave Pix do tipo CPF, CNPJ, E-mail, Telefone e Aleatória | [Link Documentação](/documentation/pix/portabilidade#criando-um-pedido-de-portabilidade) |  QIC0004 ou QIC0005  |
| PIX0014* | Reenvio de 2fa de uma Solicitação de Portabilidade In de uma Chave Pix do tipo E-mail ou Telefone | Solicitar o reenvio do SMS (Chave Pix do tipo Telefone) ou E-mail (Chave Pix do tipo E-mail) de uma Solicitação de Portabilidade In de uma Chave Pix pendente (pending_claimer_validation) | [Link Documentação](/documentation/pix/portabilidade#reenviando-a-valida%C3%A7%C3%A3o-de-dois-fatores) | PIX0013 |
| PIX0015* | Exclusão de Solicitação de Portabilidade In de uma Chave Pix | Excluir uma Solicitação de Portabilidade In de uma Chave Pix pendente | [Link Documentação](/documentation/pix/portabilidade#deletando-um-pedido-de-portabilidade) | PIX0013 |
| PIX0016* | Leitura de webhook de conclusão de Solicitação de Portabilidade In de Chave Pix | Ler corretamente o webhook de conclusão de uma Solicitação de Portabilidade In de uma Chave Pix. Testando todos os possíveis status de conclusão (concluded, cancelled e failed) | Webhook: <br/> [Link Documentação](/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade) |PIX0013 |
| PIX0017* | Simulação de Solicitação de Portabilidade Out de uma Chave Pix | Simular a chegada de uma solicitação de Solicitação de Portabilidade Out de uma Chave Pix | Item 5:<br/> [Link Documentação](/documentation/pix/simulacao/index.html) | PIX0013 |
| PIX0018* | Aprovação e Reprovação de Solicitação de Portabilidade Out de uma Chave Pix | Realizar a aprovação de uma Solicitação de Portabilidade Out de uma Chave Pix | [Link Documentação](/documentation/pix/portabilidade#request-4) | PIX0017 |
| PIX0019* | Reenvio de 2fa de uma Solicitação de Portabilidade Out de uma Chave Pix | Solicitar reenvio de 2fa de uma Solicitação de Portabilidade Out de uma Chave Pix | Enum “pending_donator_validation”  <br/> [Link Documentação](/documentation/pix/portabilidade#request-4) | PIX0018 |
| PIX0020* | Leitura de webhook de conclusão de Solicitação de Portabilidade Out de Chave Pix | Ler corretamente o webhook de conclusão de uma Solicitação de Portabilidade Out de uma Chave Pix. Testando todos os possíveis status de conclusão (concluded, cancelled e failed) | [Link Documentação](D/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade-1) | PIX0018 |

## Gestão de QR Code Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0022* | Criação de QR Code Pix Estático | Gerar QR Code Estático | [Link Documentação](/documentation/pix/criar_qr_code_estatico) | PIX0008 |
| PIX0023 | Criação de QR Code Pix Dinâmico | Gerar QR Code Dinâmico com vencimento (dia de vencimento) e gerar QR Code Dinâmico Instantâneo (com segundos de expiração). | [Link Documentação](/documentation/pix/criar_qr_code_dinamico) | PIX0008 |
| PIX0024 | Exclusão de QR Code Pix Dinâmico | Excluir QR Code Pix | [Link Documentação](/documentation/pix/baixar_qr_code_dinamico) | PIX0023 |
| PIX0025 | Listar QR Codes Pix Dinâmicos | Listar QR Codes Pix Dinâmicos | [Link Documentação](/documentation/pix/pesquisar_por_qr_code_dinamico) | PIX0023 |
| PIX0026 | Leitura de webhook de expiração de QR Code Pix Dinâmico Instantâneo | Recepcionar com sucesso um webhook de expiração de QR Code Pix Dinâmico Instantâneo | [Link Documentação](/documentation/pix/webhook_por_qr_code_expirado) | PIX0023 |

## Pagamento de QR Code Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0029* | Pagamento de QR Code Pix Estático | Realizar o pagamento de um QR Code Pix Estático | [1. Solicitar transferência](/documentation/baas/pix/2fa_v2/solicitacao_de_transacao_pix_2fa) <br></br> [2. Aprovar transferência](/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa) | PIX0022 |
| PIX0030* | Pagamento de QR Code Pix Dinâmico | Realizar o pagamento de um QR Code Pix Dinâmico |  [1. Solicitar transferência](/documentation/baas/pix/2fa_v2/solicitacao_de_transacao_pix_2fa) <br></br> [2. Aprovar transferência](/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa) | PIX0022 |
| PIX0027* | Decodificação de QR Code Pix | Decodificar um QR Code Pix Estático, Dinâmico com vencimento e Dinâmico Instantâneo | [Link Documentação](/documentation/pix/decodificar_qr_code) | PIX0022 e PIX0023 |

## Gestão de Limite Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0032* | Solicitação de alteração de limite Pix | Realizar solicitação de alteração de limite Pix de uma QI Conte | [Link Documentação](/documentation/pix/solicitar_alteracao_de_limite_pix) |  QIC0004 ou QIC0005  |
| PIX0033 | Listagem de solicitações de alteração de limite Pix | Listar as solicitações de alteração de limite Pix para uma QI Conta | [Link Documentação](/documentation/pix/busca_por_solicitacao_de_limite_pix) | PIX0032 |
| PIX0034* | Consulta de limite Pix consumido | Consultar o limite Pix consumido para uma QI Conta | [Link Documentação](/documentation/pix/busca_por_uso_de_limite_pix) |  QIC0004 ou QIC0005  |

---

# Gestão de Tarifas
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GTF0001* | Solicitação de alteração de tarifas | Realizar a alteração de tarifas de uma conta| [Link Documentação](/documentation/contas/gestao_de_tarifas) |  QIC0004 ou QIC0005  |
| GTF0002* | Consulta de tarifas  | Consultar tarifas cadastradas em uma conta | [Link Documentação](/documentation/contas/consulta_de_tarifas) |  QIC0004 ou QIC0005  |

## Gestão de Usuários Administradores
| GUA0001* | Inclusão de usuário administrador | Realizar a criação e vinculo de um usuário administrador a uma QI Conta. | Intro: [Documentação](/documentation/gestao_de_usuarios/tfa_introducao)<br/>1. Criação: [Documentação](/documentation/gestao_de_usuarios/criacao_de_pessoa)<br/>2. Inclusão: [Documentação](/documentation/gestao_de_usuarios/inclusao_de_vinculo) |QIC0004 ou QIC0005 |
| GUA0002* | Alteração de dados de contato de um usuário administrador | Relizar a alteração dos dados para contato (E-mail e telefone) de um usuário administrador | [Link Documentação](/documentation/gestao_de_usuarios/alteracao_de_contato_de_vinculo) |  |
| GUA0003* | Exclusão de usuário administrador | Realizar a exclusão de vínculo entre um usuário administrador e uma QI Conta | [Link Documentação](/documentation/gestao_de_usuarios/exclusao_de_vinculo) |  |

# Gestão de Cartoẽs

## Criação de Cartão
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GDC0001* | Criação de Cartão virtual  | Realizar a criação de um cartão virtual| [Link Documentação](/documentation/cards/create/gerar_cartao_virtual) |  QIC0004 ou QIC0005  |
| GDC0002* | Criação de Cartão físico  | Realizar a criação de um cartão físico| [Link Documentação](/documentation/cards/create/gerar_cartao_fisico) |  QIC0004 ou QIC0005  |

## Consulta de Cartões
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GDC0003* | Consulta cartão por chave  | Realizar a consulta de um cartão | [Link Documentação](/documentation/cards/search/buscar_cartao_by_key) | GDC0001 ou GDC0002 |
| GDC0004* | Listar cartões  | Realizar a listagem de cartões| [Link Documentação](/documentation/cards/search/listar_cartoes) | GDC0001 ou GDC0002 |
| GDC0005* | Buscar dados de um cartão | Buscar dados de um cartão| [Link Documentação](/documentation/cards/search/buscar_dados_pci) | GDC0001 ou GDC0002 |
| GDC0006* | Buscar Senha PCI | Buscar Senha PCI| [Link Documentação](/documentation/cards/search/buscar_senha) | GDC0001 ou GDC0002 |
| GDC0007* | Consultar dados da entrega | Consultar dados da entrega| [Link Documentação](/documentation/cards/search/buscar_entrega_by_key) | GDC0001 ou GDC0002 |

## Atualizar dados de um cartão
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GDC0008* | Atualizar status de um cartão  | Atualizar status de um cartão| [Link Documentação](/documentation/cards/status/update_status_cartao) | GDC0001 ou GDC0002 |
| GDC0009* | Ativar cartão físico  | Realizar a ativação de um cartão físico| [Link Documentação](/documentation/cards/status/ativar_cartao) | GDC0001 ou GDC0002 |
| GDC0010* | Alterar Senha   | Realizar a alteração de senha de um cartão | [Link Documentação](/documentation/cards/update/password_cartao) | GDC0001 ou GDC0002 |
| GDC0011* | Configurar contactless de um cartão  | Configurar contactless de um cartão  | [Link Documentação](/documentation/cards/update/contactless_cartao) | GDC0002 |

---

# Roteiro de Homologação - BaaS Conta Digital

URL: /documentation/roteiros_de_homologacao/conta_digital_baas

O roteiro de homolgoação descreve todos os recursos e funcionalidades que precisam
ser testados pelo parceiro integrador no ambiente de sandbox da QI Tech (ambiente de testes), 
antes da entrada em ambiente de produção do produto.

Este roteiro descreve todos os recursos e funcionalidades envolvidos no produto. 

⚠️ **Todos os testes devem ser obrigatoriamente realizados no ambiente de Sandbox da QI Tech (ambiente de testes).
As movimentações realizadas em ambiente de Sandbox são movimentações financeiras fictícias, servindo apenas para teste de funcionalidade das APIs.**

## Cadastro e Autenticação API BaaS
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| CAB0001* | Cadastro no ambiente de Sandbox | Realizar o cadastro na plataforma da QI Tech no ambiente de Sandbox (sandbox.qitech.app) | cs@qitech.com.br |
| CAB0002* | Validação de token em Sandbox | Realizar a validação do QI Token em Sandbox | [Link Documentação](https://docs.qitech.com.br/assets/pdfs/QI%20Tech%20Manual%20Inclus%C3%A3o%20de%20Token.pdf) | CAB0001 |
| CAB0003* | Troca de chaves públicas | Realizar a troca de chaves públicas dentro da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Link Documentação](/documentation/primeiros_passos/troca_de_chaves) | CAB0001 e CAB0002 |
| CAB0004* | Teste de autenticação de chamadas | Finalizar teste de autenticação de chamadas |[Link Documentação](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2) <br/><br/> [Link Documentação](/documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste) | CAB0003 |
| CAB0005* | Configuração de webhooks | Realizar a configuração da url para envio dos webhooks por parte da QI, através da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Link Documentação](/documentation/primeiros_passos/configurando_webhooks) | CAB0001 e CAB0002 |

# **QI Conta**

## Abertura de Conta

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| QIC0002* | Reserva de conta PF | Solicitar a reserva de uma conta cujo titular seja uma pessoa física | [Link Documentação](/documentation/baas/account/reservar_conta_pf) | CAB0005 e CAB0006 |
| QIC0003* | Abertura de conta PF | Realizar a abertura de uma conta cujo titular seja uma pessoa física | [Link Documentação](/documentation/baas/account/abrir_conta_pf) | CAB0005 e CAB0006 |
| QIC0004* | Reserva de conta PJ | Solicitar a reserva de uma conta cujo titular seja uma pessoa jurídica | [Link Documentação](/documentation/baas/account/reservar_conta_pj) | CAB0005 e CAB0006 |
| QIC0005* | Abertura de conta PJ | Realizar a abertura de uma conta cujo titular seja uma pessoa jurídica | [Link Documentação](/documentation/baas/account/abrir_conta_pj) | CAB0005 e CAB0006 |
| QIC0006* | Leitura de webhooks de abertura de conta | Ler corretamente os webhooks de abertura de conta | Item 1.2. ou 1.3:<br/>[Link Documentação](/documentation/baas/account/webhooks) |  QIC0003 ou QIC0005  |
| QIC0007* | Listar contas | Listar contas abertas| [Link Documentação](/documentation/contas/consultar_conta) |  QIC0003 ou QIC0005  |
| QIC0008* | Consulta de dados de uma conta | Consultar dados como saldo, dados do titular, data de abertura, dentre outros | [Link Documentação](/documentation/contas/consultar_conta) |  QIC0003 ou QIC0005  |

## Movimentações

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| QIC0008* | Consulta de Extrato | Realizar a consulta do extrato de uma conta | [Link Documentação](/documentation/movimentacao_de_contas/consulta_de_transacoes) |  QIC0003 ou QIC0005  |
| QIC0009* | Solicitação de comprovante de transferência | Solicitar um comprovante de transferência | [Link Documentação](/documentation/movimentacao_de_contas/comprovante_de_transferencia)|  |
| QIC0010* | Leitura de webhooks de transação | Recepcionar com sucesso todos os webhooks de transação |  [Link Documentação](/documentation/movimentacao_de_contas/webhook_movimentacoes/index.html) |  QIC0003 ou QIC0005  |
| QIC0011* | Consulta de lista de instituições financeiras | Consultar lista de instituições financeiras habiliatadas para recebimento de TED e Pix |  [Link Documentação](/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras) |  QIC0003 ou QIC0005  |

---

# Upload de Documentos

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| UDD0001* | Upload de documento | Realizar o upload de um documento através da nossa API de documentos |  [Link Documentação](/documentation/upload_de_documentos/) |  |

---

# TED

| Código | Etapa | Descrição | Link                                                                                                        | Pré-requisito |
| --- | --- | --- |-------------------------------------------------------------------------------------------------------------| --- |
| TED0001* | Transferência TED Out | Realizar transferência TED  | [Link Documentação](/documentation/baas/ted/realizar_transferencia) | QIC0003 ou QIC0005 |
| TED0002* | Simulação de estorno de uma TED Out | Simular o estorno de uma TED Out enviada a partira de uma QI Conta | Item 3: <br/>[Link Documentação](/documentation/movimentacao_de_contas/transacao) | TED0003 |
| TED0003* | Simulação de TED In | Simular a entrada de uma TED In em uma QI conta | Item 2: <br/>[Link Documentação](/documentation/movimentacao_de_contas/transacao) | QIC0003 ou QIC0005 |
| TED0004* | Listar transações TED| Listar transações TED de entrada/saída  | [Link Documentação](/documentation/baas/ted/listar_teds)  | QIC0003 ou QIC0005 |
| TED0004* | Consulta de transação  TED| Realizar a consulta de uma transação TED  | [Link Documentação](/documentation/baas/ted/consultar_ted)           | QIC0003 ou QIC0005 |
| TED0006* | Leitura de webhooks de TED| Recepcionar com sucesso um webhook de TED | [Link Documentação](/documentation/baas/ted/webhooks/index.html)| QIC0003 ou QIC0005 |
---

# Transferência Interna

| Nº | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| TFI0001 | Transferência Interna com débito em conta | Comandar uma transferência a partir de uma QI Conta, tendo como destino da transferência, outra QI Conta | [Link Documentação](/documentation/baas/ted/realizar_transferencia) |  QIC0003 ou QIC0005  |
| TFI0002 | Simulação de transferência Interna com crédito em conta | Simular o recebimento de recursos na QI Conta alvo, tendo como origem, outra QI Conta | Item 1: <br/> [Link Documentação](/documentation/movimentacao_de_contas/transacao) |  QIC0003 ou QIC0005  |

---

# Boletos

## Gestão de Boletos

| Nº | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| Nº      | Etapa | Descrição | Link  | Pré-requisito |
|---|---|---|---|---|
| BOL0001 | Registro de boleto de um único boleto cobrança    | Realizar o registro de um boleto de cobrança | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao/index.html) | CAB0002 ou CAB0003   |
| BOL0002 | Registro de boleto de um único boleto de cobrança instantâneo | Realizar o registro de um boleto de cobrança | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) | CAB0002 ou CAB0003   |
| BOL0003 | Registro de boleto de boleto em lote  | Realizar o registro de boleto de cobrança em lote | [Link Documentação](/documentation/boletos/v2/emissao/emissao_em_lote) | CAB0002 ou CAB0003   |
| BOL0004 | Emissão de Boleto Único Padrão        | Emitir um boleto único padrão    | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao)  | CAB0002 ou CAB0003   |
| BOL0005 | Emissão de Boleto Único Instantâneo   | Emitir um boleto único instantân | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) | CAB0002 ou CAB0003   |
| BOL0006 | Emissão em Lote   | Emitir boletos em lote | [Link Documentação](/documentation/boletos/v2/emissao/emissao_em_lote)| CAB0002 ou CAB0003   |
| BOL0007 | Realizar abatimento no valor de um boleto | Realizar abatimento no valor de um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/abatimento/criar_abatimento) | BOL0001, BOL0002 ou BOL0003 |
| BOL0008 | Cancelar Abatimento     | Cancelar abatimento em um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/abatimento/cancelar_abatimento) | BOL0001, BOL0002 ou BOL0003  |
| BOL0009 | Estender vencimento de um boleto               | Enviar extensão de prazo de um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/extensao)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0010 | Incluir desconto em um boleto               | Incluir desconto em um boleto    | [Link Documentação](/documentation/boletos/v2/instrucoes/desconto)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0011 | Incluir juros em um boleto                   | Incluir juros em um boleto       | [Link Documentação](/documentation/boletos/v2/instrucoes/juros)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0012 | Incluir multa em um boleto                   | Incluir multa em um boleto       | [Link Documentação](/documentation/boletos/v2/instrucoes/multa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0013 | Realizar baixa de um boleto                   | Baixar um boleto                 | [Link Documentação](/documentation/boletos/v2/instrucoes/baixa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0014 | Consultar boletos por chave      | Consultar boletos por chave      | [Link Documentação](/documentation/boletos/v2/consulta/consulta_por_chave) | BOL0001, BOL0002 ou BOL0003   |
| BOL0015 | Listar Boletos          | Listar boletos     | [Link Documentação](/documentation/boletos/v2/consulta/listar_boletos) | BOL0001, BOL0002 ou BOL0003   |
| BOL0016 | Consulta de carteira de cobrança      | Consultar uma carteira de cobrança | [Link Documentação](/documentation/boletos/v2/carteira/listar_carteiras/index.html) | BOL0001, BOL0002 ou BOL0003   |
| BOL0017 | Webhooks de Boleto      | Realizar a leitura de webhook para boleto | [Link Documentação](/documentation/boletos/v2/webhooks/boleto) | BOL0001, BOL0002 ou BOL0003   |

## Pagamento de Boletos

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| BOL0009* | Consulta de linha digitável ou Código de Barras | Realizar a consulta de uma linha digitável de um boleto bancário | [Link Documentação](/documentation/baas/cobranca/consultar_boleto_bancario) |  |
| BOL0010* | Realizar pagamento de um boleto | Realizar o pagamento de um boleto bancário | [Link Documentação](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_boleto_bancario) |  QIC0003 ou QIC0005  |
| BOL0012* | Consulta de linha digitável ou Código de Barras de um boleto de convênio | Realizar a consulta de uma linha digitável de um  boleto convênio. | [Link Documentação](/documentation/baas/cobranca/consultar_fatura_de_recolhimento) |  |
| BOL0013* | Realizar pagamento de um boleto de convênio | Realizar o pagamento de um boleto convênio | [Link Documentação](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_fatura_de_recolhimento) |  QIC0003 ou QIC0005  |

---

## Pix

## Transferência Pix 
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
|---------|--|---|---|---|
| PIX0002* | Transferência Pix Out | Realizar uma transferência Pix a partir de uma QI Conta utilizando dados bancários (pix manual) ou chave Pix | [Link Documentação](/documentation/baas/pix/realizar_transferencia) | CAB0001 |
| PIX0035 | Consulta de transferência pix | Recuperar os dados de uma transferência | [Link Documentação](/documentation/baas/pix/consultar_transferencias) | PIX0002 |
| PIX0003* | Simulação de reembolso de Pix Out | Simular o reembolso de um Pix Out. | [Link Documentação - Item 2](/documentation/pix/simulacao)| PIX0002 |
| PIX0004* | Simulação de Pix In | Simular o crédito de um Pix In em uma QI Conta. | [Link Documentação -> Item 1](/documentation/pix/simulacao)||
| PIX0037* | Leitura de webhook de transação pendente | Recepcionar com sucesso um webhook de transação pendente | [Link Documentação][(/documentation/baas/pix/webhooks) | PIX0002 |
| PIX0038* | Leitura de webhook de Pix de In | Recepcionar com sucesso um webhook de transferência Pix de entrada | [Link Documentação](/documentation/baas/pix/webhooks#webhook-para-pix-de-entrada)| PIX0004 |
| PIX0039 | Leitura de webhook de Devolução Pix | Recepcionar com sucesso um webhook de devolução de um Pix | [Link Documentação](/documentation/baas/pix/webhooks#webhook-para-devolu%C3%A7%C3%B5es-de-pix) | PIX0003 |
| PIX0040 | Solicitar a devolução de um Pix recebido | Solicitar a devolução de um Pix recebido | [Link Documentação](/documentation/baas/pix/solicitar_devolucao) | PIX0003 |
| PIX0041 | Listar transferências Pix de uma conta | Listar transferências Pix de uma conta | [Link Documentação](/documentation/baas/pix/listar_transferencias) | PIX0003 |

## Gestão de Chave Pix

### Criação e Exclusão de Chave pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0008* | Criação de chave Pix | Realizar a criação de chave Pix do tipo cpf, cnpj, aleatória, e-mail e telefone | [Link Documentação](/documentation/pix/criar_chave) | 
|QIC0003 ou QIC0005  |](/documentation/baas/pix/consultar_chave_pix)
| PIX0009 | Exclusão de chave Pix | Realizar a exclusão de uma chave Pix | [Link Documentação](/documentation/pix/excluir_chave) | PIX0008 |
| PIX0010* | Listagem de chaves Pix de uma QI Conta | Listar chaves Pix vinculadas a uma QI Conta | [Link Documentação](/documentation/pix/listar_chaves_pix) | PIX0008 |

### Portabilidade de Chave Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0013* | Criação de Solicitação de Portabilidade In de uma Chave Pix | Criar um pedido de Portabilidade In de uma Chave Pix do tipo CPF, CNPJ, E-mail, Telefone e Aleatória | [Link Documentação](/documentation/pix/portabilidade#criando-um-pedido-de-portabilidade) |  QIC0003 ou QIC0005  |
| PIX0014* | Reenvio de 2fa de uma Solicitação de Portabilidade In de uma Chave Pix do tipo E-mail ou Telefone | Solicitar o reenvio do SMS (Chave Pix do tipo Telefone) ou E-mail (Chave Pix do tipo E-mail) de uma Solicitação de Portabilidade In de uma Chave Pix pendente (pending_claimer_validation) | [Link Documentação](/documentation/pix/portabilidade#reenviando-a-valida%C3%A7%C3%A3o-de-dois-fatores) | PIX0013 |
| PIX0015* | Exclusão de Solicitação de Portabilidade In de uma Chave Pix | Excluir uma Solicitação de Portabilidade In de uma Chave Pix pendente | [Link Documentação](/documentation/pix/portabilidade#deletando-um-pedido-de-portabilidade) | PIX0013 |
| PIX0016* | Leitura de webhook de conclusão de Solicitação de Portabilidade In de Chave Pix | Ler corretamente o webhook de conclusão de uma Solicitação de Portabilidade In de uma Chave Pix. Testando todos os possíveis status de conclusão (concluded, cancelled e failed) | Webhook: <br/> [Link Documentação](/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade) |PIX0013 |
| PIX0017* | Simulação de Solicitação de Portabilidade Out de uma Chave Pix | Simular a chegada de uma solicitação de Solicitação de Portabilidade Out de uma Chave Pix | Item 5:<br/> [Link Documentação](/documentation/pix/simulacao/index.html) | PIX0013 |
| PIX0018* | Aprovação e Reprovação de Solicitação de Portabilidade Out de uma Chave Pix | Realizar a aprovação de uma Solicitação de Portabilidade Out de uma Chave Pix | [Link Documentação](/documentation/pix/portabilidade#request-4) | PIX0017 |
| PIX0019* | Reenvio de 2fa de uma Solicitação de Portabilidade Out de uma Chave Pix | Solicitar reenvio de 2fa de uma Solicitação de Portabilidade Out de uma Chave Pix | Enum “pending_donator_validation”  <br/> [Link Documentação](/documentation/pix/portabilidade#request-4) | PIX0018 |
| PIX0020* | Leitura de webhook de conclusão de Solicitação de Portabilidade Out de Chave Pix | Ler corretamente o webhook de conclusão de uma Solicitação de Portabilidade Out de uma Chave Pix. Testando todos os possíveis status de conclusão (concluded, cancelled e failed) | [Link Documentação](D/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade-1) | PIX0018 |

## Gestão de QR Code Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0022* | Criação de QR Code Pix Estático | Gerar QR Code Estático | [Link Documentação](/documentation/pix/criar_qr_code_estatico) | PIX0008 |
| PIX0023 | Criação de QR Code Pix Dinâmico | Gerar QR Code Dinâmico com vencimento (dia de vencimento) e gerar QR Code Dinâmico Instantâneo (com segundos de expiração). | [Link Documentação](/documentation/pix/criar_qr_code_dinamico) | PIX0008 |
| PIX0024 | Exclusão de QR Code Pix Dinâmico | Excluir QR Code Pix | [Link Documentação](/documentation/pix/baixar_qr_code_dinamico) | PIX0023 |
| PIX0025 | Listar QR Codes Pix Dinâmicos | Listar QR Codes Pix Dinâmicos | [Link Documentação](/documentation/pix/pesquisar_por_qr_code_dinamico) | PIX0023 |
| PIX0026 | Leitura de webhook de expiração de QR Code Pix Dinâmico Instantâneo | Recepcionar com sucesso um webhook de expiração de QR Code Pix Dinâmico Instantâneo | [Link Documentação](/documentation/pix/webhook_por_qr_code_expirado) | PIX0023 |

## Pagamento de QR Code Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |

| PIX0029* | Pagamento de QR Code Pix Estático | Realizar o pagamento de um QR Code Pix Estático | [Link Documentação](/documentation/baas/pix/realizar_transferencia#transfer%C3%AAncia-por-qr-code-pix) | PIX0022 |
| PIX0030* | Pagamento de QR Code Pix Dinâmico | Realizar o pagamento de um QR Code Pix Dinâmico |  [Link Documentação](/documentation/baas/pix/realizar_transferencia#transfer%C3%AAncia-por-qr-code-pix) | PIX0022 |
| PIX0027* | Decodificação de QR Code Pix | Decodificar um QR Code Pix Estático, Dinâmico com vencimento e Dinâmico Instantâneo | [Link Documentação](/documentation/pix/decodificar_qr_code) | PIX0022 e PIX0023 |

## Gestão de Limite Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0032* | Solicitação de alteração de limite Pix | Realizar solicitação de alteração de limite Pix de uma QI Conte | [Link Documentação](/documentation/pix/solicitar_alteracao_de_limite_pix) |  QIC0003 ou QIC0005  |
| PIX0033 | Listagem de solicitações de alteração de limite Pix | Listar as solicitações de alteração de limite Pix para uma QI Conta | [Link Documentação](/documentation/pix/busca_por_solicitacao_de_limite_pix) | PIX0032 |
| PIX0034* | Consulta de limite Pix consumido | Consultar o limite Pix consumido para uma QI Conta | [Link Documentação](/documentation/pix/busca_por_uso_de_limite_pix) |  QIC0003 ou QIC0005  |

---

# Gestão de Tarifas
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GTF0001* | Solicitação de alteração de tarifas | Realizar a alteração de tarifas de uma conta| [Link Documentação](/documentation/contas/gestao_de_tarifas) |  QIC0003 ou QIC0005  |
| GTF0002* | Consulta de tarifas  | Consultar tarifas cadastradas em uma conta | [Link Documentação](/documentation/contas/consulta_de_tarifas) |  QIC0003 ou QIC0005  |

# Gestão de Cartoẽs

## Criação de Cartão
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GDC0001* | Criação de Cartão virtual  | Realizar a criação de um cartão virtual| [Link Documentação](/documentation/cards/create/gerar_cartao_virtual) |  QIC0003 ou QIC0005  |
| GDC0002* | Criação de Cartão físico  | Realizar a criação de um cartão físico| [Link Documentação](/documentation/cards/create/gerar_cartao_fisico) |  QIC0003 ou QIC0005  |

## Consulta de Cartões
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GDC0003* | Consulta cartão por chave  | Realizar a consulta de um cartão | [Link Documentação](/documentation/cards/search/buscar_cartao_by_key) | GDC0001 ou GDC0002 |
| GDC0004* | Listar cartões  | Realizar a listagem de cartões| [Link Documentação](/documentation/cards/search/listar_cartoes) | GDC0001 ou GDC0002 |
| GDC0005* | Buscar dados de um cartão | Buscar dados de um cartão| [Link Documentação](/documentation/cards/search/buscar_dados_pci) | GDC0001 ou GDC0002 |
| GDC0006* | Buscar Senha PCI | Buscar Senha PCI| [Link Documentação](/documentation/cards/search/buscar_senha) | GDC0001 ou GDC0002 |
| GDC0007* | Consultar dados da entrega | Consultar dados da entrega| [Link Documentação](/documentation/cards/search/buscar_entrega_by_key) | GDC0001 ou GDC0002 |

## Atualizar dados de um cartão
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GDC0008* | Atualizar status de um cartão  | Atualizar status de um cartão| [Link Documentação](/documentation/cards/status/update_status_cartao) | GDC0001 ou GDC0002 |
| GDC0009* | Ativar cartão físico  | Realizar a ativação de um cartão físico| [Link Documentação](/documentation/cards/status/ativar_cartao) | GDC0001 ou GDC0002 |
| GDC0010* | Alterar Senha   | Realizar a alteração de senha de um cartão | [Link Documentação](/documentation/cards/update/password_cartao) | GDC0001 ou GDC0002 |
| GDC0011* | Configurar contactless de um cartão  | Configurar contactless de um cartão  | [Link Documentação](/documentation/cards/update/contactless_cartao) | GDC0002 |

---

# Roteiro de Homologação - BaaS Conta Digital Escrow

URL: /documentation/roteiros_de_homologacao/conta_digital_escrow

O roteiro de homolgoação descreve todos os recursos e funcionalidades que precisam
ser testados pelo parceiro integrador no ambiente de sandbox da QI Tech (ambiente de testes), 
antes da entrada em ambiente de produção do produto.

Este roteiro descreve todos os recursos e funcionalidades envolvidos no produto. 

⚠️ **Todos os testes devem ser obrigatoriamente realizados no ambiente de Sandbox da QI Tech (ambiente de testes).
As movimentações realizadas em ambiente de Sandbox são movimentações financeiras fictícias, servindo apenas para teste de funcionalidade das APIs.**

## Cadastro e Autenticação API BaaS
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| CAB0001* | Cadastro no ambiente de Sandbox | Realizar o cadastro na plataforma da QI Tech no ambiente de Sandbox (sandbox.qitech.app) | cs@qitech.com.br |
| CAB0002* | Validação de token em Sandbox | Realizar a validação do QI Token em Sandbox | [Link Documentação](https://docs.qitech.com.br/assets/pdfs/QI%20Tech%20Manual%20Inclus%C3%A3o%20de%20Token.pdf) | CAB0001 |
| CAB0003* | Troca de chaves públicas | Realizar a troca de chaves públicas dentro da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Link Documentação](/documentation/primeiros_passos/troca_de_chaves) | CAB0001 e CAB0002 |
| CAB0004* | Teste de autenticação de chamadas | Finalizar teste de autenticação de chamadas |[Link Documentação](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2) <br/><br/> [Link Documentação](/documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste) | CAB0003 |
| CAB0005* | Configuração de webhooks | Realizar a configuração da url para envio dos webhooks por parte da QI, através da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Link Documentação](/documentation/primeiros_passos/configurando_webhooks) | CAB0001 e CAB0002 |

# **QI Conta**

## Abertura de Conta

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| QIC0002* | Reserva de conta PF | Solicitar a reserva de uma conta cujo titular seja uma pessoa física | [Link Documentação](/documentation/baas/account/reservar_conta_pf) | CAB0005 e CAB0006 |
| QIC0003* | Abertura de conta PF | Realizar a abertura de uma conta cujo titular seja uma pessoa física | [Link Documentação](/documentation/baas/account/abrir_conta_pf) | QIC0002 |
| QIC0004* | Reserva de conta PJ | Solicitar a reserva de uma conta cujo titular seja uma pessoa jurídica | [Link Documentação](/documentation/baas/account/reservar_conta_pj) | CAB0005 e CAB0006 |
| QIC0005* | Abertura de conta PJ | Realizar a abertura de uma conta cujo titular seja uma pessoa jurídica | [Link Documentação](/documentation/baas/account/abrir_conta_pj) | QIC0004 |
| QIC0009* | Reserva de conta escrow PF | Solicitar a reserva de uma conta escrow cujo titular seja uma pessoa física | [Link Documentação](/documentation/baas/escrow/reservar_conta_pf) | CAB0005 e CAB0006 |
| QIC0010* | Abertura de conta escrow PF | Realizar a abertura de uma conta escrow cujo titular seja uma pessoa física | [Link Documentação](/documentation/baas/escrow/abrir_conta_pf) | CAB0005 e CAB0006 |
| QIC0011* | Reserva de conta escrow PJ | Solicitar a reserva de uma conta escrow cujo titular seja uma pessoa jurídica | [Link Documentação](/documentation/baas/escrow/reservar_conta_pj) | CAB0005 e CAB0006 |
| QIC0012* | Abertura de conta escrow PJ | Realizar a abertura de uma conta escrow cujo titular seja uma pessoa jurídica | [Link Documentação](/documentation/baas/escrow/abrir_conta_pj) | CAB0005 e CAB0006 |
| QIC0006* | Leitura de webhooks de abertura de conta | Ler corretamente os webhooks de abertura de conta | Item 1.2. ou 1.3:<br/>[Link Documentação](/documentation/baas/account/webhooks) |  QIC0003 ou QIC0005  |
| QIC0007* | Listar contas | Listar contas abertas| [Link Documentação](/documentation/contas/consultar_conta) |  QIC0003 ou QIC0005  |
| QIC0008* | Consulta de dados de uma conta | Consultar dados como saldo, dados do titular, data de abertura, dentre outros | [Link Documentação](/documentation/contas/consultar_conta) |  QIC0003 ou QIC0005  |

## Movimentações

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| QIC0008* | Consulta de Extrato | Realizar a consulta do extrato de uma conta | [Link Documentação](/documentation/movimentacao_de_contas/consulta_de_transacoes) |  QIC0003 ou QIC0005  |
| QIC0009* | Solicitação de comprovante de transferência | Solicitar um comprovante de transferência | [Link Documentação](/documentation/movimentacao_de_contas/comprovante_de_transferencia)|  |
| QIC0010* | Leitura de webhooks de transação | Recepcionar com sucesso todos os webhooks de transação |  [Link Documentação](/documentation/movimentacao_de_contas/webhook_movimentacoes/index.html) |  QIC0003 ou QIC0005  |
| QIC0011* | Consulta de lista de instituições financeiras | Consultar lista de instituições financeiras habiliatadas para recebimento de TED e Pix |  [Link Documentação](/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras) |  QIC0003 ou QIC0005  |

---

# Upload de Documentos

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| UDD0001* | Upload de documento | Realizar o upload de um documento através da nossa API de documentos |  [Link Documentação](/documentation/upload_de_documentos/) |  |

---

# TED

| Código | Etapa | Descrição | Link                                                                                                        | Pré-requisito |
| --- | --- | --- |-------------------------------------------------------------------------------------------------------------| --- |
| TED0001* | Transferência TED Out | Realizar transferência TED  | [Link Documentação](/documentation/baas/ted/realizar_transferencia) | QIC0003 ou QIC0005 |
| TED0002* | Simulação de estorno de uma TED Out | Simular o estorno de uma TED Out enviada a partira de uma QI Conta | Item 3: <br/>[Link Documentação](/documentation/movimentacao_de_contas/transacao) | TED0003 |
| TED0003* | Simulação de TED In | Simular a entrada de uma TED In em uma QI conta | Item 2: <br/>[Link Documentação](/documentation/movimentacao_de_contas/transacao) | QIC0003 ou QIC0005 |
| TED0004* | Listar transações TED| Listar transações TED de entrada/saída  | [Link Documentação](/documentation/baas/ted/listar_teds)  | QIC0003 ou QIC0005 |
| TED0004* | Consulta de transação  TED| Realizar a consulta de uma transação TED  | [Link Documentação](/documentation/baas/ted/consultar_ted)           | QIC0003 ou QIC0005 |
| TED0006* | Leitura de webhooks de TED| Recepcionar com sucesso um webhook de TED | [Link Documentação](/documentation/baas/ted/webhooks/index.html)| QIC0003 ou QIC0005 |
---

# Transferência Interna

| Nº | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| TFI0001 | Transferência Interna com débito em conta | Comandar uma transferência a partir de uma QI Conta, tendo como destino da transferência, outra QI Conta | [Link Documentação](/documentation/baas/ted/realizar_transferencia) |  QIC0003 ou QIC0005  |
| TFI0002 | Simulação de transferência Interna com crédito em conta | Simular o recebimento de recursos na QI Conta alvo, tendo como origem, outra QI Conta | Item 1: <br/> [Link Documentação](/documentation/movimentacao_de_contas/transacao) |  QIC0003 ou QIC0005  |

---

# Boletos

## Gestão de Boletos

| Nº | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| Nº      | Etapa | Descrição | Link  | Pré-requisito |
|---|---|---|---|---|
| BOL0001 | Registro de boleto de um único boleto cobrança    | Realizar o registro de um boleto de cobrança | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao/index.html) | CAB0002 ou CAB0003   |
| BOL0002 | Registro de boleto de um único boleto de cobrança instantâneo | Realizar o registro de um boleto de cobrança | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) | CAB0002 ou CAB0003   |
| BOL0003 | Registro de boleto de boleto em lote  | Realizar o registro de boleto de cobrança em lote | [Link Documentação](/documentation/boletos/v2/emissao/emissao_em_lote) | CAB0002 ou CAB0003   |
| BOL0004 | Emissão de Boleto Único Padrão        | Emitir um boleto único padrão    | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao)  | CAB0002 ou CAB0003   |
| BOL0005 | Emissão de Boleto Único Instantâneo   | Emitir um boleto único instantân | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) | CAB0002 ou CAB0003   |
| BOL0006 | Emissão em Lote   | Emitir boletos em lote | [Link Documentação](/documentation/boletos/v2/emissao/emissao_em_lote)| CAB0002 ou CAB0003   |
| BOL0007 | Realizar abatimento no valor de um boleto | Realizar abatimento no valor de um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/abatimento/criar_abatimento) | BOL0001, BOL0002 ou BOL0003 |
| BOL0008 | Cancelar Abatimento     | Cancelar abatimento em um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/abatimento/cancelar_abatimento) | BOL0001, BOL0002 ou BOL0003  |
| BOL0009 | Estender vencimento de um boleto               | Enviar extensão de prazo de um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/extensao)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0010 | Incluir desconto em um boleto               | Incluir desconto em um boleto    | [Link Documentação](/documentation/boletos/v2/instrucoes/desconto)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0011 | Incluir juros em um boleto                   | Incluir juros em um boleto       | [Link Documentação](/documentation/boletos/v2/instrucoes/juros)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0012 | Incluir multa em um boleto                   | Incluir multa em um boleto       | [Link Documentação](/documentation/boletos/v2/instrucoes/multa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0013 | Realizar baixa de um boleto                   | Baixar um boleto                 | [Link Documentação](/documentation/boletos/v2/instrucoes/baixa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0014 | Consultar boletos por chave      | Consultar boletos por chave      | [Link Documentação](/documentation/boletos/v2/consulta/consulta_por_chave) | BOL0001, BOL0002 ou BOL0003   |
| BOL0015 | Listar Boletos          | Listar boletos     | [Link Documentação](/documentation/boletos/v2/consulta/listar_boletos) | BOL0001, BOL0002 ou BOL0003   |
| BOL0016 | Consulta de carteira de cobrança      | Consultar uma carteira de cobrança | [Link Documentação](/documentation/boletos/v2/carteira/listar_carteiras/index.html) | BOL0001, BOL0002 ou BOL0003   |
| BOL0017 | Webhooks de Boleto      | Realizar a leitura de webhook para boleto | [Link Documentação](/documentation/boletos/v2/webhooks/boleto) | BOL0001, BOL0002 ou BOL0003   |

## Pagamento de Boletos

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| BOL0009* | Consulta de linha digitável ou Código de Barras | Realizar a consulta de uma linha digitável de um boleto bancário | [Link Documentação](/documentation/baas/cobranca/consultar_boleto_bancario) |  |
| BOL0010* | Realizar pagamento de um boleto | Realizar o pagamento de um boleto bancário | [Link Documentação](/documentation/baas/cobranca/pagar_boleto_bancario) |  QIC0003 ou QIC0005  |
| BOL0012* | Consulta de linha digitável ou Código de Barras de um boleto de convênio | Realizar a consulta de uma linha digitável de um  boleto convênio. | [Link Documentação](/documentation/baas/cobranca/consultar_fatura_de_recolhimento) |  |
| BOL0013* | Realizar pagamento de um boleto de convênio | Realizar o pagamento de um boleto convênio | [Link Documentação](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_fatura_de_recolhimento) |  QIC0003 ou QIC0005  |

---

## Pix

## Transferência Pix 
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
|---------|--|---|---|---|
| PIX0002* | Transferência Pix Out | Realizar uma transferência Pix a partir de uma QI Conta utilizando dados bancários (pix manual) ou chave Pix | [Link Documentação](/documentation/baas/pix/realizar_transferencia) | CAB0001 |
| PIX0035 | Consulta de transferência pix | Recuperar os dados de uma transferência | [Link Documentação](/documentation/baas/pix/consultar_transferencias) | PIX0002 |
| PIX0003* | Simulação de reembolso de Pix Out | Simular o reembolso de um Pix Out. | [Link Documentação - Item 2](/documentation/pix/simulacao)| PIX0002 |
| PIX0004* | Simulação de Pix In | Simular o crédito de um Pix In em uma QI Conta. | [Link Documentação -> Item 1](/documentation/pix/simulacao)||
| PIX0037* | Leitura de webhook de transação pendente | Recepcionar com sucesso um webhook de transação pendente | [Link Documentação][(/documentation/baas/pix/webhooks) | PIX0002 |
| PIX0038* | Leitura de webhook de Pix de In | Recepcionar com sucesso um webhook de transferência Pix de entrada | [Link Documentação](/documentation/baas/pix/webhooks#webhook-para-pix-de-entrada)| PIX0004 |
| PIX0039 | Leitura de webhook de Devolução Pix | Recepcionar com sucesso um webhook de devolução de um Pix | [Link Documentação](/documentation/baas/pix/webhooks#webhook-para-devolu%C3%A7%C3%B5es-de-pix) | PIX0003 |
| PIX0040 | Solicitar a devolução de um Pix recebido | Solicitar a devolução de um Pix recebido | [Link Documentação](/documentation/baas/pix/solicitar_devolucao) | PIX0003 |
| PIX0041 | Listar transferências Pix de uma conta | Listar transferências Pix de uma conta | [Link Documentação](/documentation/baas/pix/listar_transferencias) | PIX0003 |

## Gestão de Chave Pix

### Criação e Exclusão de Chave pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0008* | Criação de chave Pix | Realizar a criação de chave Pix do tipo cpf, cnpj, aleatória, e-mail e telefone | [Link Documentação](/documentation/pix/criar_chave) | 
|QIC0003 ou QIC0005  |](/documentation/baas/pix/consultar_chave_pix)
| PIX0009 | Exclusão de chave Pix | Realizar a exclusão de uma chave Pix | [Link Documentação](/documentation/pix/excluir_chave) | PIX0008 |
| PIX0010* | Listagem de chaves Pix de uma QI Conta | Listar chaves Pix vinculadas a uma QI Conta | [Link Documentação](/documentation/pix/listar_chaves_pix) | PIX0008 |

### Portabilidade de Chave Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0013* | Criação de Solicitação de Portabilidade In de uma Chave Pix | Criar um pedido de Portabilidade In de uma Chave Pix do tipo CPF, CNPJ, E-mail, Telefone e Aleatória | [Link Documentação](/documentation/pix/portabilidade#criando-um-pedido-de-portabilidade) |  QIC0003 ou QIC0005  |
| PIX0014* | Reenvio de 2fa de uma Solicitação de Portabilidade In de uma Chave Pix do tipo E-mail ou Telefone | Solicitar o reenvio do SMS (Chave Pix do tipo Telefone) ou E-mail (Chave Pix do tipo E-mail) de uma Solicitação de Portabilidade In de uma Chave Pix pendente (pending_claimer_validation) | [Link Documentação](/documentation/pix/portabilidade#reenviando-a-valida%C3%A7%C3%A3o-de-dois-fatores) | PIX0013 |
| PIX0015* | Exclusão de Solicitação de Portabilidade In de uma Chave Pix | Excluir uma Solicitação de Portabilidade In de uma Chave Pix pendente | [Link Documentação](/documentation/pix/portabilidade#deletando-um-pedido-de-portabilidade) | PIX0013 |
| PIX0016* | Leitura de webhook de conclusão de Solicitação de Portabilidade In de Chave Pix | Ler corretamente o webhook de conclusão de uma Solicitação de Portabilidade In de uma Chave Pix. Testando todos os possíveis status de conclusão (concluded, cancelled e failed) | Webhook: <br/> [Link Documentação](/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade) |PIX0013 |
| PIX0017* | Simulação de Solicitação de Portabilidade Out de uma Chave Pix | Simular a chegada de uma solicitação de Solicitação de Portabilidade Out de uma Chave Pix | Item 5:<br/> [Link Documentação](/documentation/pix/simulacao/index.html) | PIX0013 |
| PIX0018* | Aprovação e Reprovação de Solicitação de Portabilidade Out de uma Chave Pix | Realizar a aprovação de uma Solicitação de Portabilidade Out de uma Chave Pix | [Link Documentação](/documentation/pix/portabilidade#request-4) | PIX0017 |
| PIX0019* | Reenvio de 2fa de uma Solicitação de Portabilidade Out de uma Chave Pix | Solicitar reenvio de 2fa de uma Solicitação de Portabilidade Out de uma Chave Pix | Enum “pending_donator_validation”  <br/> [Link Documentação](/documentation/pix/portabilidade#request-4) | PIX0018 |
| PIX0020* | Leitura de webhook de conclusão de Solicitação de Portabilidade Out de Chave Pix | Ler corretamente o webhook de conclusão de uma Solicitação de Portabilidade Out de uma Chave Pix. Testando todos os possíveis status de conclusão (concluded, cancelled e failed) | [Link Documentação](D/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade-1) | PIX0018 |

## Gestão de QR Code Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0022* | Criação de QR Code Pix Estático | Gerar QR Code Estático | [Link Documentação](/documentation/pix/criar_qr_code_estatico) | PIX0008 |
| PIX0023 | Criação de QR Code Pix Dinâmico | Gerar QR Code Dinâmico com vencimento (dia de vencimento) e gerar QR Code Dinâmico Instantâneo (com segundos de expiração). | [Link Documentação](/documentation/pix/criar_qr_code_dinamico) | PIX0008 |
| PIX0024 | Exclusão de QR Code Pix Dinâmico | Excluir QR Code Pix | [Link Documentação](/documentation/pix/baixar_qr_code_dinamico) | PIX0023 |
| PIX0025 | Listar QR Codes Pix Dinâmicos | Listar QR Codes Pix Dinâmicos | [Link Documentação](/documentation/pix/pesquisar_por_qr_code_dinamico) | PIX0023 |
| PIX0026 | Leitura de webhook de expiração de QR Code Pix Dinâmico Instantâneo | Recepcionar com sucesso um webhook de expiração de QR Code Pix Dinâmico Instantâneo | [Link Documentação](/documentation/pix/webhook_por_qr_code_expirado) | PIX0023 |

## Pagamento de QR Code Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |

| PIX0029* | Pagamento de QR Code Pix Estático | Realizar o pagamento de um QR Code Pix Estático | [Link Documentação](/documentation/baas/pix/realizar_transferencia#transfer%C3%AAncia-por-qr-code-pix) | PIX0022 |
| PIX0030* | Pagamento de QR Code Pix Dinâmico | Realizar o pagamento de um QR Code Pix Dinâmico |  [Link Documentação](/documentation/baas/pix/realizar_transferencia#transfer%C3%AAncia-por-qr-code-pix) | PIX0022 |
| PIX0027* | Decodificação de QR Code Pix | Decodificar um QR Code Pix Estático, Dinâmico com vencimento e Dinâmico Instantâneo | [Link Documentação](/documentation/pix/decodificar_qr_code) | PIX0022 e PIX0023 |

## Gestão de Limite Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0032* | Solicitação de alteração de limite Pix | Realizar solicitação de alteração de limite Pix de uma QI Conte | [Link Documentação](/documentation/pix/solicitar_alteracao_de_limite_pix) |  QIC0003 ou QIC0005  |
| PIX0033 | Listagem de solicitações de alteração de limite Pix | Listar as solicitações de alteração de limite Pix para uma QI Conta | [Link Documentação](/documentation/pix/busca_por_solicitacao_de_limite_pix) | PIX0032 |
| PIX0034* | Consulta de limite Pix consumido | Consultar o limite Pix consumido para uma QI Conta | [Link Documentação](/documentation/pix/busca_por_uso_de_limite_pix) |  QIC0003 ou QIC0005  |

---

# Gestão de Tarifas
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GTF0001* | Solicitação de alteração de tarifas | Realizar a alteração de tarifas de uma conta| [Link Documentação](/documentation/contas/gestao_de_tarifas) |  QIC0003 ou QIC0005  |
| GTF0002* | Consulta de tarifas  | Consultar tarifas cadastradas em uma conta | [Link Documentação](/documentation/contas/consulta_de_tarifas) |  QIC0003 ou QIC0005  |

# Gestão de Cartoẽs

## Criação de Cartão
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GDC0001* | Criação de Cartão virtual  | Realizar a criação de um cartão virtual| [Link Documentação](/documentation/cards/create/gerar_cartao_virtual) |  QIC0003 ou QIC0005  |
| GDC0002* | Criação de Cartão físico  | Realizar a criação de um cartão físico| [Link Documentação](/documentation/cards/create/gerar_cartao_fisico) |  QIC0003 ou QIC0005  |

## Consulta de Cartões
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GDC0003* | Consulta cartão por chave  | Realizar a consulta de um cartão | [Link Documentação](/documentation/cards/search/buscar_cartao_by_key) | GDC0001 ou GDC0002 |
| GDC0004* | Listar cartões  | Realizar a listagem de cartões| [Link Documentação](/documentation/cards/search/listar_cartoes) | GDC0001 ou GDC0002 |
| GDC0005* | Buscar dados de um cartão | Buscar dados de um cartão| [Link Documentação](/documentation/cards/search/buscar_dados_pci) | GDC0001 ou GDC0002 |
| GDC0006* | Buscar Senha PCI | Buscar Senha PCI| [Link Documentação](/documentation/cards/search/buscar_senha) | GDC0001 ou GDC0002 |
| GDC0007* | Consultar dados da entrega | Consultar dados da entrega| [Link Documentação](/documentation/cards/search/buscar_entrega_by_key) | GDC0001 ou GDC0002 |

## Atualizar dados de um cartão
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GDC0008* | Atualizar status de um cartão  | Atualizar status de um cartão| [Link Documentação](/documentation/cards/status/update_status_cartao) | GDC0001 ou GDC0002 |
| GDC0009* | Ativar cartão físico  | Realizar a ativação de um cartão físico| [Link Documentação](/documentation/cards/status/ativar_cartao) | GDC0001 ou GDC0002 |
| GDC0010* | Alterar Senha   | Realizar a alteração de senha de um cartão | [Link Documentação](/documentation/cards/update/password_cartao) | GDC0001 ou GDC0002 |
| GDC0011* | Configurar contactless de um cartão  | Configurar contactless de um cartão  | [Link Documentação](/documentation/cards/update/contactless_cartao) | GDC0002 |

---

# Roteiro de Homologação - BaaS Conta Digital Escrow

URL: /documentation/roteiros_de_homologacao/conta_digital_escrow_caas

O roteiro de homolgoação descreve todos os recursos e funcionalidades que precisam
ser testados pelo parceiro integrador no ambiente de sandbox da QI Tech (ambiente de testes), 
antes da entrada em ambiente de produção do produto.

Este roteiro descreve todos os recursos e funcionalidades envolvidos no produto. 

⚠️ **Todos os testes devem ser obrigatoriamente realizados no ambiente de Sandbox da QI Tech (ambiente de testes).
As movimentações realizadas em ambiente de Sandbox são movimentações financeiras fictícias, servindo apenas para teste de funcionalidade das APIs.**

## Cadastro e Autenticação API BaaS
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| CAB0001* | Cadastro no ambiente de Sandbox | Realizar o cadastro na plataforma da QI Tech no ambiente de Sandbox (sandbox.qitech.app) | cs@qitech.com.br |
| CAB0002* | Validação de token em Sandbox | Realizar a validação do QI Token em Sandbox | [Link Documentação](https://docs.qitech.com.br/assets/pdfs/QI%20Tech%20Manual%20Inclus%C3%A3o%20de%20Token.pdf) | CAB0001 |
| CAB0003* | Troca de chaves públicas | Realizar a troca de chaves públicas dentro da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Link Documentação](/documentation/primeiros_passos/troca_de_chaves) | CAB0001 e CAB0002 |
| CAB0004* | Teste de autenticação de chamadas | Finalizar teste de autenticação de chamadas |[Link Documentação](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2) <br/><br/> [Link Documentação](/documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste) | CAB0003 |
| CAB0005* | Configuração de webhooks | Realizar a configuração da url para envio dos webhooks por parte da QI, através da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Link Documentação](/documentation/primeiros_passos/configurando_webhooks) | CAB0001 e CAB0002 |

## Antifraude

## Cadastro e Autenticação

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| ATF0002* | Obtenção de API-key de onboarding | Obter junto ao time de integração da QI Tech a chave de API para uso da API de /onboarding | suporte.caas@qitech.com.br |  
| ATF0003* | Obtenção de mobile-token de OCR | Obter junto ao time de integração da QI Tech o Mobile Token  para uso do SDK de OCR | suporte.caas@qitech.com.br |  
| ATF0004* | Obtenção de mobile-token de Face Recognition | Obter junto ao time de integração da QI Tech o Mobile Token  para uso do SDK de Face Recognition | suporte.caas@qitech.com.br |  
| ATF0005* | Obtenção de mobile-token de Device scan | Obter junto ao time de integração da QI Tech o Mobile Token  para uso do SDK de Device scan | suporte.caas@qitech.com.br |  

## SDK OCR

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| ATF0007* | Build do SDK | Definir o template e customizações para coleta dos documentos e buildar o SDK com sucesso dentro da sua aplicação (aplicação do cliente QI Tech) | Android: [Link Documentação](/documentation/caas/ocr/android/introduction) <br/> iOS:[ Link Documentação](/documentation/caas/ocr/ios/introduction) |  |
| ATF0008* | Envio de documentos | Realizar a coleta de documentos utilizando o SDK dentro da sua aplicação (aplicação cliente QI Tech) |  | ATF0003 e ATF0007 |
| ATF0009* | Armazenamento de ocr_key | Armazenar as chaves retornadas pelo SDK, identificando a natureza do documento coletado (ex: cnh_front, cnh_back, etc) | Android: [Link Documentação](/documentation/caas/ocr/android/collecting_response) <br/>iOS:[ Link Documentação](/documentation/caas/ocr/ios/collecting_response)| ATF0008 |

## SDK Face Recognition

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| ATF0011* | Build do SDK | Definir customizações e buildar o SDK com sucesso dentro da sua aplicação (aplicação do cliente QI Tech) |Android: [Link Documentação](/documentation/caas/face_recognition/android/introduction) <br/>iOS:[ Link Documentação](/documentation/caas/face_recognition/ios/introduction)  |  |
| ATF0012* | Fluxo de prova de vida | Realizar o fluxo de prova de vida utilizando o SDK dentro da sua aplicação (aplicação cliente QI Tech) | | ATF0004 e ATF0011* |
| ATF0013* | Armazenamento de chave de imagem | Armazenar a image_key retornada pelo SDK após finalização do fluxo de prova de vida | Android: [Link Documentação](/documentation/caas/face_recognition/android/collecting_response) iOS:[ Link Documentação](/documentation/caas/face_recognition/ios/collecting_response) | ATF0012 |

## SDK Device Scan

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| ATF0015* | Build do SDK | Definição das permissões a serem solicitadas ao usuário por sua aplicação (aplicação do cliente QI Tech) e buildar o SDK com sucesso dentro da sua aplicação (aplicação do cliente QI Tech) | Android: [Link Documentação](/documentation/caas/device_scan/android/introduction)<br/>iOS:[ Link Documentação](/documentation/caas/device_scan/ios/introduction)|  
| ATF0016* | Armazenamento da sessão do usuário | Realizar o armazenamento da sessão do usuário (sessionId) que terá o dispositivo escaneado | Android: [Link Documentação](/documentation/caas/device_scan/android/example)<br/>iOS:[ Link Documentação](/documentation/caas/device_scan/ios/example) | ATF0015 e ATF0017 |
| ATF0017* | Coleta de informações | Instanciar o SDK com o sessionId armazenado e chamar o método de coleta de informações dentro de sua aplicação (aplicação do cliente QI Tech) | Android: [Link Documentação](/documentation/caas/face_recognition/android/collecting_response)<br/>iOS:[ Link Documentação](/documentation/caas/face_recognition/ios/collecting_response) | ATF0005 e ATF0015 |

## Antifraude

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| ATF0019* | Antifraude PF | Realizar com sucesso o antifraude de uma cliente pessoa física | [Link Documentação](/documentation/caas/onboarding/natural_person) | ATF0002 |
| ATF0020* | Antifraude PJ | Realizar com sucesso o antifraude de uma cliente pessoa jurídica | [Link Documentação](/documentation/caas/onboarding/legal_person) | ATF0002 |
| ATF0021* | Leitura de webhooks de analises derivadas para fluxo assíncrono | Recepcionar com sucesso o webhook de análise derivada para o fluxo de resposta assíncrona |[Link Documentação](/documentation/caas/onboarding/webhook) | ATF0019 ou ATF0020 |

## Cadastro Plataforma

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| ATF0022* | Cadastro de usuário Master | Realizar o cadastro de um usuário Master na plataforma do CaaS, para resolução de solicitações derivadas para “Análise manual”  | suporte.caas@qitech.com.br | ATF0019 ou ATF0020 |

---

# **QI Conta**

## Abertura de Conta

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| QIC0002* | Reserva de conta PF | Solicitar a reserva de uma conta cujo titular seja uma pessoa física | [Link Documentação](/documentation/baas/account/reservar_conta_pf) | CAB0005 e CAB0006 |
| QIC0003* | Abertura de conta PF | Realizar a abertura de uma conta cujo titular seja uma pessoa física | [Link Documentação](/documentation/baas/account/abrir_conta_pf) | QIC0002 |
| QIC0004* | Reserva de conta PJ | Solicitar a reserva de uma conta cujo titular seja uma pessoa jurídica | [Link Documentação](/documentation/baas/account/reservar_conta_pj) | CAB0005 e CAB0006 |
| QIC0005* | Abertura de conta PJ | Realizar a abertura de uma conta cujo titular seja uma pessoa jurídica | [Link Documentação](/documentation/baas/account/abrir_conta_pj) | QIC0004 |
| QIC0009* | Reserva de conta escrow PF | Solicitar a reserva de uma conta escrow cujo titular seja uma pessoa física | [Link Documentação](/documentation/baas/escrow/reservar_conta_pf) | CAB0005 e CAB0006 |
| QIC0010* | Abertura de conta escrow PF | Realizar a abertura de uma conta escrow cujo titular seja uma pessoa física | [Link Documentação](/documentation/baas/escrow/abrir_conta_pf) | CAB0005 e CAB0006 |
| QIC0011* | Reserva de conta escrow PJ | Solicitar a reserva de uma conta escrow cujo titular seja uma pessoa jurídica | [Link Documentação](/documentation/baas/escrow/reservar_conta_pj) | CAB0005 e CAB0006 |
| QIC0012* | Abertura de conta escrow PJ | Realizar a abertura de uma conta escrow cujo titular seja uma pessoa jurídica | [Link Documentação](/documentation/baas/escrow/abrir_conta_pj) | CAB0005 e CAB0006 |
| QIC0006* | Leitura de webhooks de abertura de conta | Ler corretamente os webhooks de abertura de conta | Item 1.2. ou 1.3:<br/>[Link Documentação](/documentation/baas/account/webhooks) |  QIC0003 ou QIC0005  |
| QIC0007* | Listar contas | Listar contas abertas| [Link Documentação](/documentation/contas/consultar_conta) |  QIC0003 ou QIC0005  |
| QIC0008* | Consulta de dados de uma conta | Consultar dados como saldo, dados do titular, data de abertura, dentre outros | [Link Documentação](/documentation/contas/consultar_conta) |  QIC0003 ou QIC0005  |

## Movimentações

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| QIC0008* | Consulta de Extrato | Realizar a consulta do extrato de uma conta | [Link Documentação](/documentation/movimentacao_de_contas/consulta_de_transacoes) |  QIC0003 ou QIC0005  |
| QIC0009* | Solicitação de comprovante de transferência | Solicitar um comprovante de transferência | [Link Documentação](/documentation/movimentacao_de_contas/comprovante_de_transferencia)|  |
| QIC0010* | Leitura de webhooks de transação | Recepcionar com sucesso todos os webhooks de transação |  [Link Documentação](/documentation/movimentacao_de_contas/webhook_movimentacoes/index.html) |  QIC0003 ou QIC0005  |
| QIC0011* | Consulta de lista de instituições financeiras | Consultar lista de instituições financeiras habiliatadas para recebimento de TED e Pix |  [Link Documentação](/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras) |  QIC0003 ou QIC0005  |

---

# Upload de Documentos

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| UDD0001* | Upload de documento | Realizar o upload de um documento através da nossa API de documentos |  [Link Documentação](/documentation/upload_de_documentos/) |  |

---

# TED

| Código | Etapa | Descrição | Link                                                                                                        | Pré-requisito |
| --- | --- | --- |-------------------------------------------------------------------------------------------------------------| --- |
| TED0001* | Transferência TED Out | Realizar transferência TED  | [Link Documentação](/documentation/baas/ted/realizar_transferencia) | QIC0003 ou QIC0005 |
| TED0002* | Simulação de estorno de uma TED Out | Simular o estorno de uma TED Out enviada a partira de uma QI Conta | Item 3: <br/>[Link Documentação](/documentation/movimentacao_de_contas/transacao) | TED0003 |
| TED0003* | Simulação de TED In | Simular a entrada de uma TED In em uma QI conta | Item 2: <br/>[Link Documentação](/documentation/movimentacao_de_contas/transacao) | QIC0003 ou QIC0005 |
| TED0004* | Listar transações TED| Listar transações TED de entrada/saída  | [Link Documentação](/documentation/baas/ted/listar_teds)  | QIC0003 ou QIC0005 |
| TED0004* | Consulta de transação  TED| Realizar a consulta de uma transação TED  | [Link Documentação](/documentation/baas/ted/consultar_ted)           | QIC0003 ou QIC0005 |
| TED0006* | Leitura de webhooks de TED| Recepcionar com sucesso um webhook de TED | [Link Documentação](/documentation/baas/ted/webhooks/index.html)| QIC0003 ou QIC0005 |
---

# Transferência Interna

| Nº | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| TFI0001 | Transferência Interna com débito em conta | Comandar uma transferência a partir de uma QI Conta, tendo como destino da transferência, outra QI Conta | [Link Documentação](/documentation/baas/ted/realizar_transferencia) |  QIC0003 ou QIC0005  |
| TFI0002 | Simulação de transferência Interna com crédito em conta | Simular o recebimento de recursos na QI Conta alvo, tendo como origem, outra QI Conta | Item 1: <br/> [Link Documentação](/documentation/movimentacao_de_contas/transacao) |  QIC0003 ou QIC0005  |

---

# Boletos

## Gestão de Boletos

| Nº | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| Nº      | Etapa | Descrição | Link  | Pré-requisito |
|---|---|---|---|---|
| BOL0001 | Registro de boleto de um único boleto cobrança    | Realizar o registro de um boleto de cobrança | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao/index.html) | CAB0002 ou CAB0003   |
| BOL0002 | Registro de boleto de um único boleto de cobrança instantâneo | Realizar o registro de um boleto de cobrança | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) | CAB0002 ou CAB0003   |
| BOL0003 | Registro de boleto de boleto em lote  | Realizar o registro de boleto de cobrança em lote | [Link Documentação](/documentation/boletos/v2/emissao/emissao_em_lote) | CAB0002 ou CAB0003   |
| BOL0004 | Emissão de Boleto Único Padrão        | Emitir um boleto único padrão    | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao)  | CAB0002 ou CAB0003   |
| BOL0005 | Emissão de Boleto Único Instantâneo   | Emitir um boleto único instantân | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) | CAB0002 ou CAB0003   |
| BOL0006 | Emissão em Lote   | Emitir boletos em lote | [Link Documentação](/documentation/boletos/v2/emissao/emissao_em_lote)| CAB0002 ou CAB0003   |
| BOL0007 | Realizar abatimento no valor de um boleto | Realizar abatimento no valor de um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/abatimento/criar_abatimento) | BOL0001, BOL0002 ou BOL0003 |
| BOL0008 | Cancelar Abatimento     | Cancelar abatimento em um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/abatimento/cancelar_abatimento) | BOL0001, BOL0002 ou BOL0003  |
| BOL0009 | Estender vencimento de um boleto               | Enviar extensão de prazo de um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/extensao)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0010 | Incluir desconto em um boleto               | Incluir desconto em um boleto    | [Link Documentação](/documentation/boletos/v2/instrucoes/desconto)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0011 | Incluir juros em um boleto                   | Incluir juros em um boleto       | [Link Documentação](/documentation/boletos/v2/instrucoes/juros)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0012 | Incluir multa em um boleto                   | Incluir multa em um boleto       | [Link Documentação](/documentation/boletos/v2/instrucoes/multa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0013 | Realizar baixa de um boleto                   | Baixar um boleto                 | [Link Documentação](/documentation/boletos/v2/instrucoes/baixa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0014 | Consultar boletos por chave      | Consultar boletos por chave      | [Link Documentação](/documentation/boletos/v2/consulta/consulta_por_chave) | BOL0001, BOL0002 ou BOL0003   |
| BOL0015 | Listar Boletos          | Listar boletos     | [Link Documentação](/documentation/boletos/v2/consulta/listar_boletos) | BOL0001, BOL0002 ou BOL0003   |
| BOL0016 | Consulta de carteira de cobrança      | Consultar uma carteira de cobrança | [Link Documentação](/documentation/boletos/v2/carteira/listar_carteiras/index.html) | BOL0001, BOL0002 ou BOL0003   |
| BOL0017 | Webhooks de Boleto      | Realizar a leitura de webhook para boleto | [Link Documentação](/documentation/boletos/v2/webhooks/boleto) | BOL0001, BOL0002 ou BOL0003   |

## Pagamento de Boletos

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| BOL0009* | Consulta de linha digitável ou Código de Barras | Realizar a consulta de uma linha digitável de um boleto bancário | [Link Documentação](/documentation/baas/cobranca/consultar_boleto_bancario) |  |
| BOL0010* | Realizar pagamento de um boleto | Realizar o pagamento de um boleto bancário | [Link Documentação](/documentation/baas/cobranca/pagar_boleto_bancario) |  QIC0003 ou QIC0005  |
| BOL0012* | Consulta de linha digitável ou Código de Barras de um boleto de convênio | Realizar a consulta de uma linha digitável de um  boleto convênio. | [Link Documentação](/documentation/baas/cobranca/consultar_fatura_de_recolhimento) |  |
| BOL0013* | Realizar pagamento de um boleto de convênio | Realizar o pagamento de um boleto convênio | [Link Documentação](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_fatura_de_recolhimento) |  QIC0003 ou QIC0005  |

---

## Pix

## Transferência Pix 
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
|---------|--|---|---|---|
| PIX0002* | Transferência Pix Out | Realizar uma transferência Pix a partir de uma QI Conta utilizando dados bancários (pix manual) ou chave Pix | [Link Documentação](/documentation/baas/pix/realizar_transferencia) | CAB0001 |
| PIX0035 | Consulta de transferência pix | Recuperar os dados de uma transferência | [Link Documentação](/documentation/baas/pix/consultar_transferencias) | PIX0002 |
| PIX0003* | Simulação de reembolso de Pix Out | Simular o reembolso de um Pix Out. | [Link Documentação - Item 2](/documentation/pix/simulacao)| PIX0002 |
| PIX0004* | Simulação de Pix In | Simular o crédito de um Pix In em uma QI Conta. | [Link Documentação -> Item 1](/documentation/pix/simulacao)||
| PIX0037* | Leitura de webhook de transação pendente | Recepcionar com sucesso um webhook de transação pendente | [Link Documentação][(/documentation/baas/pix/webhooks) | PIX0002 |
| PIX0038* | Leitura de webhook de Pix de In | Recepcionar com sucesso um webhook de transferência Pix de entrada | [Link Documentação](/documentation/baas/pix/webhooks#webhook-para-pix-de-entrada)| PIX0004 |
| PIX0039 | Leitura de webhook de Devolução Pix | Recepcionar com sucesso um webhook de devolução de um Pix | [Link Documentação](/documentation/baas/pix/webhooks#webhook-para-devolu%C3%A7%C3%B5es-de-pix) | PIX0003 |
| PIX0040 | Solicitar a devolução de um Pix recebido | Solicitar a devolução de um Pix recebido | [Link Documentação](/documentation/baas/pix/solicitar_devolucao) | PIX0003 |
| PIX0041 | Listar transferências Pix de uma conta | Listar transferências Pix de uma conta | [Link Documentação](/documentation/baas/pix/listar_transferencias) | PIX0003 |

## Gestão de Chave Pix

### Criação e Exclusão de Chave pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0008* | Criação de chave Pix | Realizar a criação de chave Pix do tipo cpf, cnpj, aleatória, e-mail e telefone | [Link Documentação](/documentation/pix/criar_chave) | 
|QIC0003 ou QIC0005  |](/documentation/baas/pix/consultar_chave_pix)
| PIX0009 | Exclusão de chave Pix | Realizar a exclusão de uma chave Pix | [Link Documentação](/documentation/pix/excluir_chave) | PIX0008 |
| PIX0010* | Listagem de chaves Pix de uma QI Conta | Listar chaves Pix vinculadas a uma QI Conta | [Link Documentação](/documentation/pix/listar_chaves_pix) | PIX0008 |

### Portabilidade de Chave Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0013* | Criação de Solicitação de Portabilidade In de uma Chave Pix | Criar um pedido de Portabilidade In de uma Chave Pix do tipo CPF, CNPJ, E-mail, Telefone e Aleatória | [Link Documentação](/documentation/pix/portabilidade#criando-um-pedido-de-portabilidade) |  QIC0003 ou QIC0005  |
| PIX0014* | Reenvio de 2fa de uma Solicitação de Portabilidade In de uma Chave Pix do tipo E-mail ou Telefone | Solicitar o reenvio do SMS (Chave Pix do tipo Telefone) ou E-mail (Chave Pix do tipo E-mail) de uma Solicitação de Portabilidade In de uma Chave Pix pendente (pending_claimer_validation) | [Link Documentação](/documentation/pix/portabilidade#reenviando-a-valida%C3%A7%C3%A3o-de-dois-fatores) | PIX0013 |
| PIX0015* | Exclusão de Solicitação de Portabilidade In de uma Chave Pix | Excluir uma Solicitação de Portabilidade In de uma Chave Pix pendente | [Link Documentação](/documentation/pix/portabilidade#deletando-um-pedido-de-portabilidade) | PIX0013 |
| PIX0016* | Leitura de webhook de conclusão de Solicitação de Portabilidade In de Chave Pix | Ler corretamente o webhook de conclusão de uma Solicitação de Portabilidade In de uma Chave Pix. Testando todos os possíveis status de conclusão (concluded, cancelled e failed) | Webhook: <br/> [Link Documentação](/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade) |PIX0013 |
| PIX0017* | Simulação de Solicitação de Portabilidade Out de uma Chave Pix | Simular a chegada de uma solicitação de Solicitação de Portabilidade Out de uma Chave Pix | Item 5:<br/> [Link Documentação](/documentation/pix/simulacao/index.html) | PIX0013 |
| PIX0018* | Aprovação e Reprovação de Solicitação de Portabilidade Out de uma Chave Pix | Realizar a aprovação de uma Solicitação de Portabilidade Out de uma Chave Pix | [Link Documentação](/documentation/pix/portabilidade#request-4) | PIX0017 |
| PIX0019* | Reenvio de 2fa de uma Solicitação de Portabilidade Out de uma Chave Pix | Solicitar reenvio de 2fa de uma Solicitação de Portabilidade Out de uma Chave Pix | Enum “pending_donator_validation”  <br/> [Link Documentação](/documentation/pix/portabilidade#request-4) | PIX0018 |
| PIX0020* | Leitura de webhook de conclusão de Solicitação de Portabilidade Out de Chave Pix | Ler corretamente o webhook de conclusão de uma Solicitação de Portabilidade Out de uma Chave Pix. Testando todos os possíveis status de conclusão (concluded, cancelled e failed) | [Link Documentação](D/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade-1) | PIX0018 |

## Gestão de QR Code Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0022* | Criação de QR Code Pix Estático | Gerar QR Code Estático | [Link Documentação](/documentation/pix/criar_qr_code_estatico) | PIX0008 |
| PIX0023 | Criação de QR Code Pix Dinâmico | Gerar QR Code Dinâmico com vencimento (dia de vencimento) e gerar QR Code Dinâmico Instantâneo (com segundos de expiração). | [Link Documentação](/documentation/pix/criar_qr_code_dinamico) | PIX0008 |
| PIX0024 | Exclusão de QR Code Pix Dinâmico | Excluir QR Code Pix | [Link Documentação](/documentation/pix/baixar_qr_code_dinamico) | PIX0023 |
| PIX0025 | Listar QR Codes Pix Dinâmicos | Listar QR Codes Pix Dinâmicos | [Link Documentação](/documentation/pix/pesquisar_por_qr_code_dinamico) | PIX0023 |
| PIX0026 | Leitura de webhook de expiração de QR Code Pix Dinâmico Instantâneo | Recepcionar com sucesso um webhook de expiração de QR Code Pix Dinâmico Instantâneo | [Link Documentação](/documentation/pix/webhook_por_qr_code_expirado) | PIX0023 |

## Pagamento de QR Code Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |

| PIX0029* | Pagamento de QR Code Pix Estático | Realizar o pagamento de um QR Code Pix Estático | [Link Documentação](/documentation/baas/pix/realizar_transferencia#transfer%C3%AAncia-por-qr-code-pix) | PIX0022 |
| PIX0030* | Pagamento de QR Code Pix Dinâmico | Realizar o pagamento de um QR Code Pix Dinâmico |  [Link Documentação](/documentation/baas/pix/realizar_transferencia#transfer%C3%AAncia-por-qr-code-pix) | PIX0022 |
| PIX0027* | Decodificação de QR Code Pix | Decodificar um QR Code Pix Estático, Dinâmico com vencimento e Dinâmico Instantâneo | [Link Documentação](/documentation/pix/decodificar_qr_code) | PIX0022 e PIX0023 |

## Gestão de Limite Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0032* | Solicitação de alteração de limite Pix | Realizar solicitação de alteração de limite Pix de uma QI Conte | [Link Documentação](/documentation/pix/solicitar_alteracao_de_limite_pix) |  QIC0003 ou QIC0005  |
| PIX0033 | Listagem de solicitações de alteração de limite Pix | Listar as solicitações de alteração de limite Pix para uma QI Conta | [Link Documentação](/documentation/pix/busca_por_solicitacao_de_limite_pix) | PIX0032 |
| PIX0034* | Consulta de limite Pix consumido | Consultar o limite Pix consumido para uma QI Conta | [Link Documentação](/documentation/pix/busca_por_uso_de_limite_pix) |  QIC0003 ou QIC0005  |

---

# Gestão de Tarifas
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GTF0001* | Solicitação de alteração de tarifas | Realizar a alteração de tarifas de uma conta| [Link Documentação](/documentation/contas/gestao_de_tarifas) |  QIC0003 ou QIC0005  |
| GTF0002* | Consulta de tarifas  | Consultar tarifas cadastradas em uma conta | [Link Documentação](/documentation/contas/consulta_de_tarifas) |  QIC0003 ou QIC0005  |

# Gestão de Cartoẽs

## Criação de Cartão
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GDC0001* | Criação de Cartão virtual  | Realizar a criação de um cartão virtual| [Link Documentação](/documentation/cards/create/gerar_cartao_virtual) |  QIC0003 ou QIC0005  |
| GDC0002* | Criação de Cartão físico  | Realizar a criação de um cartão físico| [Link Documentação](/documentation/cards/create/gerar_cartao_fisico) |  QIC0003 ou QIC0005  |

## Consulta de Cartões
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GDC0003* | Consulta cartão por chave  | Realizar a consulta de um cartão | [Link Documentação](/documentation/cards/search/buscar_cartao_by_key) | GDC0001 ou GDC0002 |
| GDC0004* | Listar cartões  | Realizar a listagem de cartões| [Link Documentação](/documentation/cards/search/listar_cartoes) | GDC0001 ou GDC0002 |
| GDC0005* | Buscar dados de um cartão | Buscar dados de um cartão| [Link Documentação](/documentation/cards/search/buscar_dados_pci) | GDC0001 ou GDC0002 |
| GDC0006* | Buscar Senha PCI | Buscar Senha PCI| [Link Documentação](/documentation/cards/search/buscar_senha) | GDC0001 ou GDC0002 |
| GDC0007* | Consultar dados da entrega | Consultar dados da entrega| [Link Documentação](/documentation/cards/search/buscar_entrega_by_key) | GDC0001 ou GDC0002 |

## Atualizar dados de um cartão
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GDC0008* | Atualizar status de um cartão  | Atualizar status de um cartão| [Link Documentação](/documentation/cards/status/update_status_cartao) | GDC0001 ou GDC0002 |
| GDC0009* | Ativar cartão físico  | Realizar a ativação de um cartão físico| [Link Documentação](/documentation/cards/status/ativar_cartao) | GDC0001 ou GDC0002 |
| GDC0010* | Alterar Senha   | Realizar a alteração de senha de um cartão | [Link Documentação](/documentation/cards/update/password_cartao) | GDC0001 ou GDC0002 |
| GDC0011* | Configurar contactless de um cartão  | Configurar contactless de um cartão  | [Link Documentação](/documentation/cards/update/contactless_cartao) | GDC0002 |

---

# Roteiro de Homologação - BaaS Cobrança

URL: /documentation/roteiros_de_homologacao/roteiro_cobranca

O roteiro de homolgação descreve todos os recursos e funcionalidades que precisam
ser testados pelo parceiro integrador no ambiente de sandbox da QI Tech (ambiente de testes), 
antes da entrada em ambiente de produção do produto.

Este roteiro descreve todos os recursos e funcionalidades envolvidos no produto.

:::info ATENÇÃO
As etapas sinalizadas com * são obrigatórias para a entrada em produção
:::

:::info ATENÇÃO
⚠️ **Todos os testes devem ser obrigatoriamente realizados no ambiente de Sandbox da QI Tech (ambiente de testes).
As movimentações realizadas em ambiente de Sandbox são movimentações financeiras fictícias, servindo apenas para teste de funcionalidade das APIs.**
:::

## Cadastro e Autenticação API BaaS
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| CAB0001* | Cadastro no ambiente de Sandbox | Realizar o cadastro na plataforma da QI Tech no ambiente de Sandbox (sandbox.qitech.app) | cs@qitech.com.br |
| CAB0002* | Validação de token em Sandbox | Realizar a validação do QI Token em Sandbox | [Download Manual de Inclusão do Token](https://docs.qitech.com.br/assets/pdfs/QI%20Tech%20Manual%20Inclus%C3%A3o%20de%20Token.pdf) | CAB0001 |
| CAB0003* | Troca de chaves públicas | Realizar a troca de chaves públicas dentro da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Link Documentação](/documentation/primeiros_passos/troca_de_chaves) | CAB0001 e CAB0002 |
| CAB0004* | Teste de autenticação de chamadas | Finalizar teste de autenticação de chamadas | [Passo a Passo](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2) <br/><br/> [Link Documentação](/documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste) | CAB0003 |
| CAB0005* | Configuração de webhooks | Realizar a configuração da url para envio dos webhooks por parte da QI, através da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Link Documentação](/documentation/primeiros_passos/configurando_webhooks) | CAB0001 e CAB0002 |

---

## QI Conta

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| QIC0001* | Consulta de dados de uma conta | Consultar dados como saldo, dados do titular, data de abertura, dentre outros | [Link Documentação](/documentation/contas/consultar_contas) | CAB0003  |

---

## Movimentações

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| QIC0008* | Consulta de Extrato | Realizar a consulta do extrato de uma conta | [Link Documentação](/documentation/movimentacao_de_contas/consulta_de_transacoes) |  CAB0003  |
| QIC0009* | Solicitação de comprovante de transferência | Solicitar um comprovante de transferência | [Link Documentação](/documentation/movimentacao_de_contas/consulta_de_transacoes)| CAB0003 |
| QIC0010* | Leitura de webhooks de transação | Recepcionar com sucesso todos os webhooks de transação |  [Link Documentação](/documentation/movimentacao_de_contas/comprovante_de_transferencia) |  CAB0003  |
| QIC0011* | Consulta de lista de instituições financeiras | Consultar lista de instituições financeiras habiliatadas para recebimento de TED e Pix |  [Link Documentação](/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras) |  CAB0003  |

---

## Boletos

### Gestão de Chave Pix
#### Criação e Exclusão de Chave pix
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0001* | Criação de chave Pix | Realizar a criação de chave Pix do tipo cpf, cnpj, aleatória, e-mail e telefone | [Link Documentação](/documentation/pix/criar_chave) | 
| PIX0010* | Listagem de chaves Pix de uma QI Conta | Listar chaves Pix vinculadas a uma QI Conta | [Link Documentação](/documentation/pix/listar_chaves_pix) | PIX0001 |

### Gestão da Carteira
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| CRT0001* | Criação de carteira | Realizar a criação de carteira para configurações específicas de pagamento, baixa, protesto, etc.  | [Link Documentação](/documentation/boletos/carteira/criar_carteira) | 
| CRT0002* | Editar carteira | Realizar a edição das configurações padrão.  | [Link Documentação](/documentation/boletos/carteira/editar_carteira) |  CRT0002  |

### Gestão de Boletos
| Nº      | Etapa | Descrição | Link  | Pré-requisito |
|---|---|---|---|---|
| BOL0001 | Registro de boleto único de cobrança (padrão)    | Realizar o registro de um boleto de cobrança | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao/index.html) | CAB0002 ou CAB0003   |
| BOL0002 | Registro de boleto único de cobrança (instantânea) | Realizar o registro de um boleto de cobrança | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) | CAB0002 ou CAB0003   |
| BOL0003 | Registro de boleto em lote  | Realizar o registro de boleto de cobrança em lote | [Link Documentação](/documentation/boletos/v2/emissao/emissao_em_lote) | CAB0002 ou CAB0003   |
| BOL0004 | Realizar abatimento no valor de um boleto | Realizar abatimento no valor de um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/abatimento/criar_abatimento) | BOL0001, BOL0002 ou BOL0003 |
| BOL0005 | Cancelar Abatimento     | Cancelar abatimento em um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/abatimento/cancelar_abatimento) | BOL0001, BOL0002 ou BOL0003  |
| BOL0006 | Estender vencimento de um boleto               | Enviar extensão de prazo de um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/extensao)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0007 | Incluir desconto em um boleto               | Incluir desconto em um boleto    | [Link Documentação](/documentation/boletos/v2/instrucoes/desconto)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0008 | Incluir juros em um boleto                   | Incluir juros em um boleto       | [Link Documentação](/documentation/boletos/v2/instrucoes/juros)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0009 | Incluir multa em um boleto                   | Incluir multa em um boleto       | [Link Documentação](/documentation/boletos/v2/instrucoes/multa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0010 | Realizar baixa de um boleto                   | Baixar um boleto                 | [Link Documentação](/documentation/boletos/v2/instrucoes/baixa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0011 | Consultar boletos por chave      | Consultar boletos por chave      | [Link Documentação](/documentation/boletos/v2/consulta/consulta_por_chave) | BOL0001, BOL0002 ou BOL0003   |
| BOL0012 | Listar Boletos          | Listar boletos     | [Link Documentação](/documentation/boletos/v2/consulta/listar_boletos) | BOL0001, BOL0002 ou BOL0003   |
| BOL0013 | Consulta de carteira de cobrança      | Consultar uma carteira de cobrança | [Link Documentação](/documentation/boletos/v2/carteira/listar_carteiras/index.html) | BOL0001, BOL0002 ou BOL0003   |
| BOL0014 | Webhooks de Boleto      | Realizar a leitura de webhook para boleto | [Link Documentação](/documentation/boletos/v2/webhooks/boleto) | BOL0001, BOL0002 ou BOL0003   |

### Conciliação de Boletos
| Nº      | Etapa | Descrição | Link  | Pré-requisito |
|---|---|---|---|---|
| CON0001 | Listar grupos de liquidação  | Realizar a listagem dos grupos de liquidação dos boletos liquidados | [Link Documentação](/documentation/boletos/liquidacao/listar_grupos_de_liquidacao) | BOL0001 ou BOL0002 ou BOL0003   |
| CON0002 | Listar liquidações | Realizar a listagem dos boletos dos grupos de liquidação | [Link Documentação](/documentation/boletos/liquidacao/listar_liquidacoes) | BOL0001 ou BOL0002 ou BOL0003   |

## Gestão de Tarifas
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GTF0001* | Solicitação de alteração de tarifas | Realizar a alteração de tarifas de uma conta| [Link Documentação](/documentation/contas/gestao_de_tarifas) |  
| GTF0002* | Consulta de tarifas  | Consultar tarifas cadastradas em uma conta | [Link Documentação](/documentation/contas/consulta_de_tarifas) |

---

# Roteiro de Homologação - BaaS Conta Digital com Dupla Autenticação

URL: /documentation/roteiros_de_homologacao/roteiro_conta_digital

O roteiro de homolgoação descreve todos os recursos e funcionalidades que precisam
ser testados pelo parceiro integrador no ambiente de sandbox da QI Tech (ambiente de testes), 
antes da entrada em ambiente de produção do produto.

Este roteiro descreve todos os recursos e funcionalidades envolvidos no produto. 

⚠️ **Todos os testes devem ser obrigatoriamente realizados no ambiente de Sandbox da QI Tech (ambiente de testes).
As movimentações realizadas em ambiente de Sandbox são movimentações financeiras fictícias, servindo apenas para teste de funcionalidade das APIs.**

## Cadastro e Autenticação API BaaS
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| CAB0001* | Cadastro no ambiente de Sandbox | Realizar o cadastro na plataforma da QI Tech no ambiente de Sandbox (sandbox.qitech.app) | cs@qitech.com.br |
| CAB0002* | Validação de token em Sandbox | Realizar a validação do QI Token em Sandbox | [Link Documentação](https://docs.qitech.com.br/assets/pdfs/QI%20Tech%20Manual%20Inclus%C3%A3o%20de%20Token.pdf) | CAB0001 |
| CAB0003* | Troca de chaves públicas | Realizar a troca de chaves públicas dentro da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Link Documentação](/documentation/primeiros_passos/troca_de_chaves) | CAB0001 e CAB0002 |
| CAB0004* | Teste de autenticação de chamadas | Finalizar teste de autenticação de chamadas |[Link Documentação](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2) <br/><br/> [Link Documentação](/documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste) | CAB0003 |
| CAB0005* | Configuração de webhooks | Realizar a configuração da url para envio dos webhooks por parte da QI, através da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Link Documentação](/documentation/primeiros_passos/configurando_webhooks) | CAB0001 e CAB0002 |

## Antifraude

## Cadastro e Autenticação

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| ATF0002* | Obtenção de API-key de onboarding | Obter junto ao time de integração da QI Tech a chave de API para uso da API de /onboarding | suporte.caas@qitech.com.br |  
| ATF0003* | Obtenção de mobile-token de OCR | Obter junto ao time de integração da QI Tech o Mobile Token  para uso do SDK de OCR | suporte.caas@qitech.com.br |  
| ATF0004* | Obtenção de mobile-token de Face Recognition | Obter junto ao time de integração da QI Tech o Mobile Token  para uso do SDK de Face Recognition | suporte.caas@qitech.com.br |  
| ATF0005* | Obtenção de mobile-token de Device scan | Obter junto ao time de integração da QI Tech o Mobile Token  para uso do SDK de Device scan | suporte.caas@qitech.com.br |  

## SDK OCR

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| ATF0007* | Build do SDK | Definir o template e customizações para coleta dos documentos e buildar o SDK com sucesso dentro da sua aplicação (aplicação do cliente QI Tech) | Android: [Link Documentação](/documentation/caas/ocr/android/introduction) <br/> iOS:[ Link Documentação](/documentation/caas/ocr/ios/introduction) |  |
| ATF0008* | Envio de documentos | Realizar a coleta de documentos utilizando o SDK dentro da sua aplicação (aplicação cliente QI Tech) |  | ATF0003 e ATF0007 |
| ATF0009* | Armazenamento de ocr_key | Armazenar as chaves retornadas pelo SDK, identificando a natureza do documento coletado (ex: cnh_front, cnh_back, etc) | Android: [Link Documentação](/documentation/caas/ocr/android/collecting_response) <br/>iOS:[ Link Documentação](/documentation/caas/ocr/ios/collecting_response)| ATF0008 |

## SDK Face Recognition

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| ATF0011* | Build do SDK | Definir customizações e buildar o SDK com sucesso dentro da sua aplicação (aplicação do cliente QI Tech) |Android: [Link Documentação](/documentation/caas/face_recognition/android/introduction) <br/>iOS:[ Link Documentação](/documentation/caas/face_recognition/ios/introduction)  |  |
| ATF0012* | Fluxo de prova de vida | Realizar o fluxo de prova de vida utilizando o SDK dentro da sua aplicação (aplicação cliente QI Tech) | | ATF0004 e ATF0011* |
| ATF0013* | Armazenamento de chave de imagem | Armazenar a image_key retornada pelo SDK após finalização do fluxo de prova de vida | Android: [Link Documentação](/documentation/caas/face_recognition/android/collecting_response) iOS:[ Link Documentação](/documentation/caas/face_recognition/ios/collecting_response) | ATF0012 |

## SDK Device Scan

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| ATF0015* | Build do SDK | Definição das permissões a serem solicitadas ao usuário por sua aplicação (aplicação do cliente QI Tech) e buildar o SDK com sucesso dentro da sua aplicação (aplicação do cliente QI Tech) | Android: [Link Documentação](/documentation/caas/device_scan/android/introduction)<br/>iOS:[ Link Documentação](/documentation/caas/device_scan/ios/introduction)|  
| ATF0016* | Armazenamento da sessão do usuário | Realizar o armazenamento da sessão do usuário (sessionId) que terá o dispositivo escaneado | Android: [Link Documentação](/documentation/caas/device_scan/android/example)<br/>iOS:[ Link Documentação](/documentation/caas/device_scan/ios/example) | ATF0015 e ATF0017 |
| ATF0017* | Coleta de informações | Instanciar o SDK com o sessionId armazenado e chamar o método de coleta de informações dentro de sua aplicação (aplicação do cliente QI Tech) | Android: [Link Documentação](/documentation/caas/face_recognition/android/collecting_response)<br/>iOS:[ Link Documentação](/documentation/caas/face_recognition/ios/collecting_response) | ATF0005 e ATF0015 |

## Antifraude

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| ATF0019* | Antifraude PF | Realizar com sucesso o antifraude de uma cliente pessoa física | [Link Documentação](/documentation/caas/onboarding/natural_person) | ATF0002 |
| ATF0020* | Antifraude PJ | Realizar com sucesso o antifraude de uma cliente pessoa jurídica | [Link Documentação](/documentation/caas/onboarding/legal_person) | ATF0002 |
| ATF0021* | Leitura de webhooks de analises derivadas para fluxo assíncrono | Recepcionar com sucesso o webhook de análise derivada para o fluxo de resposta assíncrona |[Link Documentação](/documentation/caas/onboarding/webhook) | ATF0019 ou ATF0020 |

## Cadastro Plataforma

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| ATF0022* | Cadastro de usuário Master | Realizar o cadastro de um usuário Master na plataforma do CaaS, para resolução de solicitações derivadas para “Análise manual”  | suporte.caas@qitech.com.br | ATF0019 ou ATF0020 |

---

# **QI Conta**

## Abertura de Conta

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| QIC0002* | Reserva de conta PF | Solicitar a reserva de uma conta cujo titular seja uma pessoa física | [Link Documentação](/documentation/baas/account/reservar_conta_pf) | CAB0005 e CAB0006 |
| QIC0003* | Abertura de conta PF | Realizar a abertura de uma conta cujo titular seja uma pessoa física | [Link Documentação](/documentation/baas/account/abrir_conta_pf) | QIC0002 |
| QIC0004* | Reserva de conta PJ | Solicitar a reserva de uma conta cujo titular seja uma pessoa jurídica | [Link Documentação](/documentation/baas/account/reservar_conta_pj) | CAB0005 e CAB0006 |
| QIC0005* | Abertura de conta PJ | Realizar a abertura de uma conta cujo titular seja uma pessoa jurídica | [Link Documentação](/documentation/baas/account/abrir_conta_pj) | QIC0004 |
| QIC0006* | Leitura de webhooks de abertura de conta | Ler corretamente os webhooks de abertura de conta | Item 1.2. ou 1.3:<br/>[Link Documentação](/documentation/baas/account/webhooks) |  QIC0003 ou QIC0005  |
| QIC0007* | Listar contas | Listar contas abertas| [Link Documentação](/documentation/contas/consultar_conta) |  QIC0003 ou QIC0005  |
| QIC0008* | Consulta de dados de uma conta | Consultar dados como saldo, dados do titular, data de abertura, dentre outros | [Link Documentação](/documentation/contas/consultar_conta) | QIC0003 ou QIC0005  |

## Movimentações

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| QIC0008* | Consulta de Extrato | Realizar a consulta do extrato de uma conta | [Link Documentação](/documentation/movimentacao_de_contas/consulta_de_transacoes) |  QIC0003 ou QIC0005  |
| QIC0009* | Solicitação de comprovante de transferência | Solicitar um comprovante de transferência | [Link Documentação](/documentation/movimentacao_de_contas/comprovante_de_transferencia)|  |
| QIC0010* | Leitura de webhooks de transação | Recepcionar com sucesso todos os webhooks de transação |  [Link Documentação](/documentation/movimentacao_de_contas/webhook_movimentacoes/index.html) |  QIC0003 ou QIC0005  |
| QIC0011* | Consulta de lista de instituições financeiras | Consultar lista de instituições financeiras habiliatadas para recebimento de TED e Pix |  [Link Documentação](/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras) |  QIC0003 ou QIC0005  |

---

# Upload de Documentos

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| UDD0001* | Upload de documento | Realizar o upload de um documento através da nossa API de documentos |  [Link Documentação](/documentation/upload_de_documentos/) |  |

---

# TED

| Código | Etapa | Descrição | Link                                                                                                        | Pré-requisito |
| --- | --- | --- |-------------------------------------------------------------------------------------------------------------| --- |
| TED0001* | Transferência TED Out | Realizar transferência TED  | 1 . Criar a solicitação de transferência: [Link Documentação](/documentation/baas/ted/realizar_transferencia_2fa) <br/>   2 . Aprovar a transferência: [Link Documentação](/documentation/baas/ted/realizar_transferencia_2fa) <br/>           | QIC0003 ou QIC0005 |
| TED0002* | Solicitar reenvio de token | Reenviar token de aprovação da transferência TED | [Link Documentação](/documentation/baas/ted/2fa/solicitacao_de_reenvio_de_token) | TED0001 |
| TED0003* | Simulação de estorno de uma TED Out | Simular o estorno de uma TED Out enviada a partira de uma QI Conta | Item 3: <br/>[Link Documentação](/documentation/movimentacao_de_contas/transacao) | TED0004 |
| TED0004* | Simulação de TED In | Simular a entrada de uma TED In em uma QI conta | Item 2: <br/>[Link Documentação](/documentation/movimentacao_de_contas/transacao) | QIC0003 ou QIC0005 |
| TED0005* | Listar transações TED| Listar transações TED de entrada/saída  | [Link Documentação](/documentation/baas/ted/listar_teds)  | QIC0003 ou QIC0005 |
| TED0006* | Consulta de transação  TED | Realizar a consulta de uma transação TED  | [Link Documentação](/documentation/baas/ted/consultar_ted)           | TED0001 ou TED0004  |
| TED0007* | Leitura de webhooks de TED | Recepcionar com sucesso um webhook de TED | [Link Documentação](/documentation/baas/ted/webhooks/index.html)| TED0001 ou TED0004 |
---

# Transferência Interna

| Nº | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| TFI0001 | Transferência Interna com débito em conta | Comandar uma transferência a partir de uma QI Conta, tendo como destino da transferência, outra QI Conta |  1 . Criar a solicitação de transferência: [Link Documentação](/documentation/baas/ted/realizar_transferencia_2fa) <br/>   2 . Aprovar a transferência: [Link Documentação](/documentation/baas/ted/realizar_transferencia_2fa) <br/> |  QIC0003 ou QIC0005  |
| TFI0002 | Simulação de transferência Interna com crédito em conta | Simular o recebimento de recursos na QI Conta alvo, tendo como origem, outra QI Conta | Item 1: <br/> [Link Documentação](/documentation/movimentacao_de_contas/transacao) |  QIC0003 ou QIC0005  |

---

# Boletos

## Gestão de Boletos

| Nº | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| Nº      | Etapa | Descrição | Link  | Pré-requisito |
|---|---|---|---|---|
| BOL0001 | Registro de boleto de um único boleto cobrança    | Realizar o registro de um boleto de cobrança | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao/index.html) | QIC0003 ou QIC0005   |
| BOL0002 | Registro de boleto de um único boleto de cobrança instantâneo | Realizar o registro de um boleto de cobrança | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) | QIC0003 ou QIC0005   |
| BOL0003 | Registro de boleto de boleto em lote  | Realizar o registro de boleto de cobrança em lote | [Link Documentação](/documentation/boletos/v2/emissao/emissao_em_lote) | QIC0003 ou QIC0005   |
| BOL0004 | Emissão de Boleto Único Padrão        | Emitir um boleto único padrão    | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao)  | QIC0003 ou QIC0005   |
| BOL0005 | Emissão de Boleto Único Instantâneo   | Emitir um boleto único instantân | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) | QIC0003 ou QIC0005   |
| BOL0006 | Emissão em Lote   | Emitir boletos em lote | [Link Documentação](/documentation/boletos/v2/emissao/emissao_em_lote)| QIC0003 ou QIC0005   |
| BOL0007 | Realizar abatimento no valor de um boleto | Realizar abatimento no valor de um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/abatimento/criar_abatimento) | BOL0001, BOL0002 ou BOL0003 |
| BOL0008 | Cancelar Abatimento     | Cancelar abatimento em um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/abatimento/cancelar_abatimento) | BOL0001, BOL0002 ou BOL0003  |
| BOL0009 | Estender vencimento de um boleto               | Enviar extensão de prazo de um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/extensao)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0010 | Incluir desconto em um boleto               | Incluir desconto em um boleto    | [Link Documentação](/documentation/boletos/v2/instrucoes/desconto)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0011 | Incluir juros em um boleto                   | Incluir juros em um boleto       | [Link Documentação](/documentation/boletos/v2/instrucoes/juros)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0012 | Incluir multa em um boleto                   | Incluir multa em um boleto       | [Link Documentação](/documentation/boletos/v2/instrucoes/multa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0013 | Realizar baixa de um boleto                   | Baixar um boleto                 | [Link Documentação](/documentation/boletos/v2/instrucoes/baixa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0014 | Consultar boletos por chave      | Consultar boletos por chave      | [Link Documentação](/documentation/boletos/v2/consulta/consulta_por_chave) | BOL0001, BOL0002 ou BOL0003   |
| BOL0015 | Listar Boletos          | Listar boletos     | [Link Documentação](/documentation/boletos/v2/consulta/listar_boletos) | BOL0001, BOL0002 ou BOL0003   |
| BOL0016 | Consulta de carteira de cobrança      | Consultar uma carteira de cobrança | [Link Documentação](/documentation/boletos/v2/carteira/listar_carteiras/index.html) | BOL0001, BOL0002 ou BOL0003   |
| BOL0017 | Webhooks de Boleto      | Realizar a leitura de webhook para boleto | [Link Documentação](/documentation/boletos/v2/webhooks/boleto) | BOL0001, BOL0002 ou BOL0003   |

## Pagamento de Boletos

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| BOL0009* | Consulta de linha digitável ou Código de Barras | Realizar a consulta de uma linha digitável de um boleto bancário | [Link Documentação](/documentation/baas/cobranca/consultar_boleto_bancario) |  |
| BOL0010* | Solicitar Token para pagamento de um boleto | Solicitar o token o pagamento de um boleto bancário | [Link Documentação](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_boleto_bancario) |  QIC0003 ou QIC0005  |
| BOL0011* | Aprovar o pagamento de um boleto | Solicitar o token o pagamento de um boleto bancário  | [Link Documentação](/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_boleto_bancario) |  QIC0003 ou QIC0005  |
| BOL0012* | Consulta de linha digitável ou Código de Barras de um boleto de convênio | Realizar a consulta de uma linha digitável de um  boleto convênio. | [Link Documentação](/documentation/baas/cobranca/consultar_fatura_de_recolhimento) |  |
| BOL0013* | Solicitar Token para pagamento de um boleto de convênio | Solicitar o token o pagamento de um boleto convênio | [Link Documentação](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_fatura_de_recolhimento) |  QIC0003 ou QIC0005  |
| BOL0014* | Aprovar o pagamento de um boleto de convênio| Solicitar o token o pagamento de um boleto de convênio  | [Link Documentação](/documentation/baas/cobranca/2fa_v2/confirmacao_de_pagamento_de_fatura_de_recolhimento) |  QIC0003 ou QIC0005  |

---

## Pix

## Transferência Pix 
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
|---------|--|---|---|---|
| PIX0002* | Transferência Pix Out | Realizar uma transferência Pix a partir de uma QI Conta utilizando dados bancários (pix manual) ou chave Pix | [1. Solicitar transferência](/documentation/baas/pix/2fa_v2/solicitacao_de_transacao_pix_2fa) <br></br> [2. Aprovar transferência](/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa) | CAB0001 |
| PIX0035 | Consulta de transferência pix | Recuperar os dados de uma transferência | [Link Documentação](/documentation/baas/pix/consultar_transferencias) | PIX0002 |
| PIX0003* | Simulação de reembolso de Pix Out | Simular o reembolso de um Pix Out. | [Link Documentação - Item 2](/documentation/pix/simulacao)| PIX0002 |
| PIX0004* | Simulação de Pix In | Simular o crédito de um Pix In em uma QI Conta. | [Link Documentação -> Item 1](/documentation/pix/simulacao)||
| PIX0037* | Leitura de webhook de transação pendente | Recepcionar com sucesso um webhook de transação pendente | [Link Documentação][(/documentation/baas/pix/webhooks) | PIX0002 |
| PIX0038* | Leitura de webhook de Pix de In | Recepcionar com sucesso um webhook de transferência Pix de entrada | [Link Documentação](/documentation/baas/pix/webhooks#webhook-para-pix-de-entrada)| PIX0004 |
| PIX0039 | Leitura de webhook de Devolução Pix | Recepcionar com sucesso um webhook de devolução de um Pix | [Link Documentação](/documentation/baas/pix/webhooks#webhook-para-devolu%C3%A7%C3%B5es-de-pix) | PIX0003 |
| PIX0040 | Solicitar a devolução de um Pix recebido | Solicitar a devolução de um Pix recebido | [1. Solicitar devolução](/documentation/baas/pix/2fa_v2/solicitacao_de_devolucao_pix) <br></br> [2. Aprovar devolução](/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa) | PIX0003 |
| PIX0041 | Listar transferências Pix de uma conta | Listar transferências Pix de uma conta | [Link Documentação](/documentation/baas/pix/listar_transferencias) | PIX0003 |

## Gestão de Chave Pix

### Criação e Exclusão de Chave pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0008* | Criação de chave Pix | Realizar a criação de chave Pix do tipo cpf, cnpj, aleatória, e-mail e telefone | [Link Documentação](/documentation/pix/criar_chave) | 
|QIC0003 ou QIC0005  |](/documentation/baas/pix/consultar_chave_pix)
| PIX0009 | Exclusão de chave Pix | Realizar a exclusão de uma chave Pix | [Link Documentação](/documentation/pix/excluir_chave) | PIX0008 |
| PIX0010* | Listagem de chaves Pix de uma QI Conta | Listar chaves Pix vinculadas a uma QI Conta | [Link Documentação](/documentation/pix/listar_chaves_pix) | PIX0008 |

### Portabilidade de Chave Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0013* | Criação de Solicitação de Portabilidade In de uma Chave Pix | Criar um pedido de Portabilidade In de uma Chave Pix do tipo CPF, CNPJ, E-mail, Telefone e Aleatória | [Link Documentação](/documentation/pix/portabilidade#criando-um-pedido-de-portabilidade) |  QIC0003 ou QIC0005  |
| PIX0014* | Reenvio de 2fa de uma Solicitação de Portabilidade In de uma Chave Pix do tipo E-mail ou Telefone | Solicitar o reenvio do SMS (Chave Pix do tipo Telefone) ou E-mail (Chave Pix do tipo E-mail) de uma Solicitação de Portabilidade In de uma Chave Pix pendente (pending_claimer_validation) | [Link Documentação](/documentation/pix/portabilidade#reenviando-a-valida%C3%A7%C3%A3o-de-dois-fatores) | PIX0013 |
| PIX0015* | Exclusão de Solicitação de Portabilidade In de uma Chave Pix | Excluir uma Solicitação de Portabilidade In de uma Chave Pix pendente | [Link Documentação](/documentation/pix/portabilidade#deletando-um-pedido-de-portabilidade) | PIX0013 |
| PIX0016* | Leitura de webhook de conclusão de Solicitação de Portabilidade In de Chave Pix | Ler corretamente o webhook de conclusão de uma Solicitação de Portabilidade In de uma Chave Pix. Testando todos os possíveis status de conclusão (concluded, cancelled e failed) | Webhook: <br/> [Link Documentação](/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade) |PIX0013 |
| PIX0017* | Simulação de Solicitação de Portabilidade Out de uma Chave Pix | Simular a chegada de uma solicitação de Solicitação de Portabilidade Out de uma Chave Pix | Item 5:<br/> [Link Documentação](/documentation/pix/simulacao/index.html) | PIX0013 |
| PIX0018* | Aprovação e Reprovação de Solicitação de Portabilidade Out de uma Chave Pix | Realizar a aprovação de uma Solicitação de Portabilidade Out de uma Chave Pix | [Link Documentação](/documentation/pix/portabilidade#request-4) | PIX0017 |
| PIX0019* | Reenvio de 2fa de uma Solicitação de Portabilidade Out de uma Chave Pix | Solicitar reenvio de 2fa de uma Solicitação de Portabilidade Out de uma Chave Pix | Enum “pending_donator_validation”  <br/> [Link Documentação](/documentation/pix/portabilidade#request-4) | PIX0018 |
| PIX0020* | Leitura de webhook de conclusão de Solicitação de Portabilidade Out de Chave Pix | Ler corretamente o webhook de conclusão de uma Solicitação de Portabilidade Out de uma Chave Pix. Testando todos os possíveis status de conclusão (concluded, cancelled e failed) | [Link Documentação](D/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade-1) | PIX0018 |

## Gestão de QR Code Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0022* | Criação de QR Code Pix Estático | Gerar QR Code Estático | [Link Documentação](/documentation/pix/criar_qr_code_estatico) | PIX0008 |
| PIX0023 | Criação de QR Code Pix Dinâmico | Gerar QR Code Dinâmico com vencimento (dia de vencimento) e gerar QR Code Dinâmico Instantâneo (com segundos de expiração). | [Link Documentação](/documentation/pix/criar_qr_code_dinamico) | PIX0008 |
| PIX0024 | Exclusão de QR Code Pix Dinâmico | Excluir QR Code Pix | [Link Documentação](/documentation/pix/baixar_qr_code_dinamico) | PIX0023 |
| PIX0025 | Listar QR Codes Pix Dinâmicos | Listar QR Codes Pix Dinâmicos | [Link Documentação](/documentation/pix/pesquisar_por_qr_code_dinamico) | PIX0023 |
| PIX0026 | Leitura de webhook de expiração de QR Code Pix Dinâmico Instantâneo | Recepcionar com sucesso um webhook de expiração de QR Code Pix Dinâmico Instantâneo | [Link Documentação](/documentation/pix/webhook_por_qr_code_expirado) | PIX0023 |

## Pagamento de QR Code Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0029* | Pagamento de QR Code Pix Estático | Realizar o pagamento de um QR Code Pix Estático | [1. Solicitar transferência](/documentation/baas/pix/2fa_v2/solicitacao_de_transacao_pix_2fa) <br></br> [2. Aprovar transferência](/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa) | PIX0022 |
| PIX0030* | Pagamento de QR Code Pix Dinâmico | Realizar o pagamento de um QR Code Pix Dinâmico |  [1. Solicitar transferência](/documentation/baas/pix/2fa_v2/solicitacao_de_transacao_pix_2fa) <br></br> [2. Aprovar transferência](/documentation/baas/pix/2fa_v2/aprovar_transacao_pix_2fa) | PIX0022 |
| PIX0027* | Decodificação de QR Code Pix | Decodificar um QR Code Pix Estático, Dinâmico com vencimento e Dinâmico Instantâneo | [Link Documentação](/documentation/pix/decodificar_qr_code) | PIX0022 e PIX0023 |

## Gestão de Limite Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0032* | Solicitação de alteração de limite Pix | Realizar solicitação de alteração de limite Pix de uma QI Conte | [Link Documentação](/documentation/pix/solicitar_alteracao_de_limite_pix) |  QIC0003 ou QIC0005  |
| PIX0033 | Listagem de solicitações de alteração de limite Pix | Listar as solicitações de alteração de limite Pix para uma QI Conta | [Link Documentação](/documentation/pix/busca_por_solicitacao_de_limite_pix) | PIX0032 |
| PIX0034* | Consulta de limite Pix consumido | Consultar o limite Pix consumido para uma QI Conta | [Link Documentação](/documentation/pix/busca_por_uso_de_limite_pix) |  QIC0003 ou QIC0005  |

---

# Gestão de Tarifas
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GTF0001* | Solicitação de alteração de tarifas | Realizar a alteração de tarifas de uma conta| [Link Documentação](/documentation/contas/gestao_de_tarifas) |  QIC0003 ou QIC0005  |
| GTF0002* | Consulta de tarifas  | Consultar tarifas cadastradas em uma conta | [Link Documentação](/documentation/contas/consulta_de_tarifas) |  QIC0003 ou QIC0005  |

## Gestão de Usuários Administradores
| GUA0001* | Inclusão de usuário administrador | Realizar a criação e vinculo de um usuário administrador a uma QI Conta. | Intro: [Documentação](/documentation/gestao_de_usuarios/tfa_introducao)<br/>1. Criação: [Documentação](/documentation/gestao_de_usuarios/criacao_de_pessoa)<br/>2. Inclusão: [Documentação](/documentation/gestao_de_usuarios/inclusao_de_vinculo) | QIC0003 ou QIC0005 |
| GUA0002* | Alteração de dados de contato de um usuário administrador | Relizar a alteração dos dados para contato (E-mail e telefone) de um usuário administrador | [Link Documentação](/documentation/gestao_de_usuarios/alteracao_de_contato_de_vinculo) | QIC0003 ou QIC0005 |
| GUA0003* | Exclusão de usuário administrador | Realizar a exclusão de vínculo entre um usuário administrador e uma QI Conta | [Link Documentação](/documentation/gestao_de_usuarios/exclusao_de_vinculo) |  QIC0003 ou QIC0005 |

# Gestão de Cartoẽs

## Criação de Cartão
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GDC0001* | Criação de Cartão virtual  | Realizar a criação de um cartão virtual| [Link Documentação](/documentation/cards/create/gerar_cartao_virtual) |  QIC0003 ou QIC0005  |
| GDC0002* | Criação de Cartão físico  | Realizar a criação de um cartão físico| [Link Documentação](/documentation/cards/create/gerar_cartao_fisico) |  QIC0003 ou QIC0005  |

## Consulta de Cartões
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GDC0003* | Consulta cartão por chave  | Realizar a consulta de um cartão | [Link Documentação](/documentation/cards/search/buscar_cartao_by_key) | GDC0001 ou GDC0002 |
| GDC0004* | Listar cartões  | Realizar a listagem de cartões| [Link Documentação](/documentation/cards/search/listar_cartoes) | GDC0001 ou GDC0002 |
| GDC0005* | Buscar dados de um cartão | Buscar dados de um cartão| [Link Documentação](/documentation/cards/search/buscar_dados_pci) | GDC0001 ou GDC0002 |
| GDC0006* | Buscar Senha PCI | Buscar Senha PCI| [Link Documentação](/documentation/cards/search/buscar_senha) | GDC0001 ou GDC0002 |
| GDC0007* | Consultar dados da entrega | Consultar dados da entrega| [Link Documentação](/documentation/cards/search/buscar_entrega_by_key) | GDC0001 ou GDC0002 |

## Atualizar dados de um cartão
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GDC0008* | Atualizar status de um cartão  | Atualizar status de um cartão| [Link Documentação](/documentation/cards/status/update_status_cartao) | GDC0001 ou GDC0002 |
| GDC0009* | Ativar cartão físico  | Realizar a ativação de um cartão físico| [Link Documentação](/documentation/cards/status/ativar_cartao) | GDC0001 ou GDC0002 |
| GDC0010* | Alterar Senha   | Realizar a alteração de senha de um cartão | [Link Documentação](/documentation/cards/update/password_cartao) | GDC0001 ou GDC0002 |
| GDC0011* | Configurar contactless de um cartão  | Configurar contactless de um cartão  | [Link Documentação](/documentation/cards/update/contactless_cartao) | GDC0002 |

---

# Roteiro de Homologação - BaaS Conta Digital

URL: /documentation/roteiros_de_homologacao/roteiro_conta_digital_d795dc71-05b2-4476-bfbc-07ef247abd90

O roteiro de homolgoação descreve todos os recursos e funcionalidades que precisam
ser testados pelo parceiro integrador no ambiente de sandbox da QI Tech (ambiente de testes), 
antes da entrada em ambiente de produção do produto.

Este roteiro descreve todos os recursos e funcionalidades envolvidos no produto. 
:::info ATENÇÃO
As etapas sinalizadas com * são obrigatórias para a entrada em produção
:::

⚠️ **Todos os testes devem ser obrigatoriamente realizados no ambiente de Sandbox da QI Tech (ambiente de testes).
As movimentações realizadas em ambiente de Sandbox são movimentações financeiras fictícias, servindo apenas para teste de funcionalidade das APIs.**

## Cadastro e Autenticação API BaaS
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| CAB0001* | Cadastro no ambiente de Sandbox | Realizar o cadastro na plataforma da QI Tech no ambiente de Sandbox (sandbox.qitech.app) | cs@qitech.com.br |
| CAB0002* | Validação de token em Sandbox | Realizar a validação do QI Token em Sandbox | [Download Manual de Inclusão do Token](https://docs.qitech.com.br/assets/pdfs/QI%20Tech%20Manual%20Inclus%C3%A3o%20de%20Token.pdf) | CAB0001 |
| CAB0003* | Troca de chaves públicas | Realizar a troca de chaves públicas dentro da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Link Documentação](/documentation/primeiros_passos/troca_de_chaves) | CAB0001 e CAB0002 |
| CAB0004* | Teste de autenticação de chamadas | Finalizar teste de autenticação de chamadas | [Passo a Passo](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2) <br/><br/> [Link Documentação](/documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste) | CAB0003 |
| CAB0005* | Configuração de webhooks | Realizar a configuração da url para envio dos webhooks por parte da QI, através da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Link Documentação](/documentation/primeiros_passos/configurando_webhooks) | CAB0001 e CAB0002 |

## Antifraude

## Cadastro e Autenticação

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| ATF0002* | Obtenção de API-key de onboarding | Obter junto ao time de integração da QI Tech a chave de API para uso da API de /onboarding | suporte.caas@qitech.com.br |  
| ATF0003* | Obtenção de mobile-token de OCR | Obter junto ao time de integração da QI Tech o Mobile Token  para uso do SDK de OCR | suporte.caas@qitech.com.br |  
| ATF0004* | Obtenção de mobile-token de Face Recognition | Obter junto ao time de integração da QI Tech o Mobile Token  para uso do SDK de Face Recognition | suporte.caas@qitech.com.br |  
| ATF0005* | Obtenção de mobile-token de Device scan | Obter junto ao time de integração da QI Tech o Mobile Token  para uso do SDK de Device scan | suporte.caas@qitech.com.br |  

## SDK OCR

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| ATF0007* | Build do SDK | Definir o template e customizações para coleta dos documentos e buildar o SDK com sucesso dentro da sua aplicação (aplicação do cliente QI Tech) | Android: [Link Documentação](/documentation/caas/ocr/android/introduction) <br/> iOS:[ Link Documentação](/documentation/caas/ocr/ios/introduction) |  |
| ATF0008* | Envio de documentos | Realizar a coleta de documentos utilizando o SDK dentro da sua aplicação (aplicação cliente QI Tech) |  | ATF0003 e ATF0007 |
| ATF0009* | Armazenamento de ocr_key | Armazenar as chaves retornadas pelo SDK, identificando a natureza do documento coletado (ex: cnh_front, cnh_back, etc) | Android: [Link Documentação](/documentation/caas/ocr/android/collecting_response) <br/>iOS:[ Link Documentação](/documentation/caas/ocr/ios/collecting_response)| ATF0008 |

## SDK Face Recognition

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| ATF0011* | Build do SDK | Definir customizações e buildar o SDK com sucesso dentro da sua aplicação (aplicação do cliente QI Tech) |Android: [Link Documentação](/documentation/caas/face_recognition/android/introduction) <br/>iOS:[ Link Documentação](/documentation/caas/face_recognition/ios/introduction)  |  |
| ATF0012* | Fluxo de prova de vida | Realizar o fluxo de prova de vida utilizando o SDK dentro da sua aplicação (aplicação cliente QI Tech) | | ATF0004 e ATF0011* |
| ATF0013* | Armazenamento de chave de imagem | Armazenar a image_key retornada pelo SDK após finalização do fluxo de prova de vida | Android: [Link Documentação](/documentation/caas/face_recognition/android/collecting_response) iOS:[ Link Documentação](/documentation/caas/face_recognition/ios/collecting_response) | ATF0012 |

## SDK Device Scan

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| ATF0015* | Build do SDK | Definição das permissões a serem solicitadas ao usuário por sua aplicação (aplicação do cliente QI Tech) e buildar o SDK com sucesso dentro da sua aplicação (aplicação do cliente QI Tech) | Android: [Link Documentação](/documentation/caas/device_scan/android/introduction)<br/>iOS:[ Link Documentação](/documentation/caas/device_scan/ios/introduction)|  
| ATF0016* | Armazenamento da sessão do usuário | Realizar o armazenamento da sessão do usuário (sessionId) que terá o dispositivo escaneado | Android: [Link Documentação](/documentation/caas/device_scan/android/example)<br/>iOS:[ Link Documentação](/documentation/caas/device_scan/ios/example) | ATF0015 e ATF0017 |
| ATF0017* | Coleta de informações | Instanciar o SDK com o sessionId armazenado e chamar o método de coleta de informações dentro de sua aplicação (aplicação do cliente QI Tech) | Android: [Link Documentação](/documentation/caas/face_recognition/android/collecting_response)<br/>iOS:[ Link Documentação](/documentation/caas/face_recognition/ios/collecting_response) | ATF0005 e ATF0015 |

## Antifraude

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| ATF0019* | Antifraude PF | Realizar com sucesso o antifraude de uma cliente pessoa física | [Link Documentação](/documentation/caas/onboarding/natural_person) | ATF0002 |
| ATF0020* | Antifraude PJ | Realizar com sucesso o antifraude de uma cliente pessoa jurídica | [Link Documentação](/documentation/caas/onboarding/legal_person) | ATF0002 |
| ATF0021* | Leitura de webhooks de analises derivadas para fluxo assíncrono | Recepcionar com sucesso o webhook de análise derivada para o fluxo de resposta assíncrona |[Link Documentação](/documentation/caas/onboarding/webhook) | ATF0019 ou ATF0020 |

## Cadastro Plataforma

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| ATF0022* | Cadastro de usuário Master | Realizar o cadastro de um usuário Master na plataforma do CaaS, para resolução de solicitações derivadas para “Análise manual”  | suporte.caas@qitech.com.br | ATF0019 ou ATF0020 |

---

# **QI Conta**

## Abertura de Conta

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| QIC0002* | Abertura de conta PF | Realizar a abertura de uma conta cujo titular seja uma pessoa física | [Link Documentação](/documentation/baas/manual_baas#13-cria%C3%A7%C3%A3o-da-conta-pf) |  |
| QIC0002* | Abertura de conta PJ | Realizar a abertura de uma conta cujo titular seja uma pessoa jurídica | [Link Documentação](/documentation/baas/manual_baas#12-cria%C3%A7%C3%A3o-da-conta-pj) | CAB0005 e CAB0006 |
| QIC0004* | Leitura de webhooks de abertura de conta | Ler corretamente os webhooks de abertura de conta | Item 1.2. ou 1.3:<br/>[Link Documentação](/documentation/baas/manual_baas#12-cria%C3%A7%C3%A3o-da-conta-pj) |  QIC0002 ou QIC0002  |
| QIC0005* | Consulta de dados de uma conta | Consultar dados como saldo, dados do titular, data de abertura, dentre outros | [Link Documentação](/documentation/contas/consultar_contas) |  QIC0002 ou QIC0002  |

## Movimentações

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| QIC0008* | Consulta de Extrato | Realizar a consulta do extrato de uma conta | [Link Documentação](/documentation/movimentacao_de_contas/consulta_de_transacoes) |  QIC0002 ou QIC0002  |
| QIC0009* | Solicitação de comprovante de transferência | Solicitar um comprovante de transferência | [Link Documentação](/documentation/movimentacao_de_contas/consulta_de_transacoes)|  |
| QIC0010* | Leitura de webhooks de transação | Recepcionar com sucesso todos os webhooks de transação |  [Link Documentação](/documentation/movimentacao_de_contas/comprovante_de_transferencia) |  QIC0002 ou QIC0002  |
| QIC0011* | Consulta de lista de instituições financeiras | Consultar lista de instituições financeiras habiliatadas para recebimento de TED e Pix |  [Link Documentação](/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras) |  QIC0002 ou QIC0002  |

---

# Upload de Documentos

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| UDD0001* | Upload de documento | Realizar o upload de um documento através da nossa API de documentos |  [Link Documentação](/documentation/upload_de_documentos/) |  |

---

# TED

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| TED0001* | Transferência TED Out | Realizar transferência TED para outra instituição financeira | [Link Documentação](/documentation/baas/ted/realizar_transferencia) | QIC0002 ou QIC0002 |
| TED0002* | Simulação de estorno de uma TED Out | Simular o estorno de uma TED Out enviada a partira de uma QI Conta | Item 3: <br/>[Link Documentação](/documentation/movimentacao_de_contas/transacao) | TED0001 |
| TED0003* | Simulação de TED In | Simular a entrada de uma TED In em uma QI conta | Item 2: <br/>[Link Documentação](/documentation/movimentacao_de_contas/transacao) | QIC0002 ou QIC0002 |
| TED0004* | Consulta de transações TED| Listar transações TED  | [Link Documentação](/documentation/baas/ted/listar_transferencias) | QIC0002 ou QIC0002 |
| TED0004* | Consulta de transação  TED| Realizar a consulta de uma transação TED  | [Link Documentação](/documentation/baas/ted/consultar_transferencia) | QIC0002 ou QIC0002 |
| TED0006* | Leitura de webhooks de TED| Recepcionar com sucesso um webhook de TED | [Link Documentação](/documentation/baas/ted/webhooks) | QIC0002 ou QIC0002 |
---

# Transferência Interna

| Nº | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| TFI0001 | Transferência Interna com débito em conta | Comandar uma transferência a partir de uma QI Conta, tendo como destino da transferência, outra QI Conta | [Link Documentação](/documentation/baas/ted/realizar_transferencia) |  QIC0002 ou QIC0002  |
| TFI0002 | Simulação de transferência Interna com crédito em conta | Simular o recebimento de recursos na QI Conta alvo, tendo como origem, outra QI Conta | Item 1: <br/> [Link Documentação](/documentation/movimentacao_de_contas/transacao) |  QIC0002 ou QIC0002  |

---

# Boletos

## Gestão de Boletos

| Nº | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| BOL0002* | Registro de boleto de cobrança | Realizar o registro de um boleto de cobrança enviando uma ocorrência de registro | [Link Documentação](/documentation/boletos/emissao/emissao_via_json) |  QIC0002 ou QIC0002 , |
| BOL0003 | Consultar carteira de cobrança de boletos | Consultar as carteiras de cobrança disponíveis para registro de boletos | [Link Documentação](/documentation/boletos/consultar/consulta_de_carteira) |  QIC0002 ou QIC0002  |
| BOL0004* | Instrução de boleto de cobrança | Comandar uma instrução para um boleto registrado | [Link Documentação](/documentation/boletos/enviar_instrucao_de_boleto) | BOL0002 |
| BOL0005 | Simulação de liquidação de boleto | Simular a liquidação de um boleto | [Link Documentação](/documentation/boletos/pagamento/liquidacao) | BOL0002 |
| BOL0006* | Leitura de webhooks de boletos | Recepcionar com sucesso todos os webhooks relacionados às alterações de status de um boleto | [Link Documentação](/documentation/webhooks/boletos) | BOL0004 |
| BOL0007 | Registro de um bolepix | Realizar o registro de um bolepix | [Link Documentação](/documentation/boletos/emissao/emissao_de_um_bolepix) |  |

## Pagamento de Boletos

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| BOL0009* | Consulta de linha digitável | Realizar a consulta de uma linha digitável de um boleto bancário ou boleto convênio. | [Link Documentação](/documentation/boletos/pagamento/consulta_linha_digitavel) |  |
| BOL0010* | Pagamento de um boleto | Realizar o pagamento de um boleto bancário ou de boleto de convênio | [Link Documentação](/documentation/boletos/pagamento/realizar_pagamento) |  QIC0002 ou QIC0002  |
| BOL0011* | Consulta de linha digitável | Realizar a consulta de uma linha digitável de um  boleto convênio. | [Link Documentação](/documentation/boletos/pagamento/consulta_linha_digitavel) |  |
| BOL0013* | Pagamento de um boleto | Realizar o pagamento de um boleto de convênio | [Link Documentação](/documentation/boletos/pagamento/realizar_pagamento) |  QIC0002 ou QIC0002  |

---

## Pix

## Transferência Pix 
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
|---------|--|---|---|---|
| PIX0002* | Transferência Pix Out | Realizar uma transferência Pix a partir de uma QI Conta utilizando dados bancários (pix manual) ou chave Pix | [Link Documentação](/documentation/baas/pix/realizar_transferencia)| CAB0001 |
| PIX0035 | Consulta de transferência pix | Recuperar os dados de uma transferência | [Link Documentação](/documentation/baas/pix/consultar_transferencias) | PIX0002 |
| PIX0003* | Simulação de reembolso de Pix Out | Simular o reembolso de um Pix Out. | [Link Documentação - Item 2](/documentation/pix/simulacao)| PIX0002 |
| PIX0004* | Simulação de Pix In | Simular o crédito de um Pix In em uma QI Conta. | [Link Documentação -> Item 1](/documentation/pix/simulacao)||
| PIX0037* | Leitura de webhook de transação pendente | Recepcionar com sucesso um webhook de transação pendente | [Link Documentação][(/documentation/baas/pix/webhooks) | PIX0002 |
| PIX0038* | Leitura de webhook de Pix de In | Recepcionar com sucesso um webhook de transferência Pix de entrada | [Link Documentação](/documentation/baas/pix/webhooks)| PIX0004 |
| PIX0039 | Leitura de webhook de Devolução Pix | Recepcionar com sucesso um webhook de devolução de um Pix | [Link Documentação](/documentation/baas/pix/webhooks#webhook-para-devolu%C3%A7%C3%B5es-de-pix) | PIX0003 |

## Gestão de Chave Pix

### Criação e Exclusão de Chave pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0008* | Criação de chave Pix | Realizar a criação de chave Pix do tipo cpf, cnpj, aleatória, e-mail e telefone | Item 5.1. e 5.2:<br/>[Link Documentação](/documentation/baas/manual_baas#5---gerenciar-chaves-pix) |  QIC0002 ou QIC0002  |](/documentation/pix_v2/index.html#consulta-de-chave-pix-no-banco-central)
| PIX0009 | Exclusão de chave Pix | Realizar a exclusão de uma chave Pix | [Link Documentação](/documentation/pix/excluir_chave) | PIX0008 |
| PIX0010* | Listagem de chaves Pix de uma QI Conta | Listar chaves Pix vinculadas a uma QI Conta | [Link Documentação](/documentation/pix/listar_chaves_pix) | PIX0008 |
| PIX0011* | Leitura de webhook de ativação de chave Pix aleatória | Recepcionar com suacesso webhook de criação de chave aleatória | Item 5.1:  <br/> [Link Documentação](/documentation/baas/manual_baas#51-criar-chave-pix-cpf-cnpj-ou-aleat%C3%B3ria) | PIX0008 |

### Portabilidade de Chave Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0013* | Criação de Solicitação de Portabilidade In de uma Chave Pix | Criar um pedido de Portabilidade In de uma Chave Pix do tipo CPF, CNPJ, E-mail, Telefone e Aleatória | [Link Documentação](/documentation/pix/portabilidade#criando-um-pedido-de-portabilidade) |  QIC0002 ou QIC0002  |
| PIX0014* | Reenvio de 2fa de uma Solicitação de Portabilidade In de uma Chave Pix do tipo E-mail ou Telefone | Solicitar o reenvio do SMS (Chave Pix do tipo Telefone) ou E-mail (Chave Pix do tipo E-mail) de uma Solicitação de Portabilidade In de uma Chave Pix pendente (pending_claimer_validation) | [Link Documentação](/documentation/pix/portabilidade#reenviando-a-valida%C3%A7%C3%A3o-de-dois-fatores) | PIX0013 |
| PIX0015* | Exclusão de Solicitação de Portabilidade In de uma Chave Pix | Excluir uma Solicitação de Portabilidade In de uma Chave Pix pendente | [Link Documentação](/documentation/pix/portabilidade#deletando-um-pedido-de-portabilidade) | PIX0013 |
| PIX0016* | Leitura de webhook de conclusão de Solicitação de Portabilidade In de Chave Pix | Ler corretamente o webhook de conclusão de uma Solicitação de Portabilidade In de uma Chave Pix. Testando todos os possíveis status de conclusão (concluded, cancelled e failed) | Webhook: <br/> [Link Documentação](/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade) |PIX0013 |
| PIX0017* | Simulação de Solicitação de Portabilidade Out de uma Chave Pix | Simular a chegada de uma solicitação de Solicitação de Portabilidade Out de uma Chave Pix | Item 5:<br/> [Link Documentação](/documentation/pix/simulacao/index.html) | PIX0013 |
| PIX0018* | Aprovação e Reprovação de Solicitação de Portabilidade Out de uma Chave Pix | Realizar a aprovação de uma Solicitação de Portabilidade Out de uma Chave Pix | [Link Documentação](/documentation/pix/portabilidade#request-4) | PIX0017 |
| PIX0019* | Reenvio de 2fa de uma Solicitação de Portabilidade Out de uma Chave Pix | Solicitar reenvio de 2fa de uma Solicitação de Portabilidade Out de uma Chave Pix | Enum “pending_donator_validation”  <br/> [Link Documentação](/documentation/pix/portabilidade#request-4) | PIX0018 |
| PIX0020* | Leitura de webhook de conclusão de Solicitação de Portabilidade Out de Chave Pix | Ler corretamente o webhook de conclusão de uma Solicitação de Portabilidade Out de uma Chave Pix. Testando todos os possíveis status de conclusão (concluded, cancelled e failed) | [Link Documentação](D/documentation/pix/portabilidade#conclus%C3%A3o-da-portabilidade-1) | PIX0018 |

## Gestão de QR Code Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0022* | Criação de QR Code Pix Estático | Gerar QR Code Estático | [Link Documentação](/documentation/pix/criar_qr_code_estatico) | PIX0008 |
| PIX0023 | Criação de QR Code Pix Dinâmico | Gerar QR Code Dinâmico com vencimento (dia de vencimento) e gerar QR Code Dinâmico Instantâneo (com segundos de expiração). | [Link Documentação](/documentation/pix/criar_qr_code_dinamico) | PIX0008 |
| PIX0024 | Exclusão de QR Code Pix Dinâmico | Excluir QR Code Pix | [Link Documentação](/documentation/pix/baixar_qr_code_dinamico) | PIX0023 |
| PIX0025 | Listar QR Codes Pix Dinâmicos | Listar QR Codes Pix Dinâmicos | [Link Documentação](/documentation/pix/pesquisar_por_qr_code_dinamico) | PIX0023 |
| PIX0026 | Leitura de webhook de expiração de QR Code Pix Dinâmico Instantâneo | Recepcionar com sucesso um webhook de expiração de QR Code Pix Dinâmico Instantâneo | [Link Documentação](/documentation/pix/webhook_por_qr_code_expirado) | PIX0023 |
| PIX0027* | Decodificação de QR Code Pix | Decodificar um QR Code Pix Estático, Dinâmico com vencimento e Dinâmico Instantâneo | [Link Documentação](/documentation/pix/decodificar_qr_code) | PIX0022 e PIX0023 |

## Pagamento de QR Code Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0029* | Pagamento de QR Code Pix Estático | Realizar o pagamento de um QR Code Pix Estático | Item 4.1: [Link Documentação](/documentation/baas/manual_baas#41-pagando-um-qr-code-pix-est%C3%A1tico) | PIX0022 |
| PIX0030* | Pagamento de QR Code Pix Dinâmico | Realizar o pagamento de um QR Code Pix Dinâmico | Item 4.2: [Link Documentação](/documentation/baas/manual_baas#42-pagando-um-qr-code-pix-din%C3%A2mico) | PIX0022 |

## Gestão de Limite Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0032* | Solicitação de alteração de limite Pix | Realizar solicitação de alteração de limite Pix de uma QI Conte | [Link Documentação](/documentation/pix/solicitar_alteracao_de_limite_pix) |  QIC0002 ou QIC0002  |
| PIX0033 | Listagem de solicitações de alteração de limite Pix | Listar as solicitações de alteração de limite Pix para uma QI Conta | [Link Documentação](/documentation/pix/busca_por_solicitacao_de_limite_pix) | PIX0032 |
| PIX0034* | Consulta de limite Pix consumido | Consultar o limite Pix consumido para uma QI Conta | [Link Documentação](/documentation/pix/busca_por_uso_de_limite_pix) |  QIC0002 ou QIC0002  |

---

# Gestão de Tarifas
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GTF0001* | Solicitação de alteração de tarifas | Realizar a alteração de tarifas de uma conta| [Link Documentação](/documentation/contas/gestao_de_tarifas) |  QIC0002 ou QIC0002  |
| GTF0002* | Consulta de tarifas  | Consultar tarifas cadastradas em uma conta | [Link Documentação](/documentation/contas/consulta_de_tarifas) |  QIC0002 ou QIC0002  |

# Gestão de Cartoẽs

## Criação de Cartão
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GDC0001* | Criação de Cartão virtual  | Realizar a criação de um cartão virtual| [Link Documentação](/documentation/cards/create/gerar_cartao_virtual) |  QIC0002 ou QIC0002  |
| GDC0002* | Criação de Cartão físico  | Realizar a criação de um cartão físico| [Link Documentação](/documentation/cards/create/gerar_cartao_fisico) |  QIC0002 ou QIC0002  |

## Consulta de Cartões
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GDC0003* | Consulta cartão por chave  | Realizar a consulta de um cartão | [Link Documentação](/documentation/cards/search/buscar_cartao_by_key) | GDC0001 ou GDC0002 |
| GDC0004* | Listar cartões  | Realizar a listagem de cartões| [Link Documentação](/documentation/cards/search/listar_cartoes) | GDC0001 ou GDC0002 |
| GDC0005* | Buscar dados de um cartão | Buscar dados de um cartão| [Link Documentação](/documentation/cards/search/buscar_dados_pci) | GDC0001 ou GDC0002 |
| GDC0006* | Buscar Senha PCI | Buscar Senha PCI| [Link Documentação](/documentation/cards/search/buscar_senha) | GDC0001 ou GDC0002 |
| GDC0007* | Consultar dados da entrega | Consultar dados da entrega| [Link Documentação](/documentation/cards/search/buscar_entrega_by_key) | GDC0001 ou GDC0002 |

## Atualizar dados de um cartão
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GDC0008* | Atualizar status de um cartão  | Atualizar status de um cartão| [Link Documentação](/documentation/cards/status/update_status_cartao) | GDC0001 ou GDC0002 |
| GDC0009* | Ativar cartão físico  | Realizar a ativação de um cartão físico| [Link Documentação](/documentation/cards/status/ativar_cartao) | GDC0001 ou GDC0002 |
| GDC0010* | Alterar Senha   | Realizar a alteração de senha de um cartão | [Link Documentação](/documentation/cards/update/password_cartao) | GDC0001 ou GDC0002 |
| GDC0011* | Configurar contactless de um cartão  | Configurar contactless de um cartão  | [Link Documentação](/documentation/cards/update/contactless_cartao) | GDC0002 |

---

# Roteiro de Homologação - Conta Integrada

URL: /documentation/roteiros_de_homologacao/roteiro_conta_integrada

O roteiro de homolgoação descreve todos os recursos e funcionalidades que precisam
ser testados pelo parceiro integrador no ambiente de sandbox da QI Tech (ambiente de testes), 
antes da entrada em ambiente de produção do produto.

Este roteiro descreve todos os recursos e funcionalidades envolvidos no produto. 

`*: etapas obrigatórias para entrada em produção`

## Cadastro e Autenticação API BaaS
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
|---------|--|---|---|---|
| CAB0001* | Cadastro no ambiente de Sandbox | Realizar o cadastro na plataforma da QI Tech no ambiente de Sandbox (sandbox.qitech.app) | [Link documentação](/documentation/primeiros_passos/inicio) 
| CAB0002* | Validação de token em Sandbox | Realizar a validação do QI Token em Sandbox | [Manual de Inclusão do Token](https://docs.qitech.com.br/assets/pdfs/QI%20Tech%20Manual%20Inclus%C3%A3o%20de%20Token.pdf) | CAB0001 |
| CAB0003* | Troca de chaves públicas | Realizar a troca de chaves públicas dentro da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Troca de chaves](/documentation/primeiros_passos/troca_de_chaves) | CAB0001 e CAB0002 |
| CAB0004* | Teste de autenticação de chamadas | Finalizar teste de autenticação de chamadas | [Teste de Autenticação](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2) <br/><br/> [Endpoints de teste da autenticação](/documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste) | CAB0003 |
| CAB0005* | Configuração de webhooks | Realizar a configuração da url para envio dos webhooks por parte da QI, através da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Configuração de webhooks](/documentation/primeiros_passos/configurando_webhooks) | CAB0001 e CAB0002 |

## QI Conta
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
|---------|--|---|---|---|
| QIC0005 | Consulta de dados de uma conta | Recuperar os dados de uma QI Conta com sucesso | [Consultar Conta](/documentation/contas/consultar_conta) ||

## Transferência Pix 
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
|---------|--|---|---|---|
| PIX0002* | Transferência Pix Out | Realizar uma transferência Pix a partir de uma QI Conta utilizando dados bancários (pix manual) ou chave Pix | [Realização de Transação Pix](/documentation/baas/pix/realizar_transferencia)||
| PIX0035 | Consulta de transferência pix | Recuperar os dados de uma transferência | [Consulta de transferência Pix](/documentation/baas/pix/consultar_transferencias) | PIX0002 |
| PIX0003* | Simulação de reembolso de Pix Out | Simular o reembolso de um Pix Out. | [Simulação reembolso Pix Out -> Item 2](/documentation/pix/simulacao)| PIX0002 |
| PIX0004* | Simulação de Pix In | Simular o crédito de um Pix In em uma QI Conta. | [Simulação Pix In -> Item 1](/documentation/pix/simulacao)||
| PIX0005* | Reembolso de Pix In | Realizar o reembolso de um Pix In a partir de uma QI Conta. | [Reembolso Pix In](/documentation/baas/pix/solicitar_devolucao)| PIX0004 |
| PIX0037* | Leitura de webhook de transação pendente | Recepcionar com sucesso um webhook de transação pendente | [Webhook de transação pendente](/documentation/baas/pix/webhooks#webhook-para-transa%C3%A7%C3%B5es-pendentes) | PIX0002 |
| PIX0038* | Leitura de webhook de Pix de In | Recepcionar com sucesso um webhook de transferência Pix de entrada | [Webhook Pix In](/documentation/baas/pix/webhooks#webhook-para-pix-de-entrada) | PIX0004 |
| PIX0039 | Leitura de webhook de Devolução Pix | Recepcionar com sucesso um webhook de devolução de um Pix | [Webhook Devolução Pix](/documentation/baas/pix/webhooks#webhook-para-devolu%C3%A7%C3%B5es-de-pix) | PIX0003 |

## Movimentações
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
|---------|--|---|---|---|
| QIC0008* | Consulta de Transações | Realizar a consulta das transações de uma conta | [Consulta de Transações](/documentation/movimentacao_de_contas/consulta_de_transacoes) ||
| QIC0009 | Solicitação de comprovante de transferência | Solicitação de comprovante de transferência | [Solicitar comprovante de transferência](/documentation/movimentacao_de_contas/comprovante_de_transferencia) | PIX0002 |
| QIC0010* | Leitura de webhooks de transação | Recepcionar com sucesso todos os webhooks de transação | [Webhook account_transaction](/documentation/movimentacao_de_contas/webhook_movimentacoes) | CAB0005 e PIX0002 |
| QIC0011 | Consulta de lista de instituições financeiras | Consultar lista de instituições financeiras habiliatadas para recebimento de TED e Pix | [Consulta de Instituições Financeiras](/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras) ||

## Consulta de Chave Pix
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
|---------|--|---|---|---|
| PIX0008* | Criação de Chave Pix Aleatória | Criar uma chave pix aleatória | [Link Documentação](/documentation/pix/criar_chave#criar-chave-pix-cpf-cnpj-ou-aleat%C3%B3ria) | PIX008 |
| PIX0036* | Consulta de dados de uma chave Pix | Realizar com sucesso a consulta de uma chave Pix no Bacen. | [Consulta de chave Pix](/documentation/baas/pix/consultar_chave_pix) ||

## Gestão de QR Code Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0022* | Criação de QR Code Pix Estático | Gerar QR Code Estático | [Link Documentação](/documentation/pix/criar_qr_code_estatico) | PIX0008 |
| PIX0023 | Criação de QR Code Pix Dinâmico | Gerar QR Code Dinâmico com vencimento (dia de vencimento) e gerar QR Code Dinâmico Instantâneo (com segundos de expiração). | [Link Documentação](/documentation/pix/criar_qr_code_dinamico) | PIX0008 |
| PIX0024 | Exclusão de QR Code Pix Dinâmico | Excluir QR Code Pix | [Link Documentação](/documentation/pix/baixar_qr_code_dinamico) | PIX0023 |
| PIX0025 | Listar QR Codes Pix Dinâmicos | Listar QR Codes Pix Dinâmicos | [Link Documentação](/documentation/pix/pesquisar_por_qr_code_dinamico) | PIX0023 |
| PIX0026* | Leitura de webhook de expiração de QR Code Pix Dinâmico Instantâneo | Recepcionar com sucesso um webhook de expiração de QR Code Pix Dinâmico Instantâneo | [Link Documentação](/documentation/pix/webhook_por_qr_code_expirado) | PIX0023 |
| PIX0027* | Decodificação de QR Code Pix | Decodificar um QR Code Pix Estático, Dinâmico com vencimento e Dinâmico Instantâneo | [Link Documentação](/documentation/pix/decodificar_qr_code) | PIX0022 e PIX0023 |

## Decodificar QR Code Pix
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
|---------|--|---|---|---|
| PIX0027* | Decodificação de QR Code Pix | Consultar os dados de um QR Code Pix (decodificar) utilizando a url do pix copia e cola | [Decodificação de QR Code Pix](/documentation/pix/decodificar_qr_code)||

## Boletos

## Gestão de Boletos
| Nº      | Etapa | Descrição | Link  | Pré-requisito |
|---|---|---|---|---|
| BOL0001 | Registro de boleto de um único boleto cobrança    | Realizar o registro de um boleto de cobrança | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao/index.html) | CAB0002 ou CAB0003   |
| BOL0002 | Registro de boleto de um único boleto de cobrança instantâneo | Realizar o registro de um boleto de cobrança | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) | CAB0002 ou CAB0003   |
| BOL0003 | Registro de boleto de boleto em lote  | Realizar o registro de boleto de cobrança em lote | [Link Documentação](/documentation/boletos/v2/emissao/emissao_em_lote) | CAB0002 ou CAB0003   |
| BOL0004 | Emissão de Boleto Único Padrão        | Emitir um boleto único padrão    | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao)  | CAB0002 ou CAB0003   |
| BOL0005 | Emissão de Boleto Único Instantâneo   | Emitir um boleto único instantân | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) | CAB0002 ou CAB0003   |
| BOL0006 | Emissão em Lote   | Emitir boletos em lote | [Link Documentação](/documentation/boletos/v2/emissao/emissao_em_lote)| CAB0002 ou CAB0003   |
| BOL0007 | Realizar abatimento no valor de um boleto | Realizar abatimento no valor de um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/abatimento/criar_abatimento) | BOL0001, BOL0002 ou BOL0003 |
| BOL0008 | Cancelar Abatimento     | Cancelar abatimento em um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/abatimento/cancelar_abatimento) | BOL0001, BOL0002 ou BOL0003  |
| BOL0009 | Estender vencimento de um boleto               | Enviar extensão de prazo de um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/extensao)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0010 | Incluir desconto em um boleto               | Incluir desconto em um boleto    | [Link Documentação](/documentation/boletos/v2/instrucoes/desconto)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0011 | Incluir juros em um boleto                   | Incluir juros em um boleto       | [Link Documentação](/documentation/boletos/v2/instrucoes/juros)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0012 | Incluir multa em um boleto                   | Incluir multa em um boleto       | [Link Documentação](/documentation/boletos/v2/instrucoes/multa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0013 | Realizar baixa de um boleto                   | Baixar um boleto                 | [Link Documentação](/documentation/boletos/v2/instrucoes/baixa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0014 | Consultar boletos por chave      | Consultar boletos por chave      | [Link Documentação](/documentation/boletos/v2/consulta/consulta_por_chave) | BOL0001, BOL0002 ou BOL0003   |
| BOL0015 | Listar Boletos          | Listar boletos     | [Link Documentação](/documentation/boletos/v2/consulta/listar_boletos) | BOL0001, BOL0002 ou BOL0003   |
| BOL0016 | Webhooks de Boleto      | Realizar a leitura de webhook para boleto | [Link Documentação](/documentation/boletos/v2/webhooks/boleto) | BOL0001, BOL0002 ou BOL0003   |

---

# Roteiro para construção do Backoffice

URL: /documentation/roteiros_de_homologacao/roteiro_criacao_backoffice_cliente

# **QI Conta**

### Conta

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| QIC0001 | Listar contas | Listar contas abertas| [Link Documentação](/documentation/contas/consultar_conta) |  QIC0003 ou QIC0005  |
| QIC0002 | Consulta de dados de uma conta | Consultar dados como saldo, dados do titular, data de abertura, dentre outros | [Link Documentação](/documentation/contas/consultar_conta) |  QIC0003 ou QIC0005  |
| QIC0003 | Limite Pix | Busca por solicitação de Limite Pix | [Link Documentação](/documentation/pix/busca_por_solicitacao_de_limite_pix)
| QIC0004 | Encerramento de conta | Encerramento de uma conta específica | [Link Documentação](/documentation/contas/encerramento_de_conta)

### Movimentações

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| QIC0005 | Consulta de Extrato | Realizar a consulta do extrato de uma conta | [Link Documentação](/documentation/movimentacao_de_contas/consulta_de_transacoes) |  QIC0003 ou QIC0005  |
| QIC0006 | Solicitação de comprovante de transferência | Solicitar um comprovante de transferência | [Link Documentação](/documentation/movimentacao_de_contas/comprovante_de_transferencia)|  |
| QIC0007 | Informe de rendimentos | Informe de rendimentos de uma conta específica | [Link Documentação](/documentation/contas/informe_rendimentos)
| QIC0008 | Listar Transferências TEDs | Verificar transações TEDs de uma conta específica | [Link Documentação](/documentation/baas/ted/listar_teds) | 
| QIC0009 | Listar Transferências Pix | Verificar transações PIX de uma conta específica | [Link Documentação](/documentation/baas/pix/listar_transferencias)

## Gestão de Tarifas
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GTF0001* | Solicitação de alteração de tarifas | Realizar a alteração de tarifas de uma conta| [Link Documentação](/documentation/contas/gestao_de_tarifas) |  QIC0003 ou QIC0005  |
| GTF0002* | Consulta de tarifas  | Consultar tarifas cadastradas em uma conta | [Link Documentação](/documentation/contas/consulta_de_tarifas) |  QIC0003 ou QIC0005  |

## Boleto

| Nº      | Etapa | Descrição | Link  | Pré-requisito |
|---|---|---|---|---|
| BOL0004 | Emissão de Boleto Único Padrão        | Emitir um boleto único padrão    | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao)  | CAB0002 ou CAB0003   |
| BOL0007 | Realizar abatimento no valor de um boleto | Realizar abatimento no valor de um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/abatimento/criar_abatimento) | BOL0001, BOL0002 ou BOL0003 |
| BOL0008 | Cancelar Abatimento     | Cancelar abatimento em um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/abatimento/cancelar_abatimento) | BOL0001, BOL0002 ou BOL0003  |
| BOL0009 | Estender vencimento de um boleto               | Enviar extensão de prazo de um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/extensao)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0010 | Incluir desconto em um boleto               | Incluir desconto em um boleto    | [Link Documentação](/documentation/boletos/v2/instrucoes/desconto)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0011 | Incluir juros em um boleto                   | Incluir juros em um boleto       | [Link Documentação](/documentation/boletos/v2/instrucoes/juros)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0012 | Incluir multa em um boleto                   | Incluir multa em um boleto       | [Link Documentação](/documentation/boletos/v2/instrucoes/multa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0013 | Realizar baixa de um boleto                   | Baixar um boleto                 | [Link Documentação](/documentation/boletos/v2/instrucoes/baixa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0014 | Consultar boletos por chave      | Consultar boletos por chave      | [Link Documentação](/documentation/boletos/v2/consulta/consulta_por_chave) | BOL0001, BOL0002 ou BOL0003   |
| BOL0015 | Listar Boletos          | Listar boletos     | [Link Documentação](/documentation/boletos/v2/consulta/listar_boletos) | BOL0001, BOL0002 ou BOL0003   |
| BOL0016 | Consulta de carteira de cobrança      | Consultar uma carteira de cobrança | [Link Documentação](/documentation/boletos/v2/carteira/listar_carteiras/index.html) | BOL0001, BOL0002 ou BOL0003   |
| BOL0017 | Solicitar 2ª via de boleto | Gerar o pdf com a segunda via de boleto | [Link Documentação](/documentation/boletos/consultar_v1/segunda_via_de_boleto)
| BOL0018 | Listar liquidações | A listagem de liquidações retornará todas as liquidações do grupo de liquidação enviado na request | [Link Documentação](/documentation/boletos/liquidacao/listar_liquidacoes)

---

# Roteiro de Homologação - BaaS Conta Payments

URL: /documentation/roteiros_de_homologacao/roteiro_payments

O roteiro de homolgoação descreve todos os recursos e funcionalidades que precisam
ser testados pelo parceiro integrador no ambiente de sandbox da QI Tech (ambiente de testes), 
antes da entrada em ambiente de produção do produto.

Este roteiro descreve todos os recursos e funcionalidades envolvidos no produto. 

⚠️ **Todos os testes devem ser obrigatoriamente realizados no ambiente de Sandbox da QI Tech (ambiente de testes).
As movimentações realizadas em ambiente de Sandbox são movimentações financeiras fictícias, servindo apenas para teste de funcionalidade das APIs.**

## Cadastro e Autenticação API BaaS
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| CAB0001* | Cadastro no ambiente de Sandbox | Realizar o cadastro na plataforma da QI Tech no ambiente de Sandbox (sandbox.qitech.app) | cs@qitech.com.br |
| CAB0002* | Validação de token em Sandbox | Realizar a validação do QI Token em Sandbox | [Link Documentação](https://docs.qitech.com.br/assets/pdfs/QI%20Tech%20Manual%20Inclus%C3%A3o%20de%20Token.pdf) | CAB0001 |
| CAB0003* | Troca de chaves públicas | Realizar a troca de chaves públicas dentro da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Link Documentação](/documentation/primeiros_passos/troca_de_chaves) | CAB0001 e CAB0002 |
| CAB0004* | Teste de autenticação de chamadas | Finalizar teste de autenticação de chamadas |[Link Documentação](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2) <br/><br/> [Link Documentação](/documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste) | CAB0003 |
| CAB0005* | Configuração de webhooks | Realizar a configuração da url para envio dos webhooks por parte da QI, através da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Link Documentação](/documentation/primeiros_passos/configurando_webhooks) | CAB0001 e CAB0002 |

# **QI Conta**

## Abertura de Conta

| Código | Etapa | Descrição | Link Documentação | Pré-requisito |
| --- | --- | --- | --- | --- |
| QIC0002* | Reserva de conta PF | Solicitar a reserva de uma conta cujo titular seja uma pessoa física | [Link Documentação](/documentation/baas/account/reservar_conta_pf) | CAB0005 e CAB0006 |
| QIC0003* | Abertura de conta PF | Realizar a abertura de uma conta cujo titular seja uma pessoa física | [Link Documentação](/documentation/baas/account/abrir_conta_pf) | CAB0005 e CAB0006 |
| QIC0004* | Reserva de conta PJ | Solicitar a reserva de uma conta cujo titular seja uma pessoa jurídica | [Link Documentação](/documentation/baas/account/reservar_conta_pj) | CAB0005 e CAB0006 |
| QIC0005* | Abertura de conta PJ | Realizar a abertura de uma conta cujo titular seja uma pessoa jurídica | [Link Documentação](/documentation/baas/account/abrir_conta_pj) | CAB0005 e CAB0006 |
| QIC0006* | Leitura de webhooks de abertura de conta | Ler corretamente os webhooks de abertura de conta | Item 1.2. ou 1.3:<br/>[Link Documentação](/documentation/baas/account/webhooks) |  QIC0003 ou QIC0005  |
| QIC0007* | Listar contas | Listar contas abertas| [Link Documentação](/documentation/contas/consultar_conta) |  QIC0003 ou QIC0005  |
| QIC0008* | Consulta de dados de uma conta | Consultar dados como saldo, dados do titular, data de abertura, dentre outros | [Link Documentação](/documentation/contas/consultar_conta) |  QIC0003 ou QIC0005  |

## Movimentações

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| QIC0008* | Consulta de Extrato | Realizar a consulta do extrato de uma conta | [Link Documentação](/documentation/movimentacao_de_contas/consulta_de_transacoes) |  QIC0003 ou QIC0005  |
| QIC0009* | Solicitação de comprovante de transferência | Solicitar um comprovante de transferência | [Link Documentação](/documentation/movimentacao_de_contas/comprovante_de_transferencia)|  |
| QIC0010* | Leitura de webhooks de transação | Recepcionar com sucesso todos os webhooks de transação |  [Link Documentação](/documentation/movimentacao_de_contas/webhook_movimentacoes/index.html) |  QIC0003 ou QIC0005  |
| QIC0011* | Consulta de lista de instituições financeiras | Consultar lista de instituições financeiras habiliatadas para recebimento de TED e Pix |  [Link Documentação](/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras) |  QIC0003 ou QIC0005  |

---

# Upload de Documentos

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| UDD0001* | Upload de documento | Realizar o upload de um documento através da nossa API de documentos |  [Link Documentação](/documentation/upload_de_documentos/) |  |

---

# TED

| Código | Etapa | Descrição | Link                                                                                                        | Pré-requisito |
| --- | --- | --- |-------------------------------------------------------------------------------------------------------------| --- |
| TED0001* | Transferência TED Out | Realizar transferência TED  | [Link Documentação](/documentation/baas/ted/realizar_transferencia) | QIC0003 ou QIC0005 |
| TED0002* | Simulação de estorno de uma TED Out | Simular o estorno de uma TED Out enviada a partira de uma QI Conta | Item 3: <br/>[Link Documentação](/documentation/movimentacao_de_contas/transacao) | TED0003 |
| TED0003* | Simulação de TED In | Simular a entrada de uma TED In em uma QI conta | Item 2: <br/>[Link Documentação](/documentation/movimentacao_de_contas/transacao) | QIC0003 ou QIC0005 |
| TED0004* | Listar transações TED| Listar transações TED de entrada/saída  | [Link Documentação](/documentation/baas/ted/listar_teds)  | QIC0003 ou QIC0005 |
| TED0004* | Consulta de transação  TED| Realizar a consulta de uma transação TED  | [Link Documentação](/documentation/baas/ted/consultar_ted)           | QIC0003 ou QIC0005 |
| TED0006* | Leitura de webhooks de TED| Recepcionar com sucesso um webhook de TED | [Link Documentação](/documentation/baas/ted/webhooks/index.html)| QIC0003 ou QIC0005 |
---

# Transferência Interna

| Nº | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| TFI0001 | Transferência Interna com débito em conta | Comandar uma transferência a partir de uma QI Conta, tendo como destino da transferência, outra QI Conta | [Link Documentação](/documentation/baas/ted/realizar_transferencia) |  QIC0003 ou QIC0005  |
| TFI0002 | Simulação de transferência Interna com crédito em conta | Simular o recebimento de recursos na QI Conta alvo, tendo como origem, outra QI Conta | Item 1: <br/> [Link Documentação](/documentation/movimentacao_de_contas/transacao) |  QIC0003 ou QIC0005  |

---

# Boletos

## Gestão de Boletos

| Nº | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| Nº      | Etapa | Descrição | Link  | Pré-requisito |
|---|---|---|---|---|
| BOL0001 | Registro de boleto de um único boleto cobrança    | Realizar o registro de um boleto de cobrança | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao/index.html) | CAB0002 ou CAB0003   |
| BOL0002 | Registro de boleto de um único boleto de cobrança instantâneo | Realizar o registro de um boleto de cobrança | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) | CAB0002 ou CAB0003   |
| BOL0003 | Registro de boleto de boleto em lote  | Realizar o registro de boleto de cobrança em lote | [Link Documentação](/documentation/boletos/v2/emissao/emissao_em_lote) | CAB0002 ou CAB0003   |
| BOL0004 | Emissão de Boleto Único Padrão        | Emitir um boleto único padrão    | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_padrao)  | CAB0002 ou CAB0003   |
| BOL0005 | Emissão de Boleto Único Instantâneo   | Emitir um boleto único instantân | [Link Documentação](/documentation/boletos/v2/emissao/emissao_boleto_unico_instantanea) | CAB0002 ou CAB0003   |
| BOL0006 | Emissão em Lote   | Emitir boletos em lote | [Link Documentação](/documentation/boletos/v2/emissao/emissao_em_lote)| CAB0002 ou CAB0003   |
| BOL0007 | Realizar abatimento no valor de um boleto | Realizar abatimento no valor de um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/abatimento/criar_abatimento) | BOL0001, BOL0002 ou BOL0003 |
| BOL0008 | Cancelar Abatimento     | Cancelar abatimento em um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/abatimento/cancelar_abatimento) | BOL0001, BOL0002 ou BOL0003  |
| BOL0009 | Estender vencimento de um boleto               | Enviar extensão de prazo de um boleto | [Link Documentação](/documentation/boletos/v2/instrucoes/extensao)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0010 | Incluir desconto em um boleto               | Incluir desconto em um boleto    | [Link Documentação](/documentation/boletos/v2/instrucoes/desconto)     | BOL0001, BOL0002 ou BOL0003   |
| BOL0011 | Incluir juros em um boleto                   | Incluir juros em um boleto       | [Link Documentação](/documentation/boletos/v2/instrucoes/juros)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0012 | Incluir multa em um boleto                   | Incluir multa em um boleto       | [Link Documentação](/documentation/boletos/v2/instrucoes/multa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0013 | Realizar baixa de um boleto                   | Baixar um boleto                 | [Link Documentação](/documentation/boletos/v2/instrucoes/baixa)        | BOL0001, BOL0002 ou BOL0003   |
| BOL0014 | Consultar boletos por chave      | Consultar boletos por chave      | [Link Documentação](/documentation/boletos/v2/consulta/consulta_por_chave) | BOL0001, BOL0002 ou BOL0003   |
| BOL0015 | Listar Boletos          | Listar boletos     | [Link Documentação](/documentation/boletos/v2/consulta/listar_boletos) | BOL0001, BOL0002 ou BOL0003   |
| BOL0016 | Consulta de carteira de cobrança      | Consultar uma carteira de cobrança | [Link Documentação](/documentation/boletos/v2/carteira/listar_carteiras/index.html) | BOL0001, BOL0002 ou BOL0003   |
| BOL0017 | Webhooks de Boleto      | Realizar a leitura de webhook para boleto | [Link Documentação](/documentation/boletos/v2/webhooks/boleto) | BOL0001, BOL0002 ou BOL0003   |

## Pagamento de Boletos

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| BOL0009* | Consulta de linha digitável ou Código de Barras | Realizar a consulta de uma linha digitável de um boleto bancário | [Link Documentação](/documentation/baas/cobranca/consultar_boleto_bancario) |  |
| BOL0010* | Realizar pagamento de um boleto | Realizar o pagamento de um boleto bancário | [Link Documentação](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_boleto_bancario) |  QIC0003 ou QIC0005  |
| BOL0012* | Consulta de linha digitável ou Código de Barras de um boleto de convênio | Realizar a consulta de uma linha digitável de um  boleto convênio. | [Link Documentação](/documentation/baas/cobranca/consultar_fatura_de_recolhimento) |  |
| BOL0013* | Realizar pagamento de um boleto de convênio | Realizar o pagamento de um boleto convênio | [Link Documentação](/documentation/baas/cobranca/2fa_v2/solicitacao_de_pagamento_de_fatura_de_recolhimento) |  QIC0003 ou QIC0005  |

---

## Pix

## Transferência Pix 
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
|---------|--|---|---|---|
| PIX0002* | Transferência Pix Out | Realizar uma transferência Pix a partir de uma QI Conta utilizando dados bancários (pix manual) ou chave Pix | [Link Documentação](/documentation/baas/pix/realizar_transferencia) | CAB0001 |
| PIX0035 | Consulta de transferência pix | Recuperar os dados de uma transferência | [Link Documentação](/documentation/baas/pix/consultar_transferencias) | PIX0002 |
| PIX0003* | Simulação de reembolso de Pix Out | Simular o reembolso de um Pix Out. | [Link Documentação - Item 2](/documentation/pix/simulacao)| PIX0002 |
| PIX0004* | Simulação de Pix In | Simular o crédito de um Pix In em uma QI Conta. | [Link Documentação -> Item 1](/documentation/pix/simulacao)||
| PIX0037* | Leitura de webhook de transação pendente | Recepcionar com sucesso um webhook de transação pendente | [Link Documentação](/documentation/baas/pix/webhooks) | PIX0002 |
| PIX0038* | Leitura de webhook de Pix de In | Recepcionar com sucesso um webhook de transferência Pix de entrada | [Link Documentação](/documentation/baas/pix/webhooks#webhook-para-pix-de-entrada)| PIX0004 |
| PIX0039 | Leitura de webhook de Devolução Pix | Recepcionar com sucesso um webhook de devolução de um Pix | [Link Documentação](/documentation/baas/pix/webhooks#webhook-para-devolu%C3%A7%C3%B5es-de-pix) | PIX0003 |
| PIX0040 | Solicitar a devolução de um Pix recebido | Solicitar a devolução de um Pix recebido | [Link Documentação](/documentation/baas/pix/solicitar_devolucao) | PIX0003 |
| PIX0041 | Listar transferências Pix de uma conta | Listar transferências Pix de uma conta | [Link Documentação](/documentation/baas/pix/listar_transferencias) | PIX0003 |

## Gestão de Chave Pix

### Criação e Exclusão de Chave pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0008* | Criação de chave Pix | Realizar a criação de chave Pix do tipo cpf, cnpj, aleatória, e-mail e telefone | [Link Documentação](/documentation/pix/criar_chave) | 
| PIX0010* | Listagem de chaves Pix de uma QI Conta | Listar chaves Pix vinculadas a uma QI Conta | [Link Documentação](/documentation/pix/listar_chaves_pix) | PIX0008 |

## Gestão de QR Code Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0022* | Criação de QR Code Pix Estático | Gerar QR Code Estático | [Link Documentação](/documentation/pix/criar_qr_code_estatico) | PIX0008 |
| PIX0023 | Criação de QR Code Pix Dinâmico | Gerar QR Code Dinâmico com vencimento (dia de vencimento) e gerar QR Code Dinâmico Instantâneo (com segundos de expiração). | [Link Documentação](/documentation/pix/criar_qr_code_dinamico) | PIX0008 |
| PIX0024 | Exclusão de QR Code Pix Dinâmico | Excluir QR Code Pix | [Link Documentação](/documentation/pix/baixar_qr_code_dinamico) | PIX0023 |
| PIX0025 | Listar QR Codes Pix Dinâmicos | Listar QR Codes Pix Dinâmicos | [Link Documentação](/documentation/pix/pesquisar_por_qr_code_dinamico) | PIX0023 |
| PIX0026 | Leitura de webhook de expiração de QR Code Pix Dinâmico Instantâneo | Recepcionar com sucesso um webhook de expiração de QR Code Pix Dinâmico Instantâneo | [Link Documentação](/documentation/pix/webhook_por_qr_code_expirado) | PIX0023 |

## Pagamento de QR Code Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0029* | Pagamento de QR Code Pix Estático | Realizar o pagamento de um QR Code Pix Estático | [Link Documentação](/documentation/baas/pix/realizar_transferencia#transfer%C3%AAncia-por-qr-code-pix) | PIX0022 |
| PIX0030* | Pagamento de QR Code Pix Dinâmico | Realizar o pagamento de um QR Code Pix Dinâmico |  [Link Documentação](/documentation/baas/pix/realizar_transferencia#transfer%C3%AAncia-por-qr-code-pix) | PIX0022 |
| PIX0027* | Decodificação de QR Code Pix | Decodificar um QR Code Pix Estático, Dinâmico com vencimento e Dinâmico Instantâneo | [Link Documentação](/documentation/pix/decodificar_qr_code) | PIX0022 e PIX0023 |

## Gestão de Limite Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0032* | Solicitação de alteração de limite Pix | Realizar solicitação de alteração de limite Pix de uma QI Conte | [Link Documentação](/documentation/pix/solicitar_alteracao_de_limite_pix) |  QIC0003 ou QIC0005  |
| PIX0033 | Listagem de solicitações de alteração de limite Pix | Listar as solicitações de alteração de limite Pix para uma QI Conta | [Link Documentação](/documentation/pix/busca_por_solicitacao_de_limite_pix) | PIX0032 |
| PIX0034* | Consulta de limite Pix consumido | Consultar o limite Pix consumido para uma QI Conta | [Link Documentação](/documentation/pix/busca_por_uso_de_limite_pix) |  QIC0003 ou QIC0005  |

---

# Gestão de Tarifas
| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| GTF0001* | Solicitação de alteração de tarifas | Realizar a alteração de tarifas de uma conta| [Link Documentação](/documentation/contas/gestao_de_tarifas) |  QIC0003 ou QIC0005  |
| GTF0002* | Consulta de tarifas  | Consultar tarifas cadastradas em uma conta | [Link Documentação](/documentation/contas/consulta_de_tarifas) |  QIC0003 ou QIC0005  |

---

# Roteiro de Homologação - Pix Conta Integrada

URL: /documentation/roteiros_de_homologacao/roteiro_pix_conta_integrada

O roteiro de homolgoação descreve todos os recursos e funcionalidades que precisam
ser testados pelo parceiro integrador no ambiente de sandbox da QI Tech (ambiente de testes), 
antes da entrada em ambiente de produção do produto.

Este roteiro descreve todos os recursos e funcionalidades envolvidos no produto. 

`*: etapas obrigatórias para entrada em produção`

## Cadastro e Autenticação API BaaS
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
|---------|--|---|---|---|
| CAB0001* | Cadastro no ambiente de Sandbox | Realizar o cadastro na plataforma da QI Tech no ambiente de Sandbox (sandbox.qitech.app) | [Link documentação](/documentation/primeiros_passos/inicio) 
| CAB0002* | Validação de token em Sandbox | Realizar a validação do QI Token em Sandbox | [Manual de Inclusão do Token](https://docs.qitech.com.br/assets/pdfs/QI%20Tech%20Manual%20Inclus%C3%A3o%20de%20Token.pdf) | CAB0001 |
| CAB0003* | Troca de chaves públicas | Realizar a troca de chaves públicas dentro da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Troca de chaves](/documentation/primeiros_passos/troca_de_chaves) | CAB0001 e CAB0002 |
| CAB0004* | Teste de autenticação de chamadas | Finalizar teste de autenticação de chamadas | [Teste de Autenticação](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2) <br/><br/> [Endpoints de teste da autenticação](/documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste) | CAB0003 |
| CAB0005* | Configuração de webhooks | Realizar a configuração da url para envio dos webhooks por parte da QI, através da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Configuração de webhooks](/documentation/primeiros_passos/configurando_webhooks) | CAB0001 e CAB0002 |

## QI Conta
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
|---------|--|---|---|---|
| QIC0005* | Consulta de dados de uma conta | Recuperar os dados de uma QI Conta com sucesso | [Consultar Conta](/documentation/contas/consultar_conta) | - |
| QIC0006* | Listar contas | Listar contas abertas| [Link Documentação](/documentation/contas/consultar_contas) |  -  |

## Gestão de QR Code Pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0023 | Criação de QR Code Pix Dinâmico | Gerar QR Code Dinâmico com vencimento (dia de vencimento) e gerar QR Code Dinâmico Instantâneo (com segundos de expiração). | [Link Documentação](/documentation/pix/criar_qr_code_dinamico) | PIX0008 |
| PIX0024 | Exclusão de QR Code Pix Dinâmico | Excluir QR Code Pix | [Link Documentação](/documentation/pix/baixar_qr_code_dinamico) | PIX0023 |
| PIX0025 | Listar QR Codes Pix Dinâmicos | Listar QR Codes Pix Dinâmicos | [Link Documentação](/documentation/pix/pesquisar_por_qr_code_dinamico) | PIX0023 |
| PIX0026 | Leitura de webhook de expiração de QR Code Pix Dinâmico Instantâneo | Recepcionar com sucesso um webhook de expiração de QR Code Pix Dinâmico Instantâneo | [Link Documentação](/documentation/pix/webhook_por_qr_code_expirado) | PIX0023 |
| PIX0038 | Leitura de webhook de entrada de uma transferência Pix  | Recepcionar com sucesso um webhook de entrada de uma transferência Pix  | [Link Documentação](/documentation/baas/pix/webhooks#webhook-para-pix-de-entrada) | - |

## Consulta de Chave Pix
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
|---------|--|---|---|---|
| PIX0036* | Consulta de dados de uma chave Pix | Realizar com sucesso a consulta de uma chave Pix no Bacen. | [Consulta de chave Pix](/documentation/baas/pix/consultar_chave_pix) ||

## Transferência Pix 
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
|---------|--|---|---|---|
| PIX0002* | Transferência Pix Out | Realizar uma transferência Pix a partir de uma QI Conta utilizando dados bancários (pix manual) ou chave Pix | [Realização de Transação Pix](/documentation/baas/pix/realizar_transferencia)||
| PIX0035 | Listagem de transferências Pix | Listar todas as transferências Pix de uma conta | [Listagem de transferências Pix](/documentation/baas/pix/listar_transferencias) | PIX0002 |
| PIX0036 | Consulta de transferência Pix | Recuperar os dados de uma transferência | [Consulta de transferência Pix](/documentation/baas/pix/consultar_transferencias) | PIX0002 |
| PIX0003* | Simulação de reembolso de Pix Out | Simular o reembolso de um Pix Out. | [Simulação reembolso Pix Out -> Item 3](/documentation/pix/simulacao)| PIX0002 |
| PIX0004* | Simulação de Pix In | Simular o crédito de um Pix In em uma QI Conta. | [Simulação Pix In -> Item 1](/documentation/pix/simulacao)||
| PIX0005* | Reembolso de Pix In | Realizar o reembolso de um Pix In a partir de uma QI Conta. | [Reembolso Pix In](/documentation/baas/pix/solicitar_devolucao)| PIX0004 |
| PIX0040* | Simulação de status de transferência Pix pendente | Simular o status de transferência Pix| [Simulação Pix In -> Item 5](/documentation/pix/simulacao)||
| PIX0037* | Leitura de webhook de transação pendente | Recepcionar com sucesso um webhook de transação pendente | [Webhook de transação pendente](/documentation/baas/pix/webhooks#webhook-para-transa%C3%A7%C3%B5es-pendentes) | PIX0040 |
| PIX0038* | Leitura de webhook de Pix de In | Recepcionar com sucesso um webhook de transferência Pix de entrada | [Webhook Pix In](/documentation/baas/pix/webhooks#webhook-para-pix-de-entrada) | PIX0004 |
| PIX0039 | Leitura de webhook de Devolução Pix | Recepcionar com sucesso um webhook de devolução de um Pix | [Webhook Devolução Pix](/documentation/baas/pix/webhooks#webhook-para-devolu%C3%A7%C3%B5es-de-pix) | PIX0003 |

## Movimentações
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
|---------|--|---|---|---|
| QIC0008* | Consulta de Transações | Realizar a consulta das transações de uma conta | [Consulta de Transações](/documentation/movimentacao_de_contas/consulta_de_transacoes) ||
| QIC0009 | Solicitação de comprovante de transferência | Solicitação de comprovante de transferência | [Solicitar comprovante de transferência](/documentation/movimentacao_de_contas/comprovante_de_transferencia) | PIX0002 |
| QIC0010* | Leitura de webhooks de transação | Recepcionar com sucesso todos os webhooks de transação | [Webhook account_transaction](/documentation/movimentacao_de_contas/webhook_movimentacoes) | CAB0005 e PIX0002 |
| QIC0011 | Consulta de lista de instituições financeiras | Consultar lista de instituições financeiras habiliatadas para recebimento de TED e Pix | [Consulta de Instituições Financeiras](/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras) ||

## Gestão de Chave Pix

### Criação e Exclusão de Chave pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0008* | Criação de chave Pix | Realizar a criação de chave Pix do tipo cpf, cnpj, aleatória, e-mail e telefone | [Link Documentação](/documentation/pix/criar_chave) | -  | 
| PIX0009 | Exclusão de chave Pix | Realizar a exclusão de uma chave Pix | [Link Documentação](/documentation/pix/excluir_chave) | PIX0008 |
| PIX0010* | Listagem de chaves Pix de uma QI Conta | Listar chaves Pix vinculadas a uma QI Conta | [Link Documentação](/documentation/pix/listar_chaves_pix) | PIX0008 |

## Decodificar QR Code Pix
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
|---------|--|---|---|---|
| PIX0027* | Decodificação de QR Code Pix | Consultar os dados de um QR Code Pix (decodificar) utilizando a url do pix copia e cola | [Decodificação de QR Code Pix](/documentation/pix/decodificar_qr_code)||

## Gestão de Chave Pix

### Criação e Exclusão de Chave pix

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PIX0008* | Criação de chave Pix | Realizar a criação de chave Pix do tipo cpf, cnpj, aleatória, e-mail e telefone | [Link Documentação](/documentation/pix/criar_chave) | -  | 
| PIX0009 | Exclusão de chave Pix | Realizar a exclusão de uma chave Pix | [Link Documentação](/documentation/pix/excluir_chave) | PIX0008 |
| PIX0010* | Listagem de chaves Pix de uma QI Conta | Listar chaves Pix vinculadas a uma QI Conta | [Link Documentação](/documentation/pix/listar_chaves_pix) | PIX0008 |

## Decodificar QR Code Pix
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
|---------|--|---|---|---|
| PIX0027* | Decodificação de QR Code Pix | Consultar os dados de um QR Code Pix (decodificar) utilizando a url do pix copia e cola | [Decodificação de QR Code Pix](/documentation/pix/decodificar_qr_code)||

---

# Roteiro de Homologação - Pix indireto

URL: /documentation/roteiros_de_homologacao/roteiro_pix_indireto

O roteiro de homologação descreve todos os recursos e funcionalidades que precisam
ser testadas pelo parceiro integrador no ambiente de sandbox da QI Tech (ambiente de testes), 
antes da entrada em ambiente de produção.

Este roteiro descreve todos os recursos e funcionalidades envolvidas no produto. 

## Cadastro e Autenticação API BaaS
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
|---------|--|---|---|---|
| CAB0001 | Cadastro no ambiente de Sandbox | Realizar o cadastro na plataforma da QI Tech no ambiente de Sandbox (sandbox.qitech.app) | [Link documentação](/documentation/primeiros_passos/inicio) 
| CAB0002 | Validação de token em Sandbox | Realizar a validação do QI Token em Sandbox | [Link documentação](https://docs.qitech.com.br/assets/pdfs/QI%20Tech%20Manual%20Inclus%C3%A3o%20de%20Token.pdf) | CAB0001 |
| CAB0003 | Troca de chaves públicas | Realizar a troca de chaves públicas dentro da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Link documentação](/documentation/primeiros_passos/troca_de_chaves) | CAB0001 e CAB0002 |
| CAB0004 | Teste de autenticação de chamadas | Finalizar teste de autenticação de chamadas | [Teste de Autenticação](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2) <br/><br/> [Link documentação](/documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste) | CAB0003 |
| CAB0005 | Configuração de webhooks | Realizar a configuração da url para envio dos webhooks por parte da QI, através da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Link documentação](/documentation/primeiros_passos/configurando_webhooks) | CAB0001 e CAB0002 |

## QI Conta
### Contas 
| Código  | Etapa | Descrição | Link Documentação                                                                                           | Pré-requisito |
|---------|--|---|-------------------------------------------------------------------------------------------------------------|---------------|
| QCI0012 | Abertura de conta de titularidade do participante indireto | Realizar a abertura de 4 contas de titularidade do participante indireto | [Link documentação](/documentation/contas/abertura_de_conta/abertura_de_conta_pj) | CAB0004 e CAB0005 |
| QIC0005 | Consulta de dados de uma conta | Recuperar os dados de uma conta previamente aberta pelo participante | [Link documentação](/documentation/contas/consultar_contas)                          |        QCI0012       |
| QIC0006 | Encerramento de uma conta | Encerrar uma conta de titularidade do participante indireto | [Link documentação](/documentation/contas/encerramento_de_conta)                          |        QCI0012       |

## Alias 
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
|---------|--|---|---|---|
| QCA0014 | Criação de alias de pessoa jurídica para conta de titularidade do participante indireto| Realizar a criação de 2 alias de uma ou mais pessoas jurídicas para uma conta de titularidade do participante indireto | [Link documentação](/documentation/pix_indireto/gerenciamento_de_alias/criacao_de_alias)|QCI0012|
| QCA0015 | Criação de alias de pessoa física para conta de titularidade do participante indireto | Realizar a criação de 2 alias de uma ou mais pessoas físicas para uma conta de titularidade do participante indireto | [Link documentação](/documentation/pix_indireto/gerenciamento_de_alias/criacao_de_alias) | QCI0012 |
| QCA0016 | Consulta de dados de um alias | Consulta os dados de um alias vinculado a uma conta de titularidade do participante indireto | [Link documentação](/documentation/pix_indireto/gerenciamento_de_alias/consultar_alias)| QCA0014 ou QCA0015 |
| QCA0017 | Deleção de alias | Realizar a deleção de um alias vinculado a uma conta de titularidade do participante indireto | [Link documentação](/documentation/pix_indireto/gerenciamento_de_alias/deletar_alias)|QCA0014 ou QCA0015|
| QCA0018 | Listagem de alias vinculados a uma QI Conta | Realizar a deleção de um alias vinculado a uma conta de titularidade do participante indireto | [Link documentação](/documentation/pix_indireto/gerenciamento_de_alias/listagem_de_alias)| QCA0014 ou QCA0015 |

## Movimentações
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito                                                       |
|---------|--|---|---|---------------------------------------------------------------------|
| QIC0008 | Consulta de Extrato| Realizar a consulta do extrato de uma conta | [Link documentação](/documentation/movimentacao_de_contas/consulta_de_transacoes) | QCI0012 |
| QIC0009 | Solicitação de comprovante de transferência | Solicitação de comprovante de transferência | [Link documentação](/documentation/movimentacao_de_contas/comprovante_de_transferencia) | PXI0002, ou PXI0003, ou PXI0009, ou PXI0010, ou PXI0004, ou PXI0005 |
| QIC0010 | Leitura de webhooks de transação | Recepcionar com sucesso todos os webhooks de transação | [Link documentação](/documentation/movimentacao_de_contas/webhook_movimentacoes/index.html) | PXI0002, ou PXI0003, ou PXI0009, ou PXI0010, ou PXI0004, ou PXI0005 |
| QIC0011 | Consulta de lista de instituições financeiras | Consultar lista de instituições financeiras habiliatadas para recebimento de TED e Pix | [Link documentação](/documentation/lista_de_instituicoes_financeiras/consulta_de_instituicoes_financeiras) |                                                                     |

## Pix indireto
### Transferência Pix Out
| Código   | Etapa                                            | Descrição | Link Documentação | Pré-requisito                               |
|----------|--------------------------------------------------|---|---|---------------------------------------------|
| PXI0002  | Transferência Pix Out via Chave Pix - Síncrona	  | Realizar uma transferência Pix a partir de uma QI Conta utilizando dados bancários utilizando uma chave Pix, com fluxo síncrono de resposta da API | [Link documentação](/documentation/pix_indireto/movimentacoes/transacao/transacao_pix_chave_sync) | QCA0014 ou QCA0015                          |
| PXI0003  | Transferência Pix Out Manual - Síncrona	         | Realizar uma transferência Pix a partir de uma QI Conta utilizando dados bancários (pix manual), com fluxo síncrono de resposta da API | [Link documentação](/documentation/pix_indireto/movimentacoes/transacao/transacao_pix_manual_sync) | QCA0014 ou QCA0015                          |
| PXI0009  | Transferência Pix Out via Chave Pix - Assíncrona	 | Realizar uma transferência Pix a partir de uma QI Conta utilizando dados bancários utilizando uma chave Pix, com fluxo assíncrono de resposta da API | [Link documentação](/documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_normal) | QCA0014 ou QCA0015                          |
| PXI0010  | Transferência Pix Out Manual - Assíncrona        | Realizar uma transferência Pix a partir de uma QI Conta utilizando dados bancários (pix manual), com fluxo assíncrono de resposta da API | [Link documentação](/documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_manual) | QCA0014 ou QCA0015                          |
| PXI0004  | Simulação de reembolso de Pix Out                | Simular o reembolso de um Pix Out | [Link documentação](/documentation/pix_indireto/movimentacoes/simulacao#3---simulação-de-devolução-de-pix) | PXI0002, ou PXI0003, ou PXI0009, ou PXI0010 |
| PXI0005  | Simulação de Pix In                              | Simular o crédito de um Pix In em uma QI Conta. | [Link documentação](/documentation/pix_indireto/movimentacoes/simulacao#3---simulação-de-devolução-de-pix) | QCA0014 ou QCA0015                          |
| PXI0006  | Reembolso de Pix In                              | Realizar o reembolso de um Pix In a partir de uma QI Conta | [Link documentação](/documentation/pix_indireto/movimentacoes/devolucao_pix) | PXI0005                                     |
| PXI0007  | Simulação de Pix Out rejeitado                   | Realizar um pix out utilizando as chaves mockadas informadas na documentação da QI Tech para simular o cenário de um pix rejeitado. | [Link documentação](/documentation/pix_indireto/movimentacoes/simulacao/index.html#5---simulação-de-transação-rejeitada) |                                             |
| PXI0008  | Simulação de Pix Out pendente                    | Realizar um pix out utilizando as chaves mockadas informadas na documentação da QI Tech para simular o cenário de um pix pendente. | [Link documentação](/documentation/pix_indireto/movimentacoes/simulacao#4---simulação-de-transação-em-estado-pendente-de-confirmação) | PXI0003, ou PXI0010                         |

### Transferência Pix Interna
| Código   | Etapa                              | Descrição | Link Documentação | Pré-requisito                               |
|----------|------------------------------------|---|---|---------------------------------------------|
| PXI0012  | Transferência Pix Interna entre 2 alias via chave Pix - Síncrona	 | Realizar uma transferência Pix a partir de uma QI Conta utilizando uma chave Pix, com fluxo síncrono de resposta da API | [Link documentação](/documentation/pix_indireto/movimentacoes/transacao/transacao_pix_chave_sync) | QCA0014 ou QCA0015                          |
| PXI0013  | Transferência Pix Interna entre 2 alias via Manual - Síncrona | Realizar uma transferência Pix a partir de uma QI Conta utilizando dados bancários (pix manual), com fluxo síncrono de resposta da API| [Link documentação](/documentation/pix_indireto/movimentacoes/transacao/transacao_pix_manual_sync) | QCA0014 ou QCA0015                          |
| PXI0015  | Transferência Pix Interna entre 2 alias via chave Pix - Assíncrona	 | Realizar uma transferência Pix a partir de uma QI Conta utilizando uma chave Pix, com fluxo assíncrono de resposta da API | [Link documentação](/documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_normal) | QCA0014 ou QCA0015                          |
| PXI0016  | Transferência Pix Interna entre 2 alias via Manual - Assíncrona | Realizar uma transferência Pix a partir de uma QI Conta dados bancários (pix manual), com fluxo assíncrono de resposta da API | [Link documentação](/documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_manual) | QCA0014 ou QCA0015                          |
| PXI0014  | Devolução de Pix Interno  | Realizar a devolução de um Pix Interno a partir de uma QI Conta | [Link documentação](/documentation/pix_indireto/movimentacoes/simulacao#3---simulação-de-devolução-de-pix) | PXI0012, ou PXI0013, ou PXI0015, ou PXI0016 |

### Consulta de Transferência Pix
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito                                                                                           |
|---------|--|---|---|---------------------------------------------------------------------------------------------------------|
| PXI0017 | Consulta transferência Pix | Recuperar os dados de uma transaferência Pix | [Link documentação](/documentation/pix_indireto/movimentacoes/consultar_pix)| PXI0002, ou PXI0003, ou PXI0009, ou PXI0010, ou PXI0005, ou PXI0012, ou PXI0013, ou PXI0015, ou PXI0016 |

### Movimentações Pix
| Código   | Etapa                              | Descrição | Link Documentação | Pré-requisito                               |
|----------|------------------------------------|---|---|---------------------------------------------|
| PXI0018  | Leitura de webhook de pix in	 | Realizar com sucesso, a leitura de um webhook de um Pix In. O webhook é gerado a partir da simulação de um Pix In| [Link documentação](/documentation/pix_indireto/movimentacoes/webhook/webhook_incoming_pix) | PXI0005                         |
| PXI0019  | Leitura de webhook de pix interno | Realizar com sucesso, a leitura de um webhook de um pix interno. O webhook é gerado após realizar um Pix Interno| [Link documentação](/documentation/pix_indireto/movimentacoes/webhook/webhook_incoming_pix) | PXI0012, ou PXI0013, ou PXI0015, ou PXI0016                          |
| PXI0020  | Leitura de webhook de transação pix pendente	 | Realizar com sucesso, a leitura de um webhook de uma transação pix pendente. O webhook é gerado a partir da simulação de uma transação Pix Pendente. | [Link documentação](/documentation/pix_indireto/movimentacoes/webhook/webhook_transacao) | PXI0008                         |
| PXI0021  |Leitura de webhook de reembolso de um pix out | Realizar com sucesso, a leitura de um webhook de reembolso de um pix out. O webhook é gerado a partir da simulação de um reembolso de um pix out | [Link documentação](/documentation/pix_indireto/movimentacoes/webhook/webhook_devolucao_outgoing_pix) | PXI0004                          |

## Gestão de chave pix

### Criação e Exclusão de chave pix
| Código   | Etapa                                          | Descrição | Link Documentação | Pré-requisito |
|----------|------------------------------------------------|---|---|--------|
| PXI0022  | Criação de chave Pix aleatória **pessoa física**	  | Realizar a criação de **5** chaves aleatórios em um alias de pessoa física| [Link documentação](/documentation/pix_indireto/chaves_pix/criacao_de_chaves) | QCA0014 ou QCA0015 |
| PXI0023  | Criação de chave Pix aleatória **pessoa jurídica** | Realizar a criação de **20** chaves aleatórios em um alias de pessoa jurídica| [Link documentação](/documentation/pix_indireto/chaves_pix/criacao_de_chaves) | QCA0014 ou QCA0015 |
| PXI0024  | Exclusão de chave Pix **pessoa física**        | Realizar a exclusão de uma chave Pix de uma pessoa física | [Link documentação](/documentation/pix_indireto/chaves_pix/deletar_chaves) | PXI0022 |
| PXI0025  | Exclusão de chave Pix **pessoa jurídica**          | Realizar a exclusão de uma chave Pix de uma pessoa jurídica| [Link documentação](/documentation/pix_indireto/chaves_pix/deletar_chaves) | PXI0025|
| PXI0026  | Listagem de chaves Pix de um alias | Listar chaves Pix vinculadas a um alias | [Link documentação](/documentation/pix_indireto/chaves_pix/listar_chaves) | PXI0022, ou PXI0023 |

## Gestão de QR Code Pix
| Código   | Etapa                                                 | Descrição                                                                         | Link Documentação                                                                                                     | Pré-requisito       |
|----------|-------------------------------------------------------|-----------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|---------------------|
| PXI0027  | Introdução QR Code pix	                               | Introdução QR Code pix                                                            | [Link documentação](/documentation/pix_indireto/qr_code/introducao_qr_code) | PXI0022, ou PXI0023 |
| PXI0027  | Criação de QR Code Pix Estático	                      | Gerar QR Code Estático                                                            | [Link documentação](/documentation/pix_indireto/qr_code/Criar%20QR%20Code/criar_qr_code_estatico) | PXI0022, ou PXI0023 |
| PXI0028  | Criação de QR Code Pix Dinâmico com vencimento        | Gerar QR Code Dinâmico com vencimento                                             | [Link documentação](/documentation/pix_indireto/qr_code/Criar%20QR%20Code/criar_qr_code_dinamico_com_vencimento) | PXI0022, ou PXI0023 |
| PXI0029  | Criação de QR Code Pix Dinâmico de pagamento imediato | Criar QR Code Pix Dinâmico pagamento imediato                                     | [Link documentação](/documentation/pix_indireto/qr_code/Criar%20QR%20Code/criar_qr_code_dinamico_imediato) | PXI0028  |
| PXI0029  | Desativar de QR Code Pix Dinâmico                     | Desativar de QR Code Pix Dinâmico                                                            | [Link documentação](/documentation/pix_indireto/qr_code/desativar_qr_code) | PXI0028  |
| PXI0030  | Listar QR Codes de um alias                           | Listar QR Codes de um alias                                                      | [Link documentação](/documentation/pix_indireto/qr_code/listar_alias_qr_codes) | PXI0029  |
| PXI0030  | Consultar um QR Code Pix                              | Consultar um QR Code Pix                                                       | [Link documentação](/documentation/pix_indireto/qr_code/consultar_qr_code) |   |
| PXI0031  | Webhook para Pix de Entrada de pagamento de QR Code   | Webhook para Pix de Entrada de pagamento de QR Code | [Link documentação](/documentation/pix_indireto/qr_code/webhook_incoming_pix) | PXI0028 |
| PXI0032  | Decodificação de QR Code Pix                          | Decodificar um QR Code Pix Estático, Dinâmico com vencimento e Dinâmico Instantâneo | [Link documentação](/documentation/pix_indireto/qr_code/decodificar_qr_code)                                 |   |

## Pagamento de QR code Pix
| Código   | Etapa                                          | Descrição                                                                            | Link Documentação                                                                                                     | Pré-requisito       |
|----------|------------------------------------------------|--------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|---------------------|
| PXI0033  | Pagamento de QR Code Pix Estático - Síncrono	  | Realizar o pagamento de um QR Code Pix Estático, com fluxo síncrono de resposta da API   | [Link documentação](/documentation/pix_indireto/movimentacoes/transacao/transacao_pix_qr_code_sync) | PXI0032 |
| PXI0028  | Pagamento de QR Code Pix Dinâmico - Síncrono	  | Realizar o pagamento de um QR Code Pix Dinâmico, com fluxo síncrono de resposta da API     | [Link documentação](/documentation/pix_indireto/movimentacoes/transacao/transacao_pix_qr_code_sync) | PXI0032 |
| PXI0035  | Pagamento de QR Code Pix Estático - Assíncrono  | Realizar o pagamento de um QR Code Pix Estático, com fluxo assíncrono de resposta da API    | [Link documentação](/documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_qr_code) | PXI0032  |
| PXI0036  | Pagamento de QR Code Pix Dinâmico - Assíncrono  | Realizar o pagamento de um QR Code Pix Dinâmico, com fluxo assíncrono de resposta da API     | [Link documentação](/documentation/pix_indireto/movimentacoes/transacao_async/transacao_pix_qr_code) | PXI0032  |

## Relato de Infração
| Código   | Etapa                                          | Descrição                                                                            | Link Documentação                                                                                                    | Pré-requisito                               |
|----------|------------------------------------------------|--------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|---------------------------------------------|
| PXI0037  | Relato de Infração (outgoing) de um Pix Out	  | Abrir um relato de infração para um Pix Out  | [Link documentação](/documentation/pix_indireto/relato_de_infracao/criar_relato_infracao) | PXI0002, ou PXI0003, ou PXI0009, ou PXI0010 |
| PXI0038  | Relato de infração (outgoing) de um Pix In  | Abrir um relato de infração  para um Pix In     | [Link documentação](/documentation/pix_indireto/relato_de_infracao/criar_relato_infracao) | PXI0005                                     |
| PXI0039  | Leitura de webhook de atualização de status de Relato de Infração (incoming e outgoing)  | Recepcionar com sucesso o webhook de atualização de status de um relato de infração anteriormente aberto pelo participante  | [Link documentação](/documentation/pix_indireto/relato_de_infracao/webhooks_relato_infracao) | PXI0037, ou  PXI0038                        |
| PXI0040  | Consulta de Relato de Infração (incoming e outgoing)  | Recuperar os dados de um relato de infração para um Pix Out/In aberto pelo participante     | [Link documentação](/documentation/pix_indireto/relato_de_infracao/consultar_relato_infracao) | PXI0037, ou  PXI0038                        |
| PXI0041  | Cancelamento de Relato de Infração (outgoing)	  | Cancelar um relato de infração anteriormente aberto pelo participante   | [Link documentação](/documentation/pix_indireto/relato_de_infracao/cancelar_relato_infracao) | PXI0037, ou  PXI0038                        |
| PXI0042  | Simulação de resposta de aceite de Relato de Infração (outgoing)	  | Simular a resposta com aceite da contraparte para um relato de infração criado pelo participante (analysis_result=agreed)     | Contatar time técnico da QI para simulação deste cenário | PXI0037, ou  PXI0038                        |
| PXI0043  | Simulação de resposta de rejeição de Relato de Infração (outgoing)  | Simular a resposta com rejeição da contraparte para um relato de infração criado pelo participante (analysis_result=disagreed)  | [Link documentação](/documentation/pix_indireto/relato_de_infracao/webhooks_relato_infracao) | PXI0037, ou  PXI0038                        |
| PXI0044  | Simulação de recebimento de um Relato de Infração (incoming) | Simular o recebimento de um relato de infração criado por outro PSP para um Pix In recebido pelo participante    | Contatar time técnico da QI para simulação deste cenário | PXI0005                                     |
| PXI0045  | Aceite de Relato de Infração (incoming)  | Fechar um Relato de Infração (incoming) informando o aceite do relato recebido.  | [Link documentação](/documentation/pix_indireto/relato_de_infracao/fechar_relato_infracao) | PXI0044                                     |
| PXI0046  | Rejeição de Relato de Infração (incoming)	  | Fechar um Relato de Infração (incoming) informando a rejeição do Relato de Infração recebido.    | [Link documentação](/documentation/pix_indireto/relato_de_infracao/fechar_relato_infracao) | PXI0044                                     |
| PXI0047  | Listagem de Relatos de Infração (incoming e outgoing) | Listar Relatos de Infração (incoming e outgoing) recebidos ou criados pelo participante | [Link documentação](/documentation/pix_indireto/devolucao/listar_solicitacoes) | PXI0037, ou PXI0038, ou PXI0044             |

## Solicitação de Devolução
| Código   | Etapa                                                                   | Descrição                                                                                                                                           | Link Documentação                                                                               | Pré-requisito                               |
|----------|-------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|---------------------------------------------|
| PXI0048  | Solicitação de devolução por relato de infração                         | Abrir uma solictação de dovolução para um Relato de Infração (outgoing) aceito pela contraparte (PSP recebedor).                                   | [Link documentação](/documentation/pix_indireto/devolucao/criar_devolucao) | PXI0042                                     |
| PXI0049  |Solicitação de devolução por erro operacional                            | Abrir uma solictação de dovolução para um Relato de Infração (outgoing) aceito pela contraparte (PSP recebedor).                                    | [Link documentação](/documentation/pix_indireto/devolucao/criar_devolucao) | PXI0002, ou PXI0003, ou PXI0009, ou PXI0010 |
| PXI0050  |Consulta de Solicitação de Devolução (incoming e outgoing)               | Recuperar os dados de uma solicitação de devolução aberto pelo participante                          | [Link documentação](/documentation/pix_indireto/devolucao/consultar_devolucao) | PXI0048, ou PXI0049                         |
| PXI0051  | Cancelamento de Solicitação de Devolução                                | Cancelar uma solicitação de devolução anteriormente aberto pelo participante                                                           | [Link documentação](/documentation/pix_indireto/devolucao/cancelar_devolucao) | PXI0048, ou PXI0049                         |
| PXI0052  | Simulação de aceite de uma Solicitação de Devolução por relato de infração	 | Simular o aceite de uma solicitação de devolução por relato de infração aberta pelo participante.                                                                            | Contatar time técnico da QI para simulação deste cenário                                        | PXI0048                                     |
| PXI0053  | Simulação de aceite de uma Solicitação de Devolução por erro operacional | Simular o aceite de uma solicitação de devolução por erro operacional aberta pelo participante.                         | Contatar time técnico da QI para simulação deste cenário                                        | PXI0049                                     |
| PXI0054  | Simulação de rejeição de uma Solicitação de Devolução por relato de infração | Simular a rejeição de uma solicitação de devolução por relato de infração aberta pelo participante.                    | Contatar time técnico da QI para simulação deste cenário                                        | PXI0048                                     |
| PXI0055  | Simulação de rejeição de uma Solicitação de Devolução por erro operacional | Simular a rejeição de uma solicitação de devolução por erro operacional aberta pelo participante.                                      | Contatar time técnico da QI para simulação deste cenário                                        | PXI0049                                     |
| PXI0056  | Leitura de webhook de atualização de status da solicitação de devolução | Recepcionar com sucesso o webhooks de atualização de status da solicitação de devolução                                                                     | [Link documentação](/documentation/pix_indireto/devolucao/webhooks_devolucao) | PXI0048, ou PXI0049                         |
| PXI0057  | Listagem de Solicitações de Devolução	                                  | Listar solicitações de devolução recebidos ou criados pelo participante                                                       | [Link documentação](/documentation/pix_indireto/devolucao/listar_solicitacoes) | PXI0048, ou PXI0049, ou PXI0058             |
| PXI0058  | Simulação de recebimento de uma Solicitação de Devolução por relato de infração | Simular o recebimento de uma solicitação de devolução por relato de infração                                                                        | Contatar time técnico da QI para simulação deste cenário                      | PXI0038, ou PXI0044                         |
| PXI0059  | Simulação de recebimento de uma Solicitação de Devolução por erro operacional | Simular o recebimento de uma solicitação de devolução por erro operacional                                                                          | Contatar time técnico da QI para simulação deste cenário                     | PXI0005                                     |
| PXI0060  | Reembolso de Pix In de uma Solicitação de Devolução recebida            | Realizar o reembolso de uma Pix In informado na Solicitação de Devolução recebida pelo participante                                                 | [Link documentação](/documentation/pix_indireto/movimentacoes/devolucao_pix) | PXI0058, ou PXI0059                         |
| PXI0061  | Fechar Solicitação de Devolução	                                        | Fechar uma Solicitação de Devolução, informando a pix_transfer_key do Reembolso Pix realizado em resposta a esta Solicitação de Devolução recebida. | [Link documentação](/documentation/pix_indireto/devolucao/fechar_devolucao) | PXI0060                                     |

## Gestão de Tarifas
| Código   | Etapa                                          | Descrição                                                                            | Link Documentação                                                                                                     | Pré-requisito       |
|----------|------------------------------------------------|--------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|---------------------|
| GDT0001  | Alteração de configuração de tarifas de uma QI Conta  | Alterar a configuração de tarifas de uma QI Conta   | [Link documentação](/documentation/contas/gestao_de_tarifas) | QCI0012 |

---

# Roteiro de Homologação - Emissão de dívida PF com desembolso pagando QR Code

URL: /documentation/roteiros_laas/roteiro_00f2a5d3-39c2-4f3d-9234-7d1525daaaf2

`*: etapas obrigatórias para entrada em produção`

## 1 - Cadastro e Autenticação APIs LaaS
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
|---------|--|---|---|---|
| CAB0001* | Cadastro no ambiente de Sandbox | Realizar o cadastro na plataforma da QI Tech no ambiente de Sandbox (sandbox.qitech.app) | https://sandbox.qitech.com.br/register| |
| CAB0002* | Validação de token em Sandbox | Realizar a validação do QI Token em Sandbox | [Download Manual de Inclusão do Token](https://docs.qitech.com.br/assets/pdfs/QI%20Tech%20Manual%20Inclus%C3%A3o%20de%20Token.pdf) | CAB0001 |
| CAB0003* | Troca de chaves públicas | Realizar a troca de chaves públicas dentro da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Link Documentação](/documentation/primeiros_passos/troca_de_chaves) | CAB0001 e CAB0002 |
| CAB0004* | Teste de autenticação de chamadas | Finalizar teste de autenticação de chamadas | [Passo a Passo](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2) <br/><br/> [Link Documentação](/documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste) | CAB0003 |
| CAB0005* | Configuração de webhooks | Realizar a configuração da url para envio dos webhooks por parte da QI, através da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Link Documentação](/documentation/primeiros_passos/configurando_webhooks) | CAB0001 e CAB0002 |

## 2- Simulação da dívida

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| SID0001* | Simulação de dívida| Simulação das condições da dívida, utilizando variáveis previamente determinadas| [Link Documentação](/documentation/emissao_de_divida/simulacao_de_divida_novo) | **Item 1** |

## 3 - Emissão de dívida (PF)

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| EMD0001* | Emissão de dívida PF | Emissão da CCB PF. Formada por quatro objetos principais: dados cadastrais do devedor (objeto borrower), dados financeiros da operação (objeto financial), dados para desembolso via QR Code Pix e indicação do cessionário (purchaser_document_number)| [Link Documentação](/documentation/emissao_de_divida/emissao/emissao_de_divida_pf) | **Itens 1 e 2**  |
| EMD0002* | Implementação de dados adicionais | Dados para preenchimento da CCB gerada| Payload alinhado em paralelo | Obrigatório, se definido a utilização.  |

## 4 - Formalização de dívida 

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| FOR0001 | Formalização da dívida  | A assinatura da CCB será realizada via Opt-In após a emissão da dívida| -- |  **Item 3** |
| FOR0002* | Leitura do webhook de assinatura finalizada | Leitura da resposta assíncrona da formalização da operação. Webhook status signature_finished| [Link Documentação](/documentation/webhooks/dividas) | FOR0001 |

## 5 - Desembolso da dívida

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| DES0001* | Escolha da data de desembolso | Após o cumprimento de todos os requisitos para pagamento da operação (envio de documentos, assinatura e averbação), deve-se obrigatoriamente escolher uma data de desembolso para que a operação seja paga, dentro do range de desembolso.| [Link Documentação](/documentation/emissao_de_divida/reprocessar_multiplas_datas/trocar_data) |  **Item 4** |
| DES0002* | Autorização de desembolso | Flag de liberação do pagamento, impede que uma operação seja desembolsada ser estar previamente autorizada| [Link Documentação](/documentation/emissao_de_divida/autorizar_desembolso) |  DES0001 |
| DES0003* | Leitura do webhook de desembolso da operação | Leitura da resposta assíncrona que indica o sucesso no pagamento da operação. Webhook status: disbursed. Aqui teremos o comprovante de pagamento em PDF. Além do retorno das chaves identificadoras das parcelas e seus respectivos boletos| [Link Documentação](/documentation/webhooks/dividas) |  DES0001 e DES0002 |

## 6 -  Cancelamento da operação

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| CAN0002* | Cancelamento permanente da dívida antes do desembolso  |Permite o cancelamento definitivo (status final) da dívida antes do pagamento| [Link Documentação](/documentation/emissao_de_divida/cancelamento/cancelar_permanentemente) |  EMD0001 |
| CAN0003* | Leitura do webhook de cancelamento  |Leitura da resposta assíncrona do cancelamento da operação. Webhook status: canceled| [Link Documentação](/documentation/webhooks/dividas) |  CAN0002 |
| CAN0004 | Cancelamento de dívida em até sete dias após o desembolso  | Considerando que o tomador do crédito pode realizar o cancelamento da dívida em até 7 dias do desembolso, é possível que ele faça um chargeback do PIX recebido ou pagar um QR Code de devolução | [Link Documentação](/documentation/emissao_de_divida/cancelamento/desistencia/introducao) |  DES0002 |

---

# Roteiro de Homologação - Emissão de dívida PF - Adiantamento de Precatório

URL: /documentation/roteiros_laas/roteiro_5d068423-6094-49e4-b15b-7740038295a8

`*: etapas obrigatórias para entrada em produção`

## 1 - Cadastro e Autenticação APIs LaaS
| Código  | Etapa | Descrição | Link Documentação | Pré-requisito |
|---------|--|---|---|---|
| CAB0001* | Cadastro no ambiente de Sandbox | Realizar o cadastro na plataforma da QI Tech no ambiente de Sandbox (sandbox.qitech.app) | https://sandbox.qitech.com.br/register| |
| CAB0002* | Validação de token em Sandbox | Realizar a validação do QI Token em Sandbox | [Download Manual de Inclusão do Token](https://docs.qitech.com.br/assets/pdfs/QI%20Tech%20Manual%20Inclus%C3%A3o%20de%20Token.pdf) | CAB0001 |
| CAB0003* | Troca de chaves públicas | Realizar a troca de chaves públicas dentro da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Link Documentação](/documentation/primeiros_passos/troca_de_chaves) | CAB0001 e CAB0002 |
| CAB0004* | Teste de autenticação de chamadas | Finalizar teste de autenticação de chamadas | [Passo a Passo](/documentation/primeiros_passos/teste_de_autenticacao/teste_de_autenticacao_v2) <br/><br/> [Link Documentação](/documentation/primeiros_passos/teste_de_autenticacao/endpoints_de_teste) | CAB0003 |
| CAB0005* | Configuração de webhooks | Realizar a configuração da url para envio dos webhooks por parte da QI, através da plataforma da QI Tech em sandbox (sandbox.qitech.app) | [Link Documentação](/documentation/primeiros_passos/configurando_webhooks) | CAB0001 e CAB0002 |

## 2- Simulação da dívida

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| SID0001* | Simulação de dívida| Simulação das condições da dívida, utilizando variáveis previamente determinadas| [Link Documentação](/documentation/emissao_de_divida/simulacao_de_divida_novo) | **Item 1** |

## 3 - Emissão de dívida (PF)

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| EMD0001* | Emissão de dívida PF | Emissão da CCB PF. Formada por quatro objetos principais: dados cadastrais do devedor (objeto borrower), dados financeiros da operação (objeto financial), dados bancários para pagamento (disbursement_bank_account) e indicação do cessionário (purchaser_document_number)| [Link Documentação](/documentation/emissao_de_divida/emissao/emissao_de_divida_pf) | **Itens 1 e 2**  |
| EMD0002* | Implementação de dados adicionais | Dados para preenchimento da CCB gerada| Payload alinhado em paralelo | Obrigatório, se definido a utilização.  |

## 4 - Formalização de dívida 

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| FOR0001 | Formalização da dívida  | A assinatura da CCB será disparada automaticamente do lado da QI SCD via QI Sign, após a emissão da dívida| -- |  **Item 3** |
| FOR0002* | Leitura do webhook de assinatura finalizada | Leitura da resposta assíncrona da formalização da operação. Webhook status signature_finished| [Link Documentação](/documentation/webhooks/dividas) | FOR0001 |

## 5 - Desembolso da dívida

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| DES0001* | Escolha da data de desembolso | Após o cumprimento de todos os requisitos para pagamento da operação (envio de documentos, assinatura e averbação), deve-se obrigatoriamente escolher uma data de desembolso para que a operação seja paga, dentro do range de desembolso.| [Link Documentação](/documentation/emissao_de_divida/reprocessar_multiplas_datas/trocar_data) |  **Item 4** |
| DES0002* | Autorização de desembolso | Flag de liberação do pagamento, impede que uma operação seja desembolsada ser estar previamente autorizada| [Link Documentação](/documentation/emissao_de_divida/autorizar_desembolso) |  DES0001 |
| DES0003* | Leitura do webhook de desembolso da operação | Leitura da resposta assíncrona que indica o sucesso no pagamento da operação. Webhook status: disbursed. Aqui teremos o comprovante de pagamento em PDF. Além do retorno das chaves identificadoras das parcelas e seus respectivos boletos| [Link Documentação](/documentation/webhooks/dividas) |  DES0001 e DES0002 |

## 6 - Parcelas da dívida

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| INS0001* | Leitura do webhook de parcelas | Leitura da resposta assíncrona que indica a atualização de status das parcelas da dívida. Aqui temos webhook_type: installment.status_change. Webhook status: opened, paid, waiting_payment, paid_early, paid_partial, overdue, paid_partial_overdue e paid_overdue.| [Link Documentação](/documentation/webhooks/parcelas) |  DES0002 |

## 7 - Reapresentação da dívida

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PAG0001* | Alteração/atualização da data de desembolso| Quando uma operação está cancelada, a atualização da data de desembolso faz com que a operação volte ao status anterior ao cancelamento.| [Link Documentação](/documentation/emissao_de_divida/reprocessar_multiplas_datas/trocar_data) | **Item 5**   |
| PAG0002 | Alteração dos dados bancários | Mudança dos dados para pagamento da operação, obrigatório um conta de mesma titularidade do devedor| [Link Documentação](/documentation/emissao_de_divida/reprocessar_multiplas_datas/trocar_conta) |  PAG0001. Obrigatório, caso exista retentativa  |

## 8 -  Cancelamento da operação

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| CAN0002* | Cancelamento permanente da dívida antes do desembolso  |Permite o cancelamento definitivo (status final) da dívida antes do pagamento| [Link Documentação](/documentation/emissao_de_divida/cancelamento/cancelar_permanentemente) |  EMD0001 |
| CAN0003* | Leitura do webhook de cancelamento  |Leitura da resposta assíncrona do cancelamento da operação. Webhook status: canceled| [Link Documentação](/documentation/webhooks/dividas) |  CAN0002 |
| CAN0004 | Cancelamento de dívida em até sete dias após o desembolso  | Considerando que o tomador do crédito pode realizar o cancelamento da dívida em até 7 dias do desembolso, é possível que ele faça um chargeback do PIX recebido ou pagar um QR Code de devolução | [Link Documentação](/documentation/emissao_de_divida/cancelamento/desistencia/introducao) |  DES0002 |

## 9 - Boletos da dívida

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| BKS0001 | Solicitar 2ª via de boleto | Emissão de segunda via de boleto, através da chave identificadora do boleto (*bank_slip_key*), retornada no webhook de desembolso | [Link Documentação](/documentation/boletos/consultar/segunda_via_de_boleto) |  DES0002 |

## 10 - Renegociação de dívida

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| REN0001 | Simulação de uma renegociação  | Permite a simulação parcial ou total de uma renegociação  | [Link Documentação](/documentation/renegociacao/simulacao_de_uma_renegociacao) | DES0002 |
| REN0002 | Criar uma renegociação  | Permite a criação de uma renegociação parcial ou total (geração de um boleto de antecipação para pagamentos de parcelas) | [Link Documentação](/documentation/renegociacao/criacao_de_uma_renegociacao) |  DES0002 |
| REN0003 | Consultar uma renegociação  | Verificar as condições de uma renegociação, parcelas que foram afetadas, dados financeiros, vencimento e tipo de pagamento | [Link Documentação](/documentation/renegociacao/consultar_uma_renegociacao) | REN0002 |
| REN0004 | Listar Renegociações | Verificar uma listagem das condições de mais de uma renegociação | [Link Documentação](/documentation/renegociacao/consultar_uma_renegociacao) | REN0002 |
| REN0005 | Cancelar uma renegociação| Efetuar o cancelamento de uma renegociação | [Link Documentação](/documentation/renegociacao/cancelar_uma_renegociacao) | REN0002 |
| REN0006 | Pagamento de uma renegociação | Webhooks de atualização de status de uma renegociação. Webhook_type: renegotiation.proposal | [Link Documentação](/documentation/renegociacao/consultar_uma_renegociacao) | REN0002 |

## 11 - Pagamentos e Transferências

| Código | Etapa | Descrição | Link | Pré-requisito |
| --- | --- | --- | --- | --- |
| PGT0001 | Decodificar QR Code | Obtenção de dados para pagamento do QR Code de devolução, através da URI do Pix Copia e Cola  | [Link Documentação](/documentation/pix/decodificar_qr_code/index.html) |  CAN0004 |
| PGT0002 | Transferência por QR Code Pix |  Pagamento do QR Code, através das informações obtidas pela decodificação do QR Code para o cancelamento da dívida | [Link Documentação](/documentation/baas/pix/realizar_transferencia/index.html#transfer%C3%AAncia-por-qr-code-pix) |  PGT0001 |
| PGT0003 | Transferência via PIX |  Realizar um PIX para o tomador a partir da conta escrow  | [Link Documentação](/documentation/baas/pix/realizar_transferencia/index.html#transfer%C3%AAncia-por-qr-code-pix) |  DES0003 |
| PGT0004 | Aumento de limite de conta |  Solicitar aumento do limite PIX da escrow | [Link Documentação](/documentation/pix/solicitar_alteracao_de_limite_pix/index.html) |  DES0003 |
| PGT0005 | Transferência via TED |  Realizar uma TED para o tomador a partir da conta escrow  | [Link Documentação](/documentation/baas/ted/realizar_transferencia/index.html) |  DES0003 |

---

# Homologation Roadmap - Credit Pay

URL: /documentation/roteiros_laas/roteiro_cecdd0e2-081a-4590-b571-188c376a7c64

## Summary

## 1. Debt inquiry

You can query the debt later to retrieve information or track its current status:

### Request

ENDPOINT /v2/credit_operation/ REQUESTER-IDENTIFIER-KEY
METHOD GET

Test in Playground

### Path params

| Field  | Type   | Description | Max. Char. |
|---|---|---|---|   
| `requester_identifier_key` * | string |  Client tracking key for the request | UUID |

### Response

STATUS 200

Response Body

```json
{
   "credit_operation_key":"0773a1b1-675a-4a10-80a2-a10308c7281e",
   "issue_amount":15367.14,
   "origin_key":"0773a1b1-675a-4a10-80a2-a10308c7281e",
   "total_iof":367.14,
   "assigned_at":null,
   "disbursement_start_date":"2026-03-23",
   "disbursement_end_date":"2026-03-23",
   "issue_date":"2026-03-23",
   "requester_identifier_key":"494598fd200",
   "installments":[
      {
         "business_due_date":"2026-06-08",
         "due_date":"2026-06-06",
         "calendar_days":75,
         "due_interest":0,
         "due_principal":15367.14,
         "fine_amount":0,
         "has_interest":true,
         "post_fixed_amount":0,
         "pre_fixed_amount":2432.7,
         "principal_amortization_amount":0,
         "tax_amount":0,
         "total_amount":2432.7,
         "workdays":50,
         "accrual_reference_date":null,
         "advanced_paid_amount":0,
         "bank_slip_key":null,
         "digitable_line":null,
         "installment_key":"c0c716ca-1645-4cf6-bb6b-438a69693d79",
         "installment_status":"created",
         "installment_type":"principal",
         "original_due_principal":15367.14,
         "original_pre_fixed_amount":2432.7,
         "original_principal_amortization_amount":0,
         "paid_amount":0,
         "original_total_amount":2432.7,
         "qr_code_key":null,
         "qr_code_url":null,
         "renegotiation_proposal_key":null,
         "total_accrual_amount":0,
         "total_paid_amount":0,
         "installment_number":1,
         "paid_at":null,
         "updated_at":null,
         "principal_amortization_payment_amount":0,
         "prefixed_interest_payment_amount":0
      },
      {
         "business_due_date":"2026-07-06",
         "due_date":"2026-07-06",
         "calendar_days":30,
         "due_interest":399,
         "due_principal":15367.14,
         "fine_amount":0,
         "has_interest":true,
         "post_fixed_amount":0,
         "pre_fixed_amount":1503.02,
         "principal_amortization_amount":929.68,
         "tax_amount":8,
         "total_amount":2432.7,
         "workdays":21,
         "accrual_reference_date":null,
         "advanced_paid_amount":0,
         "bank_slip_key":null,
         "digitable_line":null,
         "installment_key":"46d7a106-004f-4f64-910c-bc9e2c010845",
         "installment_status":"created",
         "installment_type":"principal",
         "original_due_principal":15367.14,
         "original_pre_fixed_amount":1503.02,
         "original_principal_amortization_amount":929.68,
         "paid_amount":0,
         "original_total_amount":2432.7,
         "qr_code_key":null,
         "qr_code_url":null,
         "renegotiation_proposal_key":null,
         "total_accrual_amount":0,
         "total_paid_amount":0,
         "installment_number":2,
         "paid_at":null,
         "updated_at":null,
         "principal_amortization_payment_amount":0,
         "prefixed_interest_payment_amount":0
      },
      {
         "business_due_date":"2026-08-06",
         "due_date":"2026-08-06",
         "calendar_days":31,
         "due_interest":0,
         "due_principal":14437.46134964,
         "fine_amount":0,
         "has_interest":true,
         "post_fixed_amount":0,
         "pre_fixed_amount":1045.5,
         "principal_amortization_amount":1387.2,
         "tax_amount":15.47,
         "total_amount":2432.7,
         "workdays":23,
         "accrual_reference_date":null,
         "advanced_paid_amount":0,
         "bank_slip_key":null,
         "digitable_line":null,
         "installment_key":"af84c132-7311-412f-a5e4-a827047fda52",
         "installment_status":"created",
         "installment_type":"principal",
         "original_due_principal":14437.46,
         "original_pre_fixed_amount":1045.5,
         "original_principal_amortization_amount":1387.2,
         "paid_amount":0,
         "original_total_amount":2432.7,
         "qr_code_key":null,
         "qr_code_url":null,
         "renegotiation_proposal_key":null,
         "total_accrual_amount":0,
         "total_paid_amount":0,
         "installment_number":3,
         "paid_at":null,
         "updated_at":null,
         "principal_amortization_payment_amount":0,
         "prefixed_interest_payment_amount":0
      },
      {
         "business_due_date":"2026-09-08",
         "due_date":"2026-09-06",
         "calendar_days":31,
         "due_interest":0,
         "due_principal":13050.26167997,
         "fine_amount":0,
         "has_interest":true,
         "post_fixed_amount":0,
         "pre_fixed_amount":945.05,
         "principal_amortization_amount":1487.65,
         "tax_amount":20.37,
         "total_amount":2432.7,
         "workdays":21,
         "accrual_reference_date":null,
         "advanced_paid_amount":0,
         "bank_slip_key":null,
         "digitable_line":null,
         "installment_key":"8517161a-408a-400d-9a27-e4e54c87d9ec",
         "installment_status":"created",
         "installment_type":"principal",
         "original_due_principal":13050.26,
         "original_pre_fixed_amount":945.05,
         "original_principal_amortization_amount":1487.65,
         "paid_amount":0,
         "original_total_amount":2432.7,
         "qr_code_key":null,
         "qr_code_url":null,
         "renegotiation_proposal_key":null,
         "total_accrual_amount":0,
         "total_paid_amount":0,
         "installment_number":4,
         "paid_at":null,
         "updated_at":null,
         "principal_amortization_payment_amount":0,
         "prefixed_interest_payment_amount":0
      },
      {
         "business_due_date":"2026-10-06",
         "due_date":"2026-10-06",
         "calendar_days":30,
         "due_interest":0,
         "due_principal":11562.6067212,
         "fine_amount":0,
         "has_interest":true,
         "post_fixed_amount":0,
         "pre_fixed_amount":809.38,
         "principal_amortization_amount":1623.32,
         "tax_amount":26.22,
         "total_amount":2432.7,
         "workdays":21,
         "accrual_reference_date":null,
         "advanced_paid_amount":0,
         "bank_slip_key":null,
         "digitable_line":null,
         "installment_key":"8c14e19c-a70e-4b0b-b0b5-d655f6136537",
         "installment_status":"created",
         "installment_type":"principal",
         "original_due_principal":11562.61,
         "original_pre_fixed_amount":809.38,
         "original_principal_amortization_amount":1623.32,
         "paid_amount":0,
         "original_total_amount":2432.7,
         "qr_code_key":null,
         "qr_code_url":null,
         "renegotiation_proposal_key":null,
         "total_accrual_amount":0,
         "total_paid_amount":0,
         "installment_number":5,
         "paid_at":null,
         "updated_at":null,
         "principal_amortization_payment_amount":0,
         "prefixed_interest_payment_amount":0
      },
      {
         "business_due_date":"2026-11-06",
         "due_date":"2026-11-06",
         "calendar_days":31,
         "due_interest":0,
         "due_principal":9939.28802441,
         "fine_amount":0,
         "has_interest":true,
         "post_fixed_amount":0,
         "pre_fixed_amount":719.76,
         "principal_amortization_amount":1712.94,
         "tax_amount":32.03,
         "total_amount":2432.7,
         "workdays":21,
         "accrual_reference_date":null,
         "advanced_paid_amount":0,
         "bank_slip_key":null,
         "digitable_line":null,
         "installment_key":"4a880580-5873-4c12-8d32-3cf95b416417",
         "installment_status":"created",
         "installment_type":"principal",
         "original_due_principal":9939.29,
         "original_pre_fixed_amount":719.76,
         "original_principal_amortization_amount":1712.94,
         "paid_amount":0,
         "original_total_amount":2432.7,
         "qr_code_key":null,
         "qr_code_url":null,
         "renegotiation_proposal_key":null,
         "total_accrual_amount":0,
         "total_paid_amount":0,
         "installment_number":6,
         "paid_at":null,
         "updated_at":null,
         "principal_amortization_payment_amount":0,
         "prefixed_interest_payment_amount":0
      },
      {
         "business_due_date":"2026-12-07",
         "due_date":"2026-12-06",
         "calendar_days":30,
         "due_interest":0,
         "due_principal":8226.34916112,
         "fine_amount":0,
         "has_interest":true,
         "post_fixed_amount":0,
         "pre_fixed_amount":575.84,
         "principal_amortization_amount":1856.86,
         "tax_amount":39.28,
         "total_amount":2432.7,
         "workdays":19,
         "accrual_reference_date":null,
         "advanced_paid_amount":0,
         "bank_slip_key":null,
         "digitable_line":null,
         "installment_key":"94db881b-0054-4c73-b969-89c37c082f39",
         "installment_status":"created",
         "installment_type":"principal",
         "original_due_principal":8226.35,
         "original_pre_fixed_amount":575.84,
         "original_principal_amortization_amount":1856.86,
         "paid_amount":0,
         "original_total_amount":2432.7,
         "qr_code_key":null,
         "qr_code_url":null,
         "renegotiation_proposal_key":null,
         "total_accrual_amount":0,
         "total_paid_amount":0,
         "installment_number":7,
         "paid_at":null,
         "updated_at":null,
         "principal_amortization_payment_amount":0,
         "prefixed_interest_payment_amount":0
      },
      {
         "business_due_date":"2027-01-06",
         "due_date":"2027-01-06",
         "calendar_days":31,
         "due_interest":0,
         "due_principal":6369.49243064,
         "fine_amount":0,
         "has_interest":true,
         "post_fixed_amount":0,
         "pre_fixed_amount":461.25,
         "principal_amortization_amount":1971.45,
         "tax_amount":46.72,
         "total_amount":2432.7,
         "workdays":21,
         "accrual_reference_date":null,
         "advanced_paid_amount":0,
         "bank_slip_key":null,
         "digitable_line":null,
         "installment_key":"d32e9f02-426d-4861-ad5c-fe541d2a4b94",
         "installment_status":"created",
         "installment_type":"principal",
         "original_due_principal":6369.49,
         "original_pre_fixed_amount":461.25,
         "original_principal_amortization_amount":1971.45,
         "paid_amount":0,
         "original_total_amount":2432.7,
         "qr_code_key":null,
         "qr_code_url":null,
         "renegotiation_proposal_key":null,
         "total_accrual_amount":0,
         "total_paid_amount":0,
         "installment_number":8,
         "paid_at":null,
         "updated_at":null,
         "principal_amortization_payment_amount":0,
         "prefixed_interest_payment_amount":0
      },
      {
         "business_due_date":"2027-02-10",
         "due_date":"2027-02-06",
         "calendar_days":31,
         "due_interest":0,
         "due_principal":4398.04366699,
         "fine_amount":0,
         "has_interest":true,
         "post_fixed_amount":0,
         "pre_fixed_amount":318.49,
         "principal_amortization_amount":2114.21,
         "tax_amount":55.48,
         "total_amount":2432.7,
         "workdays":22,
         "accrual_reference_date":null,
         "advanced_paid_amount":0,
         "bank_slip_key":null,
         "digitable_line":null,
         "installment_key":"0c6ef3ba-6d82-45e4-9f3f-9f9a89207f68",
         "installment_status":"created",
         "installment_type":"principal",
         "original_due_principal":4398.04,
         "original_pre_fixed_amount":318.49,
         "original_principal_amortization_amount":2114.21,
         "paid_amount":0,
         "original_total_amount":2432.7,
         "qr_code_key":null,
         "qr_code_url":null,
         "renegotiation_proposal_key":null,
         "total_accrual_amount":0,
         "total_paid_amount":0,
         "installment_number":9,
         "paid_at":null,
         "updated_at":null,
         "principal_amortization_payment_amount":0,
         "prefixed_interest_payment_amount":0
      },
      {
         "business_due_date":"2027-03-08",
         "due_date":"2027-03-06",
         "calendar_days":28,
         "due_interest":0,
         "due_principal":2283.83070016,
         "fine_amount":0,
         "has_interest":true,
         "post_fixed_amount":0,
         "pre_fixed_amount":148.87,
         "principal_amortization_amount":2283.83,
         "tax_amount":65.17,
         "total_amount":2432.7,
         "workdays":18,
         "accrual_reference_date":null,
         "advanced_paid_amount":0,
         "bank_slip_key":null,
         "digitable_line":null,
         "installment_key":"470dd63a-89eb-4c6c-8cd6-f570d469aa35",
         "installment_status":"created",
         "installment_type":"principal",
         "original_due_principal":2283.83,
         "original_pre_fixed_amount":148.87,
         "original_principal_amortization_amount":2283.83,
         "paid_amount":0,
         "original_total_amount":2432.7,
         "qr_code_key":null,
         "qr_code_url":null,
         "renegotiation_proposal_key":null,
         "total_accrual_amount":0,
         "total_paid_amount":0,
         "installment_number":10,
         "paid_at":null,
         "updated_at":null,
         "principal_amortization_payment_amount":0,
         "prefixed_interest_payment_amount":0
      }
   ],
   "first_due_date":"2026-06-06",
   "requester_key":"3e69b448-9afb-4aef-9c0d-0a3059350d80",
   "original_total_iof":null,
   "contract_number":"ANT000000787",
   "credit_operation_status_enumerator":"waiting_signature",
   "operation_type_enumerator":"settlement_refinancing",
   "disbursement_date":"2026-03-23",
   "issuer_name":"Alan Mathison Turing",
   "issuer_document_number":"47003534819",
   "external_contract_fees":[
      {
         "amount_type":"absolute",
         "fee_amount":0,
         "tax_amount":0,
         "irrf_amount":0,
         "amount":0,
         "pis_amount":0,
         "amount_released":0,
         "fee_type":"tac",
         "cofins_amount":0,
         "csll_amount":0,
         "description":null,
         "net_fee_amount":0,
         "rebate_account":null
      }
   ],
   "cet":7.51,
   "annual_cet":138.34,
   "final_disbursement_amount":4885.12,
   "number_of_installments":10,
   "disbursement_issue_amount":15000,
   "prefixed_interest_rate":{
      "annual_rate":1.252191589,
      "daily_rate":0.0022578334,
      "interest_base":{
         "enumerator":"calendar_days",
         "year_days":360
      },
      "monthly_rate":0.07
   },
   "fine_configuration":{
      "contract_fine_rate":0.02,
      "fine_delay_rate":{
         "annual_rate":4.35025011,
         "daily_rate":0.0046696,
         "interest_base":{
            "enumerator":"calendar_days",
            "year_days":360
         },
         "monthly_rate":0.15
      }
   },
   "attached_documents":[
      {
         "document_key":"494598fd-c226-4332-a500-591ae3884673",
         "document_url":"https://storage.googleapis.com/sandbox-doc-api/documents/494598fd-c226-4332-a500-591ae3884673/3d684e68e7df4e557d0480d98e26be92.jpg",
         "signature_url":null,
         "document_type":"document_identification",
         "signature_required":false,
         "signed":false
      },
      {
         "document_key":"494598fd-c226-4332-a500-591ae3884673",
         "document_url":"https://storage.googleapis.com/sandbox-doc-api/documents/494598fd-c226-4332-a500-591ae3884673/3d684e68e7df4e557d0480d98e26be92.jpg",
         "signature_url":null,
         "document_type":"document_identification_back",
         "signature_required":false,
         "signed":false
      },
      {
         "document_key":"cb97f9f5-9b58-4a55-826f-8698f2b97230",
         "document_url":"https://storage.googleapis.com/sandbox-doc-api-private/documents/cb97f9f5-9b58-4a55-826f-8698f2b97230/CASTELLOBNPL-ALAN_MATHISON_TURING-CCB-ANT000000787-20260408055239.pdf",
         "signature_url":null,
         "document_type":"ccb_pre_price_days",
         "signature_required":true,
         "signed":false
      }
   ],
   "related_parties":[
      {
         "related_party_key":"70f0bc84-98e0-4d4c-9ea7-ed783746ba5c",
         "role_type":"issuer",
         "person_type":"natural",
         "name":"Alan Mathison Turing",
         "email":"",
         "individual_document_number":"47003534819"
      }
   ],
   "base_iof":308.75,
   "additional_iof":58.39,
   "assignment_amount":15444.19,
   "created_at":"2026-04-08T05:52:38Z",
   "total_prefixed_amount":8959.86
}
```

### Response example (refinancing — `refinanced_credit_operations`)

For a **refinancing** credit operation, the GET response includes **`operation_type_enumerator`**: **`settlement_refinancing`** and the array **`refinanced_credit_operations`**, which lists the prior operation(s) being settled by this new contract. The example below uses **`final_disbursement_amount`**: **`0`** (no cash payout to the borrower—the new operation is sized to settle the prior obligation); see the note on **`final_disbursement_amount`** in this section.

:::caution Homologation / sample data

The payload below is a **sandbox / homologation** sample. **UUIDs, contract numbers, monetary amounts, calendar dates, and document URLs** are **illustrative** only. In production, rely on the **field names and types**, not on these literal values.

:::

Response Body (refinancing)

```json
{
   "credit_operation_key":"7c106ebb-42b5-4f9d-afdb-d3cc7c7883d1",
   "issue_amount":101.81,
   "origin_key":"7c106ebb-42b5-4f9d-afdb-d3cc7c7883d1",
   "total_iof":0.91,
   "assigned_at":null,
   "disbursement_start_date":"2026-04-15",
   "disbursement_end_date":"2026-04-15",
   "issue_date":"2026-04-15",
   "requester_identifier_key":"7014211f-0d09-4db3-957a-c916903ec4d3",
   "installments":[
      {
         "business_due_date":"2026-05-15",
         "due_date":"2026-05-15",
         "calendar_days":30,
         "due_interest":0,
         "due_principal":101.81,
         "fine_amount":0,
         "has_interest":true,
         "post_fixed_amount":0,
         "pre_fixed_amount":8.14,
         "principal_amortization_amount":31.43,
         "tax_amount":0.08,
         "total_amount":39.57,
         "workdays":20,
         "accrual_reference_date":null,
         "advanced_paid_amount":0,
         "bank_slip_key":null,
         "digitable_line":null,
         "installment_key":"ffd81916-ce62-4b32-82b8-3c7cb7afde0a",
         "installment_status":"opened",
         "installment_type":"principal",
         "original_due_principal":101.81,
         "original_pre_fixed_amount":8.14,
         "original_principal_amortization_amount":31.43,
         "paid_amount":0,
         "original_total_amount":39.57,
         "qr_code_key":null,
         "qr_code_url":null,
         "renegotiation_proposal_key":null,
         "total_accrual_amount":0,
         "total_paid_amount":0,
         "installment_number":1,
         "paid_at":null,
         "updated_at":"2026-04-16T01:30:36",
         "principal_amortization_payment_amount":0,
         "prefixed_interest_payment_amount":0
      },
      {
         "business_due_date":"2026-06-15",
         "due_date":"2026-06-15",
         "calendar_days":31,
         "due_interest":0,
         "due_principal":70.38415074,
         "fine_amount":0,
         "has_interest":true,
         "post_fixed_amount":0,
         "pre_fixed_amount":5.83,
         "principal_amortization_amount":33.74,
         "tax_amount":0.17,
         "total_amount":39.57,
         "workdays":20,
         "accrual_reference_date":null,
         "advanced_paid_amount":0,
         "bank_slip_key":null,
         "digitable_line":null,
         "installment_key":"4b41315b-d685-4646-b57f-107c00bf36e0",
         "installment_status":"opened",
         "installment_type":"principal",
         "original_due_principal":70.38,
         "original_pre_fixed_amount":5.83,
         "original_principal_amortization_amount":33.74,
         "paid_amount":0,
         "original_total_amount":39.57,
         "qr_code_key":null,
         "qr_code_url":null,
         "renegotiation_proposal_key":null,
         "total_accrual_amount":0,
         "total_paid_amount":0,
         "installment_number":2,
         "paid_at":null,
         "updated_at":"2026-04-16T01:30:36",
         "principal_amortization_payment_amount":0,
         "prefixed_interest_payment_amount":0
      },
      {
         "business_due_date":"2026-07-15",
         "due_date":"2026-07-15",
         "calendar_days":30,
         "due_interest":0,
         "due_principal":36.63949004,
         "fine_amount":0,
         "has_interest":true,
         "post_fixed_amount":0,
         "pre_fixed_amount":2.93,
         "principal_amortization_amount":36.64,
         "tax_amount":0.27,
         "total_amount":39.57,
         "workdays":22,
         "accrual_reference_date":null,
         "advanced_paid_amount":0,
         "bank_slip_key":null,
         "digitable_line":null,
         "installment_key":"920af811-9d4c-4886-9095-73cc6f546f02",
         "installment_status":"opened",
         "installment_type":"principal",
         "original_due_principal":36.64,
         "original_pre_fixed_amount":2.93,
         "original_principal_amortization_amount":36.64,
         "paid_amount":0,
         "original_total_amount":39.57,
         "qr_code_key":null,
         "qr_code_url":null,
         "renegotiation_proposal_key":null,
         "total_accrual_amount":0,
         "total_paid_amount":0,
         "installment_number":3,
         "paid_at":null,
         "updated_at":"2026-04-16T01:30:36",
         "principal_amortization_payment_amount":0,
         "prefixed_interest_payment_amount":0
      }
   ],
   "first_due_date":"2026-05-15",
   "requester_key":"3e69b448-9afb-4aef-9c0d-0a3059350d80",
   "original_total_iof":null,
   "contract_number":"0000667215/NDR",
   "credit_operation_status_enumerator":"opened",
   "operation_type_enumerator":"settlement_refinancing",
   "disbursement_date":"2026-04-15",
   "issuer_name":"NOME DO REPRESENTANTE",
   "issuer_document_number":"31057466093",
   "external_contract_fees":[
      {
         "amount_type":"absolute",
         "fee_amount":0,
         "tax_amount":0,
         "irrf_amount":0,
         "amount":0,
         "pis_amount":0,
         "amount_released":0,
         "fee_type":"tac",
         "cofins_amount":0,
         "csll_amount":0,
         "description":null,
         "net_fee_amount":0,
         "rebate_account":null
      }
   ],
   "cet":8.62,
   "annual_cet":169.6,
   "final_disbursement_amount":0,
   "number_of_installments":3,
   "disbursement_issue_amount":100.9,
   "prefixed_interest_rate":{
      "annual_rate":1.5181701168,
      "daily_rate":0.0025686614,
      "interest_base":{
         "enumerator":"calendar_days",
         "year_days":360
      },
      "monthly_rate":0.08
   },
   "fine_configuration":{
      "contract_fine_rate":0.02,
      "fine_delay_rate":{
         "annual_rate":0.12682503,
         "daily_rate":0.00032719,
         "interest_base":{
            "enumerator":"calendar_days_365",
            "year_days":365
         },
         "monthly_rate":0.01
      }
   },
   "attached_documents":[
      {
         "document_key":"a3749ce5-750a-4a1a-a22c-5966e9d13885",
         "document_url":"https://storage.googleapis.com/sandbox-doc-api-private/documents/a3749ce5-750a-4a1a-a22c-5966e9d13885/CASTELLOBNPL-NOME_DO_REPRESENTANTE-CCB-0000667215-20260416013033.pdf",
         "signature_url":"https://storage.googleapis.com/sandbox-doc-api-private/documents/a3749ce5-750a-4a1a-a22c-5966e9d13885/CASTELLOBNPL-NOME_DO_REPRESENTANTE-CCB-0000667215-20260416013033_signed.pdf",
         "document_type":"ccb_pre_price_days",
         "signature_required":true,
         "signed":true
      }
   ],
   "related_parties":[
      {
         "related_party_key":"bb7ab0e0-04f5-4814-901f-e44a6eb0b243",
         "role_type":"issuer",
         "person_type":"natural",
         "name":"NOME DO REPRESENTANTE",
         "email":"2210@test.com",
         "individual_document_number":"31057466093"
      }
   ],
   "base_iof":0.52,
   "additional_iof":0.39,
   "assignment_amount":102.42,
   "created_at":"2026-04-16T01:30:33Z",
   "total_prefixed_amount":16.9,
   "refinanced_credit_operations":[
      {
         "refinanced_credit_operation_key":"a0c66c34-404a-4391-b0d1-7c109329b808",
         "refinanced_contract_number":"0000667214/NDR",
         "due_balance":100.9,
         "due_balance_reference_date":"2026-04-15",
         "original_deadline":91,
         "refinanced_credit_operation_status_enumerator":"pending_payment",
         "updated_at":"2026-04-16T01:30:33",
         "created_at":"2026-04-16T01:30:33"
      }
   ]
}
```

:::info **`refinanced_credit_operations`**

Each object describes a **prior** credit operation included in this refinancing: **`refinanced_credit_operation_key`** and **`refinanced_contract_number`** identify it; **`due_balance`** and **`due_balance_reference_date`** are the payoff context used when structuring the new contract; **`refinanced_credit_operation_status_enumerator`** is the status of that **refinanced** operation at the time of the inquiry (not necessarily the new operation’s status). **`original_deadline`** refers to the prior operation’s term where applicable.

:::

:::info **`business_due_date`** (installments)

In each object under **`installments[]`**, pay attention to **`business_due_date`**: it is the installment due date on the **business-day** calendar (working / banking days). It may match **`due_date`** or differ when the natural calendar date falls on a non-business day—use both fields together when reconciling schedules and cut-offs.
:::

:::info **`operation_type_enumerator`**

When **`operation_type_enumerator`** is **`settlement_refinancing`**, the credit operation is a **refinancing** debt—that is, it is issued under the refinancing flow (settling prior credit operations). Use this field to distinguish refinancing debts from other operation types.
:::

:::info **`final_disbursement_amount`**

**`final_disbursement_amount`** is the effective disbursement of the new credit operation. When there is **no** net amount paid to the borrower (no cash payout from the new loan), the platform **does not** rely on a separately informed disbursement: it **computes the due balance** (payoff) of the refinanced loan(s), and **that amount is used as the disbursed amount of the new loan**—the new operation is sized to settle the prior obligation.
:::

## 2. Renegotiation — Batch simulation

### Overview

Before creating a proposal, you can simulate batch renegotiation values for operations. The simulation shows affected installments, discounts, and the total amount due across multiple operations.

When **`amortization_type`** is **`present_amount`**, send only **`installment_key`** on each installment in `operations[].installments[]` for simulation. Per-installment **`paid_amount`** and **`discount_amount`** are **not** used on **`batch_proposal_simulation`**—they are required on **`POST /renegotiation/batch_proposal`** (see §3).

:::caution Attention
Batch renegotiation can only include operations from the same issuer and the same integration key. There is a limit of **50 operations** per batch renegotiation.
:::

### Request

ENDPOINT /renegotiation/batch_proposal_simulation
METHOD POST

:::warning Warning
The `discount_amount` and `discount_percentage` fields must **not** be sent together in the same payload (root level).
:::

:::info Note
At the root, `discount_amount` and `discount_percentage` are mutually exclusive global discount options for the simulation payload. Per-installment **`paid_amount`** and **`discount_amount`** are documented under **`POST /renegotiation/batch_proposal`** only.
:::

Request Body

```json
{
    "amortization_type": "present_amount",
    "reference_date": "2026-04-08",
    "discount_percentage": 0.0,
    "operations": [
        {
            "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
            "installments": [
                {
                    "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88"
                }
            ]
        },
        {
            "debt_key": "2cbfb9b1-1fdb-5f8d-9967-b338e5eb83f9",
            "installments": [
                {
                    "installment_key": "2ef25ed8-7124-44f5-9e3d-1d1a7196166e"
                }
            ]
        }
    ]
}
```

### Response

Example response ( batch_proposal_simulation )

```json
{
    "batch_proposal_key": "429fd784-e13e-47a1-ad9f-291209e0e621",
    "discount_percentage": 0,
    "discount_amount": 20,
    "amortization_type": "present_amount",
    "payment_amount": 78389.55,
    "requester_name": "Castello  (BNPL)",
    "requester_key": "3e69b448-9afb-4aef-9c0d-0a3059350d80",
    "issuer_name": "Alan Mathison Turing",
    "reference_date": "2026-04-11",
    "issuer_document_number": "82744088021",
    "operations": [
        {
            "requester_key": "3e69b448-9afb-4aef-9c0d-0a3059350d80",
            "contract_number": "TEST00790",
            "payment_amount": 78389.55,
            "discount_amount": 20,
            "origin_key": null,
            "affected_installments": [
                {
                    "installment_key": "24b5deae-304e-4773-9b25-e42dbd450241",
                    "due_date": "2026-05-10",
                    "principal_amount": 73107.75725415,
                    "interest_amount": 10580.11274585,
                    "fine_amount": 0,
                    "total_amount": 83687.87,
                    "present_amount": 78389.55,
                    "paid_amount": 78389.55,
                    "principal_amortization_payment_amount": 78048.3,
                    "prefixed_interest_payment_amount": 341.25,
                    "fine_payment_amount": 0,
                    "discount_amount": 0
                }
            ],
            "remaining_installments": [
                {
                    "installment_key": "2b1d9423-4dab-44b3-bf8c-efc8433176dd",
                    "due_date": "2026-06-10",
                    "principal_amount": 73096.23,
                    "interest_amount": 10591.64,
                    "fine_amount": 0,
                    "total_amount": 83687.87
                }
            ],
            "debt_key": "388c47fa-6c6c-4d2b-8f00-ccc2d571fcb0"
        }
    ]
}
```

### Body parameters

| Field | Type | Description | Max length |
|---|---|---|---|
| `amortization_type`* | string | Amortization type | **[Amortization type values](#enumeradores-amortization-type)** |
| `reference_date`* | string | Reference date for present value (must be D+1) | 10 |
| `discount_percentage` | float | Discount percentage on present value ((1 − percentage) × present value) | 10 |
| `discount_amount` | float | Discount amount on present value | 10 |
| `force_due_date` | boolean | Optional. When `true`, installments whose `reference_date` falls within the shift window `[due_date, business_due_date]` (`business_due_date > due_date`, e.g. weekend/holiday rollover) are priced at face value using the installment's own `due_date` as reference — no accrued interest, no delay fine. Default `false`. See **[Force due date behavior](#force-due-date-behavior)**. | — |
| `operations`* | array | Operations to renegotiate | **[Operations object](#objeto-operations)** |

### Operations object

| Field | Type | Description | Max length |
|---|---|---|---|
| `debt_key`* | string | Unique credit operation key (DEBT-KEY) | UUID |
| `installments`* | array | Installments to renegotiate | **[Installments object](#objeto-installments)** |

### Installments object

| Field | Type | Description | Max length |
|---|---|---|---|
| `installment_key`* | string | Installment key | UUID |

### Amortization type values

| Value | Description |
|---|---|
| **present_amount** | Simulation with present value per installment: each `installments[]` entry includes **`installment_key`** only. **`paid_amount`** / **`discount_amount`** are not sent on this endpoint—use **`batch_proposal`** for those fields. |

### Force due date behavior {#force-due-date-behavior}

When `force_due_date` is `true`, the API applies a shift-window rule to each installment:

- If `business_due_date > due_date` (i.e. there is a weekend/holiday rollover) **and** `reference_date` falls within `[due_date, business_due_date]`, the installment is treated as **not yet due** and priced at face value using its own `due_date` as reference. Interest does not accrue for the days between `due_date` and `reference_date`, and no delay fine is charged.
- Otherwise (no shift, or `reference_date` outside the window) the installment behaves as usual (overdue or not overdue).

Typical use case: the client wants to pay on Sunday installments that fell on Saturday. Without the flag, one day of interest accrues; with the flag, only the face value is charged. The flag is opt-in and defaults to `false` — omitting it preserves the current behavior.

## 3. Renegotiation — Batch proposal

### Overview

After simulating values, you can create a batch renegotiation proposal for multiple operations. The proposal generates a single payment method (bank slip and/or Pix) covering all operations in the batch.

For amortization type **`present_amount`**, each installment listed under `operations[].installments[]` must include **`paid_amount`** (amount paid or allocated for that installment), **`discount_amount`** (discount in BRL applied to the installment), and **`installment_key`**.

:::caution Attention
Batch renegotiation can only include operations from the same issuer and the same integration key. There is a limit of **50 operations** per batch renegotiation.
:::

### Request

ENDPOINT /renegotiation/batch_proposal
METHOD POST

### Paid amount and discount amount (installments) {#installment-paid-discount-proposal}

For **`POST /renegotiation/batch_proposal`** only: when **`amortization_type`** is **`present_amount`**, each object in `operations[].installments[]` must include these fields (in addition to **`installment_key`**):

| Field | Type | Description | Max length |
|---|---|---|---|
| **`paid_amount`** | float | Amount paid or allocated on that installment (BRL). Required when **`amortization_type`** is **`present_amount`**. | 15,2 |
| **`discount_amount`** | float | Discount in BRL applied to that installment. Required when **`amortization_type`** is **`present_amount`**; use **`0`** if there is no discount. Optional per installment for other amortization types, when applicable. | 15,2 |

:::warning Warning
The `discount_amount` and `discount_percentage` fields must **not** be sent together in the same payload (root level).
:::

:::info Note
At the root of the body, `discount_amount` and `discount_percentage` are mutually exclusive options for a global discount on the present value. The **`paid_amount`** and **`discount_amount`** fields inside each object in `operations[].installments[]` define the per-installment composition when `amortization_type` is **`present_amount`** (they are required in this mode and do not conflict with the root-level rule).
:::

Request Body

```json
{
    "amortization_type": "present_amount",
    "reference_date": "2026-04-08",
    "proposal_due_date": "2026-04-15",
    "discount_percentage": 0.0,
    "payment_type": "pix",
    "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db",
    "operations": [
        {
            "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
            "installments": [
                {
                    "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88",
                    "paid_amount": 500,
                    "discount_amount": 50
                }
            ]
        },
        {
            "debt_key": "2cbfb9b1-1fdb-5f8d-9967-b338e5eb83f9",
            "installments": [
                {
                    "installment_key": "2ef25ed8-7124-44f5-9e3d-1d1a7196166e",
                    "paid_amount": 150,
                    "discount_amount": 10
                }
            ]
        }
    ]
}
```

### Response

STATUS 200

Example response body ( batch_proposal )

```json
{
    "batch_proposal_key": "37879d40-c16e-4d7f-a16f-d79d20c50d42",
    "discount_percentage": 0,
    "discount_amount": 20,
    "amortization_type": "present_amount",
    "payment_amount": 78206.27,
    "requester_name": "Castello  (BNPL)",
    "requester_key": "3e69b448-9afb-4aef-9c0d-0a3059350d80",
    "issuer_name": "Alan Mathison Turing",
    "reference_date": "2026-04-11",
    "issuer_document_number": "82744088021",
    "batch_proposal_status": "pending_payment",
    "proposal_due_date": "2026-04-11",
    "payment_type": "pix",
    "request_control_key": "37879d40-c16e-4d7f-a16f-d79d20c50d42",
    "origin_key": null,
    "operations": [
        {
            "requester_key": "3e69b448-9afb-4aef-9c0d-0a3059350d80",
            "contract_number": "TEST1570594223",
            "payment_amount": 78206.27,
            "discount_amount": 20,
            "origin_key": null,
            "affected_installments": [
                {
                    "installment_key": "1162e382-8bd6-4c0b-9111-8390d9794102",
                    "due_date": "2026-05-10",
                    "principal_amount": 73277.29,
                    "interest_amount": 10214.91,
                    "fine_amount": 0,
                    "total_amount": 83492.2,
                    "present_amount": 78206.27,
                    "paid_amount": 78206.27,
                    "principal_amortization_payment_amount": 78206.27,
                    "prefixed_interest_payment_amount": 0,
                    "fine_payment_amount": 0,
                    "discount_amount": 0
                }
            ],
            "remaining_installments": [
                {
                    "installment_key": "58eea645-5682-440d-aa6b-a3b124253684",
                    "due_date": "2026-06-10",
                    "principal_amount": 72925.33,
                    "interest_amount": 10566.87,
                    "fine_amount": 0,
                    "total_amount": 83492.2
                }
            ],
            "debt_key": "6564493d-75c3-4efe-9f11-82fa5cff9a78"
        }
    ],
    "payment": {
        "digitable_line": null,
        "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/426661142f5d4cd9954dcae3725d020d5204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***6304B878",
        "qr_code_key": "42666114-2f5d-4cd9-954d-cae3725d020d",
        "bank_slip_key": null,
        "paid_method_type": "pix",
        "source_account_key": null,
        "payment_data": {
            "creditor_bank_account_key": "6108dd45-580d-48c4-b3bb-74c1e843be49",
            "batch_renegotiation_proposal_key": "37879d40-c16e-4d7f-a16f-d79d20c50d42"
        }
    }
}
```

### Body parameters

| Field | Type | Description | Max length |
|---|---|---|---|
| `amortization_type`* | string | Amortization type | **[Amortization type values](#enumeradores-amortization-type)** |
| `reference_date`* | string | Reference date for present value calculation (D+1) | 10 |
| `proposal_due_date`* | string | Renegotiation proposal due date | 10 |
| `payment_type`* | string | Payment type | **[Payment type values](#enumeradores-payment-type)** |
| `request_control_key` | string | Optional control key for tracking and unique identification | UUID |
| `discount_percentage` | float | Discount percentage on present value | 10 |
| `discount_amount` | float | Discount amount on present value | 10 |
| `force_due_date` | boolean | Optional. When `true`, installments in the shift window `[due_date, business_due_date]` (`business_due_date > due_date`) are charged at face value using their own `due_date` as reference — no accrued interest, no delay fine. Default `false`. See **[Force due date behavior](#force-due-date-behavior)**. | — |
| `operations`* | array | Operations to renegotiate | **[Operations object](#objeto-operations)** |

### Operations object {#objeto-operations}

| Field | Type | Description | Max length |
|---|---|---|---|
| `debt_key`* | string | Unique credit operation key (DEBT-KEY) | UUID |
| `installments`* | array | Installments to renegotiate | **[Installments object](#objeto-installments)** |

### Installments object {#objeto-installments}

| Field | Type | Description | Max length |
|---|---|---|---|
| `installment_key`* | string | Installment key | UUID |
| `paid_amount` | float | Required for **`present_amount`**. See **[Paid amount and discount amount](#installment-paid-discount-proposal)**. | 15,2 |
| `discount_amount` | float | Required for **`present_amount`**. See **[Paid amount and discount amount](#installment-paid-discount-proposal)**. | 15,2 |

### Payment type values {#enumeradores-payment-type}

| Value | Description |
|---|---|
| `bank_slip` | Bank slip (generates slip and Pix) |
| `pix` | Pix only |
| `internal` | Internal transfer (automatic processing) |
| `manual` | Manual payment (no payment method generated) |

### Amortization type values {#enumeradores-amortization-type}

| Value | Description |
|---|---|
| **present_amount** | Present value per installment. Each `installments[]` item must include `installment_key`, **`paid_amount`**, and **`discount_amount`**. |

## 4. Renegotiation — Delete batch proposal

### Overview

**`DELETE /renegotiation/batch_proposal/{request_control_key}`** cancels or deletes a **batch** renegotiation proposal that is **not** finalized or is still in a **cancellable** state. The proposal is marked canceled/deleted and any associated payment methods (bank slip, Pix, etc.) are invalidated.

Pass the same **`request_control_key`** you used when creating the batch with **`POST /renegotiation/batch_proposal`** (optional field on the create payload). If your integration maps this route to another identifier, follow your contract; the path parameter name in the API is **`request_control_key`**.

### Request

ENDPOINT /renegotiation/batch_proposal/{'{request_control_key}'}
METHOD DELETE

### Response

STATUS 200

Example response body

```json
{}
```

## 5. Refinancing simulation

### Request

ENDPOINT /debt_simulation
METHOD POST

Request Body

```json
{
  "borrower": {
    "person_type": "natural"
  },
  "refinanced_credit_operations": [
    {
      "operation_key": "89b5c27e-b291-4414-abb0-f5f15c06c82b"
    }
  ],
  "financial": {
    "final_disbursement_amount": 0,
    "disbursement_amount": 0,
    "interest_type": "pre_price_days",
    "credit_operation_type": "ccb",
    "annual_interest_rate": 2.32,
    "disbursement_date": "2023-04-01",
    "first_due_date": "2023-05-01",
    "interest_grace_period": 0,
    "principal_grace_period": 0,
    "number_of_installments": 2,
    "fine_configuration": {
      "contract_fine_rate": 0.02,
      "interest_base": "calendar_days",
      "monthly_rate": 0.01
    }
  }
}
```

:::info **`final_disbursement_amount`** (`financial`)

You may send **`final_disbursement_amount`** as **`0`** when you are **not** specifying a cash disbursement to the borrower. In that case, the simulation derives the **disbursed amount of the new loan** from the **due balance** (payoff) of the refinanced operation(s)—the same rule as in **[debt inquiry](#1-debt-inquiry)** for **`final_disbursement_amount`**: the new credit is sized from what is owed on the previous loan(s), not from a user-defined payout amount.
:::

:::caution Attention

Send **`borrower`**, **`financial`**, and **`refinanced_credit_operations`** with **`operation_key`** for each operation to refinance. See **[Definitions (refinancing simulation)](#definitions-refinancing-simulation)**.
:::

### Response

STATUS 200

Response Body

```json
{
   "type":"debt",
   "key":"938351f9-511c-4ccb-9e09-35ebc8f1af2f",
   "status":"finished",
   "event_datetime":"2026-04-09 03:21:09",
   "data":{
      "interest_type":"pre_price_days",
      "credit_operation_type":"ccb",
      "interest_grace_period":0,
      "interest_payment_month_period":1,
      "principal_grace_period":0,
      "principal_amortization_month_period":1,
      "operation_type":"settlement_refinancing",
      "post_fixed_interest_base":"workdays",
      "post_fixed_interest_rate":null,
      "prefixed_interest_rate":{
         "interest_base":"calendar_days_365",
         "annual_rate":2.32,
         "monthly_rate":0.1051676747,
         "daily_rate":0.0032929847
      },
      "issue_date":"2023-04-01",
      "number_of_installments":2,
      "requester_key":"3e69b448-9afb-4aef-9c0d-0a3059350d80",
      "final_disbursement_amount":0,
      "refinanced_credit_operations":[
         {
            "refinanced_credit_operation_key":"89b5c27e-b291-4414-abb0-f5f15c06c82b",
            "refinanced_credit_operation_status":"pending_payment",
            "due_balance":15114.45,
            "due_balance_reference_date":"2023-04-01",
            "original_deadline":61
         }
      ],
      "total_pre_fixed_amount":2434.45,
      "iof_amount":115.62,
      "cet":0.1109,
      "annual_cet":2.5332,
      "disbursement_date":"2023-04-01",
      "installments":[
         {
            "calendar_days":30,
            "workdays":18,
            "business_due_date":"2023-05-02",
            "due_date":"2023-05-01",
            "due_principal":15230.07,
            "has_interest":true,
            "post_fixed_amount":0,
            "pre_fixed_amount":1578.66550979,
            "tax_amount":17.84384245,
            "total_amount":8832.26,
            "principal_amortization_amount":7253.59449021,
            "installment_number":1
         },
         {
            "calendar_days":31,
            "workdays":23,
            "business_due_date":"2023-06-01",
            "due_date":"2023-06-01",
            "due_principal":7976.47550979,
            "has_interest":true,
            "post_fixed_amount":0,
            "pre_fixed_amount":855.78449021,
            "tax_amount":39.8983305,
            "total_amount":8832.26,
            "principal_amortization_amount":7976.47550979,
            "installment_number":2
         }
      ],
      "external_contract_fees":[
         {
            "fee_type":"tac",
            "amount_type":"absolute",
            "amount":0,
            "fee_amount":0,
            "tax_amount":0,
            "net_fee_amount":0,
            "csll_amount":0,
            "irrf_amount":0,
            "pis_amount":0,
            "cofins_amount":0,
            "amount_released":0,
            "description":null
         }
      ],
      "contract_fee_amount":45.69,
      "external_contract_fee_amount":0,
      "net_external_contract_fee_amount":0,
      "contract_fees":[
         {
            "fee_type":"spread",
            "amount_type":"percentage",
            "amount":0.3,
            "fee_amount":45.69
         }
      ],
      "issue_amount":15230.07,
      "disbursed_issue_amount":15114.45,
      "assignment_amount":15275.76,
      "disbursement_options":[
         {
            "iof_amount":115.62,
            "total_pre_fixed_amount":2434.45,
            "cet":0.1109,
            "annual_cet":2.5332,
            "contract_fees":[
               {
                  "fee_type":"spread",
                  "amount_type":"percentage",
                  "amount":0.3,
                  "fee_amount":45.69
               }
            ],
            "external_contract_fees":[
               {
                  "fee_type":"tac",
                  "amount_type":"absolute",
                  "amount":0,
                  "fee_amount":0,
                  "tax_amount":0,
                  "net_fee_amount":0,
                  "csll_amount":0,
                  "irrf_amount":0,
                  "pis_amount":0,
                  "cofins_amount":0,
                  "amount_released":0,
                  "description":null
               }
            ],
            "contract_fee_amount":45.69,
            "external_contract_fee_amount":0,
            "net_external_contract_fee_amount":0,
            "disbursement_date":"2023-04-01",
            "first_due_date":"2023-05-01",
            "installments":[
               {
                  "calendar_days":30,
                  "workdays":18,
                  "business_due_date":"2023-05-02",
                  "due_date":"2023-05-01",
                  "due_principal":15230.07,
                  "has_interest":true,
                  "post_fixed_amount":0,
                  "pre_fixed_amount":1578.66550979,
                  "tax_amount":17.84384245,
                  "total_amount":8832.26,
                  "principal_amortization_amount":7253.59449021,
                  "installment_number":1
               },
               {
                  "calendar_days":31,
                  "workdays":23,
                  "business_due_date":"2023-06-01",
                  "due_date":"2023-06-01",
                  "due_principal":7976.47550979,
                  "has_interest":true,
                  "post_fixed_amount":0,
                  "pre_fixed_amount":855.78449021,
                  "tax_amount":39.8983305,
                  "total_amount":8832.26,
                  "principal_amortization_amount":7976.47550979,
                  "installment_number":2
               }
            ],
            "issue_amount":15230.07,
            "disbursed_issue_amount":15114.45,
            "assignment_amount":15275.76,
            "final_disbursement_amount":0,
            "prefixed_interest_rate":{
               "interest_base":"calendar_days_365",
               "annual_rate":2.32,
               "monthly_rate":0.1051676747,
               "daily_rate":0.0032929847
            },
            "refinanced_credit_operations":[
               {
                  "refinanced_credit_operation_key":"89b5c27e-b291-4414-abb0-f5f15c06c82b",
                  "refinanced_credit_operation_status":"pending_payment",
                  "due_balance":15114.45,
                  "due_balance_reference_date":"2023-04-01",
                  "original_deadline":61
               }
            ]
         }
      ]
   }
}
```

## Definitions (refinancing simulation)

### Request body
| Field | Type | Description |
|-------|------|-------------|
| **borrower** * | object | **[Borrower object](#objeto-borrower)** — Borrower of the simulated operation |
| **refinanced_credit_operations** * | array | **[Refinanced credit operations](#refinanced-credit-operations-object)** — Operations to refinance |
| **financial** * | object | **[Financial object](#objeto-financial)** — Terms of the new operation |

### Borrower object {#objeto-borrower}
| Field | Type | Description |
|-------|------|-------------|
| **person_type** | string | **[Person type](#enumerador-person_type)** — `natural` or `legal` |

### Financial object {#objeto-financial}
| Field | Type | Description |
|-------|------|-------------|
| **final_disbursement_amount** | float | Effective disbursement of the new operation (when not a cash payout to the borrower, sizing follows due balance of refinanced loan(s)—see §1 and §5). |
| **interest_type** | enum | **[Interest type](#enumerador-interest-type)** — Amortization and interest calculation |
| **credit_operation_type** | enum | **[Credit operation type](#enumerador-credit-operation-type)** — Agreement type (e.g. CCB) |
| **annual_interest_rate** | float | Annual prefixed interest rate (decimal) |
| **disbursement_date** | date | Disbursement date (`YYYY-MM-DD`) |
| **interest_grace_period** | int | Interest grace period (months) |
| **principal_grace_period** | int | Principal grace period (months) |
| **number_of_installments** | int | Number of installments |
| **fine_configuration** | object | **[Fine configuration object](#objeto-fine-configuration)** — Late interest and penalty |

### Refinanced credit operations object {#refinanced-credit-operations-object}

| Field | Type | Description |
|-------|------|-------------|
| **operation_key** | string (UUID) | Credit operation key to settle with this refinancing |

### Fine configuration object {#objeto-fine-configuration}
| Field                  | Type  | Description                                                                            | 
|------------------------|-------|--------------------------------------------------------------------------------------|
| **contract_fine_rate** | float | Late penalty rate as a decimal                                   |
| **interest_base**      | enum  | **[Interest base](#enumerador-interest-base)** — Interest calculation basis |
| **monthly_rate**       | float | Monthly late interest rate as a decimal                             |

## 6. Standard loan (normal flow) — POST /signed_debt {#standard-loan-post-signed-debt}

Standard issuance uses **`POST /signed_debt`** **without** **`refinanced_credit_operations`**. The **`financial`** object carries the disbursed principal via **`disbursed_amount`** (cash payout to the borrower). Field shapes for **`borrower`**, **`additional_data.contract`** (opt-in signatures), **`disbursement_bank_accounts`**, and other objects follow the same definitions as in **[§7. Creating a refinancing](#creating-a-refinancing)**—omit **`refinanced_credit_operations`** and use **`disbursed_amount`** instead of sizing from refinanced operations.

### Request

ENDPOINT /signed_debt
METHOD POST

Test in Playground

Request Body

```json
{
    "additional_data": {
        "contract": {
            "contract_number": null,
            "signed": true,
            "signatures": [
                {
                    "signer": {
                        "name": "Alan Mathison Turing",
                        "phone": {
                            "number": "912345678",
                            "area_code": "11",
                            "country_code": "055"
                        },
                        "email": "alan.turing@email.com",
                        "document_number": "96969879003"
                    },
                    "signature": {
                        "ip_address": "168.211.22.84",
                        "timestamp": "27-10-2025 11:07:15",
                        "signature_file": {
                            "file_url": "http://qitech.com.br/signature.pdf",
                            "file_type": "pdf"
                        },
                        "geolocation": {
                            "long": "-46.63611",
                            "lat": "-23.5475"
                        },
                        "fingerprint_device": null
                    }
                }
            ]
        }
    },
    "financial": {
        "number_of_installments": 2,
        "credit_operation_type": "ccb",
        "interest_type": "pre_price_days",
        "monthly_interest_rate": 0.07,
        "disbursed_amount": 150000,
        "fine_configuration": {
            "contract_fine_rate": 0.02,
            "monthly_rate": 0.15,
            "interest_base": "calendar_days"
        },
        "interest_grace_period": 0,
        "disbursement_date": "2026-04-11",
        "first_due_date": "2026-05-10",
        "principal_grace_period": 0
    },
    "purchaser_document_number": "32402502000135",
    "requester_identifier_key": null,
    "document_template_key": "518a0b57-2ce3-4309-94e5-6a95bc056d12",
    "borrower": {
        "email": "",
        "document_identification": "494598fd-c226-4332-a500-591ae3884673",
        "document_identification_back": "494598fd-c226-4332-a500-591ae3884673",
        "birth_date": "1998-06-03",
        "person_type": "natural",
        "is_pep": false,
        "mother_name": "Mother's full name",
        "profession": "Public server",
        "individual_document_number": "82744088021",
        "address": {
            "city": "São Paulo",
            "neighborhood": "CENTRO",
            "street": "Avenida Feliz",
            "complement": "",
            "postal_code": "49026100",
            "state": "SP",
            "number": ""
        },
        "phone": {
            "country_code": "055",
            "number": "912345678",
            "area_code": "11"
        },
        "document_identification_number": "47003534819",
        "name": "Alan Mathison Turing"
    },
    "disbursement_bank_accounts": [
        {
            "name": "NOME DEVEDOR",
            "bank_code": "001",
            "account_digit": "0",
            "branch_number": "2874",
            "account_number": "000057555",
            "document_number": "82744088021",
            "transfer_method": "pix",
            "percentage_receivable": 100
        }
    ]
}
```

### Response (HTTP 200)

The synchronous response echoes the request body with fields completed by the platform (for example **`contract.contract_number`** and **`requester_identifier_key`**).

STATUS 200

Response Body

```json
{
    "additional_data": {
        "contract": {
            "contract_number": "TEST7886216399",
            "signed": true,
            "signatures": [
                {
                    "signer": {
                        "name": "Alan Mathison Turing",
                        "phone": {
                            "number": "912345678",
                            "area_code": "11",
                            "country_code": "055"
                        },
                        "email": "alan.turing@email.com",
                        "document_number": "96969879003"
                    },
                    "signature": {
                        "ip_address": "168.211.22.84",
                        "timestamp": "27-10-2025 11:07:15",
                        "signature_file": {
                            "file_url": "http://qitech.com.br/signature.pdf",
                            "file_type": "pdf"
                        },
                        "geolocation": {
                            "long": "-46.63611",
                            "lat": "-23.5475"
                        },
                        "fingerprint_device": null
                    }
                }
            ]
        }
    },
    "financial": {
        "number_of_installments": 2,
        "credit_operation_type": "ccb",
        "interest_type": "pre_price_days",
        "monthly_interest_rate": 0.07,
        "disbursed_amount": 150000,
        "fine_configuration": {
            "contract_fine_rate": 0.02,
            "monthly_rate": 0.15,
            "interest_base": "calendar_days"
        },
        "interest_grace_period": 0,
        "disbursement_date": "2026-04-11",
        "first_due_date": "2026-05-10",
        "principal_grace_period": 0
    },
    "purchaser_document_number": "32402502000135",
    "requester_identifier_key": "2a55c1a76af4",
    "document_template_key": "518a0b57-2ce3-4309-94e5-6a95bc056d12",
    "borrower": {
        "email": "",
        "document_identification": "494598fd-c226-4332-a500-591ae3884673",
        "document_identification_back": "494598fd-c226-4332-a500-591ae3884673",
        "birth_date": "1998-06-03",
        "person_type": "natural",
        "is_pep": false,
        "mother_name": "Mother's full name",
        "profession": "Public server",
        "individual_document_number": "82744088021",
        "address": {
            "city": "São Paulo",
            "neighborhood": "CENTRO",
            "street": "Avenida Feliz",
            "complement": "",
            "postal_code": "49026100",
            "state": "SP",
            "number": ""
        },
        "phone": {
            "country_code": "055",
            "number": "912345678",
            "area_code": "11"
        },
        "document_identification_number": "47003534819",
        "name": "Alan Mathison Turing"
    },
    "disbursement_bank_accounts": [
        {
            "name": "NOME DEVEDOR",
            "bank_code": "001",
            "account_digit": "0",
            "branch_number": "2874",
            "account_number": "000057555",
            "document_number": "82744088021",
            "transfer_method": "pix",
            "percentage_receivable": 100
        }
    ]
}
```

Webhook body

```json
{
    "webhook_type": "debt",
    "key": "4e1ed268-9f29-44ce-9991-3bdf036aeacd",
    "status": "waiting_disbursement",
    "event_datetime": "2026-04-14 03:38:14",
    "data": {
        "borrower": {
            "name": "Alan Mathison Turing",
            "document_number": "82744088021",
            "related_party_key": "71b28fde-5d75-48b4-9c3f-ee531dccac66"
        },
        "contract": {
            "document_key": null,
            "number": "TEST7886216399",
            "urls": [],
            "signature_information": [
                {
                    "signer_name": "Alan Mathison Turing",
                    "signer_document_number": "82744088021",
                    "signer_role": "issuer",
                    "signer_email": null,
                    "signer_external_key": null,
                    "signature_url": null
                }
            ]
        },
        "requester_identifier_key": "2a55c1a76af4",
        "iof_charge_method": "financed",
        "collaterals": [],
        "contract_fees": [
            {
                "fee_type": "spread",
                "fee_amount": 453.39
            }
        ],
        "external_contract_fees": [
            {
                "fee_type": "tac",
                "fee_amount": 0,
                "tax_amount": 0,
                "net_fee_amount": 0
            }
        ],
        "external_contract_fee_amount": 0,
        "net_external_contract_fee_amount": 0,
        "contract_fee_amount": 453.39,
        "issue_amount": 151131.6,
        "assignment_amount": 151584.99,
        "cet": "7,6600%",
        "annual_cet": "142,4473%",
        "number_of_installments": 2,
        "base_iof": 557.3,
        "additional_iof": 574.3,
        "total_iof": 1131.6,
        "ipoc_code": "324025020203182744088021TEST7886216399",
        "prefixed_interest_rate": {
            "annual_rate": 1.252191589,
            "created_at": "2026-04-14T03:38:10",
            "daily_rate": 0.0022578334,
            "interest_base": "calendar_days",
            "monthly_rate": 0.07
        },
        "installments": [
            {
                "accrual_reference_date": null,
                "additional_costs": [],
                "advanced_paid_amount": 0,
                "bank_slip_key": null,
                "business_due_date": "2026-05-11",
                "calendar_days": 29,
                "digitable_line": null,
                "due_date": "2026-05-10",
                "due_interest": 0,
                "due_principal": 151131.6,
                "fine_amount": null,
                "has_interest": true,
                "installment_history": [],
                "installment_key": "c00dbecc-efb9-4384-8db3-dadba82f2d70",
                "installment_number": 1,
                "installment_payment": [],
                "installment_status": "created",
                "installment_type": "principal",
                "original_due_principal": 151131.6,
                "original_pre_fixed_amount": 10214.91484159,
                "original_principal_amortization_amount": 73277.28515841,
                "original_total_amount": 83492.2,
                "paid_amount": 0,
                "paid_at": null,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 10214.91484159,
                "principal_amortization_amount": 73277.28515841,
                "qr_code_key": null,
                "qr_code_url": null,
                "renegotiation_proposal_key": null,
                "tax_amount": 174.25338411,
                "total_accrual_amount": null,
                "total_amount": 83492.2,
                "total_paid_amount": 0,
                "workdays": 18
            },
            {
                "accrual_reference_date": null,
                "additional_costs": [],
                "advanced_paid_amount": 0,
                "bank_slip_key": null,
                "business_due_date": "2026-06-10",
                "calendar_days": 31,
                "digitable_line": null,
                "due_date": "2026-06-10",
                "due_interest": 0,
                "due_principal": 77854.31484159,
                "fine_amount": null,
                "has_interest": true,
                "installment_history": [],
                "installment_key": "d3a2f42d-80cb-4891-b2be-ce80ffd383b2",
                "installment_number": 2,
                "installment_payment": [],
                "installment_status": "created",
                "installment_type": "principal",
                "original_due_principal": 77854.31484159,
                "original_pre_fixed_amount": 5637.88515841,
                "original_principal_amortization_amount": 77854.31484159,
                "original_total_amount": 83492.2,
                "paid_amount": 0,
                "paid_at": null,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 5637.88515841,
                "principal_amortization_amount": 77854.31484159,
                "qr_code_key": null,
                "qr_code_url": null,
                "renegotiation_proposal_key": null,
                "tax_amount": 383.04322902,
                "total_accrual_amount": null,
                "total_amount": 83492.2,
                "total_paid_amount": 0,
                "workdays": 22
            }
        ],
        "total_pre_fixed_amount": 15852.8
    }
}
```

## 7. Creating a refinancing {#creating-a-refinancing}

### Request

ENDPOINT /signed_debt
METHOD POST

Request Body

```json
{
    "additional_data": {
        "contract": {
            "contract_number": "TEST00007890",
            "signed": true,
            "signatures": [
                {
                    "signer": {
                        "name": "Alan Mathison Turing",
                        "phone": {
                            "number": "912345678",
                            "area_code": "11",
                            "country_code": "055"
                        },
                        "email": "alan.turing@email.com",
                        "document_number": "96969879003"
                    },
                    "signature": {
                        "ip_address": "168.211.22.84",
                        "timestamp": "27-10-2025 11:07:15",
                        "signature_file": {
                            "file_url": "http://qitech.com.br/signature.pdf",
                            "file_type": "pdf"
                        },
                        "geolocation": {
                            "long": "-46.63611",
                            "lat": "-23.5475"
                        },
                        "fingerprint_device": null
                    }
                }
            ]
        }
    },
    "financial": {
        "number_of_installments": 2,
        "credit_operation_type": "ccb",
        "interest_type": "pre_price_days",
        "monthly_interest_rate": 0.07,
        "final_disbursement_amount": 0,
        "fine_configuration": {
            "contract_fine_rate": 0.02,
            "monthly_rate": 0.15,
            "interest_base": "calendar_days"
        },
        "interest_grace_period": 0,
        "disbursement_date": "2026-04-08",
        "first_due_date": "2026-05-08",
        "principal_grace_period": 0
    },
    "disbursement_bank_accounts": [
        {
            "account_digit": "5",
            "document_number": "32402502000135",
            "bank_code": "341",
            "account_number": "00002",
            "percentage_receivable": 100,
            "branch_number": "0001",
            "name": "Accout Name"
        }
    ],
    "purchaser_document_number": "32402502000135",
    "requester_identifier_key": "494598fd2009078709098",
    "refinanced_credit_operations": [
        {
            "operation_key": "067c421d-9ba1-4d4f-bf98-eb39dd12a5a5",
            "due_balance": 1000
        }
    ],
    "document_template_key": "518a0b57-2ce3-4309-94e5-6a95bc056d12",
    "borrower": {
        "email": "",
        "document_identification": "494598fd-c226-4332-a500-591ae3884673",
        "document_identification_back": "494598fd-c226-4332-a500-591ae3884673",
        "birth_date": "1998-06-03",
        "person_type": "natural",
        "is_pep": false,
        "mother_name": "Mother's full name",
        "profession": "Public server",
        "individual_document_number": "47003534819",
        "address": {
            "city": "São Paulo",
            "neighborhood": "CENTRO",
            "street": "Avenida Feliz",
            "complement": "",
            "postal_code": "49026100",
            "state": "SP",
            "number": ""
        },
        "phone": {
            "country_code": "055",
            "number": "912345678",
            "area_code": "11"
        },
        "document_identification_number": "47003534819",
        "name": "Alan Mathison Turing"
    }
}
```

:::caution Attention

Refinancing creation uses the same **`POST /signed_debt`** endpoint as **[§6. Standard loan (normal flow)](#standard-loan-post-signed-debt)**, with **`refinanced_credit_operations`** listing operations to settle. The example below also includes **`additional_data.contract`** (opt-in signatures) and **`disbursement_bank_accounts`**.
:::

### Body parameters

| Field                           | Type   | Description                                                                                                                                                                                                        | Max. chars | 
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **additional_data** *            | object | Contract metadata and **signature** evidence under `additional_data.contract` (contract number, signed flag, `signatures[]` with signer and evidence). | -            |
| **borrower** *                  | object | **[Borrower object](#objeto-borrower)** — Borrower of the credit operation.                                                                                                                                         | -            | 
| **disbursement_bank_accounts** * | array | **[Disbursement bank account](#objeto-disbursement_bank_accounts)** — Account for disbursement                                                                               | -            |
| **financial** *                 | object | **[Financial object](#objeto-financial)** — Financial terms; use `"natural"` for `person_type` when applicable. | -            |
| **purchaser_document_number** * | string | Assignee (purchaser) CNPJ (digits only, no formatting).                                                                                                                                                           | -            |
| **requester_identifier_key** | string | Client tracking key for the request.                                                                                                                                                           | -            |
| **refinanced_credit_operations** * | array of objects | **[Refinanced credit operations](#objeto-refinanced_credit_operations)** — Operations to settle with this refinancing.                                                                                                                                                           | -            |

### Borrower object
| Field                            | Type    | Description                                                                             | Max. chars | 
|----------------------------------|---------|---------------------------------------------------------------------------------------|--------------|
| **name** *                       | string  | Borrower full name                                                                       | 100          |
| **email**                        | string  | Borrower email                                                                      | 254          |
| **phone**                        | object  | **[Phone object](#objeto-phone)** — Contact phone                    | -            | 
| **is_pep** *                     | boolean | PEP indicator (http://www.portaldatransparencia.gov.br/download-de-dados/pep)      | -            |
| **address** *                    | object  | **[Address object](#objeto-address)** — Borrower address                           | -            | 
| **role_type** *                  | enum    | Default: _issuer_                                                                     | -            |
| **birth_date** *                 | date    | Borrower birth date (`YYYY-MM-DD`)                                  | -            |
| **mother_name** *                | string  | Mother’s full name                                                                | 100          |
| **nationality**                  | string  | Nationality                                                              | 50           |
| **person_type** *                | string  | **[Person type](#enumerador-person_type)** — `natural` or `legal` (default: `natural` for individuals) | -            |
| **individual_document_number** * | string  | Borrower CPF (digits only)                                                       | 11           |
| **document_identification**     * | string  | **DOCUMENT_KEY** of the borrower’s photo ID PDF (RG or CNH) | -            |
| **document_identification_back** |string | **DOCUMENT_KEY** of the back of the photo ID (uploaded beforehand). | 11 |

### Address object {#objeto-address}
| Field              | Type   | Description                                                                | Max. chars | 
|--------------------|--------|--------------------------------------------------------------------------|--------------| 
| **city** *         | string | City                                                       | 100          |
| **state** *        | string | State (two uppercase letters)                      | 2            |
| **number** *       | string | Street number                                                       | 10           |
| **street** *       | string | Street name                                                          | 100          |
| **complement** *   | string | Address complement (free text)                                    | 100          |
| **postal_code** *  | string | Postal code (https://www.buscacep.correios.com.br/) | 8            |
| **neighborhood** * | string | Neighborhood                                                       | 100          |

### Phone object {#objeto-phone}
| Field              | Description | Example                                               | Max. chars | 
|--------------------|-----------|-------------------------------------------------------|--------------| 
| **number** *       | string    | Phone number                                    | 10           |
| **area_code** *    | string    | Area code (https://ddd.guiamais.com.br/) | 2            |
| **country_code** * | string    | Country code (https://ddi.guiamais.com.br/) | 3            |

### Disbursement bank account {#objeto-disbursement_bank_accounts}

Debt issuance must include bank details for disbursement; by default this is an account in the borrower’s name.

| Field                 | Type   | Description                                                                                          | Max. chars | 
|-----------------------|--------|----------------------------------------------------------------------------------------------------|--------------|
| name                  | string | Account holder name                                                                           | 50           |
| document_number       | string | Account holder CPF                                                                            | 11           |
| bank_code *           | string | COMPE bank code (https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf) | 3            |
| branch_number *       | string | Branch number (do not include branch check digit)                                  | 4            |
| account_number *      | string | Account number (without account check digit)                                               | 10           |
| account_digit *       | string | Account check digit (use zero instead of letters)                                     | 1            |
| account_type          | enum   | [Account type](#enumerador-account-type)                                  | 1            |

### Financial object {#objeto-financial}

The `financial` object describes the credit operation’s financial terms.

| Field                      | Type   | Description                                                                                                     | Max. chars |
|----------------------------|--------|---------------------------------------------------------------------------------------------------------------|--------------|
| **final_disbursement_amount** *     | float  | Effective disbursement of the credit operation (when not a cash payout to the borrower, sizing follows due balance of refinanced loan(s)—see §1 and §5).                                                                 | -            |
| **interest_type**          | enum | **[Interest type](#enumerador-interest-type)** — Amortization and interest calculation | -            |
| **credit_operation_type**  | enum | **[Credit operation type](#enumerador-credit-operation-type)** — Agreement type       | -            |
| **annual_interest_rate**   | float  | Annual prefixed interest rate as a decimal                                                           | -            |
| **disbursement_date**      | date   | Disbursement date                                                                                | -            |
| **interest_grace_period**  | int    | Interest grace period (months)                                                                                  | -            |
| **principal_grace_period** | int    | Principal grace period                                                                                 | -            |
| **number_of_installments** | int    | Number of installments                                                                     | -            |
| **fine_configuration**     | object | **[Fine configuration](#objeto-fine-configuration)** — Late interest and penalty        | -            |

### Fine configuration object

Fine configuration defines late penalty and interest for the credit operation.

| Field                  | Type  | Description                                                                            | Max. chars |
|------------------------|-------|--------------------------------------------------------------------------------------|--------------|
| **contract_fine_rate** | float | Late penalty rate                                                       | -            |
| **interest_base**      | enum  | **[Interest base](#enumerador-interest-base)** — Interest calculation basis | -            |
| **monthly_rate**       | float | Monthly late interest rate                                                 | -            |

### Refinanced credit operations {#objeto-refinanced_credit_operations}

| Field | Type | Description | Max. chars |
|---|---|---|---|
| `operation_key` * | string | Key of the operation to refinance | UUID |
| `due_balance` | number | Payoff amount of the operation to settle (optional, ≥ 0) | -    |

### Enumerators

#### Person type {#enumerador-person_type}
| Value             | Description             |
|------------------------|-----------------------|
| **legal**   | Legal entity        |
| **natural**    | Natural person    |

#### Account type {#enumerador-account-type}
| Value             | Description             |
|------------------------|-----------------------|
| **checking_account**   | Checking account        |
| **deposit_account**    | Deposit account     |
| **guaranteed_account** | Guaranteed account     |
| **investment_account** | Investment account |
| **payment_account**    | Payment account    |
| **saving_account**     | Savings account        |
| **salary_account**     | Salary account         |

#### Interest type {#enumerador-interest-type}
| Value           | Description                                                                                                                                                                |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **pre_price_days**   | Price method (equal installments) with daily prefixed interest                                                                                     |
| **pre_price**        | Price method (equal installments) with prefixed interest in fixed 30-day periods                                                                |
| **pre_sac**          | SAC (constant amortization) with daily prefixed interest                                                                                 |
| **post_sac**         | SAC with prefixed rate plus post-fixed index (CDI, IPCA, or IGP-M), daily                                                                                  |
| **post_price**       | Price method with prefixed rate plus post-fixed index in fixed 30-day periods |
| **post_price_days**  | Price method with prefixed rate plus post-fixed index, daily                      |

#### Credit operation type {#enumerador-credit-operation-type}
| Value    | Description                      |
|---------------|--------------------------------|
| **ccb**       | Bank credit note (Cédula de Crédito Bancário)     |
| **cce**       | Export credit note |
| **cci**       | Real estate credit note  |
| **nce**       | Export credit note (alternative)   |

#### Interest base {#enumerador-interest-base}
| Value            | Description                                                                 |
|-----------------------|---------------------------------------------------------------------------|
| **workdays**          | Business days, 252-day year    |
| **calendar_days**     | Calendar days, 360-day year |
| **calendar_days_365** | Calendar days, 365-day year |

#### Fee type {#enumerador-fee-type}
Each fee type must be enabled and configured by QI Tech in advance.

| Value            | Description                                                                  |
|-----------------------|----------------------------------------------------------------------------|
| **tac**               | Account opening fee                                             |
| **spread**            | Premium on the credit operation acquisition amount                  |
| **warranty_analysis** | Collateral analysis fee                                             |
| **ted_fee**           | TED transfer fee                                                              |
| **spread_ted_fee**    | Premium on TED fee in the acquisition amount |

### Response

STATUS 200

Response Body

```json
{
    "webhook_type": "debt",
    "key": "f6c9c359-217a-475b-b2bc-540402d0c720",
    "status": "waiting_signature",
    "event_datetime": "2026-04-09 03:14:55",
    "data": {
        "borrower": {
            "name": "Alan Mathison Turing",
            "document_number": "47003534819",
            "related_party_key": "f606243a-6d6b-4de8-984e-0364fffe50cc"
        },
        "contract": {
            "document_key": "6f8ecbba-c7ed-482e-81f7-717a91b8c5cb",
            "number": "TEST00007890",
            "urls": [
                "https://storage.googleapis.com/sandbox-doc-api-private/documents/6f8ecbba-c7ed-482e-81f7-717a91b8c5cb/CASTELLOBNPL-ALAN_MATHISON_TURING-CCB0260409031449.pdf"
            ],
            "signature_information": [
                {
                    "signer_name": "Alan Mathison Turing",
                    "signer_document_number": "47003534819",
                    "signer_role": "issuer",
                    "signer_email": null,
                    "signer_external_key": null,
                    "signature_url": null
                }
            ]
        },
        "requester_identifier_key": "494598fd2009078709098",
        "iof_charge_method": "financed",
        "collaterals": [],
        "contract_fees": [
            {
                "fee_type": "spread",
                "fee_amount": 30.46
            },
            {
                "fee_type": "spread_refinancing",
                "fee_amount": 30.23
            }
        ],
        "external_contract_fees": [
            {
                "fee_type": "tac",
                "fee_amount": 0,
                "tax_amount": 0,
                "net_fee_amount": 0
            }
        ],
        "external_contract_fee_amount": 0,
        "net_external_contract_fee_amount": 0,
        "contract_fee_amount": 60.69,
        "issue_amount": 10153.18,
        "assignment_amount": 10213.87,
        "cet": "7,6500%",
        "annual_cet": "142,2787%",
        "number_of_installments": 2,
        "base_iof": 38.3,
        "additional_iof": 38.58,
        "total_iof": 76.88,
        "ipoc_code": "324025020203147003534819TEST00007890",
        "prefixed_interest_rate": {
            "annual_rate": 1.252191589,
            "created_at": "2026-04-09T03:14:49",
            "daily_rate": 0.0022578334,
            "interest_base": "calendar_days",
            "monthly_rate": 0.07
        },
        "installments": [
            {
                "accrual_reference_date": null,
                "additional_costs": [],
                "advanced_paid_amount": 0,
                "bank_slip_key": null,
                "business_due_date": "2026-05-08",
                "calendar_days": 30,
                "digitable_line": null,
                "due_date": "2026-05-08",
                "due_interest": 0,
                "due_principal": 10153.18,
                "fine_amount": null,
                "has_interest": true,
                "installment_history": [],
                "installment_key": "5359d7b1-8952-42e4-89bd-7fc57ac304aa",
                "installment_number": 1,
                "installment_payment": [],
                "installment_status": "created",
                "installment_type": "principal",
                "original_due_principal": 10153.18,
                "original_pre_fixed_amount": 710.7240611,
                "original_principal_amortization_amount": 4911.0359389,
                "original_total_amount": 5621.76,
                "paid_amount": 0,
                "paid_at": null,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 710.7240611,
                "principal_amortization_amount": 4911.0359389,
                "qr_code_key": null,
                "qr_code_url": null,
                "renegotiation_proposal_key": null,
                "tax_amount": 12.08114841,
                "total_accrual_amount": null,
                "total_amount": 5621.76,
                "total_paid_amount": 0,
                "workdays": 20
            },
            {
                "accrual_reference_date": null,
                "additional_costs": [],
                "advanced_paid_amount": 0,
                "bank_slip_key": null,
                "business_due_date": "2026-06-08",
                "calendar_days": 31,
                "digitable_line": null,
                "due_date": "2026-06-08",
                "due_interest": 0,
                "due_principal": 5242.1440611,
                "fine_amount": null,
                "has_interest": true,
                "installment_history": [],
                "installment_key": "02ad962c-22b7-49ab-bdb3-99f30758a254",
                "installment_number": 2,
                "installment_payment": [],
                "installment_status": "created",
                "installment_type": "principal",
                "original_due_principal": 5242.1440611,
                "original_pre_fixed_amount": 379.6159389,
                "original_principal_amortization_amount": 5242.1440611,
                "original_total_amount": 5621.76,
                "paid_amount": 0,
                "paid_at": null,
                "post_fixed_amount": 0,
                "pre_fixed_amount": 379.6159389,
                "principal_amortization_amount": 5242.1440611,
                "qr_code_key": null,
                "qr_code_url": null,
                "renegotiation_proposal_key": null,
                "tax_amount": 26.22120459,
                "total_accrual_amount": null,
                "total_amount": 5621.76,
                "total_paid_amount": 0,
                "workdays": 20
            }
        ],
        "total_pre_fixed_amount": 1090.34
    }
}
```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

## 8. Technical Specifications and Enums

### Fees Object
| Field           | Type  | Description                                                                                           |
|-----------------|-------|-----------------------------------------------------------------------------------------------------|
| **amount**      | float | Fee amount (in percentage or absolute value, depending on the value provided in the amount_type field)| -            |
| **amount_type** | enum  | Fee value unit                   |  **[Amount Type Enumerator](#amount-type-enumerator)**             |
| **fee_amount**  | float | Absolute value of the fee charged in the operation                                                           | -            |
| **fee_type**    | string  | Type of fee charged in the operation                   | **[Fee Type Enumerator](#fee-type-enumerator)**          |
| **type**        | string  |  Source of the fee charged in the operation                         | **[Origin Type Enumerator](#origin-type-enumerator)**          |

### Installments Object
| Field                             | Type    | Description                                                                      | 
|-----------------------------------|---------|--------------------------------------------------------------------------------|
| **calendar_days**                 | integer    | Number of calendar days between installments                                | -            |
| **due_date**                      | string    | Installment due date in calendar days                                   | -            |
| **due_principal**                 | float   | Remaining principal on the installment due date before its payment | -            |
| **has_interest**                  | boolean | _true_ - If true, interest applies to the installment                           | -            |
| **installment_number**            | integer    | Installment number                                                              | -            |
| **prefixed_amount**               | float   | Fixed interest amount paid on the installment                                      | -            |
| **principal_amortization_amount** | float   | Principal amount paid on the installment                                           | -            |
| **tax_amount**                    | float   | Base IOF amount of installment                                                            | -            |
| **amount**                        | float   | Installment total value                                                         | -            |
| **due_interest**                  | float     | Remaining interest after the installment due date before its payment                                   | -            |
| **period**                        | float     | Installment period | -            |
| **period_workdays**               | float     | Installment period in business days | -            |
| **period_to_disbursement**        | float     | Period until disbursement | -            |
| **period_workdays_to_disbursement**| float     | Business days until disbursement | -            |
| **calendar_days_to_disbursement** | integer    | Calendar days to disbursement | -            |
| **workdays**                      | integer    | Business days between installments | -            |
| **workdays_to_disbursement**      | integer    | Business days until disbursement | -            |

### Interest Rate Object
| Field             | Description                                                                             | 
|-------------------|---------------------------------------------------------------------------------------|
| **annual_rate**   | Annual fixed/floating interest rate expressed as a decimal                                      | -            |
| **daily_rate**    | Daily fixed/floating interest rate expressed as a decimal                                      | -            |
| **interest_base** | **[Interest Base Enumerator](#interest-base-enumerator)** - Interest calculation basis  | -            |
| **monthly_rate**  | Monthly fixed/floating interest rate expressed as a decimal                                      | -            |

### Tax Configuration Object
| Field                 | Description                                                                             | 
|-----------------------|---------------------------------------------------------------------------------------|
| **base_rate**         | Base IOF rate value                                                                | -            |
| **additional_rate**   | Additional IOF rate value                                                           | -            |

### Enumeratores

### Person Type Enumerator
| Enumerator             | Description             |
|------------------------|-----------------------|
| **legal**              | Legal person       |
| **natural**            | Natural person          |

### Account Type Enumerator
| Enumerator             | Description             |
|------------------------|-----------------------|
| **checking_account**   | Checking account        |

### Amount Type Enumerator
| Enumerator             | Description             |
|------------------------|-----------------------|
| **absolute**           | Absolute value        |
| **percentage**         | Percentage value      |

###  Interest Type Enumerator
| Enumerator           | Description                                                                                                                                                                |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **pre_price_days**   | Price amortization method (equal installments) with daily fixed-rate interest calculation                                                                                     |
| **pre_price**        | Price amortization method (equal installments) with fixed-rate interest calculation over 30-day periods                                                                |

### Credit Operation Type Enumerator 
| Enumerator    | Description                      |
|---------------|--------------------------------|
| **ccb**       | Bank Credit Note    |

### Interest Base Enumerator 
| Enumerator            | Description                                                                 |
|-----------------------|---------------------------------------------------------------------------|
| **workdays**          | Interest calculation basis in business days, assuming a 252-day year    |
| **calendar_days**     | Interest calculation basis in calendar days, assuming a 360-day year |
| **calendar_days_365** | Interest calculation basis in calendar days, assuming a 365-day year |

###  Fee Type Enumerator
Each fee type must be previously enabled and configured by QI Tech

| Enumerator            | Description                                                                  |
|-----------------------|----------------------------------------------------------------------------|
| **spread**            | Premium included in the credit operation's acquisition value                  |
| **spread_ted_fee**    | Premium on the TED transfer fee |

### Origin Type Enumerator
Each fee type must be previously enabled and configured by QI Tech

| Enumerator            | Description                                                                  |
|-----------------------|----------------------------------------------------------------------------|
| **internal**          | Internal fee                                                   |
| **external**          | External fee                                                   |

## 9. Webhooks — batch renegotiation

These events notify your systems when a **batch** renegotiation proposal (created via **`POST /renegotiation/batch_proposal`**) reaches a relevant lifecycle state—for example after **payment** (`status`: **`paid`**) or when the proposal is **rejected** (`status`: **`rejected`**).

### `webhook_type`: `renegotiation.batch_proposal`

Use this payload to reconcile **`batch_proposal_status`**, payment method, and amounts with your internal records for the **`request_control_key`** / **`batch_proposal_key`** you track from creation.

:::caution Attention

A **batch** renegotiation proposal may move to **`rejected`** when the **payment window expires** without settlement, or when an **installment is paid outside** the batch renegotiation (invalidating the proposal). Treat **`status`** accordingly and use **`key`** as **`batch_proposal_key`**.

:::

Example payload (status: paid )

```json
{
    "key": "217bf9ba-65e0-4416-8f5e-ef423d72b23c",
    "data": {
        "paid_in": {
            "ispb": "32402502",
            "name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
            "code_number": 329
        },
        "paid_method_type": "pix"
    },
    "status": "paid",
    "webhook_type": "renegotiation.batch_proposal",
    "event_datetime": "2025-09-30 13:42:58"
}
```

Example payload (status: rejected )

```json
{
    "key": "217bf9ba-65e0-4416-8f5e-ef423d72b23c",
    "data": {},
    "status": "rejected",
    "webhook_type": "renegotiation.batch_proposal",
    "event_datetime": "2025-09-30 13:42:58"
}
```

## 10. API error codes — renegotiation (reference)

The following **`code`** values may appear in error responses from renegotiation-related endpoints (batch proposal, single proposal, etc.), aligned with the service exception classes below. **`title`** and **`http_status`** follow each class; **`description`** and **`translation`** are the English and Portuguese messages returned by the API.

### General (`QIT*`)

| Code | HTTP | Exception class | Description (EN) | Translation (PT) |
|---|---|---|---|---|
| `QIT000001` | 400 | `InvalidSchema` | Payload validation message (variable). | Payload Inválido |
| `QIT000002` | 403 | `ForbiddenNotMaster` | You are not allowed to perform this action at this endpoint. | Você não está autorizado a performar esta ação neste endpoint. |
| `QIT000003` | 403 | `ForbiddenInexistentRequester` | This service cannot process requests without a 'SELECTED-AGENT' | Esse serviço não pode processar requisições sem o Header 'SELECTED-AGENT' |
| `QIT000004` | 403 | `ForbiddenNotInternal` | Request must be internal | Requisição precisa ser interna |
| `QIT000005` | 403 | `ForbiddenSelectedAgentNotTheSameAsPersonKey` | Selected agent and person key are different. | Agente da operação é diferente da chave do usuário. |
| `QIT000404` | 404 | `NotFoundResource` | The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible. | O resource solicitado não podee ser encontrado, mas pode estar disponível no futuro. Requests subsequentes do cliente são permitidos. |

### Renegotiation (`RN*`)

| Code | HTTP | Exception class | Description (EN) | Translation (PT) |
|---|---|---|---|---|
| `RN0000001` | 400 | `InvalidOperationStatus` | Credit operation status is invalid for this request. Status: `{status}` | O status dessa operação de crédito é invalido para essa requisição. Status: `{status}` |
| `RN0000002` | 400 | `InvalidInstallmentStatus` | Installment status is invalid for this request. Installment key: `{installment_key}` | O status dessa parcela é invalido para essa requisição. Installment key: `{installment_key}` |
| `RN0000003` | 404 | `InstallmentNotFound` | No installment found for received installment keys. | Nenhuma parcela encontrada para as installment keys recebidas. |
| `RN0000004` | 400 | `PercentageDiscountField` | The percentage discount amount must be less than or equal to 1. | O valor do desconto percentual deve ser menor ou igual a 1. |
| `RN0000005` | 400 | `DiscountValue` | The discount amount cannot be greater than the the installments values. | O valor do desconto não pode ser maior do que o valor das parcelas. |
| `RN0000006` | 400 | `DuplicateInstallmentKey` | The same installment key was informed more than once. Installment Key: `{installment_key}` | A mesma installment_key foi informada mais de uma vez. Installment Key: `{installment_key}` |
| `RN0000007` | 400 | `PaidAmount` | Installment doesn't have paid_amount field. Installment_key: `{installment_key}` | Parcela não possui campo paid_amount. Installment_key: `{installment_key}` |
| `RN0000008` | 400 | `ProposalWithoutPayment` | Proposal must have a payment linked to it. | A proposta deve ter um pagamento vinculado a ela. |
| `RN0000009` | 403 | `ForbiddenInvalidRequester` | The requester informed is not the same as the credit operation. | O solicitante informado não é o mesmo da operação de crédito. |
| `RN0000010` | 404 | `ProposalNotFound` | Proposal not found. | Proposta não encontrada. |
| `RN0000011` | 400 | `ProposalNotCancelable` | Proposal cannot be canceled in current status. Status: `{status}` | Proposta não pode ser cancelada no status atual. Status: `{status}` |
| `RN0000012` | 404 | `NotFoundCreditOperation` | Credit Operation not found for sent contract number. | Operação de credito não encontrada pelo número de contrato enviado. |
| `RN0000013` | 404 | `NotFoundPaymentEngine` | The payment engine has not been found. | O mecanismo de pagamento não foi encontrado. |
| `RN0000014` | 404 | `NotFoundRequesterProfile` | The requester profile has not been found. | O perfil de solicitante não foi encontrado. |
| `RN0000015` | 400 | `InvalidDate` | Proposal due date or reference date cannot be in past. | A data de vencimento da renegociação ou a data de referência não podem estar no passado. |
| `RN0000016` | 404 | `NotFoundRequesterConfiguration` | The requester configuration has not been found. | A configuração de solicitante não foi encontrada. |
| `RN0000017` | 400 | `CannotBePaid` | The proposal cannot be paid in current status. Proposal Status: `{status}` | A renegociação não pode ser paga no status atual. Proposal Status: `{status}` |
| `RN0000018` | 400 | `BankSlipRegistrationRejected` | The bank slip registration has been rejected. | O registro do boleto bancário foi rejeitado. |
| `RN0000019` | 409 | `SimilarProposalExists` | This contract is already linked to another proposal in progress. | Esse contrato ja está vinculado a outra proposta em andamento. |
| `RN0000020` | 400 | `InvalidRenegotiation` | Renegotiation request invalid due to credit operation status. | A requisição de renegociação é inválida devido ao status da operação de crédito. |
| `RN0000021` | 400 | `RenegotiationOperationNumber` | Number of operations is greater than the maximum allowed. Maximum operations allowed: `{maximum_operations}` | Número de operações é maior que o máximo permitido. Máximo de operações permitidas: `{maximum_operations}` |
| `RN0000022` | 400 | `DifferentIssuersBatchRenegotiation` | It is not possible to carry out a batch renegotiation with different issuers. | Não é possível realizar uma renegociação em lote com emissores diferentes. |
| `RN0000024` | 404 | `BatchProposalNotFound` | Batch proposal not found. | Batch proposal não encontrada. |
| `RN0000025` | 400 | `BatchProposalNotCancelable` | Batch Proposal cannot be canceled in current status. Status: `{status}` | Proposta em lote não pode ser cancelada no status atual. Status: `{status}` |
| `RN0000026` | 400 | `DuplicatedBatchProposalRequesterIdentifierKey` | Requester identifier key is already been used for another batch proposal. | Requester identifier key ja está sendo utilizada para outra proposta em lote. |
| `RN0000027` | 400 | `DiscountValueBatchProposal` | The discount amount cannot be greater than the batch proposal payment amount: `{payment_amount}`. | O valor do desconto não pode ser maior do que o valor de pagamento da renegociação em lote: `{payment_amount}`. |
| `RN0000028` | 400 | `InvalidInstallmentsForCollateralRenegotiation` | Selected Installments for renegotiation must include the latest due dates. | As parcelas selecionadas para renegociação devem incluir as últimas datas de vencimento. |
| `RN0000029` | 400 | `InvalidAmortizationTypeForCollateralRenegotiation` | Amortization Type of collateral renegotiation must be Installment Payment. | O tipo de amortização para a renegociação com colateral deve ser pagamento de parcelas. |
| `RN0000030` | 400 | `InvalidDisbursementAmountPayload` | Discount amount field can't be informed for batch proposal and operations in same request. | O campo de valor de desconto não pode ser informado para a batch proposal e para as operações na mesma requisição. |
| `RN0000031` | 400 | `InstallmentAmountZero` | Installment payment amount can't be 0. Installment_key: `{installment_key}` | Valor de pagamento da parcela não pode ser 0. Installment_key: `{installment_key}` |
| `RN0000032` | 400 | `PaymentAmountGreaterThanDisbursement` | Payment amount cannot be greater than the disbursement amount. | O valor do pagamento não pode ser maior que o valor de desembolso. |
| `RN0000033` | 400 | `PaymentAmountNotRequired` | Payment amount is not required for present amount amortization type. | O valor do pagamento não é necessário para o tipo de amortização presente. |
| `RN0000034` | 400 | `DuplicatedProposalRequesterIdentifierKey` | Requester identifier key is already been used for another proposal. | Requester identifier key ja está sendo utilizada para outra proposta. |
| `RN0000035` | 400 | `InvalidDiscountAmountOnlyInterestDiscount` | Invalid discount amount. Discount amount must be only interest discount. | O valor do desconto é invalido. O valor do desconto deve ser apenas desconto de juros. |
| `RN0000036` | 500 | `MaxRetriesTooBig` | Max retries set is too big to be executable. | Número máximo de retentativas é muito grande. |
| `RN0000037` | 400 | `InvalidEmployerDocumentForCreditOperation` | The payer document number does not match the employer document for the credit operation. | O documento do pagador não corresponde ao documento do empregador para a operação de crédito. |
| `RN0000038` | 400 | `RenegotiationAmortizationErrors` | One or more operations failed. | Uma ou mais operacoes falharam. |

Placeholder tokens such as `{status}` or `{installment_key}` reflect dynamic segments in the actual **`description`** / **`translation`** strings returned by the API.

---

# APP Integration

URL: /documentation/roteiros_laas/roteiro_e7030e18-a9c7-452b-8236-1cf8edfb4de9

## Resumo

Este guia descreve como emitir uma dívida (operação de crédito) para pessoa física através do fluxo BNPL / e-commerce utilizando o endpoint POST /signed_debt.

Este fluxo suporta pagamentos via QR Code, permitindo coletar as informações necessárias para o desembolso diretamente do QR Code, incluindo o número do documento do beneficiário, número da conta, dígito da conta, número da agência e o valor a desembolsar.

A emissão para pessoa física representa um empréstimo padrão. Nesse cenário:

- O campo `financial.disbursed_amount` especifica o valor principal a ser desembolsado ao tomador. Ele **deve ser igual** ao valor registrado no QR Code Pix informado em `disbursement_bank_accounts`.
- `borrower.person_type` deve estar definido como `natural`.
- O campo `refinanced_credit_operations` não deve ser informado.

A estrutura do borrower, additional_data.contract (assinaturas opt-in), disbursement_bank_accounts e demais objetos da requisição é descrita nas seções a seguir.

:::caution disbursed_amount deve ser igual ao valor do QR Code
O valor desembolsado (`financial.disbursed_amount`) **deve ser igual ao valor registrado no QR Code Pix**. Decodifique o QR Code primeiro via **`POST /pix/decode_qrcode_payload`** (passo 1) para obter o valor e use esse mesmo valor em `disbursed_amount` na emissão da dívida.
:::

## 1. Decodificação do QR Code

### Requisição

ENDPOINT pix/decode_qrcode_payload
MÉTODO POST

Testar no Playground

### Corpo da requisição

```json
{
   "qr_code_payload": "00020101021226850014br.gov.bcb.pix2563qrcodepix.bb.com.br/pix/v2/d373e385-dfe7-49f6-b9ec-14ba60a9b8285204000053039865802BR5925TESTE62070503***63047B7D"
}
```

| Campo | Tipo | Descrição | Máx caracteres |
|---|---|---|---|
| `qr_code_payload` * | string | Payload EMV do QR Code Pix (copia-e-cola). | 340 |

### Corpo da resposta

A resposta retorna os campos decodificados em um objeto aninhado `qr_code_data`. O conteúdo varia conforme o tipo de QR Code — selecione a aba correspondente.

**static**

```json
{
   "qr_code_type": "static",
   "qr_code_payload": "00020126580014br.gov.bcb.pix0136a23bf0e9-5175-4829-bf89-e8fe6ac09aa1520400005303986540530.005802BR5914TywinLannister6008saopaulo62070503***6304D4FD",
   "qr_code_data": {
      "target_pix_key": "a23bf0e9-5175-4829-bf89-e8fe6ac09aa1",
      "amount": "30.00",
      "receiver_conciliation_id": "***",
      "additional_data": [],
      "category_code": "0000",
      "city": "saopaulo",
      "postal_code": null,
      "reusable_qrcode": "no"
   }
}
```

:::info QR Code estático — campos indisponíveis
Por especificação do BR Code, QR Codes estáticos **não contêm** dados do pagador esperado, data de expiração, multa, juros, descontos nem abatimento. Esses campos só existem em QR Codes dinâmicos.

Além disso, `qr_code_data.amount` em QR estático pode vir `null` quando o lojista emitiu o QR "em branco" (sem valor fixo) — o pagador define o valor no momento do pagamento.
:::

**dynamic_instant**

```json
{
   "qr_code_type": "dynamic_instant",
   "qr_code_payload": "00020101021226850014br.gov.bcb.pix2563qrcodepix.bb.com.br/pix/v2/d373e385-dfe7-49f6-b9ec-14ba60a9b8285204000053039865802BR5925TESTE62070503***63047B7D",
   "qr_code_data": {
      "target_pix_key": "teste.cobrancapix@gmail.com.br",
      "receiver_conciliation_id": "fgnb4NTt7pOUBGfrcporERwVVqr0f8PWRfK",
      "amount": "9367.61",
      "can_change": "no",
      "expiration_seconds": 201574,
      "created_at": "2023-03-13T19:00:28.440Z",
      "presented_at": "2023-03-14T19:07:48.729Z",
      "question_to_payer": "Liquidacao de Parcelas",
      "status": "ATIVA",
      "revision": 0,
      "category_code": "0000",
      "city": "RIO DE JANEIRO",
      "postal_code": null,
      "reusable_qrcode": "no",
      "receiver_url": "qrcodepix.bb.com.br/pix/v2/d373e385-dfe7-49f6-b9ec-14ba60a90000",
      "additional_data": [],
      "payer_name": "ISMAEL FATIMA AMARAL",
      "payer_document_number": "10003550206",
      "payer_person_type": "natural",
      "target_name": "TESTE LTDA."
   }
}
```

:::info Expiração — `dynamic_instant`
O QR Code dinâmico imediato expira após `expiration_seconds` segundos contados a partir de `created_at`. Para obter o instante exato de expiração, calcule no cliente: `created_at + expiration_seconds`.
:::

**dynamic_term**

```json
{
   "qr_code_type": "dynamic_term",
   "qr_code_payload": "00020101021226840014br.gov.bcb.pix2562invoice.starkbank.com/v2/cobv/8b434df48c30482a81f7c936ae35cc123456000053039865802BR5925Oncred Sociedade de Credi6015TESTE 62070503***6304D008",
   "qr_code_data": {
      "target_pix_key": "e623e7b0-d00a-400e-aee6-79632430e817",
      "receiver_conciliation_id": "8b434df48c30482a81f7c936ae35cc87",
      "original_amount": "55.59",
      "reduction_amount": null,
      "discount_amount": null,
      "fee_amount": null,
      "fine_amount": null,
      "amount": "55.59",
      "due_date": "2023-03-27",
      "days_after_due_accepted": 16,
      "created_at": "2023-01-10T19:49:58.30Z",
      "presented_at": "2023-03-10T15:32:15.87Z",
      "question_to_payer": null,
      "status": "ATIVA",
      "revision": 0,
      "category_code": "0000",
      "reusable_qrcode": "no",
      "receiver_url": "invoice.starkbank.com/v2/cobv/8b434df48c30482a81f7c936ae351234",
      "additional_data": [],
      "payer_name": "Willian Rocha",
      "payer_document_number": "00000000000",
      "payer_person_type": "natural",
      "target_name": "TESTE LTDA.",
      "target_trading_name": null,
      "address": "Rua Tapajos, 941",
      "state": "SP",
      "city": "Sao Caetano do Sul",
      "postal_code": "09551230"
   }
}
```

:::info Expiração — `dynamic_term`
Cobranças com vencimento aceitam pagamento até `due_date + days_after_due_accepted` dias corridos. No exemplo acima, com `due_date: 2023-03-27` e `days_after_due_accepted: 16`, o pagamento é aceito até `2023-04-12`.

`amount` representa o **valor final a ser pago** (já incidente `fine_amount`, `fee_amount`, `discount_amount` e `reduction_amount`). Para o valor base, use `original_amount`.
:::

#### Campos da resposta

| Campo | Tipo | Descrição | Presente em |
|---|---|---|---|
| `qr_code_type` | string | Tipo do QR Code: `static`, `dynamic_instant` ou `dynamic_term`. | Todos |
| `qr_code_payload` | string | Payload EMV original enviado na requisição. | Todos |
| `qr_code_data.target_pix_key` | string | Chave Pix do recebedor. | Todos |
| `qr_code_data.amount` | string/decimal | Valor da cobrança. Em `dynamic_term` é o valor final (após multa/juros/desconto/abatimento). Em `static` pode vir `null`. | Todos |
| `qr_code_data.receiver_conciliation_id` | string | Identificador de conciliação do recebedor (txid). | Todos |
| `qr_code_data.additional_data` | array | Lista de informações adicionais `{name, value}`. | Todos |
| `qr_code_data.category_code` | string | Código de categoria do estabelecimento (MCC). | Todos |
| `qr_code_data.city` | string | Cidade do recebedor. | Todos |
| `qr_code_data.postal_code` | string | CEP do recebedor. | Todos |
| `qr_code_data.reusable_qrcode` | string | `yes` se o QR pode ser pago múltiplas vezes, `no` caso contrário. | Todos |
| `qr_code_data.receiver_url` | string | URL do PSP do recebedor (campo `loc` do BR Code). | `dynamic_*` |
| `qr_code_data.status` | string | Status da cobrança — ver enumeradores abaixo. | `dynamic_*` |
| `qr_code_data.revision` | integer | Versão atual da cobrança. | `dynamic_*` |
| `qr_code_data.created_at` | string ISO | Data de criação da cobrança no PSP do recebedor. | `dynamic_*` |
| `qr_code_data.presented_at` | string ISO | Data de apresentação da cobrança ao pagador. | `dynamic_*` |
| `qr_code_data.question_to_payer` | string | Mensagem do recebedor ao pagador (`solicitacaoPagador`). | `dynamic_*` |
| `qr_code_data.payer_name` | string | Nome do pagador esperado, quando informado pelo recebedor. | `dynamic_*` |
| `qr_code_data.payer_document_number` | string | CPF/CNPJ do pagador esperado. | `dynamic_*` |
| `qr_code_data.payer_person_type` | string | `natural` ou `legal`. | `dynamic_*` |
| `qr_code_data.target_name` | string | Nome do recebedor. | `dynamic_*` |
| `qr_code_data.expiration_seconds` | integer | Tempo de validade do QR em segundos a partir de `created_at`. | `dynamic_instant` |
| `qr_code_data.can_change` | string | `yes` se o pagador pode alterar o valor, `no` caso contrário. | `dynamic_instant` |
| `qr_code_data.original_amount` | string/decimal | Valor original da cobrança antes de multa/juros/desconto. | `dynamic_term` |
| `qr_code_data.due_date` | string (date) | Data de vencimento da cobrança. | `dynamic_term` |
| `qr_code_data.days_after_due_accepted` | integer | Dias após o vencimento em que ainda aceita pagamento. | `dynamic_term` |
| `qr_code_data.fine_amount` | string/decimal | Multa aplicada após o vencimento. | `dynamic_term` |
| `qr_code_data.fee_amount` | string/decimal | Juros aplicados após o vencimento. | `dynamic_term` |
| `qr_code_data.discount_amount` | string/decimal | Desconto concedido antes do vencimento. | `dynamic_term` |
| `qr_code_data.reduction_amount` | string/decimal | Abatimento aplicado à cobrança. | `dynamic_term` |
| `qr_code_data.target_trading_name` | string | Nome fantasia do recebedor. | `dynamic_term` |
| `qr_code_data.address` | string | Logradouro do recebedor. | `dynamic_term` |
| `qr_code_data.state` | string | UF do recebedor. | `dynamic_term` |

#### Enumeradores de status (QR Code dinâmico)

| Valor | Descrição |
|---|---|
| `ATIVA` | Cobrança disponível, sem pagamento realizado. |
| `CONCLUIDA` | Cobrança paga e finalizada. |
| `REMOVIDA_PELO_USUARIO_RECEBEDOR` | Usuário recebedor solicitou a remoção da cobrança. |
| `REMOVIDA_PELO_PSP` | Banco recebedor solicitou a remoção da cobrança. |

### Erros

QR Code com formato inválido

```json
{
  "data": "{\"title\": \"Invalid Qr Code Format\", \"description\": \"The Qr Code format is invalid, please enter a valid Qr Code\", \"translation\": \"O formato do Qr Code é inválido, por favor insira um Qr Code válido\", \"extra_fields\": {}, \"code\": \"PXT000070\"}"
}
```

Tipo de QR Code não identificado no payload

```json
{
  "data": "{\"title\": \"Invalid Qr Code Type\", \"description\": \"The Qr Code payload given did not provide a propper Qr Code type\", \"translation\": \"O payload de QR Code fornecido não contêm um tipo de Qr Code Válido\", \"extra_fields\": {}, \"code\": \"PXT000071\"}"
}
```

Erro ao solicitar o payload do QR Code à instituição de registro

```json
{
  "data": "{\"title\": \"Error in Qr Code Payload Request\", \"description\": \"An error occurred while requesting the qr code payload to the registry institution\", \"translation\": \"Um erro ocorreu durante a requisição do payload do qr code para a instituição de registro\", \"extra_fields\": {}, \"code\": \"PXT000069\"}"
}
```

## 2. Emissão de dívida

### Requisição

ENDPOINT /signed_debt
MÉTODO POST

Testar no Playground

### Corpo da requisição

```json
{
   "additional_data": {
      "contract": {
         "contract_number": null,
         "signed": true,
         "signatures": [
            {
               "signer": {
                  "name": "Alan Mathison Turing",
                  "phone": { "number": "912345678", "area_code": "11", "country_code": "055" },
                  "email": "alan.turing@email.com",
                  "document_number": "96969879003"
               },
               "signature": {
                  "ip_address": "168.211.22.84",
                  "timestamp": "27-10-2025 11:07:15",
                  "signature_file": { "file_url": "http://qitech.com.br/signature.pdf", "file_type": "pdf" },
                  "geolocation": { "long": "-46.63611", "lat": "-23.5475" },
                  "fingerprint_device": null
               }
            }
         ]
      }
   },
   "financial": {
      "number_of_installments": 2,
      "credit_operation_type": "ccb",
      "interest_type": "pre_price_days",
      "monthly_interest_rate": 0.07,
      "disbursed_amount": 150000,
      "fine_configuration": { "contract_fine_rate": 0.02, "monthly_rate": 0.15, "interest_base": "calendar_days" },
      "interest_grace_period": 0,
      "disbursement_date": "2026-04-11",
      "first_due_date": "2026-05-10",
      "principal_grace_period": 0
   },
   "purchaser_document_number": "32402502000135",
   "requester_identifier_key": "40822732-c4ce-41fb-9ee5-5e0304cd04a7",
   "document_template_key": "518a0b57-2ce3-4309-94e5-6a95bc056d12",
   "borrower": {
      "email": "alan.turing@email.com",
      "document_identification": "494598fd-c226-4332-a500-591ae3884673",
      "document_identification_back": "494598fd-c226-4332-a500-591ae3884673",
      "birth_date": "1998-06-03",
      "person_type": "natural",
      "is_pep": false,
      "mother_name": "Nome completo da mãe",
      "profession": "Servidor público",
      "individual_document_number": "82744088021",
      "address": {
         "city": "São Paulo",
         "neighborhood": "CENTRO",
         "street": "Avenida Feliz",
         "complement": "",
         "postal_code": "49026100",
         "state": "SP",
         "number": ""
      },
      "phone": { "country_code": "055", "number": "912345678", "area_code": "11" },
      "document_identification_number": "47003534819",
      "name": "Alan Mathison Turing"
   },
   "disbursement_bank_accounts": [
      {
         "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/3fecc731adf542659b84be038ec4151e5204000053039865802BR5925LogcardMeiosDePagamentoLt6008SaoPaulo61080145200062070503***6304A936"
      }
   ]
}
```

:::caution Atenção
A emissão para pessoa física utiliza `borrower.person_type: "natural"` e um `individual_document_number` (CPF). `financial.disbursed_amount` deve ser igual ao valor registrado no QR Code Pix enviado em `disbursement_bank_accounts` — decodifique o QR Code antes via **`POST /pix/decode_qrcode_payload`**. Omita `refinanced_credit_operations` (esse campo só é utilizado quando há quitação de operações existentes em refinanciamento).
:::

### Parâmetros do corpo

| Campo | Tipo | Descrição | Máx caracteres |
|---|---|---|---|
| `additional_data` * | object | Metadados do contrato e evidências de assinatura em `additional_data.contract` (número do contrato, flag de assinatura, signatures[] com signer e evidências). | - |
| `borrower` * | object | Objeto borrower — pessoa física tomadora do crédito. | - |
| `disbursement_bank_accounts` * | array | Contas de desembolso — array contendo o QR Code que recebe o desembolso (um único item neste fluxo). | - |
| `financial` * | object | Objeto financial — condições financeiras; use `disbursed_amount` para o valor a desembolsar ao tomador. | - |
| `purchaser_document_number` * | string | CNPJ do cessionário (somente dígitos, sem formatação). | - |
| `requester_identifier_key` | string | Chave de rastreio do cliente para a requisição. | 50 |
| `document_template_key` | string | Chave do template do contrato a ser utilizado na operação. | UUID |

### Objeto borrower

| Campo | Tipo | Descrição | Máx caracteres |
|---|---|---|---|
| `name` * | string | Nome completo do tomador | 100 |
| `email` | string | E-mail do tomador | 254 |
| `phone` | object | Objeto phone — telefone de contato | - |
| `is_pep` * | boolean | Indicador de PEP ([http://www.portaldatransparencia.gov.br/download-de-dados/pep](http://www.portaldatransparencia.gov.br/download-de-dados/pep)) | - |
| `address` * | object | Objeto address — endereço do tomador | - |
| `role_type` | enum | Papel do tomador no contrato. Padrão: `issuer`. | - |
| `birth_date` * | date | Data de nascimento (YYYY-MM-DD) | - |
| `mother_name` * | string | Nome completo da mãe | 100 |
| `nationality` | string | Nacionalidade | 50 |
| `profession` | string | Profissão do tomador | 100 |
| `person_type` * | string | Tipo de pessoa — deve ser `natural` para pessoas físicas | - |
| `individual_document_number` * | string | CPF do tomador (somente dígitos) | 11 |
| `document_identification` * | string | DOCUMENT_KEY do PDF do documento (RG ou CNH), enviado previamente | UUID |
| `document_identification_back` | string | DOCUMENT_KEY do verso do documento (enviado previamente) | UUID |
| `document_identification_number` | string | Número do documento de identificação do tomador (RG ou CNH), somente dígitos | 20 |

### Objeto address

| Campo | Tipo | Descrição | Máx caracteres |
|---|---|---|---|
| `city` * | string | Cidade | 100 |
| `state` * | string | Estado (duas letras maiúsculas) | 2 |
| `number` * | string | Número | 10 |
| `street` * | string | Logradouro | 100 |
| `complement` * | string | Complemento do endereço (texto livre) | 100 |
| `postal_code` * | string | CEP ([https://www.buscacep.correios.com.br/](https://www.buscacep.correios.com.br/)) | 8 |
| `neighborhood` * | string | Bairro | 100 |

### Objeto phone

| Campo | Tipo | Descrição | Máx caracteres |
|---|---|---|---|
| `number` * | string | Número do telefone | 10 |
| `area_code` * | string | DDD ([https://ddd.guiamais.com.br/](https://ddd.guiamais.com.br/)) | 2 |
| `country_code` * | string | DDI ([https://ddi.guiamais.com.br/](https://ddi.guiamais.com.br/)) | 3 |

### Contas de desembolso

Neste fluxo, o desembolso é liquidado pelo pagamento do QR Code dinâmico Pix fornecido pelo lojista. Em vez de enviar as coordenadas bancárias do beneficiário, envie o payload do QR Code dentro de `disbursement_bank_accounts` — a QI Tech decodifica e roteia o desembolso para o dono do QR Code.

`disbursement_bank_accounts` é um array com um único item contendo apenas o payload do QR Code:

| Campo | Tipo | Descrição | Máx caracteres |
|---|---|---|---|
| `qr_code_url` * | string | Payload EMV do QR Code dinâmico Pix a ser pago. | 250 |

:::caution Consistência de valor
O valor registrado no QR Code **deve ser igual** a `financial.disbursed_amount`. Decodifique o QR Code via **`POST /pix/decode_qrcode_payload`** (passo 1) para obter o valor e use esse mesmo valor em `disbursed_amount` na emissão da dívida.
:::

:::info Dados do recebedor preenchidos na resposta
Ao emitir com `qr_code_url`, a QI Tech decodifica o QR Code e preenche automaticamente os dados do recebedor no `disbursement_account` da resposta/webhook:

- `name`: nome completo do recebedor (sempre por extenso, sem máscara).
- `document_number`: documento do recebedor — **CPF (11 dígitos) é retornado mascarado** como `***XXXXXX**`; **CNPJ (14 dígitos) é retornado íntegro**, sem máscara.
- `ispb` / `financial_institutions` / `financial_institutions_code_number`: instituição financeira do recebedor.
- `pix_key`, `receiver_conciliation_id`, `end_to_end_id`, `amount_receivable`: extraídos do QR Code decodificado.

Os campos `account_branch`, `account_number` e `account_digit` permanecem `null` no caso de QR Code dinâmico, pois esses dados não fazem parte do EMV.
:::

### Objeto financial

O objeto financial descreve as condições financeiras da operação de crédito.

| Campo | Tipo | Descrição | Máx caracteres |
|---|---|---|---|
| `disbursed_amount` * | float | Valor desembolsado ao tomador (principal da operação) | - |
| `interest_type` | enum | Tipo de juros — amortização e cálculo de juros | - |
| `credit_operation_type` | enum | Tipo da operação de crédito — tipo de instrumento | - |
| `monthly_interest_rate` | float | Taxa de juros mensal prefixada (decimal) | - |
| `disbursement_date` | date | Data de desembolso (YYYY-MM-DD) | - |
| `first_due_date` | date | Data do primeiro vencimento (YYYY-MM-DD) | - |
| `interest_grace_period` | int | Carência de juros (meses) | - |
| `principal_grace_period` | int | Carência do principal | - |
| `number_of_installments` | int | Número de parcelas | - |
| `fine_configuration` | object | Configuração de multa — juros de mora e multa | - |

### Objeto fine_configuration

A configuração de multa define a multa e os juros de mora aplicáveis à operação.

| Campo | Tipo | Descrição | Máx caracteres |
|---|---|---|---|
| `contract_fine_rate` | float | Taxa de multa contratual | - |
| `interest_base` | enum | Base de juros — base de cálculo dos juros | - |
| `monthly_rate` | float | Taxa de juros de mora mensal | - |

### Enumeradores

#### Person type

| Valor | Descrição |
|---|---|
| `natural` | Pessoa física |
| `legal` | Pessoa jurídica |

#### Account type

| Valor | Descrição |
|---|---|
| `checking_account` | Conta corrente |
| `deposit_account` | Conta de depósito |
| `guaranteed_account` | Conta garantida |
| `investment_account` | Conta de investimento |
| `payment_account` | Conta de pagamento |
| `saving_account` | Poupança |
| `salary_account` | Conta salário |

#### Interest type

| Valor | Descrição |
|---|---|
| `pre_price_days` | Método Price (parcelas iguais) com juros prefixados diários |
| `pre_price` | Método Price (parcelas iguais) com juros prefixados em períodos fixos de 30 dias |
| `pre_sac` | SAC (amortização constante) com juros prefixados diários |
| `post_sac` | SAC com taxa prefixada + índice pós-fixado (CDI, IPCA ou IGP-M), diário |
| `post_price` | Price com taxa prefixada + índice pós-fixado em períodos fixos de 30 dias |
| `post_price_days` | Price com taxa prefixada + índice pós-fixado, diário |

#### Credit operation type

| Valor | Descrição |
|---|---|
| `ccb` | Cédula de Crédito Bancário |
| `cce` | Cédula de Crédito à Exportação |
| `nce` | Nota de Crédito à Exportação |

:::info BNPL
No fluxo BNPL / e-commerce, `ccb` é o valor utilizado na prática.
:::

#### Interest base

| Valor | Descrição |
|---|---|
| `workdays` | Dias úteis, ano de 252 dias |
| `calendar_days` | Dias corridos, ano de 360 dias |
| `calendar_days_365` | Dias corridos, ano de 365 dias |

### Resposta (HTTP 200)

A resposta síncrona ecoa o corpo da requisição com campos completados pela plataforma (por exemplo `contract.contract_number` e `requester_identifier_key`).

STATUS 200

Corpo da resposta

```json
{
   "webhook_type": "debt",
   "key": "4e1ed268-9f29-44ce-9991-3bdf036aeacd",
   "status": "issued",
   "event_datetime": "2026-04-14 03:38:14",
   "data": {
      "borrower": {
         "name": "Alan Mathison Turing",
         "document_number": "82744088021",
         "related_party_key": "71b28fde-5d75-48b4-9c3f-ee531dccac66"
      },
      "contract": {
         "document_key": null,
         "number": "TEST7886216399",
         "urls": [],
         "signature_information": [
            {
               "signer_name": "Alan Mathison Turing",
               "signer_document_number": "82744088021",
               "signer_role": "issuer",
               "signer_email": null,
               "signer_external_key": null,
               "signature_url": null
            }
         ]
      },
      "requester_identifier_key": "40822732-c4ce-41fb-9ee5-5e0304cd04a7",
      "iof_charge_method": "financed",
      "collaterals": [],
      "contract_fees": [ { "fee_type": "spread", "fee_amount": 453.39 } ],
      "external_contract_fees": [ { "fee_type": "tac", "fee_amount": 0, "tax_amount": 0, "net_fee_amount": 0 } ],
      "external_contract_fee_amount": 0,
      "net_external_contract_fee_amount": 0,
      "contract_fee_amount": 453.39,
      "issue_amount": 151131.6,
      "assignment_amount": 151584.99,
      "cet": "7,6600%",
      "annual_cet": "142,4473%",
      "number_of_installments": 2,
      "base_iof": 557.3,
      "additional_iof": 574.3,
      "total_iof": 1131.6,
      "ipoc_code": "324025020203182744088021TEST7886216399",
      "prefixed_interest_rate": {
         "annual_rate": 1.252191589,
         "created_at": "2026-04-14T03:38:10",
         "daily_rate": 0.0022578334,
         "interest_base": "calendar_days",
         "monthly_rate": 0.07
      },
      "installments": [
         {
            "due_date": "2026-05-10",
            "due_principal": 151131.6,
            "installment_key": "c00dbecc-efb9-4384-8db3-dadba82f2d70",
            "installment_number": 1,
            "installment_status": "created",
            "installment_type": "principal",
            "pre_fixed_amount": 10214.91484159,
            "principal_amortization_amount": 73277.28515841,
            "tax_amount": 174.25338411,
            "total_amount": 83492.2
         },
         {
            "due_date": "2026-06-10",
            "due_principal": 77854.31484159,
            "installment_key": "d3a2f42d-80cb-4891-b2be-ce80ffd383b2",
            "installment_number": 2,
            "installment_status": "created",
            "installment_type": "principal",
            "pre_fixed_amount": 5637.88515841,
            "principal_amortization_amount": 77854.31484159,
            "tax_amount": 383.04322902,
            "total_amount": 83492.2
         }
      ],
      "total_pre_fixed_amount": 15852.8,
      "disbursement_account": [
         {
            "name": "Logcard Meios De Pagamento Ltda",
            "document_number": "18236120000158",
            "pix_key": "d6e2d611-6c68-4f84-9be5-962ad2f2bcb6",
            "qr_code_key": null,
            "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/3fecc731adf542659b84be038ec4151e5204000053039865802BR5925LogcardMeiosDePagamentoLt6008SaoPaulo61080145200062070503***6304A936",
            "account_branch": null,
            "account_number": null,
            "account_digit": null,
            "account_type": "checking_account",
            "ispb": "18236120",
            "percentage_receivable": 100,
            "amount_receivable": 150000,
            "end_to_end_id": "E32402502202606270040dNdgaZPUHxT"
         }
      ]
   }
}
```

### Webhook (`webhook_type: debt`)

Após a operação ser processada, a QI Tech notifica seu endpoint com os dados consolidados da dívida, incluindo o valor emitido, breakdown de IOF, taxa de juros prefixada e o cronograma de parcelas.

Corpo do webhook

```json
{
   "webhook_type": "debt",
   "key": "4e1ed268-9f29-44ce-9991-3bdf036aeacd",
   "status": "waiting_disbursement",
   "event_datetime": "2026-04-14 03:38:14",
   "data": {
      "borrower": {
         "name": "Alan Mathison Turing",
         "document_number": "82744088021",
         "related_party_key": "71b28fde-5d75-48b4-9c3f-ee531dccac66"
      },
      "contract": {
         "document_key": null,
         "number": "TEST7886216399",
         "urls": [],
         "signature_information": [
            {
               "signer_name": "Alan Mathison Turing",
               "signer_document_number": "82744088021",
               "signer_role": "issuer",
               "signer_email": null,
               "signer_external_key": null,
               "signature_url": null
            }
         ]
      },
      "requester_identifier_key": "40822732-c4ce-41fb-9ee5-5e0304cd04a7",
      "iof_charge_method": "financed",
      "collaterals": [],
      "contract_fees": [ { "fee_type": "spread", "fee_amount": 453.39 } ],
      "external_contract_fees": [ { "fee_type": "tac", "fee_amount": 0, "tax_amount": 0, "net_fee_amount": 0 } ],
      "external_contract_fee_amount": 0,
      "net_external_contract_fee_amount": 0,
      "contract_fee_amount": 453.39,
      "issue_amount": 151131.6,
      "assignment_amount": 151584.99,
      "cet": "7,6600%",
      "annual_cet": "142,4473%",
      "number_of_installments": 2,
      "base_iof": 557.3,
      "additional_iof": 574.3,
      "total_iof": 1131.6,
      "ipoc_code": "324025020203182744088021TEST7886216399",
      "prefixed_interest_rate": {
         "annual_rate": 1.252191589,
         "created_at": "2026-04-14T03:38:10",
         "daily_rate": 0.0022578334,
         "interest_base": "calendar_days",
         "monthly_rate": 0.07
      },
      "installments": [
         {
            "business_due_date": "2026-05-11",
            "calendar_days": 29,
            "due_date": "2026-05-10",
            "due_interest": 0,
            "due_principal": 151131.6,
            "has_interest": true,
            "installment_key": "c00dbecc-efb9-4384-8db3-dadba82f2d70",
            "installment_number": 1,
            "installment_status": "created",
            "installment_type": "principal",
            "pre_fixed_amount": 10214.91484159,
            "principal_amortization_amount": 73277.28515841,
            "tax_amount": 174.25338411,
            "total_amount": 83492.2,
            "workdays": 18
         },
         {
            "business_due_date": "2026-06-10",
            "calendar_days": 31,
            "due_date": "2026-06-10",
            "due_interest": 0,
            "due_principal": 77854.31484159,
            "has_interest": true,
            "installment_key": "d3a2f42d-80cb-4891-b2be-ce80ffd383b2",
            "installment_number": 2,
            "installment_status": "created",
            "installment_type": "principal",
            "pre_fixed_amount": 5637.88515841,
            "principal_amortization_amount": 77854.31484159,
            "tax_amount": 383.04322902,
            "total_amount": 83492.2,
            "workdays": 22
         }
      ],
      "total_pre_fixed_amount": 15852.8,
      "disbursement_account": [
         {
            "name": "Logcard Meios De Pagamento Ltda",
            "document_number": "18236120000158",
            "pix_key": "d6e2d611-6c68-4f84-9be5-962ad2f2bcb6",
            "qr_code_key": null,
            "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/3fecc731adf542659b84be038ec4151e5204000053039865802BR5925LogcardMeiosDePagamentoLt6008SaoPaulo61080145200062070503***6304A936",
            "account_branch": null,
            "account_number": null,
            "account_digit": null,
            "account_type": "checking_account",
            "ispb": "18236120",
            "percentage_receivable": 100,
            "amount_receivable": 150000,
            "end_to_end_id": "E32402502202606270040dNdgaZPUHxT"
         }
      ]
   }
}
```

## 3. Consulta de dívida

Você pode consultar a dívida posteriormente para recuperar informações ou acompanhar o status atual.

### Requisição

ENDPOINT /v2/credit_operation/requester_identifier_key/ REQUESTER-IDENTIFIER-KEY
MÉTODO GET

Testar no Playground

### Parâmetros de path

| Campo | Tipo | Descrição | Máx caracteres |
|---|---|---|---|
| `requester_identifier_key` * | string | Chave de rastreio do cliente enviada na emissão da dívida | 50 |

:::info Rota alternativa
Caso possua o `credit_operation_key` (UUID), utilize `GET /v2/credit_operation/{credit_operation_key}`.
:::

### Resposta

STATUS 200

Corpo da resposta

```json
{
   "credit_operation_key": "0773a1b1-675a-4a10-80a2-a10308c7281e",
   "issue_amount": 151131.6,
   "origin_key": "0773a1b1-675a-4a10-80a2-a10308c7281e",
   "total_iof": 1131.6,
   "assigned_at": null,
   "disbursement_start_date": "2026-04-11",
   "disbursement_end_date": "2026-04-11",
   "issue_date": "2026-04-11",
   "requester_identifier_key": "40822732-c4ce-41fb-9ee5-5e0304cd04a7",
   "installments": [
      {
         "due_date": "2026-05-10",
         "calendar_days": 29,
         "due_principal": 151131.6,
         "has_interest": true,
         "installment_key": "c00dbecc-efb9-4384-8db3-dadba82f2d70",
         "installment_number": 1,
         "installment_status": "created",
         "installment_type": "principal",
         "pre_fixed_amount": 10214.91484159,
         "principal_amortization_amount": 73277.28515841,
         "tax_amount": 174.25338411,
         "total_amount": 83492.2
      }
   ]
}
```

## 4. Especificações técnicas e enumeradores

### Objeto installments

| Campo | Tipo | Descrição |
|---|---|---|
| `calendar_days` | integer | Número de dias corridos entre parcelas |
| `due_date` | string | Data de vencimento da parcela em dias corridos |
| `due_principal` | float | Saldo do principal na data de vencimento da parcela, antes do pagamento |
| `has_interest` | boolean | Se verdadeiro, há incidência de juros na parcela |
| `installment_number` | integer | Número da parcela |
| `pre_fixed_amount` | float | Valor de juros prefixados pago na parcela |
| `principal_amortization_amount` | float | Valor do principal amortizado na parcela |
| `tax_amount` | float | Valor base de IOF da parcela |
| `total_amount` | float | Valor total da parcela |
| `due_interest` | float | Saldo de juros após a data de vencimento da parcela, antes do pagamento |
| `workdays` | integer | Dias úteis entre parcelas |

### Objeto interest_rate

| Campo | Descrição |
|---|---|
| `annual_rate` | Taxa de juros anual prefixada/flutuante (decimal) |
| `daily_rate` | Taxa de juros diária prefixada/flutuante (decimal) |
| `interest_base` | Base de juros — base de cálculo dos juros |
| `monthly_rate` | Taxa de juros mensal prefixada/flutuante (decimal) |

### Objeto tax_configuration

| Campo | Descrição |
|---|---|
| `base_rate` | Valor da alíquota base de IOF |
| `additional_rate` | Valor da alíquota adicional de IOF |

---

# Fluxo de reembolso

Este guia explica como processar reembolsos totais e parciais para operações de crédito originadas via fluxo BNPL / e-commerce utilizando o endpoint POST /signed_debt.

O fluxo de reembolso é composto por duas etapas principais:

1. **Notificação de chargeback** — um webhook é enviado sempre que um chargeback é processado, independentemente de representar um reembolso total ou parcial. O webhook contém todas as informações necessárias para identificar e processar o chargeback.
2. **Renegociação** — após processar o webhook com sucesso, é possível iniciar uma renegociação para gerar um novo cronograma de parcelas refletindo o valor reembolsado. Os termos da renegociação são totalmente configuráveis e devem seguir suas regras e políticas de negócio.

## Webhook — Reembolso recebido

### Visão geral

Assim que um reembolso identificado for recebido, a QI Tech enviará um webhook contendo os detalhes do reembolso, incluindo se trata-se de reembolso total ou parcial e o valor creditado na conta do FIDC.

Com base nessas informações, você poderá aplicar suas políticas de negócio e determinar como proceder com o reembolso solicitado por seu cliente.

Corpo do webhook

```json
{
   "origin_key": "d5c88545-4d17-4679-b262-ae170618078a",
   "refund_date": "2026-06-26",
   "webhook_type": "laas.transitory_conciliation.refund",
   "amount": "200.00",
   "event_datetime": "2026-06-12T11:52:22"
}
```

## Renegociação — Simulação

### Visão geral

Antes de criar uma proposta, é possível simular os valores do estorno para a operação. A simulação retorna as parcelas afetadas, o valor presente, o desconto e o valor total.

O fluxo de reembolso utiliza dois tipos de amortização:

- **`equal_amount`** — estorno **parcial**. Distribui `payment_amount` proporcionalmente entre as parcelas em aberto, reduzindo o saldo devedor. A operação permanece ativa com as parcelas remanescentes em aberto.
- **`full_settle`** — estorno **total**. Quita integralmente a operação na `reference_date`. A operação passa a `settled` e não há parcelas remanescentes.

### Requisição

ENDPOINT /renegotiation/simulation
MÉTODO POST

Testar no Playground

Corpo da requisição

**equal_amount (parcial)**

```json
{
    "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c",
    "amortization_type": "equal_amount",
    "reference_date": "2026-04-13",
    "payment_amount": 50.00
}
```

**full_settle (total)**

```json
{
    "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c",
    "amortization_type": "full_settle",
    "reference_date": "2026-04-13",
    "payment_amount": 1043.55
}
```

### Parâmetros do corpo

| Campo | Tipo | Descrição | Máx tamanho |
|---|---|---|---|
| `debt_key` * | string | Chave única da operação de crédito (DEBT-KEY) | UUID |
| `amortization_type` * | string | Modalidade do estorno | **[Valores do amortization_type](#valores-do-amortization-type)** |
| `payment_amount` * | float | Valor do estorno em reais. Em `equal_amount`, valor parcial a ser abatido. Em `full_settle`, deve cobrir o saldo total na `reference_date`. | 15,2 |
| `reference_date` | string | Data de referência para cálculo do valor presente (YYYY-MM-DD). Não pode ser anterior à data de desembolso. | 10 |
| `discount_percentage` | float | Percentual de desconto opcional sobre o valor presente. Não pode ser enviado junto com `discount_amount`. | - |
| `discount_amount` | float | Valor de desconto opcional sobre o valor presente. Não pode ser enviado junto com `discount_percentage`. | - |

### Valores do amortization_type

| Valor | Descrição |
|---|---|
| **`equal_amount`** | Estorno parcial. `payment_amount` é distribuído proporcionalmente entre as parcelas em aberto; a operação permanece ativa com as parcelas remanescentes em aberto. |
| **`full_settle`** | Estorno total. Quita integralmente a operação na `reference_date`. A operação passa a `settled` e não há parcelas remanescentes. |

### Resposta

STATUS 200

Exemplo de corpo de resposta

```json
{
    "amortization_type": "equal_amount",
    "payment_amount": 50.00,
    "discount_percentage": 0,
    "discount_amount": 0,
    "reference_date": "2026-04-13",
    "affected_installments": [
        {
            "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88",
            "due_date": "2026-05-07",
            "principal_amount": 15.71,
            "interest_amount": 4.07,
            "fine_amount": 0,
            "total_amount": 19.78,
            "present_amount": 18.00,
            "paid_amount": 18.00,
            "principal_amortization_payment_amount": 18.00,
            "prefixed_interest_payment_amount": 0,
            "fine_payment_amount": 0
        }
    ],
    "remaining_installments": [
        {
            "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999",
            "due_date": "2026-06-07",
            "principal_amount": 15.71,
            "interest_amount": 4.07,
            "fine_amount": 0,
            "total_amount": 19.78
        }
    ]
}
```

## Renegociação — Proposta

### Visão geral

Após validar a simulação, crie a proposta de renegociação. Para o fluxo de estorno, envie `payment_type: "internal"` — o valor é debitado diretamente da `account_key` informada, sem geração de boleto ou Pix.

:::caution Atenção
- A operação deve estar ativa e já desembolsada.
- `reference_date` não pode ser anterior à data de desembolso.
- `request_control_key` é obrigatório para idempotência.
:::

### Requisição

ENDPOINT /renegotiation/proposal
MÉTODO POST

Testar no Playground

Corpo da requisição

**equal_amount (parcial)**

```json
{
    "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c",
    "payment_type": "internal",
    "amortization_type": "equal_amount",
    "reference_date": "2026-04-13",
    "payment_amount": 50.00,
    "account_key": "5ae72355-1e47-4624-9915-ceb93d872194",
    "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db"
}
```

**full_settle (total)**

```json
{
    "debt_key": "72760166-4ddf-41fb-8a8c-605f8f4fc35c",
    "payment_type": "internal",
    "amortization_type": "full_settle",
    "reference_date": "2026-04-13",
    "payment_amount": 1043.55,
    "account_key": "5ae72355-1e47-4624-9915-ceb93d872194",
    "request_control_key": "e5f6c3d4-e5f6-7890-abcd-ef1234567890"
}
```

### Parâmetros do corpo

| Campo | Tipo | Descrição | Máx tamanho |
|---|---|---|---|
| `debt_key` * | string | Chave única da operação de crédito (DEBT-KEY) | UUID |
| `payment_type` * | string | Para fluxo de estorno, use `internal`. | **[Valores do payment_type](#valores-do-payment-type)** |
| `amortization_type` * | string | Modalidade do estorno | **[Valores do amortization_type](#valores-do-amortization-type-1)** |
| `payment_amount` * | float | Valor do estorno em reais. | 15,2 |
| `account_key` * | string | Chave da conta interna de onde o valor será debitado. | UUID |
| `request_control_key` * | string | Chave de idempotência do cliente. Use um valor único por tentativa. | 50 |
| `reference_date` | string | Data de referência para cálculo do valor presente (YYYY-MM-DD). Não pode ser anterior à data de desembolso. | 10 |
| `discount_percentage` | float | Percentual de desconto opcional sobre o valor presente. Não pode ser enviado junto com `discount_amount`. | - |
| `discount_amount` | float | Valor de desconto opcional sobre o valor presente. Não pode ser enviado junto com `discount_percentage`. | - |

### Valores do payment_type

| Valor | Descrição |
|---|---|
| `internal` | Débito interno na `account_key` (automático, sem boleto ou Pix). Usado para o fluxo de estorno. |
| `bank_slip` | Gera boleto bancário e Pix. |
| `pix` | Somente Pix. |
| `manual` | Pagamento manual (sem geração de meio de pagamento). |

### Valores do amortization_type {#valores-do-amortization-type-1}

| Valor | Descrição |
|---|---|
| **`equal_amount`** | Estorno parcial. `payment_amount` é distribuído proporcionalmente entre as parcelas em aberto; a operação permanece ativa com as parcelas remanescentes em aberto. |
| **`full_settle`** | Estorno total. Quita integralmente a operação na `reference_date`. A operação passa a `settled` e não há parcelas remanescentes. |

### Resposta

STATUS 201

Exemplo de corpo de resposta

```json
{
    "proposal_key": "bcc16a6d-ce21-4cd4-8d8c-d26f89ccc685",
    "contract_number": "DWF1761222116",
    "amortization_type": "equal_amount",
    "payment_amount": 50.00,
    "discount_percentage": 0,
    "discount_amount": 0,
    "requester_name": "Dante Ltda",
    "requester_key": "78287247-947d-4730-9bd1-7efb068175b6",
    "origin_key": null,
    "issuer_name": "Dante Ferrarini",
    "issuer_document_number": "31057466093",
    "affected_installments": [
        {
            "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88",
            "due_date": "2026-05-07",
            "principal_amount": 15.71,
            "interest_amount": 4.07,
            "fine_amount": 0,
            "total_amount": 19.78,
            "present_amount": 18.00,
            "paid_amount": 18.00,
            "principal_amortization_payment_amount": 18.00,
            "prefixed_interest_payment_amount": 0,
            "fine_payment_amount": 0
        }
    ],
    "remaining_installments": [
        {
            "installment_key": "370e73d1-55d8-431e-9b22-d08fb8297999",
            "due_date": "2026-06-07",
            "principal_amount": 15.71,
            "interest_amount": 4.07,
            "fine_amount": 0,
            "total_amount": 19.78
        }
    ],
    "proposal_status": "pending_payment",
    "payment_type": "internal",
    "payment": {
        "digitable_line": null,
        "qr_code_url": null,
        "qr_code_key": null,
        "bank_slip_key": null,
        "paid_method_type": "internal",
        "source_account_key": "5ae72355-1e47-4624-9915-ceb93d872194",
        "payment_data": {
            "target_account_key": "6108dd45-580d-48c4-b3bb-74c1e843be49",
            "transaction_amount": 50.00
        }
    },
    "proposal_due_date": "2026-04-13",
    "reference_date": "2026-04-13",
    "devolution_amount": 0,
    "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db"
}
```

### Detalhes da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `proposal_key` | string | Chave única da proposta (UUID). Use para consulta e correlação com webhook. |
| `proposal_status` | string | Estado da proposta. Inicia em `pending_payment`; vai para `paid` quando o débito interno é processado. |
| `affected_installments` | array | Parcelas que receberam o estorno. Mostra a composição do `paid_amount` entre principal, juros e multa. |
| `remaining_installments` | array | Parcelas que permanecem em aberto após o estorno. Vazio em `full_settle`. |
| `payment.payment_data.target_account_key` | string | Conta de destino do débito interno. |
| `payment.payment_data.transaction_amount` | float | Valor efetivamente debitado da `account_key`. |
| `devolution_amount` | float | Sobrepagamento devolvido ao fundo. Só é diferente de zero quando um pagamento prévio somado ao estorno excede o saldo devedor. |
| `request_control_key` | string | Eco da chave de idempotência enviada na requisição. |

### Webhook de quitação

Quando um estorno quita integralmente a operação — tipicamente em `full_settle`, também possível quando `equal_amount` em sequência zera o saldo — a QI Tech envia um webhook `webhook_type: debt` com `status: settled`. Use para confirmar a quitação de forma assíncrona.

## Renegociação — Cancelar proposta

### Visão geral

`DELETE /renegotiation/proposal/{proposal_key}` cancela uma proposta que ainda não foi finalizada. Apenas propostas com `proposal_status: "pending_payment"` são canceláveis. Quaisquer meios de pagamento associados (boleto, Pix) são invalidados.

### Requisição

ENDPOINT /renegotiation/proposal/{'{proposal_key}'}
MÉTODO DELETE

### Parâmetros de path

| Campo | Tipo | Descrição | Máx tamanho |
|---|---|---|---|
| `proposal_key` * | string | Chave da proposta retornada em `POST /renegotiation/proposal`. | UUID |

### Resposta

STATUS 200

Exemplo de corpo de resposta

```json
{
    "proposal_key": "bcc16a6d-ce21-4cd4-8d8c-d26f89ccc685",
    "proposal_status": "canceled",
    "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db"
}
```

## Consultar status da proposta

Após criar a proposta, é possível consultar seu status pelo `request_control_key`.

ENDPOINT /renegotiation/proposal/request_control_key/ REQUEST-CONTROL-KEY
MÉTODO GET

A resposta segue o mesmo formato do retorno do `POST /renegotiation/proposal`. O `proposal_status` indica o andamento:

| Status | Descrição |
|---|---|
| `pending_payment` | Proposta criada, aguardando processamento do débito interno. |
| `paid` | Débito processado. Em `full_settle`, a operação já está em `settled`. |
| `canceled` | Proposta cancelada via `DELETE /renegotiation/proposal/{proposal_key}`. |

---

# Renegociação em lote

Para cenários em que é necessário renegociar múltiplas operações do mesmo emissor de uma só vez — gerando um único meio de pagamento (boleto e/ou Pix) cobrindo todo o lote — utilize os **endpoints em lote**.

:::caution Atenção
- A renegociação em lote só pode incluir operações do mesmo emissor e da mesma chave de integração.
- Limite de **50 operações** por lote.
- Os endpoints em lote suportam um conjunto distinto de tipos de amortização: `installment_payment`, `overdue_installment_payment`, `present_amount`. `equal_amount` e `full_settle` **não** estão disponíveis em lote.
:::

## Renegociação — Simulação em lote

### Visão geral

Antes de criar uma proposta em lote, simule os valores. A simulação retorna as parcelas afetadas, os descontos e o valor total devido entre todas as operações.

Para `present_amount` na simulação, cada item de `installments[]` contém apenas `installment_key`. Os campos por parcela `paid_amount` e `discount_amount` são obrigatórios apenas no endpoint **proposta em lote**.

### Requisição

ENDPOINT /renegotiation/batch_proposal_simulation
MÉTODO POST

Testar no Playground

:::warning Atenção
Na raiz, `discount_amount` e `discount_percentage` são mutuamente exclusivos.
:::

Corpo da requisição

```json
{
   "amortization_type": "installment_payment",
   "reference_date": "2026-04-08",
   "operations": [
      {
         "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
         "installments": [
            { "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88" }
         ]
      },
      {
         "debt_key": "2cbfb9b1-1fdb-5f8d-9967-b338e5eb83f9",
         "installments": [
            { "installment_key": "2ef25ed8-7124-44f5-9e3d-1d1a7196166e" }
         ]
      }
   ]
}
```

### Parâmetros do corpo

| Campo | Tipo | Descrição | Máx tamanho |
|---|---|---|---|
| `amortization_type` * | string | Tipo de amortização do lote | **[Valores do amortization_type em lote](#valores-do-amortization-type-em-lote)** |
| `operations` * | array | Operações a renegociar | **[Objeto operations](#objeto-operations-batch)** |
| `reference_date` | string | Data de referência para cálculo do valor presente (YYYY-MM-DD). | 10 |
| `discount_percentage` | float | Percentual de desconto opcional sobre o valor presente (nível raiz, global). | - |
| `discount_amount` | float | Valor de desconto opcional sobre o valor presente (nível raiz, global). | - |

### Objeto operations {#objeto-operations-batch}

| Campo | Tipo | Descrição | Máx tamanho |
|---|---|---|---|
| `debt_key` * | string | Chave única da operação de crédito (DEBT-KEY) | UUID |
| `installments` * | array | Parcelas a renegociar | **[Objeto installments](#objeto-installments-batch-simulacao)** |

### Objeto installments {#objeto-installments-batch-simulacao}

| Campo | Tipo | Descrição | Máx tamanho |
|---|---|---|---|
| `installment_key` * | string | Chave da parcela | UUID |

### Valores do amortization_type em lote

| Valor | Descrição |
|---|---|
| `installment_payment` | Pagar parcelas específicas. Cada item de `installments[]` contém apenas `installment_key`. |
| `overdue_installment_payment` | Pagar parcelas em atraso. Mesma estrutura de `installment_payment`. |
| `present_amount` | Valor presente por parcela. Na simulação, enviar apenas `installment_key`. No endpoint de proposta, enviar também `paid_amount` e `discount_amount`. |

### Resposta

STATUS 200

Exemplo de corpo de resposta

```json
{
   "batch_proposal_key": "429fd784-e13e-47a1-ad9f-291209e0e621",
   "amortization_type": "installment_payment",
   "payment_amount": 78389.55,
   "discount_percentage": 0,
   "discount_amount": 0,
   "requester_name": "Castello (BNPL)",
   "requester_key": "3e69b448-9afb-4aef-9c0d-0a3059350d80",
   "issuer_name": "Alan Mathison Turing",
   "issuer_document_number": "82744088021",
   "reference_date": "2026-04-08",
   "operations": [
      {
         "requester_key": "3e69b448-9afb-4aef-9c0d-0a3059350d80",
         "contract_number": "TEST00790",
         "payment_amount": 78389.55,
         "discount_amount": 0,
         "affected_installments": [
            {
               "installment_key": "24b5deae-304e-4773-9b25-e42dbd450241",
               "due_date": "2026-05-10",
               "principal_amount": 73107.75,
               "interest_amount": 10580.11,
               "fine_amount": 0,
               "total_amount": 83687.87,
               "present_amount": 78389.55,
               "paid_amount": 78389.55,
               "principal_amortization_payment_amount": 78048.30,
               "prefixed_interest_payment_amount": 341.25,
               "fine_payment_amount": 0,
               "discount_amount": 0
            }
         ],
         "remaining_installments": [
            {
               "installment_key": "2b1d9423-4dab-44b3-bf8c-efc8433176dd",
               "due_date": "2026-06-10",
               "principal_amount": 73096.23,
               "interest_amount": 10591.64,
               "fine_amount": 0,
               "total_amount": 83687.87
            }
         ],
         "debt_key": "388c47fa-6c6c-4d2b-8f00-ccc2d571fcb0"
      }
   ]
}
```

## Renegociação — Proposta em lote

### Visão geral

Após simular os valores, crie a proposta em lote. A proposta gera um único meio de pagamento (boleto e/ou Pix) cobrindo todas as operações.

Para `amortization_type: present_amount`, cada item em `operations[].installments[]` deve incluir `paid_amount` e `discount_amount` (além de `installment_key`). Para `installment_payment` / `overdue_installment_payment`, apenas `installment_key` é obrigatório.

### Requisição

ENDPOINT /renegotiation/batch_proposal
MÉTODO POST

Testar no Playground

Corpo da requisição

**installment_payment**

```json
{
   "amortization_type": "installment_payment",
   "reference_date": "2026-04-08",
   "proposal_due_date": "2026-04-15",
   "payment_type": "pix",
   "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db",
   "operations": [
      {
         "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
         "installments": [
            { "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88" }
         ]
      },
      {
         "debt_key": "2cbfb9b1-1fdb-5f8d-9967-b338e5eb83f9",
         "installments": [
            { "installment_key": "2ef25ed8-7124-44f5-9e3d-1d1a7196166e" }
         ]
      }
   ]
}
```

**present_amount**

```json
{
   "amortization_type": "present_amount",
   "reference_date": "2026-04-08",
   "proposal_due_date": "2026-04-15",
   "payment_type": "pix",
   "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db",
   "operations": [
      {
         "debt_key": "1baea8a0-0fca-4f7c-8857-a227d4da72f8",
         "installments": [
            { "installment_key": "ca5741c7-99a2-42e7-92a1-9328a36e4e88", "paid_amount": 500, "discount_amount": 50 }
         ]
      },
      {
         "debt_key": "2cbfb9b1-1fdb-5f8d-9967-b338e5eb83f9",
         "installments": [
            { "installment_key": "2ef25ed8-7124-44f5-9e3d-1d1a7196166e", "paid_amount": 150, "discount_amount": 10 }
         ]
      }
   ]
}
```

### Parâmetros do corpo

| Campo | Tipo | Descrição | Máx tamanho |
|---|---|---|---|
| `amortization_type` * | string | Tipo de amortização do lote | **[Valores do amortization_type em lote](#valores-do-amortization-type-em-lote-1)** |
| `payment_type` * | string | Tipo de pagamento em lote | **[Valores do payment_type em lote](#valores-do-payment-type-em-lote)** |
| `operations` * | array | Operações a renegociar | **[Objeto operations](#objeto-operations-batch-1)** |
| `proposal_due_date` * | string | Data de vencimento da proposta (YYYY-MM-DD) | 10 |
| `reference_date` * | string | Data de referência (YYYY-MM-DD) | 10 |
| `request_control_key` | string | Chave de idempotência do cliente. Necessária para cancelamento por `request_control_key`. | 50 |
| `discount_percentage` | float | Percentual de desconto global opcional sobre o valor presente. | - |
| `discount_amount` | float | Valor de desconto global opcional sobre o valor presente. | - |
| `payer_document_number` | string | CNPJ do pagador (somente dígitos). | 14 |
| `payer_name` | string | Nome do pagador. Obrigatório quando `payer_document_number` é enviado. | 200 |

### Objeto operations {#objeto-operations-batch-1}

| Campo | Tipo | Descrição | Máx tamanho |
|---|---|---|---|
| `debt_key` * | string | Chave única da operação de crédito (DEBT-KEY) | UUID |
| `installments` * | array | Parcelas a renegociar | **[Objeto installments](#objeto-installments-batch-proposta)** |

### Objeto installments {#objeto-installments-batch-proposta}

| Campo | Tipo | Descrição | Máx tamanho |
|---|---|---|---|
| `installment_key` * | string | Chave da parcela | UUID |
| `paid_amount` | float | Valor pago/alocado na parcela (BRL). Obrigatório quando `amortization_type` é `present_amount`. | 15,2 |
| `discount_amount` | float | Desconto em BRL aplicado à parcela. Obrigatório quando `amortization_type` é `present_amount` (use `0` se não houver). | 15,2 |

### Valores do payment_type em lote

| Valor | Descrição |
|---|---|
| `bank_slip` | Boleto bancário (também gera Pix). |
| `pix` | Somente Pix. |
| `manual` | Pagamento manual (sem geração de meio de pagamento). |

### Valores do amortization_type em lote {#valores-do-amortization-type-em-lote-1}

| Valor | Descrição |
|---|---|
| `installment_payment` | Pagar parcelas específicas — cada item em `operations[].installments[]` requer apenas `installment_key`. |
| `overdue_installment_payment` | Pagar parcelas em atraso — mesma estrutura de `installment_payment`. |
| `present_amount` | Valor presente por parcela — cada item requer `installment_key`, `paid_amount`, `discount_amount`. |

### Resposta

STATUS 201

Exemplo de corpo de resposta

```json
{
   "batch_proposal_key": "37879d40-c16e-4d7f-a16f-d79d20c50d42",
   "amortization_type": "installment_payment",
   "payment_amount": 78206.27,
   "discount_percentage": 0,
   "discount_amount": 0,
   "requester_name": "Castello (BNPL)",
   "requester_key": "3e69b448-9afb-4aef-9c0d-0a3059350d80",
   "issuer_name": "Alan Mathison Turing",
   "issuer_document_number": "82744088021",
   "reference_date": "2026-04-08",
   "proposal_due_date": "2026-04-15",
   "payment_type": "pix",
   "batch_proposal_status": "pending_payment",
   "request_control_key": "94b31045-c8e7-45be-a88d-2ae25c5df5db",
   "operations": [
      {
         "requester_key": "3e69b448-9afb-4aef-9c0d-0a3059350d80",
         "contract_number": "TEST1570594223",
         "payment_amount": 78206.27,
         "debt_key": "6564493d-75c3-4efe-9f11-82fa5cff9a78",
         "affected_installments": [
            {
               "installment_key": "1162e382-8bd6-4c0b-9111-8390d9794102",
               "due_date": "2026-05-10",
               "principal_amount": 73277.29,
               "interest_amount": 10214.91,
               "fine_amount": 0,
               "total_amount": 83492.20,
               "present_amount": 78206.27,
               "paid_amount": 78206.27,
               "principal_amortization_payment_amount": 78206.27,
               "prefixed_interest_payment_amount": 0,
               "fine_payment_amount": 0,
               "discount_amount": 0
            }
         ],
         "remaining_installments": [
            {
               "installment_key": "58eea645-5682-440d-aa6b-a3b124253684",
               "due_date": "2026-06-10",
               "principal_amount": 72925.33,
               "interest_amount": 10566.87,
               "fine_amount": 0,
               "total_amount": 83492.20
            }
         ]
      }
   ],
   "payment": {
      "digitable_line": null,
      "qr_code_url": "00020126930014br.gov.bcb.pix2571qrcode-h.sandbox.qitech.app/bacen/cobv/426661142f5d4cd9954dcae3725d020d5204000053039865802BR5925QISOCIEDADEDECREDITODIRET6008SaoPaulo61080145200062070503***6304B878",
      "qr_code_key": "42666114-2f5d-4cd9-954d-cae3725d020d",
      "bank_slip_key": null,
      "paid_method_type": "pix",
      "source_account_key": null,
      "payment_data": {
         "creditor_bank_account_key": "6108dd45-580d-48c4-b3bb-74c1e843be49",
         "batch_renegotiation_proposal_key": "37879d40-c16e-4d7f-a16f-d79d20c50d42"
      }
   }
}
```

## Renegociação — Cancelar proposta em lote

### Visão geral

Cancela uma proposta em lote que ainda esteja em estado cancelável. Apenas propostas com `batch_proposal_status: "pending_payment"` são canceláveis. Quaisquer meios de pagamento associados (boleto, Pix) são invalidados.

Duas rotas estão disponíveis:

- **Por `batch_proposal_key`** (UUID retornado em `POST /renegotiation/batch_proposal`)
- **Por `request_control_key`** (chave de idempotência enviada na criação) — útil quando o cliente rastreia as operações pela própria chave

### Cancelar por batch_proposal_key

ENDPOINT /renegotiation/batch_proposal/{'{batch_proposal_key}'}
MÉTODO DELETE

#### Parâmetros de path

| Campo | Tipo | Descrição | Máx tamanho |
|---|---|---|---|
| `batch_proposal_key` * | string | Chave da proposta retornada em `POST /renegotiation/batch_proposal`. | UUID |

### Cancelar por request_control_key

ENDPOINT /renegotiation/batch_proposal/request_control_key/{'{request_control_key}'}
MÉTODO DELETE

#### Parâmetros de path

| Campo | Tipo | Descrição | Máx tamanho |
|---|---|---|---|
| `request_control_key` * | string | Chave de idempotência enviada em `POST /renegotiation/batch_proposal`. | 50 |

### Resposta

Ambas as rotas retornam a mesma resposta.

STATUS 204

---

# Webhooks INSS

URL: /documentation/roteiros_laas/webhooks_inss

## Consultas (lista de benefícios e dados do benefício)

### 1. Consulta da lista de benefícios

- WEBHOOK_TYPE social_security_benefits_request
- STATUS success

        *Body:*

**body.json**

```json
{
    "key": "d6c193f9-ed5e-42cc-9480-e48338766eb7",
    "data": [
        {
            "grant_date": [
                "2015-05-07"
            ],
            "benefit_number": 7015686016,
            "benefit_status": "elegible"
        }
    ],
    "status": "success",
    "webhook_type": "social_security_benefits_request",
    "event_datetime": "2024-09-19T22:11:30"
}

```

- WEBHOOK_TYPE social_security_benefits_request
- STATUS failure

        *Body:*

**body.json**

```json
{
    "key": "e571385f-06e7-4277-b2e6-b1ee0522ae44",
    "data": {
        "enumerator": "not_found_legal_representative",
        "description": "beneficiary has a legal representative, but was not informed"
    },
    "status": "failure",
    "webhook_type": "social_security_benefits_request",
    "event_datetime": "2024-09-19T22:11:46"
}
```

### 2. Consulta de dados do benefício

- WEBHOOK_TYPE social_security_balance_request
- STATUS success

        *Body:*

**body.json**

```json
{
    "key": "720fc2b3-0fa7-4fb0-bea9-3c798ca8e595",
    "data": {
        "name": "NOME BENEFICIARIO",
        "state": "RS",
        "alimony": "not_payer",
        "birth_date": "18021978",
        "block_type": "not_blocked",
        "grant_date": "2006-05-22",
        "credit_type": "checking_account",
        "benefit_card": {
            "limit": 2259.2,
            "balance": 0
        },
        "benefit_number": "1377902789",
        "benefit_status": "elegible",
        "payroll_card": {
            "limit": 2259.2,
            "balance": 0
        },
        "assistance_type": "retirement_invalidity_social_security",
        "document_number": "81442882034",
        "benefit_end_date": null,
        "consigned_credit": {
            "balance": 0
        },
        "benefit_situation": "active",
        "last_inquiry_date": "2018-06-18",
        "max_total_balance": 635.4,
        "used_total_balance": 635.4,
        "politically_exposed": {
            "type": "not_politically_exposed",
            "is_politically_exposed": false
        },
        "has_power_of_attorney": false,
        "available_total_balance": 0,
        "has_judicial_concession": false,
        "number_of_portabilities": 0,
        "disbursement_bank_account": {
            "bank_code": "748",
            "account_digit": "4",
            "account_branch": "0155",
            "account_number": "000070963"
        },
        "has_entity_representation": false,
        "social_benefit_max_balance": 635.4,
        "social_benefit_used_balance": 635.4,
        "benefit_quota_expiration_date": null,
        "number_of_active_reservations": 3,
        "number_of_suspended_reservations": 0,
        "number_of_refinanced_reservations": 0,
        "number_of_active_suspended_reservations": 3
    },
    "status": "success",
    "webhook_type": "social_security_balance_request",
    "event_datetime": "2024-09-02T18:49:02"
}

```

- WEBHOOK_TYPE social_security_balance_request
- STATUS failure

        *Body:*

**body.json**

```json
{
    "key": "70130c68-7e91-41a9-8dc5-11ad876f36d2",
    "data": {
        "enumerator": "not_found_legal_representative",
        "description": "beneficiary has a legal representative, but was not informed"
    },
    "status": "failure",
    "webhook_type": "social_security_balance_request",
    "event_datetime": "2024-09-02T18:57:25"
}
```

## Portabilidade IN + Refinanciamento

### 1. Emissão de dívidas Port + Refin.

- WEBHOOK_TYPE credit_transfer.proposal.credit_operation
- CREDIT_OPERATION_TYPE portability
- CREDIT_OPERATION_STATUS issued

        *Body:*

**body.json**

```json
{
    "data": {
        "document_key": "91210cb0-2cd2-4508-98b5-ff16dbda27af",
        "signed_document_url": "https://storage.googleapis.com/live-doc-api/documents/91210cb0-2cd2-4508-98b5-ff16dbda27af/contrato_signed.pdf",
        "credit_operation_key": "6f71be3f-3814-4f1d-b015-c234755935f8",
        "credit_operation_type": "portability",
        "credit_operation_status": "issued"
    },
    "proposal_key": "22191e35-5d29-4d55-92db-0920f90b5747",
    "webhook_type": "credit_transfer.proposal.credit_operation",
    "event_datetime": "2024-10-01T10:10:32"
}

```

- WEBHOOK_TYPE credit_transfer.proposal.credit_operation
- CREDIT_OPERATION_TYPE refinancing
- CREDIT_OPERATION_STATUS issued

        *Body:*

**body.json**

```json
{
    "data": {
        "document_key": "91210cb0-2cd2-4508-98b5-ff16dbda27af",
        "signed_document_url": "https://storage.googleapis.com/live-doc-api/documents/91210cb0-2cd2-4508-98b5-ff16dbda27af/CONTRATO_signed.pdf",
        "credit_operation_key": "cbaaa1da-7610-4eba-9a48-8728b0be8f34",
        "credit_operation_type": "refinancing",
        "credit_operation_status": "issued"
    },
    "proposal_key": "91210cb0-2cd2-4508-98b5-ff16dbda27af",
    "webhook_type": "credit_transfer.proposal.credit_operation",
    "event_datetime": "2024-10-01T10:10:38"
}

```

### 2. Status Portabilidade

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS pending_acceptance

        *Body:*

**body.json**

```json
{
    "webhook_type": "credit_transfer.proposal",
    "proposal_key": "6bd4f3cc-5787-4e4c-a6ba-3748883394cd",
    "proposal_status": "pending_acceptance",
    "event_datetime": "2022-11-24T15:42:12",
    "data": {
        "portability_number": "202211230000246536429",
        "inclusion_date": "2022-11-24",
        "due_balance_expected_return_date": "2022-12-01"
    }
}

```

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS accepted

        *Body:*

**body.json**

```json
{
    "data": {
        "final_due_balance": 5558.4,
        "original_contract": {
            "cet": 26.11,
            "interest": 22.1311,
            "total_iof": 218.4,
            "contract_date": "2022-06-15",
            "last_due_date": "2029-07-07",
            "final_due_date": "2024-10-08",
            "first_due_date": "2024-11-07",
            "amortization_type": "pre_price",
            "final_due_balance": 5558.4,
            "effective_interest": 22.1311,
            "installment_number": 84,
            "origin_ispb_number": "00360305",
            "origin_operation_type": "payroll",
            "corban_document_number": null,
            "installment_face_value": 148.07,
            "origin_contract_number": "0000000000000000000000000000000001899642",
            "opened_installment_number": 57,
            "overdue_installment_number": 0
        },
        "portability_number": "202410010000341749111"
    },
    "proposal_key": "1860a994-a3aa-4456-9b14-3aa35c97797a",
    "webhook_type": "credit_transfer.proposal",
    "event_datetime": "2024-10-08T07:18:23",
    "proposal_status": "accepted"
}

```

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS canceled

        *Body:*

**body.json**

```json
{
    "webhook_type": "credit_transfer.proposal",
    "proposal_status": "canceled",
    "proposal_key": "3130d43f-4f60-49c6-806e-61b4c9cb3a14",
    "event_datetime": "2022-11-24T15:42:12"
}

```

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS retained

        *Body:*

**body.json**

```json
{
    "webhook_type": "credit_transfer.proposal",
    "proposal_key": "3130d43f-4f60-49c6-806e-61b4c9cb3a14",
    "proposal_status": "retained",
    "event_datetime": "2022-11-24T15:42:12",
    "data": {
        "retained_reason": {
            "reason": "issuer_retention",
            "description": "Retenção do Cliente"
        }
    }
}
```

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS rejected

        *Body:*

**body.json**

```json
{
  "webhook_type": "credit_transfer.proposal",
  "proposal_key": "91210cb0-2cd2-4508-98b5-ff16dbda27af",
  "proposal_status": "rejected",
  "event_datetime": "2022-11-24T15:42:12",
  "data": {
    "error": {
        "code": "ECTC0023",
        "reason": "Contrato com portabilidade em andamento"
    }
  }
}

```

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS settlement_sent

        *Body:*

**body.json**

```json
{
    "data": {
        "receipt": {
            "fee": 0,
            "amount": 5558.4,
            "origin": {
                "name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
                "type": "payment_account",
                "branch": "0001",
                "document": "32402502000135",
                "bank_code": "329",
                "account_key": "792e04a3-566d-489d-9c5a-8385f7dc76b0",
                "branch_digit": null,
                "account_digit": "6",
                "account_number": "1000111"
            },
            "timestamp": "2024-10-08T07:19:39",
            "description": "104 1620 - 00360305000104 - CAIXA ECONOMICA FEDERAL",
            "destination": {
                "name": "CAIXA ECONOMICA FEDERAL",
                "type": "checking_account",
                "branch": "1620",
                "purpose": "Saída Liquidação de Portabilidade",
                "document": "00360305000104",
                "bank_code": "104",
                "branch_digit": null,
                "account_digit": null,
                "account_number": null
            },
          "ted_receipt_url": "https://storage.googleapis.com/live-doc-api/documents/5aa5026.pdf",
            "transaction_key": "8a76b511-96c9-4b0f-a9b3-5405d400e00a",
            "ted_receipt_document_key": "5aa5026d-e78f-4781-9c4e-e2cf21425a3c"
        }
    },
    "proposal_key": "3130d43f-4f60-49c6-806e-61b4c9cb3a14",
    "webhook_type": "credit_transfer.proposal",
    "event_datetime": "2024-10-08T07:19:39",
    "proposal_status": "settlement_sent"
}

```

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS pending_settlement_confirmation

        *Body:*

**body.json**

```json
{
    "proposal_key": "3130d43f-4f60-49c6-806e-61b4c9cb3a14",
    "webhook_type": "credit_transfer.proposal",
    "event_datetime": "2024-10-08T07:20:18",
    "proposal_status": "pending_settlement_confirmation"
}

```

- WEBHOOK_TYPE credit_transfer.proposal
- STATUS paid

        *Body:*

**body.json**

```json
{
    "proposal_key": "1860a994-a3aa-4456-9b14-3aa35c97797a",
    "webhook_type": "credit_transfer.proposal",
    "event_datetime": "2024-10-09T09:14:19",
    "proposal_status": "paid"
}
```

### 3. Status Averbação (tentativas e sucesso)

        **Portabilidade**

- WEBHOOK_TYPE credit_transfer.proposal.collateral
- CREDIT_OPERATION_TYPE portability
- STATUS pending_reservation
- COLLATERAL_CONSTITUTED false
- RESERVATION_METHOD new_credit

        *Body:*

**body.json**

```json
{
    "data": {
        "collateral_data": {
            "status": "pending_reservation",
            "last_response": {
                "errors": [
                    {
                        "enumerator": "consignable_margin_excceded"
                    }
                ]
            },
            "reservation_method": "new_credit",
            "last_response_event_datetime": "2024-10-08T10:19:32Z"
        },
        "collateral_type": "social_security",
        "credit_operation_key": "6f71be3f-3814-4f1d-b015-c23475593987",
        "credit_operation_type": "portability",
        "collateral_constituted": false
    },
    "proposal_key": "6bd4f3cc-5787-4e4c-a6ba-3748883394cd",
    "webhook_type": "credit_transfer.proposal.collateral",
    "event_datetime": "2024-10-08T07:19:32"
}

```

- WEBHOOK_TYPE credit_transfer.proposal.collateral
- STATUS pending_reservation
- CREDIT_OPERATION_TYPE portability
- COLLATERAL_CONSTITUTED false
- RESERVATION_METHOD portability

        *Body:*

**body.json**

```json
{
    "data": {
        "collateral_data": {
            "status": "pending_reservation",
            "last_response": {
                "errors": [
                    {
                        "enumerator": "consignable_margin_excceded"
                    }
                ]
            },
            "reservation_method": "portability",
            "last_response_event_datetime": "2024-10-09T00:00:26Z"
        },
        "collateral_type": "social_security",
        "credit_operation_key": "6f71be3f-3814-4f1d-b015-c234755935f8",
        "credit_operation_type": "portability",
        "collateral_constituted": false
    },
    "proposal_key": "3130d43f-4f60-49c6-806e-61b4c9cb3a14",
    "webhook_type": "credit_transfer.proposal.collateral",
    "event_datetime": "2024-10-08T21:02:29"
}
```

- WEBHOOK_TYPE credit_transfer.proposal.collateral
- STATUS pending_reservation
- CREDIT_OPERATION_TYPE portability
- COLLATERAL_CONSTITUTED true
- RESERVATION_METHOD portability

        *Body:*

**body.json**

```json
{
    "data": {
        "collateral_data": {
            "reservation_method": "portability"
        },
        "collateral_type": "social_security",
        "credit_operation_key": "6f71be3f-3814-4f1d-b015-c234755935f8",
        "credit_operation_type": "portability",
        "collateral_constituted": true
    },
    "proposal_key": "3130d43f-4f60-49c6-806e-61b4c9cb3a14",
    "webhook_type": "credit_transfer.proposal.collateral",
    "event_datetime": "2024-10-09T16:49:50"
}
```

        **Refinancimamento**

- WEBHOOK_TYPE credit_transfer.proposal.collateral
- STATUS pending_reservation
- CREDIT_OPERATION_TYPE refinancing
- COLLATERAL_CONSTITUTED true
- RESERVATION_METHOD refinancing

        *Body:*

**body.json**

```json
{
    "data": {
        "collateral_data": {
            "reservation_method": "refinancing"
        },
        "collateral_type": "social_security",
        "credit_operation_key": "cbaaa1da-7610-4eba-9a48-8728b0be8f34",
        "credit_operation_type": "refinancing",
        "collateral_constituted": true
    },
    "proposal_key": "3130d43f-4f60-49c6-806e-61b4c9cb3a14",
    "webhook_type": "credit_transfer.proposal.collateral",
    "event_datetime": "2024-10-09T16:50:12"
}
```

### 4. Desembolso refinanciamento (Troco).

- WEBHOOK_TYPE credit_transfer.proposal.credit_operation
- CREDIT_OPERATION_TYPE refinancing
- CREDIT_OPERATION_STATUS disbursed

        *Body:*

**body.json**

```json
{
    "data": {
        "credit_operation_key": "cbaaa1da-7610-4eba-9a48-8728b0be8111",
        "transaction_receipts": [
            {
                "fee": 0,
                "url": "https://storage.googleapis.com/live-doc-api/documents/26ff118e-52c0-4092-bdbd-9d8253.pdf",
                "amount": 924.61,
                "origin": {
                    "name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
                    "type": "payment_account",
                    "branch": "0001",
                    "document": "32402502000135",
                    "bank_code": "329",
                    "account_key": "792e04a3-566d-489d-9c5a-8385f7dc76b0",
                    "branch_digit": null,
                    "account_digit": "6",
                    "account_branch": "0001",
                    "account_number": "1000789",
                    "financial_institution_name": "QI SCD S.A."
                },
                "timestamp": "2024-10-09T19:51:34",
                "description": "DESCRICAO",
                "destination": {
                    "name": "JOSE HENRIQUE DA SILVA",
                    "type": "checking_account",
                    "branch": "1621",
                    "purpose": "Crédito PIX em Conta",
                    "document": "79202603022",
                    "bank_ispb": "00360305",
                    "branch_digit": null,
                    "account_digit": "3",
                    "account_number": "763804111",
                    "financial_institution_name": "CAIXA ECONOMICA FEDERAL"
                },
                "end_to_end_id": "E32402502202410091950saI7VCHPrlB",
                "transaction_key": "2109e1d6-8c89-401b-9ff0-751d42b45e43",
                "origin_transaction_key": "d99f633b-1cec-4469-8ae6-61642931b475"
            }
        ],
        "credit_operation_type": "refinancing",
        "credit_operation_status": "disbursed"
    },
    "proposal_key": "3130d43f-4f60-49c6-806e-61b4c9cb3a14",
    "webhook_type": "credit_transfer.proposal.credit_operation",
    "event_datetime": "2024-10-09T16:51:34"
}

```

- WEBHOOK_TYPE credit_transfer.proposal.credit_operation
- CREDIT_OPERATION_TYPE refinancing
- CREDIT_OPERATION_STATUS canceled

        *Body:*

**body.json**

```json
{
    "webhook_type": "credit_transfer.proposal.credit_operation",
    "proposal_key": "3130d43f-4f60-49c6-806e-61b4c9cb3a14",
    "event_datetime": "2022-11-24T15:42:12",
    "data": {
        "credit_operation_status": "canceled",
        "credit_operation_type": "refinancing",
        "credit_operation_key": "1a1a44df-29b6-431c-89af-53657d906333",
        "pix_refusal": {
            "reason_enumerator": "invalid_document_number",
            "reason": "CPF/CNPJ do usuário recebedor não é compatível com o titular da conta de destino."
        },
        "cancel_reason": "pix_refusal"
    }
}

```

### 5. Consulta de portabilidade de origem

- WEBHOOK_TYPE social_security_portability_origin_contract_request
- status success

        *Body:*

**body.json**

```json
{
    "webhook": {
        "key": "25e93655-4713-488b-8800-7ac4fddf745f",
        "data": {
          "portability_number": 9223372036854776000,
          "portability_status": "open",
          "benefit_number": 1544326820,
          "portability_start_date": "2024-02-22",
          "deleted_contracts": [
            {
              "origin_bank": {
                "bank_code": 752,
                "name": "CETELEM-BNP"
              },
              "contract_number": "22-844817807/20",
              "last_installment_paid": 84,
              "exclusion_date": "22022024",
              "period_amount": 165.73
            }
          ]
        },
        "status": "success",
        "webhook_type": "social_security_portability_origin_contract_request",
        "event_datetime": "2024-02-26T21:36:22"
    }
}

```

- WEBHOOK_TYPE social_security_portability_origin_contract_request
- status failure

        *Body:*

**body.json**

```json
{
    "webhook": {
        "key": "522b5d7d-2dfc-4e92-99b7-d4df3d97edb2",
        "data": {
            "enumerator": "invalid_bank_code",
            "description": "Invalid bank code"
        },
        "status": "failure",
        "webhook_type": "social_security_portability_origin_contract_request",
        "event_datetime": "2024-02-26T21:36:22"
    }
}

```

## Crédito Novo

### 1. Status Dívida

- WEBHOOK_TYPE debt
- STATUS signature_finished

        *Body:*

**body.json**

```json
{
    "key": "ebe12ca1-ec34-4674-bd62-24c0bc204e81",
    "status": "signature_finished",
    "webhook_type": "debt",
    "event_datetime": "2024-09-02 18:39:49",
    "signed_contract_url": "https://storage.googleapis.com/live-doc-api/documents/6099edd7-1c83-4890-998e-ce60e218523cb/S_signed.pdf"
}
```

- WEBHOOK_TYPE debt
- STATUS disbursed

        *Body:*

**body.json**

```json
{
    "key": "b91ee4cd-85fd-4548-b03f-31024fc5d285",
    "data": {
        "installments": [
            {
                "due_date": "2024-12-10",
                "total_amount": 116.76,
                "installment_key": "dc3a5877-6860-42cd-b885-c4ca84b69546",
                "pre_fixed_amount": 116.76,
                "principal_amortization_amount": 0
            },
            {
                "due_date": "2025-01-10",
                "total_amount": 116.76,
                "installment_key": "1ca2c016-1bc4-4f64-a681-17699a90e27d",
                "pre_fixed_amount": 79.96557434,
                "principal_amortization_amount": 36.79442566
            },
            {
                "due_date": "2025-02-10",
                "total_amount": 116.76,
                "installment_key": "9f11bd0e-60f1-4d0c-9882-e6196e279f7a",
                "pre_fixed_amount": 66.16762896,
                "principal_amortization_amount": 50.59237104
            },
            {
                "due_date": "2025-03-10",
                "total_amount": 116.76,
                "installment_key": "0ed43a28-9324-41d1-84b3-fb41940c02e2",
                "pre_fixed_amount": 57.20192546,
                "principal_amortization_amount": 59.55807454
            },
            {
                "due_date": "2025-04-10",
                "total_amount": 116.76,
                "installment_key": "1da0b291-9e15-41a5-8aa6-86d733af6195",
                "pre_fixed_amount": 60.33833893,
                "principal_amortization_amount": 56.42166107
            },
            {
                "due_date": "2025-05-10",
                "total_amount": 116.76,
                "installment_key": "e884d447-31ea-4847-b479-eac11baeac96",
                "pre_fixed_amount": 55.45582536,
                "principal_amortization_amount": 61.30417464
            },
            {
                "due_date": "2025-06-10",
                "total_amount": 116.76,
                "installment_key": "ab16369b-c551-4a0e-84e4-b5f2a6161c1d",
                "pre_fixed_amount": 54.10815043,
                "principal_amortization_amount": 62.65184957
            },
            {
                "due_date": "2025-07-10",
                "total_amount": 116.76,
                "installment_key": "64db51eb-47c9-4f44-86e0-35ca054fc2f8",
                "pre_fixed_amount": 49.1128602,
                "principal_amortization_amount": 67.6471398
            },
            {
                "due_date": "2025-08-10",
                "total_amount": 116.76,
                "installment_key": "5035ee8e-8462-4b54-9598-de7a269103a4",
                "pre_fixed_amount": 47.21257597,
                "principal_amortization_amount": 69.54742403
            },
            {
                "due_date": "2025-09-10",
                "total_amount": 116.76,
                "installment_key": "233da01d-8ec4-4c60-8096-01a702af9b71",
                "pre_fixed_amount": 43.53204519,
                "principal_amortization_amount": 73.22795481
            },
            {
                "due_date": "2025-10-10",
                "total_amount": 116.76,
                "installment_key": "1d4bf5b2-5ff1-49c3-8a4a-ddf90fe5c370",
                "pre_fixed_amount": 38.34531007,
                "principal_amortization_amount": 78.41468993
            },
            {
                "due_date": "2025-11-10",
                "total_amount": 116.76,
                "installment_key": "a5211802-15b6-4245-afe2-8e5dcfde2e96",
                "pre_fixed_amount": 35.5069396,
                "principal_amortization_amount": 81.2530604
            },
            {
                "due_date": "2025-12-10",
                "total_amount": 116.76,
                "installment_key": "886e7907-f46e-45c7-bb9c-c66dd87050e0",
                "pre_fixed_amount": 30.17493687,
                "principal_amortization_amount": 86.58506313
            },
            {
                "due_date": "2026-01-10",
                "total_amount": 116.76,
                "installment_key": "4e82409c-1769-4555-86bd-527d585d0f88",
                "pre_fixed_amount": 26.62475039,
                "principal_amortization_amount": 90.13524961
            },
            {
                "due_date": "2026-02-10",
                "total_amount": 116.76,
                "installment_key": "e226d32f-33ec-4a20-ad60-96a0ec3216d7",
                "pre_fixed_amount": 21.85468788,
                "principal_amortization_amount": 94.90531212
            },
            {
                "due_date": "2026-03-10",
                "total_amount": 116.76,
                "installment_key": "710e51e3-9720-4b6a-a383-569736781e28",
                "pre_fixed_amount": 15.16506862,
                "principal_amortization_amount": 101.59493138
            },
            {
                "due_date": "2026-04-10",
                "total_amount": 116.76,
                "installment_key": "88cba573-627d-4ca0-b39e-0fcc20f22422",
                "pre_fixed_amount": 11.45566586,
                "principal_amortization_amount": 105.30433414
            },
            {
                "due_date": "2026-05-10",
                "total_amount": 116.76,
                "installment_key": "0e51f217-21c8-4897-baee-2bd2aad43d22",
                "pre_fixed_amount": 5.59829551,
                "principal_amortization_amount": 111.16170449
            }
        ],
        "ted_receipt_list": [
            {
                "fee": 0,
                "url": "https://storage.googleapis.com/live-doc-api/documents/304b5b46-08e5-4.pdf",
                "amount": 1000,
                "origin": {
                    "name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
                    "type": "payment_account",
                    "branch": "0001",
                    "document": "32402502000135",
                    "bank_code": "329",
                    "account_key": "836ce4ef-855b-4672-bc52-36e32e22ec05",
                    "branch_digit": null,
                    "account_digit": "1",
                    "account_branch": "0001",
                    "account_number": "00852",
                    "financial_institution_name": "QI SCD S.A."
                },
                "timestamp": "2024-10-14T03:09:17",
                "description": "DESCRICAO",
                "destination": {
                    "name": "DEVEDOR",
                    "type": "checking_account",
                    "branch": "0648",
                    "purpose": "Crédito PIX em Conta",
                    "document": "04973666068",
                    "bank_ispb": "90400888",
                    "branch_digit": null,
                    "account_digit": "7",
                    "account_number": "25252",
                    "financial_institution_name": "BCO SANTANDER (BRASIL) S.A."
                },
                "end_to_end_id": "E3240250220241014030292IkYMOt523",
                "transaction_key": "797ab666-07c4-4702-a68b-1d67afb34534",
                "origin_transaction_key": "af8aa38f-8a49-45bd-9878-101cefe9bdd4"
            }
        ],
        "requester_identifier_key": "70675b9fe09da90c8b5c992"
    },
    "status": "disbursed",
    "webhook_type": "debt",
    "event_datetime": "2024-10-14 03:09:17"
}
```

- WEBHOOK_TYPE debt
- STATUS canceled

        *Body:*

**body.json**

```json
{
    "webhook": {
        "key": "dfdf8cde-eb49-437a-a798-bb90eec03af8",
        "data": {
            "cancel_reason": "Operacao cancelada manualmente",
            "cancel_reason_enumerator": "manual"
        },
        "status": "canceled",
        "webhook_type": "debt",
        "event_datetime": "2024-09-02 18:40:12"
    }
}
```

**body_pix_refusal.json**

```json
{
    "key": "3fee13aa-a193-4444-a39a-097de8f824bf",
    "data": {
        "pix_refusal": {
            "reason": "A conta de destino encontra-se bloqueada.",
            "reason_enumerator": "blocked_account",
            "cancel_reason_enumerator": "blocked_account"
        },
        "cancel_reason": "pix_refusal",
        "cancel_reason_enumerator": "pix_refusal"
    },
    "status": "canceled",
    "webhook_type": "debt",
    "event_datetime": "2024-09-02 18:40:40"
}
```

**body_ted_refusal.json**

```json
 {
 	"status": "canceled",
 	"key": "3fee13aa-a193-4444-a39a-097de8f824bf",
 	"data": {
 		"ted_refusal": {
 			"transaction_key": "16faabfc-3876-437d-a4f6-aae17a1d68c9",
 			"description": "341 0000 000000-7 12345678900 - NOME BENEFICIÁRIO",
 			"origin": {
 				"account_key": "a1d2dea5-fa90-4676-a125-da355fdc3ed0",
 				"account_number": "00086",
 				"bank_code": "329",
 				"name": "ACCOUNT TRANSITORY",
 				"type": "payment_account",
 				"document": "32402502000135",
 				"branch_digit": null,
 				"account_digit": "8",
 				"branch": "0001"
 			},
 			"fee": 0,
 			"reason_enumerator": "agencia_conta_invalida",
 			"timestamp": "2022-11-07T14:36:05",
 			"amount": 483.6,
 			"reason": "Agência ou Conta Destinatária do Crédito Inválida",
 			"destination": {
 				"branch": "0000",
 				"account_number": "000000",
 				"name": "NOME BENEFICIÁRIO",
 				"purpose": "Crédito em Conta",
 				"type": "checking_account",
 				"branch_digit": null,
 				"document": "12345678900",
 				"bank_code": "341",
 				"account_digit": "7"
 			}
 		},
 		"cancel_reason": "ted_refusal"
 	}
 }
```

- WEBHOOK_TYPE debt
- STATUS canceled_permanently

        *Body:*

**body.json**

```json
{
    "key": "cf416a66-8e4c-4ac9-a3ee-d529e49acaf4",
    "status": "canceled_permanently",
    "webhook_type": "debt",
    "event_datetime": "2024-09-02 18:39:56"
}
```

### 2. Status Averbação

- WEBHOOK_TYPE debt
- STATUS credit_operation.collateral
- COLLATERAL_CONSTITUTED true

        *Body:*

**body.json**

```json
{
    "key": "2dabec49-780d-4742-a81b-a5b40a837386",
    "data": {
        "collateral_data": {},
        "collateral_type": "social_security",
        "collateral_constituted": true
    },
    "event_time": "2024-10-14 02:46:01",
    "webhook_type": "credit_operation.collateral"
}
```

- WEBHOOK_TYPE debt
- STATUS credit_operation.collateral
- COLLATERAL_CONSTITUTED false

        *Body:*

**body.json**

```json
{
    "key": "2dabec49-780d-4742-a81b-a5b40a837386",
    "data": {
        "collateral_data": {},
        "collateral_type": "social_security",
        "collateral_constituted": false
    },
    "event_time": "2024-10-14 08:46:01",
    "webhook_type": "credit_operation.collateral"
}
```

## Portabilidade Out

### 1. Notificação de recebimento de ataque de portabilidade

- WEBHOOK_TYPE credit_transfer.received_portability
- RECEIVED_PORTABILITY_STATUS received

        *Body:*

**body.json**

```json
{
    "webhook_type": "credit_transfer.received_portability",
    "received_portability_status": "received", 
    "received_portability_key": "673d2872-c6c9-4075-b9ab-4525bcbe4aa1",
    "event_datetime": "2022-07-24T18:29:45",  
    "data": {
        "annual_interest_rate": 1,
        "annual_effective_interest_rate": 1,
        "number_of_installments": 6,
        "installment_face_value": 201.71,
        "phone_number": "(05)541997558",
        "address": {
            "street": "Rua Longe de Casa",
            "city": "Rio de Janeiro",
            "state": "RJ",
            "number": "112",
            "postal_code": "38300569"
        },
        "due_balance": 1000,
        "due_balance_date": "2022-07-29",
        "issuer_name": "A Random Name",
        "issuer_document_number": "37197645832",
        "reference_date": "2022-08-01",
        "contract_number": "0000049045/UO",
        "origin_credit_operation_key": "key",
        "retention_limit_date": "2022-08-03", 
        "due_balance_limit_date": "2022-08-08", 
        "portability_number": "202207150000001642808",
        "corban_document_number": "08289470514408",
        "source_ispb_number": "0"
    }
}
```

### 2. Status

- WEBHOOK_TYPE credit_transfer.received_portability
- RECEIVED_PORTABILITY_STATUS waiting_settlement

        *Body:*

**body.json**

```json
{
  "webhook_type": "credit_transfer.received_portability",
  "received_portability_key": "673d2872-c6c9-4075-b9ab-4525bcbe4aa1",
  "received_portability_status": "waiting_settlement",
  "event_datetime": "2022-07-24T18:29:45",
  "data": {
    "settlement_due_balance": 120.00,
    "settlement_date": "2022-08-02"
  }
}
```

- WEBHOOK_TYPE credit_transfer.received_portability
- RECEIVED_PORTABILITY_STATUS canceled_by_proponent

        *Body:*

**body.json**

```json
{
  "webhook_type": "credit_transfer.received_portability",
  "received_portability_key": "673d2872-c6c9-4075-b9ab-4525bcbe4aa1",
  "received_portability_status": "canceled_by_proponent",
  "event_datetime": "2022-07-24T18:29:45",
  "data": {}
}
```

- WEBHOOK_TYPE credit_transfer.received_portability
- RECEIVED_PORTABILITY_STATUS settled

        *Body:*

**body.json**

```json
{
  "webhook_type": "credit_transfer.received_portability",
  "received_portability_key": "673d2872-c6c9-4075-b9ab-4525bcbe4aa1",
  "received_portability_status": "settled",
  "event_datetime": "2022-07-24T18:29:45Z",
  "data": {}
}
```

- WEBHOOK_TYPE credit_transfer.received_portability
- RECEIVED_PORTABILITY_STATUS canceled_by_creditor

        *Body:*

**body.json**

```json
{
  "webhook_type": "credit_transfer.received_portability",
  "received_portability_key": "673d2872-c6c9-4075-b9ab-4525bcbe4aa1",
  "received_portability_status": "canceled_by_creditor",
  "event_datetime": "2022-07-24T18:29:45",
  "data": {
   "canceled_reason": {
    "enumerator": "not_paid",
    "description": "Decurso de prazo por STR não paga dentro do prazo"
   }
  }
}
```

---

# Consultar saldo disponível

URL: /documentation/saque_aniversario_fgts/consultar_saldo_disponivel

## Request

ENDPOINT /baas/v2/fgts/available_balance
MÉTODO POST

Esse serviço permite consultar o saldo disponível do trabalhador no FGTS. Como resultado, o cliente visualiza as parcelas futuras disponíveis para os seus saques-aniversário.

A consulta de saldo na V2 é assíncrona. Portanto é feita uma requisição, e a resposta será dada por Webhook.

Webhook de Consulta recebido.

YOUR REQUEST HISTORY

Request Body

```json
{
   "document_number": "639.092.770-39"
}

```

### Body Params

| Campo | Descrição |
|---|---|
| `document_number` | CPF (apenas números) do titular da conta |

---

# Criar operação de crédito

URL: /documentation/saque_aniversario_fgts/criacao_da_operacao

## Request

ENDPOINT /baas/debt_fgts
MÉTODO POST

Request Body

```json
{
    "borrower": {
        "person_type": "natural",
        "name": "Patrícia Tereza Bernardes",
        "mother_name": "Maria Mariane",
        "birth_date": "1990-05-06",
        "profession": "Deputada",
        "nationality": "nationality",
        "marital_status": "married",
        "property_system": "total_communion_of_goods",
        "wedding_certificate": "56ab7849-4d90-490b-b539-96ac3c5a619b",
        "spouse": {
            "person_type": "natural",
            "name": "Patrícia Tereza Bernardes",
            "mother_name": "Maria Mariane",
            "birth_date": "1990-05-06",
            "profession": "Deputada",
            "nationality": "nationality",
            "marital_status": "married",
            "property_system": "total_communion_of_goods",
            "wedding_certificate": "56ab7849-4d90-490b-b539-96ac3c5a619b",
            "is_pep": false,
            "individual_document_number": "34651104630",
            "document_identification": "3c24579b-9810-4fa6-9b08-fe67d237160a",
            "document_identification_back": "2f43456a-3664-4805-82b8-96a2ec72c04c",
            "document_identification_type": "cnh",
            "document_identification_number": "232479719",
            "email": "api@qitech.com.br",
            "Phone": {
                "country_code": "055",
                "area_code": "11",
                "number": "999999999"
            },
            "address": {
                "street": "Av. Brigadeiro Faria Lima",
                "state": "SP",
                "city": "São Paulo",
                "neighborhood": "Jardim Paulistano",
                "number": "2391",
                "postal_code": "01452905",
                "complement": "1o. Andar"
            },
            "proof_of_residence": "780456bd-1eec-4e5f-82c0-d8c3921497ea"
        },
        "is_pep": false,
        "individual_document_number": "34651104630",
        "document_identification": "3c24579b-9810-4fa6-9b08-fe67d237160a",
        "document_identification_back": "2f43456a-3664-4805-82b8-96a2ec72c04c",
        "document_identification_type": "cnh",
        "document_identification_number": "232479719",
        "email": "api@qitech.com.br",
        "Phone": {
            "country_code": "055",
            "area_code": "11",
            "number": "999999999"
        },
        "address": {
            "street": "Av. Brigadeiro Faria Lima",
            "state": "SP",
            "city": "São Paulo",
            "neighborhood": "Jardim Paulistano",
            "number": "2391",
            "postal_code": "01452905",
            "complement": "1o. Andar"
        },
        "proof_of_residence": "780456bd-1eec-4e5f-82c0-d8c3921497ea"
    },
    "financial": {
        "interest_type": "pre_price_days",
        "credit_operation_type": "ccb",
        "annual_interest_rate": 0.05,
        "disbursement_date": "2022-07-25",
        "disbursement_start_date": "2022-07-27",
        "disbursement_end_date": "2022-07-27",
        "issue_date": "2019-07-25",
        "interest_grace_period": 0,
        "principal_grace_period": 0,
        "number_of_installments": 2,
        "fine_configuration": {
            "contract_fine_rate": 0,
            "interest_base": "workdays",
            "monthly_rate": 0
        }
    },
    "disbursement_bank_accounts": {
        "bank_code": "329",
        "branch_number": "001",
        "account_number": "15570",
        "account_digit": "4",
        "document_number": "94632180173",
        "name": "Pedro Felipe Henrique Alves",
        "percentage_receivable": 100,
        "ispb_number": 92874270,
        "pix_key": "qitech@qitech.com.br",
        "qr_code_key": "00020126580014br.gov.bcb.pix01366214e102-494c-4cf7-a99c-fd903d9f4aab5204000053039865802BR5911QI SCD S.A.6009sao paulo610912345-78062070503***6304C32E",
        "digitable_line": "00190500954014481606906809350314337370000000100"
    }
}

```

A simulação da operação retornará uma série de informações, no entanto, a de maior importância é o disbursed_issue_amount, que representa o valor líquido presente possível de se desembolsar. A partir dele é possível realizar os cálculos e, por fim, montar a operação no formato desejado e enviar a requisição.

**ATRIBUTOS DE UMA EMISSÃO DO SAQUE-ANIVERSÁRIO FGTS**

A criação da operação consiste em 4 objetos:

- borrower: tomador da dívida (objeto PF)
- collaterals: informações das parcelas de pagamento (objeto Collateral FGTS)
- financial: dados do fluxo financeiro da operação (Objeto Financeiro FGTS)
- disbursement_bank_accounts: lista de informações bancárias para o desembolso (Objeto Conta Bancária)

### Body Params

| Campo | Descrição |
|---|---|
| `borrower` *(obrigatório)* | Identificador de que o objeto enviado é uma pessoa física. Deve conter SEMPRE o valor "natural" para Objeto PF |
| `collaterals` *(obrigatório)* | Informações das parcelas de pagamento. |
| `financial` *(obrigatório)* | Contém todas as informações de um objeto Financial, mas com a adição dos desired installments, que representam os valores de cada parcela simulada pelo cliente. |
| `disbursement_bank_accounts` *(obrigatório)* | Uma emissão de dívida deve conter as informações bancárias para desembolso, por padrão, uma conta do tomador. Este objeto deve ser uma lista com uma ou mais contas. O Objeto Conta Bancária deve conter: |

### BORROWER OBJECT

| Campo | Descrição |
|---|---|
| `person_type` *(obrigatório)* | Identificador de que o objeto enviado é uma pessoa física. Deve conter SEMPRE o valor "natural" para Objeto PF |
| `name` *(obrigatório)* | Nome da pessoa |
| `mother_name` *(obrigatório)* | mother_name |
| `birth_date` *(obrigatório)* | Data de nascimento da pessoa (formato "AAAA-MM-DD") |
| `profession` *(obrigatório)* | Profissão da pessoa |
| `nationality` *(obrigatório)* | Nacionalidade da pessoa |
| `marital_status` *(obrigatório)* | Estado civil da pessoa: "single", "married", "widower" ou "divorced" |
| `property_system` | Regime de separação de bens (obrigatório apenas para pessoas com marital_status "married"): "total_communion_of_goods", "partial_communion_of_goods", "total_separation_of_goods", "final_participation_of_acquisitions" ou "compulsory_separation_of_goods" |
| `wedding_certificate` *(obrigatório)* | DOCUMENT_KEY do PDF do certificado de casamento da pessoa (enviado previamente). No caso de marital_status ser "single", o valor deste campo deve ser null |
| `spouse` *(obrigatório)* | Objeto PF do esposo/esposa da pessoa (obrigatório apenas quando "compulsory_separation_of_goods" for "total_communion_of_goods", "partial_communion_of_goods", "final_participation_of_acquisitions" ou "compulsory_separation_of_goods"). No caso de marital_status ser "single", o valor deste campo deve ser null |
| `is_pep` *(obrigatório)* | Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep) valor booleano |
| `individual_document_number` *(obrigatório)* | CPF da pessoa (apenas números) |
| `document_identification` *(obrigatório)* | DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) |
| `document_identification_back` | DOCUMENT_KEY do PDF da parte de trás do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) |
| `document_identification_type` | Qual o tipo do documento de identificação. Um enumerador que aceita "rg" ou "cnh" |
| `document_identification_number` *(obrigatório)* | Número do documento de identificação da pessoa enviado em document_identification |
| `email` | Email da pessoa |
| `phone` | Telefone da pessoa |
| `address` | Endereço da pessoa |
| `proof_of_residence` *(obrigatório)* | DOCUMENT_KEY do PDF do comprovante de endereço do endereço enviado (enviado previamente) |
| `ocr` | Objeto para entrega das chaves geradas pelo SDK de OCR |

### SPOUSE OBJECT

| Campo | Descrição |
|---|---|
| `person_type` *(obrigatório)* | Identificador de que o objeto enviado é uma pessoa física. Deve conter SEMPRE o valor "natural" para Objeto PF |
| `name` *(obrigatório)* | Nome da pessoa |
| `mother_name` *(obrigatório)* | mother_name |
| `birth_date` *(obrigatório)* | Data de nascimento da pessoa (formato "AAAA-MM-DD") |
| `profession` *(obrigatório)* | Profissão da pessoa |
| `nationality` *(obrigatório)* | Nacionalidade da pessoa |
| `marital_status` *(obrigatório)* | Estado civil da pessoa: "single", "married", "widower" ou "divorced" |
| `property_system` | Regime de separação de bens (obrigatório apenas para pessoas com marital_status "married"): "total_communion_of_goods", "partial_communion_of_goods", "total_separation_of_goods", "final_participation_of_acquisitions" ou "compulsory_separation_of_goods" |
| `wedding_certificate` *(obrigatório)* | DOCUMENT_KEY do PDF do certificado de casamento da pessoa (enviado previamente). No caso de marital_status ser "single", o valor deste campo deve ser null |
| `spouse` *(obrigatório)* | Objeto PF do esposo/esposa da pessoa (obrigatório apenas quando "compulsory_separation_of_goods" for "total_communion_of_goods", "partial_communion_of_goods", "final_participation_of_acquisitions" ou "compulsory_separation_of_goods"). No caso de marital_status ser "single", o valor deste campo deve ser null |
| `is_pep` *(obrigatório)* | Declaração se a pessoa é PEP (http://www.portaldatransparencia.gov.br/download-de-dados/pep) valor booleano |
| `individual_document_number` *(obrigatório)* | CPF da pessoa (apenas números) |
| `document_identification` *(obrigatório)* | DOCUMENT_KEY do PDF do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) |
| `document_identification_back` | DOCUMENT_KEY do PDF da parte de trás do documento de identificação da pessoa com foto (RG ou CNH) (enviado previamente) |
| `document_identification_type` | Qual o tipo do documento de identificação. Um enumerador que aceita "rg" ou "cnh" |
| `document_identification_number` *(obrigatório)* | Número do documento de identificação da pessoa enviado em document_identification |
| `email` | Email da pessoa |
| `phone` | Telefone da pessoa |
| `address` | Endereço da pessoa |
| `proof_of_residence` *(obrigatório)* | DOCUMENT_KEY do PDF do comprovante de endereço do endereço enviado (enviado previamente) |
| `ocr` | Objeto para entrega das chaves geradas pelo SDK de OCR |

### PHONE OBJECT

| Campo | Descrição |
|---|---|
| `country_code` *(obrigatório)* | Código DDI do telefone (https://ddi.guiamais.com.br/)(deve ter obrigatoriamente 3 dígitos). |
| `area_code` *(obrigatório)* | Código DDD do telefone (https://ddd.guiamais.com.br/).) |
| `number` *(obrigatório)* | Número de telefone (apenas números). |
| `document_number` *(obrigatório)* | Numero de documento do signatário. |

### ADDRESS OBJECT

| Campo | Descrição |
|---|---|
| `street` *(obrigatório)* | Rua do endereço. |
| `state` *(obrigatório)* | Estado do endereço (com dois caracteres maiúsculos). |
| `city` *(obrigatório)* | Cidade do endereço. |
| `neighborhood` *(obrigatório)* | Bairro do endereço. |
| `number` *(obrigatório)* | Número da rua. |
| `postal_code` *(obrigatório)* | CEP do endereço (http://www.buscacep.correios.com.br/sistemas/buscacep/) (apenas números). |
| `complement` *(obrigatório)* | Complemento do endereço (texto livre). |

### OCR OBJECT

| Campo | Descrição |
|---|---|
| `ocr` | Objeto para entrega das chaves geradas pelo SDK de OCR |

### COLLATERALS OBJECT

| Campo | Descrição |
|---|---|
| `percentage` | Porcentagem da garantia (vai de 0 a 1) |
| `collateral_type` *(obrigatório)* | Tipo de collateral. No caso do FGTS, precisa ser "fgts_balance" |
| `collateral_data` |  |

### COLLATERAL DATA OBJECT

| Campo | Descrição |
|---|---|
| `total_amount` *(obrigatório)* | Valor amortizado em determinada data |
| `due_date` | Data Hora do Pedido (formato "AAAA-MM-DD") |

### FINANCIAL OBJECT

| Campo | Descrição |
|---|---|
| `desired_installments` | Valor de desembolso para o cliente |
| `interest_type` *(obrigatório)* | Tipo de juros aplicado na dívida. |
| `credit_operation_type` *(obrigatório)* | Tipo de operação de crédito: "ccb", "cce", "cci", "nce" |
| `annual_interest_rate` *(obrigatório)* | Valor porcentual da parcela prefixada de juros (atenção: 1 = 100%) |
| `disbursement_date` | Data de desembolso (formato "AAAA-MM-DD") (excludente de disbursement_date) |
| `disbursement_start_date` | Data inicial do período de desembolso (formato "AAAA-MM-DD") (excludente de disbursement_date) |
| `disbursement_end_date` | Data final do período de desembolso (formato "AAAA-MM-DD") (excludente de disbursement_date) |
| `issue_date` | Data de emissão da CCB (formato "AAAA-MM-DD") |
| `interest_grace_period` | Carência de juros (em meses) |
| `principal_grace_period` | Carência do principal (em meses) |
| `number_of_installments` | Número de parcelas (anuais) |
| `fine_configuration` | configuração das multas |
| `rebates` | Lista de objetos de rebates. |

### REBATES OBJECT

| Campo | Descrição |
|---|---|
| `amount` | Valor do rebate. |
| `fee_type` | Tipo de fee |
| `amount_type` | Tipo do valor inserido (valor absoluto, valor em porcentagem) |
| `rebate_bank_account` | Objeto conta bancária de rebate. |

### FINE CONFIGURATION OBJECT

| Campo | Descrição |
|---|---|
| `contract_fine_rate` *(obrigatório)* | Valor porcentual fixo da multa |
| `interest_base` | Contagem do tempo para multa ("calendar_days" para dias corridos, "workdays" para dias úteis) |
| `monthly_rate` | Valor porcentual mensal da multa |

### DISBURSEMENT BANK ACCOUNT OBJECT

| Campo | Descrição |
|---|---|
| `bank_code` *(obrigatório)* | Identificador da instituição no Sistema de Pagamentos Brasileiro - Obrigatório apenas se o COMPE não for enviado. |
| `branch_number` *(obrigatório)* | Número da agência |
| `account_number` *(obrigatório)* | Número da conta |
| `account_digit` | Dígito verificador da conta (obrigatório caso haja) |
| `document_number`| CPF ou CNPJ do dono da conta para desembolso (obrigatório caso haja mais de uma conta para desembolso) |
| `name`  |Nome do dono da conta para desembolso (obrigatório caso haja mais de uma conta para desembolso) |
| `percentage_receivable` | Valor em porcentagem que a conta receberá no desembolso. Este campo é utilizado para definir a quantidade a ser dividida caso haja mais de uma conta para desembolso (no caso de ser somente uma conta, o valor integral será transferido). Caso a porcentagem não seja enviada (de uma, ou de todas as contas), a porcentagem restante será dividida igualmente entre as contas sem porcentagem definida. Caso todas as porcentagens sejam enviadas, a soma delas não pode passar de 100 |
| `ispb_number` | Identificador de Sistema de Pagamentos Brasileiro |
| `pix_key`  | Chave Pix |
| `qr_code_key` | Chave fornecida no momento da criação de um QR Code |
| `digitable_line` | Representação numérica do código de barras do boleto |

---

# Introdução ao Saque Aniversário FGTS

URL: /documentation/saque_aniversario_fgts/introducao

Conforme publicado pela lei 8.036 e regulamentado pela lei 13.932 de 2019, o trabalhador que possui conta vinculada do FGTS pode optar pela sistemática do Saque Aniversário, em alternativa à sistemática do Saque Rescisão do contrato de trabalho. A opção pelo Saque Aniversário permite a retirada de parte do saldo da(s) conta(s) vinculada(s) do FGTS, anualmente, no mês do seu aniversário.

### Pré requisitos para implementação

Para emitir operações de crédito FGTS é necessário primeiro realizar homologação de api na sandbox
Realizar roteiro de homologação

---

# roteiro_de_homologacao

URL: /documentation/saque_aniversario_fgts/roteiro_de_homologacao

## Roteiro de Homologação

Passo a passo para o consumo de serviços de antecipação do saque-aniversário FGTS em ambiente de homologação

Conforme publicado pela lei 8.036 e regulamentado pela lei 13.932 de 2019, o trabalhador que possui conta vinculada do FGTS pode optar pela sistemática do Saque Aniversário, em alternativa à sistemática do Saque Rescisão do contrato de trabalho. A opção pelo Saque Aniversário permite a retirada de parte do saldo da(s) conta(s) vinculada(s) do FGTS, anualmente, no mês do seu aniversário.

Por meio desta, é garantido a qualquer pessoa física receber nos próximos dias (a ser definido no momento de criação da operação) um montante cujo empréstimo terá como garantia até 7 anos das parcelas que originalmente tem o direito de resgatar no mês de seu aniversário.

## FGTS 

Fundo de Garantia do Tempo de Serviço (FGTS) é um fundo criado com o objetivo de proteger o trabalhador que for demitido sem justa causa. Mediante a abertura de uma conta vinculada ao contrato de trabalho, os empregadores depositam em contas abertas na Caixa Econômica Federal, no início de cada mês e em nome dos empregados, o valor correspondente a 8% do salário bruto de cada funcionário.

Nos próximos tópicos utilizaremos os termos:

- **Averbação**: Registro das parcelas do saque-aniversário FGTS como garantia da operação de crédito;
- **Desaverbação**: Liberação das parcelas devido ao cancelamento da operação ou quitação da dívida.

## Operação de Crédito

A QI Tech é uma Sociedade de Crédito Direto (SCD) com copetência de emitir operações de crédito com garantia nas parcelas do saque-aniversário FGTS por meio da emissão de Cédulas de Crédito Bancário (CCBs) cujo valor deve ser desembolsado na conta da pessoa que o contrata.

Nos próximos tópicos utilizaremos os termos:

- **SCD**: Conforme Art. 3o. da RESOLUÇÃO No. 4.656, DE 26 DE ABRIL DE 2018 a SCD é instituição financeira que tem por objeto a realização de operações de empréstimo, de financiamento e de aquisição de direitos creditórios exclusivamente por meio de plataforma eletrônica, com utilização de recursos financeiros que tenham como única origem capital próprio.
- **Tomador**: Pessoa física (detentora de CPF) que receberá o empréstimo
- **Credor**: Pessoa jurídica (detentora de CNPJ) a quem compete a capacidade de emitir operações de crédito, aqui representada pela QI Tech,
- **Originador**: Pessoa jurídica (detentora de CNPJ) que utilizará dos serviços da QI Tech para iniciar a operação de crédito a ser desembolsada para a conta do tomador
- **CCB**: Conforme Art. 1o. da MEDIDA PROVISÓRIA No 1.925-15, DE 14 DE DEZEMBRO DE 2000, a Cédula de Crédito Bancário é título de crédito emitido, por pessoa física ou jurídica, em favor de instituição financeira ou de entidade a esta equiparada, representando promessa de pagamento em dinheiro, decorrente de operação de crédito, de qualquer modalidade.
- **FIDC**: Fundo de Investimento em Direitos Creditórios são fundos responsáveis por converter uma dívida em título negociável, que pode ser vendido a uma investidora a preços reduzidos

## Serviços via API

Para que uma operação de antecipação de saque-aniversário FGTS seja completa em ambiente de homologação no nível de consumo de serviços via API os seguintes serviços devem ser utilizados com sucesso:

1. Consultar saldo disponível
2. Simulação do valor máximo
3. Simulação por valor desejado (opcional)
4. Envio de documentos
5. Criação de operação
6. Entrega de operação assinada pelo tomador
7. Recálculo de operação
8. Cancelamento de operação
9. Desaverbação

É importante mencionar que o originador esteja apto a receber webhooks (via método POST) em uma url cadastrada em nossa plataforma. Devido à assincronia no processo de assinatura da CCB pelo tomador, quando assinada, o documento resultante será enviado via webhook à url cadastrada pelo originador.

:::tip **A partir de quando começamos a operar em ambiente produtivo?**

Em conjunto com os setores comercial e jurídico entre as partes interessadas, ou seja:

- Credora (QiTech)
- Originadora
- FIDC
- Securitizadora (opcional)

A QI Tech identifica que uma integração está homologada quando estão concluídos:

1. Contrato de acordo de parceria
2. Acordo de correspondente bancário (CORBAN)
3. CCB emitida confere em cláusulas e valores (memória de cálculo)
4. Acordo de formas de cobrança de tarifas da QI e rebates
5. Formalização de veículos (QI, Fundo, Securitizadora) e minutas de cessão
6. Formalização de CNPJ e representantes da originadora que operarão em ambiente produtivo

:::

---

# Simulação do valor desejado

URL: /documentation/saque_aniversario_fgts/simulacao_do_valor_desejado

## Request
ENDPOINT /baas/fgts_simulation_guess
MÉTODO POST

Esse serviço mostra qual é o valor máximo que pode ser antecipado pelo tomador, de acordo com as parcelas informadas.

Como originador, é possível informar qual valor o tomador poderá desembolsar de cada parcela, sendo isso individual ou parcelas múltiplas.

Request Body

```json
{
    "target_disbursed_amount": 1000,
    "borrower": {
      "person_type": "natural"
    },
    "financial": {
        "interest_type": "pre_price_days",
        "credit_operation_type": "ccb",
        "annual_interest_rate": 0.05,
        "disbursement_date": "2022-07-25",
        "disbursement_start_date": "2022-07-27",
        "disbursement_end_date": "2022-07-27",
        "issue_date": "2019-07-25",
        "interest_grace_period": 0,
        "principal_grace_period": 0,
        "number_of_installments": 2,
        "fine_configuration": {
            "contract_fine_rate": 0,
            "interest_base": "workdays",
            "monthly_rate": 0
        }
    }
}

```

### Body Params

| Campo | Descrição                                                                         |
|---|-----------------------------------------------------------------------------------|
| `target_disbursed_amount` *(obrigatório)* | Valor de desembolso desejado para a operação de crédito                           |
| `borrower` *(obrigatório)* | Tomador da dívida, neste caso precisamos apenas do tipo de pessoa ("person_type") |
| `financial` | Objeto Financial (adaptado para o saque-aniversário FGTS)                         |

### BORROWER OBJECT

| Campo | Descrição |
|---|---|
| `person_type` *(obrigatório)* | Tomador da dívida, neste caso precisamos apenas do tipo de pessoa ("person_type") |

### FINANCIAL OBJECT

| Campo | Descrição |
|---|---|
| `desired_installments` | Valor de desembolso para o cliente |
| `interest_type` *(obrigatório)* | Tipo de juros aplicado na dívida. |
| `credit_operation_type` *(obrigatório)* | Tipo de operação de crédito: "ccb", "cce", "cci", "nce" |
| `annual_interest_rate` *(obrigatório)* | Valor porcentual da parcela prefixada de juros (atenção: 1 = 100%) |
| `disbursement_date`  | Data de desembolso (formato "AAAA-MM-DD") (excludente de disbursement_date) |
| `disbursement_start_date` *(obrigatório)* | Data inicial do período de desembolso (formato "AAAA-MM-DD") (excludente de disbursement_date) |
| `disbursement_end_date` *(obrigatório)* | Data final do período de desembolso (formato "AAAA-MM-DD") (excludente de disbursement_date) |
| `issue_date` *(obrigatório)* | Data de emissão da CCB (formato "AAAA-MM-DD") |
| `interest_grace_period` *(obrigatório)* | Carência de juros (em meses) |
| `principal_grace_period` *(obrigatório)* | Carência do principal (em meses) |
| `number_of_installments` *(obrigatório)* | Número de parcelas (anuais) |
| `fine_configuration` *(obrigatório)* | configuração das multas |
| `rebates` *(obrigatório)* | Lista de objetos de rebates. |

### DESIRED INSTALLMENTS OBJECT

| Campo | Descrição |
|---|---|
| `total_amount` *(obrigatório)* | Valor amortizado em determinada data |
| `due_date` | Data Hora do Pedido (formato "AAAA-MM-DD") |

### FINE CONFIGURATION OBJECT

| Campo | Descrição |
|---|---|
| `contract_fine_rate` *(obrigatório)* | Valor porcentual fixo da multa |
| `interest_base` | Contagem do tempo para multa ("calendar_days" para dias corridos, "workdays" para dias úteis) |
| `monthly_rate` | Valor porcentual mensal da multa |

### REBATES OBJECT

| Campo | Descrição |
|---|---|
| `amount` | Valor do rebate. |
| `fee_type` | Tipo de fee |
| `amount_type` | Tipo do valor inserido (valor absoluto, valor em porcentagem) |
| `rebate_bank_account` | Objeto conta bancária de rebate. |

### REBATES BANK ACCOUNT OBJECT

| Campo | Descrição |
|---|---|
| `name` | Nome da instituição financeira |
| `bank_code` | Código COMPE da instituição financeira (https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf) com 3 dígitos. |
| `ispb_number` | Identificador da instituição no Sistema de Pagamentos Brasileiro. |
| `account_digit` | Dígito da conta. |
| `branch_number` | Número da agência |
| `account_number` | Número da conta. |
| `document_number` | CPF ou CNPJ do dono da conta para o rebate. |

---

# Simulação do valor máximo

URL: /documentation/saque_aniversario_fgts/simulacao_do_valor_maximo

## Request

ENDPOINT /baas/fgts_simulation
MÉTODO POST

Esse serviço mostra qual é o valor máximo que pode ser antecipado pelo tomador, de acordo com as parcelas informadas.

Como originador, é possível informar qual valor o tomador poderá desembolsar de cada parcela, sendo isso individual ou parcelas múltiplas.

Request Body

```json
{
    "borrower": {
      "person_type": "natural"
    },
    "financial": {
        "interest_type": "pre_price_days",
        "credit_operation_type": "ccb",
        "annual_interest_rate": 0.05,
        "disbursement_date": "2022-07-25",
        "disbursement_start_date": "2022-07-27",
        "disbursement_end_date": "2022-07-27",
        "issue_date": "2019-07-25",
        "interest_grace_period": 0,
        "principal_grace_period": 0,
        "number_of_installments": 2,
        "fine_configuration": {
            "contract_fine_rate": 0,
            "interest_base": "workdays",
            "monthly_rate": 0
        }
    }
}

```

### Body Params

| Campo | Descrição |
|---|---|
| `borrower` *(obrigatório)* | Tomador da dívida, neste caso precisamos apenas do tipo de pessoa ("person_type") |
| `financial` | Objeto Financial (adaptado para o saque-aniversário FGTS) |

### BORROWER OBJECT

| Campo | Descrição |
|---|---|
| `person_type` *(obrigatório)* | Tomador da dívida, neste caso precisamos apenas do tipo de pessoa ("person_type") |

### FINANCIAL OBJECT

| Campo | Descrição |
|---|---|
| `desired_installments` | Valor de desembolso para o cliente |
| `interest_type` *(obrigatório)* | Tipo de juros aplicado na dívida. |
| `credit_operation_type` *(obrigatório)* | Tipo de operação de crédito: "ccb", "cce", "cci", "nce" |
| `annual_interest_rate` *(obrigatório)* | Valor porcentual da parcela prefixada de juros (atenção: 1 = 100%) |
| `disbursement_date`  | Data de desembolso (formato "AAAA-MM-DD") (excludente de disbursement_date) |
| `disbursement_start_date` *(obrigatório)* | Data inicial do período de desembolso (formato "AAAA-MM-DD") (excludente de disbursement_date) |
| `disbursement_end_date` *(obrigatório)* | Data final do período de desembolso (formato "AAAA-MM-DD") (excludente de disbursement_date) |
| `issue_date` *(obrigatório)* | Data de emissão da CCB (formato "AAAA-MM-DD") |
| `interest_grace_period` *(obrigatório)* | Carência de juros (em meses) |
| `principal_grace_period` *(obrigatório)* | Carência do principal (em meses) |
| `number_of_installments` *(obrigatório)* | Número de parcelas (anuais) |
| `fine_configuration` *(obrigatório)* | configuração das multas |
| `rebates` *(obrigatório)* | Lista de objetos de rebates. |

### DESIRED INSTALLMENTS OBJECT

| Campo | Descrição |
|---|---|
| `total_amount` *(obrigatório)* | Valor amortizado em determinada data |
| `due_date` | Data Hora do Pedido (formato "AAAA-MM-DD") |

### FINE CONFIGURATION OBJECT

| Campo | Descrição |
|---|---|
| `contract_fine_rate` *(obrigatório)* | Valor porcentual fixo da multa |
| `interest_base` | Contagem do tempo para multa ("calendar_days" para dias corridos, "workdays" para dias úteis) |
| `monthly_rate` | Valor porcentual mensal da multa |

### REBATES OBJECT

| Campo | Descrição |
|---|---|
| `amount` | Valor do rebate. |
| `fee_type` | Tipo de fee |
| `amount_type` | Tipo do valor inserido (valor absoluto, valor em porcentagem) |
| `rebate_bank_account` | Objeto conta bancária de rebate. |

### REBATES BANK ACCOUNT OBJECT

| Campo | Descrição |
|---|---|
| `name` | Nome da instituição financeira |
| `bank_code` | Código COMPE da instituição financeira (https://www.bcb.gov.br/pom/spb/estatistica/port/ASTR003.pdf) com 3 dígitos. |
| `ispb_number` | Identificador da instituição no Sistema de Pagamentos Brasileiro. |
| `account_digit` | Dígito da conta. |
| `branch_number` | Número da agência |
| `account_number` | Número da conta. |
| `document_number` | CPF ou CNPJ do dono da conta para o rebate. |

---

# Webhooks de Consulta de Saldo

URL: /documentation/saque_aniversario_fgts/webhooks_de_consulta_de_saldo

O webhook retornado terá duas opções. Ou ele retorna um sucesso, ou uma falha.

Em caso de sucesso:

Response Body

```json
{
    "key": "843ab07e-b16f-4dfa-b048-37c464483aa5",
    "status": "success",
    "webhook_type": "fgts_available_balance",
    "event_datetime": "2022-07-14T18:31:29",
    "data": {
        "reference_date": "2022-07-14",
        "periods": [{
                "amount": 776.41,
                "due_date": "2023-01-01"
            },
            {
                "amount": 508.25,
                "due_date": "2024-01-01"
            },
            {
                "amount": 286,
                "due_date": "2025-01-01"
            }
        ]
    }
}

```

Em caso de falha:

Request Body

```json
{
    "key": "843ab07e-b16f-4dfa-b048-37c464483aa5",
    "status": "failed",
    "webhook_type": "fgts_available_balance",
    "event_datetime": "2022-07-14T18:31:29",
    "data": {
        "enumerator": "unauthorized_institution",
        "description": "Institution isn’t authorized by the client"
    }
}

```

**Erros existentes na consulta:**

Os erros existentes são:

| Dígitos do CPF | Enumerador |Descrição |
|---|---|---|
| 90 | ongoing_operation | There's an ongoing operation |
| 91 | unauthorized_institution | Institution isn't authorized by the client |
| 92 | inexistent_anniversary_membership | Client does not have membership for anniversary withdraw on current date |
| 93 | on_locked_date_range | Not permitted action on current date |
| 94 | anniversary_membership_egress | Client moving away from anniversary membership. It needs to be canceled before requesting a reserve |
| 95 | processing_pending_changes | Changes on client's FGTS account are still being processed |
| 96, 97, 98 e 99 | caixa_error | Request wasn't able to process due to an error on CEF |

---

# Cancelar apólice

URL: /documentation/seguros/apolices/cancelar_apolice

Cancela uma **única** apólice; as demais apólices do mesmo pedido não são afetadas. O cancelamento é sempre **assíncrono e em duas fases**: a solicitação coloca a apólice em `cancellation_requested` e o cancelamento efetivo (`canceled`) só ocorre quando a seguradora confirma — até lá, a cobertura permanece em vigor.

Para cancelar **todas** as apólices de um pedido de uma vez, use o [cancelamento do pedido](/documentation/seguros/pedidos/cancelar_pedido) em um pedido emitido.

## Devolução de prêmio

Na confirmação do cancelamento, a QI Tech determina a base e calcula o valor da devolução automaticamente, sobre o prêmio bruto (`gross_premium_amount`):

| Momento do cancelamento | Base de devolução |
|---|---|
| Até 7 dias corridos da confirmação da emissão (`issued`) — direito de arrependimento | Devolução **integral** do prêmio. |
| Após 7 dias | Devolução **proporcional** ao período de cobertura não decorrido (pró-rata). |

A confirmação do cancelamento chega pelo [webhook de cancelamento](/documentation/seguros/apolices/webhooks#apolice-cancelada) e a devolução ao pagador é executada pela QI Tech.

## Request

ENDPOINT /v1/insurance/policies/{policy_key}/cancel
MÉTODO POST

### Path params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `policy_key` | string | obrigatório | Chave da apólice. |

```json title="Request Body"
{
  "reason": "Cliente solicitou o cancelamento"
}
```

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `reason` | string | opcional | Motivo do cancelamento, registrado na trilha de eventos e ecoado no webhook de cancelamento. |

## Response

STATUS 202

```json title="Response Body"
{
  "policy_key": "0b6e7c1a-9a4e-4c1e-b1d4-2f5a8c9e0d31",
  "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
  "status": "cancellation_requested"
}
```

A conclusão do cancelamento chega pelo [webhook de apólice](/documentation/seguros/apolices/webhooks) com status `canceled`, e pode ser acompanhada pela [consulta de apólice](/documentation/seguros/apolices/consultar_apolice).

### Semântica por status

| Status atual da apólice | Resultado |
|---|---|
| `issued` | `202` — cancelamento solicitado à seguradora. |
| `cancellation_requested` | `202` — idempotente: não gera segunda solicitação e retorna o mesmo corpo. |
| `issuance_requested` | `409` — a apólice ainda não está em vigor. Para desfazer a venda inteira nesse estágio, cancele o **pedido** (a solicitação fica retida e cancela a apólice automaticamente assim que a emissão confirmar); para cancelar só esta apólice, aguarde a emissão confirmar. |
| `canceled` | `409` — já cancelada. |
| `finished` | `409` — a vigência já terminou. |
| outra integração / inexistente | `404` |

## Possíveis erros

Todo erro (`non-2xx`) retorna o corpo padrão `{ "title", "description", "translation", "code" }` — trate programaticamente **apenas** o campo `code`.

| Status | Código | Descrição |
|---|---|---|
| `401` / `403` | — | Falha de autenticação ou autorização. |
| `404` | `POL000001` | Apólice inexistente ou pertencente a outra integração. |
| `409` | `POL000010` | A apólice já foi cancelada. |
| `409` | `POL000011` | A vigência da cobertura já terminou. |
| `409` | `POL000012` | A apólice ainda não está em vigor. |
| `429` | — | Limite de requisições excedido — repita com backoff. |
| `500` | `QIT000500` | Erro interno — a solicitação é idempotente, repita a chamada. |
| `503` | `POL000030` | Serviço indisponível — a solicitação é idempotente, repita a chamada. |

---

# Consultar apólice

URL: /documentation/seguros/apolices/consultar_apolice

Retorna o detalhe de uma apólice: identidade e chaves de correlação, status, número da apólice na seguradora, a classificação do produto, a decomposição do prêmio (bruto, IOF e líquido), a vigência, as coberturas efetivas e a trilha de eventos.

## Request

ENDPOINT /v1/insurance/policies/{policy_key}
MÉTODO GET

### Path params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `policy_key` | string | obrigatório | Chave da apólice, obtida na [listagem por pedido](/documentation/seguros/apolices/listar_apolices) ou nos [webhooks de apólice](/documentation/seguros/apolices/webhooks). |

## Response

STATUS 200

```json title="Response Body"
{
  "policy_key": "0b6e7c1a-9a4e-4c1e-b1d4-2f5a8c9e0d31",
  "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
  "provider_product_key": "9d1f8c7a-3b21-4e60-8a2f-1c5d7e9b0a44",
  "provider_key": "c4a2e8b0-1f6d-4e3a-9c7b-5d0a2e8f4b61",
  "status": "issued",
  "external_policy_number": "APL-2026-000123",
  "customer_document_number": "96969879003",
  "product_category": "insurance",
  "insurance_class": {
    "name": "credit_life",
    "class_number": "0977",
    "group_number": "09"
  },
  "regulator_registration": "15414.900388/2015-21",
  "gross_premium_amount": 617.28,
  "iof_amount": 2.35,
  "net_premium_amount": 614.93,
  "term": {
    "start_date": "2026-07-16",
    "end_date": "2027-07-15"
  },
  "effective_services": [
    {
      "effective_service_key": "7f3a9c2e-0b5d-4e8a-a1c6-9d4b2e7f0a53",
      "provider_service_key": "0a3c5e7f-2b4d-4a6c-8e0f-1a3b5c7d9e2f",
      "service_type": {
        "code": "credit_life",
        "name": "Prestamista (Credit Life)"
      },
      "service_category": "insurance",
      "regulator_registration": null,
      "insured_amount": 150000.00,
      "gross_premium_amount": 617.28,
      "deductible_data": {
        "deductible_type": "monetary_amount",
        "value": 1500.00
      },
      "waiting_period_days": 30,
      "service_attributes": {},
      "term": {
        "start_date": "2026-07-16",
        "end_date": "2027-07-15"
      }
    }
  ],
  "events": [
    {
      "new_status": "issuance_requested",
      "agent_type": "system",
      "created_at": "2026-07-16T14:03:25.481Z"
    },
    {
      "new_status": "issued",
      "agent_type": "provider",
      "created_at": "2026-07-16T15:00:00.000Z"
    }
  ]
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `policy_key` | string | Chave única da apólice. |
| `order_key` | string | Chave do pedido que originou a apólice. |
| `provider_product_key` | string | Chave do produto no catálogo. |
| `provider_key` | string | Chave da seguradora emissora. |
| `status` | string | Status atual. Veja o [ciclo de vida](/documentation/seguros/apolices/inicio). |
| `external_policy_number` | string | Número da apólice na seguradora. `null` até a emissão ser confirmada (`issued`). |
| `customer_document_number` | string | Documento do segurado. |
| `product_category` | string | Categoria do produto: `insurance`, `capitalization` ou `benefit`. |
| `insurance_class` | object | Ramo do seguro: `{ name, class_number, group_number }`. `null` para produtos não securitários. `class_number` e `group_number` são strings — os zeros à esquerda são significativos. |
| `regulator_registration` | string | Registro do produto no regulador (ex.: processo SUSEP). |
| `gross_premium_amount` | number | Prêmio bruto (o valor pago pelo segurado), com IOF. |
| `iof_amount` | number | Componente de IOF do prêmio. |
| `net_premium_amount` | number | Prêmio líquido (bruto menos IOF). |
| `term` | object | Vigência da apólice: `{ start_date, end_date }`. |
| `effective_services` | array | Coberturas efetivas da apólice. |
| `events` | array | Trilha de transições de status, em ordem cronológica — é dela que se derivam os instantes do ciclo de vida (emissão, solicitação de cancelamento, cancelamento). |

#### Objeto em `effective_services`

| Campo | Tipo | Descrição |
|---|---|---|
| `effective_service_key` | string | Chave única da cobertura efetiva. |
| `provider_service_key` | string | Chave da cobertura no catálogo. |
| `service_type` | object | Tipo da cobertura: `{ code, name }`. |
| `service_category` | string | Categoria da cobertura: `insurance`, `capitalization` ou `benefit`. |
| `regulator_registration` | string | Registro próprio da cobertura no regulador. `null` quando herda o do produto. |
| `insured_amount` | number | Importância segurada contratada. |
| `gross_premium_amount` | number | Prêmio bruto da cobertura. |
| `deductible_data` | object | Franquia contratada: `{ deductible_type, value }`. |
| `waiting_period_days` | integer | Carência em dias. |
| `service_attributes` | object | Atributos fixos da cobertura. |
| `term` | object | Vigência da cobertura: `{ start_date, end_date }`. |

#### Objeto em `events`

| Campo | Tipo | Descrição |
|---|---|---|
| `new_status` | string | O status assumido na transição. |
| `agent_type` | string | Quem causou a transição: `requester` (sua integração), `provider` (seguradora), `system` (automático) ou `operator` (operação QI Tech). |
| `created_at` | string | Instante da transição. |

## Possíveis erros

Todo erro (`non-2xx`) retorna o corpo padrão `{ "title", "description", "translation", "code" }` — trate programaticamente **apenas** o campo `code`.

| Status | Código | Descrição |
|---|---|---|
| `401` / `403` | — | Falha de autenticação ou autorização. |
| `404` | `POL000001` | Apólice inexistente ou pertencente a outra integração — os casos são indistinguíveis. |
| `429` | — | Limite de requisições excedido — repita com backoff. |
| `500` | `QIT000500` | Erro interno — seguro repetir a chamada. |
| `503` | `POL000030` | Serviço indisponível — seguro repetir a chamada. |

---

# Início

URL: /documentation/seguros/apolices/inicio

A **apólice** (`policy`) é o contrato de seguro individual — uma por produto vendido em um pedido emitido. Ela nasce na emissão do pedido, é registrada junto à seguradora e passa a ser a fonte da verdade sobre a cobertura: número de apólice na seguradora, vigência, coberturas efetivas, prêmio decomposto e trilha de eventos.

## Ciclo de vida da apólice

![Fluxo de status da apólice, da solicitação de emissão ao encerramento](/img/diagrams/seguros-apolices-inicio.svg)

_Como ler o diagrama: **contorno tracejado** = status transitório que não gera webhook · **azul** = emissão confirmada (gera webhook) · **verde** = encerramento natural (não gera webhook) · **vermelho** = cancelada (gera webhook)._

| Status | Significado |
|---|---|
| `issuance_requested` | Apólice criada na emissão do pedido; a emissão foi solicitada à seguradora e aguarda confirmação. |
| `issued` | A seguradora confirmou a emissão. O `external_policy_number` (número da apólice na seguradora) passa a estar disponível. A cobertura está em vigor. |
| `cancellation_requested` | Um cancelamento foi solicitado e aguarda a confirmação da seguradora. **A cobertura permanece em vigor** enquanto o cancelamento não é confirmado. |
| `canceled` | A seguradora confirmou o cancelamento. A devolução de prêmio, quando devida, é calculada e processada automaticamente. |
| `finished` | A vigência da apólice chegou ao fim naturalmente (`term.end_date`). Status terminal, sem evento — o fim de vigência é conhecido desde a emissão. |

## Devolução de prêmio no cancelamento

Quando um cancelamento é confirmado, a QI Tech determina a base de devolução e calcula o valor automaticamente, sobre o prêmio bruto (`gross_premium_amount`):

- **Dentro de 7 dias corridos** da confirmação da emissão (`issued`) — direito de arrependimento: devolução **integral** do prêmio.
- **Após 7 dias**: devolução **proporcional** ao período de cobertura não decorrido (pró-rata).

A devolução é calculada na confirmação do cancelamento e executada ao pagador pela própria QI Tech.

## Endpoints

| Endpoint | Descrição |
|---|---|
| [`GET /v1/insurance/policies/{policy_key}`](/documentation/seguros/apolices/consultar_apolice) | Detalha uma apólice. |
| [`GET /v1/insurance/policies?order_key=`](/documentation/seguros/apolices/listar_apolices) | Lista as apólices de um pedido emitido. |
| [`POST /v1/insurance/policies/{policy_key}/cancel`](/documentation/seguros/apolices/cancelar_apolice) | Cancela uma apólice individualmente. |

---

# Listar apólices de um pedido

URL: /documentation/seguros/apolices/listar_apolices

Lista as apólices geradas por um pedido emitido — **a** forma de descobrir as `policy_key` de um pedido, já que a consulta de pedido não retorna apólices. Retorna resumos; para o detalhe completo, use a [consulta de apólice](/documentation/seguros/apolices/consultar_apolice).

## Request

ENDPOINT /v1/insurance/policies
MÉTODO GET

### Query params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `order_key` | string | obrigatório | Chave do pedido cujas apólices serão listadas. |

```python title="Exemplo de chamada"
GET /v1/insurance/policies?order_key=5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90
```

## Response

STATUS 200

```json title="Response Body"
{
  "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
  "policies": [
    {
      "policy_key": "0b6e7c1a-9a4e-4c1e-b1d4-2f5a8c9e0d31",
      "provider_product_key": "9d1f8c7a-3b21-4e60-8a2f-1c5d7e9b0a44",
      "provider_key": "c4a2e8b0-1f6d-4e3a-9c7b-5d0a2e8f4b61",
      "status": "issued",
      "external_policy_number": "APL-2026-000123",
      "gross_premium_amount": 617.28,
      "term": {
        "start_date": "2026-07-16",
        "end_date": "2027-07-15"
      },
      "created_at": "2026-07-16T14:03:25.481Z"
    }
  ]
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `order_key` | string | Chave do pedido consultado. |
| `policies` | array | Resumo de cada apólice do pedido. Os campos são um subconjunto da [consulta de apólice](/documentation/seguros/apolices/consultar_apolice). |

:::info Consistência eventual após a emissão
As apólices são criadas de forma **assíncrona** logo após o webhook de `emitted` do pedido. Imediatamente após a emissão, esta lista pode vir vazia ou menor que o `product_count` do webhook enquanto as apólices são materializadas. Aguarde os [webhooks de apólice](/documentation/seguros/apolices/webhooks) ou consulte novamente em instantes.
:::

Um `order_key` desconhecido, ainda não processado ou pertencente a outra integração retorna `200` com a lista vazia — os casos são indistinguíveis.

## Possíveis erros

Todo erro (`non-2xx`) retorna o corpo padrão `{ "title", "description", "translation", "code" }` — trate programaticamente **apenas** o campo `code`.

| Status | Código | Descrição |
|---|---|---|
| `400` | `QIT000001` | Parâmetro `order_key` ausente. |
| `401` / `403` | — | Falha de autenticação ou autorização. |
| `429` | — | Limite de requisições excedido — repita com backoff. |
| `500` | `QIT000500` | Erro interno — seguro repetir a chamada. |
| `503` | `POL000030` | Serviço indisponível — seguro repetir a chamada. |

---

# Webhooks da Apólice

URL: /documentation/seguros/apolices/webhooks

Os marcos do ciclo de vida da apólice são notificados por webhooks do tipo `insurance.policy.status_changed`. Dois status geram evento: `issued` (emissão confirmada pela seguradora) e `canceled` (cancelamento confirmado). Os status transitórios (`issuance_requested`, `cancellation_requested`) e o encerramento natural de vigência (`finished`) **não** geram webhook — os transitórios são resultado das suas próprias chamadas, e o fim de vigência é conhecido desde a emissão pelo `term.end_date`.

:::info Configuração de webhooks
Para receber webhooks é necessário ter uma URL de callback configurada. Veja [Autenticação — Recebimento de webhooks](/documentation/seguros/introducao/autenticacao#recebimento-de-webhooks).
:::

## Estrutura do webhook

| Campo | Tipo | Descrição |
|---|---|---|
| `webhook_type` | string | Sempre `insurance.policy.status_changed`. |
| `webhook_datetime` | string | Data e hora do evento no formato ISO 8601. |
| `data` | object | Dados do evento. Veja tabela abaixo. |

#### Atributos de `data`

| Campo | Tipo | Descrição |
|---|---|---|
| `policy_key` | string | Chave da apólice. |
| `order_key` | string | Chave do pedido que originou a apólice — a correlação com a sua venda. |
| `status` | string | Novo status: `issued` ou `canceled`. |
| `external_policy_number` | string | Número da apólice na seguradora. Presente no evento de `issued`. |
| `reason` | string | Motivo do cancelamento. Presente no evento de `canceled`, quando informado. |

```json title="Estrutura padrão do webhook"
{
  "webhook_type": "insurance.policy.status_changed",
  "webhook_datetime": "2026-07-16T15:00:00Z",
  "data": {
    "policy_key": "0b6e7c1a-9a4e-4c1e-b1d4-2f5a8c9e0d31",
    "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
    "status": "status",
    "external_policy_number": "APL-2026-000123",
    "reason": null
  }
}
```

## Eventos por status

### Apólice emitida

STATUS issued

Enviado quando a seguradora confirma a emissão. A partir deste evento o `external_policy_number` está disponível e a cobertura está formalmente em vigor. Como cada apólice é emitida de forma independente, um pedido com N produtos gera N eventos deste tipo — possivelmente em momentos diferentes.

```json title="Webhook Body"
{
  "webhook_type": "insurance.policy.status_changed",
  "webhook_datetime": "2026-07-16T15:00:00Z",
  "data": {
    "policy_key": "0b6e7c1a-9a4e-4c1e-b1d4-2f5a8c9e0d31",
    "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
    "status": "issued",
    "external_policy_number": "APL-2026-000123",
    "reason": null
  }
}
```

---

### Apólice cancelada

STATUS canceled

Enviado quando a seguradora confirma o cancelamento — solicitado pelo [cancelamento de apólice](/documentation/seguros/apolices/cancelar_apolice) ou pelo [cancelamento pós-emissão do pedido](/documentation/seguros/pedidos/cancelar_pedido). A devolução de prêmio devida (integral dentro do direito de arrependimento, pró-rata depois) é calculada neste momento e executada pela QI Tech.

```json title="Webhook Body"
{
  "webhook_type": "insurance.policy.status_changed",
  "webhook_datetime": "2026-08-02T09:30:00Z",
  "data": {
    "policy_key": "0b6e7c1a-9a4e-4c1e-b1d4-2f5a8c9e0d31",
    "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
    "status": "canceled",
    "external_policy_number": "APL-2026-000123",
    "reason": "Cliente solicitou o cancelamento"
  }
}
```

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeados de forma estrita.
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

---

# Consultar produto

URL: /documentation/seguros/catalogo/consultar_produto

Retorna o **envelope de venda** de um produto habilitado para a sua integração: as coberturas ativas com seus espaços de opções, as dependências entre coberturas, os seus valores padrão e a sua faixa de comissão. Com essa resposta você tem tudo o que precisa para montar uma [cotação](/documentation/seguros/cotacao/criar_cotacao) válida.

## Request

ENDPOINT /v1/product_catalog/products/{product_key}
MÉTODO GET

### Path params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `product_key` | string | obrigatório | Chave do produto, obtida na [listagem de produtos](/documentation/seguros/catalogo/listar_produtos). |

## Response

STATUS 200

```json title="Response Body"
{
  "product_key": "9d1f8c7a-3b21-4e60-8a2f-1c5d7e9b0a44",
  "name": "Prestamista Master",
  "product_category": "insurance",
  "insurance_class": "credit_life",
  "contract_instrument_type": "ticket",
  "regulator_registration": "15414.900123/2025-77",
  "provider_name": "QI Seguradora",
  "commission_bounds": {
    "minimum_rate": 0.05,
    "maximum_rate": 0.20,
    "default_rate": 0.15
  },
  "services": [
    {
      "service_key": "0a3c5e7f-2b4d-4a6c-8e0f-1a3b5c7d9e2f",
      "service_type": "credit_life",
      "service_category": "insurance",
      "mandatory": true,
      "maximum_insured_amount": 500000.00,
      "deductible_options": {
        "deductible_type": "monetary_amount",
        "options_type": "list",
        "options": [0.00, 1500.00, 3000.00]
      },
      "waiting_period_options": {
        "waiting_period_type": "days",
        "options_type": "range",
        "options": {
          "minimum": 0,
          "maximum": 90,
          "step": 30
        }
      },
      "indemnity_unit_options": null,
      "regulator_registration": null,
      "dependencies": {
        "include": [],
        "exclude": []
      },
      "service_attributes": null,
      "default_configuration": {
        "insured_amount_basis": "percentage_of_risk_value",
        "insured_amount": null,
        "insured_amount_percentage": 0.8000,
        "unit_amount": null,
        "unit_count": null,
        "deductible_data": {
          "deductible_type": "monetary_amount",
          "value": 1500.00
        },
        "waiting_period_days": 30
      }
    }
  ]
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `product_key` | string | Chave única do produto. |
| `name` | string | Nome comercial do produto. |
| `product_category` | string | Categoria do produto: `insurance`, `capitalization` ou `benefit`. |
| `insurance_class` | string | Ramo SUSEP do produto. `null` para produtos não-seguro. |
| `contract_instrument_type` | string | Instrumento contratual do produto: `ticket` (bilhete) ou `policy` (apólice). Determina o fluxo de contratação e quais métodos de aceite são válidos — veja [Criar pedido](/documentation/seguros/pedidos/criar_pedido). `null` para produtos não securitários. |
| `regulator_registration` | string | Registro do produto na SUSEP (Código SUSEP). |
| `provider_name` | string | Nome da seguradora parceira. |
| `commission_bounds` | object | A **sua** faixa de comissão para este produto: `minimum_rate`, `maximum_rate` e `default_rate` (taxas decimais com 4 casas). A comissão da cotação/pedido é validada contra `[minimum_rate, maximum_rate]`; se omitida, vale `default_rate`. |
| `services` | array | Coberturas **ativas** do produto. |

#### Objeto em `services`

| Campo | Tipo | Descrição |
|---|---|---|
| `service_key` | string | Chave única da cobertura. Use-a na lista `services` da cotação e do pedido. |
| `service_type` | string | Tipo da cobertura (ex.: `credit_life`). |
| `service_category` | string | Categoria da cobertura: `insurance`, `capitalization` ou `benefit`. |
| `mandatory` | boolean | Cobertura obrigatória em toda venda do produto. Uma seleção que a omita é rejeitada com `MISSING_MANDATORY_SERVICE`. |
| `maximum_insured_amount` | number | Importância segurada máxima aceita. `null` para coberturas sem importância segurada (benefícios). |
| `deductible_options` | object | Envelope tipado das franquias aceitas (veja abaixo). `null` indica que a cobertura **não tem franquia** — enviar `deductible_data` para ela é rejeitado. |
| `waiting_period_options` | object | Envelope tipado das carências aceitas (veja abaixo). `null` indica que a cobertura **não tem carência**. |
| `indemnity_unit_options` | object | Envelope tipado das unidades de indenização aceitas, para coberturas precificadas por unidade (ex.: "R$ 100 por diária, até 60 diárias"). `null` indica que a cobertura **não é precificada por unidade** — enviar `unit_amount`/`unit_count` para ela é rejeitado com `OUT_OF_OPTION_SPACE`. |
| `regulator_registration` | string | Registro SUSEP próprio da cobertura. `null` indica que a cobertura herda o registro do produto. |
| `dependencies` | object | Regras estruturais entre coberturas deste produto: `include` (chaves de coberturas pré-requisito — toda cobertura listada precisa estar na seleção) e `exclude` (chaves mutuamente exclusivas — não podem coexistir na seleção). |
| `service_attributes` | object | Atributos fixos da cobertura definidos pela seguradora (ex.: quantidades de um benefício). Ecoados na cotação. |
| `default_configuration` | object | O **seu** padrão configurado para esta cobertura — o que a cotação preenche automaticamente quando a seleção omite `services`. Todos os campos de valor são emitidos, com `null` nos que não se aplicam; `insured_amount_basis` diz qual está ativo. Os valores vêm na **mesma forma** que você enviaria na seleção, prontos para reuso. `null` quando não há padrão configurado. |

#### Envelopes de opções (`deductible_options` / `waiting_period_options` / `indemnity_unit_options`)

| Campo | Tipo | Descrição |
|---|---|---|
| `deductible_type` | string | Tipo da franquia: `monetary_amount`, `days` ou `percentage_of_insured_amount`. Presente em `deductible_options`. |
| `waiting_period_type` | string | Tipo da carência: `days`. Presente em `waiting_period_options`. |
| `indemnity_unit_type` | string | Tipo da unidade de indenização (ex.: `daily`). Presente em `indemnity_unit_options`. |
| `options_type` | string | Forma do espaço de opções: `list` (lista de valores aceitos) ou `range` (intervalo `{minimum, maximum, step}`; `step` `null` indica intervalo contínuo). |
| `options` | array / object | Os valores aceitos, na forma indicada por `options_type`. |

#### Objeto `default_configuration`

| Campo | Tipo | Descrição |
|---|---|---|
| `insured_amount_basis` | string | Base da importância segurada: `monetary_amount` (valor absoluto), `percentage_of_risk_value` (percentual do valor do objeto de risco) ou `unit_amount_times_count` (valor por unidade × quantidade de unidades). Diz qual dos campos de valor abaixo está ativo. |
| `insured_amount` | number | Importância segurada em reais. Presente quando a base é `monetary_amount`; `null` nas demais. |
| `insured_amount_percentage` | number | Percentual do valor do objeto de risco, em `(0, 1]` (`1.0000` = 100%). Presente quando a base é `percentage_of_risk_value`; `null` nas demais. |
| `unit_amount` | number | Valor por unidade de indenização. Presente quando a base é `unit_amount_times_count`; `null` nas demais. |
| `unit_count` | integer | Quantidade de unidades de indenização. Presente quando a base é `unit_amount_times_count`; `null` nas demais. |
| `deductible_data` | object | Franquia padrão, na mesma forma tipada enviada na seleção: `{ deductible_type, value }`. |
| `waiting_period_days` | integer | Carência padrão, em dias. |

## Possíveis erros

Todo erro (`non-2xx`) retorna o corpo padrão `{ "title", "description", "translation", "code" }` — trate programaticamente **apenas** o campo `code`.

| Status | Código | Descrição |
|---|---|---|
| `401` / `403` | — | Falha de autenticação ou autorização. |
| `404` | `CAT000040` | O produto não existe, está inativo ou não está habilitado para a sua integração — os três casos são indistinguíveis. |
| `429` | — | Limite de requisições excedido — repita com backoff. |
| `500` | `QIT000500` | Erro interno — seguro repetir a chamada. |
| `503` | `CAT000033` | Serviço indisponível — seguro repetir a chamada. |

---

# Início

URL: /documentation/seguros/catalogo/inicio

O **Catálogo de Produtos** é a superfície de descoberta do Insurance-as-a-Service: ele responde "o que a minha integração pode vender?" e "como monto uma seleção válida para cotar?". São dois endpoints somente de leitura, escopados aos produtos habilitados para a sua integração.

## Conceitos

| Conceito | Descrição |
|---|---|
| **Produto** (`product`) | Um produto de seguro de uma seguradora parceira (ex.: um prestamista, um seguro de vida em grupo). É a unidade de venda: cada produto vendido em um pedido gera uma apólice. Endereçado por `product_key`. |
| **Cobertura** (`service`) | Uma cobertura ou benefício que compõe o produto (ex.: morte, invalidez por acidente, assistência funeral). Pode ser obrigatória (`mandatory`) ou opcional. Endereçada por `service_key`. |
| **Espaço de opções** | Os limites configuráveis de cada cobertura: importância segurada máxima (`maximum_insured_amount`) e os envelopes tipados de franquia (`deductible_options`) e carência (`waiting_period_options`) aceitos. Uma seleção fora do espaço de opções é rejeitada na cotação. |
| **Dependências** | Regras estruturais entre coberturas do mesmo produto: `include` (coberturas pré-requisito) e `exclude` (coberturas mutuamente exclusivas). |
| **Faixa de comissão** (`commission_bounds`) | A banda `{minimum_rate, maximum_rate, default_rate}` da **sua** comissão por venda daquele produto. A comissão enviada na cotação e no pedido (`commission_data`) é validada contra essa faixa; se omitida, vale o `default_rate`. |
| **Configuração padrão** (`default_configuration`) | Valores padrão de cobertura configurados para a sua integração. Quando a seleção omite a lista `services`, a cotação preenche automaticamente todas as coberturas padrão configuradas. |

## Classificação dos produtos

Cada produto carrega uma classificação regulatória e comercial:

| Campo | Descrição |
|---|---|
| `product_category` | `insurance`, `capitalization` ou `benefit`. Um produto pode combinar coberturas de categorias diferentes (ex.: seguro + assistência). |
| `insurance_class` | O ramo SUSEP do produto (ex.: `credit_life`). Ausente para produtos não-seguro. Na cotação e no pedido, o ramo é retornado como objeto `{ name, class_number, group_number }`. |
| `regulator_registration` | O registro do produto na SUSEP (Código SUSEP). |

## Visibilidade e confidencialidade

- Somente produtos **ativos** habilitados para a sua integração são visíveis; um produto de outro parceiro (ou inexistente) retorna `404`.
- A faixa de comissão retornada é sempre a **sua** — nunca a de outro parceiro.
- As regras internas de tarifação e elegibilidade da seguradora não são expostas: você recebe os limites estruturais (espaço de opções e dependências) e o resultado da avaliação na [cotação](/documentation/seguros/cotacao/criar_cotacao).

## Endpoints

| Endpoint | Descrição |
|---|---|
| [`GET /v1/product_catalog/products`](/documentation/seguros/catalogo/listar_produtos) | Lista os produtos que a sua integração pode vender. |
| [`GET /v1/product_catalog/products/{product_key}`](/documentation/seguros/catalogo/consultar_produto) | Detalha um produto: coberturas, espaço de opções, dependências, seus padrões e sua faixa de comissão. |

---

# Listar produtos

URL: /documentation/seguros/catalogo/listar_produtos

Retorna a lista paginada de produtos de seguro **ativos e habilitados para a sua integração** — a resposta à pergunta "o que posso vender?". Cada item traz um resumo do produto e de suas coberturas; para o envelope completo de venda, use a [consulta de produto](/documentation/seguros/catalogo/consultar_produto).

## Request

ENDPOINT /v1/product_catalog/products
MÉTODO GET

### Query params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `page` | integer | opcional | Número da página. Padrão: `1`. |
| `rows_per_page` | integer | opcional | Registros por página. Padrão: `50`. |
| `name` | string | opcional | Filtra pelo nome do produto. |
| `product_category` | string | opcional | Filtra pela categoria: `insurance`, `capitalization` ou `benefit`. |
| `insurance_class` | string | opcional | Filtra pelo ramo do produto (ex.: `credit_life`). |
| `service_category` | string | opcional | Filtra por produtos que contenham cobertura da categoria informada. |

```python title="Exemplo de chamada"
GET /v1/product_catalog/products?page=1&rows_per_page=50&product_category=insurance
```

## Response

STATUS 200

```json title="Response Body"
{
  "data": [
    {
      "product_key": "9d1f8c7a-3b21-4e60-8a2f-1c5d7e9b0a44",
      "name": "Prestamista Master",
      "product_category": "insurance",
      "insurance_class": "credit_life",
      "contract_instrument_type": "ticket",
      "provider_name": "QI Seguradora",
      "services": [
        {
          "service_type": "credit_life",
          "service_category": "insurance",
          "mandatory": true
        },
        {
          "service_type": "funeral_assistance",
          "service_category": "benefit",
          "mandatory": false
        }
      ]
    }
  ],
  "pagination": {
    "current_page": 1,
    "next_page": null,
    "rows_per_page": 50
  }
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Lista de produtos habilitados. |
| `pagination` | object | Estado da paginação: `current_page` (página atual), `next_page` (número da próxima página, ou `null` quando esta é a última) e `rows_per_page` (tamanho da página solicitado). |

:::caution Esta listagem não retorna `total`
A paginação do catálogo é **por cursor de página**, não por contagem: pare de paginar quando `pagination.next_page` vier `null`. A [listagem de pedidos](/documentation/seguros/pedidos/listar_pedidos) usa uma convenção diferente (`page_size` + `total`) — as duas superfícies não são intercambiáveis.
:::

#### Objeto em `data`

| Campo | Tipo | Descrição |
|---|---|---|
| `product_key` | string | Chave única do produto. Use-a na consulta de produto, na cotação e no pedido. |
| `name` | string | Nome comercial do produto. |
| `product_category` | string | Categoria do produto: `insurance`, `capitalization` ou `benefit`. |
| `insurance_class` | string | Ramo SUSEP do produto (ex.: `credit_life`). `null` para produtos não-seguro. |
| `contract_instrument_type` | string | Instrumento contratual do produto: `ticket` (bilhete) ou `policy` (apólice). Determina o fluxo de contratação — veja [Criar pedido](/documentation/seguros/pedidos/criar_pedido). `null` para produtos não securitários. |
| `provider_name` | string | Nome da seguradora parceira. |
| `services` | array | Resumo das coberturas do produto. |

#### Objeto em `services`

| Campo | Tipo | Descrição |
|---|---|---|
| `service_type` | string | Tipo da cobertura (ex.: `credit_life`, `life_death`, `funeral_assistance`). |
| `service_category` | string | Categoria da cobertura: `insurance`, `capitalization` ou `benefit`. |
| `mandatory` | boolean | Indica se a cobertura é obrigatória em toda venda do produto. |

## Possíveis erros

Todo erro (`non-2xx`) retorna o corpo padrão `{ "title", "description", "translation", "code" }` — trate programaticamente **apenas** o campo `code`.

| Status | Código | Descrição |
|---|---|---|
| `400` | `QIT000010` | Parâmetro de paginação inválido. |
| `400` | `QIT000001` | Parâmetro de filtro malformado. |
| `401` / `403` | — | Falha de autenticação ou autorização. |
| `429` | — | Limite de requisições excedido — repita com backoff. |
| `500` | `QIT000500` | Erro interno — seguro repetir a chamada. |
| `503` | `CAT000033` | Serviço indisponível — seguro repetir a chamada. |

---

# Criar cotação

URL: /documentation/seguros/cotacao/criar_cotacao

Precifica uma seleção de produtos e coberturas para um cliente. A cotação é uma **calculadora**: nada é persistido e nenhum recurso é criado. O [pedido](/documentation/seguros/pedidos/criar_pedido) usa exatamente a mesma lista `products[]` e é reprecificado com o mesmo motor no momento da submissão.

:::info A cotação é indicativa
Cotação e pedido rodam contra a configuração **vigente** — não há token de cotação, snapshot de tarifa nem prazo de validade. Se a tarifa ou a configuração do produto mudar entre a cotação e a submissão, o preço muda: **o preço calculado na submissão do pedido é o que vale**.
:::

Uma cotação pode combinar **vários produtos**, cada um segurando o seu próprio objeto de risco. O caso típico: um carro vendido com financiamento gera um pedido com o produto **prestamista** (objeto de risco = a operação de crédito) e o produto **auto** (objeto de risco = o veículo).

## Request

ENDPOINT /v1/insurance/quote
MÉTODO POST

Para **produtos de prateleira** — vendidos como estão, com as coberturas padrão e a comissão padrão da sua integração — a linha do produto precisa apenas de `product_key`, `term` e `risk_object`. É o cenário ideal para quem vende produtos fixos, sem personalização:

```json title="Request Body — produto de prateleira"
{
  "products": [
    {
      "product_key": "9d1f8c7a-3b21-4e60-8a2f-1c5d7e9b0a44",
      "term": {
        "start_date": "2026-07-16",
        "end_date": "2028-07-15"
      },
      "risk_object": {
        "type": "credit_operation",
        "insurable_value": 50000.00,
        "attributes": {
          "installment_amount": 1050.00,
          "number_of_installments": 48
        }
      }
    }
  ],
  "customer": {
    "date_of_birth": "1987-03-22",
    "occupation_code": "211205"
  }
}
```

Com `services` omitido, todas as coberturas com [configuração padrão](/documentation/seguros/catalogo/consultar_produto) da sua integração são preenchidas automaticamente; com `commission_data` omitido, vale o `default_rate` da faixa `commission_bounds` do produto.

Para personalizar a seleção — escolher coberturas, importância segurada, franquia, carência ou a comissão — envie `services` e `commission_data` explicitamente:

```json title="Request Body — seleção personalizada"
{
  "products": [
    {
      "product_key": "9d1f8c7a-3b21-4e60-8a2f-1c5d7e9b0a44",
      "commission_data": {
        "commission_type": "percentage_of_gross_premium",
        "value": 0.1000
      },
      "term": {
        "start_date": "2026-07-16",
        "end_date": "2028-07-15"
      },
      "services": [
        {
          "service_key": "0a3c5e7f-2b4d-4a6c-8e0f-1a3b5c7d9e2f",
          "insured_amount_basis": "monetary_amount",
          "insured_amount": 50000.00
        }
      ],
      "risk_object": {
        "type": "credit_operation",
        "insurable_value": 50000.00,
        "attributes": {
          "installment_amount": 1050.00,
          "number_of_installments": 48
        }
      }
    }
  ],
  "customer": {
    "date_of_birth": "1987-03-22",
    "occupation_code": "211205"
  }
}
```

### Atributos do request

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `products` | array | obrigatório | A seleção de produtos a precificar, campo de topo do request — o mesmo formato usado no pedido. Um item por produto. |
| `customer` | object | opcional | Dados do segurado usados na precificação e na avaliação de elegibilidade, em objeto plano (sem wrapper). Quando omitido, a elegibilidade não é avaliada (`eligibility` retorna `not_evaluated`) — e produtos cuja tarifa depende de dados do cliente são rejeitados com `NOT_PRICEABLE`. |

#### Objeto em `products`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `product_key` | string | obrigatório | Chave do produto no [catálogo](/documentation/seguros/catalogo/listar_produtos). |
| `commission_data` | object | opcional | A forma de comissão desejada (veja abaixo). Quando omitida, vale o `default_rate` da faixa `commission_bounds` do produto. |
| `term` | object | obrigatório | Vigência do produto, em datas absolutas: `{ "start_date": "AAAA-MM-DD", "end_date": "AAAA-MM-DD" }`. **Obrigatório em todo item** — não há forma por duração nem vigência padrão da seleção. Produtos do mesmo pedido podem ter vigências diferentes. |
| `services` | array | opcional | Coberturas explícitas. Quando omitido ou vazio, todas as coberturas com [configuração padrão](/documentation/seguros/catalogo/consultar_produto) da sua integração são preenchidas automaticamente. |
| `risk_object` | object | condicional | O objeto que **este produto** segura. Obrigatório para produtos de risco valorado (`credit_operation`, `vehicle`); omitido quando o objeto do seguro é a própria pessoa (`person`). |

#### Objeto `commission_data`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `commission_type` | string | obrigatório | `percentage_of_gross_premium` (taxa sobre o prêmio bruto), `monetary_amount` (comissão em R$ fixo, valor-alvo) ou `total_gross_premium_amount` (preço final desejado ao cliente, valor-alvo). As três formas são mutuamente exclusivas. |
| `value` | number | obrigatório | O valor da forma escolhida: taxa com 4 casas (ex.: `0.1000`), valor em R$ (ex.: `61.73`) ou preço total (ex.: `650.00`). |

Em qualquer forma, a **taxa efetiva** resultante é validada contra a faixa `commission_bounds` do produto — violação rejeita a linha com `OUT_OF_BOUNDS_COMMISSION`. Nas formas por valor (`monetary_amount`, `total_gross_premium_amount`), o valor é um alvo: o realizado pode variar centavos por arredondamento.

#### Objeto em `services`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `service_key` | string | obrigatório | Chave da cobertura no catálogo. É o **único** campo obrigatório do item: omitindo os demais, vale a sua [configuração padrão](/documentation/seguros/catalogo/consultar_produto) para a cobertura. |
| `insured_amount_basis` | string | condicional | Base da importância segurada: `monetary_amount`, `percentage_of_risk_value` ou `unit_amount_times_count`. Informar a base torna obrigatório o campo de valor correspondente. |
| `insured_amount` | number | condicional | Importância segurada em reais. Obrigatório quando a base é `monetary_amount`. |
| `insured_amount_percentage` | number | condicional | Percentual do valor do objeto de risco, em `(0, 1]` (`1.0000` = 100%). Obrigatório quando a base é `percentage_of_risk_value`; resolvido contra o `insurable_value` do objeto de risco da linha. |
| `unit_amount` | number | condicional | Valor por unidade de indenização (ex.: R$ 100 por diária). Obrigatório, junto com `unit_count`, quando a base é `unit_amount_times_count`. Deve pertencer ao envelope `indemnity_unit_options` da cobertura. |
| `unit_count` | integer | condicional | Quantidade de unidades de indenização (ex.: 60 diárias). Obrigatório, junto com `unit_amount`, quando a base é `unit_amount_times_count`. |
| `deductible_data` | object | opcional | Franquia, na forma tipada `{ "deductible_type": "monetary_amount", "value": 1500.00 }`. O `deductible_type` deve ser o mesmo do envelope `deductible_options` da cobertura, e o valor deve pertencer ao espaço de opções. |
| `waiting_period_days` | integer | opcional | Carência em dias, dentro das `waiting_period_options` da cobertura. |

#### Objeto `risk_object`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `type` | string | obrigatório | Tipo do objeto de risco: `credit_operation`, `vehicle` ou `person`. |
| `insurable_value` | number | condicional | Valor do objeto de risco. Obrigatório para `credit_operation` e `vehicle`; não se aplica a `person`. Limita a importância segurada **das coberturas atreladas ao valor do risco** — coberturas de limite estipulado respeitam apenas o próprio `maximum_insured_amount`. |
| `attributes` | object | opcional | Atributos do objeto de risco usados na tarifação, específicos por ramo (ex.: para uma operação de crédito, `installment_amount` e `number_of_installments`). |

#### Objeto `customer`

O objeto é plano — não há wrapper `data`.

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `document_number` | string | opcional | CPF ou CNPJ do segurado. |
| `name` | string | opcional | Nome completo. |
| `email` | string | opcional | E-mail. |
| `phone_number` | string | opcional | Telefone no formato E.164. |
| `date_of_birth` | string | opcional | Data de nascimento do segurado, no formato `YYYY-MM-DD`. A **idade** usada na precificação e nas regras de elegibilidade (ex.: idade máxima no fim da vigência) é derivada dela a cada chamada — não existe campo de idade. |
| `occupation_code` | string | opcional | Código de ocupação do segurado (CBO). |
| `address` | object | opcional | Endereço do segurado, na mesma forma usada no [pedido](/documentation/seguros/pedidos/criar_pedido#objeto-customeraddress). |

## Response

STATUS 200

```json title="Response Body"
{
  "total_order_amount": 617.28,
  "products": [
    {
      "product_key": "9d1f8c7a-3b21-4e60-8a2f-1c5d7e9b0a44",
      "name": "Prestamista Master",
      "provider_name": "QI Seguradora",
      "product_category": "insurance",
      "insurance_class": {
        "name": "credit_life",
        "class_number": "0977",
        "group_number": "09"
      },
      "contract_instrument_type": "ticket",
      "regulator_registration": "15414.900388/2015-21",
      "result": "priced",
      "term": {
        "start_date": "2026-07-16",
        "end_date": "2028-07-15"
      },
      "gross_premium_amount": 617.28,
      "iof_amount": 2.35,
      "net_premium_amount": 614.93,
      "services": [
        {
          "service_key": "0a3c5e7f-2b4d-4a6c-8e0f-1a3b5c7d9e2f",
          "service_type": {
            "code": "credit_life",
            "name": "Prestamista (Credit Life)"
          },
          "service_category": "insurance",
          "regulator_registration": null,
          "insured_amount": 50000.00,
          "unit_amount": null,
          "unit_count": null,
          "deductible_data": {
            "deductible_type": "monetary_amount",
            "value": 1500.00
          },
          "waiting_period_days": 30,
          "service_attributes": {},
          "gross_premium_amount": 617.28
        }
      ]
    }
  ],
  "eligibility": "eligible"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `total_order_amount` | number | Soma dos prêmios brutos dos produtos precificados (`priced`), com IOF. |
| `products` | array | Resultado por produto. Cada linha é avaliada de forma independente: um produto rejeitado nunca contamina os demais na **cotação** (no pedido, qualquer linha rejeitada recusa a submissão inteira, que retorna erro `422`). |
| `eligibility` | string | Veredito de elegibilidade da cotação: `eligible`, `declined` (alguma regra de elegibilidade reprovou) ou `not_evaluated` (o `customer` não foi enviado — **não é uma aprovação**). |

#### Objeto em `products`

| Campo | Tipo | Descrição |
|---|---|---|
| `product_key` | string | Chave do produto avaliado. |
| `name` / `provider_name` | string | Nome comercial do produto e da seguradora. |
| `product_category` | string | Categoria do produto: `insurance`, `capitalization` ou `benefit`. |
| `insurance_class` | object | Ramo do seguro: `{ name, class_number, group_number }`. `null` para produtos não securitários. |
| `contract_instrument_type` | string | Instrumento contratual do produto: `ticket` (bilhete) ou `policy` (apólice). Ecoado aqui para que você conheça o instrumento — e portanto quais métodos de aceite são válidos — **antes** de coletar o aceite no [pedido](/documentation/seguros/pedidos/criar_pedido). |
| `regulator_registration` | string | Registro do produto no regulador. |
| `result` | string | `priced` (precificado) ou `rejected` (rejeitado). Presente em **toda** linha. |
| `term` | object | A vigência que você enviou, ecoada. Presente quando `priced`. |
| `gross_premium_amount` | number | Prêmio bruto do produto, com IOF — soma exata dos prêmios das coberturas. Presente quando `priced`. |
| `iof_amount` | number | IOF do produto. Presente quando `priced`. |
| `net_premium_amount` | number | Prêmio líquido do produto, sem IOF. Presente quando `priced`. |
| `services` | array | Coberturas precificadas, com o prêmio de cada uma. Presente quando `priced`. |
| `decline_reasons` | array | Motivos da rejeição, um item `{ code, detail }` por falha subjacente — duas coberturas da mesma linha violando o espaço de opções geram duas entradas sob o mesmo `code`. Presente **apenas** quando `rejected`. |

#### Objeto em `services`

| Campo | Tipo | Descrição |
|---|---|---|
| `service_key` | string | Chave da cobertura. |
| `service_type` | object | Tipo da cobertura: `{ code, name }`. |
| `service_category` | string | Categoria da cobertura: `insurance`, `capitalization` ou `benefit`. |
| `regulator_registration` | string | Registro SUSEP próprio da cobertura. `null` quando a cobertura herda o registro do produto. |
| `insured_amount` | number | Importância segurada resolvida — o percentual já aplicado sobre o valor do objeto de risco, o par por unidade já multiplicado. Você nunca a recalcula. |
| `unit_amount` | number | Valor por unidade de indenização. `null` quando a cobertura não é precificada por unidade. |
| `unit_count` | integer | Quantidade de unidades de indenização. `null` quando a cobertura não é precificada por unidade. |
| `deductible_data` | object | Franquia aplicada: `{ deductible_type, value }`. `null` quando a cobertura não tem franquia. |
| `waiting_period_days` | integer | Carência aplicada, em dias. `null` quando a cobertura **não tem** carência — que é diferente de uma carência de 0 dias. |
| `service_attributes` | object | Atributos fixos da cobertura, ecoados do catálogo. |
| `gross_premium_amount` | number | Prêmio bruto da cobertura, arredondado em 2 casas. |

### Motivos de rejeição

Quando `result` é `rejected`, a linha traz **apenas** `product_key`, `result` e `decline_reasons` — nada é oferecido, então nada é descrito: sem `name`, sem classificação, sem `term`, sem prêmios e sem `services`. Ramifique sempre pelo `result`, nunca pela presença de um campo.

A avaliação é por estágios (estrutura → precificação → elegibilidade): os motivos retornados são sempre do **mesmo estágio** — o primeiro que reprovar — coletados por completo.

```json title="Linha rejeitada"
{
  "product_key": "9d1f8c7a-3b21-4e60-8a2f-1c5d7e9b0a44",
  "result": "rejected",
  "decline_reasons": [
    {
      "code": "OUT_OF_OPTION_SPACE",
      "detail": "deductible 2000.00 is not in the option list for coverage credit_life"
    }
  ]
}
```

| Código | Significado |
|---|---|
| `NOT_ENTITLED` | A sua integração não está habilitada para vender este produto. |
| `INACTIVE_PRODUCT` | O produto está inativo (ou a chave é desconhecida). |
| `INACTIVE_SERVICE` | Uma cobertura selecionada está inativa. |
| `UNKNOWN_SERVICE` | Uma `service_key` não pertence a este produto. |
| `MISSING_MANDATORY_SERVICE` | A seleção omite uma cobertura obrigatória do produto. |
| `DEPENDENCY_VIOLATION` | A seleção viola as dependências entre coberturas (`include`/`exclude`). |
| `OUT_OF_OPTION_SPACE` | Importância segurada, franquia ou carência fora do espaço de opções da cobertura — inclusive tipo divergente do envelope, valor fora da `list`/`range`/`step`, ou valor enviado para uma cobertura sem franquia/carência (envelope `null`). |
| `INVALID_INSURED_AMOUNT_BASIS` | A base de importância segurada não é compatível com a linha — ex.: cobertura atrelada ao valor do risco em uma linha sem `insurable_value`. Vale para qualquer base. |
| `NOT_PRICEABLE` | O motor não conseguiu produzir um preço: um insumo da tarifa não é resolvível (ex.: a tarifa depende de dados do `customer` e ele não foi enviado). |
| `ZERO_PREMIUM` | A linha inteira precificou a custo zero. Uma única cobertura gratuita é válida (sai com `gross_premium_amount: 0.00`); a linha toda a zero é rejeitada. |
| `INELIGIBLE` | Uma regra de elegibilidade reprovou (ex.: idade máxima no fim da vigência). O `detail` do item nomeia a regra e os valores que a reprovaram. |
| `OUT_OF_BOUNDS_COMMISSION` | A comissão efetiva derivada de `commission_data` está fora da faixa `commission_bounds` do produto. |
| `DELEGATED_UNSUPPORTED` | Produto com precificação delegada à seguradora — reservado, ainda não suportado. |
| `STALE_DEFAULT` | Uma configuração padrão da sua integração aponta para uma cobertura que não está mais ativa — contate o suporte para atualizar o padrão. |

## Possíveis erros

Todo erro (`non-2xx`) retorna o corpo padrão `{ "title", "description", "translation", "code" }` — trate programaticamente **apenas** o campo `code`.

| Status | Código | Descrição |
|---|---|---|
| `400` | `QIT000001` | Requisição malformada: schema inválido, `products` vazio, produto sem `term`, base de importância segurada sem o campo de valor correspondente, `insurable_value` ausente para `credit_operation`/`vehicle`, `deductible_data` estruturalmente malformado, `customer.date_of_birth` fora do calendário ou no futuro. |
| `401` / `403` | — | Falha de autenticação ou autorização. |
| `429` | — | Limite de requisições excedido — repita com backoff. |
| `503` | — | Motor de precificação indisponível — a cotação falha rápido, sem preço em cache. Repita a chamada. |

---

# Início

URL: /documentation/seguros/cotacao/inicio

A etapa de precificação oferece duas operações, ambas **calculadoras**: nada é persistido e nenhum recurso é criado. A diferença está na pergunta que cada uma responde.

- A **cotação** (`POST /v1/insurance/quote`) responde *"quanto custa esta seleção?"* — calcula o **preço exato** de uma seleção de produtos e coberturas para uma configuração de comissão específica (a enviada em `commission_data`, ou o padrão do produto quando omitida).
- A **simulação** (`POST /v1/insurance/simulate`) responde *"por quanto eu posso vender esta seleção?"* — calcula a **faixa de preço vendável** de cada produto, variando apenas a comissão entre o mínimo e o máximo da sua faixa (`commission_bounds`). Por isso ela não aceita `commission_data`: a faixa inteira é varrida.

## Cotação vs. simulação

| | [Cotação](/documentation/seguros/cotacao/criar_cotacao) | [Simulação](/documentation/seguros/cotacao/simular_precos) |
|---|---|---|
| Responde | O preço exato da seleção. | O menor e o maior preço final possíveis por produto. |
| Comissão | Uma configuração específica (`commission_data` ou o padrão do produto). | Varre a faixa `commission_bounds` inteira — enviar `commission_data` é `400`. |
| Retorna | `gross_premium_amount` por produto e por cobertura, com veredito de elegibilidade. | `price_range` por produto: piso e teto do prêmio, comissão em R$ e taxas nos extremos. |
| Use para | Exibir o preço de uma oferta fechada antes de submeter o [pedido](/documentation/seguros/pedidos/criar_pedido). | Montar ofertas com preço customizado: descobrir os limites antes de escolher um `total_gross_premium_amount`. |

Os dois requests usam a mesma lista `products[]` do pedido — a única diferença estrutural é a presença ou não de `commission_data`.

## Fluxo típico

1. **Simule** a seleção para descobrir a faixa de preço vendável de cada produto.
2. Escolha o preço final dentro da faixa e **cote** com `commission_type: total_gross_premium_amount` para ver o preço exato e o veredito de elegibilidade.
3. **Submeta o pedido** com a mesma lista `products[]` — ele é reprecificado com o mesmo motor no momento da submissão.

:::info Preços são indicativos
Cotação e simulação rodam contra a configuração **vigente** — não há token de cotação, snapshot de tarifa nem prazo de validade. **O preço calculado na submissão do pedido é o que vale.**
:::

## Endpoints

| Endpoint | Descrição |
|---|---|
| [`POST /v1/insurance/quote`](/documentation/seguros/cotacao/criar_cotacao) | Precifica uma seleção com uma configuração de comissão específica. |
| [`POST /v1/insurance/simulate`](/documentation/seguros/cotacao/simular_precos) | Retorna a faixa de preço vendável de uma seleção, variando a comissão. |

---

# Simular faixa de preço

URL: /documentation/seguros/cotacao/simular_precos

Retorna a **faixa de preço vendável** de uma seleção — o menor e o maior preço final possíveis para cada produto, variando apenas a comissão dentro da sua faixa (`commission_bounds`). Use-a para montar ofertas com preço customizado: o valor enviado em `commission_data` com `commission_type: total_gross_premium_amount` no [pedido](/documentation/seguros/pedidos/criar_pedido) deve estar dentro dessa faixa.

Assim como a cotação, a simulação é uma calculadora: nada é persistido.

## Request

ENDPOINT /v1/insurance/simulate
MÉTODO POST

O request usa a mesma lista `products[]` da [cotação](/documentation/seguros/cotacao/criar_cotacao) — **sem** `commission_data`: a simulação varre a faixa de comissão inteira, então enviar uma comissão é `400`.

```json title="Request Body"
{
  "products": [
    {
      "product_key": "9d1f8c7a-3b21-4e60-8a2f-1c5d7e9b0a44",
      "term": {
        "start_date": "2026-07-16",
        "end_date": "2028-07-15"
      },
      "services": [
        {
          "service_key": "0a3c5e7f-2b4d-4a6c-8e0f-1a3b5c7d9e2f",
          "insured_amount_basis": "monetary_amount",
          "insured_amount": 50000.00
        }
      ],
      "risk_object": {
        "type": "credit_operation",
        "insurable_value": 50000.00,
        "attributes": {
          "installment_amount": 1050.00,
          "number_of_installments": 48
        }
      }
    }
  ],
  "customer": {
    "date_of_birth": "1987-03-22",
    "occupation_code": "211205"
  }
}
```

## Response

STATUS 200

```json title="Response Body"
{
  "total_order_floor_amount": 583.10,
  "total_order_ceiling_amount": 686.42,
  "products": [
    {
      "product_key": "9d1f8c7a-3b21-4e60-8a2f-1c5d7e9b0a44",
      "result": "priced",
      "name": "Prestamista Master",
      "provider_name": "QI Seguradora",
      "product_category": "insurance",
      "insurance_class": {
        "name": "credit_life",
        "class_number": "0977",
        "group_number": "09"
      },
      "contract_instrument_type": "ticket",
      "regulator_registration": "15414.900388/2015-21",
      "term": {
        "start_date": "2026-07-16",
        "end_date": "2028-07-15"
      },
      "price_range": {
        "floor_gross_premium_amount": 583.10,
        "ceiling_gross_premium_amount": 686.42,
        "floor_requester_amount": 29.16,
        "ceiling_requester_amount": 137.28,
        "minimum_requester_rate": 0.0500,
        "maximum_requester_rate": 0.2000
      },
      "services": [
        {
          "service_key": "0a3c5e7f-2b4d-4a6c-8e0f-1a3b5c7d9e2f",
          "service_type": {
            "code": "credit_life",
            "name": "Prestamista (Credit Life)"
          },
          "service_category": "insurance",
          "regulator_registration": null,
          "insured_amount": 50000.00,
          "unit_amount": null,
          "unit_count": null,
          "deductible_data": {
            "deductible_type": "monetary_amount",
            "value": 1500.00
          },
          "waiting_period_days": 30,
          "service_attributes": {}
        }
      ]
    }
  ],
  "eligibility": "eligible"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `total_order_floor_amount` | number | Menor valor total possível do pedido (todas as comissões na taxa mínima). |
| `total_order_ceiling_amount` | number | Maior valor total possível do pedido (todas as comissões na taxa máxima). |
| `products` | array | Uma linha por produto solicitado, na ordem do request. Linhas rejeitadas são **byte a byte idênticas** às da [cotação](/documentation/seguros/cotacao/criar_cotacao#motivos-de-rejeicao) — `product_key`, `result: "rejected"` e `decline_reasons` — porque foram recusadas pelo mesmo motivo, no mesmo estágio. |
| `eligibility` | string | Veredito de elegibilidade da simulação: `eligible`, `declined` ou `not_evaluated`. |

#### Objeto em `products` (linha precificada)

A linha da simulação é **a linha da cotação com todos os campos de prêmio substituídos por uma única faixa**: mesma identidade, mesma classificação, mesmo `term` ecoado, mesmas coberturas realizadas — só o dinheiro muda. Ela traz `product_key`, `result`, `name`, `provider_name`, `product_category`, `insurance_class`, `contract_instrument_type`, `regulator_registration`, `term`, `price_range` e `services[]`.

`services[]` tem exatamente a forma da cotação **menos** o `gross_premium_amount` da cobertura: um prêmio por cobertura é uma decomposição no grão que a faixa deliberadamente não fixa. Todo o resto — importância segurada resolvida, par por unidade, franquia, carência e atributos — permanece, porque é o que você está vendendo.

#### Objeto `price_range`

| Campo | Tipo | Descrição |
|---|---|---|
| `floor_gross_premium_amount` | number | Menor preço final possível do produto (comissão na taxa mínima). |
| `ceiling_gross_premium_amount` | number | Maior preço final possível do produto (comissão na taxa máxima). |
| `floor_requester_amount` | number | A sua comissão em R$ no piso da faixa. |
| `ceiling_requester_amount` | number | A sua comissão em R$ no teto da faixa. |
| `minimum_requester_rate` | number | Taxa mínima da sua faixa de comissão para o produto. |
| `maximum_requester_rate` | number | Taxa máxima da sua faixa de comissão para o produto. |

Um `total_gross_premium_amount` igual ao piso ou ao teto da faixa usa exatamente a taxa `minimum_requester_rate`/`maximum_requester_rate`, sem arredondamento intermediário.

:::info Não há prêmio na simulação
A simulação **não** devolve `gross_premium_amount`, `iof_amount` nem `net_premium_amount`, em nenhum nível. Os extremos da faixa são os únicos valores de prêmio desta superfície. Para o preço fechado e decomposto, use a [cotação](/documentation/seguros/cotacao/criar_cotacao).
:::

## Possíveis erros

Todo erro (`non-2xx`) retorna o corpo padrão `{ "title", "description", "translation", "code" }` — trate programaticamente **apenas** o campo `code`.

| Status | Código | Descrição |
|---|---|---|
| `400` | `QIT000001` | Requisição malformada — inclusive `commission_data` presente em alguma linha. |
| `401` / `403` | — | Falha de autenticação ou autorização. |
| `429` | — | Limite de requisições excedido — repita com backoff. |
| `503` | — | Motor de precificação indisponível. Repita a chamada. |

---

# Consultar extrato

URL: /documentation/seguros/financeiro/consultar_extrato

:::caution Superfície ainda não disponível
Os endpoints financeiros descritos nesta seção **ainda não estão publicados** no gateway externo. Esta seção descreve o contrato-alvo e pode mudar antes da liberação — confirme a disponibilidade com o time de Integração ([api@qitech.com.br](mailto:api@qitech.com.br)) antes de implementar contra ela.
:::

Retorna o extrato paginado das movimentações da sua posição de comissão: créditos por parcela liquidada, estornos de cancelamento e liquidações de repasse. Cada movimentação de comissão é correlacionada à apólice que a originou pelo `policy_key`.

## Request

ENDPOINT /finance/v1/statement
MÉTODO GET

### Query params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `page` | integer | opcional | Número da página. Padrão: `1`. |
| `page_size` | integer | opcional | Registros por página. Padrão: `50`. Máximo: `200`. |
| `from` | string | opcional | Data mínima da movimentação (`AAAA-MM-DD`). |
| `to` | string | opcional | Data máxima da movimentação (`AAAA-MM-DD`). |

```python title="Exemplo de chamada"
GET /finance/v1/statement?from=2026-07-01&to=2026-07-31&page=1&page_size=50
```

## Response

STATUS 200

```json title="Response Body"
{
  "items": [
    {
      "event_type": "REQUESTER_COMMISSION_BOOKED",
      "amount": "14.64",
      "policy_key": "0b6e7c1a-9a4e-4c1e-b1d4-2f5a8c9e0d31",
      "installment_number": 1,
      "occurred_at": "2026-07-20T14:05:01.000Z"
    },
    {
      "event_type": "REQUESTER_CLAWBACK_BOOKED",
      "amount": "-14.64",
      "policy_key": "0b6e7c1a-9a4e-4c1e-b1d4-2f5a8c9e0d31",
      "occurred_at": "2026-07-25T11:00:00.000Z"
    },
    {
      "event_type": "TRANSFER_SETTLED",
      "amount": "-980.10",
      "transfer_key": "3c4d5e6f-7a8b-4c9d-0e1f-2a3b4c5d6e7f",
      "occurred_at": "2026-07-21T09:00:12.000Z"
    }
  ],
  "page": 1,
  "page_size": 50,
  "total": 3
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `items` | array | Movimentações da sua posição, da mais recente para a mais antiga. |
| `page` | integer | Página atual. |
| `page_size` | integer | Tamanho da página solicitado. |
| `total` | integer | Total de movimentações no período. |

#### Objeto em `items`

| Campo | Tipo | Descrição |
|---|---|---|
| `event_type` | string | Tipo da movimentação. Veja a tabela de tipos abaixo. |
| `amount` | string | Valor **com sinal**: positivo credita a posição, negativo debita (estornos e liquidações de repasse). |
| `policy_key` | string | Apólice que originou a movimentação. Presente em créditos de comissão e estornos. |
| `installment_number` | integer | Número da parcela liquidada que originou o crédito. Presente em créditos de comissão. |
| `transfer_key` | string | Repasse correspondente. Presente em liquidações de repasse. |
| `occurred_at` | string | Instante da movimentação. |

### Tipos de movimentação

| `event_type` | Sinal | Significado |
|---|---|---|
| `REQUESTER_COMMISSION_BOOKED` | `+` | Comissão creditada sobre uma parcela de prêmio liquidada. |
| `REQUESTER_CLAWBACK_BOOKED` | `−` | Estorno de comissão pelo cancelamento de uma apólice com devolução de prêmio. |
| `TRANSFER_SETTLED` | `−` | Repasse liquidado na sua conta — a posição é debitada pelo valor transferido. |
| `MANUAL_ADJUSTMENT` | `+`/`−` | Ajuste operacional lançado pela QI Tech (ex.: resolução de incidente). |

## Possíveis erros

| Status | Descrição |
|---|---|
| `400` | Parâmetro de filtro ou paginação inválido. |
| `401` / `403` | Falha de autenticação ou autorização. |
| `500` / `503` | Erro interno ou serviço indisponível — seguro repetir a chamada. |

---

# Consultar saldo

URL: /documentation/seguros/financeiro/consultar_saldo

:::caution Superfície ainda não disponível
Os endpoints financeiros descritos nesta seção **ainda não estão publicados** no gateway externo. Esta seção descreve o contrato-alvo e pode mudar antes da liberação — confirme a disponibilidade com o time de Integração ([api@qitech.com.br](mailto:api@qitech.com.br)) antes de implementar contra ela.
:::

Retorna o saldo da sua posição de comissão: o valor pendente de liberação, o valor disponível para o próximo repasse e a data prevista da próxima transferência.

## Request

ENDPOINT /finance/v1/balance
MÉTODO GET

## Response

STATUS 200

```json title="Response Body"
{
  "account_key": "7a1b2c3d-0e4f-4a5b-8c6d-9e0f1a2b3c4d",
  "pending_amount": "1250.40",
  "available_amount": "980.10",
  "next_transfer_date": "2026-07-21"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `account_key` | string | Chave da sua conta de comissão na QI Tech. |
| `pending_amount` | string | Total creditado que ainda não atingiu a data de liberação do cronograma de repasse. |
| `available_amount` | string | Valor líquido liberado (créditos menos estornos), que entrará no próximo repasse. |
| `next_transfer_date` | string | Data prevista do próximo repasse, conforme a cadência configurada para a sua conta. |

:::info Saldo negativo
Estornos de cancelamento podem deixar a posição temporariamente negativa. Nesse caso nenhum repasse é executado até que novos créditos compensem o saldo — a QI Tech nunca debita a sua conta.
:::

## Possíveis erros

| Status | Descrição |
|---|---|
| `401` / `403` | Falha de autenticação ou autorização. |
| `500` / `503` | Erro interno ou serviço indisponível — seguro repetir a chamada. |

---

# Início

URL: /documentation/seguros/financeiro/inicio

:::caution Superfície ainda não disponível
Os endpoints financeiros descritos nesta seção **ainda não estão publicados** no gateway externo. Esta seção descreve o contrato-alvo e pode mudar antes da liberação — confirme a disponibilidade com o time de Integração ([api@qitech.com.br](mailto:api@qitech.com.br)) antes de implementar contra ela.
:::

A superfície **Financeiro** dá visibilidade sobre a sua remuneração como distribuidor: o saldo da sua posição de comissão, o extrato de movimentações e os repasses realizados pela QI Tech para a sua conta.

## Como a sua comissão é apurada

A apuração é feita em **regime de caixa, por parcela de apólice**: a cada parcela de prêmio efetivamente liquidada pelo segurado, a sua comissão sobre aquela parcela é creditada na sua posição. Nada é creditado antes de o dinheiro entrar.

- **Crédito** — a cada parcela liquidada, a sua fatia (calculada com a taxa de comissão congelada na venda) vira um lançamento a pagar na sua posição.
- **Estorno (clawback)** — o cancelamento de uma apólice com devolução de prêmio gera um lançamento **negativo**, que compensa a comissão correspondente. Lançamentos negativos nunca geram cobrança contra a sua conta: eles são abatidos dos seus próximos créditos.
- **Repasse** — em uma cadência configurada para a sua conta (diária, semanal ou mensal, com valor mínimo opcional), a QI Tech agrega a posição líquida disponível e executa a transferência para a sua conta.

## Saldo pendente × disponível

| Conceito | Significado |
|---|---|
| `pending_amount` | Lançamentos creditados que ainda não atingiram a data de liberação do seu cronograma de repasse. |
| `available_amount` | Valor líquido já liberado, que entrará no próximo repasse. |

## Endpoints

| Endpoint | Descrição |
|---|---|
| [`GET /finance/v1/balance`](/documentation/seguros/financeiro/consultar_saldo) | Saldo da sua posição de comissão. |
| [`GET /finance/v1/statement`](/documentation/seguros/financeiro/consultar_extrato) | Extrato das suas movimentações. |
| [`GET /finance/v1/transfers`](/documentation/seguros/financeiro/listar_transferencias) | Repasses realizados para a sua conta. |

:::info
Os endpoints financeiros são somente de leitura: não existe endpoint de movimentação de dinheiro nesta superfície. Os repasses são executados automaticamente pela QI Tech conforme a configuração da sua conta.
:::

---

# Listar repasses

URL: /documentation/seguros/financeiro/listar_transferencias

:::caution Superfície ainda não disponível
Os endpoints financeiros descritos nesta seção **ainda não estão publicados** no gateway externo. Esta seção descreve o contrato-alvo e pode mudar antes da liberação — confirme a disponibilidade com o time de Integração ([api@qitech.com.br](mailto:api@qitech.com.br)) antes de implementar contra ela.
:::

Retorna a lista paginada dos repasses de comissão executados (ou em execução) para a sua conta.

## Request

ENDPOINT /finance/v1/transfers
MÉTODO GET

### Query params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `page` | integer | opcional | Número da página. Padrão: `1`. |
| `page_size` | integer | opcional | Registros por página. Padrão: `50`. Máximo: `200`. |
| `status` | string | opcional | Filtra pelo status do repasse. |

```python title="Exemplo de chamada"
GET /finance/v1/transfers?status=SETTLED&page=1
```

## Response

STATUS 200

```json title="Response Body"
{
  "items": [
    {
      "transfer_key": "3c4d5e6f-7a8b-4c9d-0e1f-2a3b4c5d6e7f",
      "amount": "980.10",
      "status": "SETTLED",
      "scheduled_date": "2026-07-21",
      "settled_at": "2026-07-21T09:00:12.000Z"
    },
    {
      "transfer_key": "4d5e6f7a-8b9c-4d0e-1f2a-3b4c5d6e7f8a",
      "amount": "1250.40",
      "status": "PENDING",
      "scheduled_date": "2026-07-28",
      "settled_at": null
    }
  ],
  "page": 1,
  "page_size": 50,
  "total": 2
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `items` | array | Repasses, do mais recente para o mais antigo. |
| `page` | integer | Página atual. |
| `page_size` | integer | Tamanho da página solicitado. |
| `total` | integer | Total de repasses que atendem aos filtros. |

#### Objeto em `items`

| Campo | Tipo | Descrição |
|---|---|---|
| `transfer_key` | string | Chave única do repasse — a mesma referenciada nas movimentações `TRANSFER_SETTLED` do [extrato](/documentation/seguros/financeiro/consultar_extrato). |
| `amount` | string | Valor líquido do repasse (créditos carregados menos estornos compensados). |
| `status` | string | Status do repasse. Veja a tabela abaixo. |
| `scheduled_date` | string | Data programada da execução. |
| `settled_at` | string | Instante da liquidação. `null` enquanto não liquidado. |

### Status do repasse

| Status | Significado |
|---|---|
| `PENDING` | Repasse montado, aguardando execução na data programada. |
| `PROCESSING` | Instrução de transferência enviada, aguardando liquidação. |
| `SETTLED` | Liquidado na sua conta. Status terminal. |
| `FAILED` | A transferência falhou; será reprocessada. Os valores retornam à sua posição disponível até a nova tentativa. |

## Possíveis erros

| Status | Descrição |
|---|---|
| `400` | Parâmetro de filtro ou paginação inválido. |
| `401` / `403` | Falha de autenticação ou autorização. |
| `500` / `503` | Erro interno ou serviço indisponível — seguro repetir a chamada. |

---

# Autenticação

URL: /documentation/seguros/introducao/autenticacao

A autenticação do Insurance-as-a-Service segue o **padrão de requisição assinada da QI Tech** — o mesmo utilizado no Lending-as-a-Service, no Banking-as-a-Service e na QI DTVM. Se você já integra qualquer outra linha de produto QI Tech, o mecanismo é idêntico; muda apenas o host.

## Requisição assinada

Todas as requisições devem usar **HTTPS** com **TLS 1.2 ou 1.3** e conter dois headers:

| Header           | Descrição                                                                                    |
| ---------------- | -------------------------------------------------------------------------------------------- |
| `API-CLIENT-KEY` | Chave disponibilizada pelo time de Integração da QI Tech que identifica a sua integração.     |
| `AUTHORIZATION`  | Assinatura da requisição no padrão JWT, gerada com a sua chave privada.                       |

A QI Tech utiliza o padrão de chaves assimétricas: você gera um par de chaves, assina cada requisição com a sua **chave privada** e a QI Tech valida a assinatura com a sua **chave pública**.

O passo a passo completo — geração do par de chaves, envio da chave pública à QI Tech e montagem do header `AUTHORIZATION` — está descrito em:

- [Troca de Chaves](/documentation/seguros/primeiros_passos/seguros_troca_de_chaves)
- [Teste de Autenticação](/documentation/seguros/primeiros_passos/teste_de_autenticacao/seguros_teste_de_autenticacao_v2)
- [Exemplo Completo de Autenticação](/documentation/seguros/primeiros_passos/teste_de_autenticacao/seguros_teste_de_autenticacao_completo)
- [Possíveis Erros de Autenticação](/documentation/seguros/primeiros_passos/teste_de_autenticacao/seguros_possiveis_erros)

:::caution Atenção
A chave privada é de uso exclusivo do parceiro integrador e deve ser armazenada com segurança. A QI Tech nunca irá pedir, em hipótese alguma, que você a compartilhe.
:::

Opcionalmente, você pode restringir as chamadas da sua integração a uma lista de endereços IP autorizados. Veja [Configurar IP de Integração](/documentation/seguros/primeiros_passos/seguros_configurar_ip_de_integracao).

## Recebimento de webhooks

Os eventos de pedido e apólice são notificados na URL de callback configurada para a sua integração. Para configurar a URL, siga [Configurando Webhooks](/documentation/seguros/primeiros_passos/seguros_configurando_webhooks) e valide o recebimento com [Validação de Webhooks](/documentation/seguros/primeiros_passos/teste_de_autenticacao/seguros_webhook_v2).

Os webhooks da QI Tech seguem uma estrutura padrão:

```json
{
  "webhook_type": "<tipo_do_evento>",
  "webhook_datetime": "2026-07-16T14:03:22Z",
  "data": {}
}
```

| Campo              | Tipo   | Descrição                                   |
| ------------------ | ------ | ------------------------------------------- |
| `webhook_type`     | string | Identificador do tipo de evento.            |
| `webhook_datetime` | string | Data e hora do evento no formato ISO 8601.  |
| `data`             | object | Dados específicos do evento.                |

Os eventos disponíveis nesta linha de produto estão descritos em [Webhooks de Pedido](/documentation/seguros/pedidos/webhooks) e [Webhooks de Apólice](/documentation/seguros/apolices/webhooks).

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeados de forma estrita.
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

---

# Introdução

URL: /documentation/seguros/introducao/inicio

O **Insurance-as-a-Service** da QI Tech permite que parceiros distribuam produtos de seguro por API: consulta do catálogo de produtos habilitados, cotação, venda (pedido com aceite e pagamento do segurado), acompanhamento das apólices emitidas e do repasse financeiro das comissões.

Essa documentação descreve os fluxos, endpoints e estruturas de dados da jornada completa de distribuição de seguros.

Obs.: Em caso de dúvidas em qualquer etapa do processo, favor entrar em contato com [api@qitech.com.br](mailto:api@qitech.com.br) detalhando seu problema/dúvida que te auxiliaremos.

## Visão geral da jornada

1. **Catálogo** — consulte os produtos de seguro que a sua integração está habilitada a distribuir, com as coberturas, limites e a sua faixa de comissão ([Catálogo de Produtos](/documentation/seguros/catalogo/inicio)).
2. **Cotação** — precifique uma seleção de produtos e coberturas para um cliente, sem criar nenhum recurso ([Criar cotação](/documentation/seguros/cotacao/criar_cotacao)), e descubra a faixa de preço vendável de cada produto ([Simular faixa de preço](/documentation/seguros/cotacao/simular_precos)).
3. **Pedido** — submeta a venda, já com o **aceite** que você coletou do segurado. O pedido nasce aguardando o **pagamento** da primeira parcela; confirmado o pagamento, o pedido é emitido ([Pedidos](/documentation/seguros/pedidos/inicio)).
4. **Apólices** — a emissão do pedido gera uma apólice por produto vendido, emitida junto à seguradora. Consulte e cancele apólices individualmente ([Apólices](/documentation/seguros/apolices/inicio)). _Superfície ainda não publicada._
5. **Financeiro** — acompanhe o seu saldo de comissão, o extrato de movimentações e os repasses realizados ([Financeiro](/documentation/seguros/financeiro/inicio)). _Superfície ainda não publicada._

Cada etapa relevante notifica a sua URL de callback por [webhooks de pedido](/documentation/seguros/pedidos/webhooks) e [webhooks de apólice](/documentation/seguros/apolices/webhooks).

## Ambientes (Hosts)

O Insurance-as-a-Service possui dois ambientes, SANDBOX e PRODUÇÃO. Ambos possuem comportamento idêntico, porém o ambiente de SANDBOX opera com valores e emissões totalmente fictícios, enquanto o de Produção realiza transações e emissões válidas.

| Ambiente | Host                                       |
| -------- | ------------------------------------------ |
| Sandbox  | https://api.sandbox.insurance.qitech.app   |
| Produção | https://api.insurance.qitech.app           |

:::danger Aviso Importante!
Não devem ser usados dados reais de pessoas físicas e/ou jurídicas nos ambientes de Sandbox da QI Tech.
:::

## Convenções da API

- Os paths são versionados com o segmento de versão **liderando** o caminho (ex.: `/v1/insurance/order`, `/v1/product_catalog/products`).
- Todos os recursos são endereçados por chaves públicas UUID (`order_key`, `policy_key`, `product_key`), nunca por identificadores numéricos internos.
- Os paths de coleção nem sempre são plurais: a criação e a listagem de pedidos vivem em `/v1/insurance/order` (singular), enquanto as rotas por chave usam `/v1/insurance/orders/{order_key}`. Siga o path indicado na página de cada endpoint.
- Valores monetários trafegam como **número JSON com 2 casas decimais** (ex.: `312.48`, nunca string), sempre em BRL e sempre **brutos** (com IOF). Taxas e percentuais são números com 4 casas em `(0, 1]` (ex.: `0.1000`). Identificadores numéricos com zeros à esquerda significativos (documentos, códigos de ramo) permanecem strings.
- Status são strings de enumerador em caixa baixa (ex.: `awaiting_payment`, `emitted`). Não mapeie o conjunto de forma fechada — veja os [status reservados](/documentation/seguros/pedidos/inicio).
- Vigências são objetos aninhados `term: { "start_date", "end_date" }` — por produto e por cobertura.
- Datas seguem `AAAA-MM-DD` e data-hora segue ISO 8601 (`2026-07-16T14:03:22Z`).
- Listagens usam paginação por offset, mas **a forma varia por superfície** — confira sempre a página do endpoint. Pedidos usam `page` / `page_size` (padrão `50`, máximo `200`) e devolvem `{ items, page, page_size, total }`; o catálogo de produtos usa `page` / `rows_per_page` (padrão `50`) e devolve `{ data, pagination { current_page, next_page, rows_per_page } }`, sem `total`.
- Todo erro (`non-2xx`) retorna o corpo padrão `{ "title", "description", "translation", "code" }`. O `code` é o **único** campo para tratamento programático — `title`/`description`/`translation` podem mudar sem aviso.
- O escopo de acesso é sempre o da sua integração: uma chave de outro parceiro é indistinguível de uma chave inexistente e retorna `404`.

## Para começar

A autenticação segue o padrão QI Tech de requisições assinadas, o mesmo utilizado nas demais linhas de produto. Veja [Autenticação](/documentation/seguros/introducao/autenticacao).

Antes de consumir os endpoints desta documentação, complete os passos abaixo **em ambiente de sandbox**:

1. Entrar em contato com o time de Integração ([api@qitech.com.br](mailto:api@qitech.com.br)) para iniciar o onboarding da sua integração.
2. [Gerar o par de chaves e enviar a sua chave pública por meio seguro](/documentation/seguros/primeiros_passos/seguros_troca_de_chaves) para receber as credenciais de integração.
3. [Realizar o teste de autenticação](/documentation/seguros/primeiros_passos/teste_de_autenticacao/seguros_teste_de_autenticacao_v2).
4. [Configurar a URL de recebimento de webhooks](/documentation/seguros/primeiros_passos/seguros_configurando_webhooks).

---

# Cancelar pedido

URL: /documentation/seguros/pedidos/cancelar_pedido

Cancela um pedido. O comportamento depende do momento:

- **Antes da emissão** (`awaiting_payment`): a venda é desfeita e o pedido vai para `cancelled`.
- **Depois da emissão** (`emitted`): o pedido em si não muda de status. A chamada dispara **um pedido de cancelamento por apólice** do pedido; cada apólice segue o seu próprio [fluxo de cancelamento](/documentation/seguros/apolices/cancelar_apolice), incluindo o cálculo da devolução de prêmio.

## Request

ENDPOINT /v1/insurance/orders/{order_key}/cancel
MÉTODO POST

### Path params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `order_key` | string | obrigatório | Chave do pedido. |

```json title="Request Body"
{
  "reason": "Cliente desistiu da compra"
}
```

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `reason` | string | opcional | Motivo do cancelamento, registrado na trilha de eventos e propagado aos cancelamentos de apólice no caso pós-emissão. |

## Response

:::caution O QR Pix não é revogado no cancelamento pré-emissão
Nesta versão o cancelamento pré-emissão é uma transação local: o mandato Pix **não** é cancelado na cobrança, e o QR simplesmente expira junto com a janela de pagamento. Um segurado que autorize o pagamento mesmo assim paga em um pedido já `cancelled` — o pagamento é barrado antes da emissão e devolvido ao pagador. Trate o cancelamento como definitivo e pare de exibir o QR ao segurado.
:::

### Pré-emissão

STATUS 200

```json title="Response Body"
{
  "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
  "status": "cancelled"
}
```

### Pós-emissão

STATUS 202

```json title="Response Body"
{
  "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
  "status": "emitted",
  "policies_cancellation_requested": 2
}
```

| Campo | Tipo | Descrição |
|---|---|---|
| `policies_cancellation_requested` | integer | Quantidade de apólices cujo cancelamento foi solicitado — uma por produto do pedido. Acompanhe cada uma pelos [webhooks de apólice](/documentation/seguros/apolices/webhooks) ou pela [consulta de apólice](/documentation/seguros/apolices/consultar_apolice). |

### Semântica por status

| Status atual do pedido | Resultado |
|---|---|
| `awaiting_payment` | `200` — venda desfeita, pedido vai para `cancelled`. |
| `emitted` | `202` — cancelamento solicitado para cada apólice; o pedido permanece `emitted`. |
| `cancelled` | `200` — idempotente, nada muda. |
| `rejected` / `declined` / `expired` | `409` — status terminal, nada a cancelar. |

:::info Corrida entre pagamento e cancelamento
Se um pagamento for confirmado praticamente ao mesmo tempo do cancelamento pré-emissão, o pedido ainda é cancelado: o pagamento é barrado antes da emissão e devolvido ao pagador. Se o pagamento tiver sido confirmado **antes** e o pedido já estiver `emitted`, a mesma chamada passa a valer como cancelamento pós-emissão (`202`) — nunca há `409` nessa corrida.
:::

## Possíveis erros

Todo erro (`non-2xx`) retorna o corpo padrão `{ "title", "description", "translation", "code" }` — trate programaticamente **apenas** o campo `code`.

| Status | Código | Descrição |
|---|---|---|
| `401` / `403` | — | Falha de autenticação ou autorização. |
| `404` | `ORD000001` | Pedido inexistente ou pertencente a outra integração. |
| `409` | `ORD000010` | O pedido está em um status terminal sem nada a cancelar (`rejected`, `declined`, `expired`). |
| `502` / `504` | `ORD000031` | Falha em uma integração síncrona do cancelamento. Nenhum estado foi alterado — repita a chamada, ela é idempotente. |

---

# Consultar pedido

URL: /documentation/seguros/pedidos/consultar_pedido

Retorna o detalhe completo de um pedido: identidade, status, prazo de pagamento, os produtos congelados na submissão (com seus objetos de risco), a cobrança, o segurado e a trilha de eventos.

:::info O pedido não retorna apólices
O pedido é a visão da **venda**. Após a emissão (`emitted`), as apólices vivem em um recurso próprio — consulte-as com [`GET /v1/insurance/policies?order_key=`](/documentation/seguros/apolices/listar_apolices).
:::

## Request

ENDPOINT /v1/insurance/orders/{order_key}
MÉTODO GET

### Path params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `order_key` | string | obrigatório | Chave do pedido. |

## Response

STATUS 200

```json title="Response Body"
{
  "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
  "status": "emitted",
  "distribution_type": "direct",
  "quote_data": {
    "total_order_amount": 617.28,
    "products": [
      {
        "order_product_key": "7f3a9c2e-0b5d-4e8a-a1c6-9d4b2e7f0a53",
        "product_key": "9d1f8c7a-3b21-4e60-8a2f-1c5d7e9b0a44",
        "product_category": "insurance",
        "insurance_class": {
          "name": "credit_life",
          "class_number": "0977",
          "group_number": "09"
        },
        "regulator_registration": "15414.900388/2015-21",
        "contract_instrument_type": "ticket",
        "gross_premium_amount": 617.28,
        "iof_amount": 2.35,
        "net_premium_amount": 614.93,
        "term": {
          "start_date": "2026-07-15",
          "end_date": "2027-07-14"
        },
        "risk_object": {
          "type": "credit_operation",
          "insurable_value": 50000.00,
          "attributes": {
            "installment_amount": 1050.00,
            "number_of_installments": 48
          }
        },
        "services": [
          {
            "service_key": "0a3c5e7f-2b4d-4a6c-8e0f-1a3b5c7d9e2f",
            "service_type": {
              "code": "credit_life",
              "name": "Prestamista (Credit Life)"
            },
            "service_category": "insurance",
            "regulator_registration": null,
            "gross_premium_amount": 617.28,
            "insured_amount": 50000.00,
            "unit_amount": null,
            "unit_count": null,
            "deductible_data": {
              "deductible_type": "monetary_amount",
              "value": 1500.00
            },
            "waiting_period_days": 30,
            "service_attributes": {},
            "term": {
              "start_date": "2026-07-15",
              "end_date": "2027-07-14"
            }
          }
        ]
      }
    ]
  },
  "payment_data": {
    "payment_method": "pix_automatic",
    "installment_count": 12,
    "installment_amount": 51.44,
    "first_installment_amount": 51.44,
    "first_due_date": "2026-07-23"
  },
  "customer": {
    "document_number": "96969879003",
    "name": "Maria Souza",
    "email": "maria@example.com",
    "phone_number": "+5511999990000",
    "date_of_birth": "1987-03-22",
    "occupation_code": "211205"
  },
  "events": [
    {
      "new_status": "emitted",
      "at": "2026-07-16T14:03:22Z"
    }
  ]
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `order_key` | string | Chave única do pedido. |
| `status` | string | Status atual. Veja o [ciclo de vida](/documentation/seguros/pedidos/inicio). |
| `expires_at` | string | Prazo para o pagamento da primeira parcela (7 dias a partir da submissão). `null` em um pedido `rejected`. |
| `distribution_type` | string | Modelo de distribuição da venda. Hoje sempre `direct`. |
| `payment_data` | object | A cobrança do pedido — mesmo bloco retornado na [criação](/documentation/seguros/pedidos/criar_pedido#objeto-payment_data-resposta). O sub-objeto `payment_artifact` (o QR Pix) só é reexposto enquanto o pedido está `awaiting_payment`; em um pedido emitido ou terminal ele é omitido. `null` em um pedido `rejected`. |
| `quote_data` | object | Os produtos congelados na submissão — mesmo bloco, com a mesma forma, retornado na [criação do pedido](/documentation/seguros/pedidos/criar_pedido). |
| `quote_data.total_order_amount` | number | Valor total do pedido (soma dos prêmios brutos dos produtos). |
| `customer` | object | O segurado do pedido, em objeto plano: `document_number`, `name`, `email`, `phone_number`, `date_of_birth`, `occupation_code`. Devolvido exatamente como foi submetido — a data de nascimento é o dado congelado; a idade usada na precificação foi derivada dela na submissão e não é armazenada. Os campos opcionais (`occupation_code`, `address`) **só aparecem se tiverem sido enviados**: nada é preenchido por padrão, e a chave é omitida em vez de vir `null`. |
| `events` | array | Trilha de mudanças de status do pedido, em ordem cronológica. Cada entrada é `{ "new_status", "at" }`. |

#### Objeto em `quote_data.products`

| Campo | Tipo | Descrição |
|---|---|---|
| `order_product_key` | string | Chave do produto dentro do pedido — a correlação com a apólice gerada na emissão. |
| `product_key` | string | Chave do produto no catálogo. |
| `product_category` | string | Categoria do produto: `insurance`, `capitalization` ou `benefit`. |
| `insurance_class` | object | Ramo do seguro: `{ name, class_number, group_number }`. `null` para produtos não securitários. |
| `regulator_registration` | string | Registro do produto no regulador (ex.: processo SUSEP). |
| `contract_instrument_type` | string | Instrumento contratual congelado do produto: `ticket` (bilhete) ou `policy` (apólice). `null` para produtos não securitários. |
| `gross_premium_amount` | number | Prêmio bruto do produto (com IOF). |
| `iof_amount` | number | IOF do produto. |
| `net_premium_amount` | number | Prêmio líquido do produto (sem IOF). |
| `term` | object | Vigência do produto, congelada na submissão: `{ start_date, end_date }`. Produtos do mesmo pedido podem ter vigências diferentes. |
| `risk_object` | object | O objeto de risco congelado deste produto (`type`, `insurable_value`, `attributes`). |
| `services` | array | Coberturas congeladas — cada uma com `service_type` (`{ code, name }`), `service_category`, `regulator_registration`, prêmio bruto, importância segurada, o par por unidade (`unit_amount` / `unit_count`, `null` quando a cobertura não é precificada por unidade), franquia (`deductible_data`), carência (`waiting_period_days`), atributos e vigência (`term`). |

:::caution Pedido `rejected` na consulta
Um pedido nascido `rejected` não persiste produtos nem cobrança: a consulta devolve `quote_data.products` vazio e `payment_data` nulo, e **não** repete os `decline_reasons`. Os motivos da recusa são entregues uma única vez, no `201` da [submissão](/documentation/seguros/pedidos/criar_pedido#pedido-recusado-rejected) — registre-os no seu lado.
:::

## Possíveis erros

Todo erro (`non-2xx`) retorna o corpo padrão `{ "title", "description", "translation", "code" }` — trate programaticamente **apenas** o campo `code`.

| Status | Código | Descrição |
|---|---|---|
| `401` / `403` | — | Falha de autenticação ou autorização. |
| `404` | `ORD000001` | Pedido inexistente ou pertencente a outra integração — os casos são indistinguíveis. |
| `500` / `503` | `QIT000500` | Erro interno ou serviço indisponível — seguro repetir a chamada. |

---

# Criar pedido

URL: /documentation/seguros/pedidos/criar_pedido

Cria e submete um pedido em uma única chamada. A submissão reprecifica a seleção no servidor (preços enviados pelo cliente nunca são confiados), valida o **aceite** que você coletou do segurado, cria a cobrança do prêmio e devolve o pedido em `awaiting_payment`, com o artefato Pix que o segurado deve pagar.

A lista `products[]` é **a mesma da [cotação](/documentation/seguros/cotacao/criar_cotacao)** — cotação e pedido usam a mesma gramática de seleção, acrescida do bloco `acceptance` por produto. A cotação é **indicativa**: a submissão reprecifica contra a configuração vigente e o preço do submit é o que vale.

:::info O aceite é coletado por você
A QI Tech não renderiza documento de proposta nem hospeda tela de assinatura nesta versão. Você conduz a cerimônia de aceite no seu próprio fluxo e **atesta** o resultado no campo `acceptance` de cada produto. Não existe `acceptance_url`.
:::

:::caution Apenas bilhete (`ticket`) nesta versão
O produto informa em `contract_instrument_type` se é vendido como **bilhete** (`ticket`) ou como **apólice** (`policy`). O bilhete dispensa proposta — o contrato se forma pelo ato da compra, e é por isso que o aceite atestado por você basta. Produtos `policy` ainda **não são vendáveis** e são recusados com `ORD000033`. O campo é ecoado na [cotação](/documentation/seguros/cotacao/criar_cotacao), então você descobre o instrumento **antes** de coletar o aceite.
:::

## Request

ENDPOINT /v1/insurance/order
MÉTODO POST

```json title="Request Body"
{
  "request_control_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
  "products": [
    {
      "product_key": "9d1f8c7a-3b21-4e60-8a2f-1c5d7e9b0a44",
      "commission_data": {
        "commission_type": "percentage_of_gross_premium",
        "value": 0.1000
      },
      "term": {
        "start_date": "2026-07-16",
        "end_date": "2027-07-15"
      },
      "services": [
        {
          "service_key": "0a3c5e7f-2b4d-4a6c-8e0f-1a3b5c7d9e2f",
          "insured_amount_basis": "monetary_amount",
          "insured_amount": 50000.00
        }
      ],
      "risk_object": {
        "type": "credit_operation",
        "insurable_value": 50000.00,
        "attributes": {
          "installment_amount": 1050.00,
          "number_of_installments": 48
        }
      },
      "acceptance": {
        "acceptance_method": "click_wrap",
        "accepted_at": "2026-07-16T13:58:04Z",
        "ip_address": "200.150.10.24",
        "document_number_hash": "f7c3bc1d808e04732adf679965ccc34ca7ae3441ef0d5e6ba2c1d0f0d5f1e2a3",
        "terms": {
          "version": "2026-05-v3",
          "hash": "9b74c9897bac770ffc029102a200c5de"
        },
        "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X)",
        "evidence_reference": "ceremony-8842197"
      }
    }
  ],
  "customer": {
    "document_number": "96969879003",
    "name": "Maria Souza",
    "email": "maria@example.com",
    "phone_number": "+5511999990000",
    "date_of_birth": "1987-03-22",
    "occupation_code": "211205",
    "address": {
      "street": "Avenida Paulista",
      "number": "1000",
      "complement": "Conjunto 42",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "01310100"
    }
  },
  "payment_data": {
    "payment_method": "pix_automatic",
    "installment_count": 12
  }
}
```

### Atributos do request

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `request_control_key` | string (UUID) | opcional | Chave de controle definida por você. Veja [Controle de duplicidade](#controle-de-duplicidade) — **não é uma chave de retentativa**. |
| `products` | array | obrigatório | A seleção de produtos, de 1 a 20 itens, no mesmo formato da [cotação](/documentation/seguros/cotacao/criar_cotacao#atributos-do-request) mais o bloco `acceptance`. |
| `customer` | object | obrigatório | O comprador/segurado do pedido (um por pedido). |
| `payment_data` | object | obrigatório | Forma de pagamento do prêmio. |

#### Objeto em `products[]`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `product_key` | string | obrigatório | Chave do produto no [catálogo](/documentation/seguros/catalogo/inicio). Não pode se repetir no mesmo pedido. |
| `commission_data` | object | opcional | A forma de comissão desejada para o produto. Omitido, aplica-se a taxa padrão (`default_rate`) do produto. Veja abaixo. |
| `term` | object | obrigatório | Vigência do produto, em datas absolutas: `{ "start_date": "AAAA-MM-DD", "end_date": "AAAA-MM-DD" }`. Não há forma por duração nem vigência padrão no nível do pedido. `end_date` deve ser posterior a `start_date`. |
| `services` | array | opcional | Coberturas selecionadas. Omitido, aplica-se a configuração padrão do produto. Mesmo formato da [cotação](/documentation/seguros/cotacao/criar_cotacao#objeto-em-services). |
| `risk_object` | object | obrigatório | Objeto de risco do produto (`type`, `insurable_value`, `attributes`). `insurable_value` é obrigatório para `type` `credit_operation` e `vehicle`. Um produto cujo objeto de risco é a própria pessoa informa `{"type": "person"}` — o bloco nunca é omitido. |
| `acceptance` | object | obrigatório | O aceite do segurado para **este** produto. Veja abaixo. |

#### Objeto `commission_data`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `commission_type` | string | obrigatório | Uma de três formas, mutuamente exclusivas: `percentage_of_gross_premium` (taxa sobre o prêmio bruto), `monetary_amount` (comissão em R$ fixo) ou `total_gross_premium_amount` (preço final desejado ao cliente). |
| `value` | number | obrigatório | O valor da forma escolhida: taxa com 4 casas decimais (ex.: `0.1000`), valor em R$ (ex.: `61.73`) ou preço total (ex.: `650.00`). |

A comissão efetiva é sempre validada contra a faixa (`commission_bounds`) do produto. Um valor fora da faixa **rejeita a linha na precificação**: o pedido nasce `rejected`, com `OUT_OF_BOUNDS_COMMISSION` em `decline_reasons`. Um `commission_type` desconhecido ou `value` mal tipado é `400`.

#### Objeto `acceptance`

O aceite é atestado **por produto**, nunca herdado de um produto vizinho: cada `OrderProduct` vira exatamente uma apólice, e a evidência precisa sobreviver ao lado do contrato que ela justifica. Quando uma única cerimônia cobriu vários produtos, repita o bloco em cada item.

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `acceptance_method` | string | obrigatório | Como o aceite foi coletado: `click_wrap`, `checkbox`, `otp_sms`, `otp_email` ou `voice`. |
| `accepted_at` | string | obrigatório | Data e hora do aceite, em RFC 3339 (ex.: `2026-07-16T13:58:04Z`). Deve estar dentro das últimas **24 horas** e não pode estar no futuro além de 5 minutos de tolerância de relógio — caso contrário, `ORD000027`. |
| `ip_address` | string | obrigatório | Endereço IP (v4 ou v6) de onde o aceite foi dado. |
| `document_number_hash` | string | obrigatório | SHA-256 (hex, 64 caracteres) do `customer.document_number`, sem salt. É recalculado e conferido no servidor: divergência é `ORD000026`. |
| `terms` | object | obrigatório | Identificação das condições aceitas: `{ "version", "hash" }`. |
| `user_agent` | string | opcional | User agent do dispositivo do segurado (até 512 caracteres). |
| `evidence_reference` | string | opcional | Referência da evidência no seu sistema (até 128 caracteres). |

:::caution O hash é um token de integridade, não anonimização
`document_number_hash` é SHA-256 **sem salt** sobre um CPF — o espaço é exaustivamente pesquisável. A escolha é deliberada, para que qualquer detentor do documento possa reverificar o vínculo. Não o trate como dado pseudonimizado.
:::

#### Objeto `customer`

O objeto é plano — não há wrapper `data`. Diferente da cotação, onde tudo é opcional, aqui o comprador é o **segurado de registro** e também o pagador da cobrança — por isso a maioria dos campos passa a ser obrigatória.

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `document_number` | string | obrigatório | CPF (11 dígitos) ou CNPJ (14 dígitos) do segurado, somente dígitos. |
| `name` | string | obrigatório | Nome completo. |
| `email` | string | obrigatório | E-mail do segurado. |
| `phone_number` | string | obrigatório | Telefone, 10 a 15 dígitos, opcionalmente prefixado por `+`. |
| `date_of_birth` | string | obrigatório | Data de nascimento do segurado, no formato `YYYY-MM-DD`. A **idade** lida pelas regras de precificação e elegibilidade é derivada dela no momento da cotação — não envie idade. |
| `occupation_code` | string | opcional | Código de ocupação (CBO). Se o produto precifica ou avalia elegibilidade por ocupação, a ausência do código **rejeita a linha** — o pedido nasce `rejected` com o motivo em `decline_reasons`, não `400`. Consulte o produto no [catálogo](/documentation/seguros/catalogo/inicio) para saber se ele lê esse campo. |
| `address` | object | obrigatório | Endereço do segurado. |

#### Objeto `customer.address`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `street` | string | obrigatório | Logradouro. |
| `number` | string | obrigatório | Número. |
| `complement` | string | opcional | Complemento. |
| `neighborhood` | string | obrigatório | Bairro. |
| `city` | string | obrigatório | Município. |
| `state` | string | obrigatório | Unidade federativa. |
| `postal_code` | string | obrigatório | CEP, 8 dígitos, sem separadores. |

#### Objeto `payment_data`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `payment_method` | string | obrigatório | Meio de pagamento do prêmio. Único valor aceito nesta versão: `pix_automatic` (Pix Automático). |
| `installment_count` | integer | obrigatório | Quantidade de parcelas do prêmio, de `1` a `24`. |

### Controle de duplicidade

`request_control_key` é uma **asserção de unicidade**, não um handle de retentativa. **Qualquer** segundo uso do mesmo par (sua integração, `request_control_key`) responde `409` / `ORD000011` — inclusive com corpo idêntico. Nada compara corpos.

:::danger Obrigação de integração
Um submit que estourar timeout pode ter sido **efetivado**. Repetir a chamada com a mesma `request_control_key` responde `409`, e não devolve o pedido. O caminho de recuperação é `GET /v1/insurance/order?request_control_key={sua_chave}`. Repetir com uma **chave nova** vende a mesma coisa duas vezes.
:::

## Response

STATUS 201

:::info O `POST` responde `201` **sempre**
Uma recusa de negócio é um recurso criado, não uma falha da chamada: o pedido nasce com `status: "rejected"` e os motivos em `decline_reasons`, ainda em `201`. **Ramifique pelo `status`, nunca pela classe HTTP.** O envelope de erro fica reservado para chamadas que não chegaram a uma decisão.
:::

### Pedido criado (`awaiting_payment`)

```json title="Response Body — pedido criado"
{
  "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
  "status": "awaiting_payment",
  "distribution_type": "direct",
  "expires_at": "2026-07-23T13:58:04Z",
  "quote_data": {
    "total_order_amount": 617.28,
    "products": [
      {
        "order_product_key": "7f3a9c2e-0b5d-4e8a-a1c6-9d4b2e7f0a53",
        "product_key": "9d1f8c7a-3b21-4e60-8a2f-1c5d7e9b0a44",
        "product_category": "insurance",
        "insurance_class": {
          "name": "credit_life",
          "class_number": "0977",
          "group_number": "09"
        },
        "regulator_registration": "15414.900388/2015-21",
        "contract_instrument_type": "ticket",
        "gross_premium_amount": 617.28,
        "iof_amount": 2.35,
        "net_premium_amount": 614.93,
        "term": {
          "start_date": "2026-07-16",
          "end_date": "2027-07-15"
        },
        "risk_object": {
          "type": "credit_operation",
          "insurable_value": 50000.00,
          "attributes": {
            "installment_amount": 1050.00,
            "number_of_installments": 48
          }
        },
        "services": [
          {
            "service_key": "0a3c5e7f-2b4d-4a6c-8e0f-1a3b5c7d9e2f",
            "service_type": {
              "code": "credit_life",
              "name": "Prestamista (Credit Life)"
            },
            "service_category": "insurance",
            "regulator_registration": null,
            "gross_premium_amount": 617.28,
            "insured_amount": 50000.00,
            "unit_amount": null,
            "unit_count": null,
            "deductible_data": {
              "deductible_type": "monetary_amount",
              "value": 1500.00
            },
            "waiting_period_days": 30,
            "service_attributes": {},
            "term": {
              "start_date": "2026-07-16",
              "end_date": "2027-07-15"
            }
          }
        ]
      }
    ]
  },
  "payment_data": {
    "payment_method": "pix_automatic",
    "installment_count": 12,
    "installment_amount": 51.44,
    "first_installment_amount": 51.44,
    "first_due_date": "2026-07-23",
    "payment_artifact": {
      "type": "pix_automatic",
      "qr_code_payload": "https://pix.example.qitech.app/r/9f2c1b0e",
      "qr_code_key": "9f2c1b0e-5d47-4a11-9c3e-0b8a7d61f402"
    }
  },
  "customer_document_number": "96969879003"
}
```

| Campo | Tipo | Descrição |
|---|---|---|
| `order_key` | string | Chave única do pedido. |
| `status` | string | `awaiting_payment` no pedido criado. Veja o [ciclo de vida](/documentation/seguros/pedidos/inicio). |
| `distribution_type` | string | Modelo de distribuição da venda. Hoje sempre `direct`. |
| `expires_at` | string | Prazo para o pagamento da primeira parcela: 7 dias a partir da submissão. Vencido o prazo, o pedido expira. |
| `quote_data` | object | O que foi vendido e congelado na submissão: `total_order_amount` e produtos com suas coberturas. É o mesmo bloco, com a mesma forma, retornado na [consulta do pedido](/documentation/seguros/pedidos/consultar_pedido). |
| `quote_data.products[].order_product_key` | string | Chave do produto **dentro do pedido**. É a chave de correlação com a apólice gerada na emissão. |
| `payment_data` | object | A cobrança criada para o pedido. Veja abaixo. |
| `customer_document_number` | string | Documento do segurado. |

#### Objeto `payment_data` (resposta)

| Campo | Tipo | Descrição |
|---|---|---|
| `payment_method` | string | Meio de pagamento congelado — `pix_automatic`. |
| `installment_count` | integer | Quantidade de parcelas. |
| `installment_amount` | number | Valor de cada parcela. |
| `first_installment_amount` | number | Valor da primeira parcela — absorve o resíduo de arredondamento, de modo que `first_installment_amount + (installment_count - 1) × installment_amount` reconcilia exatamente com `total_order_amount`. |
| `first_due_date` | string | Vencimento da primeira parcela (`AAAA-MM-DD`). |
| `payment_artifact` | object | O artefato Pix a ser entregue ao segurado: `type`, `qr_code_payload` (a **URL** do Pix, não o copia-e-cola EMV) e `qr_code_key`. **Retornado apenas enquanto o pedido está `awaiting_payment`** — em um pedido emitido ou terminal o QR está gasto e não é reexposto. |

### Pedido recusado (`rejected`)

Quando a precificação recusa qualquer linha, o pedido nasce `rejected`. A submissão é **tudo-ou-nada**: uma linha recusada recusa o pedido inteiro, nenhuma cobrança é criada e nenhum produto é persistido. Mesmo assim o recurso existe e é consultável pelo `order_key`.

```json title="Response Body — pedido recusado (201)"
{
  "order_key": "b41d90a7-8c22-4f3e-9a10-2d6e4b7c5f81",
  "status": "rejected",
  "decline_reasons": [
    {
      "product_key": "9d1f8c7a-3b21-4e60-8a2f-1c5d7e9b0a44",
      "code": "INELIGIBLE",
      "detail": "age_at_maturity 76 exceeds the maximum 75 for coverage credit_life"
    }
  ]
}
```

| Campo | Tipo | Descrição |
|---|---|---|
| `order_key` | string | Chave do pedido recusado. |
| `status` | string | Sempre `rejected` neste ramo. |
| `decline_reasons` | array | Lista plana de `{ product_key, code, detail }`, uma entrada por falha subjacente — duas coberturas de um mesmo produto violando o espaço de opções geram duas entradas sob o mesmo `code`. Os códigos são os [mesmos da cotação](/documentation/seguros/cotacao/criar_cotacao#motivos-de-rejeicao). `product_key` pode ser `null` para um motivo não atribuível a um produto específico. |

Um pedido `rejected` **não** traz `quote_data` nem `payment_data`: nada foi vendido e não há o que pagar.

## Possíveis erros

Todo erro (`non-2xx`) retorna o corpo padrão `{ "title", "description", "translation", "code" }` — trate programaticamente **apenas** o campo `code`. Recusa de negócio **não** vem por aqui: ela é o `201` com `status: rejected` descrito acima.

| Status | Código | Descrição |
|---|---|---|
| `400` | `QIT000001` | Requisição malformada (schema inválido) — inclusive `customer.date_of_birth` fora do calendário ou no futuro. |
| `401` / `403` | — | Falha de autenticação ou autorização. |
| `409` | `ORD000011` | `request_control_key` já utilizada pela sua integração. Recupere o pedido com `GET /v1/insurance/order?request_control_key=`. |
| `422` | `ORD000020` | Objeto de risco ausente, ou sem `insurable_value` quando o tipo o exige (`credit_operation`/`vehicle`). |
| `422` | `ORD000021` | Produto sem `term`. |
| `422` | `ORD000022` | `term.end_date` anterior ou igual a `term.start_date`. |
| `422` | `ORD000023` | `product_key` repetido no mesmo pedido. |
| `422` | `ORD000024` | Integração inativa — não pode transacionar. |
| `422` | `ORD000025` | Produto sem o bloco `acceptance`. |
| `422` | `ORD000026` | `acceptance.document_number_hash` não corresponde ao `customer.document_number` do pedido. |
| `422` | `ORD000027` | `acceptance.accepted_at` inválido, no futuro ou fora da janela de 24 horas. |
| `422` | `ORD000028` | A sua integração não tem configuração de pagamento e não pode ser cobrada. Contate o time de Integração. |
| `422` | `ORD000029` | O meio de pagamento solicitado não está habilitado para a sua integração. |
| `422` | `ORD000032` | O pedido mistura instrumentos contratuais diferentes — bilhete e apólice não podem ser vendidos no mesmo pedido. |
| `422` | `ORD000033` | O instrumento contratual do produto não está disponível para venda (apenas `ticket` nesta versão). |
| `502` / `504` | `ORD000031` | Falha em uma integração síncrona da submissão (cobrança). Nenhum pedido foi criado. |
| `503` | `ORD000030` | Motor de precificação indisponível — as vendas ficam pausadas. Repita a chamada. |

:::caution Retentativa após `502` / `504` / `503`
Repetir o submit exige **a mesma** `request_control_key` — ou nenhuma. Uma chave nova cria um segundo pedido para a mesma venda.
:::

---

# Início

URL: /documentation/seguros/pedidos/inicio

O **pedido** (`order`) é a unidade de venda do Insurance-as-a-Service: uma submissão que carrega um ou mais produtos, o segurado, o **aceite** que você coletou dele e a forma de pagamento. O pedido nasce aguardando o **pagamento** da primeira parcela. Confirmado o pagamento, o pedido é **emitido** — e cada produto vendido vira uma [apólice](/documentation/seguros/apolices/inicio).

:::info O aceite viaja no próprio pedido
Não há etapa de assinatura hospedada pela QI Tech nesta versão. Você conduz a cerimônia de aceite no seu fluxo e atesta o resultado no bloco `acceptance` de cada produto da submissão. Por isso o pedido nasce já em `awaiting_payment`, e não em um estado de espera por assinatura.
:::

## Ciclo de vida do pedido

![Fluxo de status do pedido, da submissão à emissão, com os desfechos possíveis](/img/diagrams/seguros-pedidos-inicio.svg)

_Como ler o diagrama: **azul** = status intermediário · **verde** = emitido (desfecho de sucesso) · **vermelho** = desfecho sem emissão. Toda transição de status gera um [webhook](/documentation/seguros/pedidos/webhooks)._

| Status | Significado |
|---|---|
| `awaiting_payment` | Pedido criado e precificado; aguardando a confirmação do pagamento da primeira parcela via o `payment_artifact` Pix retornado na submissão. |
| `emitted` | Pagamento confirmado; as apólices do pedido foram disparadas para emissão. Status terminal do pedido — daqui em diante o acompanhamento é pelas [apólices](/documentation/seguros/apolices/inicio). |
| `rejected` | O pedido nasceu rejeitado na submissão porque a precificação recusou ao menos uma linha. Os motivos vêm em `decline_reasons`, no próprio `201`. |
| `expired` | O prazo de 7 dias para pagamento (`expires_at`) venceu sem confirmação. |
| `cancelled` | O pedido foi cancelado pela sua integração antes da emissão. |

### Status reservados

Os enumeradores abaixo existem no modelo de dados mas **não ocorrem nesta versão**. Eles são a razão pela qual você não deve mapear o campo `status` de forma fechada — trate um valor desconhecido como "em andamento" e consulte o pedido.

| Status | Reservado para |
|---|---|
| `awaiting_acceptance` | O fluxo de **apólice** (`contract_instrument_type: policy`), que exige proposta renderizada e assinatura sobre ela. |
| `under_analysis` | Análise cadastral assíncrona (KYC). |
| `declined` | Recusa do segurado em uma cerimônia de assinatura conduzida pela QI Tech. |

:::info O pagamento sempre vence o relógio
A expiração nunca desfaz um pagamento válido: se o pagamento for confirmado enquanto a expiração está sendo processada, o pedido é emitido normalmente. Um pagamento que chegue **depois** de um cancelamento é devolvido ao pagador automaticamente.
:::

## O que congela na submissão

No momento da submissão, o pedido congela tudo o que foi precificado: produtos, coberturas, prêmios, importâncias seguradas, vigências, objetos de risco e o aceite atestado. Esses dados são imutáveis e são exatamente o que as apólices herdarão na emissão — uma reprecificação posterior do catálogo nunca afeta um pedido já submetido.

## Pedido × apólice

- Um pedido vende **N produtos**; a emissão gera **uma apólice por produto**, correlacionada pelo `order_product_key`.
- O pedido **não** retorna apólices nas consultas: descubra as apólices de um pedido emitido com [`GET /v1/insurance/policies?order_key=`](/documentation/seguros/apolices/listar_apolices).
- Cancelar um pedido **antes** da emissão desfaz a venda inteira; cancelar **depois** da emissão dispara o cancelamento de cada apólice individualmente ([Cancelar pedido](/documentation/seguros/pedidos/cancelar_pedido)).

## Endpoints

| Endpoint | Descrição |
|---|---|
| [`POST /v1/insurance/order`](/documentation/seguros/pedidos/criar_pedido) | Cria e submete o pedido. |
| [`GET /v1/insurance/order`](/documentation/seguros/pedidos/listar_pedidos) | Lista os pedidos da sua integração. |
| [`GET /v1/insurance/orders/{order_key}`](/documentation/seguros/pedidos/consultar_pedido) | Detalha um pedido. |
| [`POST /v1/insurance/orders/{order_key}/cancel`](/documentation/seguros/pedidos/cancelar_pedido) | Cancela um pedido (pré ou pós-emissão). |

:::caution Rota de coleção no singular
A rota de coleção é `/v1/insurance/order` (singular) e carrega tanto a criação (`POST`) quanto a listagem (`GET`). As rotas endereçadas por chave usam o plural: `/v1/insurance/orders/{order_key}`.
:::

---

# Listar pedidos

URL: /documentation/seguros/pedidos/listar_pedidos

Retorna a lista paginada dos pedidos da sua integração, do mais recente para o mais antigo.

## Request

ENDPOINT /v1/insurance/order
MÉTODO GET

### Query params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `page` | integer | opcional | Número da página. Padrão: `1`. |
| `page_size` | integer | opcional | Registros por página. Padrão: `50`. Máximo: `200`. |
| `status` | string | opcional | Filtra pelo status do pedido (ex.: `awaiting_payment`). |
| `customer_document_number` | string | opcional | Filtra pelo documento do segurado. |
| `request_control_key` | string | opcional | Filtra pela sua chave de idempotência. |
| `distribution_type` | string | opcional | Filtra pelo modelo de distribuição (ex.: `direct`). |
| `created_from` | string | opcional | Data/hora mínima de criação (ISO 8601). |
| `created_to` | string | opcional | Data/hora máxima de criação (ISO 8601). |

```python title="Exemplo de chamada"
GET /v1/insurance/order?page=1&page_size=50&status=awaiting_payment&created_from=2026-07-01T00:00:00Z
```

## Response

STATUS 200

```json title="Response Body"
{
  "items": [
    {
      "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
      "status": "awaiting_payment",
      "product_keys": ["9d1f8c7a-3b21-4e60-8a2f-1c5d7e9b0a44"],
      "customer_document_number": "96969879003",
      "total_order_amount": 617.28,
      "created_at": "2026-07-14T12:00:00Z"
    }
  ],
  "page": 1,
  "page_size": 50,
  "total": 137
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `items` | array | Lista de resumos de pedido. |
| `page` | integer | Página atual. |
| `page_size` | integer | Tamanho da página solicitado. |
| `total` | integer | Total de pedidos que atendem aos filtros. |

#### Objeto em `items`

| Campo | Tipo | Descrição |
|---|---|---|
| `order_key` | string | Chave única do pedido. |
| `status` | string | Status atual. Veja o [ciclo de vida](/documentation/seguros/pedidos/inicio). |
| `product_keys` | array | Chaves dos produtos vendidos no pedido. |
| `customer_document_number` | string | Documento do segurado. |
| `total_order_amount` | number | Valor total do pedido (soma dos prêmios brutos dos produtos). |
| `created_at` | string | Data/hora da submissão. |

## Possíveis erros

Todo erro (`non-2xx`) retorna o corpo padrão `{ "title", "description", "translation", "code" }` — trate programaticamente **apenas** o campo `code`.

| Status | Código | Descrição |
|---|---|---|
| `400` | `QIT000010` | Parâmetro de paginação inválido. |
| `400` | `QIT000001` | Parâmetro de filtro malformado. |
| `401` / `403` | — | Falha de autenticação ou autorização. |
| `429` | — | Limite de requisições excedido — repita com backoff. |
| `500` / `503` | `QIT000500` | Erro interno ou serviço indisponível — seguro repetir a chamada. |

---

# Webhooks do Pedido

URL: /documentation/seguros/pedidos/webhooks

A cada transição de status do pedido, a QI Tech envia um webhook do tipo `insurance.order.status_changed` para a URL de callback configurada. O evento identifica o pedido pelo `order_key` e carrega o novo status.

:::info Webhooks são notificações, não a fonte da verdade
A entrega dos webhooks é do tipo *best-effort*. Não dependa exclusivamente deles: um evento perdido é sempre recuperável consultando o pedido em [`GET /v1/insurance/order`](/documentation/seguros/pedidos/listar_pedidos).
:::

:::info Configuração de webhooks
Para receber webhooks é necessário ter uma URL de callback configurada. Veja [Autenticação — Recebimento de webhooks](/documentation/seguros/introducao/autenticacao#recebimento-de-webhooks).
:::

## Estrutura do webhook

| Campo | Tipo | Descrição |
|---|---|---|
| `webhook_type` | string | Sempre `insurance.order.status_changed`. |
| `webhook_datetime` | string | Data e hora do evento no formato ISO 8601. |
| `data` | object | Dados do evento. Veja tabela abaixo. |

#### Atributos de `data`

| Campo | Tipo | Descrição |
|---|---|---|
| `order_key` | string | Chave do pedido. |
| `status` | string | Novo status do pedido. |
| `customer_document_number` | string | Documento do segurado. |
| `reason` | array / string | Motivo, quando aplicável: a lista de `decline_reasons` em `rejected`, o motivo informado em `cancelled`. `null` nos demais casos — a chave está sempre presente. |
| `product_count` | integer | Quantidade de produtos do pedido. No evento de `emitted`, é o número de apólices que serão emitidas. |

```json title="Estrutura padrão do webhook"
{
  "webhook_type": "insurance.order.status_changed",
  "webhook_datetime": "2026-07-16T14:03:22Z",
  "data": {
    "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
    "status": "status",
    "customer_document_number": "96969879003",
    "reason": null
  }
}
```

## Eventos por status

### Pedido criado

STATUS awaiting_payment

Enviado quando a submissão é concluída com sucesso. O pedido aguarda o pagamento da primeira parcela pelo `payment_artifact` Pix retornado na [criação do pedido](/documentation/seguros/pedidos/criar_pedido).

---

### Pedido recusado

STATUS rejected

Enviado quando o pedido nasce recusado na submissão porque a precificação recusou ao menos uma linha. O campo `reason` traz a lista de `decline_reasons`.

---

### Pedido emitido

STATUS emitted

Enviado quando o pagamento é confirmado e a emissão das apólices é disparada. O campo `product_count` indica quantas apólices serão criadas — **o evento não carrega as chaves das apólices**, porque elas são emitidas de forma assíncrona logo em seguida. Descubra-as com [`GET /v1/insurance/policies?order_key=`](/documentation/seguros/apolices/listar_apolices) ou aguarde os [webhooks de apólice](/documentation/seguros/apolices/webhooks).

```json title="Webhook Body"
{
  "webhook_type": "insurance.order.status_changed",
  "webhook_datetime": "2026-07-16T14:03:22Z",
  "data": {
    "order_key": "5e2b3f60-7c4b-4c8e-9f1a-6d2e8b4a7c90",
    "status": "emitted",
    "customer_document_number": "96969879003",
    "reason": null,
    "product_count": 2
  }
}
```

---

### Pedido expirado

STATUS expired

Enviado quando o prazo de pagamento (`expires_at`) vence sem confirmação. A expiração nunca desfaz um pagamento válido: se o pagamento for confirmado antes do processamento da expiração, o pedido é emitido normalmente e este evento não ocorre.

---

### Pedido cancelado

STATUS cancelled

Enviado quando o [cancelamento pré-emissão](/documentation/seguros/pedidos/cancelar_pedido) é concluído. O campo `reason` traz o motivo informado no cancelamento, quando houver. O cancelamento **pós-emissão** não gera este evento — o pedido permanece `emitted` e o acompanhamento é pelos [webhooks de apólice](/documentation/seguros/apolices/webhooks).

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeados de forma estrita.
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

---

# Configurando Webhooks

URL: /documentation/seguros/primeiros_passos/seguros_configurando_webhooks

:::info Veja também
- [Validação de Webhooks](/documentation/seguros/primeiros_passos/teste_de_autenticacao/seguros_webhook_v2)
- [Configurar IP de Integração](/documentation/seguros/primeiros_passos/seguros_configurar_ip_de_integracao)
:::

Os eventos de pedido e de apólice são notificados por `POST` na URL de callback configurada para a sua integração.

## Como configurar

No Insurance-as-a-Service a URL de recebimento das notificações **não está disponível pelo portal QI Tech**. Ela é configurada pelo time de Integração da QI Tech.

Envie para [api@qitech.com.br](mailto:api@qitech.com.br):

- A **URL de callback**, por ambiente (sandbox e produção). A URL deve ser HTTPS e aceitar `POST`.
- Os **headers** que você precisa que a QI Tech envie nas notificações, se houver — por exemplo um header de autenticação do seu lado.

Avise-nos com antecedência quando a URL mudar: enquanto a alteração não for registrada, as notificações continuam sendo enviadas para o endereço anterior.

## Formato das notificações

Os webhooks da QI Tech seguem uma estrutura padrão:

```json
{
  "webhook_type": "<tipo_do_evento>",
  "webhook_datetime": "2026-07-16T14:03:22Z",
  "data": {}
}
```

| Campo              | Tipo   | Descrição                                   |
| ------------------ | ------ | ------------------------------------------- |
| `webhook_type`     | string | Identificador do tipo de evento.            |
| `webhook_datetime` | string | Data e hora do evento no formato ISO 8601.  |
| `data`             | object | Dados específicos do evento.                |

Os eventos desta linha de produto estão descritos em [Webhooks de Pedido](/documentation/seguros/pedidos/webhooks) e [Webhooks de Apólice](/documentation/seguros/apolices/webhooks).

As notificações são enviadas com headers assinados. Valide a assinatura antes de processar o conteúdo — veja [Validação de Webhooks](/documentation/seguros/primeiros_passos/teste_de_autenticacao/seguros_webhook_v2).

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeados de forma restrita.
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Informação
O timeout para resposta dos nossos webhooks é de 10 segundos.
:::

---

# Configurar IP de Integração

URL: /documentation/seguros/primeiros_passos/seguros_configurar_ip_de_integracao

:::info Veja também
- [Configurando Webhooks](/documentation/seguros/primeiros_passos/seguros_configurando_webhooks)
- [Troca de Chaves](/documentation/seguros/primeiros_passos/seguros_troca_de_chaves)
:::

As chamadas à API do Insurance-as-a-Service são restritas a uma lista de **endereços IP públicos** previamente autorizados para a sua integração. Uma requisição originada de um IP fora da lista é recusada, por mais correta que seja a sua assinatura.

## Como configurar

No Insurance-as-a-Service o cadastro dos IPs **não está disponível pelo portal QI Tech**. A lista é registrada pelo time de Integração da QI Tech.

Envie a relação dos endereços IP públicos de onde a sua integração fará as chamadas para [api@qitech.com.br](mailto:api@qitech.com.br), informando o ambiente (sandbox ou produção) de cada endereço.

O que é aceito em cada entrada:

- Um endereço IPv4 público, individual (ex.: `189.10.20.30`)
- Um endereço IPv6 público, individual

Cada endereço é comparado exatamente como foi cadastrado, portanto informe **um endereço por entrada** — inclusive quando eles forem vizinhos na mesma faixa.

:::caution Envie a lista completa desde o início
Informe todos os endereços de uma vez no onboarding da sua integração. Incluir um endereço depois exige uma nova solicitação ao time de Integração, e até que ela seja processada as chamadas partindo dele são recusadas.

Avise-nos **antes** de passar a chamar a API a partir de uma rede nova — um novo escritório, uma VPN, um NAT gateway adicional ou um _runner_ de CI. O cadastro passa a valer imediatamente após ser registrado, mas só depois de ser registrado.
:::

## Possíveis erros

Todo erro (`non-2xx`) retorna o corpo padrão de erro — trate programaticamente **apenas** o campo `code`.

| Status | Código | Descrição |
|---|---|---|
| `403` | `EGW000007` | O IP de origem da requisição não está na lista de IPs permitidos da integração. |

```json
{
  "title": "Forbidden",
  "description": "The request source IP is not in the integration's allowed IP list.",
  "translation": "O IP de origem da requisição não está na lista de IPs permitidos da integração.",
  "code": "EGW000007",
  "extra_fields": {}
}
```

Se você receber esse erro, confirme qual endereço a sua infraestrutura está de fato usando para sair (o IP público de saída pode não ser o do servidor, no caso de NAT, proxy ou balanceador) e compare com a lista que você nos enviou.

---

# Troca de chaves

URL: /documentation/seguros/primeiros_passos/seguros_troca_de_chaves

## Conferindo o formato da chave pública

A chave pública que esperamos receber é o arquivo gerado pelo **segundo** comando da seção anterior (`openssl ec ... -pubout`) — `jwtECDSASHA512.key.pub` no Unix e no Windows, `ec512-public.pem` no Mac OS. Ele está no formato **PEM**, em várias linhas, delimitado por `-----BEGIN PUBLIC KEY-----` e `-----END PUBLIC KEY-----`, como no exemplo abaixo — que serve apenas para conferir o formato e nunca deve ser cadastrado como a sua chave:

```
-----BEGIN PUBLIC KEY-----
MIGbMBAGByqGSM49AgEGBSuBBAAjA4GGAAQAD8a66B1olkMDoeQM9imiOOCuq1Hq
LOq0bu6ry2GJJzDtjGws5u52SQikFFv0YSRSGpgAJN7cZiuXQkGooDxDvXsAev+2
iQn7HImrLN8YaNPqGMU28UFiuc2SSPf5QdHozEf6LRqq1bhg2oJirpLJAgKlse9M
hhsYr9sznWJDoLOJgjM=
-----END PUBLIC KEY-----
```

Confira o arquivo antes de nos enviar:

```bash
openssl ec -pubin -in jwtECDSASHA512.key.pub -text -noout
```

A resposta esperada termina em `ASN1 OID: secp521r1` e `NIST CURVE: P-521`. Se o comando responder um erro de leitura, o arquivo não é uma chave pública em PEM.

### Se a sua chave está no formato OpenSSH

O `ssh-keygen` do primeiro comando também grava um arquivo `.pub` ao lado da chave privada, mas ele está no formato **OpenSSH**: uma única linha começando pelo tipo da chave e terminando no comentário.

```
ecdsa-sha2-nistp521 AAAAE2VjZHNhLXNoYTItbmlzdHA1MjEAAAAI... usuario@maquina
```

Esse arquivo corresponde ao mesmo par de chaves, mas **não é o formato aceito no cadastro da sua integração**. Você não precisa gerar um novo par: basta executar o comando `openssl ec ... -pubout` sobre a sua chave privada para obter a mesma chave pública em PEM.

## Envio da chave pública

Como parte da assinatura das requisições e das respostas, é necessário que você forneça a sua chave pública a nós e que retornemos uma chave pública para você — assim a leitura das mensagens pode ser feita nas duas pontas da comunicação. Além disso, fornecemos uma chave única do tipo UUID (`API-CLIENT-KEY`) que representa a sua integração via API dentro do nosso sistema.

No Insurance-as-a-Service o cadastro da chave pública ainda não está disponível pelo portal QI Tech. Envie a sua **chave pública em PEM** — o arquivo conferido na seção anterior — ao time de Integração da QI Tech por um **meio seguro** — entre em contato com [api@qitech.com.br](mailto:api@qitech.com.br) para alinhar o canal de envio. Em retorno, você receberá a sua **chave de integração** (`API-CLIENT-KEY`) e a **chave pública da QI Tech**.

:::danger Atenção!

Nunca compartilhe sua chave privada, ela é de uso exclusivo seu e o compartilhamento da mesma no lugar da chave pública compromete a segurança de suas requests. Além disso, não compartilhe sua chave pública QI Tech e chave de integração pois eles são seu meio de comunicação com nossas APIs.

:::

---

# Possíveis erros

URL: /documentation/seguros/primeiros_passos/teste_de_autenticacao/seguros_possiveis_erros

:::info Veja também
- [Teste de autenticação](./seguros_teste_de_autenticacao_v2)
- [Exemplo completo de autenticação](./seguros_teste_de_autenticacao_completo)
:::

## Erro no token

Caso a assinatura da string_to_sign esteja incorreta, um erro será apresentado relativo ao encoded_header_token :

STATUS 401

Response Body

```json
{
	"title": "QI Unauthenticated",
	"description": "Please provide valid credentials as part of the request. (Documentation: https://qitech.com.br/documentation) Details: Failed while decoding the authentication token",
	"translation": "Por favor forneça credenciais válidas como parte da request. (Documentação: https://qitech.com.br/documentation) Detalhes: Falha ao decodificar o token de autenticação",
	"code": "GDF000014"
}
```

## Erro no <strong>API_KEY</strong>

Caso a API_KEY não seja enviada no header o seguinte erro será apresentado:

STATUS 400

Response Body

```json
{
	"title": "Bad Request",
	"description": "No API Client Key received",
	"translation": "Nenhuma chave de API do cliente recebida",
	"code": "GDF000003"
}
```

## <strong>API_KEY</strong> incorreta

Caso a API_KEY enviada não corresponda a API_KEY apresentada no front QI Tech após o cadastro de chaves o seguinte retorno será apresentado:

STATUS 404

Response Body

```json
  {
  	"code": "GDF000018",
  	"title": "Not Found",
  	"description": "No ClientIntegration found for api_client_key: {api_client_key}.",
  	"translation": "Nenhuma ClientIntegration encontrada para api_client_key: {api_client_key}."
  }
```

## Endpoint não autorizado

Caso o endpoint ou método acessado não esteja autorizado o seguinte erro será retornado:

STATUS 401

Response Body

```json
{
	"title": "QI Unauthenticated",
	"description": "Please provide valid credentials as part of the request. (Documentation: https://qitech.com.br/documentation) Details: Endpoint or HTTP method not allowed for the given ClientIntegration (Action: POST /debt)",
	"translation": "Por favor forneça credenciais válidas como parte da request. (Documentação: https://qitech.com.br/documentation) Detalhes: Endpoint ou método HTTP não permitido para a ClientIntegration fornecida (Action: POST /debt)",
	"code": "GDF000014"
}
```

:::caution Atenção!

Para requisitar acesso ao endpoint que retornou o erro referido, é necessário solicitar a liberação ao time de suporte QI Tech.
:::

---

# Exemplo completo de teste de autenticação

URL: /documentation/seguros/primeiros_passos/teste_de_autenticacao/seguros_teste_de_autenticacao_completo

:::info Veja também
- [Teste de autenticação passo a passo](./seguros_teste_de_autenticacao_v2)
- [Possíveis erros](./seguros_possiveis_erros)
:::

### Visão Geral
Esta documentação detalha o processo de assinatura e encriptação de cabeçalhos para autenticação segura em requisições à nossa API. O processo garante que as requisições sejam confiáveis e seguras, prevenindo acessos não autorizados e garantindo a integridade dos dados.

:::caution Atenção!

Requisições dos métodos `GET` e `DELETE` não possuem corpo. O hash md5 dessas requisições deve ser gerado sobre a **string vazia** (`""`), e o valor é sempre a constante abaixo:

```
d41d8cd98f00b204e9800998ecf8427e
```

Esse valor é **diferente** do utilizado no Lending-as-a-Service, que assina `GET` e `DELETE` com o md5 do objeto JSON vazio (`"{}"`), `99914b932bd37a50b983c5e7c90ae93b`. Se você já integra o Lending-as-a-Service, não reaproveite a constante: assinar um `GET` do Insurance-as-a-Service com ela retorna `401` com o código `EGW000006`.
:::

### Os dois erros `401` do header `AUTHORIZATION`

Uma falha no header `AUTHORIZATION` retorna `401` com um de dois códigos, e eles apontam para causas diferentes:

| Status | Código | Descrição |
|---|---|---|
| `401` | `EGW000004` | A assinatura da requisição não pôde ser verificada com a chave pública registrada da integração. |
| `401` | `EGW000006` | O digest do payload assinado não corresponde ao corpo da requisição. |

- `EGW000004` significa que o problema está no **par de chaves**: a assinatura não foi verificada com a chave pública registrada para a sua integração. Confira a [troca de chaves](/documentation/seguros/primeiros_passos/seguros_troca_de_chaves), inclusive o formato do arquivo enviado.
- `EGW000006` significa que a assinatura **foi verificada com sucesso** — a sua chave está correta — e que apenas o `md5` não corresponde ao corpo enviado. Não investigue o par de chaves: confira o hash, começando pela constante de `GET` e `DELETE` acima.

**Python**

```python
#Aqui, importamos as bibliotecas necessárias ao longo do processo de autenticação.
from jose import jwt
import json
from datetime import datetime, timezone
from hashlib import md5
import requests

def get_auth_header(endpoint, method, CLIENT_PRIVATE_KEY, API_KEY, request_body=None):

    if request_body is None:
        request_body = {}

    #O objeto de data e hora informado deve estar em UTC e deve seguir o padrão da norma internacional ISO 8601 ("2023-06-26T19:48:32.759844Z")
    timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")

    #Definimos o algoritmo de codificação JWT
    jwt_header = {
        "typ": "JWT",
        "alg": "ES512"
    }

    #Construir hash em MD5 para assinatura no cabeçalho (header) utilizando o payload
    json_body = json.dumps(request_body)
    md5_hash = md5(json_body.encode()).hexdigest()

    #Essas são as infromações necessárias para assinatura do cabeçalho
    jwt_body = {
        "payload_md5": md5_hash,
        "timestamp": timestamp,
        "method": method,
        "uri": endpoint
    }

    #Realizar criptografia do header
    encoded_header_token = jwt.encode(
        claims=jwt_body,
        key=CLIENT_PRIVATE_KEY,
        algorithm="ES512",
        headers=jwt_header
    )

    #Montar header assinado
    signed_header = {
        "AUTHORIZATION": encoded_header_token,
        "API-CLIENT-KEY": API_KEY
    }

    return signed_header

if __name__ == "__main__":

    #Utilizaremos as variáveis base_url, endpoint, method e request_body. Neste exemplo faremos um POST no endpoint "/test".
    #As chaves contidas neste exemplo são apenas para fins de demonstração. Por favor, utilize suas próprias chaves.
    CLIENT_PRIVATE_KEY = "SUA PRIVATE KEY AQUI"
    API_KEY = "SUA API KEY AQUI"

    BASE_URL = "https://api.sandbox.insurance.qitech.app"
    METHOD = "POST" #GET ou POST
    REQUEST_BODY = {
        "name": "QI Tech"
    }

    #Para fazer um GET na /test, é necessário inserir a API key ao final, enquanto para fazer um POST no mesmo endpoint, não é necessário
    if METHOD == 'GET':
        ENDPOINT = f"/test/{API_KEY}"
        signed_header = get_auth_header(ENDPOINT, METHOD, CLIENT_PRIVATE_KEY, API_KEY)
        response = requests.get(f"{BASE_URL}{ENDPOINT}", headers=signed_header)
    else:
        ENDPOINT = f"/test"
        signed_header = get_auth_header(ENDPOINT, METHOD, CLIENT_PRIVATE_KEY, API_KEY, REQUEST_BODY)
        response = requests.post(f"{BASE_URL}{ENDPOINT}", json=REQUEST_BODY, headers=signed_header)

    print(response.status_code)
    print(response.json())
```

**PHP**

```php
<?php
require __DIR__ . '/vendor/autoload.php';

//Aqui, importamos as bibliotecas necessárias ao longo do processo de autenticação.
use Jose\Component\Core\AlgorithmManager;
use Jose\Component\Signature\JWSTokenSupport;
use Jose\Component\Signature\Algorithm\ES512;
use Jose\Component\Signature\Serializer\CompactSerializer;
use Jose\Component\KeyManagement\JWKFactory;
use Jose\Component\Signature\JWSBuilder;

function get_auth_header($endpoint, $method, $privateKeyString, $api_key, $request_body = null) {

    if ($request_body === null) {
        $request_body = (object)[];
    }

    //O objeto de data e hora informado deve estar em UTC e deve seguir o padrão da norma internacional ISO 8601 ("2023-06-26T19:48:32.759844Z")
    $microtime_float = microtime(true);
    $datetime = new DateTimeImmutable('@' . floor($microtime_float), new DateTimeZone('UTC'));
    $timestamp = $datetime->format('Y-m-d\TH:i:s.') . sprintf('%06d', ($microtime_float - floor($microtime_float)) * 1000000) . 'Z';

    //Definimos o algoritmo de codificação JWT
    $header = [
        "typ" => "JWT",
        "alg" => "ES512"
    ];

    //Construir hash em MD5 para assinatura no cabeçalho (header) utilizando o payload
    $request_body_json = json_encode($request_body);
    $md5_hash = md5($request_body_json);

    //Essas são as infromações necessárias para assinatura do cabeçalho
    $payload = [
        "payload_md5" => $md5_hash,
        "timestamp" => $timestamp,
        "method" => $method,
        "uri" => $endpoint
    ];

    // Inicializar Algorithm Manager com ES512
    $algorithmManager = new AlgorithmManager([
        new ES512(),
    ]);

    // Inicializar JWS Builder
    $jwsBuilder = new JWSBuilder(
        $algorithmManager,
        new JWSTokenSupport()
    );

    $privateKey = JWKFactory::createFromKey($privateKeyString);

    //Realizar criptografia do header
    $jws = $jwsBuilder
        ->create()
        ->withPayload(json_encode($payload))
        ->addSignature($privateKey, $header)
        ->build();

    $serializer = new CompactSerializer();
    $jwt = $serializer->serialize($jws, 0);

    //Montar header assinado
    $headers = [
        'Authorization' => $jwt,
        'API-CLIENT-KEY' => $api_key,
    ];

    return $headers;
}

if (php_sapi_name() == 'cli' || (isset($_SERVER['REQUEST_METHOD']) && realpath($_SERVER['SCRIPT_FILENAME']) === __FILE__)) {
    
    //Utilizaremos as variáveis base_url, endpoint, method e request_body. Neste exemplo faremos um POST no endpoint "/test".
    $base_url = "https://api.sandbox.insurance.qitech.app";
    $method = "POST"; // HTTP method: "GET" or "POST"

    $request_body = ["name" => "QI Tech"];

    //As chaves contidas neste exemplo são apenas para fins de demonstração. Por favor, utilize suas próprias chaves.
    $api_key = "SUA API KEY AQUI";
    $privateKeyString = "SUA PRIVATE KEY AQUI";

    $response = null;

    #Para fazer um GET na /test, é necessário inserir a API key ao final, enquanto para fazer um POST no mesmo endpoint, não é necessário
    if ($method == 'GET') {
        $endpoint = "/test/" . $api_key;
        $headers = get_auth_header($endpoint, $method, $privateKeyString, $api_key);
        $url = $base_url . $endpoint;
        $response = \WpOrg\Requests\Requests::get($url, $headers);
    } else {
        $endpoint = "/test";
        $headers = get_auth_header($endpoint, $method, $privateKeyString, $api_key, $request_body);
        $url = $base_url . $endpoint;
        $response = \WpOrg\Requests\Requests::post($url, $headers, json_encode($request_body));
    }

    if ($response) {
        echo "HTTP Status Code: " . $response->status_code . "\n";

        $json_response = json_decode($response->body, true);
        if (json_last_error() === JSON_ERROR_NONE) {
            echo "Response JSON:\n";
            print_r($json_response);
        } else {
            echo "Error decoding JSON. Raw Response Text:\n";
            echo $response->body . "\n";

    }
}
?>
```

**Node.js**

```js
//Aqui, importamos as bibliotecas necessárias ao longo do processo de autenticação.
const jwt = require('jsonwebtoken');
const crypto = require('crypto');
const axios = require('axios');

function getAuthHeader(endpoint, method, client_private_key, api_key, request_body = null) {
    if (request_body === null) {
        request_body = {};
    }

    //O objeto de data e hora informado deve estar em UTC e deve seguir o padrão da norma internacional ISO 8601 ("2023-06-26T19:48:32.759844Z")
    const now = new Date();
    const isoString = now.toISOString();
    const timestamp = isoString.slice(0, -1) + (now.getMilliseconds() * 1000).toString().padStart(6, '0').slice(0, 3) + 'Z';

    //Definimos o algoritmo de codificação JWT
    const jwt_header = {
        typ: 'JWT',
        alg: 'ES512'
    };

    //Construir hash em MD5 para assinatura no cabeçalho (header) utilizando o payload
    const str_body = JSON.stringify(request_body);
    const md5_hash = crypto.createHash('md5').update(str_body).digest('hex');

    //Essas são as infromações necessárias para assinatura do cabeçalho
    const jwt_body = {
        payload_md5: md5_hash,
        timestamp: timestamp,
        method: method,
        uri: endpoint
    };

    // Inicializar JWS Builder
    const encoded_header_token = jwt.sign(
        jwt_body,
        client_private_key,
        {
            algorithm: 'ES512',
            header: jwt_header
        }
    );

    //Realizar criptografia do header
    const signed_header = {
        'AUTHORIZATION': encoded_header_token,
        'API-CLIENT-KEY': api_key
    };

    return signed_header;
}
//Utilizaremos as variáveis BASE_URL, ENDPOINT, METHOD e REQUEST_BODY. Neste exemplo faremos um POST no endpoint "/test".
async function main() {
    const BASE_URL = "https://api.sandbox.insurance.qitech.app";
    const METHOD = "POST"; //"POST" ou "GET"

    const REQUEST_BODY = {
        name: "QI Tech"
    };

    const API_KEY = "SUA API KEY AQUI";
    const CLIENT_PRIVATE_KEY = "SUA PRIVATE KEY AQUI";

    let ENDPOINT;
    let url;
    let signed_header;

    try {
    //Para fazer um GET na /test, é necessário inserir a API key ao final, enquanto para fazer um POST no mesmo endpoint, não é necessário
        if (METHOD === 'GET') {
            ENDPOINT = `/test/${API_KEY}`;
            url = `${BASE_URL}${ENDPOINT}`;
            signed_header = getAuthHeader(ENDPOINT, METHOD, CLIENT_PRIVATE_KEY, API_KEY);

            const response = await axios.get(url, { headers: signed_header });
            console.log("Status Code:", response.status);
            console.log("Response Body:", response.data);

        } else {
            ENDPOINT = "/test";
            url = `${BASE_URL}${ENDPOINT}`; // Corrected string interpolation
            signed_header = getAuthHeader(ENDPOINT, METHOD, CLIENT_PRIVATE_KEY, API_KEY, REQUEST_BODY);

            const response = await axios.post(url, REQUEST_BODY, { headers: signed_header });
            console.log("Status Code:", response.status);
            console.log("Response Body:", response.data);
        }
    } catch (error) {
        // More robust error handling for Axios
        if (error.response) {
            console.error("API Error - Status Code:", error.response.status);
            console.error("API Error - Response Data:", error.response.data);
            console.error("API Error - Headers:", error.response.headers);
        } else if (error.request) {
            console.error("Network Error: No response received from server.");
            console.error("Request:", error.request);
        } else {
            console.error("Error setting up request:", error.message);
        }
        console.error("Full Error Object:", error);
    }
}

main();
```

**Java**

```java
//Para Java precisaremos criar um arquivo com o nome de qitech-java-client
//Crie um arquivo chamado pom.xml e cole o final do código dentro dele
// Será necessário dentro do seu projeto criar algumas pastas - crie o seguinte path; src > main > java > com > qitech > api e insira seu arquivo java dentro com o nome de QItechApiClient.java
// Adicione sua private key no diretório raiz de seu projeto no mesmo nível que seu pom
// Para rodar o código abra o terminal ou comand prompt, navegue para a raiz de seu projeto e rode o seguinte código:
// mvn clean install exec:java

//Aqui, importamos as bibliotecas necessárias ao longo do processo de autenticação.
package com.qitech.api;

import com.google.gson.Gson;
import io.jsonwebtoken.JwtBuilder;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;
import org.bouncycastle.jce.provider.BouncyCastleProvider;

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.security.KeyFactory;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.security.PrivateKey;
import java.security.Security;
import java.security.spec.InvalidKeySpecException;
import java.security.spec.PKCS8EncodedKeySpec;
import java.text.SimpleDateFormat;
import java.util.Base64;
import java.util.Collections;
import java.util.Date;
import java.util.HashMap;
import java.util.Map;
import java.util.TimeZone;
import java.util.concurrent.TimeUnit;
import org.bouncycastle.jce.ECNamedCurveTable;
import org.bouncycastle.jce.spec.ECParameterSpec;
import org.bouncycastle.jce.spec.ECPrivateKeySpec;

public class QItechApiClient {

    public static Map<String, String> getAuthHeader(String endpoint, String method, PrivateKey privateKey, String apiKey, Map<String, Object> requestBody) throws NoSuchAlgorithmException {        
        //O objeto de data e hora informado deve estar em UTC e deve seguir o padrão da norma internacional ISO 8601 ("2023-06-26T19:48:32.759844Z")
        SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSSSSS'Z'");
        sdf.setTimeZone(TimeZone.getTimeZone("UTC"));
        String timestamp = sdf.format(new Date());

        //Construir hash em MD5 para assinatura no cabeçalho (header) utilizando o payload
        String jsonBody = jsonToString(requestBody);
        String md5Hash = md5Hash(jsonBody);

        //Essas são as infromações necessárias para assinatura do cabeçalho
        Map<String, Object> jwtBody = new HashMap<>();
        jwtBody.put("payload_md5", md5Hash);
        jwtBody.put("timestamp", timestamp);
        jwtBody.put("method", method);
        jwtBody.put("uri", endpoint);

        //Realizar criptografia do header
        JwtBuilder jwtBuilder = Jwts.builder()
                .setClaims(jwtBody)
                .signWith(privateKey, SignatureAlgorithm.ES512);
        String encodedHeaderToken = jwtBuilder.compact();

        //Montar header assinado
        Map<String, String> signedHeader = new HashMap<>();
        signedHeader.put("AUTHORIZATION", encodedHeaderToken);
        signedHeader.put("API-CLIENT-KEY", apiKey);

        return signedHeader;
    }

    public static void main(String[] args) {
        Security.addProvider(new BouncyCastleProvider());
        OkHttpClient client = null;

        try {

            //Utilizaremos as variáveis base_url, endpoint, method e request_body. Neste exemplo faremos um POST no endpoint "/test".
                //As chaves contidas neste exemplo são apenas para fins de demonstração. Por favor, utilize suas próprias chaves.
            final String BASE_URL = "https://api.sandbox.insurance.qitech.app";
            final String PRIVATE_KEY_FILENAME = "private.key";

            final String API_CLIENT_KEY = "SUA API KEY AQUI";
            
            final String METHOD = "GET";  //GET ou POST
            final Map<String, Object> REQUEST_BODY = new HashMap<>();
            REQUEST_BODY.put("name", "QI Tech");

            
            String keyFromFile = readKeyFromFile(PRIVATE_KEY_FILENAME);
            PrivateKey privateKey = getPrivateKey(keyFromFile);

            String endpoint;
            Request request;

            //Para fazer um GET na /test, é necessário inserir a API key ao final, enquanto para fazer um POST no mesmo endpoint, não é necessário

            if ("GET".equalsIgnoreCase(METHOD)) {
                endpoint = "/test/" + API_CLIENT_KEY;

                Map<String, String> headers = getAuthHeader(endpoint, "GET", privateKey, API_CLIENT_KEY, Collections.emptyMap());

                request = new Request.Builder()
                        .url(BASE_URL + endpoint)
                        .headers(okhttp3.Headers.of(headers))
                        .get()
                        .build();

            } else {
                endpoint = "/test";

                Map<String, String> headers = getAuthHeader(endpoint, "POST", privateKey, API_CLIENT_KEY, REQUEST_BODY);

                RequestBody body = RequestBody.create(
                    jsonToString(REQUEST_BODY),
                    MediaType.parse("application/json; charset=utf-8")
                );

                request = new Request.Builder()
                        .url(BASE_URL + endpoint)
                        .headers(okhttp3.Headers.of(headers))
                        .post(body)
                        .build();
            }

            client = new OkHttpClient.Builder()
                    .connectTimeout(30, TimeUnit.SECONDS)
                    .readTimeout(30, TimeUnit.SECONDS)
                    .build();

            System.out.println("--- Sending " + METHOD + " Request ---");
            System.out.println("URL: " + BASE_URL + endpoint);

            try (Response response = client.newCall(request).execute()) {
                System.out.println("\n--- Received Response ---");
                System.out.println("Status Code: " + response.code());
                if (response.body() != null) {
                    System.out.println("Response Body: " + response.body().string());
                }
            }

        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            if (client != null) {
                client.dispatcher().executorService().shutdown();
                client.connectionPool().evictAll();
            }
        }
    }

    // --- Helper Methods ---
    
    private static String readKeyFromFile(String filename) throws IOException {
        String key = new String(Files.readAllBytes(Paths.get(filename)));
        return key.replace("-----BEGIN EC PRIVATE KEY-----", "")
                  .replace("-----END EC PRIVATE KEY-----", "")
                  .replace("-----BEGIN PRIVATE KEY-----", "")
                  .replace("-----END PRIVATE KEY-----", "")
                  .replaceAll("\\s", "");
    }

    private static String jsonToString(Map<String, Object> jsonMap) { return new Gson().toJson(jsonMap); }

    private static String md5Hash(String text) throws NoSuchAlgorithmException {
        MessageDigest md = MessageDigest.getInstance("MD5");
        byte[] array = md.digest(text.getBytes());
        StringBuilder sb = new StringBuilder();
        for (byte b : array) { sb.append(String.format("%02x", b)); }
        return sb.toString();
    }

    private static PrivateKey getPrivateKey(final String encodedPvKey) throws IOException {
        try {
            byte[] derBytes = Base64.getDecoder().decode(encodedPvKey);
            KeyFactory keyFactory = KeyFactory.getInstance("EC", BouncyCastleProvider.PROVIDER_NAME);
            try {
                return keyFactory.generatePrivate(new PKCS8EncodedKeySpec(derBytes));
            } catch (InvalidKeySpecException e) {
                org.bouncycastle.asn1.sec.ECPrivateKey sec1Key = org.bouncycastle.asn1.sec.ECPrivateKey.getInstance(derBytes);
                ECParameterSpec ecParameterSpec = ECNamedCurveTable.getParameterSpec("secp521r1");
                ECPrivateKeySpec privateKeySpec = new ECPrivateKeySpec(sec1Key.getKey(), ecParameterSpec);
                return keyFactory.generatePrivate(privateKeySpec);
            }
        } catch (Exception e) {
            throw new IOException("Failed to parse private key. Key is corrupted or not a valid EC key.", e);
        }
    }
}

////POM File

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.qitech.api</groupId>
    <artifactId>qitech-api-client</artifactId>
    <version>1.0.0</version>

    <properties>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <!-- HTTP Client -->
        <dependency>
            <groupId>com.squareup.okhttp3</groupId>
            <artifactId>okhttp</artifactId>
            <version>4.12.0</version>
        </dependency>

        <!-- JSON Web Token (JWT) Handling -->
        <dependency>
            <groupId>io.jsonwebtoken</groupId>
            <artifactId>jjwt-api</artifactId>
            <version>0.12.5</version>
        </dependency>
        <dependency>
            <groupId>io.jsonwebtoken</groupId>
            <artifactId>jjwt-impl</artifactId>
            <version>0.12.5</version>
            <scope>runtime</scope>
        </dependency>
        <dependency>
            <groupId>io.jsonwebtoken</groupId>
            <artifactId>jjwt-jackson</artifactId>
            <version>0.12.5</version>
            <scope>runtime</scope>
        </dependency>

        <!-- Cryptography Provider for ES512 -->
        <dependency>
            <groupId>org.bouncycastle</groupId>
            <artifactId>bcprov-jdk18on</artifactId>
            <version>1.78</version>
        </dependency>

        <!-- JSON Serialization -->
        <dependency>
            <groupId>com.google.code.gson</groupId>
            <artifactId>gson</artifactId>
            <version>2.10.1</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.13.0</version>
            </plugin>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>3.2.0</version>
                <configuration>
                    <mainClass>com.qitech.api.QItechApiClient</mainClass>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

```

**C#**

```c#
//Aqui, importamos as bibliotecas necessárias ao longo do processo de autenticação.
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Threading.Tasks;
using Jose;
using Newtonsoft.Json;

public static class QiTechAuthGenerator {
    public static string GetAuthorizationHeader(
        string endpoint,
        string method,
        string clientPrivateKey,
        object requestBody)
    {
        string privateKeyBase64 = clientPrivateKey 
            .Replace("-----BEGIN EC PRIVATE KEY-----", "")
            .Replace("-----END EC PRIVATE KEY-----", "")
            .Replace("\n", "")
            .Replace("\r", "");

        using var privateKey = ECDsa.Create();
        privateKey.ImportECPrivateKey(Convert.FromBase64String(privateKeyBase64), out _);

        string payloadToHash;

        if (method.ToUpper() == "GET") {
            payloadToHash = "{}";
        }
        else {
            payloadToHash = JsonConvert.SerializeObject(requestBody);
        }
        
        //Construir hash em MD5 para assinatura no cabeçalho (header) utilizando o payload
        var payloadMd5Hash = CalculateMd5Hash(payloadToHash);

        //Essas são as infromações necessárias para assinatura do cabeçalho
        var jwtBody = new Dictionary<string, object> {
            { "payload_md5", payloadMd5Hash },
            { "timestamp", timestamp },
            { "method", method },
            { "uri", endpoint }
        };

        //Definimos o algoritmo de codificação JWT
        var jwtHeader = new Dictionary<string, object> {
            { "typ", "JWT" },
            { "alg", "ES512" }
        };

        return JWT.Encode(jwtBody, privateKey, JwsAlgorithm.ES512, jwtHeader);
    }

    //Construir hash em MD5 para assinatura no cabeçalho (header) utilizando o payload
    private static string CalculateMd5Hash(string input) {
        using (var md5 = MD5.Create()) {
            byte[] inputBytes = Encoding.UTF8.GetBytes(input);
            byte[] hashBytes = md5.ComputeHash(inputBytes);

            var builder = new StringBuilder();
            foreach (var b in hashBytes) {
                builder.Append(b.ToString("x2"));
            }
            return builder.ToString();
        }
    }
}

public class QiTechApiClient {
    private readonly string _baseUrl;
    private readonly string _apiKey;
    private readonly string _clientPrivateKey;

    public QiTechApiClient(string baseUrl, string apiKey, string clientPrivateKey) {
        _baseUrl = baseUrl;
        _apiKey = apiKey;
        _clientPrivateKey = clientPrivateKey;
    }

    //Realizar criptografia do header
    public async Task<string> CallEndpointAsync(string endpoint, string method, object requestBody) {
        var signedHeader = QiTechAuthGenerator.GetAuthorizationHeader(
            endpoint,
            method,
            _clientPrivateKey,
            requestBody
        );

        var url = $"{_baseUrl}{endpoint}";

        //Montar header assinado
        using (var client = new HttpClient()) {
            client.DefaultRequestHeaders.Add("AUTHORIZATION", signedHeader);
            client.DefaultRequestHeaders.Add("API-CLIENT-KEY", _apiKey);

            HttpResponseMessage httpResponse;

            if (method.ToUpper() == "GET") {
                httpResponse = await client.GetAsync(url);
            }
            else {
                var jsonBody = JsonConvert.SerializeObject(requestBody);
                var content = new StringContent(jsonBody, Encoding.UTF8, "application/json");
                httpResponse = await client.PostAsync(url, content);
            }

            httpResponse.EnsureSuccessStatusCode();

            var responseContent = await httpResponse.Content.ReadAsStringAsync();

            return responseContent;
        }
    }
}

public class Program {
    public static async Task Main() {
        string response = "";
        
        //Utilizaremos as variáveis baseUrl, endpoint, method e requestBody. Neste exemplo faremos um POST no endpoint "/test".
        var baseUrl = "https://api.sandbox.insurance.qitech.app";
        var method = "POST";
        var requestBody = new { name = "QI Tech" };
        
        //As chaves contidas neste exemplo são apenas para fins de demonstração. Por favor, utilize suas próprias chaves.
        var apiKey = "SUA API KEY AQUI";
        var clientPrivateKey = @"SUA PRIVATE KEY AQUI";

        try {
            var apiClient = new QiTechApiClient(baseUrl, apiKey, clientPrivateKey);

            //Para fazer um GET na /test, é necessário inserir a API key ao final, enquanto para fazer um POST no mesmo endpoint, não é necessário
            if (method.ToUpper() == "GET") {
                var endpoint = "/test/" + apiKey;
                response = await apiClient.CallEndpointAsync(endpoint, method, null);
            }
            else {
                var endpoint = "/test";
                response = await apiClient.CallEndpointAsync(endpoint, method, requestBody);
            }

            Console.WriteLine("\nAPI Response:");
            Console.WriteLine(response);
        }
        catch (HttpRequestException ex) {
            Console.WriteLine($"\nHTTP Error: {ex.Message}");
        }
        catch (Exception ex) {
            Console.WriteLine($"\nAn unexpected error occurred: {ex.Message}");
        }
    }
}
```

---

# Teste de autenticação

URL: /documentation/seguros/primeiros_passos/teste_de_autenticacao/seguros_teste_de_autenticacao_v2

:::info Veja também
- [Exemplo completo de autenticação](./seguros_teste_de_autenticacao_completo)
- [Possíveis erros](./seguros_possiveis_erros)
:::

## 1. Introdução e Configuração Inicial

### Visão Geral
Esta documentação detalha o processo de assinatura e encriptação de cabeçalhos para autenticação segura em requisições à nossa API. O processo garante que as requisições sejam confiáveis e seguras, prevenindo acessos não autorizados e garantindo a integridade dos dados.

### Importar Bibliotecas
Aqui, importamos as bibliotecas necessárias ao longo do processo de autenticação.

**Python**

```python
import json
import requests
from datetime import datetime, timezone
from hashlib import md5
from jose import jwt
```

**PHP**

```php
use Jose\Component\Core\AlgorithmManager;
use Jose\Component\Signature\JWSTokenSupport;
use Jose\Component\Signature\Algorithm\ES512;
use Jose\Component\Signature\Serializer\CompactSerializer;
use Jose\Component\Signature\JWSBuilder;
use Jose\Component\KeyManagement\JWKFactory;
```

**Node.js**

```js
const jose = require('jose');
const jwt = require('jsonwebtoken');
const crypto = require('crypto');
const axios = require('axios');
```

**Java**

```java
import io.jsonwebtoken.JwtBuilder;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;
import okhttp3.MediaType;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.RequestBody;
import okhttp3.Response;

import java.io.IOException;
import java.io.StringReader;
import java.security.KeyPair;
import java.security.PrivateKey;
import java.util.Base64;
import java.util.Date;
import java.util.HashMap;
import java.util.Map;

import org.bouncycastle.openssl.PEMKeyPair;
import org.bouncycastle.openssl.PEMParser;
import org.bouncycastle.openssl.jcajce.JcaPEMKeyConverter;
```

**C#**

```c#
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using Jose;
using Newtonsoft.Json;
```

### Definir variáveis

Utilizaremos as variáveis _base_url_, _endpoint_, _method_ e _request_body_. Neste exemplo faremos um POST no endpoint "/test".

**Python**

```python
base_url = "https://api.sandbox.insurance.qitech.app"
endpoint = "/test"
method = "POST"
request_body = {"name": "QI Tech"}
```
  

**PHP**

```php
$base_url = "https://api.sandbox.insurance.qitech.app";
$endpoint = "/test";
$method = "POST";
$request_body = ["name" => "QI Tech"];
```
  

**Node.js**

```js
const base_url = 'https://api.sandbox.insurance.qitech.app';
const endpoint = '/test';
const method = 'POST';
const request_body = { name: 'QI Tech' };
```
  

**Java**

```java
private static final String base_url = "https://api.sandbox.insurance.qitech.app";
private static final String endpoint = "/test";
private static final String method = "POST";
private static final Map<String, Object> request_body = new HashMap<>();
static {
    request_body.put("name", "QI Tech");
}
```
  

**C#**

```c#
var base_url = "https://api.sandbox.insurance.qitech.app";
var endpoint = "/test";
var method = "POST";
var request_body = new { name = "QI Tech" };

```
  

## 2. Preparação de Dados para Assinatura

### Inserir dados de criptografia

As chaves contidas neste exemplo são apenas para fins de demonstração. Por favor, utilize suas próprias chaves. 

**Python**

```python
api_key = "f19c6e62-bd82-4334-9839-020810550c44" 

client_private_key = '''-----BEGIN EC PRIVATE KEY-----
MIHbAgEBBEHh1hIeOPE5XNNhn6bxRAmVswsPZ0wZCmzVvP8Tl/LZK9ofVmRVGzll
srU1uezJEyHKYdOHrE2p52xUj+pHzjJvb6AHBgUrgQQAI6GBiQOBhgAEAAofUz1J
hBSOyGHLsnV9Sz0DSWmhl7U+ljqbfa8PKVFWSV3w16I1v2zME5/UzUhHn1gWsjnv
7/ekcLLAQbvqMPNXAfjIhFXLAPzqbB9iCuVua1v0Vgy52rBemOWrJka/Ws2bnKR8
h1N1OxOYeYr6C2jqMygBLktKMAs+282CEiEb4bIv
-----END EC PRIVATE KEY-----'''  
```
  

**PHP**

```php
$api_key = "f19c6e62-bd82-4334-9839-020810550c44"; 

$privateKeyString = "-----BEGIN EC PRIVATE KEY-----
MIHbAgEBBEHh1hIeOPE5XNNhn6bxRAmVswsPZ0wZCmzVvP8Tl/LZK9ofVmRVGzll
srU1uezJEyHKYdOHrE2p52xUj+pHzjJvb6AHBgUrgQQAI6GBiQOBhgAEAAofUz1J
hBSOyGHLsnV9Sz0DSWmhl7U+ljqbfa8PKVFWSV3w16I1v2zME5/UzUhHn1gWsjnv
7/ekcLLAQbvqMPNXAfjIhFXLAPzqbB9iCuVua1v0Vgy52rBemOWrJka/Ws2bnKR8
h1N1OxOYeYr6C2jqMygBLktKMAs+282CEiEb4bIv
-----END EC PRIVATE KEY-----"; 
```
  

**Node.js**

```js
const api_key = 'f19c6e62-bd82-4334-9839-020810550c44'; 

const client_private_key = `-----BEGIN EC PRIVATE KEY-----
MIHbAgEBBEHh1hIeOPE5XNNhn6bxRAmVswsPZ0wZCmzVvP8Tl/LZK9ofVmRVGzll
srU1uezJEyHKYdOHrE2p52xUj+pHzjJvb6AHBgUrgQQAI6GBiQOBhgAEAAofUz1J
hBSOyGHLsnV9Sz0DSWmhl7U+ljqbfa8PKVFWSV3w16I1v2zME5/UzUhHn1gWsjnv
7/ekcLLAQbvqMPNXAfjIhFXLAPzqbB9iCuVua1v0Vgy52rBemOWrJka/Ws2bnKR8
h1N1OxOYeYr6C2jqMygBLktKMAs+282CEiEb4bIv
-----END EC PRIVATE KEY-----`; 
```
  

**Java**

```java
private static final String clientPrivateKey = "MIHbAgEBBEHh1hIeOPE5XNNhn6bxRAmVswsPZ0wZCmzVvP8Tl/LZK9ofVmRVGzll
srU1uezJEyHKYdOHrE2p52xUj+pHzjJvb6AHBgUrgQQAI6GBiQOBhgAEAAofUz1J
hBSOyGHLsnV9Sz0DSWmhl7U+ljqbfa8PKVFWSV3w16I1v2zME5/UzUhHn1gWsjnv
7/ekcLLAQbvqMPNXAfjIhFXLAPzqbB9iCuVua1v0Vgy52rBemOWrJka/Ws2bnKR8
h1N1OxOYeYr6C2jqMygBLktKMAs+282CEiEb4bIv"; 
```
  

**C#**

```c#
var api_key = "f19c6e62-bd82-4334-9839-020810550c44"; 
var client_private_key = @"-----BEGIN EC PRIVATE KEY-----
MIHbAgEBBEHh1hIeOPE5XNNhn6bxRAmVswsPZ0wZCmzVvP8Tl/LZK9ofVmRVGzll
srU1uezJEyHKYdOHrE2p52xUj+pHzjJvb6AHBgUrgQQAI6GBiQOBhgAEAAofUz1J
hBSOyGHLsnV9Sz0DSWmhl7U+ljqbfa8PKVFWSV3w16I1v2zME5/UzUhHn1gWsjnv
7/ekcLLAQbvqMPNXAfjIhFXLAPzqbB9iCuVua1v0Vgy52rBemOWrJka/Ws2bnKR8
h1N1OxOYeYr6C2jqMygBLktKMAs+282CEiEb4bIv
-----END EC PRIVATE KEY-----"; 
```
  

### Formatar data
O objeto de data e hora informado deve estar em UTC e deve seguir o padrão da norma internacional ISO 8601 ("2023-06-26T19:48:32.759844Z")

**Python**

```python
timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%fZ")
```
  

**PHP**

```php
$timestamp = gmdate('Y-m-d\TH:i:s.u\Z');
```
  

**Node.js**

```js
const timestamp = new Date().toISOString();
```
  

**Java**

```java
Date now = new Date();
SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSSSSS'Z'");
String formattedDate = sdf.format(now);
```
  

**C#**

```c#
var timestamp = datetime.now.ToString("yyyy-MM-ddTHH:mm:ss.fffZ");
```
  

### Definir cabeçalho JWT
Definimos o algoritmo de codificação JWT

**Python**

```python
jwt_header = {
    "typ": "JWT",
    "alg": "ES512"
}
```
  

**PHP**

```php
$header = [
    "typ" => "JWT",
    "alg" => "ES512"
];
```
  

**Node.js**

```js
const jwt_header = {
  typ: 'JWT',
  alg: 'ES512'
};
```
  

**Java**

```java
// Não é necessário
```
  

**C#**

```c#
var jwt_header = new Dictionary<string, object>
{ 
  { "typ", "JWT" },
  { "alg", "ES512" }
};
```
  

### Construir hash em MD5 para assinatura no cabeçalho JSON

Construir hash em MD5 para assinatura no cabeçalho (header) utilizando o payload

**Python**

```python
json_body = json.dumps(request_body)
md5_hash = md5(json_body.encode()).hexdigest()
```
  

**PHP**

```php
$request_body_json = json_encode($request_body);
$md5_hash = md5($request_body_json);
```
  

**Node.js**

```js
const str_body = JSON.stringify(request_body);
const md5_hash = crypto.createHash('md5').update(str_body).digest('hex');
```
  

**Java**

```java
String payloadMd5 = md5Hash(jsonToString(request_body));

...

private static String jsonToString(Map<String, Object> jsonMap) {
    return new com.google.gson.Gson().toJson(jsonMap);
}

...

private static String md5Hash(String text) {
    try {
        java.security.MessageDigest md = java.security.MessageDigest.getInstance("MD5");
        byte[] array = md.digest(text.getBytes());
        StringBuilder sb = new StringBuilder();
        for (byte b : array) {
            sb.append(String.format("%02x", b));
        }
        return sb.toString();
    } catch (java.security.NoSuchAlgorithmException e) {
        return null;
    }
}
```
  

**C#**

```c#
var json_body = JsonConvert.SerializeObject(request_body);
var md5_hash = CalculateMD5Hash(json_body);

.

static string CalculateMD5Hash(string input)
{
    using (MD5 md5 = MD5.Create())
    {
        byte[] inputBytes = Encoding.UTF8.GetBytes(input);
        byte[] hashBytes = md5.ComputeHash(inputBytes);

        StringBuilder builder = new StringBuilder();

        for (int i = 0; i < hashBytes.Length; i++)
        {
            builder.Append(hashBytes[i].ToString("x2"));
        }

        return builder.ToString();
    }
}
```
  

:::caution Atenção!

Requisições dos métodos `GET` e `DELETE` não possuem corpo. O hash md5 dessas requisições deve ser gerado sobre a **string vazia** (`""`), e o valor é sempre a constante abaixo:

```
d41d8cd98f00b204e9800998ecf8427e
```

Esse valor é **diferente** do utilizado no Lending-as-a-Service, que assina `GET` e `DELETE` com o md5 do objeto JSON vazio (`"{}"`), `99914b932bd37a50b983c5e7c90ae93b`. Se você já integra o Lending-as-a-Service, não reaproveite a constante: assinar um `GET` do Insurance-as-a-Service com ela retorna `401` com o código `EGW000006`.
:::

### Os dois erros `401` do header `AUTHORIZATION`

Uma falha no header `AUTHORIZATION` retorna `401` com um de dois códigos, e eles apontam para causas diferentes:

| Status | Código | Descrição |
|---|---|---|
| `401` | `EGW000004` | A assinatura da requisição não pôde ser verificada com a chave pública registrada da integração. |
| `401` | `EGW000006` | O digest do payload assinado não corresponde ao corpo da requisição. |

- `EGW000004` significa que o problema está no **par de chaves**: a assinatura não foi verificada com a chave pública registrada para a sua integração. Confira a [troca de chaves](/documentation/seguros/primeiros_passos/seguros_troca_de_chaves), inclusive o formato do arquivo enviado.
- `EGW000006` significa que a assinatura **foi verificada com sucesso** — a sua chave está correta — e que apenas o `md5` não corresponde ao corpo enviado. Não investigue o par de chaves: confira o hash, começando pela constante de `GET` e `DELETE` acima.

### Construir hash em MD5 para assinatura no cabeçalho Arquivo

Construir hash em MD5 para assinatura no cabeçalho (header) utilizando um arquivo

**Python**

```python
md5_instance = md5()
for chunk in iter(lambda: file.read(4096), b""):
    md5_instance.update(chunk)

file.seek(0)
md5_hash = md5_instance.hexdigest()
```

**PHP**

```php
$md5_instance = md5_file($file);
$md5_hash = hash_file('md5', $file);
```

**Node.js**

```js
const md5_instance = crypto.createHash('md5');
const readStream = fs.createReadStream(file);

readStream.on('data', (chunk) => {
  md5_instance.update(chunk);
});

readStream.on('end', () => {
  const md5_hash = md5_instance.digest('hex');
  file.seek(0);
```

**Java**

```java
MessageDigest md5_instance = MessageDigest.getInstance("MD5");
byte[] buffer = new byte[4096];
int bytesRead;

try (InputStream inputStream = new FileInputStream(file)) {
    while ((bytesRead = inputStream.read(buffer)) != -1) {
        md5_instance.update(buffer, 0, bytesRead);
    }
}

byte[] md5_hashBytes = md5_instance.digest();
StringBuilder md5_hashBuilder = new StringBuilder();

for (byte b : md5_hashBytes) {
    md5_hashBuilder.append(String.format("%02x", b));
}

String md5_hash = md5_hashBuilder.toString();
```

**C#**

```c#
using (var md5_instance = MD5.Create())
{
    using (var stream = File.OpenRead(file))
    {
        byte[] hash = md5_instance.ComputeHash(stream);
        string md5_hash = BitConverter.ToString(hash).Replace("-", "").ToLower();
        stream.Seek(0, SeekOrigin.Begin);
    }
}
```

### Definir o corpo do JWT
Essas são as infromações necessárias para assinatura do cabeçalho

**Python**

```python
jwt_body = {
    "payload_md5": md5_hash,
    "timestamp": timestamp,
    "method": method,
    "uri": endpoint
}
```
  

**PHP**

```php
$payload = [
    "payload_md5" => $md5_hash,
    "timestamp" => $timestamp,
    "method" => $method,
    "uri" => $endpoint
];
```
  

**Node.js**

```js
const jwt_body = {
  payload_md5: md5_hash,
  timestamp: timestamp,
  method: method,
  uri: endpoint
};
```
  

**Java**

```java
Map<String, Object> jwt_body = new HashMap<>();
jwt_body.put("payload_md5", payloadMd5);
jwt_body.put("timestamp", formattedDate);
jwt_body.put("method", method);
jwt_body.put("uri", endpoint);
```
  

**C#**

```c#
// Ajuste: Remover espaços e quebras de linha no meio da chave privada
client_private_key = client_private_key.Replace("-----BEGIN EC PRIVATE KEY-----", "")
                                       .Replace("-----END EC PRIVATE KEY-----", "")
                                       .Replace("\n", "")
                                       .Replace("\r", "");
// Converter a chave privada para ECDsa
using (ECDsa ecdsa = ECDsa.Create())
{
  ecdsa.ImportECPrivateKey(Convert.FromBase64String(client_private_key), out _);
  var jwt_body = new Dictionary<string, object>
    {
      { "payload_md5", md5_hash },
      { "timestamp", timestamp },
      { "method", method },
      { "uri", endpoint }
    };
```
  

### Realizar criptografia do header

**Python**

```python
encoded_header_token = jwt.encode(
    claims=jwt_body,
    key=client_private_key,
    algorithm="ES512",
    headers=jwt_header
)
```
  

**PHP**

```php
$jws = $jwsBuilder
    ->create()
    ->withPayload(json_encode($payload))
    ->addSignature($privateKey, $header)
    ->build();
$serializer = new CompactSerializer();
$jwt = $serializer->serialize($jws, 0);
```
  

**Node.js**

```js
const encoded_header_token = jwt.sign(
  jwt_body,
  client_private_key,
  {
    algorithm: 'ES512',
    header: jwt_header
  }
);
```
  

**Java**

```java
PrivateKey privateKey = getPrivateKey(clientPrivateKey);
JwtBuilder jwtBuilder = Jwts.builder().setClaims(jwt_body).signWith(privateKey, SignatureAlgorithm.ES512);
String encodedHeaderToken = jwtBuilder.compact();

...

public static PrivateKey getPrivateKey(final String encodedPvKey) {
    try {
        final String pvKey = new String(Base64.getDecoder().decode(encodedPvKey));
        PEMParser pemParser = new PEMParser(new StringReader(pvKey));
        PEMKeyPair pemKeyPair = (PEMKeyPair) pemParser.readObject();

        JcaPEMKeyConverter converter = new JcaPEMKeyConverter();
        KeyPair kp = converter.getKeyPair(pemKeyPair);
        pemParser.close();

        return kp.getPrivate();
    } catch (IOException e) {
        throw new RuntimeException("Couldn't load private key");
    }
}
```
  

**C#**

```c#
var encoded_header_token = JWT.Encode(jwt_body, ecdsa, JwsAlgorithm.ES512, jwt_header);
```
  

### Montar header assinado

**Python**

```python
signed_header = {
    "AUTHORIZATION": encoded_header_token,
    "API-CLIENT-KEY": api_key
}
```
  

**PHP**

```php
$headers = [
    'Authorization' => $jwt,
    'API-CLIENT-KEY' => $api_key,
];
```
  

**Node.js**

```js
const signed_header = {
  AUTHORIZATION: encoded_header_token,
  'API-CLIENT-KEY': api_key
};
```
  

**Java**

```java
Map<String, String> headers = new HashMap<>();
headers.put("AUTHORIZATION", encodedHeaderToken);
headers.put("API-CLIENT-KEY", api_key);
```
  

**C#**

```c#
using (var client = new HttpClient())
    client.DefaultRequestHeaders.Clear();
    client.DefaultRequestHeaders.Add("AUTHORIZATION", encoded_header_token);
    client.DefaultRequestHeaders.Add("API-CLIENT-KEY", api_key);
```
  

### Construir a URL da solicitação

**Python**

```python
url = f"{base_url}{endpoint}"
```
  

**PHP**

```php
$url = $base_url . $endpoint;
```
  

**Node.js**

```js
const url = `${base_url}${endpoint}`;
```
  

**Java**

```java
String requestUrl = base_url + endpoint;
```
  

**C#**

```c#
var url = $"{base_url}{endpoint}";
```
  

## 3. Realizar Requisição

**Python**

```python
post_test_response = requests.post(url=url, headers=signed_header, json=request_body)
```
  

**PHP**

```php
$response = \WpOrg\Requests\Requests::post($url, $headers, json_encode($request_body));
```
  

**Node.js**

```js
axios
  .post(url, request_body, { headers: signed_header })
  .then(response => {
    console.log(response.data);
  })
  .catch(error => {
    console.error(error);
  });
```
  

**Java**

```java
OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/json");
okhttp3.RequestBody requestBody = RequestBody.create(mediaType, jsonToString(request_body));
Request request = new Request.Builder().url(requestUrl).headers(okhttp3.Headers.of(headers))
        .method(method, requestBody).build();
Response response = client.newCall(request).execute();

System.out.println(response.body().string());
```
  

**C#**

```c#
var content = new StringContent(json_body, Encoding.UTF8, "application/json");
var post_test_response = client.PostAsync(url, content).Result;
```

---

# Validação de Webhooks

URL: /documentation/seguros/primeiros_passos/teste_de_autenticacao/seguros_webhook_v2

:::info Veja também
- [Configurando Webhooks](/documentation/seguros/primeiros_passos/seguros_configurando_webhooks)
:::

## 1. Introdução e Preparação

### Visão Geral e Importância
Esta seção aborda como a QI Tech envia webhooks com headers assinados, destacando a importância de descriptografar e validar esses headers para garantir segurança nas comunicações.

### Formato das Requisições
As requisições de webhook serão enviadas para a [URL configurada para recebimento dos webhooks](/documentation/seguros/primeiros_passos/seguros_configurando_webhooks). Elas possuem um formato específico de headers e body, detalhado a seguir.

ENDPOINT URL configurada para recebimento dos webhooks
MÉTODO POST

Request Headers

```json
{
    "AUTHORIZATION": "eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkX21kNSI6IjRhNjAzZjBmMGU3ZGRkZTlkYTJhMGFkM2QzNDFmNzRiIiwidGltZXN0YW1wIjoiMjAyMy0wNi0zMFQxODo1MjoyNy44ODU3MzFaIiwibWV0aG9kIjoiUE9TVCIsInVyaSI6Ii90ZXN0In0.AcNiJqXDdVmlXSbPI6bH41n0KXz9JwVVMgo4Ivqsq5UZjM2WBOTWw3aAvIMAAhjK5OdrURD4cX3dbbnRgzxspUckANRt0hVHRKSkhROHBfZxuTXVfv8oYzwghwiO2MatPBsroC9Vxbh-DEVQJIBigtN9_D5bg8p2-mlVvoxou2I-EwZs",
    "API-CLIENT-KEY": "20d6a816-9d21-4e29-bbe5-2ffb3baacfe9"
}
```

Request Body

```json
{
    "body_sample": "Exemplo de webhook"
}
```

## 2. Configuração e Descriptografia

### Importar bibliotecas

Antes de começar a descriptografia e validação dos webhooks, é essencial importar as bibliotecas necessárias em sua linguagem de programação preferida. Estas bibliotecas facilitarão o trabalho com JWTs, criptografia e outros aspectos relacionados.

**Python**

```python
import json
from datetime import datetime, timedelta
from hashlib import md5
from jose import jwt
```

**PHP**

```php
use Jose\Component\Core\AlgorithmManager;
use Jose\Component\Signature\Algorithm\ES512;
use Jose\Component\Signature\JWSVerifier;
use Jose\Component\KeyManagement\JWKFactory;
use Jose\Component\Signature\Serializer\JWSSerializerManager;
use Jose\Component\Signature\Serializer\CompactSerializer;
```

**Node.js**

```js
const jwt = require('jsonwebtoken');
const crypto = require('crypto');
```

**Java**

```java
import io.jsonwebtoken.Claims;
import io.jsonwebtoken.Jwts;
import org.bouncycastle.jce.provider.BouncyCastleProvider;
import org.bouncycastle.util.io.pem.PemReader;
import java.io.IOException;
import java.io.Reader;
import java.io.StringReader;
import java.security.KeyFactory;
import java.security.NoSuchAlgorithmException;
import java.security.PublicKey;
import java.security.Security;
import java.security.spec.InvalidKeySpecException;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;
```

**C#**

```c#
using System;
using System.Collections.Generic;
using System.Security.Cryptography;
using System.Text;
using Newtonsoft.Json;
using Jose;
```

### Definir variáveis

Defina as variáveis necessárias para manipular os headers e o corpo do webhook. Isso inclui a chave pública fornecida pela QI Tech, utilizada para descriptografar e validar o webhook.

**Python**

```python
headers = {
    "AUTHORIZATION": "eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkX21kNSI6IjRhNjAzZjBmMGU3ZGRkZTlkYTJhMGFkM2QzNDFmNzRiIiwidGltZXN0YW1wIjoiMjAyMy0wNi0zMFQxODo1MjoyNy44ODU3MzFaIiwibWV0aG9kIjoiUE9TVCIsInVyaSI6Ii90ZXN0In0.AcNiJqXDdVmlXSbPI6bH41n0KXz9JwVVMgo4Ivqsq5UZjM2WBOTWw3aAvIMAAhjK5OdrURD4cX3dbbnRgzxspUckANRt0hVHRKSkhROHBfZxuTXVfv8oYzwghwiO2MatPBsroC9Vxbh-DEVQJIBigtN9_D5bg8p2-mlVvoxou2I-EwZs",
    "API-CLIENT-KEY": "20d6a816-9d21-4e29-bbe5-2ffb3baacfe9",
}
body = {"body_sample": "Exemplo de webhook"}
authorization = headers.get("AUTHORIZATION")
```

**PHP**

```php
$headers = [
    "AUTHORIZATION" => "eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkX21kNSI6IjRhNjAzZjBmMGU3ZGRkZTlkYTJhMGFkM2QzNDFmNzRiIiwidGltZXN0YW1wIjoiMjAyMy0wNi0zMFQxODo1MjoyNy44ODU3MzFaIiwibWV0aG9kIjoiUE9TVCIsInVyaSI6Ii90ZXN0In0.AcNiJqXDdVmlXSbPI6bH41n0KXz9JwVVMgo4Ivqsq5UZjM2WBOTWw3aAvIMAAhjK5OdrURD4cX3dbbnRgzxspUckANRt0hVHRKSkhROHBfZxuTXVfv8oYzwghwiO2MatPBsroC9Vxbh-DEVQJIBigtN9_D5bg8p2-mlVvoxou2I-EwZs",
    "API-CLIENT-KEY" => "20d6a816-9d21-4e29-bbe5-2ffb3baacfe9",
];
$body = ["body_sample" => "Exemplo de webhook"];
$authorization = $headers["AUTHORIZATION"];
```

**Node.js**

```js
const headers = {
  AUTHORIZATION: 'eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkX21kNSI6IjRhNjAzZjBmMGU3ZGRkZTlkYTJhMGFkM2QzNDFmNzRiIiwidGltZXN0YW1wIjoiMjAyMy0wNi0zMFQxODo1MjoyNy44ODU3MzFaIiwibWV0aG9kIjoiUE9TVCIsInVyaSI6Ii90ZXN0In0.AcNiJqXDdVmlXSbPI6bH41n0KXz9JwVVMgo4Ivqsq5UZjM2WBOTWw3aAvIMAAhjK5OdrURD4cX3dbbnRgzxspUckANRt0hVHRKSkhROHBfZxuTXVfv8oYzwghwiO2MatPBsroC9Vxbh-DEVQJIBigtN9_D5bg8p2-mlVvoxou2I-EwZs',
  'API-CLIENT-KEY': '20d6a816-9d21-4e29-bbe5-2ffb3baacfe9'
};
const body = { body_sample: 'Exemplo de webhook' };
```

**Java**

```java
String authorization = "eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkX21kNSI6IjRhNjAzZjBmMGU3ZGRkZTlkYTJhMGFkM2QzNDFmNzRiIiwidGltZXN0YW1wIjoiMjAyMy0wNi0zMFQxODo1MjoyNy44ODU3MzFaIiwibWV0aG9kIjoiUE9TVCIsInVyaSI6Ii90ZXN0In0.AcNiJqXDdVmlXSbPI6bH41n0KXz9JwVVMgo4Ivqsq5UZjM2WBOTWw3aAvIMAAhjK5OdrURD4cX3dbbnRgzxspUckANRt0hVHRKSkhROHBfZxuTXVfv8oYzwghwiO2MatPBsroC9Vxbh-DEVQJIBigtN9_D5bg8p2-mlVvoxou2I-EwZs";
```

**C#**

```c#
var headers = new Dictionary<string, string>()
{
    { "AUTHORIZATION", "eyJhbGciOiJFUzUxMiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkX21kNSI6IjRhNjAzZjBmMGU3ZGRkZTlkYTJhMGFkM2QzNDFmNzRiIiwidGltZXN0YW1wIjoiMjAyMy0wNi0zMFQxODo1MjoyNy44ODU3MzFaIiwibWV0aG9kIjoiUE9TVCIsInVyaSI6Ii90ZXN0In0.AcNiJqXDdVmlXSbPI6bH41n0KXz9JwVVMgo4Ivqsq5UZjM2WBOTWw3aAvIMAAhjK5OdrURD4cX3dbbnRgzxspUckANRt0hVHRKSkhROHBfZxuTXVfv8oYzwghwiO2MatPBsroC9Vxbh-DEVQJIBigtN9_D5bg8p2-mlVvoxou2I-EwZs" },
    { "API-CLIENT-KEY", "20d6a816-9d21-4e29-bbe5-2ffb3baacfe9" }
};

var body = new Dictionary<string, string>()
{
    { "body_sample", "Exemplo de webhook" }
};
```

### 2. Inserção de Dados de Criptografia e Realização da Descriptografia
Inserimos a chave pública fornecida pela QI Tech e realizamos a descriptografia do header do webhook. Essa chave é crucial para a descriptografia dos headers do webhook.

**Python**

```python
qi_public_key = """-----BEGIN PUBLIC KEY-----
{QI_PUBLIC_KEY}
-----END PUBLIC KEY-----"""
```

**PHP**

```php
$qiPublicKey = "-----BEGIN PUBLIC KEY-----
{QI_PUBLIC_KEY}
-----END PUBLIC KEY-----";
```

**Node.js**

```js
const qiPublicKey = `-----BEGIN PUBLIC KEY-----
{QI_PUBLIC_KEY}
-----END PUBLIC KEY-----`;
```

**Java**

```java
String publicKeyStr = "{QI_PUBLIC_KEY}";
```

**C#**

```c#
var authorization = headers["AUTHORIZATION"];

var qiPublicKey = @"-----BEGIN PUBLIC KEY-----
{QI_PUBLIC_KEY}
-----END PUBLIC KEY-----";
```

### Realizar descriptografia do header

O processo de descriptografia é essencial para verificar a autenticidade e integridade do webhook recebido.

**Python**

```python
try:
    decoded_header = jwt.decode(token=authorization, key=qi_public_key)
except:
    raise Exception("Decodification failed.")
```

**PHP**

```php
$algorithmManager = new AlgorithmManager([new ES512()]);
$jwsVerifier = new JWSVerifier($algorithmManager);
$publicKey = JWKFactory::createFromKey($qiPublicKey, null, ['use' => 'sig']);
$serializerManager = new JWSSerializerManager([new CompactSerializer]);
$jws = $serializerManager->unserialize($authorization);
$decodedHeader = json_decode($jws->getPayload(), true);
```

**Node.js**

```js
const decodedHeader = jwt.verify(authorization, qiPublicKey);
```

**Java**

```java
private static Claims validate(final String encodedBody, String publicKeyStr){
    try {
        Security.addProvider(new BouncyCastleProvider());

        final String pbKey = new String(Base64.getDecoder().decode(publicKeyStr));
        Reader rdr = new StringReader(pbKey);
        PemReader pemParser = new PemReader(rdr);

        X509EncodedKeySpec spec = new X509EncodedKeySpec(pemParser.readPemObject().getContent());
        KeyFactory kf = KeyFactory.getInstance("EC");

        PublicKey publicKey = kf.generatePublic(spec);
        return Jwts.parser().setSigningKey(publicKey).parseClaimsJws(encodedBody).getBody();
    }  catch (IOException | NoSuchAlgorithmException | InvalidKeySpecException e) {
        throw new IllegalStateException(e);
    }
}
```

**C#**

```c#
var key = ECDsa.Create();
key.ImportFromPem(qiPublicKey);
var decodedHeader = JWT.Decode<IDictionary<string, string>>(authorization, key);
```

## 3. Validação e Conclusão

### Realização de Validações

Após descriptografar o header, é importante realizar várias validações para garantir que o webhook é válido e seguro.

**Python**

```python
assert decoded_header.get("method") == "POST"
assert decoded_header.get("uri") == "/client_webhook_endpoint"
assert (
    decoded_header.get("payload_md5")
    == md5(json.dumps(body).encode()).hexdigest()
)
assert (
    (datetime.now() - timedelta(minutes=5))
    < datetime.strptime(decoded_header.get("timestamp"), "%Y-%m-%dT%H:%M:%S.%fZ")
    < (datetime.now() + timedelta(minutes=5))
)
```

**PHP**

```php
$method = $decodedHeader["method"];
$uri = $decodedHeader["uri"];
$payloadMd5 = $decodedHeader["payload_md5"];
$timestamp = $decodedHeader["timestamp"];

assert($method === "POST");
assert($uri === "/client_webhook_endpoint");
assert($payloadMd5 === md5(json_encode($body, JSON_UNESCAPED_SLASHES)));
assert(
    (new DateTime("now", new DateTimeZone("UTC")))->sub(new DateInterval("PT5M")) < DateTime::createFromFormat("Y-m-d\TH:i:s.u\Z", $timestamp) &&
    DateTime::createFromFormat("Y-m-d\TH:i:s.u\Z", $timestamp) < (new DateTime("now", new DateTimeZone("UTC")))->add(new DateInterval("PT5M"))
);
```

**Node.js**

```js
if (decodedHeader.method !== 'POST') {
    throw new Error('Invalid method');
  }
  
  if (decodedHeader.uri !== '/client_webhook_endpoint') {
    throw new Error('Invalid URI');
  }
  
  const payloadMd5 = crypto
    .createHash('md5')
    .update(JSON.stringify(body))
    .digest('hex');
    
  if (decodedHeader.payload_md5 !== payloadMd5) {
    throw new Error('Invalid payload MD5');
  }
  
  const timestamp = new Date(decodedHeader.timestamp);
  const currentDateTime = new Date();
  
  const fiveMinutesAgo = new Date(currentDateTime.getTime() - 5 * 60000);
  const fiveMinutesAhead = new Date(currentDateTime.getTime() + 5 * 60000);
  
  if (!(timestamp > fiveMinutesAgo && timestamp < fiveMinutesAhead)) {
    throw new Error('Invalid timestamp');
  }
```

**Java**

```java
Claims result = validate(authorization, publicKeyStr);
System.out.println(result);
System.out.println(result.get("method").equals("POST"));
System.out.println(result.get("uri").equals("/test"));
```

**C#**

```c#
var method = decodedHeader["method"];
var uri = decodedHeader["uri"];
var payloadMd5 = decodedHeader["payload_md5"];
var timestamp = DateTime.Parse(decodedHeader["timestamp"]);
timestamp = timestamp.ToUniversalTime();
var bodyJson = JsonConvert.SerializeObject(body, new JsonSerializerSettings
{
    NullValueHandling = NullValueHandling.Ignore,
    Formatting = Formatting.None
});

using (var md5Hash = MD5.Create())
{
    var calculatedMd5 = GetMd5Hash(md5Hash, bodyJson);
    if (payloadMd5 != calculatedMd5)
    {
        throw new Exception("Payload MD5 verification failed.");
    }
}

var currentTime = datetime.now;
var validTimeStart = currentTime.AddMinutes(-5);
var validTimeEnd = currentTime.AddMinutes(5);
if (timestamp < validTimeStart || timestamp > validTimeEnd)
{
    throw new Exception("Timestamp verification failed.");
}

...

static string GetMd5Hash(MD5 md5Hash, string input)
{
    byte[] data = md5Hash.ComputeHash(Encoding.UTF8.GetBytes(input));

    StringBuilder builder = new StringBuilder();
    for (int i = 0; i < data.Length; i++)
    {
        builder.Append(data[i].ToString("x2"));
    }

    return builder.ToString();
}
```

---

# Assinatura em Lote

URL: /documentation/siape/assinatura-em-lote

Agrupa **várias operações SIAPE** em **um único envelope** de assinatura do QI Sign. Você abre o lote, cria as operações referenciando o `document_batch_key`, confere (opcionalmente limpa) e dispara o envio para assinatura.

Fluxo recomendado para [compra de dívida](./04-portabilidade-refin.md) — onde N duplas `debt_purchase` + `refinancing` + 1 refin/refin consolidador podem ser assinadas num único envelope (servidor assina uma vez só).

:::caution Regras do lote
**Mesma titularidade:** todas as operações do lote devem ser do **CPF** (ou do **mesmo representante legal**) do servidor. Incluir CPF "A" e CPF "B" no mesmo lote gera **erro síncrono** no `POST /debt`.

**Tipos permitidos:** o lote SIAPE aceita apenas `POST /debt` com `collateral_type: federal_payroll`.
:::

## 1. Abrir o lote

ENDPOINT /document/document_batch
MÉTODO POST

**Request Body**

```json
{
  "type": "federal_payroll_external_batch",
  "certifier_type": "qi_sign",
  "batch_name": "Lote SIAPE compra-divida - 5ed20003-0610-46d2-88cc-a5d0de640696",
  "request_control_key": "5ed20003-0610-46d2-88cc-a5d0de640696"
}
```

### Campos chave

| Campo | Tipo | Descrição |
|---|---|---|
| `type` | string | Fixo: **`federal_payroll_external_batch`** |
| `certifier_type` | string | Fixo: **`qi_sign`** |
| `batch_name` | string | Nome identificador do lote (**máximo 100 caracteres**) |
| `request_control_key` | string (UUIDv4) | **Idempotência** — não reutilize entre lotes |

**Response Body**

```json
{
  "document_batch_key": "17f35e19-a039-468f-aaa7-84aa8edec3dc"
}
```

Guarde o `document_batch_key` retornado — ele é referenciado em todas as próximas chamadas.

## 2. Incluir operações no lote

Ao criar cada operação SIAPE, envie **`document_batch_key` na raiz** do payload do `POST /debt` (mesmo nível dos demais campos principais).

ENDPOINT /debt
MÉTODO POST

```json
{
  "document_batch_key": "17f35e19-a039-468f-aaa7-84aa8edec3dc",
  "borrower": { "...": "demais campos do borrower" },
  "financial": { "...": "demais campos financeiros" },
  "operation_type": "refinancing",
  "collaterals": [
    {
      "collateral_type": "federal_payroll",
      "collateral_data": {
        "reservation_type": "refinancing",
        "authority_code": "17000",
        "registration_code": "1354387"
      }
    }
  ],
  "modality": { "code": "0202" },
  "refinanced_credit_operations": [
    { "...": "operation_key + contrato externo (ver Portabilidade + Refin)" }
  ]
}
```

O restante do body segue o contrato do `POST /debt`. Consulte os roteiros da [Margem Livre](./03-margem-livre.md) ou [Portabilidade + Refinanciamento](./04-portabilidade-refin.md) conforme a modalidade.

:::tip Compra de dívida cabe num lote só
Pra [compra de dívida](./04-portabilidade-refin.md) (`debt_purchase` + `refinancing` port-enrustido), todas as duplas Op A + Op B + o refin/refin consolidador podem entrar no mesmo lote.
:::

## 3. Consultar documentos do lote

Recomendado **antes de fechar o lote** para conferir os documentos agrupados.

ENDPOINT /document/document_batch/DOCUMENT_BATCH_KEY
MÉTODO GET

**Response Body**

```json
{
  "document_batch_key": "1eee4ec2-05f5-45ef-aa64-38bb3d9de02f",
  "documents": [
    {
      "document_key": "5cca1dad-28fe-4f19-8bbb-0edd6f042384",
      "document_type": "ccb_pre_price_days"
    },
    {
      "document_key": "c109d589-ae18-4f4f-ad31-2879bf714c71",
      "document_type": "ccb_pre_price_days"
    }
  ]
}
```

## 4. Limpar documentos do lote (opcional)

Remove **todos os documentos** vinculados ao lote — útil pra reagrupar do zero se identificar inconsistência antes do envio.

ENDPOINT /document/document_batch/DOCUMENT_BATCH_KEY/documents
MÉTODO DELETE

Body vazio. Response: HTTP 200.

## 5. Enviar para assinatura

Fecha o lote e dispara os documentos pro QI Sign. **Antes desse PUT, os documentos não vão pro servidor.** É o gatilho final.

ENDPOINT /document/document_batch/DOCUMENT_BATCH_KEY/send_to_signature
MÉTODO PUT

Body: `{}`. Response: HTTP 200.

## Erros comuns

| HTTP | Código | Endpoint | Quando ocorre |
|---|---|---|---|
| 404 | `DOC000007` | `GET /document/document_batch/DOCUMENT_BATCH_KEY` | `document_batch_key` inexistente |
| 409 | `DOC000103` | `POST /document/document_batch` | `request_control_key` duplicado (idempotência violada) |

**Exemplo — DOC000103 (idempotência)**

```json
{
  "code": "DOC000103",
  "title": "Bad Request",
  "description": "request_control_key already exists",
  "translation": "Chave de controle da request já existe.",
  "http_status": 409
}
```

:::info Conflito de titularidade
Validação de **mesmo CPF/representante** no lote retorna erro no `POST /debt` (não no endpoint do lote). O corpo de erro segue o catálogo do `/debt`.
:::

---

# Cancelamento, Desaverbação e Reversal (SIAPE)

URL: /documentation/siape/cancelamento

Cancelar uma operação SIAPE tem dois eixos independentes:
1. **Cancelamento da CCB** — estado da operação no LaaS, e eventual estorno do dinheiro desembolsado.
2. **Desaverbação no SIGEPE** — liberação da margem em folha.

Os dois acontecem de forma assíncrona. Cancelar a operação NÃO libera a margem instantaneamente.

## 1. Pré-desembolso — Cancelamento Imediato

```http
PATCH /debt/{DEBT_KEY}/cancel
```

Operação imediatamente vai pra `canceled`. Sem reversal financeiro (dinheiro nem saiu). QI dispara em seguida a desaverbação no SIGEPE.

Webhook: `debt` com `status: canceled` + `cancel_reason_enumerator`.

## 2. Pós-desembolso — Janela de Desistência (7 dias úteis)

**Janela legal de 7 dias úteis** após desembolso. Dentro dela:

```http
PATCH /debt/{DEBT_KEY}/cancel
```

A response retorna um **PIX QR Code** pra borrower pagar de volta o dinheiro desembolsado:

| Campo na response | Significado |
|---|---|
| `cancel_qr_code.qr_code_url` / `digitable_line` | PIX copia-e-cola |
| `cancel_qr_code.amount` | Valor a devolver |
| `cancel_qr_code.expiration` | Prazo (15 dias úteis após desembolso) |

Quando o borrower paga:
1. QI confirma o pagamento.
2. Dispara o **reversal financeiro automático**.
3. Webhook `reversal`:
   ```json
   {
     "webhook_type": "reversal",
     "credit_operation_key": "<uuid>",
     "reversal": {
       "status": "pending_fund",
       "amount": 2026.93,
       "is_total": true,
       "is_operation_canceled": true,
       "reversal_key": "<uuid>"
     }
   }
   ```
4. QI dispara a desaverbação no SIGEPE.
5. Operação vai pra `canceled`.

> [!warning] Janela operacional do SIGEPE afeta desaverbação
> Como o SIAPE só processa 07:00-00:00 em dias úteis, a desaverbação pode demorar. Cancelamento de PIX QR funciona 24/7 (BaaS); só a parte do SIGEPE espera janela.

Restrições pós-desembolso:
- Status `open` (sem parcelas pagas).
- Pagamento parcial bloqueia o cancelamento.
- Sem cancelamento parcial.

## 3. Cancelamento Permanente

```http
PATCH /debt/{DEBT_KEY}/cancel/permanent
```

`canceled_permanently` — não há volta. Sem reversal automático.

## 4. Desaverbação no SIGEPE

![Fluxo de cancelamento SIAPE](/img/diagrams/siape-cancelamento.svg)

| Status | Significado |
|---|---|
| `waiting_confirmation` | SIGEPE ainda processando |
| `successfully_deleted` | Margem liberada |
| `communication_error` | SIGEPE indisponível — QI retenta |

Pra consultar:

```http
GET /debt/{DEBT_KEY}/collateral
```

## 5. Auto-cancelamento (7 dias)

Operações em `canceled` por mais de 7 dias viram automaticamente `canceled_permanently`. Aplica-se a:
- `consent_refused`
- `consent_expired`
- Pendente de assinatura além do prazo
- QR não pago dentro de 15 dias úteis

## Resumo dos Endpoints

| Endpoint | Quando usar | Reversal automático? |
|---|---|---|
| `PATCH /debt/{KEY}/cancel` (pré-desembolso) | Antes do desembolso | Não aplica |
| `PATCH /debt/{KEY}/cancel` (pós-desembolso) | Em até 7 dias úteis após desembolso | Sim — após borrower pagar o PIX QR |
| `PATCH /debt/{KEY}/cancel/permanent` | Definitivo (sem volta) | Não |

## Cancel reasons no webhook `debt` (`status: canceled`)

| Enumerador | Significado |
|---|---|
| `manual` | Cancelado via API ou portal |
| `waiting_signature` | Não assinou no prazo |
| `not_collateral_constituted` | Averbação falhou (consent_refused, consent_expired, etc.) |
| `is_portability` | Portabilidade falhou |
| `pix_max_retry` | Muitas falhas no desembolso PIX |
| `lack_of_resource` | Sem recurso pra desembolsar |
| `kyc_not_accepted` | KYC reprovado |

→ [Lista completa de enumeradores em Mapa de Status](./08-mapa-de-status.md)

---

# Consulta de Margem Consignável (SIAPE)

URL: /documentation/siape/consulta-margem

Endpoint que consulta a margem disponível do servidor federal no SIGEPE/SIAPE. Sem o `balance_key` desse passo, não dá pra simular nem emitir.

## Pré-requisitos

1. **Servidor pré-autorizou QI SCD** no Portal do Servidor (válida 30 dias).
2. `authority_code` (código UPAG) — recebido na fase comercial.

> [!warning]
> Diferente do Exército, **não há upload de documento de autorização**. Tudo é digital no portal.

## Endpoint

```http
POST /federal_payroll/balance
```

| Campo | Tipo | Descrição |
|---|---|---|
| `document_number` | string | CPF do servidor (11 dígitos) |
| `authority_code` | string | Código da Unidade Pagadora (UPAG) |
| `registration_code` | string | Matrícula SIAPE |

Resposta síncrona:

```json
{
  "balance_key": "...",
  "status": "pending_search"
}
```

## Webhook de resultado

Tipo: `federal_payroll.balance`

Estrutura do payload de **sucesso**:
```json
{
  "balance_query": [
    {
      "available_balance": 3500.00,
      "authority_code": "17000",
      "registration_code": "1354387",
      "employment_relationship": "active",
      "consigned_credit": 1200.00,
      "consigned_card": 300.00
    }
  ]
}
```

- `available_balance` — margem disponível
- `consigned_credit` — quanto já está consignado em crédito
- `consigned_card` — quanto está em cartão consignado

## Enumeradores de falha (balance)

| Enumerador | Significado | Ação |
|---|---|---|
| `unauthorized_institution` | Servidor não pré-autorizou QI SCD no portal | Pedir autorização |
| `inexistent_relationship` | Sem vínculo federal | Verificar dados |
| `invalid_document_number` | CPF malformado | Verificar CPF |
| `inactive_federal_employee` | Servidor inativo | Não há ação |
| `deceased_federal_employee` | Servidor falecido | Não há ação |

## Cenários de Sandbox

### Sucesso

| `document_number` | `authority_code` | `registration_code` |
|---|---|---|
| 25256363506 | 17000 | 1354387 |

### Falha

| `document_number` | `failure_reason` |
|---|---|
| 71987878353 | `unauthorized_institution` |

> [!info] Reset diário
> Reservas não-finalizadas no sandbox são **encerradas todo dia às 23:59h** pra manter o ambiente limpo.

## Próximo passo

Após o webhook `succeeded` com `available_balance` retornado, escolha a modalidade:

- [Margem Livre](./03-margem-livre.md) — crédito novo com margem disponível
- [Portabilidade + Refinanciamento](./04-portabilidade-refin.md) — refin de operação QI ou compra de dívida externa

---

# Conta Interna para Desembolso

URL: /documentation/siape/conta-interna-desembolso

Em **compra de dívida**, **portabilidade** e **refinanciamento** consignado, o desembolso da operação **não vai direto para a conta externa do tomador**: ele cai numa conta interna **em nome do tomador** (aberta pelo parceiro via `POST /account`). É a partir dessa conta que a QI executa as ações pós-desembolso — **quitação do contrato externo**, **repasse de troco**, **conciliação**.

:::tip Por que conta interna?
Concentrar o desembolso numa conta operacional dá controle do fluxo: a QI consegue orquestrar quitação externa + averbação + repasse de troco sem depender de SLA de banco terceiro no meio do processo.
:::

## Quando usar conta interna vs externa

| Cenário | `disbursement_bank_account` |
|---|---|
| [Margem Livre](./03-margem-livre.md) (crédito novo direto) | Conta **externa** do tomador |
| [Refinanciamento puro](./04-portabilidade-refin.md) (renegocia CO QI ativa) | Conta **interna** em nome do tomador |
| [Portabilidade](./04-portabilidade-refin.md) (com ou sem troco) | Conta **interna** em nome do tomador |
| [Compra de dívida](./04-portabilidade-refin.md) (`debt_purchase` + `refinancing` port-enrustido) | Conta **interna** em nome do tomador **nas duas operações da dupla** |
| Refin/refin consolidador (opcional, fecha várias port/refins) | Conta **interna** em nome do tomador |

## 1. Abrir a conta interna em nome do tomador

ENDPOINT /account
MÉTODO POST

A conta é aberta pelo **parceiro** (autenticado com seus `client_integration_key`), com o `owner_document_number` apontando para o **CPF do tomador**. Reutilize a conta existente — uma por tomador (não abrir nova a cada operação).

**Request Body**

```json
{
  "owner_document_number": "<CPF DO TOMADOR>",
  "owner_person_key": "<PERSON_KEY DO TOMADOR>",
  "requester_key": "<REQUESTER_KEY DO PARCEIRO>",
  "webhook_enabled": true
}
```

:::info Pré-requisito
O tomador precisa estar **onboarded** previamente (ter `person_key`) — o parceiro envia esse `person_key` no `owner_person_key`. Caso contrário, o `/account` falha com `ACC000xxx` por validation.
:::

**Response Body**

```json
{
  "account_key": "602de111-21e1-4c1e-8c5c-d60c032309ca",
  "account_branch": "0001",
  "account_number": "1431704",
  "account_digit": "3",
  "owner_document_number": "<CPF DO TOMADOR>",
  "owner_name": "<NOME DO TOMADOR>",
  "bank_code": "329",
  "account_status": "active",
  "webhook_enabled": true
}
```

:::tip Idempotência por tomador
Se já existe conta ativa para esse `owner_document_number` no parceiro, evite chamar `POST /account` de novo — consulte `GET /accounts?owner_document_number= ` antes e reaproveite o `account_key` retornado.
:::

## 2. Usar a conta no `/debt`

Use os dados retornados em `disbursement_bank_account` no payload do `POST /debt`. **A mesma conta vai nas DUAS operações da dupla `debt_purchase` + `refinancing`** (e no `refinancing` consolidador, se houver).

```json
{
  "disbursement_bank_account": {
    "name": "<NOME DO TOMADOR>",
    "bank_code": "329",
    "account_type": "checking_account",
    "account_branch": "0001",
    "account_number": "1431704",
    "account_digit": "3",
    "document_number": "<CPF DO TOMADOR>",
    "transfer_method": "ted"
  }
}
```

| Campo | Valor (conta interna QI Tech) |
|---|---|
| `bank_code` | `"329"` (QI Tech S.A. — SCD) |
| `account_branch` | `"0001"` |
| `account_number` / `account_digit` | retornados no `POST /account` |
| `document_number` | **CPF do tomador** (mesmo do `owner_document_number`) |
| `transfer_method` | `"ted"` (recomendado para `payment_type_id: 10`) |

Exemplo completo: ver [Portabilidade + Refinanciamento — Compra de dívida](./04-portabilidade-refin.md).

## 3. Ações pós-desembolso

A QI dispara as ações abaixo automaticamente conforme os webhooks confirmam cada etapa.

### 3.1 Conferir saldo

ENDPOINT /account/ACCOUNT_KEY/balance
MÉTODO GET

### 3.2 Quitação do contrato externo (port)

Disparada pela QI ao receber `credit_operation.collateral` (`reservation_status: deleted`) na operação antiga: saldo da conta interna é enviado ao banco origem via **PIX** ou **TED** para liquidar o contrato externo.

### 3.3 Repasse de troco pro tomador (se houver)

Se `final_disbursement_amount > 0` na simulação, o saldo residual é transferido da conta interna para a **conta externa do tomador** (informada no onboarding ou no payload da operação).

### 3.4 Conciliação

ENDPOINT /account/ACCOUNT_KEY/statement
MÉTODO GET

Query params `from_date` e `to_date` no formato `YYYY-MM-DD`.

### 3.5 Webhooks relevantes

| Webhook | Quando dispara |
|---|---|
| `account.balance_change` | Crédito recebido na conta interna (desembolso da CO) |
| `pix_transfer.status_change` | Quitação externa OU repasse de troco confirmados |
| `ted.status_change` | Quitação externa OU repasse via TED confirmados |

## Referências

- [Conta de pagamento — fluxo completo](/documentation/contas/abertura_de_conta/fluxo_de_abertura_de_conta) — referência do `POST /account` em detalhes
- [Portabilidade + Refinanciamento](./04-portabilidade-refin.md) — usa essa conta em compra de dívida (`debt_purchase` + `refinancing`)
- [Webhooks](./07-webhooks.md) — eventos assíncronos da operação

---

# Modelos de Formalização (SIAPE)

URL: /documentation/siape/formalizacao

A QI suporta **5 modelos de formalização** pra operações SIAPE — mesmo conjunto do Exército. Adicionalmente, pra agrupar várias operações num único envelope (recomendado em [compra de dívida](./04-portabilidade-refin.md)), use [Assinatura em Lote](./11-assinatura-em-lote.md).

:::tip Várias operações no mesmo envelope
Em compra de dívida com N duplas `debt_purchase` + `refinancing` (+ refin/refin consolidador), use [Assinatura em Lote](./11-assinatura-em-lote.md) (`POST /document/document_batch` com `type: federal_payroll_external_batch`) — o servidor assina tudo de uma vez só.
:::

## Modelos disponíveis

| Modelo | Quando usar |
|---|---|
| **QI Sign automático** (default) | QI envia link de assinatura ao borrower; nenhuma config extra |
| **QI Sign em lote** | Várias operações num único envelope; ver [Assinatura em Lote](./11-assinatura-em-lote.md) |
| **PDF assinado externamente** | Parceiro tem signature provider próprio |
| **Data-signature: opt-in** | Borrower clica "concordo" em portal do parceiro |
| **Data-signature: zip** | Parceiro envia zip de evidências |
| **Data-signature: selfie** | Biometria via CaaS |

## QI Sign Automático

Não requer chamada adicional após `/debt`. QI envia URL pro borrower. Webhook `debt` fires com `status: signature_finished`.

## PDF assinado externamente

```http
POST /debt/{DEBT_KEY}/signed
```

```json
{
  "signed_document_key": "<uuid retornado pelo upload do PDF>"
}
```

## Data-signature: opt-in

```json
{
  "data_signature": {
    "type": "opt_in",
    "evidence": { "ip_address": "...", "user_agent": "...", "timestamp": "..." }
  }
}
```

## Data-signature: zip

```json
{
  "data_signature": {
    "type": "zip",
    "signed_document_key": "<uuid do zip>"
  }
}
```

## Data-signature: selfie

Requer integração CaaS (face match + liveness):

```json
{
  "data_signature": {
    "type": "selfie",
    "signed_document_key": "<image_key do CaaS>"
  }
}
```

## Webhook após formalização

`debt` com `status: signature_finished` — assinatura aceita pela QI. Em seguida, se `reservation_method: issuing`, a averbação é disparada agora; se `creation`, já foi disparada antes e o desembolso entra na fila quando confirmada.

## Próximo passo

Após o `signature_finished`, a operação segue automaticamente: averbação confirmada (se `issuing`) → desembolso PIX/TED → webhook `debt` (`disbursed`).

Para acompanhar via webhooks: [Webhooks](./07-webhooks.md). Para cancelar a qualquer momento: [Cancelamento](./06-cancelamento.md).

---

# SIAPE-SIGEPE — Introdução

URL: /documentation/siape/introducao

API para originação de **CCB consignado** para **servidores públicos federais** (professores em universidades federais, funcionários em órgãos federais — **não inclui** militares). A reserva de margem é feita via **SIGEPE/SIAPE** e exige pré-autorização da QI SCD no **Portal do Servidor** pelo próprio servidor antes de qualquer operação.

| Item | Valor |
|---|---|
| Autoridade pagadora | Governo Federal / **SIGEPE-SIAPE** |
| Tipo de garantia (`collateral_type`) | `federal_payroll` |
| Modelo de reserva | Averbação (assíncrona, consentida no Portal do Servidor) |
| Funcionamento | **07:00–00:00, dias úteis, exceto feriados** |
| Modalidades suportadas | [Margem Livre (Crédito Novo)](./03-margem-livre.md) e [Portabilidade + Refinanciamento](./04-portabilidade-refin.md) |
| Pré-autorização do servidor | **30 dias** de validade — Portal do Servidor: *Consignações → Empréstimo Consignado → Autorizar Consignatário* |
| Instrumento | CCB (via `POST /debt`) |

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeados de forma restrita.
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

:::caution Janela operacional
Diferente do Exército (24/7), o SIAPE só processa de **segunda a sexta, das 07:00 às 00:00**. Requisições de averbação fora dessa janela ficam em fila e são processadas no próximo dia útil. Planeje retries e SLA com isso em mente.
:::

## Fluxo End-to-End

Em **margem livre** o desembolso vai direto pra conta externa do servidor. Em **refinanciamento, portabilidade e compra de dívida** o desembolso vai pra uma **conta interna em nome do tomador** (aberta pelo parceiro via `POST /account`) — daí a QI quita o contrato externo, repassa o troco e faz a conciliação. Ver [Conta Interna para Desembolso](./10-conta-interna-desembolso.md).

![Fluxo end-to-end SIAPE](/img/diagrams/siape-introducao.svg)

## Modalidades

A operação se divide em quatro modalidades, escolhidas no `operation_type` e `collateral_data`:

| Modalidade | `operation_type` / `reservation_type` | Quando usar | Doc |
|---|---|---|---|
| **Margem Livre** (Crédito Novo) | `operation_type: structured_operation` / `reservation_type: new_credit` | Servidor com margem disponível; sem dívida externa nem refin de operação ativa | [→ Margem Livre](./03-margem-livre.md) |
| **Refinanciamento** | `operation_type: refinancing` / `reservation_type: refinancing` + `operation_key` | Renegociar operação QI ativa (prazo/taxa), eventualmente liberando troco | [→ Port + Refin](./04-portabilidade-refin.md) |
| **Portabilidade** (com ou sem troco) | `operation_type: refinancing` / `reservation_type: refinancing` + `original_contract_number` | Trazer dívida de outro banco; pode incluir troco | [→ Port + Refin](./04-portabilidade-refin.md) |
| **Compra de dívida** (port enrustida) | `operation_type: debt_purchase` + `operation_type: refinancing` (dupla) | Trazer N dívidas externas; QI emite uma dupla `debt_purchase` + `refinancing` por contrato externo, com desembolso em [conta interna em nome do tomador](./10-conta-interna-desembolso.md) | [→ Port + Refin](./04-portabilidade-refin.md) |

## Pré-requisitos

1. **Servidor pré-autorizou QI SCD no Portal do Servidor** — autorização válida 30 dias. Sem isso, `federal_payroll.balance` falha com `unauthorized_institution`. O parceiro deve orientar o servidor a entrar em `Consignações → Empréstimo Consignado → Autorizar Consignatário` antes de qualquer chamada.
2. **Não há upload de termo de autorização** — diferente do Exército, a autorização SIAPE é digital no portal (não há `authorization_document_key` no payload de balance).

## Referência por área

- [Consulta de Margem](./02-consulta-margem.md) — endpoint `/federal_payroll/balance` + UPAG
- [Margem Livre](./03-margem-livre.md) — Simulação + Emissão para `new_credit`
- [Portabilidade + Refinanciamento](./04-portabilidade-refin.md) — Simulação + Emissão para `refinancing` + payloads de compra de dívida (`debt_purchase` + `refinancing` port-enrustido)
- [Formalização](./05-formalizacao.md) — 5 modelos: QI Sign, PDF, opt-in, zip, selfie
- [Conta Interna para Desembolso](./10-conta-interna-desembolso.md) — POST `/account` em nome do tomador + uso em compra de dívida + ações pós-desembolso
- [Assinatura em Lote](./11-assinatura-em-lote.md) — agrupar várias operações num único envelope QI Sign (`POST /document/document_batch`)
- [Cancelamento, Desaverbação e Reversal](./06-cancelamento.md) — pré + pós-desembolso + reversal automático
- [Webhooks](./07-webhooks.md) — todos os eventos assíncronos + payloads
- [Mapa de Status](./08-mapa-de-status.md) — enumeradores consolidados
- [Mocks (Sandbox)](./09-mocks-sandbox.md) — dados de teste e cenários end-to-end

---

# Mapa de Status

URL: /documentation/siape/mapa-de-status

Referência consolidada de todos os enumeradores que podem aparecer nas respostas síncronas e webhooks do produto consignado SIAPE.

## Consulta de Margem (`federal_payroll.balance`)

| Status | Significado |
|---|---|
| `pending_search` | Resposta síncrona — consulta enfileirada |
| `succeeded` | Webhook — margem retornada |
| `failure` | Webhook — falha |

### Failure reasons

| Enumerador | Significado |
|---|---|
| `unauthorized_institution` | Servidor não pré-autorizou QI SCD no Portal |
| `inexistent_relationship` | Sem vínculo federal |
| `invalid_document_number` | CPF malformado |
| `inactive_federal_employee` | Servidor inativo |
| `deceased_federal_employee` | Servidor falecido |

## Averbação / Desaverbação (`credit_operation.collateral`)

| Status | Significado |
|---|---|
| `pending_consent` | SIGEPE aceitou; aguardando servidor confirmar no Portal |
| `success` | Averbação confirmada (`collateral_constituted: true`) |
| `failure` | Falha (ver enumerator) |

### Enumeradores de failure

| Enumerador | Ação |
|---|---|
| `consent_refused` | Servidor recusou no Portal — cancela operação |
| `consent_expired` | Janela de consentimento expirou — cancela |
| `invalid_balance` | Margem insuficiente — cancela |
| `unauthorized_institution` | Autorização QI SCD expirou no Portal — **retenta por até 7 dias** |
| `origin_contract_not_found` | Contrato origem (port/refin) não existe — cancela |
| `waiting_for_origin_contract_closure` | Aguardando quitação externa — permanece em retry |
| `expired_portability` | Janela de port no SIGEPE fechou |
| `successfully_deleted` | Margem desaverbada com sucesso |

## Operação (`debt`)

| Status | Significado |
|---|---|
| `waiting_signature` | Aguardando assinatura |
| `signature_finished` | Assinatura concluída |
| `waiting_disbursement` | Aguardando desembolso |
| `disbursed` | Desembolsado |
| `canceled` | Cancelada (não-permanente) |
| `canceled_permanently` | Cancelada definitivamente |
| `settled` | Liquidada |

### Cancel reasons

| Enumerador | Significado |
|---|---|
| `manual` | Cancelado via API ou portal |
| `waiting_signature` | Não assinou no prazo |
| `not_collateral_constituted` | Averbação falhou |
| `is_portability` | Portabilidade falhou |
| `pix_max_retry` | Muitas falhas no desembolso PIX |
| `lack_of_resource` | Sem recurso pra desembolsar |
| `kyc_not_accepted` | KYC reprovado |
| `agencia_conta_invalida` | Erro em dados bancários |
| `invalid_account` | Conta inválida |
| `rejected_payment` | Pagamento recusado pelo banco destino |

## Reversal (cancelamento pós-desembolso)

| Status | Significado |
|---|---|
| `pending_fund` | Reversal iniciado, aguardando devolução pro fundo |
| `completed` | Reversal completo |
| `failed` | Reversal falhou (raro — investigação manual) |

## Parcelas (`installment.status_change`)

| Status | Significado |
|---|---|
| `opened` | Aberta, ainda não venceu |
| `waiting_payment` | Aberta, na data de vencimento |
| `paid` | Paga em dia |
| `paid_early` | Paga antes do vencimento |
| `paid_partial` | Paga parcialmente |
| `paid_overdue` | Paga após o vencimento |
| `paid_partial_overdue` | Paga parcialmente após vencimento |
| `overdue` | Em atraso |
| `canceled` | Cancelada |

## Recuperar último estado

```http
GET /debt/{DEBT_KEY}/collateral
```

Retorna `last_response` + `reservation_status` + timestamp.

---

# Margem Livre (Crédito Novo)

URL: /documentation/siape/margem-livre

Esteira de **originação direta** quando o servidor federal tem margem consignável disponível no SIAPE/SIGEPE. Cobre simulação e emissão para `reservation_type: new_credit`.

Para refinanciar uma operação QI ativa ou trazer dívida de outro banco, ver [Portabilidade + Refinanciamento](./04-portabilidade-refin.md).

## Pré-requisitos

- Servidor **pré-autorizou QI SCD no Portal do Servidor** (válida 30 dias).
- `balance_key` recebido na [Consulta de Margem](./02-consulta-margem.md), com webhook `federal_payroll.balance` em `status: succeeded`.
- `available_balance` retornado > parcela desejada × prazo.

## 1. Simulação

ENDPOINT /debt_simulation
MÉTODO POST

**Request Body**

```json
{
  "borrower": {
    "person_type": "natural",
    "individual_document_number": "25256363506"
  },
  "financial": {
    "first_due_date": "2026-07-01",
    "installment_face_value": 500.00,
    "disbursement_date": "2026-06-02",
    "number_of_installments": 72,
    "monthly_interest_rate": 0.0185,
    "interest_type": "pre_price_days",
    "credit_operation_type": "ccb",
    "interest_grace_period": 0,
    "principal_grace_period": 0,
    "fine_configuration": {
      "monthly_rate": 0.01,
      "interest_base": "calendar_days",
      "contract_fine_rate": 0.02
    }
  },
  "collaterals": [
    {
      "collateral_type": "federal_payroll",
      "percentage": 1,
      "collateral_data": {
        "reservation_type": "new_credit",
        "authority_code": "17000",
        "registration_code": "1354387"
      }
    }
  ]
}
```

### Campos chave

| Campo | Descrição |
|---|---|
| `collaterals[].collateral_type` | **`federal_payroll`** (obrigatório) |
| `collaterals[].collateral_data.reservation_type` | **`new_credit`** — sempre pra margem livre |
| `collaterals[].collateral_data.authority_code` | Código da Unidade Pagadora (UPAG) |
| `collaterals[].collateral_data.registration_code` | Matrícula SIAPE |
| `financial.installment_face_value` | Parcela — ≤ `available_balance` |
| `financial.number_of_installments` | Prazo (geralmente até 96 meses pra SIAPE) |

`modality.code` **NÃO** é obrigatório em margem livre.

### Janela operacional

Pra `disbursement_date`, lembre que o SIAPE só processa em **dias úteis das 07:00 às 00:00**. Datas em fim de semana ou feriados são empurradas pro próximo dia útil.

## 2. Emissão

ENDPOINT /debt
MÉTODO POST

**Request Body**

```json
{
  "borrower": {
    "name": "MARIA DOS SANTOS",
    "email": "maria@email.com",
    "phone": { "number": "900000000", "area_code": "11", "country_code": "+55" },
    "address": {
      "city": "Brasília", "state": "DF", "number": "100",
      "street": "Esplanada", "complement": "",
      "postal_code": "70000000", "neighborhood": "Centro"
    },
    "role_type": "issuer",
    "birth_date": "1978-09-22",
    "mother_name": "JOSEFINA DOS SANTOS",
    "person_type": "natural",
    "individual_document_number": "25256363506",
    "gender": "female",
    "nationality": "brasileiro",
    "is_pep": false,
    "marital_status": "married"
  },
  "financial": ,
  "simplified": true,
  "collaterals": [
    {
      "collateral_type": "federal_payroll",
      "percentage": 1,
      "collateral_data": {
        "reservation_type": "new_credit",
        "reservation_method": "creation",
        "authority_code": "17000",
        "registration_code": "1354387"
      }
    }
  ],
  "disbursement_bank_account": {
    "name": "MARIA DOS SANTOS",
    "bank_code": "001",
    "account_type": "checking_account",
    "account_digit": "8",
    "branch_number": "1234",
    "account_number": "00098765",
    "document_number": "25256363506",
    "transfer_method": "ted"
  },
  "purchaser_document_number": "32402502000135"
}
```

### `reservation_method`

**creation (averbação imediata)**

Averbação no SIGEPE dispara junto com a criação do `/debt`.

**issuing (averbação após formalização)**

Averbação só dispara após a formalização (`POST /debt/{KEY}/signed`).

### Etapa-chave: confirmação do servidor no Portal

![Fluxo de margem livre SIAPE](/img/diagrams/siape-margem-livre.svg)

:::warning Servidor precisa confirmar
Após o `/debt`, o webhook chega com `status: pending_consent`. **O servidor precisa entrar no Portal do Servidor e confirmar a operação** dentro da janela do SIGEPE. Se não confirmar, expira com `consent_expired` e cancela. Comunique o servidor imediatamente após o `/debt`.
:::

### Webhooks pós `/debt`

| Webhook | Status | Quando |
|---|---|---|
| `debt` | `waiting_signature` | Operação criada |
| `credit_operation.collateral` | `pending_consent` | Aguardando servidor confirmar no Portal |
| `credit_operation.collateral` | `success` (`collateral_constituted: true`) | Servidor confirmou; averbação ativa |
| `debt` | `disbursed` | Desembolso PIX/TED enviado |

→ Próximo passo: [Formalização](./05-formalizacao.md)

## Falhas comuns

| Webhook / Erro | Enumerador | Significado | Ação |
|---|---|---|---|
| `federal_payroll.balance` | `unauthorized_institution` | Servidor não pré-autorizou QI SCD | Solicitar autorização |
| `federal_payroll.balance` | `inexistent_relationship` | Sem vínculo federal | Verificar dados |
| `credit_operation.collateral` | `invalid_balance` | Margem insuficiente | Reduzir parcela |
| `credit_operation.collateral` | `consent_refused` | Servidor recusou no Portal | Conversar com servidor |
| `credit_operation.collateral` | `consent_expired` | Janela do SIGEPE fechou | Re-emitir |

→ [Lista completa de enumeradores](./08-mapa-de-status.md)

## Sandbox

### Sucesso

| `document_number` | `authority_code` | `registration_code` |
|---|---|---|
| 25256363506 | 17000 | 1354387 |

### Falha

| `document_number` | `failure_reason` |
|---|---|
| 71987878353 | `unauthorized_institution` |

→ [Mocks completos](./09-mocks-sandbox.md)

---

# Mocks (Sandbox)

URL: /documentation/siape/mocks-sandbox

O `federal-payroll-api` da QI Tech intercepta as chamadas ao SIAPE/SIGEPE em sandbox e retorna respostas mockadas via [`siape_mocker.py`](https://gitlab.qitech.com.br/qilaas/federal-payroll-api/-/blob/master/src/connectors/siape_mocker.py). Apenas os CPFs listados abaixo são reconhecidos — qualquer outro retorna `cdRetCode 9999` ("O número do documento informado não é um mock válido no ambiente de teste").

## Sucesso completo (consulta + emissão + portabilidade)

CPFs que passam por **todos** os endpoints (`consultarAutorizacoesMargemConsignavelV2`, `incluirContratoV2`, `incluirContratoPortabilidade`, `renovarContratoV2`, etc.) com retorno OK:

| `document_number` (CPF) | `authority_code` | `registration_code` |
|---|---|---|
| 25256363506 | 17000 | 1354387 |
| 03137300088 | 17000 | 1354387 |
| 20472510010 | 17000 | 1354387 |
| 67050758051 | 17000 | 1354387 |
| 59669701066 | 17000 | 1354387 |

Resposta esperada no webhook `federal_payroll.balance` (`status: succeeded`):

```xml
nome: KAUAN RIBEIRO PEREIRA
codOrgao: 17000 (MINISTERIO DA ECONOMIA)
cdMatricula: 1354387
autorizacaoEmprestimo: S (válida até 09/10/2024)
autorizacaoPortabilidade: S (válida até 24/10/2024)
contratoPortado:
  nrCnpj: 00000000000191
  nrContrato: 526985/WU
vlMargemDisp: 100000 (geral), 50000 (portabilidade)
```

## Cenários especiais

### CPF sem autorização (`unauthorized_institution`)

| `document_number` | Comportamento |
|---|---|
| `71987878353` | Funciona apenas em `consultarAutorizacoesMargemConsignavelV2`. Retorna servidor "HELEN LUCIA REZENDE DE MORAES" com `autorizacaoEmprestimo: N` e `autorizacaoPortabilidade: N` |

Use este CPF pra testar a UX de "peça pro servidor autorizar QI SCD no Portal".

### CPF sem margem (`consignable_margin_exceeded`)

| `document_number` | Comportamento |
|---|---|
| `33673248090` | Funciona em `consultarAutorizacoes` (retorna `vlMargemDisp: 0`) E em `incluirContratoV2/incluirContratoPortabilidade/renovarContratoV2` (retorna `cdRetCode: 8058` "Funcionário não tem margem para essa solicitação") |

Use este CPF pra testar fluxo de margem insuficiente após autorização concedida.

## CPFs fora da whitelist

Qualquer outro CPF retorna:

```xml
cdRetCode: 9999
dsRetCode: O número do documento informado não é um mock válido no ambiente de teste
```

Webhook resultante: `federal_payroll.balance` com `status: failure` + `failure_reason: mock_error`.

## Token e Portal do Servidor em Sandbox

- **Não há autorização real no Portal do Servidor em sandbox.** Os mocks já trazem `autorizacaoEmprestimo: S` (ou N) baseado no CPF da whitelist.
- O endpoint `consultarAnuenciaContratos` retorna `void` (não há body) — significa que o mock pula o passo de consulta de anuência.

## Portabilidade — dados do contrato origem mockados

Quando você usa um CPF da whitelist e simula portabilidade, os mocks já têm:

| Campo | Valor mockado |
|---|---|
| `original_financial_institution_document_number` | `00000000000191` (Banco do Brasil) |
| `original_contract_number` | `526985/WU` |
| `due_balance` mockado | varia conforme `vlMargemDisp` da resposta |

Use estes valores ao montar o payload de `/debt` em portabilidade pra que o mock reconheça o contrato origem.

## Reset diário

Reservas que não atingiram estado terminal (`reserved`, `canceled`, `deleted`) são **encerradas automaticamente às 23:59h** pra manter o ambiente limpo.

## Cenário end-to-end completo

Sequência recomendada para validar a integração em sandbox:

1. `POST /federal_payroll/balance` com `25256363506` + `authority_code: 17000` + `registration_code: 1354387`
2. Aguardar webhook `federal_payroll.balance` (succeeded) com `available_balance` retornado
3. `POST /debt_simulation` com `installment_face_value` ≤ `available_balance` retornado
4. `POST /debt` com `reservation_method: creation` (margem livre) ou com `refinanced_credit_operations` (port com `original_contract_number: 526985/WU`)
5. Aguardar webhook `credit_operation.collateral` (`pending_consent` → `success`) — em sandbox o consent é automático após o `/debt`
6. `POST /debt/{KEY}/signed` com QI Sign ou data-signature opt-in
7. Aguardar webhook `debt` (`disbursed`)
8. (opcional cancelamento) `PATCH /debt/{KEY}/cancel` → recebe PIX QR → simular pagamento → webhook `reversal`

## Janela operacional sandbox

Diferente da produção, o sandbox SIAPE **não respeita a janela 07:00-00:00** dias úteis — você pode rodar a qualquer hora, qualquer dia da semana. Em prod a janela é estrita.

## Endpoints mockados (referência interna)

O `siape_mocker.py` cobre estes operation types do SIAPE (SOAP):

| Operation type | Comportamento mockado |
|---|---|
| `consultarAutorizacoesMargemConsignavelV2` | Retorna dados do servidor + autorização emprestimo/portabilidade |
| `incluirContratoV2` | Inclui novo contrato — sucesso pra CPFs whitelist |
| `incluirContratoPortabilidade` | Inclui contrato de portabilidade — sucesso pra whitelist |
| `renovarContratoV2` | Refinanciamento — sucesso pra whitelist |
| `alterarContrato` | Sucesso fixo `cdRetCode: 0000` |
| `consultarContrato` | Retorna situação `Ativo` ou `Aguardando Encerramento do Contrato` (port) |
| `encerrarContrato` | Sucesso fixo |
| `consultarAnuenciaContratos` | Void (pula passo) |

---

# Portabilidade + Refinanciamento

URL: /documentation/siape/portabilidade-refin

Fluxo de **compra de dívida consignada** SIAPE via assinatura em lote. A QI Tech emite uma CCB de quitação (`debt_purchase`) que paga o banco vendedor, uma CCB de portabilidade (`portability`) que porta o contrato, e um `refinancing` consolidador **sempre obrigatório** que carrega seguro e troco. Tudo assinado de uma única vez na QI Sign.

:::info Contas por operação
Cada operação do fluxo exige uma conta de desembolso distinta:

- **`debt_purchase`** → **conta interna QI** em nome do tomador. O desembolso cai nessa conta e quita a dívida origem no banco vendedor via `after_disbursement_actions` (boleto/PIX).
- **`refinancing`** → **conta externa do tomador**. O troco do refinanciamento é desembolsado nessa conta.

O parceiro abre a conta interna via `POST /account` antes da emissão. Ver [Conta Interna para Desembolso](./10-conta-interna-desembolso.md).
:::

## Cenários

O `refinancing` consolidador é **sempre obrigatório** no batch federal — é ele quem carrega seguro e troco.

| Cenário | Composição | Quando usar |
|---|---|---|
| **α** | 1× `debt_purchase` + 1× `portability` + 1× `refinancing` | Porta **uma** dívida externa |
| **β** | N× `debt_purchase` + N× `portability` + 1× `refinancing` | Porta **N dívidas** externas num único envelope |
| **γ** | α ou β + `financial.rebates` no `refinancing` | Qualquer composição acima com prêmio de seguro — gera `insurance_premium_term` automaticamente |

:::caution Regra do seguro e do troco
Seguro (`financial.rebates` com `fee_type: "insurance_premium_qi"`) e troco só podem ser enviados no `refinancing` consolidador (Passo 5).

- **`debt_purchase`** — `rebates` proibido (CCB de quitação não carrega seguro).
- **`portability`** — `rebates` proibido **e** `final_disbursement_amount` deve ser `0`.
:::

## Sequência de chamadas

```
1.  POST /upload   (documentos da operação)
    └─ (opcional) POST /upload  (documento de identificação do tomador)

2.  POST /account  (conta interna QI p/ debt_purchase)

3.  POST /document/document_batch
    └─ (opcional) personal_document com as chaves do documento de identificação

4.  POST /debt  (debt_purchase)        → desembolso em conta interna QI

5.  POST /debt  (portability)          → sem troco, sem seguro

6.  POST /debt  (refinancing)          → seguro + troco em conta externa

7.  PUT  /document/document_batch/{key}/send_to_signature
```

:::caution Ordem obrigatória de inserção no batch
`debt_purchase` deve ser inserido **antes** da `portability` que o referencia, e a `portability` **antes** do `refinancing` consolidador. Inverter a ordem dispara:

- **`DOC000110`** (HTTP 422) — `portability` cujo `refinanced_credit_operations[].operation_key` não casa com nenhum `debt_purchase` já inserido no batch.
- **`DOC000112`** (HTTP 422) — `refinancing` cujo `refinanced_credit_operations[].operation_key` não casa com nenhuma `portability` já inserida no batch.
:::

---

## 1. Upload dos documentos

Antes de abrir a conta e o lote, faça o **upload dos documentos** exigidos na operação via `POST /upload`. Cada chamada retorna um `document_key`, identificador do documento referenciado nas etapas seguintes.

ENDPOINT /upload
MÉTODO POST

→ Autenticação, headers, FormData e exemplos de código (Python / Node.js) em [Upload de Documentos](../upload_de_documentos/upload_de_documentos.md) .

:::caution Atenção
Salve o `document_key` retornado — ele é necessário para a consulta e o uso futuro do documento.
:::

### (Opcional) Documento de identificação do tomador {#documento-de-identificacao-do-tomador}

Se o seu fluxo já coleta o documento de identificação do tomador (RG, CNH etc.), suba os arquivos **neste mesmo passo** e informe as chaves na abertura do lote (Passo 3). A etapa de captura do documento chega **pré-atendida** na jornada de assinatura e o tomador não precisa fotografar o documento novamente.

Suba **um arquivo por lado** do documento, ou **um arquivo único** no caso de documento digital. Não é preciso classificar o arquivo no upload: é o **campo** em que você informa a chave, no Passo 3, que declara qual lado ela representa.

| Campo do `personal_document` | Arquivo esperado |
|---|---|
| `document_identification_front_key` | Frente do documento de identificação |
| `document_identification_back_key` | Verso do documento de identificação |
| `document_identification_full_key` | Documento digital completo, em arquivo único |

Tipos aceitos e os modos de envio de cada um:

| `type` | Documento | Frente e verso | Arquivo único |
|---|---|---|---|
| `rg` | Registro Geral (RG) | ✔ | — |
| `cnh` | Carteira Nacional de Habilitação | ✔ | ✔ |
| `cin` | Carteira de Identidade Nacional | — | ✔ |

O conjunto efetivamente aceito também depende da jornada de assinatura configurada para o seu requester — um `type` fora dessa configuração retorna **`DOC000130`**.

:::caution Atenção
Esses arquivos ficam vinculados ao lote, mas **não são assinados**: não entram no envelope como documentos assináveis e não participam do `send_to_signature`.
:::

---

## 2. Abrir a conta interna em nome do tomador

Em **compra de dívida**, **portabilidade** e **refinanciamento** do consignado federal (Siape), o desembolso da operação **não vai direto para a conta externa do tomador**: ele cai numa conta interna **em nome do tomador** (aberta pelo parceiro via `POST /account`). É a partir dessa conta que a QI executa as ações pós-desembolso — **quitação do contrato externo**, **repasse de troco**, **conciliação**.

ENDPOINT /account
MÉTODO POST

A conta é aberta pelo **parceiro** (autenticado com seus `client_integration_key`), com o `owner_document_number` apontando para o **CPF do tomador**. Reutilize a conta existente — uma por tomador (não abrir nova a cada operação).

**Request Body**

```json
{
  "owner_document_number": "<CPF DO TOMADOR>",
  "owner_person_key": "<PERSON_KEY DO TOMADOR>",
  "requester_key": "<REQUESTER_KEY DO PARCEIRO>",
  "webhook_enabled": true
}
```

**Response Body**

```json
{
  "account_key": "1167955-...",
  "account_branch": "0001",
  "account_number": "1167955",
  "account_digit": "1",
  "owner_document_number": "<CPF DO MILITAR>",
  "owner_name": "<NOME DO MILITAR>",
  "bank_code": "329",
  "account_status": "active",
  "webhook_enabled": true
}
```

:::tip Idempotência por tomador
Se já existe conta ativa para esse `owner_document_number` no parceiro, evite chamar `POST /account` de novo — consulte `GET /accounts?owner_document_number= ` antes e reaproveite o `account_key` retornado.
:::

---

## 3. Abrir o lote

ENDPOINT /document/document_batch
MÉTODO POST

**Request Body**

```json
{
  "type": "federal_payroll_external_batch",
  "certifier_type": "qi_sign",
  "batch_name": "Lote SIAPE portabilidade - <UUID_UNICO>",
  "request_control_key": "<UUID_UNICO_2>"
}
```

### Campos chave

| Campo | Tipo | Descrição |
|---|---|---|
| `type` | string | Fixo: **`federal_payroll_external_batch`** |
| `certifier_type` | string | Fixo: **`qi_sign`** |
| `batch_name` | string | Nome identificador do lote — **único** (não reutilize entre lotes) e **máximo 100 caracteres** |
| `request_control_key` | string (UUIDv4) | **Idempotência** — não reutilize entre lotes |
| `personal_document` | object | (Opcional) Chaves do [documento de identificação do tomador](#documento-de-identificacao-do-tomador) subido no Passo 1 |

### (Opcional) Enviar o documento de identificação pré-coletado {#enviar-documento-de-identificacao}

Informe as `document_key` do Passo 1 no objeto `personal_document`, na **raiz** do payload de abertura do lote:

**Request Body com documento pré-coletado**

```json
{
  "type": "federal_payroll_external_batch",
  "certifier_type": "qi_sign",
  "batch_name": "Lote SIAPE portabilidade - <UUID_UNICO>",
  "request_control_key": "<UUID_UNICO_2>",
  "personal_document": {
    "type": "rg",
    "document_identification_front_key": "3b28a1a6-51c0-4f0e-9b64-2c98d6a3f1e0",
    "document_identification_back_key": "9d47c2b1-8f3a-4e5d-a1c2-7b6e5d4f3a2b"
  }
}
```

| Campo | Tipo | Descrição |
|---|---|---|
| `personal_document.type` | string | Tipo do documento: `rg`, `cnh` ou `cin` |
| `personal_document.document_identification_front_key` | string (UUIDv4) | Chave da **frente** — obrigatório junto com `..._back_key` |
| `personal_document.document_identification_back_key` | string (UUIDv4) | Chave do **verso** — obrigatório junto com `..._front_key` |
| `personal_document.document_identification_full_key` | string (UUIDv4) | Chave do **arquivo único** (documento digital) — não combinar com frente e verso |

:::caution Regras
- Envie **frente + verso** **ou** o **arquivo único** — nunca os dois modos juntos. Combinação inválida retorna **`DOC000128`**.
- Os arquivos devem pertencer ao seu requester e já ter o upload concluído — chave inexistente ou de outro requester retorna **`DOC000004`**; arquivo ausente retorna **`DOC000049`**.
- Cada arquivo só pode ser usado em **um lote**; reaproveitar uma chave já vinculada retorna **`DOC000137`**.
- O envio ocorre **apenas na abertura do lote** — não é possível adicionar ou trocar o documento depois. Se algum arquivo for rejeitado, nenhum lote é criado.
- A requisição precisa identificar o titular dos arquivos: envie o header `SELECTED-AGENT`. Sem ele, a abertura retorna **`QIT000004`**.
:::

**Response Body**

```json
{
  "document_batch_key": "17f35e19-a039-468f-aaa7-84aa8edec3dc"
}
```

Guarde o `document_batch_key` retornado — ele é referenciado em todas as chamadas seguintes.

→ Para consultar, limpar documentos ou conferir o batch antes do envio, ver [Assinatura em Lote](./11-assinatura-em-lote.md).

---

## 4. Emitir `debt_purchase`

CCB de **quitação da dívida original**. A QI Tech vai pagar o banco vendedor.

ENDPOINT /debt
MÉTODO POST

:::info Particularidades do `debt_purchase`
- `document_batch_key` incluído na **raiz** do payload (mesmo nível de `borrower`, `financial`).
- `disbursement_bank_account` aponta para a **conta interna QI** do tomador (Criada no passo 2).
- `after_disbursement_actions` na raiz define a quitação automática da dívida origem após o desembolso (boleto ou PIX do banco vendedor).
:::

**Request Body**

```json
{
  "borrower": {
    "name": "MARIA DOS SANTOS",
    "email": "maria@email.com",
    "phone": { "number": "900000000", "area_code": "11", "country_code": "055" },
    "is_pep": false,
    "address": {
      "city": "Brasília",
      "state": "DF",
      "number": "100",
      "street": "Esplanada dos Ministérios",
      "complement": "",
      "postal_code": "70000000",
      "neighborhood": "Centro"
    },
    "role_type": "issuer",
    "birth_date": "1978-09-22",
    "mother_name": "JOSEFINA DOS SANTOS",
    "nationality": "Brasileiro",
    "person_type": "natural",
    "marital_status": "married",
    "individual_document_number": "25256363506",
    "gender": "female",
    "document_identification_type": "rg",
    "document_identification_number": "1234567",
    "document_identification_date": "2015-01-01"
  },
  "financial": {
    "first_due_date": "2026-06-10",
    "installment_face_value": 100,
    "disbursement_date": "2026-05-10",
    "limit_days_to_disburse": 5,
    "number_of_installments": 20,
    "monthly_interest_rate": 0.017,
    "interest_type": "pre_price_days",
    "fine_configuration": {
      "monthly_rate": 0.01,
      "interest_base": "calendar_days",
      "contract_fine_rate": 0.02
    },
    "credit_operation_type": "ccb",
    "interest_grace_period": 0,
    "principal_grace_period": 0
  },
  "simplified": true,
  "collaterals": [],
  "requester_identifier_key": "<UUIDv4 gerado por request>",
  "disbursement_bank_account": {
    "bank_code": "329",
    "account_digit": "7",
    "branch_number": "0001",
    "account_number": "4944068",
    "document_number": "25256363506",
    "name": "MARIA DOS SANTOS"
  },
  "purchaser_document_number": "<CNPJ do comprador>",
  "document_batch_key": "<document_batch_key DO PASSO 2>",
  "after_disbursement_actions": [
    {
      "action_type": "bankslip_payment",
      "action_data": {
        "qr_code": null,
        "destination": null,
        "digitable_line": "03399199530490000005237385601010297590005474921",
        "pix_transfer_type": null,
        "transaction_amount": 0
      }
    }
  ]
}
```

### Campos que devem ser alterados

| Campo | Obrigatório alterar? | Observação |
|---|---|---|
| `document_batch_key` | ✅ Sim | Valor retornado no Passo 2 |
| `borrower.*` | ✅ Sim | Dados reais do tomador |
| `financial.first_due_date` / `disbursement_date` | ✅ Sim | Conforme calendário da operação |
| `financial.installment_face_value` / `number_of_installments` / `monthly_interest_rate` | ✅ Sim | Conforme condições comerciais |
| `purchaser_document_number` | ✅ Sim | CNPJ do comprador (via variável de ambiente) |
| `requester_identifier_key` | ✅ Sim | UUIDv4 único por requisição |
| `disbursement_bank_account` | ✅ Sim | **Conta interna QI em nome do tomador** |
| `after_disbursement_actions` | ✅ Sim | Quitação da dívida origem. `action_type`: `bankslip_payment` (boleto) ou PIX. Preencha `digitable_line` (boleto) ou `qr_code` (PIX) do banco vendedor |

**Response Body**

```json
{
  "proposal_id": "<id interno>",
  "status": 200,
  "key": "<key da operação debt_purchase>",
  "data": {
    "credit_operation_key": "<mesmo valor de key>",
    "status": "waiting_signature"
  }
}
```

**Guarde a `key` retornada** — ela é passada em `refinanced_credit_operations[].operation_key` da `portability` correspondente.

---

## 5. Emitir `portability`

CCB de **portabilidade da dívida**. Cada portabilidade referencia **exatamente um** `debt_purchase` via `refinanced_credit_operations`. **Não carrega seguro nem troco** — ambos vão no `refinancing` consolidador.

ENDPOINT /debt
MÉTODO POST

:::info Particularidades da `portability`
- `collaterals[0].collateral_data.portability_data` é **obrigatório** — contém os dados do contrato de origem na instituição vendedora.
- `refinanced_credit_operations` carrega a `key` do `debt_purchase` correspondente.
:::

:::caution Portabilidade sem seguro e sem troco
Em batch federal, a `portability` **não pode** carregar `financial.rebates` (seguro). O seguro é enviado exclusivamente no `refinancing` consolidador. A QI Tech rejeita o `POST /debt` que violar essa regra.
:::

**Request Body**

```json
{
  "borrower": { "...": "mesmo borrower do Passo 4" },
  "financial": {
    "first_due_date": "2026-06-10",
    "disbursement_date": "2026-05-10",
    "limit_days_to_disburse": 5,
    "number_of_installments": 20,
    "monthly_interest_rate": 0.017,
    "interest_type": "pre_price_days",
    "final_disbursement_amount": 0,
    "fine_configuration": {
      "monthly_rate": 0.01,
      "interest_base": "calendar_days",
      "contract_fine_rate": 0.02
    },
    "credit_operation_type": "ccb",
    "interest_grace_period": 0,
    "principal_grace_period": 0
  },
  "simplified": true,
  "collaterals": [
    {
      "percentage": 1,
      "collateral_type": "federal_payroll",
      "collateral_data": {
        "authority": {
          "description": "GOVERNO DO DISTRITO FEDERAL",
          "authority_document_number": "00.394.601/0001-26"
        },
        "authority_code": "99072",
        "reservation_type": "portability",
        "registration_code": "1393831",
        "reservation_method": "issuing",
        "pensioner_registration_code": "",
        "portability_data": {
          "start_date": "2024-06-24",
          "control_number": "57309647149",
          "origin_contract": {
            "contract_number": "866415127",
            "financial_institution_document_number": "90400888000142"
          }
        }
      }
    }
  ],
  "requester_identifier_key": "<UUIDv4>",
  "disbursement_bank_account": { "...": "mesmo disbursement do Passo 4" },
  "purchaser_document_number": "<CNPJ do comprador>",
  "document_batch_key": "<document_batch_key DO PASSO 2>",
  "refinanced_credit_operations": [
    { "operation_key": "<key DO PASSO 4>" }
  ]
}
```

### Campos que devem ser alterados

| Campo | Obrigatório alterar? | Observação |
|---|---|---|
| `document_batch_key` | ✅ Sim | Valor retornado no Passo 2 |
| `refinanced_credit_operations[0].operation_key` | ✅ Sim | `key` do `debt_purchase` referenciado (Passo 4) |
| `collaterals[0].collateral_data.registration_code` | ✅ Sim | Matrícula SIAPE do servidor |
| `collaterals[0].collateral_data.authority_code` / `authority.description` / `authority.authority_document_number` | ✅ Sim | Órgão pagador (UPAG) |
| `portability_data.start_date` | ✅ Sim | Data de início do contrato de origem |
| `portability_data.control_number` | ✅ Sim | Número de controle no SIAPE |
| `portability_data.origin_contract.contract_number` | ✅ Sim | Nº do contrato na instituição vendedora |
| `portability_data.origin_contract.financial_institution_document_number` | ✅ Sim | CNPJ da instituição vendedora |
| `financial.installment_face_value` | 🚫 Não enviar | Valor da parcela (auto calculado) |
| `financial.rebates` | 🚫 Proibido | Seguro não é aceito em portabilidade — só no `refinancing` |

**Response Body**

```json
{
  "proposal_id": "<id interno>",
  "status": 200,
  "key": "<key da operação portability>",
  "data": {
    "credit_operation_key": "<mesmo valor de key>",
    "status": "waiting_signature"
  }
}
```

**Guarde a `key` desta portabilidade** — usada em `refinanced_credit_operations` do `refinancing` consolidador (Passo 5) no cenário β.

### Erros possíveis na criação

| Código | HTTP | Quando |
|---|---|---|
| `DOC000110` | 422 | `refinanced_credit_operations[].operation_key` não casa com nenhum `credit_operation_key` de `debt_purchase` já inserido no batch |
| `DOC000114` | 422 | `refinanced_credit_operations[].operation_key` já está em outra portabilidade do mesmo batch (duplicidade) |
| `COP000515` | 400 | `final_disbursement_amount` ≠ `0` — portabilidade não carrega troco |
| `COP000516` | 400 | `financial.rebates` presente — portabilidade federal não aceita seguro |

---

## 6. Emitir `refinancing` consolidador

CCB **mãe** que consolida as portabilidades num único instrumento. **Sempre obrigatória** no batch federal — tanto no cenário α (1 portabilidade) quanto no β (N portabilidades). É a única operação do fluxo que carrega **seguro** e **troco**.

ENDPOINT /debt
MÉTODO POST

:::info Particularidades do `refinancing` consolidador
- `reservation_type: "refinancing"` no `collateral_data`.
- `refinanced_credit_operations` lista as `key` de **todas** as portabilidades do batch.
- `disbursement_bank_account` aponta para a **conta externa do tomador** — destino do troco.
- `financial.rebates` é **opcional** — único lugar do fluxo que aceita seguro.
- `after_disbursement_actions` só é enviado **quando há seguro** — liquida o prêmio após o desembolso.
:::

:::caution `after_disbursement_actions` exige seguro
`after_disbursement_actions` só pode ser enviado no `refinancing` **quando a operação tem seguro** (`financial.rebates` presente). Enviar `after_disbursement_actions` sem `rebates` faz a QI Tech rejeitar o `POST /debt`.
:::

**Request Body**

**Sem seguro**

```json
{
  "borrower": { "...": "mesmo borrower" },
  "financial": {
    "first_due_date": "2026-06-10",
    "installment_face_value": 1000,
    "disbursement_date": "2026-05-10",
    "limit_days_to_disburse": 5,
    "number_of_installments": 20,
    "monthly_interest_rate": 0.017,
    "interest_type": "pre_price_days",
    "fine_configuration": {
      "monthly_rate": 0.01,
      "interest_base": "calendar_days",
      "contract_fine_rate": 0.02
    },
    "credit_operation_type": "ccb",
    "interest_grace_period": 0,
    "principal_grace_period": 0
  },
  "simplified": true,
  "collaterals": [
    {
      "percentage": 1,
      "collateral_type": "federal_payroll",
      "collateral_data": {
        "authority": {
          "description": "GOVERNO DO DISTRITO FEDERAL",
          "authority_document_number": "00.394.601/0001-26"
        },
        "authority_code": "99072",
        "reservation_type": "refinancing",
        "registration_code": "1393831",
        "reservation_method": "issuing",
        "pensioner_registration_code": ""
      }
    }
  ],
  "requester_identifier_key": "<UUIDv4>",
  "disbursement_bank_account": { "...": "conta externa do tomador" },
  "purchaser_document_number": "<CNPJ do comprador>",
  "document_batch_key": "<document_batch_key DO PASSO 2>",
  "refinanced_credit_operations": [
    { "operation_key": "<key da portabilidade 1>" },
    { "operation_key": "<key da portabilidade 2>" }
  ]
}
```

**Com seguro + troco (Cenário γ)**

```json
{
  "borrower": { "...": "mesmo borrower" },
  "financial": {
    "first_due_date": "2026-06-10",
    "installment_face_value": 1500,
    "disbursement_date": "2026-05-10",
    "limit_days_to_disburse": 5,
    "number_of_installments": 20,
    "monthly_interest_rate": 0.017,
    "interest_type": "pre_price_days",
    "fine_configuration": {
      "monthly_rate": 0.01,
      "interest_base": "calendar_days",
      "contract_fine_rate": 0.02
    },
    "credit_operation_type": "ccb",
    "interest_grace_period": 0,
    "principal_grace_period": 0,
    "rebates": [
      {
        "fee_type": "insurance_premium_qi",
        "description": "credit_insurance_blindado"
      }
    ]
  },
  "simplified": true,
  "collaterals": [
    {
      "percentage": 1,
      "collateral_type": "federal_payroll",
      "collateral_data": {
        "authority": {
          "description": "GOVERNO DO DISTRITO FEDERAL",
          "authority_document_number": "00.394.601/0001-26"
        },
        "authority_code": "99072",
        "reservation_type": "refinancing",
        "registration_code": "1393831",
        "reservation_method": "issuing",
        "pensioner_registration_code": ""
      }
    }
  ],
  "requester_identifier_key": "<UUIDv4>",
  "disbursement_bank_account": { "...": "conta externa do tomador" },
  "purchaser_document_number": "<CNPJ do comprador>",
  "document_batch_key": "<document_batch_key DO PASSO 2>",
  "refinanced_credit_operations": [
    { "operation_key": "<key da portabilidade 1>" },
    { "operation_key": "<key da portabilidade 2>" }
  ],
  "after_disbursement_actions": [
    {
      "action_type": "bankslip_payment",
      "action_data": {
        "qr_code": null,
        "destination": null,
        "digitable_line": "03399199530490000005237385601010297590005474921",
        "pix_transfer_type": null,
        "transaction_amount": 0
      }
    }
  ]
}
```

### Campos que devem ser alterados

| Campo | Obrigatório alterar? | Observação |
|---|---|---|
| `document_batch_key` | ✅ Sim | Valor retornado no Passo 2 |
| `refinanced_credit_operations` | ✅ Sim | **Todas** as `key` das portabilidades emitidas no Passo 5 |
| `collaterals[0].collateral_data.authority.*` / `authority_code` / `registration_code` | ✅ Sim | Conforme órgão e servidor |
| `reservation_method` | ✅ Sim | Sempre `"issuing"` para o consolidador |
| `disbursement_bank_account` | ✅ Sim | **Conta externa do tomador** — destino do troco |
| `financial.rebates` | ⚠️ Opcional | Único lugar do fluxo que aceita seguro. Incluir `[{ "fee_type": "insurance_premium_qi", ... }]` apenas se a operação tem seguro |
| `financial.final_disbursement_amount` | 🚫 Não enviar | Valor final do desembolso (troco) calculado automaticamente baseado no valor da parcela |
| `after_disbursement_actions` | ⚠️ Só com seguro | Liquida o prêmio do seguro após desembolso. **Só envie quando `rebates` está presente** — caso contrário a QI Tech rejeita o `POST /debt` |

### Erros possíveis na criação

| Código | HTTP | Quando |
|---|---|---|
| `DOC000109` | 422 | Batch já contém outro `refinancing` — só 1 por batch |
| `DOC000112` | 422 | `refinanced_credit_operations[].operation_key` não casa com nenhum `credit_operation_key` de portabilidade no batch |
| `COP000517` | 400 | `refinancing` **com** seguro (`rebates`) sem nenhuma `after_disbursement_actions` — seguro exige ao menos uma ação pós-desembolso |
| `COP000518` | 400 | `refinancing` **sem** seguro carregando `after_disbursement_actions` — só permitido quando há `rebates` |

---

## 7. Enviar para assinatura

Fecha o lote e dispara os documentos para o QI Sign. **Antes desse PUT, nada é enviado ao servidor.**

ENDPOINT /document/document_batch/DOCUMENT_BATCH_KEY/send_to_signature
MÉTODO PUT

Body: `{}`. Response: **HTTP 200**.

### Erros possíveis no envio

| Código | HTTP | Quando |
|---|---|---|
| `DOC000108` | 422 | Batch contém mais de 1 `insurance_premium_term` |
| `DOC000109` | 422 | Batch contém mais de 1 `refinancing` |
| `DOC000110` | 422 | `portability` cujo `refinanced_op` não casa com nenhum `debt_purchase` no batch |
| `DOC000111` | 422 | Batch **sem** `refinancing` consolidador |
| `DOC000114` | 422 | `debt_purchase` referenciado por 0 ou mais de 1 portabilidade |

:::tip Conferir antes de enviar
Use `GET /document/document_batch/DOCUMENT_BATCH_KEY` para listar os documentos agrupados e confirmar a composição antes do `send_to_signature`. Ver [Assinatura em Lote](./11-assinatura-em-lote.md).
:::

→ Próximo passo: [Formalização](./05-formalizacao.md)

---

## Mapa consolidado de erros

| Código | HTTP | Ponto de disparo | Quando |
|---|---|---|---|
| `DOC000108` | 422 | criação + envio | Mais de 1 `insurance_premium_term` no batch |
| `DOC000109` | 422 | criação + envio | Mais de 1 `refinancing` no batch |
| `DOC000110` | 422 | criação + envio | `portability` com `refinanced_op` sem `debt_purchase` casado no batch |
| `DOC000111` | 422 | envio | Batch sem `refinancing` consolidador |
| `DOC000112` | 422 | criação | `refinancing` com `refinanced_op` sem portabilidade casada no batch |
| `DOC000114` | 422 | criação + envio | `debt_purchase` referenciado por ≠ 1 portabilidade (0 órfão ou ≥ 2 duplicado) |
| `COP000515` | 400 | criação (`portability`) | `final_disbursement_amount` ≠ `0` na portabilidade |
| `COP000516` | 400 | criação (`portability`) | `financial.rebates` enviado na portabilidade federal |
| `COP000517` | 400 | criação (`refinancing`) | `refinancing` com seguro sem nenhuma `after_disbursement_actions` |
| `COP000518` | 400 | criação (`refinancing`) | `refinancing` sem seguro carregando `after_disbursement_actions` |
| `DOC000128` | 400 | abertura do lote | `type` do `personal_document` não suporta o modo enviado (frente e verso × arquivo único) |
| `DOC000129` | 400 | abertura do lote | Jornada configurada para o requester não coleta documento de identificação |
| `DOC000130` | 400 | abertura do lote | `type` do `personal_document` fora dos tipos aceitos pela configuração do requester |
| `DOC000137` | 400 | abertura do lote | `document_key` do documento de identificação já vinculada a outro lote |
| `DOC000004` | 404 | abertura do lote | `document_key` do documento de identificação não encontrada (inclui arquivo de outro requester) |
| `DOC000049` | 400 | abertura do lote | Documento de identificação sem arquivo — upload não concluído |
| `QIT000004` | 403 | abertura do lote | `personal_document` enviado sem o header `SELECTED-AGENT` |

:::info Notas sobre erros recorrentes
- `DOC000110` dispara em **dois momentos**: na criação da portabilidade (validação imediata) e no envio (cobertura defensiva).
- `DOC000114` dispara em **dois momentos**: na criação da segunda portabilidade duplicada e no envio (cobre o `debt_purchase` órfão, i.e. `count = 0`).
- `DOC000111` dispara **apenas no envio** — não há validação na criação.
- Batches que **não** são `federal_payroll_external_batch` não disparam nenhuma das validações acima.
:::

---

## Glossário

| Termo | Significado |
|---|---|
| **CCB** | Cédula de Crédito Bancário — instrumento de dívida emitido pelo banco |
| **SIAPE** | Sistema Integrado de Administração de Recursos Humanos do Governo Federal — folha de pagamento dos servidores da União |
| **UPAG** | Unidade Pagadora — órgão da União que paga o salário do servidor (identificado por `authority_code` + `authority_document_number`) |
| **matrícula SIAPE** | `registration_code` — identificador do servidor na folha |
| **portability_data** | Dados do contrato de origem na instituição vendedora (`start_date`, `control_number`, `contract_number`, `financial_institution_document_number`) |
| **credit_operation_key** | Chave única da operação retornada por `POST /debt` — também chamada `key` |
| **insurance_premium_term** | Documento extra gerado automaticamente no batch quando uma `portability` ou `refinancing` carrega `financial.rebates` com `fee_type: "insurance_premium_qi"`. **Nunca** originado de `debt_purchase` |
| **QI Sign** | Provedor de assinatura digital QI Tech (configurado via `certifier_type: "qi_sign"`) |

---

# Webhooks

URL: /documentation/siape/webhooks

Eventos assíncronos emitidos pela QI Tech durante o ciclo de vida da operação consignada SIAPE. Todos seguem o protocolo unificado de [Webhooks QI](/documentation/webhooks/notificacoes_baas_e_laas) — 5 segundos pra resposta HTTP 200 com `encoded_body` assinado, 3 retries de 5 minutos em caso de falha.

:::danger Atenção!
Os webhooks da QI Tech **não devem ser mapeados de forma restrita**. Campos adicionais podem ser incluídos aos payloads a qualquer momento. Use desserialização permissiva.
:::

## Webhooks específicos do produto SIAPE

| Webhook | Quando dispara | Origem |
|---|---|---|
| `federal_payroll.balance` | Resultado da consulta de margem (`succeeded` ou `failure`) | federal-payroll-api |
| `credit_operation.collateral` | Averbação ou desaverbação no SIGEPE | credit-operation-api |
| `credit_transfer.received_portability` | Portabilidade externa recebida (banco origem aceitou) | credit-transfer-api |
| `credit_transfer_status_change` | Atualização do credit-transfer | credit-transfer-api |

## Webhooks comuns LaaS

| Webhook | Status | Quando dispara |
|---|---|---|
| `debt` | `waiting_signature` | Operação criada, aguardando assinatura |
| `debt` | `signature_finished` | Assinatura concluída |
| `debt` | `disbursed` | Desembolso PIX/TED enviado |
| `debt` | `canceled` | Operação cancelada |
| `debt` | `canceled_permanently` | Cancelamento definitivo |
| `debt` | `settled` | Operação liquidada |
| `reversal` | `pending_fund` | Borrower pagou PIX QR de cancelamento — reversal iniciado |
| `installment.status_change` | `paid` / `overdue` / etc | Mudança de status de parcela individual |
| `laas.devolution.refund_receipt` | `refunded` | Devolução de overpayment via PIX |

## Estrutura padrão

```json
{
  "key": "<UUID da operação>",
  "data": ,
  "status": "<status>",
  "webhook_type": "<tipo>",
  "event_datetime": "2026-06-02 14:30:00"
}
```

## Exemplos

### `federal_payroll.balance` (sucesso)

```json
{
  "webhook_type": "federal_payroll.balance",
  "key": "81da8afb-e1b2-4215-8093-c4b5feab8a9f",
  "status": "succeeded",
  "data": {
    "balance_query": [
      {
        "available_balance": 3500.00,
        "authority_code": "17000",
        "registration_code": "1354387",
        "employment_relationship": "active",
        "consigned_credit": 1200.00,
        "consigned_card": 300.00
      }
    ]
  },
  "event_datetime": "2026-06-02 14:30:00"
}
```

### `credit_operation.collateral` (pending_consent)

```json
{
  "webhook_type": "credit_operation.collateral",
  "key": "27a099df-4688-43cb-87fa-515b1cf343a5",
  "status": "pending_consent",
  "data": {
    "collateral_constituted": false,
    "enumerator": "waiting_borrower_consent"
  },
  "event_datetime": "2026-06-02 15:00:00"
}
```

### `credit_operation.collateral` (success)

```json
{
  "webhook_type": "credit_operation.collateral",
  "key": "27a099df-4688-43cb-87fa-515b1cf343a5",
  "status": "success",
  "data": {
    "collateral_constituted": true,
    "enumerator": "successfully_reserved",
    "reservation_status": "reserved"
  },
  "event_datetime": "2026-06-02 15:30:00"
}
```

### `debt` (disbursed)

```json
{
  "webhook_type": "debt",
  "key": "27a099df-4688-43cb-87fa-515b1cf343a5",
  "status": "disbursed",
  "data": {
    "ted_receipt_list": [{
      "amount": 12500.00,
      "transaction_key": "...",
      "destination": { "name": "MARIA DOS SANTOS", "bank_ispb": "60746948" }
    }]
  },
  "event_datetime": "2026-06-02 16:00:00"
}
```

### `reversal` (cancelamento pós-desembolso)

```json
{
  "webhook_type": "reversal",
  "credit_operation_key": "2893b8bd-...",
  "contract_number": "0000049333/TW",
  "reversal": {
    "status": "pending_fund",
    "amount": 12500.00,
    "is_total": true,
    "is_operation_canceled": true,
    "reversal_key": "...",
    "date": "2026-09-06"
  }
}
```

## Cancel reasons (`cancel_reason_enumerator`)

| Enumerador | Significado |
|---|---|
| `manual` | Cancelado via API ou portal |
| `waiting_signature` | Não assinou no prazo |
| `not_collateral_constituted` | Averbação falhou (`consent_refused`, `consent_expired`, etc.) |
| `is_portability` | Portabilidade falhou |
| `pix_max_retry` | Muitas falhas no desembolso PIX |
| `lack_of_resource` | Sem recurso pra desembolsar |
| `kyc_not_accepted` | KYC reprovado |

→ Lista completa em [Mapa de Status](./08-mapa-de-status.md)

## Reenvio Manual

Webhooks podem ser consultados e reenviados via portal seguindo [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).

---

# Manual SRCC - Consulta de Condição da Operação

URL: /documentation/srcc/consulta_condicao_operacao

:::info Antes de começar
- [Introdução ao SRCC](/documentation/srcc/introducao)
:::

---

## 1. Consulta de condição da operação

Verifica se um CPF tem registro no SRCC em uma data. Esse registro pode ter vindo de uma liquidação antecipada, de uma portabilidade ou de um refinanciamento com redução da parcela.

Use essa consulta antes de decidir sobre a comissão do correspondente: quando o tomador quitou um contrato antes do prazo, uma nova operação feita em menos de 90 dias depois não gera comissão.

A resposta vem na hora, na própria requisição.

:::info Liberação do endpoint
O endpoint é liberado por integração. Peça a liberação ao seu contato na QI Tech.
:::

### Request

**GET**
/srcc/operation/operation_condition

**Exemplo**

```
GET /srcc/operation/operation_condition?issuer_document_number=96969879003&payroll_type=social_security&benefit_number=1234567890&reference_date=2026-08-31
```

**Query Params Details**

| Campo | Tipo | Obrigatório | Descrição |
|-------|------|-------------|-----------|
| issuer_document_number | string | Sim | CPF do tomador, com 11 dígitos e sem pontuação |
| payroll_type | string | Sim | Tipo de empregador: `social_security`, `public` ou `private` |
| benefit_number | string | Só quando `payroll_type` é `social_security` | Número do benefício do INSS, apenas dígitos, no máximo 10 |
| reference_date | string | Não | Data usada na consulta, no formato `YYYY-MM-DD`. Se não for enviada, usamos a data de hoje |

:::caution Número do benefício
O `benefit_number` só existe para `social_security`, e é pedido só nesse caso. Quando o tipo de empregador é `public` ou `private`, não envie o campo.
:::

### Response

STATUS
**200** (OK)

**Payload**

```json
{
    "issuer_document_number": "96969879003",
    "payroll_type": "social_security",
    "benefit_number": "1234567890",
    "reference_date": "2026-08-31",
    "has_restriction": true
}
```

**Response Body Details**

| Campo | Tipo | Descrição |
|-------|------|-----------|
| issuer_document_number | string | CPF consultado |
| payroll_type | string | Tipo de empregador usado na consulta |
| benefit_number | string | Número do benefício enviado ao SRCC, completado com zeros à esquerda até 10 dígitos. Vem `null` quando o tipo de empregador não é `social_security` |
| reference_date | string | Data usada na consulta |
| has_restriction | boolean | `true` quando o CPF tem registro no SRCC nessa data |

---

## 2. Como ler o resultado

| Valor | Significado |
|-------|-------------|
| `has_restriction: true` | O CPF tem registro no SRCC nessa data, e a operação não gera comissão. |
| `has_restriction: false` | O CPF não tem registro no SRCC nessa data. |

:::caution
O `true` não diz **qual** evento gerou o registro. Pode ter sido liquidação antecipada, portabilidade ou refinanciamento com redução da parcela. A consulta também não devolve a data do evento, e o prazo de 90 dias é aplicado pelo próprio SRCC em relação à data que você enviou.
:::

Para conferir uma data passada, como a data em que uma operação já contratada foi feita, envie essa data em `reference_date`. A consulta sempre olha para a data enviada, não para a data de hoje.

---

## 3. Erros

| Código HTTP | Código QI | O que aconteceu |
|-------------|-----------|-----------------|
| 400 | `SRCC00007` | Faltou um parâmetro obrigatório |
| 400 | `SRCC00008` | Um parâmetro foi enviado com valor ou formato inválido |
| 401/403 | (padrão) | Headers de autenticação ausentes ou inválidos |
| 502 | `SRCC00009` | O SRCC não aceitou a consulta ou respondeu de forma inesperada |

Nos dois erros de 400, o campo `translation` diz qual parâmetro está com problema e o que fazer para corrigir.

### 3.1. SRCC00007 — faltou um parâmetro

| O que faltou | O que vem em `translation` |
|--------------|----------------------------|
| `issuer_document_number` | O parametro 'issuer_document_number' nao foi enviado. Ele deve conter o CPF do tomador, com 11 digitos e sem pontuacao. |
| `payroll_type` | O parametro 'payroll_type' nao foi enviado. Os valores aceitos sao 'social_security' para INSS, 'public' para servidor publico e 'private' para trabalhador de empresa privada. |
| `benefit_number`, com `payroll_type=social_security` | O parametro 'benefit_number' nao foi enviado. Ele e obrigatorio quando 'payroll_type' e 'social_security' e deve conter o numero do beneficio do INSS. |

**Exemplo**

Consulta de INSS sem o número do benefício:

```
GET /srcc/operation/operation_condition?issuer_document_number=96969879003&payroll_type=social_security
```

```json
{
    "code": "SRCC00007",
    "title": "Bad Request",
    "description": "Query param 'benefit_number' was not sent. It is required when 'payroll_type' is 'social_security' and must contain the INSS benefit number.",
    "translation": "O parametro 'benefit_number' nao foi enviado. Ele e obrigatorio quando 'payroll_type' e 'social_security' e deve conter o numero do beneficio do INSS."
}
```

### 3.2. SRCC00008 — parâmetro com valor inválido

| O que você enviou | O que vem em `translation` |
|-------------------|----------------------------|
| `issuer_document_number=969.698.790-03` | O parametro 'issuer_document_number' deve ser um CPF com exatamente 11 digitos e sem pontuacao. |
| `payroll_type=other` | O parametro 'payroll_type' recebeu um valor que nao existe. Os valores aceitos sao 'social_security' para INSS, 'public' para servidor publico e 'private' para trabalhador de empresa privada. |
| `benefit_number=123.456.789-0` | O parametro 'benefit_number' deve conter apenas digitos, no maximo 10. |
| `reference_date=31/08/2026` | O parametro 'reference_date' deve ser uma data no formato 'YYYY-MM-DD'. |

**Exemplo**

Consulta com o CPF formatado:

```
GET /srcc/operation/operation_condition?issuer_document_number=969.698.790-03&payroll_type=private
```

```json
{
    "code": "SRCC00008",
    "title": "Bad Request",
    "description": "Query param 'issuer_document_number' must be a CPF with exactly 11 digits and no punctuation.",
    "translation": "O parametro 'issuer_document_number' deve ser um CPF com exatamente 11 digitos e sem pontuacao."
}
```

### 3.3. SRCC00009 — problema no SRCC

Nesse caso não há nada errado na sua requisição: o problema está no SRCC ou na comunicação com ele. Tente de novo em alguns minutos e, se continuar, abra um ticket com a QI Tech.

**Exemplo**

```json
{
    "code": "SRCC00009",
    "title": "Bad Gateway",
    "description": "SRCC did not accept the consult or answered in an unexpected format, so the result could not be read. Nothing is wrong with your request. Retry in a few minutes and open a ticket with QI Tech if it keeps happening.",
    "translation": "O SRCC nao aceitou a consulta ou respondeu em um formato inesperado, e nao foi possivel ler o resultado. Nao ha nada errado na sua requisicao. Tente novamente em alguns minutos e abra um ticket com a QI Tech se continuar acontecendo."
}
```

:::info Acentuação
As mensagens em `translation` são enviadas sem acento. Não é erro de digitação, é o formato padrão das nossas respostas de erro.
:::

:::danger Aviso Importante!
Não use dados pessoais reais, como CPF e número de benefício, no ambiente de sandbox.
:::

---

# Manual SRCC - Introdução

URL: /documentation/srcc/introducao

:::info Próximo passo
- [Consulta de Condição da Operação](/documentation/srcc/consulta_condicao_operacao)
:::

---

## 1. O que é o SRCC

O SRCC (Serviço de Registro de Crédito Consignado) é um registro central de operações de crédito consignado, mantido pela [Núclea](https://www.nuclea.com.br/registro-de-credito-consignado/).

Os bancos que aderiram às regras do consignado, criadas em 2021 pela FEBRABAN e pela ABBC, registram ali alguns eventos das operações que fazem. Qualquer um desses bancos pode consultar o registro depois.

## 2. O que fica registrado

| Evento | Quando acontece |
|--------|-----------------|
| Portabilidade | O contrato passa para outro banco. |
| Refinanciamento | O contrato é refinanciado com redução da parcela. |
| Liquidação antecipada | O contrato é quitado antes do prazo. |

Cada registro fica ligado ao CPF do tomador e ao tipo de empregador que desconta as parcelas na folha.

## 3. Para que serve a consulta

Uma das regras do consignado trata da comissão do correspondente bancário: se o tomador quitou um contrato antes do prazo, uma nova operação feita em menos de **90 dias** depois dessa quitação não gera comissão.

A consulta ao SRCC é o que responde essa pergunta. Você envia o CPF, o tipo de empregador e uma data. A resposta diz se aquele CPF tem registro no SRCC naquela data.

:::info
Os eventos registrados e o prazo de 90 dias são definidos pelas regras do consignado e pelos manuais do SRCC publicados pela Núclea. A QI Tech faz a consulta e traduz a resposta, sem mudar o critério.
:::

## 4. Tipos de empregador

O SRCC separa o tomador pelo tipo de empregador, ou seja, por quem desconta as parcelas na folha:

| Valor | Descrição |
|-------|-----------|
| `social_security` | INSS: aposentados e pensionistas. |
| `public` | Servidor público federal, estadual ou municipal. |
| `private` | Trabalhador de empresa privada (CLT). |

---

# Aprovar Transferência

URL: /documentation/ted/2fa/aprovar_transferencia

Para realizar uma transferência via TED é necessário realizar a seguinte chamada:

1. [Solicitação de token de validação de transferência](/documentation/ted/2fa/solicitar_transferencia): /baas/token_request

2. Aprovação da transferência /baas/movement_validation

:::info
As transferências TED só podem ser realizadas em dias úteis das **7:00** às **17:00**.
:::

## Request

ENDPOINT /baas/token_request
MÉTODO POST

Request Body

```json
{
	"token": "329329",
	"agent_document_number": "99999999999",
	"movement_payload": {
		"source_account": {
			"account_branch": "0001",
			"account_number": "0000000",
			"account_digit": "0",
			"owner_document_number": "99999999000107"
		},
		"target_account": {
			"financial_institution_code": "341",
			"account_branch": "0001",
			"account_number": "0000000",
			"account_digit": "1",
			"owner_document_number": "999999999",
			"owner_name": "Nome do Titular da Conta Destino"
		},
		"transaction_amount": 8.86,
        "approver_document_number": "999999999"
	}
}

```

## Body Params
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `token` * | string | Token de autenticação | 6 |
| `agent_document_number` * | string | CPF do usuário que irá receber o token. (Apenas números) | 11 | 
| `movement_payload` | Object | Payload contendo as informações da transferência | **[Objeto movement_payload](#objeto-movement_payload)** | 

### Objeto movement_payload

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `source_account` * | Object | Objeto contendo os dados da conta de origem | **[Objeto source_account](#objeto-source_account)** |
| `target_account` * | Object | Objeto contendo os dados da conta de destino | **[Objeto target_account](#objeto-target_account)** |
| `transaction_amount` * | float | Valor da transferência | - |
| `approver_document_number` * | string | CPF do usuário que irá receber o token. (Apenas números) | - |

### Objeto source_account

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `account_branch` * | string | Número Agência. | 0 |
| `branch_digit` |string | Dígito da Agência.| 0 |
| `account_digit` * | string | Dígito da conta.| 0 |
| `account_number` * | string | Número da conta.| 0 | 
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta.| 0 |

### Objeto target_account

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `account_branch` * | string | Agência. | 10 |
| `account_digit` * | string | Dígito da conta | 10 |
| `account_number` * | string | Número da conta. | 10 |
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta. | 10 |
| `owner_name` * | string | Nome do titular da conta. | 10 |
| `account_type` * |string |  CPF ou CNPJ (apenas números) do titular da conta.| 10 |
| `ispb` | string |  Código de oito dígitos que identifica os bancos no sistema de transferência de reserva do Banco Central.| 10 |

## Response

:::info
O campo de “***transacted_at***“ está em formato UTC.
:::

:::info
A “***transaction_key***“ será utilizada posteriormente para solicitação do comprovante de transferência.
:::

STATUS 200

Response Body

```json
{
	"authentication_code": "e8f0fffaeb4ebad2df0417194fe6a9e5",
	"origin_key": "d07f77f9-f157-4c35-a26b-567cba59e385",
	"pdf_encoded_string": "\<BASE 64 DO COMPROVANTE\>",
	"source_account": {
		"account_branch": "0001",
		"account_digit": "2",
		"account_number": "2359934",
		"financial_institution_compe_number": 329,
		"financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
		"owner_document_number": "09080702000105",
		"owner_document_number_formatted": "09.080.702/0001-05",
		"owner_name": "VOVO LUCIA CONVENIENCIA LTDA"
	},
	"source_subtype": "withdrawal",
	"source_subtype_translation_ptbr": "Transferência",
	"target_account": {
		"account_branch": "0001",
		"account_digit": "1",
		"account_number": "81156",
		"account_type": "checking_account",
		"account_type_str": "Conta Corrente",
		"financial_institution_compe_number": "001",
		"financial_institution_name": "Banco do Brasil S.A.",
		"owner_document_number": "10932327656",
		"owner_document_number_formatted": "109.323.276-56",
		"owner_name": "Lucas de Jesus Clarim"
	},
	"transacted_at": "2022-09-02 14:39:56",
	"transacted_at_br": "2022-09-02 11:39:56",
	"transacted_at_br_formatted": "21/11/2022, 11:39:56",
	"transacted_at_formatted": "21/11/2022, 14:39:56",
	"transaction_amount": 550,
	"transaction_amount_formatted": "R$ 550,00",
	"transaction_key": "32ac0781-f292-4172-b58f-3310102e6fb9"
}

```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}
```

---

# Solicitar Transferência

URL: /documentation/ted/2fa/solicitar_transferencia

Para realizar uma transferência via TED é necessário realizar a seguinte chamada:

1. Solicitação de token de validação de transferência: /baas/token_request

2. [Aprovação da transferência](/documentation/ted/2fa/aprovar_transferencia) /baas/movement_validation

:::info
As transferências TED só podem ser realizadas em dias úteis das **7:00** às **17:00**.
:::

## Request

ENDPOINT /baas/token_request
MÉTODO POST

Request Body

```json
{
	"contact_type": "sms",
	"agent_document_number": "99999999999",
	"movement_payload": {
		"source_account": {
			"account_branch": "0001",
			"account_number": "0000000",
			"account_digit": "0",
			"owner_document_number": "99999999000107"
		},
		"target_account": {
			"financial_institution_code": "341",
			"account_branch": "0001",
			"account_number": "0000000",
			"account_digit": "1",
			"owner_document_number": "999999999",
			"owner_name": "Nome do Titular da Conta Destino"
		},
		"transaction_amount": 8.86,
        "approver_document_number": "999999999"
	}
}

```

### Body Params
| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `contact_type` * | string | Forma de envio do token de autenticação,  podendo ser via E-mail (“email”) ou SMS (“sms”)| 10 |
| `agent_document_number` * | string | CPF do usuário que irá receber o token. (Apenas números) | 11 | 
| `movement_payload` | Object | Payload contendo as informações da transferência | **[Objeto movement_payload](#objeto-movement_payload)** | 

### Objeto movement_payload

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `source_account` * | Object | Objeto contendo os dados da conta de origem | **[Objeto source_account](#objeto-source_account)** |
| `target_account` * | Object | Objeto contendo os dados da conta de destino | **[Objeto target_account](#objeto-target_account)** |
| `transaction_amount` * | float | Valor da transferência | - |
| `approver_document_number` * | string | CPF do usuário que irá receber o token. (Apenas números) | - |

### Objeto source_account

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `account_branch` * | string | Número Agência. | 0 |
| `branch_digit` |string | Dígito da Agência.| 0 |
| `account_digit` * | string | Dígito da conta.| 0 |
| `account_number` * | string | Número da conta.| 0 | 
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta.| 0 |

### Objeto target_account

| Campo | Tipo | Descrição | Caracteres |
|---|---| ---| ---|
| `account_branch` * | string | Agência. | 10 |
| `account_digit` * | string | Dígito da conta | 10 |
| `account_number` * | string | Número da conta. | 10 |
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta. | 10 |
| `owner_name` * | string | Nome do titular da conta. | 10 |
| `account_type` * |string |  CPF ou CNPJ (apenas números) do titular da conta.| 10 |
| `ispb` | string |  Código de oito dígitos que identifica os bancos no sistema de transferência de reserva do Banco Central.| 10 |

## Response

STATUS 200

Response Body

```json
{}

```

STATUS 400

Response Body

```json
{
  "data": "{\"title\": \"Bad Request\", \"description\": \"Invalid request body.\", \"translation\": \"Corpo da requisição inválido.\", \"extra_fields\": {}, \"code\": \"LEG000069\"}"
}

```

---

# TED

URL: /documentation/ted/ted_v2

## Realizar TED

O recebimento de uma transação TED não é instantânea no sistema financeiro nacional. Ao realizar uma transação TED no
sistema QI uma resposta imediata será retornada informando erro, rejeição ou aceite da transferencia. Mesmo que uma
transferência tenha sido colocada em `sent`, a Instituição Financeira recebedora pode recusar a entrada de
recurso e
realizar a devolução do valor. Neste caso um novo webhook com status de `rejected` será enviado e o motivo da rejeição
retornado no campo `refusal_reason`.

Débitos na conta fonte da transação serão realizados imediatamente. Isso não significa que o valor foi creditado na
conta destino devido aos princípios de transações TED descritos acima. Caso ocorra a rejeição da transação enviada, o
valor da transação será creditado novamente à conta fonte.

### Request

ENDPOINT /account/ ACCOUNT_KEY /ted
MÉTODO POST

Request Body

```json
{
  "target_account": {
    "account_branch": "0001",
    "account_number": "92796",
    "account_digit": "1",
    "owner_document_number": "23599885000192",
    "owner_name": "Titular da Conta",
    "ispb": "12345678",
    "account_type": "checking_account"
  },
  "transaction_amount": 8.86,
  "request_control_key": "048c8ee5-1c91-46a6-952e-7e5c27c21f20"
}
```

### Body Params

| Campo                   | Tipo   | Descrição                                                                          | Caracteres                                          |
|-------------------------|--------|------------------------------------------------------------------------------------|-----------------------------------------------------|
| `request_control_key` * | string | Chave única de identificação da request utilizada pelo cliente no formato uuid v4. | 36                                                  |
| `target_account` *      | object | Conta de destino                                                                   | **[Objeto target_account](#objeto-target_account)** | 
| `transaction_amount` *  | float  | Valor da transferência                                                             | 10                                                  |

### Objeto target_account

| Campo                     | Tipo   | Descrição                                           | Caracteres                                                |
|---------------------------|--------|-----------------------------------------------------|-----------------------------------------------------------|
| `account_branch` *        | string | Agência.                                            | 4                                                         |
| `account_digit` *         | string | Dígito da conta                                     | 1                                                         |
| `account_number` *        | string | Número da conta.                                    | 20                                                        |
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta.   | 14                                                        |
| `owner_name` *            | string | Nome do titular da conta.                           | 50                                                        |
| `account_type`*           | string | Tipo da conta.                                      | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string | Base no CNPJ da instituição financeira (8 dígitos). | 8                                                         |

### Enumerador account_type

| Enumerador         | Tradução              |
|--------------------|-----------------------|
| checking_account   | conta corrente        |
| deposit_account    | conta depósito        |
| guaranteed_account | conta de garantia     |
| investment_account | conta de investimento |
| payment_account    | conta de pagamento    |
| saving_account     | conta poupança        |

### Response

STATUS 201

Response Body

```json
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "created_at": "2021-10-22T20:30:23.459Z",
  "ted_status": "sent",
  "transaction_amount": 126.97,
  "fee_amount": 0.0,
  "transaction_key": "8ea90347-330d-4b3a-8ebb-2ac217ad6eb3"
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`                                 | Descrição (eng)<br/>`description`                                                                                       | Descrição (ptbr)<br/>`translation`                                                                                     |
|--------------------------|----------------------|----------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
| 400                      | QIT000001            | Bad Request                                        | Schema Error                                                                                                            | Erro de Schema                                                                                                         |
| 400                      | TED000XXX            | request_control_key must be a valid uuid v4 string | request_control_key was not accepted for not being a valid uuid v4 string                                               | request_control_key não foi aceito por não ser uma palavra uuid v4 válida                                              |
| 400                      | TED000XXX            | Invalid Transaction Amount                         | Transaction amount of \{transaction_amount\} is not valid. It must be a positive value with at maximum 2 decimal places | O valor de transação \{transaction_amount\} não é válido. Deve ser um valor positivo com no máximo duas casas decimais |
| 404                      | TED000XXX            | Account not found                                  | Account not found for: \{account_datum\}                                                                                | Conta não encontrada para: \{account_datum\}                                                                           |
| 400                      | TED000XXX            | Account is Closed                                  | Account \{account_key\} is closed.                                                                                      | Conta \{account_key\} está fechada.                                                                                    |
| 400                      | TED000XXX            | Account is Blocked                                 | Account \{account_key\} is blocked.                                                                                     | Conta \{account_key\} está bloqueada.                                                                                  |
| 403                      | TED000XXX            | User is not allowed to do this transaction         |                                                                                                                         | Usuário não tem autorização para fazer essa transação                                                                  |
| 400                      | TED000XXX            | Target Account may not receive resources           | Target account is currently unavailable o receive resorses                                                              | Conta destino está impedida de receber recursos                                                                        |
| 400                      | TED000XXX            | Bad Request                                        | Insufficient account balance for transfer and fee amount.                                                               | Saldo de conta insuficiente para a transferência e a taxa.                                                             |
| 400                      | TED000XXX            | Bad Request                                        | Billing account closed or blocked                                                                                       | Conta de cobrança encerrada ou bloqueada                                                                               |
| 400                      | TED000XXX            | Bad Request                                        | Insufficient billing account balance for fee.                                                                           | Saldo de conta de cobrança insuficiente para a taxa.                                                                   |
| 400                      | TED000XXX            | Bad Request                                        | Transaction amount is over limit.                                                                                       | O total da transferência é superior ao limite.                                                                         |
| 400                      | TED000XXX            | Bad Request                                        | Insufficient account balance for transfer and fee amount.                                                               | Saldo de conta insuficiente para a transferência e a taxa                                                              |
| 400                      | TED000XXX            | Bad Request                                        | request_control_key \{request_control_key\} already in use                                                              | request_control_key \{request_control_key\} já utilizada                                                               |
| 400                      | TED000XXX            | Invalid Target Account Number                      | Target account number is invalid                                                                                        | Número da conta de destino é inexistente ou inválido                                                                   |
| 400                      | TED000XXX            | Invalid Target Account Document Number             | Target account document is invalid                                                                                      | Número de documento enviado é inválido                                                                                 |
| 400                      | TED000XXX            | Unrelated Beneficiary Document Number              | Target account document is not the same as sent                                                                         | Número de documento da conta de destino diferente do enviado                                                           |
| 400                      | TED000XXX            | Blocked Target Account                             | Target account is blocked.                                                                                              | A conta de destino encontra-se bloqueada.                                                                              |
| 400                      | TED000XXX            | Closed Target Account                              | Target account is closed.                                                                                               | A conta de destino encontra-se encerrada.                                                                              |
| 400                      | TED000XXX            | Rejected Payment Order                             | Transaction refused by target                                                                                           | Transação rejeitada por recebedor.                                                                                     |

[//]: # (Break here for new page -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------)

## Consultar Transação TED

### Request

ENDPOINT /account/ ACCOUNT_KEY /ted/ TED_KEY / TED_DIRECTION
MÉTODO GET

### Request Path Params

| Campo             | Tipo   | Descrição                                                   | Caracteres                                                  |
|-------------------|--------|-------------------------------------------------------------|-------------------------------------------------------------|
| `ted_direction` * | string | Filtro para indicar se uma transação é de entrada ou saída. | **[Enumerador ted_direction](#enumeradores-ted_direction)** |
| `account_key` *   | uuidv4 | Chave única de identificação da conta QI                    | 36                                                          |
| `ted_key` *       | uuidv4 | Chave única de identificação da transferência TED           | 36                                                          |

### Enumeradores ted_direction

| Enumerador | Tradução |
|------------|----------|
| incoming   | entrada  |
| outgoing   | saída    |

:::caution Atenção
Será apenas permitida a visualização de uma transferência caso o requisitante tenha permissões na conta de saída da
transação para o caso da ted_direction de outgoing ou tenha permissões na conta de entrada da
transação para o caso da ted_direction de incoming. Caso o contrário um erro de não encontrado será retornado.
:::

### Response

STATUS 200

Response Body: Transferência Rejeitada (outgoing)

```json
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "created_at": "2021-10-22T20:30:23.459Z",
  "ted_status": "rejected",
  "transaction_amount": 126.97,
  "fee_amount": 0.0,
  "target_account": {
    "account_branch": "0001",
    "account_digit": "6",
    "account_number": "78340",
    "ispb": "12345678",
    "owner_document_number": "32402502000135",
    "owner_name": "QI Tech"
  },
  "refusal_reason": {
    "refusal_code": 1,
    "enumerator": "conta_destinatario_encerrada",
    "description": "Conta Destinatária do Crédito Encerrada"
  }
}
```

Response Body: Transferência Enviada (outgoing)

```json
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "created_at": "2021-10-22T20:30:23.459Z",
  "ted_status": "sent",
  "transaction_amount": 126.97,
  "fee_amount": 0.0,
  "target_account": {
    "account_branch": "0001",
    "account_digit": "6",
    "account_number": "78340",
    "ispb": "12345678",
    "owner_document_number": "32402502000135",
    "owner_name": "QI Tech"
  },
  "refusal_reason": {}
}
```

Response Body: Transferência Recebida (incoming)

```json
{
  "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
  "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
  "created_at": "2021-10-22T20:30:23.459Z",
  "ted_status": "received",
  "transaction_amount": 126.97,
  "fee_amount": 0.0,
  "source_account": {
    "account_branch": "0001",
    "account_digit": "6",
    "account_number": "78340",
    "ispb": "12345678",
    "owner_document_number": "32402502000135",
    "owner_name": "QI Tech"
  },
  "refusal_reason": {}
}
```

STATUS 4xx

Response Body: Error

```json
{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}
```

| Código HTTP<br/>`status` | Código QI<br/>`code` | Título<br/>`title`     | Descrição (eng)<br/>`description` | Descrição (ptbr)<br/>`translation`                                     |
|--------------------------|----------------------|------------------------|-----------------------------------|------------------------------------------------------------------------|
| 404                      | TED000XXX            | Outgoing TED Not Found | Ted key \{ted_key\} was not found | Transferência Ted de saída com chave \{ted_key\} não foi encontrada.   |
| 404                      | TED000XXX            | Incoming TED Not Found | Ted key \{ted_key\} was not found | Transferência Ted de entrada com chave \{ted_key\} não foi encontrada. |

[//]: # (Break here for new page -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------)

## Consultar Transações TED

### Request

ENDPOINT /account/ ACCOUNT_KEY /teds
MÉTODO GET

### Path Params

| Campo           | Tipo   | Descrição                                | Caracteres |
|-----------------|--------|------------------------------------------|------------|
| `account_key` * | uuidv4 | Chave única de identificação da conta QI | 36         |

### Query Params

| Campo                 | Tipo       | Descrição                                                                                                  | Caracteres                                                                  |
|-----------------------|------------|------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------|
| `ted_direction`       | enumerator | Indicador do sentido da transação (entrada ou saída). Caso não seja enviado, **outgoing** será considerado | [Enumeradores ted_transfer_direction](#enumeradores-ted_transfer_direction) |
| `request_control_key` | uuidv4     | Chave única de identificação da request utilizada pelo cliente.                                            | 36                                                                          |
| `date_from`           | string     | Data inicial. Formato "YYYY-MM-DD"                                                                         |                                                                             |
| `date_to`             | string     | Data final. Formato "YYYY-MM-DD"                                                                           |                                                                             |
| `page`                | integer    | Número da página requisitada. 1 por padrão                                                                 |                                                                             |
| `page_size`           | integer    | Tamanho da página requisitada na consulta. 30 por padrão e valor máximo                                    | Valor máximo de 30                                                          |

### Enumeradores ted_transfer_direction

| Enumerador   | Descrição                    |
|--------------|------------------------------|
| **incoming** | Transferência TED de entrada |
| **outgoing** | Transferência TED de saída   |

### Response

STATUS 201

Response Body

```json
{
  "data": [
    {
      "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
      "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
      "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
      "created_at": "2021-10-22T20:30:23.459Z",
      "ted_status": "sent",
      "transaction_amount": 126.97,
      "fee_amount": 0.0,
      "target_account": {
        "account_branch": "0001",
        "account_digit": "6",
        "account_number": "78340",
        "ispb": "12345678",
        "owner_document_number": "32402502000135",
        "owner_name": "QI Tech"
      },
      "refusal_reason": {}
    }
  ],
  "pagination": {
    "current_page": 1,
    "rows_per_page": 30
  }
}

```

[//]: # (Break here for new page -----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------)

## Webhook após finalização de envio de TED

Webhook informará caso uma transação TED tenha sido devolvida.

### Webhook Request Body

**Webhook Body: TED Rejeitada**

```json
{
  "webhook_type": "baas.ted.outgoing_ted",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
    "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
    "created_at": "2021-10-22T20:30:23.459Z",
    "ted_status": "sent",
    "transaction_amount": 126.97,
    "fee_amount": 0.0,
    "target_account": {
      "account_branch": "0001",
      "account_digit": "6",
      "account_number": "78340",
      "ispb": "12345678",
      "owner_document_number": "32402502000135",
      "owner_name": "QI Tech"
    },
    "refusal_reason": {
      "refusal_code": 1,
      "enumerator": "conta_destinatario_encerrada",
      "description": "Conta Destinatária do Crédito Encerrada"
    }
  }
}
```

### Webhook Body Param

| Campo                 | Tipo   | Descrição                                                                         | Max. Caracteres                                     |
|-----------------------|--------|-----------------------------------------------------------------------------------|-----------------------------------------------------|
| `webhook_type`        | string | Um enumerador que define o tipo de evento sendo reportado                         | 23                                                  |
| `webhook_datetime`    | string | Data e hora do envio do webhook                                                   | 20                                                  |
| `request_control_key` | string | Chave única de identificação da request utilizada pelo cliente no formato uuid v4 | 36                                                  | 
| `ted_key`             | string | Chave única de identificação da transferência TED                                 | 36                                                  |
| `created_at`          | string | Data e hora de criação da transação                                               | 24                                                  |
| `ted_status`          | string | Status da transação TED                                                           | **[Enumerador ted_status](#enumerador-ted_status)** |
| `transaction_amount`  | number | Valor da transferência                                                            | 10                                                  |
| `fee_amount`          | number | Valor da taxca cobrada pela transferencia                                         | 35                                                  |
| `target_account`      | Object | Conta destino - Só deve ser enviada em transações do tipo "manual"                | **[Objeto target_account](#objeto-target_account)** |
| `refusal_reason`      | Object | Motivo da recusa de acordo com o padrão do Banco Central                          | **[Objeto refusal_reason](#objeto-refusal_reason)** |

### Enumerador ted_status

| Enumerador   | Descrição                                |
|--------------|------------------------------------------|
| **sent**     | Transferência TED realizada com sucesso. |
| **pending**  | Transferência TED pendente.              |
| **rejected** | Transferência TED rejeitada.             |
| **returned** | Transferência TED devolvida.             |

### Objeto target_account

| Campo                     | Tipo   | Descrição                                           | Caracteres                                              |
|---------------------------|--------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string | Agência.                                            | 4                                                       |
| `account_digit` *         | string | Dígito da conta                                     | 1                                                       |
| `account_number` *        | string | Número da conta.                                    | 20                                                      |
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta.   | 14                                                      |
| `owner_name` *            | string | Nome do titular da conta.                           | 50                                                      |
| `account_type`*           | string | Tipo da conta.                                      | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string | Base no CNPJ da instituição financeira (8 dígitos). | 8                                                       |

### Objeto refusal_reason

| Campo           | Tipo   | Descrição                  | Caracteres |
|-----------------|--------|----------------------------|------------|
| `bacen_code` *  | string | Código de recusa Bacen     | 3          |
| `enumerator` *  | string | Enumerador da recusa Bacen | 100        |
| `description` * | string | Descrição da recusa Bacen  | 100        |

### Enumerador account_type

| Enumerador         | Tradução              |
|--------------------|-----------------------|
| checking_account   | conta corrente        |
| deposit_account    | conta depósito        |
| guaranteed_account | conta de garantia     |
| investment_account | conta de investimento |
| payment_account    | conta de pagamento    |
| saving_account     | conta poupança        |

## Webhook após o recebimento de TED

Webhook informará sobre o status final da transação TED.

### Webhook Request Body

**Request Body: TED Recebida**

```json
{
  "webhook_type": "baas.ted.incoming_ted",
  "webhook_datetime": "2021-10-22T20:30:23.459Z",
  "data": {
    "request_control_key": "6e290347-330d-4b3a-8ebb-2ac217ad6eb3",
    "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
    "account_key": "fc6862c4-2b20-4057-8063-b8809866e494",
    "created_at": "2021-10-22T20:30:23.459Z",
    "ted_status": "received",
    "transaction_amount": 126.97,
    "fee_amount": 0.0,
    "source_account": {
      "account_branch": "0001",
      "account_digit": "6",
      "account_number": "78340",
      "ispb": "12345678",
      "owner_document_number": "32402502000135",
      "owner_name": "QI Tech"
    },
    "refusal_reason": {}
  }
}
```

### Webhook Body Param

| Campo                 | Tipo   | Descrição                                                                         | Max. Caracteres                                     |
|-----------------------|--------|-----------------------------------------------------------------------------------|-----------------------------------------------------|
| `webhook_type`        | string | Um enumerador que define o tipo de evento sendo reportado                         | 23                                                  |
| `webhook_datetime`    | string | Data e hora do envio do webhook                                                   | 20                                                  |
| `ted_key`             | string | Chave única de identificação da transferência TED                                 | 36                                                  |
| `created_at`          | string | Data e hora de criação da transação                                               | 100                                                 |
| `ted_status`          | string | Status da transação TED                                                           | **[Enumerador ted_status](#enumerador-ted_status)** |
| `transaction_amount`  | number | Valor da transferência                                                            | 10                                                  |
| `fee_amount`          | number | Valor da taxca cobrada pela transferencia                                         | 35                                                  |
| `target_account`      | Object | Conta destino - Só deve ser enviada em transações do tipo "manual"                | **[Objeto target_account](#objeto-target_account)** |
| `refusal_reason`      | Object | Motivo da recusa de acordo com o padrão do Banco Central                          | **[Objeto refusal_reason](#objeto-refusal_reason)** |

### Enumerador ted_status

| Enumerador   | Descrição                                |
|--------------|------------------------------------------|
| **received** | Transferência TED realizada com sucesso. |
| **pending**  | Transferência TED pendente.              |
| **rejected** | Transferência TED rejeitada.             |

### Objeto target_account

| Campo                     | Tipo   | Descrição                                           | Caracteres                                              |
|---------------------------|--------|-----------------------------------------------------|---------------------------------------------------------|
| `account_branch` *        | string | Agência.                                            | 10                                                      |
| `account_digit` *         | string | Dígito da conta                                     | 10                                                      |
| `account_number` *        | string | Número da conta.                                    | 10                                                      |
| `owner_document_number` * | string | CPF ou CNPJ (apenas números) do titular da conta.   | 14                                                      |
| `owner_name` *            | string | Nome do titular da conta.                           | 50                                                      |
| `account_type`*           | string | Tipo da conta.                                      | **[Enumerador account_type](#enumerador-account_type)** |
| `ispb` *                  | string | Base no CNPJ da instituição financeira (8 dígitos). | 8                                                       |

### Objeto refusal_reason

| Campo           | Tipo   | Descrição                  | Caracteres |
|-----------------|--------|----------------------------|------------|
| `bacen_code` *  | string | Código de recusa Bacen     | 3          |
| `enumerator` *  | string | Enumerador da recusa Bacen | 100        |
| `description` * | string | Descrição da recusa Bacen  | 100        |

### Enumerador account_type

| Enumerador         | Tradução              |
|--------------------|-----------------------|
| checking_account   | conta corrente        |
| deposit_account    | conta depósito        |
| guaranteed_account | conta de garantia     |
| investment_account | conta de investimento |
| payment_account    | conta de pagamento    |
| saving_account     | conta poupança        |

---

# consulta_de_agenda_com_opt_in

URL: /documentation/trava_de_domicilio_bancario/consulta_de_agenda_com_opt_in

## Request

- ENDPOINT /receivables/inquiry
- MÉTODO POST
- BODY (antes de ser assinado):

:::caution **Atenção**

Essa request gera um documento de autorização para assinatura, ao ser assinada a agenda vai ser consultada e o resultado devolvido por webhook.

:::

YOUR REQUEST HISTORY

**body.json**

```json
{
    "notification_type": "webhook",
    "owner_person_type": "legal",
    "owner_person_name": "John Sample Inc",
    "owner_document_number": "86498542000151",
    "reference_code": "5830c2f9-fd17-4c9c-b30c-68ddd1a92751",
    "agenda": {
        "end_date": "2021-06-23",
        "start_date": "2021-06-23"
    }
}

```

### Body Params

| Campo | Descrição |
|---|---|
| `notification_type` *(obrigatório)* |  |
| `owner_person_type` *(obrigatório)* | Tipo de pessoa (natural ou juridica) objeto da consulta de agenda. |
| `owner_person_name` *(obrigatório)* | Nome do objeto da consulta de agenda. |
| `owner_document_number` *(obrigatório)* | Numero de documento do objeto da consulta de agenda. |
| `reference_code` *(obrigatório)* | Identificador único do opt-in. |
| `signature` *(obrigatório)* | Informações do opt-in. |
| `agenda` *(obrigatório)* | Parâmetros para a consulta de agenda. |

### SIGNATURE OBJECT

| Campo | Descrição |
|---|---|
| `signers` *(obrigatório)* | Lista de signatários. |

### AGENDA OBJECT

| Campo | Descrição |
|---|---|
| `acquirers` *(obrigatório)* | Lista de números de documentos da Credenciadoras. |
| `card_schemes` *(obrigatório)* | Lista de arranjos de pagamento. |
| `end_date` | Data de termino da consulta. |
| `start_date` *(obrigatório)* | Data de início da consulta. |

---

# consulta_de_agenda_sem_opt_in

URL: /documentation/trava_de_domicilio_bancario/consulta_de_agenda_sem_opt_in

## Request

- ENDPOINT /receivables/inquiry
- MÉTODO POST
- BODY (antes de ser assinado):

YOUR REQUEST HISTORY

**body.json**

```json
{
    "notification_type": "webhook",
    "owner_person_type": "legal",
    "owner_person_name": "John Sample Inc",
    "owner_document_number": "86498542000151",
    "reference_code": "5830c2f9-fd17-4c9c-b30c-68ddd1a92751",
    "agenda": {
        "end_date": "2021-06-23",
        "start_date": "2021-06-23"
    }
}

```

:::caution **Atenção**

A request com pré-autorização deverá ser usada, quando o solicitante da agenda já tem o consentimento do cliente. Dessa forma, deverá ser passado no campo authorization dentro de signatures, todas as informações referentes ao consentimento do cliente.

Essa request gerará uma consulta de agenda que será consultada assincronamente, o resultado virá via webhook.

:::

### Body Params

| Campo | Descrição |
|---|---|
| `notification_type` *(obrigatório)* |  |
| `owner_person_type` *(obrigatório)* | Tipo de pessoa (natural ou juridica) objeto da consulta de agenda. |
| `owner_person_name` *(obrigatório)* | Nome do objeto da consulta de agenda. |
| `owner_document_number` *(obrigatório)* | Numero de documento do objeto da consulta de agenda. |
| `reference_code` *(obrigatório)* | Identificador único do opt-in. |
| `signature` *(obrigatório)* | Informações do opt-in. |
| `agenda` *(obrigatório)* | Parâmetros para a consulta de agenda. |

### SIGNATURE OBJECT

| Campo | Descrição |
|---|---|
| `signers` *(obrigatório)* | Lista de signatários. |
| `authorization` *(obrigatório)* | |

### AGENDA OBJECT

| Campo | Descrição |
|---|---|
| `acquirers` *(obrigatório)* | Lista de números de documentos da Credenciadoras. |
| `card_schemes` *(obrigatório)* | Lista de arranjos de pagamento. |
| `end_date` | Data de termino da consulta. |
| `start_date` *(obrigatório)* | Data de início da consulta. |

---

# emissao_de_divida_com_trava_de_agenda

URL: /documentation/trava_de_domicilio_bancario/emissao_de_divida_com_trava_de_agenda

## Request

- ENDPOINT /baas/debt_receivables
- MÉTODO POST
- BODY (antes de ser assinado):

YOUR REQUEST HISTORY

:::info

A emissão de dividas com trava de agenda segue o mesmo forma de uma emissão de dividas simples apresentada no conjunto de APIs 3, com a adição do objeto "contract" conforme descrito aqui.

:::

**body.json**

```json
{"contract": {
        "payment_account": {
            "account_number": "48391",
            "account_branch": "0001",
            "account_digit": "6",
            "owner_document_number": "86498542000151"
        },
        "collateral_management": {
            "collateral_management_type": "absolute",
            "amount": 2000,
            "maximum_value": 2000,
            "maximum_daily_value": 200,
            "minimum_date": "2021-06-28",
            "contract_payment_type": "partial_payment"
        }
    }}

```

### Body Params

| Campo | Descrição |
|---|---|
| `contract` | Dados da garantia. |

### CONTRACT OBJECT

| Campo | Descrição |
|---|---|
| `payment_account` | Conta de pagamentos para os recebíveis |
| `collaterals` | Listas de garantias. |
| `collateral_management` | Configurações de garantia. |

### PAYMENT ACCOUNT OBJECT

| Campo | Descrição |
|---|---|
| `account_number` *(obrigatório)* | Número da conta onde vão cair os recebíveis de cartão. |
| `account_branch` *(obrigatório)* | Agência da conta. |
| `account_digit` *(obrigatório)* | Dígito da conta. |
| `owner_document_number` *(obrigatório)* | Número de documento do titular da conta (CPF ou CNPJ). |

### COLLATERALS OBJECT

| Campo | Descrição |
|---|---|
| `acquirer` *(obrigatório)* | Lista de números de documentos da Credenciadoras. |
| `card_scheme` *(obrigatório)* | Lista de arranjos de pagamento. |
| `initial_date` *(obrigatório)* | Data de início do contrato. |
| `final_date` *(obrigatório)* | Data de termino do contrato. |
| `division_rule` *(obrigatório)* | Tipo de distribuição dos ônus pré-definida de acordo com tabela fornecida pela QI Tech. 1- Comprometimento de valor definido 2- Comprometimento de percentual do valor que vier a ser constituído |
| `encumbered_amount` *(obrigatório)* | Valor a onerar conforme a regra de divisão. |

### COLLATERALS MANAGEMENT OBJECT

| Campo | Descrição |
|---|---|
| `collateral_management_type` *(obrigatório)* | Tipo de gestão a ser utilizada para amortizar a divida. |
| `amount` *(obrigatório)* | Valor a ser utilizado. |
| `maximum_value` | Valor máximo que será utilizado para pagamento da operação. |
| `maximum_daily_value` | Valor máximo que será utilizado por dia. |
| `minimum_date` | Data mínima para começar à utilizar os recebiveis. |
| `contract_payment_type` *(obrigatório)* | Tipo de pagamento para o contrato |

---

# introducao

URL: /documentation/trava_de_domicilio_bancario/introducao

## Trava de domicílio bancário

Caso o cliente deseje realizar uma operação de crédito com garantia em recebíveis, a QI Tech juntamente com a CERC, está preparada para criar essa operação de maneira muito semelhante ao fluxo de emissão de dívida comum.

---

# Abrir lote de tombamento de boletos

URL: /documentation/troca_de_titularidade/abrir_lote

Esse endpoint criará um lote de tombamento de boletos. 
O lote é criado sem nenhum boleto, e os boletos precisarão ser inseridos através do endpoint de [inclusão de boletos](/incluir_boletos).

## Request

ENDPOINT /account/ ACCOUNT-KEY /requester_profile/ REQUESTER-PROFILE-KEY /bank_slip_ownership_exchange_batch/stream
MÉTODO POST

### Path parameters

| Campo         | Tipo   | Descrição                                                                                                              | Caracteres |
|---------------|--------|------------------------------------------------------------------------------------------------------------------------|------------|
| `ACCOUNT-KEY` | uuidv4 | Chave única de identificação da conta de origem, onde os boletos foram originalmente registrados.                      | 36         |
| `REQUESTER-PROFILE-KEY` | uuidv4 | Chave única de identificação da carteira de cobrança de origem, onde os boletos foram originalmente registrados. | 36         |

Request Body - Chave UUID da carteira de cobrança

```json
{
	"request_control_key": "66c9399a-1463-4e2b-acc0-7ee447f81bf0",
	"new_requester_profile_key": "e494067f-5bd4-4819-b64f-0687bd217f45",
	"new_pix_key": "2376da91-86ad-4a0b-a466-f0f5acf53e24"
}
```

Request Body - Código da carteira de cobrança

```json
{
	"request_control_key": "66c9399a-1463-4e2b-acc0-7ee447f81bf0",
	"new_requester_profile_code": "329-09-0001-1234567",
	"new_pix_key": "2376da91-86ad-4a0b-a466-f0f5acf53e24"
}
```

:::info Código da Carteira de Cobrança de boletos
O Código da Carteira de Cobrança é uma string que segue o seguinte padrão:

[ Número do Banco ] + [ Código da Carteira ] + [ Número da Agência da Conta ] + [ Número da Conta com 7 caracteres e sem dígito verificador ]

Por padrão, na QI Tech, o Número do Banco, o Código da Carteira e a Agência, sempre serão `329`, `09` e `0001`, respectivamente.

Sendo assim, o Código da Carteira de Cobrança da conta 5308318-3, será: `329-09-0001-5308318`.
:::

## Body Params
| Campo | Tipo | Descrição | Caracteres |
|---|------|-----------| --|
|`request_control_key`| uuidv4 | Chave única de identificação da requisição neste endpoint. Utilizada para evitar duplicidade na chamada via API. |36|
|`new_requester_profile_key`| uuidv4 | Chave única de identificação da carteira de cobrança de destino. É a carteira de cobrança para onde os boletos serão tombados. Você consegue opter essa chave através do [endpoint de consulta de carteiras de cobrança de uma conta](../boletos/carteira/listar_carteiras) |36|
|`new_requester_profile_code`| string | Código da carteira de cobrança de destino. É a carteira de cobrança para onde os boletos serão tombados. |19|
|`new_pix_key` | string | Chave pix da conta de destino do tombamento (para os casos de bolepix). | 255 |

## Response

STATUS 202

Response Body

```json
{
    "bank_slip_ownership_exchange_batch_key": "243c9369-ce8b-49df-969c-d891c2fc8c21",
    "request_control_key": "66c9399a-1463-4e2b-acc0-7ee447f81bf0",
    "bank_slip_ownership_exchange_batch_status": "open",
    "new_requester_profile_key": "e494067f-5bd4-4819-b64f-0687bd217f45",
    "new_requester_profile_code": "329-09-0001-8703524",
    "new_requester_profile_owner_name": "Fulano de Tal",
    "new_requester_profile_owner_document_number": "70896538000101",
    "new_requester_profile_account_number": "8703524",
    "new_requester_profile_account_digit": "1",
    "new_requester_profile_account_branch": "0001",
    "new_pix_key": "2376da91-86ad-4a0b-a466-f0f5acf53e24",
    "total_bank_slip_count": 0,
    "total_amount": 0
}
```

## Response Params
| Campo                                         | Tipo  | Descrição                                                                                                                                                                                                                                                                   | Caracteres                                                                                                          |
|-----------------------------------------------|-------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| `bank_slip_ownership_exchange_batch_key`      | uuidv4 | Chave única de indentificação do lote de tombamento.                                                                                                                                                                                                                        | 36                                                                                                                  |
| `request_control_key`                         | uuidv4 | Chave única de identificação da requisição neste endpoint. Utilizada para evitar duplicidade na chamada via API.                                                                                                                                                            | 36                                                                                                                  |
| `bank_slip_ownership_exchange_batch_status`   | enum  | Status do lote de tombamento.                                                                                                                                                                                                                                               | [Enumeradores `bank_slip_ownership_exchange_batch_status`](#enumeradores-bank_slip_ownership_exchange_batch_status) |
| `new_requester_profile_key`                   | uuidv4 | Chave única de identificação da carteira de cobrança de destino. É a carteira de cobrança para onde os boletos serão tombados. Você consegue opter essa chave através do [endpoint de consulta de carteiras de cobrança de uma conta](../boletos/carteira/listar_carteiras) | 36                                                                                                                  |
| `new_requester_profile_code`                  | string | Código da carteira de cobrança de destino. É a carteira de cobrança para onde os boletos serão tombados.                                                                                                                                                                    | 19                                                                                                                  |
| `new_requester_profile_owner_name`            | string | Nome do titular da conta de destino e do beneficiário da carteira de cobrança de destino.                                                                                                                                                                                   | 255                                                                                                                 |
| `new_requester_profile_owner_document_number` | string | Número do documento (CPF/CNPJ) do titular da conta de destino e do beneficiário da carteira de cobrança de destino.                                                                                                                                                         | 255                                                                                                                 |
| `new_requester_profile_account_number`        | string | Número da conta de destino do tombamento.                                                                                                                                                                                                                                   | 7                                                                                                                   |
| `new_requester_profile_account_digit`         | string | Dígito verificador da conta de destino do tombamento.                                                                                                                                                                                                                       | 1                                                                                                                   |
| `new_requester_profile_account_branch`        | string | Número da agência da conta de destino do tombamento.                                                                                                                                                                                                                        | 4                                                                                                                   |
| `new_pix_key`                                 | string | Chave pix da conta de destino do tombamento (para os casos de bolepix).                                                                                                                                                                                                     | 255                                                                                                                 |
| `total_bank_slip_count`                       | float | Total de boletos no lote de tombamento.                                                                                                                                                                                                                                     | -                                                                                                                   |
| `total_amount`                                 | float | Somatória do valor de face dos boletos no lote de tombamento.                                                                                                                                                                                                               | -                                                                                                                   |                                                                                                                                                                                                               

### Enumeradores bank_slip_ownership_exchange_batch_status
| Enumerador | Descrição                                                                                              |
|------------|--------------------------------------------------------------------------------------------------------|
| open       | O lote foi criado e ainda está aberto para inclusão/exclusão de boletos.                               |
| sent     | A seleção dos boletos foi concluída e o lote de tombamento esta pendente de aprovação. A parte aprovadora necessita realizar a aprovação                  |
| processing | A seleção dos boletos foi concluída e o tombamento dos boletos contidos no lote esta sendo processado. |
| approved | Os boletos contidos no lote já foram tombados o destinatário |
| cancelled   | Lote de tombamento cancelado. |
| rejected | Lote de tomabamento rejeitado. |

---

# Aprovar lote de tombamento de boletos

URL: /documentation/troca_de_titularidade/aprovar_lote

Uma vez que foi feito o envio do lote de tombamento através do ```/send```, é necessário realizar a aprovação do tombamento.

A aprovação deve ser feita pela conta e requester de destino, que serão os novos responsáveis pelos boletos após o tombamento. Se o tombamento for entre contas do mesmo requester, basta fazer a alteração da account-key.

## Request

ENDPOINT /account/ ACCOUNT-KEY /requester_profile/ REQUESTER-PROFILE-KEY /bank_slip_ownership_exchange_batch/ BANK-SLIP-OWNERSHIP-EXCHANGE-BATCH-KEY /approve
MÉTODO PATCH

### Path parameters

| Campo                                    | Tipo   | Descrição                                                                                                        | Caracteres |
|------------------------------------------|--------|------------------------------------------------------------------------------------------------------------------|------------|
| `ACCOUNT-KEY`                            | uuidv4 | Chave única de identificação da conta de destino, onde os boletos serão enviados.                | 36         |
| `REQUESTER-PROFILE-KEY`                  | uuidv4 | Chave única de identificação da carteira de destino, onde os boletos serão transferidos. | 36         |
| `BANK-SLIP-OWNERSHIP-EXCHANGE-BATCH-KEY` | uuidv4 | Chave única de indentificação do lote de tombamento.                                                             | 36         |

Request Body

```json
{}
```

## Response

STATUS 200

Response Body

```json
{
    "bank_slip_ownership_exchange_batch_key": "243c9369-ce8b-49df-969c-d891c2fc8c21",
    "request_control_key": "66c9399a-1463-4e2b-acc0-7ee447f81bf0",
    "bank_slip_ownership_exchange_batch_status": "processing",
    "new_requester_profile_key": "e494067f-5bd4-4819-b64f-0687bd217f45",
    "new_requester_profile_code": "329-09-0001-8703524",
    "new_requester_profile_owner_name": "Fulano de Tal",
    "new_requester_profile_owner_document_number": "70896538000101",
    "new_requester_profile_account_number": "8703524",
    "new_requester_profile_account_digit": "1",
    "new_requester_profile_account_branch": "0001",
    "new_pix_key": "2376da91-86ad-4a0b-a466-f0f5acf53e24",
    "total_bank_slip_count": 3,
    "total_amount": 750.00
}
```

## Response Params
| Campo | Tipo | Descrição | Caracteres                                                                                                          |
|---|------|-----------|---------------------------------------------------------------------------------------------------------------------|
| `bank_slip_ownership_exchange_batch_key`      | uuidv4 | Chave única de indentificação do lote de tombamento.                                                                                                                                                                                                                        | 36                                                                                                                  |
| `request_control_key`                         | uuidv4 | Chave única de identificação da requisição neste endpoint. Utilizada para evitar duplicidade na chamada via API.                                                                                                                                                            | 36                                                                                                                  |
| `bank_slip_ownership_exchange_batch_status`   | enum  | Status do lote de tombamento.                                                                                                                                                                                                                                               | [Enumeradores `bank_slip_ownership_exchange_batch_status`](#enumeradores-bank_slip_ownership_exchange_batch_status) |
| `new_requester_profile_key`                   | uuidv4 | Chave única de identificação da carteira de cobrança de destino. É a carteira de cobrança para onde os boletos serão tombados. Você consegue opter essa chave através do [endpoint de consulta de carteiras de cobrança de uma conta](../boletos/carteira/listar_carteiras) | 36                                                                                                                  |
| `new_requester_profile_code`                  | string | Código da carteira de cobrança de destino. É a carteira de cobrança para onde os boletos serão tombados.                                                                                                                                                                    | 19                                                                                                                  |
| `new_requester_profile_owner_name`            | string | Nome do titular da conta de destino e do beneficiário da carteira de cobrança de destino.                                                                                                                                                                                   | 255                                                                                                                 |
| `new_requester_profile_owner_document_number` | string | Número do documento (CPF/CNPJ) do titular da conta de destino e do beneficiário da carteira de cobrança de destino.                                                                                                                                                         | 255                                                                                                                 |
| `new_requester_profile_account_number`        | string | Número da conta de destino do tombamento.                                                                                                                                                                                                                                   | 7                                                                                                                   |
| `new_requester_profile_account_digit`         | string | Dígito verificador da conta de destino do tombamento.                                                                                                                                                                                                                       | 1                                                                                                                   |
| `new_requester_profile_account_branch`        | string | Número da agência da conta de destino do tombamento.                                                                                                                                                                                                                        | 4                                                                                                                   |
| `new_pix_key`                                 | string | Chave pix da conta de destino do tombamento (para os casos de bolepix).                                                                                                                                                                                                     | 255                                                                                                                 |
| `total_bank_slip_count`                       | float | Total de boletos no lote de tombamento.                                                                                                                                                                                                                                     | -                                                                                                                   |
| `total_amount`                                | float | Somatória do valor de face dos boletos no lote de tombamento. | -                                                                                                                   |                                                                                                                                                                                                               

### Enumeradores bank_slip_ownership_exchange_batch_status
| Enumerador | Descrição                                                                                              |
|------------|--------------------------------------------------------------------------------------------------------|
| open       | O lote foi criado e ainda está aberto para inclusão/exclusão de boletos.                               |
| closed     | O lote se encontra fechado e o tombamento dos boletos contidos no lote foi concluído.                  |
| processing | A seleção dos boletos foi concluída e o tombamento dos boletos contidos no lote esta sendo processado. |
| pending_approval | A seleção dos boletos foi concluída e o lote de tombamento esta pendente de aprovação. A parte aprovadora, pode remover boletos do lote. |
| canceled   | Lote de tombamento cancelado. |
| rejected | Lote de tomabamento rejeitado. |

---

# Cancelar lote de tombamento de boletos

URL: /documentation/troca_de_titularidade/cancelar_lote

## Request

ENDPOINT /bank_slip/account/ ACCOUNT-KEY /requester_profile/ REQUESTER-PROFILE-KEY /bank_slip_ownership_exchange_batch/ BANK-SLIP-OWNERSHIP-EXCHANGE-BATCH-KEY /cancel
MÉTODO PATCH

### Path parameters

| Campo                                    | Tipo   | Descrição                                                                                                              | Caracteres |
|------------------------------------------|--------|------------------------------------------------------------------------------------------------------------------------|------------|
| `ACCOUNT-KEY`                            | uuidv4 | Chave única de identificação da conta de origem, onde os boletos foram originalmente registrados.                      | 36         |
| `REQUESTER-PROFILE-KEY`                  | uuidv4 | Chave única de identificação da carteira de cobrança de origem, onde os boletos foram originalmente registrados. | 36         |
| `BANK-SLIP-OWNERSHIP-EXCHANGE-BATCH-KEY` | uuidv4 |Chave única de indentificação do lote de tombamento.| 36         |

Request Body

```json
{}
```

## Response

STATUS 200

Response Body

```json
{
    "bank_slip_ownership_exchange_batch_key": "243c9369-ce8b-49df-969c-d891c2fc8c21",
    "request_control_key": "66c9399a-1463-4e2b-acc0-7ee447f81bf0",
    "bank_slip_ownership_exchange_batch_status": "canceled",
    "new_requester_profile_key": "e494067f-5bd4-4819-b64f-0687bd217f45",
    "new_requester_profile_code": "329-09-0001-8703524",
    "new_requester_profile_owner_name": "Fulano de Tal",
    "new_requester_profile_owner_document_number": "70896538000101",
    "new_requester_profile_account_number": "8703524",
    "new_requester_profile_account_digit": "1",
    "new_requester_profile_account_branch": "0001",
    "new_pix_key": "2376da91-86ad-4a0b-a466-f0f5acf53e24",
    "total_bank_slip_count": 3,
    "total_amount": 750.00
}
```

## Response Params
| Campo | Tipo | Descrição | Caracteres                                                                                                          |
|---|------|-----------|---------------------------------------------------------------------------------------------------------------------|
| `bank_slip_ownership_exchange_batch_key`      | uuidv4 | Chave única de indentificação do lote de tombamento.                                                                                                                                                                                                                        | 36                                                                                                                  |
| `request_control_key`                         | uuidv4 | Chave única de identificação da requisição neste endpoint. Utilizada para evitar duplicidade na chamada via API.                                                                                                                                                            | 36                                                                                                                  |
| `bank_slip_ownership_exchange_batch_status`   | enum  | Status do lote de tombamento.                                                                                                                                                                                                                                               | [Enumeradores `bank_slip_ownership_exchange_batch_status`](#enumeradores-bank_slip_ownership_exchange_batch_status) |
| `new_requester_profile_key`                   | uuidv4 | Chave única de identificação da carteira de cobrança de destino. É a carteira de cobrança para onde os boletos serão tombados. Você consegue opter essa chave através do [endpoint de consulta de carteiras de cobrança de uma conta](../boletos/carteira/listar_carteiras) | 36                                                                                                                  |
| `new_requester_profile_code`                  | string | Código da carteira de cobrança de destino. É a carteira de cobrança para onde os boletos serão tombados.                                                                                                                                                                    | 19                                                                                                                  |
| `new_requester_profile_owner_name`            | string | Nome do titular da conta de destino e do beneficiário da carteira de cobrança de destino.                                                                                                                                                                                   | 255                                                                                                                 |
| `new_requester_profile_owner_document_number` | string | Número do documento (CPF/CNPJ) do titular da conta de destino e do beneficiário da carteira de cobrança de destino.                                                                                                                                                         | 255                                                                                                                 |
| `new_requester_profile_account_number`        | string | Número da conta de destino do tombamento.                                                                                                                                                                                                                                   | 7                                                                                                                   |
| `new_requester_profile_account_digit`         | string | Dígito verificador da conta de destino do tombamento.                                                                                                                                                                                                                       | 1                                                                                                                   |
| `new_requester_profile_account_branch`        | string | Número da agência da conta de destino do tombamento.                                                                                                                                                                                                                        | 4                                                                                                                   |
| `new_pix_key`                                 | string | Chave pix da conta de destino do tombamento (para os casos de bolepix).                                                                                                                                                                                                     | 255                                                                                                                 |
| `total_bank_slip_count`                       | float | Total de boletos no lote de tombamento.                                                                                                                                                                                                                                     | -                                                                                                                   |
| `total_amount`                                | float | Somatória do valor de face dos boletos no lote de tombamento. | -                                                                                                                   |                                                                                                                                                                                                               

### Enumeradores bank_slip_ownership_exchange_batch_status
| Enumerador | Descrição                                                                                              |
|------------|--------------------------------------------------------------------------------------------------------|
| open       | O lote foi criado e ainda está aberto para inclusão/exclusão de boletos.                               |
| closed     | O lote se encontra fechado e o tombamento dos boletos contidos no lote foi concluído.                  |
| processing | A seleção dos boletos foi concluída e o tombamento dos boletos contidos no lote esta sendo processado. |
| pending_approval | A seleção dos boletos foi concluída e o lote de tombamento esta pendente de aprovação. A parte aprovadora, pode remover boletos do lote. |
| canceled   | Lote de tombamento cancelado. |
| rejected | Lote de tomabamento rejeitado. |

---

# Criar lote de tombamento de boletos

URL: /documentation/troca_de_titularidade/criar_lote_batch

## Request

ENDPOINT /bank_slip/account/ ACCOUNT-KEY /requester_profile/ REQUESTER-PROFILE-KEY /bank_slip_ownership_exchange_batch
MÉTODO POST

### Path parameters

| Campo         | Tipo   | Descrição                                                                                                              | Caracteres |
|---------------|--------|------------------------------------------------------------------------------------------------------------------------|------------|
| `ACCOUNT-KEY` | uuidv4 | Chave única de identificação da conta de origem, onde os boletos foram originalmente registrados.                      | 36         |
| `REQUESTER-PROFILE-KEY` | uuidv4 | Chave única de identificação da carteira de cobrança de origem, onde os boletos foram originalmente registrados. | 36         |

Request Body - Chave da carteira de cobrança

```json
{
	"bank_slips": [
		"b21c5b5a-a71f-4672-9254-022401cd15f6",
		"8197e3d0-1500-439f-9f9d-d243115542fa",
		"8293b817-bed9-418a-8c1e-ec8ef5a31468"
	],
	"request_control_key": "66c9399a-1463-4e2b-acc0-7ee447f81bf0",
	"new_requester_profile_key": "e494067f-5bd4-4819-b64f-0687bd217f45",
	"new_pix_key": "2376da91-86ad-4a0b-a466-f0f5acf53e24"
}
```

Request Body - Código da carteira de cobrança

```json
{
	"bank_slips": [
		"b21c5b5a-a71f-4672-9254-022401cd15f6",
		"8197e3d0-1500-439f-9f9d-d243115542fa",
		"8293b817-bed9-418a-8c1e-ec8ef5a31468"
	],
	"request_control_key": "66c9399a-1463-4e2b-acc0-7ee447f81bf0",
	"new_requester_profile_code": "329-09-0001-1234567",
	"new_pix_key": "2376da91-86ad-4a0b-a466-f0f5acf53e24"
}
```

## Body Params
| Campo | Tipo | Descrição | Caracteres |
|---|------|-----------|------------|
|`bank_slips` | list | Lista de boletos que serão incluídos no lote de tombamento.         | 36         |
|`request_control_key`| uuidv4 | Chave única de identificação da requisição neste endpoint. Utilizada para evitar duplicidade na chamada via API. | 36         |
|`new_requester_profile_key`| uuidv4 | Chave única de identificação da carteira de cobrança de destino. É a carteira de cobrança para onde os boletos serão tombados. Você consegue opter essa chave através do [endpoint de consulta de carteiras de cobrança de uma conta](../boletos/carteira/listar_carteiras) | 36         |
|`new_requester_profile_code`| string | Código da carteira de cobrança de destino. É a carteira de cobrança para onde os boletos serão tombados. | 19         |
|`new_pix_key` | uuidv4 | Chave pix da conta de destino do tombamento (para os casos de bolepix). | 36         |

:::caution Atenção!
A lista de boletos informada no objeto `bank_slips` no payload de criação do lote, tem uma limitação de 10.000 boletos por requisição. 
:::

:::info Código da Carteira de Cobrança de boletos
O Código da Carteira de Cobrança é uma string que segue o seguinte padrão:

[ Número do Banco ] + [ Código da Carteira ] + [ Número da Agência da Conta ] + [ Número da Conta com 7 caracteres e sem dígito verificador ]

Por padrão, na QI Tech, o Número do Banco, o Código da Carteira e a Agência, sempre serão `329`, `09` e `0001`, respectivamente.

Sendo assim, o Código da Carteira de Cobrança da conta 5308318-3, será: `329-09-0001-5308318`.
:::

## Response

STATUS 201 Created

Response Body

```json
{
    "bank_slip_ownership_exchange_batch_key": "243c9369-ce8b-49df-969c-d891c2fc8c21",
    "request_control_key": "66c9399a-1463-4e2b-acc0-7ee447f81bf0",
    "bank_slip_ownership_exchange_batch_status": "closed",
    "bank_slips": [
        "b21c5b5a-a71f-4672-9254-022401cd15f6",
        "8197e3d0-1500-439f-9f9d-d243115542fa",
        "8293b817-bed9-418a-8c1e-ec8ef5a31468"
    ],
    "new_requester_profile_key": "e494067f-5bd4-4819-b64f-0687bd217f45",
    "new_requester_profile_code": "329-09-0001-8703524",
    "new_requester_profile_owner_name": "Fulano de Tal",
    "new_requester_profile_owner_document_number": "70896538000101",
    "new_requester_profile_account_number": "8703524",
    "new_requester_profile_account_digit": "1",
    "new_requester_profile_account_branch": "0001",
    "pix_key": "2376da91-86ad-4a0b-a466-f0f5acf53e24",
    "total_bank_slip_count": 40,
    "total_amount": 67245.96
}
```

## Response Params
| Campo | Tipo | Descrição | Caracteres                                                                                                          |
|---|------|-----------|---------------------------------------------------------------------------------------------------------------------|
| `bank_slip_ownership_exchange_batch_key`      | uuidv4 | Chave única de indentificação do lote de tombamento.                                                                                                                                                                                                                        | 36                                                                                                                  |
| `request_control_key`                         | uuidv4 | Chave única de identificação da requisição neste endpoint. Utilizada para evitar duplicidade na chamada via API.                                                                                                                                                            | 36                                                                                                                  |
| `bank_slip_ownership_exchange_batch_status`   | enum  | Status do lote de tombamento.                                                                                                                                                                                                                                               | [Enumeradores `bank_slip_ownership_exchange_batch_status`](#enumeradores-bank_slip_ownership_exchange_batch_status) |
|`bank_slips` | list | Lista de boletos que serão incluídos no lote de tombamento.         | 36                                                                                                                  |
| `new_requester_profile_key`                   | uuidv4 | Chave única de identificação da carteira de cobrança de destino. É a carteira de cobrança para onde os boletos serão tombados. Você consegue opter essa chave através do [endpoint de consulta de carteiras de cobrança de uma conta](../boletos/carteira/listar_carteiras) | 36                                                                                                                  |
| `new_requester_profile_code`                  | string | Código da carteira de cobrança de destino. É a carteira de cobrança para onde os boletos serão tombados.                                                                                                                                                                    | 19                                                                                                                  |
| `new_requester_profile_owner_name`            | string | Nome do titular da conta de destino e do beneficiário da carteira de cobrança de destino.                                                                                                                                                                                   | 255                                                                                                                 |
| `new_requester_profile_owner_document_number` | string | Número do documento (CPF/CNPJ) do titular da conta de destino e do beneficiário da carteira de cobrança de destino.                                                                                                                                                         | 255                                                                                                                 |
| `new_requester_profile_account_number`        | string | Número da conta de destino do tombamento.                                                                                                                                                                                                                                   | 7                                                                                                                   |
| `new_requester_profile_account_digit`         | string | Dígito verificador da conta de destino do tombamento.                                                                                                                                                                                                                       | 1                                                                                                                   |
| `new_requester_profile_account_branch`        | string | Número da agência da conta de destino do tombamento.                                                                                                                                                                                                                        | 4                                                                                                                   |
| `new_pix_key`                                 | string | Chave pix da conta de destino do tombamento (para os casos de bolepix).                                                                                                                                                                                                     | 255                                                                                                                 |
| `total_bank_slip_count`                       | float | Total de boletos no lote de tombamento.                                                                                                                                                                                                                                     | -                                                                                                                   |
| `total_amount`                                 | float | Somatória do valor de face dos boletos no lote de tombamento. | -                                                                                                                   |                                                                                                                                                                                                               

### Enumeradores bank_slip_ownership_exchange_batch_status
| Enumerador | Descrição                                                                                              |
|------------|--------------------------------------------------------------------------------------------------------|
| open       | O lote foi criado e ainda está aberto para inclusão/exclusão de boletos.                               |
| closed     | O lote se encontra fechado e o tombamento dos boletos contidos no lote foi concluído.                  |
| processing | A seleção dos boletos foi concluída e o tombamento dos boletos contidos no lote esta sendo processado. |
| canceled   | Lote de tombamento cancelado. |
| rejected | Lote de tomabamento rejeitado. |

---

# Incluir boletos em um lote de tombamento

URL: /documentation/troca_de_titularidade/incluir_boletos

Esse endpoint é utiliza para inclusão de boletos em um lote de tombamento de boletos.

## Request

ENDPOINT /account/ ACCOUNT-KEY /requester_profile/ REQUESTER-PROFILE-KEY /bank_slip_ownership_exchange_batch/ BANK-SLIP-OWNERSHIP-EXCHANGE-BATCH-KEY /append
MÉTODO PATCH

### Path parameters

| Campo                                    | Tipo   | Descrição                                                                                                              | Caracteres |
|------------------------------------------|--------|------------------------------------------------------------------------------------------------------------------------|------------|
| `ACCOUNT-KEY`                            | uuidv4 | Chave única de identificação da conta de origem, onde os boletos foram originalmente registrados.                      | 36         |
| `REQUESTER-PROFILE-KEY`                  | uuidv4 | Chave única de identificação da carteira de cobrança de origem, onde os boletos foram originalmente registrados. | 36         |
| `BANK-SLIP-OWNERSHIP-EXCHANGE-BATCH-KEY` | uuidv4 |Chave única de indentificação do lote de tombamento.| 36         |

Request Body

```json
{
	"bank_slips": [
		"b21c5b5a-a71f-4672-9254-022401cd15f6",
		"8197e3d0-1500-439f-9f9d-d243115542fa",
		"8293b817-bed9-418a-8c1e-ec8ef5a31468"
	]
}
```

:::caution Atenção!
A lista de boletos informada no objeto `bank_slips` no payload, possui uma limitação de 10.000 boletos por requisição. 
:::

## Response

STATUS 200

Response Body

```json
{
    "bank_slip_ownership_exchange_batch_key": "243c9369-ce8b-49df-969c-d891c2fc8c21",
    "request_control_key": "66c9399a-1463-4e2b-acc0-7ee447f81bf0",
    "bank_slip_ownership_exchange_batch_status": "open",
    "new_requester_profile_key": "e494067f-5bd4-4819-b64f-0687bd217f45",
    "new_requester_profile_code": "329-09-0001-8703524",
    "new_requester_profile_owner_name": "Fulano de Tal",
    "new_requester_profile_owner_document_number": "70896538000101",
    "new_requester_profile_account_number": "8703524",
    "new_requester_profile_account_digit": "1",
    "new_requester_profile_account_branch": "0001",
    "new_pix_key": "2376da91-86ad-4a0b-a466-f0f5acf53e24",
    "total_bank_slip_count": 3,
    "total_amount": 750.00
}
```

## Response Params
| Campo | Tipo | Descrição | Caracteres                                                                                                          |
|---|------|-----------|---------------------------------------------------------------------------------------------------------------------|
| `bank_slip_ownership_exchange_batch_key`      | uuidv4 | Chave única de indentificação do lote de tombamento.                                                                                                                                                                                                                        | 36                                                                                                                  |
| `request_control_key`                         | uuidv4 | Chave única de identificação da requisição neste endpoint. Utilizada para evitar duplicidade na chamada via API.                                                                                                                                                            | 36                                                                                                                  |
| `bank_slip_ownership_exchange_batch_status`   | enum  | Status do lote de tombamento.                                                                                                                                                                                                                                               | [Enumeradores `bank_slip_ownership_exchange_batch_status`](#enumeradores-bank_slip_ownership_exchange_batch_status) |
| `new_requester_profile_key`                   | uuidv4 | Chave única de identificação da carteira de cobrança de destino. É a carteira de cobrança para onde os boletos serão tombados. Você consegue opter essa chave através do [endpoint de consulta de carteiras de cobrança de uma conta](../boletos/carteira/listar_carteiras) | 36                                                                                                                  |
| `new_requester_profile_code`                  | string | Código da carteira de cobrança de destino. É a carteira de cobrança para onde os boletos serão tombados.                                                                                                                                                                    | 19                                                                                                                  |
| `new_requester_profile_owner_name`            | string | Nome do titular da conta de destino e do beneficiário da carteira de cobrança de destino.                                                                                                                                                                                   | 255                                                                                                                 |
| `new_requester_profile_owner_document_number` | string | Número do documento (CPF/CNPJ) do titular da conta de destino e do beneficiário da carteira de cobrança de destino.                                                                                                                                                         | 255                                                                                                                 |
| `new_requester_profile_account_number`        | string | Número da conta de destino do tombamento.                                                                                                                                                                                                                                   | 7                                                                                                                   |
| `new_requester_profile_account_digit`         | string | Dígito verificador da conta de destino do tombamento.                                                                                                                                                                                                                       | 1                                                                                                                   |
| `new_requester_profile_account_branch`        | string | Número da agência da conta de destino do tombamento.                                                                                                                                                                                                                        | 4                                                                                                                   |
| `new_pix_key`                                 | string | Chave pix da conta de destino do tombamento (para os casos de bolepix).                                                                                                                                                                                                     | 255                                                                                                                 |
| `total_bank_slip_count`                       | float | Total de boletos no lote de tombamento.                                                                                                                                                                                                                                     | -                                                                                                                   |
| `total_amount`                                | float | Somatória do valor de face dos boletos no lote de tombamento. | -                                                                                                                   |                                                                                                                                                                                                               

### Enumeradores bank_slip_ownership_exchange_batch_status
| Enumerador | Descrição                                                                                              |
|------------|--------------------------------------------------------------------------------------------------------|
| open       | O lote foi criado e ainda está aberto para inclusão/exclusão de boletos.                               |
| sent     | A seleção dos boletos foi concluída e o lote de tombamento esta pendente de aprovação. A parte aprovadora necessita realizar a aprovação                  |
| processing | A seleção dos boletos foi concluída e o tombamento dos boletos contidos no lote esta sendo processado. |
| approved | Os boletos contidos no lote já foram tombados o destinatário |
| cancelled   | Lote de tombamento cancelado. |
| rejected | Lote de tomabamento rejeitado. |

---

# Introdução

URL: /documentation/troca_de_titularidade/introducao

A troca de titularidade de boletos **(tombamento)** consiste no processo de alteração da carteira de cobrança e da conta de liquidação associadas aos boletos já registrados.

Em uma troca de titularidade, sempre existirão **uma conta e uma carteira de cobrança de origem e uma conta e uma carteira de cobrança de destino.**

- A **conta e carteira de origem** são aquelas em que os boletos foram originalmente registrados.

- A **conta e carteira de destino** são aquelas para as quais os boletos serão transferidos (tombados).

**O que é alterado?**
- Carteira de cobrança
- Conta de liquidação

**O que NÃO é alterado?**
- Dados do beneficiário da cobrança
- Linha digitável para pagamento
- QR Code Pix para pagamento (nos casos de BolePix)

## Casos de Uso

### Composição de garantia
Os boletos de cobrança de uma carteira podem ser utilizados na composição de garantia de uma operação de crédito.
Nesse cenário, o titular da conta de destino tomba os boletos da sua carteira de cobrança simples para a carteira de cobrança vinculada à conta de garantia da operação.

### Cessão de direito creditório
Nos casos em que o boleto de cobrança esteja vinculado a um direito creditório antecipado, é possível — após a conclusão da antecipação — tombar os boletos para a carteira do novo credor do direito antecipado.

:::caution Atenção!
A API de troca de titularidade de boletos **não formaliza** a cessão fiduciária ou a antecipação do direito creditório.
Ela apenas reflete o que deve acontecer com o fluxo financeiro do ativo vinculado ao boleto de cobrança tombado.
:::

## Fluxo do Processo
O tombamento de boletos é o processo de transferência de titularidade dos boletos registrados de uma carteira para outra.
Esse fluxo é composto por quatro etapas principais, que devem ser executadas em sequência por meio de chamadas à API.

A seguir, descrevemos o funcionamento de cada uma delas.

**1. Abertura de lote**

O primeiro passo consiste na criação de um lote de tombamento, que agrupará todos os boletos que serão transferidos.
Assim que o lote é criado, ele é retornado com o status inicial `opened`.
Nessa etapa, devem ser informadas as chaves da conta de origem, da carteira de destino e a nova chave Pix associada.

**2. Inclusão de boletos no lote**

Com o lote aberto, é possível adicionar os boletos que serão incluídos na troca de titularidade.
Durante essa etapa, o status do lote permanece `opened`, indicando que ele ainda está em preparação e pode receber novos boletos.

**3. Envio dos boletos**

Após a inclusão de todos os boletos desejados, é necessário enviar o lote para processamento.
No momento em que o envio é realizado, o status do lote é atualizado para `sent`, e um webhook é disparado para informar a alteração de status.
Esse envio marca o início do fluxo operacional do tombamento.

**4. Aprovação do tombamento**

Por fim, a aprovação do lote deve ser realizada pela conta de destino, confirmando a transferência de titularidade dos boletos.
Após a aprovação, o status do lote muda para `processing`, indicando que o tombamento está em andamento.
Quando o processo é concluído com sucesso, o sistema envia um webhook final com o status `approved`, confirmando que a troca de titularidade foi finalizada.

Compartilhamos a seguir o link que apresenta um organograma do fluxo completo, incluindo os endpoints associados e as respectivas mudanças de status em cada etapa do processo:

---

# Listar boletos de um lote de tombamento

URL: /documentation/troca_de_titularidade/listar_boletos_lote

Utilize esse endpoint para listar todos os boletos incluídos no lote de tombamento consultado.

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip_ownership_exchange_batch/ BANK_SLIP_OWNERSHIP_EXCHANGE_BATCH_KEY /bank_slips
MÉTODO GET

### Path parameters

| Campo         | Tipo   | Descrição                                                                                                              | Caracteres |
|---------------|--------|------------------------------------------------------------------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta de origem, onde os boletos foram originalmente registrados.                      | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira de cobrança de origem, onde os boletos foram originalmente registrados. | 36         |
| `bank_slip_ownership_exchange_batch_key` | uuidv4 |Chave única de indentificação do lote de tombamento.| 36         |

### Query parameters

| Campo                | Descrição                                  |
|----------------------|--------------------------------------------|
| `page_number`        | Página atual que está sendo consultada     |
| `page_size`          | Quantidade de resultados por página        |

## Response

STATUS 200

Response Body

```json
{
    "data": [
        {
            "bank_slip_key": "b58ce415-5428-45c4-8e33-b2df0d3ab6e8",
            "request_control_key": "53529224-330d-44b5-9f4d-59d55bc3cb8c",
            "our_number": 24384760943,
            "document_number": "DOC4561237",
            "amount": "8000.00",
            "rebate_amount": "200.00",
            "expiration": "2024-07-13",
            "barcode": "32994978900005000000001594438621284040114400",
            "digitable_line": "32990001529443862128940401144007497890000500000",
            "bank_teller_instructions": "Confirm payment",
            "protest_data": {
                "days_to_protest": 7
            },
            "bankruptcy_protest_data": {
                "days_to_bankruptcy_protest": 14
            },
            "max_payment_days": 45,
            "fine_data": {
                "fine_type": "absolute",
                "fine_amount": 100,
                "days_to_fine": 10
            },
            "interest_data": {
                "interest_type": "workdays_daily_amount",
                "interest_amount": 5,
                "days_to_interest": 10
            },
            "discounts_data": [
                {
                    "discount_type": "anticipation_workdays_daily_percentage",
                    "discount_number": 1,
                    "discount_limit_date": "2024-07-13",
                    "discount_percentage": 10
                }
            ],
            "payer_data": {
                "name": "Country Tech",
                "address": {
                    "city": "Innovation City",
                    "state": "RS",
                    "number": "202",
                    "street": "101 High St.",
                    "complement": "Building A",
                    "postal_code": "57099999",
                    "neighborhood": "Tech Park"
                },
                "person_type": "legal",
                "document_number": "12345678000195"
            },
            "guarantor_data": {
                "name": "Jamie Doe",
                "address": {
                    "city": "Peaceful Town",
                    "state": "MG",
                    "number": "303",
                    "street": "202 Elm St.",
                    "complement": "House 1",
                    "postal_code": "57099999",
                    "neighborhood": "Quiet Neighborhood"
                },
                "person_type": "natural",
                "document_number": "98765432100"
            },
            "bank_slip_status": "accepted"
        }
    ],
    "pagination": {
        "current_page": 1,
        "rows_per_page": 100
    }
}
```

## Response Params

[Objeto de Listagem de boletos](../boletos/consulta/listar_boletos#response-body-params)

---

# Listar lotes de tombamento de boletos - destino

URL: /documentation/troca_de_titularidade/listar_lotes_destino

Utilize este endpoint para listar os lotes de tombamento de boletos a partir da conta de destino — ou seja, a conta para a qual os boletos foram tombados.

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip_ownership_exchange_batches/incoming
MÉTODO GET

### Path parameters

| Campo         | Tipo   | Descrição                                                                                             | Caracteres |
|---------------|--------|-------------------------------------------------------------------------------------------------------|------------|
| `account_key` | uuidv4 | Chave única de identificação da conta de destino, para onde os boletos serão tombados.                | 36         |
| `requester_profile_key` | uuidv4 | Chave única de identificação da carteira de cobrança de destino, para onde os boletos serão tombados. | 36         |

### Query parameters

| Campo                | Descrição                                  |
|----------------------|--------------------------------------------|
| `page_number`        | Página atual que está sendo consultada     |
| `page_size`          | Quantidade de resultados por página        |

## Response

STATUS 200

Response Body

```json
{
	"data": [
        {
            "bank_slip_exchange_batch_key": "186e73f1-456f-4265-8cb0-b32722041580",
            "request_control_key": "fa7fa38c-0356-4345-98ef-21a089d9a39a",
            "bank_slip_ownership_exchange_batch_status": "processing",
            "old_requester_profile_key": "01a30518-0b2e-4dd1-a105-8f8bf31868a2",
            "old_requester_profile_code": "329-09-0001-5963550",
            "old_requester_profile_owner_document_number": "02602536000102",
            "old_requester_profile_owner_name": "Coca Cola",
            "old_requester_profile_account_number": "5963550",
            "old_requester_profile_account_digit": "7",
            "old_requester_profile_account_branch": "0001",
            "old_pix_key": "2376da91-86ad-4a0b-a466-f0f5acf53e24",
            "total_bank_slip_count": 200,
            "total_amount": 38145.58
        },
        {
            "bank_slip_exchange_batch_key": "8a5bbded-72ff-4642-8830-f2a5a73eb62c",
            "request_control_key": "d3725802-7e56-4196-8182-2747ea18e96a",
            "bank_slip_ownership_exchange_batch_status": "open",
            "old_requester_profile_key": "316052e8-a017-4fb9-9939-9ce0390fa053",
            "old_requester_profile_code": "329-09-0001-4743630",
            "old_requester_profile_owner_document_number": "40500359000142",
            "old_requester_profile_owner_name": "QI SCD",
            "old_requester_profile_account_number": "4743630",
            "old_requester_profile_account_digit": "1",
            "old_requester_profile_account_branch": "0001",
            "old_pix_key": "2376da91-86ad-4a0b-a466-f0f5acf53e24",
            "total_bank_slip_count": 450,
            "total_amount": 548682.19
        },
        {
            "bank_slip_exchange_batch_key": "6f749806-8768-44ab-b7de-1f0d94d0a61a",
            "request_control_key": "1c1551f2-c6e7-42d5-b78d-1f7662128a33",
            "bank_slip_ownership_exchange_batch_status": "closed",
            "old_requester_profile_key": "8bfdd50f-97fd-4f29-bc53-b542a914f2d6",
            "old_requester_profile_code": "329-09-0001-7390371",
            "old_requester_profile_owner_document_number": "56000040000198",
            "old_requester_profile_name": "Meta",
            "old_requester_profile_account_number": "7390371",
            "old_requester_profile_account_digit": "7",
            "old_requester_profile_account_branch": "0001",
            "old_pix_key": "2376da91-86ad-4a0b-a466-f0f5acf53e24",
            "total_bank_slip_count": 40,
            "total_amount": 67245.96
        }
	],
	"pagination": {
		"current_page": 1,
		"rows_per_page": 100
	}
}
```

## Response Params
| Campo                                         | Tipo  | Descrição                                                                                                                                                                                                                                          | Caracteres                                                                                                          |
|-----------------------------------------------|-------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| `bank_slip_ownership_exchange_batch_key`      | uuidv4 | Chave única de indentificação do lote de tombamento.                                                                                                                                                                                               | 36                                                                                                                  |
| `request_control_key`                         | uuidv4 | Chave única de identificação da requisição neste endpoint. Utilizada para evitar duplicidade na chamada via API.                                                                                                                                   | 36                                                                                                                  |
| `bank_slip_ownership_exchange_batch_status`   | enum  | Status do lote de tombamento.                                                                                                                                                                                                                      | [Enumeradores `bank_slip_ownership_exchange_batch_status`](#enumeradores-bank_slip_ownership_exchange_batch_status) |
| `old_requester_profile_key`                   | uuidv4 | Chave única de identificação da carteira de cobrança de destino, para onde os boletos serão tombados. Você consegue opter essa chave através do [endpoint de consulta de carteiras de cobrança de uma conta](../boletos/carteira/listar_carteiras) | 36                                                                                                                  |
| `old_requester_profile_code`                  | string | Código da carteira de cobrança de destino, para onde os boletos serão tombados.                                                                                                                                                                    | 19                                                                                                                  |
| `old_requester_profile_owner_name`            | string | Nome do titular da conta de destino e do beneficiário da carteira de cobrança de destino.                                                                                                                                                          | 255                                                                                                                 |
| `old_requester_profile_owner_document_number` | string | Número do documento (CPF/CNPJ) do titular da conta de destino e do beneficiário da carteira de cobrança de destino.                                                                                                                                | 255                                                                                                                 |
| `old_requester_profile_account_number`        | string | Número da conta de destino do tombamento.                                                                                                                                                                                                          | 7                                                                                                                   |
| `old_requester_profile_account_digit`         | string | Dígito verificador da conta de destino do tombamento.                                                                                                                                                                                              | 1                                                                                                                   |
| `old_requester_profile_account_branch`        | string | Número da agência da conta de destino do tombamento.                                                                                                                                                                                               | 4                                                                                                                   |
| `old_pix_key`                                 | string | Chave pix da conta de destino do tombamento (para os casos de bolepix).                                                                                                                                                                            | 255                                                                                                                 |
| `total_bank_slip_count`                       | float | Total de boletos no lote de tombamento.                                                                                                                                                                                                            | -                                                                                                                   |
| `total_amount`                                 | float | Somatória do valor de face dos boletos no lote de tombamento.                                                                                                                                                                                      | -                                                                                                                   |                                                                                                                                                                                                               

### Enumeradores bank_slip_ownership_exchange_batch_status
| Enumerador | Descrição                                                                                              |
|------------|--------------------------------------------------------------------------------------------------------|
| open       | O lote foi criado e ainda está aberto para inclusão/exclusão de boletos.                               |
| sent     | A seleção dos boletos foi concluída e o lote de tombamento está pendente de aprovação. A parte aprovadora necessita realizar a aprovação.                  |
| processing | A seleção dos boletos foi concluída e o tombamento dos boletos contidos no lote está sendo processado. |
| approved | Os boletos contidos no lote já foram tombados o destinatário. |
| cancelled   | Lote de tombamento cancelado. |
| rejected | Lote de tombamento rejeitado. |

---

# Listar lotes de tombamento de boletos - origem

URL: /documentation/troca_de_titularidade/listar_lotes_origem

Utilize este endpoint para listar os lotes de tombamento de boletos a partir da conta de origem do tombamento, ou seja, a conta na qual os boletos foram originalmente registrados.

## Request

ENDPOINT /account/ ACCOUNT_KEY /requester_profile/ REQUESTER_PROFILE_KEY /bank_slip_ownership_exchange_batches/outgoing
MÉTODO GET

### Path parameters

| Campo         | Tipo   | Descrição                                                                                                              | Caracteres |
|---------------|--------|------------------------------------------------------------------------------------------------------------------------|------------|
| `ACCOUNT-KEY` | uuidv4 | Chave única de identificação da conta de origem, onde os boletos foram originalmente registrados.                      | 36         |
| `REQUESTER-PROFILE-KEY` | uuidv4 | Chave única de identificação da carteira de cobrança de origem, onde os boletos foram originalmente registrados. | 36         |

### Query parameters

| Campo                | Descrição                                  |
|----------------------|--------------------------------------------|
| `page_number`        | Página atual que está sendo consultada     |
| `page_size`          | Quantidade de resultados por página        |

## Response

STATUS 200

Response Body

```json
{
	"data": [
        {
            "bank_slip_exchange_batch_key": "186e73f1-456f-4265-8cb0-b32722041580",
            "request_control_key": "fa7fa38c-0356-4345-98ef-21a089d9a39a",
            "bank_slip_ownership_exchange_batch_status": "processing",
            "new_requester_profile_key": "01a30518-0b2e-4dd1-a105-8f8bf31868a2",
            "new_requester_profile_code": "329-09-0001-5963550",
            "new_requester_profile_owner_document_number": "02602536000102",
            "new_requester_profile_owner_name": "Coca Cola",
            "new_requester_profile_account_number": "5963550",
            "new_requester_profile_account_digit": "7",
            "new_requester_profile_account_branch": "0001",
            "new_pix_key": "2376da91-86ad-4a0b-a466-f0f5acf53e24",
            "total_bank_slip_count": 200,
            "total_amount": 38145.58
        },
        {
            "bank_slip_exchange_batch_key": "8a5bbded-72ff-4642-8830-f2a5a73eb62c",
            "request_control_key": "d3725802-7e56-4196-8182-2747ea18e96a",
            "bank_slip_ownership_exchange_batch_status": "open",
            "new_requester_profile_key": "316052e8-a017-4fb9-9939-9ce0390fa053",
            "new_requester_profile_code": "329-09-0001-4743630",
            "new_requester_profile_owner_document_number": "40500359000142",
            "new_requester_profile_owner_name": "QI SCD",
            "new_requester_profile_account_number": "4743630",
            "new_requester_profile_account_digit": "1",
            "new_requester_profile_account_branch": "0001",
            "new_pix_key": "2376da91-86ad-4a0b-a466-f0f5acf53e24",
            "total_bank_slip_count": 450,
            "total_amount": 548682.19
        },
        {
            "bank_slip_exchange_batch_key": "6f749806-8768-44ab-b7de-1f0d94d0a61a",
            "request_control_key": "1c1551f2-c6e7-42d5-b78d-1f7662128a33",
            "bank_slip_ownership_exchange_batch_status": "closed",
            "new_requester_profile_key": "8bfdd50f-97fd-4f29-bc53-b542a914f2d6",
            "new_requester_profile_code": "329-09-0001-7390371",
            "new_requester_profile_owner_document_number": "56000040000198",
            "new_requester_profile_name": "Meta",
            "new_requester_profile_account_number": "7390371",
            "new_requester_profile_account_digit": "7",
            "new_requester_profile_account_branch": "0001",
            "new_pix_key": "2376da91-86ad-4a0b-a466-f0f5acf53e24",
            "total_bank_slip_count": 40,
            "total_amount": 67245.96
        }
	],
	"pagination": {
		"current_page": 1,
		"rows_per_page": 100
	}
}
```

## Response Params
| Campo                                         | Tipo  | Descrição                                                                                                                                                                                                                                                                   | Caracteres                                                                                                          |
|-----------------------------------------------|-------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------|
| `bank_slip_ownership_exchange_batch_key`      | uuidv4 | Chave única de indentificação do lote de tombamento.                                                                                                                                                                                                                        | 36                                                                                                                  |
| `request_control_key`                         | uuidv4 | Chave única de identificação da requisição neste endpoint. Utilizada para evitar duplicidade na chamada via API.                                                                                                                                                            | 36                                                                                                                  |
| `bank_slip_ownership_exchange_batch_status`   | enum  | Status do lote de tombamento.                                                                                                                                                                                                                                               | [Enumeradores `bank_slip_ownership_exchange_batch_status`](#enumeradores-bank_slip_ownership_exchange_batch_status) |
| `new_requester_profile_key`                   | uuidv4 | Chave única de identificação da carteira de cobrança de destino. É a carteira de cobrança para onde os boletos serão tombados. Você consegue opter essa chave através do [endpoint de consulta de carteiras de cobrança de uma conta](../boletos/carteira/listar_carteiras) | 36                                                                                                                  |
| `new_requester_profile_code`                  | string | Código da carteira de cobrança de destino. É a carteira de cobrança para onde os boletos serão tombados.                                                                                                                                                                    | 19                                                                                                                  |
| `new_requester_profile_owner_name`            | string | Nome do titular da conta de destino e do beneficiário da carteira de cobrança de destino.                                                                                                                                                                                   | 255                                                                                                                 |
| `new_requester_profile_owner_document_number` | string | Número do documento (CPF/CNPJ) do titular da conta de destino e do beneficiário da carteira de cobrança de destino.                                                                                                                                                         | 255                                                                                                                 |
| `new_requester_profile_account_number`        | string | Número da conta de destino do tombamento.                                                                                                                                                                                                                                   | 7                                                                                                                   |
| `new_requester_profile_account_digit`         | string | Dígito verificador da conta de destino do tombamento.                                                                                                                                                                                                                       | 1                                                                                                                   |
| `new_requester_profile_account_branch`        | string | Número da agência da conta de destino do tombamento.                                                                                                                                                                                                                        | 4                                                                                                                   |
| `new_pix_key`                                 | string | Chave pix da conta de destino do tombamento (para os casos de bolepix).                                                                                                                                                                                                     | 255                                                                                                                 |
| `total_bank_slip_count`                       | float | Total de boletos no lote de tombamento.                                                                                                                                                                                                                                     | -                                                                                                                   |
| `total_amount`                                 | float | Somatória do valor de face dos boletos no lote de tombamento.                                                                                                                                                                                                               | -                                                                                                                   |                                                                                                                                                                                                               

### Enumeradores bank_slip_ownership_exchange_batch_status
| Enumerador | Descrição                                                                                              |
|------------|--------------------------------------------------------------------------------------------------------|
| open       | O lote foi criado e ainda está aberto para inclusão/exclusão de boletos.                               |
| sent     | A seleção dos boletos foi concluída e o lote de tombamento está pendente de aprovação. A parte aprovadora necessita realizar a aprovação.                  |
| processing | A seleção dos boletos foi concluída e o tombamento dos boletos contidos no lote está sendo processado. |
| approved | Os boletos contidos no lote já foram tombados o destinatário. |
| cancelled   | Lote de tombamento cancelado. |
| rejected | Lote de tombamento rejeitado. |

---

# Webhooks de Tombamento de Boletos

URL: /documentation/troca_de_titularidade/notificacoes_webhooks

No fluxo de tombamento, os webhooks são disparados em dois momentos: após o envio do lote para processamento e após a aprovação do lote pela conta de destino.

Essas notificações permitem o acompanhamento do progresso do tombamento, garantindo que o parceiro seja informado quando o lote é enviado para processamento e quando o tombamento é concluído.

## Status do processo de tombamento

### Enviado

WEBHOOK_TYPE baas.bank_slip.bank_slip_ownership_exchange_batch
STATUS sent

Webhook Body

```json
{
  "data": {
    "bank_slip_ownership_exchange_batch_key": "3e8d08df-3585-476f-b464-0897ecf7467d",
    "bank_slip_ownership_exchange_batch_status": "sent"
  },
  "webhook_type": "baas.bank_slip.bank_slip_ownership_exchange_batch",
  "webhook_datetime": "2025-10-21T19:45:47.588Z"
}
```

### Aprovado

WEBHOOK_TYPE baas.bank_slip.bank_slip_ownership_exchange_batch
STATUS approved

Webhook Body

```json
{
  "data": {
    "bank_slip_ownership_exchange_batch_key": "3e8d08df-3585-476f-b464-0897ecf7467d",
    "bank_slip_ownership_exchange_batch_status": "approved"
  },
  "webhook_type": "baas.bank_slip.bank_slip_ownership_exchange_batch",
  "webhook_datetime": "2025-10-21T19:46:34.467Z"
}
```

---

# Remover boletos em um lote de tombamento

URL: /documentation/troca_de_titularidade/remover_boletos

Esse endpoint é utiliza para remover boletos de um lote de tombamento de boletos com status `open`.

## Request

ENDPOINT /account/ ACCOUNT-KEY /requester_profile/ REQUESTER-PROFILE-KEY /bank_slip_ownership_exchange_batch/ BANK-SLIP-OWNERSHIP-EXCHANGE-BATCH-KEY /remove
MÉTODO PATCH

### Path parameters

| Campo                                    | Tipo   | Descrição                                                                                                              | Caracteres |
|------------------------------------------|--------|------------------------------------------------------------------------------------------------------------------------|------------|
| `ACCOUNT-KEY`                            | uuidv4 | Chave única de identificação da conta de origem, onde os boletos foram originalmente registrados.                      | 36         |
| `REQUESTER-PROFILE-KEY`                  | uuidv4 | Chave única de identificação da carteira de cobrança de origem, onde os boletos foram originalmente registrados. | 36         |
| `BANK-SLIP-OWNERSHIP-EXCHANGE-BATCH-KEY` | uuidv4 |Chave única de indentificação do lote de tombamento.| 36         |

Request Body

```json
{
	"bank_slips": [
		"b21c5b5a-a71f-4672-9254-022401cd15f6",
		"8197e3d0-1500-439f-9f9d-d243115542fa",
		"8293b817-bed9-418a-8c1e-ec8ef5a31468"
	]
}
```

:::caution Atenção!
A lista de boletos informada no objeto `bank_slips` no payload, possui uma limitação de 10.000 boletos por requisição. 
:::

## Response

STATUS 200

Response Body

```json
{
    "bank_slip_ownership_exchange_batch_key": "243c9369-ce8b-49df-969c-d891c2fc8c21",
    "request_control_key": "66c9399a-1463-4e2b-acc0-7ee447f81bf0",
    "bank_slip_ownership_exchange_batch_status": "open",
    "new_requester_profile_key": "e494067f-5bd4-4819-b64f-0687bd217f45",
    "new_requester_profile_code": "329-09-0001-8703524",
    "new_requester_profile_owner_name": "Fulano de Tal",
    "new_requester_profile_owner_document_number": "70896538000101",
    "new_requester_profile_account_number": "8703524",
    "new_requester_profile_account_digit": "1",
    "new_requester_profile_account_branch": "0001",
    "new_pix_key": "2376da91-86ad-4a0b-a466-f0f5acf53e24",
    "total_bank_slip_count": 0,
    "total_amount": 0
}
```

## Response Params
| Campo | Tipo | Descrição | Caracteres                                                                                                          |
|---|------|-----------|---------------------------------------------------------------------------------------------------------------------|
| `bank_slip_ownership_exchange_batch_key`      | uuidv4 | Chave única de indentificação do lote de tombamento.                                                                                                                                                                                                                        | 36                                                                                                                  |
| `request_control_key`                         | uuidv4 | Chave única de identificação da requisição neste endpoint. Utilizada para evitar duplicidade na chamada via API.                                                                                                                                                            | 36                                                                                                                  |
| `bank_slip_ownership_exchange_batch_status`   | enum  | Status do lote de tombamento.                                                                                                                                                                                                                                               | [Enumeradores `bank_slip_ownership_exchange_batch_status`](#enumeradores-bank_slip_ownership_exchange_batch_status) |
| `new_requester_profile_key`                   | uuidv4 | Chave única de identificação da carteira de cobrança de destino. É a carteira de cobrança para onde os boletos serão tombados. Você consegue opter essa chave através do [endpoint de consulta de carteiras de cobrança de uma conta](../boletos/carteira/listar_carteiras) | 36                                                                                                                  |
| `new_requester_profile_code`                  | string | Código da carteira de cobrança de destino. É a carteira de cobrança para onde os boletos serão tombados.                                                                                                                                                                    | 19                                                                                                                  |
| `new_requester_profile_owner_name`            | string | Nome do titular da conta de destino e do beneficiário da carteira de cobrança de destino.                                                                                                                                                                                   | 255                                                                                                                 |
| `new_requester_profile_owner_document_number` | string | Número do documento (CPF/CNPJ) do titular da conta de destino e do beneficiário da carteira de cobrança de destino.                                                                                                                                                         | 255                                                                                                                 |
| `new_requester_profile_account_number`        | string | Número da conta de destino do tombamento.                                                                                                                                                                                                                                   | 7                                                                                                                   |
| `new_requester_profile_account_digit`         | string | Dígito verificador da conta de destino do tombamento.                                                                                                                                                                                                                       | 1                                                                                                                   |
| `new_requester_profile_account_branch`        | string | Número da agência da conta de destino do tombamento.                                                                                                                                                                                                                        | 4                                                                                                                   |
| `new_pix_key`                                 | string | Chave pix da conta de destino do tombamento (para os casos de bolepix).                                                                                                                                                                                                     | 255                                                                                                                 |
| `total_bank_slip_count`                       | float | Total de boletos no lote de tombamento.                                                                                                                                                                                                                                     | -                                                                                                                   |
| `total_amount`                                | float | Somatória do valor de face dos boletos no lote de tombamento. | -                                                                                                                   |                                                                                                                                                                                                               

### Enumeradores bank_slip_ownership_exchange_batch_status
| Enumerador | Descrição                                                                                              |
|------------|--------------------------------------------------------------------------------------------------------|
| open       | O lote foi criado e ainda está aberto para inclusão/exclusão de boletos.                               |
| sent     | A seleção dos boletos foi concluída e o lote de tombamento esta pendente de aprovação. A parte aprovadora necessita realizar a aprovação                  |
| processing | A seleção dos boletos foi concluída e o tombamento dos boletos contidos no lote esta sendo processado. |
| approved | Os boletos contidos no lote já foram tombados o destinatário |
| cancelled   | Lote de tombamento cancelado. |
| rejected | Lote de tomabamento rejeitado. |

---

# Enviar lote de tombamento de boletos

URL: /documentation/troca_de_titularidade/validar_lote_e_enviar

Esse endpoint é utilizado para fechar o lote e iniciar o processamento da troca de titularidade. Ao fazer a requisição, o lote será validado e o status alterado para sent, onde ambas as partes envolvidas receberão um webhook relativo ao tombamento.

:::danger Atenção!
Esse endpoint só deve ser acionado caso a inserção dos boletos esteja finalizada e as devidas formalizações entre as contrapartes de origem e destino do tombamento, estejam concluídas. 
:::

## Request

ENDPOINT /account/ ACCOUNT-KEY /requester_profile/ REQUESTER-PROFILE-KEY /bank_slip_ownership_exchange_batch/ BANK-SLIP-OWNERSHIP-EXCHANGE-BATCH-KEY /send
MÉTODO PATCH

### Path parameters

| Campo                                    | Tipo   | Descrição                                                                                                        | Caracteres |
|------------------------------------------|--------|------------------------------------------------------------------------------------------------------------------|------------|
| `ACCOUNT-KEY`                            | uuidv4 | Chave única de identificação da conta de origem, onde os boletos foram originalmente registrados.                | 36         |
| `REQUESTER-PROFILE-KEY`                  | uuidv4 | Chave única de identificação da carteira de cobrança de origem, onde os boletos foram originalmente registrados. | 36         |
| `BANK-SLIP-OWNERSHIP-EXCHANGE-BATCH-KEY` | uuidv4 | Chave única de indentificação do lote de tombamento.                                                             | 36         |

Request Body

```json
{}
```

## Response

STATUS 200

Response Body

```json
{
    "bank_slip_ownership_exchange_batch_key": "243c9369-ce8b-49df-969c-d891c2fc8c21",
    "request_control_key": "66c9399a-1463-4e2b-acc0-7ee447f81bf0",
    "bank_slip_ownership_exchange_batch_status": "processing",
    "new_requester_profile_key": "e494067f-5bd4-4819-b64f-0687bd217f45",
    "new_requester_profile_code": "329-09-0001-8703524",
    "new_requester_profile_owner_name": "Fulano de Tal",
    "new_requester_profile_owner_document_number": "70896538000101",
    "new_requester_profile_account_number": "8703524",
    "new_requester_profile_account_digit": "1",
    "new_requester_profile_account_branch": "0001",
    "new_pix_key": "2376da91-86ad-4a0b-a466-f0f5acf53e24",
    "total_bank_slip_count": 3,
    "total_amount": 750.00
}
```

## Response Params
| Campo | Tipo | Descrição | Caracteres                                                                                                          |
|---|------|-----------|---------------------------------------------------------------------------------------------------------------------|
| `bank_slip_ownership_exchange_batch_key`      | uuidv4 | Chave única de indentificação do lote de tombamento.                                                                                                                                                                                                                        | 36                                                                                                                  |
| `request_control_key`                         | uuidv4 | Chave única de identificação da requisição neste endpoint. Utilizada para evitar duplicidade na chamada via API.                                                                                                                                                            | 36                                                                                                                  |
| `bank_slip_ownership_exchange_batch_status`   | enum  | Status do lote de tombamento.                                                                                                                                                                                                                                               | [Enumeradores `bank_slip_ownership_exchange_batch_status`](#enumeradores-bank_slip_ownership_exchange_batch_status) |
| `new_requester_profile_key`                   | uuidv4 | Chave única de identificação da carteira de cobrança de destino. É a carteira de cobrança para onde os boletos serão tombados. Você consegue opter essa chave através do [endpoint de consulta de carteiras de cobrança de uma conta](../boletos/carteira/listar_carteiras) | 36                                                                                                                  |
| `new_requester_profile_code`                  | string | Código da carteira de cobrança de destino. É a carteira de cobrança para onde os boletos serão tombados.                                                                                                                                                                    | 19                                                                                                                  |
| `new_requester_profile_owner_name`            | string | Nome do titular da conta de destino e do beneficiário da carteira de cobrança de destino.                                                                                                                                                                                   | 255                                                                                                                 |
| `new_requester_profile_owner_document_number` | string | Número do documento (CPF/CNPJ) do titular da conta de destino e do beneficiário da carteira de cobrança de destino.                                                                                                                                                         | 255                                                                                                                 |
| `new_requester_profile_account_number`        | string | Número da conta de destino do tombamento.                                                                                                                                                                                                                                   | 7                                                                                                                   |
| `new_requester_profile_account_digit`         | string | Dígito verificador da conta de destino do tombamento.                                                                                                                                                                                                                       | 1                                                                                                                   |
| `new_requester_profile_account_branch`        | string | Número da agência da conta de destino do tombamento.                                                                                                                                                                                                                        | 4                                                                                                                   |
| `new_pix_key`                                 | string | Chave pix da conta de destino do tombamento (para os casos de bolepix).                                                                                                                                                                                                     | 255                                                                                                                 |
| `total_bank_slip_count`                       | float | Total de boletos no lote de tombamento.                                                                                                                                                                                                                                     | -                                                                                                                   |
| `total_amount`                                | float | Somatória do valor de face dos boletos no lote de tombamento. | -                                                                                                                   |                                                                                                                                                                                                               

### Enumeradores bank_slip_ownership_exchange_batch_status
| Enumerador | Descrição                                                                                              |
|------------|--------------------------------------------------------------------------------------------------------|
| open       | O lote foi criado e ainda está aberto para inclusão/exclusão de boletos.                               |
| closed     | O lote se encontra fechado e o tombamento dos boletos contidos no lote foi concluído.                  |
| processing | A seleção dos boletos foi concluída e o tombamento dos boletos contidos no lote esta sendo processado. |
| pending_approval | A seleção dos boletos foi concluída e o lote de tombamento esta pendente de aprovação. A parte aprovadora, pode remover boletos do lote. |
| canceled   | Lote de tombamento cancelado. |
| rejected | Lote de tomabamento rejeitado. |

---

# Consulta de documentos

URL: /documentation/upload_de_documentos/consulta_documents

A consulta do documento poderá ser feita a partir da requisição:

### Request

ENDPOINT /document/[document_key]/url
MÉTODO GET

### Path Params

| Campo          | Descrição                              |
|--------------- |----------------------------------------|
| `document_key` | Chave única do documento               |

:::caution Atenção
A url do documento será gerada com um prazo de expiração de 10 minutos.
:::

### Response

STATUS 200

Response Body

```json
{
	"document_key": "8a1e62f3-7add-4240-a51d-e0f1a2f421fa",
	"document_url": "url_expirável",
	"signed_document_url": "url_expirável",
	"expiration_datetime": "2024-05-01T01:00:00.000Z"
}
```

| Campo 				| Tipo   | Descrição                                                                                               | 
|-----------------------|--------|---------------------------------------------------------------------------------------------------------|
| `document_url`* 		| string | URL expirável do documento original.                                                                    |
| `signed_document_url` | string | URL expirável do documento assinado se houver. Em caso de não existência não iremos retornar esse campo.|
| `expiration_datetime`*| string | Data e hora do momento em que ocorrerá a expiração das urls.                                            |

---

# Upload de documentos

URL: /documentation/upload_de_documentos/

---

A chamada deve ser autenticada seguindo o padrão descrito na seção [1.1.3. Teste de Autenticação](../primeiros_passos/teste_de_autenticacao). Com as seguintes ressalvas:

- O valor da variável **md5_hash** (**md5_body** para a v1 da nossa autenticação) enviada na assinatura do header deverá ser o MD5 do binário do arquivo que está sendo enviado
- O binário do arquivo deve ser enviado no corpo da request como um FormData utilizando como chave a string "file" e no valor o arquivo a ser enviado. (Este conteúdo não é encriptado)
- No body de resposta dessa chamada será enviado um GUID que é o identificador do documento (chamado de DOCUMENT_KEY daqui para frente) e deve ser armazenado para uso futuro.

---

## Request

ENDPOINT /upload
MÉTODO POST

Response Body

```json
{
  "document_key": "cfbc8469-89ea-4a80-9f64-ba7b1566c68b",
  "document_md5": "cd451103fa512frc98ce684d3896698c"
}
```

:::caution Atenção
Lembrar de salvar a **document_key**, chave essa necessária para a consulta do documento.
:::

## Exemplo de chamada

Exemplo para upload de uma imagem a partir de uma URL.

**Python**

```python

import jwt
import hashlib
import requests
from requests_toolbelt.multipart.encoder import MultipartEncoder
import json
from datetime import datetime

BASE_URL = "https://api-auth.sandbox.qitech.app"
API_KEY = "4c268c0a-53ff-429b-92b6-47ef98a6d89a" # Esta chave é um exemplo, por favor utilize sua própria chave
CLIENT_PRIVATE_KEY = ''''
-----BEGIN EC PRIVATE KEY-----
MIHbAgEBBEHh1hIeOPE5XNNhn6bxRAmVswsPZ0wZCmzVvP8Tl/LZK9ofVmRVGzll
srU1uezJEyHKYdOHrE2p52xUj+pHzjJvb6AHBgUrgQQAI6GBiQOBhgAEAAofUz1J
hBSOyGHLsnV9Sz0DSWmhl7U+ljqbfa8PKVFWSV3w16I1v2zME5/UzUhHn1gWsjnv
7/ekcLLAQbvqMPNXAfjIhFXLAPzqbB9iCuVua1v0Vgy52rBemOWrJka/Ws2bnKR8
h1N1OxOYeYr6C2jqMygBLktKMAs+282CEiEb4bIv
-----END EC PRIVATE KEY----- 
''' # Esta chave é um exemplo, por favor utilize sua própria chave

def get_document(url):
    try:
        response = requests.get(url)
        return response.content
    except Exception as error:
        print("Error fetching document:", error)
        raise

def upload_document(array_buffer):
    endpoint = "/upload"
    method = "POST"
    timestamp = datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
    md5_hash = hashlib.md5(array_buffer).hexdigest()

    jwt_header = {
        "typ": "JWT",
        "alg": "ES512",
    }

    jwt_body = {
        "payload_md5": md5_hash,
        "timestamp": timestamp,
        "method": method,
        "uri": endpoint,
    }

    encoded_header_token = jwt.encode(jwt_body, CLIENT_PRIVATE_KEY, algorithm="ES512", headers=jwt_header)

    signed_header = {
        "Authorization": encoded_header_token,
        "API-CLIENT-KEY": API_KEY,
        "Content-Type": "multipart/form-data",
    }

    url = f"{BASE_URL}{endpoint}"
    multipart_data = MultipartEncoder(
        fields={'file': ('image.jpeg', array_buffer, 'image/jpeg')}
    )
    signed_header['Content-Type'] = multipart_data.content_type

    try:
        response = requests.post(url, headers=signed_header, data=multipart_data)
        response_data = response.json()
        document_key = response_data.get('document_key')
        print(f'Response data is: {response_data} and document_key is: {document_key}')
        return document_key
    except Exception as error:
        print('Error:', error)
        raise

def main():
    file_url = "{FILE_URL}"

    document_buffer = get_document(file_url)

    document_key = upload_document(document_buffer)

    print("document_key is", document_key)

if __name__ == "__main__":
    main()

```
  

**Node.js**

```js
const jwt = require('jsonwebtoken')
const crypto = require('crypto')
const axios = require('axios')
const FormData = require('form-data')
const fs = require('fs')
const fetch = require('node-fetch')

async function getDocument(url) {
  try {
    const response = await axios.get(url, { responseType: 'arraybuffer' })
    return response.data
  } catch (error) {
    console.error('Error fetching document:', error)
    throw error
  }
}

async function uploadDocument(arrayBuffer) {
  const base_url = "[https://api-auth.sandbox.qitech.app](https://api-auth.sandbox.qitech.app)"
  const endpoint = '/upload'
  const method = 'POST'
  const timestamp = new Date().toISOString()
  const md5_hash = crypto.createHash('md5').update(arrayBuffer).digest('hex')
  const client_private_key = `-----BEGIN EC PRIVATE KEY-----
    MIHbAgEBBEHh1hIeOPE5XNNhn6bxRAmVswsPZ0wZCmzVvP8Tl/LZK9ofVmRVGzll
    srU1uezJEyHKYdOHrE2p52xUj+pHzjJvb6AHBgUrgQQAI6GBiQOBhgAEAAofUz1J
    hBSOyGHLsnV9Sz0DSWmhl7U+ljqbfa8PKVFWSV3w16I1v2zME5/UzUhHn1gWsjnv
    7/ekcLLAQbvqMPNXAfjIhFXLAPzqbB9iCuVua1v0Vgy52rBemOWrJka/Ws2bnKR8
    h1N1OxOYeYr6C2jqMygBLktKMAs+282CEiEb4bIv
    -----END EC PRIVATE KEY-----`; // This key is an example, please use your own
  const api_key = '4c268c0a-53ff-429b-92b6-47ef98a6d89a' // This key is an example, please use your own

  try {
    const jwt_header = {
      typ: 'JWT',
      alg: 'ES512',
    }

    const jwt_body = {
      payload_md5: md5_hash,
      timestamp: timestamp,
      method: method,
      uri: endpoint,
    }

    const encoded_header_token = jwt.sign(jwt_body, client_private_key, {
      algorithm: 'ES512',
      header: jwt_header,
    })

    const signed_header = {
      AUTHORIZATION: encoded_header_token,
      'API-CLIENT-KEY': api_key,
    }

    const url = `${base_url}${endpoint}`
    const formData = new FormData()
    formData.append('file', Buffer.from(arrayBuffer), {
      filename: 'image.jpeg',
    })

    const response = await fetch(url, {
      method: 'POST',
      headers: {
        ...signed_header,
        ...formData.getHeaders(),
      },
      body: formData,
    })

    if (!response.ok) {
      const errorText = await response.text()
      console.log(`Error: ${response.status} ${response.statusText}`, errorText)
      return
    }

    const data = await response.json()
    console.log('Response data is: ', data)
    return data.document_key
    
  } catch (error) {
    console.error('Error:', error)
  }
}

async function main() {
  const fileUrl = '<URL_LINK_TO_DOCUMENT_IMAGE>'
  const documentBuffer = await getDocument(fileUrl)
  const documentKey = await uploadDocument(documentBuffer)

  console.log('Document key is: ' + documentKey)
}

main()
```

- OBS: O exemplo acima utiliza a biblioteca [node-fetch](https://www.npmjs.com/package/node-fetch) para realizar a chamada, mas você pode utilizar a biblioteca de sua preferência. O importante é que a chamada seja feita com o método POST, com o header `Content-Type` com o valor `multipart/form-data` e o body seja um FormData com a chave `file` e o valor o binário do arquivo a ser enviado.

:::warning Aviso
A blibioteca 'Axios' está com um bug que faz com que o FormData seja enviado vazio. A issue pode ser vista no [repositório no GitHub](https://github.com/axios/axios/issues/5986). Caso este problema ainda não tenha sido resolvido no momento de sua integração, sugerimos a utilização da biblioteca 'node-fetch' para realizar esta chamada.
:::

---

# acg1

URL: /documentation/webhooks/acg1

Após o envio de uma solicitação de consulta o resto do fluxo fica a cargo da QI Tech. Será então enviado um webhook apresentando dois modelos distintos:

- Em caso de consulta encontrada com sucesso, receberá um campo "status" com o valor "completed", neste caso, o objeto "data" trará as demais informações da consulta.

- Em caso de documento não encontrado na base para o período consultado, receberá um campo "status" com o valor "not_found", informando que a consulta não trouxe nenhuma informação.

----

### Exemplo de sucesso

No webhook temos o objeto "data" com os campos:

**"valueless_months"**: Número de meses sem atividade.
**"card_schemes"**: São os arranjos de pagamentos que constituíram o valor total liquidado.
**"value"**: Valor total liquidado em cartões.

Body.json

```json
{
   "status": "completed",
   "webhook_type": "historic_card_settlement",
   "data": {
      "valueless_months": 0,
      "card_schemes": [
         {
            "code": "003",
            "enumerator": "credit_mastercard",
            "description": "Mastercard Crédito"
         }
      ],
      "value": 847.86
   },
   "event_datetime": "2022-05-18T20:57:00",
   "key": "38934f1b-204f-4fc4-844d-5ad562ff36f6"
}

```

### Em caso de consulta não encontrada 

Body.json

```json
{
   "status": "not_found",
   "webhook_type": "historic_card_settlement",
   "event_datetime": "2022-05-18T20:57:00",
   "key": "38934f1b-204f-4fc4-844d-5ad562ff36f6"
}

```

---

# agenda_de_recebiveis

URL: /documentation/webhooks/agenda_de_recebiveis

O webhook de consulta é divido em agendas que representam uma credenciadora e um arranjo de pagamento.

Em cada agenda, há uma lista de unidades de recebíveis que são divididas por data de liquidação.

Para cada unidade de recebível, existe uma liste de pagamentos aonde esse recebíveis serão depositados.

Body.json

```json
{
   "webhook_type":"cerc_inquiry",
   "inquiry_request_key":"624ca87e-71ec-4dc7-8bc1-823e61d172cb",
   "reference_code":"888888888889",
   "complete_data_url":"https://storage.googleapis.com/dev-cerc-api/inquiry_data/624ca87e-71ec-4dc7-8bc1-823e61d172cb.json",
   "agendas":[
      {
         "acquirer_document_number":"01425787003383",
         "receivable_units":[
            {
               "total_amount":628895.6,
               "total_constituted_amout":null,
               "settlement_date":"2021-08-06"
            },
            {
               "total_constituted_amout":null,
               "settlement_date":"2021-08-05",
               "total_amount":1167245.78
            },
            {
               "settlement_date":"2021-08-09",
               "total_constituted_amout":null,
               "total_amount":625828.02
            },
            {
               "total_amount":618395.21,
               "total_constituted_amout":null,
               "settlement_date":"2021-07-30"
            },
            {
               "total_constituted_amout":null,
               "settlement_date":"2021-08-04",
               "total_amount":587023.86
            },
            {
               "settlement_date":"2021-08-03",
               "total_constituted_amout":null,
               "total_amount":1091400.94
            },
            {
               "settlement_date":"2021-08-02",
               "total_constituted_amout":null,
               "total_amount":495907.37
            },
            {
               "total_constituted_amout":null,
               "total_amount":533202.88,
               "settlement_date":"2021-08-10"
            }
         ],
         "card_scheme_code":"MCC"
      }
   ]
}

```

---

# Webhooks de boletos

URL: /documentation/webhooks/boletos

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

## Introdução

Após a criação de um boleto dentro do nosso sistema, serão enviados webhooks com os seguintes status:

| Enumerador | Tradução | Descrição                      |
|---|---|---|
|  registered  | registrado | boleto registrado e disponível para pagamento.
|  rejected  | rejeitado | solicitação de emissão de boleto rejeitada, quando a solicitação de registro do boleto contem erro de semântica que impede o registro.
|  payment_notice  | aviso de pagamento | aviso de pagamento do boleto, essa notificação é enviada no momento que o boleto é pago, mas ainda não existe a liquidação financeira.
|  notary_office_payment_notice  | aviso de pagamento em cartório | aviso de pagamento do boleto, essa notificação é enviada no momento que o boleto é pago em cartório, mas ainda não existe a liquidação financeira.
|  paid  | pago | boleto pago (baixado com liquidação financeira).
|  written_off  | baixado | boleto baixado sem liquidação financeira.

:::info
O timeout para resposta de nosso webhooks é de 10 segundos.
:::

## Exemplos
----

### Registro

Webhook Body

```json
{
	"key": "11b13b2c-4204-41b3-8596-2ee7ecbde38c",
	"data": {
		"expiration": "2020-11-14",
		"our_number": 11,
		"bank_slip_key": "11b13b2c-4204-41b3-8596-2ee7ecbde38c",
		"rebate_amount": 0,
		"occurrence_type": "registration",
		"occurrence_feedback": "confirmed",
		"occurrence_sequence": 2,
		"requester_profile_code": "329-01-0001-0078570",
		"glados_occurrence_reasons": null,
		"cnab_file_occurrence_order": 1,
		"registration_institution_occurrence_date": "2020-11-11"
	},
	"status": "registered",
	"webhook_type": "bank_slip.status_change",
	"event_datetime": "2020-11-11 21:33:03"
}
```

### Aviso de pagamento

Webhook Body

```json
{
	"key": "03c38d18-d12f-4b5f-841c-afab52fe33c5",
	"data": {
		"our_number": 142,
		"paid_amount": 6676.38,
		"payment_bank": 104,
		"bank_slip_key": "03c38d18-d12f-4b5f-841c-afab52fe33c5",
		"payment_method": 2,
		"payment_origin": 3,
        "paid_in": {
            "name": "QI TECH",
            "code_number": "329",
            "ispb": "32402502"
        },
		"occurrence_type": "payment_notice",
		"occurrence_feedback": "confirmed",
		"occurrence_sequence": 0,
		"requester_profile_code": "329-09-0001-0082162",
		"registration_institution": "qi_scd",
		"cnab_file_occurrence_order": 1,
		"registration_institution_occurrence_date": "2021-04-19"
	},
	"status": "payment_notice",
	"webhook_type": "bank_slip.status_change",
	"event_datetime": "2021-04-19 20:04:06"
}

```

Tradução dos ID's de origem de pagamento:

| ID | Descrição
|---|---|
|  1  | Postos tradicionais.
|  2  | Terminal de Auto-atendimento.
|  3  | Internet(home/office bank).
|  5  | Correspondente bancário.
|  6  | Central de atendimento (call center).
|  7  | Arquivo eletrônico.
|  8  | DDA.
|  9  | Correspondente Digital.
|  901  | Pagamento via Pix QR Code.

### Pagamento

Webhook Body: Pagamento via QR Code

```json
{
	"key": "505fd25f-89cf-40ca-927c-3800f207146a",
	"data": {
		"agent_type": "system",
		"our_number": 69993012,
		"origin_type": "qr_code",
		"paid_amount": 551.5,
		"payment_bank": "329",
		"bank_slip_key": "505fd25f-89cf-40ca-927c-3800f207146a",
		"payment_branch": "0001",
		"payment_method": "2",
		"payment_origin": "901",
		"discount_amount": 0.0,
		"occurrence_type": "payment",
		"payment_account": "1727560-2",
		"payment_bank_ispb": "32402502",
		"occurrence_reasons": [289],
		"occurrence_feedback": null,
		"occurrence_sequence": "0",
		"payment_credit_date": "2023-01-10",
		"selected_user_agent": null,
        "paid_in": {
            "name": "QI TECH",
            "code_number": "329",
            "ispb": "32402502"
        },
		"paid_interest_amount": 0.0,
		"requester_profile_code": "329-01-0001-0000002",
		"registration_institution": "qi_scd",
		"cnab_file_occurrence_order": 1,
		"registration_institution_occurrence_date": "2023-01-10"
	},
	"status": "paid",
	"webhook_type": "bank_slip.status_change",
	"event_datetime": "2023-01-10 14:08:46"
}

```

Webhook Body: Pagamento via linha digitável

```json
{
	"key": "94cbc702-df42-4a84-bd03-d80728cde1e9",
	"data": {
		"our_number": 69993325,
		"paid_amount": 261.49,
		"payment_bank": 329,
		"protocol_date": null,
		"payment_branch": "0001",
		"discount_amount": 0.0,
		"occurrence_type": "payment",
        "paid_in": {
            "name": "QI TECH",
            "code_number": "329",
            "ispb": "32402502"
        },
		"paid_fine_amount": null,
		"occurrence_sequence": "2",
		"payment_credit_date": "2023-02-03",
		"notary_office_number": null,
		"paid_interest_amount": 0.0,
		"notary_office_protocol": null,
		"requester_profile_code": "329-01-0001-0000002",
		"cnab_file_occurrence_order": 1,
		"registration_institution_enumerator": "qi_scd",
		"registration_institution_occurrence_date": "2023-02-02"
	},
	"status": "paid",
	"webhook_type": "bank_slip.status_change",
	"event_datetime": "2023-02-03 07:00:27"
}

```

Tradução dos ID's de origem de pagamento:

| ID | Descrição
|---|---|
|  1  | Postos tradicionais.
|  2  | Terminal de Auto-atendimento.
|  3  | Internet(home/office bank).
|  5  | Correspondente bancário.
|  6  | Central de atendimento (call center).
|  7  | Arquivo eletrônico.
|  8  | DDA.
|  9  | Correspondente Digital.
|  901  | Pagamento via Pix QR Code.

### Baixa

Webhook Body

```json
{
	"key": "93e58a9a-287b-4bf2-9cdc-5467a9d3d9bf",
	"data": {
		"expiration": "2021-05-17",
		"our_number": 113,
		"bank_slip_key": "93e58a9a-287b-4bf2-9cdc-5467a9d3d9bf",
		"rebate_amount": 0,
		"occurrence_type": "write_off",
		"occurrence_reasons": [],
		"occurrence_feedback": "confirmed",
		"occurrence_sequence": 3,
		"requester_profile_code": "329-09-0001-0082162",
		"glados_occurrence_reasons": null,
		"cnab_file_occurrence_order": 1,
		"registration_institution_occurrence_date": "2021-04-20"
	},
	"occurrence_reason": {
		"bank_reason_code": "16",
		"bank_reason_name": "Título Baixado pelo Banco por decurso de Prazo"
	},
	"status": "written_off",
	"webhook_type": "bank_slip.status_change",
	"event_datetime": "2021-04-20 11:55:09"
}

```

Tradução dos motivos da ocorrência de baixa:

| Código | Descrição
|---|---|
|  00  | Ocorrência Aceita.
|  10  | Baixa Comandada pelo cliente.
|  14  | Título Protestado.
|  16  | Título Baixado pela Instituição Financeira por decurso Prazo.
|  20  | Título Baixado e Transferido para Desconto.

---

# Webhooks de dívida

URL: /documentation/webhooks/dividas

:::info Informação
O timeout para resposta de nosso webhooks é de 5 segundos.
:::

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

## Webhook de assinatura finalizada

Response Body

```json
{
    "key": "ebe12ca1-ec34-4674-bd62-24c0bc204e81",
    "status": "signature_finished",
    "webhook_type": "debt",
    "event_datetime": "2024-09-02 18:39:49",
    "signed_contract_url": "https://storage.googleapis.com/live-doc-api/documents/6099edd7-1c83-4890-998e-ce60e218523cb/S_signed.pdf"
}

```

## Webhook de desembolso.

Response Body

```json
{
    "key": "bb81d525s-aa4b-4ddf-81d6-aa4b41fd04nb",
    "data": {
        "installments": [
        {
            "due_date": "2025-11-24",
            "total_amount": 8304.16,
            "installment_key": "7ec2f4d-b21e-4bd5-ahs6-60e998267249",
            "pre_fixed_amount": 2475.77421509,
            "installment_number": 1,
            "principal_amortization_amount": 5828.23857532
        },
        {
            "due_date": "2025-12-22",
            "total_amount": 8304.16,
            "installment_key": "54g37d78-a9a9-bf82-9f8e-fd3ba123797a",
            "pre_fixed_amount": 2001.06342502,
            "installment_number": 2,
            "principal_amortization_amount": 6303.43346322
        }
        ],
        "ted_receipt_list": [
        {
            "fee": 0,
            "url": "https://storage.storage.com/sandbox-doc-api/documents/f9as9329-22bd-4dbg-91a2-f2sdgeth4h04/fheth459-bhrf-4hrt-9hra-fdsfsgehth42.pdf",
            "amount": 123456.0,
            "origin": {
            "name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A.",
            "type": "payment_account",
            "branch": "0001",
            "document": "32402502000777",
            "bank_code": "329",
            "account_key": "5d068423-7774-49e4-b15b-7741238df5a8",
            "branch_digit": null,
            "account_digit": "5",
            "account_branch": "0001",
            "account_number": "00002",
            "financial_institution_name": "QI SOCIEDADE DE CRÉDITO DIRETO S.A."
            },
            "timestamp": "2025-10-26T17:00:51",
            "description": "60701190 8615 22110-2 96969879003 - Alan Mathison Turing",
            "destination": {
            "name": "Alan Mathison Turing",
            "type": "checking_account",
            "branch": "8612",
            "purpose": "Crédito PIX em Conta",
            "document": "96972379003",
            "bank_ispb": "60111190",
            "branch_digit": null,
            "account_digit": "2",
            "account_number": "44110",
            "financial_institution_name": "BANCO S.A."
            },
            "end_to_end_id": "E32402402200510221300gNgeefVNtVr",
            "transaction_key": "25044504-1902-412a-a445-23b813bee6c1",
            "origin_transaction_key": "542224ea-b5ea-49ff-b7b7-673b81af387b"
        }
        ],
        "requester_identifier_key": null
    },
    "status": "disbursed",
    "webhook_type": "debt",
    "event_datetime": "2025-10-26 17:00:52"
    }
```

:::info Importante
    Quando os boletos de uma dívida são gerados, é enviado outro webhook: [Webhook de parcelas](/documentation/webhooks/parcelas)
:::

## Webhook de cancelamento.

Response Body

```json
{
     "webhook_type": "debt",
     "key":"27a099df-4688-43cb-87fa-515b1cf343a5",
     "event_datetime": "2022-09-27 07:03:49",
    "data": {
        "cancel_reason": "Operacao cancelada manualmente",
        "cancel_reason_enumerator": "manual"
    },
     "status":"canceled "
  }

```

## Webhook de contrato quitado:

Response Body

```json
{
    "key": "27a099df-4688-43cb-87fa-515b1cf343a5",
    "data": {
        "settlement_amount": 3429.38
    },
    "status": "settled",
    "webhook_type": "debt",
    "event_datetime": "2022-09-27 07:03:49"
}
```

----

### Motivos de cancelamento

| cancel_reason_enumerator | Descrição | 
|---|---|
|disbursing_error|Operação cancelada por erro no momento do desembolso.
|waiting_signature |	Operação cancelada por falta de assinatura.
|is_portability|A operação foi cancelada pois é uma portabilidade que não foi concluída.
|not_collateral_constituted	| A operação foi cancelada pois as garantias não foram constituídas.
|entry_not_paid| A operação foi cancelada pois a entrada não foi paga.
|not_assigned |Operação foi cancelada porque o processo de cessão não foi realizado.
|pix_max_retry|Operação cancelada pois o banco recebedor não conseguiu receber o desembolso.
|lack_of_resource |Operação cancelada por falta de recurso.
|manual|Operação cancelada manualmente.
|kyc_not_accepted|Operação cancelada pois não foi aprovada no compliance.
|not_collateral_fgts|Operação cancelada por erro com FTGS.
|agencia_conta_invalida	|Agência ou Conta Destinatária do Crédito Inválida.
|not_assigned	|Operação foi cancelada porque o processo de cessão não foi realizado.
|invalid_account|	Número da conta de destino é inexistente ou inválido.
|invalid_document_number	|CPF/CNPJ da conta de destino está incorreto.
|unsupported_transaction	|A conta de destino não suporta este tipo de transação.
|bank_slip_payment	|Operação cancelada por erro no pagamento do boleto.
|bank_slip_paid	|Operação cancelada pois o boleto já está pago.
|bank_slip_written_off	|Operação cancelada pois o boleto já está baixado.
|invalid_ispb	|Número ISPB é inválido ou inexistente.
|rejected_payment|	Ordem de pagamento foi rejeitada pelo banco recebedor.
|disbursed_amount_refunded| Operação cancelada devido a devolução do valor de desembolso|

---

# Webhooks de gestão de risco

URL: /documentation/webhooks/gestao_de_risco

O `risk_amount` corresponde ao saldo devedor das operações ainda **não cedidas** — ou seja, a exposição em aberto da carteira que permanece sob risco e que consome o limite (`limit_amount`) disponível para novos desembolsos. Conforme as operações são cedidas ou quitadas, elas deixam de compor o `risk_amount` e liberam limite para novos desembolsos.

:::danger Regra de desembolso
Se `risk_amount + issue_amount > limit_amount`, a operação não será desembolsada.
:::

:::tip Habilitação
Entre em contato com o time da QI Tech para configurarmos o envio!
:::

## Webhook de atualização de risco

Enviado periodicamente, **a cada hora**, com a atualização do valor de risco acumulado do cliente.

Response Body

```json
{
    "key": "b3a7e2c4-9d1f-4e8a-a456-2c3d4e5f6a7b",
    "data": {
        "risk_amount": 1500000,
        "limit_amount": 9000000,
        "reconciled_at": "2025-09-15T20:24:41"
    },
    "status": "completed",
    "webhook_type": "risk_management.risk_updated",
    "event_datetime": "2025-09-15T20:24:41Z"
}
```

## Webhook de atualização de limite

Enviado quando o limite de emissão de dívidas do cliente é atualizado.

Response Body

```json
{
    "key": "c4b8f3d5-0e2a-5f9b-b567-3d4e5f6a7b8c",
    "data": {
        "risk_amount": 0,
        "limit_amount": 9000000,
        "reconciled_at": "2025-09-15T18:03:54"
    },
    "status": "completed",
    "webhook_type": "risk_management.limit_updated",
    "event_datetime": "2025-09-15T18:03:54Z"
}
```

## Definições

### Objeto callback

| Campo | Tipo | Descrição | Obrigatório |
|-------|------|-----------|-------------|
| **event_datetime** | string | Data e hora do evento no formato ISO 8601 UTC | Sim |
| **key** | string | Chave única do evento | Sim |
| **status** | string | Status do evento | Sim |
| **webhook_type** | string | Tipo do webhook (`risk_management.risk_updated` ou `risk_management.limit_updated`) | Sim |
| **data** | object | Dados específicos do evento de gestão de risco | Sim |

### Objeto data

| Campo | Tipo | Descrição | Obrigatório |
|-------|------|-----------|-------------|
| **risk_amount** | number | Saldo devedor das operações ainda não cedidas — exposição em aberto da carteira que consome o limite disponível | Sim |
| **limit_amount** | number | Limite total disponível para emissão de novas dívidas | Sim |
| **reconciled_at** | string | Data e hora da última reconciliação no formato ISO 8601 | Sim |

---

# Webhooks de indevidos

URL: /documentation/webhooks/indevidos

:::info Informação
O timeout para resposta de nossos webhooks é de 5 segundos.
:::

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

## Introdução

Estes webhooks são disparados automaticamente quando a QI Tech identifica e processa a devolução de um valor indevido.

## Webhook de sucesso na devolução de indevidos

Response Body

```json
{
    {
        "event_datetime": "2024-01-15T14:30:00.000Z",
        "key": "fb34e0ac-2c98-47e7-9040-406b8c3d80e7",
        "status": "refunded",
        "webhook_type": "laas.devolution.refund_receipt",
        "data": {
            "origin_key":"b41c63e4-6912-4217-9111-a47dd4da9588",
            "devolution_key": "336f0e15-e7b8-45a4-8986-5411434be76a",
            "devolution_amount": 150.75,
            "devolution_status": "refunded",
            "devolution_reason_description": "The payment arrived earlier than expected. The difference between the paid amount and the present value should be refund",
            "receipt_url": "https://storage.googleapis.com/receipts/devolution_receipt_12345.pdf",
            "document_key": "cd27a0c3-630d-4682-81b2-71b5b325bcde",
            "transacted_at": "2024-01-15T14:25:30.000Z",
            "devolution_origin_type":"social_security"
        }
    }
}
```

## Webhook de falha na devolução de indevidos

Response Body

```json
{
    {
        "event_datetime": "2024-01-15T14:30:00.000Z",
        "key": "fb34e0ac-2c98-47e7-9040-406b8c3d80e7",
        "status": "error",
        "webhook_type": "laas.devolution.refund_failed",
        "data": {
            "origin_key":"b41c63e4-6912-4217-9111-a47dd4da9588",
            "devolution_key": "336f0e15-e7b8-45a4-8986-5411434be76a",
            "devolution_amount": 150.75,
            "devolution_status": "error",
            "devolution_reason_description": "The payment arrived earlier than expected. The difference between the paid amount and the present value should be refund",
            "devolution_origin_type":"social_security"
        }
    }
}
```

# Retentativa de devolução

No caso de falha na devolução, é possível realizar uma chamada para retentar a transferência. 

Enviando os dados bancários, será feita a retentativa inicialmente por pix na conta informada, no caso de falha, será realizada uma segunda tentativa através de chave pix cpf. 
É possível realizar a retentativa diretamente por chave pix cpf.

PATCH
/devolution/DEVOLUTION-KEY/retry

**Request Body**

**Informando dados bancários**

```json
{
    "issuer_name":"John Doe",
    "document_number": "14471835092",
    "bank_account": {
      "account_branch":"0001",
      "account_number":"12345",
      "account_digit":"9",
      "bank_code":"001",
      "ispb":"00000000",
      "account_type":"checking"
    },
}
```

**Por chave pix cpf**

```json
{ 
    "use_only_document_number_pix_key": true
}
```

# Consulta de devolução

### Query Parameters

| Parâmetro             | Tipo      | Obrigatório | Descrição                                       | Valor Padrão |
|-----------------      |---------  |-------------|-------------------------------------------      |--------------|
| document_number       | string    | Não         | documento do tomador da dívida                  |               |
| credit_operation_key  | uuid      | Não         | Chave única da operação de crédito              |               |
| origin_key            | uuid      | Não         | Chave de referência do recurso devolvido        |               |
| status                | sring     | Não         | Status da devolução                             |               |
| start_date            | date      | Não         | Data de criação da devolução (YYYY-mm-dd)       |               |
| end_date              | date      | Não         | Data de criação da devolução (YYYY-mm-dd)       |               |
| page                  | integer   | Não         | Número da página a ser retornada                | 1             |
| page_size             | integer   | Não         | Quantidade de registros por página              | 25            |

:::info
A paginação é baseada em um, portanto a primeira página é a página 1.
:::

GET
/devolutions

**Request Body**

```json
{
    "data": [
        {
            "devolution_key": "336f0e15-e7b8-45a4-8986-5411434be76a",
            "document_number": "03047465096",
            "devolution_amount": 150.75,
            "status": "refunded",
            "origin_type": "social_security",
            "devolution_reason": "The payment arrived earlier than expected. The difference between the paid amount and the present value should be refund",
            "receipt_url":"https://storage.googleapis.com/receipts/devolution_receipt_12345.pdf",
            "credit_operation_key": "fb34e0ac-2c98-47e7-9040-406b8c3d80e7",
            "origin_key": "b41c63e4-6912-4217-9111-a47dd4da9588",
            "created_at": "2024-01-15T14:30:00.000Z",
        }
    ],
    "pagination": {
        "current_page": 1,
        "next_page": 2,
        "rows_per_page": 100,
    }
}
```

## Definições

### Objeto callback

| Campo | Tipo | Descrição | Obrigatório |
|-------|------|-----------|-------------|
| **event_datetime** | string | Data e hora do evento no formato ISO 8601 UTC | Sim |
| **key** | string | Chave única da operação de crédito | Sim |
| **status** | string | Status da devolução | Sim |
| **webhook_type** | string | Tipo do webhook | Sim |
| **data** | object | Dados específicos da devolução | Sim |

### Objeto data

| Campo | Tipo | Descrição | Obrigatório |
|-------|------|-----------|-------------|
| **origin_key** | string | Chave de referência do recurso devolvido | Sim |
| **devolution_key** | string | Chave única da devolução | Sim |
| **devolution_amount** | number | Valor da devolução em reais | Sim |
| **devolution_status** | string | Status atual da devolução | Sim |
| **devolution_reason_description** | string | Descrição do motivo da devolução | Sim |
| **receipt_url** | string | URL do comprovante da devolução | Sim |
| **document_key** | string | Chave do documento relacionado | Sim |
| **transacted_at** | string | Data e hora da transação no formato ISO 8601 UTC | Sim |
| **devolution_origin_type** | string | Origem do recurso da devolução, consulte os possíveis enumeradores na tabela [Possíveis enumeradores de devolution_origin_type](#devolution_origin_type) | Sim |

## Possíveis enumeradores de devolution_origin_type {#devolution_origin_type}

| Status | Descrição |
|--------|-----------|
| **fgts_conciliation**             | Desconto indevido associado ao repasse de FGTS |
| **ss_conciliation**               | Desconto indevido associado ao repasse de INSS |
| **private_payroll_conciliation**  | Desconto indevido associado ao repasse de Consignado Privado |
| **military_payroll_conciliation** | Desconto indevido associado ao repasse de Exército |
| **federal_payroll_conciliation**  | Desconto indevido associado ao repasse de SIAPE |
| **payroll_card_discount**         | Desconto indevido associado ao repasse de Cartão Consignado |
| **renegotiation**                 | Desconto indevido associado a renegociação |

## Status possíveis

| Status                    | Descrição |
|--------                   |-----------|
| **refunded**              | Devolução processada com sucesso      |
| **error**                 | Devolução processada sem sucesso      |
| **pending**               | Devolução ainda não processada        |
| **refund_reversed**       | Devolução estornada                   |

---

# notificacoes_baas_e_laas

URL: /documentation/webhooks/notificacoes_baas_e_laas

---- 

A QI Tech possui um sistema de webhooks para informar o status dos processos que ocorrem de forma assíncrona ou offline, eles estão divididos por categorias de acordo com as sessões que atendem.

:::caution Atenção!

Nossos webhooks podem ser enviados mais de uma vez (em casos de timeout, por exemplo), como também podem não ser enviados de forma ordenada.
:::

---- 

### Operações de crédito:
#### Contratos:
- Contrato aguardando assinatura;
- Contrato assinado;

#### Desembolso:
- Operação desembolsada;
- Operação cancelada;
- Contrato quitado (Configurada mediante a solicitação);
#### Parcelas (Configurada mediante a solicitação):
- Parcela em aberto
- Parcela Paga
- Parcela aguardando pagamento;
- Parcela paga antecipadamente;
- Parcela vencida;
- Parcela paga parcialmente após o vencimento;
- Parcela paga após o vencimento
#### Boletos:
- Solicitação de registro criada;
- Boleto registrado;
- Notificação de pagamento;
- Boleto pago;
- Boleto baixado;
- Boleto rejeitado;
- Boleto pago em cartório;
#### SCR:
- Resultado da consulta;

---- 

### Como confirmar o recebimento de uma notificação?

Para confirmar o sucesso no recebimento é necessário que o status da resposta seja 200 e que exista uma resposta assinada para a notificação semelhante a enviada em requisições.

Ou seja, deverá ter um response_body no formato **\{"encoded_body": "payloadEmJWT"\}** e um response header **Authorization**. Neste header a diferença única é que no path você deve colocar o endpoint de recebimento da notificação.

Caso não exista uma confirmação de recebimento o mecanismo de redundância dos webhooks será acionado.

---- 

### Redundância
Possuímos um mecanismo de redundância nas notificações enviadas que gera 3 retentivas, uma a cada 5 minutos.

---

# Webhooks de pagamento de parcelas

URL: /documentation/webhooks/pagamento_de_parcela

:::info Informação
O timeout para resposta de nosso webhooks é de 10 segundos.
:::

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

----
### Exemplo de webhook de parcela paga

```json
{
    "key": "4219cb7b-32b9-45d1-b19c-24fbca04ca02",
    "webhook_type": "laas.credit_operation.installment.payment",
    "event_datetime": "2026-01-14 04:08:30",
    "data": {
        "installment_key":"1234cb7b-3329-12d1-429c-24f84975ca02",
        "reference_date":"2026-02-13",
        "paid_at":"2026-02-13 20:38:07",
        "paid_method_type":"pix",
        "installment_status":"paid_early",
        "installment_payment_key":"2accee19-ed22-43f9-9573-3b6232658337",
        "paid_amount":567.73,
        "total_amount":567.73,
        "present_total_amount":567.73,
        "prefixed_interest_payment_amount":556.73948769,
        "principal_amortization_payment_amount":10.99051231,
        "resource_account_key":"422cee19-ed22-43f9-9573-3b6111658337",
        "batch_renegotiation_proposal_key":null,
        "renegotiation_proposal_key":null,
        "received_portability_key":null,
        "refinancing_credit_operation_key":null,
        "bank_slip_key":null,
        "pix_qrcode_key":"3b61ee19-ed22-6119-9573-3b6119573337",
        "paid_in":{
                "name": "ITAÚ UNIBANCO S.A.",
                "code_number": 341,
                "ispb": 60701190
            }
    },
}
```

## Anexo

### Descritivo dos campos {#paid_method}

|Campo                                  | Tipo              | Descrição     |
|-------------------------------------- |------             |-----          |
|key                                    |UUID               |chave identificadora da dívida (credit_operation_key ou DEBT_KEY)|
|installment_key                        |UUID               |chave identificadora da parcela|
|reference_date                         |Date               |Data de referência para o cálculo do saldo devedor da parcela|            
|paid_at                                |DateTime           |Data do pagamento|        
|paid_method_type                       |string             |Método de pagamento, consulte os possíveis enumeradores na tabela [Enumeradores para paid_method_type](#paid_method)|                
|installment_status                     |string             |Status da parcela, consulte os possíveis enumeradores na tabela [Enumeradores para installment_status](#installment_status)|
|installment_payment_key                |UUID               |Chave única do pagamento|                        
|paid_amount                            |decimal            |Valor pago|            
|total_amount                           |decimal            |Valor total da parcela, em caso de pagamento parcial é atualizado com o valor em aberto|            
|present_total_amount                   |decimal            |Valor presente na data de referência (reference_date)|                    
|prefixed_interest_payment_amount       |decimal            |Valor do pagamento referente à amortização de juros|                    
|principal_amortization_payment_amount  |decimal            |Valor do pagamento referente à amortização de principal|                    
|resource_account_key                   |UUID               |Conta de origem do saldo utilizado na liquidação|                    
|batch_renegotiation_proposal_key       |UUID               |Chave da renegociação em lote, se aplicável|                                
|renegotiation_proposal_key             |UUID               |Chave da renegociação, se aplicável|                        
|refinancing_credit_operation_key       |UUID               |Chave da operação de refinanciamento, se aplicável|                        
|received_portability_key               |UUID               |Chave da portabilidade recebida, se aplicável|                        
|bank_slip_key                          |UUID               |Chave do boleto registrado com a parcela, se aplicável|                        
|pix_qrcode_key                         |UUID               |Chave da pix qr code registrado com a parcela, se aplicável|                        
|paid_in                                |objeto             |Informações do banco pagador, aplicável nos casos de pagamento por pix ou boleto|                        

:::warning Valor de multa e mora do pagamento
O valor de multa+mora (fine_amount) do pagamento pode ser identificado através da fórmula:

fine_amount = paid_amount - prefixed_interest_payment_amount - principal_amortization_payment_amount.
:::

### Enumeradores para paid_method_type {#paid_method}

| Enumerador            | Descrição         |
|-----------------------|--------           |
|bankslip               | Boleto            |
|ted                    | ted               |
|pix                    | pix               |
|refinancing            | refinanciamento   |
|portability            | portabilidade     |
|unmonitored            | baixa manual      |
|collateral             | colateral         |

### Enumeradores para installment_status {#installment_status}

| Enumerador                            | Descrição   |
|-----------------------                |--------     |
|created                                | aberta    |      
|opened                                 | aberta    |  
|waiting_payment                        | aberta aguardando pagamento na data de vencimento |              
|paid_partial                           | paga parcialmente |          
|paid                                   | paga |  
|paid_early                             | paga adiantada |      
|overdue                                | atrasada |      
|paid_partial_overdue                   | paga parcialmente atrasada |                  
|paid_overdue                           | paga atrasada |          
|canceled                               | cancelada |      
|unmonitored                            | aberta |          
|waiting_payment_confirmation           | aguardando liquidação de refinanciamento |                          

:::warning Pago parcialmente adiantado
Repare que não existe o status de pago adiantado parcialmente, caso haja uma baixa parcial com data de referência anterior ao vencimento da parcela, o status anterior se mantém (unmonitored ou opened).
:::

---

# Webhooks de parcelas

URL: /documentation/webhooks/parcelas

:::info Informação
O timeout para resposta de nosso webhooks é de 10 segundos.
:::

:::danger Atenção!
Os webhooks da QI Tech não devem ser mapeadas de forma restrita. 
Campos adicionais podem ser incluídos aos payloads dos webhooks retornados em nossas APIs.
:::

:::info Reenvio de Webhooks
Você pode consultar e reenviar webhooks seguindo as instruções detalhadas na documentação: [Reenvio de Webhooks](/documentation/notificacoes/reenvio_de_notificacoes).
:::

Essa configuração pode ser habilitada quando a QI Tech é o agente de cobrança da operação, com ela você receberá as mudanças de status nas parcelas da operação.

Os status que podem ser configurados são:

- **opened** (aberto)
- **paid** (pago)
- **waiting_payment** (aguardando pagamento)
- **paid_early** (pago antecipadamente)
- **paid_partial** (pago parcialmente)
- **overdue** (vencido)
- **paid_partial_overdue** (pago parcialmente após o vencimento)
- **paid_overdue** (pago após o vencimento)

----
### Exemplo de webhook de parcela paga

Body.json

```json
{
    "key": "92a05d9c-e457-4f28-9fa8-86be638ee2d0",
    "data": {
        "status": "paid",
        "installment": {
            "events": [{
                "amount": 1009.68,
                "created_at": "2022-09-27T07:03:35",
                "event_date": "2022-09-27T07:03:34",
                "old_due_date": null,
                "installment_event_type": {
                    "enumerator": "payment",
                    "translation_path": "co.InstallmentEventType.payment"
                },
                "installment_old_status": {
                    "enumerator": "opened",
                    "translation_path": "co.InstallmentStatus.opened"
                }
            }],
            "paid_at": "2022-09-27T07:03:34",
            "due_date": "2022-10-28",
            "workdays": 21,
            "created_at": "2022-08-27T10:54:18",
            "tax_amount": 5.11785875,
            "updated_at": "2022-09-27T07:03:35",
            "fine_amount": null,
            "paid_amount": 1009.68,
            "qr_code_key": "92a05d9c-e457-4f28-9fa8-86be638ee2d0",
            "qr_code_url": "https://qitech.com.br/",
            "due_interest": 0,
            "has_interest": true,
            "payment_type": {
                "enumerator": "bankslip",
                "translation_path": "co.PaymentType.bankslip"
            },
            "total_amount": 1009.68,
            "bank_slip_key": "92a05d9c-e457-4f28-9fa8-86be638ee2d0",
            "calendar_days": 30,
            "due_principal": 1006.66428708,
            "digitable_line": "32990001031000699917042000000200291520000100968",
            "installment_key": "92a05d9c-e457-4f28-9fa8-86be638ee2d0",
            "additional_costs": [],
            "installment_type": {
                "enumerator": "principal",
                "translation_path": "co.InstallmentType.principal"
            },
            "pre_fixed_amount": 3.02013568,
            "business_due_date": "2022-10-31",
            "cetip_settlements": [],
            "post_fixed_amount": 0,
            "total_paid_amount": 0,
            "installment_number": 3,
            "installment_status": {
                "enumerator": "paid",
                "translation_path": "co.InstallmentStatus.paid"
            },
            "installment_payment": [{
                "created_at": "2022-09-27T07:03:35",
                "installment_payment_key": "f03e1fbc-6d7a-456b-bd6a-db0faac1b481",
                "paid_at": "2026-02-10T11:39:07",
                "paid_amount": 1009.68,
                "total_amount": 1009.68,
                "due_principal": 1006.66428708,
                "reference_date": "2022-09-27",
                "paid_method_type": {
                    "enumerator": "pix",
                    "translation_path": "co.PaymentType.pix"
                },
                "payment_data":{
                    "resource_account_key": "0fcc076f-f5e4-422c-aabd-67dbb63b7fb0",
                    "paid_in":{
                        "name": "ITAÚ UNIBANCO S.A.",
                        "code_number": 341,
                        "ispb": 60701190
                    }
                },
                "pre_fixed_amount": 3.02013568,
                "advanced_paid_amount": 0,
                "present_total_amount": 1009.68,
                "renegotiation_proposal_key": null,
                "principal_amortization_amount": 1006.65986432,
                "prefixed_interest_payment_amount": 3.02013568,
                "principal_amortization_payment_amount": 1006.65986432
            }],
            "advanced_paid_amount": 0,
            "total_accrual_amount": 0,
            "original_total_amount": 1009.68,
            "accrual_reference_date": "2022-09-27",
            "original_due_principal": 1006.66428708,
            "original_pre_fixed_amount": 3.02013568,
            "renegotiation_proposal_key": null,
            "principal_amortization_amount": 1006.65986432,
            "original_principal_amortization_amount": 1006.65986432
        },
        "is_finished": true
    },
    "webhook_type": "installment.status_change"
}

```

### Exemplo de webhook de criação de boletos para pagamento de parcelas
Body.json

```json
{
    "key": "96015228-4905-42fc-bda6-e70e0e552b6b",
    "webhook_type": "installment.status_change",
    "data": {
        "status": "update",
        "installments": [
            {
                "installment_key": "bc60ad8e-4dc1-4edc-8c5b-6df1b5c9415d",
                "digitable_line": "32990001455000000000503007797909797660000100000",
                "qr_code_key": "7d20015e-c4ed-4290-b255-33c1c5b56362",
                "qr_code_url": "00020126580014br.gov.bcb.pix0136dc4a27db-2fe1-474d-aa02-88d6fffb8d0d5204000053039865802BR5921NeymarSportEMarketing6008saopaulo62070503***63040EB2",
                "principal_amortization_amount": 141.07452576,
                "pre_fixed_amount": 72.89547424,
                "bank_slip_key": "5f25e9fd-f612-47a3-acff-be9f29d87f6c",
                "due_date": "2024-07-17",
                "total_amount": 216.97
            },
            {
                "principal_amortization_amount": 144.84483469,
                "pre_fixed_amount": 65.12516531,
                "due_date": "2024-08-19",
                "digitable_line": "32990001454000000000627007797908997530000500000",
                "installment_key": "be3f0fde-24ac-42d2-82e9-4b0aa15bf01e",
                "qr_code_key": "4d696847-73a2-4dba-be9f-218084dff8e7",
                "qr_code_url": "00020126580014br.gov.bcb.pix0136dc4a27db-2fe1-474d-aa02-88d6fffb8d0d5204000053039865802BR5921NeymarSportEMarketing6008saopaulo62070503***63040EB2",
                "total_amount": 216.97,
                "bank_slip_key": "bc1cc18f-2db5-470d-8541-b944e53cb699"
            },
            {
                "qr_code_url": "00020126580014br.gov.bcb.pix0136dc4a27db-2fe1-474d-aa02-88d6fffb8d0d5204000053039865802BR5921NeymarSportEMarketing6008saopaulo62070503***63040EB2",
                "digitable_line": "32990001454000000000623007797907697530000500000",
                "bank_slip_key": "8a00a520-7d49-4f51-9293-9ea26e241338",
                "principal_amortization_amount": 164.37001228,
                "installment_key": "3d4b5f21-c0a3-4075-bac2-9086cd90b77e",
                "due_date": "2024-09-17",
                "qr_code_key": "4d47528a-167d-41aa-b9da-246d2030af75",
                "total_amount": 216.97,
                "pre_fixed_amount": 52.59998772
            }
        ]
    }
}

```

## Definições

### Objeto Request Body
| Campo                           | Tipo   | Descrição                                                                                                                                                                                                        | Máx. Caract. | 
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **key** *                  | object | DEBT-KEY da operação de crédito da referida parcela.                                                                                                                                     | -            | 
| **data** * | object | Dados do webhook.                                                                                | -            |
| **webhook_type** *                 | object | Tipo do webhook enviado. | -            |

### Objeto data
| Campo                           | Tipo   | Descrição                                                                                                                                                                                                        | Máx. Caract. | 
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **status** *                  | object | Status da parcela                                                                                                                                     | -            | 
| **installment** * | object | Dados da parcela                                                                                | -            |
| **is_finished** *                 | booleano | Campo booleano indicando se existem novos status para a parcela ou se já esta finalizada. | -            |

### Objeto installment
| Campo                           | Tipo   | Descrição                                                                                                                                                                                                        | Máx. Caract. | 
|---------------------------------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------|
| **events** *                  | object | Status da parcela                                                                                                                                     | -            | 
| **paid_at** * | object | Dados da parcela                                                                                | -            |
| **due_date** *                 | booleano | Campo booleano indicando se existem novos status para a parcela ou se já esta finalizada. | -            |
| **workdays** *                 | booleano | Campo booleano indicando se existem novos status para a parcela ou se já esta finalizada. | -            |
| **created_at** *                 | booleano | Campo booleano indicando se existem novos status para a parcela ou se já esta finalizada. | -            |
| **tax_amount** *                 | booleano | Campo booleano indicando se existem novos status para a parcela ou se já esta finalizada. | -            |
| **updated_at** *                 | booleano | Campo booleano indicando se existem novos status para a parcela ou se já esta finalizada. | -            |